192 lines
13 KiB
Markdown
192 lines
13 KiB
Markdown
# 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）。
|