kcode-pi 0.1.15 → 0.1.17

package/README.md

@@ -397,13 +397,50 @@ ship     汇总变更、验证证据、风险和后续事项
 - 进入 `execute` 前必须已有 `PLAN.md` 和必要证据。
 - `PLAN.md` 必须包含 `## 执行步骤`，并用 `- [ ] STEP-001：...` 格式拆分可跟踪步骤。
 - `PLAN.md` 必须包含 `## TDD / 红绿检查`，声明红灯证据、绿灯证据和测试/检查命令。
+- Java/C# 产品代码进入 `execute` 前必须已有 `evidence/sdk-signature.md`。该证据由 `kd_sdk_signature` 成功查证当前项目真实 SDK jar/dll 后自动写入。
+- LLM 禁止凭记忆、模型知识或随包知识库猜 SDK 方法签名。`kd_search`、`kd_cosmic_api` 只能作为线索；最终签名事实必须来自 `kd_sdk_signature`、当前项目构建输出、项目源码封装或官方元数据。
 - 红绿检查不等于必须写 JUnit。金蝶项目不要为了满足门禁引入额外 jar 或测试框架。
 - 写生产源码前必须已有 `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/tdd-green.md` 必须包含真实成功输出和 `Exit: 0` 或 `退出码：0`；不能写“需在开发环境验证”“待验证”“未执行”等不确定结论。
+- 如果门禁提示 evidence 内容无效，不要反复改文案或补关键词；必须重新运行 `PLAN.md` 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。
 - 旗舰版项目必须先检查当前项目结构。若存在 `code/`，跟随 `code/` 下的实际组织；若不存在，必须在 `PLAN.md` 记录实际源码根或目标文件。
 - 不允许凭空写 demo、sample、scaffold，或在不了解项目结构时新建猜测目录。
 
+### SDK 签名门禁怎么用
+
+当需求涉及 Java/C# 插件代码时，KCode 会强制要求先查证当前项目真实 SDK 的类、方法、构造器、枚举或属性签名。这个门禁是为了避免 LLM 根据记忆编出不存在的方法。
+
+推荐操作顺序：
+
+```text
+1. discuss/spec 阶段确认需求、产品、插件类型和目标单据。
+2. plan 阶段检查当前项目源码结构、构建文件和 SDK 依赖位置。
+3. 用 kd_sdk_signature 查证要调用的 SDK 类型和方法。
+4. 确认生成 .pi/kd/runs/<run-id>/evidence/sdk-signature.md。
+5. 记录 evidence/tdd-red.md。
+6. 进入 execute 后再写 PLAN.md 中列出的生产源码。
+7. 写完后记录 evidence/tdd-green.md，再进入 verify。
+```
+
+示例：
+
+```text
+kd_sdk_signature product=flagship query=SaveServiceHelper method=save
+kd_sdk_signature product=flagship query=OperationServiceHelper method=executeOperate
+kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject
+```
+
+如果 `kd_sdk_signature` 找不到结果，不要让 Agent 直接写代码。先检查：
+
+- 当前是否在业务项目根目录启动 `kcode start`。
+- 项目是否能看到 SDK jar/dll，例如 `lib/`、`libs/`、`bin/`、`WebSite/bin/` 或构建缓存。
+- `PLAN.md` 是否记录了真实源码根和 SDK 依赖位置。
+- 是否可以通过当前项目已有封装类、编译输出或官方元数据反查签名。
+
+只有 `kd_sdk_signature`、当前项目构建输出、项目源码封装或官方元数据能作为签名事实。`kd_search`、`kd_cosmic_api` 和 README 里的示例只用于找线索。
+
 示例计划步骤：
 
 ```markdown
@@ -425,6 +462,7 @@ ship     汇总变更、验证证据、风险和后续事项
 - 绿灯证据：evidence/tdd-green.md
 - 红绿检查命令或工具：kd_sdk_signature / kd_cosmic_metadata / kd_check / build
 - 不要为了满足门禁引入第三方测试 jar 或测试框架。
+- Java/C# SDK 签名证据：evidence/sdk-signature.md
 ```
 
 示例执行记录：
@@ -491,6 +529,7 @@ kd_debug            分析金蝶日志和堆栈
 - `kd_cosmic_metadata` 使用统一路由 API 查询真实单据/表单元数据，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
 - `kd_sdk_signature` 优先从当前业务项目的实际 SDK jar/dll 中读取类型和方法签名。Cosmic Java 依赖 `javap`，Enterprise C# 依赖 PowerShell 读取 DLL 元数据。
 - `kd_cosmic_api` 查询随包金蝶知识库，只作为 API 线索和兜底；精确方法签名优先使用 `kd_sdk_signature`、当前项目 SDK 或编译输出确认。
+- 当前项目存在 active run 时，`kd_sdk_signature` 成功后会自动写入 `.pi/kd/runs/<run-id>/evidence/sdk-signature.md`。Java/C# 产品代码缺少这份证据时，KCode 不允许进入 `execute` 或写生产源码。
 
 示例：
 
@@ -538,6 +577,34 @@ npm view kcode-pi version
 npm install -g kcode-pi@latest
 ```
 
+如果 `npm install -g` 没有更新到新版本，或提示 `EEXIST: file already exists ... kcode.cmd`，通常是全局命令 shim 或旧包目录没有被 npm 清干净。按下面顺序处理：
+
+```powershell
+npm uninstall -g kcode-pi
+npm install -g kcode-pi@latest
+kcode version
+```
+
+如果仍提示 `kcode.cmd` 已存在，先确认它属于旧的 `kcode-pi` 全局安装：
+
+```powershell
+npm root -g
+where kcode
+```
+
+删除 `where kcode` 指向的旧 `kcode.cmd`、`kcode.ps1` 后再重装：
+
+```powershell
+npm install -g kcode-pi@latest
+```
+
+如果 npm 仍使用缓存或企业镜像没有同步新版本，先确认 registry 上真实可安装版本：
+
+```powershell
+npm view kcode-pi version
+npm view kcode-pi versions --json
+```
+
 升级后建议在业务项目根目录重新执行：
 
 ```powershell

package/extensions/kingdee-harness.ts

@@ -18,6 +18,7 @@ import {
 } from "../src/harness/state.ts";
 import { readArtifact } from "../src/harness/artifacts.ts";
 import { flagshipWriteBlockReason, isSourceLikePath, planWriteBlockReason } from "../src/harness/path-policy.ts";
+import { sdkSignatureProductionWriteBlockReason } from "../src/harness/sdk-policy.ts";
 import { tddProductionWriteBlockReason } from "../src/harness/tdd-policy.ts";
 import { readProjectContext } from "../src/context/project-context.ts";
 import { windowsPathHint } from "../src/platform/path.ts";
@@ -123,9 +124,12 @@ function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof re
 		"",
 		phaseGuidance[run.phase],
 		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
+		"禁止凭记忆、模型知识或随包知识库直接编写 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；红绿证据可以是 kd_sdk_signature 本地 SDK 签名、API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
+		"写生产源码前必须先有红灯证据 evidence/tdd-red.md；Java/C# 还必须有 SDK 签名证据 evidence/sdk-signature.md。红绿证据可以是 kd_sdk_signature 本地 SDK 签名、API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
+		"如果门禁提示 evidence 内容无效，不要通过改写结论、补关键词或反复读取文件来过关；必须重新运行 PLAN.md 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。",
 	].join("\n");
 }
 
@@ -151,14 +155,18 @@ function codeWriteBlockReason(cwd: string, path: string | undefined): string | u
 
 	const run = readActiveRun(cwd);
 	if (!run) {
-		return "KCode 工作流未启动，不能直接写产品代码。请先用自然语言说明需求，KCode 会进入 discuss，或手动运行 /kd-start <需求>。";
+		return "KCode 工作流未启动，不能直接写产品代码。下一步：先用自然语言说明需求让 KCode 自动进入 discuss，或手动运行 /kd-start <需求> 创建 run；完成 discuss -> spec -> plan -> execute 后再写生产源码。";
 	}
 
 	if (run.phase !== "execute") {
-		return `当前 KCode 阶段是 ${run.phase}，不能写产品代码。请先完成 discuss -> spec -> plan 并进入 execute。`;
+		return `当前 KCode 阶段是 ${run.phase}，不能写产品代码。下一步：先完成当前阶段文档和门禁，用 /kd-advance 推进到 execute；如果发现计划不完整，更新 PLAN.md，而不是直接写代码。`;
 	}
 
-	return tddProductionWriteBlockReason(cwd, run, path) ?? planWriteBlockReason(cwd, run, path, readArtifact(cwd, run, "plan") ?? "");
+	return (
+		sdkSignatureProductionWriteBlockReason(cwd, run, path) ??
+		tddProductionWriteBlockReason(cwd, run, path) ??
+		planWriteBlockReason(cwd, run, path, readArtifact(cwd, run, "plan") ?? "")
+	);
 }
 
 const kdPlanStatusTool = defineTool({
@@ -326,7 +334,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}。`;
+			const reason = `当前是 Windows 工作区，不能使用 WSL/MSYS 路径 ${path}。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}；不要再尝试 /mnt/d 或 /d 路径。`;
 			if (ctx.hasUI) ctx.ui.notify(reason, "warning");
 			return { block: true, reason };
 		}

package/extensions/kingdee-tools.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } 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";
@@ -22,6 +22,9 @@ import {
 	writeOfficialEvidence,
 } 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 { SDK_SIGNATURE_EVIDENCE } from "../src/harness/sdk-policy.ts";
 
 const extensionDir = dirname(fileURLToPath(import.meta.url));
 const knowledgePath = join(extensionDir, "..", "knowledge");
@@ -329,9 +332,11 @@ const kdSdkSignatureTool = defineTool({
 			path: params.path,
 			limit: params.limit,
 		});
+		const text = formatSdkSignatureResult(result);
+		const evidencePath = result.exitCode === 0 ? writeSdkSignatureEvidence(ctx.cwd, text) : undefined;
 		return {
-			content: [{ type: "text", text: formatSdkSignatureResult(result) }],
-			details: { product: profile.product, ...result },
+			content: [{ type: "text", text: evidencePath ? `${text}\n\n已写入 SDK 签名证据：${evidencePath}` : text }],
+			details: { product: profile.product, evidencePath, ...result },
 		};
 	},
 });
@@ -396,9 +401,9 @@ const kdDebugTool = defineTool({
 			return {
 				content: [
 					{
-					type: "text",
-					text: `来源：${input.source}\n产品：${profile.product}/${profile.platform}/${profile.techStack}\n\n${formatDebugFindings(findings)}`,
-				},
+						type: "text",
+						text: `来源：${input.source}\n产品：${profile.product}/${profile.platform}/${profile.techStack}\n\n${formatDebugFindings(findings)}`,
+					},
 				],
 				details: { source: input.source, product: profile.product, findings },
 			};
@@ -423,3 +428,27 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdBuildTool);
 	pi.registerTool(kdDebugTool);
 }
+
+function writeSdkSignatureEvidence(cwd: string, content: string): string | undefined {
+	const run = readActiveRun(cwd);
+	if (!run) return undefined;
+
+	const path = runArtifactPath(cwd, run, SDK_SIGNATURE_EVIDENCE);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(
+		path,
+		[
+			"# SDK 签名证据",
+			"",
+			`- 生成时间：${new Date().toISOString()}`,
+			"- 来源：kd_sdk_signature 当前项目本地 SDK jar/dll",
+			"",
+			"```text",
+			content.trim(),
+			"```",
+			"",
+		].join("\n"),
+		"utf8",
+	);
+	return path;
+}

package/package.json

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

package/prompts/kd-execute.md

@@ -4,7 +4,7 @@ description: 在 Harness 门禁约束下执行当前金蝶实施计划。
 
 使用 `kd-execute` skill。
 
-编辑代码前，先使用 `kd_plan_status` 检查当前 run。如果缺少 `PLAN.md` 或门禁被阻塞，必须停止并说明缺少的文档或证据。通过后只实现 `PLAN.md` 批准的内容，并更新 `EXECUTION.md`。
+编辑代码前，先使用 `kd_plan_status` 检查当前 run。如果缺少 `PLAN.md`、`evidence/sdk-signature.md` 或门禁被阻塞，必须停止并说明缺少的文档或证据。通过后只实现 `PLAN.md` 批准的内容，并更新 `EXECUTION.md`。禁止凭记忆、模型知识或随包知识库猜 SDK 方法签名。
 
 用户补充说明：
 

package/prompts/kd-plan.md

@@ -4,7 +4,7 @@ description: 为当前金蝶 Harness run 编写实施计划。
 
 使用 `kd-plan` skill。
 
-读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。必须包含已检查的项目结构、需要查看的文件、预计修改的真实路径、必须查证的金蝶 API/元数据、验证命令和回滚说明。
+读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。必须包含已检查的项目结构、需要查看的文件、预计修改的真实路径、必须查证的金蝶 API/元数据、SDK 签名证据、验证命令和回滚说明。Java/C# SDK 方法签名必须来自 `kd_sdk_signature` 当前项目 jar/dll、项目构建输出或官方元数据，不能凭记忆猜。
 
 用户补充说明：
 

package/src/harness/artifacts.ts

@@ -83,6 +83,10 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"",
 				"## 必需的金蝶查证项",
 				"",
+				"- Java/C# 代码涉及 SDK 类、方法、构造器、枚举、属性时，必须先用 kd_sdk_signature 或项目构建输出确认真实签名。",
+				"- 知识库搜索、随包 Cosmic API 查询只能作为线索，不能作为最终方法签名事实。",
+				"- SDK 签名证据：evidence/sdk-signature.md",
+				"",
 				"## 执行步骤",
 				"",
 				"- [ ] STEP-001：检查现有目标文件，确认精确修改位置。",
@@ -96,9 +100,10 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"- 红灯证据：evidence/tdd-red.md",
 				"- 绿灯证据：evidence/tdd-green.md",
 				"- 红绿检查命令或工具：未知",
-				"- 允许的检查：官方 API/基类/方法签名查证、元数据查证、kd_check、构建/编译输出、项目已有测试框架、外部接口最小验证。",
+				"- 允许的检查：本地 SDK 签名查证、官方 API/基类/方法查证、元数据查证、kd_check、构建/编译输出、项目已有测试框架、外部接口最小验证。",
 				"- 不要为了满足门禁引入第三方测试 jar 或框架。",
 				"- 如果无法自动化测试，记录一个产品相关、实现前应失败且实现后应通过的检查。",
+				"- 禁止凭记忆或随包知识库猜 SDK 方法签名；签名事实必须来自当前项目 jar/dll、构建输出或官方元数据。",
 				"",
 				"## 验证命令",
 				"",

package/src/harness/gates.ts

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import type { ActiveRun, GateResult, KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS, PHASE_ORDER } from "./types.ts";
 import { artifactExists, readArtifact } from "./artifacts.ts";
@@ -5,6 +7,8 @@ import { isKnownProduct } from "../product/profile.ts";
 import { flagshipPlanBlockReason } from "./path-policy.ts";
 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";
 
 const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
 	plan: ["## 验证命令"],
@@ -32,7 +36,7 @@ export function inspectGate(cwd: string, run: ActiveRun): GateResult {
 	const evidenceProblem = inspectEvidence(cwd, run, run.phase);
 	const questionProblem = inspectOpenQuestions(run);
 	const reasonParts = [];
-	if (missing.length > 0) reasonParts.push(`缺少必需产物：${[...new Set(missing)].join(", ")}`);
+	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);
@@ -51,7 +55,9 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 	const reasonParts: string[] = [];
 
 	if (target !== "discuss" && !isKnownProduct(run.profile?.product ?? run.product)) {
-		reasonParts.push("不能离开 discuss：产品画像未知。请使用 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>。");
+		reasonParts.push(
+			"不能离开 discuss：产品画像未知。下一步：根据需求或用户回答确认产品，然后执行 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。",
+		);
 	}
 
 	for (let i = 0; i < targetIndex; i++) {
@@ -85,7 +91,7 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 		missing.push(PHASE_ARTIFACTS.verify);
 	}
 
-	if (missing.length > 0) reasonParts.push(`不能进入 ${target}：缺少 ${[...new Set(missing)].join(", ")}`);
+	if (missing.length > 0) reasonParts.push(missingForTargetReason(target, [...new Set(missing)]));
 	const reason = reasonParts.length > 0 ? reasonParts.join("; ") : undefined;
 	return {
 		passed: !reason,
@@ -97,7 +103,10 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 function inspectOpenQuestions(run: ActiveRun): string | undefined {
 	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
 	if (open.length === 0) return undefined;
-	return `存在未回答的阻断问题：${open.map((question) => `${question.id} ${question.question}`).join("；")}`;
+	return [
+		`存在未回答的阻断问题：${open.map((question) => `${question.id} ${question.question}`).join("；")}`,
+		"下一步：先向用户等待或获取答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录；不要绕过问题推进阶段。",
+	].join("。");
 }
 
 function inspectStepState(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
@@ -123,13 +132,13 @@ 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(", ")}`;
+	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}。下一步：更新 ${PHASE_ARTIFACTS[phase]}，补齐这些章节并写入真实内容；不要只添加空标题。`;
 }
 
 function inspectEvidence(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
 	const missing = missingEvidenceForPhase(cwd, run, phase);
 	if (missing.length === 0) return undefined;
-	return `缺少必需的官方证据：${missing.join(", ")}`;
+	return missingEvidenceReason(missing);
 }
 
 function isCosmicRun(run: ActiveRun): boolean {
@@ -137,22 +146,23 @@ function isCosmicRun(run: ActiveRun): boolean {
 }
 
 function missingEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase): string[] {
-	return requiredEvidenceForPhase(cwd, run, phase).filter((artifact) => !artifactExists(cwd, run, artifact));
+	return requiredEvidenceForPhase(cwd, run, phase).filter((artifact) => !evidenceArtifactSatisfied(cwd, run, artifact));
 }
 
 function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase): string[] {
-	if (!isCosmicRun(run)) return [];
-
 	const required = new Set<string>();
 	const phaseIndex = PHASE_ORDER.indexOf(phase);
 
 	if (phaseIndex >= PHASE_ORDER.indexOf("execute")) {
-		required.add(COSMIC_CONFIG_EVIDENCE);
-		if (planHasMetadataRequirement(cwd, run)) required.add(COSMIC_METADATA_EVIDENCE);
-		if (planHasApiRequirement(cwd, run)) required.add(COSMIC_API_EVIDENCE);
+		if (requiresSdkSignatureEvidence(run)) required.add(SDK_SIGNATURE_EVIDENCE);
+		if (isCosmicRun(run)) {
+			required.add(COSMIC_CONFIG_EVIDENCE);
+			if (planHasMetadataRequirement(cwd, run)) required.add(COSMIC_METADATA_EVIDENCE);
+			if (planHasApiRequirement(cwd, run)) required.add(COSMIC_API_EVIDENCE);
+		}
 	}
 
-	if (phaseIndex >= PHASE_ORDER.indexOf("ship") && runHasKsqlDelivery(cwd, run)) {
+	if (isCosmicRun(run) && phaseIndex >= PHASE_ORDER.indexOf("ship") && runHasKsqlDelivery(cwd, run)) {
 		required.add(COSMIC_METADATA_EVIDENCE);
 		required.add(KSQL_LINT_EVIDENCE);
 	}
@@ -160,6 +170,56 @@ function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase):
 	return [...required];
 }
 
+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));
+}
+
+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("；");
+}
+
+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 planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {
 	const plan = readArtifact(cwd, run, "plan") ?? "";
 	return /kd_cosmic_metadata|cosmic-metadata|cosmic-metadata\.json|metadata evidence|字段元数据证据|元数据证据/i.test(plan);
@@ -167,7 +227,7 @@ function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {
 
 function planHasApiRequirement(cwd: string, run: ActiveRun): boolean {
 	const plan = readArtifact(cwd, run, "plan") ?? "";
-	return /kd_sdk_signature|kd_cosmic_api|cosmic-api|cosmic-api\.txt|api signature evidence|method signature evidence|SDK 签名证据|方法签名证据|接口签名证据/i.test(plan);
+	return /kd_cosmic_api|cosmic-api|cosmic-api\.txt/i.test(plan);
 }
 
 function runHasKsqlDelivery(cwd: string, run: ActiveRun): boolean {

package/src/harness/path-policy.ts

@@ -22,7 +22,9 @@ export function flagshipWriteBlockReason(run: ActiveRun | undefined, path: strin
 	const normalized = normalizeRelativePath(cwd && isAbsolute(path) ? relative(cwd, path) : path);
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (cwd && !hasWorkspaceCodeDir(cwd)) return undefined;
-	if (!normalized.startsWith("code/")) return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}`;
+	if (!normalized.startsWith("code/")) {
+		return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：先读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
+	}
 
 	return undefined;
 }
@@ -35,7 +37,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 `PLAN.md 未批准写入 ${normalized}。下一步：停止写入该文件，回到 plan 阶段检查项目结构和影响范围，把该文件加入 PLAN.md 的 ## 允许修改的文件 和执行步骤；重新通过门禁后再写。`;
 }
 
 export function flagshipPlanBlockReason(cwd: string, run: ActiveRun | undefined, plan: string): string | undefined {
@@ -43,11 +45,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/ 下的实际目标路径；不要按固定模块规则猜路径。";
+		return "不能进入 execute：星空旗舰版 PLAN.md 必须先记录当前项目 code/ 下的实际目标路径；不要按固定模块规则猜路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
 	}
 
 	if (planMentionsDiscoveredSourcePath(plan)) return undefined;
-	return "不能进入 execute：PLAN.md 必须先记录已检查当前项目结构，并写明实际源码根或目标文件路径；当前项目没有 code/ 时更不能猜路径。";
+	return "不能进入 execute：PLAN.md 必须先记录已检查当前项目结构，并写明实际源码根或目标文件路径；当前项目没有 code/ 时更不能猜路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
 }
 
 function hasWorkspaceCodeDir(cwd: string): boolean {

package/src/harness/plan-steps.ts

@@ -21,16 +21,16 @@ export function parsePlanSteps(plan: string): PlanStep[] {
 
 export function planStepsBlockReason(plan: string): string | undefined {
 	if (!/##\s*执行步骤/i.test(plan)) {
-		return "PLAN.md 缺少 ## 执行步骤。必须把计划拆成 STEP-001 这种可跟踪步骤。";
+		return "PLAN.md 缺少 ## 执行步骤。下一步：回到 plan，补充 `## 执行步骤`，把工作拆成 `- [ ] STEP-001：...` 这种可跟踪步骤；每一步都应能产生代码变更或 evidence。";
 	}
 
 	const steps = parsePlanSteps(plan);
 	if (steps.length === 0) {
-		return "PLAN.md 没有可执行步骤。请使用 `- [ ] STEP-001：...` 列出步骤。";
+		return "PLAN.md 没有可执行步骤。下一步：在 `## 执行步骤` 下使用 `- [ ] STEP-001：...` 列出步骤；不要用普通段落代替可勾选步骤。";
 	}
 
 	const duplicate = firstDuplicate(steps.map((step) => step.id));
-	if (duplicate) return `PLAN.md 存在重复步骤编号：${duplicate}`;
+	if (duplicate) return `PLAN.md 存在重复步骤编号：${duplicate}。下一步：重新编号执行步骤，确保 STEP-001、STEP-002 等编号唯一且顺序稳定。`;
 	return undefined;
 }
 
@@ -54,8 +54,12 @@ export function executionStepsBlockReason(cwd: string, run: ActiveRun, plan: str
 		}
 	}
 
-	if (missing.length > 0) return `不能进入 verify：EXECUTION.md 未完成计划步骤 ${missing.join(", ")}。`;
-	if (missingEvidence.length > 0) return `不能进入 verify：步骤 ${missingEvidence.join(", ")} 缺少已落地的 evidence 文件。`;
+	if (missing.length > 0) {
+		return `不能进入 verify：EXECUTION.md 未完成计划步骤 ${missing.join(", ")}。下一步：继续执行这些步骤，完成后在 EXECUTION.md 的 ## 步骤结果 中用 \`- [x] STEP-###：已完成。证据：evidence/step-###.md\` 记录；未真正执行时不要勾选。`;
+	}
+	if (missingEvidence.length > 0) {
+		return `不能进入 verify：步骤 ${missingEvidence.join(", ")} 缺少已落地的 evidence 文件。下一步：为每个步骤创建真实 evidence 文件，写入检查命令、结果、改动文件或验证输出，然后在 EXECUTION.md 对应步骤行引用该 evidence 路径。`;
+	}
 	return undefined;
 }
 

package/src/harness/sdk-policy.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import type { ActiveRun } from "./types.ts";
+import { runRoot } from "./paths.ts";
+import { isSourceLikePath } from "./path-policy.ts";
+
+export const SDK_SIGNATURE_EVIDENCE = "evidence/sdk-signature.md";
+
+export function requiresSdkSignatureEvidence(run: ActiveRun): boolean {
+	const language = run.profile?.language;
+	return language === "java" || language === "csharp";
+}
+
+export function hasValidSdkSignatureEvidence(cwd: string, run: ActiveRun): boolean {
+	if (!requiresSdkSignatureEvidence(run)) return true;
+	const path = join(runRoot(cwd, run), SDK_SIGNATURE_EVIDENCE);
+	if (!existsSync(path)) return false;
+
+	const content = readFileSync(path, "utf8");
+	return /(退出码|Exit)\s*[：:]\s*0/i.test(content) && /(来源|Sources?)\s*[：:]/i.test(content);
+}
+
+export function sdkSignatureProductionWriteBlockReason(cwd: string, run: ActiveRun | undefined, path: string | undefined): string | undefined {
+	if (!run || run.phase !== "execute") return undefined;
+	if (!requiresSdkSignatureEvidence(run)) return undefined;
+	if (!path || !isSourceLikePath(path)) return undefined;
+
+	const normalized = normalizeRelativePath(cwd && isAbsolute(path) ? relative(cwd, path) : path);
+	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。`;
+}
+
+function normalizeRelativePath(path: string): string {
+	return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}

package/src/harness/tdd-policy.ts

@@ -9,7 +9,7 @@ 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 / 红绿检查。必须声明红灯验证、绿灯验证和无法自动化时的产品验证替代方案。";
+	return "PLAN.md 缺少 ## TDD / 红绿检查。下一步：回到 plan 补充该章节，明确红灯证据、绿灯证据、验证命令或无法自动化时的产品验证替代方案；至少写明 evidence/tdd-red.md、evidence/tdd-green.md 和要运行的真实检查。";
 }
 
 export function tddProductionWriteBlockReason(cwd: string, run: ActiveRun | undefined, path: string | undefined): string | undefined {
@@ -21,25 +21,65 @@ 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}。请先记录失败的测试、API/基类/方法签名检查、元数据检查、编译检查或外部接口最小验证输出。`;
+	return `不能写生产源码 ${normalized}：缺少红灯证据 ${TDD_RED_EVIDENCE}。下一步：先运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
 }
 
 export function tddVerifyBlockReason(cwd: string, run: ActiveRun): string | undefined {
-	const missing: string[] = [];
-	if (!hasValidTddEvidence(cwd, run, "red")) missing.push(TDD_RED_EVIDENCE);
-	if (!hasValidTddEvidence(cwd, run, "green")) missing.push(TDD_GREEN_EVIDENCE);
-	if (missing.length === 0) return undefined;
-	return `不能进入 verify：缺少 TDD 红绿证据 ${missing.join(", ")}。`;
+	const problems = [
+		validateTddEvidence(cwd, run, "red"),
+		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("");
 }
 
 function hasValidTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green"): boolean {
+	return validateTddEvidence(cwd, run, kind).valid;
+}
+
+function validateTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green"): { valid: boolean; reason?: string } {
 	const evidenceName = kind === "red" ? TDD_RED_EVIDENCE : TDD_GREEN_EVIDENCE;
 	const evidencePath = join(runRoot(cwd, run), evidenceName);
-	if (!existsSync(evidencePath)) return false;
+	if (!existsSync(evidencePath)) return { valid: false, reason: `缺少 ${evidenceName}` };
 
 	const content = readFileSync(evidencePath, "utf8");
-	if (kind === "red") return /red|fail|failed|failure|error|失败|未通过|Exit:\s*[1-9]/i.test(content);
-	return /green|pass|passed|success|成功|通过|Exit:\s*0/i.test(content);
+	const uncertainty = uncertaintyReason(content);
+	if (uncertainty) {
+		return { valid: false, reason: `${evidenceName} 内容无效：${uncertainty}` };
+	}
+
+	if (kind === "red") {
+		const hasFailure = /red|fail|failed|failure|error|失败|未通过|Exit\s*[：:]\s*[1-9]/i.test(content);
+		return hasFailure
+			? { valid: true }
+			: { valid: false, reason: `${evidenceName} 内容无效：必须包含真实失败输出或非 0 退出码，不能只写结论` };
+	}
+
+	const hasGreenExit = /Exit\s*[：:]\s*0|退出码\s*[：:]\s*0/i.test(content);
+	const hasSuccess = /green|pass|passed|success|成功|通过/i.test(content);
+	if (hasGreenExit && hasSuccess) return { valid: true };
+
+	return {
+		valid: false,
+		reason: `${evidenceName} 内容无效：绿灯证据必须同时包含成功结论和 Exit: 0/退出码：0，不能只写“通过”或人工结论`,
+	};
+}
+
+function uncertaintyReason(content: string): string | undefined {
+	const patterns: Array<[RegExp, string]> = [
+		[/需.*验证|需要.*验证|待.*验证|后续.*验证/i, "包含待验证措辞"],
+		[/未验证|未执行|没有执行|无法执行|无法验证/i, "声明未完成验证"],
+		[/TODO|待补充|待完善|假设|预计|理论上|应该可以/i, "包含占位或推测性结论"],
+		[/编译验证通过[^。\n]*(需|需要|待).*验证/i, "同时声明通过和仍需验证，结论矛盾"],
+	];
+	for (const [pattern, reason] of patterns) {
+		if (pattern.test(content)) return reason;
+	}
+	return undefined;
 }
 
 function isTestLikePath(path: string): boolean {