kcode-pi 0.1.6 → 0.1.7

package/README.md

@@ -414,10 +414,26 @@ kd_debug            分析金蝶日志和堆栈
 这些工具不依赖本机 Python：
 
 - `kd_ksql_lint` 是内置 Node 静态检查器。
-- `kd_cosmic_config` 使用 Node 读取并校验 `ok-cosmic.json`。
-- `kd_cosmic_metadata` 使用 `ok-cosmic.json` 中的统一路由 API，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
+- `kd_cosmic_config` 使用 Node 校验 Cosmic 官方能力配置；项目没有 `ok-cosmic.json` 时会自动使用 KCode 随包默认配置。
+- `kd_cosmic_metadata` 使用统一路由 API 查询真实单据/表单元数据，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
 - `kd_cosmic_api` 查询随包金蝶知识库；需要精确方法签名时，仍要结合当前项目 SDK、编译输出或红绿证据确认。
 
+`ok-cosmic.json` 是可选的 KCode 官方能力覆盖配置，不是苍穹工程模板里的 `cosmic.json`。业务项目里的 `cosmic.json` 通常只包含开发者标识、工程标识、MC 资源地址等运行环境信息，不能替代 `ok-cosmic.json`。
+
+只有需要指定企业统一路由 API 或覆盖知识库路径时，才需要在业务项目根目录创建 `ok-cosmic.json`：
+
+```json
+{
+  "graph": {
+    "dbPath": "D:\\path\\to\\ok-cosmic-docs.db"
+  },
+  "route": {
+    "apiUrl": "https://your-runtime-route.example.com/api",
+    "timeoutSeconds": 10
+  }
+}
+```
+
 ## 升级
 
 查看当前安装版本：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,

package/src/official/kingdee-skills.ts

@@ -109,8 +109,8 @@ export async function runOfficialCommand(command: OfficialCommand): Promise<Comm
 export async function cosmicConfigCommand(cwd: string, config?: string): Promise<OfficialCommand> {
 	await ensureOfficialSkillRoot(cwd, "ok-cosmic");
 	const configPath = resolveConfigPath(cwd, config);
-	const display = formatCommand("kcode-node:cosmic-config", config ? ["--config", configPath] : []);
-	return officialCommand(display, () => runCosmicConfig(cwd, configPath));
+	const display = formatCommand("kcode-node:cosmic-config", config && configPath ? ["--config", configPath] : []);
+	return officialCommand(display, () => runCosmicConfig(cwd, configPath, Boolean(config)));
 }
 
 export async function cosmicMetadataCommand(
@@ -133,7 +133,7 @@ export async function cosmicMetadataCommand(
 	if (params.fuzzy) args.push("--fuzzy", ...splitTerms(params.fuzzy));
 	if (params.typeFilter) args.push("--type", params.typeFilter);
 	const configPath = resolveConfigPath(cwd, params.config);
-	return officialCommand(formatCommand("kcode-node:cosmic-metadata", args), () => runCosmicMetadata(cwd, configPath, params));
+	return officialCommand(formatCommand("kcode-node:cosmic-metadata", args), () => runCosmicMetadata(cwd, configPath, Boolean(params.config), params));
 }
 
 export async function cosmicApiCommand(
@@ -219,8 +219,10 @@ function officialCommand(display: string, run: () => Promise<Omit<CommandResult,
 	};
 }
 
-function resolveConfigPath(cwd: string, config?: string): string {
-	return config ? resolveWorkspacePath(cwd, config) : resolve(cwd, "ok-cosmic.json");
+function resolveConfigPath(cwd: string, config?: string): string | undefined {
+	if (config) return resolveWorkspacePath(cwd, config);
+	const projectConfig = resolve(cwd, "ok-cosmic.json");
+	return existsSync(projectConfig) ? projectConfig : undefined;
 }
 
 function readJsonObject(path: string): Record<string, unknown> {
@@ -231,20 +233,34 @@ function readJsonObject(path: string): Record<string, unknown> {
 	return data as Record<string, unknown>;
 }
 
-async function runCosmicConfig(_cwd: string, configPath: string): Promise<Omit<CommandResult, "command">> {
+interface LoadedCosmicConfig {
+	config: Record<string, unknown>;
+	path?: string;
+	source: "project" | "explicit" | "bundled";
+	baseDir: string;
+}
+
+async function runCosmicConfig(cwd: string, configPath: string | undefined, explicitConfig: boolean): Promise<Omit<CommandResult, "command">> {
 	const issues: Array<{ level: "OK" | "WARNING" | "ERROR"; key: string; message: string }> = [];
 	issues.push({ level: "OK", key: "runtime.node", message: `Node ${process.version}` });
 
-	let config: Record<string, unknown> | undefined;
+	let loaded: LoadedCosmicConfig | undefined;
 	try {
-		if (!existsSync(configPath)) throw new Error(`找不到配置文件: ${configPath}`);
-		config = readJsonObject(configPath);
-		issues.push({ level: "OK", key: "__file__", message: `已找到配置文件: ${configPath}` });
+		loaded = loadCosmicConfig(cwd, configPath, explicitConfig);
+		if (loaded.path) {
+			issues.push({ level: "OK", key: "__file__", message: `已找到配置文件: ${loaded.path}` });
+		} else {
+			issues.push({
+				level: "WARNING",
+				key: "__file__",
+				message: "当前项目未提供 ok-cosmic.json，已使用 KCode 随包默认配置。项目根目录 cosmic.json 是苍穹工程配置，不是 KCode 官方能力配置。",
+			});
+		}
 	} catch (error) {
 		issues.push({ level: "ERROR", key: "__file__", message: error instanceof Error ? error.message : String(error) });
 	}
 
-	if (config) issues.push(...validateCosmicConfig(config, dirname(configPath)));
+	if (loaded) issues.push(...validateCosmicConfig(loaded.config, loaded.baseDir));
 	const errors = issues.filter((issue) => issue.level === "ERROR").length;
 	const warnings = issues.filter((issue) => issue.level === "WARNING").length;
 	const lines = issues.map((issue) => `[${issue.level}] ${issue.key}: ${issue.message}`);
@@ -252,6 +268,36 @@ async function runCosmicConfig(_cwd: string, configPath: string): Promise<Omit<C
 	return { exitCode: errors ? 1 : 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
 }
 
+function loadCosmicConfig(cwd: string, configPath: string | undefined, explicitConfig: boolean): LoadedCosmicConfig {
+	if (configPath) {
+		if (!existsSync(configPath)) throw new Error(`找不到配置文件: ${configPath}`);
+		return {
+			config: readJsonObject(configPath),
+			path: configPath,
+			source: explicitConfig ? "explicit" : "project",
+			baseDir: dirname(configPath),
+		};
+	}
+	if (explicitConfig) throw new Error("指定的 ok-cosmic.json 配置文件不存在。");
+	return {
+		config: defaultCosmicConfig(),
+		source: "bundled",
+		baseDir: cwd,
+	};
+}
+
+function defaultCosmicConfig(): Record<string, unknown> {
+	return {
+		graph: {
+			dbPath: join(packageRoot, "vendor", "kingdee-skills", "ok-cosmic", "setup", "ok-cosmic-docs.db"),
+		},
+		route: {
+			apiUrl: process.env.COSMIC_ROUTE_API || process.env.COSMIC_RUNTIME_ROUTE_API || "",
+			timeoutSeconds: Number(process.env.COSMIC_ROUTE_TIMEOUT || 10),
+		},
+	};
+}
+
 function validateCosmicConfig(config: Record<string, unknown>, baseDir: string): Array<{ level: "OK" | "WARNING" | "ERROR"; key: string; message: string }> {
 	const issues: Array<{ level: "OK" | "WARNING" | "ERROR"; key: string; message: string }> = [];
 	const graph = objectValue(config.graph);
@@ -308,10 +354,11 @@ function validateCosmicConfig(config: Record<string, unknown>, baseDir: string):
 
 async function runCosmicMetadata(
 	cwd: string,
-	configPath: string,
+	configPath: string | undefined,
+	explicitConfig: boolean,
 	params: { form: string; fuzzy?: string; typeFilter?: string; sql?: boolean; op?: boolean; showDetail?: boolean },
 ): Promise<Omit<CommandResult, "command">> {
-	const config = readJsonObject(configPath);
+	const config = loadCosmicConfig(cwd, configPath, explicitConfig).config;
 	const cache = readMetadataCache(cwd);
 	const targets = params.form.split(/[,，]/).map((item) => item.trim()).filter(Boolean);
 	if (targets.length === 0) return { exitCode: 1, stdout: "", stderr: "必须提供 formId 或中文单据名。" };

package/src/rules/checker.ts

@@ -65,6 +65,7 @@ function checkCosmicReviewerRules(lines: string[]): CheckResult[] {
 		...checkSecurityPatterns(lines),
 		...checkThreadingPatterns(lines),
 		...checkUiPerformance(lines),
+		...checkViewInteractionOrder(lines),
 		...checkLoggingAndDiagnostics(lines),
 	];
 }
@@ -134,6 +135,17 @@ function checkResourceHandling(lines: string[]): CheckResult[] {
 		results.push(makeResult(i, line, "DataSet", "resource", "error", "P0：DataSet 创建后未明显使用 try-with-resources 关闭，可能导致连接泄漏", "p0-dataset-not-closed"));
 	}
 
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (isCommentLine(line)) continue;
+		if (/\.\s*getDynamicObject\s*\([^)]*\)\s*\.\s*get(?:String|Long|Int|Integer|Double|Date|PkValue|DynamicObject|DynamicObjectCollection)\s*\(/.test(line)) {
+			results.push(makeResult(i, line, "getDynamicObject", "resource", "warning", "P1：嵌套 DynamicObject 直接取值缺少空值保护，引用字段为空时可能 NPE；先取对象并判空或用安全取值工具", "p1-dynamicobject-chain-null-risk"));
+		}
+		if (/row\s*\.\s*get(?:BigDecimal|String|Long|Int|Integer|Date)\s*\(/.test(line) && !nearbyLineHas(lines, i, -2, /\brow\b\s*(?:!=|==)\s*null|Optional\.ofNullable\s*\(\s*row\s*\)|Objects\.nonNull\s*\(\s*row\s*\)/)) {
+			results.push(makeResult(i, line, "row", "resource", "warning", "P1：DataSet.Row 取值可能返回 null，参与运算或解包前应判空或给默认值", "p1-dataset-row-null-risk"));
+		}
+	}
+
 	return results;
 }
 
@@ -159,6 +171,20 @@ function checkSecurityPatterns(lines: string[]): CheckResult[] {
 		if (/(password|passwd|secret|token|ak|sk)\s*=\s*"[^"]{4,}"/i.test(line)) {
 			results.push(makeResult(i, line, "=", "security", "error", "P0：疑似敏感信息硬编码，请改为安全配置或密文存储", "p0-secret-hardcode"));
 		}
+
+		if (/\bcache\s*\.\s*put\s*\(/i.test(line) || /\bCacheFactory\b/.test(line)) {
+			const statement = collectStatement(lines, i, 5);
+			if (/\bput\s*\(/i.test(statement) && !/(account|acct|tenant|org|dcId|getAccountId|getOrgId|RequestContext|UserServiceHelper)/i.test(statement)) {
+				results.push(makeResult(i, line, "put", "security", "warning", "P1：缓存写入 key 未体现账套/租户/组织隔离，跨账套环境可能串数据", "p1-cache-key-without-tenant"));
+			}
+		}
+
+		if (/\b(openConnection|HttpClient\s*\.|HttpClientBuilder|OkHttpClient|RestTemplate|WebClient)\b/.test(line)) {
+			const statement = collectStatement(lines, i, 8);
+			if (!/(timeout|setConnectTimeout|setReadTimeout|connectTimeout|readTimeout|callTimeout|responseTimeout)/i.test(statement)) {
+				results.push(makeResult(i, line, line.match(/\b(openConnection|HttpClient|HttpClientBuilder|OkHttpClient|RestTemplate|WebClient)\b/)?.[1] ?? "HTTP", "security", "warning", "P1：第三方 HTTP 调用未看到超时设置，生产环境可能阻塞业务线程", "p1-http-without-timeout"));
+			}
+		}
 	}
 
 	return results;
@@ -197,6 +223,22 @@ function checkUiPerformance(lines: string[]): CheckResult[] {
 		if (isInsideLoop(lines, i) && /getFieldIndex\s*\(/.test(line)) {
 			results.push(makeResult(i, line, "getFieldIndex", "performance", "warning", "P1：循环内重复获取 FieldIndex 会造成性能损耗；应在循环外缓存", "p1-loop-field-index"));
 		}
+
+		if (/SerializationUtils\s*\.\s*toJsonString\s*\(/.test(line) && /(view|model|event|page|args|this|getView\s*\(|getModel\s*\(|\be\b)/i.test(line)) {
+			results.push(makeResult(i, line, "SerializationUtils", "performance", "warning", "P1：不要序列化页面、模型或事件大对象做日志，容易造成 CPU 和内存压力；只记录关键字段", "p1-heavy-json-serialization"));
+		}
+
+		const entryUiMatch = line.match(/\bgetView\s*\(\)\s*\.\s*(setEnable|setVisible)\s*\(/);
+		if (entryUiMatch) {
+			const statement = collectStatement(lines, i, 3);
+			const args = extractCallArgs(statement, /(setEnable|setVisible)\s*\(/);
+			if (args.length >= 2 && !looksLikeRowIndexedViewCall(args)) {
+				const fieldArgs = args.slice(1).join(",");
+				if (/(entry|entries|detail|row|qty|price|amount|material|item)/i.test(fieldArgs)) {
+					results.push(makeResult(i, line, entryUiMatch[1], "performance", "warning", "P1：疑似对分录字段使用单头 setEnable/setVisible；分录字段应使用带 rowIndex 的重载", "p1-entry-field-without-row-index"));
+				}
+			}
+		}
 	}
 
 	if (beginInitCount > endInitCount) {
@@ -209,6 +251,45 @@ function checkUiPerformance(lines: string[]): CheckResult[] {
 	return results;
 }
 
+function checkViewInteractionOrder(lines: string[]): CheckResult[] {
+	const results: CheckResult[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (isCommentLine(line)) continue;
+
+		if (/setDataChanged\s*\(\s*false\s*\)/.test(line)) {
+			for (let j = i + 1; j < Math.min(lines.length, i + 25); j++) {
+				if (/^\s*}\s*$/.test(lines[j])) break;
+				if (!isCommentLine(lines[j]) && /(getModel\s*\(\)\s*\.\s*)?setValue\s*\(/.test(lines[j])) {
+					results.push(makeResult(i, line, "setDataChanged", "lifecycle", "warning", "P1：setDataChanged(false) 后仍继续 setValue，脏标记会被重新置回；应放到所有 setValue 之后", "p1-set-data-changed-before-setvalue"));
+					break;
+				}
+			}
+		}
+
+		if (/showConfirm\s*\(/.test(line)) {
+			const statement = collectStatement(lines, i, 8);
+			const args = extractCallArgs(statement, /showConfirm\s*\(/);
+			if (args.length < 3 || /\bnull\b/.test(args[2] ?? "")) {
+				results.push(makeResult(i, line, "showConfirm", "lifecycle", "error", "P0：showConfirm 未提供有效回调监听器，用户选择不会触发业务处理", "p0-show-confirm-without-callback"));
+			}
+		}
+
+		if (/getView\s*\(\)\s*\.\s*close\s*\(/.test(line)) {
+			for (let j = i + 1; j < Math.min(lines.length, i + 10); j++) {
+				if (/^\s*}\s*$/.test(lines[j])) break;
+				if (!isCommentLine(lines[j]) && /returnDataToParent\s*\(/.test(lines[j])) {
+					results.push(makeResult(i, line, "close", "lifecycle", "error", "P0：先 close 再 returnDataToParent 会导致返回数据不执行；应先 returnDataToParent 再 close", "p0-close-before-return-data"));
+					break;
+				}
+			}
+		}
+	}
+
+	return results;
+}
+
 function checkLoggingAndDiagnostics(lines: string[]): CheckResult[] {
 	const results: CheckResult[] = [];
 
@@ -548,6 +629,68 @@ function isInsideLoop(lines: string[], index: number): boolean {
 	return false;
 }
 
+function collectStatement(lines: string[], start: number, maxExtraLines: number): string {
+	const parts: string[] = [];
+	for (let i = start; i < Math.min(lines.length, start + maxExtraLines + 1); i++) {
+		parts.push(lines[i]);
+		if (/[;{}]\s*$/.test(lines[i].trim())) break;
+	}
+	return parts.join("\n");
+}
+
+function extractCallArgs(statement: string, callPattern: RegExp): string[] {
+	const match = callPattern.exec(statement);
+	if (!match || match.index === undefined) return [];
+	const open = statement.indexOf("(", match.index);
+	if (open < 0) return [];
+
+	const args: string[] = [];
+	let depth = 0;
+	let current = "";
+	let quote: "'" | '"' | undefined;
+	for (let i = open + 1; i < statement.length; i++) {
+		const ch = statement[i];
+		const prev = statement[i - 1];
+		if (quote) {
+			current += ch;
+			if (ch === quote && prev !== "\\") quote = undefined;
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			quote = ch;
+			current += ch;
+			continue;
+		}
+		if (ch === "(" || ch === "[" || ch === "{") {
+			depth++;
+			current += ch;
+			continue;
+		}
+		if (ch === ")" && depth === 0) {
+			if (current.trim()) args.push(current.trim());
+			return args;
+		}
+		if (ch === ")" || ch === "]" || ch === "}") {
+			depth--;
+			current += ch;
+			continue;
+		}
+		if (ch === "," && depth === 0) {
+			args.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += ch;
+	}
+	return [];
+}
+
+function looksLikeRowIndexedViewCall(args: string[]): boolean {
+	if (args.length < 3) return false;
+	const second = args[1].trim();
+	return /^(rowIndex|index|idx|i|row|entryIndex|\d+)$/.test(second) || /\bgetRowIndex\s*\(/.test(second);
+}
+
 function isCommentLine(line: string): boolean {
 	const trimmed = line.trim();
 	return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");

package/vendor/kingdee-skills/kingdee-cosmic-reviewer/SKILL.md

@@ -304,7 +304,7 @@ references/
 
 ### 📌 步骤3: 执行模式匹配扫描
 
-**使用 pattern-matcher.py 或手动执行以下模式检查**：
+**使用 KCode `kd_check` 或手动执行以下模式检查**：
 
 ```
 📌 步骤3: 执行模式匹配扫描
@@ -671,4 +671,4 @@ D:\new_workspace\macc-dev\pm\report\代码审查报告_xxx.html  ❌ 子模块
 ### 幂等性
 - 重复执行是否产生副作用
 - MQ 消费是否支持重复消费
-- 操作是否可安全重试
+- 操作是否可安全重试

package/vendor/kingdee-skills/ok-cosmic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "ok-cosmic"
-description: "金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons 封装。适用于插件开发、单据/列表/表单逻辑、操作服务、BOTP 转换、后台视图打开、附件处理、DynamicObject 与元数据处理、弹性域解析及 OpenAPI 集成。默认优先使用仓库封装；在涉及原生插件事件、SDK API、方法签名或封装未覆盖场景时，使用内置脚本进行查询。"
+description: "金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons 封装。适用于插件开发、单据/列表/表单逻辑、操作服务、BOTP 转换、后台视图打开、附件处理、DynamicObject 与元数据处理、弹性域解析及 OpenAPI 集成。默认优先使用仓库封装；在涉及原生插件事件、SDK API、方法签名或封装未覆盖场景时，使用 KCode Node 适配器查询。"
 ---
 
 # 苍穹开发
@@ -13,18 +13,18 @@ description: "金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons
 
 ## Step 0. 配置预检（先于一切）
 
-1. Step 0 的第一个动作必须直接执行：
-   `python3 <SKILL_ROOT>/scripts/cosmic-config-check.py`
+1. Step 0 的第一个动作必须直接执行 KCode 工具：
+   `kd_cosmic_config`
 2. 默认在当前项目工作目录直接执行；不要先询问或搜索 `ok-cosmic.json` 的位置。
 3. 只有用户明确提供了其他配置路径，或当前工作目录不是目标项目根目录时，才改用：
-   `python3 <SKILL_ROOT>/scripts/cosmic-config-check.py --config <显式路径>`
+   `kd_cosmic_config config=<显式路径>`
 4. 若脚本返回非 0 或输出含 `ERROR`：停止生成代码，明确提示用户补齐缺失项。
-5. 若仅有 `WARNING`：先告知用户哪些在线能力不可用，再决定是否继续当前任务。后续脚本调用受以下限制：
+5. 若仅有 `WARNING`：先告知用户哪些在线能力不可用，再决定是否继续当前任务。后续工具调用受以下限制：
 
    | WARNING 类型 | 限制 |
    |---|---|
-   | "API 不可达" 或 "在线服务不可用" | **禁止调用** `cosmic-basedata-query.py`；`cosmic-form-metadata.py` 仅允许使用本地缓存，**禁止 `--refresh` 刷新** |
-   | "知识库不存在" | `cosmic-api-knowledge.py` 不可用，改为仅依赖 `cheat-sheet.md` 和模板中的方法签名 |
+   | "API 不可达" 或 "在线服务不可用" | `kd_cosmic_metadata` 只能使用 KCode 本地缓存；需要实时基础资料数据时停止并要求项目侧证据 |
+   | "知识库不存在" | `kd_cosmic_api` 随包知识不可用，改为仅依赖 `cheat-sheet.md`、项目 SDK 和编译结果 |
 
 ## 自然语言意图路由（首读）
 
@@ -100,15 +100,15 @@ description: "金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons
    - 🔍 **Agent A — 事件参考**：读对应 `references/*.md` 的 TL;DR 摘要 + `assets/*.java` 模板，提取事件签名与骨架。只读当前任务需要的事件方法段，不要一次性通读整个模板。如果卡在事件先后顺序，先读 [references/adv/event-lifecycle.md](references/adv/event-lifecycle.md)。
    - 🔍 **Agent B — 项目探索**：在用户项目中搜索相似插件实现（同类型插件、相似业务场景），分析已有代码风格、import 习惯、封装用法，确保生成代码与项目风格一致。
 3. **‖ 并行验证**字段与 API 签名（互不依赖的查询应同时发起）：
-   - 调用脚本前，先查下方“脚本路由”表格确认调用模板；表格未覆盖时才执行 `python3 <script> --help`。
-   - 3a. 若目标 API 已在 `rules/cheat-sheet.md` 中列出 → 直接使用，**无需脚本验证**。
-   - 3b. 字段 / `entityId` / 枚举值验证 → 查 `cosmic-form-metadata.py`。**只要要生成代码且已知目标单据/表单，凡涉及字段（无论用户给中文名还是英文标识），都必须验证字段是否存在、字段类型、所属实体和特殊取值规则；多个字段合并到同一次调用**。
-   - 3c. SDK 类名/方法签名不在 cheat-sheet 中 → 查 `cosmic-api-knowledge.py`。**与 3b 互不依赖，应同时发起**。
+   - 调用工具前，先查下方“KCode 工具路由”表格确认参数；表格未覆盖时读取工具 schema。
+   - 3a. 若目标 API 已在 `rules/cheat-sheet.md` 中列出 → 直接使用，**无需额外工具验证**。
+   - 3b. 字段 / `entityId` / 枚举值验证 → 查 `kd_cosmic_metadata`。**只要要生成代码且已知目标单据/表单，凡涉及字段（无论用户给中文名还是英文标识），都必须验证字段是否存在、字段类型、所属实体和特殊取值规则；多个字段合并到同一次调用**。
+   - 3c. SDK 类名/方法签名不在 cheat-sheet 中 → 查 `kd_cosmic_api`，并优先结合项目 SDK/编译结果做红绿验证。**与 3b 互不依赖，应同时发起**。
    - 3d. 需要查询多个不同类的 detail → **多个 `detail` 调用也可并行**。
-   - ⚠️ `cosmic-basedata-query.py` 必须等 `entityId` 从 3b 确认后才能调用，**不可并行**。
+   - ⚠️ 基础资料实时数据查询必须等 `entityId` 从 3b 确认后才能进行；npm 包不再内置 Python 基础资料脚本，需要项目侧接口、SQL 或人工证据。
 4. 只有"插件类型 + 事件方法 + 字段/签名"都确认后，才开始生成代码。
 5. 编写代码时遵守最小干预：插件只做当前事件该做的事；能用封装就不退回原生。
-6. **代码生成后，必须执行 `cosmic-post-check.py` 自动校验**，详见"代码生成后自动校验"章节。
+6. **代码生成后，必须执行 `kd_check`，条件允许时再执行 `kd_build` 或项目编译命令**，详见"代码生成后自动校验"章节。
 
 ## 写代码前的最小确认卡
 
@@ -119,105 +119,56 @@ description: "金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons
 | 1 | 插件类型 | 决策矩阵 |
 | 2 | 目标事件方法 | 模板 / references |
 | 3 | 使用模板 | `assets/*.java` |
-| 4 | 已验证字段 / refType / entityId | 生成代码且已知目标单据/表单时，字段中文名/英文标识都必须经 `cosmic-form-metadata.py` 确认；`entityId` 来自用户明确给出或元数据脚本确认 |
-| 5 | 已确认枚举/下拉选项值（有使用时） | `cosmic-form-metadata.py --show-detail` |
-| 6 | 已验证类/方法签名 | cheat-sheet / `cosmic-api-knowledge.py` / 业务拓展点 `--full` 返回的清晰 Java 示例 |
+| 4 | 已验证字段 / refType / entityId | 生成代码且已知目标单据/表单时，字段中文名/英文标识都必须经 `kd_cosmic_metadata` 确认；`entityId` 来自用户明确给出或元数据证据确认 |
+| 5 | 已确认枚举/下拉选项值（有使用时） | `kd_cosmic_metadata showDetail=true` |
+| 6 | 已验证类/方法签名 | cheat-sheet / `kd_cosmic_api` / 项目 SDK / 编译结果 / 业务拓展点清晰 Java 示例 |
 
-## 脚本路由
+## KCode 工具路由
 
-### 脚本调用协议
+### 工具调用协议
 
-常用脚本的调用模板已列在下方表格，可直接按模板执行。仅当参数不确定或下表未覆盖时，才需先执行 `python3 <script> --help` 确认调用方式。
+本 npm 包不发布 Python/JAR/bat/sh 运行资产；官方脚本能力已迁移为 KCode Node 适配器。所有查询和校验优先使用下表工具，不要尝试执行 `scripts/*.py`。
 
-### 先选脚本，再按模板调用
-
-| 场景 | 优先脚本 | 常用用法 | 调用模板 | 备注 |
-|---|---|---|---|---|
-| SDK 类名、方法名、继承链、`@Override` 签名确认 | `scripts/cosmic-api-knowledge.py` | `search` / `search-method` / `detail` | `python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json <subcommand> ...` | `detail` 支持逗号分隔批量查类详情（并发请求） |
-| 字段标识、枚举映射、`refType`、按中文名确认真实英文标识 | `scripts/cosmic-form-metadata.py` | `get` | `python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get ...` | 字段不确定先查它。`formIdOrName` 支持逗号分隔批量查询（formId 与中文名可混合，自动识别，并发请求） |
-| 已确认 `entityId` 后查询基础资料编码/名称/完整数据 | `scripts/cosmic-basedata-query.py` | `get` | `python3 <SKILL_ROOT>/scripts/cosmic-basedata-query.py --config ok-cosmic.json get ...` | 只在 `entityId` 来源已确认后调用 |
-| 查询业务拓展点 / SDK 扩展接口候选 | `scripts/cosmic-extpoints-query.py` | `get` | `python3 <SKILL_ROOT>/scripts/cosmic-extpoints-query.py --config ok-cosmic.json get --keyword ...` | 默认摘要模式；仅在需要生成代码或查看 Java 示例时加 `--full`；若 `--full` 已返回清晰 Java 示例，可先按示例，不强制立即 `detail` |
-| 生成或修改苍穹 Java 代码后的统一校验 | `scripts/cosmic-post-check.py` | 直接执行 | `python3 <SKILL_ROOT>/scripts/cosmic-post-check.py <file_or_directory> --fix-hint` | 必须形成"生成 -> 校验 -> 修复 -> 复检"闭环 |
+| 场景 | 优先工具 | 常用参数 | 备注 |
+|---|---|---|---|
+| SDK 类名、方法名、继承链、`@Override` 签名确认 | `kd_cosmic_api` | `mode=search/search-method/detail`、`query`、`method`、`compact` | 随包知识给线索；精确签名优先结合项目 SDK/编译红绿验证 |
+| 字段标识、枚举映射、`refType`、按中文名确认真实英文标识 | `kd_cosmic_metadata` | `form`、`fuzzy`、`typeFilter`、`sql`、`op`、`showDetail` | 字段不确定先查它；多个表单用逗号合并 |
+| 已确认 `entityId` 后查询基础资料编码/名称/完整数据 | 项目侧接口/SQL/人工证据 | 先由 `kd_cosmic_metadata` 确认 `entityId` | KCode 不内置实时基础资料 Python 查询脚本 |
+| 查询业务拓展点 / SDK 扩展接口候选 | `kd_search` + `kd_cosmic_api` | 业务关键词、接口类名、方法名 | 命中接口类名后用 `kd_cosmic_api detail` 或编译确认签名 |
+| 生成或修改苍穹 Java 代码后的统一校验 | `kd_check` + `kd_build` | 修改文件路径、项目构建命令 | 必须形成"生成 -> 校验 -> 修复 -> 复检"闭环 |
 
 ### 常用用法示例
 
-```bash
-# 搜索类名
-python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search QueryServiceHelper
-
-# 搜索方法名
-python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search-method loadSingle
-
-# 查看类详情（全部方法）
-python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail kd.bos.servicehelper.QueryServiceHelper
-
-# 查看类详情（单个方法筛选）
-python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail kd.bos.servicehelper.QueryServiceHelper --method loadSingle --compact
-
-# 批量查类详情（逗号分隔，并发请求）
-python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail kd.bos.servicehelper.QueryServiceHelper,kd.bos.servicehelper.SaveServiceHelper --method save --compact
-
-# 查元数据字段
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order
-
-# 查元数据字段（带数据库相关信息）
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order,ap_finapbill --sql
-
-# 批量查询多个单据（逗号分隔）
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order,ap_finapbill --fuzzy supplier
-
-# 混合查询：formId + 中文单据名（自动识别）
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get "ap_finapbill,物料,bd_supplier" --fuzzy number
-
-# 模糊筛选字段
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --fuzzy qty price amount
-
-# 按多种字段类型筛选（正则 OR）
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --type "combo|check"
-
-# 类型 + 关键词交集筛选（Decimal 类型且含 amount）
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --type decimal --fuzzy amount
-
-# 按单据中文名查元数据
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get 物料
-
-# 查看单据所有操作
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --op
-
-# 按关键词筛选操作
-python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --op 审核 提交
-
-# 查基础资料
-python3 <SKILL_ROOT>/scripts/cosmic-basedata-query.py --config ok-cosmic.json get --entity-id bd_material --number-or-name 01.0001
-
-# 查业务拓展点
-python3 <SKILL_ROOT>/scripts/cosmic-extpoints-query.py --config ok-cosmic.json get --keyword 应付
-
-# 代码校验
-python3 <SKILL_ROOT>/scripts/cosmic-post-check.py ./src/main/java/MyPlugin.java --fix-hint
+```text
+kd_cosmic_config
+kd_cosmic_api mode=search query=QueryServiceHelper
+kd_cosmic_api mode=search-method query=loadSingle
+kd_cosmic_api mode=detail query=kd.bos.servicehelper.QueryServiceHelper method=loadSingle compact=true
+kd_cosmic_metadata form=sal_order
+kd_cosmic_metadata form=sal_order,ap_finapbill sql=true
+kd_cosmic_metadata form=sal_order fuzzy="qty price amount"
+kd_cosmic_metadata form=sal_order typeFilter="combo|check" showDetail=true
+kd_cosmic_metadata form=sal_order op=true fuzzy="审核 提交"
+kd_check path=./src/main/java/MyPlugin.java
+kd_build
 ```
 
-### 跨脚本硬约束
-
-- 完成 Step 0 后，后续脚本优先显式使用 `--config ok-cosmic.json`；若当前工作目录不是项目根目录，再传绝对路径。不要为了拼配置路径先额外搜索 `ok-cosmic.json`。
-- **参数不确定时**，先执行 `python3 <script> --help` 确认调用方式；如果 `--help` 仍不足以确认，就停止并报告。
-- **凡是带子命令的脚本，`--config` 等全局参数统一放在子命令前，按 `python3 <script> --config ok-cosmic.json <subcommand> ...` 组织。**
-- `entityId` 只允许来自"用户明确给出的准确英文标识"或"元数据脚本确认出的真实标识"；来源不明时，先查 `cosmic-form-metadata.py`，不得直接执行基础资料查询。
-- **字段生成代码强制验证**：只要要生成/修改代码，且已知目标单据/表单（`formId` 或 `billName`），凡涉及字段（无论用户给的是中文名还是英文标识），都必须先用 `cosmic-form-metadata.py` 验证字段是否存在、字段类型、所属实体（表头/表体/子表体/容器）和特殊取值规则（如 `BasedataPropField` 的 `refType`、`LargeTextField` 的 `{fieldKey}_tag`、Combo/下拉字段的 Ext 映射）。目标单据/表单不明确时，先确认目标，不要直接把用户给的字段写进代码。
-- **枚举/下拉选项值禁猜 [A1.8]**：使用 ComboField / 下拉字段的具体选项值前，必须先查 `cosmic-form-metadata.py` 的 Ext 列确认真实映射，详见 [constraints.md](rules/constraints.md) A1.8。
-- 需要确认多个字段时，优先一次性合并到同一次元数据查询里；不要逐个字段重复调用脚本。
-- **并行调用**：`cosmic-form-metadata.py`（字段/枚举验证）与 `cosmic-api-knowledge.py`（类/方法签名验证）查询不同数据源、互不依赖，应在同一轮并行发起。同理，多个 `detail` 查询、多个文件读取也应并行。唯一例外：`cosmic-basedata-query.py` 依赖 `entityId` 确认结果，必须串行等待。
-- **元数据批量查询**：`cosmic-form-metadata.py` 的 `formIdOrName` 位置参数支持逗号分隔多个查询目标（如 `get sal_order,ap_finapbill,物料`），含中文的自动走 billName、英文标识走 formId，脚本内部通过 `ThreadPoolExecutor` 并发请求（最多 4 线程），结果按原始顺序拼接输出。跨单据场景（如下推、对比源单与目标单字段）优先使用批量查询，减少脚本调用次数。
+### 跨工具硬约束
+
+- 完成 Step 0 后，后续工具可显式传 `config=<ok-cosmic.json>`；当前项目没有 `ok-cosmic.json` 时，KCode 使用随包默认知识库并输出 warning。不要把苍穹工程 `cosmic.json` 当成 `ok-cosmic.json`。
+- `entityId` 只允许来自"用户明确给出的准确英文标识"或"`kd_cosmic_metadata` 确认出的真实标识"；来源不明时，先查元数据，不得直接查询基础资料或写入代码。
+- **字段生成代码强制验证**：只要要生成/修改代码，且已知目标单据/表单（`formId` 或 `billName`），凡涉及字段（无论用户给的是中文名还是英文标识），都必须先用 `kd_cosmic_metadata` 验证字段是否存在、字段类型、所属实体和特殊取值规则。目标单据/表单不明确时，先确认目标，不要直接把用户给的字段写进代码。
+- **枚举/下拉选项值禁猜 [A1.8]**：使用 ComboField / 下拉字段的具体选项值前，必须先查 `kd_cosmic_metadata showDetail=true` 的附加信息确认真实映射，详见 [constraints.md](rules/constraints.md) A1.8。
+- 需要确认多个字段时，优先一次性合并到同一次元数据查询里；不要逐个字段重复调用工具。
+- **并行调用**：`kd_cosmic_metadata`（字段/枚举验证）与 `kd_cosmic_api`（类/方法签名验证）查询不同数据源、互不依赖，应在同一轮并行发起。
 - 查询超时或远端失败时，只能基于当前会话里已确认的字段、`refType`、`entityId`、接口返回继续；若本次查询结果是继续前提，则停止。
-- 若 Traceback 明确指向 Skill 脚本实现问题，立即停止并报告命令与错误摘要；不要绕过验证继续生成依赖该事实的代码。
-- 只有在用户已修正配置/环境，或本次明确修改了查询条件后，才允许重试同类脚本；不要原样重复执行。
 
 ### 项目级配置文件 (`ok-cosmic.json`)
 
-脚本依赖 `ok-cosmic.json` 获取数据库路径及 API 地址。若需模板可参考 `<SKILL_ROOT>/setup/ok-cosmic.json`。
+KCode 适配器可读取 `ok-cosmic.json` 获取知识库路径及在线路由 API 地址。若项目没有该文件，会使用随包默认知识库并输出 warning；苍穹工程自带的 `cosmic.json` 不是 KCode 官方能力配置。
 
-- **显式指定**: 调用脚本时建议指定 `--config <路径>`。未指定时读取**当前执行目录**下的 `ok-cosmic.json`；不存在则报错。
-- **在线查询配置**: 三个在线查询脚本统一走 `route.apiUrl`（`runtime/route`，URL 中包含 `openApiSign`）/ `route.timeoutSeconds`；脚本内部通过 `data.type=meta|basedata|extpoint` 路由。
+- **显式指定**: 调用工具时可指定 `config=<路径>`。未指定时优先读取当前项目根目录下的 `ok-cosmic.json`；不存在则使用随包默认配置。
+- **在线查询配置**: 元数据在线查询走 `route.apiUrl`（`runtime/route`，URL 中可包含 `openApiSign`）/ `route.timeoutSeconds`；KCode 内部通过 `data.type=meta` 路由。
 - **统一路由请求体**: 元数据 `data.type=meta` + `reqData.entityId/formId/billName/full`；基础资料 `data.type=basedata` + `reqData.entityId/numberOrName/full`；业务拓展点 `data.type=extpoint` + `reqData.keyword`。
 
 ## 扩展代码库探索（Extension Repos Fallback）
@@ -236,16 +187,16 @@ python3 <SKILL_ROOT>/scripts/cosmic-post-check.py ./src/main/java/MyPlugin.java
   - 扩展代码库仅作为**实现参考**，不等同于 ok-cosmic 推荐写法。
   - 生成代码时仍须遵守 A 层硬约束（`rules/constraints.md`、`rules/anti-patterns.md`）与 B 层编码偏好（`rules/coding-preferences.md`）。
   - 若扩展代码与 ok-cosmic 规范冲突，**以 ok-cosmic 规范为准**；只借鉴参考项目的业务组装方式与字段暴露结构。
-  - 若扩展代码库中未搜到相关实现，回落到 fallback 第 3 步（`cosmic-api-knowledge.py search`）后再向用户确认。
+  - 若扩展代码库中未搜到相关实现，回落到 fallback 第 3 步（`kd_cosmic_api mode=search`）后再向用户确认。
 
 ## 代码生成后自动校验（Post-Check）
 
 修改任何苍穹 `.java` 文件后，必须执行：
 
-`python3 <SKILL_ROOT>/scripts/cosmic-post-check.py <生成的文件或目录> --fix-hint`
+`kd_check path=<生成的文件或目录>`
 
 - `ERROR` → 必须修复并复检；`WARNING` → 优先修复；`INFO` → 治理参考，不阻断。
-- Gradle 项目编译成功后仍串联 post-lint 静态校验，以综合结果为准；非 Gradle 直接回退静态 lint。
+- 条件允许时继续执行 `kd_build` 或项目 Gradle/Maven 编译命令；编译与静态校验以综合结果为准。
 - 最多连续 3 轮"修复 → 复检"；3 轮后仍有 `ERROR`，向用户报告。
 - 规则 ID 映射、修复示例、历史项目解释口径见 [rules/post-check.md](rules/post-check.md)。
 

package/vendor/kingdee-skills/ok-cosmic/agents/openai.yaml

@@ -3,14 +3,14 @@ interface:
   short_description: "封装优先的苍穹开发主 skill"
   default_prompt: |
     使用 $ok-cosmic 来实现或审查苍穹插件代码。严格遵循以下流程：
-    0. 首先执行 cosmic-config-check.py 完成配置预检；ERROR 必须停止，WARNING 需告知用户受限能力
+    0. 首先执行 kd_cosmic_config 完成配置预检；ERROR 必须停止，WARNING 需告知用户受限能力
     1. 先查 SKILL.md 决策矩阵确定插件类型和对应模板
     2. 读 references/*.md 确认事件边界和适用场景
     3. 读 assets/*.java 模板沿用已有骨架，小场景查 snippets 映射表
-    4. 首次调用任何脚本前，先执行 --help 读取调用契约，定好命令模板后再填参数执行（三步首调协议）
-    5. 字段不确定先查 cosmic-form-metadata.py；entityId 来源不明先查 cosmic-form-metadata.py（查 refType 或按中文名确认英文标识），严禁凭经验猜 entityId；枚举/下拉选项值必须查 --show-detail 的 Ext 列确认（A1.8 硬约束），严禁凭空编造；SDK 签名不确定先查 cosmic-api-knowledge.py
+    4. 首次调用任何 KCode 工具前，先读取工具 schema，定好参数后再执行
+    5. 字段不确定先查 kd_cosmic_metadata；entityId 来源不明先查 kd_cosmic_metadata（查 refType 或按中文名确认英文标识），严禁凭经验猜 entityId；枚举/下拉选项值必须查 showDetail=true 的 Ext 列确认（A1.8 硬约束），严禁凭空编造；SDK 签名不确定先查 kd_cosmic_api
     6. 只有"插件类型 + 事件方法 + 字段/基础资料/签名 + 枚举值来源"都确认后，才开始生成代码
-    7. 代码生成后，执行 cosmic-post-check.py 自动校验，有 ERROR 须修复后重验
+    7. 代码生成后，执行 kd_check，条件允许时执行 kd_build 或项目编译；有 ERROR 须修复后重验
     核心原则：封装优先（kd-cd-cosmic-commons），原生兜底；严禁凭记忆猜测 API 签名。
 
 policy: