kcode-pi 0.1.34 → 0.1.35

package/extensions/kingdee-tools.ts

@@ -77,7 +77,7 @@ function sdkLanguageForProfile(profile: ProductProfile, value: string | undefine
 
 function rejectNonCosmic(profile: ProductProfile): string | undefined {
 	if (isCosmicFamily(profile)) return undefined;
-	if (profile.product === "unknown") return "请先提供支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。";
+	if (profile.product === "unknown") return "必须提供支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。";
 	return `当前产品 ${profile.product} 使用 ${profile.platform}/${profile.techStack}，不适用 Cosmic 官方能力。`;
 }
 
@@ -90,7 +90,7 @@ async function runOrDryRun(
 	const command = await commandPromise;
 	if (dryRun) {
 		return {
-			content: [{ type: "text" as const, text: `仅展示命令，不执行：\n${command.display}` }],
+			content: [{ type: "text" as const, text: `输出命令预览；不执行：\n${command.display}` }],
 			details: { command: command.display, dryRun: true },
 		};
 	}
@@ -119,11 +119,11 @@ function autoAdvanceAfterEvidence(cwd: string): { text: string; details: ReturnT
 const kdSearchTool = defineTool({
 	name: "kd_search",
 	label: "KD 搜索",
-	description: "搜索 KCode 随包金蝶知识库，包括 SDK、插件生命周期、代码模式和常见实现建议。",
+	description: "搜索 KCode 随包金蝶知识库，包括 SDK、插件生命周期、代码模式和实现约束。",
 	parameters: Type.Object({
-		query: Type.String({ description: "要搜索的关键词、API、类名、表名或生命周期术语。" }),
+		query: Type.String({ description: "搜索关键词、API、类名、表名或生命周期术语。" }),
 		product: Type.Optional(Type.String({ description: "金蝶产品：flagship、xinghan、cangqiong 或 enterprise。" })),
-		edition: Type.Optional(Type.String({ description: "旧参数，等同于 product。优先使用 product。" })),
+		edition: Type.Optional(Type.String({ description: "旧参数，等同于 product；product 覆盖 edition。" })),
 		limit: Type.Optional(Type.Number({ description: "最大结果数，默认 5。" })),
 	}),
 
@@ -133,7 +133,7 @@ const kdSearchTool = defineTool({
 		if (!scopes) {
 			const guidance =
 				profile.product === "unknown"
-					? "请先提供 product，例如 flagship、enterprise、xinghan 或 cangqiong。"
+					? "必须提供 product，例如 flagship、enterprise、xinghan 或 cangqiong。"
 					: "当前产品画像未配置可搜索知识范围。";
 			return {
 				content: [
@@ -141,7 +141,7 @@ const kdSearchTool = defineTool({
 						type: "text",
 						text: [
 							`产品画像：${profile.product}/${profile.techStack}/${profile.language}`,
-							"KCode 随包知识库搜索需要明确产品画像。",
+							"KCode 随包知识库搜索必须明确产品画像。",
 							guidance,
 						].join("\n"),
 					},
@@ -166,7 +166,7 @@ const kdTableTool = defineTool({
 	parameters: Type.Object({
 		table: Type.String({ description: "表名，例如 T_PUR_POORDER。" }),
 		product: Type.Optional(Type.String({ description: "金蝶产品：flagship、xinghan、cangqiong 或 enterprise。" })),
-		edition: Type.Optional(Type.String({ description: "旧参数，等同于 product。优先使用 product。" })),
+		edition: Type.Optional(Type.String({ description: "旧参数，等同于 product；product 覆盖 edition。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -175,8 +175,8 @@ const kdTableTool = defineTool({
 		if (!edition) {
 			const guidance =
 				profile.product === "unknown"
-					? "请先提供 product。不要跨金蝶产品族猜测表结构。"
-					: "没有元数据查证前，不要把旗舰版/企业版表结构假设复用到苍穹/星瀚/Cosmic。";
+					? "必须提供 product。禁止跨金蝶产品族猜测表结构。"
+					: "没有元数据查证前，禁止把旗舰版/企业版表结构假设复用到苍穹/星瀚/Cosmic。";
 			return {
 				content: [
 					{
@@ -204,12 +204,12 @@ const kdCheckTool = defineTool({
 	name: "kd_check",
 	label: "KD 检查",
 	description:
-		"检查金蝶 Java/C#/Python 插件代码中的魔法值、命名问题、循环内 DB 调用和空 catch 等问题。",
+		"检查金蝶 Java/C#/Python 插件代码中的魔法值、命名问题、循环内 DB 调用和空 catch。",
 	parameters: Type.Object({
-		code: Type.Optional(Type.String({ description: "要检查的源码。与 path 二选一。" })),
-		path: Type.Optional(Type.String({ description: "要检查的源码文件路径。与 code 二选一。" })),
+		code: Type.Optional(Type.String({ description: "待检查源码。与 path 二选一。" })),
+		path: Type.Optional(Type.String({ description: "待检查源码文件路径。与 code 二选一。" })),
 		product: Type.Optional(Type.String({ description: "金蝶产品。未提供 language 时用于推导 Java 或 C#。" })),
-		language: Type.Optional(Type.String({ description: "语言：java、csharp 或 python。会覆盖产品推导结果。" })),
+		language: Type.Optional(Type.String({ description: "语言：java、csharp 或 python。覆盖产品推导结果。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -226,7 +226,7 @@ const kdCheckTool = defineTool({
 
 		if (!code) {
 			return {
-				content: [{ type: "text", text: "kd_check 需要提供 code 或 path。" }],
+				content: [{ type: "text", text: "kd_check 必须提供 code 或 path。" }],
 				details: { error: "missing-code-or-path" },
 			};
 		}
@@ -250,8 +250,8 @@ const kdCosmicConfigTool = defineTool({
 	description: "运行 Cosmic 家族金蝶产品的官方能力配置预检查。",
 	parameters: Type.Object({
 		product: Type.String({ description: "支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。" }),
-		config: Type.Optional(Type.String({ description: "可选 ok-cosmic.json 路径。默认按当前工作目录解析。" })),
-		dryRun: Type.Optional(Type.Boolean({ description: "只返回命令，不实际执行。" })),
+		config: Type.Optional(Type.String({ description: "ok-cosmic.json 路径；省略时按当前工作目录解析。" })),
+		dryRun: Type.Optional(Type.Boolean({ description: "输出命令预览；不实际执行。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -268,14 +268,14 @@ const kdCosmicMetadataTool = defineTool({
 	description: "查询官方 Cosmic 表单/单据元数据，包括字段、枚举值、操作和 SQL 表信息。",
 	parameters: Type.Object({
 		product: Type.String({ description: "支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。" }),
-		form: Type.String({ description: "Form ID、单据 ID 或中文单据名；多个目标可用逗号分隔。" }),
-		config: Type.Optional(Type.String({ description: "可选 ok-cosmic.json 路径。" })),
-		fuzzy: Type.Optional(Type.String({ description: "可选字段关键词，用空格或逗号分隔。" })),
-		typeFilter: Type.Optional(Type.String({ description: "可选字段类型正则，例如 combo|check 或 decimal。" })),
-		sql: Type.Optional(Type.Boolean({ description: "是否包含数据库表和字段信息。" })),
-		op: Type.Optional(Type.Boolean({ description: "是否显示表单/单据操作。" })),
-		showDetail: Type.Optional(Type.Boolean({ description: "是否显示详细元数据输出。" })),
-		dryRun: Type.Optional(Type.Boolean({ description: "只返回命令，不实际执行。" })),
+		form: Type.String({ description: "Form ID、单据 ID 或中文单据名；多个目标使用逗号分隔。" }),
+		config: Type.Optional(Type.String({ description: "ok-cosmic.json 路径；省略时使用默认配置。" })),
+		fuzzy: Type.Optional(Type.String({ description: "字段关键词，使用空格或逗号分隔。" })),
+		typeFilter: Type.Optional(Type.String({ description: "字段类型正则，例如 combo|check 或 decimal。" })),
+		sql: Type.Optional(Type.Boolean({ description: "包含数据库表和字段信息。" })),
+		op: Type.Optional(Type.Boolean({ description: "显示表单/单据操作。" })),
+		showDetail: Type.Optional(Type.Boolean({ description: "显示详细元数据输出。" })),
+		dryRun: Type.Optional(Type.Boolean({ description: "输出命令预览；不实际执行。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -289,15 +289,15 @@ const kdCosmicMetadataTool = defineTool({
 const kdCosmicApiTool = defineTool({
 	name: "kd_cosmic_api",
 	label: "KD Cosmic API",
-	description: "查询随包 Cosmic API 知识，获取类和方法线索；最终签名事实应以 kd_sdk_signature 或项目构建输出为准。",
+	description: "查询随包 Cosmic API 知识，输出类和方法线索；最终签名事实必须以 kd_sdk_signature 或项目构建输出为准。",
 	parameters: Type.Object({
 		product: Type.String({ description: "支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。" }),
 		mode: Type.String({ description: "查询模式：search、search-method 或 detail。" }),
 		query: Type.String({ description: "类名、方法名或完整限定类名。" }),
-		config: Type.Optional(Type.String({ description: "可选 ok-cosmic.json 路径。" })),
-		method: Type.Optional(Type.String({ description: "detail 模式下的可选方法过滤条件。" })),
-		compact: Type.Optional(Type.Boolean({ description: "支持时请求紧凑详情输出。" })),
-		dryRun: Type.Optional(Type.Boolean({ description: "只返回命令，不实际执行。" })),
+		config: Type.Optional(Type.String({ description: "ok-cosmic.json 路径；省略时使用默认配置。" })),
+		method: Type.Optional(Type.String({ description: "detail 模式下的方法过滤条件。" })),
+		compact: Type.Optional(Type.Boolean({ description: "启用紧凑详情输出；命令支持时生效。" })),
+		dryRun: Type.Optional(Type.Boolean({ description: "输出命令预览；不实际执行。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -323,14 +323,14 @@ const kdSdkSignatureTool = defineTool({
 	name: "kd_sdk_signature",
 	label: "KD SDK 签名",
 	description:
-		"从当前项目真实存在的 SDK jar 或 dll 中检查方法/类型签名。涉及 API 签名事实时，优先使用它而不是随包知识库。",
+		"从当前项目真实存在的 SDK jar 或 dll 中检查方法/类型签名。API 签名事实必须使用此工具查证，不以随包知识库替代。",
 	parameters: Type.Object({
 		product: Type.Optional(Type.String({ description: "金蝶产品。未提供 language 时用于推导 Java 或 C#。" })),
 		language: Type.Optional(Type.String({ description: "java 或 csharp。默认由产品画像推导。" })),
-		query: Type.Optional(Type.String({ description: "要搜索的类/类型关键词，例如 QueryServiceHelper 或 DynamicObject。" })),
-		className: Type.Optional(Type.String({ description: "已知时提供完整限定 Java/C# 类型名。" })),
-		method: Type.Optional(Type.String({ description: "在匹配类/类型内过滤方法或属性；不会全局扫描所有方法。" })),
-		path: Type.Optional(Type.String({ description: "可选 SDK lib/bin 目录或依赖根路径。默认从当前项目查找。" })),
+		query: Type.Optional(Type.String({ description: "类/类型搜索关键词，例如 QueryServiceHelper 或 DynamicObject。" })),
+		className: Type.Optional(Type.String({ description: "完整限定 Java/C# 类型名。" })),
+		method: Type.Optional(Type.String({ description: "在匹配类/类型内过滤方法或属性；禁止全局扫描所有方法。" })),
+		path: Type.Optional(Type.String({ description: "SDK lib/bin 目录或依赖根路径；省略时从当前项目查找。" })),
 		limit: Type.Optional(Type.Number({ description: "最大检查 jar/dll/class 数量。默认 20 个结果类、200 个文件。" })),
 	}),
 
@@ -361,8 +361,8 @@ const kdKsqlLintTool = defineTool({
 	description: "对生成的 KSQL/SQL 文件运行官方 ok-ksql lint 检查。",
 	parameters: Type.Object({
 		product: Type.String({ description: "支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。" }),
-		path: Type.String({ description: "SQL/KSQL 文件路径，可为工作区相对路径或绝对路径。" }),
-		dryRun: Type.Optional(Type.Boolean({ description: "只返回命令，不实际执行。" })),
+		path: Type.String({ description: "SQL/KSQL 文件路径；支持工作区相对路径或绝对路径。" }),
+		dryRun: Type.Optional(Type.Boolean({ description: "输出命令预览；不实际执行。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -379,8 +379,8 @@ const kdBuildTool = defineTool({
 	description: "按产品画像运行或预览金蝶构建命令，支持 Cosmic Java 和企业版 C# 项目。",
 	parameters: Type.Object({
 		product: Type.String({ description: "金蝶产品：cangqiong、xinghan、flagship 或 enterprise。" }),
-		target: Type.Optional(Type.String({ description: "Java 可提供 Gradle task；C# 可提供 .sln/.csproj 路径。" })),
-		dryRun: Type.Optional(Type.Boolean({ description: "只返回构建命令，不实际执行。" })),
+		target: Type.Optional(Type.String({ description: "Java 使用 Gradle task；C# 使用 .sln/.csproj 路径。" })),
+		dryRun: Type.Optional(Type.Boolean({ description: "输出构建命令预览；不实际执行。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -400,11 +400,11 @@ const kdBuildTool = defineTool({
 const kdDebugTool = defineTool({
 	name: "kd_debug",
 	label: "KD 调试",
-	description: "分析金蝶构建/运行日志或堆栈，给出可能原因和下一步检查建议。",
+	description: "分析金蝶构建/运行日志或堆栈，输出推断原因和检查指令。",
 	parameters: Type.Object({
 		text: Type.Optional(Type.String({ description: "日志文本或堆栈。与 path 二选一。" })),
 		path: Type.Optional(Type.String({ description: "日志文件路径。与 text 二选一。" })),
-		product: Type.Optional(Type.String({ description: "可选产品提示，用于补充上下文。" })),
+		product: Type.Optional(Type.String({ description: "产品上下文。" })),
 	}),
 
 	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -434,10 +434,10 @@ const kdDocReadTool = defineTool({
 	name: "kd_doc_read",
 	label: "KD 文档读取",
 	description:
-		"读取 PDF、Word (.docx/.doc)、Excel (.xlsx/.xls) 或 CSV 文件并提取文本内容。对于 .pdf、.docx、.doc、.xlsx、.xls、.csv 文件，必须使用此工具而非 read 工具，因为 read 无法解析这些二进制格式。PDF 目前只支持可复制文本抽取；扫描型 PDF 需要另行提供图片或 OCR 结果。",
+		"读取 PDF、Word (.docx/.doc)、Excel (.xlsx/.xls) 或 CSV 文件并提取文本内容。对于 .pdf、.docx、.doc、.xlsx、.xls、.csv 文件，必须使用此工具而非 read 工具，因为 read 无法解析这些二进制格式。PDF 目前仅支持可复制文本抽取；扫描型 PDF 必须另行提供图片或 OCR 结果。",
 	parameters: Type.Object({
 		path: Type.String({ description: "文档文件路径，支持 .pdf、.docx、.doc、.xlsx、.xls、.csv。" }),
-		sheet: Type.Optional(Type.String({ description: "Excel 工作表名或序号（从 1 开始）。默认读取第一个工作表。" })),
+		sheet: Type.Optional(Type.String({ description: "Excel 工作表名或序号（从 1 开始）。默认第一个工作表。" })),
 		maxRows: Type.Optional(Type.Number({ description: "Excel/CSV 最大返回行数。默认 200。" })),
 		maxPages: Type.Optional(Type.Number({ description: "PDF 最大提取页数。默认 50。" })),
 	}),
@@ -516,7 +516,7 @@ function extractXlsx(filePath: string, sheetNameOrIndex?: string, maxRows?: numb
 		} else if (sheetNames.includes(sheetNameOrIndex)) {
 			sheetName = sheetNameOrIndex;
 		} else {
-			return `[Excel] 工作表 "${sheetNameOrIndex}" 不存在。可用：${sheetNames.join(", ")}`;
+			return `[Excel] 工作表 "${sheetNameOrIndex}" 不存在。有效工作表：${sheetNames.join(", ")}`;
 		}
 	} else {
 		sheetName = sheetNames[0];

package/package.json

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

package/src/cli/kcode.ts

@@ -98,8 +98,8 @@ export function doctor(cwd: string, args: string[] = []): KcodeCliResult {
 	lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
 	lines.push(`KCode version：${packageName}@${packageVersion}`);
 	lines.push(`KCode package：${packageRoot}`);
-	lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
-	lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，请运行 kcode context"}`);
+	lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，运行 kcode init"}`);
+	lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，运行 kcode context"}`);
 
 	if (existsSync(settingsPath)) {
 		const settingsResult = readSettingsSafe(settingsPath);
@@ -199,7 +199,7 @@ export function start(cwd: string, piArgs: string[]): KcodeCliResult {
 	if (!piCli) {
 		return {
 			exitCode: 1,
-			output: `${init.output}\n未找到随包 Pi CLI 或全局 pi 命令。请重新安装 kcode-pi 后再运行 kcode start。`,
+			output: `${init.output}\n未找到随包 Pi CLI 或全局 pi 命令。重新安装 kcode-pi 后再运行 kcode start。`,
 		};
 	}
 

package/src/context/project-context.ts

@@ -69,9 +69,9 @@ export function generateProjectContext(cwd: string): string {
 		"",
 		"- 本文件是 KCode 的项目记忆，计划或编辑代码前必须读取。",
 		"- 业务需求不得生成 demo/sample/scaffold 代码。",
-		"- 不要假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
-		"- 调用文件工具时优先使用项目相对路径。在 Windows 中，不要把路径改写为 /mnt/<drive>/... 或 /<drive>/...；只有确需绝对路径时才使用 Windows 路径。",
-		"- 如果本文件过期，计划前先运行 `kcode context --refresh` 重新生成。",
+		"- 禁止假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
+		"- 调用文件工具时默认使用项目相对路径。在 Windows 中禁止把路径改写为 /mnt/<drive>/... 或 /<drive>/...；绝对路径只允许使用 Windows 路径。",
+		"- 本文件过期时，计划前运行 `kcode context --refresh` 重新生成。",
 		"- 只有 Harness 进入 `execute` 且 PLAN.md 写明真实目标路径后，才能写产品代码。",
 		"",
 		"## 项目结构摘要",

package/src/harness/artifacts.ts

@@ -3,6 +3,7 @@ import type { ActiveRun, KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS } from "./types.ts";
 import { runArtifactPath, runRoot } from "./paths.ts";
 import type { ProductProfile } from "../product/profile.ts";
+import { PLAN_REQUIRED_CHECK_LINES, formatPromptLines } from "./prompt-policy.ts";
 
 export function ensureRunDirectories(cwd: string, run: ActiveRun): void {
 	mkdirSync(runRoot(cwd, run), { recursive: true });
@@ -86,7 +87,7 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"",
 				"## 已检查的项目结构",
 				"",
-				"## 需要查看的文件",
+				"## 待读取文件",
 				"",
 				"## 目标源码根 / 路径",
 				"",
@@ -99,9 +100,7 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"",
 				"## 必需的金蝶查证项",
 				"",
-				"- Java/C# 代码涉及 SDK 类、方法、构造器、枚举、属性时，必须先用 kd_sdk_signature 或项目构建输出确认真实签名。",
-				"- 知识库搜索、随包 Cosmic API 查询只能作为线索，不能作为最终方法签名事实。",
-				"- SDK 签名证据：evidence/sdk-signature.md",
+				...formatPromptLines(PLAN_REQUIRED_CHECK_LINES),
 				"",
 				"## 需求条目 / 依赖 / 批次",
 				"",
@@ -120,12 +119,12 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"- 红灯证据：evidence/tdd-red.md",
 				"- 绿灯证据：evidence/tdd-green.md",
 				"- 红绿检查命令或工具：未知",
-				"- Java 语法/编译检查：优先使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `./gradlew :模块:build`。",
+				"- Java 语法/编译检查：使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `./gradlew :模块:build`。",
 				"- C# 语法/编译检查：使用 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。",
 				"- 允许的检查：本地 SDK 签名查证、官方 API/基类/方法查证、元数据查证、kd_check、Gradle/dotnet 构建输出、项目已有测试框架、外部接口最小验证。",
-				"- 测试框架：优先使用项目已有测试基础设施。",
+				"- 测试框架：使用项目已有测试基础设施。",
 				"- 命令无法运行时记录真实阻塞原因和残余风险，不能作为绿灯证据。",
-				"- 如果无法自动化测试，记录一个产品相关、实现前应失败且实现后应通过的检查。",
+				"- 自动化测试不可执行时，记录一个产品相关、实现前应失败且实现后应通过的检查。",
 				"- SDK 方法签名事实必须来自当前项目 jar/dll、构建输出或官方元数据。",
 				"",
 				"## 验证命令",

package/src/harness/data-source-policy.ts

@@ -0,0 +1,302 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import type { ActiveRun } from "./types.ts";
+import { readArtifact } from "./artifacts.ts";
+import { hasEvidenceEntry } from "./evidence.ts";
+import { runRoot } from "./paths.ts";
+import { isSourceLikePath } from "./path-policy.ts";
+import {
+	dataSourcePlanBlockedReason,
+	dataSourceWriteBlockedReason,
+	implementationPlanBlockedReason,
+	implementationWriteBlockedReason,
+	integrationPlanBlockedReason,
+	integrationWriteBlockedReason,
+} from "./messages.ts";
+import {
+	DATA_SOURCE_CONTEXT_FIELDS,
+	IMPLEMENTATION_CONTRACT_FIELDS,
+	INTEGRATION_CONTEXT_FIELDS,
+	type ContractField,
+} from "./prompt-policy.ts";
+
+export const COSMIC_METADATA_EVIDENCE = "evidence/cosmic-metadata.json";
+export const DATA_SOURCE_EVIDENCE = "evidence/data-source.md";
+
+const DATA_SOURCE_KEYWORDS =
+	/数据源|元数据|表单|单据|字段|实体|分录|单据体|基础资料|物料|客户|供应商|Form\s*ID|FormId|formid|DynamicObject|DataSet|SQL|KSQL|查询|保存|校验|插件|事件|操作|列表|表名|数据库|dbName|dbKey|下推|上推|转换|生成单据/i;
+const IMPLEMENTATION_KEYWORDS =
+	/插件|服务|处理器|二开|开发|实现|新增|修改|保存|校验|联动|下推|上推|转换|生成|同步|接口|审批|提交|审核|操作|按钮|定时|任务|脚本|SQL|KSQL/i;
+const INTEGRATION_KEYWORDS =
+	/第三方|外部系统|外部接口|接口对接|对接|接口文档|HTTP|HTTPS|REST|SOAP|Webhook|webhook|回调|推送|拉取|同步|上报|下发|开放平台|API\s*接口/i;
+
+const IMPLEMENTATION_FIELDS = Object.fromEntries(IMPLEMENTATION_CONTRACT_FIELDS.map((field) => [field.id, field])) as Record<string, ContractField>;
+const DATA_SOURCE_FIELDS = Object.fromEntries(DATA_SOURCE_CONTEXT_FIELDS.map((field) => [field.id, field])) as Record<string, ContractField>;
+const INTEGRATION_FIELDS = Object.fromEntries(INTEGRATION_CONTEXT_FIELDS.map((field) => [field.id, field])) as Record<string, ContractField>;
+
+export function requiresDataSourceEvidence(cwd: string, run: ActiveRun): boolean {
+	if (!run.profile?.requiresMetadataVerification) return false;
+	if (run.profile.product === "unknown") return false;
+	return DATA_SOURCE_KEYWORDS.test(dataSourcePlanningText(cwd, run, { includePlan: false })) || planDeclaresConcreteDataSourceWork(cwd, run);
+}
+
+export function dataSourceEvidenceForRun(run: ActiveRun): string | undefined {
+	if (!run.profile?.requiresMetadataVerification) return undefined;
+	if (run.profile.platform === "cosmic") return COSMIC_METADATA_EVIDENCE;
+	if (run.profile.product === "enterprise") return DATA_SOURCE_EVIDENCE;
+	return DATA_SOURCE_EVIDENCE;
+}
+
+export function hasValidDataSourceEvidence(cwd: string, run: ActiveRun): boolean {
+	const evidence = dataSourceEvidenceForRun(run);
+	if (!evidence) return true;
+	const path = join(runRoot(cwd, run), evidence);
+	if (!existsSync(path)) return false;
+	if (!hasEvidenceEntry(cwd, run, evidence)) return false;
+	if (evidence === COSMIC_METADATA_EVIDENCE) return true;
+	return dataSourceEvidenceContentLooksConcrete(readFileSync(path, "utf8"));
+}
+
+export function dataSourceProductionWriteBlockReason(cwd: string, run: ActiveRun | undefined, path: string | undefined): string | undefined {
+	if (!run || run.phase !== "execute") return undefined;
+	if (!path || !isSourceLikePath(path)) return undefined;
+
+	const normalized = normalizeRelativePath(cwd && isAbsolute(path) ? relative(cwd, path) : path);
+	if (normalized.startsWith(".pi/")) return undefined;
+
+	const implementationMissing = missingImplementationContractItems(cwd, run);
+	if (implementationMissing.length > 0) return implementationWriteBlockedReason(normalized, implementationMissing);
+
+	const integrationMissing = missingIntegrationContextItems(cwd, run);
+	if (integrationMissing.length > 0) return integrationWriteBlockedReason(normalized, integrationMissing);
+
+	if (!requiresDataSourceEvidence(cwd, run)) return undefined;
+	if (hasValidDataSourceEvidence(cwd, run)) return undefined;
+
+	return dataSourceWriteBlockedReason(normalized, dataSourceEvidenceForRun(run) ?? DATA_SOURCE_EVIDENCE);
+}
+
+export function dataSourceContextBlockReason(cwd: string, run: ActiveRun): string | undefined {
+	const implementationMissing = missingImplementationContractItems(cwd, run);
+	if (implementationMissing.length > 0) return implementationPlanBlockedReason(implementationMissing);
+
+	const integrationMissing = missingIntegrationContextItems(cwd, run);
+	if (integrationMissing.length > 0) return integrationPlanBlockedReason(integrationMissing);
+
+	if (!requiresDataSourceEvidence(cwd, run)) return undefined;
+	const missing = missingDataSourceContextItems(cwd, run);
+	return missing.length > 0 ? dataSourcePlanBlockedReason(missing) : undefined;
+}
+
+function dataSourcePlanningText(cwd: string, run: ActiveRun, options: { includePlan?: boolean } = { includePlan: true }): string {
+	return [run.goal ?? "", readArtifact(cwd, run, "spec") ?? "", options.includePlan === false ? "" : readArtifact(cwd, run, "plan") ?? ""].join("\n");
+}
+
+function planDeclaresConcreteDataSourceWork(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	const withoutBoilerplate = plan
+		.split(/\r?\n/)
+		.filter((line) => !/必须先确认真实数据源|数据源证据|进入 execute 前必须写明|不能只根据 API 文档|必需的金蝶查证项/.test(line))
+		.join("\n");
+	return DATA_SOURCE_KEYWORDS.test(withoutBoilerplate);
+}
+
+function missingImplementationContractItems(cwd: string, run: ActiveRun): string[] {
+	if (!requiresImplementationContract(cwd, run)) return [];
+	const text = dataSourcePlanningText(cwd, run);
+	const missing: string[] = [];
+
+	if (!hasTriggerOrEntry(text)) missing.push(IMPLEMENTATION_FIELDS.trigger.label);
+	if (!hasSourceObject(text)) missing.push(IMPLEMENTATION_FIELDS.source.label);
+	if (!hasTargetObject(text)) missing.push(IMPLEMENTATION_FIELDS.target.label);
+	if (!hasDataChangeContract(text)) missing.push(IMPLEMENTATION_FIELDS["data-change"].label);
+	if (!hasRuleOrCondition(text)) missing.push(IMPLEMENTATION_FIELDS.rules.label);
+	if (!hasFailureContract(text)) missing.push(IMPLEMENTATION_FIELDS.failure.label);
+	if (!hasAcceptanceSample(text)) missing.push(IMPLEMENTATION_FIELDS.acceptance.label);
+
+	return missing;
+}
+
+function requiresImplementationContract(cwd: string, run: ActiveRun): boolean {
+	if (!run.profile?.requiresMetadataVerification || run.profile.product === "unknown") return false;
+	return IMPLEMENTATION_KEYWORDS.test(dataSourcePlanningText(cwd, run, { includePlan: false })) || planDeclaresConcreteImplementationWork(cwd, run);
+}
+
+function planDeclaresConcreteImplementationWork(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	const withoutBoilerplate = plan
+		.split(/\r?\n/)
+		.filter((line) => !/实现就绪|进入 execute 前必须写明|第三方对接必须写明|必需的金蝶查证项|不要写模板代码/.test(line))
+		.join("\n");
+	return IMPLEMENTATION_KEYWORDS.test(withoutBoilerplate);
+}
+
+function missingDataSourceContextItems(cwd: string, run: ActiveRun): string[] {
+	const text = dataSourcePlanningText(cwd, run);
+	const missing: string[] = [];
+
+	if (!hasTargetObjectIdentifier(text)) missing.push(DATA_SOURCE_FIELDS["target-form"].label);
+	if (!hasPluginHook(text)) missing.push(DATA_SOURCE_FIELDS["plugin-hook"].label);
+	if (!hasFieldOrEntityIdentifier(text)) missing.push(DATA_SOURCE_FIELDS["field-entity"].label);
+	if (!hasDataAccessStrategy(text)) missing.push(DATA_SOURCE_FIELDS["data-access"].label);
+	if (usesSql(text) && !hasSqlIdentifier(text)) missing.push(DATA_SOURCE_FIELDS["sql-identifiers"].label);
+
+	return missing;
+}
+
+function hasTriggerOrEntry(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.trigger)) return true;
+	return /(?:触发入口|执行时机|触发时机|入口|事件|生命周期|插件类型|按钮|操作|定时|任务|保存前|保存后|提交后|审核后|Before\w+|After\w+)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:保存前|保存后|提交后|审核后|定时|按钮点击|操作执行)/i.test(text);
+}
+
+function hasSourceObject(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.source)) return true;
+	return /(?:源对象|源单|来源单据|来源表单|输入数据|数据来源|取数来源|源 FormId|源FormId|源表|源实体)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:从|读取|基于).{0,20}(?:单据|表单|实体|字段|DynamicObject|DataSet|SQL|KSQL)/i.test(text);
+}
+
+function hasTargetObject(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.target)) return true;
+	return /(?:目标对象|目标单据|目标表单|目标 FormId|目标FormId|输出结果|生成结果|下游单据|目标表|目标实体)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:下推到|生成|写入|更新|推送到).{0,20}(?:单据|表单|实体|字段|接口|系统|表)/i.test(text);
+}
+
+function hasDataChangeContract(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS["data-change"])) return true;
+	return /(?:数据变化|字段映射|字段对应|字段改写|修改字段|写入字段|赋值规则|转换规则|映射关系|更新字段)\s*[：:=]\s*[^。\n\r；;]{2,}|(?:字段|field).{0,20}(?:->|映射|对应|写入|修改|赋值|更新)/i.test(text);
+}
+
+function hasRuleOrCondition(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.rules)) return true;
+	return /(?:业务规则|适用条件|过滤条件|执行条件|前置条件|判断条件|范围|何时执行|哪些数据)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:当|如果|仅|只处理|满足).{0,40}(?:时|则|才)/i.test(text);
+}
+
+function hasFailureContract(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.failure)) return true;
+	return /(?:失败处理|异常处理|错误处理|回滚|补偿|人工处理|失败后|重复执行|幂等|日志|告警)\s*[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function missingIntegrationContextItems(cwd: string, run: ActiveRun): string[] {
+	const text = dataSourcePlanningText(cwd, run);
+	if (!requiresIntegrationContext(cwd, run)) return [];
+
+	const missing: string[] = [];
+	if (!hasInterfaceDocument(text)) missing.push(INTEGRATION_FIELDS["interface-doc"].label);
+	if (!hasIntegrationDirection(text)) missing.push(INTEGRATION_FIELDS.direction.label);
+	if (!hasEndpointAndAuth(text)) missing.push(INTEGRATION_FIELDS["endpoint-auth"].label);
+	if (!hasFieldMapping(text)) missing.push(INTEGRATION_FIELDS["field-mapping"].label);
+	if (!hasConcurrencyStrategy(text)) missing.push(INTEGRATION_FIELDS.concurrency.label);
+	if (!hasRetryTimeoutStrategy(text)) missing.push(INTEGRATION_FIELDS.retry.label);
+	if (!hasErrorHandlingStrategy(text)) missing.push(INTEGRATION_FIELDS.error.label);
+	if (!hasLoggingStrategy(text)) missing.push(INTEGRATION_FIELDS.logging.label);
+	if (!hasAcceptanceSample(text)) missing.push(INTEGRATION_FIELDS.samples.label);
+	return missing;
+}
+
+function requiresIntegrationContext(cwd: string, run: ActiveRun): boolean {
+	return INTEGRATION_KEYWORDS.test(dataSourcePlanningText(cwd, run, { includePlan: false })) || planDeclaresConcreteIntegrationWork(cwd, run);
+}
+
+function planDeclaresConcreteIntegrationWork(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	const withoutBoilerplate = plan
+		.split(/\r?\n/)
+		.filter((line) => !/第三方对接必须写明|接口文档来源\/版本|没有这些信息只能写模板代码|必需的金蝶查证项/.test(line))
+		.join("\n");
+	return INTEGRATION_KEYWORDS.test(withoutBoilerplate);
+}
+
+function hasInterfaceDocument(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS["interface-doc"])) return true;
+	return /(?:接口文档|API\s*文档|文档来源|协议文档|OpenAPI|Swagger)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:https?:\/\/|\.pdf|\.docx?|\.xlsx?|swagger\.json|openapi\.json)/i.test(text);
+}
+
+function hasIntegrationDirection(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.direction)) return true;
+	return /(?:对接方向|触发时机|同步方向|数据流向|调用方|被调用方)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}|(?:金蝶调用第三方|第三方调用金蝶|入站|出站|推送|拉取|回调|定时|保存后|审核后|提交后)/i.test(text);
+}
+
+function hasEndpointAndAuth(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS["endpoint-auth"])) return true;
+	return /(?:接口地址|Endpoint|URL|Base\s*URL|认证|鉴权|Token|AK|SK|AppKey|AppSecret|密钥|签名|OAuth)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasFieldMapping(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS["field-mapping"])) return true;
+	return /(?:字段映射|映射关系|字段对应|字段对照|mapping)\s*[：:=]\s*[^。\n\r；;]{2,}|(?:第三方字段|外部字段).*(?:金蝶字段|单据字段|字段标识)/is.test(text);
+}
+
+function hasConcurrencyStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.concurrency)) return true;
+	return /(?:并发|幂等|去重|唯一键|业务主键|重复提交|锁|乐观锁|重入)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasRetryTimeoutStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.retry)) return true;
+	return /(?:超时|timeout|重试|retry|限流|频率|rate\s*limit|熔断)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasErrorHandlingStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.error)) return true;
+	return /(?:错误处理|异常处理|失败处理|失败补偿|补偿|回滚|死信|告警|人工处理)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasLoggingStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.logging)) return true;
+	return /(?:日志|审计|留痕|脱敏|敏感信息|traceId|requestId|请求日志|响应日志)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasAcceptanceSample(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.acceptance) || hasLabeledValue(text, INTEGRATION_FIELDS.samples)) return true;
+	return /(?:请求样例|响应样例|报文样例|验收样例|测试数据|示例报文|payload)\s*[：:=]\s*[^。\n\r；;]{2,}/i.test(text);
+}
+
+function hasTargetObjectIdentifier(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["target-form"])) return true;
+	return /(?:Form\s*ID|FormId|formid|表单标识|单据标识|目标单据|目标表单)\s*[：:=]\s*[A-Za-z0-9_.-]{2,}|(?:单据|表单)\s*[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasPluginHook(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["plugin-hook"])) return true;
+	return /(?:插件类型|插件|事件|生命周期|触发时机|挂载点)\s*[：:=]\s*[^。\n\r，,；;]{2,}|Before\w+|After\w+|Save|保存前|保存后|提交|审核|字段值改变|F7|列表/i.test(text);
+}
+
+function hasFieldOrEntityIdentifier(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["field-entity"])) return true;
+	return /(?:字段标识|字段|实体标识|实体|分录标识|单据体标识|Entry|Entity)\s*[：:=]\s*[^。\n\r，,；;]{2,}|[A-Za-z][A-Za-z0-9_]*(?:Id|ID|No|Name|Qty|Amount)\b/.test(text);
+}
+
+function hasDataAccessStrategy(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["data-access"])) return true;
+	return /(?:读取方式|写入方式|数据访问|取数方式|数据源|读写策略)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:表单数据|模型数据|单据数据|DynamicObject|DataSet|QueryService|BusinessDataService|SQL|KSQL|直接读表|数据库查询)/i.test(text);
+}
+
+function usesSql(text: string): boolean {
+	const normalized = text.replace(/不(?:需要|使用|直接)?读表|不使用\s*(?:SQL|KSQL)|无需\s*(?:SQL|KSQL)|非\s*(?:SQL|KSQL)/gi, "");
+	return /\bSQL\b|\bKSQL\b|直接读表|数据库查询|表名/i.test(normalized);
+}
+
+function hasSqlIdentifier(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["sql-identifiers"])) return true;
+	return /(?:表名|数据库表|SQL\s*表|KSQL\s*表)\s*[：:=]\s*[A-Za-z0-9_.$-]{2,}/i.test(text) && /(?:数据库字段|SQL\s*字段|字段名|列名)\s*[：:=]\s*[A-Za-z0-9_.$,\s-]{2,}/i.test(text);
+}
+
+function dataSourceEvidenceContentLooksConcrete(content: string): boolean {
+	const text = content.trim();
+	if (text.length < 30) return false;
+	if (/待确认|未知|TODO|TBD|未提供|无数据源/i.test(text)) return false;
+	return /Form\s*ID|FormId|formid|单据|表单|字段|实体|表名|数据源|BOS|DynamicObject|DataSet|数据库|测试数据/i.test(text);
+}
+
+function normalizeRelativePath(path: string): string {
+	return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+function hasLabeledValue(text: string, field: ContractField): boolean {
+	return field.aliases.some((alias) => {
+		const escaped = escapeRegExp(alias);
+		return new RegExp(`(?:^|[\\r\\n\\-\\*\\s])${escaped}\\s*[：:=]\\s*[^\\r\\n。；;，,]{2,}`, "i").test(text);
+	});
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}