Jerry Liang
fbcf388620
feat: 脚本调用工具 run_script（模型写 Python 脚本，网关在沙箱中批量调用 MCP 工具；写工具执行前统一审批一次、破坏性工具不可用；审计一条汇总、明细写入工作区；会话中显示脚本进度）
|
4 napja | |
|---|---|---|
| .. | ||
| adr | 4 napja | |
| design | 4 napja | |
| guides | 4 napja | |
| research | 1 hete | |
| README.md | 4 napja | |
| integration.md | 4 napja | |
README.md
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>、<TeamChat> 组件）
├─ guides/
│ └─ mcp-guide.md MCP 接入指南：给 MCP 服务开发者（工具设计、长任务、询问用户、资源、认证）
├─ 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（一期至三期已实施）
│ ├─ 14-schedules.md 定时任务：在对话中创建，到点自动在会话或工作组中执行
│ ├─ 15-background-calls.md 后台调用：外部工具的长调用由服务端等待，完成后通知 AI 继续
│ ├─ 16-mcp-support.md MCP 支持完善：工具提示、结构化输出、长任务、询问用户、OAuth、资源与提示模板
│ └─ 17-run-script.md 脚本调用工具：模型写 Python 脚本，由网关在沙箱中执行并批量调用 MCP 工具
├─ 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 |
| 0025 | 按 MCP 规范补齐工具以外的能力（长任务、询问用户、OAuth、资源等） | Accepted |
| 0026 | 脚本批量调用工具由网关在沙箱中执行 | 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 中的可读/可写/禁止路径配置，与全局禁止项、基线合并后生效 |