refactor: simplify reader digest skill
This commit is contained in:
zhuyongxin
@@ -1,195 +1,29 @@
|
||||
# 关键词引擎维护流程
|
||||
# 关键词治理路由
|
||||
|
||||
## 概述
|
||||
关键词治理不属于 `reader-digest-flow` 的日常执行阶段。
|
||||
|
||||
reader 项目内置了完整的关键词清洗链路，用于管理 `term_aliases.json`、`term_stopwords.json`、`filter_context.personal.json` 等配置。本文件说明链路各环节的职责与使用方式。
|
||||
仅当用户明确要求“清理关键词”“词库治理”“生成关键词建议”时，委托：
|
||||
|
||||
## 完整数据流
|
||||
|
||||
```
|
||||
每日日报 pipeline
|
||||
│
|
||||
▼
|
||||
term_index/daily/YYYY-MM-DD.json ← build_keyword_index.py (pipeline 末环节自动)
|
||||
│
|
||||
▼
|
||||
term_index/term_stats.json ← 全量汇总
|
||||
│
|
||||
▼
|
||||
build_review_bundle.py ← 打包审查数据包 (手动触发)
|
||||
│
|
||||
▼
|
||||
generate_term_cleanup_suggestions.py ← 生成建议 (手动触发)
|
||||
│
|
||||
▼
|
||||
apply_term_suggestions.py ← 人工确认后落盘 (手动触发)
|
||||
```text
|
||||
skills/keyword-cleanup-review/SKILL.md
|
||||
```
|
||||
|
||||
## 各环节命令
|
||||
Review 输入生成由该 Skill 定义，后续确认与 Apply 由当前编排层负责：
|
||||
|
||||
### 1. 重建每日 term_index（pipeline 末环节自动执行，也可手动）
|
||||
|
||||
```bash
|
||||
cd /home/ubuntu/zhu/github/reader
|
||||
.venv/bin/python3 scripts/build_keyword_index.py \
|
||||
--input outputs/freshrss/rerun/<run-id>/candidates/openclaw-delivery-payload.json
|
||||
```text
|
||||
build review bundle
|
||||
→ generate rule suggestions
|
||||
→ optional semantic suggestions
|
||||
→ human review
|
||||
→ dry-run
|
||||
→ apply accepted suggestions
|
||||
```
|
||||
|
||||
### 2. 重建 review bundle（打包当前配置+统计供审查）
|
||||
约束：
|
||||
|
||||
```bash
|
||||
cd /home/ubuntu/zhu/github/reader
|
||||
.venv/bin/python3 skills/keyword-cleanup-review/scripts/build_review_bundle.py \
|
||||
--days 365 \
|
||||
--top 200 \
|
||||
--output outputs/term_index/review/keyword-cleanup-bundle.json
|
||||
```
|
||||
- Suggestions JSON 是 Review 与 Apply 之间的正式契约；
|
||||
- LLM 语义建议不能自动 Apply；
|
||||
- 不直接编辑 aliases、stopwords、watchlist 或 interest 配置；
|
||||
- 不在日报主流程中因 tag 质量不佳自动触发治理。
|
||||
|
||||
参数：
|
||||
- `--days 365` — 考虑最近多少天的统计数据
|
||||
- `--top 200` — 取前 N 个高频词纳入 bundle
|
||||
|
||||
### 3. 生成清洗建议
|
||||
|
||||
```bash
|
||||
cd /home/ubuntu/zhu/github/reader
|
||||
.venv/bin/python3 scripts/generate_term_cleanup_suggestions.py \
|
||||
--bundle outputs/term_index/review/keyword-cleanup-bundle.json \
|
||||
--emit-markdown
|
||||
```
|
||||
|
||||
输出：
|
||||
- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json` — 正式建议产物
|
||||
- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.md` — 人工阅读展示稿
|
||||
|
||||
当前脚本能生成的建议类型：
|
||||
|
||||
| 类型 | 生成规则 | 当前产出 |
|
||||
|:----|:---------|:---------|
|
||||
| interest_keyword_suggestions | 高频未覆盖词（total≥3, days≥2） | ✅ 按阈值产出 |
|
||||
| watch_terms | 中频观察词（total≤2, days≤2） | ✅ 按阈值产出 |
|
||||
| alias_suggestions | 大小写变体/单复数/空格连词符差异 | ✅ 统计规则产出 |
|
||||
| stopword_suggestions | — | ❌ 脚本硬编码为空 |
|
||||
|
||||
### 4. 应用建议（dry-run → review → apply）
|
||||
|
||||
```bash
|
||||
# 先 dry-run 预览
|
||||
cd /home/ubuntu/zhu/github/reader
|
||||
.venv/bin/python3 scripts/apply_term_suggestions.py \
|
||||
--suggestions outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json \
|
||||
--accept-interest 强化学习 ReAct CLI \
|
||||
--dry-run
|
||||
|
||||
# 确认后正式 apply（去掉 --dry-run）
|
||||
.venv/bin/python3 scripts/apply_term_suggestions.py \
|
||||
--suggestions outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json \
|
||||
--accept-interest 强化学习 ReAct CLI \
|
||||
```
|
||||
|
||||
支持的 accept 参数：
|
||||
- `--accept-interest 词1 词2 ...` — 添加到 interest_keywords
|
||||
- `--accept-watch 词1 词2 ...` — 添加到 watchlist
|
||||
- `--accept-alias 源词1 源词2 ...` — 添加 alias 映射
|
||||
- `--accept-stopword 词1 词2 ...` — 添加停用词
|
||||
|
||||
## 脚本能做什么 vs 不能做什么
|
||||
|
||||
### ✅ 脚本能做的（统计级清洗）
|
||||
|
||||
- 发现大小写变体（`vibe coding` → `Vibe Coding`）
|
||||
- 发现单复数差异（`Agent Skill` → `Agent Skills`）
|
||||
- 发现空格/连词符差异
|
||||
- 按频次推荐 should-be-interest / should-be-watch 的词
|
||||
- 批量 apply 到配置文件，自动记录变更日志
|
||||
|
||||
### ❌ 脚本不能做的（语义级清洗，需要人工判断）
|
||||
|
||||
- 识别产品名（`WorkBuddy`、`LibTV Agent`、`飞书妙搭`）→ 应加 stopword
|
||||
- 识别模型名（`Qwen3-30B-A3B`、`GLM 5.2`、`Opus 4.8`）→ 应加 stopword
|
||||
- 识别人名/地名（`Andrej Karpathy`、`成都天府长岛`）→ 应加 stopword
|
||||
- 英文专有名词归一化到中文主题词（`Multi-Agent` → `多Agent`）
|
||||
- 长产品名归一化（`火山云数据库PostgreSQL Serverless版` → `Serverless数据库`）
|
||||
- 判断某个词对 Hugo tag 是否有用（`1688`、`OPC训练营` → 无效）
|
||||
|
||||
## 语义级清洗：LLM 辅助（generate_term_cleanup_semantic_suggestions.py）
|
||||
|
||||
除了统计规则的清洗，项目还有一个 **LLM 驱动的语义级清洗脚本**，能发现统计规则做不到的事情：
|
||||
|
||||
```bash
|
||||
cd /home/ubuntu/zhu/github/reader
|
||||
.venv/bin/python3 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
|
||||
```
|
||||
|
||||
参数：
|
||||
- `--bundle` — review bundle（先跑 build_review_bundle.py）
|
||||
- `--suggestions` — 规则层的建议 JSON（可选，供 LLM 避免重复）
|
||||
- `--output` — 输出路径（自动生成）
|
||||
- `--dry-run` — 只打印 prompt 不调 LLM
|
||||
|
||||
### 语义脚本能做的（而统计规则不能做的）
|
||||
|
||||
| 类型 | LLM 能发现什么 | 示例 |
|
||||
|:----|:--------------|:-----|
|
||||
| **semantic_alias** | 中英文映射、简称↔全称、近义词 | `AI智能体`→`AI Agent`, `AI Harness`→`Harness Engineering` |
|
||||
| **stopword** | 语义判断哪些词太泛/不相干 | `自动化`(太泛), `AlphaFold`(生物领域), `陌生化`(穿透词) |
|
||||
| **promote_to_interest** | 与用户关注领域对齐的新词 | `强化学习`, `Loop Engineering`, `MoE`, `ChatGPT` |
|
||||
|
||||
### 两阶段清洗 SOP
|
||||
|
||||
当需要清洗关键词时，按此顺序操作：
|
||||
|
||||
**阶段一：规则统计清洗（脚本发现 + 人工确认）**
|
||||
1. `build_review_bundle.py` → 重建 bundle
|
||||
2. `generate_term_cleanup_suggestions.py` → 产出统计级建议
|
||||
3. 检查建议，决定哪些 accept
|
||||
4. `apply_term_suggestions.py --dry-run` → 预览
|
||||
5. `apply_term_suggestions.py` → 正式落地
|
||||
|
||||
**阶段二：语义级清洗（LLM 发现 + 人工确认）**
|
||||
1. `generate_term_cleanup_semantic_suggestions.py` → 调 LLM 产生语义建议
|
||||
2. 检查 LLM 的 semantic_alias / stopword / promote_to_interest
|
||||
3. 人工编辑 term_aliases.json / term_stopwords.json（语义级判断不能自动化）
|
||||
|
||||
**🔴 不要绕过确认流程直接改配置。** 先跑脚本看看发现了什么，再针对性改。未经审视的批量改配置会引入新问题。
|
||||
|
||||
## 完整的语义级清洗操作流程
|
||||
|
||||
当需要大量添加 aliases/stopwords 时，推荐流程：
|
||||
|
||||
1. **跑一次 `build_review_bundle.py` + `generate_term_cleanup_suggestions.py`** 看看统计建议
|
||||
2. **走一遍实际 pipeline 产出**，收集所有 unique keywords：
|
||||
```bash
|
||||
for rid in $(ls outputs/freshrss/rerun/); do
|
||||
python3 -c "
|
||||
import json
|
||||
d = json.load(open('outputs/freshrss/rerun/$rid/summary/summary-batch.json'))
|
||||
for item in d['items']:
|
||||
for kw in item['summary'].get('keywords', []):
|
||||
print(kw)
|
||||
"
|
||||
done | sort -u
|
||||
```
|
||||
3. 按类别分组：正常词 / 产品名（stopword） / 模型名（stopword） / 需要 alias 的
|
||||
4. 分别更新 `term_aliases.json` 和 `term_stopwords.json`
|
||||
5. **重建 term_index**：对每个受影响日期的 run 跑 `build_keyword_index.py`
|
||||
6. **更新 Hugo tags**：从重建后的 `data/term_index/daily/YYYY-MM-DD.json` 取
|
||||
|
||||
## 当前配置 (2026-07-16)
|
||||
|
||||
| 文件 | 条目数 |
|
||||
|:----|:------|
|
||||
| `configs/term_aliases.json` | 142 |
|
||||
| `configs/term_stopwords.json` | 106 |
|
||||
| `configs/filter_context.personal.json` | 54 (interest_keywords) |
|
||||
| `configs/term_watchlist.json` | 6 |
|
||||
|
||||
## 关键词/别名/停用词配置的更新规范
|
||||
|
||||
- `term_aliases.json` — 只放"源词→目标词"的映射，目标是让不同写法的同一概念归一到标准形式
|
||||
- `term_stopwords.json` — 放产品名、模型名、人名、地名等对 Hugo tag 无价值的词
|
||||
- **随时可以加**，加了后重建 term_index 即可生效
|
||||
- 不涉及 pipeline 重新跑——只影响下游展示
|
||||
Review bundle、Suggestions、Schema 和产物保留策略以 `keyword-cleanup-review` 为唯一事实来源；该 Skill 不直接 Apply 配置。
|
||||
|
||||
Reference in New Issue
Block a user