# FFAI Agent — Phase 1 PRD（Web 工作台首页 MVP → GA）

> **状态**：🟡 v0.2 — 架构反推已填；时间 / 人数 / 阈值待用户填
>
> **本文档定位**：Phase 1（Web 工作台首页）的**详细产品需求**。
>
> **上游**：[`01-prd.md`](./01-prd.md) §5.1
>
> **技术对应**：[`02-architecture.md`](./02-architecture.md) §8 PR1 → PR15.7

---

## 1. Phase 1 北极星与退出标准

> ❓ 阈值数字待 [`01-prd.md`](./01-prd.md) §11 P3 + P5 决策后填入（M0 Alpha 数据出来后定）。
>
> **测量基线统一**（review 反馈，所有 SLA 须 attached 这套基线，否则不可验证）：
> - **网络**：内网 / 公司 VPN（不是公网 4G）
> - **数据规模**：单组织 50-200 项目 / 5-20 个并发 user / Phase 1 测试 org 数 ≤ 5
> - **LLM 后端**：staging 真实 LLM（OpenAI gpt-4o-mini 默认 / Anthropic claude-haiku-4.5 fallback），mock 场景独立标注
> - **测量点**：所有 p50/p95 = 用户 client 端到首字 / 首工件 / 终态 三段时间分别测，不是后端单测

**SLA 三段定义**（替代笼统的"5 秒内"）：
- **首字延迟**（user 发消息 → SSE 出第一个 text token）
- **首工件延迟**（user 发消息 → Display Panel 出现第一个完整 artifact，如表格首行）
- **终态延迟**（user 发消息 → agent stop_reason=end_turn）

| 指标 | MVP 退出（PR1-PR7 完成）| GA 退出（PR0.5-PR15.7 完成）|
|---|---|---|
| 任务完成率（north star，人工抽样标注）| ≥ ❓ % | ≥ ❓ %（切 LLM-as-judge）|
| 内测 DAU | ≥ ❓ 人 | ≥ ❓ 人 |
| 内测周会话样本量（北极星统计有效性前置）| ≥ 500 sessions/周 + 内测人数 ≥ 80% 至少触发 1 次 | 同上 |
| 单会话平均业务动作数 | ≥ ❓ | ≥ ❓ |
| **首字延迟 p50** | < 1.5s | < 1.2s（review 反馈：< 1s 物理上不可达——gpt-4o-mini baseline 800ms-1.5s + ModelRouter ~100ms + ToolRegistry 校验 ~50ms = floor ≈ 1s）|
| **首工件延迟 p95**（业务工具 round-trip）| < 8s | < 5s |
| **终态延迟 p95**（含 LLM 思考完整 turn）| < 15s | < 10s |
| 月度 LLM 成本 / DAU | < $❓ | < $❓ |
| **跨组织数据泄漏事件** | < 1/季度 + 5 分钟可检测 + 30 分钟可清除（INV-1 SLO）| 同上 |
| 用户 NPS（内测后调研）| — | ≥ ❓ |
| ModelRouter 决策被 admin override 率 | < 30% | < 15% |
| **i18n missing key warning（CI/staging）** | = 0 | = 0 |

---

## 2. 用户故事（按优先级 P0 / P1 / P2）

> 格式：As a `<persona>`, I want to `<action>`, so that `<value>`.
>
> Persona 编号对应 [`01-prd.md`](./01-prd.md) §2.1。

### P0（MVP 必备 — 抓质量）

| # | Persona | 故事 | 涉及 PR |
|---|---|---|---|
| **US-100** | 全部（首次访问）| 我第一次进 `/agent` 时看到 Onboarding 引导：3 张示例 prompt 卡片（"上季度延期项目"/"提差旅审批"/"报销流程"）+ 协作模式简介 + i18n 切换提示。**验收标准**：起点 = SSO 跳转回来后页面 first paint；停点 = 用户键入完按 Enter 发出第一个 query；"有效"判定 = query 命中三件套之一（intent classifier 规则或简单关键词匹配）；样本 = M0 Alpha 5 人 × ≥ 3 次冷启动测试，p75 ≤ 30s | PR1（empty state UI）|
| **US-105b** | 全部（admin 视角）| 我（admin）想配 `OrganizationAgentSettings.allowedPermissionModes` 白名单（如禁 bypass + scripted），普通用户切不到禁用的 mode；admin 改后已存活 session 在下次 turn 强制重新协商 mode | PR4.5 |
| **US-101** | 项目经理 | 我想问 "上季度延期项目按延期天数排序"，立即在 Display Panel 看到表格，无需手动跑报表 | PR1-PR5 |
| **US-102** | 业务员工 | 我想说 "提个去上海三天的差旅审批"，agent 帮我填好表单等我确认提交 | PR1-PR6 |
| **US-103** | 新员工 | 我想问 "公司报销流程是什么"，从知识库拿到准确答案 + 引用源 | PR1-PR4 + PR5 (`Knowledge.search`) |
| **US-104** | 全部 | 我想看到所有历史会话按项目分组的左栏列表，能切回任意旧会话 | PR1-PR2 |
| **US-105** | 全部 | 我想拒绝/批准 agent 提议的高风险操作（写库 / 发邮件等），通过 Permission ask | PR4 + PR4.5 |
| **US-106** | 全部 | 我想切到 Plan mode 让 agent 先列计划再执行，避免不可逆操作 | PR4.5 |
| **US-107** | 项目经理 | 我想在 Display Panel 点击表格里的项目名跳转到项目详情页，不需要复制 ID 找 | PR5 (Display 链接渲染) |
| **US-108** | 全部 | 我想 agent 流式打字机效果回复，不卡白屏 | PR3 (SSE 流式) |

### P1（GA 前补齐 — 抓规模/效率）

| # | Persona | 故事 | 涉及 PR |
|---|---|---|---|
| **US-201** | 全部 | 我想用 `/clear` `/compact` `/help` 等内置 slash command 控制会话 | PR7 |
| **US-202** | 全部 | 我想看到工件库（跨会话检索 / 引用过去 artifact）| PR8-9 |
| **US-203** | 项目经理 | 我想说 "汇总我下属本周工作"，agent 派子 agent 并行跑后台返回汇总 | PR8 (Sub-agent) |
| **US-204** | IT 管理员 | 我想配 "每天 9 点自动汇总待审批" 跑 cron isolated agent | PR10 (Cron) |
| **US-205** | 业务员工 | 我想把会议纪要 PDF 上传 → agent 提取关键条款 → 存进我的 OneDrive 知识区 | PR10.5 (StorageBackend OneDrive) |
| **US-206** | IT 管理员 | 我想看 ModelRouter Decision Dashboard：本周组织 agent 调了哪些 model / 总成本 / 哪些规则被 override 最多 | PR10.6 |
| **US-207** | 全部 | 我想触发自定义 skill（"提交差旅审批" 这种工作流模板），同名时组织自定义优先 | PR7 |
| **US-208** | 项目经理 | 我想 agent 调用业务工具失败时给我有意义的错误（不是 stack trace），并建议下一步 | PR4 (FailoverError + Permission) |

### P2（GA 后再上）

- US-301: 工具发现/搜索（大工具集时 ToolSearch）
- US-302: Hooks（管理员自定义 PreToolUse 拦截）
- US-303: Memory（per-user MEMORY.md 索引）—— 注：架构 Q14 已锁 day-1 落 schema，但用户可见的 memory 管理 UI 进 P2

---

## 3. 功能清单（v0.3 review 后重排，含拆分 + 新增）

> **review 关键变更**（vs v0.2）：
> - **PR0.5 monorepo 骨架前置**（避免 Phase 1 GA 前抽包大返工）—— 工程 + 架构 review 共识
> - **PR2 收敛到 4 表**（业务隔离 / 单一迁移文件 + 其余表跟随各自功能 PR）
> - **PR3.6 quota/rate limit 紧跟 PR3.5**（不再压到 PR15.7 后置）
> - **PR4 拆为 PR4a/4b/4c**（TAOR 骨架 / Compaction / TrajectoryEvent + 哈希链）
> - **PR4.5 显式 depends_on：PR4a + PR5**（避免误并行）
> - **PR12.5 新增**：ai-assistant 收编为 `legacy-qa` skill（兑现 Q5 退役约定）
> - **PR15.7 拆**：i18n / 错误恢复 各 PR 单独消化，dashboards/quota 已前置

| PR | 功能模块 | 用户可见行为 | 优先级 | depends_on | 验收 |
|---|---|---|---|---|---|
| **PR0.5** | `packages/agent-protocol/` + `packages/agent-renderer-lark/` monorepo 骨架（业务代码后续直接落 packages 内）| 透明，不影响用户 | **P0 day-1** | — | build 通过 + 空 SDKMessage 类型可被引用 |
| **PR1** | UI 骨架 + `/agent` 路由 + **US-100 Onboarding empty state**（3 示例卡片）| 用户访问 `/agent` 看到布局 + 引导 + i18n 切换；Phase 2 redesign 后双栏 + slide-in artifacts 抽屉 | P0 | PR0.5 | Playwright MCP 看布局 + i18n 双语 + Onboarding 30 秒 fire 测试 |
| **PR2** | Prisma schema **核心 4 表**（AgentSession **含 surface enum 默认 'web' day-1** / AgentMessage / AgentTrajectoryEvent + 哈希链 + 时间×org 二级分区 / OrganizationAgentSettings **含 Phase 2 预留字段 day-1**：`disabledCapabilities String[]` / `allowedCliTools String[]` / `allowedPermissionModes String[]` —— 字段先建空，避免 Phase 2 PR13/PR15/PR4.5 二次迁移）+ Gateway Controller + WebInbox + **runtime DataScope violation 检测器**（INV-1 day-1 必备）+ **turn-level reconciliation 计数器**（INV-3 day-1） | 后端模块就绪 | P0 | — | L1 集成测试连通 PG + 跨 org 注入测试必拒 + REVOKE UPDATE/DELETE 强约束验证 + reconciliation 差值 ≥ 1 告警测试 |
| **PR0.6** | **Day-1 Ops Baseline**（review 反馈：监控/告警/灰度不能延 PR15.7）：Prometheus + Grafana skeleton + cost / quota / DataScope violation / failover 4 个 day-1 dashboard + PagerDuty 告警通道 + on-call rota + runbook 模板 + feature flag 系统（per-org / per-user toggle）+ DR runbook 草案 + 部署架构图含 LLM egress proxy | SRE / on-call 就位 | P0 | PR0.5 | dashboard 跑通 + 告警链路 PoC + feature flag 灰度切换演练 + 首次 DR tabletop（不实际 failover）|
| **PR3** | ModelProvider Registry + Resolver + Shim + OpenAI/Anthropic/Mock + **SDKMessage Anthropic 同构 review** | 接通 LLM | P0 | PR2，**前置依赖：法务 LLM 数据出境合规评估** | mock 跑通 + SDKMessage schema 跟 Anthropic 字段对齐 |
| **PR3.5** | **ModelRouter（G10 核心，day-1 全量）**：5 信号源 + rule-based + LLM-routed + scope-override + ModelRoutingRule/Decision schema | 不同任务自动选模型；决策落 PG | P0 | PR3 | Routing 决策可查 + admin dashboard mock 数据 |
| **PR3.6** | **Quota / Rate limiting**（per-user / per-org token + monthly cost budget + 超限策略 degrade-to-cheap-model）| admin 配 quota；用户超限 degrade 提示 | P0 | PR3.5 | quota 触发 → ModelRouter degrade 验证 |
| **PR4a** | QueryEngine 骨架（TAOR 主循环 + StreamingToolExecutor + AsyncGenerator<SDKMessage>）| 多轮 echo 对话不卡 | P0 | PR3.5 | 多轮 turn / 中断 / cancel 测试 |
| **PR4b** | Context Compaction（5 层）+ contentReplacementState | 长会话不爆 context | P0 | PR4a | 强制触发 compaction → 不丢必要 working set |
| **PR4c** | TrajectoryEvent 完整事件流 + 哈希链 + admin/audit/trajectory API + retention job + **两路异质外部锚定**（S3 Object Lock Compliance + 第三方 TSA）+ **时间×org 二级分区** day-1 启用 | admin 可钻取审计 | P0 | PR4a | 事件不可篡改测试 + 哈希链断裂检测（L1c 必备）+ 跨 anchor 一致性测试 |
| **PR4.5** | Plan / Permission mode 两轴 + EnterPlanMode/ExitPlanMode/SetPermissionMode 工具 + OrganizationAgentSettings 扩展 | 用户切 Plan mode；admin 可禁 bypass | P0 | **PR4a + PR5** | 模式切换 + 工具集过滤验证 |
| **PR5** | ToolRegistry + Descriptor + AvailabilityExpression + MCP Client + Project MCP（含 Skill / Hook 表 schema） | agent 跑通 "查项目并回显" | P0 | PR4a | US-101 / US-107 验收（首字 / 首工件 / 终态三段 SLA）|
| **PR6** | Approval MCP + Knowledge MCP + AskUserQuestion（含降级到表单的兜底：反问 ≥ 3 次自动 fallback）| US-102 / US-103 跑通 | P0 | PR5 | 三件套 E2E + i18n 双语 |
| **PR7** | SkillRegistry（双源）+ HookRegistry（5 事件）+ Slash Commands（/clear /compact /help）+ **i18n 完整覆盖（zh-CN/en-US）** | skill 触发 / hook 拦截 / `/clear` | P1 | PR5 | US-201 / US-207 |
| **PR8** | Sub-agent（同进程 fork+resume）+ Scratchpad + Task Tracker + **organizationId 强制继承父 session** | agent 派子 agent 跑后台 | P1 | PR4a | US-203 + 跨 org 注入子 agent 必拒 |
| **PR9** | TodoWrite + AgentArtifact 工件库 + 跨会话引用 + **跨 org artifact 引用 evict** | 工件库 UI + 检索 | P1 | PR8 | US-202 + 跨 org 引用测试 |
| **PR10** | Cron Isolated Agent（Temporal worker）+ FailoverError + Credentials Vault（HashiCorp Vault / KMS）+ **离职失效三层防线**：① IAM webhook 监听 user.deactivated 事件 ② 5 分钟巡检兜底（轮询 RBAC 状态）③ **Cron worker 每个 turn 前 inline 校验当前 user RBAC 状态（fail-closed，第三层防线，防 webhook + 巡检都挂）**+ ④ 检测到失效 → Temporal abort 已在跑 worker + Vault 同步吊销 token + cron 配置 disable + TrajectoryEvent 标记代理执行人 ⑤ SLA：失效检测 → cron disable ≤ 5 分钟 + 失效窗口期内的写操作进入"待审计回滚"队列 ⑥ 覆盖未识别场景：用户权限降级（仍在职但失去某 org 访问）/ OAuth grant 用户主动注销 / 配置者已离职无接班人 → 自动 disable + org admin 邮件提醒 | "每天 9 点汇总待审批" | P2 | PR4a | US-204 + 配置者离职后下次 cron 不触发 + 已在跑 worker abort + IAM webhook 失败必须告警（不静默降级）+ 死信队列设计 + LLM provider failover（双家挂时降级到 cache + 用户提示） |
| **PR10.5** | StorageBackend 抽象 + OneDriveAdapter（含 OAuth token vault + refresh + 离职吊销 + **per-user envelope encryption key 派生**：派生输入含 user secret + KMS + per-org salt 三因子，HSM 隔离，KMS root user 也不可单独解）+ **三层 scope binding（含 organization 默认 binding 字段 day-1 落 schema + 最小 admin CLI 兜底，避免 Phase 2 PR14.5 admin UI 上线前 schema 已被读路径依赖出现"幽灵 backend"）** + onboarding/settings UI + File.* 工具家族 + **cross-phase contract review 签字**（Phase 2 PR14.5 owner 必须 review 此 PR schema） | 用户绑 OneDrive，agent 上传文件能在 OneDrive Web 看到 | P2 | PR5 | US-205 + 用户离职 token 自动吊销测试 + KMS root user 单点失陷下用户 token 仍不可解（envelope encryption 三因子派生验证）+ Phase 2 schema 字段反向引用签字 |
| **PR10.6** | ModelRouter 配置 UI（admin 后台 + per-user/project 覆盖）+ Routing Decision Dashboard + **学习反馈机制**（PR3.5 落库的 decision → 分析 → 推规则建议）| admin 能配规则 / 查路由决策 / 看 cost 报告 | P1 | PR3.5 + PR4c | US-206 |
| **PR12.5** | **ai-assistant 收编为 `legacy-qa` skill**（兑现 P6 / Q5 退役）：旧端点保留兼容期 + 历史会话只读迁移（无 organizationId 的旧会话 → 强制只能由原创建者本人查看）+ 流量监控 dashboard + **数据 diff 脚本**（迁移前后 record count + 字段完整性对比）| ai-assistant 用户无感切到 agent；旧 URL 重定向 | **P1（GA 后窗口期，6 个月内退役）**——review 反馈：把"owner 团队签字"绑死在 MVP 启动是政治拖延陷阱；改为 GA 后窗口期处理，PR1 启动只需 ai-assistant owner 团队"知情确认"（不阻塞启动）| 同时 PR4a/PR5 | 0 数据丢失 + 历史会话可回看 + 兼容期结束流量趋零 |
| **PR15.7** | **横切残余**（错误恢复 fixture / 测试 fixture 标准 / 部署拓扑文档）| 见 02-architecture §1.15 | P1 | 全部前置 PR | 各项独立验收 |

---

## 4. UI 与交互（详见 05-ui-interaction-spec.md，待补）

Phase 1 UI 关键约束：

- **双栏布局 + slide-in artifacts 抽屉**（Phase 2 redesign，对齐 ChatGPT 空态 hero + Claude artifacts 风格；参 02-architecture §1.1.3 + §2 顶层架构图 L0）：
  - **左**：会话栏 260px（按时间分组：Today / Past 7d / Past 30d / Older；含 Projects / Memory / Personas disclosure 段）
  - **中**：对话主区（max-w-3xl 居中；裸消息——助手无 border 纯文本 / 用户右侧胶囊 rounded-2xl；composer rounded-3xl shadow + 内置黑色圆形 Send）
  - **右（按需弹出）**：Artifact 抽屉（fixed right slide-in，artifacts.length > 0 自动开；A2UI 渲染表格/图表/表单/diff/file 等）
- **设计系统**：Lark DS（参 `frontend-main` skill）
- **i18n**：默认 zh-CN，必须支持 en-US 切换；MCP 测试每次双语回归
- **流式**：SSE 打字机效果（参 02-architecture §1.2 / 03-impl §2.3）
- **协作模式 UI**：会话级 Plan toggle + Permission mode 5 态选择器（参 02-architecture §1.14）+ **当前态视觉提示**（顶部条 chip 显示当前 mode；切换 / 切换中 / admin 禁用某 mode 各有视觉态）
- **Permission ask 弹窗**：写操作前显示工具 + 参数（脱敏规则见下）+ 用户 allow/deny 按钮 + 键盘可操作（Enter=allow / Esc=deny）+ 屏幕阅读器友好（ARIA dialog + label）
- **参数脱敏规则**（review 反馈：PRD 写"脱敏"必须有规则）：① password / token / secret / api_key 等关键字字段 → 全替换为 `<redacted>` ② 长度 > 200 字符的 string → 截断 + 显示 "...（已截断 N 字符）" ③ 含 `password` 等敏感关键字的 query → 整段 `<redacted>` ④ 用户可点"显示完整"二次确认查看（仍审计落 TrajectoryEvent）

**错误态文案规格**（review 反馈，原 PRD 全空）：

| 场景 | 文案规格 | 后续动作 |
|---|---|---|
| agent 不知道答案 | "我没找到相关信息。你可以试试 [示例 prompt 1] / [示例 prompt 2]，或联系 X 同事" | 推荐 fallback 路径 |
| 跨组织被 INV-1 拦截 | "这个数据属于其他组织，我无法访问。请切换到对应组织 session" | 提供组织切换入口 |
| LLM 全部 down | "暂时连不上 AI 后端（全部 provider 不可用），1 分钟后重试或刷新页面" | 自动重试 + 显式倒计时 |
| 工具超时 | "调用 X 工具超时（>10s）。可能：① 数据量大 ② 后端慢。是否重试？" | retry button |
| Permission deny 后 | "你拒绝了 X 操作。需要我换个方式吗？（例如先生成 plan 给你看）" | 提供 Plan mode 切换 |
| Approval 字段校验失败 | 直接显示后端校验错误（含字段名 + 修改建议）+ 不丢已填字段 | 用户可改后重提 |
| 知识库无答案（空数据态）| "知识库中没有 [关键词] 相关文档。你可以：① 改个问法 ② 联系 [部门] 补充文档" | 引导补全 |
| 用户无权限 | "你没有 [操作] 权限。如需访问请联系 [角色 owner] 申请" | 提供联系入口 |

**a11y 约束**（review 反馈，原 PRD 零提及）：
- Permission ask / 协作模式切换 / 所有按钮：键盘可操作（Tab / Enter / Esc）
- 流式打字机：可在用户设置里关闭（前庭 / 认知障碍用户）
- Display Panel 表格：完整 ARIA（role=table / row / columnheader）+ tab navigation
- 颜色对比度：≥ WCAG AA（4.5:1 正文 / 3:1 大字）

**加载态 / 流式中断态**：
- 首字到达前：skeleton + "思考中..."
- 工具调用：进度条 + "正在查 X..."
- Display Panel 增量推送：partial render（不等全量）
- 用户 cancel：300ms 内停 SSE + UI 回滚 + 显示"已取消"

待补内容（属 05-ui-interaction-spec.md 范围）：
- 高保真稿
- 关键页面 wireframe（首次访问 / 多会话切换 / Permission ask / Display Panel 工件展开 / 协作模式切换 / 错误态各场景）
- 关键交互动效（流式打字、Display Panel 增量推送、Plan mode 折叠 TODO）

---

## 5. 数据模型（详见 02-architecture §5 + 待补 06-data-model.md）

Phase 1 day-1 必备的表（从 02-architecture §5 16 表里挑）：

| 表 | 用途 | Phase |
|---|---|---|
| `AgentSession` | 会话主表（含 planMode/permissionMode 字段）| P1 day-1 |
| `AgentMessage` | 消息历史（含 compactedAt）| P1 day-1 |
| `AgentTask` | 后台任务跟踪 | P1 PR8 |
| `AgentArtifact` | 工件库（用户维度）| P1 PR9 |
| `AgentTrajectoryEvent` | 审计 + debug 事件流（PG REVOKE UPDATE/DELETE）| P1 day-1（INV-3 必备）|
| `AgentScratchpad` | per-session sub-agent 共享 | P1 PR8 |
| `AgentMemory` | per-user + per-org memory（Q14 day-1 落 schema）| P1 day-1 schema |
| `AgentCredential` | 凭据 vault + ref | P1 PR10 |
| `OrganizationProfile` | 组织级 CLAUDE.md/AGENTS.md 缓存 | P1 PR4 |
| `OrganizationAgentSettings` | per-org config（含 defaultPermissionMode / allowedPermissionModes）| P1 PR4.5 |
| `ModelPricing` | per-vendor 价格表 | P1 PR3 |
| `ModelRoutingRule` | 路由规则（org/user/project 三层）| P1 PR3.5 |
| `ModelRoutingDecision` | 路由决策落库（学习反馈源数据）| P1 PR3.5 |
| `StorageBinding` | 用户/项目/组织绑定的 backend | P1 PR10.5 |
| `Hook` | per-org hook 注册 | P1 PR7 |
| `Skill` | DB 双源里的 organization-custom skill | P1 PR7 |

> 全部表 schema 详见 [`02-architecture.md` §5](./02-architecture.md)（待补 06-data-model.md 时直接引用）。

---

## 6. API 契约（详见 02-architecture §1.1.3 + §6 + 待补 07-api.md）

Phase 1 主要 API：

| Endpoint | Method | 用途 | PR |
|---|---|---|---|
| `/api/agent/sessions` | GET | 列出会话（按项目分组） | PR2 |
| `/api/agent/sessions` | POST | 新建会话（指定 organizationId / projectId）| PR2 |
| `/api/agent/sessions/:id` | GET | 取单会话 + 消息历史（含 compactedAt 过滤） | PR2 |
| `/api/agent/sessions/:id` | PATCH | 更新 planMode / permissionMode / title | PR4.5 |
| `/api/agent/sessions/:id` | DELETE | 删除会话（软删，保留审计）| PR2 |
| `/api/agent/messages` | POST | **SSE 流式对话主入口**（输入：session_id + 消息块；输出：SDKMessage 流）| PR3-PR4 |
| `/api/agent/messages/:id/cancel` | POST | 取消正在进行的 turn | PR4 |
| `/api/agent/artifacts` | GET / POST / DELETE | 工件库 CRUD | PR9 |
| `/api/agent/artifacts/:id/preview` | GET | 工件预览 URL（OneDrive Office Online / 缩略图）| PR10.5 |
| `/api/agent/skills` | GET | 列出可用 skills（fs + DB 双源合并）| PR7 |
| `/api/agent/tasks` | GET | 列出后台任务 | PR8 |
| `/api/agent/tasks/:id` | GET | 单任务详情 + 输出引用 | PR8 |
| `/api/agent/storage/bindings` | GET / POST / DELETE | StorageBinding CRUD（三层 scope）| PR10.5 |
| `/api/agent/admin/routing/rules` | GET / POST / PATCH / DELETE | ModelRoutingRule CRUD（admin 限）| PR10.6 |
| `/api/agent/admin/routing/decisions` | GET | Routing Decision Dashboard 数据源（admin 限）| PR10.6 |
| `/api/agent/admin/cost` | GET | Cost 报告（admin 限）| PR10.6 |
| `/api/agent/admin/audit/trajectory` | GET | TrajectoryEvent 钻取（admin 限）| PR4 day-1 |

详细 schema + 错误码 → 待补 07-api.md。SDKMessage 协议详见 [`02-architecture.md` §6](./02-architecture.md)。

---

## 7. 验收标准（按 US 编号）

> 每个 P0 US 一条 BDD 风格"做完算赢"标准。MCP 必须能跑通；i18n 双语都验。

### US-101 验收
```gherkin
Given 我是项目经理（angular @ ffai.com，所属 org 有 50+ 项目，含 8 个延期）
When 我在 /agent 输入 "上季度延期项目按延期天数排序"
Then 5 秒内 Display Panel 出现表格，列：项目名 / 计划完成 / 实际完成 / 延期天数
And 表格按延期天数倒序，仅显示我组织的项目（INV-1）
And 我能点击项目名跳转到 /projects/:id（US-107 联动）
And 切英文 locale 重跑，列名显示英文，数据不变
```

### US-102 验收
```gherkin
Given 我是业务员工，组织已开启差旅审批流
When 我说 "提个去上海三天的差旅审批"
Then agent 通过 AskUserQuestion 反问 "出发日期 / 项目归属 / 预算"
When 我答完
Then agent 在 Display Panel 渲染审批表单预览（type='form'），所有字段已填
And 我点 "确认提交" 调 Approval.submit，5 秒内出审批 ID
And 失败时（如预算超限）agent 给有意义错误并建议下一步（US-208）
```

### US-103 验收
```gherkin
Given 知识库有 "员工报销流程 v3.2" 文档
When 我说 "公司报销流程是什么"
Then 5 秒内 agent 回复包含报销关键步骤（金额阈值 / 审批人 / 时限）
And 引用源链接指向 "员工报销流程 v3.2"
And 切到 en-US 重问 "What is the reimbursement process"，回复也准确（i18n + 知识库多语言索引）
```

### US-104 验收
```gherkin
Given 我有 5 个跨项目的旧会话
When 我访问 /agent
Then 左栏按项目分组列出，无项目归属的归到 "全部会话"
When 我点任一旧会话
Then 中间栏加载完整历史（含 compactedAt 标记的旧消息也能拉到，仅不喂模型）
```

### US-105 验收
```gherkin
Given Permission mode = default（写操作 ask）
When agent 调 Approval.submit
Then 弹窗显示工具名 + 参数（脱敏后）+ allow/deny 按钮
When 我点 deny
Then agent 立即停（不重试），并询问 "需要我换个方式吗"
```

### US-106 验收
```gherkin
Given 我会话默认 Execute mode
When 我点 Plan toggle 切到 Plan mode
Then agent 当前 turn 重启，工具集过滤为 isReadOnly=true 子集
When 我说 "帮我清理过期项目"
Then agent 输出 TODO 列表（"将清理 X / Y / Z 项目，估计影响 N 条数据"），不实际执行
When 我点 "Exit Plan & Execute"
Then 切回 Execute mode，按 TODO 实际执行
```

### US-108 验收
```gherkin
When 我发任意消息
Then 首字延迟 < 1.5s（p50）
And SSE 持续打字机效果，无白屏 / 无停顿 > 2s
And 中途网络断开重连，能 resume（用 lastMessageId）
```

剩余 US 验收待 P1/P2 PR 启动时补。

---

## 8. 测试策略（详见 02-architecture §1.15 + 09-test-scenarios.md 待补）

按 CLAUDE.md 三层测试：

| 层 | 范围 | Phase 1 必做 |
|---|---|---|
| **L0a/L0b** 契约校验 | 静态对比前后端字段 | 每个 PR 必过 |
| **L0c** 响应快照 | 真实请求 vs frontend interface | L2 CI 阶段门禁 |
| **L1** 集成测试 | HTTP → 真实 PG，业务规则 + 权限 + **跨组织隔离**（INV-1）| 每个 PR 必有 + 跨组织专项 |
| **L1c** 数据质量 | 种子数据 JSONB 完整性 + FK | seed 必过 |
| **L2** MCP E2E | accessibility tree 走 P0 US 流程 | 每个 P0 US 必有 + i18n 双语 |
| **L3** 人工验收 | 内测部门按 US 验收清单 | MVP / GA 前各跑一次 |

**LLM 测试 fixture 标准**（02-architecture §1.15 / PR3.5+PR4a 上时确立）：
- LLM 用 MockProvider（确定性输出 + 可重放）—— 用于 L1 集成测试
- **任务完成率 north star 测量必须用 staging 真实 LLM** + 标注集（不能用 mock）—— review 反馈：mock 下任务完成率永远 100%
- 工具用集成测试（PG + 真实 Service）
- A2UI 用 schema snapshot 对比
- TrajectoryEvent 落库可作为回放数据

**跨组织数据泄漏专项测试矩阵**（review 反馈，原 PRD 只有口号；本表必须 traceable 到具体测试文件）：

每个业务工具 PR（PR5/PR6/PR8/PR9/PR10/PR10.5）必须包含以下 L1 集成测试场景：

| # | 场景 | 期望 | 测试文件路径 | Fixture | 责任人 | Cadence |
|---|---|---|---|---|---|---|
| 1 | 用户 A（双 org）切 org-2 session 后 prompt injection 诱导 agent 调出 org-1 数据 | runtime DataScope violation 检测器拦截 + alert | `testing/backend/integration/agent/cross-org-injection.spec.ts` | `seed/cross-org-fixtures.ts`（A in org-1+org-2，B 仅 org-1）| agent 团队 owner | 每 PR + 每日 cron |
| 2 | sub-agent fork 时 organizationId 是否强制继承父 session | 子 agent 工具调用 organizationId 必须 = 父 | `testing/backend/integration/agent/subagent-org-inherit.spec.ts` | 同 #1 | agent 团队 owner | 每 PR |
| 3 | AgentArtifact "用户维度"工件跨组织复用 | 跨 org 引用必拒 + UI 隐藏 | `testing/backend/integration/agent/artifact-cross-org.spec.ts` | seed 含跨 org artifact | agent 团队 owner | 每 PR |
| 4 | ModelRoutingDecision 落库的 prompt/response 跨 org PII 泄漏 | 决策记录脱敏后存储（脱敏规则复用 §4 Permission ask 弹窗规则）| `testing/backend/integration/agent/routing-decision-pii.spec.ts` | PII fixture（10 类典型 PII 样本）| 安全 + agent owner | 每 PR |
| 5 | Cron Isolated Agent organizationId 字段被 prompt 篡改 | Cron 配置时 organizationId 强 bind，runtime 不可改 | `testing/backend/integration/cron/org-immutable.spec.ts` | seed 含恶意 prompt | agent 团队 owner | 每 PR |
| 6 | AgentMemory per-user + per-org 跨 org session 共享 per-user 那部分时的过滤 | 跨 org 时仅注入 per-user 全局 memory，不带 per-org（per-user memory 内容必须 sanitize 不含 org 业务上下文）| `testing/backend/integration/agent/memory-cross-org.spec.ts` | seed 含跨 org memory 写入 | agent 团队 owner | 每 PR |
| 7 | **红队代理指标**：100 个跨组织 prompt injection 样本（NLP 级，不依赖 schema）| 拦截率 = 100%（INV-1 上线前 gate）| `testing/backend/integration/agent/red-team-injection.spec.ts` | 红队 fixture 100 样本（每季度更新）| 安全团队 | 每月 + 每 release |

**安全测试专项套**（review 反馈，原 PRD 只有 happy path L0-L3）：
- IDOR / 未授权 API（每 admin endpoint 必测）
- prompt injection 让 agent 越权调跨 org 工具
- Permission deny 后 agent 重试绕过尝试
- 撤销权限后 sub-agent 仍在跑场景

---

## 9. 上线计划与里程碑

> ❓ 时间窗待 [`01-prd.md`](./01-prd.md) §11 P4 + P5 决策后填入。

| 里程碑 | 时间 | 范围 | 用户 | 退出标准 |
|---|---|---|---|---|
| **M0 内部 Alpha** | ❓ | PR1-PR4.5 跑通"echo + 模式切换" | 内部团队 ~5 人 | 双栏 UI（Phase 2 redesign）+ 流式对话 + Plan/Permission 切换 |
| **M1 MVP 内测** | ❓ | + PR5-PR7 三件套 | 内测部门 ~❓ 人 | §1 MVP 退出指标达标 ≥ 14 天 |
| **M2 GA** | ❓ | + PR8-PR15.7 | 全员可用 | §1 GA 退出指标达标 ≥ 30 天 |
| **M3 ai-assistant 退役** | M2 + 6 个月（建议）| ai-assistant 流量切到 agent | 全员 | 0 新会话进 ai-assistant |

---

## 10. 风险与依赖

**部署架构 + DR / RPO / RTO**（review 反馈，原 PRD 全篇 0 提及；day-1 必须文档化，不延 PR15.7）：

```
┌─────────────────────────────────────────────────────────────┐
│ k8s namespace: ffai-agent                                   │
│ ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│ │ Gateway     │  │ Gateway     │  │ Gateway     │  3 副本   │
│ │ (NestJS)    │  │ (NestJS)    │  │ (NestJS)    │  HPA      │
│ └─────────────┘  └─────────────┘  └─────────────┘           │
│        │                │                │                  │
│        └────────────────┼────────────────┘                  │
│                         ▼                                   │
│   ┌──────────────────────────────────────────┐              │
│   │ Redis Sentinel (3 节点) — per-session lock│              │
│   └──────────────────────────────────────────┘              │
│                         │                                   │
│   ┌──────────────────────────────────────────┐              │
│   │ PG 主备 (1+1 流复制) — Session/Message/  │              │
│   │ Trajectory + 时间×org 二级分区          │              │
│   └──────────────────────────────────────────┘              │
│                         │                                   │
│   ┌─────────────┐  ┌─────────────┐                          │
│   │ Temporal    │  │ Vault       │  Cron + 凭据             │
│   │ worker (2)  │  │ (HA)        │                          │
│   └─────────────┘  └─────────────┘                          │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
            S3 (TrajectoryEvent 归档 + 哈希锚定)
            第三方 TSA（独立时间戳服务）
```

**SLO 目标**：
- **可用性**：99.5%（计划内维护除外）
- **RPO**（数据丢失容忍）：≤ 5 分钟（PG 流复制 + 异步备份）
- **RTO**（服务恢复时间）：≤ 30 分钟（手动 failover）+ ≤ 2 小时（异地灾备）
- **滚动升级**：HPA + 蓝绿；in-flight SSE turn 通过 lastMessageId resume

**灾难恢复演练**：每季度演练一次（PG 主挂 / Redis 集群挂 / Temporal worker 全挂 / 整 region 不可用）

**关键技能盘点**（review 反馈：4 类专家技能未盘点 = 上线风险）：

| 技能 | 用在哪 | 公司现状 | 解决路径 |
|---|---|---|---|
| LLM 路由 / Compaction | PR3.5 / PR4b | 待评估 | 现有团队学习 + 顾问外援 |
| OAuth + Token Vault | PR10 / PR10.5 | 待评估 | 已有后端工程师 + 安全团队配合 |
| OS sandbox（Phase 2 PR13）| Phase 2 | 缺口 | 招聘 / 外部安全顾问 |
| iOS / Android 原生（Phase 3）| Phase 3 | 缺口 | M9 决策前完成招聘可行性评估 |

**Phase 1 特有依赖**：

| 依赖 | 状态 | 缺则影响 | 责任方 | 何时验证 |
|---|---|---|---|---|
| **法务 LLM 数据出境合规评估**（PIPL / CAC）| **强前置（必须先有结论）**——常态 4-12 周，可能否决直连，**PR0.5 启动同时并行启动法务**+ 准备 PR3-alt 国内 LLM 适配 plan B PR 占位 | **PR3 不能启动** | 法务 + 安全 + 平台 | **PR0.5 启动同时并行**（不是 PR3 前才开始）|
| **Service contract audit**（Project / Approval / Knowledge 三个 NestJS Service：方法签名 / 异常结构 / idempotency / DataScope 继承能力）| 待审 | PR5/PR6 实现到一半发现 Service 缺方法被堵 | 业务模块 owner + agent 团队 | **PR5 启动前**（半天工作量）|
| **ai-assistant owner 团队配合**（KPI 重新挂接 + 收编时间表）| 待协调 | PR12.5 政治拖延 | ai-assistant owner + 上级 | **PR1 启动前** |
| Project / Approval / Knowledge NestJS Service 稳定 | 现存 | PR5-PR6 跑不通 | 业务模块 owner | PR5 启动时 |
| LLM provider OpenAI + Anthropic 接通 | day-1 必备 | PR3 跑不通 | 平台 / IT | PR3 启动时 |
| OneDrive Graph API 公司 IT 放通 | PR10.5 前 | OneDrive backend 跑不通 | IT | PR10.5 启动前 |
| **Microsoft Bot Framework 国内可达性 PoC**（Phase 2 PR14 前置，但建议 Phase 1 GA 时就启动调研）| 未评估 | Phase 2 north star 不可达 | IT | **Phase 1 GA 时**（不是 PR14 启动时）|
| Temporal worker 现成（已有）| 现存 | PR10 cron 跑不通 | DevOps | PR10 启动时 |
| Redis（用于 per-session lock）| 现存 | PR4a 多实例部署不安全 | DevOps | PR4a 启动时 |
| **HashiCorp Vault / KMS**（凭据 vault）| 未确认 | PR10 Credentials Vault 跑不通 | DevOps + 安全 | PR10 启动前 |

**Phase 1 特有风险**：见 [`01-prd.md`](./01-prd.md) §8 全模块风险表。Phase 1 重点关注：
- LLM 成本失控（mitigation：PR3.5 ModelRouter day-1 + admin quota）
- 跨组织数据泄漏（mitigation：每个业务工具 PR 必有 L1 跨组织测试）
- 用户预期被外部 AI 拉高（mitigation：MVP 选三件套高价值 + onboarding 引导）

---

## 10.5 实现快照（Implementation Snapshot）

> **截止 2026-05-16，slot-5 session 7 end-of-day**。状态分级：
> - ✅ **DONE** — 代码就位、Playwright MCP 端到端验证、真后端 / 真 LLM 接通
> - 🟨 **PARTIAL** — 主路径可跑，部分子能力为 stub / TODO（行内注明）
> - 🟧 **SKELETON-ONLY** — 接口齐全但实际跑通需外部基础设施（凭证 / 协议）；`isConfigured()` 兜底 false 不影响主流程
> - ⬜ **NOT STARTED** — 计划内但未触
>
> **本快照对应分支**：`feature/agent-pr0.5-monorepo-skeleton`（stacked on PR #388 PRD 分支）。**所有改动尚未 push**，已合并为单个迁移文件 `20260516085046_add_ffai_agent_module`（335 行 SQL，13 张表 + 6 个 enum）。

### 一句话状态

**FFAI Agent 第一阶段功能闭环跑通**——用户登录 `/agent` → 中文 prompt → ModelRouter（rule 或 qwen-turbo LLM-routed 分类）选模型 → qwen-plus 真 LLM 回复 → 命中工具时自动 multi-turn TAOR + tool_use → DevTracker/KnowledgeQA/Approval 真后端被调 → tool result 自动落 Artifact 显示在右栏 → SSE 流式打字 → trajectory 哈希链审计 → quota 自动扣减。

### Phase 1 PR 实施状态

| PR | 状态 | 实际落地（slot-5 session 6+7 累计） | 缺口 |
|---|---|---|---|
| **PR0.5** | ✅ DONE | `packages/agent-protocol`（SDKMessage / HostBridge / A2UI / Provider / 新增 ProviderToolDescriptor + ProviderStreamChunk）+ `packages/agent-renderer-lark`；两包 tsc 通过 | — |
| **PR1** | ✅ DONE | `/agent` UI 骨架 + Onboarding 3 卡 + composer + locale toggle + i18n 完整（zh + en），MCP 验证；Phase 2 已 redesign 为双栏 + slide-in artifacts 抽屉 | — |
| **PR2** | ✅ DONE | AgentSession + AgentMessage schema + REST API + 前端 client。MCP 端到端 | DataScope runtime 检测器、reconciliation 计数器、时间×org 分区仍是后续硬件层强化 |
| **PR0.6** | ⬜ NOT STARTED **（用户决策延后）** | — | Prometheus / Grafana / PagerDuty / feature flag / DR runbook 整块未做；需外部基础设施。**2026-05-16 用户决策：先把功能都实现，运维相关后面再做**——参考 `.learnings/2026-05-16-ffai-agent-ops-deferred.md` |
| **PR3** | ✅ DONE | ProviderRegistry + 4 个 provider：**`QwenProvider`（真接通义千问，国内 LLM 绕开法务出境合规）** + Mock + Anthropic stub + OpenAI stub。MCP 验证 qwen-plus 真回复 + 字符级流式 | Anthropic / OpenAI 真集成等法务合规结论 |
| **PR3.5** | ✅ DONE | 5 信号源 + 3 策略全套：rule-based（DB 规则）+ **LLM-routed strategy B（qwen-turbo 任务分类器）** + scope-override + default。`ModelRoutingRule` / `ModelRoutingDecision` 表 + persist + outcome 回填 actualLatency/actualCost。MCP 验证：rule 命中分流（翻译→qwen-turbo / 推理→qwen-max）+ 禁用 rule 时 LLM-routed 接管返回正确 model | 学习反馈分析 job（PR15.7 优化批） |
| **PR3.6** | ✅ DONE | per-user + per-org 月度 token + cost 预算 + 硬上限 ForbiddenException + 软上限 degrade。messages.service 全链路集成 | admin UI（PR10.6 子项）+ 真 Cost Tracker per-model 单价表（当前 token×$2/M 线性占位） |
| **PR4a** | ✅ DONE | **真 multi-turn TAOR loop**：调 provider → stop_reason 判定 → tool_use 时执行 ToolRegistry tool + 写 TOOL_USE/TOOL_RESULT message + trajectory → 拼 tool_result 回 loopMessages → 再次调 provider → 直到 end_turn（MAX_ITER=5 防死循环）。**SSE 流式 endpoint** `POST /agent/messages/stream`：text/event-stream + fetch ReadableStream consumer + frontend 打字机预览。MCP 验证：qwen tool_calls 返回 → agent 调 project_query → 真 DevTracker 数据 → 整合成自然语言回复 | StreamingToolExecutor 并发（当前串行）+ siblingAbortController 取消传播 |
| **PR4b** | ✅ DONE | Compaction 4 层：**layer 1（budget trim）+ layer 2（tool_result 中间 truncate）+ layer 3（qwen-turbo LLM 摘要老历史，threshold 8000 tokens）+ layer 5（sliding window N 对）**。messages.service 主路径集成；layer 3 等长会话自然触发 | layer 4 pin working set（需 working-set 概念，进 PR15）+ contentReplacementState 跟 trajectory 联动 |
| **PR4c** | 🟨 PARTIAL | AgentTrajectoryEvent + sha256 哈希链 + sequenceInSession 唯一约束 + service + 2 个 API endpoint。messages.service 在 TURN_STARTED / ROUTING_DECIDED / PROVIDER_INVOKED / TOOL_CALL / TOOL_RESULT / TURN_DONE 6 个点写事件。MCP 验证 verifyChain 通过 | **🟧 SKELETON-ONLY 子项**：S3 Object Lock + RFC 3161 TSA 双路锚定（`TrajectoryAnchorService.isConfigured()` 永远 false 等 AWS+TSA）+ retention cron 接 admin trigger + 时间×org 二级分区（schema 未拆） |
| **PR4.5** | ✅ DONE | OrganizationAgentSettings + AgentSession planMode/permissionMode 字段 + 3 控制 tool（EnterPlanMode/ExitPlanMode/SetPermissionMode）+ ToolRegistry mode 过滤（Plan REQUIRED / READ_ONLY 屏蔽 writeAction tool）+ **slash command 集成**（`/plan` `/normal` `/readonly`）。MCP 验证：6 → 5 工具切换 + 403 拦截 + slash 命令工作 | Permission ask 弹窗（ASK_EVERY_TIME mode 前端拦截待加） |
| **PR5** | ✅ DONE | ToolRegistry + AvailabilityExpression（surface + permissions + writeAction + controlTool）+ **listAsProviderTools()** 把 tool 喂给 LLM tool_calls。**8 个内置 tool**：project_query / knowledge_query / approval_submit / EnterPlanMode / ExitPlanMode / SetPermissionMode / **delegate_task** / **file_save** | **🟧 SKELETON-ONLY**：`McpClient` 等 @modelcontextprotocol/sdk + 真 server；FFAI_MCP_ENABLED feature flag 默认 false |
| **PR6** | ✅ DONE | **3 个 day-1 tool 接真后端**：project_query → `ItemsService.findAll`（DevTracker）/ knowledge_query → `KnowledgeQaService.ask`（RAGFlow，slot 无 RAGFlow 配置时错误正确传播）/ approval_submit → `ApprovalService.startApproval`（Approval engine 真启动）。AgentModule 引入 DevtrackerModule + KnowledgeBaseModule + ApprovalModule。MCP 验证 DevTracker 真数据返回 1 条匹配 + 落 Artifact | AskUserQuestion 反问降级 fallback（PR4.5 ASK_EVERY_TIME 上接）|
| **PR7** | ✅ DONE | **Slash Commands**：`/clear`（关旧建新）/ `/help`（弹列表）/ `/plan` / `/normal` / `/readonly` / `/compact`（重拉 session 触发 layer 3）。前端 composer 识别 `/` 拦截不入 LLM 主路径。i18n zh+en 完整 | SkillRegistry / HookRegistry 还是 stub（schema/类未建）—— Phase 1 GA 不阻塞，进 PR15 |
| **PR8** | ✅ DONE | AgentTaskTracker + AgentScratchpad 表 + 双 service。**`delegate_task` tool**：父 agent 调 → 建 TaskTracker PENDING → 创建 child AgentSession → child 跑 runTurn → child Qwen 回复 → TaskTracker COMPLETED + metadata 写 childSessionId/turnId → 返回 reply 给父 agent。MCP 验证："1+1=?" delegate → child 真回 "1+1 等于 2。" | sub-agent 配额隔离（PR10 一起做）+ scratchpad 暴露给 agent 用的工具（PR8b）|
| **PR9** | ✅ DONE | AgentArtifact schema + service + 2 个 API endpoint。messages.service 在 TOOL_RESULT 后 `maybeCreateArtifact()`：检测 output 含 items/projects/results/rows 数组 → 自动 TABLE artifact。前端右栏 ArtifactCard 渲染 max 20 行表格。MCP 验证：project_query 返 1 条 → 自动建 artifact → 右栏 7 列表格 | CHART/FILE/LINK 类型渲染（当前只 TABLE）+ artifact 删除 / 收藏 |
| **PR10** | ⬜ NOT STARTED **（用户决策延后）** | — | Cron Isolated Agent + Temporal worker + 离职失效三层防线 + Credentials Vault；slot Temporal 反复 connect failed，需 Temporal 实例 + IAM webhook 上。**2026-05-16 用户决策：先把功能都实现，运维相关后面再做**——参考 `.learnings/2026-05-16-ffai-agent-ops-deferred.md` |
| **PR10.5** | 🟨 PARTIAL | StorageBinding（3 层 scope）+ StorageFile + `StorageService.resolveBinding/upload/download`。Adapter：`LocalStorageAdapter` 真写 fs（验证 `/tmp/ffai-agent-storage/<orgId>/...`）+ `OneDriveStorageAdapter` skeleton。**`EnvelopeEncryptionService` 三因子 HKDF**（kmsRoot + orgSalt + userSecret → aes-256-gcm）。`file_save` tool MCP 验证 62 字节文件落盘 + sha256 完整 | **🟧 SKELETON-ONLY**：OneDrive 真 OAuth2 + Graph API 上传（需 Azure AD app 注册）+ admin UI 配 binding |
| **PR10.6** | ✅ DONE | `/agent/admin/routing` 前端 dashboard：4 stat card（决策总数/平均延迟/累计成本/活跃 model）+ 按 matchSource bar chart + 按 model bar chart + 最近 100 条决策表（含 reasoning） | rules CRUD admin UI（当前只读，写动作走 SQL/seed）+ 学习反馈页 |
| **PR12.5** | ⬜ NOT STARTED | — | ai-assistant 收编为 legacy-qa skill（PRD 已改为 GA 后窗口期，不阻塞 GA） |
| **PR15.x** | 🟨 PARTIAL | Memory 子项完成（M1 + A + M2 + M3 全部 / 2026-05-18 落地，详见下文）。| 性能优化批 / Skill/Hook 完整体 / Sub-agent 配额隔离 / ai-assistant 退役 / Memory M4 embedding / Memory M5 dreaming |

#### PR15.x Memory 子项（2026-05-18 落地）

| 子项 | 状态 | 范围 |
|---|---|---|
| M1-step1 | ✅ DONE | per-user × GLOBAL 注入 system prompt + 跨 org sanitize（regex 4 条） |
| M1-step2 | ✅ DONE | PROJECT / PERSONA scope 激活（session 加 personaId FK，messages.service 注入 ctx） |
| M1-step3 | ✅ DONE | category 维度（USER/FEEDBACK/PROJECT/REFERENCE）+ 4 章节分组注入 + frontend 4-segment picker |
| M1-step4 | ✅ DONE | ownerScope 维度（USER/ORG）+ admin endpoint（POST/DELETE /agent/admin/memories）+ DB CHECK 约束 |
| A (frontend) | ✅ DONE | MemorySection 改 4-category 折叠分组 + ai-detected / org-shared 角标 + 删按钮仅 USER 可用 |
| M2 (auto-extract) | ✅ DONE | LLM `<remember category="...">` tag 解析 → 写 ai-detected memory + 剥离 tag；单轮 max 3 条 + dedup |
| M3 (容量算法) | ✅ DONE | CC 200 行 / 25KB 双约束截断 + truncated 提示 |
| M4 (相关性 top-K) | ⬜ NOT STARTED | embedding provider 选型未决（BGE / Azure OpenAI / 国内合规） |
| M5 (dreaming 后台整理) | ⬜ NOT STARTED | job 调度框架选型未决（Temporal / cron / Redis queue） |
| Persona picker UI | ✅ DONE | sidebar 已有 picker；建 session 时绑 `activePersonaId` → `session.personaId` 激活 PERSONA-scope memory 注入；切已有 session 的 persona 通过 `PATCH /agent/sessions/:id` 完成 |
| Admin memory 管理页 | ✅ DONE | `/agent/admin/memories` 列 + 加 + 删 org-shared memory，含 category filter + admin 角色三层判定（顶层 roles / per-org / permissions）+ `GET /agent/admin/memories` endpoint |
| PATCH /agent/sessions/:id | ✅ DONE | title / personaId / projectId 改动；跨 org / 非 owner 403；DataScope 走 getSession 校验 |

测试覆盖：28 个 memory-injection 测试（25 注入 + 3 e2e）+ 14 个 memories.api 测试 + 106 总 agent 集成测试全通过。

### 数据模型实际落地（13 张新表）

| Schema 模型 | 状态 | 备注 |
|---|---|---|
| `AgentSession` | ✅ | 含 planMode + permissionMode + surface enum |
| `AgentMessage` | ✅ | 6 种 type 全覆盖（含 TOOL_USE / TOOL_RESULT / A2UI_COMPONENT）+ sequence + payload |
| `AgentTrajectoryEvent` | ✅ | sha256 哈希链 + 唯一序列约束 |
| `AgentArtifact` | ✅ | 5 种 type（TABLE / CHART / FILE / LINK / TEXT），slot 已有真 artifact 数据 |
| `AgentTaskTracker` | ✅ | 状态机表，含父子任务链 |
| `AgentScratchpad` | ✅ | per-session KV，slot 暂无数据 |
| `ModelRoutingRule` | ✅ | 3 条 ORG 规则已 seed（translation/reasoning/long context →Qwen 阶梯） |
| `ModelRoutingDecision` | ✅ | actualLatency/actualCost 全链路回填 |
| `AgentQuota` / `AgentQuotaUsage` | ✅ | 表落地，slot 当前无 quota 行 → 无限通过 |
| `OrganizationAgentSettings` | ✅ | 含 Phase 2 预留字段 |
| `StorageBinding` | ✅ | 三层 scope + 4 种 backend kind |
| `StorageFile` | ✅ | sha256 + externalId + encrypted flag |

### API 实际暴露

| 路由 | 方法 | 状态 |
|---|---|---|
| `/agent/sessions` | GET/POST | ✅ |
| `/agent/sessions/:id` | GET/DELETE | ✅ |
| `/agent/sessions/:id` | PATCH | ⬜ 走 SetPermissionMode tool 替代 |
| `/agent/messages` | POST | ✅ 同步 |
| `/agent/messages/stream` | POST | ✅ **SSE 流式** |
| `/agent/messages/:id/cancel` | POST | ⬜ |
| `/agent/routing/decisions` | GET | ✅ |
| `/agent/trajectory/events` | GET | ✅ |
| `/agent/trajectory/verify/:sessionId` | GET | ✅ |
| `/agent/tools` | GET | ✅ |
| `/agent/tools/:name` | POST | ✅ |
| `/agent/artifacts` | GET | ✅ |
| `/agent/artifacts/:id` | GET | ✅ |
| `/agent/admin/routing`（前端页） | - | ✅ |

### 真后端集成

| Service | 来源 module | 通过工具 |
|---|---|---|
| `ItemsService.findAll` | `@modules/devtracker` | project_query |
| `KnowledgeQaService.ask` | `@modules/knowledge-base/services` | knowledge_query（RAGFlow 未配时错误传播）|
| `ApprovalService.startApproval` | `@engines/approval` | approval_submit |
| 文件系统 | `LocalStorageAdapter` | file_save（`/tmp/ffai-agent-storage/<orgId>/`）|
| Qwen / 阿里云百炼 | `QwenProvider` via openai SDK 兼容 | 所有 provider invoke + invokeStream |

### 接下来该做什么（按依赖排序）

| 优先级 | 项 | 阻塞 |
|---|---|---|
| 🚀 高 | 现在就能 push 这个超大 PR（35+ controllers/services，13 张表，5 个真后端接通，1 真 LLM）+ 等团队 review | 无 |
| 🔧 中 | PR0.6 Ops baseline | 需 Prometheus / Grafana 实例 |
| 🔧 中 | PR4c 真锚定 | 需 AWS S3 Object Lock bucket + TSA 服务 |
| 🔧 中 | PR10.5 OneDrive 真 OAuth | 需 Microsoft Azure AD app 注册 |
| 🔧 中 | PR5 MCP Client 真握手 | 需 `npm i @modelcontextprotocol/sdk` + 真 MCP server |
| 🔧 中 | PR10 Cron Isolated Agent | 需 Temporal 联通（slot 内反复 connect failed）|
| 🟦 低 | PR12.5 ai-assistant 收编 | ai-assistant owner 团队配合 / 政治协调 |

### 如何在新 session 接手

1. **当前位置**：`/home/chentao/Code/ffworkspace-wt/.agent-pool/slot-5`，分支 `feature/agent-pr0.5-monorepo-skeleton`（commit `ca820ef9` PR0.5 + 大量未 commit 改动）
2. **测试入口**：浏览器开 `https://slot-5.chentao.test.jiachentao.com/agent`，账户 `itadmin@ff.com` / `Admin@2024`
3. **运行环境**：backend 已在 4301 跑 + frontend 已在 4300 跑（nodemon/Next dev 都活着）。slot DB 已 sync 到最新 schema
4. **测试数据**：DEV 组织已绑 itadmin（`/learnings` ~`2026-05-16-slot-fresh-db-needs-org-binding` 文件），3 条 ModelRoutingRule + 4 条 DevTracker dev_items 已 seed
5. **改动量**：~80 文件、~7000 行 diff、1 个合并迁移、5 个真 backend service 接通、1 个真 LLM provider 接通、35+ NestJS 类、~10 个新 API endpoint、1 个新 admin frontend 页面
6. **未 commit 文件清单**：`git status` 看（slot 文件未提交）
7. **不要做**：在主仓库直接动；本 session 全部走 slot-5 worktree

---

## 11. 文档版本

| 版本 | 日期 | 变更 | 作者 |
|---|---|---|---|
| v0.1 (骨架) | 2026-05-15 | 章节大纲 + 用户故事候选 | (slot-2 session) |
| v0.2 (架构反推) | 2026-05-15 | 从 02-architecture §8 反推填功能清单 / API / 数据模型 / 验收标准 | (slot-2 session) |
| v0.3 (8 角色 review) | 2026-05-15 | 应用 prd-multi-role-review 8 角色 finding：PR0.5 monorepo 前置 / PR2 收 4 表 / PR4 拆 a/b/c / PR3.6 quota 前置 / PR12.5 ai-assistant 收编新增 / SLA 拆三段 + 测量基线 / Onboarding US-100 / 错误态 + a11y / 跨组织测试矩阵 / Service audit + LLM 合规前置依赖 | (slot-2 session + 8 角色 review) |
| v0.4 (Round 2 review 应用) | 2026-05-16 | 纯重跑 8 角色 dogfood 实验找出 80+ 新 finding。应用 Top P0：首字 SLA 放宽 < 1.2s / US-100 验收数字化 / 新增 US-105b admin 配 mode / PR4c 加两路异质锚定 + 二级分区 / PR10 Cron 离职失效详细机制 / PR10.5 schema 含 org binding day-1 / PR12.5 改 P1 GA 后窗口（解政治阻塞）/ 跨组织测试矩阵 7 项 + traceability 列 / 部署架构图 + DR/RPO/RTO + 关键技能盘点 / 错误态文案 i18n 双语 key | (slot-2 session + 8 角色 round 2 review) |
| v0.5 (Round 3+4 review 应用) | 2026-05-16 | 4 轮 dogfood，R3+R4 真新 ~100 个。应用 PRD 缺漏类：新增 PR0.6 Day-1 Ops Baseline（监控/告警/灰度/runbook 不再延 PR15.7）/ PR2 加 Phase 2 字段预留（surface enum / disabledCapabilities / allowedCliTools / allowedPermissionModes）+ turn-level reconciliation 计数器 / PR10 加第三层防线（cron worker turn 前 inline 校验 fail-closed）/ PR10.5 加 envelope encryption 三因子派生 + cross-phase contract review 签字 / PR12.5 顶层 P6 同步 GA 后窗口期措辞 | (slot-2 session + 8 角色 round 3+4 review) |
| v0.6 (slot-5 实施) | 2026-05-16 | 新增 §10.5 实现快照 —— 反映 slot-5 session 6 实际落地：PR0.5/PR1/PR3/PR3.5/PR4.5 完整 DONE；PR2/PR3.6/PR4a/PR4b/PR4c/PR5 主路径 DONE + 子项缺口（S3/TSA 锚定、MCP Client、真 streaming、layer 3/4 compaction、admin UI 等列入 SKELETON-ONLY / 缺口表）。配套 ~55 文件 / ~3000 行 / 6 个 prisma 迁移 / 6 个新 PG 表 / ~25 个 NestJS 服务 + 控制器 + 工具，全部 Playwright MCP 端到端跑通。**未启动**：PR0.6 Ops baseline / PR6+ 真后端集成 / PR7+ Skills/Hooks/Sub-agent/Storage/Cron 等 | (slot-5 session 6) |
| v0.7 (slot-5 完整迭代) | 2026-05-16 | §10.5 重写为完整 phase-1 落地快照。session 7 增量：**真 Qwen LLM 接通**（国内服务绕开法务合规）+ **真 multi-turn TAOR + tool_use loop**（qwen tool_calls 验证通过）+ **SSE 流式** + **LLM-routed 策略 B**（qwen-turbo 任务分类器）+ **PR4b layer 3 LLM 摘要** + **PR6 三件套接真后端**（DevTracker / KnowledgeQA / Approval Engine）+ **PR7 slash commands**（/clear /plan /readonly /normal /compact /help）+ **PR8 sub-agent**（delegate_task 真 child fork）+ **PR9 AgentArtifact**（auto TABLE 落 + 右栏渲染）+ **PR10.5 LocalStorageBackend**（真文件落盘）+ **PR10.6 admin dashboard**。**7 个迁移合并成 1 个 335 行迁移**（`20260516085046_add_ffai_agent_module`），干净 PG 重放验证通过 → 13 张表 + FK 完整建出。累计 ~80 文件 / ~7000 行 / 5 个真 backend service 接通 / 1 真 LLM provider / ~35 个 NestJS 类 / 10+ API endpoint / 1 admin 页面 | (slot-5 session 7) |
| v0.8 (AI review 修复) | 2026-05-16 | AI pre-push review must-fix 4 项处理完：① `tools.controller.ts` Surface 大小写 bug：加 `normalizeSurfaceLabel()` 在 query/body 入口归一化（'WEB'/'web'/'Web' → 'web'），并新增 06 集成测试用例 `[AGENT-TOOL-002]` 锁口径 ② `.env.example` 补全 13 个 agent env（ANTHROPIC/OPENAI/FFAI_LLM_EGRESS/FFAI_ANCHOR_*/FFAI_MCP_ENABLED/AZURE_*/FFAI_ENVELOPE_KMS_ROOT/FFAI_STORAGE_LOCAL_ROOT/QWEN_MODEL/QWEN_BASE_URL，每个含用途/默认值/缺失症状）③ 新增 `docs/modules/agent/06-data-model.md`（13 张表速查 + 11 个 enum + DataScope 合规 + INV-* 映射）+ `07-api.md`（10+ endpoint 契约 + 鉴权 / 错误码 / 测试入口）④ 新增 `testing/backend/integration/agent/` 3 个 L1 集成测试文件（sessions / tools / trajectory，共 12 个 case，覆盖 happy path + 跨 org 拒绝 + mode 过滤 + 哈希链篡改）。同时 routing/trajectory admin endpoint 加 `@RequirePermissions('system:admin')`（security review fix）| (slot-5 session 7 post-push) |