客户端、Python 与 Native：三个外围平面

示例本次示例：web UI 渲染我们的会话

# 11 页示例轨迹 11-1 的 seq 0-16 日志
# apiproxy（32 页）把 session/event 推给浏览器
# ui-conversation 渲染 transcript：
#   遍历事件，用 isAppendSurfaceEvent 过滤（06 页）
#   → 用户看到：turn 1 的完整对话（含 chunk 重建的模型回复）
#   若日志里有 compaction 的 replace 摘要（21 页示例轨迹 21-1）：
#   → 摘要被过滤掉 → 用户仍看到 50 个 turn 的原文
# UI 不发明状态——数据永远是日志的投影（33 页 §1）

# Linux 上：native/landlock-run（Landlock addon）实现文件访问限制
# Windows 上：sandbox-windows-acl（2530 行 ACL 沙箱）实现同类限制
# 两者都实现 29 页的沙箱 seam → 产品代码不写 if(platform)
# 平台差异被 seam 吸收（33 页 §3 的结论）

§1client 包群（36 包）

packages/client/ 是 Web UI 的全部：

• 浏览器运行时：web-react（React 桥）、connection（9 文件 / 937 行，与宿主 apiproxy 的连接）、runtime（56 行）
• UI 组件族：ui-conversation、ui-sidebar、ui-tool、ui-permission-presets、ui-model-selection、ui-subagent、ui-workflow-run、ui-directory-picker-browse……每个能力域一个 UI 包（命名即能力）。
• 主题与基础：ui-theme（156 行）、ui-primitives（855 行）——设计系统层。
• 浏览器安全约束的延伸：06 页提过 surface.ts/json.ts 是「浏览器安全子路径」（禁 node: 导入）——client 消费它们就是原因。UI 渲染的 transcript 用 isAppendSurfaceEvent 过滤（06 页），模型可见的 replace 不进人类视图。

读 UI 的正确姿势：先读 apiproxy 的契约（32 页），再读对应 ui-* 包的渲染器——数据永远是 06 页日志的投影，UI 不发明状态。

§2python/sdk

python/sdk/src/deepseek_harness/ 是 Python 客户端（5 个模块：api / client / errors / models / __init__）：

• 协议客户端：与 32 页的 JSON-RPC SDK 对应——Python 程序驱动 harness agents。
• 内置运行时：python/README 提到 bundled runtime——Python SDK 自带运行时环境（对模型可见的 Python 代码执行），与 14 页的 Code Mode 呼应（py-types.ts 渲染的 SDK 就跑在这种运行时里）。
• 模型可见断言：python 的测试里有「model-visible surface」的 pin（PR #2462）——「模型可见 ⟺ 已记录」不变量在 Python 侧同样被测试钉住。

§3native/landlock-run

native/landlock-run/ 是 @deepseek-ai/node-addon-landlock-run 的源：Linux Landlock 沙箱的 node-addon（平台包 linux-x64/linux-arm64）。它对应 29 页的沙箱域——Landlock 是 Linux 的「文件系统访问控制」内核机制，addon 把它暴露给 harness 的沙箱 provider。

结构：packages/entry（JS 面）+ 两个平台包（linux-x64 / linux-arm64）+ 顶层 source of record。Windows 的 ACL 沙箱（29 页的 sandbox-windows-acl）是它的平台对应物——沙箱能力是平台实现的，seam 是平台无关的。

§4易错点