메뉴
契约治理三件套的「结构层」。判定一处改动是否破坏跨模块/跨服务公共契约的结构与语义（MySQL schema、Qdrant/ES 索引、MQ topic 与消息结构、OSS 路径、HTTP 接口、错误码），并据此列出必须同步的契约文档 + migration 清单。本 skill 只做「判定 + 列清单」，不核对同一物理值在多处是否逐字一致（那是值层，转 config-contract-sync），也不亲自改写文档内容（那是文档层，转 doc-maintenance-sync）。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
契约治理三件套的「值层」。核对同一个物理契约值（MQ topic/group、OSS bucket、消息字段名/别名、内部 HTTP 路径等）在 .env/.env.example/代码生效点/Java 对端多处是否逐字相等，找出配置漂移与死值，防止消息收不到/文件取不到。本 skill 只比对「同一个值在多处是否一致」，不判断结构/语义是否破坏对端（那是结构层，转 contract-guard），也不改文档。
指导 LLM 如何使用 toLink-Rag 项目的 MQ 消息中台进行消息收发、定义新消息类型以及处理多厂商适配逻辑。
当用户认为当前模块代码实现完毕，且当前分支应为 dev，需要从 dev 基于当前修改创建规范分支、提交并发起合并到 dev 的 GitHub PR 时使用；也用于发布收口，即直接创建 dev -> master 的 release PR，不新建 release 分支。适用于“从 dev 新建分支”“把当前修改提 PR”“实现完成创建 feature/refactor 分支并 PR”“发布新版本”“dev 合并 master”等交付收口场景。本 skill 是交付链终点，并在建分支/提 PR 前执行收口门槛：测试未过、契约文档失同步、acceptance 未提升者拒绝收口。
当用户要求把需求、功能、技术方案、架构改造、故障复盘、项目治理实践或实现过程写成博客/技术文章时必须使用；尤其适用于“写一篇博客”“生成技术博客”“把这个需求写成文章”“根据这个功能写博客”“把项目实现讲清楚”等请求。使用时要基于用户给出的需求和 toLink-Rag 当前仓库的真实代码、文档、契约、配置与测试证据完成分析，默认输出 Markdown 到 `.specs/blog/《博客名称》.md`。文章须采用「少量
把项目里已有的内部组件（如 MQ 中台、解析 pipeline、缓存层、对象存储）抽象成一份「项目自有 skill」，让 AI 每次接入都自动复用该组件的架构边界与约定。读组件真实代码，提炼「架构定位 / 职责边界 / 已落地清单 / 扩展点 / 红线」五要素，按统一原型生成 SKILL.md，登记到 .ai/skills/README.md 注册表并跑校验。
当用户要提 issue、登记 bug、记录新需求时使用；自动识别所属项目，生成结构化 issue 内容，先在 Linear 建主记录、再在 GitHub 建镜像，并双向回链。用户说"提个 issue""记一下这个 bug""把这个需求登记一下""同步到 Linear 和 GitHub""别再依赖 Linear 自动同步"时都应触发，即使没有明确说出"Linear"或"GitHub"。
| name | contract-guard |
| description | 契约治理三件套的「结构层」。判定一处改动是否破坏跨模块/跨服务公共契约的结构与语义（MySQL schema、Qdrant/ES 索引、MQ topic 与消息结构、OSS 路径、HTTP 接口、错误码），并据此列出必须同步的契约文档 + migration 清单。本 skill 只做「判定 + 列清单」，不核对同一物理值在多处是否逐字一致（那是值层，转 config-contract-sync），也不亲自改写文档内容（那是文档层，转 doc-maintenance-sync）。 |
| when_to_use | 当技术设计或代码实现改到 MySQL 表/字段、Qdrant/Elasticsearch 索引结构、MQ topic 或消息字段结构、OSS 路径规则、对外 HTTP 接口、错误码等公共约定，需要回答『这个改动会不会破坏对端、要同步哪些契约文档』时激活。触发示例：'这个改动会破坏公共约定吗'、'新增表字段要同步什么'、'改了消息结构对端受影响吗'、'加了错误码要更新哪些文档'。三件套切分：只是核对同一个 topic/bucket/字段名在 .env/代码/Java 多处取值是否逐字一致（值层）→ config-contract-sync；判定完拿到清单后要真正改写 docs/AGENTS 内容（文档层）→ doc-maintenance-sync；写/校验迁移本身 → alembic-migration。 |
在「技术设计」与「编码实现」阶段，确保改动不会悄悄破坏跨模块/跨服务的公共契约，
并按本项目按域拆分的契约文档与 CLAUDE.md §6 机器强制同步规则给出必须同步的清单。
本项目没有单一的 middleware_contract.md；契约分散在 docs/api/** 与若干 docs/internals/**。
| 契约面 | 代码位置 | 权威文档 |
|---|---|---|
| MySQL 表结构 / ORM | src/models/**.py | docs/api/schemas/mysql.md |
| Qdrant 向量索引（collection / named vector / payload） | src/core/qdrant_vector_storage/** | docs/api/schemas/qdrant.md |
| Elasticsearch 索引 | src/core/**（ES 入库阶段） | docs/api/schemas/elasticsearch.md |
| MQ topic / 消息结构 | src/core/mq/messages/** | docs/api/mq_contracts.md + docs/internals/mq.md |
| 对外 HTTP 接口 | src/api/routes/** | docs/api/http_contracts.md |
| 错误码 / 失败通知语义 | src/core/**（error_codes） | docs/api/error_codes.md |
| OSS 路径 / 桶 / 公私有 | src/core/**（object storage） | docs/internals/object_storage.md |
| 命名 / 配置 / DB 来源约定 | src/config.py 等 | docs/internals/naming_conventions.md |
| 解析任务流水线阶段契约 | src/core/pipeline/parse_task/** | docs/internals/parse_task_pipeline.md |
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 冻结）。逐项判断本次改动是否触碰公共契约（任一为「是」即需同步对应文档）：
python scripts/quality/check_docs_sync.py --staged。check_docs_sync.py --staged。三者按「同一改动的不同层面」分工，不重叠：
| 层面 | skill | 回答的问题 | 产物 |
|---|---|---|---|
| 结构层（本 skill） | contract-guard | 结构/语义/必填性变了没有？破坏对端兼容没有？该同步哪些契约文档？ | 判定 + 同步清单（不改文档） |
| 值层 | config-contract-sync | 同一个 topic/bucket/字段名/路径在 .env/代码/Java 多处取值是否逐字相等？ | 取值对照表 + 统一方案 |
| 文档层 | doc-maintenance-sync | 文档内容是否已落后于代码现状？ | 实际改写后的文档 |
docs/**、AGENTS.md 内容 → 转 doc-maintenance-sync 执行。config-contract-sync 核值。alembic-migration。