05-agent协作准则.md 4.6 KB
# 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 读取
byteabitmap；自定义范围对 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 返回后，主会话核对产出是否落在边界内、是否满足验证点，再决定集成。