插件脚手架工坊 lunarmoon26/harness-alchemist

面向编码智能体插件的通用脚手架。一个仓库，五套 harness，技能自带运行时。

关注 @haochuanzero on X 获取更新 · 从一页式导览开始。

Harness Alchemist 会搭出一个 TypeScript 插件仓库，它能原生安装进 Claude Code、Codex/ChatGPT、OpenCode、Google Antigravity 和 DeepSeek Harness/Cordis。每个产品技能都在 skill-runtime.json 里声明自己固定的可执行文件和可移植工具 schema；宿主入口点通过 @lunarmoon26/agent-skill-runtime 做委托。

安装

npm install -g harness-alchemist
or run it without installing:
npx harness-alchemist@latest create my-plugin --help

命令行实现是一个原生 Rust 二进制文件。用 npm 和 Bun 安装时，会通过一个小型启动器，为 x64 或 arm64 挑选预编译好的 macOS、Linux 或 Windows 二进制文件。命令行用户不需要 Rust 工具链，也不需要安装脚本。开发仓库本身需要 rust-toolchain.toml 里锁定的 Rust 工具链。npm 启动器要求 Node.js 22.20+；也支持用 Bun 1.2+ 调用。

快速开始

npx harness-alchemist@latest create my-plugin \
--description "What the plugin does" \
--author "Example Team" \
--repository example/my-plugin

cd my-plugin && npm install && npm run verify

创建操作只会写入不存在或为空的目标目录。生成的项目开箱即通过自己的关卡：TypeScript 检查、运行时委托测试、脚手架校验，以及 npm 包内容审计。

已有 monorepo 和 SDK 包

validate 也支持在已有仓库里放一个改造过的插件包。在仓库根目录添加 alchemy.json：

{json
{
"$schema": "https://unpkg.com/harness-alchemist/alchemy.schema.json",
"pluginRoot": "packages/my-sdk",
"opencodeExport": "./server"
}

这份清单经过 JSON Schema 校验；schema 随 npm 包一起发布，通过 $schema 引用，所以编辑器能自动补全并检查每个字段。

pluginRoot 存放规范的插件清单、共享技能、Cordis 补丁、适配器源码，以及可发布的包元数据。仓库级 marketplace 清单仍留在项目根目录，指向那个包目录。opencodeExport: "./server" 让 SDK 保留在包根目录，同时通过现代的 server 入口暴露 OpenCode 适配器。省略这个文件，就保留严格生成的单包布局。

可选的 runtime 字段决定适配后的包必须包含什么：

- "npm"（默认）—— 完整的生成契约：npm 元数据、可移植运行时清单、OpenCode 与 Cordis 适配器，以及 Cordis 补丁。
- "skills" —— 只包含技能、可移植运行时清单和 harness 清单。不需要 npm 包、适配器或 Cordis 补丁，也允许单语言脚本，所以 Python、Go、Rust、Java、C#、Swift 仓库都能把自己的工作流暴露给 Claude Code、Codex、Antigravity 和 DeepSeek 的文件系统技能根目录，无需引入 JavaScript 运行时。

生成的项目会带一份 alchemy.json 清单，记录 runtime、规范的 template 版本、generator、generatorVersion 和 createdAt；npm run sync 让 generatorVersion 与包版本保持一致。

你会得到什么

| 界面 | 用途 |
| skills/<name>/ | Agent Skills 工作流、可移植的 skill-runtime.json、固定可执行文件、可选的已测试孪生体，以及工具契约参考 |
| src/opencode.ts | OpenCode 插件，把可移植运行时清单投射为原生工具 |
| src/deepseek.ts + cordis.patch.yml | Cordis 函数插件，注册同一批可移植工具 |
| .claude-plugin/、.codex-plugin/、.agents/plugins/、plugin.json、mcp.json | 面向 Claude Code、Codex、Antigravity 和 MCP 宿主的原生与 Agent Plugins 清单 |
| .agents/skills/develop-<name>/ | 仓库维护技能，让智能体能递归开发这个项目 |
| .github/workflows/ | CI 加标签触发的发布（vX.Y.Z → 校验 → npm provenance） |

支持的 harness

下表中的安装路径在随模板发布前，都已对照真实命令行验证过。

| Harness | 技能 | 运行时 | 安装 |
| Claude Code | 原生内置 | — | claude plugin install <name>@<marketplace> |
| Codex/ChatGPT | 原生内置 | — | codex plugin add <name>@<marketplace> |
| OpenCode | 通过 ~/.agents/skills/ | npm 包插件 | 在 opencode.json 中写 "plugins": ["<package>"] |
| Google Antigravity | 嵌套包 | — | agy plugin validate . && agy plugin install . |
| DeepSeek Harness | profile 文件系统根目录 | Cordis 工具插件 | dsh plugin --profile demo add <package-or-path> |

技能脚本契约

产品技能自己管逻辑，适配器从不插手。

skills/<name>/skill-runtime.json 声明面向模型的 schema，并选定一个由作者控制的入口点。宿主校验同一份 manifest，绝不接受来自模型输入的可执行路径。
bash
echo '{"request": "hello"}' | node skills/<name>/scripts/main.mjs

{"ok":true,"plugin":"my-plugin","echo":{"request":"hello"}}

- stdin 传一个 JSON 对象，stdout 返回一个 JSON 结果加换行。
- 失败时以非零退出码退出，并在 stderr 输出诊断信息。
- scripts/main.py 是仅用标准库的行为孪生版本，用于直接做兼容性测试；starter manifest 为宿主工具选定的是 scripts/main.mjs。

安装级验证

install-check 拿你本地的 harness 命令行去跑项目，断言每个都能发现插件——这正是用户安装时会做的检查，只不过自动化了，跑完还会清理干净： bash
npx harness-alchemist@latest install-check /path/to/project
npx harness-alchemist@latest install-check . --harness agy --json

| Harness | 验证方式 | 隔离 |
| Claude Code | marketplace add → install → plugin details 技能清单 | 用户作用域，自动移除 |
| Codex | marketplace add → plugin add → plugin list 已启用 | 插件缓存，自动移除 |
| Antigravity | plugin validate → install → plugin list | 暂存，自动卸载 |
| OpenCode | 通过 debug skill 发现技能 + 插件启动 | 临时 XDG_CONFIG_HOME |
| DeepSeek | Cordis bundle 组合进 profile（--dump-config） | 临时 DSH_HOME |

Claude、Codex 和 Antigravity 在两种运行时下都会跑；OpenCode 插件这一路和 DeepSeek Cordis 检查需要 npm 模式，且适配器已构建（先跑 npm run build）。缺少的命令行会报告为跳过，而不是失败。

校验层级

npm run validate 始终强制检查 Agent Skills frontmatter 合规性、SKILL.md 引用可解析、每个存在的运行时 manifest 都通过校验、入口点固定且受约束、npm 模式孪生版本一致，以及用原生 Rust 解析器检查 Python 语法。生成的 npm 插件要求每个产品技能都有运行时 manifest；适配后的纯技能仓库也可以包含额外的纯文字技能，同时为主要的 MCP 目标技能保留 manifest。校验器在结构校验期间不执行项目 Python；JavaScript/Python 的行为一致性由运行时测试来验证。

发布自动化

主包和六个平台包都用 lunarmoon26/harness-alchemist 里的 GitHub Actions 工作流 npm-publish.yml 作为 Trusted Publisher。工作流在匹配的托管 runner 上构建每个原生目标，先发布平台包，再发布主包。它用 OIDC 而不是 NPM_TOKEN，要求 tag 同时匹配 package.json 和 Cargo.toml，并且只接受包含在 main 中的提交。

Trusted Publisher 配置的作用域是包级。首次原生发布之前，先用带 2FA 的交互式 npm 会话为每个新平台包各创建一次（保留一个 0.0.0 引导版本，让正式发布走 OIDC），然后用 npm 11.5.1 或更新版本配置它的发布者： bash
npm trust github @lunarmoon26/harness-alchemist-darwin-arm64 \
--repo lunarmoon26/harness-alchemist --file npm-publish.yml \
--allow-publish --yes

对全部六个平台包名重复执行这条命令，然后把每个包的发布访问权限设为 Require two-factor authentication and disallow tokens。现有的主包必须保留相同的工作流身份和策略。预发布版本发布到 next dist-tag 下；稳定版本发布到 latest 下。
bash

bump package.json version, then:

npm run sync && npm run verify && git commit -am "Release vX.Y.Z" && git push

after the release commit is merged to main:

git tag vX.Y.Z && git push origin vX.Y.Z # publishes through npm Trusted Publishing

License

MIT