kcode-pi 0.1.23 → 0.1.24

package/docs/CHANGELOG.md

@@ -4,9 +4,25 @@
 
 ## 未发布
 
+- 暂无。
+
+## 0.1.24 - 2026-06-07
+
 ### 新增
 
 - 新增更新日志文档，并在 README 文档导航中提供入口。
+- 新增 `src/harness/prompt.ts`，集中管理运行时 Harness prompt。
+- 新增 `src/harness/messages.ts`，集中管理 Harness 门禁、证据、路径、SDK/TDD 阻断消息。
+
+### 改进
+
+- 收敛运行时 prompt，只保留状态、最近阶段资料、项目上下文摘要、当前阶段任务和核心约束。
+- 精简 `kd-plan`、`kd-execute`、`kd-verify` 命令入口提示，减少和 skills、门禁规则的重复。
+- 移除不存在的 IDE 相关验证表述，保留 Gradle/dotnet 的真实构建验证策略。
+
+### 验证
+
+- `npm run release:check` 通过，包含 TypeScript 检查、CLI 构建、Harness smoke、KCode 命令 smoke、SDK 签名 smoke、package smoke 和 pack dry run。
 
 ## 0.1.23 - 2026-06-07
 

package/docs/EVIDENCE_AND_GATES.md

@@ -89,13 +89,12 @@ Exit: 0
 退出码：0
 ```
 
-不能写：
+以下内容不能作为绿灯证据：
 
 - “需在开发环境验证”
 - “待验证”
 - “未执行”
 - “应该可以”
-- “Kingdee IDE 中编译”
 
 如果命令无法运行，记录真实阻塞原因和残余风险，不能把它当绿灯。
 
@@ -107,7 +106,7 @@ Exit: 0
 evidence/index.json
 ```
 
-KCode 内置工具和统一 evidence 写入路径会自动维护索引。不要手工塞文件绕过门禁。
+KCode 内置工具和统一 evidence 写入路径会自动维护索引。
 
 常见 evidence：
 
@@ -165,4 +164,4 @@ medium
 high
 ```
 
-风险原因应来自 `VERIFY.md` 和 `SHIP.md` 的真实验证结果，不要为了过门禁随手写 `low`。
+风险原因应来自 `VERIFY.md` 和 `SHIP.md` 的真实验证结果。

package/docs/HARNESS_WORKFLOW.md

@@ -58,7 +58,7 @@ ship     汇总变更、验证证据、风险和后续事项
 /kd-advance ship
 ```
 
-门禁不通过时，不要绕过。先按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
+门禁不通过时，先按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
 
 ## 阶段文档
 
@@ -107,7 +107,6 @@ evidence/index.json
 原则：
 
 - 一次只问一个当前最阻塞的问题。
-- 不要把 FormId、字段、触发时机、弹窗内容打包成问题清单。
 - 得到答案后再继续问下一个必要问题。
 
 ## 多个需求
@@ -143,7 +142,6 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 - 未进入 `execute` 阶段不能写产品代码。
 - `execute` 只能写 `PLAN.md` 中批准的真实源码文件。
 - 临时发现要改新文件，先回到 `plan` 更新计划。
-- 不允许凭空写 demo、sample、scaffold。
 - 必须先理解当前业务项目已有目录、模块、包名、基类和本地封装。
 
 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。

package/extensions/kingdee-harness.ts

@@ -22,8 +22,8 @@ import { readArtifact } from "../src/harness/artifacts.ts";
 import { flagshipWriteBlockReason, isSourceLikePath, planWriteBlockReason } from "../src/harness/path-policy.ts";
 import { sdkSignatureProductionWriteBlockReason } from "../src/harness/sdk-policy.ts";
 import { tddProductionWriteBlockReason } from "../src/harness/tdd-policy.ts";
-import { readProjectContext } from "../src/context/project-context.ts";
 import { windowsPathHint } from "../src/platform/path.ts";
+import { workflowPromptForRun } from "../src/harness/prompt.ts";
 
 function requireRun(cwd: string): ReturnType<typeof readActiveRun> {
 	return readActiveRun(cwd);
@@ -109,77 +109,6 @@ function sendWorkflowPrompt(pi: ExtensionAPI, ctx: ExtensionContext, run: NonNul
 	if (ctx.hasUI) ctx.ui.notify("KCode 工作流消息已排队。", "info");
 }
 
-function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>, userText: string): string {
-	const status = formatStatus(cwd, run);
-	const memory = workflowMemoryForRun(cwd, run);
-	const phaseGuidance = phaseGuidanceForRun(run);
-
-	return [
-		"用户输入：",
-		userText,
-		"",
-		"KCode 项目常驻上下文：",
-		readProjectContext(cwd) ?? "未生成。请在终端运行 `kcode context --refresh` 后继续；在生成前不要猜测项目目录。",
-		"",
-		"KCode Harness 状态：",
-		status,
-		"",
-		"KCode 本次工作流本地文档：",
-		memory,
-		"",
-		"需求来源处理：如果用户输入的是本地文件路径，先读取该文件并抽取需求；如果是目录，先列出候选需求文档再读取最相关文件；如果是在线文档链接，先尝试访问或导出可读内容。遇到登录、权限或防下载限制时，只问一个最阻塞问题：请用户提供可访问链接、导出文件路径或关键内容。不要要求用户改写成 KCode 专用格式。",
-		"",
-		`当前 active run 对应本次需求目标：${run.goal ?? run.id}。如果用户补充的是同一目标下的需求文档或细节，先纳入当前阶段文档；如果是无关目标，再要求用户运行 /kd-start <新需求> 创建新 run，或 /kd-switch <run-id> 切换已有 run。`,
-		"需要用户确认时，kd_question 一次只能问一个当前最阻塞的问题；不要把 FormId、触发时机、库存条件、弹窗内容、插件位置等打包成清单。选项最多 3 个；交互模式下会弹出选择/输入对话并自动记录答案。",
-		"",
-		phaseGuidance,
-		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
-		"禁止凭记忆、模型知识或随包知识库直接编写 SDK 方法调用。Java/C# 代码中出现的 SDK 类、方法、构造器、枚举和属性，必须来自 kd_sdk_signature 对当前项目 jar/dll 的成功结果、项目构建输出或官方元数据证据。",
-		"kd_search、kd_cosmic_api 和随包知识只能用于找线索；没有 evidence/sdk-signature.md 或明确构建证据时，不得进入 execute，也不得写生产源码。",
-		"路径规则：在 Windows 工作区内，优先使用项目相对路径；如需绝对路径必须使用 `D:\\...` 这类 Windows 路径，禁止把路径改写成 `/mnt/d/...`、`/d/...` 等 WSL/MSYS 风格路径。",
-		"execute 阶段只能写 PLAN.md 明确列出的源码文件；如果目标文件不在计划内，必须先回到 plan 更新 PLAN.md。",
-		"写生产源码前必须先有红灯证据 evidence/tdd-red.md；Java/C# 还必须有 SDK 签名证据 evidence/sdk-signature.md。红绿证据可以是 kd_sdk_signature 本地 SDK 签名、API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
-		"语法/编译验证必须使用真实项目构建命令：Java/Cosmic/苍穹/星空旗舰版使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `:模块:build`；C#/企业版使用 `dotnet build` 或 `dotnet build <.sln/.csproj>`。",
-		"不要写“Kingdee IDE 中编译”作为验证方式或绿灯证据；命令无法运行时，记录真实阻塞原因和残余风险，不能标记为通过。",
-		"如果门禁提示 evidence 内容无效，不要通过改写结论、补关键词或反复读取文件来过关；必须重新运行 PLAN.md 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。",
-	].join("\n");
-}
-
-function phaseGuidanceForRun(run: NonNullable<ReturnType<typeof readActiveRun>>): string {
-	const guidance: Record<KdPhase, string> = {
-		discuss:
-			"当前处于 discuss。先理解需求来源，判断是一条需求还是一组需求；梳理可确认事实、边界、开放问题和后续需要验证的产品信息；不要编辑产品代码。",
-		spec:
-			"当前处于 spec。先把需求写成可验收条目；如果是一组需求，明确每条需求的验收标准、依赖、风险和批次关系；不要编辑产品代码。",
-		plan:
-			"当前处于 plan。先检查当前项目结构，写明真实目标路径、允许修改文件、查证项、验证命令和回滚说明；如果是一组需求，按批次组织计划；必须明确声明是否涉及产品实现、构建、元数据或 SDK 查证；不要编辑产品代码。",
-		execute:
-			"当前处于 execute。只能实现 PLAN.md 中批准的内容和文件。先读取 PLAN.md 和实际项目文件，遵循既有结构写真实可用代码；不要写 demo/sample/scaffold。",
-		verify:
-			"当前处于 verify。先使用 kd-verify 收集验证证据，不要继续扩大代码改动。",
-		ship:
-			"当前处于 ship。整理发布摘要、验证证据、风险和后续事项，不要继续扩大代码改动。",
-	};
-	return guidance[run.phase];
-}
-
-function workflowMemoryForRun(cwd: string, run: NonNullable<ReturnType<typeof readActiveRun>>): string {
-	const phases = PHASE_ORDER.slice(0, PHASE_ORDER.indexOf(run.phase) + 1);
-	return phases
-		.map((phase) => {
-			const content = readArtifact(cwd, run, phase);
-			if (!content) return undefined;
-			return [`## ${phase}`, trimForPrompt(content, 6000)].join("\n");
-		})
-		.filter(Boolean)
-		.join("\n\n") || "暂无阶段文档。";
-}
-
-function trimForPrompt(content: string, maxLength: number): string {
-	if (content.length <= maxLength) return content;
-	return `${content.slice(0, maxLength)}\n\n[...文档过长，已截断；如需完整内容必须读取本地文件...]`;
-}
-
 function codeWriteBlockReason(cwd: string, path: string | undefined): string | undefined {
 	if (!path || !isSourceLikePath(path)) return undefined;
 
@@ -218,11 +147,11 @@ const kdQuestionTool = defineTool({
 	name: "kd_question",
 	label: "KD 问题",
 	description:
-		"创建、回答或列出金蝶 Harness 结构化问题。每次只能问一个最阻塞的短问题，不要批量列清单。",
+		"创建、回答或列出金蝶 Harness 结构化问题。每次只记录一个最阻塞的短问题。",
 	parameters: Type.Object({
 		action: Type.Optional(Type.String({ description: "操作类型：ask、answer 或 list，默认 ask。" })),
 		id: Type.Optional(Type.String({ description: "回答问题时的问题编号，例如 Q-001。" })),
-		question: Type.Optional(Type.String({ description: "提问内容。只能是一个短问题，不要写编号清单或多个问题。" })),
+		question: Type.Optional(Type.String({ description: "提问内容。使用一个短问题。" })),
 		answer: Type.Optional(Type.String({ description: "用户答案，action=answer 时使用。" })),
 		reason: Type.Optional(Type.String({ description: "说明为什么这个问题会阻塞当前阶段。" })),
 		choices: Type.Optional(Type.Array(Type.String(), { description: "可选项，最多 3 个简短选项。" })),
@@ -367,7 +296,7 @@ export default function (pi: ExtensionAPI) {
 		const path = typeof input.path === "string" ? input.path : undefined;
 		const hint = path ? windowsPathHint(path) : undefined;
 		if (hint && ["read", "write", "edit"].includes(event.toolName)) {
-			const reason = `当前是 Windows 工作区，不能使用 WSL/MSYS 路径 ${path}。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}；不要再尝试 /mnt/d 或 /d 路径。`;
+			const reason = `当前是 Windows 工作区，路径 ${path} 不是本项目使用的路径形式。下一步：改用项目相对路径；如果必须使用绝对路径，使用 Windows 路径 ${hint}。`;
 			if (ctx.hasUI) ctx.ui.notify(reason, "warning");
 			return { block: true, reason };
 		}

package/package.json

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

package/prompts/kd-execute.md

@@ -4,9 +4,9 @@ description: 在 Harness 门禁约束下执行当前金蝶实施计划。
 
 使用 `kd-execute` skill。
 
-编辑代码前，先使用 `kd_plan_status` 检查当前 run。如果缺少 `PLAN.md`、`evidence/sdk-signature.md` 或门禁被阻塞，必须停止并说明缺少的文档或证据。通过后只实现 `PLAN.md` 批准的内容，并更新 `EXECUTION.md`。禁止凭记忆、模型知识或随包知识库猜 SDK 方法签名。
+先检查当前 run 和门禁。通过后只实现 `PLAN.md` 批准的内容，更新 `EXECUTION.md`，并按计划记录红绿 evidence。
 
-实现后要按计划运行真实构建检查语法问题：Java 使用当前项目 Gradle 命令，例如 `.\gradlew.bat build` 或 `.\gradlew.bat :模块:build`；C# 使用 `dotnet build` 或 `dotnet build <.sln/.csproj>`。不能写“Kingdee IDE 中编译”作为验证结果；命令未运行就不能记录为绿灯证据。
+实现后运行计划中的验证命令；命令无法运行时记录阻塞原因和残余风险。
 
 用户补充说明：
 

package/prompts/kd-plan.md

@@ -4,13 +4,9 @@ description: 为当前金蝶 Harness run 编写实施计划。
 
 使用 `kd-plan` skill。
 
-读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。必须包含已检查的项目结构、需要查看的文件、预计修改的真实路径、是否涉及产品实现/构建/元数据/SDK 查证、必须查证的金蝶 API/元数据、SDK 签名证据、验证命令和回滚说明。Java/C# SDK 方法签名必须来自 `kd_sdk_signature` 当前项目 jar/dll、项目构建输出或官方元数据，不能凭记忆猜。
+读取 `CONTEXT.md` 和 `SPEC.md`，编写或更新 `PLAN.md`。重点写清：项目结构、目标路径、允许修改文件、SDK/元数据查证、验证命令和回滚说明。
 
-验证命令必须贴近真实项目：
-
-- 苍穹 / 星瀚 / 星空旗舰版 Java：优先使用当前项目 Gradle 构建做语法和编译检查，例如 `./gradlew build`、`./gradlew :模块:build` 或 Windows 下的 `.\gradlew.bat build`。
-- C# / 企业版：使用 `dotnet build` 或 `dotnet build <.sln/.csproj>` 做语法和编译检查。
-- 不要写“Kingdee IDE 中编译”。如果当前机器缺少依赖导致命令无法运行，要记录真实阻塞原因，不能把未执行的编译当作绿灯证据。
+验证命令按产品选择：Cosmic Java 用当前项目 Gradle；企业版 C# 用 `dotnet build`。命令无法运行时记录阻塞原因和应运行的具体命令。
 
 用户补充说明：
 

package/prompts/kd-verify.md

@@ -4,13 +4,7 @@ description: 验证当前金蝶实现并收集证据。
 
 使用 `kd-verify` skill。
 
-执行计划中的验证命令，收集证据，运行可用检查，并更新 `VERIFY.md`。如果某项验证无法运行，记录具体阻塞原因和残余风险。
-
-验证优先使用真实构建命令检查语法和编译：
-
-- 苍穹 / 星瀚 / 星空旗舰版 Java：运行当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`.\gradlew.bat :模块:build` 或同等 Gradle task。
-- C# / 企业版：运行 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。
-- 绿灯证据必须包含实际命令、`Exit: 0` 和输出摘要。不能用“Kingdee IDE 中编译”“需在开发环境验证”替代真实证据。
+执行 `PLAN.md` 中的验证命令，收集 evidence，并更新 `VERIFY.md`。成功证据记录命令、`Exit: 0` 和输出摘要；命令无法运行时记录阻塞原因和残余风险。
 
 用户补充说明：
 

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

@@ -79,7 +79,7 @@ POJO 或简单枚举场景可以简要说明后直接实现。
 写完测试后：
 
 - 使用 `kd_build` 或计划中的命令运行最窄可行 Gradle test 任务。
-- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task；不要写“在 IDE 中运行”作为验证结论。
+- 如果本机缺少业务 jar 或本地配置导致 Gradle 不能运行，明确说明真实阻塞原因，并给出应该运行的 Gradle task。
 - 存在 harness run 时，把测试文件和验证结果写入 `.pi/kd/runs/<run-id>/EXECUTION.md`。
 
 ## 输出要求

package/skills/kd-execute/SKILL.md

@@ -24,5 +24,5 @@ Rules:
 - Before entering verify, rerun the same check and record passing output in `evidence/tdd-green.md`.
 - After implementation, run the planned real build command for syntax/compile validation when available: Java uses the project Gradle command such as `.\gradlew.bat build` or `.\gradlew.bat :module:build`; C# uses `dotnet build` or `dotnet build <.sln/.csproj>`.
 - 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.
-- Do not record "compile in Kingdee IDE" or "needs local development environment verification" as green evidence. If the command cannot run, record the blocker instead of marking verification passed.
+- If the command cannot run, record the blocker instead of marking verification passed.
 - If implementation needs a plan change, update `PLAN.md` first.

package/skills/kd-plan/SKILL.md

@@ -28,7 +28,7 @@ Gate:
 - Execution must not start without `PLAN.md`.
 - A plan for 星空旗舰版 is incomplete unless it records the existing project layout and exact target path to edit. If `code/` exists, follow its actual structure; if it does not, record the discovered source root or existing target file.
 - A plan without validation commands is incomplete.
-- A Java/C# plan that uses vague wording such as "compile in Kingdee IDE" instead of a real Gradle or dotnet command is incomplete.
+- A Java/C# plan without a concrete Gradle or dotnet validation command is incomplete.
 - A plan without structured `STEP-001` execution steps is incomplete.
 - A plan without TDD red/green checks is incomplete.
 - A plan that relies on unverified Kingdee API names is incomplete; bundled knowledge alone is not enough when local SDK jars/dlls or compile evidence are available.

package/skills/kd-verify/SKILL.md

@@ -20,5 +20,5 @@ Rules:
 
 - Passing unit tests is not enough if acceptance criteria require workflow behavior.
 - If validation cannot run, state the exact blocker.
-- Do not use "Kingdee IDE" as a verification target. Evidence must show the real command, `Exit: 0`, and useful output summary.
+- Passing evidence must show the real command, `Exit: 0`, and useful output summary.
 - Do not ship while verification evidence is missing.

package/src/harness/artifacts.ts

@@ -115,10 +115,10 @@ export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?:
 				"- Java 语法/编译检查：优先使用当前项目 Gradle 命令，例如 `./gradlew build`、`.\\gradlew.bat build` 或 `./gradlew :模块:build`。",
 				"- C# 语法/编译检查：使用 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。",
 				"- 允许的检查：本地 SDK 签名查证、官方 API/基类/方法查证、元数据查证、kd_check、Gradle/dotnet 构建输出、项目已有测试框架、外部接口最小验证。",
-				"- 不要为了满足门禁引入第三方测试 jar 或框架。",
-				"- 不要写“Kingdee IDE 中编译”作为验证方式；命令无法运行时记录真实阻塞原因，不能作为绿灯证据。",
+				"- 测试框架：优先使用项目已有测试基础设施。",
+				"- 命令无法运行时记录真实阻塞原因和残余风险，不能作为绿灯证据。",
 				"- 如果无法自动化测试，记录一个产品相关、实现前应失败且实现后应通过的检查。",
-				"- 禁止凭记忆或随包知识库猜 SDK 方法签名；签名事实必须来自当前项目 jar/dll、构建输出或官方元数据。",
+				"- SDK 方法签名事实必须来自当前项目 jar/dll、构建输出或官方元数据。",
 				"",
 				"## 验证命令",
 				"",

package/src/harness/gates.ts

@@ -10,6 +10,15 @@ import { tddPlanBlockReason, tddVerifyBlockReason } from "./tdd-policy.ts";
 import { SDK_SIGNATURE_EVIDENCE, hasValidSdkSignatureEvidence, requiresSdkSignatureEvidence } from "./sdk-policy.ts";
 import { runRoot } from "./paths.ts";
 import { EVIDENCE_INDEX, hasEvidenceEntry } from "./evidence.ts";
+import {
+	missingArtifactsReason,
+	missingEvidenceReason,
+	missingForTargetReason,
+	missingMarkerReason,
+	openQuestionsReason,
+	unknownProductReason,
+	unknownRiskReason,
+} from "./messages.ts";
 
 const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
 	plan: ["## 验证命令"],
@@ -104,13 +113,6 @@ function gateResult(reasonParts: string[]): GateResult {
 	};
 }
 
-function unknownProductReason(declaration: boolean | undefined): string {
-	if (declaration === undefined) {
-		return "不能进入 execute：产品画像未知，且 PLAN.md 未明确声明是否涉及产品实现、构建、元数据或 SDK 查证。下一步：先由当前需求和项目计划判断该范围；如果涉及产品实现，执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果不涉及，在 PLAN.md 的“产品实现范围”写明“不涉及”及依据。";
-	}
-	return "不能进入 execute：PLAN.md 声明涉及产品实现、构建、元数据或 SDK 查证，但产品画像未知。下一步：根据需求、计划或用户回答确认产品，然后执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。";
-}
-
 function productImplementationDeclaration(cwd: string, run: ActiveRun): boolean | undefined {
 	const plan = readArtifact(cwd, run, "plan") ?? "";
 	const line = plan
@@ -131,10 +133,6 @@ function hasRiskAssessment(cwd: string, run: ActiveRun): boolean {
 	return riskSectionHasContent(readArtifact(cwd, run, "verify") ?? "") || riskSectionHasContent(readArtifact(cwd, run, "ship") ?? "");
 }
 
-function unknownRiskReason(): string {
-	return "不能进入 ship：风险等级或风险原因未知。下一步：根据 VERIFY.md 和 SHIP.md 的残余风险执行 /kd-risk <low|medium|high> <原因>，或在风险章节写入真实风险说明后再刷新门禁。";
-}
-
 function riskSectionHasContent(content: string): boolean {
 	const match = content.match(/##\s*(残余风险|风险)\s*\r?\n([\s\S]*?)(?=\r?\n##\s+|$)/);
 	if (!match) return false;
@@ -147,10 +145,7 @@ function riskSectionHasContent(content: string): boolean {
 function inspectOpenQuestions(run: ActiveRun): string | undefined {
 	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
 	if (open.length === 0) return undefined;
-	return [
-		`存在未回答的阻断问题：${open.map((question) => `${question.id} ${question.question}`).join("；")}`,
-		"下一步：先向用户等待或获取答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录；不要绕过问题推进阶段。",
-	].join("。");
+	return openQuestionsReason(open);
 }
 
 function inspectStepState(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
@@ -176,7 +171,7 @@ function inspectMarkers(cwd: string, run: ActiveRun, phase: KdPhase): string | u
 
 	const missing = markers.filter((marker) => !content.includes(marker));
 	if (missing.length === 0) return undefined;
-	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}。下一步：更新 ${PHASE_ARTIFACTS[phase]}，补齐这些章节并写入真实内容；不要只添加空标题。`;
+	return missingMarkerReason(phase, missing);
 }
 
 function inspectEvidence(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
@@ -220,51 +215,6 @@ function evidenceArtifactSatisfied(cwd: string, run: ActiveRun, artifact: string
 	return existsSync(join(runRoot(cwd, run), artifact)) && hasEvidenceEntry(cwd, run, artifact);
 }
 
-function missingArtifactsReason(artifacts: string[]): string {
-	return [
-		`缺少必需产物：${artifacts.join(", ")}`,
-		`下一步：使用 /kd-artifact <阶段> 创建或更新阶段文档，或按当前阶段要求补写 ${artifacts.join(", ")} 的真实内容后再刷新门禁。`,
-	].join("。");
-}
-
-function missingForTargetReason(target: KdPhase, artifacts: string[]): string {
-	const evidence = artifacts.filter((artifact) => artifact.startsWith("evidence/"));
-	const documents = artifacts.filter((artifact) => !artifact.startsWith("evidence/"));
-	const actions: string[] = [];
-	if (documents.length > 0) {
-		actions.push(`先补齐阶段文档 ${documents.join(", ")}，可用 /kd-artifact 创建模板后填入真实分析、计划或验证内容`);
-	}
-	if (evidence.length > 0) {
-		actions.push(evidenceAction(evidence));
-	}
-	return `不能进入 ${target}：缺少 ${artifacts.join(", ")}。下一步：${actions.join("；")}。`;
-}
-
-function missingEvidenceReason(artifacts: string[]): string {
-	return `缺少必需证据：${artifacts.join(", ")}。下一步：${evidenceAction(artifacts)}。`;
-}
-
-function evidenceAction(artifacts: string[]): string {
-	return artifacts.map(evidenceArtifactAction).join("；");
-}
-
-function evidenceArtifactAction(artifact: string): string {
-	switch (artifact) {
-		case SDK_SIGNATURE_EVIDENCE:
-			return "运行 kd_sdk_signature，从当前项目真实 SDK jar/dll 查证类、方法、构造器或属性签名，成功后自动写入 evidence/sdk-signature.md";
-		case COSMIC_CONFIG_EVIDENCE:
-			return "运行 kd_cosmic_config 生成 evidence/cosmic-config.txt；如果项目没有 ok-cosmic.json，先使用 KCode 默认配置，不要手写假结果";
-		case COSMIC_METADATA_EVIDENCE:
-			return "运行 kd_cosmic_metadata 查询目标表单/单据/字段元数据并生成 evidence/cosmic-metadata.json";
-		case COSMIC_API_EVIDENCE:
-			return "运行 kd_cosmic_api 查询相关 Cosmic API 线索并生成 evidence/cosmic-api.txt，再用 kd_sdk_signature 或构建输出确认签名";
-		case KSQL_LINT_EVIDENCE:
-			return "运行 kd_ksql_lint 校验 KSQL/SQL 交付内容并生成 evidence/ksql-lint.txt";
-		default:
-			return `运行 PLAN.md 中声明的验证命令，记录命令、Exit、STDOUT/STDERR 或工具输出到 ${artifact}`;
-	}
-}
-
 function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {
 	const plan = readArtifact(cwd, run, "plan") ?? "";
 	return /kd_cosmic_metadata|cosmic-metadata|cosmic-metadata\.json|metadata evidence|字段元数据证据|元数据证据/i.test(plan);

package/src/harness/messages.ts

@@ -0,0 +1,113 @@
+import type { KdPhase } from "./types.ts";
+import { PHASE_ARTIFACTS } from "./types.ts";
+
+export function unknownProductReason(declaration: boolean | undefined): string {
+	if (declaration === undefined) {
+		return "不能进入 execute：产品画像未知，且 PLAN.md 未明确声明是否涉及产品实现、构建、元数据或 SDK 查证。下一步：先由当前需求和项目计划判断该范围；如果涉及产品实现，执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果不涉及，在 PLAN.md 的“产品实现范围”写明“不涉及”及依据。";
+	}
+	return "不能进入 execute：PLAN.md 声明涉及产品实现、构建、元数据或 SDK 查证，但产品画像未知。下一步：根据需求、计划或用户回答确认产品，然后执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。";
+}
+
+export function unknownRiskReason(): string {
+	return "不能进入 ship：风险等级或风险原因未知。下一步：根据 VERIFY.md 和 SHIP.md 的残余风险执行 /kd-risk <low|medium|high> <原因>，或在风险章节写入真实风险说明后再刷新门禁。";
+}
+
+export function openQuestionsReason(questions: Array<{ id: string; question: string }>): string {
+	return [
+		`存在未回答的阻断问题：${questions.map((question) => `${question.id} ${question.question}`).join("；")}`,
+		"下一步：先获取用户答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录。",
+	].join("。");
+}
+
+export function missingMarkerReason(phase: KdPhase, missing: string[]): string {
+	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}。下一步：更新 ${PHASE_ARTIFACTS[phase]}，补齐这些章节并写入真实内容。`;
+}
+
+export function missingArtifactsReason(artifacts: string[]): string {
+	return [
+		`缺少必需产物：${artifacts.join(", ")}`,
+		`下一步：使用 /kd-artifact <阶段> 创建或更新阶段文档，或按当前阶段要求补写 ${artifacts.join(", ")} 的真实内容后再刷新门禁。`,
+	].join("。");
+}
+
+export function missingForTargetReason(target: KdPhase, artifacts: string[]): string {
+	const evidence = artifacts.filter((artifact) => artifact.startsWith("evidence/"));
+	const documents = artifacts.filter((artifact) => !artifact.startsWith("evidence/"));
+	const actions: string[] = [];
+	if (documents.length > 0) {
+		actions.push(`先补齐阶段文档 ${documents.join(", ")}，可用 /kd-artifact 创建模板后填入真实分析、计划或验证内容`);
+	}
+	if (evidence.length > 0) {
+		actions.push(evidenceAction(evidence));
+	}
+	return `不能进入 ${target}：缺少 ${artifacts.join(", ")}。下一步：${actions.join("；")}。`;
+}
+
+export function missingEvidenceReason(artifacts: string[]): string {
+	return `缺少必需证据：${artifacts.join(", ")}。下一步：${evidenceAction(artifacts)}。`;
+}
+
+export function evidenceAction(artifacts: string[]): string {
+	return artifacts.map(evidenceArtifactAction).join("；");
+}
+
+export function evidenceArtifactAction(artifact: string): string {
+	switch (artifact) {
+		case "evidence/sdk-signature.md":
+			return "运行 kd_sdk_signature，从当前项目真实 SDK jar/dll 查证类、方法、构造器或属性签名，成功后自动写入 evidence/sdk-signature.md";
+		case "evidence/cosmic-config.txt":
+			return "运行 kd_cosmic_config 生成 evidence/cosmic-config.txt；如果项目没有 ok-cosmic.json，先使用 KCode 默认配置";
+		case "evidence/cosmic-metadata.json":
+			return "运行 kd_cosmic_metadata 查询目标表单/单据/字段元数据并生成 evidence/cosmic-metadata.json";
+		case "evidence/cosmic-api.txt":
+			return "运行 kd_cosmic_api 查询相关 Cosmic API 线索并生成 evidence/cosmic-api.txt，再用 kd_sdk_signature 或构建输出确认签名";
+		case "evidence/ksql-lint.txt":
+			return "运行 kd_ksql_lint 校验 KSQL/SQL 交付内容并生成 evidence/ksql-lint.txt";
+		default:
+			return `运行 PLAN.md 中声明的验证命令，记录命令、Exit、STDOUT/STDERR 或工具输出到 ${artifact}`;
+	}
+}
+
+export function flagshipWriteBlockedReason(path: string): string {
+	return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：先读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
+}
+
+export function planWriteBlockedReason(path: string): string {
+	return `PLAN.md 未批准写入 ${path}。下一步：停止写入该文件，回到 plan 阶段检查项目结构和影响范围，把该文件加入 PLAN.md 的 ## 允许修改的文件 和执行步骤；重新通过门禁后再写。`;
+}
+
+export function flagshipPlanNeedsCodePathReason(): string {
+	return "不能进入 execute：星空旗舰版 PLAN.md 需要先记录当前项目 code/ 下的实际目标路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
+}
+
+export function flagshipPlanNeedsSourcePathReason(): string {
+	return "不能进入 execute：PLAN.md 需要先记录已检查当前项目结构，并写明实际源码根或目标文件路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
+}
+
+export function tddPlanMissingReason(): string {
+	return "PLAN.md 缺少 ## TDD / 红绿检查。下一步：回到 plan 补充该章节，明确红灯证据、绿灯证据、验证命令或无法自动化时的产品验证替代方案；至少写明 evidence/tdd-red.md、evidence/tdd-green.md 和要运行的真实检查。";
+}
+
+export function tddProductionMissingRedReason(path: string, evidenceName: string): string {
+	return `不能写生产源码 ${path}：缺少红灯证据 ${evidenceName}。下一步：先运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
+}
+
+export function tddVerifyBlockedReason(reasons: string[]): string {
+	return [
+		`不能进入 verify：${reasons.join("；")}。`,
+		"修复方式：重新运行 PLAN.md 中声明的同一验证命令或等价的产品验证命令，",
+		"并把命令、Exit、STDOUT/STDERR 或明确的工具输出写入对应 evidence 文件。",
+	].join("");
+}
+
+export function redEvidenceInvalidReason(evidenceName: string): string {
+	return `${evidenceName} 内容无效：需要包含真实失败输出或非 0 退出码`;
+}
+
+export function greenEvidenceInvalidReason(evidenceName: string): string {
+	return `${evidenceName} 内容无效：绿灯证据需要同时包含成功结论和 Exit: 0/退出码：0`;
+}
+
+export function sdkSignatureWriteBlockedReason(path: string, evidenceName: string): string {
+	return `不能写生产源码 ${path}：缺少本地 SDK 签名证据 ${evidenceName}。下一步：运行 kd_sdk_signature，从当前项目真实 jar/dll 查证即将使用的 SDK 类、方法、构造器或属性签名；成功生成 evidence/sdk-signature.md 后再写代码。禁止凭记忆或随包知识库猜 SDK API。`;
+}

package/src/harness/path-policy.ts

@@ -1,6 +1,12 @@
 import type { ActiveRun } from "./types.ts";
 import { existsSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
+import {
+	flagshipPlanNeedsCodePathReason,
+	flagshipPlanNeedsSourcePathReason,
+	flagshipWriteBlockedReason,
+	planWriteBlockedReason,
+} from "./messages.ts";
 
 const SOURCE_EXTENSIONS = new Set([
 	".java",
@@ -23,7 +29,7 @@ export function flagshipWriteBlockReason(run: ActiveRun | undefined, path: strin
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (cwd && !hasWorkspaceCodeDir(cwd)) return undefined;
 	if (!normalized.startsWith("code/")) {
-		return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：先读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
+		return flagshipWriteBlockedReason(path);
 	}
 
 	return undefined;
@@ -37,7 +43,7 @@ export function planWriteBlockReason(cwd: string, run: ActiveRun | undefined, pa
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (planMentionsPath(plan, normalized)) return undefined;
 
-	return `PLAN.md 未批准写入 ${normalized}。下一步：停止写入该文件，回到 plan 阶段检查项目结构和影响范围，把该文件加入 PLAN.md 的 ## 允许修改的文件 和执行步骤；重新通过门禁后再写。`;
+	return planWriteBlockedReason(normalized);
 }
 
 export function flagshipPlanBlockReason(cwd: string, run: ActiveRun | undefined, plan: string): string | undefined {
@@ -45,11 +51,11 @@ export function flagshipPlanBlockReason(cwd: string, run: ActiveRun | undefined,
 
 	if (hasWorkspaceCodeDir(cwd)) {
 		if (/(?:^|[\s`"'(])code[\\/][^\s`"')]+/i.test(plan)) return undefined;
-		return "不能进入 execute：星空旗舰版 PLAN.md 必须先记录当前项目 code/ 下的实际目标路径；不要按固定模块规则猜路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
+		return flagshipPlanNeedsCodePathReason();
 	}
 
 	if (planMentionsDiscoveredSourcePath(plan)) return undefined;
-	return "不能进入 execute：PLAN.md 必须先记录已检查当前项目结构，并写明实际源码根或目标文件路径；当前项目没有 code/ 时更不能猜路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
+	return flagshipPlanNeedsSourcePathReason();
 }
 
 function hasWorkspaceCodeDir(cwd: string): boolean {

package/src/harness/prompt.ts

@@ -0,0 +1,68 @@
+import { readProjectContext } from "../context/project-context.ts";
+import { readArtifact } from "./artifacts.ts";
+import { formatStatus } from "./format.ts";
+import type { ActiveRun, KdPhase } from "./types.ts";
+import { PHASE_ORDER } from "./types.ts";
+
+export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: string): string {
+	const status = formatStatus(cwd, run);
+	const memory = workflowMemoryForRun(cwd, run);
+	const phaseGuidance = phaseGuidanceForRun(run.phase);
+	const projectContext = readProjectContext(cwd);
+
+	return [
+		"用户输入：",
+		userText,
+		"",
+		"KCode Harness 状态：",
+		status,
+		"",
+		"KCode 阶段资料：",
+		memory,
+		"",
+		"项目上下文：",
+		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。需要项目结构时先运行或提示用户运行 `kcode context --refresh`。",
+		"",
+		"当前阶段任务：",
+		phaseGuidance,
+		"",
+		"核心约束：",
+		"- 产品代码只在 execute 阶段写入，并限于 PLAN.md 批准的文件。",
+		"- Java/C# SDK 签名以当前项目 jar/dll、构建输出或官方元数据为准。",
+		"- Java/Cosmic 用当前项目 Gradle；C#/企业版用 dotnet build。",
+		"- evidence 记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
+		"- Windows 下优先使用项目相对路径；绝对路径使用 D:\\... 形式。",
+	].join("\n");
+}
+
+function phaseGuidanceForRun(phase: KdPhase): string {
+	const guidance: Record<KdPhase, string> = {
+		discuss: "梳理需求来源、范围、已知事实和一个最阻塞的待确认问题。",
+		spec: "把需求转成验收标准、数据对象、异常行为、依赖和风险。",
+		plan: "检查项目结构，写明目标路径、允许修改文件、查证项、验证命令和回滚说明。",
+		execute: "按 PLAN.md 实现，记录步骤结果、变更文件和 evidence。",
+		verify: "运行计划中的验证命令，更新 VERIFY.md、证据和残余风险。",
+		ship: "整理 SHIP.md，包括摘要、验证证据、风险和后续事项。",
+	};
+	return guidance[phase];
+}
+
+function workflowMemoryForRun(cwd: string, run: ActiveRun): string {
+	const currentIndex = PHASE_ORDER.indexOf(run.phase);
+	const phases = PHASE_ORDER.slice(Math.max(0, currentIndex - 1), currentIndex + 1);
+	return (
+		phases
+			.map((phase) => {
+				const content = readArtifact(cwd, run, phase);
+				if (!content) return undefined;
+				return [`## ${phase}`, trimForPrompt(content, 1500)].join("\n");
+			})
+			.filter(Boolean)
+			.join("\n\n") || `阶段文档路径：.pi/kd/runs/${run.id}/`
+	);
+}
+
+function trimForPrompt(content: string, maxLength: number): string {
+	if (content.length <= maxLength) return content;
+	return `${content.slice(0, maxLength)}\n\n[...已截断；需要完整内容时读取本地文件...]`;
+}

package/src/harness/sdk-policy.ts

@@ -4,6 +4,7 @@ import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
 import { isSourceLikePath } from "./path-policy.ts";
 import { hasEvidenceEntry } from "./evidence.ts";
+import { sdkSignatureWriteBlockedReason } from "./messages.ts";
 
 export const SDK_SIGNATURE_EVIDENCE = "evidence/sdk-signature.md";
 
@@ -31,7 +32,7 @@ export function sdkSignatureProductionWriteBlockReason(cwd: string, run: ActiveR
 	if (normalized.startsWith(".pi/")) return undefined;
 	if (hasValidSdkSignatureEvidence(cwd, run)) return undefined;
 
-	return `不能写生产源码 ${normalized}：缺少本地 SDK 签名证据 ${SDK_SIGNATURE_EVIDENCE}。下一步：运行 kd_sdk_signature，从当前项目真实 jar/dll 查证即将使用的 SDK 类、方法、构造器或属性签名；成功生成 evidence/sdk-signature.md 后再写代码。禁止凭记忆或随包知识库猜 SDK API。`;
+	return sdkSignatureWriteBlockedReason(normalized, SDK_SIGNATURE_EVIDENCE);
 }
 
 function normalizeRelativePath(path: string): string {

package/src/harness/tdd-policy.ts

@@ -4,13 +4,20 @@ import type { ActiveRun } from "./types.ts";
 import { runRoot } from "./paths.ts";
 import { isSourceLikePath } from "./path-policy.ts";
 import { hasEvidenceEntry } from "./evidence.ts";
+import {
+	greenEvidenceInvalidReason,
+	redEvidenceInvalidReason,
+	tddPlanMissingReason,
+	tddProductionMissingRedReason,
+	tddVerifyBlockedReason,
+} from "./messages.ts";
 
 export const TDD_RED_EVIDENCE = "evidence/tdd-red.md";
 export const TDD_GREEN_EVIDENCE = "evidence/tdd-green.md";
 
 export function tddPlanBlockReason(plan: string): string | undefined {
 	if (/##\s*TDD\s*\/\s*红绿检查/i.test(plan)) return undefined;
-	return "PLAN.md 缺少 ## TDD / 红绿检查。下一步：回到 plan 补充该章节，明确红灯证据、绿灯证据、验证命令或无法自动化时的产品验证替代方案；至少写明 evidence/tdd-red.md、evidence/tdd-green.md 和要运行的真实检查。";
+	return tddPlanMissingReason();
 }
 
 export function tddProductionWriteBlockReason(cwd: string, run: ActiveRun | undefined, path: string | undefined): string | undefined {
@@ -22,7 +29,7 @@ export function tddProductionWriteBlockReason(cwd: string, run: ActiveRun | unde
 	if (isTestLikePath(normalized)) return undefined;
 	if (hasValidTddEvidence(cwd, run, "red")) return undefined;
 
-	return `不能写生产源码 ${normalized}：缺少红灯证据 ${TDD_RED_EVIDENCE}。下一步：先运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
+	return tddProductionMissingRedReason(normalized, TDD_RED_EVIDENCE);
 }
 
 export function tddVerifyBlockReason(cwd: string, run: ActiveRun): string | undefined {
@@ -31,11 +38,7 @@ export function tddVerifyBlockReason(cwd: string, run: ActiveRun): string | unde
 		validateTddEvidence(cwd, run, "green"),
 	].filter((result) => !result.valid);
 	if (problems.length === 0) return undefined;
-	return [
-		`不能进入 verify：${problems.map((problem) => problem.reason).join("；")}。`,
-		"修复方式：不要反复修改 evidence 文案；必须重新运行 PLAN.md 中声明的同一验证命令或等价的产品验证命令，",
-		"并把命令、Exit、STDOUT/STDERR 或明确的工具输出写入对应 evidence 文件。",
-	].join("");
+	return tddVerifyBlockedReason(problems.map((problem) => problem.reason ?? "未知 TDD evidence 问题"));
 }
 
 function hasValidTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green"): boolean {
@@ -58,7 +61,7 @@ function validateTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green")
 		const hasFailure = /red|fail|failed|failure|error|失败|未通过|Exit\s*[：:]\s*[1-9]/i.test(content);
 		return hasFailure
 			? { valid: true }
-			: { valid: false, reason: `${evidenceName} 内容无效：必须包含真实失败输出或非 0 退出码，不能只写结论` };
+			: { valid: false, reason: redEvidenceInvalidReason(evidenceName) };
 	}
 
 	const hasGreenExit = /Exit\s*[：:]\s*0|退出码\s*[：:]\s*0/i.test(content);
@@ -67,7 +70,7 @@ function validateTddEvidence(cwd: string, run: ActiveRun, kind: "red" | "green")
 
 	return {
 		valid: false,
-		reason: `${evidenceName} 内容无效：绿灯证据必须同时包含成功结论和 Exit: 0/退出码：0，不能只写“通过”或人工结论`,
+		reason: greenEvidenceInvalidReason(evidenceName),
 	};
 }