kcode-pi 0.1.18 → 0.1.20

package/README.md

@@ -293,6 +293,7 @@ kcode start --provider openai --model gpt-4o
 ```text
 /kd-start [--product 产品] [--version 版本] <需求>
 /kd-product <产品> [--version 版本]
+/kd-risk <low|medium|high> <原因>
 /kd-status
 /kd-runs
 /kd-switch <run-id>
@@ -300,7 +301,7 @@ kcode start --provider openai --model gpt-4o
 /kd-finish
 /kd-gate
 /kd-advance [阶段]
-/kd-artifact [阶段] [内容]
+/kd-artifact [阶段] [内容] [--replace]
 /kd-answer Q-001 <答案>
 ```
 
@@ -312,6 +313,14 @@ kcode start --provider openai --model gpt-4o
 
 `/kd-start` 会创建新的功能点 run，并立即触发 Agent 进入 `discuss` 阶段。如果未识别出产品画像，例如显示 `(unknown/unknown)`，下一步应先确认产品、版本和技术栈，而不是直接写代码。
 
+进入 `ship` 前必须确认风险等级：
+
+```text
+/kd-risk low 已完成本地构建和元数据检查，无残余交付风险
+```
+
+`/kd-artifact` 默认只创建缺失阶段文档。若阶段文档已存在，带内容调用不会直接覆盖；确认要整体替换时必须追加 `--replace`。
+
 暂停后接续：
 
 ```text
@@ -376,6 +385,7 @@ KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入
 .pi/kd/runs/<run-id>/VERIFY.md
 .pi/kd/runs/<run-id>/SHIP.md
 .pi/kd/runs/<run-id>/evidence/
+.pi/kd/runs/<run-id>/evidence/index.json
 ```
 
 下次重新 `kcode start` 时，KCode 会提示当前项目的 active run。执行 `/kd-resume` 后，KCode 会读取项目常驻上下文、active run 状态和已生成的阶段文档，再继续当前功能点的当前阶段。已完成或暂停的功能点仍保留在 `.pi/kd/runs/<run-id>/`，可用 `/kd-runs` 查看，用 `/kd-switch <run-id>` 切回。
@@ -403,6 +413,7 @@ ship     汇总变更、验证证据、风险和后续事项
 - 写生产源码前必须已有 `evidence/tdd-red.md`，内容可以是 API/基类/方法签名检查、元数据检查、编译检查、既有测试框架或外部接口最小验证的失败输出。
 - 进入 `execute` 后，只允许写入 `PLAN.md` 明确列出的源码文件；如果临时发现要改新文件，必须先回到 plan 更新 `PLAN.md`。
 - 进入 `verify` 前，`EXECUTION.md` 必须逐个完成 `PLAN.md` 中的所有 `STEP-###`，并为每个步骤记录真实存在的 `evidence/...` 文件；同时必须已有 `evidence/tdd-red.md` 和 `evidence/tdd-green.md`。
+- evidence 文件必须登记在 `evidence/index.json` 中。KCode 内置工具和 evidence 写入路径会自动维护索引；不要手工塞文件绕过门禁。
 - `evidence/tdd-green.md` 必须包含真实成功输出和 `Exit: 0` 或 `退出码：0`；不能写“需在开发环境验证”“待验证”“未执行”等不确定结论。
 - 如果门禁提示 evidence 内容无效，不要反复改文案或补关键词；必须重新运行 `PLAN.md` 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。
 - Java / 苍穹 / 星空旗舰版的语法和编译验证优先使用当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`./gradlew build` 或 `.\gradlew.bat :模块:build`。

package/extensions/kingdee-harness.ts

@@ -15,7 +15,9 @@ import {
 	switchActiveRun,
 	updateProductProfile,
 	updatePhaseArtifact,
+	updateRisk,
 } from "../src/harness/state.ts";
+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";
@@ -30,18 +32,19 @@ function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
 }
 
-function parseArtifactArgs(args: string, currentPhase: KdPhase): { phase: KdPhase; content?: string } | undefined {
-	const trimmed = args.trim();
-	if (!trimmed) return { phase: currentPhase };
+function parseArtifactArgs(args: string, currentPhase: KdPhase): { phase: KdPhase; content?: string; replace: boolean } | undefined {
+	const replace = /\s*(^|\s)--replace(\s|$)/.test(args);
+	const trimmed = args.replace(/\s*(^|\s)--replace(?=\s|$)/g, " ").trim();
+	if (!trimmed) return { phase: currentPhase, replace };
 
 	const [first, ...rest] = trimmed.split(/\s+/);
 	if (isKdPhase(first)) {
 		const contentStart = trimmed.indexOf(first) + first.length;
 		const content = trimmed.slice(contentStart).trim();
-		return { phase: first, content: content || undefined };
+		return { phase: first, content: content || undefined, replace };
 	}
 
-	return { phase: currentPhase, content: trimmed };
+	return { phase: currentPhase, content: trimmed, replace };
 }
 
 function parseStartArgs(args: string): { goal: string; product?: string; version?: string } {
@@ -73,6 +76,15 @@ function parseProductArgs(args: string): { product: string; version?: string } |
 	return { product, version: parsed.version };
 }
 
+function parseRiskArgs(args: string): { risk: KdRisk; reason: string } | undefined {
+	const [first, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+	const risk = first?.toLowerCase();
+	if (risk !== "low" && risk !== "medium" && risk !== "high") return undefined;
+	const reason = rest.join(" ").trim();
+	if (!reason) return undefined;
+	return { risk, reason };
+}
+
 function shouldStartHarnessFromInput(text: string): boolean {
 	if (!text.trim() || text.trim().startsWith("/")) return false;
 	return KINGDEE_INTENT_PATTERN.test(text);
@@ -320,6 +332,9 @@ export default function (pi: ExtensionAPI) {
 			run = createActiveRun(ctx.cwd, event.text);
 			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|cosmic|xinghan|cangqiong|enterprise>。", "warning");
+				}
 			}
 		}
 
@@ -390,6 +405,9 @@ 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|cosmic|xinghan|cangqiong|enterprise>。", "warning");
+			}
 			sendWorkflowPrompt(pi, ctx, run, `继续 KCode Harness run ${run.id}：${goal}`);
 		},
 	});
@@ -467,6 +485,26 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("kd-risk", {
+		description: "设置当前 Kingdee run 风险等级：/kd-risk <low|medium|high> <原因>",
+		handler: async (args, ctx) => {
+			const run = requireRun(ctx.cwd);
+			if (!run) {
+				ctx.ui.notify("当前没有 active Kingdee Harness run。请使用 /kd-start <需求>。", "error");
+				return;
+			}
+
+			const risk = parseRiskArgs(args);
+			if (!risk) {
+				ctx.ui.notify("用法：/kd-risk <low|medium|high> <原因>", "error");
+				return;
+			}
+
+			const updated = updateRisk(ctx.cwd, run, risk.risk, risk.reason);
+			ctx.ui.notify(`风险等级：${updated.riskAssessment?.level}（${updated.riskAssessment?.reason}）`, "info");
+		},
+	});
+
 	pi.registerCommand("kd-advance", {
 		description: `推进 Kingdee run 到下一阶段，或指定阶段：${PHASE_ORDER.join("|")}`,
 		handler: async (args, ctx) => {
@@ -492,7 +530,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-artifact", {
-		description: "创建或更新阶段文档：/kd-artifact [阶段] [内容]",
+		description: "创建阶段文档，或显式覆盖阶段文档：/kd-artifact [阶段] [内容] [--replace]",
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
@@ -502,7 +540,12 @@ export default function (pi: ExtensionAPI) {
 
 			const parsed = parseArtifactArgs(args, run.phase);
 			if (!parsed) {
-				ctx.ui.notify("用法：/kd-artifact [阶段] [内容]", "error");
+				ctx.ui.notify("用法：/kd-artifact [阶段] [内容] [--replace]", "error");
+				return;
+			}
+
+			if (parsed.content && readArtifact(ctx.cwd, run, parsed.phase) !== undefined && !parsed.replace) {
+				ctx.ui.notify(`拒绝覆盖 ${parsed.phase} 阶段文档。若确认要整体替换，请追加 --replace；追加内容应让 Agent 更新具体章节。`, "warning");
 				return;
 			}
 

package/extensions/kingdee-header.ts

@@ -1,52 +1,33 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { inspectGate } from "../src/harness/gates.ts";
+import { readActiveRun } from "../src/harness/state.ts";
+import type { ActiveRun, GateResult } from "../src/harness/types.ts";
+import { formatProductProfile } from "../src/product/profile.ts";
 
-type KdPhase = "discuss" | "spec" | "plan" | "execute" | "verify" | "ship";
-
-interface ActiveRun {
-	id?: string;
-	phase?: KdPhase;
-	product?: string;
-	profile?: {
-		product?: string;
-		techStack?: string;
-		language?: string;
-	};
-	risk?: "low" | "medium" | "high";
-	gate?: {
-		passed?: boolean;
-		reason?: string;
-	};
+function formatProduct(run: ActiveRun | undefined): string {
+	if (!run) return "未选择";
+	if (run.profile?.product === "unknown") return "未确认";
+	return formatProductProfile(run.profile);
 }
 
-function readActiveRun(cwd: string): ActiveRun | undefined {
-	const activeRunPath = join(cwd, ".pi", "kd", "active-run.json");
-	if (!existsSync(activeRunPath)) return undefined;
-
-	try {
-		return JSON.parse(readFileSync(activeRunPath, "utf8")) as ActiveRun;
-	} catch {
-		return undefined;
-	}
+function formatPhase(phase: ActiveRun["phase"] | undefined): string {
+	return phase ?? "空闲";
 }
 
-function formatProduct(run: ActiveRun | undefined): string {
-	if (!run) return "未选择";
-	const product = run.profile?.product ?? run.product ?? "unknown";
-	const techStack = run.profile?.techStack ?? "unknown";
-	const language = run.profile?.language ?? "unknown";
-	return `${product}/${techStack}/${language}`;
+function formatGate(gate: GateResult | undefined): string {
+	if (!gate) return "门禁：待检查";
+	return gate.passed ? "门禁：通过" : "门禁：阻塞";
 }
 
-function formatPhase(phase: ActiveRun["phase"]): string {
-	return phase ?? "空闲";
+function riskLevel(run: ActiveRun | undefined): string {
+	return run?.riskAssessment?.level ?? "未知";
 }
 
-function formatGate(run: ActiveRun | undefined): string {
-	if (!run?.gate) return "门禁：待检查";
-	if (run.gate.passed) return "门禁：通过";
-	return `门禁：阻塞${run.gate.reason ? ` - ${run.gate.reason}` : ""}`;
+function riskColor(risk: string): "error" | "warning" | "muted" | "success" {
+	if (risk === "high") return "error";
+	if (risk === "medium") return "warning";
+	if (risk === "未知") return "muted";
+	return "success";
 }
 
 function padOrTrim(text: string, width: number): string {
@@ -73,10 +54,11 @@ export default function (pi: ExtensionAPI) {
 			return {
 				render(width: number): string[] {
 					const run = readActiveRun(ctx.cwd);
+					const gateState = run ? inspectGate(ctx.cwd, run) : undefined;
 					const phase = formatPhase(run?.phase);
 					const product = formatProduct(run);
-					const gate = formatGate(run);
-					const risk = run?.risk ?? "未知";
+					const gate = formatGate(gateState);
+					const risk = riskLevel(run);
 					const runId = run?.id ?? "无";
 
 					const status = [
@@ -85,9 +67,9 @@ export default function (pi: ExtensionAPI) {
 						theme.fg("muted", " | 产品："),
 						theme.fg("text", product),
 						theme.fg("muted", " | 风险："),
-						theme.fg(risk === "high" ? "error" : risk === "medium" ? "warning" : "success", risk),
+						theme.fg(riskColor(risk), risk),
 						theme.fg("muted", " | "),
-						theme.fg(run?.gate?.passed === false ? "error" : "muted", gate),
+						theme.fg(gateState?.passed === false ? "error" : "muted", gate),
 					].join("");
 
 					return [

package/extensions/kingdee-tools.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatSearchResults, formatTableSchema } from "../src/knowledge/format.ts";
@@ -23,7 +23,7 @@ import {
 } from "../src/official/kingdee-skills.ts";
 import { resolveWorkspacePath } from "../src/platform/path.ts";
 import { readActiveRun } from "../src/harness/state.ts";
-import { runArtifactPath } from "../src/harness/paths.ts";
+import { writeEvidenceFile } from "../src/harness/evidence.ts";
 import { SDK_SIGNATURE_EVIDENCE } from "../src/harness/sdk-policy.ts";
 
 const extensionDir = dirname(fileURLToPath(import.meta.url));
@@ -433,10 +433,10 @@ function writeSdkSignatureEvidence(cwd: string, content: string): string | undef
 	const run = readActiveRun(cwd);
 	if (!run) return undefined;
 
-	const path = runArtifactPath(cwd, run, SDK_SIGNATURE_EVIDENCE);
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(
-		path,
+	return writeEvidenceFile(
+		cwd,
+		run,
+		SDK_SIGNATURE_EVIDENCE,
 		[
 			"# SDK 签名证据",
 			"",
@@ -448,7 +448,6 @@ function writeSdkSignatureEvidence(cwd: string, content: string): string | undef
 			"```",
 			"",
 		].join("\n"),
-		"utf8",
+		{ kind: "sdk-signature", command: "kd_sdk_signature", exitCode: 0 },
 	);
-	return path;
 }

package/package.json

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

package/src/harness/evidence.ts

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ActiveRun } from "./types.ts";
+import { runArtifactPath, runRoot } from "./paths.ts";
+
+export interface EvidenceEntry {
+	path: string;
+	kind: string;
+	command?: string;
+	exitCode?: number;
+	createdAt: string;
+	updatedAt: string;
+	size: number;
+}
+
+export interface EvidenceIndex {
+	version: 1;
+	entries: EvidenceEntry[];
+}
+
+export const EVIDENCE_INDEX = "evidence/index.json";
+
+export function evidenceIndexPath(cwd: string, run: ActiveRun): string {
+	return runArtifactPath(cwd, run, EVIDENCE_INDEX);
+}
+
+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: [] };
+	} catch {
+		return { version: 1, entries: [] };
+	}
+}
+
+export function hasEvidenceEntry(cwd: string, run: ActiveRun, path: string): boolean {
+	const normalized = normalizeEvidencePath(path);
+	return readEvidenceIndex(cwd, run).entries.some((entry) => normalizeEvidencePath(entry.path) === normalized);
+}
+
+export function writeEvidenceFile(
+	cwd: string,
+	run: ActiveRun,
+	path: string,
+	content: string,
+	options: { kind?: string; command?: string; exitCode?: number } = {},
+): string {
+	const normalized = normalizeEvidencePath(path);
+	if (!normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
+		throw new Error(`非法 evidence 路径：${path}`);
+	}
+
+	const absolutePath = runArtifactPath(cwd, run, normalized);
+	mkdirSync(dirname(absolutePath), { recursive: true });
+	writeFileSync(absolutePath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+	recordEvidence(cwd, run, normalized, options);
+	return absolutePath;
+}
+
+export function recordEvidence(
+	cwd: string,
+	run: ActiveRun,
+	path: string,
+	options: { kind?: string; command?: string; exitCode?: number } = {},
+): void {
+	const normalized = normalizeEvidencePath(path);
+	const absolutePath = join(runRoot(cwd, run), normalized);
+	if (!existsSync(absolutePath)) return;
+
+	const now = new Date().toISOString();
+	const size = statSync(absolutePath).size;
+	const index = readEvidenceIndex(cwd, run);
+	const existing = index.entries.find((entry) => normalizeEvidencePath(entry.path) === normalized);
+	if (existing) {
+		existing.kind = options.kind ?? existing.kind;
+		existing.command = options.command ?? existing.command;
+		existing.exitCode = options.exitCode ?? existing.exitCode;
+		existing.updatedAt = now;
+		existing.size = size;
+	} else {
+		index.entries.push({
+			path: normalized,
+			kind: options.kind ?? inferKind(normalized),
+			command: options.command,
+			exitCode: options.exitCode,
+			createdAt: now,
+			updatedAt: now,
+			size,
+		});
+	}
+
+	const indexPath = evidenceIndexPath(cwd, run);
+	mkdirSync(dirname(indexPath), { recursive: true });
+	writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, "utf8");
+}
+
+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(/^\.\//, "");
+}

package/src/harness/format.ts

@@ -21,7 +21,7 @@ export function formatStatus(cwd: string, run: ActiveRun | undefined): string {
 		`下一阶段：${next}`,
 		`产品：${formatProductProfile(refreshed.profile)}`,
 		`版本：${refreshed.version ?? "未选择"}`,
-		`风险：${refreshed.risk ?? "未知"}`,
+		`风险：${formatRisk(refreshed)}`,
 		`门禁：${refreshed.gate.passed ? "通过" : "阻塞"}`,
 		refreshed.gate.reason ? `原因：${refreshed.gate.reason}` : undefined,
 		"",
@@ -30,3 +30,9 @@ export function formatStatus(cwd: string, run: ActiveRun | undefined): string {
 		.filter(Boolean)
 		.join("\n");
 }
+
+function formatRisk(run: ActiveRun): string {
+	const level = run.riskAssessment?.level ?? "未知";
+	const reason = run.riskAssessment?.reason?.trim();
+	return reason ? `${level}（${reason}）` : level;
+}

package/src/harness/gates.ts

@@ -9,6 +9,7 @@ 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";
 
 const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
 	plan: ["## 验证命令"],
@@ -21,77 +22,79 @@ const COSMIC_METADATA_EVIDENCE = "evidence/cosmic-metadata.json";
 const COSMIC_API_EVIDENCE = "evidence/cosmic-api.txt";
 const KSQL_LINT_EVIDENCE = "evidence/ksql-lint.txt";
 
-export function inspectGate(cwd: string, run: ActiveRun): GateResult {
-	const currentIndex = PHASE_ORDER.indexOf(run.phase);
-	const missing: string[] = [];
-
-	for (let i = 0; i <= currentIndex; i++) {
-		const phase = PHASE_ORDER[i];
-		const artifact = PHASE_ARTIFACTS[phase];
-		if (!artifactExists(cwd, run, artifact)) missing.push(artifact);
-	}
+type GateMode = "inspect" | "enter";
 
-	const markerProblem = inspectMarkers(cwd, run, run.phase);
-	const stepProblem = inspectStepState(cwd, run, run.phase);
-	const evidenceProblem = inspectEvidence(cwd, run, run.phase);
-	const questionProblem = inspectOpenQuestions(run);
-	const reasonParts = [];
-	if (missing.length > 0) reasonParts.push(missingArtifactsReason([...new Set(missing)]));
-	if (markerProblem) reasonParts.push(markerProblem);
-	if (stepProblem) reasonParts.push(stepProblem);
-	if (evidenceProblem) reasonParts.push(evidenceProblem);
-	if (questionProblem) reasonParts.push(questionProblem);
-
-	return {
-		passed: reasonParts.length === 0,
-		reason: reasonParts.length > 0 ? reasonParts.join("; ") : undefined,
-		checkedAt: new Date().toISOString(),
-	};
+export function inspectGate(cwd: string, run: ActiveRun): GateResult {
+	return gateResult(collectGateProblems(cwd, run, run.phase, "inspect"));
 }
 
 export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): GateResult {
-	const targetIndex = PHASE_ORDER.indexOf(target);
+	return gateResult(collectGateProblems(cwd, run, target, "enter"));
+}
+
+function collectGateProblems(cwd: string, run: ActiveRun, phase: KdPhase, mode: GateMode): string[] {
+	const phaseIndex = PHASE_ORDER.indexOf(phase);
 	const missing: string[] = [];
 	const reasonParts: string[] = [];
 
-	if (target !== "discuss" && !isKnownProduct(run.profile?.product ?? run.product)) {
-		reasonParts.push(
-			"不能离开 discuss：产品画像未知。下一步：根据需求或用户回答确认产品，然后执行 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。",
-		);
+	if (phase !== "discuss" && !isKnownProduct(run.profile?.product ?? run.product)) {
+		reasonParts.push(unknownProductReason());
 	}
 
-	for (let i = 0; i < targetIndex; i++) {
-		const phase = PHASE_ORDER[i];
-		const artifact = PHASE_ARTIFACTS[phase];
+	if (phaseIndex >= PHASE_ORDER.indexOf("ship") && !hasRiskAssessment(cwd, run)) {
+		reasonParts.push(unknownRiskReason());
+	}
+
+	const lastRequiredArtifactIndex = mode === "inspect" ? phaseIndex : phaseIndex - 1;
+	for (let i = 0; i <= lastRequiredArtifactIndex; i++) {
+		const requiredPhase = PHASE_ORDER[i];
+		const artifact = PHASE_ARTIFACTS[requiredPhase];
 		if (!artifactExists(cwd, run, artifact)) missing.push(artifact);
 	}
 
-	if (target === "execute" && !artifactExists(cwd, run, PHASE_ARTIFACTS.plan)) {
+	if (mode === "enter" && phase === "execute" && !artifactExists(cwd, run, PHASE_ARTIFACTS.plan)) {
 		missing.push(PHASE_ARTIFACTS.plan);
 	}
 
-	const flagshipPathProblem = target === "execute" ? flagshipPlanBlockReason(cwd, run, readArtifact(cwd, run, "plan") ?? "") : undefined;
+	const markerProblem = mode === "inspect" ? inspectMarkers(cwd, run, phase) : undefined;
+	const flagshipPathProblem = mode === "enter" && phase === "execute" ? flagshipPlanBlockReason(cwd, run, readArtifact(cwd, run, "plan") ?? "") : undefined;
+	const stepProblem = inspectStepState(cwd, run, phase);
+	const evidenceProblem = mode === "inspect" ? inspectEvidence(cwd, run, phase) : undefined;
+	const questionProblem = inspectOpenQuestions(run);
+
 	if (flagshipPathProblem) {
 		reasonParts.push(flagshipPathProblem);
 	}
-
-	const stepProblem = inspectStepState(cwd, run, target);
+	if (markerProblem) {
+		reasonParts.push(markerProblem);
+	}
 	if (stepProblem) {
 		reasonParts.push(stepProblem);
 	}
-
-	const questionProblem = inspectOpenQuestions(run);
+	if (evidenceProblem) {
+		reasonParts.push(evidenceProblem);
+	}
 	if (questionProblem) {
 		reasonParts.push(questionProblem);
 	}
 
-	missing.push(...missingEvidenceForPhase(cwd, run, target));
+	if (mode === "enter") {
+		missing.push(...missingEvidenceForPhase(cwd, run, phase));
 
-	if (target === "ship" && !artifactExists(cwd, run, PHASE_ARTIFACTS.verify)) {
-		missing.push(PHASE_ARTIFACTS.verify);
+		if (phase === "ship" && !artifactExists(cwd, run, PHASE_ARTIFACTS.verify)) {
+			missing.push(PHASE_ARTIFACTS.verify);
+		}
+	}
+
+	if (missing.length > 0) {
+		const uniqueMissing = [...new Set(missing)];
+		reasonParts.push(mode === "inspect" ? missingArtifactsReason(uniqueMissing) : missingForTargetReason(phase, uniqueMissing));
 	}
 
-	if (missing.length > 0) reasonParts.push(missingForTargetReason(target, [...new Set(missing)]));
+	return reasonParts;
+}
+
+function gateResult(reasonParts: string[]): GateResult {
 	const reason = reasonParts.length > 0 ? reasonParts.join("; ") : undefined;
 	return {
 		passed: !reason,
@@ -100,6 +103,30 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 	};
 }
 
+function unknownProductReason(): string {
+	return "不能离开 discuss：产品画像未知。下一步：根据需求或用户回答确认产品，然后执行 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。";
+}
+
+function hasRiskAssessment(cwd: string, run: ActiveRun): boolean {
+	const level = run.riskAssessment?.level;
+	if (!level) return false;
+	if (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;
+	return match[2]
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.some((line) => line && !/^[-*]?\s*(无|未知|待确认|待补充|none|unknown)$/i.test(line));
+}
+
 function inspectOpenQuestions(run: ActiveRun): string | undefined {
 	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
 	if (open.length === 0) return undefined;
@@ -172,7 +199,8 @@ 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);
-	return existsSync(join(runRoot(cwd, run), artifact));
+	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 {

package/src/harness/plan-steps.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
+import { hasEvidenceEntry } from "./evidence.ts";
 
 export interface PlanStep {
 	id: string;
@@ -49,7 +50,7 @@ export function executionStepsBlockReason(cwd: string, run: ActiveRun, plan: str
 		}
 
 		const evidencePaths = [...line.matchAll(EVIDENCE_PATTERN)].map((match) => normalizeEvidencePath(match[0]));
-		if (evidencePaths.length === 0 || !evidencePaths.some((path) => existsSync(join(runRoot(cwd, run), path)))) {
+		if (evidencePaths.length === 0 || !evidencePaths.some((path) => existsSync(join(runRoot(cwd, run), path)) && hasEvidenceEntry(cwd, run, path))) {
 			missingEvidence.push(step.id);
 		}
 	}

package/src/harness/sdk-policy.ts

@@ -3,6 +3,7 @@ import { isAbsolute, join, relative } from "node:path";
 import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
 import { isSourceLikePath } from "./path-policy.ts";
+import { hasEvidenceEntry } from "./evidence.ts";
 
 export const SDK_SIGNATURE_EVIDENCE = "evidence/sdk-signature.md";
 
@@ -15,6 +16,7 @@ export function hasValidSdkSignatureEvidence(cwd: string, run: ActiveRun): boole
 	if (!requiresSdkSignatureEvidence(run)) return true;
 	const path = join(runRoot(cwd, run), SDK_SIGNATURE_EVIDENCE);
 	if (!existsSync(path)) return false;
+	if (!hasEvidenceEntry(cwd, run, SDK_SIGNATURE_EVIDENCE)) return false;
 
 	const content = readFileSync(path, "utf8");
 	return /(退出码|Exit)\s*[：:]\s*0/i.test(content) && /(来源|Sources?)\s*[：:]/i.test(content);

package/src/harness/state.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import type { ActiveRun, KdPhase, KdQuestion } from "./types.ts";
+import type { ActiveRun, KdPhase, KdQuestion, KdRisk, KdRiskSource } from "./types.ts";
 import { PHASE_ARTIFACTS, isKdPhase, nextPhase } from "./types.ts";
 import { activeRunPath, kdDir, runStatePath, runsDir } from "./paths.ts";
 import { defaultArtifactContent, ensureArtifact, ensureRunDirectories, writeArtifact } from "./artifacts.ts";
@@ -79,7 +79,6 @@ export function createActiveRun(cwd: string, goal: string, productInput?: string
 		product: profile.product,
 		version,
 		profile,
-		risk: "unknown",
 		artifacts: {},
 		questions: [],
 		gate: {
@@ -143,6 +142,18 @@ export function updateProductProfile(cwd: string, run: ActiveRun, productInput:
 	return run;
 }
 
+export function updateRisk(cwd: string, run: ActiveRun, risk: KdRisk, reason: string, source: KdRiskSource = "manual"): ActiveRun {
+	run.riskAssessment = {
+		level: risk,
+		reason: reason.trim(),
+		source,
+		updatedAt: new Date().toISOString(),
+	};
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return run;
+}
+
 export function ensurePhaseArtifact(cwd: string, run: ActiveRun, phase: KdPhase): string {
 	const path = ensureArtifact(cwd, run, phase, defaultArtifactContent(phase));
 	run.artifacts[phase] = PHASE_ARTIFACTS[phase];

package/src/harness/tdd-policy.ts

@@ -3,6 +3,7 @@ import { isAbsolute, join, relative } from "node:path";
 import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
 import { isSourceLikePath } from "./path-policy.ts";
+import { hasEvidenceEntry } from "./evidence.ts";
 
 export const TDD_RED_EVIDENCE = "evidence/tdd-red.md";
 export const TDD_GREEN_EVIDENCE = "evidence/tdd-green.md";
@@ -45,6 +46,7 @@ function validateTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green")
 	const evidenceName = kind === "red" ? TDD_RED_EVIDENCE : TDD_GREEN_EVIDENCE;
 	const evidencePath = join(runRoot(cwd, run), evidenceName);
 	if (!existsSync(evidencePath)) return { valid: false, reason: `缺少 ${evidenceName}` };
+	if (!hasEvidenceEntry(cwd, run, evidenceName)) return { valid: false, reason: `${evidenceName} 未登记到 evidence/index.json` };
 
 	const content = readFileSync(evidencePath, "utf8");
 	const uncertainty = uncertaintyReason(content);

package/src/harness/types.ts

@@ -1,8 +1,16 @@
 import type { KdProduct, ProductProfile } from "../product/profile.ts";
 
 export type KdPhase = "discuss" | "spec" | "plan" | "execute" | "verify" | "ship";
-export type KdRisk = "unknown" | "low" | "medium" | "high";
+export type KdRisk = "low" | "medium" | "high";
 export type KdRunStatus = "active" | "paused" | "done";
+export type KdRiskSource = "manual" | "verify" | "ship";
+
+export interface RiskAssessment {
+	level: KdRisk;
+	reason: string;
+	source: KdRiskSource;
+	updatedAt: string;
+}
 
 export interface GateResult {
 	passed: boolean;
@@ -34,7 +42,7 @@ export interface ActiveRun {
 	product?: KdProduct;
 	version?: string;
 	profile?: ProductProfile;
-	risk?: KdRisk;
+	riskAssessment?: RiskAssessment;
 	artifacts: Record<string, string>;
 	gate: GateResult;
 	questions?: KdQuestion[];

package/src/official/kingdee-skills.ts

@@ -5,7 +5,7 @@ import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 import type { ProductProfile } from "../product/profile.ts";
 import { readActiveRun } from "../harness/state.ts";
-import { runArtifactPath } from "../harness/paths.ts";
+import { writeEvidenceFile } from "../harness/evidence.ts";
 import { searchKnowledge } from "../knowledge/search.ts";
 import { formatSearchResults } from "../knowledge/format.ts";
 import { resolveWorkspacePath } from "../platform/path.ts";
@@ -174,15 +174,15 @@ export function writeOfficialEvidence(cwd: string, evidenceFile: OfficialEvidenc
 	const run = readActiveRun(cwd);
 	if (!run) return undefined;
 
-	const path = runArtifactPath(cwd, run, join("evidence", evidenceFile));
-	mkdirSync(dirname(path), { recursive: true });
-
 	const content =
 		evidenceFile === "cosmic-metadata.json"
 			? formatJsonEvidence(evidenceFile, result)
 			: `${formatCommandResult(result)}\nCaptured: ${new Date().toISOString()}\n`;
-	writeFileSync(path, content.endsWith("\n") ? content : `${content}\n`, "utf8");
-	return path;
+	return writeEvidenceFile(cwd, run, join("evidence", evidenceFile), content, {
+		kind: evidenceFile.replace(/\.(txt|json)$/i, ""),
+		command: result.command,
+		exitCode: result.exitCode,
+	});
 }
 
 function formatJsonEvidence(evidenceFile: OfficialEvidenceFile, result: CommandResult): string {