kcode-pi 0.1.34 → 0.1.38

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.38",
   "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

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
+import { PROJECT_PERSISTENT_RULES, formatPromptLines } from "../harness/prompt-policy.js";
 
 const IGNORED_DIRS = new Set([
 	".git",
@@ -67,11 +68,9 @@ export function generateProjectContext(cwd: string): string {
 		"",
 		"## 持久规则",
 		"",
-		"- 本文件是 KCode 的项目记忆，计划或编辑代码前必须读取。",
-		"- 业务需求不得生成 demo/sample/scaffold 代码。",
-		"- 不要假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
-		"- 调用文件工具时优先使用项目相对路径。在 Windows 中，不要把路径改写为 /mnt/<drive>/... 或 /<drive>/...；只有确需绝对路径时才使用 Windows 路径。",
-		"- 如果本文件过期，计划前先运行 `kcode context --refresh` 重新生成。",
+		...formatPromptLines(PROJECT_PERSISTENT_RULES),
+		"- 禁止假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
+		"- 调用文件工具时默认使用项目相对路径。在 Windows 中禁止把路径改写为 /mnt/<drive>/... 或 /<drive>/...；绝对路径只允许使用 Windows 路径。",
 		"- 只有 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、构建输出或官方元数据。",
 				"",
 				"## 验证命令",