hs-data/docs/05-agent协作准则.md

# Agent 角色与职责

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

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

修订记录

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

---

1. 项目背景

内部数据平台,MVP 先交付拼团漏斗一个可用模块,其余能力域占位"待开发"。完整需求见 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/。
• 技术：React 19 + Vite + TypeScript + shadcn/ui + Tailwind v4 + ECharts(漏斗图)+ TanStack Query。
• 职责：
  • 平台导航/布局壳,五个 L1 能力域进导航(见 docs/01 §2)。
  • 拼团漏斗模块:时间控件(单日 / 近 7 天 / 近 30 天,单日带历史日历)、ECharts 漏斗图、结果表格、空/错误状态。
  • 其余域:"待开发"占位页(复用同一占位组件)。
  • 前端校验:单日上限昨日、今天/未来不可选(T+1)。
  • 调用后端 POST /api/funnels/query,消费 UV/转化率/流失率/data_status。
• 不碰：后端代码、数据契约的服务端实现。
• 产出：可运行前端 + 组件；契约未就绪时用 mock 响应 对齐字段并行开发。
• 测试：周期选择、单日历史/今天不可选、图表渲染、表格渲染、missing/错误状态。

6. 后端 agent

• 目录：只在 apps/api/。
• 技术：FastAPI + Pydantic v2 + SQLAlchemy(async)。
• 职责：
  • 提供 POST /api/funnels/query。
  • 校验 period(枚举)与 snapshot_dt(仅单日有效、上限昨日、今天/未来拒绝)。
  • 从 PostgreSQL 读预聚合两表(ads_trd_group_funnel_daily / _rolling,见 docs/03 §11):单日取 daily 行、近 7/30 天取 rolling 行的对应列;不读 bitmap、不做 OR、不跨天聚合。
  • 返回每层 UV、相邻转化率/流失率、data_status(ready/missing)。
• 不碰：前端代码、埋点明细存储、数仓侧产出逻辑（只消费 docs/03 约定的表）。
• 产出：可运行 API + 单测；真数据未就绪时基于 seed 假数据 开发(USE_FAKE_DATA 兜底)。
• 测试：period 校验、单日(最新/指定/不存在/今天拒绝)、近 7/30 天取列、转化率(第 1 层 null)、data_status 两态。

7. 契约交接点

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

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

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

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

9. 委派纪律

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