[{"content":" Hermes Agent 教程 # 本系列从可用的 Hermes 安装出发，一路读到并能扩展 Agent 核心——面向成为 Agent 开发工程师 的学习路径。\n学习路径 # 入门 — 安装、首次对话、CLI 与配置 架构 — 设计哲学、系统地图、不变量、数据流 代码导读 — 如何在仓库里找代码 扩展 — Footprint Ladder、skills、plugins、tools 实战 Labs — 在用户目录下动手练习 适合谁 # 想尽快跑通一次对话的新用户 想理解 Hermes「为什么长这样」的工程师 需要在 skill / plugin / 核心工具之间正确选型的贡献者 约定 # 纯 Markdown，适配 Hugo（无 Docusaurus MDX） 示例优先写在用户目录（~/.hermes/），不要求改 Hermes 核心 更细的 API：见 hermes-agent 仓库中的官方文档 website/docs/ ","externalUrl":null,"permalink":"/zh-cn/hermes/","section":"Hermes Agent 教程","summary":"","title":"Hermes Agent 教程","type":"hermes"},{"content":" 入门 # 最短路径跑通 Hermes。经验法则：先完成一次干净对话，再加 gateway、cron、skills 或路由。\n章节 # Hermes 是什么 安装与首次对话 CLI 与配置基础 ","externalUrl":null,"permalink":"/zh-cn/hermes/getting-started/","section":"Hermes Agent 教程","summary":"","title":"入门","type":"hermes"},{"content":" Hermes 是什么 # Hermes 是个人 AI Agent，同一套 Agent 核心跑在多种表面上：\nCLI — 交互式终端助手 消息 Gateway — Telegram、Discord、Slack 等约二十种平台 TUI — Ink 终端 UI（hermes --tui） Desktop — Electron 应用，经 JSON-RPC 连接同一后端 它能跨会话学习（memory + skills）、委派子 Agent、跑定时任务，并驱动真实终端与浏览器。新能力应主要通过 plugins 与 skills 扩展，而不是无限膨胀核心。\n心智模型 # CLI / Gateway / TUI / Desktop / Cron / ACP │ ▼ AIAgent（单一核心） │ ┌───────────┼───────────┐ ▼ ▼ ▼ Prompt Providers Tools + cache + backends 核心之上都是入口。平台差异应留在入口，而不是写进 AIAgent。\n你会反复看到的两个观念 # Prompt caching 神圣不可轻易破坏。 长对话每轮复用缓存的 system prompt 前缀。中途改历史、换 toolset、重建 system prompt 会让成本成倍上升。压缩（compression）是少数被允许的例外。 细腰、富边缘。 每个核心模型工具几乎会出现在每次 API 调用里。优先 skill、CLI、plugin、MCP，最后才考虑新核心工具。 两者会在 架构 中展开。\n学完本系列你应能 # 跑通 Hermes 并验证一次干净对话 用一张图讲清架构 按主题找代码（stem_*.py siblings，而不是先啃 facade） 选对扩展档位（skill → plugin → tool） 完成 Labs 且不必改核心源码 下一章 # 安装与首次对话\n延伸阅读 # 仓库根目录 AGENTS.md 官方文档：website/docs/getting-started/ ","externalUrl":null,"permalink":"/zh-cn/hermes/getting-started/01-what-is-hermes/","section":"Hermes Agent 教程","summary":"","title":"Hermes 是什么","type":"hermes"},{"content":" 安装与首次对话 # 目标：从零到已验证的对话。在此之前不要加消息机器人、cron 或自定义工具。\n1. 安装 # Desktop 安装包（macOS / Windows） # 从项目站点下载 Hermes Desktop 安装包并运行，可同时获得 CLI 与桌面端。\n仅 CLI — Linux / macOS / WSL2 / Termux # curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash 之后重载 shell：\nsource ~/.bashrc # 或 ~/.zshrc 仅 CLI — Windows（PowerShell） # iex (irm https://hermes-agent.nousresearch.com/install.ps1) 确认命令可用 # hermes --help 2. 选择 Provider # 目标 先做 然后 最快上手 hermes setup（常含 portal/OAuth） 聊一次 已知道 Provider hermes model 保存配置再聊 本地 / 自建端点 hermes model → 自定义 endpoint 核对模型名与上下文长度 常驻消息机器人 先让 CLI 对话变绿 再 hermes gateway setup 法则： 若普通对话都不通，先修好，再堆功能。\n3. 第一次对话 # 启动 CLI：\nhermes 或一次性查询：\nhermes -q \u0026#34;Reply with exactly: hermes-ok\u0026#34; 你要的是真实模型回复，而不是凭证或路由错误。\n失败时 # 重跑 hermes model / hermes setup，确认 Provider 凭证 确认密钥在 ~/.hermes/.env（或当前 profile 的 home），不要只依赖临时 shell export 查看 ~/.hermes/logs/（agent.log、errors.log）或 hermes logs 使用 hermes -p \u0026lt;name\u0026gt; 时，home 是该 profile 目录，不一定是 ~/.hermes。\n4. 可选：消息（CLI 通了之后） # hermes gateway setup 预期结果 # hermes 能启动且无配置崩溃 至少完成一轮 user → assistant 知道当前 home 下配置与日志在哪 下一章 # CLI 与配置基础\n延伸阅读 # website/docs/getting-started/installation.md website/docs/getting-started/quickstart.md ","externalUrl":null,"permalink":"/zh-cn/hermes/getting-started/02-install-and-first-chat/","section":"Hermes Agent 教程","summary":"","title":"安装与首次对话","type":"hermes"},{"content":" CLI 与配置基础 # 对话通了之后，先分清 Hermes 放状态的三个地方——以及哪个才是密钥。\n配置 vs 密钥 # 文件 用途 ~/.hermes/config.yaml（或 profile home） 行为设置：模型默认、超时、显示、gateway、tools、cron… ~/.hermes/.env 仅密钥：API key、bot token、密码 ~/.hermes/logs/ agent.log、errors.log、gateway.log 不要把超时、功能开关、显示偏好放进 .env。\n常用命令：\nhermes config get model hermes config set display.skin default hermes doctor hermes logs --follow Tools 表面 # hermes tools 可按平台启用/禁用 toolset。配置里也有 tools.\u0026lt;platform\u0026gt;.enabled/disabled。\n会话内斜杠命令 # 命令来自统一注册表（hermes_cli/commands.py）。常见：\n/help /model — 切换模型（明确的用户动作） /compress — 被允许的上下文压缩 /skills — skill 管理（影响 system prompt 的变更默认延迟失效；需要立刻生效再用 --now） Skill 斜杠命令以用户消息注入，而不是改写 system prompt——这样能保住 prompt caching。\n工作目录 # CLI：当前 os.getcwd() 消息 Gateway：config 里的 terminal.cwd Profiles（预览） # hermes -p work Profile 是孤岛：各自的 home、密钥、会话与记忆。默认不做实时配置继承。\n进入架构前自检 # 能成功对话 分清 config.yaml 与 .env 知道失败时去哪看日志 还没有「为了有工具而加核心工具」 下一章 # 架构 → 设计哲学\n延伸阅读 # website/docs/user-guide/configuration.md website/docs/user-guide/cli.md ","externalUrl":null,"permalink":"/zh-cn/hermes/getting-started/03-cli-and-config-basics/","section":"Hermes Agent 教程","summary":"","title":"CLI 与配置基础","type":"hermes"},{"content":" 架构 # 阅读顺序：为什么（哲学）→ 是什么（地图）→ 不能破（不变量）→ 消息怎么走（数据流）。\n章节 # 设计哲学 系统地图 设计不变量 数据流 ","externalUrl":null,"permalink":"/zh-cn/hermes/architecture/","section":"Hermes Agent 教程","summary":"","title":"架构","type":"hermes"},{"content":" 设计哲学 # 本页讲为什么。后面的地图、硬不变量与 Labs 都建立在此之上。\nHermes 优化什么 # Hermes 交付一个 Agent 核心和多种表面（CLI、gateway、TUI、Desktop、cron、ACP）。它应当：\n无论从哪里对话，都像同一个 Agent 跨会话学习（memory + skills），却不在对话中途悄悄改写「过去」 在边缘增长能力（skills、plugins、MCP、平台适配器），而不是把每个想法塞进核心工具 schema 每个改动的两面透镜 # 1. 会不会破坏 per-conversation prompt caching？ # 长对话每轮复用缓存的 system prompt 前缀。改历史、换 toolset、把记忆写进 system prompt、中途重建 system prompt，都会使缓存失效并放大成本。\n压缩（compression）是刻意允许的例外。会改 system-prompt 状态的斜杠命令（skills、tools、memory）应默认延迟失效（下次会话），并提供 opt-in 的 --now。\n2. 会不会撑宽细腰？ # 每个核心模型工具几乎挂在每次 API 调用上。新增核心工具门槛很高。优先顺序：扩展已有代码 → CLI + skill → 服务门控工具 → plugin → MCP → 最后才是新核心工具。\n这就是 Footprint Ladder — 见 扩展。\n边缘扩张，腰部克制 # Hermes 不是小产品。平台、Provider、桌面/TUI 功能可以积极扩展。\n克制针对的是 核心 Agent + 模型工具 schema——唯一「每次 API 都付钱」的地方：\n可以大胆扩展（边缘） 必须克制（腰部） 平台适配器、Provider、桌面 UI 核心工具 schema 新条目 Skills、optional skills、plugins 对话中途改写 system prompt Gateway 功能、仪表盘 没有真实消费者的投机 hooks 架构设计原则 # 摘自官方架构文档，并配上工程师向的「好改 / 坏改」：\n原则 好的改动 坏的改动 Prompt 稳定 用用户消息或工具结果注入指引 每轮重建 system prompt「刷新记忆」 可观察执行 经现有回调展示工具进度 用户看不见的静默副作用 可中断 长工具尊重 cancel/interrupt /stop 无效、工具永远跑 平台无关核心 Discord 怪癖放在 Discord 适配器 在 AIAgent 里特判 Discord 松耦合 用 check_fn / registry 门控可选能力 在核心循环硬依赖小众 SaaS SDK Profile 隔离 按 profile home / secret scope 取状态 多路复用时从进程 os.environ 读次要 profile 密钥 贡献品味（摘要） # 想要： 端到端修真 bug；在边缘扩展；把 god-file 拆成 stem_topic.py；保持核心窄；扩展而非复制；测试断言行为契约；用临时 HERMES_HOME 做真实 E2E。\n不要（即使写得很漂亮）： 投机 hooks；为非密钥配置新增 HERMES_*；终端+文件或 skill 已够用时仍加核心工具；教学类工具上的偷懒分页；毁掉功能的「安全修复」；无 opt-in 的出站遥测；改核心文件的 plugin；把第三方产品插件吞进核心树。\nFacade + siblings 文化 # 大模块是 facade 加主题 siblings（gateway/run.py + run_*.py，agent/turn_*.py）。按主题找代码，不要先当 facade 是全部逻辑。\n衔接下文 # 下一页 增加什么 系统地图 盒子与目录 设计不变量 可执行的硬规则 Footprint Ladder 如何加能力 Labs 练习拒绝错误档位 延伸阅读 # 根目录 AGENTS.md website/docs/developer-guide/architecture.md § Design Principles ","externalUrl":null,"permalink":"/zh-cn/hermes/architecture/01-design-philosophy/","section":"Hermes Agent 教程","summary":"","title":"设计哲学","type":"hermes"},{"content":" 系统地图 # 先建立全局方位，再按子系统深入。\n总览 # ┌─────────────────────────────────────────────────────────────┐ │ 入口 │ │ CLI (cli.py) Gateway (gateway/run.py) ACP Batch/API │ │ TUI / Desktop (tui_gateway) Cron │ └──────────────────────────┬──────────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ AIAgent（run_agent.py facade） │ │ Prompt builder │ Provider 解析 │ 工具分发 │ │ 压缩/缓存 │ API 模式 │ 会话持久化 │ └───────────┬─────────────────────────────┬───────────────────┘ ▼ ▼ 会话存储（SQLite） 工具后端 hermes_state*.py terminal / browser / web / MCP … 目录地图（承重） # 路径 角色 run_agent.py 公开 AIAgent facade agent/conversation_loop.py + agent/turn_*.py 真正的 turn 循环与各阶段 agent/prompt_builder.py System prompt 组装 model_tools.py 发现工具、构建 schema、handle_function_call tools/registry.py 零依赖注册表；工具 import 时自注册 toolsets.py 捆绑 / _HERMES_CORE_TOOLS — 暴露门控 tools/ 工具实现与后端 gateway/ 消息适配器、鉴权、会话、斜杠命令 hermes_cli/ CLI 子命令、配置、plugins、更新器 plugins/ Memory、model providers、context engines… skills/ / optional-skills/ 内置与可选 skills tui_gateway/ TUI + Desktop 的 JSON-RPC 后端 cron/ 调度器与任务存储 工具依赖链 # tools/registry.py ↑ tools/*.py（import 时 register） ↑ model_tools.py（发现 + 分发） ↑ run_agent.py / cli.py / gateway / batch_runner / environments 注册发生在 import 时。有顶层 registry.register() 的工具文件会被自动发现——但只有 toolset 点名后，模型才看得到。\n下一章 # 设计不变量\n延伸阅读 # website/docs/developer-guide/architecture.md website/docs/developer-guide/agent-loop.md website/docs/developer-guide/tools-runtime.md ","externalUrl":null,"permalink":"/zh-cn/hermes/architecture/02-system-map/","section":"Hermes Agent 教程","summary":"","title":"系统地图","type":"hermes"},{"content":" 设计不变量 # 哲学变成契约。打破它们就是 bug——即使 demo 看起来能跑。\n1. System prompt 字节级稳定 # 一次对话生命周期内，system prompt 应保持字节稳定。\n不要为了刷新 skills/memory/tools 中途重建 回合中内容走用户消息或工具结果 Skill 斜杠命令以用户消息注入 子目录 AGENTS.md 提示追加到工具结果（不是 system prompt） 2. 压缩是被批准的缓存破坏 # 上下文压缩（Agent 压缩器 + Gateway 卫生阈值）是为长度而设计的历史变更方式。\n让压缩成为唯一的常规缓存破坏 各表面的手动 /compress 应走共享入口 3. 严格角色交替 # 消息使用 OpenAI 形角色：system | user | assistant | tool。\n不要连续两条同角色消息（tool_calls 之后连续多条 tool 除外） 不要在循环中途插入合成用户消息（例外：/steer 在合法边界） Cron 投递使用独立会话，部分原因也在此 4. Session 表面 ≠ 进程环境 # 依赖「谁在看」（桌面窗格、应用内浏览器等）的能力必须从 session 解析，而不是后端进程的环境变量。\nGUI 工具放进由 session 平台解析器折叠进来的具名 toolset 不要只在进程级 check_fn 里用 HERMES_DESKTOP=1 门控 HERMES_DESKTOP=1 表示「由应用拉起」，不表示「有 GUI 在看」 5. Profile 隔离与密钥作用域 # 多路复用时，os.environ 是启动 profile。次要 profile 需要 scoped 密钥读取，以及为非回合路径显式绑定 runtime scope。\n不要硬编码 ~/.hermes——用 get_hermes_home() / display_hermes_home() 不要自造「scoped miss 后再 os.environ」的泄密读法 6. 注册 ≠ 暴露 # registry.register() 让工具可被发现。出现在 toolsets.py（或平台 toolset 选择）里才对模型可见。\n提案改动自测 # 除非用户选择失效/压缩，system prompt 是否跨轮一致？ 历史是否仍合法交替？ 若仅 GUI，门控是否 session 作用域？ 若加工具，是否先爬过 Footprint Ladder？ 两个 profile 时，次要侧是否仍读到自己的密钥？ 在 缓存安全变更评审 上练习。\n下一章 # 数据流\n延伸阅读 # 根目录 AGENTS.md website/docs/developer-guide/prompt-assembly.md website/docs/developer-guide/context-compression-and-caching.md ","externalUrl":null,"permalink":"/zh-cn/hermes/architecture/03-design-invariants/","section":"Hermes Agent 教程","summary":"","title":"设计不变量","type":"hermes"},{"content":" 数据流 # 同一核心，不同边缘。先摸清三条路径，评审才站得住。\nCLI 回合 # 用户输入（REPL / -q / TUI prompt.submit） │ ▼ HermesCLI / tui_gateway methods │ ▼ AIAgent.run_conversation / chat │ ▼ agent/conversation_loop.py → 组装请求（来自 model_tools 的 tools schemas） → Provider API 调用 → 若有 tool_calls：handle_function_call → 追加 tool 结果 → 否则：最终 assistant 文本 │ ▼ 会话持久化（hermes_state）+ UI 流式输出 Gateway 消息路径 # 平台事件（Telegram/Discord/…） │ ▼ 适配器（gateway/platforms/*） → 规范化 identity / session key → 鉴权（allowlist、gates）经 scoped 读取 │ ▼ Gateway runner（gateway/run*.py） → busy 守卫（/stop、/approve…） → 为本回合绑定 profile runtime scope │ ▼ 同一个 AIAgent 对话循环 │ ▼ 投递适配器 send / stream（平台怪癖留在这里） 注意：适配器排队与 runner 控制命令是两道 busy 守卫；审批类命令必须同时绕过两者。\nCron 路径 # cron ticker（按被服务的 profile，在 profile scope 下） │ ▼ 任务到期 → 推进 next_run / 认领 → 拉起 agent session │ ▼ 带 cron 会话设置的 AIAgent（通常 skip_memory=True） │ ▼ 可选投递 / 镜像到面向用户的会话（保持角色交替） 共同教训 # 调试「CLI 行、Telegram 不行」时，先比边缘：identity、鉴权、toolset、profile scope、投递——而不是先怀疑 AIAgent 里的模型算术。\n下一章 # 开始 代码导读。\n延伸阅读 # website/docs/developer-guide/gateway-internals.md website/docs/developer-guide/cron-internals.md gateway/AGENTS.md、cron/AGENTS.md ","externalUrl":null,"permalink":"/zh-cn/hermes/architecture/04-data-flows/","section":"Hermes Agent 教程","summary":"","title":"数据流","type":"hermes"},{"content":" 代码导读 # 先学会导航习惯，再沿 registry → tools → turn loop → 各入口表面走一遍。\n章节 # 阅读顺序 Agent 核心导读 工具与注册表 Gateway 与 CLI 边缘 ","externalUrl":null,"permalink":"/zh-cn/hermes/code-tour/","section":"Hermes Agent 教程","summary":"","title":"代码导读","type":"hermes"},{"content":" 阅读顺序 # Hermes 把昔日的 god-file 拆成 facade 加主题 siblings。先读 facade 往往最贵。\n习惯 # 说出你关心的主题（overflow、斜杠命令、MCP 发现…） 搜 siblings：agent/turn_*.py、gateway/run_*.py、hermes_cli/cli_*_mixin.py 打开对应 sibling；再扫 facade 看公开入口 例：turn overflow 在 agent/turn_overflow*.py 一带，而不是只埋在 run_agent.py。\nFacade vs 循环 # 打开… 实际得到… run_agent.py AIAgent 公开表面、mixin 组装、构造 agent/conversation_loop.py turn 的 while 循环 agent/turn_*.py 每文件一个阶段 在生产读取处打补丁 # Siblings 常在函数内从 facade late-import，以便测试 monkeypatch facade 属性。只补定义模块可能静默 miss。\n推荐导读序列 # tools/registry.py → toolsets.py → model_tools.py → agent/conversation_loop.py（+ 扫一眼 turn_*.py 文件名） → run_agent.py（仅 facade） → agent/prompt_builder.py → gateway/run.py + 一个感兴趣的 run_*.py → hermes_cli/commands.py 下一章 # Agent 核心导读\n延伸阅读 # 根目录 AGENTS.md § Facade + siblings website/docs/developer-guide/architecture.md ","externalUrl":null,"permalink":"/zh-cn/hermes/code-tour/01-reading-order/","section":"Hermes Agent 教程","summary":"","title":"阅读顺序","type":"hermes"},{"content":" Agent 核心导读 # 在仓库里打开这些文件。扫读即可，不必背参数列表。\n1. run_agent.py — facade # AIAgent 由 mixin 组装，构造走 agent/agent_init.py。公开接口包括：\nchat(message) -\u0026gt; str run_conversation(...) — 返回 final_response + messages 入门先关心 model、provider、enabled_toolsets、platform、session_id。\n2. agent/conversation_loop.py — 循环 # 概念形状（简化）：\nwhile under_iteration_budget: if interrupted: break response = client.chat.completions.create( model=model, messages=messages, tools=tool_schemas ) if response.tool_calls: for tc in response.tool_calls: messages.append(tool_result_message( handle_function_call(tc.name, tc.args, task_id) )) else: return response.content 真实代码还有预检、重试、overflow、压缩、用量与收尾——各在 agent/turn_*.py。\n3. 按名字扫 agent/turn_*.py # rg -n \u0026#34;^def \u0026#34; agent/turn_*.py 4. Prompt 组装 # agent/prompt_builder.py 相关：prompt caching、compression facade 稳定/上下文层可缓存；临时覆盖不要随便改写缓存前缀。见 设计不变量。\n5. 内联 / Agent 级工具 # 部分工具（todo、memory…）经 agent/inline_tool_executors.py 的 INLINE_TOOL_EXECUTORS 在 handle_function_call() 前拦截。新增用表驱动，不要 if name == ... 长链。\n练习（约 10 分钟） # 找到 AIAgent.run_conversation 并确认它委托给 conversation loop 列出五个 turn_*.py 文件名，从名字猜阶段 找到 tool schemas 传入 API 调用的位置 下一章 # 工具与注册表\n延伸阅读 # website/docs/developer-guide/agent-loop.md agent/AGENTS.md ","externalUrl":null,"permalink":"/zh-cn/hermes/code-tour/02-agent-core-tour/","section":"Hermes Agent 教程","summary":"","title":"Agent 核心导读","type":"hermes"},{"content":" 工具与注册表 # 三份文件讲清工具故事。记住这条链。\n链条 # tools/registry.py → tools/*.py register() → model_tools.py 发现 ↓ toolsets.py 决定模型看见什么 ↓ handle_function_call() 分发 handler tools/registry.py # 零项目依赖 registry.register(name=..., toolset=..., schema=..., handler=..., check_fn=...) check_fn 回答当前 profile 下的可达/选择加入；结果按 hermes home 做 TTL 缓存 Handler 返回 JSON 字符串 toolsets.py # 单一 TOOLSETS 与 _HERMES_CORE_TOOLS 已注册但未进入所选 toolset ⇒ 模型不可见 model_tools.py # 触发 discover_builtin_tools() 构建 API 用的 tool schemas handle_function_call() 是 turn 循环的分发入口 加能力时的提醒 # 需求 优先 Agent 应遵循的流程 Skill 小众 / 用户私有工具 Plugin ctx.register_tool 仅当某服务已配置 带 check_fn 的服务门控工具 近乎人人需要的原语 核心工具（最后手段） Schema 卫生 # 不要在 schema 描述里硬编码其他 toolset 的工具名 展示路径用 display_hermes_home()；状态文件用调用时的 get_hermes_home() 教学类加载器不要 offset/limit 分页 练习 # 打开任意 tools/*_tool.py，找到 registry.register(...) 在 toolsets.py 中 grep 该工具名 在 model_tools.py 找到 handle_function_call 下一章 # Gateway 与 CLI 边缘\n延伸阅读 # website/docs/developer-guide/tools-runtime.md tools/AGENTS.md ","externalUrl":null,"permalink":"/zh-cn/hermes/code-tour/03-tools-and-registry/","section":"Hermes Agent 教程","summary":"","title":"工具与注册表","type":"hermes"},{"content":" Gateway 与 CLI 边缘 # 核心保持平台无关。意外发生在边缘。\nGateway facade # gateway/run.py — facade gateway/run_*.py — 各阶段 gateway/platforms/\u0026lt;name\u0026gt;.py — 每平台一个适配器 斜杠：mixin + _command_handler_table（不要长 if canonical ==） 每个事件只规范化一次 identity（gateway/session_identity.py）。\nBusy 守卫（两道都重要） # Agent 运行时：\n适配器可能把入站文本排入活动会话队列 Runner 在当普通聊天处理前拦截控制命令（/stop、/approve…） 必须在阻塞中可用的新命令需要同时绕过两者。\nCLI 边缘 # cli.py — HermesCLI facade + mixins 斜杠：_SLASH_DISPATCH / _handle_\u0026lt;name\u0026gt;_command 约定 单一命令注册表：hermes_cli/commands.py 配置加载器因表面而异——CLI 能见、Gateway 不见，多半用错了 loader 边缘上的配置与密钥 # 行为 → config.yaml 密钥 → .env / secret scope 多路复用下适配器必须用共享 scoped 读取器，禁止 miss 后回落 os.getenv 泄出启动 profile TUI / Desktop # tui_gateway 说 JSON-RPC。Agent 行为仍在 Python——不要在 React 里重写一套。\n练习 # 找到 COMMAND_REGISTRY 或 _SLASH_DISPATCH，选一个命令定位 CLI 与 Gateway handler 在 gateway/platforms/base.py 找到活动会话排队处 扫一眼你在入门里用过的配置键在 defaults 中的位置 下一章 # 扩展 → Footprint Ladder\n延伸阅读 # gateway/AGENTS.md、hermes_cli/AGENTS.md、tui_gateway/AGENTS.md ","externalUrl":null,"permalink":"/zh-cn/hermes/code-tour/04-gateway-and-cli-edges/","section":"Hermes Agent 教程","summary":"","title":"Gateway 与 CLI 边缘","type":"hermes"},{"content":" 扩展 # 能力应落在仍能解决问题的最小 footprint 上。\n章节 # Footprint Ladder Skills、plugins 与 tools 练习清单 ","externalUrl":null,"permalink":"/zh-cn/hermes/extend/","section":"Hermes Agent 教程","summary":"","title":"扩展","type":"hermes"},{"content":" Footprint Ladder # 新能力应从仍够用的最小 footprint 往上选。\n档位 # 扩展已有代码 — 零新表面 CLI 命令 + skill — 用 hermes \u0026lt;subcommand\u0026gt; + skill 教 Agent；许多工作流的默认档 服务门控工具（check_fn） — 仅当前置已配置才出现（进程/profile 可达性——不是「谁在看」） Plugin — 第三方 / 小众 / 用户私有；~/.hermes/plugins/ 或 pip MCP server（目录） — 像工具但非核心必需 新核心工具 — 最后手段：基础、广泛有用、且终端+文件/skill/MCP 够不到 为何有这个顺序 # 核心工具 schema 几乎出现在每次 API 调用。Skills 与 plugins 保持细腰，同时在边缘交付能力——对齐 设计哲学。\nSession vs 进程门控 # 问题 正确机制 Home Assistant 配好了吗？ check_fn / toolset 启用 有 GUI session 在看吗？ 来自 session 平台的具名 toolset — 不要只靠 HERMES_DESKTOP 只为某一用户的小众 API？ Plugin 快速例子 # 想法 大概档位 记录 Agent 应遵循的部署清单 Skill 包装带鉴权的内部 HTTP API Plugin 工具 把 WhatsApp 变成聊天表面 平台适配器（边缘），不是核心工具 完整练习见 Footprint 决策演练。\n下一章 # Skills、plugins 与 tools\n延伸阅读 # 根目录 AGENTS.md § Footprint Ladder plugins/AGENTS.md ","externalUrl":null,"permalink":"/zh-cn/hermes/extend/01-footprint-ladder/","section":"Hermes Agent 教程","summary":"","title":"Footprint Ladder","type":"hermes"},{"content":" Skills、plugins 与 tools # 三种常见扩展方式。请有意识地选一种。\nSkills # Markdown 流程（SKILL.md）+ 可选 scripts/、references/ 教 Agent 如何用好已有工具 斜杠 skill 以用户消息注入（对缓存友好） 用户 skill 在 ~/.hermes/skills/；内置在 skills/；较重的在 optional-skills/ Plugins # 位于 ~/.hermes/plugins/、项目插件或 pip entry points register(ctx) 可挂 hooks、tools、CLI 子命令 绝不能改核心文件（run_agent.py、cli.py、gateway/run.py…） 缺能力时加宽通用 plugin 表面，不要给单个 plugin 在核心里开后门 第三方产品后端应 out-of-tree（目录 / 独立仓库），不要吞进核心树的 plugins/ Tools（模型可调用） # 结构化 JSON 入 / JSON 字符串出 核心工具：tools/*.py + toolsets.py（高门槛） Plugin 工具：ctx.register_tool(...)（小众优先） 服务门控：check_fn + 可选 requires_env 对照 # Skill Plugin 工具 核心工具 每次 API 都带 schema 否 仅插件加载/启用时 若在所选 toolset 中则是 最适合 流程、清单 小众 API、hooks 通用原语 碰核心树 否 否 是 缓存提示 # 安装/启用会改 system-prompt 状态的 skills/tools 应默认延迟失效；只有你愿意付缓存代价时才用 --now。\n下一章 # 练习清单 · 编写 Skill Lab · 编写 Plugin 工具 Lab\n延伸阅读 # website/docs/developer-guide/creating-skills.md website/docs/developer-guide/plugins/index.md skills/AGENTS.md、plugins/AGENTS.md ","externalUrl":null,"permalink":"/zh-cn/hermes/extend/02-skills-plugins-tools/","section":"Hermes Agent 教程","summary":"","title":"Skills、plugins 与 tools","type":"hermes"},{"content":" 练习清单 # 开 PR 或开始 lab 功能前使用。\n1. 用一句话陈述用户问题 # 说不清，就是在发明基础设施。\n2. 选定 Footprint Ladder 档位 # 写下档位名，以及为何更低档不够。「我想要一个工具」不是理由。\n3. 列出会碰到的文件 # 档位 可能触点 Skill ~/.hermes/skills/\u0026lt;name\u0026gt;/SKILL.md（+ scripts） Plugin 仅 ~/.hermes/plugins/\u0026lt;name\u0026gt;/ 核心工具 tools/*.py + toolsets.py（+ 测试）— 必须强力论证 Gateway 适配器 gateway/platforms/ 或平台 plugin 若清单同时包含 run_agent.py + cli.py + gateway/run.py 却只是小众功能——停下来重新选档。\n4. 缓存 / 交替 / session 风险 # System prompt 跨轮稳定（或用户选择了 --now / 压缩） 没有非法的双 user/assistant 行 回合中指引是用户消息或工具结果 仅 GUI 行为是 session 作用域，不是只靠 env 次要 profile 不会读到启动 profile 的密钥 5. 你会写的测试 # 偏好行为契约，而不是模型列表 / 配置版本快照 涉及解析、配置、安全或 I/O：用真实 import + 临时 HERMES_HOME 做 E2E 用 scripts/run_tests.sh，不要裸 pytest 且带着密钥 6. 文档 / AGENTS.md # 上游贡献：同 PR 更新区域 AGENTS.md 与用户/开发者文档 对本 Hugo 系列：把笔记写在 lab 里，而不是改核心 去练习 # 追踪一轮对话 编写一个 Skill 编写一个 Plugin 工具 Footprint 决策演练 缓存安全变更评审 ","externalUrl":null,"permalink":"/zh-cn/hermes/extend/03-practice-checklist/","section":"Hermes Agent 教程","summary":"","title":"练习清单","type":"hermes"},{"content":" 实战 Labs # 可执行练习。工作在用户目录（~/.hermes/skills/、~/.hermes/plugins/）或只读读仓库——这些 lab 不要求修改 Hermes 核心。\n每篇结构：目标 → 前置 → 步骤 → 预期结果 → 验证 → 常见坑 → 进阶。\nLabs # 追踪一轮对话 编写一个 Skill 编写一个 Plugin 工具 Footprint 决策演练 缓存安全变更评审 ","externalUrl":null,"permalink":"/zh-cn/hermes/labs/","section":"Hermes Agent 教程","summary":"","title":"实战 Labs","type":"hermes"},{"content":" Lab：追踪一轮对话 # 目标 # 跑一轮会触发工具调用的对话，并把运行时路径映射到仓库里的具体符号。\n前置 # 可用的 hermes 对话（安装与首次对话） 建议：本地 hermes-agent 仓库只读阅读 终端/文件类 toolset 已启用 步骤 # 启动 Hermes，提一个需要工具的问题，例如： 「用你的工具显示当前工作目录。」 或「列出当前目录下的文件。」 观察 UI：最终回答前应能看到工具调用（名称 + 参数）。 在仓库中（只读）按顺序打开： agent/conversation_loop.py — 找到带 tools= 的 Provider 调用循环 model_tools.py — 找到 handle_function_call tools/ 下对应工具模块 — 找到 registry.register 与 handler 在纸上写出一轮工具回合后的角色序列： user → assistant（含 tool_calls）→ tool → assistant（最终） 预期结果 # 会话中至少出现一次工具调用 一份短笔记：循环文件 → 分发函数 → handler 模块 角色序列符合严格交替规则 验证 # UI 里看到的工具名出现在 toolsets.py 或已启用的 toolset 中 能指到 handle_function_call 作为模型 → handler 的桥梁 没有修改任何核心文件 常见坑 # 问纯知识题导致从不调工具 — 把提示导向文件系统/shell 只读 run_agent.py，漏掉循环在 conversation_loop.py 把「UI 出现了工具」当成「一定在 _HERMES_CORE_TOOLS」— 要查当前平台 toolset 进阶 # CLI 通了后再用 gateway 消息复做一遍（hermes gateway setup），对照 数据流 Telegram：website/docs/user-guide/messaging/telegram.md 下一 Lab # 编写一个 Skill\n","externalUrl":null,"permalink":"/zh-cn/hermes/labs/01-trace-one-turn/","section":"Hermes Agent 教程","summary":"","title":"Lab：追踪一轮对话","type":"hermes"},{"content":" Lab：编写一个 Skill # 目标 # 在用户目录创建最小 skill，不改 Hermes 核心。\n前置 # Hermes 对话可用 能编辑 Hermes home 下文件（~/.hermes/ 或 profile home） 步骤 # 创建 skill 目录： mkdir -p ~/.hermes/skills/hello-agent-eng 写入 ~/.hermes/skills/hello-agent-eng/SKILL.md： --- name: hello-agent-eng description: Prints a short Agent eng checklist via terminal. version: 0.1.0 author: Your Name license: MIT metadata: hermes: tags: [tutorial, lab] category: productivity --- # Hello Agent Eng Skill 练习 Hermes 扩展 Labs 时使用本 skill。 ## When to Use - 想用一个极小 skill 验证加载是否正常 ## How to Run 1. 用五条要点概括 Footprint Ladder。 2. 若需要一行 shell，使用 `terminal` 工具 — 不要把其他 CLI 当主界面。 ## Quick Reference | 步骤 | 动作 | | ---- | ---- | | 1 | 重述用户目标 | | 2 | 选择 Footprint Ladder 档位 | | 3 | 列出缓存风险 | 按安装方式加载/刷新 skills（/skills、hermes skills 或重启会话）。若提示影响 system prompt，优先延迟生效；只有你愿意立刻付缓存代价时才用 --now。 调用 skill（斜杠命令，或说：「按 hello-agent-eng skill 执行」）。 预期结果 # 目录与合法 frontmatter 存在 Agent 遵循清单（或明确加载了 skill 内容） 理解 deferred 与 --now 验证 # description 保持一句短句（冲上游质量时 ≤ 60 字符） 正文用反引号引用原生工具（如 terminal），而不是把 grep/cat 当主界面 hermes-agent git 树无改动 常见坑 # 把 skill 写进仓库的 skills/（那是内置贡献区，不是本 lab） description 写成小说，污染列表 习惯性 --now，然后奇怪对话为何变贵 进阶 # 增加 scripts/hello.py，经 terminal 用 skill 相对路径调用 阅读 skills/AGENTS.md / website/docs/developer-guide/creating-skills.md 下一 Lab # 编写一个 Plugin 工具\n","externalUrl":null,"permalink":"/zh-cn/hermes/labs/02-write-a-skill/","section":"Hermes Agent 教程","summary":"","title":"Lab：编写一个 Skill","type":"hermes"},{"content":" Lab：编写一个 Plugin 工具 # 目标 # 在 ~/.hermes/plugins/ 注册一个 plugin 工具（或 hook），不碰核心。\n前置 # Hermes 对话可用 已读 Footprint Ladder 注意：plugin manifest 字段可能随版本演进——若发现失败，以你安装版本的 website/docs/developer-guide/plugins/index.md 与 hermes plugins / doctor 为准 步骤 # 创建目录： mkdir -p ~/.hermes/plugins/lab-echo 最小清单 ~/.hermes/plugins/lab-echo/plugin.yaml（示意）： name: lab-echo version: 0.1.0 description: Tutorial echo tool for Agent eng labs ~/.hermes/plugins/lab-echo/__init__.py（示意 API——按你的 Hermes 版本调整 ctx）： import json def register(ctx): def echo_handler(args, **kwargs): text = (args or {}).get(\u0026#34;text\u0026#34;, \u0026#34;\u0026#34;) return json.dumps({\u0026#34;success\u0026#34;: True, \u0026#34;echo\u0026#34;: text}) ctx.register_tool( name=\u0026#34;lab_echo\u0026#34;, description=\u0026#34;Echo text back as JSON (tutorial plugin).\u0026#34;, parameters={ \u0026#34;type\u0026#34;: \u0026#34;object\u0026#34;, \u0026#34;properties\u0026#34;: { \u0026#34;text\u0026#34;: {\u0026#34;type\u0026#34;: \u0026#34;string\u0026#34;, \u0026#34;description\u0026#34;: \u0026#34;Text to echo\u0026#34;} }, \u0026#34;required\u0026#34;: [\u0026#34;text\u0026#34;], }, handler=echo_handler, ) 重启 Hermes / 重新加载 plugins（新进程最稳妥）。 对话：「用 lab_echo 回显文本 ping-lab」。 可选：注册 pre_tool_call 记录工具名——仍只写在 plugin 包内。\n预期结果 # 有 manifest + register(ctx) 模型能调用 lab_echo（或得到可在用户空间修复的明确启用错误） hermes-agent 受控源码零修改 验证 # hermes plugins / doctor 列出插件或给出可操作错误 工具调用返回含你文本的 JSON 没有把工具加进 tools/ 或 toolsets.py 常见坑 # 因为「注册看起来很像」就去改核心 tools/ — 跳过了梯子 放下插件后忘记重启进程 API 漂移 — 对照你的版本文档修，lab 仍留在用户目录 进阶 # 增加 pre_tool_call，给某一工具名前缀化 args 阅读原生兼容规则：plugins/AGENTS.md 下一 Lab # Footprint 决策演练\n","externalUrl":null,"permalink":"/zh-cn/hermes/labs/03-write-a-plugin-tool/","section":"Hermes Agent 教程","summary":"","title":"Lab：编写一个 Plugin 工具","type":"hermes"},{"content":" Lab：Footprint 决策演练 # 目标 # 针对三个功能设想，选择梯子档位，用 ≤5 条要点论证，并列出将触及的文件——先不实现。\n前置 # 已读 Footprint Ladder 与 Skills、plugins 与 tools 步骤 # 对每个场景写下：\n所选档位（1–6） 为何更低档不够（或为何此档已够） 会触及的路径（用户目录 vs 核心） 一个要盯住的缓存/session 风险 场景 A — 每日 GitHub 摘要 # 「每天早上总结我的 open PR，并发到 Telegram。」\n场景 B — 自定义天气 API # 「公司有带私有 token 的内部天气 HTTP API；Agent 应用结构化参数调用它。」\n场景 C — 响应 Discord 表情反应 # 「有人对消息点 👀 时，机器人应在线程里确认。」\n预期结果 # 一份三决策短文。写完后再对照参考答案（评分看推理质量，不要求标签完全一致）：\n场景 建议档位 原因 A CLI/cron + skill（及 gateway 投递） 调度 + 流程；复用 cron/消息 — 不是新核心工具 B Plugin 工具（或 MCP） 小众鉴权 API；token 放密钥；避开核心 schema C Gateway / Discord 适配器边缘功能 反应处理是平台表面，不是 AIAgent 核心工具 验证 # 没有在未穷尽低档时直接「加进 _HERMES_CORE_TOOLS」 场景 B 不把 API token 放进 config.yaml 场景 C 不以单独的 HERMES_DESKTOP check_fn 作为方案 常见坑 # 「Agent 应该做 X」自动等于「需要核心工具」 只有 skill、没有持久调度器却想做每日任务 在 run_agent.py 里解决 Discord UX 进阶 # 用 script-only cron（no_agent）对比完整 agent cron 重做场景 A 见 website/docs/user-guide/features/cron.md 下一 Lab # 缓存安全变更评审\n","externalUrl":null,"permalink":"/zh-cn/hermes/labs/04-footprint-decision-drill/","section":"Hermes Agent 教程","summary":"","title":"Lab：Footprint 决策演练","type":"hermes"},{"content":" Lab：缓存安全变更评审 # 目标 # 评审六个简短「拟议 PR」。对每个标 PASS 或 FAIL，并引用你用的规则。\n前置 # 设计哲学 设计不变量 步骤 # 复制下表并填写 Verdict + Rule。\n# 提案 Verdict（PASS/FAIL） Rule 1 每轮重建 system prompt，以注入最新 memory prefetch 2 Skill 斜杠命令把说明追加为用户消息 3 循环中途在 tool 结果之间插入额外 user 消息「推一把」 4 证明 terminal+skill 不够后，把广泛有用的原语加入 _HERMES_CORE_TOOLS 5 用 check_fn 检查 os.getenv(\u0026quot;HERMES_DESKTOP\u0026quot;) == \u0026quot;1\u0026quot; 来门控仅桌面窗格工具 6 窗口满时，上下文压缩总结中间回合 预期结果 # 每条 verdict 能用一句话解释。参考答案：\n# Verdict Rule 1 FAIL Prompt caching / system prompt 字节稳定 — 记忆不该每轮重建前缀 2 PASS Skills 以用户消息注入；保住缓存前缀 3 FAIL 严格角色交替 — 禁止循环中途合成 user（/steer 有特定合法形状） 4 PASS 核心工具是最后档，不是禁区；低档真失败且足够基础时允许 5 FAIL Session 表面 ≠ 进程 env — 用 session/toolset 门控，不要只靠桌面 env check_fn 6 PASS 压缩是被批准的缓存破坏 验证 # FAIL 集合至少包含 1、3、5 2 与 6 标为 PASS 对提案 4 能复述「先低档」的限定语 常见坑 # 永远把 4 标 FAIL — 核心工具是最后，不是禁止 因「桌面会设 env」把 5 标 PASS — 远程/云后端会打破该假设 忘记 /steer 是有精确落点的文档化例外 进阶 # 再自撰两个提案（一 PASS 一 FAIL）与同伴交换 扫读 website/docs/developer-guide/context-compression-and-caching.md 完成 # 回到 系列首页，或拿一个你真正关心的想法重跑 练习清单。\n","externalUrl":null,"permalink":"/zh-cn/hermes/labs/05-cache-safe-change-review/","section":"Hermes Agent 教程","summary":"","title":"Lab：缓存安全变更评审","type":"hermes"},{"content":"This is my first blog!\n","date":"3 August 2026","externalUrl":null,"permalink":"/posts/hello/","section":"Posts","summary":"","title":"Hello","type":"posts"},{"content":"","date":"3 August 2026","externalUrl":null,"permalink":"/posts/","section":"Posts","summary":"","title":"Posts","type":"posts"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/agent/","section":"Tags","summary":"","title":"Agent","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/architecture/","section":"Tags","summary":"","title":"Architecture","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/authors/","section":"Authors","summary":"","title":"Authors","type":"authors"},{"content":"","externalUrl":null,"permalink":"/zh-cn/categories/","section":"Categories","summary":"","title":"Categories","type":"categories"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/code-tour/","section":"Tags","summary":"","title":"Code-Tour","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/extend/","section":"Tags","summary":"","title":"Extend","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/getting-started/","section":"Tags","summary":"","title":"Getting-Started","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/hermes/","section":"Tags","summary":"","title":"Hermes","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/labs/","section":"Tags","summary":"","title":"Labs","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/series/","section":"Series","summary":"","title":"Series","type":"series"},{"content":"","externalUrl":null,"permalink":"/zh-cn/tags/","section":"Tags","summary":"","title":"Tags","type":"tags"},{"content":"","externalUrl":null,"permalink":"/zh-cn/","section":"首页","summary":"","title":"首页","type":"page"}]