astroidal 是做什么的？
Astroidal 是一份 AI 代码审查地图、评分器和助手。它绘制出变更的爆炸半径，并根据可证明的内容进行评分。映射变更，搜索真实 Bug，然后对发现进行排名。图表和表格保存在文件中。聊天回复是一段简短、可粘贴的摘要性文字。
Bug 目录位于本文件同级的 references/review-lenses.md 中。在判断发现之前请先阅读它。该目录不在 .astroidal/ 文件夹内。
不要将 Astroidal 添加为依赖项。不要编辑 package.json、lockfiles、pyproject.toml、go.mod 或 Cargo.toml 来安装它。
运行
按以下顺序解析命令：
astroidal（如果已在PATH中）npx --yes astroidal
如果无法下载该包，且用户指向本地仓库，则运行 npx --yes <astroidal-包的路径> 或 node <路径>/dist/cli.js。
在每个仓库中安装一次该技能：
npx --yes astroidal init
使用 --global 参数可一次性为本机上的所有仓库安装：
npx --yes astroidal init --global
全局安装会在较新的 Astroidal 运行 graph 或 rank 时自动更新，前提是这些技能文件仍然是 Astroidal 所写入的。被编辑过的技能文件将保持不变，直到执行 init --force。再次运行 init 可刷新项目安装。
选择范围
首先运行一次 graph。阅读它打印出的范围说明。如果范围错误，请用下面的标志重新运行一次，此后不要再重新运行。
| 请求内容 | 命令 |
|---|---|
| 当前编辑，包括未跟踪的文件 | npx --yes astroidal graph |
| 当前分支或其拉取请求（当工作区不干净时） | npx --yes astroidal graph --base <默认分支> |
| 干净的特性分支 | npx --yes astroidal graph |
| 拉取请求编号或 URL | npx --yes astroidal graph --pr 12,18,24 |
| 所有打开的拉取请求 | npx --yes astroidal graph --open |
| 按作者、标签或基础分支筛选打开的拉取请求 | npx --yes astroidal graph --open --author 名称 --label 标签 --base 分支 |
| 当前拉取请求及其下方的栈 | npx --yes astroidal graph --stack |
| 单个提交 | npx --yes astroidal graph --commit SHA |
| 仅已暂存的变更 | npx --yes astroidal graph --staged |
| 未暂存的变更和未跟踪的文件 | npx --yes astroidal graph --unstaged |
批量操作是一张合并的地图。不要将它们作为独立的报告审查。
GitHub
仅在需要时调用 gh 获取审查所需的信息。地图已经完成了本地优先的读取，因此不要再次列出相同的文件、重新获取已存储的 diff，或轮询检查。发出少量针对性的调用是可以的，例如当标题、基础分支或正文缺失时使用 gh pr view。不要滥用 gh，不要评论拉取请求、批准它或请求审查者。
GitLab
仅在需要时调用 glab 获取审查所需的信息。地图已经完成了本地优先的读取，因此不要再次列出相同的文件、重新获取已存储的 diff，或轮询流水线。发出少量针对性的调用是可以的，例如当标题、基础分支或正文缺失时使用 glab mr view。不要滥用 glab，不要评论合并请求、批准它或请求审查者。
搜索 Bug
依次读取以下文件：
.astroidal/packets/bug-map.md.astroidal/packets/architecture.md.astroidal/packets/security.md.astroidal/packets/performance.md.astroidal/packets/ux.md.astroidal/packets/correctness.mdreferences/review-lenses.md（与本技能同级）
应用目录中的门禁（gate）、规范检查（spec pass）和标准检查（standards pass）。然后应用与“新增行”中文件匹配的每种语言章节。跳过其他语言章节。
覆盖 Bug 地图中的每个变更路径。从 Added lines 章节开始。该章节就是变更内容，每个拉取请求一个代码块。当 diff 是通过远程获取时，符号摘录可能为空；在栈中它只包含顶部。空摘录表示缺少上下文，而非空变更。
不要找到第一个可能文件就停止。对于“新增行”中的每个非测试源文件代码块：
- 读取整个代码块，包括当代码块提示更多内容在证据文件中时其下方的行。
- 根据目录检查该代码块，而不仅仅是与文件名匹配的类别。以下五个类别是最低要求。
- 当同一个文件列出多个拉取请求时，请审查每个代码块。映射的主体仅包含栈顶。
- 当代码块不足以确认或排除 Bug 时，打开文件。
- 对于每个变更的符号，检查地图中列出的一级调用者和被调用者，如果变更可能破坏它们。
特别关注以下情况：错误的分支、将 false 或空值视为缺失、差一错误或时区不匹配、失败后阻止重试的锁或状态、通过拼接构建的 URL 或查询、使用了错误身份的身份验证检查，以及一级调用者仍在使用旧方式的约定。高分值不是发现，也不能作为跳过代码块的借口。
搜索所有以下类别：
- 逻辑和边界情况：错误的分支、差一错误、吞掉的错误、空指针崩溃
- 数据丢失和状态：迁移、竞态、部分写入、过期缓存
- 损坏的约定：API、类型、路由、导出行为、模式不匹配
- 安全 Bug：权限漏洞、注入、密钥、不可信的信任边界
- UX 流程错误：死胡同、缺失错误状态、空状态、加载状态、导航故障
寻找重要问题。包中的线索是提示而非发现。代码异味、长文件、缺失测试或依赖项升级只有在目录的前置检查通过时才能算作发现。忽略格式、命名、注释、表扬、问题和未指明具体故障的重构。
编写发现
写入 .astroidal/findings.json：
{
"findings": [
{
"pr": 12,
"severity": "high",
"description": "一句话描述哪里出了问题。",
"path": "src/auth.ts",
"line": 12,
"quote": "从文件中复制的确切行内容",
"recommendation": "移除该 Bug 的具体变更。",
"category": "security"
}
]
}
severity 可以是 critical、high 或 medium，根据目录中的门禁判断。critical 指用户路径上的崩溃、数据丢失、权限绕过、注入或密钥泄露。high 指会导致实际错误结果、写入丢失、竞态或约定破坏的问题。medium 指现实边缘情况下会失败的问题。quote 是从新增行代码块、映射文件或其一级邻居中复制的准确一行。将 pr 设置为引入该行的拉取请求编号，如果是本地变更则省略。
说明哪里出了问题，指出符号名称，给出消除该 Bug 的变更。对于安全和架构问题，说明为什么那个变更有效。不要含糊其辞、重述引用的行或提交问题。只有在检查了所有非测试源文件的“新增行”之后，且无一包含重要 Bug 时，findings 数组才允许为空。
当变更文件因目录未显示的原因而属于同一组时，为组命名。图表会自行绘制目录，并以线表示导入。组适用于跨越这些的流程、特性或共享约定。
{
"findings": [],
"groups": [
{
"name": "Payment links",
"paths": ["apps/admin/lib/whatsapp.ts", "apps/admin/lib/proxied-link.ts"]
}
]
}
使用简短名称，并至少包含两个映射路径。当没有额外内容需要归组时，省略 groups。
然后运行：
npx --yes astroidal rank
如果 rank 因为引用或路径错误而丢弃某个发现，请修复该发现并再次运行 rank。不要发明一个替代 Bug 来保持计数。不要运行第三次 rank。
回复
在聊天中写一段简短的摘要。以一行可粘贴的文本开头：Astroidal {分数} · Passed 或 Astroidal {分数} · Fix first。然后指出最严重的问题以及两个输出路径：.astroidal/review.md 和 .astroidal/constellation.html。不要粘贴发现表格。不要重新创建图表。最终由人类决定是否合并。