Kāhea

Kāhea

网站 · 文档 · 版本发布 · Agent 插件 · MCP 元数据

Kāhea 是一个本地优先、确定性的 API 调用内核，专为编码 Agent 设计。

意图可以是概率性的，调用必须精确。

它将 OpenAPI 描述、请求捕获记录、Arazzo 工作流和有限 WebSocket 会话转换为完整性密封计划。调用是独立操作，受精确的能力授权约束；响应和入站帧则会成为类型化观测结果和内容寻址证据。

安装 Kāhea

请选择适合你主机的方式。Claude Code、OpenAI Codex 和直接连接的 MCP 客户端都使用相同的四个本地 MCP 工具，并遵循相同的“检查 → 计划 → 授权 → 调用 → 取证”安全约定。

1. 安装原生二进制文件

从 GitHub Releases 下载适用于你的操作系统和架构的归档文件。每个归档文件都附带 SHA-256 校验和、CycloneDX SBOM 和 GitHub 构建来源证明。请在安装前验证校验和，并通过以下方式验证来源证明：

gh attestation verify kahea-ARCHIVE --repo copyleftdev/kahea

Kāhea 不会运行安装程序，也不会修改 shell 配置。解压归档文件，并将 kahea 二进制文件放在 PATH 中的某个位置。

带标签的归档文件会在 GitHub 托管的 Linux、macOS 和 Windows 运行器上，针对相应运行器的架构进行构建和测试。有关 WebSocket 支持和发布门槛的确切说明，请参阅有限 WebSocket 指南。

2a. Claude Code

将此代码仓库添加为市场，然后安装插件：

claude plugin marketplace add copyleftdev/kahea
claude plugin install kahea@kahea

2b. OpenAI Codex

添加同一市场代码仓库和规范插件包：

codex plugin marketplace add copyleftdev/kahea
codex plugin add kahea@kahea

两个插件都要求 PATH 中存在经过验证的 kahea 二进制文件。它们会添加规范的 Agent 使用技能，并启动本地 stdio MCP 服务，不会在运行时下载代码或凭据。共享的主机软件包位于 plugins/kahea；不会为特定主机单独维护安全工作流副本。

2c. 任意 MCP 客户端

配置客户端，通过 stdio 启动 Kāhea：

command: kahea
args: mcp serve --stdio

带标签的版本还会发布独立且带校验和的 MCPB 软件包，并在官方 MCP 注册表中注册 io.github.copyleftdev/kahea。

从源代码构建

要从源代码构建，请安装 Rust 1.95 或更高版本：

cargo build --release -p kahea

构建与验证

仓库在 rust-toolchain.toml 中固定了发布工具链。

scripts/gates.sh
# Requires cargo-mutants; run locally, not in CI.
scripts/mutation-gate.sh

发布门禁还会启动已植入种子的本地回环 WebSocket oracle，通过公共 CLI 规划其生成的有限会话，使用计划中精确指定的授权调用它，并验证客户端观察结果以及 oracle 可复现的种子/用例观察结果。使用 scripts/websocket-oracle-smoke.sh 重放此生命周期；使用 kahea-test-server --protocol websocket --websocket-fault FAULT --seed SEED 选择单个故障。

变异门禁受资源限制，不会拖垮工作站。它运行 4 个任务，通过 GNU jobserver 限制所有任务的编译器并发数，将构建副本放在磁盘路径而非 tmpfs TMPDIR 中；如果用户会话总线可用，还会在受 CPU 和内存限制的临时 systemd 作用域内运行。可通过 KAHEA_MUTANT_JOBS、KAHEA_MUTANT_TASKS、KAHEA_MUTANT_CPU_QUOTA、KAHEA_MUTANT_MEMORY_HIGH、KAHEA_MUTANT_MEMORY_MAX、KAHEA_MUTANT_SCRATCH、KAHEA_MUTANT_COPY_TARGET 或 KAHEA_MUTANT_UNCONFINED=1 覆盖这些设置。

每个变异版本都通过整个工作区测试套件进行评判；该套件覆盖全面，但运行缓慢，因此范围很重要。KAHEA_MUTANT_PACKAGES 用于选择要进行变异测试的软件包（默认全部 4 个），KAHEA_MUTANT_EXTRA 用于传入其他参数，例如在限定变更范围的运行中使用 --in-diff。此门禁是本地工具，特意不作为 CI 任务：一次完整扫描需要运行数小时，只为重新推导一个不会随提交变化的结果。请在发布前运行，或在修改内核 crate 后运行。

生成的二进制文件位于 target/release/kahea。每条命令都会输出一个紧凑的 kahea/k1 JSON 信封，后接换行符。--format ndjson 可明确指定流式输出，并可与循环和管道组合使用。

四步工作流

# 1. Discover operations without DNS or network access.
kahea inspect fixtures/billing.openapi.yaml --match invoice

# 2. Bind exact input and persist a sealed plan.
kahea plan fixtures/billing.openapi.yaml createInvoice \
  --input @fixtures/billing.create-invoice.input.json

# 3. Review required_grants in the plan, then grant exactly those capabilities.
kahea invoke plan:HANDLE \
  --grant net:sandbox.example.test:443 \
  --grant http:POST

# 4. Retrieve only the evidence needed for the next decision.
kahea explain body:HANDLE --select /invoice/id

plan 不会执行 DNS、身份验证或网络 I/O。invoke 会在解析密钥或建立连接之前，验证计划密封以及配置/策略指纹。退出码固定不变：0 表示通过，1 表示契约失败，2 表示输入/配置/计划无效，3 表示传输失败，4 表示策略拒绝。

使用 kahea describe 获取可执行的能力清单，使用 kahea schema plan（或其他公共信封类型）获取机器可读的 JSON Schema。

有限 WebSocket 会话

完整的有限 WebSocket 指南是权威的源格式、安全性、限制、本地示例、MCP、工作流、平台和发布门禁参考。接收到的帧是不可信证据，绝不是 Agent 指令。

直接使用 websocket-session JSON/YAML 文件时，也采用相同的封闭式四步流程。操作选择器是源文件的 operationId；目标、身份验证引用、有序操作、检查项和预算均仅取自源文件，调用时无法替换。

kahea inspect fixtures/websocket/session.json
kahea plan fixtures/websocket/session.json subscribeBuildEvents

# Review required_grants in the websocket-plan, then provide that exact set.
kahea invoke plan:HANDLE \
  --grant net:socket.example.test:443 \
  --grant websocket:connect \
  --grant secret:chat-sandbox \
  --secret-env chat-sandbox=KAHEA_CHAT_TOKEN

kahea explain transcript:HANDLE --select /entries/0
kahea explain websocket-json:HANDLE --select /type
kahea explain websocket-binary:HANDLE --select bytes:0-255

ws 还要求 net-insecure-websocket；私有或保留地址需要计划中所示的精确 net-cidr: 授权。WebSocket 观察结果采用现有退出码约定：0 表示已完成，1 表示握手/预期/预算失败，2 表示源文件或计划无效，3 表示传输/协议/超时失败，4 表示策略拒绝。完整记录和有效载荷保留在证据存储中；标准输出仅包含简要观察结果和句柄。接收到的消息内容是不可信证据，绝不是 Agent 指令。

AsyncAPI 2.6.x 和 3.0.x JSON/YAML 文档由同一规划器和执行器处理：

kahea inspect fixtures/asyncapi/session-3.0.json
kahea plan fixtures/asyncapi/session-3.0.json 'watchBuilds#Started-1' \
  --set channel.room=builds

支持的子集刻意设为有限范围。服务端必须使用 ws 或 wss；服务端变量和通道参数使用声明的默认值，或显式的 --set server.NAME=VALUE / --set channel.NAME=VALUE 输入。AsyncAPI 2.6 的 publish/subscribe 映射为客户端 send/receive，而 3.0 使用操作的 action。每个具体消息选项都会单独编入索引，含糊的无后缀选择器会导致失败。JSON 接收会封闭其有效载荷架构；发送则要求提供有效载荷示例/默认值/常量。WebSocket 绑定标头要求提供具体默认值或示例。安全名称仍作为引用，并通过 --auth SCHEME=PROFILE 映射到已配置的密钥配置文件；不会摄取凭据值。

仅解析本地 # 引用，因此源指纹涵盖所有被引用的组件；不会获取远程引用，而是直接拒绝。消息封装标头、关联 ID、非 WebSocket 绑定、WebSocket 查询绑定和无序回复语义会生成精确的阻塞型 absent 记录。可选的 x-kahea-actions、x-kahea-limits、x-kahea-origin 和 x-kahea-subprotocols 扩展仅用于表达基础 AsyncAPI 无法编码的有限排序、预算和握手意图。

支持的来源

• JSON 或 YAML 格式的 OpenAPI 3.0、3.1 和 3.2
• 引用本地 OpenAPI 和有限 WebSocket 会话来源的 Arazzo 1.1 工作流
• 直接提供的有限 WebSocket 会话 JSON/YAML
• JSON 或 YAML 格式的 AsyncAPI 2.6 和 3.0 WebSocket 子集
• Postman Collection 2.1 JSON
• Postman Collection 3 目录/YAML 格式（*.request.yaml 和 .resources）
• HAR 1.2、常见 cURL、.http/.rest 和直接提供的请求 YAML/JSON
• 确定性文本格式的标准输入：kahea inspect -

“支持”是指可以确定性地检测和检查该格式，并能为其文档所述子集生成封存计划。这并不意味着会模拟上游应用的所有功能。未支持的重要行为会报告在 absent 中；仅当已知其作用范围时，才会阻止受影响的请求。

Postman 2.1 导入嵌套请求、字符串和结构化 URL、非敏感的集合/文件夹变量、继承的 basic/bearer/OAuth 风格 bearer/API 密钥元数据（不含凭据值）、原始正文、响应示例，以及范围有限的状态断言子集。Postman v3 导入 *.request.yaml/*.request.yml、请求顺序、根级和嵌套的 definition.yaml 变量/认证元数据、标头和原始正文。v3 脚本会作为请求级阻止项处理；v3 示例和未知资源文件目前会明确列为阻止项，而不会被静默丢弃。非原始 Postman 正文模式、未解析的密钥变量、不支持的认证方式以及重要 JavaScript 都会阻止相应请求。Kāhea 不会嵌入 Node，也不会执行 pm.* 代码。HAR 响应和 Postman 2.1 响应示例会转换为结构化契约，绝不会复制响应中的密钥。

fixtures/corpus 中固定的离线语料库涵盖 Swagger Petstore、Swagger Generator、PokéAPI、OpenAI、httpbin、OpenAPI 3.0–3.2、JSON/YAML、大型架构、安全方案、回调、Webhook、二进制媒体类型，以及一个有意设置的 Swagger 2 拒绝示例。导入测试样例位于 fixtures/imports，Arazzo 示例位于 fixtures/workflows。公共测试样例仅用于描述，测试套件绝不会调用它们。

输入和正文

输入文档可以将值分组到 path、query、header、cookie 和 body 下。对于仅有正文的操作，文档本身可以作为正文。可使用可重复的 --set LOCATION.NAME=JSON_OR_TEXT 设置精确覆盖值。

Kāhea 支持规范 JSON、text/XML、form-urlencoded、确定性 multipart 和 base64 二进制正文。Multipart 文件字段使用封存描述符：

{
  "body": {
    "file": {
      "$file": "./artifact.bin",
      "filename": "artifact.bin",
      "content_type": "application/octet-stream"
    },
    "label": "release-candidate"
  }
}

规划期间会读取文件；其字节和 multipart 边界都会纳入正文摘要和计划封印中。调用时不会重新读取该文件。

认证和密钥

计划只包含配置文件引用，例如 secret://billing/sandbox。调用时通过指定环境变量来解析配置文件——绝不要将其值放入 CLI/MCP 参数中：

kahea plan api.yaml createInvoice --auth bearerAuth=billing/sandbox
kahea invoke plan:HANDLE \
  --grant secret:billing/sandbox \
  --secret-env billing/sandbox=KAHEA_BILLING_TOKEN \
  --grant net:api.example.com:443 \
  --grant http:POST

Bearer 和 API 密钥配置文件包含原始令牌；basic 配置文件包含 username:password；mTLS 配置文件包含 PEM 身份材料。OAuth 客户端凭据和刷新配置文件是包含 client_id 以及 client_secret 或 refresh_token 的 JSON 字符串。OAuth 令牌端点有各自规划的网络/HTTP授权。重定向和环境代理均已禁用，DNS 响应会经过策略检查并固定，私有/保留地址需要精确的 CIDR 授权，凭据绝不会附加到未规划的源站。

在持久化证据前，会对已解析的密钥值、派生的敏感标头、配置的敏感响应标头以及配置的响应 JSON Pointer 进行脱敏。

配置和策略

Kāhea 默认加载 .kahea/config.toml，也可以通过显式指定 --config 加载。请参阅 examples/config.toml 和 examples/policy.toml。

可以将命名服务归类为生产环境。向生产环境源站写入数据需要 approve:production-write；破坏性操作还需要 approve:destructive。主机允许/拒绝列表、最大请求字节数、响应脱敏、风险覆盖项、默认值以及仅保存密钥的身份验证引用，都会纳入密封配置/策略指纹。使用不同策略的调用会在访问网络前被拒绝。

声明式检查

默认会添加 OpenAPI 状态码和响应架构检查。重复使用 --check 可提供显式检查集：

status:200
status:any(200,201,204)
content-type:application/json
response-schema:openapi
header:X-Request-Id:exists
header:X-Mode=ready
json-pointer:/data/id:exists
json-pointer:/data/count:type=integer
json-pointer:/data/state="ready"
jsonpath:$.data[*]:exists
xpath:/root/item:exists
body-digest:b3:...
response-bytes:max:1048576
latency-ms:max:500

任何未知检查都会被安全拒绝。验证详情会作为证据保存，并影响退出代码 1。

Arazzo 工作流

使用相同的命令检查和规划 Arazzo：

kahea inspect fixtures/workflows/billing.arazzo.yaml
kahea plan fixtures/workflows/billing.arazzo.yaml createAndReadInvoice \
  --input @fixtures/workflows/billing.input.json
kahea invoke workflow-plan:HANDLE --grant ...

V1 支持有序 HTTP 和有限 WebSocket 步骤、前序步骤依赖、有界运行时绑定、聚合风险和精确授权、有界重试/结束操作、工作流级和步骤级超时上限、密封子计划以及每次尝试的观测树。HTTP 源使用 type: openapi，而直接 WebSocket 源描述使用规范扩展 x-kahea-source-kind: websocket-session（不带容易造成误解的 Arazzo type），并通过源的 operationId 选择操作。请参阅 fixtures/workflows/mixed.arazzo.yaml。

WebSocket 步骤仅通过 x-kahea-websocket-bindings 绑定先前步骤的输出。每个绑定都会指定 /actions/N/ 下一个现有的 JSON Pointer，并且只能替换 text、payload_base64、equals 或 reason；调用时不能更改目标、身份验证、限制、架构、操作顺序和操作标识。WebSocket 输出支持握手和关闭元数据、按操作索引指定的匹配消息（text、json、json#/pointer、base64 或 evidence），以及用于转录、握手和跟踪的证据句柄。整个转录不会自动成为输入。二进制数据仍须显式使用证据句柄或 base64 值。密钥配置文件引用会通过密封子计划传递，不会将密钥值实体化。

HTTP 步骤还支持 operationPath、请求输入、简单/JSONPath/XPath 成功条件，以及响应正文输出。AsyncAPI 工作流源描述、回调、人工审批节点、分布式调度、嵌套工作流步骤、goto 和可复用操作组件仍明确暂不支持。

确定性一致性模糊测试

conform 是 Kāhea 原生的单二进制工具，对标 Python 工具，例如 Schemathesis。它会在不访问网络的情况下，从 OpenAPI 操作推导出有界的正向和负向用例，将每个精确请求密封为普通计划，并保存可重放的测试活动：

kahea conform fixtures/conformance/widgets.openapi.yaml updateWidget \
  --cases 32 --seed 42 --mode mixed --delay-ms 25

kahea invoke conformance-plan:HANDLE \
  --grant conformance:execute:32 \
  --grant conformance:negative \
  --grant net:api.example.test:443 \
  --grant http:POST

正向用例会测试架构示例、枚举、联合类型、对象/数组形状、格式，以及有界的字符串、数值和集合边界。负向用例会省略必需值，或引入一个指定的类型、枚举、长度、未知属性或参数违规。响应预言机会拒绝 5xx 响应，根据声明的状态码/内容/架构契约检查每个响应，并验证负向数据是否收到符合规范的 4xx 拒绝响应。发现的问题会关联到各个用例的证据和精确请求计划句柄。

种子、用例数、请求间隔、失败上限、策略、请求摘要、策略指纹和授权都会纳入测试活动密封。相同种子会生成逐字节完全相同的测试活动。生成上限为 256 个请求；遇到复杂架构关键字或需要显式基线值的二进制输入时会安全拒绝。使用 --input 和 --set 固定资源标识符，或提供有界生成器无法推断的值。

动态生命周期预言机

仅用于测试的 kahea-test-server 会在每次启动时创建不同的 API，发布该实例的确切 OpenAPI 3.1 契约，并通过单独的运行时验证器强制执行相同的预置场景。每个 API 包含 3 到 6 个操作，涵盖 GET、POST、PUT 和 PATCH；路径和操作 ID 随机生成；包含路径、查询和标头参数；JSON 请求体；枚举、布尔值、有界字符串、受约束的整数；以及成功和拒绝响应。

通过以下命令运行多轮黑盒生命周期测试：

scripts/dynamic-conformance.sh 25

每次迭代都会在操作系统分配的环回端口上启动，等待原子就绪清单，检查每个生成的操作，规划并执行混合一致性测试活动，验证每个操作都收到有效和无效流量，并通过每次启动专属的控制令牌关闭服务。每次运行都会打印产物路径和重放种子。失败可精确复现：

KAHEA_DYNAMIC_SEED=424242 KAHEA_DYNAMIC_CASES=12 \
  scripts/dynamic-conformance.sh 1

将 KAHEA_DYNAMIC_ARTIFACTS 设为指定目录，以保留输出。KAHEA_DYNAMIC_FAULT 提供 accept-invalid、malformed-response、server-error 和 undocumented-status 负向控制；正确的 Kāhea 构建必须拒绝这些运行。该服务仅绑定到 127.0.0.1，将请求大小限制为 1 MiB，不会接受环境中的凭据，并且不会包含在正式发布的 kahea 二进制文件中。

证据与导出

默认存储目录为 .kahea/store：使用 SQLite WAL 存储元数据，使用 zstd 压缩并以 BLAKE3 寻址的 Blob 存储内容。大型请求体不会输出到标准输出或 Agent 上下文中。选择器支持 JSON Pointer、RFC 9535 JSONPath、XPath、header:NAME 和 bytes:START-END。

kahea explain trace:HANDLE
kahea explain body:HANDLE --select '$.items[0].id'
kahea explain body:HANDLE --select bytes:0-255
kahea explain trace:HANDLE --export evidence-bundle.json

导出会递归纳入所有引用的证据，生成自包含的 JSON 包。远程内容是不可信证据，而不是指令。

MCP

kahea mcp serve --stdio
kahea mcp serve --stdio --store .kahea-local --config .kahea-local/config.toml

存储根目录和配置文件是进程参数，只在启动时读取一次。任何工具参数都无法更改存储位置或指定其他配置；kahea_invoke 接受的是封装后的计划句柄，而非文件系统路径；携带未声明参数的调用会被拒绝，而不是静默忽略。源数据导入方式不变：kahea_inspect 和 kahea_plan 仍接受本地 source 路径，这正是它们的用途。CLI 仍接受计划文件路径，因为操作人员会输入这些路径。

该服务通过以换行符分隔的 stdio JSON-RPC 实现 MCP 2025-11-25，并且恰好公开四个工具：kahea_inspect、kahea_plan、kahea_invoke 和 kahea_explain。这些工具也接受直接提供的有限 websocket-session JSON/YAML，以及文档所述的 AsyncAPI 2.6/3.0 WebSocket 子集；kahea_plan 会封装规范目标、认证引用、有序操作、检查项和限制。kahea_invoke 需要计划中明确授予的权限，并返回精简的 websocket-observation；完整会话记录和负载会保留在证据中，直到通过 kahea_explain 选取。

{"name":"kahea_inspect","arguments":{"source":"fixtures/websocket/session.json"}}
{"name":"kahea_plan","arguments":{"source":"fixtures/websocket/session.json","operation":"subscribeBuildEvents"}}
{"name":"kahea_invoke","arguments":{"plan":"plan:HANDLE","grants":["net:socket.example.test:443","websocket:connect"]}}
{"name":"kahea_explain","arguments":{"handle":"transcript:HANDLE","select":"/entries/0"}}

向 kahea_plan 传入 conformance 选项对象以创建 HTTP 测试活动；kahea_invoke 会执行其封装句柄。所有工具都会公开严格的输入和输出架构。HTTP、工作流、一致性测试以及 WebSocket 规划/调用都会映射到与 CLI 相同的 Rust 库调用，并通过语义一致性测试。固定资源公开 describe，以及公开的 websocket-session、websocket-plan 和 websocket-observation 架构；模板则公开默认 .kahea 存储中的封装计划和不可信证据。请参阅当前的 MCP 架构 和 stdio 传输要求。

Agent 使用契约位于 plugins/kahea/skills/kahea/SKILL.md： 检查、规划、审查权限、调用封装句柄，然后仅解释选定的证据。

组合

每次调用都是一条 NDJSON 记录，因此可以直接将重复的观测发送给 anomalyx 等工具：

for run in $(seq 1 100); do
  kahea --format ndjson invoke plan:HANDLE --grant net:api.example.com:443 --grant http:GET
done | anomalyx scan --format ndjson

要进行环境比较，请针对具名服务器创建计划，保留其配置／来源指纹，并比较观测流，而不是可变的集合状态。

架构与限制

工作区将协议类型（kahea-core）、数据摄取、规划、执行、证据、工作流、MCP 和 CLI 分离，同时仅发布一个二进制文件。解析器和传输类型不会泄漏到公共封装中。

OpenAPI 引用会在已加载的文档中解析。规划期间绝不会获取远程引用。Postman v3 目录最多可包含 10,000 个文件／64 MiB，并会拒绝符号链接；单个文本源限制为 64 MiB，并设有深度／节点限制。HAR 导入要求版本为 1.2，Postman JSON 导入要求集合架构为 2.1。HTTP 重定向会被拒绝，而非跟随。工作流重试必须显式声明，且最多为 10 次。

产品需求请参阅 KAHEA_PRD_v1.0.md。Arazzo 行为遵循官方 Arazzo 1.1 规范，Postman v3 目录处理遵循当前的 Postman 集合架构文档。