kcode-pi 0.1.15 → 0.1.16

package/README.md

@@ -397,6 +397,8 @@ 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`。
@@ -425,6 +427,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 +494,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` 或写生产源码。
 
 示例：
 

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,11 @@ 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。",
 	].join("\n");
 }
 
@@ -158,7 +161,11 @@ function codeWriteBlockReason(cwd: string, path: string | undefined): string | u
 		return `当前 KCode 阶段是 ${run.phase}，不能写产品代码。请先完成 discuss -> spec -> plan 并进入 execute。`;
 	}
 
-	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({

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.16",
   "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: ["## 验证命令"],
@@ -129,7 +133,7 @@ function inspectMarkers(cwd: string, run: ActiveRun, phase: KdPhase): string | u
 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 `缺少必需证据：${missing.join(", ")}`;
 }
 
 function isCosmicRun(run: ActiveRun): boolean {
@@ -137,22 +141,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 +165,11 @@ 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 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 +177,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/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 API。`;
+}
+
+function normalizeRelativePath(path: string): string {
+	return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}