toolfactory

toolfactory

构建一次 Agent 工具；通过一个操作模块和一个配置文件，即可将它发布为 Agent Skill、Agent Plugins bundle、Claude Code、Codex 或 Cursor 插件、MCP 服务、CLI、npm 或 PyPI 包、MCP Registry 条目、OpenClaw 或 Hermes 原生插件，以及网页。

toolfactory 是一个脚手架生成器和同步维护工具，并非运行时。它会按每种接入方式自身工具的生成格式创建对应内容，使用该方式自己的验证器进行验证，并将所有生成的文件记录在锁文件中，以便在 CI 中检测漂移。将 toolfactory 从它生成的仓库中删除后，每种接入方式仍可安装、构建和发布。

安装

• Agent Skill — npx skills add GoatInAHat/toolfactory
• MCP 服务 — npx -y toolfactory mcp
• Claude Desktop 扩展 — 从 GitHub Release 下载 toolfactory.mcpb，然后双击安装
• Claude Code 插件 — claude plugin marketplace add GoatInAHat/toolfactory，然后运行 claude plugin install toolfactory@toolfactory
• Codex 插件 — codex plugin marketplace add GoatInAHat/toolfactory，然后运行 codex plugin add toolfactory@toolfactory
• Gemini CLI 扩展 — gemini extensions install https://github.com/GoatInAHat/toolfactory
• OpenClaw 插件 — 在检出目录中运行 openclaw plugins install --link hosts/openclaw
• Hermes 插件 — hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes
• DSH 插件（实验性）— 在检出目录中运行 dsh plugin --profile <profile> add ./hosts/dsh，或使用发布包 toolfactory-dsh-0.4.6.tgz
• Web 应用 — npx -y toolfactory mcp --http --open 会在同一端口上为操作页面和 MCP 端点提供服务，并打开页面；通过 MCP 或 skill 调用 web 操作也会执行相同操作并返回 URL。
• npm 包 — npm install toolfactory

快速开始

mkdir hello && cd hello
npx toolfactory init --name hello --binding typescript --surfaces skill,agent-plugins,claude,mcp,cli,npm

init 会创建 plugin.json（身份信息）、dev.toolfactory/tool.json（接入方式、绑定、配置）、内核脚手架、.agents/ Agent 配置规范（skills、MCP 服务、sync.py、setup 和各类宿主的钩子载体，使工具可在任何宿主中开发），以及首次构建。它还会执行接下来人们通常会做的事：运行 git init 并创建首次提交，然后运行 bash .agents/setup，以生成宿主适配器、安装用于保持同步的 git 钩子，并安装依赖项。nextSteps 最后会给出当前运行所在宿主唯一需要的一条重新加载命令，因为仓库无法自动完成重新加载。

添加 --repo <owner>/<name> 后，它会通过 gh 创建对应的 GitHub 仓库并推送到该仓库——除非传入 --public，否则仓库为私有——为每种选定的接入方式添加一个主题，并在存在 .env 文件时准备实时测试环境。--dryRun 会打印 gh 命令调用。以上操作都不是必需的：即使没有 GitHub，只使用普通 git，或者完全不使用 git，下面的所有功能仍然可用。

仅含指令的 Codex 插件

如果插件仅包含供 Codex 使用的 SKILL.md 指令，请使用 --runtime none --surfaces skill,codex。此时，ToolFactory 不会生成 MCP 服务、操作快照、语言脚手架或使用方的运行时依赖。为兼容配置，仍需提供 binding，但在此模式下不会用到。从 ToolFactory 0.1.1 开始，已发布的 npm 包支持此功能。

1. 在 src/ops.ts（TypeScript）或 src/<pkg>/ops.py（Python）中编写操作。每个操作包含名称、描述、输入架构、可选的输出架构、可选的 requires 列表，以及一个处理函数。
2. npx toolfactory introspect 会启动内核 MCP 服务，并将 tools/list 快照保存到 dev.toolfactory/ops.json。
3. npx toolfactory build 会在项目树中重新生成所有已选表面。
4. npx toolfactory gate 会运行 CI 执行的检查，在此包括：构建、差异检查、每个表面的上游验证器、自有检查和测试，以及无需凭据的主机端到端测试。
5. 提交所有内容。npx toolfactory package 会将发布资源构建到 dist/release/；CI 会运行相同的检查，并在 v* 标签上发布前运行相同的打包任务。

一个 TypeScript 操作：

operation({
  name: "echo",
  description: "Echo text back.",
  input: z.object({ text: z.string() }),
  output: z.object({ text: z.string() }),
  annotations: { readOnlyHint: true },
  handler: async ({ text }) => ({ text }),
})

命令

每个命令既是 CLI 子命令，也是 MCP 工具（toolfactory mcp），因为 toolfactory 本身就是用 toolfactory 构建的。

命令	说明
init	新建工具：身份文件（keywords 默认为 [name]，即 Kiro Powers/Agent Plugins 的激活触发词；可用 --keywords 覆盖）、tool.json、内核脚手架、首次构建、git init + 首次提交、.agents/setup；--repo <owner>/<name> 会创建 GitHub 仓库（私有；可用 --public 设为公开）并推送到该仓库
introspect	将内核的 tools/list 快照保存到 ops.json
build	重新生成所有已选表面；删除孤立文件；写入锁文件
check	如果操作快照或任何生成文件与代码不一致，则失败（CI 检查）
validate [--surface]	运行每个表面的上游验证器
coverage	操作 × 表面判定矩阵
gate	运行 CI 执行的检查，在此包括：构建、差异检查、验证器、自有检查和测试、主机端到端测试——遇到第一个失败时停止
package	将所有发布资源构建到 dist/release/（npm 压缩包、发行包、插件压缩包和 bundle zip、Web 构建、覆盖率）
adopt / unadopt / eject	接管 toolfactory 管理的文件（或整个表面），或将其交还
doctor	查看此计算机可委托给哪些上游 CLI
secrets	项目所需的全部凭据——自身的敏感配置键和发布注册表令牌——包括每项凭据的生成位置、其是否存在于本地和 GitHub，以及注册表是否接受该凭据（--action check）；绝不显示凭据值
bootstrap-repo	通过 gh 将 .env 推送到 GitHub（配置键推送到 live-tests 环境，发布令牌推送到仓库），启用 Pages，在软件包创建后配置 npm 可信发布，并列出剩余的一次性步骤
unpublish	从上一个已发布标签以来，对所有已移除某表面的注册表撤回该表面；发布流程会运行此命令，--dryRun 可预览操作

表面

优先选择 Skills。init 会选取已能服务所有运行环境的最小集合——skill、agent-plugins、mcp、cli 和绑定对应的软件包注册表——因为任何支持插件的地方也都支持 skill 加 MCP 服务，而 skill 只有一个文件，无需跟踪上游。以下特定于主机的插件均为可选项：只有当该主机需要 skill 和 MCP 服务无法提供的功能（网关标签页、浏览器功能、商店列表）时，才添加对应插件。

Surface	Emits	Validated by
skill	skills/<name>/SKILL.md（frontmatter + operations 块；正文由你编写），以及指向它的符号链接 .agents/skills/<name>，让 Copilot、Codex、Hermes、DSH 和 .agents/sync.py 使用同一个技能	agentskills validate
agent-plugins	根目录下的 plugin.json + mcp.json（由 OpenClaw、Hermes、Copilot、Cursor、Codex 使用）	使用 Ajv 根据 1.0.0 架构验证
claude	.claude-plugin/plugin.json	claude plugin validate
codex	.codex-plugin/plugin.json + .agents/plugins/marketplace.json（codex plugin marketplace add <owner>/<repo>）	真实的 Codex CLI：marketplace add、plugin add、plugin list
cursor	.cursor-plugin/ 清单	符合架构格式
gemini	根目录下的 gemini-extension.json——可直接从仓库安装的 Gemini CLI 扩展，会读取你的 AGENTS.md 和 skills/	gemini extensions validate
mcp、cli	内核 MCP 服务（stdio 或 --http）以及用于执行操作的 CLI；每个只列出其可运行的操作	MCP Inspector、--help
npm、pypi	合并到 package.json / pyproject.toml 中的包元数据	npm pack、uv build
cargo、nuget、maven-central、rubygems、packagist、go-module	与工具一同发布的、由作者拥有的原生包；元数据保持原生格式	Cargo、.NET、Maven、RubyGems、Composer、Go
homebrew、winget、scoop、chocolatey、apt、rpm	适用于相应操作系统的原生打包和目录／仓库分发	管理器自带的工具
mcp-registry	server.json	mcp-publisher
mcpb	hosts/mcpb/manifest.json，以及从 npm tarball 打包的 .mcpb 发布资源——Claude Desktop 用于一键安装的包	mcpb validate
openclaw-native	hosts/openclaw/，仿照 openclaw plugins init --type tool	openclaw plugins build --check、validate、plugin-inspector
hermes-native	hosts/hermes/，一个 manifest v2 插件	hermes plugins doctor --ci
web	web/，一个 shadcn/ui（Vite、React、Tailwind）应用，每个操作都有对应的表单；你自己的页面可与它并列放在 App.tsx 中	vite build、Playwright
browser-extension	hosts/browser/，一个适用于 Chromium、Firefox 和 Safari 的 WXT 扩展：worker 通过 loopback MCP 调用你的内核，popup 是 web 应用，而需要页面的操作由你在 entrypoints/ 中编写	wxt build、web-ext lint、针对真实 Chromium 运行的 Playwright
vscode-extension	hosts/vscode/，一个原生 TypeScript 扩展，包含 MCP 发现、命令面板操作、设置和 SecretStorage；激活逻辑和原生贡献由你实现	与 Microsoft generator-code 脚手架比较、vsce package、真实的 Extension Development Host
dsh（实验性）	hosts/dsh/，一个零代码 DSH（DeepSeek Harness）捆绑包：通过 @deepseek-ai/dsh-mcp-client 挂接你的 MCP 服务的一行 Cordis 补丁	无需密钥即可启动的 dsh --profile headless
workflows（始终包含）	ci.yml、release.yml（gate → package → publish 步骤 → GitHub Release，另含 Pages）、compose.toolfactory.yaml、.env.example、renovate.json；每个步骤都可通过一次 toolfactory gate / toolfactory package 运行，无需 GitHub	工作流自身
readme（始终包含）	README.md 的 Install 部分（带标记的区域）：每个选定的 surface 对应一条安装命令，另附静态 Agent Skill 徽章	—
选择 vscode-extension，并同时选择 mcp、cli 和运行时注册表（TypeScript 使用 npm，Python 使用 pypi）。在 dev.toolfactory/tool.json 中设置 vscode.publisher，然后构建。
打开 hosts/vscode 并按 F5，即可使用此检出版本的运行时；也可以在该目录中运行 npm run vsix 进行打包。原生命令、视图、Webview、语言服务、聊天参与者和语言模型工具可在你自己的 src/extension.ts 中使用完整的 VS Code API。直接将贡献点添加到其 package.json；重新构建时会保留作者条目以及生成条目上的其他字段。注册发布者后，Marketplace 和 Open VSX 发布任务会使用 VSCE_PAT 和 OVSX_PAT。两者都可以在 tool.json 中单独禁用。

同一条原生自定义规则也适用于其他界面：JSON、TOML 和 YAML 清单仅合并投影字段，宿主入口点则会保留标记区域之外的代码。OpenClaw、Hermes、DSH 和浏览器 shim 可以使用其宿主的完整原生 API。完全替换生成的集成时，仍可使用 adopt 和 eject。

包分发为可选项。PyPI 支持 pip install 和 uv add；pip 使用同一个已发布的 wheel/sdist。其他生态系统使用作者提供的真实原生包和元数据。配置和注册表设置请参阅原生包发布和系统包发布。 Toolfactory 本身仍使用 npm 作为包注册表。

通过 Agent 驱动 toolfactory

同时选择 skill 和 openclaw-native，默认会将该工具自带的 skill 与原生插件一同发布。openclaw.skills 是精确覆盖项：[] 表示不发布；["my-tool", "custom"] 会发布生成的自带 skill 和 .agents/skills/custom/。仅自定义 skill 的显式列表会继续只发布这些 skill。自带 skill 的生成区域会在同一次构建中刷新；作者撰写的文本和 UTF-8 文本资源会保留。原生清单会声明 skills: ["./skills"]，npm 打包也会包含该目录。如果不存在独立的 skill 界面，则不会推断原生插件 skill。

每个命令都是 MCP 工具，因此宿主可以不使用 shell 驱动整个流程，而且无需手动注册任何内容。每个生成的项目都包含 .agents/ 规范，因此 toolfactory 和该工具自己的内核已列入 .agents/mcp/servers.json；运行 bash .agents/setup 会将其渲染到机器上可用的各类工具中（.mcp.json、.cursor/mcp.json、.codex/config.toml 等），并从其中任意一处保持同步。每个工具都将 root 作为参数，因此一次注册即可服务于机器上的所有代码库；在宿主工作树内使用时，请显式传入该参数。

仓库无法自动化的唯一环节是重新加载，因此 init 会打印与其所运行的工具相匹配的命令行，而生成的 AGENTS.md 会包含对应的表格。在 OpenClaw 内，使用 openclaw plugins install --link <repo>/hosts/openclaw --force 安装正在构建的工具；在 Hermes 内，提交更改并运行 hermes plugins install file://<repo>#hosts/hermes/<pkg> — 每次运行 hermes 都会启动一个新进程，hermes gateway restart 仅适用于消息网关。

GSD 使用相同的 skill、CLI 和 MCP 服务；无需 GSD 专属界面。在生成的项目中，运行 bash .agents/setup --all，以便即使在仅安装 GSD 的机器上也能生成 .mcp.json，然后在交互式 GSD 会话中发现该服务，再进行无人值守使用。由 OpenClaw 或 Hermes 启动的 GSD 会与外层 Agent 分别加载子项目的配置。有关设置、运行时边界和可重复的冒烟测试，请参阅 GSD 兼容性。

边界

核心逻辑是 JSON 参数、环境/配置和文件系统的纯函数。操作会从一组封闭词汇中声明其所需能力：net、fs、shell、secret 可移植；browser、model、user-input、channel 则不可移植。每个操作在每个表面上都会在 COVERAGE.md 中获得一个判定（native、bridged、degraded、excluded，并附带原因），而被排除的操作不会出现在该表面的工具列表中，也不会用存根代替。需要浏览器的工具会拆分为两个操作：一个将页面内容作为参数，能够在任何地方运行；另一个声明 browser，仅在有浏览器的环境中运行。

规范性设计请参阅 docs/spec.md。

仓库

toolfactory 自身的仓库由 toolfactory build 根据其 dev.toolfactory/tool.json 生成。pnpm check、pnpm test、pnpm toolfactory check 和 pnpm toolfactory validate 是必过检查。