ppw:update

用途

此 Skill 会从上游 GitHub 仓库 Lylll9436/Paper-Polish-Workflow-skill 同步本地 .claude/skills/ 和 references/。它会下载最新的 SKILL.md 文件和参考文档，与本地版本进行比较，并更新所有已更改的文件。

触发条件

在用户提出以下请求时激活：

• 更新或同步远程仓库中的技能
• 更新或同步技能包

示例调用：

• “更新技能”
• “从 GitHub 同步技能”
• “更新技能”

模式

模式	默认值	行为
direct	是	获取、比较、更新并报告，不进行中间确认
interactive		在应用每项更新前显示差异摘要

默认模式： direct

工作流

步骤 0：工作流记忆检查

• 读取 .planning/workflow-memory.json。如果文件缺失或为空，则跳至步骤 1。
• 检查最近 1-2 条日志是否构成包含 ppw:update 的已识别模式，且该模式在日志中出现次数 >= threshold。完整算法请参阅 skill-conventions.md > Workflow Memory > Pattern Detection。
• 如果发现模式，则通过 AskUserQuestion 提出建议：
  • 问题：“检测到常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 ppw:update？”
  • 选项：“Yes, proceed” / “No, continue normally”
• 如果用户接受：将模式设为 direct，跳过 Ask Strategy 问题。
• 如果用户拒绝或 AskUserQuestion 不可用：继续正常模式。

步骤 1：运行前检查

• 确认 gh CLI 可用且已通过身份验证：gh auth status
• 确认可以访问上游仓库：gh api repos/Lylll9436/Paper-Polish-Workflow-skill --jq '.full_name'
• 如果任一检查失败，则报告错误并停止。
• 记录工作流： 将 {"skill": "ppw:update", "ts": "<ISO timestamp>"} 追加到 .planning/workflow-memory.json。如果文件缺失，则创建文件并写入 []。如果日志长度 >= 50，则删除最旧的条目。

步骤 2：获取远程文件索引

• 列出远程仓库中的所有技能目录：

  gh api repos/Lylll9436/Paper-Polish-Workflow-skill/contents/.claude/skills --jq '.[].name'
  

• 列出远程仓库中的所有参考文件：

  gh api repos/Lylll9436/Paper-Polish-Workflow-skill/contents/references --jq '.[] | .name + " " + .type'
  

• 对于参考子目录（type=dir），还要递归列出其中的内容。

步骤 3：比较并更新技能

对于每个远程技能目录：

1. 获取远程 SKILL.md 内容：

   gh api repos/Lylll9436/Paper-Polish-Workflow-skill/contents/.claude/skills/{skill-name}/SKILL.md --jq '.content' | base64 -d
   

2. 如果本地 .claude/skills/{skill-name}/SKILL.md 存在，则读取该文件。
3. 比较两者：
   • 如果本地文件不存在 → NEW 技能，创建目录并写入文件。
   • 如果内容不同 → UPDATED，覆盖本地文件。
   • 如果内容相同 → UNCHANGED，跳过。
4. 记录结果，用于最终报告。

在 interactive 模式下： 应用每项更新前，显示变更摘要并请求确认。

步骤 4：比较并更新参考文件

对于每个远程参考文件：

1. 通过 gh api 获取远程文件内容并进行 base64 解码。
2. 如果本地 references/{filename} 存在，则读取该文件。
3. 进行比较并应用与步骤 3 相同的 NEW/UPDATED/UNCHANGED 逻辑。
4. 对于子目录（例如 references/journals/、references/expression-patterns/），递归处理其中的每个文件。

步骤 5：输出报告

呈现摘要表：

## Skills Update Report

| Skill | Status |
|-------|--------|
| polish-skill | ✓ Updated |
| de-ai-skill | - Unchanged |
| new-skill | + New |

## References Update Report

| File | Status |
|------|--------|
| expression-patterns.md | ✓ Updated |
| skill-conventions.md | - Unchanged |

**Summary:** {updated_count} updated, {new_count} new, {unchanged_count} unchanged

输出约定

输出	格式	条件
更新报告	Markdown 表格	始终生成
文件数量摘要	文本	始终报告

边缘情况

情况	处理方式
未安装 gh CLI 或未通过身份验证	报告错误，建议运行 gh auth login
无法访问远程仓库	报告网络/权限错误
本地技能包含远程版本中没有的修改	使用远程版本覆盖（远程版本是事实来源）
远程仓库中的新技能在本地不存在	创建目录并写入 SKILL.md
远程技能已删除但本地仍存在	保留本地版本（不删除；报告为“仅本地”）
本地不存在参考子目录	创建该目录

回退方案

场景	回退方案
gh api 遭遇速率限制	等待后重试一次，然后报告错误
Base64 解码失败	尝试使用 Accept: application/vnd.github.raw 标头调用 gh api
单个文件获取失败	跳过该文件，继续处理其余文件，并在摘要中报告

---

约定：references/skill-conventions.md