企业官网建设流程全解析

• Agent 记忆
• 人工智能
• AI 应用
• MCP 服务
• CLI
• 知识管理

OKF Agent Memory是一款为 AI 编程 Agent 打造的 Git 原生持久记忆工具，它将知识按project（项目）、vendor（供应商）、user（用户）、system（系统）四层作用域进行分层存储，并实现了 300 微秒级的内存 BM25 搜索与嵌入式 MCP 服务器。本文带你深度解析这四层记忆作用域的优先级、遮蔽规则与日常使用技巧，帮助新手快速掌握这套知识分层机制。

为什么需要 4 层记忆作用域？🤔

AI Agent 的知识来源各不相同：有的只属于当前项目，有的是团队共享的行业规范，有的存你个人偏好，还有的是企业级强制标准。如果混在一起，Agent 就会"分不清谁说了算"。

OKF Agent Memory 的答案是：四个确定性作用域 + 严格的优先级遮蔽。高层级知识会自动覆盖（shadow）低层级中相同 ID 的概念，保证"本地项目决策永远优先于外部依赖和机器基线"。

4层作用域一览：优先级与存储位置

📌 优先级常量定义在 pkg/okf/scope.go，完整的分层设计决策记录在 knowledge/architecture/registry-and-vendor-layering.md。

各层"装什么"最合理

• 项目层：架构决策、命名约定、runbook——只对本仓库有效的知识；
• 供应商层：框架最佳实践包（如nextjs-15、@org/security-rules），版本锁定在okf.lock中；
• 用户层：你的编码风格偏好、跨项目通用笔记，跟着你的机器走；
• 系统层：安全合规策略、组织级基础设施基线，通常由运维统一维护。

遮蔽机制（Shadowing）：高层级如何"接管"低层级

这是整个分层机制的核心不变量（invariant）：

project(100) 严格遮蔽 vendor(70)，vendor 遮蔽 user(50)，user 遮蔽 system(10)——针对相同相对 ID 的概念。

举个例子：如果本地knowledge/里已有decisions/auth这个概念，而供应商包和用户层中也存在同名decisions/auth，搜索时只有项目层的那份会出现在结果里，另外两份被自动屏蔽，从根源上避免了 Agent 引用到"过期的外部版本"。

排序规则同样确定性强（见 pkg/okf/scope.go）：

1. 先比层级优先级（100 → 70 → 50 → 10）；
2. 同层级内再比BM25 相关度分数；
3. 分数相同时按概念 ID 字典序，保证每次结果完全一致。

另外，供应商层的多个包会被合并成一个"组合语料库"再做 BM25 统计，确保文档频率在整个 vendor 层统一计算，而不是按包割裂打分。

实战：用--scope参数搜索各层知识 🔍

okf search支持--scope <all|project|bundle|vendor|user|system>参数（默认all），可精准过滤到某一层：

okf search "routing" --scope vendor # 只搜供应商层 okf search "auth" --scope project # 只搜本地项目记忆

而okf show支持作用域引用，直接跨层查看任意一个概念的完整元数据与正文：

okf show decisions/auth # 本地项目概念 okf show @nextjs-15/decisions/routing # 供应商概念（@ 前缀） okf show user:preferences/style # 用户层概念 okf show system:corp/policies # 系统层概念

💡 命令参数细节可参考 docs/guides/CLI.md，日常速查表见 docs/guides/GETTING_STARTED.md。

跨作用域链接与 URI 体系

四层知识之间可以互相引用，且解析规则无歧义：

所有引用都有规范的okf://统一资源名（URN），例如okf://@nextjs-15/decisions/routing、okf://user/guidelines/style。URI 解析逻辑与测试用例分别在 pkg/okf/scope.go 和 pkg/okf/scope_test.go 中。

一个贴心的细节：okf validate --strict会把这些外部引用全部识别为"外部目标"，不会产生断链报错，也不会误判为孤儿概念——你可以放心地在项目知识中引用供应商和用户层的文档。

供应商层如何安装与维护？

供应商知识包通过去中心化 Registry 分发，常用命令：

okf pull nextjs-15 # 拉取并锁定到 okf.lock okf restore # 按锁文件恢复全部依赖 okf vendor list # 查看已安装的供应商包 okf vendor remove nextjs-15 # 移除并清理锁文件

拉取的包会先做 SHA-256 完整性校验和严格验证，任何校验失败都会原子回滚，保证.okf/vendor/目录永远处于可信状态。

小结：记住这三点就够了 ✅

1. 四层分工：项目层管"本仓库真理"，供应商层管"外部最佳实践"，用户层管"个人偏好"，系统层管"企业基线"；
2. 优先级即真理：100 → 70 → 50 → 10，高层级相同 ID 的知识永远遮蔽低层级；
3. 一切可验证：纯文本 + Git 版本管理，用--scope参数即可精确控制搜索范围。

想继续深入了解分层设计背后的架构决策，推荐阅读 knowledge/architecture/registry-and-vendor-layering.md 与 knowledge/architecture/layers.md。

• Agent 记忆
• 人工智能
• AI 应用
• MCP 服务
• CLI
• 知识管理