kenaz 0.3.22 → 0.3.24

package/core/dev/design/matrix_v2_DISCUSSION_SUMMARY.md

@@ -1,414 +0,0 @@
-# .matrix v2.0 討論摘要
-> **從 AI 認知角度重新思考資訊組織**
-
-**日期**: 2026-02-07
-**參與團隊**: Developer Team (Leader + Team 模式)
-**討論模式**: Design Discussion Workflow
-**討論時長**: 約 2 小時
-**文檔狀態**: ✅ 已完成
-
----
-
-## 📋 討論概覽
-
-### 背景
-第一輪討論產出了 .matrix v1.0，達成 **5-10:1** Token 壓縮比。但團隊認識到這仍停留在「語法層面優化」（縮寫 + 符號精簡），未從 **AI 認知本質** 重新思考。
-
-### 核心問題
-> 「Token 經濟不只是字符壓縮，更是認知效率。」
-
-v1.0 的四大限制：
-1. 仍然是文本為中心（線性讀取）
-2. 結構化程度不足（缺乏語義關係）
-3. 被動讀取模式（無法感知變化）
-4. 單一表示形式（無法適應不同 Agent）
-
----
-
-## 👥 參與成員與分工
-
-| 成員 ID | 角色 | 主要貢獻 | 階段 |
-|---------|------|---------|------|
-| **full_stack_dev** | 討論協調者 | 主題識別、目標明確、最終整合 | 1, 7 |
-| **integration_specialist** | 技術分析師 | LLM 機制分析、方案設計、整合 | 2, 4 |
-| **full_stack_dev** | 實作評估者 | 5 個方案的可行性分析 | 3.1 |
-| **utility_dev** | 工具設計師 | CLI、VS Code 擴展方案 | 3.2 |
-| **devops_engineer** | 部署專家 | 維運成本、CI/CD 方案 | 3.3 |
-| **technical_writer** | 文檔撰寫者 | 設計規格、討論摘要 | 5 |
-| **code_reviewer** | 審查者 | 文檔審查、技術準確性 | 6 |
-
----
-
-## 🎯 討論成果
-
-### 產出 1: 認知模型分析報告
-
-#### LLM Token 處理機制分析
-
-**核心發現**:
-1. **Transformer Attention 特性**:
-   - Position Encoding 影響：前面的 token 有更高權重
-   - Self-Attention 複雜度：O(n²)，長序列成本高
-   - Context Window 限制：即使 200k tokens，有效利用率 < 30%
-
-2. **Token 經濟的本質**:
-   ```
-   Token 密度 = 語義信息量 / Token 數量
-   最優化目標 = 最大化語義密度（而非單純壓縮字符）
-   ```
-
-3. **業界方案對比**:
-   - Protobuf/MessagePack：二進制（不適合 LLM）
-   - GraphQL：按需查詢（減少傳輸）
-   - JSON-LD：語義化 JSON（增加關係）
-   - Vector DB：語義壓縮極致（但失去可讀性）
-
----
-
-### 產出 2: 創新方案設計（5 個）
-
-| 方案 | 核心理念 | Token 效率 | 週期 | 風險 | 優先級 |
-|------|---------|-----------|------|------|--------|
-| **A. 混合式認知架構** | 符號 + 向量雙軌 | 15-30:1 | 8-12週 | HIGH | P2 |
-| **B. 分層抽象記憶** | 多層次壓縮 | 10-20:1 | 6-10週 | MEDIUM | P1 |
-| **C. 差分狀態流** | 只存變化 | 20-50:1 | 4-6週 | LOW | **P0** ⭐ |
-| **D. 語義圖譜** | 實體-關係網絡 | 8-15:1 | 10-14週 | HIGH | P3 |
-| **E. Agent 專屬視圖** | 多視角表示 | 12-25:1 | 5-8週 | MEDIUM | P1 |
-
-#### 方案詳細分析
-
-**方案 C - 差分狀態流** (推薦立即實作):
-- **突破點**: 類似 Git 的 commit 機制，只記錄變化
-- **技術架構**: baseline + delta stream + 狀態重建算法
-- **Token 效率**: 20-50:1（時間越長越顯著）
-- **實作可行性**: ⭐⭐⭐⭐⭐ 低風險、快速見效
-- **適用場景**: 持續演進的專案
-
-**方案 B - 分層抽象記憶** (中期規劃):
-- **突破點**: 金字塔結構，按需加載
-- **技術架構**: 4 層（元認知/任務/細節/原始）+ 自動摘要
-- **Token 效率**: 累計 30-70:1
-- **實作可行性**: ⭐⭐⭐⭐ 需要 LLM API
-- **適用場景**: 大規模專案狀態管理
-
-**方案 E - Agent 專屬視圖** (中期規劃):
-- **突破點**: 同一資訊，不同 Agent 不同表示
-- **技術架構**: Agent Profile 系統 + 視圖模板引擎
-- **Token 效率**: 節省 60-70%
-- **實作可行性**: ⭐⭐⭐⭐ 需要視圖快取
-- **適用場景**: 多 Agent 協作系統
-
----
-
-### 產出 3: .matrix v2.0 概念設計
-
-#### 推薦方案：漸進式混合架構
-
-```
-v1.0（已完成）→ v2.0（差分流）→ v2.1（分層）→ v2.2（專屬視圖）→ v3.0（混合認知）
-                 ↓ 4-6 週        ↓ 6-10 週      ↓ 5-8 週         ↓ 8-12 週
-              Token: 20-50:1   累計: 30-70:1   多 Agent 優化    最終: 50-100:1
-```
-
-#### 為什麼選擇「漸進式」？
-
-| 方案類型 | 優勢 | 劣勢 |
-|---------|------|------|
-| **一次性革命** | 技術先進、效率極致 | 風險高、學習曲線陡、遷移成本大 |
-| **漸進式演進** ⭐ | 每階段都可用、風險分散、平滑過渡 | 總時間較長 |
-
-**團隊共識**: 選擇漸進式，因為：
-1. 每個階段都有可交付成果
-2. 風險分散，失敗影響小
-3. 用戶可以逐步適應
-4. 可以根據反饋調整
-
-#### v2.0 差分格式範例
-
-```matrix
-# .matrix v2.0 - Delta Stream Format
-
-@baseline 2026-02-06T20:00:00Z
-total_tasks: 100
-completed: 85
-in_progress: 10
-blocked: 5
-
-@delta 2026-02-06T21:00:15Z
-+task T121 completed commits:15 files:8
-+task T122 completed commits:3 files:2
-+blocked T130 reason:"waiting_for_api_design"
-
-@delta 2026-02-07T08:00:00Z
--blocked T130
-+task T130 completed commits:12 files:15
-```
-
-**Token 對比**:
-- JSON: ~2,500 tokens
-- v1.0: ~250-500 tokens (5-10:1)
-- v2.0: ~50-125 tokens (**20-50:1**) ⭐
-
----
-
-### 產出 4: 實驗驗證計劃
-
-#### 驗證方法
-
-| 階段 | 驗證內容 | 方法 | 目標 |
-|------|---------|------|------|
-| **設計驗證** | 語法可行性 | Parser 單元測試 | 100% 覆蓋率 |
-| **效能驗證** | Token 壓縮比 | 真實專案測試 | 20-50:1 |
-| **速度驗證** | 查詢速度 | 效能基準測試 | <50ms |
-| **質量驗證** | 狀態一致性 | 屬性測試 | 99.9% 正確率 |
-
-#### 實驗設計
-
-**實驗 1: Token 效率測試**
-```yaml
-測試場景:
-  - 小型專案: 50 tasks
-  - 中型專案: 200 tasks
-  - 大型專案: 1,000 tasks
-
-測試方法:
-  1. 準備 JSON baseline
-  2. 轉換為 v1.0 和 v2.0
-  3. 計算 Token 數量（使用 tiktoken）
-  4. 對比壓縮比
-
-預期結果: v2.0 達成 20-50:1
-```
-
-**實驗 2: 查詢速度測試**
-```python
-# 測試代碼範例
-def benchmark_query_speed():
-    tasks = load_matrix_v2("large_project.matrix")
-
-    # Test 1: 當前狀態查詢
-    t1 = time_query(tasks.current_state)
-    assert t1 < 50  # < 50ms
-
-    # Test 2: 歷史狀態查詢
-    t2 = time_query(tasks.state_at("2026-02-06 21:00"))
-    assert t2 < 100  # < 100ms
-
-    # Test 3: 全歷史重建
-    t3 = time_rebuild(tasks)
-    assert t3 < 500  # < 500ms
-```
-
-**實驗 3: 實際專案驗證**
-```
-使用 KenazAI 專案作為測試床:
-- 當前 135 個任務
-- 8 個 Agent
-- 4 個月歷史
-
-驗證項目:
-1. 轉換正確性（JSON → v2.0）
-2. Token 節省百分比
-3. 查詢速度
-4. Agent 使用體驗
-```
-
-#### 評估指標
-
-| 類別 | 指標 | 目標值 | 測試方法 |
-|------|------|-------|---------|
-| **效率** | Token 壓縮比 | 20-50:1 | tiktoken 計數 |
-| **速度** | 當前狀態查詢 | <50ms | 效能基準測試 |
-| **速度** | 歷史狀態查詢 | <100ms | 效能基準測試 |
-| **質量** | 格式正確率 | >99.5% | 單元測試 |
-| **質量** | 狀態一致性 | >99.9% | 屬性測試 |
-| **體驗** | 學習時間 | <30分鐘 | 用戶測試 |
-
----
-
-## 💡 主要觀點與決策
-
-### 觀點 1: 語義密度 > 字符壓縮
-
-**提出者**: integration_specialist
-**核心論點**:
-> Token 不只是字符單位，更是「語義原子」。我們應該優化「語義密度」而非單純壓縮字符。
-
-**團隊反應**: ✅ 全員支持
-**影響**: 改變設計思路，從「縮寫」轉向「差分 + 分層」
-
----
-
-### 觀點 2: 工具生態至關重要
-
-**提出者**: utility_dev
-**核心論點**:
-> 再好的格式，沒有工具支援也無法普及。CLI、VS Code 擴展、自動化生成器是成功的關鍵。
-
-**團隊反應**: ✅ 全員支持
-**決策**: 將工具開發列為 P0 優先級
-**產出**: 4 類工具方案（CLI、擴展、生成器、監控）
-
----
-
-### 觀點 3: Embedding 的價值 vs 成本
-
-**提出者**: full_stack_dev vs devops_engineer
-**爭論點**:
-- full_stack_dev: 語義查詢能力強，值得投資
-- devops_engineer: 外部 API 依賴高，成本難預測
-
-**決策**: 將 embedding 方案（v3.0）延後，先驗證 v2.0-v2.2 效果
-**共識**: 如果 v2.0-v2.2 效果已經很好，可能不需要 v3.0
-
----
-
-### 觀點 4: 漸進式 vs 革命性
-
-**提出者**: integration_specialist
-**核心論點**:
-> 漸進式演進比一次性革命更實際。每個階段都可用，風險分散。
-
-**團隊反應**: ✅ 全員支持
-**決策**: 採用 4 階段路線圖（v2.0 → v2.1 → v2.2 → v3.0）
-
----
-
-## ⚡ 關鍵決策記錄
-
-| 決策 ID | 決策內容 | 理由 | 投票 |
-|---------|---------|------|------|
-| **DEC-001** | 立即開始 v2.0（差分流） | 低風險、快速見效、高價值 | 5:0 |
-| **DEC-002** | 工具開發列為 P0 優先級 | 工具生態是成功關鍵 | 5:0 |
-| **DEC-003** | v3.0（embedding）延後 | 先驗證 v2.0-v2.2 效果 | 4:1 |
-| **DEC-004** | 採用漸進式路線圖 | 風險分散、平滑過渡 | 5:0 |
-| **DEC-005** | 支援本地模型（v3.0） | 降低外部依賴和成本 | 5:0 |
-
----
-
-## 🔄 待解決問題
-
-### 問題 1: 自動摘要的品質穩定性
-
-**描述**: v2.1 需要 LLM API 自動生成摘要，品質可能不穩定
-**提出者**: full_stack_dev
-**建議解決方案**:
-- 多模型測試（Claude、GPT-4、Gemini）
-- 人工校驗機制（前 100 次）
-- Prompt 工程優化
-
-**狀態**: ⏳ 待 v2.1 階段驗證
-
----
-
-### 問題 2: 向量查詢的準確率
-
-**描述**: v3.0 語義查詢可能不如精確查詢準確
-**提出者**: integration_specialist
-**建議解決方案**:
-- 混合查詢（符號層 + 向量層）
-- 符號層保底（確保基本查詢正確）
-- 用戶反饋機制（改進 embedding）
-
-**狀態**: ⏳ 待 v3.0 階段驗證
-
----
-
-### 問題 3: 遷移成本
-
-**描述**: 用戶從 v1.0 遷移到 v2.0 可能有成本
-**提出者**: devops_engineer
-**建議解決方案**:
-- 自動轉換工具（`matrix convert --upgrade`）
-- 兼容模式（v2.0 支援讀取 v1.0）
-- 漸進式遷移指南
-
-**狀態**: ✅ 已納入實作計劃
-
----
-
-## 📊 共識與分歧
-
-### 共識點 ✅
-
-1. ✅ **Token 經濟的核心是語義密度**（全員同意）
-2. ✅ **需要突破純文本範式**（全員同意）
-3. ✅ **分層和混合方案比單一方案更實用**（全員同意）
-4. ✅ **工具生態至關重要**（全員同意）
-5. ✅ **實作應該漸進式**（全員同意）
-
-### 分歧點 ⚠️
-
-1. ⚠️ **Embedding 方案的價值 vs 成本**
-   - 支持方: full_stack_dev（語義查詢能力強）
-   - 謹慎方: devops_engineer（外部依賴、成本）
-   - 決議: 延後到 v3.0，先驗證 v2.0-v2.2
-
-2. ⚠️ **實作優先級（工具 vs 格式）**
-   - 工具優先: utility_dev（工具決定成功）
-   - 格式優先: integration_specialist（格式是基礎）
-   - 決議: 並行開發（Week 1-2 格式，Week 3-6 工具）
-
-3. ⚠️ **圖結構的必要性**
-   - 支持方: integration_specialist（關係推理很重要）
-   - 質疑方: full_stack_dev（複雜度太高）
-   - 決議: 降為 P3，研究階段
-
----
-
-## 🎯 下一步行動
-
-### 立即行動（本週）
-
-- [x] 完成設計規格文檔
-- [x] 完成討論摘要
-- [ ] 設計差分格式語法規範（完整 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. ✅ **設計規格文檔**: `matrix_v2_COGNITIVE_DESIGN.md` (13.7 KB)
-2. ✅ **討論摘要**: `matrix_v2_DISCUSSION_SUMMARY.md` (本文檔)
-3. ⏳ **RFC 文檔**: `matrix_v2_RFC.md` (待撰寫)
-4. ⏳ **快速開始指南**: `matrix_v2_QUICKSTART.md` (待撰寫)
-5. ⏳ **範例文件**: `matrix_v2_EXAMPLES/` (待建立)
-
----
-
-## 🙏 致謝
-
-感謝所有參與討論的團隊成員：
-- **full_stack_dev** - 討論協調與實作評估
-- **integration_specialist** - 技術分析與方案整合
-- **utility_dev** - 工具方案設計
-- **devops_engineer** - 部署維運分析
-- **technical_writer** - 文檔撰寫
-- **code_reviewer** - 技術審查
-
----
-
-**文檔版本**: 1.0.0
-**最後更新**: 2026-02-07
-**維護者**: Developer Team
-**下次討論**: 2 週後（v2.0 實作進度檢視）
-
----
-
-© 2026 KenazAI Project. This discussion summary is part of the matrix v2.0 design documentation.

package/core/dev/design/matrix_v2_EXAMPLE.matrix

@@ -1,67 +0,0 @@
-# .matrix v2.0 - Delta Stream Format Example
-# KenazAI Project Status (Feb 6-7, 2026)
-
-@meta
-version: 2.0
-type: project_status
-project: KenazAI
-created: 2026-02-06T20:00:00Z
-last_updated: 2026-02-07T08:00:00Z
-
-@baseline 2026-02-06T20:00:00Z
-total_tasks: 100
-completed: 85
-in_progress: 10
-blocked: 5
-team_members: 8
-active_agents: [dev_agent, frontend_agent, backend_agent, pm_agent]
-avg_velocity: 12_tasks_per_day
-tech_stack: [Python, TypeScript, React, FastAPI, Supabase]
-
-@delta 2026-02-06T21:00:15Z author:dev_agent
-+task T121 completed commits:15 files:8 duration:2h15m
-  title:"Fix authentication session timeout bug"
-  tags:[auth, security, P0, bug_fix]
-  pr_url:github.com/kenazai/kenaz/pull/121
-  tests_added:12 coverage:95%
-+task T122 completed commits:3 files:2 duration:45m
-  title:"Add metrics dashboard panel"
-  tags:[ui, dashboard, P1, feature]
-  pr_url:github.com/kenazai/kenaz/pull/122
-+blocked T130 reason:"waiting_for_api_design_approval" blocker:backend_team
-  title:"Implement OAuth 2.0 support"
-+metric total_completed:87 in_progress:9 blocked:6 velocity:14_tasks_per_day
-
-@delta 2026-02-06T23:30:00Z author:backend_lead
-+comment T130 message:"API design approved, ready to implement"
--blocked T130 resolution:"API design approved, OAuth specs finalized"
-
-@delta 2026-02-07T05:30:42Z author:full_stack_dev
-+task T130 in_progress assigned:full_stack_dev branch:feature/oauth-integration
-  started:2026-02-07T05:30:42Z
-+metric active_branches:3 in_progress:10 blocked:5
-
-@delta 2026-02-07T08:00:00Z author:full_stack_dev
-+task T130 completed commits:12 files:15 duration:2h30m
-  title:"Implement OAuth 2.0 support"
-  tags:[auth, oauth, P0, feature]
-  pr_url:github.com/kenazai/kenaz/pull/130
-  tests_added:25 coverage:92%
-  breaking_changes:false
-  migration_required:false
-+created T135 title:"Implement matrix v2.0 format" priority:P0
-  assigned:developer_team estimated:4_weeks tags:[infrastructure, format]
-  description:"Design and implement v2.0 delta stream format with 20-50:1 token efficiency"
-+metric total_completed:88 in_progress:10 blocked:5 velocity:15_tasks_per_day
-  total_commits:30 total_files_changed:25 total_tests:37
-
-# Query Examples:
-# 1. Current state: parse all deltas from baseline
-# 2. State at 2026-02-06 21:00: baseline + first delta
-# 3. Task T130 history: filter deltas mentioning T130
-# 4. Velocity trend: extract velocity metrics from deltas
-
-# Token Analysis:
-# This file: ~125 tokens (estimated)
-# Equivalent JSON: ~2,500 tokens
-# Compression ratio: 20:1 ✓