 调研与学习方案)
调研依据本机安装的deepseek-ai/dsh0.1.2-rc.1checkout:D:\app\nvm\v24.16.0\node_modules\deepseek-ai\dsh、DSH_HOMEC:\Users\BingerLiang\.dsh真实配置、plugin_check内置校验规则。结论全部可在本机复核附证据路径。一、用了哪些开源框架1.1 自研核心同属 monorepogithub.com/deepseek-ai/deepseek-harness包版本定位deepseek-ai/cordis4.0.2“Meta-Framework for Modern JavaScript Applications”。TypeScript 插件框架DI 容器Context、服务Service、生命周期Fiberdispose 时自动清理副作用/事件/服务、事件、inject声明式依赖、配置驱动加载cordis-plugin-loader1.0.3运行时插件树 Loader把 YAML 配置变成挂载的插件树cordis-plugin-include/-group/-hmr/-timer—YAML include、嵌套隔离域isolate realm、热替换、定时器管理deepseek-ai/schemastery3.18.x类型驱动 schema 校验器轻量、可序列化、支持 union/intersect/transform、兼容 Standard Schema~standard。配置校验 工具参数 schema 的底座deepseek-ai/cosmokit1.8.x通用工具库作者 shigma 的公开库deepseek-ai/dsh-*0.1.2-rc.1约 230 个功能包全部是 cordis 插件本机dsh\node_modules\deepseek-ai\下可见全量清单1.2 关键第三方依赖dsh\node_modules顶层可验证类别依赖用在哪Web 服务hono、expressexpress-rate-limitdsh-host-webserver知道路由注册不知道 harness 概念的纯 web 插件Web GUIreact、lexical富文本、xterm终端、tanstack、preact、clsx浏览器客户端 UIdsh-client-ui-*约 40 个包协议modelcontextprotocol/sdk、agentclientprotocol/sdkZed 的 ACP、dsh-sdk-protocolNDJSON-RPC over stdioMCP 桥接、自动化 ACP 服务器、进程外 SDKLLMearendil-works/*pi-ai 多 provider 生态、openai、anthropic-ai、gaxios/google-auth-library、aws-sdkdsh-llm-pi-ai多 provider 孪生适配器、dsh-llm-deepseek原生适配器可观测性opentelemetryOTLP 遥测默认 FEEDBACK_ONLY用户 /feedback 才上传沙箱node-addon-api/koffi原生层node-addon-landlock-runLinux Landlock、dsh-sandbox-windows-aclWindows 受限令牌 capability-SID 写白名单、node-pty文件/进程沙箱、持久终端Schemazod、ajv、typebox、zod-to-json-schema客户端侧校验与互转与 schemastery 分工文件监听chokidarskills 热加载、patch 热加载其他commanderCLI、js-yaml配置、wsWebSocket、turndownHTML→MD、sharp图片各处二、一切是插件的机制拆解2.1 五层结构自底向上┌─────────────────────────────────────────────────────────────────┐ │ 5. Hub / Marketnpm 包 GitHub 直装github:user/repo#sha │ │ 第三方插件dsh-email、dsh-memento、liustack/modsearch、 │ │ changfenhuang/dsh-genui、dshmarket、dsh-editor … │ ├─────────────────────────────────────────────────────────────────┤ │ 4. Profile$DSH_HOME/profiles/name 一个 pnpm 工程 │ │ package.json: dsh.profile.bundles [有序 bundle 栈] │ │ 内置 profileweb / headless / acp / sdk / sdk-minimal │ │ dsh plugin --profile X add pkg → 转发 pnpm add │ ├─────────────────────────────────────────────────────────────────┤ │ 3. Patch 层last-write-wins按 row id 覆盖 │ │ 根 cordis.yml([]) ← 各 bundle 的 cordis.patch.yml │ │ ← profile 用户层 ← $DSH_HOME/cordis.patch.yml ← --patch 叠加 │ │ 补丁整体替换目标行 config不深合并支持 !!js 运行时表达式 │ ├─────────────────────────────────────────────────────────────────┤ │ 2. Row行{ id, name(npm包), config?, disabled? } │ │ 整个应用 一份 YAML 行列表。行顺序无语义—— │ │ 激活由服务可用性驱动inject 的服务齐了就挂载 │ ├─────────────────────────────────────────────────────────────────┤ │ 1. Cordis Context根 DI 容器。所有能力都是 ctx 上的服务或插件 │ │ ctx.tools / ctx.llm / ctx.fs / ctx.session / ctx.skills / │ │ ctx.sandbox / ctx.approval / ctx.settings / ctx.subagents … │ └─────────────────────────────────────────────────────────────────┘2.2 核心机制逐条证据路径应用 空根 补丁叠加证据profiles\web\cordis.yml内容就是[]注释写明 “Edit cordis.patch.yml, not this file”。dsh-base\cordis.patch.yml498 行 base 层插入的 ~50 个 rowllm 适配器、session、存储、沙箱、审批、全部工具、命令、plan-mode 提示词、token-meter、compaction、subagent 双 provider、workflow、ralph、遥测……连系统提示词都是插件system-prompt行persona配置、plan-mode行整段 plan-mode 行为规则是 YAML 里的字符串。Seam接口包/ 实现分离接口包dsh-fs、dsh-llm、dsh-tools、dsh-session、dsh-sandbox、dsh-sandbox-policy、dsh-user-approval、dsh-attachment、dsh-storage、dsh-subagent、dsh-skill、dsh-settings。实现包dsh-fs-local/dsh-fs-sandbox、dsh-llm-deepseek/dsh-llm-pi-ai/dsh-llm-mock-server/dsh-llm-replay、dsh-session-persistence-jsonl/dsh-session-query-sqlite、dsh-skill-filesystem……证据dsh-tool-fs\package.json的 peerDependencies 全部指向接口包——工具只依赖 seam不依赖实现。多平台就是这么来的tool-bash行带disabled: !!js process.platform win32Windows 上自动换成 pwsh 双生子。工具管线dsh-toolsdefineTool类型化参数/输出 schemaschemastery DSL16 层容器类型推断注册进ctx.tools后 schema 自动进入提示词组装。固定执行管线tools/pre-executeallow/deny/ask 瀑布可多插件介入→ 单调 guard一旦拒绝不可逆转→tools/executearound超时/重试→tools/post-execute检查/替换结果→finalizeContent→tools/result只读观察。呈现模式native原生 function calling/ptc只给run_code 生成的 TS/Python SDK/both。Skills轻量级插件纯 Markdown格式name/SKILL.md或扁平name.mdYAML frontmattername/description/whenToUse/disable-model-invocation/user-invocable。发现根按 rank项目.dsh/skills(100) → 项目.agents/skills(200) → 自定义(300) →~/.dsh/skills(400) →~/.agents/skills(500) → bundled(600)。chokidar 热加载新增/改名/删除技能无需重启正文每次加载重读catalog 与 body 生命周期分离。证据dsh-skill-filesystem\README.mdDSH_HOME\skills\目录。双半部插件host/client dual-halfdsh-cordis-host-runnerhost 半部沙箱生命周期dsh-cordis-client-runner浏览器半部事件订阅、loader 条目。这就是 Web GUI 里dsh-client-ui-*约 40 个 UI 插件chat、sidebar、settings、theme、tool 卡片渲染器……能随插件安装/卸载的机制。registry 形态的dsh.plugin.json里有client.mainclient.inject字段与之对应。Typert类型化远程协议dsh-typert-protocolcompiler-independent 反射/提供者协议dsh-typert-registry生成包反射 Zod schema 的运行时注册表dsh-api-gatewayRemote Host 分发器 客户端 API 端点。效果浏览器客户端与 host 之间是由包反射生成的类型化 RPC而不是手写 API。事件溯源 快照回放dsh-session 事件溯源会话存储JSONL.zstd 落盘见$env:DSH_SESSION_JSONLcordis.snapshot.yml记录启动时的精确组合树replay 模式直接启动快照 → 会话可确定性复现配dsh-llm-replay。热加载与故障显式化web profilepatchReload: live用户 patch 文件被监听合法编辑免重启重组合cordis-plugin-hmr做代码热替换client-plugin HMR 需要 dev watcher 配合。fail-loud启动失败永远是一行带标签的诊断点名失败的插件 阶段--dump-config可预览组合结果带来源注释。插件形态plugin_check schema输出的官方分类形态特征bundlenpm 包 dsh.bundle.patch声明 cordis.patch.yml声明式配置层无代码入口要求tool-bundlebundle src/index.ts/tsconfig/build 产物带代码的插件构建纪律最严registrydsh.plugin.json清单id/version/main/client.main/client.inject/engines.dsh(semver)/contributes.tools/contributes.skillscollection多插件集合skill纯 Markdown 技能沙箱与审批今天亲身踩到的sandbox-policyrowmoderead-only / workspace-write / danger-full-accessworkspaceRoot审批策略 row 与沙箱 mode 联动danger-full-access → never 询问。Windows 实现dsh-sandbox-windows-acl 受限令牌子进程 capability-SID 写白名单。本机实证profiles\web\cordis.patch.yml里用户层把workspaceRoot钉到D:\给 dsh-editor 的 host 侧写文件 RPC 放行并禁用了better-sidebar。2.3 设计理念小结配置即组合代码即补丁bundle 本质是静态补丁文档不挂服务、不发事件、无状态产品面web/headless/acp/sdk 同一启动器 不同 bundle 栈。核心 README 明说 “this package is not a library you import”。声明式 全程可审计--dump-config输出一棵带来源注释的组合树谁改了哪一行一目了然。服务可用性驱动激活row 顺序无语义inject决定挂载时机 → 天然解耦、无循环依赖焦虑。模型感知工程每个包 README 都有 “Model Experience” “KV Cache effect” 章节——每个包都文档化自己如何影响模型可见的请求前缀前缀稳定 KV cache 命中。这是少见的、把 LLM 推理经济学写进包约定的工程纪律。文档即接口统一 README 结构Summary / Use this package / Understand the implementation(含 source map) / Further Exploration / Model Experience / Known Limitations / Dev Note中英双语README 之间互相交叉引用monorepo 还有.agents/notes架构决策记录。生态开放第三方插件直接作为 pnpm 依赖含 GitHub 直装进 profiledsh-plugin-check提供官方 lint47 条检查规则dshmarket.dsh-market/提供发现层。三、学习方案约 2.5 周可压缩到 1 周核心路径Phase 0 — 环境侦察0.5 天目标建立看得见的全局地图。跑dsh --dump-config和dsh --dump-default-config对照阅读输出里的来源注释。浏览C:\Users\BingerLiang\.dshprofiles\web\package.json cordis.yml cordis.patch.yml .dsh-market、skills\、settings.yaml、sessions\JSONL.zstd、storages\。DoD能徒手画出 2.1 的五层图并说出我现在这个 web 会话由哪 20 个 bundle 组成。Phase 1 — Cordis 核心1–2 天目标吃透插件宿主本身。读cordis\README.mdQuick Start 就是最小例子monorepo 文档若有访问权docs/tutorials/build-a-plugin.md、docs/guides/plugin-lifecycle.md、docs/guides/loader-config.md、docs/api/core.md。写一个玩具一个CounterService 一个注入它的函数式插件照抄 README Quick Start再手动dispose观察副作用清理。理解Context/Service/Fiber/inject/ 事件四件套以及 YAML → 插件树的 Loader。DoD能解释 “Fiber dispose 时哪些东西会被移除”能用!!js标签写配置表达式。Phase 2 — DSH 组合模型 动手2–3 天★核心目标会组合而不是只会读。读dsh-base\cordis.patch.yml注释极其详尽逐行读、dsh-base\README.md、dsh-app-boot\README.mdprofile 章节。动手建自定义 profilepackage.json里dsh.profile.bundles: [deepseek-ai/dsh-base]跑dsh --profile my hello。在my的cordis.patch.yml里禁用一个 row如hmr、整体替换一个 row 的 config体会不深合并、insert 一个新 row。用--dump-config对比改前改后的组合树。装一个第三方插件dsh plugin --profile my add dsh-email或任意 hub 包观察 node_modules 与组合树变化。DoD独立完成改默认模型 / 换权限模式 / 增删工具三类定制全部只动 YAML 或装包。Phase 3 — Seams 与服务面2–3 天目标建立ctx.*地图理解 seam/实现分离。读接口包 READMEdsh-fs、dsh-llm、dsh-tools、dsh-session、dsh-sandbox、dsh-user-approval、dsh-subagent、dsh-skill、dsh-storage、dsh-settings。对照实现包各读一个dsh-fs-sandboxfencing 怎么做到、dsh-llm-pi-aidormant 挂载、settings 驱动激活的懒激活模式、dsh-session-persistence-jsonl、dsh-skill-filesystem。读dsh-llm-mock-server/dsh-llm-replay/dsh-llm-retry测试与回放是怎么靠 seam 换实现的。DoD画出一张 “ctx 服务 → 接口包 → 默认实现 → 可替换实现” 的表能回答加一个第二文件系统 provider 为什么会 fail load双注册。Phase 4 — 工具系统写一个自己的工具插件1–2 天★动手高潮目标产出第一个可安装的 dsh 插件。读dsh-tools\README.md全文尤其 pipeline 与 defineTool 示例、dsh-tool-fs的lib/结构最小工具包长什么样。动手按tool-bundle形态做一个插件src/index.ts里defineTool注册一个工具如list_workspace参数用 schemastery DSLexecute里走ctx.fs走 seam不要直接 node:fstsconfig/main/files 按plugin_check的 tool-bundle 检查项配置用plugin_check工具actioncheck跑官方 lint 直到全绿装进 profile验证工具出现在模型工具列表、管线事件pre/post-execute能挂。DoDplugin_check0 error工具在 web GUI 会话里可被模型调用。Phase 5 — Skills 与提示词层0.5–1 天读dsh-skill-filesystem\README.md已很完整、dsh-system-prompt、dsh-plan-mode看 plan-mode 规则如何作为 YAML 字符串注入、dsh-agent-instructionsAGENTS.md 机制。动手在D:\ai\llmproxy\.dsh\skills\写一个 SKILL.mdfrontmatter 五字段 正文观察热加载进 catalog再试user-invocable/disable-model-invocation两种表面开关。DoD能说清 catalog 与 body 的双生命周期以及 skill 与 plugin 的分工文本指令 vs 代码能力。Phase 6 — Web / 双半部2–3 天读dsh-web-appweb patch 层 前端 dist 服务、dsh-host-webserver纯路由注册 seam、dsh-client-connection浏览器认证 RPC、dsh-cordis-host-runner/dsh-cordis-client-runner双半部、dsh-agent-tool-presentation工具卡片渲染决策。动手装/看一个dsh-client-ui-*插件本机已有changfenhuang/dsh-genui即 GenUI 组件理解client.inject如何把 UI 注入会话观察 HMR 条件client-plugin 需要 dev watcher 同时跑。DoD能解释一个 UI 插件从 npm 安装到出现在 GUI 里的完整链路pnpm → bundle patch → host runner → client runner → 组件挂载。Phase 7 — 进阶专题按兴趣各 0.5–1 天typertdsh-typert-protocol/-registry/dsh-api-gateway—— 包反射生成类型化远程 API 的机制。SDK/ACP/MCPdsh-sdk-protocolNDJSON-RPC stdio、dsh-acp自动化驱动、dsh-mcp-clientMCP 服务器工具桥接进 ctx.tools。子代理体系dsh-subagentseam spawn/forkin-process provider dsh-workflow-worker-thread ralph/goal 工具行对应 base patch 里的配置行。上下文工程dsh-compaction-*、dsh-token-meter、dsh-spill-*大输出落盘、dsh-repeat-tool-reminder、dsh-agent-tool-presentation—— 围绕 KV cache 稳定性的一组设计。安全纵深dsh-sandbox-policy预设联动、dsh-sandbox-windows-acl受限令牌、dsh-fs-observation-policy、dsh-user-approval、dsh-credentials-local凭证不物化进环境变量。回放cordis.snapshot.ymldsh-llm-replaydsh-session-query-sqlite。学习资源索引本机即可资源路径CLI 启动器151 行带详尽注释...\dsh\lib\bin.jsbase 层全量 row 逐行注释...\dsh-base\cordis.patch.yml各包 README中英双语、交叉引用...\node_modules\deepseek-ai\dsh\node_modules\deepseek-ai\pkg\README.md真实 profile含第三方插件栈C:\Users\BingerLiang\.dsh\profiles\web\package.json用户层补丁沙箱根钉扎实例C:\Users\BingerLiang\.dsh\profiles\web\cordis.patch.yml插件形态 lint47 条规则plugin_check工具actionschema组合树预览dsh --dump-config/--dump-default-configmonorepo文档/决策记录访问权限待确认github.com/deepseek-ai/deepseek-harnessdocs/cordis-primer.md、docs/config-catalog.md、.agents/notes/里程碑交付物建议my自定义 profile 3 类 YAML 定制Phase 2一个通过plugin_check全绿的自研 tool-bundle 插件Phase 4一个自研 skillPhase 5一篇从 npm 到 GUI的插件生命周期笔记Phase 6本文档的更新把你验证过的细节回填到第二部分
DeepSeek Harness (dsh) 调研与学习方案
调研依据本机安装的deepseek-ai/dsh0.1.2-rc.1checkout:D:\app\nvm\v24.16.0\node_modules\deepseek-ai\dsh、DSH_HOMEC:\Users\BingerLiang\.dsh真实配置、plugin_check内置校验规则。结论全部可在本机复核附证据路径。一、用了哪些开源框架1.1 自研核心同属 monorepogithub.com/deepseek-ai/deepseek-harness包版本定位deepseek-ai/cordis4.0.2“Meta-Framework for Modern JavaScript Applications”。TypeScript 插件框架DI 容器Context、服务Service、生命周期Fiberdispose 时自动清理副作用/事件/服务、事件、inject声明式依赖、配置驱动加载cordis-plugin-loader1.0.3运行时插件树 Loader把 YAML 配置变成挂载的插件树cordis-plugin-include/-group/-hmr/-timer—YAML include、嵌套隔离域isolate realm、热替换、定时器管理deepseek-ai/schemastery3.18.x类型驱动 schema 校验器轻量、可序列化、支持 union/intersect/transform、兼容 Standard Schema~standard。配置校验 工具参数 schema 的底座deepseek-ai/cosmokit1.8.x通用工具库作者 shigma 的公开库deepseek-ai/dsh-*0.1.2-rc.1约 230 个功能包全部是 cordis 插件本机dsh\node_modules\deepseek-ai\下可见全量清单1.2 关键第三方依赖dsh\node_modules顶层可验证类别依赖用在哪Web 服务hono、expressexpress-rate-limitdsh-host-webserver知道路由注册不知道 harness 概念的纯 web 插件Web GUIreact、lexical富文本、xterm终端、tanstack、preact、clsx浏览器客户端 UIdsh-client-ui-*约 40 个包协议modelcontextprotocol/sdk、agentclientprotocol/sdkZed 的 ACP、dsh-sdk-protocolNDJSON-RPC over stdioMCP 桥接、自动化 ACP 服务器、进程外 SDKLLMearendil-works/*pi-ai 多 provider 生态、openai、anthropic-ai、gaxios/google-auth-library、aws-sdkdsh-llm-pi-ai多 provider 孪生适配器、dsh-llm-deepseek原生适配器可观测性opentelemetryOTLP 遥测默认 FEEDBACK_ONLY用户 /feedback 才上传沙箱node-addon-api/koffi原生层node-addon-landlock-runLinux Landlock、dsh-sandbox-windows-aclWindows 受限令牌 capability-SID 写白名单、node-pty文件/进程沙箱、持久终端Schemazod、ajv、typebox、zod-to-json-schema客户端侧校验与互转与 schemastery 分工文件监听chokidarskills 热加载、patch 热加载其他commanderCLI、js-yaml配置、wsWebSocket、turndownHTML→MD、sharp图片各处二、一切是插件的机制拆解2.1 五层结构自底向上┌─────────────────────────────────────────────────────────────────┐ │ 5. Hub / Marketnpm 包 GitHub 直装github:user/repo#sha │ │ 第三方插件dsh-email、dsh-memento、liustack/modsearch、 │ │ changfenhuang/dsh-genui、dshmarket、dsh-editor … │ ├─────────────────────────────────────────────────────────────────┤ │ 4. Profile$DSH_HOME/profiles/name 一个 pnpm 工程 │ │ package.json: dsh.profile.bundles [有序 bundle 栈] │ │ 内置 profileweb / headless / acp / sdk / sdk-minimal │ │ dsh plugin --profile X add pkg → 转发 pnpm add │ ├─────────────────────────────────────────────────────────────────┤ │ 3. Patch 层last-write-wins按 row id 覆盖 │ │ 根 cordis.yml([]) ← 各 bundle 的 cordis.patch.yml │ │ ← profile 用户层 ← $DSH_HOME/cordis.patch.yml ← --patch 叠加 │ │ 补丁整体替换目标行 config不深合并支持 !!js 运行时表达式 │ ├─────────────────────────────────────────────────────────────────┤ │ 2. Row行{ id, name(npm包), config?, disabled? } │ │ 整个应用 一份 YAML 行列表。行顺序无语义—— │ │ 激活由服务可用性驱动inject 的服务齐了就挂载 │ ├─────────────────────────────────────────────────────────────────┤ │ 1. Cordis Context根 DI 容器。所有能力都是 ctx 上的服务或插件 │ │ ctx.tools / ctx.llm / ctx.fs / ctx.session / ctx.skills / │ │ ctx.sandbox / ctx.approval / ctx.settings / ctx.subagents … │ └─────────────────────────────────────────────────────────────────┘2.2 核心机制逐条证据路径应用 空根 补丁叠加证据profiles\web\cordis.yml内容就是[]注释写明 “Edit cordis.patch.yml, not this file”。dsh-base\cordis.patch.yml498 行 base 层插入的 ~50 个 rowllm 适配器、session、存储、沙箱、审批、全部工具、命令、plan-mode 提示词、token-meter、compaction、subagent 双 provider、workflow、ralph、遥测……连系统提示词都是插件system-prompt行persona配置、plan-mode行整段 plan-mode 行为规则是 YAML 里的字符串。Seam接口包/ 实现分离接口包dsh-fs、dsh-llm、dsh-tools、dsh-session、dsh-sandbox、dsh-sandbox-policy、dsh-user-approval、dsh-attachment、dsh-storage、dsh-subagent、dsh-skill、dsh-settings。实现包dsh-fs-local/dsh-fs-sandbox、dsh-llm-deepseek/dsh-llm-pi-ai/dsh-llm-mock-server/dsh-llm-replay、dsh-session-persistence-jsonl/dsh-session-query-sqlite、dsh-skill-filesystem……证据dsh-tool-fs\package.json的 peerDependencies 全部指向接口包——工具只依赖 seam不依赖实现。多平台就是这么来的tool-bash行带disabled: !!js process.platform win32Windows 上自动换成 pwsh 双生子。工具管线dsh-toolsdefineTool类型化参数/输出 schemaschemastery DSL16 层容器类型推断注册进ctx.tools后 schema 自动进入提示词组装。固定执行管线tools/pre-executeallow/deny/ask 瀑布可多插件介入→ 单调 guard一旦拒绝不可逆转→tools/executearound超时/重试→tools/post-execute检查/替换结果→finalizeContent→tools/result只读观察。呈现模式native原生 function calling/ptc只给run_code 生成的 TS/Python SDK/both。Skills轻量级插件纯 Markdown格式name/SKILL.md或扁平name.mdYAML frontmattername/description/whenToUse/disable-model-invocation/user-invocable。发现根按 rank项目.dsh/skills(100) → 项目.agents/skills(200) → 自定义(300) →~/.dsh/skills(400) →~/.agents/skills(500) → bundled(600)。chokidar 热加载新增/改名/删除技能无需重启正文每次加载重读catalog 与 body 生命周期分离。证据dsh-skill-filesystem\README.mdDSH_HOME\skills\目录。双半部插件host/client dual-halfdsh-cordis-host-runnerhost 半部沙箱生命周期dsh-cordis-client-runner浏览器半部事件订阅、loader 条目。这就是 Web GUI 里dsh-client-ui-*约 40 个 UI 插件chat、sidebar、settings、theme、tool 卡片渲染器……能随插件安装/卸载的机制。registry 形态的dsh.plugin.json里有client.mainclient.inject字段与之对应。Typert类型化远程协议dsh-typert-protocolcompiler-independent 反射/提供者协议dsh-typert-registry生成包反射 Zod schema 的运行时注册表dsh-api-gatewayRemote Host 分发器 客户端 API 端点。效果浏览器客户端与 host 之间是由包反射生成的类型化 RPC而不是手写 API。事件溯源 快照回放dsh-session 事件溯源会话存储JSONL.zstd 落盘见$env:DSH_SESSION_JSONLcordis.snapshot.yml记录启动时的精确组合树replay 模式直接启动快照 → 会话可确定性复现配dsh-llm-replay。热加载与故障显式化web profilepatchReload: live用户 patch 文件被监听合法编辑免重启重组合cordis-plugin-hmr做代码热替换client-plugin HMR 需要 dev watcher 配合。fail-loud启动失败永远是一行带标签的诊断点名失败的插件 阶段--dump-config可预览组合结果带来源注释。插件形态plugin_check schema输出的官方分类形态特征bundlenpm 包 dsh.bundle.patch声明 cordis.patch.yml声明式配置层无代码入口要求tool-bundlebundle src/index.ts/tsconfig/build 产物带代码的插件构建纪律最严registrydsh.plugin.json清单id/version/main/client.main/client.inject/engines.dsh(semver)/contributes.tools/contributes.skillscollection多插件集合skill纯 Markdown 技能沙箱与审批今天亲身踩到的sandbox-policyrowmoderead-only / workspace-write / danger-full-accessworkspaceRoot审批策略 row 与沙箱 mode 联动danger-full-access → never 询问。Windows 实现dsh-sandbox-windows-acl 受限令牌子进程 capability-SID 写白名单。本机实证profiles\web\cordis.patch.yml里用户层把workspaceRoot钉到D:\给 dsh-editor 的 host 侧写文件 RPC 放行并禁用了better-sidebar。2.3 设计理念小结配置即组合代码即补丁bundle 本质是静态补丁文档不挂服务、不发事件、无状态产品面web/headless/acp/sdk 同一启动器 不同 bundle 栈。核心 README 明说 “this package is not a library you import”。声明式 全程可审计--dump-config输出一棵带来源注释的组合树谁改了哪一行一目了然。服务可用性驱动激活row 顺序无语义inject决定挂载时机 → 天然解耦、无循环依赖焦虑。模型感知工程每个包 README 都有 “Model Experience” “KV Cache effect” 章节——每个包都文档化自己如何影响模型可见的请求前缀前缀稳定 KV cache 命中。这是少见的、把 LLM 推理经济学写进包约定的工程纪律。文档即接口统一 README 结构Summary / Use this package / Understand the implementation(含 source map) / Further Exploration / Model Experience / Known Limitations / Dev Note中英双语README 之间互相交叉引用monorepo 还有.agents/notes架构决策记录。生态开放第三方插件直接作为 pnpm 依赖含 GitHub 直装进 profiledsh-plugin-check提供官方 lint47 条检查规则dshmarket.dsh-market/提供发现层。三、学习方案约 2.5 周可压缩到 1 周核心路径Phase 0 — 环境侦察0.5 天目标建立看得见的全局地图。跑dsh --dump-config和dsh --dump-default-config对照阅读输出里的来源注释。浏览C:\Users\BingerLiang\.dshprofiles\web\package.json cordis.yml cordis.patch.yml .dsh-market、skills\、settings.yaml、sessions\JSONL.zstd、storages\。DoD能徒手画出 2.1 的五层图并说出我现在这个 web 会话由哪 20 个 bundle 组成。Phase 1 — Cordis 核心1–2 天目标吃透插件宿主本身。读cordis\README.mdQuick Start 就是最小例子monorepo 文档若有访问权docs/tutorials/build-a-plugin.md、docs/guides/plugin-lifecycle.md、docs/guides/loader-config.md、docs/api/core.md。写一个玩具一个CounterService 一个注入它的函数式插件照抄 README Quick Start再手动dispose观察副作用清理。理解Context/Service/Fiber/inject/ 事件四件套以及 YAML → 插件树的 Loader。DoD能解释 “Fiber dispose 时哪些东西会被移除”能用!!js标签写配置表达式。Phase 2 — DSH 组合模型 动手2–3 天★核心目标会组合而不是只会读。读dsh-base\cordis.patch.yml注释极其详尽逐行读、dsh-base\README.md、dsh-app-boot\README.mdprofile 章节。动手建自定义 profilepackage.json里dsh.profile.bundles: [deepseek-ai/dsh-base]跑dsh --profile my hello。在my的cordis.patch.yml里禁用一个 row如hmr、整体替换一个 row 的 config体会不深合并、insert 一个新 row。用--dump-config对比改前改后的组合树。装一个第三方插件dsh plugin --profile my add dsh-email或任意 hub 包观察 node_modules 与组合树变化。DoD独立完成改默认模型 / 换权限模式 / 增删工具三类定制全部只动 YAML 或装包。Phase 3 — Seams 与服务面2–3 天目标建立ctx.*地图理解 seam/实现分离。读接口包 READMEdsh-fs、dsh-llm、dsh-tools、dsh-session、dsh-sandbox、dsh-user-approval、dsh-subagent、dsh-skill、dsh-storage、dsh-settings。对照实现包各读一个dsh-fs-sandboxfencing 怎么做到、dsh-llm-pi-aidormant 挂载、settings 驱动激活的懒激活模式、dsh-session-persistence-jsonl、dsh-skill-filesystem。读dsh-llm-mock-server/dsh-llm-replay/dsh-llm-retry测试与回放是怎么靠 seam 换实现的。DoD画出一张 “ctx 服务 → 接口包 → 默认实现 → 可替换实现” 的表能回答加一个第二文件系统 provider 为什么会 fail load双注册。Phase 4 — 工具系统写一个自己的工具插件1–2 天★动手高潮目标产出第一个可安装的 dsh 插件。读dsh-tools\README.md全文尤其 pipeline 与 defineTool 示例、dsh-tool-fs的lib/结构最小工具包长什么样。动手按tool-bundle形态做一个插件src/index.ts里defineTool注册一个工具如list_workspace参数用 schemastery DSLexecute里走ctx.fs走 seam不要直接 node:fstsconfig/main/files 按plugin_check的 tool-bundle 检查项配置用plugin_check工具actioncheck跑官方 lint 直到全绿装进 profile验证工具出现在模型工具列表、管线事件pre/post-execute能挂。DoDplugin_check0 error工具在 web GUI 会话里可被模型调用。Phase 5 — Skills 与提示词层0.5–1 天读dsh-skill-filesystem\README.md已很完整、dsh-system-prompt、dsh-plan-mode看 plan-mode 规则如何作为 YAML 字符串注入、dsh-agent-instructionsAGENTS.md 机制。动手在D:\ai\llmproxy\.dsh\skills\写一个 SKILL.mdfrontmatter 五字段 正文观察热加载进 catalog再试user-invocable/disable-model-invocation两种表面开关。DoD能说清 catalog 与 body 的双生命周期以及 skill 与 plugin 的分工文本指令 vs 代码能力。Phase 6 — Web / 双半部2–3 天读dsh-web-appweb patch 层 前端 dist 服务、dsh-host-webserver纯路由注册 seam、dsh-client-connection浏览器认证 RPC、dsh-cordis-host-runner/dsh-cordis-client-runner双半部、dsh-agent-tool-presentation工具卡片渲染决策。动手装/看一个dsh-client-ui-*插件本机已有changfenhuang/dsh-genui即 GenUI 组件理解client.inject如何把 UI 注入会话观察 HMR 条件client-plugin 需要 dev watcher 同时跑。DoD能解释一个 UI 插件从 npm 安装到出现在 GUI 里的完整链路pnpm → bundle patch → host runner → client runner → 组件挂载。Phase 7 — 进阶专题按兴趣各 0.5–1 天typertdsh-typert-protocol/-registry/dsh-api-gateway—— 包反射生成类型化远程 API 的机制。SDK/ACP/MCPdsh-sdk-protocolNDJSON-RPC stdio、dsh-acp自动化驱动、dsh-mcp-clientMCP 服务器工具桥接进 ctx.tools。子代理体系dsh-subagentseam spawn/forkin-process provider dsh-workflow-worker-thread ralph/goal 工具行对应 base patch 里的配置行。上下文工程dsh-compaction-*、dsh-token-meter、dsh-spill-*大输出落盘、dsh-repeat-tool-reminder、dsh-agent-tool-presentation—— 围绕 KV cache 稳定性的一组设计。安全纵深dsh-sandbox-policy预设联动、dsh-sandbox-windows-acl受限令牌、dsh-fs-observation-policy、dsh-user-approval、dsh-credentials-local凭证不物化进环境变量。回放cordis.snapshot.ymldsh-llm-replaydsh-session-query-sqlite。学习资源索引本机即可资源路径CLI 启动器151 行带详尽注释...\dsh\lib\bin.jsbase 层全量 row 逐行注释...\dsh-base\cordis.patch.yml各包 README中英双语、交叉引用...\node_modules\deepseek-ai\dsh\node_modules\deepseek-ai\pkg\README.md真实 profile含第三方插件栈C:\Users\BingerLiang\.dsh\profiles\web\package.json用户层补丁沙箱根钉扎实例C:\Users\BingerLiang\.dsh\profiles\web\cordis.patch.yml插件形态 lint47 条规则plugin_check工具actionschema组合树预览dsh --dump-config/--dump-default-configmonorepo文档/决策记录访问权限待确认github.com/deepseek-ai/deepseek-harnessdocs/cordis-primer.md、docs/config-catalog.md、.agents/notes/里程碑交付物建议my自定义 profile 3 类 YAML 定制Phase 2一个通过plugin_check全绿的自研 tool-bundle 插件Phase 4一个自研 skillPhase 5一篇从 npm 到 GUI的插件生命周期笔记Phase 6本文档的更新把你验证过的细节回填到第二部分
