Contract 规范 · Typed API 契约

Request Schema

所有工具调用的标准 request 字段。每个工具可以在此基础上扩展自己的特有参数。

ToolRequest {
  design_ref: DesignRef        // 设计引用: "design_name@tech_lib"
  intent_ref?: IntentRef       // 意图引用——Agent 想解决什么问题
  scenario_ref?: ScenarioRef   // 场景引用——当前处于流程的哪一步
  effort?: str                 // 计算投入: "quick" | "standard" | "exhaustive"
  budget?: CostBudget          // 成本预算约束
  snap_ref?: SnapshotRef       // 目标快照——默认使用 main head
  dirty_hint?: DirtySetRef     // DirtySet 引用——增量计算的 dirty region
}

// Extended example: iPL.place request
PlaceRequest extends ToolRequest {
  congestion_weight?: f64      // 拥塞优化权重 (0.0~1.0)
  timing_weight?: f64          // 时序优化权重 (0.0~1.0)
  density_target?: f64         // 目标密度 (0.0~1.0)
  max_iterations?: int         // 最大迭代次数
}

Result Schema

所有工具调用的标准 result 字段。确保 Agent 收到结构化的、可比较的返回值。

ToolResult {
  value: Any                    // 工具的具体返回值
  uncertainty?: f64             // 结果的不确定性 (0.0~1.0), 0 = deterministic
  coverage?: f64                // 验证覆盖率 (0.0~1.0)
  provenance?: Provenance       // 结果来源追踪
  warnings?: []str              // 非致命警告
  elapsed_ms: int               // 工具执行耗时 (毫秒)
}

Provenance {
  tool_name: str               // 生成此结果的工具名
  tool_version: str            // 工具版本号
  input_snap: SnapshotRef      // 输入快照
  input_params_hash: str       // 输入参数的哈希 (用于缓存比对)
  computed_at: Timestamp       // 计算时间戳
}

// Extended example: iSTA.analyze result
STAResult extends ToolResult {
  value: TimingReport {
    wns: f64                   // Worst Negative Slack (ns)
    tns: f64                   // Total Negative Slack (ns)
    critical_paths: []Path     // 关键路径列表
    clock_domains: {}ClockSummary // 各时钟域的时序摘要
  }
  uncertainty: 0.15            // 15% 不确定性（STA 模型估算）
  coverage: 0.98               // 98% 的时序路径已覆盖
}

Proposal / Delta / Certificate

Agent 提案、设计变更与验证证书的核心类型定义。

Proposal

Proposal {
  id: str                      // 提案唯一标识
  intent_ref: IntentRef        // 意图——Agent 想达成的优化目标
  expected_delta: DesignDelta  // 预期的设计变更
  expected_metrics: {}MetricGoal // 预期的指标变更, e.g. {"hpwl": "-5%"}
  rationale?: str              // Agent 的决策理由（自然语言）
  parent_snap: SnapshotRef     // 基于哪个快照生成的提案
  confidence?: f64             // Agent 对此提案的信心 (0.0~1.0)
}

DesignDelta

DesignDelta {
  moved_cells: []CellMove {
    cell_id: StableId
    from: Position
    to: Position
  }
  resized_cells: []CellResize
  new_nets: []NetChange
  timing_changes: []TimingDelta
  drc_changes: []DRCDelta
  summary: DeltaSummary {
    cells_affected: int
    nets_affected: int
    area_delta: f64           // 总面积变化 (um^2)
  }
}

Certificate

Certificate {
  id: str                      // 证书唯一标识
  proposal_id: str             // 被验证的提案
  gate_result: GateJudgment    // 门禁判定结果
  pareto_position: ParetoRank  // Pareto 前沿位置
  regret: f64                  // 相对最优候选的 regret
  signed_by: str               // 签发者: "Evaluation/v0.2.0"
  signed_at: Timestamp
}

工具能力声明

每个工具必须声明自己的能力范围——Agent 在选择工具之前就能判断该工具是否适合当前场景。

ToolCapability {
  tool_name: str               // 工具名称, e.g. "iPL.place"
  version: str                 // 工具版本
  supported_scenarios: []str   // 支持的场景: ["placement", "floorplan", ...]
  fidelity_levels: []str       // 精度等级: ["quick", "standard", "exhaustive"]
  input_constraints: {         // 输入约束
    requires_snapshot: bool
    requires_dirty_set: bool
    max_design_cells?: int     // 支持的最大 cell 数
    supported_techs?: []str    // 支持的工艺库, null = 全部
  }
  output_schema: Schema        // 输出的 JSON Schema
  known_limitations: []str     // 已知限制（自然语言）
  performance_profile: {       // 性能画像
    typical_latency_ms: int
    peak_memory_mb: int
    scaling: str               // "linear" | "nlogn" | "quadratic"
  }
}

Contract 版本控制

工具契约遵循语义版本控制——Agent 可以根据版本号判断契约的兼容性。

# Semantic versioning for tool contracts: MAJOR.MINOR.PATCH

# MAJOR (X.0.0): Breaking changes
#   - Removing a field from result
#   - Changing a field type
#   - Renaming a required parameter

# MINOR (0.X.0): Backward-compatible additions
#   - Adding a new optional parameter
#   - Adding a new field to result
#   - Adding a new fidelity level

# PATCH (0.0.X): Behavior-only changes
#   - Bug fixes that don't change the schema
#   - Performance improvements
#   - Documentation updates

# Agent compatibility check
agent_depends_on: "iPL.place >= 1.2.0, < 2.0.0"
platform_provides: "iPL.place @ 1.3.1"
# → Compatible: 1.2.0 <= 1.3.1 < 2.0.0 ✓

# Contract negotiation at connection time
client = AgentClient(required_contracts={
    "iDB": ">=0.8.0",
    "iPL": ">=1.2.0",
    "iSTA": ">=1.0.0",
})
client.connect()  # Fails if platform cannot satisfy requirements