root
590d050218
- 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/: 引擎设计方案
224 lines
7.7 KiB
Markdown
224 lines
7.7 KiB
Markdown
---
|
||
name: keyword-cleanup-review
|
||
description: 生成 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：构建审查数据包
|
||
|
||
```bash
|
||
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：生成建议（规则层）
|
||
|
||
```bash
|
||
python scripts/generate_term_cleanup_suggestions.py \
|
||
--bundle outputs/term_index/review/keyword-cleanup-bundle.json
|
||
```
|
||
|
||
如需人工审阅展示稿：
|
||
|
||
```bash
|
||
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 辅助：
|
||
|
||
```bash
|
||
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 引擎设计）
|