本地网页工作台:在浏览器里管文件、看模型、点按钮跑各种 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 浏览器端信标(排查前端错误用)
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里选。
在 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 里就能用。
| 方法 | 路径 | 说明 |
|---|---|---|
| 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,出不了根目录。
| 组 | 能力 | 干什么 |
|---|---|---|
| 检查 | GLB 解剖 | 纯 Python 拆 GLB 容器,1 秒看清节点/材质/贴图/骨骼(不启动 Blender) |
| 改造线 | 全流程 / 只体检 / 只导出 | 调 character-pipeline 的 intake → audit → export → verify |
| 分件 | 法向面组 / 按连通块 | 调 parts.py,把一坨网格拆成部件 |
| 头发 | 单图生成发片 | 调 HairDeck,出 GLB(已内置 8GB 显存的环境变量) |
左下角固定一块面板:对话记录 + 一个输入框 + 一个模型下拉。它不是"发一条消息看一次日志",而是一段有记忆的对话:
- 每次发送 = 一个
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,界面底部日志是同一份。
- 别用 PowerShell 的
Get-Content/Set-Content改.mjs/.html—— 它默认按 GBK 解码 UTF-8,会把中文和▾ ▸ …这类符号写成乱码,直接撕坏字符串字面量导致整个模块不执行。用编辑器/write工具。 three.module.js从 0.16x 起拆成了两个文件,必须同时放three.core.js,否则 404、页面白屏。THREE.Clock在 0.18x 已弃用,用performance.now()自己算 delta。- 预览地址必须带 job id(
/files/jobs/<id>/input/x.glb),/files/不放行裸相对路径。 - Harness 报
MISSING_CREDENTIAL:dsh headless读不到桌面端的凭据服务。工作台在启动 dsh 前会从~/.dsh/.credentials.yaml里取DEEPSEEK_API_KEY塞进那个子进程的环境变量(只在服务端内存里过一手,不进日志、不发前端)。文件里没有这个键时,手动setx DEEPSEEK_API_KEY sk-...再重启服务。 dsh.cmd不能直接 spawn:Windows 上.cmd/.bat要走shell: true,服务端已按扩展名自动判断。- 界面是奶白偏黄的浅色:
style.css顶部一组变量(--bg/--bg2/--line/--acc…)就是全部配色,改主题只改这里;3D 视口的底色在viewer.mjs的setClearColor与scene.background(0xf3ecd9)两处。 --json是个模式开关,必须放最后:dsh --profile headless --patch X --session-id S --json -。写成--json --patch X会报unknown option '--patch'——--json之后的参数不再按全局选项解析。--patch文件必须是"补丁条目数组",不是配置对象:[{"id":"agent-default-model","name":"@deepseek-ai/dsh-agent-default-model","config":{...}}],否则报must be a top-level YAML array of loader patch entries。--session-id只认已存在的会话(不会顺手新建)。所以续聊的前提是上一轮真的跑成功、session.txt里存到了 id;会话的 cwd 被移动过就会拒绝,需要重置。
- 能力还缺:验收(
verify_export)、贴图(烘焙 / Fix UV)、动捕(FlowHMR)、导出到 UE5。 - 还没有"一次点完跑一条线"的编排(现在是一个按钮一段)。
- 预览只支持 GLB/VRM,FBX 需要换 loader。
- 任务模板还没做(
复制一份是它的一半:复制后再删掉不需要的产物);refs\(参考图)也还没单独做一栏。