osiman/reader
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
reader/skills/keyword-cleanup-review/SKILL.md
T
root 590d050218 keyword cleanup: v2 engine, alias rule layer, LLM semantic suggestions 
- build_review_bundle.py: 新增 _compute_percentile/_compute_growth,
  候选池从固定阈值改为百分位排名 + 增速因子 (v2 policy)
- term_cleanup_policy.json: 升级 v2 schema
- generate_term_cleanup_suggestions.py: 新增 _prepare_alias_suggestions,
  规则层输出 alias (大小写/单复数/分词变体)
- generate_term_cleanup_semantic_suggestions.py: 新增 LLM 语义建议脚本
  (DeepSeek API, 产出 semantic alias/stopword/promote)
- SKILL.md: 更新为 5 Phase 工作流程
- 首轮清洗 apply: interest 54, aliases 17组, stopwords 17个
- docs/design/keyword-cleanup-flow-overview.md: 流程文档
- plans/: 引擎设计方案
2026-05-14 17:17:49 +08:00

7.7 KiB
Raw Permalink Blame History

name, description
name description
keyword-cleanup-review 生成 reader 项目的正式关键词 review 输入。当用户需要基于 `data/term_index/term_stats.json`、最近的 `data/term_index/daily/*.json` 和当前 configs 产出 bundle、正式 suggestions JSON，或按需生成审阅 Markdown 供 OpenClaw 汇报和等待确认时使用。不要用于低频清理 review 目录、删除旧产物或直接 apply 配置。

关键词清理审查

使用此技能将仓库的关键词统计转化为正式 review 输入，供 OpenClaw 后续做汇报、确认和 apply 编排。

角色边界

这个 skill 负责：

  • 构建 review bundle
  • 生成正式 suggestions JSON
  • 按需生成人工审阅 Markdown
  • 给 OpenClaw 提供稳定的关键词 review 输入

这个 skill 不负责：

  • 清理 outputs/term_index/review/ 下的旧文件
  • 决定删除哪些历史 bundle / suggestions / markdown
  • 直接 apply configs/term_aliases.json / configs/term_stopwords.json / configs/filter_context.personal.json

低频维护、清理和 dry-run 校验应由 OpenClaw 侧 maintenance SOP 处理，而不是由本 skill 承担。

工作流程

Phase 1：构建审查数据包

python skills/keyword-cleanup-review/scripts/build_review_bundle.py

可选参数：

  • --days 7（默认 7，建议传 365 覆盖全量）
  • --top 100（考虑的词数）
  • --output outputs/term_index/review/keyword-cleanup-bundle.json

候选引擎策略

根据 configs/term_cleanup_policy.json 的 schema_version 自动切换：

版本 策略 说明
v1（旧） 固定阈值（total≥3/days≥2 → interest） 小数据集兼容
v2（当前默认） 百分位排名 + 增速因子 自适应数据量，不需要手工调阈值

v2 策略说明：

  • percentile：total_count 在所有词里的排位占比。top 5% → interest 候选，5%-20% → watch 候选
  • growth：recent_count / total_count，衡量近期活跃度。growth≥0.5 的排位外词也会主动推荐

Phase 2：生成建议（规则层）

python scripts/generate_term_cleanup_suggestions.py \
  --bundle outputs/term_index/review/keyword-cleanup-bundle.json

如需人工审阅展示稿：

python scripts/generate_term_cleanup_suggestions.py \
  --bundle outputs/term_index/review/keyword-cleanup-bundle.json \
  --emit-markdown

产出能力

建议类型 状态 方法
interest 建议 ✅ 已实现 百分位 top 5% + 增速促活
watch 建议 ✅ 已实现 百分位 5%-20%
alias 建议 ✅ 已实现 规则层：大小写归一、单复数、去空格/连字符
stopword 建议 ❌ 规则层空缺 见 Phase 3（LLM 层）

默认生成：

  • term-cleanup-suggestions-YYYY-MM-DD.json（正式建议产物）

显式加 --emit-markdown 额外生成：

  • term-cleanup-suggestions-YYYY-MM-DD.md（临时展示稿）

Phase 3：生成建议（LLM 层，可选）

规则层覆盖不了 alias（中英文对应、缩写展开、同义不同名）和 stopword 判断，需要 LLM 辅助：

python scripts/generate_term_cleanup_semantic_suggestions.py \
  --bundle outputs/term_index/review/keyword-cleanup-bundle.json \
  --suggestions outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json \
  --output outputs/term_index/review/term-cleanup-semantic-suggestions-YYYY-MM-DD.json

从 .env 读取 LLM 配置（LLM_API_URL / LLM_MODEL / LLM_API_KEY），使用 DeepSeek API。

输出三部分：

输出 说明
semantic_alias 语义级别名（中英文、缩写、同义不同名）
stopword 泛词过滤建议（规则层做不了的需要语义判断的）
promote_to_interest 与用户关注方向一致的新词，建议加入 interest

注：LLM 层产物是候选，不应自动 apply，需要人工确认后由 OpenClaw 编排 apply。

Phase 4：输出给 OpenClaw 编排

  • suggestions JSON = review / apply 之间唯一正式建议输入
  • semantic-suggestions JSON = LLM 补充建议，需要人工筛选后合并到 suggestions JSON 再 apply
  • Markdown = 临时展示层
  • 后续汇报、确认、dry-run、apply、收尾清理由 OpenClaw 编排层执行

Phase 5：严格保持边界

  • 建议 configs/term_aliases.json 的修改
  • 建议 configs/term_stopwords.json 的修改
  • 建议 configs/filter_context.personal.json 的新增
  • LLM 层产出（semantic-suggestions）不自动 apply，需人工确认后由 OpenClaw 编排层执行
  • 除非用户明确要求，否则不要直接编辑这些文件
  • 除非用户要求修改规则逻辑，否则不要建议直接编辑 configs/filter_rules.json

审查启发式规则

优先考虑以下决策：

  • 别名建议
    • 同一概念的不同命名、大小写、缩写或中英文变体
  • 停用词建议
    • 过于通用、过于宽泛或噪声过大，对过滤无帮助
  • 兴趣关键词建议
    • 高频且与用户的后端工程、AI Agent 和前沿技术关注方向一致
  • 关注词
    • 近期出现且可能重要，但证据尚不充分

建议保守为主。如果置信度较低，将词放入 watch_terms。

输入

主要输入：

  • 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

打包脚本已将这些内容压缩为单个审查数据包。

输出要求

Markdown 输出应：

  • 简要总结当前状态
  • 列出值得处理的高频词
  • 分类别名、停用词、兴趣关键词和关注词建议
  • 用简短、具体的句子解释理由

说明：Markdown 主要用于人工临时审阅，不必默认当作长期资产保留。

JSON 输出应遵循：

  • references/suggestion-schema.md

说明：JSON 是 review / apply 之间的唯一正式建议产物，应优先保留。

产物口径

长期保留：

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

短期保留：

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

临时产物：

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

默认执行口径：

  • bundle 只作为运行时工作文件，默认只保留当前最新一份
  • Markdown 只作为人工展示层，优先按需生成，不默认长期归档
  • JSON suggestions 是 review / apply 之间唯一正式建议输入

说明：

  • “是否删除旧 bundle / 旧 markdown / 旧 suggestions” 不属于本 skill 的正式职责
  • 这类维护动作应由 OpenClaw 侧的 maintenance skill 处理

仓库说明

当前仓库行为：

  • 关键词统计由程序维护，而非 LLM 维护
  • 统计基于 keywords 构建，而非 topics
  • 统计仅包含非 drop 候选项
  • data/term_index/term_stats.json 从每日文件重建，因此重新运行会覆盖同一天的数据而非重复计算
  • 清理策略、关注列表和变更日志是仓库管理的治理输入，审查时应予以尊重

保持建议与此设计保持一致。

资源

  • 脚本：
    • skills/keyword-cleanup-review/scripts/build_review_bundle.py
    • scripts/generate_term_cleanup_suggestions.py
    • scripts/generate_term_cleanup_semantic_suggestions.py（LLM 层）
  • 参考文档：
    • references/suggestion-schema.md
    • plans/keyword-cleanup-interest-watch-engine-improvement.md（v2 引擎设计）
Reference in New Issue View Git Blame Copy Permalink