393 393.ee中文技术博客
2026/09/12完整文章

OpenContext 装好之后怎么验收：一张真正面向 Agent 工作效果的检查清单

不以 oc init 成功为终点，围绕跨会话、跨仓库、检索准确性、写回质量、配置范围和隐私边界，建立一套可复现的 OpenContext Agent 工作验收方法。

OpenContextAI Agent开发工具知识管理验收清单

OpenContext 安装成功，只能证明文件被生成；它是否真的改善了 Agent 工作，要等一套跨会话、跨仓库和可追溯的验收跑完之后才知道。很多人执行 npm install -g @aicontextlab/cli，进入项目运行 oc init，看到没有报错，就把接入当成完成。可 Agent 仍然可能不知道上一轮做过的决定，检索时拿错项目的文档，写回时覆盖原有结论，甚至把不该进入共享上下文的凭据带进去。

OpenContext 官方 README 的定位是个人上下文和知识库：它提供管理全局 contexts/ 库的 oc CLI、MCP Server、Skills 与斜杠命令、桌面应用和本地 Web UI，并复用已有的 Codex、Claude 或 OpenCode CLI。验收对象不是“有没有一个新目录”，而是一条完整闭环：Agent 能否在行动前读到正确背景，能否跨项目找到正确资料，任务完成后能否把有价值的结论写回，而且每一步的范围都在人的控制之内。

先定义通过标准：从安装检查转向工作结果

建议在验收记录里同时保留基线和接入后的结果。基线可以选一个过去经常需要重复解释的任务，例如让 Agent 修改一个接口、遵守一项架构约定，再把决策写进项目文档。记录首次解释所需时间、返工次数、错误引用和最终文档状态。接入 OpenContext 后，用相近难度的任务重跑，不要求每一次都更快，但要能观察到三个变化：背景说明减少，检索命中更相关，完成后的知识不再只留在聊天记录里。

通过标准必须是可观察的，而不是“感觉更聪明”。跨会话测试要能从第二个会话中复述一项明确决策；跨仓库测试要能区分两个项目同名但不同含义的配置；写回测试要能找到新文档或新增段落；隐私测试要能证明排除的目录没有进入上下文。没有证据的“应该可以”不算验收通过。

第一关：确认初始化到底改了什么

官方 Quick Start 的基本路径是：

npm install -g @aicontextlab/cli
cd your-project
oc init

oc init 会提示工具设置，默认面向全部支持的工具。README 还列出了非交互参数 --tools cursor,claude,codex，以及 --no-claude、--no-cursor、--no-codex。第一轮验收不要只看终端返回值，要把实际写入范围列出来：当前机器启用了哪些工具，是否生成了用户级 Skill，是否生成了斜杠命令，MCP 配置写到了哪里。

官方列出的路径包括：Cursor 的命令在 ~/.cursor/commands，Claude Code 的命令在 ~/.claude/commands；Skills 分别位于 ~/.cursor/skills/opencontext-*、~/.claude/skills/opencontext-* 和 ~/.codex/skills/opencontext-*。如果使用了 CLAUDE_CONFIG_DIR 或 CODEX_HOME，还要按实际环境检查对应位置。MCP 配置则分别是 ~/.cursor/mcp.json、~/.claude/mcp.json 和 ~/.codex/mcp.json。验收时把“生成了什么”和“本来不希望改什么”都记录下来，避免一次初始化意外影响所有项目。

随后分别运行相关 CLI 的新会话，而不是只在当前终端里猜测。检查 Agent 是否能发现 opencontext-context、opencontext-search、opencontext-create、opencontext-iterate 这些斜杠命令或对应 Skills。OpenContext 不会替代已有的编码 Agent；如果 Codex、Claude 或 OpenCode 本身不能正常启动，不能把问题归咎于上下文层，也不能把一个能启动的 MCP 配置误判为完整接入。

第二关：用固定样本验收跨会话记忆

先建立一个刻意设计、容易核对的上下文，而不是直接把整个工作目录塞进去。可以使用 CLI 创建目录和文档：

oc folder create decisions -d "经过确认的工程决策"
oc doc create decisions api-timeout.md -d "API 超时约定"
oc doc ls decisions
oc folder ls

在 api-timeout.md 中写入三条带有唯一关键词的事实：例如“订单服务外部请求超时为 3 秒”“超时后只重试一次”“日志必须包含 request_id”。第一会话只让 Agent 读取并解释这些约定；结束前要求它通过 opencontext-iterate 或等价的写回流程记录确认内容。关闭会话后重新开启第二会话，换一个项目目录，提出一个不直接重复原文的问题，例如“这个项目调用订单服务时，超时和日志有什么约束”。

通过条件不是 Agent 恰好答对，而是它能引用正确的三条事实，并说明来源属于全局上下文还是当前仓库。如果它回答“通常可以重试三次”，却没有指出这是未知信息，验收应判失败。为了排除模型偶然记忆，测试样本里的关键词可以使用不自然但唯一的代号；第二次会话不能粘贴第一会话的聊天内容。

第三关：验证跨仓库共享，但防止串库

README 宣称全局上下文库可以跨项目使用，这正是最有价值、也最容易出现边界错误的地方。准备两个临时仓库：shop-api 约定 REST 接口使用 snake_case，shop-web 约定前端状态字段使用 camelCase；另外各写一条只属于自己的部署说明。进入第一个仓库，用 oc doc create 或 Agent 的创建能力保存后端约定，再到第二个仓库执行搜索。

验收分为正向和反向两组。正向问题应找到属于当前任务的文档；反向问题要确认不会把后端部署结论当成前端约定。可以用 oc search "snake_case" 和 oc search "camelCase" 直接检查搜索结果，再用 oc context manifest <folder> 生成指定文件列表，确认 Agent 读取的是预期目录。若两个仓库都有同名文档，必须检查结果中是否有足够的标题、文件夹或描述帮助区分；区分不了时，不应继续扩大自动写回权限，而应改进命名和目录结构。

这一步还要测“项目本地事实”和“个人通用原则”的优先级。把代码风格这类通用原则放进一个全局文件，把数据库连接方式这类仓库事实放进另一个项目文件，分别询问 Agent。合格答案应主动标注适用范围，而不是把所有内容拼成一套适用于任何仓库的规则。

第四关：把检索准确性拆成命中、排序和拒答

oc search "query" 是官方列出的检索入口，但“能搜到”远远不够。建立至少十条小样本，其中包含五条应命中的问题、三条相近但应排除的内容、两条知识库中不存在的问题。每条样本写下期望文档、可接受的同义词和不可接受的混淆文档。

先测精确命中：用文档中的唯一短语搜索，结果应包含目标文档。再测自然语言：用“外部调用失败时怎么处理”替代“重试一次”，观察是否仍能找到正确决策。再测同名干扰：在不同文件夹放入两个“部署”文档，要求 Agent 说明它选择了哪一个以及为什么。最后测未知问题：询问库中没有记录的团队约定，合格表现不是编造答案，而是明确说没有找到，并请求补充上下文。

不要只看 Agent 的最终回复，保留搜索词、返回文档、引用片段和最终结论。若 GUI、MCP 和 CLI 的结果不一致，也要分别记录。官方 README 将 MCP Server 定义为供 Cursor、Claude Code、Codex 等调用 OpenContext 工具的组件；因此 MCP 可用不代表检索策略天然正确，工具返回结果仍需人工抽样核对。

第五关：验收写回质量，而不是“创建了一个文件”

OpenContext 的价值闭环是“先加载历史再行动，交付后再持久化”。写回测试应该安排在一次真实但低风险的任务后：让 Agent 修改一个小功能，要求它总结采用的方案、未解决问题、验证命令和后续风险。再检查它是否使用了 opencontext-create 或 opencontext-iterate 的正确语义，而不是把临时聊天草稿原样倾倒进知识库。

一份合格的写回至少包括：明确标题、适用范围、日期或版本、结论、证据、待确认事项和来源。它不应混入 API 密钥、个人访问令牌、完整环境变量、客户数据或未经确认的推测。重复运行相同的迭代动作时，要观察是否产生无意义的重复文档；如果会重复创建，就应改为更新既有文档或在流程中加入人工确认。

通过 CLI 复核结果：用 oc doc ls <folder> 检查文件是否出现，用 oc context manifest <folder> 检查它是否被纳入可读文件列表，再用 oc search 搜回刚写入的唯一关键词。只有“生成成功、能被列出、能被检索、内容可审查”四项同时成立，才算写回闭环通过。

第六关：配置范围和副作用要单独签字

OpenContext 同时有 CLI、MCP、Skills、斜杠命令、桌面应用和本地 Web UI。组件多并不等于应该全部启用。开发者只需要命令行和 MCP，就不必为了验证安装桌面应用；需要人工浏览和编辑时，再使用桌面应用或 oc ui。README 明确列出 oc mcp 用来启动 MCP Server，oc ui 用来启动本地 Web UI，验收时要确认启动的服务、进程生命周期和关闭方式符合本机管理习惯。

配置范围至少检查四件事：oc init 是否只为选择的工具安装集成；当前项目是否只是使用全局 contexts 而没有复制个人知识文件；MCP 客户端是否只暴露 OpenContext 必需的工具；团队成员的配置目录是否因环境变量不同而指向错误位置。可以在临时用户目录或测试账号中先跑一遍，再进入主工作环境。

把“读、搜、创建、迭代”分别验收。读和搜风险较低；创建和迭代会改变持久化数据，必须确认目标目录、文件名、描述和覆盖行为。涉及删除、批量改写或外部同步的动作，不应因为 MCP 能调用就自动放行。

第七关：建立隐私边界，别把“本地”理解成“无需治理”

README 把 OpenContext 描述为个人上下文存储，并说明 Web UI 可在本地浏览和编辑；这不等于所有进入上下文的资料都天然安全。最稳妥的做法是建立允许清单，而不是先全盘导入。允许清单可以包括公开架构决策、团队确认的开发规范和脱敏后的故障复盘；排除清单应包括 .env、密钥目录、客户导出数据、私有证书、浏览器会话文件和未经授权的聊天记录。

用一份包含假令牌的测试文件验证边界：确认它没有被复制到 contexts 文档，没有出现在 Agent 摘要中，也没有被写回新文档。再检查 MCP、桌面应用和 Web UI 三条入口是否都能看到同样的范围。不要把“搜索不到”当成绝对删除证明；还要检查生成的 manifest、日志和备份目录。真实凭据不应被用于这项测试，测试令牌也应在完成后销毁。

如果 OpenContext 与已有 Agent CLI 共用用户级配置，隐私评估还要覆盖这些配置的访问范围。记录哪些人能访问本机账户、哪些进程可以调用 MCP，以及上下文文件是否进入备份、同步盘或团队共享目录。个人知识库和团队知识库应分开命名、分开权限和分开备份，不能因为“跨仓库”方便就默认所有仓库共享所有内容。

最终验收表：六个问题全部回答“是”

  • 跨会话：关闭原会话后，新会话能从唯一测试样本中找到正确背景，并能区分已知与未知信息。
  • 跨仓库：两个项目的同名文档不会互相污染，项目事实和通用原则的适用范围清楚。
  • 检索：精确词、自然语言、同名干扰和未知问题都有记录，Agent 不会用猜测填补空白。
  • 写回：新知识能创建或迭代到正确位置，能被列出、生成 manifest 并再次搜回，内容有证据和边界。
  • 配置：只启用了实际需要的工具和入口，MCP、Skills、命令路径与环境变量一致，副作用可回滚。
  • 隐私：允许与排除清单已验证，假令牌没有进入知识库、摘要、manifest 或日志，访问范围有人负责。

如果其中任何一项失败，正确结论是“安装完成，接入未验收”，而不是继续增加上下文文件。先修正目录、命名、检索样本或写回规则，再重复同一组测试。OpenContext 的收益不在于让 Agent 永远记住一切，而在于让重要背景可被明确保存、按范围找到、在需要时引用，并且在错误发生时能够追查。把这条链路跑通，才算从 oc init 迈到了真正可用的 Agent 工作流。

官方参考：OpenContext GitHub 仓库、官方 README。命令、支持的客户端与配置路径可能随版本变化，实际验收应以当前仓库文档和本机生成结果为准。