kcode-pi 0.1.31 → 0.1.35

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

@@ -22,6 +22,7 @@ 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";
@@ -137,14 +138,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 +156,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 +172,22 @@ const kdQuestionTool = defineTool({
 	name: "kd_question",
 	label: "KD 问题",
 	description:
-		"创建、回答或列出金蝶 Harness 结构化问题。每次只记录一个最阻塞的短问题。",
+		"创建、回答或列出金蝶 Harness 结构化问题。每次必须只记录一个最阻塞的短问题。",
 	parameters: Type.Object({
 		action: Type.Optional(Type.String({ description: "操作类型：ask、answer 或 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: "当前阶段阻塞原因。" })),
+		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" },
 			};
 		}
@@ -199,7 +201,7 @@ const kdQuestionTool = defineTool({
 		if (action === "answer") {
 			if (!params.id || !params.answer) {
 				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" },
 				};
 			}
@@ -220,14 +222,14 @@ const kdQuestionTool = defineTool({
 
 		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、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,11 +242,11 @@ const kdQuestionTool = defineTool({
 						text: [
 							batchProblem,
 							"",
-							"kd_question 一次只登记一个当前最阻塞的问题。",
-							"请先问第一个必须确认的问题，例如：",
+							"kd_question 一次必须只登记一个当前最阻塞的问题。",
+							"登记第一个必须确认的问题，例如：",
 							"kd_question action=ask question=\"采购入库单 Form ID 是否为 pur_receivebill？\" choices=[\"是\", \"不是\"]",
 							"",
-							"注意：交互模式下会弹出选择/输入对话并自动记录；非交互模式下用户在对话中回答后再用 kd_question action=answer 记录。",
+							"交互模式弹出选择/输入对话并自动记录；非交互模式必须由用户在对话中回答，再用 kd_question action=answer 记录。",
 						].join("\n"),
 					},
 				],
@@ -272,7 +274,7 @@ const kdQuestionTool = defineTool({
 			}
 		}
 
-		const text = `${formatQuestionCard(question)}\n\n未获得交互式答案；在用户回答前，该问题会保持 open。`;
+		const text = `${formatQuestionCard(question)}\n\n未记录交互式答案；该问题保持 open，直至用户回答。`;
 		return { content: [{ type: "text", text }], details: { question, gate: readActiveRun(ctx.cwd)?.gate, answered: false } };
 	},
 });
@@ -281,7 +283,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 +296,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 +328,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,7 +344,7 @@ 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");
 				}
 			}
 		}
@@ -360,15 +362,26 @@ 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 };
 		}
 
+		// Redirect read tool to kd_doc_read for office document formats
+		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}"。`;
+				if (ctx.hasUI) ctx.ui.notify(reason, "info");
+				return { block: true, reason };
+			}
+		}
+
 		const subagentRole = isSubagentChild() ? subagentRoleFromEnv() : undefined;
 		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") ?? "") : "") ??
@@ -398,14 +411,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");
@@ -413,11 +426,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);
@@ -426,7 +439,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;
@@ -438,7 +451,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}`);
 		},
@@ -449,7 +462,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;
 			}
 
@@ -465,7 +478,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) {
@@ -475,7 +488,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;
 			}
 
@@ -488,12 +501,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");
 		},
 	});
 
@@ -502,7 +515,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;
 			}
 
@@ -523,7 +536,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;
 			}
 
@@ -544,7 +557,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;
 			}
 
@@ -552,7 +565,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;
@@ -564,11 +577,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;
 			}
 
@@ -579,7 +592,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;
 			}
 
@@ -596,7 +609,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+/);
@@ -621,7 +634,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+/);
@@ -655,7 +668,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) =>
 			[
@@ -677,7 +690,7 @@ function formatQuestionCard(question: NonNullable<NonNullable<ReturnType<typeof
 		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");
@@ -693,14 +706,14 @@ async function askQuestionInteractively(
 	const normalizedChoices = choices?.map((choice) => choice.trim()).filter(Boolean) ?? [];
 	try {
 		if (normalizedChoices.length === 0) {
-			return (await ctx.ui.input(question, "请输入答案"))?.trim() || undefined;
+			return (await ctx.ui.input(question, "输入答案"))?.trim() || undefined;
 		}
 
-		const customChoice = "其他，自定义输入";
+		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;
+		return (await ctx.ui.input(question, "输入答案"))?.trim() || undefined;
 	} catch {
 		return undefined;
 	}
@@ -711,8 +724,8 @@ function questionBatchProblem(question: string, choices?: string[]): string | un
 	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 拒绝了复杂选项。选项必须是短标签，不能嵌套问题。";
 	}

package/extensions/kingdee-header.ts

@@ -43,7 +43,7 @@ function visibleWidth(str: string): number {
  * and appends SGR reset before the `>`. No padding — pi-tui only requires
  * visibleWidth <= width.
  */
-function clipLine(text: string, maxWidth: number): string {
+export function clipLine(text: string, maxWidth: number): string {
 	if (maxWidth <= 0) return "";
 	const vw = visibleWidth(text);
 	if (vw <= maxWidth) return text;
@@ -56,7 +56,7 @@ function clipLine(text: string, maxWidth: number): string {
 	while (i < text.length && visibleSoFar < targetW) {
 		// Preserve ANSI escape sequences
 		if (text[i] === "\x1b") {
-			const m = text.slice(i).match(/^(?:\[[0-9;]*[A-Za-z]|\][^\x07]*\x07|_[^\x1b]*\x1b\\)/);
+			const m = text.slice(i).match(/^\x1b(?:\[[0-9;]*[A-Za-z]|\][^\x07]*\x07|_[^\x1b]*\x1b\\)/);
 			if (m) {
 				result += m[0];
 				i += m[0].length;
@@ -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 [