dash-devtools 2.0.1

大許開發工具集 DashAI DevTools - 驗證、遷移、文件產生工具

DashAI DevTools v2.1

English | 日本語 | 正體中文

大許開發工具集 - 統一的開發、驗證、測試、AI 分析工具

特色

• E2E 測試: 使用 agent-browser (by Vercel Labs) 進行網頁自動化測試
• AI 視覺分析: 截圖 + Gemini AI 進行 UI/UX、無障礙、效能分析
• 程式碼品質: 自動檢查安全性、規範、技術債務
• 四大測試套件: UIT/Smoke/E2E/UAT 完整測試 + Word/Markdown 報告

安裝

cd dash-devtools
pip install -e .

工具總覽

分類	指令	用途
驗證	dash validate	驗證專案符合開發規範
健康	dash health	專案健康評分 (類似 Lighthouse)
規格	dash spec	OpenSpec 規格驅動開發 (SDD)
統計	dash stats	程式碼統計儀表板
測試	dash test	執行測試 (vitest/jest/pytest)
測試套件	dash test-suite	四大類測試 (UIT/Smoke/E2E/UAT) + 報告
E2E	dash e2e	E2E 煙霧測試 (agent-browser)
報告	dash report	產生完整 HTML 報告
監控	dash watch	即時監控模式
掃描	dash scan	掃描機敏資料
AI	dash ai	AI 程式碼助手 (Gemini)
資料庫	dash db	資料庫遷移管理 (Alembic)
圖表	dash dbdiagram	產生資料庫 ERD 連結
文件	dash docs	產生文件、CLAUDE.md
視覺	dash vision	AI 視覺分析工具
診斷	dash doctor	診斷開發環境

快速使用

驗證專案

# 智慧驗證 (自動偵測專案類型)
dash validate /path/to/project

# 驗證並自動修復
dash validate /path/to/project --fix

# 驗證所有專案
dash validate --all

# 只檢查特定項目
dash validate --check security /path/to/project
dash validate --check smart /path/to/project

自動修復功能

使用 --fix 參數可自動修復以下問題：

問題類型	自動修復
表格內下拉選單	轉換為圖示按鈕
圖示按鈕缺少 title	自動加入 title 屬性
白底卡片缺邊框	加入 CSS 邊框樣式
Emoji 圖示	建議改用 sl-icon

遷移 UI 框架（已暫停）

注意：自動遷移功能已暫停使用。 UI 框架遷移需要完整理解設計邏輯後手動進行，避免破壞現有 UI/UX。

# 此指令目前會返回錯誤訊息
dash migrate /path/to/project

產生文件

# 產生 CLAUDE.md
dash docs claude /path/to/project

# 產生所有專案的 CLAUDE.md
dash docs claude --all

版本發布

# 檢視版本狀態
dash release status

# 發布新版本
dash release publish --version 1.2.0 /path/to/project

驗證項目

智慧驗證 (smart)

自動偵測專案類型並執行對應檢查：

專案類型	偵測方式	檢查項目
Angular	angular.json	PrimeNG、TypeScript、Bundle
Vite	vite	Shoelace 使用、Emoji 圖示、UX 模式
React	react	JSX、Hooks、Bundle
Node.js	Express/Fastify	API、Vercel、安全性
Python	requirements.txt	AI/ML、模型檔案

UI/UX 檢查

檢查項目	說明	嚴重度
表格內下拉選單	建議改用圖示按鈕	[UX]
圖示按鈕缺 title	影響無障礙性	[A11Y]
巢狀選單過深	超過 2 層影響體驗	[UX]
白底卡片無邊框	難以辨識區域	[UI]

安全性檢查 (security)

• API Key / Token 外洩
• 密碼硬編碼
• .env 檔案提交
• 敏感資料暴露

GitGuardian 整合

支援 GitGuardian 掃描引擎，與 GitHub 偵測一致：

# 安裝 ggshield
pip install ggshield

# 設定 API Key
export GITGUARDIAN_API_KEY="your-api-key"

# 掃描會自動使用 GitGuardian（如果有設定）
dash scan /path/to/project

掃描優先順序：

1. GitGuardian - 如果有 API Key 且安裝了 ggshield
2. 本地規則 - 備援，使用內建正則表達式

資料庫圖表

從 Prisma schema 自動產生 dbdiagram.io 可分享連結：

# 產生連結
dash dbdiagram /path/to/project

# 開啟瀏覽器
dash dbdiagram . --open

# 複製到剪貼簿
dash dbdiagram . --copy

# 儲存到檔案
dash dbdiagram . --save

Prisma 設定

在 schema.prisma 加入：

generator dbml {
  provider   = "prisma-dbml-generator"
  output     = "../docs"
  outputName = "schema.dbml"
}

安裝套件：

npm install -D prisma-dbml-generator

執行 npx prisma generate 後會產生 DBML 檔案，dash dbdiagram 會自動編碼為可分享連結。

注意：dbdiagram.io 的 DBML-in-Link 功能完全免費，不需要帳號也不需要 API Key

程式碼品質 (code_quality)

• 檔案行數限制 (500 行)
• 命名規範 (kebab-case)
• 禁止 Emoji (程式碼和 commit message)
• 禁止簡體字
• 禁止中國用語 (56 組詞彙，如「視頻→影片」「內存→記憶體」)
• AI 寫作痕跡偵測 (「值得注意的是」「至關重要」等)

v2.0 新功能

OpenSpec 規格驅動開發

使用 Spec-Driven Development (SDD) 工作流程管理功能規格：

# 初始化 OpenSpec
dash spec init .

# 列出活動變更
dash spec list .

# 互動式儀表板
dash spec view .

# 顯示變更詳情
dash spec show . my-feature

# 驗證規格格式
dash spec validate . my-feature

# 歸檔完成的變更
dash spec archive . my-feature

# 快速狀態總覽
dash spec status .

需要先安裝 OpenSpec CLI：

npm install -g @fission-ai/openspec@latest

目錄結構：

project/
└── openspec/
    ├── specs/      # 功能規格
    ├── changes/    # 活動變更提案
    └── archive/    # 已歸檔的變更

整合功能：

• dash validate . 自動偵測 openspec/ 並驗證規格格式
• dash health . 顯示規格健康度評分

專案健康評分

類似 Lighthouse 的評分機制：

# 單一專案
dash health .

# 所有專案
dash health --all

# JSON 輸出
dash health . --json

評分項目：

• 安全性：機敏資料、依賴漏洞
• 品質：程式碼規範、檔案結構
• 維護性：技術債務、文件完整度
• 效能：Bundle 大小、依賴數量

程式碼統計

# 單一專案
dash stats .

# 比較所有專案
dash stats --all

顯示：語言分佈、檔案數量與行數、最大檔案排行、複雜度警告

測試執行

# 執行測試
dash test .

# 含覆蓋率報告
dash test . --coverage

# 測試所有專案
dash test --all

自動偵測：vitest、jest、karma、pytest

四大類測試套件

執行完整測試套件並產生報告：

# 執行四大類測試
dash test-suite .

# 產生 Word 報告
dash test-suite . --word test-report.docx

# 產生 Markdown 報告
dash test-suite . --md test-report.md

# 只執行特定類型
dash test-suite . --types UIT,Smoke

測試類型	說明	測試檔案
UIT	單元測試	*.spec.ts
Smoke	煙霧測試	e2e/smoke.spec.ts
E2E	端對端測試	e2e/mes-system.spec.ts
UAT	驗收測試	e2e/uat.spec.ts

報告包含：

• 測試摘要與統計圖表
• 各測試類型明細
• API 測試回應內容
• 系統截圖

E2E 煙霧測試

使用 agent-browser 檢查頁面 JS 錯誤：

# 基本測試
dash e2e https://your-app.vercel.app

# 只檢查頁面載入
dash e2e https://example.com --check load

# 延長超時
dash e2e https://example.com --timeout 60000

# 失敗時截圖
dash e2e https://example.com --screenshot

# 手機版測試
dash e2e https://example.com --mobile

# JSON 輸出
dash e2e https://example.com --json

需要先安裝 agent-browser：

npm install -g agent-browser
agent-browser install

專案報告

產生完整 HTML 報告：

# 基本報告
dash report .

# 含 UI 截圖
dash report . --screenshot -u http://localhost:3000

# 不執行測試
dash report . --no-test

即時監控

# 監控檔案變更
dash watch .

# 發現問題自動修復
dash watch . --fix

AI 程式碼助手

使用 Gemini 2.5 分析程式碼：

# 分析程式碼
dash ai analyze src/main.py

# 安全分析
dash ai analyze src/api.ts --focus security

# 建議修復
dash ai fix src/main.py -e "TypeError: Cannot read property"

# 生成測試
dash ai test src/utils.py

# 解釋程式碼
dash ai explain src/complex-algo.py

# 審查 commit
dash ai review .

需設定環境變數：export GEMINI_API_KEY="your-api-key"

視覺 AI 分析

使用 agent-browser 截圖 + Gemini AI 進行 UI/UX 分析：

# 基本視覺分析
dash vision https://example.com

# UI/UX 專家分析
dash vision https://example.com --type ui_ux

# 無障礙 (WCAG 2.1) 檢查
dash vision https://example.com --type accessibility

# 效能視覺指標
dash vision https://example.com --type performance

# 分析本地截圖
dash vision /path/to/screenshot.png

分析類型：

類型	說明
general	整體 UI/UX 評估
ui_ux	專業 UI/UX 分析
accessibility	WCAG 2.1 無障礙檢查
performance	視覺效能指標

需要安裝 agent-browser 和設定 Gemini API Key。

瀏覽器自動化 API

Python API 提供完整的瀏覽器控制：

from dash_devtools.browser import AgentBrowser, quick_screenshot

# 快速截圖
quick_screenshot("https://example.com", "/tmp/screenshot.png")

# 完整控制
browser = AgentBrowser()
browser.open("https://example.com")
browser.snapshot(interactive_only=True)  # 取得可互動元素
browser.fill("@e1", "[e-mail]")  # 填寫表單
browser.click("@e2")                      # 點擊按鈕
browser.screenshot("/tmp/result.png")
browser.close()

視覺分析 API：

from dash_devtools.vision import analyze_url, compare_screenshots

# 截圖並分析
result = analyze_url("https://example.com", analysis_type="ui_ux")
print(result.issues)
print(result.recommendations)

# 比較兩張截圖 (視覺回歸)
result = compare_screenshots("before.png", "after.png")
print(result.analysis)

資料庫遷移

Alembic 整合：

# 初始化
dash db init .

# 檢視狀態
dash db status .

# 產生遷移
dash db generate . -m "add user table"

# 升級
dash db upgrade .

# 降級（需確認）
dash db downgrade . -r -1 --confirm

診斷工具

dash doctor

顯示：系統資訊、Python 路徑、套件版本、環境變數

Git Hooks (Pre-push v3)

全域 pre-push hook，所有專案推送前自動檢查：

# 安裝全域 hook
git config --global core.hooksPath ~/.config/git/hooks
cp scripts/pre-push ~/.config/git/hooks/pre-push
chmod +x ~/.config/git/hooks/pre-push

Push 前自動執行（依專案類型動態調整步驟數）：

步驟	前端	後端	說明
Emoji 掃描	v	v	只掃 git diff 變更檔 + commit message
commit message 格式	v	v	禁止 Emoji，建議 類型: 描述 格式
機敏資料掃描	v	v	GitGuardian 或本地規則
TypeScript 建構	v	-	vue-tsc / ng build / tsc（自動偵測）
Python Ruff lint	-	v	check + format 檢查
專案驗證	v	v	dash validate（簡體字、AI 痕跡、品質）

錯誤阻擋推送，警告放行但顯示提示。每步驟附計時。

模板

位於 templates/ 目錄：

模板	說明
deploy-netlify.yml	GitHub Actions Netlify 備援部署

---

Claude Code 指令集指南

內建指令總覽

會話管理

指令	功能	說明
/clear	清空對話	重新開始對話
/resume [session]	恢復對話	按 ID 或名稱恢復
/compact [指令]	壓縮對話	節省 token，可指定焦點
/rewind	回退	回退對話和程式碼變更
/rename <name>	重新命名	為當前會話命名
/exit	退出	結束 CLI

設定與配置

指令	功能	說明
/config	設定介面	開啟設定頁面
/model	切換模型	選擇 AI 模型
/permissions	權限管理	查看/更新工具權限
/settings	設定管理	管理所有設定
/sandbox	沙箱模式	啟用安全沙箱
/status	狀態資訊	版本、模型、帳號狀態

工具與整合

指令	功能	說明
/mcp	MCP 伺服器	管理 MCP 連接
/hooks	Hooks 設定	管理工具事件鉤子
/ide	IDE 整合	管理編輯器整合
/plugin	插件管理	管理 Claude Code 插件
/agents	代理管理	管理自定義子代理

開發與專案

指令	功能	說明
/init	初始化	建立 CLAUDE.md
/memory	編輯記憶	編輯 CLAUDE.md
/review	程式碼審查	請求審查
/add-dir	新增目錄	添加工作目錄

資訊與統計

指令	功能	說明
/cost	Token 用量	顯示使用統計
/context	上下文視覺化	彩色網格顯示
/todos	待辦事項	列出當前 TODO
/stats	使用統計	日常用法、連勝記錄
/usage	用量限制	訂閱計劃使用量

系統與診斷

指令	功能	說明
/doctor	健康檢查	檢查安裝狀態
/bug	回報 Bug	發送至 Anthropic
/release-notes	發行說明	查看更新內容
/login / /logout	帳號管理	登入/登出

輸出與匯出

指令	功能	說明
/vim	Vim 模式	進入 Vim 編輯模式
/export [file]	匯出對話	匯出到檔案或剪貼簿
/output-style	輸出樣式	設定回應格式

---

自定義指令 (Slash Commands)

建立位置

範圍	路徑	說明
專案級	.claude/commands/xxx.md	與團隊共享
個人級	~/.claude/commands/xxx.md	跨專案可用

基本格式

---
description: 指令說明（必填）
argument-hint: [參數提示]
allowed-tools: Bash(npm:*), Read, Edit
---

# 指令內容

你的提示詞內容...

Frontmatter 選項

選項	必填	說明
description	是	指令說明
argument-hint	否	參數提示
allowed-tools	否	允許的工具
model	否	指定模型

範例：Chrome 截圖指令

---
description: Chrome 截圖或輸出 PDF
argument-hint: <url> [--pdf]
allowed-tools: Bash(*/Google Chrome*:*), Read
---

截圖網頁並進行 UI/UX 分析。

使用方式：
- `/chrome https://example.com` - 截圖
- `/chrome https://example.com --pdf` - 輸出 PDF

動態內容

使用 ! 前綴執行 Bash 指令：

當前狀態：!`git status`
最近提交：!`git log -3 --oneline`

使用 @ 前綴引用檔案：

請參考 @src/utils/helpers.js 的實作

---

Skills（複雜工作流）

與 Slash Commands 差異

項目	Slash Commands	Skills
複雜度	簡單提示	複雜工作流
結構	單一 .md 檔	目錄 + 多檔案
觸發	手動 /command	自動偵測上下文
適用	常用指令	團隊標準流程

目錄結構

.claude/skills/my-skill/
├── SKILL.md          # 必須 - 主要說明
├── REFERENCE.md      # 選用 - API 參考
├── EXAMPLES.md       # 選用 - 使用範例
└── scripts/          # 選用 - 輔助腳本
    └── helper.py

SKILL.md 格式

---
name: skill-name
description: 簡短說明（何時使用）
allowed-tools: Read, Bash(npm:*)
---

# Skill 名稱

## 何時使用
描述觸發條件...

## 步驟
1. 步驟一
2. 步驟二

## 範例
具體使用範例...

---

CLI 參數

啟動方式

claude                         # 交互模式
claude "問題"                  # 帶初始提示
claude -p "問題"               # 非交互模式
claude -c                      # 恢復最近對話
claude -r "session-name"       # 恢復特定會話
cat file | claude -p "問題"    # 管道輸入

常用參數

參數	說明
--model <model>	指定模型
--add-dir <path>	添加工作目錄
--permission-mode plan	Plan 模式
--tools "Bash,Edit,Read"	指定工具
--append-system-prompt	追加系統提示

---

開發

# 安裝開發依賴
pip install -e ".[dev]"

# 執行測試
pytest

# 格式化
black .

致謝

本專案使用以下開源工具：

• agent-browser - Vercel Labs 開發的瀏覽器自動化工具
• Playwright - Microsoft 的 E2E 測試框架
• Google Gemini - AI 視覺分析引擎
• Rich - 終端 UI 美化

更新歷程

v2.0.0 (2026-05-20)

發布至 PyPI，自此 README 歷程與套件版本號統一。彙整 v2.2 (2026-03-15) 之後至 2026-05-17 的改動。

• 語意層驗證器: 新增 4 個語意層驗證器 (Next.js SEO 與安全標頭、i18n key 一致性、a11y)，警告顯示細節
• Logto 認證 pattern 驗證: 認 Logto / Clerk 與通用共 6 種 pattern，public proxy 以 @public-proxy 註解標示
• Flat OpenSpec adapter: 扁平 OpenSpec 自動跳過 orphan check (specs 以 [[ref]] opt-in)
• 禁用概念掃描: 自動攔截已移除概念 (傍通曆、五行、暦注、六害宿等)
• 架構文件完整性: 新增 dash architecture check/diff 指令，pre-push 步驟 5 架構檢查
• 開源工具整合: 整合 9 個開源工具，health 評分精準化
• 品質與安全修復: a11y 精準度提升 (排除有文字或 sr-only 的按鈕)、regex 收斂並跳過 test 目錄降低假陽性、knowledge_ JSON 檔加入 allowlist、ggshield stdin pipe 修正、新增 verify 指令

v2.2 (2026-03-15)

• 大型檔案拆分: 消除所有超過 500 行的檔案警告
  • cli.py 1528 → 62 行，拆為 commands/ 目錄 (10 個模組)
  • test_suite.py 690 → 393 行，抽出 test_runners/ (4 個 runner)
  • word_report.py 689 → 485 行，抽出 reporters/templates + charts
  • report.py 667 → 453 行，抽出 reporters/report_data + screenshot
  • quality.py 510 → 429 行，詞庫常數抽為 constants.py
  • browser.py 541 → 354 行，便捷函數抽至 browser_helpers.py
• 品質修復: 中國用語修正、.gitignore 補齊 node_modules
• dash validate 達成 0 錯誤 0 警告

v2.1 (2026-03-14)

• Pre-push Hook v3: 合併全域版與專案版，動態步驟數
  • 新增 TypeScript 建構檢查 (vue-tsc / ng build / tsc)
  • 新增 commit message 格式檢查（禁止 Emoji）
  • Emoji 掃描改用 git diff（只查變更檔，速度提升）
  • 新增 Python Ruff lint (check + format)
  • 錯誤/警告分級，每步驟計時
• 品質檢查擴充
  • 新增中國用語禁用詞 (56 組，來源: pjchender/cn2tw4programmer)
  • 新增 AI 寫作痕跡偵測 (check_ai_slop)

v2.0 (2026-02)

• OpenSpec 規格驅動開發 (SDD)
• 專案健康評分
• 程式碼統計儀表板
• 四大測試套件 (UIT/Smoke/E2E/UAT)
• AI 視覺分析 (Gemini)
• UptimeRobot 監控管理

v1.0 (2026-01)

• 專案驗證 (dash validate)
• 機敏資料掃描 (dash scan)
• E2E 煙霧測試 (agent-browser)
• 資料庫遷移管理 (Alembic)
• dbdiagram.io 圖表產生

授權

MIT License - DashAI