襷の系譜:数据治理 Agent 技术方案
更新:2026-11-18。依据PRD,按当前源码整理;取代早期研发计划和重复历史状态。问题及验证过程见优化记录。契约版本 event-governance/1,规则常量 2026-11-13.2,归一化策略 whole-group-cross-check/8;版本常量不表示其后没有代码修正,运行审计仍需关联实际提交/镜像。
1. 系统边界
主站拥有 Prisma schema、migration、业务页面与缓存;Agent 仓库拥有 src/governance-v2 的 CLI、runner、Graph、研究适配器和唯一受控 BusinessWriter;个人站点提供文档与现有只读观测入口。旧 Agent 诊断/批处理入口不是 V2 导入执行链,不迁移旧运行记录来冒充新版基线。
赛事系列、届次、Race 和 Source 先由确定性准备脚本写入。标准输入只引用已存在结构,不要求调用方先手工匹配人物,不调用旧 importRacePayload 再次归一化。LLM、网络和 SMTP 调用均在业务事务外。
2. 输入、存储与幂等
Manifest 为 strict Zod schema:
| 字段 | 约定 |
|---|---|
| version | event-governance/1 |
| requestKey | 全任务幂等键,同键同输入复用,同键异输入拒绝 |
| eventEditionId | 已存在的赛事届次 |
| mode | dry_run 或 apply |
| agentMode | full(默认)或 membership_only |
| batches | 按唯一非负 sequence 排序,区组键在任务内唯一 |
Batch 包含 unitType(leg/heat/group)、unitKey、sequence、sourceId、raceSlug、organizations、rows、可选 teams 和 sourcePayload。行可提供 name、kana、roman、birthDate、organizationKey、memberships、mark、rank、teamRank、grade、notes、hometown、pbs、sourceUrl 和 sourceKey。没有来源支持的字段留空;组织引用必须在本批组织列表内,行键和组织键各自唯一。
sourceKey 只填写真实稳定来源标识,不能把姓名或不稳定行号冒充跨赛事人物 ID。缺省人物观察键使用 raceSlug 与 row key;旧 payload 通过 adapt 转为 manifest,保留原对象,不调用旧写入器。结构错误报错,不静默过滤行;dry_run 改 apply 使用新 requestKey。
原始批次按 hash 寻址存为 gzip,SQL 存引用;读时校验 hash、绝对路径和符号链接,解压上限 64 MiB。LangGraph checkpoint 使用独立 governance_checkpoint schema。dry_run 只保存计划,不写业务,后批不会看到前批的模拟变化。
3. 业务模型与治理记录
RaceResult.organizationNameSnapshot 与 organizationId 分开:有正式组织时可关联,未确认参赛名称只存快照并以纯文本显示。unknown/club/company 在输入契约中保留用于表达未确认来源,不能据此创建正式组织或 Membership;不能把“业务下线”误写成 schema 已删除枚举。地方代表及选拔/主办语义不自动生成 Membership。学校与已确认实业团是参赛所属生成 Membership 的允许类型。
Membership 使用 startDate/endDate、startDateBasis/endDateBasis(unknown/source/inferred)、endState(unknown/ongoing/ended)、dateEvidence、exclusivityGroup。旧数据未核验的日期不伪装为 source,缺结束时间不自动 ongoing。人物不增加 Agent 运行状态字段。
| 治理表 | 用途 |
|---|---|
| EventImportTask | requestKey、输入 hash、模式、汇总、租约和任务状态 |
| GovernanceBatch | 顺序、区组键、payload 引用/hash、行数、状态和汇总 |
| BatchAttempt | attemptNo、graphThreadId、inputFingerprint、metrics 和错误 |
| AgentExecution | attempt 下三组 Agent 的执行状态、结果及指标 |
| GovernanceFinding | 问题键、来源对象、严重性、resolutionStatus、原因和证据 |
| GovernanceChange | 受控操作、目标、计划版本、全局幂等键、patch/证据、AuditLog 引用 |
| NotificationDelivery | 赛事/批次通知、去重键、投递租约、重试和结果 |
业务外键和治理 UUID 分开;CHECK/XOR 等约束由 SQL migration 保证。finding resolved/unresolved/informational 与业务数据 pending/verified/conflicting 等状态不是同一概念。
4. 完整 Graph
load_batch_context
→ organization_rules → organization_light_batch
→ person_rules → person_light_batch
→ prepare_cross_check → normalization_cross_check → validate_cross_check
→ organization_adjudication → organization_network_research
→ affected_person_reassessment → normalization_deep_research
→ finalize_normalization
→ govern_membership(按需) → verify_person_facts(按需)
→ aggregate_governance_result
→ runner 保存计划 → BusinessWriter 事务提交
节点可无操作跳过,但没有回边。交叉校验一次,组织追加裁决最多一次,受影响选手重评最多一次。归一化属于同一职责组,不能用暂定人物证明组织、再用该组织反证同人。
4.1 规则、轻量及重型分流
来源映射、规范名、shortName 和 NameVariant 别名优先复用;组织做 NFKC/空白、学校后缀等规范化,不能把所有相似字符串写成普遍等价规则。别名预筛选和节点规范化并非完全统一,别名类型也没有完整分权重,不能承诺所有别名都能召回。
人物规则消费规范姓名、假名、生日、Membership 和来源明确的历史成绩。exact_name_kana_historical_organization 要求强候选唯一、相同汉字/假名、不同赛事且不晚于本场的有来源历史记录、同 canonical 组织,并排除学年或竞争所属矛盾。
unique_person_under_unconfirmed_organization 的实际条件:没有已确认组织映射、输入类型 unknown/club/company、该 organizationKey 在本批恰好一行、召回候选只有一个且姓名规范化一致、没有已知生日冲突。该规则复用人物,不创建组织或 Membership;不是“库中任何同名都直接合并”。
规则剩余对象按组织/人物各整组一次不联网轻量请求。人物 personAssessments 逐候选输出 nameRelation、samePersonPlausibility 和 reason;必须完整覆盖 allowedIds。相同读音只是候选线索,疑似误录需解释,不按相同字数决定身份。匹配需要目标独立证据;仅引用本次来源行且无明确一致生日时,单条降级 unresolved 并保留原判断,其他合法项继续。
交叉输入共享 catalog 去重,保留全组行/组织概况、相关证据、覆盖与截断提示。输出 personKeys 仅允许本批 rows[].key,不是候选 ID 或 gov 暂定 ID;未知引用、越界目标和结构损坏不能当作普通疑难通过。
组织仍有实质身份疑问时逐组织联网;结论限候选范围内的 match/distinct/unresolved。受影响人物重评后,中高可能性竞争或实质矛盾进入单人物深度研究;低可能性候选不因数量多就自动搜索。DNS 来源行当前跳过人物轻量/重型身份研究,安全规则匹配或保留独立档案;历史 DNS 仍能证明报名身份。
4.2 Membership 与事实节点
组织已确认且类型在初中/高中/大学/实业团允许集合时,缺少显式 hint 也生成隐式观察,学校为 enrolled、实业团为 affiliated。没有日期就保存空日期关系;DNS 仍参与。已有同关系无新信息不重复写;多段同组织记录不盲目合并。
年级和比赛日映射日本四月学年;高中三年、大学四年按可靠锚点双向补空,来源日期可纠正推算。互斥重叠或时间矛盾按规则先判断,无法解释时才请求 membership_conflict 研究。API/解析错误是技术失败,日期修正整体校验,不部分应用一个不合法回答。
事实节点只有 hometown/PB 输入时触发,当前跳过 DNS 和身份 unresolved 行。PB 需可解析、项目可比且满足来源可靠度门槛;正常改善不覆盖更好值,错误 PB 撤销不混入日常更新。
身份 unresolved 行当前暂不执行 Membership/事实写入,但保留人物和成绩。应明确记录待补内容,身份复核后补跑,不把这个跳过误报为“全部字段已治理”。
4.3 Membership-only 路径
agentMode=membership_only 复用来源映射、唯一规范名匹配及当前赛事成绩人物映射,组织类型以已归一化业务记录为准。只构造 Membership 计划和必要冲突研究,不重新归一化、不重写人物或成绩。无法恢复人物/组织时保留 membership_unresolved,不能构造不存在的业务人物 ID。
5. 模型协议、额度与诊断
模型和路由由环境显式配置,不继承当前 Codex 会话。现有路由使用 pro 的 gpt-6.1-sol;不能把不同账户分组的同模型名视为等价。适配器使用 /responses、消息数组输入、stream=true 和结构化 JSON schema,再以本地完整 Zod/引用范围校验。只有完整成功响应才能形成决策。请求联网时使用 web_search;确认结论须有实际工具调用及可追溯 URL/引文。
每批重型逻辑请求默认 3 次,非联网归一化/交叉/裁决共享 5 次逻辑额度。六类模型请求最多首次加两次重试,重试预留独立持久额度,恢复不重置。暂时网络故障、超时、408/409/429/5xx、不完整响应及可修复输出错误可重试;正常 unresolved、拒答、配置/预算不足、输入超限及 400/401/403 不盲重试。
GOVERNANCE_RESEARCH_TIMEOUT_MS 是应用请求超时,代码缺省 25000 ms,部署值可以覆盖;不能把示例值当线上实际值,也不能说模型固有 25 秒限制。已有生产调优将单请求限制调到 240 秒;新部署仍须核验运行环境和镜像。普通研究输入上限 24000 字符,归一化/组织裁决 512000 字符,响应读取上限 4 MiB。不宣称已配置请求级 token 或金额硬上限。
每个物理请求生成 callId/X-Client-Request-Id,日志关联 stage、startedAt、attemptNo、timeoutMs、请求 UTF-8 字节数/hash、HTTP 状态、响应 ID、提供方请求 ID、错误阶段、用量与重试耗尽。中转可能不提供或不支持检索这些 ID。HTTP 错误正文限读 32 KiB,提取脱敏限长摘要;SSE failed/incomplete、缺完成事件、网络和 JSON/schema/范围错误分开。完整 prompt、响应正文和密钥不进入公开日志;失败时未知用量不记作已知零费用。
6. 写入、状态与恢复
Plan 先持久化,writer 使用分离权限连接,在单批事务内校验 lease fencing、目标版本和受控操作,再提交业务实体、来源映射、AuditLog、change applied 和缓存失效。合并/拆分迁移指定关联并保存审计,不暴露任意 SQL/任意字段 patch 给 LLM。
任务/批次 queued → running → completed/completed_with_unresolved/failed;partial 仅为扩展位,不表示允许半事务提交。attempt 为 running/succeeded/failed/superseded;change 为 planned/applied/superseded。dry_run 不写业务,apply 还受写入开关约束。
技术失败停止后续批次,前面成功提交保留。retry 从未完成处恢复;checkpoint 已有完整计划时复用,计划过时则重读上下文;提交后崩溃只补收尾,幂等键防重复成绩和关系。租约 fencing 防旧 worker 提交。LLM 和批次重试分别记录。
7. 汇总、邮件与只读观测
importedRows 只累计实际 apply 成功数据,plannedRows 可含 dry_run。repairs 为已应用非纯创建/来源映射/成绩写入操作数,不等于人数;重试不重复累计写入,物理模型请求和 tokens 则累计全部尝试。估算价格未配置为 unknown,不是免费;搜索费等未配置成本不计为已覆盖。
批次只有 serious unresolved 或技术失败才排队告警,赛事终态排队总结。标题含赛事/区组,失败邮件也包含已完成阶段与调用统计。NotificationDelivery 使用稳定去重键与租约退避,投递失败不撤销业务;SMTP 不承诺端到端恰好一次。
现有站点只读连接有访问认证,缺配置时 fail closed。查询和展示有范围限制,提供人可读状态、阶段、attempt、指标、证据和最小变更摘要,不能把截断列表当完整统计。完整 payload、prompt、checkpoint 和凭据不公开;观测 UI 的进一步调整由独立工作维护。
8. 部署与运行
业务 schema/迁移与 grant 先部署,初始化 checkpoint schema,再更新 Agent worker 和只读站点;实际运行连接主站生产库,不连旧 Agent 库。环境变量和密钥由服务器受保护配置管理,不写文章。
Agent 使用 Compose 持久 payload volume、共享业务数据库网络、健康检查及现有内存保护,部署 workflow 构建并发布镜像。部署完成必须检查运行版本、健康状态及当前配置,不能只看仓库有提交。文档发布不触发赛事执行。
CLI 入口为 src/governance-v2/cli.ts:adapt、submit、run、status、retry、worker、work-once、deliver、mail-worker、setup-checkpoints、cleanup-checkpoints。完整导入选择 full,单独补履历选择 membership_only。命令、环境和启动顺序详见仓库 docs/governance-v2.md,其中历史运行叙述不替代实际生产核验。
默认只清理完成七天后的成功/过时 checkpoint;失败任务恢复点保留。原始输入、治理审计和通知没有完整自动清理策略,需按实际增长和备份制定保留周期。停 worker 不撤销已提交数据;应用回退不 drop schema,数据修正用独立审计补偿,不提供未经审查的一键回滚。
9. 验证状态与限制
V2 已用于生产赛事增量导入和 Membership 补跑,不再处于“只完成 fixture、未部署”的阶段。第333回任务最后两条身份 finding 经人工决策与数据修正后 resolved,任务 unresolved=0;这不是纯 Graph 自动治理效果。
变更验证覆盖类型检查、规则/研究/姓名回归和隔离 PostgreSQL 集成测试。每次发布说明实际运行的检查,不复用旧测试数量声称全部新规则已验证;集成测试须用显式隔离测试库,禁止连接生产库做故障注入。
当前限制包括:别名召回不完全统一;身份未决行下游治理仍需补跑;保留周期和费用覆盖不完整;网络来源和模型判断不保证绝对正确。新赛事应保留每批输入、版本、完整结果及问题,按真实观测再优化,不把单场人工清零视为通用准确率证明。