dsh-maestro-runtime：适配 Maestro-Flow 的 DSH 运行时插件

前言¶

DSH 采用插件化架构。当智能体需要与 Maestro-Flow 运行时深度交互时，需要将 Maestro-Flow 的运行时表面适配到 DSH 会话中。dsh-maestro-runtime 旨在解决这一适配问题，提供安全防护、上下文注入、后台 KG 同步等功能，覆盖 P0 + P1 级场景。

插件介绍¶

这是一个 DSH host 插件，由 zhao-wuyan 维护。它将 Maestro-Flow 的运行时表面适配到 DSH 会话。插件通过 cordis.patch.yml 挂载，无需修改 DSH 源码即可运行。

核心功能¶

Guard¶

阻止危险的 bash / pwsh 命令（如递归删除、硬 git reset、强制 push、磁盘格式化等）。
阻止模型直接写入受保护的 Maestro 状态文件（.workflow/state.json、.workflow/config.json、.workflow/sessions/**、.workflow/runs/**、.workflow/.maestro/**）。
强制执行 .workflow/config.json 中的 PathGuard 边界。
验证 .workflow/specs/*.md 中的 <spec-entry> 格式。

Context¶

在用户提示和 /maestro* 技能调用时注入去重后的 <maestro-context> 快照。
快照内容包含工作流状态、活动会话、项目标题、specs 索引、knowhow 索引以及 delegate 通知。

Onboarding¶

当在未配置有效 Maestro 工作区的项目中调用 /maestro* 技能时，注入一次性的 /maestro-init / /maestro "<intent>" 指导。
对普通非 Maestro 提示保持静默。

KG¶

当 maestro.db 缺失时，后台运行 maestro kg init（5 分钟冷却）。
当 maestro.db 存在时，后台运行 maestro kg sync --incremental（30 秒冷却）。
直接通过 node maestro.js 启动，不使用 cmd shell，不显示控制台窗口。

Delegate¶

扫描 host 的 tmpdir 和第一级 dsh-* 会话 temp 目录中的 maestro-notify-*.jsonl 文件。
注入未读的完成通知，并将它们标记为已读。

Team¶

当本地 git 身份匹配已加入的成员时，将去重的心跳（60 秒间隔）追加写入 .workflow/collab/activity.jsonl。

Coordinator¶

在 step/end 和 turn/end 事件时写入 maestro-coord-<dsh_session>.json 桥接文件。

安装与启用¶

环境要求¶

DSH 0.1.0-rc.6 profile（dsh web 可用）。
Node.js >= 20。
pnpm >= 10。
maestro-flow CLI 已安装并可在命令行中调用。

安装步骤¶

DSH 插件通过 pnpm 安装并使用 cordis.patch.yml 挂载。可以使用官方推荐的直接安装命令：

dsh plugin --profile web add "github:zhao-wuyan/dsh-maestro-runtime#v0.1.2"

安装后，DSH 会自动激活其 bundle 层。重启 DSH 并验证：

dsh --profile web --dump-config | grep maestro-runtime

配置¶

默认配置通常已满足需求，但可以通过修改 ~/.dsh/profiles/web/cordis.patch.yml 覆盖。以下是可配置项及其默认值：

- id: maestro-runtime
  name: 'dsh-maestro-runtime'
  config:
    guardEnabled: true
    contextEnabled: true
    maxContextChars: 8000
    kgEnabled: true
    delegateMonitorEnabled: true
    teamMonitorEnabled: true
    coordinatorEnabled: true

典型用法¶

安全防护：用户尝试执行 rm -rf / 或 git reset --hard HEAD~10 时，Guard 会拦截并阻止执行。
上下文增强：在用户发送普通提示时，插件自动注入当前的 <maestro-context> 快照，使智能体能获取工作流状态和项目信息。
自动初始化：首次在项目目录下使用 /maestro 指令时，插件会引导用户初始化工作区。
后台同步：即使没有人工干预，KG 数据也会在后台根据文件存在情况自动初始化或增量同步。
协作同步：团队成员在本地提交代码后，心跳数据会自动写入协作日志。

适用场景与注意¶

适用场景¶

使用 Maestro-Flow 进行工作流编排的开发者。
需要在 DSH 会话中深度集成 Maestro 上下文和状态的场景。
需要自动化处理 KG 同步和团队协作日志的场景。

注意事项¶

权限与进程：插件以当前 DSH 进程的权限运行，请确保已安装的依赖版本兼容。
依赖检查：安装前请确认本地环境满足 Node.js >= 20、pnpm >= 10 以及 maestro-flow CLI 的可用性。
源码审查：虽然是 MIT 许可证，但建议在引入生产环境前检查源码实现。

生态背景¶

DSH 理念是「一切皆插件」。社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。此插件通过遵循 DSH 插件发布约定（如 dsh-* 命名、dsh.bundle 声明、cordis.patch.yml 挂载），实现了与主框架的无缝集成。