monotykamary/dsh-fabric

🧵 dsh-fabric

为 DeepSeek Harness 提供 Fabric 风格的能力

_确定性压缩、受检代码执行、持久化协调与实时拓扑 —— 以原生 DSH 插件的形式交付。_

checks
DeepSeek Harness
TypeScript
license

dsh-fabric 将 pi-fabric 中最有用的理念移植到 DeepSeek Harness，而不会创建一套并行的运行时。DSH ToolRuntime 仍然是工具与策略的权威，Cordis 负责组件生命周期，而 Fabric 则为压缩、代码执行、协调、投影和浏览器 UI 添加了专注的提供者。

为什么选择 Fabric？

| | 能力 | 它能带来什么 |
| :-: | --- | --- |
| 🧠 | 确定性压缩 | 结构化、有界的摘要，无需第二次模型请求。 |
| ⚡ | 受检代码模式 | 先进行 TypeScript 校验，随后在严格预算下进行隔离的 QuickJS 执行。 |
| 🏎️ | 推测式 PTC | 当 run_code 仍在流式传输时，字面量的 read、glob 和 grep 调用就已启动，然后仅在自然策略关口处提交。 |
| 🕸️ | 持久化网格 | 主题、比较并交换（compare-and-swap）状态，以及崩溃保守型 actor 邮箱。 |
| 📡 | 统一活动视图 | 将 Fabric、工作流和压缩事件投影到同一个按时间顺序排列的界面中。 |
| 🗺️ | 实时拓扑 | 可移植的参与者和网格资源以分组树的形式呈现，消息流则保留为流量叠加层。 |
| 🧩 | 原生组合 | 外部 DSH 插件 —— 没有第二套工具注册表、生命周期或 React 业务状态存储。 |

它如何融入

flowchart LR
Model[Model] --> TR[DSH ToolRuntime]
TR --> QJS[Checked QuickJS]
TR --> Mesh[Fabric Mesh]
Mesh --> Store[(storage-domain)]
DSH[DSH events] --> Host[Fabric host projection]
Mesh --> Host
Host --> UI[Activity + Topology UI]
Compiler[Deterministic compiler] --> Compact[DSH compaction transaction]
DSH --> Compiler
可安装的工作区捆绑包会遮蔽继承的代码运行时、原装压缩器/修剪器以及随附的预设清单。随后，它会在八个组合行下挂载 Fabric 的 QuickJS 提供程序、确定性压缩引擎、Fabric 拥有的预设、网格提供程序、宿主投影以及客户端界面。Fabric 网格 Consumer、fabric_models Consumer 以及 Fabric 系统提示覆盖层并非宿主行：它们挂载在 fabric 预设自身内部，因此其提示界面保持 fabric 作用域，不会触及任何其他预设的系统提示。Fabric 拥有的清单保留四个固定的 DSH 模式，并新增第五个模式 fabric：Fabric 模式在其自身的预设身份下使用 Code Mode SDK，并选择 runCodeLabel: inferred，因此 code 是唯一必需的外部参数，显式描述仍然优先，否则一个从所记录程序派生的确定性标题将服务于调用卡片和压缩。Fabric 会话会以 Fabric 模式记录和显示，而不是复用 PTC 模式。

包

| 包 | 职责 |
| --- | --- |
| dsh-fabric-protocol | 与宿主无关的参与者、活动、拓扑、网格和 actor 记录。 |
| dsh-fabric-compaction | 确定性摘要编译器、DSH CompactionEngine 以及被遮蔽的预设清单。 |
| dsh-fabric-host | 持久事件适配器和有界会话投影。 |
| dsh-fabric-system-prompt | Fabric 拥有的系统提示覆盖和原生散文最小化。 |

| dsh-fabric-mesh | 主题、CAS 状态、actor 邮箱以及 fabric_mesh Consumer。 |
| dsh-fabric-models | 通过 fabric_models Consumer 进行会话模型检查和别名感知切换。 |
| dsh-fabric-schema | 模式强制的世界状态和根作用域认证：精确观察允许列表、对所有 ToolRuntime 效果的故障关闭式遏制，以及同一 run_code 假设 → 证书 → 原子提交事务，支持 enforce/audit 模式。 |
| dsh-fabric-code-runtime-quickjs | 带执行预算的受检查 QuickJS CodeRuntime 提供程序。 |
| dsh-fabric-client-ui | 浏览器 Activity、Topology、弹出指标、子代理导航以及持久的 Schema/speculation 设置卡片。 |

安装

要求：Node.js ^22.19.0 || >=24、Bun 1.4+ 以及 DSH 0.1.0-rc.7。

克隆仓库并将其安装到本地 DSH web 配置文件中：

git clone https://github.com/monotykamary/dsh-fabric.git
cd dsh-fabric
bun install
bun run install:local

安装程序会构建所有包，链接捆绑包及其九个包，并验证组合后的插件图。它不会启动或重启 DSH。插件图会在下次配置文件加载时生效。

配置文件、自定义 DSH 主目录以及卸载

Target another profile
bun run install:local -- --profile tui

指定另一个 DSH 主目录
DSH_HOME=/path/to/dsh-home bun run install:local -- --profile web

复用现有构建输出
bun run install:local -- --skip-build

恢复安装前存在的确切依赖规范
bun run uninstall:local

卸载时使用相同的 --profile 或 DSH_HOME 选择。如果没有其所有权状态文件，卸载程序会拒绝移除软件包，除非此检出目录的确切本地链接能证明所有权。

系统提示词与 DSH 掩码

安装该捆绑包会将冗长的原生 DSH 提示词文本替换为精简的 Fabric 操作提示词：

- 一个 fabric:system-prompt 段（紧接在 persona 之后）捕获 pi-fabric 的长周期准则，并向模型提供确切的一次性 tools.subagent({ description, prompt, provider, model }) 配方、后台优先的可续接生命周期，以及全新与分叉的选择。
- 一个 system-prompt/assemble 瀑布监听器会丢弃冗余的原生逐工具指导，同时保留 persona、受信任的 user:system-instructions、计划策略、报告、Code-Mode SDK/collapse 段、记忆和网格指导。精简后的 SDK 保留完整核心契约，将可选 schema 替换为仅含名称的 JSON 名册，并保留 DSH ToolRuntime 的运行作用域 tools.describe/tools.call 声明以实现精确发现。
- DSH 的待办账本和目标系统（todo_write、create_goal/get_goal/update_goal、/goal、目标轮次驱动器以及目标栏）被掩蔽。长周期目标和进度应放在 fabric_mesh 中，而不是同一会话的待办/目标记录中。
- Fabric 记忆/召回在持久化 SQLite FTS5 索引之上组合 DSH 的原生会话查询工具（session_search、session_event_search，以及 session_trace/session_event_trace/session_event_read 读取器），并通过 fabric:memory-guidance 提示词指导在 /compact 之后重新建立已丢弃的上下文。
- standard、code、fabric 和 cordis 预设通过普通斜杠命令 UI 暴露 /delegate [--provider  --model ] [--fork] ，启动一个后台子进程而无需父模型轮次。

推测性 Code Mode

Fabric 启用 DSH ToolRuntime 的推测性 Code Mode 路径，而 Harness 范围的默认值保持关闭。在流式传输的 TypeScript run_code 参数期间，惰性字面量扫描器会识别参数为静态 JSON 的完整 tools.read(...)、tools.glob(...) 和 tools.grep(...) 调用，并提前启动其定义所拥有的 speculate 回调。动态表达式和 Python 程序仍走权威的自然路径。
预取的工作绝不会绕过策略或写入重复的生命周期记录。定义必须通过 risk: "read"、effectKind: "none" 和 speculate 回调来选择启用。一个不可伪造的流式根所有者可防止复用的提供方调用 ID 跨会话/步骤，并且最终参数必须恰好包含一个与流式程序完全相同的顶层 code 字符串。最终的 SDK 调用仍会经过 DSH 的预执行、守卫、分发前后、执行后、终结以及持久事件管道。定义身份、按所有者的变更纪元、新鲜度、取消以及一次性消费仍然具有权威性。隐藏的文件系统获取被限制在规范会话工作区内；外部目标回退到自然经策略授权的调用。read 会验证观察到的文件版本，并且仅在准入后重放 fs/observed。glob 和 grep 在服务时重新运行其完整获取，并且仅在规范结果未改变时复用输出，而不会提前运行直接调用溢出投影。任何未命中或失效都会执行普通工具主体。

Settings → Plugins 下的 Speculative Code Mode 卡片会编辑实时的 tool-speculation 命名空间：启用、并发工作、保留条目、流缓冲区字节、聚合保留结果字节以及条目 TTL。保存新边界会在应用它们之前取消未提供的隐藏工作。相邻的 Fabric Schema 卡片仍然是新会话 Schema 默认值的持久权威。

fabric_mesh 工具

一个 Consumer 通过紧凑的操作协议暴露持久协调：

| 原语 | 操作 | 保证 |
| --- | --- | --- |
| Topics | create_topic、publish、read_topic、prune_topic | 具有显式保留的存储支持的有序消息。 |
| State | get_state、cas_state | 经修订检查的更新；修订 0 会创建一个不存在的键。 |
| Actors | create_actor、send_actor、read_mailbox | 发往稳定 actor 的持久命令队列。 |
| Claims | claim_actor_message、settle_actor_message | 令牌围栏结算和可重放安全的最终结果。 |
| Discovery | snapshot | 用于重新发现持久协调状态的有界元数据。 |

Actor 声明有意采取崩溃保守策略。已声明的命令在进程失败后仍保持已声明状态，结算需要不透明的声明令牌，并且重试同一结算会返回已存储的结果，而不是执行两次。

Mesh 记录由提示组装和工具执行共享的一个工作区身份隔离：已注册的工作区成员资格或规范路径所有权优先，其次是非注册路径摘要，最后是在不存在 cwd 时的仅会话作用域。

压缩与延续

Fabric 成为唯一组合的压缩后端，同时保留 DSH 的 /compact 命令、持久事务、令牌计量以及与后端无关的不变量。
- 类型化消息和生命周期事件会编译为有界的 Session Goal、Files and Changes、Fabric Activity、Outstanding Context、Earlier Turns、Current Status 以及近期转录片段。
- 推理块会被擦除；工具调用和结果通过精确身份保持配对。
- 每次压缩都会从不可变的源事件引用重建累积事实，而不是递归信任先前检查点的文本；严格快照仍是有界的诊断产物和分离调用方产物。100,000 个事件的遍历上限会以显式省略通知的方式降级，而不是永久导致 /compact 失败。
- Mesh 只贡献有界元数据——绝不贡献任意载荷——因此持久标识符可以在压缩后被重新发现。
- 指导原则要求在压缩或 TOOL_OUTCOME_UNKNOWN 后重新读取持久状态，而不是信任对话记忆。

有关复用矩阵、验收证据和延迟对齐面，请参见 ADAPTATION_SWEEP.md。

客户端界面

Fabric 在“设置 → 插件”下贡献两张双语卡片——Fabric Schema 和 Speculative Code Mode——并添加一个对话标签页，其中包含：

- 按时间顺序展示 agent、workflow、mesh 和压缩事件的 Activity 视图；
- 从左到右的 Topology 树：Main → Participants → {Sessions, Agents, Actors} 和 Main → Mesh → {Topics, State}；
- 用于主题发布、actor 路由和状态访问的虚线流量叠加层，而不是层级中的消息节点；
- 确定性的方向键或 H/J/K/L 导航，并带有焦点感知滚动；
- 原生导航到权威 DSH 会话。

FabricParticipantRecord 是 UI 使用的可移植语义身份。DSH 会话镜像和 Fabric actor 记录仍是生命周期权威；该适配器不会引入第二个执行器、注册表或客户端业务状态存储。Workflow、phase、message 和 compaction 事实仍可在 Activity 中获取，而不会挤占拓扑。

业务状态保留在 DSH 和存储域中。客户端本地状态仅限于视图选择、过滤器、展开和视口状态。

客户端 HMR

热重载需要两个 watcher：

1. 提供 GUI 的 DeepSeek Harness 检出目录运行 bun run dev:web。
2. 此工作区运行 bun run watch:client 以重新构建 packages/client-ui/lib/client.js。

仅运行服务器不会编译此仓库，并且首次安装新的 profile 行需要后续的 profile 加载。

开发

bun install
Optional when co-developing against a sibling ../deepseek-harness checkout
bun run link:harness
bun run check

bun run check 会进行类型检查、构建、测试并验证整个工作区。QuickJS provider 强制实施全新上下文、JSON 桥接验证、截止时间、取消、内存/栈/输出预算以及静默处置。

当前范围

这是一个聚焦于 DSH 的适配，而不是字面意义上的 pi-fabric 对齐。已知限制包括：
- 新的 mesh 活动使用 DSH 原生的 tool/result.meta 和 tool/code-dispatch 事件。只有使用已弃用的必需 fabric/activity 事件编写的旧日志，才与 DSH 0.1.0-rc.6 的静态持久化事件允许列表不兼容。
- 在工作区作用域之前写入的 mesh 记录仍会被存储，但会被有意地对工作区绑定的读取隐藏；自动迁移会猜测一个不明确的目标，因此任何重新键控都必须是显式的操作员操作。
- 当前的 DSH CodeRunRequest 省略了生成的 SDK 声明前导部分，因此 QuickJS 会检查命名空间/成员是否存在以及正常的 TypeScript 语义，而 ToolRuntime 仍然是权威的参数/结果验证器。
- Actor 邮箱提供持久的 claim/settle 语义，而不是一个始终驻留的自主 actor 宿主。
- Fabric 拥有的预设是 DSH 0.1.0-rc.6 的固定适配版本，必须在宿主升级时进行审查。
- Memory/recall 是组合到 fabric 预设中的 DSH 会话查询，而不是 pi-fabric 的分层转录索引：正则查询模式、pi 的 Fabric 操作过滤器以及会话列表浏览工具均未被移植。

致谢

- 为 DeepSeek Harness 构建。
- 改编自 pi-fabric 中的理念和实现经验。

许可证

MIT © Tom Nguyen。参见 THIRD_PARTY_NOTICES.md。