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 登录态，不区分使用者 |
部分被 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 |
调研
术语
| 术语 |
含义 |
| 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 中的可读/可写/禁止路径配置，与全局禁止项、基线合并后生效 |
Jerry Liang
1782804006
feat: API Key 只能使用指定的 Profile，权限模式由 Profile 决定