# 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](06-security.md#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
- 区分终端使用者、按使用者路由凭证
- 内部平台连接器（框架已设计，暂缓实现）