HACOO — Human Agent CO-wOrk eTV design platform

基于 FluxEDA 五层协议架构（见 docs/FluxEDA.md）实现的人机协同 eTV 设计平台。以 OpenCode + KIMI 2.6 (vLLM) 为 Agent 入口，通过 MCP 把异构 EDA 工具整合到统一、安全、可观测的 API 空间。多用户共享部署，实例级隔离。

多 Agent 设计团队（产品核心）

平台内置覆盖数字芯片设计全流程的 9 个专业 Agent，每个有独立 prompt、 工具白名单和专属知识库:

生产 EDA adapter（真实命令语义封装）

每个工具 adapter 把 api_* 调用翻译为工具原生命令（T2 语义差异封装在 adapter 内）:PrimeTime/ICC2/Innovus/Voltus/RedHawk-SC 走持久 Tcl shell 会话(hacoo/adapters/shell.py: TclShell),Calibre 走批处理 + RVE 解析。 工具可执行文件按 HACOO_<TOOL>_BIN 环境变量解析（缺失时报错含配置指引）:

export HACOO_PRIMETIME_BIN=/tools/synopsys/pt/bin/pt_shell
export HACOO_ICC2_BIN=/tools/synopsys/icc2/bin/icc2_shell
export HACOO_INNOVUS_BIN=/tools/cadence/innovus/bin/innovus
export HACOO_CALIBRE_BIN=/tools/mentor/calibre/bin/calibre
export HACOO_VOLTUS_BIN=/tools/cadence/voltus/bin/voltus
export HACOO_REDHAWK_SC_BIN=/tools/ansys/redhawk_sc/bin/redhawk_sc

注意：不同工具的同名 api_* 方法（如各家 api_load_design）按 (instance → tool) 命名空间解析签名，网关 G3 参数检查始终使用正确工具的签名。

自由搭配（按实验裁剪 Agent 集合）

python -m hacoo agents list              # 查看 9 个 Agent 及启停状态
python -m hacoo agents disable thermal   # 本次实验不让 thermal 参与
python -m hacoo agents disable sipi
python -m hacoo agents sync              # 重新生成 OpenCode subagent 文件

禁用是网关层硬强制：被禁 Agent 的任何调用返回 AGENT_DISABLED；每个 Agent 只能调用白名单内的后端工具，越权返回 AGENT_FORBIDDEN。flow 中含被禁 Agent 的 stage 会让 run 立即失败并记录——未参与的 Agent 绝不会"偷偷执行"。

自我成长（每 Agent 独立知识库）

每个 Agent 的生成式 prompt 内置强制的 Knowledge loop: 决策前查 KB → 决策前记录 rationale → 行动后闭环 outcome → 新问题沉淀 lesson。

• hacoo_knowledge_add / query —— 经验按 Agent 隔离存储（knowledge/<agent>.jsonl)， 关键词+tag 检索，被复用的经验权重自动上升（reuse_count)

• 经验是 append-only JSONL，可 git 追踪、可人工审阅

问题定位（哪个 Agent 的哪个决策出了问题）

# Agent 视角: 每个决策都有 rationale + outcome
python -m hacoo call api_decision_query --args '{"run_id": "run-xxx"}'
# Run 视角: manifest + 决策时间线 + request_id 级审计
python -m hacoo call api_flow_trace --args '{"run_id": "run-xxx"}'

Flow 编排

api_flow_start(template, params) 按模板执行多 Agent 流程（内置 block_signoff / sta_only)；所有 stage 共享后端实例（状态跨 stage 连续）， 每个 stage 自动记录决策并关联审计。ISF 能力通过 isf adapter 暴露 （api_isf_submit_flow / flow_status / db_save / db_query / cicd_trigger / airflow_dags,mock 实现，替换为真实 ISF REST 调用即可上线）。

Related MCP server: Arcas OnlineEDA MCP Server

5 分钟上手

# 1) 启动平台（核心层零第三方依赖, Python >= 3.8）
python -m hacoo serve

# 2) 新终端: 环境自检
python -m hacoo doctor

# 3) 跑一遍演示流程 (mock 时序签核)
python -m hacoo demo

# 4) OpenCode 入口 (Agent 形式)
set VLLM_BASE_URL=http://<vllm-host>:8000/v1   # Windows; Linux 用 export
opencode            # hacoo 为主 orchestrator, hacoo-sta 等为 subagent

架构映射（SPEC 五层 + Skills 层）

多用户使用

• 身份与授权：token → Principal(user, role, capabilities)。角色：admin / engineer（read+write）/ viewer（read-only）。配置 HACOO_AUTH_FILE：

  {
    "tokens": {"tok-alice": {"user": "alice", "role": "engineer"},
               "tok-admin": {"user": "bob", "role": "admin"}},
    "roles": {"admin": ["read", "write", "admin"],
              "engineer": ["read", "write"],
              "viewer": ["read"]}
  }

• 实例隔离：实例按 user 归属，非属主访问返回 UNAUTHORIZED（admin 豁免）； api_list_instances 只列自己的实例。

• 配额：每用户默认最多 8 个实例（HACOO_MAX_INSTANCES_PER_USER），超限返回 QUOTA_EXCEEDED。

• 并发安全：同一实例上的调用自动串行化（保护持久状态）；不同实例/不同用户 完全并行。

• 审计：每次调用落一条 JSONL（logs/hacoo-audit.jsonl，HACOO_AUDIT_LOG=off 关闭），含 request_id / user / method / status / elapsed_ms，全链路可追溯。

CLI 一览（易用入口）

python -m hacoo serve [--host H] [--port P]   启动平台服务
python -m hacoo doctor                        环境自检 (Python/服务/授权/工具/vLLM)
python -m hacoo demo                          演示流程 (mock 时序签核)
python -m hacoo whoami                        当前身份 / 角色 / 配额
python -m hacoo methods [-v] [--tool T]       列出可用 api_* 方法
python -m hacoo instances                     我的活实例
python -m hacoo call api_report_timing --instance inst-xxx --args '{"max_paths":5}'

配置（hacoo/config.py，全部可用环境变量覆盖）

客户端侧：HACOO_SERVER（平台地址）、HACOO_TOKEN（访问令牌）。

扩展一个新 EDA 工具（维护者指南）

方式一：插件目录（推荐，零侵入）

1. 在任意目录写 mytool_adapter.py：继承 ToolAdapter，设置 tool_name， 用 @api_method 封装工具原生命令（T2 语义差异限制在 api_* 方法之后）；

2. 部署时 export HACOO_ADAPTERS_PATH=/path/to/dir —— 网关与后端自动发现， hacoo_list_methods 即刻可见。

方式二：内置登记 在 hacoo/adapters/ 新建模块并在 ADAPTERS 字典加一行。

两种方式都自动获得：注册表发现、参数校验、授权、审计、实例生命周期管理。

三种 Agent / 客户端入口（A1）

1. OpenCode（推荐）：根目录 opencode.json 已配好 vllm-kimi/kimi2.6 provider + hacoo MCP server；.opencode/agent/hacoo.md 为 primary agent。

2. LangChain runner（批处理/CI）： python -m hacoo.agent_runner "加载 chip.v (top=chip), 综合并报告时序"

3. Python SDK：

   from hacoo.access.sdk import HacooClient
   with HacooClient() as c, c.session("mock_eda") as eda:
       eda.call("api_load_design", path="chip.v", top="chip")
       print(eda.call("api_report_timing", max_paths=5)["data"])

公司 Linux 部署

bash scripts/deploy_linux.sh ~/hacoo-platform   # 含冒烟测试
# 编辑 ~/hacoo-platform/hacoo.env 填公司 vLLM 地址与 token, 然后:
~/hacoo-platform/start-server.sh

测试

python -m tests.test_e2e    # 或 python -m pytest tests/

覆盖：能力发现 / 状态保持 (R6) / 实例隔离 / 多用户所有权与配额 / 并发串行化 / 注册表与协议拒绝 (G1-G2) / 参数校验 (G3) / 授权 (G4) / 异步任务与取消 (R8) / 显式释放 (R11) / 审计日志。