kenaz 0.3.21 → 0.3.23

package/core/dev/design/matrix_v2_COGNITIVE_DESIGN.md

@@ -1,503 +0,0 @@
-# .matrix v2.0 - 從 AI 認知角度重新思考資訊組織
-
-> **核心突破**: Token 經濟不只是字符壓縮，更是認知效率
->
-> **版本**: v2.0 (Cognitive Architecture)
-> **日期**: 2026-02-07
-> **狀態**: 深度設計階段
-> **團隊**: Developer Team (Leader + Team 模式)
-
----
-
-## 🧠 執行摘要
-
-第一輪討論產出了 .matrix v1.0（極簡 DSL 格式），達成 **5-10:1** Token 壓縮比。但這仍是「語法層面的優化」。
-
-**本設計從 AI 認知本質重新思考**，提出 5 個創新方案和漸進式演進路線圖：
-
-| 版本 | Token 效率 | 核心技術 | 實作時間 | 狀態 |
-|------|-----------|---------|---------|------|
-| v1.0 | 5-10:1 | 極簡 DSL | - | ✅ 已完成 |
-| **v2.0** | **20-50:1** | 差分狀態流 | 4-6 週 | 🚀 推薦立即實作 |
-| v2.1 | 30-70:1 | 分層抽象記憶 | 6-10 週 | ⏳ 中期規劃 |
-| v2.2 | 累計提升 | Agent 專屬視圖 | 5-8 週 | ⏳ 中期規劃 |
-| v3.0 | 50-100:1 | 混合認知架構 | 8-12 週 | 💡 長期願景 |
-
----
-
-## 📊 核心問題分析
-
-### v1.0 的限制
-
-1. **仍然是文本為中心** - Agent 需要線性讀取、解析文本
-2. **結構化程度不足** - 缺乏語義關係、上下文連結
-3. **被動讀取模式** - Agent 需要主動查詢，無法「感知」變化
-4. **單一表示形式** - 無法適應不同 Agent 的認知模式
-
-### AI 認知機制深度分析
-
-#### 1. LLM Token 處理特性
-
-```
-Transformer Attention 機制：
-- Position Encoding: 前面的 token 權重更高
-- Self-Attention 複雜度: O(n²)，長序列成本高
-- Context Window 利用率: 即使 200k tokens，有效利用率 < 30%
-```
-
-**關鍵洞察**:
-- Token 不只是字符單位，更是「語義原子」
-- Token 密度 = 語義信息量 / Token 數量
-- 最優化目標：最大化語義密度
-
-#### 2. 記憶組織原理
-
-| 記憶類型 | 特性 | 適用場景 |
-|---------|------|---------|
-| 短期記憶 | 小容量、快速訪問 | 當前任務狀態 |
-| 長期記憶 | 大容量、需要檢索 | 歷史記錄、知識庫 |
-| 工作記憶 | 中等容量、正在處理 | 進行中的推理 |
-
-**關鍵洞察**:
-- 不同記憶類型需要不同的編碼策略
-- 重要性衰減（舊信息可以壓縮或遺忘）
-- 關聯記憶（相關信息應該聚集）
-
----
-
-## 🎯 五大創新方案
-
-### 方案 A: 混合式認知架構（Hybrid Cognitive Architecture）
-
-**核心理念**: 符號系統 + 向量系統雙軌並行
-
-```
-Symbolic Layer (精確查詢)     Vector Layer (語義關聯)
-        ↓                              ↓
-  [T121: status=completed]    [embedding(T121) → [0.12, -0.45, ...]]
-        ↓                              ↓
-  精確匹配: "T121 完成了嗎?"      語義搜索: "認證相關的問題"
-```
-
-**Token 效率**: 15-30:1
-**實作週期**: 8-12 週
-**技術風險**: HIGH（需要 embedding model）
-**優勢**: 支援精確查詢 + 語義關聯
-**劣勢**: 需要外部 API 或本地模型
-
----
-
-### 方案 B: 分層抽象記憶（Hierarchical Abstract Memory）⭐
-
-**核心理念**: 多層次資訊壓縮，按需加載
-
-```
-Layer 1 (Meta-Cognitive) - 10-20 tokens
-"專案進度良好，70% 任務完成，無重大阻礙"
-
-Layer 2 (Task-Level) - 30-50 tokens
-"P0: 15/15 ✓ | P1: 8/12 → | P2: 3/10 ⏸"
-
-Layer 3 (Detail-Level) - 100-200 tokens
-"T121: Fix auth bug [completed, 15 commits]
- T122: Add dashboard [completed, 3 commits]"
-
-Layer 4 (Raw Data) - 50-125 tokens (delta format)
-@delta 2026-02-07T08:00:00Z
-+task T121 completed (commits:15)
-```
-
-**智能層級切換**:
-```python
-# 簡單查詢 → Layer 1
-"專案進度如何？" → 10 tokens
-
-# 統計查詢 → Layer 2
-"有多少 P0 完成了？" → 30 tokens
-
-# 詳細查詢 → Layer 3 或 4
-"T121 做了什麼？" → 100 tokens
-```
-
-**Token 效率**: 10-20:1（單層），累計 30-70:1
-**實作週期**: 6-10 週
-**技術風險**: MEDIUM（需要 LLM API 生成摘要）
-
----
-
-### 方案 C: 差分狀態流（Delta State Stream）⭐⭐⭐
-
-**核心理念**: 只存變化，重建當前狀態（類似 Git）
-
-```matrix
-# .matrix v2.0 - Delta Stream Format
-
-## Baseline (2026-02-06T20:00:00Z)
-@baseline
-project: KenazAI
-total_tasks: 100
-completed: 85
-in_progress: 10
-blocked: 5
-
-## Delta Stream
-@delta 2026-02-06T21:00:15Z
-+task T121 completed by:dev_agent commits:15 files:8
-+task T122 completed by:frontend_agent commits:3 files:2
-+blocked T130 reason:"waiting_for_api_design"
-
-@delta 2026-02-07T05:30:42Z
--blocked T130
-+task T130 in_progress assigned:full_stack_dev
-
-@delta 2026-02-07T08:00:00Z
-+task T130 completed commits:12 files:15
-+created T135 title:"Add matrix v2.0" priority:P0
-```
-
-**狀態重建算法**:
-```python
-def rebuild_state(baseline, deltas):
-    state = baseline.copy()
-    for delta in deltas:
-        for change in delta.changes:
-            if change.op == '+':
-                state.apply_addition(change)
-            elif change.op == '-':
-                state.apply_removal(change)
-    return state
-
-# 時間複雜度: O(n) where n = delta 數量
-# 支援時間點查詢: "2026-02-06 21:00 的狀態是什麼?"
-```
-
-**Token 效率對比**:
-
-| 格式 | Token 數 | 壓縮比 |
-|------|---------|-------|
-| JSON (baseline) | ~2,500 | 1:1 |
-| .matrix v1.0 | ~250-500 | 5-10:1 |
-| .matrix v2.0 (delta) | ~50-125 | **20-50:1** ⭐ |
-
-**實作週期**: 4-6 週
-**技術風險**: LOW
-**推薦理由**: 快速見效、低風險、高價值
-
----
-
-### 方案 D: 語義圖譜（Semantic Knowledge Graph）
-
-**核心理念**: 實體-關係網絡，支援多跳推理
-
-```
-TASK_121 --completed_by--> Developer_A
-        \--depends_on--> TASK_115
-        \--fixed--> BUG_023
-        \--related_to--> FEATURE_AUTH
-
-查詢: "誰完成了認證相關的任務？"
-→ 語義遍歷圖結構: TASK_121 --related_to--> FEATURE_AUTH
-```
-
-**Token 效率**: 8-15:1（但推理能力強）
-**實作週期**: 10-14 週
-**技術風險**: HIGH（圖序列化複雜）
-
----
-
-### 方案 E: Agent 專屬視圖（Agent-Specific Views）⭐
-
-**核心理念**: 同一資訊，不同 Agent 不同表示
-
-```yaml
-# Developer Agent Profile
-cognitive_preferences:
-  focus: [code_structure, file_paths, commits]
-  ignore: [business_metrics, time_estimates]
-  format: hierarchical
-  detail_level: high
-```
-
-**同一狀態，不同視圖**:
-
-```
-Developer Agent 視圖:
-## Recent Commits (Last 24h)
-src/auth/login.py: Fix session timeout (T121, 8 commits)
-src/ui/dashboard.tsx: Add metrics panel (T122, 3 commits)
-
-PM Agent 視圖:
-## Timeline (Feb 6-7)
-2026-02-06 21:00 ✓ T121 completed (auth fix)
-2026-02-06 21:00 ✓ T122 completed (dashboard)
-
-## Priority Status
-P0: 15/15 (100%) ✓
-P1: 8/12 (67%) →
-```
-
-**Token 節省**: ~60-70% = **2.5-3x 提升**
-**實作週期**: 5-8 週
-**技術風險**: MEDIUM
-
----
-
-## 🚀 漸進式實作路線圖
-
-### 推薦路線: C → B → E → A
-
-```
-Phase 1: v2.0 Foundation (4-6 週) ⭐⭐⭐ [立即開始]
-├─ 差分狀態流（方案 C）
-├─ CLI 工具 (query, convert, validate)
-└─ Token 效率: 20-50:1
-
-Phase 2: v2.1 Enhancement (6-10 週) ⭐⭐
-├─ 分層抽象記憶（方案 B）
-├─ 自動摘要生成器
-└─ 累計 Token 效率: 30-70:1
-
-Phase 3: v2.2 Optimization (5-8 週) ⭐
-├─ Agent 專屬視圖（方案 E）
-├─ 視圖模板引擎
-└─ 多 Agent 協作優化
-
-Phase 4: v3.0 Innovation (8-12 週) 💡
-├─ 混合認知架構（方案 A）
-├─ 向量層整合
-└─ 最終 Token 效率: 50-100:1
-```
-
-**總時間**: 23-36 週（約 6-9 個月）
-
----
-
-## 💻 v2.0 實作詳細設計
-
-### 差分格式語法規範
-
-#### 操作符定義
-
-| 操作符 | 語義 | 範例 |
-|-------|------|------|
-| `+task` | 新增或更新任務 | `+task T121 completed` |
-| `-task` | 刪除任務 | `-task T999` |
-| `+blocked` | 任務被阻塞 | `+blocked T130 reason:"API_DOWN"` |
-| `-blocked` | 解除阻塞 | `-blocked T130` |
-| `+metric` | 更新指標 | `+metric velocity:15_tasks_per_day` |
-| `~update` | 部分更新 | `~update T121 assignee:new_dev` |
-
-#### 完整範例
-
-```matrix
-# .matrix v2.0 - KenazAI Project Status
-
-@meta
-version: 2.0
-type: project_status
-project: KenazAI
-created: 2026-02-06T20:00:00Z
-
-@baseline 2026-02-06T20:00:00Z
-total_tasks: 100
-completed: 85
-in_progress: 10
-blocked: 5
-team_members: 8
-avg_velocity: 12_tasks_per_day
-
-@delta 2026-02-06T21:00:15Z author:dev_agent
-+task T121 completed commits:15 files:8 duration:2h15m
-  tags:[auth, security, P0]
-  pr_url:github.com/kenaz/121
-+task T122 completed commits:3 files:2 duration:45m
-  tags:[ui, dashboard, P1]
-+blocked T130 reason:"waiting_for_api_design" blocker:backend_team
-+metric total_completed:87 in_progress:9 blocked:6
-
-@delta 2026-02-07T05:30:42Z author:backend_lead
--blocked T130 resolution:"API design approved"
-+task T130 in_progress assigned:full_stack_dev branch:feature/oauth
-+metric active_branches:3
-
-@delta 2026-02-07T08:00:00Z author:full_stack_dev
-+task T130 completed commits:12 files:15 duration:2h30m
-  tags:[auth, oauth, P0]
-  tests_added:25 coverage:92%
-+created T135 title:"Implement matrix v2.0 format" priority:P0
-  assigned:developer_team estimated:4_weeks
-+metric total_completed:88 velocity:15_tasks_per_day
-```
-
-### CLI 工具設計
-
-#### 1. matrix query
-
-```bash
-# 查詢當前狀態
-matrix query status
-
-# 查詢歷史狀態（時間點查詢）
-matrix query status --at "2026-02-06 21:00"
-
-# 查詢特定任務
-matrix query task T121
-
-# 查詢任務歷史
-matrix query task T130 --history
-
-# 自然語言查詢（v2.1+）
-matrix ask "最近完成的 P0 任務有哪些？"
-```
-
-#### 2. matrix convert
-
-```bash
-# JSON → .matrix v2.0
-matrix convert tasks.json --to delta --output tasks.matrix
-
-# .matrix v2.0 → JSON
-matrix convert tasks.matrix --to json --output tasks.json
-
-# v1.0 → v2.0
-matrix convert old.matrix --upgrade --output new.matrix
-```
-
-#### 3. matrix validate
-
-```bash
-# 驗證格式正確性
-matrix validate tasks.matrix
-
-# 檢查狀態一致性
-matrix validate tasks.matrix --check-state
-
-# 性能分析
-matrix validate tasks.matrix --analyze-performance
-```
-
-#### 4. matrix optimize
-
-```bash
-# 合併舊 delta（垃圾回收）
-matrix optimize tasks.matrix --compress-old-deltas
-
-# 重建 baseline（基於當前狀態）
-matrix optimize tasks.matrix --rebuild-baseline
-
-# 分析 Token 使用
-matrix optimize tasks.matrix --token-report
-```
-
----
-
-## 📈 效能指標與驗證
-
-### Token 效率驗證計劃
-
-| 測試場景 | JSON Token | v1.0 Token | v2.0 Token | 目標壓縮比 |
-|---------|-----------|-----------|-----------|-----------|
-| 小型專案 (50 tasks) | 1,200 | 120-240 | **24-60** | 20-50:1 ✓ |
-| 中型專案 (200 tasks) | 8,000 | 800-1,600 | **160-400** | 20-50:1 ✓ |
-| 大型專案 (1,000 tasks) | 50,000 | 5,000-10,000 | **1,000-2,500** | 20-50:1 ✓ |
-
-### 查詢速度測試
-
-| 操作 | v1.0 | v2.0 目標 |
-|------|------|----------|
-| 讀取當前狀態 | <100ms | <50ms |
-| 時間點查詢 | N/A | <100ms |
-| 全歷史重建 | N/A | <500ms |
-
----
-
-## 🛠️ 技術棧建議
-
-```yaml
-核心語言: Python 3.10+ (主要) + Node.js 18+ (工具)
-
-關鍵依賴:
-  Parser: lark-parser (Python) / chevrotain (Node.js)
-  Validation: pydantic (Python) / zod (Node.js)
-  CLI: click (Python) / commander.js (Node.js)
-
-v2.1 新增:
-  LLM API: openai / anthropic (自動摘要生成)
-
-v3.0 新增:
-  Embedding: sentence-transformers / openai embeddings
-  Vector DB: chromadb / faiss
-```
-
----
-
-## ⚠️ 風險評估
-
-| 風險 | 嚴重度 | 緩解措施 | 方案 |
-|------|-------|---------|------|
-| 狀態重建效能瓶頸 | MEDIUM | 增量快取、壓縮舊 delta | C |
-| 摘要生成品質不穩定 | MEDIUM | 多模型測試、人工校驗 | B |
-| Embedding 成本過高 | HIGH | 支援本地模型、批量處理 | A |
-| 學習曲線陡峭 | LOW | 完整文檔、VS Code 擴展 | All |
-| 遷移成本高 | MEDIUM | 自動轉換工具、兼容模式 | All |
-
----
-
-## ✅ 下一步行動
-
-### 立即行動（本週）
-
-- [x] 完成 v2.0 認知設計文檔
-- [ ] 設計差分格式語法規範（完整 EBNF）
-- [ ] 建立 GitHub repo: `matrix-format`
-- [ ] 撰寫 RFC，徵求社群意見
-
-### 短期行動（2 週內）
-
-- [ ] 實作 v2.0 Parser（Python + Node.js）
-- [ ] 建立單元測試框架（>100 測試案例）
-- [ ] 開發 `matrix convert` CLI 工具
-- [ ] 撰寫快速開始指南
-
-### 中期行動（1-3 個月）
-
-- [ ] 完成 v2.0 所有 CLI 工具
-- [ ] 開發 VS Code 擴展
-- [ ] 建立自動化生成器
-- [ ] 開始 v2.1 架構設計
-
----
-
-## 📚 參考文獻
-
-1. **Vaswani et al. (2017)** - "Attention Is All You Need" - Transformer 架構基礎
-2. **Devlin et al. (2019)** - "BERT: Pre-training of Deep Bidirectional Transformers" - Embedding 應用
-3. **Kraska et al. (2018)** - "The Case for Learned Index Structures" - 智能索引設計
-4. **GraphQL Specification** - 按需查詢設計理念
-5. **Git Internals** - 差分和版本控制機制
-
----
-
-## 📖 術語表
-
-| 術語 | 定義 |
-|------|------|
-| **Token 密度** | 語義信息量 / Token 數量 |
-| **差分流** | 只記錄變化的狀態序列（類似 Git commits） |
-| **分層抽象** | 多層次資訊壓縮結構（金字塔模型） |
-| **語義查詢** | 基於含義而非關鍵字的查詢 |
-| **Agent 專屬視圖** | 針對特定 Agent 優化的資訊表示 |
-| **混合認知架構** | 符號系統 + 向量系統結合 |
-| **認知效率** | AI 理解和處理資訊的效率（不只是 Token 數量） |
-
----
-
-**文檔版本**: 2.0.0
-**最後更新**: 2026-02-07
-**維護者**: Developer Team (full_stack_dev, integration_specialist, utility_dev, devops_engineer)
-**審查者**: code_reviewer
-**聯繫**: kenazai-dev@example.com
-
----
-
-© 2026 KenazAI Project. Licensed under MIT License.