**标题：关于提升“长文档完整性读取”及新用户开箱即用体验的建议**

[xuanku-001]

标题：关于提升“长文档完整性读取”及新用户开箱即用体验的建议

正文：

Harness 团队你好，

我在深度使用 Standard 预设处理长文档（Word/PDF/长网页）时，通过调试 agent.cordis.yml 定位到了导致 Agent 回复“蜻蜓点水”（只概括头尾、遗漏中间核心内容）的三个机制级根因。同时，作为一名尝试入门的新用户，也感受到了较高的配置门槛。

以下是具体的痛点及可落地的优化建议，供参考：

痛点 1：tool-result-pruner 阈值（8192字符）严重截断长文档内容

• 现状：工具返回结果超过 8K 字符自动裁剪为“头 4K + 尾 1K”。对于动辄几万字的文档，AI 物理上“看不到”中间部分，导致总结必然缺失关键信息。
• 建议：
  • 默认阈值调高：建议将默认 thresholdChars 从 8192 提升至 128K 或 256K（适配主流大模型的上下文窗口）。
  • 截断策略优化：若必须截断，建议改为“头 + 尾 + 自动提示截断警告”，强制模型在回复时声明“内容已被截断，如需完整信息请告知”，而非悄无声息地丢失中间段。

痛点 2：persona 缺少“完整性校验”的底层指令

• 现状：Base Persona 仅一句话（“You are a coding agent...”），没有对“读取完整性”做任何硬性约束。AI 拿到截断的数据不会自我怀疑，只会硬着头皮编造概括。
• 建议：在默认 Persona 中内置一条不可忽略的 System Directive：

  “Before delivering a final summary based on file/web content, you MUST state whether the content was fully loaded or truncated. If truncated, prioritize asking the user for permission to read in parts or explicitly list missing sections.”

痛点 3：tool-web 默认 fetch: false 限制了信息获取能力

• 现状：默认只能用搜索摘要，无法抓取网页全文，导致处理在线文档或长文章时先天信息不足。
• 建议：考虑到绝大多数用户是本地个人环境，建议将默认值改为 true。若担心 SSRF 风险，可改为 UI 界面的一个显性开关（如“允许 Agent 抓取网页全文”），让用户根据自身网络环境自行勾选，而非写死在 YAML 里让新手无从下手。

痛点 4：配置修改对新手不友好（YAML 寻路难）

• 现状：新手要优化上述问题，需在 node_modules 或缓存目录里翻找 YAML 文件，且修改后易被更新覆盖。
• 建议：
  • 提供 “新手/专家”模式切换。新手模式下，直接在 Web UI 的设置页提供“上下文长度滑块”和“网页抓取开关”。
  • 官方文档增加一个 “如何为长文档阅读调优” 的 FAQ 专题，直接给出上述 YAML 改法，降低排查成本。

---

总结：
Harness 的架构非常灵活，但默认配置目前更偏向“极客跑分”而非“普通用户处理实际文档”。调整上述 3 个 YAML 参数（Pruner阈值 + Persona指令 + Fetch开关）即可解决 80% 的“内容缺失”投诉，且改造成本极低。

[xuanku-001]

“我做了一个简单测试：第一次让 Agent 读一个长 Word 文档，它只概括了开头和结尾。第二次让 Agent 读一个长网页链接，它又是只概括了开头和结尾。两次独立场景、同样的‘只读头尾’模式——这不是偶然，一定是底层机制在控制。后来我查了配置，发现 tool-result-pruner 阈值 8192 字符，超过就直接截断成头 4K + 尾 1K。这就解释了为什么两次都只看头尾。”

[Ei-Ayw]

xuanku-001 定位得很准，tool-result-pruner 8K 截断就是元凶。补一个不碰配置的实战解法（针对长 Word / PDF 文档）：

1. 先把长文档转成 Markdown 落地到工作区——Word 可以用第三方插件 dsh-word-docs 的 extract（.docx → Markdown，标题/列表/表格都还原），PDF 用 dsh-file-upload 的解析
2. 让 Agent 分段读："先读第 1–3 章，再读 4–6 章……"——每次工具返回只有几百到几千字符，远低于 8K 阈值，中间的核心内容不会被裁掉
3. 读完再基于完整笔记汇总——这次汇总的输入是笔记而非原文档，不会触发截断

原理一句话：把一次大读取拆成多次小读取，绕开裁剪窗口。想根治可以调 toolResultPrune 配置，但分段读是零风险的先行方案，亲测有效。

（dsh-word-docs 为第三方项目，按需甄别使用。）

[xuanku-001]

我的策略：① 侦察 → ② 定策略（你决策） → ③ 按策略读取（声明完整状态） → ④ 不假设缺失 → ⑤ 安全红线 → ⑥ 自检

• ⑦ 源状态标注 + ⑧ 分段确认 + ⑨ 侦察/交差分离
  修复后AGENT返回：修复的认知**（这是最重要的收获）：

1. tool-web fetch 禁用是 SSRF 安全设计，不是疏忽——不该绕过
2. "蜻蜓点水"的真正主因：不是没有抓取能力（pwsh 抓取一直可用），而是没有"侦察→深挖→自检"的纪律——这是 persona 层面的事，已修复
3. 网页抓取今后：pwsh 显式抓取 + 按 5.10/persona 纪律（先侦察结构→确认边界→深挖到底→标注完整状态）