kcode-pi 0.1.6 → 0.1.8

package/README.md

@@ -277,6 +277,7 @@ kcode start --provider openai --model gpt-4o
 /kd-gate
 /kd-advance [phase]
 /kd-artifact [phase] [content]
+/kd-answer Q-001 <answer>
 ```
 
 典型开始方式：
@@ -369,7 +370,7 @@ ship     汇总变更、验证证据、风险和后续事项
 
 - Red evidence: evidence/tdd-red.md
 - Green evidence: evidence/tdd-green.md
-- Red/green command or tool: kd_cosmic_api detail / kd_cosmic_metadata / kd_check / build
+- Red/green command or tool: kd_sdk_signature / kd_cosmic_metadata / kd_check / build
 - Do not add third-party test jars or frameworks only for this gate.
 ```
 
@@ -387,6 +388,12 @@ ship     汇总变更、验证证据、风险和后续事项
 
 如果 LLM 跳过步骤、没有记录 evidence，或只是口头声明完成，KCode 不允许进入 `verify`。
 
+结构化问题也会进入门禁。Agent 需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，会使用 `kd_question` 记录问题；未回答的阻断问题会阻止进入下一阶段。用户回复后，Agent 会记录答案；也可以手动执行：
+
+```text
+/kd-answer Q-001 采购订单
+```
+
 运行状态保存在当前业务项目：
 
 ```text
@@ -400,12 +407,14 @@ KCode 会向 Pi 注册这些金蝶工具：
 
 ```text
 kd_plan_status      查看当前 Harness run、阶段、产物和门禁
+kd_question         记录/回答/查看阻断问题，未回答时阻止阶段推进
 kd_search           搜索内置金蝶 SDK 知识和代码模式
 kd_table            查询内置金蝶表结构
 kd_check            检查金蝶 Java/C# 插件代码
 kd_cosmic_config    运行官方 ok-cosmic 配置预检
 kd_cosmic_metadata  查询官方 Cosmic 表单/单据元数据
-kd_cosmic_api       查询官方 Cosmic API 签名和方法
+kd_cosmic_api       查询随包 Cosmic API 知识线索
+kd_sdk_signature    从当前项目实际 SDK jar/dll 中读取类和方法签名
 kd_ksql_lint        运行官方 ok-ksql SQL/KSQL lint
 kd_build            按产品画像执行或 dry-run 构建
 kd_debug            分析金蝶日志和堆栈
@@ -414,9 +423,35 @@ 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_api` 查询随包金蝶知识库；需要精确方法签名时，仍要结合当前项目 SDK、编译输出或红绿证据确认。
+- `kd_cosmic_config` 使用 Node 校验 Cosmic 官方能力配置；项目没有 `ok-cosmic.json` 时会自动使用 KCode 随包默认配置。
+- `kd_cosmic_metadata` 使用统一路由 API 查询真实单据/表单元数据，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
+- `kd_sdk_signature` 优先从当前业务项目的实际 SDK jar/dll 中读取类型和方法签名。Cosmic Java 依赖 `javap`，Enterprise C# 依赖 PowerShell 读取 DLL 元数据。
+- `kd_cosmic_api` 查询随包金蝶知识库，只作为 API 线索和兜底；精确方法签名优先使用 `kd_sdk_signature`、当前项目 SDK 或编译输出确认。
+
+示例：
+
+```text
+kd_sdk_signature product=flagship query=QueryServiceHelper method=loadSingle path=lib
+kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject path=bin
+```
+
+`method` 只是在已匹配的类/类型里过滤方法或属性；如果不知道类名，先用 `query` 搜类型关键词，再结合项目源码和构建文件缩小范围。
+
+`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/docs/DEVELOPMENT.md

@@ -32,6 +32,7 @@ npm run smoke:checker
 npm run smoke:harness
 npm run smoke:official
 npm run smoke:build-debug
+npm run smoke:sdk-signature
 npm run smoke:package
 npm run smoke:kcode-cli
 ```
@@ -45,6 +46,7 @@ npm run smoke:kcode-cli
 - Harness 阶段和门禁。
 - 官方能力 Node 适配器。
 - 构建/调试诊断。
+- 当前项目 SDK jar/dll 签名读取。
 - package manifest、skills、vendor 文件完整性。
 - `kcode` 项目级入口逻辑。
 

package/extensions/kingdee-harness.ts

@@ -4,6 +4,8 @@ import { formatStatus } from "../src/harness/format.ts";
 import { PHASE_ORDER, isKdPhase, type KdPhase } from "../src/harness/types.ts";
 import {
 	advanceRun,
+	addQuestion,
+	answerQuestion,
 	createActiveRun,
 	ensurePhaseArtifact,
 	readActiveRun,
@@ -107,7 +109,7 @@ function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof re
 		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
 		"路径规则：在 Windows 工作区内，优先使用项目相对路径；如需绝对路径必须使用 `D:\\...` 这类 Windows 路径，禁止把路径改写成 `/mnt/d/...`、`/d/...` 等 WSL/MSYS 风格路径。",
 		"execute 阶段只能写 PLAN.md 明确列出的源码文件；如果目标文件不在计划内，必须先回到 plan 更新 PLAN.md。",
-		"写生产源码前必须先有红灯证据 evidence/tdd-red.md；红绿证据可以是 API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
+		"写生产源码前必须先有红灯证据 evidence/tdd-red.md；红绿证据可以是 kd_sdk_signature 本地 SDK 签名、API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
 	].join("\n");
 }
 
@@ -158,8 +160,86 @@ const kdPlanStatusTool = defineTool({
 	},
 });
 
+const kdQuestionTool = defineTool({
+	name: "kd_question",
+	label: "KD Question",
+	description:
+		"Create, answer, or list structured Kingdee Harness questions. Open blocking questions stop phase advancement until answered.",
+	parameters: Type.Object({
+		action: Type.Optional(Type.String({ description: "ask, answer, or list. Defaults to ask." })),
+		id: Type.Optional(Type.String({ description: "Question id when action=answer, for example Q-001." })),
+		question: Type.Optional(Type.String({ description: "Question to ask when action=ask." })),
+		answer: Type.Optional(Type.String({ description: "User answer when action=answer." })),
+		reason: Type.Optional(Type.String({ description: "Why this question blocks or matters." })),
+		choices: Type.Optional(Type.Array(Type.String(), { description: "Optional concrete choices for the user." })),
+		blocking: Type.Optional(Type.Boolean({ description: "Whether the question blocks phase advancement. Defaults to true." })),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const run = readActiveRun(ctx.cwd);
+		if (!run) {
+			return {
+				content: [{ type: "text", text: "No active Kingdee harness run. Start one with /kd-start <goal> first." }],
+				details: { error: "no-active-run" },
+			};
+		}
+
+		const action = (params.action ?? "ask").toLowerCase();
+		if (action === "list") {
+			const text = formatQuestions(run);
+			return { content: [{ type: "text", text }], details: { questions: run.questions ?? [] } };
+		}
+
+		if (action === "answer") {
+			if (!params.id || !params.answer) {
+				return {
+					content: [{ type: "text", text: "kd_question action=answer requires id and answer." }],
+					details: { error: "missing-answer-params" },
+				};
+			}
+			const answered = answerQuestion(ctx.cwd, run, params.id, params.answer);
+			if (!answered) {
+				return {
+					content: [{ type: "text", text: `Question not found: ${params.id}` }],
+					details: { error: "question-not-found", id: params.id },
+				};
+			}
+			appendQuestionEventToArtifact(ctx.cwd, run, [`- Answered ${answered.id}: ${answered.answer}`]);
+			return {
+				content: [{ type: "text", text: `Recorded answer for ${answered.id}. Gate refreshed.` }],
+				details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate },
+			};
+		}
+
+		if (action !== "ask") {
+			return {
+				content: [{ type: "text", text: `Unknown kd_question action: ${params.action}. Use ask, answer, or list.` }],
+				details: { error: "unknown-action", action: params.action },
+			};
+		}
+
+		if (!params.question?.trim()) {
+			return {
+				content: [{ type: "text", text: "kd_question action=ask requires question." }],
+				details: { error: "missing-question" },
+			};
+		}
+
+		const question = addQuestion(ctx.cwd, run, {
+			question: params.question,
+			reason: params.reason,
+			choices: params.choices,
+			blocking: params.blocking,
+		});
+		appendQuestionEventToArtifact(ctx.cwd, run, formatQuestionArtifactLines(question));
+		const text = formatQuestionCard(question);
+		return { content: [{ type: "text", text }], details: { question, gate: readActiveRun(ctx.cwd)?.gate } };
+	},
+});
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdPlanStatusTool);
+	pi.registerTool(kdQuestionTool);
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") return { action: "continue" };
@@ -299,4 +379,62 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.notify(`Artifact ready: ${path}`, "info");
 		},
 	});
+
+	pi.registerCommand("kd-answer", {
+		description: "Answer a blocking Kingdee harness question: /kd-answer Q-001 <answer>",
+		handler: async (args, ctx) => {
+			const run = requireRun(ctx.cwd);
+			if (!run) {
+				ctx.ui.notify("No active Kingdee harness run. Use /kd-start <goal>.", "error");
+				return;
+			}
+			const [id, ...answerParts] = args.trim().split(/\s+/);
+			const answer = answerParts.join(" ").trim();
+			if (!id || !answer) {
+				ctx.ui.notify("Usage: /kd-answer Q-001 <answer>", "error");
+				return;
+			}
+			const answered = answerQuestion(ctx.cwd, run, id, answer);
+			if (!answered) {
+				ctx.ui.notify(`Question not found: ${id}`, "error");
+				return;
+			}
+			appendQuestionEventToArtifact(ctx.cwd, run, [`- Answered ${answered.id}: ${answered.answer}`]);
+			ctx.ui.notify(`Recorded answer for ${answered.id}`, "info");
+		},
+	});
+}
+
+function formatQuestions(run: NonNullable<ReturnType<typeof readActiveRun>>): string {
+	const questions = run.questions ?? [];
+	if (questions.length === 0) return "No harness questions recorded.";
+	return questions.map(formatQuestionCard).join("\n\n");
+}
+
+function formatQuestionCard(question: NonNullable<NonNullable<ReturnType<typeof readActiveRun>>["questions"]>[number]): string {
+	const lines = [
+		`Question ${question.id} [${question.status}${question.blocking ? ", blocking" : ""}]`,
+		`Phase: ${question.phase}`,
+		`Question: ${question.question}`,
+		question.reason ? `Reason: ${question.reason}` : undefined,
+		question.choices?.length ? `Choices: ${question.choices.join(" | ")}` : undefined,
+		question.answer ? `Answer: ${question.answer}` : undefined,
+		question.status === "open" ? `Reply with the answer, then record it using kd_question action=answer id=${question.id} answer=<answer>.` : undefined,
+	];
+	return lines.filter(Boolean).join("\n");
+}
+
+function formatQuestionArtifactLines(question: NonNullable<NonNullable<ReturnType<typeof readActiveRun>>["questions"]>[number]): string[] {
+	return [
+		`- ${question.id} [${question.blocking ? "blocking" : "non-blocking"}] ${question.question}`,
+		question.reason ? `  - Reason: ${question.reason}` : undefined,
+		question.choices?.length ? `  - Choices: ${question.choices.join(" | ")}` : undefined,
+		"  - Status: open",
+	].filter(Boolean) as string[];
+}
+
+function appendQuestionEventToArtifact(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>, lines: string[]): void {
+	const existing = readArtifact(cwd, run, run.phase) ?? "";
+	const section = ["", "## Harness Questions", "", ...lines, ""].join("\n");
+	updatePhaseArtifact(cwd, run, run.phase, existing.includes("## Harness Questions") ? `${existing.trimEnd()}\n${lines.join("\n")}\n` : `${existing.trimEnd()}${section}`);
 }

package/extensions/kingdee-tools.ts

@@ -9,6 +9,7 @@ import type { Edition, KnowledgeScope } from "../src/knowledge/types.ts";
 import { resolveProductProfile, type ProductProfile } from "../src/product/profile.ts";
 import { checkCode, formatCheckResults, type CheckLanguage } from "../src/rules/checker.ts";
 import { analyzeDebugText, formatDebugFindings, planBuild, readDebugInput, runBuild } from "../src/tools/build-debug.ts";
+import { formatSdkSignatureResult, inspectSdkSignature, type SdkSignatureLanguage } from "../src/tools/sdk-signature.ts";
 import {
 	cosmicApiCommand,
 	cosmicConfigCommand,
@@ -64,6 +65,13 @@ function languageForProfile(profile: ProductProfile, value: string | undefined):
 	return "java";
 }
 
+function sdkLanguageForProfile(profile: ProductProfile, value: string | undefined): SdkSignatureLanguage {
+	if (value === "csharp" || value === "cs") return "csharp";
+	if (value === "java") return "java";
+	if (profile.platform === "enterprise-csharp") return "csharp";
+	return "java";
+}
+
 function rejectNonCosmic(profile: ProductProfile): string | undefined {
 	if (isCosmicFamily(profile)) return undefined;
 	if (profile.product === "unknown") return "Provide a Cosmic-family product first: cangqiong, xinghan, flagship, or cosmic.";
@@ -265,7 +273,7 @@ const kdCosmicMetadataTool = defineTool({
 const kdCosmicApiTool = defineTool({
 	name: "kd_cosmic_api",
 	label: "KD Cosmic API",
-	description: "Query official Cosmic API knowledge for class names, method names, and method signatures.",
+	description: "Query bundled Cosmic API knowledge for class and method clues. Use kd_sdk_signature or build output for final local SDK facts.",
 	parameters: Type.Object({
 		product: Type.String({ description: "Cosmic-family product: cangqiong, xinghan, flagship, or cosmic." }),
 		mode: Type.String({ description: "search, search-method, or detail." }),
@@ -295,6 +303,39 @@ const kdCosmicApiTool = defineTool({
 	},
 });
 
+const kdSdkSignatureTool = defineTool({
+	name: "kd_sdk_signature",
+	label: "KD SDK Signature",
+	description:
+		"Inspect method/type signatures from SDK jars or dlls actually present in the current project. Prefer this over bundled knowledge for factual API signatures.",
+	parameters: Type.Object({
+		product: Type.Optional(Type.String({ description: "Kingdee product. Used to derive Java or C# when language is omitted." })),
+		language: Type.Optional(Type.String({ description: "java or csharp. Defaults from product profile." })),
+		query: Type.Optional(Type.String({ description: "Class/type keyword to search, for example QueryServiceHelper or DynamicObject." })),
+		className: Type.Optional(Type.String({ description: "Fully qualified Java/C# type name when known." })),
+		method: Type.Optional(Type.String({ description: "Optional method/property name filter within the matched class/type. Does not scan all methods globally." })),
+		path: Type.Optional(Type.String({ description: "Optional SDK lib/bin directory or specific dependency root. Defaults to current project." })),
+		limit: Type.Optional(Type.Number({ description: "Maximum jars/dlls/classes to inspect. Defaults to 20 result classes and 200 files." })),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const profile = resolveToolProfile(params.product, undefined);
+		const language = sdkLanguageForProfile(profile, params.language);
+		const result = await inspectSdkSignature(ctx.cwd, {
+			language,
+			query: params.query,
+			className: params.className,
+			method: params.method,
+			path: params.path,
+			limit: params.limit,
+		});
+		return {
+			content: [{ type: "text", text: formatSdkSignatureResult(result) }],
+			details: { product: profile.product, ...result },
+		};
+	},
+});
+
 const kdKsqlLintTool = defineTool({
 	name: "kd_ksql_lint",
 	label: "KD KSQL Lint",
@@ -377,6 +418,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdCosmicConfigTool);
 	pi.registerTool(kdCosmicMetadataTool);
 	pi.registerTool(kdCosmicApiTool);
+	pi.registerTool(kdSdkSignatureTool);
 	pi.registerTool(kdKsqlLintTool);
 	pi.registerTool(kdBuildTool);
 	pi.registerTool(kdDebugTool);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,
@@ -61,6 +61,7 @@
     "smoke:harness": "tsx scripts/smoke-harness.ts",
     "smoke:official": "tsx scripts/smoke-official-tools.ts",
     "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",
     "kcode": "tsx scripts/kcode.ts",

package/skills/kd-check/SKILL.md

@@ -12,7 +12,7 @@ Checklist:
 - Magic values: status codes, operation names, field keys, table names, numbers, and business strings.
 - Naming: Java/C# naming conventions and project-local naming.
 - Lifecycle: correct plugin base class and lifecycle method for the target behavior.
-- SDK usage: no invented API names; uncertain APIs must be verified through `kd_search`.
+- SDK usage: no invented API names; uncertain Java/C# APIs must be verified through `kd_sdk_signature` against current project jars/dlls, or by compile/build evidence. Use `kd_search` only for guidance.
 - Database access: no DB query or save operation inside loops unless explicitly justified.
 - Exception handling: no empty catch blocks; errors should be logged or converted to business exceptions as appropriate.
 - Resource cleanup: close or dispose resources where the SDK requires it.
@@ -23,4 +23,3 @@ Output expectations:
 - Lead with concrete findings and file/line references when reviewing code.
 - Separate errors, warnings, and improvement suggestions.
 - State which checks were not possible because context or tools were missing.
-

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

@@ -46,7 +46,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 
 3. 通过官方适配器验证产品事实。
    - 代码引用字段、表单 ID、单据名称、枚举/下拉值、实体 ID、操作编码、SQL 字段时，使用 `kd_cosmic_metadata`。
-   - 类名、方法名、方法签名、继承关系、Override 签名未被内置知识验证时，使用 `kd_cosmic_api`。
+   - 类名、方法名、方法签名、继承关系、Override 签名不确定时，优先使用 `kd_sdk_signature` 从当前项目实际 SDK jar 中验证；`kd_cosmic_api` 只作为随包知识线索和兜底。
    - 多个表单或字段尽量合并到一次元数据查询。
    - 元数据查询和 API 签名查询互不依赖时并行执行。
 
@@ -63,7 +63,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 
 ## 硬性规则
 
-- 不臆造字段 key、表单 ID、操作名、枚举值、表名或 SDK 方法。
+- 不臆造字段 key、表单 ID、操作名、枚举值、表名或 SDK 方法；本地 SDK 查不到且编译未验证时，不把知识库结果当作最终签名事实。
 - 不把 Enterprise C# 命名空间或生命周期假设用于 Cosmic Java。
 - 星空旗舰版不允许猜目录或写 demo/sample；如果无法判断真实代码位置，先询问或更新计划，不要直接创建新目录。
 - 不在数据绑定前的初始化阶段操作 UI 控件。
@@ -78,7 +78,7 @@ description: 金蝶 Cosmic 体系 Java 插件开发技能，适用于苍穹、
 完成执行工作时说明：
 
 - 修改了哪些文件。
-- 使用了哪些官方检查：配置、元数据、API。
+- 使用了哪些检查：配置、元数据、本地 SDK 签名、API 知识、编译。
 - 哪些事实仍无法验证。
 - 验证命令和结果。
 - `EXECUTION.md` 中记录相对 `PLAN.md` 的偏差。

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

@@ -17,7 +17,7 @@ description: 金蝶 Cosmic 体系 Java 插件和 KSQL 代码审查技能，按
 
 - 存在 harness run 时，先用 `kd_plan_status` 查看产品画像。
 - 用 `kd_search` 查询 Cosmic 审查清单、生命周期、平台约束、KSQL 和单测指导。
-- SDK 签名或生命周期方法不确定时，用 `kd_cosmic_api` 验证。
+- SDK 签名或生命周期方法不确定时，优先用 `kd_sdk_signature` 从当前项目实际 SDK jar 验证；查不到时再用 `kd_cosmic_api` 获取知识库线索，并要求编译或人工证据兜底。
 - 变更中用到字段、操作、枚举值、表名、数据库列时，用 `kd_cosmic_metadata` 验证。
 - 先运行 `kd_check` 做基础静态检查，再按下方清单深入审查。
 - 对新增或修改的 SQL/KSQL 文件运行 `kd_ksql_lint`。
@@ -84,7 +84,7 @@ description: 金蝶 Cosmic 体系 Java 插件和 KSQL 代码审查技能，按
 随后说明：
 
 - 已运行和未运行的检查。
-- 已验证的产品、元数据和 API 事实。
+- 已验证的产品、元数据、本地 SDK 签名和 API 线索。
 - 剩余风险或缺失上下文。
 
 如果没有发现问题，明确说明未发现问题，并列出剩余测试或证据缺口。

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

@@ -25,7 +25,7 @@ description: 金蝶 Cosmic 体系 Java 单元测试生成和审查技能，适
 - 阅读被测类和最近的测试基类。
 - 新增测试风格前，先搜索同模块同包下已有测试。
 - 用 `kd_search` 查询 Cosmic 单测指导和模块测试模式。
-- 仅在测试或被测代码使用的 SDK 方法签名不确定时，使用 `kd_cosmic_api`。
+- 仅在测试或被测代码使用的 SDK 方法签名不确定时，优先使用 `kd_sdk_signature` 从当前项目实际 SDK jar 验证；查不到时再用 `kd_cosmic_api` 获取线索，并以编译结果兜底。
 
 ## 测试模式选择
 
@@ -56,7 +56,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 ## 测试质量规则
 
 - 使用项目已有 JUnit 和 Mockito 版本。
-- 如果项目没有既有且允许使用的单测框架，不要新增 JUnit、Mockito 或额外 jar；改用 Harness 的红绿验证门禁，例如 API/基类/方法签名、元数据、编译或最小外部接口验证。
+- 如果项目没有既有且允许使用的单测框架，不要新增 JUnit、Mockito 或额外 jar；改用 Harness 的红绿验证门禁，例如 `kd_sdk_signature` 本地 SDK 签名、元数据、编译或最小外部接口验证。
 - import 保持显式；项目风格允许时也不要使用宽泛静态通配导入。
 - 每个测试方法必须有真实断言或交互验证。
 - 避免 `assertTrue(true)`、`assertEquals(x, x)` 或只执行不验证的测试。

package/skills/kd-debug/SKILL.md

@@ -19,7 +19,7 @@ Analysis approach:
   - permission or authorization failure
   - null dynamic object or missing entry rows
   - repeated DB calls in loops causing slow saves/submits
-- Use `kd_search` for uncertain SDK behavior and `kd_table` for table assumptions.
+- Use `kd_sdk_signature` for uncertain SDK types/methods against current project jars/dlls, `kd_search` for guidance, and `kd_table`/metadata tools for table assumptions.
 
 Output expectations:
 
@@ -27,4 +27,3 @@ Output expectations:
 - Provide the next concrete inspection step.
 - Suggest a minimal fix, then verification evidence needed to prove it.
 - If evidence is insufficient, say exactly what log, stack trace, metadata, or code file is missing.
-

package/skills/kd-execute/SKILL.md

@@ -10,7 +10,7 @@ Use this skill only after `PLAN.md` exists.
 Goal:
 
 - Implement only the approved plan.
-- Use `kd_search` and `kd_table` before relying on Kingdee APIs or table schemas.
+- Use `kd_sdk_signature` before relying on uncertain Java/C# SDK APIs. Use `kd_search` for guidance and `kd_table`/metadata tools for table schemas.
 - Update `.pi/kd/runs/<run-id>/EXECUTION.md` with every planned `STEP-###`, changed files, and evidence files.
 
 Rules:
@@ -20,7 +20,7 @@ Rules:
 - For 星空旗舰版, edit only the real target path recorded in `PLAN.md` after inspecting the project. If `code/` exists, follow its actual layout; if it does not, follow the discovered source root or existing target file. Do not create demo/sample code or root-level `src/main/java` by guesswork.
 - Do not mark work complete until verification runs.
 - Do not skip planned steps. Every `STEP-###` in `PLAN.md` must be marked complete in `EXECUTION.md` with a real `evidence/...` file before entering verify.
-- Before writing production source files, run the planned red check and record failing output in `evidence/tdd-red.md`. This can be API/base-class/method-signature, metadata, compile/build, existing project test, or minimal external-interface evidence.
+- Before writing production source files, run the planned red check and record failing output in `evidence/tdd-red.md`. This can be `kd_sdk_signature` local SDK signature, metadata, compile/build, existing project test, or minimal external-interface evidence.
 - Before entering verify, rerun the same check and record passing output in `evidence/tdd-green.md`.
 - 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.
 - If implementation needs a plan change, update `PLAN.md` first.

package/skills/kd-gen/SKILL.md

@@ -13,12 +13,13 @@ Inputs to establish before coding:
 - Plugin type and correct base class.
 - Target bill/entity/form and lifecycle event.
 - Business rule and acceptance criteria.
-- Relevant SDK/table facts from `kd_search` or `kd_table`.
+- Relevant SDK/table facts from `kd_sdk_signature`, `kd_search`, `kd_table`, or product metadata tools.
 
 Rules:
 
 - Generate code only after the active run has a `PLAN.md`.
 - Use the correct base class only when verified for the target product family.
+- Verify uncertain Java/C# class names, base classes, methods, and overloads against current project SDK jars/dlls with `kd_sdk_signature`; bundled knowledge is not enough for final signature facts.
 - For 星空旗舰版, generate or edit product code only under the real target path selected in `PLAN.md` after project inspection. Follow the existing layout, whether it uses `code/`, app modules, cloud modules, or no module split; never create demo/sample code or root-level `src/main/java` by guesswork.
 - Use `kd.bos.*` style packages for Cosmic-family Java code and `Kingdee.BOS.*` style namespaces for enterprise C# code.
 - Do not reuse Cosmic/Xinghan/Cangqiong APIs for enterprise C#.

package/skills/kd-plan/SKILL.md

@@ -13,10 +13,10 @@ Goal:
 - List files to inspect before editing.
 - List the inspected project layout and the exact target source root or file path before editing.
 - List expected files to modify.
-- List required `kd_search` and `kd_table` lookups.
+- List required `kd_sdk_signature`, `kd_search`, `kd_table`, metadata, and build/compile checks.
 - List `## Execution Steps` using `- [ ] STEP-001: ...` style IDs.
 - List `## TDD / Red-Green Checks` with red evidence, green evidence, and the command/tool or product-specific check.
-- Do not plan to add third-party test jars or frameworks only for red/green checks. For Kingdee plugin work, prefer API/base-class/method-signature checks, metadata checks, compile/build checks, existing project tests, or minimal external-interface tests.
+- Do not plan to add third-party test jars or frameworks only for red/green checks. For Kingdee plugin work, prefer `kd_sdk_signature` against current project jars/dlls, metadata checks, compile/build checks, existing project tests, or minimal external-interface tests.
 - Define validation commands and expected evidence.
 - Add rollback or containment notes for medium/high risk work.
 
@@ -27,4 +27,4 @@ Gate:
 - A plan without validation commands is incomplete.
 - A plan without structured `STEP-001` execution steps is incomplete.
 - A plan without TDD red/green checks is incomplete.
-- A plan that relies on unverified Kingdee API names is incomplete.
+- A plan that relies on unverified Kingdee API names is incomplete; bundled knowledge alone is not enough when local SDK jars/dlls or compile evidence are available.

package/src/harness/gates.ts

@@ -30,11 +30,13 @@ export function inspectGate(cwd: string, run: ActiveRun): GateResult {
 	const markerProblem = inspectMarkers(cwd, run, run.phase);
 	const stepProblem = inspectStepState(cwd, run, run.phase);
 	const evidenceProblem = inspectEvidence(cwd, run, run.phase);
+	const questionProblem = inspectOpenQuestions(run);
 	const reasonParts = [];
 	if (missing.length > 0) reasonParts.push(`缺少必需产物：${[...new Set(missing)].join(", ")}`);
 	if (markerProblem) reasonParts.push(markerProblem);
 	if (stepProblem) reasonParts.push(stepProblem);
 	if (evidenceProblem) reasonParts.push(evidenceProblem);
+	if (questionProblem) reasonParts.push(questionProblem);
 
 	return {
 		passed: reasonParts.length === 0,
@@ -72,6 +74,11 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 		reasonParts.push(stepProblem);
 	}
 
+	const questionProblem = inspectOpenQuestions(run);
+	if (questionProblem) {
+		reasonParts.push(questionProblem);
+	}
+
 	missing.push(...missingEvidenceForPhase(cwd, run, target));
 
 	if (target === "ship" && !artifactExists(cwd, run, PHASE_ARTIFACTS.verify)) {
@@ -87,6 +94,12 @@ export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): Gat
 	};
 }
 
+function inspectOpenQuestions(run: ActiveRun): string | undefined {
+	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+	if (open.length === 0) return undefined;
+	return `存在未回答的阻断问题：${open.map((question) => `${question.id} ${question.question}`).join("；")}`;
+}
+
 function inspectStepState(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
 	if (phase === "execute") {
 		const plan = readArtifact(cwd, run, "plan") ?? "";
@@ -154,7 +167,7 @@ function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {
 
 function planHasApiRequirement(cwd: string, run: ActiveRun): boolean {
 	const plan = readArtifact(cwd, run, "plan") ?? "";
-	return /kd_cosmic_api|cosmic-api|api signature|method signature|sdk.*签名|方法签名|接口签名/i.test(plan);
+	return /kd_sdk_signature|kd_cosmic_api|cosmic-api|api signature|method signature|sdk.*签名|方法签名|接口签名/i.test(plan);
 }
 
 function runHasKsqlDelivery(cwd: string, run: ActiveRun): boolean {

package/src/harness/state.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import type { ActiveRun, KdPhase } from "./types.ts";
+import type { ActiveRun, KdPhase, KdQuestion } from "./types.ts";
 import { PHASE_ARTIFACTS, isKdPhase, nextPhase } from "./types.ts";
 import { activeRunPath, kdDir, runsDir } from "./paths.ts";
 import { defaultArtifactContent, ensureArtifact, ensureRunDirectories, writeArtifact } from "./artifacts.ts";
@@ -14,6 +14,7 @@ export function readActiveRun(cwd: string): ActiveRun | undefined {
 		const parsed = JSON.parse(readFileSync(path, "utf8")) as ActiveRun;
 		if (!parsed.id || !isKdPhase(parsed.phase)) return undefined;
 		parsed.artifacts ??= {};
+		parsed.questions ??= [];
 		const legacyEdition = (parsed as ActiveRun & { edition?: string }).edition;
 		parsed.profile = parsed.profile ?? profileForProduct(parsed.product ?? resolveProductProfile(legacyEdition).product);
 		parsed.product = parsed.profile.product;
@@ -41,6 +42,7 @@ export function createActiveRun(cwd: string, goal: string, productInput?: string
 		profile,
 		risk: "unknown",
 		artifacts: {},
+		questions: [],
 		gate: {
 			passed: false,
 			reason: "CONTEXT.md and product profile are required before moving to spec",
@@ -55,6 +57,43 @@ export function createActiveRun(cwd: string, goal: string, productInput?: string
 	return run;
 }
 
+export function addQuestion(
+	cwd: string,
+	run: ActiveRun,
+	input: { question: string; reason?: string; choices?: string[]; blocking?: boolean },
+): KdQuestion {
+	const existing = run.questions ?? [];
+	const question: KdQuestion = {
+		id: createQuestionId(existing.length + 1),
+		phase: run.phase,
+		question: input.question.trim(),
+		reason: input.reason?.trim() || undefined,
+		choices: input.choices?.map((choice) => choice.trim()).filter(Boolean),
+		blocking: input.blocking ?? true,
+		status: "open",
+		createdAt: new Date().toISOString(),
+	};
+	run.questions = [...existing, question];
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return question;
+}
+
+export function answerQuestion(cwd: string, run: ActiveRun, id: string, answer: string): KdQuestion | undefined {
+	const question = (run.questions ?? []).find((item) => item.id === id);
+	if (!question) return undefined;
+	question.status = "answered";
+	question.answer = answer.trim();
+	question.answeredAt = new Date().toISOString();
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return question;
+}
+
+export function openBlockingQuestions(run: ActiveRun): KdQuestion[] {
+	return (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+}
+
 export function updateProductProfile(cwd: string, run: ActiveRun, productInput: string, version?: string): ActiveRun {
 	const profile = resolveProductProfile(productInput);
 	run.product = profile.product;
@@ -115,3 +154,7 @@ function createRunId(goal: string): string {
 		.slice(0, 40);
 	return slug ? `${stamp}-${slug}` : stamp;
 }
+
+function createQuestionId(sequence: number): string {
+	return `Q-${String(sequence).padStart(3, "0")}`;
+}