multi-platform-plugin-guide

name	multi-platform-plugin-guide
description	用于维护 SumSec-Skills 多平台插件元数据与发布清单：package.json、plugin.json、Claude/Cursor/Codex/DSH manifest、marketplace JSON、版本号、描述、关键词、安装文档。

多平台插件开发指南（AI Inner OS）

本仓入口：优先执行文末 SumSec-Skills 发布清单（本仓）。前半部分保留 AI Inner OS 多平台矩阵作为参考；本仓还落地 OpenClaw / OpenCode / Hermes / DeepSeek Harness（DSH）专用入口。

上游矩阵参考：AI Inner OS 主仓根目录 CLAUDE.md。若本技能的通用平台说明与 AI Inner OS 主仓不一致，先更新上游矩阵，再同步本技能。

何时使用

• 修改 hooks/hooks.json、.claude-plugin/、.codex-plugin/、.cursor-plugin/、.agents/plugins/marketplace.json、根 plugin.json、openclaw.plugin.json 或 release 版本字段。
• 修改根 package.json 的 dsh.bundle.patch / DSH keywords、dsh/cordis.patch.yml、dsh/README.md、scripts/validate-dsh.mjs 或 profile bundle 安装说明。
• 修改 hooks/、codex/、cursor/ 下的 hook 适配器，或共享库 hooks/lib/。
• 更新必须和 manifest 保持一致的安装文档，例如 cursor/README.md、docs/install-cursor.md、codex/README.md、docs/install-codex.md。
• 准备跨平台 release、插件市场发布、插件缓存更新或多平台能力对齐。

官方文档优先

开发或审查任何平台适配前，先查看对应平台最新官方文档。本技能只记录本仓库当前约定；如果官方规范变化，以官方文档为准，再同步更新仓库实现、CLAUDE.md 和本技能。

平台	官方开发指南
Claude Code	Plugins reference
Codex	Build plugins
Cursor	Plugins Reference
OpenClaw	Building plugins、Skills
OpenCode	Plugins
Hermes Agent	Plugins、Skills System
DeepSeek Harness	deepseek-ai/deepseek-harness、@deepseek-ai/dsh；本仓当前按 0.1.0-rc.6 验证，该包仍为 prerelease，升级前必须重新检查 package manifest、profile 与 Cordis patch contract。

默认流程：

1. 读取对应平台最新官方指南。
2. 对照本仓库 CLAUDE.md 和现有实现。
3. 只实现官方已支持的 manifest 字段、hook 事件和路径规则。
4. 如果官方规范与仓库文档冲突，先修实现，再同步 README、安装文档、CLAUDE.md 和本技能。

插件注册地图

Role	Path
Claude Code hook 注册	hooks/hooks.json
Claude Code 插件清单	.claude-plugin/plugin.json
Claude marketplace 入口	.claude-plugin/marketplace.json
Codex 插件清单	.codex-plugin/plugin.json
Codex 仓库级 marketplace	.agents/plugins/marketplace.json
Cursor 插件清单	.cursor-plugin/plugin.json
Cursor marketplace 入口	.cursor-plugin/marketplace.json
OpenClaw 插件清单	openclaw.plugin.json
OpenClaw 插件入口	openclaw/index.js
OpenCode 插件入口	opencode/plugins/inner-os.js
Hermes Skill	hermes/skills/inner-os/SKILL.md
DeepSeek Harness bundle manifest	根 package.json 的 dsh.bundle.patch
DeepSeek Harness bundle patch	dsh/cordis.patch.yml
仓库级元数据	plugin.json

版本同步清单

发布更新时，同步 bump 下列版本字段，否则 marketplace/cache 可能不会拉取新内容。多插件仓尤其要确认 marketplace 条目版本和对应子插件 manifest 版本完全一致，不要只改根 manifest：

1. package.json
2. plugin.json
3. .claude-plugin/plugin.json
4. .claude-plugin/marketplace.json → 每个 plugins[].version
5. .codex-plugin/plugin.json
6. .agents/plugins/marketplace.json → 每个 Codex 插件条目 version
7. .cursor-plugin/plugin.json
8. .cursor-plugin/marketplace.json → 每个条目 version
9. 各子插件 .claude-plugin/plugin.json
10. 各子插件 .codex-plugin/plugin.json
11. openclaw.plugin.json

Claude Code 插件规范摘要

• .claude-plugin/ 下只放 manifest 文件；组件目录留在插件根目录，例如 commands/、skills/、agents/、hooks/hooks.json、.mcp.json、.lsp.json、output-styles/、themes/、monitors/。
• .claude-plugin/plugin.json 中的自定义路径必须相对插件根目录，以 ./ 开头，不能使用 ..。
• Hook 命令引用插件内文件时使用 ${CLAUDE_PLUGIN_ROOT}；marketplace 安装后不能假设仓库 checkout 路径存在。
• 可变状态只写入 ${CLAUDE_PLUGIN_DATA}，不要写入插件根目录或 cache 源码目录。
• 每次发布更新都要 bump .claude-plugin/plugin.json 的 version。
• 验证：claude plugin validate .，然后 npm run check 和 npm test。

Cursor 插件规范摘要

• Manifest：.cursor-plugin/plugin.json、.cursor-plugin/marketplace.json。
• 本仓库 Cursor 组件目录是 cursor/，例如 rules: "./cursor/rules/"、hooks: "./cursor/hooks.json"。
• 路径必须相对仓库/插件根目录，不能使用 ..。
• Rules 是带 YAML frontmatter 的 .mdc 文件；cursor/rules/inner-os-protocol.mdc 必须保留 description 和 alwaysApply: true。
• 本仓库 Cursor hook 事件名：sessionStart、postToolUse、stop，使用小写。
• Cursor hook 输出格式：顶层 { "additional_context": "..." }。
• 不要把 Cursor preToolUse 用于上下文注入，因为它不能注入 additional_context。
• 保持 cursor/README.md、docs/install-cursor.md 与 .cursor-plugin/plugin.json、cursor/hooks.json 一致。

Codex 插件规范摘要

• Manifest：.codex-plugin/plugin.json，该目录下只放 manifest；组件留在插件根目录。
• Marketplace：.agents/plugins/marketplace.json；repo-scoped marketplace 可被 codex plugin marketplace add <repo> --ref <ref> 作为 Git marketplace 添加。
• Marketplace 插件条目有三类官方 source：
  • local：source.source = "local" + source.path = "./..."，path 相对 marketplace root 解析，不是相对 .agents/plugins/ 目录。
  • Git 根插件：source.source = "url" + url + 可选 ref / sha，用于插件位于 Git 仓库根目录。
  • Git 子目录插件：source.source = "git-subdir" + url + path + 可选 ref / sha，用于一个 Git 仓库中包含多个插件或插件不在根目录。
• 区分 marketplace source 与 plugin entry source：codex plugin marketplace add <repo> 管理 marketplace 本身从哪里来；plugins[].source 管理某个插件包从哪里加载。两者都可以涉及 Git，但字段语义不同。
• Skill 路径应使用 ./skills/、./skills/<name>/SKILL.md 或 manifest 的 skills 字段；仓库级本地 skills 放在 .agents/skills/。
• Hook 路径：项目级 hook 使用 .codex/hooks.json 或 .codex/config.toml；插件可按官方插件打包规则携带默认 hooks/hooks.json。
• Hook 事件名使用官方大小写：SessionStart、PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、UserPromptSubmit、SubagentStart、SubagentStop、Stop。
• repo-local hook 命令优先从 git root 定位脚本，避免 Codex 从子目录启动时相对路径失效；非托管 hook 变更后需要重新 review/trust。
• 插件根可包含 skills/、hooks/、.app.json、.mcp.json、assets/；只有 plugin.json 放进 .codex-plugin/。Manifest 路径必须相对插件根、以 ./ 开头，并留在插件根内。
• 插件 hooks 默认文件是 hooks/hooks.json；若 .codex-plugin/plugin.json 写了 hooks 字段，则覆盖默认。插件 hook 命令可用 / ，Codex 也兼容 / 。

Codex 与 Cursor：marketplace 的 source 与「从 Git 安装」

两家的 marketplace 条目语法不同，不要强行把 Codex 的写法套到 Cursor 上。

Codex（.agents/plugins/marketplace.json）

• 官方支持 Git marketplace source：使用 codex plugin marketplace add owner/repo --ref main、HTTPS/SSH Git URL 或本地 marketplace root，让 Codex 安装并跟踪 marketplace 源。Git ref、sparse checkout 等属于 marketplace source 配置。
• marketplace 中每个插件条目可以指向本地路径，也可以直接指向 Git-backed plugin source：
  • local："source": { "source": "local", "path": "./plugins/my-plugin" }。path 相对 marketplace root 解析，并应以 ./ 开头。
  • url："source": { "source": "url", "url": "https://github.com/owner/plugin.git", "ref": "main" }。插件位于 Git 仓库根目录。
  • git-subdir："source": { "source": "git-subdir", "url": "https://github.com/owner/plugins.git", "path": "./plugins/my-plugin", "ref": "main" }。插件位于 Git 仓库子目录。
• ref 和 sha 是 Git-backed plugin entry 的官方选择器；如果 Codex 解析不了某个 entry，会跳过该插件条目而不是让整个 marketplace 失败。
• 本地调试：可以直接 codex plugin marketplace add ./local-marketplace-root 指向本地 marketplace root；若修改插件内容，需要刷新/重启 Codex 让本地安装拾取新文件。

Cursor（.cursor-plugin/marketplace.json）

• 官方 schema 中，插件条目里的 source 字段表示 当前已被 Cursor 作为 marketplace 来源纳入的那份 Git 工作副本里的相对路径（多插件仓里常见为子目录名，如 docker；单插件占满整仓根 时为 "./"），用于在该路径下查找 .cursor-plugin/plugin.json 并与条目字段合并。见 Plugins Reference — Multi-plugin repositories / How resolution works。
• 没有 Codex 那种 source: { "source": "url" | "git-subdir", "url": "...", "ref": "..." } 插件条目。所谓「从 Git 安装」是指：用户或管理员 用 GitHub 仓库 URL 导入整个 marketplace 仓库（例如 Team marketplace Import）；导入后，source: "./" 自然指向该次 Git 检出的根目录，而不是在 JSON 里再写一遍 clone URL 当作 source。
• 推荐补强：在 marketplace 的插件条目上增加官方支持的 repository（及 homepage）字符串，写明 canonical Git URL（如 https://github.com/SummerSec/SumSec-Skills.git），避免维护者误以为必须把 source 改成 URL 才算「对齐 Codex、默认从 Git」——语义上由 导入来源 + repository 共同表达即可。

跨平台 hook 行为摘要

• Hook 脚本应包裹 try/catch，失败时静默，不中断主会话。
• Claude Code：PreToolUse 使用 hookSpecificOutput.additionalContext；部分事件使用 stdout 文本，详见 CLAUDE.md。
• Cursor：支持事件使用顶层 additional_context JSON。
• Codex：SessionStart 输出 stdout；PostToolUse 使用 hookSpecificOutput.additionalContext；不使用 PreToolUse 注入上下文。
• Bash 命令目标摘要截断为 80 字符。

OpenClaw 插件规范摘要

• 插件清单：openclaw.plugin.json，保持 id、version、main、description 对 OpenClaw 有效。
• 插件入口：openclaw/index.js，必须纳入 npm run check。
• Skill 内容：openclaw/skills/inner-os/SKILL.md，保持 AgentSkills 兼容。
• 插件分发的 skills 优先级低于 workspace、project、personal、managed 等位置；不要假设插件 skill 会覆盖用户或工作区 skill。
• 保持 openclaw/README.md、docs/install-openclaw.md 与 openclaw.plugin.json、openclaw/index.js、openclaw/skills/inner-os/SKILL.md 一致。

OpenCode 插件规范摘要

• 插件入口：opencode/plugins/inner-os.js，这是独立插件，不复用 hooks/lib/。
• 静态指令：opencode/inner-os-rules.md；配置示例位于 opencode/。
• OpenCode 插件通常从 .opencode/plugins/、~/.config/opencode/plugins/ 或 opencode.json 配置的 npm 包加载。
• OpenCode 插件代码应遵循官方 plugin API 和事件名；不要把 Claude/Codex 的 lifecycle hook 写成 OpenCode 行为。
• 保持 opencode/README.md、docs/install-opencode.md、scripts/install.js 与插件入口和指令文件路径一致。

Hermes 插件规范摘要

• 当前仓库通过 hermes/skills/inner-os/SKILL.md 和 hermes/hermes.md 支持 Hermes。
• Hermes skill 应保留 Hermes 专用 frontmatter，例如 version、category、tags 等字段。
• hermes/hermes.md 是项目 context-file 变体，必须与 canonical protocol 和 persona markers 保持同步。
• 不要假设 Hermes 支持 Claude Code、Codex 或 Cursor 的 JavaScript hook 模型。
• 保持 hermes/README.md、docs/install-hermes.md 与 skill/context-file 安装路径一致。

共享维护提示

• 全局安装：scripts/install.js 会把共享核心复制到 ~/.inner-os/ 并生成各平台配置，详见 CLAUDE.md 的 Global Install Script。
• 协议唯一来源：protocol/SKILL.md。各平台静态副本需要手动同步，详见 CLAUDE.md 的 Single Source of Truth。

DeepSeek Harness 插件规范摘要

• profile bundle 是 npm 包，通过 package.json 的 dsh.bundle.patch 指向顶层为 patch list 的 Cordis YAML；bundle patch 按 dsh.profile.bundles 顺序组合。
• 官方 base bundle 先用 - insert: 插入 id: skill-filesystem。本仓作为后续层按该 id 替换整行配置；Cordis 不会局部 merge config，因此必须完整保留 providerName: filesystem、includeDefaultRoots: true 和全部 customSkillDirs，不能只写新增目录。includeDefaultRoots: true 保留项目 .dsh/skills、项目 .agents/skills、$DSH_HOME/skills 与 ~/.agents/skills。
• customSkillDirs 直接挂载真实 <plugin>/skills/ root；官方 filesystem provider 只发现其下一层的 <skill>/SKILL.md，不递归发现嵌套 Skill。插件 root 增删时，必须同时更新 dsh/cordis.patch.yml、scripts/validate-dsh.mjs、dsh/README.md 和根 README 的平台说明。
• patch 中的包内路径用 patch baseUrl 解析，避免依赖调用时 cwd 或 Git symlink checkout。
• 持久安装分两步。先执行 dsh plugin --profile <profile> add --workspace-root --ignore-scripts <package>，该命令只安装 profile 依赖；再编辑 $DSH_HOME/profiles/<profile>/package.json，把安装后的 package name 显式追加到现有 dsh.profile.bundles 末尾并保留原顺序。--workspace-root 明确允许 pnpm 修改 profile workspace 根依赖；--ignore-scripts 避免执行本仓仅供 submodule 同步维护的 Python postinstall。
• dsh --profile <profile> --patch ./dsh/cordis.patch.yml ... 只是本次启动的后置 overlay，不会持久激活 bundle，不能替代上述 profile 配置。

DSH 变更的发布前验证门禁：

# bundle metadata、完整 mount 清单与一层 Skill 结构
npm run validate:dsh

# 用独立临时 home 检查官方 prerelease 的真实 Cordis 组合；不要指向用户 DSH_HOME
$dshVerifyHome = Join-Path ([System.IO.Path]::GetTempPath()) ("sumsec-dsh-verify-" + [guid]::NewGuid().ToString("N"))
$env:DSH_HOME = $dshVerifyHome
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 --profile headless --patch ./dsh/cordis.patch.yml --dump-config

# 分发包必须包含 manifest、patch 与各真实 Skill root；不得执行维护型 postinstall
npm pack --dry-run --ignore-scripts --json

# JSON、同步映射和 diff 基线
node -e "const fs=require('fs'); for (const f of ['package.json','plugin.json','.claude-plugin/plugin.json','.claude-plugin/marketplace.json','.cursor-plugin/plugin.json','.cursor-plugin/marketplace.json','.codex-plugin/plugin.json','.agents/plugins/marketplace.json','openclaw.plugin.json']) JSON.parse(fs.readFileSync(f,'utf8')); console.log('json ok')"
$env:PYTHONIOENCODING = 'utf-8'
npm run sync:dry
git diff --check

检查 --dump-config 输出确实包含 skill-filesystem、customSkillDirs 和首尾 SumSec roots；检查 npm pack --dry-run 的 JSON file list 确实包含 package.json、dsh/cordis.patch.yml 与各插件的 SKILL.md。验证完成后清理临时 $dshVerifyHome，不要修改用户真实 profile。

SumSec-Skills 发布清单（本仓）

SumSec-Skills 为「多 plugin 源码集合」仓库，当前 marketplace 对外注册多个独立插件目录，每插件有自己的 .claude-plugin/plugin.json 与 .codex-plugin/plugin.json。已落地的多平台入口 包含 OpenClaw / OpenCode / Hermes / DSH 专用文件（openclaw.plugin.json、opencode/、hermes/、dsh/cordis.patch.yml）。维护者 bump 版本或调整对外描述 时，请将下列文件中的 version（及需要的 description / keywords） 全部对齐：

1. package.json（根）
2. plugin.json（根）
3. .claude-plugin/plugin.json
4. .claude-plugin/marketplace.json → 每个 plugins[].version
5. .cursor-plugin/plugin.json
6. .cursor-plugin/marketplace.json → 每个条目 version
7. .codex-plugin/plugin.json
8. .agents/plugins/marketplace.json → 每个 Codex 插件条目 version
9. writing-zh/.claude-plugin/plugin.json、writing-zh/.codex-plugin/plugin.json
10. dev-tools/.claude-plugin/plugin.json、dev-tools/.codex-plugin/plugin.json
11. agents-dev/.claude-plugin/plugin.json、agents-dev/.codex-plugin/plugin.json
12. claude-md-management/.claude-plugin/plugin.json、claude-md-management/.codex-plugin/plugin.json
13. hookify/.claude-plugin/plugin.json、hookify/.codex-plugin/plugin.json
14. plugin-dev/.claude-plugin/plugin.json、plugin-dev/.codex-plugin/plugin.json
15. cloudflare-email/.claude-plugin/plugin.json、cloudflare-email/.codex-plugin/plugin.json、cloudflare-email/.cursor-plugin/plugin.json
16. taste-skill/.claude-plugin/plugin.json、taste-skill/.codex-plugin/plugin.json、taste-skill/.cursor-plugin/plugin.json
17. semantic-linter/.claude-plugin/plugin.json、semantic-linter/.codex-plugin/plugin.json、semantic-linter/.cursor-plugin/plugin.json
18. openclaw.plugin.json — OpenClaw manifest
19. opencode/plugins/sumsec-skills.mjs — OpenCode plugin entry (inline version)
20. hermes/skills/sumsec-skills/SKILL.md — Hermes skill (inline version)

DSH 本身不在 patch 中复制版本字段，但每次插件目录增删或安装说明变化时，还必须同步核对根 package.json 的 dsh.bundle.patch / keywords、dsh/cordis.patch.yml、dsh/README.md 与 scripts/validate-dsh.mjs。

注意：Codex 的 .agents/plugins/marketplace.json 是用户安装时看到的版本，子目录内 .codex-plugin/plugin.json 是实际插件包 manifest；二者版本必须一起更新。Claude/Cursor marketplace 也同理，条目版本不能和插件 manifest 分叉。

Codex：本仓 .agents/plugins/marketplace.json 与 Claude/Cursor 一样采用多插件条目；每个条目使用 source.source: "local" + 对应子目录 path（如 ./writing-zh、./dev-tools）。通过 codex plugin marketplace add SummerSec/SumSec-Skills --ref master 拉取 marketplace 后，Codex 会从该 checkout 的子目录加载各插件目录内的 .codex-plugin/plugin.json。若未来维护单独 marketplace 仓库，或希望某个 entry 直接指向远端插件包，可使用官方 Git-backed entry：source: "url"（插件在仓库根）或 source: "git-subdir"（插件在仓库子目录），并配合 url、ref / sha。

Cursor：.cursor-plugin/marketplace.json 与 「Codex 与 Cursor：marketplace 的 source 与『从 Git 安装』」 一节保持一致（source: "./" + 条目级 repository 等）。SumSec-Skills 下可选规则在 .cursor/rules/，由 .cursor-plugin/plugin.json 的 rules 引用。

各平台字段语义、hooks 与完整矩阵仍以本文前半与 AI Inner OS 主仓 CLAUDE.md 为准；上表仅约束 本仓库 内实际存在的路径。