@fitlab-ai/agent-infra 0.12.0 → 0.12.2

package/lib/platform/issue-summary-content.ts

@@ -0,0 +1,132 @@
+import { runSummaryContentPipeline } from './summary-content-pipeline.ts';
+
+export type DeliverySummaryContent = Readonly<{
+  taskId: string; title: string; summary: string; artifacts: readonly string[];
+  verification: Readonly<{ state: string; detail: string }>;
+}>;
+export type CancelSummaryContent = Readonly<{
+  taskId: string; title: string; outcome: 'cancelled'; reason: string; cancelledAt: string;
+  lastCompletedArtifact: string | null;
+}>;
+
+export type DeliverySummarySources = Readonly<{
+  taskId: string;
+  title: string;
+  artifacts: readonly string[];
+  verificationFallback?: Readonly<{ state: string; detail: string }>;
+}>;
+
+function text(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  return value.trim();
+}
+
+function isMissingText(value: unknown): boolean {
+  return typeof value !== 'string' || !value.trim();
+}
+
+function fillText(input: Record<string, unknown>, key: string, fallback: string): void {
+  if (isMissingText(input[key])) input[key] = fallback;
+}
+
+function fillDeliveryVerification(
+  input: Record<string, unknown>, fallback: Readonly<{ state: string; detail: string }>
+): void {
+  if (!input.verification || typeof input.verification !== 'object' || Array.isArray(input.verification)) {
+    input.verification = fallback;
+    return;
+  }
+  const verification = { ...(input.verification as Record<string, unknown>) };
+  fillText(verification, 'state', fallback.state);
+  fillText(verification, 'detail', fallback.detail);
+  input.verification = verification;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.trim());
+}
+
+export function parseDeliverySummaryContent(value: unknown): DeliverySummaryContent {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('delivery summary must be an object');
+  const input = value as Record<string, unknown>;
+  if (!Array.isArray(input.artifacts) || input.artifacts.some((item) => typeof item !== 'string')) throw new Error('artifacts must be a string array');
+  if (!input.verification || typeof input.verification !== 'object' || Array.isArray(input.verification)) throw new Error('verification must be an object');
+  const verification = input.verification as Record<string, unknown>;
+  return {
+    taskId: text(input.taskId, 'taskId'), title: text(input.title, 'title'), summary: text(input.summary, 'summary'),
+    artifacts: input.artifacts.map((item) => text(item, 'artifacts[]')),
+    verification: { state: text(verification.state, 'verification.state'), detail: text(verification.detail, 'verification.detail') }
+  };
+}
+
+function correctDeliverySummaryContent(value: unknown, sources: DeliverySummarySources): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('delivery summary must be an object');
+  const input = { ...(value as Record<string, unknown>) };
+  fillText(input, 'taskId', sources.taskId);
+  if (input.taskId !== sources.taskId) throw new Error('taskId does not match the active task');
+  fillText(input, 'title', sources.title);
+  if (!isStringArray(input.artifacts)) input.artifacts = [...sources.artifacts];
+  if (sources.verificationFallback) fillDeliveryVerification(input, sources.verificationFallback);
+  return input;
+}
+
+export function prepareAndRenderDeliverySummaryContent(value: unknown, sources: DeliverySummarySources) {
+  return runSummaryContentPipeline(value, {
+    validate: parseDeliverySummaryContent,
+    correct: (input) => correctDeliverySummaryContent(input, sources),
+    render: renderDeliverySummaryContent
+  });
+}
+
+export function renderDeliverySummaryContent(value: DeliverySummaryContent): string {
+  const content = parseDeliverySummaryContent(value);
+  return [
+    `# ${content.title}`, '', content.summary, '', '## 交付产物', '',
+    ...(content.artifacts.length ? content.artifacts.map((item) => `- ${item}`) : ['- 无']), '',
+    '## 验证', '', `状态：${content.verification.state}`, '', content.verification.detail, ''
+  ].join('\n');
+}
+
+export function parseCancelSummaryContent(value: unknown): CancelSummaryContent {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('cancel summary must be an object');
+  const input = value as Record<string, unknown>;
+  if (input.outcome !== 'cancelled') throw new Error('outcome must be cancelled');
+  if (input.lastCompletedArtifact !== null && typeof input.lastCompletedArtifact !== 'string') throw new Error('lastCompletedArtifact must be a string or null');
+  return {
+    taskId: text(input.taskId, 'taskId'), title: text(input.title, 'title'), outcome: 'cancelled',
+    reason: text(input.reason, 'reason'), cancelledAt: text(input.cancelledAt, 'cancelledAt'),
+    lastCompletedArtifact: input.lastCompletedArtifact === null ? null : text(input.lastCompletedArtifact, 'lastCompletedArtifact')
+  };
+}
+
+function correctCancelSummaryContent(value: unknown, sources: Readonly<{
+  taskId: string; title: string; reason: string; cancelledAt: string; lastCompletedArtifact: string | null;
+}>): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('cancel summary must be an object');
+  const input = { ...(value as Record<string, unknown>) };
+  fillText(input, 'taskId', sources.taskId);
+  if (input.taskId !== sources.taskId) throw new Error('taskId does not match the task');
+  fillText(input, 'title', sources.title);
+  fillText(input, 'reason', sources.reason);
+  fillText(input, 'cancelledAt', sources.cancelledAt);
+  if (input.lastCompletedArtifact === undefined
+    || (input.lastCompletedArtifact !== null && (typeof input.lastCompletedArtifact !== 'string' || !input.lastCompletedArtifact.trim()))) {
+    input.lastCompletedArtifact = sources.lastCompletedArtifact;
+  }
+  return input;
+}
+
+export function prepareAndRenderCancelSummaryContent(value: unknown, sources: Readonly<{
+  taskId: string; title: string; reason: string; cancelledAt: string; lastCompletedArtifact: string | null;
+}>) {
+  return runSummaryContentPipeline(value, {
+    validate: parseCancelSummaryContent,
+    correct: (input) => correctCancelSummaryContent(input, sources),
+    render: renderCancelSummaryContent
+  });
+}
+
+export function renderCancelSummaryContent(value: CancelSummaryContent): string {
+  const content = parseCancelSummaryContent(value);
+  return [`# ${content.title}`, '', `结果：${content.outcome}`, '', `取消时间：${content.cancelledAt}`, '', `原因：${content.reason}`, '', `最近完成产物：${content.lastCompletedArtifact ?? '无'}`, ''].join('\n');
+}

package/lib/platform/issues.ts

@@ -27,9 +27,7 @@ import {
   labelDelta,
   inLabelMappingDigest,
   planInLabelUpdate,
-  syncLabelDelta,
   validateInLabelMapping,
-  validateRepositoryLabelPayload
 } from './in-label-sync.ts';
 import {
   providerError,

package/lib/platform/operation-coordinator.ts

@@ -37,7 +37,8 @@ async function coordinatePlatformWrite<T extends OperationResult>(input: Coordin
     });
   }
 
-  const selection = input.operation.kind === 'issue-metadata' && input.operation.issueMetadata?.state === 'closed'
+  const boundedPr = input.operation.kind === 'pull-request' && input.operation.dependency === 'required';
+  const selection = boundedPr || input.operation.kind === 'issue-metadata' && input.operation.issueMetadata?.state === 'closed'
     ? 'all' : input.operation.dependency;
   const drained = input.drain
     ? await input.drain(input.operation.taskRef, operationId, input.agent, input.operation.cwd)
@@ -45,7 +46,8 @@ async function coordinatePlatformWrite<T extends OperationResult>(input: Coordin
       agent: input.agent,
       client: input.client,
       cwd: input.operation.cwd,
-      excludeId: operationId
+      excludeId: operationId,
+      ...(boundedPr ? { beforeId: operationId } : {})
     });
   if (drained.status !== 'applied' && drained.status !== 'no-op') {
     return input.block(drained.error ? { ...drained.error, retryable: true } : {

package/lib/platform/pr-change-report.ts

@@ -7,7 +7,7 @@ import { isResourceIdentity } from './resource-identity.ts';
 import type { ResourceIdentity } from './resource-identity.ts';
 
 const REPORT_FILE_NAME = 'pr-change-report.json';
-const REPORT_VERSION = 2 as const;
+const REPORT_VERSION = 3 as const;
 const CANONICAL_REPORT_PLACEHOLDER = '<!-- canonical-pr-change-report -->';
 const CANONICAL_REPORT_HEADING = '### PR 代码增减';
 const PRECHECK_IDS = [
@@ -71,11 +71,21 @@ type Evidence = {
   detail: string;
 };
 
+type FunctionalGroup = {
+  id: string;
+  target: string;
+  behaviorChange: string;
+  necessity: string;
+  files: string[];
+  tests: { coverage: string; cost: string };
+};
+
 type Precheck = {
   id: PrecheckId;
   verdict: CheckVerdict;
   evidence: Evidence[];
   rationale: string;
+  groups?: FunctionalGroup[];
 };
 
 type PrecheckCandidate = {
@@ -213,25 +223,136 @@ function parseEvidence(value: unknown, checkId: string, index: number): Validati
   return { ok: true, value: { path: value.path, startLine, endLine, detail: value.detail } };
 }
 
-function parseChecks(value: unknown, prefix = 'precheck.checks'): ValidationResult<Precheck[]> {
+function parseFunctionalGroupFiles(value: unknown, prefix: string): ValidationResult<string[]> {
+  if (!Array.isArray(value) || value.length === 0) return invalid(`${prefix} must be a non-empty array`);
+  const files: string[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const file = value[index];
+    if (!isSafeRenderedText(file)) return invalid(`${prefix}[${index}] must be a non-empty string`);
+    files.push(file.trim());
+  }
+  return { ok: true, value: files };
+}
+
+function parseFunctionalGroupTests(value: unknown, prefix: string): ValidationResult<FunctionalGroup['tests']> {
+  if (!isRecord(value)) return invalid(`${prefix} must be an object`);
+  if (!isSafeRenderedText(value.coverage)) return invalid(`${prefix}.coverage is required`);
+  if (!isSafeRenderedText(value.cost)) return invalid(`${prefix}.cost is required`);
+  return { ok: true, value: { coverage: value.coverage.trim(), cost: value.cost.trim() } };
+}
+
+function parseFunctionalGroup(value: unknown, prefix: string, ids: Set<string>): ValidationResult<FunctionalGroup> {
+  if (!isRecord(value)) return invalid(`${prefix} must be an object`);
+  if (Object.hasOwn(value, 'additions') || Object.hasOwn(value, 'deletions') || Object.hasOwn(value, 'net') || Object.hasOwn(value, 'counts')) {
+    return invalid(`${prefix} line counts are derived from diff files and must not be supplied`);
+  }
+  if (!isSafeRenderedText(value.id) || ids.has(value.id.trim())) return invalid(`${prefix}.id must be non-empty and unique`);
+  if (!isSafeRenderedText(value.target)) return invalid(`${prefix}.target is required`);
+  if (!isSafeRenderedText(value.behaviorChange)) return invalid(`${prefix}.behaviorChange is required`);
+  if (!isSafeRenderedText(value.necessity)) return invalid(`${prefix}.necessity is required`);
+  const files = parseFunctionalGroupFiles(value.files, `${prefix}.files`);
+  if (!files.ok) return files;
+  const tests = parseFunctionalGroupTests(value.tests, `${prefix}.tests`);
+  if (!tests.ok) return tests;
+  const id = value.id.trim();
+  ids.add(id);
+  return {
+    ok: true,
+    value: {
+      id, target: value.target.trim(), behaviorChange: value.behaviorChange.trim(),
+      necessity: value.necessity.trim(), files: files.value, tests: tests.value
+    }
+  };
+}
+
+function parseFunctionalGroups(value: unknown, prefix: string): ValidationResult<FunctionalGroup[]> {
+  if (!Array.isArray(value) || value.length === 0) return invalid(`${prefix} must be a non-empty array`);
+  const groups: FunctionalGroup[] = [];
+  const ids = new Set<string>();
+  for (let index = 0; index < value.length; index += 1) {
+    const group = parseFunctionalGroup(value[index], `${prefix}[${index}]`, ids);
+    if (!group.ok) return group;
+    groups.push(group.value);
+  }
+  return { ok: true, value: groups };
+}
+
+function indexDiffFiles(files: ChangeFile[]): ValidationResult<Map<string, ChangeFile>> {
+  const fileByPath = new Map<string, ChangeFile>();
+  for (const file of files) {
+    const key = file.oldPath ?? file.newPath;
+    if (!key || fileByPath.has(key)) return invalid(`diff file path '${key ?? ''}' is missing or duplicated`);
+    fileByPath.set(key, file);
+  }
+  return { ok: true, value: fileByPath };
+}
+
+function collectGroupMembership(
+  groups: FunctionalGroup[], fileByPath: Map<string, ChangeFile>
+): ValidationResult<Set<string>> {
+  const assigned = new Set<string>();
+  for (const group of groups) {
+    for (const member of group.files) {
+      const file = fileByPath.get(member);
+      if (!file) return invalid(`change-composition group '${group.id}' references unknown diff file '${member}'`);
+      if (assigned.has(member)) return invalid(`diff file '${member}' belongs to more than one functional group`);
+      assigned.add(member);
+    }
+  }
+  return { ok: true, value: assigned };
+}
+
+function validateGroupMembership(checks: Precheck[], files: ChangeFile[]): ValidationResult<Precheck[]> {
+  const composition = checks.find((check) => check.id === 'change-composition');
+  if (!composition?.groups) return invalid('precheck.checks.change-composition.groups is required');
+  const indexed = indexDiffFiles(files);
+  if (!indexed.ok) return indexed;
+  const assigned = collectGroupMembership(composition.groups, indexed.value);
+  if (!assigned.ok) return assigned;
+  const missing = [...indexed.value.keys()].find((key) => !assigned.value.has(key));
+  if (missing) return invalid(`diff file '${missing}' has no functional group`);
+  return { ok: true, value: checks };
+}
+
+function parseEvidenceList(value: unknown, checkId: PrecheckId, prefix: string): ValidationResult<Evidence[]> {
+  if (!Array.isArray(value) || value.length === 0) return invalid(`${prefix}.${checkId}.evidence must not be empty`);
+  const evidence: Evidence[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const parsed = parseEvidence(value[index], checkId, index);
+    if (!parsed.ok) return parsed;
+    evidence.push(parsed.value);
+  }
+  return { ok: true, value: evidence };
+}
+
+function parseCheck(value: unknown, index: number, prefix: string): ValidationResult<Precheck> {
+  const expectedId = PRECHECK_IDS[index]!;
+  const entryPrefix = `${prefix}[${index}]`;
+  const at = `${prefix}.${expectedId}`;
+  if (!isRecord(value)) return invalid(`${entryPrefix} must be an object`);
+  if (value.id !== expectedId) return invalid(`${entryPrefix}.id must be '${expectedId}'`);
+  if (value.verdict !== 'pass' && value.verdict !== 'needs-review') return invalid(`${at}.verdict is invalid`);
+  const evidence = parseEvidenceList(value.evidence, expectedId, prefix);
+  if (!evidence.ok) return evidence;
+  if (!isSafeRenderedText(value.rationale)) return invalid(`${at}.rationale is required`);
+  if (expectedId !== 'change-composition') {
+    if (Object.hasOwn(value, 'groups')) return invalid(`${at}.groups is not allowed`);
+    return { ok: true, value: { id: expectedId, verdict: value.verdict, evidence: evidence.value, rationale: value.rationale } };
+  }
+  const groups = parseFunctionalGroups(value.groups, `${at}.groups`);
+  if (!groups.ok) return groups;
+  return { ok: true, value: { id: expectedId, verdict: value.verdict, evidence: evidence.value, rationale: value.rationale, groups: groups.value } };
+}
+
+function parseChecks(value: unknown, prefix = 'precheck.checks', diffFiles?: ChangeFile[]): ValidationResult<Precheck[]> {
   if (!Array.isArray(value) || value.length !== PRECHECK_IDS.length) return invalid(`${prefix} must contain exactly six checks`);
   const checks: Precheck[] = [];
   for (let index = 0; index < value.length; index += 1) {
-    const raw = value[index];
-    if (!isRecord(raw)) return invalid(`${prefix}[${index}] must be an object`);
-    const expectedId = PRECHECK_IDS[index]!;
-    if (raw.id !== expectedId) return invalid(`${prefix}[${index}].id must be '${expectedId}'`);
-    if (raw.verdict !== 'pass' && raw.verdict !== 'needs-review') return invalid(`${prefix}.${expectedId}.verdict is invalid`);
-    if (!Array.isArray(raw.evidence) || raw.evidence.length === 0) return invalid(`${prefix}.${expectedId}.evidence must not be empty`);
-    const evidence: Evidence[] = [];
-    for (let evidenceIndex = 0; evidenceIndex < raw.evidence.length; evidenceIndex += 1) {
-      const parsed = parseEvidence(raw.evidence[evidenceIndex], expectedId, evidenceIndex);
-      if (!parsed.ok) return parsed;
-      evidence.push(parsed.value);
-    }
-    if (!isSafeRenderedText(raw.rationale)) return invalid(`${prefix}.${expectedId}.rationale is required`);
-    checks.push({ id: expectedId, verdict: raw.verdict, evidence, rationale: raw.rationale });
+    const parsed = parseCheck(value[index], index, prefix);
+    if (!parsed.ok) return parsed;
+    checks.push(parsed.value);
   }
+  if (diffFiles) return validateGroupMembership(checks, diffFiles);
   return { ok: true, value: checks };
 }
 
@@ -306,7 +427,7 @@ function validatePrChangeReport(value: unknown): ValidationResult<PrChangeReport
   if (!totalsMatchFiles(totals.value, files)) return invalid('change report totals do not match files');
   if (value.precheck.formalReview !== false || (value.precheck.verdict !== 'clear' && value.precheck.verdict !== 'needs-review') ||
       (value.precheck.route !== 'watch-pr' && value.precheck.route !== 'review-code')) return invalid('change report precheck envelope is invalid');
-  const checks = parseChecks(value.precheck.checks);
+  const checks = parseChecks(value.precheck.checks, 'precheck.checks', files);
   if (!checks.ok) return checks;
   const derivedVerdict: PrecheckVerdict = checks.value.every((check) => check.verdict === 'pass') ? 'clear' : 'needs-review';
   const derivedRoute: PrecheckRoute = derivedVerdict === 'clear' ? 'watch-pr' : 'review-code';
@@ -372,10 +493,6 @@ function buildPrChangeReport(
   });
 }
 
-function reportFilePath(taskDir: string): string {
-  return path.join(taskDir, REPORT_FILE_NAME);
-}
-
 function readPrChangeReport(file: string): ValidationResult<PrChangeReport> {
   try {
     const stat = fs.lstatSync(file);
@@ -556,10 +673,34 @@ function renderEvidence(evidence: Evidence): string {
   return `  - 证据：<code>${escapeReportText(evidence.path)}</code>${location}：${escapeReportText(evidence.detail)}`;
 }
 
-function renderPrechecks(checks: Precheck[]): string[] {
+function renderFunctionalGroups(groups: FunctionalGroup[], files: ChangeFile[]): string[] {
+  const filesByPath = new Map(files.map((file) => [file.oldPath ?? file.newPath!, file]));
+  return groups.flatMap((group) => {
+    const members = group.files.map((member) => filesByPath.get(member)!);
+    const additions = members.reduce((total, file) => total + (file.additions ?? 0), 0);
+    const deletions = members.reduce((total, file) => total + (file.deletions ?? 0), 0);
+    const unknownFiles = members.filter((file) => file.additions === null).length;
+    return [
+      `  - **功能组 ${escapeReportText(group.id)}**：${escapeReportText(group.target)}`,
+      `    - 行为变化：${escapeReportText(group.behaviorChange)}`,
+      `    - 必要性：${escapeReportText(group.necessity)}`,
+      `    - 文件：${group.files.map((member) => {
+        const file = filesByPath.get(member)!;
+        return file.oldPath && file.newPath && file.oldPath !== file.newPath
+          ? `<code>${escapeReportText(file.oldPath)}</code> → <code>${escapeReportText(file.newPath)}</code>`
+          : `<code>${escapeReportText(member)}</code>`;
+      }).join('、')}`,
+      `    - 可计数行数（由正式 diff 逐文件推导）：新增 ${additions}、删除 ${deletions}、净增 ${additions - deletions}${unknownFiles ? `；另有 ${unknownFiles} 个文件行数不可计` : ''}。`,
+      `    - 测试覆盖：${escapeReportText(group.tests.coverage)}；成本：${escapeReportText(group.tests.cost)}`
+    ];
+  });
+}
+
+function renderPrechecks(checks: Precheck[], files: ChangeFile[]): string[] {
   return checks.flatMap((check) => [
     `- **${PRECHECK_LABELS[check.id]}（${check.id}）**：${check.verdict === 'pass' ? '通过' : '需复核'}。${escapeReportText(check.rationale)}`,
-    ...check.evidence.map(renderEvidence)
+    ...check.evidence.map(renderEvidence),
+    ...(check.groups ? renderFunctionalGroups(check.groups, files) : [])
   ]);
 }
 
@@ -593,7 +734,7 @@ function renderCanonicalChangeReport(report: PrChangeReport): string {
     '',
     '#### 适宜性预检',
     `- 结论：${precheckSummary}；${route}；正式审查：否。`,
-    ...renderPrechecks(report.precheck.checks)
+    ...renderPrechecks(report.precheck.checks, report.diff.files)
   ].join('\n');
 }
 
@@ -620,7 +761,6 @@ export {
   readPrChangeReport,
   renderCanonicalChangeReport,
   replaceCanonicalReportPlaceholder,
-  reportFilePath,
   runMechanicalChangeReport,
   taskIntentDigest,
   taskIntentProjection,

package/lib/platform/pr-checks.ts

@@ -15,7 +15,6 @@ import {
   providerError,
   providerOperationContext,
   providerStatus,
-  resourceIdentity,
   resourceIdentityNumber,
   unsupportedProviderOperation
 } from './provider-bridge.ts';
@@ -56,14 +55,6 @@ function classifyPullRequestReadiness(input: {
   return { state: 'ready', headSha: input.headSha };
 }
 
-function resolveRunCandidate(candidates: RunCandidate[], headSha: string, checkName: string):
-  | { status: 'resolved'; runId: number; jobId: number | null }
-  | { status: 'missing' | 'ambiguous'; runId: null; jobId: null } {
-  const matches = candidates.filter((candidate) => candidate.headSha === headSha && candidate.name === checkName);
-  if (matches.length === 1) return { status: 'resolved', runId: matches[0]!.id, jobId: matches[0]!.jobId || null };
-  return { status: matches.length === 0 ? 'missing' : 'ambiguous', runId: null, jobId: null };
-}
-
 function checksResult(status: PlatformResult['status'], overrides: Partial<ChecksResult> = {}): ChecksResult {
   return {
     ...platformResult(status),
@@ -256,5 +247,5 @@ async function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions &
   }
 }
 
-export { classifyPullRequestReadiness, classifyRequiredChecks, fetchPlatformCheckLogs, inspectRequiredChecks, inspectPullRequestReadiness, resolvePlatformCheckRun, resolveRunCandidate, watchPullRequestReadiness };
+export { classifyPullRequestReadiness, classifyRequiredChecks, fetchPlatformCheckLogs, inspectRequiredChecks, inspectPullRequestReadiness, resolvePlatformCheckRun, watchPullRequestReadiness };
 export type { CheckBucket, CheckSnapshot, ChecksResult, ChecksSnapshot, CheckState, ReadinessSnapshot, ReadinessState, RunCandidate };

package/lib/platform/pr-review.ts

@@ -7,7 +7,7 @@ import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { providerErrorRetryable } from './provider-validation.ts';
 import { platformResult } from './types.ts';
-import type { PlatformOperation, PlatformResult } from './types.ts';
+import type { PlatformResult } from './types.ts';
 import {
   providerError,
   providerOperationContext,

package/lib/platform/pr-summary-content.ts

@@ -0,0 +1,60 @@
+import { CANONICAL_REPORT_PLACEHOLDER } from './pr-change-report.ts';
+import { MANUAL_VALIDATION_RECEIPT_PLACEHOLDER } from '../task/manual-validation-receipt.ts';
+
+export type PrSummaryContent = Readonly<{
+  overview: string;
+  tests: Readonly<{ state: string; detail: string }>;
+  review: Readonly<{ state: string; detail: string }>;
+  manualValidation: Readonly<{ state: string; detail: string }>;
+  humanDecisions: Readonly<{ open: number; resolved: number; detail: string }>;
+  risks: string;
+}>;
+
+function nonEmpty(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} must be a non-empty string`);
+  return value.trim();
+}
+
+export function parsePrSummaryContent(value: unknown): PrSummaryContent {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('PR summary must be an object');
+  const input = value as Record<string, unknown>;
+  const pair = (key: 'tests' | 'review' | 'manualValidation') => {
+    const item = input[key];
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error(`${key} must be an object`);
+    const fields = item as Record<string, unknown>;
+    return { state: nonEmpty(fields.state, `${key}.state`), detail: nonEmpty(fields.detail, `${key}.detail`) };
+  };
+  const decisions = input.humanDecisions;
+  if (!decisions || typeof decisions !== 'object' || Array.isArray(decisions)) throw new Error('humanDecisions must be an object');
+  const counts = decisions as Record<string, unknown>;
+  for (const key of ['open', 'resolved'] as const) {
+    if (!Number.isSafeInteger(counts[key]) || Number(counts[key]) < 0) throw new Error(`humanDecisions.${key} must be a non-negative integer`);
+  }
+  return {
+    overview: nonEmpty(input.overview, 'overview'),
+    tests: pair('tests'), review: pair('review'), manualValidation: pair('manualValidation'),
+    humanDecisions: { open: counts.open as number, resolved: counts.resolved as number, detail: nonEmpty(counts.detail, 'humanDecisions.detail') },
+    risks: nonEmpty(input.risks, 'risks')
+  };
+}
+
+export function renderPrSummaryContent(value: PrSummaryContent): string {
+  const content = parsePrSummaryContent(value);
+  const manualValidationHeading = content.manualValidation.state === 'required' ? '⚠️ 需人工校验'
+    : content.manualValidation.state === 'pending' ? '⏳ 人工验证待收尾'
+    : content.manualValidation.state === 'passed' ? '✅ 人工验证已通过'
+      : ['none', 'not-required'].includes(content.manualValidation.state) ? '✅ 无需人工校验'
+        : content.manualValidation.state === 'unavailable' ? '⚠️ 人工校验状态不可用'
+          : content.manualValidation.state === 'not-observed' ? 'ℹ️ 尚未读取人工校验状态'
+            : `人工校验状态：${content.manualValidation.state}`;
+  return [
+    '## 审查摘要', '', content.overview, '',
+    '### 关键技术决策', '', '（见审查历程）', '',
+    '### 审查历程', '', `状态：${content.review.state}`, '', content.review.detail, '',
+    '### 测试结果', '', `状态：${content.tests.state}`, '', content.tests.detail, '',
+    `### ${manualValidationHeading}`, '', `状态：${content.manualValidation.state}`, '', content.manualValidation.detail,
+    ...(content.manualValidation.state === 'passed' ? ['', MANUAL_VALIDATION_RECEIPT_PLACEHOLDER] : []), '',
+    '### 人工决策', '', `未解决：${content.humanDecisions.open}；已解决：${content.humanDecisions.resolved}`, '', content.humanDecisions.detail, '',
+    '### 风险', '', content.risks, '', CANONICAL_REPORT_PLACEHOLDER, ''
+  ].join('\n');
+}