mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-03 09:17:09 +08:00
289cc47631
Broad drift audit against origin/main (b52b63396).
Reference pages (most user-visible drift):
- slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer
that were missing; drop non-existent /terminal-setup; fix /q footnote
(resolves to /queue, not /quit); extend CLI-only list with all 24
CLI-only commands in the registry
- cli-commands: add dedicated sections for hermes curator / fallback /
hooks (new subcommands not previously documented); remove stale
hermes honcho standalone section (the plugin registers dynamically
via hermes memory); list curator/fallback/hooks in top-level table;
fix completion to include fish
- toolsets-reference: document the real 52-toolset count; split browser
vs browser-cdp; add discord / discord_admin / spotify / yuanbao;
correct hermes-cli tool count from 36 to 38; fix misleading claim
that hermes-homeassistant adds tools (it's identical to hermes-cli)
- tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao,
2 Discord toolsets; move browser_cdp/browser_dialog to their own
browser-cdp toolset section
- environment-variables: add 40+ user-facing HERMES_* vars that were
undocumented (--yolo, --accept-hooks, --ignore-*, inference model
override, agent/stream/checkpoint timeouts, OAuth trace, per-platform
batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs,
gateway restart/connect timeouts); dedupe the Cron Scheduler section;
replace stale QQ_SANDBOX with QQ_PORTAL_HOST
User-guide (top level):
- cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20)
- configuration.md: display.platforms is the canonical per-platform
override key; tool_progress_overrides is deprecated and auto-migrated
- profiles.md: model.default is the config key, not model.model
- sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8
- checkpoints-and-rollback.md: destructive-command list now matches
_DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd)
- docker.md: the container runs as non-root hermes (UID 10000) via
gosu; fix install command (uv pip); add missing --insecure on the
dashboard compose example (required for non-loopback bind)
- security.md: systemctl danger pattern also matches 'restart'
- index.md: built-in tool count 47 -> 68
- integrations/index.md: 6 STT providers, 8 memory providers
- integrations/providers.md: drop fictional dashscope/qwen aliases
Features:
- overview.md: 9 image models (not 8), 9 TTS providers (not 5),
8 memory providers (Supermemory was missing)
- tool-gateway.md: 9 image models
- tools.md: extend common-toolsets list with search / messaging /
spotify / discord / debugging / safe
- fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY
(lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan,
tencent-tokenhub, azure-foundry)
- plugins.md: Available Hooks table now includes on_session_finalize,
on_session_reset, subagent_stop
- built-in-plugins.md: add the 7 bundled plugins the page didn't
mention (spotify, google_meet, three image_gen providers, two
dashboard examples)
- web-dashboard.md: add --insecure and --tui flags
- cron.md: hermes cron create takes positional schedule/prompt, not
flags
Messaging:
- telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when
TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it
per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch.
- discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default
is 2.0, not 0.1
- dingtalk.md: document DINGTALK_REQUIRE_MENTION /
FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL /
ALLOW_ALL_USERS that the adapter supports
- bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env
var; the setting lives in platforms.bluebubbles.extra only
- qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and
QQ_GROUP_ALLOWED_USERS
- wecom-callback.md: replace 'hermes gateway start' (service-only)
with 'hermes gateway' for first-time setup
Developer-guide:
- architecture.md: refresh tool/toolset counts (61/52), terminal
backend count (7), line counts for run_agent.py (~13.7k), cli.py
(~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py
(~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform
adapter count 18 -> 20
- agent-loop.md: run_agent.py line count 10.7k -> 13.7k
- tools-runtime.md: add vercel_sandbox backend
- adding-tools.md: remove stale 'Discovery import added to
model_tools.py' checklist item (registry auto-discovery)
- adding-platform-adapters.md: mark send_typing / get_chat_info as
concrete base methods; only connect/disconnect/send are abstract
- acp-internals.md: ACP sessions now persist to SessionDB
(~/.hermes/state.db); acp.run_agent call uses
use_unstable_protocol=True
- cron-internals.md: gateway runs scheduler in a dedicated background
thread via _start_cron_ticker, not on a maintenance cycle; locking
is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows)
- gateway-internals.md: gateway/run.py ~12k lines
- provider-runtime.md: cron DOES support fallback (run_job reads
fallback_providers from config)
- session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations
10 and 11 (trigram FTS, inline-mode FTS5 re-index); add
api_call_count column to Sessions DDL; document messages_fts_trigram
and state_meta in the architecture tree
- context-compression-and-caching.md: remove the obsolete 'context
pressure warnings' section (warnings were removed for causing
models to give up early)
- context-engine-plugin.md: compress() signature now includes
focus_topic param
- extending-the-cli.md: _build_tui_layout_children signature now
includes model_picker_widget; add to default layout
Also fixed three pre-existing broken links/anchors the build warned
about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and
tips#background-tasks, nix-setup.md -> #container-aware-cli).
Regenerated per-skill pages via website/scripts/generate-skill-docs.py
so catalog tables and sidebar are consistent with current SKILL.md
frontmatter.
docusaurus build: clean, no broken links or anchors.
165 lines
6.4 KiB
Markdown
165 lines
6.4 KiB
Markdown
---
|
|
title: "Architecture Diagram — Dark-themed SVG architecture/cloud/infra diagrams as HTML"
|
|
sidebar_label: "Architecture Diagram"
|
|
description: "Dark-themed SVG architecture/cloud/infra diagrams as HTML"
|
|
---
|
|
|
|
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
|
|
|
# Architecture Diagram
|
|
|
|
Dark-themed SVG architecture/cloud/infra diagrams as HTML.
|
|
|
|
## Skill metadata
|
|
|
|
| | |
|
|
|---|---|
|
|
| Source | Bundled (installed by default) |
|
|
| Path | `skills/creative/architecture-diagram` |
|
|
| Version | `1.0.0` |
|
|
| Author | Cocoon AI (hello@cocoon-ai.com), ported by Hermes Agent |
|
|
| License | MIT |
|
|
| Tags | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
|
|
| Related skills | [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
|
|
|
|
## Reference: full SKILL.md
|
|
|
|
:::info
|
|
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
|
:::
|
|
|
|
# Architecture Diagram Skill
|
|
|
|
Generate professional, dark-themed technical architecture diagrams as standalone HTML files with inline SVG graphics. No external tools, no API keys, no rendering libraries — just write the HTML file and open it in a browser.
|
|
|
|
## Scope
|
|
|
|
**Best suited for:**
|
|
- Software system architecture (frontend / backend / database layers)
|
|
- Cloud infrastructure (VPC, regions, subnets, managed services)
|
|
- Microservice / service-mesh topology
|
|
- Database + API map, deployment diagrams
|
|
- Anything with a tech-infra subject that fits a dark, grid-backed aesthetic
|
|
|
|
**Look elsewhere first for:**
|
|
- Physics, chemistry, math, biology, or other scientific subjects
|
|
- Physical objects (vehicles, hardware, anatomy, cross-sections)
|
|
- Floor plans, narrative journeys, educational / textbook-style visuals
|
|
- Hand-drawn whiteboard sketches (consider `excalidraw`)
|
|
- Animated explainers (consider an animation skill)
|
|
|
|
If a more specialized skill is available for the subject, prefer that. If none fits, this skill can also serve as a general SVG diagram fallback — the output will just carry the dark tech aesthetic described below.
|
|
|
|
Based on [Cocoon AI's architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT).
|
|
|
|
## Workflow
|
|
|
|
1. User describes their system architecture (components, connections, technologies)
|
|
2. Generate the HTML file following the design system below
|
|
3. Save with `write_file` to a `.html` file (e.g. `~/architecture-diagram.html`)
|
|
4. User opens in any browser — works offline, no dependencies
|
|
|
|
### Output Location
|
|
|
|
Save diagrams to a user-specified path, or default to the current working directory:
|
|
```
|
|
./[project-name]-architecture.html
|
|
```
|
|
|
|
### Preview
|
|
|
|
After saving, suggest the user open it:
|
|
```bash
|
|
# macOS
|
|
open ./my-architecture.html
|
|
# Linux
|
|
xdg-open ./my-architecture.html
|
|
```
|
|
|
|
## Design System & Visual Language
|
|
|
|
### Color Palette (Semantic Mapping)
|
|
|
|
Use specific `rgba` fills and hex strokes to categorize components:
|
|
|
|
| Component Type | Fill (rgba) | Stroke (Hex) |
|
|
| :--- | :--- | :--- |
|
|
| **Frontend** | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |
|
|
| **Backend** | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |
|
|
| **Database** | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |
|
|
| **AWS/Cloud** | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |
|
|
| **Security** | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |
|
|
| **Message Bus** | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |
|
|
| **External** | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |
|
|
|
|
### Typography & Background
|
|
- **Font:** JetBrains Mono (Monospace), loaded from Google Fonts
|
|
- **Sizes:** 12px (Names), 9px (Sublabels), 8px (Annotations), 7px (Tiny labels)
|
|
- **Background:** Slate-950 (`#020617`) with a subtle 40px grid pattern
|
|
|
|
```svg
|
|
<!-- Background Grid Pattern -->
|
|
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
|
|
<path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
|
|
</pattern>
|
|
```
|
|
|
|
## Technical Implementation Details
|
|
|
|
### Component Rendering
|
|
Components are rounded rectangles (`rx="6"`) with 1.5px strokes. To prevent arrows from showing through semi-transparent fills, use a **double-rect masking technique**:
|
|
1. Draw an opaque background rect (`#0f172a`)
|
|
2. Draw the semi-transparent styled rect on top
|
|
|
|
### Connection Rules
|
|
- **Z-Order:** Draw arrows *early* in the SVG (after the grid) so they render behind component boxes
|
|
- **Arrowheads:** Defined via SVG markers
|
|
- **Security Flows:** Use dashed lines in rose color (`#fb7185`)
|
|
- **Boundaries:**
|
|
- *Security Groups:* Dashed (`4,4`), rose color
|
|
- *Regions:* Large dashed (`8,4`), amber color, `rx="12"`
|
|
|
|
### Spacing & Layout Logic
|
|
- **Standard Height:** 60px (Services); 80-120px (Large components)
|
|
- **Vertical Gap:** Minimum 40px between components
|
|
- **Message Buses:** Must be placed *in the gap* between services, not overlapping them
|
|
- **Legend Placement:** **CRITICAL.** Must be placed outside all boundary boxes. Calculate the lowest Y-coordinate of all boundaries and place the legend at least 20px below it.
|
|
|
|
## Document Structure
|
|
|
|
The generated HTML file follows a four-part layout:
|
|
1. **Header:** Title with a pulsing dot indicator and subtitle
|
|
2. **Main SVG:** The diagram contained within a rounded border card
|
|
3. **Summary Cards:** A grid of three cards below the diagram for high-level details
|
|
4. **Footer:** Minimal metadata
|
|
|
|
### Info Card Pattern
|
|
```html
|
|
<div class="card">
|
|
<div class="card-header">
|
|
<div class="card-dot cyan"></div>
|
|
<h3>Title</h3>
|
|
</div>
|
|
<ul>
|
|
<li>• Item one</li>
|
|
<li>• Item two</li>
|
|
</ul>
|
|
</div>
|
|
```
|
|
|
|
## Output Requirements
|
|
- **Single File:** One self-contained `.html` file
|
|
- **No External Dependencies:** All CSS and SVG must be inline (except Google Fonts)
|
|
- **No JavaScript:** Use pure CSS for any animations (like pulsing dots)
|
|
- **Compatibility:** Must render correctly in any modern web browser
|
|
|
|
## Template Reference
|
|
|
|
Load the full HTML template for the exact structure, CSS, and SVG component examples:
|
|
|
|
```
|
|
skill_view(name="architecture-diagram", file_path="templates/template.html")
|
|
```
|
|
|
|
The template contains working examples of every component type (frontend, backend, database, cloud, security), arrow styles (standard, dashed, curved), security groups, region boundaries, and the legend — use it as your structural reference when generating diagrams.
|