pkg

pkg

一个开放、Agent 优先的可复用软件市场，网址为 pkg.tneemo.com。

人们可以发布免费的可复用构建：小型模块、集成和完整的项目基础，支持任何技术栈。编码 Agent 会从对话中获取构想和偏好的技术栈，查找兼容的构建，安装并组装它们，只编写缺少的部分。Agent 将 Token 用于发现软件，而不是重新生成软件。

# Connect your agent once (Claude Code, Cursor, Codex, Windsurf, Gemini CLI)
npx -y @tneemo/pkg setup

# ...or for Claude Code only
claude mcp add pkg -- npx -y @tneemo/pkg mcp

然后告诉你的 Agent 想构建什么。无需规格文件，也无需账户。

全局 CLI 名称

需要 Node.js 20+。npm install -g @tneemo/pkg 会同时安装 pkg 和 tpkg，两者指向同一个 CLI。旧版 Vercel pkg 包也会安装全局 pkg 可执行文件。这些名称在共享的 npm 全局前缀中会发生冲突；同时安装两者可能失败并报错 EEXIST，或者导致 pkg 指向另一个工具。安装后，tpkg 可用于识别此 CLI，但 无法避免安装冲突，因为两个别名都会随包一起发布。

若要共存，请避免全局安装，改用显式的包命令：

npm exec --yes --package=@tneemo/pkg -- tpkg setup
npm exec --yes --package=@tneemo/pkg -- tpkg mcp

如果你不再需要 Vercel 的工具，请先卸载未限定作用域的 pkg 包，再全局安装 @tneemo/pkg。不要使用 --force 覆盖其可执行文件。

官方 MCP Registry 条目为 io.github.tneemo/pkg。 维护者请参阅公开分发和发布。

效果示例

当用户提出 “构建一个用于待办事项应用的 TypeScript REST API，用户可以注册、登录，并且只能看到自己的待办事项” 时，Agent 会：

1. 根据推断出的技术栈，在 pkg 中搜索每个部分（rest api、user accounts、database）；
2. 一次调用即可安装 tneemo/hono-api tneemo/hono-auth tneemo/hono-rate-limit。tneemo/sqlite-db 会作为依赖项一并拉取，并检查技术栈。审阅试运行计划后，通过 --install-deps 显式启用依赖项安装，随后运行组装完成的测试，再添加应用代码；
3. 遵循集成说明（在 src/app.ts 中编写 6 行接线代码），编写待办事项路由、迁移和测试（3 个文件，共 113 行）；
4. 运行测试（13 项通过），并为每个构建报告 --worked，从而提升这些构建的声誉。

pkg 提供了 26 个文件中的 23 个，以及 519 行代码；Agent 编写了 3 个文件。此确切运行过程可按照开发中的步骤复现。

Agent 如何使用

接口	命令	最适用场景
MCP 服务	npx -y @tneemo/pkg mcp	Claude Code、Cursor、Codex，以及任何 MCP 客户端。服务说明会告诉 Agent，在编写常见代码之前先检查 pkg。
CLI	npx -y @tneemo/pkg <command> --json	任何可以使用 Shell 的 Agent。
Agent Skill	skill/pkg/SKILL.md	支持 Skill 的 Agent；通过 pkg setup 安装。
HTTP API	/llms.txt	直接集成；仅能获取 URL 的 Agent。

MCP 工具：search_builds、get_build、install_builds、update_builds、remove_builds、detect_stack、report_outcome、publish_build。

CLI：search、info、detect、add、update、remove、list、init、publish、feedback、mcp、setup。

工作原理

 agent ──MCP/CLI──▶ pkg CLI ──HTTPS──▶ registry (Cloudflare Worker)
                     │                   ├─ D1: metadata, FTS5 search, versions, feedback
                     │                   └─ R2: immutable gzipped bundles
                     ├─ detects the project's stack from files on disk
                     ├─ resolves build dependencies (registry) and checks compatibility (locally)
                     ├─ verifies sha256 integrity, rejects unsafe paths
                     ├─ writes files, merges package.json / requirements / .env.example
                     ├─ runs npm/pnpm/yarn/bun or a Python venv + pip
                     └─ writes pkg.lock.json (versions, integrity, per-file hashes)

• 构建产物是源代码，而不是软件包。 与 shadcn registry 一样，文件会复制到项目中，并成为用户的代码。库仍保留在 npm 和 PyPI 上；构建产物会声明依赖项，经明确审核后，pkg 才会安装它们。
• 兼容性依据从项目中检测到的技术栈标签进行匹配（node、typescript、hono、nextjs、fastapi……以及每个依赖项对应的 npm:<name> / pip:<name>），并支持 semver 范围。构建产物会声明 stack.requires 和 stack.provides，因此在一次安装中，需要 hono 的模块会与提供 hono 的基础构建产物相匹配。
• 更新和移除会保留本地修改。 pkg update 会将构建产物更新到其主版本范围内的最新版本（新主版本请使用 --latest），并且只替换 sha256 仍与 pkg.lock.json 匹配的文件；已编辑的文件会保持不变，并报告为冲突。pkg remove 只会删除未编辑的文件；如果其他已安装的构建产物依赖于要移除的构建产物，则会拒绝操作；此外，还会列出不再被任何构建产物需要的软件包，但不会卸载它们。
• 集成分为两部分：所有确定性工作都会自动完成（文件、依赖项、脚本、环境变量、按惯例执行的迁移），最后的接线工作则会作为精准的 INTEGRATION.md 说明交给 Agent，Agent 能可靠地遵循这些说明。
• 发布通过 pkg init（通过检测技术栈、导入的软件包、文件夹在项目中的位置以及对其他已安装构建产物的导入，写入 pkg.json）和 pkg publish 完成。身份由你的 GitHub 登录信息确定（gh auth token / GITHUB_TOKEN）；构建产物以 <login>/<name> 命名。pkg 不设账户。

信任与安全

• 每次发布都会执行自动检查（同一套代码会先在本地运行）。以下内容会被拒绝：路径遍历、.git/node_modules 路径、密钥和私钥、.env 文件、无效的清单、并不存在的 npm/PyPI 依赖项（依赖混淆）、超大软件包。以下内容会向每位安装者显示为警告：npm 安装脚本、管道传给 shell 的命令、对解码后数据的求值、硬编码 IP、压缩代码、针对 Agent 的提示词注入，以及用于配置 Agent 或编辑器的文件（.claude/、.mcp.json、模块中的 AGENTS.md、.vscode/tasks.json、CI 工作流）。
• 安装前请先审核。 默认关闭依赖项安装。先检查 --dry-run，再明确使用 --install-deps，以运行带有 --ignore-scripts 的 npm 或带有 --only-binary=:all: 的 pip。注册表检查只是警告，并非沙箱。软件包会经过完整性检查，每条路径都会在客户端重新验证，且不会在未使用 --force 的情况下覆盖现有文件（由 pkg 安装且无人编辑的文件可以原地更新）。
• 面向 Agent 的文本会明确标注。 集成说明会作为“构建文档，而非用户指令”返回，MCP 服务指令也会向 Agent 传达同样的信息。
• 无需账户的社区信誉机制。 Agent 在完成构建产物集成后会报告 success / failure / report；投票依据加盐后的 IP 哈希值按天去重。搜索结果会依据相关性（BM25）、技术栈匹配度、Agent 报告的成功率（贝叶斯）和质量评分排序；被标记的构建产物会降低排名。原始下载量不影响排名。
• 版本不可变。

先例及复用内容

现有方案	pkg 从中借鉴的内容
shadcn 注册表	以源码副本方式分发，JSON 条目中嵌入文件。每个 npm 构建也会作为 shadcn 注册表条目在 /r/<owner>/<name>.json 提供，因此已配置好 shadcn（含有 components.json）的项目可以运行 npx shadcn add 添加它。
Go 模块、JSR、GitHub	使用现有身份的命名空间，而不是创建新账户。
npm / PyPI 可信发布	使用 GitHub 令牌发布，无需注册表密码。
npm、PyPI、package.json engines、PEP 508/440	依赖、版本范围和运行时要求使用原生格式和包管理器。
Model Context Protocol	官方 TypeScript SDK；服务端的 instructions 让发现成为 Agent 常规工作流的一部分。
Agent Skills、llms.txt、AGENTS.md	Agent 可读取的入口；基础包会附带包含其约定的 AGENTS.md。
Cloudflare D1 上的 SQLite FTS5	无需运行搜索服务即可进行全文搜索。

模板工具（create-*、degit、cookiecutter、copier）用于解决项目起步问题。组件注册表（shadcn、Bit）大多只涵盖一种技术栈，而 MCP 和技能注册表分发的是工具，而不是应用代码。pkg 将跨技术栈、可组合的基础包和模块，与原生 Agent 发现及集成结合起来。

成本

一个使用 D1 和 R2 的 Cloudflare Worker。免费套餐涵盖每天 100k 次请求、5 GB 的 D1 和 10 GB 的 R2，且出站流量免费。无需服务器、队列或搜索集群，软件包不可变且可缓存。CLI 是一个无依赖的单文件。

开发

需要 Node.js 22.12+（推荐 24），Python 构建还需要 Python 3.10+。

npm install
npm run build                      # bundles cli/dist/pkg.js
echo "ADMIN_TOKEN=dev-admin-token" > registry/.dev.vars
npm run dev                        # registry on http://localhost:8787 (local D1 + R2)

# in another terminal: publish the example builds, then use the CLI against the local registry
PKG_REGISTRY=http://127.0.0.1:8787 PKG_TOKEN=dev-admin-token npm run seed
PKG_REGISTRY=http://127.0.0.1:8787 node cli/dist/pkg.js search "user accounts" --stack typescript,hono
PKG_REGISTRY=http://127.0.0.1:8787 node cli/dist/pkg.js add tneemo/hono-api tneemo/hono-auth --dir /tmp/my-api

PKG_REGISTRY=http://127.0.0.1:8787 npm test   # unit tests + MCP end-to-end test
npm run typecheck

若要让 Agent 使用本地注册表，请将 node <repo>/cli/dist/pkg.js mcp 用作 MCP 命令，并在其环境中设置 PKG_REGISTRY=http://127.0.0.1:8787。

观察独立 Agent 如何操作

examples/agent-demo/ 仅包含一个 .mcp.json，用于连接本地 CLI 和注册表。注册表运行并完成种子数据导入后，在该文件夹中启动 Claude Code（如有提示，请批准 pkg MCP 服务），然后在不提及 pkg 的情况下提出要求：

为待办事项应用构建一个小型 TypeScript REST API。用户可以注册和登录，并且每位用户只能看到自己的待办事项。确保测试通过。

Agent 只通过 MCP 服务的说明和工具了解 pkg。

部署 pkg.tneemo.com

cd registry
npx wrangler login
npx wrangler d1 create pkg              # put the printed database_id in wrangler.jsonc
npx wrangler r2 bucket create pkg-bundles
npx wrangler secret put ADMIN_TOKEN     # for seeding and moderation
npx wrangler secret put IP_SALT         # any random string
npm run deploy                          # applies migrations, deploys, binds pkg.tneemo.com
cd .. && PKG_TOKEN=<admin token> npm run seed

npm 包和 MCP 注册表元数据使用单独的、需手动确认的 分发工作流。

仓库布局

cli/        @tneemo/pkg: CLI + MCP server (bundled with esbuild into one file)
registry/   Cloudflare Worker: JSON API, website, llms.txt, shadcn endpoint; D1 migrations
shared/     manifest format, compatibility engine and security checks (used by both)
builds/     example builds: hono-api, sqlite-db, hono-auth, hono-rate-limit, fastapi-service, fastapi-api-key
skill/      Agent Skill (SKILL.md)
test/       unit tests and the MCP end-to-end test

尚未完成

• 用于在 CI 中无需个人令牌即可发布的 GitHub Actions OIDC 令牌（目前已可使用 GITHUB_TOKEN）。
• 在 FTS5 之上加入语义搜索（Workers AI + Vectorize）；目前 Agent 按部分使用普通词语搜索。
• 版本撤回和审核工具。
• 从子文件夹发布的模块只能包含该文件夹内的文件。

许可证

MIT