乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > OpenCode插件系列: opencode-magic-context

OpenCode插件系列: opencode-magic-context

当前时间： 2026-05-06 06:45:07 更新时间： 2026-05-06 分类：软件教程 评论(0)

OpenCode插件系列: opencode-magic-context

类型: 上下文管理插件 代码库: https://github.com/cortexkit/magic-context 

NPM包: @cortexkit/magic-context (CLI), @cortexkit/opencode-magic-context (OpenCode插件), @cortexkit/pi-magic-context (Pi插件) 星标: 500+ ⭐

1. 这是什么插件？

Magic Context 是一个用于AI编码代理的缓存感知无限上下文、跨会话内存和背景历史压缩插件。

核心思想是让代理专注于编码工作，而不是自己管理上下文和内存。所有上下文压缩和内存管理都在后台自动运行，代理完全无感知。

主要组件:

  1. 背景历史记录器 — 主代理继续工作时，一个单独的模型在后台压缩旧的对话。所有操作都是缓存感知的，避免浪费缓存的prefix。
  2. 跨会话项目内存 — 架构决策、约束和偏好在不同会话间持久化。
  3. 夜间梦想家代理 — 整合、去重、提升记忆到规范事实，并维护代码库文档。
  4. 按需助手 — 用相关的项目上下文增强提示。
  5. TUI侧边栏 — 在终端内显示实时上下文分解、token使用、历史记录器状态和内存计数。

2. 有什么用？

在以下场景中使用它：

  • ✅ 无限上下文窗口 — 可以在同一会话中工作数周、数月甚至数年
  • ✅ 跨会话记忆 — 在OpenCode中写入记忆，在Pi中检索（反之亦然）
  • ✅ 防止上下文过载 — 自动压缩旧对话，保持当前上下文精简
  • ✅ 智能记忆管理 — 通过语义搜索检索相关记忆
  • ✅ 实时监控 — 通过TUI侧边栏查看token分解和历史记录器状态
  • ✅ 自动代码库文档 — 梦想家代理维护项目文档

技术特性:

  • 缓存感知压缩 — 避免破坏缓存prefix，只在必要时压缩
  • 分层压缩策略 — 不同年龄的文本采用不同的压缩强度
  • 语义搜索 — 通过嵌入向量在记忆和会话历史中搜索
  • 时间感知 — 显示消息间的时间间隔，帮助代理理解时间流逝
  • Git提交索引 — 索引项目提交记录，支持语义查询
  • 子代理上下文管理 — 子代理自动清理旧工具调用和推理过程

3. 怎么用？

快速安装（推荐）

运行交互式设置向导 — 它会检测你的模型、配置所有内容并处理兼容性：

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex

或手动安装OpenCode插件:

opencode plugin @cortexkit/opencode-magic-context@latest --global

配置

关闭 ~/.config/opencode/opencode.jsonc 文件中的压缩:

"compaction": {"auto": false,"prune": false  },

如果使用了oh-my-openagent 或者oh-my-opencode  , 需要做以下设置：

"disabled_hooks": ["non-interactive-env","context-window-monitor","preemptive-compaction","anthropic-context-window-limit-recovery","agent-usage-reminder","category-skill-reminder","comment-checker","directory-readme-injector","keyword-detector","todo-continuation-enforcer","write-existing-file-guard"  ]

创建 ~/.config/opencode/magic-context.jsonc 文件：

{"enabled": true,"debug": false,// 上下文管理设置"ctx_reduce_enabled": false,  // 禁用代理驱动的压缩（推荐使用背景压缩）"execute_threshold": 0.75,    // 触发压缩的上下文利用率阈值（百分比）// 历史记录器设置"historian": {"enabled": true,"model": "anthropic/claude-haiku-4.5"// 用于压缩的模型  },// 梦想家设置"dreamer": {"enabled": true,"schedule": "daily",        // 每天运行"user_memories": true,      // 提取用户行为观察"pin_key_files": false// 实验性：自动固定关键文件  },// 记忆设置"memories": {"enabled": true,"embedding_provider": "openai",  // 或 "anthropic", "cohere""max_injected": 10// 每次注入的最大记忆数  }}

可用的斜杠命令

命令
功能
/ctx-status
调试视图：标签、待处理删除、缓存TTL、历史记录器进度
/ctx-flush
强制立即执行所有排队操作，绕过缓存TTL
/ctx-recomp
从原始历史重新构建隔间和事实
/ctx-aug
对提示运行助手增强 — 通过单独模型检索相关记忆
/ctx-dream
按需运行梦想家维护 — 整合、验证、归档、改进记忆

效果图:

对于不同的AI代理：

  • OpenCode: 使用 @cortexkit/opencode-magic-context 插件
  • Pi代理: 使用 @cortexkit/pi-magic-context 插件
  • 独立CLI: 使用 @cortexkit/magic-context 包

4. 什么时候用？

在以下场景使用：

  • ✅ 长期项目 — 在同一项目上工作数周或数月
  • ✅ 大型代码库 — 需要跨多个文件保持上下文一致
  • ✅ 团队协作 — 需要共享架构决策和项目知识
  • ✅ 复杂重构 — 需要参考历史决策和约束
  • ✅ 多个AI代理 — 在OpenCode和Pi之间共享记忆
  • ✅ 按token付费 — 需要减少不必要的上下文重复

不要使用的场景：

  • ❌ 简单短任务 — 一次性脚本或简单的bug修复
  • ❌ 探索性工作 — 快速原型验证，不需要长期记忆
  • ❌ 受限的系统资源 — SQLite数据库和后台模型需要额外资源
  • ❌ 需要手动完全控制 — 想要100%手动管理所有上下文

⚠️ 重要注意事项

缓存权衡：

  • 没有Magic Context: 缓存命中率约 90%
  • 有Magic Context: 缓存感知操作，根据模型变化调整压缩时机，避免不必要的缓存破坏
  • 背景压缩 使用单独模型，不影响主代理的缓存

兼容性问题：

  • 与DCP插件冲突 — 不能同时启用Magic Context和DCP
  • OpenCode内置压缩 — 需要禁用以避免冲突
  • 启动时冲突检测 — Magic Context会自动检测并警告配置问题

实验性功能：

  • 用户记忆 — 提取用户行为模式并注入为 <user-profile>
  • 关键文件固定 — 自动识别并固定经常读取的核心文件
  • Git提交索引 — 使提交历史可通过语义搜索访问
  • 自动搜索提示 — 在提示前运行后台搜索，提供相关片段

许可证: MIT

🔗 有用链接

  • 官方文档:
    • GitHub仓库: https://github.com/cortexkit/magic-context
    • 发布页面: https://github.com/cortexkit/magic-context/releases
    • 桌面应用发布: https://github.com/cortexkit/magic-context/releases/tag/dashboard-v0.4.1
    • 问题追踪: https://github.com/cortexkit/magic-context/issues
    • 讨论区: https://github.com/cortexkit/magic-context/discussions
  • NPM包:
    • CLI工具: https://www.npmjs.com/package/@cortexkit/magic-context
    • OpenCode插件: https://www.npmjs.com/package/@cortexkit/opencode-magic-context
    • Pi插件: https://www.npmjs.com/package/@cortexkit/pi-magic-context
  • 配置和架构文档:
    • 完整配置参考: https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md
    • API参考: https://cortexkit.github.io/magic-context/
    • 架构说明: https://github.com/cortexkit/magic-context/blob/master/ARCHITECTURE.md
    • 迁移指南: https://github.com/cortexkit/magic-context/blob/master/MIGRATION.md
  • 相关项目和平台:
    • OpenCode官网: https://opencode.ai/
    • Pi coding agent: https://pi.dev
    • Discord社区: https://discord.gg/DSa65w8wuf
    • 开发文档: https://github.com/cortexkit/magic-context/blob/master/DEVELOPMENT.md
  • 比较和迁移:
    • 与DCP插件比较: https://github.com/cortexkit/magic-context/wiki/DCP-vs-Magic-Context
    • 从DCP迁移: https://github.com/cortexkit/magic-context/wiki/Migrating-from-DCP
    • 常见问题: https://github.com/cortexkit/magic-context/wiki/FAQ