前言¶
开发智能体插件时，往往需要适配 Claude Code、Codex、OpenCode、Google Antigravity 以及 DeepSeek Harness/Cordis 等不同平台的格式。手动维护多套配置和结构非常繁琐。DeepSeek Harness（DSH）的理念是“一切皆插件”，开发者需要一个工具来统一生成符合各平台规范的代码仓库。
是什么¶
harness-alchemist 是一个 TypeScript 插件仓库脚手架，由 lunarmoon26 维护。它将“一套代码、五种 Harness”的概念落地：生成的仓库可以原生安装到上述五个平台。其核心在于让技能（Skill）拥有自己的运行时，通过 skill-runtime.json 声明契约，而非由宿主适配器编写逻辑。该项目遵循 MIT 许可证。
核心功能¶
- 自动脚手架：生成一个 TypeScript 插件仓库，包含各平台所需的入口文件和配置。
- 结构验证：在生成后自动运行 TypeScript 检查、运行时委托测试、脚手架验证以及 npm 包体审计。
- 清单生成：自动生成
skill-runtime.json、alchemy.json等 manifest 文件。
安装与启用¶
CLI 工具是一个原生 Rust 二进制文件，无需用户安装 Rust 环境即可运行。npm 和 Bun 安装方式使用轻量级启动器，但启动器本身需要 Node.js 22.20+ 或 Bun 1.2+。
安装命令如下：
npm install -g harness-alchemist
安装完成后，可以使用 npx 直接运行而无需全局安装：
npx harness-alchemist@latest create my-plugin --help
典型用法¶
- 创建插件项目：
指定项目描述、作者和仓库地址。
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
- 代码验证：
运行npm run validate强制执行 Agent Skills frontmatter 合规性检查、SKILL.md 引用解析以及运行时清单验证。
配置与结构¶
生成的项目包含以下关键结构：
skills/<name>/：存放 Agent Skills 工作流、可移植的skill-runtime.json、固定执行入口以及工具契约引用。src/opencode.ts：OpenCode 插件入口，将可移植运行时清单投射为原生工具。src/deepseek.ts+cordis.patch.yml：Cordis 函数插件入口，注册相同的可移植工具。- Manifests：
skill-runtime.json定义模型面 Schema 并选择执行入口；alchemy.json记录runtime模式、模板版本和生成时间。
项目支持两种 runtime 模式：
* npm（默认）：包含完整的生成契约、npm 元数据、可移植运行时清单、适配器和 Cordis 补丁。
* skills：仅包含技能、运行时清单和 Harness 清单。适用于不需要 npm 包和 JavaScript 运行时的 Python、Go 等语言仓库。
支持的平台¶
该脚手架生成的插件可安装至以下 Harness：
- DeepSeek Harness：通过 profile 文件系统根目录和 Cordis 工具插件安装。
- Claude Code：通过市场清单原生安装。
- Codex/ChatGPT：通过市场清单原生安装。
- OpenCode：通过
~/.agents/skills/安装，并在opencode.json中配置。 - Google Antigravity：通过嵌套包安装。
注意事项¶
插件以当前 DSH 进程的权限运行。在安装或使用插件前，请务必检查源码，确认其安全性及许可证要求。
总结¶
harness-alchemist 通过一套 TypeScript 仓库规范，降低了多平台智能体插件开发的门槛。开发者可以专注于技能逻辑本身，而将适配和验证工作交给脚手架处理。
