Skip to content
项目

pearjelly/deep-blend has 102 GitHub stars and 1 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 08:53 UTC. Last push 2026-11-11.

这些数字如何统计

实测星标增长

24小时
0
7天
正在收集历史
15天
正在收集历史
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Create and refine Blender product scenes in DSH: editable recipes, model imports, real previews, saved revisions and PNG/MP4 delivery.

人工智能

README.zh.md

原文

DeepBlend Studio

0.23.0 发布与验收范围 · DeepSeek 1017 / DSH 0.2.1 适配记录

DeepBlend Studio:创建、调整、渲染。图中为流程示意,不是产品截图

Awesome DSH Plugin

在 DSH 里,把产品场景做出来。
从作品配方或自己的模型开始,调整造型、材质和灯光,用真实渲染判断效果,再交付结果。

最新 npm 版本 主线 CI 状态 MIT 许可

English · 简体中文

安装并开始 · 看看工作台 · 文档导航 · 最新版本 · 参与贡献

0.23.0 已在 GitHub 和 npm 发布,可以逐面修复平面网格的重复纹理坐标,保持几何与摄影;也包含完整台灯表面放置和完整取景。完整验收、全新安装和公开三路安装均已核验;10 月 28 日两份社区公开目录均已读回 0.23.0。详见发布记录与社区收尾记录。

独立创作候选新增运动预览、直接图片/影片交付及指定机位评审;这些候选改动尚未公开发布,也不代表已经通过独立用户或美术验收。

在「版本」页使用「保存可编辑副本」,下载一个已保存版本的 ZIP,可选附带已核验的同版本完成影片。准备支持取消、重试和刷新恢复。详见使用步骤。

安装并开始

准备好 Node.js 22.23.3 或更新版本、DSH 0.1.5-rc.2、pnpm 10.28.2 和 Blender 5.2.1 后:

npm_config_ignore_workspace_root_check=true npm_config_auto_install_peers=false dsh plugin --profile web add @deepblend/dsh-blender-bundle
dsh web

上述两个临时参数允许 pnpm 向 DSH profile 的工作区根安装,并使用已安装 DSH 提供的 peer;只作用于这一条命令,不改全局 pnpm 配置。

已运行的 dsh web 需要重启。在新会话中选择 DeepBlend Studio 预设,从侧栏打开 Blender 工作台。 安装会同时加入工作台与智能体预设。

第一次配置环境? 先看中英文快速上手。 输出 MP4 另需 FFmpeg 和 ffprobe;创建场景和渲染图片可以先做。

预构建包、源码安装与已有版本升级

预构建包:

npm_config_ignore_workspace_root_check=true npm_config_auto_install_peers=false dsh plugin --profile web add https://github.com/pearjelly/deep-blend/releases/latest/download/deepblend-bundle.tgz

当前源码:

npm_config_ignore_workspace_root_check=true npm_config_auto_install_peers=false dsh plugin --profile web add 'github:pearjelly/deep-blend#path:/packages/deepblend/bundle'

0.9.0 的公开三路验证使用 DSH 0.1.5-rc.2 与 pnpm 9.15。源码/npm 路线在临时 profile 中明确允许工作区根安装,并使用已安装 DSH 提供的 peer 依赖;自动补装较新 peer 曾遇到 dsh-type-meta 获取失败。以下设置只作用于本次命令,不写个人配置:

npm_config_ignore_workspace_root_check=true npm_config_auto_install_peers=false dsh plugin --profile web add @deepblend/dsh-blender-bundle

相同设置也可用于上面的源码命令;预构建包已独立安装通过。源码构建授权仍按 DSH 的明确提示处理。

所有路线都需要 pnpm 在 PATH 中。源码路线若提示构建授权,按 DSH 给出的具体提示处理。 升级已有安装时,先移除旧注册再添加,并重启 dsh web:

dsh plugin --profile web remove @deepblend/dsh-blender-bundle
npm_config_ignore_workspace_root_check=true npm_config_auto_install_peers=false dsh plugin --profile web add @deepblend/dsh-blender-bundle

配置、存储与升级细节见安装指南。

新案例:夜班 / Night Shift

Night Shift / 夜班

在 DeepSeek Harness 实际安装的 deep-blend 0.5.0 中,导入 Blender 官方 CHARGE Packbot,制作工业布景、灯光和六秒相机运动。79 个网格部件、511,595 个面、19 张嵌入图片;1080p / 24 fps / 144 个实际渲染帧。 第二个实际 DSH 项目已验证相同场景摘要,第 72 帧预览最大通道差值为 1/255。

播放视频 / Watch · 复现指南 / Replay guide · 完整复现素材 / Replay inputs

机器人使用原资产第 1 帧的静态姿态,视频展示新布景与相机运动。CHARGE Packbot © Blender Studio / Blender Foundation — CC-BY;新增场景与脚本为 MIT。推广版只增加标题和署名。0.8.1 安装包包含 examples/charge-study/ 的场景、提示词与复现工具;指南固定本次已验证的 0.5.0 环境。

新案例:古塔庭院 / Courtyard Pagoda

古塔庭院首帧

最新案例视频围绕佛塔庭院展开,共五段镜头:37.5 秒、900 帧、24 fps、1280 × 720,Cycles / 128 samples。播放完整视频并查看关键帧 · 案例记录 · 素材来源与许可。

真实作品:光与材质

用本机安装的 DeepBlend 制作三组产品场景:琥珀玻璃、香槟金属灯具、编织格栅音箱。每组包含高清主图、材质近景和一段 6 秒 / 1080p / 24 fps 的真实镜头动画。

琥珀时间 · Amber Atlas 金色暮光 · Solstice 织声 · Nocturne
DeepBlend 真实镜头动画:琥珀玻璃与象牙釉盘 DeepBlend 真实镜头动画:建筑背景前的香槟金桌灯 DeepBlend 真实镜头动画:深色木纹音箱与编织格栅
播放 MP4 播放 MP4 播放 MP4

页内动图从实际成片按 12 fps 取样;MP4 保留全部 144 个渲染帧,帧率为 24 fps。点击预览可查看 2560×1440 高清静帧。

打开作品画廊 · 场景源码与复现 · 渲染来源记录 · Blender 官网视觉参考

作品的造型、布景与输出来自公开 SceneSpec 和实际渲染;官网案例用于光影与材质的设计参考。以上三组原创产品场景没有使用官方案例的模型、纹理或成片。

从具体作品起步

下面是真实 Blender 渲染。台灯、玻璃陶瓷和音箱有可重建输入与来源记录, 杯子图片来自青釉杯教程的实际交付。

金属台灯 玻璃陶瓷
Cycles 实际渲染的金属台灯 Cycles 实际渲染的空心玻璃瓶与陶瓷托盘
桌面音箱 青釉带把手杯
Cycles 实际渲染的桌面音箱 青釉杯教程交付的原始 PNG

在作品配方中选起点,调整颜色、粗糙度和曝光,创建后直接看实际预览。 创建失败时保留输入,按提示修复后可重试原请求;已保存但回执丢失的项目会直接恢复,避免重复创建。浏览器创建草稿可在重载或重新打开后明确选择继续,多个页面各自保留输入。 也可以导入自己的 glTF、GLB、OBJ 模型和外部贴图。

从产品首作开始: 创建香槟金属桌灯,再在同一保存作品中继续改稿。 候选版本台灯教程覆盖三张图片、真实六秒短片和可编辑 ZIP,并标明尚未发布的入口。青釉杯教程保留为几何练习;已知杯柄根部凸起尚未通过质量审阅,不作为推荐首作。

选择你的使用方式

从哪里开始 适合做什么 继续阅读
工作台创作 从配方或模型开始,直接改尺寸、材质、相机和灯光 工作台指南
与智能体协作 描述场景,查看预览,分步骤修改,再决定是否交付 智能体上手
创作配方与工具 通过公共 SDK 校验场景、编写配方或集成内容工具 公共作者 SDK

不必先记住全部工具。可以先用配方和工作台控件完成一次创作,再让 DeepBlend Studio 智能体协助修改。

在使用 DeepBlend Studio 预设的会话中,可以这样开始:

列出可用作品配方,先给我看青釉带把手杯及其参数,暂时不要创建。 我选好数值后再创建预览;后续材质和灯光修改分别保存为独立版本。

这是请求示例,不是实际运行记录。具体操作见工具指南。

从起点到保存的结果

步骤 你可以做什么 能检查什么
创建 使用配方,或上传模型资源包、纹理和环境图 配方版本、原始资源路径与来源字节
调整 改造型、倒角、阵列、局部材质和表面纹理,调整摄影 每次采纳修改后的独立场景版本
检查 对照预览,在固定相机与帧看材质图、灰模图和参考目标 实际图片、机位、帧号和渲染条件
交付 输出 PNG 帧和 MP4,取消或续做任务 帧进度、实际设置与交付来源

喜欢一套构图与灯光时,可从保存作品的指定版本复用摄影设置,先套用到草稿,再检查并保存,减少重复填写。

素材库 · 建模 · 摄影 · 固定视角检查 · 恢复

看看工作台

下方光台截图来自运行中的 DSH 工作台与真实浏览器;拍摄说明和来源摘要记录桌面与窄屏画面。 它们是产品截图与真实渲染;首屏横幅是品牌流程示意。

实际光台工作台中的青釉杯预览、已保存版本与最近结果

查看版本预览对照与渲染拼图

对比图与渲染拼图由 deepblend/tools/capture-docs-images.mjs 生成。对照的是两个保存版本的实际预览,来源场景与图片摘要记录在截图清单中;较早的工作台截图也保留在该清单内。

带各自图片摘要与时间戳的实际修改前后预览

拼图包含动画采样帧与额外检查机位。

实际 Blender 七视角渲染拼图

让每次调整都有依据

  • 保留历史: 采纳修改后形成不可变版本;恢复时移动当前指针,中间版本仍保留。
  • 按来源重建: SceneSpec 是事实来源,.blend 是编译产物,场景与锁定资源可以重新构建。
  • 继续交付: 检查磁盘上的真实帧,补渲缺失或损坏帧;帧齐时直接继续编码。
  • 明确预算: 昂贵操作经过审批闸门,任务始终关联要渲染的场景版本。
  • 分开判断: 技术测量与有图片依据的美术评审分别保留,分数上升不等于画面更好。

作品评审 · 恢复指南 · 安全控制

按任务找文档

我想…… 从这里看
安装、配置 Blender 或更新插件 快速上手 · 安装与自检
完成第一次创作 台灯首作(候选版本)
导入自己的模型与贴图 素材库
调整造型、相机与灯光 建模指南 · 摄影编辑
对照版本,定位粗糙的原因 固定视角检查 · 参考图片
续渲或恢复场景 故障恢复
投稿配方或使用 SDK 配方创作 · 公共 API
贡献代码、复现证据或查看限制 贡献指南 · 验收记录

完整入口见文档导航。

开始前的几个问题

第一次创作必须接入 AI 模型吗?

配方、工作台控件和本地渲染可以直接使用。与智能体对话、基于模型的视觉评审使用 DSH 中配置的模型。

项目保存在哪里?

普通安装默认使用 DSH home 下的项目目录。源码开发工具可以使用仓库内存储,切换配置前先看存储说明。

支持所有 Blender 编辑和所有平台吗?

建模能力以受支持的生成器与编辑为准。受管 Blender 下载面向 macOS arm64, 其他平台自行安装与配置;CI 也覆盖部分 Linux x64 路径。具体覆盖与作品质量、真人采用等开放问题见验收记录。

版本与社区

最新版本 · 更新记录 · 报告问题或提出建议

MIT — 许可。安全问题按安全报告方式提交;参与开发前阅读贡献指南。

开发与验收参考:架构、工作区装配、完整测试和核心机制

下面保留可复现的开发说明与测量快照。普通使用者可以从上面的快速上手与操作指南开始。

这是什么

SPEC.md 是唯一主规格,本仓库是它的实现。架构分三个平面:

DSH Host Composition        →  packages/deepblend/bundle/cordis.patch.yml
  共享服务:Blender 执行、Project/Revision Store、原子提交事务、UI Host 半

DeepBlend Agent Presets     →  ~/.dsh/.agent-presets/{deepblend,deepblend-dev}/
  单个会话自己的模型可见工具与提示词

Blender Runtime             →  packages/deepblend/provider-local/python/
  受控 bpy 执行、确定性 JSON 协议、SceneSpec 编译器

核心规则:发布服务的行必须放 Host composition;preset 只能放模型可见工具、 Persona 与会话级能力。工具行不发布任何服务,因此天然满足 SPEC §4.4。


目录

deepblend/
  schemas/            权威 JSON Schema(SPEC §5.2):scene-spec / scene-patch / job-result
  presets/            agent preset 的**源**(SPEC §5.2):deepblend/(正式,最小权限)与
                      deepblend-dev/(开发);preset 自带的 skills/ 随目录一起部署
  fixtures/           产品转台 golden 场景;室内房间(正确参考 + 三个植入缺陷的派生场景)
  docs/               **手册(使用视角)**:install / usage / recovery —— 见上面「三份手册」
                      **规格与记录**:dsh-baseline / runtime-audit / architecture-decisions
                      / tool-contracts / milestone-status / m2-brief / m3-brief / m4-brief
                      **安全**:security.md —— SPEC §15 的逐条对照表(含**没做到的那几条**)
                      **实测日志**:probe-m3-restart.log / probe-m3-delivery.log / probe-m4-client-loop.log
                      / probe-dsh-plugin-install.log(两条装法各自测到什么,见「5. 安装进 DSH profile」)
                      / probe-dsh-plugin-github.log(**源码**路线:`Packages: +7`,六个同级包全靠自指 git spec)
                      / probe-dsh-plugin-tarball.log(**tarball** 路线:`Packages: +1`,产物自包含、不解析任何依赖;
                        也记下了「URL 跨版本逐字节相同,所以 pnpm 的 store 会把上一个产物装给你」这条实测)
                      / probe-dsh-plugin-npm.log(**npm** 路线:`Packages: +7`,七个包全从 registry 解析、一个都不回 git)
                      这三份用**同一套判据**读回 `installed version` 与 `/deepblend/workbench`——
                      版本号是产物对自己的声明,而那条路由只有当前版本才有
                      / probe-disk-full.log(卷写满时会发生什么:一帧不丢、可续渲)
                      / probe-coverage.log(整套验收执行了产品的哪些行,以及量具看不见什么)
  docs/images/        版本对比、渲染拼图、历史工作台截图 + manifest.json
  docs/assets/lighttable/  当前光台桌面与窄屏截图、独立来源清单与复拍说明
  tools/              link-workspace.mjs —— 把 node_modules 链接到已安装的 DSH 部署(全新 clone 的第一步)
                      workspace-layout.mjs —— 从源码里读出「要链接哪些包」,链接器与契约测试共用
                      dsh-baseline.json —— DSH 兼容性锚点(版本号)的机器可读来源
                      install-blender.mjs —— 下载/校验/安装受管 Blender 到 .tools/(免 sudo)
                      blender-release.json —— Blender 的 pin:版本、URL、字节数、sha256
                      install-plugin.mjs —— 装配 profile:包链接 + bundle 注册 + operator layer
                      operator-layer.mjs —— 从 bundle 推导存储位置;安装器与测试 harness 共用
                      create-demo-project.mjs —— 在真实 store 中生成演示项目
                      make-visual-fixtures.mjs —— 从室内房间派生三个缺陷场景
                      visual-review-live-probe.mjs —— 直接调用视觉模型的最小探针
                      inspect-checkpoint.py —— 量编译后几何
                      m3-restart-probe.mjs —— M3 的第一个任务:真实 kill -9 重启探针
                      m3-delivery-acceptance.mjs —— 真实项目上的 1080p 交付(约 30 分钟)
                      install-presets.mjs —— 把 deepblend/presets/ 部署到 $DSH_HOME(--check 只报漂移)
                      browser-driver.mjs —— 无依赖的 CDP 驱动(M4 的浏览器验收用它开真实 Chrome)
                      dsh-web-harness.mjs —— 自带 DSH home 与项目 store 地启动一个 dsh web
                      ui-loop-probe.mjs —— M4 的第一个任务:量「改一行客户端代码怎样才能看见」
                      capture-docs-images.mjs —— 生成 docs/images 的截图与渲染拼图
                      dsh-plugin-install-probe.mjs —— 在临时 DSH_HOME 上量「DSH 自己的装法」到底做了什么
                      disk-full-probe.mjs —— 在一个真的 24 MiB 卷上把磁盘写满,看宿主怎么收场
                      coverage-probe.mjs —— 跑整套并列出产品里从没被执行过的行(含它自己的盲区)
                      count-assertions.mjs —— 契约层断言总数怎么数出来的(README 那组快照的命令;
                                              规则自己有测试,因为它写错过一次,D143)
                      probe-target.mjs —— 探针该测哪个 revision:从 store 的 currentRevision 读,而不是记住一个 id
                      coverage-merge.mjs —— 那份读数的合并规则:行级判定写在模块里,因为它在四轮里错过四次
                                            (`contract/probe-merge.test.mjs` 用合成的 V8 报告驱动它)
  tests/              单元、契约、Blender 集成、组合激活、真实模型 e2e
    contract/         159 个 *.test.mjs(当前源码)
    lib/              dsh-deployment.mjs —— 定位并加载运行中的 DSH 部署
                      command-claims.mjs —— 「文档里点名的命令是否存在」只有一份(模板与证据日志共用)
                      milestone-claims.mjs —— 「不许复述里程碑状态」只有一份(README / CONTRIBUTING / 模板共用)
                      m3-host-child.mjs —— 独立进程里的 Host(供重启套件 fork)
                      spec-tools.mjs —— 从 SPEC.md §11 读出工具清单(三个套件共用这一份)
                      tool-plane-harness.mjs —— 用 stub 的 tools 注册表与 stub 的 blenderStudio 组装工具面
                                                 (两个契约套件共用;不需要 Blender 也能跑失败分支与卡片标题)
    blender-integration/  M0 能力探测 + M1 批量 SceneSpec + M2 视觉闭环 + M3 持久渲染
    composition/      Host 组合激活 + preset 工具面(M0–M3)+ UI 平面(座位表与闭集路由)
    e2e/              ui.e2e.mjs —— 真实浏览器验收(自带 dsh web 与项目 store)
                      visual-live.e2e.mjs / ui-live.e2e.mjs —— 真实模型调用(不进 run-all.sh)

packages/deepblend/
  contracts/          纯数据与纯规则:Schema、语义校验、digest、稳定错误码、Canonical 投影、
                      PNG 编解码 + contact sheet 合成、VisualIssue 评分器、修复循环控制器
  provider-local/     BlenderRuntime:ctx.subprocess 传输层 + python/ 运行时
    python/           bootstrap.py 分派器 + 10 个动作模块(另有 deepblend_util.py 这一份工具)
                      deepblend_geometry.py 提供参数化网格,deepblend_images.py 构造图片材质,deepblend_bridge.py 提供实时连接
  host/               blenderStudio 门面、Project Store、Revision 事务、路径守卫
  tool/               20 个模型可见工具(Agent preset 平面,不发布服务)
  ui/                 工作台 UI:Host 半(闭集 HTTP 路由)+ Client 半(lib/client.js,
                      手写的 CJS 工厂,无打包步骤 —— 改一行存盘即可在打开的页面里看到)
  bundle/             Host Bundle:cordis.patch.yml + dsh.bundle 声明

快速开始

0. 这台机器上得有什么

需要 用在哪 没有它会怎样
macOS arm64 受管 Blender 是一份 macOS 的 DMG(deepblend/tools/blender-release.json 的 platform) npm run blender:install / blender:check 报「只认得钉住的那份 macOS arm64 构建」并退出 2,同时告诉你去设哪个键;别的平台自装 Blender 5.2.1 并把 blenderPath 设在 operator layer 即可。契约层不受影响(CI 就跑在 Linux 上)
Node ≥ 22(package.json 的 engines,CI 跑的就是 22) 一切 跑不起来
一个已安装的 DSH 部署,版本钉在 deepblend/tools/dsh-baseline.json 本仓库的 import 目标 第 1 步的报错会点名要装哪一个版本
Python 3 render-job.test.mjs 验证帧命名与账本;asset-preview-provider.test.mjs 验证逐图相机与渲染信息 依赖 Python 的检查会失败;其他测试文件继续执行
git 契约层里读仓库状态的两条断言 没有 .git 时那两条报「not a git checkout」并跳过(退出码仍然是 0)
Blender 5.2.1(npm run blender:install) 需要 Blender 的那几层 契约层照跑;run-all.sh 找不到 Blender 会直接以 2 退出
ffmpeg + ffprobe(macOS brew install ffmpeg;Debian/Ubuntu sudo apt install ffmpeg;Fedora sudo dnf install ffmpeg;Windows winget install ffmpeg) 只有交付的编码那一步:blender_final_render 渲完最后一帧之后把它编成 MP4,blender_export 同理 渲染照跑、帧一帧不丢,只有编码以 ENCODER_NOT_FOUND 失败,消息里点名 ffmpeg 与装法。装上之后对同一个 job 调 blender_export 即可补上交付(recovery.md §3;第 30 轮实测:2 帧的 job 渲完、编码失败、帧保留、装好编码器后导出并发布成功)
Google Chrome 只有 npm run docs:images 与 M4 的浏览器验收 那两件事不跑,其余不受影响

Python 3 这一行是 2026-09-14 才写下的(milestone-status.md §25):在那之前它是一条 谁也不知道的依赖,而缺了它的机器看到的是 spawnSync python3 ENOENT 的堆栈—— 它落在 60 条断言里的第 15 条,于是后面 45 条一起消失,还没有汇总。同一个仓库里, 产品侧早就把「每个失败都必须是可分支的结果、不许是堆栈」写成了规矩(SPEC §9.4), 而这条规矩此前没有用在检查产品的那个文件上。

1. 装配工作区(全新 clone 的第一步)

本仓库的 node_modules/ 不在版本控制里:它没有任何内容,只有 18 个指向 已安装的 DSH 部署、普通运行依赖与本仓库 packages/ 的绝对符号链接(见 .gitignore)。 所以刚 clone 下来的仓库解析不了自己写的任何一句 import:需要 import 的那些契约文件 会在跑第一条断言之前死于 ERR_MODULE_NOT_FOUND,只有纯读文件的那几个照跑:

$ node deepblend/tests/run.mjs
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@deepblend/dsh-blender-contracts'
DeepBlend tests: 30/159 file(s) passed

(这两个数字由检查钉住 ✓:contract/readme-fresh-clone.test.mjs 会造一份没有 node_modules 的树、 跑同一条命令、比对这一行 ✓✓——它们曾经是 0/16 ✗,而那两处都漂了:文件从 16 涨到 64 ✓, 而「全部死于 import」也不再成立 ✓——十个纯读文件的套件根本不需要链接 ✓。)

这不是假设——2026-09-14 DSH profile 被重装后,本仓库就是这个状态。补上这一步:

npm run setup          # = node deepblend/tools/link-workspace.mjs
npm run setup:check    # 只报告漂移,不改动任何文件
node deepblend/tools/development.mjs sdk  # 准备锁定的 SDK 类型检查工具

它不写 DSH 安装目录,也不写 $DSH_HOME:只在仓库根建 node_modules/@deepseek-ai/* 与 node_modules/@deepblend/* 两组符号链接,然后逐个真的 import 一遍来验证。 要链接哪些包不是写死的清单,而是从本仓库源码里读出来的——新增一句 import '@deepseek-ai/dsh-xxx' 只需重跑本命令,不需要改任何脚本。

新开发环境也可直接使用 npm run dev:setup 完成固定依赖安装、链接和 SDK 工具准备。 SDK 编译工具只用于开发验收;产品运行不需要 TypeScript,外部 DSH 部署不会因准备工具被重装。

为什么不直接写进 package.json 的 dependencies:那会在仓库里装下第二份 harness, 它可以和真正运行 DeepBlend 的那个部署各自漂移,于是契约套件会对着一份产品并不加载的 cordis 变绿。理由与实测见 deepblend/tests/lib/dsh-deployment.mjs;这条不变式由 deepblend/tests/contract/workspace-links.test.mjs 守住。

2. Blender

Blender 安装在工作区内(免 sudo、免系统目录写入):

.tools/Blender.app/Contents/MacOS/Blender     # Blender 5.2.1 LTS, arm64

来源与校验和见 deepblend/docs/dsh-baseline.md §5。.tools/ 已被 git 忽略。

3. 运行全部验收测试

bash deepblend/tests/run-all.sh
npm run verify:clone          # 换一台「从没见过这个项目」的机器,也能装上吗?

verify:clone 把上面那四步按顺序、在一个全新的 clone 加一个全新的 DSH_HOME 上 走一遍,然后在那个 clone 里跑契约层;它不碰你自己的 $DSH_HOME。 这条命令是一次真的走查逼出来的:四步各自都对,缺的是它们之间的那个前提 (milestone-status.md §21)。

它现在也在 CI 里跑(milestone-status.md §28)。在那之前,「陌生人也能装上」是一条 只有人记得才会被验证的断言——写它的那一次量过,之后六个轮次的改动没有人再跑过它。 它在 CI 里既不需要 pnpm 也不需要网络:clone 的是 runner 上那份 checkout, 四步里有三步是纯 Node,而 dsh --profile web --dump-config 实测在没有 pnpm 的 PATH 上 照样成功(容器里跑过整条 job)。

CI 另有固定 Linux 运行时的真实检查,覆盖 Host 灰模/材质、Agent 附图及浏览器流程;渲染配置与摄影编辑使用独立 job 和时间预算。 Linux 专用安装器 deepblend/tools/install-ci-runtimes.mjs 提供 npm run ci:runtimes:install 与只读的 npm run ci:runtimes:check。 范围与证据保留见CI 说明;它不替代完整本地验收或在线美术评审。

预期:57 个套件、215 个文件全部通过。其中契约层(run.mjs,不需要 Blender)的当前文件结构与实际断言快照分别记录为 159 个文件 = 2134 项自计断言(34 个文件打印计数)+ 2222 个 node:test 用例(125 个文件)。 需要 Blender 的那几层把总断言数推到 1400 项以上(M4 那一次完整 run 记为 1400; M5 之后重测过一次,逐套件数字见 deepblend/docs/milestone-status.md §14)。

套件与文件数是源码的结构检查,断言与用例总数需要运行核对。 0.6.0 已发布:冻结实现 ee7d833 完整验收 39/39;最终发布和主线来源的产品包与配方字节相同,发布维护脚本、检查和文档差异单独核对。最终候选与主线 CI、干净构建、七包匿名读回、公开命令及隔离 DSH 下整轮三路安装均通过。0.6.1 也已发布:39 套流程分别有通过证据,原整轮 33/39 的磁盘失败与同源六项复验单独保留;最新单元文件全部通过,用例总数见上表。七包、公开 CLI、安装包及一次整轮公开三路读回通过。0.6.2 已完成一次整轮 39/39、对应主线构建与两次三项 CI、七包及整轮公开三路读回;不会在项目往返切换后继续旧预览请求。0.6.3 也已完成一次整轮 39/39、两次三项 CI、干净主线构建、七包及整轮公开三路读回;新配方平滑格栅弯折,旧版嵌入场景和尺寸修改保持兼容。0.6.4 已完成新冻结来源的一次整轮 39/39、候选和主线各三项 CI、干净主线构建、七包匿名完整归档及整轮公开三路读回;原 Live Session 测量路径错误与传播等待均保留,严格速度断言没有放宽。原始证据见每日发布记录;社区投稿已更新,等待上游审核。 套件数、文件数、工具数由 contract/documented-counts.test.mjs 直接从 run-all.sh、契约目录和 UI_TOOL_CARD_KEYS 里读出来比对——改了代码不改文档,它会红。而断言总数没有这层保护:只有真跑一遍才知道 它是多少,而一个「为了数其它套件而跑其它套件」的测试会让整套的成本翻倍。所以上面那两个数字是 快照,不是承诺;你机器上的数字以你自己的 run 为准。 2026-10-27 计数快照:自计套件在隔离且已安装当前 preset 的 DSH_HOME 中运行; 上述数量由当前源码的计数工具核对,不代表完整验收结果。0.23 候选 41eedff 的历史 155/155 运行及原始日志摘要见逐面 UV 实现记录。当前工作区的运行记录见独立创作执行记录。0.21 的完整 149 文件与 46 套发布验收另行记录,0.20 发布来源的完整契约为 146/146。 此前迭代的文档耦合失败及来源冻结失败保留在表面放置记录,不记作整轮通过。 最终冻结来源的完整验收和公开发布状态见对应 Release 的证据记录。 取这个快照的命令是 node deepblend/tools/count-assertions.mjs:它按 run.mjs 的规则发现文件、 跑那些会打印计数的,再把每份摘要加起来——它自己有一条测试(contract/assertion-counter.test.mjs), 因为它的规则写错过一次:\(s\)? 让「)」可选而「(」仍是必需的, 于是 store.test.mjs 的 47/47 checks passed 没被数进去,审计因此报出 1202(真值是 1249, D143)。

一个会咬人的计数口径:preset-source.test.mjs 的断言数取决于本机装没装 preset ——没装时它报 19 项,装了之后报 21 项。所以拿两个不同机器(或同一台机器装 preset 前后)的 总数直接相减,会凭空多出或少掉两项。上面那个总数是「已安装且与源码一致」preset 的隔离环境读数;同一份快照在未安装 preset 的环境下,preset-source.test.mjs 会少两项。 单跑某一层:

node deepblend/tests/run.mjs                                    # 单元 + 契约(不需要 Blender)
node deepblend/tests/blender-integration/probe.e2e.mjs          # M0 能力探测
node deepblend/tests/blender-integration/fixture.e2e.mjs        # M1 SceneSpec + revision 回放
node deepblend/tests/blender-integration/visual-loop.e2e.mjs    # M2 多视角 / 评分 / 修复 / handover
node deepblend/tests/blender-integration/render-job.e2e.mjs     # M3 重启 / 续渲 / 取消 / 交付
node deepblend/tests/e2e/complete-frame-delivery.e2e.mjs        # 已完整 PNG 帧的 FFmpeg 交付与取消;不启动 Blender
node deepblend/tests/composition/activation.e2e.mjs             # Host composition 是否真的激活
node deepblend/tests/composition/tool-plane.e2e.mjs             # M0 preset 工具面 + 降级
node deepblend/tests/composition/tool-plane-m1.e2e.mjs          # M1 的 7 个工具 + 无 checkpoint 的 revision 仍然可预览
node deepblend/tests/composition/tool-plane-m2.e2e.mjs          # M2 全部 10 个工具 + 图片回传
node deepblend/tests/composition/tool-plane-m3.e2e.mjs          # 全部 20 个工具 + 真实交付
node deepblend/tests/composition/hardening.e2e.mjs              # M5 安全加固:白名单/截止时间/输出上限/采样预算/工作区边界
node deepblend/tests/composition/concurrency.e2e.mjs            # M5 并发:两个会话打同一个 store,以及把它们隔开的 realm
node deepblend/tests/composition/approval.e2e.mjs               # M5 审批:阈值以上没有授权就一帧都不渲
node deepblend/tests/composition/assets.e2e.mjs                 # M5 资产:本地自动、网络需审批、以及两者之间的上限
node deepblend/tests/composition/ui-plane.e2e.mjs               # M4 UI 平面:闭集路由 + 座位表
node deepblend/tests/e2e/ui.e2e.mjs                             # M4 真实浏览器验收(自带 Host)

M3 的两个套件会真的渲 1080p、真的编码,所以它们是整个 run 里最慢的(约 5–10 分钟); M4 的 e2e/ui.e2e.mjs 会启动自己的 dsh web、开一个真实 Chrome,并真的渲一次预览、 起一次渲染再取消(约 1–2 分钟,全程在自己的临时 store 里,不碰开发者的数据)。

新增小交付检查 本地定向结果与范围
deepblend/tests/e2e/complete-frame-delivery.e2e.mjs 9/9:真实 FFmpeg/ffprobe 编码两张 256×192 PNG、取消自建编码进程并确认退出、保护旧帧与已发布视频;未启动 Blender 或浏览器。新增 CI 步骤仍待 Linux 实跑。

其中 contract/patch-resolution.test.mjs(116 项)值得单独知道:它全部来自在真实项目上 使用产品时暴露的缺陷——patch 结果没被解析完整、bare generator 产生 NaN、 主体与视角依赖了会被排序破坏的数组顺序。每条断言写的是用户当时看到的现象。

需要真实模型调用的一项,不在上面(它花 token,需要 credential store):

node deepblend/tests/e2e/visual-live.e2e.mjs      # 模型真的看图、识别缺陷、修好并提高分数

4. 生成演示项目

node deepblend/tools/create-demo-project.mjs

在真实的 .deepblend/projects/ 下创建 watch-commercial:r0001 = 产品转台场景, r0002 = 一次灯光/材质调整并带预览。幂等:已存在则报告状态并退出,不做任何修改。

生成器只铺到 r0002。对齐 SPEC.md:150 那条需求(15 秒、黑背景、产品环绕、表盘逐渐点亮、片尾品牌标)的是 另一条命令:

node deepblend/tools/apply-brief-content.mjs     # r0018 → r0023,走真实的 Host 事务

它把项目从 r0018 推到 r0023,每个 revision 的 operation-manifest.json 都完整记录了操作,可直接重放或 blender_revision_restore 回退;这一段的决策与被实测挡回来的地方见 architecture-decisions.md §5D(D42–D46)。

这两条命令各自的产物(r0001–r0002、r0018–r0023)是这里唯一能承诺的东西 ✓:.deepblend/projects/ 是 operator 状态而不是仓库内容 ✓,它现在的样子取决于你跑过哪些命令——所以这份文档写的是工具会做什么, 而不是你的 store 里现在有什么(早先这里写着一个「项目现在停在某个 revision」的句子,而 store 早就不是那样了: 一句关于 operator 状态的话,仓库没有任何办法让它保持为真——所以现在连那样一句话本身都被检查器挡着, 引文也不行,这条说明只能绕着说)。

5. 安装进 DSH profile

两个平面各装一次。两者都会在 profile 下次启动时才生效。

npm run plugin:check     # 只报告漂移:六个包链接 + dsh.profile.bundles 里那一行
npm run plugin:install   # 把 @deepblend/* 链接进 profiles/node_modules,并注册 Host Bundle

npm run presets:check    # 只报告漂移(本机没装过则报「未安装」,那不是漂移)
npm run presets:install  # 把 deepblend/presets/ 部署到 $DSH_HOME/.agent-presets/

有两条装法,而且它们不是等价的——选哪条取决于你是用它还是改它:

dsh plugin --profile web add <六个包的路径> npm run plugin:install
谁用 只想把它跑起来的用户 在本仓库里改代码的人
认证 DSH 自己的路径 自己写的,不经过 DSH
需要 pnpm 在 PATH 上(dsh plugin 不内置它) 只要 Node
dsh.profile.bundles 自动加 自动加
包落在哪 profiles/web/node_modules/@deepblend/ profiles/node_modules/@deepblend/
项目存储在哪 <DSH_HOME>/deepblend(产品默认) <repo>/.deepblend(写 operator layer 钉住)
--check 无 有

第二条存在的唯一理由是最后两行:本仓库的工具全都工作在 <repo>/.deepblend, 而部署默认读 <DSH_HOME>/deepblend——于是磁盘上明明有项目,面板里却是空列表。 实测见 deepblend/docs/probe-dsh-plugin-install.log(tools/dsh-plugin-install-probe.mjs 在临时 DSH_HOME 上跑完整条路):装完能服务,/deepblend/capabilities 返回 HTTP 200 / hostApiVersion 4,但 projectsRoot 落在那个临时的 DSH_HOME 下。

install-plugin.mjs 于是做三件事:把 @deepblend/* 链接进 $DSH_HOME/profiles/node_modules/,把 @deepblend/dsh-blender-bundle 加进 dsh.profile.bundles,以及推导出那一层 operator layer 把存储钉在本仓库上。 它不碰 DSH 安装目录,也不会覆盖别人写的 cordis.patch.yml(见下)。

这两步以前只写在文档里。2026-09-14 profile 被重装后它们都没了,代价不是理论上的: M4 的浏览器套件起了自己的 dsh web,而它链接真实 profile 的 node_modules—— bundle 解析不到,工作台就永远不出现,报错只有一句 never served /deepblend/capabilities。

存储放在哪里(--portable)

M5 之后 bundle 里没有任何路径:不配置时产品把项目存在 $DSH_HOME/deepblend (SPEC §17)。这对一次安装是对的,对一个 clone 是错的——本仓库的工具全部在 <repo>/.deepblend 上工作,产品若去读 ~/.dsh/deepblend,工作台会对着一个明明存在于 磁盘上的项目显示空列表。

所以 install-plugin.mjs 默认还会写一层 operator layer,把这个部署的存储钉在 <repo>/.deepblend;--portable 则跳过它(并删掉自己以前写的那个),让部署留在产品默认值上。 那一层是每次从 bundle patch 推导出来的,不是手抄的:patch 层的 config 是整体替换而不是 合并(实测,D74),所以覆盖必须重述全部键,而重述的唯一安全做法就是推导。 --check 会重新推导并比对,于是「bundle 改了但没传导到部署」会被报出来而不是被忽略。

重启后复核:

dsh --profile web --dump-config | grep -A6 deepblend    # 确认三行已组合;路径只应来自 operator layer
dsh web                                                 # 重启后生效

DeepBlend 开发模式 与 DeepBlend Studio 的 DeepBlend 工具清单为 20 个。 正式 preset 不包含通用 Shell、文件写入、Web 和 Creator Tool;开发模式另带调试工具。


M3 的核心机制

帧是事实来源,记录只是它的缓存

一份交付渲染实测 19.6–41.4 秒/帧,450 帧 = 3.4 小时。这样的任务必然会被打断。 所以「哪些帧已经渲好」的权威是磁盘上的帧文件,而不是 job 记录里的计数:

  • 记录里的 completedFrames 是缓存,永不覆盖磁盘;
  • 子进程 fsync 的 events.jsonl 是佐证,也不是权威;
  • 一段被 kill -9 截断的 PNG 存在,但它不是一帧——账本按 「PNG 签名 + IHDR 尺寸 + 尺寸下限 + IEND 结尾」判定,把它算进重渲集合。

要渲的集合因此是 missing + corrupt。这就是「可只渲缺失帧」这条验收的全部内容。

一次重启里,真正的证据是那个孤立进程

探针(tools/m3-restart-probe.mjs)实测:Host 被 SIGKILL 之后,它启动的 Blender 活着——它是 detached 进程组的组长,而且仍在往「恢复流程马上要描述的那个目录」里写。 所以恢复的顺序是证据而不是风格:先停孤儿,再读账本。

而「哪个 pid 是它」这件事只能由子进程自己写下来: ctx.subprocess.spawn 的 handle 实测没有 pid 字段。于是 bootstrap.py 在碰 bpy 之前 先写下 process.json,并且每次 attempt 带一个 token——Host 只接受 token 相同的身份文档。 (这条 token 是修补「续渲读回上一次 attempt 的死 pid」时加的,见 D58。)

交付清单要能让人不看磁盘就判断完整

output/delivery-manifest.json 同时记录声明与实测:视频路径、字节数、sha256, job 声称的帧数/时长/fps/分辨率,ffprobe -count_frames 实际量到的, 两者之间的全部不一致,以及 completeness 自判。不一致就以 ENCODE_VERIFY_FAILED 失败,并且什么都不发布——一份描述着不存在文件的清单,比没有清单更糟。


M2 的核心机制

模型确实看图,但分数不是它给的

一次视觉审查产出三件分开的东西:

谁产出 可否复现
score Host,从渲染像素的确定性测量算出 ✅ 纯函数,由契约与实际渲染验证
issues Host,每条带触发它的那个数字 ✅
reported 视觉模型,它说自己在图上看到了什么 ❌ 但每条都要过校验:视角必须真实存在、类别必须在闭集内、证据不能为空

把两者分开是 M2 最重要的一条设计:如果修复循环同时写它自己被评判的那个数字, 「评分提高」就变成关于模型的声明,而不是关于渲染的声明。

接触表作为 image block 随工具结果返回(字节经 attachments 归一化后只留引用), 所以工具结果里的图就是模型看到的那张图。

遮挡是定义性测量,不是启发式

相机 → 该像素的一条射线:这条视线上最近的东西是谁?
  主体最近   → 该像素属于主体
  其他角色最近 → 该像素被遮挡

前两版分别用「除我之外的一切」和「其他被跟踪实体」的掩码比较,都错得很安静: 前者让地板把每个主体测成 100% 遮挡,后者让「屏幕矩形重叠」冒充遮挡。 environment 标签的实体会被排除在跟踪之外——因为背景板不是遮挡物。

用技术测量和美术证据共同决定是否采纳

每轮提出一个 ScenePatch,候选经重新渲染、测量和前后图评审后再决定是否保留。 技术分不下降、没有新增严重问题且有明确美术改善时,即使技术分持平也可以采纳。 技术分提高仍需要有依据的美术不退步结论。证据不足、技术退步或美术退步时,条件恢复 此前版本;候选仍保留在历史中,不覆盖期间他人提交的修改。

每次循环固定基线的主要评审对象、文字目标和参考图片。停止条件包括技术与美术均通过、 迭代上限(默认 5)、同一问题连续未改善 2 次,以及固定评审输入失效。未通过时返回 handover:可继续工作的 revision、未解决问题、未采纳的尝试及下一步。 具体规则见作品评审。


M1 的核心机制

SceneSpec 是事实来源,.blend 是编译产物

项目的权威状态是 revisions/<id>/scene-spec.json。.blend 由 spec 编译而来,可重建、 可缺失(saveCheckpoint:false 的 revision 就没有)。这样修订历史才可 diff、可审计、 可幂等重放。

每次成功修改 = 一个不可变 revision

验证 patch → 解析幂等键 → 比对 baseRevision → 在内存中应用
  → JSON Schema + 语义校验 → 在 staging/ 中编译 Blender 场景 → 技术校验
  → 写 revision manifest → 一次 rename 原子发布 → 移动 current 指针 → 记录幂等结果

三条因此成为结构性质而非"记得要做的清理":

  • 失败不污染当前 revision —— 当前 revision 的目录从未被打开写入。已用递归内容哈希证明。
  • 不存在半提交 revision —— 没被 rename 的目录不是 revision。
  • 崩溃最多留下 staging —— 无人读取,下次事务清除。

幂等键省略时自动派生

{projectId, baseRevision, actor, stage, operations} 的哈希。于是无意的重试默认安全: 完全相同的重试返回首次结果;真正不同的 patch 正常应用;同样的操作针对更晚的 baseRevision 得到不同的键。要有意重复应用同一组操作,就显式给 key。

幂等查询早于冲突查询:谨慎的调用者重试时,第一次通常已经成功、项目已经前进—— 若先查冲突,回应会是 REVISION_CONFLICT,而调用者唯一的动作是重读重提, 恰好制造出幂等键要防止的那次重复提交。

失败永远是可分支的结果,不是堆栈

所有错误归入 BlenderErrorCode 稳定表;工具返回 ok:false + errorCode + message。 只有没有稳定码的意外才附带堆栈——那说明是 bug,此时堆栈才是唯一有用的信息。

完整决策记录与理由见 deepblend/docs/architecture-decisions.md(D11–D68), 运行时实测(含 M2 图片回传探针)见 deepblend/docs/runtime-audit.md §7.2, 工具契约见 deepblend/docs/tool-contracts.md。


三份手册

想做什么 看哪一份
装上它——从 clone 到「新建会话里能选到 DeepBlend Studio」,四步各有 --check,以及每一步不验证什么 deepblend/docs/install.md
用它——一次会话长什么样、每个工具的分工、成本模型、工作台六个页签、一个完整例子 deepblend/docs/usage.md
救它——渲染被 kill -9、半张帧、帧齐了没视频、改错想回退、宿主比包旧、项目列表是空的 deepblend/docs/recovery.md

上面「快速开始」是同一套命令的开发视角,三份手册是使用视角:手册只讲怎么用与 怎么判断,设计的理由留在 deepblend/docs/ 的其余文档里,两边不重复。

参考图片指南说明上传、版本绑定、证据引用与有限自动修正。

台灯首作(候选版本):在同一作品改稿,准备摄影与运动,交付三图、短片和可编辑工程;青釉杯练习保留固定视角和几何对比。

真人验收指南提供用自己的素材完成作品、外部投稿与他人复用、公开接口采用的实际执行步骤及空白记录,分别观察几何、材质、灯光和目标吻合。


安全

SPEC §15 列的每一条安全要求,都在 deepblend/docs/security.md 里查到它由哪一行代码负责、 被哪一条断言盯着,或者写着它没做——这份表由 contract/security-controls.test.mjs 盯住: SPEC 增删一条要求、表里指到的文件或片段消失、或者某条缺口没有在 milestone-status.md §7 里编号,都会变红。报告漏洞见根目录的 SECURITY.md。

许可与参与

本项目采用 MIT 许可证(见 LICENSE)。

想改点什么,先看 CONTRIBUTING.md——里面有三条不知道就会白干几小时的规则: npm run setup 不是可选的、改动只能落在三个平面中的一个、以及新增 import 之后不需要 改任何脚本(清单是从源码读出来的)。提交前那张清单同时是 .github/PULL_REQUEST_TEMPLATE.md。

报了 bug 请用 .github/ISSUE_TEMPLATE/bug_report.yml:它会要 Blender / DSH / 平台三个版本, 因为本仓库的每一次测量都是对着 pin 住的版本做的,缺了这三样,报告只能靠猜。 deepblend/docs/recovery.md 里已经写下的失败,先在那里找一眼。


当前状态与下一步

这个仓库的当前状态就是一条命令的输出,不是这一段文字:

bash deepblend/tests/run-all.sh      # 57 个套件;上面「快速开始」给了预期

逐里程碑的结论、每条验收的证据、以及已知的偏差与缺口(包括 SPEC §15 里没做到的那几条、 以及它们为什么没做)都在 deepblend/docs/milestone-status.md——那份文档是唯一记录, 这里不复述。理由是这套文档反复付过代价的那一条:同一件事写两处,就会有先烂的那一处。 这一节曾经把五个里程碑一起判为验收完成,紧接着又说最后一个里程碑应当另起一个会话—— 而那两句话在最后一个里程碑做完之后的第六个轮次里还挂在这里(§33)。

contract/docs-consistency.test.mjs 现在盯着这件事:README 里出现任何一种对里程碑状态的 断言(完成的判决、进行中的报告、下一步的计划)都会变红。这一节只写「去哪儿看」, 不写「现在到哪儿了」——前者永远是对的。

下一步是 SPEC 第二十节列的 M6 扩展项(Blender Live Bridge、Blender Add-on、远程 Worker、 对象存储、多 GPU、角色动画、复杂模拟、独立全屏工作台)。SPEC §21.1 明确写着 「不得在一次会话中横跨多个未完成里程碑」且「停止,不自动进入下一里程碑」, 所以它是一份待办列表,不是一件正在进行的事。

已经跑通过的东西(每一条都有对应的套件,不是叙述):一次真实的视觉闭环里模型独立指出 植入的遮挡而确定性评分器独立给出同一结论(blender-integration/visual-loop.e2e.mjs); 一次真实的交付里 Host 在渲染到第 6 帧时被 SIGKILL,新进程停掉孤儿渲染器、 从帧本身重建账本并补渲完剩下的 54 帧,最终编码出 1920×1080 的 output/final.mp4 (blender-integration/render-job.e2e.mjs,以及逐行的 probe-m3-delivery.log); 以及一个真实 Chrome 里点击完成「建项目 → 改场景 → 渲预览 → 起渲染 → 取消」、 刷新后从 Host 恢复同一个项目与 job(e2e/ui.e2e.mjs)。