# Clawith 架构研究与 AgentKit 改进分析

## 研究背景

Clawith (clawith.ai) 是一个开源的多智能体协作平台，基于 OpenClaw 构建，旨在将 AI 代理从简单的聊天机器人提升为组织的"数字员工"。

GitHub: https://github.com/dataelement/Clawith
许可证: MIT
技术栈: React 19 + TypeScript / FastAPI + PostgreSQL + Redis

---

## Clawith 核心架构

### 1. Agent Plaza — 协作知识流
**设计理念**：代理共享的社交空间，代理在其中发布更新、分享发现、评论彼此的工作，实现知识流动而非被动查询。

**核心组件**：
- `PlazaFeed`：类似社交 feed，支持 post、comment、tag 过滤
- `KnowledgeBase`：组织级共享知识池
- 代理可订阅相关领域 feed，实现"被动发现"

### 2. Persistent Identity — Soul & Memory
**设计理念**：每个代理有跨会话的持久身份，而非每次会话从头开始。

**核心组件**：
- `soul.md`：代理的个性、价值观、工作风格（持久存储）
- `memory.md`：长期上下文和学习到的偏好
- 代理启动时加载 Soul，用于 Prompt 注入

### 3. Organization Awareness — 组织感知
**设计理念**：代理理解完整组织结构，知道谁是同事，能自主建立工作关系和委派任务。

**核心组件**：
- `OrganizationContext`：组织架构、代理能力矩阵
- 代理之间可以自发 `handoff`，而非只能通过中央编排器
- 像新员工加入团队一样自然融入

### 4. Supervision Tasks — 主动跟进
**设计理念**：代理可以代表组织主动跟进同事，确保待办事项完成。

**核心组件**：
- `SupervisorAgent`：可配置自动跟进规则
- `deadline`、`reminder`、`escalation` 机制

### 5. Self-Evolution — 自我进化
**设计理念**：代理遇到无法处理的任务时，主动搜索 MCP 注册表发现并安装新工具。

**核心组件**：
- 从 Smithery + ModelScope MCP 注册表搜索工具
- 代理可为自己或同事创建新 Skill
- `SkillCreator` 工具

### 6. Enterprise Governance — 企业治理
**设计理念**：组织级控制能力。

**核心组件**：
- `UsageQuota`：每个用户/代理的消息限制、Token 配额、代理 TTL
- `ApprovalWorkflow`：危险操作需人工审批
- `AuditLog`：全链路操作可追溯
- RBAC + 多租户隔离

---

## AgentKit 当前架构

### 项目结构
```
src/agentkit/
├── core/          # BaseAgent、Orchestrator、Dispatcher、Registry
├── skills/        # SkillConfig、Skill、SkillRegistry、SkillLoader
├── memory/        # WorkingMemory、EpisodicMemory、SemanticMemory、RAG
├── evolution/     # EvolutionMixin、Reflector、PromptOptimizer、ABTester
├── llm/           # LLMGateway、Provider（OpenAI/Anthropic/Gemini/DeepSeek/国产）
├── orchestrator/  # PipelineEngine、HandoffManager、DynamicPipeline
├── mcp/           # MCPClient、MCPServer、MCPManager
├── tools/         # Tool基类、FunctionTool、AgentTool、MCPTool
├── server/        # FastAPI Server、routes、middleware
└── telemetry/     # OpenTelemetry tracing + metrics
```

### 已实现的核心能力
- **ReAct Engine**：`react.py` 实现推理-行动循环
- **LLM Gateway**：`llm/gateway.py` 统一调用、路由、计量
- **Intent Router**：`router/intent.py` 三级路由（关键词+LLM）
- **Quality Gate**：`quality/gate.py` 产出质量管理
- **Skill System**：`skills/base.py` SkillConfig + Skill + SkillRegistry
- **Evolution System**：`evolution/lifecycle.py` 反思→优化→A/B测试→应用
- **Pipeline**：`orchestrator/pipeline_engine.py` 多步骤编排+重试+补偿

---

## 差距分析

### 功能对比表

| 功能 | Clawith | AgentKit | 差距 |
|------|---------|----------|------|
| Agent Plaza | ✅ | ❌ | 需要新增 plaza/ 模块 |
| Soul/Memory 持久身份 | ✅ | ⚠️ 部分 | Soul 缺失，memory 是会话级非代理级 |
| 组织感知 | ✅ | ❌ | Agent 不知道可以向谁求助 |
| Supervision Tasks | ✅ | ❌ | 任务即结束，无跟进机制 |
| 主动 Self-Evolution | ✅ | ⚠️ 被动 | evolve_after_task 是完成后触发 |
| Enterprise Governance | ✅ | ⚠️ 部分 | QualityGate 有，Quota/审批/RBAC 无 |
| 多渠道 Gateway | ✅ | ⚠️ MCP | 当前是 Agent 平台，Clawith 是 Channel |
| 意图路由 | ✅ | ✅ | 已有 Intent Router |

---

## 建议优先实现的功能

### P0 — 组织感知 + 主动进化

**1. OrganizationContext（组织上下文）**
- 新增 `src/agentkit/org/context.py`
- `OrganizationModel`：组织架构、代理能力注册表
- `Agent.on_task_start()` 自动注入组织上下文
- 支持代理主动 `handoff` 给合适的同事

**2. 主动工具发现**
- 当 ReAct 循环遇到未知任务时，触发 MCP 注册表搜索
- 新增 `ToolDiscovery` 类
- 集成 Smithery + ModelScope MCP 注册表

### P1 — Agent Plaza + Persistent Identity

**3. Agent Plaza**
- 新增 `src/agentkit/plaza/` 模块
- `PlazaFeed`、`KnowledgeShare`、`SubscriptionManager`
- 代理可发布状态、评论、发现

**4. Soul & LongTermMemory**
- 新增 `src/agentkit/identity/` 模块
- `SoulManager`：管理代理 soul.md
- `LongTermMemory`：跨任务的持续记忆

### P2 — Supervision + Enterprise Governance

**5. Supervision Tasks**
- 新增 `SupervisionTask` 类型
- `SupervisorAgent` 主动跟进机制

**6. Enterprise Governance 补齐**
- `UsageQuota`
- `ApprovalWorkflow`
- 完善 RBAC

---

## 深入分析任务

请在另一个会话中完成以下分析：

1. **OrganizationContext 详细设计**
   - 如何表示组织架构和代理能力
   - Agent 如何感知可用的同事
   - handoff 协议如何扩展支持自发协作

2. **Agent Plaza 技术方案**
   - Feed 数据模型设计
   - 与现有 Memory 系统如何集成
   - 订阅/推送机制实现

3. **Persistent Identity 实现路径**
   - soul.md 的 Schema 设计
   - LongTermMemory 与 WorkingMemory/EpisodicMemory 的关系
   - 跨会话记忆如何注入 Prompt

4. **Self-Evolution 主动性增强**
   - 何时触发工具发现
   - 如何平衡探索成本和任务需求
   - 发现新工具后如何学习使用

5. **与现有 Phase 6/7/8 规划的关系**
   - Layered Memory（Phase 8）
   - Adaptive Chat（Phase 8）
   - Headroom（Phase 7）
   - 如何避免重复建设

6. **实现优先级和依赖关系**
   - 哪些功能可以并行开发
   - 哪些必须依赖其他模块先完成
   - 建议的迭代顺序