kibi-mcp

提示意图，Kibi 让 Agent 记住它，并证明实现符合要求。

_{根据 Kibi 在各个案例中的报告简化而来。}

Kibi 是一个原生适用于 Agent 的需求编译器和强制执行层。你用自然语言描述产品意图；Agent 会创建并维护结构化需求、场景、测试、语义事实和代码链接。随后，Kibi 会检查实现是否始终与该意图保持一致。

与被动记忆或检索系统不同，Kibi 旨在融入 Agent 的工作流。Agent 无须记得去查阅工单、看板或需求文件夹：Kibi 的钩子、工具和验证关卡会持续将相关产品上下文带回工作中。

文档 · 快速入门 · Kibi 自身的健康报告

为什么选择 Kibi

大多数项目知识散落在提示词、工单、代码和对话中，而大多数 AI Agent 最终都会遗忘其中一部分。Kibi 将这些知识转化为可强制执行、与分支相关联的模型：

• 人类维护意图，而非产物 — 提示词是主要的编写界面。Agent 负责创建和演进需求、场景、测试、事实和符号链接等常规工作；人类负责解决真正的歧义并做出产品决策。
• 记忆可强制执行 — 符号需要归属需求，需求需要完整语义和场景，场景需要测试，而提供证明的测试需要最新的执行证据。
• Prolog 可防止偏离 — 类型化属性、谓词和安全规则可通过确定性检查，在矛盾、无依据的臆造和语义不完整被采纳为项目知识之前将其揭示出来。
• 端到端行为可追溯 — Kibi 记录端到端测试证明了什么，而不仅仅是它碰巧执行了哪些代码行。你可以从符号导航到其需求，也可以从测试导航到它验证的场景和意图。
• 意图在分支切换后依然保留 — 每个 Git 分支都有自己的 KB 快照，因此功能上下文彼此隔离，并会在你返回时保留。
• 支持多种语言 — 内置 TypeScript 和 JavaScript 符号支持。可选的 kibi-plugin-treesitter 使用固定版本的 WASM 语法，为 Python、Go、Rust、Java、C#、PHP、C、C++、Bash、Ruby 和 Terraform/HCL 添加离线符号提取功能。
• 可选的 UI 设计守护工具（实验性） — kibi-plugin-ui 让 React 和 Angular 组件遵循约定的设计模式。像素、颜色和间距仍由你的代码检查工具负责。
• 让知识留在本地 — KB 状态保存在仓库的 .kb/ 目录中；Kibi 软件包不会发送外部遥测数据或分析数据。只有文档网站会统计访问量，使用的是无 Cookie 的 Umami 分析服务。

快速开始

Kibi 旨在由你的编码 Agent 设置和驱动，因此推荐的安装方式是使用提示词，而不是一串命令。Kibi 需要 Node.js 22+。SWI-Prolog 已随附：在 Linux（x64 或 arm64，glibc 2.28+）和 macOS（Apple silicon 或 Intel）上，无需安装其他内容。在其他平台（例如 Alpine/musl 或原生 Windows；请使用 WSL）上，请安装 SWI-Prolog 9.0+，并将 swipl 加入 PATH（详情）。

推荐：让你的 Agent 代为设置。 将以下内容粘贴到 Claude Code、Cursor、Codex、OpenCode，或任何能在你的代码仓库中运行命令的编码 Agent 中：

Set up Kibi (https://github.com/Looted/kibi) in this repository, then bootstrap its knowledge base.

1. Install: confirm Node.js 22+ is available. With the package manager this repository already uses, add kibi-core, kibi-cli and kibi-mcp as dev dependencies. Do not skip optional dependencies; the bundled SWI-Prolog runtime is one.
2. Initialize: run every `kibi` command through the package manager's local runner (npm: `npm exec -- kibi <command>`). Run `kibi init`; if it reports a problem, run `kibi doctor` and fix what it names. If this platform has no bundled SWI-Prolog, tell me what to install and stop.
3. Connect: register the project-local `kibi-mcp` server for the agent host you are running in, following https://looted.github.io/kibi/guide/connect-an-agent.html. Prefer project-scoped configuration, and ask me before installing a plugin or changing global settings. Until the kb_* tools are visible to you, use Kibi's CLI JSON routes instead.
4. Bootstrap: run `kibi skills load kibi-bootstrap --format markdown` and follow that skill exactly. It starts by asking me where product intent lives outside the code (issue trackers, wikis, specs) and which sources to trust; read them through the connectors you have and cite them. Show me the complete plan and its hash, and write nothing until I approve it.
5. Verify: run `kibi check` and `kibi status`, fix anything they report, and summarize what was added. Do not commit; I will review the changes.

接下来会发生：

1. 设置。 Agent 安装软件包、运行 kibi init，并将自身连接到 Kibi。
2. 访谈。 它会询问产品意图目前存放在哪里（例如 Jira 或 YouTrack 等问题跟踪系统、维基、规格文档），以及应信任哪些来源。
3. 制定计划。 它通过现有连接器读取这些来源并起草初始化计划。计划中的每项需求都会注明其来源工单或页面。它发现的未决问题和来源间的冲突会标记出来供你处理，而不会将其转化为需求。
4. 由你审批。 它会向你展示计划及其哈希值。你批准前，不会写入任何内容。
5. 应用并检查。 它应用计划、验证结果，然后补充计划无法写入的内容，例如根据验收标准生成的场景，以及新需求对应的机器可检查事实。它会告知你新增了哪些内容。

之后就可以照常工作：提出功能、修复和重构需求，Agent 会让需求、场景、测试和代码链接与代码保持同步。

npm install --save-dev kibi-core kibi-cli kibi-mcp
npm exec -- kibi init

升级。 更新 Kibi 软件包后，运行 kibi migrate（或让你的 Agent 代为运行）。它会显示将要发生的更改，并且只有在你批准后才会应用；CLI 参考介绍了每个架构版本。

连接你的编码 Agent

上方的设置提示词已为你完成此步骤。若要手动操作：每个客户端都会启动同一个项目本地的 kibi-mcp 服务（npx --no-install kibi-mcp，stdio，工作目录 = 你的代码库）。可选插件还会添加内置技能和钩子。

claude plugin marketplace add Looted/kibi

claude plugin install kibi-claude@kibi

claude mcp add --scope project kibi -- npx --no-install kibi-mcp

{
  "mcpServers": {
    "kibi": {
      "command": "npx",
      "args": ["--no-install", "kibi-mcp"]
    }
  }
}

codex mcp add kibi -- npx --no-install kibi-mcp

codex plugin marketplace add Looted/kibi

{
  "mcp": {
    "kibi": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "--no-install", "kibi-mcp"]
    }
  },
  "plugin": ["kibi-opencode"]
}

{
  "servers": {
    "kibi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--no-install", "kibi-mcp"]
    }
  }
}

Agent 可获得的能力

Kibi 的技能子系统为 Agent 提供六项内置技能，教它如何使用 Kibi，因此你无需粘贴冗长的系统提示词；少量 MCP 工具即可完成其余工作：

• 用通俗语言回答问题。 询问“什么规定了结账舍入？”，kb_search 会返回当前需求、相关测试和决策，以及 Kibi 检查结果。
• 审查每项更改。 对 Agent 修改过的文件运行 kb_check，即可查看代码实现的需求，并标记没有需求覆盖的新代码。
• 安全写入。 每次写入都可先预览；你批准的计划要么全部生效，要么完全不生效。

MCP 参考列出了所有工具。通用 Agent 可从 Agent 入门指南开始。

查看每项保证的力度

npm exec -- kibi report --open

kibi report 会根据一次覆盖率快照生成独立完整的 kibi-report/index.html 和 kibi-report/badge.svg。% tested 表示当前需求中，在当前代码上有最新端到端证据支持的比例；报告会列出已测试的内容、缺少证据的内容、相互矛盾的内容，以及已过时的内容。

每项需求还会标注证据等级，因此保证的表述不会强于其依据：proved（需求中的每项声明对所有情况都成立，并由来自 exhaustive、typecheck、arithmetic、smt、rule、state_machine、regex 或 source 证明契约的最新证书支持；契约会指明声明，另一个独立检查器会重新验证证书。声明不必是数字：权限规则、适用于每个成员的属性、状态转换、永远无法到达的状态、必填字段和字符串格式，都会依据代码精确判定；source 证明会检查 Kibi 从项目自身读取的路由、数据库架构、配置、验证器和代码引用）、tested（最新端到端回执覆盖所有关联场景）、asserted（有人为其背书，但目前没有任何检查机制验证）和 unverified（由 Agent 编写，且未经任何人批准）。kibi coverage 会为每项需求返回 evidenceLevel，并在 summary.evidenceLevels 中统计各等级数量；报告和 kibi signoff 会在确定程度旁显示证据等级。请参阅证明阶梯、证明需求（了解证书证明类型），以及阅读报告。

知识库本身也会以相同方式接受检查。kibi check（Agent 使用的命令为 kb_check）会证明需求中陈述的事实彼此一致（某个属性上的所有事实都能由同一个值满足，每项决策都有一个结果），并确认存储的规则是分层的；它还会为每个答案生成一份证书，由一个小型独立检查器重新验证。它也能发现只有合在一起才会产生矛盾的事实，这是两两检查无法发现的。出现矛盾时，会返回无法同时成立的最小事实集合；任何无法进行比较的内容都会报告为未解决，而绝不会报告为一致。

在批准变更之前，kibi signoff 会显示新增、重写或受影响的需求，并逐项注明其确定程度、证明状态和证据等级；kibi signoff --questions 会为待你处理的决策编号，并显示每项决策会改变的规则。Agent 会在回复中以纯 Markdown 呈现此视图，因此无论 Agent 在哪里撰写回复，都能正常渲染，包括通过消息工具传递回复的聊天应用和云端会话；同一视图也会作为独立完整的页面保存在 .kb/briefs/signoff/latest.html 中。Claude Code、Cursor、ZCode 和 OpenCode 会添加 /kibi-signoff 命令，OpenCode 会以卡片形式呈现此视图，VS Code 会在面板中打开它；Agent 钩子会在会话写入需求后请求生成此视图。

若要将报告和可点击徽章发布到 GitHub Pages，请运行 npm exec -- kibi init --github，然后启用 Settings → Pages → Source → GitHub Actions。GitHub 集成指南涵盖了报告工作流、仅发布徽章，以及在只有 Kibi 自身文件发生冲突时仍确保拉取请求可以合并的 CI 步骤。符号的行位置绝不会提交：每次 kibi sync 都会将其生成到 Git 忽略的缓存中，因此两个分支即使编辑同一个源文件，也不会因这些位置发生冲突。

日常检查可使用 CLI 参考中的 kibi status、kibi search、kibi gaps、kibi coverage 和 kibi check。

工作原理

Kibi 将概率式解读与确定性验证相结合：

Human prompt
    |
    v
Agent updates code and product knowledge
    |
    v
Requirements + semantic facts/rules + scenarios + tests + symbol links
    |
    v
Prolog coherence checks + traceability gates + fresh E2E evidence
    |
    v
Tested result or explicit, repairable gaps

Agent 绝不会将任意 Prolog 代码当作可信事实来编写。它会通过类型化事实、谓词模式和安全的逻辑表示来工作；Kibi 会在 Prolog 层使用这些编码进行推理之前先验证它们。

Kibi 强制执行的规则

Kibi 会维护规范的可追溯性与证明链：

Requirement -> Scenario -> Test
     ^                       ^
     |                       |
 Production symbol     Executable test symbol

要让一项需求经过端到端测试，而非仅记录在案：

• 每个生产符号都必须追溯到其实现的需求。
• 每条规范性需求条款都必须建模为类型化事实，或明确标记为尚未解决。
• 需求必须通过场景进行说明，测试必须验证这些场景。若成功场景假设了当前需求所禁止的行为，则会阻止证明。
• 可执行测试符号必须标明实际执行验证的代码。
• 承载证明的生产符号必须由符合要求的测试覆盖，且提交前钩子采用与完整检查相同的规则。
• 端到端证据必须是最新的，并与当前代码快照绑定，确保 CI 与同一提交的本地检出结果一致。

这样一来，就能双向回答以下问题：哪个需求对应此符号、此端到端测试实际验证了什么、哪些需求缺少场景或当前证据，以及当前有哪些需求彼此矛盾。仅靠代码覆盖率无法回答这些问题：它只能说明测试触及了某一行代码，而不能说明测试验证了哪种产品行为。

Prolog 作为安全层

假设产品明确规定只有三种用户角色。一旦将此约束编码为严格属性或谓词，Agent 就无法悄悄虚构第四种角色并将其当作已确认的意图：Kibi 可以确定性地指出矛盾或缺失的授权。

如果 Kibi 无法判断，它不会报告“无冲突”。数值约束会进行精确比较（“大于 0”与“等于 0”相冲突），针对同一操作的允许与拒绝规则互相矛盾，而任何 Kibi 无法建模的内容都会报告为待解决事项，交由 Agent 审查，绝不会被当作验证通过。

Prolog 不会判断最初的人类意图是否正确。它会验证已编码的知识，而 Kibi 会明确标示歧义、本体缺失、依据不完整和证据过时，而不是将它们称为证明。

为什么现在能够实现

传统知识库需要专家设计本体、编写形式逻辑，并手动维护每一项映射。大模型改变了这类编写工作的成本，而 Kibi 和 Prolog 则提供了严谨性：

最终方案利用大模型的优势来应对大模型的弱点：记忆有限、幻觉、上下文漂移，以及产品与代码之间的映射丢失——过去，这种映射分散在产品负责人、工单系统和规划看板中。

Kibi 建模的内容

八种实体类型：req、scenario、test、fact、adr、flag、event 和 symbol。实体架构包含完整的模型。

每个实体都会记录其作者是某个人还是某个 Agent；建议性检查会列出尚未得到任何人批准的 Agent 编写的需求。

需求和 ADR 还会说明其决策的确定程度。firm 规则由人明确提出：它会指向其原话，Agent 在更改前会先询问，而且 Kibi 不会悄悄重写它。default 选择可以根据证据重新审视，exploratory 则表示猜测。每次取代旧决定时，都必须说明更改原因。Kibi 的工作方式介绍了详细信息。

软件包

在项目中安装 kibi-core、kibi-cli 和 kibi-mcp。其他所有软件包均为可选。

文档

指南和参考文档发布于 https://looted.github.io/kibi/。语言模型可以从文档索引开始查阅。

• 安装 — 随附的 SWI-Prolog 运行时、软件包管理器、插件和验证
• Kibi 的工作方式和证明阶梯
• 证明需求 — 证明契约、kibi prove 和回执
• CLI 参考和MCP 参考
• 实体架构和推理规则
• 架构 — 存储、分支隔离和数据流
• 故障排除

Beta 状态

Kibi 目前处于 beta 阶段，已可用于真实项目。1.0 版本发布前，公共接口仍可能演进；如需确保可复现性，请固定确切的软件包版本。

Kibi 根据 AGPL-3.0-or-later 许可。