P1：区分人类 / Agent 工时并记录可评估的工作里程碑

[CubePlus1]

P1：区分人类 / Agent 工时并记录可评估的工作里程碑

背景

EchoLog 同时面向人和 AI Agent，但目前 records.source=cli|web|api 只表示写入渠道，不能回答：

• 这段工作是人类完成，还是 Agent 完成？
• 人与 Agent 各投入多久，是否并行？
• 一个阶段完成时具体交付了什么，有哪些 commit / Issue / 测试可以证明？
• 后续遇到同类工作时，应该如何根据历史数据估算工作量？

因此需要把“执行者工时”和“里程碑成果”一起建模。只记录时间不够，只记录完成摘要也无法分析投入。

目标

1. 分别记录 human 与 agent 的有效工作区间，并关联稳定身份与具体会话。
2. 正确表达人机并行、多个 Agent 并行和人机交接，不重复计算墙钟时间。
3. 在阶段性完成时记录“完成了哪些工作”、验证结果和成果证据。
4. 用相似历史里程碑的投入区间辅助后续工作量估算，但不生成单一生产力分数。

调研结论

• OpenTelemetry Traces 将 span 定义为带开始/结束时间的工作单元，span event 用于有意义的单一时间点；适合映射为“工作记录=时段、里程碑=完成事件”。
• OpenTelemetry GenAI 属性 区分 agent identity、conversation/session 与 workflow；近期规范变更 进一步强调 agent ID 应稳定，不应使用临时实例 UUID。
• GitHub Agent Sessions 同时呈现 session length、token usage、执行日志、验证过程，并让 commit 链回 session，说明“时长 + 会话 + 成果证据”应形成一条可审计链。
• SPACE 开发者生产力框架 明确指出活动量和工时不能单独代表生产力，应结合 outcome、质量、协作和 flow；本功能因此只用于个人复盘和估算，不做个人/Agent 排名。

关键语义

source 不等于 actor

• 保留 source=cli|web|api 表示写入渠道。
• 新增 actorType=human|agent|unknown 表示实际执行者。
• actorId 是稳定身份，例如 sc、codex。
• sessionId 是一次具体会话/线程，不与 actorId 混用。
• 一条时间记录只有一种 actor；人机协作由同一根任务下多条可重叠记录表示，不使用含糊的 hybrid。
• 历史数据回填 unknown，不根据 source 猜测。

必须区分的时间指标

• humanActiveSeconds：人类有效区间并集。
• agentAccumulatedSeconds：所有 Agent 各自运行时间之和，表示计算投入。
• agentWallSeconds：全部 Agent 区间并集，表示现实墙钟时间。
• humanAgentOverlapSeconds：人与 Agent 同时工作的交集。
• elapsedSeconds：从最早开始到里程碑完成的端到端历时。

多个 Agent 并行 30 分钟可以是 60 分钟 accumulated、30 分钟 wall；两者必须同时展示，不能只报一个“总工时”。

里程碑模型

里程碑是一等实体，不等同于普通 note，至少包含：

• 标题、完成摘要、完成时间、关联项目与根任务；
• “完成了哪些工作”的结构化条目；
• 验证状态和质量/影响说明；
• 阻塞、返工、交接等补充信息；
• 可选事前估算或规模标签；
• 创建时的人类/Agent/重叠/历时工时快照；
• 证据列表：commit | issue | pr | test | doc | artifact | url。

首版一个里程碑关联一个根任务，并聚合其后代记录；以后若确有需求，再扩展多根任务关联，避免重复计时。

候选数据字段

records 扩展

actor_type   human | agent | unknown
actor_id     nullable stable identity
session_id   nullable session/thread id
initiated_by nullable delegator identity

milestones / milestone_evidence

milestones:
  id, title, summary, project, root_record_id, completed_at
  created_by_actor_type, created_by_actor_id
  verification_status, impact, quality_notes, blockers, rework_notes
  estimate_seconds/size, effort_snapshot

milestone_evidence:
  milestone_id, kind, ref, label, status, metadata

产品范围

API / Core

• records 创建、补录、编辑、过滤支持 actor 字段。
• summary 按 actor 聚合，并计算 accumulated / wall / overlap / elapsed。
• 增加 milestones 与 evidence 的创建、查询接口。
• pause 仍从有效区间扣除；父子任务继续作为里程碑聚合边界。

CLI / Agent

el start "实现缓存" --actor agent --actor-id codex --session <session-id> --parent <root-id>
el log --actor agent
el milestone add --record <root-id> --title "完成缓存层" \
  --summary "完成读写缓存、失效策略和回归测试" \
  --evidence commit:<sha> --evidence test:"pnpm test"
el milestone show <id>

• CLI 人工启动默认 human；API 默认 unknown；Agent 集成必须显式传 actor。
• JSON 输出透传完整 actor、session、milestone 和 effort 数据。

Web / 报告

• 活跃与历史记录显示“人 / Agent / 未知”及 actor 名称。
• 同一任务用双轨时间线展示人类、Agent 和重叠区间。
• 里程碑卡片展示完成事项、证据、验证结果和五种时间指标。
• 日报增加“今日里程碑”和“人机协作投入”。
• 历史估算按项目、标签、任务类型或规模查找相似里程碑，展示 P50/P80 与样本数，不只展示平均值。

隐私与边界

• 默认只记录会话元数据、时长、摘要和成果引用。
• 不默认保存 prompt、模型回复、推理过程或完整工具参数；内容采集必须显式 opt-in。
• 不把 token、工时、提交数或代码行数单独用作生产力评价。
• 不把 Agent 运行时间直接换算为“节省了多少人类时间”。

建议拆分

• 子任务 A：数据迁移、actor 契约、区间聚合与 API
• 子任务 B：CLI actor 参数、Agent session 接入与 JSON 契约
• 子任务 C：里程碑与 evidence 的 Core/API/CLI
• 子任务 D：Web 双轨可视化、日报和历史估算

验收标准

• 同一根任务下 human 与 agent 记录可并行存在并正确归因。
• source 与 actor 独立，历史记录迁移为 unknown。
• 五种时间指标在暂停、多 Agent 并行、人机重叠场景下计算正确。
• 可记录“完成了哪些工作”、验证结果及 commit/Issue/测试等证据。
• 里程碑可回溯关联记录及创建时的工时快照。
• API、CLI、Web、日报均支持 actor 与 milestone。
• 可按相似历史里程碑给出工作量区间，并显示样本数与指标边界。
• 默认不持久化敏感的 Agent 会话内容。
• migration、domain、route、CLI JSON 和 Web 关键行为测试通过。

实施顺序

优先完成 actor 数据契约和时间算法，再实现里程碑，最后接 Web 与估算。开始开发前将本 Issue 拆成可独立验收的 Trellis/GitHub 子任务。