企业官网建设流程全解析

DeepSeek-Reasonix 插件 Manifest 完全指南：技能、钩子、MCP 与主题声明一文读懂

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

DeepSeek-Reasonix 是一款 DeepSeek 原生的终端 AI 编程智能体（AI coding agent），而它的插件包（Plugin Package）通过一份 Manifest 清单文件，把技能（Skills）、钩子（Hooks）、MCP 服务器与主题（Themes）打包成一个可安装单元。本文带你完整读懂reasonix-plugin.json的每一项声明，从零上手为自己的插件或扩展写出规范的 Manifest。

先 clone 项目源码来熟悉结构：

git clone https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

一、什么是插件 Manifest？为什么重要？

Manifest 是插件包的"身份证 + 能力声明表"。安装插件时，Reasonix 会读取它并回答三个问题：

• 这个插件叫什么、什么版本？（name/version/description）
• 它贡献了什么能力？（skills、hooks、mcpServers、prompts、themes）
• 它需要什么、提供什么？（v2 的requires/provides/runtime）

解析逻辑集中在internal/pluginpkg/目录：入口是 pluginpkg.go 中的ParseDir，v2 版本的严格解析在 manifest_v2.go。官方使用文档见docs/PLUGIN_PACKAGES.md。

Reasonix 支持三种 Manifest，按优先级探测：

二、最小可用的原生 Manifest

一个最小原生插件长这样（相对路径都相对于插件根目录）：

{ "name": "example", "version": "1.0.0", "description": "Example plugin", "skills": "skills", "hooks": { "SessionStart": [ { "command": "hooks/session-start", "args": [], "description": "加载启动上下文" } ] }, "mcpServers": { "helper": { "command": "bin/helper" } } }

注意几个新手容易踩的坑：

• name必须合规：字母、数字开头，仅含字母数字、.、_、-，最长 64 字符。
• 路径必须是相对路径且不能逃出插件根目录，绝对路径、../穿越都会被直接拒绝。
• Reasonix 不会执行第三方安装脚本，安全性由解析层兜底。

三、技能（Skills）声明：让智能体"多会一样本事"

skills字段声明技能根目录，支持三种写法：

{ "skills": "skills" } { "skills": ["skills", "tools/skills"] } { "skills": [{ "path": "skills" }] }

安装后，技能会出现在/skills列表中，用/<插件名>:<技能名>调用，例如/superpowers:writing-plans；也可以自然语言提问，让智能体按描述自动匹配技能。

Claude 风格插件未显式声明时，会自动探测skills/与.claude/skills/目录，与 Claude Code 的自动发现行为保持一致。

四、钩子（Hooks）声明：在生命周期事件上自动执行

hooks以"事件名 → 钩子列表"的映射形式声明。常用事件包括SessionStart、UserPromptSubmit、PreToolUse、PostToolUse。每个钩子支持这些字段：

关键规则——exec 形式 vs shell 形式：

• 声明了args（哪怕"args": []）→exec 形式：command即可执行文件，参数原样传递，不经过 shell，最安全。
• 未声明args但有shell→shell 形式：整条command原样交给 bash / PowerShell / cmd 解释，支持&&等复合命令。

"hooks": { "SessionStart": [ { "command": "hooks/audit", "args": [], "description": "exec 形式" }, { "command": "printf 'ready' && ./hooks/audit", "shell": "bash", "description": "shell 形式" } ] }

钩子运行时可读取REASONIX_PLUGIN_ROOT、REASONIX_PLUGIN_NAME、REASONIX_HOME、REASONIX_WORKSPACE_ROOT等环境变量定位插件内部文件。

五、MCP 服务器声明：给智能体接入外部工具

mcpServers声明插件自带的 MCP（Model Context Protocol）服务器，安装启用后自动并入正常的 MCP/工具流，智能体在相关任务中会自动调用：

"mcpServers": { "helper": { "command": "bin/helper", "args": ["--stdio"], "display_name": "Helper Server", "description": "提供示例工具" } }

常用字段：type、command/args/env（stdio 本地进程）、url/headers（远程服务）、auto_start（是否随会话自动启动，兼容导入的服务器默认false，按需连接）。服务器名同样受插件名规范约束。

六、主题（Themes）声明：一个字段换一整套界面皮肤

v2 Manifest 中，contributes.themes声明*.reasonix-theme主题文件，支持通配符：

"contributes": { "themes": ["themes/*.reasonix-theme"] }

• 主题在桌面端设置 → 主题中只读展示，ID 形如plugin:<插件名>:<主题名>，不会被复制进用户主题库，避免污染。
• 校验很严格：路径必须是普通文件、不能通过符号链接逃出插件根目录；通配符按路径段展开，不跨目录。
• 插件被禁用或卸载时，桌面端回落到基础样式但保留主题 ID——重装同一插件，主题原样恢复。

七、进阶：v2 的 requires / provides / runtime

原生插件若要声明为代码型扩展（Extension），Manifest 必须使用精确的版本号，写错一个字符都会直接报错：

"apiVersion": "reasonix.io/plugin/v2"

v2 是严格解析：任何未知字段（包括contributes/runtime内部）都会触发带字段路径的错误提示——拼错字段名不会静默失效，而是响亮地失败，这对新手排查拼写错误非常友好。

三个进阶块：

• provides：声明本插件提供的能力（命名空间 + 种类 + ID + 版本），重复的能力键会被拒绝。
• requires：声明依赖其他插件/平台的能力，支持版本区间（versionRange）与optional: true可选依赖。
• runtime：声明一个由 Reasonix 启动的 sidecar 进程，通过扩展协议（JSON-RPC 2.0 over stdio）通信。

"runtime": { "command": "${REASONIX_PLUGIN_ROOT}/bin/example", "args": [], "required": true, "intercepts": ["input.receive", "tool.before"], "capabilities": ["interceptors"] }

• command支持${REASONIX_PLUGIN_ROOT}前缀，在启动时展开为插件根目录。
• intercepts可从 17 个拦截点中选择（session.start、provider.request、tool.after、permission.decision等）。
• replaces声明可独占的替换槽位（system_prompt、context、compaction等），每个槽位全局只有一个拥有者，冲突会导致构建失败并指明双方来源。

⚠️完全信任警告：带runtime的插件在沙箱之外运行，可读取完整会话与环境、绕过权限检查。安装预览、reasonix plugin show与桌面安装器都会展示醒目的FULL TRUST区块——安装前务必核对，只安装你完全信任的扩展。

八、新手排错清单：doctor 与能力诊断

Manifest 写错了怎么办？不要猜，直接跑诊断：

# 检查某个插件的 Manifest 与技能根目录可读性 reasonix plugin doctor superpowers # 工作区级能力总览（技能/钩子/MCP 合并情况、包根目录） reasonix doctor capabilities --json

诊断会区分错误（路径逃逸、未知字段、非普通文件的主题）与警告（声明的文件不存在、通配符未匹配到文件）。另外，桌面端 Settings → Diagnostics 与聊天中的/reasonix-guide命令提供同一套能力诊断。

常见报错速查：

九、快速上手：三步发布你的第一个插件

1. 建目录：my-plugin/下放reasonix-plugin.json+skills/+hooks/等资源。
2. 先预览：reasonix plugin install /path/to/my-plugin --dry-run验证解析通过。
3. 安装试用：reasonix plugin install /path/to/my-plugin --link --replace --yes，用--link链接模式开发，改完即生效；发布时去掉--link改为复制安装。

插件状态持久化在~/.reasonix/plugin-packages.json，插件内容位于~/.reasonix/plugins/<name>/。配合/plugins、/plugins show <name>命令，即可在会话内随时核对插件导出的技能、钩子与 MCP 服务器清单。

掌握这份 Manifest 声明规范后，你就能把技能、钩子、MCP 与主题打包成即装即用的插件包，把 DeepSeek-Reasonix 改造成完全贴合自己工作流的 AI 编程助手。

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix