前言¶
在 DeepSeek Harness 裏做架構梳理或流程說明時，常見做法是留在 Markdown 裏畫 Mermaid，或切到外部繪圖工具再貼截圖。前者交互弱、難和倉庫證據對齊；後者和當前會話脫節，改一版就要重新導出。apitu 是面向 DSH 桌面的客戶端插件：由當前會話裏的模型讀源碼或需求、寫出符合 schema 的 JSON，插件在本地渲染成交互式 HTML，並提供中文右側欄與原生工具 apitu，不另配模型賬號或 API Key。
這是什麼¶
apitu（倉庫 yueyexiayu/dsh-apitu，社區目錄 skillhub.cn/plugins/yueyexiayu/dsh-apitu）由維護者 yueyexiayu 發佈，分類爲客戶端。當前插件包版本爲 1.2.4（MIT），內置圖表核心標識 3.1.0（vendored 上游來源標識，帶本地缺陷修復，不冒充上游新發行版）。一句話定位：把當前會話中的想法、需求或代碼證據製作成交互式 HTML 圖。
核心功能¶
下面介紹插件已文檔化的能力邊界，避免和舊 viewer 或獨立 Mermaid 服務混淆。
六種圖類型¶
支持 roadmap、architecture、workflow、sequence、dataflow、lifecycle。其中默認 roadmap 使用 api-sheji 風格中文雙 SVG 站點地圖（縮放/平移、F/A 編號、點擊提示、路線篩選與流動光點等），不含舊 viewer 的主題、搜索、演示或 PNG/SVG/WebM 導出；其餘五型仍保留主題、搜索、關係追蹤、演示和導出。Roadmap 規範與示例位於包內 vendor/core/references/roadmap.md、vendor/core/schemas/roadmap.schema.json 等路徑。
對話工具與 CLI¶
Host 側通過 JSON 動作調用，例如 guide 返回創作入口與 skill 正文；read 按 offset 分頁讀 schema；run 在指定絕對項目目錄下執行 CLI（如 finalize 走 validate → deliver → check → browser-check）。Mermaid、自然語言或倉庫證據由當前 AI 閱讀 skill 並轉換爲 typed JSON，不是獨立 Mermaid CLI 或額外模型服務。
CLI 子命令包括 render、compare architecture、deliver、finalize、preview、validate、migrate workflow、inspect architecture|roadmap、check、browser-check、visual-check、guide、examples、doctor、demo 等；核心入口爲 vendor/core/bin/apitu.mjs。preview 爲本機持續預覽，修改 JSON 可熱更新；成功構建的 HTML 經大小與 SHA-256 覈對後進入任務產物列表。
側欄與文件策略¶
右側欄選擇 apitu，填寫項目絕對工作目錄。側欄關聯當前存活會話，由 Host 查詢真實會話並應用與對話工具一致的文件策略，不接受前端指定策略模式。默認 roadmap 可生成六類示例、渲染已有 JSON、查看本會話任務結果並打開 HTML。
CLI 子進程不能繼承受限 DSH 文件沙箱，僅在 danger-full-access 策略下執行；只讀與 workspace-write 等模式會明確拒絕。讀取插件內文檔不受此限制。
安裝與啓用¶
當前執行策略接入版爲 1.2.4。本機按 profile bundle 加載（package.json 的 dependencies + dsh.profile.bundles），包內 patch 的 name 爲 apitu。修改後需 完全退出 DeepSeek Harness 後重新打開；重啓後用工具 guide 或側欄 GET 確認 version: "1.2.4" 再驗收。
先做 clone，再做 profile 依賴與安裝：
export DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
git clone https://github.com/yueyexiayu/dsh-apitu.git "$DSH_HOME/plugins/apitu"
然後把 apitu 寫入 $DSH_HOME/profiles/desktop/package.json 的 dependencies（link: 到該目錄）和 dsh.profile.bundles，在 profile 目錄執行 pnpm install，完全退出後重開 DSH。不要再對同一 id 做 desktop insert。
需要 finalize、瀏覽器或視覺檢查時，在本插件目錄安裝固定無頭依賴（Node.js ≥ 18，文檔示例使用 /usr/local/bin/node；瀏覽器側依賴 playwright-core@1.58.2）。兼容性說明：目前文檔寫明 macOS arm64 有經過驗證的安裝校驗 manifest；Linux、Windows 等爲 unsupported/unverified，安裝前請自行覈對 README「運行環境」一節。
典型用法¶
- 在對話中說「用 apitu 給這個項目畫架構圖」或「用 apitu 畫訂單支付流程」。當前會話模型負責讀源碼/需求、生成符合 schema 的 JSON，再調用插件。
- 右側欄選擇 apitu，填寫絕對工作目錄，按需選
roadmap或其它類型。 - 需要交付物時，先用 DSH 文件工具寫好 JSON，再調用
run（目錄僅爲示例）：
{
"action": "run",
"cwd": "/absolute/project",
"args": ["finalize", "architecture", "candidate.json", ".apitu/new-run/diagram.html", "--json"]
}
自動檢查通過不等於人工視覺檢查通過；ok:false、非零 exitCode、stderr 或 receipt gate 失敗時必須修復後再交付。失敗或視覺修復後應重跑完整 finalize，使用新產物路徑（例如 .apitu/new-run/repair-2/diagram.html），只改 --out-dir 不夠。
查規範時可從工具入口分頁讀取：
{"action":"guide"}
{"action":"read","resource":"schemas/architecture.schema.json","offset":1,"limit":180}
適用場景與注意¶
適合在 DSH 桌面裏和當前會話聯動：架構圖、工作流、時序、數據流、生命週期和 roadmap 站點圖，產物爲本地 HTML，可在側欄打開。
務必注意：
- 插件以當前 DSH 進程權限運行；安裝前應閱讀倉庫源碼與 MIT 許可證，確認
danger-full-access與本地文件寫入範圍可接受。 - 普通任務最多運行 180 秒，輸出上限 2 MiB；持續 preview 另有併發與保留策略（文檔：最多 8 個活動預覽等）。
cwd須來自真實會話目錄或用戶顯式填寫，僅支持本地文件系統。- 社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；星標等元數據以目錄頁爲準（當前爲 0）。
結尾¶
apitu 把「會話裏的結構化描述 + 本地校驗與渲染」收進一個 DSH 客戶端插件：中文側欄、原生 apitu 工具、六種 typed 圖與可選 headless 驗收鏈。進一步細節見 GitHub README 的「完整能力與邊界」「執行策略」「運行環境」各節，以及目錄頁 yueyexiayu/dsh-apitu。
