Tripo 3D 建模 Tripo-Developer/Tripo3D-Plugin-dsh

面向 DeepSeek Harness 的 Tripo 3D

一个只提供技能的 DeepSeek Harness（dsh）插件。它把 Tripo 的 3D 生成能力做成两个技能交给 dsh 智能体；智能体通过 shell 工具驱动 tripo-cli，生成的模型直接落到用户的项目里。

npm tripo-dsh · 零依赖 · 纯 ESM · 无需构建步骤 · 覆盖 Tripo 两个区域（中国大陆与国际）

user DeepSeek Harness (dsh) this plugin Tripo
──── ────────────────────── ─────────── ─────
"make a low-poly treasure chest"
│
▼
┌──────────┐ catalog lists tripo-3d ┌────────────────────────┐
│ agent │ ◀── name + description ─────────────── │ index.js │
│ (model) │ │ ctx.skills │
│ │ ── skill tool loads the body ────────▶ │ .registerProvider() │
│ │ ◀── SKILL.md body ──────────────────── │ skills//SKILL.md │
│ │ └────────────────────────┘
│ │
│ │ ── shell: tripo make "..." --json --yes ──────────────────────▶ ┌─────────┐
│ │ (blocking: submit, poll, download) │ Tripo │
│ │ ◀── last stdout line = result JSON, plus exit code ─────────── │ API │
└──────────┘ │ cn / ov │
│ └─────────┘
▼
./tripo-out/<name>-<id8>/model.glb preview.png task.json (already on the user's disk)

运行时行为（安装、设备登录、方案与确认、退出码、结果 JSON、额度规则）只在 plugin/skills/tripo-3d/SKILL.md 里写一次。本 README 讲仓库、安装、开发、发布与设计。

仓库结构

Tripo3D-Plugin-dsh/
├── plugin/ npm package tripo-dsh, the only distributable
│ ├── package.json dsh.bundle manifest and "files" allowlist
│ ├── cordis.patch.yml bundle layer: inserts one row that loads index.js
│ ├── index.js SkillProvider: reads the SKILL.md files, registers on ctx.skills
│ ├── README.md npm page for end users
│ └── skills/
│ ├── tripo-3d/
│ │ ├── SKILL.md base skill: setup, login, plan, run, credits, results
│ │ └── references/
│ │ └── capability.md models, parameters, steps, other commands (loaded on demand)
│ └── tripo-game-asset/
│ └── SKILL.md game recipes on top of tripo-3d
├── scripts/validate.mjs static checks plus a provider smoke test
├── .github/workflows/publish.yml 在 push 和 PR 时校验；把 v 标签发布到 npm（OIDC） └── README.md 本文件

只有 plugin/ 会发布；它的 files 白名单把其余内容挡在包外。

安装与验证

版本 0.1.6。要求命令行 >=0.8.0：运行 tripo --version；如果缺失或版本更旧，先停下，征得用户同意后安装 npm install -g tripo-cli@0.8，再查一次版本。
共享包同时保留 cn 和 ov 两个账号；问清正确的区域。
P2 比 H/P1 消耗更多积分，P1 仍可选，费用可能无法预估，方案不是服务端强制的授权闸门。

From npm
dsh plugin --profile web add tripo-dsh

From GitHub (the package lives in plugin/; pnpm path: syntax; no build script, so no build allowance)
dsh plugin --profile web add "github:Tripo-Developer/Tripo3D-Plugin-dsh#path:/plugin"

From a local checkout (development; pnpm link, so skill edits apply immediately)
dsh plugin --profile web add /path/to/Tripo3D-Plugin-dsh/plugin

三项检查；前两项不花积分：

1. The configuration layer is composed (no boot)
dsh --profile web --dump-config # shows a "# == tripo-dsh" layer

2. Both skills are in the catalog
dsh web # type / in the input box: tripo-3d and tripo-game-asset

3. End to end (spends real credits)
Ask the agent: "make a low-poly treasure chest 3D model and export FBX"
Expected: doctor, device login if needed, a plan to confirm, tripo make, preview.png

--profile 和 --patch 是启动器参数，必须放在 web 这类应用参数之前。

开发

1. 改 plugin/ 下的文件。智能体的行为在技能里：改 SKILL.md 或 references/capability.md，不要改本 README。
2. 运行 node scripts/validate.mjs 和 node --test scripts/semantic.test.mjs （语义测试套件需要 Node.js 20.11+，无需安装任何东西）。每次 push 到 master、每个 pull request 和每个标签，CI 都会跑校验脚本。
3. 从本地检出在 dsh 里试改动。技能改动立即生效；改完 cordis.patch.yml 或 package.json 后重启 dsh。
4. 当 tripo-cli 改了技能依赖的参数或行为，在同一次改动里更新技能并提升 plugin/package.json 里的 version。

发布

没有用户单独授权，不要打标签、push 或发布。版本变更见 CHANGELOG.md。

包 tripo-dsh 由 GitHub Actions 发布，走 npm 可信发布（OIDC，不用 token）。一次性前置操作：在 npmjs.com 打开包的 Settings -> Trusted Publisher，绑定 Organization Tripo-Developer、Repository Tripo3D-Plugin-dsh、Workflow publish.yml、Environment 留空。至少保留两个包所有者（npm owner add <user> tripo-dsh）。
发布时，先改 plugin/package.json 里的 version，提交，再推送匹配的 tag：

git tag v<version> && git push origin v<version>

publish.yml 会校验插件，检查 tag 与包版本是否一致，然后运行 npm publish；npm 会自动附加 provenance。

设计说明

为什么只做技能

dsh 插件可以注册工具、连接 MCP 服务器或添加钩子。这个插件只注册技能，因为职责划分得很清楚：

- tripo-cli 负责 API 契约：认证、区域检测、任务轮询、下载、退出码，以及 --json 的 stdout 行。技能要求已安装并验证过 >=0.8.0 的 CLI；不得引导安装旧版 registry 发布。
- 技能负责操作手册：什么时候用 Tripo、先跑什么、如何根据结果分支、如何花用户的额度、如何呈现结果。
- dsh 把技能放进模型可见的目录，并提供 shell 工具和沙箱。

因此插件里没有 API 代码：CLI 契约变了，就改技能文本、升版本。智能体用已有的 shell 工具，所以不会给每个请求都加工具 schema；只有模型选中某个技能时，技能正文才进入上下文。CLI 的退出码和最后一行 JSON stdout 就是协议。代价是登录和生成需要 shell 和网络，所以每个技能都要求智能体在两者不可用时如实报告。

dsh 如何加载插件

dsh 里可运行的单元是配置档，由它的各个 bundle 按顺序叠加配置层组成。这个包就是一个 bundle：

plugin/package.json "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } contributes a layer
plugin/cordis.patch.yml insert row { id: tripo-3d, name: 'tripo-dsh' } resolved by package name
plugin/index.js inject = ['skills']; apply(ctx) registers a SkillProvider on ctx.skills

dsh plugin --profile <name> add tripo-dsh 用 pnpm 把包安装到 $DSH_HOME/profiles/<name>/，并追加到 dsh.profile.bundles。每次启动时，各层按以下顺序生效：

1. @deepseek-ai/dsh-base（官方基础层）
2. @deepseek-ai/dsh-web-app（仅 web 配置档）
3. tripo-dsh（本插件，插入一行）
4. 配置档自己的 cordis.patch.yml（用户覆盖）
5. $DSH_HOME/cordis.patch.yml（机器级覆盖）
6. 命令行 --patch <file> 叠加

后面的层按 id 覆盖行，所以用户可以在自己的 cordis.patch.yml 里覆盖 tripo-3d 行来禁用这个插件，不必卸载。

index.js 里的 provider 实现 dsh 技能契约的 list() 和 get()：

- rank: 600 对应 @deepseek-ai/dsh-skill 里的 BUNDLED_SKILL_RANK。同一层内，rank 低的在重名时胜出（项目 .dsh/skills 100，项目 .agents/skills 200，用户级
- 400 和 500，内置 600），因此项目可以用自己的副本覆盖 tripo-3d。
- source: 'bundled' 沿用官方技能徽章服务商；目录中显示
tripo-3d[bundled]。
- resourceBase 指向技能目录，因此 skill 工具可以按需加载显式链接的文件，例如 references/capability.md。
- 每次 list() 和 get() 都会重新读取文件；dsh 自己缓存目录，编辑后立即生效，不会留下过期的服务商缓存。
- 技能注册表位于宿主层级，因此服务商全局注册，每个智能体预设（cordis、ptc、standard）都能看到这些技能。

模型在目录中只能看到每个技能的 name 和 description，当它判断技能相关时，再通过 skill 工具加载正文。因此描述是唯一的触发面，dsh 会按 catalogDescriptionMaxLength（默认 500 字符）截断它。描述中写明「in any language」，这样用中文写的请求也能选中这些技能。

硬性约束

scripts/validate.mjs 会强制检查以下各项；每次改动后都要运行它。

- package.json 中不得出现 dependencies、devDependencies、peerDependencies 或 scripts。 git 安装只拉取源码，不运行构建；prepare 脚本会撞上 pnpm 10 的构建权限门禁，要求用户信任安装期代码。零依赖时，npm、tarball、目录和 git 安装都无需任何权限即可工作。
- 纯 ESM，main: index.js，不用 TypeScript。 没有构建产物，就不会出现「源码已安装但 lib/ 缺失」的失败。
- rank 是字面量 600，不从 @deepseek-ai/dsh-skill 导入，以保持零依赖。改动 BUNDLED_SKILL_RANK 属于 dsh 破坏性变更；请手动同步。
- 技能名用 kebab-case，且与目录名一致；dsh 注册表遇到格式错误的候选会快速失败。
- 描述是单行纯值，空白归一化后最多 500 字符：index.js 只读一行，dsh 会截断更长的目录条目。
- SKILL.md 最多 500 行；参考资料放进技能的 references/ 目录，相对链接必须能在 plugin/ 内解析。
- 每个技能都保留「cannot execute shell commands」条款；dsh 会话可能在没有网络访问或受限沙箱中运行。
- 两个技能都带有 DeepSeek 归属值（TRIPO_CLIENT_APP=deepseek， TRIPO_DISTRIBUTION_CHANNEL=deepseek_plugin），不得带有其他平台的值。
- tripo-3d 同时写明两个区域控制台，并保留面向中国大陆网络的 npmmirror 提示。
- 技能文件中不得出现本地路径，也不得残留其他智能体产品的名称；文本移植自姊妹项目。
- 仓库中任何位置都不得出现中文字符或全角标点。
- 补丁行只有 id 和 name；插件没有配置 schema。
除了静态检查，校验器还会导入 plugin/index.js，用一个假的 ctx 走一遍 registerProvider → list() → get()，断言候选对象的形状（rank、source、invocation、resourceBase），并确认正文里的 frontmatter 已被剥离。

区域与归因

Tripo 运营两个独立站点；账号、控制台和支付方式都不互通：

- cn：https://developers.tripo3d.com，+86 短信登录，支付宝充值
- ov：https://developers.tripo3d.ai，邮箱登录，Stripe 充值

DeepSeek 用户大多在中国大陆，所以两个区域都是硬性要求。技能会在开始设备登录前先问账号在哪个站点，因为在错误的控制台上走设备流程，会把用户送到一个没有其账号的站点。区域选错可以补救：命令行校验密钥时会探测两个区域，tripo doctor 会报告密钥与区域不匹配，并给出修复方法。候选配置流程绝不会悄悄改动 npm registry，也不会回退到语义过时的已发布命令行。

两个技能在每次调用命令行时都会设置 TRIPO_CLIENT_APP=deepseek 和 TRIPO_DISTRIBUTION_CHANNEL=deepseek_plugin。这两个值不含用户数据；命令行的使用分析会读取它们，设置 TRIPO_ANALYTICS_ENABLED=0 可关闭分析。截至 tripo-cli 0.7.1：

- 分析只对 ov 调用运行，所以 cn 的使用永远不会被归因；
- 从 0.7.1 起，ov 事件还会带上用户的 Tripo 账号 id，通过 POST https://apiplatform.tripo3d.ai/verify 查询（选择退出会跳过该查询）；
- 命令行只识别 codex、workbuddy、zcode 和 kimi（以及它们对应的 *_plugin 渠道），其他值一律记为 unknown，包括 deepseek / deepseek_plugin。

因此在命令行加入这些值之前，DeepSeek 的使用在两个区域都不会被归因。

相关

- tripo-cli：技能驱动的命令行，也是命令约定的权威来源；tripo docs --topic commands/make 会打印参数参考。
- DeepSeek Harness： docs/user/develop/basic/publish.md（打包、配置档、层级顺序）， docs/subsystems/skills.md（服务商约定、rank、目录行为）， packages/experimental/skill-badge（官方内置技能示例）。
- 发现：GitHub 话题 dsh-plugin。

许可证

MIT