---
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 引擎设计）