🎮 AI 命令使用手册（8 条 workflow 速查）#

本篇是 用户视角 的 AI 命令手册——只讲 "在哪触发、怎么写命令、我会看到什么、失败了看哪里"。不讲 YAML 实现（那在 ai-automation / ai-review-strategy 两篇）。

适合收藏为浏览器书签，日常贴命令时回来查。

🗺️ 命令速查表（一眼看全）#

🔒 "OWNER / MEMBER / COLLABORATOR" 由 GitHub 的 author_association 字段判定。陌生访客（NONE / FIRST_TIME_CONTRIBUTOR）触发这些命令会被直接忽略——属于预期行为，不报错、不回复。

📖 Issue 生命周期的 3 条命令#

1. ai-triage — 新 issue 自动分类（无需命令）#

什么时候跑：任何人打开一个新 issue。

会看到什么：

👋 感谢提交 issue！

经过 AI 初步分析，我们给这个 issue 自动打上了以下标签：
`bug` `cli` `needs-reproduction`

可能还需要你补充：
- 完整的错误日志
- pnpm / node 版本
- 能复现的最小示例

维护者会尽快跟进！

---
<sub>🤖 This reply was generated by AI. Answers may be inaccurate —
please verify before acting on technical advice.</sub>

限制：

• 最多打 5 个 label（避免噪音）
• body 太短或含糊 → 自动追加 needs-reproduction
• 会根据 issue 正文语言自动切换中 / 英回复

失败了看哪里：Actions → "🤖 AI Issue Triage" → 最近一次运行的日志。常见原因：

• 403 Forbidden：仓库在组织里且组织禁用了 GitHub Models
• JSON parse failed：模型偶发输出畸形 JSON，workflow 会记 warning 但不报红，issue 无 label 即可手动补

2. @ai-bot <问题> — 上下文感知问答#

什么时候用：想让机器人基于 README + issue 上下文回答技术问题。

命令格式：

合法示例：

不合法 / 会被忽略：

会看到什么（约 10-20 秒）：

1. 你的评论上出现 👀 表情反应（workflow 开始跑）
2. AI 用一条新评论回答
3. 你的评论的 👀 反应变成 👍（表示成功）

AI 不会做的事：

• ❌ 不改代码 — 命令里让它改，它会回复 "请开 PR 或 ping 维护者"
• ❌ 不跨 issue 检索 — 只看当前 issue + README + 近 5 条评论
• ❌ 不执行命令 — 它不会跑 pnpm test，只会解读代码

失败了看哪里：

• 👀 反应一直不变 → Actions → "🤖 AI Assistant" 看 step 日志
• 返回 "Sorry, I don't have enough context" → 把相关代码片段贴到 issue 里再 @

3. ai-summary label — 长讨论串 TL;DR#

什么时候用：一个 issue 或 PR 超过 15 条评论、讨论分散，想生成结构化摘要。

怎么触发：给目标 issue 或 PR 打 label ai-summary（不是评论！）。issue 和 PR 都支持，共享同一套逻辑。

会看到什么（~30 秒）：

<!-- ai-summary-marker -->

📋 Summary: 用户在 @lhx-kit/offline 的哈希并发配置上遇到了 Node 18 兼容问题。

🗣️ Key points discussed:
- @alice 最早报告在 concurrency=16 时 Node 18 内存泄漏
- @bob 确认 Node 20 无此问题
- @maintainer 提议降默认值到 8

✅ Decisions / agreements reached:
- 默认 hashConcurrency 从 16 降到 8
- 文档里补说明

❓ Still open:
- 是否需要同时保留 env 开关

➡️ Suggested next step: 开 PR 改默认值 + 补文档。

---
<sub>Generated by AI. Remove the `ai-summary` label then re-add it to refresh.</sub>

关键特性：

• 发完 AI 评论，自动把 ai-summary 标签摘掉（状态即完成）
• 二次触发：取消标签 → 重新打 即会生成新一版，并替换旧总结评论（靠 HTML marker 识别）
• 不会在 issue 里堆多份总结

🔍 PR 生命周期的 4 条命令#

4. ai-review-gpt — GPT-4o 主审（自动）#

什么时候跑：PR opened / synchronize / reopened / ready_for_review。

谁能触发：PR 作者的 author_association 不是 NONE / FIRST_TIME_CONTRIBUTOR（陌生人 PR 不跑，防滥用）。

关注重点：正确性、安全、破坏性变更、测试覆盖。

会看到什么（~15 秒）：

## 🎯 Verdict
🟡 approve with nits

## ⚠️ Concerns
- `packages/cli/src/commands/dev.ts:42` — 新增的 `--watch` flag 没调用
  现有的 `validateProjectConfig`，可能跳过 schema 校验

## 💡 Suggestions
- 考虑在 README "CLI 命令" 表格里补充 `--watch` 的说明

## ✅ What looks good
- 命名一致，error path 有 graceful degradation

---
<sub>🤖 GPT-4o review via GitHub Models · Review is advisory only.</sub>

同一 PR 多次 push 会发生什么：新评论不会堆积，workflow 会更新已有的那条 marker 评论（identity via <!-- ai-review-gpt-marker -->）。

5. ai-review-llama — Llama 架构视角（自动）#

同样自动触发，同样 PR 条件，但模型换成 meta/llama-3.3-70b-instruct（Meta 的开源旗舰）。

关注重点：跨文件影响、文档覆盖、命名一致性。

会看到什么（约 25 秒）：

## 🧭 Cross-file / architectural observations
- The new `debugDump` helper in `packages/runtime/src/logger.ts` is exported
  but not re-exported from `packages/runtime/src/index.ts` — downstream
  consumers can't import it.

## 📝 Documentation & comments
- `formatTimestamp` lacks a TSDoc block describing the accepted `ts` formats.

## 🏷️ Naming & consistency
- `debugDump` mixes camelCase with verb+noun — fine — but other log helpers
  in this file use `create*` prefix. Consider consistency.

## 🔁 Potential ripple effects
- `packages/runtime/README.md` "Logger API" section would need a new row.

— 🤖 Llama 3.3 70B second-opinion via GitHub Models

6. ai-review-deepseek — DeepSeek 推理视角（自动）#

同样自动触发，同样 PR 条件，模型是 deepseek/deepseek-v3-0324。

关注重点：边界条件、推理链、测试覆盖缺口。这是三个 reviewer 中**最"adversarial"**的一个——专门挑你没考虑到的输入。

会看到什么（约 35 秒）：

## 🧠 Edge cases & invariants
- `formatTimestamp(ts)`: when `ts` is an invalid string like "hello",
  `new Date("hello")` produces `Invalid Date`, and `.toISOString()` throws
  `RangeError`. The `// TODO: handle invalid dates` comment acknowledges
  this but doesn't fix it.
- `debugDump(logger, payload)`: `JSON.stringify` throws on circular
  references — which is common for logger payloads that include DOM nodes.

## 🧪 Test coverage gaps
- No test in `packages/runtime/tests/logger.test.ts` exercises the new
  helpers. Smallest additions:
  1. `formatTimestamp(NaN)` should throw or return sentinel
  2. `debugDump(logger, {a: {b: <circular>}})` should not crash

## 🔢 Algorithmic / correctness concerns
- `ts instanceof Date ? ts : new Date(ts as any)` — the `as any` cast
  hides a type mismatch; `ts: string | number | Date` is already the
  right type, no cast needed.

## 🤝 Agreement check with other reviewers
- Confirms Llama's point about missing TSDoc (same root cause: helpers
  weren't designed with consumers in mind).
- Possible divergence with GPT — GPT said "formatTimestamp uses Date
  effectively"; I'd say "it uses Date UNSAFELY".

— 🤖 DeepSeek V3 reasoning lens via GitHub Models

为什么三个 reviewer 不重复：每个模型的 system prompt 刻意错位。GPT 负责正确性 + 安全，Llama 盯架构 + 文档，DeepSeek 刨边界。详见 ai-review-strategy §三模型 reviewer。

7. @bot-fix-lint — Biome 确定性自动修复#

什么时候用：PR 里 CI 挂在 biome lint 上，不想本地拉分支再 push。

命令格式：在 PR 评论 里（不是 issue）输入：

一行就够，不带参数。

谁能触发：只有 OWNER / MEMBER / COLLABORATOR。Fork PR 一律拒绝（安全考虑，fork 分支不能 push）。

会看到什么：

1. 你的评论出现 🔧 反应
2. workflow 跑 pnpm biome check --write + typecheck 兜底
3. 有改动 → 直接 commit & push 到 PR 分支（commit message: style: apply biome autofix）
4. 机器人回复一条评论告诉你改了几个文件
5. 没改动 → 回复 "Nothing to fix ✅"

重点（和 @ai-bot fix 的区别）：

• 不过 LLM，纯 Biome 确定性规则
• 直接 push 到你的 PR 分支，不会另开 Draft PR
• 幻觉风险为零——Biome 不会"顺手"改掉别的东西

失败了看哪里：

• refuse fork PRs 错误 → 你的 PR 来自 fork，请自己 rebase
• typecheck 失败 → autofix 会自动回滚（保持干净），回到你原本的状态

8. @ai-bot fix <指令> — AI 起草代码修改（Draft PR）#

这是最危险也最强大的命令，所以有 4 层安全门（见 ai-review-strategy §4 层安全门）。

什么时候用：issue 里已经定位到 bug / 小需求，想让 AI 起草一个补丁，人类来 review。

命令格式（在 issue 评论，不是 PR）：

好示例：

坏示例：

谁能触发：OWNER / MEMBER / COLLABORATOR。

会看到什么（~60-120 秒）：

重要约束：

• 永远开 Draft PR，不会自动 ready_for_review
• PR body 第一行必写 ⚠️ This PR was AI-generated
• Blocked 路径（不会被 AI 改写）：pnpm-lock.yaml · .changeset/* · 任何 dist/ · node_modules/
• 单次 diff 上限：超过 50 个文件或 2000 行会直接拒绝

失败了看哪里：

• 看 issue 里机器人的反馈评论，一般会说明降级原因
• Actions → "🤖 AI Code Fix" → 最近一次运行

📝 文档工作流的 2 条命令#

9. @ai-docs draft <topic> — 起草新文档#

什么时候用：想要一篇新文档（比如"如何写一个 Vite 插件"），但不想从空白 MD 开始。

命令格式（在 issue 评论）：

好示例：

谁能触发：OWNER / MEMBER / COLLABORATOR。

会看到什么（~60 秒）：

1. 评论出现 📚 反应
2. AI 生成一篇 Markdown 草稿（带 frontmatter text 作为 sidebar label）
3. 放在 apps/docs/docs/drafts/<slug>.md（drafts/ 是 AI 默认落盘目录）
4. 开 Draft PR，PR body 里贴大纲预览
5. 你去 review → 自己润色 → mark ready → merge

AI 起草的产物特点：

• 有完整的小标题层级（## / ###）
• 代码示例带语言标识（ts / bash）
• 末尾带 "📚 相关资料" 小节
• 但：链接、具体版本号、引用的仓库文件路径 经常是幻觉，必须人工 verify

10. @ai-docs polish <path> — 原地润色现有文档#

什么时候用：一篇文档读起来混乱、句子冗长、结构散，但内容本身没问题，想让 AI 重写而不改意。

命令格式：

好示例：

错误示例：

谁能触发：OWNER / MEMBER / COLLABORATOR。

会看到什么：

1. AI 读原文 + 整个 docs/ 目录结构（保证风格一致）
2. 生成一份完全替换的 Markdown
3. 在一个新分支里覆盖原文件
4. 开 Draft PR，diff 就是"旧版 → 新版"对比

AI 的润色原则（system prompt 里明确约束）：

• ✅ 保留所有代码示例原封不动
• ✅ 保留 frontmatter
• ✅ 保留 link anchors（URL 不变）
• ❌ 不新增内容（你没写的 AI 不会自己"补"）
• ❌ 不删减技术决策（只改叙述方式）

典型改进：

• 冗长从句拆短
• 专业术语统一
• 列表格式对齐
• 加总结小节

🚨 通用排错指南#

触发了没反应？#

1. 检查命令拼写：@ai-bot、@bot-fix-lint、@ai-docs 三个是不同 workflow，打错字不会回退
2. 检查位置：
   • @ai-bot / @ai-bot fix / @ai-docs → issue 评论
   • @bot-fix-lint → PR 评论
3. 检查权限：非 OWNER/MEMBER/COLLABORATOR 触发这 4 条命令会被静默忽略，不回复
4. 检查是否 bot 发的：机器人自己的评论会被过滤

看 workflow 失败日志#

对应名字：

超时 / 配额#

每条 workflow 都有 timeout-minutes 限制：

超过就自动终止，你会看到 Actions 页面那条 run 标红为 cancelled。一般是模型返回太慢，重新触发一次即可。

GitHub Models 公开仓库无官方硬限；私有仓库每天按 model 有配额（通常对个人项目够用）。配额耗尽 → AI 调用返回 429，workflow 会在评论里注明，过几小时重试。

我不想让 AI 碰某些文件#

编辑 .github/workflows/ai-code-fix.yaml，在这块加 regex：

const BLOCKED = [
  /^pnpm-lock\.yaml$/,
  /^\.changeset\//,
  /\/dist\//,
  // 自己追加 →
  /^packages\/cli\/src\/commands\/release\.ts$/,
  /^\.github\/workflows\//,  // 不让 AI 改 workflow
];

💡 最佳实践#

问问题的姿势#

• ❌ @ai-bot 这报错怎么办 → AI 看不到报错内容
• ✅ @ai-bot 下面这个 error 在 pnpm 9 + Node 20 下出现，可能原因？<贴完整堆栈>

起草 fix 的姿势#

• ❌ @ai-bot fix 这个问题 → 模型不知道改啥
• ✅ @ai-bot fix <在哪个文件> <要改成什么行为> <为什么>

Review AI 产出的姿势#

• 不要无脑合并 AI 的 Draft PR
• 重点 check：link 是否存在、version 号是否真实、引用的文件是否存在、引用的 API 是否真的在用
• AI 最容易幻觉的三个地方：版本号、链接、API 签名

📚 相关阅读#

• 🤖 ai-automation — 3 条基础 workflow 的 YAML 实现细节
• 🎯 ai-review-strategy — 5 条扩展 workflow 的设计哲学
• 🔧 gh-cli-guide — 用命令行管 label / review / merge
• CLI 参考 — 本地 lhx-cli 命令
• GitHub Models 官方文档