upgrade

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

读取以下文件以配置特定领域的行为：

1. 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

2. ops/config.yaml — 处理深度、领域上下文

3. 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：清点当前系统

收集知识库的当前状态：

1. 阅读 ops/derivation.md，了解：

   • 原始派生状态
   • 生成系统的引擎版本
   • 领域描述和维度位置

2. 阅读 ops/generation-manifest.yaml（如果存在），了解：

   • 技能版本和生成时间戳
   • 生成每项技能的插件版本

3. 列出所有已安装的技能：

   # Find all skill directories with 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
   

4. 阅读 ops/config.yaml，了解当前维度位置

5. 检查是否有用户修改：

   # Detect skills modified after generation
   for dir in .claude/skills/*/; do
     skill=$(basename "$dir")
     file="$dir/SKILL.md"
     [[ ! -f "$file" ]] && continue
     # Check git status — modified files indicate user customization
     git_status=$(git status --porcelain "$file" 2>/dev/null)
     if [[ -n "$git_status" ]]; then
       echo "MODIFIED: $skill"
     fi
   done
   

呈现清点结果：

--=={ upgrade : inventory }==--

System: {domain description}
Engine: arscontexta-{version}
Skills: {count} installed ({modified_count} user-modified)

  Skill               Version  Generated From    Modified
  /{vocabulary.reduce}    1.0  arscontexta-v1.6  no
  /{vocabulary.reflect}   1.0  arscontexta-v1.6  yes
  ...

---

步骤 2：咨询知识库

对于每项生成的技能（或指定的特定技能），请查阅插件内置的知识库，评估该技能当前的方法是否符合现行最佳实践。

知识库分层

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

层级	路径	内容
方法论图谱	${CLAUDE_PLUGIN_ROOT}/methodology/	所有内容 — 按 kind: 字段筛选（research/guidance/example）
参考文档	${CLAUDE_PLUGIN_ROOT}/reference/	WHAT — 结构化参考文档和维度映射

methodology/ 中的笔记通过其 kind: frontmatter 字段区分：

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

每项技能的咨询流程

针对每项待评估的技能：

1. 阅读当前知识库技能 — 理解其完整方案、质量关卡和边缘情况处理方式

2. 阅读相关知识库文档：

   • 关于该技能领域的研究主张（例如，对于 /{vocabulary.reduce}：关于提取方法的主张）
   • 关于处理流水线最佳实践的指导文档
   • 关于该技能操作模式的参考文档

3. 比较方法，而非文本：

   • 该技能是否实现了知识库建议的质量关卡？
   • 是否处理了知识库指出的边缘情况？
   • 是否采用了知识库建议的发现／搜索模式？
   • 自生成该技能以来，知识库是否添加了新技术？

4. 对每项发现分类：

   分类	含义	示例
   当前	技能体现了知识库的最佳实践	无需采取行动
   增强	知识库新增了技能尚未具备的技术	新的质量关卡、更好的搜索模式
   修正	知识库与技能采用的方法相矛盾	方法过时、已知反模式
   扩展	知识库涵盖了技能忽略的场景	新的边缘情况、新的领域模式

5. 检查用户修改： 如果技能已被用户修改，请阅读当前（用户修改后的）版本，并评估：

   • 用户的更改是否已包含该改进（跳过）
   • 用户的更改是否与该改进无关（可以共存）
   • 用户的更改是否与该改进冲突（标记以供并排审查）

---

第 3 步：生成升级计划

针对每项有可用改进的技能，创建一份结构化提案：

Skill: /{domain:skill-name}
Status: {current | enhancement | correction | extension}
User-modified: {yes | no}

Current approach:
  {2-3 sentences describing what the skill currently does}

Proposed improvement:
  {2-3 sentences describing what would change}

Research backing:
  {Specific claims from the knowledge base that support this change}
  - "{claim title}" — {how it applies}
  - "{claim title}" — {how it applies}

Impact: {what changes for the user's workflow}
Risk: low | medium | high
Reversible: yes (previous version archived to ops/skills-archive/)

风险评估

风险级别	标准
低	增量变更（新增质量关卡、改进日志记录）。现有行为保持不变。
中	行为变更（不同的提取策略、变更搜索模式）。会影响输出质量。
高	结构性变更（变更阶段顺序、变更交接格式）。会影响流水线协调。

针对用户修改技能的并排对比

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

Skill: /{domain:skill-name} (USER-MODIFIED)

Your version:                     Recommended:
  [relevant section excerpt]        [what knowledge base suggests]

Your customization:
  {description of what the user changed and why it appears intentional}

Options:
  (a) Keep your version unchanged
  (b) Apply upgrade, preserving your customizations
  (c) Apply upgrade, replacing your version (archived to ops/skills-archive/)

选项 (b) 要求升级与用户的更改兼容。如果两者冲突，请说明原因并建议选择 (a) 或 (c)。

---

第 4 步：呈现计划

--=={ upgrade }==--

Plugin: arscontexta-{current_version}
Knowledge base: {count} research claims, {count} guidance docs
Skills checked: {count}

Upgrades available: {count}
  Enhancements: {n}  |  Corrections: {n}  |  Extensions: {n}

  1. /{domain:skill-name}
     Type: Enhancement
     Change: {one-line summary}
     Research: "{claim title}"
     Risk: low

  2. /{domain:skill-name} (USER-MODIFIED)
     Type: Correction
     Change: {one-line summary}
     Research: "{claim title}", "{claim title}"
     Risk: medium
     Note: Side-by-side comparison available

  ...

{If no upgrades:}
  All {count} skills reflect current best practices.
  No upgrades needed.

Apply all? Select specific upgrades (e.g., "1, 3")?
Or "show 2" for side-by-side detail on a specific skill.

等待用户回复。未经明确批准，不得继续。

---

第 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. 生成更新后的技能

1. 读取插件中的技能生成区块（如有）
2. 应用第 2 步中确定的具体改进
3. 保留用户在 ops/derivation-manifest.md 中的词汇转换
4. 保留用户在 ops/config.yaml 中的维度位置
5. 对于选择了选项 (b) 的用户修改技能：将用户自定义内容合并到更新后的技能中

5c. 更新版本跟踪

更新技能的 frontmatter：

---
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: "{brief description of what changed}"

---

第 6 步：验证

应用所有已批准的升级后：

1. 内核验证 — 运行内核检查，确认结构不变量成立：

   # Verify skill files are valid
   for dir in .claude/skills/*/; do
     [[ -f "$dir/SKILL.md" ]] || echo "MISSING: $dir/SKILL.md"
   done
   

2. 上下文文件检查 — 验证上下文文件中的所有技能引用仍然有效

3. 词汇检查 — 确认升级后的技能统一使用领域词汇：

   # Spot-check that vocabulary markers were resolved
   grep -l '{vocabulary\.' .claude/skills/*/SKILL.md 2>/dev/null
   # Should return nothing — all markers should be resolved
   

4. 流水线兼容性 — 如果升级了流水线技能（/{vocabulary.reduce}、/{vocabulary.reflect}、/{vocabulary.reweave}、/{vocabulary.verify}），请验证其与 /ralph 的交接格式兼容

---

最终报告

--=={ upgrade complete }==--

Applied: {N} upgrades
Archived: {N} previous versions to ops/skills-archive/
Skipped: {N} (user-modified, kept as-is)

Changes:
  - /{skill}: {what changed} (Research: "{claim}")
  - /{skill}: {what changed} (Research: "{claim}")

Validation: {PASS | FAIL with details}

{If any validation failed:}
  WARNING: Validation issue detected.
  Previous versions available in ops/skills-archive/
  for manual rollback.

Note: Run /{vocabulary.verify} on a recent {vocabulary.note}
to confirm upgraded skills work correctly in practice.

---

不变量

/upgrade 绝不会自动实施升级。 升级计划始终会先提交给用户。由用户决定应用哪些升级。这样可以防止系统在用户不了解的情况下自行更改这一认知外包失效模式。

所有升级都仅供参考。文件由用户掌控。

---

边界情况

没有可用的改进： 报告“所有技能均符合当前最佳实践，无需升级。”并注明已检查的技能数量。

没有生成清单： 将所有技能视为版本 0（生成状态未知）。将方法与当前知识库进行比较。这没有问题——咨询关注的是方法，而非版本号。

技能已被用户修改： 展示并排对比，并提供三个选项：保留用户版本、将升级与自定义内容合并，或替换（并存档）。绝不静默覆盖。

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

知识库不可用： 报告知识库咨询需要 Ars Contexta 插件。没有该插件附带的 methodology/ 和 reference/ 目录，/upgrade 就无法评估技能。

用户持续拒绝升级： 这是一个信号，而不是错误。记录这一模式——这可能意味着知识库建议与该用户的领域不匹配。如果这一情况在多次 /upgrade 运行中持续出现，请记录到 ops/observations/。

修正与用户修改冲突： 当知识库指出需要修正（而不只是增强），但用户已修改该技能时，请清楚说明冲突。用户可能正是因为原有方法有误才修改技能——他们的修正可能已经解决了这一问题。展示两者并由用户决定。

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