|
|
@@ -0,0 +1,156 @@
|
|
|
+# Hermes Agent:Orchestrator + Kanban+Worker‑Profile 架构手册(最终修正版)
|
|
|
+> 直接供给 **default(默认Profile,就是你的主Orchestrator)** 学习执行
|
|
|
+> 重要前提:
|
|
|
+> 1. **不新建额外协调者Profile;default Profile = 主Orchestrator,同时承担全部对外Channel:企微聊天、人机交互入口、任务编排**;
|
|
|
+> 2. Gateway、企微机器人服务全部挂载在 default Profile;不要新建另外一套orchestrator,之前gateway/企微挂掉就是因为试图把协调职责迁移到新建Profile,造成端口冲突、channel实例冲突;
|
|
|
+> 3. 任务分层:
|
|
|
+> - **项目级专员任务 → 匹配已存在持久Worker‑Profile,走Kanban委派(依赖Worker独立Claude‑Code MCP、独立专家记忆)**
|
|
|
+> - **轻量小任务、日常临时分析、信息收集、快速并行碎活 → 使用 delegate_task sub‑agent**
|
|
|
+> 4. delegate_task工具**保留可用,不做config层面exclude**,依靠业务规则做任务路由区分。
|
|
|
+
|
|
|
+## 一、问题本质与根因
|
|
|
+### 1.1 核心机制
|
|
|
+1. **default Profile**:系统默认Profile,**唯一绑定企微Channel、API‑Server、Gateway对外会话入口**。企微机器人、外部消息通道全部运行在default;**禁止把主协调/对外沟通职责迁移到其他新建Profile**,会造成channel冲突、gateway实例冲突、服务崩溃。
|
|
|
+2. **delegate_task sub‑agent**:进程内临时线程worker,继承default Profile全部工具/MCP;**不能加载其他Worker‑Profile的MCP、SOUL、MEMORY**;任务结束销毁,无持久状态;适合不需要专家独立MCP/记忆的轻量碎任务。
|
|
|
+3. **Worker‑Profile**:磁盘持久专家实例,独立`config.yaml`/`.env`/`SOUL.md`/`MEMORY.md`,每个可绑定独立Claude‑Code MCP;仅由**全局Gateway(由default启动)**通过Kanban唤起;执行时生成独立OS子进程;Worker子进程**不监听任何对外端口,不挂载任何Channel**。
|
|
|
+4. **Kanban**:Hermes唯一原生可以委派任务给已有持久Profile的工具集;异步队列;default作为主Orchestrator创建任务后非阻塞,需要轮询拿结果。
|
|
|
+5. **全局Gateway进程**:由default Profile启动,是整个系统唯一调度中枢;Worker只是fork出来的子进程,不独立启动gateway、不启动企微channel。
|
|
|
+
|
|
|
+### 1.2 历史故障根因清单
|
|
|
+|现象|根因分类|详细根因|
|
|
|
+|---|---|---|
|
|
|
+|Gateway挂掉、企微聊天服务挂掉|配置/架构错误|**尝试新建独立协调者Profile,把对外Channel、gateway迁移到新Profile**;企微channel、gateway实例只能属于default,多实例抢占同一个监听资源,直接崩溃。|
|
|
|
+|本该Kanban的项目专员任务,LLM调用delegate_task跑临时sub‑agent|行为约束缺失|LLM天然偏好同步简单的`delegate_task`;缺少明确「小任务/项目专员任务」判定标准;没有前置`profile_list`匹配校验。|
|
|
|
+|端口大量占用、端口冲突、端口暴涨|配置错误(高频)|Worker‑Profile错误开启 `platforms.api_server.enabled: true`;每个开启api_server的Profile绑定TCP端口,冲突、端口自增。Gateway/API‑Server只允许default开启。|
|
|
|
+|Kanban任务卡在`claimed`僵死、僵尸Worker进程|原生机制短板|Claude‑Code MCP长连接会话卡死;Worker PID存活但内部逻辑卡死;原生PID检测不完全可靠;缺少超时回收;同一Profile并发多任务造成MCP会话状态冲突。|
|
|
|
+|并发拉起过多Worker进程,内存OOM、负载飙升|配置参数不合理|Kanban全局并发、单Profile并发、单tick新建worker未做限制;每个Worker完整初始化Hermes+独立Claude‑Code MCP会话,内存开销高。|
|
|
|
+|default无限轮询Kanban任务,会话卡死|Agent逻辑缺陷|Kanban轮询缺少最大轮询次数、超时阈值;对`failed/stale`状态不识别,不向用户上报异常。|
|
|
|
+|指派不存在Profile名称 → Kanban任务永久pending|运行时错误|`kanban_create`前未调用`profile_list`校验assignee存在;Profile名字拼写错误。|
|
|
|
+|Worker无法调用Claude‑Code MCP|配置错误|Claude‑Code MCP配置写在default而不是对应Worker‑Profile;新建Profile后没有执行`doctor`自检MCP连通性。|
|
|
|
+|项目级专员任务交给delegate_task sub‑agent执行|业务逻辑混淆|sub‑agent只能继承default环境,**无法访问其他Profile的Claude‑Code MCP与专家记忆**;即便模仿专家话术,也不是真实专家实例。|
|
|
|
+
|
|
|
+> 区分:
|
|
|
+> - MCP僵死、异步轮询模型缺陷:原生短板,只能缓解,无法彻底消除;
|
|
|
+> - Gateway/企微崩溃、端口爆炸、错误路由任务、MCP放错位置:完全可规避的架构/配置错误。
|
|
|
+
|
|
|
+## 二、全局硬性规则(写入 default 的 SOUL.md Hard Rules)
|
|
|
+> ⚠️ default = 主Orchestrator,**不新建额外协调Profile**;企微、所有外部Channel全部归属default。
|
|
|
+> ⚠️ delegate_task工具保留可用,不做config exclude,依靠业务规则路由。
|
|
|
+
|
|
|
+### 2.1 架构铁则(最高优先级)
|
|
|
+1. **default Profile 是唯一主协调者,唯一对外通信入口**。企微机器人、API‑Server、Gateway服务只能在default上运行;**禁止创建新Profile充当主协调/对外沟通角色**;禁止在任何Worker‑Profile中启用任何IM channel(企微、discord、telegram)。
|
|
|
+2. Worker‑Profile只做后台专业干活,**不接收用户直接消息,不对外暴露任何channel**,只接收来自default通过Kanban下发的任务。
|
|
|
+
|
|
|
+### 2.2 任务路由判定铁则(先判断任务类型,再选工具)
|
|
|
+1. ✅ **满足任意一条 = 项目级 / 专员任务,必须走 Kanban,委派给对应持久 Worker‑Profile**
|
|
|
+ - 需要该领域专家Profile**独立Claude‑Code MCP能力**(完整项目开发、重构、大规模代码修改)
|
|
|
+ - 需要复用该专家Profile的**持久记忆、历史项目上下文、专属人格SOUL设定**
|
|
|
+ - 属于完整项目交付、长周期任务,任务价值高,需要专家角色沉淀经验
|
|
|
+ - 需要隔离独立环境、独立密钥配置
|
|
|
+ > 前置动作:调用 `profile_list` 获取可用Profile列表,匹配最合适assignee;禁止直接调用delegate_task模拟专家。
|
|
|
+
|
|
|
+2. ✅ **满足下面 = 轻量日常小任务,可以使用 delegate_task sub‑agent**
|
|
|
+ - 短期信息检索、文本摘要、简单分析、并行调研、小片段文本处理
|
|
|
+ - **不需要外部Profile的Claude‑Code MCP,不需要专家持久记忆**
|
|
|
+ - 任务结束不需要保留角色上下文,允许执行完成后销毁
|
|
|
+ > delegate_task生成的sub‑agent只能继承default的工具集,不能访问其他Profile的MCP与记忆。
|
|
|
+
|
|
|
+> ❌禁止行为:
|
|
|
+> - 项目级专员任务,不允许偷懒降级为 delegate_task;
|
|
|
+> - 不允许用 delegate_task 去“模拟”一个已经存在的专家Profile角色绕开Kanban流程;
|
|
|
+> - 禁止把对外企微/channel能力迁移到Worker‑Profile或者新建协调Profile。
|
|
|
+
|
|
|
+### 2.3 default(主Orchestrator)配置约束
|
|
|
+1. config.yaml:**保留 delegate_task 在可用工具集,不要exclude**。
|
|
|
+2. default职责边界
|
|
|
+ - 接收企微/用户消息、需求解析、任务路由判断、Kanban任务生命周期管理、delegate_task调用、结果汇总输出。
|
|
|
+ - default**自身不配置Claude‑Code MCP**;不亲自做项目级编码重构;Claude‑Code全部部署在各个Worker‑Profile内部。
|
|
|
+ - default开启:`platforms.api_server.enabled: true`;企微channel配置写在default;Gateway由default启动:`hermes gateway start`。
|
|
|
+3. Kanban固定调用流程(项目/专员任务)
|
|
|
+ 1)解析用户需求,判定属于项目专员任务;
|
|
|
+ 2)调用 `profile_list`,核对目标assignee Profile真实存在;
|
|
|
+ 3)调用 `kanban_create(assignee="xxx‑expert", body="完整任务目标、上下文、交付标准")`;
|
|
|
+ 4)**带超时与最大轮询次数保护轮询** `kanban_get`;
|
|
|
+ 5)状态分支处理:
|
|
|
+ - `completed`:汇总结果输出给用户;
|
|
|
+ - `failed / stale`:停止等待,向用户明确报告任务失败/超时以及简要原因;**严禁无限轮询**;
|
|
|
+ - `ready / claimed`:未到最大轮询次数继续等待;到达阈值判定任务超时。
|
|
|
+
|
|
|
+### 2.4 Worker‑Profile(所有专家分身,未来新建Profile强制套用)
|
|
|
+> **以后每新增任何Worker‑Profile,必须使用下面config.yaml模板**
|
|
|
+```yaml
|
|
|
+# Worker‑Profile 标准模板(新建profile必须复制)
|
|
|
+platforms:
|
|
|
+ api_server:
|
|
|
+ enabled: false # ✅核心:Worker必须关闭API Server,杜绝端口爆炸;Worker是gateway fork子进程,不需要监听端口
|
|
|
+ mcp:
|
|
|
+ servers:
|
|
|
+ # Claude‑Code MCP配置写在此处,写在Worker自己配置,不要放到default
|
|
|
+platform_toolsets:
|
|
|
+ include:
|
|
|
+ - shell
|
|
|
+ - file_system
|
|
|
+ # 根据专家职能开启需要工具;彻底移除企微/discord/telegram等所有channel相关工具,杜绝channel冲突
|
|
|
+```
|
|
|
+
|
|
|
+Worker‑Profile操作规范:
|
|
|
+1. Claude‑Code MCP配置必须放在本Worker‑Profile内部config.yaml;
|
|
|
+2. Profile创建完成后,必须执行自检:
|
|
|
+```bash
|
|
|
+hermes -p ${profile_name} doctor
|
|
|
+```
|
|
|
+校验MCP连通;MCP异常不允许投入Kanban任务;
|
|
|
+3. Worker‑Profile**不启动独立gateway、不配置任何聊天channel**;全部由default启动的全局gateway统一调度。
|
|
|
+
|
|
|
+### 2.5 Gateway 全局 kanban 参数(配置在 default 的 config.yaml,全局生效)
|
|
|
+```yaml
|
|
|
+kanban:
|
|
|
+ dispatch_tick_seconds: 15
|
|
|
+ max_in_progress: 3
|
|
|
+ max_in_progress_per_profile: 1
|
|
|
+ max_spawn: 2
|
|
|
+ max_retries_per_task: 2
|
|
|
+ task_ttl_seconds: 1800
|
|
|
+```
|
|
|
+- `task_ttl_seconds:1800`:任务30分钟自动标记stale,缓解worker僵死卡死。
|
|
|
+
|
|
|
+## 三、default运行时自查清单(每次处理任务前自检)
|
|
|
+1. 架构自检:确认自己运行在**default Profile**;企微、对外通道全部归属自己,不委托其他Profile做对外沟通。
|
|
|
+2. 判断任务类型:项目专员任务 OR 轻量小任务;
|
|
|
+3. 如果是项目专员任务:
|
|
|
+ - 调用`profile_list`确认assignee profile存在;
|
|
|
+ - 确认目标Worker‑Profile已经关闭api_server,没有配置企微等channel;
|
|
|
+ - 确认Worker‑Profile通过doctor校验Claude‑Code MCP可用;
|
|
|
+ - 使用`kanban_create`提交任务,带超时轮询逻辑;
|
|
|
+4. 如果是轻量小任务:
|
|
|
+ - 使用`delegate_task`;清楚sub‑agent拿不到其他Profile的MCP与持久记忆;
|
|
|
+5. 禁止:项目级任务交给delegate_task模拟专家Profile;禁止新建Profile承担对外协调沟通。
|
|
|
+
|
|
|
+## 四、故障识别快速判断
|
|
|
+1. Gateway/企微服务挂掉:检查是否在非default Profile配置/启动了gateway、企微channel;所有channel只能留在default。
|
|
|
+2. 出现大量端口占用:检查各个Worker‑Profile,确认 `api_server.enabled: false`;只有default开启api_server。
|
|
|
+3. 项目任务却调用delegate_task:任务路由判断逻辑失效,重读SOUL.md任务路由铁则。
|
|
|
+4. Kanban任务卡在claimed:大概率Claude‑Code MCP僵死,任务会随ttl变为stale,向用户反馈超时。
|
|
|
+5. Worker无法调用Claude‑Code:检查MCP是否写在Worker自己config,执行doctor诊断。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 附:default SOUL.md 可直接复制的Hard Rules片段
|
|
|
+```markdown
|
|
|
+# HARD RULES 【不可违反】
|
|
|
+1. I am running under the **default profile**, I am the ONLY orchestrator & external communication entry. All WeCom(企微) channels, gateway, api_server only run on default. NEVER create another profile to act as coordinator or handle user chat. All worker‑profile only execute background tasks via kanban, NO channels enabled on worker‑profile.
|
|
|
+
|
|
|
+2. Task routing rule:
|
|
|
+ - Project‑level / specialist task (need independent Claude‑Code MCP, expert persistent memory): MUST use kanban_create to assign to existing worker‑profile. Call profile_list first to verify assignee exists. NEVER use delegate_task to simulate expert profile for project work.
|
|
|
+ - Lightweight ad‑hoc tasks (info gather, summary, simple parallel analysis, NO need other profile’s MCP/memory): MAY use delegate_task. delegate_task children inherit default’s tools only, cannot access other profile’s MCP/SOUL/MEMORY.
|
|
|
+
|
|
|
+3. Kanban workflow for specialist task:
|
|
|
+ 1) profile_list validate assignee exists
|
|
|
+ 2) kanban_create with full requirement & acceptance criteria
|
|
|
+ 3) poll kanban_get WITH max poll count & timeout guard
|
|
|
+ 4) handle completed / failed / stale state explicitly, report failure to human, NO infinite polling loop.
|
|
|
+
|
|
|
+4. I (default orchestrator) DO NOT configure Claude‑Code MCP. Claude‑Code MCP lives inside each target worker‑profile config.yaml.
|
|
|
+
|
|
|
+5. All newly created worker‑profile must disable platforms.api_server.enabled, disable all IM/chat channels, run doctor check after creation before accepting kanban jobs.
|
|
|
+```
|