DeepSeek 開源 dsh-superagent:會自己開 PR 的代理,先學會少吵人

dsh-superagent 是 DeepSeek 開源的主動式 coding agent(★20,409、MIT、TypeScript、0.1.0),包成 DeepSeek Harness 外掛,只服務單一 repo。深度拆解:13 個核心類別與 Pick 型別依賴規則、65 個測試檔與 1,041 KB 測試碼、15 個 prompt 檔的 8 步組裝順序、面板只回答的三個問題、獨立 profile 部署要求,以及擴充一個事件來源的 11 步食譜。

  • Dennis
  • 13 分鐘閱讀
DeepSeek 開源 dsh-superagent:會自己開 PR 的代理,先學會少吵人

一句話結論

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 日那個版本。

它是什麼、不是什麼

項目內容
GitHubdeepseek-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 步順序)
Sessionsagent 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))

規則有兩條:

  1. Runtime 只在自己被包成這類介面之後才傳出去,不會有任何類別拿到完整的 Runtime。
  2. Source 外掛只看得到自己的 SourceContext,看不到別的 kind、也看不到 Registry 全域。

換句話說,權限邊界不是靠 code review 維持,而是靠型別系統擋住——想越權就得先改介面定義,而那會在 review 時被看見。

65 個測試檔、1,041 KB:治理規則是被測試釘住的

這個專案最反直覺的數字在這裡:執行期依賴只有 2 個,測試碼卻有 1,041 KB。

測試檔大小釘住的東西(依 007 的 Tests 章節)
tests/runtime.spec.ts138.7 KBRuntime 的組裝與各單位協作
tests/core-engine.spec.ts104.4 KB記憶體版 repository 上的領域規則:收事件、Eval、fan-out、續跑與停止、被中斷的 Assignment、暫停、Policy 變更、回報與結果、掛載、回覆、投遞失敗、被 dismiss 的問題
tests/sources.spec.ts100.5 KBFeishu 與 GitHub 兩種 Source 在 SourceContext 上的行為
tests/runtime-concurrency.spec.ts62.5 KB併發(多 Thread、多 Ticket 同時跑)
tests/policy.spec.ts43.9 KBSource 範圍、gate、admission table、Mandate 重新驗證、Policy 版本、設定遷移、判斷結果
tests/migration.spec.ts42.1 KB設定與資料的版本遷移
tests/tools.spec.ts38.4 KB模型面工具(主 session/執行者各自能呼叫什麼)
tests/stage.spec.ts5.5 KBTicket 狀態機,逐列驗證
tests/registry.spec.ts11.6 KBSourceRegistry:實例、驗證、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 指令,或執行者的工作指令
5runtime/admission(主動判斷與忽略條件)✅
6交接(handoff)指令
7runtime/environment(部署層級的值)
8runtime/policy✅

這個「排序」有實際作用:admission 與 policy 只給主 session,執行者拿不到——執行者不需要自己判斷「該不該做」,因為那是別人的職責。另外 orchestrator_eval 只回傳情境,不重複這些指令,避免同一條規則在兩處各寫一次而漂移。

面板只回答三個問題

大多數 agent 儀表板會把所有狀態都畫出來;這個專案刻意相反,打開面板只回答三件事,而且照這個順序:

  1. 「現在有東西需要我嗎?」
  2. 系統健康嗎、在做對的事嗎?
  3. 某一件工作的歷史:從 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.js22.19+ 或 24+
pnpm、gitpnpm 必需;git 2.32+
Python、tmuxPython 3.8+;tmux 必需
GitHub CLIgh 2.48 以上(Source 的 CLI 欄位必須指向 gh 或 lark-cli 包裝,宿主依賴它們的子命令與輸出格式)
Repo必須在 github.com;不支援 GitHub Enterprise Server
模型必須有一個給 DeepSeek Harness 用的 provider(預設用 profile 的預設模型)
選配 Feishulark-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 內找不到該文的公開連結,所以無法核對「文章描述」與「程式實作」的差距——這點只能等作者補上。

而作者自己在架構文件末尾列了兩個未解的問題,比任何外部評論都值得注意:

  1. 信任邊界:Trigger 的哪些欄位可信(Source 回報的 actor、Thread 成員資格),哪些不可信(訊息本文、引用的內容)——這決定「有人假冒發話者」時會發生什麼。
  2. 部署隔離: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 依賴,現階段不適合

站內延伸閱讀

本文為獨立評測與整理,不含聯盟連結、未受任何廠商贊助。專案數據取自 GitHub 公開資料(2026-11-06 查證),架構、測試、提示詞、部署與食譜等細節取自 repo 內 docs/004~docs/008;本文未實際部署或執行該專案。

📬 訂閱 most.tw 電子報

每週精選 AI 工具教學與技術乾貨,直接送到你的信箱。免費、隨時可退訂。

訂閱即表示同意收到 most.tw 電子報,隨時可一鍵退訂。

💬 有問題想討論?加 LINE 聯絡我

歡迎透過 LINE 官方帳號直接留言,我會盡快回覆你的問題。

加入 LINE 好友