kcode-pi 0.1.7 → 0.1.9

package/README.md

@@ -274,9 +274,13 @@ kcode start --provider openai --model gpt-4o
 /kd-start [--product product] [--version version] <goal>
 /kd-product <product> [--version version]
 /kd-status
+/kd-runs
+/kd-switch <run-id>
+/kd-finish
 /kd-gate
 /kd-advance [phase]
 /kd-artifact [phase] [content]
+/kd-answer Q-001 <answer>
 ```
 
 典型开始方式：
@@ -309,12 +313,30 @@ discuss -> spec -> plan -> execute -> verify -> ship
 
 KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入自然语言需求；如果当前项目还没有 active run，KCode 会自动创建 run 并进入 `discuss` 阶段，而不是直接生成代码。
 
+一个功能点对应一个 run。每个 run 都有独立阶段、计划、执行记录和证据；做另一个功能点时，不要复用上一个功能点的阶段。
+
+```text
+/kd-start 实现采购订单保存校验
+/kd-finish
+/kd-start 实现采购订单列表字段展示
+```
+
+查看和切换当前项目里的功能点 run：
+
+```text
+/kd-runs
+/kd-switch <run-id>
+```
+
+如果当前 active run 处于 `execute` 或 `verify`，但你提出的是另一个需求，KCode 会要求先创建新 run 或切换 run，避免把新需求塞进旧功能点的 `PLAN.md` 和阶段门禁。
+
 每次进入 Harness 时，KCode 会附带 `.pi/kd/PROJECT_CONTEXT.md`。这份上下文不会替代计划阶段的实际文件检查，但会让 Agent 在暂停、恢复、重新打开终端后仍知道当前项目的源码根、模块线索和禁止猜路径规则。
 
 每个需求 run 的设计和执行文档会落到本地：
 
 ```text
 .pi/kd/active-run.json
+.pi/kd/runs/<run-id>/RUN.json
 .pi/kd/runs/<run-id>/CONTEXT.md
 .pi/kd/runs/<run-id>/SPEC.md
 .pi/kd/runs/<run-id>/PLAN.md
@@ -324,7 +346,7 @@ KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入
 .pi/kd/runs/<run-id>/evidence/
 ```
 
-下次重新 `kcode start` 时，KCode 会读取当前项目的 active run、项目常驻上下文和已生成的阶段文档，再继续当前阶段。
+下次重新 `kcode start` 时，KCode 会读取当前项目的 active run、项目常驻上下文和已生成的阶段文档，再继续当前功能点的当前阶段。已完成或暂停的功能点仍保留在 `.pi/kd/runs/<run-id>/`，可用 `/kd-runs` 查看，用 `/kd-switch <run-id>` 切回。
 
 阶段含义：
 
@@ -369,7 +391,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,11 +409,28 @@ ship     汇总变更、验证证据、风险和后续事项
 
 如果 LLM 跳过步骤、没有记录 evidence，或只是口头声明完成，KCode 不允许进入 `verify`。
 
+结构化问题也会进入门禁。Agent 需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，会使用 `kd_question` 记录问题；未回答的阻断问题会阻止进入下一阶段。
+
+`kd_question` 一次只允许问一个当前最阻塞的问题，不能把多个问题打包成编号清单。比如应先问：
+
+```text
+采购入库单 Form ID 是否为 pur_receivebill？
+```
+
+得到回答后，再继续问触发时机、库存条件、弹窗内容或插件位置。
+
+在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode Question 选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
+
+```text
+/kd-answer Q-001 采购订单
+```
+
 运行状态保存在当前业务项目：
 
 ```text
 .pi/kd/active-run.json
 .pi/kd/runs/<run-id>/
+.pi/kd/runs/<run-id>/RUN.json
 ```
 
 ## 内置金蝶工具
@@ -400,12 +439,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            分析金蝶日志和堆栈
@@ -416,7 +457,17 @@ kd_debug            分析金蝶日志和堆栈
 - `kd_ksql_lint` 是内置 Node 静态检查器。
 - `kd_cosmic_config` 使用 Node 校验 Cosmic 官方能力配置；项目没有 `ok-cosmic.json` 时会自动使用 KCode 随包默认配置。
 - `kd_cosmic_metadata` 使用统一路由 API 查询真实单据/表单元数据，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
-- `kd_cosmic_api` 查询随包金蝶知识库；需要精确方法签名时，仍要结合当前项目 SDK、编译输出或红绿证据确认。
+- `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`。
 

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

@@ -1,13 +1,18 @@
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { formatStatus } from "../src/harness/format.ts";
 import { PHASE_ORDER, isKdPhase, type KdPhase } from "../src/harness/types.ts";
 import {
 	advanceRun,
+	addQuestion,
+	answerQuestion,
 	createActiveRun,
 	ensurePhaseArtifact,
+	finishActiveRun,
+	listRuns,
 	readActiveRun,
 	refreshGate,
+	switchActiveRun,
 	updateProductProfile,
 	updatePhaseArtifact,
 } from "../src/harness/state.ts";
@@ -103,11 +108,14 @@ 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。`,
+		"需要用户确认时，kd_question 一次只能问一个当前最阻塞的问题；不要把 FormId、触发时机、库存条件、弹窗内容、插件位置等打包成清单。选项最多 3 个；交互模式下会弹出选择/输入对话并自动记录答案。",
+		"",
 		phaseGuidance[run.phase],
 		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
 		"路径规则：在 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 +166,118 @@ const kdPlanStatusTool = defineTool({
 	},
 });
 
+const kdQuestionTool = defineTool({
+	name: "kd_question",
+	label: "KD Question",
+	description:
+		"Create, answer, or list structured Kingdee Harness questions. Ask exactly one short blocking question at a time; do not batch a checklist.",
+	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: "One short question to ask when action=ask. No numbered lists or multiple questions." })),
+		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, maximum 3 short labels." })),
+		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 batchProblem = questionBatchProblem(params.question, params.choices);
+		if (batchProblem) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: [
+							batchProblem,
+							"",
+							"kd_question 一次只登记一个当前最阻塞的问题。",
+							"请先问第一个必须确认的问题，例如：",
+							"kd_question action=ask question=\"采购入库单 Form ID 是否为 pur_receivebill？\" choices=[\"是\", \"不是\"]",
+							"",
+							"注意：Pi 当前不会弹出表单；问题会显示在对话里，用户在对话中回答后再用 kd_question action=answer 记录。",
+						].join("\n"),
+					},
+				],
+				details: { error: "batched-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 interactiveAnswer = await askQuestionInteractively(ctx, question.question, question.choices);
+		if (interactiveAnswer) {
+			const answered = answerQuestion(ctx.cwd, run, question.id, interactiveAnswer);
+			if (answered) {
+				appendQuestionEventToArtifact(ctx.cwd, run, [`- Answered ${answered.id}: ${answered.answer}`]);
+				return {
+					content: [{ type: "text", text: `User answered ${answered.id}: ${answered.answer}` }],
+					details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, answered: true },
+				};
+			}
+		}
+
+		const text = `${formatQuestionCard(question)}\n\nInteractive answer was not provided; keep this question open until the user answers.`;
+		return { content: [{ type: "text", text }], details: { question, gate: readActiveRun(ctx.cwd)?.gate, answered: false } };
+	},
+});
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdPlanStatusTool);
+	pi.registerTool(kdQuestionTool);
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") return { action: "continue" };
@@ -206,6 +324,14 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("kd-runs", {
+		description: "List Kingdee harness runs for this project",
+		handler: async (_args, ctx) => {
+			const active = readActiveRun(ctx.cwd);
+			ctx.ui.notify(formatRuns(listRuns(ctx.cwd), active?.id), "info");
+		},
+	});
+
 	pi.registerCommand("kd-gate", {
 		description: "Refresh and show the active Kingdee harness gate",
 		handler: async (_args, ctx) => {
@@ -234,6 +360,39 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("kd-switch", {
+		description: "Switch active Kingdee harness run: /kd-switch <run-id>",
+		handler: async (args, ctx) => {
+			const id = args.trim();
+			if (!id) {
+				ctx.ui.notify("Usage: /kd-switch <run-id>", "error");
+				return;
+			}
+
+			const run = switchActiveRun(ctx.cwd, id);
+			if (!run) {
+				ctx.ui.notify(`Kingdee harness run not found: ${id}. Use /kd-runs to list runs.`, "error");
+				return;
+			}
+
+			ctx.ui.notify(`Switched active Kingdee harness run: ${run.id} (${run.phase})`, "info");
+		},
+	});
+
+	pi.registerCommand("kd-finish", {
+		description: "Mark the active Kingdee harness run as done and clear active run",
+		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 finished = finishActiveRun(ctx.cwd, run);
+			ctx.ui.notify(`Finished Kingdee harness run: ${finished.id}. Start the next feature with /kd-start <goal>.`, "info");
+		},
+	});
+
 	pi.registerCommand("kd-product", {
 		description: "Set the active Kingdee product profile: /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise> [--version version]",
 		handler: async (args, ctx) => {
@@ -299,4 +458,114 @@ 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 formatRuns(runs: NonNullable<ReturnType<typeof readActiveRun>>[], activeId?: string): string {
+	if (runs.length === 0) return "No Kingdee harness runs in this project. Start one with /kd-start <goal>.";
+	return runs
+		.map((run) =>
+			[
+				`${run.id === activeId ? "*" : "-"} ${run.id}`,
+				`  Goal: ${run.goal ?? "unknown"}`,
+				`  Status: ${run.status ?? "active"} | Phase: ${run.phase} | Product: ${run.profile?.product ?? run.product ?? "unknown"}`,
+				`  Updated: ${run.updatedAt ?? "unknown"}`,
+			].join("\n"),
+		)
+		.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"
+			? `Answer the dialog if available, or reply in chat and record it using kd_question action=answer id=${question.id} answer=<answer>.`
+			: undefined,
+	];
+	return lines.filter(Boolean).join("\n");
+}
+
+async function askQuestionInteractively(
+	ctx: ExtensionContext,
+	question: string,
+	choices: string[] | undefined,
+): Promise<string | undefined> {
+	if (!ctx.hasUI) return undefined;
+
+	const normalizedChoices = choices?.map((choice) => choice.trim()).filter(Boolean) ?? [];
+	try {
+		if (normalizedChoices.length === 0) {
+			return (await ctx.ui.input("KCode Question", question))?.trim() || undefined;
+		}
+
+		const customChoice = "其他，自定义输入";
+		const selected = await ctx.ui.select("KCode Question", [...normalizedChoices, customChoice]);
+		if (!selected) return undefined;
+		if (selected !== customChoice) return selected;
+		return (await ctx.ui.input("KCode Question", question))?.trim() || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function questionBatchProblem(question: string, choices?: string[]): string | undefined {
+	const text = question.trim();
+	const numberedItems = text.split(/\r?\n/).filter((line) => /^\s*(\d+[\.\)、)]|[-*]\s+)/.test(line)).length;
+	if (numberedItems >= 2) return "kd_question rejected a batched checklist question.";
+	if ((text.match(/[?？]/g) ?? []).length > 1) return "kd_question rejected multiple questions in one prompt.";
+	if (text.length > 220) return "kd_question rejected an overlong question. Ask only the smallest blocking question first.";
+	if ((choices?.length ?? 0) > 3) return "kd_question rejected too many choices. Provide at most 3 concise choices.";
+	if (choices?.some((choice) => choice.length > 40 || /[\r\n?？]/.test(choice))) {
+		return "kd_question rejected complex choices. Choices must be short labels, not nested questions.";
+	}
+	return undefined;
+}
+
+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.7",
+  "version": "0.1.9",
   "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-discuss/SKILL.md

@@ -20,5 +20,6 @@ Rules:
 - Do not propose implementation before the context is clear.
 - Do not invent SDK APIs, table names, or lifecycle methods.
 - If the product/version, tech stack, or target object is unknown, mark it as an open question.
+- Ask unresolved questions one at a time. When using `kd_question`, ask only the single most blocking question and use at most 3 short choices; never submit a numbered checklist of questions.
 - Never apply enterprise C# rules to Java products, or Java/Cosmic plugin rules to enterprise C#.
 - Keep context concise; detailed design belongs in `SPEC.md`.