AgentServer/docs

AgentServer 设计文档

AgentServer 是一个自托管的 Agent 服务：在服务端接入 Claude Code 和 Codex，用统一的 API 给多个内部业务前端提供 Agent 能力，并附带一个管理后台（含 Playground 对话调试）。

状态：M1、M2 已完成（Claude 与 Codex、MCP Gateway、技能与插件、用量统计、业务平台接入），下一步 M3 · 最后更新：2026-10-23

文档结构

docs/
├─ README.md                  本文件：索引、术语、文档约定
├─ integration.md             业务平台接入指南（SDK 安装、浏览器令牌、<AgentChat> 组件）
├─ design/                    设计文档（随设计演进持续更新）
│  ├─ 01-requirements.md      需求与范围
│  ├─ 02-architecture.md      总体架构、模块划分、运行时模型
│  ├─ 03-providers.md         引擎接入：Claude Agent SDK / Codex app-server
│  ├─ 04-api.md               对外 API、统一事件模型、交互协议
│  ├─ 05-data-model.md        数据模型与存储
│  ├─ 06-security.md          隔离、沙箱、网络、凭证与合规
│  ├─ 07-files-and-knowledge.md  文件/截图上传、文档分析、本地与远程资料检索
│  ├─ 08-platform-connectors.md  内部平台数据接入（MCP Gateway）
│  ├─ 09-admin-ui.md          管理后台与 Playground（含视觉规范）
│  ├─ 10-deployment.md        部署与运维
│  ├─ 11-roadmap.md           里程碑与待决事项
│  ├─ 12-custom-skills.md     自定义技能（导入或在后台编写，两个引擎共用）
│  └─ 13-bot-teams.md         Bot 工作组：多岗位机器人、组长分派任务、Bot API（一期、二期已实施）
├─ adr/                       架构决策记录（一事一档，只追加不改写；推翻时新增一条并标注 Superseded）
└─ research/                  调研材料（选型依据、参考实现分析）

架构决策索引（ADR）

#	决策	状态
0001	后端采用 Node.js + TypeScript	Accepted
0002	Claude 通过 Agent SDK 接入	Accepted
0003	Codex 通过 codex app-server 接入	Accepted
0004	隔离：引擎沙箱 + 专用用户 + systemd 加固	Superseded → 0009
0005	模型凭证使用 CLI 登录态，按使用者路由	Superseded → 0008
0006	内部平台数据通过统一 MCP Gateway 暴露	Accepted（连接器暂缓）
0007	后台用 Vue 3 + UnoCSS，视觉对齐 Claude VS Code 插件	Accepted
0008	复用本人终端的 CLI 登录态，不区分使用者	部分被 0012 取代
0009	暂不使用专用用户：引擎沙箱 + systemd 加固 + 应用层校验	Superseded → 0012
0010	文件读写权限由 Profile 配置，三层合并	Accepted
0011	路径等运行配置由后台管理，不写死在配置文件中	Accepted
0012	以专用用户 agentsvc 运行服务	Accepted
0013	官方技能通过 Claude Code 插件机制使用	Accepted
0014	在后台完成 Claude 登录	Accepted
0015	API Key 只能使用指定的 Profile；权限模式由 Profile 决定	Accepted
0016	每个引擎接入各自厂商的官方技能仓库	Accepted
0017	第三方技能：skills.sh 目录 + GitHub 固定提交，两个引擎共用	Accepted
0018	Codex 插件（openai-curated）只在 Playground 中使用	Accepted
0019	浏览器令牌、CORS 与 SDK 包分发	Accepted
0020	Codex 会话配置变化时分叉	Accepted
0021	第三方 MCP 服务经 MCP Gateway 转接	Accepted
0022	服务管理的技能目录在沙箱中只读可见；Codex 的禁止规则绕开可读路径	Accepted
0023	Bot 工作组：协调者模式，每个机器人一个独立会话	Accepted
0024	Bot API 使用独立路径和独立的 Bot Key	Accepted

调研

• research/claude-vscode-ui-reference.md — Claude VS Code 插件视觉规范提取
• research/document-analysis-approaches.md — 官方客户端的文档分析方案

术语

术语	含义
Provider / 引擎	底层 Agent 实现：claude 或 codex
Platform / 平台	接入 AgentServer 的一个上层业务前端（持有 Agent Key 和/或 Bot Key）；服务不区分终端使用者
Agent Key / Bot Key	后台"API Keys"页面签发的两类密钥：Agent Key（ask_，原名 API Key）只能调用 /v1，按 Profile 授权；Bot Key（bk_）只能调用 /bot/v1，按机器人授权（ADR-0024）
Session / 会话	一段多轮对话，绑定一个 Provider、一个 Workspace
Run	会话中的一次"用户发言 → Agent 完成"的执行过程
Event	Run 过程中产生的统一事件（文本增量、工具调用、交互请求…）
Interaction / 交互	Agent 需要人参与的点：审批（approval）或提问（question）
Workspace / 工作区	会话的独立目录，存放上传文件与产出文件
Profile	Agent 预设：提示词、模型、工具、连接器、权限模式的组合
Connector / 连接器	（暂缓）一个内部平台的数据接入定义，通过 MCP Gateway 暴露为工具
Knowledge Root / 资料库	在后台登记的本地资料目录，Profile 启用后 Agent 可以访问
Bot / 机器人	后台配置的岗位：身份 + 关联的 Profile；分组长（lead）和组员（worker）两类（见 13）
Team / 工作组	Bot 协作的容器：1 个成员（人）+ 0–1 个组长 + 0–多个组员
Job / 任务、Task / 子任务	成员交给组长的复杂工作；组长分派给组员的单项工作
File Access Policy / 文件访问策略	Profile 中的可读/可写/禁止路径配置，与全局禁止项、基线合并后生效