内容
# 硬件协同设计
[](https://github.com/mrcha033/hw-codesign/actions/workflows/ci.yml)
[](LICENSE)
**对于支持的板系列，将代理简报转化为可审查的硬件候选方案和明确的制造阻塞报告。**
[](docs/demo/README.md)
[下载独立的只读审查](docs/demo/index.html) ·
[检查演示证据和哈希值](docs/demo/README.md) ·
[阅读验证合同](docs/validation-contract.md)
<!-- golden-demo-evidence:start -->
演示是一个针对RP2040 USB设备系列的完整工具链仓库。它生成了一个候选方案，而不是一个合格的制造板：48个记录的门中，44个通过，1个失败，3个被阻塞。Freerouting报告零个原始未路由连接，KiCad报告零个填充后未连接项；本地ERC和DRC均报告零个违规。本地Zephyr构建被阻塞，因为选定的ARM工具链缺少newlib运行时文件。
其余证据是材料性的：采购失败，当前供应商可用性被阻塞，本地Zephyr构建在ARM newlib上被阻塞，物理资格被阻塞。
该板尚未制造，U2.57 via-in-pad填充/盖/帐篷工艺不合格。Bundle `7d6731501a24716965593f7fcdc168a3d739d1b0a1b7a57f7a0b29fee51c1b84`记录了这些边界。
<!-- golden-demo-evidence:end -->
## 20秒产品循环
| 简报 | 候选方案 | 阻塞报告 |
|---|---|---|
| 自然语言约束降低为具有来源的键入项目字段。 | 运行发出电子源代码、KiCad工件、固件、BOM、审查包和哈希值。 | 每个门都是`通过`、`失败`或`阻塞`；物理证据缺口保持发布阻塞。 |
`hw-codesign`作为CLI（`hw`）、MCP服务器（`hw-mcp`）和存储库拥有的代理插件提供。其设计表面由模板和合同驱动。它不是一个任意提示的PCB预言家。
## 从源代码安装
需要Python 3.11或更高版本。
```bash
git clone https://github.com/mrcha033/hw-codesign.git
cd hw-codesign
python3.11 -m venv .venv
.venv/bin/pip install '.[mcp]'
export PATH="$PWD/.venv/bin:$PATH"
hw --help
```
此源代码检查是唯一经过验证的公共安装路线。独立审查也可在https://mrcha033.github.io/hw-codesign/上实时查看。 目前尚未声称软件包索引、容器注册表或标记版本，直到该端点实时且独立烟雾测试。
创建演示中使用的相同候选类：
```bash
mkdir my-hardware-workspace
cd my-hardware-workspace
hw --root . create-project my_usb_board --template rp2040_usb_device
hw --root . update-requirements my_usb_board \
"设计一个2层RP2040 USB HID和CDC板，通过USB-C供电。使用Zephyr。"
hw --root . design-candidate my_usb_board --brief \
"设计一个2层RP2040 USB HID和CDC板，通过USB-C供电。使用Zephyr。"
hw --root . export-standalone-review my_usb_board
```
生成的HTML审查是独立的。不需要接收者或云帐户来检查它。
### MCP客户端
Claude Desktop配置：
```json
{
"mcpServers": {
"hw-codesign": {
"command": "/absolute/path/to/hw-codesign/.venv/bin/hw-mcp",
"args": [],
"env": {
"HW_PLATFORM_ROOT": "/absolute/path/to/a/writable/hardware-workspace"
}
}
}
}
```
Claude 代码：
```bash
claude mcp add hw-codesign \
-e HW_PLATFORM_ROOT="$PWD" \
-- /absolute/path/to/hw-codesign/.venv/bin/hw-mcp
```
对于Codex或Claude插件使用，请克隆此存储库并安装`hw-codesign`市场条目：
```bash
codex plugin marketplace add /absolute/path/to/hw-codesign
codex plugin add hw-codesign@hw-codesign
```
## 状态含义
| 状态 | 含义 |
|---|---|
| `通过` | 命名的门运行，其声明的检查通过。 |
| `失败` | 门运行并发现具体缺陷或未满足的合同。 |
| `阻塞` | 证据或所需工具/输入缺失。这永远不会被视为通过。 |
| `候选方案` | 可审查的生成工件存在，但发布促销未授权。 |
| `已发布` | 配置的发布门通过，发布包已导出。这并不意味着物理资格，除非存在和批准物理证据。 |
每个公共工具响应都带有`release_eligible`、`candidate_only`和`release_blocking_failures`。只有发布门和发布导出路径才能设置`release_eligible: true`。
## 支持的板系列
所有13个已发货的模板都符合当前的键入规范模式。它们的设计和物理成熟度并不相同；检查每个候选方案的门报告。
| 组 | 模板 |
|---|---|
| USB设备 | `rp2040_usb_device`, `usb_hid_controller`, `avr_32u4_hid`, `nrf52840_dongle` |
| 传感器和网关 | `ble_sensor_node`, `sensor_data_logger`, `lora_sensor_node`, `esp32_wifi_gateway`, `samd21_sensor_hub`, `stm32g0_power_monitor` |
| 机器人和电源 | `robotics_controller_full`, `mini_servo_robot`, `bldc_esc` |
使用`hw diagnose-environment`检查已安装的原生后端，或在添加不同拓扑结构之前查看[适应设计系统](docs/adapting-a-spec.md)。
## 代理工作流
MCP名称使用与CLI相同的生命周期：
```text
hw_get_capabilities
→ hw_create_project
→ hw_update_requirements
→ hw_design_candidate
→ hw_check_cross_domain_consistency
→ hw_generate_physical_qualification_plan
→ hw_record_physical_evidence
→ hw_check_release_gate
→ hw_export_release_bundle
```
代理还可以编写电路块、放置约束和固件模块，探索替代方案，比较候选方案，并运行对抗性接地基准测试。有关完整合同，请参见[MCP工具参考](docs/mcp-tools.md)。
## 存储库映射
| 路径 | 目的 |
|---|---|
| `src/hw_codesign/` | CLI、MCP服务、生成器、验证器和审查UI |
| `src/hw_codesign/templates/` | 支持的系列规格 |
| `parts/` | 精选组件、角色集、供应商记录和数据表证据 |
| `projects/golden_rp2040_usb_hid/` | 有时间戳的黄金候选方案和当前证据缺口 |
| `docs/demo/` | 20秒演示和独立只读审查 |
| `schemas/` | 键入项目和结果合同 |
| `tests/` | 跨平台回归和证据边界测试 |
## 开发
```bash
python3.11 -m venv .venv
.venv/bin/pip install '.[dev,mcp]'
npm ci --ignore-scripts
pytest -q
ruff check .
```
原生门需要其对应的工具。在解释阻塞结果之前，请诊断当前机器：
```bash
hw diagnose-environment --target fabrication_release --backend kicad
hw check my_usb_board
```
有关贡献范围、测试和声明边界，请参见[CONTRIBUTING.md](CONTRIBUTING.md)。安全报告应遵循[SECURITY.md](SECURITY.md)。
## 已知限制
- 生成的工件在所有配置的发布门通过之前保持候选状态。Gerber ZIP文件不能证明板子是安全或可制造的。
- 数字检查不能证明热性能、EMI/EMC、振动、侵入、滥用安全、连接器寿命、装配质量或电气启动。那些需要可追溯的物理证据。
- RP2040黄金候选方案尚未制造。其当前阻塞报告有意发布，没有基准测量。
- 供应商目录条目标识零件和来源，但当前库存和替代品需要新的供应商证据。
- 接收器仅绑定到环回。远程使用需要身份验证的SSH隧道或反向代理；它不是多租户托管服务。
## 许可证
该项目在[Apache-2.0](LICENSE)下许可。`src/hw_codesign/footprints/`下的KiCad封装保留其CC-BY-SA 4.0许可证，附带KiCad库异常；有关边界，请参见[NOTICE](NOTICE)。
