它有点特殊。
特殊在于，它不是 MCP，也不是 Skills，也不是普通的 Subagent，更不是 Agent Teams。
更特殊的是：它已经出现在 Claude Code 的二进制实现里，也可以实际运行，但官方公开文档里还没有正式说明。甚至在 Claude Code 2.1.147 的发布信息中，Workflow 曾短暂出现过，随后又被移除。
所以今天这篇文章不会把它包装成”官方正式发布的新功能”。更准确地说：
Workflow 是 Claude Code 里已经可用、但仍处于隐藏/实验状态的多 Agent 编排能力。
如果你平时已经在用 Claude Code、Subagents、Skills 或 Agent Teams，那么 Workflow 值得重点关注。它可能是继 MCP 和 Skills 之后，Claude Code 生态里又一个非常关键的能力方向。
🚀 本篇笔记所对应的视频：
一句话解释：
Workflow 是用 JavaScript 脚本来编排多个 Claude Code agent 的机制。
以前我们让 Claude Code 做复杂任务，通常是这样说：
请你先分析代码，再找风险，再给出修复方案。
这本质上还是自然语言驱动。模型会自己决定怎么拆任务、什么时候派 subagent、如何汇总结果。
Workflow 不一样。
它把这个过程写成代码：
phase("Review")
const results = await Promise.all([
agent("检查 correctness 风险", { label: "correctness-reviewer" }),
agent("检查 security 风险", { label: "security-reviewer" }),
agent("检查 testing 覆盖", { label: "test-reviewer" }),
])
phase("Aggregate")
const final = await agent(
`请汇总这些结果：${JSON.stringify(results)}`,
{ label: "aggregator" },
)
return final
也就是说，Workflow 做的不是”再多叫几个 agent”，而是把多 Agent 的调用顺序、并行关系、阶段划分、输出格式和最终聚合，都变成可复用的脚本。
这就是它真正重要的地方。
很多人第一次看到 Workflow，可能会问：Claude Code 不是已经有 Subagents 和 Agent Teams 了吗？为什么还需要 Workflow？
可以这样理解。
Subagent 很适合临时委派。
比如：
它的优点是简单、自然、启动成本低。
但它的问题也明显：整个流程主要还是模型临场决定。今天它这么拆，明天可能换一种拆法；这次它记得验证，下次可能跳过验证。它适合”临时任务”，不太适合沉淀成稳定流程。
Agent Teams 更像一个多 agent 协作界面。
你可以让不同角色并行工作，人类再去调度、查看、接管。它适合交互式协作，适合长期多角色任务。
但如果你要的是一个可以反复跑的”工程流水线”，Agent Teams 仍然偏交互，不够脚本化。
Skills 更像”能力包”。
它告诉模型：
Skills 的优势在于分发、说明、触发、上下文封装。
但 Workflow 的优势在于执行编排。
所以更准确的关系不是”Workflow 取代 Skills”，而是：
Skills 负责封装和分发，Workflow script 负责执行真正的多 Agent 工作流。
未来很可能出现这种形态：
my-review-skill/
SKILL.md
workflows/
sharded-review.workflow.mjs
pr-review.workflow.mjs
examples/
report.md
Skill 告诉 Claude Code 什么时候用；Workflow 负责把流程跑起来。
这是我测试之后最深的感受。
普通 prompt 是一次性的。
Subagent 是临时派生的。
Agent Teams 更偏人工调度。
但 Workflow script 可以沉淀下来。
一旦某个脚本在某类任务上跑得不错，后续你就可以复用它完成类似任务。
比如：
你不需要每次重新描述完整流程。你只需要保存脚本，下次换一个仓库、换一个主题、换一个 PR，再把参数改掉即可。
这就让”工作流”从一种 prompt 写法，变成了可以共享、可以修改、可以迭代的资产。
当前 Workflow 仍然是隐藏/实验能力，所以需要显式开启。
启动 Claude Code 前，可以这样设置：
export CLAUDE_CODE_WORKFLOWS=1
claude
或者直接：
CLAUDE_CODE_WORKFLOWS=1 claude
进入 Claude Code 后，如果你希望它使用 Workflow，可以明确写：
ultrawork
请生成一个只读的大代码库分片审查 workflow script。
不要执行，先让我确认。
这里要注意：ultrawork 更像一个经验性触发词，不是官方公开文档里的正式命令。它在测试中能有效提示 Claude Code 使用 Workflow，但不能把它当成稳定 API。
最稳妥的方式是两步走：
第一步，让 Claude Code 生成脚本，但不要执行。
ultrawork
请为当前仓库生成一个 workflow script，但不要执行。
要求：
1. 识别 4-8 个 review shard
2. 每个 shard 用 agent()
3. 每个 agent 必须带 JSON schema
4. 最后 aggregator 合并 findings
5. 写到 /tmp/sharded-review.workflow.mjs
6. 输出 scriptPath，等待我确认
第二步，确认脚本后再运行：
Workflow({
scriptPath: "/tmp/sharded-review.workflow.mjs"
})
目前我最推荐 scriptPath 方式，因为这是反复 E2E 验证过的路径。
下面是一个最小可运行的例子：
export const meta = {
name: "workflow-smoke-test",
description: "Minimal one-agent workflow script smoke test",
phases: [
{ title: "Run", detail: "Spawn one subagent and validate structured output" },
],
}
phase("Run")
const result = await agent(
"Return ok=true and message exactly WORKFLOW_SCRIPT_SMOKE_OK. Do not use tools.",
{
label: "smoke-agent",
phase: "Run",
model: "haiku",
schema: {
type: "object",
properties: {
ok: { type: "boolean" },
message: { type: "string" },
},
required: ["ok", "message"],
additionalProperties: false,
},
},
)
return {
ok: result.ok === true && result.message === "WORKFLOW_SCRIPT_SMOKE_OK",
result,
}
这里有几个关键点：
第一，meta 定义这个 workflow 的名称、描述和阶段。
第二，phase() 用来声明当前执行阶段。
第三，agent() 用来启动 subagent。
第四，schema 用来约束 subagent 的结构化输出。
第五，最后用 return 返回 workflow 的最终结果。
这已经不是普通 prompt，而是一个可以复跑、可以检查 artifact、可以被别人复用的工作流。
下面是几类我认为最值得做成 Workflow script 的场景。
这是 Workflow 最典型的场景。
比如一个仓库可以拆成：
每个 reviewer 只看自己的分片，最后 aggregator 汇总结果、去重、排序。
这种模式比”请审查整个仓库”稳定得多。
一个 PR 可以让多个 agent 同时检查：
最后给出：
这比单 agent review 更有覆盖面。
适合文档、方案、Prompt、Release Note。
流程可以是：
这个模式很适合需要质量闭环的内容生产。
可以让不同 agent 分别研究：
然后由 synthesizer 生成最终报告。
这种 workflow 一旦跑通，就可以反复用于不同技术主题。
比如你有 4 个 prompt 版本，不知道哪个更好。
Workflow 可以并行测试多个版本，然后由 judge agent 评分和排序。
这比人工复制粘贴 prompt 做对比高效很多。
可以，而且这可能是 Workflow 最有想象力的地方。
以前大家共享的是 prompt、skill、MCP server。
现在，至少在工作流编排这个层面，大家可以共享：
deep-research.workflow.mjs
pr-review.workflow.mjs
large-codebase-review.workflow.mjs
prompt-eval.workflow.mjs
release-gate.workflow.mjs
别人拿到脚本后，只要环境支持 Workflow，就可以复用这套工作流。
这意味着什么？
意味着”如何组织多个 agent 做事”本身，也可以变成开源资产。
以前我们共享的是能力。
现在我们可以共享流程。
Workflow 很强，但不代表它可以无监督使用。
我在实际测试中也看到过边界。
比如用 Workflow 做代码审查时，它能快速发现很多高价值问题，但也可能把某些问题严重级别判断过高。一个看似 SQL 注入的 finding，人工复核后发现上游已经有 UUID/prefix 正则约束，所以不能直接定性为 critical。
还有一次生成-批评-修复 workflow 中，因为 schema 字段叫 ok，critic 把它理解成”草稿是否合格”，返回了 ok=false，导致脚本最终断言失败。后来把字段改成 reviewed，结果就稳定了。
这说明两点：
第一，Workflow 能提升覆盖面，但不能替代工程判断。
第二，Workflow 的 schema 设计非常关键。
所以我建议：
Workflow({ scriptPath }) 执行Workflow 的价值，不是让 Claude Code 多叫几个 agent。
它真正的价值是：
把 Agent 编排变成代码。
这件事会带来三个变化。
第一，复杂任务可以复跑。
第二，优秀工作流可以共享。
第三，多 Agent 协作可以从”模型临场发挥”，变成”脚本化、结构化、可观察的工程流程”。
这也是为什么我认为 Workflow 值得重点关注。
它现在还不是正式公开能力，也不适合被包装成稳定平台 API。
但如果你已经在深度使用 Claude Code，尤其是已经在使用 Subagents、Agent Teams、Skills，那么 Workflow 很可能会成为你下一阶段最重要的效率杠杆。
未来如果官方正式公开这个能力，我们大概率会看到大量 workflow script 项目出现：
那时，大家共享的就不只是 prompt，而是完整的多 Agent 工作流。
这可能才是 Claude Code Workflow 最值得期待的地方。
本期内容到这里，欢迎大家点赞、关注和转发，谢谢大家观看。
]]>/goal 是 OpenAI 在 Codex CLI 0.128.0（2026 年 4 月 30 日发布）中新增的一条命令。它不是又一个普通的提示词模板，而是 Codex 内部新增了一整套目标生命周期管理机制——给一个目标，Codex 会自己一轮接一轮往下推进，真正实现无人值守。社区里已经出现连续运行 21 小时、烧掉 9 亿 token 的案例。这篇笔记把我自己踩过的坑、固定下来的工作流、配套的 Skill 全都整理成保姆级教程。
🚀 本篇笔记所对应的视频：
/goal 是什么，以及它为什么重要/goal 是 OpenAI 在 Codex CLI 0.128.0（2026 年 4 月 30 日发布）中新增的一条命令。官方更新日志的原话是：
Added persisted /goal workflows with app-server APIs, model tools, runtime continuation, and TUI controls for create, pause, resume, and clear.
翻译成大白话就是：/goal 不是又一个普通的提示词模板，而是 Codex 内部新增了一整套目标生命周期管理机制。它由四个层面共同构成：
active / paused / achieved / unmet / budget_limited）thread/goal/{get, set, clear} 三个接口，让客户端可以读写目标状态get_goal、create_goal、update_goal 三个工具，让模型可以查询和声明完成，但不能自己暂停/清空/篡改这套机制最直观的效果就是：给一个目标，Codex 会自己一轮接一轮往下推进，真正实现无人值守。社区里已经出现连续运行 21 小时、烧掉 9 亿 token 的案例；我自己测试中也跑过几个小时不间断的批量重构任务。
如果你之前听说过 Ralph Loop（用脚本反复让 agent 跑同一个目标的工作流），/goal 就是 OpenAI 把它做进了 Codex 内核里。OpenAI 总裁 Greg Brockman 在 X 上的原话是：“codex now has a built in Ralph loop++”。比起外部脚本驱动的 Ralph Loop，内置版本的优势在于：目标可以跨会话恢复、token 预算是一等公民、暂停/恢复是原生命令，而且不需要每轮重建上下文，产出质量明显更稳。
/goal 解决了哪些以前解决不了的问题理解 /goal 价值的关键，是它到底解决了什么以前没办法解决的问题。我归纳为四点：
普通 prompt 是写在 Codex 的对话流里的。一旦上下文超过阈值触发 /compact，或者你切换会话，prompt 就可能被压缩、被覆盖、被丢失。/goal 不一样，它把”目标”作为独立的 thread 状态存起来，跟对话历史是两回事。所以：
/compact 压缩对话历史，不会破坏 goal 状态codex resume <id> 还能续上之前的 goal注意一个已知问题：Issue #19910 报告，如果
/compact发生在一轮模型调用执行的中间，延续提示词不会被重新注入，下一个 agent 可能丢掉目标和审计要求。如果你计划做超长任务，尽量让自动 compaction 落在轮次边界而不是手动压缩。
这是 /goal 最低估的部分，但也是最关键的部分。
每一轮空闲后，Codex 会自动向模型注入一段叫 continuation.md 的提示词（源码在 codex-rs/core/templates/goals/continuation.md）。这段提示词的核心要求是这样的（直译关键段落）：
在判定目标已达成之前，执行一次”完成审计”：
- 把目标重述为具体的交付物或成功标准
- 构建一份提示词到产物的清单，把每一条显式要求、每一个编号项、每一个具名文件、命令、测试、门禁、交付物映射到具体证据
- 检查相关文件、命令输出、测试结果、PR 状态等真实证据
- 不要把代理信号当成完成证据：测试通过、清单填满、verifier 跑成功、写了大量代码 —— 这些只是辅助信号，不能单独作为完成依据
- 把不确定视作未达成；继续验证或继续工作
以及一段非常关键的反偷懒规则：
不要依赖你的意图、阶段性进度、已耗费精力、对早前工作的记忆、或一个看上去合理的最终答案，作为完成的证明。只有审计显示目标确实已达成、且没有遗留必需工作时，才能调用
update_goal标记完成。
这套机制是在解决一个具体的痛点：模型在长任务中习惯”sandbag”（早早声称做完然后偷懒）。/goal 把这种倾向用机制压住了 —— 但前提是你给的目标必须能被映射成一份清单。
/goal 支持设置 token 预算上限。一旦烧到上限，Codex 不会粗暴中断当前轮次，而是注入另一段提示词 budget_limit.md，让模型把当前任务收尾：总结已完成的进度、列出剩余工作、给出下一步建议，然后停下。
对于无人值守场景，这意味着即使你设错了预期或者目标比想象中复杂，你也能在第二天打开终端时拿到一份能看懂的进度报告，而不是一堆半成品和没了的 token。
/goal 提供四条 TUI 命令：
| 命令 | 作用 |
|---|---|
/goal <objective> |
创建或替换当前目标 |
/goal |
显示当前目标摘要（状态、目标内容、耗时、token 用量） |
/goal pause |
暂停延续 |
/goal resume |
恢复暂停的目标（早期叫 /goal unpause，后来 PR #20082 改名了） |
/goal clear |
清空当前目标 |
注意：暂停/恢复/清空/预算限制状态的转换，模型自己改不了，只能由用户或运行时触发。这是设计上的安全边界 —— 模型唯一能自己做的状态变更是”标记完成”，而且这个动作还得通过完成审计。
/goal，什么场景不要用/goal 很强，但不是所有任务都该用它。盲目用反而费 token、跑偏、卡死。我的判断标准是这样的：
/goal/goal 跑/goal/goal 给我开发一个背单词 APP。没有验收标准，Codex 会幻想出一个目标然后认真去实现，但实现出来的不是你要的。/goal 的特点是会自己往下推进，这种场景下风险会被放大。/goal 反而徒增开销。/plan 模式下，即使你看到 UI 上显示 “Goal active”，Codex 实际上不会自动延续。源码里 should_ignore_goal_for_mode 函数在 Plan 模式下直接跳过 goal 延续。所以如果你要用 /plan 做规划，先退出 Plan 模式再启动或恢复 /goal。/goal/goal 目前是实验性功能，默认关闭，需要手动开启。
打开 ~/.codex/config.toml，加上下面这段：
[features]
goals = true
如果你想完整体验所有相关功能（尤其是 /plan 配合 /goal），可以把协作模式也打开：
[features]
goals = true
collaboration_modes = true
保存，然后重启 Codex，/goal 就可用了。
如果你不熟悉配置文件的位置和写法，可以直接在 Codex 里用自然语言描述，比如：
请帮我开启 Codex 0.128 新增的 /goal 命令。
配置文件位置：~/.codex/config.toml
需要在 [features] 段下加上 goals = true。
如果文件不存在请创建，如果 [features] 段不存在请新增。
Codex 会自动帮你完成。改完别忘了重启。
启动后输入 /，如果在斜杠命令补全列表里能看到 /goal，说明已经启用。也可以直接输入 /goal 回车，如果显示”暂无目标”或者类似的状态摘要，就是好了。
/goal 提示词的核心心法我在最初使用 /goal 的时候，踩过一个最典型的坑：直接 /goal 加一句简短描述就回车走人。结果几个小时回来一看，Codex 跑了一堆事情，但跑的根本不是我要的；甚至有时候会陷入静默卡死状态。
后来我把这个事情想清楚了：/goal 对提示词的要求，比普通对话高一个数量级。原因是它的内置审计机制 —— continuation.md 要把你的目标映射成一份”提示词到产物”的清单，如果你用的是模糊词（”全部”、”所有”、”彻底”、”清理一下”、”提升一下”），清单根本建不起来，审计就会退化成”测试跑过了就算完成”这种代理信号 —— 然后你就得到一个声称完成、实际跑偏的结果。
所以 /goal 真正发挥威力的前提，是你要能写出可被映射成清单的目标。
经过这段时间的实践，我固定下来一套五段式模板，几乎所有 /goal 我都按这个写：
/goal <一句话描述目标>
Scope: <作用范围 — 改哪些文件/子系统/feature 区域，其他不要碰>
Constraints:
- <硬性约束 1 — 比如"不要修改数据库 schema">
- <硬性约束 2 — 比如"保持现有公开 API 不变">
- <硬性约束 3 — 项目类型相关的默认规则>
Done when:
1. <可验证的产物 1 — 引用具体文件名或命令>
2. <可验证的产物 2>
3. <可验证的产物 3>
...
Stop if:
- <机械可识别的停止条件 1 — 比如"需要新依赖">
- <机械可识别的停止条件 2 — 比如"需要修改 MUST NOT 列表中的文件">
Use a token budget of <N> tokens for this goal.
每一段的要点：
project.pbxproj“就比”不要破坏现有结构”好。npm test、pytest -q、tsc --noEmit 都比”测试通过”明确）。/goal 把 src/data/words.json 里的词库扩展到 1000 个唯一词条。
Scope: 只改 src/data/words.json，其他文件不要动。
Constraints:
- 词条 schema 保持不变（id / word / phonetic / meaning / example）
- 不允许重复词条（以 word 字段为准去重）
- 只能用真实的、常见的英语单词，不要生造
Done when:
1. words.json 包含恰好 1000 个唯一词条
2. 所有词条 schema 校验通过（用 tools/validate.js 跑一遍）
3. 在终端输出最终词条数和文件大小
Stop if:
- 需要修改 words.json 以外的任何文件
- 需要新增 npm 依赖
- 出现 schema 校验失败超过 3 次
Use a token budget of 80000 tokens.
这个目标可以被审计 —— 每一条 Done when 都对应一个能跑的检查；每一条 Stop if 都是机械可识别的；Scope 把作用面锁死了。这种 goal Codex 跑起来准确率明显不一样。
下面是我目前固定下来的三种 /goal 用法。从简单到复杂，按任务规模选用。
/goal 直接用 — 适合中等任务适合任务边界清楚、自己能写出五段式模板的场景。直接在 Codex 里输入完整的 /goal <五段式提示词>，回车，然后该干嘛干嘛去。
跑起来后，你随时可以：
/goal（不带参数）查看当前进度：状态、耗时、token 用量/goal pause 暂停/goal resume 恢复/goal clear 中止这是最常用的形态。70% 的任务我都是这样跑的。
/plan + /goal — 适合复杂任务如果任务复杂、需求还比较模糊、自己也没想清楚验收标准，直接 /goal 是不行的，要先用 /plan 把方案讨论清楚。
完整流程：
/plan 或者 Shift+Tab 切换）Shift+Tab 退出 Plan 模式/goal 执行上面的开发计划，加上 Done when / Stop if / token budget为什么要先选”保持 Plan 模式”再手动退出？因为前两个选项会立刻执行，但执行的不是 /goal 模式，享受不到延续和审计；而你直接在 Plan 模式里输入 /goal，会落入 Issue #20656 的坑（看上去激活了但其实不延续）。所以必须先退出 Plan 模式，再下 /goal。
/goal — 适合规格驱动开发这是最适合 /goal 的工作流之一。Spec-Driven Development（SDD）的思路是：先把需求写成规格文档（包含 proposal、specs、design、tasks），然后让 AI 严格按规格实现。规格文档天然就是一份审计清单 —— 把它喂给 /goal，完成审计能精准地工作。
OpenSpec 是 Fission-AI 团队开发的开源 SDD 工具（MIT 协议，GitHub 上 37k stars），它的工作方式是这样的：
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — 为什么要做、改了什么
✓ specs/ — 需求和场景
✓ design.md — 技术方案
✓ tasks.md — 实现清单
Ready for implementation!
完整工作流：
OpenSpec 需要 Node.js 20.19.0+。安装命令：
npm install -g @fission-ai/openspec@latest
进入项目目录，初始化：
cd your-project
openspec init
OpenSpec 会在项目里生成 openspec/ 目录，并把适配你 AI 工具的指令写到对应的位置（它支持 20+ 种 AI 工具，Codex 也在里面）。
在 Codex 里直接输入（/opsx:propose 是 OpenSpec 安装后注册的斜杠命令）：
/opsx:propose 为这个项目新增 Cohere Rerank 作为第五个 Rerank provider
Codex 会调用 OpenSpec，把你的需求拆解成 proposal.md、specs/、design.md、tasks.md。这一步不会动你任何源代码，只是把”要做什么”写清楚。
/goal 执行规格规格文档生成完后，在 Codex 里：
/goal 严格实现 openspec/changes/add-cohere-rerank/ 中描述的变更。
First action: 先读 proposal.md / specs/ / design.md / tasks.md / AGENTS.md 这五个文件，
报告每个文件的字数和关键章节标题，等我确认后再开始实现。
Scope: design.md 里的 "MUST NOT modify" 列表严格遵守。
Constraints:
- AGENTS.md 中的所有 iron rules 不可违反
- 不允许新增 npm 依赖
- 镜像现有 4 个 Rerank provider 的代码风格
Done when:
1. tasks.md 中的每一项都打勾，引用对应文件路径
2. 每条 SHALL 都有对应的通过测试，引用测试名
3. 每个 GIVEN/WHEN/THEN 场景都有集成测试覆盖
4. `npx tsc --noEmit` 退出码 0
5. `npm test` 退出码 0，粘贴汇总输出
6. README.md 在 provider 表格里加上新一行
7. CHANGELOG.md 在 Unreleased 段加条目
Stop if:
- 任何任务需要修改 MUST NOT 列表中的文件
- SHALL 之间出现冲突（暂停，让我决定）
- 需要 npm install 新依赖
- 现有 Rerank provider 测试出现失败
Use a token budget of 120000 tokens.
注意第二行的 First action：这是个非常关键的小技巧。它强制 Codex 在动手前先把规格文件全部读一遍并向你报告确认 —— 防止 Codex 用 @filename 等不可靠引用方式假装”知道”了规格，实际上没读全。
这种工作流跑出来的产物质量最稳。我自己测试中，中等规模的 feature（类似新增一个 provider 这种 200~400 行的改动）基本都能一次跑通，跑完直接是个能 review 的 PR。
goal-prompt-builder 把上面这些自动化写好五段式提示词需要练习。如果不熟练，或者懒得每次手写，可以用我开发的 goal-prompt-builder —— 一个专门用来生成 /goal 提示词的 Claude Skill，仓库在：
https://github.com/win4r/goal-prompt-builder （MIT 协议）
/goal 内置的 continuation.md 审计机制非常强，但前提是你的目标文本能被映射成清单。这个 skill 的核心目的就是：保证生成的目标文本一定可以被映射成审计清单。
按 README 描述，skill 触发后会走 6 步：
package.json、Cargo.toml、*.xcodeproj 等）或者抓 GitHub README，顺便读 AGENTS.md / CLAUDE.md/goal 提示词，加一段简短的设计说明它内部有一组硬规则（从 continuation.md 倒推出来的）：
@filename 引用不准我用这个 skill 之后，日常写 /goal 的速度快了非常多 —— 简单任务一两分钟就能从一句话需求走到一个可用的 5 段式提示词。
按 README，有三种方式：
curl -L -o /tmp/goal-prompt-builder.skill \
https://github.com/win4r/goal-prompt-builder/raw/main/goal-prompt-builder.skill
mkdir -p ~/.claude/skills
unzip -o /tmp/goal-prompt-builder.skill -d ~/.claude/skills/
rm /tmp/goal-prompt-builder.skill
git clone https://github.com/win4r/goal-prompt-builder.git
ln -s "$(pwd)/goal-prompt-builder/goal-prompt-builder" ~/.claude/skills/goal-prompt-builder
如果你不熟命令行，直接在 Codex 里描述安装需求：
请帮我安装这个 skill：https://github.com/win4r/goal-prompt-builder
按 README 的安装方式装到默认位置。
Codex 会自己执行下载、解压、放到对应目录。装完后重启 Codex，skill 就生效了。
注意：这个 skill 是用 Claude Skills 格式构建的，默认安装位置是
~/.claude/skills/。具体在哪个客户端能被识别，以你客户端文档为准 —— README 明确列出的兼容客户端是 Claude Code、Claude Desktop、以及支持 Skills 的 Claude.ai。
安装重启后，skill 会被以下短语自动触发，不需要手动调：
最简单的用法是丢一个一句话需求进去，比如：
我想用 /goal 给这个项目增加 Cohere Rerank 作为第五个 Rerank provider
skill 会：
package.json）AGENTS.md / CLAUDE.md 提取项目特定的规则/goal + 一段设计说明，告诉你为什么这样写把输出粘贴到 Codex 的输入框，回车，任务就跑起来了。
这些是我自己踩过、或者社区在 GitHub Issue 里报告过的坑。直接列出来，贴在显示器旁边比什么都管用。
/goal 不延续现象：UI 上显示 “Goal active”，但 Codex 不会自己往下推进，看上去像卡死了。
原因：Issue #20656。源码里 should_ignore_goal_for_mode(mode) -> mode == ModeKind::Plan。Plan 模式下 goal 延续被静默跳过。
对策：用 /plan 做规划时不要同时启动 /goal。规划完先退出 Plan 模式（Shift+Tab），再下 /goal。
/compact 把 goal 上下文搞丢现象：跑了一段时间，模型突然好像”忘了”目标的细节，开始做不相关的事，或者过早声称完成。
原因：Issue #19910。如果 /compact 发生在一轮模型调用执行的中间，延续提示词不会被重新注入，后续 agent 丢掉目标和审计要求。
对策：长任务不要手动 /compact。设一个相对宽松的 token 预算，让自动 compaction 落在轮次边界上。
/goal，之后 resume 列表里找不到这个会话现象：codex resume 列表、Codex Desktop 的 recents 里都看不到这个 thread，但 thread 本身没丢，知道 ID 还能打开。
原因：Issue #20792。/goal-first 的 thread 在列表里被遗漏了。
对策：新 thread 第一条消息别用 /goal。先随便发一句话，比如 “Working on the OAuth migration goal”，再用 /goal。
现象：跑了几个小时回来，声称做完了，但你一看实际改动只是边边角角，核心问题没动。
原因：这些词没法被 continuation.md 映射成清单，审计退化成”测试跑过 = 完成”。
对策：换具体的数字或可验证的状态。”修 5 个真实可复现的 bug”、”覆盖 README 列出的 3 条用户路径”、”pytest 0 失败 0 跳过” —— 这些都比”修复所有 bug”强一万倍。
现象：任务跑飞，token 烧光也没人提醒，等回来一看账单不对劲。
对策：永远设 token budget。Use a token budget of <N> tokens for this goal.。烧到上限会触发软停止，让模型把工作收尾，而不是裸停。
现象：让 Codex 做迁移，跑着跑着把数据库 schema 改了 / 把不该删的文件删了。
对策：破坏性操作不要用 /goal。必须用的话，Constraints 里明确写”不要执行 rm -rf“、”不要修改数据库 schema”、”任何 destructive migration 暂停问我”，并且把对应内容也写进 Stop if。
| 操作 | 命令 |
|---|---|
| 创建/替换目标 | /goal <objective> |
| 查看当前目标摘要 | /goal（不带参数） |
| 暂停 | /goal pause |
| 恢复 | /goal resume |
| 清空 | /goal clear |
| 退出 Plan 模式 | Shift+Tab |
| 跨会话恢复 thread | codex resume <id> |
状态标识：
pursuing / active — 正在自主推进paused — 被手动暂停achieved / complete — 完成审计通过，目标达成unmet — 未达成budget_limited — token 预算耗尽，软停止中每次发 /goal 之前，过一遍这个清单：
/goal 吗？（单轮能干完的别用）/goal 消息再说跑起来之后：
/goal pause，补上下文，再 /goal resume/goal 查进度/compact最近半年，prompt 写法明显在变化：
/goal 是这个方向走得最远的产物之一。它把”过程指挥”压到最低、把”结果声明”提到最高，然后用一套内置审计机制保证模型不偷懒。
但反过来，这也提高了对”会写需求”的要求。模型越来越能干，但它干得好不好，反过来更依赖你能不能把”到底要啥”说清楚。会写需求这件事，正在重新变成稀缺技能。
以前 prompt 糊一点没事，反正它也只跑几秒钟；现在它能跑一整天，你那条糊掉的 goal，换来的就是一整天的糊产出。
/goal 的真正价值不在于”它能跑一整天”，而在于它把”AI 真的能替你跑一整天”这件事，从一个需要外部脚本 + 反复试错的工程，变成了一条可以直接在终端里下的命令。剩下的事，是把目标写清楚。
GitNexus 被作者称作代码库的神经系统，核心理念只有一句话：AI Agent 不应该盲目编辑代码。它把代码仓库索引为知识图谱，再通过 MCP 协议把这份图谱喂给 Codex、Claude Code、Cursor 等 AI 编程助手，让它们在动手改代码之前就能完整地感知项目结构、依赖关系和”爆炸半径”。
🚀 本篇笔记所对应的视频：
传统 AI 编程工具最大的问题是：它们看到的是代码片段，而不是代码结构。
无论是 Claude Code、Codex 还是 Cursor，本质上都是通过 Glob / Grep 一段一段地读文件。如果不借助外部工具，它们对项目的全貌缺乏感知，很容易出现”盲改代码”的情况——改了一个函数的返回类型，根本不知道有几十个调用方会被破坏；重构一个模块，不知道下游有哪些隐藏依赖。
GitNexus 的解题思路是：在索引阶段就把调用链、聚类、置信度评分全部预计算好，AI 工具一次调用 MCP 就能拿到完整的结构化上下文。这样既提升了改动的可靠性，又节省了 Token，甚至让小模型也能胜任原本需要大模型才能处理的复杂任务。
GitNexus 内置了 7 个 MCP 工具，每一个都对应一个具体的开发痛点：
| 工具 | 用途 |
|---|---|
impact |
爆炸半径分析——改这个函数会波及哪些代码 |
context |
360 度符号视图——某个符号的完整上下游关系 |
query |
进程感知的混合搜索（BM25 + 语义向量） |
detect_changes |
Git diff 风险评估，配合 PR Review |
rename |
跨文件协调重命名 |
cypher |
原始图查询，给高级用户用 |
list_repos |
全局仓库注册表 |
这是 GitNexus 最值得称道的一点：索引、解析、聚类、图构建都是完全本地化的。即便是嵌入向量（用于语义搜索），它也是通过本地的 transformers.js 跑 Hugging Face 嵌入模型，不调用任何 LLM API，不消耗任何 Token。
你只在用 gitnexus wiki 自动生成项目文档时才会用到 LLM API（默认 OpenAI 的 gpt-4o-mini，可以通过 --base-url 切换到任意 OpenAI 兼容协议的服务）。日常的索引、查询、影响分析等核心功能，一个 API Key 都不需要。
支持主流的 TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP 等编程语言，覆盖绝大多数生产项目的技术栈。
不少朋友会问 GitNexus 和 Graphify 怎么选，这里直接给一个对照：
| 维度 | GitNexus | Graphify |
|---|---|---|
| 定位 | AI Agent 的代码地图 | 跨模态知识编译器 |
| 关注点 | 调用链、爆炸半径、类型解析 | 代码、文档、论文、图像、视频统一图谱 |
| 索引 LLM 开销 | 零 Token | AST 通道零开销，语义通道有 LLM 消耗 |
| 触发方式 | MCP 协议 | Skill 触发 |
| 输出 | 实时查询的结构化上下文 | Git 友好的静态产物（团队共享） |
简单概括：
两个项目互不冲突，叠加使用效果更好。
npm install -g gitnexus
如果你担心 npm 全局目录权限问题，可以提前把全局目录改到家目录下：
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
之后所有的 npm install -g 都不再需要 sudo。
gitnexus --version
输出版本号即说明安装成功。
gitnexus setup
这条命令会自动检测本地装的 Cursor、Claude Code、OpenCode、Codex、Windsurf 等 MCP 兼容编辑器，把 GitNexus 的 MCP server 配置一次性写入所有编辑器的全局 MCP 配置文件，同时安装对应的 Skill。
如果你只想配置 Claude Code，也可以单独执行：
claude mcp add gitnexus -- gitnexus mcp
Windows 用户请使用：
claude mcp add gitnexus -- cmd /c gitnexus mcp
配置完成后，完全退出再重启 Claude Code——MCP server 只在启动时初始化，配置改了必须重启才会生效。
下面以一个真实项目为例：为 OpenClaw 开发的记忆插件 memory-lancedb-pro，看看完整的索引流程。
cd ~/Desktop/project/memory-lancedb-pro
gitnexus analyze
这条命令会跑完整的 6 阶段管线：Structure → Parsing → Resolution → Clustering → Processes → Search，最终生成 .gitnexus/lbug 数据库，以及配套的 AGENTS.md 和 CLAUDE.md。
实测下来，167 个文件的项目大约 6 秒完成索引；几千文件的项目也只需要几分钟。索引完成后，会提示生成了多少节点、多少边、多少社区（cluster）、多少执行流（flow）——比如本期演示的项目就生成了 6400 个节点、1 万多条边、203 个簇、300 个 flow。
需要注意的是：基础索引不会生成语义向量、模块级 Skill 和诊断细节。也就是说在 Claude Code 里调用 GitNexus 时只能做关键词匹配，无法发挥真正的实力。
gitnexus analyze --embeddings
加上 --embeddings 参数后，GitNexus 会用本地 Hugging Face 嵌入模型为每个 symbol 生成向量。这样 query() 工具就能做真正的自然语言语义搜索，而不只是关键词匹配。
整个过程仍然零 Token、零 LLM 调用，只是索引时间会多 30%–100%（取决于 CPU/GPU 性能）。
gitnexus analyze --embeddings --skills --verbose
这是日常使用的推荐配置：
--embeddings 启用语义搜索--skills 把 Leiden 算法识别的每个功能社区生成独立的 SKILL.md，写到 .claude/skills/generated/<area>/，让 Claude Code 在不同模块工作时拿到精准的局部架构上下文--verbose 打印被跳过的文件，方便诊断索引覆盖率gitnexus list # 查看所有已索引的仓库
gitnexus status # 查看当前仓库索引状态
索引完成后，可以启动本地 HTTP 服务来浏览图谱：
gitnexus serve
默认监听 4747 端口，启动后保持终端运行即可。然后浏览器访问 https://gitnexus.vercel.app，UI 会自动检测本地 4747 端口的 backend，列出所有已索引的仓库。点击对应卡片就能进入图浏览界面。
实测体验：
如果你不想长期占着一个终端，可以把服务放到后台：
nohup gitnexus serve > ~/.gitnexus/serve.log 2>&1 &
需要停止时执行 pkill -f "gitnexus serve" 或 lsof -ti:4747 | xargs kill。
完成索引后，在 Claude Code 中输入斜杠，就能看到 GitNexus 自动注册的几个 Skill，比如 gitnexus exploring、gitnexus debugging、gitnexus pr review。下面分别测试几个高频场景。
直接输入：
分析项目架构
Claude Code 会调用 GitNexus 的 MCP 工具，输出结构化的分析报告：
分析这个项目中 A-MAC 的作用是什么
GitNexus 会基于图谱给出准确的回答：「A-MAC 是智能写入门控」，并给出具体的调用关系和上下文。
这是 GitNexus 最能体现价值的场景：
如果删除 A-MAC 功能会影响哪些代码
输出结果不仅列出了所有受影响的文件，甚至精确到具体的代码行号。这种粒度的分析，没有知识图谱根本做不到。
为了公平对比，我重新克隆了同样的项目，不做任何 GitNexus 索引，开一个干净的 Claude Code 窗口，提同样的问题。
然后再开第三个 Claude Code 窗口，把两边的回复都贴进去，让它客观评判：
「分析这两个 AI 回答的差别，哪个更详细？」
最终结论：
这个对比基本可以说明 GitNexus 在影响分析这类任务上的硬实力。
随便从项目里挑一个 issue，把链接贴给 Claude Code，再用 /gitnexus debugging 触发分析：
/gitnexus debugging 分析这个 issue：<issue 链接>
GitNexus 会输出：
选定路线（比如直接回复「路线 A」）后，Claude Code 会按 GitNexus 给出的方案完成修复，并提供改动摘要和验证方式。
通过 /gitnexus pr review Skill 加上 PR 链接：
/gitnexus pr review <PR 链接>
GitNexus 会基于图谱完成 review。继续追问「如果合并这个 PR 会影响哪些代码」时，它会输出：
gitnexus analyze
GitNexus 会比对已有索引，只处理变更的文件。如果你执行过 gitnexus setup，PostToolUse hook 会在每次 commit 后自动提醒 Claude Code 重新索引，多数情况下不用手动跑。
gitnexus status
会对比 meta.json 里的 lastCommit 和当前 HEAD，告诉你索引是否需要更新。
gitnexus analyze --force
升级 GitNexus 大版本、改动量过大、怀疑索引被污染时使用。
gitnexus clean # 清当前项目
gitnexus clean --all --force # 清所有已注册仓库
gitnexus wiki
这是 GitNexus 唯一会调用 LLM 的命令，默认走 OpenAI 的 gpt-4o-mini。如果想换模型，加 --model 和 --base-url 参数即可，对应的 API Key 通过环境变量提供。
如果你只想要一份能直接拷贝执行的脚本：
# 阶段 0：环境准备（可选）
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# 阶段 1：安装
npm install -g gitnexus
gitnexus --version
# 阶段 2：索引（在你的项目目录下执行）
cd ~/your-project-path
gitnexus analyze --embeddings --skills
# 阶段 3：启动 Web UI
gitnexus serve &
# 浏览器打开 https://gitnexus.vercel.app
# 阶段 4：配置 Claude Code
claude mcp add gitnexus -- gitnexus mcp
# 完全重启 Claude Code
# 阶段 5：日常维护
gitnexus list # 查看所有索引仓库
gitnexus status # 查看当前索引状态
gitnexus analyze # 增量更新
每一步是否成功，可以参考下面这张表自检：
| 阶段 | 验证命令 | 成功标志 |
|---|---|---|
| 安装 | gitnexus --version |
输出 1.6.3 或更新版本 |
| 索引 | cat .gitnexus/meta.json |
看到 nodes / edges / lastCommit 字段 |
| 注册 | cat ~/.gitnexus/registry.json |
出现你的仓库条目 |
| Context 文件 | ls AGENTS.md CLAUDE.md |
两个文件都存在且非空 |
| HTTP server | curl http://localhost:4747/api/mcp |
返回 JSON 而非 connection refused |
| Web UI | 访问 https://gitnexus.vercel.app |
看到仓库列表页面 |
| Claude MCP | 在 Claude Code 里问「列出 GitNexus 工具」 | 列出 7 个工具名 |
通过这一轮实测可以看到，借助 GitNexus，AI 编程工具就能对代码库有更深入、更全面的理解：
而且这一切的代价仅仅是一次本地索引，不消耗任何 Token，不需要任何 LLM API。对于希望让 Claude Code、Codex、Cursor 这类工具在自己代码库上变得真正靠谱的开发者来说，GitNexus 几乎是一个零成本的能力增强。
如果你前面已经在用 Graphify 处理跨模态知识，那么把 GitNexus 加进来，就等于把代码侧的”全局视野”也补齐了——一个负责语义，一个负责结构，配合起来才是完整的 AI 编程工作流。
本期内容到这里，欢迎大家点赞、关注和转发，谢谢大家观看。
]]>今天给大家介绍一个非常硬核的开源项目——notebooklm-py。它通过逆向 NotebookLM 的内部 API，把所有功能（包括 Web 端没暴露的）都做成了 Python API + CLI + AI Agent Skill 三件套。
⚠️ 重要提示：这是非官方库，使用的是 Google 未公开的内部接口，存在 API 随时变动的风险。适合做原型、做研究、做个人项目，不建议用在生产环境。
先看一张能力总览：
| 模块 | 能力 |
|---|---|
| 笔记本 | 创建、列出、重命名、删除 |
| 资料源 | URL、YouTube、PDF、Markdown、Word、音视频、图片、Google Drive、纯文本，都能批量导入 |
| 对话 | 提问、查看历史、自定义 Persona |
| 研究 | Web 研究 / Drive 研究 Agent，支持快速 / 深度两种模式，结果自动入库 |
| 分享 | 公开 / 私有链接、用户权限（查看 / 编辑） |
| 生成 | 音频概览、视频概览、PPT、信息图、测验、闪卡、报告、数据表、思维导图 |
这才是这个项目最值钱的地方：
光这几条就值得一试。
win4r 这个 fork 把版本锁定在 v0.3.4-hermes.4，附带了一份 SECURITY_AUDIT.md 安全审计报告，比直接装 PyPI 上的版本更稳。
pip install "git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
pip install "notebooklm-py[browser] @ git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
playwright install chromium
加上 [browser] extra 后就能用 Playwright 自动登录，省掉手动复制 cookie 的麻烦。
如果你是 Hermes 用户：
VIRTUAL_ENV=~/.hermes/hermes-agent/venv uv pip install \
"notebooklm-py[browser,cookies] @ git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
~/.hermes/hermes-agent/venv/bin/playwright install chromium
mkdir -p ~/.local/bin
ln -sf ~/.hermes/hermes-agent/venv/bin/notebooklm ~/.local/bin/notebooklm
最后这行 ln -sf 是把 notebooklm 命令软链到 ~/.local/bin/，这样在终端任何位置都能调用。
NotebookLM 没有 OAuth，所以认证只能靠 cookie。项目提供了三种方案，首推方案一。
notebooklm login --browser-cookies chrome
notebooklm auth check --test
这条命令会自动从你已登录的 Chrome 里读 cookie，几乎零配置。
由于 Google session 通常 15-30 分钟就过期，强烈建议在 ~/.hermes/.env（或你常用的 shell rc 文件）里加一行：
NOTEBOOKLM_REFRESH_CMD=notebooklm login --browser-cookies chrome
设置后，cookie 过期时会自动透明刷新，你不会感知到。
notebooklm login
# 企业 SSO 用户用 Edge：
notebooklm login --browser msedge
会弹一个浏览器窗口让你扫码 / 输密码，登完自动保存。
装一个浏览器扩展叫 “Get cookies.txt LOCALLY”，导出 JSON 后：
python3 skills/notebooklm/import_browser_cookies.py /tmp/nb_cookies.json
rm /tmp/nb_cookies.json # ⚠️ 用完立刻删，里面是你的 Google 登录态
🔐 安全提示：
~/.notebooklm/storage_state.json存的就是你的 Google 登录凭证，当成密码看待。项目自带.gitignore屏蔽，但别手贱去git add -A。
CLI 是最适合脚本化的入口，下面是一份”从零到产出”的完整 demo。
notebooklm create "AI 研究"
notebooklm list # 列出所有笔记本
notebooklm use <notebook_id> # 把某个笔记本设为当前默认上下文
use 之后，后续所有命令都默认作用在这个笔记本上，不用每次都传 ID。
# 网页
notebooklm source add "https://arxiv.org/abs/2501.12345"
# 本地 PDF
notebooklm source add "./paper.pdf"
# 让 NotebookLM 自己去 Web 上找资料并自动入库
notebooklm source add-research "Diffusion Transformer"
source add-research 是真·杀器：传一个关键词，它会调用 NotebookLM 的 Research Agent 去全网检索，结果自动塞进笔记本，省掉你自己搜 + 整理的功夫。
notebooklm ask "总结一下这些论文的核心方法"
# 音频概览（播客）
notebooklm generate audio "make it engaging" --wait
# 视频概览（白板风格）
notebooklm generate video --style whiteboard --wait
# 电影感视频（纪录片风格）
notebooklm generate cinematic-video "documentary-style" --wait
# 测验
notebooklm generate quiz --difficulty hard
# 闪卡
notebooklm generate flashcards --quantity more
# PPT
notebooklm generate slide-deck
# 信息图
notebooklm generate infographic --orientation portrait
# 思维导图
notebooklm generate mind-map
# 数据表（用自然语言描述结构）
notebooklm generate data-table "对比各论文的核心方法、数据集、评测指标"
--wait 参数会一直 poll 到任务完成，省掉自己写轮询逻辑。
notebooklm download audio ./podcast.mp3
notebooklm download video ./overview.mp4
notebooklm download cinematic-video ./documentary.mp4
notebooklm download quiz --format markdown ./quiz.md
notebooklm download flashcards --format json ./cards.json
notebooklm download slide-deck ./slides.pdf # 也支持 .pptx
notebooklm download infographic ./infographic.png
notebooklm download mind-map ./mindmap.json
notebooklm download data-table ./data.csv
注意 quiz / flashcards 的 --format 选项，这是 Web UI 完全没有的能力。
notebooklm auth check --test # 检查登录状态
notebooklm metadata --json # 输出当前笔记本元数据
notebooklm share status # 查看分享设置
notebooklm language list # 列出 50+ 语言代码
CLI 适合写脚本，Python API 适合接进自己的应用。整个库基于 asyncio，下面是一个标准用法：
import asyncio
from notebooklm import NotebookLMClient
async def main():
async with await NotebookLMClient.from_storage() as client:
# 1. 创建笔记本，导入网页
nb = await client.notebooks.create("Research")
await client.sources.add_url(
nb.id,
"https://example.com",
wait=True,
)
# 2. 提问
result = await client.chat.ask(nb.id, "Summarize this")
print(result.answer)
# 3. 生成 + 下载播客
status = await client.artifacts.generate_audio(
nb.id,
instructions="make it fun",
)
await client.artifacts.wait_for_completion(nb.id, status.task_id)
await client.artifacts.download_audio(nb.id, "podcast.mp3")
# 4. 生成 + 导出测验为 JSON
status = await client.artifacts.generate_quiz(nb.id)
await client.artifacts.wait_for_completion(nb.id, status.task_id)
await client.artifacts.download_quiz(
nb.id,
"quiz.json",
output_format="json",
)
# 5. 生成 + 导出思维导图 JSON
await client.artifacts.generate_mind_map(nb.id)
await client.artifacts.download_mind_map(nb.id, "mindmap.json")
asyncio.run(main())
几个关键点：
NotebookLMClient.from_storage() 会自动读 ~/.notebooklm/storage_state.json，不需要你管 cookieasync with 会保证 client 优雅退出，连接不泄漏task_id，配合 wait_for_completion 实现异步轮询download_quiz 这种 API 多了一个 output_format 参数——这就是 Web UI 拿不到的”结构化导出”这是整个项目最有想象力的玩法——把 NotebookLM 变成 AI Agent 的工具。
npx skills add win4r/notebooklm-py
一行命令搞定。装完之后，Claude Code 就能用自然语言驱动整个 NotebookLM 流程，比如你跟它说：
“把这 10 篇论文导入新笔记本，生成一个深度播客和思维导图，导出到 ./output/”
它会自己去调 notebooklm create → source add → generate audio → download 全流程。
.agents/ 目录方式notebooklm skill install
会把 Skill 写到当前项目的 .agents/ 下，只在当前项目生效，适合给具体项目定制。
hermes skills tap add win4r/notebooklm-py
hermes skills install win4r/notebooklm-py/skills/notebooklm --force
记得先装 Python 包（参见第二节），并且把自动刷新命令塞到 ~/.hermes/.env：
NOTEBOOKLM_REFRESH_CMD=notebooklm login --browser-cookies chrome
Hermes 子进程会自动继承这个环境变量，cookie 过期不用你管。
每天早上跑一个定时任务：
source add 进同一个笔记本generate audio --wait通勤路上听昨天的论文摘要——比逛 Twitter 高效十倍。
老师 / 培训讲师特别适合：
接到 Claude Code / OpenClaw 之后：
“调研 NotebookLM 的所有竞品，每个都生成一份对比报告，最后产出一张数据表”
Agent 会自己跑 add-research → generate report → generate data-table → download data-table，全程不用你点鼠标。
API 不稳定性：Google 可能随时改内部接口。如果哪天突然报错，先 git pull 看看 fork 有没有更新，或者去 upstream 看 issue。
Cookie 过期：默认 15-30 分钟，一定要配 NOTEBOOKLM_REFRESH_CMD，否则跑长任务跑一半挂掉很烦。
Linux + Playwright：第一次装可能缺系统依赖，跑一下 playwright install-deps chromium 即可。
存储路径：~/.notebooklm/storage_state.json 是登录态文件，别上传到任何地方（包括 GitHub Gist、ChatGPT 截图）。
生产慎用：再说一遍，这是非官方接口，千万别接到生产业务——一旦 Google 改 API，你的服务就挂了。
如果你符合下面任何一条，这个项目值得花 10 分钟试一下：
项目地址再贴一遍：
如果只是普通用法、不需要 Hermes，建议直接用 upstream（更新更快）；如果你是 Hermes 用户或者特别在意安全审计，就用 win4r 这个 fork（带 audit report 和锁版本）。
NotebookLM 本身已经是 2026 年最被低估的 AI 工具之一，再叠加 notebooklm-py 之后，它从一个”网页版 AI 研究助手”直接升维成了”可编程的知识基础设施“。
值得玩。
]]>官方给它的定义只有一句话——
“A new era of image generation.”（图像生成的新纪元）
轻描淡写，却野心毕露。
如果说上一代AI画图是”听得懂话的画师”，那么2.0这一代，更像是一个”既懂设计、又懂排版、还懂文化”的全能创作搭子。
从官方放出的大量样图来看，这次升级主要踩在了几个关键词上：
以前你让AI画一幅海报，得到的可能是”大概那个意思”。现在，连一张桌面截图里的macOS图标、文件命名、窗口层级，它都能精细还原。Designer看了直呼内行。
中文、日文、韩文、阿拉伯文……以往AI一写非英文就变”鬼画符”的尴尬，这次被一次性按住。官方放出的日式漫画、韩屋（hanok）酒店宣传页、泰国街景海报，文字排版几乎可以直接拿去印刷。
Bauhaus风、Art Deco风、法国新浪潮拼贴风、杂志跨页风……这一次它不只是”画图”，而是在做完整的视觉设计。
从电影感人像、夜晚闪光灯抓拍，到超现实主义、seinen黑白漫画，AI的”审美颗粒度”肉眼可见地往上拔了一个段位。
这是最让人兴奋的一点：AI画图开始”先思考再下笔”。你让它解释康托尔对角线论证？它能给你画一张干净漂亮的教学信息图；你让它复刻GPT-1论文海报？它能像学术会议poster那样排版严谨。
官方放出的几十张样图里，几个场景特别有代表性：
看完只有一个感觉：设计师的工作流，要重新洗牌了。
坦白说，ChatGPT Images 2.0释放的信号，已经不只是”AI画图变强了”。
它意味着：
官方已经开放入口，直接在ChatGPT里就能体验（Try in ChatGPT）。有Horizontal / Square / Vertical三种画幅，还新增了Image mode和Classic mode两种模式切换。
建议你今晚就去玩一把，不夸张地说——
你今天玩到的，就是明年广告公司、自媒体、电商设计师正在卷的东西。
下面是本期视频中实测用到的所有Prompt，按场景分类整理，方便你直接复制使用。
用红线划出迷宫从入口到出口的最短路线图：
为这首宋词生成一幅与词中意境相匹配的画：
**长相思·伤春**
花又残，雨又寒，
一夜东风吹梦难。
啼莺隔小阑。
柳丝闲，雁书悭，
满地香尘不忍看。
春归人未还。
将这首词生成一张书法作品
还原成彩色照片
将图像改成油画风格
将图像还原为真实的照片风格
手绘涂鸦风格的射箭打卡日记，竖版构图，米黄色格纹笔记本纸张质感，拼贴风格。页面顶部写着"2026年4月22日 星期三"标题，右上角有黑色素描风格的拉弓射箭男人剪影和手写"ARCHERY"字样。中间部分是手绘的靶场射箭靶纸图案，红黄蓝黑白同心圆箭靶，上面用彩色（绿→黄→橙→红渐变）小箭头标注每一轮射箭的落点，标有第1箭、第2箭、第3箭、第4箭、第5箭节点和对应环数。左侧信息栏用蓝色、红色、绿色马克笔手写记录：地点"大王山射箭馆"、距离"30米"、类型"反曲弓训练"、心率"95bpm"、专注度"2-3区"、每轮得分数据。下方有红色折线图的命中环数曲线
生成这个毛坯房装修后照片，装修风格为现代简约
后续修改（北欧风格）：
再生成一张北欧风格的装修后的照片
将图中老者钓鱼的鱼竿换成路亚竿，老者的姿势改成路亚钓
阅读Agent Skills官方文档：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
然后画出Agent Skills的架构图
生成一张iOS端app的登陆页
超写实电影感概念摄影：一只巨型 机械鹤（同时是塔吊） 伫立在建筑工地上——鸟身与长颈由桁架钢架构成，红顶钢喙延伸成塔吊臂，钢索下方正吊起一块混凝土配重；地面有戴安全帽的小工人作尺寸对比，远景是黄昏城市天际线与在建高楼。金属工业细节高度写实，金色 magic hour 落日配冷蓝云层，低角度仰视构图，史诗感十足。视觉双关玩 "crane = 鹤 / 起重机"，4:5 竖版。
仿《TIME》杂志封面：标志性红色粗边框 + 白色衬线大号 "TIME" Logo。中央为电影感 CG 视觉：一个巨大暗色多面体悬浮在荒原湿地上，棱边发出蓝色霓虹光，落日余晖与远山剪影，一个小小的人物背影仰望它。下方白色无衬线大字副标题 "[AI超元域]" 与小字说明 "[突破10万粉丝]"。深蓝紫 + 橙色夕阳的高反差末世科技氛围，4:5 竖版。
短版prompt：
Make me a 360 image of Paris in 1920.
详细版prompt：
一张 1920 年代巴黎街头的 360° 全景照片，
等距圆柱投影格式（Equirectangular Projection），宽高比严格为 2:1，
分辨率 8192×4096，适合用于 VR 全景查看器与 Google Street View。
【场景设定】：1920 年的巴黎，春日午后，阳光明媚，
蓝天中飘着几朵松软的积云。画面以街道中央为观察点，
四周 360 度完整展开城市风貌。
【左前方】：经典的巴黎老式咖啡馆"Café de Flore"，
墨绿色遮阳棚、金色手写体店招、藤编椅与圆形大理石桌，
几位戴礼帽的绅士与穿及膝连衣裙、戴钟形帽的女士围坐喝咖啡，
一位穿白围裙黑马甲的侍者正端着托盘走出店门。
【正前方 / 街道中央】：奥斯曼风格的米白色石砌公寓
英文标题版：
创作一幅以 "visual polyglot（视觉通才）" 为主题的杂志风拼贴页，画面中央标题为 "Create Everything at Once"。采用非网格的、发散式的艺术排版，融合科学图解、元素周期表、太阳系、中世纪手稿、植物与解剖插图、古地图、工程图纸、多语言文字、漫画分格、UI 截图、蝴蝶标本、图表、建筑蓝图、像素艺术、雕塑、绘画等多元视觉元素。整体呈现高端研究宣言或博物馆式宣言的气质：优雅、有野心，色彩鲜艳（避免米色调）。4:5 竖版，除中央标题外不添加其他说明文字（作为画面一部分的文字可以保留）。
中文标题版：
杂志风拼贴艺术海报，中央大标题 "一次创造万物"。发散式自由排版（非网格），融合科学图解、周期表、太阳系、古地图、中世纪手稿、植物与解剖插画、建筑蓝图、漫画分格、UI 截图、蝴蝶标本、像素艺术、雕塑与绘画等多元视觉元素。博物馆宣言式的优雅气质，色彩鲜艳（避免米色调），4:5 竖版，除中央标题外不加额外说明文字。
一张放在木桌上的白色餐巾纸,上面用铅笔速写一位长发女性的正面肖像,旁边有一圈淡淡的咖啡渍,手机随手拍摄。
厚涂油画笔触的日系动漫插画：一位黑色齐刘海长发少女站在东京原宿街头，穿着宽松白色连帽卫衣，卫衣上点缀着随性的彩色油画笔触；背景是 "原宿"、"Laforet" 招牌和熙攘人群的色块化建筑。印象派厚涂油画质感，紫青橙黄的高饱和互补配色，青春文艺氛围，4:5 竖版。
手绘水彩插画风旅行攻略海报：以 [广州] 行政区划地图为主体，每个区用糖果色水彩块填色，虚线分界；地图上手绘当地地标建筑、山水、美食小图标。顶部糖果色描边手写体大标题 "[广州]吃货和游玩地图"，搭配太阳、彩虹、云朵、帆船等可爱贴纸。四周圆角卡片分区列出"玩/吃"要点并配美食插画；右下角戴渔夫帽、拿糖葫芦和相机的卡通女孩吉祥物，左下角木牌写 "快乐出游 快乐干饭"。暖米黄背景 + 高饱和糖果色，小红书治愈风，4:5 竖版。
19 世纪末美好年代学院派油画肖像（Sargent / Boldini 风格）：一位端庄优雅的年轻女士四分之三侧身站在昏暗的古典厅室内，深色盘发、柔光打亮面部。她身穿紧身胸衣 + 泡泡短袖的拖地长 A 字晚礼服，裙身如同一幅展开的风景油画——胸口是远方城堡，从腰际到裙摆绘着山谷、河流、树林与田园，颜料笔触与丝缎褶皱浑然一体。左侧有刺绣白纱帘与窗框，右侧深绿墙面前一张巴洛克雕花木桌与瓷瓶。厚涂油画技法，暖棕、奶白、墨绿的古典配色，戏剧性明暗对比，博物馆藏画气质，4:5 竖版。
桌面近摄照片：一页米白色笔记本纸斜放在深色木桌上，背景浅景深虚化，右上方一束柔和窗光。纸上是一枚用红蓝两色蜡笔涂鸦的卡通火箭（线条粗糙、颜色涂不均、有蜡笔颗粒感），旁边用黑色圆珠笔手写英文工程笔记，关键词加下划线并用手绘小箭头指向火箭部位，内容如 "Images 2.0 with thinking"、"Stage II — Liquid fuel, gimballed engine"、"Payload 3000 lbs"、"thrust"、"ORION"。童趣 + 工程手稿感，米色纸张 + 红蓝蜡笔 + 黑笔字的低饱和暖调，写实摄影质感，4:5 竖版。
字幕最后说还有很多图像没有逐一展示，prompt也一并放在笔记中，供大家继续探索。
一张仿《纽约时报》头版报纸被斜放在深色木桌上的 45° 俯拍写实照片，暖色侧光，纸张有真实褶皱与新闻纸质感。严格遵守 NYT 排版：哥特体报头、日期版次、多栏 Serif 衬线正文；大通栏主标题 "[AI超元域]"，副标题 "[突破10万粉丝]"；中央一张大幅黑白新闻摄影配图，左右两栏为 "Wall Street Reacts" 和 "What This Means" 分栏评论，底部含一条走势折线图。写实摄影风格，4:5 竖版。
复古剪贴拼贴海报（欧式老杂志 / 丝网印刷风），米白毛糙纸张质感。上半部为撕边拼贴：一位条纹衫黑白老照片女郎正看着一份旧报纸，背景由红、黄、蓝三色撕纸色块与黑白街景、法文字片拼接。中部是巨大、错落叠压的粗体无衬线三原色大标题 "GPT Image 2.0"（GPT 黑、Image 红、2.0 蓝），下方黑色粗笔刷横条压着白字 "即将上线"。底部大号黑色衬线中文标题 "OpenAI 正式推出 ChatGPT Images 2.0"，再下方一排社交平台图标与账号。红黄蓝三原色 + 黑白照片的达达主义配色，撕边毛边颗粒感，4:5 竖版。
瑞士国际主义 / 包豪斯风格海报，做旧米白褶皱纸张质感。左侧大号黑色无衬线粗体中文标题 "正式推出 ChatGPT Images 2.0"，下方红色副标题 "图像生成的新纪元"，再下方多段左对齐小字正文排版；右侧为蒙德里安式几何构成：正红圆形、蓝色矩形、黄色方块、黑色半圆与平行黑色细条纹，由垂直水平基准线精确切分。米白 + 红蓝黄 + 黑的克制三原色配色，理性克制的宣言式气质，4:5 竖版。
俯拍平铺摄影海报：浅灰色设计师桌面正上方视角，中央是一台显示彩色画面的宽屏显示器，周围对称整齐地排列着相机镜头、音箱、笔、剪刀、平板、调色盘、色卡、颜料瓶等创意工具。画面中央叠加大号白色无衬线中文标题 "一次创造万物"，下方小字 "即将上线"。写实摄影质感，整洁专业，4:5 竖版。
Color block 极简摄影美学,正面平视视角,一栋粉色平顶小屋孤立在橙红色沙漠中,天空是一整块纯钴蓝,屋顶有一根薄荷绿的烟囱;画面被水平分割成三大色块(天空 / 房子 / 地面),对称、安静、超现实,Palm Springs 中世纪建筑风格,强烈的几何秩序感。
Risograph 印刷风格插画,荧光粉与薄荷绿双色套印,一只坐着的胖橘猫正面肖像,轮廓用粗黑线勾勒,毛发以半调网点表现;背景是简单的几何图形和手写英文字母拼贴;油墨不均、略有错版、纸面有轻微颗粒与折痕,温暖的手工感,独立艺术家 zine 风格。
理想孔版印刷(Risograph)风格的双色海报,荧光粉红与荧光绿两种专色套印,画面中央是一个张大嘴尖叫的朋克青年,头发竖起呈锐利的尖刺状,背后有爆炸式放射图形;左右两侧拼贴着模糊的黑色人物剪影,边缘粗糙像被撕下的报纸;整体带有明显的半调网点、颗粒噪点、油墨错位和纸张折痕,低保真 DIY 朋克 zine 美学,1980年代地下音乐海报感。
维多利亚时代植物图鉴风格插页，泛米色旧纸质感。顶部页眉 "BOTANICAL ATLAS · PLATE XLVII · NATURAL HISTORY"，中央用花体 Serif 大字写学名 "[拉丁学名]"，下方副标题 "[植物俗名] / Family, [科名]"。中心是水彩钢笔线描的盆栽主图，周围环绕多个标号小图（Fig. 2 花正面、Fig. 3 花纵剖、Fig. 4 叶、Fig. 5 根茎、Fig. 6 雄蕊与雌蕊、Fig. 7/8 花苞），用细线引出各部位英文术语标注，说明文字为古典衬线小字。彩蛋：在其中一个花苞内藏着一位透翅花仙子，用同样严谨的博物学口吻把她作为物种描述。水彩 + 钢笔描边，典雅橙红与叶绿配色，四角有小卷草装饰
每一次OpenAI的更新，都像是在提醒我们一句老话——
“工具永远不会淘汰人，但会用工具的人，会。”
这一次，轮到图像生成了。
你准备好了吗？👀
]]>💡 方案一适合想要零配置、零成本快速上手的新手；方案二解决了聊天软件中使用 Hermes 的各种痛点，带来媲美 ChatGPT 的交互体验；方案三则是高阶省钱技巧——用主副模型分工策略大幅降低 Token 消耗。
Ollama 已内置 Hermes Agent，所以不需要单独部署 Hermes，只需要：
Step 1：下载并安装 Ollama
Step 2：查看集成项
打开 Ollama 后可以看到已集成：
Step 3：复制启动命令并在终端执行
在 Ollama 界面复制 Hermes 的启动命令，回到终端运行，进入模型选项界面。
Step 4：选择模型
推荐模型列表中，前几个模型后缀带 Cloud，表示可通过 Ollama 云端使用（不占用本地资源）。
演示中选择的是：MiniMax M2.7
Step 5：登录账号
Step 6：完成 Gateway 刷新与 App 连接
Step 7：验证模型
提问”你是什么模型”，返回：MiniMax M2.7 云端版本 ✅
| 特性 | 说明 |
|---|---|
| ✅ 部署方式 | 一条命令完成全部配置 |
| ✅ 费用 | 免费使用云端模型额度 |
| ✅ 资源占用 | 零本地资源占用 |
| ✅ 上手难度 | 适合新手小白快速上手 |
直接在聊天软件中使用 Hermes Agent 存在以下局限：
Hermes Agent 原生支持 Open WebUI，通过这种方式可以获得以下体验：
按照 Open WebUI 官方仓库的安装命令进行安装，复制官方给出的安装命令，在终端直接执行即可。
用编辑器（Antigravity / 记事本 / VS Code 均可）打开 Hermes Agent 配置文件，添加两个参数：
| 参数 | 作用 |
|---|---|
| 启用 API 服务参数 | 为 Hermes Agent 启用 API 服务 |
| API 密码参数 | 为 API 设置访问密码（可自定义） |
保存配置文件即可。
💡 懒人方案：也可以直接让 Codex / Claude Code 等任何支持操作本地文件的 Agent，用自然语言描述需求（告诉它配置文件位置和要添加的两个参数），自动完成配置。
在终端执行重启命令，让配置生效。
复制 Open WebUI 官方的启动命令，在终端执行启动。
浏览器访问：localhost:8080
配置项填写：
| 字段 | 填写内容 |
|---|---|
| URL | http://localhost:8642/v1（本地 Hermes Agent，端口 8642，后缀 /v1 表示兼容 OpenAI API 的接口） |
| 认证 | 刚才在配置文件中设置的 API 密码 |
点击 保存。
验证测试：提问”你可以调用哪些 Skill” → 返回 118 个 Skill ✅
可以直接在手机上通过 Open WebUI 与电脑上的 Hermes Agent 交互：
http://<电脑IP地址>:8080手机端效果：
如果需要在 公网环境 通过手机访问本机 Hermes Agent：
这是最高阶的玩法——通过配置 MiniMax-CN 主模型 + Gemini 副模型，让核心对话走高质量模型，辅助任务走免费/低价模型，从而大幅节省 Token 消耗。
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$(date +%Y%m%d-%H%M%S)
编辑 ~/.hermes/.env，确保以下三个 key 存在：
MINIMAX_CN_API_KEY=<你的 MiniMax 国内 key>
GOOGLE_API_KEY=<你的 Google AI Studio key>
OPENAI_API_KEY=<你的 OpenAI key>
编辑 ~/.hermes/config.yaml，将 model: 块改为：
model:
api_key: env:MINIMAX_CN_API_KEY
base_url: https://api.minimaxi.com/anthropic
default: MiniMax-M2.7
provider: minimax-cn
要点：
base_url 不要带 /v1（SDK 自动追加）MiniMax-M2.7provider 必须是 minimax-cn（国内端点）auxiliary: 块保持如下结构，全部走 Gemini 2.5 Flash（免费额度大、速度快）：
auxiliary:
approval:
provider: gemini
model: gemini-2.5-flash
timeout: 30
compression:
provider: gemini
model: gemini-2.5-flash
timeout: 120
flush_memories:
provider: gemini
model: gemini-2.5-flash
timeout: 30
mcp:
provider: gemini
model: gemini-2.5-flash
timeout: 30
session_search:
provider: gemini
model: gemini-2.5-flash
timeout: 30
skills_hub:
provider: gemini
model: gemini-2.5-flash
timeout: 30
title_generation:
provider: gemini
model: gemini-2.5-flash
timeout: 30
vision:
provider: gemini
model: gemini-2.5-flash
timeout: 30
download_timeout: 30
web_extract:
provider: gemini
model: gemini-2.5-flash
timeout: 360
compression:
enabled: true
protect_last_n: 20
target_ratio: 0.2
threshold: 0.5
⚠️ 不要在这里放
summary_model/summary_provider/summary_base_url，模型选择统一在auxiliary.compression中配置。
custom_providers:
- api_key: ""
api_mode: chat_completions
base_url: https://generativelanguage.googleapis.com/v1beta
name: google-ai
- api_key: ""
api_mode: anthropic_messages
base_url: https://api.minimaxi.com/anthropic
name: minimax-custom
要点：
name 不能与内置 provider 同名api_mode 必须与 base_url 端点格式一致：
/anthropic → anthropic_messages/v1 → chat_completions所有 mcp_servers.*.env 下的 key 都用 env: 前缀引用，不要写明文：
mcp_servers:
gbrain:
command: gbrain
args: [serve]
env:
OPENAI_API_KEY: env:OPENAI_API_KEY
connect_timeout: 15
timeout: 30
# YAML 语法检查
python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" && echo OK
# 配置诊断
hermes doctor
# 功能测试
hermes chat -q "Say exactly 'pong' and nothing else." -Q
期望输出：
session_id: ...
pong
如果配置出现问题，随时可以回滚：
cp ~/.hermes/config.yaml.bak-<时间戳> ~/.hermes/config.yaml
| 方案 | 适合人群 | 核心优势 | 难度 |
|---|---|---|---|
| Ollama 一键集成 | 新手小白 | 零配置、免费模型、3分钟上手 | ⭐ |
| Open WebUI | 日常重度使用 | ChatGPT 级交互体验、多端访问 | ⭐⭐ |
| 主副模型分工 | 高阶玩家 | 大幅省 Token、灵活配置 | ⭐⭐⭐ |
三个方案可以组合使用：用 Ollama 快速启动 + Open WebUI 美化界面 + 主副模型分工省钱，打造最强 Hermes Agent 使用体验！
]]>📱 首先演示了Hermes Agent连接个人微信的完整流程——扫码登录、配对连接、私聊交互，轻松在微信中调用AI能力。
📚 重点讲解了基于Andrej Karpathy分享的LLM Wiki知识库工作流。通过深入对比传统RAG（无状态碎片检索）与LLM Wiki（有状态知识编辑），揭示了知识复利增长的核心优势。实战演示了：从ArXiv批量摄入论文 → 自动提取结构化知识 → 生成交叉引用的Wiki页面 → 在Obsidian中可视化Graph图谱 → 多Wiki无缝切换与合并。
🏗️ 详细解析了LLM Wiki的三层架构：不可变的原始来源层、Agent驱动的Wiki页面层、人机协同的进化层，真正实现”编译一次，持续更新”的数据飞轮。
🚀本篇笔记所对应的视频：
这个适配器是针对个人微信账号的，使用的是腾讯的 iLink Bot API。它通过 HTTP 长轮询（long-polling）接收消息，因此不需要公网端点或 Webhook。如果你需要企业微信，请使用 WeCom 适配器。
aiohttp 和 cryptographyqrcode 包（可选，用于在终端中显示二维码）安装依赖：
pip install aiohttp cryptography
# 可选：用于终端二维码显示
pip install qrcode
执行以下命令：
hermes gateway setup
在提示中选择 Weixin。向导会自动完成以下操作：从 iLink Bot API 请求二维码 → 在终端显示二维码（或提供一个 URL）→ 等待你用微信手机端扫码 → 提示你在手机上确认登录 → 自动将账号凭证保存到 ~/.hermes/weixin/accounts/。
成功后你会看到类似消息：微信连接成功，account_id=your-account-id
向导会自动保存 account_id、token 和 base_url，无需手动配置。
QR 登录完成后，在 ~/.hermes/.env 中至少设置 account ID：
WEIXIN_ACCOUNT_ID=your-account-id
# 可选：访问控制
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
# 可选：定时任务/通知的主频道
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home
hermes gateway
适配器会恢复已保存的凭证，连接 iLink API，并开始长轮询接收消息。
该适配器支持非常丰富的功能，包括：长轮询传输（无需公网端点）、二维码扫码登录、私聊和群聊消息（可配置访问策略）、媒体支持（图片/视频/文件/语音）、AES-128-ECB 加密的 CDN 媒体传输（自动加解密）、上下文 Token 持久化（重启后保持回复连续性）、Markdown 格式适配（标题/表格/代码块自动转换为微信可读格式）、智能消息分块（4000 字符以内保持单条发送）、输入中提示（”对方正在输入…”）、消息去重（5 分钟滑动窗口）以及自动重试与退避机制。
私聊策略（DM Policy） 默认为 open（任何人可以私聊机器人），可设为 allowlist（仅白名单用户）、disabled（忽略所有私聊）或 pairing（配对模式）。
群聊策略（Group Policy） 默认为 disabled（忽略所有群消息，这是有意为之，因为个人微信可能在很多群中）。可设为 open 或 allowlist。
pip install aiohttp cryptographyhermes gateway setup 完成扫码登录hermes gateway setup 扫描新二维码WEIXIN_DM_POLICY 是否设为 allowlist 且发送者不在白名单中disabled，需要设置 WEIXIN_GROUP_POLICY=open 或 allowlistpip install qrcode，或使用终端上方打印的 URL 链接整个流程非常简洁：安装依赖 → 运行 hermes gateway setup 扫码 → 配置环境变量 → 启动 hermes gateway，就可以让 Hermes Agent 通过你的个人微信收发消息了。
分析日期: 2026-04-11 数据来源: GitHub PR #5100/#5635、Karpathy Gist、Hermes Agent 官方文档、SkillsLLM
LLM Wiki 是 Andrej Karpathy 于 2026 年 4 月 4 日提出的一种持久化知识编译模式，旨在用 LLM 增量构建和维护一个结构化的 Markdown 知识库，取代传统 RAG（检索增强生成）每次查询都从头发现知识的低效方式。
Hermes Agent（Nous Research 开发的自改进 AI Agent）在 PR #5100 中首次引入 LLM Wiki 作为内置 Skill，并在 PR #5635 中正式合并，成为第一个使用全新 Skill Config 接口的技能。
| 维度 | 传统 RAG | LLM Wiki |
|---|---|---|
| 知识发现 | 每次查询重新检索 | 编译一次，持续更新 |
| 检索单元 | 原始文档片段 | 结构化 Wiki 页面 |
| 交叉引用 | 无 | 预先构建 |
| 矛盾检测 | 查询时可能发现 | 摄入时主动标记 |
| 知识积累 | 无累积效应 | 每个源使 Wiki 更丰富 |
chmod -R a-w raw/ 强制文件系统级不可变~/wiki/raw/[[wikilink]] 进行交叉引用~/wiki/wiki/SCHEMA.md）~/wiki/SCHEMA.md流程步骤：
raw/ 目录index.mdlog.md 条目Hermes 增强特性：
index.md 定位流程步骤：
index.md 找到相关页面检查维度（Hermes 实现 8 类检查）：
index.md 与实际内容不一致## [YYYY-MM-DD] action | subjectgrep "^## \[" log.md | tail -5LLM Wiki 是第一个使用 Hermes 新 Skill Config 接口的技能：
# config.yaml
skills:
config:
wiki:
path: ~/wiki # LLM Wiki 路径
实现组件：
agent/skill_utils.py: extract_skill_config_vars(), discover_all_skill_config_vars(), resolve_skill_config_values(), SKILL_CONFIG_PREFIXagent/skill_commands.py: _inject_skill_config() — 将配置注入技能上下文hermes_cli/config.py: get_missing_skill_config_vars(), migrate_config(), show_config()wiki.path 配置 Wiki 存储路径~/wikihermes config migrate 扫描并提示配置hermes config show 显示所有技能配置lint 发现知识空白并指导下一步阅读Karpathy 将此理念追溯到 Vannevar Bush 的 Memex (1945)：
“人类的工作是策展来源、指导分析、提出好问题、思考这一切的意义。LLM 的工作是其他一切。” — Andrej Karpathy
| 局限 | 解决方案 |
|---|---|
| raw/ 不可变仅是口头约定 | chmod -R a-w raw/ 文件系统强制 |
| log.md 格式漂移 | 宽松正则 + 格式修复指导 |
| search_files 工具名可能不匹配 | 运行时工具名验证 |
| Schema 迁移路径 | Lint 检查 frontmatter 与当前 SCHEMA 一致性 |
| 大规模更新风险 | 10+ 页面阈值，先确认再批量更新 |
| 知识规模增长后的检索效率 | qmd 混合搜索引擎 |
| 持久化错误复合传播 | 矛盾标记 [!contradiction] + 定期 Lint |
/raw 文件夹，里面塞满了论文、推文截图、代码片段和笔记，但这些素材之间的关联全在你脑子里，任何 AI 助手想要理解它们就必须把所有文件全读一遍。Graphify 的答案是：一次性构建知识图谱，之后每次查询仅消耗原始 token 的 1/71.5。
该项目是 MIT 许可的开源项目，截至目前已有约 2.2k stars，支持 Claude Code、Codex、OpenCode 和 OpenClaw 四个 AI 编程平台。
🚀本篇笔记所对应的视频：
Graphify 的提取分为两个独立的通道，可并行执行：
通道 A — AST 确定性提取：对代码文件使用 tree-sitter 进行抽象语法树分析，零 LLM 开销。支持 15 种编程语言（Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua）。提取内容包括类定义、函数签名、导入关系、调用图、文档字符串，以及带有 # WHY:、# HACK:、# NOTE: 等标记的设计决策注释。
通道 B — 语义提取：由 LLM 子代理对文档（.md/.txt/.rst）、论文（.pdf）和图片（.png/.jpg/.webp/.gif）进行概念抽取。图片使用视觉模型分析，PDF 进行引用挖掘和概念提取。这一通道会产生 token 消耗。
每条关系边都被标记为三级之一：EXTRACTED（直接从源码找到的显式关系，置信度固定为 1.0）、INFERRED（合理推断的关系，附带 0.6-0.9 的置信度评分）、AMBIGUOUS（不确定的关系，标记留待人工审查）。这套体系是 graphify 的核心设计哲学——对自己「找到了什么」和「猜测了什么」保持诚实。
使用 Leiden 算法（基于 graspologic 库）进行社区发现，完全基于图的边密度拓扑，不需要任何嵌入向量或向量数据库。LLM 提取出的语义相似性边（semantically_similar_to，标记为 INFERRED）直接参与社区检测的计算。
一次运行产出四类核心输出：graph.html（交互式可视化图，支持节点点击、搜索、按社区筛选）、GRAPH_REPORT.md（包含上帝节点、惊人连接、建议问题的审计报告）、graph.json（持久化图数据，可跨会话查询）、以及 cache/ 目录（SHA256 缓存，增量更新仅处理变更文件）。
可选输出还包括：Obsidian 知识库（--obsidian）、SVG 导出（--svg）、GraphML 格式（--graphml，供 Gephi/yEd 使用）、Neo4j Cypher 脚本（--neo4j）、直接推送 Neo4j（--neo4j-push）、MCP 服务器（--mcp）、Wiki 风格的 Markdown 知识库（--wiki）。
超边（Hyperedges）：捕捉 3 个以上节点之间的群组关系，比如实现同一协议的所有类、认证流程中的所有函数。这是普通的成对边无法表达的关系。
语义相似性边：跨文件的概念链接，当两个函数解决同一问题但没有任何调用关系时自动建立连接。
设计决策节点（Rationale Nodes）：从文档和代码注释中提取的「为什么」信息，以 rationale_for 关系连接到对应的代码元素。
Git Hooks（graphify hook install）：安装 post-commit 和 post-checkout 钩子，每次提交和分支切换后自动重建图谱（仅代码文件，无 LLM 开销）。如果重建失败，钩子会以非零退出码结束，Git 会显式地报告错误。
文件监听（--watch）：后台监控文件变更，代码变更即时触发 AST 重建，文档/图片变更则通知用户执行 --update。
反馈回路：每次 /graphify query 的问答结果自动保存到 graphify-out/memory/，下次 --update 时会被提取为图中的节点，让知识图谱越用越智能。
场景 1：快速理解新代码库。你刚加入一个项目，面对数十个源文件。运行 /graphify . 后，GRAPH_REPORT 告诉你哪些是「上帝节点」（所有东西都连接到的核心概念），社区结构揭示了模块的真实边界，惊人连接可能揭示出某个看似无关的工具函数实际是性能瓶颈的根源。
场景 2：个人知识库管理。把论文、推文截图、白板照片、代码实验扔进一个文件夹，graphify 自动将它们连接起来。例如一篇 Transformer 论文中的「注意力机制」概念会与你代码中的 Attention 类自动建立跨模态关联。
场景 3：大型研究项目的文献管理。通过 /graphify add 从 arXiv 拉取论文、从 Twitter/X 抓取推文，自动融入现有图谱。引用图和概念图合二为一，让你发现论文之间的隐藏联系。
场景 4：团队协作中的架构文档自动化。通过 --wiki 生成 Wikipedia 风格的知识库，每个社区一篇文章，自动交叉引用。新成员阅读 index.md 即可导航整个代码库的知识结构。
根据 ARCHITECTURE.md，整个管线是 detect() → extract() → build_graph() → cluster() → analyze() → report() → export()，每个阶段是一个独立模块中的单一函数，通过普通 Python 字典和 NetworkX 图进行通信，无共享状态，无副作用（所有输出仅写入 graphify-out/ 目录）。
核心模块包括：detect.py（文件收集与过滤）、extract.py（AST + 语义提取）、build.py（图构建与节点去重）、cluster.py（Leiden 社区检测）、analyze.py（上帝节点/惊人连接/建议问题分析）、report.py（报告生成）、export.py（多格式导出）、security.py（URL 验证、SSRF 防护、Cypher 注入防护等安全模块）。
这是你问题的核心部分。根据源码和文档的详细分析，在 OpenClaw 中使用 graphify 的完整流程如下：
bash
`pip install graphifyy && graphify install –platform claw
这个命令做了一件事：将 `skill-claw.md` 文件复制到 `~/.claw/skills/graphify/SKILL.md`。这个路径是 OpenClaw 读取技能定义的标准位置。
### 第二步：使用 /graphify 命令构建图谱
在 OpenClaw 中打开你的项目，输入：
/graphify .`
OpenClaw 会读取 ~/.claw/skills/graphify/SKILL.md 中定义的完整管线指令，按步骤执行。
OpenClaw 与其他平台有一个关键区别——语义提取使用顺序模式而非并行模式。在 skill-claw.md 中明确写到：由于 OpenClaw 的多代理支持尚处于早期阶段，提取过程是逐文件顺序执行的。这意味着相比 Claude Code 的并行子代理提取，OpenClaw 上的首次构建会更慢，但结果完全一致。AST 提取（代码文件）不受此影响，仍然是瞬时完成的。
bash
graphify claw install
这个命令会在你的项目根目录写入一个 AGENTS.md 文件（而非 Claude Code 使用的 CLAUDE.md），其中包含一个 ## graphify 段落，指示 OpenClaw：在回答架构或代码库问题前，先读取 graphify-out/GRAPH_REPORT.md 了解上帝节点和社区结构；如果存在 graphify-out/wiki/index.md，优先导航 wiki 而非直接读源文件；修改代码后自动触发图谱重建。
需要注意的是，OpenClaw 不支持 Claude Code 的 PreToolUse hook 机制（该机制能在 Claude 每次执行 Glob/Grep 操作前自动提醒它先查看图谱）。AGENTS.md 是 OpenClaw 上唯一的 always-on 机制。
构建完成后，可使用以下命令在 OpenClaw 中交互式探索：
/graphify query "什么连接了认证模块和数据库？" — BFS 广度遍历/graphify query "..." --dfs — DFS 深度追踪特定路径/graphify path "AuthModule" "Database" — 两个概念间的最短路径/graphify explain "SwinTransformer" — 某个节点的完整解释bash
graphify claw uninstall
这会从 AGENTS.md 中移除 graphify 段落。如果移除后文件为空，会直接删除该文件。
从源码 __main__.py 可以看到，OpenClaw 的平台配置为：技能文件使用 skill-claw.md，安装目标路径为 ~/.claw/skills/graphify/SKILL.md，不使用 CLAUDE.md（claude_md: False）。always-on 集成通过写入项目根目录的 AGENTS.md 实现。Git hooks（graphify hook install）是跨平台的，在 OpenClaw 上同样适用。
你刚加入团队，面前是一个几十个文件的 Python 项目，完全不知道从哪里看起。
/graphify .
graphify 扫描整个目录，代码文件走 tree-sitter AST 提取，文档走语义提取，几分钟后直接在聊天里输出三段关键信息：上帝节点（所有东西都连接到的核心概念，比如某个 BaseHandler 类被 15 个模块依赖）、惊人连接（你绝对想不到的跨模块关联，比如日志模块和认证模块共享同一个配置解析器）、建议问题（图谱最擅长回答的 4-5 个架构问题）。同时生成 graphify-out/graph.html，浏览器打开就是一张可交互的节点图，按社区着色，点击任意节点查看它的所有连接。
你不需要读一行代码就已经知道了这个项目的骨架。
你在 code review 时发现改了 DigestAuth 模块后 Response 模块的测试挂了，但你不理解它们之间有什么关系。
/graphify path "DigestAuth" "Response"
graphify 在已有的知识图谱上跑最短路径算法，返回类似这样的结果：
Shortest path (3 hops):
DigestAuth --calls--> [EXTRACTED]
AuthFlow --shares_data_with--> [INFERRED, 0.82]
RequestBuilder --implements--> [EXTRACTED]
Response
每一跳都标注了关系类型、置信度和源码位置。你立刻知道中间经过了 AuthFlow 和 RequestBuilder，而且 AuthFlow 到 RequestBuilder 之间的关系是推断出来的（不是显式调用，而是共享数据结构），置信度 0.82。这比自己在代码里追调用链快得多。
你想搞清楚项目里最关键的 Gateway 模块到底做了什么、和谁有关系。
/graphify explain "Gateway"
返回该节点的完整连接画像：度数（多少个其他节点连接到它）、所有邻居节点及其关系类型、源码文件位置。然后 Claude 用这些图数据写一段 3-5 句话的结构化解释，每个论断都引用了 source_location。
你想知道项目里的错误处理和日志记录之间是怎么协作的。
/graphify query "错误处理和日志记录之间有什么关系？"
graphify 用 BFS 从匹配的节点出发，向外探索 3 层邻居，返回相关的子图。Claude 基于子图中的节点、边和置信度标签来回答你的问题，而且只使用图谱中实际存在的信息——如果图谱里没有足够的数据，它会明确告诉你而不是编造。
如果你想追踪一条具体的依赖链而不是看广泛的上下文：
/graphify query "错误处理和日志记录之间有什么关系？" --dfs
DFS 模式会沿着一条路径深入追踪到 6 层，适合回答”A 怎么最终影响到 B”这类链式问题。
你读到一篇和项目相关的论文，想把它纳入图谱。
/graphify add <https://arxiv.org/abs/1706.03762>
graphify 自动抓取论文的摘要和元数据，保存为 Markdown 文件到 ./raw 目录，然后自动触发 --update 管线，只提取这一个新文件并合入现有图谱。论文中的概念会和代码中的已有节点自动建立跨模态关联。
同样支持推文：
/graphify add <https://x.com/karpathy/status/>... --author "Karpathy"
也支持任意网页、PDF 链接和图片 URL。
你做了一轮重构，改了几个核心文件。
/graphify . --update
graphify 比较 SHA256 缓存，只对变更的文件重新提取。如果只改了代码文件，它会自动跳过语义提取（零 LLM 开销，只跑 AST）。更新完成后还会展示图谱 diff——新增了哪些节点、新增了多少条边。
你希望图谱永远和代码保持同步，不想记任何命令。
# 在终端执行一次
graphify claude install
graphify hook install
第一条命令做两件事：在项目的 CLAUDE.md 里写入指令让 Claude 每次回答架构问题前自动查图谱，并在 .claude/settings.json 里注册 PreToolUse hook 在每次 Glob/Grep 前自动提醒。第二条命令安装 git post-commit 和 post-checkout 钩子，每次提交和切换分支都自动重建。
装完之后你就可以忘掉 graphify 的存在了。你正常提问，Claude 自动走图谱路径；你正常 commit，图谱自动更新。
你觉得默认提取太保守，想发现更多潜在的关联。
/graphify . --mode deep
deep 模式让语义提取的子代理更激进地推断 INFERRED 边——间接依赖、共享假设、潜在耦合都会被标注出来。不确定的用 AMBIGUOUS 标记而不是省略。适合做架构审计或准备重构前的全面摸底。
你想让团队其他成员也能浏览项目的知识结构，但他们不用 Claude Code。
/graphify . --wiki
生成 graphify-out/wiki/ 目录，包含 index.md 入口页和每个社区、每个上帝节点的独立文章，带有交叉链接、内聚度评分和审计追踪。任何人用 Markdown 阅读器就能导航整个知识库。
你想用专业的图分析工具进一步探索。
/graphify . --graphml # 导出给 Gephi 或 yEd
/graphify . --neo4j # 生成 Cypher 导入脚本
/graphify . --neo4j-push bolt://localhost:7687 # 直接推到 Neo4j
/graphify . --mcp # 启动 MCP 服务器，其他 AI agent 可以实时查询
MCP 服务器模式特别值得注意——它暴露了 query_graph、get_node、get_neighbors、shortest_path 等工具接口，可以加入 Claude Desktop 的 MCP 配置，让其他 agent 也能查询这张图谱。
你在一个长时间的开发会话中，希望图谱实时跟上你的改动。
/graphify . --watch
在后台终端运行。代码文件变更立即触发 AST 重建（无 LLM 开销）；文档或图片变更会写一个 flag 文件并通知你执行 --update。设有 3 秒防抖，不会因为快速连续保存触发多次重建。
你觉得社区划分不够理想，想用已有的图数据重新跑一次聚类。
/graphify . --cluster-only
跳过所有提取步骤，直接加载 graph.json，重新运行 Leiden 社区检测，重新生成报告和可视化。零 token 开销，几秒完成。
🚀本篇笔记所对应的视频：
修复这个问题主要涉及三层兼容性问题：
OpenRouter / HuggingFace Router 不支持 Gemma 4 的 tool/function calling
而 OpenClaw 的 agent 依赖工具调用，因此这些接入方式不可用。
OpenClaw 内置的 google/* provider 不包含 Gemma 模型
因此直接使用内置 Google provider 时，gemma-4-31b-it 会被识别为未知模型。
Gemma 4 的流式响应中包含 “thought”: true 的 thinking / reasoning token
OpenClaw 的响应解析器会尝试将其按结构化 reasoning 输出处理，进而触发 MALFORMED_RESPONSE 错误。
解决方案是：
这样可以让 OpenClaw 跳过对 reasoning/thinking token 的解析，从而避免 Gemma 4 的 thought chunk 导致解析失败。
在 models.providers 下加入：
"google-ai": {
"baseUrl": "https://generativelanguage.googleapis.com/v1beta",
"api": "google-generative-ai",
"authHeader": true,
"models": [
{
"id": "gemma-4-31b-it",
"name": "Gemma 4 31B IT",
"reasoning": false,
"input": ["text", "image"],
"cost": {
"input": 0,
"output": 0
},
"contextWindow": 262144,
"maxTokens": 32768
}
]
}
// agents.defaults.model
"primary": "google-ai/gemma-4-31b-it",
"fallbacks": ["minimax/MiniMax-M2.7", "minimax-portal/MiniMax-M2.1"]
// agents.list[0]（主 agent）
"primary": "google-ai/gemma-4-31b-it"
// agents.defaults.models（模型目录项）
"google-ai/gemma-4-31b-it": {
"alias": "gemma4"
}
"google-ai:default": {
"type": "api_key",
"provider": "google-ai",
"key": "<GOOGLE_AI_STUDIO_API_KEY>"
}
GOOGLE_AI_API_KEY=AIza...
要让 OpenClaw 正常使用 Gemma 4 31B IT，核心是三点：
今天我对这份源码进行了深度分析，专注于一个很少有人关注的问题：Claude Code 的上下文管理和记忆系统，对英文和中文的支持程度是否一样？
结论先行：英文是原生优化的一等公民，中文存在系统性偏差。
整个上下文管理系统的决策基础是一个叫 roughTokenCountEstimation() 的函数，源码位于 src/services/tokenEstimation.ts 第 203-208 行：
export function roughTokenCountEstimation(
content: string,
bytesPerToken: number = 4,
): number {
return Math.round(content.length / bytesPerToken)
}
逻辑很简单：用 JavaScript 的 string.length（UTF-16 code unit 数量）除以 4 来估算 token 数。
这个假设完全是为英文设计的。
在英文中，1 个 token 大约对应 4 个字符，所以 string.length / 4 是一个合理的近似。但在中文里：
| 文本 | string.length | 估算 tokens | 实际 tokens | 偏差 |
|---|---|---|---|---|
| “hello world” | 11 | ~3 | ~2 | 1.5x 高估（安全） |
| “你好世界” | 4 | 1 | 4-6 | 4-6x 低估（危险） |
| 400字中文段落 | 400 | 100 | 400-800 | 4-8x 低估 |
每个中文字在 JavaScript 里只占 1 个 string.length 单位，但在 Claude 的 BPE 分词器中通常需要 1-2 个 token。 除以 4 之后，中文的 token 数被低估了 4 到 8 倍。
更关键的是，代码中完全没有语言感知的调整——唯一存在的调整是针对 JSON 文件类型（bytesPerToken = 2），而不是针对语言。
这个 token 低估不是孤立的问题，它直接影响了上下文自动压缩（auto-compact）的触发时机。
Claude Code 的 auto-compact 触发逻辑定义在 src/services/compact/autoCompact.ts：
effectiveContextWindow - 13,000tokenCountWithEstimation()，而这个函数底层就是 roughTokenCountEstimation()英文对话： 估算值接近真实值，auto-compact 在上下文窗口用到 ~93% 时准时触发，平稳压缩。
中文对话： 估算值只有真实值的 12.5%-25%。系统认为上下文才用了 25%，实际已经 100% 满了。结果是 auto-compact 永远触发不了，直到 API 返回 413 Prompt Too Long 错误，才由反应式压缩（reactive compact）兜底。
这意味着中文用户会经历更多的”上下文突然中断”，而英文用户几乎不会遇到这个问题。
当上下文压缩确实被触发后（无论是主动还是被动），系统会调用一个 LLM 来生成结构化摘要。
摘要提示词定义在 src/services/compact/prompt.ts，包含 9 个英文结构化节：
没有中文变体，没有语言适配指令。
虽然系统提示中有一条 "Always respond in {language}" 指令会传递给压缩子代理，但压缩专用提示本身完全是英文的。这导致：
此外，摘要的最大输出限制是 20,000 tokens。由于中文字符的 token 密度更高（每个字 1-2 tokens vs 英文每个词 1 token），同样 20K tokens 的预算下，中文摘要能承载的信息量更少。
Claude Code 有一个精巧的记忆系统（src/memdir/），能从最多 200 个记忆文件中选出 5 个最相关的，注入到当前对话上下文。
选择器使用 Sonnet 模型，接收用户查询和记忆文件清单（文件名 + 描述），返回最匹配的文件名。
关键点：选择器的系统提示是纯英文的。
"You are selecting memories that will be useful to Claude Code
as it processes a user's query..."
当英文用户查询 “Fix the auth middleware” 匹配英文描述 “Auth middleware gotchas” 时，这是直接的关键词对应。
当中文用户查询 “修复认证中间件的问题” 匹配同一个英文描述时，Sonnet 需要做跨语言语义推理——”认证” ↔ “auth”，”中间件” ↔ “middleware”。虽然现代 LLM 有很好的多语言理解能力，但跨语言匹配的精度和可靠性不可避免地低于同语言匹配。
这是最直观的差距。
src/hooks/useVoice.ts 中定义了 16 种支持的 STT（语音转文字）语言：
en, es, fr, ja, de, pt, it, ko, hi, id, ru, pl, tr, nl, uk, el, cs, da, sv, no
日语和韩语都有，唯独没有中文（zh）。
作为全球使用人数最多的语言之一，中文在语音输入中的缺席是一个明显的功能空白。
公平地说，Claude Code 在终端显示层面对中文的支持是合格的。
src/ink/stringWidth.ts 使用了 east-asian-width 库和 Intl.Segmenter 进行字素分割，CJK 全角字符被正确地视为宽度 2。这意味着中文文本在终端界面中的布局和换行是准确的。
但终端渲染只是”展示层”，它不影响上下文管理的核心决策。
| 维度 | English | 中文 | 差距等级 |
|---|---|---|---|
| Token 估算准确度 | 90% | 15% | 严重 |
| Auto-Compact 触发时机 | 92% | 12% | 严重 |
| 压缩总结质量 | 95% | 55% | 中等 |
| 记忆召回匹配 | 88% | 62% | 轻-中 |
| 语音输入 | 100% | 0% | 完全缺失 |
| 终端渲染 | 95% | 93% | 无差距 |
综合评级：English A / 中文 C-
这些问题不是零散的 bug，而是同一个根因的连锁反应。
roughTokenCountEstimation() 中 string.length / 4 这个假设是为英文字符密度设计的。这个偏差通过调用链向上传播：
roughTokenCountEstimation() ← 根因：CJK 低估 4-8x
↓
tokenCountWithEstimation() ← 上下文大小的权威函数
↓
┌───────────────┬──────────────────┬──────────────────┐
│ autoCompact │ microCompact │ shouldAutoCompact│
│ 触发过晚 │ 工具结果清理不及时 │ 阈值判断失准 │
└───────────────┴──────────────────┴──────────────────┘
修复思路也很明确：
bytesPerToken 系数——检测到 CJK 字符占比 >50% 时，使用 ~1.0-1.5 而非 4countTokens 端点进行精确计数，而非本地估算这两个改动的代码量都不大，但影响面覆盖整个上下文管理链路。
Claude Code 无疑是一款优秀的产品，其架构设计（query loop、5 层错误恢复、4 层上下文压缩）展现了极高的工程水准。但在国际化支持方面，它目前本质上还是一个”英文优先”的工具。
对于中文用户来说，你可能会发现在长对话中更容易遇到上下文中断、压缩后信息丢失、记忆匹配不精确等问题——这些不是你的使用方式有问题，而是底层系统对中文的支持确实存在结构性差距。
希望这篇分析能帮助大家更好地理解自己使用的工具，也希望 Anthropic 团队能在未来版本中改进这些问题。
本文基于 Claude Code 源码快照（2026-03-31）的深度分析，涵盖 src/services/tokenEstimation.ts、src/services/compact/、src/memdir/ 等核心模块。
]]>