kcode-pi 0.1.31 → 0.1.35

package/extensions/kingdee-tools.ts

@@ -1,6 +1,6 @@
-import { dirname, join } from "node:path";
+import { dirname, join, extname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
+import { readFileSync, readFile as fsReadFile } 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";
@@ -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) {
@@ -430,6 +430,133 @@ const kdDebugTool = defineTool({
 	},
 });
 
+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 结果。",
+	parameters: Type.Object({
+		path: Type.String({ description: "文档文件路径，支持 .pdf、.docx、.doc、.xlsx、.xls、.csv。" }),
+		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。" })),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const filePath = resolveWorkspacePath(ctx.cwd, params.path);
+		const ext = extname(filePath).toLowerCase();
+
+		try {
+			let text: string;
+
+			if (ext === ".pdf") {
+				text = await extractPdf(filePath, params.maxPages ?? 50);
+			} else if (ext === ".docx") {
+				text = await extractDocx(filePath);
+			} else if (ext === ".doc") {
+				text = await extractDoc(filePath);
+			} else if (ext === ".xlsx" || ext === ".xls") {
+				text = extractXlsx(filePath, params.sheet, params.maxRows ?? 200);
+			} else if (ext === ".csv") {
+				text = extractCsv(filePath, params.maxRows ?? 200);
+			} else {
+				return {
+					content: [{ type: "text", text: `不支持的文件格式：${ext}。支持 .pdf、.docx、.doc、.xlsx、.xls、.csv。` }],
+					details: { error: "unsupported-format", ext },
+				};
+			}
+
+			return {
+				content: [{ type: "text", text }],
+				details: { path: params.path, format: ext },
+			};
+		} catch (error) {
+			return {
+				content: [{ type: "text", text: `读取文档失败：${error instanceof Error ? error.message : String(error)}` }],
+				details: { error: "doc-read-failed", path: params.path },
+			};
+		}
+	},
+});
+
+async function extractPdf(filePath: string, maxPages: number): Promise<string> {
+	const { PDFParse } = await import("pdf-parse");
+	const buffer = readFileSync(filePath);
+	const parser = new PDFParse({ data: new Uint8Array(buffer) });
+	const result = await parser.getText({ last: maxPages });
+	const pages = result.total;
+	const text = result.text.trim();
+	return `[PDF] ${pages} 页\n\n${text}`;
+}
+
+async function extractDocx(filePath: string): Promise<string> {
+	const mammoth = await import("mammoth");
+	const buffer = readFileSync(filePath);
+	const result = await mammoth.extractRawText({ buffer });
+	return `[Word .docx]\n\n${result.value.trim()}`;
+}
+
+async function extractDoc(filePath: string): Promise<string> {
+	const word = await import("word");
+	const doc = await word.readFile(filePath);
+	const text = word.to_text(doc);
+	return `[Word .doc]\n\n${text.trim()}`;
+}
+
+function extractXlsx(filePath: string, sheetNameOrIndex?: string, maxRows?: number): string {
+	const XLSX = require("xlsx");
+	const workbook = XLSX.readFile(filePath);
+	const sheetNames = workbook.SheetNames;
+
+	let sheetName: string;
+	if (sheetNameOrIndex) {
+		const idx = Number(sheetNameOrIndex);
+		if (!isNaN(idx) && idx >= 1 && idx <= sheetNames.length) {
+			sheetName = sheetNames[idx - 1];
+		} else if (sheetNames.includes(sheetNameOrIndex)) {
+			sheetName = sheetNameOrIndex;
+		} else {
+			return `[Excel] 工作表 "${sheetNameOrIndex}" 不存在。有效工作表：${sheetNames.join(", ")}`;
+		}
+	} else {
+		sheetName = sheetNames[0];
+	}
+
+	const sheet = workbook.Sheets[sheetName];
+	const rows: Record<string, unknown>[] = XLSX.utils.sheet_to_json(sheet, { defval: "" });
+	const limit = Math.min(rows.length, maxRows ?? 200);
+
+	if (rows.length === 0) return `[Excel] 工作表 "${sheetName}" 为空。`;
+
+	const headers = Object.keys(rows[0]);
+	const lines: string[] = [
+		`[Excel] 工作表：${sheetName}（${sheetNames.length} 个：${sheetNames.join(", ")}）`,
+		`行数：${rows.length}${rows.length > limit ? `（显示前 ${limit} 行）` : ""}`,
+		"",
+		"| " + headers.join(" | ") + " |",
+		"| " + headers.map(() => "---").join(" | ") + " |",
+	];
+
+	for (let i = 0; i < limit; i++) {
+		const row = rows[i];
+		lines.push("| " + headers.map((h) => String(row[h] ?? "")).join(" | ") + " |");
+	}
+
+	return lines.join("\n");
+}
+
+function extractCsv(filePath: string, maxRows: number): string {
+	const XLSX = require("xlsx");
+	const workbook = XLSX.readFile(filePath, { raw: true });
+	const sheetName = workbook.SheetNames[0];
+	const sheet = workbook.Sheets[sheetName];
+	const csv = XLSX.utils.sheet_to_csv(sheet);
+	const lines = csv.split("\n");
+	const limit = Math.min(lines.length, maxRows + 1); // +1 for header
+	const truncated = lines.length > limit;
+	return `[CSV] ${lines.length - 1} 行${truncated ? `（显示前 ${limit - 1} 行）` : ""}\n\n${lines.slice(0, limit).join("\n")}`;
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdSearchTool);
 	pi.registerTool(kdTableTool);
@@ -441,6 +568,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdKsqlLintTool);
 	pi.registerTool(kdBuildTool);
 	pi.registerTool(kdDebugTool);
+	pi.registerTool(kdDocReadTool);
 }
 
 function writeSdkSignatureEvidence(cwd: string, content: string): string | undefined {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.31",
+  "version": "0.1.35",
   "description": "面向金蝶开发的 Pi Coding Agent 启动器、工具包和 Harness 工作流",
   "type": "module",
   "private": false,
@@ -47,7 +47,11 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.78.1",
-    "@earendil-works/pi-coding-agent": "^0.78.1"
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "mammoth": "^1.12.0",
+    "pdf-parse": "^2.4.5",
+    "word": "^0.4.0",
+    "xlsx": "^0.18.5"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",

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、构建输出或官方元数据。",
 				"",
 				"## 验证命令",