内容
# OKFy
用于模型上下文组装的工具。当整个知识库对于任何上下文窗口来说都太大，或者主动有害，稀释模型对任务无关材料的注意力时，OKFy会从语料库（代码库、文档、研究集合）中提取知识到特定用途的 **OKF 包** 中，并为模型提供精确访问任务所需的切片。OKF 包是一个自包含的 Markdown 概念目录，具有 YAML 前置信息，由声明的 **用途** 塑造，可被任何代理使用，甚至是无需安装 OKFy 的代理：原始文件遍历有效，CLI 使其快速，MCP 使其成为一个工具表面。
该流程按职责分开。所有确定性的部分——验证、索引、BM25 检索、基于词典的查询扩展、分段、评估记录、写入门、打包——都存在于与代理无关的 Python 核心（`core/`，PyYAML 是其唯一依赖，无 LLM 调用）。LLM 驱动的工作——目的访谈、模式设计、盲并行提取、合并以及词典或评估裁决中的判断——是由 Claude Code 插件命令驱动的代理工作流，该命令调用核心 CLI。核心是机器；代理在核心之上提供判断。检索故意 **无向量**：BM25 加上经过审查的机器可读词典确定性地关闭跨语言差距，因此相同的查询每次运行都会返回相同的答案，并且可审计。
**提取质量不自我认证。** OKFy 不声称某个包是好的，因为构建它的模型说是这样。验收是一个可重放的工件：`okfy eval run` 确定性地重放包自己的测试查询，LLM 评委可以 **提出** 裁决，但只有 **所有者** 裁决才计入发布——一个包评估自己的输出是一个封闭循环，这个设计拒绝信任。裁决、查询扩展契约和每个“此概念不再当前”的标志都记录在包中，而不是在聊天记录中。
## 安装
**核心 CLI**（Python 3.11+，[uv](https://docs.astral.sh/uv/))：
```bash
git clone https://github.com/vsov/okfy && cd okfy
uv tool install ./core # 安装 `okfy` 命令
```
**Claude Code 插件**（添加 `/okfy:new`、`/okfy:extract`、`/okfy:eval` 等）：
```bash
/plugin marketplace add vsov/okfy
/plugin install okfy@okfy
```
该插件驱动访谈和提取；它会调用 `okfy` CLI 执行每个确定性步骤，因此必须先安装核心。
## 快速入门
```bash
/okfy:new <语料库路径> <包路径> # 目的访谈 → 调查 → 提取计划
# ↳ 审查和批准计划 （单个必填检查点)
/okfy:extract <包路径> # 盲并行工作线程 → 合并 → 验证 → 打包
/okfy:eval <包路径> # 重放测试查询；您来判断裁决
```
`/okfy:new` 会询问您 Bundle 的用途，调查语料库，根据目的原型设计模式（用于散文语料库的决策支持，用于更改代码的代码库映射，用于使用 API 的 API 参考），并编写您批准的提取计划。`/okfy:extract` 运行盲并行提取，将草稿合并为最终概念，根据 OKF 规范验证源代码检查，并打包 Bundle（索引、README、`AGENTS.md`、静默 git init、结构化提交、提取账本）。`/okfy:eval` 重放十个测试查询，并记录您的裁决——在您判断完所有查询之前，Bundle 保持 **暂定** 状态。
[用户指南](docs/guide/GUIDE.md) 从头到尾介绍两条路径——§6 是将文本语料库和代码库转换为 OKF 的逐步过程，§11 解释了如何验证包质量以及为什么所有者而非模型会签署。
## CLI 参考
核心 CLI 与代理无关，可直接使用。运行 `okfy <命令> --help` 获取完整选项。
| 命令 | 执行操作 |
| --- | --- |
| `okfy init <包> --corpus <路径> [--language zh]` | 创建一个空的 Bundle 骨架并初始化其 git 仓库。 |
| `okfy survey <语料库>` | 对语料库进行廉价侦察 → JSON 语料库映射（文件、大小、样本）。Git 语料库遍历 `git ls-files`（尊重 `.gitignore`）；默认排除供应商/构建/锁定文件/二进制噪声，并报告所有跳过的内容，绝不沉默丢弃。 |
| `okfy segment <包> [--budget N] [--include ...] [--exclude ...]` | 将语料库切分为确定性的每个 Worker 分段；超过预算的文件会在空行边界处切分为 `{路径, 行数}` 切片；密集文件若无空行（压缩、单行）则回落到 `{路径, 字符}` 字符窗口。 |
| `okfy segment-status <包> <分段 ID> <状态>` | 在管道状态中记录分段的提取状态。 |
| `okfy cluster <包>` | 预先聚集草稿概念以指导合并。 |
| `okfy validate <包> [--all] [--no-archetype] [--quiet] [--strict-sources] [--strict-quality]` | 验证概念：OKF 规范一致性 + 包完整性。源路径解析为语料库快照——断开的路径会警告（`W_BAD_SOURCE`）；`--strict-sources` 升级为错误，这是新提取所遵循的标准。还会检查锚点：`path#L10-L20` 必须是真实的行范围，`guide.md#heading-id` 必须是真实的标题（`W_BAD_ANCHOR`/`E_BAD_ANCHOR`）。`--strict-quality` 要求一个完整的 `meta/purpose-fitness.md` 工件——持久的 L3 传递——涵盖每个采样的概念 × 目的检查。 |
| `okfy index <包>` | 构建 `.okfy-cache/` 中的 BM25 + 链接索引。 |
| `okfy query <包> <文本> [--type T] [--tag T] [-n N] [--include-meta] [--no-expand] [--no-stale]` | 带有前置过滤的词汇 BM25 搜索。默认启用词典查询扩展（`--no-expand` 退出）；过期概念保持可见但被标记（`--no-stale` 删除它们）。 |
| `okfy show <包> <概念 ID>` | 打印概念的完整内容。 |
| `okfy links <包> <概念 ID>` | 显示概念的入站和出站链接。 |
| `okfy stale <包> <概念 ID> (--reason R \| --clear)` | 仅限所有者：标记概念为“不信任为当前”（或清除）。从不自动设置——过期是审查后的决定。 |
| `okfy eval run <包> [-n N]` | 重放包的 `purpose.md` 测试查询（扩展 → 顶部命中）到 `meta/eval.json` 中的追加评估运行。 |
| `okfy eval verdict <包> <运行\|最新> <查询索引> <通过\|失败\|部分> (--llm \| --owner) [--note …]` | 记录查询的裁决。`--llm` 提出（保持暂定）；`--owner` 处理（唯一发布接受计数）。 |
| `okfy eval status <包> [运行\|最新]` | 有效裁决每个查询和总数；包在每个查询都有所有者裁决之前保持 **暂定**。 |
| `okfy job <包> <分段> --prompt-file <p>` | 将分段的工作者契约冻结到 `meta/jobs/<分段>.json` — 输入带有 `行`/`字符` 跨度和内容哈希，语料库快照，原型，提示 SHA-256 — 并打印其摘要。 |
| `okfy ledger add\|list <包> … [--job <摘要>]` | 追加/读取提取账本（`meta/ledger.jsonl`）— Worker 和合并步骤的分段级来源；`--job` 将行与冻结的作业工件绑定。 |
| `okfy propose <包> …` | 代理通道：在 `proposals/` 中提交概念更改 — 绝不进入实时映射。 |
| `okfy review list\|accept\|reject <包> …` | 所有者门控：审查提案；接受在合并前验证。 |
| `okfy refine <包> <概念 ID>` | 所有者通道：直接编辑实时概念，已验证并提交。 |
| `okfy diff <包>` / `okfy snapshot <包>` | 语料库漂移报告（`受影响` / `未覆盖的新内容` / `过期候选者`）/ 更新后重新标记快照。 |
| `okfy repair-links <包>` | 在重命名和合并后确定性地修复悬空概念链接。 |
| `okfy workspace init\|status\|export …` / `okfy link-candidates …` | 联邦多个包：工作区生命周期，交叉候选，一次性导出融合。 |
| `okfy sample <包> [--fraction F] [--minimum N]` | 面向目的适应性审查的风险导向确定性样本：更改的源代码，过时标志，罕见类型，弱覆盖首先，然后是种子分层填充。返回选择器版本和种子，以便样本可重放。 |
| `okfy package <包>` | 生成 `index.md`，`README.md`，`AGENTS.md`，日志和预提交钩子。 |
| `okfy log <包> <消息>` | 追加到包的 `log.md` 的结构化条目。 |
## MCP
通过 stdio 将包（或联合工作区）提供给任何 MCP 客户端——Claude Code、Claude Desktop、Cursor。适配器是一个隔离的包：MCP SDK 位于其中，核心保持纯 Python。
```bash
uv tool install ./adapters/mcp # 安装 `okfy-mcp`
okfy-mcp config ~/bundles/<b> --client claude-code # 打印配置片段
```
将打印的块粘贴到项目的 `.mcp.json` 中，重启客户端，然后出现五个工具：`okfy_query` / `okfy_show` / `okfy_links` / `okfy_overview`（读取）和 `okfy_propose`（仅写入 `proposals/`，审查门控完整）。`okfy_query` 运行与 CLI 相同的词典扩展（`expand`，`include_stale` 默认值为真）；`okfy_show` 采用 `section` 标题和 `max_chars`上限，而 `okfy_overview` 采用 `max_items` / `max_chars`上限——每个上限响应都带有 `truncated` 标记，以便代理绑定自己的上下文。OKFy 打印片段，但从不编辑客户端配置。指向工作区路径以联合多个包。详情：[adapters/mcp/README.md](adapters/mcp/README.md)。
## 包默认私有
OKFy 生成的包是 非公开 工件，**不能在此仓库中创建**——核心拒绝将包置于 OKFy 源代码树下，由 CLI 强制执行，而不是通过约定。包存在于其自己的 git 仓库中（或使用 `--embed` 时位于 `.okf/`）。共享包始终是明确的用户行为：其仓库及其访问控制。
## 文档
- [用户指南](docs/guide/GUIDE.md) — 面向工程人员的知识工程：OKF 格式入门，OKFy 的思考方式（目的 → 计划 → 包），文本语料库和代码库的端到端演练，保持包新鲜，联合，精炼循环，验证质量和 MCP。
- [MCP 适配器](adapters/mcp/README.md) — 为 MCP 客户端提供包。
## 许可证
[Apache-2.0](LICENSE)
