kcode-pi 0.1.24 → 0.1.30

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,88 @@
 
 - 暂无。
 
+## 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
+
+### 修复
+
+- 强化 active run / RUN.json 读取容错，过滤异常 `questions`、`artifacts`、`riskAssessment`、`gate` 字段，避免旧状态或坏状态触发门禁崩溃。
+- Header 渲染门禁时增加兜底，门禁异常会显示为阻塞状态，不再导致 TUI 进程退出。
+- 阶段产物存在但不可读或误建为目录时，现在按缺失处理，不再在读取 `CONTEXT.md`、`PLAN.md`、`EXECUTION.md` 等文件时抛出异常。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖损坏 run state 和损坏 evidence index 的容错。
+
+## 0.1.26 - 2026-06-07
+
+### 修复
+
+- 修复已有项目的 `evidence/index.json` 中存在异常 entry 时，Header 门禁渲染可能因读取 `path` 崩溃的问题。
+- `readEvidenceIndex` 现在会过滤无效 evidence entry，`hasEvidenceEntry` 和 evidence 记录逻辑对坏数据保持容错。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖损坏 evidence index 不再触发崩溃。
+
+## 0.1.25 - 2026-06-07
+
+### 修复
+
+- 修复 `/kd-risk`、`/kd-product`、`/kd-answer`、`/kd-artifact` 等命令在解除门禁后不会自动尝试推进下一阶段的问题。
+- 修复 `kd_question` 回答阻断问题后只刷新门禁、不尝试推进的问题。
+- 修复 `kd_cosmic_config`、`kd_cosmic_metadata`、`kd_cosmic_api`、`kd_sdk_signature`、`kd_ksql_lint` 写入证据后不反馈自动推进结果的问题。
+- 修复官方 evidence 只要文件存在就可能满足门禁的问题；现在要求 evidence index 中记录的退出码为 `0`。
+
+### 验证
+
+- `npm run smoke:harness` 通过，覆盖阻断问题回答后的自动推进、风险更新后的自动推进尝试，以及失败 evidence 不能通过门禁。
+
 ## 0.1.24 - 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

@@ -4,6 +4,7 @@ import { formatStatus } from "../src/harness/format.ts";
 import { PHASE_ORDER, isKdPhase, type KdPhase } from "../src/harness/types.ts";
 import {
 	advanceRun,
+	advanceRunIfReady,
 	addQuestion,
 	answerQuestion,
 	createActiveRun,
@@ -23,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);
@@ -109,6 +112,26 @@ function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNul
 	if (ctx.hasUI) ctx.ui.notify("KCode 工作流消息已排队。", "info");
 }
 
+function autoAdvanceCommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	run: NonNullable<ReturnType<typeof readActiveRun>>,
+	reason: string,
+): ReturnType<typeof advanceRunIfReady> {
+	const result = advanceRunIfReady(ctx.cwd, run);
+	if (result.advanced) {
+		if (ctx.hasUI) ctx.ui.notify(result.message, "info");
+		sendWorkflowPrompt(pi, ctx, result.run, `${reason}\n继续 KCode Harness run ${result.run.id}：${result.run.goal ?? "未知需求"}`);
+	} else if (!result.message.includes("最终阶段")) {
+		if (ctx.hasUI) ctx.ui.notify(`门禁仍阻塞：${result.message}`, "warning");
+	}
+	return result;
+}
+
+function autoAdvanceTool(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>): ReturnType<typeof advanceRunIfReady> {
+	return advanceRunIfReady(cwd, run);
+}
+
 function codeWriteBlockReason(cwd: string, path: string | undefined): string | undefined {
 	if (!path || !isSourceLikePath(path)) return undefined;
 
@@ -188,9 +211,10 @@ const kdQuestionTool = defineTool({
 				};
 			}
 			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
+			const auto = autoAdvanceTool(ctx.cwd, run);
 			return {
-				content: [{ type: "text", text: `已记录 ${answered.id} 的答案，并刷新门禁。` }],
-				details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate },
+				content: [{ type: "text", text: `已记录 ${answered.id} 的答案。${auto.advanced ? auto.message : `门禁仍阻塞：${auto.message}`}` }],
+				details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, autoAdvance: auto },
 			};
 		}
 
@@ -240,9 +264,10 @@ const kdQuestionTool = defineTool({
 			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}` }],
-					details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, answered: true },
+					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 },
 				};
 			}
 		}
@@ -252,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);
@@ -271,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)) {
@@ -301,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);
@@ -427,6 +514,7 @@ export default function (pi: ExtensionAPI) {
 
 			const updated = updateProductProfile(ctx.cwd, run, parsed.product, parsed.version);
 			ctx.ui.notify(`产品画像：${updated.profile?.product}/${updated.profile?.techStack}/${updated.profile?.language}`, "info");
+			autoAdvanceCommand(pi, ctx, updated, "产品画像已更新。");
 		},
 	});
 
@@ -447,6 +535,7 @@ export default function (pi: ExtensionAPI) {
 
 			const updated = updateRisk(ctx.cwd, run, risk.risk, risk.reason);
 			ctx.ui.notify(`风险等级：${updated.riskAssessment?.level}（${updated.riskAssessment?.reason}）`, "info");
+			autoAdvanceCommand(pi, ctx, updated, "风险评估已更新。");
 		},
 	});
 
@@ -498,6 +587,7 @@ export default function (pi: ExtensionAPI) {
 				? updatePhaseArtifact(ctx.cwd, run, parsed.phase, parsed.content)
 				: ensurePhaseArtifact(ctx.cwd, run, parsed.phase);
 			ctx.ui.notify(`阶段文档已就绪：${path}`, "info");
+			autoAdvanceCommand(pi, ctx, readActiveRun(ctx.cwd) ?? run, `${parsed.phase} 阶段文档已更新。`);
 		},
 	});
 
@@ -522,8 +612,40 @@ export default function (pi: ExtensionAPI) {
 			}
 			appendQuestionEventToArtifact(ctx.cwd, run, [`- 已回答 ${answered.id}：${answered.answer}`]);
 			ctx.ui.notify(`已记录 ${answered.id} 的答案`, "info");
+			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

@@ -19,6 +19,19 @@ function formatGate(gate: GateResult | undefined): string {
 	return gate.passed ? "门禁：通过" : "门禁：阻塞";
 }
 
+function safeInspectGate(cwd: string, run: ActiveRun | undefined): GateResult | undefined {
+	if (!run) return undefined;
+	try {
+		return inspectGate(cwd, run);
+	} catch (error) {
+		return {
+			passed: false,
+			reason: error instanceof Error ? error.message : String(error),
+			checkedAt: new Date().toISOString(),
+		};
+	}
+}
+
 function riskLevel(run: ActiveRun | undefined): string {
 	return run?.riskAssessment?.level ?? "未知";
 }
@@ -54,7 +67,7 @@ export default function (pi: ExtensionAPI) {
 			return {
 				render(width: number): string[] {
 					const run = readActiveRun(ctx.cwd);
-					const gateState = run ? inspectGate(ctx.cwd, run) : undefined;
+					const gateState = safeInspectGate(ctx.cwd, run);
 					const phase = formatPhase(run?.phase);
 					const product = formatProduct(run);
 					const gate = formatGate(gateState);