0026 本机的需求索引、使用记录和 req api
背景
1.9 要做两件依赖同一份数据的事：Paseo 插件在网页端列出本机所有项目的需求、做确认和停止这类管理操作；管理方要定期看到 req-kit 的使用情况（多少需求、多快、返工多少、花了多少）。在此之前，需求的状态分散在各仓库各工作区的功能目录里，req list 只看得到当前仓库；用时和用量只在每个需求的状态文件中，没有跨需求的汇总；req list、req status 只输出给人看的文字，程序要用只能解析文字或直接读状态文件，后者把状态文件的内部格式变成了对外约定。
决定
- 需求索引：引擎每次写状态文件时，确认本机配置目录下的
index/<key>.json记着这个需求在哪里（目录、功能目录、对话所在目录、工作区），一个需求一个文件，几个流水线同时运行也不会互相覆盖。索引只记位置，阶段和进度仍然现场从功能目录读取，所以不会和实际情况不一致。 - 使用记录：每次运行（后台进程从开始到结束）结束时向
usage/runs.jsonl追加一行：步骤、用时、用量、质量门、结束时的状态。按运行而不是按需求记，追加即可，不用改写旧记录；需求层面的数字（交付周期、评审轮数、等待时长）在统计时从同一需求的各次运行算出。 - 只在本机，不自动上报：两样都不提交进仓库，也不发往任何地方；不记需求内容和代码。汇总给管理方时由人导出（
req stats --export）再合并（--merge）；之后定下汇总通道时，用 1.9 的集成模块订阅"运行结束"，数据格式不变。 req stats：Markdown 汇总、JSON、每个需求一行的 CSV，--report生成汇报用的两份文件。req api：给程序的稳定接口，一行 JSON，带schema。读操作（list、status、file、stats、index）不改变任何东西；管理操作req api run <approve|stop|resume|verify>就是在相应目录执行req <命令>，引擎仍是唯一修改状态的一方。file只能读功能目录中的文档白名单。- 评估和测试不进记录：
REQ_KIT_NO_RECORD=1关闭记录，评估运行设置它；测试把本机配置目录指向临时目录。
影响
- 插件和脚本只依赖
contracts/cli-json.md，状态文件的内部格式可以继续演进。 - 1.9 之前运行过的需求不在索引里，需要
req index --rebuild补登；删掉的目录在索引里显示为"已移除"，--prune清理。 - 记录是尽力而为的：写失败不影响流水线，被强制结束（kill -9、断电）的运行没有记录，统计会少算这次运行。
- 主机名写进每条记录，用于合并多台机器的数据时区分来源。
本页由仓库中的 docs/adr/0026-machine-records-and-api.md 生成。在 GitHub 上编辑