dash-devtools 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. dash_devtools-1.0.0/PKG-INFO +834 -0
  2. dash_devtools-1.0.0/README.md +794 -0
  3. dash_devtools-1.0.0/dash_devtools/__init__.py +8 -0
  4. dash_devtools-1.0.0/dash_devtools/__main__.py +11 -0
  5. dash_devtools-1.0.0/dash_devtools/ai_engine.py +441 -0
  6. dash_devtools-1.0.0/dash_devtools/browser.py +541 -0
  7. dash_devtools-1.0.0/dash_devtools/cli.py +1452 -0
  8. dash_devtools-1.0.0/dash_devtools/database.py +338 -0
  9. dash_devtools-1.0.0/dash_devtools/dbdiagram.py +183 -0
  10. dash_devtools-1.0.0/dash_devtools/e2e.py +329 -0
  11. dash_devtools-1.0.0/dash_devtools/fixers/__init__.py +57 -0
  12. dash_devtools-1.0.0/dash_devtools/fixers/migration_fixer.py +115 -0
  13. dash_devtools-1.0.0/dash_devtools/fixers/ux_fixer.py +106 -0
  14. dash_devtools-1.0.0/dash_devtools/fixers/version_bumper.py +115 -0
  15. dash_devtools-1.0.0/dash_devtools/gas_mes_test.py +1241 -0
  16. dash_devtools-1.0.0/dash_devtools/generators/__init__.py +84 -0
  17. dash_devtools-1.0.0/dash_devtools/health.py +476 -0
  18. dash_devtools-1.0.0/dash_devtools/hooks/__init__.py +250 -0
  19. dash_devtools-1.0.0/dash_devtools/hooks/pre_commit.py +161 -0
  20. dash_devtools-1.0.0/dash_devtools/hooks/pre_push.py +275 -0
  21. dash_devtools-1.0.0/dash_devtools/init_test.py +352 -0
  22. dash_devtools-1.0.0/dash_devtools/markdown_report.py +309 -0
  23. dash_devtools-1.0.0/dash_devtools/migrators/__init__.py +21 -0
  24. dash_devtools-1.0.0/dash_devtools/perf.py +321 -0
  25. dash_devtools-1.0.0/dash_devtools/report.py +667 -0
  26. dash_devtools-1.0.0/dash_devtools/reporters/__init__.py +11 -0
  27. dash_devtools-1.0.0/dash_devtools/spec.py +230 -0
  28. dash_devtools-1.0.0/dash_devtools/stats.py +355 -0
  29. dash_devtools-1.0.0/dash_devtools/test_suite.py +690 -0
  30. dash_devtools-1.0.0/dash_devtools/testing.py +416 -0
  31. dash_devtools-1.0.0/dash_devtools/validators/__init__.py +157 -0
  32. dash_devtools-1.0.0/dash_devtools/validators/backend/__init__.py +12 -0
  33. dash_devtools-1.0.0/dash_devtools/validators/backend/nodejs.py +245 -0
  34. dash_devtools-1.0.0/dash_devtools/validators/backend/python.py +439 -0
  35. dash_devtools-1.0.0/dash_devtools/validators/code_quality.py +243 -0
  36. dash_devtools-1.0.0/dash_devtools/validators/common/__init__.py +11 -0
  37. dash_devtools-1.0.0/dash_devtools/validators/common/quality.py +319 -0
  38. dash_devtools-1.0.0/dash_devtools/validators/common/security.py +270 -0
  39. dash_devtools-1.0.0/dash_devtools/validators/common/spec.py +273 -0
  40. dash_devtools-1.0.0/dash_devtools/validators/detector.py +394 -0
  41. dash_devtools-1.0.0/dash_devtools/validators/frontend/__init__.py +14 -0
  42. dash_devtools-1.0.0/dash_devtools/validators/frontend/angular.py +245 -0
  43. dash_devtools-1.0.0/dash_devtools/validators/frontend/gas.py +310 -0
  44. dash_devtools-1.0.0/dash_devtools/validators/frontend/vite.py +539 -0
  45. dash_devtools-1.0.0/dash_devtools/validators/migration.py +292 -0
  46. dash_devtools-1.0.0/dash_devtools/validators/performance.py +167 -0
  47. dash_devtools-1.0.0/dash_devtools/validators/security.py +205 -0
  48. dash_devtools-1.0.0/dash_devtools/vision/__init__.py +368 -0
  49. dash_devtools-1.0.0/dash_devtools/watch.py +266 -0
  50. dash_devtools-1.0.0/dash_devtools/word_report.py +690 -0
  51. dash_devtools-1.0.0/dash_devtools.egg-info/PKG-INFO +834 -0
  52. dash_devtools-1.0.0/dash_devtools.egg-info/SOURCES.txt +56 -0
  53. dash_devtools-1.0.0/dash_devtools.egg-info/dependency_links.txt +1 -0
  54. dash_devtools-1.0.0/dash_devtools.egg-info/entry_points.txt +2 -0
  55. dash_devtools-1.0.0/dash_devtools.egg-info/requires.txt +26 -0
  56. dash_devtools-1.0.0/dash_devtools.egg-info/top_level.txt +1 -0
  57. dash_devtools-1.0.0/pyproject.toml +74 -0
  58. dash_devtools-1.0.0/setup.cfg +4 -0
@@ -0,0 +1,834 @@
1
+ Metadata-Version: 2.4
2
+ Name: dash-devtools
3
+ Version: 1.0.0
4
+ Summary: 大許開發工具集 DashAI DevTools - 驗證、遷移、文件產生工具
5
+ Author-email: DashAI <dev@dashai.dev>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/seikaikyo/dash-devtools
8
+ Project-URL: Repository, https://github.com/seikaikyo/dash-devtools
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ Requires-Dist: click>=8.0
20
+ Requires-Dist: rich>=13.0
21
+ Requires-Dist: pyyaml>=6.0
22
+ Requires-Dist: jinja2>=3.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=7.0; extra == "dev"
25
+ Requires-Dist: black>=23.0; extra == "dev"
26
+ Requires-Dist: ruff>=0.1; extra == "dev"
27
+ Provides-Extra: vision
28
+ Requires-Dist: opencv-python>=4.8; extra == "vision"
29
+ Requires-Dist: pillow>=10.0; extra == "vision"
30
+ Requires-Dist: numpy>=1.24; extra == "vision"
31
+ Provides-Extra: ai
32
+ Requires-Dist: google-genai>=1.0.0; extra == "ai"
33
+ Requires-Dist: python-dotenv>=1.0.0; extra == "ai"
34
+ Provides-Extra: report
35
+ Requires-Dist: python-docx>=1.1.0; extra == "report"
36
+ Requires-Dist: matplotlib>=3.8.0; extra == "report"
37
+ Requires-Dist: pillow>=10.0; extra == "report"
38
+ Provides-Extra: all
39
+ Requires-Dist: dash-devtools[ai,dev,report,vision]; extra == "all"
40
+
41
+ # DashAI DevTools v2.0
42
+
43
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
44
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
45
+
46
+ **[English](README.en.md)** | **[日本語](README.ja.md)** | **正體中文**
47
+
48
+ 大許開發工具集 - 統一的開發、驗證、測試、AI 分析工具
49
+
50
+ ## 特色
51
+
52
+ - **E2E 測試**: 使用 [agent-browser](https://github.com/vercel-labs/agent-browser) (by Vercel Labs) 進行網頁自動化測試
53
+ - **AI 視覺分析**: 截圖 + Gemini AI 進行 UI/UX、無障礙、效能分析
54
+ - **程式碼品質**: 自動檢查安全性、規範、技術債務
55
+ - **四大測試套件**: UIT/Smoke/E2E/UAT 完整測試 + Word/Markdown 報告
56
+
57
+ ## 安裝
58
+
59
+ ```bash
60
+ cd dash-devtools
61
+ pip install -e .
62
+ ```
63
+
64
+ ## 工具總覽
65
+
66
+ | 分類 | 指令 | 用途 |
67
+ |------|------|------|
68
+ | **驗證** | `dash validate` | 驗證專案符合開發規範 |
69
+ | **健康** | `dash health` | 專案健康評分 (類似 Lighthouse) |
70
+ | **規格** | `dash spec` | OpenSpec 規格驅動開發 (SDD) |
71
+ | **統計** | `dash stats` | 程式碼統計儀表板 |
72
+ | **測試** | `dash test` | 執行測試 (vitest/jest/pytest) |
73
+ | **測試套件** | `dash test-suite` | 四大類測試 (UIT/Smoke/E2E/UAT) + 報告 |
74
+ | **E2E** | `dash e2e` | E2E 煙霧測試 (agent-browser) |
75
+ | **報告** | `dash report` | 產生完整 HTML 報告 |
76
+ | **監控** | `dash watch` | 即時監控模式 |
77
+ | **掃描** | `dash scan` | 掃描機敏資料 |
78
+ | **AI** | `dash ai` | AI 程式碼助手 (Gemini) |
79
+ | **資料庫** | `dash db` | 資料庫遷移管理 (Alembic) |
80
+ | **圖表** | `dash dbdiagram` | 產生資料庫 ERD 連結 |
81
+ | **文件** | `dash docs` | 產生文件、CLAUDE.md |
82
+ | **視覺** | `dash vision` | AI 視覺分析工具 |
83
+ | **診斷** | `dash doctor` | 診斷開發環境 |
84
+
85
+ ## 快速使用
86
+
87
+ ### 驗證專案
88
+
89
+ ```bash
90
+ # 智慧驗證 (自動偵測專案類型)
91
+ dash validate /path/to/project
92
+
93
+ # 驗證並自動修復
94
+ dash validate /path/to/project --fix
95
+
96
+ # 驗證所有專案
97
+ dash validate --all
98
+
99
+ # 只檢查特定項目
100
+ dash validate --check security /path/to/project
101
+ dash validate --check smart /path/to/project
102
+ ```
103
+
104
+ ### 自動修復功能
105
+
106
+ 使用 `--fix` 參數可自動修復以下問題:
107
+
108
+ | 問題類型 | 自動修復 |
109
+ |----------|----------|
110
+ | 表格內下拉選單 | 轉換為圖示按鈕 |
111
+ | 圖示按鈕缺少 title | 自動加入 title 屬性 |
112
+ | 白底卡片缺邊框 | 加入 CSS 邊框樣式 |
113
+ | Emoji 圖示 | 建議改用 sl-icon |
114
+
115
+ ### 遷移 UI 框架(已暫停)
116
+
117
+ > **注意**:自動遷移功能已暫停使用。
118
+ > UI 框架遷移需要完整理解設計邏輯後手動進行,避免破壞現有 UI/UX。
119
+
120
+ ```bash
121
+ # 此指令目前會返回錯誤訊息
122
+ dash migrate /path/to/project
123
+ ```
124
+
125
+ ### 產生文件
126
+
127
+ ```bash
128
+ # 產生 CLAUDE.md
129
+ dash docs claude /path/to/project
130
+
131
+ # 產生所有專案的 CLAUDE.md
132
+ dash docs claude --all
133
+ ```
134
+
135
+ ### 版本發布
136
+
137
+ ```bash
138
+ # 檢視版本狀態
139
+ dash release status
140
+
141
+ # 發布新版本
142
+ dash release publish --version 1.2.0 /path/to/project
143
+ ```
144
+
145
+ ## 驗證項目
146
+
147
+ ### 智慧驗證 (`smart`)
148
+
149
+ 自動偵測專案類型並執行對應檢查:
150
+
151
+ | 專案類型 | 偵測方式 | 檢查項目 |
152
+ |----------|----------|----------|
153
+ | Angular | `angular.json` | PrimeNG、TypeScript、Bundle |
154
+ | Vite | `vite` | Shoelace 使用、Emoji 圖示、UX 模式 |
155
+ | React | `react` | JSX、Hooks、Bundle |
156
+ | Node.js | Express/Fastify | API、Vercel、安全性 |
157
+ | Python | `requirements.txt` | AI/ML、模型檔案 |
158
+
159
+ ### UI/UX 檢查
160
+
161
+ | 檢查項目 | 說明 | 嚴重度 |
162
+ |----------|------|--------|
163
+ | 表格內下拉選單 | 建議改用圖示按鈕 | [UX] |
164
+ | 圖示按鈕缺 title | 影響無障礙性 | [A11Y] |
165
+ | 巢狀選單過深 | 超過 2 層影響體驗 | [UX] |
166
+ | 白底卡片無邊框 | 難以辨識區域 | [UI] |
167
+
168
+ ### 安全性檢查 (`security`)
169
+
170
+ - API Key / Token 外洩
171
+ - 密碼硬編碼
172
+ - .env 檔案提交
173
+ - 敏感資料暴露
174
+
175
+ #### GitGuardian 整合
176
+
177
+ 支援 [GitGuardian](https://www.gitguardian.com/) 掃描引擎,與 GitHub 偵測一致:
178
+
179
+ ```bash
180
+ # 安裝 ggshield
181
+ pip install ggshield
182
+
183
+ # 設定 API Key
184
+ export GITGUARDIAN_API_KEY="your-api-key"
185
+
186
+ # 掃描會自動使用 GitGuardian(如果有設定)
187
+ dash scan /path/to/project
188
+ ```
189
+
190
+ 掃描優先順序:
191
+ 1. **GitGuardian** - 如果有 API Key 且安裝了 ggshield
192
+ 2. **本地規則** - 備援,使用內建正則表達式
193
+
194
+ ### 資料庫圖表
195
+
196
+ 從 Prisma schema 自動產生 [dbdiagram.io](https://dbdiagram.io) 可分享連結:
197
+
198
+ ```bash
199
+ # 產生連結
200
+ dash dbdiagram /path/to/project
201
+
202
+ # 開啟瀏覽器
203
+ dash dbdiagram . --open
204
+
205
+ # 複製到剪貼簿
206
+ dash dbdiagram . --copy
207
+
208
+ # 儲存到檔案
209
+ dash dbdiagram . --save
210
+ ```
211
+
212
+ #### Prisma 設定
213
+
214
+ 在 `schema.prisma` 加入:
215
+
216
+ ```prisma
217
+ generator dbml {
218
+ provider = "prisma-dbml-generator"
219
+ output = "../docs"
220
+ outputName = "schema.dbml"
221
+ }
222
+ ```
223
+
224
+ 安裝套件:
225
+
226
+ ```bash
227
+ npm install -D prisma-dbml-generator
228
+ ```
229
+
230
+ 執行 `npx prisma generate` 後會產生 DBML 檔案,`dash dbdiagram` 會自動編碼為可分享連結。
231
+
232
+ **注意**:dbdiagram.io 的 DBML-in-Link 功能完全免費,不需要帳號也不需要 API Key
233
+
234
+ ### 程式碼品質 (`code_quality`)
235
+
236
+ - 檔案行數限制 (500 行)
237
+ - 命名規範 (kebab-case)
238
+ - 禁止 Emoji (程式碼中)
239
+ - 禁止簡體字
240
+
241
+ ## v2.0 新功能
242
+
243
+ ### OpenSpec 規格驅動開發
244
+
245
+ 使用 Spec-Driven Development (SDD) 工作流程管理功能規格:
246
+
247
+ ```bash
248
+ # 初始化 OpenSpec
249
+ dash spec init .
250
+
251
+ # 列出活動變更
252
+ dash spec list .
253
+
254
+ # 互動式儀表板
255
+ dash spec view .
256
+
257
+ # 顯示變更詳情
258
+ dash spec show . my-feature
259
+
260
+ # 驗證規格格式
261
+ dash spec validate . my-feature
262
+
263
+ # 歸檔完成的變更
264
+ dash spec archive . my-feature
265
+
266
+ # 快速狀態總覽
267
+ dash spec status .
268
+ ```
269
+
270
+ 需要先安裝 OpenSpec CLI:
271
+
272
+ ```bash
273
+ npm install -g @fission-ai/openspec@latest
274
+ ```
275
+
276
+ 目錄結構:
277
+
278
+ ```
279
+ project/
280
+ └── openspec/
281
+ ├── specs/ # 功能規格
282
+ ├── changes/ # 活動變更提案
283
+ └── archive/ # 已歸檔的變更
284
+ ```
285
+
286
+ 整合功能:
287
+ - `dash validate .` 自動偵測 `openspec/` 並驗證規格格式
288
+ - `dash health .` 顯示規格健康度評分
289
+
290
+ ### 專案健康評分
291
+
292
+ 類似 Lighthouse 的評分機制:
293
+
294
+ ```bash
295
+ # 單一專案
296
+ dash health .
297
+
298
+ # 所有專案
299
+ dash health --all
300
+
301
+ # JSON 輸出
302
+ dash health . --json
303
+ ```
304
+
305
+ 評分項目:
306
+ - 安全性:機敏資料、依賴漏洞
307
+ - 品質:程式碼規範、檔案結構
308
+ - 維護性:技術債務、文件完整度
309
+ - 效能:Bundle 大小、依賴數量
310
+
311
+ ### 程式碼統計
312
+
313
+ ```bash
314
+ # 單一專案
315
+ dash stats .
316
+
317
+ # 比較所有專案
318
+ dash stats --all
319
+ ```
320
+
321
+ 顯示:語言分佈、檔案數量與行數、最大檔案排行、複雜度警告
322
+
323
+ ### 測試執行
324
+
325
+ ```bash
326
+ # 執行測試
327
+ dash test .
328
+
329
+ # 含覆蓋率報告
330
+ dash test . --coverage
331
+
332
+ # 測試所有專案
333
+ dash test --all
334
+ ```
335
+
336
+ 自動偵測:vitest、jest、karma、pytest
337
+
338
+ ### 四大類測試套件
339
+
340
+ 執行完整測試套件並產生報告:
341
+
342
+ ```bash
343
+ # 執行四大類測試
344
+ dash test-suite .
345
+
346
+ # 產生 Word 報告
347
+ dash test-suite . --word test-report.docx
348
+
349
+ # 產生 Markdown 報告
350
+ dash test-suite . --md test-report.md
351
+
352
+ # 只執行特定類型
353
+ dash test-suite . --types UIT,Smoke
354
+ ```
355
+
356
+ | 測試類型 | 說明 | 測試檔案 |
357
+ |----------|------|----------|
358
+ | UIT | 單元測試 | `*.spec.ts` |
359
+ | Smoke | 煙霧測試 | `e2e/smoke.spec.ts` |
360
+ | E2E | 端對端測試 | `e2e/mes-system.spec.ts` |
361
+ | UAT | 驗收測試 | `e2e/uat.spec.ts` |
362
+
363
+ 報告包含:
364
+ - 測試摘要與統計圖表
365
+ - 各測試類型明細
366
+ - API 測試回應內容
367
+ - 系統截圖
368
+
369
+ ### E2E 煙霧測試
370
+
371
+ 使用 agent-browser 檢查頁面 JS 錯誤:
372
+
373
+ ```bash
374
+ # 基本測試
375
+ dash e2e https://your-app.vercel.app
376
+
377
+ # 只檢查頁面載入
378
+ dash e2e https://example.com --check load
379
+
380
+ # 延長超時
381
+ dash e2e https://example.com --timeout 60000
382
+
383
+ # 失敗時截圖
384
+ dash e2e https://example.com --screenshot
385
+
386
+ # 手機版測試
387
+ dash e2e https://example.com --mobile
388
+
389
+ # JSON 輸出
390
+ dash e2e https://example.com --json
391
+ ```
392
+
393
+ 需要先安裝 agent-browser:
394
+
395
+ ```bash
396
+ npm install -g agent-browser
397
+ agent-browser install
398
+ ```
399
+
400
+ ### 專案報告
401
+
402
+ 產生完整 HTML 報告:
403
+
404
+ ```bash
405
+ # 基本報告
406
+ dash report .
407
+
408
+ # 含 UI 截圖
409
+ dash report . --screenshot -u http://localhost:3000
410
+
411
+ # 不執行測試
412
+ dash report . --no-test
413
+ ```
414
+
415
+ ### 即時監控
416
+
417
+ ```bash
418
+ # 監控檔案變更
419
+ dash watch .
420
+
421
+ # 發現問題自動修復
422
+ dash watch . --fix
423
+ ```
424
+
425
+ ### AI 程式碼助手
426
+
427
+ 使用 Gemini 2.5 分析程式碼:
428
+
429
+ ```bash
430
+ # 分析程式碼
431
+ dash ai analyze src/main.py
432
+
433
+ # 安全分析
434
+ dash ai analyze src/api.ts --focus security
435
+
436
+ # 建議修復
437
+ dash ai fix src/main.py -e "TypeError: Cannot read property"
438
+
439
+ # 生成測試
440
+ dash ai test src/utils.py
441
+
442
+ # 解釋程式碼
443
+ dash ai explain src/complex-algo.py
444
+
445
+ # 審查 commit
446
+ dash ai review .
447
+ ```
448
+
449
+ 需設定環境變數:`export GEMINI_API_KEY="your-api-key"`
450
+
451
+ ### 視覺 AI 分析
452
+
453
+ 使用 agent-browser 截圖 + Gemini AI 進行 UI/UX 分析:
454
+
455
+ ```bash
456
+ # 基本視覺分析
457
+ dash vision https://example.com
458
+
459
+ # UI/UX 專家分析
460
+ dash vision https://example.com --type ui_ux
461
+
462
+ # 無障礙 (WCAG 2.1) 檢查
463
+ dash vision https://example.com --type accessibility
464
+
465
+ # 效能視覺指標
466
+ dash vision https://example.com --type performance
467
+
468
+ # 分析本地截圖
469
+ dash vision /path/to/screenshot.png
470
+ ```
471
+
472
+ 分析類型:
473
+
474
+ | 類型 | 說明 |
475
+ |------|------|
476
+ | `general` | 整體 UI/UX 評估 |
477
+ | `ui_ux` | 專業 UI/UX 分析 |
478
+ | `accessibility` | WCAG 2.1 無障礙檢查 |
479
+ | `performance` | 視覺效能指標 |
480
+
481
+ 需要安裝 agent-browser 和設定 Gemini API Key。
482
+
483
+ ### 瀏覽器自動化 API
484
+
485
+ Python API 提供完整的瀏覽器控制:
486
+
487
+ ```python
488
+ from dash_devtools.browser import AgentBrowser, quick_screenshot
489
+
490
+ # 快速截圖
491
+ quick_screenshot("https://example.com", "/tmp/screenshot.png")
492
+
493
+ # 完整控制
494
+ browser = AgentBrowser()
495
+ browser.open("https://example.com")
496
+ browser.snapshot(interactive_only=True) # 取得可互動元素
497
+ browser.fill("@e1", "test@example.com") # 填寫表單
498
+ browser.click("@e2") # 點擊按鈕
499
+ browser.screenshot("/tmp/result.png")
500
+ browser.close()
501
+ ```
502
+
503
+ 視覺分析 API:
504
+
505
+ ```python
506
+ from dash_devtools.vision import analyze_url, compare_screenshots
507
+
508
+ # 截圖並分析
509
+ result = analyze_url("https://example.com", analysis_type="ui_ux")
510
+ print(result.issues)
511
+ print(result.recommendations)
512
+
513
+ # 比較兩張截圖 (視覺回歸)
514
+ result = compare_screenshots("before.png", "after.png")
515
+ print(result.analysis)
516
+ ```
517
+
518
+ ### 資料庫遷移
519
+
520
+ Alembic 整合:
521
+
522
+ ```bash
523
+ # 初始化
524
+ dash db init .
525
+
526
+ # 檢視狀態
527
+ dash db status .
528
+
529
+ # 產生遷移
530
+ dash db generate . -m "add user table"
531
+
532
+ # 升級
533
+ dash db upgrade .
534
+
535
+ # 降級(需確認)
536
+ dash db downgrade . -r -1 --confirm
537
+ ```
538
+
539
+ ### 診斷工具
540
+
541
+ ```bash
542
+ dash doctor
543
+ ```
544
+
545
+ 顯示:系統資訊、Python 路徑、套件版本、環境變數
546
+
547
+ ## Git Hooks
548
+
549
+ 安裝 pre-push hook 自動驗證:
550
+
551
+ ```bash
552
+ # 基本安裝
553
+ dash hooks install .
554
+
555
+ # 嚴格模式:測試失敗會阻止推送
556
+ dash hooks install . --strict
557
+
558
+ # 啟用 E2E 煙霧測試
559
+ dash hooks install . --e2e https://your-app.vercel.app
560
+
561
+ # 嚴格 E2E 模式:E2E 失敗會阻止推送
562
+ dash hooks install . --e2e https://your-app.vercel.app --strict-e2e
563
+ ```
564
+
565
+ Push 前會自動執行:
566
+ 1. 檢查 Emoji
567
+ 2. 掃描機敏資料 (GitGuardian 或本地規則)
568
+ 3. 驗證專案規範
569
+ 4. 執行測試 (vitest/jest/pytest)
570
+ 5. E2E 煙霧測試 (如有設定)
571
+
572
+ ## 模板
573
+
574
+ 位於 `templates/` 目錄:
575
+
576
+ | 模板 | 說明 |
577
+ |------|------|
578
+ | `deploy-netlify.yml` | GitHub Actions Netlify 備援部署 |
579
+
580
+ ---
581
+
582
+ # Claude Code 指令集指南
583
+
584
+ ## 內建指令總覽
585
+
586
+ ### 會話管理
587
+
588
+ | 指令 | 功能 | 說明 |
589
+ |------|------|------|
590
+ | `/clear` | 清空對話 | 重新開始對話 |
591
+ | `/resume [session]` | 恢復對話 | 按 ID 或名稱恢復 |
592
+ | `/compact [指令]` | 壓縮對話 | 節省 token,可指定焦點 |
593
+ | `/rewind` | 回退 | 回退對話和程式碼變更 |
594
+ | `/rename <name>` | 重新命名 | 為當前會話命名 |
595
+ | `/exit` | 退出 | 結束 CLI |
596
+
597
+ ### 設定與配置
598
+
599
+ | 指令 | 功能 | 說明 |
600
+ |------|------|------|
601
+ | `/config` | 設定介面 | 開啟設定頁面 |
602
+ | `/model` | 切換模型 | 選擇 AI 模型 |
603
+ | `/permissions` | 權限管理 | 查看/更新工具權限 |
604
+ | `/settings` | 設定管理 | 管理所有設定 |
605
+ | `/sandbox` | 沙箱模式 | 啟用安全沙箱 |
606
+ | `/status` | 狀態資訊 | 版本、模型、帳號狀態 |
607
+
608
+ ### 工具與整合
609
+
610
+ | 指令 | 功能 | 說明 |
611
+ |------|------|------|
612
+ | `/mcp` | MCP 伺服器 | 管理 MCP 連接 |
613
+ | `/hooks` | Hooks 設定 | 管理工具事件鉤子 |
614
+ | `/ide` | IDE 整合 | 管理編輯器整合 |
615
+ | `/plugin` | 插件管理 | 管理 Claude Code 插件 |
616
+ | `/agents` | 代理管理 | 管理自定義子代理 |
617
+
618
+ ### 開發與專案
619
+
620
+ | 指令 | 功能 | 說明 |
621
+ |------|------|------|
622
+ | `/init` | 初始化 | 建立 CLAUDE.md |
623
+ | `/memory` | 編輯記憶 | 編輯 CLAUDE.md |
624
+ | `/review` | 程式碼審查 | 請求審查 |
625
+ | `/add-dir` | 新增目錄 | 添加工作目錄 |
626
+
627
+ ### 資訊與統計
628
+
629
+ | 指令 | 功能 | 說明 |
630
+ |------|------|------|
631
+ | `/cost` | Token 用量 | 顯示使用統計 |
632
+ | `/context` | 上下文視覺化 | 彩色網格顯示 |
633
+ | `/todos` | 待辦事項 | 列出當前 TODO |
634
+ | `/stats` | 使用統計 | 日常用法、連勝記錄 |
635
+ | `/usage` | 用量限制 | 訂閱計劃使用量 |
636
+
637
+ ### 系統與診斷
638
+
639
+ | 指令 | 功能 | 說明 |
640
+ |------|------|------|
641
+ | `/doctor` | 健康檢查 | 檢查安裝狀態 |
642
+ | `/bug` | 回報 Bug | 發送至 Anthropic |
643
+ | `/release-notes` | 發行說明 | 查看更新內容 |
644
+ | `/login` / `/logout` | 帳號管理 | 登入/登出 |
645
+
646
+ ### 輸出與匯出
647
+
648
+ | 指令 | 功能 | 說明 |
649
+ |------|------|------|
650
+ | `/vim` | Vim 模式 | 進入 Vim 編輯模式 |
651
+ | `/export [file]` | 匯出對話 | 匯出到檔案或剪貼簿 |
652
+ | `/output-style` | 輸出樣式 | 設定回應格式 |
653
+
654
+ ---
655
+
656
+ ## 自定義指令 (Slash Commands)
657
+
658
+ ### 建立位置
659
+
660
+ | 範圍 | 路徑 | 說明 |
661
+ |------|------|------|
662
+ | 專案級 | `.claude/commands/xxx.md` | 與團隊共享 |
663
+ | 個人級 | `~/.claude/commands/xxx.md` | 跨專案可用 |
664
+
665
+ ### 基本格式
666
+
667
+ ```markdown
668
+ ---
669
+ description: 指令說明(必填)
670
+ argument-hint: [參數提示]
671
+ allowed-tools: Bash(npm:*), Read, Edit
672
+ ---
673
+
674
+ # 指令內容
675
+
676
+ 你的提示詞內容...
677
+ ```
678
+
679
+ ### Frontmatter 選項
680
+
681
+ | 選項 | 必填 | 說明 |
682
+ |------|------|------|
683
+ | `description` | 是 | 指令說明 |
684
+ | `argument-hint` | 否 | 參數提示 |
685
+ | `allowed-tools` | 否 | 允許的工具 |
686
+ | `model` | 否 | 指定模型 |
687
+
688
+ ### 範例:Chrome 截圖指令
689
+
690
+ ```markdown
691
+ ---
692
+ description: Chrome 截圖或輸出 PDF
693
+ argument-hint: <url> [--pdf]
694
+ allowed-tools: Bash(*/Google Chrome*:*), Read
695
+ ---
696
+
697
+ 截圖網頁並進行 UI/UX 分析。
698
+
699
+ 使用方式:
700
+ - `/chrome https://example.com` - 截圖
701
+ - `/chrome https://example.com --pdf` - 輸出 PDF
702
+ ```
703
+
704
+ ### 動態內容
705
+
706
+ 使用 `!` 前綴執行 Bash 指令:
707
+
708
+ ```markdown
709
+ 當前狀態:!`git status`
710
+ 最近提交:!`git log -3 --oneline`
711
+ ```
712
+
713
+ 使用 `@` 前綴引用檔案:
714
+
715
+ ```markdown
716
+ 請參考 @src/utils/helpers.js 的實作
717
+ ```
718
+
719
+ ---
720
+
721
+ ## Skills(複雜工作流)
722
+
723
+ ### 與 Slash Commands 差異
724
+
725
+ | 項目 | Slash Commands | Skills |
726
+ |------|----------------|--------|
727
+ | 複雜度 | 簡單提示 | 複雜工作流 |
728
+ | 結構 | 單一 `.md` 檔 | 目錄 + 多檔案 |
729
+ | 觸發 | 手動 `/command` | 自動偵測上下文 |
730
+ | 適用 | 常用指令 | 團隊標準流程 |
731
+
732
+ ### 目錄結構
733
+
734
+ ```
735
+ .claude/skills/my-skill/
736
+ ├── SKILL.md # 必須 - 主要說明
737
+ ├── REFERENCE.md # 選用 - API 參考
738
+ ├── EXAMPLES.md # 選用 - 使用範例
739
+ └── scripts/ # 選用 - 輔助腳本
740
+ └── helper.py
741
+ ```
742
+
743
+ ### SKILL.md 格式
744
+
745
+ ```markdown
746
+ ---
747
+ name: skill-name
748
+ description: 簡短說明(何時使用)
749
+ allowed-tools: Read, Bash(npm:*)
750
+ ---
751
+
752
+ # Skill 名稱
753
+
754
+ ## 何時使用
755
+ 描述觸發條件...
756
+
757
+ ## 步驟
758
+ 1. 步驟一
759
+ 2. 步驟二
760
+
761
+ ## 範例
762
+ 具體使用範例...
763
+ ```
764
+
765
+ ---
766
+
767
+ ## CLI 參數
768
+
769
+ ### 啟動方式
770
+
771
+ ```bash
772
+ claude # 交互模式
773
+ claude "問題" # 帶初始提示
774
+ claude -p "問題" # 非交互模式
775
+ claude -c # 恢復最近對話
776
+ claude -r "session-name" # 恢復特定會話
777
+ cat file | claude -p "問題" # 管道輸入
778
+ ```
779
+
780
+ ### 常用參數
781
+
782
+ | 參數 | 說明 |
783
+ |------|------|
784
+ | `--model <model>` | 指定模型 |
785
+ | `--add-dir <path>` | 添加工作目錄 |
786
+ | `--permission-mode plan` | Plan 模式 |
787
+ | `--tools "Bash,Edit,Read"` | 指定工具 |
788
+ | `--append-system-prompt` | 追加系統提示 |
789
+
790
+ ---
791
+
792
+ ## 專案清單
793
+
794
+ | 專案 | 類型 | 說明 |
795
+ |------|------|------|
796
+ | MES 製造執行 | Angular + PrimeNG | 再生廠製造執行系統 |
797
+ | SSO 管理後台 | Vite + Shoelace | 用戶與權限管理 |
798
+ | EAP 設備自動化 | Vite + Shoelace | 設備自動化平台 |
799
+ | VAC 承攬商門禁 | Vite + Shoelace | 承攬商門禁管理系統 |
800
+ | RFID 追蹤 | Vite + Shoelace | RFID 標籤追蹤系統 |
801
+ | MCS 物料控制 | Vite + Shoelace | 物料控制系統 |
802
+ | MIDS 材料追蹤 | Vite + Shoelace | 材料識別與追蹤系統 |
803
+ | GHG 碳排管理 | Vite + Shoelace | 溫室氣體排放管理系統 |
804
+ | BPM 簽核流程 | Vite + Shoelace | 簽核流程管理系統 |
805
+ | RMS 配方管理 | Vite + Shoelace | 配方管理系統 |
806
+ | 8D 問題管理 | Vite + Shoelace | 8D 問題解決流程管理 |
807
+ | Vision AI | Python | AI 影像辨識系統 |
808
+ | API Center | Vite + Shoelace | API 管理中心與開發文件 |
809
+
810
+ ## 開發
811
+
812
+ ```bash
813
+ # 安裝開發依賴
814
+ pip install -e ".[dev]"
815
+
816
+ # 執行測試
817
+ pytest
818
+
819
+ # 格式化
820
+ black .
821
+ ```
822
+
823
+ ## 致謝
824
+
825
+ 本專案使用以下開源工具:
826
+
827
+ - **[agent-browser](https://github.com/vercel-labs/agent-browser)** - Vercel Labs 開發的瀏覽器自動化工具
828
+ - **[Playwright](https://playwright.dev/)** - Microsoft 的 E2E 測試框架
829
+ - **[Google Gemini](https://ai.google.dev/)** - AI 視覺分析引擎
830
+ - **[Rich](https://github.com/Textualize/rich)** - 終端 UI 美化
831
+
832
+ ## 授權
833
+
834
+ MIT License - DashAI