kcode-pi 0.1.39 → 0.1.42

package/prompts/kd-verify.md

@@ -4,8 +4,20 @@ description: 验证当前金蝶实现并收集证据。
 
 使用 `kd-verify` skill。
 
-执行 `PLAN.md` 中的验证命令。验证命令完成后必须调用 `kd_verify_result` 记录 `command`、`exitCode` 和关键输出；不要手工绕过 Harness 的验证结果记录。
-
-用户补充说明：
+执行验证阶段。输入：
 
 {{args}}
+
+执行协议：
+
+- 读取当前 run、`PLAN.md`、`EXECUTION.md` 和 evidence。
+- 只执行或记录 `PLAN.md` 声明的验证命令；替代命令必须说明等价依据。
+- 验证命令完成后必须调用 `kd_verify_result` 记录 `command`、`exitCode`、关键 stdout/stderr 和结论。
+- 外部系统、BOS 注册、人工功能测试和生产验证不能由 LLM 代办；只记录用户提供的证据来源、测试数据和结果。
+- 验证失败时进入修复循环，不得进入 ship。
+
+输出契约：
+
+- `kd_verify_result` 记录结果。
+- 通过或失败证据路径。
+- 唯一下一动作。

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

@@ -46,7 +46,7 @@ description: 金蝶苍穹/Cosmic 平台 Java 插件开发技能，适用于苍
 3. 通过官方适配器验证产品事实。
    - 代码引用字段、表单 ID、单据名称、枚举/下拉值、实体 ID、操作编码、SQL 字段时，使用 `kd_cosmic_metadata`。
    - 类名、方法名、方法签名、继承关系、Override 签名不确定时，优先使用 `kd_sdk_signature` 从当前项目实际 SDK jar 中验证；`kd_cosmic_api` 只作为随包知识线索和兜底。
-   - 多个表单或字段尽量合并到一次元数据查询。
+   - 多个表单或字段能够合并查询时，合并为一次元数据查询。
    - 元数据查询和 API 签名查询互不依赖时并行执行。
 
 4. 只有插件类型、生命周期方法、字段元数据和 API 签名都明确后，才生成或修改代码。
@@ -64,7 +64,7 @@ description: 金蝶苍穹/Cosmic 平台 Java 插件开发技能，适用于苍
 
 - 不臆造字段 key、表单 ID、操作名、枚举值、表名或 SDK 方法；本地 SDK 查不到且编译未验证时，不把知识库结果当作最终签名事实。
 - 不把 Enterprise C# 命名空间或生命周期假设用于苍穹/Cosmic 平台 Java。
-- 星空旗舰版不允许猜目录或写 demo/sample；如果无法判断真实代码位置，先询问或更新计划，不要直接创建新目录。
+- 星空旗舰版不允许猜目录或写 demo/sample；无法判断真实代码位置时，先登记阻塞问题或更新计划，不得直接创建新目录。
 - 不在数据绑定前的初始化阶段操作 UI 控件。
 - 不在平台期望修改入参数据实体的事务钩子里另起保存。
 - 不在循环中查询或保存，除非计划中明确说明无法批量处理并接受风险。

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

@@ -26,7 +26,7 @@ description: 金蝶苍穹/Cosmic 平台 Java 插件和 KSQL 代码审查技能
 
 - P0：阻断问题，可能导致崩溃、数据损坏、事务失效、安全暴露、严重资源泄漏或核心功能不可用。
 - P1：高风险问题，可能影响生产性能、稳定性、扩展性或可维护性。
-- P2：规范和可维护性问题，建议在合适时机修复。
+- P2：规范和可维护性问题，应在计划窗口修复。
 
 ## P0 重点
 
@@ -79,7 +79,7 @@ description: 金蝶苍穹/Cosmic 平台 Java 插件和 KSQL 代码审查技能
 - 文件和行号。
 - 具体问题。
 - 为什么在 Cosmic 中有风险。
-- 修复建议。
+- 修复指令。
 
 随后说明：
 

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

@@ -51,7 +51,7 @@ description: 金蝶 Cosmic 体系 Java 单元测试生成和审查技能，适
 - 需要构造的 `DynamicObject` 字段和集合结构。
 - 被测代码中应由测试暴露而不是绕过的 bug。
 
-POJO 或简单枚举场景可以简要说明后直接实现。
+POJO 或简单枚举场景允许在说明依据后直接实现。
 
 ## 测试质量规则
 
@@ -70,7 +70,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 
 - 优先使用项目已有 `DynamicObjectMocker`、`CommonMockObject`、`BaseTest`、`BasePluginTest`。
 - `DataSet` 和查询行只 mock 实际 select 并读取的字段。
-- 查询别名里包含点号时，如果平台 mocker 无法安全表示，使用 mock 的 `DynamicObject`。
+- 查询别名里包含点号且平台 mocker 无法安全表示时，使用 mock 的 `DynamicObject`。
 - 对 `kd.bos.db.DB`，遵循项目已有 Class defrost 后再静态 mock 的模式。
 - 对带分布式缓存行为的 helper，先搜索已有测试中的专用 mock helper，不直接 `mockStatic`。
 
@@ -79,7 +79,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 写完测试后：
 
 - 使用 `kd_build` 或计划中的命令运行最窄可行 Gradle test 任务。
-- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task。
+- 本机缺少业务 jar 或本地配置导致 Gradle 不能运行时，明确说明真实阻塞原因，并给出应运行的 Gradle task。
 - 存在 harness run 时，把测试文件和验证结果写入 `.pi/kd/runs/<run-id>/EXECUTION.md`。
 
 ## 输出要求

package/skills/kd-discuss/SKILL.md

@@ -21,5 +21,7 @@ Rules:
 - 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.
+- If any open blocking question already exists, do not ask or list another question; record the current answer first.
+- Treat API/SDK documentation as technical evidence only; it cannot establish FormId, fields, entities, plugin events, table names, integration mappings, concurrency policy, or acceptance data.
 - 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`.

package/skills/kd-execute/SKILL.md

@@ -17,6 +17,8 @@ Rules:
 
 - Do not broaden scope silently.
 - Do not rewrite unrelated modules.
+- Do not write code when implementation contract, data source context, SDK signature evidence, TDD red evidence, or PLAN-approved paths are missing.
+- Do not use API documentation or bundled knowledge to fill business identifiers; stop and ask one blocking question or collect metadata evidence.
 - 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.
@@ -26,3 +28,4 @@ Rules:
 - 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 the command cannot run, record the blocker instead of marking verification passed.
 - If implementation needs a plan change, update `PLAN.md` first.
+- External BOS registration, third-party system operation, and manual functional tests must be recorded as user-provided evidence; do not claim the LLM completed them.

package/skills/kd-plan/SKILL.md

@@ -22,6 +22,7 @@ Goal:
 - 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.
+- For enterprise Python plugins, do not invent a local build step; require BOS registration and user-provided functional test evidence in `VERIFY.md`.
 
 Gate:
 
@@ -32,3 +33,5 @@ Gate:
 - 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; bundled knowledge alone is not enough when local SDK jars/dlls or compile evidence are available.
+- A plan that lacks implementation contract, data source context, integration context, or acceptance data must stop at one blocking question; do not create a broad question list.
+- A plan that writes demo/sample/scaffold or placeholder paths is invalid.

package/skills/kd-ship/SKILL.md

@@ -19,4 +19,5 @@ Rules:
 - Do not claim completion without verification evidence.
 - Keep the handoff concise and decision-oriented.
 - If verification is partial, say so clearly.
-
+- Do not describe external system operation, BOS registration, manual functional testing, or production validation as completed unless the user supplied verifiable evidence.
+- Include remaining manual validation boundaries and residual risk explicitly.

package/skills/kd-spec/SKILL.md

@@ -18,6 +18,9 @@ Goal:
 Rules:
 
 - Separate confirmed facts from assumptions.
-- Mark every API/table assumption as requiring lookup with `kd_search` or `kd_table`.
+- Write only verifiable facts into the specification; unresolved business identifiers must become a single blocking question.
+- Mark every API/table assumption as requiring lookup with local metadata, SDK signature, build output, or product evidence. Bundled knowledge alone is only a clue.
 - Do not edit product code in this phase.
-- If acceptance criteria are vague, ask targeted questions one at a time or state explicit assumptions. 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.
+- If acceptance criteria are vague, ask targeted 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.
+- If any open blocking question already exists, stop and record the answer before continuing.
+- Do not generate implementation templates, sample code, or pseudo-code in `SPEC.md`.

package/skills/kd-verify/SKILL.md

@@ -22,3 +22,5 @@ Rules:
 - If validation cannot run, state the exact blocker.
 - Do not hand-edit `VERIFY.md` as the primary result path; `kd_verify_result` owns pass/failure evidence and the repair loop.
 - Do not ship while verification evidence is missing.
+- Do not convert skipped external/BOS/manual validation into a pass. Record user-provided evidence source, test data, environment, and result.
+- If validation fails, keep the run in the repair loop; do not summarize delivery or mark residual risk as low.

package/src/cli/kcode.ts

@@ -12,6 +12,7 @@ export interface KcodeCliResult {
 
 interface PiSettings {
 	packages?: string[];
+	shellPath?: string;
 	[key: string]: unknown;
 }
 
@@ -100,6 +101,7 @@ export function doctor(cwd: string, args: string[] = []): KcodeCliResult {
 	lines.push(`KCode package：${packageRoot}`);
 	lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，运行 kcode init"}`);
 	lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，运行 kcode context"}`);
+	lines.push(`Windows bash：${process.platform === "win32" ? formatWindowsBashStatus(readSettingsSafe(settingsPath)) : "不适用"}`);
 
 	if (existsSync(settingsPath)) {
 		const settingsResult = readSettingsSafe(settingsPath);
@@ -135,6 +137,10 @@ export function doctor(cwd: string, args: string[] = []): KcodeCliResult {
 			warnings++;
 			lines.push("[WARN] 项目上下文不存在，运行 kcode context --refresh 或 kcode repair。");
 		}
+		if (process.platform === "win32" && !findWindowsBash(readSettingsSafe(settingsPath))) {
+			warnings++;
+			lines.push("[WARN] Pi 内置 bash 在当前 Windows 环境不可用；KCode 已覆盖 bash 为 PowerShell，并提供 kd_find_file/kd_list_dir。安装 Git for Windows 可恢复 Pi 原生 bash。");
+		}
 		const npmPrefix = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" });
 		const npmRoot = spawnSync("npm", ["root", "-g"], { encoding: "utf8" });
 		lines.push(`npm prefix -g：${npmPrefix.status === 0 ? npmPrefix.stdout.trim() : "不可用"}`);
@@ -351,3 +357,24 @@ function helpText(): string {
 		"  kcode start     初始化项目配置后启动 KCode 工作环境",
 	].join("\n");
 }
+
+function formatWindowsBashStatus(settingsResult: ReturnType<typeof readSettingsSafe>): string {
+	const bash = findWindowsBash(settingsResult);
+	return bash ? `可用（${bash}）` : "不可用；KCode 将使用 PowerShell 覆盖工具和 kd_find_file/kd_list_dir";
+}
+
+function findWindowsBash(settingsResult?: ReturnType<typeof readSettingsSafe>): string | undefined {
+	const configured = settingsResult?.ok && typeof settingsResult.settings.shellPath === "string" ? settingsResult.settings.shellPath : undefined;
+	if (configured && existsSync(configured)) return configured;
+	const candidates = [
+		process.env.ProgramFiles ? join(process.env.ProgramFiles, "Git", "bin", "bash.exe") : undefined,
+		process.env["ProgramFiles(x86)"] ? join(process.env["ProgramFiles(x86)"]!, "Git", "bin", "bash.exe") : undefined,
+		...pathEntries().map((entry) => join(entry, "bash.exe")),
+	].filter((item): item is string => Boolean(item));
+	return candidates.find((candidate) => existsSync(candidate));
+}
+
+function pathEntries(): string[] {
+	const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+	return (process.env[pathKey] ?? "").split(";").filter(Boolean);
+}

package/src/harness/messages.ts

@@ -1,10 +1,6 @@
 import type { KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS } from "./types.ts";
 import {
-	DATA_SOURCE_CONTEXT_FIELDS,
-	IMPLEMENTATION_CONTRACT_FIELDS,
-	INTEGRATION_CONTEXT_FIELDS,
-	fieldLabels,
 	questionForMissingLabel,
 } from "./prompt-policy.ts";
 
@@ -20,9 +16,12 @@ export function unknownRiskReason(): string {
 }
 
 export function openQuestionsReason(questions: Array<{ id: string; question: string }>): string {
+	const first = questions[0];
+	if (!first) return "不存在未回答的阻断问题。";
+	const remaining = questions.length > 1 ? `；另有 ${questions.length - 1} 个历史 open 问题，需先处理当前问题后再逐个处理` : "";
 	return [
-		`存在未回答的阻断问题：${questions.map((question) => `${question.id} ${question.question}`).join("；")}`,
-		"下一步：获取用户答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录。",
+		`当前未回答的阻断问题：${first.id} ${first.question}${remaining}`,
+		`下一步：只获取 ${first.id} 的用户答案，然后用 kd_question action=answer id=${first.id} answer=<用户答案> 记录；禁止继续提出其他问题。`,
 	].join("。");
 }
 
@@ -33,8 +32,8 @@ export function repairBlockedReason(attempts: number, maxAttempts: number, evide
 
 export function dataSourcePlanBlockedReason(missing: string[]): string {
 	return [
-		`不能进入 execute：业务数据源上下文不完整，缺少 ${missing.join("、")}。`,
-		`下一步：停止编码，使用 kd_question 逐项确认 ${fieldLabels(DATA_SOURCE_CONTEXT_FIELDS).join("、")}。`,
+		missingSummary("业务数据源上下文", missing),
+		"下一步：停止编码，只登记当前最阻塞问题；用户回答并记录后，再重新刷新门禁决定下一问。",
 		nextQuestionInstruction(missing),
 		"API 文档只能作为调用线索，不能替代这些业务事实。",
 	].filter(Boolean).join("");
@@ -42,8 +41,8 @@ export function dataSourcePlanBlockedReason(missing: string[]): string {
 
 export function integrationPlanBlockedReason(missing: string[]): string {
 	return [
-		`不能进入 execute：第三方对接上下文不完整，缺少 ${missing.join("、")}。`,
-		`下一步：停止编码，使用 kd_question 逐项确认 ${fieldLabels(INTEGRATION_CONTEXT_FIELDS).join("、")}。`,
+		missingSummary("第三方对接上下文", missing),
+		"下一步：停止编码，只登记当前最阻塞问题；用户回答并记录后，再重新刷新门禁决定下一问。",
 		nextQuestionInstruction(missing),
 		"缺少这些信息时禁止生成模板代码。",
 	].filter(Boolean).join("");
@@ -51,8 +50,8 @@ export function integrationPlanBlockedReason(missing: string[]): string {
 
 export function implementationPlanBlockedReason(missing: string[]): string {
 	return [
-		`不能进入 execute：实现就绪信息不完整，缺少 ${missing.join("、")}。`,
-		`下一步：禁止生成模板代码；使用 kd_question 按最阻塞项逐个确认 ${fieldLabels(IMPLEMENTATION_CONTRACT_FIELDS).join("、")}。`,
+		missingSummary("实现就绪信息", missing),
+		"下一步：禁止生成模板代码，只登记当前最阻塞问题；用户回答并记录后，再重新刷新门禁决定下一问。",
 		nextQuestionInstruction(missing),
 		"这些字段是所有插件、服务和集成实现的通用输入，不依赖具体业务场景枚举。",
 	].filter(Boolean).join("");
@@ -158,15 +157,22 @@ export function dataSourceWriteBlockedReason(path: string, evidenceName: string)
 }
 
 export function integrationWriteBlockedReason(path: string, missing: string[]): string {
-	return `不能写生产源码 ${path}：第三方对接上下文不完整，缺少 ${missing.join("、")}。下一步：补齐 ${fieldLabels(INTEGRATION_CONTEXT_FIELDS).join("、")}。`;
+	return `不能写生产源码 ${path}：第三方对接上下文不完整，当前最阻塞缺失：${missing[0] ?? "未知"}。下一步：只确认当前缺失事实，记录后重新刷新门禁；禁止一次性向用户索要完整清单。`;
 }
 
 export function implementationWriteBlockedReason(path: string, missing: string[]): string {
-	return `不能写生产源码 ${path}：实现就绪信息不完整，缺少 ${missing.join("、")}。下一步：确认 ${fieldLabels(IMPLEMENTATION_CONTRACT_FIELDS).join("、")}；信息不足时继续提问，禁止生成模板代码。`;
+	return `不能写生产源码 ${path}：实现就绪信息不完整，当前最阻塞缺失：${missing[0] ?? "未知"}。下一步：只确认当前缺失事实，记录后重新刷新门禁；信息不足时继续提问，禁止生成模板代码。`;
 }
 
 function nextQuestionInstruction(missing: string[]): string | undefined {
 	const question = questionForMissingLabel(missing[0]);
 	if (!question) return undefined;
-	return `阻断问题命令：kd_question action=ask factLabel="${missing[0]}" question="${question}" reason="${missing[0]} 缺失会阻塞实现。"。`;
+	return `唯一允许的阻断问题命令：kd_question action=ask factLabel="${missing[0]}" question="${question}" reason="${missing[0]} 缺失会阻塞实现。"。`;
+}
+
+function missingSummary(scope: string, missing: string[]): string {
+	const first = missing[0] ?? "未知";
+	const remaining = Math.max(0, missing.length - 1);
+	const remainingText = remaining > 0 ? `；另有 ${remaining} 项待后续逐项确认，本轮不得向用户展开` : "";
+	return `不能进入 execute：${scope}不完整，当前最阻塞缺失：${first}${remainingText}。`;
 }

package/src/harness/prompt-policy.ts

@@ -145,6 +145,7 @@ export const INTEGRATION_CONTEXT_FIELDS: ContractField[] = [
 export const PROJECT_PERSISTENT_RULES = [
 	"计划或编辑代码前必须读取本文件；本文件过期时先运行 `kcode context --refresh`。",
 	"信息不足时禁止开始编码。必须先登记一个最阻塞的结构化问题，获得可核验答案后再继续；禁止输出 demo/sample/scaffold、模板代码或占位实现。",
+	"任何时刻最多只能存在一个 open blocking question；已有未回答阻断问题时，必须先记录用户答案，禁止继续提出、登记或展示其他问题。",
 	"API 文档、SDK 文档和知识库只能证明技术用法，不能替代业务事实。FormId、单据/表单标识、字段/实体/分录标识、插件类型与事件、SQL/KSQL 表名和数据库字段名必须来自用户确认、项目元数据或 evidence。",
 	`产品代码实现前必须具备通用实现契约：${IMPLEMENTATION_CONTRACT_FIELDS.map((field) => field.label).join("、")}。`,
 	`涉及业务数据源时必须具备数据源上下文：${DATA_SOURCE_CONTEXT_FIELDS.map((field) => field.label).join("、")}。`,
@@ -154,9 +155,11 @@ export const PROJECT_PERSISTENT_RULES = [
 	"`run.facts` 是唯一结构化事实源；已回答 questions 仅为审计记录，禁止在读取状态时从历史 question 反推事实。",
 	"`factLabel` 必须使用集中定义的事实标签或别名；未知标签、占位答案、口头确认语、待确认/TODO/TBD/按实际环境等不能解除门禁。",
 	"用户回答 open question 后，先用 `kd_question action=answer` 写入答案；用户更正事实时用 `kd_question action=revise`，禁止重复询问已确认事实。",
+	"门禁提示只暴露当前最阻塞缺失事实；后续待确认项只能在当前问题回答后重新刷新门禁逐项生成，禁止一次性向用户展开完整问题清单。",
 	"企业版 Python 插件通常没有本地构建可替代验证；BOS 注册、外部系统操作、人工功能测试和生产环境验证必须由用户提供可核验证据并记录来源。",
 	"提示语集中管理为正式工程指令；禁止口语化、闲聊式、鼓励式提示词进入运行时规则。",
 	"工具使用必须匹配当前会话实际可用工具和操作系统；Windows 默认使用 PowerShell、`rg`、`Get-ChildItem`、`Get-Content`，禁止假设 bash 可用。",
+	"Windows 查找文件和目录时优先使用 `kd_find_file`、`kd_list_dir` 或 PowerShell；禁止用 Linux find/ls 语法反复调用 Pi 内置 bash。",
 	"文件定位必须使用真实搜索或目录读取结果；工具不可用时明确说明阻塞原因和需要用户执行的命令，禁止猜测路径、反复自述工具失败或用 kd_subagent 代替基础文件搜索。",
 	"不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实必须重新提问确认。",
 ];
@@ -166,6 +169,49 @@ export const PROMPT_STYLE_RULES = [
 	"事实不足时生成阻断问题；禁止输出模板代码、占位实现或基于猜测的业务标识。",
 	"每次只提出一个最阻塞问题；问题必须指向可验证事实、数据标识或验收证据。",
 	"引用顺序：当前项目文件、PLAN/SPEC、元数据 evidence、SDK 签名、验证输出。",
+	"响应必须说明当前阶段、门禁结论、采用的事实来源和唯一下一动作；禁止同时给出多个并行动作让用户选择。",
+];
+
+export const PROMPT_DECISION_PROTOCOL = [
+	"先读取 Harness 状态、当前阶段资料、已问已答事实和项目上下文；禁止只根据用户最后一句话行动。",
+	"先判断用户输入是否是在回答 open blocking question；如是，唯一动作是调用 `kd_question action=answer` 记录答案。",
+	"再判断当前阶段门禁是否阻塞；阻塞时只执行门禁要求的唯一下一动作，禁止绕过阶段推进。",
+	"再判断是否缺少可核验事实；缺失时只登记当前最阻塞的一个问题，禁止展开后续问题。",
+	"只有在阶段、门禁、事实和证据均满足时，才允许进入计划、编码、验证或交付动作。",
+];
+
+export const PROMPT_FACT_PROTOCOL = [
+	"`run.facts` 是结构化事实唯一来源；`questions` 仅为问答审计记录。",
+	"业务事实必须有来源分类：用户明确回答、项目元数据/evidence、当前项目文件、验证输出。",
+	"API/SDK 文档只作为技术用法线索；不得补全 FormId、字段标识、实体标识、表名、接口字段映射、并发策略或验收数据。",
+	"事实值包含待确认、未知、按实际环境、TODO/TBD、可以、好的、是/否等内容时，视为无效事实。",
+	"同一事实存在冲突时，停止推进并使用 `kd_question action=revise` 或登记一个最阻塞更正问题。",
+];
+
+export const PROMPT_QUESTION_PROTOCOL = [
+	"任何时刻最多存在一个 open blocking question。",
+	"已有 open blocking question 时，禁止继续提问、禁止输出问题清单、禁止登记新问题；唯一动作是获取并记录该问题答案。",
+	"`kd_question action=ask` 的问题文本只能包含一个事实点，不能使用编号列表、多个问号或复合事实。",
+	"带 `factLabel` 的问题必须使用集中定义标签或别名；产品类型不是 factLabel。",
+	"问题登记后停止推进，等待用户回答；不得在同一轮继续生成方案、计划或代码。",
+];
+
+export const PROMPT_OUTPUT_CONTRACT = [
+	"阻塞时输出：阻塞原因、唯一下一动作、需要使用的工具或命令；不得输出实现方案或代码片段。",
+	"提问时输出：只登记或展示一个问题；不得附带后续问题预告清单。",
+	"计划时输出：目标路径、允许修改文件、查证项、验证命令、回滚方式和 evidence 要求。",
+	"执行时输出：仅说明已修改文件、证据文件和验证结果；不得把未验证内容写成已完成。",
+	"验证失败时输出：失败证据、定位结论、下一轮修复边界；不得直接跳到 ship。",
+];
+
+export const PROMPT_PROHIBITED_BEHAVIORS = [
+	"禁止根据 API 文档、SDK 记忆或知识库推断业务数据源。",
+	"禁止生成 demo/sample/scaffold、占位实现、伪代码或仅可手工替换的模板。",
+	"禁止一次性向用户索要多项业务信息。",
+	"禁止重复询问已确认事实或已存在 open blocking question 的问题。",
+	"禁止猜测路径、包名、类名、FormId、字段、实体、SQL 表名、数据库字段名或接口字段映射。",
+	"禁止用子 agent、shell 失败自述或自由文本计划绕过门禁。",
+	"禁止将外部系统操作、BOS 注册、人工功能测试或生产验证描述为 LLM 已完成。",
 ];
 
 export const CORE_WORKFLOW_CONSTRAINTS = [
@@ -174,6 +220,7 @@ export const CORE_WORKFLOW_CONSTRAINTS = [
 	"业务数据源未知时禁止编码；确认目标 FormId/单据或表单、插件类型和事件、字段/实体/分录标识、数据读取写入方式后再编码；SQL/KSQL 同步确认表名和数据库字段名。",
 	"第三方对接确认接口文档、对接方向、触发时机、认证配置、字段映射、并发/幂等、重试超时限流、错误补偿、日志脱敏和验收样例后再编码。",
 	"事实缺失时使用 kd_question 登记一个最阻塞问题；禁止用 API 文档、SDK 知识库或推测替代业务事实。",
+	"已有 open blocking question 时禁止继续提问；先记录该问题答案，再根据刷新后的门禁决定下一问。",
 	"用户输入是在回答 open question 时，必须先调用 kd_question action=answer 记录答案，再继续推进或登记下一个问题。",
 	"同一 factLabel 已有当前事实时禁止重复提问；用户明确更正时使用 kd_question action=revise 记录新事实和更正原因。",
 	"run.facts 是唯一结构化事实源；questions 仅作为问答审计记录，禁止从历史 question 反推门禁事实。",
@@ -183,7 +230,7 @@ export const CORE_WORKFLOW_CONSTRAINTS = [
 	"evidence 必须记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
 	"外部系统操作、BOS 注册、人工功能测试和生产环境验证不能由 LLM 代办；必须要求用户提供验证结果或可核验证据，并记录证据来源。",
 	"Windows 路径规则：项目相对路径为默认；绝对路径使用 D:\\... 形式。",
-	"工具规则：按当前会话实际 shell 和工具执行；Windows 不假设 bash，可用 PowerShell/rg/Get-ChildItem/Get-Content；禁止猜路径或用 kd_subagent 代替基础搜索失败。",
+	"工具规则：按当前会话实际 shell 和工具执行；Windows 不假设 bash，优先用 kd_find_file/kd_list_dir/PowerShell；禁止猜路径或用 kd_subagent 代替基础搜索失败。",
 ];
 
 export const PHASE_GUIDANCE: Record<KdPhase, string> = {
@@ -214,6 +261,25 @@ export function fieldLabels(fields: ContractField[]): string[] {
 	return fields.map((field) => field.label);
 }
 
+export function allFactLabels(): string[] {
+	return fieldLabels([...IMPLEMENTATION_CONTRACT_FIELDS, ...DATA_SOURCE_CONTEXT_FIELDS, ...INTEGRATION_CONTEXT_FIELDS]);
+}
+
+export function formatFactLabelCatalog(): string {
+	return [
+		"## 实现契约事实标签",
+		...formatPromptLines(fieldLabels(IMPLEMENTATION_CONTRACT_FIELDS)),
+		"",
+		"## 数据源上下文事实标签",
+		...formatPromptLines(fieldLabels(DATA_SOURCE_CONTEXT_FIELDS)),
+		"",
+		"## 第三方对接事实标签",
+		...formatPromptLines(fieldLabels(INTEGRATION_CONTEXT_FIELDS)),
+		"",
+		"产品类型/产品画像不是 factLabel；使用 /kd-product <产品> 或先登记无 factLabel 的产品确认问题。",
+	].join("\n");
+}
+
 export function questionForMissingLabel(label: string): string | undefined {
 	const fields = [...IMPLEMENTATION_CONTRACT_FIELDS, ...DATA_SOURCE_CONTEXT_FIELDS, ...INTEGRATION_CONTEXT_FIELDS];
 	return fields.find((field) => field.label === label)?.question;

package/src/harness/prompt.ts

@@ -4,7 +4,17 @@ import { delegationGuidanceForWorkflow, shouldInjectDelegationGuidance } from ".
 import { formatStatus } from "./format.ts";
 import type { ActiveRun, KdPhase } from "./types.ts";
 import { PHASE_ORDER } from "./types.ts";
-import { CORE_WORKFLOW_CONSTRAINTS, PHASE_GUIDANCE, PROMPT_STYLE_RULES, formatPromptLines } from "./prompt-policy.ts";
+import {
+	CORE_WORKFLOW_CONSTRAINTS,
+	PHASE_GUIDANCE,
+	PROMPT_DECISION_PROTOCOL,
+	PROMPT_FACT_PROTOCOL,
+	PROMPT_OUTPUT_CONTRACT,
+	PROMPT_PROHIBITED_BEHAVIORS,
+	PROMPT_QUESTION_PROTOCOL,
+	PROMPT_STYLE_RULES,
+	formatPromptLines,
+} from "./prompt-policy.ts";
 import { formatQuestionMemory } from "./question-memory.ts";
 
 export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: string): string {
@@ -33,6 +43,21 @@ export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: stri
 		"当前阶段任务：",
 		phaseGuidance,
 		"",
+		"执行顺序协议：",
+		...formatPromptLines(PROMPT_DECISION_PROTOCOL),
+		"",
+		"事实处理协议：",
+		...formatPromptLines(PROMPT_FACT_PROTOCOL),
+		"",
+		"提问协议：",
+		...formatPromptLines(PROMPT_QUESTION_PROTOCOL),
+		"",
+		"输出契约：",
+		...formatPromptLines(PROMPT_OUTPUT_CONTRACT),
+		"",
+		"禁止行为：",
+		...formatPromptLines(PROMPT_PROHIBITED_BEHAVIORS),
+		"",
 		"工程指令风格：",
 		...formatPromptLines(PROMPT_STYLE_RULES),
 		"",

package/src/harness/question-memory.ts

@@ -1,5 +1,5 @@
 import type { ActiveRun, KdFact, KdQuestion } from "./types.ts";
-import { canonicalFactLabel } from "./prompt-policy.ts";
+import { allFactLabels, canonicalFactLabel, formatFactLabelCatalog } from "./prompt-policy.ts";
 
 export function formatQuestionMemory(run: ActiveRun): string {
 	const questions = Array.isArray(run.questions) ? run.questions : [];
@@ -96,16 +96,20 @@ export function factFromAnsweredQuestion(question: KdQuestion, now = new Date().
 
 export function questionAskBlockReason(run: ActiveRun, input: { factLabel?: string }): string | undefined {
 	const rawLabel = input.factLabel?.trim();
-	if (!rawLabel) return undefined;
-	const label = canonicalFactLabel(rawLabel);
-	if (!label) return `未知 factLabel：${rawLabel}。必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签。`;
-	const key = factKey(label);
-	const open = (Array.isArray(run.questions) ? run.questions : []).find(
-		(question) => question.status === "open" && question.blocking && question.factLabel && factKey(question.factLabel) === key,
-	);
-	if (open) {
+	const label = rawLabel ? canonicalFactLabel(rawLabel) : undefined;
+	if (rawLabel && !label) return [`未知 factLabel：${rawLabel}。必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签。`, "", "执行 `kd_question action=labels` 查看完整合法标签。", "", formatFactLabelCatalog()].join("\n");
+	const openBlocking = (Array.isArray(run.questions) ? run.questions : []).filter((question) => question.status === "open" && question.blocking);
+	const sameFactOpen = label
+		? openBlocking.find((question) => question.factLabel && factKey(question.factLabel) === factKey(label))
+		: undefined;
+	const open = sameFactOpen ?? openBlocking[0];
+	if (open && sameFactOpen && label) {
 		return `事实标签 ${label} 已有未回答问题 ${open.id}，禁止重复提问。下一步：获取用户答案后用 kd_question action=answer id=${open.id} answer=<答案> 记录。`;
 	}
+	if (open) {
+		return `已有未回答阻断问题 ${open.id}：${open.question}。禁止继续登记其他问题。下一步：只获取该问题答案，并用 kd_question action=answer id=${open.id} answer=<答案> 记录。`;
+	}
+	if (!label) return undefined;
 	const fact = currentFactForLabel(run, label);
 	if (fact) {
 		return `事实标签 ${label} 已确认为 ${fact.value}，禁止重复提问。用户明确更正时使用 kd_question action=revise factLabel="${label}" answer="<新值>" reason="<更正原因>"。`;
@@ -113,6 +117,26 @@ export function questionAskBlockReason(run: ActiveRun, input: { factLabel?: stri
 	return undefined;
 }
 
+export function questionFactLabelMismatchReason(input: { question: string; factLabel?: string }): string | undefined {
+	const question = input.question.trim();
+	const label = input.factLabel?.trim() ? canonicalFactLabel(input.factLabel) : undefined;
+	if (!label) return undefined;
+	const asksProduct = /产品类型|产品画像|金蝶产品|技术栈|苍穹|星瀚|星空旗舰版|旗舰版|企业版|Cloud\s*BOS|Cosmic|BOS/i.test(question);
+	const asksOtherFact = allFactLabels().some((candidate) => candidate !== label && labelAppearsInQuestion(question, candidate));
+	const conjunction = /以及|和|并|同时|还有|及|\/|、|，|,/.test(question);
+	if (asksProduct && (asksOtherFact || conjunction)) {
+		return [
+			`问题文本同时要求确认产品类型和 ${label}，但 factLabel 只能记录一个结构化事实。`,
+			"产品类型/产品画像不是 factLabel；先使用 /kd-product <产品>，或登记一个无 factLabel 的产品确认问题。",
+			`确认产品后，再单独登记 ${label}。`,
+		].join("\n");
+	}
+	if (asksOtherFact && conjunction) {
+		return `问题文本包含多个结构化事实，但 factLabel 只能是一个：${label}。必须拆成单事实问题，并且每次只登记当前最阻塞的一个。`;
+	}
+	return undefined;
+}
+
 export function invalidFactValueReason(value: string): string | undefined {
 	return isInvalidFactValue(value) ? "事实值不是可核验内容，不能使用待确认、未知、按实际环境、TODO/TBD、单独确认/否定或口头确认语解除门禁。" : undefined;
 }
@@ -218,3 +242,15 @@ function normalizePersistedFact(fact: KdFact): KdFact[] {
 	if (!label || !value || invalidFactValueReason(value)) return [];
 	return [{ ...fact, key: factKey(label), label, value }];
 }
+
+function labelAppearsInQuestion(question: string, label: string): boolean {
+	const normalizedQuestion = question.toLowerCase().replace(/\s+/g, "");
+	const normalizedLabel = label.toLowerCase().replace(/\s+/g, "");
+	if (normalizedQuestion.includes(normalizedLabel)) return true;
+	if (label === "目标 FormId/单据或表单标识") return /formid|formid|单据标识|表单标识|目标单据|目标表单/i.test(question);
+	if (label === "插件类型和触发事件") return /插件类型|触发事件|生命周期|挂载点|审核事件|保存事件/i.test(question);
+	if (label === "字段/实体/分录标识") return /字段标识|实体标识|分录标识|字段|实体|单据体/i.test(question);
+	if (label === "数据读取写入方式") return /读取方式|写入方式|读写|取数|数据访问|SQL|KSQL/i.test(question);
+	if (label === "SQL/KSQL 表名和数据库字段名") return /表名|数据库字段名|SQL字段|KSQL字段/i.test(question);
+	return false;
+}

package/src/tools/file-search.ts

@@ -0,0 +1,107 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { resolveWorkspacePath } from "../platform/path.ts";
+
+const IGNORED_DIRS = new Set([".git", ".idea", ".pi", ".tmp", ".vscode", "bin", "build", "dist", "node_modules", "obj", "out", "target"]);
+const DEFAULT_MAX_RESULTS = 50;
+const MAX_ENTRIES = 50000;
+
+export interface FileSearchResult {
+	path: string;
+	type: "file" | "directory";
+	size?: number;
+}
+
+export function findFiles(cwd: string, input: { root?: string; name: string; maxResults?: number }): FileSearchResult[] {
+	const root = resolveWorkspacePath(cwd, input.root || ".");
+	const pattern = input.name.trim();
+	if (!pattern) throw new Error("kd_find_file requires a non-empty name.");
+	if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`Search root is not a directory: ${root}`);
+
+	const maxResults = clampLimit(input.maxResults);
+	const matcher = wildcardMatcher(pattern);
+	const results: FileSearchResult[] = [];
+	const queue = [root];
+	let visited = 0;
+
+	while (queue.length > 0 && results.length < maxResults && visited < MAX_ENTRIES) {
+		const current = queue.shift();
+		if (!current) break;
+
+		let children;
+		try {
+			children = readdirSync(current, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		for (const child of children) {
+			if (results.length >= maxResults || visited >= MAX_ENTRIES) break;
+			const fullPath = join(current, child.name);
+			visited++;
+
+			if (child.isDirectory()) {
+				if (!IGNORED_DIRS.has(child.name)) queue.push(fullPath);
+				if (matcher(child.name)) results.push({ path: displayPath(cwd, fullPath), type: "directory" });
+				continue;
+			}
+
+			if (child.isFile() && matcher(child.name)) {
+				let size: number | undefined;
+				try {
+					size = statSync(fullPath).size;
+				} catch {
+					size = undefined;
+				}
+				results.push({ path: displayPath(cwd, fullPath), type: "file", size });
+			}
+		}
+	}
+
+	return results;
+}
+
+export function listDirectory(cwd: string, input: { path?: string; maxEntries?: number }): FileSearchResult[] {
+	const dir = resolveWorkspacePath(cwd, input.path || ".");
+	if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`Path is not a directory: ${dir}`);
+	const maxEntries = clampLimit(input.maxEntries);
+	return readdirSync(dir, { withFileTypes: true })
+		.slice(0, maxEntries)
+		.map((entry) => {
+			const fullPath = join(dir, entry.name);
+			if (entry.isDirectory()) return { path: displayPath(cwd, fullPath), type: "directory" as const };
+			let size: number | undefined;
+			try {
+				size = statSync(fullPath).size;
+			} catch {
+				size = undefined;
+			}
+			return { path: displayPath(cwd, fullPath), type: "file" as const, size };
+		});
+}
+
+export function formatFileSearchResults(results: FileSearchResult[]): string {
+	if (results.length === 0) return "未找到匹配项。";
+	return results.map((item) => `- ${item.type === "directory" ? "[dir]" : "[file]"} ${item.path}${item.size === undefined ? "" : ` (${item.size} bytes)`}`).join("\n");
+}
+
+function clampLimit(value: number | undefined): number {
+	return Math.max(1, Math.min(Math.trunc(value ?? DEFAULT_MAX_RESULTS), 500));
+}
+
+function displayPath(cwd: string, fullPath: string): string {
+	const rel = relative(cwd, fullPath);
+	if (rel && !rel.startsWith("..") && !/^[a-zA-Z]:/.test(rel)) return rel.replace(/\//g, "\\");
+	return fullPath;
+}
+
+function wildcardMatcher(pattern: string): (name: string) => boolean {
+	const normalized = pattern.trim();
+	if (!/[*?]/.test(normalized)) {
+		const target = normalized.toLowerCase();
+		return (name) => basename(name).toLowerCase() === target;
+	}
+	const escaped = normalized.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+	const regex = new RegExp(`^${escaped}$`, "i");
+	return (name) => regex.test(basename(name));
+}