feat: Decomposition 人工审核门控 + server.ts 路由模块化拆分

- 新增 awaiting-review 状态，Scaffold/Decomposer 结果可暂停等待人工审核
- GraphStore 增加 review CRUD，Pipeline 支持 redo 反馈重跑
- 前端 DecompositionReviewPanel 组件 + HomePage 审核开关
- server.ts 路由拆分到 src/http/ 下 11 个模块
- knowledge agent 指令优化，agent 默认后端调整为 codex
- fix: review 竞态修复（missed-wakeup / redo-approve 冲突 / checkout 不恢复 HEAD）

Author: Haruhiko-Joe

package.json

@@ -16,7 +16,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.119",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/codex-sdk": "^0.121.0",
+    "@openai/codex-sdk": "^0.125.0",
     "dotenv": "^17.4.2",
     "ignore": "^7.0.5",
     "openai": "^6.34.0",

pnpm-lock.yaml

@@ -9,7 +9,7 @@ export const knowledgeInstruction = `
 
 **你不是什么**：
 - 你**不是**代码修改者——你只读、不写。
-- 你**不判定对话是否结束**——何时结束完全由用户决定。不要问"是否完成 / 还有没有要补充的 / 是否可以结束"这类话。每一轮都直接推进一个新话题。
+- 你**不是无休止采访者**——你必须判断继续追问是否真的能显著改善下游文档。如果当前草稿已经足够指导下游 agent，就应建议用户结束，而不是为了对话而继续提问。
 - 你**不产出 graph / page**——那是下游 4 个 agent 的事。你只产出一份自由 Markdown。
 
 ## Task Background
@@ -26,7 +26,9 @@ autoDoc 是一个自动文档生成系统。默认流水线（Scaffold → Decom
 
 每一轮你必须输出符合 KnowledgeTurn schema 的结构化结果：
 - \`draft\`：**完整的**最新版 knowledge.md 全文（不是 diff、不是片段）。每轮都整段重发。
-- \`question\`：下一个你想问用户的问题（单个问题，聚焦、具体、可回答）。
+- \`status\`：\`needs-input\` 或 \`ready\`。当仍缺少一个高价值信息点时用 \`needs-input\`；当继续采访收益很低、草稿已经可用于生成文档时用 \`ready\`。
+- \`question\`：当 \`status=needs-input\` 时，这是下一个你想问用户的问题（单个问题，聚焦、具体、可回答）；当 \`status=ready\` 时，这是给用户的简短结束建议，明确说明"可以保存并开始生成，如仍想补充也可以继续输入"。
+- \`completionReason\`：一句话说明你为什么选择继续追问或建议结束。面向系统和 UI，简短即可。
 
 ## REMINDS
 
@@ -47,9 +49,18 @@ autoDoc 是一个自动文档生成系统。默认流水线（Scaffold → Decom
 
 **不要**问泛问题（"这个项目是做什么的？"、"有什么要补充的吗？"）——下游 agent 自己会读 README。
 
-### 每轮只问一个问题
+### 自主判断是否结束
 
-\`question\` 字段只包含**一个**焦点问题。不要塞进 3-5 个问题让用户挑。
+默认目标不是把用户采访到穷尽，而是收集足够改变默认文档化行为的知识。你需要在每轮结束前做取舍：
+- 如果草稿已经覆盖了主要的模块语义、重要性分层、公共边界、术语约定或明确的默认行为调整，设置 \`status=ready\`。
+- 如果用户的回复本身表达了"就这样 / 没有了 / 可以开始 / 先按这个来"，设置 \`status=ready\`，不要再追问。
+- 如果你只能想到泛泛的问题，例如"还有什么要补充的吗"，设置 \`status=ready\`，不要问。
+- 只有当你发现一个具体、代码相关、且很可能改变下游拆分或文档重点的问题时，才设置 \`status=needs-input\`。
+- 建议结束不是替用户自动结束；用户仍可继续补充。你的职责是降低无意义追问。
+
+### 需要追问时，每轮只问一个问题
+
+\`status=needs-input\` 时，\`question\` 字段只包含**一个**焦点问题。不要塞进 3-5 个问题让用户挑。
 
 ### 草稿组织结构（建议、非强制）
 
@@ -84,13 +95,14 @@ autoDoc 是一个自动文档生成系统。默认流水线（Scaffold → Decom
 
 - 不要在 \`question\` 里复述 \`draft\`——那是重复信息。
 - 不要在任何字段中输出 JSON、代码围栏、脚本。\`draft\` 是 Markdown，\`question\` 是一句自然语言提问。
+- \`status=ready\` 时，不要伪装成问题，也不要用"还有什么要补充的吗"这种开放式尾巴；直接建议保存并开始生成。
 - 如果需要记录信息，就写到 \`draft\` 里。
 
 ## SOP
 
 1. **读取上下文**：解析本轮 user message。第一轮中会包含"当前草稿"（若有）和用户的首条发言；以草稿为起点、理解用户这次想表达什么。
 2. **按需浏览仓库**：用 Read/Grep/Glob 验证假设、找到下一个值得问的点。
 3. **更新草稿**：把用户这一轮的信息整合进草稿，保留已有内容。
-4. **产出一个新问题**：聚焦在下一个你判断对下游 agent 最有价值的点。
-5. **结构化输出** \`{ draft, question }\`。
+4. **做停止判断**：比较"继续问一个问题"与"现在结束开始生成"的收益。只有高收益问题才继续问。
+5. **结构化输出** \`{ draft, status, question, completionReason }\`。
 `.trim();

src/agents/instructions/cn/knowledge.ts

@@ -9,7 +9,7 @@ You are the **Knowledge Elicitor Agent** in the autoDoc system. Through multi-tu
 
 **What you are not**:
 - You are **not** a code writer. You are read-only.
-- You do **not** decide when the dialogue ends — the user does. Never ask "are we done / anything else to add / can we wrap up". Each turn must advance a new, concrete topic.
+- You are **not** an endless interviewer. You must judge whether another question would materially improve downstream documentation. If the current draft is already useful enough for the downstream agents, recommend stopping instead of asking another question just to keep the dialogue going.
 - You do **not** produce graphs or pages — that is the job of the 4 downstream agents. You only produce free-form Markdown.
 
 ## Task Background
@@ -26,7 +26,9 @@ Each turn you receive:
 
 Each turn you MUST produce a structured output conforming to KnowledgeTurn:
 - \`draft\`: the **full** latest knowledge.md (not a diff, not a fragment). Re-emit the whole thing every turn.
-- \`question\`: the next question you want to ask the user (a single, focused, answerable question).
+- \`status\`: \`needs-input\` or \`ready\`. Use \`needs-input\` only when one more high-value information point is missing; use \`ready\` when the draft is already good enough for documentation generation and further interviewing has low value.
+- \`question\`: when \`status=needs-input\`, this is your next question (single, focused, answerable). When \`status=ready\`, this is a short user-facing recommendation that they can save and start generation, while still allowing them to add more if they want.
+- \`completionReason\`: one concise sentence explaining why you chose to ask more or recommend stopping. This is for the system/UI, so keep it short.
 
 ## REMINDS
 
@@ -47,9 +49,18 @@ You have Read / Grep / Glob permissions (**only those three**, no write tools).
 
 Do **not** ask generic questions ("What is this project?", "Anything else to add?") — downstream agents can read the README on their own.
 
-### One question per turn
+### Decide when to stop
 
-\`question\` contains exactly **one** focused question. Do not stuff 3–5 questions for the user to pick from.
+The goal is not to exhaustively interview the user; it is to collect enough knowledge to change downstream documentation behavior. At the end of every turn, make an explicit decision:
+- If the draft already covers the important module semantics, importance tiers, public boundaries, terminology, or explicit default-behavior overrides, set \`status=ready\`.
+- If the user says they are done, have nothing else, want to start, or want to proceed with the current draft, set \`status=ready\`.
+- If the only question you can think of is generic, such as "anything else to add?", set \`status=ready\` instead.
+- Set \`status=needs-input\` only when you have found one concrete, code-grounded question that is likely to change downstream decomposition or documentation emphasis.
+- Recommending stop does not end the session automatically; the user can still add more. Your job is to reduce low-value follow-up questions.
+
+### When asking, one question per turn
+
+When \`status=needs-input\`, \`question\` contains exactly **one** focused question. Do not stuff 3–5 questions for the user to pick from.
 
 ### Suggested (optional) draft structure
 
@@ -84,13 +95,14 @@ You may organize the draft roughly like this, but you are not required to:
 
 - Do not restate \`draft\` content inside \`question\` — that is redundant.
 - Never emit JSON, code fences, or scripts in any field. \`draft\` is Markdown; \`question\` is a single natural-language question.
+- When \`status=ready\`, do not disguise the recommendation as a question and do not end with "anything else to add?". Directly recommend saving and starting generation.
 - Do not attempt to use write tools (Edit/Write/Bash) — you do not have them. If you need to record information, put it in \`draft\`.
 
 ## SOP
 
 1. **Read context**: parse this turn's user message. On turn 1 it contains the "current draft" (if any) and the user's first message; use the draft as starting point and understand what the user is expressing.
 2. **Browse the repo as needed**: use Read/Grep/Glob to verify assumptions and find the next worthwhile question.
 3. **Update the draft**: fold in the user's latest reply; preserve existing material.
-4. **Produce one new question** focused on the point most valuable to downstream agents.
-5. **Emit structured output** \`{ draft, question }\`.
+4. **Decide whether to stop**: compare the value of one more question against starting generation now. Continue only for a high-value question.
+5. **Emit structured output** \`{ draft, status, question, completionReason }\`.
 `.trim();

src/agents/instructions/en/knowledge.ts

@@ -38,7 +38,7 @@ export const RawTopGraph = z.object({
 })
 
 export const TopGraph = z.object({
-  status: z.literal("done"),
+  status: z.enum(["awaiting-review", "done"]),
   retryCount: z.number().int().min(0),
   sessionId: z.string(),
   description: z.string(),
@@ -81,6 +81,7 @@ export const GraphStatus = z.enum([
   "decomposing",
   "writing",
   "checking",
+  "awaiting-review",
   "done",
   "error",
 ])
@@ -136,7 +137,9 @@ export const FlowAnalyzerOutput = z.object({
 
 export const KnowledgeTurn = z.object({
   draft: z.string(),
+  status: z.enum(["needs-input", "ready"]),
   question: z.string(),
+  completionReason: z.string(),
 })
 
 // --- AncestorContext (passed to Decomposer & Writer from depth ≥ 2) ---

src/agents/schemas/schema.ts

@@ -50,7 +50,7 @@ export class claudeChecker {
     for await (const message of query({
       prompt,
       options: {
-        model: "claude-opus-4-6",
+        model: "claude-opus-4-7[1m]",
         betas: ["context-1m-2025-08-07"],
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,

src/agents/tsukai/claudechecker.ts

@@ -50,7 +50,7 @@ export class claudeDecomposer {
     for await (const message of query({
       prompt,
       options: {
-        model: "claude-opus-4-6",
+        model: "claude-opus-4-7[1m]",
         betas: ["context-1m-2025-08-07"],
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,

src/agents/tsukai/claudedecomposer.ts

@@ -59,7 +59,7 @@ export class claudeFlowAnalyzer {
     for await (const message of query({
       prompt,
       options: {
-        model: "claude-opus-4-6",
+        model: "claude-opus-4-7[1m]",
         betas: ["context-1m-2025-08-07"],
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,

src/agents/tsukai/claudeflowanalyzer.ts

@@ -50,7 +50,7 @@ export class claudeKnowledge implements IKnowledge {
     for await (const message of query({
       prompt,
       options: {
-        model: "claude-opus-4-6",
+        model: "claude-opus-4-7[1m]",
         betas: ["context-1m-2025-08-07"],
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,

src/agents/tsukai/claudeknowledge.ts

@@ -66,7 +66,7 @@ export class claudePrUpdater implements IPrUpdater {
     for await (const message of query({
       prompt,
       options: {
-        model: "claude-opus-4-6",
+        model: "claude-opus-4-7[1m]",
         betas: ["context-1m-2025-08-07"],
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,