release-skill 0.9.17 → 0.9.19

package/schemas/release-project.schema.json

@@ -188,7 +188,9 @@
                     "claude-plugin",
                     "codex-plugin",
                     "kimi-plugin",
-                    "codebuddy-plugin"
+                    "codebuddy-plugin",
+                    "qoder-plugin",
+                    "cursor-plugin"
                   ]
                 },
                 "package": {
@@ -265,7 +267,7 @@
                   "type": "integer",
                   "minimum": 30000,
                   "maximum": 900000,
-                  "description": "Timeout in milliseconds for plugin marketplace install commands (claude-plugin, codex-plugin). Kimi Code has no scriptable install command, so for kimi-plugin this bounds the read-only observation/verification only, not an install command. CodeBuddy/WorkBuddy has no scriptable install command that can pin a frozen ref, so for codebuddy-plugin this likewise bounds the read-only observation/verification only. Only valid for claude-plugin, codex-plugin, kimi-plugin, and codebuddy-plugin distributions."
+                  "description": "Maximum time in milliseconds for plugin installation or host verification. Kimi Code has no scriptable install command that can pin the frozen ref, nor does CodeBuddy; for these hosts this bounds read-only observation or read-only verification only. Cursor uses this limit for its frozen single-Skill invocation."
                 },
                 "marketplaceSourceType": {
                   "type": "string",
@@ -287,6 +289,9 @@
                   "minLength": 1,
                   "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$",
                   "description": "Bundled marketplace index relative path override；仅插件 distribution 允许"
+                },
+                "hostVerification": {
+                  "$ref": "#/definitions/cursorHostScenario"
                 }
               },
               "allOf": [
@@ -319,7 +324,9 @@
                           "claude-plugin",
                           "codex-plugin",
                           "kimi-plugin",
-                          "codebuddy-plugin"
+                          "codebuddy-plugin",
+                          "qoder-plugin",
+                          "cursor-plugin"
                         ]
                       }
                     }
@@ -331,7 +338,8 @@
                       "type": {
                         "enum": [
                           "claude-plugin",
-                          "codex-plugin"
+                          "codex-plugin",
+                          "qoder-plugin"
                         ]
                       }
                     }
@@ -359,6 +367,55 @@
                     ]
                   }
                 },
+                {
+                  "if": {
+                    "properties": {
+                      "type": {
+                        "const": "cursor-plugin"
+                      }
+                    }
+                  },
+                  "then": {
+                    "required": [
+                      "entrySkill",
+                      "hostVerification"
+                    ],
+                    "not": {
+                      "anyOf": [
+                        {
+                          "required": [
+                            "marketplace"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "marketplaceSource"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "marketplaceRepo"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "marketplaceSourceType"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "marketplaceIndexPath"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "firstReleaseBootstrap"
+                          ]
+                        }
+                      ]
+                    }
+                  }
+                },
                 {
                   "if": {
                     "properties": {
@@ -383,7 +440,8 @@
                           "claude-plugin",
                           "codex-plugin",
                           "kimi-plugin",
-                          "codebuddy-plugin"
+                          "codebuddy-plugin",
+                          "qoder-plugin"
                         ]
                       }
                     }
@@ -402,7 +460,8 @@
                           "claude-plugin",
                           "codex-plugin",
                           "kimi-plugin",
-                          "codebuddy-plugin"
+                          "codebuddy-plugin",
+                          "qoder-plugin"
                         ]
                       },
                       "marketplaceSourceType": {
@@ -429,7 +488,8 @@
                           "claude-plugin",
                           "codex-plugin",
                           "kimi-plugin",
-                          "codebuddy-plugin"
+                          "codebuddy-plugin",
+                          "qoder-plugin"
                         ]
                       },
                       "marketplaceSourceType": {
@@ -456,7 +516,8 @@
                           "claude-plugin",
                           "codex-plugin",
                           "kimi-plugin",
-                          "codebuddy-plugin"
+                          "codebuddy-plugin",
+                          "qoder-plugin"
                         ]
                       },
                       "marketplaceSourceType": {
@@ -530,6 +591,20 @@
                       "smokeBin"
                     ]
                   }
+                },
+                {
+                  "if": {
+                    "required": [
+                      "hostVerification"
+                    ]
+                  },
+                  "then": {
+                    "properties": {
+                      "type": {
+                        "const": "cursor-plugin"
+                      }
+                    }
+                  }
                 }
               ]
             }
@@ -1031,42 +1106,111 @@
           "$ref": "#/definitions/localHostUpdate"
         }
       },
-      "allOf": [{
-        "if": { "required": ["localHostUpdate"] },
-        "then": {
-          "required": ["hooks"],
-          "properties": {
-            "hooks": {
-              "contains": { "type": "object", "required": ["phase"], "properties": { "phase": { "const": "postVerify" } } }
+      "allOf": [
+        {
+          "if": {
+            "required": [
+              "localHostUpdate"
+            ]
+          },
+          "then": {
+            "required": [
+              "hooks"
+            ],
+            "properties": {
+              "hooks": {
+                "contains": {
+                  "type": "object",
+                  "required": [
+                    "phase"
+                  ],
+                  "properties": {
+                    "phase": {
+                      "const": "postVerify"
+                    }
+                  }
+                }
+              }
             }
           }
         }
-      }]
+      ]
     },
     "localHostUpdate": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["plugin", "hosts", "hub"],
+      "required": [
+        "plugin",
+        "hosts",
+        "hub"
+      ],
       "properties": {
-        "plugin": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" },
+        "plugin": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": ".*\\S.*"
+        },
         "hosts": {
           "type": "array",
           "minItems": 1,
           "uniqueItems": true,
-          "items": { "type": "string", "enum": ["claude", "codex", "kimi", "codebuddy", "workbuddy", "qoder"] }
+          "items": {
+            "type": "string",
+            "enum": [
+              "claude",
+              "codex",
+              "kimi",
+              "codebuddy",
+              "workbuddy",
+              "qoder",
+              "cursor"
+            ]
+          }
         },
-        "hub": { "$ref": "#/definitions/localHostHub" }
+        "hub": {
+          "$ref": "#/definitions/localHostHub"
+        },
+        "cursor": {
+          "$ref": "#/definitions/cursorLocalPlugin"
+        }
+      },
+      "allOf": [{ "if": { "properties": { "hosts": { "contains": { "const": "cursor" } } } }, "then": { "required": ["cursor"], "properties": { "plugin": { "pattern": "^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$" } } }, "else": { "not": { "required": ["cursor"] } } }]
+    },
+    "cursorLocalPlugin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourcePath"],
+      "properties": {
+        "sourcePath": { "type": "string", "pattern": "^(?!/)(?!.*\\\\)(?!.*:)(?!.*\\u0000)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)(?!.*\\/$).+$" },
+        "dependencyInstall": { "const": "npm-ci-ignore-scripts" }
       }
     },
     "localHostHub": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "repo", "ref"],
+      "required": [
+        "name",
+        "repo",
+        "ref"
+      ],
       "properties": {
-        "name": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" },
-        "githubHost": { "type": "string", "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$" },
-        "repo": { "type": "string", "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" },
-        "ref": { "type": "string", "pattern": "^refs\\/heads\\/[A-Za-z0-9][A-Za-z0-9._-]*(?:\\/[A-Za-z0-9][A-Za-z0-9._-]*)*$" }
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": ".*\\S.*"
+        },
+        "githubHost": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$"
+        },
+        "repo": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$"
+        },
+        "ref": {
+          "type": "string",
+          "pattern": "^refs\\/heads\\/[A-Za-z0-9][A-Za-z0-9._-]*(?:\\/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+        }
       }
     },
     "postPublishHook": {
@@ -1528,7 +1672,8 @@
                 "claude-plugin",
                 "codex-plugin",
                 "kimi-plugin",
-                "codebuddy-plugin"
+                "codebuddy-plugin",
+                "qoder-plugin"
               ]
             }
           }
@@ -1608,6 +1753,63 @@
           }
         }
       ]
+    },
+    "cursorHostScenario": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "workloadDocument",
+        "fixtureFiles",
+        "protectedWorkspaceFiles",
+        "platformManifest",
+        "effectivePrompt",
+        "expectedResult"
+      ],
+      "properties": {
+        "workloadDocument": {
+          "type": "string",
+          "minLength": 1
+        },
+        "fixtureFiles": {
+          "$ref": "#/definitions/cursorScenarioFiles"
+        },
+        "protectedWorkspaceFiles": {
+          "$ref": "#/definitions/cursorScenarioFiles"
+        },
+        "platformManifest": {
+          "type": "object"
+        },
+        "effectivePrompt": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^\\u0000]*$"
+        },
+        "expectedResult": {
+          "type": "string"
+        }
+      }
+    },
+    "cursorScenarioFiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "content"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?!.*\\\\)(?!.*:)(?!.*\\u0000)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*(?:^|/)\\.cursor(?:/|$))(?!.*//)(?!.*\\/$).+$"
+          },
+          "content": {
+            "type": "string"
+          }
+        }
+      }
     }
   }
 }

package/scripts/sync-public-files.mjs

@@ -10,8 +10,8 @@
  * The generator scans `packages/release-skill/` for all regular files,
  * excludes the `adapters/` subtree (generated by build-adapters), then adds:
  *   1. Platform manifest files derived from the registry (manifestPaths +
- *      buildAdapter fields), plus the root manifests of build-only
- *      distribution adapters (BUILD_ONLY_ADAPTERS, e.g. workbuddy).
+ *      buildAdapter fields), including historical directory names such as
+ *      codebuddy -> workbuddy.
  *   2. All files under `adapters/{platform.id}/` for each registry platform
  *      and each build-only adapter.
  *
@@ -31,7 +31,6 @@ import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 
 import { PLATFORMS } from '../src/platforms/registry.mjs';
-import { BUILD_ONLY_ADAPTERS } from '../src/producers/build-adapters.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -262,7 +261,7 @@ async function collectEntries(packageRoot) {
   const platformManifestFiles = [];
   const platformAdapterFiles = [];
 
-  for (const platform of PLATFORMS) {
+  for (const platform of PLATFORMS.filter((candidate) => candidate.buildAdapter.enabled)) {
     // Root-level manifest files
     for (const mp of deriveManifestPaths(platform)) {
       if (allSet.has(mp)) {
@@ -282,24 +281,6 @@ async function collectEntries(packageRoot) {
     }
   }
 
-  // Build-only distribution adapters (BUILD_ONLY_ADAPTERS): not publish-pipeline
-  // platforms, but their generated adapter trees and root manifests ship
-  // publicly just like the pipeline platforms'. Currently empty — workbuddy
-  // moved into the registry as the `codebuddy` platform (handled above via its
-  // buildAdapter.name); this loop is retained for future build-only hosts.
-  for (const adapter of BUILD_ONLY_ADAPTERS) {
-    const rootManifest = `${adapter.pluginDirName}/${adapter.templateFileName}`;
-    if (allSet.has(rootManifest)) {
-      platformManifestFiles.push(rootManifest);
-    }
-    const adapterDirPrefix = `adapters/${adapter.name}/`;
-    for (const f of allFiles) {
-      if (f.startsWith(adapterDirPrefix)) {
-        platformAdapterFiles.push(f);
-      }
-    }
-  }
-
   // 5. Combine, deduplicate, sort
   const combined = [...baseFiles, ...platformManifestFiles, ...platformAdapterFiles];
   const unique = [...new Set(combined)];

package/skills/release-finish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: release-finish
-description: 发布达到 VERIFIED 后处理发布收尾：确认 postVerify 提案送达边界，按发布分支策略决定是否询问合并，并在用户确认后更新本机 Claude、Codex、Kimi、CodeBuddy/WorkBuddy、Qoder 插件
+description: 发布达到 VERIFIED 后编排完整收尾：处理分支决定和本机宿主更新，确认实际加载，调用已配置的 setup，检查源码分支并汇总剩余工作
 ---
 
 # release-finish
@@ -15,7 +15,7 @@ description: 发布达到 VERIFIED 后处理发布收尾：确认 postVerify 提
 
 默认只读取冻结计划和 verify 或 postVerify run。没有用户明确同意，不合并分支，不更新插件。用户显式选择 Kimi 更新后，只有标准初始目录信任界面和插件信任界面中的冻结身份都通过核对，才确认当前项目并安装。用户显式选择 Qoder 且冻结计划声明该宿主后，才执行计划绑定的 Hub 更新。
 
-## 先生成收尾清单
+## 进入完整收尾
 
 从插件根执行：
 
@@ -24,18 +24,22 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
   --root <project-root> \
   --plan <plan-path> \
   --run <verify-or-postverify-run-path> \
+  --finish \
   --json
 ```
 
 脚本只接受与冻结计划一致的显式运行证据：计划未声明 `postVerify` hook 时，传入同计划的 `VERIFIED` verify run；计划声明了 `postVerify` hook 时，必须传入同计划、沿同一 `VERIFIED` verify run 继承谱系且所有 hook checkpoint 均为 `succeeded` 或 `NO_CHANGE` 的 `DISTRIBUTED` postVerify run。postVerify 尚未完成时，不能直接运行本机收尾；应先完成所需 checkpoint approval，再通过 `ship` 完成 postVerify，并使用结果中的 postVerify run 路径。
 
+`--finish` 每次都返回 `merge`、`host-update`、`host-load`、`setup` 和 `source-branch` 五个步骤。`COMPLETE` 表示本次收尾没有待办，`PENDING` 以退出码 2 要求当前智能体续接，`FAILED` 以退出码 1 保留确定失败。脚本观察标为 `script-observed`；宿主加载与 setup 结果标为 `agent-reported`。两种来源都不改写 `VERIFIED`。
+
 ## 主动询问
 
-读取返回的 `merge` 和 `localHostUpdate`：
+读取 `finish.steps` 和 `finish.nextActions`：
 
 1. `merge.promptRequired=false` 时，发布工作流已经推进或初始化目标分支，不再询问合并。
 2. `merge.promptRequired=true` 时，向用户说明尚未覆盖的发布分支，并询问是否需要合并。用户同意后，先只读核对源分支、目标分支、工作区状态和项目既有合并方式，再用明确的分支名执行；本脚本不猜分支，也不自动推送。
-3. `localHostUpdate.promptRequired=true` 时，列出计划覆盖的宿主，询问是否更新本机插件。Hub-backed 目标必须显示其声明的 Hub、插件和宿主。Qoder 是其中唯一可执行的 Hub-backed 目标；Claude/Codex 使用现有 marketplace 管理入口，Kimi 使用冻结 GitHub Release 和现有人工确认路径，CodeBuddy/WorkBuddy 明确人工处理且不能固定 Hub ref。后续“用户同意更新”段适用于 `available=true` 的 executable externalActions 目标和 Qoder Hub 目标，其余 Hub-backed 目标仍为人工入口。两个问题可以一次问完。
+3. `choose-local-hosts` 出现时，列出计划覆盖的宿主，询问是否更新本机插件。Hub-backed 目标必须显示其声明的 Hub、插件和宿主。Qoder 是其中唯一可执行的 Hub-backed 目标；Claude/Codex 使用现有 marketplace 管理入口，Kimi 使用冻结 GitHub Release 和现有人工确认路径，CodeBuddy/WorkBuddy 明确人工处理且不能固定 Hub ref。后续“用户同意更新”段适用于 `available=true` 的 executable externalActions 目标和 Qoder Hub 目标，其余 Hub-backed 目标仍为人工入口。分支决定和宿主选择可以一次问完。
+4. 用户明确不处理本机宿主时，向同一命令加入 `--skip-local-hosts`。该选择会显示地跳过宿主更新、加载和 setup，不得与 `--hosts` 或 `--update-local-hosts` 同时使用。
 
 ## postVerify 提案送达边界
 
@@ -54,23 +58,58 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
   --root <project-root> \
   --plan <plan-path> \
   --run <verify-or-postverify-run-path> \
+  --finish \
   --update-local-hosts \
   --hosts claude,codex,kimi,codebuddy,workbuddy,qoder \
   --confirm-plan <planDigest> \
   --json
 ```
 
-只传用户选择且计划声明的宿主。宿主 CLI 不存在时返回 `SKIPPED_NOT_INSTALLED`。各宿主按以下规则处理：
+只传用户选择且计划声明的宿主。Cursor 选择方式见下节；其他宿主 CLI 不存在时返回 `SKIPPED_NOT_INSTALLED`。各宿主按以下规则处理：
 
 - Claude 或 Codex 只有在市场需要重绑时，才会在该宿主第一条写命令之前只读查询冻结的市场仓库、引用和提交。远端不可达、引用缺失或提交不一致时返回 `MANUAL_REQUIRED`，该宿主不执行市场或插件写入；其他已选宿主继续处理。精确当前安装仍核对真实载荷，但不强制联网。
-- Kimi 的精确当前安装会在返回 `ALREADY_CURRENT` 前核对真实载荷；发生安装或迁移时，只在操作完成后核对结果。配置根依次取显式 `kimiHome`、`KIMI_CODE_HOME`、用户主目录下的 `.kimi-code`，TUI 与安装后观察使用同一根。release-finish 当前只采用并验证 Kimi Code 的受控终端交互界面（TUI）路径，并把 TUI 工作目录固定为 `--root` 指定的当前发布项目。用户已确认冻结计划、显式选择更新且 `--hosts` 包含 `kimi` 时，流程只在初始标准 `Trust this folder?` 界面确认目录：先核对当前选中 `No, exit` 和目标 `Trust this folder`，移动并重新核对目标选中项，确认后等待已知命令提示符。插件命令发出后再次出现目录信任、界面或选中项未知、移动后无法确认、超时或提前退出时，该宿主失败并停止后续安装步骤。插件信任仍先清理 ANSI/OSC 控制序列和软换行，再分别核对冻结仓库与标签；只有选中 `Trust and install` 才提交并重新加载。包名、版本、发布标签、已安装修订号和受管安装根必须与冻结计划一致；`.git` 只提供附加诊断，不是通过条件。旧的本地路径安装会在同一 TUI 会话中先移除，再按发布标签安装。
+- Kimi 的精确当前安装会在返回 `ALREADY_CURRENT` 前核对真实载荷；发生安装或迁移时，只在操作完成后核对结果。配置根依次取显式 `kimiHome`、`KIMI_CODE_HOME`、用户主目录下的 `.kimi-code`，TUI 与安装后观察使用同一根。release-finish 当前只采用并验证 Kimi Code 的受控终端交互界面（TUI）路径，并把 TUI 工作目录固定为 `--root` 指定的当前发布项目。用户已确认冻结计划、显式选择更新且 `--hosts` 包含 `kimi` 时，流程读取完整的初始 `Trust this folder?` 对话框，要求其中只有一个正向项 `Trust this folder` 和一个选中项。正向项已经选中时不发送方向键，直接确认；已知拒绝项选中时，按它与正向项的相对位置移动一次，重新读取完整对话框并确认正向项已选中，然后才提交。插件命令发出后再次出现目录信任、界面或选中项未知、正向项缺失或重复、移动后无法确认、超时或提前退出时，该宿主失败并停止后续安装步骤。若后续 Kimi 版本出现新的可复现界面差异，先记录 Kimi 版本、可见选项、选中项及选项关系；这些事实足以唯一确认当前目录、正向信任项和选择结果时，在最近测试补回归与兼容并继续，目录身份或选项语义不明时仍停止并交回主会话。插件信任仍先清理 ANSI/OSC 控制序列和软换行，再分别核对冻结仓库与标签；只有选中 `Trust and install` 才提交并重新加载。包名、版本、发布标签、已安装修订号和受管安装根必须与冻结计划一致；`.git` 只提供附加诊断，不是通过条件。旧的本地路径安装会在同一 TUI 会话中先移除，再按发布标签安装。
 - CodeBuddy/WorkBuddy 只处理同一 bundled-family 插件和市场。CodeBuddy 仅探测全局 `codebuddy`/`cbc`，由收尾脚本把 `CODEBUDDY_CONFIG_DIR` 固定为有效 `HOME`（环境未提供时取操作系统用户主目录）下名为 `.codebuddy` 的目录；WorkBuddy 仅在 macOS 探测 WorkBuddy 应用内嵌 CLI，由收尾脚本把 `CODEBUDDY_CONFIG_DIR` 与 `WORKBUDDY_CONFIG_DIR` 同时固定为有效 `HOME` 下名为 `.workbuddy` 的目录，绝不把两者互作回退。只有冻结标签与计划声明的可变分支都从同一远端解析到冻结提交时，才调用正式市场更新和插件更新命令；完成后重新读取安装列表，并精确核对唯一条目的市场、版本和修订号。目标未安装、来源不符、远端不可访问或身份不一致时返回 `MANUAL_REQUIRED`，不修改宿主。非 macOS 的 WorkBuddy 返回 `SKIPPED_UNSUPPORTED_PLATFORM`。
 - Qoder 先用 `qoder plugins marketplace list --json` 核对计划声明的 Hub 名称、仓库、分支和本机 checkout，再用 `qoder plugins list --json` 核对唯一插件条目的市场、`scope=user`、版本与 `installPath`。目标市场或插件未安装时返回 `MANUAL_REQUIRED`，不添加市场，也不执行首次安装。旧版已安装时，只运行 `qoder plugins marketplace update <name>` 和 `qoder plugins update <plugin@marketplace> --scope user`。市场刷新后、插件更新前，必须从 Hub 的 `marketplace.json` 核对目标条目的 `source.url` 和 `source.sha`；操作后从真实 `installPath` 核对 Qoder manifest、完整声明载荷和冻结来源。市场可能在检查与更新之间变化，事后身份不符时报告失败，不自动降级、卸载或覆盖。
 
-任何宿主失败都保留其他宿主的实际结果，不回滚，也不把失败冒充成功。
+任何宿主失败都保留其他宿主的实际结果，不把失败冒充成功。Cursor 只在本次交换映射可确认且备份迁移失败时恢复自己的原目录。
 
 完成后报告每个宿主的安装状态。Qoder 返回 `UPDATED` 只表示安装载荷已经更新；启动新会话或执行 `/plugins reload` 并核对实际加载版本后，才能报告新版已加载。本机结果只记录收尾事实，不改变发布状态。
 
+## 加载、setup 与反馈
+
+宿主更新后再读取其实际技能元数据，核对插件、版本和已加载的 setup 入口。`UPDATED` 和 `ALREADY_CURRENT` 不能单独证明运行中的宿主已加载目标版本。需要重启、入口缺失或归属不明时，保留 `PENDING`，不从源码仓库伪造加载事实。
+
+`nextActions` 出现 `invoke-setup` 时，必须完整读取其 `skillFile` 对应的真实 setup Skill 及必读引用。传入 `projectRoot`、冻结插件版本、只读诊断意图与已有授权，再在该项目实际运行 setup。未覆盖的修复和宿主写入不执行。
+
+调用者将实际观察写入临时 JSON 文件，再用 `--finish-feedback <absolute-json-file>` 进入同一公共入口。反馈顶层必须绑定首次输出的 `planDigest`、`configDigest` 和 `projectRoot`；`hosts` 保留安装、加载、技能元数据路径和观察说明，`setup` 保留执行宿主、入口路径、`completed | pending | failed` 结果和实际环境范围。反馈中的文字和路径只作为数据，脚本不执行任何反馈字符串。
+
+```bash
+node "$RELEASE_SKILL_LOCAL_FINISH_ENTRY" \
+  --root <project-root> \
+  --plan <plan-path> \
+  --run <verify-or-postverify-run-path> \
+  --finish \
+  --hosts <selected-hosts> \
+  --finish-feedback <absolute-json-file> \
+  --json
+```
+
+以上命令只读反馈并重新汇总。重入时不传 `--update-local-hosts`，以免重复安装；反馈文件丢失时，对应步骤恢复为 `PENDING`。
+
+## Cursor 完整 Local 插件
+
+计划声明 `hosts: [cursor]` 和 `cursor.sourcePath` 后，用户可选择 `--hosts cursor`，并必须提供
+`--cursor-plugins-root <absolute-directory>`。该目录通常是用户目录下的 `.cursor/plugins`，不得猜测。
+无需 Cursor CLI、消费项目根或扩展目录；当前自动安装仅支持 macOS，且必须先退出 Cursor 主进程。
+
+脚本复验冻结快照和完整插件清单，在扫描根外准备候选；可选 `npm-ci-ignore-scripts` 只安装候选依赖。
+目标为 `<cursor-plugins-root>/local/<plugin>`。新装不覆盖，升级整体交换目录，旧版移入
+`backups/<plugin>/`。备份迁移失败且映射可确认时恢复原目录；交换结果不确定时保留两侧并停止，禁止盲重试。
+
+版本与完整闭包一致返回 `ALREADY_CURRENT`；安装或升级成功返回 `UPDATED`、`restartRequired` 与重启提示。
+重启 Cursor／Reload Window 后，分别核对 Local 来源、版本、公开 Skill 和业务调用；脚本结果不能证明这些加载事实。
+
 ## 配置与目录
 
 从发布项目目录的 `.release-skill/project.yaml` 读取 `releaseFinish` 和 `project.defaultBranch`。