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 掛載），實現了與主框架的無縫集成。