技能 2026-09-24 02:37 UTC
hermes-optimization-guidev1.4
版本【v1.4】由提交人 OnlyTerp 提交,主要更新类型为:功能特性新增与扩展。提交说明:Restructure guide into 16 sequential chapters; remove legacy docs (#35)。为项目引入了新的能力与模块支持。
Commit提交信息原文
Restructure guide into 16 sequential chapters; remove legacy docs (#35) * Guide v2 (WIP): rebuild against Hermes v0.21.4 Start the from-scratch rewrite of the guide, pinned to Hermes Agent v0.21.4 (tag v2026.9.21). This checkpoint adds: - guide/: chapters 01 (How Hermes Works), 02 (Install), 05 (Cost & Speed), 06 (Personality & Context Files), 15 (Troubleshooting), 16 (Recipes) and the cheat sheet. Token figures are measured on a real v0.21.4 install; troubleshooting fixes cite official docs, merged PRs, or release notes. - scripts/drift_guard.py: installs the pinned release and checks every hermes subcommand and flag, slash command, config key, env var, and official-docs link and anchor; also runs upstream's skill linter. - skills/: four new operations skills (cost audit, health check, security review, encrypted off-machine backup) with zero upstream lint findings; the backup script is shellchecked and tested. - templates/config/: lean.yaml and messaging-bot.yaml, validated against the v0.21.4 schema and loaded into a real install. - New README, CHANGELOG (with a v1 part -> v2 chapter map), CONTRIBUTING, issue/PR templates, CI (links, anchors, YAML, shellcheck) and a drift-guard workflow with an upstream-release watcher. Remaining chapters, templates, and removal of the v1 files follow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Troubleshooting: re-source two fixes to official docs, narrow Weixin row #53008 and #21915 were closed as not planned, so the compression-loop and restart-loop rows now cite the official docs sections that describe the behavior. #96134 is Weixin-specific; #95189 notes the version it was reported on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Stop routing auxiliary.vision in templates; teach drift guard docs 'config set' keys An explicit auxiliary.vision backend makes Hermes describe every image in text, even when the main model can see (agent/image_routing.py, _explicit_aux_vision_override). The lean and messaging-bot templates set one, which silently downgraded native vision. Removed it there, in chapter 05's examples, the README, cheat sheet, troubleshooting row, and the cost-audit skill, and added a warning explaining when to set it. drift_guard extract now also collects keys the official docs set with 'hermes config set <key>' (e.g. model.lmstudio_load_mode). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapter 05: summarizer window rule; chapter 15: what debug share really uploads The compression trigger is clamped to the auxiliary summarizer's window (context_compressor._apply_threshold_tokens_cap), so a small summarizer compacts early and often. 'hermes debug share' redacts only secrets; names, platform IDs, message text and paths go to a public paste (hermes_cli/debug.py privacy notice). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapter 01: a profile is not a sandbox; drift guard knows guide-defined commands Profiles separate state, not filesystem access (docs user-guide/profiles 'Profiles vs workspaces vs sandboxing'). The drift guard now accepts slash names the guide itself creates: bundles made with 'hermes bundles create', example SKILL.md frontmatter names, and quick_commands keys. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Remove v1 CI workflows and scripts bootstrap-smoke, pin-watch, release-hash-check and release-publisher existed for scripts/vps-bootstrap.sh and its installer hash pin, which no longer matches upstream. validate_skills.py enforced an invented skill schema; skills are now checked with upstream's own linter via drift_guard.py lint-skills. The old first-token CLI checkers are replaced by drift_guard.py, and score-your-setup.py by the cost-audit and security-review skills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Remove v1 images and infographics The SVG infographics were tied to the v1 part structure and carried v1 claims (token tax, seven security layers, release timeline). The desktop and MoA banners were decorative (the desktop mock-up shows an old model picker). The hero banner is kept as a 59 KB JPEG. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Add chapters 03 (Models & Providers) and 04 (Local Models), local template Chapter 03 covers choosing a main model for tool calling, provider routes and what subscription plans actually pay for, /model scope and cache cost, reasoning effort, auxiliary routing, the retry/fallback ladder, credential pools, OpenRouter routing, MoA and hermes proxy. Chapter 04 covers runtimes, the 64K rule, a tool-calling checklist, small-model tuning with measured prefixes, and hybrid setups. templates/config/local.yaml: a local-model profile, validated with the real v0.21.4 loader. Tool schemas drop from 43,062 B (25 tools) to 24,642 B (15 tools), about 4,300 tokens per call. Recipe 6 now uses 'hermes verify --save' so verify_on_stop has a recipe. The drift guard treats provider_routing.models.<id> as open-ended. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Drift guard: check toolset names, gateway keys, correct anchor slugs - Toolset names in 'hermes tools enable|disable', -t/--toolsets, and agent.disabled_toolsets / platform_toolsets YAML are checked against the pinned release's registry (static TOOLSETS plus tool/plugin registrations). mcp-<server>, no_mcp, server:tool and MCP servers the guide defines are accepted. - Top-level keys the gateway reads without a DEFAULT_CONFIG entry (gateway/config_loader.py _TOPLEVEL_BRIDGE) count as config keys. - Heading slugs strip markup before slugging, so underscores inside code spans survive (#...write_approval), matching Docusaurus. - A crash can no longer be silent: importing Hermes swaps sys.stderr, so tracebacks now go to sys.__stderr__ and extract prints where it wrote. Recipe 1 and the cheat sheet: 'hermes cron runs' filters by job ID only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Add chapters 07 (Memory) and 08 (Skills); bot template drops shared USER.md Chapter 07 covers the frozen memory snapshot, what belongs in memory, write approval and cleanup, measured costs, session boundaries and retention, external providers, and privacy. Chapter 08 covers the skill loading levels with measured costs, trust levels and the scanner, writing and linting skills, auto_load and bundles, the curator's real scope, and project/shared skills. messaging-bot.yaml now sets memory.user_profile_enabled: false: USER.md is one file per profile, so on a shared bot what it learns about one person lands in everyone's prompt. Re-measured: ~42 KB -> ~17 KB of tool schemas on Telegram, about 5,800 tokens per message. skills/README.md: install straight from GitHub with 'hermes skills install OnlyTerp/hermes-optimization-guide/skills/<name>' (owner/repo/path identifiers, tools/skills_hub_github.py). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Add chapters 11 (Automation) and 12 (Delegation & Multi-Agent) Chapter 11 covers choosing a trigger, cron (schedules, delivery, model resolution, zero-token and pay-on-change runs, continuity, trimming the cron toolsets: measured -4,100 tokens per call, fleet health, unattended safety), webhooks, /goal, /loop and /heartbeat, hooks, blueprints, scripting with -z, stream-json and send, and the emergency brake. Chapter 12 covers when to split, subagents (what a child gets, measured 7,700 tokens of schemas per call, config, steering, limits), coding agents and worktrees, the Codex runtime, ACP, Kanban and its traps, profiles as agents and distributions, Bot Mode, hermes peer, and A2A. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * CHANGELOG: say where LightRAG went and why the old templates were removed Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * README: link the top-ten list to the exact sections Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * WIP: chapters 09, 10, 13, 14 drafts and the hardened template Drafts pass the drift guard and anchor checks; final review follows. templates/config/hardened.yaml is the chapter 13 hardened profile, and the real v0.21.4 loader reports no structure issues. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Correct the protected-file claim: your own SOUL.md is not approval-gated tools/file_tools_write_guards.py exempts the Hermes home from security.protected_instruction_files ('this gate targets PROJECT-LOCAL files only'). Tested on v0.21.4: a write to ~/.hermes/SOUL.md passes the gate, while a project SOUL.md or AGENTS.md is gated. The upstream SOUL guide says otherwise; the code wins. Chapter 06 now says so and tells you to back up SOUL.md before the Molty rewrite; the cheat sheet row is fixed; the security-review skill checks the extra patterns and the memory/skill write gates. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Pairing: say when strangers really get a code gateway/authz_mixin.py treats a global unauthorized_dm_behavior: pair as the default, and the default becomes 'ignore' once any allowlist is set. The messaging-bot template's global 'pair' line did nothing, so it is replaced by a comment showing the per-platform setting that does work (tested: platforms.telegram.unauthorized_dm_behavior lands in the platform's extra and wins). Recipe 5 now says to leave the allowlist empty when you want pairing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Docs: the drift guard also checks toolset names; note screenshots removal Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * WIP: chapter 09/10 precision edits from the writer's verification pass Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapter 10 final pass; fix chapter 05 streaming claim; guard reads indented YAML Chapter 05 said Telegram streams by default. It doesn't: streaming.enabled is the master switch and defaults to false, and on a fresh install no per-platform value overrides it (gateway/run_turn_runner.py, gateway/display_config.py). The row now says how to turn it on. Chapter 10's final verification pass: approval button sets per platform, Discord intents, /busy scope, the ExecStopPost fix, FAQ anchors, and more. drift_guard reads docs and guide YAML fences at any indentation (docs nest them inside list items). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapter 11: name the four tools webhook runs get Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Cheat sheet: tools, MCP, plugins and security commands; guard accepts -- New rows: /rollback and 'hermes verify --save', a tools/MCP/plugins/ security section (catalog installs, security audit, approvals test and suggest, /platform pause), and approvals.deny / streaming.enabled in the settings table. drift_guard treats '--' as argparse's end of options, so 'hermes approvals test -- <command>' (checked on v0.21.4) passes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Remove the v1 guide: parts 1-29, docs/, benchmarks/, old templates Everything listed in the CHANGELOG's 'Removed' section: the 29 part files (mapped to v2 chapters in CHANGELOG.md), README-zh/ja, docs/ (outreach, evidence, wizard, reference architectures, quickstart, failure modes), benchmarks/, diagrams/, screenshots/, ECOSYSTEM.md, ROADMAP.md, and the v1 templates (five config files, systemd, caddy, compose, cron). All of it remains in git history. With the v1 files gone, every relative link and anchor in the repo resolves, and the drift guard, skill lint, yamllint and shellcheck pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapter 05: explain why byte counts differ slightly between chapters Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * README: point v1 readers to the part-to-chapter map Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Health-check skill: 'not a recognized config key' can be a false alarm v0.21.4 prints it for some real keys (agent.reasoning_effort, model_aliases.*, skills.creation_nudge_interval), found while verifying chapters 03 and 08. Split it from the missing-options row, whose fix is config migrate. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * WIP: chapter 13/14 verification-pass edits Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapter 14: which service names hermes update restarts hermes-serve.service (or hermes-serve-<name>) is restarted by the fleet pass (hermes_cli/update_cmd_fleet.py). hermes-dashboard.service is restarted by the post-update dashboard cleanup step (update_cmd_maint._finish_dashboard_update_cleanup), which skips it when the Node.js dependency refresh failed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Gateway setup: the service is the normal path; don't stack a system unit 'hermes setup' installs and starts a user gateway service without asking (hermes_cli/setup_platforms.setup_gateway), and 'hermes gateway setup' offers to, defaulting to yes (gateway_setup_wizard). Chapter 10 told readers to run 'hermes gateway run' next, which refuses while an installed service is running (_guard_supervised_gateway_conflict). It also recommended adding 'sudo hermes gateway install --system', which would leave two units fighting over one bot token. Chapter 10, the cheat sheet, chapter 15 and the health-check skill now treat the installed service as the normal path, keep the foreground run for debugging with the service stopped, and point to chapter 14's system-unit steps, which uninstall the user service first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Chapters 01/02: setup installs the gateway service; say so ensure_gateway_service (hermes_cli/gateway.py) installs and starts a user-scope service without prompting at the end of Quick and Full setup, so a new user isn't surprised by a background process and doesn't start a second gateway by hand. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * Troubleshooting: list the open Portal OAuth checkpoint issue (#120602) Opened 2026-09-23 and still open: the Portal's Vercel checkpoint returns 403/429 on the OAuth token and JWKS endpoints, so dashboard logins fail. Listed as unsolved, with the documented alternative (SSH tunnel to the loopback-bound dashboard). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * CONTRIBUTING: keep hardened.yaml and chapter 13's block in sync Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf * CI: move actions to their Node 24 majors The first PR run warned that actions/checkout@v4 and actions/setup-python@v5 target the deprecated Node.js 20. checkout@v5, setup-python@v6 and github-script@v8 declare runs.using: node24 and keep the inputs these workflows use (checked in each tag's action.yml). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018gnb1HapdThqvnTJhVMCdf --------- Co-authored-by: Claude <noreply@anthropic.com>