FDS-21 · B12 周期复盘

不再让"开完会就散、做没做没人追"靠人记。系统每周/每月自己回看这段时间项目里发生了什么:做成了什么、哪几件跑偏了、下阶段该盯哪里;并算一个硬指标——改进项完成率(已经确认过的待办里"完成"的占多少),太低就报警;一份复盘报告可以回写进项目知识库,管理层打开就能一眼看出这个项目是健康还是失控。全部在站内,不接任何外部工具。

1. 业务说明

• 是什么:一个按时间周期(默认每周一次,可配每月一次)自动跑的任务。它只读项目事实库(B8,见 FDS-17)里这一周期的数据——这周期内开了哪些会、新产生和已确认的待办、风险、决策、里程碑——交给一个"复盘技能"写成一份人看得懂的复盘报告,报告里有一段叙述(做成了什么 / 哪些跑偏 / 下阶段聚焦)和一组硬数字(其中最关键的是改进项完成率)。
• "周期复盘"是什么:管理学里 PDCA(计划-执行-检查-改进,一个持续改进的循环)里的"检查 + 改进"那一环。传统做法是开完会没人回头看上次说要做的事到底做没做;这一章就是把"回头看"这件事定时自动做掉,而且看的是已经核实过的事实,不是重新去啃一遍录音(那样又慢又对不上)。
• 改进项完成率是什么:一个口径写死的硬指标。分母 = 这个项目里所有已经被人确认过的待办(状态在事实库里是"已确认/confirmed",由 B9 待办管理维护,见 FDS-18);分子 = 这些待办里状态为"完成/done"的条数。完成率 = 分子 ÷ 分母。低于一半(50%)就报警——给项目经理一条站内提醒,意思是"这个项目执行在掉链子,该看了"。它由代码按口径算,不让模型估,因为这是要给管理层看、要据此报警的数,算错一次就误导决策。
• 给谁、解决什么:
  • 项目经理:不用自己每周翻聊天记录手工汇总"上周说的事做了几件",系统按周期把账算清、把跑偏的点列出来。
  • 管理层:打开项目就有一份"健康度一眼清"的复盘——绿/黄/红 + 完成率 + 跑偏清单,不必逐个项目盘问。
  • 项目本身:复盘结论可回写进项目知识库,下次开会的开场材料(B11,见 FDS-20)能直接引用"上周期复盘指出 X 没做、Y 跑偏",闭环不断。
• 不做会怎样:就是现在的样子——开完会没人系统性回看,跑偏的事拖到爆雷才发现;偶尔有人手工写的总结口径各人各样、不可比、管理层不敢拿来做判断(详见 §9 现状,这正是"无可信复盘"的由来)。

2. 用户操作与界面

周期复盘不需要谁手动触发(到点自动跑),用户主要是"看"和少量"配":

1. 项目经理 / 管理员在项目设置里配周期:每周(默认,选周几)或每月(选每月几号);可临时点"现在生成一次本周期复盘"(手动补跑,不改周期节奏)。
2. 到点后系统自动跑完,在项目工作台出现一张复盘卡片:周期(如"2026 第 21 周")、健康度色块(绿/黄/红)、改进项完成率(如"6/14 = 43%"且标红)、三段式摘要(做成了什么 / 哪些跑偏 / 下阶段聚焦)、一个「看依据」链接(点开能看到每条结论是从事实库哪些事实、哪场会来的,可继续点回原文,沿用 B8 的 trace 能力)。
3. 完成率低于 50% → 系统发一条站内消息提醒给项目经理(不接飞书/企微/邮件,全局约束〇):"项目 X 第 21 周改进项完成率 43%,低于阈值,请查看复盘"。点提醒直达这张复盘卡片。
4. 管理层在项目列表/驾驶舱看到每个项目最近一期的健康度色块与完成率,点进去看完整复盘报告;无需逐个项目追问负责人。
5. 项目经理可对这份报告点**「回写项目知识库」**(可关,见 §3):把这期复盘存进项目知识库,成为下次开场材料(B11)和后续周期可引用的历史;也可点「不准确,标记」对某段叙述提异议(异议进留痕,不改已发数字)。

3. 数据与接口(字段级)

复盘不新建一套"真相",它的输入全来自事实库(B8);它只新增"复盘报告"这一种产物的存储与触发记录。

复盘报告表 project_retro_reports(一条 = 一个项目一个周期的一份复盘):

字段	类型	说明
id	uuid PK	复盘报告唯一 id
project_id	uuid, 索引	所属项目(隔离边界,所有查询强制带,沿用现有权限校验)
period_kind	enum	weekly / monthly(周期粒度)
period_start / period_end	ts	本期时间窗(左闭右开;取数与算指标都以它为界)
metrics	jsonb	硬数字:{confirmed_total, done_count, completion_rate, overdue_count, new_decisions, new_risks, meetings_count} —— 全部由代码算
completion_rate	float	改进项完成率(从 metrics 提升为独立列,便于排序/驾驶舱直接读)
health	enum	green / yellow / red(由完成率 + 跑偏数按固定档位映射,见 §4)
narrative	jsonb	复盘技能产出的三段式叙述:{achieved, drifted, focus_next},每段含引用的事实 id 列表(可 trace)
evidence_refs	jsonb	本期纳入计算/叙述的事实 id 集合(报告可"看依据"的来源,锁定快照)
status	enum	generated(已生成) / kb_synced(已回写知识库) / dismissed(被标记无效)
alerted	bool	是否已因低于阈值发过站内提醒(防重复打扰)
generated_by	enum	scheduler(定时自动) / manual(人工补跑)
skill_version	text	产出叙述时的复盘技能版本(口径/叙述演进与回退依据,对齐 FDS-04)
created_at / updated_at / deleted_at	ts	deleted_at 非空=软删(可逆,沿用项目可逆存储)

辅助:project_retro_anomalies(对某段叙述的人工异议留痕:谁、何时、异议内容,不回改已发数字)。 索引:(project_id, period_kind, period_end) 唯一(同项目同周期不重复生成)、(project_id, health)(驾驶舱按健康度筛)、completion_rate(排序找最差项目)。

接口(acdm-backend 提供;技能经工具接口取数与回交叙述,不直连库——对齐 FDS-04 §5):

• POST /retro/run:对某 project_id + 周期生成复盘。代码侧:① 按 period 窗口从事实库 GET /facts/query 拉本期数据;② 算 metrics 与 completion_rate、定 health;③ 调复盘技能产出 narrative;④ 写入 project_retro_reports;⑤ 完成率低于阈值则发站内提醒。幂等:同项目同周期已存在则更新而非重复建(generated_by=manual 补跑允许覆盖叙述,数字按当下事实重算)。
• GET /retro/query:按 project_id(+ period_kind / 时间范围)查复盘列表;驾驶舱按 health/completion_rate 排序。
• GET /retro/{id}:取一份复盘全文(含 narrative 与 evidence_refs);前端"看依据"据 evidence_refs 调 GET /facts/{id}/trace 回原文。
• POST /retro/{id}/sync-kb:把这份复盘回写项目知识库(见 §4 第 5 步);记 status=kb_synced。可关:项目设置 retro_kb_sync_enabled=false 时该接口拒绝(默认开)。
• POST /retro/{id}/dismiss …/anomaly:标记整份无效 / 对某段叙述提异议(进 project_retro_anomalies 留痕,不改已发数字)。

取数接口与完成率计算口径属"算错会误导决策"——按 FDS-04 §2 判据全部在代码侧;技能只拿到代码已取好的本期数据快照,负责"写成人看得懂的话"。

4. 技术实现(分步)

1. 定时触发(用现有定时机制,不新造调度器):复用 acdm-backend 已经在生产跑的后台定时任务范式——应用启动时 lifespan 起一个常驻 asyncio 后台任务(现有 ba_report 同步调度器就是这套:run_sync_scheduler 在 main.py 的 lifespan 里 asyncio.create_task 拉起、退出时 cancel)。复盘调度器同样挂进去:按节拍轮询"哪些项目到了周期点且本期还没生成",命中即对该项目调 POST /retro/run。为什么这样:周期级低频任务不需要引入新的调度中间件;沿用已验证、已被运维认识的机制,少一个会半夜出事的新组件。
2. 圈定周期窗口:按项目配置(weekly:对齐到周几;monthly:对齐到每月某日)算出 [period_start, period_end) 左闭右开窗口。窗口一旦定下,这一期取数与算数都以它为界,保证可复算、不同期不交叠。
3. 只读取数(不重啃录音):用 project_id + 窗口调事实库 GET /facts/query,拉本期:已确认待办(算完成率分母)、其中完成的(分子)、超期的、新决策/新风险/里程碑、本期会议数。全部来自已核实事实——这是"快又准又可追溯"的根:不重新分析任何录音/纪要,事实库强一致(刚写完即可查,见 FDS-17 §4)保证拿到的是最新真相。
4. 代码算硬指标(口径写死):
   • completion_rate = done_count / confirmed_total(分母为 0 时记 null 并在卡片显示"本期无已确认待办,不计完成率",不报警也不算红——没有待办不等于执行差)。
   • health 固定档位映射:完成率 ≥ 0.7 且无超期 → green;0.5 ≤ 完成率 < 0.7 或有少量超期 → yellow;完成率 < 0.5 → red。档位是写死的代码常量,不让模型定。
   • 低于 0.5 且本期 alerted=false → 发一条站内提醒给项目经理,置 alerted=true(同期不重复打扰)。
5. 复盘技能写叙述:把代码已取好的本期数据快照(只读、已脱去库细节)交给复盘技能,产出三段:做成了什么(本期完成的待办、关闭的风险、达成的里程碑)、哪些跑偏(超期未做、反复出现的同一阻塞、范围漂移、与上期决策相悖之处)、下阶段聚焦(基于未完成项与新风险给出 3-5 条聚焦建议)。每段须引用具体事实 id(进 narrative 与 evidence_refs),保证"每句话有据可查";技能不碰那些硬数字(数字代码已算好直接填),它只负责把事实组织成人能读的复盘话语。
6. 写入与回写:报告写入 project_retro_reports(一次事务)。项目经理点「回写知识库」时,经 POST /retro/{id}/sync-kb 把这份复盘作为一条项目知识沉淀进项目知识库(沿用项目现有知识库存储),供 B11 下次开场材料引用、供后续周期对比"上期说要聚焦的这次做到没"。回写可关(项目设置开关),默认开;不接任何外部系统,纯站内。
7. 可逆与留痕:复盘报告软删进回收站可恢复;人对叙述的异议进 project_retro_anomalies 留痕但不回改已发数字(数字以生成时事实快照为准,要更新则按当下事实重算并升一版,不静默改历史)。

5. 技能 or 代码

按 FDS-04 §2 判据("错了会算错数据/出假结论的 → 代码;换种说法/换套规则的 → 技能"):

必须是技能(叙述与口径表达会变、靠判断)	必须是代码(正确性不容漂移)
复盘叙述:做成了什么 / 哪些跑偏 / 下阶段聚焦怎么措辞、详略、聚焦建议怎么提	改进项完成率计算(分子分母口径、零分母处理)
"什么算跑偏""聚焦建议给几条"这类业务判断规则	定时调度(何时触发、周期窗口圈定、幂等)
报告整体话术风格(给管理层看的口吻)	只读事实库取数(按项目隔离、强一致、窗口边界)
	健康度档位映射、低于阈值站内报警、回写知识库写动作

边界一句:复盘技能只写"话",不碰"数"。给管理层报警的那个完成率、健康度色块,以及"到点取哪段数据"全是代码硬规矩;技能拿到代码备好的本期事实,负责把它组织成人看得懂、可追溯的复盘叙述。复盘技能必带 eval 样例、改动走自动测试 + 人审(FDS-04 三条不让步)。

6. 二开归类

🟢 复用 deer-flow(直接用) · 🟡 基于 deer-flow(扩展位上做,不动内核) · 🔴 从头自建(acdm-backend 写)

• 🟡 复盘叙述做成技能 + 复用现有定时机制:复盘叙述是一个新增业务原子技能,挂技能目录、跑在 deer-flow 引擎上(对齐 FDS-04 文件结构与版本评审);触发不另造调度器,复用 acdm-backend 已在生产运行的后台定时任务范式(现有 ba_report 同步调度器:lifespan 起常驻 asyncio 任务、轮询到点项目),只是多挂一个"周期复盘"轮询逻辑。
• 🔴 取数与完成率自建:按周期窗口只读事实库取数、改进项完成率口径计算、健康度档位映射、低于阈值站内报警、复盘报告表与回写知识库——deer-flow 没有这类"项目级、口径精确、要据此报警"的能力,全在 acdm-backend 从头写。
• 为什么不复用 deer-flow 自带"记忆/摘要"做复盘:它把对话摘成一段 blob,不能按周期窗口精确取数、不能算口径写死的完成率、写完要等异步不能强一致地拿到本期最新真相(FDS-17 §6 已确认其不胜任)——给管理层报警的数字必须自建、必须代码算。

7. 与人机协同模型关系

• 任务流:周期复盘是一条由"时间"而非"用户点击"触发的自动任务流——定时器到点 → 取数(代码)→ 叙述(技能,AI 管"怎么说")→ 算数报警(代码)→ 落报告。AI 只管叙述这一内层节点,边界外的取数/算指标/报警全是代码,符合"任务流可审阅、AI 与人共写、不让 AI 碰正确性硬规矩"。
• 任务卡片:复盘报告以卡片形态落在项目工作台,人可查看、可对叙述提异议(进留痕)、可点回原文看依据——符合"AI 产出默认可审、人能否决但不破坏可追溯"。
• 项目工作台(项目级账):复盘只读事实库(模型里的"项目级单一真相"),回写知识库后又成为项目级上下文的一部分,供下次开场(B11)引用——闭环就是绕着这个"单一真相"转,杜绝复盘自己另搞一套对不上的数据。

8. 验收(可证伪)

• 可用:某项目配周到点后,系统自动生成一份本周期复盘卡片,含三段叙述 + 改进项完成率 + 健康度色块;不依赖任何人手动触发。
• 可用:改进项完成率 = 该项目本期"已确认待办中完成数 ÷ 已确认待办总数",手工按事实库数据核算与系统显示一致;构造一个完成率 43%(< 50%)的项目,系统自动给项目经理发出且仅发一条站内提醒。
• 可用:本期无已确认待办时,卡片显示"不计完成率"且不报警、不判红(不把"没有待办"误判成"执行差")。
• 好用:复盘叙述每条结论可点「看依据」回到事实库对应事实并 trace 回原文;随机抽 10 条叙述结论,与事实库该期事实一致、无技能臆造的事实。
• 好用:点「回写知识库」后,下一场会议的开场材料(B11)能引用到这期复盘的"未完成项 / 下阶段聚焦";关闭回写开关后该动作被拒。
• 可逆:软删的复盘报告可从回收站恢复;对叙述提的异议进留痕但已发完成率/健康度数字不被静默改写。

9. 现状

没有。当前无可信复盘:系统不会按周期自动回看;偶有的人工总结口径各人各样、不可比、来源不可追溯,管理层不据此决策,产品里也不据此报警。换句话说,现在产出的那类报告不可信、不算数——本章即从零建一套"只读已核实事实、口径写死、可追溯、能据此报警并回写知识库"的周期复盘,把"检查 + 改进"这一环真正自动闭上。

10. 风险与取舍

• 风险:完成率口径有歧义(算不算被作废的待办、跨会归并后算一条还是多条)→ 数字不可信。取舍:口径写死在代码并文档化——只统计事实库里 status=confirmed 的待办,作废(dropped)不计分母,跨会归并后按归并结果算一条(归并由 B9/FDS-19 维护,复盘只读其结果),不让任何技能改口径。
• 风险:阈值"低于一半报警"在小项目(本期就一两条待办)上误伤,频繁打扰。取舍:零分母不报警不判红;小样本(已确认待办少于约定下限)报告里标"样本小,完成率仅供参考",报警仍以阈值为准但措辞提示样本量。
• 风险:复盘技能把跑偏说重了/漏了关键跑偏,管理层被误导。取舍:跑偏的硬证据(超期数、反复阻塞)由代码从事实库算出后钉进数字区;技能只在叙述区组织语言,且每条须挂事实 id 可追溯,人可标异议;技能必带 eval 样例 + 改动走人审(FDS-04)。
• 风险:回写知识库污染项目知识(每周一份堆积、或把不准的复盘写进去被 B11 反复引用)。取舍:回写默认开但可关、人工点击触发(不自动回写)、被 dismiss 的报告不进知识库;每期一条、带周期标识,B11 引用时只取最近一期。
• 风险:定时任务在生产半夜出错没人知道(复盘静默不生成)。取舍:复用已被运维认识的现有定时机制(同 ba_report 调度器路径),失败有日志、下个节拍可补跑、支持人工 POST /retro/run 兜底;不引入新调度组件以免多一个无人值守的故障点。

周期复盘完成。它与 B11 下次开场(FDS-20)合起来即原始需求的 PDCA"检查 + 改进"闭环:复盘只读事实库算账与叙述,回写知识库后喂给下次开场,循环不断。