编写 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，另外还有两个给编写测试的人的字段：dut_connection（该 Net 落在被测设备的哪个位置：连接器、引脚或测试点）和 test_hints（一行一条的提示）。purpose、notes 和 tags 请在 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 \
  --dut-connection "J3 pins 2-3 (PA9/PA10)" \
  --test-hint "115200 8N1, no flow control" \
  --box my-lager-box

--dut-connection 和 --test-hint 是在 CLI 中设置这两个字段的唯一途径；TUI 只编辑 purpose、notes 和 tags。

/etc/lager/bench.json 中可以为某个 Net 保存一条 net_overrides 条目。如果该条目设置了 purpose、notes、tags、dut_connection 或 test_hints，智能体看到的是覆盖值，而不是保存在该 Net 上的值。TUI 和 lager nets describe 都不会对此给出警告。discover_bench(net_name) 和实验台清单都带有 metadata_sources，它指明每个字段来自哪个文件（bench.json 或 saved_net），因此您可以看出覆盖值何时遮住了保存的值。请先从覆盖条目中删除该字段，再到 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）。
`external_id`	该文档在外部文档存储库中的 ID。
`external_url`	该文档在外部文档存储库中的 URL。智能体用它自己的凭据打开它。
`pages`	可选的页码/图纸提示，例如 `"3-5"` 或 `"POWER sheet"`。
`notes`	可选的自由格式备注。

--url、--repo-path、--external-id 和 --external-url 中至少要提供一个。MCP 服务器加载 bench.json 时，会跳过一个都没有提供的引用，并记录一条警告。

URL 还是 repo-path：该用哪个

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

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

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

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

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

不在您项目中的文档

智能体会先在您的项目根目录中查找 repo_path。如果那里没有该文件，它会在 ~/.lager_dut_docs/ 下按相同的相对路径查找。例如，智能体会在 ~/.lager_dut_docs/docs/sch.pdf 查找 docs/sch.pdf。请把该目录放在您的项目之外。lager python 会上传项目目录并跟随符号链接，压缩后大于 20 MB 的上传会被拒绝。放在项目中或链接到项目中的 PDF 文件夹，可能会让每次运行都失败。

智能体如何使用它

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

智能体读取 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：该用哪个

​不在您项目中的文档

​智能体如何使用它

​让改动生效