humanagentprotocol

HAP——人类代理协议

人类和自主人工智能代理之间共生协作的通用协议。

HAP使AI代理能够以结构化、可审计和延迟安全的方式请求人类决策。代理从不阻塞——它们创建具有定义超时行为的票证，允许优雅的降级或升级。

______________________________________________________________________

______________________________________________________________________

共享SQLite数据库 (~/.hap/hap.db)连接所有组件。MCP服务器将HAP操作作为任何AI代理都可以调用的工具公开。人类通过CLI或桌面应用程序批准/拒绝。

快速开始

1.安装

git clone https://github.com/spinualexandru/humanagentprotocol.git
cd hap
npm install

2.运行测试

npm test

3.配置您的AI工具

克劳德代码

已通过配置 .mcp.json 在项目根中。或者在全球范围内添加：

claude mcp add --transport stdio hap-bridge -- npx tsx packages/mcp-server/src/index.ts

用HAP替换克劳德的内置审批系统：

添加a PreToolUse 挂钩到你的项目 .claude/settings.local.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx /path/to/hap/packages/cli/src/hook.ts",
            "timeout": 310000
          }
        ]
      }
    ]
  }
}

现在，每个工具调用（Bash、Edit、Write等）都会创建一个HAP票证，而不是显示Claude的标准权限提示。只读工具（Read、Glob、Grep）是自动批准的。编写/执行工具块，直到您批准：

[HAP] Ticket tk_a1b2c3 created — Run command: npm test
[HAP] Approve: hap approve tk_a1b2c3 | Reject: hap reject tk_a1b2c3

从另一个终端或Tauri应用程序批准——克劳德立即继续。

风险按工具类型评分：

Codex CLI

# Add to your Codex MCP configuration
codex mcp add hap-bridge --stdio -- npx tsx /path/to/hap/packages/mcp-server/src/index.ts

开源代码

添加到您的OpenCode MCP配置中：

{
  "mcpServers": {
    "hap-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/path/to/hap/packages/mcp-server/src/index.ts"],
      "env": { "HAP_HUMAN_ID": "human:yourname" }
    }
  }
}

VS代码副本

增添 .vscode/mcp.json 或用户设置：

{
  "servers": {
    "hap-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/path/to/hap/packages/mcp-server/src/index.ts"],
      "env": { "HAP_HUMAN_ID": "human:yourname" }
    }
  }
}

Copilot命令行界面

使用与VS代码副本相同的MCP配置。

4.使用CLI

# List pending tickets
npx tsx packages/cli/src/index.ts inbox

# Show ticket details
npx tsx packages/cli/src/index.ts show tk_abc123

# Approve a ticket
npx tsx packages/cli/src/index.ts approve tk_abc123 "LGTM"

# Reject a ticket
npx tsx packages/cli/src/index.ts reject tk_abc123 "Needs tests"

# Acknowledge (pause timer)
npx tsx packages/cli/src/index.ts ack tk_abc123 "Reviewing..."

# Verify event log integrity
npx tsx packages/cli/src/index.ts verify

5.构建Tauri桌面应用程序

cd packages/tauri-app
npm install
cargo tauri dev     # Development mode
cargo tauri build   # Production build

MCP工具

MCP服务器将这些工具暴露给AI代理：

门票生命周期

PENDING → DELIVERED → ACKED → APPROVED / REJECTED / CHANGES_REQUESTED
    ↓          ↓         ↓
    └──────────┴─────────┴──→ CANCELED (from any non-terminal state)
                              EXPIRED  (from PENDING or DELIVERED on timeout)

• 租赁计时器 从已送达开始，在确认时暂停
• 超时时: auto_approve, auto_reject，或 cancel
• 风险评分：基于变更范围、环境和置信度的0.0-1.0
• 高风险 （≥0.7）：需要升压确认(typed_confirmation="approve production")

环境变量

包裹

事件日志

所有操作都会生成一个仅追加的事件日志，其中包含SHA-256哈希链，用于完整性验证：

npx tsx packages/cli/src/index.ts events   # View event log
npx tsx packages/cli/src/index.ts verify   # Verify integrity

许可证

协议规范：CC BY 4.0 参考运行时：Apache 2.0