osiman/reader

Fork 0

Files

T

root e3663f681d feat: add keyword cleanup docs, skill updates, and delivery compatibility fix

2026-04-14 09:51:57 +08:00

16 KiB

Raw Blame History

keyword-cleanup-review 建议产物补齐设计

1. 背景与目标

当前仓库已经具备 keyword cleanup review 的大部分基础设施：

已有 review bundle 构建脚本 skills/keyword-cleanup-review/scripts/build_review_bundle.py
已有 term stats 与 daily term index 数据源
已有治理输入：configs/term_cleanup_policy.json、configs/term_watchlist.json、configs/term_change_log.json
已有建议落地脚本 scripts/apply_term_suggestions.py

当前缺口是：

缺少一层“把 keyword-cleanup-bundle.json 转成正式建议产物”的实现层。

也就是说，仓库现在能生成 review bundle，也能消费 suggestions JSON，但中间缺少稳定、可复用、可落盘的 suggestions 生成器。

本轮目标是补齐最小闭环，让仓库能够从 review bundle 稳定生成两份正式建议产物：

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

并保证 JSON 与 skills/keyword-cleanup-review/references/suggestion-schema.md 对齐，且能直接衔接 scripts/apply_term_suggestions.py。

补充口径：本方案中的 JSON 是 review / apply 之间的唯一正式建议产物；bundle 与 Markdown 主要作为运行时工作文件和临时展示层，不建议与 facts/configs 一样长期沉淀。

2. 当前现状

2.1 已有输入层

build_review_bundle.py 已经把以下输入聚合成单个 bundle：

data/term_index/term_stats.json
data/term_index/daily/*.json
configs/term_aliases.json
configs/term_stopwords.json
configs/filter_context.personal.json
configs/term_cleanup_policy.json
configs/term_watchlist.json
configs/term_change_log.json

bundle 中已经包含：

当前配置快照
最近 N 天热点词
uncovered terms
interest review candidates
watch review candidates

这些信息已经足够支撑“保守的、可审查的” suggestions 生成。

2.2 已有输出消费层

scripts/apply_term_suggestions.py 已经能消费 suggestions JSON，并将接受的建议写回：

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

这说明落地层已存在，缺的是中间的正式建议产物生成层。

3. 当前缺口

当前流程停在：

build_review_bundle.py -> keyword-cleanup-bundle.json

但缺少：

keyword-cleanup-bundle.json -> term-cleanup-suggestions-YYYY-MM-DD.json/.md

因此出现几个问题：

README / 设计文档里已经引用 suggestions 产物，但仓库内没有稳定生成脚本
人工审阅与后续 apply 之间没有统一的正式交付格式
同一份 bundle 无法稳定、幂等地重放为同名 suggestions 产物
alias / stopword / interest / watch 四类建议缺少统一出入口

4. 推荐最小闭环架构

推荐新增一层独立脚本：

scripts/generate_term_cleanup_suggestions.py

职责：

输入：outputs/term_index/review/keyword-cleanup-bundle.json
输出：
- outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json
- outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.md

推荐最小数据流：

build_review_bundle.py 生成 bundle
generate_term_cleanup_suggestions.py 读取 bundle
脚本基于治理 hints 生成 suggestions JSON
同时渲染人类可审阅的 Markdown
审阅后可用 apply_term_suggestions.py 选择性写回配置

本轮不引入默认 LLM 路径：

默认实现采用确定性规则生成
如果未来需要 LLM 参与，应作为显式可选增强，而不是默认路径

5. 产物设计

5.1 JSON 产物

JSON 必须与 suggestion-schema.md 对齐，至少包含：

{
  "date": "2026-04-08",
  "based_on_days": 7,
  "alias_suggestions": [],
  "stopword_suggestions": [],
  "interest_keyword_suggestions": [
    {
      "term": "Claude Code",
      "reason": "Meets the configured interest-keyword review threshold and is not yet covered."
    }
  ],
  "watch_terms": [
    {
      "term": "A2A",
      "reason": "Falls into the configured watch-term review range and should be observed first."
    }
  ]
}

在不破坏兼容性的前提下，可以补充少量元数据字段，建议仅限：

source_bundle
policy_schema_version
summary

建议项字段口径：

alias_suggestions[]
- from
- to
- reason
stopword_suggestions[]
- term
- reason
interest_keyword_suggestions[]
- term
- reason
- 可选：total_count、days_seen、recent_count
watch_terms[]
- term
- reason
- 可选：total_count、days_seen、recent_count

兼容性要求：

apply_term_suggestions.py 只依赖分类 bucket 与关键字段名
因此额外证据字段只能追加，不能替换现有字段名

5.2 Markdown 产物

Markdown 推荐结构：

标题与日期
输入 bundle 与策略摘要
当前现状摘要
- top/global 观察
- uncovered terms 概览
- 当前 watchlist / interest 覆盖情况
建议摘要
- interest 建议数量
- watch 建议数量
- alias 建议数量
- stopword 建议数量
interest_keyword_suggestions
watch_terms
alias_suggestions
stopword_suggestions
应用方式
- 指向生成的 JSON
- 给出 apply_term_suggestions.py 的调用示例

这样可以保证：

人可以直接审阅
机器可以直接消费同名 JSON
Markdown 与 JSON 始终一一对应

6. 建议生成策略

6.1 本轮主链路：interest / watch

本轮先实现最小可用主链路：

interest_keyword_suggestions
watch_terms

直接复用 bundle 中已有的：

governance_hints.interest_review_candidates
governance_hints.watch_review_candidates

原因：

这些候选已经与 policy 对齐
这些候选已经排除了大部分已覆盖项
能直接与现有 apply 脚本形成闭环

6.2 alias / stopword 保守处理

本轮边界明确如下：

alias_suggestions 先保持保守，默认可为空
stopword_suggestions 先保持保守，默认可为空
后续如果补充更强证据或人工审查规则，再逐步增强

这样可以避免在证据不足时误伤配置。

6.3 Phase 2 新方向：alias review 交给 LLM 整理

对于 alias，不再优先走程序规则匹配。 Phase 2 建议改为：

程序继续负责准备 review 输入（term stats / daily / current aliases / stopwords / interest / watchlist）
LLM 负责整理 alias 候选
默认先输出人工审阅汇报，而不是直接 apply
人工确认后，再决定是否写入 term_aliases.json

这样做的原因：

alias 更偏语义整理，而不是简单趋势筛选
与 watch / interest 相比，alias 一旦错误归并，代价更高
对当前低频治理场景来说，LLM + 人工确认更轻，也比在程序里持续堆复杂规则更合适

7. 错误处理

脚本应做显式校验，并在失败时给出明确错误：

7.1 输入错误

bundle 文件不存在 -> 直接失败
bundle 不是 JSON object -> 直接失败
缺少关键字段（如 days、governance_hints）-> 直接失败
候选 bucket 结构错误 -> 直接失败

7.2 输出错误

输出目录不存在时自动创建
JSON / Markdown 写入失败时直接退出非 0

7.3 数据去重与冲突

同一 term 不能同时出现在 interest 与 watch 中
优先级：interest_keyword_suggestions > watch_terms
已在 bundle 当前配置中覆盖的 term 不重复输出

8. 幂等性

本轮要求具备基础幂等性：

同一份 bundle 多次运行，默认生成同名产物
同一份 bundle 多次运行，JSON 内容顺序稳定
Markdown 内容顺序稳定

建议做法：

优先使用 bundle 的 generated_at 日期作为 suggestions 文件日期
term 排序按证据强度与 term 名稳定排序
不在默认输出中写入“每次运行变化”的当前时间戳

这样可以让生成器作为可重放步骤存在于 review 流程中。

9. 与 apply_term_suggestions.py 的衔接

正式链路应变成：

build_review_bundle.py
generate_term_cleanup_suggestions.py
人工审阅 Markdown
apply_term_suggestions.py --suggestions ...

衔接要求：

JSON bucket 名必须与 apply_term_suggestions.py 读取逻辑一致
date 与 based_on_days 字段保留，用于 change log 回写
建议项中的 reason 直接沿用到 apply 后的 change log

这保证建议生成层不会成为孤立产物，而是正式进入 repo 治理闭环。

10. Python 3.11 依赖处理

10.1 当前现状

build_review_bundle.py 当前使用 from datetime import UTC，这要求 Python 3.11。

仓库整体 pyproject.toml 当前也声明 requires-python = ">=3.11"，因此短期内使用 /usr/bin/python3.11 运行是符合仓库现状的。

10.2 短期建议

短期先在文档与验证命令中明确：

bundle 构建使用 /usr/bin/python3.11
suggestions 生成脚本也按仓库当前 3.11 基线运行

10.3 中期建议

如果后续希望把 keyword cleanup 工具链下探到 Python 3.10，可做兼容改造：

把 datetime.UTC 替换为 datetime.timezone.utc
重新检查相关脚本是否还有其他 3.11-only 语法或库依赖

本轮不做超范围兼容重构，只在文档中把此约束说清楚。

11. 边界与非目标

本轮明确边界：

先实现 interest/watch 主链路
alias/stopword 先保持保守或留待后续增强
不做超范围重构
不把 LLM 作为默认生成路径
不直接改 filter_rules.json
不自动 apply 建议到配置

因此，本轮交付定义为：

补齐 bundle -> suggestions 的正式实现层
让 review 流程可运行、可落盘、可审阅、可应用

而不是一次性做完所有高级治理逻辑。

12. 实施建议

建议按以下小步落地：

Phase 1（已完成）

新增 scripts/generate_term_cleanup_suggestions.py
读取 bundle 并做结构校验
生成稳定排序的 interest/watch suggestions JSON
Markdown 改成按需生成
README / skill 文档补一条生成命令
用 /usr/bin/python3.11 完整跑通 bundle -> suggestions

完成后，keyword cleanup review 的最小正式链路变为：

review bundle -> suggestions json -> apply accepted suggestions

其中 Markdown 只是按需生成的展示层。

Phase 2（下一步）

保持程序继续准备 review 输入
引入 LLM 做 alias 候选整理
默认先生成 alias review 汇报，而不是直接 apply
由人工确认后再决定是否写入 term_aliases.json

这样 alias review 会成为一个低频治理动作，而不是主链路里的自动归一步骤。

Phase 3（下一步）

保持程序继续准备 review 输入
引入 LLM 做 stopword 候选整理
默认先生成 stopword review 汇报，而不是直接 apply
由人工确认后再决定是否写入 term_stopwords.json

这样 stopword review 会成为一个低频减噪动作，而不是主链路里的自动过滤步骤。

Phase 3 输入建议

建议给 LLM 的输入包括：

data/term_index/term_stats.json 中的高频词与 recent evidence
最近 N 天 data/term_index/daily/*.json 的热点词上下文
当前 configs/term_stopwords.json
当前 configs/term_aliases.json
当前 configs/filter_context.personal.json 中的 interest_keywords
当前 configs/term_watchlist.json

程序层只负责把这些输入整理成紧凑 review context，不负责直接做 stopword 决策。

Phase 3 输出建议

建议 LLM 默认输出一份人工审阅汇报，而不是直接写配置：

建议加入 stopword
- 词
- 简短理由
- 证据（如 total_count / days_seen / recent_count）
暂不建议加入 stopword
- 词
- 为什么虽然偏泛，但当前还不能杀
需要人工判断
- 词
- 风险点：可能是噪声，也可能仍保留有价值信号

如需结构化输出，可额外补一份 stopword_review_candidates.json，但该文件只作为 review 输入，不直接作为自动 apply 指令。

Phase 3 审阅原则

宁可少删，不乱杀
优先处理过泛、低辨识度、持续污染统计的词
对可能仍承载有效技术语义的词保持保守
默认先汇报，确认后再执行

Phase 3 汇报模板建议

建议 stopword review 默认按以下结构汇报给用户：

建议加入 stopword
- 词
- 理由：为什么这个词对治理帮助低、噪声高
- 证据：total_count / days_seen / recent_count 或最近出现上下文
暂不建议加入 stopword
- 词
- 理由：为什么当前不建议删掉
需要人工判断
- 词
- 风险点：泛词与有效主题词之间边界不清等

推荐汇报风格：

简短、保守、可审阅
先给判断，再给证据
不输出机器式原始 dump
不默认承诺“已应用”，只汇报“建议”

Phase 2 输入建议