capture_workflow_snapshot
Capture a read-only structured snapshot of a selected Houdini node subnetwork, including node metadata, VEX, sticky notes, and connections, for documenting workflow knowledge.
Instructions
把用户选中（或 node_path 指定）的节点子网络捕获为结构化工作流快照 （add-workflow-knowledge-capture，readOnly relay，不修改场景）。
触发时机（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。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ctx | Yes | ||
| max_nodes | No | ||
| node_path | No | ||
| include_vex | No | ||
| include_hda_internals | No |