| 1 | # Reasonix 插件包 |
| 2 | |
| 3 | Reasonix 插件包把 skills、hooks、MCP servers、prompts、主题和代码型扩展组织成一个可安装单元。 |
| 4 | |
| 5 | ## CLI 模式 |
| 6 | |
| 7 | 在终端里使用 `reasonix plugin` 安装和管理插件包。插件包当前按全局范围安装， |
| 8 | 写入 Reasonix home 目录。 |
| 9 | |
| 10 | ### 通过 CLI 安装 |
| 11 | |
| 12 | `install` 接收一个来源： |
| 13 | |
| 14 | - GitHub 仓库，例如 `git:github.com/obra/superpowers` 或 |
| 15 | `https://github.com/obra/superpowers`。 |
| 16 | - GitHub 分支或子目录 URL，例如 |
| 17 | `https://github.com/owner/repo/tree/main/path/to/plugin`。 |
| 18 | - 本地目录，目录内需要包含 `reasonix-plugin.json`、 |
| 19 | `.codex-plugin/plugin.json` 或 `.claude-plugin/plugin.json`。 |
| 20 | |
| 21 | 只预览安装计划，不写文件： |
| 22 | |
| 23 | ```bash |
| 24 | reasonix plugin install git:github.com/obra/superpowers --dry-run |
| 25 | ``` |
| 26 | |
| 27 | 确认计划后安装： |
| 28 | |
| 29 | ```bash |
| 30 | reasonix plugin install git:github.com/obra/superpowers --yes |
| 31 | ``` |
| 32 | |
| 33 | 指定安装名称，或覆盖已安装的同名插件： |
| 34 | |
| 35 | ```bash |
| 36 | reasonix plugin install git:github.com/obra/superpowers --name superpowers --replace --yes |
| 37 | ``` |
| 38 | |
| 39 | 以开发模式使用本地目录： |
| 40 | |
| 41 | ```bash |
| 42 | reasonix plugin install /path/to/plugin --link --replace --yes |
| 43 | ``` |
| 44 | |
| 45 | CLI 安装参数： |
| 46 | |
| 47 | - `--dry-run` 只规划和校验安装，不写文件。 |
| 48 | - `--yes` 用于确认执行会写文件的安装。 |
| 49 | - `--replace` 允许当前来源替换已安装的同名插件。 |
| 50 | - `--name <name>` 或 `--name=<name>` 覆盖插件 manifest 里的名称， |
| 51 | 作为本次安装名称。 |
| 52 | - `--link` 链接本地插件目录，而不是复制到 Reasonix 的插件存储目录。 |
| 53 | 移动或删除该目录会导致这个链接插件失效。 |
| 54 | |
| 55 | 如果运行 `reasonix plugin install <source>` 时既没有 `--dry-run`， |
| 56 | 也没有 `--yes`，CLI 会拒绝写文件，并提示使用其中一个参数重新运行。 |
| 57 | 安装和移除命令会输出结构化 JSON，来源于桌面端同一套 install-source 后端。 |
| 58 | |
| 59 | 插件状态和内容写入： |
| 60 | |
| 61 | ```text |
| 62 | ~/.reasonix/plugin-packages.json |
| 63 | ~/.reasonix/plugins/<name>/ |
| 64 | ``` |
| 65 | |
| 66 | ### 通过 CLI 管理 |
| 67 | |
| 68 | 列出已安装插件： |
| 69 | |
| 70 | ```bash |
| 71 | reasonix plugin list |
| 72 | ``` |
| 73 | |
| 74 | 查看某个插件的元数据、根目录、来源以及导出的能力数量： |
| 75 | |
| 76 | ```bash |
| 77 | reasonix plugin show superpowers |
| 78 | ``` |
| 79 | |
| 80 | 如果能读取到能力明细，`show` 也会输出具体清单： |
| 81 | |
| 82 | - **skills** 会展示建议的 `/<插件名>:<技能名>` 调用方式和描述。 |
| 83 | - **commands** 会展示 `/<插件名>:<命令名>` 调用方式、参数提示和描述。 |
| 84 | - **hooks** 会展示生命周期事件、matcher、命令或上下文文件。 |
| 85 | - **mcpServers** 会展示服务器名称、传输方式和启动目标。 |
| 86 | |
| 87 | 检查 manifest 和 skill roots 是否可读： |
| 88 | |
| 89 | ```bash |
| 90 | reasonix plugin doctor superpowers |
| 91 | ``` |
| 92 | |
| 93 | 工作区级能力总览（skills / hooks / MCP 合并 / 包根目录）见 |
| 94 | [能力诊断](./CAPABILITY_DIAGNOSTICS.zh-CN.md)： |
| 95 | |
| 96 | ```bash |
| 97 | reasonix doctor capabilities --json |
| 98 | # 桌面端：设置 → 诊断 |
| 99 | # Agent： /reasonix-guide |
| 100 | ``` |
| 101 | |
| 102 | 在不卸载的情况下启用或禁用插件： |
| 103 | |
| 104 | ```bash |
| 105 | reasonix plugin disable superpowers |
| 106 | reasonix plugin enable superpowers |
| 107 | ``` |
| 108 | |
| 109 | 移除插件： |
| 110 | |
| 111 | ```bash |
| 112 | reasonix plugin remove superpowers --yes |
| 113 | ``` |
| 114 | |
| 115 | `remove` 也可以写成 `uninstall`。它需要 `--yes`， |
| 116 | 因为会写入状态并删除复制安装的插件内容。如果是链接模式安装的本地插件， |
| 117 | 外部源目录会保留。 |
| 118 | |
| 119 | ### 在 CLI 中使用已安装插件 |
| 120 | |
| 121 | 已安装插件不会打开一个独立聊天界面。插件启用后，Reasonix 会把它的能力加载到普通交互会话里： |
| 122 | |
| 123 | - 在交互会话里运行 `/plugins` 可以列出已安装插件包。 |
| 124 | 运行 `/plugins show <name>` 可以在不离开聊天的情况下查看该插件导出的 |
| 125 | skills、hooks、MCP servers 和使用提示。 |
| 126 | - **Skills** 会出现在 `/skills` 中。可以用 `/<插件名>:<技能名> [args]` 直接调用， |
| 127 | 也可以自然描述任务，让 agent 按 description 选择匹配的 skill。 |
| 128 | - **Hooks** 会在配置的生命周期事件里自动运行，例如 `SessionStart`、 |
| 129 | `UserPromptSubmit`、`PreToolUse` 或 `PostToolUse`。 |
| 130 | - **MCP servers** 会进入正常 MCP/工具流程。用户只需要描述任务， |
| 131 | Reasonix 会在相关时调用插件提供的工具。 |
| 132 | |
| 133 | 如果是在另一个终端里安装、启用、禁用或更新插件，而当前已有 `reasonix` 会话正在运行， |
| 134 | 建议开启新会话，或重新打开 `/skills` 确认当前会话能看到预期技能。 |
| 135 | |
| 136 | ## 桌面端设置 |
| 137 | |
| 138 | 打开 **设置 -> 插件**，可以不用 CLI 直接安装和管理插件包。 |
| 139 | |
| 140 | ### 安装插件 |
| 141 | |
| 142 | 安装区有两种模式： |
| 143 | |
| 144 | - **本地目录**：点击 **选择插件目录**，从磁盘选择一个插件目录。 |
| 145 | 选中路径会显示在按钮右侧。 |
| 146 | - **Git 仓库**：填写 Git 来源，例如 `git:github.com/obra/superpowers`。 |
| 147 | **安装名称（可选）** 可覆盖插件 manifest 声明的名称，用于本次安装或覆盖。 |
| 148 | |
| 149 | 选择来源和选项后，再使用操作按钮： |
| 150 | |
| 151 | - **预检** 校验来源并展示计划安装动作，不写入文件。 |
| 152 | - **安装插件** 按当前来源和选项执行安装。 |
| 153 | - **刷新插件** 从磁盘和配置重新读取已安装插件列表。 |
| 154 | |
| 155 | 安装选项： |
| 156 | |
| 157 | - **覆盖同名插件** 允许当前来源替换已安装的同名插件。关闭时，同名安装会失败， |
| 158 | 而不是覆盖已有内容。 |
| 159 | - **开发模式：链接源目录** 只在 **本地目录** 模式出现。它不会复制插件， |
| 160 | 而是直接链接所选目录；适合开发或调试插件。移动或删除该目录会导致这个链接插件失效。 |
| 161 | |
| 162 | 对新的 Git 来源或本地插件目录，建议先点 **预检**。 |
| 163 | |
| 164 | ### 管理已安装插件 |
| 165 | |
| 166 | 已安装插件列表会展示每个插件包以及它导出的 skills、hooks 和 MCP servers。 |
| 167 | 通过应用外编辑插件文件或配置后，可点 **刷新插件** 重新读取。 |
| 168 | |
| 169 | 展开插件行后可以： |
| 170 | |
| 171 | - 启用或禁用插件。 |
| 172 | - 查看 **使用方法**，了解该插件导出的 skills、hooks 和 MCP servers。 |
| 173 | - 使用 **更新** 拉取或刷新具备更新来源的插件。 |
| 174 | - 使用 **诊断** 检查插件 manifest，并查看警告或诊断信息。 |
| 175 | - 使用 **移除插件**，确认后卸载该插件包。 |
| 176 | |
| 177 | ### 在桌面端使用已安装插件 |
| 178 | |
| 179 | 桌面端设置页和 CLI 使用同一套运行模型： |
| 180 | |
| 181 | - 展开已安装插件，可以看到 **使用方法** 区域。 |
| 182 | - 在任意桌面会话里输入 `/plugins` 可以列出已安装插件； |
| 183 | 输入 `/plugins show <name>` 可以直接从聊天界面查看同一套使用详情。 |
| 184 | - Skills 会展示带插件名的直接命令，例如 `/superpowers:writing-plans`； |
| 185 | 在会话中也可以通过 `/skills` 浏览。 |
| 186 | - 插件命令统一以带插件名的形式展示和调用，例如 `/superpowers:plan`。 |
| 187 | - Hooks 和 MCP servers 作为透明能力清单展示。它们不需要单独的“运行”按钮： |
| 188 | 启用的 hooks 会自动触发，MCP 工具会通过普通工具调用流程可用。 |
| 189 | - 如果当前打开的会话没有反映插件变更，刷新插件列表并开启新会话。 |
| 190 | |
| 191 | ## 原生 Manifest |
| 192 | |
| 193 | Reasonix 原生插件在根目录声明 `reasonix-plugin.json`： |
| 194 | |
| 195 | ```json |
| 196 | { |
| 197 | "name": "example", |
| 198 | "version": "1.0.0", |
| 199 | "description": "Example plugin", |
| 200 | "skills": "skills", |
| 201 | "hooks": { |
| 202 | "SessionStart": [ |
| 203 | { |
| 204 | "command": "hooks/session-start", |
| 205 | "args": [], |
| 206 | "description": "Load startup context" |
| 207 | }, |
| 208 | { |
| 209 | "command": "printf 'ready' && ./hooks/audit", |
| 210 | "shell": "bash", |
| 211 | "description": "Run a compound shell script" |
| 212 | } |
| 213 | ] |
| 214 | }, |
| 215 | "mcpServers": { |
| 216 | "helper": { |
| 217 | "command": "bin/helper" |
| 218 | } |
| 219 | } |
| 220 | } |
| 221 | ``` |
| 222 | |
| 223 | 相对路径都按插件根目录解析。Reasonix 安装插件时不会执行第三方安装脚本。 |
| 224 | |
| 225 | 插件 Hook 的执行形态是显式的： |
| 226 | |
| 227 | - 只要出现 `args`（包括 `"args": []`），就使用 **exec form**。`command` |
| 228 | 是可执行文件，每个参数都会按原值直接传递，不经过 Shell 解析或变量展开。 |
| 229 | - 未提供 `args` 且提供 `shell` 时，使用 **shell form**。完整 `command` |
| 230 | 会原样交给 `bash`、`powershell`/`pwsh`、`cmd`（仅 Windows）或 `auto`。 |
| 231 | Windows 上 `auto` 优先选择 Git Bash，找不到时回退 PowerShell。 |
| 232 | - 既未声明 `args` 也未声明 `shell` 的已有原生 Hook 继续使用 Reasonix |
| 233 | 历史 Shell 命令行为；`shellCommand: true` 仍作为 shell form 的旧写法兼容。 |
| 234 | |
| 235 | ## Manifest v2（扩展） |
| 236 | |
| 237 | Reasonix 原生扩展使用精确的 v2 `apiVersion`： |
| 238 | |
| 239 | ```json |
| 240 | { |
| 241 | "apiVersion": "reasonix.io/plugin/v2", |
| 242 | "name": "example", |
| 243 | "version": "1.0.0", |
| 244 | "description": "Example extension", |
| 245 | "requires": [], |
| 246 | "provides": [ |
| 247 | { |
| 248 | "namespace": "plugin/example", |
| 249 | "kind": "interceptors", |
| 250 | "id": "default", |
| 251 | "version": "1.0.0" |
| 252 | } |
| 253 | ], |
| 254 | "contributes": { |
| 255 | "skills": ["skills"], |
| 256 | "agents": ["agents"], |
| 257 | "commands": ["commands"], |
| 258 | "prompts": ["prompts"], |
| 259 | "hooks": {}, |
| 260 | "mcpServers": {}, |
| 261 | "themes": ["themes/*.reasonix-theme"] |
| 262 | }, |
| 263 | "runtime": { |
| 264 | "command": "${REASONIX_PLUGIN_ROOT}/bin/example", |
| 265 | "args": [], |
| 266 | "env": {}, |
| 267 | "required": true, |
| 268 | "priority": 0, |
| 269 | "intercepts": ["input.receive", "tool.before"], |
| 270 | "replaces": [], |
| 271 | "capabilities": ["interceptors"] |
| 272 | } |
| 273 | } |
| 274 | ``` |
| 275 | |
| 276 | 解析规则： |
| 277 | |
| 278 | - 原生 `reasonix-plugin.json` 必须声明精确值 `reasonix.io/plugin/v2`。 |
| 279 | v1 与缺失版本都会被拒绝；不提供 v1 双读或自动迁移路径。 |
| 280 | - v2 是严格的：根对象或 `contributes`/`runtime` 下的任何未知字段都会 |
| 281 | 报错并指明字段路径，避免拼写错误静默失效。 |
| 282 | - v2 的资源发现是显式的。Reasonix 只加载原生 manifest 中声明的 skills、 |
| 283 | agents、commands、prompts、hooks、MCP servers、themes 与 runtime；不会隐式 |
| 284 | 导入根目录 `CLAUDE.md`、`hooks/hooks.json`、`.claude/settings.json` 或 |
| 285 | `.mcp.json` 等宿主专用 sidecar。 |
| 286 | - minor 别名（如 `reasonix.io/plugin/v2.0`、`v2.1`）及未知 major version |
| 287 | 都会被拒绝。 |
| 288 | - `requires` 与 `provides` 声明依赖约束和能力上限；Sidecar handshake |
| 289 | 不能超出该上限。 |
| 290 | - v2 可以同时使用受支持的顶层资源字段（`skills`、`hooks`、 |
| 291 | `mcpServers` 等）与 |
| 292 | `contributes`：完全相同的路径去重；同名但定义不同的条目报 Manifest |
| 293 | 错误并指明键名。 |
| 294 | - 所有相对路径与 glob 必须位于插件根目录内：拒绝路径穿越、绝对路径、 |
| 295 | 逃逸 symlink 和非普通 theme 文件。 |
| 296 | |
| 297 | 新资源类型： |
| 298 | |
| 299 | - `prompts` 使用与 commands 相同的模板语义和参数替换，公开名为 |
| 300 | `/<plugin>:<name>`；`commands` 保持兼容别名。 |
| 301 | - `themes` 是 `.reasonix-theme` 文件，在 Desktop 设置中以只读插件主题 |
| 302 | 展示（ID 为 `plugin:<plugin>:<theme>`），不会复制进用户主题库。插件 |
| 303 | 被禁用或卸载时，若当前使用的是它的主题，界面回退到基础样式但保留该 |
| 304 | ID，重新安装同一插件后自动恢复。 |
| 305 | |
| 306 | `runtime` 块声明的是代码型扩展——由 Reasonix 启动并通过 Extension |
| 307 | Protocol（基于 stdio 的 JSON-RPC 2.0，方法索引见 |
| 308 | `docs/EXTENSION_PROTOCOL.generated.md`，Go SDK 见 `sdk/go/README.md`） |
| 309 | 驱动的 Sidecar 进程： |
| 310 | |
| 311 | - `command`/`args`/`env` 仅支持 **exec form**：command 即可执行文件， |
| 312 | 绝不经过 Shell 解释；`${REASONIX_PLUGIN_ROOT}` 展开为插件安装根目录。 |
| 313 | - `intercepts` 声明要拦截的事件（如 `input.receive`、`tool.before`、 |
| 314 | `permission.decision`）；`replaces` 声明可以持有的替换槽 |
| 315 | （`system_prompt`、`context`、`provider_request`、`provider_response`、 |
| 316 | `compaction`、`session_policy`、`permission`、`frontend_events`、 |
| 317 | `tool:<name>`、`provider:<ref>`）。同一替换槽在所有已安装插件中只能有 |
| 318 | 一个 owner，争用会导致构建失败并列出来源。 |
| 319 | - `capabilities` 按能力族授权：`interceptors`、`strategies`、`providers`、 |
| 320 | `ui`。Sidecar 在握手时声明的任何超出 Manifest 的能力都会被拒绝。 |
| 321 | - 扩展提供的模型以 `plugin/<plugin>/<provider>/<model>` 形式出现在模型 |
| 322 | 选择器中；该 ref 同样可用作 `default_model`（包括首次启动），并可 |
| 323 | 在 `/model`、Desktop 与 ACP 的模型切换中使用。 |
| 324 | |
| 325 | **完全信任（Full trust）。** 代码型扩展运行在 Sandbox 之外，继承未过滤 |
| 326 | 的完整环境：它可以读取完整会话与环境、绕过权限、直接操作本机；扩展在 |
| 327 | `permission.decision` 上的 "allow" 可以覆盖宿主的 deny。安装、更新、 |
| 328 | 替换或 `--link` 一个带有 `runtime` 块的插件**即代表授权**——不会有二次 |
| 329 | 确认，`--link` 模式在内容变化后自动保持信任。因此安装预览、 |
| 330 | `reasonix plugin show`、能力诊断和 Desktop 安装界面都会显著展示 |
| 331 | `FULL TRUST` 区块，列出 Runtime 命令、Interceptors、替换槽和 |
| 332 | Provider/UI 能力。安装前请确认该区块内容，只安装你完全信任的运行时。 |
| 333 | 只有通过插件安装流程写入插件状态的 Runtime 才能启动；项目配置无法 |
| 334 | 声明代码型 Sidecar。 |
| 335 | |
| 336 | ## Codex 与 Claude 兼容 |
| 337 | |
| 338 | Reasonix 也会读取 `.codex-plugin/plugin.json` 和 `.claude-plugin/plugin.json`。 |
| 339 | 安装预检会结构化显示“完全兼容 / 部分兼容 / 不兼容”、已映射能力和每个被跳过 |
| 340 | 的条目。非原生插件如果没有任何可映射能力，会直接阻止安装，不再留下“安装成功 |
| 341 | 但不可用”的记录。“完全兼容”指清单里声明的每个能力都成功解析并映射到了 |
| 342 | Reasonix 的对应实现，并不代表导入 Hook 的每一种运行时决策都被遵守。 |
| 343 | `PreToolUse`/`PermissionRequest` 的“拒绝”与 `PermissionRequest` 的“批准”已经 |
| 344 | 实现；但 Hook 的 `updatedInput`，以及 `PreToolUse` 的 `ask`/`defer` 决策，是 |
| 345 | 脚本在实际运行时通过 stdout 决定的，并非清单里的静态字段，因此安装阶段无法 |
| 346 | 据此标记——具体已实现范围见下面 Hook 条目。GitHub 仓库若在 |
| 347 | `.claude-plugin/marketplace.json` 中通过 `./plugins/example` 或 |
| 348 | `plugins/example` 这类相对字符串列出多个插件，可以直接从仓库根目录安装； |
| 349 | 预检会在写入前逐项展示安装动作。填写可选安装名称时，可只选择 marketplace |
| 350 | 中的同名插件。对象来源仅接受 GitHub 仓库 URL 加完整 commit SHA；未固定版本的 |
| 351 | 外部字符串、npm、`strict: false` 以及其他高级 marketplace 协议在整库安装时会 |
| 352 | 跳过，按名称选中时则直接报错。 |
| 353 | 对于 Superpowers 和 Claude 风格 skill 包，Reasonix 会映射以下兼容约定。 |
| 354 | 原生 v2 manifest 只使用显式声明，不应用这些回退规则： |
| 355 | |
| 356 | - `skills` 到 Reasonix skill root。Claude 清单若未声明 `skills` 字段，会回退到 |
| 357 | 约定目录 `skills/`（或 `.claude/skills/`），与 Claude 自身的自动发现一致。 |
| 358 | 插件 skill 统一以 `/<插件名>:<技能名>` 展示和调用。无歧义的 `/<技能名>` |
| 359 | 仍作为隐藏兼容别名接受输入；项目和用户 skill 保留短名称，多个插件导出的 |
| 360 | 同名 skill 则只能通过各自的限定名称独立调用。这一用户侧命名空间不会改变 |
| 361 | 模型 skill 索引或 `run_skill` 工具使用的内部短标识。 |
| 362 | - `commands/`（以及 `.claude/commands/`）映射为 Reasonix 自定义斜杠命令：每个 |
| 363 | `<name>.md` 提示词模板统一以 `/<插件名>:<命令名>` 展示和调用，frontmatter 的 |
| 364 | `description` / `argument-hint` 以及 `$ARGUMENTS` / `$1..$N` 替换均生效。 |
| 365 | 当短名称没有歧义时，`/<命令名>` 仍作为隐藏兼容别名接受输入，但不会出现在 |
| 366 | 补全、帮助、桌面菜单、ACP 命令发现或提供给模型的命令清单中。用户和项目命令 |
| 367 | 始终占有自己的短名称；多个插件导出同名命令时不会生成短名称别名。显式自定义 |
| 368 | 命令也可以占用限定名称，Desktop 插件详情会报告该冲突。原生 |
| 369 | `reasonix-plugin.json` 清单也可以通过 `"commands"` 路径列表显式声明。 |
| 370 | - `agents/*.md` 映射为插件所属、需要手动调用的子代理配置。Claude 模型别名会继承 |
| 371 | 当前 Reasonix 模型；内联 `tools` 列表会转换为 Reasonix 工具名，并支持 |
| 372 | `mcp__*__search` 这类 MCP 通配符。Agent 使用独立的 |
| 373 | `/<插件>:agent:<名称>` 命名空间，因此上游 Agent 与 Skill 同名时不会互相遮蔽。 |
| 374 | - 如果存在 `hooks/session-start-codex`，映射为 Reasonix `SessionStart` hook。 |
| 375 | - 对 Codex 兼容包，插件根目录的 `CLAUDE.md` 会映射为内置的 `SessionStart` |
| 376 | 上下文 hook，Reasonix 会直接读取该文件，不通过 shell 命令。Claude 插件 |
| 377 | manifest 会忽略该文件，与 Claude Code 的插件契约保持一致。 |
| 378 | - `.claude/settings.json` 和 `hooks/hooks.json` 里的 command hooks 会按同名事件映射。 |
| 379 | `matcher`、`args`、`shell`、`async`、`env` 和 timeout 均会保留。Claude 的执行契约 |
| 380 | 也会完整保留：只要出现 `args`（即使是空数组）就按 exec form 执行，并逐项原样传参； |
| 381 | 省略 `args` 才按 shell form 执行，将原始命令交给声明的 Bash 或 PowerShell。 |
| 382 | `matcher` 以及 Hook 脚本看到的 |
| 383 | `tool_name` 会在 Reasonix 与 Claude 的工具名之间互译（`bash` ↔ `Bash`、 |
| 384 | `write_file` ↔ `Write` 等），因此 `"Bash"` 这类 matcher 能正确触发；Reasonix 里所有会 |
| 385 | 启动子代理的工具（`task`、`read_only_task`、`parallel_tasks`，以及专用的 |
| 386 | `explore`/`research`/`review`/`security_review` 包装工具）都会映射到 Claude 唯一的 |
| 387 | `Agent` 工具，matcher 里旧名 `Task` 依然可用。`tool_input` 里字段名不同的键也会改名—— |
| 388 | 每个映射后的 `Agent` 载荷都会包含 Claude 必填的 `prompt` 和 `description`；若 |
| 389 | Reasonix 调用省略了可选描述，会补一个稳定的操作标签。 |
| 390 | `Read`/`Write`/`Edit`/`MultiEdit` 的 `path` 改成 `file_path`，`NotebookEdit` 的 |
| 391 | `path` 改成 `notebook_path`，`Skill` 的 `name`/`arguments` 改成 `skill`/`args`， |
| 392 | 当前 `TaskOutput`/`TaskStop` 的 `job_id` 改成 `task_id`，专用子代理包装 |
| 393 | 工具的 `task` 改成 `Agent` 的 `prompt`，`parallel_tasks` 则会把各子任务的 prompt |
| 394 | 合成为 `Agent` 的 `prompt`（原 `tasks` 数组保留）——这样读取 |
| 395 | `.tool_input.file_path` 或 `.tool_input.prompt` 的防护 Hook 才不会因为拿到空值 |
| 396 | 而失败放行。旧的 `BashOutput`/`KillShell` matcher 仍能触发，但下发名称和字段使用 |
| 397 | Claude 当前词汇；`bash_output` 会补齐 `TaskOutput` 的非阻塞必填字段，`wait` 也会 |
| 398 | 映射为 `TaskOutput`，单任务等待时包含 `task_id`，无限等待时省略可选的 |
| 399 | `timeout`，而不是谎报 0 毫秒预算。`AskUserQuestion` 会补省略的 |
| 400 | `multiSelect:false` 和空选项描述；`TodoWrite` 只接受扁平的 `content`、`status`，旧 `activeForm` 会被严格校验拒绝； |
| 401 | `NotebookEdit` 则会从 Reasonix 接受的别名补 `new_source`，删除或空单元格操作补空串。 |
| 402 | 相对的 `file_path`/`notebook_path` 会按载荷 `cwd` 解析为绝对路径， |
| 403 | 与 Claude 文件工具契约一致，前缀匹配的防护 Hook 检查的就是工具实际访问的路径。 |
| 404 | `Bash` 的 `tool_response` 按 Claude 的 `{stdout, stderr, interrupted}` 形态下发 |
| 405 | （Reasonix 的合并输出放在 `stdout`，失败错误文本作为 `stderr`），官方 |
| 406 | security-guidance 插件的 commit/push 检查读取的正是这些字段；其他工具的结果仍按 |
| 407 | 原样透传。导入 Hook 的 |
| 408 | stdin 使用 Claude 兼容的 snake_case 载荷（包括 `hook_event_name`）。宿主会在启动 |
| 409 | 进程前展开 `${CLAUDE_PLUGIN_ROOT}` 和 `${REASONIX_PLUGIN_ROOT}`，也兼容不带花括号的 |
| 410 | `$NAME` 与 Windows `%NAME%` 写法，因此插件相对路径不再依赖目标 shell 的环境变量 |
| 411 | 语法。Windows 上未显式指定 Shell 的 shell-form Hook 会和 Reasonix Shell 工具一样， |
| 412 | 优先选择 Git Bash，找不到时回退 PowerShell；指向带 POSIX shebang 的脚本文件时， |
| 413 | 宿主会把 Windows 路径转换为 Bash 可用形式。显式 Bash Hook 以及旧式裸 |
| 414 | `sh -c`/`bash -c` Hook 会复用 Git for Windows Bash 探测，即使 Bash 不在 |
| 415 | `cmd.exe` 的 `PATH` 中也能执行；带目录的显式解释器路径保持 |
| 416 | 不变。如果机器确实没有可用 Bash，hook 会返回清晰的依赖提示，而不是本地化的 |
| 417 | “无法识别 sh”乱码。通过 `[tools.shell] prefer = "bash"` 和 |
| 418 | `path = ".../bash.exe"` 配置的非标准目录或便携版 Bash 也会被显式 Bash Hook 复用。 |
| 419 | `reasonix plugin doctor <名称>` 和 `reasonix doctor capabilities` 会在 Hook 首次触发前 |
| 420 | 报告缺失的 Shell 依赖。旧代码页输出也会在进入界面前转换为 UTF-8。`PreToolUse` 和 |
| 421 | `UserPromptSubmit` hook 仍可 |
| 422 | 通过退出码 2 或退出码 0 时的 JSON 拒绝形态拒绝该次调用（`PreToolUse` 用 |
| 423 | `hookSpecificOutput.permissionDecision`，`UserPromptSubmit` 用顶层 |
| 424 | `decision:"block"`）；导入的 `PermissionRequest` hook 还能直接代答权限弹窗 |
| 425 | （拒绝或自动批准，而不只是发通知），通过退出码 2 或 |
| 426 | `hookSpecificOutput.decision.behavior` 实现，与 Claude 官方语义保持一致。 |
| 427 | `updatedInput` 暂未应用到实际工具调用参数；Hook 的 `if` 条件和 `asyncRewake` |
| 428 | 字段也不会被求值。声明其中之一、声明 `Stop`/`SubagentStop` hook（Reasonix 中 |
| 429 | 不能阻止本轮结束），或 matcher 覆盖三种无法无损表达的输入时，插件都会报告 |
| 430 | 部分兼容并附具体警告：`WebFetch.prompt`、Reasonix 以 `cell_number` 调用时的 |
| 431 | `NotebookEdit.cell_id`，以及 Reasonix `wait` 同时覆盖多个/全部任务时的 |
| 432 | `TaskOutput.task_id`。每类结构性缺口在每个 hooks 文件里只报告一次， |
| 433 | 通配 matcher 的插件每类缺口只会看到一条警告，而不是每个 hook 一条。 |
| 434 | - 插件根目录 `.mcp.json` 会映射为已安装 MCP。Claude 的 `local` 会转换为 stdio； |
| 435 | 中文等显示名称会生成稳定内部 ID；重复声明会去重。导入服务器默认 |
| 436 | `auto_start=false`，由用户按需连接，避免启动时改变提供给模型的工具 schema。 |
| 437 | |
| 438 | 不支持的 Claude hook item type 会跳过并产生 warning。Reasonix 不会执行第三方安装脚本。 |
| 439 | |
| 440 | 插件 hook 会收到这些环境变量： |
| 441 | |
| 442 | - `REASONIX_PLUGIN_ROOT` |
| 443 | - `REASONIX_PLUGIN_NAME` |
| 444 | - `REASONIX_PLUGIN_VERSION` |
| 445 | - `REASONIX_HOME` |
| 446 | - `REASONIX_WORKSPACE_ROOT` |
| 447 | - `CLAUDE_PROJECT_DIR` |
| 448 | - `CLAUDE_PLUGIN_ROOT` |
| 449 | |
| 450 | ## 桌面端后端方法 |
| 451 | |
| 452 | Desktop 通过 host command 暴露插件包操作： |
| 453 | |
| 454 | - `Plugins` |
| 455 | - `PlanPluginInstall` |
| 456 | - `InstallPlugin` |
| 457 | - `RemovePlugin` |
| 458 | - `SetPluginEnabled` |
| 459 | - `UpdatePlugin` |
| 460 | - `PluginDoctor` |
| 461 |