AgentServer/docs/README.md

AgentServer 设计文档

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

状态：M1 已完成（Claude 主链路 + 管理后台），M2 进行中 · 最后更新：2026-10-22

文档结构

docs/
├─ README.md                  本文件：索引、术语、文档约定
├─ 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           里程碑与待决事项
├─ 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 登录态，不区分使用者	Accepted
0009	暂不使用专用用户：引擎沙箱 + systemd 加固 + 应用层校验	Accepted
0010	文件读写权限由 Profile 配置，三层合并	Accepted
0011	路径等运行配置由后台管理，不写死在配置文件中	Accepted

调研

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

术语

术语	含义
Provider / 引擎	底层 Agent 实现：claude 或 codex
Platform / 平台	接入 AgentServer 的一个上层业务前端（持有一个 API Key）；服务不区分终端使用者
Session / 会话	一段多轮对话，绑定一个 Provider、一个 Workspace
Run	会话中的一次"用户发言 → Agent 完成"的执行过程
Event	Run 过程中产生的统一事件（文本增量、工具调用、交互请求…）
Interaction / 交互	Agent 需要人参与的点：审批（approval）或提问（question）
Workspace / 工作区	会话的独立目录，存放上传文件与产出文件
Profile	Agent 预设：提示词、模型、工具、连接器、权限模式的组合
Connector / 连接器	（暂缓）一个内部平台的数据接入定义，通过 MCP Gateway 暴露为工具
Knowledge Root / 资料库	在后台登记的本地资料目录，Profile 启用后 Agent 可以访问
File Access Policy / 文件访问策略	Profile 中的可读/可写/禁止路径配置，与全局禁止项、基线合并后生效