一句話結論
dsh-superagent 不是一個新產品,而是 DeepSeek 團隊把「自己在用的 agent 工作流」去蕪存菁後開源出來的樣本: 一個只服務單一 GitHub repo 的主動式 coding agent,包成 DeepSeek Harness 的外掛。有人在 repo 裡叫它做事,它會自己開一個工作項、在獨立的 agent session 與目錄裡做完、回到原本那段對話回報(通常是開一張 PR),另外用一個網頁面板顯示「哪裡需要真人」。
但這個專案最值得看的不是「它能開 PR」——那已經不稀奇。它真正在處理的問題是:一個能替整個團隊做事的 agent,也能浪費整個團隊的注意力。 所以核心規則是「以最少的真人注意力,換最大的價值」,而且寫得很硬:只在被要求、或團隊白紙黑字寫下規則時才行動。
上線五天,星數從 6,447 長到 20,409(2026-11-06 查詢),但程式碼從公開那天起一行都沒動——repo 至今只有一個 commit。這代表成長來自轉推與討論,不是迭代;下面拆的每個設計,都還是 10 月 31 日那個版本。
它是什麼、不是什麼
| 項目 | 內容 |
|---|---|
| GitHub | deepseek-ai/dsh-superagent-prototype |
| 星數/分支 | ★20,409/2,378 forks(2026-11-06 查詢;公開當日為 6,447/633) |
| 授權/語言 | MIT/TypeScript |
| 版本 | 0.1.0 |
| 建庫與最後推送 | 建庫 2026-10-31 09:32、推送同日 12:05(UTC),之後僅一個 commit |
| 規模 | 216 個檔案,其中 src/ 111 檔、tests/ 65 檔、prompts/ 15 檔、docs/ 9 篇 |
| 執行環境 | Node ^22.19.0 或 ≥24,且需要 DeepSeek Harness ^0.2.1-alpha.2 |
| 執行期依賴 | 只有 2 個(proper-lockfile、zod) |
它不是獨立 CLI,而是 Harness 的外掛(bundle)——這點很重要:必須跑在 DeepSeek Harness 之上,不是裝了就能單獨跑。
而 README 自己把話講得很白:
「Research prototype for reference only, not an official DeepSeek product.」(研究原型,僅供參考,不是官方 DeepSeek 產品)
還補了兩句更難得的誠實聲明:程式碼是團隊日常開發長出來的、大部分工程由 coding agent 自己完成,因此「可能仍有 bug,風格與工程實踐可能不一致」;而且文章裡討論的部分設計,這個原型並沒有實作。
運作流程:從一句話到一張 PR
它的資料流是一條固定的鏈,每個環節都有明確定義:
| 環節 | 做什麼 |
|---|---|
| Source | 事件來源。GitHub(可選 Feishu)各自是一個實作,負責記錄讀取位置、自己的 bot 身分、過濾自己的訊息 |
| Trigger | 一個不可變的事件(誰、在哪、說什麼)。同一個 Trigger 被接受兩次只會產生一張 Ticket(幂等) |
| Thread | 依時間排序的 Trigger 串。同一條 Thread 同時只允許一個 Eval 在跑 |
| Eval | 兩層判斷(gate+assessment):這批事件該不該開新工作、該不該繼續、該不該停 |
| Mandate | 受理時發出的授權:政策版本、範圍、強度、命中的規則、發話者在該 Source 的身分。不可變,要擴大範圍只能開新 Ticket |
| Ticket | 一個「被授權的工作單位」。只有 Eval 能建立;有獨立狀態機(open → ended,可被人喚回) |
| Assignment/Executor | 把 Ticket 交給一個執行者實例;執行者在獨立 session(worker-<ticket id>)與獨立目錄裡工作 |
| Channel | 寫回 Source 的通道:回覆、開 PR、回應 review 都算寫入 |
這套設計解決的是 agent 自動化最常見的三個災難:重複觸發(幂等)、並發打架(一條 Thread 一個 Eval)、越權(Mandate 不可變)。
11 個領域概念,但只留必要的
團隊刻意把設計壓到「少數概念+具體實作」,商業需求只能變成某個概念的屬性,不能新增概念。核心概念可以整理成三層:
| 層 | 概念 | 一句話 |
|---|---|---|
| 來源層 | Source、Trigger、Thread、Correlation、Channel | 事件從哪來、屬於哪條討論、回哪裡 |
| 判斷層 | Policy、Eval、Mandate | 規則怎麼寫、怎麼判斷、憑什麼授權 |
| 執行層 | Ticket、Assignment、Subscription | 做什麼、誰做、後續討論怎麼接回來 |
其中 Subscription 是整套設計裡最聰明的一個:它讓「後續討論自動回到執行者」,不需要任何人再 @ 一次 agent。PR 關掉或合併後,Ticket 仍保留訂閱——有人留言就沿著同一份 Mandate 喚回,不用重新走一次判斷。這解決了「agent 開完 PR 就斷線」的老問題。
三層授權:誰能叫它做事
這是整個專案最不像玩具的地方。它把「能不能做」拆成三層,而且三層都不靠提示詞的自制力:
| 層 | 機制 | 重點 |
|---|---|---|
| ① 誰能發話 | Source 層的 allowed list(Policy 的一部分) | 只有名單上的人、或團隊開放討論串裡的人,發話才算「請求」 |
| ② 請求的強度 | admission table(准許程度表) | 分 mention(被 @)與 direct(私訊);表是 Policy 版本的一部分,調弱某格不會立刻停掉已開的 Ticket,但會在重新驗證時撤銷其 Mandate |
| ③ 已授權的範圍 | Mandate(不可變) | 範圍是寫死的;要更大範圍=新 Ticket。只有真人喊停、或新版 Policy 不再涵蓋,才會失效 |
還有一個關鍵設計:「沒人要求的自動工作,先只記錄、不執行」(record-only 模式)。等團隊看過「它本來會做什麼」覺得沒問題,才放寬到真的動手。這是把 agent 上線風險降到最低的做法,比任何「請謹慎使用」的警語都有效。
13 個核心類別:把系統拆成可替換的零件
docs/007-architecture.md(70 KB,全專案最大的檔案)把程式切成 13 個核心單位,每個只透過一個具名介面跟外界往來。以下一句話是依該文件章節歸納,不是官方原文:
| 單位 | 負責 |
|---|---|
| Runtime | 啟動與組裝:讀機器設定、把其餘 12 個單位接起來,並提供「存檔後重啟」的入口 |
| Engine | 被呼叫的入口角色,本身以 Pick 形式暴露給呼叫方 |
| Model | 模型呼叫與回應處理 |
| Policy | 三層授權的規則本體(allowed list、admission table、版本) |
| Store | 持久化:Ticket、Mandate、Trigger 等狀態落地 |
| Effects | 對外副作用(推分支、開 PR、送訊息) |
| Sources | 事件來源的註冊表與各 kind 的實作(GitHub、Feishu) |
| DshExecutor | 真正跑 DeepSeek Harness 的執行者 |
| MasterAssessor | 判斷層:決定這批事件要不要開新工作、要不要停 |
| Settings | 設定讀取與遷移 |
| Prompts | 提示詞組裝(見下一節的 8 步順序) |
| Sessions | agent session 的建立、命名與生命週期 |
| Glue | 黏合層:HTTP、主 session 工具、執行者工具、資源與連結 |
這份清單本身就是設計宣言:13 個單位、沒有第 14 個。要加商業需求,只能改某個單位的屬性,不能新增一個平行概念——跟前面「11 個領域概念」是同一條規則的兩種展現。
依賴規則:用 Pick 型別把權限縮到最小
這是整份架構文件裡最值得抄的一段工程實務。每個核心類別拿到的不是「另一個類別」,而是只列出它真的會用到的成員的 Pick 型別:
| 介面 | 給誰用 |
|---|---|
ExecutorHost、AssessorHost、SessionsHost | 核心類別彼此呼叫時的最小面 |
SettingsHost、SetupHost、PassesHost、OutboxHost | 同上,各自只暴露必要方法 |
HttpHost、MainToolsHost、ExecutorToolsHost、ResourceHost、LinkHost、SourceContextDeps | 黏合層對外 |
SourceHost | 給 Source 外掛注入的 orchestrator(只有註冊表與 context(kind)) |
規則有兩條:
- Runtime 只在自己被包成這類介面之後才傳出去,不會有任何類別拿到完整的 Runtime。
- Source 外掛只看得到自己的
SourceContext,看不到別的 kind、也看不到 Registry 全域。
換句話說,權限邊界不是靠 code review 維持,而是靠型別系統擋住——想越權就得先改介面定義,而那會在 review 時被看見。
65 個測試檔、1,041 KB:治理規則是被測試釘住的
這個專案最反直覺的數字在這裡:執行期依賴只有 2 個,測試碼卻有 1,041 KB。
| 測試檔 | 大小 | 釘住的東西(依 007 的 Tests 章節) |
|---|---|---|
tests/runtime.spec.ts | 138.7 KB | Runtime 的組裝與各單位協作 |
tests/core-engine.spec.ts | 104.4 KB | 記憶體版 repository 上的領域規則:收事件、Eval、fan-out、續跑與停止、被中斷的 Assignment、暫停、Policy 變更、回報與結果、掛載、回覆、投遞失敗、被 dismiss 的問題 |
tests/sources.spec.ts | 100.5 KB | Feishu 與 GitHub 兩種 Source 在 SourceContext 上的行為 |
tests/runtime-concurrency.spec.ts | 62.5 KB | 併發(多 Thread、多 Ticket 同時跑) |
tests/policy.spec.ts | 43.9 KB | Source 範圍、gate、admission table、Mandate 重新驗證、Policy 版本、設定遷移、判斷結果 |
tests/migration.spec.ts | 42.1 KB | 設定與資料的版本遷移 |
tests/tools.spec.ts | 38.4 KB | 模型面工具(主 session/執行者各自能呼叫什麼) |
tests/stage.spec.ts | 5.5 KB | Ticket 狀態機,逐列驗證 |
tests/registry.spec.ts | 11.6 KB | SourceRegistry:實例、驗證、Policy 片段、Channel、Thread context |
(另有 56 個較小的 spec 與 fixture,合計 65 檔。)
這張表說明的不是「測試很多」,而是測試挑得很有針對性:專案最怕的三件事——越權、重複觸發、並發打架——各自有專屬 spec。對想做 agent 治理的人,policy.spec.ts 與 stage.spec.ts 兩份值得直接讀。
15 個 prompt 檔與 8 步組裝順序
提示詞在這個專案裡不是一大段文字,而是可以被組裝與排序的零件:prompts/ 目錄共 15 個檔案、合計 48.7 KB,最大的是 prompts/team/communication.md(9.4 KB)。
系統提示詞的組裝順序是固定的 8 步(依 docs/004-prompts.md):
| 順序 | 內容 | 只給主 session? |
|---|---|---|
| 1 | 共用指令與角色 | |
| 2 | 三個團隊段落(team/communication、team/scope、team/delivery) | |
| 3 | 訂閱與回覆規則 | |
| 4 | 主 session 的 dispatch 指令,或執行者的工作指令 | |
| 5 | runtime/admission(主動判斷與忽略條件) | ✅ |
| 6 | 交接(handoff)指令 | |
| 7 | runtime/environment(部署層級的值) | |
| 8 | runtime/policy | ✅ |
這個「排序」有實際作用:admission 與 policy 只給主 session,執行者拿不到——執行者不需要自己判斷「該不該做」,因為那是別人的職責。另外 orchestrator_eval 只回傳情境,不重複這些指令,避免同一條規則在兩處各寫一次而漂移。
面板只回答三個問題
大多數 agent 儀表板會把所有狀態都畫出來;這個專案刻意相反,打開面板只回答三件事,而且照這個順序:
- 「現在有東西需要我嗎?」
- 系統健康嗎、在做對的事嗎?
- 某一件工作的歷史:從 Trigger → Eval → Ticket 的完整軌跡?
原則寫得很清楚:需要真人的事才佔版面,健康的狀態不佔。 判斷標準是「有人必須動手,或有人可以直接用得上結果」,其餘一律沉默——與 README 那句「speaks only when someone must act or can use a result」是同一條。
執行與資源控制
| 項目 | 設定 |
|---|---|
| 執行 session 命名 | worker-<ticket id>,每個 Ticket 一個目錄 |
| 背景工作上限 | 每一輪結束後,背景工作最多 30 分鐘,超過就砍掉 shell job 並回報「等待中」 |
| 目錄準備 | 首次執行前跑一次 prepare 指令(sh),限時 10 分鐘,失敗即該 Ticket 失敗並記錄輸出 |
| 併發 | 有設定的併發槽上限,額外保留 1 個槽給真人訊息或狀態查詢 |
| 可觀測 | 面板只列「需要真人」的事;健康的狀態不佔版面 |
那個「額外 1 個槽給真人」是實務細節,但很有意義:它保證人的一句話永遠不會排在 agent 的批次工作後面。
部署前置:為什麼一定要獨立 profile
docs/006-deployment.md(23 KB)把落地條件寫得很細,其中兩點會直接影響「能不能裝」:
硬性前置
| 需求 | 版本/條件 |
|---|---|
| Node.js | 22.19+ 或 24+ |
| pnpm、git | pnpm 必需;git 2.32+ |
| Python、tmux | Python 3.8+;tmux 必需 |
| GitHub CLI | gh 2.48 以上(Source 的 CLI 欄位必須指向 gh 或 lark-cli 包裝,宿主依賴它們的子命令與輸出格式) |
| Repo | 必須在 github.com;不支援 GitHub Enterprise Server |
| 模型 | 必須有一個給 DeepSeek Harness 用的 provider(預設用 profile 的預設模型) |
| 選配 Feishu | lark-cli(測試版 1.0.90)+ 一個有 bot 的 Feishu/Lark app |
為什麼要另開一個 Harness profile:文件明講要建一個專用的 profile(範例叫 superagent),不要跟你平常工作用的那個共用。理由不是潔癖,而是這個 plugin 會改動 process-wide 的 PATH 與 git 設定,而且它需要獨立的重啟與升級節奏。文件也提醒:如果要為每個 Ticket 開一份 checkout,得保留一份本機 clone,讓 prepare 指令能開 worktree;repo 用 Git LFS 就要先裝 git-lfs。
部署後還有幾個常設機制:gh 必須只以 agent 的那個帳號登入(它用該身分留言、推分支、開 PR)、每小時的健康檢查、設定用的 Management API、以及一組 setup 檢查。
擴充一個事件來源:11 步食譜
docs/008-cookbook.md(30 KB)的價值不在概念,而在**「要加一個新的 Source(例如 GitLab、Jira)到底要動哪些東西」**。它給的是 11 步清單:
| 步 | 要做的事 |
|---|---|
| 1 | 把 Trigger、Thread、actor、Channel 位址、接收範圍對映到領域模型 |
| 2 | 寫 kind 的 schema、fields、health,以及(若 setup 需要)facts |
| 3 | 把事件轉成 穩定 id 的 Trigger,並丟掉 agent 自己的訊息 |
| 4 | 決定這個 Source 在 scope 裡收得到什麼(只從 meta 判斷) |
| 5 | 給它一個 Channel:send 每則訊息只送一次;只有在「這段對話永遠收不到」時才回 gone |
| 6 | 若它能讀 Thread,就把 Thread context 給判斷層 |
| 7 | 給它 Policy 的一部分:allowed 與 admission 列 |
| 8 | 註冊它的執行環境變數 |
| 9 | 寫 plugin 入口與迴圈(等 setup、跟隨開關、搬 current 游標) |
| 10 | 註冊這個 plugin |
| 11 | 寫測試 |
這份清單的價值在於它把「擴充性」變成可驗收的:11 步走完,就有第 14 個零件可用,而 13 個核心類別一行都不用改。
五個該保留懷疑的地方
| 疑點 | 說明 |
|---|---|
| 熱度不等於驗證 | 五天內從 ★6,447 長到 ★20,409,但 repo 至今只有一個 commit、程式碼完全沒動;成長來自討論,不是社群已經在用 |
| 0 個 open issue 不代表穩定 | 專案 10-31 才公開,0 issue 更可能是「太新」而不是「沒問題」 |
| 必須搭配 alpha 版 Harness | 依賴 dsh ^0.2.1-alpha.2——alpha 會變,跟著升級可能隨時壞 |
| 官方明說不是產品 | research prototype、部分設計未實作、程式碼由 agent 自己寫、風格不一致;README 直接要你「先審再改」才用 |
| 沒有可驗證的成效數據 | README 與文件都沒有「省下多少時間、開了幾張 PR、誤判率多少」的數字;本文亦未實測,因此不給任何效能結論 |
另外,README 提到一篇同名文章《Exploring Super-agent Design: Towards a More Autonomous Agent System》,但 repo 內找不到該文的公開連結,所以無法核對「文章描述」與「程式實作」的差距——這點只能等作者補上。
而作者自己在架構文件末尾列了兩個未解的問題,比任何外部評論都值得注意:
- 信任邊界:Trigger 的哪些欄位可信(Source 回報的 actor、Thread 成員資格),哪些不可信(訊息本文、引用的內容)——這決定「有人假冒發話者」時會發生什麼。
- 部署隔離:agent 應該跑在自己 pin 住的 Harness 安裝上,這樣在別處升級 Harness 不會弄壞它。
誰適合看、誰先不用碰
適合
- 想把 agent 接進團隊既有工作流(不是自己玩)的工程主管:這份 repo 是「治理先於能力」的參考樣本
- 正在設計多代理/審批制系統的人:11 個概念、Mandate 不可變、
Pick型別邊界、policy.spec.ts都可以直接借 - 已經在用 DeepSeek Harness 的人:這是官方生態裡第一個「主動式」bundle
- 想研究「提示詞怎麼工程化」的人:15 個 prompt 檔+8 步組裝順序是一份現成的對照組
先不用碰
- 只想要一個能自動回 issue 的機器人:這個要裝 Harness、跑 alpha、還要寫 Policy
- 想要開箱即用的 SaaS:它是原型,不是產品
- 需要穩定 SLA 的生產環境:0.1.0 + alpha 依賴,現階段不適合
站內延伸閱讀
- DeepSeek Harness 開源登場:「一切皆插件」的 Agent 框架 — dsh-superagent 就是掛在這套框架上的 bundle,先懂 Harness 再看這篇會更順
- DeepSeek Harness 十大插件推薦 — 同生態的其他外掛,可比較「主動式」與「被動式」插件的差別
- claude-mem 完整教學 2026:AI 代理長期記憶 — 代理要跨 session 工作,記憶層是另一個必須解決的題目
本文為獨立評測與整理,不含聯盟連結、未受任何廠商贊助。專案數據取自 GitHub 公開資料(2026-11-06 查證),架構、測試、提示詞、部署與食譜等細節取自 repo 內
docs/004~docs/008;本文未實際部署或執行該專案。
