文档

Okryptos 是为 AI 编程助手提供的项目知识库:知识按项目隔离,通过 hooks/扩展自动注入 AI 上下文,并可强制执行工作流规则。

五分钟上手

从安装到第一次检索注入

经验沉淀

AI 提议、人批准的草稿流程

实现原理

混合检索与 hook 时序

安装与首次引导

三种安装方式任选其一,详见首页安装区。安装完成后运行首次引导(幂等,可重复执行):

ok setup            # 或只装某个 agent:ok setup --agent zcode

ok setup 依次完成三件事:

  1. 写入 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 不可阻断致强制检查降级)
  2. 安装六个技能——ok-init / on / off / propose / capture / wiki,写入各 agent 的技能目录
  3. 配置 embedding——交互询问 base_url / model / API key,写入全局配置并当场验证连通性;回车跳过则只用关键词检索
注意hooks 在会话启动时加载:安装或变更配置后,需要新开一个 AI 助手会话才会生效。

快速开始

# 在需要使用知识库的项目目录里
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 助手会话即可生效:

也可以在会话里直接说「初始化知识库」「关闭知识库 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 切换:

常用命令

命令作用
ok setup首次引导:hooks 配置 + 技能安装 + embedding 配置
ok gui启动 Web 管理界面(双击 exe 无参数运行同效)
ok init [名字]注册当前项目,并幂等写入/更新 hooks 配置
ok add新建知识条目(自动重建索引与向量)
ok propose / ok approveAI 提议草稿 / 批准转正
ok capture [...]查看/切换沉淀模式,配置轮次间隔
ok wiki status|mark|base|diffwiki 状态 / 记游标 / 基准分支 / 分支差异素材
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 停止常驻服务。四个标签页:

配置

生效配置 = 内置默认 ← 全局 ~/.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:

1 万条条目下单次查询约 30ms;embedding 服务不可用时自动降级为纯关键词检索,注入永不缺席。实现细节见架构文档第 17 章。

工作原理

以 Kimi Code 为例,AI 助手在三个时机调用 ok(其他 agent 经各自适配器等价触发):

Hook何时执行作用
UserPromptSubmit每条用户消息、模型调用之前首次提问注入 mandatory + 索引;每次提问检索注入
PostToolUseAI 用 Write/Edit 成功改完文件后把改动文件记入会话状态
StopAI 每个回合即将结束时改了代码没写日志 → exit 2 阻断(同会话同规则只阻断一次)
说明所有 hook 路径 fail-open:任何内部错误只记日志(~/.okryptos/ok.log),绝不影响正常会话。