Agent Hermes 与 OpenClaw 工作区文件与 Prompt 组装全解析

Agent Hermes & OpenClaw: Workspace Files and Prompt Assembly — A Deep Dive

最后更新 | Last updated: 2026-06-06

一、设计哲学对比 | Design Philosophy Comparison

中文

工作区文件是「文件即配置」理念的核心：Agent 的人格、流程与知识外化为 Markdown，在会话启动时组装进系统提示词。

English

Workspace files embody files-as-config: agent persona, procedures, and knowledge externalized as Markdown and assembled into the system prompt at session start.

二、OpenClaw 八文件 Bootstrap 体系 | OpenClaw Eight Bootstrap Files

中文

OpenClaw 在 agents.defaults.workspace（默认 ~/.openclaw/workspace/）中维护用户可编辑的 bootstrap 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13

~/.openclaw/workspace/
├── SOUL.md           # 人格、语气、价值观、行为边界
├── AGENTS.md         # 操作手册：工作流、记忆规则、多 Agent 协作
├── USER.md           # 用户偏好与身份信息
├── TOOLS.md          # 工具使用指南（不控制工具是否存在）
├── IDENTITY.md       # Agent 名称、头像、元数据
├── HEARTBEAT.md      # 主动巡检任务清单
├── BOOTSTRAP.md      # 首次运行仪式（完成后删除）
├── MEMORY.md         # 长期记忆（Agent 可更新）
├── memory/           # 日记式记忆（按需，非自动注入）
│   └── 2026-06-05.md
└── skills/           # 技能目录（独立加载机制）
    └── weather/SKILL.md

2.1 注入顺序与优先级

新会话首轮流次，OpenClaw 将 bootstrap 文件注入 Project Context（系统提示词区块）：

设计意图：稳定的人格指令先于易变的记忆内容，降低记忆更新对行为核心的干扰。

2.2 体积控制

空白文件跳过；超大文件截断并附加标记，提示 Agent 用 read 获取全文。memory/*.md 不自动注入，通过 memory 工具按需读取。

2.3 BOOTSTRAP.md 特殊行为

• 仅当工作区无任何其他 bootstrap 文件时由 openclaw setup 创建
• 存在期间保持在 Project Context，指导首次仪式
• 完成后删除，不会在后续重启时重建
• 工作区 attestation 标记防止静默重种

English

OpenClaw maintains eight bootstrap files under the workspace. Injection order: SOUL → IDENTITY → USER → AGENTS → TOOLS → HEARTBEAT → BOOTSTRAP → MEMORY (most volatile last). Blank files skipped; large files truncated per bootstrapMaxChars (20k) and bootstrapTotalMaxChars (150k). memory/*.md is on-demand only. BOOTSTRAP.md is one-time for brand-new workspaces.

三、SOUL 与 AGENTS 职责分离 | SOUL vs AGENTS Separation

中文

两个框架均推荐将人格与流程拆分到不同文件：

反模式示例：

1
2
3
4
5
6
7

# ❌ SOUL.md 中写操作步骤
When deploying, run kubectl apply -f deploy.yaml...

# ✅ AGENTS.md 中写操作步骤
## Deploy workflow
1. Run tests first
2. kubectl apply with --server-side

English

Separate persona (SOUL.md: tone, values, boundaries) from procedures (AGENTS.md: workflows, memory rules, tool conventions). USER.md holds user profile; MEMORY.md holds facts; TOOLS.md guides tool usage without defining which tools exist. Version-control SOUL and AGENTS in Git; let the agent manage MEMORY.

四、Hermes Prompt 三层架构 | Hermes Three-Tier Prompt Architecture

中文

Hermes 将系统提示词分为 stable → context → volatile 三层，优化前缀缓存命中率：

flowchart LR
    subgraph Stable["stable tier（跨会话稳定）"]
        S1[SOUL.md / 身份]
        S2[工具与模型指引]
        S3[技能索引 Level 0]
        S4[平台 hints]
    end
    subgraph Context["context tier（项目相关）"]
        C1[AGENTS.md]
        C2[.cursorrules]
        C3[CLAUDE.md / .hermes.md]
    end
    subgraph Volatile["volatile tier（会话内冻结）"]
        V1[MEMORY.md 快照]
        V2[USER.md 快照]
        V3[外部记忆 Provider 块]
        V4[时间戳/会话元数据]
    end
    Stable --> Context --> Volatile

最终拼接：stable → context → volatile

4.1 项目上下文发现顺序

build_context_files_prompt() 按优先级加载仅一个项目上下文类型（首个匹配胜出）：

Cron 任务可通过 workdir 参数钉在项目目录，注入该目录的上下文文件。

4.2 冻结记忆快照

会话启动时渲染进 volatile tier 后不再变更（保护 LLM 前缀缓存）。会话中 memory 工具可增删改并立即落盘，但下次会话才进入 Prompt。

English

Hermes assembles the system prompt as stable → context → volatile. Stable: identity, skill index, platform hints (cross-session 1h cache on Anthropic). Context: first-match project file (.hermes.md > AGENTS.md > CLAUDE.md > .cursorrules). Volatile: frozen MEMORY/USER snapshots, external memory block, timestamp — captured at session start, not mutated mid-session.

五、Prompt 稳定性与前缀缓存 | Prompt Stability & Prefix Caching

中文

两个框架均将 Prompt 稳定性 作为一等设计目标：

5.1 Hermes Anthropic 缓存策略

1
2
3

Breakpoint 1: System prompt stable 前缀     → cache_control (1h 跨会话)
Breakpoint 2: tools schema 末尾             → cache_control (1h)
Breakpoint 3-4: 最后 2 条非 system 消息      → cache_control (5m 滚动)

配置：

1
2
3
4

prompt_caching:
  cache_ttl: "5m"
  long_lived_prefix: true    # 默认开启
  long_lived_ttl: "1h"

压缩交互：上下文压缩后，stable 前缀缓存存活；仅压缩区域及之后的消息缓存失效，1-2 轮内滚动窗口重建。

5.2 已知缓存破坏点

English

Both frameworks prioritize prompt stability. OpenClaw reuses bootstrap snapshots; Hermes caches _cached_system_prompt once per session. Volatile content at the end preserves prefix cache. Hermes Anthropic strategy: 1h cache on stable prefix + tools schema, 5m rolling on last messages. Compression preserves stable prefix cache; only compressed region invalidates.

六、contextVisibility 与注入防护 | contextVisibility & Injection Protection

中文

6.1 OpenClaw contextVisibility

控制注入模型的补充上下文（引用回复、线程历史），与触发授权分离：

这降低不可信发送者通过引用链注入 Prompt 的风险，不替代 dmPolicy 身份认证。

6.2 上下文文件安全扫描

两个框架在注入前扫描工作区文件：

Hermes 阻断时显示：[BLOCKED: AGENTS.md contained potential prompt injection]

记忆写入（memory 工具）同样经过安全扫描后才进入下次会话快照。

English

OpenClaw contextVisibility filters supplemental context (quotes, thread history) separately from auth: all, allowlist, allowlist_quote. Both frameworks scan workspace files before injection for prompt injection, hidden comments, credential exfiltration, and invisible Unicode. Hermes blocks with [BLOCKED: ...] markers; memory writes are scanned before entering the next session snapshot.

七、Agent 循环与 Prompt 组装流程 | Agent Loop & Prompt Assembly Flow

中文

sequenceDiagram
    participant C as 渠道/CLI
    participant G as Gateway/Runner
    participant P as Prompt Builder
    participant L as LLM
    participant T as Tools
    C->>G: 用户消息
    G->>P: 构建 Prompt
    Note over P: OpenClaw: bootstrap + skills XML + tools
    Note over P: Hermes: stable→context→volatile + tools schema
    P->>L: 系统提示 + 对话历史
    L->>T: 工具调用
    T->>G: 执行结果
    G->>L: 结果回注
    loop 直至无工具调用
        L->>T: 可能更多工具
    end
    L->>C: 最终响应

Hermes 设计原则：

• 提示词稳定性 — 会话中不突变系统提示词
• 可观测执行 — 每次工具调用对用户可见
• 可中断 — 用户可随时取消

OpenClaw Steering：流式响应期间到达的消息默认 steer 进当前 run，在当前 assistant turn 的工具执行完成后、下一次 LLM 调用前注入。

English

Standard agent loop: user message → prompt build (bootstrap/skills/tools or stable/context/volatile) → LLM → tool calls → result injection → loop until done → response. Hermes principles: prompt stability, observable execution, interruptibility. OpenClaw supports mid-run steering of inbound messages.

八、子 Agent 与缩减上下文 | Sub-Agents & Reduced Context

中文

多 Agent 场景下，子代理不应继承完整父会话上下文：

最佳实践：子 Agent 的 prompt 应自包含任务描述，不假设「上文已讨论过 X」。

English

Sub-agents should not inherit full parent context. OpenClaw: sessions_spawn with separate sessionKey/workspace. Hermes: delegate_tool with task description only, no chat history, shared Docker container, cron toolset disabled. Sub-agent prompts must be self-contained.

九、从 OpenClaw 迁移工作区上下文 | Migrating Workspace Context from OpenClaw

中文

hermes claw migrate 可一键导入龙虾工作区的核心 bootstrap 文件：

迁移后注意：

• Hermes 记忆有字符上限，超长 MEMORY/USER 需人工精简
• OpenClaw 全量 MEMORY 注入 → Hermes 冻结快照 + session_search 补历史
• HEARTBEAT.md 不自动映射 — 需改写为 Hermes cronjob 或保留 OpenClaw Gateway 运行 heartbeat
• 共享 ~/.agents/skills/ 可同时服务两个框架的技能发现

1

hermes claw migrate    # 交互式导入 SOUL、记忆、技能、API Key

English

hermes claw migrate imports OpenClaw bootstrap files: SOUL → stable tier identity, USER/MEMORY → frozen volatile snapshots (with char limits), AGENTS.md → context tier (pin via workdir), skills → ~/.hermes/skills/. HEARTBEAT.md has no direct mapping — convert to Hermes cronjob or keep OpenClaw heartbeat. Shared ~/.agents/skills/ works for both frameworks.

十、OpenClaw 与 Hermes 记忆注入对比 | Memory Injection Comparison

中文

English

OpenClaw MEMORY.md has no hard limit but full injection grows token cost linearly. Hermes frozen snapshots cap at ~2200 + ~1375 chars; historical detail via session_search. OpenClaw uses daily memory/*.md files; Hermes uses FTS5 on-demand recall.

十一、最佳实践 | Best Practices

中文

OpenClaw

1. Git 管理 SOUL.md + AGENTS.md；MEMORY.md 可 Agent 自管
2. 控制体积：定期审查 MEMORY.md，避免 bootstrap 总量触顶
3. HEARTBEAT 精简：保持巡检清单短小稳定
4. skipBootstrap：预置工作区时设 agents.defaults.skipBootstrap: true
5. /context detail：诊断各文件 Token 贡献

Hermes Agent

1. 职责分层：关键事实 → MEMORY.md；历史细节 → session_search
2. 项目钉扎：Cron/批处理用 workdir 注入正确 AGENTS.md
3. 勿 mid-session 期待记忆更新：写入落盘但 volatile tier 不变
4. SOUL 迁移：hermes claw migrate 或 /personality 导入龙虾 SOUL
5. 压缩后检查：确认 stable 前缀未被不必要重建

English

OpenClaw: Git-manage SOUL/AGENTS, audit MEMORY size, keep HEARTBEAT concise, use /context detail, skipBootstrap for pre-seeded workspaces.

Hermes: layer facts in MEMORY vs history in session_search, pin cron workdir, don’t expect mid-session memory in prompt, migrate SOUL from OpenClaw, verify stable prefix after compression.

十二、快速对照表 | Quick Reference Table

十三、延伸阅读 | Further Reading

• 记忆系统深度解析
• 技能系统与学习闭环
• 自动化调度与主动巡检
• OpenClaw Agent Runtime
• Hermes Prompt Assembly

十四、结语 | Conclusion

中文

工作区文件与 Prompt 组装是个人 Agent「是谁」和「怎么做」的根基。OpenClaw 以 八文件 Bootstrap + 固定注入顺序 提供透明、可 Git 管理、人类可读的配置面；Hermes 以 stable/context/volatile 三层 + 冻结记忆快照 在可控 Token 成本下最大化前缀缓存效率。掌握 SOUL/AGENTS 分离、注入顺序、稳定性策略和子 Agent 缩减上下文，是部署长期运行、高性价比 Agent 的必备知识。

English

Workspace files and prompt assembly are the foundation of who an agent is and how it operates. OpenClaw offers eight bootstrap files with fixed injection order — transparent, Git-versionable, human-readable config. Hermes offers stable/context/volatile tiers with frozen memory snapshots — controlled token cost and maximal prefix-cache efficiency. Mastering SOUL/AGENTS separation, injection order, stability strategies, and sub-agent reduced context is essential for long-running, cost-effective agent deployments.

Agent Hermes 与 OpenClaw 工具链与执行环境全解析

Agent Hermes & OpenClaw: Toolchains and Execution Environments — A Deep Dive

最后更新 | Last updated: 2026-06-06

一、工具体系概览 | Tool System Overview

中文

两个框架都将「工具」作为 Agent 连接外部世界的桥梁，但组织方式不同：

English

Both frameworks use tools as the bridge to the external world, but organize them differently:

二、Hermes 工具与 Toolsets | Hermes Tools & Toolsets

中文

Hermes 工具按 toolset 分组，每个平台（CLI、Telegram、Cron 等）可独立启用/禁用 toolset 子集：

1
2

hermes tools                    # Curses UI 按平台配置 toolsets
hermes chat --toolsets web,file -q "List files in cwd"

平台预设（hermes tools 中的 platform）：

English

Hermes groups 70+ tools into 28 toolsets. Each platform (CLI, Telegram, Cron, etc.) can enable/disable subsets via hermes tools. Categories: web, terminal/file, browser, media, memory, skills, delegation, cron, code execution, messaging, safe, RL. Presets like hermes-cli (full dev) and hermes-telegram (messaging-focused) tune the default tool surface.

三、Hermes 六类终端后端 | Hermes Six Terminal Backends

中文

所有 terminal、文件工具、execute_code 调用均路由到配置的执行后端：

flowchart TB
    subgraph Hermes["Hermes Tool Dispatch"]
        TD[Tool Dispatch]
    end
    subgraph Backends["6 终端后端"]
        L[local — 本机 Shell]
        D[docker — 持久容器]
        S[ssh — 远程服务器]
        SI[singularity — HPC 容器]
        MO[modal — Serverless 云]
        DA[daytona — 云开发沙箱]
    end
    TD --> L & D & S & SI & MO & DA

1
2
3
4
5
6
7
8
9
10

# ~/.hermes/config.yaml
terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120      # MB
  container_disk: 51200     # MB
  container_persistent: true
  docker_volumes:
    - "/home/user/projects:/workspace/projects"

TERMINAL_ENV 环境变量可覆盖 config.yaml 中的 terminal.backend，适合单次会话临时切换。

English

All terminal, file, and execute_code calls route through the configured backend: local (default), docker, ssh, singularity, modal, or daytona. Configure in ~/.hermes/config.yaml or override with TERMINAL_ENV. Docker is recommended for production Gateway isolation; SSH splits control plane from execution.

四、Docker 持久容器生命周期 | Docker Persistent Container Lifecycle

中文

Hermes Docker 后端的核心理念：一个长驻容器，跨工具调用、跨会话、跨子 Agent 共享。

1
2
3
4
5
6
7

首次 terminal/file/execute_code 调用
    → docker run -d ... sleep 2h（懒创建）
    → 后续全部通过 docker exec 进入同一容器
    → 工作目录、已装包、/workspace 文件在调用间保持
    → /new、/reset、delegate_task 子代理共用同一容器
    → Hermes 进程退出时默认不销毁容器（可复用）
    → 带 hermes-profile= 标签，下一会话毫秒级 attach

与 OpenClaw 对比：OpenClaw 可选 agents.defaults.sandbox.docker 按会话沙箱；Hermes Docker 默认是进程级单容器共享模型，更适合长期开发工作流。

English

Hermes Docker backend uses one long-lived container shared across tool calls, sessions, and sub-agents. Lazy creation on first use; state (cwd, packages, /workspace files) persists between calls. Default: container survives Hermes process exit and reattaches via label on next start. Profile-scoped isolation via hermes-profile= labels. Cleanup after terminal.lifetime_seconds of inactivity when no background processes remain.

五、后台进程、PTY 与 sudo | Background Processes, PTY & Privileges

中文

5.1 后台进程（Background）

1
2
3
4
5
6
7
8
9
10

# Hermes terminal 工具
terminal(command="pytest -v tests/", background=True)
# → {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                              # 列出运行中进程
process(action="poll", session_id="proc_abc123")  # 检查状态
process(action="wait", session_id="proc_abc123")  # 阻塞至完成
process(action="log", session_id="proc_abc123")   # 完整输出
process(action="kill", session_id="proc_abc123")  # 终止
process(action="write", session_id="proc_abc123", data="y")  # 发送输入

两种后台模式：

1. 长驻服务（dev server、watcher）— 永不退出
2. 长任务 + notify_on_complete — 测试/构建完成后自动通知 Agent

watch_patterns 可在输出中匹配错误/就绪标记，中途触发通知。

5.2 PTY 模式

pty=true 启用伪终端，支持交互式 CLI：

• Codex、Claude Code 等 coding agent
• Python REPL、vim、htop 等 TUI 工具

OpenClaw 等效：exec 工具的 pty 参数。

5.3 sudo 与危险命令

容器后端跳过审批：docker/singularity/modal/daytona 将容器视为信任边界，不重复主机级审批。

English

Hermes terminal(background=true) returns a session_id managed via process tool (list/poll/wait/log/kill/write). PTY mode (pty=true) enables interactive CLIs. Container backends skip host approval checks — the container is the boundary. OpenClaw mirrors this with exec + process and pty parameter.

六、OpenClaw 工具 Profile 与分组 | OpenClaw Tool Profiles & Groups

中文

OpenClaw 通过 tools 配置控制 Agent 可见工具集：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  tools: {
    profile: "messaging",           // 预设 profile
    deny: ["group:automation", "group:runtime", "group:fs",
           "sessions_spawn", "sessions_send"],
    allow: ["read", "web_search"],
    fs: { workspaceOnly: true },
    exec: {
      security: "deny",             // deny | allowlist | full
      ask: "always",                // always | on-miss | off
      host: "sandbox",              // auto | sandbox | gateway | node
      timeoutSec: 1800,
    },
    elevated: { enabled: false },
  },
}

工具分组（groups）：

硬化基线（不可信渠道推荐）：

• tools.profile: "messaging"
• deny gateway / cron / sessions_spawn
• tools.fs.workspaceOnly: true
• tools.exec.security: "deny" 或 "allowlist" + ask: "always"

English

OpenClaw controls tool visibility via tools.profile, deny, allow, and groups (group:automation, group:runtime, group:fs). High-risk control-plane tools: gateway, cron, sessions_spawn. Hardened baseline: messaging profile, deny automation/runtime/fs groups, workspaceOnly fs, deny/limit exec with approvals.

七、OpenClaw Exec 安全模型 | OpenClaw Exec Security Model

中文

flowchart TD
    A[exec 工具调用] --> B{host 路由}
    B -->|auto + 有沙箱| C[sandbox]
    B -->|auto + 无沙箱| D[gateway 主机]
    B -->|node| E[配对 Node 设备]
    C --> F{security 模式}
    D --> F
    F -->|deny| G[拒绝]
    F -->|allowlist| H[白名单匹配]
    F -->|full| I[全权限 + ask 门控]
    H --> J{ask 模式}
    I --> J
    J -->|always| K[人工审批]
    J -->|on-miss| L[未命中时询问]
    J -->|off| M[YOLO 执行]

关键安全行为：

• 沙箱默认关闭；host=auto 无沙箱时解析为 gateway
• 显式 host=sandbox 无沙箱时失败关闭，不会静默落到 gateway
• env.PATH 和 LD_* 覆盖在 gateway/node 执行时被拒绝
• OPENCLAW_SHELL=exec 注入子进程环境，供 shell 配置识别
• 长任务用 process 管理，禁止 sleep 循环模拟调度（应用 cron）

会话覆盖：/exec host=auto security=allowlist ask=on-miss

English

OpenClaw exec routes by host (auto→sandbox or gateway, or node). Security modes: deny, allowlist, full. Ask modes gate human approval. Sandbox off by default; explicit host=sandbox fails closed without sandbox. PATH/loader overrides rejected on gateway/node. Use process for long work; use cron for scheduling, not sleep loops. Session overrides via /exec.

八、文件安全与沙箱 | Filesystem Safety & Sandboxing

中文

OpenClaw workspaceOnly: true 限制 read/write/edit 仅在 workspace 目录内操作。Hermes cron 任务可通过 workdir 参数将文件/终端工具钉在特定项目目录。

English

OpenClaw: @openclaw/fs-safe, tools.fs.workspaceOnly, applyPatch.workspaceOnly (default true). Hermes: cwd allowlist, context file scanning, env var stripping. Both constrain filesystem blast radius; Hermes cron workdir pins file/terminal tools to a project directory.

九、浏览器与代码执行 | Browser & Code Execution

中文

9.1 浏览器自动化

Hermes 浏览器工具支持导航、点击、填表、截图；与 web_fetch 互补（后者适合静态抓取）。

9.2 代码执行

English

OpenClaw: browser plugin + SSRF policy + apply_patch for OpenAI models. Hermes: 5 browser backends, browse-sh skill catalog, bidirectional MCP, execute_code in terminal backend sandbox with credential filtering.

十、子 Agent 委派与工具隔离 | Sub-Agent Delegation

中文

Hermes delegate_tool 生成隔离子代理并行处理子任务：

• 子代理继承父级 Docker 容器（共享执行环境）
• 子代理获得缩减上下文（无完整聊天历史）
• Cron 执行时 禁用 cronjob toolset，防止递归调度

OpenClaw sessions_spawn / sessions_send 实现跨会话 Agent 操作，默认应对不可信面 deny。

English

Hermes delegate_tool spawns isolated sub-agents with reduced context, sharing the parent Docker container. Cron runs disable cronjob toolset to prevent recursive scheduling. OpenClaw uses sessions_spawn/sessions_send for cross-session agents — deny by default on untrusted surfaces.

十一、生产部署对照 | Production Deployment Comparison

中文

English

OpenClaw production: enable sandbox, tighten profile/deny, exec deny + ask always, audit with security audit.

Hermes production: terminal.backend: docker or ssh split, per-platform toolsets, manual approvals, cron_mode: deny, hermes doctor.

十二、最佳实践 | Best Practices

中文

通用

1. 最小工具面：只启用任务所需 toolset/profile
2. 容器即边界：生产环境优先 docker 后端，而非 YOLO full exec
3. 后台用 process：长任务 background=true，勿用 sleep 轮询
4. PTY 仅必要时：交互式 CLI 才开 pty=true，减少复杂度

Hermes 专属

1. Cron 任务设 enabled_toolsets: ["web", "file"] 控制 schema 体积
2. Serverless 场景用 modal/daytona，空闲休眠降成本
3. notify_on_complete 用于 >1 分钟的构建/测试

OpenClaw 专属

1. 共享 DM 禁用 group:runtime 和 cron
2. tools.exec.safeBins 仅用于 stdin 过滤器，勿加解释器
3. 启用 strictInlineEval 限制 python -c 类内联执行

English

Universal: minimal tool surface, container as boundary, background via process not sleep loops, PTY only when needed.

Hermes: cron enabled_toolsets, modal/daytona for serverless, notify_on_complete for long builds.

OpenClaw: deny runtime/cron on shared DMs, safeBins for stdin filters only, strictInlineEval for inline eval.

十三、延伸阅读 | Further Reading

• Gateway 架构深度解析
• 安全模型深度解析
• 自动化调度与主动巡检
• OpenClaw Exec 文档
• Hermes Tools 文档

十四、结语 | Conclusion

中文

工具链与执行环境决定了 Agent 能「做什么」以及「爆炸半径有多大」。OpenClaw 以 Profile + Exec 审批 + 可选沙箱 构建灵活的控制面，适合多渠道、多 Node 的广度连接场景。Hermes 以 70+ 工具、28 toolsets、6 后端、持久 Docker 容器 构建深度执行能力，适合长期开发、Serverless 和研究轨迹场景。理解两者的工具哲学——范围控制 vs. 执行深度——是安全配置与性能优化的前提。

English

Toolchains and execution environments define what an agent can do and its blast radius. OpenClaw uses profiles + exec approvals + optional sandbox for flexible control across channels and nodes. Hermes uses 70+ tools, 28 toolsets, 6 backends, and persistent Docker containers for deep execution in long-running dev, serverless, and research scenarios. Understanding scope control vs. execution depth is prerequisite to security hardening and performance tuning.

Agent Hermes 与 OpenClaw 技能系统与学习闭环全解析

Agent Hermes & OpenClaw: Skills System and Learning Loop — A Deep Dive

最后更新 | Last updated: 2026-06-06

一、设计哲学对比 | Design Philosophy Comparison

中文

技能（Skills）是两个框架扩展 Agent「程序性记忆」的核心机制，但学习与治理路径截然不同：

English

Skills are the core mechanism for procedural memory in both frameworks, but learning and governance paths diverge sharply:

二、SKILL.md 开放标准 | The agentskills.io Standard

中文

两个框架均遵循 Agent Skills 开放标准：每个技能是一个目录，内含带 YAML frontmatter 的 SKILL.md 正文。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

---
name: deploy-k8s
description: Deploy services to Kubernetes with rollout verification
version: 1.0.0
metadata:
  {"openclaw": {"requires": {"bins": ["kubectl"], "env": ["KUBECONFIG"]}}}
---

# Deploy to Kubernetes

## When to Use
User asks to deploy, roll out, or verify a K8s service.

## Procedure
1. Validate manifest with `kubectl apply --dry-run=client`
2. Apply and watch rollout status
3. Run smoke checks against the service endpoint

关键约定：

OpenClaw frontmatter 解析器仅支持单行键；metadata 必须是单行 JSON。Hermes 额外支持 platforms、required_environment_variables、fallback_for_toolsets 等扩展。

English

Both frameworks follow the Agent Skills open standard: each skill is a directory containing SKILL.md with YAML frontmatter and a markdown body.

Key conventions: name and description are required; metadata.openclaw gates skills by bins/env/config/OS on OpenClaw; Hermes adds platforms, required_environment_variables, and conditional activation fields. OpenClaw’s parser accepts single-line keys only; metadata must be a single-line JSON object.

三、OpenClaw 技能加载与优先级 | OpenClaw Skill Loading & Precedence

中文

OpenClaw 从多个根目录发现技能，同名技能以高优先级来源覆盖低优先级：

flowchart TB
    subgraph Priority["加载优先级（高 → 低）"]
        W["1. workspace/skills"]
        P["2. workspace/.agents/skills"]
        A["3. ~/.agents/skills"]
        M["4. ~/.openclaw/skills"]
        B["5. bundled skills"]
        E["6. skills.load.extraDirs + 插件"]
    end
    W --> P --> A --> M --> B --> E

安装命令：

1
2
3

openclaw skills install <slug>              # 安装到当前 workspace/skills/
openclaw skills install <slug> --global     # 安装到 ~/.openclaw/skills/
openclaw skills update --all                # 更新 ClawHub 来源技能

门控（Gating）：加载时根据 metadata.openclaw.requires 过滤——缺失二进制、环境变量或配置项的技能不会进入 eligible 列表。always: true 可跳过所有门控。

会话快照：会话启动时对 eligible 技能拍快照，同会话后续轮次复用；skills.load.watch: true 时 SKILL.md 变更会在下一轮刷新。

English

OpenClaw discovers skills from multiple roots; same-named skills are overridden by higher-precedence sources. Priority: workspace → project .agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled → extraDirs + plugins. Install with openclaw skills install; use --global for shared managed dir. Gating filters by bins/env/config at load time. Session snapshots reuse the eligible list until refresh on new session or watcher bump.

四、ClawHub 与 Skill Workshop | ClawHub & Skill Workshop

中文

4.1 ClawHub 公共注册表

ClawHub 是 OpenClaw 的公共技能市场：

ClawHub 技能页展示 VirusTotal、ClawScan、静态分析等安全扫描状态。安装时记录 .clawhub/origin.json 用于后续 verify。

4.2 Skill Workshop 提案队列

OpenClaw 的治理型学习路径：Agent 不直接写活跃 SKILL.md，而是先创建 PROPOSAL.md 提案。

stateDiagram-v2
    [*] --> pending: Agent 起草提案
    pending --> applied: 人工/策略 apply
    pending --> rejected: reject
    pending --> quarantined: 安全隔离
    pending --> stale: 目标技能 hash 已变
    applied --> [*]: 写入 SKILL.md
    rejected --> [*]
    quarantined --> [*]

核心规则：

• 提案优先：生成内容存为 PROPOSAL.md，非 SKILL.md
• Apply 是唯一活写：create/update/revise 不改动活跃技能
• Hash 绑定：update 提案绑定目标技能当前 hash，过期变 stale
• 扫描门控：apply 前重新运行安全扫描
• 审批策略：默认 approvalPolicy: "pending"；"auto" 跳过人工确认

1
2
3
4

openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>
openclaw skills workshop reject <proposal-id> --reason "Not reusable"

skills.workshop.autonomous.enabled: false（默认）控制是否在成功回合后自动起草提案。

English

ClawHub is OpenClaw’s public skill registry with install, verify, and publish flows. Skill Workshop is the governed learning path: agents draft PROPOSAL.md instead of writing live SKILL.md. Lifecycle: pending → applied/rejected/quarantined/stale. Apply is the only live write; hash binding and scanner gating protect integrity. CLI: openclaw skills workshop list/inspect/apply/reject.

五、OpenClaw 技能 Token 成本公式 | OpenClaw Skill Token Cost Formula

中文

OpenClaw 将 eligible 技能编译为紧凑 XML 块注入系统提示词（仅元数据，全文通过 read 按需加载）：

1

total_chars = 195 + Σ (97 + len(name) + len(description) + len(filepath))

示例：50 个技能，平均 name=12、description=80、filepath=40：

1

total ≈ 195 + 50 × (97 + 12 + 80 + 40) = 195 + 11,450 ≈ 11,645 字符 ≈ ~2,900 tokens

优化建议：

• 保持 description 简短（影响每技能成本）
• 用 agents.defaults.skills allowlist 限制可见技能
• skills.limits.maxSkillsPromptChars 设上限
• /context detail 诊断当前会话技能贡献
• 禁用不需要的 bundled 技能：skills.entries.<name>.enabled: false

English

Eligible skills compile into a compact XML block in the system prompt (metadata only; full instructions loaded on demand via read). Formula: total = 195 + Σ(97 + len(name) + len(description) + len(filepath)). Base 195 chars when ≥1 skill; ~97 chars wrapper per skill plus field lengths. At ~4 chars/token, expect ~24 tokens/skill before fields. Trim descriptions, use allowlists, set maxSkillsPromptChars, and run /context detail to diagnose.

六、Hermes 渐进式披露 | Hermes Progressive Disclosure

中文

Hermes 将技能作为第四层程序性记忆，采用三级渐进式披露控制 Token：

1
2
3

Level 0: skills_list()           → [{name, description, category}]   (~3k tokens)
Level 1: skill_view(name)        → 完整 SKILL.md + metadata            (按需)
Level 2: skill_view(name, path)  → references/ 等附属文件              (按需)

sequenceDiagram
    participant U as 用户
    participant A as AIAgent
    participant S as Skill Index
    participant F as SKILL.md 全文
    U->>A: 复杂任务请求
    Note over A,S: 会话启动
    A->>S: Level 0 索引已在 stable tier
    A->>A: 判断需要某技能
    A->>F: skill_view(name) — Level 1
    opt 需要参考文件
        A->>F: skill_view(name, path) — Level 2
    end
    A->>U: 按技能指引执行

效果：技能库从 40 个增长到 200 个，Level 0 成本几乎不变（~3k tokens）；仅实际使用的技能产生 Level 1/2 开销。

技能索引属于 Prompt stable tier（与 SOUL、工具指引同层），保证前缀缓存友好；全文加载通过工具调用注入对话，不污染系统提示词前缀。

English

Hermes treats skills as fourth-layer procedural memory with three disclosure levels: Level 0 index (~3k tokens at session start), Level 1 full SKILL.md on demand, Level 2 reference files on demand. Libraries can grow from 40 to 200 skills with near-flat Level 0 cost. The index lives in the stable prompt tier; full content loads via tool calls without mutating the cached prefix.

七、Hermes 闭环学习（skill_manage）| Hermes Closed Learning Loop

中文

Hermes 最核心的差异化能力：任务完成后 Agent 自主沉淀技能，无需人工编写。

7.1 自动创建触发条件

7.2 skill_manage 工具操作

1
2
3
4
5
6
7

# 优先 patch — 比 edit 更省 Token
skill_manage(
    action="patch",
    name="deploy-k8s",
    old_string="kubectl apply -f manifest.yaml",
    new_string="kubectl apply -f manifest.yaml --server-side"
)

7.3 与记忆系统的协同

flowchart LR
    T[任务完成] --> M[memory 工具策划事实]
    T --> S[skill_manage 沉淀流程]
    T --> DB[SQLite FTS5 索引会话]
    S --> N[下次同类任务]
    N --> V[skill_view 按需加载]
    N --> SS[session_search 历史召回]

Periodic Nudge：会话间隙触发自我反思，可能更新 MEMORY.md 或 patch 现有技能。

English

Hermes’s key differentiator: after tasks, the agent curates procedural memory via skill_manage. Triggers: 5+ tool calls, error recovery, user corrections, non-trivial workflows. Prefer patch over edit for token efficiency. Synergy with memory tool curation, FTS5 session indexing, and Periodic Nudge between sessions.

八、Skills Hub 与供应链安全 | Skills Hub & Supply Chain Security

中文

8.1 Hermes Skills Hub 来源

1
2
3
4
5

hermes skills browse
hermes skills search kubernetes --source skills-sh
hermes skills install openai/skills/k8s        # 安全扫描后安装
hermes skills install <slug> --force           # 覆盖 caution/warn，不可覆盖 dangerous
hermes skills audit                            # 重扫已安装技能

8.2 信任等级与安全扫描

扫描项：数据外泄、Prompt 注入、破坏性命令、供应链信号。dangerous 判定不可被 --force 覆盖。

8.3 Hermes Skill Bundles

~/.hermes/skill-bundles/*.yaml 将多个技能组合为单一斜杠命令：

1
2
3
4
5
6
7
8

name: backend-dev
description: Backend feature work — review, test, PR
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start with failing tests, then implement.

/backend-dev refactor auth middleware 一次加载全部技能。Bundle 不修改系统提示词缓存，在调用时生成新 user message。

English

Hermes Skills Hub integrates official, skills-sh, well-known, GitHub, ClawHub, browse-sh, and direct URL sources. Trust levels: builtin > official > trusted > community. Security scan blocks dangerous verdicts regardless of --force. Skill bundles group multiple skills under one slash command without invalidating the prompt cache.

九、学习路径对比与选型 | Learning Path Comparison

中文

选型建议：

• 重视人工审核与社区市场 → OpenClaw + ClawHub + Skill Workshop
• 重视自动进化与 Token 效率 → Hermes + skill_manage + 渐进式披露
• 已有龙虾技能库 → hermes claw migrate 或保持 OpenClaw 加载顺序兼容的 ~/.agents/skills/ 共享目录

English

Choose OpenClaw for human-reviewed community skills; choose Hermes for automatic evolution and token-efficient progressive disclosure.

十、最佳实践 | Best Practices

中文

OpenClaw

1. 工作区优先：项目专属技能放 workspace/skills/，全局共享放 ~/.openclaw/skills/
2. 简短描述：直接影响 Token 公式中的 len(description)
3. 启用 Workshop：生产环境保持 approvalPolicy: "pending"
4. 定期 verify：openclaw skills verify 检查 ClawHub 信任信封
5. allowlist 收敛：多 Agent 场景用 agents.list[].skills 限制爆炸半径

Hermes Agent

1. 信任闭环学习：复杂任务后让 Agent 自动 skill_manage，不必手写一切
2. 优先 patch：小改动用 patch 而非 edit，节省 Token 与 diff 可读性
3. Hub 安装先 inspect：hermes skills inspect 预览后再 install
4. 善用 bundle： recurring 多技能任务用 /backend-dev 而非多次 /skill
5. 外部目录只读：共享 external_dirs 用文件权限防止 Agent 误改

English

OpenClaw: workspace-first layout, short descriptions, Workshop with pending approval, periodic verify, per-agent allowlists.

Hermes: trust the learning loop, prefer patch, inspect before install, use bundles for recurring multi-skill tasks, make shared external_dirs read-only when needed.

十一、延伸阅读 | Further Reading

• 记忆系统深度解析 — 技能作为第四层程序性记忆
• 工作区文件与 Prompt 组装 — stable tier 中的技能索引
• 安全模型深度解析 — Skills 供应链扫描
• Agent Skills 开放标准
• OpenClaw Skills 文档
• Hermes Skills 文档

十二、结语 | Conclusion

中文

OpenClaw 的技能系统是 「连接生态 + 人工治理」 — 通过 agentskills.io 标准、六级加载优先级、ClawHub 市场和 Skill Workshop 提案队列，让社区技能可发现、可审计、可控制爆炸半径。Hermes 的技能系统是 「进化引擎 + 渐进披露」 — 通过 skill_manage 闭环学习、Level 0-2 披露和 Skills Hub 多源集成，让 Agent 从经验中自动沉淀程序性记忆，同时保持 Token 成本近乎平坦。二者共享同一文件格式，却服务不同的产品哲学：广度连接 与 深度进化。

English

OpenClaw’s skill system is connectivity + human governance — agentskills.io standard, six-tier loading precedence, ClawHub marketplace, and Skill Workshop proposal queues for discoverable, auditable community skills. Hermes’s skill system is evolution engine + progressive disclosure — skill_manage closed-loop learning, Level 0-2 disclosure, and multi-source Skills Hub for automatic procedural memory with near-flat token cost. Both share the same file format but serve different philosophies: connectivity breadth vs. evolutionary depth.

从 2021 超大规模预训练到 2026 系统智能，按年份归档的技术博客系列索引，每篇中英文对照。

AnythingLLM 是由 Mintplex Labs 开发的开源一体化 AI 应用，涵盖架构设计、RAG 数据流、Agent/MCP 能力、典型应用场景与优缺点分析，中英文对照。

从「能调一次 API」到「能上线、能评估、能运维」，Agent 开发需要跨越语言栈、模型能力、编排框架、工具集成与工程化五条战线。本页是 Agent 开发学习路线 系列的 master index：将能力拆成 五层模型、14 篇独立博文，每篇约 1500–2500 字、含可运行示例与系列内上下篇链接，可单独阅读，也可按下文推荐顺序串成 2–4 周自学计划。

适用读者：有基础编程经验、希望系统补齐 LLM Agent 全栈能力的后端、全栈与 ML 工程师；不要求先通读 LangChain 文档，但建议具备 HTTP/JSON 与命令行使用经验。

五层能力模型

第一层解决「运行时与数据契约」：Agent 代码大量依赖 async/await、流式响应与 Pydantic/Zod 校验，语言基本功不到位会在工具调用与状态持久化处反复踩坑。第二层解决「模型行为与知识注入」：同一套业务逻辑，Prompt 与 RAG 设计差一个档次，幻觉与成本会差一个数量级。第三层是多数团队的选型焦点：用图（LangGraph）还是 Handoff（OpenAI SDK）还是角色剧组（CrewAI），取决于任务是否需要确定性分支与人机协同。第四层把 Agent 从聊天玩具接到 CRM、工单与内部 API；MCP 与 Function Calling 分工在于「能力发现/隔离」与「单次工具契约」。第五层则回答上线后的问题：镜像与密钥、队列削峰、评测集防回归——没有这一层，Demo 很难变成可 SLO 的服务。

14 篇系列目录

第一层：编程基础

1. Agent 开发基础：Python 3.10+ 必备技能（类型注解 / 异步 / Pydantic）
   异步 I/O、Pydantic 与类型注解，把 Python 用到主流 Agent 框架的预期水平。

2. Agent 全栈开发：TypeScript 与 Node.js 实战指南
   对话 UI、SSE 流式与 B 端控制台场景下的 TS 全栈 Agent 实践。

第二层：大模型基础

3. Agent 开发必修课：Prompt Engineering 系统性设计
   角色、约束、Few-shot 与工具边界写法，是 Agent 可靠性的底座。

4. 主流大模型 API 调用实战：OpenAI / Claude / DeepSeek / 通义千问
   多厂商 SDK、流式、重试与用量控制，统一「你请求模型」这一侧。

5. Agent 记忆系统：Embedding 与向量检索实战（Chroma / Milvus / Qdrant）
   向量库选型与 RAG 流水线，解决上下文有限而业务记忆无限的问题。

第三层：Agent 框架

6. Agent 框架核心：LangChain 与 LangGraph 面试必考知识点
   LCEL、Tool 绑定、ReAct 与图 State/Checkpoint，生态内最通用的编排基座。

7. OpenAI Agents SDK 实战：Agent 定义、Handoff 与 Guardrails
   官方轻量多 Agent 运行时，与 Responses API、Tracing 深度集成。

8. 多 Agent 协作框架：CrewAI 角色扮演 vs AutoGen 对话驱动
   角色化「剧组」与对话式群聊两种多 Agent 心智模型对比选型。

第四层：工具集成

9. MCP 协议实战：让 Agent 连接一切外部工具（Model Context Protocol）
   标准化工具发现与进程隔离，把能力从 Host 应用中抽离。

10. Function Calling 深度解析：Tool Use 参数设计、并行调用与错误处理
    Schema、并行 Tool 与失败语义，让模型「知道该调什么、怎么调」。

11. Agent 外部世界集成：RESTful API、OAuth 认证与 Webhook 处理
    把 Agent 接到企业 REST、OAuth 与异步 Webhook 业务系统。

第五层：工程化

12. Agent 应用部署：Docker 容器化与基础 DevOps 实践
    可复现镜像、密钥注入、CI 与可观测性，从笔记本 Demo 到可运维服务。

13. Agent 异步基础设施：Redis 缓存与消息队列实战
    会话状态、限流、任务队列与多 Worker，支撑高并发 Agent 服务。

14. Agent 质量闭环：LLM 评估、回归测试与线上监控
    评测集、自动化回归与指标看板，让迭代可度量、可回滚。

推荐学习顺序

1
2
3
4
5
6
7
8
9
10
11
12
13
14

                  ┌─────────────────────────────────────┐
                  │  可选先读：架构全景 / LangGraph 生产  │
                  └─────────────────┬───────────────────┘
                                    ▼
[01 Python] ──► [02 TS/Node] ──► [03 Prompt] ──► [04 API] ──► [05 Embedding]
                                    │
                                    ▼
            [06 LangChain/LangGraph] ──► [07 OpenAI SDK] ──► [08 CrewAI/AutoGen]
                                    │
                                    ▼
       [09 MCP] ──► [10 Function Calling] ──► [11 API 集成]
                                    │
                                    ▼
            [12 Docker] ──► [13 Redis/队列] ──► [14 评估与测试]

• 纵向主线：01→05 打基础，06→08 选 1–2 个框架深入，09→11 接工具与业务，12→14 上线与质量。
• 横向选修：只做 Python 后端可跳过 02；已有前端栈可 02 与 01 对调阅读顺序。
• 框架层不必三篇全读：06 为通用基线；若团队已标准化 OpenAI 栈，07 优先；若业务是「多角色分工报告」，08 优先。
• 工具层建议 09→10→11 顺序：先理解 MCP 传输与发现，再深化 Function Calling 参数设计，最后落到企业 API 的 OAuth 与 Webhook。

按角色快速选课

后端应保证 05（RAG/记忆）与 11（业务 API）不跳：生产 Agent 几乎都需要检索与写操作幂等。全栈可把 02 作入口，用 07 快速出可演示的多 Agent 原型，再在 12 补部署。ML 可把 14 提前：评测与回归是模型迭代的安全网；08 用于探索多 Agent 论文式工作流，与 06 的图编排形成对照。

每篇文末均有「上一篇 / 下一篇」链接；若从本索引跳入中间某篇，建议至少回读该层前置一篇（例如读 10 前先扫 09 的 MCP 与 04 的 tools 字段）。

延伸阅读（系列外深度文）

若希望先建立全局图景再逐篇精读，建议配合以下两篇（与系列 06 互补，不重复展开 LCEL 细节）：

• LLM Agent 架构全景：LangChain 生态设计与实践（中英文对照） — ReAct、RAG、多 Agent 模式与生态选型鸟瞰。
• LangGraph 深度指南：从图状态机到生产级 Agent（中英文对照） — PostgresSaver、Studio、监控与生产部署细节。

学习节奏建议

按上表从第一层起步，或先读架构全景再按 slug 跳转对应博文，即可系统补齐 Agent 全栈能力。系列持续更新，欢迎从任意一篇收藏本索引以便回溯。祝学习顺利。

English Title: Agent Evaluation & Testing — LLM-as-Judge and Regression Strategies

完成 Redis 与消息队列 后，你的 Agent 已经能在容器里跑起来、用 Redis 扛会话与任务队列。但「能跑」不等于「敢上线」：同一条用户问题，换模型版本或改一句 System Prompt，回答可能从正确工单分类变成幻觉引用。传统单元测试断言 assert result == 42 在 LLM 场景往往失效——你需要一套 面向分布的评测体系：可重复的 Golden Dataset、自动回归、以及用更强模型当裁判的 LLM-as-Judge。本文是系列第 14 篇（收官篇），把评估从「人肉点踩」推进到可 CI 集成的工程流程。

1. 为什么 Agent 测试特别难？

Agent 链路比单次 Chat Completion 更长：规划 → 多轮 Tool 调用 → 记忆/RAG 注入 → 最终回复。难点集中在以下几类：

因此 Agent 测试通常是 分层组合：底层 Tool 与解析器仍用确定性单测；中层用 轨迹断言（调了哪些工具、参数是否合法）；顶层用 端到端评测集 衡量任务完成率与安全合规。切忌只测「模型有没有返回字符串」——那会放过工具选错、参数幻觉等生产事故主因。

2. 评估维度：准确率、安全、延迟、成本

上线前建议把指标写进 Dashboard，并与业务 SLA 对齐：

工程习惯： 每次 Prompt / 模型变更跑同一套 Golden Set，记录四维指标的 delta，避免「准确率升 2%、成本涨 40%」未被看见。安全维度建议 失败即阻断合并（fail closed），功能维度可用阈值 + 人工复核。

3. LLM-as-Judge 方法论

当参考答案无法逐字对比时，用 更强的 Judge 模型（或专用评测模型）按 Rubric 打分，是 2026 年 Agent 团队的主流做法。

基本流程：

1. 定义 评分准则（Rubric）：如「事实正确 0–2」「工具使用合理 0–2」「格式合规 0–1」。
2. Judge 输入：用户问题 + Agent 最终回答 +（可选）参考要点 + 工具轨迹摘要。
3. Judge 输出：结构化 JSON（分数 + 一句理由），便于聚合与回归对比。
4. 校准：抽 50–100 条让人类标注，计算 Judge 与人类的 Cohen’s κ；κ 过低则改 Rubric 或换 Judge 模型。

常见陷阱：

• 位置偏见（Position Bias）：比较 A/B 两条回答时，Judge 偏爱先出现的；应随机交换顺序或分两次单评。
• 自我偏好：用与被测相同的模型当 Judge 会偏宽松；尽量用 更强或不同家族 的模型。
• 长度偏见：更长不等于更好；Rubric 里写明「简洁不扣分」。

Judge 适合评 主观质量；涉及数学、代码执行结果，仍应以 可执行验证（pytest、SQL 查询、API 回读）为准。

4. Golden Dataset 与回归测试

Golden Dataset（黄金集） 是一组经人工审核的 (input, expected_behavior, optional_reference)，覆盖主路径与已知边界（空输入、歧义、对抗、多语言等）。

构建原则：

• 版本化：datasets/support_v3.jsonl，与 Prompt v3、模型 gpt-4.1-mini 绑定。
• 稳定输入：RAG 场景可 冻结检索结果（recorded chunks），避免索引更新导致回归噪声。
• 行为断言优先于全文：例如 assert "create_ticket" in trace.tools 或 assert json.loads(output)["status"] == "ok"。

回归测试（Regression Testing） 在 CI 中每次 PR 触发：对 Golden Set 跑 Agent → 聚合指标 → 与 main 分支基线 对比。若任务完成率下降超过阈值（如 3%）或安全用例失败，则阻断合并。样本量较小时可用 统计检验 或「连续两次 nightly 下降」再告警，降低抖动误报。

维护 Golden Set 时，建议为每条用例打上 标签（billing、refund、rag_miss），回归报告按标签出 breakdown——避免「总体准确率不变，但退款场景全面劣化」被平均值掩盖。对 flaky 用例（偶发网络超时），标记 quarantine 并单独追踪，不要与 Prompt 回归混在同一门禁里。

5. LangSmith 与自建 Eval Pipeline

LangSmith（及同类：Weights & Biases Weave、Braintrust、Arize Phoenix）提供：Trace 采集、数据集管理、在线/离线评测、Prompt 版本对比。适合已使用 LangChain/LangGraph 的团队——run_on_dataset 一类 API 能把「跑一遍集合并打分」标准化。

自建 Pipeline 适合深度定制或数据不出境的场景，最小架构：

1

Golden JSONL → Runner(Agent) → Traces(JSON) → Scorers(规则 + LLM Judge) → Report(HTML/PR Comment)

要点：Runner 与生产共用同一 Tool Gateway 配置（可指向 Mock）；Scorers 插件化（exact_match、json_schema、llm_judge）；结果写入 Postgres 或 S3，供历史曲线查询。无论 LangSmith 还是自建，都应把 trace_id 写进日志，方便从失败样本反查完整多步轨迹。

离线评测通过后，仍建议保留 影子流量（Shadow）：生产请求复制一份到评测环境，只记录不调真实副作用，用于发现「评测集未覆盖的长尾问法」。影子模式对 Redis 队列与 Worker 容量有要求——可与系列前文中的异步拓扑结合，避免拖慢主链路。

6. A/B 测试 Prompt 与模型

Prompt 与模型迭代应走 实验框架，而非直接全量切换：

实验变量 一次只改一类（只改 System 或只换模型），否则无法归因。记录 experiment_id 到 trace metadata，便于 SQL 聚合。注意 新奇效应：新模型短期指标可能虚高，至少观察 1–2 个完整业务周期。

7. Python 评测示例

以下示例展示：规则打分 + LLM-as-Judge + 简单回归门控（伪代码级，便于迁入 pytest）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# eval/scorers.py
import json
from dataclasses import dataclass

@dataclass
class EvalCase:
    user_input: str
    must_call_tools: list[str]  # 例如 ["search_kb", "create_ticket"]
    reference_points: list[str]  # Judge 对照要点

def score_tools(trace: dict, case: EvalCase) -> float:
    called = {t["name"] for t in trace.get("tool_calls", [])}
    if not set(case.must_call_tools).issubset(called):
        return 0.0
    return 1.0

def llm_judge(client, case: EvalCase, answer: str) -> dict:
    rubric = (
        "按 0-5 打分：事实正确、工具合理、用户问题是否解决。"
        "只输出 JSON：{\"score\": int, \"reason\": str}"
    )
    resp = client.chat.completions.create(
        model="gpt-4.1",  # Judge 强于被测模型
        messages=[
            {"role": "system", "content": rubric},
            {"role": "user", "content": json.dumps({
                "question": case.user_input,
                "reference_points": case.reference_points,
                "answer": answer,
            }, ensure_ascii=False)},
        ],
        response_format={"type": "json_object"},
    )
    return json.loads(resp.choices[0].message.content)

# eval/run_regression.py
def run_suite(agent_run, cases: list[EvalCase], baseline: float = 0.85) -> None:
    scores = []
    for case in cases:
        trace, answer = agent_run(case.user_input)
        t = score_tools(trace, case)
        j = llm_judge(judge_client, case, answer)["score"] / 5.0
        scores.append(0.4 * t + 0.6 * j)  # 可按业务调权
    mean = sum(scores) / len(scores)
    assert mean >= baseline, f"regression: {mean:.3f} < {baseline}"

结合 LangSmith 时，可将 agent_run 换为 client.run_on_dataset(dataset_name="support_golden_v3")，自定义 Evaluator 封装上述 llm_judge。本地开发则用 pytest -k eval 只跑快速子集（10 条），nightly 跑全量 200+ 条。

8. 小结与系列导航

Agent 测试没有银弹，但有清晰路径：确定性层测 Tool 与解析，分布层用 Golden Set + 回归，主观层用 LLM-as-Judge（需人工校准），上线用 A/B 验证业务指标。把评测接进 CI 后，Prompt 迭代从「凭感觉」变为「有证据的发布」——这与本系列强调的 Prompt 版本化、Docker 交付、Redis 异步拓扑一起，构成可运维 Agent 产品的最后一块拼图。

系列导航 Series Navigation：

• 上一篇：Redis 与消息队列
• 系列目录（全 14 篇）：Agent 开发学习路线索引（规划见仓库 docs/agent-learning-series-plan.md）
• 系列起点：Python 3.10+ Agent 开发基础

若你从零跟完本系列，建议用一篇 roadmap 复盘文 串起五层能力模型，并在团队内落地：Golden Dataset 仓库、每周回归报告、Judge κ 季度复核——让 Agent 质量成为可度量的工程资产，而非上线后的救火现场。

English Title: Agent State & Task Queues — Redis Caching & Message Queue Patterns

在 Docker 与基础 DevOps 里，你已经用 compose 把 Agent API、Redis 与向量库拉成同一拓扑。容器解决的是 交付一致性；真正扛住多用户并发、长对话与后台任务的，往往是 Redis 作为会话缓存 + 消息队列中枢。没有它，每个请求都把完整对话历史塞进 LLM 上下文，或把耗时 Tool 调用阻塞在 HTTP 线程里——延迟与成本会迅速失控。本文是系列第 13 篇，聚焦 Agent 场景下的 Redis 缓存模式、异步任务队列、Pub/Sub 协作，以及生产级持久化与 TTL 策略。

1. 为什么 Agent 离不开 Redis 与消息队列

Agent 运行时有三类「状态」需要跨请求、跨进程共享：

Redis 在 Agent 栈里常扮演三重角色：

1. 缓存（Cache）：热会话、限流计数、短期 Tool 结果去重。
2. 队列（Queue）：Celery / BullMQ / Redis Streams 承载异步 Job。
3. Pub/Sub：多 Agent 实例或「审批通过」事件的轻量通知。

与 Postgres / LangGraph Checkpointer 的分工：Redis 管热路径与毫秒级读写；关系库或专用 Checkpointer 管可审计、可回溯的长期状态。许多团队两者并存，而不是二选一。

常见反模式也要警惕：把 Redis 当「唯一真相源」却不做持久化，重启即丢全站会话；或把完整 RAG 检索结果（数万 token）塞进 String，导致 big key 阻塞单线程 Redis。正确做法是：热小冷大——热数据在 Redis，大块内容与审计日志在外部存储。

2. 会话状态缓存模式

2.1 Key 设计与 TTL

推荐按租户与会话隔离 Key，避免全局撞车：

1
2

agent:session:{tenant_id}:{thread_id}  → Hash
agent:ratelimit:{user_id}              → String (INCR + EXPIRE)

Hash 存会话字段 示例：messages（JSON 数组或压缩 blob）、last_model、tool_state、updated_at。每次用户发消息时 HSET 更新，并 EXPIRE 滑动续期（如 24h 无活动则淘汰）。

2.2 只缓存「窗口」而非全量历史

LLM 上下文有 token 上限。缓存策略应是：

• Redis 存 最近 K 轮 或 摘要 + 最近几轮（摘要可由异步 Job 生成后写回 Hash 字段 summary）。
• 冷历史落库或对象存储；需要时再按 thread_id 拉取。

这样既控制 Redis 内存，也避免每次请求反序列化 megabytes 级 JSON。

2.3 与 Checkpointer 对齐

若使用 LangGraph，Checkpointer 可能写 Postgres；Redis 仍可作 读加速层：API 先读 Redis，miss 再读 DB 并回填。注意 写顺序：以 Checkpointer 为准，Redis 仅缓存，避免双写不一致。

2.4 限流与熔断

Agent 调用 LLM 按 token 计费，必须在 Redis 做 租户级限流：INCR agent:rl:{tenant}:{minute} 配合 EXPIRE 60，超限则返回 429 或降级到更小模型。Tool 调用外部 API 时，同样可对 user_id + tool_name 维度限流，防止模型陷入「疯狂重试」把下游打挂。

3. 异步任务队列：Celery、BullMQ 与 Redis Streams

Agent 中适合入队的操作：文档切块嵌入、向量库 upsert、发送通知、重试失败的 Webhook、长耗时 Tool（生成报告 PDF 等）。

选型建议： Python 全栈 Agent 优先 Celery；Node 服务用 BullMQ；若已有统一 Redis 且团队愿维护消费逻辑，Streams 可减少中间件种类。

任务载荷应包含：job_id、thread_id、tenant_id、trace_id（对接 OpenTelemetry），便于日志串联。幂等键写入 Redis SET job:done:{id} NX EX 3600，防止 Worker 重试导致重复副作用。

与 HTTP 请求的衔接： API 收到用户消息后，先写会话 Hash，再 delay() / add() 入队；立即返回 202 Accepted 与 job_id，前端轮询或 SSE 订阅进度字段 status（queued → running → done）。这样用户不必盯着 30 秒的 Tool 调用，体验与 API 集成 里的 Webhook 异步模式一致。

Celery 配置要点：task_acks_late=True 保证 Worker 崩溃时任务可重投；task_time_limit 防止嵌入死循环；result_backend 可仍用 Redis，但 不要把超大结果塞进 backend——结果写对象存储，Redis 只存 URL。

4. Pub/Sub 与多 Agent 协调

Redis 经典 Pub/Sub 不持久化：订阅者离线则消息丢失，适合「提示性」事件，不适合资金类事务。

典型 Agent 场景：

• Human-in-the-loop：审批服务 PUBLISH agent:approval:{thread_id} '{"approved":true}'，阻塞中的 Agent Worker SUBSCRIBE 后恢复图执行。
• 多 Agent 广播：Planner 完成分解后 PUBLISH agent:plan:ready，Executor 实例各自订阅（或按 channel 分片）。

需要 至少一次投递 时，改用 Redis Streams 或独立 MQ（RabbitMQ、Kafka），不要用裸 Pub/Sub。

CrewAI / AutoGen 多 Agent 场景下，可用 channel 区分角色：agent:role:planner、agent:role:critic。Planner 发布子任务描述，多个 Executor 竞争消费 Stream，避免单点 Worker 成为瓶颈——这与消费者组（Consumer Group）模型天然契合。

5. Agent 场景下的 Redis 数据结构

List vs Stream： List 实现简单，但无 Consumer Group、难追溯；生产更推荐 Stream 或 Celery/BullMQ。

6. Python 示例（redis-py）

安装：pip install redis。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

import json
import redis
from datetime import timedelta

r = redis.Redis.from_url("redis://localhost:6379/0", decode_responses=True)

SESSION_TTL = int(timedelta(hours=24).total_seconds())

def session_key(tenant_id: str, thread_id: str) -> str:
    return f"agent:session:{tenant_id}:{thread_id}"

def append_message(tenant_id: str, thread_id: str, role: str, content: str) -> None:
    key = session_key(tenant_id, thread_id)
    raw = r.hget(key, "messages") or "[]"
    messages = json.loads(raw)
    messages.append({"role": role, "content": content})
    # 只保留最近 20 条，控制体积
    messages = messages[-20:]
    pipe = r.pipeline()
    pipe.hset(key, mapping={"messages": json.dumps(messages, ensure_ascii=False)})
    pipe.expire(key, SESSION_TTL)
    pipe.execute()

def enqueue_embedding_job(job_id: str, doc_id: str, payload: dict) -> None:
    r.xadd(
        "agent:jobs:embed",
        {"job_id": job_id, "doc_id": doc_id, "payload": json.dumps(payload)},
        maxlen=10000,  # 近似裁剪，防止 Stream 无限增长
    )

def consume_embed_group(consumer_name: str):
    group = "embed_workers"
    stream = "agent:jobs:embed"
    try:
        r.xgroup_create(stream, group, id="0", mkstream=True)
    except redis.ResponseError as e:
        if "BUSYGROUP" not in str(e):
            raise
    while True:
        resp = r.xreadgroup(group, consumer_name, {stream: ">"}, count=1, block=5000)
        if not resp:
            continue
        for _stream, entries in resp:
            for msg_id, fields in entries:
                # ... 执行嵌入，写向量库 ...
                r.xack(stream, group, msg_id)

Celery 侧只需将 broker 设为 redis://...，任务函数内复用上述 append_message 更新会话进度即可。

7. 生产环境：持久化、集群与 TTL

7.1 持久化

• RDB：定时快照，恢复快，可能丢最近几分钟数据。
• AOF：追加写日志，可配置 everysec，会话与队列数据更安全。

Agent 会话若可重建，可接受适度丢失；任务队列与 Stream 建议开启 AOF，并监控 appendfsync 延迟。

7.2 高可用

• Redis Sentinel：主从自动故障转移，适合中小规模。
• Redis Cluster：数据分片，注意 多 key 事务与 Lua 受 slot 限制；会话 Key 用 hash tag：agent:session:{tenant}:{thread} 保证同 slot。

7.3 TTL 与内存

• 所有会话 Key 必须 EXPIRE，防止僵尸 thread 吃光内存。
• 配置 maxmemory-policy volatile-lru（或 allkeys-lru），并为 Stream 设置 MAXLEN ~。
• 大 payload 不要进 Redis：存 S3/MinIO，Redis 只存指针 s3://bucket/key。

7.4 安全

生产禁用 FLUSHALL 权限；TLS 连接；密码与 ACL 按服务拆分（API 只读写 session 前缀，Worker 只访问 queue 前缀）。

7.5 可观测性

在 Docker 部署 之上，为 Redis 增加指标：used_memory、connected_clients、instantaneous_ops_per_sec、Stream 的 lag（待消费条数）。Agent 侧自定义 metric：session_cache_hit_ratio、queue_wait_seconds、tool_retry_count。告警阈值示例：内存使用率 > 80%、某 Stream lag 连续 5 分钟 > 1000。

8. 小结

Redis 让 Agent 服务具备 可共享的会话热数据、可扩展的异步任务、可协作的轻量事件通道。实践路径：先用 Hash + TTL 管会话窗口 → 将慢 Tool 与嵌入迁到 Celery/Streams → 仅在需要广播时用 Pub/Sub，可靠投递用 Stream 或专业 MQ → 最后补齐持久化、集群与监控（内存、连接数、Stream lag）。完成本篇后，建议继续 Agent 评估与测试，用可重复的评测集验证「队列里的 Agent」是否仍然答得准、走得稳。

系列导航 Series Navigation：

• 上一篇：Docker 与基础 DevOps
• 下一篇：Agent 评估与测试

Claude Code 全面介绍 / A Comprehensive Introduction to Claude Code

Anthropic 推出的智能体编程工具：架构、应用与权衡
Anthropic’s agentic coding tool: architecture, applications, and trade-offs

一、概述 / Overview

中文： Claude Code 是 Anthropic 于 2025 年发布的智能体编程工具（Agentic Coding Tool）。它并非新的 AI 模型，而是围绕 Claude 系列模型（Opus、Sonnet、Haiku）构建的编排层（Orchestration Layer），使 AI 能够自主读取代码库、编辑文件、执行 Shell 命令、调用外部服务，并在多步任务中持续迭代，直到目标完成。

与传统代码补全工具（如 GitHub Copilot）或 IDE 内嵌助手（如 Cursor）不同，Claude Code 的核心范式是从「建议」转向「自主执行」：用户用自然语言描述目标，系统负责规划、执行、验证与修正。

English: Claude Code is an agentic coding tool released by Anthropic in 2025. It is not a new AI model, but an orchestration layer built around the Claude model family (Opus, Sonnet, Haiku), enabling AI to autonomously read codebases, edit files, run shell commands, call external services, and iterate across multi-step tasks until the goal is achieved.

Unlike traditional code completion tools (e.g., GitHub Copilot) or IDE-embedded assistants (e.g., Cursor), Claude Code’s core paradigm shifts from “suggestion” to “autonomous execution”: users describe goals in natural language, and the system handles planning, execution, verification, and correction.

可用形态 / Available Interfaces:

二、架构设计 / Architecture Design

2.1 核心哲学：简单循环 + 厚重基础设施 / Core Philosophy: Simple Loop + Heavy Infrastructure

中文： Claude Code 的架构有一个反直觉的特点：据学术研究分析，其代码库中仅约 1.6% 是 AI 决策逻辑，其余 98.4% 是确定性的基础设施——权限门控、上下文管理、工具路由、恢复逻辑等。核心智能体循环极其简单：

1
2
3
4
5

while (model_requests_tool) {
    call_model();
    dispatch_tools();
    check_stop_conditions();
}

真正的工程复杂度在于围绕循环构建的系统（Harness），而非循环本身。

English: Claude Code’s architecture has a counterintuitive characteristic: according to academic source analysis, only about 1.6% of its codebase is AI decision logic; the remaining 98.4% is deterministic infrastructure—permission gates, context management, tool routing, recovery logic, and more. The core agent loop is remarkably simple:

1
2
3
4
5

while (model_requests_tool) {
    call_model();
    dispatch_tools();
    check_stop_conditions();
}

The real engineering complexity lies in the harness built around the loop, not in the loop itself.

2.2 系统分层 / System Layers

中文： 系统可分解为 7 个组件，跨越 5 个架构层：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

┌─────────────────────────────────────────────────────────┐
│  用户层 / User Layer                                     │
│  开发者 / Developer                                      │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  接口层 / Interface Layer                                │
│  Terminal CLI │ IDE Extension │ Desktop App │ Web/CI-CD │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  智能体层 / Agent Layer                                   │
│  Agent Loop (while-tool_call)                           │
│  Permission System (7 modes + ML classifier)          │
│  Context Management (5-layer compaction)                │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  工具层 / Tool Layer                                      │
│  Built-in Tools │ Subagents │ MCP │ Skills & Plugins     │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│  持久化层 / Persistence Layer                             │
│  Session Storage (JSONL) │ CLAUDE.md │ File-based Memory│
└─────────────────────────────────────────────────────────┘

English: The system decomposes into 7 components across 5 architectural layers: User → Interfaces → Agent Loop → Permission System → Tools → State & Persistence → Execution Environment.

2.3 九步回合流水线 / Nine-Step Turn Pipeline

中文： 每一轮交互遵循严格的九步流水线：

English: Each interaction round follows a strict nine-step pipeline: Settings Resolution → State Initialization → Context Assembly → Context Compaction → Model Call → Tool Dispatch → Permission Gate → Tool Execution → Stop Condition Check.

2.4 内置工具集 / Built-in Tool Set

中文： Claude Code 的核心工具集精简而强大，遵循「搜索，不索引（Search, Don’t Index）」哲学——使用 ripgrep 而非向量数据库进行代码搜索，以降低运维复杂度与安全风险。

English: Claude Code’s core toolset is lean yet powerful, following a “Search, Don’t Index” philosophy—using ripgrep rather than vector databases for code search, reducing operational complexity and security risks. The eight core tools are listed in the table above.

2.5 权限系统 / Permission System

中文： 权限系统是 Claude Code 安全架构的核心，采用**拒绝优先（Deny-First）**规则引擎，提供 7 种权限模式，形成渐进的信任光谱：

1

plan → default → acceptEdits → auto → dontAsk → bypassPermissions

• plan：仅规划，不执行任何修改操作
• default：每次危险操作需用户确认
• acceptEdits：自动接受文件编辑，其他操作需确认
• auto：ML 分类器（yoloClassifier）自动筛选低风险操作
• dontAsk：不再询问，自动执行（高风险）
• bypassPermissions：跳过所有权限检查（仅限受信环境）

据 Anthropic 内部数据，用户对 Claude 请求的批准率高达 93%，系统设计大量代码来处理剩余 7% 的边缘情况。

English: The permission system is the core of Claude Code’s security architecture, using a deny-first rule engine with 7 permission modes forming a graduated trust spectrum (see above). According to Anthropic internal data, users approve Claude’s requests 93% of the time; the system invests significant engineering in handling the remaining 7% edge cases.

2.6 上下文管理 / Context Management

中文： Claude Code 在固定上下文窗口（约 200K tokens，因模型而异）内运行，采用五层压缩管道主动管理上下文：

1. 预算削减 / Budget Reduction — 按优先级裁剪低价值内容
2. Snip — 截断过长的工具输出
3. Microcompact — 压缩重复或冗余信息
4. Context Collapse — 合并相似上下文片段
5. Auto-Compact — LLM 驱动的智能摘要

CLAUDE.md 层级体系（4 级）提供持久化项目上下文：

1
2
3
4

~/.claude/CLAUDE.md          → 全局用户偏好
./CLAUDE.md                  → 项目根目录规则
./src/CLAUDE.md              → 子目录特定规则
./src/module/CLAUDE.md       → 模块级规则

记忆系统采用纯文件存储（Markdown 文件），无向量数据库，完全可检查、可编辑、可版本控制。

English: Claude Code operates within a fixed context window (~200K tokens, varying by model), using a five-layer compaction pipeline for proactive context management (listed above). The CLAUDE.md hierarchy (4 levels) provides persistent project context, and the memory system uses file-based storage (Markdown files) with no vector database—fully inspectable, editable, and version-controllable.

2.7 扩展机制 / Extension Mechanisms

中文： Claude Code 提供四种扩展机制，形成可定制的智能体平台：

子智能体（Subagents） 通过 Task 工具生成，在隔离的上下文窗口中运行，仅向父智能体返回摘要，防止上下文爆炸。更新的 Agent Teams 功能支持多会话协作，共享任务与点对点通信。

English: Claude Code provides four extension mechanisms forming a customizable agent platform (see table). Subagents spawn via the Task tool, running in isolated context windows and returning only summaries to the parent. The newer Agent Teams feature supports multi-session collaboration with shared tasks and peer-to-peer messaging.

2.8 会话存储 / Session Storage

中文： 所有交互以 append-only JSONL 格式持久化，支持确定性审计与回放。子智能体隔离可通过 Git Worktrees 实现，确保并行智能体互不干扰。

English: All interactions are persisted in append-only JSONL format, enabling deterministic auditing and replay. Subagent isolation can be achieved via Git Worktrees, ensuring parallel agents do not interfere with each other.

三、应用场景 / Application Scenarios

3.1 复杂多文件重构 / Complex Multi-File Refactoring

中文： 当需要在数十个文件间协调修改时（如认证层重构、API 版本迁移），Claude Code 可自主规划变更顺序、逐文件执行、运行测试验证，并在失败时自动修正。

English: When coordinated changes across dozens of files are needed (e.g., auth layer refactoring, API version migration), Claude Code autonomously plans change order, executes file by file, runs tests for verification, and auto-corrects on failure.

3.2 测试驱动开发循环 / Test-Driven Development Loop

中文： Claude Code 可编写测试 → 运行测试 → 读取失败输出 → 修复实现 → 再次运行，形成完整的 TDD 闭环，无需人工介入每一步。

English: Claude Code can write tests → run tests → read failure output → fix implementation → run again, forming a complete TDD loop without human intervention at each step.

3.3 Git 工作流自动化 / Git Workflow Automation

中文： 从读取 Issue、编写代码、运行测试到提交 PR，Claude Code 可端到端处理整个开发流程，与 GitHub、GitLab 深度集成。

English: From reading issues, writing code, and running tests to submitting PRs, Claude Code can handle the entire development workflow end-to-end, with deep GitHub and GitLab integration.

3.4 代码库探索与文档 / Codebase Exploration & Documentation

中文： 利用 agentic search（基于 grep，非 RAG），Claude Code 可在数秒内映射并解释整个代码库结构，生成架构文档或 onboarding 指南。

English: Using agentic search (grep-based, not RAG), Claude Code can map and explain entire codebase structure in seconds, generating architecture docs or onboarding guides.

3.5 CI/CD 与自动化 / CI/CD & Automation

中文： 通过 GitHub Actions 集成或 SDK，Claude Code 可在 CI 流水线中自动审查 PR、修复 lint 错误、更新依赖，实现「无人值守」的代码维护。

English: Via GitHub Actions integration or SDK, Claude Code can automatically review PRs, fix lint errors, and update dependencies in CI pipelines, enabling “unattended” code maintenance.

3.6 团队知识沉淀 / Team Knowledge Capture

中文： 通过 CLAUDE.md、Skills 和 Hooks，团队可将编码规范、审查流程、部署检查清单固化为可复用的智能体能力，新成员快速获得团队最佳实践。

English: Through CLAUDE.md, Skills, and Hooks, teams can codify coding standards, review processes, and deployment checklists into reusable agent capabilities, giving new members rapid access to team best practices.

四、优缺点分析 / Pros and Cons Analysis

4.1 优点 / Advantages

4.2 缺点与局限 / Disadvantages & Limitations

五、与其他工具的定位对比 / Positioning vs. Other Tools

中文：

Claude Code 与 Cursor 等 IDE 工具并非竞争关系，而是覆盖同一工作流的不同环节：

English:

Claude Code and IDE tools like Cursor are not competitors—they cover different parts of the same workflow (see table above). The key insight: Cursor is a force multiplier on your keystrokes; Claude Code is a delegate for whole jobs.

六、设计启示 / Design Insights for Agent Builders

中文： Claude Code 的架构为构建 AI 智能体系统提供了重要启示：

1. 模型是小部分，基础设施是大头 — 投资应集中在 Harness（权限、上下文、工具路由）而非模型调用本身
2. 简单循环足够 — 无需 DAG、分类器或 RAG；让模型决定一切
3. 搜索优于索引 — grep 比向量搜索更简单、更安全、在 agentic 场景下同样有效
4. 权限是产品特性，不是障碍 — 93% 批准率说明用户信任自主性，但 7% 的边缘情况值得大量工程投入
5. 文件即记忆 — 可检查、可编辑、可版本控制的 Markdown 优于黑盒向量数据库
6. 扩展性决定平台价值 — MCP、Skills、Hooks、Plugins 四层机制使 Claude Code 从工具演变为平台

English: Claude Code’s architecture offers key insights for building AI agent systems (listed above). As frontier models converge, harness + model co-optimization is the differentiator.

七、总结 / Summary

中文： Claude Code 代表了 AI 辅助编程从「自动补全」到「自主智能体」的范式转变。其架构哲学——简单循环 + 厚重基础设施——证明了一个反直觉的事实：构建优秀智能体系统的关键，不在于更复杂的 AI 逻辑，而在于更可靠的确定性系统。对于需要委托复杂、多步、跨文件开发任务的团队，Claude Code 是目前最成熟的终端原生智能体编程解决方案。

English: Claude Code represents the paradigm shift in AI-assisted programming from “autocomplete” to “autonomous agent.” Its architectural philosophy—simple loop + heavy infrastructure—proves a counterintuitive truth: the key to building excellent agent systems lies not in more complex AI logic, but in more reliable deterministic systems. For teams needing to delegate complex, multi-step, cross-file development tasks, Claude Code is currently the most mature terminal-native agentic coding solution.

参考资料 / References

• Claude Code Official Documentation
• How Claude Code Works (Official)
• Extend Claude Code - Features Overview
• Dive into Claude Code (arXiv Academic Paper)
• VILA-Lab/Dive-into-Claude-Code (GitHub)

English Title: Deploying Agent Apps — Docker Containerization & Essential DevOps

完成 API 集成（REST/OAuth/Webhook） 后，你的 Agent 往往已经能调用外部系统、接收 Webhook、对接企业 SSO。但在笔记本上 uvicorn 或 node index.js 跑通的代码，并不等于能在团队里稳定交付。依赖版本漂移、环境变量散落、向量库与 Redis 地址写死在代码里——这些都会在第一次「给别人部署」时集中爆发。容器化把 运行时、依赖与配置 打成可复现单元；再配合基础 CI/CD 与可观测性，Agent 服务才能从 Demo 走向可运维的生产形态。本文聚焦 Agent 场景下最实用的 Docker 与 DevOps 实践，不展开 K8s 全家桶，却足以支撑多数中小团队的上线路径。

1. 为什么 Agent 应用需要容器化？

Agent 服务与普通 Web API 相比，有几个额外的「环境敏感点」：

容器不是银弹：它解决的是 「在我机器上能跑」 与 交付可重复性；并发扩缩、多租户隔离仍要配合编排平台或 PaaS。但对 Agent 团队而言，先做到「任何人 docker compose up 能复现全栈」，再谈 K8s，性价比最高。许多团队在 PoC 阶段就把 Celery Worker、向量索引任务与 API 塞进同一进程，上线前才拆分——容器化恰好强迫你在早期厘清 进程边界，为后续水平扩展留出接口。

2. Dockerfile 最佳实践（Python / Node Agent 服务）

无论 Python（FastAPI + LangGraph）还是 Node（Express + OpenAI Agents SDK），原则相通：

1. 多阶段构建（multi-stage）：构建阶段装编译工具与 dev 依赖；运行阶段只保留产物，缩小攻击面与镜像体积。
2. 非 root 用户：USER app，避免容器内进程以 root 运行。
3. 固定基础镜像标签：用 python:3.12-slim-bookworm 而非 latest，便于安全补丁回溯。
4. 层缓存友好：先 COPY requirements.txt / package-lock.json 再 install，代码变更不触发全量重装。
5. 健康检查：HEALTHCHECK 探测 /health，编排器可自动重启僵死实例。
6. 单进程前台：容器主进程应是 API 或 Worker，不要用 shell 脚本后台 & 多个服务——一个容器一个职责。

Python 示例要点： 用 uv 或 pip install --no-cache-dir；若依赖 sentence-transformers 等大包，考虑单独基础镜像层。启动命令显式指定 worker 数：uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2。

Node 示例要点： npm ci --omit=dev 保证 lockfile 一致；生产用 node dist/index.js 而非 ts-node。Agent 若大量调用外部 API，注意容器内 DNS 与 HTTP 代理环境变量（HTTP_PROXY）需在运行时配置，不要 bake 进镜像。

若镜像体积仍是瓶颈，可进一步用 distroless 或 Alpine 基础镜像，但需验证 glibc 与部分 Python 轮子（如 numpy）的兼容性。构建时加上 .dockerignore 排除 __pycache__、.git、tests/，能显著减少构建上下文上传时间——这在 monorepo 里尤其明显。

3. docker-compose 本地全栈（Agent + Redis + 向量库）

本地开发的目标是：一条命令 启动 Agent API、会话缓存与向量检索，且端口与生产拓扑接近。

典型服务划分：

compose 中通过 服务名 互联：REDIS_URL=redis://redis:6379/0、QDRANT_URL=http://qdrant:6333。切勿在代码里写 localhost——在容器网络内应指向服务名。开发时可将源码目录 volume 挂载 进容器实现热重载，但生产镜像不应依赖挂载。

数据持久化：为 Redis、Qdrant 配置 named volume，避免 docker compose down -v 误删后丢失索引。向量库首次启动较慢，compose 可用 depends_on + 应用内重试连接，而非假设「启动顺序即就绪」。

开发阶段可在 docker-compose.override.yml（不提交 Git）里挂载源码、开启 debug 端口；生产 compose 则去掉 volume 挂载，仅保留数据卷。这样同一套文件服务两条路径，减少「开发能跑、上线配置不一致」的割裂感。

4. 基础 CI/CD：GitHub Actions 构建与部署

最小可用流水线分三段：测试 → 构建镜像 → 部署。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# .github/workflows/deploy-agent.yml（示意）
name: Deploy Agent API
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt && pytest -q
  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}/agent-api:${{ github.sha }}
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: |
          # SSH 到 VM 或触发平台 API：拉取新 tag 并 rolling restart
          ssh deploy@host "docker pull ghcr.io/org/agent-api:${{ github.sha }} && docker compose up -d agent-api"

Agent 特有注意点： CI 中 mock LLM 与外部 API，避免每次 push 消耗真实 token；集成测试用 recorded fixtures。镜像 tag 用 Git SHA 而非 latest，便于回滚。若部署到云托管（Fly.io、Railway、ECS），将 deploy 步骤换成对应 CLI 即可，构建层不变。

建议在 main 分支保护规则中要求 PR 通过 test job 才能合并；对 Agent 项目，可额外加一步 Dockerfile lint（如 hadolint）与 镜像漏洞扫描（Trivy），把安全问题左移到合并前。部署策略上，单 VM 用 docker compose pull && up -d 足够；多实例时引入负载均衡与健康检查，再考虑蓝绿或滚动更新。

5. 日志与监控基础

Agent 排障常问三类问题：请求是否到达？LLM 调用是否超时？检索是否命中？ 日志应结构化（JSON），字段建议包含：trace_id、user_id、model、latency_ms、prompt_tokens、completion_tokens、tool_name、retrieval_hit_count。

避免在日志中打印完整 Prompt 或 API Key；必要时对 PII 脱敏。本地开发可用 docker compose logs -f agent-api；生产将日志导向 Loki / CloudWatch / ELK 之一即可，不必一开始上全套 APM。

对 Agent 而言，建议在日志或指标中区分 用户可见延迟（首 token 时间 TTFT）与 端到端任务完成时间（含多轮 Tool 调用）。前者关系体验，后者关系计费与 SLA。当 P99 飙升时，先看是 LLM 供应商慢、向量检索慢，还是 Redis 连接池耗尽——结构化字段让这类归因不必靠猜。

6. 环境变量与密钥管理

Agent 服务典型环境变量：

原则： 密钥只通过环境注入或 Secret 挂载（Docker secret、K8s Secret、GitHub Encrypted Secrets），绝不写入 Dockerfile、docker-compose.yml 默认值或 Git 仓库。.env 仅用于本地，且应列入 .gitignore。生产与开发使用不同 key 与不同 Redis DB index，防止测试流量污染生产记忆。

轮换密钥时：先在新 Secret 中写入新 key → 滚动重启实例 → 吊销旧 key。compose 本地可用 env_file: .env；CI 用 secrets: OPENAI_API_KEY 映射为环境变量。

7. 示例：Dockerfile 与 docker-compose.yml

Dockerfile（Python Agent API）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

FROM python:3.12-slim-bookworm AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -t /deps

FROM python:3.12-slim-bookworm
WORKDIR /app
RUN useradd --create-home app
COPY --from=builder /deps /usr/local/lib/python3.12/site-packages
COPY app ./app
USER app
ENV PYTHONUNBUFFERED=1
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

services:
  agent-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      REDIS_URL: redis://redis:6379/0
      QDRANT_URL: http://qdrant:6333
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    depends_on:
      - redis
      - qdrant
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  qdrant:
    image: qdrant/qdrant:v1.12.0
    volumes:
      - qdrant_data:/qdrant/storage
    ports:
      - "6333:6333"

volumes:
  redis_data:
  qdrant_data:

Node 版可将 builder 阶段改为 npm ci && npm run build，运行阶段使用 node:20-alpine，其余拓扑相同。需要后台嵌入任务时，增加 worker 服务：command: ["python", "-m", "app.worker"]，与 API 共享环境变量与网络。

8. 小结

容器化解决的是 Agent 交付的 一致性；compose 解决的是 本地全栈复现；CI/CD 解决的是 可重复发布与回滚；日志与密钥规范解决的是 出事能查、密钥不泄。建议路径：先用 compose 跑通 Agent + Redis + Qdrant → 写好 Dockerfile 与健康检查 → 接上 GitHub Actions 构建镜像 → 再按需迁移到托管 K8s 或 PaaS。下一篇将深入 Redis 与消息队列，把会话缓存、任务分发与限流从「能连上」做到「扛得住并发」。

系列导航 Series Navigation：

• 上一篇：API 集成（REST/OAuth/Webhook）
• 下一篇：Redis 与消息队列