okf-mcp

okf-mcp

okf-mcp 从已经保存知识的系统中发布 Open Knowledge Format v0.2，并将结果提供给 Agent。它是一个本地优先的消费者、验证器、图索引、CLI 和 MCP 服务。

难点在于如何安全地写入目录。配置好的生产者会读取外部来源并返回候选包；okf-mcp 会验证该包，然后在所有权清单下发布，清单会准确记录它拥有的文件。手工编写的内容绝不会被接管，未发生变化的来源不会触发任何重写，生产者的输出也不会逸出其所属的包。@mfdaves/okf-postgres 通过这种方式读取 PostgreSQL 目录，不会读取任何表行。

读取是常规部分。它会使用由 Markdown 文件和 YAML frontmatter 构成的 OKF 包目录。可选的工作区模式可以联合多个包。概念通过 CLI 命令以及 MCP 资源和工具提供，支持验证、结构化搜索、图导航、来源检查和基于提案的编写。

核心有意不依赖数据库、嵌入向量、构建步骤或托管服务。它使用 js-yaml 安全处理 YAML，使用 CommonMark 处理 Markdown 结构，使用 MiniSearch 进行内存中的 BM25+ 文本检索，并使用官方的 Model Context Protocol TypeScript SDK v2 提供 stdio MCP。Local root 模式不会发起网络调用。可选的远程加载会从 GitHub 获取公开的 Markdown 概念，以及仅由这些概念明确引用的惰性资源。v0.2 的计算支持中没有任何内容会执行代码或证明收据有效。

OKF v0.2 支持与扩展

OKF v0.2 有意规定的是一种可移植的文件格式，而非服务或查询运行时。okf-mcp 明确保持这一界限：

区域	官方 OKF v0.2	okf-mcp 的行为
包和标识	Markdown 文件目录树；Concept ID 是相对于包的路径，不含 .md	--root 直接映射到一个包；okf:// 是可选的工作区定位符，不是可移植的 Concept ID
概念元数据	必需的 type；建议使用 title、description、resource 和 tags；允许未知键	保留扩展字段和未知类型，同时分别报告规范符合性和工作区策略
来源和生命周期	sources、usage_window、generated、verified、status 和 stale_after	对这些字段进行规范化处理，以支持搜索、来源遍历、信任层级和确定性新鲜度检查
引用	Markdown 链接，以及路径值字段 resource、sources[].resource、computation、executor.resource 和 attester.resource	构建图边和有界的惰性资源快照，不执行或隐式获取所引用的代码
经证明的计算	定义契约字段和说明性的使用者流程，同时将运行时线协议和证明者打包方式留待后续规定	静态检查契约和摘要，检查声明的参数和收据字段名称，绝不执行代码或声称已完成证明
v0.1 兼容性	当整个 generated 映射不存在时，允许回退到 timestamp；当 sources 键不存在时，允许回退到 # Citations	可使用这两种形式，并添加仅用于审核的迁移检查和提案

以下内容是 okf-mcp 的扩展，并非该格式的要求：

• CLI、MCP 和 HTTP 接口；内存中的搜索和图视图
• 可选的多包 okf.project.yaml 工作区和类型化的 relations
• 兼容性 id、aliases 和 okf:// 定位符
• 通过提案编写内容，并明确接受提案
• 有界的 GitHub 远程加载和显式映射的固定 Git 源
• 生成器插件，以及更严格的可选项目策略，例如 strictLinks

安装并运行

需要 Node 22 或更高版本。

从 GitHub 发布版本安装：

git clone --branch v0.12.0-rc.1 https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
node bin/okf-mcp.js --root ./path/to/okf validate

固定已发布的版本，以便可复现地使用：

npx -y @mfdaves/[email protected] --version
npx -y @mfdaves/[email protected] --root ./path/to/okf validate

进行持久安装：

npm install --global @mfdaves/[email protected]

okf --version
okf --root ./path/to/okf validate
okf-mcp --root ./path/to/okf mcp

从当前源代码分支运行：

git clone https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
npm test
node bin/okf-mcp.js --version

--root 接受一个本地 OKF bundle 目录，是单个 bundle 推荐使用的 okf-mcp 接口。每个概念的可移植标识是该根目录内不带扩展名的路径。

--bundle 接受路径或 id=path。为保持兼容，仍支持多个标志。--project 及其 bundles: 列表是可选的 okf-mcp 联邦／编写扩展，不属于 OKF v0.2。

--remote-bundle 接受 id=https://github.com/<owner>/<repo>/tree/<ref>/<path>。它会先获取公开的 Markdown，然后仅获取标准 v0.2 资源字段明确指定的 bundle 本地文件。远程内容保持只读且不执行。

--inspect 会打印精简的图摘要并退出。如果未指定 --inspect，也未指定明确命令，进程将启动 stdio MCP 服务。

安装后，该软件包会同时提供 okf 和 okf-mcp 二进制文件。如果没有明确指定来源，CLI 会先查找最近的根目录 index.md（其中声明了 okf_version）；最近项目发现仍作为兼容性回退机制。

CLI 退出状态码为：成功时 0，验证或操作失败时 1，用法无效时 2。不接受未知选项。

随附的 OKF 参考资料

此仓库发布了一个自描述的 OKF bundle，涵盖产品、运行时边界、接口、编写工作流和安全策略。其可移植入口 Concept ID 为 overview/okf-mcp；okf://okf-mcp/overview/okf-mcp 仍是工作区／MCP 资源定位符。

从代码检出目录或已安装的软件包验证并查询随附的参考资料：

okf --root okf/okf-mcp validate
okf --root okf/okf-mcp search "proposal"
okf --root okf/okf-mcp concept overview/okf-mcp

直接从当前源代码分支加载参考 bundle：

okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/main/okf/okf-mcp --inspect

已发布的 v0.8.0 标签保留了原始的 okf/bundles/okf-mcp 路径。较短的 okf/okf-mcp 路径是在 未发布的 0.8.1 维护检查点中准备的，并随 v0.9.0 一同发布；不可变的 v0.8.0 发布版本保持不变。

@mfdaves/okf-mcp npm 软件包同时包含 okf.project.yaml 和 完整的参考 bundle。

可选的多 Bundle 项目配置

仅当单个进程需要联合多个根目录、配置生成器或外部元数据生产器，或强制执行项目级关系词汇表时，才使用 okf.project.yaml：

project: Example
strictLinks: false
bundles:
  - id: app
    root: okf/bundles/app
    include: ["**/*.md"]
    exclude: ["archive/**"]
  - id: data
    root: okf/bundles/data
  - id: company-database
    root: okf/company-database
relationTypes:
  - deployed_by
remoteBundles:
  - id: shared
    url: https://github.com/example/okf-atlas/tree/main/bundles/shared
    include: ["public/**"]
    exclude: ["drafts/**"]
plugins:
  - name: docs
    type: filesystem
    root: docs
    output: okf/bundles/app/generated/docs
    bundle: app
producers:
  - name: main-database
    type: postgresql
    package: "@mfdaves/okf-postgres"
    bundle: company-database
    config:
      connectionEnv: DATABASE_URL
      source: company-db
      schemas: [public]
      includeIndexes: true

运行项目命令：

okf --project okf.project.yaml validate
okf --project okf.project.yaml search "orders"
okf --project okf.project.yaml graph mermaid
okf --project okf.project.yaml generate
okf --project okf.project.yaml producer list
okf --project okf.project.yaml producer preview main-database
okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
okf --project okf.project.yaml mcp
okf --project okf.project.yaml mcp --authoring
okf --project okf.project.yaml mcp --allow-remote-tool
OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve
okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect

命令：

• mcp
• validate
• graph [json|dot|mermaid]
• search <query>
• concept <concept-id-or-locator>
• neighbors <concept-id-or-locator>
• paths <from> <to>
• provenance <uri>
• edge-kinds
• computation inspect|prepare|check-receipt
• asset <okf-asset-uri>
• source <concept-id-or-locator> <source-id>
• migrate check|preview
• generate
• producer list|preview|run
• serve

外部元数据生产器

生产器独立于内置的 plugins: 生成器。生产器从外部来源读取元数据，并返回一个内存中的候选 OKF bundle；okf-mcp 会验证并发布该候选 bundle。将每个生产器软件包安装到项目旁边，然后在可信项目配置中将其准确的裸软件包名称加入允许列表。MCP 调用方可以选择已配置的生产器，但不能替换其软件包、配置、凭据、查询、bundle 或输出路径。

软件包必须安装在属于该项目的 node_modules 目录下，并通过其准确的裸名称解析。普通的注册表安装、npm 工作区、npm link 以及 pnpm 等基于存储的布局均满足此要求；配置中的路径则不满足。 该包必须导出带版本的 okfProducer API。Producer API v1 面向 OKF v0.2，并将 validateConfig() 与无副作用的目标生成分开。候选概念必须包含原生的 generated 和非空的 sources 溯源信息。主机将拒绝不安全的路径、格式错误的概念、未解析的链接或类型化关系、未归属的文件冲突、本地修改过的受管理文件、输出中的机密值，以及任何会导致整个项目无效的候选内容。

两个接口运行相同的主机。使用 CLI 执行计划刷新：

okf --project okf.project.yaml producer preview main-database
okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh

当候选内容无效时，producer preview 以 1 退出；未发布任何内容时，producer run 以 1 退出。二者都会打印与 MCP 工具返回内容相同的回执。

对于已配置的项目，MCP 会提供：

• okf_list_producers：列出配置，不加载包代码，也不读取源数据
• okf_preview_producer：读取源元数据，并返回经过验证但不会写入的差异
• okf_run_producer：在共享写入队列下重新生成，并通过版本检查和回滚机制发布；仅当使用 --write 和符合实际情况的 --actor 时可用，--actor 须采用 human:<id>、process:<id> 或 provider/model 语法

预览和运行仅接受已配置的 producer 名称及可选的回执详情。回执包含有界的数值型源对象摘要和发布差异计数。发布记录会将所属的相对路径和 SHA-256 摘要写入 bundle 本地的 .okf-producer.json。只有由先前清单拥有且未被修改的路径才能更新或移除；手动编写的内容绝不会被隐式接管。清单不包含 producer 配置、凭据或连接详情。

以下两条规则可确保受管理的 bundle 在重复运行时保持稳定：

• Producer 每次运行都会重新写入 generated.at。主机会在比较候选内容与已发布文件时忽略该时间戳，因此，如果源数据未发生变化，结果会报告为 unchanged，且不改动字节内容、时间戳或清单。因此，发布差异计数反映的是源数据变化，而非运行情况。
• 清单条目本身并不构成删除内容的授权。主机将重写或移除的任何文件本身都必须带有 generated 溯源信息，这样，受损、手动合并或伪造的清单就无法让 producer 删除手动编写的内容。

因过期内容删除而变空的目录，会随其中最后一个受管理文件一并移除。

@mfdaves/okf-postgres 是 PostgreSQL 实现。其平均用途 v1 涵盖数据库、架构、表/视图、列、键、检查约束、枚举、索引和描述元数据，不读取表行。将连接字符串保存在由 connectionEnv 指定的环境变量中；不要在 YAML 中放置连接字符串。

serve 选项：

• --host <host>：绑定主机，默认值为 127.0.0.1
• --port <port>：绑定端口，默认值为 8765
• --write-token <token>：写入端点的 bearer 令牌；默认使用 OKF_WRITE_TOKEN
• --proposal-root <path>：提案 JSON 目录；默认位于所选本地根目录或项目下的 .okf-proposals

提案属于存储状态，而非派生缓存，因此提案目录绝不会自动清理。使用 --git-commit 启动的服务在工作树中存在未跟踪文件时会拒绝发布，因此该目录必须被 Git 忽略：将 .okf-proposals/ 添加到 .gitignore（本仓库即如此），或使用 --proposal-root 指定 Git 已忽略的目录。在项目模式下，提案根目录必须位于项目根目录内。

MCP 客户端配置

以下基于 npm 的示例使用当前已发布版本。检出源代码后，可以使用相同参数调用其可执行文件 bin/okf-mcp.js。

客户端配置示例：

{
  "mcpServers": {
    "okf": {
      "command": "npx",
      "args": [
        "-y",
        "@mfdaves/[email protected]",
        "--root",
        "/absolute/path/to/okf",
        "mcp"
      ]
    }
  }
}

项目配置模式，提供只读项目辅助工具，但不支持提案变更：

{
  "mcpServers": {
    "okf": {
      "command": "npx",
      "args": [
        "-y",
        "@mfdaves/[email protected]",
        "--project",
        "/absolute/path/to/repo/okf.project.yaml",
        "mcp"
      ]
    }
  }
}

添加 --authoring 以启用提案的创建、接受和拒绝。若要缩小直接写入范围，可添加 --write --actor <actor>，以启用只读的 okf_validate_changes 和经过验证的批量工具 okf_apply_changes；如果目录位于干净的 Git 工作树中，添加 --git-commit 可在每个批次成功后提交。添加 --allow-remote-tool，允许 MCP 客户端在运行时加载任意受支持的公共远程工具包。未启用此运行时加载标志时，仍可读取已配置的远程工具包。

stdio 服务使用 @modelcontextprotocol/server v2。它支持现代 2026-07-28 MCP 修订版，以及 SDK 为 2025 年客户端提供的兼容路径， 包括 2025-11-25。协议协商、分帧、资源分发、工具分发以及通告模式验证均由 SDK 负责。

对于已知工具的预期失败，例如概念缺失、工具包只读、远程获取失败、参数无效或提案冲突，都会作为 MCP 工具结果返回，并设置 isError: true。SDK 分发会拒绝调用未启用的工具。意外的实现错误会被屏蔽，不会暴露内部详情。

MCP 注册表元数据

server.json 将 npm 包描述为 stdio 服务 io.github.mfdaves/okf-mcp。支持注册表的客户端应提示用户输入绝对 OKF 根路径，通过 --root 传入，并附加固定的 mcp 命令。

概念标识与扩展

概念 ID 是移除 .md 后的工具包相对 Markdown 路径。这个不带扩展名的路径是可移植的 OKF 标识。okf-mcp 还提供一个限定于工作区的兼容定位符：

okf://<bundle-id>/<extensionless-concept-id>

原有的 .md URI 和有效的自定义 id 仍可用作兼容性查找别名。只有当裸概念 ID 在所有已加载工具包中唯一时，才能解析该 ID。对于独立的聚合目录，如果 URI 格式的可移植路径（例如 okf://services/queue.md）在全局范围内唯一，且 services 不是已加载的工具包 ID，也可以解析。精确的规范 URI 始终优先；已知工具包中的未匹配项或有歧义的可移植路径仍无法解析。保留的 index.md 和 log.md 资源会保留其文件名，因为它们不是概念。

下文中的 id、aliases 和类型化的 relations 字段是 okf-mcp 扩展。标准 v0.2 标识仍由路径派生：

---
id: okf://app/routes/order-status
type: API Route
title: Order Status Route
description: Serves order status state.
aliases: [order-status]
tags: [api, orders]
relations:
  - type: consumes
    target: okf://data/tables/order_status
  - type: configured_by
    target: repo://src/routes/order-status.js
---

# Order Status Route

新内容应使用普通的相对路径或工具包根目录下的 Markdown 路径来编写内部链接和扩展关系目标。仍支持现有的 okf:// 目标；repo:// 等非 OKF 方案会保留为不透明的兼容性引用。

固定版本的 Git 源

代码知识可以存放在代码仓库之外，而无需记录特定机器的路径。将标准 sources 条目指向 Git Repository 概念，并添加下方的 okf-mcp git 扩展：

sources:
  - id: implementation
    resource: /repositories/application.md
    git:
      revision: 0123456789abcdef0123456789abcdef01234567
      path: src/application.js
      lines: { from: 10, to: 30 }

仅在本地进程配置中映射仓库概念：

okf --root /path/to/catalog \
  --repo repositories/application=/work/application \
  source architecture/application implementation

read_git_source 和 source CLI 命令会从映射的 Git 对象数据库中读取固定版本的 blob。它们不会读取有未提交更改的工作树，也不会执行获取操作。未配置映射或未固定修订版本的源仍会显示，但不可用。仓库映射可以指向普通检出目录、裸仓库或挂载路径；凭据和本地路径会保留在 OKF 工具包之外。

工具

• list_bundles
• list_concepts
• get_concept
• search_concepts
• list_types
• list_tags
• list_relation_types
• list_edge_kinds
• get_provenance
• inspect_attested_computation
• read_bundle_asset
• read_git_source
• prepare_attested_computation
• check_computation_receipt
• check_v02_migration
• load_remote_bundle
• list_remote_bundles
• okf_validate_concept
• okf_suggest_concept_path
• okf_propose_concept
• okf_propose_update
• okf_propose_attested_computation
• okf_propose_v02_migration
• okf_list_proposals
• okf_get_proposal
• okf_accept_proposal
• okf_reject_proposal
• okf_validate_changes
• okf_apply_changes
• okf_list_producers
• okf_preview_producer
• okf_run_producer
• get_graph
• get_neighbors
• get_subgraph
• find_paths
• graph_summary
• validate_bundle
• validate_project
• export_graph

大多数 MCP 工具对当前索引仅提供只读访问。load_remote_bundle 只会通过获取公开的 GitHub 树来修改服务的内存索引，不会写入文件。概念列表和搜索默认返回精简摘要；需要导航元数据、信号、排序信息或片段时，请传入 detail: "full"。即使多个平行边类型连接相同概念，关系路径也会按节点序列去重。

每个 MCP 工具都包含特定用途的描述、输入参数说明，以及涵盖只读行为、破坏性行为、幂等性和外部访问的标准注释。

执行前会根据公布的输入架构验证工具参数。未经支持的字段、缺少的必填值、错误的基本类型以及超出范围的整数都会被拒绝，不会进行强制转换。未知或已禁用的工具名称仍会导致协议级无效参数错误。

工具发现和直接调用使用相同的能力检查：

模式	常规提案	直接实时写入	计算提案	运行时远程加载
默认	已禁用	已禁用	已禁用	已禁用
--authoring	已启用	已禁用	已禁用	已禁用
--write --actor openai/gpt-5.6	已禁用	已启用	已禁用	已禁用
--authoring --allow-computation-authoring	已启用	已禁用	已启用	已禁用
--allow-remote-tool	已禁用	已禁用	已禁用	已启用

显式指定本地根目录或项目工作区后，可使用概念验证、路径建议和提案检查辅助工具。提案变更工具需要 --authoring。直接实时工具则需要 --write，并且需要使用 human:<id>、process:<id> 或 provider/model 语法提供真实的操作者标识。在普通单根模式下，调用方可省略 bundle；只有在多个项目根目录中进行选择时才需要它。远程根目录保持只读。

通用概念工具无法创建或更改 Attested Computation 合约。okf_propose_attested_computation 还需要 --allow-computation-authoring，并会为该概念及一个可选的外部计算文件创建一个协调审查提案。

实时概念创作

只有在 MCP 客户端／用户审批边界足以进行审查时，才使用直接写入功能启动服务：

okf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp

Agent 会看到一个只读批量验证工具和一个具有破坏性的应用工具。它提供结构化概念字段，而不是 YAML；OKF 会序列化为兼容的 Markdown frontmatter，并为整个批次写入配置的 generated.by 和一个 generated.at 时间戳。

{
  "name": "okf_apply_changes",
  "arguments": {
    "message": "docs(okf): document order creation",
    "changes": [
      {
        "op": "create",
        "type": "MCP Tool",
        "title": "Create Order",
        "body": "# Create Order\n\nCreates a validated order.",
        "tags": ["orders", "mcp"],
        "sources": ["/repositories/orders-service.md"],
        "relations": [
          { "type": "related_to", "target": "/workflows/order-creation.md" }
        ]
      }
    ]
  }
}

创建路径为可选项。服务首先根据请求前缀内现有同类型概念的强主导目录惯例确定路径，然后回退到确定性的类型／标题 slug。okf_suggest_concept_path 会报告策略、依据、路径可用性以及同类型／标题匹配项，避免将文件名可用误认为不存在安全的重复项。更新通过现有的 uri 标识；过期定位符会返回数量有限的可能替代项，而标量字段会替换现有值，tags、sources 和 relations 则使用显式的 add／remove 补丁。metadata 用于承载扩展 frontmatter，但不能覆盖身份、生成、集合或计算字段。更新期间路径和 URI 不可变：移动概念会改变其可移植身份，因此仍是单独且有意不支持的操作。

每个包含 1–100 项的批次都会作为一个未来图进行验证，因此同批创建的概念可以相互引用，并且会检测创建与更新之间的同类型／标题冲突。使用完整的预期批次调用 okf_validate_changes，即可获得不会写入文件的检查时预览。验证和应用共用同一规划器；由于修订和 Git 状态可能在预览后发生变化，应用会在写入队列中重新执行所有检查。精简回执是 v0.8 的默认格式；传入 detail: "full" 可使用 v0.7 的规划布局。效果会公开结构化关系，并将服务管理的生成来源与实质性的 changedFields 分开。

只有在所有候选项均有效、修订检查仍然匹配，且所有目标都位于同一个可写入包内时，服务才会写入文件。由进程生成的文档、生成器输出目录、.git/** 等隐藏／控制平面路径、保留文件以及 Attested Computation 契约均不是实时写入目标。回滚会在每次还原前检查修订，并将检测到的替换报告为部分 rollback_conflict。此保护在文档所述的单一外部写入方要求下尽力而为；它不保证跨进程比较并交换。

将 --git-commit 添加为服务策略，即可为每个成功批次创建一个提交。检测到 Git 工作树时，必须确保其完全干净且已配置身份信息，才能发布。活动 Git 过滤器属性以及 assume-unchanged／skip-worktree 索引标志会阻止操作，以免验证执行已配置的过滤器或忽略隐藏的用户更改；禁用替换对象解析，以免隐藏的替换历史更改父树。服务会根据已验证的 Markdown 字节构建隔离索引，使用 commit-tree 创建精确的树，通过比较并交换 ref 更新发布该树，随后仅同步受影响的普通索引路径，并且绝不会推送。并发写入的无关暂存条目不会进入提交。若提交失败且结果明确，则匹配的有效文件会保留为仅在工作树中的更改；若 ref 更新超时且结果不明确，则报告为未知，除非能够证明生成的提交树。非 Git 目录仍按常规方式写入。每个响应都会明确说明仓库根目录、提交状态、索引状态、目标字节状态和持久化边界。

写入策略

写入策略会限制各参与者通过实时批次和提案可以写入的内容。这是受信任的配置：在 okf.project.yaml 中将其声明为 writePolicy，或在配合 --root 使用 --write 或 --authoring 时传入 --policy <file>（内容为相同映射的 YAML 文件）。工具和 HTTP 参数无法指定、替换或放宽策略。

writePolicy:
  defaultEffect: deny          # allow (default) or deny when no rule decides
  rules:
    - name: humans
      actors: ["human:*"]
    - name: nightly-seo
      actors: ["process:nightly-*", "openai/*"]
      bundles: ["customers-*"]
      paths: ["findings/**"]
      types: ["SEO Finding"]
      requiredFields: ["sources", "stale_after"]
      defaultStatus: draft     # stamped on creates that set no status
      maxConceptsPerBatch: 20
    - name: no-drafts
      actors: ["**"]
      paths: ["drafts/**"]
      effect: deny
  applyToProducers: false      # true also judges producer runs

对于批次中的每个概念，第一个满足以下条件的规则将决定处理结果：actors 与配置的 --actor 匹配，且其他选择器（如果存在）也匹配。effect 默认值为 allow；requiredFields、defaultStatus 和 maxConceptsPerBatch 仅适用于允许规则。模式使用固定的 glob 子集：* 匹配单个片段内的内容，作为完整片段的 ** 匹配任意深度，另有字面值片段。模式绝不会被编译为正则表达式；加载策略时会拒绝绝对路径、空片段、. 和 .. 片段。格式错误的策略属于项目错误，因此不会启动可写服务。策略只检查批次创建或更新的概念；不会追溯验证现有内容。

违规信息采用结构化格式：{ code: "policy_violation", rule, reason, field?, path?, bundleId?, uri?, limit?, count? }，其中 rule 为规则的 name，若无则为其索引；如果由 defaultEffect 决定，则为 null。reason 的值为 actor_denied、bundle_denied、path_denied、type_denied、missing_required_field 或 batch_too_large。okf_validate_changes 以只读方式在 policyViolations 和 layer: "policy" 诊断信息中报告这些违规；okf_apply_changes 会在暂存或触及任何文件之前拒绝此类批次，并将状态设为 rejected。只有配置了策略时，回执才会包含 policyViolations；消息会列出规则、路径和 URI，不会包含目录文本。

适用范围。实时批次（okf_validate_changes、okf_apply_changes）根据 --actor 进行检查。提案会接受两次检查。当 okf_propose_concept、okf_propose_update、okf_propose_attested_computation、okf_propose_v02_migration（在存储任何内容之前检查每个子更新以及 index.md 版本声明）或其 HTTP 等效操作即将存储内容时，会根据提案者的参与者（--actor，--authoring 也接受此参数）进行检查；被拒绝的提案会返回 created: false 和 policyViolations，且不会被存储。当 okf_accept_proposal 或 POST /v1/proposals/<id>/accept 即将写入内容时，会根据提案记录的参与者（proposedBy）进行检查；如果没有记录，则使用接受提案者的参与者。被拒绝时，会在写入任何文件之前返回 accepted: false；如果接受的创建操作匹配某条规则，且该规则提供了 defaultStatus，则会以该状态发布。没有参与者的写入（HTTP 调用，或在配置参与者或策略之前存储的提案）会按字面参与者 unknown 进行检查：* 和 ** 可以匹配它，规则也可以直接指定它。因此，除非接受提案的服务配置了参与者，否则旧提案在接受时会被视为 unknown。okf serve 从 okf.project.yaml 获取策略；也可在配合 --root 使用 --authoring 时通过 --policy <file> 指定策略。生产者以 process:<producer name> 身份发布，默认不受策略约束；设置 applyToProducers: true 后，okf_preview_producer 会以只读方式报告创建和更新的概念文件中的违规，而 okf_run_producer / producer run 会在发布之前拒绝操作。生产者输出绝不会被重写，因此 defaultStatus 不适用于生产者输出：生成的文件中必须包含必需的 status，否则运行会因 missing_required_field 被拒绝。生产者包中保留的 index.md 和 log.md 文件不受检查。

概念编写

可审查的提案工作流仍可通过使用 --authoring 启动的 MCP 工具以及 HTTP API 使用。客户端无需直接访问本地文件。

MCP 提案流程：

{
  "name": "okf_propose_concept",
  "arguments": {
    "path": "tools/create-order.md",
    "frontmatter": {
      "type": "MCP Tool",
      "title": "Create Order",
      "relations": [
        {
          "type": "related_to",
          "target": "/workflows/order-creation.md"
        }
      ]
    },
    "body": "# Create Order\n\nCreates an order through the application MCP tool.",
    "message": "Document create_order for agents."
  }
}

然后使用返回的 proposal.id 调用 okf_accept_proposal。

要更正现有概念，请使用 get_concept 读取，然后仅提议需要更改的字段：

{
  "name": "okf_propose_update",
  "arguments": {
    "uri": "okf://app/tools/create-order",
    "frontmatter": {
      "title": "Create Order Tool",
      "description": "Creates a validated order."
    },
    "removeFrontmatterKeys": ["deprecatedField"],
    "message": "Correct outdated tool metadata."
  }
}

未提供的 frontmatter 字段和未提供的正文会保留。概念 URI 无法通过更新更改。每个更新提案都会记录源文件修订版本，并在替换文件前立即再次检查；如果检测到并发更改，则会拒绝接受提案。

安全规则：

• 概念路径必须是可写知识包内安全的、非隐藏的相对 .md 路径
• 概念写入不得遍历可写知识包下的符号链接
• 仅在接受提案时创建缺失的子目录
• 不得将 index.md 和 log.md 编写为概念
• 拒绝重复路径和重复的 okf:// ID
• 更新不得更改概念身份，并会拒绝检测到的提案创建后发生的更改
• 无效 ID、无效关系类型和损坏的内部 OKF 关系均无法通过验证
• 允许使用外部关系目标，例如 repo://...
• 单个进程内的直接批处理会串行执行，并在发布前验证合并后的未来关系图
• 不同进程仍需要外部单写入者协调

HTTP API

启动 HTTP 服务：

OKF_WRITE_TOKEN=change-me okf --root /path/to/catalog serve --host 127.0.0.1 --port 8765

读取／验证端点：

• GET /health
• GET /v1/bundles
• POST /v1/concepts/validate
• POST /v1/concepts/suggest-path

提案检查和变更端点需要 Authorization: Bearer <OKF_WRITE_TOKEN>，因为待处理记录可能包含完整的候选 Markdown 和计算代码：

• GET /v1/proposals
• GET /v1/proposals/:id
• POST /v1/proposals
• POST /v1/proposals/update
• POST /v1/proposals/:id/accept
• POST /v1/proposals/:id/reject

默认的文件型提案存储会将提案 JSON 写入所选根目录或项目下的 .okf-proposals。已接受的提案会将 Markdown 概念写入所选本地根目录。

POST /v1/concepts/validate 和 POST /v1/concepts/suggest-path 不会持久化任何内容。POST /v1/proposals 仅持久化提案记录。只有 POST /v1/proposals/:id/accept 会写入概念 Markdown 文件。

远程知识包

远程知识包可让一个工作区使用另一个仓库发布的概念，而无需将其纳入本地仓库。对于与宿主平台无关的设置，请从任意 Git 托管平台克隆或挂载一个 OKF 仓库，并通过 --root 传入其目录；传输和同步仍不属于 OKF 规范的范围。

支持的来源：

• 公共 GitHub 仓库树 URL：https://github.com/<owner>/<repo>/tree/<ref>/<path>

远程加载：

• 清点目录树，先获取选中的 .md 文档，然后仅获取显式引用的知识包本地资源
• 记录解析后的修订版本元数据、SHA256 摘要、文档／资源字节数以及未解析的引用
• 清点远程路径，但绝不下载未引用的 .sql、.py 或二进制文件内容
• 将每个远程知识包保存在其配置的知识包 ID 下
• 支持 include 和 exclude 筛选器
• 解析远程知识包路径中的 Markdown 链接
• 强制执行文件数量和字节数限制
• 不执行远程仓库中的代码

CLI 示例：

okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect
okf --project okf.project.yaml --remote-bundle vendor=https://github.com/example/vendor-okf/tree/main/bundles/catalog validate

MCP 运行时加载：

调用 load_remote_bundle 之前，先使用 --allow-remote-tool 启动 MCP 服务。

{
  "name": "load_remote_bundle",
  "arguments": {
    "id": "shared",
    "url": "https://github.com/example/okf-atlas/tree/main/bundles/shared",
    "include": ["public/**"]
  }
}

使用 list_remote_bundles 检查已加载的内容。

结构化搜索

search_concepts 接受：

• query
• bundle
• types
• tagsAny
• tagsAll
• pathPrefix
• frontmatter
• linkedTo
• linkedFrom
• relationType
• orphanOnly
• statuses
• trustTiers
• freshness 和确定性的 asOf
• hasSources
• runtime 和 attestationReady
• generatedBy 和 verifiedBy
• detail（默认为 compact，也可为 full）
• limit
• offset

list_concepts 也接受文本 query（以及 mode），并将其与列表筛选条件一起应用。文本搜索会以不区分大小写的方式进行分词、折叠变音符号、丢弃停用词和单个字母，并使用目录的语言（英语和意大利语，权重均为 1.0）对每个词进行词干提取。自 0.10 起，mode 默认为 auto：匹配所有词的概念会按其自身顺序排在前面；如果这类概念少于 autoFill（默认为 3），则随后列出只匹配部分词的概念（此时响应中的 mode 为 auto）；如果没有概念匹配所有词，则为 any；如果没有追加概念，则为 all。这样可以避免一篇恰好包含所有查询词的长文档，遮蔽匹配大部分查询词的较短文档。autoFill 是库的搜索选项，也是 okf.project.yaml 中的键（autoFill: 0 会恢复 0.10 规则：只有在没有概念匹配所有词时才回退），它不是工具参数。all 会恢复 0.10 之前的行为，any 会为匹配任意一个词的结果排序。BM25+ 会对标题、类型、标签、别名、描述、路径、正文和精确字段（ID、路径、别名、原始标题词）进行排序；精确字段不会进行词干提取，因此标识符和 SKU 仍按字面匹配。双引号括起来的文本会按字面匹配（不进行词干提取或重音符号折叠，保留停用词和单个字母），匹配范围包括 ID、路径、别名、标题和原始词；包含数字或连字符的未加引号词语也会按字面匹配；只有文本字段会进行词干提取。Frontmatter 仍可通过精确结构化筛选条件使用，但不会复制到文本索引中。分数仅在结果集中相对有效，并非跨版本的稳定标尺；应使用排序和 relevance。

查询响应会报告 mode（实际采用的模式）、queryTerms、droppedTerms、allTermsTotal（匹配所有查询词的概念数，即使在 any 模式下也会报告）以及 lowConfidence；当 mode 为 any（即按任意词匹配结果排序）且排名第一的结果匹配的查询词少于一半时，lowConfidence 为 true。每个结果都包含 coverage（匹配的查询词占比）、relevance（得分与最高分之比），以及在完整详情中提供的 matchedTerms。可选择启用的阈值 minCoverage 和 minRelevance 会剔除较弱的结果；freshnessPrior 会降低已弃用（0.5）、过期（0.7）和草稿（0.85）概念的权重。精简结果包含 uri、title、type、description、coverage 和 relevance；标题、类型和描述都有长度限制，而完整结果不会丢失信息。

查询长度上限为 512 个字符，去除停用词后最多包含 16 个词。前缀扩展和模糊匹配会刻意禁用。词干提取所用语言来自项目配置键 languages（auto、none 或 [it, en] 之类的代码），或 --root 模式下的 --languages；auto 会根据各文档检测每个 bundle 的语言。仅包含标点符号的查询不会返回匹配项。标签和类型的匹配不区分大小写。任意 frontmatter 筛选条件支持精确标量匹配和数组包含匹配。relationType 会筛选出具有该类型出向关系的概念。

SDK 回归测试套件还会基于实际序列化的 MCP 文本，为一个中性的四步研究路径设定预算。它使用 UTF-8 字节数除以 4 作为确定性的估算值，而非精确的模型分词数或计费数量，并同时检查精简结果的绝对预算和精简结果与完整结果的比例。

示例：

{
  "query": "catalog",
  "types": ["API Route"],
  "tagsAll": ["api", "orders"],
  "limit": 10
}

如需进行本地相关性和性能检查，请运行非打包的开发基准测试，并提供 bundle 根目录以及可选的 { "query": "...", "expected": "path/or/concept-id" } JSON 数组形式的判断结果：

node --expose-gc scripts/search-benchmark.js \
  --root /path/to/okf \
  --qrels /path/to/qrels.json

它会报告 OKF 和搜索索引的构建时间、保留堆内存/RSS、查询延迟 p50/p95、Recall@10、MRR@10 以及有代表性的排名。搜索索引在进程内，并以解析后的 OKF 索引为键，因此远程加载和已接受的提案都会自动获得新的索引。

预算约束的上下文与章节锚点（0.11）

get_context（MCP，只读）和 okf context <query> [--budget <tokens>] [--limit <n>] [--provenance compact|full|none]（CLI，JSON）会用相关章节回答问题，而不是返回完整概念。候选项来自与 search_concepts 相同的搜索（相同的筛选条件、mode、minCoverage、minRelevance、lowConfidence、queryTerms）。章节根据其自身文本评分（BM25；概念的类型、标签和路径最多额外增加 20%），并按候选概念的排名排序；在同一概念内，文本与查询匹配的章节排在仅通过元数据找到的章节之前，而强匹配章节最多可以排到 4 个较弱概念之前。章节按此顺序去重并打包，直到达到 budgetTokens（默认值为 1,200，绝不超出）。预算涵盖完整的响应内容：usedTokens 是整个 JSON 结果（包括所有字段，如候选 concepts、queryTerms、计数器和每个章节字段，以及评分字段）的 ceil(characters / 4)；get_context 会以紧凑格式返回该 JSON，因此 Agent 接收到的文本就是实际计量的内容。章节会打包进响应其余部分留出的空间；如果章节周围的字段也放不下，候选概念列表会从末尾缩短（记入 omittedConcepts）；只有当预算小于查询回显和字段名称所需空间时，才会超出预算（此时不会返回章节或概念）。每个章节的 tokens 使用相同的估算方式，响应中也会注明估算器。0.11.0-rc.2 之前只统计章节的内容字段，因此响应会达到预算的 1.6 至 1.7 倍。来源信息默认采用 compact（包含 status、freshness、布尔值 verified、sourceCount）；provenance: "full" 会返回 status、staleAfter、freshness、trustTier、verified、generated 和 sources；provenance: "none"（或 includeProvenance: false）则将全部预算用于章节。该库提供 assembleContext(index, options)、conceptSections(doc) 和 sectionUnits(index)。

章节锚点是 okf-mcp 扩展；OKF v0.2 未定义章节锚点，包中也不需要包含它们。概念会在文档级标题处分段：第一个标题之前的文本（含标题和描述）仅通过概念 URI 定位，其他章节则通过 uri#slug 定位。标题文本首先会进行规范化（setext 标题或换行标题中的换行符，以及每段连续空白字符，都会替换为一个空格，然后去除首尾空格）；之后 slug 遵循 GitHub 规则：转换为小写，移除所有非字母、组合标记、数字、下划线、连字符或空格的字符，再将每个空格替换为连字符（因此 ## Consentito / Allowed 会生成 consentito--allowed，与 GitHub 相同）。重复的标题会按文档顺序依次添加 -1、-2……。去掉片段标识符的阅读器仍会定位到该概念。锚点仅取决于它自身之前的标题文本：对任意章节正文的编辑、仅更改空白字符的编辑以及对后续章节的编辑，都不会改变锚点；但重命名标题或在它之前添加同名标题，则会改变锚点。

嵌入（0.11，可选启用）

默认情况下，不启用稠密检索，默认安装也不会发出网络请求。0.11 提供了嵌入器接口、一个零依赖的客户端，可用于 OpenAI embeddings API 和兼容服务（Ollama、vLLM、LM Studio），还提供了存储在软件包之外的向量缓存，路径为 $XDG_CACHE_HOME/okf-mcp/<sha256 of the root>/（~/.cache/okf-mcp/ 或 %LOCALAPPDATA%\okf-mcp\），因此已填充的缓存不会污染 Git 工作树，且可随时删除，并支持基于缓存的混合搜索。

在 okf.project.yaml 中启用（或者在 --root 模式下，使用通过 --embedder-config <file> 传入的 JSON 或 YAML 文件；该文件也可以是裸嵌入器配置块；--cache-dir <dir> 可覆盖缓存位置）：

embedder:
  type: openai
  baseUrl: https://api.openai.com   # or a local OpenAI-compatible server
  model: text-embedding-3-small
  apiKeyEnv: OPENAI_API_KEY         # the key is read only from this variable
  dimensions: 512
  # optional: batchSize, timeoutMs, maxRetries, concurrency, maxInputChars
cacheDir: ../okf-vectors            # optional; relative to the project root, never inside it
fusion:
  alpha: 0.4                        # weight of the dense side (default 0.4, chosen on the development queries)
  normalization: tmm                # tmm (default), lexical-tmm or minmax
embedUnits: concepts                # concepts (default) or sections (one vector per section; better on synonym queries)

嵌入器设置绝不接受作为工具参数。服务器启动时会验证嵌入器，在未配置维度时发现维度，打开缓存，并在后台为缺失单元生成嵌入；嵌入器出现问题不会导致服务器无法启动。随后，search_concepts 会将词法排名与缓存中的余弦相似度排名融合，方法是对归一化分数进行凸组合：两侧的分数均按其评分函数的最低理论值以上的最佳分数缩放；默认情况下，最低理论值分别为词法分数的 0 和余弦分数的 -1（tmm）；lexical-tmm 仅在词法侧使用最低理论值，minmax 则在两侧使用观测到的最低值，参见 Bruch 等人，arXiv:2210.11934（每次调用设置 hybrid: false 会保持纯词法搜索，不发出请求）。远程软件包始终仅进行词法搜索：其文本绝不会被嵌入。mode、coverage、allTermsTotal 以及 minCoverage/minRelevance 下限均保持词法含义（显式设置 mode: "all" 只会重新排序所有词项匹配结果）：词法命中结果会与余弦相似度最高的 200 个概念融合；这是固定候选集，因此查询的每一页都会按相同排名分页，并且每个候选项都带有自身的词法依据（匹配词项、覆盖率、分数），供下限和 lowConfidence（根据展示的最高排名结果计算）使用。当运行了全词项匹配阶段且查询包含带引号或类似标识符的词项时，所有词项匹配结果都会排在每个语义邻近项之前。relevance 和 score 将变为融合分数，每个结果还会新增 lexicalScore、denseScore（余弦相似度）和 fusedScore。响应中会新增 hybrid、alpha、normalization、embedder: { id, remote, dimension, degraded, code?, serverCode? }、cache: { rows, dir? }（dir 仅在 --write 服务器上出现）、用于查询编码的 usage: { promptTokens, requests }，以及 timings: { queryEncodingMs, searchMs, totalMs }。只要嵌入器缺失、发生故障或缓存为空，搜索就会仅使用词法方式，并返回 embedder.degraded: true、固定的 code，以及 HTTP 故障时枚举的 serverCode；绝不会返回服务器提供的文本。查询编码失败后，服务器会保持纯词法模式 30 秒再重试。每次成功执行 okf_apply_changes 批次后，只会为变更单元生成嵌入（若批次大小允许，则只需一个请求），且回执会包含 embedding: { units, embedded, skipped, embedder, cache, usage, durationMs }。只读的 embedding_status 工具仅在配置了嵌入器时列出，并报告嵌入器、缓存、启动和最近一次准备回执以及 Token 用量。只要文本离开本机，回执就会报告 embedder.remote: true。缓存以嵌入器标识 openai:<endpoint>:<model>:<dimension>:<maxInputChars> 为键，因此更改端点、模型、维度或截断长度都会重建缓存。该库提供 createOpenAiEmbedder、openVectorCache、resolveCacheDir、prepareEmbeddings、openEmbeddingRuntime、denseSearch 和 fuseRankings；node scripts/eval-search.js --embedder <file> 可在检索测试数据上评估混合搜索的运行效果。 篇幅较长或标识符密集的文档：客户端会将每项输入截断至 maxInputChars（默认 24,000 个字符），并按每 3 个字符约 1 个令牌的保守估算来规划请求，因为生成的契约和列名列表平均每个令牌约 2.6 个字符，在旧的 32,000 字符默认值下会超出提供方 8,192 个令牌的输入上限（更改默认值会重建以 32000 为键的缓存）。如果提供方仍以 invalid_request 拒绝请求，客户端会将批次对半拆分，直到被拒绝的输入单独成批（额外请求数有限）；然后将每项被拒绝的输入缩短至原长度的一半后重试一次（不会短于 2,000 个字符），如果再次被拒绝，则跳过该单元：准备回执会在 skipped: [{ id, reason: "input_rejected" }] 下列出该单元，其他所有单元都会完成嵌入，搜索仍保持混合模式。embedding_status 会报告最近一次准备中 skipped: { count, ids }（前五个 ID），启动回执也包含相同字段；被跳过的单元会在下一次准备时重试，在此期间则通过词法得分检索。如果请求中的所有输入都被拒绝，则属于配置问题，仍会像以前一样失败。

自适应融合权重（0.12）：fusion.alpha: adaptive 会根据词法搜索已掌握的信息，为每个查询确定语义侧的权重，因此同一查询的每一页都使用相同权重：当查询包含引号括起来的词语或类似标识符的词语，且有概念匹配所有词语时，使用 fusion.adaptive.low（匹配所有词语的结果仍排在所有语义近邻之前）；当至少有 autoFill 个概念匹配所有词语时，使用 mid；当没有概念匹配所有词语，且没有概念匹配到一半以上的词语时，使用 high；介于两者之间时，根据最佳词法覆盖率线性插值，覆盖率从 0.5 时的 high 到 1 时的 mid。权重默认采用开发集拆分选出的 { low: 0.1, mid: 0.5, high: 0.9 }；high 不得低于 mid。混合响应会报告 alphaUsed 和 alphaReason（fixed、literal_terms、all_terms、weak_lexical 或 interpolated），embedding_status 会报告该设置及其权重。默认值仍为固定的 0.4，排序结果与 0.11 完全相同：在测试样例中，自适应权重使 alpinaria 的 Recall@5 从 0.830 升至 0.838（同义词从 0.542 升至 0.604），但使 atlas 从 0.882 降至 0.870，因此未达到预先登记的条件（test/fixtures/retrieval/reports/hybrid-0.12-2026-10-25.md）。

fusion:
  alpha: adaptive                   # or a number between 0 and 1 (default 0.4)
  adaptive: { low: 0.1, mid: 0.5, high: 0.9 }

上下文单元（0.12）：embedUnits: contextual-sections 会在每个分节前加上一行概念名称前缀 title · type · path（最多 160 个字符；标题较长时会先缩短），再对其进行嵌入，因此独立的“Limits”或“Steps”分节也会带有其所属系统的信息；contextual-concepts 则会在概念文本前添加 type · path。锚点与 sections 相同。带前缀的文本有各自的哈希，因此切换单元集时会对每个单元重新嵌入一次（准备回执、启动回执和 embedding_status 都会标明单元集；embedded 和 pruned 会统计此次切换），此后，正文编辑只会重新嵌入其所在分节（标题、类型或路径编辑会重新嵌入该概念的所有分节）。concepts 仍为默认值：在开发集查询中，没有其他单元集按照预先登记的规则胜过它（开发集 Recall@5 均值：concepts 为 0.844，contextual-concepts 为 0.843，contextual-sections 为 0.841，sections 为 0.834）；在测试样例的短分节上，前缀会使提示词令牌增加 56%（contextual-concepts 增加 6.6%）。 置信度（0.12）：每个针对查询的 search_concepts 和 get_context 响应都包含 confidence: { coverage, topSimilarity, lowConfidence, reasons }。coverage 是查询词中被排名最高的结果匹配的词所占比例；当语义侧运行时，topSimilarity 是查询与任一候选项单元之间的最高余弦相似度（否则为 null）；当任意词回退机制生成结果且排名最高的结果匹配的词少于一半时（原因是 weak_lexical_match），或者排名最高的结果匹配的词少于一半且 topSimilarity 低于 confidence.minSimilarity 时（原因是 low_similarity），lowConfidence（也是顶层字段）为 true。仅使用词法匹配的响应没有相似度，并沿用 0.10 规则。get_context 接受 abstainOnLowConfidence: true，在查询置信度较低时不返回任何章节（响应仍包含置信度块和候选概念，并注明 abstained: true）。相似度阈值取决于嵌入模型；默认值 0 是根据 text-embedding-3-small 的开发查询选定的：将阈值设为最高 0.8 都不会额外标记任何一个无法回答的查询，因为所有排名最高的结果匹配词数少于一半的无法回答查询，已经触发了任意词回退机制。部署时可以设置自己的阈值：

confidence:
  minSimilarity: 0.3                # cosine below which a weakly matched top result is flagged

图行为

作为 okf-mcp 图投影，Markdown 链接会变为 markdown_link 边，扩展中的 relations 会变为类型化的 relation 边，标准 v0.2 中值为路径的字段会变为 resource、source、computation、executor 和 attester 边。内部概念引用会解析为规范节点；明确引用的非 Markdown 文件会解析为 okf-mcp okf-asset:// 节点；URL 和范围描述符则保持为未获取的外部叶节点或不透明叶节点。

为方便导航，如果没有完全匹配的文档目标，okf-mcp 会将指向嵌套捆绑包目录的链接解析到该目录保留的 index.md。此规则适用于本地和远程捆绑包，也适用于提案编写期间的候选项验证。

图工具返回有界 JSON：

{
  "nodes": [
    {
      "id": "okf://app/routes/order-status",
      "bundle": "app",
      "path": "routes/order-status.md",
      "type": "API Route",
      "title": "Order Status Route",
      "tags": ["api", "orders"],
      "description": "Serves order status state."
    }
  ],
  "edges": [],
  "warnings": []
}

首先使用 graph_summary 获取按生命周期、信任度、新鲜度、运行时、就绪状态和边类型分类的计数。图工具接受 edgeKinds；需要这些叶节点时，传入 includeExternal: true 或 includeAssets: true。

默认关系类型：

• depends_on
• produces
• consumes
• persists_to
• materializes_to
• configured_by
• checked_by
• owned_by
• supersedes
• related_to

在 okf.project.yaml 中使用 relationTypes 添加项目专属的关系类型。

bundles 和 plugins 中的项目路径必须是相对于 okf.project.yaml 所在目录的路径，并且必须位于该目录内。绝对路径和通过 ../ 越界的路径都会被拒绝。

捆绑包的 include 和 exclude 过滤器使用简单的路径模式：

• 精确文件路径，例如 services/order-status.md
• 目录前缀，例如 archive/
• * 表示一个路径段
• ** 表示任意嵌套路径

验证

validate、validate_bundle 和 validate_project 会分别返回 conformant 和 validForProject 字段，以及结构化诊断信息。valid 仍是 validForProject 的兼容别名。

当存在相应文件时，OKF 一致性检查涵盖：

• 非保留概念文档中可解析的 YAML 映射型 frontmatter
• 非空的 type
• index.md 和 log.md 的保留结构

未知 frontmatter 键和未知概念类型值不会导致一致性检查失败。YAML 解析器支持嵌套映射、数组、块标量，以及其安全 YAML 核心模式接受的其他结构；重复键和不支持的自定义标签会被拒绝。

缺少 index.md 文件和损坏的交叉链接不会导致 OKF 一致性检查失败。strictLinks 只影响 okf-mcp 工作区的有效性（validForProject），不影响规范性的 conformant 结果。

项目有效性检查还会报告：

• 重复的 OKF URI
• 损坏的内部 Markdown 链接，默认作为提示；设置项目的 strictLinks: true 或传入 --strict-links，会使其导致项目无效
• 无效的关系类型
• 缺失的关系目标
• 损坏的 okf:// 关系目标
• 重复的 Bundle ID
• 无效或越界的项目路径
• 解析到已配置 Bundle 根目录之外的链接
• 缺失的 Bundle 根目录

即使 Bundle 不完整，服务仍会提供其中有效的概念。

可选的 v0.2 系列会归一化为 signals。格式错误的来源、生成、验证、生命周期、新鲜度或计算元数据会产生提示，且绝不会创建第四种信任层级。验证采用失败关闭策略，结果为 unverified；未指定状态时默认为 stable；若提供明确的 asOf 日期，则会据此评估新鲜度。创作时的校验比使用时更严格，会拒绝格式错误的已知 v0.2 字段。

经证明的计算

inspect_attested_computation 会报告运行时、声明的参数、经过认可的内联或文件计算摘要、执行器回执字段、证明者引用、已索引资产、就绪状态和诊断信息。prepare_attested_computation 会检查声明的参数名称并返回摘要，但不会返回参数值。check_computation_receipt 会检查字段是否存在，但不会返回字段值、持久化回执或声称已完成证明。

okf-mcp 没有执行或证明适配器。它绝不会运行计算、执行器资源或证明者资源，也绝不会按需获取外部合约 URI。

CLI 提供对应功能：computation inspect|prepare|check-receipt、provenance、edge-kinds 和 asset。使用 --parameters-file <path|-> 或 --receipt-file <path|-> 提供敏感值；原始参数和回执 JSON 会被有意禁止作为进程参数传入。- 会从标准输入读取一个 JSON 对象。资产读取可接受最高达已索引 1 MiB 限制的 --max-content-bytes。

将现有目录迁移到 v0.2

v0.2 规范通过两项回退机制，确保 v0.1 bundle 仍可使用：当缺少 generated 时使用旧版 timestamp，当缺少 sources 时使用正文中的旧版 # Citations 列表。okf-mcp 会在读取时应用这些回退机制，并提供可选的仅供审核的转换工作流。

对于单个根目录，可检查迁移就绪情况并预览拟添加的原生字段，全程不会写入任何内容：

okf --root /path/to/catalog migrate check
okf --root /path/to/catalog migrate preview \
  '{"metrics/revenue.md":{"by":"human:owner","confirmed":true}}'

在可选的多根项目模式下，请在 actor 映射 JSON 之前提供根目录 ID。

迁移会采取审慎保守的做法：

• 原生 generated 和 sources 字段始终优先
• 只有在明确确认 by 是真实的 actor 后，才会将有效的 timestamp 复制到新的 generated: { by, at } 映射中
• 只有当 # Citations 是单个顶层 H1 章节、至少包含一个可安全解析的列表条目，且没有未解析的散文、嵌套章节、含义不明的条目或逃逸路径时，才会将其转换为 sources
• 为保持兼容性，会保留旧字段和引用说明文字
• 通过 --generated-path、文档标记或 generated_file/generatedFile frontmatter 标记的概念，必须通过其生成器进行更改；远程根目录仅生成报告
• 身份冲突、无效文档、不安全引用和未解决的资源都会阻止版本声明

okf_propose_v02_migration 要求在本地根目录中编写内容。它会创建审核清单、为每个受影响文件创建一项提案，并创建一项受门控的根目录 okf_version: "0.2" 提案。不会自动接受任何内容；只有在所有子项都已接受且整个目录通过验证后，才能接受根目录提案。

生成器插件

生成器插件在 okf.project.yaml 中配置，并通过 generate 运行。

内置插件：

• filesystem：为每个匹配的源文件创建一个概念。默认处理 Markdown 文件。
• json-spec：为每个 JSON 文件创建一个概念，并可在存在目标表时生成 persists_to 关系。

生成的输出是常规的 Markdown/YAML OKF，并由与手写概念相同的索引器进行验证。

限制

• MCP 传输仅支持 stdio。单独的 HTTP 编写 API 并非基于 HTTP 的 MCP。
• MCP 协议兼容性遵循固定版本的官方 SDK v2 依赖项。
• 没有文件监视器。外部文件发生更改后，请重启服务。通过 MCP 编写功能接受的概念会立即刷新 MCP 服务索引。
• HTTP API 是轻量级内置服务，并非完整的托管式多租户服务。
• OKF v0.2 计算支持仅限静态检查和预检；不会执行任何计算或证明者。