# 第 12 章：已知不足与边界——诚实版

> 本章目标：不吹不黑，列出 dsh 当前的**已知不足**与**使用边界**。写这本白皮书时 dsh 仍处于 `0.1.0-rc.6`（预发布阶段），这些不足是"此刻的事实"，不是"永远的宿命"——它们会随版本迭代变化。
>
> 本章所有"已知问题"均来自本机实测 + 官方仓库 deepseek-ai/deepseek-harness 讨论区（截至 2026-08-14）的公开反馈。

## TL;DR（本章核心，30 秒版）

1. **rc 阶段是最大的不确定性**：API/配置随时可能破坏性变更，投入前先锁版本线
2. **插件生态早期**：官方包 60+ 但覆盖有限，第三方插件少，交互形态（TUI）缺失
3. **跨平台短板**：Windows 上除路径/编码 bug（UTF-16、0x00）外，还有端口保留、局域网访问、沙箱稳定性、WSL 工作区、子进程终止等家族问题（速查表见 [12.4](#124-跨平台已知问题速查表)）
4. **性能边界未充分验证**：高并发、大型代码库场景缺少公开压测数据
5. **官方策略风险**：开源承诺 vs 商业化转向，是选型时必须考虑的黑天鹅

<!-- [fix] 结构核验：补齐本章导航（第 12 章为新增章节，原缺失，与第 3-11 章结构保持一致） -->
<details><summary>本章导航</summary>
- [12.1 rc 阶段的不稳定性](#121-rc-阶段的不稳定性)
- [12.2 插件生态早期](#122-插件生态早期)
- [12.3 跨平台短板](#123-跨平台短板)
- [12.4 跨平台已知问题速查表](#124-跨平台已知问题速查表)
- [12.5 性能边界未充分验证](#125-性能边界未充分验证)
- [12.6 与成熟 Agent 的差距](#126-与成熟-agent-的差距)
- [12.7 官方策略风险](#127-官方策略风险)
- [12.8 白皮书自身的局限](#128-白皮书自身的局限)
</details>

---

## 12.1 rc 阶段的不稳定性

### 破坏性变更随时发生

dsh 从 rc.1 到 rc.6 已经历过至少一次**依赖断裂**：早期版本 `@deepseek-ai/*` 包的版本线不一致会导致插件装不上（404/ERR_MODULE_NOT_FOUND）。rc.6 收敛了很多，但**没有任何承诺**说 rc.7/正式版不会再来一次。

**对你的实际影响**：
- 写教程/插件，可能每两周就要跟着改一遍
- 锁版本线（`^0.1.0-rc.6`）是基本操作，但 rc 线升级是"向上兼容"还是"推翻重来"，取决于官方心情

> [!WARNING]
> 生产环境请谨慎评估。白皮书写作时官方仍在快速迭代，**今日的写法明天可能就废弃**。

### 已知的 rc 坑（本机/社区复现）

| 坑 | 表现 | 状态 |
|---|---|---|
| link 开发依赖断裂 | `@deepseek-ai/*` 本地 link 时报 ERR_MODULE_NOT_FOUND，npm 安装却正常 | 已定位（扁平兜底目录机制），需锁依赖线规避 |
| Windows 路径 0x00 | 含中文/特殊字符路径 workspace 创建失败（ENOENT） | 社区反馈中（#151/#396） |
| fs-sandbox 竞态 | post-check 路径检查与 workspace-write 存在时序竞态 | 社区反馈中（#159） |
| TUI 缺失 | 官方 examples 无交互终端 UI（社区自建有，未纳入） | 建议中（#392） |

## 12.2 插件生态早期

**现状**：官方包 60+，但生态整体处于"零日"状态。

- **第三方插件少**：讨论区插件帖在爆发，但质量参差，多数是"第一个插件"练手作
- **交互形态缺失**：headless/JSON-RPC/Web 形态齐全，**TUI 等终端交互形态无官方示例**（社区 deepseek-harness-tui 已证明可行，未纳入官方）
- **文档滞后于代码**：官方文档以架构为主，上手路径/避坑记录依赖社区自产（这正是本白皮书存在的理由）
- **版本线混乱**：npm 上同包多版本线并存，装错线就是 404

**判断**：生态玩法现在入场是早期红利（竞争少、官方扶持意愿强），但**不要指望"照着官方文档就能跑"**——踩坑是常态。

## 12.3 跨平台短板

dsh 在 macOS/Linux 上表现成熟，但 Windows 支持有明显的**第二公民感**：

- **路径处理**：中文路径、特殊字符路径有真实 bug（0x00 截断、ENOENT），社区多人反馈（根因 #107，家族 17+ 帖）
- **编码问题**：UTF-16 相关处理存在缺陷，终端输出偶发乱码
- **CLI/TUI 之争未定**：官方讨论区存在"CLI 才是正道 vs TUI 才是交互未来"的路线争议（#386），路线未明前，投资终端 UI 形态有风险

> 以下 Windows 家族问题来自官方讨论区挖掘报告（[docs/research/discussion-mining.md](./research/discussion-mining.md)，2026-08-14 抓取，rc.6 时代），均为社区真实复现，多数尚未修复。

### 端口：默认 3080 撞上 Hyper-V 保留区间（#589）

**现象**：Windows 上默认端口 3080 启动报 EACCES，服务起不来、web 界面打不开。
**根因**：启用 Hyper-V/WSL2 后，Windows 会保留一段动态端口区间（3070-3169），3080 恰好落在其中。
**临时 workaround**：换用保留区间外的端口（社区实测 13080 可用）。

### 局域网 HTTP 访问 RPC 全挂（#755）

**现象**：局域网内通过 HTTP（非 localhost、非 HTTPS）访问时，所有 RPC 调用失败。
**根因**：`crypto.randomUUID` 只在安全上下文（HTTPS 或 localhost）可用，局域网裸 HTTP 属非安全上下文。
**临时 workaround**：官方无修复；HTTPS 或隧道（如 Tailscale）访问可规避非安全上下文限制（按成因推论，未在社区帖内验证）。

### 沙箱：临时目录清理后永久崩溃（#758）

**现象**：Windows 上清理沙箱临时目录后 dsh 永久崩溃、不自愈（社区标 P0），并伴随 4 个相关稳定性问题。
**影响**：清一次临时目录 = 服务报废，无自动恢复路径。
**临时 workaround**：不要清理 dsh 沙箱临时目录；已触发则重启进程恢复。

### WSL：工作区只能选 /root（#160）

**现象**：WSL/Ubuntu 环境下工作区选择器只能选 /root 内的目录，其余路径不可选。
**临时 workaround**：把项目放到 /root 下使用（限制内可用，限制外暂无绕过方案）。

### 子进程：Windows 无优雅终止（#717）

**现象**：Windows 下子进程管理系统性缺失——没有优雅终止阶梯、孙进程输出截断、spill 权限不生效、shellPath 默认指向 /bin/bash（Windows 上不存在该路径）。
**影响**：长任务终止不干净、输出丢失、权限预期失效，属平台适配缺口而非单个 bug。
**临时 workaround**：手动 `taskkill /T` 清理进程树；显式配置 shellPath 为 Windows 实际路径。

---

## 12.4 跨平台已知问题速查表

> 本章跨平台已知问题一表速查。帖号均为官方讨论区真实帖（deepseek-ai/deepseek-harness），截至 2026-08-14。

| 问题 | 环境 | 帖号 | 临时 workaround |
|---|---|---|---|
| 中文路径截断（readUtf16 单字节判 0，`开`=U+5F00 被截） | Windows | [#107](https://github.com/deepseek-ai/deepseek-harness/discussions/107)（根因；家族 #151/#396/#563 等 17+ 帖） | 工作区路径避开中文/特殊字符；社区附修复补丁可 cherry-pick（#244/#580） |
| 目录选择器 worker 崩溃（koffi 相关） | Windows | [#30](https://github.com/deepseek-ai/deepseek-harness/discussions/30)（家族 #154/#236/#449/#768） | 安装层锁 koffi@3.1.2（#293）；选择器崩溃暂无绕行 |
| 默认端口 3080 撞 Hyper-V 保留区间（EACCES） | Windows（启用 Hyper-V/WSL2） | [#589](https://github.com/deepseek-ai/deepseek-harness/discussions/589) | 换用保留区间外端口（如 13080） |
| 局域网 HTTP 访问 RPC 全挂（crypto.randomUUID 非安全上下文） | 局域网 HTTP（非 localhost） | [#755](https://github.com/deepseek-ai/deepseek-harness/discussions/755) | HTTPS/隧道访问可规避（推论）；官方无修复 |
| 沙箱临时目录清理后永久崩溃（不自愈，P0） | Windows | [#758](https://github.com/deepseek-ai/deepseek-harness/discussions/758) | 勿清理沙箱临时目录；已触发需重启进程 |
| WSL 工作区只能选 /root 内目录 | WSL/Ubuntu | [#160](https://github.com/deepseek-ai/deepseek-harness/discussions/160) | 项目放 /root 下使用 |
| Windows 子进程无优雅终止（孙进程输出截断/spill 失效/shellPath 错） | Windows | [#717](https://github.com/deepseek-ai/deepseek-harness/discussions/717) | 手动 `taskkill /T` 清理；显式配置 shellPath |

---

## 12.5 性能边界未充分验证

白皮书的 benchmark 覆盖了**单 agent、常规任务规模**，以下场景缺少公开数据：

- **高并发**：多 agent 并行、大规模任务分发
- **大型代码库**：百万行级仓库的上下文管理、工具调用延迟
- **长时运行**：连续数小时运行的稳定性、内存泄漏风险
- **缓存命中率的边界**：97% 实测命中率依赖"对话模式重复"——全新任务/冷启动场景会明显下降

## 12.6 与成熟 Agent 的差距

对照 Claude Code、Codex 等成熟产品，dsh 的差距是**结构性**的（不是补几个功能就能追上）：

| 维度 | dsh（rc.6） | 成熟 Agent |
|---|---|---|
| 生态阶段 | 零日，第三方资产稀少 | 成熟，生态完整 |
| 开箱即用 | 需理解 profile/插件体系 | 装完就跑 |
| 稳定性 | rc 期，破坏性变更风险 | 稳定版，长期兼容承诺 |
| 文档 | 官方偏架构，上手靠社区 | 官方文档完善 + 教程丰富 |
| IDE/工具链集成 | 起步 | 深度集成 |

**dsh 的定位**：不是"开箱即用的整车"，是"可编程的乐高底座"。选择 dsh = 选择**自由度**，代价是**自己要动手拼**。

## 12.7 官方策略风险

作为选型者，必须考虑的黑天鹅：

- **开源承诺**：MIT 开源目前无杂音，但"官方级插件体系"意味着生态深度绑定官方节奏
- **模型绑定倾向**：官方默认体验倾向 DeepSeek 模型（通过 llm 插件可接任意模型，但"官方优化"以自家模型为主）
- **商业化转向**：一旦 dsh 用户量上来，官方可能推出托管服务/付费层——开源版能否保持同等能力未知
- **方向漂移**：rc 期功能增删频繁（TUI/CLI 路线之争即信号），押注错误方向 = 沉没成本

## 12.8 白皮书自身的局限

最后，诚实说这本白皮书自己：

- **基于 rc.6 编写**：所有命令、配置、数据在 rc.6 验证，**新版本可能全部失效**
- **benchmark 样本有限**：单机、单模型、有限任务集，不是权威评测
- **中文优先**：英文版是翻译/精简版，可能滞后于中文版内容
- **覆盖不全面**：dsh 官方包 60+，本手册深挖的是核心路径，长尾插件未逐一覆盖

> **使用建议**：把本白皮书当"rc.6 快照 + 方法论"，不要当"永恒圣经"。版本更新时，先跑一遍 [roadmap 学习路径](./roadmap.md) 与 [速查卡](./cheatsheet.md) 的验收标准，再决定要不要更新你的依赖线。

---

*本章信息截至 2026-08-14（dsh 0.1.0-rc.6）。后续版本如有更新，欢迎提 Issue/PR 修正。*