triplestone/text-to-cad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
text-to-cad/AGENTS.md
T
triplestone 156bce0183 chore: 删除 matx-case 与 engine-case 
自有机箱只保留 modular-case。文档中的当前模型清单同步去掉这两项。
2026-10-12 14:39:34 +09:00

13 KiB
Raw Permalink Blame History

AGENTS.md

本仓库是用于开发 CAD 相关智能体技能的工作台。将 skills/ 视为产品目录， 将 models/ 视为自有设计与共享夹具目录。框架来自 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 包分发（服务端 + 预构建客户端）。启动：

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）。

Reference in New Issue View Git Blame Copy Permalink