本工具 **不建立 Houdini TCP 连接**，直接在 bridge 进程内加载并查询
BEST_PRACTICES.md。recipe 是 advisory，不替代 verify_hou_api /
get_houdini_help，也不替代目标 Houdini 版本的 live verification。

参数说明：
- query: 可选，对 problem/symptom/fix/category/source 做 casefold
  子串匹配。
- category: 可选，精确匹配 category 字段。
- id: 可选，精确匹配 recipe id（如 "BP-001"）。
多个参数组合为 AND。

返回统一 envelope：status（success/error）、practices（实际返回列表）、
total_indexed（过滤前索引数）、matched_count（过滤命中数）、
returned_count（cap 后实际返回数，恒等于 len(practices)）、truncated
（matched > returned 时为 true）。error 时 error={code,message,details}，
且 practices 为空、三个 count 为 0。响应整体过 apply_response_cap。

本工具 **不建立 Houdini TCP 连接**，直接在 bridge 进程内加载并查询
本地 RAG 索引（``index.v1.json``）。与 ``get_houdini_help`` /
``verify_hou_api`` 互补：那两个面向单条 API / 节点的结构化查询
（local-help-first + 在线回退），本工具面向「跨文档主题检索」，
如「怎么搭 pyro 网络」「karma 采样设置」。

参数说明：
- query: 检索文本；tokenizer 会保留 hou.xxx() API 与 /obj/geo1 节点
  路径整体语义，下划线复合词同时按完整与拆分匹配。
- limit: 可选，返回条目上限，clamp 到 [1, 50]，默认 10。

返回统一 envelope：status（success/error）、query、limit、matched
（response cap 前所有 BM25 正分文档总数）、returned（cap 后实际
results 长度，恒等于 len(results)）、results（每条含 path / title /
score / 围绕首个命中位置的 snippet）。索引缺失返回
rag_index_missing；损坏 / 不兼容返回 rag_index_unavailable；命中
stale 缓存时附 _index_warning。响应整体过 apply_response_cap。

本工具 **不建立 Houdini TCP 连接**，``path`` 只与已校验索引中的规范
化 POSIX 相对 path 做精确匹配，全文从 JSON 内嵌 content 返回，
**绝不拼接源文件系统路径或回读索引外文件**（含 ``..`` 遍历串）。
与 ``get_houdini_help`` / ``verify_hou_api`` 互补：那两个面向在线
结构化字段查询，本工具面向已索引离线文档的整篇读取。

参数说明：
- path: 索引中文档的 POSIX 相对路径（如 ``nodes/sop/box.html``），
  可先用 search_docs 取得。

返回统一 envelope：status（success/error）、path、title、length、
content（全文，过 apply_response_cap）、returned（1 命中 / 0 未命中）。
path 不存在或非法返回 rag_doc_not_found；索引缺失 / 损坏分别返回
rag_index_missing / rag_index_unavailable。

本工具 **不建立 Houdini TCP 连接、不 import hou**，直接在 bridge 进程
内按真实 legacy cpio/odc entry 流式读取 archive（magic 070707、76 字节
header），best-effort 提取节点 type、def comment/position/connections、
可选 parm 序列化原始值、postit 文本与 netbox label，并对不可信输入施加
file/entry/section/total/node 五类硬限额（``max_depth`` 仅裁输出树）。

与 ``serialize_scene`` / ``get_node_info`` 互补：那两个面向**在线** Houdini
连接的实时节点树查询；本工具面向**离线**文件审计（如查看一个 .hip 里
有哪些节点/连线，而不必启动 Houdini）。

参数说明：
- file_path: ``.hip``/``.hiplc``/``.hipnc`` 文件路径；其他扩展名返回
  ``unsupported_extension``。
- include_params: 可选，True 时每节点附 ``parameters``（archive 中序列化
  的原始 parm 文本，**不求值、不比较默认、不保证动画/表达式完整**）。
- max_depth: 可选，输出 ``structure`` 树深度，clamp 到 ``[1,64]``；
  flat ``nodes``/``connections`` 不受影响。

返回统一 envelope：``status``（success/error）、``file_path``、
``save_version``（从 ``.variables`` 的 ``_HIP_SAVEVERSION`` 明确提取，
不可得为 null）、``nodes``（flat）、``connections``、``postits``、
``netboxes``、``structure``（depth-clipped 树）、``metadata``（含
complete_entries/bytes_consumed/trailer_seen/duplicate_entries/
skipped_sections/limits）。error 形如
``error:{code,message,details}`` 并尽可能附 partial（trailer_seen=false，
不含截断 body）。error code：unsupported_extension / invalid_archive /
corrupt_archive / truncated_archive / resource_limit_exceeded /
hip_not_found / hip_io_error。success 与 error-partial 均**过**
``apply_response_cap``。

触发时机：agent 在 Houdini 操作遇到报错、重试第 2 次仍未解决、或遇到
不认识的 API/参数时，先调用本工具检索既往经验；命中后用 read_lesson
拉全文。本工具是 advisory，不替代 verify_hou_api / get_houdini_help /
get_best_practices，也不替代目标 Houdini 版本的 live verification。

主动沉淀工作流（advisory 行为注解，非强制协议）：用户完成 HDA / 节点流
/ VEX 工作流后说"沉淀这些知识"时，agent SHALL 依次：get_selection 定位
→ capture_workflow_snapshot 取快照 → 组织为 recipe（用法文档，走
save_recipe）或 lesson（经验，走 save_lesson）→ 写入后向用户汇报写入的
id / root / 状态。

加深与研究方法论（advisory 引导，非强制）：用户要求"加深 / 改造 / 优化"
既有沉淀时，agent SHALL 先调用本工具定位既有 recipe/lesson id，再用
capture_workflow_snapshot（自制 HDA 带 include_hda_internals=True）
重新研究，最后 save_recipe(recipe_id=...) 原地更新，**不得新增重复
知识**。沉淀目标是原理 / 设计意图 / 为什么（方法论优先），参数按需收录
（用户显式要求除外）；正文索引用资产级标识（type_full / hda 资产全名 +
版本），实例名仅辅助，**禁止本机路径入正文**（HDA 库路径 / hip 完整
路径，团队知识库跨机器误导源）。

参数说明：
- query: 检索文本（可为空串 → 按新鲜度/priority 基线浏览）。
- category / severity: 精确过滤（severity: low/medium/high/critical）。
- node_type: doc 文本子串过滤（如 /obj/geo1、sop/attribwrangle）。
- houdini_version: affected_versions 子串过滤（如 H21.0）。
- scope: 可选 root 名（如 "personal"）或 "all"；缺省检索全部 root。

返回统一 envelope：status/query/top_k/matched/returned_count/truncated/
results（紧凑摘要，含 source_root）/draft_suggestions；unavailable root
附 _warning。错误为 status=error + error={code,message,details}
（未知 scope → ls_unknown_root）。整体过 apply_response_cap。

触发时机：agent 在解决一个 Houdini 问题后主动沉淀经验。写入个人库
draft 状态，不立即进入检索索引；同 symptom 再次出现会自动累积
strength（只累积不覆盖）。团队 root 默认只读，写入返回
root_not_writable。沉淀的是 advisory 经验，不替代 verify_hou_api /
get_houdini_help / get_best_practices 与目标 Houdini 版本 live
verification。

主动沉淀工作流（advisory 行为注解，非强制协议）：用户完成 HDA / 节点流
/ VEX 工作流后说"沉淀这些知识"时，agent SHALL 依次：get_selection 定位
→ capture_workflow_snapshot 取快照 → 组织为 recipe（用法文档，走
save_recipe）或 lesson（经验，走本工具）→ 写入后向用户汇报写入的
id / root / 状态。

加深与研究方法论（advisory 引导，非强制）：用户要求"加深 / 改造 / 优化"
既有沉淀时，agent SHALL 先 search_lessons 定位既有 id，再用
capture_workflow_snapshot（自制 HDA 带 include_hda_internals=True）
重新研究，最后 save_recipe(recipe_id=...) 原地更新（recipe 通道），
**不得新增重复知识**。沉淀目标是原理 / 设计意图 / 为什么（方法论优先），
参数按需收录（用户显式要求除外）；正文索引用资产级标识（type_full /
hda 资产全名 + 版本），实例名仅辅助，**禁止本机路径入正文**。

参数说明：
- problem / symptom / fix / category / affected_versions: 必填。
- severity: 必填，取值 low / medium / high / critical。
- verified_versions: 可选；缺省 "unknown"。
- root: 可选 root 名；缺省 personal（唯一可写 root）。

返回：新 lesson → {status:success, lesson_id, lesson_status:"draft",
strength:1, root}；同 fingerprint 已存在 → strength 递增且内容保留。
错误为 status=error + error={code,message,details}（非法 severity →
ls_write_error 并列出合法值；只读团队 root → root_not_writable）。

触发时机：search_lessons 命中后按需拉全文；draft 也可读。本工具只读
advisory 内容，不替代 verify_hou_api / get_houdini_help /
get_best_practices，也不替代目标 Houdini 版本的 live verification。

参数说明：
- id: lesson id（如 L-20260802-001），由 search_lessons 返回。

返回：{status:success, id, root, lesson_status, markdown}（markdown 为
规范格式，可 round-trip）；id 不存在 → status=error + error.code=
ls_lesson_not_found（提示先 search_lessons 获取 id）。整体过
apply_response_cap。

触发时机：需要了解知识库状态、确认写入是否生效或排查检索范围时调用。
查看各 root 状态（ok/unconfigured/unavailable）与 lessons/inbox/
recipes 计数；unconfigured 静默、unavailable 会带 _warning。本工具是
只读状态查询，不替代 verify_hou_api / get_houdini_help /
get_best_practices，也不替代目标 Houdini 版本的 live verification。

参数说明：
- scope: 可选 root 名；缺省/"all" 报告全部 root。

返回：{status:success, roots:[{name, state, path, priority, writable,
lesson_count, draft_count, published_count, inbox_count,
recipes_count}]}；未知 scope → status=error + error.code=
ls_unknown_root。整体过 apply_response_cap。

触发时机（advisory）：用户完成 HDA / 节点流 / VEX 工作流后说"沉淀这些
知识"时，agent 先调用 get_selection 定位，再调本工具取快照，组织为
recipe（用法文档，走 save_recipe）或 lesson（经验，走 save_lesson）。
本工具是 advisory，不替代 verify_hou_api / get_houdini_help /
get_best_practices，也不替代目标 Houdini 版本的 live verification。

参数说明：
- node_path: 可选；省略时取当前节点选择（空选择返回 no_selection
  结构化错误，不静默回退）；指定时捕获以该节点为根的闭包子网络。
- include_vex: 可选，默认 True；包含 Attribute Wrangle 的 VEX snippet。
- max_nodes: 可选，默认 50；闭包节点硬上限，超限截断并标记 truncated。
- include_hda_internals: 可选，默认 False；True 时满足展开判定的节点
  内部子网并入同一 BFS 遍历（受同一 max_nodes 预算与 truncated
  语义）。展开判定（H21 实测收敛）：children() 非空 且（用户资产
  ——库文件非 $HFS otls；或官方 HDA 带 Editable Nodes 声明——
  definition().hasSection("EditableNodes")，如 rbdbulletsolver1
  的 dopnet/forces 子网络；或非 HDA 普通容器 subnet/geo）。
  官方无声明的封装 HDA（rbdconstraintproperties / rbdconfigure
  等）默认**不拆解**；官方空壳节点（attribwrangle 等 children
  恒空）不展开。**不能用 isEditable() 判定**（实例锁定态
  isEditable False 但 children 完全可读，且大 HDA 上定义比较可能
  极慢）。研究用户自制 HDA 原理（内部 VEX / 约束 / 子网结构）时
  启用，并可视需要上调 max_nodes（大资产内部节点多，如 500）。

返回结构：{status:success, root, node_count, truncated, hip_file,
nodes, sticky_notes, connections}，超限截断时 truncated=true；API
降级附 _warning。节点表每项含资产级标识 type_full（nameWithCategory，
API 缺失降级 type）与 is_hda（**用户数字资产实例**：definition() 非 None
且库文件非 $HFS/houdini/otls 内建库——H21 上 attribwrangle 等 HDA 化
内建类型也有 definition，纯 definition 判定会误标），hda 字段
为 {type_name, version(可选), definition_source: embedded|external}，
**绝不输出 library_path 或任何本机路径**（跨机器复现误导源）；顶层
hip_file 只取 basename（隐私安全）。快照只含节点表（path/name/type/
type_full/is_hda/comment/非默认参数/vex/hda/errors/warnings）+
sticky note + 连线，**不含几何数据**，readOnly 不修改场景，纯规则
读取**不调用 LLM / 嵌入模型**。错误为 status=error + error={code,
message,details}（no_selection / invalid_node_path /
selection_read_failed / capture_connection_error）。整体过
apply_response_cap。

方法论沉淀协议（advisory，非强制）：沉淀目标是工作流的**原理 / 设计
意图 / 为什么这么搭**，不是节点名与参数的复制粘贴；参数仅在用户要求
或直接影响复现时收录。正文索引用 type_full / hda 资产标识，实例名仅
辅助；**禁止本机路径入正文**（HDA 库路径 / hip 完整路径，团队知识库
跨机器误导源），资产只用全名 + 版本索引。自制 HDA 先
include_hda_internals=True 研究内部原理再组织为 recipe。

触发时机（advisory）：用户完成工作流后说"沉淀这些知识"时，agent 先用
get_selection 定位，再调 capture_workflow_snapshot 取快照；用法/流程
文档（"怎么用这个 HDA""这个网络怎么搭"）走本工具 save_recipe（写入即被
search_lessons 检索，无 draft 门槛），错误经验走 save_lesson（draft
门槛 + 指纹累积）。本工具是 advisory，不替代 verify_hou_api /
get_houdini_help / get_best_practices，也不替代目标 Houdini 版本的
live verification。

参数说明：
- title / problem / symptom / fix / category / severity /
  affected_versions: 必填；title 渲染为块上方 ``> title`` 注释行。
- severity: 必填，recipes severity 合法取值 low / medium / high
  （3 值，与 lesson 的 4 值不同）。
- verified_versions: 可选；缺省 "unknown"。
- recipe_id: 可选；引用**既有** ``### BP-NNN`` 块 id（格式
  ``BP-\d{3}``，非自定义新 id）。提供时**原地替换**该块 9 字段、
  不新增块（首块 ``> title`` 行同步更新），响应 action=updated；
  未提供时维持自增追加，响应 action=created。
- root: 可选 root 名；缺省 personal（唯一默认可写 root）。

返回：{status:success, recipe_id, root, severity, source,
immediately_searchable:true, action:created|updated}；recipe_id 为
BP-NNN 自动生成（扫描既有块最大序号 + 1），**不接受自定义 id**；团队
root 写入 source 自动附 ``@<用户名>``（系统标注）。错误为 status=error
+ error={code,message,details}（非法 severity → ls_write_error 并列出
合法值；recipe_id 格式非法 → ls_write_error；引用不存在的 id →
ls_recipe_not_found 且 message 附既有 id 列表；只读团队 root →
root_not_writable；未知/不可用 root → ls_unknown_root）。整体过
apply_response_cap。

方法论沉淀协议（advisory，非强制）：
- 沉淀内容是工作流的**原理 / 设计意图 / 方法论**（为什么这么搭），
  不是节点名与参数的复制粘贴；参数仅在用户要求或直接影响复现时收录。
- 正文索引用资产级标识（capture_workflow_snapshot 的 type_full / hda
  资产全名 + 版本），实例名仅辅助。
- **禁止本机路径入正文**：不写 HDA 库路径 / hip 完整路径（团队知识库
  跨机器误导源）。
- 改造 / 加深既有知识时先 search_lessons 定位既有 id，再传 recipe_id
  **原地更新**，**不得新增一条重复知识**。

Execute arbitrary Python code in Houdini's environment. LAST RESORT:
prefer the dedicated tools (connect_nodes, set_parameters, create_wrangle,
get_geometry_info, ...) — they validate input, report structured errors
and are undoable as a single step. Use this only for operations no
dedicated tool covers.

Args:
    code: Python source to exec inside Houdini.
    policy: "read-only" / "normal" / "privileged" (PR 4 safety policy).
    allow_dangerous: explicit per-call dangerous-code override (privileged only).
    allow_heavy_geometry: explicit per-call heavy-geometry override.
    capture_diff: when True, server snapshots scene state before & after.

Returns status, any stdout/stderr, and an optional audit block.

The Houdini-side server caches the most recent serialize_scene_state pair;
this tool fetches and pretty-prints the diff so the agent can verify what
a privileged execution actually changed in the scene.

file_path 省略（None/""）时保存到当前 hip 路径（hou.hipFile.path()）；
会话 untitled（无 hip 路径）时返回错误而非弹出模态保存对话框。
Returns JSON like {"saved": true, "file_path": "..."} or an error string.

Server-side also calls cmn.invalidate_all_caches() so downstream caches
(NodeTypeCache coming in PR 6) reset on scene switch.

默认禁用：未设置 HOUDINI_MCP_ALLOW_NEW_SCENE（或非 truthy）时返回错误，
禁止 AI 自主清空用户场景；需显式放行时由用户设置
HOUDINI_MCP_ALLOW_NEW_SCENE=1。
Server-side also calls cmn.invalidate_all_caches().

只读操作，AI 用于场景结构对比 / 文档生成。
include_params=False 时每节点只含 path/type/name/children；
True 时增加 parameters dict。

PR 6: relays to server-side disc.list_node_types, which populates the
NodeTypeCache on first call and reuses it across invocations.

PR 6: relays to server-side disc.list_children.

PR 6: relays to server-side disc.find_nodes.

action="stats"     -> return cache hits/misses/size/last_populated_at
action="invalidate"-> clear all registered caches (calls
                      cmn.invalidate_all_caches under the hood)
action="warmup"    -> pre-populate the NodeTypeCache

PR 6: relays to server-side disc.manage_cache. ValueError on unknown
action surfaces as an error dict with origin="houdini".

Wire one node's output into another node's input. Both nodes must live in
the same network. input_index selects which input of to_path to connect
(0-based); output_index selects which output of from_path to use.

Set one or more parameters on a node in a single undoable call.
Values: scalar for single parms (e.g. {"scale": 2.0}), a list for parm
tuples (e.g. {"t": [0, 1, 0]}), and menu token or label strings for menu
parms. Unknown names fail per-parameter with did-you-mean suggestions —
check the "failed" list in the result. Use get_parameter_schema first if
unsure of names, types or valid menu values.

Describe a node's parameters: names, labels, types, tuple sizes, current
values, defaults, numeric ranges and menu options. Use this to discover
valid parameter names/values before calling set_parameters. Filter with a
glob pattern (e.g. "*scale*", matched against name and label); paginate
with offset/limit when a node has many parameters.

从 root_path 出发，单次调用 node.allSubChildren() 收集所有后代节点，
返回 errors 与 warnings 双列表。include_warnings 默认 True（PR 11 行为）；
max_warnings 限制警告条目数（超过返 _warnings_truncated 标记）；
max_errors 限制错误条目数（None 表示不限）。适合场景构建完成后做
一次性体检，比逐节点 cook_node 更快。

返回 SOP 节点的 point / primitive / vertex 计数、bbox 6 元、attributes /
groups 列表（带 name/type/size），以及前 sample_size 个点的属性采样。
point_count 超过 max_points_for_full 时自动降级 — 跳过 sample_points 与
详细 attributes/groups，避免大几何撑爆 MCP。比 get_geometry_info 更轻，
比 get_geometry_data 更结构化。适用于“先看看节点生成了什么规模的几何”。

Create an Attribute Wrangle SOP with the given VEX snippet, optionally
wiring input_node into its first input. run_over: points, primitives,
vertices, detail or numbers. The node is cooked immediately and the
result includes a 'validation' report — check it for VEX compile errors
before building on top. On invalid input the node is removed, never left
half-configured.

Summarize a node's geometry: point/primitive/vertex counts, bounding box,
attribute listings per class, and group names. Accepts a SOP path or a
geometry container (its display SOP is used). Use this to verify what a
network actually produced instead of judging from a render.

Read actual attribute values from geometry, paginated (limit capped at
500 — use start to page through large geometry). element: 'points' or
'primitives'. attributes: names to read (default: P for points); call
get_geometry_info first to see what exists.

IMPORTANT (fork-render-policy-redirect-and-consent):
    在用户机 H21 缺 OGL 3.3 环境下，本工具的 opengl renderer 已被 fork
    强制 redirect 到 ``capture_pane_screenshot(SceneViewer)``（不再
    触发 opengl output node 链路，避免 Houdini 主线程死锁）；karma_cpu /
    karma_xpu renderer 需带 ``consent_token`` 重调，token 在首次调用返
    回的 ``_interrupt`` 字段中获得。详见 ``_render_policy.py``。

Render a single view inside Houdini and return a structured result dict.

Returns a dict (carrying renderer / image_path / size_bytes / etc.)
instead of a string. Pydantic-typed MCP output models reject dicts
when the return annotation is `str`; this tool is the one that broke
live with `1 validation error for render_single_viewOutput / result
Input should be a valid string [type=string_type, input_type=dict]`.
Server-side always returns a dict; we forward it verbatim and only
fall back to an error envelope on exception.

IMPORTANT (fork-render-policy-redirect-and-consent):
    在用户机 H21 缺 OGL 3.3 环境下，本工具的 opengl renderer 已被 fork
    强制 redirect 到 ``capture_pane_screenshot(SceneViewer)``；karma_cpu
    / karma_xpu 需带 ``consent_token`` 重调。详见 ``_render_policy.py``。

Render 4 canonical views from Houdini and return a structured result dict.

Returns a dict (4 views × {image_path, size_bytes, ...}) instead of a
string. See render_single_view docstring for the dict-vs-str Pydantic
background. The legacy bridge command name is `render_quad_view`
(singular) — kept for backward compatibility with the server-side
handler dictionary in opera-houdini-mcp/server.py.

IMPORTANT (fork-render-policy-redirect-and-consent):
    在用户机 H21 缺 OGL 3.3 环境下，本工具的 opengl renderer 已被 fork
    强制 redirect 到 ``capture_pane_screenshot(SceneViewer)``；karma_cpu
    / karma_xpu 需带 ``consent_token`` 重调。详见 ``_render_policy.py``。

Render from a specific camera path in the Houdini scene.

Returns a structured dict (renderer / image_path / size_bytes) instead
of a string. See render_single_view docstring for the dict-vs-str
Pydantic background.

HScript 是 Houdini 的传统脚本语言（与 Python/HScript 两套接口并存），
适合执行 `ls`、`cd`、`opset` 等内建命令。调用结果以 stdout / stderr
形式返回。

参数说明：
- code: HScript 命令字符串（如 "cd /obj; ls"）。空字符串 / 纯空白
  会被服务端拒绝并返回错误。

返回字符串包含 stdout / stderr 两段；连接或服务端出错时返回
"Error (...): ..." 形式的提示。

参数说明：
- node_path: 目标节点路径。
- new_order: list of input_index，按新顺序排列（如 [2, 0, 1] 表示把
  原 input 2 移到 input 0，依此类推）。空 list 表示全部断开。
- order: 旧版别名；若同时传 new_order 与 order，以 new_order 为准。

返回 dict 包含 path / old_order / new_order / success 四项；
节点不存在时函数会抛 ValueError，bridge 不会再以 success:True 形式
静默吞错。

参数说明：
- parent_path: 父节点路径（PR 9 推荐命名）。
- parent: 旧版别名；若同时传 parent_path 与 parent，以 parent_path 为准。
- horizontal_spacing: 水平间距（Houdini units），缺省 2.0。
- vertical_spacing: 垂直间距，缺省 1.5。
- direction: "horizontal"（默认）或 "vertical"。

返回 dict 包含 parent_path / children_count / direction / spacing
四项。后向兼容：现有调用 layout_children(ctx, parent) 仍 work。

参数说明：
- node_path: 节点路径。
- x: x 坐标（Houdini units）。
- y: y 坐标。

返回 dict 包含 path / position / success 三项；
节点不存在时函数会抛 ValueError。

参数说明：
- node_path: 节点路径。
- r, g, b: 颜色分量；负值 clamp 为 0.0，>1 值 clamp 为 1.0。

返回 dict 包含 path / color / success 三项；
节点不存在时函数会抛 ValueError。

参数说明：
- parent_path: 父节点路径。
- name: 可选，box 名；缺省时由 Houdini 自动命名。
- node_paths: 可选，要包含到此 box 的节点路径列表；
  不存在的节点静默跳过，不抛错。

返回 dict 包含 path / name / nodes_in_box 三项；
父节点不存在时函数会抛 ValueError。

参数说明：
- node_path: 目标节点路径。
- include_errors: 可选，是否包含 errors / warnings 字段，默认 True。
- force_cook: 可选，读取前是否调 node.cook(force=True)，默认 False。
- include_input_details: 可选，是否包含每个 input 的详细连接
  （用 node.inputConnectors() 一次性取），默认 False。
- compact: 可选，是否仅返精简字段 path/type/counts（不含 parameters /
  errors / warnings），默认 False。

返回 dict：compact=True 时仅含 path / type / children_count / input_count
/ output_count 五项；否则包含完整字段（详见 _node_info.get_node_info）。
节点不存在时函数会抛 ValueError，bridge 透传 error envelope 不静默吞错。

pane_type_name 必须是 hou.paneTabType 的合法属性名。save_path 为 None
时不落盘，size_bytes 改用 QBuffer 估算。fit_contents=True 时先按
pane 类型调用 homeAll() / curViewport().home() 把可视范围对齐。
响应走 apply_response_cap。无 PySide 环境返回 _warning dict。

返回 {desktop, pane_type, name, is_current} 四元组列表；is_current
标记该 desktop 当前激活的 pane。只读操作，响应过 apply_response_cap。

pane_types 是 pane 类型名列表；返回与 pane_types 等长的 result 列表，
每条 {pane_type, save_path, success, error} 独立报告。任意一种 pane
抛异常不影响其他 pane。响应过 apply_response_cap。

node_path 必须存在；fit_contents=True 时截图前调用 homeAll() 把可视
范围对齐到节点子树。save_path=None 时不落盘（size_bytes 改用 QBuffer
估算）。响应过 apply_response_cap。

views=None 时严格按 top、front、right 顺序采集；传入 views 时保留调用方
顺序且不允许重复或未知视图。每张图由 Houdini 内部 flipbook 生成并校验
PNG IHDR，返回结构化的逐视图结果与 state_restored 状态。

返回 dict 字段：frame / time / fps / frame_range /
playback_range / frame_increment；任一 hou 调用抛异常时降级为
status=error 而非向调用方抛异常。仅读取时间线状态，不修改场
景或参数（READ_ONLY_COMMANDS）。响应整体过 server 端
``apply_response_cap`` 截断大 payload（虽然规模小，仍保持
defense-in-depth）。

``frame`` 接受 int / float；拒绝 bool / NaN / ±inf / 非数值；
hou 接受 float 值并保留 sub-frame。任何 hou 异常降级为 error
dict。该命令在 NO_UNDO_COMMANDS 中，batch dispatcher 会在调
用前自动关闭当前 undo segment，确保不进入 ``hou.undos.group``。

``start`` / ``end`` 必须为有限浮点且 ``start <= end``；end
可 sub-frame。错误（如 start > end）返回 status=error 不写；
成功时由 hou.playbar.setFrameRange 持久化。

校验同 ``set_frame_range``；调 ``hou.playbar.setPlaybackRange``。

``path`` / ``parameter`` 必为非空字符串；``frame`` / ``value``
必须为有限浮点。value 创建 ``hou.Keyframe(float(value))`` 并
``keyframe.setFrame(float(frame))`` 后 ``parm.setKeyframe``。
字符串参数 / NaN / inf 等返回 status=error 不写。

``keyframes`` 为 list，每项 dict 至少含 ``path`` /
``parameter`` / ``frame`` / ``value``；任一项无效则**整调
用**失败、零写入（在 server 上层预校验拒绝）。全部有效时
在单个 ``hou.undos.group`` 内逐项写入并返回 ``set_count`` /
``requested``。错误列表同样受 server 端 ``apply_response_cap``
截断保护。

``frame`` 必须为有限浮点（删除 sub-frame 精确点）。目标帧
不存在返回 status=error（"no keyframe found at frame ..."），
不写。实际删除后再次读取 keyframes 列表验证已消失。

返回 list 中每项 ``{"frame": float, "value": float}``，不
做 ``int()`` 截断；空关键帧列表返回 ``keyframes=[]``。本
工具仅查询状态（READ_ONLY_COMMANDS），不会修改场景或参数。

``action`` 取值：
- ``play`` / ``reverse`` / ``stop``：直接调 SideFX HOM 同名方法。
- ``step_forward`` / ``step_backward``：仅通过
  ``hou.setFrame(current ± hou.playbar.frameIncrement())``
  路径并 clamp 到当前 playback range 闭区间，**不引入其
  他 step helper**（increment 非有限正数 / range 不可用
  → error 且 **不**调 hou.setFrame）。
- ``goto_start`` / ``goto_end``：直接设 playback range 端点。

整个 action 集在 NO_UNDO_COMMANDS 中，batch dispatcher 在
该命令前关闭 undo segment，保证不进入 ``hou.undos.group``。

``language`` 接受 ``hscript`` / ``python``，映射到对应
``hou.exprLanguage``；其他值（包括大小写变体）一律
status=error。该命令属于参数通道数据写
（MUTATING_COMMANDS），**不**归为只读或 no-undo；与其他
关键帧 / 范围写共用 undo group 策略。

不读 hou、不发 TCP；通过 stdlib ``subprocess`` 调 PowerShell CIM
（Windows）或 ``ps``（POSIX），按 executable basename
（``husk`` / ``husk.exe`` / ``mantra`` / ``mantra.exe`` /
``mantra-bin`` / ``mantra-bin.exe``）过滤；不把命令行任意
substring 当 renderer。PID / name 必填；CPU / memory 可得为
float，不可得为 ``null`` 并在 ``_warning`` 列明
``cpu_unavailable`` / ``memory_unavailable``。命令缺失、权限
不足或解析失败返 ``status=success``、空 / 部分结果与 warning，
不抛异常。响应整体过 ``apply_response_cap``。

本工具 **bridge-only**，不进入 server registry 或三个 server
分类集合。

Args:
    node_path: 真实 ROP 节点路径（如 ``/out/mantra1``）。
    policy_renderer: 必填提示，bridge Layer 1 用其初筛（``mantra`` /
        ``opengl`` / ``karma_cpu`` / ``karma_xpu``）；不替换真实
        node 推断。
    frame_range: 可选 2 或 3 元 ``[start, end[, inc]]``，缺省走
        ROP 自身设置。
    consent_token: 可选，karma 路径重调时携带。

Returns:
    dict: 直接 relay server 响应；blocked 时为 redirect / interrupt /
    error 字典；正常完成时为 ``status=success`` 含
    ``state / elapsed / frame_range``。

响应字段：``parent_path / count / nodes``，每节点含
``name / path / type / renderer``。未知 ROP type 仍列出但
``renderer=""``。整体过 ``apply_response_cap``。

仅返回 ``ifd`` / ``opengl`` / ``karmarender`` 实际存在且数据安全的
parm；script / callback / command / executable 类型拒绝。整体
过 ``apply_response_cap``。

完整预校验所有 key/value/parm 可写性/prospective engine 后快
照旧值；应用失败显式恢复快照旧值，**不**依赖 undo 自动 rollback。
全部成功 -> ``status=success``；恢复成功 ->
``status=error, error_code=render_settings_apply_failed,
restored=true``；任一恢复失败 ->
``status=error, error_code=render_settings_restore_failed,
restored=false`` + ``restore_errors``。响应过
``apply_response_cap``。

仅允许 ``ifd`` / ``opengl`` / ``karmarender``；创建后通过同一
白名单设置参数并校验 renderer 可识别。未知 node type 整体
error。响应过 ``apply_response_cap``。

使用 ``hou.hda.loadedFiles()`` + ``hou.hda.definitionsInFile()``
按 ``(libraryFilePath, nameWithCategory())`` 去重。响应过
server 端 ``apply_response_cap``。``category`` 可选透传过滤。

``node_type`` 仅接受 ``hou.NodeType.nameWithCategory()`` 完整
类别名（如 ``Sop/box``）；短名称 / 未知 / 歧义均返回稳定
error。响应过 ``apply_response_cap``。

落盘 + 全局 HDA registry 副作用，**不**可由 Houdini undo 恢复。
响应过 ``apply_response_cap``。

先 ``canCreateDigitalAsset()``，再
``createDigitalAsset(name=, hda_file_name=, description=)``。
``label`` 可选，作为 description。响应过 ``apply_response_cap``。

落盘 + registry 副作用，**不**可由 Houdini undo 恢复。

落盘 + registry 副作用，**不**可由 Houdini undo 恢复。

验证节点存在、拥有 definition、实例类型匹配后调
``definition.updateFromNode(node)``；**不**使用
``definition.save()``。响应过 ``apply_response_cap``。

每项含 ``name / size / protected / binary / utf8``；``utf8``
严格探测；``binary`` 固定 true。响应过 ``apply_response_cap``。

``encoding`` 显式必填 ``utf8`` / ``base64``；两种模式均以
``binaryContents()`` 一次拿到的 raw bytes 为唯一分页真相。
响应过 ``apply_response_cap``。

``section`` 仅 ``Help`` / ``IconSVG`` 大小写敏感精确匹配允许；
其他全部 ``section_write_denied`` 且零写入。``content`` UTF-8
字节上限 65536。响应过 ``apply_response_cap``。

使用 ``geo.intrinsicValue("bounds")`` 的
``(xmin, xmax, ymin, ymax, zmin, zmax)`` 标准布局。响应过 server
端 ``apply_response_cap``。

edge groups 在 H21+ 通过 ``geo.edgeGroups()`` 公开。响应过
server 端 ``apply_response_cap``。

- ``offset / limit`` 必填；``limit`` 默认 1000。
- vertex 成员 ``{prim_index, vertex_index, point_index}``；
  edge 成员 ``[min_point, max_point]`` 排序端点对。
- 返回 ``{values, offset, limit, total, next_offset}``。响应过
  server 端 ``apply_response_cap``。

- ``attrib_class`` 接受 ``point / prim / vertex / detail``。
- 返回 ``{values, offset, limit, total, next_offset, storage,
  tuple_size}``。响应过 server 端 ``apply_response_cap``。

``names`` 可选子集过滤；越界返回结构化 error。响应过 server
端 ``apply_response_cap``。

- ``position`` 必须是 ``[x, y, z]``。
- ``max_distance`` 默认 1.0，作为 ``geo.nearestPoint`` 的
  ``max_radius``。
- Point 返回 ``{point_index, point_position, distance}``；None
  返回三字段均 null。响应过 server 端 ``apply_response_cap``。

- 创建 + 连接 + 配置是单 undo group 的连续步骤；失败 destroy
  半成品。
- **不**调用 cooked ``node.geometry()`` 的写方法。
- ``attrib_type`` 接受 ``float / int / string / vector``。
- 响应过 server 端 ``apply_response_cap``。

- ``format`` 接受 ``bgeo / bgeo.gz / bgeo.lzma / bgeo.bz2 / geo``
  （H21+ 实机 ``geo.saveToFile`` 验证）。
- ``output_path`` 扩展名必须与 format 匹配；不匹配返回
  ``extension_mismatch``。
- 临时文件 ``fsync`` + ``os.replace`` 原子覆盖；``overwrite=False``
  且目标存在返回 ``target_exists``；失败清理临时文件。
- 落盘副作用不进 Houdini undo group；响应过 server 端
  ``apply_response_cap``。

预检同名冲突；返回新 path / old_name / new_name。响应过
``apply_response_cap``。

使用 ``hou.copyNodesTo``；预检目标 category 与同名冲突。
``name`` 可选，None 时由 hou 决定。响应过 ``apply_response_cap``。

使用 ``hou.moveNodesTo``；预检目标 category。响应过
``apply_response_cap``。

返回 ``{value, type, expression, is_time_dependent}``；无 expression
时 ``expression: None``。响应过 ``apply_response_cap``。

单 undo group；失败抛 error。响应过 ``apply_response_cap``。

返回 ``{expression}``，空表达式时 ``expression: None``。响应过
``apply_response_cap``。

走 ``parm.revertToDefaults()``，单 undo group。响应过
``apply_response_cap``。

使用 ``Parm.set(Parm)`` / ``setExpression()`` 建跨 parm 引用；
不用 channel alias 冒充。``source`` / ``target`` 形式
``node_path.parm_name``。响应过 ``apply_response_cap``。

``locked`` 接受 bool；单 undo group。响应过 ``apply_response_cap``。

通过 ``parmTemplateGroup()`` 复制 + 一次性
``setParmTemplateGroup()`` 提交。``data_type`` 接受 ``float / int /
string / toggle / menu``。``folder`` 可选。响应过
``apply_response_cap``。

``parameters`` 是 list of spec dict；先全量校验、失败零部分提交。
单次 ``setParmTemplateGroup()`` 完成。响应过 ``apply_response_cap``。