LinkRag

契约治理三件套的「值层」。核对同一个物理契约值（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"。

当用户提出新需求、口头想法、初步框架，或要求"写个 brief / 需求理解 / 业务分析 / 先理清楚需求"时激活；输出面向开发者的 brief.md，覆盖需求摘要、业务流程、涉及模块与影响面（含概念数据模型，但不到物理 schema 与 how）、风险、待确认问题五章；支持开发者审阅后通过对话迭代修订，直到开发者确认冻结，作为后续 acceptance.feature 生成的输入。若用户已基于 brief.md 提出修改、补充、疑问、回答待确认项，继续用本 skill 做迭代收敛。

仅当 brief.md 已由开发者确认冻结后，基于 brief.md 生成 Gherkin 格式的 acceptance.feature 验收契约，描述每条业务规则在"Given/When/Then"下的可机器验证断言；该文件后续由 pytest-bdd 等框架直接消费为自动化测试。本 skill 不输出散文 PRD（旧版 requirement.md 已废弃）。若用户尚未提供冻结的 brief.md，禁止使用本 skill。

编写、校验 Alembic 迁移，保证 schema 演进唯一通过「ORM 模型 + 迁移链」落地，不触碰冻结的 migrations/db.sql baseline。

契约治理三件套的「结构层」。判定一处改动是否破坏跨模块/跨服务公共契约的结构与语义（MySQL schema、Qdrant/ES 索引、MQ topic 与消息结构、OSS 路径、HTTP 接口、错误码），并据此列出必须同步的契约文档 + migration 清单。本 skill 只做「判定 + 列清单」，不核对同一物理值在多处是否逐字一致（那是值层，转 config-contract-sync），也不亲自改写文档内容（那是文档层，转 doc-maintenance-sync）。

「需求 → 交付」链的编码执行站。把已冻结的 brief.md / acceptance.feature（L3 还有 technical_design.md）落地为真实代码，并在 L3 或实现偏离方案时产出 implementation_report.md。核心纪律：编码中发现 spec 缺口必须先回写 spec 再继续，不允许静默改代码绕过、让 spec 与代码脱节。只要进入"按方案写代码 / 开始实现这个需求 / 可以编码了"的阶段就用本 skill。无冻结 spec（只有口头需求）→ 先转 brief-generator 收敛；代码写完 → 转 run-all-tests + code-review-and-quality，最终经 branch-pr-workflow 提 PR。

在用户明确要求生成技术方案、技术实现文档或 technical_design.md 时激活；输入源为同目录下的 brief.md 和 acceptance.feature，必须先校验二者存在且 acceptance.feature 已冻结，然后在同目录产出 technical_design.md，并严格基于真实代码、组件文档和公共契约进行设计。原 requirement.md (散文 PRD) 已废弃，不再作为输入。

从日志/现象定位 RAG 解析与召回链路故障，按「定位阶段 → 区分配置漂移还是数据不一致 → 给修复 + 重置/回滚动作」的路径收敛，输出可执行结论。

契约治理三件套的「文档层」——真正动手改写文档的那一个。当 AGENTS.md/CLAUDE.md、docs/api、docs/internals、docs/ops、docs/contributing.md 落后于代码现状时，按文档映射读取最小必要文档并执行同步更新，保证项目文档自动维护。本 skill 负责「改写文档内容」；它不判断某个改动是否破坏公共契约（那是结构层，转 contract-guard），也不核对同一物理值在多处是否一致（那是值层，转 config-contract-sync）。

在进入最终提交/合并前执行五维代码审查并输出分级结论。用于功能实现完成后、测试交付完成后、以及任何准备发布前的质量门禁。

对照原始需求，客观判断一项功能是否真正实现完成。从需求覆盖、验收对齐、正确性边界、契约集成、测试证据、范围偏离六个维度独立取证，输出可追溯的完成度结论与缺口清单。两种入口：对话上下文里的功能实现用子 agent 独立复核（避开实现者自证偏差）；审核 PR 用当前 agent 直接读 diff。

在任何需要改代码的需求进入开发链之前做一次轻量分诊，按改动性质判定 L1/L2/L3 车道，决定走快车道还是全链，并把后续交接给对应 skill。本 skill 不产出文档，只给出"车道结论 + 下一站"。属于整条「需求 → 交付」链的入口前置站。

当仓库内创建、删除、移动、重命名源码、脚本、配置、测试或 Agent/Skill 等核心项目目录，并且这些变更影响项目结构展示时，要求同步更新根目录 AGENTS.md 中的“当前项目结构”树。docs 目录下任何文件或目录结构变化都不触发本 skill。

自动化测试生成工作流。为 FastAPI/RAG 后端生成 pytest 单测/集成/冒烟测试，强调 Mock 隔离、分层策略与边界覆盖。

代码高质量注释生成工作流。为 Python 项目生成恰到好处的 Docstring 注释，强调全局上下文感知、注释粒度控制和 PEP 257 规范。

MySQL 建表与字段规范（面向文档解析/任务类业务）。统一命名、索引、字段类型、时间戳、引擎字符集与注释要求，便于研发与 DBA 评审落地。

运行当前仓库 tests 目录下的全部 pytest 测试并直接返回结果报告，不落本地测试文档。适用于用户要求“运行当前所有测试”“跑全量测试”“把 tests 全跑一遍并告诉我结果”等场景。

FastAPI Swagger 中文注解生成工作流。为 Controller 路由和 Pydantic 模型生成符合企业级规范的中文 Swagger 注解。