组织级 Agent 系统概览

文档维护规范

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

文档说明

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

Enterprise 文档结构：

overview.md（本文档）：整体架构、业务场景、MVP 规划
implementation.md：认证、审计、多租户技术实现

相关文档：

知识管理：知识结构、检索、提取机制
Scope 设计：知识可见性和权限控制
Agent 框架：核心 Agent 能力

原则

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

架构

1. 用户交互层

飞书空间组成：

人类员工：

运营人员
编辑
管理员

通用助理（入口 Agent）：

处理一般性问题
智能路由到职能 Agent
协调多个 Agent 协作

职能 Agent（专业领域）：

爬虫运维 Agent
内容库 Agent
成本统计 Agent

交互模式：

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

2. 网关层（Gateway）

网关层负责请求的认证、鉴权、路由和审计。详细技术设计见 Enterprise 层实现。

核心功能

认证：飞书 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. 知识管理层

知识管理层负责知识的存储、检索和权限控制。详细设计见：

知识管理文档：知识结构、检索、提取机制
Scope 设计文档：知识可见性和权限控制

文件系统存储（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：向量检索

详细设计：见知识管理文档和 Scope 设计文档

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

代码库

对 Agent 的可见性（待定义）

5. 基础设施层

基础设施层提供审计、监控、配置管理等支撑功能。详细技术设计见 Enterprise 层实现。

审计与监控（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 间协作

overview.md 9.2 KB Bezpośredni odnośnik Historia Czysty