ss-update

在此工作流之前，请先执行每个会话一次的更新预检。

StyleSeed 更新

以注册表为先的制品边界

当 .styleseed/project.json 和 .styleseed/artifacts/index.json 存在时，先解析请求的制品 ID，然后只读取 .styleseed/bundles/<artifact-id>.md 和 .styleseed/manifests/<artifact-id>.json。对于注册表项目，绝不可回退到全局旧版 bundle。只有在不存在注册表时，旧版项目才可以使用 .styleseed/effective-rules.md。

更新的是引擎负载，而不是用户的产品 UI。发布版本表示一个已发布的版本线；engineRevision 标识确切维护的规则、技能、入口文档和调色板引擎。两个安装的发布版本相同，并不能证明它们相同，除非其修订版本也匹配。

检查器会验证当前安装渠道的负载。仓库／插件检出使用完整的 core 清单；项目本地的 Agent Skills 安装使用可执行的 skills 清单。已发布的端点必须同时公开引擎 revision，以及仅安装技能时的 skillsRevision。项目清单会继续记录用于编译其方法 bundle 的引擎修订版本。

捆绑目录还会记录 distributionSource.channel。edge 跟随可变的公共仓库状态；stable 跟随最新的已发布版本清单。除非用户明确要求切换渠道，否则不要直接将 stable 压缩包与 edge main 进行比较。

不适用场景

• 首次安装 → /ss-setup 或 $ss-setup。
• 新建一个屏幕或组件 → /ss-build、/ss-page 或 /ss-component。
• 重新设计旧 UI → 先更新，然后提供下方的可选改造步骤。
• StyleSeed 负载经过大量分叉 → 生成试运行报告后停止，并请求进行手动差异比较。

归属边界

StyleSeed 负责已安装的 ss-* 技能负载以及编译后的 .styleseed/effective-rules.md。项目负责 STYLESEED.md、应用代码、组件、令牌、资源，以及现有的 AGENTS.md、CLAUDE.md 或 Cursor 指令。绝不要仅为了更新 StyleSeed 而覆盖项目所有的文件。

更新可能会改变设计方法的行为，尤其是在跨越主版本时。用户可以通过版本控制回退，但不能保证每次更新都是增量式的或不会造成破坏。

步骤 1 — 只读检查修订状态

在用户的项目根目录中，通过已安装路径运行捆绑的检查器：

node <installed-ss-update>/scripts/check-update.mjs --project-root . --json

严格按以下方式解读结果：

• current — 已安装和已发布的修订版本以及现有注册表制品均匹配；停止操作， 除非用户明确要求重新安装。这不代表已通过视觉／证据检查。
• update-available — 即使语义化版本相同，也要刷新已安装的负载。
• project-bundle-stale — 技能是最新的；跳过重新安装，并重新解析项目。
• legacy-skill-conflict — 已弃用的独立七类别审查器仍与规范技能并存。显示其路径和哈希值；只有确认它不是经过项目修改的技能后，才将其移除。
• remote-check-unavailable — 远程请求失败；报告状态未知，而非当前。
• project-config-invalid — 在声称版本一致之前，先修复不完整／无效的注册表。
• installed-revision-unverified / installed-revision-tampered — 检查本地负载； 切勿盲目覆盖分叉版本。
• remote-revision-unavailable — 仅凭版本证据无法证明版本一致。说明这一限制，不要声称“已是最新”。

对于注册表项目，还要读取排序后的 artifacts 数组。每次都会根据当前制品契约、清单、声明的输出字节和已安装目录计算其状态：

• current — 方法、验证契约和输出字节仍然匹配；
• corrupt — 声明的捆绑包／调色板缺失，或其字节不匹配；
• method-changed — 重新编译，然后重新运行所有实现／渲染证据检查；
• validation-changed — 仅在报告此状态时重新编译，并重新运行标记为 stale 的检查；
• metadata-changed — 针对已安装引擎元数据重新编译；仅元数据变化不会使未变更的视觉证据失效；
• legacy — 在声称制品级别版本一致之前，先迁移该制品。

changedInputs 列出项目自有输入中当前规范化字节与清单不同的项目。如果无法获取先前的验证详情，检查器会采取保守策略，将所有可能受影响的检查标记为过期；它不会根据摘要臆造精确到字段级别的历史记录。

同时检查 git status --short。此步骤中不要修改文件。

步骤 2 — 报告更新范围

进行任何更改之前，先报告：

StyleSeed update report
- Installed: <version> @ <revision>
- Installed channel: <stable|edge|legacy-edge>
- Installed payload: <core|skills> @ <distribution revision>
- Published: <version> @ <revision>
- Project bundle: <version/revision or not resolved>
- Project worktree: clean | has existing changes
- Will refresh: canonical ss-* skill payloads
- Will preserve: STYLESEED.md, app code, components, tokens, assets, project instructions
- Requires review: compiled rule-bundle diff and any copied legacy engine docs

如果工作树中有无关更改，请予以保留。建议在更新方法之前提交或备份，但不要使用会造成破坏的 reset/checkout 命令作为更新策略。

步骤 3 — 通过原始安装渠道刷新

使用安装 StyleSeed 时所用的相同渠道：

• 通过 Edge Agent Skills CLI 安装：运行返回的 installed.install 命令（通常为 npx skills add bitjaru/styleseed），并选择相同的项目／提供商范围。
• 通过 Stable Agent Skills CLI 安装：运行 npx skills add <remote.archiveUrl> --agent codex --yes --copy，使用检查器返回的精确最新发布归档 URL。
• Claude/plugin 或其他提供商市场：使用该提供商的常规更新操作。
• Vendored source checkout：获取目标标签或提交，审查差异，并整体更新规范引擎。不要混用两个修订版本中的文件。

不要通过盲目递归复制到现有技能目录来实现更新。安装程序必须协调受管理的负载；项目自有文件应留在该操作范围之外。刷新时不要擅自将 stable 更改为 edge，或将 edge 更改为 stable。

如果调用此技能仅为检查可用性，请在执行外部刷新之前停止并呈现报告。

步骤 4 — 验证已安装的修订版本

再次运行新检查器的路径。只有在已安装和已发布的 engineRevision 值匹配时，才能称引擎为当前版本。仅版本字符串匹配不足以证明这一点。

如果已安装负载仍报告旧修订版本，请停止操作。不要使用混合或未经验证的安装重新编译项目。

第 5 步 — 重新编译项目上下文

对于注册表项目（.styleseed/project.json 加 .styleseed/artifacts/index.json）：

1. 对每个结果中带有 bundleRecompileRequired:true 的资源，使用 resolve-context.mjs --project-root . --artifact <id> --agent <agent> 重新解析。
2. 使用同一条命令并添加 --check 运行，要求退出状态为 0。
3. 保留报告为 current 的资源；不要为了更新一个资源而覆盖所有捆绑包。

对于存在 STYLESEED.md 的旧版项目：

1. 运行已安装的 ss-resolve/scripts/resolve-context.mjs，并添加 --project-root . --from-lock STYLESEED.md --agent <agent>。
2. 检查 .styleseed/effective-rules.md、.styleseed/manifest.json 和生成的 调色板文件的差异。清单必须记录新的 engineRevision。
3. 使用同一条命令并添加 --check 运行；要求退出状态为 0。
4. 报告新旧捆绑包哈希。不要将 llms-full.txt 用作项目上下文。

设计锁会保留选择，但新的引擎版本可能会正确地更改这些选择周围编译后的方法。应展示这些差异，而不是将其隐藏。

第 6 步 — 检查旧版复制文档

较旧的项目可能包含复制来的 DESIGN-LANGUAGE.md、PRODUCT-PRINCIPLES.md、RULESETS.md 或提供方入口文件。检测并报告这些文件。不要覆盖项目的 AGENTS.md、 CLAUDE.md 或 .cursorrules；建议仅替换可明确识别的 StyleSeed 管理区块，或在审核后删除过时的重复方法文件。

可选改造

更新引擎不会重新设计现有界面。如果用户希望进行改造：

1. 对注册表项目，解析所选资源及其项目自有配置；只有在两个注册表文件都不存在时，才确认或创建旧版 STYLESEED.md。注册表不完整或无效属于错误，不得回退；
2. 根据新的有效捆绑包，对流量最高的界面重新评分；
3. 使用 /ss-review 或 $ss-review 获取只读检查结果，然后在获批的实施步骤中应用修复；
4. 使用 /ss-verify 或 $ss-verify 渲染并检查；
5. 报告改造前后的证据；如果旧评分并未实际测量，不得声称测量过。

每个关卡通过后即停止；否则最多进行三轮修正，包括委派的修正轮次。报告剩余故障和实际证据；调用另一项技能不会重置此限额。

完成报告

分别说明以下状态：

• 已安装版本：已验证 | 未验证；
• 项目捆绑包：已重新编译并校验哈希 | 已过时 | 不存在；
• 应用程序代码：未更改 | 已明确改造；
• 代码关卡：已通过 | 未运行；
• 视觉关卡：已根据检查过的渲染结果通过 | 未运行。

绝不要将安装、编译、构建或评分称为视觉验证。