# keyword-cleanup 产物精简方案 v1

## 1. 背景

当前 keyword-cleanup 治理链已经从“只有 review bundle”演进到：

- term stats / daily term index
- review bundle
- suggestions json
- suggestions markdown
- apply -> config / watchlist / change_log

这说明链路已经打通，但也带来一个新问题：

> 中间产物偏多，容易让治理系统本身比被治理对象更重。

本方案的目标不是回退功能，而是重新划分：

- 哪些产物是长期资产
- 哪些产物只是决策输入
- 哪些产物只是运行时工作文件

从而把 keyword-cleanup 收敛成一个更轻的治理辅助层，而不是继续长成一个复杂子系统。

---

## 2. 设计目标

本轮精简目标：

1. 保留真正有长期价值的事实层与状态层数据
2. 保留唯一正式建议产物，用于 review / apply
3. 将 review bundle 和 markdown 展示稿降级为临时产物
4. 让主链路收敛到：

`stats -> suggestions json -> apply -> config`

而不是长期依赖：

`stats -> bundle -> suggestions json + md -> review -> apply`

---

## 3. 产物分层建议

### 3.1 长期保留：事实层

这些文件是系统长期事实基础，应继续长期保留：

- `data/term_index/daily/YYYY-MM-DD.json`
- `data/term_index/term_stats.json`

原因：

- daily 文件代表每日聚合观察结果
- global stats 是治理决策的核心事实来源
- 二者共同构成 term governance 的历史依据

### 3.2 长期保留：状态层

这些文件代表治理系统当前状态，应继续长期保留：

- `configs/filter_context.personal.json`
- `configs/term_watchlist.json`
- `configs/term_aliases.json`
- `configs/term_stopwords.json`
- `configs/term_change_log.json`

原因：

- 它们是已确认生效的治理结果
- 后续 reader 行为依赖这些配置
- `change_log` 负责回溯治理动作

### 3.3 短期保留：正式建议层

建议保留：

- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json`

定位：

- 这是 review / apply 之间的唯一正式建议产物
- 机器可消费
- 可作为某次治理决策的外部依据

建议策略：

- 默认仅保留最近少量几份
- 或仅保留已经 apply 过的 suggestions JSON
- 避免无限累积所有历史 suggestions 文件

### 3.4 降级为临时产物：review bundle

建议降级：

- `outputs/term_index/review/keyword-cleanup-bundle.json`

定位：

- review 输入打包文件
- 只服务于 suggestions 生成过程
- 不属于长期治理资产

建议策略：

- 默认只保留当前最新一份
- 或迁移到更明确的 working/tmp 目录语义
- 不按日期长期积累

### 3.5 降级为临时产物：Markdown 展示稿

建议降级：

- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.md`

定位：

- 纯人工审阅展示层
- 不是唯一真相
- 不参与 apply 逻辑

建议策略：

- 默认不长期持久化
- 需要人工审阅时临时生成
- 优先在聊天/界面中直接展示，而不是默认写成长期文件

---

## 4. 精简后的主链路

建议主链路口径收敛为：

1. 更新 daily term index
2. 更新 global term stats
3. 生成 suggestions JSON
4. 人工确认
5. apply 到 config
6. 记录 change log

即：

`stats -> suggestions json -> apply -> config`

其中：

- bundle = 内部工作层
- markdown = 展示层
- suggestions JSON = 唯一正式建议输入

---

## 5. 为什么这样收敛

### 5.1 避免中间层过多

如果 bundle / md / suggestions 都被长期持久化，就容易出现：

- 多份文件语义重叠
- 不知道谁是“准的”
- 哪些只是试跑产物，哪些是正式治理决策不清晰

### 5.2 保持系统重心正确

keyword-cleanup 的最终目的不是维护一个漂亮的 review 文件集合，而是：

- 持续积累稳定的关键词事实数据
- 让 interest/watch/alias/stopword 演化有据可依
- 让 reader 的长期偏好配置从真实日报里长出来

### 5.3 降低治理系统自身复杂度

治理系统应该比主系统更轻，而不是更重。
如果 review 产物越积越多，最终会反过来增加维护和理解成本。

---

## 6. 对现有实现的影响

本轮不要求删除已有能力，而是重新定义口径。

### 6.1 保留

- `build_review_bundle.py`
- `generate_term_cleanup_suggestions.py`
- `apply_term_suggestions.py`

### 6.2 调整口径

- `keyword-cleanup-bundle.json` 从“默认产物”降级为“临时工作文件”
- `term-cleanup-suggestions-YYYY-MM-DD.md` 从“正式产物”降级为“临时展示稿”
- `term-cleanup-suggestions-YYYY-MM-DD.json` 作为唯一正式建议产物保留

### 6.3 后续可选实现动作

- 覆盖式写入 bundle，而不是长期累积
- Markdown 按需生成，而不是默认总是落盘
- 增加清理策略，只保留最近 N 个 suggestions JSON

---

## 7. SOP 调整建议

### 7.1 review 阶段

默认步骤：

1. 生成或更新 term stats
2. 生成最新 bundle（临时）
3. 生成 suggestions JSON（正式）
4. 如需要人工阅读，再临时生成 Markdown 或直接在聊天展示

### 7.2 apply 阶段

apply 后以以下内容作为最终真相：

- config 文件当前值
- `term_change_log.json`
- 如需要，保留对应 suggestions JSON 作为决策依据

### 7.3 清理策略

建议：

- bundle：默认仅保留最新
- markdown：默认不归档
- suggestions JSON：保留少量最近记录或已应用记录

---

## 8. 非目标

本轮不做：

- 删除现有脚本
- 重写治理链路
- 一次性重构所有 review 文档
- 自动 apply 所有 suggestions
- 引入更复杂的存储系统

本轮只做一件事：

> 把 keyword-cleanup 的产物语义分清，长期保留该留的，临时化该临时的。

---

## 9. 一句话结论

keyword-cleanup 应该收敛为：

- **事实层长期保留**：daily / term_stats
- **状态层长期保留**：interest / watch / alias / stopword / change_log
- **正式建议层轻量保留**：suggestions JSON
- **中间输入层与展示层临时化**：bundle / markdown

最终目标是让 reader 的关键词治理成为一个轻量、可持续、可回溯的偏好演化机制，而不是一个不断膨胀的中间文件系统。