涤尘 — 技能与记忆维护工具 🧹

Purpose

定期（或按需）对平台的技能系统和记忆系统进行全面的健康检查，发现问题、找出改进点、向用户汇报。

When to Use

用户用任何方式表示需要检查/清理/维护/整理技能或记忆时。包括但不限于：

• "检查一下技能有没有问题"
• "帮我整理一下记忆"
• "技能体检"
• "清理维护"
• maintenance / cleanup / organize

Principles

1. 诊断优先，修改需确认 — 所有修改需先列出给用户，获得明确同意后才执行
2. 无问题不强提意见 — 如果技能和记忆文件都没有明显需要改动的地方，直接告知用户一切正常
3. 分类汇报 — 按「需要处理 / 需要注意 / 仅供参考」三级分类整理发现
4. 一次只做一件事 — 技能检查和记忆检查可以分步执行，先汇报结果再继续

Workflow

Step 1 — 收集信息

同时运行两个扫描脚本，获取原始数据。

定位 managed Python： 寻找当前平台管理的 Python 解释器。路径因平台而异，通常位于平台内置运行时的 python 目录下。可通过 system prompt 中 Available binaries 列出的具体路径获得。

执行命令（按当前平台使用对应 shell 语法）：

# 扫描所有已安装技能（用户级 + 项目级）
MANAGED_PYTHON="<上一步找到的 python 路径>"
$MANAGED_PYTHON scripts/scan_skills.py \
  --user-dir <用户级技能目录> \
  --workspace-dir <项目级技能目录> \
  --output-dir <输出目录>

# 扫描记忆文件
$MANAGED_PYTHON scripts/scan_memory.py \
  --memory-dir <记忆文件目录> \
  --output-dir <输出目录>

扫描结果会同时在 stdout 打印人类可读摘要（供 AI 在对话中直接引用形成报告） 并写入 {workspace}/scan_skills_report.json 和 {workspace}/scan_memory_report.json（供后续参考）。

关键原则：在对话中报告。 扫描脚本输出的 stdout 摘要已包含关键信息，AI 应以此为素材，在对话中形成详细、结构化的报告给用户，而不是让用户自己去查看 JSON 文件。

Step 2 — 分析并形成意见

将扫描结果组织成清晰的结构化报告，分为三部分展示给用户。

2a — 技能分析

按照三个严重级别分类发现：

对每个发现：

• 列出技能名称和具体问题
• 给出修改建议（具体的命令或代码修改方案）
• 标记是否需要用户确认（所有修改都需要用户确认）

如果没有任何发现（零 error、零 warning、零 info），直接告诉用户「所有技能看起来都正常」。

2b — 记忆分析

从扫描结果中提取关键发现：

1. 可归档的旧文件：天数超过 14 天的每日记录文件列表。提示用户是否将其中有价值的内容提炼进 MEMORY.md。

   即使文件未满 14 天，也会通过以下两个机制参与分析：

   • 可合并候选：行数较多（>20 行）且涉及 ≥2 个主题的文件会被标记，不论天数
   • 缺失主题回溯：所有每日记录文件都会被检查关键词是否在 MEMORY.md 中有对应 所以不会因为天数短而漏掉需要提炼的内容。

2. 可合并的主题：来自 consolidation_candidates 中的文件，内容较多且关联多个主题，可能值得提取进 MEMORY.md。
3. 缺失的主题回溯：来自 orphaned_topics 的结果，显示哪些关键词在每日记录中出现但不在 MEMORY.md 中。

对每个建议：

• 展示相关的记忆文件名和片段（最多引用 2-3 行关键内容）
• 询问用户是否提炼到长期记忆
• 在用户同意提炼后，自动提供三选一方案：

  1. 全量写入 MEMORY.md — 适合频繁引用的活跃主题（如当前研究方向）
  2. 建立独立子文件 XXX_memory.md — 适合已完成的大项目（如 grant 申请），MEMORY.md 只留指针
  3. 智能混合 — AFMEMORY.md 放摘要 + 独立文件放完整细节，MEMORY.md 指针写明读取条件

• 如果用户选择子文件方案，在 MEMORY.md 末尾追加指针引用（如 "当涉及 XX 工作时，读取 XX_memory.md"）
• 如果用户选择混合方案，同时做摘要提取 + 子文件建立 + 指针写入

如果没有任何可提炼的内容，直接告诉用户「记忆文件结构良好，暂无需整理」。

2c — 综合建议

如果技能和记忆的扫描都没有发现问题，总结：「系统状态良好，无需处理。」

Step 3 — 执行修改（仅当用户明确确认后）

用户逐条确认后，执行以下操作：

技能修改：

• 修复 SKILL.md 中的错误（更新 frontmatter、修正路径引用、更新命令）
• 删除可清理的文件（如 __pycache__）
• 更新脚本中的过时路径

记忆整理：

• 将用户确认的内容追加到 MEMORY.md（用 Edit 工具或在文件末尾追加）
• 如果用户要求建立专门的领域记忆文件，创建 {topic}_memory.md 并更新 MEMORY.md 中的引用
• 用户确认后删除已过时效的每日记录文件（超过 14 天且已提炼内容）
  • ⚠️ 删除前必须再次向用户确认文件列表

Step 4 — 反馈

向用户报告执行结果：

• 修改了哪些内容
• 为什么修改
• 对未来的影响

Files

Dependencies

• Python 3.x with pyyaml（自动安装尝试，失败则有健壮的简易解析器兜底）
• 访问用户级技能目录和项目级记忆目录的权限（通常为平台默认安装目录）
• 跨平台兼容：脚本使用 os.path 处理路径分隔，不使用平台特定命令

Notes

• 技能扫描依赖 pyyaml（脚本启动时自动尝试安装，失败则用内置简易解析器兜底）
• 简易解析器可正确解析 | 和 > 多行 YAML 值，不再出现误报
• __pycache__ 不检测——自动生成的字节码缓存，清理无实际收益
• 硬编码路径判断不准确，需要人工核实
• 跨平台：两个 Python 脚本均通过 --output-dir 参数指定输出目录（默认当前目录），不使用硬编码路径
• 跨平台：AI 执行扫描时应根据当前平台动态定位 managed Python，而非复制硬编码路径
• WorkBuddy / OpenClaw 通用：用户级技能目录和项目级记忆目录是两者共用约定；不需要其他平台特定依赖
• 记忆扫描的「可归档」标准为 14 天（STALE_DAYS），可在 scan_memory.py 顶部调整
• 即使未满 14 天，内容丰富的文件也会通过 consolidation_candidates 机制参与分析
• 本技能不自动执行任何修改，所有操作必须经用户确认
• 扫描结果写入 {workspace}/scan_skills_report.json 和 {workspace}/scan_memory_report.json，供后续分析