diff --git a/reader-keyword-maintenance/SKILL.md b/reader-keyword-maintenance/SKILL.md new file mode 100644 index 0000000..aaa4cf5 --- /dev/null +++ b/reader-keyword-maintenance/SKILL.md @@ -0,0 +1,128 @@ +--- +name: reader-keyword-maintenance +description: 维护 reader 项目的关键词 review 目录与低频清理 SOP。当用户要求清理或整理 reader 的关键词 review 目录、控制哪些产物长期保留、检查 suggestions JSON 是否可 apply、或执行“只保留当前 bundle / 仅保留最近少量 suggestions JSON / 删除旧 markdown”等低频维护动作时使用。不要用于正式关键词 review 生成,不要用于 reader 日报主链路。 +--- + +# Reader Keyword Maintenance + +这个 skill 负责 reader 关键词治理里的**低频维护动作**,目标是把清理策略、展示稿生成、dry-run 校验和 review 目录维护从 reader 主链路里拆出来,由 OpenClaw 单独承接。 + +## 角色边界 + +这个 skill 负责: + +- 检查 `outputs/term_index/review/` 当前有哪些产物 +- 判断哪些 review 产物应长期保留、短期保留或可清理 +- 用 `apply_term_suggestions.py --dry-run` 做 apply 前校验 +- 执行低频清理和收尾动作 + +这个 skill 不负责: + +- 正式生成关键词 review 建议 +- 充当 alias / stopword 正式 review 决策器 +- 替代 reader 侧的 `keyword-cleanup-review` + +如果用户要的是“做一轮正式关键词 review / 生成正式 suggestions JSON”,应由 OpenClaw 去调用 reader 侧 `keyword-cleanup-review`,而不是由本 skill 直接承担。 + +## 适用场景 + +当用户要求以下事情时使用: + +- 查看或解释 `reader/outputs/term_index/review/` 下有哪些文件 +- 清理旧的 review bundle、old suggestions、old markdown +- 只保留当前 bundle 或最近少量 suggestions JSON +- 检查 suggestions JSON 是否可被 `apply_term_suggestions.py` 消费 +- 执行一次人工 review 准备动作,但不改变 reader 主链路设计 + +不要用于: + +- 日报正式生产运行 +- 生成 daily term index / term_stats 主链路 +- 自动写配置作为默认行为 +- 修改 reader 仓库里的主 SOP 作为低频维护动作的默认入口 +- 正式生成 alias / stopword / interest / watch 建议 + +## 默认口径 + +长期保留: + +- `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/keyword-cleanup-bundle.json` +- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.md` + +更细的保留/清理判断,读取: + +- `references/cleanup-policy.md` + +## 固定 SOP + +### 1. 检查 review 目录 + +- 查看 `outputs/term_index/review/` 当前有哪些文件 +- 分类成: + - 长期保留 + - 短期保留 + - 临时工作文件 + +### 2. 准备人工审阅 + +- 确认最新 bundle 存在 +- 确认最新 suggestions JSON 存在 +- 如需正式生成 suggestions 或 Markdown 展示稿,应转到 reader 侧 `keyword-cleanup-review` + +### 3. dry-run 校验 apply + +- 仅通过 `scripts/apply_term_suggestions.py --dry-run` 校验 suggestions JSON 是否可消费 +- 不直接落配置 + +### 4. 清理 review 产物 + +- 删除旧 markdown 展示稿 +- 默认只保留当前/latest bundle +- 保守清理旧 suggestions JSON +- 不碰 facts/state/config files + +## 常用动作 + +### 1. 验证 suggestions JSON 能否被 apply 消费 + +```bash +cd /home/ubuntu/zhu/github/reader && \ +/usr/bin/python3.11 scripts/apply_term_suggestions.py \ + --suggestions outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json \ + --accept-interest "Claude Code" \ + --dry-run +``` + +## 清理策略 + +保守策略: + +- bundle:默认只保留当前最新一份 +- markdown:默认不归档,需要时现生成 +- suggestions JSON:只保留最近少量几份或已应用过的记录 + +## 维护原则 + +- 优先减少中间产物,不要让 review 工作文件变成长期资产 +- JSON suggestions 是 review / apply 之间唯一正式输入 +- Markdown 只是展示层,不是系统真相 +- 任何清理动作前,先确认不会影响当前待审阅或待 apply 的 suggestions JSON +- 正式关键词 review 的生成入口不在这里,而在 reader 侧 `keyword-cleanup-review` + +执行清理或 review-prep 前,先读取: + +- `references/maintenance-checklist.md` diff --git a/reader-keyword-maintenance/references/alias-review-example.md b/reader-keyword-maintenance/references/alias-review-example.md new file mode 100644 index 0000000..acb590d --- /dev/null +++ b/reader-keyword-maintenance/references/alias-review-example.md @@ -0,0 +1,33 @@ +# Alias Review Example + +Use this as the default style reference when preparing a low-frequency alias review report. + +## Suggested merges + +- `Claude code -> Claude Code` + - 理由:明显属于同一产品名,仅是大小写写法不一致。 + - 证据:`Claude Code` 在最近多日持续出现,而小写写法只是在少量上下文中作为变体出现。 + +- `Sub-Agent -> SubAgent` + - 理由:更像词形差异,不构成新的独立概念。 + - 证据:两者都围绕同一 agent 架构语境出现,且没有稳定区分语义。 + +## Not recommended to merge + +- `Skills ↔ Agent Skills` + - 理由:前者过泛,后者更具体,当前强行归并会损失粒度。 + +- `Anthropic ↔ Claude` + - 理由:公司名与产品名并不等价,不应直接视为一个关键词。 + +## Needs human judgment + +- `AI助手 ↔ AI Agent` + - 风险点:语义可能接近,但中文表述范围更宽,是否并入需要结合实际使用语境判断。 + +## Style notes + +- Keep the report concise. +- Give judgment first, then evidence. +- Do not claim anything is already applied. +- Prefer conservative proposals over broad semantic merging. diff --git a/reader-keyword-maintenance/references/cleanup-policy.md b/reader-keyword-maintenance/references/cleanup-policy.md new file mode 100644 index 0000000..0cbb527 --- /dev/null +++ b/reader-keyword-maintenance/references/cleanup-policy.md @@ -0,0 +1,106 @@ +# Cleanup Policy + +## Purpose + +This reference defines how `reader-keyword-maintenance` should treat keyword governance artifacts. + +The goal is to keep long-term assets small and stable while allowing review-time working files to exist when needed. + +This policy is for low-frequency maintenance only. +It does not replace the formal keyword review generation flow in reader. + +## Artifact classes + +### Long-term assets + +Keep these by default: + +- `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` + +These are facts or active state. + +### Short-term decision artifacts + +Keep selectively: + +- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.json` + +Recommended policy: + +- keep only recent few files, or +- keep only files that were actually used for apply decisions + +### Temporary working/display files + +Treat as disposable unless the user explicitly asks to archive them: + +- `outputs/term_index/review/keyword-cleanup-bundle.json` +- `outputs/term_index/review/term-cleanup-suggestions-YYYY-MM-DD.md` + +Recommended policy: + +- bundle: keep only latest current file +- markdown: generate on demand, do not archive by default + +## Default maintenance actions + +### Safe checks + +Before deleting anything: + +1. confirm the target is not the current bundle under active review +2. confirm the target suggestions JSON is not the one about to be applied +3. never delete configs or facts during review cleanup + +### Safe cleanup order + +1. remove or overwrite old markdown display drafts +2. keep only latest bundle file +3. prune old suggestions JSON files conservatively + +## Decision rules + +### When user says "clean review artifacts" + +Default action: + +- keep facts/state untouched +- keep current suggestions JSON +- remove markdown drafts if they are old and clearly derived display files +- keep bundle only as current working file + +### When user says "prepare manual review" + +Default action: + +- ensure latest bundle exists +- ensure latest suggestions JSON exists +- do not generate formal suggestions or markdown here by default +- if the user wants formal review material, route to reader-side `keyword-cleanup-review` + +### When user says "review alias candidates" or "review stopword candidates" + +Default action: + +- explain that formal keyword review generation belongs to reader-side `keyword-cleanup-review` +- keep this skill focused on maintenance, cleanup, display generation, and dry-run validation +- only proceed here if the user explicitly wants a low-frequency maintenance view rather than the formal review flow + +### When user says "what can be deleted" + +Explain in three buckets: + +- must keep +- can keep temporarily +- safe to regenerate/delete + +## Non-goals + +This policy does not change reader production logic. +It only governs low-frequency maintenance and cleanup decisions in OpenClaw. diff --git a/reader-keyword-maintenance/references/maintenance-checklist.md b/reader-keyword-maintenance/references/maintenance-checklist.md new file mode 100644 index 0000000..1dc12d6 --- /dev/null +++ b/reader-keyword-maintenance/references/maintenance-checklist.md @@ -0,0 +1,55 @@ +# Maintenance Checklist + +Use this checklist before doing any cleanup or review-maintenance action for reader keyword artifacts. + +## Pre-check + +1. Confirm the current repo root is `/home/ubuntu/zhu/github/reader` +2. Confirm the user asked for a maintenance / cleanup / review-prep action +3. If the user actually wants formal keyword review generation, route to reader-side `keyword-cleanup-review` instead of using this maintenance skill +4. Identify whether the action targets: + - current bundle + - suggestions JSON + - markdown display draft + - old review outputs + +## Safety check + +Before deleting or overwriting anything: + +1. Do not touch: + - `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` +2. Confirm the suggestions JSON to keep is not the one about to be applied +3. Treat markdown drafts as disposable only after confirming they are display-only artifacts + +## Review-prep flow + +When preparing manual review: + +1. Ensure the latest bundle exists +2. Ensure the latest suggestions JSON exists +3. Generate markdown only if the user explicitly wants human-readable review material +4. Prefer showing conclusions in chat before creating more files + +## Cleanup flow + +Recommended order: + +1. remove old markdown display drafts +2. keep only the current/latest bundle +3. prune old suggestions JSON conservatively +4. leave facts/state/config untouched + +## Post-check + +After the action: + +1. verify the expected kept files still exist +2. verify no config file was accidentally changed +3. summarize what was kept vs removed