kcp-harness — KCP compliance proxy

kcp-harness

🧾 查看运行效果 — 交互式 KCP 演练场 · 阅读揭秘文章

适用于任何 AI Agent 的确定性知识治理。

你的 Agent 可以读取项目中的每个文件。它能证明自己为何读取这些内容吗？

KCP Harness 是一个 MCP 合规代理，位于 AI 编码 Agent 与其工具之间。它会拦截与知识相关的调用，通过 kcp-agent 确定性规划器（14 道关卡级联，无 LLM）进行路由，并在 Agent 正常运行的过程中生成合规性产物——决策跟踪记录、审计日志、预算账本。

Agent 无法绕过治理，因为它只能通过代理的 MCP 接口进行通信。代理决定哪些知识可以访问、跟踪支出，并记录每项决策。默认拒绝：如果 harness 无法验证请求，Agent 将无法获取任何内容。

Agent (Claude Code / Cursor / Copilot / Windsurf / Cline / Crush / OpenClaw / ...)
  │
  │  MCP tool call
  v
┌─────────────────────────────────────────────────────────┐
│  kcp-harness                                            │
│                                                         │
│  classify → govern (14 gates) → execute → audit         │
│                                                         │
│  Side outputs:                                          │
│  · Decision traces     (per-request, deterministic)     │
│  · Audit log           (append-only JSONL)              │
│  · Budget ledger       (itemized, ceiling-enforced)     │
│  · Temporal drift      (plan validity over time)        │
│  · Approval tickets    (named-human sign-off, durable)  │
│  · Confidence verdicts (post-synthesis gate)            │
└─────────────────────────────────────────────────────────┘
  │
  v
Knowledge manifests (knowledge.yaml)

文档 →

为什么需要

企业需要可辩护的 Agent——可审计、可复现、受预算控制，并且在时间维度上有明确约束。如今的 Agent 无法证明自己为何读取这些内容。harness 增加了合规层，但不会取代 Agent。

你保留的内容	harness 增加的内容
你的 Agent（Claude Code、Cursor、Copilot，……）	确定性知识选择
你的工作流（编码、审查、交付）	决策跟踪记录（每个单元 14 道关卡）
你的工具（MCP 服务、shell、浏览器）	预算执行（上限，按币种分别计算）
	时间治理（漂移检测）
	仅追加的审计日志
	回放 / 交叉质询
	人工审批关卡（指定审查者 + 策略引用）
	置信度关卡（综合后执行，转交人工处理）

你销售的是合规层。Agent 可插拔。

安装

npm install -g kcp-harness

也可以不安装，直接使用：

npx kcp-harness --help

原生可执行文件

为 Linux x64/arm64、macOS x64/arm64 和 Windows x64 提供预构建二进制文件（无需 Node/Deno） ——可从发行版获取。也可以自行构建：

npm ci && npm run build
deno compile --allow-read --allow-env --allow-net --allow-run \
  --node-modules-dir=auto --output kcp-harness dist/cli.js

快速开始

1. 初始化

kcp-harness init          # creates harness.yaml

2. 生成 Agent 集成配置

kcp-harness integrate claude-code    # or: pi, cursor, copilot, windsurf, cline, continue, crush, openclaw

3. 开始编码

现在，你的 Agent 会通过 harness 路由知识访问。每项决策都会被记录。

支持的 Agent

Agent	配置	集成方式
Claude Code	.mcp.json + PreToolUse 钩子	kcp-harness integrate claude-code
Cursor	.cursor/mcp.json + .mdc 规则	kcp-harness integrate cursor
GitHub Copilot	.vscode/mcp.json（使用 "servers" 键）	kcp-harness integrate copilot
Windsurf	全局配置 + .windsurfrules	kcp-harness integrate windsurf
Cline	MCP 设置 + .clinerules	kcp-harness integrate cline
Continue	.continue/mcpServers/*.yaml	kcp-harness integrate continue
Crush	crush.json + PrepareStep	kcp-harness integrate crush
OpenClaw	openclaw.json + 插件钩子	kcp-harness integrate openclaw
Pi	.pi/mcp.json + 项目技能	kcp-harness integrate pi

每种 Agent 都有自己的 MCP 配置格式、规则文件和特性。integrate 命令会处理所有这些差异——一个治理层，适用于任何 Agent。

工作原理

每次工具调用都会经过一个五阶段流水线：

1. RECEIVE      MCP JSON-RPC request from agent
2. CLASSIFY     Knowledge-navigation or pass-through?
3. GOVERN       14-gate cascade (audience → temporal → budget → ...)
4. EXECUTE      Call downstream tool / return content
5. AUDIT        Log decision to append-only audit log

分类器

分类器会检查每次工具调用，并判断其是否针对受治理的知识。 Read("docs/api.md") 中的 docs/ 受治理？通过规划器路由。Read("package.json") 中的 package.json 不受治理？直接放行。KCP 工具（kcp_plan、kcp_load）始终受治理。

Governor

两种自动化模式，以及一个优先级高于两者的人工审核关卡：

• 先规划（快速路径） — Agent 首先调用 kcp_plan。运行框架会缓存已批准的 计划。后续读取会根据缓存的计划进行检查 — 无需重新规划。
• 自动规划（回退路径） — Agent 未先规划便读取受治理的路径。运行框架会自动运行 规划器。速度较慢，但即使 Agent 不知道 kcp_plan，也能强制执行治理。
• 人工审批 — 匹配 governance.approvals 规则的调用会交由指定的 审核者处理（pending），无论自动化路径会作出什么决定。工单会在重启后保留，并可通过 kcp-harness approvals CLI（或任何自定义的 ApprovalProvider 渠道）处理。处理时必须指定审核者，并引用政策依据。

14 道关卡的级联

每个知识单元都会依次通过 14 道确定性关卡进行评估：

audience → not_for → temporal → deprecated → supersession → relevance →
skill_eligibility → attestation → payment → access → strict → max_units →
money_budget → context_budget

一个单元必须通过所有关卡。阻止它的关卡会记录在决策跟踪记录中。相同 输入 → 相同计划。不涉及模型。

对于 skill_eligibility 关卡的适用主题 — 受治理的 kind: skill 单元 — 其 编写规范、检查器和符合性向量位于 Cantara/kcp-skill。

MCP 工具

连接后，Agent 可以使用以下治理工具：

工具	描述
kcp_plan	确定性加载计划 — 包括要加载哪些单元、按什么顺序加载，以及哪些单元被跳过及原因
kcp_load	规划并加载符合条件的单元内容
kcp_trace	完整的 14 道关卡决策跟踪记录
kcp_validate	检查 knowledge.yaml
harness_status	当前治理状态
harness_session	此会话的已批准计划和已知单元
harness_budget	明细支出跟踪
harness_temporal_check	计划偏移检测
harness_approvals	人工审批工单（待处理 / 已批准 / 已驳回 / 已过期）
harness_assess	在采取行动前，为合成答案进行置信度关卡检查

合规性产物

审计日志

仅追加的 JSONL。每项决策 — 无论是否受治理 — 都会记录序列号、 时间戳、工具、目标和治理决策：

cat .kcp-harness/audit.jsonl | jq 'select(.governed == true)'

预算台账

仅追加的明细支出跟踪。按货币统计累计总额。强制执行上限 — 如果加载操作会 超出预算，则会原子性地拒绝该操作（不进行部分加载）。

时间治理

计划会注册到时间监视器。后续调用时，监视器会根据当前时间重新评估。 如果单元发生偏移（已过期或新近有效），运行框架会发出偏移 事件。长时间运行的会话也能保持可靠。

审批工单

符合审批规则的调用会创建一张持久化工单 （pending_review → approved | dismissed | expired，被使用的一次性授权还会变为 used）。工单存储会在重启后保留 — 会话是临时的，人工审核则不是。每次决议都会记录 谁 批准、何时 批准，以及满足 哪项策略 — 这些证据在审批时生成，绝不从日志中重建。

审批是有期限的授权，绝不是长期权限。 它仅适用于创建工单的会话、确切的工具和目标，以及调用参数摘要 — 并且会失效。每条规则设置 grant: once | session | <duration>（默认值为 session），且始终受 governance.approvals.grant_max 限制（默认值为 24h）。不在有效授权范围内的调用会被拒绝，审计记录为 grant_denied（expired、wrong_session、used 等），并创建一张新工单。长期权限应通过策略规则定义，而不是靠点击授予。授权期限从存储自身的时钟开始计算，而不是从审核者提供的 reviewedAt 开始；工单的第一个有效决议会生效（已驳回的工单不能通过追加一行重新批准）；启用 approvals.require_signed_resolutions 后，每次读取时都会验证签名，而不只是在 resolve() 中验证；启用 approvals.require_args_binding 后，不接受未绑定调用参数的工单所授予的授权。工单存储无法保护的内容 — 对其目录的写入权限 — 详见工单存储信任模型。另请参阅治理模型。

置信度判定

harness_assess 会在合成答案可供采取行动之前，对其运行 kcp-agent 的后合成 assess()。规划器控制加载，依据 grounding 控制断言，而此项控制行动。对于已路由的配置，低于阈值的判定会创建审批工单，并将完整判定嵌入为证据。

配置

# harness.yaml
version: "1.0"

governance:
  domains:
    - manifest: "./knowledge.yaml"
      paths: ["docs/", "src/"]

  policy:
    fail_closed: true
    audit_all: true
    max_units: 5
    budget:
      amount: 1.00
      currency: USDC

  confidence:                  # optional post-synthesis gate (harness_assess)
    threshold: 0.7
    severity: critical
    route_to_role: account-owner

  approvals:                   # optional human-approval gates
    provider: file
    rules:
      - match: { tools: [Write, Edit], paths: [records/] }
        required_role: account-owner
        expires_after: 72h
        policy_ref: POL-7.2
        grant: session           # once | session | 15m / 4h / 1d  (default: session)
    grant_max: 24h               # hard cap on any approval's validity (default 24h)
    # require_signed_resolutions: true  # + trusted_keys: verify signatures on every read (recommended)
    require_args_binding: true   # refuse grants not bound to the call's arguments (recommended)

audit:
  path: ".kcp-harness/audit.jsonl"

CLI

kcp-harness serve  [--config harness.yaml]   Start the MCP proxy
kcp-harness init                             Create a harness.yaml template
kcp-harness check  [--config harness.yaml]   Validate configuration
kcp-harness integrate <agent> [options]       Generate agent integration files
kcp-harness integrate --list                  List supported agents
kcp-harness export   [options]               Export compliance evidence (SOC 2 / ISO 27001)
kcp-harness dashboard [options]              Launch the live compliance dashboard
kcp-harness approvals list [--state s]        List human-approval tickets
kcp-harness approvals approve <id> --reviewer <name> --policy-ref <ref>
kcp-harness approvals dismiss <id> --reviewer <name> --policy-ref <ref>

库

import { classify, govern, BudgetLedger, TemporalWatch } from "kcp-harness";
import { generate, listAgents } from "kcp-harness";

// Classify a tool call
const result = classify("Read", { file_path: "docs/api.md" }, governedDomains);

// Generate integration files
const output = generate("claude-code", { manifest: "./knowledge.yaml", paths: ["docs/"] });

架构

┌──────────────────────────────────────────────┐
│  Layer 3: Integration Packages               │
│  Agent-specific configs + rules files        │
│  (claude-code, cursor, copilot, ...)         │
├──────────────────────────────────────────────┤
│  Layer 2: KCP Compliance Harness             │  ← THIS
│  MCP proxy — deterministic governance        │
├──────────────────────────────────────────────┤
│  Layer 1: kcp-agent (planner core)           │
│  14-gate cascade, decision traces            │
└──────────────────────────────────────────────┘

Fork Agent 会让你陷入竞争；Harness 则让你融入协作。

测试

npm test     # 314 tests across 20 test files

涵盖分类器、治理器（包括审批优先级）、审批状态机和提供程序、置信度门控接线、代理、审计、预算账本、时间监控、证据导出、仪表板，以及所有 Agent 集成。

许可证

Apache-2.0 · 由 eXOReaction AS 提供，托管于 Cantara。