# AGENTS.md

本仓库是用于开发 CAD 相关智能体技能的工作台。将 `skills/` 视为产品目录，
将 `models/` 视为自有设计与共享夹具目录。框架来自
[earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
（0.7.19 基线，2026-10-09 跟进合并）；三端同步与框架跟进操作手册见 `GIT_SYNC.md`。

## 分支与目录布局

- 本仓库（fork）唯一工作分支是 `master`：Windows 与 fnnas 两端直接在 master 上
  工作，origin 指向 fnnas Gitea（唯一允许 push 的远端），GitHub upstream 物理禁推。
- 向上游贡献时遵循上游规则：`main` 是唯一长线分支，从 `main` 拉分支、
  PR 回 `main`，不直接推送 `main`。
- 0.5.0 起不再有 develop 符号链接布局——树中每个路径都是真实文件；
  不要引用或重建 `scripts/dev/setup-symlinks.sh` 一类机制（已随上游移除）。

## 发布流程

日常开发期间，不要修改根目录 `VERSION` 中的规范发布版本（仓库根就是
插件包，根部 `plugin.json`、`mcp.json`、`*.mcp.json`、`skills.sh.json` 等
清单与 MCP 配置齐全，规范版本号从
`plugins/cad/VERSION` 移到根 `VERSION`）。发布只能通过 GitHub Actions 的
`Prepare Release` + `Publish Release` 两个工作流在 `main` 上进行：前者开并合入
版本号 PR（连同 `VERSION`、派生元数据和所有 skill 的 `cadgen==` 锁定），后者在
该合并推送上构建 `cadgen` wheel、发布 PyPI、部署文档并打 `v<VERSION>` 标签。
未指明 patch/minor/major 或确切版本时，先询问再触发。`target=build-test` 是
流水线演练，仅在明确要求测试 CI/CD 时使用，绝不是正式发布。本 fork 托管在
Gitea、不运行这些工作流；完整流程、恢复路径与本地后备方案见 `CONTRIBUTING.md`
的 Releases 章节。

开发环境安装 `requirements-dev.txt`，不要单独安装某个 skill 的
`requirements.txt`（那会从 PyPI 拉上一个正式版 cadgen）。

## 仓库目录

- `skills/`：智能体技能及其参考资料和脚本。
- 根部 `plugin.json`、`mcp.json`、`claude.mcp.json`、`codex.mcp.json`、
  `cursor.mcp.json`、`gemini-extension.json`、`skills.sh.json`：智能体插件清单与
  MCP 配置；仓库根本身即插件包（上游 0.7 起不再有 `.claude-plugin/` 等子目录）。
- `models/`：示例及长期保留的 CAD/机器人描述夹具；其中 `modular-case`、
  `modular-drawer`、`smart-farm`、`toast-inner-core`、`freecad`
  为本仓自有设计（只入库设计源码，产物由 `.gitignore` 的 models 规则忽略）。
- `apps/web/`：CAD Viewer 的 React 客户端（其后端是 `cadgen.viewer`）；
  `apps/api/`：版本发布页 API；`apps/mcp/`：CAD app 的 MCP host。
- `packages/cadgen/`：发布的发行版——STEP/GLB/拓扑生成、skill CLI 解析器、
  Viewer 后端与客户端及其运行时。
- `packages/core/`：共享的 JS CAD、渲染及运行时核心（不依赖 React），打进
  cadgen 运行时与各 app；`packages/ui/`：共享 React UI 组件与渲染器。
- `apps/docs/`：文档站点。
- `tests/`：由仓库根目录管理的技能、软件包、Viewer 服务及仓库级策略测试套件。
- `scripts/`：按用途分组、可长期维护的仓库命令。

## 仓库规则

- 根目录指南保持简短。领域工作流、CLI 细节和验证策略放在相应的
  `skills/<skill>/SKILL.md` 或 `references/` 文件中；各包边界与设计法则见
  `packages/cadgen/README.md`、`packages/core/README.md`、`packages/ui/README.md`、
  `apps/web/README.md` 与 `apps/docs/README.md`。
- `packages/cadgen` 必须可脱离本仓库独立运行（ships-alone），其文档不得引用
  包外路径（`tests/python/global/test_package_boundaries.py` 强制）。
- 行为、命令或仓库布局发生变化时，同步更新相关 Markdown 文档，但不要让
  `AGENTS.md` 过度膨胀；该文件只保留长期有效的仓库级规则和指引。
- 在提交、变基、解决生成文件冲突或更新发布版本前，先阅读 `CONTRIBUTING.md`。
- 每个技能在运行时必须自包含且相互独立，不得引用、导入或依赖其他技能、
  `skills/` 根目录或仓库根目录模块，也不得把仓库路径加入运行时查找路径。
  共享运行时辅助工具以 `packages/` 下的代码为事实来源，再植入或生成到各
  消费方的技能运行时中。
- 使用限定路径的搜索和验证命令，并检查 `git status`；除非任务需要，避免
  广泛扫描生成的 CAD/LFS 产物。
- 根 `VERSION` 是规范发布版本。不要手动修改软件包、锁文件或 Python
  `pyproject.toml` 中的重复版本；发布准备流程和 `scripts/bundle/bundle.sh`
  会根据规范版本写入这些值。
- 生成运行时或插件包相关源码变更时，用主打包封装脚本
  `scripts/bundle/bundle.sh` 刷新或检查。
- `packages/core` 必须保持可复用且不依赖 React；React UI 放在 `packages/ui`，
  应用 UI 和工作流状态放在 `apps/web|api|mcp` 中。
- 模型脚本只依赖 build123d；总装标签与着色用各模型自含的 `AssemblyHelper`，
  不导入相邻模型目录，也不依赖仓库自维护的 Python 包。
- `models/` 只入库设计源码（`.py`/`.md`/配置），STEP/STL/GLB/DXF/URDF/G-code
  等生成产物一律不入库，在目标端按需重新生成。
- `scripts/` 仅用于可长期维护的仓库命令；一次性脚本放 `tmp/`。
- 不要提交 `.venv/`、`node_modules/`、缓存、`tmp/`、本地凭据或打印机配置。

## 环境

- 进行 CAD Python 工作时，优先使用 `./.venv/bin/python`（Windows 为
  `.venv/Scripts/python.exe`）：`py -3.12 -m venv .venv`、
  `pip install build123d==0.11.1`，再装 `requirements-dev.txt`。已知坑：
  build123d 0.11.1 导入扫描系统字体，
  `C:\Windows\Fonts\msttc.ttf` 非标准 TTF 会崩；重建 venv 后需重打
  text.py 的 register_font try/except 补丁。
- Viewer 运行时随 `cadgen` Python 包分发，运行时无需 Node；仅修改 Viewer
  或 core/ui 源码时才需要 Node 工具链（仓库根 `npm install`，workspace 布局）。
- 只安装当前变更工作流所需的依赖。
- 仅当用户提出要求或任务针对 `models/` 下特定文件时才物化 LFS 对象；
  `.lfsconfig` 默认排除 `assets/**`、`models/**` 的 fetch。

## 检查

运行能够覆盖变更的最小范围、路径定向检查。修改共享功能或交付前，使用覆盖
范围更广的封装命令：

- 代码测试：`scripts/test/test.sh`
- 定向测试运行器：`scripts/test/test-js.sh`、`scripts/test/test-docs.sh`、
  `scripts/test/test-python.sh`、`scripts/test/test-global.sh`
- 规范发布版本：`scripts/release/check-version.sh`
- 生成运行时新鲜度：`scripts/bundle/bundle.sh --check`
- CAD Viewer、`packages/core`、`packages/ui`：`npm --prefix packages/core test`、
  `npm --prefix packages/ui test`、`npm --prefix apps/web run test`、
  `npm --prefix apps/web run build`。
  Viewer 后端套件在 `tests/python/packages/cadgen/viewer`，由
  `scripts/test/test-python.sh` 覆盖；改 `cadgen/viewer/` 必须跑它。
- 文档站点：`npm --prefix apps/docs run check`
- 定向 Python 测试：`./.venv/bin/python -m unittest <changed test paths>`

## CAD 查看器

Viewer 随 `cadgen` 包分发（服务端 + 预构建客户端）。启动：

```bash
cd <repo>/models && cadgen viewer --host 127.0.0.1 --json --detach
```

- `--detach` 必带：前台 viewer 永不退出，detach 后台运行并立即返回 JSON。
- 启动目录（cwd）就是被服务的目录，也是实例复用键——务必从 `models/` 启动，
  不要在 skill 目录内启动。
- 命令总是返回一个可用 URL（`action: started|reused`）；端口从 3245 起自动
  递增，不要手动选端口或停止他人启动的实例。
- `cadgen` 在开发环境来自 `requirements-dev.txt` 的 editable 安装（版本须与
  根 `VERSION` 一致，`cadgen doctor` 可校验）；
  `cadgen doctor <skill 目录>` 可校验版本匹配。
- 详细手册（启动契约、复用、目录扫描陷阱）见 `skills/cad/SKILL.md`
  与 `apps/web/README.md`。

## `models/modular-case` 当前模型

该模型是 175×225×254 mm 的直立塔式 mATX 机箱，目标主板为 Intel B75 / LGA1155
Micro-ATX（24.4×17.5 cm）。统一使用世界坐标：X 为左右宽度
（左板 X=0、右板 X=size_x；PSU 仓在左、主板仓在右）、Y 为前后深度（前面板 Y=0）、
Z 为垂直高度。组件、面板、骨架和总装公共入口都必须直接返回最终方向；
旧顶层 `config.py`、`core_skeleton.py`、`modular_case/specs.py` 和 `modular_case/coordinates.py` 已删除，不得恢复双坐标系。
设计数据（外购件规格、标定、尺寸、布局、跨件接口）唯一定义在 `modular_case/config.py`，
尺寸按世界轴命名（`size_x/size_y/size_z`、`*_xz` 等），其他文件只引用不另存。

- 骨架在 Z=127 mm 拆为上下两段，通过 15 mm 搭接区和 6 颗 M3 贯穿螺栓连接
  （两段均为 Ø3.3 过孔 + 垫片螺母锁紧，合拢对正由螺栓孔承担）；上段基体
  在搭接区让位，与下段舌板贴合互锁，打印件两两不得实体交叠
  （`test/test_printed_interference.py` 强制）。中板有
  5 个胶囊减重窗及 37 mm 前部走线通道。快速模式顶底盖板为实心板；详细模式（打印导出用）
  底板为纵向直槽梯格（2.2 mm 槽、三段式、中板带 18 mm 实心脊），顶板为斜分区的三角孔/
  斜槽/直槽并带主板仓后部两段式出风槽。
- 前上板默认使用斜向百叶，可显式选择蜂窝版本；前下板只开圆形凹面开机键（实测无锁
  微动的两段式开关仓：前段与前下板一体——帽头行程孔 + 托板 + 多头内螺纹筒，后段为
  外螺纹杯 part.button_chamber_rear；按钮为插柱式——颈端十字插孔、开关可 90° 任意
  旋转安装，帽从机箱外压装在按柱插头上、由开关弹簧定位回弹；开关先放入杯内
  （引脚占本体背面上半部、朝上，焊线从杯底上半开口穿出）随杯一起从机箱内拧入，
  杯口沿抵托板背面压紧，拧到底时方腔回正、杯尾对位刻线朝上），从机箱内拧螺丝固定。
  左右板、后板及所有内部组件均为独立可引用部件。
- 后板主板 IO 区为打印式开孔（原装金属挡片弃用）：`IO_PORTS.openings` 为实测接口
  壳体外廓（板局部坐标），开孔每边外扩 `IO_PORTS.hole_clearance`；外侧凹槽由开孔
  外包加 `IO_PORTS.groove_margin` 派生（`IO_GROOVE_XZ`），机箱侧只经
  `LAYOUT.motherboard` 平移；接口前端面与凹槽底面同平面（`IO_PORT_FACE_Y`）。
  后板下沿保留 `IO_PORTS.bottom_rim`（2.4 mm）完整底边，凹槽下沿与开孔切刀都裁在
  该边之上，底盖后缘不设让位。`IO_PORTS.offset_x`、`IO_PORTS.offset_z`、
  `IO_PORTS.scale_z` 留给 `io_plate_coupon` 回写。标定流程见
  models/modular-case/README.md 与 calibration/README.md。
- 总装默认使用快速模式，不生成面板蜂窝、mesh 等高成本细节；只有单面板预览或显式
  `--detailed` 才完整生成。默认配色为黑色，可选蓝白、红黄主题。
- 紧固件默认采用 M3 成形攻丝；方形角柱可扩孔安装热熔铜柱。骨架搭接区为
  6 颗贯穿螺栓配垫片螺母。
  主板安装例外：6+4 铜柱旋入中板成形攻丝孔（PCB 背面 X=105，底孔 Ø3.0 暂定、待
  `standoff_tap_coupon` 标定）；完整总装默认选件为
  前板蜂窝、左右板 `panel.left.slanted`/`panel.right.slanted`，快速/完整模式默认不变。
- 详细设计、命令和当前风险见 `models/modular-case/README.md`。当前测试全部通过；遗留项均
  标状态管理（前板留缝只针对旧打印件，当前斜接不得留缝；硬盘笼运输防滑、SATA 转接背板推迟；按钮仓键控
  宽牙与左板 PSU 进风已按试装闭环；PCIe 嵌板 P1 推迟），清单与触发条件以 README「遗留问题与建议」
  为准，打印与装配顺序同样以 README 为准。

## Git 与大文件存储

本仓树只保存代码与小型文本夹具（2026-09-13 决策）：上游 0.5.0 合并带入的
LFS 指针夹具（assets 3 个演示 GIF、`models/drawings/DXF/imported/` 9 个 DXF、
`models/thang010146/STEP/imported/` 3 个 STEP）已全部从树中移除，二进制一律
不入库；后续合并上游若再带回这些路径，按删除解决。例外：15KB 的
`models/examples/imported/import-smoke.step` 为 viewer 启动测试引用的文本
夹具，保留。`.gitattributes` 的 LFS 规则保留作防线（误加二进制时退化为指针
而非巨型 blob）。执行 `git add`、提交或其他写入对象的操作时，绝不能禁用
LFS 过滤器；纯源码提交普通 `git push` 即可，仅当提交携带 LFS 指针文件且被
pre-push 拦截时才允许 `--no-verify`（Gitea LFS 端点 502，见 GIT_SYNC.md）。
本地钩子位于 `.githooks`，并通过 `scripts/git-hooks/pre-commit` 委托构建
检查。强推只允许指向 origin（Gitea）。