kcode-pi 0.1.34 → 0.1.35

package/src/harness/delegation.ts

@@ -21,29 +21,29 @@ export interface ParsedDelegationArgs extends DelegationRequest {
 const ROLE_GUIDANCE: Record<DelegationRole, string[]> = {
 	research: [
 		"只读调研项目、文档、SDK 线索和现有实现。",
-		"输出压缩结论、证据文件/代码位置、风险和建议下一步。",
-		"不要修改文件，不要推进 Harness 状态。",
+		"输出压缩结论、证据文件/代码位置、风险和下一步指令。",
+		"禁止修改文件；禁止推进 Harness 状态。",
 	],
 	doc: [
 		"只写当前任务明确要求的文档或阶段产物。",
-		"如果需要改阶段文档，保持内容和当前 Harness 阶段一致。",
-		"不要修改产品源码，不要推进 Harness 状态。",
+		"修改阶段文档时，内容必须匹配当前 Harness 阶段。",
+		"禁止修改产品源码；禁止推进 Harness 状态。",
 	],
 	code: [
 		"只有当前 run 处于 execute 阶段时才允许修改产品代码。",
-		"只修改 PLAN.md 批准的文件；发现新文件需求时停止并说明需要回到 plan。",
-		"完成后列出变更文件、执行步骤证据和需要主 agent 验证的命令。",
+		"只修改 PLAN.md 批准的文件；发现新文件需求时停止并说明必须回到 plan。",
+		"完成后列出变更文件、执行步骤证据和主 agent 必须执行的验证命令。",
 	],
 	review: [
 		"只读交叉自查，不修改文件。",
-		"优先找 bug、状态机漏洞、门禁绕过、证据缺口和测试缺口。",
+		"审查重点：bug、状态机漏洞、门禁绕过、证据缺口和测试缺口。",
 		"输出 findings，按严重程度排序并带文件/函数引用；明确是否阻止发布。",
 	],
 	verify: [
 		"只读分析计划中的验证命令、失败证据和风险。",
-		"需要实际运行验证时，把命令和原因交回主 agent 执行。",
+		"实际运行验证由主 agent 执行；子 agent 输出命令和原因。",
 		"验证结果由主 agent 通过 kd_verify_result 记录。",
-		"不要手工绕过 Harness 的 VERIFY/evidence 记录闭环。",
+		"禁止绕过 Harness 的 VERIFY/evidence 记录闭环。",
 	],
 };
 
@@ -55,12 +55,12 @@ const ROLE_ALLOWED_WRITES: Record<DelegationRole, string> = {
 	verify: "evidence-through-kd_verify_result",
 };
 
-export const DEFAULT_REVIEW_TASK = "审查当前 run 和最近变更，重点找状态机漏洞、门禁绕过、证据缺口、提示词分散和测试缺口。";
+export const DEFAULT_REVIEW_TASK = "审查当前 run 和最近变更，重点找状态机漏洞、门禁绕过、证据缺口、工程指令分散和测试缺口。";
 export const CHILD_AGENT_USER_TASK = "执行 KCode 子 agent 委派任务。";
 export const KD_SUBAGENT_TOOL_DESCRIPTION =
 	"将调研、文档、代码、验证或交叉审查任务委派给隔离 Pi 子进程。主 Harness 仍负责阶段推进、证据和门禁。";
 export const KD_DELEGATE_USAGE = "用法：/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]";
-export const KD_SUBAGENT_INVALID_PARAMS = "kd_subagent 需要 role=research|doc|code|review|verify 和非空 task，或提供 tasks/chain。";
+export const KD_SUBAGENT_INVALID_PARAMS = "kd_subagent 参数要求：role=research|doc|code|review|verify 且 task 非空，或提供 tasks/chain。";
 export const KD_SUBAGENT_PARALLEL_ROLE_ERROR = "kd_subagent 并行模式只允许 research、review、verify 这类只读角色。doc/code 必须串行执行。";
 export const KD_REVIEW_COMMAND_DESCRIPTION = "启动只读交叉自查子 agent：/kd-review [审查重点]";
 export const KD_DELEGATE_COMMAND_DESCRIPTION = "委派任务给隔离子 agent：/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]";
@@ -97,10 +97,10 @@ export function parseDelegationArgs(args: string): ParsedDelegationArgs | undefi
 
 export function delegationBlockReason(role: DelegationRole, run: ActiveRun | undefined): string | undefined {
 	if (role === "code") {
-		if (!run) return "code 子 agent 需要 active Harness run，且必须处于 execute 阶段。";
+		if (!run) return "code 子 agent 要求 active Harness run，且必须处于 execute 阶段。";
 		if (run.phase !== "execute") return `code 子 agent 只能在 execute 阶段运行；当前阶段：${run.phase}。`;
 	}
-	if (role === "verify" && !run) return "verify 子 agent 需要 active Harness run。";
+	if (role === "verify" && !run) return "verify 子 agent 要求 active Harness run。";
 	return undefined;
 }
 
@@ -142,7 +142,7 @@ export function subagentToolCallBlockReason(input: {
 	sourceWriteBlockReason?: string;
 }): string | undefined {
 	if (SHELL_TOOL_NAMES.has(input.toolName)) {
-		return "子 agent 不允许调用 shell 类工具；需要运行命令时交回主 agent 执行。";
+		return "子 agent 禁止调用 shell 类工具；运行命令由主 agent 执行，子 agent 只输出命令和原因。";
 	}
 	if (!WRITE_TOOL_NAMES.has(input.toolName)) return undefined;
 
@@ -164,19 +164,19 @@ export function subagentToolCallBlockReason(input: {
 
 export function buildDelegationCommandPrompt(request: DelegationRequest, dryRun: boolean): string {
 	return [
-		"请调用 kd_subagent 完成以下委派任务。",
+		"执行 kd_subagent 委派任务。",
 		`role: ${request.role}`,
 		`dryRun: ${dryRun ? "true" : "false"}`,
 		"task:",
 		request.task,
 		"",
-		"子 agent 返回后，由主 agent 判断是否需要修改文件、记录 evidence 或推进 Harness。",
+		"子 agent 返回后，主 agent 负责采纳结论、修改文件、记录 evidence 或推进 Harness。",
 	].join("\n");
 }
 
 export function delegationGuidanceForWorkflow(): string {
 	return [
-		"- 当任务需要大量调研、独立交叉审查、长上下文复盘或可并行拆分时，优先考虑 kd_subagent。",
+		"- 任务包含大量调研、独立交叉审查、长上下文复盘或可并行拆分内容时，使用 kd_subagent。",
 		"- 自动委派只做旁路工作；主 agent 仍负责采纳结论、修改文件、记录 evidence 和推进阶段。",
 		"- code 委派只能在 execute 阶段且限于 PLAN.md 批准文件；review/research 默认只读。",
 	].join("\n");
@@ -192,7 +192,7 @@ export function buildChainedDelegationRequest(request: DelegationRequest, previo
 			"上一子 agent 输出：",
 			trimForPrompt(previousOutput, 6000),
 			"",
-			"请基于上一输出继续当前步骤，并只交付本步骤结论。",
+			"基于上一输出继续当前步骤；仅交付本步骤结论。",
 		].join("\n"),
 	};
 }
@@ -217,8 +217,8 @@ export function buildDelegationPrompt(cwd: string, run: ActiveRun | undefined, r
 		"",
 		"角色规则：",
 		...roleGuidance.map((item) => `- ${item}`),
-		"- 你不是主状态机；不要调用 /kd-advance、/kd-finish 或改变 run 生命周期。",
-		"- 不要再创建子 agent；把结果交回主 agent 统一决策。",
+		"- 子 agent 不是主状态机；禁止调用 /kd-advance、/kd-finish 或改变 run 生命周期。",
+		"- 禁止创建子 agent；输出结果交回主 agent 统一决策。",
 		"",
 		"Harness 状态：",
 		status,
@@ -227,13 +227,13 @@ export function buildDelegationPrompt(cwd: string, run: ActiveRun | undefined, r
 		phaseContext,
 		"",
 		"项目上下文：",
-		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。需要项目结构时读取本地文件或提示主 agent 运行 `kcode context --refresh`。",
+		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。项目结构缺失时读取本地文件；无法读取时要求主 agent 运行 `kcode context --refresh`。",
 		"",
 		"输出格式：",
 		"- 结论",
 		"- 证据/引用",
 		"- 风险",
-		"- 建议给主 agent 的下一步",
+		"- 主 agent 下一步指令",
 	].join("\n");
 }
 
@@ -268,7 +268,7 @@ function artifactSection(cwd: string, run: ActiveRun, phase: KdPhase): 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[...已截断；完整内容读取本地文件...]`;
 }
 
 function isDocWritablePath(cwd: string, run: ActiveRun | undefined, path: string | undefined): boolean {

package/src/harness/gates.ts

@@ -8,6 +8,13 @@ import { flagshipPlanBlockReason } from "./path-policy.ts";
 import { executionStepsBlockReason, planStepsBlockReason } from "./plan-steps.ts";
 import { tddPlanBlockReason, tddVerifyBlockReason } from "./tdd-policy.ts";
 import { SDK_SIGNATURE_EVIDENCE, hasValidSdkSignatureEvidence, requiresSdkSignatureEvidence } from "./sdk-policy.ts";
+import {
+	COSMIC_METADATA_EVIDENCE,
+	dataSourceContextBlockReason,
+	dataSourceEvidenceForRun,
+	hasValidDataSourceEvidence,
+	requiresDataSourceEvidence,
+} from "./data-source-policy.ts";
 import { runRoot } from "./paths.ts";
 import { EVIDENCE_INDEX, readEvidenceIndex } from "./evidence.ts";
 import {
@@ -28,7 +35,6 @@ const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
 };
 
 const COSMIC_CONFIG_EVIDENCE = "evidence/cosmic-config.txt";
-const COSMIC_METADATA_EVIDENCE = "evidence/cosmic-metadata.json";
 const COSMIC_API_EVIDENCE = "evidence/cosmic-api.txt";
 const KSQL_LINT_EVIDENCE = "evidence/ksql-lint.txt";
 
@@ -69,6 +75,7 @@ function collectGateProblems(cwd: string, run: ActiveRun, phase: KdPhase, mode:
 
 	const markerProblem = mode === "inspect" ? inspectMarkers(cwd, run, phase) : undefined;
 	const flagshipPathProblem = mode === "enter" && phase === "execute" ? flagshipPlanBlockReason(cwd, run, readArtifact(cwd, run, "plan") ?? "") : undefined;
+	const dataSourceContextProblem = phaseIndex >= PHASE_ORDER.indexOf("execute") ? dataSourceContextBlockReason(cwd, run) : undefined;
 	const stepProblem = inspectStepState(cwd, run, phase);
 	const evidenceProblem = mode === "inspect" ? inspectEvidence(cwd, run, phase) : undefined;
 	const questionProblem = inspectOpenQuestions(run);
@@ -77,6 +84,9 @@ function collectGateProblems(cwd: string, run: ActiveRun, phase: KdPhase, mode:
 	if (flagshipPathProblem) {
 		reasonParts.push(flagshipPathProblem);
 	}
+	if (dataSourceContextProblem) {
+		reasonParts.push(dataSourceContextProblem);
+	}
 	if (markerProblem) {
 		reasonParts.push(markerProblem);
 	}
@@ -204,6 +214,10 @@ function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase):
 
 	if (phaseIndex >= PHASE_ORDER.indexOf("execute")) {
 		if (requiresSdkSignatureEvidence(run)) required.add(SDK_SIGNATURE_EVIDENCE);
+		if (requiresDataSourceEvidence(cwd, run)) {
+			const evidence = dataSourceEvidenceForRun(run);
+			if (evidence) required.add(evidence);
+		}
 		if (isCosmicRun(run)) {
 			required.add(COSMIC_CONFIG_EVIDENCE);
 			if (planHasMetadataRequirement(cwd, run)) required.add(COSMIC_METADATA_EVIDENCE);
@@ -221,6 +235,7 @@ function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase):
 
 function evidenceArtifactSatisfied(cwd: string, run: ActiveRun, artifact: string): boolean {
 	if (artifact === SDK_SIGNATURE_EVIDENCE) return hasValidSdkSignatureEvidence(cwd, run);
+	if (artifact === dataSourceEvidenceForRun(run)) return hasValidDataSourceEvidence(cwd, run);
 	if (artifact === EVIDENCE_INDEX) return existsSync(join(runRoot(cwd, run), artifact));
 	return existsSync(join(runRoot(cwd, run), artifact)) && hasSuccessfulEvidenceEntry(cwd, run, artifact);
 }

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 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,196 @@
+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", "表单标识", "单据标识", "目标单据", "目标表单"],
+		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 PROMPT_STYLE_RULES = [
+	"使用正式、可执行的工程指令；禁止口语化、闲聊式、鼓励式表达。",
+	"事实不足时生成阻断问题；禁止输出模板代码、占位实现或基于猜测的业务标识。",
+	"每次只提出一个最阻塞问题；问题必须指向可验证事实、数据标识或验收证据。",
+	"引用顺序：当前项目文件、PLAN/SPEC、元数据 evidence、SDK 签名、验证输出。",
+];
+
+export const CORE_WORKFLOW_CONSTRAINTS = [
+	"产品代码只在 execute 阶段写入，并限于 PLAN.md 批准的文件。",
+	"写代码前必须具备通用实现契约：触发入口、源对象/输入数据、目标对象/输出结果、数据变化或字段映射、业务规则、失败处理和验收样例。",
+	"业务数据源未知时禁止编码；确认目标 FormId/单据或表单、插件类型和事件、字段/实体/分录标识、数据读取写入方式后再编码；SQL/KSQL 同步确认表名和数据库字段名。",
+	"第三方对接确认接口文档、对接方向、触发时机、认证配置、字段映射、并发/幂等、重试超时限流、错误补偿、日志脱敏和验收样例后再编码。",
+	"事实缺失时使用 kd_question 登记一个最阻塞问题；禁止用 API 文档、SDK 知识库或推测替代业务事实。",
+	"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;
+}

package/src/harness/prompt.ts

@@ -4,6 +4,7 @@ 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";
 
 export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: string): string {
 	const status = formatStatus(cwd, run);
@@ -23,17 +24,16 @@ export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: stri
 		memory,
 		"",
 		"项目上下文：",
-		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 +48,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 +68,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[...已截断；完整内容读取本地文件...]`;
 }