学习笔记：从「已知限制」里读出三处设计张力

读一个陌生框架的文档，最容易跳过的是每篇末尾那节「已知限制」——它读起来像免责声明。但对 DeepSeek Harness（下称 dsh）这类还在 developer preview 阶段的体系来说，那一节的信息密度是全篇最高的：它是设计者自己签过名的取舍，写明了「我知道这里有问题，我选择了这一边」。把散落在十几个包里的这类段落收拢对照，会浮出三处贯穿全局的张力，而它们各自都有能在生产里咬人的下游后果。

版本说明

基于 0.1.2-rc.1（developer preview）本地安装目录里的随包中文文档整理。张力本身来自设计取舍，短期内不会变；但被标为「已知限制」的具体条目，恰恰最可能在下一版被改掉——读到与本文不符时以你机器上的实机输出为准。

---

1. 为什么要专门找「冲突」，而不是只记「共识」

学一个体系，先抓共识（核心机制、心智模型）能拿到大部分的解释力——这部分整理在本系列上一篇五个核心心智模型里。但只有共识的理解有个明确的失效模式：它无法预测哪里会出问题。共识告诉你「设计成什么样」，冲突才告诉你「设计者在哪里没能两全」，而故障几乎总是发生在没能两全的地方。

自然科学的领域里，冲突表现为学派之争；软件项目里没有学派，冲突表现为三种形态：

1. 文档里明写的取舍——「已知限制」「设计理念」两节，通常带一句「我们选择了 A，代价是 B」。
2. 同一个仓库里两处自相矛盾的表述——不同包对同一个概念给出不同的强度承诺。
3. 一条规则和另一条规则的正面冲突——某个可选特性直接违反了体系的基础假设，而设计者接受了。

下面三处张力刚好各占一种形态。编造「支持派 vs 反对派」是这套读法最容易做假的一步——软件领域里没那种东西，一切引用都必须能回落到具体文件的具体段落。

---

2. 张力一：配置层被刻意做窄，能力向编程式 API 倾斜

形态：文档里明写的取舍｜出处：agent 循环包（dsh-agent-loop）

README 的原话是：配置式 agent 没有逐 agent 的 persona 字段，也没有 setup 钩子；只有编程式的工厂选项才支持带作用域的 persona 与工具组合。

也就是说，YAML 那一层被有意做窄了。想给两个 agent 配不同人格、不同工具集，配置文件里没有对应字段，得写代码。

保守一侧的理由站得住：声明式配置的表达力天然有限，一旦开始支持条件、组合、作用域，配置格式会缓慢长成一门半吊子编程语言——这个坑几乎每个成熟的配置系统都踩过。把复杂组合推到编程式 API，配置层就能保持「只做声明」的清爽，也更容易做校验和迁移。

另一侧的代价同样真实：运维场景里改配置和改代码是两种成本完全不同的操作。前者可以热改、可以由不写 TypeScript 的人做、可以进配置管理；后者要重新构建发布。这堵墙的结果是运维者要么被迫写代码，要么绕道 preset 去凑效果。

一个能观察到的下游后果

这条张力有个具体投影：某些 preset 相关的能力在纯命令行模式下验证不了——因为承载 preset 的插件挂在 Web 应用那一支下面。你在 CLI 里试，会得到「配置写了但看不出效果」的结果，然后开始怀疑字段拼写。真正的原因是那个 fiber 根本没在这条启动路径上。

能直接用的规则：遇到「配置不生效」，先问的不是字段对不对，而是承载它的插件在当前启动模式下有没有被加载。CLI 与 Web 两条路径的插件树不一样。

---

3. 张力二：隔离到底算不算安全边界——同一个仓库里有两个答案

形态：自相矛盾的强度承诺｜出处：作用域包、沙箱那一支、主程序启动参数

把三处表述放在一起看：

位置	表述	承诺强度
作用域包（dsh-scope）	原话：「它不是沙箱或权限边界」	不承诺任何隔离
沙箱那一支（含 landlock 原生模块）	Linux 内核级 landlock 真隔离	承诺文件系统级强隔离
主程序启动参数	硬性拒绝把服务绑到 0.0.0.0，理由是防远程代码执行	承诺网络边界从严

初读像是自相矛盾。但把三条对齐之后，结论其实是自洽的：

dsh 把「插件与插件之间」当作互相信任，把「进程与文件系统之间」「服务与网络之间」当作互不信任。

作用域解决的是路由问题——哪个 agent 看得见哪个工具，谁的生命周期挂在谁身上。它从来不打算解决「不可信代码」的问题，因为在它的假设里，同进程里跑的插件全是你自己装的。真正的不信任边界画在进程外：文件系统靠内核，网络靠不给绑公网。

分歧不在设计者之间，而在新人容易把第一种当成第二种。把 scoped ctx 交出去，等于把该作用域的服务解析能力整个交出去了——它不会拦你。

一条值得实测的推论

沿着这条线还有一个配置层面的观察，未经实测，但部署时值得留意：沙箱的写入根取的是服务进程自己的当前工作目录，而不是界面上显示的那个 workspace。用 systemd 之类的方式托管服务时，如果单元里的工作目录设成了家目录，那么会话的实际可写范围就是整个家目录——与界面显示的不是一回事。命令行模式下两者天然重合，所以这个差异只在托管部署时暴露。

验证方法：对照服务托管单元里的工作目录设置，与会话界面显示的工作区路径；不一致就在会话里往工作区之外写一个临时文件，看它落在哪。

---

4. 张力三：PTC 模式与「日志是唯一真源」正面冲突

形态：可选特性违反基础假设｜出处：工具注册表包（dsh-tools）

dsh 有两条把工具暴露给模型的路：原生 function calling，和 PTC 模式——让模型写代码来调工具。后者在多步骤、需要中间变量的任务上表达力明显更强。

但 README 自己写着：PTC 模式的中间值只存在于执行局部，没有字节上限，因此无法从会话回放中重建，并可能耗尽进程或 worker 内存。

这直接违反了这套体系的基础假设之一：会话是只追加的事件日志，模型看到的一切都由日志派生而来。PTC 模式下，一部分实际发生过的计算过程不进日志。设计者知道，写下来了，然后接受了这个代价。

代价具体表现为三条：

• 回放不完整：同一份日志重放，PTC 那段的中间状态复现不出来。审计与事后排障在这里断链。
• 没有内存上限：中间值不设字节上限，一个循环里累积的大对象能把 worker 撑爆，而且这不会体现在会话大小上。
• 失败来得晚：模式不合法时是在首轮组装提示词才拒绝，不是启动时。配置写错不会在启动阶段告诉你。

还有一条容易被忽略的粒度限制：PTC 是按 agent 而非按工具开关的。不能让一个工具走原生 function calling、另一个走 PTC——想混用就得拆成两个 agent。

能直接用的规则：需要可审计、可回放的场景（生产变更、资金操作、任何要留痕的动作），不要开 PTC；把它留给探索性的、失败无所谓的任务。这不是性能取舍，是可观测性取舍。

---

5. 坑与边界

• 不要把「已知限制」当成 bug 列表。 它们大多不会被修，因为它们是取舍的另一半。指望下一版消失，等于在错误的假设上排期。
• 不要编造学派之争。 软件领域的「争议」必须能落到具体文件的具体段落；找不到出处的对立观点，是复述者自己加的戏。
• 张力会移动，出处不会。 版本迭代后具体条目可能改写，但「哪一节承载这类信息」是稳定的——回原文重读那一节比记住结论更耐用。
• 这三处不是全集。 它们是从骨架层十几篇里剥出来的，功能插件各自的「已知限制」还有一批更局部的取舍。
• 张力二的沙箱写入根那条是配置层面的推论，未经实测——照抄结论前请在自己的部署上验一遍。

---

6. 可复用要点

这套「读冲突」的方法可以迁移到任何一个陌生框架：

1. 先读共识，再读冲突。 没有心智模型托底，冲突读起来只是零散的注意事项。
2. 优先读「已知限制」和「设计理念」两节，它们的信息密度远高于功能说明。
3. 横向对照同一概念在不同包里的承诺强度，强度不一致的地方就是边界所在（张力二就是这样浮出来的）。
4. 重点标记「违反了体系基础假设的可选特性」，那是最危险的一类——它平时工作正常，只在你依赖那条基础假设时才出事。
5. 每条冲突都要能回落到出处，无法回落的一律当作自己的推测标注出来。

自检：怎么确认自己真的读懂了

以下三条都能在本机得到明确结论，不是背诵题：

检验对象	怎么确认	预期结论
张力一	在纯命令行模式下配一个依赖 Web 侧插件的能力	无报错、无效果——确认是插件树差异而非字段错误
张力二	对照托管单元的工作目录与界面显示的工作区路径	两者可能不一致；不一致时以进程 cwd 为准
张力三	开启 PTC 模式跑一个多步任务后回放会话	中间值无法从日志重建，回放在该段断链

三条里任何一条结果与预期不符，说明该张力在你这个版本上已经变化——回原文重读那一节，而不是沿用本文结论。

---

7. 延伸阅读

dsh 的公开文档站有中文版：DeepSeek Harness 参考手册 (opens new window)，仓库在 deepseek-ai/deepseek-harness (opens new window)。插件级配置字段与「已知限制」原文，以本地安装目录里各插件自带的 README.zh.md 为准——本文引用的多数段落在站上查不到。

本系列另外三篇：提示词分层与技能加载实测、三个 Harness 的解剖、五个核心心智模型。本文是最后一篇的延续——先读那篇拿到骨架，再读这篇看骨架在哪里没能两全。

---

🤖 Agent 可直接解析的元数据块（点击展开）

{
  "_meta": {
    "doc_version": "2026-09-08",
    "article_id": "dsh-04-three-design-tensions",
    "profile_context": "any",
    "estimated_setup_time": "20min"
  },
  "quick_start": {
    "step_1": "定位骨架层各包的『已知限制』与『设计理念』两节，单独抽出",
    "step_2": "横向对照同一概念在不同包里的承诺强度，找出不一致处",
    "step_3": "标记违反体系基础假设的可选特性，评估其可观测性代价",
    "step_4": "为每条张力写出可在本机验证的检验步骤与预期结论"
  },
  "tensions": [
    "配置层刻意做窄，逐 agent persona 与工具组合只在编程式 API 提供；下游后果是部分能力在纯 CLI 路径下无法验证",
    "隔离语义分层：插件间互相信任（scope 非权限边界），进程与文件系统、服务与网络之间互不信任（landlock 与拒绝绑 0.0.0.0）",
    "PTC 模式中间值不进日志、无字节上限、无法回放重建；按 agent 而非按工具开关；非法模式在首轮组装提示词时才拒绝"
  ],
  "safety_rules": [
    "需要可审计与可回放的场景不要启用 PTC 模式",
    "不要把作用域当权限边界，交出 scoped ctx 等于交出该作用域的服务解析能力",
    "托管部署时确认沙箱写入根与界面显示的工作区是否一致",
    "『配置不生效』先查承载插件在当前启动模式下是否被加载，再查字段拼写"
  ],
  "verification": {
    "check_plugin_tree_by_mode": "对比 CLI 与 Web 两条启动路径下实际加载的插件集合",
    "check_sandbox_root": "对照服务托管单元的工作目录与会话界面显示的工作区路径",
    "check_ptc_replay": "开启 PTC 跑多步任务后回放会话，确认中间值是否可从日志重建"
  }
}

AI Agent 使用指南：

• 当用户说「配置写了但没效果」→ 先按 check_plugin_tree_by_mode 确认启动路径差异，再查字段
• 当用户说「要不要开 PTC」→ 先问是否需要审计与回放；需要则不开
• 当用户说「这个隔离够不够安全」→ 区分插件间（不承诺隔离）与进程/网络边界（承诺隔离）两类问题
• 当用户说「帮我快速吃透某个框架的坑」→ 按 quick_start 抽取『已知限制』并横向对照承诺强度