# Agent 角色与职责

> 描述 AI agent 在本项目里的角色定位与职责边界。协作进度由人把控，本文不立工作流规矩。
> 本文由原 05（协作准则，已砍掉技术栈/铁律/CI/工作流）与原 06（subagent 角色分工）合并而来。

| 项 | 内容 |
|----|------|
| 文档版本 | v1.0 |
| 文档状态 | 待评审 |
| 更新日期 | 2026-06-21 |

## 修订记录

| 版本 | 日期 | 修订内容 |
|------|------|----------|
| v1.0 | 2026-06-21 | 初版：合并原 05 与 06 |

---

## 1. 项目背景

内部数据服务平台，MVP 先交付泛用 UV 漏斗一个可用模块，其余能力域占位"待开发"。完整需求见 `docs/01-产品需求`。

## 2. 角色模型

- **主会话（orchestrator，人主导）**：拆任务、定契约、做集成与评审，是协作的把控者。
- **AI agent（实现执行者）**：接受需求与方案，产出代码、文档、SQL 等具体产物。

具体实现按目录边界委派给两个 **subagent**：**前端 agent**（在 `apps/web/`）、**后端 agent**（在 `apps/api/`）。按目录分两个 subagent，各自上下文干净、互不越界，主会话只在契约与集成处介入。

## 3. Agent 总体职责范围

- 按既定的产品需求（`docs/01`）、技术架构（`docs/02`）、数据契约（`docs/03`）、设计规范（`docs/04`）做实现。
- **导航信息架构(模块与层级,L1/L2/L3)以 `docs/01` §2 为准**;视觉/交互定稿以 `docs/04` 为准。
- 跟随既定技术栈，不擅自更换；新增依赖前先与人确认。
- 不清楚的事实以代码与 `docs/` 为准，查不到先问，不臆测。
- 严格的"做"与"不做"边界以 `docs/01` §7"明确不做"为准。

## 4. Agent 不负责

- **不负责协作进度安排、需求决策、架构定型** —— 由人（主会话）把控。
- 不擅自扩大需求范围、不"顺手优化"周边、不替假想场景写防御性代码。
- 不替用户拍板未决议事项（鉴权方案、事件清单等），见 `docs/01` §10。

## 5. 前端 agent

- **目录**：只在 `apps/web/`。
- **职责**：
  - 平台导航/布局壳，五大能力域全部进入导航。
  - 漏斗模块：时间选择区、漏斗配置区、结果图表区（ECharts 漏斗图）、结果表格区、空/错误状态。
  - 其余四域："待开发"占位页。
  - 前端校验：自定义范围最大 15 天、今天不可选/不可提交。
  - 调用后端 `POST /api/funnels/query`，消费 UV/转化率/流失率/数据状态。
- **不碰**：bitmap 字节解析与计算、后端代码、数据契约的服务端实现。
- **产出**：可运行前端 + 组件；契约未就绪时用 **mock 响应** 对齐字段并行开发。
- **测试**：快捷时间选择、15 天限制、今天不可提交、图表渲染、表格渲染、空/错误状态。

## 6. 后端 agent

- **目录**：只在 `apps/api/`。
- **职责**：
  - 提供 `POST /api/funnels/query`。
  - 校验时间范围与漏斗步骤参数（15 天上限、今天不可查）。
  - 从 PostgreSQL 读取 `bytea` bitmap；自定义范围对 daily bitmap 做 OR 后取 cardinality；标准周期优先读 period 表。
  - 返回每层 UV、转化率、流失率、数据状态。
  - bitmap 的 CPU 计算不阻塞 async event loop（放线程/进程池）。
- **不碰**：前端代码、埋点明细存储、数仓侧产出逻辑（只消费 `docs/03` 约定的表）。
- **产出**：可运行 API + 单测；真数据未就绪时基于 **seed 假数据** 开发。
- **测试**：单日/多日/标准周期/空 bitmap/缺失数据查询、重复用户只计一次、多步骤 UV 与转化率计算。

## 7. 契约交接点

两角色唯一耦合在接口契约：

- **唯一来源**：`docs/02-技术架构` §5 的请求/响应字段。
- **并行机制**：前端按契约 mock、后端按契约 + seed 实现，各自先跑通，再联调。
- **改契约协议**：任一侧需要改字段，先改 `docs/02` 并同步对端，不在代码里单方面偏离。
- **数据状态**：`ready`/`partial`/`missing`/`invalid` 由后端判定并返回，前端按状态渲染，**两侧都不静默补零**。

## 8. 主会话职责（不下放给 agent）

- 任务拆分与排期、契约定义与变更裁决。
- 跨端集成与联调、端到端验收（对照 `docs/01` §8）。
- 代码评审、依赖增减裁决（新依赖按 `docs/02` §1 技术栈把关）。

## 9. 委派纪律

- 一个 subagent 只在自己的目录内改动；跨目录需求回主会话重新拆分。
- 委派任务时带齐：目标、相关契约/文档、验证点。
- subagent 返回后，主会话核对产出是否落在边界内、是否满足验证点，再决定集成。