kenaz 0.3.21 → 0.3.23

package/core/dev/design/matrix_format_DESIGN_SPEC.md

@@ -1,601 +0,0 @@
-# .matrix 檔案格式設計規格
-
-> **版本**: 1.0.0
-> **日期**: 2026-02-07
-> **狀態**: 設計階段
-> **作者**: Developer Team
-
----
-
-## 📋 執行摘要
-
-.matrix 是一種革命性的資料格式，專為 LLM Agent 優化設計。核心目標是將 Token 消耗降至現有 JSON/YAML 格式的 1/10，同時保持極速讀取和分層查詢能力。
-
-**核心指標**:
-- 🎯 Token 壓縮比：8-12:1（目標 10:1）
-- ⚡ 讀取速度：< 100ms
-- 📊 檔案大小減少：70-90%
-- 🔍 查詢延遲：< 50ms
-
----
-
-## 🎯 設計目標
-
-### 1. 極致 Token 經濟
-- **問題**: 現有格式（JSON/YAML）充斥大量語法符號（{}, [], "", :）和重複欄位名，浪費 Token
-- **目標**: 將 Token 消耗降至 1/10
-- **策略**: 極簡語法 + 縮寫 + 列式存儲思維
-
-### 2. 極速讀取
-- **問題**: Agent 需要讀取多個文件才能獲取專案狀態
-- **目標**: 單文件包含所有信息，分層讀取
-- **策略**: 索引優先 + 按需加載
-
-### 3. Agent 原生
-- **問題**: 二進制格式需轉換，反而耗 Token
-- **目標**: LLM 可直接讀取，零轉換成本
-- **策略**: 文本格式 + 語義化縮寫
-
-### 4. 創新格式
-- **問題**: 受限於現有格式規範
-- **目標**: 發明全新語法，突破傳統
-- **策略**: DSL（Domain Specific Language）
-
----
-
-## 🏗️ 技術架構
-
-### 文件結構（三層設計）
-
-```
-# .matrix v1.0
-@meta |v=1.0|c=project-status|t=260207-0530|
-@index |t=task|e=123|c=15|p=10|b=2|
-@data
-T121|st=C|p=P0|tt=2h15m|
-T122|st=P|p=P1|tt=1h30m|
-T123|st=B|p=P2|blk=API_DOWN|
-```
-
-### 層級說明
-
-| 層級 | 名稱 | 用途 | Token 消耗 |
-|------|------|------|-----------|
-| `@meta` | 元數據層 | 版本、類型、時間戳 | ~20 tokens |
-| `@index` | 索引層 | 快速查詢索引（統計、關鍵字） | ~50 tokens |
-| `@data` | 數據層 | 實際數據內容（按需加載） | 變動 |
-
-### 分層讀取策略
-
-```bash
-# Level 1（概要）- 只讀 @meta + @index
-matrix read project-status.matrix --level 1
-# 輸出: ~70 tokens
-
-# Level 2（中等詳細）- + 最近 N 條記錄
-matrix read project-status.matrix --level 2 --last 10
-# 輸出: ~300 tokens
-
-# Level 3（完整）- 全部數據
-matrix read project-status.matrix --level 3
-# 輸出: ~2000 tokens（原本 JSON 需 20000 tokens）
-```
-
----
-
-## 📝 語法規則
-
-### 1. 欄位名縮寫（Field Abbreviation）
-
-| 原名 | 縮寫 | 範例 |
-|------|------|------|
-| `status` | `st` | `st=C` |
-| `priority` | `p` | `p=P0` |
-| `id` | `i` | `i=T123` |
-| `time` | `t` | `t=260207` |
-| `type` | `ty` | `ty=task` |
-| `count` | `c` | `c=15` |
-| `description` | `d` | `d=Fix bug` |
-| `blocked_by` | `blk` | `blk=API_DOWN` |
-
-**縮寫規則**:
-- 單詞 → 首字母或前 2-3 字母
-- 常用欄位 → 單字母（s, t, i, p）
-- 罕見欄位 → 2-3 字母（blk, desc）
-
-### 2. 值代碼化（Value Encoding）
-
-| 原值 | 代碼 | 範例 |
-|------|------|------|
-| `completed` | `C` | `st=C` |
-| `in_progress` | `P` | `st=P` |
-| `pending` | `D` | `st=D` |
-| `blocked` | `B` | `st=B` |
-| `P0` | `0` | `p=0` |
-| `P1` | `1` | `p=1` |
-| `true` | `1` | `active=1` |
-| `false` | `0` | `active=0` |
-
-**代碼化規則**:
-- 狀態 → 單字母（C, P, D, B）
-- 優先級 → 數字（0, 1, 2, 3）
-- 布林值 → 0/1
-- 時間戳 → 縮短格式（2026-02-07 → 260207）
-
-### 3. 符號最小化（Symbol Minimization）
-
-| 傳統格式 | .matrix 格式 | Token 節省 |
-|---------|-------------|-----------|
-| `{"status": "completed"}` | `st=C` | 85% |
-| `["T121", "T122", "T123"]` | `T121,T122,T123` | 60% |
-| `\n` | `\|` | 50% |
-| `{}` | 省略 | 100% |
-
-**符號規則**:
-- 分隔符: `|`（記錄間）、`,`（列表）、`=`（鍵值）
-- 無大括號、無方括號、無引號
-- 換行符最小化（用 `|` 替代）
-
-### 4. 列式存儲思維（Columnar Thinking）
-
-傳統格式（行式）:
-```json
-[
-  {"id": "T121", "status": "completed", "priority": "P0"},
-  {"id": "T122", "status": "in_progress", "priority": "P1"},
-  {"id": "T123", "status": "blocked", "priority": "P2"}
-]
-```
-Token 消耗: ~150 tokens
-
-.matrix 格式（列式思維）:
-```
-@data
-T121|st=C|p=0|
-T122|st=P|p=1|
-T123|st=B|p=2|
-```
-Token 消耗: ~20 tokens
-
-**壓縮比**: 7.5:1 ⭐
-
----
-
-## 🔍 索引策略
-
-### 複合索引（Multi-dimensional Index）
-
-```
-@index |t=task|e=123|c=15|p=10|b=2|st_C=10|st_P=3|st_B=2|
-```
-
-**索引欄位說明**:
-- `t=task`: 類型（type）
-- `e=123`: 總條目數（entries）
-- `c=15`: 已完成數（completed）
-- `p=10`: 進行中數（in_progress）
-- `b=2`: 阻塞數（blocked）
-- `st_C=10`: 狀態統計（completed）
-
-**查詢優化**:
-```bash
-# 查詢已完成任務（只需讀索引）
-matrix query tasks.matrix --status=completed
-# → 直接從索引知道有 10 條，無需讀取 @data
-
-# 查詢特定任務（使用索引定位）
-matrix query tasks.matrix --id=T123
-# → 索引指向位置，快速定位
-```
-
----
-
-## 📊 Token 壓縮分析
-
-### 場景 A: 專案狀態快照
-
-**現狀（JSON）**:
-```json
-{
-  "project": "KenazAI",
-  "status": "active",
-  "tasks": {
-    "total": 123,
-    "completed": 100,
-    "in_progress": 15,
-    "blocked": 8
-  },
-  "lastUpdate": "2026-02-07T05:30:00Z"
-}
-```
-Token 消耗: ~80 tokens
-
-**.matrix 格式**:
-```
-# .matrix v1.0
-@meta |v=1.0|c=project-status|t=260207-0530|
-@index |tot=123|c=100|p=15|b=8|
-```
-Token 消耗: ~15 tokens
-
-**壓縮比**: 5.3:1 ⭐
-
-### 場景 B: 任務歷史記錄（30 條）
-
-**現狀（JSON）**:
-```json
-[
-  {
-    "id": "TASK_121",
-    "status": "completed",
-    "priority": "P0",
-    "duration": "2h 15m",
-    "completed_at": "2026-02-06T14:30:00Z"
-  },
-  // ... 29 more tasks
-]
-```
-Token 消耗: ~1500 tokens
-
-**.matrix 格式**:
-```
-@data
-T121|st=C|p=0|dur=135m|ct=260206-1430|
-T122|st=C|p=1|dur=90m|ct=260206-1500|
-... (28 more lines)
-```
-Token 消耗: ~180 tokens
-
-**壓縮比**: 8.3:1 ⭐⭐
-
-### 場景 C: Agent 記憶系統
-
-**現狀（Markdown + JSON）**:
-```markdown
-# Recent Activities
-
-## 2026-02-06
-- TASK_121: Completed API integration (Priority: P0, Duration: 2h 15m)
-- TASK_122: Started UI refactoring (Priority: P1, Status: In Progress)
-
-## 2026-02-05
-- TASK_120: Fixed database migration bug (Priority: P0)
-...
-```
-Token 消耗: ~800 tokens（5 天記錄）
-
-**.matrix 格式**:
-```
-@meta |v=1.0|c=memory|t=260207-0530|r=5d|
-@index |d=260207,260206,260205,260204,260203|e=25|
-@data
-260206|T121,st=C,p=0,dur=135m;T122,st=P,p=1|
-260205|T120,st=C,p=0,bug=db_migration|
-...
-```
-Token 消耗: ~80 tokens
-
-**壓縮比**: 10:1 ⭐⭐⭐
-
----
-
-## 🛠️ 讀取工具設計
-
-### CLI 工具規格（matrix-cli）
-
-#### 基本命令
-
-```bash
-# 讀取命令
-matrix read <file> [options]
-  --level <1|2|3>         # 讀取層級（預設 2）
-  --format <compact|readable>  # 輸出格式（預設 readable）
-  --tokens                # 顯示 Token 計數
-
-# 查詢命令
-matrix query <file> <query> [options]
-  --topic <topic>         # 主題過濾
-  --status <status>       # 狀態過濾
-  --date <date>           # 日期過濾
-  --limit <n>             # 限制結果數量
-
-# 摘要命令
-matrix summary <file> [options]
-  --tokens <n>            # 限制 Token 數（預設 500）
-  --period <period>       # 時間範圍（3d, 7d, 30d）
-
-# 搜索命令
-matrix search <file> <keyword> [options]
-  --context <n>           # 顯示上下文（預設 2 行）
-  --highlight             # 高亮關鍵字
-
-# 範圍查詢
-matrix range <file> [options]
-  --from <date>           # 開始日期
-  --to <date>             # 結束日期
-```
-
-#### 轉換和驗證
-
-```bash
-# 格式轉換
-matrix convert <input> <output> [options]
-  --from <json|yaml|matrix>   # 來源格式
-  --to <json|yaml|matrix>     # 目標格式
-  --mode <compact|readable>   # 轉換模式
-
-# 語法驗證
-matrix validate <file> [options]
-  --strict                # 嚴格模式
-  --fix                   # 自動修復
-
-# 格式化
-matrix format <file> [options]
-  --mode <compact|readable>
-  --in-place              # 原地修改
-```
-
-#### 統計和分析
-
-```bash
-# 統計信息
-matrix stats <file>
-# 輸出：
-#   Entries: 123
-#   Levels: 3
-#   Token Count: 2,456
-#   Compression Ratio: 8.3:1
-
-# Token 計數
-matrix tokens <file> [options]
-  --compare <other-file>  # 對比分析
-
-# 差異對比
-matrix diff <file1> <file2> [options]
-  --token-diff            # 顯示 Token 差異
-  --stats                 # 顯示統計對比
-```
-
-### API 設計（Node.js）
-
-```javascript
-const Matrix = require('@kenaz/matrix');
-
-// 讀取文件
-const data = Matrix.read('project-status.matrix', {
-  level: 2,  // 讀取層級
-  format: 'object'  // 輸出格式
-});
-
-// 查詢
-const tasks = Matrix.query('tasks.matrix', {
-  status: 'completed',
-  priority: 'P0',
-  limit: 10
-});
-
-// 摘要
-const summary = Matrix.summary('memory.matrix', {
-  tokens: 500,
-  period: '7d'
-});
-
-// 轉換
-Matrix.convert('tasks.json', 'tasks.matrix', {
-  mode: 'compact'
-});
-
-// 驗證
-const valid = Matrix.validate('project.matrix', {
-  strict: true
-});
-```
-
----
-
-## 🚀 實作路線圖
-
-### Phase 1: 核心格式定義和解析器（Week 1-2）
-
-**目標**: 定義語法規則，實現基本解析器
-
-**交付物**:
-- ✅ 格式規格文檔（SPEC.md）
-- ✅ 語法定義（BNF 或 EBNF）
-- ✅ 縮寫映射表（ABBREVIATIONS.md）
-- ✅ 解析器實現（parser.js）
-- ✅ 序列化器實現（serializer.js）
-- ✅ 單元測試（覆蓋率 > 90%）
-
-**驗收標準**:
-- 能正確解析所有範例文件
-- 能正確序列化 JavaScript 物件
-- Token 壓縮比 ≥ 5:1
-
-### Phase 2: CLI 工具開發（Week 3-4）
-
-**目標**: 實現完整的命令行工具
-
-**交付物**:
-- ✅ matrix-cli（核心工具）
-- ✅ matrix-convert（轉換工具）
-- ✅ matrix-validate（驗證工具）
-- ✅ matrix-format（格式化工具）
-- ✅ 使用文檔（CLI_GUIDE.md）
-
-**驗收標準**:
-- 所有命令正常運作
-- 錯誤信息友善明確
-- 性能符合目標（讀取 < 100ms）
-
-### Phase 3: 與現有系統整合（Week 5-6）
-
-**目標**: 整合到 KenazAI Pipeline 系統
-
-**交付物**:
-- ✅ Pipeline 腳本更新（dev/scripts/*.ps1）
-- ✅ 自動轉換工具（JSON → .matrix）
-- ✅ Git Hook 整合
-- ✅ 遷移文檔（MIGRATION_GUIDE.md）
-
-**驗收標準**:
-- Pipeline 正常運作
-- 無功能退化
-- 所有測試通過
-
-### Phase 4: 高級功能（Week 7-8）
-
-**目標**: 實現進階功能和優化
-
-**交付物**:
-- ✅ Watch Mode（自動同步）
-- ✅ Lint 工具（最佳實踐檢查）
-- ✅ VS Code 插件（語法高亮）
-- ✅ 性能優化（大文件支援）
-
-**驗收標準**:
-- Watch Mode 穩定運作
-- IDE 插件可用
-- 大文件（> 10MB）性能良好
-
----
-
-## 🔄 整合計劃
-
-### 與現有系統共存
-
-**雙格式支援策略**:
-```
-Week 1-2: 安裝工具，測試環境
-Week 3-4: 新任務使用 .matrix，舊任務保留 JSON
-Week 5-6: 漸進式遷移（批量轉換）
-Week 7-8: 完全切換，移除 JSON 備份
-```
-
-### 遷移策略
-
-**自動遷移腳本**:
-```bash
-# 批量轉換所有 JSON 文件
-matrix-migrate convert --dir dev/pipeline --from json --to matrix
-
-# 驗證轉換結果
-matrix-migrate validate --dir dev/pipeline
-
-# 創建備份
-matrix-migrate backup --dir dev/pipeline --backup-dir .backup
-```
-
-**回退機制**:
-- 保留 JSON 備份（1-2 週）
-- 提供回退腳本
-- 監控錯誤率
-
-### 向後兼容性
-
-**版本管理**:
-```
-# 文件頭包含版本號
-# .matrix v1.0
-
-# 解析器支援多版本
-Matrix.read('file.matrix', {
-  version: 'auto'  // 自動偵測版本
-});
-```
-
-**廢棄策略**:
-- v1.0 → v1.1: 保持完全兼容
-- v1.x → v2.0: 提供轉換工具
-- 廢棄警告期: 至少 3 個月
-
-### 測試計劃
-
-**測試層級**:
-1. **單元測試** - 解析器、序列化器（覆蓋率 > 90%）
-2. **整合測試** - CLI 工具、API（覆蓋率 > 80%）
-3. **端到端測試** - Pipeline 整合（關鍵路徑 100%）
-4. **性能測試** - 大文件、並發讀寫
-5. **壓力測試** - 極限場景（10000+ 條記錄）
-
-**測試案例**:
-```bash
-# 功能測試
-npm run test:unit
-npm run test:integration
-npm run test:e2e
-
-# 性能測試
-npm run test:performance
-
-# Token 壓縮比驗證
-npm run test:compression
-```
-
----
-
-## 📈 成功指標
-
-| 指標 | 目標 | 測量方式 |
-|------|------|---------|
-| Token 壓縮比 | ≥ 8:1 | matrix tokens --compare |
-| 讀取速度 | < 100ms | 性能測試 |
-| 檔案大小減少 | ≥ 70% | ls -lh 對比 |
-| 轉換準確率 | 100% | 自動化測試 |
-| 錯誤率 | < 0.1% | 監控日誌 |
-| 開發完成時間 | 6-8 週 | 實際追蹤 |
-
----
-
-## ⚠️ 風險評估
-
-### 技術風險
-
-| 風險 | 嚴重性 | 機率 | 緩解措施 |
-|------|--------|------|---------|
-| 新語法學習曲線 | 中 | 高 | 完整文檔 + 自動轉換工具 |
-| 解析器 Bug | 高 | 中 | 高測試覆蓋率 + Code Review |
-| 性能不符預期 | 中 | 低 | 早期性能測試 + 優化 |
-| 兼容性問題 | 高 | 中 | 雙格式支援 + 回退機制 |
-
-### 業務風險
-
-| 風險 | 嚴重性 | 機率 | 緩解措施 |
-|------|--------|------|---------|
-| 遷移中斷服務 | 高 | 低 | 漸進式遷移 + 備份 |
-| 團隊抵觸新格式 | 中 | 中 | 充分溝通 + 培訓 |
-| 開發時間超期 | 中 | 中 | 敏捷開發 + MVP 優先 |
-
----
-
-## 📚 附錄
-
-### A. 完整範例文件
-
-參見:
-- `dev/design/matrix_format_EXAMPLE_project_status.matrix`
-- `dev/design/matrix_format_EXAMPLE_tasks.matrix`
-- `dev/design/matrix_format_EXAMPLE_memory.matrix`
-
-### B. 語法 BNF 定義
-
-參見: `dev/design/matrix_format_SYNTAX_BNF.md`
-
-### C. 縮寫映射表
-
-參見: `dev/design/matrix_format_ABBREVIATIONS.md`
-
-### D. Token 對比測試
-
-參見: `dev/design/matrix_format_TOKEN_COMPARISON.md`
-
----
-
-## 📞 聯繫方式
-
-**設計團隊**: Developer Team
-**技術負責人**: Integration Specialist
-**文檔維護**: Technical Writer
-
-**更新日誌**:
-- 2026-02-07: v1.0.0 初版發布