@agentsgot/agent-kit 0.0.0-stage → 1.0.1

package/docs/reference/02-INTERFACES.md

@@ -0,0 +1,487 @@
+# 跨端接口契约
+
+本文是实现前的契约骨架。约束、错误与顺序属于 interface 的一部分；后续实现不得只保持类型签名却改变语义。数值规则引用 `01-RULES §一–§十`，参数值来自 `shared/params/params.json`。
+
+> 本版本依据产品规格书全面重写，将档位日费制、多执行者竞争、复核阶段、逐条评分系统纳入接口定义。
+
+## 1. 共享领域类型
+
+以下类型由 `shared` 的 **zod schema 实现**，TypeScript 类型从 schema 推导；跨进程传输的 `bigint` 使用十进制字符串，时间使用带时区 ISO 8601，链上地址使用校验过的 `0x` 十六进制字符串。
+
+**金额单位（01-RULES §0.3）：** 本文所有金额字段、合约参数、事件字段与 EIP-712 字段的单位都是 AGT wei（`1 AGT = 10^18 wei`），以十进制整数字符串或 `uint256` 表示，字段名中的 `Agt` 后缀也表示 wei。只有 `shared/params/params.json` 存人类可读 AGT，`shared` 用 `agtToWei(value: number): bigint` 在计算前换算一次。协议不读取任何价格，不存在 USD 字段。
+
+### 1.1 枚举
+
+枚举成员与 01-RULES §〇 一一对应；下表列出序列化值（UPPER_SNAKE），代码常量名使用 01-RULES 的 PascalCase。
+
+| 类型 | 序列化值 | 约束与说明 |
+|---|---|---|
+| `Role` | `PUBLISHER \| EXECUTOR \| TESTER \| REVIEWER \| ARBITRATOR` | 测试者、复核者与仲裁者共用验证者质押，同一任务内角色互斥 |
+| `Tier` | `T1 \| T2 \| T3 \| T4 \| T5` | 档位，决定日费与名额 |
+| `AcceptanceGrade` | `A \| B \| C` | 验收条件等级 |
+| `AllocationMode` | `WINNER_TAKES_ALL \| TOP_K \| PRO_RATA` | 发布者选定的分配模式 |
+| `TaskTemplate` | `CODE_FIX \| DATA_PROCESSING \| TRANSLATION \| RESEARCH \| CUSTOM` | 任务模板，影响最低档位 |
+| `TaskStatus` | `PUBLISHED \| RUNNING \| GRACE \| CLOSED \| TESTING \| REVIEWING \| RESULT_POSTED \| ACCEPTED \| DISPUTED \| APPEALED \| MAINTENANCE \| COMPLETED \| CANCELLED \| EXPIRED \| NO_SUBMISSION \| INSUFFICIENT \| FAILED` | 只允许协议状态机定义的单向迁移 |
+| `ValidatorStatus` | `ACTIVE \| GRACE \| INACTIVE \| COOLING_DOWN` | 验证者质押状态 |
+| `ArbitrationRound` | `FIRST \| FINAL` | 一审 / 终审（申诉） |
+
+已废弃枚举：`Difficulty`、`Channel`、`ExecutionMode`、`ExecutorTier`、`Reputation`、`EmissionStage` 不再使用。
+
+### 1.2 `Criterion`
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| `id` | `string` | 1–128 chars，任务内唯一 | 条件标识 |
+| `description` | `string` | 1–4096 chars | 可判定的陈述 |
+| `grade` | `AcceptanceGrade` | — | A 须附 machineCheck |
+| `weightBps` | `number` | 0–10000，全部条件之和 = 10000 | 权重 bps |
+| `machineCheck?` | `MachineCheck` | A 级必填 | 机器校验 |
+
+### 1.3 `TaskSpec`（v3）
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| `version` | `"AGENTGRID_TASK_SPEC_V3"` | — | 版本标记 |
+| `title` | `string` | 1–200 chars | 标题 |
+| `summary` | `string` | 1–8000 chars | 概括 |
+| `template` | `TaskTemplate` | — | 任务模板，影响最低档位 |
+| `deliverables` | `string[]` | ≥ 1 | 交付物 |
+| `outOfScope` | `string[]` | — | 排除范围 |
+| `constraints` | `string[]` | — | 约束 |
+| `inputs` | `TaskInput[]` | — | 输入 |
+| `criteria` | `Criterion[]` | ≥ 1，权重和 10000 | 验收条件 |
+| `estimatedHours` | `number` | > 0 | 预估工时 |
+| `startTier` | `Tier` | ≥ minimumTier, ≤ rangeMax | 起始档位 |
+| `maxTier` | `Tier` | ≥ startTier, ≤ rangeMax | 最高档位 |
+| `runDays` | `number` | 正整数，须在两个档位的天数范围交集内 | 运行天数 |
+| `allocationMode` | `AllocationMode` | — | 分配模式 |
+| `topK?` | `number` | 正整数，仅 TOP_K 时必填 | 前 K 名 |
+| `passingThreshold` | `number` | 50–90，默认 60 | 及格线 |
+| `criticReportHash?` | `Hex32` | — | AI 批评者报告哈希 |
+
+### 1.4 `TaskDraft`
+
+草稿字段镜像 TaskSpec，额外包含：
+
+| 字段 | 来源 | 说明 |
+|---|---|---|
+| `minimumTier` | `rule` | 规则引擎计算的最低档位 |
+| `cost` | `rule` | `{ reserve, dailyFee }` |
+
+每个字段携带 `value | null`、`source: user|ai|rule`、`confirmation: unconfirmed|confirmed|suggested`。
+
+### 1.5 扣费去向（经济模型 v3）
+
+任务扣费 `C` **100% 进入 `PlatformTreasury`**，不拆给执行者 / 测试者 / 复核者。争议标的 `V = deductionExecBps · C / 10000`（默认 65% · C）只用于案件锁定与容量拦截，不是报酬拆分。
+
+### 1.6 `VestingTranche`
+
+| 字段 | 说明 |
+|---|---|
+| `kind` | `DEDUCTION \| EMISSION` |
+| `amount` | AGT (decimal string) |
+| `releaseAt` | ISO 8601 |
+| `status` | `LOCKED \| CLAIMABLE \| CLAIMED \| CLAWED_BACK` |
+
+### 1.7 `EmissionHour`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `hourId` | number | Unix 小时编号 |
+| `emission` | decimal string | 连续曲线在该小时的释放量 |
+| `allocatedAmount` | decimal string | 已分配给参与者 |
+| `burnedAmount` | decimal string | 结算确认未获配后销毁 |
+| `activeTaskCount` | number | 该小时活跃任务数 |
+
+---
+
+## 2. 规则引擎纯函数（`shared/src/rules/`）
+
+所有函数为纯函数，不依赖 I/O、随机性或时钟。参数由 `Params` 注入。返回的 `bigint` 金额均为 wei；读取 `params.json` 中的 AGT 金额参数时统一经 `agtToWei`（`shared/src/units.ts`，整数与最多 18 位小数，`0.5 → 5 × 10^17`）。
+
+| 函数 | 输入 | 输出 | 说明 |
+|---|---|---|---|
+| `computeMinimumTier` | criteria, estimatedHours, template | `Tier` | 01-RULES §3.4 |
+| `computeTierRangeMax` | minimumTier, params | `Tier` | min(minimum + offset, 5) |
+| `computeReserve` | maxTier, runDays, params | `bigint` | F_max × D |
+| `computeDeduction` | lockedTier, billedSeconds, params | `bigint` | F_t × s / 86400 |
+| `computeSegmentedDeduction` | segments[], params | `bigint` | 分段计费 |
+| `resolveParticipantLimit` | maxParticipants, params | `number \| null` | 未传值取默认 9；`0` → `null`（不限）；否则须落在 `[participantsMin, participantsMax]` |
+| `computeSubmissionScore` | criterionScores[], threshold, params | score, passes, isJunk | 逐条汇总 |
+| `allocateExecutorPool` | pool, scores[], mode, topK? | AllocationResult[] | 三种分配模式 |
+| `vestingSchedule` | amount, acceptedAtSeconds, params | tranches[] | 60/25/15% |
+| `cumulativeReleased` | schedule, timestamp | released | 连续半衰期曲线 `R(t)`，无每日上限 |
+| `hourShares` | schedule, hourId | `HourShares` | 小时发行按 10/65/15/10 四向切分 |
+| `computeEscalationStep` | runDays, params | seconds | 档位递增步长 |
+| `computeCurrentTier` | startTier, maxTier, publishedAt, now, step | `Tier` | 当前档位 |
+| `computeEarliestSubmitSeconds` | runDays, params | seconds | 最早提交时间 |
+| `checkPublisherStake` | actualStake, reserves, params | required, ok | 发布者质押校验，`required = agtToWei(publisherBaseStakeAgt) + β × reserves` |
+| `validatorRoleMinimum` | role, params | `bigint` | 测试者 `testerMinStakeAgt`、仲裁者 `arbitratorMinStakeAgt`，wei |
+| `validatorDrawWeight` | stake, role, params | `bigint` | `min(stake, 角色权重上限)`，线性 |
+| `computeTesterMissReportSlash` | reward, stake, params | `bigint` | `min(倍数 × 应得报酬, 上限比例 × 质押)` |
+| `computeDisputeBound` | reserve, params | `bigint` | `reserve × deductionExecBps`，发布拦截用 |
+| `computeMaxDisputeValue` | pool, params | `bigint` | 与 `CourtRules.maxDisputeValue` 一致 |
+| `splitOverturnPenalty` | confiscated, caseFee, finalMajorityCount, params | challenger, platform, righteous | 申诉方 `min(倍数 × R, Z)`，剩余 30/70 |
+| `computeCaseLock` | disputeValue, stake, params | `bigint` | 01-RULES §5.1 |
+| `computeCaseFee` | disputeValue, params | `bigint` | 01-RULES §7.3 |
+| `arbitrationPanel` | eligibleArbitrators, round, params | panelSize, majority | 仲裁面板 |
+| `checkDraft` | draft, params | RuleCheckResult[] | 草稿综合校验 |
+| `antiWashCheck` | params | ok | 防刷不等式 |
+
+---
+
+## 3. 协议合约接口
+
+### 3.1 合约架构
+
+| 合约 | 职责 |
+|---|---|
+| `ParamRegistry` | 存储链上可调参数；升级权限管理 |
+| `TaskEscrow` | 任务发布、预留锁定、扣费计提、退款释放 |
+| `SubmissionRegistry` | 提交登记、提交根上链（提交免费） |
+| `TesterDraw` | 测试者抽签、报告锁定、复核触发 |
+| `ReviewerDraw` | 复核者抽签、结果上链 |
+| `RewardVesting` | 分期释放、维护期缺陷回收 |
+| `ArbitrationCourt` | 争议仲裁（承诺-揭示投票）、申诉、保证金/罚没 |
+| `EmissionHours` | 连续曲线的小时发行与分配（平台 10% / 执行 65% / 测试 15% / 仲裁 10%，无每日上限） |
+| `PublisherStaking` | 发布者基础质押与预留管理 |
+| `ValidatorStaking` | 验证者质押、锁定、退出冷却 |
+| `AgentRegistry` | 执行者链上身份惰性登记 |
+
+### 3.2 TaskEscrow 核心函数
+
+```solidity
+function publishTask(
+    bytes32 specHash,
+    uint8 startTier,
+    uint8 maxTier,
+    uint32 runDays,
+    uint8 allocationMode,
+    uint8 passingThreshold,
+    bytes calldata publisherProof
+) external returns (uint256 taskId);
+
+function claimTask(uint256 taskId) external;
+
+function closeSubmissions(uint256 taskId) external;
+
+// createTask: maxParticipants = 0 means unlimited; otherwise it must be >= participantsMin (uint16).
+
+struct RootPayees {
+    bytes32 executorsRoot;    // sorted-pair Merkle root of keccak256(abi.encode(taskId, executor, share))
+    uint32 executorCount;     // <= maxParticipants unless unlimited
+    uint256 totalShares;      // == proof.executorPoolPi when P_i > 0
+    address primaryExecutor;  // largest share; target of maintenance-defect burn
+    address[] testers;        // <= 32 recorded testers (role exclusion and tester payout record)
+    address[] reviewers;      // reviewers drawn by the backend (01-RULES §4.9)
+}
+struct ShareClaim { address executor; uint256 share; bytes32[] proof; }
+
+// Step 1: Post validated settlement result; moves status to ResultPosted,
+// starts publisherReviewHours countdown. Does NOT distribute funds.
+// proof.resultsHash MUST equal keccak256(abi.encode(keccak256("AGENTGRID_RESULTS_ROOT_V1"), taskId,
+// executorsRoot, executorCount, totalShares, primaryExecutor, testers, reviewers)).
+function postResultRoot(SettlementProof calldata proof, RootPayees calldata payees, PiProof calldata piProof) external;
+// After settlement anyone may vest up to 50 leaves per call; each leaf vests once, always to its executor.
+function claimExecutorShares(bytes32 taskId, ShareClaim[] calldata claims) external returns (uint256 vested);
+function rootResultOf(bytes32 taskId) external view returns (RootResult memory);
+function executorShareClaimed(bytes32 taskId, address executor) external view returns (bool);
+
+// Step 2: Publisher calls anytime to accept; anyone calls after reviewDeadline.
+// Executor pool vests (T0 claimable), tester pool → TesterAssignment.payout, reviewer pool split
+// equally among reviewers (remainder → ArbitrationPool), platform → PlatformTreasury,
+// R − C → PublisherStaking.refund (publisher stake, never the wallet).
+function acceptResult(bytes32 taskId) external;
+
+// Publisher or a posted executor opens an appeal inside the review window; pays appealFee
+// = min(appealFeeBps × F_{t*}, appealFeeCapAgt), 100% to revealed jurors.
+// An executor proves its leaf with (share, proof); the publisher passes (0, []).
+function openAppeal(bytes32 taskId, bytes32 reasonHash, bytes calldata caseProof, uint256 share, bytes32[] calldata proof)
+    external returns (bytes32 caseId);
+// A posted executor waives its appeal right (irreversible: openAppeal then reverts AlreadyWaived);
+// once every executor waives (waiveCount == executorCount), the window closes early.
+function waiveAppeal(bytes32 taskId, uint256 share, bytes32[] calldata proof) external;
+// Publisher opens a maintenance-period defect dispute on an accepted task.
+function openMaintenanceDispute(bytes32 taskId, bytes32 reasonHash, bytes calldata caseProof) external;
+// Tester mining seat: amount comes from the backend-signed EIP-712 TesterSeatClaim(taskId, tester, amount,
+// nonce, deadline) (POST /rewards/tester-seat-claim-intents), pulled from EmissionController tester escrow;
+// one claim per (taskId, tester).
+function claimTesterSeat(bytes32 taskId, uint256 amount, uint256 nonce, uint64 deadline, bytes calldata signature)
+    external returns (uint256 paid);
+function testerSeatClaimed(bytes32 taskId, address tester) external view returns (bool);
+// ArbitrationCourt callbacks: ruling pays testers, splits reviewer pool with the majority panel and
+// refunds the publisher stake per 01-RULES §4.6; a maintenance defect claws back unreleased tranches.
+function onCourtRuling(bytes32 taskId, IArbitrationCourt.Ruling ruling, uint16 executorAwardBps) external;
+function onMaintenanceDefect(bytes32 taskId) external returns (uint256 clawedBack);
+
+// Publisher may replace the off-chain specification hash once while Published.
+// Economic fields stay frozen at createTask. Deliveries signed before amendedAt keep prior criteria.
+function amendSpec(bytes32 taskId, bytes32 newSpecHash) external;
+function amendedAtOf(bytes32 taskId) external view returns (uint64);
+// cancel() permanently reverts (CancellationDisabled). Historical Cancelled tasks still use
+// claimCancellation / finalizeCancellation. Unclaimed / expired tasks use expireTask or settleNoSubmission.
+```
+
+金额只读视图（全部返回 wei）：
+
+```solidity
+// TaskEscrow：发布时写入的五档日费快照，tier 为 1–5
+function taskDailyFeeWei(bytes32 taskId, uint8 tier) external view returns (uint256);
+// TaskEscrow：结果上链后的争议标的 V 与申诉费 min(appealFeeBps × F_{t*}, appealFeeCapAgt)
+function disputeAmounts(bytes32 taskId) external view returns (uint256 disputeValue, uint256 appealFeeAmount);
+// ArbitrationCourt：案件费 max(caseFeeBps × V, caseFeeMinAgt)；prepareCase 用它复核传入值
+function quoteCaseFee(uint256 disputeValue) external view returns (uint256);
+// ArbitrationCourt：已开案件的申诉保证金 = caseFee × appealBondMultiplierBps / 10000
+function appealBondOf(bytes32 caseId) external view returns (uint256);
+// PublisherStaking：P_min(wei) + publisherExposureBps × exposureAgt / 10000
+function requiredStake(address publisher) external view returns (uint256);
+// TaskEscrow：维护期争议标的（结算时实际授予执行者的金额）与案件 id
+function maintenanceOf(bytes32 taskId) external view
+    returns (address executor, uint256 disputeValue, bytes32 caseId, uint64 maintenanceEnd, bool finalized);
+// ArbitrationSettlement：裁决多数派陪审员，合议庭份额按人均分
+function rulingMajority(bytes32 caseId) external view returns (address[] memory);
+```
+
+仲裁者治理白名单（`ArbitrationSelection`，01-RULES §2.3）：
+
+```solidity
+// 仅 ParamRegistry.GOVERNANCE_ROLE；空列表或零地址 revert InvalidAddress，非治理 revert NotGovernance(caller)。
+// whitelisted=true：标记并直接入池（未在池中时发 ArbitratorJoined），豁免质押时长与一致测试门槛；
+// whitelisted=false：仅取消豁免，地址留在池中按常规资格判定。
+function setArbitratorWhitelist(address[] calldata accounts, bool whitelisted) external;
+function whitelistedArbitrator(address account) external view returns (bool);
+// 是否可被抽中仍以 drawWeight(account) > 0 为准（需 Active 验证者质押）
+function drawWeight(address juror) external view returns (uint256);
+```
+
+### 3.3 关键事件
+
+```solidity
+event TaskPublished(uint256 indexed taskId, address indexed publisher, uint8 startTier, uint8 maxTier, uint32 runDays);
+event TaskClaimed(uint256 indexed taskId, address indexed executor, uint8 lockedTier);
+event TierEscalated(uint256 indexed taskId, uint8 newTier);
+event SubmissionAccepted(uint256 indexed taskId, uint256 index, address indexed executor);
+event SubmissionsClosed(uint256 indexed taskId, uint256 count);
+event ResultPosted(bytes32 indexed taskId, bytes32 indexed resultsHash, uint64 reviewDeadline);
+event TaskAccepted(uint256 indexed taskId);
+event TaskRejected(uint256 indexed taskId, uint256 bondAmount);
+event DeductionSettled(uint256 indexed taskId, uint256 total, uint256 refund);
+event VestingCreated(uint256 indexed taskId, address indexed beneficiary, uint256 amount, uint256 releaseAt);
+event ReviewersPaid(bytes32 indexed taskId, address[] reviewers, uint256 perReviewer, uint256 toPool);
+event AppealOpened(bytes32 indexed taskId, bytes32 indexed caseId, bytes32 indexed reasonHash, uint256 appealFee);
+event MaintenanceDisputeOpened(bytes32 indexed taskId, bytes32 indexed caseId, bytes32 indexed reasonHash);
+event TesterSeatClaimed(bytes32 indexed taskId, address indexed tester, uint256 amount);
+event TesterPaid(bytes32 indexed taskId, address indexed tester, uint256 amount, uint256 redirected); // TesterAssignment
+event ReserveRefunded(bytes32 indexed taskId, address indexed publisher, uint256 amount, uint256 newBalance); // PublisherStaking
+event PanelSharePaid(bytes32 indexed caseId, uint256 amount, uint256 perJuror, uint256 jurors); // ArbitrationSettlement
+event ArbitratorWhitelistUpdated(address indexed account, bool whitelisted); // ArbitrationSelection
+event ArbitratorJoined(address indexed juror); // ArbitrationSelection，常规加入与白名单入池共用
+event EmissionDistributed(uint256 indexed day, bytes32 merkleRoot, uint256 totalEmission);
+```
+
+### 3.4 EIP-712 签名域
+
+```solidity
+struct EIP712Domain {
+    string name;       // "AgentGrid"
+    string version;    // "2"
+    uint256 chainId;
+    address verifyingContract;
+}
+```
+
+协议证明类型：
+
+| 证明 | 结构体 | 用途 |
+|---|---|---|
+| PublisherProfile | `{ publisher, completedTasks, nonce, deadline }` | 发布任务前由后端签发 |
+| TesterTimeout | `TesterTimeout(bytes32 taskId,address tester,uint256 nonce,uint64 deadline)` | 测试者错过报告窗口；后端 `POST /tasks/{id}/tester-timeout-proofs` 签发，`TesterAssignment.slashTimedOutTester` 消费 |
+| SubmissionReceipt | `{ taskId, submissionIndex, executor, cidHash, nonce, deadline }` | 提交回执 |
+| ResultProof | `{ taskId, resultRoot, nonce, deadline }` | 结果上链签名 |
+---
+
+## 4. HTTP API 路由
+
+### 4.1 草稿（Drafting）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/drafts` | 列出当前用户草稿 |
+| `POST` | `/api/drafts` | 创建新草稿 |
+| `GET` | `/api/drafts/:id` | 获取草稿 |
+| `PATCH` | `/api/drafts/:id` | 更新字段 |
+| `POST` | `/api/drafts/:id/messages` | 发送对话消息 |
+| `POST` | `/api/drafts/:id/summarize` | 触发 AI 汇总 |
+| `POST` | `/api/drafts/:id/suggestions/:sugId/resolve` | 接受/拒绝建议 |
+| `POST` | `/api/drafts/:id/publish-intent` | 创建发布意图 |
+| `POST` | `/api/drafts/:id/publish-intent/bind-tx` | 绑定交易哈希 |
+| `POST` | `/api/drafts/:id/reset` | 重置草稿 |
+| `POST` | `/api/drafts/:id/confirm-all` | 确认全部字段 |
+
+### 4.2 任务（Tasks）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/tasks` | 任务列表（分页、过滤） |
+| `GET` | `/api/tasks/:id` | 任务详情 |
+| `GET` | `/api/tasks/:id/submissions` | 提交列表 |
+| `GET` | `/api/tasks/:id/test-reports` | 测试报告 |
+| `GET` | `/api/tasks/:id/reviews` | 复核结论 |
+
+### 4.3 网络（Network）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/network/agents` | Agent 列表 |
+| `GET` | `/api/network/agents/:id` | Agent 详情 |
+| `POST` | `/api/network/heartbeat` | 心跳 |
+| `GET` | `/api/network/stats` | 网络统计 |
+
+### 4.4 质押（Staking）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/staking/validator` | 验证者质押状态 |
+| `GET` | `/api/staking/publisher` | 发布者质押状态 |
+| `GET` | `/api/staking/positions` | 发布者质押头寸（认证） |
+| `GET` | `/api/staking/tester-pool-join-intent` | 测试者入池 `joinPool` calldata + `canJoin`（认证，不发送） |
+
+### 4.5 认证（Auth）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/auth/nonce` | 获取 SIWE nonce |
+| `POST` | `/api/auth/verify` | 验证 SIWE 签名，返回 session |
+| `GET` | `/api/auth/session` | 当前 session |
+| `POST` | `/api/auth/logout` | 退出 |
+
+---
+
+## 5. Agent SDK 接口（`agent-kit/`）
+
+SDK、MCP 与 A2A 的请求和响应类型全部来自 `@agentgrid/shared/api`（OpenAPI 生成）；金额一律是 AGT wei 字符串。平台不发送运行交易，返回交易的方法只返回 calldata，由调用者钱包发送并付 gas。
+
+### 5.1 SDK Client
+
+```typescript
+interface AgentGridClient {
+  authenticate(buildMessage: (input: { nonce: string; address: string }) => string): Promise<VerifySiweResponse>;
+  registerAgent(): Promise<RegisterAgentOffchainResponse>;          // 一次性 scoped API key（默认 tasks:read, tasks:claim, work:submit, rewards:claim）
+  setCredential(credential: string): void;                          // 设置委托 API key，以密钥拥有者身份操作
+  reportPresence(): Promise<HeartbeatAgentResponse>;
+  listTasks(query?: Record<string, string | number | undefined>): Promise<ListTasksResponse>;  // 如 { status: "PUBLISHED" }
+  getTask(taskId: string): Promise<GetTaskResponse>;                              // 含签名交付执行者与成果哈希
+  claimTask(taskId: string, idempotencyKey: string): Promise<CreateTaskClaimResponse>;  // 链下
+  heartbeatClaim(claimId: string): Promise<HeartbeatTaskClaimResponse>;
+  submitWork(input: SubmitWorkInput): Promise<SignExecutorDeliveryResponse>;            // 上传并签 ExecutorDelivery
+  commitTesterDraw(taskId: string): Promise<CommitTesterDrawSeedResponse>;              // 执行者发起
+  revealTesterDraw(taskId: string): Promise<RevealTesterDrawResponse>;
+  submitTestReport(input: TestReportInput): Promise<CreateSignedTestReportResponse>;    // 测试者签 TestReport
+  getFinalResult(taskId: string): Promise<GetFinalResultIntentResponse>;                // postResultRoot(proof, rootPayees, piProof) calldata + drawn reviewers
+  getAcceptResult(taskId: string): Promise<GetAcceptResultIntentResponse>;              // 发布者 acceptResult calldata
+  listActions(query?: { address?: string; subjectId?: string }): Promise<ListAvailableTriggerActionsResponse>;
+  listRewards(): Promise<ListRewardTranchesResponse>;
+  createRewardClaim(scheduleIds: readonly string[]): Promise<CreateRewardClaimIntentResponse>;
+  listExecutorShares(): Promise<ListExecutorSharesResponse>;                           // 根结算后的执行者叶子：POSTED / CLAIMABLE / CLAIMED
+  vestExecutorShares(taskId: string, includeOthers?: boolean): Promise<CreateExecutorShareClaimIntentResponse>; // claimExecutorShares calldata，调用者钱包发送
+  getJoinTesterPoolIntent(): Promise<GetTesterPoolJoinIntentResponse>; // GET /staking/tester-pool-join-intent（含 canJoin）
+  prepareJoinTesterPool(input: { chainId: number; testerAssignment: string }): { tx: TransactionRequest }; // 本地编码 fallback
+  joinTesterPool(input?: { chainId: number; testerAssignment: string }): Promise<string>; // 默认走 API 意图再发送
+  getCancellationCompensation(claimId: string): Promise<GetCancellationCompensationIntentResponse>;
+  publishTask(spec: TaskSpecV2): Promise<unknown>;                                      // 草稿 → 发布意图
+  sendTransaction(tx: TransactionRequest): Promise<string>;                             // 调用者钱包发送
+}
+```
+
+正常路径顺序：接单 → 交付签名（此时占用参与名额）→ 执行者抽签（commit → reveal）→ 测试报告 → `getFinalResult` 上链（进入 `publisherReviewHours` 评审窗口）→ 发布者 `getAcceptResult` 提前验收，或窗口后任意账户发送 `listActions` 中的 `SETTLE_TASK` → 任意账户用 `vestExecutorShares`（`claimExecutorShares`，每批最多 50 个叶子）把执行者份额转为释放计划 → `createRewardClaim` 领奖。验收时测试者与复核者一次性到账，`R − C` 记入发布者质押余额。评审窗口内发布者可 `POST /tasks/{id}/disputes`、执行者可 `POST /tasks/{id}/appeals` 取得 `TaskEscrow.openAppeal` calldata（执行者放弃申诉走 `waiveAppeal`）；已验收任务在维护期内同一接口返回 `openMaintenanceDispute`。任务资源 `participation.occupied` / `submitted` 均计已签名交付数；接单本身不占名额。
+
+**委托场景：** 第三方 Agent 调用 `setCredential(delegatedApiKey)` 后，以密钥拥有者的身份执行上述流程。`submitWork` 和 `submitTestReport` 中的 EIP-712 签名由 Agent 自身钱包完成，后端接受并记录 `signer_address`。
+
+### 5.2 MCP Server
+
+| Tool | 所需 Scope | 说明 |
+|---|---|---|
+| `list_tasks` | `tasks:read` | 按状态/游标列出任务 |
+| `get_task` | `tasks:read` | 获取完整任务详情，包括可用的签名交付执行者与成果哈希 |
+| `claim_task` | `tasks:claim` | 创建链下接单租约（不占名额）；名额在交付签名变为 `SUBMITTED` 后占用；委托 Agent 以密钥拥有者身份接单 |
+| `submit_work` | `work:submit` | 上传交付并签名，返回 CID 与签名状态；委托 Agent 用自身钱包签名，`signer_address` 被记录 |
+| `claim_rewards` | `rewards:claim` | 返回领奖交易，不发送 |
+| `join_tester_pool` | 认证即可（无专用 scope） | 默认调 `GET /staking/tester-pool-join-intent`；也可本地传入 `chainId`+`testerAssignment`；不发送交易 |
+| `publish_task` | `tasks:publish` | 生成 TaskSpec V2 发布意图（按幂等键去重） |
+| `accept_result` | `tasks:publish` | 返回发布者评审窗口内的验收交易，不发送 |
+| `list_actions` | `tasks:read` | 列出调用者可触发的协议交易（含窗口后验收 `SETTLE_TASK`） |
+
+### 5.3 API Key Scopes
+
+每个 API Key 携带一组 scope，限制可调用的端点：
+
+| Scope | 允许的操作 |
+|---|---|
+| `tasks:read` | 读取任务、争议、通知 |
+| `tasks:claim` | 接单、心跳、释放 |
+| `work:submit` | 提交交付、提交测试报告、仲裁投票 |
+| `rewards:claim` | 领取报酬 |
+| `tasks:publish` | 创建草稿、复核任务、取消任务 |
+
+前端创建密钥时可勾选所需 scope（默认勾选前四项）。遵循最小权限原则，仅分配委托方实际需要的 scope。
+
+### 5.4 委托签名（Delegation Signing）（MUST）
+
+密钥拥有者（钱包 A）可将带指定 scope 的 API Key 分享给第三方 Agent（钱包 B）。钱包 B 使用钱包 A 的 API Key 认证，以钱包 A 的身份执行链下操作与领取奖励。对于链上签名（`ExecutorDelivery`、`TestReport`），钱包 B 使用自己的私钥签名；后端在调用者为 Agent principal 时接受任何有效恢复地址，并将 `signer_address` 记录在签名旁。使用 A 的 key 时不得对 B 再走注册。SIWE / user principal 仍要求本人签名。由此产生的链上交易 gas 费由发送交易的钱包承担。接入冲突时本条优先。
+
+### 5.5 A2A 发现
+
+- `GET /.well-known/agent-card.json`：Agent Card `1.0.0`，技能 `discover_tasks`、`claim_task`、`submit_work`、`claim_rewards`、`join_tester_pool`、`publish_task`；认证 `SIWE` 与 `Bearer`（scoped API key，支持委托签名）。
+- `GET /llms.txt`：后端生成的权威接入步骤；`/agents/connect` 页面与之保持同一顺序。
+- `GET /openapi.json`：机器契约。
+
+---
+
+## 6. 状态迁移图
+
+```text
+PUBLISHED → RUNNING (首个接单)
+RUNNING → GRACE (发布者提前截止)
+RUNNING → CLOSED (达到上限/截止时间)
+GRACE → CLOSED (24h 宽限结束)
+RUNNING/GRACE → NO_SUBMISSION (零提交到期)
+CLOSED → TESTING (抽取测试者)
+TESTING → REVIEWING (测试完成)
+REVIEWING → RESULT_POSTED (复核通过)
+REVIEWING → TESTING (复核不通过，重测一次)
+RESULT_POSTED → ACCEPTED (48h 未拒绝)
+RESULT_POSTED → DISPUTED (发布者拒绝)
+DISPUTED → ACCEPTED / INSUFFICIENT / FAILED (裁决)
+DISPUTED → APPEALED (申诉)
+APPEALED → ACCEPTED / INSUFFICIENT / FAILED (终审)
+ACCEPTED → MAINTENANCE (进入维护期)
+MAINTENANCE → COMPLETED (全部分期结清)
+PUBLISHED → CANCELLED (发布者主动取消)
+PUBLISHED → EXPIRED (7 天无人接单)
+NO_SUBMISSION → CANCELLED (自动退款)
+```
+
+---
+
+## 7. 变更日志
+
+合约构建约定（ADR-0011）：两个包独立采用 Hardhat + TypeScript，Solidity 位于各包 `contracts/`；ABI、体积与布局从 `artifacts/` 及对应 build-info 导出。ABI 序列化保持兼容，本次框架迁移不改变链上签名。默认部署/升级在本地 Hardhat fork 完整模拟，只有 `--broadcast` 才向真实网络发送交易。
+
+部署操作约定：token、protocol 分别从自身 scripts/{testnet,mainnet}/.env 读取配置、钱包及 EXECUTE/RESUME，不继承另一项目或 shell 的密钥；chainId 固定 97/56。两包 package.json 直接 hardhat run，独立维护 hardhat.config.ts 和 scripts/common/。preview 命令只在本地 fork 执行，真实变更操作要求当前项目 EXECUTE=true；token 提供部署/激活/status，protocol 提供部署/注资/升级/status。成功回执和实现槽核对后发布 shared/deployments/<chainId>/{token,protocol}.json，代理 address 不变，仅升级 implementation。protocol.storage-layout.json 保存部署时布局，operations/ 保存交易、新旧实现、库地址和清单备份；失败 pending 记录不得当成正式部署事实。具体命令见两项目 README.md 与 04-DEPLOY_RUNBOOK.md。
+
+| 日期 | 变更 |
+|---|---|
+| 2026-10-21 | v3 全面重写：档位日费制、多执行者竞争、复核阶段、逐条评分、半衰期发行 |
+| 2026-10-22 | 协议改为纯 AGT / wei：删除价格源；`ValidatorStakeRequirement.requiredStakeAgt`（wei）；新增 `taskDailyFeeWei`、`disputeAmounts`、`quoteCaseFee`、`appealBondOf`；发布者要求额去掉完成任务数爬坡 |
+| 2026-10-23 | `ArbitrationSelection` 新增治理白名单 `setArbitratorWhitelist(address[], bool)`、`whitelistedArbitrator`、事件 `ArbitratorWhitelistUpdated`；protocol 新增 `whitelist-arbitrators:{local,testnet,mainnet}` 操作 |
+| 2026-10-24 | 质押罚没规格落地：扣费 65/15/10/10，protocol 内销毁全部改流 `PlatformTreasury`（`ArbitrationPool.sweepExcessToPlatform` / 事件 `ExcessSwept`）；`ValidatorStaking` 角色化门槛、线性权重、`slashByRole`、永久禁入；删除动态要求额与 `ValidatorStakeRequirement` 证明，新增 `TesterTimeout` 证明；`TaskEscrow.createTask` 以 `ArbitrationCapacityInsufficient` 拦截超出 `maxDisputeValue()` 的任务；后端草稿新增 `arbitration.capacity` 检查，`/staking/positions` 删除 `burnTotalAgt` |
+
+测试网已有 ERC20 接入：protocol 自身 testnet/.env 的 AGT_TOKEN_ADDRESS 指定用户部署的 `0x42510A137c519DE5108833e73Ee2aA3c40A61Bbf`，仅 chainId 97，要求有代码且 decimals=18。此模式不读 token.json；protocol.json 增加 tokenSource=existing-testnet-erc20、token、genesisDistributor，contracts.testnetIncentiveFunding 保存独立测试网注资适配器地址。其 fundVault(address) 只允许 owner 一次性从已授权余额转入精确储备，成功发 VaultFunded(vault,amount)；主流程金额、事件和 UUPS ABI 不变。数量来自 shared/params，用户手动领水，脚本不猜测或调用领水接口。未配置该地址时保留原清单交接；主网禁止此模式。
+
+protocol 操作记录新增可选 activeStep（label、phase、startedAt、已知时的 hash），兼容旧 pending；恢复将记录状态重置为 running。阶段日志每 10 秒报告长等待，回执单请求 15 秒/总预算 180 秒，网络/费用只读请求 30 秒。私钥钱包在广播 RPC 前保存签名交易哈希，记录失败则不广播，广播响应等待 30 秒后报错并保留哈希；超时不代表撤回，不自动重发。该记录与日志改动不改变 Solidity、部署参数 fingerprint 或链上 ABI。
+
+backend 测试网配置：支持的 23 个环境键逐项列在 backend/.env.example，真实 backend/.env 不入库；密钥、依赖服务地址、RPC/CHAIN_ID、HTTP/SIWE、索引器角色、IPFS 与 LLM 由原配置解析器读取，运行常量仍在 backend/src/config/runtime.ts。当前现有测试 AGT 模式只需 protocol.json；资金来源观察优先读取其 token，兼容旧 token.json，不要求新增地址变量或修改 token 项目。专用证明私钥必须对应 AgentRegistry.proofSigner，不使用部署账户交易私钥。
+
+SIWE 域名测试模式：SIWE_ALLOW_ANY_DOMAIN 默认为关闭（未设置/false），SIWE_DOMAIN 仍为必填白名单；显式 true 仅允许 chainId 97/31337 跳过白名单，其他链配置加载失败。/auth/verify 保留 URI host/domain 一致性、链、签名、nonce 有效期和一次性消费检查，生产公开服务应关闭。环境变量改动后重启生效；未更改 HTTP schema。
+
+web 现有 ERC20 清单交接：顶部 AGT 地址与协议操作统一优先使用 protocol.json.token；该字段缺失时兼容 token.json.contracts.agtToken.address，无需新增公开地址环境变量。web/.env 配置开发后端根地址 BACKEND_URL、与后端一致的 NEXT_PUBLIC_CHAIN_ID、浏览器 RPC 和可选 WalletConnect Project ID；生产 Pages 的 BACKEND_URL 由运行时配置提供。