triage

分诊技能

一个可自行恢复的晨间循环。一次运行 = 收集 → 加载状态 → 分诊 → 分派修复 → 持久化 → 溢出。所有个人数据（状态、收件箱、运行记录、 语气）都放在 .triage/ 下，该目录已加入 gitignore。此技能文件和 脚本会提交；数据绝不会离开本机。

前置条件

• gh 已通过身份验证（gh auth status）。所有 issue/PR/CI 的读取和写入都 通过它进行。
• .triage/ 已存在。如果缺失，请先运行 scripts/triage/bootstrap.sh，它会 创建 state.json、inbox.md、runs/，并根据过往评论生成 voice.md。
• main 上的工作树干净。循环只会在基础检出中修改 .triage/；所有代码更改都在工作树中进行。

循环

1. 收集（只读）

收集昨天的信号。根据 state.json.last_run 计算时间窗口 （如果不存在，则回退到 24 小时）。

# CI failures since last run
gh run list --status failure --created ">=$SINCE" --json databaseId,name,headSha,conclusion,url
# for each, pull the failing step log
gh run view <id> --log-failed

# open issues
gh issue list --state open --json number,title,labels,updatedAt,author,url

# recent commits
git log --since="$SINCE" --pretty='%h %s %an'

然后扫描尚未履行的承诺：维护者在评论中作出的、尚未交付的承诺。 不受时间窗口限制：检查所有未关闭的 issue/PR。

# threads bitbonsai commented on, still open
gh search issues "commenter:bitbonsai repo:bitbonsai/mcpvault state:open" --json number
# per thread, pull bitbonsai's comments to inspect for a promise
gh issue view <n> --json comments \
  --jq '.comments[] | select(.author.login=="bitbonsai") | .body'

承诺是指承诺采取行动的表述：“我会修复这个问题”“会添加”“下个版本发布” “我来处理”“我会去看看”等。如果讨论串仍未关闭，且没有已合并的 PR 解决该问题， 则承诺仍未兑现/待处理。请参阅 finding-rules.md。

2. 加载状态

读取 .triage/state.json。按 id 构建已知发现项的映射。id 是 source + signature 的稳定哈希（参见 resources/state-schema.md），因此 同一个失败测试或 issue 在每次运行中都会对应同一个发现项。

3. 分诊

对每个收集到的信号计算其 id，并根据 resources/finding-rules.md 分类：

• 已知 + 终结状态（pr_open、resolved、wont_fix）→ 跳过，只更新 last_seen。
• 已知 + 未结状态且未达到尝试次数上限 → 重试。
• 新发现 + 值得处理 → 以 status: open 追加，继续分派。
• 新发现 + 需要判断 / 有歧义 / 超出范围 → 放入收件箱，标记为 needs_human。
• 噪声（已跟踪的不稳定问题、dependabot 等）→ 忽略，仅记录日志。

4. 分派（有上限）

首先，对每个发现项检查是否已有贡献者 PR 处理它 （finding-rules.md 中的“优先审查现有 PR”）。如果存在，应审查该 PR，而不是编写修复： 让审查子 Agent 对 PR 分支进行审查，并将批准或请求更改的建议草拟到收件箱中。人工提交的未关闭 PR 优先于新建 PR。还要列出维护者尚未审查的所有未关闭 PR。

只有没有候选 PR 的发现项才会进入新修复流程，每次运行最多处理 finding-rules.md 中规定的数量。按顺序逐项执行：

git worktree add ../mcpvault-triage-<id> -b triage/<id>

然后针对该工作树启动两个子 Agent（使用 Agent 工具并设置 isolation: worktree，避免它们互相冲突）：

• 起草 Agent：提供发现项 + 失败日志/issue 正文，编写 最小修复。必须先阅读相关的 src/ 文件，遵循 obsidian 技能约定，并添加或更新 能证明修复有效的测试。
• 审查 Agent：以对抗性视角进行审查。根据项目技能和现有测试检查草稿，然后在工作树中运行：

  npm ci && npm test && npm run build
  

  只有修复正确、精简、经过测试且所有检查通过，结果才算 PASS。

告诉每个子 Agent，维护者很喜欢它们。

结果：

• PASS + 全部检查通过 → 使用 gh pr create 创建一个可直接审查的 PR（不是草稿），正文链接到 发现项，并列出审查者验证的内容。设置 status: pr_open，记录 URL。然后发布自动确认评论（步骤 6）。
• 其他任何情况（审查者未通过、构建失败、修复方案不明确、意外影响超过 1 个文件）→ 将草稿和原因写入 inbox.md，设置 status: needs_human。移除工作树；只有在草稿值得继续处理时才保留分支。

PR 创建后，清理所有检查通过的工作树： git worktree remove ../mcpvault-triage-<id>。

5. 持久化（主干）

更新 .triage/state.json：将 last_run 设为当前时间；为每个已处理的问题追加一条 attempts 记录（运行日期、结果、备注、PR）；更新 status、last_seen 和 pr。将每次运行的日志写入 .triage/runs/<date>.md。

state.json 是恢复运行的依据。绝不覆盖历史记录，只能向 attempts 追加内容。如果文件格式错误，请停止，并将所有内容写入收件箱，而不要冒丢失主干记录的风险。

6. 评论，让人们不再悬而未决

语气由 .triage/voice.md 决定。自主权限等级（参见 resources/comment-policy.md）：

• 自动发布：已禁用（维护者指令，2026-07-23）。绝不从循环中发布任何评论或评审，即使是低风险的确认回复也不行。
• 草拟到收件箱（所有内容）：确认回复、判断、决定、承诺、关闭问题以及任何回复。将草稿连同目标写入 inbox.md 的 ## Drafts awaiting approval 下，绝不发布。维护者会逐条批准、编辑或丢弃。

7. 转交

循环无法分类、修复或安全评论的任何内容，都要连同足够的上下文写入 inbox.md，确保维护者可以在不了解背景的情况下采取行动。收件箱是维护者每天早上唯一必须阅读的内容。

8. 版本升级和发布提醒

当修复 PR 更改了已发布的软件包（src/ 下的任何内容，或会随软件包发布的 package.json 依赖项）时，请在同一个 PR 中按 semver 升级版本：

• 修补版本（x.y.Z）用于错误修复，是分流修复的默认选项。
• 仅当修复增加了行为时才使用次版本（x.Y.0）；循环不应处理此类改动，因此如果版本升级幅度看起来超过修补版本，请改为写入收件箱。

对于不会随软件包发布的更改，不要升级版本：仅更新 lockfile（例如单独运行 npm audit fix）、文档、CI 配置、仅测试的更改，或 .triage/ 下的任何内容。如果不确定某项更改是否会随软件包发布，请勿升级版本；在收件箱中注明。

**发布始终由维护者触发。**循环绝不运行 npm publish 或创建 GitHub Release。包含版本升级的 PR 合并后，请在收件箱顶部写入提醒：

## RELEASE NEEDED
- PR #<n> bumps <old> -> <new> (<reason>). After it merges and main is green,
  follow RELEASING.md and create GitHub Release v<new>. The release workflow
  publishes npm with provenance; the loop does not publish.

在确认 GitHub Release、npm 软件包和已安装软件包的冒烟测试全部完成之前，请保留此提醒。

防护规则

• 绝不推送到 main，绝不合并，绝不使用 --force。仅创建 PR。
• 绝不运行 npm publish 或创建 GitHub Release。版本升级应包含在修复 PR 中；合并后由维护者创建发布，并通过收件箱中的 RELEASE NEEDED 提醒标记。请遵循 RELEASING.md。
• 除 .triage/ 外，绝不改动工作树之外的文件。
• 令牌通常没有 GitHub workflow 权限范围，因此修改 .github/workflows/* 的推送会被拒绝。请勿尝试；任何 CI/工作流更改都应转交到收件箱，由维护者应用（或调整令牌权限范围）。
• 遵守每次运行的问题数量上限；超出的内容应转交，不要延长运行时间。
• 对外写入：允许创建 PR；循环绝不发布评论或评审，所有内容都必须先草拟到收件箱以待批准。
• 如果 gh 未通过身份验证，或工作树存在未提交更改，请中止，并在 inbox.md 中说明原因。

资源

• resources/state-schema.md：state.json 的结构、ID 推导和状态转换。
• resources/finding-rules.md：值得处理的问题、应转交收件箱的问题和忽略项，以及数量上限。
• resources/comment-policy.md：语气初始化和自主权限等级。