升级

应用插件知识库更新到现有生成的系统。咨询Ars Contexta研究图谱以改进方法论，提出技能升级与研究理由。永不自动实施。触发词为"/upgrade"、“upgrade skills”、“check for improvements”、“update methodology”。版本：“1.0” 生成自：“arscontexta-v1.6” 用户可调用：是上下文：分叉模型：opus 允许工具：Read, Write, Edit, Grep, Glob, Bash

运行时配置（步骤0 — 在任何处理之前）

读取这些文件以配置特定领域的操作：

ops/derivation-manifest.md — 词汇映射，平台提示
- 使用vocabulary.notes用于笔记文件夹名称
- 使用vocabulary.note / vocabulary.note_plural用于笔记类型引用
- 使用vocabulary.reduce用于提取动词
- 使用vocabulary.reflect用于连接查找动词
- 使用vocabulary.reweave用于向后传递动词
- 使用vocabulary.verify用于验证动词
- 使用vocabulary.rethink用于元认知动词
- 使用vocabulary.topic_map用于MOC引用
ops/config.yaml — 处理深度，领域上下文
ops/derivation.md — 推导状态和引擎版本

如果这些文件不存在，使用通用默认值。

立即执行

目标：$ARGUMENTS

立即解析：

如果目标包含特定技能名称（例如，“upgrade reduce”）：仅检查该技能
如果目标包含"–all"：检查所有生成的技能
如果目标为空：检查所有生成的技能（与–all相同）

现在开始。 下面的定义定义了升级过程。

为什么咨询，而不是哈希

技能不通过与生成清单的哈希比较来升级。哈希比较回答了一个狭窄的问题："这个文件改变了吗？"元技能咨询回答了正确的问题：“鉴于我们所知道的，这种技能的方法仍然是最佳方法吗？”

一个技能可能没有改变但已经过时，因为知识库已经增长。或者一个技能可能被用户大量编辑，但已经通过不同的路径包含了最新的思考。对方法论的推理比比较字节更有价值。

两条升级路径

生成的技能和元技能遵循根本不同的升级机制：

类别	技能	升级机制
生成的技能	/{vocabulary.reduce}, /{vocabulary.reflect}, /{vocabulary.reweave}, /{vocabulary.verify}, /ralph, /next, /remember, /{vocabulary.rethink}, /stats, /graph, /tasks, /refactor, /learn, /recommend, /ask	运行时咨询知识图谱
元技能	/setup, /architect, /health, /reseed, /add-domain, /help, /tutorial, /upgrade	插件发布周期 — 更新插件本身

/upgrade评估生成的技能。它不能评估自己或其他元技能 —— 这是插件维护者的责任。

步骤1：清点当前系统

收集库的当前状态：

读取ops/derivation.md以获取：
- 原始推导状态
- 生成系统的引擎版本
- 领域描述和维度位置
读取ops/generation-manifest.yaml（如果存在）以获取：
- 技能版本和生成时间戳
- 哪个插件版本生成了每个技能

列出所有安装的技能：

# 查找所有带有SKILL.md的技能目录
for dir in .claude/skills/*/; do
  skill=$(basename "$dir")
  version=$(grep '^version:' "$dir/SKILL.md" 2>/dev/null | head -1 | awk -F'"' '{print $2}')
  gen_from=$(grep '^generated_from:' "$dir/SKILL.md" 2>/dev/null | head -1 | awk -F'"' '{print $2}')
  echo "$skill  v$version  (from $gen_from)"
done

读取ops/config.yaml以获取当前维度位置

检查用户修改：

# 检测生成后修改的技能
for dir in .claude/skills/*/; do
  skill=$(basename "$dir")
  file="$dir/SKILL.md"
  [[ ! -f "$file" ]] && continue
  # 检查git状态 — 修改过的文件表示用户定制
  git_status=$(git status --porcelain "$file" 2>/dev/null)
  if [[ -n "$git_status" ]]; then
    echo "MODIFIED: $skill"
  fi
done

展示库存：

--=={ 升级 : 库存 }==--

系统：{领域描述}
引擎：arscontexta-{版本}
技能：{count}已安装（{modified_count}用户修改）

  技能               版本  生成自    修改
  /{vocabulary.reduce}    1.0  arscontexta-v1.6  否
  /{vocabulary.reflect}   1.0  arscontexta-v1.6  是
  ...

步骤2：咨询知识库

对于每个生成的技能（或如果指定，则针对特定技能），咨询插件捆绑的知识库以评估技能的当前方法是否反映了当前的最佳实践。

知识库层级

从插件的四个内容层级中读取：

层级	路径	包含什么
方法论图谱	`${CLAUDE_PLUGIN_ROOT}/methodology/`	所有内容 — 通过`kind:`字段（研究/指导/示例）过滤
参考文档	`${CLAUDE_PLUGIN_ROOT}/reference/`	WHAT — 结构化的参考文档和维度图

methodology/中的笔记根据其kind:前置字段进行区分：

kind: research — WHY: 原则和认知科学基础（213个主张）
kind: guidance — HOW: 操作程序和最佳实践（9个文档）
kind: example — WHAT IT LOOKS LIKE: 领域组合（12个示例）
type: moc — 导航：链接相关笔记的主题图（15个图）

每个技能的咨询过程

对于每个被评估的技能：

阅读当前的技能库技能 — 理解其完整的方法，质量门，边缘案例处理
阅读相关知识库文档：
- 关于这个技能领域的研究主张（例如，对于/{vocabulary.reduce}：关于提取方法论的研究主张）
- 关于处理管道最佳实践的指导文档
- 关于技能操作模式的参考文档
比较方法论，而不是文本：
- 技能是否实现了知识库推荐的质量管理门？
- 它是否处理了知识库识别的边缘案例？
- 它是否使用了知识库推荐的发现/搜索模式？
- 知识库是否自这个技能生成以来增加了新技术？

对每个发现进行分类：

分类	含义	示例
当前	技能反映了知识库的最佳实践	无需采取行动
增强	知识库增加了技能缺乏的技术	新质量管理门，更好的搜索模式
更正	知识库与技能的方法相矛盾	过时的方法论，已知的反模式
扩展	知识库涵盖了技能忽略的场景	新边缘案例，新的领域模式

检查用户修改： 如果技能已被用户修改，阅读当前（用户修改过的）版本，并评估是否：
- 用户的更改已经包含了改进（跳过它）
- 用户的更改与改进正交（可以共存）
- 用户的更改与改进冲突（标记为并排审查）

步骤3：生成升级计划

对于每个可用改进的技能，创建一个结构化的提案：

技能：/{domain:skill-name}
状态：{current | enhancement | correction | extension}
用户修改：{yes | no}

当前方法：
  {2-3句话描述技能当前做什么}

提议的改进：
  {2-3句话描述将改变什么}

研究支持：
  {知识库中支持此更改的具体主张}
  - "{主张标题}" — {它如何应用}
  - "{主张标题}" — {它如何应用}

影响：{用户工作流程的变化}
风险：低 | 中 | 高
可逆：是（先前的版本存档到ops/skills-archive/）

风险评估

风险等级	标准
低	附加更改（新的质量管理门，更好的日志记录）。现有行为不变。
中	修改后的行为（不同的提取策略，改变的搜索模式）。输出质量受影响。
高	结构更改（不同的阶段排序，改变的交接格式）。管道协调受影响。

用户修改技能的并排比较

当技能已被用户修改并且有可用的升级时，显示并排比较：

技能：/{domain:skill-name} (USER-MODIFIED)

您的版本：                    推荐：
  [相关部分摘录]        [知识库建议的内容]

您的定制：
  {描述用户更改的内容及为什么看起来是有意的}

选项：
  (a) 保持您的版本不变
  (b) 应用升级，保留您的定制
  (c) 应用升级，替换您的版本（存档到ops/skills-archive/）

选项 (b) 要求升级与用户的更改兼容。如果它们冲突，请解释为什么，并推荐 (a) 或 ©。

步骤4：提出计划

--=={ 升级 }==--

插件：arscontexta-{current_version}
知识库：{count}研究主张，{count}指导文档
检查的技能：{count}

可用升级：{count}
  增强：{n}  |  更正：{n}  |  扩展：{n}

  1. /{domain:skill-name}
     类型：增强
     更改：{一句话总结}
     研究："{主张标题}"
     风险：低

  2. /{domain:skill-name} (USER-MODIFIED)
     类型：更正
     更改：{一句话总结}
     研究："{主张标题}", "{主张标题}"
     风险：中
     注：并排比较可用

  ...

{如果没有升级：}
  所有{count}技能反映了当前最佳实践。
  不需要升级。

应用全部？选择特定升级（例如，"1, 3"）？
或"显示2"以获取特定技能的并排详细信息。

等待用户响应。没有明确的批准不要继续。

步骤5：应用批准的升级

对于每个批准的升级：

5a. 存档当前版本

mkdir -p ops/skills-archive
SKILL_NAME="{skill-name}"
DATE=$(date +%Y-%m-%d)
cp ".claude/skills/${SKILL_NAME}/SKILL.md" \
   "ops/skills-archive/${SKILL_NAME}-${DATE}.md"

5b. 生成更新后的技能

从插件中读取技能的生成块（如果可用）
应用步骤2中确定的特定改进
保留用户从ops/derivation-manifest.md中的词汇转换
保留用户从ops/config.yaml中的维度位置
对于用户修改的技能选择（b）：将用户的定制合并到更新后的技能中

5c. 更新版本跟踪

更新技能的前置字段：

---
version: "{incremented}"
generated_from: "arscontexta-{current_plugin_version}"
---

5d. 更新生成清单

如果ops/generation-manifest.yaml存在，更新此技能的条目：

skills:
  {skill-name}:
    version: "{new_version}"
    upgraded: "{ISO 8601 UTC}"
    upgrade_source: "knowledge-graph-consultation"
    changes: "{简要描述更改了什么}"

步骤6：验证

应用所有批准的升级后：

内核验证 — 运行内核检查以确认结构不变性保持：

# 验证技能文件是否有效
for dir in .claude/skills/*/; do
  [[ -f "$dir/SKILL.md" ]] || echo "MISSING: $dir/SKILL.md"
done

上下文文件检查 — 验证上下文文件中的所有技能引用仍然可以解析

词汇检查 — 确认升级后的技能一致地使用领域词汇：

# 抽查词汇标记是否已解决
grep -l '{vocabulary\.' .claude/skills/*/SKILL.md 2>/dev/null
# 应该返回无 — 所有标记应该已解决

管道兼容性 — 如果管道技能已升级（/{vocabulary.reduce}, /{vocabulary.reflect}, /{vocabulary.reweave}, /{vocabulary.verify}），验证与/ralph的手off格式兼容性

最终报告

--=={ 升级完成 }==--

应用：{N}升级
存档：{N}先前版本到ops/skills-archive/
跳过：{N}（用户修改，保持原样）

更改：
  - /{skill}: {什么改变了}（研究："{主张}"）
  - /{skill}: {什么改变了}（研究："{主张}"）

验证：{PASS | FAIL with details}

{如果任何验证失败：}
  警告：检测到验证问题。
  先前版本可在ops/skills-archive/
  手动回滚。

注：在最近的{vocabulary.note}上运行/{vocabulary.verify}
以确认升级后的技能在实践中正确工作。

不变

/upgrade永远不会自动实施。 升级计划始终首先呈现给用户。用户决定应用哪些升级。这防止了认知外包失败模式，即系统在没有人类理解的情况下自行更改。

所有升级都是咨询性的。用户拥有文件。

边缘情况

没有改进可用： 报告"所有技能反映了当前最佳实践。不需要升级。"并附上检查的技能数量。

没有生成清单： 将所有技能视为版本0（未知生成状态）。与当前知识库的方法论进行比较。这很好 — 咨询推理方法，而不是版本号。

技能已被用户修改： 提供并排比较。提供三个选项：保持用户版本不变，将升级与定制合并，或替换（存档）。永不默默覆盖。

没有ops/derivation-manifest.md： 使用通用词汇用于所有输出。

插件知识库不可用： 报告知识库咨询需要Ars Contexta插件。没有插件捆绑的方法论/和参考/目录，/upgrade无法评估技能。

用户一致拒绝升级： 这是一个信号，不是错误。注意模式 — 它可能表明知识库的建议与这个用户的领域不匹配。如果它在多次/upgrade运行中持续存在，则记录到ops/observations/。

更正与用户修改冲突： 当知识库识别出更正（不仅仅是增强）但用户已修改技能时，清楚地解释冲突。用户可能正是因为原始方法错误而修改了技能 — 他们的修复可能已经解决了更正。展示两者并让用户决定。

多个技能共享更改： 如果相同的知识库改进适用于多个技能（例如，新的搜索模式），将其作为影响多个技能的单一概念更改呈现，而不是每个技能重复列出。