dari-docs 詳細教學

對應 repo: https://github.com/mupt-ai/dari-docs（34 stars / 0 forks / v0.1.5，截至 2026-05-21）

1. 專案定位

1.1 它是什麼

mupt-ai 公司開源的 「測你的文件能不能被 agent 跑通」工具。把 docs 包 tarball 上傳給 dari.dev hosted agents（或自家 dari.dev org 的 agents），讓 simulated developer agent 試著按文件完成 task，最後產出兩種結果：

  1. failure report：哪邊卡住、哪邊有 ambiguity、哪邊需要猜
  2. optimize 模式下還會產 docs edit 建議（下載到 .dari-docs/updated/）

1.2 它解決什麼問題

過去寫 docs 的問題：

  • 「人類覺得清楚但 agent 看不懂」— 隱性假設、scattered context、不一致術語
  • 「docs lint 工具無法量化」— 拼字檢查與連結驗證測不出可讀性
  • 「agent 在 production 用你的 docs 時失敗」— 不知道為什麼失敗

dari-docs 把問題量化：在 sandbox 跑 agent → 收集失敗點 → 對應到 docs 行數 → 提建議。

1.3 與其他 docs 工具差異

工具量化方式對 agent 友善度
dari-docsagent 真的跑 docs / 失敗 → 對應行✅ 直接測
Vale / markdownlint規則式（術語 / 風格）❌ 只看文字
ChatGPT 手動問沒重現性 / 沒收集失敗點🟡 不重複
人類 user test慢、昂貴🟡 不可規模化

1.4 適合誰用

  • SDK / API 維護者：想知道「使用者跟著 quickstart 真的能 ship 嗎」
  • DevRel team：想自動化測「installation guide / first call」流程
  • 企業內部 docs 團隊：想把 docs 品質做成 CI 必過 gate
  • dari.dev 用戶：本來就在用 dari.dev hosted agent infra 的人
  • AI agent 框架作者：想看 production-grade「CLI + hosted backend + agent infra」全棧 reference

2. 安裝指南

2.1 安裝 CLI（macOS / Linux）

1# 1. 一鍵安裝（會走 install.sh 從 release 抓 binary）
2curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-docs/main/install.sh | bash
3
4# 2. 確認版本
5dari-docs --version
6dari-docs --help

install.sh 行為（從 source 推出來）：

  • 偵測 OS（darwin / linux）+ arch（x86_64 / arm64）
  • curl GitHub Releases /latest 取得最新 tag
  • tar 解壓對應 archive 到 ${DARI_DOCS_INSTALL_DIR:-/usr/local/bin} 或 ~/.local/bin
  • 用 install 命令把 binary 設好權限

2.2 環境需求

  • macOS（Intel / ARM）或 Linux（x86_64 / arm64）
  • 對 managed 模式：只需要 Supabase 登入（瀏覽器流程）
  • 對 self-managed 模式：要有 dari.dev account + API key + 自己部署的 agents
  • 對 local development：Docker（compose 起 postgres + backend + frontend）

2.3 本地完整 stack（contributor 用）

1# 從 source 跑全部 services
2git clone https://github.com/mupt-ai/dari-docs && cd dari-docs
3cp .env.example .env
4# 編 .env：填 SUPABASE_URL + SUPABASE_PUBLISHABLE_KEY（範例檔已有 dev 值）
5docker compose up
6# postgres on 127.0.0.1:$POSTGRES_HOST_PORT
7# Go backend on 127.0.0.1:$API_HOST_PORT (default 8080)
8# Vite frontend on 127.0.0.1:$WEB_HOST_PORT (default 5173)


flowchart TD
    A[安裝方式] -->|一般使用者| B[curl install.sh]
    A -->|想看原始碼 / contributor| C[git clone + docker compose]
    B --> D[dari-docs binary 在 PATH]
    C --> E[完整 stack on Docker]
    D --> F{執行模式}
    F -->|Managed| G[hosted dari.dev agents]
    F -->|Self-managed| H[自家 dari.dev org agents]
    F -->|Live-verify| I[+ Stripe / API test keys]
    E --> J[本地測試 backend / frontend]

3. 核心架構解析

3.1 三層架構


graph TB
    subgraph "Client Side (你的機器)"
        CLI[dari-docs CLI
Go + cobra]
        DOCS[你的 docs repo]
        BUNDLE[.dari-docs/input-docs-bundle.tar.gz]
        UPDATED[.dari-docs/updated/]
    end
    subgraph "Managed Service (mupt-ai 託管)"
        SUPA[Supabase Auth]
        BACKEND[Go backend
cmd/dari-docs-service]
        DB[(Postgres)]
        STRIPE[Stripe billing]
        WEB[Vite + React
optimize.dari.dev]
    end
    subgraph "Agent Runtime (dari.dev)"
        AT[Tester Agent]
        AE[Editor Agent]
        E2B[E2B sandbox
Python 3.13 / Node 22]
        LLM[Claude / GPT-5]
    end
    CLI -->|bundle| BUNDLE
    BUNDLE -->|upload| BACKEND
    CLI <-->|auth| SUPA
    BACKEND --> DB
    BACKEND --> AT
    AT --> E2B
    E2B --> LLM
    AT -.transcript / failures.-> BACKEND
    BACKEND --> AE
    AE --> LLM
    AE -.docs edits.-> BACKEND
    BACKEND -->|download| UPDATED
    WEB -->|view runs| BACKEND
    BACKEND --> STRIPE

3.2 一次 dari-docs check 的生命週期


sequenceDiagram
    participant U as 使用者
    participant CLI as dari-docs CLI
    participant API as Managed Service
    participant T as Tester Agent (e2b)
    participant L as Claude/GPT-5

    U->>CLI: dari-docs check . --managed --task "..."
    CLI->>CLI: bundle .dari-docs/input-docs-bundle.tar.gz
    CLI->>API: POST /runs (bundle + task)
    API-->>CLI: run_id
    CLI-->>U: 印 run_id
    API->>T: spawn e2b sandbox
    T->>L: 多輪 prompt（試著按 docs 做事）
    L-->>T: 答覆 / 工具呼叫
    T->>T: 卡住時記錄 ambiguity
    T-->>API: 完成 transcript + failure list
    U->>CLI: dari-docs runs wait  / --wait
    CLI->>API: poll status
    API-->>CLI: completed
    CLI->>API: GET /runs/{id}/artifacts
    CLI->>U: 印 failure report

3.3 Agent template（內建 docs-user-tester-agent）

 1# agents/docs-user-tester-agent/dari.yml
 2name: docs-user-tester-agent
 3harness: pi
 4
 5instructions:
 6  system: prompts/system.md
 7
 8sandbox:
 9  provider: e2b                          # 跑在 e2b cloud sandbox
10  internet_access: true
11  secrets: [DARI_DOCS_RUNTIME_SECRETS_JSON]
12  runtimes:
13    python: "3.13"
14    node: "22"
15  packages:
16    apt: [build-essential, ca-certificates, curl, git, jq, ripgrep, ...]
17
18llm:
19  default: claude-sonnet-4-6             # 預設模型
20  options:
21    claude-haiku-4-5: { provider: anthropic, model: claude-haiku-4-5 }
22    claude-sonnet-4-6: { provider: anthropic, model: claude-sonnet-4-6 }
23    claude-opus-4-7: { provider: anthropic, model: claude-opus-4-7 }
24    gpt-5-mini: { provider: openai, model: gpt-5-mini }
25    gpt-5.1: { provider: openai, model: gpt-5.1 }
26    gpt-5.5: { provider: openai, model: gpt-5.5 }
27
28built_in_tools: [read, bash, write, edit]
29
30skills:
31  - name: docs-user-test
32    path: skills/docs-user-test

設計意義：把「測試 agent」具體化為「一個 dari.dev agent project 資料夾」（prompts + skills + sandbox spec）。任何想自訂 testing 行為的人，只要改這個資料夾。

3.4 Backend service 結構

cmd/dari-docs-service/main.go 跑的 backend：

  • Cobra-less，直接 HTTP server on :8080
  • 用 Supabase publishable key 接收 session
  • 用 DARI_API_KEY 呼叫 dari.dev API（hosted agents）
  • 用 DARI_DOCS_SECRET_ENCRYPTION_KEY 加密 use case secrets
  • Stripe webhook 處理 billing

3.5 Bundle 選擇邏輯

internal/bundle/ 做的事：

  1. 從 --include / --exclude glob 過濾
  2. 預設 include：likely docs（README、docs/、*.md）
  3. 預設 exclude：node_modules、.git、build artifact、.dari-docs/output
  4. 印 bundle summary（檔案數 + 大小）給使用者
  5. tar+gz 成單檔上傳

flowchart LR
    A[--include globs] --> B[walk repo]
    C[預設 likely-docs
README, docs/, *.md] --> B
    B --> D{每個檔}
    D -->|match include| E[加入]
    D -->|match exclude| F[跳過]
    D -->|default skip
node_modules, .git, build| F
    E --> G[.dari-docs/input-docs-bundle.tar.gz]
    G --> H[upload to managed service]

4. Helper Scripts 詳細用法

4.1 install.sh（一鍵安裝）

 1# 直接安裝最新 release
 2curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-docs/main/install.sh | bash
 3
 4# 安裝特定版本
 5DARI_DOCS_VERSION=v0.1.4 \
 6  curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-docs/main/install.sh | bash
 7
 8# 安裝到自訂目錄
 9DARI_DOCS_INSTALL_DIR=$HOME/bin \
10  curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-docs/main/install.sh | bash

關鍵驗證：

  • 走 https://github.com/mupt-ai/dari-docs/releases/latest 解析最新 tag（GitHub 302 redirect）
  • 版本格式校驗：^v[0-9]+\.[0-9]+\.[0-9]+(...)?$
  • 一律用 install 命令而非 cp — 確保 +x 權限

4.2 compose.yaml（contributor 完整 stack）

1# 起整個服務（postgres + backend + frontend）
2docker compose up
3
4# 只起 postgres（其他自己 go run / npm run dev）
5docker compose up postgres
6
7# 重置 DB
8docker compose down -v
9docker compose up postgres

4.3 .goreleaser.yaml（release 自動化）

每個 tag push 觸發：

  1. cross-compile macOS (Intel/ARM) + Linux (x86_64/arm64) binaries
  2. tarball 每個 OS/arch
  3. 上傳到 GitHub Releases

是「Go CLI 的標配發行流程」最簡實作。

4.4 CLI 命令一覽（從 source 提取）

命令用途範例
dari-docs init [repo]寫出 .dari-docs/agents/dari-docs init .
`dari-docs check [repoURL]`跑 docs 檢查
`dari-docs optimize [repoURL]`跑檢查 + 產 docs edits
dari-docs auth loginSupabase 瀏覽器登入
dari-docs auth status看登入狀態
dari-docs auth api-key create為 CI 建 named API key
dari-docs auth api-key list列 API key
dari-docs auth api-key revoke <id>撤銷
dari-docs runs status <run-id>看 run 狀態
dari-docs runs wait <run-id>阻塞等待
dari-docs runs download <run-id> [repo]下載 artifacts
dari-docs runs apply <run-id> [repo]套用 docs edits
dari-docs billing balance看 credit 餘額
dari-docs billing checkout加 credit
dari-docs agents deploy [repo]self-managed: 部署 agents 到自家 dari.dev org
dari-docs version版本

5. 應用場景

場景怎麼用
SDK 第一次 quickstart 是否好用dari-docs check . --managed --task "Install the SDK and make a first API call"
多 task 一次跑repeat --task 或用 task file（看 docs/tasks.md）
在 GitHub Actions 把它當必過 gate走 docs/github-actions.md，CI 用 named API key + --wait
要測「使用者帶 API key 真實跑」加 --live-verify --secret-env STRIPE_TEST_SECRET_KEY
企業內部自家 agent infraself-managed 模式 + dari-docs agents deploy
public docs URL 測試（沒有 repo 只有網站）dari-docs check https://your-docs-site.com --task "..."
在 web UI 看 transcripthttps://optimize.dari.dev → 看 run history + transcript viewer

6. 資安掃描報告

掃描範圍：cmd/、internal/、install.sh、compose.yaml、.env.example、docs/、agent dari.yml。

風險面燈號說明
Shell injection（CLI）🟢 低cmd/dari-docs/init.go:138 用 exec.Command("dari", "credentials", "add", name, value) 列表形式（無 shell expansion）
Shell injection（install.sh）🟢 低set -euo pipefail，所有變數有引號；版本字串有 regex 校驗
Token 處理🟢 低Supabase publishable key 是設計上公開的（非 secret，是 SDK 用 key）；DARI_API_KEY 透過 env 注入
Secret encryption🟡 中DARI_DOCS_SECRET_ENCRYPTION_KEY 在 compose.yaml 有 base64 預設值「placeholder」字串 — production 必須換，不能用 .env.example 的 dev 值
Stripe webhook🟢 低webhook secret 走 env，無 hardcoded
網路出口🟡 中CLI 會上傳 docs bundle 到 https://api.dari.dev（或 dev-api）— 使用者要確認 docs 內沒有機密內容
Sandbox 安全🟢 低agent 跑在 e2b cloud sandbox（隔離環境），不是使用者本機
--live-verify 模式🟡 中會把 --secret-env NAME 對應 env var 值送到 hosted agent；只用 test-mode key（如 sk_test_）— docs 明確警告
dari.dev API 信任🟡 中整個 managed 模式信任 mupt-ai 的後端 — 對 mission-critical / confidential docs 應用 self-managed 模式
README 缺 LICENSE🟡 中該 repo 沒有 LICENSE file；雖然 open source，但實際授權不明 — fork / 商用前最好開 issue 詢問
Postgres compose🟢 低預設密碼是 dari_docs，但 bind 只在 127.0.0.1，本機開發無風險
.env.example 內含真實 key🟢 低是 Supabase publishable key（設計上可公開）；非密金鑰
第三方依賴鏈🟡 中包含大量 Go modules（go.sum 6.6KB）+ Node modules（web/package-lock）— 跟一般大型 fullstack 專案同等審查

綜合燈號：🟢 / 🟡（無紅燈；主要風險來自「使用者要把 docs 上傳到 mupt-ai 後端」這個信任邊界）

重點建議：

  • 機密 docs 不要走 managed mode；用 self-managed
  • DARI_DOCS_SECRET_ENCRYPTION_KEY 在 production deploy 一定要換成隨機 32-byte base64
  • --live-verify 只配 test-mode 金鑰
  • 在自家用之前可以開 PR / issue 問作者加 LICENSE（目前 repo 無）

7. FAQ

Q1：跟 ConardLi/garden-skills 是什麼關係？ A：完全不同。garden-skills 是「Agent skill 集合」（SKILL.md 範本）；dari-docs 是「測你的 docs 能不能讓 agent 跑通」的服務（CLI + backend + agent infra）。但兩者都可以搭配使用：用 garden-skills 寫好 skill 後，用 dari-docs 測 skill 文件是否清楚。

Q2：dari-docs 跟 dari.dev 有什麼關係？ A：dari.dev 是 mupt-ai 公司的旗艦產品 — agent runtime 服務。dari-docs 是 dari.dev 的 docs-specific 子產品。managed mode 直接用 dari.dev hosted agents；self-managed mode 把自家 agents 部署到自家 dari.dev org。

Q3：免費的嗎？ A：新帳戶送 $5 free credits；之後按 token 計費（在 https://optimize.dari.dev 看 billing）。Self-managed 模式不付 dari-docs 費，但要付 dari.dev account 與 agent infra 費。

Q4：為什麼新版 PR 那麼多？ A：repo 2026-05-08 才建，目前最快狀態（小公司 fast iteration）；2 週內已 v0.1.5、59+ PR。

Q5：能在 Windows 跑嗎？ A：CLI 目前不支援 Windows（install.sh 只判 darwin / linux）；可走 WSL2 或 Docker compose（含全 stack）。

Q6：機密文件可以用嗎？ A：建議用 self-managed mode（執行在自家 dari.dev org 環境）。managed mode 會把 docs 上傳到 mupt-ai backend。

Q7：agent 用哪些 LLM？ A：預設 claude-sonnet-4-6；可選 claude-haiku-4-5 / claude-opus-4-7 / gpt-5-mini / gpt-5.1 / gpt-5.5（在 dari.yml 切）。

Q8：CI 整合會卡多久？ A：用 --wait 後，由 task 複雜度決定 — quickstart task 通常 1–5 分鐘；deep tutorial 可能 10–20 分鐘。設定 GitHub Actions timeout-minutes: 30 較安全。

8. 進階技巧

8.1 自訂 tester agent

 1dari-docs init .
 2ls .dari-docs/agents/docs-user-tester-agent/
 3# dari.yml  prompts/system.md  README.md  skills/
 4
 5# 改 prompts/system.md（讓 agent 用你的口吻 / 領域語言）
 6vim .dari-docs/agents/docs-user-tester-agent/prompts/system.md
 7
 8# 改 skills/docs-user-test/SKILL.md（讓 agent 用你的測試流程）
 9vim .dari-docs/agents/docs-user-tester-agent/skills/docs-user-test/SKILL.md
10
11# self-managed 模式部署到自家 dari.dev
12dari-docs agents deploy .

8.2 跑「public docs URL」測試

1# 不需要 repo，直接給 docs URL
2dari-docs check https://docs.your-product.com \
3    --managed \
4    --task "Find the authentication section and make a first request"

agent 會用瀏覽器（agent 內建 internet access）逐頁讀。

8.3 task file（重複 / 多 task）

1# 寫 tasks.yml（從 docs/tasks.md）
2cat > tasks.yml <<EOF
3- "Install the SDK and make a first API call"
4- "Authenticate with API key, retrieve user profile"
5- "Subscribe to webhook events"
6EOF
7
8dari-docs check . --managed --task-file tasks.yml --wait

8.4 把 dari-docs 接到 GitHub Actions

看 docs/github-actions.md，最簡 workflow：

1- run: curl -fsSL https://.../install.sh | bash
2- run: dari-docs check . --managed \
3        --task "Quickstart works" \
4        --wait \
5        --api-key ${{ secrets.DARI_DOCS_API_KEY }}

8.5 把 dari-docs 反過來用：測自己 repo 的 docs

本知識庫 inbox/2026-05-21-tutorial-claude-plugins-official.md 可以餵給 dari-docs 跑：

1dari-docs check \
2    "/config/workspace/1. 25-26 Finished Project/260414 Cli tools/260416 AI-knowledge_template v1/inbox/" \
3    --managed \
4    --task "Install a Claude Code plugin from claude-plugins-official"
5# → 看 agent 能否照本知識庫的 tutorial 完成「安裝 plugin」

這是「用 dari-docs 自評我們生產的 tutorial md」的元用法。

9. 整合進其他工作流

既有 skill整合方式
ai-gh-save已存 standard gh-save md 在 inbox/2026-05-21-github-mupt-ai-dari-docs.md
gh-tutorial-qd本檔產出
ai-autofetch可加為「監控源」，每天看 mupt-ai/dari-docs 有沒有新版（v0.1.x 迭代極快）
dari-docs 元用法把本知識庫的所有 tutorial md 都餵給 dari-docs 跑，看哪些 tutorial 不夠清楚
paper-qa-lite對 docs/ 跑 RAG 問答
meeting-intel若團隊評估「是否引進 dari-docs 進內部 docs 工作流」可走 meeting-intel 做 thematic 拆解
patent-creator不適用（dari-docs 為 docs quality 工具）

10. 重點摘要 Checklist

  • 2 週生命週期（2026-05-08 創建）/ 34 stars / v0.1.5
  • Go CLI + Vite/React frontend + Postgres backend + dari.dev agents + e2b sandbox
  • 3 種模式：Managed / Self-managed / Live-verify
  • CLI 命令樹：auth、init、check、optimize、runs、billing、agents、version
  • 支援 claude-sonnet-4-6（預設）/ opus-4-7 / haiku-4-5 / gpt-5-mini / gpt-5.1 / gpt-5.5
  • 自動 release（goreleaser） + 一鍵 install.sh（macOS / Linux only）
  • 內建 docs-user-tester-agent / docs-editor-agent 兩個 agent template
  • GitHub Actions 整合範本
  • Self-managed 模式可部署到自家 dari.dev org
  • 資安綜合燈號：🟢 / 🟡（無紅燈；信任邊界 = mupt-ai backend / dari.dev）
  • 🟡 注意：無 LICENSE file；商用前最好詢問作者

11. 進一步閱讀

  • 託管服務：https://optimize.dari.dev
  • dari.dev 母產品：https://dari.dev
  • GitHub Actions 設定：docs/github-actions.md
  • Bundle 選擇：docs/bundle-selection.md
  • Live verification：docs/live-verification.md
  • 對應姊妹專案 ConardLi/garden-skills：inbox/2026-05-21-github-ConardLi-garden-skills.md
  • 本知識庫先前 gh-save：inbox/2026-05-21-github-anthropics-claude-plugins-official.md