跳到主要内容

渐进式披露（Progressive Disclosure）优化经验

记录日期：2026-06-18

背景​

对现有的工具进行优化，引入渐进式披露（Progressive Disclosure）模式，让大模型按需读取详细文档，减少单次上下文消耗，提升响应效率。

一、渐进式披露写法规范​

参考格式​

#### 📋 销售业绩数据查询

> 📖 **Progressive Disclosure / 渐进式披露**：需要详细参数和调用示例时，请先 `read references/sales-performance-tools.md`

关键要点​

要点说明
「渐进式披露」不是必须的它只是行业约定俗成的标记词，作用是让大模型一眼识别"按需读取、延迟加载文档"规则。去掉这五个字也能正常工作。
推荐中英文对照使用 **Progressive Disclosure / 渐进式披露** 双保险
为什么推荐英文Progressive Disclosure 是 LLM 训练数据中的高频专业术语。GPT、Claude、Qwen、DeepSeek 等模型看到该词组，能瞬间识别懒加载/分步读取逻辑，几乎不会漏调用 read。

结论​

推荐使用：**Progressive Disclosure / 渐进式披露**

兼顾英文大模型的术语识别能力和中文语境的可读性。

二、渐进式披露的已知副作用​

问题：钉钉连接器分段输出​

使用渐进式披露模式后，钉钉连接器（dingtalk channel）的回复出现一条消息被拆分成多段输出。

对比验证​

模式结果
✅ 不使用渐进式披露正常输出，单条回复
❌ 使用渐进式披露出现分段输出，一条回复拆成很多段

推测原因​

OpenClaw 在渐进式披露模式下会发送 tools trace（工具调用追踪），导致钉钉连接器每段 trace 输出一次，从而出现分段现象。

⚠️ 此说法尚未完全证实，但现象可稳定复现。

建议​

  • 暂未找到根本解决方案
  • 如果钉钉渠道对分段输出敏感，可以考虑：
    • 避免在钉钉渠道使用渐进式披露
    • 或等待 OpenClaw 后续版本优化 tools trace 的分段行为

三、关联历史经验​

钉钉消息截断问题（2026-06-17）​

之前 ms-ops-analysis 遇到过钉钉长消息截断问题，尝试过的方案：

方案结果
sessions_send 分段发送❌ 不可行 — 会拼接到当前卡片，不是新消息
定时器 agentTurn 分段❌ 太慢 — 需要过大模型，不能立即输出已有内容
openclaw message send CLI + PDF✅ 最可靠方案

钉钉连接器配置注意事项​

clientId / clientSecret 需要在两个层级都配置，缺一不可：

# 1. 账户层
channels:
  dingtalk:
    accounts:
      bot_public:
        clientId: xxx
        clientSecret: xxx

# 2. 连接器外层
channels:
  dingtalk:
    clientId: xxx
    clientSecret: xxx

原因：openclaw message send CLI 只有 --channel 参数，没有指定 bot 的参数，所以两个层级都需要。

四、总结​

项目结论
渐进式披露写法推荐 **Progressive Disclosure / 渐进式披露** 中英文对照
标记词是否必需❌ 不是必需的，去掉也能跑
钉钉分段输出✅ 可稳定复现，推测与 tools trace 有关
替代方案PDF + CLI 发送（已验证可靠）