OKFy 是做什么的？
概述
使用 OKFy 将文档网站或本地 Markdown 文件夹转换为本地开放知识格式（OKF）捆绑包，然后通过只读的 MCP 服务器将其暴露给智能体。在生成的命令中优先使用 npx -y okfy-ai，以便客户端无需全局安装即可启动已发布的包。
快速参考
| 目标 | 命令或操作 |
|---|---|
| 注册文档站点并打印设置 | npx -y okfy-ai init <name> <url> --client codex --max-pages 100 --max-depth 4 |
| 导入本地 Markdown | npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" |
| 为任务证明来源 | npx -y okfy-ai activate <name-or-bundle> --client codex --task "<task>" --out okfy-activation |
| 预览就绪状态和依赖关系图 | npx -y okfy-ai map <name-or-bundle> --out okfy-inspector.html |
| 诊断设置 | npx -y okfy-ai doctor <name> --client codex |
| 向 MCP 提供服务 | npx -y okfy-ai serve <name-or-bundle> --mcp --auto-refresh |
设置工作流
- 选择一个简短来源名称，例如
stripe、clerk或project-docs。 - 对于文档网站，运行
npx -y okfy-ai init <name> <url> --client codex --max-pages 100 --max-depth 4。 - 对于本地 Markdown，运行
import，然后运行validate，最后提供生成的捆绑包路径。只有在用户明确批准覆盖输出目录时，才添加--force。 - 当用户希望在配置更改前获得证明时，运行
activate并带上与用户真实问题匹配的--task。生成的包包含okfy-inspector.html、okfy-setup.md和okfy-proof.json。 - 如果设置失败或 MCP 客户端无法看到工具，请先运行
doctor，再手动编辑客户端配置。
MCP 使用
当 OKFy MCP 服务器可用时，请按以下顺序使用工具：
- 使用
bundle_summary检查验证状态、新鲜度、可用来源和工具期望。 - 使用
search_concepts并结合用户任务的关键词。在已知相关文档来源的多来源工作区中，使用source过滤器。 - 使用
read_concept获取最相关的概念，先进行少量读取再扩展。 - 当答案依赖于链接概念、反向链接、前提条件或邻近的 API/参考页面时，使用
get_neighbors。 - 引用概念结果提供的来源 URL 或资源字段。
从窄范围搜索开始，仅在结果稀疏时扩大范围。在工作区中，当概念 ID 不明确时，向 read_concept 传递 source 和 id。
工作区
当任务涉及多层级技术栈时，通过一个 MCP 服务器提供多个已注册来源的服务：
npx -y okfy-ai serve stripe clerk --mcp --auto-refresh
然后使用过滤器进行搜索：
{ "query": "checkout sessions", "source": "stripe", "limit": 5 }
每当用户提及产品名称、API、框架或文档来源时，使用 source 过滤器。如果用户询问整个技术栈的问题，先搜索整个工作区而不使用过滤器，然后为精确性对每个来源进行读取。
安全规则
- MCP 工具是只读的。自动刷新是针对已注册来源的服务器端维护，并非智能体可调用的写入工具。
- 不要使用
npx okfy；应使用npx -y okfy-ai进行免安装命令。 - 不要在常规的交互式终端会话中运行
serve --mcp。MCP 客户端会将其作为 stdio 子进程启动。 - 不要绕过爬虫安全默认值、私有网络保护或危险的
--force保护机制，除非用户明确接受风险。 - 当
init、activate或doctor可以生成或验证精确的命令/配置时，不要先手动编辑客户端配置。
常见错误
| 错误 | 修复 |
|---|---|
| 将 OKFy 视为托管索引 | 保持工作流本地化：捆绑包文件、MCP stdio 和来源 URL 保持可审查。 |
| 搜索后读取每个概念 | 先读取最匹配的结果，然后仅在需要时使用邻居扩展。 |
| 忽略工作区来源名称 | 对多来源捆绑包使用 source 过滤器和来源限定的读取。 |
| 跳过证明 | 当用户需要在连接 MCP 前获得信心时，使用 activate --task。 |
| 盲目调试配置 | 运行 doctor <name> --client codex 并遵循其输出的下一个修复命令。 |