人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本指南以 gbrain 官方技能 skills/gbrain-advisor/SKILL.md 为骨架结合仓库内 CLI 入口、12 个采集器collector、apply 安全模型与 MCP 门控的源码实现展开。读完你将掌握如何按需/按周期运行gbrain advisor给大脑做体检如何读懂 JSON 契约与退出码语义如何安全地通过--apply落地单个修复以及如何用 cron 技能搭起每周大脑检查的自动化流程。一、gbrain advisor 是什么大脑的主动式教练gbrain 是一个带知识图谱、嵌入检索、schema pack、minion 后台任务与 MCP 服务面的个人大脑系统。它体量庞大、状态面众多版本是否漂移、数据库 schema 是否落后、后台任务是否卡死、嵌入覆盖率是否不足、配置是否存在设置异味setup smells、技能包是否已安装——这些状态平时散落在各处容易积小患成大患。gbrain advisor就是专门解决这个问题的只读体检命令它从既有大脑状态出发计算出一张按严重度排序的高杠杆行动清单每条行动都带有severitycritical|warn|infotitle一行为什么它重要fix.command_argv修复它的确切命令结构化 argv而非 shell 字符串fix.dispatch_id当该修复可安全地通过--apply落地时给出配套的gbrain-advisor技能即本指南对应的 skills/gbrain-advisor/SKILL.mdfrontmatter 中mutating: false把这条命令包装成大脑的主动语音它按节奏典型为每周运行 advisor把最重要的 13 条发现以用户自己的语气推给大脑所有者并永远先询问、后执行。技能约定遵循 skills/conventions/brain-first.md 的brain-first惯例体系。技能声明了五类典型触发语Agent 遇到这些问法时应主动拉起 advisorwhat should I do to get more out of gbrain is my brain set up right gbrain advisor advise me on my brain weekly brain checkup1.1 技能契约Contractskills/gbrain-advisor/SKILL.md 明确承诺三条铁律也是理解整个设计的前提只读Read-onlygbrain advisor本身绝不改动任何状态它只是从既有大脑状态计算一份排名清单。打印、绝不执行Print, never executeAgent 把发现 SHOW 给用户并 ASK 之后再考虑运行修复用户拥有每一个决策。有界唠叨Bounded nagging按节奏运行时只呈现新出现的或关键的内容被用户无视的低严重度项不会每次运行都重复轰炸。这三条契约在源码层面被严格落实CLI 入口 src/commands/advisor.ts 顶部注释写明 The advisor itself never mutates.--applyis the only path that runs a fix且--apply也要过 TTY 确认非交互终端直接拒绝见下文安全模型。二、什么时候跑按需、每周、每月SKILL.md 给出了三个触发时机时机触发方式说明按需用户问 how do I get more out of this brain?即时执行一次完整体检每周cron 配方见第五节即使大脑看起来很闲也会收到一条如何把它运行得更好的提示每月gbrain backup status额外上报备份覆盖率结论——即哪些知识仓库没有 git remote本地裸奔任何 warn 都要转述给用户月度的备份覆盖率结论在源码中由collectBackupCoverage采集器实现见第四节它复用 src/core/backup/coverage.ts 的getBackupStatus与 src/core/backup/status-file.ts 的backupNagGate且有一个硬性总开关backupCheckDisabled()——关闭后该采集器在计算与所有渲染通道全部静默。三、运行方式与 JSON 契约3.1 三种 CLI 形态src/commands/advisor.ts 定义了三种形态--help输出可以直接看到gbrain advisor # 人类可读的排名清单agent-readable 渲染 gbrain advisor --json # 结构化 findingscritical 时退出码非 0E2 gbrain advisor --apply finding-id # 运行某一条发现的修复本地专用、先确认E53.2 退出码即严重度闸门E2CLI 的退出码由exitFor()映射这是 SKILL.md 强调的severity gate// src/commands/advisor.ts function exitFor(report: AdvisorReport): 0 | 1 | 2 { if (report.worst critical) return 2; if (report.worst warn) return 1; return 0; }退出码含义0干净clean大脑健康1有 warn警告2有 critical关键测试 test/advisor-cli.test.ts 对这条语义做了端到端断言worst critical时退出码为2worst warn如仅 ontology conflicts时退出码为1。3.3 JSON payload 结构--json输出的是整个AdvisorReport类型定义见 src/core/advisor/types.ts{ version: 0.46.x, generated_at: 2026-09-20T04:30:00.000Z, worst: warn, findings: [ { id: pending_migration, severity: critical, title: Schema migrations are pending — run them before relying on newer features., detail: Newer gbrain code assumes the latest schema; an un-migrated brain can fail or under-perform., fix: { command_argv: [gbrain, apply-migrations, --yes], dispatch_id: apply_migrations }, collector: migration, ask_user: true } ] }每个 finding 的关键字段字段说明id稳定 ID如version_drift、pending_migration、stalled_job:nameseveritycritical|warn|infotitle一行为什么重要detail可选补充上下文fix.command_argv结构化 argv如[gbrain,apply-migrations,--yes]绝非 shell 字符串无机械修复时为nullfix.dispatch_id仅当该修复可安全经--apply白名单执行时出现collector由哪个采集器产出ask_user是否必须先问用户workspace_dependent为true时该发现依赖本地 workspace如已安装技能MCP 远程端会丢弃见第七节四、十二大采集器每条发现从哪来gbrain advisor的发现不是拍脑袋生成的。运行核心 src/core/advisor/run.ts 维护了一个写死的 v1 采集器清单COLLECTORS数组顺序即确定性排序的次级键export const COLLECTORS: AdvisorCollector[] [ collectVersion, // 版本漂移 collectMigration, // 待执行 schema 迁移 collectSchemaPack, // schema pack 可解析性 collectStalledJobs, // 卡住的后台任务 过期同步 collectUsageShape, // 大脑健康 vs 使用嵌入覆盖率/孤儿页/死链 collectSetupSmells, // 配置/设置异味 collectUninstalledBrainPack, // 大脑内置而未安装的技能包 collectUninstalledBundled, // 推荐捆绑技能未安装 collectChronicle, // Life Chronicle本体冲突 时间线覆盖缺口 collectMcpClientFit, // MCP 客户端表面(right-sizing)与 STARTER_OPS 漂移 collectBackupCoverage, // 备份覆盖率 collectWritebackConsent, // 环境写回ambient writeback同意提示 ];排序规则rankFindingscritical warn info同级按采集器顺序稳定排序info尾部默认上限 10 条infoCap避免把 Agent 淹没在低优先级的唠叨里。每个采集器在各自的 try/catch中运行——单个采集器抛错只贡献零条发现绝不让整个报告失败。下面逐个展开每条都给出触发条件、严重度与修复命令以源码为准。4.1 版本漂移version—— warnsrc/core/advisor/collect-version.ts 读取更新缓存而非直接联网保证 advisor 在 cron 中快速、安全缓存由gbrain check-update/ 自升级刷新路径在带外刷新。经 src/core/self-upgrade.ts 的pendingUpgradeVersion(runningVersion, now)判定只有缓存新鲜、标记为upgrade_available、且严格新于正在运行的版本时才上报。idversion_drifttitlegbrain latest is available — youre on running.fixgbrain upgrade4.2 待执行迁移migration—— critical唯一的关键信号src/core/advisor/collect-migration.ts 调用hasPendingMigrations(engine)。这是 SKILL.md 明确指出的唯一 critical 项未迁移的大脑可能缺少新代码期望的列/索引。若无法判定如还没有 config 表返回空——不说错话。idpending_migrationfixgbrain apply-migrations --yesdispatch_id: apply_migrations——这是默认可自动执行的修复之一幂等、安全4.3 Schema pack 不可解析schema-pack—— warnsrc/core/advisor/collect-schema-pack.ts 走loadActivePack尊重 per-source 全脑配置层级。健康的大脑解析到自己的 pack或 gbrain-base 默认时不产出任何发现配置指向磁盘上不存在的 pack 时上报 warnidschema_pack_unresolvedfixgbrain schema packs4.4 卡住的任务与过期同步stalled-jobs—— warn / infosrc/core/advisor/collect-stalled-jobs.ts 用引擎无关的executeRawSQL 查两张表同时兼容 Postgres 与 PGLite卡死的 active 任务minion_jobs中statusactive且lock_until now()或stalled_counter 2按任务名聚合idstalled_job:nameseveritywarntitlen name job(s) look stalled (lock lapsed / retrying).fixgbrain jobs stats源码注释专门更正过真实子命令是jobs statsjobs status从未存在注意minion_jobs表在旧/部分大脑上可能缺失查询被 try/catch 包裹缺表即无发现、绝不报错。过期的联邦源sources中last_sync_at距今超过 7 天idstale_sync:idseverityinfofixgbrain sync --source id4.5 大脑健康 vs 使用usage-shape—— warn / infosrc/core/advisor/collect-usage-shape.ts 先getStats()拿到页面数空大脑直接返回无事可建议再getHealth()做三项检查getHealth含孤儿/死链扫描较重因此只在显式gbrain advisor/每周 cron 路径运行同步节奏路径只用getStatsid触发条件严重度fixlow_embed_coverageembed_coverage 0.7且missing_embeddings 0warngbrain embed --allorphan_pages存在无入链/出链的页面infogbrain orphansdead_links存在指向不存在页面的链接infogbrain doctor4.6 设置异味setup-smells—— warn / infosrc/core/advisor/collect-setup-smells.ts 读合并配置 DB 平面键三个具体、可修复的配置问题embeddings_disabledwarnembedding_disabled true语义搜索与去重关闭。注意command_argv为 null——因为config set embedding_model被硬性拒绝schema-sizing 文件平面键正路是重新初始化gbrain init --force --embedding-model voyage:voyage-4先设VOYAGE_API_KEY。embedding_key_missingwarn按生效模型embedding_model ?? DEFAULT_EMBEDDING_MODEL解析 provider recipe 的必需认证环境变量recipe.auth_env.required[0]env 与文件配置两平面都查缺失即报。对已日落sunset的 providerdetail 会给出迁移命令而非设 key。publish_skills_offinforemote_mcp已开启而mcp.publish_skills未开——远程 MCP 大脑服务 Agent 却给它们空list_skillsfixgbrain config set mcp.publish_skills true4.7 未安装的大脑技能包uninstalled-brain-pack—— infoworkspace_dependentsrc/core/advisor/collect-uninstalled-brain-pack.ts 扫描各 source 的skillpack.json找出brain_resident true且未按清单版本安装的包。它是A1 workspace-dependent采集器MCP 远程端直接返回空已安装是本地安装账本skillpack-state.json的属性服务器端无意义。它通过decideNagAction尊重唠叨上限nag ceiling长期被无视的包会安静下来iduninstalled_brain_pack:sourceId:packNamefixgbrain skillpack scaffold localPath4.8 推荐捆绑技能未安装uninstalled-bundled—— infoworkspace_dependentsrc/core/advisor/collect-uninstalled-bundled.ts 是 post-install-advisory 硬编码清单的泛化继承者读单一 current-state 推荐清单currentRecommendedSet()src/core/advisor/recommended-set.ts对比 workspace 已安装 slugiduninstalled_bundled_skillsfixgbrain skillpack scaffold slug1 slug2 ...4.9 Life Chronicle本体冲突与时间线缺口chronicle—— warn / infosrc/core/advisor/collect-chronicle.ts 是纯大脑状态信号非 workspace 依赖MCP 端也能运行ontology_conflictswarnfindOntologyConflicts({ minConfidence: 0.5 })发现实体维度存在互相矛盾的当前值fixgbrain ontology-contradictions此条ask_user: false纯展示chronicle_coverage_gapinfo30 天内新增的 meeting/conversation/calendar-event 页面尚未被扫入时间线timeline_entries无对应event_page_idfixgbrain chronicle-backfill或启用auto_chronicle4.10 MCP 客户端表面与 STARTER_OPS 漂移mcp-client-fit—— infosrc/core/advisor/collect-mcp-client-fit.ts 是 E3 MCP 表面右尺寸化采集器骑在共享用量读取器 src/core/mcp-usage.ts 之上做两类检查(a) 单客户端 fit30 天 distinct-op 集合完全落在STARTER_OPS内、但解析到全量目录的客户端HTTP 客户端stdio 不记日志自动化形态客户端被排除正在为一个 starter 规模的工作负载支付约 100 个工具的目录成本idmcp_starter_fit:token_name触发下限MIN_CALLS_FOR_FIT 10一次 whoami 探测不算工作负载fixgbrain auth rescope-client id --surface starter(b) 集合级漂移常驻的 STARTER_OPS 策展人——按客户端数量非裸调用量D12排名的 top-10 操作中缺失于STARTER_OPS的项以及 90 天DRIFT_UNUSED_WINDOW_DAYS未使用的 starter 成员排除ALWAYS_INCLUDED_STARTER_OPSidmcp_starter_ops_driftfixnull需人工重推导bun run scripts/derive-starter-ops.ts后把提案块贴回 src/mcp/surface.ts该采集器有自己的 nag 状态文件~/.gbrain/advisor-usage-nag-state.json与技能包账本隔离隐私纪律amendment 29远程运行时客户端标识被脱敏为聚合计数2 clients fit the starter surface — rungbrain advisoron the host for details完整逐客户端细节仅本地 CLI 可见操作名不是客户端标识两个面都保留。4.11 备份覆盖率backup-coverage—— warn / infosrc/core/advisor/collect-backup-coverage.ts 复用getBackupStatus陈旧才重算保证 cron 安全新鲜缓存就是一次文件读。本地运行时按资产逐个产出发现含fix_argv经backupNagGate整批门控远程只读缓存 聚合计数id场景严重度fixbackup_source_no_remote:id知识仓库无 git remote磁盘丢失即永久丢失warn来自a.fix_argvbackup_workspace_no_repoAgent workspace 还没有私有仓库warna.fix_argv刻意不给硬编码回退backup_db_content_unbacked大脑只存在于本地数据库warna.fix_argv ?? [gbrain,bootstrap,repo]backup_unpushed_work有未推送的提交infonullbackup_db_only_caveatdb_only 页面不在任何 git 远端覆盖内info提示gbrain export/gbrain doctor4.12 环境写回同意writeback-consent—— infosrc/core/advisor/collect-writeback-consent.ts 是 ambient writeback 提醒的周期性拉动面WP8仅在一次性 init/post-upgrade 询问已发出哨兵后才产出绝不成为同意问题首次出现的地方仅个人大脑声明优先于启发式仅本地。刻意不可--apply——同意绝不能被自动化因此无dispatch_id、command_argv为 nullidwriteback_consent_pendingdetail 给出的启用路径gbrain config set memory.auto_writeback salient后gbrain bootstrap harness --yes关闭gbrain config set memory.auto_writeback off五、每周检查cron 配方SKILL.md 给出一套薄提示词的每周任务配方配合 skills/cron-scheduler/SKILL.md 使用调度每周一个尊重安静时段的槽位如本地时间周一 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.幂等advisor 只读所以重复触发无害cron-scheduler 技能也强制所有任务幂等。由于 advisor 会记录本地运行历史每次触发时可以向用户汇报自上次运行以来新增了什么而不是把全部清单再列一遍见第六节的增量机制。六、有界唠叨与自上次以来新增的增量机制不要每次把同一份清单甩给用户不是口号而是有文件支撑的机制src/core/advisor/history.ts 在本地文件平面维护追加式历史~/.gbrain/advisor-history.jsonlexport interface AdvisorRunSnapshot { ts: string; version: string; worst: AdvisorReport[worst]; finding_ids: string[]; }上限ADVISOR_HISTORY_MAX 100条快照超出即轮转保留最新一半每次 CLI 运行--apply之外的路径先appendAdvisorRun追加当前快照并取回上一次快照再summarizeDeltas计算增量added本次新增的 finding idresolved本次消失的 finding id输出形如(2 new since last run, 1 resolved)本地专用 best-effortMCP 远程端不写历史写入失败绝不影响报告本身。采集器层面还有两套 nag 引擎src/core/skillpack/nag-state.ts 的decideNagAction技能包/捆绑技能用技能包账本~/.gbrain/skillpack-nag-state.json一系MCP 客户端 fit 用独立文件~/.gbrain/advisor-usage-nag-state.json避免污染技能包账本备份覆盖率用backupNagGate参与同一有界唠叨预算。这些引擎的行为模式一致升级-然后-抑制escalate-then-suppress到上限后安静一旦输入指纹变化如使用画像改变会重新浮现。七、修复执行的安全模型--apply 的白名单 结构化 argvgbrain advisor --apply dispatch_id是唯一会真正运行修复的路径src/core/advisor/apply.ts 与 src/commands/advisor.ts 的applyFinding()联合实现了多层防御注释中标注为安全模型 #10/C5白名单只有携带dispatch_id的发现可运行resolveApplyTarget只认f.fix.dispatch_id。没有 id 的发现即便用户同意也由 Agent 手动执行fix.command_argv。argv[0] 必须是gbrainadvisor 绝不运行任意二进制。拒绝 shell 元字符SHELL_META /[;|$(){}\n]/任一 token 命中即拒绝——防御纵深反正也从不起 shell。结构化 argv spawnSync(..., { shell: false })以子进程、无 shell 方式执行杜绝注入。先确认confirmTty(Proceed? [y/N]: )只在process.stdin.isTTY为真时才提示非 TTY 环境直接返回false绝不自动运行。只接受y/yes。本地专用--apply是 CLI 路径MCP 端天然不存在该能力见第八节。失败时输出会附上当前可运行项Runnable now: id1, id2.或Nothing is runnable right now.八、MCP 端 advisor oppublish 门控与 A1 过滤gbrain advisor不只是 CLI。它同时注册为 MCP 操作advisorsrc/core/operations.ts 中advisor: advisor实现在 src/core/ops/skills-catalog.tsscope: read不是localOnly——按 E1 暴露给 MCP但受独立发布门控mcp.publish_advisor与mcp.publish_skills分开诊断不是散文技能远程调用者ctx.remote ! false必须让大脑所有者开启mcp.publish_advisorgbrain config set mcp.publish_advisor true否则抛permission_denieddetail 带config_keymcp.publish_advisor本地调用者信任边界是 OS绕过门控远程运行时runAdvisor以remote: true构造上下文丢弃所有workspace_dependent发现A1服务器端没有 Agent workspace也绝不写历史/nag 状态——严格只读门控行为由 test/advisor-op-gate.test.ts 固定op 存在、read 作用域、非 localOnly无mcp.publish_advisor的远程调用 →permission_denied有则返回报告本地调用绕过门控。因此 SKILL.md 反模式清单里专门提醒MCPadvisorop 只返回大脑状态信号不要拿它来查 workspace 安装状态——未安装技能类发现是本地 CLI 的专属。九、如何向用户呈现发现输出格式规范SKILL.md 定义了向用户呈现的统一格式src/core/advisor/render.ts 的renderAdvisorReport()则是 CLI 人类可读渲染的共享实现与 post-install advisory 共用同一渲染器防止两面漂移使用 72 个的分隔条与[CRITICAL]/[WARN]/[INFO]标签。Agent 转述给用户时按 SKILL.md 的规范保持可扫描性 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 (youre on 0.43). Fix: gbrain upgrade规范要点每条发现一个块严重度从高到低总是展示确切的fix命令并先问再跑没有紧迫项时一句话带过brain looks healthy绝不制造工作。Agent 处理发现的完整流程SKILL.mdWhat to do with the findings按严重度从高到低读发现把 top 13 条用用户自己的渠道/语气总结critical如待迁移打头逐条展示fix.command_argv并询问是否执行用户同意且该发现带fix.dispatch_id时本地执行gbrain advisor --apply dispatch_id没有dispatch_id的发现不可自动执行用户同意后由 Agent 手动跑fix.command_argv绝不在未经批准时运行任何修复。十、反模式清单务必遵守SKILL.md 明确列出的五条反模式与源码设计一一对应不问就修——advisor 按契约只读没有用户的明确同意绝不运行--apply或任何 fix 命令。把原始 JSON 直接甩给用户——把发现翻译成用户的语言以什么重要打头--json是给 Agent 管道用的人看渲染版。每次运行都重复唠叨被无视的低严重度项——用自上次以来新增增量尊重用户之前的不行动。把info当critical用——只有critical如待迁移值得拦路/坚持info是轻推一下。用 MCPadvisorop 查 workspace 安装状态——MCP 端只有大脑状态信号未安装技能类发现是本地 CLI 的领域。十一、测试与质量保证仓库为 advisor 建立了相当完整的测试矩阵可作为理解行为契约的补充材料测试文件覆盖点test/advisor-cli.test.tsCLI 端到端--json退出码映射、--apply的 TTY 门test/advisor-apply.test.tsapply 解析与校验白名单、argv[0]、shell 元字符拒绝test/advisor-core.test.ts报告核心与排序test/advisor-collectors-findings.test.ts各采集器产出test/advisor-op-gate.test.tsMCP 门控mcp.publish_advisortest/advisor-mcp-client-fit.test.tsMCP 客户端 fit / 漂移检查test/advisor-backup-coverage.serial.test.ts备份覆盖率采集test/advisor-ranking-eval.test.ts排序质量评估十二、小结gbrain advisorgbrain-advisor技能构成了一套体检—分级—转述—确认—执行的闭环体检由 12 个确定性顺序、互相隔离的采集器完成覆盖版本、迁移、schema pack、任务、健康度、配置、技能包、Chronicle、MCP 表面、备份与写回同意分级通过critical/warn/info与退出码 0/1/2 形成机器可用的闸门转述遵循共享渲染器与 SKILL.md 的呈现规范保持可扫描、按严重度排序确认由技能契约与ask_user保证——用户拥有每个决策执行只经--apply白名单 结构化 argv TTY 确认的本地通道MCP 端严格只读。把这条命令放进每周 cron薄提示词 幂等只读你的大脑就会有一个持续提醒你如何把它运行得更好的主动教练——而所有决策权始终在你手里。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐gbrain-advisor 技能实战用 gbrain advisor 打造大脑的每周体检与主动顾问gbrain advisor 技能实战用 gbrain advisor 打造大脑的每周体检与主动顾问 gbrain 的 advisor 是一个只读的主动教练人工智能RAGAgent 记忆MCP 服务知识管理gbrain-advisor 技能实战用 gbrain advisor 建立大脑健康检查与主动优化工作流gbrain advisor 技能实战用 gbrain advisor 建立大脑健康检查与主动优化工作流 gbrain advisor 是 gbrain 仓库人工智能RAGAgent 记忆MCP 服务知识管理gbrain Maintain 技能实战指南脑健康检查、Dream 综合周期与自动化修复gbrain Maintain 技能实战指南脑健康检查、Dream 综合周期与自动化修复 导读 本指南以 gbrain 仓库中 maintain 技能 pl人工智能RAGAgent 记忆MCP 服务知识管理上一篇Halfrost-Field 项目深度解析JavaScript 作用域机制详解下一篇Golang/dep 项目安装指南从入门到精通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gbrain advisor 实战指南：只读大脑体检、分级发现与安全修复机制
人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本指南以 gbrain 官方技能 skills/gbrain-advisor/SKILL.md 为骨架结合仓库内 CLI 入口、12 个采集器collector、apply 安全模型与 MCP 门控的源码实现展开。读完你将掌握如何按需/按周期运行gbrain advisor给大脑做体检如何读懂 JSON 契约与退出码语义如何安全地通过--apply落地单个修复以及如何用 cron 技能搭起每周大脑检查的自动化流程。一、gbrain advisor 是什么大脑的主动式教练gbrain 是一个带知识图谱、嵌入检索、schema pack、minion 后台任务与 MCP 服务面的个人大脑系统。它体量庞大、状态面众多版本是否漂移、数据库 schema 是否落后、后台任务是否卡死、嵌入覆盖率是否不足、配置是否存在设置异味setup smells、技能包是否已安装——这些状态平时散落在各处容易积小患成大患。gbrain advisor就是专门解决这个问题的只读体检命令它从既有大脑状态出发计算出一张按严重度排序的高杠杆行动清单每条行动都带有severitycritical|warn|infotitle一行为什么它重要fix.command_argv修复它的确切命令结构化 argv而非 shell 字符串fix.dispatch_id当该修复可安全地通过--apply落地时给出配套的gbrain-advisor技能即本指南对应的 skills/gbrain-advisor/SKILL.mdfrontmatter 中mutating: false把这条命令包装成大脑的主动语音它按节奏典型为每周运行 advisor把最重要的 13 条发现以用户自己的语气推给大脑所有者并永远先询问、后执行。技能约定遵循 skills/conventions/brain-first.md 的brain-first惯例体系。技能声明了五类典型触发语Agent 遇到这些问法时应主动拉起 advisorwhat should I do to get more out of gbrain is my brain set up right gbrain advisor advise me on my brain weekly brain checkup1.1 技能契约Contractskills/gbrain-advisor/SKILL.md 明确承诺三条铁律也是理解整个设计的前提只读Read-onlygbrain advisor本身绝不改动任何状态它只是从既有大脑状态计算一份排名清单。打印、绝不执行Print, never executeAgent 把发现 SHOW 给用户并 ASK 之后再考虑运行修复用户拥有每一个决策。有界唠叨Bounded nagging按节奏运行时只呈现新出现的或关键的内容被用户无视的低严重度项不会每次运行都重复轰炸。这三条契约在源码层面被严格落实CLI 入口 src/commands/advisor.ts 顶部注释写明 The advisor itself never mutates.--applyis the only path that runs a fix且--apply也要过 TTY 确认非交互终端直接拒绝见下文安全模型。二、什么时候跑按需、每周、每月SKILL.md 给出了三个触发时机时机触发方式说明按需用户问 how do I get more out of this brain?即时执行一次完整体检每周cron 配方见第五节即使大脑看起来很闲也会收到一条如何把它运行得更好的提示每月gbrain backup status额外上报备份覆盖率结论——即哪些知识仓库没有 git remote本地裸奔任何 warn 都要转述给用户月度的备份覆盖率结论在源码中由collectBackupCoverage采集器实现见第四节它复用 src/core/backup/coverage.ts 的getBackupStatus与 src/core/backup/status-file.ts 的backupNagGate且有一个硬性总开关backupCheckDisabled()——关闭后该采集器在计算与所有渲染通道全部静默。三、运行方式与 JSON 契约3.1 三种 CLI 形态src/commands/advisor.ts 定义了三种形态--help输出可以直接看到gbrain advisor # 人类可读的排名清单agent-readable 渲染 gbrain advisor --json # 结构化 findingscritical 时退出码非 0E2 gbrain advisor --apply finding-id # 运行某一条发现的修复本地专用、先确认E53.2 退出码即严重度闸门E2CLI 的退出码由exitFor()映射这是 SKILL.md 强调的severity gate// src/commands/advisor.ts function exitFor(report: AdvisorReport): 0 | 1 | 2 { if (report.worst critical) return 2; if (report.worst warn) return 1; return 0; }退出码含义0干净clean大脑健康1有 warn警告2有 critical关键测试 test/advisor-cli.test.ts 对这条语义做了端到端断言worst critical时退出码为2worst warn如仅 ontology conflicts时退出码为1。3.3 JSON payload 结构--json输出的是整个AdvisorReport类型定义见 src/core/advisor/types.ts{ version: 0.46.x, generated_at: 2026-09-20T04:30:00.000Z, worst: warn, findings: [ { id: pending_migration, severity: critical, title: Schema migrations are pending — run them before relying on newer features., detail: Newer gbrain code assumes the latest schema; an un-migrated brain can fail or under-perform., fix: { command_argv: [gbrain, apply-migrations, --yes], dispatch_id: apply_migrations }, collector: migration, ask_user: true } ] }每个 finding 的关键字段字段说明id稳定 ID如version_drift、pending_migration、stalled_job:nameseveritycritical|warn|infotitle一行为什么重要detail可选补充上下文fix.command_argv结构化 argv如[gbrain,apply-migrations,--yes]绝非 shell 字符串无机械修复时为nullfix.dispatch_id仅当该修复可安全经--apply白名单执行时出现collector由哪个采集器产出ask_user是否必须先问用户workspace_dependent为true时该发现依赖本地 workspace如已安装技能MCP 远程端会丢弃见第七节四、十二大采集器每条发现从哪来gbrain advisor的发现不是拍脑袋生成的。运行核心 src/core/advisor/run.ts 维护了一个写死的 v1 采集器清单COLLECTORS数组顺序即确定性排序的次级键export const COLLECTORS: AdvisorCollector[] [ collectVersion, // 版本漂移 collectMigration, // 待执行 schema 迁移 collectSchemaPack, // schema pack 可解析性 collectStalledJobs, // 卡住的后台任务 过期同步 collectUsageShape, // 大脑健康 vs 使用嵌入覆盖率/孤儿页/死链 collectSetupSmells, // 配置/设置异味 collectUninstalledBrainPack, // 大脑内置而未安装的技能包 collectUninstalledBundled, // 推荐捆绑技能未安装 collectChronicle, // Life Chronicle本体冲突 时间线覆盖缺口 collectMcpClientFit, // MCP 客户端表面(right-sizing)与 STARTER_OPS 漂移 collectBackupCoverage, // 备份覆盖率 collectWritebackConsent, // 环境写回ambient writeback同意提示 ];排序规则rankFindingscritical warn info同级按采集器顺序稳定排序info尾部默认上限 10 条infoCap避免把 Agent 淹没在低优先级的唠叨里。每个采集器在各自的 try/catch中运行——单个采集器抛错只贡献零条发现绝不让整个报告失败。下面逐个展开每条都给出触发条件、严重度与修复命令以源码为准。4.1 版本漂移version—— warnsrc/core/advisor/collect-version.ts 读取更新缓存而非直接联网保证 advisor 在 cron 中快速、安全缓存由gbrain check-update/ 自升级刷新路径在带外刷新。经 src/core/self-upgrade.ts 的pendingUpgradeVersion(runningVersion, now)判定只有缓存新鲜、标记为upgrade_available、且严格新于正在运行的版本时才上报。idversion_drifttitlegbrain latest is available — youre on running.fixgbrain upgrade4.2 待执行迁移migration—— critical唯一的关键信号src/core/advisor/collect-migration.ts 调用hasPendingMigrations(engine)。这是 SKILL.md 明确指出的唯一 critical 项未迁移的大脑可能缺少新代码期望的列/索引。若无法判定如还没有 config 表返回空——不说错话。idpending_migrationfixgbrain apply-migrations --yesdispatch_id: apply_migrations——这是默认可自动执行的修复之一幂等、安全4.3 Schema pack 不可解析schema-pack—— warnsrc/core/advisor/collect-schema-pack.ts 走loadActivePack尊重 per-source 全脑配置层级。健康的大脑解析到自己的 pack或 gbrain-base 默认时不产出任何发现配置指向磁盘上不存在的 pack 时上报 warnidschema_pack_unresolvedfixgbrain schema packs4.4 卡住的任务与过期同步stalled-jobs—— warn / infosrc/core/advisor/collect-stalled-jobs.ts 用引擎无关的executeRawSQL 查两张表同时兼容 Postgres 与 PGLite卡死的 active 任务minion_jobs中statusactive且lock_until now()或stalled_counter 2按任务名聚合idstalled_job:nameseveritywarntitlen name job(s) look stalled (lock lapsed / retrying).fixgbrain jobs stats源码注释专门更正过真实子命令是jobs statsjobs status从未存在注意minion_jobs表在旧/部分大脑上可能缺失查询被 try/catch 包裹缺表即无发现、绝不报错。过期的联邦源sources中last_sync_at距今超过 7 天idstale_sync:idseverityinfofixgbrain sync --source id4.5 大脑健康 vs 使用usage-shape—— warn / infosrc/core/advisor/collect-usage-shape.ts 先getStats()拿到页面数空大脑直接返回无事可建议再getHealth()做三项检查getHealth含孤儿/死链扫描较重因此只在显式gbrain advisor/每周 cron 路径运行同步节奏路径只用getStatsid触发条件严重度fixlow_embed_coverageembed_coverage 0.7且missing_embeddings 0warngbrain embed --allorphan_pages存在无入链/出链的页面infogbrain orphansdead_links存在指向不存在页面的链接infogbrain doctor4.6 设置异味setup-smells—— warn / infosrc/core/advisor/collect-setup-smells.ts 读合并配置 DB 平面键三个具体、可修复的配置问题embeddings_disabledwarnembedding_disabled true语义搜索与去重关闭。注意command_argv为 null——因为config set embedding_model被硬性拒绝schema-sizing 文件平面键正路是重新初始化gbrain init --force --embedding-model voyage:voyage-4先设VOYAGE_API_KEY。embedding_key_missingwarn按生效模型embedding_model ?? DEFAULT_EMBEDDING_MODEL解析 provider recipe 的必需认证环境变量recipe.auth_env.required[0]env 与文件配置两平面都查缺失即报。对已日落sunset的 providerdetail 会给出迁移命令而非设 key。publish_skills_offinforemote_mcp已开启而mcp.publish_skills未开——远程 MCP 大脑服务 Agent 却给它们空list_skillsfixgbrain config set mcp.publish_skills true4.7 未安装的大脑技能包uninstalled-brain-pack—— infoworkspace_dependentsrc/core/advisor/collect-uninstalled-brain-pack.ts 扫描各 source 的skillpack.json找出brain_resident true且未按清单版本安装的包。它是A1 workspace-dependent采集器MCP 远程端直接返回空已安装是本地安装账本skillpack-state.json的属性服务器端无意义。它通过decideNagAction尊重唠叨上限nag ceiling长期被无视的包会安静下来iduninstalled_brain_pack:sourceId:packNamefixgbrain skillpack scaffold localPath4.8 推荐捆绑技能未安装uninstalled-bundled—— infoworkspace_dependentsrc/core/advisor/collect-uninstalled-bundled.ts 是 post-install-advisory 硬编码清单的泛化继承者读单一 current-state 推荐清单currentRecommendedSet()src/core/advisor/recommended-set.ts对比 workspace 已安装 slugiduninstalled_bundled_skillsfixgbrain skillpack scaffold slug1 slug2 ...4.9 Life Chronicle本体冲突与时间线缺口chronicle—— warn / infosrc/core/advisor/collect-chronicle.ts 是纯大脑状态信号非 workspace 依赖MCP 端也能运行ontology_conflictswarnfindOntologyConflicts({ minConfidence: 0.5 })发现实体维度存在互相矛盾的当前值fixgbrain ontology-contradictions此条ask_user: false纯展示chronicle_coverage_gapinfo30 天内新增的 meeting/conversation/calendar-event 页面尚未被扫入时间线timeline_entries无对应event_page_idfixgbrain chronicle-backfill或启用auto_chronicle4.10 MCP 客户端表面与 STARTER_OPS 漂移mcp-client-fit—— infosrc/core/advisor/collect-mcp-client-fit.ts 是 E3 MCP 表面右尺寸化采集器骑在共享用量读取器 src/core/mcp-usage.ts 之上做两类检查(a) 单客户端 fit30 天 distinct-op 集合完全落在STARTER_OPS内、但解析到全量目录的客户端HTTP 客户端stdio 不记日志自动化形态客户端被排除正在为一个 starter 规模的工作负载支付约 100 个工具的目录成本idmcp_starter_fit:token_name触发下限MIN_CALLS_FOR_FIT 10一次 whoami 探测不算工作负载fixgbrain auth rescope-client id --surface starter(b) 集合级漂移常驻的 STARTER_OPS 策展人——按客户端数量非裸调用量D12排名的 top-10 操作中缺失于STARTER_OPS的项以及 90 天DRIFT_UNUSED_WINDOW_DAYS未使用的 starter 成员排除ALWAYS_INCLUDED_STARTER_OPSidmcp_starter_ops_driftfixnull需人工重推导bun run scripts/derive-starter-ops.ts后把提案块贴回 src/mcp/surface.ts该采集器有自己的 nag 状态文件~/.gbrain/advisor-usage-nag-state.json与技能包账本隔离隐私纪律amendment 29远程运行时客户端标识被脱敏为聚合计数2 clients fit the starter surface — rungbrain advisoron the host for details完整逐客户端细节仅本地 CLI 可见操作名不是客户端标识两个面都保留。4.11 备份覆盖率backup-coverage—— warn / infosrc/core/advisor/collect-backup-coverage.ts 复用getBackupStatus陈旧才重算保证 cron 安全新鲜缓存就是一次文件读。本地运行时按资产逐个产出发现含fix_argv经backupNagGate整批门控远程只读缓存 聚合计数id场景严重度fixbackup_source_no_remote:id知识仓库无 git remote磁盘丢失即永久丢失warn来自a.fix_argvbackup_workspace_no_repoAgent workspace 还没有私有仓库warna.fix_argv刻意不给硬编码回退backup_db_content_unbacked大脑只存在于本地数据库warna.fix_argv ?? [gbrain,bootstrap,repo]backup_unpushed_work有未推送的提交infonullbackup_db_only_caveatdb_only 页面不在任何 git 远端覆盖内info提示gbrain export/gbrain doctor4.12 环境写回同意writeback-consent—— infosrc/core/advisor/collect-writeback-consent.ts 是 ambient writeback 提醒的周期性拉动面WP8仅在一次性 init/post-upgrade 询问已发出哨兵后才产出绝不成为同意问题首次出现的地方仅个人大脑声明优先于启发式仅本地。刻意不可--apply——同意绝不能被自动化因此无dispatch_id、command_argv为 nullidwriteback_consent_pendingdetail 给出的启用路径gbrain config set memory.auto_writeback salient后gbrain bootstrap harness --yes关闭gbrain config set memory.auto_writeback off五、每周检查cron 配方SKILL.md 给出一套薄提示词的每周任务配方配合 skills/cron-scheduler/SKILL.md 使用调度每周一个尊重安静时段的槽位如本地时间周一 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.幂等advisor 只读所以重复触发无害cron-scheduler 技能也强制所有任务幂等。由于 advisor 会记录本地运行历史每次触发时可以向用户汇报自上次运行以来新增了什么而不是把全部清单再列一遍见第六节的增量机制。六、有界唠叨与自上次以来新增的增量机制不要每次把同一份清单甩给用户不是口号而是有文件支撑的机制src/core/advisor/history.ts 在本地文件平面维护追加式历史~/.gbrain/advisor-history.jsonlexport interface AdvisorRunSnapshot { ts: string; version: string; worst: AdvisorReport[worst]; finding_ids: string[]; }上限ADVISOR_HISTORY_MAX 100条快照超出即轮转保留最新一半每次 CLI 运行--apply之外的路径先appendAdvisorRun追加当前快照并取回上一次快照再summarizeDeltas计算增量added本次新增的 finding idresolved本次消失的 finding id输出形如(2 new since last run, 1 resolved)本地专用 best-effortMCP 远程端不写历史写入失败绝不影响报告本身。采集器层面还有两套 nag 引擎src/core/skillpack/nag-state.ts 的decideNagAction技能包/捆绑技能用技能包账本~/.gbrain/skillpack-nag-state.json一系MCP 客户端 fit 用独立文件~/.gbrain/advisor-usage-nag-state.json避免污染技能包账本备份覆盖率用backupNagGate参与同一有界唠叨预算。这些引擎的行为模式一致升级-然后-抑制escalate-then-suppress到上限后安静一旦输入指纹变化如使用画像改变会重新浮现。七、修复执行的安全模型--apply 的白名单 结构化 argvgbrain advisor --apply dispatch_id是唯一会真正运行修复的路径src/core/advisor/apply.ts 与 src/commands/advisor.ts 的applyFinding()联合实现了多层防御注释中标注为安全模型 #10/C5白名单只有携带dispatch_id的发现可运行resolveApplyTarget只认f.fix.dispatch_id。没有 id 的发现即便用户同意也由 Agent 手动执行fix.command_argv。argv[0] 必须是gbrainadvisor 绝不运行任意二进制。拒绝 shell 元字符SHELL_META /[;|$(){}\n]/任一 token 命中即拒绝——防御纵深反正也从不起 shell。结构化 argv spawnSync(..., { shell: false })以子进程、无 shell 方式执行杜绝注入。先确认confirmTty(Proceed? [y/N]: )只在process.stdin.isTTY为真时才提示非 TTY 环境直接返回false绝不自动运行。只接受y/yes。本地专用--apply是 CLI 路径MCP 端天然不存在该能力见第八节。失败时输出会附上当前可运行项Runnable now: id1, id2.或Nothing is runnable right now.八、MCP 端 advisor oppublish 门控与 A1 过滤gbrain advisor不只是 CLI。它同时注册为 MCP 操作advisorsrc/core/operations.ts 中advisor: advisor实现在 src/core/ops/skills-catalog.tsscope: read不是localOnly——按 E1 暴露给 MCP但受独立发布门控mcp.publish_advisor与mcp.publish_skills分开诊断不是散文技能远程调用者ctx.remote ! false必须让大脑所有者开启mcp.publish_advisorgbrain config set mcp.publish_advisor true否则抛permission_denieddetail 带config_keymcp.publish_advisor本地调用者信任边界是 OS绕过门控远程运行时runAdvisor以remote: true构造上下文丢弃所有workspace_dependent发现A1服务器端没有 Agent workspace也绝不写历史/nag 状态——严格只读门控行为由 test/advisor-op-gate.test.ts 固定op 存在、read 作用域、非 localOnly无mcp.publish_advisor的远程调用 →permission_denied有则返回报告本地调用绕过门控。因此 SKILL.md 反模式清单里专门提醒MCPadvisorop 只返回大脑状态信号不要拿它来查 workspace 安装状态——未安装技能类发现是本地 CLI 的专属。九、如何向用户呈现发现输出格式规范SKILL.md 定义了向用户呈现的统一格式src/core/advisor/render.ts 的renderAdvisorReport()则是 CLI 人类可读渲染的共享实现与 post-install advisory 共用同一渲染器防止两面漂移使用 72 个的分隔条与[CRITICAL]/[WARN]/[INFO]标签。Agent 转述给用户时按 SKILL.md 的规范保持可扫描性 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 (youre on 0.43). Fix: gbrain upgrade规范要点每条发现一个块严重度从高到低总是展示确切的fix命令并先问再跑没有紧迫项时一句话带过brain looks healthy绝不制造工作。Agent 处理发现的完整流程SKILL.mdWhat to do with the findings按严重度从高到低读发现把 top 13 条用用户自己的渠道/语气总结critical如待迁移打头逐条展示fix.command_argv并询问是否执行用户同意且该发现带fix.dispatch_id时本地执行gbrain advisor --apply dispatch_id没有dispatch_id的发现不可自动执行用户同意后由 Agent 手动跑fix.command_argv绝不在未经批准时运行任何修复。十、反模式清单务必遵守SKILL.md 明确列出的五条反模式与源码设计一一对应不问就修——advisor 按契约只读没有用户的明确同意绝不运行--apply或任何 fix 命令。把原始 JSON 直接甩给用户——把发现翻译成用户的语言以什么重要打头--json是给 Agent 管道用的人看渲染版。每次运行都重复唠叨被无视的低严重度项——用自上次以来新增增量尊重用户之前的不行动。把info当critical用——只有critical如待迁移值得拦路/坚持info是轻推一下。用 MCPadvisorop 查 workspace 安装状态——MCP 端只有大脑状态信号未安装技能类发现是本地 CLI 的领域。十一、测试与质量保证仓库为 advisor 建立了相当完整的测试矩阵可作为理解行为契约的补充材料测试文件覆盖点test/advisor-cli.test.tsCLI 端到端--json退出码映射、--apply的 TTY 门test/advisor-apply.test.tsapply 解析与校验白名单、argv[0]、shell 元字符拒绝test/advisor-core.test.ts报告核心与排序test/advisor-collectors-findings.test.ts各采集器产出test/advisor-op-gate.test.tsMCP 门控mcp.publish_advisortest/advisor-mcp-client-fit.test.tsMCP 客户端 fit / 漂移检查test/advisor-backup-coverage.serial.test.ts备份覆盖率采集test/advisor-ranking-eval.test.ts排序质量评估十二、小结gbrain advisorgbrain-advisor技能构成了一套体检—分级—转述—确认—执行的闭环体检由 12 个确定性顺序、互相隔离的采集器完成覆盖版本、迁移、schema pack、任务、健康度、配置、技能包、Chronicle、MCP 表面、备份与写回同意分级通过critical/warn/info与退出码 0/1/2 形成机器可用的闸门转述遵循共享渲染器与 SKILL.md 的呈现规范保持可扫描、按严重度排序确认由技能契约与ask_user保证——用户拥有每个决策执行只经--apply白名单 结构化 argv TTY 确认的本地通道MCP 端严格只读。把这条命令放进每周 cron薄提示词 幂等只读你的大脑就会有一个持续提醒你如何把它运行得更好的主动教练——而所有决策权始终在你手里。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐gbrain-advisor 技能实战用 gbrain advisor 打造大脑的每周体检与主动顾问gbrain advisor 技能实战用 gbrain advisor 打造大脑的每周体检与主动顾问 gbrain 的 advisor 是一个只读的主动教练人工智能RAGAgent 记忆MCP 服务知识管理gbrain-advisor 技能实战用 gbrain advisor 建立大脑健康检查与主动优化工作流gbrain advisor 技能实战用 gbrain advisor 建立大脑健康检查与主动优化工作流 gbrain advisor 是 gbrain 仓库人工智能RAGAgent 记忆MCP 服务知识管理gbrain Maintain 技能实战指南脑健康检查、Dream 综合周期与自动化修复gbrain Maintain 技能实战指南脑健康检查、Dream 综合周期与自动化修复 导读 本指南以 gbrain 仓库中 maintain 技能 pl人工智能RAGAgent 记忆MCP 服务知识管理上一篇Halfrost-Field 项目深度解析JavaScript 作用域机制详解下一篇Golang/dep 项目安装指南从入门到精通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考