01 需求与范围

1. 背景与目标

在一台自有 Linux 服务器上运行 AgentServer，把 Claude Code 和 Codex 的 Agent 能力以统一 API 提供给多个内部业务平台使用，并提供管理后台进行配置、调试和监控。

2. 使用场景

维度	结论
使用者	本人；服务不区分使用者，只对上层平台提供 API
接入方	多个自建内部平台（前端技术栈：Vue + TS + UnoCSS），每个平台一个 API Key
任务类型	数据分析、资料查找与分析、生成数据文档/报表等通用任务；一般不写代码
工作区	不需要 git；每个会话一个独立目录
资料来源	本地资料（服务器目录，路径在后台设定）+ 远程资料（公网检索）；内部平台数据接入暂缓
输入	文本、数据文件（CSV/Excel/PDF/Word…）、截图图片
模型凭证	复用本人在终端登录的 CLI 登录态（`~/.claude`、`~/.codex`），见 06-security §7
部署	单机单实例
后台用户	仅本人

3. 功能需求

3.1 Agent 接入（F-AGENT）

F-AGENT-1 支持 Claude Code（Agent SDK）和 Codex（app-server）两个引擎
F-AGENT-2 会话：创建、多轮对话、恢复（服务重启后可继续）、中断、删除
F-AGENT-3 流式输出：文本增量、思考过程、工具调用与结果、文件产出、用量
F-AGENT-4 统一事件模型，前端不感知引擎差异
F-AGENT-5 交互式人工介入：工具执行审批、Agent 主动提问，前端实时响应后 Agent 继续执行
F-AGENT-6 Profile 预设：提示词、模型、权限模式、可用工具、技能（Skills）、文件访问策略（可读/可写/禁止路径）
F-AGENT-7 输入支持图片（截图）与文件附件

3.2 文件与资料（F-DATA）

F-DATA-1 上传数据文件和截图到会话工作区
F-DATA-2 浏览、预览、下载工作区产出文件（报告、图表、xlsx/docx/pdf）
F-DATA-3 本地资料库：在后台设定资料目录（路径、说明、读写属性），Profile 选择启用
F-DATA-4 远程检索：公网搜索与网页抓取
F-DATA-5 （暂缓）内部平台数据访问：通过 MCP Gateway 连接器提供，设计见 08

3.3 对外 API（F-API）

F-API-1 REST + SSE；SSE 支持断线续传
F-API-2 平台级 API Key 鉴权；不区分使用者
F-API-3 提供 TS 客户端 SDK 与 Vue 对话组件包，供各平台直接复用

3.4 管理后台（F-ADMIN）

F-ADMIN-1 登录（单管理员）
F-ADMIN-2 Playground：在后台直接与 Agent 对话以验证功能，视觉风格对齐 Claude VS Code 插件
F-ADMIN-3 会话浏览与事件回放
F-ADMIN-4 Profile 管理（可从 Playground 另存）
F-ADMIN-5 引擎状态：登录状态、可用模型、限额信息（只读）
F-ADMIN-6 API Key 管理
F-ADMIN-7 资料库管理（路径设定、可见性检测）
F-ADMIN-10 系统设置：路径（工作区、技能、Python 环境）、全局禁止路径、网络白名单、并发与超时、保留期
F-ADMIN-8 概览：运行中任务、用量趋势、错误
F-ADMIN-9 审计日志：命令执行、越权访问拦截、审批记录

4. 非功能需求

编号	要求
NF-1 安全	Agent 只能写自己的工作区；看不到服务器上的个人文件与凭证；不能直接访问局域网
NF-2 资源	全局与每引擎并发上限；单进程内存/CPU 上限；超出排队
NF-3 可恢复	服务重启后历史会话可继续；中断中的 Run 标记为 `interrupted`
NF-4 可观测	全量事件落库可回放；结构化日志；用量统计
NF-5 可维护	引擎 CLI 版本锁定，升级需在 Playground 回归验证
NF-6 合规	订阅登录态仅供本人使用（见 06-security §7）

5. 不做（Out of Scope）

多租户、对外公开服务、计费
代码仓库/git 集成、PR 工作流
多实例/集群部署
后台多管理员与 RBAC
区分终端使用者、按使用者路由凭证
内部平台连接器（框架已设计，暂缓实现）