From badee8738e794b57be0cc8018388329f8b7e4e7a Mon Sep 17 00:00:00 2001 From: Developer Date: Wed, 8 Apr 2026 16:59:13 +0800 Subject: [PATCH] docs: add OpenCode v1.2.x vs v1.4.0 plugin interface research MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add opencode-plugin-interface-research.md with version comparison - Update OPENCODE_COMPATIBILITY.md with v1.4.0 breaking changes - Add Phase 7 to roadmap.md with risk assessment and phased upgrade strategy - Add BL-056 to BL-060 to backlog.md (Epic 12 - version compatibility) Risk assessment: - 🔴 High: AI SDK v5→v6 migration (v1.3.4) affects session.idle hook - 🟡 Medium: Tool.define() bug fix (v1.3.14) affects 17 tools - 🟡 Medium: Plugin install mechanism (v1.3.11) - 🟢 Low: v1.4.0 new features unrelated Upgrade path: 1.2.25 → 1.3.14 → (1-2 weeks observation) → 1.4.x --- docs/OPENCODE_COMPATIBILITY.md | 65 ++- docs/backlog.md | 51 +++ docs/long-term-memory-landscape.md | 460 +++++++++++++++++++++ docs/opencode-plugin-interface-research.md | 347 ++++++++++++++++ docs/roadmap.md | 131 +++++- 5 files changed, 1036 insertions(+), 18 deletions(-) create mode 100644 docs/long-term-memory-landscape.md create mode 100644 docs/opencode-plugin-interface-research.md diff --git a/docs/OPENCODE_COMPATIBILITY.md b/docs/OPENCODE_COMPATIBILITY.md index 6c4a51c..cc28c31 100644 --- a/docs/OPENCODE_COMPATIBILITY.md +++ b/docs/OPENCODE_COMPATIBILITY.md @@ -1,8 +1,29 @@ # OpenCode Compatibility & Troubleshooting Guide -**Last Updated**: April 3, 2026 +**Last Updated**: April 8, 2026 **Status**: Active -**Scope**: OpenCode version compatibility, plugin loading, NAPI native addon issues +**Scope**: OpenCode version compatibility, plugin interface changes, NAPI native addon issues + +--- + +## 📋 Version Compatibility Matrix + +| OpenCode Version | Status | LanceDB Native | SDK Breaking Changes | Notes | +|------------------|--------|-----------------|---------------------|-------| +| **v1.2.0 - v1.3.7** | ✅ **Stable** | ✅ Working | None | **Recommended** | +| **v1.3.8 - v1.3.13** | ❌ **Broken** | ❌ Broken | N/A | Known bug (Issue #20623) | +| **v1.4.0+** | ⚠️ **TBD** | ⏳ Unknown | **Breaking** | Diff metadata + UserMessage changes | + +### v1.4.0+ Breaking SDK Changes + +If you upgrade to v1.4.0+, be aware of these breaking changes: + +| Change | Before (v1.2.x-v1.3.7) | After (v1.4.0+) | +|--------|------------------------|-----------------| +| **Diff metadata** | `{to, from, patch}` | `{patch}` only | +| **UserMessage.variant** | Top-level field | `msg.model.variant` | + +**Impact**: Minimal direct impact on lancedb-opencode-pro currently, but future features should use new API. --- @@ -17,15 +38,9 @@ Memory store unavailable (ollama embedding may be offline). Will retry automatic And embedding is confirmed working but memory tools persistently fail, **you likely have a native NAPI addon loading issue with OpenCode v1.3.8+**. ---- +### Status Update (April 8, 2026) -## 📋 Affected Versions & Status - -| OpenCode Version | Status | LanceDB Native Support | Notes | -|------------------|--------|----------------------|-------| -| **v1.3.7 and earlier** | ✅ **Stable** | ✅ **Working** | Recommended | -| **v1.3.8 - v1.3.13** | ❌ **Broken** | ❌ **Broken** | Known bug (Issue #20623) | -| **v1.4.0+** | ⏳ **Unknown** | ⏳ **TBD** | Monitor releases | +The NAPI bug in v1.3.8+ may or may not be fixed in v1.4.0+. We are monitoring the situation and will update this document when confirmed. ### Root Cause (Issue #20623) @@ -220,6 +235,30 @@ console.log('SUCCESS: Store initialized'); --- +## 📚 Plugin Interface Research + +See [opencode-plugin-interface-research.md](./opencode-plugin-interface-research.md) for detailed analysis of: + +- Breaking SDK changes between v1.2.x and v1.4.0 +- Diff metadata structure changes +- UserMessage.variant nesting changes +- Hook API compatibility +- Real-world plugin implementation patterns +- Migration path recommendations + +### Quick Reference: Hook Stability + +| Hook | Stability | Used by Plugin | +|------|-----------|----------------| +| `config` | ✅ Stable | ✅ Yes | +| `event` | ✅ Stable | ✅ Yes | +| `tool` | ✅ Stable | ✅ Yes | +| `experimental.text.complete` | ⚠️ Undocumented | ✅ Yes | +| `experimental.chat.system.transform` | ⚠️ Community-only | ✅ Yes | +| `session.created`, `session.idle`, `session.end` | ✅ Stable | ✅ Yes (via event hook) | + +--- + ## 📞 Support & Escalation ### If Downgrade Works @@ -293,6 +332,6 @@ Include: --- -**Last Verified**: April 3, 2026 -**Tested On**: OpenCode v1.3.13, lancedb-opencode-pro v0.6.0 -**Status**: Active Issue +**Last Verified**: April 8, 2026 +**Tested On**: OpenCode v1.3.13, lancedb-opencode-pro v0.6.3 +**Status**: Active Issue (v1.3.8+ NAPI), Unknown (v1.4.0+ SDK changes) diff --git a/docs/backlog.md b/docs/backlog.md index f26f931..1268178 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -115,6 +115,48 @@ | BL-046 | DB row runtime 型別驗證 | P1 | **done** | episodic-record-validation | `openspec/changes/episodic-record-validation/` | 降低 `as unknown as EpisodicTaskRecord` 風險；讀取後做 schema validation [Surface: Plugin + Test-infra] | | BL-047 | Embedding fallback 與搜尋模式可觀測性補強 | P2 | planned | TBD | TBD | `memory_stats` 新增 `searchMode: "in-memory-cosine" | "native-ivf"` 揭露當前向量搜尋模式；embedding fallback 保留降級語義並補 structured warning + metrics [Surface: Plugin + Docs] | +## Epic 11 — 記憶架構演進（研究驅動） + +> 技術研究依據：`docs/long-term-memory-landscape.md` +> 所有項目均在 LanceDB 之上實現，不引入新儲存後端。 + +| BL-ID | Title | Priority | Status | OpenSpec Change ID | Spec Path | Notes | +|---|---|---|---|---|---|---| +| BL-052 | 多策略檢索增強（entity-based + temporal filtering） | P2 | planned | TBD | TBD | 在 vector + BM25 基礎上增加 entity 索引與時間過濾；參考 Hindsight 四策略架構 [Surface: Plugin] | +| BL-053 | 記憶摘要壓縮 | P2 | planned | TBD | TBD | 長期未使用記憶自動摘要；相似記憶合併為知識筆記；參考 HiMem Episode→Note 模式 [Surface: Plugin] | +| BL-054 | 輕量級實體關係索引 | P2 | planned | TBD | TBD | 為 memory records 增加 entity-relationship metadata；支援關係查詢；以 LanceDB metadata 欄位實現 [Surface: Plugin] | +| BL-055 | 時態知識追蹤（bi-temporal fact management） | P2 | planned | TBD | TBD | 參考 Graphiti bi-temporal 模型；增加 `validFrom`/`supersededAt`；事實失效而非刪除 [Surface: Plugin] | + +## Epic 12 — OpenCode 版本相容性與遷移 + +> 技術研究依據：`docs/opencode-plugin-interface-research.md` +> 目標：確保插件在 OpenCode 各版本間的相容性，並建立版本遷移策略。 + +### 風險評估摘要（2026-04-08） + +| 風險等級 | 項目 | 說明 | +|---------|------|------| +| 🔴 高 | AI SDK v5 → v6 遷移 | v1.3.4 引入，可能影響 session.idle / tool hooks | +| 🟡 中 | Tool.define() bug 修復 | v1.3.14，可能改變 17 個 tools 的 execute 行為 | +| 🟡 中 | Plugin 安裝機制改變 | v1.3.11，需確認 prepublishOnly 正常運作 | +| 🟢 低 | v1.4.0 本身 | 新功能對本 plugin 無關，但今日發布未驗證 | + +### 升級策略 + +``` +1.2.25 → 1.3.14 → (觀察 1-2 週) → 1.4.x（穩定後） +``` + +### Backlog 項目 + +| BL-ID | Title | Priority | Status | OpenSpec Change ID | Spec Path | Notes | +|---|---|---|---|---|---|---| +| BL-056 | OpenCode v1.4.0+ 相容性驗證 | P1 | proposed | TBD | TBD | 確認 v1.4.0+ NAPI 載入狀態；驗證 SDK breaking changes 影響；更新相容性文件 [Surface: Plugin + Docs] | +| BL-057 | SDK 升級測試矩陣 | P2 | planned | TBD | TBD | 建立 v1.2.x / v1.3.7 / v1.4.0+ 自動化測試矩陣；確保跨版本相容性 [Surface: Test-infra] | +| BL-058 | 執行時期版本偵測機制 | P2 | planned | TBD | TBD | 在插件初始化時偵測 OpenCode 版本；提供版本特定錯誤訊息改善 [Surface: Plugin] | +| BL-059 | SDK 升級到 1.3.14 測試驗證 | P1 | proposed | TBD | TBD | 先升級到 1.3.14 跨越 AI SDK v6 遷移；執行 verify:full 驗證；重點測試 session.idle 觸發與 tool execute 行為 [Surface: Plugin] | +| BL-060 | OpenCode v1.3.14 相容性確認 | P1 | proposed | TBD | TBD | 確認 v1.3.14 版本下所有 hooks 正常運作；更新版本狀態文件 [Surface: Plugin + Docs] | + --- ## 建議執行切片（索引版） @@ -136,6 +178,15 @@ BL-036, BL-037, BL-048, BL-049, BL-050 ### Release E（架構可維護性與效能硬化）— 📝 PLANNED BL-041, BL-043, BL-044, BL-045, BL-046, BL-047 +### Release F（記憶架構演進）— 🔬 RESEARCH +BL-052, BL-053, BL-054, BL-055 +> 研究依據：`docs/long-term-memory-landscape.md` + +### Release G（OpenCode 版本相容性）— 🔬 RESEARCH +BL-056, BL-057, BL-058, BL-059, BL-060 +> 研究依據：`docs/opencode-plugin-interface-research.md` +> 升級策略：1.2.25 → 1.3.14 → (觀察) → 1.4.x + --- ## 維護規則 diff --git a/docs/long-term-memory-landscape.md b/docs/long-term-memory-landscape.md new file mode 100644 index 0000000..b5846cf --- /dev/null +++ b/docs/long-term-memory-landscape.md @@ -0,0 +1,460 @@ +# AI 長期記憶技術方案全景研究 + +> **研究日期**：2026-04-08 +> **研究範圍**：向量資料庫以外的 AI agent 長期記憶技術方案 +> **目的**：作為本專案記憶架構演進的技術參考依據 + +--- + +## 摘要 + +本專案目前以 LanceDB（向量 + BM25 混合檢索）作為記憶儲存引擎。本文研究 2024–2026 年間向量資料庫以外的長期記憶技術方案，為後續架構演進提供決策依據。 + +**核心發現**：純向量相似度搜尋已被業界普遍認為不足以支撐完整的 agent 記憶需求。2026 年的共識是 **混合架構**（vector + graph + structured + temporal）優於任何單一方案。 + +--- + +## 1. 技術方案總覽 + +| 類別 | 核心思路 | 代表專案 | 成熟度 | 與本專案關聯性 | +|------|---------|---------|--------|--------------| +| Graph-based Memory | 知識圖譜 + 關係推理 | Neo4j Agent Memory, Graphiti, LightRAG | Production-ready | **高** — 補足關係推理與時間推理 | +| 層級式記憶 (Tiered) | 模仿 OS 記憶體管理 | Letta (MemGPT), MemoryOS, HiMem | Production-ready | **中** — 本專案已有 scope 分層基礎 | +| Memory-Augmented Transformers | 注意力層內嵌壓縮記憶 | Infini-attention, Titans, M+ | Research stage | **低** — 需模型架構修改，非 plugin 層可做 | +| 參數化記憶 (Parametric) | Fine-tuning / LoRA 當記憶載體 | LoRA-as-Knowledge, Safe LoRA | Research stage | **低** — 非本專案責任範圍 | +| 反思型記憶 (Reflective) | Agent 從錯誤中學習 | Experiential Reflective Learning, MAR | Research stage | **中** — 可強化現有 episodic learning | +| 多模態記憶 | 跨模態記憶存取 | MemVerse, Omni-SimpleMem | Early research | **低** — 本專案以文字為主 | +| 混合式生產平台 | 多後端融合 | Mem0, Zep/Graphiti, Hindsight | Production-ready | **高** — 可參考架構設計 | + +--- + +## 2. Graph-based Memory（圖結構記憶） + +### 2.1 核心價值 + +向量搜尋回答「語義上最相近的是什麼」，圖結構回答： +- 「誰和誰有什麼關係」（實體關係推理） +- 「事情是怎麼因果發展的」（因果推理） +- 「上季度負責人是誰」（時間推理） + +### 2.2 三個主要分支 + +#### a) Knowledge Graph as Memory + +**代表**：Neo4j Agent Memory（[github.com/neo4j-labs/agent-memory](https://github.com/neo4j-labs/agent-memory)） + +三種記憶類型： +- **Short-term Memory**：對話歷史，以 message nodes + temporal metadata 存儲 +- **Reasoning Memory**：決策軌跡，記錄 tool usage 與 provenance +- **Long-term Memory**：實體知識圖譜，以 nodes（entities）+ edges（relationships）構成 + +特點： +- Neo4j 原生支援 vector index + property graph（不需額外向量 DB） +- Cypher 查詢語言支援複雜圖遍歷 +- 已整合 LangChain, OpenAI Agents, CrewAI, Pydantic AI + +#### b) GraphRAG（文件級圖結構檢索） + +| 系統 | 索引成本 (500頁) | 索引時間 | 優勢 | GitHub Stars | +|------|-----------------|---------|------|-------------| +| Microsoft GraphRAG | $50-200 | ~45 min | 全局分析型查詢（+26% 完整性, +57% 多樣性） | ~14K | +| LightRAG | ~$0.50 | ~3 min | 成本敏感場景，簡化圖結構 | ~32K | + +**Microsoft GraphRAG** 架構： +1. LLM 提取實體與關係 +2. Leiden 演算法將相關實體分群為階層社群 +3. 預生成多層社群摘要 +4. 查詢路由：local → 實體鄰域；global → 社群摘要 + +#### c) Temporal Knowledge Graph + +**代表**：Zep / Graphiti（[github.com/getzep/graphiti](https://github.com/getzep/graphiti)） + +核心創新 — **雙時態模型 (Bi-temporal)**： +- 每個事實記錄 `t_valid`（何時為真）和 `t_invalid`（何時被取代） +- 事實被「失效」而非「刪除」→ 支援完整時間旅行查詢 +- 三層架構：Episode Subgraph → Semantic Entity Subgraph → Community Subgraph + +**Benchmark**: LongMemEval 63.8%，時間推理比 baseline 提升 18.5% + +### 2.3 Vector vs. Graph 決策框架 + +| 場景 | 推薦方案 | +|------|---------| +| 簡單事實查找（語義匹配即可） | Vector-only | +| 多跳推理（A→B→C 關係鏈） | Graph | +| 時間推理（事實演變追蹤） | Temporal Graph | +| 全局分析（主題歸納、趨勢） | GraphRAG | +| 兼需語義搜尋與關係推理 | Hybrid（vector + graph）| + +### 2.4 與本專案的關聯 + +本專案目前的記憶模型是 **flat records + vector + BM25**，缺乏： +- 實體間關係的顯式建模（偏好之間的因果關係、決策依賴鏈） +- 事實時效性管理（哪些事實已過期、被新事實取代） +- 多跳檢索能力（「哪個專案的哪個決策影響了這次的偏好」） + +**潛在整合路徑**： +- 在 LanceDB 之上建立輕量級 entity-relationship 索引 +- 為 memory records 增加 relationship edges metadata +- 參考 Graphiti 的 bi-temporal 模式改進現有 freshness/decay 機制 + +--- + +## 3. 層級式記憶 (Tiered Memory) + +### 3.1 四層記憶架構 + +業界 2026 年的標準模式： + +| 層級 | 類比 | 容量 | 延遲 | 生命週期 | 內容 | +|------|------|------|------|---------|------| +| Working Memory | CPU Cache | 128K-2M tokens | 0ms | 單次請求 | 當前對話、system prompt | +| Short-term / Episodic | RAM | ~1000 筆互動 | <100ms | 數天 | 近期對話、活躍實體 | +| Long-term / Semantic | SSD | 無限 | 100-500ms | 數月-年 | 事實、偏好、學習知識 | +| Archival | Cold Storage | 無限（壓縮）| 秒級 | 永久 | 歷史記錄、舊 session | + +### 3.2 代表專案 + +#### Letta (MemGPT) + +OS-style 記憶管理： +- **Core Memory**（RAM）：永遠在 context window 內 +- **Recall Memory**（Disk Cache）：可搜尋的對話歷史 +- **Archival Memory**（Tape）：長期存儲，agent 主動查詢 + +關鍵創新：**Agent 主動管理自己的記憶** — 決定什麼留在 context、什麼歸檔。 + +#### MemoryOS + +基於「熱度」的層級遷移： +``` +heat = recency × frequency × importance +``` +- 熱度高 → 升級到更快層級 +- 熱度低 → 降級到更慢層級 +- 搭配 Ebbinghaus 遺忘曲線模型 + +#### HiMem（階層式長期記憶） + +arXiv: [2601.06377](https://arxiv.org/abs/2601.06377) + +雙層記憶 + 自我演化： +- **Episode Memory**（細粒度）：雙通道事件分割（主題感知 + 事件驚奇度） +- **Note Memory**（抽象知識）：事實 / 偏好 / 用戶特徵 +- **記憶自我演化**：當 Note 不足以回答 → 回退到 Episode → 提取新知識 → 分類更新（擴展 / 修正 / 保持不變） + +**Benchmark**: LoCoMo Overall 80.71%（最佳 baseline 為 69.03） + +### 3.3 與本專案的關聯 + +本專案已有層級基礎： +- `project` / `global` scope 分離 +- episodic task records vs. semantic memories +- effectiveness events 有 TTL/archival + +可改進方向： +- 記憶壓縮/摘要：長期未使用的記憶自動摘要壓縮 +- 熱度遷移：參考 MemoryOS 的 heat-based 升降級機制 +- 自我演化：參考 HiMem 的記憶自動修正模式 + +--- + +## 4. 前沿混合架構 + +### 4.1 MAGMA（多圖代理記憶） + +arXiv: [2601.03236](https://arxiv.org/abs/2601.03236) + +將記憶解耦為四種正交圖： + +| 圖類型 | 邊定義 | 回答問題 | +|--------|--------|---------| +| Temporal Graph | 時間順序 | 「X 何時發生？」 | +| Causal Graph | 邏輯蘊含 | 「X 為何發生？」 | +| Semantic Graph | 餘弦相似度 | 「什麼與 X 相似？」 | +| Entity Graph | 實體連結 | 「誰參與了？」 | + +關鍵創新：根據查詢意圖動態加權不同圖的邊。 + +**Benchmark**: Overall 0.700 vs. 最佳 baseline 0.580 + +### 4.2 Kumiho（形式化認知記憶） + +arXiv: [2603.17244](https://arxiv.org/abs/2603.17244) + +三大架構創新： +1. **AGM 信念修正語義**：嚴格遵循形式邏輯公理進行記憶更新 +2. **前瞻性索引 (Prospective Indexing)**：寫入時 LLM 產生假設未來情境，橋接 cue-trigger 語義鴻溝 +3. **Item ↔ Revision 模型**：不可變修訂版本 + 可變標籤指標 + +**Benchmark**: LoCoMo-Plus 93.3% vs Gemini 2.5 Pro 45.7% + +### 4.3 HyMem（動態雙層檢索） + +arXiv: [2602.13933](https://arxiv.org/abs/2602.13933) + +- Summary-Level（永遠啟用）+ Raw-Level（僅複雜查詢啟用） +- LLM 評估查詢複雜度，決定是否啟用第二層 +- 達成 **92.6% 計算成本降低**，性能持平 full-context + +--- + +## 5. Memory-Augmented Transformers + +在模型架構層面直接解決記憶問題（非外部存儲）。 + +### 5.1 Infini-attention（Google, 2024） + +arXiv: [2404.07143](https://arxiv.org/abs/2404.07143) + +- 標準注意力層 + 壓縮長期 linear attention +- 達成 1M token passkey retrieval，O(1) 記憶複雜度 +- 核心洞察：無限上下文不需要無限記憶 + +### 5.2 Titans（Google Research, 2025） + +- 在推理時學習記憶（test-time memorization） +- 結合注意力與可學習記憶模組 + +### 5.3 M+（IBM/MIT, ICML 2025） + +- 潛空間記憶表示 (latent-space memory) +- 可與凍結 LLM 配合，無需 fine-tuning + +### 5.4 與本專案的關聯 + +**低關聯性**。此類方案需要修改模型架構本身，非 plugin 層面可實現。但其思想（壓縮記憶、動態記憶管理）可借鑑到 plugin 層的記憶壓縮策略。 + +--- + +## 6. 參數化記憶 (Parametric Memory) + +### 6.1 LoRA as Knowledge Memory + +arXiv: [2603.01097](https://arxiv.org/abs/2603.01097) + +將 LoRA adapter 視為壓縮的事實記憶： +- 推理時零額外延遲 +- 知識深度整合到模型 + +**關鍵發現**（MIT CSAIL）：LoRA 與 Full fine-tuning 產生**質性不同**的知識表示。 + +| 優勢 | 劣勢 | +|------|------| +| 推理時零延遲 | 訓練成本高 | +| 深度整合 | 難以選擇性遺忘 | +| 無需外部檢索 | 更新需重新訓練 | + +### 6.2 與本專案的關聯 + +**低關聯性**。非本專案責任範圍（模型訓練屬上游）。但「知識可能互相矛盾」的發現值得參考——本專案的 conflict detection 機制需要持續強化。 + +--- + +## 7. 反思型記憶 (Reflective Memory) + +### 7.1 Experiential Reflective Learning（ICLR 2026 Workshop） + +arXiv: [2603.24639](https://arxiv.org/abs/2603.24639) + +Agent 從自身經驗中學習： +1. **Experience Encoding**：記錄互動 +2. **Reflection Generation**：LLM 分析失敗原因 +3. **Memory Update**：將教訓鞏固為可操作知識 + +### 7.2 MAR: Multi-Agent Reflexion（2025） + +arXiv: [2512.20845](https://arxiv.org/abs/2512.20845) + +- 多個 agent 從不同角度反思同一問題 +- 交叉反思識別盲點 + +### 7.3 與本專案的關聯 + +**中等關聯性**。本專案已有 episodic learning（BL-014–018）和 retry/recovery（BL-019–022）。反思型記憶可強化： +- 從失敗 episode 自動提取「教訓」 +- 將 retry 成功模式鞏固為 reusable playbook +- 跨任務的模式泛化（不只是「相似任務回憶」，而是「為什麼這次成功了」） + +--- + +## 8. 混合式生產平台比較 + +### 8.1 主要平台 + +| 平台 | 架構 | Benchmark | 延遲 (p50) | 特色 | GitHub Stars | +|------|------|-----------|-----------|------|-------------| +| **Mem0** | Vector + Graph | LOCOMO 66.9% | 0.20s | 90% token 節省，開源 | ~48K | +| **Hindsight** | 4 策略並行 + cross-encoder rerank | LongMemEval 91.4% | — | 最高 retrieval 準確率 | ~4K | +| **Zep/Graphiti** | Temporal KG | LongMemEval 63.8% | — | 最強時間推理 | ~24K | +| **Letta** | OS-style tiered | — | — | Agent 自主管理記憶 | ~21K | +| **Cognee** | KG + Vector | — | — | 認知記憶結構 | ~12K | +| **LangMem** | Flat KV + vector | — | — | LangGraph 整合 | ~1.3K | + +### 8.2 Hindsight 的四策略檢索 + +特別值得參考的架構： +1. **Semantic search**（embeddings） +2. **BM25 keyword matching** +3. **Entity graph traversal** +4. **Temporal filtering** + +結果以 cross-encoder reranking 融合。本專案目前已有策略 1 和 2，策略 3 和 4 是潛在的增強方向。 + +### 8.3 Mem0 架構 + +提取管線： +1. LLM 從最新交換 + rolling summary + 近期訊息中提取候選記憶 +2. 相似度比對決定操作：ADD / UPDATE / DELETE / NOOP +3. Mem0g（圖版本）：Entity Extractor + Relations Generator + Conflict Detector + +**ECAI Accepted 論文** (arXiv: [2504.19413](https://arxiv.org/abs/2504.19413)): +- 比 OpenAI Memory +26% accuracy +- 比 standard RAG -91% latency +- -90% token 消耗 + +--- + +## 9. Benchmark 與評估 + +### 9.1 主要 Benchmark + +| Benchmark | 聚焦 | 說明 | +|-----------|------|------| +| **LoCoMo** | 長期對話記憶 | 事實保留、一致性；生產比較標準 | +| **LongMemEval** | 互動式記憶 | 多輪準確率；聊天助手評估 | +| **BEAM** | 超百萬 token | 極端長度記憶 | +| **MemoryBench** | 記憶與持續學習 | 多面向評估 | +| **MemoryAgentBench** | 增量多輪 | 任務完成率 | +| **HaluMem** | 記憶幻覺 | 虛假記憶檢測 | + +### 9.2 各方案 Benchmark 比較 + +| 方案 | LoCoMo | LongMemEval | 特點 | +|------|--------|-------------|------| +| Kumiho | Token F1 0.565 | — | 最高 adversarial refusal (97.5%) | +| HiMem | Overall 80.71 | — | 多跳 + 時間推理最均衡 | +| Hindsight | — | 91.4% | 最高 retrieval accuracy | +| Zep/Graphiti | — | 63.8% | 最強 temporal reasoning | +| Mem0 | 66.9% | — | 最低延遲、最少 token | +| MAGMA | — | — | Overall 0.700（自有 benchmark）| + +--- + +## 10. 對本專案的策略建議 + +### 10.1 現有優勢 + +本專案已具備： +- Vector + BM25 混合檢索（Hindsight 4 策略中的 2 項） +- Episodic task memory（記錄任務經驗） +- Failure taxonomy + retry evidence（試錯學習基礎） +- Citation validation + freshness decay（可信度治理） +- Feedback-driven ranking（回饋驅動排序） + +### 10.2 高價值改進方向 + +按價值/可行性排序： + +#### 優先級 1：多策略檢索增強 + +在現有 vector + BM25 基礎上增加： +- **Entity-based retrieval**：為記憶建立實體索引，支援「關於 X 的所有記憶」查詢 +- **Temporal filtering**：利用現有 freshness metadata，支援「最近 N 天」「某時間段內」的過濾 + +**可行性**：高。不需要新的儲存引擎，在 LanceDB 現有能力上擴充。 + +#### 優先級 2：記憶壓縮與摘要 + +- 長期未使用的記憶自動產生摘要版本 +- 相似記憶群組合併為更高層次的「知識筆記」 +- 參考 HiMem 的 Episode → Note 兩層模式 + +**可行性**：中。需要 LLM 呼叫做摘要，有成本考量。 + +#### 優先級 3：輕量級關係圖 + +- 在 LanceDB records 之上建立 entity-relationship metadata +- 記錄記憶之間的因果/依賴/時序關係 +- 支援簡單的圖遍歷查詢（不需要完整 graph DB） + +**可行性**：中。需要 schema 擴充和新的檢索路徑。 + +#### 優先級 4：Temporal Knowledge Tracking + +- 參考 Graphiti 的 bi-temporal 模型 +- 為事實記憶增加 `validFrom` / `supersededAt` 時間戳 +- 事實被新事實取代時不刪除而是標記失效 + +**可行性**：中。需要修改現有 freshness/decay 機制。 + +#### 研究候選（不列近期） + +- Graph DB 整合（Neo4j / Memgraph）：成本與部署複雜度過高，不符 local-first 定位 +- Memory-augmented transformer 整合：非 plugin 層責任 +- Parametric memory（LoRA）：非本專案責任 + +### 10.3 儲存引擎策略維持不變 + +上述建議均 **不改變** roadmap 中「以 LanceDB 為唯一主引擎」的策略。改進方向是在 LanceDB 之上增加索引結構與檢索策略，而非引入新的儲存後端。 + +只有當以下情況成立時才重新評估： +- 記憶關係推理需求增長到輕量級 metadata 無法支撐 +- 產品方向轉向需要 full graph database 能力 +- 有測量證據顯示 LanceDB 上的 entity index 效能不足 + +--- + +## 11. 關鍵參考資源 + +### 學術論文 + +| 論文 | arXiv | 年份 | 關聯性 | +|------|-------|------|--------| +| Graph-based Agent Memory: Taxonomy, Techniques, and Applications | [2602.05665](https://arxiv.org/abs/2602.05665) | 2026 | 最完整的圖記憶分類 | +| MAGMA: Multi-Graph based Agentic Memory | [2601.03236](https://arxiv.org/abs/2601.03236) | 2026 | 多圖混合架構 | +| Kumiho: Graph-Native Cognitive Memory | [2603.17244](https://arxiv.org/abs/2603.17244) | 2026 | 形式化記憶修正 | +| HiMem: Hierarchical Long-Term Memory | [2601.06377](https://arxiv.org/abs/2601.06377) | 2026 | 層級記憶 + 自我演化 | +| HyMem: Dynamic Two-Tier Retrieval | [2602.13933](https://arxiv.org/abs/2602.13933) | 2026 | 動態檢索分層 | +| Infini-attention | [2404.07143](https://arxiv.org/abs/2404.07143) | 2024 | 壓縮記憶注意力 | +| Mem0: Scalable Long-Term Memory | [2504.19413](https://arxiv.org/abs/2504.19413) | 2025 | 生產級記憶系統 | +| Graphiti: Temporal Knowledge Graphs | [2501.13956](https://arxiv.org/abs/2501.13956) | 2025 | 時態知識圖 | +| Memory in the LLM Era | [2604.01707](https://arxiv.org/abs/2604.01707) | 2026 | 統一記憶框架 | +| Experiential Reflective Learning | [2603.24639](https://arxiv.org/abs/2603.24639) | 2026 | 反思型記憶 | +| LoRA as Knowledge Memory | [2603.01097](https://arxiv.org/abs/2603.01097) | 2025 | 參數化記憶 | + +### 開源專案 + +| 專案 | GitHub | 主要用途 | Stars | +|------|--------|---------|-------| +| [neo4j-agent-memory](https://github.com/neo4j-labs/agent-memory) | Neo4j Labs | 完整三類型記憶 | — | +| [LightRAG](https://github.com/hkuds/lightrag) | HKUDS | 簡化版 GraphRAG | ~32K | +| [Graphiti](https://github.com/getzep/graphiti) | Zep | 時態知識圖 | — | +| [Mem0](https://github.com/mem0ai/mem0) | Mem0 | 通用記憶層 | ~48K | +| [Hindsight](https://github.com/vectorize-io/hindsight) | Vectorize | 多策略檢索 | ~4K | +| [Letta](https://github.com/letta-ai/letta) | Letta AI | OS-style 記憶 | ~21K | + +### Awesome 資源 + +- [TeleAI-UAGI/Awesome-Agent-Memory](https://github.com/TeleAI-UAGI/Awesome-Agent-Memory)（330 stars） +- [IAAR-Shanghai/Awesome-AI-Memory](https://github.com/IAAR-Shanghai/Awesome-AI-Memory) + +### 產業分析 + +- [Best AI Agent Memory Systems in 2026: 8 Frameworks Compared](https://vectorize.io/articles/best-ai-agent-memory-systems)（Vectorize.io, 2026-03） +- [Graph RAG in 2026: What Actually Works in Production](https://www.paperclipped.de/en/blog/graph-rag-production/)（Paperclipped, 2026-03） +- [Vector Database vs. Knowledge Graph for AI Agent Memory](https://atlan.com/know/vector-database-vs-knowledge-graph-agent-memory/)（Atlan, 2026-04） + +--- + +## 12. 2026 年技術趨勢共識 + +> 「記憶應該是顯式且可管理的 — 而非從更大 context window 湧現的副產品。」 + +四個核心趨勢： + +1. **選擇性檢索 > 全量上下文** — 顯式提取、存儲記憶，而非塞進 context window +2. **圖結構記憶興起** — 關係推理 + 時間推理是 vector-only 無法解決的 +3. **層級式組織** — Working / Episodic / Semantic 分層已成標準模式 +4. **Agent 自主記憶管理** — 系統自己決定記什麼、怎麼更新、何時遺忘 diff --git a/docs/opencode-plugin-interface-research.md b/docs/opencode-plugin-interface-research.md new file mode 100644 index 0000000..11c58e2 --- /dev/null +++ b/docs/opencode-plugin-interface-research.md @@ -0,0 +1,347 @@ +# OpenCode Plugin Interface Research: v1.2.x vs v1.4.0 + +**Date**: April 8, 2026 +**Status**: Research Complete +**Scope**: Plugin interface compatibility analysis for lancedb-opencode-pro migration + +--- + +## Executive Summary + +This document compares OpenCode plugin interfaces between v1.2.x and v1.4.0, identifying breaking changes, migration requirements, and recommendations for lancedb-opencode-pro compatibility. + +### Key Findings + +| Aspect | v1.2.x | v1.3.8+ | v1.4.0+ | +|--------|--------|---------|---------| +| **Stability** | ✅ Stable | ❌ Broken (NAPI bug) | ⚠️ Unknown | +| **SDK Changes** | Baseline | Same as v1.2.x | **Breaking changes** | +| **Diff Metadata** | `{to, from, patch}` | `{to, from, patch}` | `{patch}` only | +| **UserMessage.variant** | Top-level | Top-level | Nested under `model` | +| **NAPI Addon** | ✅ Working | ❌ Broken (Issue #20623) | Unknown | + +### Recommendation + +1. **Short-term**: Stay on v1.3.7 or earlier (current recommendation) +2. **Medium-term**: Monitor v1.4.0+ NAPI bug fix status +3. **Long-term**: Migrate to v1.4.0+ when stable, with SDK breaking change handling + +--- + +## Version Timeline + +| Version | Release Date | Key Features | Status | +|---------|--------------|--------------|--------| +| **v1.2.0** | Feb 14, 2026 | SQLite migration, PartDelta SDK event | ✅ Stable | +| **v1.2.25** | Mar 12, 2026 | Last v1.2.x used by this plugin | ✅ Working | +| **v1.2.27** | Mar 16, 2026 | Last v1.2.x stable release | ✅ Recommended | +| **v1.3.0** | Mar 22, 2026 | Node.js support, Git-backed review | ⚠️ Transition | +| **v1.3.7** | - | Last known working version | ✅ Working | +| **v1.3.8+** | - | Plugin loader refactor | ❌ Broken (Issue #20623) | +| **v1.4.0** | Apr 8, 2026 | Breaking SDK changes, diff metadata | ⚠️ Unknown | + +--- + +## Breaking Changes in v1.4.0 + +### 1. Diff Metadata Structure Change + +**Before (v1.2.x - v1.3.7)**: +```typescript +// diff metadata contained full file contents +interface DiffMetadata { + to: string; // Full file content after change + from: string; // Previous file content + patch: string; // Unified diff +} +``` + +**After (v1.4.0+)**: +```typescript +// Only patch remains, file contents removed +interface DiffMetadata { + patch: string; // Unified diff only +} +``` + +**Impact on lancedb-opencode-pro**: +- Minimal direct impact (plugin doesn't process diff metadata directly) +- If future features need file content comparison, must reconstruct from patch + +### 2. UserMessage.variant Nesting Change + +**Before (v1.2.x - v1.3.7)**: +```typescript +// variant was top-level field +userMessage.variant +``` + +**After (v1.4.0+)**: +```typescript +// variant nested under model +userMessage.model.variant +``` + +**Impact on lancedb-opencode-pro**: +- Current code doesn't use `UserMessage.variant` +- Future features should use `msg.model.variant` if needed + +--- + +## Plugin Hooks API Comparison + +### Stable Hooks (All Versions) + +From official documentation and real-world implementations: + +| Hook Name | Purpose | Stability | +|-----------|---------|-----------| +| `config` | Configuration reload | ✅ Stable | +| `event` | Session lifecycle events | ✅ Stable | +| `session.created` | New session initialization | ✅ Stable | +| `session.idle` | Session idle/first message | ✅ Stable | +| `session.end` | Session cleanup | ✅ Stable | +| `session.compacted` | Session compaction complete | ✅ Stable | +| `tool.execute.before` | Pre-tool validation | ✅ Stable | +| `tool.execute.after` | Post-tool processing | ✅ Stable | +| `file.edited` | File change notification | ✅ Stable | + +### Experimental Hooks (Use with Caution) + +| Hook Name | Purpose | Documentation Status | +|-----------|---------|---------------------| +| `experimental.chat.messages.transform` | Transform messages before API call | ⚠️ Community-only | +| `experimental.chat.system.transform` | Modify system prompt | ⚠️ Community-only | +| `experimental.text.complete` | Buffer assistant responses | ⚠️ Undocumented | +| `experimental.session.compacting` | Add compaction context | ⚠️ Partial docs | + +**Note**: Experimental hooks may change between versions without notice. + +--- + +## Current Plugin Implementation + +### Dependencies (package.json) + +```json +{ + "dependencies": { + "@opencode-ai/plugin": "1.2.25", + "@opencode-ai/sdk": "1.2.25" + } +} +``` + +### Hooks Used (src/index.ts) + +```typescript +const hooks: Hooks = { + config: async (config) => { /* ... */ }, + event: async ({ event }) => { /* ... */ }, + "experimental.text.complete": async (input, output) => { /* ... */ }, + "experimental.chat.system.transform": async (input, output) => { /* ... */ }, + tool: { /* ... */ } +}; +``` + +### Types Used + +```typescript +import type { Hooks, Plugin } from "@opencode-ai/plugin"; +import type { Part, TextPart } from "@opencode-ai/sdk"; +``` + +--- + +## Known Issue: v1.3.8+ NAPI Addon Bug + +### Root Cause + +OpenCode v1.3.8 introduced a plugin loader refactor (PR #20112) that breaks native NAPI addon resolution: + +``` +v1.3.8+ Plugin Loader: + resolvePackagePath() + pathToFileURL() + → @lancedb/lancedb resolves to empty object {} + → import("@lancedb/lancedb") returns {} + → store.init() fails silently +``` + +### Affected Versions + +| Version Range | Status | Workaround | +|---------------|--------|------------| +| v1.2.x - v1.3.7 | ✅ Working | None needed | +| v1.3.8 - v1.3.13 | ❌ Broken | Downgrade to v1.3.7 | +| v1.4.0+ | ⚠️ Unknown | Monitor Issue #20623 | + +### Reference + +- **Issue**: https://github.com/anomalyco/opencode/issues/20623 +- **PR that introduced bug**: https://github.com/anomalyco/opencode/pull/20112 + +--- + +## Migration Path to v1.4.0+ + +### Phase 1: Preparation (Before Migration) + +1. **Audit SDK Usage** + - Check all imports from `@opencode-ai/plugin` and `@opencode-ai/sdk` + - Identify any code that accesses `diff.to`, `diff.from`, or `userMessage.variant` + +2. **Update Type Definitions** + - Update to `@opencode-ai/plugin@^1.4.0` type definitions + - Verify TypeScript compilation with new types + +3. **Test Compatibility** + - Create test matrix for v1.2.x, v1.3.7, v1.4.0+ + - Test NAPI addon loading on each version + +### Phase 2: Code Changes + +1. **Diff Metadata Handling** (if needed) + ```typescript + // BEFORE (v1.2.x) + const { to, from, patch } = diffMetadata; + + // AFTER (v1.4.0+) + const { patch } = diffMetadata; + // Reconstruct file content from patch if needed + ``` + +2. **UserMessage.variant Access** (if needed) + ```typescript + // BEFORE (v1.2.x) + const variant = userMessage.variant; + + // AFTER (v1.4.0+) + const variant = userMessage.model?.variant; + ``` + +### Phase 3: Testing & Validation + +1. **Unit Tests**: Verify all hook invocations +2. **Integration Tests**: Test with OpenCode v1.4.0+ +3. **NAPI Tests**: Verify LanceDB loading works +4. **Regression Tests**: Test all 17 memory tools + +--- + +## Real-World Plugin Implementations + +### Reference Repositories + +| Repository | Purpose | Hook Usage | +|------------|---------|------------| +| [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) | Comprehensive plugin with 30+ hooks | All hooks | +| [context-mode](https://github.com/mksglu/context-mode) | Minimal plugin example | tool hooks, session hooks | +| [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | Claude Code hook conversion | Hook event mapping | +| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Hook migration patterns | Pre/post tool hooks | + +### Key Patterns + +```typescript +// Standard plugin export +import type { Plugin, Hooks } from "@opencode-ai/plugin"; + +const plugin: Plugin = async (ctx) => { + return { + // Hook implementations + "tool.execute.before": async (input, output) => { /* ... */ }, + "experimental.chat.system.transform": async (input, output) => { /* ... */ }, + tool: { /* tool definitions */ } + }; +}; + +export default plugin; +``` + +--- + +## Recommendations for lancedb-opencode-pro + +### Immediate Actions + +1. **Keep Current Version**: Stay on `@opencode-ai/plugin@1.2.25` / `@opencode-ai/sdk@1.2.25` +2. **Document Compatibility**: Update OPENCODE_COMPATIBILITY.md with v1.4.0 status +3. **Monitor Issue #20623**: Track NAPI bug fix progress + +### Medium-term Actions + +1. **Test Matrix**: Create automated tests for multiple OpenCode versions +2. **Version Detection**: Add runtime OpenCode version detection +3. **Graceful Degradation**: Improve error messages for version-specific failures + +### Long-term Actions + +1. **SDK Upgrade**: When v1.4.0+ is stable, update SDK dependencies +2. **Type Updates**: Update TypeScript types for new SDK +3. **Migration Guide**: Document breaking changes for users + +--- + +## Compatibility Decision Tree + +``` +┌─ Using lancedb-opencode-pro? +│ +├─ YES → Check OpenCode version +│ │ +│ ├─ v1.2.x - v1.3.7 → ✅ Works perfectly +│ │ +│ ├─ v1.3.8 - v1.3.13 → ❌ Broken (Issue #20623) +│ │ └─ Solution: Downgrade to v1.3.7 +│ │ +│ └─ v1.4.0+ → ⚠️ Unknown status +│ ├─ NAPI loading works? → ✅ Probably fine +│ └─ NAPI loading fails? → ❌ Same bug as v1.3.8 +│ └─ Wait for fix or use v1.3.7 +│ +└─ NO → Install from npm + └─ Configure in ~/.config/opencode/opencode.json +``` + +--- + +## Open Questions + +1. **v1.4.0 NAPI Status**: Is the NAPI bug fixed in v1.4.0? +2. **Plugin Commands Feature**: When will PR #7563 (plugin slash commands) merge? +3. **SDK Version Compatibility**: Can we update to `@opencode-ai/plugin@1.4.0` types without runtime changes? + +--- + +## References + +### Official Documentation + +- **Plugins**: https://opencode.ai/docs/plugins/ +- **Custom Tools**: https://opencode.ai/docs/custom-tools/ +- **Commands**: https://opencode.ai/docs/commands/ +- **Changelog**: https://opencode.ai/changelog + +### GitHub References + +- **Issue #20623** (NAPI bug): https://github.com/anomalyco/opencode/issues/20623 +- **PR #20112** (Plugin loader refactor): https://github.com/anomalyco/opencode/pull/20112 +- **PR #7563** (Plugin commands): https://github.com/anomalyco/opencode/pull/7563 +- **Issue #10262** (Slash commands feature): https://github.com/anomalyco/opencode/issues/10262 + +### Plugin Development + +- **Plugin Development Guide**: https://gist.github.com/rstacruz/946d02757525c9a0f49b25e316fbe715 +- **OpenCode SDK Types**: https://github.com/anomalyco/opencode/blob/dev/packages/plugin/src/index.ts + +--- + +## Change Log + +| Date | Version | Changes | +|------|---------|---------| +| 2026-04-08 | 1.0.0 | Initial research document | + +--- + +**Last Updated**: April 8, 2026 +**Next Review**: When OpenCode v1.4.0+ NAPI status is confirmed \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md index b4addf4..dd8e6e1 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -109,6 +109,10 @@ OpenCode 要從「有長期記憶的工具」進化成「會累積團隊工作 - 在 LanceDB 之上補強 large-scope retrieval 的 ANN fast-path - 為 `effectiveness_events` 建立 TTL / archival 治理機制 +- 在 LanceDB 之上補強多策略檢索（entity-based retrieval、temporal filtering） +- 探索輕量級 entity-relationship 索引（不引入額外 graph DB） + +> 詳細技術方案研究見 `docs/long-term-memory-landscape.md`（2026-04-08）。 ### 重新評估觸發條件 @@ -118,6 +122,7 @@ OpenCode 要從「有長期記憶的工具」進化成「會累積團隊工作 2. native binding / packaging 對 plugin distribution 造成明顯跨平台阻礙 3. 產品方向轉向 remote-first / serverized / multi-tenant 為主 4. 有測量證據顯示其他方案能在不提高太多維運成本下，顯著改善整體效能或複雜度 +5. 記憶關係推理需求增長到 LanceDB metadata 索引無法支撐（需 full graph DB） --- @@ -393,6 +398,113 @@ OpenCode 要從「有長期記憶的工具」進化成「會累積團隊工作 --- +## Phase 6 — 記憶架構演進（研究與漸進整合） + +**目標**：在維持 LanceDB 為主引擎的前提下，借鑑業界長期記憶最新研究，漸進式提升記憶品質與檢索能力。 + +> 技術研究依據：`docs/long-term-memory-landscape.md` + +--- + +## Phase 7 — OpenCode 版本相容性與遷移 + +**目標**：確保插件在 OpenCode 各版本間的相容性，並建立版本遷移策略。 + +### 當前狀態 + +| OpenCode 版本 | 狀態 | 說明 | +|--------------|------|------| +| v1.2.0 - v1.3.7 | ✅ 穩定 | 推薦使用 | +| v1.3.8 - v1.3.13 | ❌ 損壞 | NAPI 載入問題（Issue #20623） | +| v1.4.0+ | ⚠️ 待確認 | SDK breaking changes + NAPI 狀態未知 | + +### v1.4.0 Breaking Changes + +| 變更項目 | v1.2.x - v1.3.7 | v1.4.0+ | +|---------|-----------------|---------| +| Diff metadata | `{to, from, patch}` | `{patch}` only | +| UserMessage.variant | 頂層欄位 | `msg.model.variant` | + +### 風險評估（2026-04-08 更新） + +#### 🔴 高風險：AI SDK v5 → v6 遷移（v1.3.4） + +OpenCode v1.3.4 內部全面遷移到 AI SDK v6，同時進行 Effect-based 架構重構。`session.idle`（觸發 auto-capture 的主要 hook）及 tool hook 的執行路徑都可能受影響。 + +**受影響的鉤子**： +- `event` hook（session.start/end/idle/compacted） +- `experimental.text.complete` +- `experimental.chat.system.transform` +- 所有 tool hooks + +#### 🟡 中風險：Tool.define() 修復（v1.3.14） + +v1.3.14 修正了 `Tool.define()` 會重複包裝 `execute` 的 bug。若目前的實作恰好在 bug 行為下測試通過，升級後執行行為可能改變。 + +**受影響的 tools**： +- 17 個自訂 tool（memory_search, memory_delete, memory_stats 等） + +#### 🟡 中風險：Plugin 安裝機制（v1.3.11） + +v1.3.11 開始固定 plugin 版本、封鎖 install scripts。`prepublishOnly` 跑 `verify:full` 需要確認仍可正常執行。 + +#### 🟢 低風險：v1.4.0 本身 + +v1.4.0 新增的項目（OTLP、HTTP proxy、PDF 拖放）對本 plugin 無關。但今天才發布，社群尚未驗證。 + +### 分階段升級策略 + +``` +1.2.25 → 1.3.14 → (觀察 1-2 週) → 1.4.x（穩定後） +``` + +#### 第一步：先升到 1.3.14 + +這是跨越 AI SDK v6 遷移 + Tool bug 修復的版本。 + +**驗證方式**： +```bash +# 改 package.json +"@opencode-ai/plugin": "1.3.14", +"@opencode-ai/sdk": "1.3.14", + +npm install +npm run verify:full +``` + +**重點驗證項目**： +- `test:foundation`：`session.idle` 是否仍能觸發 auto-capture +- `test:regression`：17 個 tool 的 execute 行為是否正確 +- `test:e2e`：完整的寫入 → 重啟 → 搜尋流程 + +#### 第二步：確認後再考慮 1.4.0 + +等 1.4.0 發布後 1~2 週，確認社群無重大回報，再跟進。 + +### 功能項目 + +- [x] 相容性文件 `docs/OPENCODE_COMPATIBILITY.md` +- [x] Plugin interface 研究文件 `docs/opencode-plugin-interface-research.md` +- [x] 風險評估與分階段升級策略 +- [ ] SDK 升級到 1.3.14 測試驗證 → BL-059 +- [ ] OpenCode v1.3.14 相容性確認 → BL-060 +- [ ] OpenCode v1.4.0+ NAPI 狀態確認（待社群回報） +- [ ] SDK 升級測試矩陣（v1.2.x / v1.3.7 / v1.4.0+） +- [ ] 執行時期版本偵測機制 + +### 成功指標 + +- 使用者能清楚知道適用的 OpenCode 版本 +- 分階段升級路徑文件化並驗證 +- v1.4.0+ 相容性狀態明確記錄 + +### 參考資料 + +- `docs/opencode-plugin-interface-research.md` — v1.2.x vs v1.4.0 介面差異研究 +- `docs/OPENCODE_COMPATIBILITY.md` — 版本相容性與故障排除指南 + +--- + ## 優先級清單（先做什麼） ### P0 @@ -417,13 +529,22 @@ OpenCode 要從「有長期記憶的工具」進化成「會累積團隊工作 17. Embedder 錯誤容忍與 graceful degradation（Surface: Plugin）→ BL-049 ✅ DONE 18. FTS/Vector index concurrent-process race condition fix（Surface: Plugin）→ BL-051 ✅ DONE v0.6.1 19. 內建 embedding 模型（transformers.js）（Surface: Plugin）→ BL-050 ⚠️ 研究完成，待實作 +20. **SDK 升級到 1.3.14 測試驗證（Surface: Plugin）** → BL-059 ⚠️ 高優先 +21. **OpenCode v1.3.14 相容性確認（Surface: Plugin + Docs）** → BL-060 ⚠️ 高優先 ### P2 -16. large-scope retrieval 的 ANN fast-path（Surface: Plugin）→ BL-036 -17. Store repository 職責分離（Surface: Plugin）→ BL-042 -18. Embedding fallback 可觀測性補強（Surface: Plugin + Docs）→ BL-047 -19. weekly review automation 強化 -20. trajectory relabeling / hindsight replay +22. OpenCode v1.4.0+ 相容性驗證（Surface: Plugin + Docs）→ BL-056 +23. large-scope retrieval 的 ANN fast-path（Surface: Plugin）→ BL-036 +24. Store repository 職責分離（Surface: Plugin）→ BL-042 +25. Embedding fallback 可觀測性補強（Surface: Plugin + Docs）→ BL-047 +26. SDK 升級測試矩陣（Surface: Test-infra）→ BL-057 +27. 執行時期版本偵測機制（Surface: Plugin）→ BL-058 +28. weekly review automation 強化 +29. trajectory relabeling / hindsight replay +30. 多策略檢索增強：entity-based retrieval + temporal filtering（Surface: Plugin）→ BL-052 +31. 記憶摘要壓縮（Surface: Plugin）→ BL-053 +32. 輕量級實體關係索引（Surface: Plugin）→ BL-054 +33. 時態知識追蹤（Surface: Plugin）→ BL-055 ---