kcode-pi 0.1.39 → 0.1.40

package/dist/cli/kcode.js

@@ -73,6 +73,7 @@ export function doctor(cwd, args = []) {
     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);
         if (!settingsResult.ok) {
@@ -109,6 +110,10 @@ export function doctor(cwd, args = []) {
             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() : "不可用"}`);
@@ -305,3 +310,22 @@ function helpText() {
         "  kcode start     初始化项目配置后启动 KCode 工作环境",
     ].join("\n");
 }
+function formatWindowsBashStatus(settingsResult) {
+    const bash = findWindowsBash(settingsResult);
+    return bash ? `可用（${bash}）` : "不可用；KCode 将使用 PowerShell 覆盖工具和 kd_find_file/kd_list_dir";
+}
+function findWindowsBash(settingsResult) {
+    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) => Boolean(item));
+    return candidates.find((candidate) => existsSync(candidate));
+}
+function pathEntries() {
+    const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+    return (process.env[pathKey] ?? "").split(";").filter(Boolean);
+}

package/dist/harness/prompt-policy.d.ts

@@ -15,5 +15,7 @@ export declare const PHASE_GUIDANCE: Record<KdPhase, string>;
 export declare const PLAN_REQUIRED_CHECK_LINES: string[];
 export declare function formatPromptLines(lines: string[]): string[];
 export declare function fieldLabels(fields: ContractField[]): string[];
+export declare function allFactLabels(): string[];
+export declare function formatFactLabelCatalog(): string;
 export declare function questionForMissingLabel(label: string): string | undefined;
 export declare function canonicalFactLabel(label: string): string | undefined;

package/dist/harness/prompt-policy.js

@@ -145,6 +145,7 @@ export const PROJECT_PERSISTENT_RULES = [
     "企业版 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 代替基础文件搜索。",
     "不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实必须重新提问确认。",
 ];
@@ -169,7 +170,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 = {
     discuss: "梳理需求来源、范围、已知事实；如缺通用实现契约、数据源或第三方接口关键事实，使用 kd_question 登记一个最阻塞问题。",
@@ -195,6 +196,23 @@ export function formatPromptLines(lines) {
 export function fieldLabels(fields) {
     return fields.map((field) => field.label);
 }
+export function allFactLabels() {
+    return fieldLabels([...IMPLEMENTATION_CONTRACT_FIELDS, ...DATA_SOURCE_CONTEXT_FIELDS, ...INTEGRATION_CONTEXT_FIELDS]);
+}
+export function formatFactLabelCatalog() {
+    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) {
     const fields = [...IMPLEMENTATION_CONTRACT_FIELDS, ...DATA_SOURCE_CONTEXT_FIELDS, ...INTEGRATION_CONTEXT_FIELDS];
     return fields.find((field) => field.label === label)?.question;

package/docs/CHANGELOG.md

@@ -6,6 +6,27 @@
 
 - 暂无。
 
+## 0.1.40 - 2026-06-07
+
+### 修复
+
+- Windows 下覆盖 Pi 内置 `bash` 工具为 PowerShell 执行，避免未安装 Git Bash 时反复搜索 `C:\Program Files\Git\bin\bash.exe`。
+- 新增 `kd_find_file` 和 `kd_list_dir`，用于不依赖 shell 的文件查找和目录探索。
+- `kcode doctor --deep` 增加 Windows bash 状态诊断，并提示 KCode 的 PowerShell 覆盖和文件工具。
+- 持久规则明确 Windows 文件定位优先使用 `kd_find_file`、`kd_list_dir` 或 PowerShell。
+- `kd_question action=labels` 可列出合法 `factLabel`，未知标签错误会返回完整标签目录，避免 LLM 反复猜标签。
+- `kd_question` 拒绝把产品类型和 FormId/字段/插件事件等多个事实塞进同一个 `factLabel`。
+
+### 验证
+
+- `npm run check`
+- `npm run smoke:harness`
+- `npm run smoke:kcode-command`
+- `npm run smoke:package`
+- `npm run smoke:official`
+- `npm run build:cli`
+- `git diff --check`
+
 ## 0.1.39 - 2026-06-07
 
 ### 修复

package/docs/COMMAND_REFERENCE.md

@@ -311,6 +311,7 @@ kd_question action=list
 ```
 
 一次只能登记一个当前最阻塞的问题，最多 3 个简短选项。`action=ask` 只登记 open 问题，不弹出输入框、不在工具调用内继续追问。
+使用 `action=labels` 查看合法 `factLabel`。产品类型/产品画像不是 `factLabel`，应使用 `/kd-product <产品>` 或先登记无 `factLabel` 的产品确认问题。
 
 结构化事实参数：
 

package/docs/TROUBLESHOOTING.md

@@ -133,3 +133,36 @@ ENOENT: no such file or directory, access 'D:\mnt\d\projects\xxx\src\main\java\F
 ```powershell
 kcode context --refresh
 ```
+
+## Windows 下 bash 工具一直搜索 Git Bash
+
+现象：
+
+```text
+Searched Git Bash in:
+  C:\Program Files\Git\bin\bash.exe
+  C:\Program Files (x86)\Git\bin\bash.exe
+```
+
+原因是 Pi 内置 `bash` 工具在 Windows 上要求 Git Bash、Cygwin 或 MSYS2。KCode 在 Windows 下会覆盖该工具为 PowerShell，并提供 `kd_find_file`、`kd_list_dir` 用于文件查找和目录探索。
+
+处理：
+
+```powershell
+kcode repair
+kcode doctor --deep
+kcode start
+```
+
+在 KCode 会话中查找文件时使用：
+
+```text
+kd_find_file name=MesApiClient.cs root=C:\Users\Administrator\Desktop\lf-project
+kd_list_dir path=C:\Users\Administrator\Desktop\lf-project
+```
+
+如果需要 Pi 原生 bash 行为，安装 Git for Windows 后重新运行：
+
+```powershell
+kcode doctor --deep
+```

package/extensions/kingdee-harness.ts

@@ -30,7 +30,8 @@ import { windowsPathHint } from "../src/platform/path.ts";
 import { repairPromptForRun, workflowPromptForRun } from "../src/harness/prompt.ts";
 import { recordVerifyResult, type VerifyResultOutcome } from "../src/harness/repair.ts";
 import { isSubagentChild, subagentRoleFromEnv, subagentToolCallBlockReason } from "../src/harness/delegation.ts";
-import { questionAskBlockReason } from "../src/harness/question-memory.ts";
+import { questionAskBlockReason, questionFactLabelMismatchReason } from "../src/harness/question-memory.ts";
+import { formatFactLabelCatalog } from "../src/harness/prompt-policy.ts";
 
 function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
@@ -175,9 +176,9 @@ const kdQuestionTool = defineTool({
 	name: "kd_question",
 	label: "KD 问题",
 	description:
-		"创建、回答、修订或列出金蝶 Harness 结构化问题。每次必须只记录一个最阻塞的短问题。",
+		"创建、回答、修订、列出金蝶 Harness 结构化问题，或列出合法 factLabel。每次必须只记录一个最阻塞的短问题。",
 	parameters: Type.Object({
-		action: Type.Optional(Type.String({ description: "操作类型：ask、answer、revise 或 list，默认 ask。" })),
+		action: Type.Optional(Type.String({ description: "操作类型：ask、answer、revise、list 或 labels，默认 ask。" })),
 		id: Type.Optional(Type.String({ description: "回答问题时的问题编号，例如 Q-001。" })),
 		question: Type.Optional(Type.String({ description: "提问内容；必须是一个短问题。" })),
 		answer: Type.Optional(Type.String({ description: "用户答案，action=answer 时使用。" })),
@@ -198,6 +199,9 @@ const kdQuestionTool = defineTool({
 		}
 
 		const action = (params.action ?? "ask").toLowerCase();
+		if (action === "labels") {
+			return { content: [{ type: "text", text: formatFactLabelCatalog() }], details: { action: "labels" } };
+		}
 		if (action === "list") {
 			const text = formatQuestions(run);
 			return { content: [{ type: "text", text }], details: { questions: run.questions ?? [] } };
@@ -260,7 +264,7 @@ const kdQuestionTool = defineTool({
 
 		if (action !== "ask") {
 			return {
-				content: [{ type: "text", text: `未知 kd_question action：${params.action}。有效值：ask、answer、revise、list。` }],
+				content: [{ type: "text", text: `未知 kd_question action：${params.action}。有效值：ask、answer、revise、list、labels。` }],
 				details: { error: "unknown-action", action: params.action },
 			};
 		}
@@ -291,6 +295,13 @@ const kdQuestionTool = defineTool({
 				details: { error: "batched-question" },
 			};
 		}
+		const mismatchReason = questionFactLabelMismatchReason({ question: params.question, factLabel: params.factLabel });
+		if (mismatchReason) {
+			return {
+				content: [{ type: "text", text: mismatchReason }],
+				details: { error: "fact-label-question-mismatch", factLabel: params.factLabel },
+			};
+		}
 		const askBlockReason = questionAskBlockReason(run, { factLabel: params.factLabel });
 		if (askBlockReason) {
 			return {

package/extensions/kingdee-tools.ts

@@ -1,6 +1,7 @@
 import { dirname, join, extname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, readFile as fsReadFile } from "node:fs";
+import { spawn } from "node:child_process";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatSearchResults, formatTableSchema } from "../src/knowledge/format.ts";
@@ -25,6 +26,7 @@ import { resolveWorkspacePath } from "../src/platform/path.ts";
 import { advanceRunIfReady, readActiveRun } from "../src/harness/state.ts";
 import { writeEvidenceFile } from "../src/harness/evidence.ts";
 import { SDK_SIGNATURE_EVIDENCE } from "../src/harness/sdk-policy.ts";
+import { findFiles, formatFileSearchResults, listDirectory } from "../src/tools/file-search.ts";
 
 const extensionDir = dirname(fileURLToPath(import.meta.url));
 const knowledgePath = join(extensionDir, "..", "knowledge");
@@ -479,6 +481,58 @@ const kdDocReadTool = defineTool({
 	},
 });
 
+const kdFindFileTool = defineTool({
+	name: "kd_find_file",
+	label: "KD 文件查找",
+	description: "在 Windows/PowerShell 环境下按文件名递归查找文件，不依赖 Pi 内置 bash。查找源码文件时优先使用此工具。",
+	parameters: Type.Object({
+		name: Type.String({ description: "文件名或通配符，例如 MesApiClient.cs 或 *.cs。" }),
+		root: Type.Optional(Type.String({ description: "搜索根目录；支持项目相对路径或 Windows 绝对路径。默认当前项目根。" })),
+		maxResults: Type.Optional(Type.Number({ description: "最大结果数，默认 50，最多 500。" })),
+	}),
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		try {
+			const results = findFiles(ctx.cwd, { root: params.root, name: params.name, maxResults: params.maxResults });
+			return { content: [{ type: "text", text: formatFileSearchResults(results) }], details: { count: results.length, root: params.root ?? ".", name: params.name } };
+		} catch (error) {
+			return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], details: { error: "find-file-failed" } };
+		}
+	},
+});
+
+const kdListDirTool = defineTool({
+	name: "kd_list_dir",
+	label: "KD 目录列表",
+	description: "列出目录内容，不读取目录为文件，不依赖 Pi 内置 bash。探索项目结构时优先使用此工具。",
+	parameters: Type.Object({
+		path: Type.Optional(Type.String({ description: "目录路径；支持项目相对路径或 Windows 绝对路径。默认当前项目根。" })),
+		maxEntries: Type.Optional(Type.Number({ description: "最大返回条目数，默认 50，最多 500。" })),
+	}),
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		try {
+			const results = listDirectory(ctx.cwd, { path: params.path, maxEntries: params.maxEntries });
+			return { content: [{ type: "text", text: formatFileSearchResults(results) }], details: { count: results.length, path: params.path ?? "." } };
+		} catch (error) {
+			return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], details: { error: "list-dir-failed" } };
+		}
+	},
+});
+
+const windowsPowerShellBashTool = defineTool({
+	name: "bash",
+	label: "PowerShell",
+	description:
+		"Windows KCode shell override. Execute a PowerShell command in the current working directory. Do not use Linux/bash syntax; use PowerShell commands such as Get-ChildItem, Select-String, Get-Content, and dotnet.",
+	promptSnippet: "Execute Windows PowerShell commands. Use PowerShell syntax, not bash syntax.",
+	parameters: Type.Object({
+		command: Type.String({ description: "PowerShell command to execute. Use PowerShell syntax, not bash syntax." }),
+		timeout: Type.Optional(Type.Number({ description: "Timeout in seconds." })),
+	}),
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		return runPowerShell(params.command, ctx.cwd, params.timeout, signal);
+	},
+});
+
 async function extractPdf(filePath: string, maxPages: number): Promise<string> {
 	const { PDFParse } = await import("pdf-parse");
 	const buffer = readFileSync(filePath);
@@ -558,6 +612,7 @@ function extractCsv(filePath: string, maxRows: number): string {
 }
 
 export default function (pi: ExtensionAPI) {
+	if (process.platform === "win32") pi.registerTool(windowsPowerShellBashTool);
 	pi.registerTool(kdSearchTool);
 	pi.registerTool(kdTableTool);
 	pi.registerTool(kdCheckTool);
@@ -569,6 +624,8 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool(kdBuildTool);
 	pi.registerTool(kdDebugTool);
 	pi.registerTool(kdDocReadTool);
+	pi.registerTool(kdFindFileTool);
+	pi.registerTool(kdListDirTool);
 }
 
 function writeSdkSignatureEvidence(cwd: string, content: string): string | undefined {
@@ -593,3 +650,47 @@ function writeSdkSignatureEvidence(cwd: string, content: string): string | undef
 		{ kind: "sdk-signature", command: "kd_sdk_signature", exitCode: 0 },
 	);
 }
+
+function runPowerShell(command: string, cwd: string, timeout: number | undefined, signal: AbortSignal | undefined): Promise<{ content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> }> {
+	return new Promise((resolve) => {
+		const shell = process.env.ComSpec?.replace(/cmd\.exe$/i, "WindowsPowerShell\\v1.0\\powershell.exe") || "powershell.exe";
+		const child = spawn(shell, ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", command], {
+			cwd,
+			windowsHide: true,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		const timeoutHandle =
+			timeout && timeout > 0
+				? setTimeout(() => {
+						timedOut = true;
+						child.kill();
+					}, timeout * 1000)
+				: undefined;
+		const onAbort = () => child.kill();
+		if (signal) signal.addEventListener("abort", onAbort, { once: true });
+		child.stdout?.on("data", (data) => {
+			stdout += data.toString();
+		});
+		child.stderr?.on("data", (data) => {
+			stderr += data.toString();
+		});
+		child.on("error", (error) => {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve({ content: [{ type: "text", text: `PowerShell 启动失败：${error.message}` }], details: { shell: "powershell", error: "spawn-failed" } });
+		});
+		child.on("close", (exitCode) => {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			const output = [stdout.trimEnd(), stderr.trimEnd()].filter(Boolean).join("\n");
+			const suffix = timedOut ? `\n\n[PowerShell timeout after ${timeout}s]` : "";
+			resolve({
+				content: [{ type: "text", text: `${output || "(no output)"}${suffix}` }],
+				details: { shell: "powershell", exitCode, timedOut, command },
+			});
+		});
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "面向金蝶开发的 Pi Coding Agent 启动器、工具包和 Harness 工作流",
   "type": "module",
   "private": false,

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/prompt-policy.ts

@@ -157,6 +157,7 @@ export const PROJECT_PERSISTENT_RULES = [
 	"企业版 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 代替基础文件搜索。",
 	"不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实必须重新提问确认。",
 ];
@@ -183,7 +184,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 +215,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/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 : [];
@@ -98,7 +98,7 @@ export function questionAskBlockReason(run: ActiveRun, input: { factLabel?: stri
 	const rawLabel = input.factLabel?.trim();
 	if (!rawLabel) return undefined;
 	const label = canonicalFactLabel(rawLabel);
-	if (!label) return `未知 factLabel：${rawLabel}。必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签。`;
+	if (!label) return [`未知 factLabel：${rawLabel}。必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签。`, "", "执行 `kd_question action=labels` 查看完整合法标签。", "", formatFactLabelCatalog()].join("\n");
 	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,
@@ -113,6 +113,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 +238,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));
+}