| name | ai-code-review |
| description | 用于对本仓库 PR、commit、diff 或代码变更做 AI Code Review；当用户要求 review PR、review commit、review diff、代码审查、CR 规范检查、AI CR 或检查变更是否符合 AgentBlog 分层与模块边界时使用。 |
| license | Proprietary |
| compatibility | {"agent":"*"} |
| metadata | {"language":"zh-CN","scope":"ai-code-review","repo":"BqLee-AI/AgentBlog"} |
ai-code-review
这个 skill 用来主动审查 AgentBlog 的代码变更。它不是通用语言 checklist，也不是替代维护者判断的自动结论。
目标是让 review 基于本仓库真源、当前 diff 和模块 reference，找出真实 bug、分层边界破坏、安全/计费/鉴权风险、契约漂移、测试缺口和需要维护者讨论的设计问题。
先读什么
README.md、docs/design/README.md（文档导航）- 相关
docs/design/*.md；设计文档是长期真相层（后端 00~14、前端 frontend/*）
- PR / commit / diff 元信息、changed files、base/head、用户指定关注点
- 关联 issue、PR 评论和 CI 结果
- 涉及
apps/api/** 时，先读 references/api/overview.md；后端分层、计费、鉴权、MCP、流式各有场景索引
- 涉及
apps/web/** 时，先读 references/web/overview.md；前端 page/feature/api/lib 分层与契约边界有场景索引
- 涉及
packages/shared/** 时，按 shared 契约边界审查（见 references/shared/overview.md）
- 需要统一输出格式时读
references/shared/review-output.md
不要一次性加载所有模块细则。先用 changed files、imports、调用形态和 diff 内容选择相关 reference。
后端变更常同时涉及多个边界：例如 Credits 计费可能同时触及 modules/credit/**（原子扣减）、modules/api-key/** 或 modules/agent/**（鉴权主体）、mcp/** 或 ai/**（计费嵌入点）、lib/errors.ts（402 错误）。不要只按单一路径审查，要顺着请求链路和计费链路追完。
Review 流程
- 明确审查对象：PR、commit range、单个 commit、工作区 diff，或用户粘贴的 patch。
- 列出 changed files，并按路径和变更类型归类（后端 routes/modules/middlewares/lib/ai/mcp、前端 pages/features/api/lib、shared 契约）。
- 读取相关真源和 overview reference，必要时再读 overview 里指向的场景细则。
- 对 diff 做证据驱动审查，只对能从当前代码、设计文档、分层规范或验证结果证明的问题给 finding。
- 如果建议来自通用最佳实践，但仓库真源没有支撑，标为 question / residual risk，不要写成 must-fix。
- 对较新框架、库 API 或工具行为（Vercel AI SDK、MCP SDK、Drizzle、Hono 版本特性），先看 lockfile、已安装版本、现有代码和官方文档；不要只靠模型记忆。
- 用普通 Markdown 输出 findings、open questions、验证建议和残余风险；需要贴到变更行的意见才使用
::code-comment{...}。
Finding 分类
must-fix：真实 bug、安全问题、计费超扣、鉴权绕过、契约破坏、仓库红线（slug 不可变、API Key 不可逆存储、对话不落库、原子扣减）、关键测试缺口。should-fix：范围内、成本低、证据充分的质量问题。needs-discussion：会改变范围、设计、模块边界、契约或验收口径的问题。defer：有价值但超出当前 PR，应进入后续 issue。not-applicable：通用建议不适用于当前仓库、当前版本、当前非目标或被现有设计明确排除。
不要因为发现“可以更好”就输出 finding。Code Review 优先报告会影响正确性、边界、安全、计费、契约、可维护性或验证可信度的问题。
仓库特有红线（must-fix 倾向）
AgentBlog 有几条需求强约束，违反即 must-fix：
- slug 永久不可变：文章一旦发布，
slug 不允许在任何更新路径被修改（见 06）。update_post 工具和 PATCH /api/posts/:id 都必须忽略或拒绝 slug 字段。
- API Key 不可逆存储：库里只能存 SHA-256 哈希，明文仅签发时返回一次，列表/详情绝不返回明文（见 07）。绝不能明文或对称加密入库。
- 在线对话不落库：
/api/chat 与 MCP 流程禁止向 message/conversation 表写记录——v1 根本不建这些表（见 10）。出现 db.insert(messages) 之类即红线。
- Credits 原子扣减防超扣：扣减必须用条件 UPDATE（
WHERE credits >= amount）+ 事务，不能「先查后扣」；余额不足必须返回 402（见 08）。
- 双鉴权体系互不通用：
/api/* 走 JWT（authMiddleware），/mcp/* 走 Header API Key（apiKeyMiddleware），不要叠加或混用（见 09 §1.1）。
- 依赖方向铁律：后端
routes → services → repositories → db 不得反向，@agentblog/shared 是契约不是依赖环；前端 pages → features(use*) → api → lib(request) → shared 不得反向。
- 契约单一真相源：跨前后端复用的类型/Zod schema/枚举/错误码只在
@agentblog/shared 定义一次，后端 DTO 与前端表单都从 shared 引入，不在前端重写。
- 不提交 secrets / runtime 数据：
.env、data/（SQLite 文件、上传文件）不得进入提交。
输出要求
默认输出普通 Markdown，不输出 JSON、XML、findings object 或其他结构化 review schema。
每条 finding 必须包含：
- 级别：
must-fix / should-fix / needs-discussion / defer / not-applicable
- 文件和行号：尽量指向 diff 中最小可行动位置
- 规则来源：设计文档编号（如
docs/design/08）、分层规范（docs/design/02）、reference overview 或现有代码模式
- 证据：当前 diff 中触发问题的具体代码或行为
- 影响：为什么这会破坏分层边界、行为、契约、计费、安全或验证
- 建议修法：可执行的修改方向
- 验证建议：最小有效验证命令或人工检查点
如果没有 finding，明确说“未发现必须修改的问题”，并说明仍未覆盖的范围或未运行的验证。
只有当反馈需要直接贴到 changed line 时，才发出 ::code-comment{...} inline comment 指令。没有可行动行级意见时，不要发任何 inline comment 指令。
关联 reference
- 输出格式：
references/shared/review-output.md
- 后端分层与场景索引：
references/api/overview.md
- 前端分层与场景索引：
references/web/overview.md
- 共享契约边界：
references/shared/overview.md
未来新增模块（如独立的 worker、CLI 工具）时，只在对应 overview 里加入导航，不把细则塞回 SKILL.md。
边界
- 本 skill 负责主动 review diff；处理已有 PR 评论或 CI 评论时，直接在 review 中引用，不另开工作流。
- 不自动修改代码，除非用户明确要求从 review 转入修复。
- 不接入 CI、GitHub bot 或自动阻塞 merge。
- 不把未确认想法写成仓库红线；需要长期沉淀时建议进入
docs/design/ 或后续 issue。
