---
name: progress-artifacts
description: 交付期第 12 步，向人汇报：用架构图、UML、可增量更新的快速 demo 等用完即弃的汇报件讲一段时间的关键进展与架构层面的前后差别，放系统临时目录下本会话本程的子目录。每次顶层回看之后、切片收口之后，或人说「汇报一下」「给我看看进展」时加载。人还在逐步看着时不加载。
---

# 进展汇报件

人把注意力移开之后，靠汇报件把控进度、健康度并快速反馈。汇报件的目的不是留档，是让人的注意力停在架构、产品、交互体验三个层面，不下到技术与代码细节。

汇报讲的是思维模型 `think-ought-vs-is` 里的差异：和之前比变了什么，和目标比还缺什么。

## 什么时候出

- 每次顶层回看之后，有变化就出一份。
- 每个切片收口之后。
- 一程交付时出最后一份，连同交付声明。

没有变化时不出。空汇报比没汇报更坏。

## 三种形式

| 形式 | 讲什么 | 怎么做 |
| --- | --- | --- |
| 架构图与 UML | 实现在架构层面长什么样，和之前比有什么区别，还缺什么 | Mermaid，前后对照两张图或一张图标出新增与改动。至多六个框，每框至多八个词。只在图能降低理解难度时画 |
| 快速 demo | 重要的产品功能让人直接上手 | 单文件 HTML，可增量更新：用 [`scripts/demo-append.mjs`](scripts/demo-append.mjs) 从[骨架](demo-skeleton.html)创建，每个切片追加一段，同一切片号再追加时替换，不重写整页。片段怎么做加载技能 `mattpocock-skills:prototype` |
| 进展文档 | 变了什么、还缺什么、待人决定什么 | 网页版用 [`scripts/build-report.mjs`](scripts/build-report.mjs) 从 plan 的进度总览、读数 JSON、前后 Mermaid 与待决事项生成单文件 HTML（模板 [`report-template.html`](report-template.html)，带暗色适配）；只要 Markdown 时按[汇报件骨架](report-skeleton.md)写 |

## 讲法

用追进度的讲法，加载技能 `pstack:ketchup`：说变化，不说过程；说「测试过了」，不说「门禁绿了」；不写哈希、路径、命令、测试数，除非人要据此做决定。开头一句话说有什么等人决定，没有就说没有。待人决定的每一项给出自己的建议、依据和风险。不编造决定来填篇幅。

汇报件是代理交给人的一次转手，人读得完、验得完的才算交到了。转手会丢信息，回路越紧越稳，一块多大由接的一方验得完多少定。做法加载技能 `think-closed-loop`。

## 没验收的库存

每份汇报件都有一栏「没验收的库存」：代理做出来、人还没上手验过的行为，每样写人怎么验、要几分钟、证据在哪，末尾写合计与人的验收窗口。它看着是进度，其实是风险，人据此决定回来先验什么。每一程都有这一栏，不因为人越过了哪条提醒而多写或少写。Markdown 版照[汇报件骨架](report-skeleton.md)写；网页生成脚本不出这一栏，要它时另附一份按骨架写的 Markdown。看到人这一侧的风险就说一次：提醒、依据、建议、选择。做法加载技能 `candid-friend`。

## 晨间交付

人交了夜间一程、早上回来看的那一份汇报件，三条规矩：

1. 第一行写有什么等人决定，没有就说没有。
2. 每样交付写怎么上手验、要几分钟、证据在哪，就是「没验收的库存」那一栏。
3. 没做的、跳过的、停在最后一步之前等人授权的，逐条明说。不写「全部完成」。

## 放在哪

统一放操作系统临时目录，各操作系统一致，借用系统的定期清理：

```
<系统临时目录>/pqw-skills/<会话标识>/<一程标识>/artifacts/
```

路径由 [`scripts/artifacts-dir.mjs`](scripts/artifacts-dir.mjs) 解析并创建，系统临时目录按 Node 的 `os.tmpdir()` 取值：Linux 与 macOS 通常是 `$TMPDIR` 或 `/tmp`，Windows 是 `%TEMP%`。会话标识从宿主环境变量取，取不到时由调用方传。汇报件不进仓库，不进项目 tmp。

要人看时直接在 IDE 打开，不只给路径。

## 清理

用完即弃。切片交付和一程交付后的清理归 `cleanup`，加载它。要长期留的事实写进正式文档，不靠保留汇报件。