前言¶
在 DSH 裏做 Agent 或本地助手時，常見窘境是：模型要查 CPU、進程、已裝應用或改 DNS，只能讓你自己開終端、翻系統設置，或零散寫腳本。信息分散在多處，操作也難和白名單化對齊，既不利於人機共讀一份「設備真相」，也不利於工具調用走同一條實現。
下面介紹社區插件 Device X（cfour-hi/dsh-plugin-devicex）：在 DSH 左側欄提供持久化客戶端面板，把硬件、系統、軟件、網絡、安全、進程等收成十個標籤頁；對非硬件能力支持界面操作，並通過 device_info、device_control、device_benchmark 暴露給 Agent。維護者爲 cfour-hi，分類爲客戶端；當前包版本爲 1.5.0，許可證 MIT。
這是什麼¶
Device X 是一個持久化的 DSH 插件：用一頁中文/英文界面彙總當前設備信息，並對除硬件外的項目做直接操作（結束進程、啓停應用、改主機名、開關 Wi-Fi/防火牆、清理緩存等）。同一套能力在 Host 側統一實現，UI 與 Agent 工具共用，避免出現兩套邏輯。
支持平臺爲 macOS 與 Windows 10/11。採集與動作按 process.platform 分流（darwin 用系統命令，win32 用 PowerShell/CIM）；瀏覽器 UI、HTTP API、Agent 工具在兩個平臺上保持一致。
核心功能¶
界面與信息分區¶
入口在 DSH 左側欄底部 Device X 面板圖標（位於 Plugins、Schedules 之後），點擊進入中央主面板。界面共十個標籤，跟隨 DSH 主題着色，並支持 prefers-reduced-motion：
| 標籤 | 作用概要 |
|---|---|
| 總覽 | CPU/內存/磁盤/電池/網絡 KPI、火花線、Top 進程與派生告警 |
| 硬件 | CPU 逐核、內存、GPU、磁盤、電池、溫度與散熱、驅動/內核擴展（只讀）等 |
| 系統 | 系統版本、啓動時長、用戶、登錄項與 LaunchAgents（可啓停） |
| 軟件 | 已裝應用（搜索、卸載）；macOS 展示 Homebrew，Windows 展示 winget |
| 網絡 | 網卡、Wi-Fi、DNS、代理、監聽端口；可開關 Wi-Fi、設 DNS |
| 安全 | FileVault/BitLocker 等狀態卡、防火牆、跳轉系統隱私/安全設置 |
| 進程 | 可排序進程表，逐行結束（二次確認） |
| 清理 | 掃描可安全清理位置，勾選後二次確認才刪除 |
| 性能 | CPU/內存/磁盤固定工作量基準，可與上次結果對比 |
| 操作 | 19 個白名單動作分組建表單，危險操作二次確認 |
單個動作失敗時，僅在對應卡片或彈窗內報錯，不會拖垮整頁或插件。
Agent 工具¶
Host 註冊三個 Agent 工具，與 UI 同源：
device_info：section可取overview | hardware | system | software | network | security | processes | cleanup；fresh可繞過緩存。device_control：action爲動作 id，params爲參數，與 UI 走同一實現。device_benchmark：可選tests（cpu|memory|disk）與repeat，引擎與「性能」標籤頁相同。
動作與白名單（19 項）¶
動作全部白名單化並做嚴格參數校驗，涵蓋進程信號、應用啓停/卸載、主機名與音量/深色模式、LaunchAgent 或 Windows 啓動項、打開系統設置、防火牆、DNS 刷新、清空廢紙簍、Wi-Fi/DNS、睡眠/鎖定、Homebrew/winget 卸載、確認後的 cleanup.delete 等。macOS 與 Windows 使用相同動作 id，平臺差異在 README 的 Windows 映射表中說明（例如 Windows 上 process.signal 不支持 STOP/CONT）。
HTTP API¶
瀏覽器通過同源 /devicex/api/* 訪問，落在 DSH Connection 信任柵欄之後（簽名會話 cookie + Host/Origin 校驗）。主要路由包括：
GET /devicex/api/metrics— 指標輪詢（UI 約 2500ms）GET /devicex/api/inventory— 分區或完整清單GET /devicex/api/actions/POST /devicex/api/action— 動作目錄與執行GET /devicex/api/cleanup— 清理掃描POST /devicex/api/benchmark— 運行基準
子進程通過 execFile 參數數組執行，不經 shell；路徑參數有根目錄與後綴校驗；動作歷史保留最近 50 條。
安裝與啓用¶
資料中的安裝方式有兩類，未在已抓取片段中出現統一的 dsh plugin add … 單行命令時，不宜自行拼接：
- 本地 link：將包目錄
plugin/鏈到當前 desktop profile，安裝結果應爲application: applied。 - Git 安裝入口：倉庫根目錄的
package.json可作爲安裝目標；具體步驟見 GitHub README 中「分享給其他人安裝」一節。
安裝前請閱讀 插件目錄頁 與倉庫 README 及 LICENSE。插件聲明支持 darwin 與 win32 平臺。
典型用法¶
在界面中查看與操作¶
- 啓動 DSH 並確保插件已應用到 desktop profile。
- 點擊左側欄底部 Device X 圖標，在十個標籤間切換查看清單或實時指標。
- 在「進程」中搜索 PID 後結束進程；在「操作」中選擇白名單動作並填寫參數；清理類操作需先掃描再勾選確認。
Agent 拉取分區信息¶
邏輯上等價於調用 device_info，指定 section 與可選 fresh。例如需要完整軟件清單時，將 section 設爲 software；需要繞過緩存時設 fresh。
Agent 執行本機控制¶
通過 device_control 傳入 README 動作表中的 action 與對應 params，與 UI「操作」標籤使用同一後端。卸載應用、改 DNS、切換防火牆等涉及權限的動作，失敗時 Host 會返回 stderr 等信息，應在 Agent 流程中如實處理。
本機性能對比¶
在「性能」標籤或通過 device_benchmark 運行固定工作量測試。文檔說明：分數僅適合同一臺機器前後對比，不作跨設備排名依據。
適用場景與注意¶
適合誰
- 需要在 DSH 內一眼掌握本機狀態、又不想反覆開系統監視器或 PowerShell 的開發者。
- 希望 Agent 以結構化工具讀取
device_info、以白名單方式執行device_control，而不是讓模型自由拼 shell 的團隊。 - 在 macOS 與 Windows 上希望 UI 與工具語義一致的場景。
務必注意
- 插件以 當前 DSH 進程權限 運行；結束進程、卸應用、改防火牆、清理文件等操作影響真實系統，安裝前應審閱源碼與 MIT 許可證，並只在可信環境啓用。
- 客戶端插件走 DSH 信任柵欄，未認證請求返回 401，異源 403；這不替代你對動作白名單與參數含義的理解。
- 硬件相關分區（含溫度、驅動清單等）以只讀爲主；基準測試會佔用 CPU/磁盤，宜在空閒時運行。
- 社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係；星標與熱度以各站點當時數據爲準。
結尾¶
Device X 把「看清本機」和「對白名單內的可控項動手」收到同一插件裏：面板給人用，三個 Agent 工具給模型用，Host 在 macOS 與 Windows 上各走一套採集/動作實現，前端與 API 保持一致。若要進一步瞭解安裝分享方式、動作表與工程驗證腳本，請以倉庫文檔爲準。
