文档
Okryptos 是为 AI 编程助手提供的项目知识库:知识按项目隔离,通过 hooks/扩展自动注入 AI 上下文,并可强制执行工作流规则。
安装与首次引导
三种安装方式任选其一,详见首页安装区。安装完成后运行首次引导(幂等,可重复执行):
ok setup # 或只装某个 agent:ok setup --agent zcode
ok setup 依次完成三件事:
- 写入 hooks 配置——覆盖全部已检测的 AI 助手:Kimi Code 写
~/.kimi-code/config.toml的 3 条 hook 标记块(自动备份、幂等覆盖),Pi 写 TypeScript 扩展,ZCode 合并写config.json,Reasonix 安装 Extension Protocol 插件包,opencode 写~/.config/opencode/plugins/的 TypeScript 插件,claude 合并写~/.claude/settings.json的 hooks(Claude Code / CodePilot 等兼容宿主共用),codex 合并写~/.codex/hooks.json(hook 契约兼容 Claude;技能零适配共享技能目录;ok 自动开启特性开关并写入信任记录;桌面端 26.707 与 CLI 0.147+ 均实证可用),qoder 合并写~/.qoder-cn/settings.json的 hooks(Qoder CN 终端 CLI;契约兼容 Claude,ok 自动开启 hooksConfig.enabled 开关——默认关闭时装好也静默不派发),qoder-ide 合并写~/.lingma/settings.json的 hooks(Qoder CN IDE 灵码内核:知识注入与触碰追踪可用、Stop 不可阻断致强制检查降级) - 安装六个技能——
ok-init / on / off / propose / capture / wiki,写入各 agent 的技能目录 - 配置 embedding——交互询问 base_url / model / API key,写入全局配置并当场验证连通性;回车跳过则只用关键词检索
快速开始
# 在需要使用知识库的项目目录里
cd /your/project
ok init # 注册项目(自动取目录名)
ok add --title "变更日志强制规则" --type rule --mandatory --file rule.md
ok add --title "Git 提交规范" --type note --tags git --file git.md
ok index # 配好 embedding 后同步索引与向量
然后新开 AI 助手会话即可生效:
- 问「git 提交规范是什么」→ AI 直接引用知识库内容回答
- AI 改了代码没写变更日志 → 回合结束时被阻断提醒
也可以在会话里直接说「初始化知识库」「关闭知识库 hooks」——对应技能会自动调用。
知识条目
每条知识是一个带 frontmatter 的 Markdown 文件(ok add 创建,也可手写):
---
title: 变更日志强制规则
type: rule # rule | pitfall | note | reference
tags: [changelog, workflow]
mandatory: true # true = 每会话首次提问全文注入
summary: 每次代码修改必须立即记录变更日志
---
正文(Markdown 自由格式)
数据集中存放在 ~/.okryptos/,不污染项目仓库。条目类型四种:rule(规则)、pitfall(踩坑)、note(笔记)、reference(参考)。
草稿流程(AI 提议,人批准)
AI 可通过 ok propose 把会话中沉淀的经验记为草稿条目(frontmatter draft: true)——草稿不参与检索与注入,只出现在 ok list 和 GUI 管理页(带「草稿」徽标)。人确认后用 ok approve <文件> 或 GUI 的「采纳」按钮转正。
沉淀模式用 ok capture propose|auto 切换:
propose(默认):AI 自主判断、主动提议,无轮次限制auto:Stop hook 每隔指定轮次强制 AI 自省提取经验;轮次间隔用ok capture interval <n>配置
常用命令
| 命令 | 作用 |
|---|---|
ok setup | 首次引导:hooks 配置 + 技能安装 + embedding 配置 |
ok gui | 启动 Web 管理界面(双击 exe 无参数运行同效) |
ok init [名字] | 注册当前项目,并幂等写入/更新 hooks 配置 |
ok add | 新建知识条目(自动重建索引与向量) |
ok propose / ok approve | AI 提议草稿 / 批准转正 |
ok capture [...] | 查看/切换沉淀模式,配置轮次间隔 |
ok wiki status|mark|base|diff | wiki 状态 / 记游标 / 基准分支 / 分支差异素材 |
ok search <词> | 命令行预览检索效果 |
ok index | 同步索引与向量(删除 kb.db 后执行 = 全量重建) |
ok doctor | 体检:配置、embedding 连通性、hooks 状态 |
ok on / ok off | 全局开关(默认开启) |
Web GUI
双击 ok.exe(无参数运行)或执行 ok gui 启动 Web 管理界面,浏览器自动打开 http://127.0.0.1:17888。GUI 由常驻 daemon 托管,关闭页面不会退出进程;ok daemon stop 停止常驻服务。四个标签页:
- 管理:项目/条目列表、新建/编辑/删除、检索预览、全局开关、分支过滤
- 引导:图形版
ok setup,另有 hook 超时、强制检查方式(reasonix)与卸载卡片 - 其他:数据导出/导入、更新日志、使用帮助、删除项目知识库(三重确认)
- 日志:ok / 守护 / embedding 三来源实时日志,来源 chips 多选 +「仅语义」开关 + 文本过滤
配置
生效配置 = 内置默认 ← 全局 ~/.okryptos/config.toml ← 项目 ~/.okryptos/projects/<名>/config.toml(逐层覆盖)。
# 全局配置(ok setup 可交互写入)
[embedding]
base_url = "https://api.openai.com/v1" # 任何 OpenAI 兼容服务
api_key = "sk-..." # 或用 api_key_env 指向环境变量
model = "text-embedding-3-small"
# 项目配置:强制规则示例
[[enforce]]
type = "changelog_required"
code_globs = ["**/*.go"] # 改了这些 = 改了代码
changelog_glob = "docs/changelogs/**" # 碰了这些 = 写了日志
message = "本次会话修改了代码但未更新变更日志,请先按规范补齐。"
检索算法
SQLite + FTS5 的混合检索,总分只用于排序、准入按通道独立判定——宁缺毋滥、不强行凑 top_n:
- 关键词通道:FTS5 全文索引 + BM25 打分,按 标题/标签/摘要/正文 分权重;中文用二元组分词,零依赖;准入需归一 BM25 分 ≥
min_score(默认 0.5,随库规模缩放) - 语义通道:OpenAI 兼容 embedding + 余弦相似度,召回「问法不同但意思相近」的条目;准入走模型无关的语义门槛(以本次查询余弦分布为参照,头部相对中位数有显著分离才启用,
min_gap默认 0.25 可调) - 草稿条目不进检索通道:FTS 与向量都排除,批准后自动参与
1 万条条目下单次查询约 30ms;embedding 服务不可用时自动降级为纯关键词检索,注入永不缺席。实现细节见架构文档第 17 章。
工作原理
以 Kimi Code 为例,AI 助手在三个时机调用 ok(其他 agent 经各自适配器等价触发):
| Hook | 何时执行 | 作用 |
|---|---|---|
UserPromptSubmit | 每条用户消息、模型调用之前 | 首次提问注入 mandatory + 索引;每次提问检索注入 |
PostToolUse | AI 用 Write/Edit 成功改完文件后 | 把改动文件记入会话状态 |
Stop | AI 每个回合即将结束时 | 改了代码没写日志 → exit 2 阻断(同会话同规则只阻断一次) |
~/.okryptos/ok.log),绝不影响正常会话。