# 已知限制与成熟度说明

版本：`0.1.0`（Developer Preview）

最后核对：2026-08-21

本文明确列出当前不能保证的内容，避免把“构建/测试通过”误认为“在所有 Harness 版本中都已稳定”。

## 1. Harness 契约仍可能破坏性变化

DeepSeek Harness 当前处于实验阶段。以下契约一旦变化，插件可能降级或无法激活：

- `dsh.bundle.patch` 与 profile layer 格式；
- Cordis service key、注入和生命周期；
- Client ModuleLoader、slot 名称与 slot props；
- `sessionQuery`、`sessionTitle`、`sessionPersistence`；
- `workspaceRegistry`、`agents`、`subagents`；
- `sessions.open` 与 `sessions.openSubagent`。

缓解：所有 service key、事件和 client slot 已集中到版本化 adapter；能力探测会报告缺失项。重大升级应新增 adapter，不应直接改业务核心。

## 2. 真实 UI 验证不是单元测试的替代品

当前自动测试能证明类型、构建、传输边界、布局、归档、改名、缓存和适配器逻辑符合仓库中的契约，但不能证明某个正在运行的 Harness 进程已经加载了新包，也不能证明浏览器中的视觉和交互完全正确。

每次 Harness 升级至少需要人工验证：按钮出现、面板开关、普通/子代理跳转、改名、批量归档、归档显隐、Agent 状态和卸载清理。

## 3. 仅支持 Web client

清单声明 `platform: web`。插件依赖同源 `fetch`、DOM、Pointer Events 和 Harness Web slots。Electron 专用 bridge、原生桌面壳或 headless 环境没有兼容承诺。

## 4. 本机 HTTP 边界不是身份认证

API 强制 POST、JSON、自定义 header、同源 Origin、`Sec-Fetch-Site` 检查和 64 KiB 请求上限。这能缓解普通浏览器 CSRF 和误请求，但 Host header 可被本机进程伪造，Harness webserver 本身也可能监听 `0.0.0.0`。

不要把未加反向代理认证的 Harness 暴露到不可信网络。需要远程访问时，应由部署层提供 TLS、认证、来源限制和防火墙。

## 5. 冷会话改名对 event schema 敏感

活跃会话优先使用 `sessionTitle.rename`。冷会话使用 `sessionQuery.readSession` 加 `sessionPersistence.append` 追加标题事件，并对序列冲突重读后重试一次。若 Harness 改变标题事件类型、序列规则或 append 语义，应临时关闭冷改名能力，直到 adapter/contract 更新。

## 6. 归档不可撤销

插件目前没有“取消归档”。批量归档会收集已选父节点的子代理后代；所有目标在写入前都会做工作区授权，但用户仍应先确认选择范围。级联项失败会报告数量，不会假装整批成功。

## 7. 超大工作区仍有成本

默认视图不读取归档标题和子代理，且有缓存、合并、信号量和退避保护。开启“显示归档”仍需要扫描完整工作区；会话数量达到数百或数千时，首次加载、自动布局和 DOM 渲染可能变慢。目前没有虚拟化或增量 session index。

## 8. 可访问性与触屏仍不完整

常用按钮带标题和可见状态，主要操作可通过点击完成；但完整键盘导航、焦点顺序、屏幕阅读器语义、触屏双指缩放和移动端布局还没有完成专项审计。

## 9. 诊断有意去敏

诊断端点只返回 adapter、插件版本和能力状态，不返回路径、会话 ID、标题或内容。这有利于隐私，但也意味着复杂故障仍需要在用户明确同意后检查本地 Harness 日志。