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_setup 激活 TO 项目环境 → api_isf_fw_start 启动 fw start -flow APR+TC+PV -block ... 流程 → api_isf_flow_status 查询； api_isf_run 为任意 ISF 命令的泛用通道；无 ISF 环境时自动回退 mock）。

成长闭环（反馈 / 复核 / 巡检三件套）

观测（每次带 agent 的工具调用自动落盘一条观测，含指标与错误签名）→ 检测（规则化检测器发现趋势异常/失败聚类/知识盲区/自我问题）→ 工程师确认或纠正 → 回流知识库 → 后续决策优先复用。三件套用法：

# 1) 反馈（人的嘴）: 纠正或确认 Agent 的做法, 直接进入知识库 (weight=5, 优先被复用)
python -m hacoo feedback --agent sta --content "这种情况应先查 clock skew" --decision-id dec-xxx

# 2) 复核: 看待审队列 (pending 决策 + Agent 自我沉淀), approve/reject 单条经验
python -m hacoo review --agent sta
python -m hacoo review-mark --entry kb-xxx --action approve --note "已验证"

# 3) 巡检（Agent 的眼）: 跑检测器生成带证据的 insight; confirm 自动沉淀为知识条目
python -m hacoo insights --scan --agent sta
python -m hacoo insights --agent sta --status new
python -m hacoo insight-mark --id ins-xxx --action confirm

反馈/复核/巡检均为人类面向接口，不受 Agent 启停限制；dismiss 的 insight 按签名去重，同类问题不再重复报警。Agent prompt 已内置两条纪律：被人类纠正后 必须调用 hacoo_feedback 沉淀；每次 flow 结束后调用 hacoo_insights_scan 并向 人类汇报 new 状态的 insight。

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) 可视化操作平台 (可选组件, 需要 streamlit, 且 streamlit 要求 Python >= 3.9)
python -m hacoo dashboard          # http://127.0.0.1:8501

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

可视化操作平台（Dashboard）

工程师的日常交互入口（对话入口仍是 OpenCode）：总览 / Run 中心 / Flow 启动台 / 决策复核 / 知识库 / Insight 中心 / 升级管理 / Agent 管理 / 基准与兼容性 / 观测与日志 共 10 个页面（docs/SPEC-dashboard.md）。

• SDK 优先：一切写操作经 HacooClient 走网关（保留多用户隔离/配额/审计）， 绝不直接改写 logs/、knowledge/ 文件。

• 离线只读模式：server 未启动时自动降级（或 HACOO_DASH_OFFLINE=1 强制）， 黄色横幅提示，写按钮全部隐藏，仅 总览 / Run 中心 / 知识库 / 基准 / 观测日志 五个页面可用，数据直接读 JSONL/manifest 文件（只读）。

• 数据层 hacoo/dashboard_data.py 为纯函数（不含 streamlit import），可独立单测； UI 层在 dashboard/（Streamlit, st.navigation + st.Page）。

架构映射（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 dashboard [--port 8501]       可视化操作平台 (可选依赖 streamlit)
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 runs [--status success]       flow run 摘要列表
python -m hacoo call api_report_timing --instance inst-xxx --args '{"max_paths":5}'
python -m hacoo feedback --agent sta --content "..."   人类反馈纠正 (成长闭环)
python -m hacoo review [--agent sta]                    待复核队列
python -m hacoo insights --scan [--agent sta]           巡检: 检测器扫描新问题
python -m hacoo upgrade propose --kind agent_capability --target sta --title "..." \
    --motivation "..." --acceptance "..."               升级提案 (Part A)
python -m hacoo upgrade list [--status proposed]        查询提案
python -m hacoo upgrade update --id up-xxx --to accepted   提案状态流转
python -m hacoo agents version sta 1.3.0                Agent 版本 bump
python -m hacoo compat snapshot|check                   契约快照: 重建 / 校验
python -m hacoo bench run [--agent sta] [--tag T]       能力基准 (golden cases)
python -m hacoo bench save-baseline --agent sta         存 baselines/<agent>@<ver>.json
python -m hacoo bench compare --baseline <path>         与基准对比 (fail->pass / pass->fail)

配置（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) / 审计日志。