kcode-pi 0.1.38 → 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

@@ -144,6 +144,9 @@ export const PROJECT_PERSISTENT_RULES = [
     "用户回答 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 代替基础文件搜索。",
     "不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实必须重新提问确认。",
 ];
 export const PROMPT_STYLE_RULES = [
@@ -167,6 +170,7 @@ export const CORE_WORKFLOW_CONSTRAINTS = [
     "evidence 必须记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
     "外部系统操作、BOS 注册、人工功能测试和生产环境验证不能由 LLM 代办；必须要求用户提供验证结果或可核验证据，并记录证据来源。",
     "Windows 路径规则：项目相对路径为默认；绝对路径使用 D:\\... 形式。",
+    "工具规则：按当前会话实际 shell 和工具执行；Windows 不假设 bash，优先用 kd_find_file/kd_list_dir/PowerShell；禁止猜路径或用 kd_subagent 代替基础搜索失败。",
 ];
 export const PHASE_GUIDANCE = {
     discuss: "梳理需求来源、范围、已知事实；如缺通用实现契约、数据源或第三方接口关键事实，使用 kd_question 登记一个最阻塞问题。",
@@ -192,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,43 @@
 
 - 暂无。
 
+## 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
+
+### 修复
+
+- 持久规则和核心约束新增工具环境规则：Windows 默认使用 PowerShell、`rg`、`Get-ChildItem`、`Get-Content`，禁止假设 bash 可用。
+- 明确文件定位必须基于真实搜索或目录读取结果；工具不可用时记录阻塞原因，禁止猜测路径或反复自述工具失败。
+- 强化 `kd_subagent` 委派边界：子 agent 不能作为 shell/read/grep 失败的替代方案，不能用来绕过基础文件搜索。
+
+### 验证
+
+- `npm run check`
+- `npm run smoke:harness`
+- `npm run smoke:kcode-command`
+- `npm run build:cli`
+- `git diff --check`
+
 ## 0.1.38 - 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/HARNESS_WORKFLOW.md

@@ -151,6 +151,7 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 - API 文档、SDK 文档和知识库只能作为技术用法证据，不能替代 FormId、字段/实体、插件事件、SQL/KSQL 表名、数据库字段名、字段映射、并发/幂等、日志脱敏和验收数据等业务事实。
 - 信息不足时登记一个最阻塞的结构化问题；禁止生成模板代码或占位实现。
 - 内部插件、自动下推、第三方对接、字段改写和数据同步统一按实现契约、数据源上下文和对接上下文补齐事实，不为单个业务场景写死提示词。
+- 工具使用必须匹配当前环境。Windows 项目默认使用 PowerShell、`rg`、`Get-ChildItem`、`Get-Content`；禁止假设 bash 可用，禁止猜测路径。
 
 ## 项目持久规则
 
@@ -162,6 +163,7 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 - `factLabel` 必须使用集中定义的事实标签或别名。
 - PLAN 自由文本不能单独证明 FormId、字段、插件事件或读写方式。
 - 外部系统操作、BOS 注册、人工功能测试和生产验证必须由用户提供可核验证据。
+- 工具不可用时必须说明阻塞原因和需要用户执行的命令；禁止反复自述工具失败或用 `kd_subagent` 代替基础文件搜索。
 - 不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实重新提问确认。
 
 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。
@@ -189,6 +191,7 @@ KCode 支持把局部任务委派给隔离子 agent，用来降低长上下文
 - `doc` 只写明确指定的文档或阶段产物。
 - `code` 只能在 `execute` 阶段运行，并且只能修改 `PLAN.md` 批准文件。
 - `verify` 只读分析验证命令、失败证据和风险；实际命令和结果记录仍由主 agent 执行。
+- 子 agent 不是 shell、read、grep 失败的替代方案；主 agent 必须先使用当前环境可用工具定位文件。
 
 `--dry-run` 会预览发送给子 agent 的上下文包，用来检查上下文是否过长、是否包含不该交给子 agent 的信息。
 

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.38",
+  "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/delegation.ts

@@ -22,6 +22,7 @@ export interface ParsedDelegationArgs extends DelegationRequest {
 const ROLE_GUIDANCE: Record<DelegationRole, string[]> = {
 	research: [
 		"只读调研项目、文档、SDK 线索和现有实现。",
+		"必须基于真实读取或搜索结果定位文件；禁止猜测路径。",
 		"输出压缩结论、证据文件/代码位置、风险和下一步指令。",
 		"禁止修改文件；禁止推进 Harness 状态。",
 	],
@@ -180,6 +181,7 @@ export function delegationGuidanceForWorkflow(): string {
 		"- 任务包含大量调研、独立交叉审查、长上下文复盘或可并行拆分内容时，使用 kd_subagent。",
 		"- 自动委派只做旁路工作；主 agent 仍负责采纳结论、修改文件、记录 evidence 和推进阶段。",
 		"- code 委派只能在 execute 阶段且限于 PLAN.md 批准文件；review/research 默认只读。",
+		"- kd_subagent 不是 shell/read/grep 失败的替代方案；基础文件搜索失败时，主 agent 必须报告阻塞原因或改用当前环境可用工具。",
 	].join("\n");
 }
 
@@ -221,6 +223,7 @@ export function buildDelegationPrompt(cwd: string, run: ActiveRun | undefined, r
 		...roleGuidance.map((item) => `- ${item}`),
 		"- 子 agent 不是主状态机；禁止调用 /kd-advance、/kd-finish 或改变 run 生命周期。",
 		"- 禁止创建子 agent；输出结果交回主 agent 统一决策。",
+		"- 禁止假设 bash、Linux 路径或猜测文件位置；Windows 项目按 PowerShell/Windows 路径语义描述命令。",
 		"",
 		"Harness 状态：",
 		status,

package/src/harness/prompt-policy.ts

@@ -156,6 +156,9 @@ export const PROJECT_PERSISTENT_RULES = [
 	"用户回答 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 代替基础文件搜索。",
 	"不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实必须重新提问确认。",
 ];
 
@@ -181,6 +184,7 @@ export const CORE_WORKFLOW_CONSTRAINTS = [
 	"evidence 必须记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
 	"外部系统操作、BOS 注册、人工功能测试和生产环境验证不能由 LLM 代办；必须要求用户提供验证结果或可核验证据，并记录证据来源。",
 	"Windows 路径规则：项目相对路径为默认；绝对路径使用 D:\\... 形式。",
+	"工具规则：按当前会话实际 shell 和工具执行；Windows 不假设 bash，优先用 kd_find_file/kd_list_dir/PowerShell；禁止猜路径或用 kd_subagent 代替基础搜索失败。",
 ];
 
 export const PHASE_GUIDANCE: Record<KdPhase, string> = {
@@ -211,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));
+}