kcode-pi 0.1.23 → 0.1.27

package/docs/CHANGELOG.md

@@ -4,9 +4,61 @@
 
 ## 未发布
 
+- 暂无。
+
+## 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
+
 ### 新增
 
 - 新增更新日志文档，并在 README 文档导航中提供入口。
+- 新增 `src/harness/prompt.ts`，集中管理运行时 Harness prompt。
+- 新增 `src/harness/messages.ts`，集中管理 Harness 门禁、证据、路径、SDK/TDD 阻断消息。
+
+### 改进
+
+- 收敛运行时 prompt，只保留状态、最近阶段资料、项目上下文摘要、当前阶段任务和核心约束。
+- 精简 `kd-plan`、`kd-execute`、`kd-verify` 命令入口提示，减少和 skills、门禁规则的重复。
+- 移除不存在的 IDE 相关验证表述，保留 Gradle/dotnet 的真实构建验证策略。
+
+### 验证
+
+- `npm run release:check` 通过，包含 TypeScript 检查、CLI 构建、Harness smoke、KCode 命令 smoke、SDK 签名 smoke、package smoke 和 pack dry run。
 
 ## 0.1.23 - 2026-06-07
 

package/docs/EVIDENCE_AND_GATES.md

@@ -89,13 +89,12 @@ Exit: 0
 退出码：0
 ```
 
-不能写：
+以下内容不能作为绿灯证据：
 
 - “需在开发环境验证”
 - “待验证”
 - “未执行”
 - “应该可以”
-- “Kingdee IDE 中编译”
 
 如果命令无法运行，记录真实阻塞原因和残余风险，不能把它当绿灯。
 
@@ -107,7 +106,7 @@ Exit: 0
 evidence/index.json
 ```
 
-KCode 内置工具和统一 evidence 写入路径会自动维护索引。不要手工塞文件绕过门禁。
+KCode 内置工具和统一 evidence 写入路径会自动维护索引。
 
 常见 evidence：
 
@@ -165,4 +164,4 @@ medium
 high
 ```
 
-风险原因应来自 `VERIFY.md` 和 `SHIP.md` 的真实验证结果，不要为了过门禁随手写 `low`。
+风险原因应来自 `VERIFY.md` 和 `SHIP.md` 的真实验证结果。

package/docs/HARNESS_WORKFLOW.md

@@ -58,7 +58,7 @@ ship     汇总变更、验证证据、风险和后续事项
 /kd-advance ship
 ```
 
-门禁不通过时，不要绕过。先按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
+门禁不通过时，先按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
 
 ## 阶段文档
 
@@ -107,7 +107,6 @@ evidence/index.json
 原则：
 
 - 一次只问一个当前最阻塞的问题。
-- 不要把 FormId、字段、触发时机、弹窗内容打包成问题清单。
 - 得到答案后再继续问下一个必要问题。
 
 ## 多个需求
@@ -143,7 +142,6 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 - 未进入 `execute` 阶段不能写产品代码。
 - `execute` 只能写 `PLAN.md` 中批准的真实源码文件。
 - 临时发现要改新文件，先回到 `plan` 更新计划。
-- 不允许凭空写 demo、sample、scaffold。
 - 必须先理解当前业务项目已有目录、模块、包名、基类和本地封装。
 
 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。

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,
@@ -22,8 +23,8 @@ 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 { tddProductionWriteBlockReason } from "../src/harness/tdd-policy.ts";
-import { readProjectContext } from "../src/context/project-context.ts";
 import { windowsPathHint } from "../src/platform/path.ts";
+import { workflowPromptForRun } from "../src/harness/prompt.ts";
 
 function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
@@ -109,75 +110,24 @@ function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNul
 	if (ctx.hasUI) ctx.ui.notify("KCode 工作流消息已排队。", "info");
 }
 
-function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>, userText: string): string {
-	const status = formatStatus(cwd, run);
-	const memory = workflowMemoryForRun(cwd, run);
-	const phaseGuidance = phaseGuidanceForRun(run);
-
-	return [
-		"用户输入：",
-		userText,
-		"",
-		"KCode 项目常驻上下文：",
-		readProjectContext(cwd) ?? "未生成。请在终端运行 `kcode context --refresh` 后继续；在生成前不要猜测项目目录。",
-		"",
-		"KCode Harness 状态：",
-		status,
-		"",
-		"KCode 本次工作流本地文档：",
-		memory,
-		"",
-		"需求来源处理：如果用户输入的是本地文件路径，先读取该文件并抽取需求；如果是目录，先列出候选需求文档再读取最相关文件；如果是在线文档链接，先尝试访问或导出可读内容。遇到登录、权限或防下载限制时，只问一个最阻塞问题：请用户提供可访问链接、导出文件路径或关键内容。不要要求用户改写成 KCode 专用格式。",
-		"",
-		`当前 active run 对应本次需求目标：${run.goal ?? run.id}。如果用户补充的是同一目标下的需求文档或细节，先纳入当前阶段文档；如果是无关目标，再要求用户运行 /kd-start <新需求> 创建新 run，或 /kd-switch <run-id> 切换已有 run。`,
-		"需要用户确认时，kd_question 一次只能问一个当前最阻塞的问题；不要把 FormId、触发时机、库存条件、弹窗内容、插件位置等打包成清单。选项最多 3 个；交互模式下会弹出选择/输入对话并自动记录答案。",
-		"",
-		phaseGuidance,
-		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
-		"禁止凭记忆、模型知识或随包知识库直接编写 SDK 方法调用。Java/C# 代码中出现的 SDK 类、方法、构造器、枚举和属性，必须来自 kd_sdk_signature 对当前项目 jar/dll 的成功结果、项目构建输出或官方元数据证据。",
-		"kd_search、kd_cosmic_api 和随包知识只能用于找线索；没有 evidence/sdk-signature.md 或明确构建证据时，不得进入 execute，也不得写生产源码。",
-		"路径规则：在 Windows 工作区内，优先使用项目相对路径；如需绝对路径必须使用 `D:\\...` 这类 Windows 路径，禁止把路径改写成 `/mnt/d/...`、`/d/...` 等 WSL/MSYS 风格路径。",
-		"execute 阶段只能写 PLAN.md 明确列出的源码文件；如果目标文件不在计划内，必须先回到 plan 更新 PLAN.md。",
-		"写生产源码前必须先有红灯证据 evidence/tdd-red.md；Java/C# 还必须有 SDK 签名证据 evidence/sdk-signature.md。红绿证据可以是 kd_sdk_signature 本地 SDK 签名、API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
-		"语法/编译验证必须使用真实项目构建命令：Java/Cosmic/苍穹/星空旗舰版使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `:模块:build`；C#/企业版使用 `dotnet build` 或 `dotnet build <.sln/.csproj>`。",
-		"不要写“Kingdee IDE 中编译”作为验证方式或绿灯证据；命令无法运行时，记录真实阻塞原因和残余风险，不能标记为通过。",
-		"如果门禁提示 evidence 内容无效，不要通过改写结论、补关键词或反复读取文件来过关；必须重新运行 PLAN.md 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。",
-	].join("\n");
-}
-
-function phaseGuidanceForRun(run: NonNullable<ReturnType<typeof readActiveRun>>): string {
-	const guidance: Record<KdPhase, string> = {
-		discuss:
-			"当前处于 discuss。先理解需求来源，判断是一条需求还是一组需求；梳理可确认事实、边界、开放问题和后续需要验证的产品信息；不要编辑产品代码。",
-		spec:
-			"当前处于 spec。先把需求写成可验收条目；如果是一组需求，明确每条需求的验收标准、依赖、风险和批次关系；不要编辑产品代码。",
-		plan:
-			"当前处于 plan。先检查当前项目结构，写明真实目标路径、允许修改文件、查证项、验证命令和回滚说明；如果是一组需求，按批次组织计划；必须明确声明是否涉及产品实现、构建、元数据或 SDK 查证；不要编辑产品代码。",
-		execute:
-			"当前处于 execute。只能实现 PLAN.md 中批准的内容和文件。先读取 PLAN.md 和实际项目文件，遵循既有结构写真实可用代码；不要写 demo/sample/scaffold。",
-		verify:
-			"当前处于 verify。先使用 kd-verify 收集验证证据，不要继续扩大代码改动。",
-		ship:
-			"当前处于 ship。整理发布摘要、验证证据、风险和后续事项，不要继续扩大代码改动。",
-	};
-	return guidance[run.phase];
-}
-
-function workflowMemoryForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>): string {
-	const phases = PHASE_ORDER.slice(0, PHASE_ORDER.indexOf(run.phase) + 1);
-	return phases
-		.map((phase) => {
-			const content = readArtifact(cwd, run, phase);
-			if (!content) return undefined;
-			return [`## ${phase}`, trimForPrompt(content, 6000)].join("\n");
-		})
-		.filter(Boolean)
-		.join("\n\n") || "暂无阶段文档。";
+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 trimForPrompt(content: string, maxLength: number): string {
-	if (content.length <= maxLength) return content;
-	return `${content.slice(0, maxLength)}\n\n[...文档过长，已截断；如需完整内容必须读取本地文件...]`;
+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 {
@@ -218,11 +168,11 @@ 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 个简短选项。" })),
@@ -259,9 +209,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 },
 			};
 		}
 
@@ -311,9 +262,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 },
 				};
 			}
 		}
@@ -367,7 +319,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 工作区，不能使用 WSL/MSYS 路径 ${path}。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}；不要再尝试 /mnt/d 或 /d 路径。`;
+			const reason = `当前是 Windows 工作区，路径 ${path} 不是本项目使用的路径形式。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}。`;
 			if (ctx.hasUI) ctx.ui.notify(reason, "warning");
 			return { block: true, reason };
 		}
@@ -498,6 +450,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, "产品画像已更新。");
 		},
 	});
 
@@ -518,6 +471,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, "风险评估已更新。");
 		},
 	});
 
@@ -569,6 +523,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} 阶段文档已更新。`);
 		},
 	});
 
@@ -593,6 +548,7 @@ 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} 已回答。`);
 		},
 	});
 }

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);

package/extensions/kingdee-tools.ts

@@ -22,7 +22,7 @@ import {
 	writeOfficialEvidence,
 } from "../src/official/kingdee-skills.ts";
 import { resolveWorkspacePath } from "../src/platform/path.ts";
-import { readActiveRun } from "../src/harness/state.ts";
+import { advanceRunIfReady, readActiveRun } from "../src/harness/state.ts";
 import { writeEvidenceFile } from "../src/harness/evidence.ts";
 import { SDK_SIGNATURE_EVIDENCE } from "../src/harness/sdk-policy.ts";
 
@@ -97,12 +97,25 @@ async function runOrDryRun(
 
 	const result = await runOfficialCommand(command);
 	const evidencePath = evidenceFile ? writeOfficialEvidence(ctx.cwd, evidenceFile, result) : undefined;
+	const autoAdvance = evidencePath ? autoAdvanceAfterEvidence(ctx.cwd) : undefined;
 	return {
-		content: [{ type: "text" as const, text: formatCommandResult(result) }],
-		details: { command: result.command, exitCode: result.exitCode, evidencePath },
+		content: [{ type: "text" as const, text: [formatCommandResult(result), evidencePath ? `已写入证据：${evidencePath}` : undefined, autoAdvance?.text].filter(Boolean).join("\n\n") }],
+		details: { command: result.command, exitCode: result.exitCode, evidencePath, autoAdvance: autoAdvance?.details },
 	};
 }
 
+function autoAdvanceAfterEvidence(cwd: string): { text: string; details: ReturnType<typeof advanceRunIfReady> } | undefined {
+	const run = readActiveRun(cwd);
+	if (!run) return undefined;
+
+	const result = advanceRunIfReady(cwd, run);
+	if (result.advanced) {
+		return { text: result.message, details: result };
+	}
+	if (result.message.includes("最终阶段")) return undefined;
+	return { text: `门禁仍阻塞：${result.message}`, details: result };
+}
+
 const kdSearchTool = defineTool({
 	name: "kd_search",
 	label: "KD 搜索",
@@ -334,9 +347,10 @@ const kdSdkSignatureTool = defineTool({
 		});
 		const text = formatSdkSignatureResult(result);
 		const evidencePath = result.exitCode === 0 ? writeSdkSignatureEvidence(ctx.cwd, text) : undefined;
+		const autoAdvance = evidencePath ? autoAdvanceAfterEvidence(ctx.cwd) : undefined;
 		return {
-			content: [{ type: "text", text: evidencePath ? `${text}\n\n已写入 SDK 签名证据：${evidencePath}` : text }],
-			details: { product: profile.product, evidencePath, ...result },
+			content: [{ type: "text", text: [text, evidencePath ? `已写入 SDK 签名证据：${evidencePath}` : undefined, autoAdvance?.text].filter(Boolean).join("\n\n") }],
+			details: { product: profile.product, evidencePath, autoAdvance: autoAdvance?.details, ...result },
 		};
 	},
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.23",
+  "version": "0.1.27",
   "description": "面向金蝶开发的 Pi Coding Agent 启动器、工具包和 Harness 工作流",
   "type": "module",
   "private": false,

package/prompts/kd-execute.md

@@ -4,9 +4,9 @@ description: 在 Harness 门禁约束下执行当前金蝶实施计划。
 
 使用 `kd-execute` skill。
 
-编辑代码前，先使用 `kd_plan_status` 检查当前 run。如果缺少 `PLAN.md`、`evidence/sdk-signature.md` 或门禁被阻塞，必须停止并说明缺少的文档或证据。通过后只实现 `PLAN.md` 批准的内容，并更新 `EXECUTION.md`。禁止凭记忆、模型知识或随包知识库猜 SDK 方法签名。
+先检查当前 run 和门禁。通过后只实现 `PLAN.md` 批准的内容，更新 `EXECUTION.md`，并按计划记录红绿 evidence。
 
-实现后要按计划运行真实构建检查语法问题：Java 使用当前项目 Gradle 命令，例如 `.\gradlew.bat build` 或 `.\gradlew.bat :模块:build`；C# 使用 `dotnet build` 或 `dotnet build <.sln/.csproj>`。不能写“Kingdee IDE 中编译”作为验证结果；命令未运行就不能记录为绿灯证据。
+实现后运行计划中的验证命令；命令无法运行时记录阻塞原因和残余风险。
 
 用户补充说明：
 

package/prompts/kd-plan.md

@@ -4,13 +4,9 @@ description: 为当前金蝶 Harness run 编写实施计划。
 
 使用 `kd-plan` skill。
 
-读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。必须包含已检查的项目结构、需要查看的文件、预计修改的真实路径、是否涉及产品实现/构建/元数据/SDK 查证、必须查证的金蝶 API/元数据、SDK 签名证据、验证命令和回滚说明。Java/C# SDK 方法签名必须来自 `kd_sdk_signature` 当前项目 jar/dll、项目构建输出或官方元数据，不能凭记忆猜。
+读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。重点写清：项目结构、目标路径、允许修改文件、SDK/元数据查证、验证命令和回滚说明。
 
-验证命令必须贴近真实项目：
-
-- 苍穹 / 星瀚 / 星空旗舰版 Java：优先使用当前项目 Gradle 构建做语法和编译检查，例如 `./gradlew build`、`./gradlew :模块:build` 或 Windows 下的 `.\gradlew.bat build`。
-- C# / 企业版：使用 `dotnet build` 或 `dotnet build <.sln/.csproj>` 做语法和编译检查。
-- 不要写“Kingdee IDE 中编译”。如果当前机器缺少依赖导致命令无法运行，要记录真实阻塞原因，不能把未执行的编译当作绿灯证据。
+验证命令按产品选择：Cosmic Java 用当前项目 Gradle；企业版 C# 用 `dotnet build`。命令无法运行时记录阻塞原因和应运行的具体命令。
 
 用户补充说明：
 

package/prompts/kd-verify.md

@@ -4,13 +4,7 @@ description: 验证当前金蝶实现并收集证据。
 
 使用 `kd-verify` skill。
 
-执行计划中的验证命令，收集证据，运行可用检查，并更新 `VERIFY.md`。如果某项验证无法运行，记录具体阻塞原因和残余风险。
-
-验证优先使用真实构建命令检查语法和编译：
-
-- 苍穹 / 星瀚 / 星空旗舰版 Java：运行当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`.\gradlew.bat :模块:build` 或同等 Gradle task。
-- C# / 企业版：运行 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。
-- 绿灯证据必须包含实际命令、`Exit: 0` 和输出摘要。不能用“Kingdee IDE 中编译”“需在开发环境验证”替代真实证据。
+执行 `PLAN.md` 中的验证命令，收集 evidence，并更新 `VERIFY.md`。成功证据记录命令、`Exit: 0` 和输出摘要；命令无法运行时记录阻塞原因和残余风险。
 
 用户补充说明：
 

package/skills/kd-cosmic-unittest/SKILL.md

@@ -79,7 +79,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 写完测试后：
 
 - 使用 `kd_build` 或计划中的命令运行最窄可行 Gradle test 任务。
-- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task；不要写“在 IDE 中运行”作为验证结论。
+- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task。
 - 存在 harness run 时，把测试文件和验证结果写入 `.pi/kd/runs/<run-id>/EXECUTION.md`。
 
 ## 输出要求

package/skills/kd-execute/SKILL.md

@@ -24,5 +24,5 @@ Rules:
 - Before entering verify, rerun the same check and record passing output in `evidence/tdd-green.md`.
 - After implementation, run the planned real build command for syntax/compile validation when available: Java uses the project Gradle command such as `.\gradlew.bat build` or `.\gradlew.bat :module:build`; C# uses `dotnet build` or `dotnet build <.sln/.csproj>`.
 - Do not add JUnit, Mockito, NUnit, xUnit, or any extra test jar/framework only to satisfy the gate. Use existing approved project test infrastructure if it already exists.
-- Do not record "compile in Kingdee IDE" or "needs local development environment verification" as green evidence. If the command cannot run, record the blocker instead of marking verification passed.
+- If the command cannot run, record the blocker instead of marking verification passed.
 - If implementation needs a plan change, update `PLAN.md` first.

package/skills/kd-plan/SKILL.md

@@ -28,7 +28,7 @@ Gate:
 - Execution must not start without `PLAN.md`.
 - A plan for 星空旗舰版 is incomplete unless it records the existing project layout and exact target path to edit. If `code/` exists, follow its actual structure; if it does not, record the discovered source root or existing target file.
 - A plan without validation commands is incomplete.
-- A Java/C# plan that uses vague wording such as "compile in Kingdee IDE" instead of a real Gradle or dotnet command is incomplete.
+- A Java/C# plan without a concrete Gradle or dotnet validation command is incomplete.
 - A plan without structured `STEP-001` execution steps is incomplete.
 - A plan without TDD red/green checks is incomplete.
 - A plan that relies on unverified Kingdee API names is incomplete; bundled knowledge alone is not enough when local SDK jars/dlls or compile evidence are available.

package/skills/kd-verify/SKILL.md

@@ -20,5 +20,5 @@ Rules:
 
 - Passing unit tests is not enough if acceptance criteria require workflow behavior.
 - If validation cannot run, state the exact blocker.
-- Do not use "Kingdee IDE" as a verification target. Evidence must show the real command, `Exit: 0`, and useful output summary.
+- Passing evidence must show the real command, `Exit: 0`, and useful output summary.
 - Do not ship while verification evidence is missing.

package/src/harness/artifacts.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import type { ActiveRun, KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS } from "./types.ts";
 import { runArtifactPath, runRoot } from "./paths.ts";
@@ -10,7 +10,11 @@ export function ensureRunDirectories(cwd: string, run: ActiveRun): void {
 }
 
 export function artifactExists(cwd: string, run: ActiveRun, artifactName: string): boolean {
-	return existsSync(runArtifactPath(cwd, run, artifactName));
+	try {
+		return statSync(runArtifactPath(cwd, run, artifactName)).isFile();
+	} catch {
+		return false;
+	}
 }
 
 export function phaseArtifactPath(cwd: string, run: ActiveRun, phase: KdPhase): string {
@@ -19,7 +23,11 @@ export function phaseArtifactPath(cwd: string, run: ActiveRun, phase: KdPhase):
 
 export function readArtifact(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
 	const path = phaseArtifactPath(cwd, run, phase);
-	return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+	try {
+		return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+	} catch {
+		return undefined;
+	}
 }
 
 export function writeArtifact(cwd: string, run: ActiveRun, phase: KdPhase, content: string): string {
@@ -115,10 +123,10 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"- Java 语法/编译检查：优先使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `./gradlew :模块:build`。",
 				"- C# 语法/编译检查：使用 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。",
 				"- 允许的检查：本地 SDK 签名查证、官方 API/基类/方法查证、元数据查证、kd_check、Gradle/dotnet 构建输出、项目已有测试框架、外部接口最小验证。",
-				"- 不要为了满足门禁引入第三方测试 jar 或框架。",
-				"- 不要写“Kingdee IDE 中编译”作为验证方式；命令无法运行时记录真实阻塞原因，不能作为绿灯证据。",
+				"- 测试框架：优先使用项目已有测试基础设施。",
+				"- 命令无法运行时记录真实阻塞原因和残余风险，不能作为绿灯证据。",
 				"- 如果无法自动化测试，记录一个产品相关、实现前应失败且实现后应通过的检查。",
-				"- 禁止凭记忆或随包知识库猜 SDK 方法签名；签名事实必须来自当前项目 jar/dll、构建输出或官方元数据。",
+				"- SDK 方法签名事实必须来自当前项目 jar/dll、构建输出或官方元数据。",
 				"",
 				"## 验证命令",
 				"",

package/src/harness/evidence.ts

@@ -28,8 +28,9 @@ export function readEvidenceIndex(cwd: string, run: ActiveRun): EvidenceIndex {
 	const path = evidenceIndexPath(cwd, run);
 	if (!existsSync(path)) return { version: 1, entries: [] };
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf8")) as EvidenceIndex;
-		return parsed.version === 1 && Array.isArray(parsed.entries) ? parsed : { version: 1, entries: [] };
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<EvidenceIndex>;
+		if (parsed.version !== 1 || !Array.isArray(parsed.entries)) return { version: 1, entries: [] };
+		return { version: 1, entries: parsed.entries.filter(isEvidenceEntry) };
 	} catch {
 		return { version: 1, entries: [] };
 	}
@@ -37,6 +38,7 @@ export function readEvidenceIndex(cwd: string, run: ActiveRun): EvidenceIndex {
 
 export function hasEvidenceEntry(cwd: string, run: ActiveRun, path: string): boolean {
 	const normalized = normalizeEvidencePath(path);
+	if (!normalized) return false;
 	return readEvidenceIndex(cwd, run).entries.some((entry) => normalizeEvidencePath(entry.path) === normalized);
 }
 
@@ -48,7 +50,7 @@ export function writeEvidenceFile(
 	options: { kind?: string; command?: string; exitCode?: number } = {},
 ): string {
 	const normalized = normalizeEvidencePath(path);
-	if (!normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
+	if (!normalized || !normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
 		throw new Error(`非法 evidence 路径：${path}`);
 	}
 
@@ -66,6 +68,7 @@ export function recordEvidence(
 	options: { kind?: string; command?: string; exitCode?: number } = {},
 ): void {
 	const normalized = normalizeEvidencePath(path);
+	if (!normalized) return;
 	const absolutePath = join(runRoot(cwd, run), normalized);
 	if (!existsSync(absolutePath)) return;
 
@@ -96,11 +99,19 @@ export function recordEvidence(
 	writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, "utf8");
 }
 
+function isEvidenceEntry(value: unknown): value is EvidenceEntry {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const entry = value as Partial<EvidenceEntry>;
+	return typeof entry.path === "string" && entry.path.trim().length > 0;
+}
+
 function inferKind(path: string): string {
 	const name = path.split("/").at(-1) ?? path;
 	return name.replace(/\.(md|txt|json)$/i, "");
 }
 
-function normalizeEvidencePath(path: string): string {
-	return path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+function normalizeEvidencePath(path: unknown): string | undefined {
+	if (typeof path !== "string") return undefined;
+	const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+	return normalized.trim() || undefined;
 }

package/src/harness/gates.ts

@@ -9,7 +9,16 @@ import { executionStepsBlockReason, planStepsBlockReason } from "./plan-steps.ts
 import { tddPlanBlockReason, tddVerifyBlockReason } from "./tdd-policy.ts";
 import { SDK_SIGNATURE_EVIDENCE, hasValidSdkSignatureEvidence, requiresSdkSignatureEvidence } from "./sdk-policy.ts";
 import { runRoot } from "./paths.ts";
-import { EVIDENCE_INDEX, hasEvidenceEntry } from "./evidence.ts";
+import { EVIDENCE_INDEX, readEvidenceIndex } from "./evidence.ts";
+import {
+	missingArtifactsReason,
+	missingEvidenceReason,
+	missingForTargetReason,
+	missingMarkerReason,
+	openQuestionsReason,
+	unknownProductReason,
+	unknownRiskReason,
+} from "./messages.ts";
 
 const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
 	plan: ["## 验证命令"],
@@ -104,13 +113,6 @@ function gateResult(reasonParts: string[]): GateResult {
 	};
 }
 
-function unknownProductReason(declaration: boolean | undefined): string {
-	if (declaration === undefined) {
-		return "不能进入 execute：产品画像未知，且 PLAN.md 未明确声明是否涉及产品实现、构建、元数据或 SDK 查证。下一步：先由当前需求和项目计划判断该范围；如果涉及产品实现，执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果不涉及，在 PLAN.md 的“产品实现范围”写明“不涉及”及依据。";
-	}
-	return "不能进入 execute：PLAN.md 声明涉及产品实现、构建、元数据或 SDK 查证，但产品画像未知。下一步：根据需求、计划或用户回答确认产品，然后执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。";
-}
-
 function productImplementationDeclaration(cwd: string, run: ActiveRun): boolean | undefined {
 	const plan = readArtifact(cwd, run, "plan") ?? "";
 	const line = plan
@@ -127,14 +129,10 @@ function productImplementationDeclaration(cwd: string, run: ActiveRun): boolean
 function hasRiskAssessment(cwd: string, run: ActiveRun): boolean {
 	const level = run.riskAssessment?.level;
 	if (!level) return false;
-	if (run.riskAssessment?.reason.trim()) return true;
+	if (typeof run.riskAssessment?.reason === "string" && run.riskAssessment.reason.trim()) return true;
 	return riskSectionHasContent(readArtifact(cwd, run, "verify") ?? "") || riskSectionHasContent(readArtifact(cwd, run, "ship") ?? "");
 }
 
-function unknownRiskReason(): string {
-	return "不能进入 ship：风险等级或风险原因未知。下一步：根据 VERIFY.md 和 SHIP.md 的残余风险执行 /kd-risk <low|medium|high> <原因>，或在风险章节写入真实风险说明后再刷新门禁。";
-}
-
 function riskSectionHasContent(content: string): boolean {
 	const match = content.match(/##\s*(残余风险|风险)\s*\r?\n([\s\S]*?)(?=\r?\n##\s+|$)/);
 	if (!match) return false;
@@ -145,12 +143,9 @@ function riskSectionHasContent(content: string): boolean {
 }
 
 function inspectOpenQuestions(run: ActiveRun): string | undefined {
-	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+	const open = Array.isArray(run.questions) ? run.questions.filter((question) => question.status === "open" && question.blocking) : [];
 	if (open.length === 0) return undefined;
-	return [
-		`存在未回答的阻断问题：${open.map((question) => `${question.id} ${question.question}`).join("；")}`,
-		"下一步：先向用户等待或获取答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录；不要绕过问题推进阶段。",
-	].join("。");
+	return openQuestionsReason(open);
 }
 
 function inspectStepState(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
@@ -176,7 +171,7 @@ function inspectMarkers(cwd: string, run: ActiveRun, phase: KdPhase): string | u
 
 	const missing = markers.filter((marker) => !content.includes(marker));
 	if (missing.length === 0) return undefined;
-	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}。下一步：更新 ${PHASE_ARTIFACTS[phase]}，补齐这些章节并写入真实内容；不要只添加空标题。`;
+	return missingMarkerReason(phase, missing);
 }
 
 function inspectEvidence(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
@@ -217,52 +212,13 @@ function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase):
 function evidenceArtifactSatisfied(cwd: string, run: ActiveRun, artifact: string): boolean {
 	if (artifact === SDK_SIGNATURE_EVIDENCE) return hasValidSdkSignatureEvidence(cwd, run);
 	if (artifact === EVIDENCE_INDEX) return existsSync(join(runRoot(cwd, run), artifact));
-	return existsSync(join(runRoot(cwd, run), artifact)) && hasEvidenceEntry(cwd, run, artifact);
-}
-
-function missingArtifactsReason(artifacts: string[]): string {
-	return [
-		`缺少必需产物：${artifacts.join(", ")}`,
-		`下一步：使用 /kd-artifact <阶段> 创建或更新阶段文档，或按当前阶段要求补写 ${artifacts.join(", ")} 的真实内容后再刷新门禁。`,
-	].join("。");
-}
-
-function missingForTargetReason(target: KdPhase, artifacts: string[]): string {
-	const evidence = artifacts.filter((artifact) => artifact.startsWith("evidence/"));
-	const documents = artifacts.filter((artifact) => !artifact.startsWith("evidence/"));
-	const actions: string[] = [];
-	if (documents.length > 0) {
-		actions.push(`先补齐阶段文档 ${documents.join(", ")}，可用 /kd-artifact 创建模板后填入真实分析、计划或验证内容`);
-	}
-	if (evidence.length > 0) {
-		actions.push(evidenceAction(evidence));
-	}
-	return `不能进入 ${target}：缺少 ${artifacts.join(", ")}。下一步：${actions.join("；")}。`;
-}
-
-function missingEvidenceReason(artifacts: string[]): string {
-	return `缺少必需证据：${artifacts.join(", ")}。下一步：${evidenceAction(artifacts)}。`;
-}
-
-function evidenceAction(artifacts: string[]): string {
-	return artifacts.map(evidenceArtifactAction).join("；");
+	return existsSync(join(runRoot(cwd, run), artifact)) && hasSuccessfulEvidenceEntry(cwd, run, artifact);
 }
 
-function evidenceArtifactAction(artifact: string): string {
-	switch (artifact) {
-		case SDK_SIGNATURE_EVIDENCE:
-			return "运行 kd_sdk_signature，从当前项目真实 SDK jar/dll 查证类、方法、构造器或属性签名，成功后自动写入 evidence/sdk-signature.md";
-		case COSMIC_CONFIG_EVIDENCE:
-			return "运行 kd_cosmic_config 生成 evidence/cosmic-config.txt；如果项目没有 ok-cosmic.json，先使用 KCode 默认配置，不要手写假结果";
-		case COSMIC_METADATA_EVIDENCE:
-			return "运行 kd_cosmic_metadata 查询目标表单/单据/字段元数据并生成 evidence/cosmic-metadata.json";
-		case COSMIC_API_EVIDENCE:
-			return "运行 kd_cosmic_api 查询相关 Cosmic API 线索并生成 evidence/cosmic-api.txt，再用 kd_sdk_signature 或构建输出确认签名";
-		case KSQL_LINT_EVIDENCE:
-			return "运行 kd_ksql_lint 校验 KSQL/SQL 交付内容并生成 evidence/ksql-lint.txt";
-		default:
-			return `运行 PLAN.md 中声明的验证命令，记录命令、Exit、STDOUT/STDERR 或工具输出到 ${artifact}`;
-	}
+function hasSuccessfulEvidenceEntry(cwd: string, run: ActiveRun, artifact: string): boolean {
+	const normalized = artifact.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+	const entry = readEvidenceIndex(cwd, run).entries.find((item) => typeof item.path === "string" && item.path.replace(/\\/g, "/") === normalized);
+	return Boolean(entry && entry.exitCode === 0);
 }
 
 function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {

package/src/harness/messages.ts

@@ -0,0 +1,113 @@
+import type { KdPhase } from "./types.ts";
+import { PHASE_ARTIFACTS } from "./types.ts";
+
+export function unknownProductReason(declaration: boolean | undefined): string {
+	if (declaration === undefined) {
+		return "不能进入 execute：产品画像未知，且 PLAN.md 未明确声明是否涉及产品实现、构建、元数据或 SDK 查证。下一步：先由当前需求和项目计划判断该范围；如果涉及产品实现，执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果不涉及，在 PLAN.md 的“产品实现范围”写明“不涉及”及依据。";
+	}
+	return "不能进入 execute：PLAN.md 声明涉及产品实现、构建、元数据或 SDK 查证，但产品画像未知。下一步：根据需求、计划或用户回答确认产品，然后执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。";
+}
+
+export function unknownRiskReason(): string {
+	return "不能进入 ship：风险等级或风险原因未知。下一步：根据 VERIFY.md 和 SHIP.md 的残余风险执行 /kd-risk <low|medium|high> <原因>，或在风险章节写入真实风险说明后再刷新门禁。";
+}
+
+export function openQuestionsReason(questions: Array<{ id: string; question: string }>): string {
+	return [
+		`存在未回答的阻断问题：${questions.map((question) => `${question.id} ${question.question}`).join("；")}`,
+		"下一步：先获取用户答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录。",
+	].join("。");
+}
+
+export function missingMarkerReason(phase: KdPhase, missing: string[]): string {
+	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}。下一步：更新 ${PHASE_ARTIFACTS[phase]}，补齐这些章节并写入真实内容。`;
+}
+
+export function missingArtifactsReason(artifacts: string[]): string {
+	return [
+		`缺少必需产物：${artifacts.join(", ")}`,
+		`下一步：使用 /kd-artifact <阶段> 创建或更新阶段文档，或按当前阶段要求补写 ${artifacts.join(", ")} 的真实内容后再刷新门禁。`,
+	].join("。");
+}
+
+export function missingForTargetReason(target: KdPhase, artifacts: string[]): string {
+	const evidence = artifacts.filter((artifact) => artifact.startsWith("evidence/"));
+	const documents = artifacts.filter((artifact) => !artifact.startsWith("evidence/"));
+	const actions: string[] = [];
+	if (documents.length > 0) {
+		actions.push(`先补齐阶段文档 ${documents.join(", ")}，可用 /kd-artifact 创建模板后填入真实分析、计划或验证内容`);
+	}
+	if (evidence.length > 0) {
+		actions.push(evidenceAction(evidence));
+	}
+	return `不能进入 ${target}：缺少 ${artifacts.join(", ")}。下一步：${actions.join("；")}。`;
+}
+
+export function missingEvidenceReason(artifacts: string[]): string {
+	return `缺少必需证据：${artifacts.join(", ")}。下一步：${evidenceAction(artifacts)}。`;
+}
+
+export function evidenceAction(artifacts: string[]): string {
+	return artifacts.map(evidenceArtifactAction).join("；");
+}
+
+export function evidenceArtifactAction(artifact: string): string {
+	switch (artifact) {
+		case "evidence/sdk-signature.md":
+			return "运行 kd_sdk_signature，从当前项目真实 SDK jar/dll 查证类、方法、构造器或属性签名，成功后自动写入 evidence/sdk-signature.md";
+		case "evidence/cosmic-config.txt":
+			return "运行 kd_cosmic_config 生成 evidence/cosmic-config.txt；如果项目没有 ok-cosmic.json，先使用 KCode 默认配置";
+		case "evidence/cosmic-metadata.json":
+			return "运行 kd_cosmic_metadata 查询目标表单/单据/字段元数据并生成 evidence/cosmic-metadata.json";
+		case "evidence/cosmic-api.txt":
+			return "运行 kd_cosmic_api 查询相关 Cosmic API 线索并生成 evidence/cosmic-api.txt，再用 kd_sdk_signature 或构建输出确认签名";
+		case "evidence/ksql-lint.txt":
+			return "运行 kd_ksql_lint 校验 KSQL/SQL 交付内容并生成 evidence/ksql-lint.txt";
+		default:
+			return `运行 PLAN.md 中声明的验证命令，记录命令、Exit、STDOUT/STDERR 或工具输出到 ${artifact}`;
+	}
+}
+
+export function flagshipWriteBlockedReason(path: string): string {
+	return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：先读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
+}
+
+export function planWriteBlockedReason(path: string): string {
+	return `PLAN.md 未批准写入 ${path}。下一步：停止写入该文件，回到 plan 阶段检查项目结构和影响范围，把该文件加入 PLAN.md 的 ## 允许修改的文件 和执行步骤；重新通过门禁后再写。`;
+}
+
+export function flagshipPlanNeedsCodePathReason(): string {
+	return "不能进入 execute：星空旗舰版 PLAN.md 需要先记录当前项目 code/ 下的实际目标路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
+}
+
+export function flagshipPlanNeedsSourcePathReason(): string {
+	return "不能进入 execute：PLAN.md 需要先记录已检查当前项目结构，并写明实际源码根或目标文件路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
+}
+
+export function tddPlanMissingReason(): string {
+	return "PLAN.md 缺少 ## TDD / 红绿检查。下一步：回到 plan 补充该章节，明确红灯证据、绿灯证据、验证命令或无法自动化时的产品验证替代方案；至少写明 evidence/tdd-red.md、evidence/tdd-green.md 和要运行的真实检查。";
+}
+
+export function tddProductionMissingRedReason(path: string, evidenceName: string): string {
+	return `不能写生产源码 ${path}：缺少红灯证据 ${evidenceName}。下一步：先运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
+}
+
+export function tddVerifyBlockedReason(reasons: string[]): string {
+	return [
+		`不能进入 verify：${reasons.join("；")}。`,
+		"修复方式：重新运行 PLAN.md 中声明的同一验证命令或等价的产品验证命令，",
+		"并把命令、Exit、STDOUT/STDERR 或明确的工具输出写入对应 evidence 文件。",
+	].join("");
+}
+
+export function redEvidenceInvalidReason(evidenceName: string): string {
+	return `${evidenceName} 内容无效：需要包含真实失败输出或非 0 退出码`;
+}
+
+export function greenEvidenceInvalidReason(evidenceName: string): string {
+	return `${evidenceName} 内容无效：绿灯证据需要同时包含成功结论和 Exit: 0/退出码：0`;
+}
+
+export function sdkSignatureWriteBlockedReason(path: string, evidenceName: string): string {
+	return `不能写生产源码 ${path}：缺少本地 SDK 签名证据 ${evidenceName}。下一步：运行 kd_sdk_signature，从当前项目真实 jar/dll 查证即将使用的 SDK 类、方法、构造器或属性签名；成功生成 evidence/sdk-signature.md 后再写代码。禁止凭记忆或随包知识库猜 SDK API。`;
+}

package/src/harness/path-policy.ts

@@ -1,6 +1,12 @@
 import type { ActiveRun } from "./types.ts";
 import { existsSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
+import {
+	flagshipPlanNeedsCodePathReason,
+	flagshipPlanNeedsSourcePathReason,
+	flagshipWriteBlockedReason,
+	planWriteBlockedReason,
+} from "./messages.ts";
 
 const SOURCE_EXTENSIONS = new Set([
 	".java",
@@ -23,7 +29,7 @@ export function flagshipWriteBlockReason(run: ActiveRun | undefined, path: strin
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (cwd && !hasWorkspaceCodeDir(cwd)) return undefined;
 	if (!normalized.startsWith("code/")) {
-		return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：先读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
+		return flagshipWriteBlockedReason(path);
 	}
 
 	return undefined;
@@ -37,7 +43,7 @@ export function planWriteBlockReason(cwd: string, run: ActiveRun | undefined, pa
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (planMentionsPath(plan, normalized)) return undefined;
 
-	return `PLAN.md 未批准写入 ${normalized}。下一步：停止写入该文件，回到 plan 阶段检查项目结构和影响范围，把该文件加入 PLAN.md 的 ## 允许修改的文件 和执行步骤；重新通过门禁后再写。`;
+	return planWriteBlockedReason(normalized);
 }
 
 export function flagshipPlanBlockReason(cwd: string, run: ActiveRun | undefined, plan: string): string | undefined {
@@ -45,11 +51,11 @@ export function flagshipPlanBlockReason(cwd: string, run: ActiveRun | undefined,
 
 	if (hasWorkspaceCodeDir(cwd)) {
 		if (/(?:^|[\s`"'(])code[\\/][^\s`"')]+/i.test(plan)) return undefined;
-		return "不能进入 execute：星空旗舰版 PLAN.md 必须先记录当前项目 code/ 下的实际目标路径；不要按固定模块规则猜路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
+		return flagshipPlanNeedsCodePathReason();
 	}
 
 	if (planMentionsDiscoveredSourcePath(plan)) return undefined;
-	return "不能进入 execute：PLAN.md 必须先记录已检查当前项目结构，并写明实际源码根或目标文件路径；当前项目没有 code/ 时更不能猜路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
+	return flagshipPlanNeedsSourcePathReason();
 }
 
 function hasWorkspaceCodeDir(cwd: string): boolean {

package/src/harness/prompt.ts

@@ -0,0 +1,68 @@
+import { readProjectContext } from "../context/project-context.ts";
+import { readArtifact } from "./artifacts.ts";
+import { formatStatus } from "./format.ts";
+import type { ActiveRun, KdPhase } from "./types.ts";
+import { PHASE_ORDER } from "./types.ts";
+
+export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: string): string {
+	const status = formatStatus(cwd, run);
+	const memory = workflowMemoryForRun(cwd, run);
+	const phaseGuidance = phaseGuidanceForRun(run.phase);
+	const projectContext = readProjectContext(cwd);
+
+	return [
+		"用户输入：",
+		userText,
+		"",
+		"KCode Harness 状态：",
+		status,
+		"",
+		"KCode 阶段资料：",
+		memory,
+		"",
+		"项目上下文：",
+		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。需要项目结构时先运行或提示用户运行 `kcode context --refresh`。",
+		"",
+		"当前阶段任务：",
+		phaseGuidance,
+		"",
+		"核心约束：",
+		"- 产品代码只在 execute 阶段写入，并限于 PLAN.md 批准的文件。",
+		"- Java/C# SDK 签名以当前项目 jar/dll、构建输出或官方元数据为准。",
+		"- Java/Cosmic 用当前项目 Gradle；C#/企业版用 dotnet build。",
+		"- evidence 记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
+		"- Windows 下优先使用项目相对路径；绝对路径使用 D:\\... 形式。",
+	].join("\n");
+}
+
+function phaseGuidanceForRun(phase: KdPhase): string {
+	const guidance: Record<KdPhase, string> = {
+		discuss: "梳理需求来源、范围、已知事实和一个最阻塞的待确认问题。",
+		spec: "把需求转成验收标准、数据对象、异常行为、依赖和风险。",
+		plan: "检查项目结构，写明目标路径、允许修改文件、查证项、验证命令和回滚说明。",
+		execute: "按 PLAN.md 实现，记录步骤结果、变更文件和 evidence。",
+		verify: "运行计划中的验证命令，更新 VERIFY.md、证据和残余风险。",
+		ship: "整理 SHIP.md，包括摘要、验证证据、风险和后续事项。",
+	};
+	return guidance[phase];
+}
+
+function workflowMemoryForRun(cwd: string, run: ActiveRun): string {
+	const currentIndex = PHASE_ORDER.indexOf(run.phase);
+	const phases = PHASE_ORDER.slice(Math.max(0, currentIndex - 1), currentIndex + 1);
+	return (
+		phases
+			.map((phase) => {
+				const content = readArtifact(cwd, run, phase);
+				if (!content) return undefined;
+				return [`## ${phase}`, trimForPrompt(content, 1500)].join("\n");
+			})
+			.filter(Boolean)
+			.join("\n\n") || `阶段文档路径：.pi/kd/runs/${run.id}/`
+	);
+}
+
+function trimForPrompt(content: string, maxLength: number): string {
+	if (content.length <= maxLength) return content;
+	return `${content.slice(0, maxLength)}\n\n[...已截断；需要完整内容时读取本地文件...]`;
+}

package/src/harness/sdk-policy.ts

@@ -4,6 +4,7 @@ import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
 import { isSourceLikePath } from "./path-policy.ts";
 import { hasEvidenceEntry } from "./evidence.ts";
+import { sdkSignatureWriteBlockedReason } from "./messages.ts";
 
 export const SDK_SIGNATURE_EVIDENCE = "evidence/sdk-signature.md";
 
@@ -31,7 +32,7 @@ export function sdkSignatureProductionWriteBlockReason(cwd: string, run: ActiveR
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (hasValidSdkSignatureEvidence(cwd, run)) return undefined;
 
-	return `不能写生产源码 ${normalized}：缺少本地 SDK 签名证据 ${SDK_SIGNATURE_EVIDENCE}。下一步：运行 kd_sdk_signature，从当前项目真实 jar/dll 查证即将使用的 SDK 类、方法、构造器或属性签名；成功生成 evidence/sdk-signature.md 后再写代码。禁止凭记忆或随包知识库猜 SDK API。`;
+	return sdkSignatureWriteBlockedReason(normalized, SDK_SIGNATURE_EVIDENCE);
 }
 
 function normalizeRelativePath(path: string): string {

package/src/harness/state.ts

@@ -100,7 +100,7 @@ export function addQuestion(
 	run: ActiveRun,
 	input: { question: string; reason?: string; choices?: string[]; blocking?: boolean },
 ): KdQuestion {
-	const existing = run.questions ?? [];
+	const existing = Array.isArray(run.questions) ? run.questions : [];
 	const question: KdQuestion = {
 		id: createQuestionId(existing.length + 1),
 		phase: run.phase,
@@ -118,7 +118,7 @@ export function addQuestion(
 }
 
 export function answerQuestion(cwd: string, run: ActiveRun, id: string, answer: string): KdQuestion | undefined {
-	const question = (run.questions ?? []).find((item) => item.id === id);
+	const question = (Array.isArray(run.questions) ? run.questions : []).find((item) => item.id === id);
 	if (!question) return undefined;
 	question.status = "answered";
 	question.answer = answer.trim();
@@ -129,7 +129,7 @@ export function answerQuestion(cwd: string, run: ActiveRun, id: string, answer:
 }
 
 export function openBlockingQuestions(run: ActiveRun): KdQuestion[] {
-	return (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+	return (Array.isArray(run.questions) ? run.questions : []).filter((question) => question.status === "open" && question.blocking);
 }
 
 export function updateProductProfile(cwd: string, run: ActiveRun, productInput: string, version?: string): ActiveRun {
@@ -189,6 +189,21 @@ export function advanceRun(cwd: string, run: ActiveRun, requestedPhase?: KdPhase
 	return { run, message: `已推进 Kingdee run 到阶段：${target}` };
 }
 
+export function advanceRunIfReady(cwd: string, run: ActiveRun): { run: ActiveRun; advanced: boolean; message: string } {
+	const current = readRun(cwd, run.id) ?? run;
+	const target = nextPhase(current.phase);
+	if (!target) {
+		return { run: current, advanced: false, message: `Run 已处于最终阶段：${current.phase}` };
+	}
+
+	const result = advanceRun(cwd, current, target);
+	return {
+		run: result.run,
+		advanced: result.run.phase === target,
+		message: result.message,
+	};
+}
+
 export function refreshGate(cwd: string, run: ActiveRun): ActiveRun {
 	run.gate = inspectGate(cwd, run);
 	writeActiveRun(cwd, run);
@@ -202,19 +217,75 @@ function writeRunState(cwd: string, run: ActiveRun): void {
 }
 
 function hydrateRun(parsed: ActiveRun): ActiveRun | undefined {
-	if (!parsed.id || !isKdPhase(parsed.phase)) return undefined;
-	parsed.artifacts ??= {};
-	parsed.questions ??= [];
-	parsed.status ??= "active";
-	parsed.createdAt ??= parsed.updatedAt;
-	parsed.updatedAt ??= parsed.createdAt;
+	if (!parsed || typeof parsed !== "object") return undefined;
+	if (typeof parsed.id !== "string" || !parsed.id.trim()) return undefined;
+	if (typeof parsed.phase !== "string" || !isKdPhase(parsed.phase)) return undefined;
+	parsed.id = parsed.id.trim();
+	parsed.artifacts = isPlainObject(parsed.artifacts) ? sanitizeArtifacts(parsed.artifacts) : {};
+	parsed.questions = Array.isArray(parsed.questions) ? parsed.questions.map(sanitizeQuestion).filter((question): question is KdQuestion => Boolean(question)) : [];
+	parsed.status = parsed.status === "paused" || parsed.status === "done" ? parsed.status : "active";
+	parsed.goal = typeof parsed.goal === "string" ? parsed.goal : undefined;
+	parsed.version = typeof parsed.version === "string" ? parsed.version : undefined;
+	parsed.createdAt = typeof parsed.createdAt === "string" ? parsed.createdAt : typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined;
+	parsed.updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : parsed.createdAt;
 	const legacyEdition = (parsed as ActiveRun & { edition?: string }).edition;
-	parsed.profile = parsed.profile ?? profileForProduct(parsed.product ?? resolveProductProfile(legacyEdition).product);
+	const product = typeof parsed.profile?.product === "string" ? parsed.profile.product : typeof parsed.product === "string" ? parsed.product : resolveProductProfile(typeof legacyEdition === "string" ? legacyEdition : undefined).product;
+	parsed.profile = profileForProduct(product);
 	parsed.product = parsed.profile.product;
-	parsed.gate ??= { passed: false, checkedAt: new Date().toISOString() };
+	parsed.riskAssessment = sanitizeRiskAssessment(parsed.riskAssessment);
+	parsed.gate = sanitizeGate(parsed.gate);
 	return parsed;
 }
 
+function sanitizeArtifacts(value: Record<string, unknown>): Record<string, string> {
+	return Object.fromEntries(Object.entries(value).filter((entry): entry is [string, string] => typeof entry[0] === "string" && typeof entry[1] === "string"));
+}
+
+function sanitizeQuestion(value: unknown): KdQuestion | undefined {
+	if (!isPlainObject(value)) return undefined;
+	const phase = typeof value.phase === "string" && isKdPhase(value.phase) ? value.phase : undefined;
+	const question = typeof value.question === "string" ? value.question.trim() : "";
+	if (!phase || !question) return undefined;
+	const id = typeof value.id === "string" && value.id.trim() ? value.id.trim() : createQuestionId(1);
+	return {
+		id,
+		phase,
+		question,
+		reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+		choices: Array.isArray(value.choices) ? value.choices.filter((choice): choice is string => typeof choice === "string" && Boolean(choice.trim())).map((choice) => choice.trim()) : undefined,
+		blocking: value.blocking !== false,
+		status: value.status === "answered" ? "answered" : "open",
+		answer: typeof value.answer === "string" ? value.answer : undefined,
+		createdAt: typeof value.createdAt === "string" ? value.createdAt : new Date().toISOString(),
+		answeredAt: typeof value.answeredAt === "string" ? value.answeredAt : undefined,
+	};
+}
+
+function sanitizeRiskAssessment(value: unknown): ActiveRun["riskAssessment"] {
+	if (!isPlainObject(value)) return undefined;
+	const level = value.level;
+	if (level !== "low" && level !== "medium" && level !== "high") return undefined;
+	return {
+		level,
+		reason: typeof value.reason === "string" ? value.reason : "",
+		source: value.source === "verify" || value.source === "ship" ? value.source : "manual",
+		updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString(),
+	};
+}
+
+function sanitizeGate(value: unknown): ActiveRun["gate"] {
+	if (!isPlainObject(value)) return { passed: false, checkedAt: new Date().toISOString() };
+	return {
+		passed: value.passed === true,
+		reason: typeof value.reason === "string" ? value.reason : undefined,
+		checkedAt: typeof value.checkedAt === "string" ? value.checkedAt : new Date().toISOString(),
+	};
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function createRunId(goal: string): string {
 	const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
 	const slug = goal

package/src/harness/tdd-policy.ts

@@ -4,13 +4,20 @@ import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
 import { isSourceLikePath } from "./path-policy.ts";
 import { hasEvidenceEntry } from "./evidence.ts";
+import {
+	greenEvidenceInvalidReason,
+	redEvidenceInvalidReason,
+	tddPlanMissingReason,
+	tddProductionMissingRedReason,
+	tddVerifyBlockedReason,
+} from "./messages.ts";
 
 export const TDD_RED_EVIDENCE = "evidence/tdd-red.md";
 export const TDD_GREEN_EVIDENCE = "evidence/tdd-green.md";
 
 export function tddPlanBlockReason(plan: string): string | undefined {
 	if (/##\s*TDD\s*\/\s*红绿检查/i.test(plan)) return undefined;
-	return "PLAN.md 缺少 ## TDD / 红绿检查。下一步：回到 plan 补充该章节，明确红灯证据、绿灯证据、验证命令或无法自动化时的产品验证替代方案；至少写明 evidence/tdd-red.md、evidence/tdd-green.md 和要运行的真实检查。";
+	return tddPlanMissingReason();
 }
 
 export function tddProductionWriteBlockReason(cwd: string, run: ActiveRun | undefined, path: string | undefined): string | undefined {
@@ -22,7 +29,7 @@ export function tddProductionWriteBlockReason(cwd: string, run: ActiveRun | unde
 	if (isTestLikePath(normalized)) return undefined;
 	if (hasValidTddEvidence(cwd, run, "red")) return undefined;
 
-	return `不能写生产源码 ${normalized}：缺少红灯证据 ${TDD_RED_EVIDENCE}。下一步：先运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
+	return tddProductionMissingRedReason(normalized, TDD_RED_EVIDENCE);
 }
 
 export function tddVerifyBlockReason(cwd: string, run: ActiveRun): string | undefined {
@@ -31,11 +38,7 @@ export function tddVerifyBlockReason(cwd: string, run: ActiveRun): string | unde
 		validateTddEvidence(cwd, run, "green"),
 	].filter((result) => !result.valid);
 	if (problems.length === 0) return undefined;
-	return [
-		`不能进入 verify：${problems.map((problem) => problem.reason).join("；")}。`,
-		"修复方式：不要反复修改 evidence 文案；必须重新运行 PLAN.md 中声明的同一验证命令或等价的产品验证命令，",
-		"并把命令、Exit、STDOUT/STDERR 或明确的工具输出写入对应 evidence 文件。",
-	].join("");
+	return tddVerifyBlockedReason(problems.map((problem) => problem.reason ?? "未知 TDD evidence 问题"));
 }
 
 function hasValidTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green"): boolean {
@@ -58,7 +61,7 @@ function validateTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green")
 		const hasFailure = /red|fail|failed|failure|error|失败|未通过|Exit\s*[：:]\s*[1-9]/i.test(content);
 		return hasFailure
 			? { valid: true }
-			: { valid: false, reason: `${evidenceName} 内容无效：必须包含真实失败输出或非 0 退出码，不能只写结论` };
+			: { valid: false, reason: redEvidenceInvalidReason(evidenceName) };
 	}
 
 	const hasGreenExit = /Exit\s*[：:]\s*0|退出码\s*[：:]\s*0/i.test(content);
@@ -67,7 +70,7 @@ function validateTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green")
 
 	return {
 		valid: false,
-		reason: `${evidenceName} 内容无效：绿灯证据必须同时包含成功结论和 Exit: 0/退出码：0，不能只写“通过”或人工结论`,
+		reason: greenEvidenceInvalidReason(evidenceName),
 	};
 }