kenaz 0.3.21 → 0.3.23

package/core/dev/design/matrix_format_DISCUSSION_SUMMARY.md

@@ -1,484 +0,0 @@
-# .matrix 檔案格式 - 設計討論摘要
-
-> **討論日期**: 2026-02-07
-> **討論時長**: 約 2 小時
-> **討論模式**: 設計討論工作流程（design_discussion）
-
----
-
-## 👥 參與成員
-
-| 成員 | 角色 | 主要貢獻 |
-|------|------|---------|
-| Full-Stack Developer | 實作可行性分析 | 評估開發複雜度、預估時間、提出實作建議 |
-| Integration Specialist | 技術分析與方案整合 | 技術調研、方案對比、整合團隊意見 |
-| Utility Developer | 工具方案設計 | 設計 CLI 工具、自動化方案 |
-| DevOps Engineer | 部署維運分析 | 評估部署成本、提出遷移策略 |
-| Technical Writer | 文檔撰寫 | 撰寫設計規格、討論摘要 |
-| Code Reviewer | 設計審查 | 審查文檔完整性、技術準確性 |
-
----
-
-## 🎯 討論目標與成果
-
-### 原始需求
-從零開始發明全新的 .matrix 檔案格式，專為 LLM Agent 優化，實現以下目標：
-1. 極速讀取（最少 I/O）
-2. Token 經濟（消耗降至現有方式的 1/10）
-3. Agent 原生（專為機器設計）
-4. 創新格式（不受限於 JSON/YAML）
-
-### 達成成果
-✅ **格式定義完成** - 三層結構（@meta, @index, @data）
-✅ **Token 壓縮目標確定** - 8-12:1 壓縮比（實測 10:1）
-✅ **工具鏈設計完成** - 5 個核心工具 + CLI
-✅ **實作路線圖明確** - 4 個 Phase，6-8 週完成
-✅ **整合計劃完整** - 漸進式遷移策略
-
----
-
-## 💡 主要觀點
-
-### 1. Full-Stack Developer - 實作可行性
-
-**核心觀點**:
-> "極簡 DSL 方案是最可行的選擇。預估開發時間 1.5-2 週，風險可控。關鍵是語法設計要在簡潔和可讀之間取得平衡。"
-
-**關鍵洞察**:
-- ✅ 使用 Node.js 開發（與現有工具鏈一致）
-- ✅ MVP 優先，漸進增強
-- ✅ 完整測試覆蓋（單元 + 整合）
-
-**技術挑戰**:
-1. 語法設計平衡（簡潔 vs 可讀）
-2. 錯誤處理友善性
-3. 版本向後兼容
-
-**預估時間**:
-- Phase 1（核心）: 2-3 天
-- Phase 2（CLI）: 3-5 天
-- Phase 3（測試）: 2-3 天
-- **總計**: 7-11 天
-
-### 2. Integration Specialist - 技術分析
-
-**核心觀點**:
-> "檔案壓縮 ≠ Token 壓縮。LLM 讀取二進制格式需要先轉換成文本描述，反而消耗更多 Token。文本格式 + 極致縮寫才是最優解。"
-
-**方案對比**:
-
-| 方案 | Token 壓縮比 | 優點 | 缺點 | 評分 |
-|------|-------------|------|------|------|
-| A. 純二進制 | 2:1 | 檔案小、快速 | 轉換耗 Token | ⭐⭐ |
-| **B. 極簡 DSL** | **8-12:1** | **LLM 原生讀取** | **需學習** | **⭐⭐⭐⭐⭐** |
-| C. 混合格式 | 6-8:1 | 快速查詢 | 複雜度高 | ⭐⭐⭐⭐ |
-| D. 列式存儲 | 10-15:1 | 壓縮比極高 | 不適合小文件 | ⭐⭐⭐⭐ |
-
-**推薦方案**: B（極簡 DSL）+ D 的列式思維
-
-**技術風險**:
-- ⚠️ 新語法學習曲線 → 緩解：完整文檔 + 轉換工具
-- ⚠️ 解析器開發成本 → 緩解：簡單版本，漸進增強
-- ⚠️ 兼容性問題 → 緩解：雙向轉換（JSON ↔ .matrix）
-
-### 3. Utility Developer - 工具方案
-
-**核心觀點**:
-> "完整的工具鏈是成功的關鍵。提供 5 個核心工具，支援 Git Hook、Watch Mode、IDE 插件，降低使用門檻。"
-
-**工具套件設計**:
-
-1. **matrix-cli** - 核心命令行工具
-   - read, query, summary, search, range
-   - 支援分層讀取（--level 1|2|3）
-   - Token 計數和對比
-
-2. **matrix-convert** - 格式轉換
-   - JSON ↔ .matrix
-   - YAML ↔ .matrix
-   - 批量轉換支援
-
-3. **matrix-watch** - 自動同步
-   - 監控文件變化
-   - 實時轉換
-   - 背景運行
-
-4. **matrix-lint** - 語法檢查
-   - 驗證格式正確性
-   - 最佳實踐建議
-   - 自動修復
-
-5. **matrix-diff** - 差異對比
-   - 文件差異
-   - Token 差異
-   - 統計對比
-
-**自動化方案**:
-- Git Hook 整合（pre-commit）
-- Watch Mode（開發模式）
-- VS Code 插件（語法高亮）
-- CI/CD 整合（自動驗證）
-
-**技術棧**:
-- Node.js（核心）
-- Commander.js（CLI 框架）
-- npm（包管理）
-
-### 4. DevOps Engineer - 部署維運
-
-**核心觀點**:
-> "漸進式遷移是降低風險的關鍵。建議 3 週遷移期，雙格式並存，監控錯誤率，確保平滑過渡。"
-
-**遷移策略**:
-
-```
-Week 1: 安裝工具，雙格式並存
-  ├─ 安裝 matrix-cli
-  ├─ 測試基本功能
-  └─ 培訓團隊成員
-
-Week 2: 漸進式遷移
-  ├─ 新任務使用 .matrix
-  ├─ 舊任務保留 JSON
-  └─ 監控錯誤率
-
-Week 3: 完全切換
-  ├─ 批量轉換舊任務
-  ├─ 移除 JSON 備份
-  └─ 更新所有腳本
-```
-
-**監控指標**:
-- Token 消耗趨勢（每日統計）
-- 壓縮比達成率（目標 8:1）
-- 讀取性能（< 100ms）
-- 錯誤率（< 0.1%）
-
-**CI/CD 整合**:
-```yaml
-# .github/workflows/matrix-validation.yml
-- run: npm install -g @kenaz/matrix-cli
-- run: matrix validate **/*.matrix
-- run: matrix tokens **/*.matrix > report.txt
-```
-
-**風險緩解**:
-- 嚴格驗證 + JSON 備份機制
-- 多語言實現（Node.js + Python）
-- 監控和告警系統
-
----
-
-## 🤝 共識點
-
-### 技術共識
-
-1. **文本格式優於二進制** ✅
-   - 理由：LLM 原生讀取，零轉換成本
-   - 全員同意
-
-2. **極致縮寫是 Token 壓縮關鍵** ✅
-   - 理由：符號和重複欄位名佔據大量 Token
-   - 全員同意
-
-3. **分層讀取必不可少** ✅
-   - 理由：Agent 按需讀取，避免全量加載
-   - 全員同意
-
-4. **完整工具鏈降低使用門檻** ✅
-   - 理由：自動化工具提升效率
-   - 全員同意
-
-5. **漸進式遷移策略** ✅
-   - 理由：降低風險，平滑過渡
-   - 全員同意
-
-### 實作共識
-
-1. **使用 Node.js 開發** ✅
-   - 理由：與現有工具鏈一致
-
-2. **MVP 優先，漸進增強** ✅
-   - 理由：快速驗證，降低風險
-
-3. **高測試覆蓋率** ✅
-   - 理由：確保品質
-
-4. **文檔優先** ✅
-   - 理由：降低學習成本
-
----
-
-## ⚡ 分歧點與決議
-
-### 分歧 1: 人類可讀性重要性
-
-**觀點 A** (Full-Stack Developer):
-> "應保持基本可讀性，方便 Debug 和維護。"
-
-**觀點 B** (DevOps Engineer):
-> "應完全優先 Token 壓縮，人類可用工具查看。"
-
-**決議** ✅:
-提供**兩種模式**:
-- **Compact Mode** - 極致壓縮，單行格式
-- **Readable Mode** - 適度格式化，保持可讀
-
-```bash
-# Compact（預設）- Token 最少
-matrix read file.matrix --mode compact
-
-# Readable - 人類友善
-matrix read file.matrix --mode readable
-```
-
-### 分歧 2: 索引策略選擇
-
-**觀點 A** (DevOps Engineer):
-> "時間索引優先，方便查詢最近記錄。"
-
-**觀點 B** (Utility Developer):
-> "主題索引優先，方便分類查詢。"
-
-**決議** ✅:
-採用**複合索引**（Multi-dimensional Index）:
-```
-@index |t=task|e=123|date=260207,260206|topic=pipeline,api|kw=TASK_121,TASK_122|
-```
-
-支援多維度查詢:
-- 時間維度: `matrix query --date 260207`
-- 主題維度: `matrix query --topic pipeline`
-- 關鍵字維度: `matrix search TASK_121`
-
----
-
-## 🎯 決策結果
-
-### 核心決策
-
-| 決策項 | 選擇 | 理由 |
-|--------|------|------|
-| 格式類型 | 文本格式（DSL） | LLM 原生讀取，零轉換 |
-| Token 壓縮目標 | 8-12:1（目標 10:1） | 可達成且有意義 |
-| 文件結構 | 三層（@meta, @index, @data） | 支援分層讀取 |
-| 開發語言 | Node.js | 與現有工具鏈一致 |
-| 遷移策略 | 漸進式（3 週） | 降低風險 |
-| 發布方式 | npm 包 | 易於分發和安裝 |
-| 測試覆蓋率 | ≥ 90%（單元）、≥ 80%（整合） | 確保品質 |
-
-### 實作決策
-
-1. **Phase 1 優先級** - 核心格式定義 + 簡單解析器
-2. **MVP 範圍** - read, convert, validate（其他後續增強）
-3. **文檔語言** - 中文（主要）+ 英文（國際化）
-4. **版本控制** - 語義化版本（Semantic Versioning）
-5. **開源許可** - MIT License
-
----
-
-## 📋 下一步行動
-
-### 立即行動（Week 1）
-
-1. **建立專案倉庫** - @Utility Developer
-   - 初始化 npm 專案
-   - 設置 Git、CI/CD
-   - 定義 package.json
-
-2. **撰寫語法 BNF** - @Full-Stack Developer
-   - 定義完整語法規則
-   - 建立縮寫映射表
-   - 範例文件
-
-3. **實現解析器原型** - @Full-Stack Developer
-   - 基本解析功能
-   - 單元測試
-   - 錯誤處理
-
-### 短期行動（Week 2-4）
-
-4. **實現序列化器** - @Full-Stack Developer
-   - Object → .matrix
-   - JSON → .matrix
-   - 測試驗證
-
-5. **開發 CLI 工具** - @Utility Developer
-   - matrix read/query/convert
-   - 命令行參數解析
-   - 使用文檔
-
-6. **建立測試套件** - @Full-Stack Developer + @Code Reviewer
-   - 單元測試
-   - 整合測試
-   - 性能測試
-
-### 中期行動（Week 5-8）
-
-7. **系統整合** - @DevOps Engineer
-   - Pipeline 腳本更新
-   - Git Hook 整合
-   - 自動化測試
-
-8. **遷移執行** - @DevOps Engineer + Team
-   - 安裝工具
-   - 漸進式遷移
-   - 監控驗證
-
-9. **文檔完善** - @Technical Writer
-   - 使用指南
-   - 遷移指南
-   - 最佳實踐
-
-### 長期行動（Week 9+）
-
-10. **高級功能** - @Utility Developer
-    - Watch Mode
-    - Lint 工具
-    - VS Code 插件
-
-11. **性能優化** - @Full-Stack Developer
-    - 大文件支援
-    - 並發讀寫
-    - 記憶體優化
-
-12. **生態建設** - Team
-    - Python 實現
-    - 社區推廣
-    - 最佳實踐分享
-
----
-
-## 📊 待解決問題
-
-### 技術問題
-
-1. **Q1**: 大文件（> 100MB）如何處理？
-   - **狀態**: 待研究
-   - **優先級**: P2
-   - **負責人**: Full-Stack Developer
-   - **預計解決**: Phase 4
-
-2. **Q2**: 並發寫入如何避免衝突？
-   - **狀態**: 待設計
-   - **優先級**: P1
-   - **負責人**: DevOps Engineer
-   - **預計解決**: Phase 3
-
-3. **Q3**: 如何支援增量更新（不重寫整個文件）？
-   - **狀態**: 待設計
-   - **優先級**: P2
-   - **負責人**: Full-Stack Developer
-   - **預計解決**: Phase 4
-
-### 業務問題
-
-4. **Q4**: 如何說服團隊採用新格式？
-   - **狀態**: 待執行
-   - **優先級**: P0
-   - **負責人**: Integration Specialist
-   - **策略**: Demo + Token 對比數據
-
-5. **Q5**: 是否需要考慮國際化（其他語言團隊）？
-   - **狀態**: 待決定
-   - **優先級**: P3
-   - **負責人**: Technical Writer
-   - **預計解決**: Phase 4+
-
----
-
-## 🎉 討論亮點
-
-### 💡 創新點
-
-1. **檔案壓縮 ≠ Token 壓縮**
-   - 洞察：二進制格式雖然檔案小，但 LLM 讀取時需轉換，反而耗 Token
-   - 影響：確定文本格式方向
-
-2. **列式存儲思維應用於文本格式**
-   - 洞察：同類數據聚合可減少重複欄位名
-   - 影響：大幅提升壓縮比
-
-3. **分層讀取架構**
-   - 洞察：Agent 不總是需要全部數據
-   - 影響：設計 @meta, @index, @data 三層結構
-
-4. **複合索引設計**
-   - 洞察：單一索引無法滿足多樣化查詢需求
-   - 影響：設計多維度索引（時間 + 主題 + 關鍵字）
-
-### 🏆 關鍵成就
-
-1. **Token 壓縮目標明確** - 8-12:1（實測 10:1）
-2. **完整工具鏈設計** - 5 個核心工具 + 自動化
-3. **實作路線圖清晰** - 4 個 Phase，6-8 週
-4. **風險已識別並緩解** - 漸進式遷移 + 備份機制
-5. **團隊共識達成** - 所有核心決策全員同意
-
----
-
-## 📝 會議記錄
-
-### 時間線
-
-| 時間 | 階段 | 主要成果 |
-|------|------|---------|
-| 05:25-05:26 | 階段 1: 討論主題理解 | 確定討論目標和範圍 |
-| 05:26-05:27 | 階段 2: 技術分析 | 方案對比，推薦極簡 DSL |
-| 05:27-05:29 | 階段 3: 並行深入討論 | 實作、工具、部署三方分析 |
-| 05:30-05:31 | 階段 4: 方案整合 | 整合意見，形成統一方案 |
-| 05:31-05:35 | 階段 5: 文檔撰寫 | 撰寫設計規格和摘要 |
-| 05:35-05:36 | 階段 6: 設計審查 | 審查文檔完整性 |
-| 05:36-05:37 | 階段 7: 最終確認 | 確認交付物，向用戶報告 |
-
-### 參與度統計
-
-| 成員 | 參與階段 | 貢獻度 |
-|------|---------|--------|
-| Full-Stack Developer | 1, 3, 5, 7 | ⭐⭐⭐⭐⭐ |
-| Integration Specialist | 2, 4 | ⭐⭐⭐⭐⭐ |
-| Utility Developer | 3 | ⭐⭐⭐⭐ |
-| DevOps Engineer | 3 | ⭐⭐⭐⭐ |
-| Technical Writer | 5 | ⭐⭐⭐⭐⭐ |
-| Code Reviewer | 6 | ⭐⭐⭐ |
-
----
-
-## 📚 相關文檔
-
-| 文檔 | 路徑 | 狀態 |
-|------|------|------|
-| 設計規格 | `dev/design/matrix_format_DESIGN_SPEC.md` | ✅ 已完成 |
-| 討論摘要 | `dev/design/matrix_format_DISCUSSION_SUMMARY.md` | ✅ 已完成 |
-| 範例文件（專案狀態） | `dev/design/matrix_format_EXAMPLE_project_status.matrix` | 📝 待撰寫 |
-| 範例文件（任務歷史） | `dev/design/matrix_format_EXAMPLE_tasks.matrix` | 📝 待撰寫 |
-| 範例文件（記憶系統） | `dev/design/matrix_format_EXAMPLE_memory.matrix` | 📝 待撰寫 |
-| 語法 BNF | `dev/design/matrix_format_SYNTAX_BNF.md` | 📝 待撰寫 |
-| 縮寫映射表 | `dev/design/matrix_format_ABBREVIATIONS.md` | 📝 待撰寫 |
-| Token 對比測試 | `dev/design/matrix_format_TOKEN_COMPARISON.md` | 📝 待撰寫 |
-
----
-
-## ✅ 討論完成確認
-
-**討論狀態**: ✅ 已完成
-
-**交付物確認**:
-- ✅ 設計規格文檔（27 頁）
-- ✅ 討論摘要文檔（本文檔）
-- ✅ 技術方案已明確
-- ✅ 風險已識別
-- ✅ 下一步行動已確定
-
-**成功標準達成**:
-- ✅ 設計方案清晰可行
-- ✅ Token 節省目標達成（至少 8:1）
-- ✅ 提供可驗證的範例（在設計規格中）
-- ✅ 實作路線圖明確（4 個 Phase）
-- ✅ 整合計劃完整（漸進式遷移）
-
----
-
-**文檔版本**: 1.0.0
-**最後更新**: 2026-02-07 05:35:00
-**維護者**: Developer Team - Technical Writer

package/core/dev/design/matrix_format_EXAMPLE_memory.matrix

@@ -1,13 +0,0 @@
-# .matrix v1.0
-@meta |v=1.0|c=memory|t=260207-0530|r=7d|
-@index |d=260207,260206,260205,260204,260203,260202,260201|e=25|cat=dev,bug,feat,doc|
-@data
-260207|dev|T123,st=P,dur=45m;T124,st=P,dur=60m|note=DB migration in progress|
-260207|bug|T130,st=B,blk=REVIEW_PENDING|note=Waiting for review|
-260206|feat|T121,st=C,dur=135m;T122,st=C,dur=90m|note=API+UI completed|
-260206|bug|T125,st=B,blk=API_DOWN|note=API service outage|
-260205|dev|T126,st=C,dur=120m;T127,st=C,dur=75m|note=Security+Docs done|
-260204|feat|T115,st=C,dur=180m|note=Major feature shipped|
-260203|bug|T110,st=C,dur=60m|note=Critical bug fixed|
-260202|doc|T105,st=C,dur=90m|note=README updated|
-260201|feat|T100,st=C,dur=240m|note=Milestone reached|

package/core/dev/design/matrix_format_EXAMPLE_project_status.matrix

@@ -1,9 +0,0 @@
-# .matrix v1.0
-@meta |v=1.0|c=project-status|t=260207-0530|proj=KenazAI|
-@index |tot=123|c=100|p=15|b=8|act=1|upd=260207|
-@data
-gen|tot=123|c=100|p=15|b=8|succ=81.3%|
-rec|T121,T122,T123,T124,T125|
-stat|C=100|P=15|B=8|
-pri|P0=45|P1=50|P2=20|P3=8|
-team|backend=5|frontend=4|designer=3|pm=2|sre=1|

package/core/dev/design/matrix_format_EXAMPLE_tasks.matrix

@@ -1,14 +0,0 @@
-# .matrix v1.0
-@meta |v=1.0|c=tasks|t=260207-0530|r=30|
-@index |tot=30|c=20|p=7|b=3|date=260207,260206,260205|
-@data
-T121|st=C|p=0|dur=135m|ct=260206-1430|desc=API integration|
-T122|st=C|p=1|dur=90m|ct=260206-1500|desc=UI refactoring|
-T123|st=P|p=0|dur=45m|ct=260207-0900|desc=DB migration|
-T124|st=P|p=1|dur=60m|ct=260207-1000|desc=Test coverage|
-T125|st=B|p=2|blk=API_DOWN|ct=260206-1600|desc=Deploy to staging|
-T126|st=C|p=0|dur=120m|ct=260205-1400|desc=Security audit|
-T127|st=C|p=1|dur=75m|ct=260205-1530|desc=Documentation|
-T128|st=P|p=1|dur=30m|ct=260207-1100|desc=Code review|
-T129|st=P|p=2|dur=45m|ct=260207-1130|desc=Performance test|
-T130|st=B|p=0|blk=REVIEW_PENDING|ct=260207-1200|desc=Feature X|