From 0b2e44feb2d11eebc0dc1fcb34982d00e6378b26 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:40:31 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 ++ README.md | 3 + commands/ngised-ceps.md | 259 ++++++++++++++++++++++++++++ commands/stnemeriuqer-ceps.md | 316 ++++++++++++++++++++++++++++++++++ plugin.lock.json | 49 ++++++ 5 files changed, 638 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/ngised-ceps.md create mode 100644 commands/stnemeriuqer-ceps.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..0453387 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "orik", + "description": "Orik tools", + "version": "0.1.0", + "author": { + "name": "Miles Chou" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..dda38ae --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# orik + +Orik tools diff --git a/commands/ngised-ceps.md b/commands/ngised-ceps.md new file mode 100644 index 0000000..386ff0c --- /dev/null +++ b/commands/ngised-ceps.md @@ -0,0 +1,259 @@ +--- +description: 從現有實作逆向推導技術設計 +argument-hint: [功能路徑或模組名稱] +allowed-tools: Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS +--- + +# 逆向工程：從實作推導設計 + +從現有程式碼逆向分析並生成技術設計文件：**$ARGUMENTS** + +## 逆向分析流程概述 + +**ORIK** 是從既有實作逆向推導出設計和需求的流程： +- 階段 1：**實作 → 設計** (ngised-ceps) +- 階段 2：**設計 → 需求** (stnemeriuqer-ceps) + +## 任務：分析實作並推導設計 + +### 1. 程式碼探索和理解 + +#### 1.1 識別程式碼範圍 +根據 **$ARGUMENTS** 確定要分析的範圍： +- 如果是功能路徑：分析該路徑下的所有相關檔案 +- 如果是模組名稱：追蹤模組的所有元件和相依性 +- 如果是 API 端點：從端點追蹤到所有相關層級 + +#### 1.2 程式碼結構分析 +探索並記錄： +``` +程式碼基礎結構 +├── 檔案組織模式 +├── 目錄結構意圖 +├── 命名慣例 +└── 模組邊界 +``` + +#### 1.3 技術堆疊識別 +自動偵測： +- 程式語言和版本 +- 使用的框架和函式庫 +- 資料庫技術 +- 外部服務整合 +- 建置和部署工具 + +### 2. 架構逆向工程 + +#### 2.1 架構模式識別 +分析並識別： +- **結構模式**：MVC、分層架構、微服務、單體式 +- **行為模式**：觀察者、策略、工廠、單例 +- **整合模式**：API Gateway、Message Queue、Event Bus + +#### 2.2 元件關係分析 +建立元件依賴圖： +```mermaid +graph TB + Controller --> Service + Service --> Repository + Repository --> Database + Service --> ExternalAPI +``` + +#### 2.3 資料流追蹤 +從入口點追蹤資料流動： +1. HTTP 請求入口 +2. 中介層處理 +3. 業務邏輯執行 +4. 資料存取層 +5. 回應生成 + +### 3. API 和介面分析 + +#### 3.1 API 端點提取 +掃描並記錄所有 API 端點： +```bash +# 搜尋路由定義 +grep -r "Route\|route\|@app\|@router" --include="*.py" --include="*.js" --include="*.php" + +# 搜尋控制器方法 +grep -r "def.*Controller\|function.*Action" --include="*.py" --include="*.php" +``` + +#### 3.2 介面契約推導 +從實作推導介面定義： +- 請求參數和驗證規則 +- 回應格式和狀態碼 +- 錯誤處理模式 +- 認證和授權需求 + +### 4. 資料模型逆向工程 + +#### 4.1 實體識別 +從程式碼提取領域實體： +```bash +# 搜尋模型定義 +grep -r "class.*Model\|@Entity\|Schema\|Table" --include="*.py" --include="*.php" --include="*.js" + +# 搜尋資料庫遷移 +find . -path "*/migrations/*" -o -path "*/schema/*" +``` + +#### 4.2 關係推導 +分析實體間關係： +- 一對一、一對多、多對多 +- 外鍵約束 +- 級聯規則 +- 索引策略 + +#### 4.3 業務規則提取 +從驗證和約束推導規則： +- 欄位驗證規則 +- 唯一性約束 +- 業務邏輯約束 +- 計算欄位邏輯 + +### 5. 設計文件生成 + +根據分析結果生成 `.orik/reverse/$ARGUMENTS/design.md`： + +```markdown +# 逆向工程技術設計 + +## 分析元資料 +- 分析日期：[當前日期] +- 分析範圍：$ARGUMENTS +- 程式碼行數：[統計] +- 檔案數量：[統計] + +## 概覽 +[從程式碼推導的系統概述] + +## 架構 +[識別的架構模式和結構] + +### 技術堆疊（推導） +- **語言**：[偵測結果] +- **框架**：[偵測結果] +- **資料庫**：[偵測結果] +- **相依套件**：[從 package.json/requirements.txt/composer.json 提取] + +### 架構決策推論 +[從實作模式推導可能的架構決策原因] + +## 資料流 +[追蹤的資料流程圖] + +## 元件和介面 + +### 識別的服務 +[從程式碼提取的服務列表和方法] + +### API 端點（發現） +| 方法 | 路由 | 推測用途 | 參數 | 回應 | +|------|------|----------|------|------| +| [提取的端點資料] | + +## 資料模型 + +### 領域實體（推導） +[從模型檔案提取的實體] + +### 實體關係（分析） +[從關聯定義推導的 ER 圖] + +## 錯誤處理模式 +[從 try-catch 和錯誤處理程式碼分析] + +## 安全實作（觀察） +[從程式碼識別的安全措施] + +## 測試覆蓋（如果存在） +[從測試檔案分析測試策略] + +## 推導的設計模式 +[識別的設計模式和最佳實踐] + +## 技術債務和改進建議 +[發現的潛在問題和優化機會] +``` + +### 6. 生成追蹤元資料 + +建立 `.orik/reverse/$ARGUMENTS/analysis.json`： +```json +{ + "analysis_type": "implementation_to_design", + "timestamp": "當前時間戳記", + "scope": "$ARGUMENTS", + "files_analyzed": [], + "patterns_identified": [], + "dependencies_found": [], + "next_phase": "stnemeriuqer-ceps", + "confidence_level": "high|medium|low", + "gaps_identified": [] +} +``` + +### 7. 分析報告生成 + +生成分析摘要給使用者： +``` +📊 逆向工程分析完成 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📁 分析範圍：$ARGUMENTS +📈 分析檔案：[數量] 個檔案 +🔍 識別模式：[列出主要架構模式] +🎯 置信度：[高/中/低] + +✅ 已生成： + • 設計文件：.orik/reverse/$ARGUMENTS/design.md + • 分析資料：.orik/reverse/$ARGUMENTS/analysis.json + +🔜 下一步： + 執行 /orik:stnemeriuqer-ceps $ARGUMENTS + 從設計推導需求和規格 +``` + +## 分析技巧 + +### 搜尋模式庫 +```bash +# Laravel/PHP +"Route::|class.*Controller|function.*Action|Schema::|DB::" + +# Python/FastAPI +"@app\.|@router\.|class.*Model|def.*endpoint|async def" + +# Node.js/Express +"router\.|app\.|module\.exports|const.*Schema|mongoose\." + +# Spring Boot +"@RestController|@RequestMapping|@Entity|@Repository" +``` + +### 自動化分析工具整合 +- 使用 AST（抽象語法樹）分析 +- 呼叫靜態分析工具 +- 整合相依性分析工具 +- 利用程式碼複雜度分析 + +## 注意事項 + +1. **保持客觀**：只記錄觀察到的，避免過度推測 +2. **標記不確定性**：明確標示推導和假設 +3. **完整性檢查**：確保沒有遺漏重要元件 +4. **版本意識**：注意程式碼可能混合不同時期的實作 +5. **隱藏邏輯**：注意設定檔、環境變數等外部配置 + +## 指示 + +1. **系統性探索** - 從入口點開始，逐層深入 +2. **模式識別** - 尋找重複的結構和慣例 +3. **關係追蹤** - 建立元件間的依賴圖 +4. **完整記錄** - 包含所有發現，即使看似瑣碎 +5. **結構化輸出** - 按照設計文件標準格式組織 +6. **標記缺口** - 明確指出缺失或不清楚的部分 +7. **提供證據** - 每個推論都要有程式碼位置佐證 + +生成的設計文件將作為下一階段（stnemeriuqer-ceps）的輸入，用於推導原始需求。 \ No newline at end of file diff --git a/commands/stnemeriuqer-ceps.md b/commands/stnemeriuqer-ceps.md new file mode 100644 index 0000000..564522b --- /dev/null +++ b/commands/stnemeriuqer-ceps.md @@ -0,0 +1,316 @@ +--- +description: 從技術設計逆向推導需求和規格 +argument-hint: [功能路徑或模組名稱] +allowed-tools: Bash, Read, Write, Edit, MultiEdit +--- + +# 逆向工程：從設計推導需求 + +從技術設計逆向推導原始需求和規格：**$ARGUMENTS** + +## 前置條件驗證 + +### 檢查設計文件 +- 設計文件：@.orik/reverse/$ARGUMENTS/design.md +- 分析資料：@.orik/reverse/$ARGUMENTS/analysis.json + +**必須先執行 `/orik:ngised-ceps $ARGUMENTS` 生成設計文件** + +## 任務：從設計推導需求 + +### 1. 設計分析和功能識別 + +#### 1.1 功能清單提取 +從設計文件識別所有功能： +``` +功能映射 +├── API 端點 → 使用者功能 +├── 服務方法 → 業務能力 +├── 資料操作 → CRUD 需求 +└── 整合點 → 外部互動需求 +``` + +#### 1.2 使用者角色推導 +從認證和授權模式推導： +- 識別的角色類型 +- 權限矩陣 +- 存取控制規則 +- 多租戶需求（如果有） + +#### 1.3 業務流程重建 +從資料流和序列圖推導： +- 主要業務流程 +- 使用者旅程 +- 系統互動模式 +- 事件驅動流程 + +### 2. 業務規則提取 + +#### 2.1 驗證規則轉換為需求 +從程式碼驗證推導業務規則： +``` +驗證邏輯 → 業務約束 +├── 欄位驗證 → 資料品質需求 +├── 關係約束 → 業務關聯規則 +├── 狀態轉換 → 工作流程需求 +└── 計算邏輯 → 業務計算規則 +``` + +#### 2.2 錯誤處理映射 +從錯誤處理推導異常場景： +- 預期的錯誤情況 → 邊界條件需求 +- 錯誤訊息 → 使用者回饋需求 +- 重試邏輯 → 可靠性需求 +- 降級策略 → 容錯需求 + +### 3. 非功能性需求推導 + +#### 3.1 效能需求 +從實作模式推導： +- 快取策略 → 回應時間需求 +- 分頁實作 → 大量資料處理需求 +- 非同步處理 → 並發需求 +- 索引策略 → 查詢效能需求 + +#### 3.2 安全需求 +從安全實作推導： +- 認證機制 → 身分驗證需求 +- 加密實作 → 資料保護需求 +- 輸入消毒 → 安全輸入需求 +- 稽核日誌 → 合規需求 + +#### 3.3 可用性需求 +從架構設計推導： +- 負載平衡 → 高可用需求 +- 資料備份 → 災難復原需求 +- 健康檢查 → 監控需求 +- 錯誤恢復 → 韌性需求 + +### 4. EARS 格式需求生成 + +將推導的需求轉換為 EARS 格式： + +#### 4.1 功能需求模板 +``` +從 API: POST /api/users +推導為: 當使用者提交註冊表單，則系統應建立新帳戶並發送確認郵件 + +從驗證: email.unique() +推導為: 如果電子郵件已存在，則系統應拒絕註冊並顯示錯誤訊息 +``` + +#### 4.2 非功能需求模板 +``` +從快取: Redis TTL=3600 +推導為: 當查詢使用者資料時，系統應在1秒內回應 + +從重試: maxRetries=3 +推導為: 如果外部服務失敗，則系統應重試最多3次 +``` + +### 5. 需求文件生成 + +生成 `.orik/reverse/$ARGUMENTS/requirements.md`： + +```markdown +# 逆向工程需求文件 + +## 分析元資料 +- 推導日期：[當前日期] +- 基於設計：.orik/reverse/$ARGUMENTS/design.md +- 置信度：[高/中/低] +- 推導方法：ORIK 逆向工程 + +## 簡介 +[從功能總覽推導的系統目的和價值主張] + +## 推導的業務背景 +### 可能的業務驅動因素 +[從技術選擇推測業務考量] + +### 推測的使用者問題 +[從功能設計推導要解決的問題] + +## 需求 + +### 需求 1：[主要功能領域] +**推導的使用者故事：** 作為 [角色]，我想要 [功能]，以便 [利益] + +#### 驗收標準（EARS 格式） +1. 當 [從程式碼觀察的觸發] 則系統應 [從實作推導的行為] +2. 如果 [從驗證推導的條件] 則系統應 [從錯誤處理推導的回應] +3. 當 [從狀態管理推導] 系統應持續 [從背景任務推導] + +**證據來源：** +- 檔案：[程式碼位置] +- 函數：[具體實作] +- 置信度：[高/中/低] + +### 需求 2：[次要功能領域] +[繼續相同模式...] + +## 非功能性需求（推導） + +### 效能需求 +[從實作模式推導的效能期望] + +### 安全需求 +[從安全措施推導的安全需求] + +### 可用性需求 +[從架構推導的可用性需求] + +## 識別的需求缺口 + +### 可能遺漏的需求 +- [從設計不一致性推測] +- [從未使用的程式碼推測] +- [從TODO註解推測] + +### 不明確的需求 +- [模糊的業務規則] +- [硬編碼的假設] +- [缺乏錯誤處理的區域] + +## 需求優先級推測 + +### 核心需求（必須有） +[從核心功能和嚴格驗證推導] + +### 重要需求（應該有） +[從輔助功能和部分實作推導] + +### 期望需求（可以有） +[從實驗性功能或註解掉的程式碼推導] + +## 需求追溯矩陣 + +| 需求編號 | 設計元件 | 程式碼實作 | 測試覆蓋 | 置信度 | +|---------|---------|-----------|---------|--------| +| REQ-1.1 | API端點 | controller.py:45 | ✓ | 高 | +| REQ-1.2 | 服務層 | service.py:120 | ✗ | 中 | +[...] +``` + +### 6. 規格文件生成 + +生成 `.orik/reverse/$ARGUMENTS/spec.json`： +```json +{ + "reverse_engineering": true, + "original_type": "implementation", + "analysis_phases": { + "implementation_analyzed": true, + "design_derived": true, + "requirements_extracted": true + }, + "confidence_metrics": { + "overall": "medium", + "functional_requirements": "high", + "non_functional_requirements": "medium", + "business_context": "low" + }, + "coverage": { + "code_analyzed": "85%", + "features_identified": 23, + "requirements_derived": 18, + "gaps_found": 5 + }, + "recommendations": [ + "與領域專家驗證推導的需求", + "補充缺失的業務背景", + "確認非功能性需求的準確性" + ], + "timestamp": "當前時間戳記" +} +``` + +### 7. 生成驗證建議 + +建立 `.orik/reverse/$ARGUMENTS/validation-checklist.md`： +```markdown +# 需求驗證檢查清單 + +## 與利害關係人確認 +- [ ] 推導的使用者角色是否完整？ +- [ ] 業務流程是否符合實際運作？ +- [ ] 優先級是否正確？ + +## 與開發團隊確認 +- [ ] 技術約束是否正確理解？ +- [ ] 非功能需求是否合理？ +- [ ] 是否有未記錄的重要功能？ + +## 與測試團隊確認 +- [ ] 驗收標準是否可測試？ +- [ ] 邊界條件是否完整？ +- [ ] 測試場景是否涵蓋所有需求？ + +## 建議的後續行動 +1. 安排需求審查會議 +2. 與原始開發者訪談（如果可能） +3. 進行使用者訪談以驗證假設 +4. 建立正式的需求文件 +``` + +### 8. 完成報告 + +生成分析完成報告： +``` +🔄 ORIK 逆向工程完成 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📊 分析統計 + • 識別功能需求：[數量] + • 推導非功能需求：[數量] + • 發現需求缺口：[數量] + • 整體置信度：[高/中/低] + +📁 生成文件 + ✓ 需求文件：.orik/reverse/$ARGUMENTS/requirements.md + ✓ 規格資料：.orik/reverse/$ARGUMENTS/spec.json + ✓ 驗證清單：.orik/reverse/$ARGUMENTS/validation-checklist.md + +⚠️ 重要提醒 + 推導的需求需要與實際利害關係人驗證 + +🎯 建議下一步 + 1. 審查推導的需求文件 + 2. 與團隊驗證準確性 + 3. 補充缺失的業務背景 +``` + +## 推導策略 + +### 從程式碼到意圖 +``` +程式碼模式 → 設計決策 → 業務需求 +├── CRUD 操作 → 資料管理 → 資訊維護需求 +├── 工作流程碼 → 狀態機 → 業務流程需求 +├── 驗證規則 → 資料品質 → 業務規則需求 +└── 整合代碼 → 系統互動 → 整合需求 +``` + +### 置信度評估 +- **高**：有明確程式碼證據和一致模式 +- **中**：有部分證據但需要推論 +- **低**：主要基於假設和慣例 + +## 注意事項 + +1. **標記所有推導**：明確區分事實和推測 +2. **保留證據鏈**：每個需求都要追溯到程式碼 +3. **識別矛盾**：記錄不一致或衝突的實作 +4. **承認限制**：明確指出無法推導的部分 +5. **建議驗證**：提供驗證推導正確性的方法 + +## 指示 + +1. **仔細分析設計文件** - 提取所有功能和非功能線索 +2. **應用 EARS 格式** - 將觀察轉換為標準需求語句 +3. **建立追溯性** - 連接需求到設計到程式碼 +4. **評估置信度** - 為每個推導標記可信度 +5. **識別缺口** - 找出可能遺漏或不完整的需求 +6. **提供驗證路徑** - 建議如何確認推導的準確性 +7. **生成可行動建議** - 提供具體的後續步驟 + +生成的需求文件提供了從實作逆向推導的完整需求視圖，但需要與實際利害關係人驗證以確保準確性。 \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..2586de1 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:MilesChou/claude-marketplace:plugins/orik", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "63398bd0bbc117881626d758a5f650c3a0ba38bb", + "treeHash": "3322960f5360c801dbf5854fdc49931bf8c4e51dbd6f6f012a28d900a9a4314a", + "generatedAt": "2025-11-28T10:12:07.793647Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "orik", + "description": "Orik tools", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "e6d069ff89d0eca6a4873a10e01c1bfe13482f4a97c87b4817f09378ddd73b38" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "139bc88dc410ee4219c6c90c873a9574ae43ac8e3a2571e8865102fdf4d7e492" + }, + { + "path": "commands/stnemeriuqer-ceps.md", + "sha256": "96eb72ac92b6aa23274bc219c23da5fcdd3e961ee219e99894ec4b42d34b66e2" + }, + { + "path": "commands/ngised-ceps.md", + "sha256": "4381861df3f7f7339f170943969fad351415e612e91bd730e2ccd411bde1ae74" + } + ], + "dirSha256": "3322960f5360c801dbf5854fdc49931bf8c4e51dbd6f6f012a28d900a9a4314a" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file