# Outputs Layout

`outputs/` 按来源和运行批次组织。当前推荐区分生产产物与调试产物。

## 生产默认输出

对于 FreshRSS 主流水线，默认只保留这 3 类文件：

- `outputs/freshrss/rerun/<run_id>/raw/freshrss.raw.json`
  - FreshRSS 原始响应快照
- `outputs/freshrss/rerun/<run_id>/candidates/openclaw-delivery-payload.json`
  - 发给 OpenClaw 的最终批量 payload
- `outputs/freshrss/rerun/<run_id>/run-report.json`
  - 本次批处理的运行报告

这是当前推荐的生产模式。

## 词元统计运行数据

词元统计不放在 `outputs/` 下，而放在单独的运行数据目录：

- `data/term_index/daily/YYYY-MM-DD.json`
  - 某一天的日报级 `keywords` 聚合结果
- `data/term_index/term_stats.json`
  - 全局累计词频统计

这两类文件属于可重建的本地运行数据，不作为仓库长期跟踪产物。

## 调试扩展输出

当启用 `debug_artifacts` 时，才会额外写出这些中间文件：

- `outputs/freshrss/rerun/<run_id>/items/`
  - 标准化 `item` 中间文件
- `outputs/freshrss/rerun/<run_id>/extracted/`
  - 提取结果
- `outputs/freshrss/rerun/<run_id>/summary/`
  - LLM 总结结果及调试尝试文件
- `outputs/freshrss/rerun/<run_id>/filter/`
  - 规则过滤结果
- `outputs/freshrss/rerun/<run_id>/candidates/*.article-candidate-record.json`
  - 内部候选记录
- `outputs/freshrss/rerun/<run_id>/candidates/*.openclaw-candidate-input.json`
  - 单篇 OpenClaw 输入对象

## 何时启用调试产物

只在这些场景启用：

- 某一批次有异常，需要定位是提取、总结还是过滤阶段出错
- 需要核对某条内容为什么被 `keep` / `review` / `drop`
- 需要为规则调整收集样本

平时不要默认开启。

## 参考目录

- `outputs/prompts/`
  - Prompt 模板
- `outputs/reference/`
  - 手工样例、固定参考输入输出
- `outputs/freshrss/`
  - FreshRSS 实跑批次输出

## 命名原则

- 每次批处理使用独立目录：`outputs/freshrss/rerun/<timestamp>/`
- 默认优先保留最终产物，不把所有中间文件都当成长期资产
- 调试文件只在需要时生成
- `reference/` 只放可复用样例，不放真实生产批次数据
- `data/term_index/` 只保存本地词元统计运行数据，不纳入 git 跟踪

## 当前建议

如果目标是交给 OpenClaw 稳定消费，优先依赖：

- `openclaw-delivery-payload.json`
- `run-report.json`
- `freshrss.raw.json`
- `data/term_index/daily/YYYY-MM-DD.json`
- `data/term_index/term_stats.json`

其中前 3 个是本次批处理产物，后 2 个是持续累积的词元统计数据。