前言¶
在 DeepSeek Harness（DSH）裏做 DevOps 相關智能體時，常見做法是讓人去 OneDev Web 界面點選，或自己寫腳本調 /~api/*。OneDev 本身提供完整的 Git / CI / CD 與管理 REST API，但模型側缺少一套帶鑑權、可枚舉、參數有 Schema 的工具面。
下面介紹的 dsh-onedev（倉庫 Altermoe/dsh-onedev，維護者 Altermoe）是 DSH 社區插件，分類爲模型推理。它內置獨立 MCP 服務 dsh-onedev-mcp，經 DSH 自帶的 @deepseek-ai/dsh-mcp-client 橋接後，OneDev 管理操作會以 mcp__onedev__… 形式出現在 harness 工具列表裏，模型可直接調用，而不必繞 Web UI。
這是什麼¶
dsh-onedev（npm 包名 dsh-onedev，當前版本 0.1.0，MIT 許可證）做兩件事：
- 提供 MCP Server，用 OneDev 訪問令牌或賬號密碼訪問 OneDev REST API（
/~api/*）。 - 作爲 DSH bundle 時，在 dsh Web Settings 增加一級 OneDev 配置區，用卡片管理多環境連接，運行時從憑據存儲讀取，一般無需再配
ONEDEV_*環境變量。
簡介與 GitHub 倉庫標題一致：DeepSeek Harness Plugin for OneDev。
核心功能¶
以下能力均來自項目 README 與 docs/dsh-integration.md。
MCP 工具面¶
- 61 個工具：約 57 個面向管理（用戶、組、角色、組成員與管理員授權、項目、授權、構建 Agent、Agent Token、構建與日誌、全局設置、訪問令牌等）；另有 3 個 OneDev 官方文檔查詢工具，以及 環境發現
onedev_list_environments。 - 通用直連
onedev_api_request：對ONEDEV_URL/~api/*發起任意已鑑權請求，覆蓋未單獨封裝的 REST 面。 - 文檔工具獨立可用：
onedev_docs_search/onedev_docs_read/onedev_docs_list對接 docs.onedev.io，無需 OneDev 連接或憑據即可使用。 - 工具由 Zod 生成 JSON Schema，便於模型理解參數。
多環境與傳輸¶
- 可配置 多個 OneDev 環境（各自 URL、憑據、備註 slug）；除
onedev_list_environments外，各工具可選environment參數，默認指向 primary 環境。 - 兩種傳輸：stdio（推薦給 DSH 本地掛載）與 streamable-http（遠程，路徑
/mcp）。
鑑權與安全¶
- Bearer 訪問令牌（
ONEDEV_TOKEN）或 賬號密碼（ONEDEV_AUTH_TYPE=password+ONEDEV_USERNAME/ONEDEV_PASSWORD，HTTP Basic）。 - 可選 只讀模式
ONEDEV_MCP_READONLY=true拒絕所有 mutating 請求；可配置 API 超時（如ONEDEV_API_TIMEOUT_MS）。
DSH Web 與本地 Setup¶
- 安裝 bundle 後：Settings → OneDev 以卡片展示環境，可新增、編輯、探測連接、設 primary、刪除；Host 提供 loopback
/api/onedev/config與/api/onedev/probe。 - Setup 控制台：
npm run setup（或node bin/dsh-onedev-mcp.mjs --setup）在http://127.0.0.1:8770/錄入 URL 與憑據並持久化（端口可用ONEDEV_MCP_PORT修改），緩解「必須先登錄 Web UI 造 Token」的問題。憑據默認寫入~/.config/dsh-onedev/config.json（權限0600，可用ONEDEV_CONFIG_FILE覆蓋）。
橋接後工具命名規則：serverName 設爲 onedev 時，例如 mcp__onedev__users_list。
環境與依賴¶
- Node.js：
^22.19.0 || >=24.0.0（項目在 Node 26 上開發測試）。 - DSH：作爲 bundle 使用時需 DeepSeek Harness 0.2.x（
engines.dsh:^0.2.0-rc.2）；獨立運行 MCP 不依賴 DSH。 - 可訪問的 OneDev 服務器（示例：
http://localhost:6610）；管理類接口通常需要具備相應權限的 Token 或管理員賬號。
安裝與啓用¶
從源碼構建 MCP¶
在克隆或解壓後的倉庫目錄執行（README 原文）：
npm install # install dependencies
npm run build # compile TypeScript → dist/
npm test # build + unit tests + stdio smoke + HTTP smoke
日常啓動 MCP：
npm start
# 等價於 node bin/dsh-onedev-mcp.mjs
開發模式：
npm run dev
首次配置憑據（可選，與 Web Settings 共用存儲）：
npm run setup
作爲 DSH profile bundle（推薦）¶
docs/dsh-integration.md 說明：v0.1.0 起插件附帶 dsh bundle。將包加入 profile 的 dsh.profile.bundles 並完成安裝後，cordis.patch.yml 會插入 dsh-onedev Host 插件與 dsh-onedev-mcp 的 @deepseek-ai/dsh-mcp-client 行（env: {}）。連接信息在 Settings → OneDev 配置；MCP 每次工具調用從憑據存儲讀取，保存後通常 無需重啓 dsh。
升級 bundle 後需執行 npm run build，並按項目腳本說明重啓 dsh（如 scripts/restart-dsh.sh）。
手動掛載 stdio（YAML 示例）¶
若未走 bundle，可在 dsh 配置中增加 @deepseek-ai/dsh-mcp-client 條目（路徑需改爲你機器上的 絕對路徑）：
plugins:
- id: dsh-onedev
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: onedev
transport: stdio
command: node
args: ['/absolute/path/to/dsh-onedev/bin/dsh-onedev-mcp.mjs']
env:
ONEDEV_URL: !!js process.env.ONEDEV_URL
ONEDEV_TOKEN: !!js process.env.ONEDEV_TOKEN
toolCallTimeoutMs: 60000
failOnStartupError: false
若已通過 npm run setup 或 Web Settings 寫入憑據，env 整段可省略；環境變量與存儲同時存在時，環境變量優先。
HTTP 模式（遠程共享）¶
在可訪問 OneDev 的主機啓動：
ONEDEV_URL=https://onedev.internal:6610 \
ONEDEV_TOKEN="$ONEDEV_TOKEN" \
ONEDEV_MCP_TRANSPORT=streamable-http \
ONEDEV_MCP_HOST=0.0.0.0 \
ONEDEV_MCP_PORT=8765 \
node /absolute/path/to/dsh-onedev/bin/dsh-onedev-mcp.mjs
DSH 側使用 transport: streamable-http 與 url: http://onedev-mcp-host:8765/mcp（詳見集成文檔 Option B）。
典型用法¶
- 發現環境：調用
mcp__onedev__onedev_list_environments，必要時帶{"query":"prod"}；後續工具傳入"environment":"<slug>"。 - 列用戶（主環境）：
mcp__onedev__users_list→{"term":"alice","count":50}。 - 列用戶（指定環境）：
{"environment":"staging","term":"alice"}。 - 授予管理員：先
mcp__onedev__group_get_id→{"name":"Administrators"}，再group_members_add傳入userId與groupId。 - 建項目：
mcp__onedev__project_create→{"name":"team/app","codeManagement":true}。 - 只讀防護：設置
ONEDEV_MCP_READONLY=true。 - 未封裝接口：
mcp__onedev__onedev_api_request→{"method":"GET","path":"/issues?project=app"}。
完整工具表見倉庫 docs/tools.md（由 npm run docs 生成）。
適用場景與注意¶
適合：已在用 OneDev 做 Git/CI/CD，希望在 DSH 對話或自動化裏用自然語言或 Agent 流程操作用戶、項目、Agent、構建與設置；或需要同時管理多套 OneDev 實例的團隊。
務必注意：
- MCP 與 Host 插件在 當前 dsh 進程權限 下運行；Token 或管理員密碼具備的能力即模型可觸達的能力。安裝前請閱讀源碼與 MIT 許可證，並評估是否開啓只讀模式。
- 管理類 Token 需具備文檔所述管理員權限；401/403 多爲 Token 權限或過期問題。
- 社區目錄 skillhub.cn 插件頁 與 GitHub 由社區維護，與 DeepSeek / 幻方無官方從屬關係；DSH 生態遵循「一切皆插件」，本文事實以倉庫文檔爲準。
結尾¶
dsh-onedev 把 OneDev 管理 REST API 收成 MCP 工具集，並可選 Web / Setup 管理多環境憑據，適合把 OneDev 運維納入 DSH 智能體工作流。進一步瞭解可訪問 目錄頁 與 GitHub 倉庫（含 docs/dsh-integration.md 與 docs/onedev-api.md）。
