dsh-schematic

同时面向人类与 Agent 的 DeepSeek Harness 控制面。

English · 简体中文

你的 Agent 不是黑盒。它是一张由模型、工具、记忆、安全策略、工作流和服务接线组成的实时网络。人需要看见并塑造它，Agent 也需要安全、结构化地操作它。

dsh-schematic 让人类和 Agent 共用同一套控制面。 人类使用全屏可视化工作区，Agent 通过 dsh 原生工具完成同样的持久化操作；双方共享实时状态、校验规则、变更预览、备份和受保护写入管线。

dsh plugin --profile web add dsh-schematic
dsh web
# 打开 http://127.0.0.1:3080/schematic

一套系统，两类操作者

| 人类操作者 | Agent 操作者 | 共同底座 | | --- | --- | --- | | 可视化探索拓扑、编辑蓝图、编排活动，并逐项审查改动。 | 在对话中通过 schematic_* 工具检查、组合、切换、整理和恢复。 | 同一张运行图、同一组存储、同一套校验与安全边界。 |

界面里每个会持久化的操作，都有对应的模型操作能力。这不是另一套“AI 自动化模式”：人和 Agent 可以随时接力，不需要在两种配置体系之间翻译意图。

三个工作区，回答三个问题

| 工作区 | 它回答什么 | 你可以做什么 | | --- | --- | --- | | 系统 | 我的 Agent 此刻到底由什么组成？ | 浏览实时拓扑或组件清单，检查依赖，配置、启停插件，并替换能力提供方。 | | 蓝图 | 如何让这套组合可复用？ | 按能力组装，自动保存本地草稿，导入/导出 YAML，查看偏离，并安全切换整套插件组合。 | | 活动 | 刚才发生了什么，是谁做的？ | 跟随会话事件与请求 Journey，按自己的理解编排信号分组与主/旁路，过滤噪声并检查失败或耗时。 |

它既是可观测控制台，也是组合工作台：先把系统看明白，再动手改变它。

为什么它不太一样

• 图就是操作界面。 选中节点或接缝就能原地处理，不必在几份互不相干的 YAML 里来回寻宝。
• 活动跟着责任方走。 模型调用、工具执行、工作流、注册表变化和失败都会归因到真正负责的插件。
• 蓝图描述能力，不保存脆弱快照。 保存成员正列表，明确处理后来出现的插件，并单独决定蓝图是否搭载 Schematic。
• 每个危险改动都必须先接受审查。 写入前展示结构警告、成员差异以及受管块的精确 YAML。
• 高压下也保持可读。 事件风暴合并为计数行，内部 service-read 噪声被过滤，动画遵守 prefers-reduced-motion。
• 中英文都是一等公民。 插件描述通过宿主配置的模型路由翻译，标识符始终保持原样。
• 人类操作与 Agent 操作保持对称。 界面和 schematic_* 工具共享计划、校验、确认门槛、备份与陈旧状态保护。

改接线，不靠祈祷

所有写操作都走同一条受保护管线：

选择改动 → 计算差异 → 组合干跑 → 审查警告
        → 备份完整 patch → 原子写入 → 验证热重载
        → 成功，或自动回滚

Schematic 只写当前 profile cordis.patch.yml 中标记清楚的受管块，以及 ~/.dsh/schematic/ 下属于自己的数据。它不会改写 bundle 层、manifest、会话日志或 profile 根配置。待应用期间源文件如果发生变化，写入会立即停止，绝不覆盖。

编辑默认关闭，也可以通过 config.edit.enabled=false 完全禁用。视口窄于 768 px 时三个工作区仍可浏览，但所有写操作都会禁用并解释原因。

经得住现实变化的蓝图

蓝图不是整棵插件树的冻结副本。它记录你想要的可选成员、成员配置、保存时见过的世界，以及是否继续搭载 Schematic。

因此，Harness 升级后蓝图也不会轻易报废：

• 新插件会成为未管理项，必须明确选择保持 / 停用 / 纳入；
• id 改绑或包名变化只会报告，不会暗中修改；
• 成员包缺失时拒绝整次切换，并给出安装命令；
• 受保护核心不进入成员列表，只有专用的 Schematic 搭载开关是明确例外；
• 偏离状态复用切换时的同一份物化计划，因此“当前”真的意味着已经无事可做。

蓝图以可读的 schema-2 YAML 存在 ~/.dsh/schematic/blueprints/。旧 schema-1 预设会幂等迁移，原文件完整保留为只读备份。

Agent 使用的是同一套控制面

启用编辑后，dsh-schematic 会注册覆盖网页持久化操作的模型工具；活动编排工具始终可用：

• schematic_plugins——检查组合树和可用能力；
• schematic_blueprint_list——列出蓝图和当前偏离；
• schematic_blueprint_save / schematic_blueprint_switch——组建、保存、预览、备份并安全切换；
• schematic_blueprint_manage——查看、复制、重命名、更新、导入导出、纳入未管理项或删除；
• schematic_system_compose——查看、预览、应用、回滚或清理当前系统组合变更；
• schematic_activity_layout——通过对话协作编排活动分组、顺序、主/旁路、说明、颜色与插件归属。

于是，“帮我保存一套精简的编程配置，切过去，再按职责整理运行信号”可以是一句对话，而不是一次配置文件考古。Agent 可以先检查、展示与人类界面相同的预览，在必要时请求确认，最后把结果留在界面中供人继续审查。

实时拓扑

• 可缩放、平移、聚类的依赖图，直接读取 loader 正在运行的插件树。
• 拓扑与组件清单共用搜索、能力筛选和状态筛选。
• 上下文面板集中展示状态、能力、依赖、来源、近期活动、配置、提供方替换和蓝图归属。
• 内部 fiber 失败会传导到可见插件单元，系统稳定后自动恢复。
• 输入框旁提供可拖动、缩放的星图，真实 service access 会点亮消费方 → 提供方路径。

运行时活动

• 跟随会话的实时事件、subagent/后台筛选、请求 Journey、历史回放和插件统计。
• 对模型回复、工具调用、工作流、宿主动作、注册表变化、后台任务和失败进行责任归因。
• 计数行合并与尾随归属重建，避免宿主事件突发把观察器本身变成性能热点。

组合工作台

• 在上下文中启停插件、编辑配置、替换接缝提供方。
• 图上幽灵预览、逐条目差异、精确 YAML 行差异和结构感知警告。
• Harness 原生干跑、时间戳备份、原子受管块写入、热重载验证与回滚。
• 亮暗主题、语义化控件、键盘操作、可见焦点、ARIA 与减少动画支持。

环境要求

| 组件 | 支持范围 | | --- | --- | | DeepSeek Harness | >=0.1.0-rc.8，web profile | | @deepseek-ai/cordis | ^4.0.1 | | @deepseek-ai/cordis-plugin-include | ^1.0.6 | | 浏览器 | 当前版本 Chromium、Firefox 或 Safari | | Node.js | 从源码构建时需要 >=22.19；CI 覆盖 Node 22 与 24 |

安装与更新

这个包本身就是 dsh bundle，官方插件命令会同时安装依赖并注册到指定 profile：

# 安装
dsh plugin --profile web add dsh-schematic

# 更新
dsh plugin --profile web update dsh-schematic

# 移除
dsh plugin --profile web remove dsh-schematic

安装后重启 profile，打开 /schematic。设置中还会出现插件拓扑入口，聊天输入框旁也会挂载实时星图。其他 profile 只需替换命令中的 profile 名称。

架构

一个 npm 包里包含互相配合的两部分：

• 宿主插件——读取 Cordis loader 树，订阅运行时活动，提供实时图和 SSE/JSON 接口，注册蓝图工具，并持有受保护的组合写入管线。
• 浏览器应用——独立的「系统 / 蓝图 / 活动」界面，加上设置集成和输入框旁星图。前端不依赖运行时框架，发布 bundle 由 esbuild 构建。

这里画的是依赖注入拓扑，不是数据流。它展示运行中 Cordis 系统稳定后的静态等价结构——也是 Cordis 论文 A Programming Paradigm for Spatiotemporal Composability 中 resting-state 结论的实际界面。

开发

npm install
npm run check

npm run check 会执行 TypeScript 校验、Node 测试和全部生产构建。缺陷报告与 PR 约定见 CONTRIBUTING.md，逐版本历史见 CHANGELOG.zh.md。

路线图

• 接缝感知的供给侧面板：从需要能力的位置发现可用提供方。
• 蓝图成员缺失时的安装交接。
• 更深入的活动查询，但不会把 Schematic 做成对话回放产品。

如果 dsh-schematic 让你的 Agent 更容易理解、调试或信任，欢迎给仓库一个 ⭐。这会帮助更多 DeepSeek Harness 开发者发现它。

许可

MIT