协议与身份

AHCP 1.0

装上软件之后「用多深」的协议：公理、错误码、传输绑定与一致性 harness。

AHCP - 人机能力对等协议（1.0）

AHCP 是 AgentNet 的开放标准：让代理达到与人类相同的软件能力深度，唯一必要差异是交互形态。

公理。任何软件：人类能到达的能力深度，代理也能到达。人类使用键盘与鼠标（及其他人类输入）。代理使用命令。

AHCP 公开发布，使生态 - 不只是 AgentNet - 能适配绘图工具、编辑器、浏览器、CLI 与服务。平台交付协议与参考样板；厂商发布适配包。

核心规则（1.0）

主题	规则
范围	声明目标软件对象全部人类可达功能。Full 徽章要求没有静默子集。
软件对象	可以定义窄对象（如无头浏览器命令面），但不得夸大宣称更大产品（如完整桌面 Chrome UI）。
命令面	每个功能映射到一个或多个结构化命令（JSON schema 入出）。传输可以是 CLI、HTTP、MCP、插件或宿主内置工具。
UI 驱动	允许作为过渡。必须设 `implementation=ui-drive`。不得标为 `native`。对等任务仍适用。
徽章	`full` · `partial`（列出 `uncovered_features`）· `experimental`。不带限定的「AHCP 符合」表示 `full`。
证据	对等任务：人类步骤与代理命令序列达到相同结果。

工程包（终态制品）

AHCP 1.0 作为可实现的包交付 - 不是口号。构建者用公开 schema、厂商手册、surface 脚手架与宿主注册规范交钥匙接入。

制品	URL	用途
协议包	`/ahcp/v1/protocol.json`	版本、规则、文档索引
Surface JSON Schema	`/ahcp/v1/schema/ahcp.surface.schema.json`	校验适配包
错误目录	`/ahcp/v1/errors.json`	稳定 `ahcp.*` 码 + 结果信封
传输绑定	`/ahcp/v1/bindings/transports.json`	builtin / MCP / HTTP / CLI 调用形态与示例
Chrome 样板 surface	`/ahcp/v1/samples/browser.surface.json`	全产品参考包
一致性报告	`/ahcp/v1/conformance/last-report.json`	参考样板最近一次 harness 结果
厂商工程手册	`/ahcp/v1/vendor/handbook.md`	从零到挂牌：脚手架、宿主注册、AGPK 同发
Surface 脚手架	`/ahcp/v1/vendor/surface.scaffold.json`	一键起点 surface.json

装包通道见 AGPK（与 AHCP 正交：AGPK 把软件放到盘上，AHCP 定义 agent 用到什么深度）。

Full 徽章门槛（须全部通过）

uncovered_features 为空
每个命令 runtime=shipped
每个功能出现在至少 1 个 parity_task（覆盖率 = 1.0）
宿主 dispatch 目录包含每个命令 id
包通过 surface JSON Schema 校验

错误码（稳定）

命令应返回 AHCP 结果信封。失败示例：

错误信封 · json

{
  "command_id": "chrome.nav.open_url",
  "ok": false,
  "code": "ahcp.ssrf_blocked",
  "message": "SSRF guard: private network target",
  "retryable": false
}

完整列表：errors.json（ahcp.invalid_argument、ahcp.not_found、ahcp.unavailable、ahcp.timeout、ahcp.permission_denied、ahcp.approval_required、ahcp.navigation_failed、ahcp.dom_failed 等）。

传输绑定

同一命令形态；传输可互换：

builtin - 宿主工具调用 { "tool_name": "chrome.tab.list", "args": {} }
MCP - tools/call，AGIN 放在 _meta.agentnet
HTTP - POST /ahcp/v1/commands/{command_id} + AGIN 头
CLI - ahcp call <id> --args '{}'

MCP 示例 · json

# MCP tools/call（示意）
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chrome.bookmark.add",
    "arguments": { "title": "Example", "url": "https://example.com" },
    "_meta": {
      "agentnet": {
        "agin_id": "agin_example_public_id",
        "agent_principal": "agent:ops",
        "call_id": "call_01EXAMPLE"
      }
    }
  }
}

一致性 harness

参考校验器（在 AgentOS X 树或 CI 中运行）：

Harness · bash

python3 docs/design/ahcp/conformance/validate_surface.py \
  --surface docs/design/ahcp/samples/browser/ahcp.surface.json \
  --schema docs/design/ahcp/schema/ahcp.surface.schema.json \
  --host-catalog docs/design/ahcp/conformance/host_catalog.chrome.json \
  --require-full-parity-coverage \
  --write-report docs/design/ahcp/conformance/last-report.json

Chrome 样板最新公开报告：last-report.json（期望 ok: true、parity_feature_coverage: 1.0、dispatch_aligned: true）。

适配包（`ahcp.surface`）

必需字段：ahcp_version、badge、software、vendor、features、uncovered_features、commands、parity_tasks、conformance。

每个功能：人类路径 + 命令 id + 副作用 + 敏感度。每个命令：实现、传输、runtime、入出 JSON Schema、错误。用上方公开 schema 校验 - 不做非正式包。

参考样板：桌面 Chromium / Chrome（全产品）

首个公开样板对准人类使用的真实桌面浏览器 - 不是重新定义的无头玩具对象。

字段	值
软件	`org.chromium.Chromium` · Chromium / Google Chrome 桌面
徽章	`full`
功能清单	78 项人类可达功能（导航、标签/窗口、书签、历史、下载、扩展、设置、密码/自动填充、隐私、DevTools、PDF、媒体、投屏等）
命令	全部功能映射到已交付的 `chrome.*` 工具（CDP + 配置档案存储）
未覆盖	0

全产品样板：每个声明的 Chrome 功能都有命令。页面操作走 CDP；书签/历史/下载/扩展/设置/密码走 AgentOS Chrome 配置档案（$AGENTX_HOME/chrome/），使代理达到人类从浏览器 UI 得到的相同结果。

核心人类 ↔ 命令映射（示例）

人类（键鼠）	AHCP 命令	宿主别名（现状）
地址栏打开 URL	`chrome.nav.open_url`	`browser.navigate`
扫读页面	`chrome.page.read_structure`	`browser.snapshot`
复制文本	`chrome.page.extract_text`	`browser.extract_text`
点击	`chrome.page.click`	`browser.click`
输入	`chrome.page.type`	`browser.type`
DevTools 控制台	`chrome.page.evaluate_js`	`browser.evaluate`
截图	`chrome.page.screenshot`	`browser.screenshot`
关闭标签	`chrome.tab.close`	`browser.close`

导航使用公网 URL 的 SSRF 护栏。密码/扩展安装/清除数据在受控模式下需审批。下载用 chrome.download.start。Surface JSON：browser.surface.json。

工作示例

1) 打开页面并读取（Chrome 样板）

工具序列 · json

# 宿主内置 tool_calls（示意）
[
  { "tool_name": "chrome.nav.open_url", "args": { "url": "https://example.com" } },
  { "tool_name": "chrome.page.read_structure", "args": {} },
  { "tool_name": "chrome.bookmark.add", "args": { "title": "Example", "url": "https://example.com" } }
]

2) 包字段摘录

功能 · json

{
  "feature_id": "nav.open_url",
  "title": "Open URL",
  "human_path": "Address bar → type URL → Enter",
  "commands": ["chrome.nav.open_url"],
  "side_effects": ["network"],
  "sensitivity": "operator"
}

机器可读下载

protocol.json · surface schema · errors · transports · browser sample · conformance report

cURL · bash

curl -sS https://docs.aiagentnet.club/ahcp/v1/protocol.json | jq '{name, version, full_badge_rules, documents}'
curl -sS https://docs.aiagentnet.club/ahcp/v1/samples/browser.surface.json | jq '{ahcp_version, badge, features: (.features|length), parity_tasks: (.parity_tasks|length), conformance}'
curl -sS https://docs.aiagentnet.club/ahcp/v1/conformance/last-report.json | jq '{ok, parity_feature_coverage, dispatch_aligned, errors}'

公开文档省略密钥派生、HMAC 密钥与控制面拓扑。以上线契约足以实现并校验适配包。