kcode-pi 0.1.34 → 0.1.38

package/src/harness/messages.ts

@@ -1,11 +1,18 @@
 import type { KdPhase } from "./types.ts";
 import { PHASE_ARTIFACTS } from "./types.ts";
+import {
+	DATA_SOURCE_CONTEXT_FIELDS,
+	IMPLEMENTATION_CONTRACT_FIELDS,
+	INTEGRATION_CONTEXT_FIELDS,
+	fieldLabels,
+	questionForMissingLabel,
+} from "./prompt-policy.ts";
 
 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>；不涉及时在 PLAN.md 的“产品实现范围”写明“不涉及”及依据。";
 	}
-	return "不能进入 execute：PLAN.md 声明涉及产品实现、构建、元数据或 SDK 查证，但产品画像未知。下一步：根据需求、计划或用户回答确认产品，然后执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；如果无法判断，先用 kd_question 只问一个最阻塞的产品确认问题。";
+	return "不能进入 execute：PLAN.md 声明涉及产品实现、构建、元数据或 SDK 查证，但产品画像未知。下一步：根据需求、计划或用户回答确认产品，然后执行 /kd-product <flagship|xinghan|cangqiong|enterprise>；无法判断时使用 kd_question 登记一个最阻塞的产品确认问题。";
 }
 
 export function unknownRiskReason(): string {
@@ -15,7 +22,7 @@ export function unknownRiskReason(): string {
 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=<用户答案> 记录。",
+		"下一步：获取用户答案，然后用 kd_question action=answer id=<问题编号> answer=<用户答案> 记录。",
 	].join("。");
 }
 
@@ -24,6 +31,33 @@ export function repairBlockedReason(attempts: number, maxAttempts: number, evide
 	return `自动修复已停止：验证失败 ${attempts}/${maxAttempts}${evidenceText}。下一步：回到 plan 调整范围，或重新创建/回答修复问题选择“继续修复”。`;
 }
 
+export function dataSourcePlanBlockedReason(missing: string[]): string {
+	return [
+		`不能进入 execute：业务数据源上下文不完整，缺少 ${missing.join("、")}。`,
+		`下一步：停止编码，使用 kd_question 逐项确认 ${fieldLabels(DATA_SOURCE_CONTEXT_FIELDS).join("、")}。`,
+		nextQuestionInstruction(missing),
+		"API 文档只能作为调用线索，不能替代这些业务事实。",
+	].filter(Boolean).join("");
+}
+
+export function integrationPlanBlockedReason(missing: string[]): string {
+	return [
+		`不能进入 execute：第三方对接上下文不完整，缺少 ${missing.join("、")}。`,
+		`下一步：停止编码，使用 kd_question 逐项确认 ${fieldLabels(INTEGRATION_CONTEXT_FIELDS).join("、")}。`,
+		nextQuestionInstruction(missing),
+		"缺少这些信息时禁止生成模板代码。",
+	].filter(Boolean).join("");
+}
+
+export function implementationPlanBlockedReason(missing: string[]): string {
+	return [
+		`不能进入 execute：实现就绪信息不完整，缺少 ${missing.join("、")}。`,
+		`下一步：禁止生成模板代码；使用 kd_question 按最阻塞项逐个确认 ${fieldLabels(IMPLEMENTATION_CONTRACT_FIELDS).join("、")}。`,
+		nextQuestionInstruction(missing),
+		"这些字段是所有插件、服务和集成实现的通用输入，不依赖具体业务场景枚举。",
+	].filter(Boolean).join("");
+}
+
 export function missingMarkerReason(phase: KdPhase, missing: string[]): string {
 	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}。下一步：更新 ${PHASE_ARTIFACTS[phase]}，补齐这些章节并写入真实内容。`;
 }
@@ -40,7 +74,7 @@ export function missingForTargetReason(target: KdPhase, artifacts: string[]): st
 	const documents = artifacts.filter((artifact) => !artifact.startsWith("evidence/"));
 	const actions: string[] = [];
 	if (documents.length > 0) {
-		actions.push(`先补齐阶段文档 ${documents.join(", ")}，可用 /kd-artifact 创建模板后填入真实分析、计划或验证内容`);
+		actions.push(`补齐阶段文档 ${documents.join(", ")}；可使用 /kd-artifact 创建模板后填入真实分析、计划或验证内容`);
 	}
 	if (evidence.length > 0) {
 		actions.push(evidenceAction(evidence));
@@ -61,9 +95,11 @@ export function evidenceArtifactAction(artifact: string): string {
 		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 默认配置";
+			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/data-source.md":
+			return "写入真实数据源证据 evidence/data-source.md，至少包含目标 FormId/单据或表单、字段/实体标识、表或数据来源、验证来源和测试数据；禁止只引用 API 文档";
 		case "evidence/cosmic-api.txt":
 			return "运行 kd_cosmic_api 查询相关 Cosmic API 线索并生成 evidence/cosmic-api.txt，再用 kd_sdk_signature 或构建输出确认签名";
 		case "evidence/ksql-lint.txt":
@@ -74,7 +110,7 @@ export function evidenceArtifactAction(artifact: string): string {
 }
 
 export function flagshipWriteBlockedReason(path: string): string {
-	return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：先读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
+	return `星空旗舰版代码必须跟随当前项目结构写入 code/ 下，不能写到 ${path}。下一步：读取当前项目 code/ 下的真实模块结构，在 PLAN.md 记录目标源码路径，再把写入路径改为 code/... 下的项目相对路径。`;
 }
 
 export function planWriteBlockedReason(path: string): string {
@@ -82,11 +118,11 @@ export function planWriteBlockedReason(path: string): string {
 }
 
 export function flagshipPlanNeedsCodePathReason(): string {
-	return "不能进入 execute：星空旗舰版 PLAN.md 需要先记录当前项目 code/ 下的实际目标路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
+	return "不能进入 execute：星空旗舰版 PLAN.md 必须记录当前项目 code/ 下的实际目标路径。下一步：列出 code/ 下模块，识别当前项目是按云、按应用还是不分模块组织，在 PLAN.md 写明真实目标文件。";
 }
 
 export function flagshipPlanNeedsSourcePathReason(): string {
-	return "不能进入 execute：PLAN.md 需要先记录已检查当前项目结构，并写明实际源码根或目标文件路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
+	return "不能进入 execute：PLAN.md 必须记录已检查当前项目结构，并写明实际源码根或目标文件路径。下一步：读取构建文件和 src/lib/bin 等目录，确认源码根后写入 PLAN.md 的 ## 已检查的项目结构、## 目标源码根 / 路径 和 ## 允许修改的文件。";
 }
 
 export function tddPlanMissingReason(): string {
@@ -94,7 +130,7 @@ export function tddPlanMissingReason(): string {
 }
 
 export function tddProductionMissingRedReason(path: string, evidenceName: string): string {
-	return `不能写生产源码 ${path}：缺少红灯证据 ${evidenceName}。下一步：先运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
+	return `不能写生产源码 ${path}：缺少红灯证据 ${evidenceName}。下一步：运行一个实现前应失败的检查，例如 kd_sdk_signature 方法不存在检查、元数据/API 检查、编译检查、kd_check、项目已有测试或外部接口最小验证；把命令、非 0 Exit 或失败输出写入 evidence/tdd-red.md 后再写生产源码。`;
 }
 
 export function tddVerifyBlockedReason(reasons: string[]): string {
@@ -106,13 +142,31 @@ export function tddVerifyBlockedReason(reasons: string[]): string {
 }
 
 export function redEvidenceInvalidReason(evidenceName: string): string {
-	return `${evidenceName} 内容无效：需要包含真实失败输出或非 0 退出码`;
+	return `${evidenceName} 内容无效：必须包含真实失败输出或非 0 退出码`;
 }
 
 export function greenEvidenceInvalidReason(evidenceName: string): string {
-	return `${evidenceName} 内容无效：绿灯证据需要同时包含成功结论和 Exit: 0/退出码：0`;
+	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。`;
 }
+
+export function dataSourceWriteBlockedReason(path: string, evidenceName: string): string {
+	return `不能写生产源码 ${path}：缺少真实数据源/元数据证据 ${evidenceName}。下一步：确认目标 FormId、单据/表单、字段/实体、表或数据来源和测试数据；API 文档只能证明调用方式，不能证明当前业务数据源存在。`;
+}
+
+export function integrationWriteBlockedReason(path: string, missing: string[]): string {
+	return `不能写生产源码 ${path}：第三方对接上下文不完整，缺少 ${missing.join("、")}。下一步：补齐 ${fieldLabels(INTEGRATION_CONTEXT_FIELDS).join("、")}。`;
+}
+
+export function implementationWriteBlockedReason(path: string, missing: string[]): string {
+	return `不能写生产源码 ${path}：实现就绪信息不完整，缺少 ${missing.join("、")}。下一步：确认 ${fieldLabels(IMPLEMENTATION_CONTRACT_FIELDS).join("、")}；信息不足时继续提问，禁止生成模板代码。`;
+}
+
+function nextQuestionInstruction(missing: string[]): string | undefined {
+	const question = questionForMissingLabel(missing[0]);
+	if (!question) return undefined;
+	return `阻断问题命令：kd_question action=ask factLabel="${missing[0]}" question="${question}" reason="${missing[0]} 缺失会阻塞实现。"。`;
+}

package/src/harness/path-policy.ts

@@ -18,6 +18,7 @@ const SOURCE_EXTENSIONS = new Set([
 	".yaml",
 	".sql",
 	".ksql",
+	".cs",
 	".py",
 ]);
 

package/src/harness/plan-steps.ts

@@ -22,12 +22,12 @@ export function parsePlanSteps(plan: string): PlanStep[] {
 
 export function planStepsBlockReason(plan: string): string | undefined {
 	if (!/##\s*执行步骤/i.test(plan)) {
-		return "PLAN.md 缺少 ## 执行步骤。下一步：回到 plan，补充 `## 执行步骤`，把工作拆成 `- [ ] STEP-001：...` 这种可跟踪步骤；每一步都应能产生代码变更或 evidence。";
+		return "PLAN.md 缺少 ## 执行步骤。下一步：回到 plan，补充 `## 执行步骤`；使用 `- [ ] STEP-001：...` 拆分可跟踪步骤；每一步必须产生代码变更或 evidence。";
 	}
 
 	const steps = parsePlanSteps(plan);
 	if (steps.length === 0) {
-		return "PLAN.md 没有可执行步骤。下一步：在 `## 执行步骤` 下使用 `- [ ] STEP-001：...` 列出步骤；不要用普通段落代替可勾选步骤。";
+		return "PLAN.md 没有可执行步骤。下一步：在 `## 执行步骤` 下使用 `- [ ] STEP-001：...` 列出步骤；禁止用普通段落代替可勾选步骤。";
 	}
 
 	const duplicate = firstDuplicate(steps.map((step) => step.id));
@@ -56,7 +56,7 @@ export function executionStepsBlockReason(cwd: string, run: ActiveRun, plan: str
 	}
 
 	if (missing.length > 0) {
-		return `不能进入 verify：EXECUTION.md 未完成计划步骤 ${missing.join(", ")}。下一步：继续执行这些步骤，完成后在 EXECUTION.md 的 ## 步骤结果 中用 \`- [x] STEP-###：已完成。证据：evidence/step-###.md\` 记录；未真正执行时不要勾选。`;
+		return `不能进入 verify：EXECUTION.md 未完成计划步骤 ${missing.join(", ")}。下一步：执行缺失步骤；完成后在 EXECUTION.md 的 ## 步骤结果 中使用 \`- [x] STEP-###：已完成。证据：evidence/step-###.md\` 记录；未执行完成时禁止勾选。`;
 	}
 	if (missingEvidence.length > 0) {
 		return `不能进入 verify：步骤 ${missingEvidence.join(", ")} 缺少已落地的 evidence 文件。下一步：为每个步骤创建真实 evidence 文件，写入检查命令、结果、改动文件或验证输出，然后在 EXECUTION.md 对应步骤行引用该 evidence 路径。`;

package/src/harness/prompt-policy.ts

@@ -0,0 +1,227 @@
+import type { KdPhase } from "./types.ts";
+
+export interface ContractField {
+	id: string;
+	label: string;
+	aliases: string[];
+	question: string;
+}
+
+export const IMPLEMENTATION_CONTRACT_FIELDS: ContractField[] = [
+	{
+		id: "trigger",
+		label: "触发入口或执行时机",
+		aliases: ["触发入口", "执行时机", "触发时机", "插件类型和事件", "入口事件"],
+		question: "该实现由哪个入口触发，执行时机是什么？",
+	},
+	{
+		id: "source",
+		label: "源对象/输入数据",
+		aliases: ["源对象", "源单", "输入数据", "数据来源", "取数来源"],
+		question: "实现读取的源对象或输入数据是什么？",
+	},
+	{
+		id: "target",
+		label: "目标对象/输出结果",
+		aliases: ["目标对象", "目标单据", "目标表单", "输出结果", "生成结果"],
+		question: "实现写入、生成或影响的目标对象是什么？",
+	},
+	{
+		id: "data-change",
+		label: "数据变化或字段映射",
+		aliases: ["数据变化", "字段映射", "字段对应", "字段改写", "赋值规则"],
+		question: "列出新增、修改、映射或保持不变的字段。",
+	},
+	{
+		id: "rules",
+		label: "业务规则和适用条件",
+		aliases: ["业务规则", "适用条件", "执行条件", "过滤条件", "前置条件"],
+		question: "该实现在哪些条件下执行，业务规则是什么？",
+	},
+	{
+		id: "failure",
+		label: "失败处理、回滚或人工处理方式",
+		aliases: ["失败处理", "异常处理", "错误处理", "回滚", "补偿", "人工处理"],
+		question: "失败、异常或重复执行时如何处理？",
+	},
+	{
+		id: "acceptance",
+		label: "验收样例或测试数据",
+		aliases: ["验收样例", "测试数据", "请求样例", "响应样例", "示例数据"],
+		question: "用于验收的样例数据和预期结果是什么？",
+	},
+];
+
+export const DATA_SOURCE_CONTEXT_FIELDS: ContractField[] = [
+	{
+		id: "target-form",
+		label: "目标 FormId/单据或表单标识",
+		aliases: ["目标 FormId", "FormId", "Form ID", "form id", "表单标识", "单据标识", "目标单据", "目标表单"],
+		question: "目标 FormId、单据或表单标识是什么？",
+	},
+	{
+		id: "plugin-hook",
+		label: "插件类型和触发事件",
+		aliases: ["插件类型", "触发事件", "生命周期", "挂载点", "插件类型和事件"],
+		question: "插件类型和触发事件是什么？",
+	},
+	{
+		id: "field-entity",
+		label: "字段/实体/分录标识",
+		aliases: ["字段标识", "实体标识", "分录标识", "单据体标识", "字段/实体标识"],
+		question: "涉及哪些字段、实体或分录标识？",
+	},
+	{
+		id: "data-access",
+		label: "数据读取写入方式",
+		aliases: ["数据读取写入方式", "读取方式", "写入方式", "数据访问", "取数方式"],
+		question: "数据通过表单模型、服务、SQL/KSQL 还是接口读取和写入？",
+	},
+	{
+		id: "sql-identifiers",
+		label: "SQL/KSQL 表名和数据库字段名",
+		aliases: ["SQL 表名", "KSQL 表名", "表名", "数据库字段名", "字段名"],
+		question: "SQL/KSQL 场景的表名和数据库字段名是什么？",
+	},
+];
+
+export const INTEGRATION_CONTEXT_FIELDS: ContractField[] = [
+	{
+		id: "interface-doc",
+		label: "接口文档来源/版本",
+		aliases: ["接口文档", "API 文档", "文档来源", "协议文档", "OpenAPI", "Swagger"],
+		question: "第三方接口文档来源和版本是什么？",
+	},
+	{
+		id: "direction",
+		label: "对接方向和触发时机",
+		aliases: ["对接方向", "触发时机", "同步方向", "数据流向"],
+		question: "对接方向、调用方和触发时机是什么？",
+	},
+	{
+		id: "endpoint-auth",
+		label: "接口地址、认证和密钥配置方式",
+		aliases: ["接口地址", "认证", "鉴权", "密钥", "Token", "OAuth"],
+		question: "接口地址、认证方式和密钥配置方式是什么？",
+	},
+	{
+		id: "field-mapping",
+		label: "第三方字段到金蝶字段的映射",
+		aliases: ["字段映射", "映射关系", "字段对应", "字段对照"],
+		question: "第三方字段与金蝶字段如何对应？",
+	},
+	{
+		id: "concurrency",
+		label: "并发/幂等策略",
+		aliases: ["并发", "幂等", "去重", "唯一键", "重复提交"],
+		question: "并发、重复提交和幂等如何处理？",
+	},
+	{
+		id: "retry",
+		label: "超时、重试和限流策略",
+		aliases: ["超时", "重试", "限流", "频率", "熔断"],
+		question: "超时、重试和限流策略是什么？",
+	},
+	{
+		id: "error",
+		label: "错误处理和失败补偿",
+		aliases: ["错误处理", "异常处理", "失败处理", "失败补偿", "告警"],
+		question: "接口失败、异常响应和补偿流程如何处理？",
+	},
+	{
+		id: "logging",
+		label: "日志、审计和敏感信息脱敏策略",
+		aliases: ["日志", "审计", "留痕", "脱敏", "敏感信息"],
+		question: "列出日志字段、审计留痕和敏感信息脱敏规则。",
+	},
+	{
+		id: "samples",
+		label: "请求/响应样例和验收数据",
+		aliases: ["请求样例", "响应样例", "报文样例", "验收数据", "payload"],
+		question: "请求样例、响应样例和验收数据是什么？",
+	},
+];
+
+export const PROJECT_PERSISTENT_RULES = [
+	"计划或编辑代码前必须读取本文件；本文件过期时先运行 `kcode context --refresh`。",
+	"信息不足时禁止开始编码。必须先登记一个最阻塞的结构化问题，获得可核验答案后再继续；禁止输出 demo/sample/scaffold、模板代码或占位实现。",
+	"API 文档、SDK 文档和知识库只能证明技术用法，不能替代业务事实。FormId、单据/表单标识、字段/实体/分录标识、插件类型与事件、SQL/KSQL 表名和数据库字段名必须来自用户确认、项目元数据或 evidence。",
+	`产品代码实现前必须具备通用实现契约：${IMPLEMENTATION_CONTRACT_FIELDS.map((field) => field.label).join("、")}。`,
+	`涉及业务数据源时必须具备数据源上下文：${DATA_SOURCE_CONTEXT_FIELDS.map((field) => field.label).join("、")}。`,
+	`涉及第三方对接时必须具备接口与运行上下文：${INTEGRATION_CONTEXT_FIELDS.map((field) => field.label).join("、")}。`,
+	"内部插件、自动下推、字段改写、数据同步等需求不得按场景写死提示词；统一通过实现契约、数据源上下文、第三方对接上下文补齐事实。",
+	"PLAN 自由文本不能单独证明 FormId、字段、插件事件或读写方式；门禁只信任结构化 facts 和 evidence。",
+	"`run.facts` 是唯一结构化事实源；已回答 questions 仅为审计记录，禁止在读取状态时从历史 question 反推事实。",
+	"`factLabel` 必须使用集中定义的事实标签或别名；未知标签、占位答案、口头确认语、待确认/TODO/TBD/按实际环境等不能解除门禁。",
+	"用户回答 open question 后，先用 `kd_question action=answer` 写入答案；用户更正事实时用 `kd_question action=revise`，禁止重复询问已确认事实。",
+	"企业版 Python 插件通常没有本地构建可替代验证；BOS 注册、外部系统操作、人工功能测试和生产环境验证必须由用户提供可核验证据并记录来源。",
+	"提示语集中管理为正式工程指令；禁止口语化、闲聊式、鼓励式提示词进入运行时规则。",
+	"不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实必须重新提问确认。",
+];
+
+export const PROMPT_STYLE_RULES = [
+	"使用正式、可执行的工程指令；禁止口语化、闲聊式、鼓励式表达。",
+	"事实不足时生成阻断问题；禁止输出模板代码、占位实现或基于猜测的业务标识。",
+	"每次只提出一个最阻塞问题；问题必须指向可验证事实、数据标识或验收证据。",
+	"引用顺序：当前项目文件、PLAN/SPEC、元数据 evidence、SDK 签名、验证输出。",
+];
+
+export const CORE_WORKFLOW_CONSTRAINTS = [
+	"产品代码只在 execute 阶段写入，并限于 PLAN.md 批准的文件。",
+	"写代码前必须具备通用实现契约：触发入口、源对象/输入数据、目标对象/输出结果、数据变化或字段映射、业务规则、失败处理和验收样例。",
+	"业务数据源未知时禁止编码；确认目标 FormId/单据或表单、插件类型和事件、字段/实体/分录标识、数据读取写入方式后再编码；SQL/KSQL 同步确认表名和数据库字段名。",
+	"第三方对接确认接口文档、对接方向、触发时机、认证配置、字段映射、并发/幂等、重试超时限流、错误补偿、日志脱敏和验收样例后再编码。",
+	"事实缺失时使用 kd_question 登记一个最阻塞问题；禁止用 API 文档、SDK 知识库或推测替代业务事实。",
+	"用户输入是在回答 open question 时，必须先调用 kd_question action=answer 记录答案，再继续推进或登记下一个问题。",
+	"同一 factLabel 已有当前事实时禁止重复提问；用户明确更正时使用 kd_question action=revise 记录新事实和更正原因。",
+	"run.facts 是唯一结构化事实源；questions 仅作为问答审计记录，禁止从历史 question 反推门禁事实。",
+	"待确认、未知、按实际环境、TODO/TBD 等占位答案不能解除门禁。",
+	"Java/C# SDK 签名以当前项目 jar/dll、构建输出或官方元数据为准。",
+	"Java/Cosmic 使用当前项目 Gradle；C#/企业版使用 dotnet build。",
+	"evidence 必须记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
+	"外部系统操作、BOS 注册、人工功能测试和生产环境验证不能由 LLM 代办；必须要求用户提供验证结果或可核验证据，并记录证据来源。",
+	"Windows 路径规则：项目相对路径为默认；绝对路径使用 D:\\... 形式。",
+];
+
+export const PHASE_GUIDANCE: Record<KdPhase, string> = {
+	discuss: "梳理需求来源、范围、已知事实；如缺通用实现契约、数据源或第三方接口关键事实，使用 kd_question 登记一个最阻塞问题。",
+	spec: "将需求转成验收标准、实现契约、数据对象、接口契约、异常行为、依赖和风险；数据对象和字段映射必须落到可核验标识。",
+	plan: "检查项目结构，写明目标路径、允许修改文件、通用实现契约、数据源/元数据查证项、第三方接口契约、插件挂载点、验证命令和回滚说明。",
+	execute: "按 PLAN.md 实现，记录步骤结果、变更文件和 evidence。",
+	verify: "运行计划中的验证命令，并用 kd_verify_result 记录结果；失败会回到 execute 修复，成功后更新 VERIFY.md、证据和残余风险。",
+	ship: "整理 SHIP.md，包括摘要、验证证据、风险和后续事项。",
+};
+
+export const PLAN_REQUIRED_CHECK_LINES = [
+	"涉及表单、单据、字段、实体、SQL/KSQL、数据读取写入或插件事件时，确认真实数据源/元数据后再编码；禁止只根据 API 文档编码。",
+	"Cosmic 家族数据源证据：evidence/cosmic-metadata.json；企业版/BOS 数据源证据：evidence/data-source.md。",
+	`所有产品代码实现必须写明通用实现契约后再编码：${IMPLEMENTATION_CONTRACT_FIELDS.map((field) => field.label).join("、")}。`,
+	`进入 execute 前必须写明：${DATA_SOURCE_CONTEXT_FIELDS.map((field) => field.label).join("、")}。`,
+	`第三方对接必须写明：${INTEGRATION_CONTEXT_FIELDS.map((field) => field.label).join("、")}。`,
+	"Java/C# 代码涉及 SDK 类、方法、构造器、枚举、属性时，使用 kd_sdk_signature 或项目构建输出确认真实签名后再编码。",
+	"知识库搜索、随包 Cosmic API 查询只能作为线索，不能作为最终方法签名事实。",
+	"SDK 签名证据：evidence/sdk-signature.md",
+];
+
+export function formatPromptLines(lines: string[]): string[] {
+	return lines.map((line) => `- ${line}`);
+}
+
+export function fieldLabels(fields: ContractField[]): string[] {
+	return fields.map((field) => field.label);
+}
+
+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;
+}
+
+export function canonicalFactLabel(label: string): string | undefined {
+	const normalized = normalizeLabel(label);
+	const fields = [...IMPLEMENTATION_CONTRACT_FIELDS, ...DATA_SOURCE_CONTEXT_FIELDS, ...INTEGRATION_CONTEXT_FIELDS];
+	return fields.find((field) => [field.label, ...field.aliases].some((item) => normalizeLabel(item) === normalized))?.label;
+}
+
+function normalizeLabel(label: string): string {
+	return label.trim().toLowerCase().replace(/\s+/g, "");
+}

package/src/harness/prompt.ts

@@ -4,6 +4,8 @@ import { delegationGuidanceForWorkflow, shouldInjectDelegationGuidance } from ".
 import { formatStatus } from "./format.ts";
 import type { ActiveRun, KdPhase } from "./types.ts";
 import { PHASE_ORDER } from "./types.ts";
+import { CORE_WORKFLOW_CONSTRAINTS, PHASE_GUIDANCE, PROMPT_STYLE_RULES, formatPromptLines } from "./prompt-policy.ts";
+import { formatQuestionMemory } from "./question-memory.ts";
 
 export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: string): string {
 	const status = formatStatus(cwd, run);
@@ -22,18 +24,20 @@ export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: stri
 		"KCode 阶段资料：",
 		memory,
 		"",
+		"KCode 已问已答事实：",
+		formatQuestionMemory(run),
+		"",
 		"项目上下文：",
-		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。需要项目结构时先运行或提示用户运行 `kcode context --refresh`。",
+		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。项目结构缺失时运行 `kcode context --refresh`。",
 		"",
 		"当前阶段任务：",
 		phaseGuidance,
 		"",
+		"工程指令风格：",
+		...formatPromptLines(PROMPT_STYLE_RULES),
+		"",
 		"核心约束：",
-		"- 产品代码只在 execute 阶段写入，并限于 PLAN.md 批准的文件。",
-		"- Java/C# SDK 签名以当前项目 jar/dll、构建输出或官方元数据为准。",
-		"- Java/Cosmic 用当前项目 Gradle；C#/企业版用 dotnet build。",
-		"- evidence 记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
-		"- Windows 下优先使用项目相对路径；绝对路径使用 D:\\... 形式。",
+		...formatPromptLines(CORE_WORKFLOW_CONSTRAINTS),
 		...delegationGuidance,
 	].join("\n");
 }
@@ -48,15 +52,7 @@ export function repairPromptForRun(run: ActiveRun): string {
 }
 
 function phaseGuidanceForRun(phase: KdPhase): string {
-	const guidance: Record<KdPhase, string> = {
-		discuss: "梳理需求来源、范围、已知事实和一个最阻塞的待确认问题。",
-		spec: "把需求转成验收标准、数据对象、异常行为、依赖和风险。",
-		plan: "检查项目结构，写明目标路径、允许修改文件、查证项、验证命令和回滚说明。",
-		execute: "按 PLAN.md 实现，记录步骤结果、变更文件和 evidence。",
-		verify: "运行计划中的验证命令，并用 kd_verify_result 记录结果；失败会回到 execute 修复，成功后更新 VERIFY.md、证据和残余风险。",
-		ship: "整理 SHIP.md，包括摘要、验证证据、风险和后续事项。",
-	};
-	return guidance[phase];
+	return PHASE_GUIDANCE[phase];
 }
 
 function workflowMemoryForRun(cwd: string, run: ActiveRun): string {
@@ -76,5 +72,5 @@ function workflowMemoryForRun(cwd: string, run: ActiveRun): string {
 
 function trimForPrompt(content: string, maxLength: number): string {
 	if (content.length <= maxLength) return content;
-	return `${content.slice(0, maxLength)}\n\n[...已截断；需要完整内容时读取本地文件...]`;
+	return `${content.slice(0, maxLength)}\n\n[...已截断；完整内容读取本地文件...]`;
 }