Magic Context Monorepo贡献指南目录地图、Golden测试与提交第一个PR的完整步骤【免费下载链接】magic-contextUnbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.项目地址: https://gitcode.com/gh_mirrors/mag/magic-contextMagic Context 是一个 TypeScript 与 Rust 双栈的 Monorepo它为编码 Agent 提供自管理的上下文与长期记忆CortexKit 中的海马体。本文面向新贡献者带你掌握 Magic Context Monorepo 的目录地图、Golden 测试机制并完整走通从克隆仓库到提交第一个 PR 的每一步。 项目速览Magic Context 是什么一句话概括Unbounded context. Memory that manages itself.无限上下文自我管理的记忆。Capture捕获后台 historian 把旧会话压缩成分层摘要同时把值得保留的知识决策、约束、约定提炼为项目记忆Consolidate巩固夜间 dreamer 代理校验、去重、晋升记忆如同睡眠巩固Recall召回每一轮自动注入相关记忆Agent 可随时跨记忆、历史对话和 git 提交搜索更多背景可阅读项目主文档 README.md 和架构说明 docs/architecture/。️ 目录地图Monorepo 全景速览首次进入仓库先记住这张地图完整说明见 STRUCTURE.md目录语言职责packages/plugin/TypeScriptOpenCode 插件 共享 TS 核心绝大多数行为改动从这里开始packages/pi-plugin/TypeScriptPi 与 OMP 插件与 OpenCode 的parity 由PARITY.md追踪packages/cli/TypeScriptsetup/doctor/migrate等 CLI 命令packages/e2e-tests/TypeScript针对 OpenCode 1/2、Pi、OMP、Rust 五种栈的端到端套件crates/mc-module/Rustck-mc子模块transform、historian、工具门面crates/mc-store/Rust单写者 SQLite 存储schema、迁移、CAS 状态转移crates/mc-core/Rust缓存稳定性 transform 与分类逻辑crates/mc-tokenizer/Rust词元估算器scripts/TS/Shell发布、版本同步、缓存击穿分析等工具定位代码的小技巧来自STRUCTURE.md的官方建议这个文件是地图找具体符号请直接搜索代码。常见落点新增 transform 行为 → packages/plugin/src/hooks/magic-context/并同步镜像到 Pi 插件与 Rust 模块新增 Agent 工具 →packages/plugin/src/tools/名称/新增迁移 →migrations.ts加条目并升版本号端到端场景 → packages/e2e-tests/tests/ 中创建并注册进mode-manifest.json 贡献两道硬门槛写代码前必读规则全文在 CONTRIBUTING.md新人最常被拒的两个原因都在这里。第一步先拿到获批的 Issue行为变更必须先有被批准的 IssueBug 修复 → 开 bug issue功能/设计变更 → 开设计提案与维护者讨论方案等待 Issue 被贴上design-approved标签再动手在 PR 正文中用模板的Approved issue: #123或分步 PR 用Refs #123关联 Issue⚠️ 不要使用Closes/Fixes/Resolves——它们会在合并时提前关闭 Issue而维护者希望在功能真正发布时才关闭门槛由草稿转换机制强制未获批的 PR 在打开或被标记为 ready 时会自动转回 draft直到关联 Issue 带有design-approved。第二步覆盖所有已存在的 Harness任何触及 harness 相关表面的改动必须同时覆盖OpenCode 1、OpenCode 2、Pi、OMP 和 Rust 模块凡该表面存在之处。某表面在某 harness 中确实不存在可以标注 not applicable但放着已存在的表面不覆盖PR 会被按形状拒收此前 #450 和 #461 即因此被拒。 Golden 测试这个仓库的质量基石Magic Context 的 TS 与 Rust 双实现要保持行为一致靠的就是Golden 测试黄金快照测试用 TS 真实实现跑一遍典型场景把结果固化为 JSON 快照Rust 测试再逐字段断言自己与快照一致。三件套的位置组成路径作用生成器crates/mc-module/gen/19 个gen-*.ts脚本驱动真实 TS 代码产出快照快照文件crates/mc-module/testdata/40 余个*-golden.jsonRust 测试的断言依据断言代码crates/mc-module/src/differential_goldens.rs 等Rust 侧读取快照并比对以边界判定为例生成器 gen-boundary-golden.ts 通过Bun.resolveSync导入真实 TS 模块产出 boundary-golden.json内含常量表与消息块用例Rust 测试随后断言分组尾巴、预算与触发判定完全一致。修改行为后如何更新快照# 单个快照 bun crates/mc-module/gen/gen-boundary-golden.ts # 差异夹具 DG-1 到 DG-8并更新输入溯源哈希 bash crates/mc-module/gen/regenerate-differential-golden.sh新手常见误区改了 TS 行为却忘记重新生成快照导致 Rust 测试全线飘红。记住口诀——改行为 → 跑生成器 → 提交快照 代码。 提交第一个 PR完整操作步骤1️⃣ 准备环境并克隆仓库唯一硬性依赖是 Bun ≥ 1.4.01.3.x 存在模块解析差异仓库门禁会主动拦截。git clone https://gitcode.com/gh_mirrors/mag/magic-context cd magic-context bun install2️⃣ 本地跑通测试与格式门禁CI 会拒收未格式化的代码提交前务必全部跑绿bun run build # 构建插件 bun run typecheck # 类型检查 bun test # TS 测试 bun run lint # Biome 检查 bun run format # Biome 格式化 cargo test --workspace # Rust 测试 cargo fmt --check # Rust 格式 cargo clippy --workspace --all-targets -- -D warnings # Rust lint懒人一步到位bun run check:all。3️⃣ 填写 PR 模板并提交草稿仓库模板 .github/pull_request_template.md 非常简洁但每一项都是硬性要求首行Approved issue: #→ 填上获批的 Issue 编号Harness coverage五个复选框OpenCode 1 / OpenCode 2 / Pi / OMP / Rust module逐一选择covered、not applicable — surface does not exist there或NOT covered——不允许留空提交时保持draft 状态等 Issue 获得design-approved后再请求 review。4️⃣ 等待评审与合并门禁机器人会检查草稿状态维护者为 Issue 打标后等待中的草稿会被自动转为 ready一个仅修改 OpenCode 文件但对应 Pi 孪生文件未同步的 PR会收到覆盖性提醒提示性质不阻断合并但需人工说明合并后由维护者在功能发布时关闭 Issue✅ 新手自检清单Issue 已获批design-approvedPR 中用Refs/Approved issue关联而非Closes五个 harness 表面逐一处理PR 模板无空项TS 行为变更后已重新生成对应 golden 快照bun test、bun run lint与cargo fmt、cargo clippy全部通过文件命名 kebab-case测试以*.test.ts与代码同目录测试未触碰真实数据库测试预加载会把数据目录指向临时路径 小结贡献 Magic Context 的路径其实很清晰读懂目录地图 → 拿到获批 Issue → 五表面全覆盖 → 用 Golden 测试守住 TS/Rust 一致性 → 提交草稿 PR。这个仓库用门禁与快照把双栈 parity做成了可自动验证的工程纪律对新贡献者既是门槛也是最好的保护——按流程走你的第一个 PR 会比你想象的更顺利。【免费下载链接】magic-contextUnbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.项目地址: https://gitcode.com/gh_mirrors/mag/magic-context创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考