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