oh-my-openagent memory-core 包级指令面审查：13 个源码域、核心不变量与公共 API 的一致性验证

oh-my-openagent memory-core 包级指令面审查13 个源码域、核心不变量与公共 API 的一致性验证【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent导读oh-my-openagentOmO在packages/memory-core/中维护着一个harness 中立harness-neutral的智能体记忆引擎以 Git 仓库为底层的 Markdown 记忆文件系统MemFS、原子化的记忆工具、提示词编译、反射调度、会话检索、同步与种子内容。本文以仓库中的审查记录 .omo/evidence/20260812-init-deep/manual-review.md 为主线完整还原一次包级指令面审查manual instruction-surface review的范围、精确校验方法与 PASS 判定标准并结合 packages/memory-core/AGENTS.md 与源码实现逐层拆解 memory-core 的 13 个源码域、8 条核心不变量、7 组公共 API 表面以及包级 QA 流程。读完本文你将掌握如何用路径存在性 符号存在性的机械检查验证文档与源码同步并理解该引擎每个子系统的职责边界与不变量约束。一、审查背景为什么需要指令面审查在像 oh-my-openagent 这样包含大量 core 包与多个 harness 适配器Senpi、Pi、OpenCode 等的仓库中每个包都有一份AGENTS.md作为面向维护者与 Agent 的指令面instruction surface它告诉后续修改者这个包能做什么、不允许做什么、如何测试。如果指令面与源码脱节后续改动就可能破坏不变量。这次审查记录于 manual-review.md针对的是memory-core包的指令面其核心目标可以概括为三条指南必须是包级范围的只描述 memory-core 自己拥有的领域不得重复根级 OpenCode/Codex QA 指令也不得越界描述适配器的完整架构指南中每一个被点名的路径与符号都必须真实存在于当前源码适配器特有行为必须归属 Senpi 组件不得被反向导入 core 包。审查结论为PASSNAMED_PATHS_OK/NAMED_SYMBOLS_OK/STYLE_OK并且包表链接是唯一一次祖先级编辑——即指南只向上引用过一次packages/AGENTS.md的包表格其余全部是包内自洽内容。二、审查范围四份文档的职责划分审查精确划定了四份关键文档每份承担不同职责理解这份分工是复现审查的前提文档职责packages/AGENTS.md仓库级指南尤其关注其中的Core 包表格用于确认 memory-core 在包矩阵中的位置与包表链接的合法性packages/memory-core/AGENTS.md本次审查的主体memory-core 的包级指令面从上到下逐段核对packages/memory-core/src/index.ts验证文档所声称的公共 barrel唯一公共导出面是否与代码一致packages/omo-senpi/src/components/memory/AGENTS.md核对adapter/core 边界避免出现重复的适配器指令这四份文档对应了指令面的四个层次仓库层包归属→ 包层领域职责→ 导出层公共 API→ 适配器层消费边界。审查确认Senpi 组件仍然是适配器注册与生命周期行为的唯一所有者而 memory-core 保持零 Senpi 导入。三、memory-core 的 13 个源码域ANATOMYmemory-core的指令面将其实现组织为 13 个源码目录加一个测试文件公共入口是 src/index.ts 的 barrel 导出export * from ./git…./seeds共 17 个导出组含personas与recall两个辅助域。下表按 AGENTS.md 的 ANATOMY 表整理并补充各目录的核心职责细节目录责任src/git/Git 命令边界、clean-tree 检查、提交、合并、remote 与类型化 git 错误src/identity/记忆身份解析与OMO_MEMORY_HOME目录布局src/locks/记忆写入、反射调度、会话记录状态的跨进程锁机器级recall-wake计数租约每槽位recall-wake.slot-n.lock、FIFOrecall-wake.tickets/、默认 2 槽、基于证明的陈旧恢复、有界等待最终以RecallWakeBusyError结束src/memfs/记忆路径校验、Markdown frontmatter 解析、hook 脚本安装src/tools/memory与memory_apply_patch操作、patch 解析、类型化工具错误、自动提交行为src/journal/每会话会话记录游标、反射快照与持久化日志状态src/facts/持久化事实管道队列 游标水位、失败退避/存储、负载上限、人物路由、恢复、变更规划src/people/人物卡文法解析/序列化、slug 规则、保留 slug、观察项src/soul/Soul 文件路径与身份作用域的 soul-notice 水位消费src/reflection/触发求值、运行预留、worktree 执行、完成校验、合并结果、孤儿清扫回收无人拥有的 worktree/分支、以及重复失败后的 park 策略每间隔一次半开探测src/compile/将已提交的记忆修订编译为标记化的系统提示块并按模板哈希缓存src/search/查询解析、会话记录 provider、排序的记忆/会话检索src/sync/远端镜像同步与秘密脱敏src/reminders/反射与记忆维护提醒生成src/seeds/默认记忆块与首次运行仓库播种src/concurrency/锁与多写入者测试用的子进程夹具不是公共运行时模块也正因如此它未出现在 index.ts 的 barrel 中从源码结构可以推断src/concurrency/是唯一一个仅供测试的目录barrel 明确不导出它AGENTS.md 也将其标注为非公共运行时模块这体现了公共表面必须显式、最小的设计原则。四、核心不变量memory-core 的行为底线AGENTS.md 定义了 8 条核心不变量它们是本次审查STYLE_OK与后续代码评审的事实基准保持 harness 中立生产代码与包依赖不得导入 Senpi、Pi、OpenCode 适配器或其他 harness 特定包。该边界由 src/harness-neutrality.test.ts 强制它先检查package.json中 dependencies/devDependencies/peerDependencies 的包名再递归扫描src/下每个.ts文件断言不包含code-yeongyu/senpi、earendil-works/、mariozechner/pi-、oh-my-opencode/omo-senpi、oh-my-opencode/senpi-task等禁用前缀的导入。把记忆仓库当作事务状态写工具必须先获取memory-write锁、要求仓库干净、校验路径、执行单次操作且只提交受影响路径。不得绕过GitMemoryRepo、锁域或工具入口。从已提交状态编译提示编译只能针对HEAD或显式修订未提交的工作树内容不构成权威记忆。这一点在 src/compile/compile.ts 中落实compileMemoryBlockAtRevision通过repo.lsTree(revision)枚举树、repo.show(revision, path)读取文件从未触碰工作树。保持 Markdown 契约记忆文件必须有含非空description的 YAML frontmatterread_only: true阻止修改保持 UTF-8、规范化仓库相对路径与 LF 输出。对应实现位于 src/tools/memory.ts 的loadEditableread_only检查与readUtf8UTF-8/UTF-16 BOM 检测与TextDecoder(utf-8, { fatal: true })严格解码。Frontmatter 是严格 YAML一处文法全局生效renderMemoryFile是唯一写入者它对yaml包无法原样读回的标量加引号并重新解析自己的头部读取端解码带引号标量、保留非契约键extra以让 SKILL.md 的name/version在编辑后存活仅对既有文件回退到旧版首个冒号文法。describeFrontmatterViolation是 pre-commit hook 规则、validateCompletion与normalizeMemoryFrontmatter以公共 git 目录中的标记为键的一次性旧版修复的共享闸门。禁止手写不带引号的description:。保持反射转移确定性手动触发 压缩触发 步数触发同时只允许一个活动运行与一个已合并的待处理预留。这由 src/reflection/machine.ts 中的优先级表支撑step-count: 1、compaction: 2、manual: 3dream 各 origin 独立排序。锁保持领域特定使用memory-write、reflection-scheduler或会话专属锁不得用单一全局锁替代也不得添加基于计时的测试。外部同步前必须脱敏远端镜像输出必须经过 sync 脱敏层严禁把含秘密的原始日志或配置提交进记忆。此外AGENTS.md 还强调两条事实管道纪律事实状态持久且 fail-closed队列/游标/已消费写入在身份作用域锁下原子发布.tmp rename、模式0o600畸形 JSON 解析为空而不阻塞入队/消费水位永不回退排序遵循规范化的日志位置/快照边界绝不做词法 message-ID 比较行为模式绝不存入人物卡卡片行只允许IDENTITY/ATTRIBUTE/RELATIONSHIP/INSTRUCTION前缀与有界元数据。五、公共 API 表面从文档到源码的 7 组符号AGENTS.md 列出了 7 组公共 API本次审查的NAMED_SYMBOLS_OK正是逐一对它们做git grep验证。下表将文档声明与源码落点一一对应均已在本仓库确认存在文档声明源码位置runMemoryTool()实现create、str_replace、insert、delete、rename、update_descriptionsrc/tools/memory.tsrunMemoryApplyPatch()在记忆仓库内应用多文件 Codex 风格 patchsrc/tools/memory-apply-patch.tsGitMemoryRepo仓库初始化、clean 检查、提交、修订、合并 worktree、remote 检测src/git/repo.tsevaluateTransitions()/reserveTransition()/completeTransition()纯反射状态机src/reflection/machine.tscompileMemoryBlock()/compileMemoryBlockAtRevision()渲染注入到 harness 提示中的已提交记忆投影src/compile/compile.tsFactsQueue、applyFactsBatch()、planFactsMutation()src/facts/consumeSoulNoticeDelta()src/soul/以工具层为例runMemoryTool的每个命令都遵循同一事务骨架先commitMemoryWrite持锁、clean 检查、校验、执行、只提交受影响路径失败时把 patch 解析错误MemoryPatchParseError/MemoryPatchHunkError与其他错误统一包装为类型化MemoryToolError。str_replace的实现刻意只替换第一处匹配与 letta-code 实测行为对齐见 Senpi 组件 AGENTS.md 的 divergence #11找不到old_string时返回明确错误insert要求insert_line为数字并把行号下限钳制为 1。这些细节说明公共 API 不只是签名还包含错误语义与边界行为。六、精确检查路径与符号的机械验证审查最硬核的部分是精确检查Exact checks它用两条 bash 循环把文档中的每个声明变成可执行断言# 1) 路径存在性文档点名的 14 个源码入口必须全部存在 for p in src/git src/identity src/locks src/memfs src/tools src/journal \ src/reflection src/compile src/search src/sync src/reminders src/seeds \ src/concurrency src/index.ts src/harness-neutrality.test.ts; do test -e packages/memory-core/$p done # 2) 符号存在性文档声明的 6 组公共符号必须在 src 内可被 grep 到 for sym in runMemoryTool runMemoryApplyPatch GitMemoryRepo \ evaluateTransitions reserveTransition completeTransition \ compileMemoryBlock compileMemoryBlockAtRevision; do git grep -q $sym -- packages/memory-core/src done本仓库复现这两条命令的结果为14 个路径全部OK8 个符号completeTransition与compileMemoryBlockAtRevision也在文档列出的同一组符号循环内均能在src/中找到。审查记录将观察结果总结为三行状态NAMED_PATHS_OK NAMED_SYMBOLS_OK STYLE_OKSTYLE_OK对应文风检查指南通篇避免了被禁止的破折号字符与仓库禁用的填充语且唯一的祖先级编辑就是包表链接。这套先机械断言、后人工风格判断的流程本身即可复用到其他 core 包的指令面维护中。七、审查结论与边界确认审查 verdict 明确了五条判定依据指南是包级范围的完整映射了 13 个源码域、核心不变量、公共表面、消费者、包级 QA 与本地反模式没有复述根级 OpenCode/Codex QA 指令也没有展开完整的适配器架构Senpi 组件始终是适配器注册与生命周期行为的唯一所有者见 packages/omo-senpi/src/components/memory/AGENTS.md 的 Anatomy 表index.ts工厂、wiring.ts注册面、identity-runtime.ts、worker/等全部留在适配器侧每个被点名的路径与符号都在当前源码中存在指南避免了被禁字符与仓库禁用填充语包表链接是唯一祖先级编辑。最终结论PASS。八、复现审查与包级 QA如果你要在本地对 memory-core 做同样或后续的验证可直接使用 AGENTS.md 给出的包级 QA 命令# 运行包内全部单元测试含 harness-neutrality 边界测试 bun test packages/memory-core/src/ # 包级类型检查 bun run --cwd packages/memory-core typecheckAGENTS.md 还给出了聚焦改动的测试策略先跑最近的同目录*.test.ts再跑整个包套件并发测试必须用有界超时精确等待状态或进程事件严禁加入固定 sleep 或重试循环——这与禁止基于计时的测试的不变量一脉相承。九、反模式清单评审与自检的检查表AGENTS.md 以六条反模式收尾它们同时是评审者和 Agent 的红线在memory-core中导入 harness 包违反中立性harness-neutrality.test.ts会直接红灯不经过路径校验、frontmatter 解析、加锁与原子 git 提交直接写记忆 Markdown把脏工作树当作编译记忆来读违反从已提交状态编译修改read_only块或接受非 UTF-8 记忆文件吞掉 git、锁、合并或反射失败用计时运气测试跨进程行为。这套清单的价值在于它把抽象不变量翻译成了可直接在 code review 中勾选的条目任何一条命中都意味着新的改动违反了 memory-core 的行为契约。结语一次 PASS 的指令面审查本质上是在回答三个问题指南是否只属于自己包的领域、指南点名的每个路径和符号是否真实、适配器边界是否清晰。围绕 manual-review.md 展开的这次审查完整覆盖了 memory-core 的 13 个源码域、8 条核心不变量、7 组公共 API 与包级 QA 流程并以可复现的 bash 断言作为证据。对于需要向 memory-core 贡献代码的开发者而言packages/memory-core/AGENTS.md 既是地图也是契约——先读它再动代码。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考