ql-link/linkrag/contract-guard

Contract Guard

目的

在「技术设计」与「编码实现」阶段，确保改动不会悄悄破坏跨模块/跨服务的公共契约， 并按本项目按域拆分的契约文档与 CLAUDE.md §6 机器强制同步规则给出必须同步的清单。 本项目没有单一的 middleware_contract.md；契约分散在 docs/api/** 与若干 docs/internals/**。

契约面与权威文档（必读，按改动涉及的面选读）

机器强制同步规则（违反会被 pre-commit / CI 拦截，见 CLAUDE.md §6）

• 改 src/models/**.py → 必同步 docs/api/schemas/mysql.md 且新增 migrations/versions/*.py。
• 改 src/core/mq/messages/** → 必同步 docs/api/mq_contracts.md + docs/internals/mq.md。
• 改 src/core/pipeline/parse_task/** → 必同步 docs/internals/parse_task_pipeline.md。
• migrations/db.sql 禁止修改（0001 baseline 冻结）。

检查清单

逐项判断本次改动是否触碰公共契约（任一为「是」即需同步对应文档）：

• [ ] 新增/改名/删除 MySQL 表或字段，或改了类型/默认值/索引/枚举取值？
• [ ] 改了 Qdrant collection 命名规则、向量维度、named sparse vector 名、payload 结构？
• [ ] 改了 ES index 名、mapping、文件级 document 结构？
• [ ] 新增/修改 MQ topic / group，或改了消息字段、别名、必填性、语义？
• [ ] 改了对外 HTTP 路由、请求/响应结构、状态语义？
• [ ] 新增/修改错误码或失败通知语义（回发 Java 的 parse_result 等）？
• [ ] 改了 OSS bucket / object key 拼接规则或公私有访问？
• [ ] 改了命名/配置约定（env key、Redis key/TTL 等通用规则）？

执行流程

1. 按改动涉及的契约面，读上表对应权威文档与代码现状。
2. 对每个面判定：复用现有约定 / 新增约定 / 破坏性变更（不向后兼容）。
3. 破坏性变更要显式标注对端影响（尤其 MQ 消息、错误码、HTTP 结构会波及 Java 侧）。
4. 列出机器强制同步项（mysql.md / migration / mq_contracts.md / mq.md / parse_task_pipeline.md）。
5. 收尾提示自检：python scripts/quality/check_docs_sync.py --staged。

输出要求

• 一张「契约面 × 判定（复用/新增/破坏）× 需同步文档」清单。
• 若全部复用：明确说明「未新增或破坏公共契约，无需同步」。
• 若新增/破坏：列出必须同步的文档与（如涉及 model）必须新增的 migration；标注对端是否需配合。
• 提示运行 check_docs_sync.py --staged。

边界（契约治理三件套的分工）

三者按「同一改动的不同层面」分工，不重叠：

• 本 skill 给出清单后，若要真正动手改写 docs/**、AGENTS.md 内容 → 转 doc-maintenance-sync 执行。
• 判定中若怀疑某个值两端对不上（而非结构变化）→ 转 config-contract-sync 核值。
• 要写/校验迁移本身 → alembic-migration。