tianyu.chu/hs-data - Gogs

# 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 返回后，主会话核对产出是否落在边界内、是否满足验证点，再决定集成。