Hermes Company OS — 集成架构设计文档

Claude/Codex 作为执行引擎 + Orchestrator 作为调度中枢 + tmux 作为运行容器

版本：V1.5 | 日期：2026-04-26

一、核心定位

1.1 一句话描述

一个以 Claude/Codex 为执行引擎的 多 Agent 自动调度系统，实现"公司自己运转"。

1.2 四层架构

┌─────────────────────────────────────────────────────────────┐
│  管理层：Hermes Company OS（我们的）                           │
│  ├── 管 Agent 身份（profile）                                 │
│  ├── 管任务票（tasks/todo → doing → review → done）           │
│  ├── 管公司规则（company/）                                    │
│  ├── 管记忆归档（memory/）                                     │
│  └── 管交付物验收（outbox/）                                   │
├─────────────────────────────────────────────────────────────┤
│  调度层：Orchestrator（我们的）                                │
│  ├── 扫描 todo 任务                                           │
│  ├── 匹配 Agent 能力                                          │
│  ├── 锁定任务 → 移动到 doing                                   │
│  ├── 管理 tmux session/pane                                   │
│  ├── 监控执行状态（心跳、超时、完成信号）                          │
│  └── 回收结果 → 移动到 review                                  │
├─────────────────────────────────────────────────────────────┤
│  容器层：tmux                                                  │
│  ├── 多 Agent 并行运行                                         │
│  ├── 实时可观察（tmux attach）                                  │
│  └── 持久化运行（断线不中断）                                     │
├─────────────────────────────────────────────────────────────┤
│  执行层：Claude Code / Codex（最强 LLM）                        │
│  ├── 每个 Agent = 一个独立的 Claude/Codex 会话                   │
│  ├── 自带文件读写、终端执行、网络搜索等工具                        │
│  ├── YOLO 模式无人值守执行                                     │
│  └── 通过 prompt 注入公司规则、任务上下文、输出规范                 │
└─────────────────────────────────────────────────────────────┘

1.3 与 Nous Hermes 的关系

Nous Hermes Agent（118k stars）是一个优秀的参考系统。我们不直接使用它作为执行引擎，但借鉴其核心设计理念：

核心差异：Nous Hermes 是单体 Agent 应用，我们是多 Agent 调度系统。两者解决不同层面的问题。

二、为什么执行层用 Claude/Codex

2.1 相比 Nous Hermes Agent 的优势

2.2 我们的弥补策略

Nous Hermes 有而我们缺少的能力，通过公司系统层面弥补：

2.3 执行引擎选择

三、集成架构详解

3.1 目录结构

hermes-company/
├── company/                    # 公司制度（我们的）
│   ├── AGENT_WORK_RULES.md     # Agent 执行规范
│   ├── SECURITY_RULES.md       # 安全约束
│   ├── COMPANY.md              # 公司愿景与规则
│   └── skills/                 # 共享技能库（借鉴 Nous 理念）
│       └── {skill_name}.md     # 可复用技能文档
│
├── orchestrator/               # 调度器（我们的）
│   ├── main.py                 # 主循环
│   ├── tmux_manager.py         # tmux 会话管理
│   ├── task_scanner.py         # 任务扫描
│   ├── task_assigner.py        # 任务分配与锁定
│   ├── agent_launcher.py       # Agent 启动（启动 Claude/Codex）
│   ├── monitor.py              # 状态监控
│   ├── memory_injector.py      # 记忆注入（搜索相关经验并注入）
│   └── config.py               # 配置
│
├── agents/                     # Agent 配置
│   └── {agent_name}/
│       ├── profile.json        # 公司定义的身份
│       │   {
│       │     "name": "laohuang",
│       │     "role": "fullstack_engineer",
│       │     "engine": "claude-code",
│       │     "skills": ["nextjs", "api_design", "db_modeling"]
│       │   }
│       ├── profile.md          # 详细角色描述（注入给 Claude 的 SOUL）
│       └── runtime.json        # 运行时状态（Orchestrator 管理）
│           {
│             "agent": "laohuang",
│             "engine": "claude-code",
│             "container": "tmux",
│             "tmux_session": "hermes",
│             "tmux_window": "agent_laohuang",
│             "status": "idle",
│             "current_task": null,
│             "last_heartbeat": "2026-04-26 13:30:00"
│           }
│
├── tasks/                      # 任务系统（我们的）
│   ├── todo/
│   ├── doing/
│   ├── blocked/
│   ├── review/
│   └── done/
│
├── memory/                     # 公司级记忆（借鉴 Nous 理念）
│   └── {agent_name}/
│       ├── experiences/        # 任务经验归档
│       │   └── {task_id}.md    # 任务执行经验
│       ├── patterns/           # 发现的模式和最佳实践
│       └── lessons/            # 教训和踩坑记录
│
├── logs/                       # 公司级日志
│   └── {agent_name}/
│       └── YYYY-MM-DD.md       # 每日工作日志
│
├── outbox/                     # 交付物
│   └── {agent_name}/
│       └── {task_id}/
│           ├── summary.md
│           ├── result files
│           └── DONE
│
└── runners/                    # 启动模板
    ├── claude_runner.md        # Claude Code 执行 prompt 模板
    └── codex_runner.md         # Codex 执行 prompt 模板

3.2 每个 Agent 的完整栈

tmux pane: agent_laohuang
    │
    ├── 运行命令: claude code --dangerously-skip-permissions
    │   （或 codex --approval-mode=auto）
    │
    ├── Claude/Codex 能力:
    │   ├── 文件读写（read_file, write_file, patch）
    │   ├── 终端执行（run commands）
    │   ├── 网络搜索（web search）
    │   ├── 浏览器自动化（browser tools）
    │   └── 代码理解与生成
    │
    └── 公司注入上下文（通过 prompt）:
        ├── Agent 身份（agents/laohuang/profile.md）
        ├── 任务文件（tasks/doing/TASK-xxx.md）
        ├── 公司规则（company/AGENT_WORK_RULES.md）
        ├── 相关记忆（memory/laohuang/experiences/ 中相关内容）
        ├── 相关技能（company/skills/ 中相关技能文档）
        └── 输出规范（outbox 格式要求）

3.3 数据流

任务创建 → 执行 → 回收

1. 人类创建任务
   hermes-company CLI → tasks/todo/TASK-001.md

2. Orchestrator 扫描
   读取 tasks/todo/ + agents/*/profile.json + agents/*/runtime.json
   匹配：task.owner = laohuang && laohuang.status = idle

3. Orchestrator 搜索相关记忆
   搜索 memory/laohuang/ 中与任务相关的经验
   准备注入上下文

4. Orchestrator 锁定任务
   任务文件写入 runtime.locked_by = "orchestrator"
   移动：tasks/todo → tasks/doing

5. Orchestrator 启动/复用 tmux pane
   tmux new-window -t hermes -n agent_laohuang
   （如果 pane 已存在，复用）

6. Orchestrator 注入任务到 Claude/Codex
   通过 tmux send-keys 发送完整 prompt：
   
   ┌─────────────────────────────────────────────┐
   │ 你是 Hermes 公司中的 Agent：laohuang          │
   │ 你的角色：全栈工程师                           │
   │                                             │
   │ ## 当前任务                                   │
   │ 文件：tasks/doing/TASK-001.md                 │
   │ 请读取并执行该任务。                            │
   │                                             │
   │ ## 相关经验（来自历史任务）                     │
   │ - 上次做类似任务时，使用了 Next.js App Router  │
   │ - 注意数据库迁移要先于代码部署                  │
   │                                             │
   │ ## 公司规则                                   │
   │ - 遵守 company/AGENT_WORK_RULES.md            │
   │ - 完成后写入 outbox/laohuang/TASK-001/        │
   │ - 必须创建 summary.md 和 DONE 标记             │
   │                                             │
   │ ## 可用技能                                   │
   │ - nextjs_deployment（见 company/skills/）      │
   │ - api_design_patterns                        │
   └─────────────────────────────────────────────┘

7. Claude/Codex 执行任务
   ├── 读取任务文件
   ├── 使用自带工具执行（文件、终端、搜索、浏览器）
   ├── 参考注入的经验和技能
   ├── 记录工作过程
   └── 生成结果

8. Claude/Codex 提交结果
   ├── 写入 outbox/laohuang/TASK-001/summary.md
   ├── 写入 outbox/laohuang/TASK-001/DONE 标记
   └── 写入 logs/laohuang/YYYY-MM-DD.md

9. Orchestrator 检测完成
   轮询检测 DONE 文件
   移动：tasks/doing → tasks/review
   更新：runtime.json status = idle, current_task = null

10. Orchestrator 归档经验（学习循环）
    读取 outbox/laohuang/TASK-001/summary.md
    提取关键经验 → memory/laohuang/experiences/TASK-001.md
    如有可复用模式 → company/skills/ 新增或更新技能

11. 人类验收
    查看 outbox/laohuang/TASK-001/summary.md
    验收通过 → tasks/review → tasks/done
    验收不通过 → tasks/review → tasks/doing（重新执行，附带反馈）

四、Prompt 注入设计

4.1 Agent 启动 Prompt 模板

# runners/claude_runner.md
 
你是 Hermes 公司中的 Agent：{{agent_name}}
 
## 身份
{{agent_profile}}
 
## 当前任务
请读取并执行：tasks/doing/{{task_id}}.md
 
## 相关经验
{{injected_memories}}
 
## 公司规则
严格遵守 company/AGENT_WORK_RULES.md 中的所有规范。
 
## 输出要求
1. 工作日志写入：logs/{{agent_name}}/{{today}}.md
2. 交付物写入：outbox/{{agent_name}}/{{task_id}}/
3. 完成后必须创建：outbox/{{agent_name}}/{{task_id}}/DONE
4. 完成后必须创建：outbox/{{agent_name}}/{{task_id}}/summary.md
 
## summary.md 格式
- 任务 ID 和标题
- 执行步骤摘要
- 产出物清单
- 遗留问题（如有）
- 建议下一步
 
## 禁止行为
- 删除 tasks/、agents/、orchestrator/ 目录
- 修改 company/ 下的任何文件
- 执行 rm -rf 或类似高危命令
- 修改其他 Agent 的文件
 
现在开始执行任务。

4.2 记忆注入逻辑

# orchestrator/memory_injector.py
 
class MemoryInjector:
    def inject(self, agent_name: str, task: Task) -> str:
        """搜索并注入相关记忆"""
        
        memory_dir = f"memory/{agent_name}"
        memories = []
        
        # 1. 搜索相关经验
        for exp_file in glob(f"{memory_dir}/experiences/*.md"):
            content = read_file(exp_file)
            if self.is_relevant(content, task):
                memories.append(f"- {exp_file}: {summarize(content)}")
        
        # 2. 搜索相关技能
        for skill_file in glob("company/skills/*.md"):
            content = read_file(skill_file)
            if self.is_relevant(content, task):
                memories.append(f"- 技能：{skill_file}")
        
        # 3. 搜索教训
        for lesson_file in glob(f"{memory_dir}/lessons/*.md"):
            content = read_file(lesson_file)
            if self.is_relevant(content, task):
                memories.append(f"- 教训：{summarize(content)}")
        
        return "\n".join(memories) if memories else "（暂无相关经验）"
    
    def is_relevant(self, content: str, task: Task) -> bool:
        """简单关键词匹配，后续可升级为向量搜索"""
        task_keywords = extract_keywords(task.title + task.description)
        return any(kw in content for kw in task_keywords)

五、Orchestrator 核心逻辑

5.1 主循环

# orchestrator/main.py
 
class Orchestrator:
    def run(self):
        while True:
            # 1. 扫描待分配任务
            todos = self.scan_todo_tasks()
            
            # 2. 扫描可用 Agent
            idle_agents = self.get_idle_agents()
            
            # 3. 匹配任务与 Agent
            assignments = self.match_tasks_to_agents(todos, idle_agents)
            
            # 4. 执行分配
            for task, agent in assignments:
                self.assign_task(task, agent)
                self.launch_or_resume_agent(agent, task)
            
            # 5. 监控执行中的任务
            self.monitor_doing_tasks()
            
            # 6. 回收完成的任务
            self.collect_completed_tasks()
            
            # 7. 归档经验（学习循环）
            self.archive_experiences()
            
            # 8. 处理超时和失败
            self.handle_timeouts_and_failures()
            
            # 9. 生成状态报告
            self.generate_status_report()
            
            # 10. 等待下一轮
            sleep(self.config.poll_interval)  # 默认 5 秒

5.2 Agent 启动逻辑

def launch_agent(self, agent_name: str, task: Task):
    """启动或复用 Agent 的 tmux pane"""
    
    # 1. 确保 tmux session 存在
    if not self.tmux.session_exists("hermes"):
        self.tmux.new_session("hermes")
    
    # 2. 检查 pane 是否存在
    pane_name = f"agent_{agent_name}"
    if not self.tmux.window_exists("hermes", pane_name):
        self.tmux.new_window("hermes", pane_name)
        
        # 启动 Claude Code
        cmd = f"claude code --dangerously-skip-permissions"
        self.tmux.send_keys("hermes", pane_name, cmd)
        
        # 等待 Claude 启动
        sleep(3)
    
    # 3. 构建注入 prompt
    prompt = self.build_injection_prompt(agent_name, task)
    
    # 4. 发送任务
    self.tmux.send_keys("hermes", pane_name, prompt)
    
    # 5. 更新运行时状态
    self.update_runtime(agent_name, status="busy", current_task=task.id)

5.3 任务注入方式

推荐方案：tmux send-keys

• Claude 在 YOLO 模式下会等待用户输入
• Orchestrator 通过 send-keys 发送任务 prompt
• Claude 接收后自动开始执行

5.4 完成信号检测

def check_task_completion(self, agent_name: str, task_id: str):
    """检测任务是否完成"""
    
    outbox_dir = f"outbox/{agent_name}/{task_id}"
    
    # 方案 1：DONE 标记文件（最快）
    if os.path.exists(f"{outbox_dir}/DONE"):
        return "completed"
    
    # 方案 2：summary.md 存在
    if os.path.exists(f"{outbox_dir}/summary.md"):
        return "completed"
    
    # 方案 3：心跳检测
    heartbeat = self.read_heartbeat(agent_name)
    if heartbeat and time.now() - heartbeat < 60:
        return "running"
    
    # 方案 4：超时检测
    task_start = self.get_task_start_time(task_id)
    if time.now() - task_start > self.config.timeout:
        return "timeout"
    
    return "unknown"

六、学习循环实现（公司层面）

6.1 学习循环流程

┌─────────────────────────────────────────────────────┐
│              公司级学习循环                            │
│                                                     │
│  任务完成 → Orchestrator 读取 summary                │
│                    ↓                                │
│          提取关键经验 → memory/experiences/           │
│                    ↓                                │
│          识别可复用模式 → company/skills/             │
│                    ↓                                │
│          记录踩坑教训 → memory/lessons/               │
│                    ↓                                │
│  下次任务 → MemoryInjector 搜索并注入相关记忆          │
│                    ↓                                │
│          Agent 执行时参考历史经验 → 更强               │
└─────────────────────────────────────────────────────┘

6.2 经验归档示例

# memory/laohuang/experiences/TASK-001.md
 
## 任务
开发知识库商品落地页
 
## 关键决策
- 使用 Next.js App Router 而非 Pages Router
- 数据库迁移使用 Drizzle ORM
- 部署到 Vercel，环境变量通过 Dashboard 配置
 
## 踩坑
- Vercel 构建超时：需要增加 timeout 配置
- 图片优化：使用 next/image 而非原生 img
 
## 可复用模式
- 落地页模板结构（见 company/skills/landing_page_template.md）
- Vercel 部署 checklist
 
## 日期
2026-04-26

6.3 技能共享

# company/skills/landing_page_template.md
 
## 适用场景
需要快速搭建产品落地页时
 
## 技术栈
- Next.js App Router
- Tailwind CSS
- Vercel 部署
 
## 标准结构
/app
  /page.tsx          # 主页面
  /layout.tsx        # 布局
/components
  /Hero.tsx          # 首屏
  /Features.tsx      # 功能介绍
  /Pricing.tsx       # 价格
  /Footer.tsx        # 页脚
 
## 部署 checklist
- [ ] 配置 Vercel 项目
- [ ] 设置环境变量
- [ ] 配置自定义域名
- [ ] 启用 Analytics

七、并发控制

7.1 约束

7.2 任务锁定机制

def lock_task(self, task_path: str, agent_name: str) -> bool:
    """原子锁定任务"""
    
    lock_path = f"{task_path}.lock"
    
    try:
        with open(lock_path, 'w') as f:
            fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB)
            f.write(json.dumps({
                "locked_by": "orchestrator",
                "locked_at": now(),
                "agent": agent_name
            }))
        
        doing_path = task_path.replace("/todo/", "/doing/")
        shutil.move(task_path, doing_path)
        
        return True
        
    except BlockingIOError:
        return False

八、安全与约束

8.1 Claude/Codex 层面的安全

8.2 公司层面的约束

# company/AGENT_WORK_RULES.md
 
## 禁止行为
1. 删除 tasks/、agents/、orchestrator/ 目录
2. 修改 company/ 下的任何文件
3. 修改其他 Agent 的目录
4. 执行 rm -rf / 或类似高危命令
5. 无限循环执行（超过 30 分钟自动标记 blocked）
 
## 必须行为
1. 任务完成后必须写入 outbox/{agent}/{task_id}/summary.md
2. 必须创建 outbox/{agent}/{task_id}/DONE 标记
3. 必须记录工作日志到 logs/{agent}/YYYY-MM-DD.md
4. 遇到无法解决的问题必须标记 blocked 并说明原因
 
## 输出格式
summary.md 必须包含：
- 任务 ID 和标题
- 执行步骤摘要
- 产出物清单
- 遗留问题（如有）
- 建议下一步

九、实施路线图

阶段一：基础设施（1-2 天）

阶段二：Orchestrator 核心（3-5 天）

阶段三：端到端验证（1-2 天）

阶段四：增强（后续）

十、验收标准

✅ 必须达到

我只创建任务
    ↓
Orchestrator 自动分配给 Agent
    ↓
Claude/Codex 自动执行（使用工具、参考记忆）
    ↓
outbox 中看到结果 + DONE 标记
    ↓
经验自动归档到 memory/
    ↓
下次类似任务能注入相关历史经验

❌ 不算成功的情况

• 还需要手动启动 Claude
• 还需要手动复制任务给 Agent
• 没有 outbox 输出
• 任务完成后没有经验归档
• 下次任务没有注入历史经验

十一、关键设计决策

十二、风险与缓解

十三、与 Nous Hermes 的对比总结

核心定位差异：

• Nous Hermes = 一个强大的单体 Agent
• 我们的方案 = 多个 Agent 的公司操作系统

十四、参考链接

• Nous Hermes Agent: https://github.com/NousResearch/hermes-agent
• Nous Hermes 文档: https://hermes-agent.nousresearch.com/docs/
• Nous Hermes 架构: https://hermes-agent.nousresearch.com/docs/developer-guide/architecture
• Skills Hub: https://agentskills.io
• 原始 PRD: agent-company.md
• Nous Hermes 分析: docs/nous-hermes-agent-analysis.md

文档生成时间：2026-04-26 版本：V1.5 集成架构设计

五、评估与预期效果

5.1 实现效果（What it achieves）

• Hermes 作为核心执行引擎，结合 Orchestrator 的调度能力，实现多 Agent 并行执行、任务自动分派和产出封装的闭环流程。<br>
• 通过 tmux 容器，在同一主机上可观测地运行多个 Agent 实例，提升吞吐与可见性。<br>
• 任务的输入/输出格式标准化：任务票（tasks/），交付物（outbox/），日志（logs/），记忆与技能按代理/公司维度分区存储，便于追踪与审计。<br>
• 引入公司层面的记忆归档和技能共享机制，降低单点知识依赖，利于后续迭代扩展。<br>
• 提供渐进式集成路径：从半自动任务创建到全自动任务执行，逐步将人机协作推向无人值守闭环。

5.2 潜在问题与风险（What could go wrong）

• 依赖 Claude/Codex 的成本与速率：执行层依然高度依赖外部模型，成本与 API 限制可能成为制约点；需要明确的限额与预算策略
• 安全与权限风险：高危操作的执行需要严格的审批、最小权限及审计日志；若未充分控制，可能造成数据暴露或系统破坏
• 记忆与隐私：本地记忆文件与凭证需加密、妥善管理，避免敏感信息泄露
• 并发与一致性：多 Agent 并行时需强原子性保障，避免重复执行或输出写入冲突
• 调试与运维成本：多 Agent/多 Pane 带来调试复杂性，需要统一日志/追踪与错误回放工具
• 兼容性与扩展性：MCP、插件、外部工具接入点增多，需要接口契约与版本管理
• 恢复与容错：需要明确的灾难恢复策略（日志、快照、输出重放）

5.3 成功标准与度量（How to measure success）

• 自动化完成率：无需人工干预完成的任务比例，初期目标 ≥ 60%，逐步提升
• 交付物完整性：每个任务产生 summary.md、DONE、outbox 条目，且可追溯
• 吞吐与耗时：平均完成时间下降，在高并发场景下保持稳定
• 记忆与技能增长：memory 与 company/skills 的新增/改进体现学习效果
• 安全合规性：无敏感数据泄露，日志可审计，关键操作有记录
• 可靠性：崩溃后能快速恢复运行，最小化人工干预
• 用户体验：仪表板/看板提升可观测性和可控性

5.4 下一步行动（Next steps）

• 扩展安全边界：增强 AGENT_WORK_RULES.md，加入审批、日志、回滚策略
• 提升并发与可靠性：实现更健壮的锁、幂等性、重试与回滚
• 加强记忆与技能能力：引入跨任务记忆检索、向量化记忆草案、技能跨 Agent 复用
• 增强观测性：开发实时看板、任务流/行为流/产出流的可视化面板
• 确定阶段性验收标准和回滚计划，确保逐步交付与回退能力

六、技能包选择与参数化调用（新增能力）

• 单个 Claude/Codex 实例可以自由选择或指定参数使用不同的技能包来开发项目，涵盖如 Superpowers、gsd、ecc、gstack 等组合，提升灵活性与适配性。
• 调用方式（示例）
  • 全局配置方式：在 Agent 配置中增加字段 skills_pack: ["superpower", "gsd"]，执行引擎在调用时自动按需装载对应技能模板。
  • prompt 指定方式：在任务 prompt 内明确声明如 "使用技能包: superpower, gsd"，执行时按该集合加载策略与工具集。
  • API/任务参数方式：任务对象加入字段 skill_pack: ["ecc", "gstack"]，在执行时解析并装载。
• 支持的技能包示例
  • Superpowers：完整的快速设计、计划与执行工作流，强规则约束与可追踪性
  • gsd：研究/计划/实现的综合工作流
  • ecc（Everything Claude Code）：工具集、执行模板、合规检查等
  • gstack：组合化工作流栈，跨工具协同能力
• 注意事项
  • 成本与性能：不同技能包组合会影响模型调用成本与延迟，应结合预算约束进行负载规划
  • 安全性：某些技能包可能赋予更高的写入/执行权限，需要额外的审批与日志
  • 版本与兼容性：技能包版本需要与模型/工具版本保持一致，避免兼容性问题
  • 追踪与审计：切换技能包应产生清晰日志并更新记忆/技能上下文

七、附录：接口与约定

• Hermes Company OS 的数据入口仍然是文件系统为主，结合 Hermes 的走向，未来可逐步引入事件总线和 API 对外暴露。
• 任务、记忆、交付物等路径保持向后兼容性，确保逐步迁移无缝进行。
• 记忆与技能的生命周期需要明确的版本控制和回滚策略，确保系统稳定性。

文档生成时间：2026-04-26 版本：V1.5 集成架构设计