极简插件架构 civaapple-alt/mini-dsh

Mini-DSH：Cordis 极简架构实现与学习指南

本项目是一个极简版（Educational & Minimalist）的 DeepSeek Harness 架构实现，专门用于学习与验证 Cordis 框架的核心设计哲学：“Everything is a plugin”（一切皆插件）。

Mini-DSH Web Shell

📖 推荐必读学习指南：
- 🚀 《从 CLI 启动到浏览器端动态插件加载全流程》：全流程时序图、window.__MINI_BOOT__ 详解、client-shell.js 运作机制与 DSH 源码对标！
- 🛡️ 《Capability Seam（能力接缝）与可移植执行世界深入指南》：Service Definition / Provider / Consumer 三元角色模型与本地/云端沙箱无感切换！
- 🧩 《预设配置体系指南：部署级 Profile vs 会话级 Preset 与 Include & Patch》：Cordis 作用域隔离（ctx.isolate）、多租户会话与全局增量补丁机制！
- 🔥 《Schemastery 配置校验与 HMR 实时热重载指南》：声明式 Schema 校验与文件变更实时热重载！
- 📝 《架构决策记录 (Agent Notes / ADRs)》：包含所有核心架构决策的中英文演进记录。

核心设计概念

1. 统一的插件模型（Cordis Plugin）：
- 所有的功能、服务、API 路由以及前端 UI 组件全部以 Cordis 插件（apply(ctx, config)）形式组织。
- 通过依赖注入（ctx.inject(['server', 'slots'])）实现插件之间的拓扑解耦与延迟挂载。
- 所有的注册与监听都封装在 ctx.effect() 中，支持干净的生命周期管理与销毁（Disposer）。

2. 配置驱动的 Profile 机制：
- 通过 YAML 文件（如 profiles/web.yml、profiles/base.yml）声明启用的插件及其配置参数。
- 切换 Profile 即切换系统能力，无需修改一行代码。

3. 前后端对称的插件组合架构（Host + Client-Web）：
- Host 端（Node.js）：
- 运行 Cordis Context。
- host-webserver 插件提供 ctx.server 基础 HTTP 服务。
- host-client-modules 插件自动扫描已加载插件的 package.json（带有 mini.client 字段），组装 window.__MINI_BOOT__ 启动图，并分发 /plugins/:id/client.js。
- Client 端（浏览器 Web GUI）：
- 在浏览器中运行 Cordis Context。
- client-slots 插件提供 ctx.slots 插槽机制（main.cards、sidebar.widgets）。
- client-shell 动态 import 插件的前端 Bundle，并在浏览器端的 Cordis 中执行 apply(ctx)，将 UI 挂载到对应 Slot。

4. 全栈插件自包含（Full-Stack Plugin）：
- 以 @mini-dsh/plugin-greeter 和 @mini-dsh/plugin-counter 为例：
- src/index.ts：向 Host 提供后端 Service 并挂载 API 路由（如 /api/greet、/api/count）。
- src/client.ts：向 Client 注册前端交互卡片/控件。
- 只需要在 profiles/web.yml 中添加一行插件名称，前后端能力就会全自动装配上线！

项目目录结构

mini-dsh/
├── package.json # 根目录配置与工作区脚本 ├── pnpm-workspace.yaml # pnpm monorepo 配置 ├── tsconfig.base.json # 基础 TypeScript 配置 ├── profiles/ # 【部署级 Profile】：全局基础设施组装 (Web/Base/Local/Sandbox/Goal/HMR) │ ├── base.yml # Headless 模式（仅基础后端插件与任务运行器） │ ├── web.yml # Web GUI 模式（包含 Web 服务与全栈 UI 插件） │ ├── local.yml # 本地执行世界 Profile（LocalExecutor + ToolBash） │ ├── sandbox.yml # 安全沙箱执行世界 Profile（SandboxExecutor + ToolBash） │ ├── presets.yml # 多会话隔离演示 Profile（SessionManager + PresetsDemo） │ ├── goal.yml # 增量补丁 Profile（Include base.yml + Patch Insert Goal 领域） │ └── hmr.yml # 实时热重载与 Schemastery 校验 Profile ├── presets/ # 【会话级 Preset】：用户在每个 Chat 独享的 Agent 预设 │ ├── minimal.yml # 极简模式：仅分配 ToolBash 与精简 Prompt │ └── standard.yml # 标准模式：分配 Greeter + Counter + ToolBash 全套工具 ├── apps/ │ └── cli/ # Host 启动入口 (支持 Include & Patch 动态递归解析与 Schemastery 校验) └── packages/ ├── seams/ # Capability Seams (抽象服务契约层) │ └── executor/ # Executor 契约包 (@mini-dsh/seam-executor) ├── providers/ # Service Providers (具体能力提供方) │ ├── executor-local/ # 本地进程执行提供方 (@mini-dsh/provider-executor-local) │ └── executor-sandbox/ # 远程安全沙箱提供方 (@mini-dsh/provider-executor-sandbox) ├── host/ │ ├── webserver/ # Host HTTP 服务插件 (ctx.server) │ ├── client-modules/ # Client 模块扫描与 Bundle 分发 (ctx.clientModules) │ ├── session-manager/ # 会话管理与 Preset 子上下文隔离 (ctx.sessions) │ └── hmr/ # 热模块替换与配置监听插件 (@mini-dsh/host-hmr) ├── client/ │ ├── slots/ # 浏览器 UI 插槽系统 (ctx.slots) │ └── shell/ # 浏览器 Cordis 引导内核 (AppWebEntry) └── plugins/ ├── greeter/ # 问候服务全栈插件 (导出 Schemastery Config Schema) ├── counter/ # 计数器全栈插件 (后端状态 + 前端组件) ├── tool-bash/ # 面向模型的 Bash 工具插件 (Consumer) ├── task-runner/ # Headless 任务运行器插件 (多步骤工作流编排与事件发射) ├── presets-demo/ # 多会话作用域隔离演示插件 ├── goal/ # 持久化目标状态机领域插件 (@mini-dsh/plugin-goal) ├── tool-goal/ # 面向模型的 Goal 工具插件 (@mini-dsh/plugin-tool-goal) └── hmr-demo/ # HMR 与 Schemastery 演示插件 (@mini-dsh/plugin-hmr-demo)

快速上手与验证

1. 安装依赖与构建 Client Bundle

1. 在 mini-dsh 目录下安装依赖
pnpm install

2. 构建所有前端 Client Bundle 与 TypeScript 产物
pnpm run build

2. 运行 Web GUI 模式

pnpm start
或者指定 profile:
pnpm --filter @mini-dsh/cli start --profile web

在浏览器中打开：http://localhost:3000

- 你将看到浏览器端 Cordis 容器自动激活。
- @mini-dsh/plugin-greeter 自动将问候卡片挂载到 main.cards 插槽，并在点击时请求 Host 的 GET /api/greet。
- @mini-dsh/plugin-counter 自动将计数器组件挂载到 sidebar.widgets 插槽，并在点击时请求 Host 的 POST /api/count。
- 提供 /api/presets 与 /api/sessions/create 接口支持按预设动态创建新会话。

3. 运行 Headless 模式（对标真实 Agent 运行器）

运行 base profile 下的默认多步骤任务
pnpm start:base

或者动态传入自定义任务指令 (模拟 dsh --profile headless "task")
pnpm start:task "Nightly Security Audit and Build"

4. 运行 Include & Patch 全局增量补丁（Goal 领域模式）

完全对标 DeepSeek Harness 的 examples/headless-agent/goal.cordis.yml，在无需复制粘贴 100+ 行配置的情况下，通过 Include + patches.insert 动态叠加 Goal 状态机：

pnpm start:goal

控制台输出： [Include & Patch] 📦 Including base profile: "./base.yml"
[Include & Patch] ➕ [Insert Patch] Injected 2 plugin(s): @mini-dsh/plugin-goal, @mini-dsh/plugin-tool-goal
[Goal Domain] 🎯 Initialized. Persisted goal state machine active.
[Consumer ToolGoal] 🛠️ Model-facing Goal tool registered (bound to ctx.goals).

▶ [TaskRunner] 启动任务："部署 Mini-DSH 无头任务"

[目标域] 🎯 已创建目标："部署 Mini-DSH 无头任务"（状态：active，轮次：1） [步骤 1/4] 上下文初始化："Hello from Headless Base Profile, Agent Engineer!"
[目标域] 🔄 目标 "部署 Mini-DSH 无头任务" 已推进至第 2 轮 [步骤 2/4] 迭代 #1 指标 = 110 [目标域] 🔄 目标 "部署 Mini-DSH 无头任务" 已推进至第 3 轮 [步骤 3/4] 迭代 #2 指标 = 120 [目标域] 🎯 目标 "部署 Mini-DSH 无头任务" 状态更新为：completed

5. 运行 Capability Seam 执行世界切换（本地 vs 云端沙箱）

仅通过切换 Profile 配置，即可实现上层工具无感跨环境迁移：

场景 A：在宿主机本地执行（Local Profile）
pnpm start:local
- 控制台输出：[Local Host Process] 🖥️ Executing: "node -v"，直接在本地环境中快速执行指令。

场景 B：在云端安全沙箱中执行（Sandbox Profile）
pnpm start:sandbox
- 控制台输出：[Cloud Sandbox VM: e2b-secure-container-prod] 🔒 Safely isolating；
- 上层 tool-bash 与 task-runner 业务代码 0 修改，命令已自动路由并安全隔离在沙箱容器中执行！

6. 运行多会话隔离实验（Per-Session Presets 极简 vs 标准模式）

验证在同一个 Node.js 进程中，两个不同 Preset 的会话如何通过 Cordis 子上下文（isolate）实现能力隔离：

pnpm start:presets

控制台隔离结果对比：
* Session A (minimal)：Prompt 为极简指令，工具池仅拥有 ['tool-bash']，ctx.counter 处于隔离排除状态；
* Session B (standard)：Prompt 为全功能指令，完整装配 ['greeter', 'counter', 'tool-bash']。

7. 运行 Schemastery 声明式校验与 HMR 实时热重载实验

验证在无需重启 Node.js 进程的前提下，外部修改配置文件如何被 HmrService 实时捕获并驱动插件内部状态瞬间热替换：

pnpm start:hmr

控制台输出： [Cordis Loader] Applying plugin: @mini-dsh/plugin-greeter
[Schemastery] 🛡️ Validated config & injected defaults for "@mini-dsh/plugin-greeter"
[Plugin Greeter] Initialized with prefix: "Initial Greeter" (Enthusiasm: !)
...
[Before HMR] Initial Greeter Output: "Initial Greeter, Bob!"
[Simulated External Editor] 📝 Modifying "scratch-live-config.json" to v2...
[Host HMR] 🔥 Detected change in "scratch-live-config.json"! Triggering live reload...
[After HMR] Hot-Reloaded Greeter Output: "🔥 Hot-Reloaded Super Greeter (v2), Bob!!!!"
✔ [HMR Demo] Live Hot-Reload test completed successfully!

8. 验证 “Everything is a plugin” 的可插拔性

实验 A：在配置文件中禁用一个插件打开 profiles/web.yml，在 plugin-counter 节点下增加 disabled: true：
- name: '@mini-dsh/plugin-counter'
disabled: true
重启服务并刷新浏览器：
- 观察终端日志：Counter 插件未加载，未注册 /api/count 路由。
- 观察网页：sidebar.widgets 插槽中的计数器组件完全消失，系统其他功能丝毫不受影响。

实验 B：验证 Headless 优雅降级打开 profiles/base.yml，将 @mini-dsh/plugin-counter 设为 disabled: true：
pnpm start:base
- 观察 task-runner：自动检测到 counter 缺失，执行降级逻辑，依然稳定完成工作流！

许可证 (License)

本项目采用 MIT 许可证。