kcode-pi 0.1.34 → 0.1.38

package/docs/USER_GUIDE.md

@@ -8,8 +8,8 @@
 
 - Node.js `>=22.19.0`
 - npm
-- Windows 推荐使用 Windows Terminal
-- 不需要安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有业务项目或外部脚本明确依赖 Python 时才需要另行安装。
+- Windows 环境使用 Windows Terminal
+- 无需安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有业务项目或外部脚本明确依赖 Python 时才另行安装。
 
 全局安装：
 
@@ -25,7 +25,7 @@ kcode
 
 ## 初始化业务项目
 
-先在终端进入你的实际业务项目根目录，不是 KCode 源码目录。
+在终端进入实际业务项目根目录，不是 KCode 源码目录。
 
 初始化项目级配置：
 
@@ -73,7 +73,7 @@ kcode version
 kcode start
 ```
 
-`kcode start` 会先确保 `.pi/settings.json` 已登记当前安装的 KCode package，然后启动随包 Pi CLI。
+`kcode start` 会确保 `.pi/settings.json` 已登记当前安装的 KCode package，然后启动随包 Pi CLI。
 
 `start` 后面的参数会原样透传给 Pi CLI：
 
@@ -83,7 +83,7 @@ kcode start --provider openai --model gpt-4o
 
 ## 配置模型
 
-首次启动 Pi 时，如果看到：
+首次启动 Pi 时出现以下信息：
 
 ```text
 Warning: No models available.
@@ -107,7 +107,7 @@ DeepSeek
 Gemini
 ```
 
-也可以在 PowerShell 中设置环境变量后再启动：
+支持在 PowerShell 中设置环境变量后再启动：
 
 ```powershell
 $env:OPENAI_API_KEY="sk-..."
@@ -124,7 +124,7 @@ KCode 在 Pi 内注册的 `/kd-*` 命令见 [命令参考](COMMAND_REFERENCE.md#
 
 ## 自定义模型供应商
 
-如果你的模型服务是企业网关、代理服务、Ollama、LM Studio、vLLM，或其他 OpenAI-compatible endpoint，不需要改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：
+模型服务为企业网关、代理服务、Ollama、LM Studio、vLLM 或其他 OpenAI-compatible endpoint 时，无需修改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：
 
 ```powershell
 notepad $env:USERPROFILE\.pi\agent\models.json
@@ -171,7 +171,7 @@ $env:CORP_AI_API_KEY="sk-..."
 kcode start
 ```
 
-也可以直接指定：
+支持直接指定：
 
 ```powershell
 kcode start --provider corp-ai --model corp-coder
@@ -199,11 +199,11 @@ npm install -g kcode-pi@latest
 kcode version
 ```
 
-升级后建议在业务项目根目录执行：
+升级后在业务项目根目录执行：
 
 ```powershell
 kcode init
 kcode doctor --deep
 ```
 
-如果升级失败或仍加载旧版本，见 [故障排查](TROUBLESHOOTING.md)。
+升级失败或仍加载旧版本时，按 [故障排查](TROUBLESHOOTING.md) 处理。

package/extensions/kingdee-harness.ts

@@ -11,8 +11,10 @@ import {
 	ensurePhaseArtifact,
 	finishActiveRun,
 	listRuns,
+	openBlockingQuestions,
 	readActiveRun,
 	refreshGate,
+	reviseFact,
 	switchActiveRun,
 	updateProductProfile,
 	updatePhaseArtifact,
@@ -22,11 +24,13 @@ import type { KdRisk } from "../src/harness/types.ts";
 import { readArtifact } from "../src/harness/artifacts.ts";
 import { flagshipWriteBlockReason, isSourceLikePath, planWriteBlockReason } from "../src/harness/path-policy.ts";
 import { sdkSignatureProductionWriteBlockReason } from "../src/harness/sdk-policy.ts";
+import { dataSourceProductionWriteBlockReason } from "../src/harness/data-source-policy.ts";
 import { tddProductionWriteBlockReason } from "../src/harness/tdd-policy.ts";
 import { windowsPathHint } from "../src/platform/path.ts";
 import { repairPromptForRun, workflowPromptForRun } from "../src/harness/prompt.ts";
 import { recordVerifyResult, type VerifyResultOutcome } from "../src/harness/repair.ts";
 import { isSubagentChild, subagentRoleFromEnv, subagentToolCallBlockReason } from "../src/harness/delegation.ts";
+import { questionAskBlockReason } from "../src/harness/question-memory.ts";
 
 function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
@@ -137,14 +141,15 @@ function codeWriteBlockReason(cwd: string, path: string | undefined): string | u
 
 	const run = readActiveRun(cwd);
 	if (!run) {
-		return "KCode 工作流未启动，不能直接写产品代码。下一步：先用自然语言说明需求让 KCode 自动进入 discuss，或手动运行 /kd-start <需求> 创建 run；完成 discuss -> spec -> plan -> execute 后再写生产源码。";
+		return "KCode 工作流未启动，禁止直接写产品代码。执行指令：使用自然语言需求启动 discuss，或执行 /kd-start <需求> 创建 run；完成 discuss -> spec -> plan -> execute 后再写生产源码。";
 	}
 
 	if (run.phase !== "execute") {
-		return `当前 KCode 阶段是 ${run.phase}，不能写产品代码。下一步：先完成当前阶段文档和门禁，用 /kd-advance 推进到 execute；如果发现计划不完整，更新 PLAN.md，而不是直接写代码。`;
+		return `当前 KCode 阶段是 ${run.phase}，禁止写产品代码。执行指令：完成当前阶段文档和门禁，使用 /kd-advance 推进到 execute；计划不完整时更新 PLAN.md，禁止直接写代码。`;
 	}
 
 	return (
+		dataSourceProductionWriteBlockReason(cwd, run, path) ??
 		sdkSignatureProductionWriteBlockReason(cwd, run, path) ??
 		tddProductionWriteBlockReason(cwd, run, path) ??
 		planWriteBlockReason(cwd, run, path, readArtifact(cwd, run, "plan") ?? "")
@@ -154,7 +159,7 @@ function codeWriteBlockReason(cwd: string, path: string | undefined): string | u
 const kdPlanStatusTool = defineTool({
 	name: "kd_plan_status",
 	label: "KD 状态",
-	description: "查看当前金蝶 Harness run、当前阶段、必需文档和门禁状态。",
+	description: "输出当前金蝶 Harness run、当前阶段、必需文档和门禁状态。",
 	parameters: Type.Object({}),
 
 	async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
@@ -170,22 +175,24 @@ const kdQuestionTool = defineTool({
 	name: "kd_question",
 	label: "KD 问题",
 	description:
-		"创建、回答或列出金蝶 Harness 结构化问题。每次只记录一个最阻塞的短问题。",
+		"创建、回答、修订或列出金蝶 Harness 结构化问题。每次必须只记录一个最阻塞的短问题。",
 	parameters: Type.Object({
-		action: Type.Optional(Type.String({ description: "操作类型：ask、answer 或 list，默认 ask。" })),
+		action: Type.Optional(Type.String({ description: "操作类型：ask、answer、revise 或 list，默认 ask。" })),
 		id: Type.Optional(Type.String({ description: "回答问题时的问题编号，例如 Q-001。" })),
-		question: Type.Optional(Type.String({ description: "提问内容。使用一个短问题。" })),
+		question: Type.Optional(Type.String({ description: "提问内容；必须是一个短问题。" })),
 		answer: Type.Optional(Type.String({ description: "用户答案，action=answer 时使用。" })),
-		reason: Type.Optional(Type.String({ description: "说明为什么这个问题会阻塞当前阶段。" })),
-		choices: Type.Optional(Type.Array(Type.String(), { description: "可选项，最多 3 个简短选项。" })),
-		blocking: Type.Optional(Type.Boolean({ description: "是否阻塞阶段推进，默认 true。" })),
+		reason: Type.Optional(Type.String({ description: "当前阶段阻塞原因。" })),
+		factLabel: Type.Optional(Type.String({ description: "该问题要补齐的结构化事实标签，例如 目标 FormId/单据或表单标识。" })),
+		proposedFactValue: Type.Optional(Type.String({ description: "确认题中的候选事实值；用户回答是/yes 时写入 factLabel。" })),
+		choices: Type.Optional(Type.Array(Type.String(), { description: "候选答案；最多 3 个简短选项。" })),
+		blocking: Type.Optional(Type.Boolean({ description: "控制问题是否阻塞阶段推进，默认 true。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 		const run = readActiveRun(ctx.cwd);
 		if (!run) {
 			return {
-				content: [{ type: "text", text: "当前没有 active Kingdee Harness run。请先使用 /kd-start <需求> 创建。" }],
+				content: [{ type: "text", text: "当前没有 active Kingdee Harness run。使用 /kd-start <需求> 创建。" }],
 				details: { error: "no-active-run" },
 			};
 		}
@@ -197,17 +204,24 @@ const kdQuestionTool = defineTool({
 		}
 
 		if (action === "answer") {
-			if (!params.id || !params.answer) {
+			if (!params.id || !params.answer?.trim()) {
 				return {
-					content: [{ type: "text", text: "kd_question action=answer 需要同时提供 id 和 answer。" }],
+					content: [{ type: "text", text: "kd_question action=answer 必须同时提供 id 和 answer。" }],
 					details: { error: "missing-answer-params" },
 				};
 			}
+			const existingQuestion = (run.questions ?? []).find((question) => question.id === params.id);
+			if (existingQuestion?.status === "answered") {
+				return {
+					content: [{ type: "text", text: `${params.id} 已回答，禁止重复覆盖。用户明确更正事实时使用 kd_question action=revise factLabel="<事实标签>" answer="<新值>" reason="<更正原因>"。` }],
+					details: { error: "question-already-answered", question: existingQuestion },
+				};
+			}
 			const answered = answerQuestion(ctx.cwd, run, params.id, params.answer);
 			if (!answered) {
 				return {
-					content: [{ type: "text", text: `未找到问题：${params.id}` }],
-					details: { error: "question-not-found", id: params.id },
+					content: [{ type: "text", text: existingQuestion ? `未能记录 ${params.id} 的答案；答案不能为空或占位内容。` : `未找到问题：${params.id}` }],
+					details: { error: existingQuestion ? "invalid-answer" : "question-not-found", id: params.id },
 				};
 			}
 			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
@@ -218,16 +232,42 @@ const kdQuestionTool = defineTool({
 			};
 		}
 
+		if (action === "revise") {
+			if (!params.factLabel?.trim() || !params.answer?.trim()) {
+				return {
+					content: [{ type: "text", text: "kd_question action=revise 必须同时提供 factLabel 和 answer。" }],
+					details: { error: "missing-revise-params" },
+				};
+			}
+			const fact = reviseFact(ctx.cwd, run, {
+				factLabel: params.factLabel,
+				value: params.answer,
+				reason: params.reason,
+			});
+			if (!fact) {
+				return {
+					content: [{ type: "text", text: "未能修订结构化事实；factLabel 和 answer 不能为空。" }],
+					details: { error: "invalid-revision" },
+				};
+			}
+			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已修订事实 ${fact.label}：${fact.value}`]);
+			const auto = autoAdvanceTool(ctx.cwd, run);
+			return {
+				content: [{ type: "text", text: `已修订事实 ${fact.label}：${fact.value}。${auto.advanced ? auto.message : `门禁仍阻塞：${auto.message}`}` }],
+				details: { fact, gate: readActiveRun(ctx.cwd)?.gate, autoAdvance: auto },
+			};
+		}
+
 		if (action !== "ask") {
 			return {
-				content: [{ type: "text", text: `未知 kd_question action：${params.action}。请使用 ask、answer 或 list。` }],
+				content: [{ type: "text", text: `未知 kd_question action：${params.action}。有效值：ask、answer、revise、list。` }],
 				details: { error: "unknown-action", action: params.action },
 			};
 		}
 
 		if (!params.question?.trim()) {
 			return {
-				content: [{ type: "text", text: "kd_question action=ask 需要提供 question。" }],
+				content: [{ type: "text", text: "kd_question action=ask 必须提供 question。" }],
 				details: { error: "missing-question" },
 			};
 		}
@@ -240,39 +280,43 @@ const kdQuestionTool = defineTool({
 						text: [
 							batchProblem,
 							"",
-							"kd_question 一次只登记一个当前最阻塞的问题。",
-							"请先问第一个必须确认的问题，例如：",
+							"kd_question 一次必须只登记一个当前最阻塞的问题。",
+							"登记第一个必须确认的问题，例如：",
 							"kd_question action=ask question=\"采购入库单 Form ID 是否为 pur_receivebill？\" choices=[\"是\", \"不是\"]",
 							"",
-							"注意：交互模式下会弹出选择/输入对话并自动记录；非交互模式下用户在对话中回答后再用 kd_question action=answer 记录。",
+							"问题登记后保持 open；用户在下一条消息中回答，或使用 kd_question action=answer 记录。",
 						].join("\n"),
 					},
 				],
 				details: { error: "batched-question" },
 			};
 		}
+		const askBlockReason = questionAskBlockReason(run, { factLabel: params.factLabel });
+		if (askBlockReason) {
+			return {
+				content: [{ type: "text", text: askBlockReason }],
+				details: { error: "duplicate-fact-question", factLabel: params.factLabel },
+			};
+		}
 
+		const existingQuestionIds = new Set((run.questions ?? []).map((question) => question.id));
 		const question = addQuestion(ctx.cwd, run, {
 			question: params.question,
 			reason: params.reason,
+			factLabel: params.factLabel,
+			proposedFactValue: params.proposedFactValue,
 			choices: params.choices,
 			blocking: params.blocking,
 		});
-		appendQuestionEventToArtifact(ctx.cwd, run, formatQuestionArtifactLines(question));
-		const interactiveAnswer = await askQuestionInteractively(ctx, question.question, question.choices);
-		if (interactiveAnswer) {
-			const answered = answerQuestion(ctx.cwd, run, question.id, interactiveAnswer);
-			if (answered) {
-				appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
-				const auto = autoAdvanceTool(ctx.cwd, run);
-				return {
-					content: [{ type: "text", text: `用户已回答 ${answered.id}：${answered.answer}。${auto.advanced ? auto.message : `门禁仍阻塞：${auto.message}`}` }],
-					details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, answered: true, autoAdvance: auto },
-				};
-			}
+		if (existingQuestionIds.has(question.id)) {
+			return {
+				content: [{ type: "text", text: `${question.id} 已是 open 问题，禁止重复登记。等待用户回答，或使用 kd_question action=answer id=${question.id} answer=<答案> 记录。` }],
+				details: { question, gate: readActiveRun(ctx.cwd)?.gate, duplicate: true },
+			};
 		}
+		appendQuestionEventToArtifact(ctx.cwd, run, formatQuestionArtifactLines(question));
 
-		const text = `${formatQuestionCard(question)}\n\n未获得交互式答案；在用户回答前，该问题会保持 open。`;
+		const text = `${formatQuestionCard(question)}\n\n问题已登记为 open。等待用户在下一条消息中回答，或执行 kd_question action=answer id=${question.id} answer=<答案>。`;
 		return { content: [{ type: "text", text }], details: { question, gate: readActiveRun(ctx.cwd)?.gate, answered: false } };
 	},
 });
@@ -281,7 +325,7 @@ function createKdVerifyResultTool(pi: ExtensionAPI) {
 	return defineTool({
 		name: "kd_verify_result",
 		label: "KD 验证结果",
-		description: "记录当前 verify 命令结果。失败时自动写失败证据并回到 execute 修复；成功时记录通过证据并尝试推进。",
+		description: "记录当前 verify 命令结果。失败时自动写失败证据并回到 execute 修复；成功时记录通过证据并推进门禁。",
 		parameters: Type.Object({
 			command: Type.String({ description: "实际执行的验证命令。" }),
 			exitCode: Type.Number({ description: "验证命令退出码。" }),
@@ -294,7 +338,7 @@ function createKdVerifyResultTool(pi: ExtensionAPI) {
 			const run = readActiveRun(ctx.cwd);
 			if (!run) {
 				return {
-					content: [{ type: "text", text: "当前没有 active Kingdee Harness run。请先使用 /kd-start <需求> 创建。" }],
+					content: [{ type: "text", text: "当前没有 active Kingdee Harness run。使用 /kd-start <需求> 创建。" }],
 					details: { error: "no-active-run" },
 				};
 			}
@@ -326,7 +370,7 @@ export default function (pi: ExtensionAPI) {
 			[
 				`发现未完成 KCode run：${run.goal ?? run.id}`,
 				`阶段：${run.phase}，产品：${run.profile?.product ?? run.product ?? "unknown"}`,
-				"输入 /kd-resume 可接续；输入 /kd-runs 查看其他需求或需求组。",
+				"执行 /kd-resume 接续；执行 /kd-runs 输出其他需求或需求组。",
 			].join("\n"),
 			"info",
 		);
@@ -342,13 +386,27 @@ export default function (pi: ExtensionAPI) {
 			if (ctx.hasUI) {
 				ctx.ui.notify(`已启动 Kingdee Harness run：${run.id}（${run.profile?.product}/${run.profile?.techStack}）`, "info");
 				if (run.profile?.product === "unknown") {
-					ctx.ui.notify("产品画像未识别。下一步先执行 /kd-product <flagship|xinghan|cangqiong|enterprise>。", "warning");
+					ctx.ui.notify("产品画像未识别。执行指令：执行 /kd-product <flagship|xinghan|cangqiong|enterprise>。", "warning");
 				}
 			}
 		}
 
 		if (!run) return { action: "continue" };
 
+		const openQuestions = openBlockingQuestions(run);
+		if (openQuestions.length === 1 && shouldAutoRecordQuestionAnswer(event.text)) {
+			const answered = answerQuestion(ctx.cwd, run, openQuestions[0].id, event.text);
+			const current = readActiveRun(ctx.cwd) ?? run;
+			if (answered) {
+				appendQuestionEventToArtifact(ctx.cwd, current, [`- 已回答 ${answered.id}：${answered.answer}`]);
+				if (ctx.hasUI) ctx.ui.notify(`已记录 ${answered.id} 的答案`, "info");
+				return {
+					action: "transform",
+					text: workflowPromptForRun(ctx.cwd, current, `用户已回答 ${answered.id}：${answered.answer}`),
+				};
+			}
+		}
+
 		return {
 			action: "transform",
 			text: workflowPromptForRun(ctx.cwd, run, event.text),
@@ -360,7 +418,7 @@ export default function (pi: ExtensionAPI) {
 		const path = typeof input.path === "string" ? input.path : undefined;
 		const hint = path ? windowsPathHint(path) : undefined;
 		if (hint && ["read", "write", "edit"].includes(event.toolName)) {
-			const reason = `当前是 Windows 工作区，路径 ${path} 不是本项目使用的路径形式。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}。`;
+			const reason = `当前是 Windows 工作区，路径 ${path} 不是本项目使用的路径形式。执行指令：改用项目相对路径；必须使用绝对路径时，使用 Windows 路径 ${hint}。`;
 			if (ctx.hasUI) ctx.ui.notify(reason, "warning");
 			return { block: true, reason };
 		}
@@ -369,7 +427,7 @@ export default function (pi: ExtensionAPI) {
 		if (event.toolName === "read" && path) {
 			const ext = path.toLowerCase().split(".").pop();
 			if (ext === "pdf" || ext === "docx" || ext === "doc" || ext === "xlsx" || ext === "xls" || ext === "csv") {
-				const reason = `read 工具无法解析 .${ext} 二进制格式。下一步：改用 kd_doc_read 工具读取此文件，参数 path="${path}"。`;
+				const reason = `read 工具无法解析 .${ext} 二进制格式。执行指令：改用 kd_doc_read 工具读取此文件，参数 path="${path}"。`;
 				if (ctx.hasUI) ctx.ui.notify(reason, "info");
 				return { block: true, reason };
 			}
@@ -379,6 +437,7 @@ export default function (pi: ExtensionAPI) {
 		if (subagentRole) {
 			const run = readActiveRun(ctx.cwd);
 			const sourceWriteBlock =
+				dataSourceProductionWriteBlockReason(ctx.cwd, run, path) ??
 				sdkSignatureProductionWriteBlockReason(ctx.cwd, run, path) ??
 				tddProductionWriteBlockReason(ctx.cwd, run, path) ??
 				planWriteBlockReason(ctx.cwd, run, path, run ? (readArtifact(ctx.cwd, run, "plan") ?? "") : "") ??
@@ -408,14 +467,14 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-status", {
-		description: "查看当前 Kingdee Harness run 和门禁状态",
+		description: "输出当前 Kingdee Harness run 和门禁状态",
 		handler: async (_args, ctx) => {
 			ctx.ui.notify(formatStatus(ctx.cwd, readActiveRun(ctx.cwd)), "info");
 		},
 	});
 
 	pi.registerCommand("kd-runs", {
-		description: "列出当前项目的 Kingdee Harness run",
+		description: "输出当前项目的 Kingdee Harness run 列表",
 		handler: async (_args, ctx) => {
 			const active = readActiveRun(ctx.cwd);
 			ctx.ui.notify(formatRuns(listRuns(ctx.cwd), active?.id), "info");
@@ -423,11 +482,11 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-gate", {
-		description: "刷新并查看当前 Kingdee Harness 门禁",
+		description: "刷新并输出当前 Kingdee Harness 门禁",
 		handler: async (_args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 			const refreshed = refreshGate(ctx.cwd, run);
@@ -436,7 +495,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-start", {
-		description: "启动一个 Kingdee Harness run：/kd-start [--product 产品] [--version 版本] <需求或需求组>",
+		description: "创建 Kingdee Harness run：/kd-start [--product 产品] [--version 版本] <需求或需求组>",
 		handler: async (args, ctx) => {
 			const parsed = parseStartArgs(args);
 			const goal = parsed.goal;
@@ -448,7 +507,7 @@ export default function (pi: ExtensionAPI) {
 			const run = createActiveRun(ctx.cwd, goal, parsed.product, parsed.version);
 			ctx.ui.notify(`已启动 Kingdee Harness run：${run.id}（${run.profile?.product}/${run.profile?.techStack}）`, "info");
 			if (run.profile?.product === "unknown") {
-				ctx.ui.notify("产品画像未识别。下一步先执行 /kd-product <flagship|xinghan|cangqiong|enterprise>。", "warning");
+				ctx.ui.notify("产品画像未识别。执行指令：执行 /kd-product <flagship|xinghan|cangqiong|enterprise>。", "warning");
 			}
 			sendWorkflowPrompt(pi, ctx, run, `继续 KCode Harness run ${run.id}：${goal}`);
 		},
@@ -459,7 +518,7 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求> 或 /kd-runs。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求> 或 /kd-runs。", "error");
 				return;
 			}
 
@@ -475,7 +534,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-switch", {
-		description: "切换当前 active Kingdee Harness run：/kd-switch <run-id>",
+		description: "设置当前 active Kingdee Harness run：/kd-switch <run-id>",
 		handler: async (args, ctx) => {
 			const id = args.trim();
 			if (!id) {
@@ -485,7 +544,7 @@ export default function (pi: ExtensionAPI) {
 
 			const run = switchActiveRun(ctx.cwd, id);
 			if (!run) {
-				ctx.ui.notify(`未找到 Kingdee Harness run：${id}。请用 /kd-runs 查看列表。`, "error");
+				ctx.ui.notify(`未找到 Kingdee Harness run：${id}。使用 /kd-runs 查看列表。`, "error");
 				return;
 			}
 
@@ -498,12 +557,12 @@ export default function (pi: ExtensionAPI) {
 		handler: async (_args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 
 			const finished = finishActiveRun(ctx.cwd, run);
-			ctx.ui.notify(`已完成 Kingdee Harness run：${finished.id}。下一个需求或需求组请使用 /kd-start <需求>。`, "info");
+			ctx.ui.notify(`已完成 Kingdee Harness run：${finished.id}。下一个需求或需求组使用 /kd-start <需求>。`, "info");
 		},
 	});
 
@@ -512,7 +571,7 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 
@@ -533,7 +592,7 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 
@@ -554,7 +613,7 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 
@@ -562,7 +621,7 @@ export default function (pi: ExtensionAPI) {
 			let requested: KdPhase | undefined;
 			if (requestedText) {
 				if (!isKdPhase(requestedText)) {
-					ctx.ui.notify(`未知阶段 "${requestedText}"。可用阶段：${PHASE_ORDER.join(", ")}`, "error");
+					ctx.ui.notify(`未知阶段 "${requestedText}"。有效阶段：${PHASE_ORDER.join(", ")}`, "error");
 					return;
 				}
 				requested = requestedText;
@@ -574,11 +633,11 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-artifact", {
-		description: "创建阶段文档，或显式覆盖阶段文档：/kd-artifact [阶段] [内容] [--replace]",
+		description: "创建阶段文档，或使用 --replace 显式覆盖阶段文档：/kd-artifact [阶段] [内容] [--replace]",
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 
@@ -589,7 +648,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (parsed.content && readArtifact(ctx.cwd, run, parsed.phase) !== undefined && !parsed.replace) {
-				ctx.ui.notify(`拒绝覆盖 ${parsed.phase} 阶段文档。若确认要整体替换，请追加 --replace；追加内容应让 KCode 更新具体章节。`, "warning");
+				ctx.ui.notify(`拒绝覆盖 ${parsed.phase} 阶段文档。确认整体替换时追加 --replace；追加内容必须让 KCode 更新具体章节。`, "warning");
 				return;
 			}
 
@@ -606,7 +665,7 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 			const [id, ...answerParts] = args.trim().split(/\s+/);
@@ -615,9 +674,14 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify("用法：/kd-answer Q-001 <答案>", "error");
 				return;
 			}
+			const existingQuestion = (run.questions ?? []).find((question) => question.id === id);
+			if (existingQuestion?.status === "answered") {
+				ctx.ui.notify(`${id} 已回答，禁止重复覆盖；用户更正事实时使用 kd_question action=revise。`, "warning");
+				return;
+			}
 			const answered = answerQuestion(ctx.cwd, run, id, answer);
 			if (!answered) {
-				ctx.ui.notify(`未找到问题：${id}`, "error");
+				ctx.ui.notify(existingQuestion ? `未能记录 ${id} 的答案；答案不能为空、占位内容或单独确认/否定。` : `未找到问题：${id}`, "error");
 				return;
 			}
 			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
@@ -631,7 +695,7 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
-				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				ctx.ui.notify("当前没有 active Kingdee Harness run。使用 /kd-start <需求>。", "error");
 				return;
 			}
 			const [exitCodeText, ...commandParts] = args.trim().split(/\s+/);
@@ -665,7 +729,7 @@ function formatQuestions(run: NonNullable<ReturnType<typeof readActiveRun>>): st
 }
 
 function formatRuns(runs: NonNullable<ReturnType<typeof readActiveRun>>[], activeId?: string): string {
-	if (runs.length === 0) return "当前项目没有 Kingdee Harness run。请使用 /kd-start <需求> 创建。";
+	if (runs.length === 0) return "当前项目没有 Kingdee Harness run。使用 /kd-start <需求> 创建。";
 	return runs
 		.map((run) =>
 			[
@@ -684,55 +748,46 @@ function formatQuestionCard(question: NonNullable<NonNullable<ReturnType<typeof
 		`阶段：${question.phase}`,
 		`问题：${question.question}`,
 		question.reason ? `原因：${question.reason}` : undefined,
+		question.factLabel ? `事实标签：${question.factLabel}` : undefined,
+		question.proposedFactValue ? `候选事实值：${question.proposedFactValue}` : undefined,
 		question.choices?.length ? `选项：${question.choices.join(" | ")}` : undefined,
 		question.answer ? `答案：${question.answer}` : undefined,
 		question.status === "open"
-			? `如果有弹窗，请直接回答；否则请在对话中回复，并用 kd_question action=answer id=${question.id} answer=<答案> 记录。`
+			? `回答方式：用户在下一条消息中回答，或使用 kd_question action=answer id=${question.id} answer=<答案> 记录。`
 			: undefined,
 	];
 	return lines.filter(Boolean).join("\n");
 }
 
-async function askQuestionInteractively(
-	ctx: ExtensionContext,
-	question: string,
-	choices: string[] | undefined,
-): Promise<string | undefined> {
-	if (!ctx.hasUI) return undefined;
-
-	const normalizedChoices = choices?.map((choice) => choice.trim()).filter(Boolean) ?? [];
-	try {
-		if (normalizedChoices.length === 0) {
-			return (await ctx.ui.input(question, "请输入答案"))?.trim() || undefined;
-		}
-
-		const customChoice = "其他，自定义输入";
-		const selected = await ctx.ui.select(question, [...normalizedChoices, customChoice]);
-		if (!selected) return undefined;
-		if (selected !== customChoice) return selected;
-		return (await ctx.ui.input(question, "请输入答案"))?.trim() || undefined;
-	} catch {
-		return undefined;
-	}
-}
-
 function questionBatchProblem(question: string, choices?: string[]): string | undefined {
 	const text = question.trim();
 	const numberedItems = text.split(/\r?\n/).filter((line) => /^\s*(\d+[\.\)、)]|[-*]\s+)/.test(line)).length;
 	if (numberedItems >= 2) return "kd_question 拒绝了批量清单式问题。";
 	if ((text.match(/[?？]/g) ?? []).length > 1) return "kd_question 拒绝了一次包含多个问题的提问。";
-	if (text.length > 220) return "kd_question 拒绝了过长问题。请只问当前最小的阻塞问题。";
-	if ((choices?.length ?? 0) > 3) return "kd_question 拒绝了过多选项。最多提供 3 个简短选项。";
+	if (text.length > 220) return "kd_question 拒绝了过长问题。问题必须聚焦当前最小阻塞项。";
+	if ((choices?.length ?? 0) > 3) return "kd_question 拒绝了过多选项。最多 3 个简短选项。";
 	if (choices?.some((choice) => choice.length > 40 || /[\r\n?？]/.test(choice))) {
 		return "kd_question 拒绝了复杂选项。选项必须是短标签，不能嵌套问题。";
 	}
 	return undefined;
 }
 
+function shouldAutoRecordQuestionAnswer(text: string): boolean {
+	const trimmed = text.trim();
+	if (!trimmed || trimmed.startsWith("/")) return false;
+	if (trimmed.length > 300) return false;
+	if (/[?？]/.test(trimmed)) return false;
+	if (/^(先|暂停|等等|不用|不要|继续|开始|实现|修改|修复|提交|push|发布)\b/i.test(trimmed)) return false;
+	if (/^(先|暂停|等等|不用|不要|继续|开始|实现|修改|修复|提交|发布)/.test(trimmed)) return false;
+	return true;
+}
+
 function formatQuestionArtifactLines(question: NonNullable<NonNullable<ReturnType<typeof readActiveRun>>["questions"]>[number]): string[] {
 	return [
 		`- ${question.id} [${question.blocking ? "blocking" : "non-blocking"}] ${question.question}`,
 		question.reason ? `  - 原因：${question.reason}` : undefined,
+		question.factLabel ? `  - 事实标签：${question.factLabel}` : undefined,
+		question.proposedFactValue ? `  - 候选事实值：${question.proposedFactValue}` : undefined,
 		question.choices?.length ? `  - 选项：${question.choices.join(" | ")}` : undefined,
 		"  - 状态：open",
 	].filter(Boolean) as string[];

package/extensions/kingdee-header.ts

@@ -186,7 +186,7 @@ export default function (pi: ExtensionAPI) {
 		description: "恢复 KCode 金蝶标题栏",
 		handler: async (_args, ctx) => {
 			if (ctx.mode !== "tui") return;
-			ctx.ui.notify("请重启会话或重新加载扩展以恢复 KCode 标题栏。", "info");
+			ctx.ui.notify("重启会话或重新加载扩展以恢复 KCode 标题栏。", "info");
 		},
 	});
 

package/extensions/kingdee-subagents.ts

@@ -246,7 +246,7 @@ async function runChainedAgents(
 
 function formatModeResult(mode: "single" | "parallel" | "chain", results: ChildAgentResult[], limit: number): string {
 	const succeeded = results.filter((result) => result.exitCode === 0).length;
-	const header = `子 agent ${mode} 完成：${succeeded}/${results.length} succeeded`;
+	const header = `子 agent ${mode} 完成：${succeeded}/${results.length} 成功`;
 	const sections = results.map((result, index) => {
 		const output = truncateOutput(result.output || result.stderr || "(子 agent 无输出)", limit);
 		return [