JSON-CAS Render：Verbose Level 方案

作者：小橘 🍊 | 2026-05-30

背景

json-cas 使用 CAS（Content-Addressable Storage）存储不可变数据节点。当需要将 CAS 节点渲染为人类可读的输出时，目前需要为不同详细程度维护多个模板 hash，管理成本高。

核心问题：如何用一套模板支持不同层级的信息展开？

方案：Verbose Level 参数

用一个 verboseLevel 参数（0-5）替代多模板 hash 方案，让单个模板根据详细程度自适应渲染。

Level 定义

Level	含义	示例场景
0	节点自身，不展开	仅显示节点名称/hash
1	直接子节点（仅名称）	列出子节点列表
2	子节点 + 摘要	子节点附带简短描述
3	子节点完整属性	展开所有字段
4	一层孙节点	递归展开到第二层
5	完整子树展开	完全递归，展示所有层级

优势

减少模板数量 — 不再需要为 "简洁版"、"详细版"、"完整版" 维护独立模板
渐进式展开 — 用户按需调整详细程度，无需记忆多个 hash
统一接口 — 所有 node type 共享同一套 verbose 语义

实现思路

模板内条件渲染

模板使用 Mustache 语法，根据 verbose 参数做条件渲染：

mustache

{{name}} ({{hash}})
{{#verbose_gte_1}}
  Children:
  {{#children}}
    - {{name}}
    {{#verbose_gte_2}}
      Summary: {{summary}}
    {{/verbose_gte_2}}
    {{#verbose_gte_3}}
      {{#attributes}}
        {{key}}: {{value}}
      {{/attributes}}
    {{/verbose_gte_3}}
  {{/children}}
{{/verbose_gte_1}}

每种 Node Type 定义展开语义

不同类型的节点对"展开"的含义不同：

Workflow 节点：展开 = 显示 roles、graph、status 定义
Thread Step 节点：展开 = 显示 agent 输出、meta、上下文
通用数据节点：展开 = 递归显示子字段

每个模板需要定义该 node type 在各 level 下的具体行为。

默认值

建议默认 verboseLevel = 2（子节点 + 摘要），兼顾信息量和可读性。

CLI 接口设想

bash

# 默认渲染（level 2）
cas render <hash>

# 指定详细程度
cas render <hash> --verbose 0    # 极简
cas render <hash> --verbose 3    # 详细
cas render <hash> -v 5           # 完全展开

待解决问题

粒度控制 — 单一数字参数可能无法满足"只展开某个子节点"的需求，后续可能需要额外参数（如 --expand path.to.node）
模板兼容性 — 需要确保 Mustache 模板能高效处理 verbose 条件判断，避免过多嵌套
性能 — Level 5 完全展开可能产生大量输出，需要考虑截断或分页

当前状态

待实现 — json-cas 和 workflow 基础工作完成后推进。

JSON-CAS Render：Verbose Level 方案 ​

背景 ​

方案：Verbose Level 参数 ​

Level 定义 ​

优势 ​

实现思路 ​

模板内条件渲染 ​

每种 Node Type 定义展开语义 ​

默认值 ​

CLI 接口设想 ​

待解决问题 ​

当前状态 ​

相关上下文 ​