DSH 到 Blender 的晶体学桥接插件。加载 CIF/POSCAR/LAMMPS 聚合物晶体,经隔离 Python 侧车处理周期性边界,在 Blender 4.2+ GUI 中实时协同编辑与出版级渲染球棍模型。
安装
# npm 包(预构建)
dsh plugin --profile web add dsh-plugin-polycrystal-bridge
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:TianyiMa96/dsh-polymcrystal-blender
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
dsh-plugin-polycrystal-bridge / PolyCrystal Blender bridge
DSH × Blender 聚合物晶体结构桥接插件(GPL-3.0-or-later)。加载 CIF/POSCAR/LAMMPS 聚合物晶体,经隔离 Python PBC 引擎处理周期性边界,推送到 Blender 4.2+ GUI(已在 5.3 上端到端验证)供人与 AI 实时协同编辑与出版级渲染。
src/— DSH 宿主插件(纯 ESM JS):环境探测、sidecar venv、127.0.0.1:39888网关、5 个模型工具。sidecar/— 隔离 Python 晶体学引擎(pymatgen/spglib/gemmi/ase/vesin):周期键图同调、PBC 聚类展开(默认pbc_cluster)、bundle.npz输出。extension/— Blender 4.2+ 扩展dsh_polycrystal_ext:反向拨号、N 面板、Geometry Nodes。skills/polymer-crystallography/— 指导模型的标准操作技能。scripts/— 扩展打包(pack_extension.py)与 headless 冒烟测试(test_blender_ext.py)。
预览
| 正交晶体视角 | 球棍近景 | 晶胞框 |
|---|---|---|
![]() |
![]() |
![]() |
特性(0.3.1)
- PBC 聚类展开(默认)。侧车按最小镜像成键、连通分量聚类、沿生成树展开(
polycrystal_core/polymer_unwrap.py),链/分子在写出 bundle 前就是连贯实体;ghost、boundary_pad、half_bond全为 0,渲染键长 ≤ 3.5 Å。periodic_clipped/chain_continuous/hkl_lamella作为显式回退。 - 超胞默认
[1,1,1]。输入 CIF 通常已是扩胞结构;需要沿链轴拉伸时显式传"auto"。 - 正交相机默认。
frame_camera对 evaluated 几何精确装箱(fill默认 0.92),支持azimuth绕世界 Z 偏航与a/b/c/chain_axis晶轴视角;perspective=true可切回透视。 - 球面精度默认 3。icosphere 320 面/球(162 顶点),近景轮廓无棱线。
- 单材质属性着色。一个
DSH_PolyCrystal_Surface材质,颜色/透明度/自发光/粗糙度/清漆由col/alpha/glow/rough/coat几何属性驱动,规避 Blender 5.xJoin Geometry的材质索引重排。 - 晶胞独立对象。
PolyCrystal_UnitCell只含 12 条晶胞边,设visible_shadow=False,不再在球面上投出环状阴影条。 - 默认观感。ghost 原子默认隐藏;自适应三点光 +
PolyCrystal_Spec小面光;竖向渐变世界;AgX Medium High Contrast;球棍Atom Scale 0.36/Bond Radius 0.15。 - 宿主工具。
polycrystal_env/load/modify/inspect/render,支持实时改样式、回读 N 面板状态、EEVEE/Cycles 出版级渲染。
改动历史见 CHANGELOG.md,架构与 5.x 兼容细节见 docs/DETAIL.md,开发命令见 AGENTS.md。
安装
- DSH 中安装本插件目录(Plugins > Add plugin)。
- 首轮对话模型会自动调用
polycrystal_env(action="doctor"),完成 sidecar.venv构建与 Blender 扩展安装;也可手动执行:
# 打包扩展(仅标准库,无需 Blender)
python scripts/pack_extension.py
# 安装到 Blender 用户扩展目录(非破坏式)
"C:/Program Files/Blender Foundation/Blender 5.3/blender.exe" --command extension install-file \
-r user_default -e extension/dist/dsh_polycrystal_ext.zip
# 可选:侧车可编辑安装
"<venv>/Scripts/python.exe" -m pip install -e sidecar
polycrystal_env(action="launch_gui")打开 Blender GUI,之后polycrystal_load加载结构。
快速上手
polycrystal_env(action="doctor")
polycrystal_load(file_path="PCLtrue.cif") # pbc_cluster + [1,1,1]
polycrystal_modify(style_mode=0, color_scheme=1, highlight_chain_ids=[0])
polycrystal_inspect(include_viewport_capture=true) # 回读人类在 N 面板的调整
polycrystal_render(resolution=[1600,1200], fill=0.92, orthographic_crystal_axis="c")
N 面板(N → PolyCrystal)提供同样的样式/着色/PBC 开关、AI 编辑暂停、相机与材质锁;AI 每轮修改前应先 polycrystal_inspect。
工具与参数
polycrystal_env
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
action |
enum | 必填 | doctor / setup_sidecar / install_blender_ext / launch_gui / list_sessions / claim_session |
session_id |
string | — | claim_session 时要认领的实例;省略则认领第一个活跃实例 |
polycrystal_load
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
file_path |
string | 必填 | .cif / POSCAR / CONTCAR / .xyz / .pdb / LAMMPS .data |
supercell |
int[3] | "auto" |
[1,1,1] |
显式扩胞;"auto" 沿链轴扩到至少 2 个周期 |
pbc_mode |
enum | pbc_cluster |
pbc_cluster / periodic_clipped / chain_continuous / hkl_lamella |
boundary_pad |
number[3] | [0.05,0.05,0.05] |
legacy 模式的边界填充比例 |
disorder_filter |
enum | default |
default / all / group_2 |
backend |
enum | native_gn |
native_gn / batoms / molecularnodes |
structure_id |
string | 自动 | 结构稳定 id(默认由文件+参数哈希派生) |
session_id |
string | — | 目标 Blender 实例 |
polycrystal_modify
| 参数 | 类型 | 说明 |
|---|---|---|
structure_id / session_id |
string | 目标结构与实例 |
style_mode |
int | 0 球棍 / 1 范德华 / 2 甘草 / 3 主链管+侧链棍 |
color_scheme |
int | 0 CPK / 1 链号 / 2 主链-侧链 / 3 无序组 |
hide_hydrogens |
bool | 隐藏氢及其键 |
show_backbone_tube |
bool | 主链平滑管 |
show_ghost_atoms |
bool | 显示周期边界 ghost 原子(默认关) |
show_half_bonds |
bool | 显示半键端帽(legacy 模式) |
show_unit_cell |
bool | 显示晶胞线框 |
atom_scale / bond_radius |
number | 原子缩放 / 键半径 |
highlight_chain_ids |
int[] | 高亮链号 |
hkl_plane |
number[4] | [h,k,l,shift] 晶面叠加 |
supercell |
int[3] | 新超胞,触发 sidecar 重建 |
pbc_mode |
enum | 新 PBC 模式,触发 sidecar 重建 |
respect_locks |
bool | 默认 true,遵守人类相机/材质锁 |
polycrystal_inspect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
include_viewport_capture |
bool | true |
附带视口 PNG 截图 |
session_id |
string | — | 目标实例 |
polycrystal_render
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
engine |
enum | BLENDER_EEVEE_NEXT |
BLENDER_EEVEE_NEXT / BLENDER_EEVEE / CYCLES(5.x 自动映射到 BLENDER_EEVEE) |
samples |
int | 64(E) / 128(C) | 采样数 |
resolution |
int[2] | [1600,1200] |
输出分辨率 |
orthographic_crystal_axis |
enum | current_user_view |
a / b / c / chain_axis / current_user_view |
transparent |
bool | false |
透明背景 |
refit |
bool | true |
分辨率变化后重新装箱(相机锁定时跳过) |
fill |
number | 0.92 |
主体到达画面边缘的比例(0.4–0.98) |
output_path |
string | staging/renders | PNG 输出路径 |
session_id |
string | — | 目标实例 |
测试与打包
# sidecar 单测(20 条)
<venv>/Scripts/python.exe -m pytest sidecar/tests -q
# 扩展 headless 冒烟(49 checks)
"C:/Program Files/Blender Foundation/Blender 5.3/blender.exe" -b --factory-startup \
--python-exit-code 1 -P scripts/test_blender_ext.py
# 打包扩展 zip -> extension/dist/dsh_polycrystal_ext.zip
python scripts/pack_extension.py
宿主插件本身不打包 Blender,也不向 Blender 内置 Python 安装任何包。
node_modules(宿主包内联)
src/tools/*.js 以官方模式 import { defineTool } from '@deepseek-ai/dsh-tools' 注册工具,但该包未发布到 npm(安装内版本 0.2.2-rc.3),profile 安装的插件无法从 DSH 安装目录解析它。因此本仓库自带 node_modules/(MIT 许可的 @deepseek-ai/{dsh-tools,cordis,schemastery,dsh-scope,dsh-llm,dsh-util-values,cosmokit,dsh-typert-protocol,dsh-util-crypto,dsh-brand,dsh-timeout,dsh-error} + zod,共约 6.7 MB,从本机 DSH 安装 app.asar 提取,与其版本精确匹配)。升级 DSH 后需重新提取同步。若日后 @deepseek-ai/dsh-tools 正式发布,可改为常规依赖。
致谢(Acknowledgments)
本项目站在以下开源项目的肩膀上,感谢这些库的作者与社区:
平台与宿主
- Blender — Blender Foundation,几何节点程序化建模与渲染宿主(GPL,本插件为其扩展)。
- DeepSeek Harness (DSH) — 插件宿主与 agent 工具框架;
@deepseek-ai/dsh-tools等运行时依赖(MIT)随仓库node_modules/内联分发。
科学计算核心(sidecar 直接依赖,均为宽松许可)
晶体学后端(可选依赖 crystal/fast extra)
- gemmi (MPL-2.0) — CIF/结构读取与对称操作。
- spglib (BSD-3) — 空间群识别。
- ASE (LGPL-2.1) — 周期结构与邻居列表回退。
- pymatgen (MIT) — 晶体结构分析与晶格操作。
- vesin (MPL-2.0) — 高性能周期邻居列表。
借鉴与参考
- batoms 与 Molecular Nodes — Blender 分子/结构可视化的先行者,本插件的可选渲染后端接口与其思路同源(见
interop_backends.py,当前仅作能力检测)。 - CPK 配色约定(Corey-Pauling-Koltun) — 元素标准着色方案。
- 单材质 + 几何属性着色的架构,是为规避 Blender 5.x
Join Geometry材质索引重排问题而独立设计;文中相关 5.x 兼容结论均为本仓库实测(见docs/DETAIL.md)。
约束与许可
- 不打包、不分发 Blender 本体;要求用户自装 Blender 4.2+(实测 5.3)。
- 不污染 Blender Python;重型科学计算全部在 DSH 侧隔离 venv。
- 专属网关
127.0.0.1:39888(可用DSH_POLYCRYSTAL_PORT覆盖),绝不监听 9876。 - 禁 AGPL 代码;本仓库为 GPL-3.0-or-later。
链接
同类插件
Tencent/WeKnora#dsh-weknora★ 37546
把 WeKnora 知识库接入 dsh 的四个只读工具:列出知识库、混合检索原文片段、按顺序还原单篇文档,以及直接取用 WeKnora 自己带引用的 RAG 或 ReAct agent 回答(含可续聊的 session id)。
DayuanJiang/next-ai-draw-io#dsh-plugin★ 36997
dsh 的 draw.io 绘图插件:通过 next-ai-drawio MCP 服务器作图,点回复里的链接在右侧栏打开实时预览,可以手动修改图,AI 的每次修改都是可以恢复的版本。需 Node.js 18+,首次使用由 npx 下载 MCP 服务器。
superdesigndev/treg★ 8164
给 Agent 的工具目录:按「要做的事」检索约 2,600 个外部接口(SEO 与 SERP、外链、社交、人物与公司信息补全、广告库、抓取),查看参数与单次调用价格后直接调用,凭据由服务端注入。附带技能,MCP 行在未设置 TREG_TOKEN 前保持禁用。
T-Auto/dsh-ops★ 5864
为 Windows 的 DSH 提供 bash、PowerShell 7 及 Rust 高性能工具,减少 token 消耗。
sixtysevenlf/dsh-blender-plugin★ 2147
让 DSH agent 通过直连 TCP 通道驱动本地 Blender,提供 15 个工具:视口帧、自定义视角渲染、Python 执行、无头与作业卸载、事务回滚,以及 34 个 family / 228 个 op 的规划层。
helloHub1212/dsh-windows-mcp★ 1456
通过官方 MCP 客户端桥接层把 CursorTouch/Windows-MCP 桌面自动化服务器接入 DSH,把截屏、UI 树快照、鼠标键盘输入、剪贴板、进程与注册表等工具注册成 mcp__windows__* 供模型调用,并附带 windows_mcp_doctor 诊断工具;Computer Use 默认关闭,需在插件面板里打开。



社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。