# 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](adr/0001-nodejs-typescript-backend.md) | 后端采用 Node.js + TypeScript | Accepted |
| [0002](adr/0002-claude-agent-sdk.md) | Claude 通过 Agent SDK 接入 | Accepted |
| [0003](adr/0003-codex-app-server.md) | Codex 通过 `codex app-server` 接入 | Accepted |
| [0004](adr/0004-isolation-strategy.md) | 隔离：引擎沙箱 + 专用用户 + systemd 加固 | Superseded → 0009 |
| [0005](adr/0005-cli-login-credentials.md) | 模型凭证使用 CLI 登录态，按使用者路由 | Superseded → 0008 |
| [0006](adr/0006-mcp-gateway.md) | 内部平台数据通过统一 MCP Gateway 暴露 | Accepted（连接器暂缓） |
| [0007](adr/0007-admin-ui-vue-vscode-style.md) | 后台用 Vue 3 + UnoCSS，视觉对齐 Claude VS Code 插件 | Accepted |
| [0008](adr/0008-personal-cli-login.md) | 复用本人终端的 CLI 登录态，不区分使用者 | 部分被 0012 取代 |
| [0009](adr/0009-isolation-without-dedicated-user.md) | 暂不使用专用用户：引擎沙箱 + systemd 加固 + 应用层校验 | Superseded → 0012 |
| [0010](adr/0010-profile-file-access-policy.md) | 文件读写权限由 Profile 配置，三层合并 | Accepted |
| [0011](adr/0011-admin-managed-settings.md) | 路径等运行配置由后台管理，不写死在配置文件中 | Accepted |
| [0012](adr/0012-dedicated-service-user.md) | 以专用用户 agentsvc 运行服务 | Accepted |
| [0013](adr/0013-official-skills-via-plugins.md) | 官方技能通过 Claude Code 插件机制使用 | Accepted |
| [0014](adr/0014-admin-claude-login.md) | 在后台完成 Claude 登录 | Accepted |
| [0015](adr/0015-api-key-profiles.md) | API Key 只能使用指定的 Profile；权限模式由 Profile 决定 | Accepted |
| [0016](adr/0016-official-skill-repos-per-engine.md) | 每个引擎接入各自厂商的官方技能仓库 | Accepted |
| [0017](adr/0017-community-skills.md) | 第三方技能：skills.sh 目录 + GitHub 固定提交，两个引擎共用 | Accepted |
| [0018](adr/0018-codex-curated-plugins-playground-only.md) | Codex 插件（openai-curated）只在 Playground 中使用 | Accepted |

## 调研

- [research/claude-vscode-ui-reference.md](research/claude-vscode-ui-reference.md) — Claude VS Code 插件视觉规范提取
- [research/document-analysis-approaches.md](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 中的可读/可写/禁止路径配置，与全局禁止项、基线合并后生效 |