gbrain-advisor

gbrain 顾问

约定： 参见 skills/conventions/brain-first.md。本 Skill 是知识库的主动发声者，负责告诉拥有者如何更好地运行它。

约定内容

本 Skill 保证：

• 只读。 gbrain advisor 从不修改任何内容。它基于现有知识库状态计算出一份按优先级排序的操作列表。
• 只打印，不执行。 你需要向用户展示发现的问题，并在运行任何修复前征得同意。每个决定都由用户做出。
• 有限提醒。 按既定节奏运行，只呈现有变化或严重的问题；对于已被忽略的低严重度项目，不要每次运行都重复提醒。

何时运行

• 用户询问“怎样才能更好地利用这个知识库？”时按需运行。
• 通过下方的 cron 配方按每周节奏运行（即使是闲置的知识库，也会收到“如何更好地运行它”的提示）。
• 每月，顾问还会给出备份覆盖情况的结论（gbrain backup status，即哪些知识仓库没有 git 远程仓库）；如有任何警告，需转告用户。

运行方法

gbrain advisor --json

退出码即严重度门槛（E2）：0 表示正常，1 表示警告，2 表示严重。JSON 载荷的结构为 { version, generated_at, worst, findings: [...] }。每条发现包含：

• severity — critical | warn | info
• title — 一行说明其重要性
• fix.command_argv — 修复该问题的确切命令（结构化 argv）
• fix.dispatch_id — 当该修复可安全通过 --apply 运行时出现

如何处理发现的问题

1. 阅读发现的问题，严重度最高的优先。

2. 用用户习惯的渠道和语气，向其概述排名前 1–3 的问题。优先说明所有 critical 项（例如待执行的迁移）。

3. 对每一项，展示 fix.command_argv，并询问用户是否运行。

4. 如果用户同意，且该发现包含 fix.dispatch_id，你可以在明确确认后在本地运行它：

   gbrain advisor --apply <dispatch_id>
   

   --apply 仅限本地使用，以结构化 argv 方式运行修复（不经过 shell），并会先进行确认。没有 dispatch_id 的发现不能自动运行——需在用户同意后由你自行运行其 fix.command_argv。

5. 绝不运行用户未批准的修复。

Cron 配方（每周检查）

通过 cron-scheduler Skill 安装每周任务。提示词务必保持精简——任务只需读取本 Skill 并运行顾问：

• 计划： 每周一次，选择一个尊重静默时段的时间（例如周一本地时间 09:00）。
• 任务提示词： Read skills/gbrain-advisor/SKILL.md and run gbrain advisor --json. If anything is critical or new since last run, ping me with the top items and the exact fix commands. Ask before fixing.
• 幂等性： 顾问只读，因此重复触发也无害。

顾问会记录本地运行历史，因此每次触发时，你可以告诉用户自上次运行以来新增的内容，而不是重复列出全部内容。

输出格式

向用户呈现顾问的发现时，应先说明严重度，并保持便于快速浏览：

🧠 gbrain checkup — 2 things worth your attention

CRITICAL  Schema migrations are pending.
          Fix: gbrain apply-migrations --yes   (want me to run it?)

WARN      gbrain 0.44 is available (you're on 0.43).
          Fix: gbrain upgrade

• 每条发现单独一个区块，严重度最高的优先。
• 始终展示确切的 fix 命令，并在运行前征得同意。
• 如果没有紧迫问题，用一行话说明即可（“知识库状态良好”）——不要人为制造工作。

失败时的处理

对于任何 gbrain 错误 code、退出码、[AGENT] 区块或通知区块，请遵循 Agent 操作协议。针对本 Skill 的具体说明如下：

• critical 发现（待执行的迁移）附带的修复命令类似 gbrain apply-migrations --yes：运行前需询问用户；没有 dispatch_id 的发现不能自动运行。
• 若 gbrain advisor 无法连接知识库（出现 GBRAIN_DB_ACCESS 标记）：应转交 db-repair Skill 处理，而不是报告“没有发现问题”。

反模式

• 未经询问就执行修复。 Advisor 按约定为只读。未经用户明确同意,绝不要运行 --apply(或任何 fix 命令)。
• 把原始 JSON 直接丢给用户。 用用户能理解的语言转述检测结果,先说最重要的内容。
• 每次运行都反复提醒已忽略的低严重级别项。 使用“自上次运行以来的新增项”增量,尊重用户之前的不处理选择。
• 把 info 当作 critical 处理。 只对 critical 级别的检测结果(待执行迁移)进行阻断或强烈提醒。info 只是温和的提示。
• 通过 MCP 调用 advisor 操作获取工作区安装状态。 通过 MCP 时,advisor 只返回大脑状态信号;未安装 Skill 的检测结果属于本地命令行的范畴。