前言¶

在 DeepSeek Harness（DSH）裏用 dsh-agent-teams 跑多智能體協作時，成員的人設、模型路由和工具邊界往往散落在對話或臨時配置裏，難以評審、版本化和與運行時對齊。若直接在運行時裏逐個改成員參數，改名或字段含義變化後也不易覈對「檔案裏寫的」和「團隊裏存的」是否一致。

下面介紹社區插件 dsh-agent-roster（npm 包名 @stofone/dsh-agent-roster，倉庫 dsh-agent-roster/dsh-agent-roster）。它把團隊成員定義成磁盤上的可校驗文件，並橋接到 agent_teams_* 調用參數；調度、建隊與 .agent-teams/ 狀態仍由 dsh-agent-teams 負責。

這是什麼¶

dsh-agent-roster 是 DSH 生態中的工作流類插件：爲 DeepSeek Harness 提供靜態成員花名冊（roster）與成員檔案的定義格式、校驗，以及向 dsh-agent-teams 成員創建流程的輸出轉換。

花名冊即一份明確文件：誰在隊、各自職責、走哪條模型路由、允許哪些工具策略。插件只做定義與校驗層，並在 roster_create 時按字段標註哪些會進入運行時、哪些僅爲聲明；不會創建成員、排任務或寫入團隊運行態。

維護與發佈信息以倉庫與 package.json 爲準：GitHub 組織/倉庫爲 dsh-agent-roster/dsh-agent-roster，npm 作者爲 STofone，當前資料中包版本爲 1.5.0，許可證 MIT。社區目錄頁：skillhub.cn 插件頁（獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）。

核心功能¶

資料中明確的能力邊界如下。

安裝後插件提供 11 個工具（資料列舉）：roster_list、roster_show、roster_create、roster_verify、roster_diff、roster_index、roster_space、roster_search、roster_changes、roster_compile、roster_team。左側欄會出現 Agent Roster 主面板（非 Settings 子項）。

成員字段在橋接時被分類：direct（如 name、role、systemPrompt、provider、model、reasoningEffort、toolPolicy）會傳給 agent_teams_add_member；config（如 fallback）需屬主側配置；declaration（如 description、aliases、skills、examples 等）僅文檔與校驗，運行時不會自動應用。roster_verify 會將各字段報告爲 applied、overridden、omitted 或 unconfirmed。

安裝與啓用¶

依賴：需要帶 tools 服務的 DSH（任意較新構建），以及 yaml（插件已聲明爲依賴）。Node 引擎要求爲 >=22.19.0（來自 package.json）。

在 DSH 插件管理器中指向本倉庫（絕對路徑），或發佈後使用包名安裝。資料原文給出的標識爲：

@stofone/dsh-agent-roster

包內帶有 cordis.patch.yml，安裝後會自動寫入 profile。Fresh 安裝時全局檔案庫爲空，面板會顯示「0 rosters」，直到在 UI 中創建或通過 CLI 操作。

安全說明：插件以當前 DSH 進程權限運行；安裝前請自行查看倉庫源碼與 MIT 許可證，確認符合你的環境策略。

檔案庫位置與文件格式¶

檔案庫是全局的：每臺機器一份，不在工作區內；默認路徑爲 DSH 數據目錄下的 agent-roster（$DSH_HOME/agent-roster，一般爲 ~/.dsh/agent-roster；Docker 中爲掛載卷）。首次保存時創建，無需手工建目錄。

每個花名冊佔一個子目錄，目錄內有且僅有一個主文件，探測順序爲 roster.yaml、roster.yml、roster.json；若存在多個會報錯，不會靜默擇一。

示例結構（來自 README）：

~/.dsh/agent-roster/
└── core-review/
    └── roster.yaml

頂層字段僅允許文檔列出的鍵；未知鍵視爲錯誤。必填包括 kind（必須爲 dsh-agent-roster/v1）、roster（kebab-case，且等於目錄名）、version（精確 SemVer）、members（1～32 條）。可選包括 defaults（成員繼承的路由字段）、captain（描述隊長會話，不自動創建）等。成員必填 name、role、systemPrompt；systemPrompt 上限 8000 字符。

Quick start 片段（YAML，字段含義見倉庫 File reference）：

kind: dsh-agent-roster/v1
roster: core-review
version: 1.0.0
title: Core review team
description: Fixed members for code review and release gatekeeping.
license: MIT
maintainers: [STofone]
tags: [review, release]

defaults:
  provider: deepseek
  model: deepseek-v4.1-flash
  reasoningEffort: high

members:
  - name: reviewer
    role: Code review
    description: Reviews only, never releases
    aliases: [code-reviewer]
    skills: [frontend-skill]
    examples:
      - Review this change for semantic bugs
    systemPrompt: |
      You review for semantic bugs first, style second.
    toolPolicy: readonly
  - name: release-manager
    role: Release gatekeeper
    systemPrompt: |
      You check the diff, the version and the rollback plan.
    model: deepseek-v4.1-pro
    reasoningEffort: low

captain:
  name: lead
  description: The main session is the captain; it splits work and accepts results
  provider: tsingmicro
  model: deepseek-v4.1-flash
  personaPrefix: |
    Restate the goal and acceptance criteria before delegating.

同目錄可選 capabilities.yaml 聲明部署能力需求（詳見倉庫 Capability requirements 章節）。機器可讀 Schema 位於倉庫 schema/roster.v1.schema.json。

典型用法¶

1、在面板或通過工具瀏覽、編輯全局檔案庫；也可讓模型調用 roster_list 等工具。

2、用 CLI 查看示例庫或校驗當前全局庫（與工具讀同一默認路徑）：

# 查看倉庫內示例庫
npx dsh-agent-roster list --dir examples

npx dsh-agent-roster validate
npx dsh-agent-roster list

3、定義好 roster.yaml 後，通過 roster_create 獲取 agent_teams_add_member 參數（字段映射如 systemPrompt → executionPrompt），再在 dsh-agent-teams 側創建成員；之後用 roster_verify 對照 team.json 檢查是否一致。改名時可用 aliases 避免驗證誤報「未部署 / 未管理」。

倉庫還提供 examples/ 與 examples-orchestration/ 示例；默認 rosterDirs 爲空，僅指向上述全局庫。若要 CLI 直接讀示例，需像上文一樣通過 --dir 指定。

適用場景與注意¶

適合：需要把多 Agent 團隊成員人設、模型與工具策略固化成可評審、可版本化文件，並與 dsh-agent-teams 創建成員流程對齊的團隊；需要在改檔案後覈對運行時狀態的場景。

不適合：期望本插件代替 dsh-agent-teams 做調度、重試或審查環的場景——這些屬於運行時插件職責。

注意：

• skills 等聲明字段不會自動加載 Skill，僅作約定與校驗。
• 插件不寫入團隊狀態；建隊與任務分發仍需在 agent-teams 工作流中完成。
• 安裝與運行權限等同於 DSH 進程；生產環境請先審閱源碼與依賴（yaml、@deepseek-ai/schemastery 等）。

結尾¶

dsh-agent-roster 把多 Agent 團隊的成員定義從「口頭配置」收攏爲磁盤上的校驗文件，並在創建成員時透明橋接到運行時接受的字段，同時用 roster_verify 幫助發現漂移。DSH 生態遵循「一切皆插件」；若要在本地啓用，以插件管理器安裝 @stofone/dsh-agent-roster 爲準。

• 社區目錄：https://www.skillhub.cn/plugins/dsh-agent-roster/dsh-agent-roster
• 源碼與文檔：https://github.com/dsh-agent-roster/dsh-agent-roster