kcode-pi 0.1.20 → 0.1.24

package/docs/USER_GUIDE.md

@@ -0,0 +1,209 @@
+# KCode 用户指南
+
+本文说明 KCode 的安装、初始化、启动、模型配置和升级。Harness 阶段细节见 [Harness 工作流](HARNESS_WORKFLOW.md)，所有命令和工具参数见 [命令参考](COMMAND_REFERENCE.md)。
+
+## 安装
+
+环境要求：
+
+- Node.js `>=22.19.0`
+- npm
+- Windows 推荐使用 Windows Terminal
+- 不需要安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有业务项目或外部脚本明确依赖 Python 时才需要另行安装。
+
+全局安装：
+
+```powershell
+npm install -g kcode-pi
+```
+
+安装后使用全局命令：
+
+```powershell
+kcode
+```
+
+## 初始化业务项目
+
+先在终端进入你的实际业务项目根目录，不是 KCode 源码目录。
+
+初始化项目级配置：
+
+```powershell
+kcode init
+```
+
+`init` 会登记 KCode package，并生成项目常驻上下文：
+
+```text
+.pi/settings.json
+.pi/kd/PROJECT_CONTEXT.md
+```
+
+项目结构变化后刷新上下文：
+
+```powershell
+kcode context --refresh
+```
+
+检查环境：
+
+```powershell
+kcode doctor
+kcode doctor --deep
+```
+
+修复项目级配置：
+
+```powershell
+kcode repair
+```
+
+查看版本：
+
+```powershell
+kcode version
+```
+
+完整终端命令说明见 [命令参考](COMMAND_REFERENCE.md#终端命令)。
+
+## 启动 KCode
+
+```powershell
+kcode start
+```
+
+`kcode start` 会先确保 `.pi/settings.json` 已登记当前安装的 KCode package，然后启动随包 Pi CLI。
+
+`start` 后面的参数会原样透传给 Pi CLI：
+
+```powershell
+kcode start --provider openai --model gpt-4o
+```
+
+## 配置模型
+
+首次启动 Pi 时，如果看到：
+
+```text
+Warning: No models available.
+```
+
+说明还没有配置模型供应商。进入 `kcode start` 后输入：
+
+```text
+/login
+```
+
+选择供应商并登录或填写 API Key。常见选择包括：
+
+```text
+ChatGPT Plus/Pro (Codex)
+Claude Pro/Max
+GitHub Copilot
+OpenAI
+Anthropic
+DeepSeek
+Gemini
+```
+
+也可以在 PowerShell 中设置环境变量后再启动：
+
+```powershell
+$env:OPENAI_API_KEY="sk-..."
+kcode start
+```
+
+登录或配置完成后，在 Pi 中选择模型：
+
+```text
+/model
+```
+
+KCode 在 Pi 内注册的 `/kd-*` 命令见 [命令参考](COMMAND_REFERENCE.md#pi-内命令)。
+
+## 自定义模型供应商
+
+如果你的模型服务是企业网关、代理服务、Ollama、LM Studio、vLLM，或其他 OpenAI-compatible endpoint，不需要改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：
+
+```powershell
+notepad $env:USERPROFILE\.pi\agent\models.json
+```
+
+写入或合并：
+
+```json
+{
+  "providers": {
+    "corp-ai": {
+      "baseUrl": "https://ai.example.com/v1",
+      "api": "openai-completions",
+      "apiKey": "$CORP_AI_API_KEY",
+      "compat": {
+        "supportsDeveloperRole": false,
+        "supportsReasoningEffort": false
+      },
+      "models": [
+        {
+          "id": "corp-coder",
+          "name": "Corp Coder",
+          "reasoning": false,
+          "input": ["text"],
+          "contextWindow": 128000,
+          "maxTokens": 16384,
+          "cost": {
+            "input": 0,
+            "output": 0,
+            "cacheRead": 0,
+            "cacheWrite": 0
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+再设置 API Key 并启动：
+
+```powershell
+$env:CORP_AI_API_KEY="sk-..."
+kcode start
+```
+
+也可以直接指定：
+
+```powershell
+kcode start --provider corp-ai --model corp-coder
+```
+
+## 升级
+
+查看当前安装版本：
+
+```powershell
+kcode version
+npm ls -g kcode-pi --depth=0
+```
+
+查看 npm 最新版本：
+
+```powershell
+npm view kcode-pi version
+```
+
+升级：
+
+```powershell
+npm install -g kcode-pi@latest
+kcode version
+```
+
+升级后建议在业务项目根目录执行：
+
+```powershell
+kcode init
+kcode doctor --deep
+```
+
+如果升级失败或仍加载旧版本，见 [故障排查](TROUBLESHOOTING.md)。

package/extensions/kingdee-harness.ts

@@ -22,11 +22,8 @@ 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";
-
-const KINGDEE_INTENT_PATTERN =
-	/金蝶|苍穹|星瀚|星空|旗舰|企业版|单据|表单|列表|插件|操作插件|校验器|反写|转换|工作流|基础资料|动态对象|DynamicObject|BOS|Cosmic|IronPython|Python\s*插件|py\s*插件|kd_|KSQL/i;
+import { workflowPromptForRun } from "../src/harness/prompt.ts";
 
 function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
@@ -48,7 +45,7 @@ function parseArtifactArgs(args: string, currentPhase: KdPhase): { phase: KdPhas
 }
 
 function parseStartArgs(args: string): { goal: string; product?: string; version?: string } {
-	const tokens = args.trim().split(/\s+/).filter(Boolean);
+	const tokens = tokenizeArgs(args);
 	const goal: string[] = [];
 	let product: string | undefined;
 	let version: string | undefined;
@@ -66,7 +63,19 @@ function parseStartArgs(args: string): { goal: string; product?: string; version
 		goal.push(token);
 	}
 
-	return { goal: goal.join(" "), product, version };
+	const goalText = goal.join(" ");
+	return { goal: goalText, product, version };
+}
+
+function tokenizeArgs(args: string): string[] {
+	const tokens: string[] = [];
+	const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
+	let match: RegExpExecArray | null;
+	while ((match = pattern.exec(args)) !== null) {
+		const token = match[1] ?? match[2] ?? match[3];
+		if (token) tokens.push(token);
+	}
+	return tokens;
 }
 
 function parseProductArgs(args: string): { product: string; version?: string } | undefined {
@@ -87,7 +96,7 @@ function parseRiskArgs(args: string): { risk: KdRisk; reason: string } | undefin
 
 function shouldStartHarnessFromInput(text: string): boolean {
 	if (!text.trim() || text.trim().startsWith("/")) return false;
-	return KINGDEE_INTENT_PATTERN.test(text);
+	return true;
 }
 
 function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNullable<ReturnType<typeof readActiveRun>>, userText: string): void {
@@ -100,70 +109,6 @@ function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNul
 	if (ctx.hasUI) ctx.ui.notify("KCode 工作流消息已排队。", "info");
 }
 
-function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>, userText: string): string {
-	const status = formatStatus(cwd, run);
-	const memory = workflowMemoryForRun(cwd, run);
-	const phaseGuidance: Record<KdPhase, string> = {
-		discuss:
-			"当前处于 discuss。先使用 kd-discuss 梳理需求、产品版本、插件类型、目标单据/表单、生命周期、边界和开放问题；不要生成 demo，不要编辑产品代码。",
-		spec:
-			"当前处于 spec。先使用 kd-spec 明确验收标准、生命周期、字段/元数据/API 假设和风险；不要编辑产品代码。",
-		plan:
-			"当前处于 plan。先使用 kd-plan 检查当前项目结构，写明实际目标路径、要检查和要修改的文件、Kingdee 查证项、验证命令和回滚说明；不要编辑产品代码。",
-		execute:
-			"当前处于 execute。只能实现 PLAN.md 中批准的内容。先读取 PLAN.md 和实际项目文件，遵循既有结构写真实可用代码；不要写 demo/sample/scaffold。",
-		verify:
-			"当前处于 verify。先使用 kd-verify 收集验证证据，不要继续扩大代码改动。",
-		ship:
-			"当前处于 ship。整理发布摘要、验证证据、风险和后续事项，不要继续扩大代码改动。",
-	};
-
-	return [
-		"用户输入：",
-		userText,
-		"",
-		"KCode 项目常驻上下文：",
-		readProjectContext(cwd) ?? "未生成。请在终端运行 `kcode context --refresh` 后继续；在生成前不要猜测项目目录。",
-		"",
-		"KCode Harness 状态：",
-		status,
-		"",
-		"KCode 本次工作流本地文档：",
-		memory,
-		"",
-		`当前 active run 只属于这个功能点：${run.goal ?? run.id}。如果用户提出的是另一个功能点或无关新需求，必须停止沿用当前阶段，要求用户运行 /kd-start <新需求> 创建新 run，或 /kd-switch <run-id> 切换已有 run。`,
-		"需要用户确认时，kd_question 一次只能问一个当前最阻塞的问题；不要把 FormId、触发时机、库存条件、弹窗内容、插件位置等打包成清单。选项最多 3 个；交互模式下会弹出选择/输入对话并自动记录答案。",
-		"",
-		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；Java/C# 还必须有 SDK 签名证据 evidence/sdk-signature.md。红绿证据可以是 kd_sdk_signature 本地 SDK 签名、API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
-		"语法/编译验证必须使用真实项目构建命令：Java/Cosmic/苍穹/星空旗舰版使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `:模块:build`；C#/企业版使用 `dotnet build` 或 `dotnet build <.sln/.csproj>`。",
-		"不要写“Kingdee IDE 中编译”作为验证方式或绿灯证据；命令无法运行时，记录真实阻塞原因和残余风险，不能标记为通过。",
-		"如果门禁提示 evidence 内容无效，不要通过改写结论、补关键词或反复读取文件来过关；必须重新运行 PLAN.md 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。",
-	].join("\n");
-}
-
-function workflowMemoryForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>): string {
-	const phases = PHASE_ORDER.slice(0, PHASE_ORDER.indexOf(run.phase) + 1);
-	return phases
-		.map((phase) => {
-			const content = readArtifact(cwd, run, phase);
-			if (!content) return undefined;
-			return [`## ${phase}`, trimForPrompt(content, 6000)].join("\n");
-		})
-		.filter(Boolean)
-		.join("\n\n") || "暂无阶段文档。";
-}
-
-function trimForPrompt(content: string, maxLength: number): string {
-	if (content.length <= maxLength) return content;
-	return `${content.slice(0, maxLength)}\n\n[...文档过长，已截断；如需完整内容必须读取本地文件...]`;
-}
-
 function codeWriteBlockReason(cwd: string, path: string | undefined): string | undefined {
 	if (!path || !isSourceLikePath(path)) return undefined;
 
@@ -202,11 +147,11 @@ const kdQuestionTool = defineTool({
 	name: "kd_question",
 	label: "KD 问题",
 	description:
-		"创建、回答或列出金蝶 Harness 结构化问题。每次只能问一个最阻塞的短问题，不要批量列清单。",
+		"创建、回答或列出金蝶 Harness 结构化问题。每次只记录一个最阻塞的短问题。",
 	parameters: Type.Object({
 		action: Type.Optional(Type.String({ description: "操作类型：ask、answer 或 list，默认 ask。" })),
 		id: Type.Optional(Type.String({ description: "回答问题时的问题编号，例如 Q-001。" })),
-		question: Type.Optional(Type.String({ description: "提问内容。只能是一个短问题，不要写编号清单或多个问题。" })),
+		question: Type.Optional(Type.String({ description: "提问内容。使用一个短问题。" })),
 		answer: Type.Optional(Type.String({ description: "用户答案，action=answer 时使用。" })),
 		reason: Type.Optional(Type.String({ description: "说明为什么这个问题会阻塞当前阶段。" })),
 		choices: Type.Optional(Type.Array(Type.String(), { description: "可选项，最多 3 个简短选项。" })),
@@ -318,7 +263,7 @@ export default function (pi: ExtensionAPI) {
 			[
 				`发现未完成 KCode run：${run.goal ?? run.id}`,
 				`阶段：${run.phase}，产品：${run.profile?.product ?? run.product ?? "unknown"}`,
-				"输入 /kd-resume 可接续；输入 /kd-runs 查看其他功能点。",
+				"输入 /kd-resume 可接续；输入 /kd-runs 查看其他需求或需求组。",
 			].join("\n"),
 			"info",
 		);
@@ -333,7 +278,7 @@ export default function (pi: ExtensionAPI) {
 			if (ctx.hasUI) {
 				ctx.ui.notify(`已启动 Kingdee Harness run：${run.id}（${run.profile?.product}/${run.profile?.techStack}）`, "info");
 				if (run.profile?.product === "unknown") {
-					ctx.ui.notify("产品画像未识别。下一步先执行 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>。", "warning");
+					ctx.ui.notify("产品画像未识别。下一步先执行 /kd-product <flagship|xinghan|cangqiong|enterprise>。", "warning");
 				}
 			}
 		}
@@ -351,7 +296,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}；不要再尝试 /mnt/d 或 /d 路径。`;
+			const reason = `当前是 Windows 工作区，路径 ${path} 不是本项目使用的路径形式。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}。`;
 			if (ctx.hasUI) ctx.ui.notify(reason, "warning");
 			return { block: true, reason };
 		}
@@ -394,19 +339,19 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("kd-start", {
-		description: "启动一个 Kingdee Harness run：/kd-start [--product 产品] [--version 版本] <需求>",
+		description: "启动一个 Kingdee Harness run：/kd-start [--product 产品] [--version 版本] <需求或需求组>",
 		handler: async (args, ctx) => {
 			const parsed = parseStartArgs(args);
 			const goal = parsed.goal;
 			if (!goal) {
-				ctx.ui.notify("用法：/kd-start [--product 产品] [--version 版本] <需求>", "error");
+				ctx.ui.notify("用法：/kd-start [--product 产品] [--version 版本] <需求或需求组>", "error");
 				return;
 			}
 
 			const run = createActiveRun(ctx.cwd, goal, parsed.product, parsed.version);
 			ctx.ui.notify(`已启动 Kingdee Harness run：${run.id}（${run.profile?.product}/${run.profile?.techStack}）`, "info");
 			if (run.profile?.product === "unknown") {
-				ctx.ui.notify("产品画像未识别。下一步先执行 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>。", "warning");
+				ctx.ui.notify("产品画像未识别。下一步先执行 /kd-product <flagship|xinghan|cangqiong|enterprise>。", "warning");
 			}
 			sendWorkflowPrompt(pi, ctx, run, `继续 KCode Harness run ${run.id}：${goal}`);
 		},
@@ -461,12 +406,12 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			const finished = finishActiveRun(ctx.cwd, run);
-			ctx.ui.notify(`已完成 Kingdee Harness run：${finished.id}。下一个功能点请使用 /kd-start <需求>。`, "info");
+			ctx.ui.notify(`已完成 Kingdee Harness run：${finished.id}。下一个需求或需求组请使用 /kd-start <需求>。`, "info");
 		},
 	});
 
 	pi.registerCommand("kd-product", {
-		description: "设置当前金蝶产品画像：/kd-product <flagship|cosmic|xinghan|cangqiong|enterprise> [--version 版本]",
+		description: "设置当前金蝶产品画像：/kd-product <flagship|xinghan|cangqiong|enterprise> [--version 版本]",
 		handler: async (args, ctx) => {
 			const run = requireRun(ctx.cwd);
 			if (!run) {
@@ -476,7 +421,7 @@ export default function (pi: ExtensionAPI) {
 
 			const parsed = parseProductArgs(args);
 			if (!parsed) {
-				ctx.ui.notify("用法：/kd-product <flagship|cosmic|xinghan|cangqiong|enterprise> [--version 版本]", "error");
+				ctx.ui.notify("用法：/kd-product <flagship|xinghan|cangqiong|enterprise> [--version 版本]", "error");
 				return;
 			}
 
@@ -545,7 +490,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (parsed.content && readArtifact(ctx.cwd, run, parsed.phase) !== undefined && !parsed.replace) {
-				ctx.ui.notify(`拒绝覆盖 ${parsed.phase} 阶段文档。若确认要整体替换，请追加 --replace；追加内容应让 Agent 更新具体章节。`, "warning");
+				ctx.ui.notify(`拒绝覆盖 ${parsed.phase} 阶段文档。若确认要整体替换，请追加 --replace；追加内容应让 KCode 更新具体章节。`, "warning");
 				return;
 			}
 

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 或 cosmic。";
+	if (profile.product === "unknown") return "请先提供支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。";
 	return `当前产品 ${profile.product} 使用 ${profile.platform}/${profile.techStack}，不适用 Cosmic 官方能力。`;
 }
 
@@ -109,7 +109,7 @@ const kdSearchTool = defineTool({
 	description: "搜索 KCode 随包金蝶知识库，包括 SDK、插件生命周期、代码模式和常见实现建议。",
 	parameters: Type.Object({
 		query: Type.String({ description: "要搜索的关键词、API、类名、表名或生命周期术语。" }),
-		product: Type.Optional(Type.String({ description: "金蝶产品：flagship、cosmic、xinghan、cangqiong 或 enterprise。" })),
+		product: Type.Optional(Type.String({ description: "金蝶产品：flagship、xinghan、cangqiong 或 enterprise。" })),
 		edition: Type.Optional(Type.String({ description: "旧参数，等同于 product。优先使用 product。" })),
 		limit: Type.Optional(Type.Number({ description: "最大结果数，默认 5。" })),
 	}),
@@ -120,7 +120,7 @@ const kdSearchTool = defineTool({
 		if (!scopes) {
 			const guidance =
 				profile.product === "unknown"
-					? "请先提供 product，例如 flagship、enterprise、cosmic、xinghan 或 cangqiong。"
+					? "请先提供 product，例如 flagship、enterprise、xinghan 或 cangqiong。"
 					: "当前产品画像未配置可搜索知识范围。";
 			return {
 				content: [
@@ -152,7 +152,7 @@ const kdTableTool = defineTool({
 	description: "按表名查询 KCode 随包金蝶表结构，查询结果受产品画像约束。",
 	parameters: Type.Object({
 		table: Type.String({ description: "表名，例如 T_PUR_POORDER。" }),
-		product: Type.Optional(Type.String({ description: "金蝶产品：flagship、cosmic、xinghan、cangqiong 或 enterprise。" })),
+		product: Type.Optional(Type.String({ description: "金蝶产品：flagship、xinghan、cangqiong 或 enterprise。" })),
 		edition: Type.Optional(Type.String({ description: "旧参数，等同于 product。优先使用 product。" })),
 	}),
 
@@ -236,7 +236,7 @@ const kdCosmicConfigTool = defineTool({
 	label: "KD Cosmic 配置",
 	description: "运行 Cosmic 家族金蝶产品的官方能力配置预检查。",
 	parameters: Type.Object({
-		product: Type.String({ description: "Cosmic 家族产品：cangqiong、xinghan、flagship 或 cosmic。" }),
+		product: Type.String({ description: "支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。" }),
 		config: Type.Optional(Type.String({ description: "可选 ok-cosmic.json 路径。默认按当前工作目录解析。" })),
 		dryRun: Type.Optional(Type.Boolean({ description: "只返回命令，不实际执行。" })),
 	}),
@@ -254,7 +254,7 @@ const kdCosmicMetadataTool = defineTool({
 	label: "KD Cosmic 元数据",
 	description: "查询官方 Cosmic 表单/单据元数据，包括字段、枚举值、操作和 SQL 表信息。",
 	parameters: Type.Object({
-		product: Type.String({ description: "Cosmic 家族产品：cangqiong、xinghan、flagship 或 cosmic。" }),
+		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: "可选字段关键词，用空格或逗号分隔。" })),
@@ -278,7 +278,7 @@ const kdCosmicApiTool = defineTool({
 	label: "KD Cosmic API",
 	description: "查询随包 Cosmic API 知识，获取类和方法线索；最终签名事实应以 kd_sdk_signature 或项目构建输出为准。",
 	parameters: Type.Object({
-		product: Type.String({ description: "Cosmic 家族产品：cangqiong、xinghan、flagship 或 cosmic。" }),
+		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 路径。" })),
@@ -346,7 +346,7 @@ const kdKsqlLintTool = defineTool({
 	label: "KD KSQL 检查",
 	description: "对生成的 KSQL/SQL 文件运行官方 ok-ksql lint 检查。",
 	parameters: Type.Object({
-		product: Type.String({ description: "Cosmic 家族产品：cangqiong、xinghan、flagship 或 cosmic。" }),
+		product: Type.String({ description: "支持 Cosmic 平台能力的产品：cangqiong、xinghan 或 flagship。" }),
 		path: Type.String({ description: "SQL/KSQL 文件路径，可为工作区相对路径或绝对路径。" }),
 		dryRun: Type.Optional(Type.Boolean({ description: "只返回命令，不实际执行。" })),
 	}),
@@ -364,7 +364,7 @@ const kdBuildTool = defineTool({
 	label: "KD 构建",
 	description: "按产品画像运行或预览金蝶构建命令，支持 Cosmic Java 和企业版 C# 项目。",
 	parameters: Type.Object({
-		product: Type.String({ description: "金蝶产品：cangqiong、xinghan、flagship、cosmic 或 enterprise。" }),
+		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: "只返回构建命令，不实际执行。" })),
 	}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.20",
+  "version": "0.1.24",
   "description": "面向金蝶开发的 Pi Coding Agent 启动器、工具包和 Harness 工作流",
   "type": "module",
   "private": false,
@@ -63,7 +63,7 @@
     "smoke:build-debug": "tsx scripts/smoke-build-debug.ts",
     "smoke:sdk-signature": "tsx scripts/smoke-sdk-signature.ts",
     "smoke:package": "tsx scripts/smoke-package.ts",
-    "smoke:kcode-cli": "tsx scripts/smoke-kcode-cli.ts",
+    "smoke:kcode-command": "tsx scripts/smoke-kcode-command.ts",
     "release:check": "tsx scripts/release-check.ts",
     "kcode": "tsx scripts/kcode.ts",
     "prepack": "npm run build:cli && npm run smoke:package"

package/prompts/kd-discuss.md

@@ -8,4 +8,9 @@ description: 开始或继续金蝶 Harness 工作流的需求讨论阶段。
 
 {{args}}
 
-请把业务目标、金蝶产品/版本、技术栈、插件类型、目标单据/表单/实体、非目标范围和待确认问题记录到 `CONTEXT.md`。
+请先读取并理解需求来源，再自行判断这是单需求还是需求组。
+
+- 单需求：记录业务目标、可判断的产品/版本、技术栈、目标对象、非目标范围和待确认问题。
+- 需求组：从原始文档抽取需求条目、验收标准、优先级、依赖、批次、共同约束和待确认问题。
+
+不要因为正文里出现产品词就直接落产品画像；只有用户显式指定、文档证据充分，或进入具体产品实现前确认后，才写成已确认产品。

package/prompts/kd-execute.md

@@ -4,9 +4,9 @@ description: 在 Harness 门禁约束下执行当前金蝶实施计划。
 
 使用 `kd-execute` skill。
 
-编辑代码前，先使用 `kd_plan_status` 检查当前 run。如果缺少 `PLAN.md`、`evidence/sdk-signature.md` 或门禁被阻塞，必须停止并说明缺少的文档或证据。通过后只实现 `PLAN.md` 批准的内容，并更新 `EXECUTION.md`。禁止凭记忆、模型知识或随包知识库猜 SDK 方法签名。
+先检查当前 run 和门禁。通过后只实现 `PLAN.md` 批准的内容，更新 `EXECUTION.md`，并按计划记录红绿 evidence。
 
-实现后要按计划运行真实构建检查语法问题：Java 使用当前项目 Gradle 命令，例如 `.\gradlew.bat build` 或 `.\gradlew.bat :模块:build`；C# 使用 `dotnet build` 或 `dotnet build <.sln/.csproj>`。不能写“Kingdee IDE 中编译”作为验证结果；命令未运行就不能记录为绿灯证据。
+实现后运行计划中的验证命令；命令无法运行时记录阻塞原因和残余风险。
 
 用户补充说明：
 

package/prompts/kd-plan.md

@@ -4,13 +4,9 @@ description: 为当前金蝶 Harness run 编写实施计划。
 
 使用 `kd-plan` skill。
 
-读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。必须包含已检查的项目结构、需要查看的文件、预计修改的真实路径、必须查证的金蝶 API/元数据、SDK 签名证据、验证命令和回滚说明。Java/C# SDK 方法签名必须来自 `kd_sdk_signature` 当前项目 jar/dll、项目构建输出或官方元数据，不能凭记忆猜。
+读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。重点写清：项目结构、目标路径、允许修改文件、SDK/元数据查证、验证命令和回滚说明。
 
-验证命令必须贴近真实项目：
-
-- Java / Cosmic / 苍穹 / 星空旗舰版：优先使用当前项目 Gradle 构建做语法和编译检查，例如 `./gradlew build`、`./gradlew :模块:build` 或 Windows 下的 `.\gradlew.bat build`。
-- C# / 企业版：使用 `dotnet build` 或 `dotnet build <.sln/.csproj>` 做语法和编译检查。
-- 不要写“Kingdee IDE 中编译”。如果当前机器缺少依赖导致命令无法运行，要记录真实阻塞原因，不能把未执行的编译当作绿灯证据。
+验证命令按产品选择：Cosmic Java 用当前项目 Gradle；企业版 C# 用 `dotnet build`。命令无法运行时记录阻塞原因和应运行的具体命令。
 
 用户补充说明：
 

package/prompts/kd-verify.md

@@ -4,13 +4,7 @@ description: 验证当前金蝶实现并收集证据。
 
 使用 `kd-verify` skill。
 
-执行计划中的验证命令，收集证据，运行可用检查，并更新 `VERIFY.md`。如果某项验证无法运行，记录具体阻塞原因和残余风险。
-
-验证优先使用真实构建命令检查语法和编译：
-
-- Java / Cosmic / 苍穹 / 星空旗舰版：运行当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`.\gradlew.bat :模块:build` 或同等 Gradle task。
-- C# / 企业版：运行 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。
-- 绿灯证据必须包含实际命令、`Exit: 0` 和输出摘要。不能用“Kingdee IDE 中编译”“需在开发环境验证”替代真实证据。
+执行 `PLAN.md` 中的验证命令，收集 evidence，并更新 `VERIFY.md`。成功证据记录命令、`Exit: 0` 和输出摘要；命令无法运行时记录阻塞原因和残余风险。
 
 用户补充说明：
 

package/skills/kd-cosmic-dev/SKILL.md

@@ -1,13 +1,12 @@
 ---
 name: kd-cosmic-dev
-description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、星瀚、星空旗舰版和共享 Cosmic 平台。处理表单、单据、列表、操作、转换、任务、工作流、OpenAPI、元数据、DynamicObject、附件、基础资料、SDK 方法签名等 Cosmic 体系开发时使用。
+description: 金蝶苍穹/Cosmic 平台 Java 插件开发技能，适用于苍穹、星瀚和星空旗舰版。处理表单、单据、列表、操作、转换、任务、工作流、OpenAPI、元数据、DynamicObject、附件、基础资料、SDK 方法签名等平台能力开发时使用。
 ---
 
 # 金蝶 Cosmic 开发
 
-当需要为 Cosmic 体系产品实现或修改 Java 代码时使用本技能：
+当需要为以下产品实现或修改 Java 代码时使用本技能：
 
-- `cosmic`
 - `cangqiong`
 - `xinghan`
 - `flagship`
@@ -19,7 +18,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 生成或修改代码前：
 
 - 先用 `kd_plan_status` 查看当前运行状态。
-- 确认产品画像属于 Cosmic 体系。
+- 确认产品画像是 `cangqiong`、`xinghan` 或 `flagship`。
 - 执行阶段必须已有 `PLAN.md`。
 - Cosmic 代码生成前必须运行 `kd_cosmic_config`。如果配置检查失败，停止编码并说明缺失配置。
 
@@ -53,7 +52,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 4. 只有插件类型、生命周期方法、字段元数据和 API 签名都明确后，才生成或修改代码。
    - 遵循项目已有包名、基类、常量、日志风格和 helper 封装。
    - 星空旗舰版项目先检查当前目录结构，再选择真实目标路径。若存在 `code/`，跟随 `code/` 下既有组织；若不存在，跟随已发现的源码根或目标文件，不要在项目根目录新建 `src/main/java`。
-   - 优先使用项目本地封装和已批准的 Cosmic helper，再考虑底层 BOS API。
+   - 优先使用项目本地封装和已批准的苍穹/Cosmic 平台 helper，再考虑底层 BOS API。
    - 事件处理器只做当前事件阶段该做的事。
 
 5. 验证结果。
@@ -64,7 +63,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 ## 硬性规则
 
 - 不臆造字段 key、表单 ID、操作名、枚举值、表名或 SDK 方法；本地 SDK 查不到且编译未验证时，不把知识库结果当作最终签名事实。
-- 不把 Enterprise C# 命名空间或生命周期假设用于 Cosmic Java。
+- 不把 Enterprise C# 命名空间或生命周期假设用于苍穹/Cosmic 平台 Java。
 - 星空旗舰版不允许猜目录或写 demo/sample；如果无法判断真实代码位置，先询问或更新计划，不要直接创建新目录。
 - 不在数据绑定前的初始化阶段操作 UI 控件。
 - 不在平台期望修改入参数据实体的事务钩子里另起保存。

package/skills/kd-cosmic-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: kd-cosmic-review
-description: 金蝶 Cosmic 体系 Java 插件和 KSQL 代码审查技能，按官方审查优先级检查代码质量、生命周期、事务、性能、安全、DataSet 泄漏、校验器/操作/表单/列表/转换插件和 KSQL 风险。适用于 Cosmic、苍穹、星瀚、星空旗舰版项目。
+description: 金蝶苍穹/Cosmic 平台 Java 插件和 KSQL 代码审查技能，按官方审查优先级检查代码质量、生命周期、事务、性能、安全、DataSet 泄漏、校验器/操作/表单/列表/转换插件和 KSQL 风险。适用于苍穹、星瀚、星空旗舰版项目。
 ---
 
 # 金蝶 Cosmic 审查
 
-本技能用于审查 Cosmic 体系 Java 或 KSQL 变更。除非用户明确要求修复，否则只做审查，不直接改代码。
+本技能用于审查苍穹/Cosmic 平台 Java 或 KSQL 变更。除非用户明确要求修复，否则只做审查，不直接改代码。
 
 不要把本技能用于 Enterprise C# 代码；Enterprise 使用通用金蝶检查流程。
 

package/skills/kd-cosmic-unittest/SKILL.md

@@ -79,7 +79,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 写完测试后：
 
 - 使用 `kd_build` 或计划中的命令运行最窄可行 Gradle test 任务。
-- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task；不要写“在 IDE 中运行”作为验证结论。
+- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task。
 - 存在 harness run 时，把测试文件和验证结果写入 `.pi/kd/runs/<run-id>/EXECUTION.md`。
 
 ## 输出要求

package/skills/kd-execute/SKILL.md

@@ -24,5 +24,5 @@ Rules:
 - Before entering verify, rerun the same check and record passing output in `evidence/tdd-green.md`.
 - After implementation, run the planned real build command for syntax/compile validation when available: Java uses the project Gradle command such as `.\gradlew.bat build` or `.\gradlew.bat :module:build`; C# uses `dotnet build` or `dotnet build <.sln/.csproj>`.
 - Do not add JUnit, Mockito, NUnit, xUnit, or any extra test jar/framework only to satisfy the gate. Use existing approved project test infrastructure if it already exists.
-- Do not record "compile in Kingdee IDE" or "needs local development environment verification" as green evidence. If the command cannot run, record the blocker instead of marking verification passed.
+- If the command cannot run, record the blocker instead of marking verification passed.
 - If implementation needs a plan change, update `PLAN.md` first.