reader/plans/keyword-cleanup-artifact-slimming-v1.md

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 的关键词治理成为一个轻量、可持续、可回溯的偏好演化机制，而不是一个不断膨胀的中间文件系统。