编写 DUT 上下文

AI 智能体可以读取网表，但仅凭网表并不能告诉它这台 Box 是做什么的，或者每根线代表什么。知道 uart1 是一个 UART，和知道它是被测设备的调试 CLI，完全是两回事。DUT 上下文就是您一次性写下的那段叙述，让智能体在系统层面而不是零散导线的层面来理解您的实验台。 DUT 上下文保存在 /etc/lager/bench.json 中，并通过 MCP 资源 lager://dut/overview.md 和 lager://dut/context，以及 discover_dut() 和 cite_schematic() 工具提供给智能体。

需要编写的两样东西

1. 每个 Net 的用途

每个 Net 都带有一句话的 purpose，以及可选的 notes。请在 Net 管理器 TUI 中设置它们：

lager nets tui --box my-lager-box

选中一个 Net，选择 Edit Details，然后填写：

Purpose —— “DUT debug CLI over UART; primary command/response channel.”
Notes（可选）—— 注意事项、跳线位置、示波器探测点。
Tags（可选）—— 供规划工具匹配的简短关键字，例如 flash、boot-critical。

purpose 和 notes 是给智能体阅读的文字。tags 是规划工具用来打分的关键字，而与测试目标匹配的标签是最强的相关性信号。您也可以不用 TUI 来设置它们：

lager nets describe uart1 \
  --purpose "DUT debug CLI over UART" \
  --notes "PA9/PA10; 115200 8N1" \
  --tag cli --tag boot-critical \
  --box my-lager-box

/etc/lager/bench.json 中可以为某个 Net 保存一条 net_overrides 条目。如果该条目设置了 purpose、notes 或 tags，智能体看到的是覆盖值，而不是保存在该 Net 上的值。TUI 和 lager nets describe 都不会对此给出警告。请先从覆盖条目中删除该字段，再到 Net 上设置它。

2. 整个 DUT 的上下文

DUT 上下文描述整块板子：它的用途、MCU、主要外设、子系统，以及文档引用。请用 lager dut 命令组来编写它。

# View current context
lager dut show --box my-lager-box

# Edit the whole DUT block in $EDITOR
lager dut edit --box my-lager-box

写完整之后的 DUT 上下文在 bench.json 中是这样的：

{
  "dut_context": {
    "name": "main",
    "purpose": "Power-regression rig for FeatureA boards",
    "mcu": "STM32H7",
    "key_peripherals": ["QSPI flash", "PMIC"],
    "summary": "STM32H7-based DUT used to validate the power tree under fault injection.",
    "schematic_refs": [
      {"title": "Main schematic", "kind": "schematic", "repo_path": "docs/sch.pdf"}
    ],
    "datasheet_refs": [
      {"title": "STM32H7 RM", "kind": "datasheet", "url": "https://...", "pages": "150-200"}
    ],
    "subsystems": [
      {
        "name": "Flash subsystem",
        "summary": "QSPI flash",
        "nets": ["flash_cs", "flash_clk"],
        "doc_refs": [
          {"title": "Flash sheet", "kind": "schematic", "repo_path": "docs/sch.pdf", "pages": "3"}
        ]
      },
      {"name": "Power tree", "summary": "PMIC + LDOs", "nets": ["psu1"]}
    ]
  }
}

子系统把相关的 Net 归为一组（电源树、闪存子系统、调试等），让智能体按功能模块来思考。智能体可以只查询一个 Net，就知道它属于哪个子系统，以及哪张原理图图纸涵盖了它。

附加原理图和数据手册

Lager Box 不是文档存储库。它记录的是指向您文档的指针；智能体用它自己的（具备视觉能力的）工具去获取和分析这些文档。这样既让 Box 保持轻量，也让智能体能用最合适的工具去阅读 PDF 或电路板图片。无需手工编辑 JSON 就能附加一个指针：

lager dut add-doc --kind schematic \
  --title "Main board" --repo-path docs/sch.pdf --pages 3-5 --box my-lager-box

lager dut add-doc --kind datasheet \
  --title "STM32H7 reference manual" --url "https://..." --pages 150-200 --box my-lager-box

一条文档引用（DocRef）包含：

字段	含义
`title`	可读的名称。
`kind`	`schematic`、`layout`、`datasheet`、`firmware`、`manual`、`errata` 或 `other`。
`url`	外部 URL（智能体能够获取的任意 URL）。
`repo_path`	相对于您测试项目的路径（执行 `lager python` 时同步到 Box）。
`pages`	可选的页码/图纸提示，例如 `"3-5"` 或 `"POWER sheet"`。
`notes`	可选的自由格式备注。

--url 和 --repo-path 中至少要提供一个。

URL 还是 repo-path：该用哪个

情形	推荐	原因
自动化 / CI / 无人值守的智能体	`--repo-path`	文件随您的项目一起同步；不需要网络、不需要认证，完全确定。
可公开获取的文档	`--url`	任何带有网页抓取工具的智能体都能取到它。
私有文档（Google Doc、Confluence、SSO）	`--repo-path` 或一个 Drive 连接器	Box 从不做认证；需要登录的 URL 返回的是登录页面，而不是内容。

对于 Google 文档，请优先使用导出 URL，而不是编辑器 URL —— /edit URL 返回的是 JS 应用，而不是内容：

https://docs.google.com/document/d/<DOC_ID>/export?format=pdf

对于需要认证的文档，您有三种选择：

把它共享为”知道链接的任何人”都可访问。
为您的智能体配置一个持有凭据的 Google Drive 连接器或 MCP 服务器。
把它导出到您的仓库中，然后使用 --repo-path。

智能体如何使用它

写好之后，这份上下文会驱动整个智能体循环：

智能体读取 lager://dut/overview.md，得知：“这是一台电源回归实验台， STM32H7，包含闪存和电源树子系统，原理图在 docs/sch.pdf。”
plan_firmware_test("flash driver", "exercise QSPI") 返回的计划已经限定在闪存子系统上，并附有指向原理图第 3 页的指引。

cite_schematic("flash_cs") 只返回该 Net 的引用：

{
  "net": "flash_cs",
  "net_purpose": "SPI flash chip-select",
  "subsystem": "Flash subsystem",
  "subsystem_doc_refs": [
    {"title": "Flash sheet", "repo_path": "docs/sch.pdf", "pages": "3"}
  ]
}

智能体用它自己的文件工具直接打开 docs/sch.pdf 的第 3 页 —— 不必扫描整个 PDF。

让改动生效

MCP 服务器监视 /etc/lager/bench.json、/etc/lager/saved_nets.json 和 /etc/lager/box_id，并在其中任何一个在磁盘上发生变化时自动重新加载。因此，在 lager dut edit、lager dut add-doc 或 lager nets describe 之后，智能体在下一次 discover_dut()、discover_bench() 或 lager://dut/overview.md 请求时就会看到新的上下文 —— 不需要任何手动步骤。您也可以立即强制重新加载，以确认某项改动已经生效。已连接的智能体可以以 action="reload" 调用 box_manage 工具，您也可以重启 Box 服务。

​需要编写的两样东西

​1. 每个 Net 的用途

​2. 整个 DUT 的上下文

​附加原理图和数据手册

​URL 还是 repo-path：该用哪个

​智能体如何使用它

​让改动生效

需要编写的两样东西

1. 每个 Net 的用途

2. 整个 DUT 的上下文

附加原理图和数据手册

URL 还是 repo-path：该用哪个

智能体如何使用它

让改动生效