kcode-pi 0.1.19 → 0.1.23

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

@@ -25,9 +25,6 @@ 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;
-
 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 {
@@ -103,20 +112,7 @@ function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNul
 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。整理发布摘要、验证证据、风险和后续事项，不要继续扩大代码改动。",
-	};
+	const phaseGuidance = phaseGuidanceForRun(run);
 
 	return [
 		"用户输入：",
@@ -131,10 +127,12 @@ function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof re
 		"KCode 本次工作流本地文档：",
 		memory,
 		"",
-		`当前 active run 只属于这个功能点：${run.goal ?? run.id}。如果用户提出的是另一个功能点或无关新需求，必须停止沿用当前阶段，要求用户运行 /kd-start <新需求> 创建新 run，或 /kd-switch <run-id> 切换已有 run。`,
+		"需求来源处理：如果用户输入的是本地文件路径，先读取该文件并抽取需求；如果是目录，先列出候选需求文档再读取最相关文件；如果是在线文档链接，先尝试访问或导出可读内容。遇到登录、权限或防下载限制时，只问一个最阻塞问题：请用户提供可访问链接、导出文件路径或关键内容。不要要求用户改写成 KCode 专用格式。",
+		"",
+		`当前 active run 对应本次需求目标：${run.goal ?? run.id}。如果用户补充的是同一目标下的需求文档或细节，先纳入当前阶段文档；如果是无关目标，再要求用户运行 /kd-start <新需求> 创建新 run，或 /kd-switch <run-id> 切换已有 run。`,
 		"需要用户确认时，kd_question 一次只能问一个当前最阻塞的问题；不要把 FormId、触发时机、库存条件、弹窗内容、插件位置等打包成清单。选项最多 3 个；交互模式下会弹出选择/输入对话并自动记录答案。",
 		"",
-		phaseGuidance[run.phase],
+		phaseGuidance,
 		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
 		"禁止凭记忆、模型知识或随包知识库直接编写 SDK 方法调用。Java/C# 代码中出现的 SDK 类、方法、构造器、枚举和属性，必须来自 kd_sdk_signature 对当前项目 jar/dll 的成功结果、项目构建输出或官方元数据证据。",
 		"kd_search、kd_cosmic_api 和随包知识只能用于找线索；没有 evidence/sdk-signature.md 或明确构建证据时，不得进入 execute，也不得写生产源码。",
@@ -147,6 +145,24 @@ function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof re
 	].join("\n");
 }
 
+function phaseGuidanceForRun(run: NonNullable<ReturnType<typeof readActiveRun>>): string {
+	const guidance: Record<KdPhase, string> = {
+		discuss:
+			"当前处于 discuss。先理解需求来源，判断是一条需求还是一组需求；梳理可确认事实、边界、开放问题和后续需要验证的产品信息；不要编辑产品代码。",
+		spec:
+			"当前处于 spec。先把需求写成可验收条目；如果是一组需求，明确每条需求的验收标准、依赖、风险和批次关系；不要编辑产品代码。",
+		plan:
+			"当前处于 plan。先检查当前项目结构，写明真实目标路径、允许修改文件、查证项、验证命令和回滚说明；如果是一组需求，按批次组织计划；必须明确声明是否涉及产品实现、构建、元数据或 SDK 查证；不要编辑产品代码。",
+		execute:
+			"当前处于 execute。只能实现 PLAN.md 中批准的内容和文件。先读取 PLAN.md 和实际项目文件，遵循既有结构写真实可用代码；不要写 demo/sample/scaffold。",
+		verify:
+			"当前处于 verify。先使用 kd-verify 收集验证证据，不要继续扩大代码改动。",
+		ship:
+			"当前处于 ship。整理发布摘要、验证证据、风险和后续事项，不要继续扩大代码改动。",
+	};
+	return guidance[run.phase];
+}
+
 function workflowMemoryForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>): string {
 	const phases = PHASE_ORDER.slice(0, PHASE_ORDER.indexOf(run.phase) + 1);
 	return phases
@@ -318,7 +334,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 +349,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");
 				}
 			}
 		}
@@ -394,19 +410,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 +477,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 +492,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 +561,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-header.ts

@@ -1,26 +1,35 @@
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { inspectGate } from "../src/harness/gates.ts";
 import { readActiveRun } from "../src/harness/state.ts";
-import type { ActiveRun } from "../src/harness/types.ts";
+import type { ActiveRun, GateResult } from "../src/harness/types.ts";
 import { formatProductProfile } from "../src/product/profile.ts";
 
 function formatProduct(run: ActiveRun | undefined): string {
-	return run ? formatProductProfile(run.profile) : "未选择";
+	if (!run) return "未选择";
+	if (run.profile?.product === "unknown") return "未确认";
+	return formatProductProfile(run.profile);
 }
 
 function formatPhase(phase: ActiveRun["phase"] | undefined): string {
 	return phase ?? "空闲";
 }
 
-function formatGate(run: ActiveRun | undefined): string {
-	if (!run?.gate) return "门禁：待检查";
-	if (run.gate.passed) return "门禁：通过";
-	return `门禁：阻塞${run.gate.reason ? ` - ${run.gate.reason}` : ""}`;
+function formatGate(gate: GateResult | undefined): string {
+	if (!gate) return "门禁：待检查";
+	return gate.passed ? "门禁：通过" : "门禁：阻塞";
 }
 
 function riskLevel(run: ActiveRun | undefined): string {
 	return run?.riskAssessment?.level ?? "未知";
 }
 
+function riskColor(risk: string): "error" | "warning" | "muted" | "success" {
+	if (risk === "high") return "error";
+	if (risk === "medium") return "warning";
+	if (risk === "未知") return "muted";
+	return "success";
+}
+
 function padOrTrim(text: string, width: number): string {
 	if (width <= 0) return "";
 	if (text.length > width) return text.slice(0, Math.max(0, width - 1)) + ">";
@@ -45,9 +54,10 @@ export default function (pi: ExtensionAPI) {
 			return {
 				render(width: number): string[] {
 					const run = readActiveRun(ctx.cwd);
+					const gateState = run ? inspectGate(ctx.cwd, run) : undefined;
 					const phase = formatPhase(run?.phase);
 					const product = formatProduct(run);
-					const gate = formatGate(run);
+					const gate = formatGate(gateState);
 					const risk = riskLevel(run);
 					const runId = run?.id ?? "无";
 
@@ -57,9 +67,9 @@ export default function (pi: ExtensionAPI) {
 						theme.fg("muted", " | 产品："),
 						theme.fg("text", product),
 						theme.fg("muted", " | 风险："),
-						theme.fg(risk === "high" ? "error" : risk === "medium" ? "warning" : "success", risk),
+						theme.fg(riskColor(risk), risk),
 						theme.fg("muted", " | "),
-						theme.fg(run?.gate?.passed === false ? "error" : "muted", gate),
+						theme.fg(gateState?.passed === false ? "error" : "muted", gate),
 					].join("");
 
 					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.19",
+  "version": "0.1.23",
   "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-plan.md

@@ -4,11 +4,11 @@ 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 查证、必须查证的金蝶 API/元数据、SDK 签名证据、验证命令和回滚说明。Java/C# SDK 方法签名必须来自 `kd_sdk_signature` 当前项目 jar/dll、项目构建输出或官方元数据，不能凭记忆猜。
 
 验证命令必须贴近真实项目：
 
-- Java / Cosmic / 苍穹 / 星空旗舰版：优先使用当前项目 Gradle 构建做语法和编译检查，例如 `./gradlew build`、`./gradlew :模块:build` 或 Windows 下的 `.\gradlew.bat build`。
+- 苍穹 / 星瀚 / 星空旗舰版 Java：优先使用当前项目 Gradle 构建做语法和编译检查，例如 `./gradlew build`、`./gradlew :模块:build` 或 Windows 下的 `.\gradlew.bat build`。
 - C# / 企业版：使用 `dotnet build` 或 `dotnet build <.sln/.csproj>` 做语法和编译检查。
 - 不要写“Kingdee IDE 中编译”。如果当前机器缺少依赖导致命令无法运行，要记录真实阻塞原因，不能把未执行的编译当作绿灯证据。
 

package/prompts/kd-verify.md

@@ -8,7 +8,7 @@ description: 验证当前金蝶实现并收集证据。
 
 验证优先使用真实构建命令检查语法和编译：
 
-- Java / Cosmic / 苍穹 / 星空旗舰版：运行当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`.\gradlew.bat :模块:build` 或同等 Gradle task。
+- 苍穹 / 星瀚 / 星空旗舰版 Java：运行当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`.\gradlew.bat :模块:build` 或同等 Gradle task。
 - C# / 企业版：运行 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。
 - 绿灯证据必须包含实际命令、`Exit: 0` 和输出摘要。不能用“Kingdee IDE 中编译”“需在开发环境验证”替代真实证据。
 

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 使用通用金蝶检查流程。