前言¶
在 DSH（DeepSeek Harness）裏跑智能體時，常見做法是換模型、接 MCP，或自己寫子進程通道。若你已經在 macOS 上用 ZCode 桌面 app 做項目級編碼，又希望 DSH 裏的模型能把整段任務交給 ZCode、等它做完再把答案取回，就需要一條不依賴 ZCode CLI 或 stdio 的橋。社區插件 dsh-zcode-native（維護者 ORIOW）走 ZCode 的 CDP 調試端口讀寫界面 DOM，同時提供本機狀態看板與原生子代理工具 subagent_zcode，把「派活—等待—取答」收成閉環。下面介紹它是什麼、怎麼裝、怎麼用，以及使用時的硬約束。
這是什麼¶
dsh-zcode-native 是 DSH 的原生插件，分類爲工作流。一句話定位：把 ZCode 桌面 app 變成 DSH 的子代理後端 / 派活通道——宿主裏的模型可以把完整任務派給 ZCode，完成後取回答案。實現上不依賴 ZCode 的 CLI、stdio 或其他通道；只要桌面上開着帶 CDP 端口的 ZCode 即可。
插件在架構上拆成兩個半身：
- host 半身（
lib/index.js等，跑在 DSH 宿主 Node 進程）：HTTP 路由（僅 loopback）、CDP 客戶端連127.0.0.1:<debugPort>、只讀狀態採集、派活狀態機、原生子代理 provider（註冊名zcode）。 - client 半身（
lib/client.js，注入 DSH Web 界面）：右側邊欄「ZCode 看板」tab、設置卡里控制看板開關的選項。client 只通過同源 HTTP 讀 host 路由，不直連 CDP。
目錄頁：skillhub.cn/plugins/ORIOW/dsh-zcode-native。源碼與說明：github.com/ORIOW/dsh-zcode-native（當前發佈版本 v0.1.0，許可證 MIT）。社區插件目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
本機 HTTP 接口（host，僅 loopback）¶
GET /plugins/dsh-zcode-native/status：只讀快照，含賬號摘要（不暴露 token 正文）、客戶端可達性與版本、套餐、catalog 模板等；在cacheMs內返回緩存。POST /plugins/dsh-zcode-native/ask：派活。請求體{"prompt": "..."}（上限 64 KiB），寫入 ZCode 輸入框並取回答案；多請求在插件內串行排隊，生成中會返回busy。
工具 subagent_zcode¶
把 ZCode 註冊爲 DSH 原生子代理後端。模型可見參數只有：
description（必填）：任務簡短描述（3–5 個詞）；prompt（必填）：完整自包含的任務文本（ZCode 看不到當前 DSH 對話）。
取消或超時會嘗試點擊 ZCode 的「停止生成」，避免空轉生成阻塞後續派活。派活前會記錄標題欄項目名；中途切換會話會以 session-changed 失敗，不會誤用其他項目的回答。
側邊欄 ZCode 看板¶
DSH 右側邊欄出現「ZCode」tab：賬號、套餐到期、餘額接口可達性（插件實測餘額 API 常報參數錯誤，看板如實顯示不可用、不猜測數值）、客戶端版本、catalog 模板數等；約每 60 秒自動刷新，也可手動刷新。可在設置卡關閉（偏好存 localStorage，key dsh-zcode-native:sidebar，默認開啓）。
配置項¶
可在 profile 的 cordis.patch.yml insert 塊裏覆蓋（定義於 lib/index.js 的 Config）：
| 字段 | 類型 | 默認值 | 說明 |
|---|---|---|---|
debugPort |
number | 9222 |
ZCode 的 CDP 調試端口 |
cacheMs |
number | 15000 |
/status 快照緩存有效期（毫秒） |
askTimeoutMs |
number | 600000 |
派活等待答案超時（毫秒） |
前置條件與安裝¶
環境¶
- macOS（Windows / Linux 未驗證）；DSH Desktop 與 ZCode 3.17.1。
- ZCode 必須用 CDP 端口啓動，且需先完全退出（Cmd+Q）再從終端啓動，否則 Electron 單實例會拒絕
--remote-debugging-port：
/Applications/ZCode.app/Contents/MacOS/ZCode --remote-debugging-port=9222
倉庫也提供 scripts/zcode-debug.sh（默認 9222，會先退舊實例再啓動）。
安裝與啓用¶
在 DSH 裏裝最省事：設置 → 插件 → 安裝插件，粘貼：
github:ORIOW/dsh-zcode-native#v0.1.0
等價 CLI（只裝依賴，裝完還須在插件頁勾選啓用 dsh-zcode-native）：
dsh plugin --profile web add "github:ORIOW/dsh-zcode-native#v0.1.0"
裝完重啓 DSH Desktop（host 半身不熱重載）。開發時可本地 link: 掛載或 .tgz/絕對路徑安裝，詳見 README 的 B、C 兩節。
安裝前建議自行瀏覽源碼與 MIT 許可證；插件以當前 DSH 進程權限運行，會讀取 ~/.zcode/v2/credentials.json 並按 ZCode 同源算法解密信封，token 僅用於本機請求 https://zcode.z.ai 的套餐相關接口，不回顯、不進 HTTP 響應。
典型用法¶
裝好後在 DSH 里正常對話即可，模型可調用 subagent_zcode，也可直接 POST /plugins/dsh-zcode-native/ask。README 中的示例意圖如下：
用 ZCode 查一下
~/Projects/foo裏pnpm test爲什麼在第 3 個用例掛掉，把根因和改法帶回來。把這個倉庫的
lib/ask.js通讀一遍，列出所有會拋錯的分支和它們的錯誤碼。
三條硬規則（ZCode 看不到 DSH 對話）：
- prompt 必須自包含：路徑、驗收標準寫全，不要用「上面那個文件」。
- 派活前讓 ZCode 停在目標項目會話：composer 只屬於當前可見會話；切走會
session-changed失敗。 - 一次一件活：串行隊列，忙時新任務爲
busy。
默認最多等 10 分鐘（askTimeoutMs 可調）。派活日誌在 ~/Library/Logs/DSH Desktop/harness.log，關鍵字 [zcode-native]；prompt 與答案正文不進日誌，只記長度。
適用場景與注意¶
適合：已在 macOS 上用 ZCode 3.17.1 做項目編碼，希望在 DSH 工作流裏把獨立子任務（讀倉、跑測、通讀文件等）交給 ZCode，並在界面側邊欄一眼看到賬號與套餐狀態。
注意：
- 插件不會替你啓動 ZCode 或切換項目；CDP 端口、目標會話都需你手動準備好。
- 一次只服務一個 ZCode 會話，派活串行；界面 DOM 隨 ZCode 版本變化可能導致選擇器失效（當前按 3.17.1 校準）。
- 所有 HTTP 路由僅接受 loopback，非本機來源 403。
結尾¶
dsh-zcode-native 把 ZCode 桌面端接成 DSH 的狀態看板、CDP 派活閉環與原生子代理後端，適合「DSH 編排 + ZCode 動手」的分工。進一步瞭解可打開 目錄頁 與 GitHub 倉庫。
