# 组织级 Agent 系统概览

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
1. **文档分层，链接代码** - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议，或大量代码；决策依据或修改日志若有必要，可在`docs/decisions.md`另行记录

## 文档说明

本文档描述组织级 Agent 系统的整体架构、业务场景和 MVP 规划。

**Enterprise 文档结构**：
- **overview.md**（本文档）：整体架构、业务场景、MVP 规划
- **[implementation.md](./implementation.md)**：认证、审计、多租户技术实现

**相关文档**：
- [知识管理](../../../docs/knowledge.md)：知识结构、检索、提取机制
- [Scope 设计](../../../docs/scope-design.md)：知识可见性和权限控制
- [Agent 框架](../../../docs/README.md)：核心 Agent 能力

---

## 原则

- 智能、共享、积累成长
- 未来人的工作是产生新的能力

## 架构

### 1. 用户交互层

**飞书空间组成**：

**人类员工**：
- 运营人员
- 编辑
- 管理员

**通用助理（入口 Agent）**：
- 处理一般性问题
- 智能路由到职能 Agent
- 协调多个 Agent 协作

**职能 Agent（专业领域）**：
- 爬虫运维 Agent
- 内容库 Agent
- 成本统计 Agent

**交互模式**：
- 单聊：用户 ↔ 通用助理 / 职能 Agent
- 群聊：项目群（人 + 多个 Agent）
- @ 调用：群里 @爬虫运维 检查状态
- 智能路由：通用助理识别意图 → 转接职能 Agent

---

### 2. 网关层（Gateway）

网关层负责请求的认证、鉴权、路由和审计。详细技术设计见 [Enterprise 层实现](./implementation.md)。

#### 核心功能

- **认证**：飞书 OAuth、API Key、JWT
- **权限控制**：角色验证、资源访问控制、操作权限检查
- **成本与限额**：用户级/组织级限额、实时成本计算、超限告警
- **审计**：操作日志、成本记录、安全事件、合规追溯
- **路由**：识别目标 Agent、上下文加载、会话管理、多 Agent 协作
- **消息队列**：异步任务、定时任务、事件触发、优先级队列

**实现位置**：`enterprise/gateway/`

**扩展点**：
- 中间件：`agent/trace/api.py:TraceAPI.middlewares`
- 钩子：`agent/core/runner.py:AgentRunner.hooks`
- Context：`agent/core/runner.py:RunConfig.context`

---

### 3. Agent 执行层

#### Agent Runner（基于现有框架）

**输入**：`messages + config (user_id, agent_id, context)`

**Phase 1: 准备阶段**
- 创建/加载 Trace
- 加载 Agent 配置（职责、能力、权限）
- 初始化工作空间

**Phase 2: 上下文构建**
- 加载用户画像（type=user_profile, scopes 包含 user_id）
- 加载 Agent 记忆（type=strategy, scopes 包含 agent_id）
- 注入全局知识库（scopes=global 或 org:{org_id}）
- 注入资源文档
- 构建 system prompt

**Phase 3: 执行循环**
- LLM 推理
- 工具调用
- 知识库查询/提交
- 子 Agent 协作
- 结果生成

**Phase 4: 完成阶段**
- 保存 Trace
- 同步到对话文件
- 更新 Agent 记忆
- 记录成本
- 返回结果

**输出**：`Trace + Messages`（流式）

#### 工具系统（Tools）

**内置工具**：
- 文件操作（read, write, edit, glob, grep）
- 命令执行（bash, sandbox）
- 网络工具（web_search, webfetch）
- 浏览器自动化
- 子 Agent 调用（agent, evaluate）

**知识库工具**：
- query_knowledge（查询知识，支持 type 和 scopes 过滤）
- save_knowledge（保存知识，自动设置 scopes 和 owner）

**领域工具（可扩展）**：
- 爬虫管理工具
- 内容库查询工具
- 成本统计工具
- 自定义工具...

---

### 4. 知识管理层

知识管理层负责知识的存储、检索和权限控制。详细设计见：
- [知识管理文档](./knowledge.md)：知识结构、检索、提取机制
- [Scope 设计文档](./scope-design.md)：知识可见性和权限控制

#### 文件系统存储（File System）

```
/workspace/
├── conversations/              # 对话记录
│   ├── {user_id}/              # 按用户组织
│   │   ├── YYYY-MM-DD.md       # 每日对话
│   │   ├── summary/            # 定期总结
│   │   └── metadata.json       # 权限元数据
│   └── ...
│
├── agents/                     # Agent 工作空间
│   ├── general_assistant/      # 通用助理
│   │   ├── profile.json        # 配置
│   │   └── memory/             # 持久记忆
│   │
│   ├── crawler_ops/            # 爬虫运维 Agent
│   │   ├── profile.json
│   │   ├── memory/             # 持久记忆
│   │   │   ├── working.md      # 当前状态
│   │   │   ├── history/        # 历史记录
│   │   │   └── relations.json  # 协作关系
│   │   └── tasks/              # 任务队列
│   │
│   ├── content_library/        # 内容库 Agent
│   └── cost_analytics/         # 成本统计 Agent
│
├── resources/                  # 组织资源（只读）
│   ├── company/                # 公司信息
│   ├── docs/                   # 业务文档
│   ├── processes/              # 流程规范
│   └── metadata.json           # 权限配置
│
├── knowledge/                  # 统一知识库（新增）
│   ├── global/                 # 全局知识（scopes=global）
│   ├── agents/                 # Agent 经验（scopes=agent:xxx）
│   └── users/                  # 用户画像（scopes=user:xxx）
│
└── traces/                     # 执行记录
    ├── {user_id}/              # 用户的 Trace
    ├── {agent_id}/             # Agent 的 Trace
    └── metadata.json           # 权限元数据
```

#### 知识库数据库（KnowHub Database）

统一知识表，支持用户画像、执行经验、工具知识等多种类型。

**核心字段**：
- `type`：知识类型（user_profile, strategy, tool, usecase, definition, plan）
- `scopes`：可见范围（user:xxx, agent:xxx, project:xxx, team:xxx, org:xxx, public）
- `owner`：所有者（唯一，控制修改权限）
- `embedding`：向量检索

**详细设计**：见 [知识管理文档](./knowledge.md) 和 [Scope 设计文档](./scope-design.md)

**实现位置**：`agent/tools/builtin/knowledge.py`

#### 代码库

对 Agent 的可见性（待定义）

---

### 5. 基础设施层

基础设施层提供审计、监控、配置管理等支撑功能。详细技术设计见 [Enterprise 层实现](./implementation.md)。

#### 审计与监控（Audit & Monitoring）

**审计日志**：
- `audit.jsonl`：操作审计（API 调用、资源访问）
- `cost.jsonl`：成本记录（Token 消耗、费用统计）
- `security.jsonl`：安全审计（认证失败、权限拒绝）
- `knowledge.jsonl`：知识审计（知识的创建、修改、查询）

**监控指标**：
- 调用频率、成功率、响应时间
- Token 消耗、成本统计、限额告警
- 异常检测、安全事件

**实现位置**：`enterprise/audit/`

#### 配置管理（Configuration）

```
/workspace/config/
├── system.yaml                 # 系统配置
├── agents.yaml                 # Agent 配置
├── permissions.yaml            # 权限配置
├── limits.yaml                 # 限额配置
└── feishu.yaml                 # 飞书配置
```

#### 备份与恢复（Backup & Recovery）
- 定期备份（对话、Trace、知识库）
- 增量备份
- 灾难恢复

---

## MVP 实施阶段

### Phase 1: 基础设施（Week 1-2）

**目标**：建立权限、审计、成本控制基础

**任务**：
- 实现 API Key 认证（`enterprise/auth/providers/api_key.py`）
- 实现飞书用户映射（`integrations/feishu/auth.py`）
- 实现审计日志系统（`enterprise/audit/logger.py`）
- 实现基础权限检查（`enterprise/auth/permissions.py`）
- 实现成本记录（`enterprise/audit/hooks.py`）

**原则**：权限和审计不能妥协，必须从一开始做对

### Phase 2: 通用助理（Week 3-4）

**目标**：
- 创建通用助理飞书账号
- 实现基础对话功能
- 对话同步到文件系统
- 知识库数据库设计和接口
- 知识库工具实现（query_knowledge/save_knowledge）
- 用户画像提取和检索机制

### Phase 3: 职能 Agent（Week 5-6）

**目标**：
- 选择一个高价值场景
- 创建职能 Agent 飞书账号
- 实现 Agent 记忆持久化
- 实现领域工具集成
- 测试通用助理 → 职能 Agent 路由

**原则**：
- 选择痛点明确、价值可量化的场景
- 验证职能 Agent 的记忆和专业能力
- 测试 Agent 间协作

---

## 相关文档

- [Enterprise 层实现](./implementation.md)：认证、审计、多租户技术实现
- [知识管理](../knowledge.md)：知识结构、检索、提取机制
- [Scope 设计](../scope-design.md)：知识可见性和权限控制
- [Agent 框架](../README.md)：核心 Agent 能力