dsh-general-agentics

dsh-general-agentics

General Agentics 發行套件（bundle）for DeepSeek Harness (DSH)。

用戶先安裝 DSH，再安裝本套件，一次獲得：

1. 貼牌：側邊欄 mark/wordmark、對話首頁 hero 文字 logo 與致敬行、品牌主色、分頁標題、favicon、輸入框下方的 START HERE 模塊（皆為執行期替換，不修改、不破壞已安裝的 DSH）
2. 自帶技能：14 個（ga-identity ＋ 13 個方法論技能，見下）
3. MCP 預配置：ga-status（ga_bundle_info 身分回報 ＋ ga_health_check 安裝健康自檢）
4. 設定面板：Settings → General Agentics（bundle 版本、每個精選插件的版本與更新狀態、隨附技能、一鍵／手動更新）
5. 13 個精選第三方插件：隨套件安裝並啟用（見「精選插件」一節）

Built on DeepSeek Harness (DSH), MIT licensed.

設計原則

• 只走官方縫隙：品牌透過三個 generic brand slot 佔位（priority: -1 陰影覆蓋官方 occupants——slot 規則是「同 cell 最低 priority 者渲染」），不停用 ui-brand-official，不修改任何 DSH 檔案。
• 不破簽章、不怕升級：本套件存在於 profile（~/.dsh/profiles/<name>/node_modules），DSH 升級不會覆蓋它；解除安裝即完全還原官方品牌。
• 手寫、零建置：lib/client.js 採用 shell module loader 的 lazy-CJS 形狀（與 dsh-pomodoro 等第三方出貨格式一致），無需 repo 內未發佈的 build preset。

覆蓋範圍（誠實清單）

安裝

# 方式一：GUI（App 運行中）——側欄 Plugins → Add plugin → 貼包名或本機路徑
dsh-general-agentics            # npm 包名（發佈後）
/path/to/dsh-general-agentics   # 本機 clone 的絕對路徑

# 方式二：模型側工具（App 運行中）——對話中請 agent 執行
#   plugin_manager { action: "install_bundle", target: "dsh-general-agentics" }

# 方式三：CLI（desktop profile 須先完全退出桌面 App）
dsh plugin --profile desktop add dsh-general-agentics

安裝後：

• 網頁重新整理一次（Cmd+R）即可載入品牌 client half（側邊欄 mark/wordmark、hero 文字 logo 與致敬行、主色、分頁標題、favicon、輸入框下方的 START HERE 模塊）
• 新建的 session 會獲得 ga-identity 等 14 個技能與 mcp__ga-status__ga_bundle_info 工具（MCP 伺服器於組合套用時即由 host spawn）
• 完全重啟 App 亦無妨

解除安裝／停用：

# 停用（保留檔案）：GUI Plugins 頁關閉 bundle，或在 profile 的 cordis.patch.yml 寫：
#   - id: general-agentics
#     disabled: true
# 解除安裝：GUI Plugins → Remove，或退出 App 後 CLI：
dsh plugin --profile desktop remove dsh-general-agentics

開發迭代：以 link: 指向本機 clone 安裝——改 lib/client.js 後重新整理頁面即生效； 改 cordis.patch.yml 或 lib/index.js（host 半）則套用新組合（HMR live）。 內容變更後重新以 file: 安裝時記得升版號——pnpm 對同版號的 file: 包可能不重新解包。 離線驗證組合用拋棄式 profile：見 docs/ops-lessons.md rule 13。

發布前注意：

• LICENSE 已在 repo 根目錄（npm 自動收入 tarball）
• MCP row 已是可攜形式（process.execPath + baseUrl，見 cordis.patch.yml；實測紀錄在 docs/ops-lessons.md rule 14）
• 對外表述維持 "Built on DeepSeek Harness (DSH), MIT licensed"

套件結構

dsh-general-agentics/
├── package.json        # dsh.bundle.patch + dsh.client 宣告＋精選插件 dependencies
├── cordis.patch.yml    # 本套件 Loader row＋MCP row＋精選插件 insert rows
├── lib/
│   ├── index.js        # host half：技能 provider（掃 skills/ 註冊）
│   └── client.js       # browser half：品牌 slot、主題、標題/favicon、START HERE
├── brand/
│   ├── mark.svg        # 佔位 mark 設計檔（client.js 內有對應 inline 版本）
│   └── wordmark.svg    # 佔位 wordmark 設計檔
├── skills/
│   ├── ga-identity/    # 自帶技能：General Agentics 身分與簽署
│   ├── (13 個方法論技能)  # vendored from obra/superpowers @ bb92a77（MIT，逐字未改）
│   ├── superpowers/    # 上游 LICENSE + UPSTREAM-SHA（無 SKILL.md，不註冊）
│   └── THIRD-PARTY.md  # 署名與更新指引
├── mcp/
│   └── ga-status-server.mjs  # ga_bundle_info 狀態回報（零依賴 stdio MCP server）
└── test/
    └── skill-provider.test.mjs  # node --test，零依賴

換正式品牌素材

隨附技能（bundled skills）

14 個技能隨包註冊（ctx.skills.registerProvider，bundled rank 600——用戶自帶同名技能一律優先）：

• ga-identity：以 General Agentics 身分自介與簽署產出
• 13 個方法論技能 vendored 自 obra/superpowers（MIT，逐字未改）： brainstorming、writing-plans、executing-plans、test-driven-development、systematic-debugging、verification-before-completion、writing-skills、diagnosing-superpowers、subagent-driven-development、dispatching-parallel-agents、requesting-code-review、receiving-code-review、finishing-a-development-branch ——15 個上游技能取 13；using-superpowers（其「任何回應前必查技能」規則與 ga-identity 的身分主導權衝突）與 using-git-worktrees（團隊 git 工作流）刻意不入，理由見 skills/THIRD-PARTY.md。

感謝：Jesse Vincent (obra) 與 superpowers 貢獻者；詳見 skills/THIRD-PARTY.md。

精選插件（curated plugins）

隨套件安裝並自動啟用（dependencies ＋ cordis.patch.yml 的 insert row；row id 一律 ga- 前綴，避免與用戶直裝的同名插件撞 id）。

DSH 版本相容性（0.2.1 的安裝閘門）

DSH 0.2.1 起，安裝時會先讀插件的 manifest 檢查相容性（dsh-app-boot 的 plugin-compatibility）：有 engines.dsh 就只看它，否則檢查它對 @deepseek-ai/dsh* 的 peer 範圍，用 semver.satisfies(..., {includePrerelease:true}) 判斷。只要有一個插件不合格，整個安裝會被拒絕並回滾。

因此本套件：

• 宣告 engines.dsh: ">=0.2.1-rc.2"（只用 >=，才不會把 rc 版擋掉）
• 精選清單以 0.2.1 可接受的版本為 floor；發佈前用 npm run check-dsh-compat 核對
• 兩個插件目前不納入（在 0.2.1 上無法安裝，非我們能修）：

  插件	原因
  @michengai/dsh-agency-agents	所有已發佈版本的 peer 只列出 0.1.x 的 dsh，沒有任何版本被 0.2.1 接受
  dsh-web-search-pro	0.2.x 全部封頂 <0.2.1-0；唯一能過的是 0.1.2（降級，故不納入）
  需要它們時可手動安裝並自負風險：

  dsh plugin --profile <p> allow-version <pkg>@<ver> --dsh-version 0.2.1-rc.2 --accept-risk
  

  上游發佈相容版本後，把 row 加回 cordis.patch.yml 即可（test/bundle-manifest.test.mjs 會檢查依賴與 row 是否一致）。

設定面板（Settings → General Agentics）

設定側欄多一個 General Agentics 分頁，回答「這個 bundle 到底裝了什麼、要不要更新」，並在介面上分成五個區塊：

1. 狀態總覽：版本、狀態 chip（已是最新／N 項待處理／可更新）、檢查時間，以及「重新檢查」
2. 需要注意：缺少外部依賴（uv 等，附一鍵複製修法）、未提供（可複製安裝指令）、直裝重複
3. 更新：一鍵更新（二次確認）＋進度計時＋aria-live，失敗顯示 code 與原因，並有可複製的手動指令
4. 精選插件：依用途分組（搜尋／介面／行動／自家／通訊），可篩選（全部／有新版／需注意／未提供）與搜尋；每列可展開看宣告範圍、已裝與 registry 版本、落後原因、複製安裝指令與 npm 連結
5. 隨附技能與前置條件（無法隨 npm 套件提供的項目，標示已就緒／需自行確認）

首次開啟會有一張可關閉的「這個 bundle 給了你什麼」引導卡。面板語言跟隨瀏覽器（zh/en，可用 localStorage['general-agentics/lang'] 覆寫），所有字串來自兩份鍵集相同的字典。

• bundle 版本：目前版本 vs registry 最新版（本地開發版領先 registry 時會標「本地版本領先 registry」而不是誤報有更新）
• 13 個精選插件：每個的宣告範圍、實際已安裝版本、registry 最新版，以及 有新版 / 最新 / 未提供 / 直裝重複 標記（後者代表這個 profile 又直裝了一份，會啟用兩次）
• 14 個隨附技能：名稱清單
• 更新：一鍵更新走 profile 的 plugin manager（installBundle）；沒有 manager 的 profile 會顯示可複製的手動指令（desktop profile 的 CLI 被 Electron 獨佔，請用面板按鈕）。link:／file: 安裝會額外提示「更新會改用 registry 版本」
• 精選插件怎麼更新：插件是上游 npm 套件的依賴，bundle 升版本身不會移動插件版本（pnpm 以 lock 為準）；只有當該次發佈提高了 floor（例如 ^0.68.1 → ^0.72.0）時，一鍵更新才會把插件一起帶上去。發佈前用 npm run check-upstream 看差距，提 floor 後必須在乾淨 profile 驗證過再發（0.x 的 minor 依 semver 可能不相容）

資料來自 host 半註冊的唯讀端點 GET /api/general-agentics/status（?plugins=1 才逐一查 registry，避免每次開面板都打 13 個請求）；POST 同一路徑才會實際觸發更新。registry 不可達時面板仍會渲染，只是版本欄顯示「未知」。

開發與 CI

npm test                 # 61 個測試：組合一致性、端點授權、i18n 字典、MCP、面板 payload
npm run ci               # 與 GitHub Actions 相同的閘門（測試 + 打包演練）
npm run review           # 對抗式探針（回滾失敗、stale 記錄、去識別化、資源上限…）＋上游新鮮度報告
node scripts/check-upstream.mjs   # bundled floor 與 catalog 的新鮮度對照
npm run prepublish-check # 再加上 overlay 的 YAML 解析（發佈前自動執行）

ci/github-actions.yml 是這個 repo 的 workflow。它放在 ci/ 而不是 .github/workflows/， 因為推送 workflow 需要 token 的 workflow scope；啟用方式（CLI 一行或 GitHub 網頁貼上） 寫在 ci/README.md。啟用前，npm run ci 提供等價的本地閘門。

面板能做什麼（0.2.0-alpha.25）

首頁 START HERE 的每張卡標出它引用的技能（能力地圖）。面板語言跟隨 App 的 locale 服務（取不到才退回瀏覽器語系），可中英切換。

安全模型

可選：需要風險豁免的插件（agency-agents）

@michengai/dsh-agency-agents 會被 DSH 0.2.1 的安裝閘門拒絕：它宣告的 @deepseek-ai/dsh* peer 只列出 0.1.x 的版本，沒有任何已發佈版本被 0.2.1 接受。因此不能放進本 bundle 的預設清單（那會讓所有新用戶安裝失敗），但實測它在 0.2.1 上可正常運作——只要對「精確的套件版本 + 精確的 DSH 版本」給一次豁免：

// ~/.dsh/profiles/<profile>/compatibility.json
{ "@michengai/dsh-agency-agents@1.0.20": ["0.2.1-rc.2"] }

或執行 dsh plugin --profile <p> allow-version @michengai/dsh-agency-agents@1.0.20 --dsh-version 0.2.1-rc.2 --accept-risk（desktop profile 的 CLI 被 App 獨佔，需在 App 內操作或走手動路線）。之後把它加進該 profile 的 dependencies 與 dsh.profile.bundles，再用該 App 自己的 pnpm 安裝。dsh-web-search-pro 同理（0.2.x 封頂 <0.2.1-0）。

安裝注意（常見「插件沒出現」的原因）

1. 不要同時直裝這些插件。若該 profile 已經直裝任一精選插件，它會出現兩行 row、激活兩次（insert 不去重），舊版還會讓設定頁完全存不進去。裝本套件前先移除直裝，或用 ga_health_check 檢查（見下）。
2. 品牌外觀要重新整理頁面（Cmd+R）才會載入；技能與 MCP 工具只出現在新建的 session。
3. 缺外部條件不是壞掉：browser-use 要 uv、modlens 要 Antigravity CLI、dsh-im 要 IM 憑證——裝了不會報錯，但功能不會出現。
4. 專家團預設停用是上游設計，要在 設定 → 专家 手動啟用（團隊與成員都要）。
5. Windows 提醒：cordis.patch.yml 的 MCP row 用 new URL(...).pathname，Windows 上會得到 /C:/…；屆時 ga-status 起不來（非致命，工具消失），需改成 win32-aware 寫法。

自我診斷：新 session 中請 agent 呼叫 mcp__ga-status__ga_health_check，它會回報套件版本、哪些精選插件被直裝（重複）、以及每個插件缺哪個外部條件與該怎麼做。

合規備忘

• 本套件 MIT；散布時保留 DSH 的 MIT 與 THIRD_PARTY_NOTICES.md（DSH 端授權義務）。
• 對外表述使用 "Built on DeepSeek Harness (DSH)"；不以 DeepSeek Harness 作為產品名，不使用官方 logo。
• ga-identity skill 內含給 agent 的對外表述規則。