Skip to content
LoneLeavePublic

About

我们的目标是,输入一个名称就能给出一个完美的3D模型。完成了基于TripoAI生成模型为核心的一系列优化工作流的建立

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

3D 工作台(workbench3d)

本地网页工作台:在浏览器里管文件、看模型、点按钮跑各种 3D 功能。 零依赖、零构建 —— 只需要 Node(22+)。服务端 700 行原生 http,前端裸 ES module。

双击桌面上的 「3D 工作台」 即可(细节见下一节)。

cd D:\AI\workbench3d
node server.mjs
# 打开 http://127.0.0.1:7788

零、桌面图标(最省事的开法)

桌面上有个 「3D 工作台」 图标,双击就完事:

  • 没在跑 → 后台把服务起起来(无黑框、无窗口),等端口通了再打开浏览器;
  • 已经在跑 → 不重复启动,只把浏览器打开;
  • 启动过程写在 logs\launch.log,服务自身的输出在 logs\server.out.log / server.err.log。
文件 作用
start.ps1 真正的启动器:查端口 → 起 server.mjs → 等端口 → 开浏览器
stop.ps1 关掉占用 7788 的进程(想彻底停服务时用,logs\launch.log 会记一笔)
launch.vbs 隐藏窗口的包装(备用入口:wscript launch.vbs)
workbench.ico / workbench.png 图标(同一个立方体,奶白底 + 深棕线条)

快捷方式指向 powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "D:\AI\workbench3d\start.ps1"。 start.ps1 / stop.ps1 故意只写 ASCII:Windows PowerShell 5.1 读无 BOM 的 .ps1 是按 ANSI 解的,中文注释会把解析器搞崩(MissingEndCurlyBrace),而 -WindowStyle Hidden 让这个崩溃完全不显眼——只剩"点了没反应"。.vbs 同理(WSH 也按 ANSI 读)。真要写中文,就存成 UTF-8 带 BOM。

命令行启动(不建快捷方式时):

cd D:\AI\workbench3d
node server.mjs
# 打开 http://127.0.0.1:7788

一、它解决什么问题

现在能力都散在命令行里:pipeline.ps1、parts.py、image_to_hair.py、各种 _probe\*.py。 每加一个功能就要记住一套参数、一个工作目录、一种输出位置。

这个工作台把它们收进同一个界面,并且把"能力"从代码里剥出来变成数据:

  • 左边:任务(job)= 一次角色制作的容器,里面是标准的阶段目录 + 文件树
  • 中间:3D 预览(three.js + VRM),点文件就加载
  • 右边:能力面板,按组排列,每个能力自己声明要什么输入、有哪些参数

二、目录结构

workbench3d\
  server.mjs              服务端(API + 静态文件 + 进程调度 + SSE)
  config.json             端口、各工具的绝对路径、默认超时
  capabilities\           一个 json = 一个按钮(排序靠文件名前缀,`_` 开头不加载)
  public\
    index.html            单页骨架
    assets\app.mjs        界面逻辑(任务/文件树/能力面板/日志)
    assets\viewer.mjs     3D 预览器(three.js + GLTFLoader + three-vrm)
    assets\style.css
    vendor\               three 0.187 + three-vrm(离线,不走 CDN)
  jobs\                   所有任务(唯一真相源)
  runs\                   每次运行的 log.txt / meta.json
  logs\client.log         浏览器端信标(排查前端错误用)

一个 job 长什么样

jobs\纱雾-解剖测试-20261112-141329\
  job.json                     任务元数据(名字、创建时间、备注)
  input\纱雾.glb               你上传的原始文件
  00-inspect\纱雾.anatomy.txt  检查结果
  out\render-views\*.png       运行产物

阶段目录用数字前缀排顺序(00- 10- 20- … 90-),每个能力只读写自己那一段。 这是整套设计的核心:能力之间不互相调用,只通过磁盘上的产物交接,所以任何一个都能被换掉。


三、加一个能力(不用改代码)

方式一:能力市场(点着加)

右侧「能力」栏标题右边有个 市场 按钮,打开就是能力市场:

  • 每张卡片显示:名字、分组、一句话介绍、用哪个工具、要不要输入文件、对应哪个 json 文件。
  • 每张卡带一个开关:卡上第一个按钮就是「已启用 / 启用」。关掉的卡会变虚、加「已停用」标记,并从右侧能力栏消失,文件不动、参数不动,随时可以再打开。停用的能力即使直接调 API 也会被拒(这个能力已在市场里停用,先启用再跑)。
  • 市场是唯一的准绳:右侧能力栏就是「市场里所有启用着的卡」,一一对应、不多不少;两边不会出现"这边有那边没有"。市场标题右上角会写 N 个能力 · M 个已启用。
  • 其余四件事都能做:查(一览)、增(+ 新建能力)、改(编辑,同一张表单)、删(删除,只删那个 json)、外加复制(改个参数就多一个变种)。
  • 新建/编辑的表单就是 json 的图形化:id、显示名、分组、工具、排序、超时、一句话介绍、args(一行一个,支持 {input} {job} {out} {stage} {char} {param:xxx})、是否要输入文件 + 扩展名过滤、capture.stdout 正则、以及参数行(key / 显示名 / 类型 / 默认值)。
  • 保存即生效:写进 capabilities\,右侧能力栏、市场、GET /api/caps 同时更新,不用重启、不用重新加载页面。
  • 安全边界:id 只允许字母数字和 ._-(防目录穿越),文件名由 id 推导;表单里没有"执行任意命令"的口子,工具只能从 config.json 的 tools 里选。

方式二:直接丢 json

在 capabilities\ 里丢一个 json 就行,前端刷新即出现。模板见 capabilities\_template.json。

{
  "id": "hair-cards",
  "name": "头发 · 单图生成发片",
  "group": "头发",
  "order": 50,
  "summary": "一张立绘 → 风格化发片 + 弹簧骨骼链,出 GLB。",
  "needs": "单张正面立绘,头发清晰",
  "tool": "hairpy",
  "args": ["E:/AI/HairDeck/HairDeck/scripts/image_to_hair.py",
           "{input}", "--out", "{stage}", "--n", "{param:n}", "--seed", "{param:seed}"],
  "cwd": "E:/AI/HairDeck/HairDeck",
  "env": { "PYTORCH_CUDA_ALLOC_CONF": "expandable_segments:True" },
  "inputs": [{ "key": "input", "label": "立绘", "accept": ".png,.jpg", "required": true }],
  "params": [{ "key": "n", "label": "变体数", "type": "int", "default": 2, "min": 1, "max": 4 }],
  "produces": ["{stage}/"],
  "timeoutSec": 2400
}

占位符:

占位符 含义
{input} 选中的输入文件(job 内绝对路径)
{stage} 本能力的输出目录(out/<capId>/,只在用到时才创建)
{char} 任务名(去掉日期后缀,用作角色名)
{param:xxx} 参数面板里填的值
{job} / {root} 任务目录 / jobs 根目录

tool 可选 python hairpy blender photoshop dsh pwsh node,实际路径在 config.json 的 tools 里改。 (photoshop 目前只被「PS」按钮用;dsh 只被 Harness 卡片用。.cmd/.bat 垫片会自动走 cmd.exe。)

想抓 stdout 当产物(比如纯脚本打印报告):

"capture": { "stdout": "00-inspect/{basename}.anatomy.txt" }

想让程序从 stdin 读一段文字(提示词里带中文、引号都不怕):

"tool": "dsh",
"args": ["headless", "-"],
"stdin": { "fromParam": "prompt" }

参数类型支持 int / number / text / textarea(textarea 会占满一整行)。

想让它先跑一个 shell 命令:tool: "pwsh" + args 里 -File/-Command。

新增工具(比如某个仓库自带的 python):先在 config.json 的 tools 里加一条,json 里就能用。


四、API

方法 路径 说明
GET /api/health 各工具是否找得到 + 能力数量
GET /api/caps 能力清单
POST /api/caps 新建能力(body 就是那个 json 的内容)
PUT /api/caps/:id 改一个能力(写回同一个文件)
DELETE /api/caps/:id 删一个能力(只删这个 json)
POST /api/caps/:id/duplicate 复制一个能力
POST /api/caps/:id/toggle {enabled:true|false} 启用/停用(停用后不出现在能力栏、也不能跑)
POST /api/caps/reload 重新读 capabilities\
GET/POST /api/jobs 列出 / 新建任务
GET /api/jobs/:id 任务详情(含文件树、历史运行、harness 对话记录)
PATCH /api/jobs/:id {name} 改名(只改显示名,文件夹不动)
DELETE /api/jobs/:id 删任务
POST /api/jobs/:id/duplicate 复制整个任务文件夹(含 input/work/out),新 id 加 -copy
POST /api/jobs/:id/upload?dir=&name= 上传(原始字节体,不经 multipart)
POST /api/jobs/:id/run {capId, input, params} → 起一个 run
GET /api/models 给左下角 Harness 用的模型清单(读 API key 现查,10 分钟缓存)
POST /api/jobs/:id/harness {prompt, model} → 起一次 Harness 运行(不走能力系统)
GET /api/runs/:id 运行详情 + 日志
GET /api/runs/:id/stream SSE:start / line / end / error
POST /api/runs/:id/kill 终止
GET /files/jobs/…、/files/runs/… 静态取产物(只放行这两个前缀)
POST /api/open {kind:'blender'|'photoshop'|'folder', jobId, rel?} 在本机开程序;dry:true 只回解析结果不启动
POST /api/clientlog 浏览器信标写入 logs/client.log

所有路径都过 safeJoin,出不了根目录。


五、当前装了哪些能力(7 个)

组 能力 干什么
检查 GLB 解剖 纯 Python 拆 GLB 容器,1 秒看清节点/材质/贴图/骨骼(不启动 Blender)
改造线 全流程 / 只体检 / 只导出 调 character-pipeline 的 intake → audit → export → verify
分件 法向面组 / 按连通块 调 parts.py,把一坨网格拆成部件
头发 单图生成发片 调 HairDeck,出 GLB(已内置 8GB 显存的环境变量)

左下角的 Harness(常驻对话)

左下角固定一块面板:对话记录 + 一个输入框 + 一个模型下拉。它不是"发一条消息看一次日志",而是一段有记忆的对话:

  • 每次发送 = 一个 dsh --profile headless 运行,cwd 就是当前任务文件夹,所以它能自己读 input\、跑能力、写 out\。
  • 对话会记住上文:第一轮结束时把 dsh 的 sessionId 存进 <job>\harness\session.txt,之后每轮都用 --session-id 续上,所以"刚才那个数字是多少"是问得通的。实测:先让它记 4271,下一轮问它,答 4271。
  • 每一问一答都落盘:<job>\harness\history.jsonl 追加 {runId, prompt, model, label, at};回答正文写在 runs\<runId>\reply.txt。刷新页面、换机器、隔天回来,对话还在原位。
  • 面板高度占左栏 44%,记录区自己滚动;右上「收起」可折成一行,任务标题旁的 Harness 按钮会展开它并把光标放进输入框。
  • 会话失效(比如任务文件夹被移动过)时,这一轮会明确写"会话已重置,下一条会重新开始",并自动删掉 session.txt,不会一直报错。
  • 模型下拉里的项来自 models.json(工作台根目录),按组显示 DeepSeek 官方 / likehub / liuhai / dragon,只列出凭据文件里有对应 key 的 provider。
  • 选中项的值是 provider::model。服务端据此生成 --patch:把该 provider 的定义塞进 llm-pi-ai、再让 agent-default-model 指过去;磁盘上的 profile 一个字节没动,patch 文件在 run 结束后删掉。
  • 用的 key 从 ~/.dsh/.credentials.yaml 取,只注入这一次的子进程(LIKEHUB_API_KEY / LIUHAI_API_KEY / DRAGON_API_KEY / DEEPSEEK_API_KEY),不进日志、不发前端。
  • 选择记在 localStorage,下次打开还是上次那个模型。
  • 没选任务时按钮禁用、提示「先选一个任务」——因为工作目录必须有值。
  • 加一个模型:编辑 models.json,在 providers.<名字> 里放 provider 块、在 catalog 里加一行 {provider, model, group, label},刷新即可(/api/models 实时读文件)。
  • 桌面端的 deepseek-account 这套没列进来:它走账号登录态,dsh headless 拿不到那个凭据服务,选它必然 MISSING_CREDENTIAL。

外部程序入口

任务标题下面一排按钮,作用于当前选中的文件:

按钮 行为
Blender 选中的是 .blend 就直接打开它;否则只启动 Blender
PS 选中的是图片(png/jpg/psd/tif/webp/bmp/exr)就打开它;否则只启动 Photoshop
定位 在资源管理器里选中这个文件;没选文件时打开任务文件夹
Harness 展开左下角对话并把光标放进输入框

路径来自 config.json 的 tools.blender / tools.photoshop,换机器只改这两行。服务端只认这三个 kind,界面传不进任意命令。

任务卡:右键就是增删查改

左栏顶部两个按钮是 + 新建任务 和 删除(删当前选中的)。任务卡上右键出菜单:

菜单项 做什么
打开 切到这个任务
重命名… 改显示名(PATCH /api/jobs/:id,只动 job.json,不动文件夹名,避免打断已有 run 的路径记录)
复制一份 整个文件夹复制成 …-copy,新任务名加「(副本)」——同一份输入、换参数重跑最省事
在资源管理器里定位 打开该任务目录
删除任务 连产物一起删(有确认)

六、排查

  • 页面白屏:先看 logs\client.log。前端启动、预览加载、异常都会用 navigator.sendBeacon 打到这里;浏览器控制台看不到的模块加载失败,这里有。
  • 改了 mjs 没反应:Ctrl+F5。静态文件带 no-store。
  • 能力不出现:点右上「重载能力」,或看 GET /api/caps 返回的 errors。
  • 跑不动:看该 run 的 runs\<runId>\log.txt,界面底部日志是同一份。

已知的坑(踩过的)

  1. 别用 PowerShell 的 Get-Content/Set-Content 改 .mjs/.html —— 它默认按 GBK 解码 UTF-8,会把中文和 ▾ ▸ … 这类符号写成乱码,直接撕坏字符串字面量导致整个模块不执行。用编辑器/write 工具。
  2. three.module.js 从 0.16x 起拆成了两个文件,必须同时放 three.core.js,否则 404、页面白屏。
  3. THREE.Clock 在 0.18x 已弃用,用 performance.now() 自己算 delta。
  4. 预览地址必须带 job id(/files/jobs/<id>/input/x.glb),/files/ 不放行裸相对路径。
  5. Harness 报 MISSING_CREDENTIAL:dsh headless 读不到桌面端的凭据服务。工作台在启动 dsh 前会从 ~/.dsh/.credentials.yaml 里取 DEEPSEEK_API_KEY 塞进那个子进程的环境变量(只在服务端内存里过一手,不进日志、不发前端)。文件里没有这个键时,手动 setx DEEPSEEK_API_KEY sk-... 再重启服务。
  6. dsh.cmd 不能直接 spawn:Windows 上 .cmd/.bat 要走 shell: true,服务端已按扩展名自动判断。
  7. 界面是奶白偏黄的浅色:style.css 顶部一组变量(--bg/--bg2/--line/--acc…)就是全部配色,改主题只改这里;3D 视口的底色在 viewer.mjs 的 setClearColor 与 scene.background(0xf3ecd9)两处。
  8. --json 是个模式开关,必须放最后:dsh --profile headless --patch X --session-id S --json -。写成 --json --patch X 会报 unknown option '--patch'——--json 之后的参数不再按全局选项解析。
  9. --patch 文件必须是"补丁条目数组",不是配置对象:[{"id":"agent-default-model","name":"@deepseek-ai/dsh-agent-default-model","config":{...}}],否则报 must be a top-level YAML array of loader patch entries。
  10. --session-id 只认已存在的会话(不会顺手新建)。所以续聊的前提是上一轮真的跑成功、session.txt 里存到了 id;会话的 cwd 被移动过就会拒绝,需要重置。

七、下一步(没做的)

  • 能力还缺:验收(verify_export)、贴图(烘焙 / Fix UV)、动捕(FlowHMR)、导出到 UE5。
  • 还没有"一次点完跑一条线"的编排(现在是一个按钮一段)。
  • 预览只支持 GLB/VRM,FBX 需要换 loader。
  • 任务模板还没做(复制一份 是它的一半:复制后再删掉不需要的产物);refs\(参考图)也还没单独做一栏。

About

我们的目标是,输入一个名称就能给出一个完美的3D模型。完成了基于TripoAI生成模型为核心的一系列优化工作流的建立

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages