kcode-pi 0.1.27 → 0.1.31

package/README.md

@@ -108,6 +108,8 @@ enterprise  金蝶企业版 / C#
 /kd-advance [阶段]
 /kd-artifact [阶段] [内容] [--replace]
 /kd-answer Q-001 <答案>
+/kd-review [审查重点]
+/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]
 ```
 
 完整说明见 [命令参考](docs/COMMAND_REFERENCE.md)。
@@ -129,6 +131,7 @@ kd_sdk_signature    从当前项目实际 SDK jar/dll 中读取类和方法签
 kd_ksql_lint        运行 KSQL/SQL lint
 kd_build            按产品画像执行或 dry-run 构建
 kd_debug            分析金蝶日志和堆栈
+kd_subagent         将调研、文档、代码、验证或交叉审查委派给隔离子 agent
 ```
 
 工具细节和使用顺序见 [Harness 工作流](docs/HARNESS_WORKFLOW.md)。

package/docs/CHANGELOG.md

@@ -6,6 +6,52 @@
 
 - 暂无。
 
+## 0.1.30 - 2026-06-07
+
+### 新增
+
+- 新增 `kd_subagent` 工具，用隔离 Pi 子进程执行调研、文档、代码、验证和交叉审查任务。
+- 新增 `/kd-review` 命令，用只读子 agent 执行交叉自查。
+- 新增 `/kd-delegate` 命令，支持按 `research/doc/code/review/verify` 角色委派任务，并可用 `--dry-run` 预览上下文包。
+- `kd_subagent` 支持单任务、只读角色并行 `tasks` 和链式 `chain` 三种模式。
+
+### 改进
+
+- 子 agent 上下文由 `src/harness/delegation.ts` 集中生成，明确写入边界、主状态机边界和禁止递归委派。
+- 工作流 prompt 增加自动委派策略：复杂调研、交叉审查和可并行拆分任务可主动调用 `kd_subagent`，但不自动推进阶段。
+- 子 agent 进程使用角色环境标记和工具白名单；child 环境不注册 `kd_subagent`，避免递归委派。
+- `research/review/verify` 为只读角色；`doc` 只能写 README、docs/ 和当前 run 阶段文档；`code` 只能在 `execute` 阶段写产品源码并继续受 PLAN/TDD/SDK 门禁约束。
+
+### 验证
+
+- `npm run smoke:harness` 覆盖委派参数解析、上下文包关键约束和写入边界预览。
+
+## 0.1.29 - 2026-06-07
+
+### 修复
+
+- 修复自动修复循环达到上限后，即使后续验证通过也会被遗留阻断问题继续卡住的问题。
+- 强化 `kd_verify_result` 输入容错，避免坏 payload 触发类似 `undefined.replace/trim` 的崩溃。
+- 限制验证结果只能在 `verify` 阶段或自动修复中的 `execute` 阶段记录，避免非验证阶段污染 `VERIFY.md` 和 evidence。
+- 收敛 `/kd-verify` 与 `kd-verify` skill 的验证结果入口，要求通过 `kd_verify_result` 进入同一修复闭环。
+
+### 验证
+
+- `npm run smoke:harness` 覆盖 repair 阻断问题关闭、坏验证 payload 容错和非法阶段拒绝。
+
+## 0.1.28 - 2026-06-07
+
+### 新增
+
+- 新增 `kd_verify_result` 工具和 `/kd-verify-result` 命令，用于记录验证命令结果。
+- 验证失败时自动写入 `evidence/verify-failure-###.md`，切回 `execute` 阶段并注入修复上下文。
+- 验证通过时写入 `evidence/verify-pass.md`，重置修复状态并继续尝试推进。
+- 自动修复循环默认最多 3 轮；达到上限后创建阻断问题，避免无限修复。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖验证失败回到 execute、三轮失败阻塞、验证通过重置修复状态。
+
 ## 0.1.27 - 2026-06-07
 
 ### 修复

package/docs/COMMAND_REFERENCE.md

@@ -255,6 +255,37 @@ discuss -> spec -> plan -> execute -> verify -> ship
 /kd-finish
 ```
 
+### /kd-review
+
+启动只读交叉自查子 agent：
+
+```text
+/kd-review [审查重点]
+```
+
+用于检查状态机漏洞、门禁绕过、证据缺口、提示词分散和测试缺口。子 agent 不修改文件，主 agent 负责采纳结论和后续修复。
+
+### /kd-delegate
+
+把局部任务委派给隔离子 agent：
+
+```text
+/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]
+```
+
+角色：
+
+```text
+research  只读调研，输出压缩结论和证据位置
+doc       写指定文档或阶段产物
+code      只在 execute 阶段修改 PLAN.md 批准文件
+review    只读交叉自查，输出 findings 和是否阻止发布
+verify    只读分析验证命令和失败证据，实际验证由主 agent 执行并用 kd_verify_result 记录
+```
+
+`--dry-run` 只预览上下文包，不启动子进程。
+复杂任务也可能由主 agent 自动调用 `kd_subagent` 委派；自动委派不会改变 Harness 阶段。
+
 ## 内置工具
 
 这些工具多数情况下会由 KCode 自动使用；当需要明确证据或排障时，也可以按下面参数手动调用。
@@ -279,6 +310,30 @@ kd_question action=list
 
 一次只能登记一个当前最阻塞的问题，最多 3 个简短选项。
 
+### kd_subagent
+
+将局部任务委派给隔离 Pi 子进程：
+
+```text
+kd_subagent role=review task="审查当前 run 的门禁和证据缺口"
+kd_subagent role=research task="查找采购订单保存插件相关代码" dryRun=true
+kd_subagent tasks=[{"role":"research","task":"查找模型层"},{"role":"review","task":"审查状态机"}]
+kd_subagent chain=[{"role":"research","task":"找相关代码"},{"role":"review","task":"基于上一输出审查风险"}]
+```
+
+参数：
+
+```text
+role            必填，research/doc/code/review/verify
+task            必填，具体委派任务
+tasks           可选，并行任务数组，只允许 research/review/verify，和 role/task/chain 三选一
+chain           可选，链式任务数组，和 role/task/tasks 三选一
+dryRun          可选，只预览上下文包
+maxOutputChars  可选，限制返回给主 agent 的输出长度
+```
+
+主 Harness 仍负责阶段推进、证据和门禁；子 agent 返回结果后由主 agent 决策下一步。
+
 ### kd_search
 
 搜索随包金蝶知识库：

package/docs/HARNESS_WORKFLOW.md

@@ -145,3 +145,36 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 - 必须先理解当前业务项目已有目录、模块、包名、基类和本地封装。
 
 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。
+
+## 子 agent 委派
+
+KCode 支持把局部任务委派给隔离子 agent，用来降低长上下文带来的注意力漂移。主 Harness 仍是唯一状态机，负责阶段推进、门禁、证据和风险记录。
+
+触发方式有两种：
+
+- 自动：主 agent 在大量调研、独立交叉审查、长上下文复盘或可并行拆分时，可以主动调用 `kd_subagent`。
+- 显式：用户用 `/kd-review` 或 `/kd-delegate` 指定委派任务。
+
+常用入口：
+
+```text
+/kd-review 审查当前实现是否有门禁绕过和测试缺口
+/kd-delegate research 调研采购订单保存插件相关代码
+/kd-delegate doc 更新当前阶段文档 --dry-run
+```
+
+角色边界：
+
+- `research`、`review` 默认只读。
+- `doc` 只写明确指定的文档或阶段产物。
+- `code` 只能在 `execute` 阶段运行，并且只能修改 `PLAN.md` 批准文件。
+- `verify` 只读分析验证命令、失败证据和风险；实际命令和结果记录仍由主 agent 执行。
+
+`--dry-run` 会预览发送给子 agent 的上下文包，用来检查上下文是否过长、是否包含不该交给子 agent 的信息。
+
+工具层支持并行和链式委派。并行只允许 `research`、`review`、`verify` 这类只读角色；`doc` 和 `code` 必须串行执行：
+
+```text
+kd_subagent tasks=[{"role":"research","task":"查找模型层"},{"role":"review","task":"审查门禁"}]
+kd_subagent chain=[{"role":"research","task":"找相关代码"},{"role":"review","task":"基于上一输出审查风险"}]
+```

package/extensions/kingdee-harness.ts

@@ -24,7 +24,9 @@ import { flagshipWriteBlockReason, isSourceLikePath, planWriteBlockReason } from
 import { sdkSignatureProductionWriteBlockReason } from "../src/harness/sdk-policy.ts";
 import { tddProductionWriteBlockReason } from "../src/harness/tdd-policy.ts";
 import { windowsPathHint } from "../src/platform/path.ts";
-import { workflowPromptForRun } from "../src/harness/prompt.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";
 
 function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
@@ -275,9 +277,47 @@ const kdQuestionTool = defineTool({
 	},
 });
 
+function createKdVerifyResultTool(pi: ExtensionAPI) {
+	return defineTool({
+		name: "kd_verify_result",
+		label: "KD 验证结果",
+		description: "记录当前 verify 命令结果。失败时自动写失败证据并回到 execute 修复；成功时记录通过证据并尝试推进。",
+		parameters: Type.Object({
+			command: Type.String({ description: "实际执行的验证命令。" }),
+			exitCode: Type.Number({ description: "验证命令退出码。" }),
+			stdout: Type.Optional(Type.String({ description: "验证命令 STDOUT 摘要或完整输出。" })),
+			stderr: Type.Optional(Type.String({ description: "验证命令 STDERR 摘要或完整输出。" })),
+			summary: Type.Optional(Type.String({ description: "失败原因或通过结论摘要。" })),
+		}),
+
+		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 <需求> 创建。" }],
+					details: { error: "no-active-run" },
+				};
+			}
+			const outcome = recordVerifyResult(ctx.cwd, run, {
+				command: params.command,
+				exitCode: params.exitCode,
+				stdout: params.stdout,
+				stderr: params.stderr,
+				summary: params.summary,
+			});
+			handleVerifyOutcome(pi, ctx, outcome);
+			return {
+				content: [{ type: "text", text: outcome.message }],
+				details: { outcome },
+			};
+		},
+	});
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdPlanStatusTool);
 	pi.registerTool(kdQuestionTool);
+	pi.registerTool(createKdVerifyResultTool(pi));
 
 	pi.on("session_start", async (_event, ctx) => {
 		const run = readActiveRun(ctx.cwd);
@@ -294,6 +334,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") return { action: "continue" };
+		if (isSubagentChild()) return { action: "continue" };
 
 		let run = readActiveRun(ctx.cwd);
 		if (!run && shouldStartHarnessFromInput(event.text)) {
@@ -324,6 +365,29 @@ export default function (pi: ExtensionAPI) {
 			return { block: true, reason };
 		}
 
+		const subagentRole = isSubagentChild() ? subagentRoleFromEnv() : undefined;
+		if (subagentRole) {
+			const run = readActiveRun(ctx.cwd);
+			const sourceWriteBlock =
+				sdkSignatureProductionWriteBlockReason(ctx.cwd, run, path) ??
+				tddProductionWriteBlockReason(ctx.cwd, run, path) ??
+				planWriteBlockReason(ctx.cwd, run, path, run ? (readArtifact(ctx.cwd, run, "plan") ?? "") : "") ??
+				flagshipWriteBlockReason(run, path, ctx.cwd);
+			const reason = subagentToolCallBlockReason({
+				role: subagentRole,
+				toolName: event.toolName,
+				path,
+				cwd: ctx.cwd,
+				run,
+				sourceLike: path ? isSourceLikePath(path) : false,
+				sourceWriteBlockReason: sourceWriteBlock,
+			});
+			if (reason) {
+				if (ctx.hasUI) ctx.ui.notify(reason, "warning");
+				return { block: true, reason };
+			}
+		}
+
 		if (event.toolName !== "write" && event.toolName !== "edit") return undefined;
 
 		const reason = codeWriteBlockReason(ctx.cwd, path) ?? flagshipWriteBlockReason(readActiveRun(ctx.cwd), path, ctx.cwd);
@@ -551,6 +615,37 @@ export default function (pi: ExtensionAPI) {
 			autoAdvanceCommand(pi, ctx, readActiveRun(ctx.cwd) ?? run, `${answered.id} 已回答。`);
 		},
 	});
+
+	pi.registerCommand("kd-verify-result", {
+		description: "记录验证命令结果：/kd-verify-result <exitCode> <command>",
+		handler: async (args, ctx) => {
+			const run = requireRun(ctx.cwd);
+			if (!run) {
+				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				return;
+			}
+			const [exitCodeText, ...commandParts] = args.trim().split(/\s+/);
+			const exitCode = Number(exitCodeText);
+			const command = commandParts.join(" ").trim();
+			if (!Number.isFinite(exitCode) || !command) {
+				ctx.ui.notify("用法：/kd-verify-result <exitCode> <command>", "error");
+				return;
+			}
+			const outcome = recordVerifyResult(ctx.cwd, run, { command, exitCode });
+			ctx.ui.notify(outcome.message, outcome.status === "passed" ? "info" : "warning");
+			handleVerifyOutcome(pi, ctx, outcome);
+		},
+	});
+}
+
+function handleVerifyOutcome(pi: ExtensionAPI, ctx: ExtensionContext, outcome: VerifyResultOutcome): void {
+	if (outcome.status === "passed") {
+		autoAdvanceCommand(pi, ctx, outcome.run, "验证结果已通过。");
+		return;
+	}
+	if (outcome.status === "repairing") {
+		sendWorkflowPrompt(pi, ctx, outcome.run, repairPromptForRun(outcome.run));
+	}
 }
 
 function formatQuestions(run: NonNullable<ReturnType<typeof readActiveRun>>): string {

package/extensions/kingdee-header.ts

@@ -4,6 +4,96 @@ import { readActiveRun } from "../src/harness/state.ts";
 import type { ActiveRun, GateResult } from "../src/harness/types.ts";
 import { formatProductProfile } from "../src/product/profile.ts";
 
+/** ANSI escape sequence pattern: CSI, OSC, APC. */
+const ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b_[^\x1b]*\x1b\\/g;
+
+/** Visible width of a string (strips ANSI codes; CJK/wide chars = 2 columns). */
+function visibleWidth(str: string): number {
+	let width = 0;
+	const clean = str.replace(ANSI_RE, "");
+	for (const ch of clean) {
+		const code = ch.codePointAt(0)!;
+		width +=
+			code >= 0x1100 &&
+			!(code >= 0x00a0 && code <= 0x00ff) &&
+			((code >= 0x1100 && code <= 0x115f) ||
+				(code >= 0x2329 && code <= 0x232a) ||
+				(code >= 0x2e80 && code <= 0x303e) ||
+				(code >= 0x3040 && code <= 0x3247) ||
+				(code >= 0x3250 && code <= 0x4dbf) ||
+				(code >= 0x4e00 && code <= 0xa4c6) ||
+				(code >= 0xa960 && code <= 0xa97c) ||
+				(code >= 0xac00 && code <= 0xd7a3) ||
+				(code >= 0xf900 && code <= 0xfaff) ||
+				(code >= 0xfe10 && code <= 0xfe19) ||
+				(code >= 0xfe30 && code <= 0xfe6b) ||
+				(code >= 0xff01 && code <= 0xff60) ||
+				(code >= 0xffe0 && code <= 0xffe6) ||
+				(code >= 0x1f300 && code <= 0x1f9ff) ||
+				(code >= 0x20000 && code <= 0x2fffd))
+				? 2
+				: 1;
+	}
+	return width;
+}
+
+/**
+ * If the line's visible width exceeds `maxWidth`, truncate visible characters
+ * and append `>` so the result fits. Preserves ANSI codes in the kept portion
+ * and appends SGR reset before the `>`. No padding — pi-tui only requires
+ * visibleWidth <= width.
+ */
+function clipLine(text: string, maxWidth: number): string {
+	if (maxWidth <= 0) return "";
+	const vw = visibleWidth(text);
+	if (vw <= maxWidth) return text;
+
+	const targetW = maxWidth - 1; // reserve 1 col for ">"
+	let result = "";
+	let visibleSoFar = 0;
+	let i = 0;
+
+	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\\)/);
+			if (m) {
+				result += m[0];
+				i += m[0].length;
+				continue;
+			}
+		}
+
+		const ch = text[i];
+		const code = ch.codePointAt(0)!;
+		const wide =
+			(code >= 0x1100 && code <= 0x115f) ||
+			(code >= 0x2329 && code <= 0x232a) ||
+			(code >= 0x2e80 && code <= 0x303e) ||
+			(code >= 0x3040 && code <= 0x3247) ||
+			(code >= 0x3250 && code <= 0x4dbf) ||
+			(code >= 0x4e00 && code <= 0xa4c6) ||
+			(code >= 0xa960 && code <= 0xa97c) ||
+			(code >= 0xac00 && code <= 0xd7a3) ||
+			(code >= 0xf900 && code <= 0xfaff) ||
+			(code >= 0xfe10 && code <= 0xfe19) ||
+			(code >= 0xfe30 && code <= 0xfe6b) ||
+			(code >= 0xff01 && code <= 0xff60) ||
+			(code >= 0xffe0 && code <= 0xffe6) ||
+			(code >= 0x1f300 && code <= 0x1f9ff) ||
+			(code >= 0x20000 && code <= 0x2fffd);
+		const charW = wide ? 2 : 1;
+
+		if (visibleSoFar + charW > targetW) break;
+
+		result += ch;
+		visibleSoFar += charW;
+		i++;
+	}
+
+	return result + "\x1b[0m>";
+}
+
 function formatProduct(run: ActiveRun | undefined): string {
 	if (!run) return "未选择";
 	if (run.profile?.product === "unknown") return "未确认";
@@ -43,12 +133,6 @@ function riskColor(risk: string): "error" | "warning" | "muted" | "success" {
 	return "success";
 }
 
-function padOrTrim(text: string, width: number): string {
-	if (width <= 0) return "";
-	if (text.length > width) return text.slice(0, Math.max(0, width - 1)) + ">";
-	return text + " ".repeat(width - text.length);
-}
-
 function logoLines(theme: Theme): string[] {
 	const accent = (text: string) => theme.fg("accent", text);
 	const muted = (text: string) => theme.fg("muted", text);
@@ -87,9 +171,9 @@ export default function (pi: ExtensionAPI) {
 
 					return [
 						"",
-						...logoLines(theme).map((line) => padOrTrim(line, width)),
-						padOrTrim(status, width),
-						padOrTrim(theme.fg("dim", `run：${runId}`), width),
+						...logoLines(theme).map((line) => clipLine(line, width)),
+						clipLine(status, width),
+						clipLine(theme.fg("dim", `run：${runId}`), width),
 						"",
 					];
 				},