autoqueue — DSH 無人值守任務隊列

前言¶

DSH（DeepSeek Harness）採用插件化架構，生態中存在多種工作流插件。開發者常需要處理定時任務或後臺任務，而不希望這些操作阻塞當前的前臺會話。autoqueue 是一款由 alin-ever 維護的工作流類插件，旨在將 Markdown 任務交給隊列，由 DSH 後臺自動派發、反阻塞、重試、結算並歸檔。

該插件的核心設計是調度器與任務的分離：調度器負責定時觸發（如 cron），到點時自動創建即時任務；即時任務則執行一次性的具體工作，擁有完整的狀態機生命週期。兩者互不干擾，確保正常任務不打擾用戶，隊列任務不改變普通前臺會話的運行狀態。

核心功能¶

根據已覈實的事實，該插件包含以下核心能力：

調度與執行分離：調度器不進入狀態機，不執行；即時任務擁有完整的狀態流轉。
定時觸發：支持通過 cron 表達式或 schedule 字段設定觸發時間。
狀態機管理：任務具備 pending、running、done、failed、stopped、interrupted 六種狀態。
會話隔離與權限控制：每次執行使用獨立的專屬會話 ID 和運行目錄，不干擾普通 Host 會話。
無人值守執行：執行模式嚴格限制，默認最大併發爲 1。
React 看板界面：提供任務、調度、歸檔三個獨立標籤頁的監控界面。
文件收件箱機制：支持直接將 Markdown 文件丟入隊列目錄以創建任務。
自動注入工具：插件加載後自動向普通 Host 會話註冊 19 個 autoqueue_* Host 工具。
HTTP API 與 OpenAPI：提供完整的 RESTful API 和 OpenAPI 3.1 文檔接入。

安裝與配置¶

安裝¶

通過官方提供的安裝命令添加插件：

dsh plugin --profile web add -w @alintever/dsh-plugin-autoqueue@latest

兼容性¶

基線版本：插件經過審計和自測的精確基線是 @deepseek-ai/dsh 0.1.5-rc.1。
清單範圍：插件清單接受 >=0.1.1-rc.2 <0.1.6。升級 DSH 後建議重新運行單元測試和 Playwright。
依賴：@deepseek-ai/dsh-sandbox-policy、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-user-approval 跟隨 DSH 引擎版本範圍。

配置¶

對於遠程部署或反向代理場景，必須配置鑑權參數：

config:
  allowedHosts:
    - queue.example.com
  apiToken: "replace-with-a-long-random-secret"

也可以通過環境變量提供 token：DSH_AUTOQUEUE_TOKEN 或 AUTOQUEUE_API_TOKEN。一旦設置 token，本地訪問 localhost 也必須攜帶鑑權頭。

使用方法¶

1. 通過 API 創建任務¶

使用 POST /api/queue/task 創建即時任務：

curl -X POST http://127.0.0.1:3080/api/queue/task \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId": "my-001",
    "key": "daily-report",
    "content": "# 生成日報\n\n收集今天的工作數據，輸出 report.md",
    "priority": 5,
    "autoArchive": true,
    "enableNotifications": false
  }'

2. 通過 API 創建調度器¶

在請求體中包含 cron 或 schedule 字段即可創建調度器：

curl -X POST http://127.0.0.1:3080/api/queue/task \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId": "my-002",
    "key": "weekly-insight",
    "content": "# 生成周報\n\n彙總本週代碼提交與 issue 進展",
    "cron": "0 9 * * 1",
    "priority": 5
  }'

調度器到點時會自動創建即時任務，即時任務繼承調度器的配置。

3. 通過文件收件箱¶

隊列目錄默認爲 ~/.dsh/queue/tasks/。文件名作爲 key，正文作爲任務內容。文件頭支持聲明調度方式：

echo "# 生成日報" > ~/.dsh/queue/tasks/daily-report.md

Markdown 文件頭示例：

<!-- cron: 0 8 * * 1-5 -->
<!-- deadline: 0 21 * * * -->
# 每日工作報告

4. 使用看板¶

安裝後，在 DSH Web 側邊欄點擊「任務工作臺」。看板提供任務/調度/歸檔三個標籤頁，支持查看狀態、編輯（非運行中）、停止、重跑、歸檔等操作。

安全與隔離¶

autoqueue 嚴格限制執行模式，確保不干擾主進程：

會話隔離：每次 attempt 使用獨立的運行目錄和專屬會話 ID（autoqueue-session-<uuid>），Runner 拒絕讀寫非本命名空間的會話。
執行模式：使用 autoqueue-unattended-v2 preset，禁用提問、jobs、subagent/fork/control/list、workflow、Ralph。bash/pwsh 強制 enableRunInBackground:false。
權限固化：會話創建後，approvalPolicy 被固化爲 never 並持久化驗證。
Host 工具隔離：插件向普通 Host 會話注入 19 個 autoqueue_* 工具，但這些工具在 autoqueue-session-* 自有任務 Agent 中被隱藏，執行層 Guard 也會拒絕繞過可見性的工具調用。

適用場景¶

該插件適合需要自動化處理後臺任務的場景，例如：

定時生成日報、週報。
需要持久化、可重試的批量數據處理。
不希望打斷當前用戶交互的自動化流程。

結語¶

autoqueue 爲 DSH 提供了一套完整的無人值守任務隊列方案。它通過調度器與任務的分離設計，配合嚴格的會話隔離機制，實現了在後臺靜默執行任務的能力。通過文件收件箱、HTTP API 和 React 看板，開發者可以靈活地管理任務流。

更多詳情請查看插件目錄或源碼倉庫。