kcode-pi 0.1.31 → 0.1.35

package/src/harness/data-source-policy.ts

@@ -0,0 +1,302 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import type { ActiveRun } from "./types.ts";
+import { readArtifact } from "./artifacts.ts";
+import { hasEvidenceEntry } from "./evidence.ts";
+import { runRoot } from "./paths.ts";
+import { isSourceLikePath } from "./path-policy.ts";
+import {
+	dataSourcePlanBlockedReason,
+	dataSourceWriteBlockedReason,
+	implementationPlanBlockedReason,
+	implementationWriteBlockedReason,
+	integrationPlanBlockedReason,
+	integrationWriteBlockedReason,
+} from "./messages.ts";
+import {
+	DATA_SOURCE_CONTEXT_FIELDS,
+	IMPLEMENTATION_CONTRACT_FIELDS,
+	INTEGRATION_CONTEXT_FIELDS,
+	type ContractField,
+} from "./prompt-policy.ts";
+
+export const COSMIC_METADATA_EVIDENCE = "evidence/cosmic-metadata.json";
+export const DATA_SOURCE_EVIDENCE = "evidence/data-source.md";
+
+const DATA_SOURCE_KEYWORDS =
+	/数据源|元数据|表单|单据|字段|实体|分录|单据体|基础资料|物料|客户|供应商|Form\s*ID|FormId|formid|DynamicObject|DataSet|SQL|KSQL|查询|保存|校验|插件|事件|操作|列表|表名|数据库|dbName|dbKey|下推|上推|转换|生成单据/i;
+const IMPLEMENTATION_KEYWORDS =
+	/插件|服务|处理器|二开|开发|实现|新增|修改|保存|校验|联动|下推|上推|转换|生成|同步|接口|审批|提交|审核|操作|按钮|定时|任务|脚本|SQL|KSQL/i;
+const INTEGRATION_KEYWORDS =
+	/第三方|外部系统|外部接口|接口对接|对接|接口文档|HTTP|HTTPS|REST|SOAP|Webhook|webhook|回调|推送|拉取|同步|上报|下发|开放平台|API\s*接口/i;
+
+const IMPLEMENTATION_FIELDS = Object.fromEntries(IMPLEMENTATION_CONTRACT_FIELDS.map((field) => [field.id, field])) as Record<string, ContractField>;
+const DATA_SOURCE_FIELDS = Object.fromEntries(DATA_SOURCE_CONTEXT_FIELDS.map((field) => [field.id, field])) as Record<string, ContractField>;
+const INTEGRATION_FIELDS = Object.fromEntries(INTEGRATION_CONTEXT_FIELDS.map((field) => [field.id, field])) as Record<string, ContractField>;
+
+export function requiresDataSourceEvidence(cwd: string, run: ActiveRun): boolean {
+	if (!run.profile?.requiresMetadataVerification) return false;
+	if (run.profile.product === "unknown") return false;
+	return DATA_SOURCE_KEYWORDS.test(dataSourcePlanningText(cwd, run, { includePlan: false })) || planDeclaresConcreteDataSourceWork(cwd, run);
+}
+
+export function dataSourceEvidenceForRun(run: ActiveRun): string | undefined {
+	if (!run.profile?.requiresMetadataVerification) return undefined;
+	if (run.profile.platform === "cosmic") return COSMIC_METADATA_EVIDENCE;
+	if (run.profile.product === "enterprise") return DATA_SOURCE_EVIDENCE;
+	return DATA_SOURCE_EVIDENCE;
+}
+
+export function hasValidDataSourceEvidence(cwd: string, run: ActiveRun): boolean {
+	const evidence = dataSourceEvidenceForRun(run);
+	if (!evidence) return true;
+	const path = join(runRoot(cwd, run), evidence);
+	if (!existsSync(path)) return false;
+	if (!hasEvidenceEntry(cwd, run, evidence)) return false;
+	if (evidence === COSMIC_METADATA_EVIDENCE) return true;
+	return dataSourceEvidenceContentLooksConcrete(readFileSync(path, "utf8"));
+}
+
+export function dataSourceProductionWriteBlockReason(cwd: string, run: ActiveRun | undefined, path: string | undefined): string | undefined {
+	if (!run || run.phase !== "execute") return undefined;
+	if (!path || !isSourceLikePath(path)) return undefined;
+
+	const normalized = normalizeRelativePath(cwd && isAbsolute(path) ? relative(cwd, path) : path);
+	if (normalized.startsWith(".pi/")) return undefined;
+
+	const implementationMissing = missingImplementationContractItems(cwd, run);
+	if (implementationMissing.length > 0) return implementationWriteBlockedReason(normalized, implementationMissing);
+
+	const integrationMissing = missingIntegrationContextItems(cwd, run);
+	if (integrationMissing.length > 0) return integrationWriteBlockedReason(normalized, integrationMissing);
+
+	if (!requiresDataSourceEvidence(cwd, run)) return undefined;
+	if (hasValidDataSourceEvidence(cwd, run)) return undefined;
+
+	return dataSourceWriteBlockedReason(normalized, dataSourceEvidenceForRun(run) ?? DATA_SOURCE_EVIDENCE);
+}
+
+export function dataSourceContextBlockReason(cwd: string, run: ActiveRun): string | undefined {
+	const implementationMissing = missingImplementationContractItems(cwd, run);
+	if (implementationMissing.length > 0) return implementationPlanBlockedReason(implementationMissing);
+
+	const integrationMissing = missingIntegrationContextItems(cwd, run);
+	if (integrationMissing.length > 0) return integrationPlanBlockedReason(integrationMissing);
+
+	if (!requiresDataSourceEvidence(cwd, run)) return undefined;
+	const missing = missingDataSourceContextItems(cwd, run);
+	return missing.length > 0 ? dataSourcePlanBlockedReason(missing) : undefined;
+}
+
+function dataSourcePlanningText(cwd: string, run: ActiveRun, options: { includePlan?: boolean } = { includePlan: true }): string {
+	return [run.goal ?? "", readArtifact(cwd, run, "spec") ?? "", options.includePlan === false ? "" : readArtifact(cwd, run, "plan") ?? ""].join("\n");
+}
+
+function planDeclaresConcreteDataSourceWork(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	const withoutBoilerplate = plan
+		.split(/\r?\n/)
+		.filter((line) => !/必须先确认真实数据源|数据源证据|进入 execute 前必须写明|不能只根据 API 文档|必需的金蝶查证项/.test(line))
+		.join("\n");
+	return DATA_SOURCE_KEYWORDS.test(withoutBoilerplate);
+}
+
+function missingImplementationContractItems(cwd: string, run: ActiveRun): string[] {
+	if (!requiresImplementationContract(cwd, run)) return [];
+	const text = dataSourcePlanningText(cwd, run);
+	const missing: string[] = [];
+
+	if (!hasTriggerOrEntry(text)) missing.push(IMPLEMENTATION_FIELDS.trigger.label);
+	if (!hasSourceObject(text)) missing.push(IMPLEMENTATION_FIELDS.source.label);
+	if (!hasTargetObject(text)) missing.push(IMPLEMENTATION_FIELDS.target.label);
+	if (!hasDataChangeContract(text)) missing.push(IMPLEMENTATION_FIELDS["data-change"].label);
+	if (!hasRuleOrCondition(text)) missing.push(IMPLEMENTATION_FIELDS.rules.label);
+	if (!hasFailureContract(text)) missing.push(IMPLEMENTATION_FIELDS.failure.label);
+	if (!hasAcceptanceSample(text)) missing.push(IMPLEMENTATION_FIELDS.acceptance.label);
+
+	return missing;
+}
+
+function requiresImplementationContract(cwd: string, run: ActiveRun): boolean {
+	if (!run.profile?.requiresMetadataVerification || run.profile.product === "unknown") return false;
+	return IMPLEMENTATION_KEYWORDS.test(dataSourcePlanningText(cwd, run, { includePlan: false })) || planDeclaresConcreteImplementationWork(cwd, run);
+}
+
+function planDeclaresConcreteImplementationWork(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	const withoutBoilerplate = plan
+		.split(/\r?\n/)
+		.filter((line) => !/实现就绪|进入 execute 前必须写明|第三方对接必须写明|必需的金蝶查证项|不要写模板代码/.test(line))
+		.join("\n");
+	return IMPLEMENTATION_KEYWORDS.test(withoutBoilerplate);
+}
+
+function missingDataSourceContextItems(cwd: string, run: ActiveRun): string[] {
+	const text = dataSourcePlanningText(cwd, run);
+	const missing: string[] = [];
+
+	if (!hasTargetObjectIdentifier(text)) missing.push(DATA_SOURCE_FIELDS["target-form"].label);
+	if (!hasPluginHook(text)) missing.push(DATA_SOURCE_FIELDS["plugin-hook"].label);
+	if (!hasFieldOrEntityIdentifier(text)) missing.push(DATA_SOURCE_FIELDS["field-entity"].label);
+	if (!hasDataAccessStrategy(text)) missing.push(DATA_SOURCE_FIELDS["data-access"].label);
+	if (usesSql(text) && !hasSqlIdentifier(text)) missing.push(DATA_SOURCE_FIELDS["sql-identifiers"].label);
+
+	return missing;
+}
+
+function hasTriggerOrEntry(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.trigger)) return true;
+	return /(?:触发入口|执行时机|触发时机|入口|事件|生命周期|插件类型|按钮|操作|定时|任务|保存前|保存后|提交后|审核后|Before\w+|After\w+)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:保存前|保存后|提交后|审核后|定时|按钮点击|操作执行)/i.test(text);
+}
+
+function hasSourceObject(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.source)) return true;
+	return /(?:源对象|源单|来源单据|来源表单|输入数据|数据来源|取数来源|源 FormId|源FormId|源表|源实体)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:从|读取|基于).{0,20}(?:单据|表单|实体|字段|DynamicObject|DataSet|SQL|KSQL)/i.test(text);
+}
+
+function hasTargetObject(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.target)) return true;
+	return /(?:目标对象|目标单据|目标表单|目标 FormId|目标FormId|输出结果|生成结果|下游单据|目标表|目标实体)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:下推到|生成|写入|更新|推送到).{0,20}(?:单据|表单|实体|字段|接口|系统|表)/i.test(text);
+}
+
+function hasDataChangeContract(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS["data-change"])) return true;
+	return /(?:数据变化|字段映射|字段对应|字段改写|修改字段|写入字段|赋值规则|转换规则|映射关系|更新字段)\s*[：:=]\s*[^。\n\r；;]{2,}|(?:字段|field).{0,20}(?:->|映射|对应|写入|修改|赋值|更新)/i.test(text);
+}
+
+function hasRuleOrCondition(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.rules)) return true;
+	return /(?:业务规则|适用条件|过滤条件|执行条件|前置条件|判断条件|范围|何时执行|哪些数据)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:当|如果|仅|只处理|满足).{0,40}(?:时|则|才)/i.test(text);
+}
+
+function hasFailureContract(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.failure)) return true;
+	return /(?:失败处理|异常处理|错误处理|回滚|补偿|人工处理|失败后|重复执行|幂等|日志|告警)\s*[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function missingIntegrationContextItems(cwd: string, run: ActiveRun): string[] {
+	const text = dataSourcePlanningText(cwd, run);
+	if (!requiresIntegrationContext(cwd, run)) return [];
+
+	const missing: string[] = [];
+	if (!hasInterfaceDocument(text)) missing.push(INTEGRATION_FIELDS["interface-doc"].label);
+	if (!hasIntegrationDirection(text)) missing.push(INTEGRATION_FIELDS.direction.label);
+	if (!hasEndpointAndAuth(text)) missing.push(INTEGRATION_FIELDS["endpoint-auth"].label);
+	if (!hasFieldMapping(text)) missing.push(INTEGRATION_FIELDS["field-mapping"].label);
+	if (!hasConcurrencyStrategy(text)) missing.push(INTEGRATION_FIELDS.concurrency.label);
+	if (!hasRetryTimeoutStrategy(text)) missing.push(INTEGRATION_FIELDS.retry.label);
+	if (!hasErrorHandlingStrategy(text)) missing.push(INTEGRATION_FIELDS.error.label);
+	if (!hasLoggingStrategy(text)) missing.push(INTEGRATION_FIELDS.logging.label);
+	if (!hasAcceptanceSample(text)) missing.push(INTEGRATION_FIELDS.samples.label);
+	return missing;
+}
+
+function requiresIntegrationContext(cwd: string, run: ActiveRun): boolean {
+	return INTEGRATION_KEYWORDS.test(dataSourcePlanningText(cwd, run, { includePlan: false })) || planDeclaresConcreteIntegrationWork(cwd, run);
+}
+
+function planDeclaresConcreteIntegrationWork(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	const withoutBoilerplate = plan
+		.split(/\r?\n/)
+		.filter((line) => !/第三方对接必须写明|接口文档来源\/版本|没有这些信息只能写模板代码|必需的金蝶查证项/.test(line))
+		.join("\n");
+	return INTEGRATION_KEYWORDS.test(withoutBoilerplate);
+}
+
+function hasInterfaceDocument(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS["interface-doc"])) return true;
+	return /(?:接口文档|API\s*文档|文档来源|协议文档|OpenAPI|Swagger)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:https?:\/\/|\.pdf|\.docx?|\.xlsx?|swagger\.json|openapi\.json)/i.test(text);
+}
+
+function hasIntegrationDirection(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.direction)) return true;
+	return /(?:对接方向|触发时机|同步方向|数据流向|调用方|被调用方)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}|(?:金蝶调用第三方|第三方调用金蝶|入站|出站|推送|拉取|回调|定时|保存后|审核后|提交后)/i.test(text);
+}
+
+function hasEndpointAndAuth(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS["endpoint-auth"])) return true;
+	return /(?:接口地址|Endpoint|URL|Base\s*URL|认证|鉴权|Token|AK|SK|AppKey|AppSecret|密钥|签名|OAuth)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasFieldMapping(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS["field-mapping"])) return true;
+	return /(?:字段映射|映射关系|字段对应|字段对照|mapping)\s*[：:=]\s*[^。\n\r；;]{2,}|(?:第三方字段|外部字段).*(?:金蝶字段|单据字段|字段标识)/is.test(text);
+}
+
+function hasConcurrencyStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.concurrency)) return true;
+	return /(?:并发|幂等|去重|唯一键|业务主键|重复提交|锁|乐观锁|重入)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasRetryTimeoutStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.retry)) return true;
+	return /(?:超时|timeout|重试|retry|限流|频率|rate\s*limit|熔断)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasErrorHandlingStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.error)) return true;
+	return /(?:错误处理|异常处理|失败处理|失败补偿|补偿|回滚|死信|告警|人工处理)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasLoggingStrategy(text: string): boolean {
+	if (hasLabeledValue(text, INTEGRATION_FIELDS.logging)) return true;
+	return /(?:日志|审计|留痕|脱敏|敏感信息|traceId|requestId|请求日志|响应日志)[^：:=\n\r]{0,24}[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasAcceptanceSample(text: string): boolean {
+	if (hasLabeledValue(text, IMPLEMENTATION_FIELDS.acceptance) || hasLabeledValue(text, INTEGRATION_FIELDS.samples)) return true;
+	return /(?:请求样例|响应样例|报文样例|验收样例|测试数据|示例报文|payload)\s*[：:=]\s*[^。\n\r；;]{2,}/i.test(text);
+}
+
+function hasTargetObjectIdentifier(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["target-form"])) return true;
+	return /(?:Form\s*ID|FormId|formid|表单标识|单据标识|目标单据|目标表单)\s*[：:=]\s*[A-Za-z0-9_.-]{2,}|(?:单据|表单)\s*[：:=]\s*[^。\n\r，,；;]{2,}/i.test(text);
+}
+
+function hasPluginHook(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["plugin-hook"])) return true;
+	return /(?:插件类型|插件|事件|生命周期|触发时机|挂载点)\s*[：:=]\s*[^。\n\r，,；;]{2,}|Before\w+|After\w+|Save|保存前|保存后|提交|审核|字段值改变|F7|列表/i.test(text);
+}
+
+function hasFieldOrEntityIdentifier(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["field-entity"])) return true;
+	return /(?:字段标识|字段|实体标识|实体|分录标识|单据体标识|Entry|Entity)\s*[：:=]\s*[^。\n\r，,；;]{2,}|[A-Za-z][A-Za-z0-9_]*(?:Id|ID|No|Name|Qty|Amount)\b/.test(text);
+}
+
+function hasDataAccessStrategy(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["data-access"])) return true;
+	return /(?:读取方式|写入方式|数据访问|取数方式|数据源|读写策略)\s*[：:=]\s*[^。\n\r，,；;]{2,}|(?:表单数据|模型数据|单据数据|DynamicObject|DataSet|QueryService|BusinessDataService|SQL|KSQL|直接读表|数据库查询)/i.test(text);
+}
+
+function usesSql(text: string): boolean {
+	const normalized = text.replace(/不(?:需要|使用|直接)?读表|不使用\s*(?:SQL|KSQL)|无需\s*(?:SQL|KSQL)|非\s*(?:SQL|KSQL)/gi, "");
+	return /\bSQL\b|\bKSQL\b|直接读表|数据库查询|表名/i.test(normalized);
+}
+
+function hasSqlIdentifier(text: string): boolean {
+	if (hasLabeledValue(text, DATA_SOURCE_FIELDS["sql-identifiers"])) return true;
+	return /(?:表名|数据库表|SQL\s*表|KSQL\s*表)\s*[：:=]\s*[A-Za-z0-9_.$-]{2,}/i.test(text) && /(?:数据库字段|SQL\s*字段|字段名|列名)\s*[：:=]\s*[A-Za-z0-9_.$,\s-]{2,}/i.test(text);
+}
+
+function dataSourceEvidenceContentLooksConcrete(content: string): boolean {
+	const text = content.trim();
+	if (text.length < 30) return false;
+	if (/待确认|未知|TODO|TBD|未提供|无数据源/i.test(text)) return false;
+	return /Form\s*ID|FormId|formid|单据|表单|字段|实体|表名|数据源|BOS|DynamicObject|DataSet|数据库|测试数据/i.test(text);
+}
+
+function normalizeRelativePath(path: string): string {
+	return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+function hasLabeledValue(text: string, field: ContractField): boolean {
+	return field.aliases.some((alias) => {
+		const escaped = escapeRegExp(alias);
+		return new RegExp(`(?:^|[\\r\\n\\-\\*\\s])${escaped}\\s*[：:=]\\s*[^\\r\\n。；;，,]{2,}`, "i").test(text);
+	});
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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 {
@@ -16,6 +23,7 @@ import {
 	missingForTargetReason,
 	missingMarkerReason,
 	openQuestionsReason,
+	repairBlockedReason,
 	unknownProductReason,
 	unknownRiskReason,
 } from "./messages.ts";
@@ -27,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";
 
@@ -68,13 +75,18 @@ 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);
+	const repairProblem = inspectRepairState(run);
 
 	if (flagshipPathProblem) {
 		reasonParts.push(flagshipPathProblem);
 	}
+	if (dataSourceContextProblem) {
+		reasonParts.push(dataSourceContextProblem);
+	}
 	if (markerProblem) {
 		reasonParts.push(markerProblem);
 	}
@@ -87,6 +99,9 @@ function collectGateProblems(cwd: string, run: ActiveRun, phase: KdPhase, mode:
 	if (questionProblem) {
 		reasonParts.push(questionProblem);
 	}
+	if (repairProblem) {
+		reasonParts.push(repairProblem);
+	}
 
 	if (mode === "enter") {
 		missing.push(...missingEvidenceForPhase(cwd, run, phase));
@@ -148,6 +163,11 @@ function inspectOpenQuestions(run: ActiveRun): string | undefined {
 	return openQuestionsReason(open);
 }
 
+function inspectRepairState(run: ActiveRun): string | undefined {
+	if (run.repair?.status !== "blocked") return undefined;
+	return repairBlockedReason(run.repair.attempts, run.repair.maxAttempts, run.repair.lastFailureEvidence);
+}
+
 function inspectStepState(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
 	if (phase === "execute") {
 		const plan = readArtifact(cwd, run, "plan") ?? "";
@@ -194,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);
@@ -211,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);
 }