Compare commits

1 Commits

Author SHA1 Message Date
admin 8fc53a7ae9 更新 README.md 2026-10-13 14:15:09 +08:00
641 changed files with 2 additions and 136903 deletions
-131
View File
@@ -1,131 +0,0 @@
# 复制为 .env;此文件不能填写真实凭据后提交。
# 业务时间统一使用 Asia/Shanghai。
DB_URL='jdbc:mysql://localhost:3306/vibemake?useUnicode=true&characterEncoding=utf8&connectionTimeZone=Asia/Shanghai'
DB_USERNAME=vibemake_app
DB_PASSWORD='replace-with-your-database-password'
GITEA_BASE_URL=http://localhost:3000
GITEA_ORGANIZATION=vibemake
GITEA_TOKEN='replace-with-your-gitea-token'
# 可选,仅供批量导入读取 GitHub 元数据;不能填写 Gitea Token。
GITHUB_TOKEN=''
# 默认 test,部署生产环境时改为 prod;连接信息也应对应生产环境。
SPRING_PROFILES_ACTIVE=test
# 与 cadworld 一致,默认日志目录为 logs,可改为部署环境中的绝对路径。
LOG_PATH=logs
PORT=8993
# OSS 封面和 URDF 直传默认关闭;地域 ID 不带 oss- 前缀,例如 cn-beijing。
# 目录由 profile 固定:test 为 vibemake_dev/,prod 为 vibemake/。
OSS_ENABLED=false
OSS_REGION=cn-beijing
OSS_BUCKET=''
OSS_ACCESS_KEY_ID=''
OSS_ACCESS_KEY_SECRET=''
# 可选,固定公开 CDN/OSS 基础地址;留空使用 Bucket 的标准 HTTPS 域名。
OSS_PUBLIC_BASE_URL=''
# 可选,历史公开基础地址,多个使用英文逗号分隔;不含环境根目录或查询参数。
OSS_LEGACY_PUBLIC_BASE_URLS=''
# 社区用户端 URDF 直传限制:单文件 50 MiB、整包 200 MiB、最多 500 个文件,不受仓库 multipart 限制影响。
# 后台项目/迁移 URDF 独立配置为无单文件配额、整包 500 MiB,不使用下列两个大小变量。
URDF_MAX_FILE_BYTES=52428800
URDF_MAX_TOTAL_BYTES=209715200
URDF_MAX_FILES=500
# 管理端四类项目资源直传签名有效期;不设置应用层文件大小、数量及总量配额。
PROJECT_RESOURCE_SIGNATURE_VALIDITY=1h
# PCB 工程 ZIP 直传独立开关,共用上述 OSS 连接及环境根目录。
PCB_OSS_ENABLED=false
PCB_MAX_FILE_BYTES=268435456
PCB_UPLOAD_VALIDITY=15m
# AI 默认关闭;启用后密钥仅在后端使用。两个环境均支持这些变量。
AI_ENABLED=false
ARK_API_KEY=''
ARK_MODEL=doubao-seed-2-1-lite-260915
ARK_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/responses
AI_REQUEST_TIMEOUT=30s
AI_SEARCH_TIMEOUT=65s
AI_MAX_CONCURRENT=4
AI_REQUESTS_PER_MINUTE=10
# CAD Agent uses its own model; the endpoint and key are shared with AI above.
CAD_AI_PROVIDER=doubao
# CAD-only profiles. Switching these never changes the community assistant's ARK_* settings.
CAD_AI_DOUBAO_API_KEY=''
CAD_AI_DOUBAO_MODEL=doubao-seed-2-1-lite-260915
CAD_AI_DOUBAO_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/responses
CAD_AI_DOUBAO_THINKING=enabled
CAD_AI_DOUBAO_REASONING_EFFORT=default
CAD_AI_OPENAI_API_KEY=''
CAD_AI_OPENAI_MODEL=gpt-6.1-terra
CAD_AI_OPENAI_ENDPOINT=https://api.openai.com/v1/responses
CAD_AI_OPENAI_REASONING_EFFORT=high
CAD_AI_OPENAI_USER_AGENT=vibemake-cad-ai/1.0
CAD_AI_DEEPSEEK_API_KEY=''
CAD_AI_DEEPSEEK_MODEL=deepseek-chat
CAD_AI_DEEPSEEK_ENDPOINT=https://api.deepseek.com/chat/completions
CAD_AI_DEEPSEEK_THINKING=disabled
CAD_AI_DEEPSEEK_REASONING_EFFORT=default
CAD_AI_REQUEST_TIMEOUT=300s
# 每次 CAD 模型请求的输出预算,包含思考 token 和可见输出。
CAD_AI_MAX_OUTPUT_TOKENS=16384
# Fork 依赖 Git 和 git-lfs;普通文件在线读取限制不影响 Git 快照复制。
FORK_GIT_EXECUTABLE=git
FORK_TIMEOUT=5m
FORK_MAX_CONCURRENT=2
FORK_MAX_TEMPORARY_BYTES=5368709120
# 可选:独立临时磁盘目录,默认系统临时目录下 vibemake-fork。
# FORK_TEMPORARY_DIRECTORY=/var/tmp/vibemake-fork
# 管理端:共用上述 DB_* / GITEA_* / OSS_*,独立端口、跨域来源及本机登录会话。
ADMIN_SERVER_PORT=8994
# 多个来源用英文逗号分隔;默认不开放跨域。本地可使用前端开发代理。
ADMIN_ALLOWED_ORIGINS=
ADMIN_IMPORT_WORKER_ENABLED=true
ADMIN_IMPORT_CONCURRENCY=2
ADMIN_MIGRATION_TIMEOUT=30m
# 仅真实 MySQL 隔离验证时需要;未设置时脚本使用 DB_*,需具有创建临时库权限。
# ADMIN_MYSQL_TEST_URL=
# ADMIN_MYSQL_TEST_USERNAME=
# ADMIN_MYSQL_TEST_PASSWORD=
# Redis 8.10.2,凭据不放入 URL;两个应用共用连接,按环境/应用前缀隔离。
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=''
REDIS_DATABASE=0
REDIS_SSL_ENABLED=false
REDIS_CONNECT_TIMEOUT=2s
REDIS_TIMEOUT=1s
# 留空不设置此变量时由 profile 使用 vibemake:test / vibemake:prod。
# REDIS_KEY_PREFIX=vibemake:prod
# 仅填写实际可信反向代理的 IP/CIDR,逗号分隔;默认忽略转发头。
TRUSTED_PROXY_CIDRS=
HTTP_JSON_MAX_BYTES=262144
HTTP_URDF_JSON_MAX_BYTES=2097152
HTTP_COMMIT_JSON_MAX_BYTES=67108864
FILE_MAX_CONCURRENT=4
RATE_CAPTCHA_PER_MINUTE=20
RATE_LOGIN_IP_PER_MINUTE=20
RATE_LOGIN_ACCOUNT_PER_MINUTE=10
RATE_ADMIN_LOGIN_PER_MINUTE=30
RATE_VIBEMAKE_READ_PER_MINUTE=120
RATE_FILE_READ_PER_MINUTE=60
RATE_CREATE_PER_MINUTE=5
RATE_FORK_PER_MINUTE=10
RATE_FILE_WRITE_PER_MINUTE=10
RATE_COVER_SIGN_PER_MINUTE=30
RATE_URDF_SIGN_PER_MINUTE=20
RATE_PCB_CREATE_PER_MINUTE=5
RATE_PCB_SIGN_PER_MINUTE=20
RATE_PCB_SAVE_PER_MINUTE=30
RATE_PCB_READ_PER_MINUTE=60
RATE_COMMENT_PER_MINUTE=10
RATE_LIKE_PER_MINUTE=60
# README 普通外链图片自动转存;动态徽章保留原链。
README_IMAGES_ENABLED=true
README_IMAGE_MAX_BYTES=20971520
README_IMAGE_CONCURRENCY=2
# CAD专项知识:off关闭;pilot允许实验候选;enabled仅允许正式准入规程
CAD_AI_KNOWLEDGE_MODE=off
-5
View File
@@ -1,5 +0,0 @@
.idea/
**/target/
.env
.DS_Store
logs/
-11
View File
@@ -1,11 +0,0 @@
## 代码实现原则
- 优先保证业务正确性、可维护性、可读性,再考虑炫技。
- Java代码统一使用显式类型声明,不使用var,包括局部变量、循环变量和try-with-resources资源变量。
- 修改代码时忽略.sql文件,如果遇到需要改表结构,直接发我sql,要求表字段规范且有中文注释。
- /api的用户请求返回数据不要暴露数据表id字段,只返回编码,增删改查都用唯一编码字段
## 日志规范
- 关键业务节点必须补充必要日志,方便线上排查。
- 不要打印密码、Token、手机号、身份证、支付密钥等敏感信息。
- 异常日志必须包含足够定位问题的信息。
## 回复规范
- 永远用中文回复。
+2 -360
View File
@@ -1,360 +1,2 @@
# Vibemake
Spring Boot 社区后端,工程分层参考 cadworld。使用 Java 21、Spring Boot 3.5.16、MyBatis-Plus 3.5.11、MySQL 和 Gitea API v1。业务库名为 vibemake,包含 sys_user、project、project_comment、project_like,以及管理端的 project_import_task。
项目模块和 Java 包名统一使用 `vibemake`,对外接口继续使用原有 `/api/community/**` 等路径,前端调用方式保持不变。
平台管理用户、项目归属、类型、发布、评论、点赞和 Fork 来源;Gitea 管理文件、目录、Commit 与历史。仓库统一存放在配置的 Gitea 组织下,为私有仓库。
内置项目类型为 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式)、ROBOTIC_ARM(机械臂)。前端通过 `/api/project-types` 获取类型列表,用于项目创建、修改和列表筛选。
## 工程结构
| 模块 | 职责与主要包 |
| --- | --- |
| vibemake-api | 应用入口、HTTP 接口和接口配置;使用 api.controller、api.config |
| vibemake-bean | 数据库实体在 bean.entity,常规请求与响应在 bean.Contracts,AI 协议在 bean.ai |
| vibemake-service | 业务 Service 接口在 service 根包,实现类在 service.impl;包含 mapper、config、gitea、ai、support |
| vibemake-security | 平台登录会话、验证码、身份上下文、认证过滤器和安全配置 |
| vibemake-common | 通用响应、分页、异常处理、requestId 和基础工具 |
| vibemake-adminapi | 独立管理端应用,用户角色鉴权、用户与全站项目管理、GitHub 在线迁移 |
| vibemake-import | 固定 Excel 的 GitHub 项目运维导入命令,不提供 HTTP 接口 |
UserService、ProjectService、FileService、InteractionService、CoverUploadService、UrdfService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、上海业务时间(Asia/Shanghai)和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,短期状态使用 Redis,限流和共享响应组装位于 service。
## 功能与边界
支持邮箱加图片验证码登录、我的项目列表、在线文本编辑、新建文件和目录、上传及多文件提交、手动发布和撤回、已发布版本浏览、快照 Fork、平铺评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。工作区是用户项目列表,没有 workspace 表。没有 repository_operation 表、草稿保存、类型表、标签、收藏、成员协作;管理后台接口由 vibemake-adminapi 提供。
**社区登录不验证邮箱归属,知道别人的邮箱并通过图片验证码即可登录其社区身份;USER 和 ADMIN 均使用邮箱加图片验证码登录前台,无需密码;后台仅允许 ADMIN 通过邮箱和密码登录;OFFICIAL 禁止登录。** 验证码、登录会话和请求频率使用 Redis;两个应用仍各单实例部署,应用重启后保留 Redis 中未过期的会话。首次从本机缓存版本升级需要重新登录。所有仓库写入统一经过平台后端。
## 启动
1. 安装 Java 21、Maven 3.9+,准备 MySQL 8.0.13 及以上和现有 Gitea。
2. 新建数据库手动执行 [基础四表 SQL](docs/database.md),并创建 [迁移任务表](docs/admin-database.md)。已有数据库执行管理端文档的增量 SQL;应用不会自动迁库。
3. 在 Gitea 创建私有组织,将技术账号设为组织所有者,生成具有 write:repository、write:organization、read:user 权限的 Token。
4. 将 .env.example 复制为 .env,填写数据库连接、Redis 连接与 Gitea 地址、组织、Token;默认使用 test 环境,.env 被 Git 忽略,不提交真实凭据。
5. 执行:
```bash
bash scripts/run-local.sh
```
当前机器已配置 Gitea 26.4.0,并建立私有组织 vibemake。本机 .env 已保存 Gitea Token,权限为 0600;没有保存管理员密码。保留这些 Gitea 配置,再补充 DB_URL、DB_USERNAME、DB_PASSWORD 和 REDIS_* 连接配置,不要用示例覆盖已有 Token。
直接部署时通过环境变量配置,运行打包后的 vibemake-api/target/vibemake-api-0.0.1-SNAPSHOT.jar。默认端口 8993,SERVER_PORT 或 PORT 可覆盖(SERVER_PORT 优先)。本机脚本会加载 .env,直接运行 jar 不会自动加载该文件。
接口文档:[前端接口对接文档](docs/vibemake-api.md),包含全部接口、字段结构、请求响应示例、页面调用顺序和错误处理。test 环境启动后访问 /swagger-ui.html;机器可读 OpenAPI 为 /v3/api-docs。prod 默认关闭这两个入口。
## 环境与日志
配置与日志方式参考 cadworld:application.yml 保存公共配置,application-test.yml 和 application-prod.yml 分别保存环境相关的数据库、Gitea、跨域白名单和日志配置。不指定环境时默认 test,通过 SPRING_PROFILES_ACTIVE 或启动参数切换。
prod 启动时检查数据库连接、用户名、密码、Gitea 地址和 Token 是否已配置且非空;缺失时停止启动,错误信息只包含配置项名称。
| 配置 | test | prod |
| --- | --- | --- |
| 数据库 | 默认本机 vibemake,可用 DB_* 覆盖 | 必须配置 DB_URL、DB_USERNAME、DB_PASSWORD |
| Gitea | 默认本机地址,使用 GITEA_* 覆盖 | 必须配置 GITEA_BASE_URL、GITEA_TOKEN、GITEA_ORGANIZATION |
| API 跨域来源 | `https://dev-vibemake.robotquan.com` | `https://vibemake.robotquan.com` |
| OSS 封面目录 | vibemake_dev/project-covers/ | vibemake/project-covers/ |
| OSS URDF 目录 | vibemake_dev/urdf/{projectCode}/{batchCode}/ | vibemake/urdf/{projectCode}/{batchCode}/ |
| OSS README 图片目录 | vibemake_dev/readme-images/ | vibemake/readme-images/ |
| 连接池 | 最少 1、最多 10 个连接 | 最少 1、最多 20 个连接 |
| 项目日志级别 | DEBUG | INFO |
| 日志目录 | logs,可用 LOG_PATH 覆盖 | logs,可用 LOG_PATH 覆盖 |
生产部署示例(先在部署环境配置以上连接变量):
```bash
SPRING_PROFILES_ACTIVE=prod java -Djava.awt.headless=true -jar vibemake-api/target/vibemake-api-0.0.1-SNAPSHOT.jar
```
本机脚本支持传递启动参数,例如 `bash scripts/run-local.sh --spring.profiles.active=prod`,此时加载 .env 中的连接信息并使用 prod 配置。测试和生产数据库、Gitea 组织需要各自隔离时,分别设置对应的 DB_*、GITEA_* 变量。
跨域白名单由 `vibemake.cors.allowed-origins` 指定,仅作用于 `/api/**`。支持 Bearer Token、JSON、文件上传下载和 AI SSE,预检缓存 3600 秒,暴露 `X-Request-Id`、`Content-Disposition`、`Retry-After`,不启用跨域 Cookie 凭据。启动日志会记录生效的白名单。默认不开放 HTTP、localhost、其他端口或跨环境来源;本地继续使用前端开发代理,配置见[开发代理示例](docs/vibemake-api.md#开发代理示例)。部署代理需透传预检请求、Origin 和后端 CORS 响应头,避免重复添加跨域头;OSS Bucket 的 CORS 仍需独立配置。
日志配置沿用 cadworld-common 的 logback-spring.xml 模板,放在 vibemake-common;应用名为 vibemake-api。测试和生产默认都写入 logs,可用 LOG_PATH 覆盖目录;目录相对于应用启动时的工作目录。本机启动脚本从项目根目录运行。
同时输出控制台、vibemake-api.log 和 vibemake-api-error.log,日志时间使用 Asia/Shanghai,格式包含线程、级别、requestId 和类名。应用日志按天或每 100MB 归档,保留 30 天、总归档上限 10GB;错误日志仅接收 ERROR,按天或每 50MB 归档,保留 60 天、总归档上限 5GB。归档写入 archive 子目录并压缩为 gzip。SQL Mapper 和 Spring Web 保持 INFO,不记录凭据、邮箱或代码内容。
业务数据库与接口中的日期时间统一使用 `Asia/Shanghai`,不依赖服务器默认时区;接口中不带时区后缀的时间需按 `+08:00` 解析。OSS 签名协议字段保留 UTC,Git 提交日期保留原时区。已有 UTC 数据库升级前,先按[业务时间迁移说明](docs/admin-database.md#业务时间由-utc-迁移到上海时间)完成一次性转换,再同时部署社区端、管理端与导入工具;前端同步调整解析方式。
## 仓库归档下载配置
用户端工作区与社区均支持 ZIP、TAR.GZ 仓库归档:工作区需登录且只能下载本人项目,支持当前 main 或指定历史 SHA;社区可匿名下载当前已发布 SHA。后端鉴权后直接流式转发 Gitea 原生归档,不向浏览器返回 Gitea 凭据或内部地址,无需数据库变更,也不新增本地 Git 或临时磁盘依赖。
| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| ARCHIVE_MAX_BYTES | 1073741824 | 压缩包最大字节数,默认 1 GiB,独立于单文件与 multipart 限制 |
| ARCHIVE_TIMEOUT | 5m | 获取当前 SHA、归档响应及响应体读取的上游预算 |
| ARCHIVE_MAX_CONCURRENT | 2 | 每实例独立归档并发,超限返回 ARCHIVE_BUSY,不占用普通文件并发额度 |
| RATE_ARCHIVE_READ_PER_MINUTE | 10 | 每 IP 每分钟归档额度,工作区与社区共用 |
对应配置为 `vibemake.archive.max-bytes`、`timeout`、`max-concurrent` 和 `vibemake.limits.per-minute.archive-read`;大小必须大于 0,并发为 1~32,超时为 100 毫秒~1 小时。沿用 Gitea 服务端 Token,需具有目标私有仓库的读取权限。上线前确认 `/api/v1/repos/{owner}/{repo}/archive/{SHA}.zip`、`{SHA}.tar.gz` 均直接返回 HTTP 200 文件;本服务不跟随重定向。Gitea 使用对象存储归档并返回重定向时,应配置 Gitea 直接输出归档(1.26.4 的 `[repository] STREAM_ARCHIVES=true` 支持此行为)。
代理读取超时至少 400 秒;调大 ARCHIVE_TIMEOUT 时同步增加代理超时,流式响应应关闭代理缓冲和缓存。中途超限、超时或连接断开会停止传输,已发送附件后不能再返回 JSON,下载文件可能不完整,应丢弃并手动重新下载。本期不支持断点续传、下载任务或进度查询。
归档沿用 Gitea 原生规则,LFS 保留指针,不下载实体,不递归下载子模块,也不包含单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源。接口及支持取消的 fetch 示例见[仓库 ZIP、TAR.GZ 下载](docs/vibemake-api.md#仓库-ziptargz-下载)。
## 验证
```bash
mvn clean verify
```
普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea/AI/OSS,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞、URDF 直传核验和独立复制,以及 AI 筛选、引用校验、创建、Fork 与候选选择、SSE、限流、超时和取消,不访问真实数据库、仓库、对象存储或模型。未加载外部服务凭据时,执行 `GIT_ENABLED=false AI_ENABLED=false VIBEMAKE_AI_ENABLED=false OSS_ENABLED=false mvn verify`;其中 `GIT_ENABLED` 关闭需要独立凭据的 Git 网关,`VIBEMAKE_AI_ENABLED` 用于覆盖管理端当前固定开启的 AI 配置,对应流程测试自行启用模拟服务。完整安装验证可执行 `GIT_ENABLED=false AI_ENABLED=false VIBEMAKE_AI_ENABLED=false OSS_ENABLED=false mvn clean install`。
PCB 个人工作空间提供 `/api/pcb/workspace/projects` 八个接口,支持独立列表、完整工程 ZIP 直传保存、幂等确认与版本冲突保护。上线前手工执行 [PCB 建表 SQL](docs/pcb-database.md),配置共用 OSS 后设置 `PCB_OSS_ENABLED=true`;默认关闭,ZIP 默认上限 256 MiB、上传有效期 15 分钟。前端对接与部署见 [PCB 工作空间文档](docs/frontend-pcb-workspace.md)。普通测试覆盖 PCB 与 CAD 保存链路,不访问真实 OSS。
真实 Gitea 联调:
```bash
python3 scripts/test-gitea.py
```
该测试使用临时 H2 数据库,在配置的组织创建临时项目仓库,验证私有仓库、多文件提交、中文路径、二进制上传、ZIP/TAR.GZ 归档、固定发布版本及快照 Fork,结束后仅删除本次测试创建的仓库。归档联调核对中文路径、二进制内容、LFS 指针及发布后继续提交时的版本隔离。Gitea 26.4.0 内置的 1.26.4 支持批量文件变更;以服务器 /swagger.v1.json 为对接依据。
## 测试 Gitea 组织仓库复制到生产
`scripts/migrate-gitea-org.py` 使用 Python 3.9+ 标准库,将测试 `vibemake` 下的 Git 仓库复制到生产 `vibemake`(组织可通过参数修改)。生产 Gitea 应先初始化,并创建目标组织。目标为同名私有普通仓库,保留默认分支、历史、分支和标签,并请求迁移 LFS;不复制 Issue、PR、Release、Wiki、用户、组织成员、权限、Webhook 或 Actions 执行记录,也不导入 Gitea 整库、不复制实例配置。
两端账号需是对应组织的所有者或站点管理员。测试 Token 需有 `read:repository`、`read:organization`、`read:user`、`read:misc`,生产 Token 需有 `write:repository`、`write:organization`、`read:user`、`read:misc`;仓库访问范围应包含私有仓库。迁移期间暂停源组织写入、导入任务以及目标后端写入,Gitea 本身保持运行。生产 Gitea 容器必须能通过 HTTP Git 和 LFS 访问测试地址,两端开启 HTTP Git/LFS,生产开启仓库迁移。
在项目根目录执行(替换地址):
```bash
# 两次提示分别输入测试、生产 Token,输入不回显,不会写入命令历史。
# 默认只读预览;不自动读取现有 .env,避免把两个环境的凭据混用。
python3 scripts/migrate-gitea-org.py \
--source-url https://测试Gitea域名 \
--target-url https://生产Gitea域名 \
--dry-run
# 先复制一个尚未处理的仓库。
python3 scripts/migrate-gitea-org.py \
--source-url https://测试Gitea域名 \
--target-url https://生产Gitea域名 \
--execute --limit 1
# 抽查通过后,用相同状态目录续跑其余仓库。
python3 scripts/migrate-gitea-org.py \
--source-url https://测试Gitea域名 \
--target-url https://生产Gitea域名 \
--execute
```
可重复指定 `--repo p_项目编码` 限定仓库;`--source-org` 默认 `vibemake`,`--target-org` 默认 `vibemake`。非交互执行可通过 `GITEA_MIGRATION_SOURCE_TOKEN`、`GITEA_MIGRATION_TARGET_TOKEN` 注入凭据,不接受 Token 命令行参数。默认只允许 HTTPS;仅在可信网络确需明文连接时指定 `--allow-http`。API 请求不跟随重定向,不将凭据放入 URL、状态文件或日志。迁移请求会将源账号和 Token 放在发往生产 Gitea 的请求体中,生产 Gitea 用它们读取源私有 Git/LFS。单仓库请求超时默认 1800 秒,可用 `--migration-timeout` 调整;生产反向代理的超时也应相应配置。
`--state-dir` 默认 `logs/gitea-org-migration`,同一批次只允许运行一个进程;目录权限 0700,文件权限 0600。目录绑定源/目标地址、组织和初始仓库清单;组织仓库发生增删或同名重建时停止,不自动改变迁移范围。`state.json` 保存进度、源分支/标签快照及成功迁移返回的目标仓库标识;`mapping.json` 仅包含已取得 HTTP 201 完成收据并核对仓库身份、私有属性、默认分支、分支和标签提交的记录。LFS 由 Gitea 迁移流程处理,脚本不逐对象下载核验;先试迁一个带 LFS 的仓库,用 `git lfs pull`/实际下载检查实体后再批量执行。子模块只保留 Git 引用,不递归复制其他仓库。
生产同名仓库标记 `CONFLICT`,不接管、不覆盖。超时、服务端错误、返回状态不明确或迁移中断时标记 `REVIEW`,停止本次新增仓库;Gitea 可能仍在后台执行,不能仅凭仓库存在认定 LFS 已完成。保留状态目录并核对生产日志及仓库;没有成功收据的记录不会自动重发。有成功收据、仅核验失败的记录,在续跑时只读核对。不要删除状态文件来盲目重试,也不要自动删除生产仓库。退出码 0 表示本次无冲突/待核对项(预览或 `--limit` 仍可能有 `PLANNED`),2 表示存在 `CONFLICT`/`REVIEW`,1 表示预检或运行环境错误。
历史导入中断后,源数据库的 `empty` 标记可能与磁盘内容不一致;脚本会检查实际 Git 引用,存在引用时按 Git 对象 SHA 核对分支和标签。LFS 还需核查迁移日志:Gitea 可能忽略源端缺失的 LFS 对象后仍返回 HTTP 201。出现 `Ignoring missing upstream LFS object` 时,应按对象 SHA-256、大小建立缺失清单,从可信原始上游或备份恢复,并验证生产端实体可下载;不能把成功响应当作缺失文件已补齐。
仓库复制后,生产社区后端设置自己的 `GITEA_BASE_URL`、`GITEA_TOKEN` 和 `GITEA_ORGANIZATION=vibemake`。此工具不连接业务数据库;已复制到生产的 `project` 记录还需按 `mapping.json` 核对项目编码及原仓库标识,再在生产业务库回写 `gitea_owner` 和新的 `gitea_repo_id`,保持 `gitea_repo_name`、发布提交 SHA 等值,并确认已发布 SHA 可读取。`gitea_repo_id` 有唯一索引,回写需处理旧标识与新标识的冲突;备份后在维护事务中执行,不改测试业务库。原 GitHub 导入批次的收据不能直接当作新生产仓库收据复用。OSS 封面、URDF、业务用户及项目记录的复制需单独处理。
## 项目封面与 OSS 直传
项目 API 的 `coverUrl` 接收和返回完整 HTTPS 地址,平台封面在数据库中保存 `/project-covers/...` 环境相对路径,外部图片保留完整 URL。无封面时返回 null;创建时可省略,修改时省略或 null 保留原值,传空字符串清除。Fork 继承同一资源引用,替换、清除或删除项目不自动删除 OSS 图片。URDF 同样保存 `/urdf/...` 环境相对路径,上传和 OSS 操作仍使用含环境根目录的真实 key。人工迁移和回退见 [数据库说明](docs/database.md#资源路径历史数据迁移)。
已有数据库必须先执行 [封面字段升级 SQL](docs/database.md#已有数据库增加项目封面),再部署新应用;新建数据库使用更新后的建表 SQL。应用不会自动变更表结构。
OSS 默认关闭,外部 HTTPS 封面仍可使用。启用时设置 `OSS_ENABLED=true`,并配置 `OSS_REGION`、`OSS_BUCKET`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`。地域 ID 使用 `cn-beijing` 等编码,不带 `oss-` 前缀。Endpoint 默认根据地域推导为 `https://oss-{region}.aliyuncs.com`,无需配置环境变量;特殊域名场景可显式配置 `vibemake.oss.endpoint`,使用可供浏览器访问的公网 HTTPS 地址,不包含 Bucket、路径或查询参数。`OSS_PUBLIC_BASE_URL` 可选,用于公开 CDN/OSS 基础地址;省略时使用 Bucket 标准 HTTPS 域名。启用但配置缺失或不合法时停止启动,未启用时签名接口返回 503 `OSS_UNAVAILABLE`。
目录由环境配置指定:test 使用 `vibemake_dev/`,prod 使用 `vibemake/`;二者均为桶内对象前缀。凭据使用仅能写入对应环境 `project-covers/*` 路径的 RAM 用户,密钥保留在服务端。实际 Bucket 和 CDN/OSS 域名由部署环境提供,不由应用创建。
登录后请求 `POST /api/uploads/project-covers/signature`,获得 OSS POST V4 表单和固定 `coverUrl`。签名有效期 5 分钟,支持 JPG、PNG、WebP,单张最多 5 MiB。浏览器直传成功后再保存项目,后端不接收图片内容。签名支持创建项目前上传;当前不提供上传完成回调、服务端图片内容检测或未绑定图片自动清理。
Bucket 需要配置前端实际域名的 CORS,允许 POST;图片通过公开读取规则或公开 CDN 地址访问。完整配置步骤、错误处理和前端 FormData 示例见[封面上传接口](docs/vibemake-api.md#项目封面与-oss-直传)。官方协议参考 [OSS POST V4](https://www.alibabacloud.com/help/en/oss/developer-reference/signature-version-4-recommend) 和[服务端签名直传](https://www.alibabacloud.com/help/en/oss/user-guide/obtain-signature-information-from-the-server-and-upload-data-to-oss)。
部署验收:在 test 环境登录,获取签名、浏览器直传、保存项目并匿名访问封面;确认 OSS 对象位于 `vibemake_dev/project-covers/`,网络请求中的图片内容直接发往 OSS。prod 切换到 `vibemake/project-covers/`,图片地址不带临时下载签名。
## Maker AI
设置 `AI_ENABLED=true` 和 `ARK_API_KEY` 后启用,默认模型为 `doubao-seed-2-1-lite-260915`,地址为 `https://ark.cn-beijing.volces.com/api/v3/responses`。使用 `ARK_MODEL`、`ARK_ENDPOINT` 可覆盖。与 cadworld 一样使用 Responses API 和 JSON Schema,关闭深度思考,`store=false`;密钥只在后端读取。未开启时接口返回 503 `AI_UNAVAILABLE`;开启但没有密钥时停止启动。
登录后调用 `POST /api/community/ai/chat`,通过 SSE 获取阶段、结果或错误。对话由前端保留最近6轮,刷新后清空,不保存到数据库。
Maker AI 支持身份介绍、日常闲聊、一般知识和技术问答,包括文本代码示例。聊天与意图识别共用一次模型调用,返回 CHAT、完整 reply、空 projects 和 null project,不联网、不执行代码、不写入项目。回复最多2000字符,可直接加入 history;聊天只有 understanding → result 两个 SSE 事件,不逐字输出。前端收到 CHAT 后追加历史并保留 previousProjectCodes,支持搜索后穿插闲聊再选择项目。
同时支持查找、创建空项目和 Fork 已发布项目;模型提取结构化项目意图,后端校验后复用现有项目服务,每轮最多一次写入。闲聊不会触发历史中的待办或已完成操作。创建时可生成名称和目标描述,类型无法判断时默认 GENERAL,仅初始化仓库和默认 README。Fork 默认沿用来源名称,按执行时的当前发布版本复制;查找并 Fork 仅在本轮唯一推荐结果时执行,多个候选返回 NEEDS_SELECTION 供下一轮选择。成功通过 CREATED/FORKED 和 project 返回新项目,前端使用 projectCode 进入工作区。
查找时仅检索已发布且仓库就绪项目的名称、描述、类型:先理解需求,再查询最多20个候选,最后排序并校验最多5个项目卡片。项目编码、引用原文和当前发布状态由后端校验;缺少依据的明确要求不算匹配,未证实的偏好单独列出。
每次模型调用默认30秒,模型/搜索阶段65秒;进入 Fork 阶段后采用独立5分钟预算并保留15秒入口及终态余量,前端和代理读取超时至少400秒;`AI_REQUEST_TIMEOUT`、`AI_SEARCH_TIMEOUT` 可调整。`AI_MAX_CONCURRENT` 默认4,`AI_REQUESTS_PER_MINUTE` 默认每用户10次,均为单实例内存控制,超限不排队。连接断开时尽力取消上游调用,实际工作结束后释放并发名额。写入开始后取消或超时不保证回滚;错误事件保留初始化异常中的 projectCode,先核对工作区,不自动重发创建或 Fork。AI 错误不影响普通项目搜索。前端请求和 SSE 解析示例见接口文档的“Maker AI”。
本期不读取 README、代码或评论,不建立向量索引,不修改四表结构。检索效果依赖项目描述,建议写清用途、技术栈、主要硬件和适用场景。描述修改即时生效;工作区文件提交仍须重新发布才更新社区代码。
真实模型联调(会调用方舟并产生模型用量):
```bash
python3 scripts/test-ai.py
```
脚本在内存 H2 中建立公开示例项目,验证 Maker AI 身份介绍、代码问答、多轮聊天、闲聊不重放创建/Fork,以及四足检索后穿插闲聊再改为轮式,默认 Maven 测试跳过该联调。密钥从当前项目 `.env` 或环境变量读取,脚本不输出密钥、不写真实数据库、不访问 Gitea。
## Git 快照 Fork
后端保留鉴权、项目编码、来源记录和 OSS 复制,仓库数据通过 Git 对象级传输。按发布 SHA 的根 tree 生成一个无父提交,只推送新 main;保留普通大文件、文件模式、符号链接和子模块引用,不继承上游历史、其他分支或标签。子模块依赖仓库不递归复制。LFS 仅传输发布快照所需实体,推送后从新副本独立下载校验;不会只有指针却缺少实际对象。
应用运行用户的 PATH 需要包含 Git 和 git-lfs(本机验证 Git 2.52 / git-lfs 3.8)。CI 同样安装这两个程序,执行本地 Git 仓库及模拟 LFS 协议测试;普通业务测试替换仓库传输边界,不访问外部服务。启动时检查依赖,缺失仅使 Fork 返回 FORK_UNAVAILABLE,不阻止普通创建或其他接口。
开发环境可通过 `brew install git git-lfs` 安装;Debian/Ubuntu 的 CI 或部署镜像安装 `git`、`git-lfs` 软件包。以应用运行用户执行 `git --version` 和 `git lfs version` 确认 PATH 生效,无需执行全局 `git lfs install`。LFS 传输通过任务内的本地端点校验转发,拒绝 HTTP 重定向及指向其他地址的 action URL;临时目录禁止写入 git-lfs 原始错误报告,防止环境凭据落盘。
| 配置 | 默认值 | 用途 |
| --- | --- | --- |
| FORK_GIT_EXECUTABLE | git | Git 可执行文件路径,git-lfs 从子进程 PATH 查找 |
| FORK_TIMEOUT | 5m | Git、LFS、核验和 OSS 共用的总时间预算 |
| FORK_MAX_CONCURRENT | 2 | 单实例并发上限,实际工作结束后释放名额 |
| FORK_MAX_TEMPORARY_BYTES | 5368709120 | 每次临时磁盘上限,含 LFS 源缓存与副本校验缓存 |
| FORK_TEMPORARY_DIRECTORY | 系统临时目录/vibemake-fork | 建议使用容量充足的独立临时磁盘 |
服务账号的 GITEA_TOKEN 需同时允许 REST 仓库创建、HTTP Git 读写及 LFS 读写。凭据通过进程环境注入,只用于配置的 Gitea 地址;不写入 URL、命令参数、Git 配置或日志。Fork 接口继续同步返回,前端和反向代理读取超时至少400秒;AI 进入 forking 后切换专用预算并继续发送心跳。
Fork 不受 JSON 文件预览的 50 MiB 限制或单文件流式下载的 1 GiB 限制。Fork 失败时先核对响应 data.projectCode:明确失败为 FAILED,远端写入或数据库状态待核对为 CREATING;不会自动重发、删除远端仓库或 OSS 对象。完成后清理本地临时目录。使用 scripts/test-gitea.py 可执行显式真实 Gitea 联调,仅创建并清理本次测试专用仓库,不修改已有社区项目。
JSON 预览保留原有上限;三个端的 `download=true` 使用流式传输,默认单文件最大 1 GiB、上游处理和读取预算 5 分钟,分别由 `FILE_DOWNLOAD_MAX_BYTES`、`FILE_DOWNLOAD_TIMEOUT` 配置,LFS 指针不在线展开。下载路径需关闭代理响应缓冲并为代理和客户端至少预留 400 秒超时,详见[文件接口](docs/vibemake-api.md#目录和文件读取)。
## 运行约定
项目名称、描述、类型、封面修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。
创建或 Fork 前先写入 CREATING 项目,成功后标记 READY。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。
## 项目短编码与 GitHub 初始化导入
### README 外链图片转存 OSS
GitHub 后台迁移和 Excel 命令行导入在分支适配后自动检查根目录 `README.md`(文件名不区分大小写)。支持 Markdown 图片、引用式图片、HTML `img src`、`srcset` 和 `picture` 图片;仓库相对路径、代码示例、普通超链接及已配置的 OSS/CDN 地址保持原样。动态徽章(shields.io、GitHub Actions、ROS 构建状态、常见覆盖率徽章)保留原链,普通静态 SVG 通过安全校验后可以转存;仅外部 DTD 声明会移除,脚本、内部实体和远程资源引用仍禁止。其他语言的 README 或子目录文档不在本次处理范围。
设置 `README_IMAGES_ENABLED=false` 可以暂停转存;默认启用,单图上限 `README_IMAGE_MAX_BYTES=20971520`,图片并发 `README_IMAGE_CONCURRENCY=2`(1~4)。可在配置的 `vibemake.readme-images.preserve-url-patterns` 中追加需要保留的完整 URL 正则。图片只下载公开 HTTP/HTTPS 地址,不携带业务凭据;单图总预算 45 秒,每次 DNS 解析及重定向都禁止内网地址。JPG、PNG、GIF、WebP 和安全 SVG 按内容摘要写入 `{环境根目录}/readme-images/{SHA256}.{扩展名}`,不覆盖已有对象;上传核验并从公开地址读取核验成功后才替换 README。RAM 账号需要对应前缀的 PutObject/GetObject 权限,资源需要公开可读或通过公开 CDN 访问。
存量项目在项目根目录运行:
```bash
# 仅扫描数据库与仓库,不下载外链、不上传图片、不修改项目。
bash scripts/migrate-readme-images.sh --dry-run
# 先处理一个含待转存图片的项目。
bash scripts/migrate-readme-images.sh --execute --limit 1
# 同一状态目录断点续跑其余项目。
bash scripts/migrate-readme-images.sh --execute
# 指定项目重新尝试仍失败的图片,使用新的状态目录保存独立收据。
bash scripts/migrate-readme-images.sh --execute --project-code 项目编码 --state-dir logs/readme-image-retry
```
默认状态目录 `logs/readme-image-migration` 绑定 Gitea、组织、OSS Bucket、环境目录和公开基础地址,禁止跨环境复用;同时只允许一个进程使用。保存精确预览、原 README 备份、原发布 SHA、每一步操作收据和结果报告,目录/文件权限分别为 0700/0600,写入原子替换并持久化。脚本使用 `java-with-env.py` 安全读取 `.env` 字面量,不进行 shell 求值;含 `&` 的 JDBC 地址可正常读取,文件中的配置覆盖同名进程变量,与原有启动脚本一致。不会修改 `.env` 或输出配置值。
未删除且仓库 READY 的项目才进入批处理。main 与原发布版本一致时复用一个图片提交;不一致时从原发布 SHA 创建 `maintenance/readme-oss/...` 维护分支,确认仅 README 变化后更新发布引用。维护分支保留以确保快照可下载和 Fork;不将 main 上其他未发布代码带入社区,不改变撤回/下架状态或发布时间。GitHub 后台迁移仍由管理员手动发布,Excel 导入仍自动发布处理后的版本,来源 SHA 与图片提交 SHA 分开保存,兼容历史迁移收据。
图片下载失败、格式不支持或 OSS 不可用时保留原链并记录告警,其余图片继续;Git 写入结果不明确则保持待核对状态,续跑只查收据,不重发提交。报告的 `failed` 是保留原链的图片引用数。恢复业务展示可在项目锁中对照备份条件回写原发布 SHA;恢复 main 需基于当前版本提交 README 的反向修改,不能强制重置分支。不要删除共享 OSS 对象或维护分支。一般日志只记录项目编码、来源主机、阶段和错误码,含完整图片地址的原文只保存在受限备份中。
### 历史外链封面转存 OSS
`scripts/migrate-project-covers.sh` 读取本项目 `.env`,将数据库现有外链图片下载并转存至当前环境 OSS,上传并核验成功后才更新 `cover_url`。配置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`OSS_REGION`、`OSS_BUCKET`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`;带 `&` 的 JDBC 地址必须加引号。环境根目录沿用 test 的 `vibemake_dev` 或 prod 的 `vibemake`。
```bash
# 默认只读预览,不下载、不上传、不更新数据库。
bash scripts/migrate-project-covers.sh --dry-run
# 先迁移三个项目,核对新封面的访问效果。
bash scripts/migrate-project-covers.sh --execute --limit 3
# 迁移其余外链,默认并发 2。
bash scripts/migrate-project-covers.sh --execute
```
支持 JPG、PNG、GIF、WebP,按实际文件头识别类型,原图不压缩、不转码。默认单图最多 5 MiB,可用 `--max-bytes` 调整,上限 50 MiB;`--concurrency` 范围为 1~4。下载只允许公开 HTTPS 地址,每次跳转重新校验,不携带任何平台或 GitHub 凭据,不访问内网地址。失效、超时、超限及非图片资源保留原值并进入失败报告。
实际对象位于 `{环境根目录}/project-covers/migrated/{图片SHA256}.{扩展名}`;数据库只保存 `/project-covers/migrated/...`。相同外链只下载一次,相同图片内容复用对象,已转存记录在再次运行时自动跳过;已属于本平台的完整 URL 也跳过,可按数据库迁移说明归一化。扫描包含已逻辑删除项目,以完成历史数据统一。未来新提交外链的行为不由此批处理修改。
每次运行在 `logs/cover-migration/` 生成独立报告目录(可用 `--report-dir` 修改)。`preview.json`、`report.json` 只包含项目编码、来源主机、状态及错误码,不记录完整外链或查询参数。`backup.jsonl` 保存修改前原值和拟写入路径,更新前强制落盘;目录和备份文件分别仅允许当前用户访问。原值可能包含签名参数,应作为受限数据库备份保存,不上传仓库或发送聊天。回写通过项目编码和原始 URL 字节比较,跳过迁移期间被修改的封面,不改 `updated_at`,不覆盖其他字段。
失败时可以重跑;上传成功但回写未完成的对象也按内容哈希复用,不会自动删除可能共享的对象。退出码 0 表示成功或仅预览,1 表示配置、连接等整体错误,2 表示存在逐项失败。人工恢复时仅将仍等于 `newCoverPath` 的记录按项目编码还原为 `originalCoverUrl`,避免覆盖之后的编辑。
对已经核验过的失效链接,可使用 `--source-overrides /绝对路径/备用源.json` 指定备用下载地址,JSON 格式为 `{"项目编码":"https://可信图片地址"}`。下载走同一套 HTTPS、大小和图片类型校验;数据库条件比较及原值备份仍使用原来的外链。采用的备用源另存于受限权限的 `source-overrides-backup.json`,便于审计。已成功迁移的项目在重跑时照常跳过。网络中断最多重试三次,证书校验失败不会绕过验证。
### 项目编码与导入流程
普通创建、Fork 和导入的新项目使用 12 位小写项目编码,字符集为 `0123456789abcdefghjkmnpqrstvwxyz`。普通项目用安全随机数生成,项目编码唯一约束冲突最多重试 5 次;其他约束错误不重试。首次导入编码由 `github-import:v1:<GitHub仓库ID>` 的 SHA-256 前 60 位确定,避免重跑或仓库更名后重复创建。后台在线迁移仅对未删除项目做来源去重;旧项目删除后再次新建迁移,使用来源与迁移代次生成新编码、新任务和新仓库,重新拉取 GitHub 内容,保留旧记录及仓库。管理员列表和详情仍隐藏已删除项目。已有后台需先执行[来源索引调整 SQL](docs/admin-database.md#允许已删除项目的-github-来源再次迁移本次上线前执行)。Gitea 仓库名称为 `p_{projectCode}`。历史 32 位编码、仓库及链接继续使用,无需因编码长度修改数据库字段。
导入工具仅接受以下固定 Sheet:`1_轮式机器人`、`2_四足机器人`、`3_小人形机器人`、`4_大人形机器人`、`5_机械臂`、`6_其他类型`、`7_开源硬件`。只选 I 列精确为“可访问”、L 列有合法 HTTPS 封面、B 列为具体 GitHub 仓库的行。其他 Sheet 不参与导入;K 列图片公式不会执行。原始 A~H 数据列与表头存在错位,工具按实际位置读取,忽略 H 列的无意义备注 `100`,不将“待查”等信息改写成已确认。
外部封面保留原 URL 和 GIF,不转存 OSS;当前环境的平台封面统一转换为相对路径。描述由原中文简介和技术资料组合,不调用 AI。轮式、四足、人形分别映射对应类型,机械臂映射 ROBOTIC_ARM,其他和硬件映射 GENERAL,原始分类保留在描述里。
脚本加载本项目 `.env`,依赖 Java 21、Maven,以及正式执行时可用的 MySQL 和 Gitea。独立导入模块不启动 Web 服务,也不加载登录或 AI。资源地址转换无需 OSS 凭据;README 图片转存按需初始化 OSS 客户端,未配置凭据时保留原链并产生告警。test/prod 根目录与在线应用一致,历史公开地址使用 `OSS_LEGACY_PUBLIC_BASE_URLS`。Gitea 技术账号需具备组织所有者及仓库写权限,实例需开启迁移、HTTP Git 和 LFS。`GITHUB_TOKEN` 可选,仅用于 GitHub 元数据 API;API 限流时读取同一公开仓库的 GitHub 网页,交叉核验仓库 ID、规范地址、公开状态和默认分支,缺失或不一致则预检失败。网页和图片请求均不携带凭据。`GITEA_TOKEN` 仅访问配置的 Gitea,不能代替 `GITHUB_TOKEN`;切勿把 Token 放进 URL 或命令参数。
```bash
IMPORT_EXCEL='/绝对路径/项目.xlsx'
# 仅验证静态筛选,不访问网络、业务库或 Gitea。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --offline
# 默认 dry-run:在线检查仓库和图片,并生成清单;不写业务库或 Gitea。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --dry-run
# 先试导前三个尚未完成的候选。必须使用已有有效用户的 userCode。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --execute --owner-user-code '<用户编码>' --limit 3
# 试导检查通过后,用相同状态目录续跑其余项目。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --execute --owner-user-code '<用户编码>'
```
`--owner-email` 可替代 `--owner-user-code` 查找已有账号,二者互斥,工具不会创建用户;状态中始终保存查到的用户编码。`--state-dir` 默认 `logs/github-import`,包含原子写入的 `manifest.json` 和 `report.json`;此目录必须保留并备份,不能在迁移进行中删除。清单绑定 Excel 指纹、归属用户和 Gitea 目标,不能复用于另一文件或环境。同一目录有进程锁,`--concurrency` 默认为 2,可选 1~4;同一批次只运行一个进程。`--limit` 限制尚未完成候选的处理数量;已完成项目、迁移结果未知或不具备收据核对条件的 REVIEW 项目不计入。
导入清单和报告通过 `timeZone` 声明 `Asia/Shanghai`。旧版未声明时区的清单首次由新版读取时,会将 `reservedAt` 从 UTC 转为上海时间并原子保存,之后续跑不会重复转换;应先完成业务库历史时间迁移,并备份状态目录后再使用新版续跑。
工具先创建 CREATING 项目记录,直接调用 Gitea `/repos/migrate`,不先创建空仓库。迁移使用私有普通仓库、开启 LFS,保留 Git 内容、历史、分支和标签;不迁移工单、PR、Wiki 或 Release 附件。迁移成功收据先落盘,再关联项目并自动发布。独立迁移请求默认超时 1800 秒,可用 `--migration-timeout-seconds` 调整,普通 Gitea 请求超时不变。原默认分支不是 main 时补建 main 并设为默认,保留原分支;同名 main 内容冲突时停止该项目,不覆盖源分支或已冻结版本。
进程在 MIGRATING 阶段中断,或迁移超时、结果不明确时,项目进入 REVIEW,禁止自动重发或仅凭仓库存在判定成功。需要核对 Gitea 迁移及 LFS 完成情况、来源和提交后由维护人员处理;不要直接把 REVIEW 改为 READY 或删除仓库再重跑。已确认的迁移收据会用于数据库回写或发布失败后的续跑,避免重复迁移。对于已持久化成功收据、仅在主分支适配时出现不明写入结果的项目,续跑先只读核对仓库身份、来源、私有属性、默认分支和两条分支的冻结 SHA;全部一致才继续关联和发布,否则保持 REVIEW,不重发分支写入。已完成项目不会因后续人工撤回、修改或删除而被批次重新发布。
报告逐项包含 Sheet、行号、短编码、阶段、错误码和兼容性提醒。退出码 0 表示本次选定工作完成,1 表示命令、配置或持久化等致命错误,2 表示存在预检未通过、失败或待核对项目。在线仓库或图片失效会减少实际导入量;报告中的候选数仍与静态筛选对账。
本次只完成仓库迁移、关联和发布。在线浏览和下载仍有单文件限制,LFS 实体、子模块及符号链接的在线浏览能力未扩展;Git 快照 Fork 已支持大文件、LFS 实体、符号链接及子模块引用,依赖仓库仍不递归复制。当前发布快照检测到的限制会写入报告。子模块只保留引用,不递归迁移独立仓库,也不下载网盘或其他外链资源。保留所有分支不代表社区提供分支切换界面。
## 管理端
独立端口默认 `8994`,共用现有 `sys_user`,通过 `USER/ADMIN/OFFICIAL` 角色鉴权,不新增管理员或会话表。后台管理员以邮箱和 BCrypt 密码登录;会话使用 Redis,默认 8 小时,应用重启后保留未过期会话。社区端和后台各单实例,使用不同 Redis Key 域,Token 不互通。
启用前先手工执行 [管理端 SQL](docs/admin-database.md),停止并排空旧写入进程,更新社区端、后台和 Excel 导入工具,最后启用后台。全部仓库写入端使用相同数据库的项目命名锁;不可让仍使用本地锁的旧版应用并行写入。
```bash
bash scripts/run-admin-local.sh
# 将一个已有普通用户初始化为管理员,交互输入密码,不传明文密码参数。
bash scripts/run-admin-local.sh --bootstrap-admin-user-code='<已有用户编码>'
# 真实 MySQL 验证:创建并删除随机临时库,不改现有业务数据。
bash scripts/test-admin-mysql.sh
```
前端对接见 [管理后台接口文档](docs/admin-api.md),服务初始化、配置与故障处理见 [管理端部署说明](docs/admin-deployment.md)。数据库 SQL 不会由启动脚本自动执行;真实仓库迁移和正式发布需在部署后由管理员通过接口触发,普通测试不会访问真实 GitHub、Gitea 或 OSS。
## Redis、安全限制与批量查询
在线应用依赖 Redis 8.10.2,使用 Spring Data Redis/Lettuce。配置 `REDIS_HOST`、`REDIS_PORT`(6379)、`REDIS_USERNAME`(可选)、`REDIS_PASSWORD`、`REDIS_DATABASE`(0)、`REDIS_SSL_ENABLED`(false);连接/命令超时默认 2s/1s。prod 必须显式提供 Redis 主机、密码及 `GITEA_ORGANIZATION`,与数据库、Gitea 凭据一样只由环境注入。
环境 Key 前缀默认 `vibemake:test` / `vibemake:prod`,可用 `REDIS_KEY_PREFIX` 覆盖;后续自动追加 `api:v1:` / `admin:v1:`。会话 Key 使用 Token 的 SHA-256 摘要;会话 JSON 仅包含用户标识和会话版本。社区和后台 TTL 分别为 24h/8h,不滑动续期,验证码 2m 且一次消费。每次请求仍检查数据库账号状态、角色、会话版本。Redis 故障返回 503 `REDIS_UNAVAILABLE`,不回退本机或放行。离线导入和管理员初始化命令不检查 Redis。
全部默认限额、变量、ACL 与发布操作见 [部署说明](docs/admin-deployment.md#redis-安全与资源保护)。Fork 为每用户 10 次/分钟、URDF 批次签名 20 次/分钟;Fork 同时执行仍最多 2 个。请求频率统计的是尝试次数,包括繁忙或失败的调用,按首次请求建立 60 秒固定窗口;窗口内各操作独立,换 Token 或 IP 不重置用户额度。限流只计一次业务调用,AI 创建/Fork 共用业务入口。
项目响应采用数据库批量查询,不缓存业务列表。列表和 AI 检索不读取体积较大的 URDF 文件清单,Fork 来源仅批量读取标识和编码。按业务服务层统计(不包含安全过滤器独立账号查询),20 条带 Fork 来源、登录用户点赞和导入来源的项目列表最多 8 次 SQL,评论列表最多 4 次,后台用户列表最多 3 次;避免记录数增加造成逐条查询。昵称、互动和下架可见性仍读取当前数据。
普通 `AI_ENABLED=false OSS_ENABLED=false mvn verify` 使用只存在于 tests 分类制品中的状态存储,不依赖 Redis,生产 jar 不包含该实现。真实 Redis 联调不自动读取 `.env`,通过 `REDIS_TEST_HOST`、`REDIS_TEST_PORT`、`REDIS_TEST_USERNAME`、`REDIS_TEST_PASSWORD`、`REDIS_TEST_DATABASE`、`REDIS_TEST_SSL_ENABLED` 连接独立测试实例,执行 `bash scripts/test-redis.sh`;只使用随机测试 Key 前缀,不执行 FLUSHDB。真实联调验证 TTL、消费竞争、计数、断开后重建连接、会话撤销与账号禁用。
## HTTPS Git 网关
网站身份可通过项目独立凭据 clone、fetch、pull、push main,支持 LFS Basic Transfer;社区仍手动发布。默认关闭,普通用户无需 Gitea 账号。先执行 [Git 凭据建表 SQL](docs/database.md#项目-git-凭据) 和 [写入记录扩展 SQL](docs/admin-database.md#https-git-写入记录扩展),同时部署社区端和管理端兼容版本,再设置 `GIT_ENABLED=true`。应用不自动迁库,本次不修改 `.sql` 文件。
| 环境变量 | 默认值/含义 |
| --- | --- |
| GIT_ENABLED | false |
| GIT_PUBLIC_BASE_URL | 必填的固定公网 HTTPS 地址,例如 `https://git.example.com/git`,不根据 Host 构造 |
| GIT_UPSTREAM_USERNAME / GIT_UPSTREAM_TOKEN | 独立非管理员、非组织所有者技术账号及其 PAT;需要 read:user、write:repository 范围,与仓库管理 GITEA_TOKEN 分离 |
| GIT_REQUEST_TIMEOUT | 10m,覆盖请求及响应流 |
| GIT_MAX_PACK_BYTES / GIT_MAX_LFS_OBJECT_BYTES | 5368709120 / 1073741824 |
| GIT_MAX_METADATA_BYTES / GIT_MAX_BATCH_OBJECTS | 8388608 / 500 |
| GIT_READ_CONCURRENT / GIT_PUSH_CONCURRENT / GIT_LFS_CONCURRENT | 4 / 2 / 8,单实例 |
| GIT_REQUESTS_PER_MINUTE / GIT_LFS_REQUESTS_PER_MINUTE | 120 / 600,每用户 |
| GIT_AUTH_FAILURES_PER_MINUTE | 20,每IP;仅信任已配置代理 |
技术账号不能是仓库管理员;首次签发项目 Token 时后端管理凭据会给它授予该仓库 write 权限。首个读写 Token 初始化 main 保护,已有规则必须兼容;每次 push 重新核验,非快进和删除由 Gitea 接收钩子拒绝。仓库主存储、对象完整性和 LFS 保留在 Gitea。部署必须确保 Git/LFS 原生端点直接响应,无重定向、且上游 LFS action 使用配置的 Gitea origin 和本项目路径;不支持外部对象存储 action 直链。
代理 `/git/` 关闭请求/响应缓冲、缓存,透传 Authorization、Git-Protocol、Content-Type、Accept、Content-Encoding;请求大小允许 pack/LFS 额度,代理与 Gitea 超时至少覆盖10分钟预算,默认读取超时不低于660秒。服务端不得记录认证头或 action Bearer。使用 HTTPS 对外开放;本机真实联调才允许回环 HTTP。保持当前社区端、管理端各单实例部署范围。
前端对接见 [HTTPS Git 与本地开发](docs/vibemake-api.md#https-git-与本地开发),运维恢复与回滚见 [Git 网关运维](docs/admin-deployment.md#https-git-网关运维)。Git Token 继承现有网页登录身份边界:邮箱加图片验证码目前不验证邮箱归属。
验证:`AI_ENABLED=false VIBEMAKE_AI_ENABLED=false OSS_ENABLED=false mvn verify`。`python3 scripts/test-git-gateway.py` 读取 `.env`,在随机测试仓库及临时技术账号上运行真实 Git/Gitea/LFS(含大于50 MiB对象)闭环,测试完成后清理;需要 GITEA_TOKEN 具备创建/删除测试用户权限,以及可连接的 Redis(只使用随机 git-live 前缀)。配置 DB_URL 时还会创建随机 `vibemake_git_verify_*` 临时 MySQL 库,需建库权限;`GIT_GATEWAY_MYSQL=false` 可单独使用 H2 验证 Git/Redis。MySQL 锁测试只创建随机临时库,Redis 测试使用独立随机前缀,均不修改已有业务数据。
# community
1
-1292
View File
File diff suppressed because it is too large Load Diff
-281
View File
@@ -1,281 +0,0 @@
# 管理端数据库变更 SQL
以下 SQL 由维护人员手工执行,应用不会自动迁库。已有数据库执行下面的增量 SQL;新建数据库先执行 database.md 中的四表 SQL,然后只创建本文件的任务表,不重复执行 ALTER。
执行前暂停社区端、后台和导入工具的写入并备份数据库。不要对已有列重复执行。所有时间字段由应用写入上海时间(Asia/Shanghai,UTC+8)。项目来源改为从任务表读取,因此社区端、后台和导入工具升级前都应创建任务表,即使暂不启动后台也需要执行。
## 项目字段收敛
治理相关字段为 moderation_reason(管理员下架原因)和 repo_write_status(跨进程写入状态)。下架直接使用现有 publish_status=BLOCKED,不再增加独立治理状态。GitHub来源标识、地址、默认分支和许可证属于迁移任务,统一放在 project_import_task;第一版只支持GitHub,不存平台类型,也不额外区分用户创建与后台创建。
## 已有数据库增加 STEP 单文件字段
已有数据库手工执行以下 SQL,再升级社区端、管理端和导入工具;新建数据库的 `database.md` 已包含这三个字段,不要重复执行。应用不自动迁库,不新增上传批次表。
```sql
ALTER TABLE project
ADD COLUMN step_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT 'STEP文件环境相对路径,不含域名和环境根目录',
ADD COLUMN step_file_name VARCHAR(1024)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT 'STEP原始文件名,保留大小写中文和空格',
ADD COLUMN step_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT 'STEP文件大小,单位字节,未绑定时为零';
```
STEP 默认最大 500 MiB(524288000 字节),可通过管理端 `STEP_MAX_FILE_BYTES` 配置;调整时须同步前端限制和文案。签名有效期为 15 分钟,文件由浏览器直传 OSS,无需调整 API multipart 限制。对象路径为 `/project-resources/{projectCode}/step/{batchCode}/model{原始后缀}`,不包含环境根目录;原始文件名单独保存。未绑定时路径和文件名为 `''`,大小为 `0`,接口的三个 STEP 字段均为 `null`。
上传签名限定对象、精确大小、禁止覆盖和附件下载响应头;公开 URL 可直接下载,不提供额外下载接口。OSS 需允许管理端来源的 multipart POST,CDN 需透传 Content-Disposition。Fork 复制这三个字段并共享 OSS 对象。替换、移除或删除项目不物理删除对象,不影响其他副本。
STEP 与现有 URDF 使用相同的无状态确认方式:批次不落库,确认核验 OSS 对象及大小,项目锁内局部更新。重复确认会再次写入;签名过期后已上传对象仍可确认;并发以最后一次成功写入为准;替换或移除后重放旧请求可以重新绑定旧对象。不提供批次历史比对、严格幂等或旧批次防复活保证。旧版前端需求文档中的相关保证不适用于本期。
## 已有数据库增加四类项目资源字段
在已完成原有部署的数据库中手工执行以下 SQL,再升级社区端、管理端和导入工具。新建数据库的 `database.md` 建表语句已包含这些字段,不要重复执行。
```sql
ALTER TABLE project
ADD COLUMN model_glb_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '整机GLB环境相对路径,不含域名和环境根目录',
ADD COLUMN model_glb_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '整机GLB文件大小,单位字节',
ADD COLUMN model_parts_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '零件模型环境相对目录,以斜杠开头和结尾',
ADD COLUMN model_parts_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT '零件GLB文件清单,包含relativePath和sizeBytes',
ADD COLUMN assembly_json_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '拼装步骤JSON环境相对路径,不含域名和环境根目录',
ADD COLUMN assembly_json_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '拼装步骤JSON文件大小,单位字节',
ADD COLUMN walking_resources_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '行走资源环境相对目录,以斜杠开头和结尾',
ADD COLUMN walking_resources_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT '行走资源文件清单,包含relativePath和sizeBytes';
```
路径为未编码的 `/project-resources/{projectCode}/{resourceType}/{batchCode}/{relativePath}`,不含域名和环境根目录。目录字段以 `/` 结尾,清单内路径相对于对应目录。未绑定或清除后路径为 `''`、大小为 `0`、清单为 `[]`。
Fork 直接复制这八个字段并复用原 OSS 对象,因此副本保存的路径可以包含源项目编码。读取不校验路径属于当前项目;新上传和确认只能使用当前项目的目录。替换、清除和删除项目均保留 OSS 对象,避免破坏其他副本的引用。后续如增加资源清理任务,必须检查所有项目的共享引用。
## 已有数据库增加字段
```sql
ALTER TABLE sys_user ADD COLUMN role VARCHAR(16) NOT NULL DEFAULT 'USER' COMMENT '用户角色 USER普通用户 ADMIN管理员 OFFICIAL官方托管账号';
ALTER TABLE sys_user ADD COLUMN password_hash VARCHAR(100) NULL COMMENT '管理员BCrypt密码哈希,普通用户为空';
ALTER TABLE sys_user ADD COLUMN session_version BIGINT NOT NULL DEFAULT 0 COMMENT '登录会话版本,禁用或修改密码时递增';
ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架';
ALTER TABLE project ADD COLUMN moderation_reason VARCHAR(500) NULL COMMENT '管理员下架原因';
ALTER TABLE project ADD COLUMN repo_write_status VARCHAR(16) NOT NULL DEFAULT 'IDLE' COMMENT '仓库写入状态 IDLE空闲 WRITING写入中 REVIEW待核对';
```
## 新建迁移任务表
```sql
CREATE TABLE project_import_task (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部任务主键',
task_code CHAR(32) NOT NULL COMMENT '迁移任务业务编码',
project_code CHAR(32) NOT NULL COMMENT '目标项目业务编码',
operator_user_code CHAR(32) NOT NULL COMMENT '任务创建管理员用户编码',
source_repository_id BIGINT NOT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用',
source_repository_url VARCHAR(2048) NOT NULL COMMENT 'GitHub仓库规范公开地址',
source_default_branch VARCHAR(255) NOT NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验',
source_license VARCHAR(128) NULL COMMENT 'GitHub许可证标识,无法识别时为空',
status VARCHAR(16) NOT NULL DEFAULT 'QUEUED' COMMENT '任务状态 QUEUED排队 RUNNING执行 SUCCEEDED成功 FAILED失败 REVIEW待核对',
phase VARCHAR(32) NOT NULL DEFAULT 'QUEUED' COMMENT '迁移阶段 QUEUED CLEANING PRECHECK MIGRATING MIGRATED NORMALIZING BRANCH_READY LINKED',
receipt_json TEXT NULL COMMENT '已确认迁移完成收据JSON,仅内部使用,不包含认证凭据',
target_sha VARCHAR(64) NULL COMMENT '迁移后冻结的目标提交SHA',
error_code VARCHAR(64) NULL COMMENT '最近失败错误码',
warnings_json TEXT NOT NULL COMMENT '兼容性提醒JSON数组',
started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)',
finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_import_task_code (task_code),
UNIQUE KEY uk_import_project (project_code),
KEY idx_import_source (source_repository_id),
KEY idx_import_queue (status, created_at),
CONSTRAINT fk_import_project FOREIGN KEY (project_code) REFERENCES project(project_code),
CONSTRAINT fk_import_operator FOREIGN KEY (operator_user_code) REFERENCES sys_user(user_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='后台公开GitHub项目迁移任务';
```
没有管理员账号表、管理员会话表、审计表或仓库状态表。第一位管理员使用初始化命令设置,禁止手写明文密码入库。后续手工修改角色时必须同时递增 session_version,且 ADMIN 必须具有通过 BCrypt 编码的密码。官方托管账号由后台首次创建或迁移项目时自动建立,保留邮箱为 vibemake-official@internal.invalid。
REVIEW 或遗留 WRITING 不应直接改为 IDLE:先核对 Gitea 写入、迁移收据、LFS 完成情况、仓库身份及提交。已持久化成功收据时提供只读核对后的续跑;明确 GITEA_MIGRATION_REJECTED 的任务允许通过 retry 进入 CLEANING,核验并清理归属于该任务的失败仓库后重迁。清理身份使用现有 project.gitea_repo_id 保存,保留原任务与项目,不新增字段或表。已有 phase 为 VARCHAR,无需因新增 CLEANING 阶段执行数据库变更。不提供强制成功操作。
迁移响应丢失、没有成功收据的 REVIEW 任务,管理员点击 retry 后进入 VERIFYING,核验通过才在同一事务保存恢复收据、仓库身份和冻结提交,接续原任务。核验不通过继续 REVIEW,不删除仓库、不重新迁移。VERIFYING 沿用现有 phase 的 VARCHAR 字段,本次恢复能力不需要新增表或字段,也无需手工修改任务状态。
## 已经执行过上一版管理端 SQL 的数据库
本节只供已经存在旧字段/旧任务表的数据库手工升级;尚未执行旧版 SQL 的数据库不要执行本节。先暂停写入并备份,不自动删除旧字段。
```sql
ALTER TABLE project_import_task ADD COLUMN source_repository_id BIGINT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用';
ALTER TABLE project_import_task ADD COLUMN source_repository_url VARCHAR(2048) NULL COMMENT 'GitHub仓库规范公开地址';
ALTER TABLE project_import_task ADD COLUMN source_default_branch VARCHAR(255) NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验';
ALTER TABLE project_import_task ADD COLUMN source_license VARCHAR(128) NULL COMMENT 'GitHub许可证标识,无法识别时为空';
UPDATE project_import_task t JOIN project p ON p.project_code = t.project_code
SET t.source_repository_id = p.external_repository_id,
t.source_repository_url = p.external_repository_url,
t.source_default_branch = p.external_default_branch,
t.source_license = p.external_license;
-- 检查结果必须为空,才能把三个必需来源字段设为 NOT NULL。
SELECT task_code, project_code FROM project_import_task
WHERE source_repository_id IS NULL OR source_repository_url IS NULL OR source_default_branch IS NULL;
ALTER TABLE project_import_task MODIFY COLUMN source_repository_id BIGINT NOT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用';
ALTER TABLE project_import_task MODIFY COLUMN source_repository_url VARCHAR(2048) NOT NULL COMMENT 'GitHub仓库规范公开地址';
ALTER TABLE project_import_task MODIFY COLUMN source_default_branch VARCHAR(255) NOT NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验';
ALTER TABLE project_import_task ADD KEY idx_import_source (source_repository_id);
UPDATE project SET publish_status = 'BLOCKED' WHERE moderation_status = 'BLOCKED' AND deleted = 0;
ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架';
```
旧版七个字段及其索引可以暂留,代码已不再读写;确认备份及来源回填完成后再清理。特别是只有旧 Excel 批次、没有后台任务的历史项目,其来源需保留原批次清单或另行归档,不能直接删除唯一来源信息。本次不对实际数据库执行增删字段操作。
## 允许已删除项目的 GitHub 来源再次迁移(本次上线前执行)
仅供已经存在 `uk_import_source` 唯一索引的数据库执行。暂停后台创建迁移任务并备份后,在业务库中手工执行以下 SQL;新建任务表已使用普通索引,无需执行本节。应用不会修改实际表结构。
```sql
ALTER TABLE project_import_task
DROP INDEX uk_import_source,
ADD KEY idx_import_source (source_repository_id);
```
来源标识保留在每条历史任务中,仍通过项目编码关联各自的项目。新版按 GitHub 稳定来源加锁,只对未删除项目去重;已删除项目可用新项目编码、新任务和新仓库再次迁移。旧项目、任务和仓库均保留,不会被覆盖或自动清理;管理员项目列表和详情仍不展示已删除项目。字段与中文注释保持不变。
部署时必须先完成上述索引调整,再更新所有管理端实例;旧索引会继续阻止创建第二条来源任务。允许重复来源后不能直接恢复全局唯一索引,回滚前须核对同一来源的历史任务记录。
## 新建普通文件写入操作记录表(本次上线前执行)
只新增此表,不需要修改项目表。由运维手工执行;应用不自动迁库。时间全部为上海时间(Asia/Shanghai,UTC+8)。
```sql
CREATE TABLE repository_write_operation (
operation_code CHAR(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '写入操作业务编码,同时作为幂等键',
operation_kind VARCHAR(16) NOT NULL DEFAULT 'WEB_COMMIT' COMMENT '操作类型 WEB_COMMIT网页提交 GIT_PUSH本地推送',
target_commit_sha VARCHAR(64) NULL COMMENT 'Git推送请求的目标提交SHA,网页提交可为空',
actor_user_code VARCHAR(32) NULL COMMENT '实际发起推送的网站用户业务编码',
git_token_code CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NULL COMMENT '本次推送使用的Git凭据业务编码,不保存明文',
project_code CHAR(32) NOT NULL COMMENT '项目业务编码',
repository_id BIGINT NOT NULL COMMENT '操作发起时Gitea仓库内部标识,仅核验使用',
repository_owner VARCHAR(255) NOT NULL COMMENT '操作发起时仓库所属账号',
repository_name VARCHAR(255) NOT NULL COMMENT '操作发起时仓库名称',
base_commit_sha VARCHAR(64) NOT NULL COMMENT '本次写入的基准提交SHA',
request_digest CHAR(64) NOT NULL COMMENT '请求内容SHA256摘要,不保存文件正文',
commit_message VARCHAR(1000) NOT NULL COMMENT '原始提交说明,不包含系统凭据尾注',
status VARCHAR(16) NOT NULL COMMENT '操作状态 PROCESSING处理中 NEEDS_REVIEW超时待确认 SUCCEEDED已成功 FAILED明确失败',
result_commit_sha VARCHAR(64) NULL COMMENT '确认成功的提交SHA',
failure_status INT NULL COMMENT '明确失败时原HTTP状态码',
last_error_code VARCHAR(64) NULL COMMENT '最近核对错误编码,不保存异常正文或凭证',
check_count INT NOT NULL DEFAULT 0 COMMENT '后台已执行核对次数',
next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)',
PRIMARY KEY (operation_code),
KEY idx_write_project_status (project_code, status, created_at),
KEY idx_write_next_check (status, next_check_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='普通文件写入幂等凭据及自动核对记录';
```
已完成的操作记录仍用于幂等重放,不要在客户端可能重试期间删除。历史 REVIEW 没有操作记录,不会凭最新 SHA 自动判成功;需核对实际结果后按原维护流程处理。迁移、Fork 继续使用原流程。
## 业务时间由 UTC 迁移到上海时间
新版统一通过 `ProjectSupport` 生成上海时间(`Asia/Shanghai`),字段类型保持 `DATETIME(3)`。以下 SQL 由维护人员手工执行,应用不会执行迁移,也不会自动修改已有数据库。
执行顺序:暂停社区端、管理端和导入工具,备份业务数据库及导入状态目录;确认以下六张表中的历史时间仍全部为 UTC 后执行一次转换;核对结果后同时部署新版各模块,并同步前端的 `+08:00` 解析方式,再恢复服务。新建空库无需执行数据转换。若已经写入上海时间或存在混合时区数据,必须先按切换记录确定待转换数据范围,不能直接执行以下全表更新;本脚本不能重复执行。
```sql
USE vibemake;
START TRANSACTION;
UPDATE sys_user
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR);
UPDATE project
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
published_at = DATE_ADD(published_at, INTERVAL 8 HOUR);
UPDATE project_comment
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR);
UPDATE project_like
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR);
UPDATE project_import_task
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
started_at = DATE_ADD(started_at, INTERVAL 8 HOUR),
finished_at = DATE_ADD(finished_at, INTERVAL 8 HOUR);
UPDATE repository_write_operation
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
next_check_at = DATE_ADD(next_check_at, INTERVAL 8 HOUR);
COMMIT;
```
空值保持为空,毫秒精度保持不变。`next_check_at` 等调度时间也需要转换,避免切换后提前或延后核对任务。Git 提交日期、OSS 签名内容和 Gitea 内部数据库不参与转换。
已有数据库的时间字段注释可单独按以下 SQL 更新;DDL 会隐式提交,不要放入上面的数据转换事务。
```sql
ALTER TABLE sys_user
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)';
ALTER TABLE project
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
MODIFY COLUMN published_at DATETIME(3) NULL COMMENT '最近发布时间(Asia/Shanghai)';
ALTER TABLE project_comment
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)';
ALTER TABLE project_like
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '点赞时间(Asia/Shanghai)';
ALTER TABLE project_import_task
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
MODIFY COLUMN started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)',
MODIFY COLUMN finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)';
ALTER TABLE repository_write_operation
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)',
MODIFY COLUMN next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)';
```
旧导入状态首次由新版读取时,将未声明时区的 `reservedAt` 从 UTC 转为上海时间,原子保存并标记 `timeZone=Asia/Shanghai`,后续不会再次转换。应在业务库完成转换后再续跑;未迁移的数据库时间与清单不一致时,现有归属校验会阻止接管项目。回滚应用前需要同时恢复数据库和导入状态备份,并恢复前端的旧时间解析约定。
## HTTPS Git 写入记录扩展
已有 `repository_write_operation` 表手工执行下列 SQL;新库使用上方完整建表语句,不重复执行 ALTER。先升级社区端和管理端兼容代码,再开启 Git 网关。既有记录默认归类为 WEB_COMMIT;Git 推送不使用网页提交尾注核对。
```sql
ALTER TABLE repository_write_operation
ADD COLUMN operation_kind VARCHAR(16) NOT NULL DEFAULT 'WEB_COMMIT' COMMENT '操作类型 WEB_COMMIT网页提交 GIT_PUSH本地推送',
ADD COLUMN target_commit_sha VARCHAR(64) NULL COMMENT 'Git推送请求的目标提交SHA,网页提交可为空',
ADD COLUMN actor_user_code VARCHAR(32) NULL COMMENT '实际发起推送的网站用户业务编码',
ADD COLUMN git_token_code CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NULL COMMENT '本次推送使用的Git凭据业务编码,不保存明文';
```
README 外链图片转存沿用 `phase` 的 VARCHAR 字段,增加 `README_IMAGES` 阶段,无需修改表结构。`receipt_json` 在原仓库收据上追加可选 `readmeImages` 进度,包含处理基准、分支、操作编码、内容摘要和结果 SHA;兼容缺少该字段的历史收据,不保存图片、README 正文或认证凭据。`target_sha` 始终保留 GitHub 原始迁移 SHA,图片提交 SHA 单独记录,续跑不能按原 SHA 再次归一化已处理的 main。
-231
View File
@@ -1,231 +0,0 @@
# Vibemake 管理端部署与运维
管理端为独立 Spring Boot 应用 `vibemake-adminapi`,默认端口 8994,接口前缀 `/admin-api`。项目文件复用现有 Gitea 私有组织仓库,封面、URDF 及四类模型/行走资源复用 OSS;不需要新建 Gitea 账号或组织。前端对接见 [管理后台接口文档](admin-api.md)。
## 部署与初始化
1. 备份数据库、暂停写入、排空旧进程。已有数据库手工执行 [增量 SQL](admin-database.md),新数据库先执行 [基础四表 SQL](database.md),再创建迁移任务表和普通文件写入操作记录表。应用不自动执行 SQL。社区端也会读取这两张表,因此暂不启用管理端时仍需创建。
2. 更新社区端、管理端和 Excel 导入工具,确保全部写入端使用数据库共享锁。
3. 在 `.env` 或部署环境中提供现有 `DB_*`、`GITEA_*`、`OSS_*`;后台默认关闭 AI,OSS 也需显式启用。另需提供 `REDIS_*` 连接变量,默认环境为 `test`,正式部署显式设置 `SPRING_PROFILES_ACTIVE=prod`。真实 `.env` 不提交,不用示例覆盖已有凭据。
4. 选择一个已有、正常的普通用户,执行初始化命令,交互输入两次管理员密码。密码至少 12 字符、UTF-8 最多 72 字节,不会写入命令参数或日志。该命令只初始化 USER,不用于重置已有管理员密码;成功后进程退出。
5. 正常启动管理端,配置前端代理或后台跨域来源。两个应用仍分别单实例运行;共享会话不代表导入恢复和 AI/Fork 并发模型已支持多实例。
```bash
bash scripts/run-admin-local.sh --bootstrap-admin-user-code='<已有用户编码>'
bash scripts/run-admin-local.sh
```
如仅初始化管理员、当前没有 OSS 凭据,可以传 `--vibemake.oss.enabled=false`。直接运行 jar 时不会自动读取 `.env`,必须先在部署环境提供连接变量。本地脚本以 ADMIN_SERVER_PORT 设置后台端口,避免共用 `.env` 中的社区 SERVER_PORT 覆盖;直接部署时也应避免传入社区端的 SERVER_PORT。
```bash
SPRING_PROFILES_ACTIVE=prod java -jar vibemake-adminapi/target/vibemake-adminapi-0.0.1-SNAPSHOT.jar
```
| 配置 | 默认值/说明 |
| --- | --- |
| `ADMIN_SERVER_PORT` | 8994;独立于社区端 `SERVER_PORT` |
| `ADMIN_ALLOWED_ORIGINS` | 空;完整前端来源用英文逗号分隔,不使用通配符 |
| `PROJECT_RESOURCE_SIGNATURE_VALIDITY` | 1h;整机、零件、拼装 JSON、行走资源直传签名有效期 |
| `ADMIN_IMPORT_WORKER_ENABLED` | true;维护期间可关闭消费 |
| `ADMIN_IMPORT_CONCURRENCY` | 2,范围 1~4 |
| `ADMIN_MIGRATION_TIMEOUT` | 30m,仅迁移请求使用,普通 Gitea 超时不变 |
| `GITHUB_TOKEN` | 可选,只访问 GitHub 元数据 API,不能填写 Gitea Token |
| `vibemake.token-ttl` | 后台默认 8h,可通过 Spring 配置覆盖 |
日志为 `vibemake-adminapi.log` 和 `vibemake-adminapi-error.log`,沿用 requestId、归档和脱敏规范。写操作记录实际操作用户编码、目标编码、接口动作、HTTP 结果和耗时;关键项目与迁移步骤另有业务日志。
## 账号与权限
复用 sys_user:USER 普通用户、ADMIN 管理员、OFFICIAL 官方托管账号。后台必须同时验证邮箱、密码、正常状态和 ADMIN 角色。管理员及官方账号不允许通过社区无密码入口登录,两个应用的 Redis Key 域隔离、Token 不互通。应用重启后保留未过期会话。
每次请求检查角色、状态和会话版本。禁用、修改密码或手工变更角色并递增 session_version 后,旧 Token 失效;恢复状态不会恢复旧会话。第一版无角色修改接口。
连续登录失败按账号 5 次、来源地址 30 次限速,15 分钟后重试;只使用连接来源地址,不信任任意客户端提交的转发 IP 头。
项目不指定归属用户时,自动创建或复用官方账号,保留邮箱 `vibemake-official@internal.invalid`。该地址在账号建立前也禁止社区登录。若已有账号的角色或状态异常,停止创建并人工核对,不接管普通用户。
## 仓库写入与迁移
project 表只新增 moderation_reason 和 repo_write_status,来源标识、地址、默认分支和许可证保存在 project_import_task。成功迁移任务用于项目来源展示与去重,不能按普通日志过期删除。Excel 运维导入仍通过原批次清单保留来源,不伪造后台任务。
全部写入端按项目编码取得同一 MySQL 命名锁,使用固定连接取得、持有和释放,支持内部重入。锁连接池每应用最多 8 个连接,另有普通业务连接池,需要预留数据库容量。远端请求期间不持有数据库长事务;写入前持久化状态,结果不明时重启后仍阻断写入。
普通文件上传和编辑使用 repository_write_operation 持久化幂等凭据。正常为 `IDLE → WRITING → IDLE`;响应丢失先尝试只读匹配凭据,匹配成功仍返回 200。未知结果持久化 REVIEW,保持原有错误响应,由后台每 15 秒核对,10 分钟后改为每分钟继续核对。核对成功自动恢复 IDLE,不自动发布。提交前或发布前的 Gitea 读取失败保持 IDLE,不能误标为未知写入。操作编码由后端自动生成,前端不需要改造。
上线前确认目标 Gitea 已开启迁移、HTTP Git、LFS,技术账号具有组织仓库写权限。GitHub 预检优先读取 API;受限时严格核对公开网页身份、可见性和默认分支,无法确认时失败。网页回退拿不到的简介、许可证可能为空,需要管理员检查原仓库文件。
失败迁移重试需要技术账号及 Token 具有目标私有仓库读取、迁移创建及删除权限。后台迁移时在 Gitea 仓库描述中写入任务归属标识;不要手工修改该标识。它仅用于失败仓库清理核验,不改变社区项目的名称和描述。
迁移成功收据先持久化,再处理分支、关联和就绪状态。迁移保留 Git 历史、分支、标签并请求迁移 LFS;不导入 Issue、PR、Wiki、Release 附件,不递归复制子模块或外链。原默认分支不是 main 时补建 main;已有 main 与源默认分支内容不同则停止,不覆盖。
迁移表单支持预上传封面及 URDF。URDF 使用现有 OSS 配置与限额,创建任务前检查对象,并使用 project 既有 URDF 字段保存,不需要新增数据库变更。上传后未提交表单的 OSS 对象不会自动清理,沿用现有资源生命周期。
整机 GLB、零件 GLB 文件夹、拼装 JSON 和行走资源在项目 READY 后通过项目资源接口上传。升级前先手工执行 [八字段增量 SQL](admin-database.md#已有数据库增加四类项目资源字段)。RAM 用户需拥有当前环境 `project-resources/*` 的 `oss:PutObject`、`oss:GetObject` 权限,配置公开读取/CDN 及真实前端 Origin 的 POST、GET、HEAD CORS。新资源签名和确认清单不设置应用正文配额,反向代理须允许实际清单大小;文件内容由浏览器直接上传 OSS。Fork 对这四类资源只继承数据库引用,不调用 OSS;旧对象保留,后续任何清理机制均需检查共享引用。
STEP 上线前还需手工执行 [STEP 三字段增量 SQL](admin-database.md#已有数据库增加-step-单文件字段),然后更新社区端、管理端及导入进程。无需新增批次表。管理端 `STEP_MAX_FILE_BYTES` 默认 `524288000`(500 MiB),前端大小限制和文案须一致;URDF 限制和 API multipart 配额不变。沿用当前环境 `project-resources/*` 的 OSS 读写权限和公开读取配置,浏览器 POST 需允许管理端实际 Origin,CDN 需透传 Content-Disposition 附件下载响应头。
测试环境验收:签名 → 真实 OSS 上传 → 确认绑定 → 普通链接下载,检查中文文件名、500 MiB 边界、替换及重复移除;确认 Git SHA、发布状态和 URDF 不变。回滚应用时保留 STEP 列和对象。无状态确认不提供旧批次防复活保证。
## 异常核对
- 超时、进程在 MIGRATING 阶段中断或远端结果不明确时进入 REVIEW。禁止自动重发,也不能仅凭仓库存在判定成功。
- Gitea 明确返回 GITEA_MIGRATION_REJECTED 时显示 FAILED,提供重试。原有同错误的 REVIEW 任务也可申请重试;后台持有项目共享锁,在 CLEANING 阶段核验任务标识、组织、名称、来源及已记录的仓库 ID,清理后确认不存在再迁移。没有残留仓库时直接继续,不删除项目记录或 OSS 资源。
- 清理操作写入前持久化 CLEANING 阶段及仓库身份;删除超时或数据库回写失败时保持阻断,下次重试先核验是否已删除再继续。仓库已替换、来源不符、缺少任务归属标识时不删除;旧任务的无标识残留仓库仍需人工核对。已就绪、发布过的项目及已有成功收据的迁移不会走删除重迁流程。
- 人工核对后已删除目标仓库的任务,可在原任务页刷新并重试,无需修改状态或清空仓库 ID。后台重新确认仓库不存在后才清除旧仓库关联和写入阻断,保留原项目与资源继续迁移;再次点击不能绕过仍存在仓库的身份校验。
- REMOTE_RESULT_UNKNOWN 需要按 requestId、项目编码、任务编码核对日志和 Gitea,不应删除目标仓库后直接重跑。
- MIGRATING 阶段缺少成功收据、项目仍未就绪且未发布/删除的 REVIEW 任务,可通过原 retry 接口排队进入 VERIFYING。后台核验任务标识、来源稳定身份、目标组织和名称、私有非镜像属性、非空状态、两次读取的仓库身份及来源分支提交;核验通过后在同一事务保存仓库关联标识、恢复收据和冻结 SHA,再继续原有分支适配与关联流程。不删除、不重新迁移、不自动发布;任何核验失败都保持 REVIEW,原项目资源保留。
- 完成判断针对当前 Gitea 1.26.4 原生 `service=git` 非镜像迁移:初建库的 `empty=true`,Git/LFS 导入成功后才持久化非空状态。参见 [Gitea 原生迁移实现](https://github.com/go-gitea/gitea/blob/v1.26.4/services/repository/migrate.go#L121-L163) 与 [迁移收尾实现](https://github.com/go-gitea/gitea/blob/v1.26.4/services/repository/migrate.go#L218-L265)。缺少 empty 布尔属性的响应直接拒绝核验,不能使用 JSON 缺省值推断完成;升级 Gitea 或改用其他迁移方式前须重新验证该约定。
- VERIFYING 由管理员点击触发,沿用现有任务消费者;没有自动扫描 REVIEW 的定时恢复任务。核验期间服务重启后仍进入 REVIEW,可再次点击核验。仓库未完成可稍后再核验,标识/来源/仓库身份不匹配时由维护人员先核对;禁止手工把 REVIEW 改成成功。
- 已持久化成功收据且停在 MIGRATED 的任务,retry 会只读验证仓库身份、来源等后续跑。
- 停在 NORMALIZING/BRANCH_READY 且有冻结目标 SHA 的任务,retry 会核对已适配分支和收据后续跑;验证不通过继续阻断。
- 无强制成功、直接清除未知写入状态、任务取消接口。不能直接把 REVIEW 改成成功。
- 迁移成功不自动发布,先在 test 验证单个仓库及人工发布,再开放生产入口。
- 停用后台先关闭任务消费、排空正在执行的任务,再停止应用。不要在后台或 Excel 导入仍写入时回退社区端到旧写入逻辑。
逻辑删除、撤回和下架不会物理删除 Gitea 仓库或 OSS 对象;已公开 OSS 链接沿用现有生命周期。
### 普通项目后台自动核对
上线顺序:手工执行 [操作表 SQL](admin-database.md#新建普通文件写入操作记录表本次上线前执行) → 排空旧写入进程 → 同时升级社区 API 与管理 API。接口沿用原有请求及成功/错误响应,不新增 202、前端结果查询或在线恢复接口。前端不需要接入新协议。
后台任务在两个 API 应用中默认启动,由数据库项目命名锁避免重复核对;在独立线程执行,避免阻塞迁移任务调度。`vibemake.repository-write.worker-enabled=false` 可停用本实例的核对消费,但必须至少保留一个启用的实例。操作记录在远端写入前落盘,进程重启后按 next_check_at 继续;结果未知只查不重发。每次扫描 main 可达的最近至多 1000 个提交,精确校验操作尾注、请求摘要、唯一父提交及仓库身份;超范围、读取失败或不匹配均保留未知,不自动判失败。
前 10 分钟每 15 秒核对,超过 10 分钟改为每分钟继续核对,不强制解除保护。使用 projectCode、operationCode、baseCommitSha、commitSha、checkCount、errorCode 关联日志;原始请求正文和认证信息不进入操作表。操作状态 PROCESSING 为处理中,NEEDS_REVIEW 为超过 10 分钟仍未确认,SUCCEEDED 为确认成功,FAILED 为明确拒绝。操作终态与 IDLE 在同一事务确认;其他实例下次取得共享锁时按数据库结果清除旧内存标记,无需重启。
上传或编辑超时后如果立即查到凭据,原接口直接返回 200;暂时不能确认时仍返回原错误,不会把本次上传显示为成功。后台确认后自动恢复写入,管理员刷新工作区后即可继续。未确认期间禁止新的远端写入,重试不自动重发 Gitea POST。恢复不会自动发布。
历史 REVIEW/遗留 WRITING 没有操作记录时不做自动猜测,仍需核对仓库身份、文件、历史和上次操作是否已结束,再按原维护流程处理。迁移和 Fork 继续使用原专门核验流程。本阶段暂不提供管理员在线恢复入口。
## 验证
```bash
AI_ENABLED=false OSS_ENABLED=false mvn clean verify
bash scripts/test-admin-mysql.sh
```
普通测试使用 H2 和模拟 GitHub/Gitea/OSS,不访问现有业务库或真实仓库。真实 MySQL 测试使用 `.env` 的 DB_* 或 ADMIN_MYSQL_TEST_* 连接配置,只创建/删除随机 `vibemake_admin_verify_*` 临时库;需要创建临时库权限。验证跨实例互斥、重入、持久化阻断、断开持锁连接及新进程恢复,不对已有业务库执行 DDL。
## Redis 安全与资源保护
本版本采用 Redis 8.10.2 单节点直连,两个在线应用各单实例。首次部署时停止并排空旧进程再替换,新旧会话存储不混用;旧本机会话和验证码不会迁移,需重新登录一次。应用重启可保留 Redis 中未过期的会话,Redis 自身重启能否保留取决于服务器持久化配置。回退旧版本需要重新登录,不执行 Redis 全库清理,遗留 Key 按 TTL 过期。本次无数据库迁移。
### 连接与隔离
| 环境变量 | 默认值与用途 |
| --- | --- |
| REDIS_HOST / REDIS_PORT | test 为 localhost / 6379;prod 主机必须显式配置 |
| REDIS_USERNAME / REDIS_PASSWORD | 用户名可选;prod 密码必须显式配置,不将凭据放进连接 URL |
| REDIS_DATABASE | 0,两个应用可使用同一逻辑库 |
| REDIS_SSL_ENABLED | false;启用时使用 JVM 信任库验证服务端证书,不关闭证书验证 |
| REDIS_CONNECT_TIMEOUT / REDIS_TIMEOUT | 2s / 1s |
| REDIS_KEY_PREFIX | test 为 vibemake:test,prod 为 vibemake:prod;随后追加 api:v1: 或 admin:v1: |
| TRUSTED_PROXY_CIDRS | 空,默认不信任转发头;实际反向代理 IP/CIDR 用逗号分隔 |
相同环境的应用重启必须沿用相同前缀;不同环境使用不同前缀和凭据范围。配置可信代理后,从连接来源开始由右向左剥离可信代理链,使用首个不可信地址限流;不信任任意客户端提交的 X-Forwarded-For。后端入口应只允许部署代理访问,代理需覆盖或正确追加转发链。不要同时在容器层无条件改写 remoteAddr,否则会绕过应用对代理来源的判断。
在线启动探测 SET NX PX、GET、GETDEL、计数 Lua、TTL 和 DEL;拒绝权限不足或连接异常的启动。运行期间 Redis 故障返回 503 REDIS_UNAVAILABLE,不回退本机或放行。离线导入和 bootstrap-admin-user-code 命令不执行 Redis 探测。
### 权限与运行配置
为应用配置仅能访问自己环境前缀的 Redis ACL 用户。业务命令为 GET、SET、GETDEL、DEL、TTL、INCR、PEXPIRE、PTTL、EVAL、EVALSHA;Lettuce 连接还需 AUTH/HELLO、PING、SELECT(非零逻辑库)、CLIENT SETNAME/SETINFO。按服务端 ACL 语法授予这些命令和对应 `~vibemake:prod:api:v1:*` / `~vibemake:prod:admin:v1:*` Key 范围,或为两端共用账号授权两段范围。无需 FLUSHDB、FLUSHALL、KEYS、CONFIG、ACL 或通用管理权限。集成测试的随机测试前缀额外需要 SCAN,生产应用不执行扫描。
Redis 只监听内网或回环地址,启用认证;跨不可信网络使用 TLS。容量监控包括 used_memory、拒绝写入、evicted_keys、连接错误和延迟。安全状态应有独立容量保障,推荐专用实例使用 noeviction 和合适的 maxmemory,避免普通缓存淘汰会话或限流计数;noeviction 内存耗尽时写入失败,应用返回 503,需容量告警。持久化按业务要求配置并验证重启恢复,不能把会话当作可随意淘汰的普通缓存。应用不会自动修改既有 Redis 全局配置。
### 频率与大小配置
固定窗口从该主体第一次调用时开始,持续 60 秒;按请求尝试计数,繁忙和失败也计入,窗口内不会因再次调用滑动延长。用户操作在业务入口限流,覆盖 AI 和 HTTP;管理员按操作管理员身份计数。各行独立,文件提交/上传以及点赞/取消点赞各自共享所在行额度。
| 环境变量 | 默认次数/分钟 | 主体 |
| --- | --- | --- |
| RATE_CAPTCHA_PER_MINUTE | 20 | IP |
| RATE_LOGIN_IP_PER_MINUTE | 20 | IP |
| RATE_LOGIN_ACCOUNT_PER_MINUTE | 10 | 规范化邮箱 |
| RATE_ADMIN_LOGIN_PER_MINUTE | 30 | IP,另保留失败次数限制 |
| RATE_VIBEMAKE_READ_PER_MINUTE | 120 | IP |
| RATE_FILE_READ_PER_MINUTE | 60 | IP |
| RATE_CREATE_PER_MINUTE | 5 | 用户/操作管理员 |
| RATE_FORK_PER_MINUTE | 10 | 用户/操作管理员 |
| RATE_FILE_WRITE_PER_MINUTE | 10 | 用户/操作管理员 |
| RATE_COVER_SIGN_PER_MINUTE | 30 | 用户/操作管理员 |
| RATE_URDF_SIGN_PER_MINUTE | 20 | 用户/操作管理员 |
| RATE_COMMENT_PER_MINUTE | 10 | 用户 |
| RATE_LIKE_PER_MINUTE | 60 | 用户 |
超限为 429 RATE_LIMITED,保留 AI_RATE_LIMITED、AI_BUSY、FORK_BUSY、ADMIN_LOGIN_LIMITED 等现有代码。普通限流响应带 Retry-After(秒),其响应体 data.retryAfterSeconds 同步提供剩余等待时间。后台失败限制维持账号 5 次/IP 30 次,失败记录在最后一次失败后 15 分钟过期;成功仅清理对应账号失败次数。应用仅聚合记录同一规则的限流日志,不记录邮箱或 Token。
| 配置 | 默认值 |
| --- | --- |
| HTTP_JSON_MAX_BYTES | 262144,普通 JSON 256 KiB |
| HTTP_URDF_JSON_MAX_BYTES | 2097152,URDF 清单 2 MiB |
| HTTP_COMMIT_JSON_MAX_BYTES | 67108864,提交 JSON 64 MiB |
| FILE_MAX_CONCURRENT | 4,单实例文件读取/目录/历史/提交/multipart 处理名额 |
| FILE_DOWNLOAD_MAX_BYTES | 1073741824,单文件流式下载上限 1 GiB,社区端和管理端均配置 |
| FILE_DOWNLOAD_TIMEOUT | 5m,获取 SHA、文件元数据、等待上游响应及读取响应体的总预算 |
| FORK_MAX_CONCURRENT | 2,保持独立 Fork 执行名额 |
JSON 上限为实际线上请求字节数,包含转义和结构开销;业务文本/总内容上限继续保留。Content-Length 和 chunked 均流式核验,超限返回 413 REQUEST_TOO_LARGE。后台仓库上传不设独立单文件上限,文件合计最多 500 MiB、每批最多 500 个文件;`vibemake.repository-upload.max-file-bytes=0` 表示关闭独立单文件配额,`max-total-bytes=524288000` 为文件合计配额,与预览及文本提交配额独立。后台 `spring.servlet.multipart.max-file-size=-1`,整个请求最多 502 MiB(预留 2 MiB 表单开销),原有 UPLOAD_TOO_LARGE/FILE_TOO_LARGE 错误保留;部署反向代理时同步确保请求体上限不低于 502 MiB。后台项目及迁移 URDF 同样不设独立单文件上限、合计最多 500 MiB(后台 `vibemake.oss.urdf.max-file-bytes=0`、`max-total-bytes=524288000`),不沿用社区用户端的 URDF 大小环境变量;URDF 文件直传 OSS,不占用这类 multipart 名额。社区用户端上传默认仍为单文件 50 MiB、合计 200 MiB。文件名额不足为 429 FILE_BUSY,不排队;Fork 繁忙仍为 FORK_BUSY。
API 和管理端均显式配置 `server.tomcat.max-part-count=1003`,允许 500 个 files、500 个 paths 及 3 个公共字段。Tomcat 默认的 50 项无法承载业务允许的批量上传;数量超限会被 Spring 包装成上传大小异常,现区分为 413 `UPLOAD_TOO_MANY_PARTS` 并记录安全诊断日志。部署时若覆盖该配置,需要与业务批量文件数对齐。
JSON 预览继续使用 50 MiB 文件读取上限,contents JSON 上限按单文件 Base64 膨胀量加 2 MiB 元信息计算,其他元数据 8 MiB,错误响应 64 KiB。GET 超限返回 502 GITEA_RESPONSE_TOO_LARGE;写入响应无法完整确认仍为 REMOTE_RESULT_UNKNOWN,持久化阻断后续仓库写入,不自动重试。
三个端的 `files?download=true` 改为同步流式转发:使用 Gitea 1.26.4 的 `contents-ext`(不传 `includes`)只查元数据,元数据响应上限 64 KiB,再按同一 SHA 请求 `/raw/`,以 64 KiB 缓冲区写出。单文件下载独立使用上述 1 GiB / 5m 配置;`FILE_MAX_CONCURRENT` 名额持有到传输完成、失败或取消。元数据、Content-Length 和实际读取字节数均校验,大小超限为 `413 FILE_TOO_LARGE`,超时为 `504 FILE_DOWNLOAD_TIMEOUT`。JSON 预览、编辑、上传和归档配额不变。
部署单文件下载路径时关闭代理响应缓冲和缓存,代理读取/发送超时默认至少预留 **400 秒**,并与调整后的下载预算保持一致;前端请求超时也至少预留 400 秒。应用下载预算约束上游处理和读取,慢客户端写出还受代理及容器超时约束。发包后故障直接停止传输,HTTP 可能仍为 200;前端应丢弃取消或截断的文件,不自动重试。上线后使用原 `doc/mujoco.gif` 下载链接验证文件长度与内容摘要。
### 依赖安全核对(2026-10-22)
基线升级为 Boot 3.5.16、Security 6.5.11、Framework 6.2.19、Tomcat 10.1.61,保持 Java 21;Redis/Lettuce 由 Boot BOM 管理。以下为本次针对实际使用路径的公告核对,不等同于全量依赖扫描或账号安全问题已解决。
| 公告 | 条件与本项目处理 |
| --- | --- |
| CVE-2026-22732 | 安全响应头在特定写出路径缺失;Security 升至 6.5.11,超过该问题最低修复版 6.5.9,验证登录、下载及错误响应缓存头 |
| CVE-2026-22735 | SSE 非结构化文本且攻击者控制发给其他用户的内容;Framework 已超过最低修复版 6.2.17,应用也使用 JSON 结构化事件 |
| CVE-2026-24880 | 特定代理放过异常 HTTP/1.1 chunk 扩展时可请求走私;Tomcat 10.1.61 含修复,代理仍应严格校验请求 |
| CVE-2026-101356 | Tomcat 10.1.55~10.1.60 的 HTTP/2 异步请求/响应复用问题;显式锁定 10.1.61,避免使用 Boot BOM 默认的 10.1.55 |
| CVE-2026-47883 | UrlHandlerFilter 使用过宽匹配模式时的开放重定向;仓库未使用该 Filter,本次记录为条件风险,后续引入该组件前重新核对修复版本 |
依据:[Spring 响应头公告](https://spring.io/security/cve-2026-22732/)、[Spring SSE 公告](https://spring.io/security/cve-2026-22735/)、[Spring UrlHandlerFilter 公告](https://spring.io/security/cve-2026-47883/)、[Tomcat 公告](https://tomcat.apache.org/security-10.html)、[Boot 依赖版本](https://docs.spring.io/spring-boot/3.5/appendix/dependency-versions/coordinates.html)。普通用户邮箱冒名登录按本次范围保留,后续更换登录方式时单独处理。
生产两端必须配置同一个目标 GITEA_ORGANIZATION;prod 关闭 Swagger/OpenAPI,test 保留。AI、OSS 默认关闭并需显式启用;不增加数据库迁移。部署后验证 Redis 隔离、应用重启会话、禁用失效、限流、大小保护、Gitea 写入结果不明状态和公开 GET 行为,再开放流量。
### 验证记录与性能基准(2026-10-22)
已通过真实 Redis 8.10.2 的 TTL、原子消费、原子计数、域隔离、重建连接、撤销和账号禁用验证,以及真实 MySQL 的共享锁、重入、持久化阻断和持锁连接断开测试。全部数据库验证只创建/删除随机临时库,Redis 测试只使用随机前缀,未改动既有业务表或 Redis 全局配置。
基准使用改造前 HEAD 的独立源码副本与当前版本,固定 JDK 21、JVM 堆 128~512 MiB、21 个项目、20 个用户、20 条评论、20 条导入来源,每次读取 20 条,预热后每场景 100 次调用,前后按顺序运行。MySQL 使用两个独立随机临时库,测试结束删除。SQL 数为服务层物理 SELECT 数,不包含 HTTP 安全过滤器的账号校验。
| 数据库 | 版本 | 并发 | 每请求 SQL | P95 毫秒 | 堆池峰值之和 MiB |
| --- | --- | --- | --- | --- | --- |
| H2 | 改造前 | 1 | 122 | 15.918 | 109.12 |
| H2 | 改造前 | 4 | 122 | 24.732 | 108.41 |
| H2 | 改造后 | 1 | 8 | 8.023 | 109.50 |
| H2 | 改造后 | 4 | 8 | 15.511 | 111.23 |
| MySQL | 改造前 | 1 | 122 | 2448.059 | 109.59 |
| MySQL | 改造前 | 4 | 122 | 2414.935 | 109.68 |
| MySQL | 改造后 | 1 | 8 | 173.823 | 110.11 |
| MySQL | 改造后 | 4 | 8 | 221.998 | 87.36 |
项目 SQL 从 122 降到 8,评论列表从 23 降到 4,20 用户后台列表从 22 降到 3。MySQL 四并发 P95 从 2414.935ms 降到 221.998ms,约降低 91%。本地微基准受运行波动影响,不能将 SQL 数变化等同于所有环境的固定延迟收益。堆池峰值是各 heap memory pool 的峰值之和,并非进程 RSS;普通小请求的内存收益不稳定,本期内存保护主要针对超大正文、无界上游响应和大文件并发。
复测:`AI_ENABLED=false OSS_ENABLED=false mvn -pl vibemake-api -am -Dtest=QueryEfficiencyTest -Dsurefire.failIfNoSpecifiedTests=false '-DargLine=-Xms128m -Xmx512m' test`。默认使用 H2;显式设置 BENCHMARK_MYSQL_URL、BENCHMARK_MYSQL_USERNAME、BENCHMARK_MYSQL_PASSWORD 时,自动创建并最终删除 vibemake_benchmark_* 随机临时库,执行 DDL 前验证连接 catalog 必须等于本次随机库。账号需要创建和删除临时库权限,禁止将基准改为直接重置业务库。该小样本不代表正式环境容量,部署仍需结合真实项目体量验证。
## HTTPS Git 网关运维
仅社区 API 暴露 `/git/**`;管理端继续使用后台认证。按 [README 配置](../README.md#https-git-网关) 部署独立 Git 技术账号、HTTPS 地址与无缓冲代理。功能默认关闭;先人工执行 [Git Token 表](database.md#项目-git-凭据) 与 [operation_kind 等字段扩展](admin-database.md#https-git-写入记录扩展),再排空旧进程并升级两个 API,最后对测试项目验证后开放。不能让旧版后台核对器消费 GIT_PUSH 操作。
Git 技术账号须非 site admin、非组织所有者、非仓库管理员,PAT 只给 read:user、write:repository。首次 Token 签发会按项目给技术账号授予 write,不提升其已有 admin/owner 权限;权限不兼容必须先人工处理。已有 main 保护不覆盖,通配/多规则配置会保守拒绝开通;每次 push 复核。运维直接修改仓库引用或 main 保护前应停写,不能绕过网关并发控制。LFS action 以短期 Redis 状态承接,上游地址与认证头只保留服务端。Redis 丢失 action 后需重新请求 batch;原 Git 凭据存 MySQL,可撤销。
网页与本地写入使用同一 ProjectLocks 和 repo_write_status,跨进程由 MySQL 命名锁串行。操作记录必须在转发 receive-pack 前提交,operation_kind=GIT_PUSH 记录 base_commit_sha、target_commit_sha、actor_user_code、git_token_code,摘要不含 pack。HTTP200 不是成功证明;仅接受完整 report-status,成功后再次核对 main,并原子保存终态与 IDLE。推送作者来自本地提交,审计 actor_user_code 是网站发起者,两者可能不同。
后台核对按类型区分:WEB_COMMIT 继续查找原有尾注;GIT_PUSH 先校验项目/远端仓库身份、私有属性及 main,再仅在 main 精确等于 target_commit_sha 时确认成功。main 仍等于 base_commit_sha、为其他SHA、上游不可用或读取失败均保持 REVIEW,不能自动判失败。10分钟后状态为 NEEDS_REVIEW,每分钟继续只读核对,不重发 push。
人工恢复顺序:
1. 关闭 Git 入口、停止并排空社区/后台仓库写入和发布,暂停核对 worker,保留数据库和日志备份。
2. 根据 requestId、projectCode、operationCode、actor_user_code、git_token_code、旧新 SHA 关联网关与 Gitea 接收日志。先确认对应 receive-pack/钩子任务已经结束;单次旧 SHA 查询不能作为结束证明。
3. 核对仓库ID、owner/name、私有、非镜像、main 及对象可达性。精确目标SHA且验证完成可确认 SUCCEEDED;确认任务停止且 main 仍为旧 SHA、未发生引用变更时才可人工标记 FAILED。main 为其他 SHA 或身份变化继续待核对,不改历史、不重推。
4. 在维护事务中同步更新操作 status/result_commit_sha/last_error_code/updated_at 和项目 repo_write_status=IDLE;必须校验项目只有这一条待核对操作,不能解除其他操作的保护。留存审批/排查依据和恢复审计,不能只执行孤立的 IDLE 更新。
5. 重启恢复进程、恢复 worker,验证网页及本地正常写入后再开放 Git。不自动发布社区。
回滚先关闭 Git 功能并排空接收请求,核对处理中操作后再回退应用。旧版本不能消费未解决的 GIT_PUSH;未解决前保持维护停写。保留新增表/列/凭据/审计、仓库内容及 main 保护,不删对象或撤销保护。功能关闭后仍可在网站查询、撤销 Git Token。
-90
View File
File diff suppressed because one or more lines are too long
-93
View File
@@ -1,93 +0,0 @@
# CAD 工作空间建表 SQL
在启用 CAD 接口前,由运维在现有 `vibemake` 数据库手工执行以下 SQL(MySQL 8.0.13+)。应用不自动建表,不修改现有项目表。所有业务时间按上海时间写入。
`id` 和归属外键仅供服务内部使用,对外使用 `cad_project_code` 和 `upload_code`。CAD 可独立创建,也可通过 `workspace_project_code` 关联当前用户的工作区项目;关联不创建或修改 Git 仓库。上线顺序:执行 SQL → 部署后端 → 验证共用 OSS 配置及文件读取 → 开放前端入口。回滚代码时保留两张表和 OSS 对象。
```sql
CREATE TABLE cad_project (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对外返回',
cad_project_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT 'CAD项目唯一业务编码',
owner_user_id BIGINT NOT NULL COMMENT '所属用户内部主键,关联sys_user.id',
name VARCHAR(100) NOT NULL COMMENT 'CAD项目名称',
description VARCHAR(2000) NOT NULL DEFAULT '' COMMENT 'CAD项目描述',
cover_url VARCHAR(2048) NULL COMMENT 'CAD项目封面,平台OSS资源存无环境前缀的相对路径',
workspace_project_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NULL COMMENT '关联工作区项目业务编码,独立项目及已删除项目为空',
initial_step_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '初始STEP文件环境相对路径,不含域名和环境根目录',
initial_step_file_name VARCHAR(1024) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '初始STEP原始文件名',
initial_step_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '初始STEP文件大小,单位字节',
document_object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '' COMMENT '当前设计文件环境相对路径,以斜杠开头,不含域名和环境根目录',
file_name VARCHAR(255) NOT NULL DEFAULT '' COMMENT '当前原生设计文件名称',
size_bytes BIGINT NOT NULL DEFAULT 0 COMMENT '当前设计文件大小,单位字节',
version BIGINT NOT NULL DEFAULT 0 COMMENT '当前保存版本,空项目为0,每次成功保存递增',
saved_at DATETIME(3) NULL COMMENT '最近成功保存设计文件的上海时间',
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除标记,0未删除,1已删除',
created_at DATETIME(3) NOT NULL COMMENT '项目创建上海时间',
updated_at DATETIME(3) NOT NULL COMMENT '项目信息最近更新上海时间',
PRIMARY KEY (id),
UNIQUE KEY uk_cad_project_code (cad_project_code),
UNIQUE KEY uk_cad_workspace_project_code (workspace_project_code),
KEY idx_cad_project_owner_list (owner_user_id, deleted, updated_at, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='CAD个人工作空间项目';
CREATE TABLE cad_project_upload (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对外返回',
upload_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '上传批次唯一业务编码',
cad_project_id BIGINT NOT NULL COMMENT '所属CAD项目内部主键,关联cad_project.id',
expected_version BIGINT NOT NULL COMMENT '签发上传时的项目基础版本,用于并发保存校验',
object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '本批次设计文件环境相对路径,以斜杠开头,不含域名和环境根目录',
file_name VARCHAR(255) NOT NULL COMMENT '本批次原生设计文件名称',
size_bytes BIGINT NOT NULL COMMENT '本批次声明的文件大小,单位字节',
expires_at DATETIME(3) NOT NULL COMMENT '未确认批次的截止上海时间,与上传签名一致',
saved_version BIGINT NULL COMMENT '确认成功的版本号,空值表示尚未确认',
saved_at DATETIME(3) NULL COMMENT '首次确认成功上海时间,重复确认返回原值',
created_at DATETIME(3) NOT NULL COMMENT '批次创建上海时间',
updated_at DATETIME(3) NOT NULL COMMENT '批次最近更新上海时间',
PRIMARY KEY (id),
UNIQUE KEY uk_cad_upload_code (upload_code),
KEY idx_cad_upload_project (cad_project_id, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='CAD设计文件上传与保存确认批次';
```
保存事务锁定当前用户的未删除项目和对应批次,按 `expected_version` 条件更新当前对象键和版本,同时写入批次回执。失败整体回滚。重放已确认批次只返回首次确认的版本和时间,不重新绑定旧对象;项目删除后仍拒绝重放。首期不清理上传批次或旧 OSS 对象,不提供历史恢复接口。
`document_object_key` 和 `object_key` 均保存 `/cad-projects/{项目编码}/{批次编码}/design.sc`,不保存 `vibemake_dev/` 或 `vibemake/`。真实上传和读取在运行时补当前环境根目录。已有数据格式转换 SQL 见 [数据库 OSS 引用统一规范](oss-storage-paths.md#现有数据手工转换-sql),无需改字段结构。
## 已有数据库增加 CAD 项目封面
已有 `cad_project` 表在部署新版前手工执行一次下列 SQL;新建数据库已包含此列,不重复执行。应用不会自动修改实际数据库,现有项目封面默认为 NULL。
```sql
ALTER TABLE cad_project
ADD COLUMN cover_url VARCHAR(2048) NULL
COMMENT 'CAD项目封面,平台OSS资源存无环境前缀的相对路径'
AFTER description;
```
平台托管封面保存 `/project-covers/...` 等未编码路径,不含域名及环境根目录;接口返回时补齐当前 OSS/CDN 基础地址和环境前缀。上传复用现有封面签名,不占用设计文件上传批次,也不改变文档版本。
## 已有数据库增加工作区项目关联与初始 STEP
已有 `cad_project` 表部署新版前手工执行以下 SQL;新建数据库已包含这些字段和索引,不重复执行。已有 CAD 项目保持独立,关联编码为 NULL,初始 STEP 为空。应用不自动修改实际数据库,不修改 `.sql` 文件。
```sql
ALTER TABLE cad_project
ADD COLUMN workspace_project_code VARCHAR(32)
CHARACTER SET ascii COLLATE ascii_bin NULL
COMMENT '关联工作区项目业务编码,独立项目及已删除项目为空',
ADD COLUMN initial_step_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '初始STEP文件环境相对路径,不含域名和环境根目录',
ADD COLUMN initial_step_file_name VARCHAR(1024)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT '初始STEP原始文件名',
ADD COLUMN initial_step_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0
COMMENT '初始STEP文件大小,单位字节',
ADD UNIQUE KEY uk_cad_workspace_project_code (workspace_project_code);
```
创建关联时在事务内先锁定本人未删除的工作区项目,再查询并锁定已有 CAD 行;不存在时固定 STEP 引用并创建。唯一索引保证一个工作区项目只有一个有效关联;独立项目允许多个 NULL。STEP 沿用原对象,不复制、不转换,历史当前环境完整 key 归一为环境相对路径,中文文件名按原样保存,不受 `.sc` 文件名和大小限制影响。
CAD 逻辑删除与清空 `workspace_project_code` 在同一事务完成,保留初始 STEP 及设计文件引用,允许工作区项目再次创建新的 CAD。工作区项目删除不级联 CAD,CAD 自身的列表、读取及保存仅校验 CAD 归属,不依赖工作区项目继续存在。来源 STEP 替换或移除、来源元信息修改均不更新已有关联的 CAD。
上线顺序:执行增量 SQL → 部署后端 → 接入前端“编辑”入口。回滚后端时保留新增字段、索引及全部文件。
-109
View File
@@ -1,109 +0,0 @@
# CAD 助手知识库
知识源与后端代码在 community 一起维护,目录为 [knowledge/cad-parts](../knowledge/cad-parts/README.md)。旧独立路径已删除。保留原版17个通用Skill与原模型工具循环,社区聊天助手不接入此增强。
2026-11-12按用户最新要求,网页助手改为**自主选文档、按ID直接读文件**。本页前半部分说明当前读取契约;后面的版本试验均为历史记录,不作为当前读取门槛。实际发布与验证状态见[交接](../knowledge/cad-parts/generation/HANDOFF.md)。
## 运行方式
1. 模型的`knowledge_lookup`工具说明包含[阅读目录](../knowledge/cad-parts/generation/reading-catalog.json)的短摘要:文档ID、名称与用途,不预加载正文。
2. 原助手根据需求、建模步骤和装配体中的部件,自行选择文档。
3. 后端按目录ID读取存在的Markdown并返回原文。没有关键词、分类冲突、参数、文档状态、部署构建或预登记哈希的拒读门槛。
4. 助手结合正文理解适用边界、参数约束和近似限制;没有适用知识时继续原通用Skill,保留用户的结构要求,不能据此把齿轮降为无齿圆柱。
只提供一个读取工具,不增加分类模型调用、检索服务或强制分步审批。行星机构可按需读取机构、外直齿轮和内齿轮三个文档。读取目录不是CAD能力白名单,运动链接也不是已生成轮齿的证据。
当前阅读目录登记17份正文:15份齿轮与相关机构文档、1份XZ造筋方向提示、1份球轴承结构规程。`ball-bearing`摘要覆盖“轴承/bearing、球轴承/ball bearing、滚珠轴承、深沟球轴承”和机构内的球轴承,正文明确内置标准件仅有包络圆环,完整结构须包含内外圈、滚道、独立滚珠和保持架;轴套、滚子和裸座体由助手结合需求区分。名称供原助手自主选文,不增加后端正则或强制读取。恢复的齿轮正文保留。普通板、轴、螺栓、座体和壳体继续使用原通用Skill。目录与正文由维护者编辑;`generation/catalog.json`分类字典和`generation/policy.json`旧准入记录供离线维护与历史复现,生产读取器不使用它们进行语义判断或筛选。
同一轮有效上下文按文档标识和实际内容去重,正文被裁剪后可重新读取;新用户轮次按原机制处理过期引用。返回的SHA256由实际文件计算,只用于内容身份与去重,不与登记值比较以拒读。
## 工具与接口
模型只需提交:
```json
{"document_id":"planetary-gear-mechanism"}
```
`document_id`对应阅读目录的`id`,例如`involute-spur-gear`、`internal-spur-gear`。不再提交`query`、`type_id`或`facts`申请读取。工具Schema只有一个必需字符串参数,不使用ID枚举阻止未知ID到达读取器。
读取成功返回`status=matched`及`documents`,每项为`{id, version, sha256, text}`;目录没有该ID或文件不可读取时返回`status=not_found`及空文档列表。这里的`id`是目录中保留的原文档标识,`version`是维护元数据,二者不构成读取审批。
网页宿主继续使用正常登录和项目绑定访问`POST /api/cad/ai/knowledge`。请求为`{cadProjectCode, documentSessionCode, arguments}`,可选诊断字段`engineBuild`;`arguments`即上述模型工具参数。读取器不比较前端、后端或引擎版本,前后端可以分别更新。正常网页由动态capabilities取得工具说明与Schema,无需为读取契约重新编译CAD引擎。
`CAD_AI_KNOWLEDGE_MODE=off`保留为A/B开关,关闭时不向模型提供知识工具;`pilot`和`enabled`均展示同一阅读工具。这个开关不对已请求的目录文件设置状态或参数门槛。
## 维护与验证
Maven将阅读目录和Markdown打包到`cad/ai/knowledge/`;不依赖本机Python服务或任意文件路径。新增知识时维护一条目录记录和对应Markdown即可。参数条件、表示精度与检查要求写在正文里,不需要补正则、兼容构建白名单或准入条件。具体规范见[维护方法](../knowledge/cad-parts/generation/MAINTENANCE.md)。
正文质量依靠参考实例、真实助手测试、原生设计、截图与独立几何检查持续改进;文件可读不等于生成结果已验证。旧路由固定用例和源码作为历史保留,不能把它们算作新直读接口已通过的评测。
在JDK21下运行当前后端回归:
```bash
mvn -q -pl vibemake-api -am \
-Dtest=CadAiKnowledgeTest,CadAiKnowledgeUtilityTest,CadAiSampleKnowledgeTest,CadAiProtocolTest,ArkCadAiClientTest,CadAiTest \
-Dsurefire.failIfNoSpecifiedTests=false package
```
离线分类资料仍可执行`python3 -m cad_knowledge check`、`evaluate`及`python3 -m unittest discover -s tests -v`。历史Python `generation-context`是旧政策的离线维护/复现接口,不是网页助手的读取器,其状态或哈希筛选不控制生产读取。当前源码测试、实际发布、文件送达和模型生成效果分别记录。
## 历史试验记录
下述记录描述当时的申请式检索、准入条件与运行环境,原样保留。其`experimental`、`approved`、`compatible_builds`、`needs_conditions`等描述均不恢复为当前读取门槛。
## 首轮真实网页结果
固定 OpenAI `gpt-6.1-terra` / `high`、引擎 `fc4e47a8db81e633cafe8e63`、同一后端 JAR 和原通用工具。外部脚本驱动正式网页,不向题目追加规程,不修补模型生成的几何:
- 同题 20 齿完整结构:A 关闭知识,132.8 秒结束,未生成实体;B 按需读取一次正文,155.9 秒完成轮毂、孔、键槽及齿形,独立几何复核通过。
- 20 齿加独立同轴轴:232.2 秒,按部件查询一次,两实体及齿形复核通过。
- 较早后端的 24 齿圆孔、无轮毂、无键槽样例复核通过,作为补充证据,不混入最终同版本 A/B。
每个有效齿轮样例独立采样 2028 点,最大渐开线采样偏差小于 0.002 mm;不等同于全曲线严格误差证明或制造认证。A 的未完成耗时不能与 B 的完成耗时构成速度收益结论。两次接入设置失败保留原始记录,不能只展示补跑成功。完整题目、截图、版本指纹、传输情况和复核限制以[实测报告](../knowledge/cad-parts/reports/gear-integration-20261111/README.md)为准。
首轮继续使用 `experimental` / `pilot`。重复读取、上下文裁剪后重读和新轮次失效已做程序测试;首轮未完成模型多轮类型切换实测,也未验证其他齿制的生成效果。完整设计和后续验收范围见[实施方案](../knowledge/cad-parts/plans/cad-assistant-knowledge-integration-plan-20261111.md)。
首轮 15/15 个真实只读接口诊断通过;但当时斜齿模型实测向 `facts` 提交了 Schema 外字段,被协议拒绝并直接结束,未执行查询和预期的原助手回退。不能把接口 `uncovered` 通过写成该端到端场景通过。该历史失败继续保留。
后续源码已改为由统一属性字典生成可选事实字段,按每份规程的条件决定缺参;原有安全恢复链可将非法工具参数作为可重试诊断交回模型,不增加第二套服务端模型循环,不返回部分可执行 CAD 调用。该契约修正已有后端回归测试记录,见[属性契约记录](../knowledge/cad-parts/reports/gear-query-contract-20261111.json)。另已增加有符号角绝对值范围及内齿、斜齿试点的派生半径边界检查,79 项服务测试通过(含 72 个固定路由样例),见[派生边界源码测试](../knowledge/cad-parts/reports/gear-query-contract-20261112.json)。这些检查仅在相应类型规程声明了完整依赖条件且无缺参或冲突时执行,不将外直齿的齿根关系套到其他齿制。源码测试、打包部署和真实网页恢复验证必须分开:没有新部署和网页复测证据时,不能把这次修正写成已修复线上斜齿生成。
## 齿轮扩展阶段(2026-11-12)
目录版本为 0.2.0,现有 13 份 `experimental` 规程:9 类单体(外直齿、内直齿、斜齿圆柱、直齿锥齿、螺旋锥齿、直齿条、斜齿条、ZA 蜗杆和示意蜗轮)及 4 类静态机构。其他齿传动暂不扩展。所有启用条件、正文哈希和精确构建兼容仍以 `policy.json` 为准。
本轮新构建 `f3d62ce93f72db42f311a46e` 修复了“旧知识引用出现在重新读取的完整正文前面时,错误压掉完整正文”的上下文去重问题;原 17 个通用 Skill 及其正文未变。13 类参考构造已在实际网页编辑器完成回放和对应几何审计;这只证明规程构造可在当前工具下实现。复杂锥齿与蜗轮保留明确的非制造级近似声明,静态机构审计不证明全周期接触或运动。
扩展阶段 v1 通过 100 项定向后端测试(81 项服务、19 项 API)与 140 条固定路由评测。正式调用暴露的查询契约问题随后在统一 v2 部署修正:104 项定向测试(85 项服务、19 项 API)、152 条固定路由评测通过,原 17 Skill 和 13 规程正文未变。v2 外直齿与齿轮副已观察到正文真实交付,内齿复合中文表述仍有实际路由缺口;不能把程序评测通过写成所有真实查询都成功。离线资料本轮 36 项单测通过。
后续 v5/v6 仅修改待发布源码:内外啮合复合名称、禁止替代语句作用域、机构短名及齿条属性说明的回归已通过(v6:222 条固定路由样例、88 项服务测试)。源码记录见 [v6 检查报告](../knowledge/cad-parts/reports/gear-routing-v6-source-20261112.json)。**当前正式 v2 测试仍使用冻结的原 JAR,未部署这些修正**;参考部件与当前部件的区分、部分限定词词序仍有已知缺口。维护时必须分别记录源码检查、实际部署和正式模型产物,不能由其中一个状态推断另外两个。
当前源码收尾复查的 **107 项针对性后端测试**(知识31、协议26、客户端31、API19)全部通过,仅运行 `test` 阶段,未重打包或重启;冻结运行 JAR 与原17个Skill的哈希再次核对未变,见[最终检查](../knowledge/cad-parts/reports/gear-source-final-check-20261112.json)。正式模型主对照的题目、原始产物链接、并排截图及独立补测见[截图与证据索引](../knowledge/cad-parts/reports/gear-family-expansion-20261112/FORMAL-AB-V2.md),补测不替换主对照中的失败。
参考回放、历史失败与补采、v1/v2部署指纹及正式同JAR模型A/B结果见[测试结果与流程评估](../knowledge/cad-parts/reports/gear-family-expansion-20261112/README.md)。本轮13对、26次主尝试已收尾:25次自然终态、1次测试中断;另3次独立补测与只读精度补证分别保存。各worker已暂停,无待执行模型。B组仅6次实际取得正文;上游模型异常、知识送达、静态几何与完整参数传播分别记录,不能由程序测试或参考回放推断总体生成收益。
源码政策的过时证据占位已更新为本轮实际入口,仅修改证据字段;13份候选继续`experimental`,没有升级为`approved`,正文、适用条件和兼容构建不变。运行JAR仍冻结,未部署后续路由源码修复或此次索引更新。证据与更新后检查见[索引收尾](../knowledge/cad-parts/reports/gear-evidence-index-closeout-20261112.json)、[源码检查](../knowledge/cad-parts/reports/gear-family-expansion-20261112/final-source-check.json)及[离线检查](../knowledge/cad-parts/reports/gear-family-expansion-20261112/final-offline-check.json)。
### 后续 v7 源码与独立 v3 运行版本
上述 v2 冻结记录属于历史试验,未被覆盖。后续 v7 修复参考对象、生成否定和局部限定词词序,澄清蜗杆/参考蜗杆的属性归属;不从自由文本抽取尺寸,不自动填值。109 项针对性后端测试和 268 条固定路由通过,既有 222 条样例逐字保留。斜齿圆柱、斜齿条及 ZA 蜗杆的检查说明改为 0.1.1,纠正显示折线字段与实际曲线采样的区别,构造公式和步骤不变,旧正文保留。见 [v7 源码与打包检查](../knowledge/cad-parts/reports/gear-routing-v7-source-20261112.json)。
本机随后单独部署 v3:JAR SHA256 为 `bb49b26788b4707d301abd1a523a2e30c1ebcbb06e7673da3ce1ead08c7b37b4`,引擎、OpenAI `gpt-6.1-terra` / `high`、原 17 个 Skill 和 12 个通用工具不变。登录后通过正式网页宿主重放 59 条查询全部符合预期,并核对 13 类正文的版本和哈希;见 [v7 实接口记录](../knowledge/cad-parts/reports/gear-routing-v7-live-20261112.json)。
新一轮七题为 B-only 独立补测,不能与旧 v2 A 组组成新的同版本 A/B,也不替代其失败。实际生成仍由正式网页助手完成,外部脚本不附加提示、不修补几何。当前所有候选继续 `experimental`,本机继续 `pilot`;源码、取文、实体、具体几何和完整编辑传播的状态分别记录。
### 当前收尾状态:路由v8、运行v5
后续先保存“直齿小齿轮”实测未命中的回归,再补充15个明确齿制的中英文别名;普通“小齿轮”仍不自动定类。110项针对性后端测试、287条固定路由通过,v4登录后的32条实接口重放及13类正文哈希核对通过。见 [v8源码](../knowledge/cad-parts/reports/gear-routing-v8-source-20261112.json)、[v8实接口](../knowledge/cad-parts/reports/gear-routing-v8-live-20261112.json)。蜗轮0.1.1以明确派生点防止根部圆弧抄写错误;0.1.2再明确保留原有1.5m毛坯余量,避免模型误换1.25m。原几何方法、类型条件、引擎与通用Skill未变。
v3七次、v4两次及v5一次补测都独立保留;每次正式网页均实际取得正文,无服务异常提示。v3有5个单体样例通过,蜗轮和机构失败;v4齿轮齿条通过,蜗轮仍因余量公式失败;v5蜗轮通过全宽喉部、体积和实际曲线/曲面采样等14项检查。旧失败不由补测覆盖,后续B不与旧A组成跨版对照。所有题目、原图、原生文件、检查限制见 [当前覆盖清单](../knowledge/cad-parts/reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)。
上述为齿轮v5阶段的历史部署:JAR SHA256 `66330cc022931791bfb1c64973e422a4358d770c7a40d20c18dca4eb28dc4012`,13份`experimental`、0份`approved`。该期worker与队列已收尾,不重发旧题。
2026-11-12用户另行授权五个样板和两种人字齿的新阶段。目录0.3.0,共28类型、53属性,政策20份`experimental`、1份`retired`、0份`approved`。正式v1使用独立冻结JAR `177a1aad09e28fae2308f3cd4d8fd4f4d0cb9967229b95d9906c137b61f9f6b7`、OpenAI `gpt-6.1-terra`/`high`及引擎`f3d62ce93f72db42f311a46e`,14次A/B已结束。五类样板均有通过产物,关键参数的独立副本改参5/5通过;两种人字齿正式生成未通过,原失败、正文未送达和前端中断分开保留。见[正式v1](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/FORMAL-V1.md)与[副本改参](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/EDITS-V1.md)。
后续修正板/壳的否定特征、无槽人字齿的零槽宽误拒,并将用户确认的齿轮副名称合并一并验证发布。最终114项后端测试及501条固定例通过,登录后的真实接口193/193符合预期:183个路由响应、10个非法枚举400拒绝。两份人字齿正文为0.1.1,实际文本哈希一致;只澄清已有参考命令,模型效果仍未验证,没有重发正式题目。由于共享8091已切换到另一任务的新引擎,用户确认本轮在独立8092/8994保留原引擎部署v2,JAR SHA256为`4b7aaa5bd886ccba1ea34b1be1be0789592ebc66ebb1c04f176f0dcab1b7185a`。原Skill、指令、工具循环及预算保持,仍无准入升级。见[路由/正文独立发布](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/ROUTING-V2.md)、[本轮总报告](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/README.md)和[带时间交接](../knowledge/cad-parts/generation/HANDOFF.md)。共享8091/8993由其他任务管理,后续操作须核对实际状态。
后端仅对已声明的适用条件及少量必要派生数值域进行拦截,包括内/外齿半径关系、锥齿缩比、蜗杆齿根和长度、蜗轮喉部定义域。孔槽、全局干涉、复杂齿面接触等仍需按规程检查,`matched` 不代表模型几何已通过验收。
-342
View File
@@ -1,342 +0,0 @@
# 数据库初始化
业务数据库名为 `vibemake`,基础业务包含以下四张表及项目 Git 凭据表;完整部署还需执行 [管理端增量 SQL](admin-database.md),新增迁移任务与仓库写入操作表。CAD 工作空间另行执行 [CAD 建表 SQL](cad-database.md),新增两张独立表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8.0.13 及以上(URDF JSON 默认值使用表达式)。
```sql
CREATE DATABASE IF NOT EXISTS vibemake CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE vibemake;
CREATE TABLE sys_user (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部用户主键',
user_code CHAR(32) NOT NULL COMMENT '用户业务编码',
email VARCHAR(254) NOT NULL COMMENT '规范化后的登录邮箱',
nickname VARCHAR(100) NOT NULL COMMENT '用户昵称',
status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE' COMMENT '账号状态',
role VARCHAR(16) NOT NULL DEFAULT 'USER' COMMENT '用户角色 USER普通用户 ADMIN管理员 OFFICIAL官方托管账号',
password_hash VARCHAR(100) NULL COMMENT '管理员BCrypt密码哈希,普通用户为空',
session_version BIGINT NOT NULL DEFAULT 0 COMMENT '登录会话版本,禁用或修改密码时递增',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_user_code (user_code),
UNIQUE KEY uk_user_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='平台用户';
CREATE TABLE project (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部项目主键',
project_code CHAR(32) NOT NULL COMMENT '项目业务编码',
owner_user_id BIGINT NOT NULL COMMENT '所属平台用户',
name VARCHAR(100) NOT NULL COMMENT '项目名称',
description TEXT NOT NULL COMMENT '项目描述',
cover_url VARCHAR(2048) NULL COMMENT '项目封面,平台资源存环境相对路径,外部图片存完整HTTPS地址',
urdf_main_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF主文件环境相对路径,以斜杠开头,不含域名和环境根目录',
urdf_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT 'URDF文件清单数组,元素包含relativePath和sizeBytes,相对路径以urdf_prefix为基准',
urdf_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF资源环境相对目录,包含上传批次,以斜杠开头和结尾',
step_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'STEP文件环境相对路径,不含域名和环境根目录',
step_file_name VARCHAR(1024) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'STEP原始文件名,保留大小写中文和空格',
step_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'STEP文件大小,单位字节,未绑定时为零',
model_glb_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '整机GLB环境相对路径,不含域名和环境根目录',
model_glb_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '整机GLB文件大小,单位字节',
model_parts_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '零件模型环境相对目录,以斜杠开头和结尾',
model_parts_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT '零件GLB文件清单,包含relativePath和sizeBytes',
assembly_json_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '拼装步骤JSON环境相对路径,不含域名和环境根目录',
assembly_json_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '拼装步骤JSON文件大小,单位字节',
walking_resources_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '行走资源环境相对目录,以斜杠开头和结尾',
walking_resources_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT '行走资源文件清单,包含relativePath和sizeBytes',
project_type VARCHAR(64) NOT NULL COMMENT '配置中的项目类型编码',
gitea_repo_id BIGINT NULL COMMENT 'Gitea 仓库标识',
gitea_owner VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库所属组织',
gitea_repo_name VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库名称',
repo_status VARCHAR(16) NOT NULL DEFAULT 'CREATING' COMMENT '仓库状态 CREATING READY FAILED',
publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架',
published_commit_sha VARCHAR(64) NULL COMMENT '社区已发布 Commit SHA',
published_at DATETIME(3) NULL COMMENT '最近发布时间(Asia/Shanghai)',
moderation_reason VARCHAR(500) NULL COMMENT '管理员下架原因',
repo_write_status VARCHAR(16) NOT NULL DEFAULT 'IDLE' COMMENT '仓库写入状态 IDLE空闲 WRITING写入中 REVIEW待核对',
source_project_id BIGINT NULL COMMENT 'Fork 来源项目',
source_commit_sha VARCHAR(64) NULL COMMENT 'Fork 来源已发布 Commit SHA',
deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标识',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_project_code (project_code),
UNIQUE KEY uk_project_repo (gitea_owner, gitea_repo_name),
UNIQUE KEY uk_project_repo_id (gitea_repo_id),
KEY idx_project_owner (owner_user_id, deleted, created_at),
KEY idx_project_vibemake (publish_status, deleted, published_at),
KEY idx_project_type (publish_status, deleted, project_type, published_at),
CONSTRAINT fk_project_owner FOREIGN KEY (owner_user_id) REFERENCES sys_user(id),
CONSTRAINT fk_project_source FOREIGN KEY (source_project_id) REFERENCES project(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户项目与社区发布';
CREATE TABLE project_comment (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部评论主键',
comment_code CHAR(32) NOT NULL COMMENT '评论业务编码',
project_id BIGINT NOT NULL COMMENT '所属项目',
user_id BIGINT NOT NULL COMMENT '评论用户',
content TEXT NOT NULL COMMENT '纯文本评论内容',
deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标识',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_comment_code (comment_code),
KEY idx_comment_project (project_id, deleted, created_at),
CONSTRAINT fk_comment_project FOREIGN KEY (project_id) REFERENCES project(id),
CONSTRAINT fk_comment_user FOREIGN KEY (user_id) REFERENCES sys_user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='项目评论';
CREATE TABLE project_like (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部点赞主键',
project_id BIGINT NOT NULL COMMENT '所属项目',
user_id BIGINT NOT NULL COMMENT '点赞用户',
created_at DATETIME(3) NOT NULL COMMENT '点赞时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_like_project_user (project_id, user_id),
CONSTRAINT fk_like_project FOREIGN KEY (project_id) REFERENCES project(id),
CONSTRAINT fk_like_user FOREIGN KEY (user_id) REFERENCES sys_user(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='项目点赞';
```
内部 ID 仅用于数据库关联,对外使用业务编码。时间均由后端写入上海时间(Asia/Shanghai,UTC+8)。`CREATING` 项目表示仓库初始化未完成,不代表编辑草稿。Gitea 数据库与业务库分离,不修改 Gitea 内部表。
新增项目和用户使用 12 位小写字母和数字编码,历史 32 位编码继续保留。现有 `project_code CHAR(32)` 和 `user_code CHAR(32)` 可容纳两者,不需要修改表结构或历史记录;仓库名称仍为 `p_{projectCode}`。用户编码由安全随机数生成,唯一索引兜底,冲突时最多尝试 5 次;同一邮箱并发注册复用已有用户。评论编码保持 32 位。GitHub 运维导入的来源和进度保存于批次状态目录,GitHub 来源不占用社区内部 Fork 来源字段。
## 已有数据库增加项目封面
已使用旧版结构的环境,先在对应业务库执行以下 SQL,再部署新版本应用;新建数据库已包含此字段,不重复执行。应用不会自动迁移数据库。
```sql
ALTER TABLE project
ADD COLUMN cover_url VARCHAR(2048) NULL COMMENT '项目封面,平台资源存环境相对路径,外部图片存完整HTTPS地址' AFTER description;
```
历史项目的封面为 NULL。平台封面保存 `/project-covers/...` 环境相对路径;外部 HTTPS 图片保留完整地址。历史完整平台 URL 仍可读取,不保存临时签名下载地址。替换、清除封面和删除项目不会自动删除 OSS 对象,Fork 可能共用同一资源。
## 已有数据库增加项目 URDF
先在对应业务库手动执行以下 SQL,再部署应用;新建数据库已包含三个字段,不重复执行。不要在应用启动时自动迁移。
```sql
ALTER TABLE project
ADD COLUMN urdf_main_object_key VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT 'URDF主文件环境相对路径,以斜杠开头,不含域名和环境根目录',
ADD COLUMN urdf_files JSON NOT NULL DEFAULT (JSON_ARRAY())
COMMENT 'URDF文件清单数组,元素包含relativePath和sizeBytes,相对路径以urdf_prefix为基准',
ADD COLUMN urdf_prefix VARCHAR(512)
CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT 'URDF资源环境相对目录,包含上传批次,以斜杠开头和结尾';
```
未上传或已清除时,两个字符串均为 `''`,文件清单为 `[]`。每个项目只绑定一个当前资源包,包内必须恰好有一个 `.urdf`(忽略扩展名大小写)。清单包含全部文件,例如 `[{"relativePath":"urdf/robot.urdf","sizeBytes":1234},{"relativePath":"meshes/base.stl","sizeBytes":5678}]`。
存储前缀为 `/urdf/{projectCode}/{batchCode}/`,主文件路径为此前缀加主文件相对路径,不含域名及环境根目录。实际 OSS key 为 `{环境根目录}{存储路径}`,接口根据 OSS/CDN 配置生成并编码 URL。历史带当前环境根目录的 key 兼容读取;其他环境的 key 不会被自动重定位。替换、清除、删除项目不物理删除对象,公开旧链接仍可读取;Fork 复制到新项目的独立目录,不共用源前缀。URDF 不进入 Gitea、不生成 Commit,更新立即影响社区展示。
## 资源路径历史数据迁移
CAD 两张表、STEP 和其他项目资源的补充转换 SQL,以及全部 OSS 绑定字段的统一存储规范,见 [数据库 OSS 引用规范](oss-storage-paths.md)。本节继续处理历史完整封面 URL 的匹配、解码和原有 URDF 数据。
先升级所有在线及导入写入进程,新版本兼容新旧格式,读取不修改记录。按环境分别执行以下操作;test 根目录为 `vibemake_dev`,prod 为 `vibemake`。OSS 对象不移动,`urdf_files`、`updated_at` 不变。不要在不同环境共用同一业务数据库。
迁移前备份数据库,并将候选记录的原值导出至备份目录。以下临时表仅属于当前数据库连接,不能代替持久备份。封面按每个受控公开基础地址分别执行一遍,包含 Bucket 标准域名、当前 CDN 基础地址和 `vibemake.oss.legacy-public-base-urls` 中的历史地址;基础地址不含环境根目录。不使用全局 REPLACE,不转换外链、带参数/片段地址或其他环境路径。
### 预览与准备
以下命令在同一个 MySQL 8 连接内执行。仅自动转换上传流程生成的规范 ASCII 封面路径,编码形式、非标准目录和异常 URDF 记录列出后跳过,由维护人员核验。数据库比较使用二进制排序规则,避免默认不区分大小写导致误匹配。所有正则的输入和模式均显式指定 `utf8mb4_bin`,避免字段、会话变量和 CONCAT 结果的排序规则推导冲突(1267);仅设置 SET NAMES 不足以消除表达式冲突。这里是字符排序规则,不使用 BINARY 强制转换作为正则参数。
```sql
-- resource-path-migration-prepare
SET NAMES utf8mb4 COLLATE utf8mb4_bin;
SET @resource_root = 'vibemake_dev';
SET @resource_public_base = 'https://linkerbot.oss-cn-beijing.aliyuncs.com';
SET @cover_prefix = CONCAT(TRIM(TRAILING '/' FROM @resource_public_base), '/', @resource_root, '/project-covers/');
DROP TEMPORARY TABLE IF EXISTS resource_path_audit;
CREATE TEMPORARY TABLE resource_path_audit AS
SELECT project_code, cover_url AS old_cover_url,
urdf_main_object_key AS old_main, urdf_prefix AS old_prefix,
LEFT(cover_url, CHAR_LENGTH(@cover_prefix)) COLLATE utf8mb4_bin = @cover_prefix COLLATE utf8mb4_bin
AND REGEXP_LIKE(SUBSTRING(cover_url, CHAR_LENGTH(@cover_prefix) + 1) COLLATE utf8mb4_bin,
'^[a-z0-9]{12}([a-z0-9]{20})?/[0-9]{8}/[a-f0-9]{32}[.](jpg|png|webp)$' COLLATE utf8mb4_bin, 'c') AS cover_ok,
REGEXP_LIKE(urdf_prefix COLLATE utf8mb4_bin,
CONCAT('^', @resource_root, '/urdf/', TRIM(project_code), '/[a-f0-9]{32}/$') COLLATE utf8mb4_bin, 'c')
AND LEFT(urdf_main_object_key, CHAR_LENGTH(urdf_prefix)) COLLATE utf8mb4_bin = urdf_prefix COLLATE utf8mb4_bin
AND CHAR_LENGTH(urdf_main_object_key) > CHAR_LENGTH(urdf_prefix)
AND REGEXP_LIKE(urdf_main_object_key COLLATE utf8mb4_bin, '[.]urdf$' COLLATE utf8mb4_bin, 'i')
AND LOCATE('//', urdf_main_object_key) = 0
AND LOCATE(CHAR(92), urdf_main_object_key) = 0
AND NOT REGEXP_LIKE(urdf_main_object_key COLLATE utf8mb4_bin,
'(^|/)[.]{1,2}(/|$)|(^|/)[.]git(/|$)|[[:cntrl:]:]' COLLATE utf8mb4_bin, 'i') AS urdf_ok
FROM project;
DROP TEMPORARY TABLE IF EXISTS resource_path_changes;
CREATE TEMPORARY TABLE resource_path_changes AS
SELECT project_code, old_cover_url, old_main, old_prefix,
CASE WHEN cover_ok THEN CONCAT('/project-covers/', SUBSTRING(old_cover_url, CHAR_LENGTH(@cover_prefix) + 1)) ELSE old_cover_url END AS new_cover_url,
CASE WHEN urdf_ok THEN SUBSTRING(old_main, CHAR_LENGTH(@resource_root) + 1) ELSE old_main END AS new_main,
CASE WHEN urdf_ok THEN SUBSTRING(old_prefix, CHAR_LENGTH(@resource_root) + 1) ELSE old_prefix END AS new_prefix
FROM resource_path_audit WHERE cover_ok OR urdf_ok;
SELECT COUNT(*) AS candidate_count FROM resource_path_changes;
-- 将下列结果导出并保存;包含迁移前后值,供审计及精确恢复使用。
SELECT * FROM resource_path_changes ORDER BY project_code;
-- 必须人工核验的封面及 URDF,结果不包含完整外链。
SELECT project_code, '封面路径非标准或包含参数,请人工核验' AS reason
FROM resource_path_audit
WHERE LEFT(old_cover_url, CHAR_LENGTH(@cover_prefix)) COLLATE utf8mb4_bin = @cover_prefix COLLATE utf8mb4_bin AND NOT cover_ok
UNION ALL
SELECT project_code, 'URDF路径或主文件关系异常,或属于其他环境' AS reason
FROM resource_path_audit
WHERE (old_main <> '' OR old_prefix <> '') AND NOT urdf_ok
AND NOT (LEFT(old_main, 6) = '/urdf/' AND LEFT(old_prefix, 6) = '/urdf/');
```
### 人工执行转换
确认备份、预览和异常清单后,在原连接内执行。更新时比较三列原值,避免覆盖预览后的并发修改;数量不足时重新预览,不能删除原值比较条件强制更新。再次运行准备及转换流程时,已转换行不会再次命中。
```sql
-- resource-path-migration-apply
START TRANSACTION;
UPDATE project p JOIN resource_path_changes c ON c.project_code = p.project_code
SET p.cover_url = c.new_cover_url,
p.urdf_main_object_key = c.new_main,
p.urdf_prefix = c.new_prefix
WHERE p.cover_url COLLATE utf8mb4_bin <=> c.old_cover_url COLLATE utf8mb4_bin
AND p.urdf_main_object_key COLLATE utf8mb4_bin = c.old_main COLLATE utf8mb4_bin
AND p.urdf_prefix COLLATE utf8mb4_bin = c.old_prefix COLLATE utf8mb4_bin;
COMMIT;
```
验证项目列表、详情、AI 卡片及 Fork 的公开 URL 与迁移前指向相同对象。迁移不触发项目重新发布,也不删除任何 OSS 对象。
### URDF 更新遇到 1267 时续跑
旧脚本如果在 URDF 更新处报 `Illegal mix of collations ... regexp_like`,先前成功的封面更新可能仍未提交。保留原连接,在同一连接执行下面的续跑 SQL;不要重新发起 START TRANSACTION 或修改字段排序规则。末尾 COMMIT 会同时提交该连接中先前成功的更新。prod 将根目录改为 `vibemake`。该脚本不再修改封面,且只匹配未转换的当前环境 URDF。
```sql
-- resource-path-migration-resume-urdf
SET NAMES utf8mb4 COLLATE utf8mb4_bin;
SET @resource_root = 'vibemake_dev';
UPDATE project
SET urdf_main_object_key = SUBSTRING(urdf_main_object_key, CHAR_LENGTH(@resource_root) + 1),
urdf_prefix = SUBSTRING(urdf_prefix, CHAR_LENGTH(@resource_root) + 1)
WHERE REGEXP_LIKE(
urdf_prefix COLLATE utf8mb4_bin,
CONCAT('^', @resource_root, '/urdf/', TRIM(project_code), '/[a-f0-9]{32}/$') COLLATE utf8mb4_bin,
'c'
)
AND LEFT(urdf_main_object_key, CHAR_LENGTH(urdf_prefix)) COLLATE utf8mb4_bin = urdf_prefix COLLATE utf8mb4_bin
AND CHAR_LENGTH(urdf_main_object_key) > CHAR_LENGTH(urdf_prefix)
AND REGEXP_LIKE(urdf_main_object_key COLLATE utf8mb4_bin, '[.]urdf$' COLLATE utf8mb4_bin, 'i')
AND LOCATE('//', urdf_main_object_key) = 0
AND LOCATE(CHAR(92), urdf_main_object_key) = 0
AND NOT REGEXP_LIKE(
urdf_main_object_key COLLATE utf8mb4_bin,
'(^|/)[.]{1,2}(/|$)|(^|/)[.]git(/|$)|[[:cntrl:]:]' COLLATE utf8mb4_bin,
'i'
);
COMMIT;
```
### 更新字段中文注释
以下 DDL 独立执行,不与数据转换事务混用。字段名、类型、长度及空值约定不变;应用不会自动执行。
```sql
ALTER TABLE project
MODIFY COLUMN cover_url VARCHAR(2048) NULL
COMMENT '项目封面,平台资源存环境相对路径,外部图片存完整HTTPS地址',
MODIFY COLUMN urdf_main_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT 'URDF主文件环境相对路径,以斜杠开头,不含域名和环境根目录',
MODIFY COLUMN urdf_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT ''
COMMENT 'URDF资源环境相对目录,包含上传批次,以斜杠开头和结尾';
```
### 回退旧版本
先暂停所有资源写入并备份数据库。必须转换当前全部新格式记录,不能仅恢复迁移前备份,否则会丢失升级后的有效写入。回退封面时需要 UTF-8 URL 编码,使用离线生成器准备 SQL 值;工具不连接数据库,也不执行 SQL。
```sql
-- 导出查询结果为 JSON Lines(仅结果值,无列头);保持资源写入暂停。
SELECT JSON_OBJECT('projectCode', project_code, 'coverPath', cover_url)
FROM project WHERE LEFT(cover_url, 16) = '/project-covers/';
```
```bash
python3 scripts/resource-path-rollback.py --root vibemake_dev \
--public-base-url 'https://linkerbot.oss-cn-beijing.aliyuncs.com' \
--input /backup/resource-covers.jsonl --output /backup/resource-cover-values.txt
```
生成失败时不要继续。新开连接,设置与当前环境一致的根目录,执行以下准备 SQL,再人工执行生成的 `.txt` 中 INSERT 语句。生成器将中文、空格、百分号等正确编码;超出旧字段 2048 字符上限时会拒绝生成,需先修复该项目封面或保留兼容版本。
```sql
-- resource-path-rollback-prepare
SET NAMES utf8mb4 COLLATE utf8mb4_bin;
SET @resource_root = 'vibemake_dev';
DROP TEMPORARY TABLE IF EXISTS resource_cover_rollback;
CREATE TEMPORARY TABLE resource_cover_rollback (
project_code CHAR(32) NOT NULL PRIMARY KEY,
cover_path VARCHAR(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
full_url VARCHAR(2048) NOT NULL
);
-- 在此执行生成器输出的 INSERT;为空文件表示没有待回退的平台封面。
```
确认映射覆盖所有 `/project-covers/` 记录,再执行以下 SQL。URDF 两列仅在属于本项目且互相匹配时成对恢复前缀;异常记录先修复,不能直接回退代码。
```sql
-- resource-path-rollback-apply
START TRANSACTION;
UPDATE project p JOIN resource_cover_rollback c ON c.project_code = p.project_code
SET p.cover_url = c.full_url
WHERE p.cover_url COLLATE utf8mb4_bin = c.cover_path COLLATE utf8mb4_bin;
UPDATE project
SET urdf_main_object_key = CONCAT(@resource_root, urdf_main_object_key),
urdf_prefix = CONCAT(@resource_root, urdf_prefix)
WHERE REGEXP_LIKE(urdf_prefix COLLATE utf8mb4_bin,
CONCAT('^/urdf/', TRIM(project_code), '/[a-f0-9]{32}/$') COLLATE utf8mb4_bin, 'c')
AND LEFT(urdf_main_object_key, CHAR_LENGTH(urdf_prefix)) COLLATE utf8mb4_bin = urdf_prefix COLLATE utf8mb4_bin
AND CHAR_LENGTH(urdf_main_object_key) > CHAR_LENGTH(urdf_prefix)
AND REGEXP_LIKE(urdf_main_object_key COLLATE utf8mb4_bin, '[.]urdf$' COLLATE utf8mb4_bin, 'i')
AND LOCATE('//', urdf_main_object_key) = 0
AND LOCATE(CHAR(92), urdf_main_object_key) = 0
AND NOT REGEXP_LIKE(urdf_main_object_key COLLATE utf8mb4_bin,
'(^|/)[.]{1,2}(/|$)|(^|/)[.]git(/|$)|[[:cntrl:]:]' COLLATE utf8mb4_bin, 'i')
AND CHAR_LENGTH(CONCAT(@resource_root, urdf_main_object_key)) <= 512
AND CHAR_LENGTH(CONCAT(@resource_root, urdf_prefix)) <= 512;
COMMIT;
SELECT project_code FROM project
WHERE LEFT(cover_url, 16) = '/project-covers/'
OR LEFT(urdf_main_object_key, 6) = '/urdf/' OR LEFT(urdf_prefix, 6) = '/urdf/';
```
最后查询必须为空,随后验证旧格式地址并回退应用,再恢复写入。旧版不识别相对路径,禁止只回退代码而跳过数据转换。
## 项目 Git 凭据
HTTPS Git 功能默认关闭。已有数据库在启用前手工执行下列建表,以及 [仓库写入记录扩展](admin-database.md#https-git-写入记录扩展)。不自动迁库;回滚保留表和审计记录。所有时间为上海时间。
```sql
CREATE TABLE project_git_token (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对用户端暴露',
token_code CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT 'Git凭据唯一业务编码',
project_code CHAR(32) NOT NULL COMMENT '绑定的项目业务编码',
owner_user_id BIGINT NOT NULL COMMENT '所属用户内部标识,仅内部关联',
token_name VARCHAR(64) NOT NULL COMMENT '用户填写的凭据名称',
token_hash CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '凭据明文的SHA256摘要,不保存明文',
permission VARCHAR(16) NOT NULL COMMENT '权限 READ_ONLY只读 READ_WRITE读写',
session_version BIGINT NOT NULL COMMENT '签发时账号会话版本,用于账号变更后失效',
expires_at DATETIME(3) NOT NULL COMMENT '过期时间,上海时间',
revoked_at DATETIME(3) NULL COMMENT '撤销时间,未撤销为空',
last_used_at DATETIME(3) NULL COMMENT '最近成功认证时间,上海时间',
created_at DATETIME(3) NOT NULL COMMENT '创建时间,上海时间',
updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间,上海时间',
PRIMARY KEY (id),
UNIQUE KEY uk_git_token_code (token_code),
UNIQUE KEY uk_git_token_hash (token_hash),
KEY idx_git_token_project_owner (project_code, owner_user_id, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
COLLATE=utf8mb4_unicode_ci COMMENT='项目级Git访问凭据';
```
-315
View File
@@ -1,315 +0,0 @@
# CAD Web AI Agent 前端对接
本文描述已实现的后端接口和 makeCAD 网页端需要完成的适配。后端不运行 CAD 引擎,不执行工具,也不持久保存聊天。**仅嵌入当前 makeCAD 网页构建不会自动启用 Agent**:原有模型客户端、CLI Agent 和聊天入口受桌面编译条件限制,需要前端新增网页 `ChatBackend`、工具适配器及文档生命周期管理。
调用链:makeCAD 面板 → `/api/cad/ai/chat` → 豆包 → 浏览器执行工具 → 携带结果再次请求。一次 HTTP 请求只推进一次模型推理。设计文件的保存与续编仍使用 [CAD 工作空间接口](frontend-cad-workspace.md)。
## 登录、启用和能力
全部接口复用平台 `Authorization: Bearer <token>`,不向网页下发方舟密钥或 Endpoint。推荐同源部署;iframe 使用受控宿主桥接时校验精确 origin、source 和请求关联编码,Token 不进入 URL。关闭、换账号或退出登录时取消旧请求并清理账号相关会话。
| 方法 | 路径 | 返回 |
| --- | --- | --- |
| GET | `/api/cad/ai/capabilities` | 普通统一 JSON 包装,data 为能力 |
| POST | `/api/cad/ai/chat` | `text/event-stream`,每个 data 使用统一包装 |
```ts
interface CadAiCapabilities {
enabled: boolean;
protocolVersion: 'cad-agent-v1';
model: string;
tools: Array<{ name: string; description: string; parameters: object }>;
limits: {
requestBytes: number; // 4194304,仅 chat 请求
imageBytes: number; // 1048576,单图解码后字节
imageMaxEdge: number; // 2048
imagesPerRequest: number; // 2,包含全部历史中的图片
textBytes: number; // 524288(512 KiB),UTF-8 文本及结构化上下文
toolResultTextBytes: number; // 32768,单份工具结果的文字合计
historyItems: number; // 256
maxModelCallsPerTurn: number; // 默认 12
maxChangesPerTurn: number; // 默认 24
requestTimeoutSeconds: number;// 默认 300
requestsPerMinute: number; // 默认 30,工具续调同样计数
};
}
```
先读能力,再启用面板中的平台 Agent。功能关闭或基础配置不完整时 `enabled=false`,能力接口仍返回 200;聊天接口返回 503。界面使用平台指定模型,隐藏本地 Agent、API Key、任意服务地址、模型切换及不受限权限选项。能力不兼容时要求更新网页构建,不能把原生桌面 Agent 当作回退。
平台助手输入区只保留一个别针附件入口,点击直接选择附件;在输入框中粘贴文字、图片或混合内容即可添加,不需要打开菜单或主动授权读取剪贴板。附件仍在读取时暂不发送,避免文字先发而图片遗漏。权限选择和“加入队列”按钮不展示;允许的当前文档操作默认执行,旧的本地权限配置不再触发确认。项目绑定、停止操作、账号鉴权及浏览器能力限制仍独立生效。
## 请求和历史类型
```ts
type Content =
| { type: 'text'; text: string }
| { type: 'image'; mimeType: 'image/png' | 'image/jpeg'; data: string };
// image.data 是纯标准 Base64,不包含 data:image/... 前缀,不接受外链或 file_id。
type HistoryItem =
| { type: 'message'; role: 'user' | 'assistant'; content: Content[] }
| { type: 'toolCall'; callCode: string; name: string; arguments: object }
| { type: 'toolResult'; callCode: string; isError: boolean; content: Content[] };
interface CadAiRequest {
protocolVersion: 'cad-agent-v1';
documentSessionCode: string;
turnCode: string;
cadProjectCode?: string;
history: HistoryItem[];
context: { documentRevision: string; selection?: object[] };
}
```
- `documentSessionCode`、`turnCode` 为前端生成的 1~64 位字母、数字、下划线或短横线编码。每次打开文档生成文档实例编码;一条用户消息的全部工具循环共用轮次编码。
- `cadProjectCode` 可省略,未保存的空白设计也能使用。提供时必须是当前账号未删除项目;其他人、不存在或已删除统一 404。
- `documentRevision` 是当前浏览器设计的修订标记,1~128 字符。它用于前端判断迟到结果,**不是云端保存的 version**,两者不能互换。
- `selection` 最多 64 个对象,采用 makeCAD 原生上下文描述,包含实体、特征或几何元素的稳定引用及必要尺寸;不发送全部 CAD 文件、整个网格或 OSS 链接。
- 文字内容不能为空字符串。单条 content 最多 16 块;助手 message 只接受文字,用户消息和工具结果可包含图片。角色不能为 system/developer。
- 每种 history 类型只填写对应字段。工具名称、参数 Schema 以能力接口为准,前端不能提交自己的工具定义、系统指令或模型配置。
历史必须以用户消息开头,发送时以本次用户消息或全部已配对的工具结果结尾。助手文字后可以连续出现多个 `toolCall`,其结果必须按调用顺序全部回填;`callCode` 在保留的历史内唯一,不允许缺失、重复或错配。
正常顺序示例:`用户 → 助手文字(可选) → 调用 A → 调用 B → 结果 A → 结果 B → 助手 → 新用户`。工具可以只有调用而没有说明文字;一次调用失败仍回填 `isError=true`,不要删除关联调用。
完整历史由前端持有,刷新或关闭页面后不恢复。超过总量、图片数或条目数时,裁剪最早的**完整用户轮次**,不单独删除调用或结果。当前轮次本身超限时停止并提示开启新聊天。图片限制覆盖历史图片:保留当前轮次需要的图片,必要时清理整轮旧历史。
## SSE 事件和执行边界
每个事件的 data:`{code,message,data,requestId}`。成功 code 为 `OK`;心跳是 SSE 注释,不带 JSON。事件中的 data 均携带 `documentSessionCode` 和 `turnCode`。
| event | data 其他字段 | 前端行为 |
| --- | --- | --- |
| `text_delta` | `text` | 追加助手显示文本 |
| `tool_call` | `callCode,name,arguments` | 展示待执行卡片,暂不执行 |
| `completed` | `finishReason,output,usage` | 本步成功终态;output 是规范化 HistoryItem[] |
| `error` | 无其他字段,错误在包装的 code/message | 停止本轮,保留设计;不执行待确认工具 |
`completed.finishReason` 为 `stop` 或 `tool_calls`。`usage` 为 `{inputTokens,outputTokens,totalTokens}`,上游未提供时为 null。本步 `output` 是历史回填的唯一来源,不再把 text_delta 或 tool_call 额外拼进历史,避免重复。
**只有完整收到 `completed` 且 `finishReason=tool_calls` 后,才按 output 中的调用顺序执行。** 所有工具参数在上游完整结束后才会被后端验证和交付。截断、参数损坏、未知工具、拒绝、超时或断流不会产生成功 completed;显示过的文字不是执行依据。不要将模型自然语言中的伪工具调用作为命令运行。
使用带 Authorization 的 POST fetch 读取 SSE,不能使用只支持 GET 的原生 EventSource。下面的读取器处理 UTF-8 分片、跨包事件、CRLF、多行 data 及注释:
```ts
async function* readSse(response: Response) {
if (!response.ok) throw await response.json();
if (!response.headers.get('content-type')?.includes('text/event-stream') || !response.body)
throw new Error('CAD AI 未返回 SSE');
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8', { fatal: true });
let buffer = '';
try {
for (;;) {
const { value, done } = await reader.read();
buffer += decoder.decode(value, { stream: !done });
if (buffer.length > 2 * 1024 * 1024) throw new Error('SSE 事件过大');
for (;;) {
const boundary = /\r?\n\r?\n/.exec(buffer);
if (!boundary) break;
const block = buffer.slice(0, boundary.index);
buffer = buffer.slice(boundary.index + boundary[0].length);
let event = 'message';
const data: string[] = [];
for (const line of block.split(/\r?\n/)) {
if (line.startsWith('event:')) event = line.slice(6).trimStart();
if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
}
if (data.length) yield { event, envelope: JSON.parse(data.join('\n')) };
}
if (done) break;
}
} finally {
await reader.cancel().catch(() => {});
reader.releaseLock();
}
}
```
调用方还必须验证 requestId、文档和轮次关联编码,并要求成功终态;EOF 不等于完成。每次请求使用新的 AbortController,停止时 abort。读取 completed 后可以结束读取本步。
### 两步请求示例
第一步请求:
```json
{
"protocolVersion": "cad-agent-v1",
"documentSessionCode": "document-abc",
"turnCode": "turn-001",
"history": [{"type":"message","role":"user","content":[{"type":"text","text":"把宽度参数设为 40 mm"}]}],
"context": {"documentRevision":"7","selection":[]}
}
```
假设本步 SSE 为:
```text
event:tool_call
data:{"code":"OK","message":"成功","data":{"documentSessionCode":"document-abc","turnCode":"turn-001","callCode":"call_a","name":"set_parameter","arguments":{"name":"width","value":40}},"requestId":"req-a"}
event:completed
data:{"code":"OK","message":"成功","data":{"documentSessionCode":"document-abc","turnCode":"turn-001","finishReason":"tool_calls","output":[{"type":"toolCall","callCode":"call_a","name":"set_parameter","arguments":{"name":"width","value":40}}],"usage":null},"requestId":"req-a"}
```
确认文档仍然有效后执行 `set_parameter`,将 completed.output 和结果依次加入原 history,再次 POST:
```json
{
"protocolVersion":"cad-agent-v1",
"documentSessionCode":"document-abc",
"turnCode":"turn-001",
"history":[
{"type":"message","role":"user","content":[{"type":"text","text":"把宽度参数设为 40 mm"}]},
{"type":"toolCall","callCode":"call_a","name":"set_parameter","arguments":{"name":"width","value":40}},
{"type":"toolResult","callCode":"call_a","isError":false,"content":[{"type":"text","text":"{\"name\":\"width\",\"value\":40,\"errors\":[]}"}]}
],
"context":{"documentRevision":"8","selection":[]}
}
```
下一步可能继续调用工具,也可能回复并以 `finishReason=stop` 结束。工具文字结果可以是 JSON 字符串,保留实际错误;不得把失败改成成功。截图结果使用 image 块,同一 callCode 可以附带简短文字说明和图片。
## makeCAD 网页工具适配
能力接口给出的 parameters 是版本化工具 Schema 的来源。现有 `window.solidcraft` 提供 `commands()`、`execute(command,params)`、`inspect(params)` 和 `request(method,params)`。这些是底层控制入口,**不能直接把模型指定的方法名传给 request**,必须经过固定工具适配器和原生 gate。
| 工具 | 输入概要 | 网页实现及结果要求 |
| --- | --- | --- |
| `list_commands` | `filter?,prefix?,panel?,compact?,fields?,limit?,offset?` | 按原生规则筛选命令目录,支持精简字段和分页,避免超大查询结果 |
| `describe_command` | `id` | `execute('engine.describe',{command:id})`;id 是引擎命令编码,不是数据库 ID |
| `inspect_design` | `measure?,sketches?,joints?` | 基于 inspect,按原生 MCP 语义补齐所需草图及关节详情;不能只透传这些标记给 inspect 后宣称完整实现 |
| `execute` | `command,params?,verbose?,expect?` | 执行前核验命令与参数;支持原生 compact 结果和 expect 测量断言,断言失败不自动回滚设计 |
| `batch` | `commands,rollback?,coalesce_parameters?,timings?,profile?,verbose?,expect?` | 使用原生 batch 映射和 checkpoint/回滚逻辑,最多 10000 步,与原生 MCP 上限一致;请求正文和工具结果仍受字节配额限制;支持可映射的 set_parameter、measure 等步骤;不允许嵌套 batch |
| `measure` | `body?,items?,names_only?,summary?` | 复用 `inspect.measure` 及原生筛选/精简逻辑,items 最多两个;返回尺寸、体积、面积、包围盒等 |
| `body_topology` | `body,faces?` | 读取 model.edges/model.faces;faces=cylinders 时按原生逻辑合并圆柱面,不能直接返回全部面假冒合并结果 |
| `set_parameter` | `name,value或expression,unit?,comment?` | 映射 parameters.change,value/expression 为别名;返回求值和重建错误 |
| `check_parameters` | `set,report?` | 按原生 MCP 的试值、检查、精确恢复逻辑实现,包含 undo 历史;返回 restored,恢复失败必须标为错误并停止本轮 |
| `screenshot` | `view或camera?,width?,height?,source?,grid?,axes?` | 只捕获 CAD 画布或模型视图;不捕获平台页面/聊天栏,不写磁盘;压缩为 PNG/JPEG content,view/camera 二选一 |
| `undo` | `{}` | 只能撤销本轮已经完成的修改,不能越过本轮起点 |
| `skill_reference` | `skill,file?` | 从浏览器 WASM 内置资源读取技能,默认 `SKILL.md`;技能和文件必须成对存在于打包目录,拒绝任意文件路径;只读,不放入 batch |
原生工具实现可参考 makeCAD 的 `crates/mcp/src/tools.rs` 和 `crates/ui-egui/src/agent_chat`,但桌面的 CLI/MCP 进程和系统钥匙串不能搬进浏览器。网页 `ChatBackend` 要使用异步 fetch 和事件队列,不阻塞绘制;面板的文本、工具卡和停止操作继续接入现有事件模型。
后端拒绝已知的文件、设置、跨文档命令,并验证工具外层参数;它没有浏览器的实时命令注册表,因此**前端仍须检查 execute/batch 的每一条实际命令及其嵌套参数**。只允许当前文档内的建模、检查、参数和视图操作,禁止文件路径、打开/替换设计、导出保存、跨文档和应用设置;几何 path 与文件路径按原生规则区分,无法确定时拒绝。直接 execute edit.undo 等命令也必须遵守撤销边界。
### 共享生成流程与技能资源
MCP、桌面助手和网页托管助手共用 CAD 仓库的 `skills/agent-workflow.md` 生成流程:先理解意图和已有设计,读取相关技能,计算参数、位置及阶段预期值,再分批建模、测量、检查参数变化,最后报告实际验证结果。模糊需求的处理依照共享流程;只有会实质改变用途或几何结果的缺失信息才需要澄清,其余使用明确说明的合理假设。
`skills/` 中的 17 个技能全部可通过 `skill_reference` 读取,并在系统指令中提供名称、用途和可用文件目录。技能按任务渐进加载,不把全部正文塞进每次请求:新零件读取 `makecad-modeling`,改现有设计读取 `makecad-editing`,建模和修改配合 `makecad-checking`,装配和运动读取 `makecad-mechanisms`;开发、排障、测试等任务读取相应技能。开发类技能中的终端、文件或发布示例不会扩大浏览器权限。
后端打包资源为 `vibemake-service/src/main/resources/cad/ai/skills.json`,由 CAD 仓库的 `scripts/sync-cad-ai-skills.mjs` 从相同源文件生成,包含共享流程、全部技能文件及修订摘要。更新源技能后重新同步,并用该脚本的 `--check` 模式检查后端资源是否一致,然后同时构建后端和 WASM。后端启动时验证资源结构,输出技能修订摘要和数量日志;资源缺失或非法时启动失败,避免静默退回无技能模式。能力接口仍使用 `cad-agent-v1`,新增只读工具后共 12 个工具;允许的技能名和文件由打包资源生成 Schema,后端还校验二者的对应关系。
在 CAD 仓库根目录执行(两个仓库为相邻目录时):
```sh
node scripts/sync-cad-ai-skills.mjs ../community
node scripts/sync-cad-ai-skills.mjs --check ../community
```
产品文案使用 makeCAD,技能名使用 `makecad-*`。`window.solidcraft` 等既有桥接标识保留技术兼容。共享流程和技能一致不等于不同模型必然产生相同结果;模型、采样配置、上下文和引擎版本也需要对齐,并以实际工具结果验收。
## 工具循环、取消、重试和保存
每个文档同一时刻只运行一个 Agent 轮次。前端执行器需要:
1. 固定当前文档实例、轮次、修订标记和撤销起点,开始累计模型调用数及修改命令数。
2. 发出一步请求并显示文字及待执行卡片,收到完整 completed 后才交付工具。
3. 检查文档与轮次仍然有效,按顺序串行执行;每次自身修改成功后更新预期本地修订。
4. 用 `(documentSessionCode,turnCode,callCode)` 缓存执行结果,重复收到同一调用返回缓存,不再次修改。
5. 将本步 output 和完整结果加入历史,再推进下一步。达到能力限制时停止循环并提示用户继续发起新消息;batch 按实际修改命令数计入 24 条上限。
6. 收到 stop 后结束本轮,合并为一个撤销组,显示可撤销的实际修改数量。
The browser can recover a failed model request within the current task: at most two retries per request and six retries per task, after one and two seconds. The backend never retries internally. `CAD_AI_TIMEOUT`, explicitly transient `CAD_AI_PROVIDER_FAILURE`, and `CAD_AI_INVALID_MODEL_TOOL` errors are recoverable. Stop, account/project changes and manual design edits still cancel recovery. Authentication, denied access, input/protocol incompatibility, stale context, rate/concurrency limits and output limits remain terminal.
For a rejected model tool response, SSE `data.retryable` is `true` and `data.correction` contains bounded validator data, for example `{"tool":"batch","rule":"required","path":"$.commands[0].params"}`. The next request may carry this object as `context.modelRecovery`. `tool` matches `[A-Za-z][A-Za-z0-9_]{0,63}`, `rule` matches `[a-z][a-z0-9_]{0,63}`, and `path` is at most 256 characters with only `$`, dot-separated property identifiers, `.*` and numeric array indices. Unknown or unsafe diagnostics fall back to `{"tool":"unknown","rule":"invalid_tool","path":"$"}`. No raw arguments or model text are returned in diagnostics.
Recovery adds controlled correction guidance to the provider prompt without changing model settings or dropping history, reasoning, images or successful tool results. Only a fully validated response can execute tools. Rejected calls do not enter committed history, and previously completed calls are never replayed. An uncertain execution outcome must be inspected before continuing. Disable the account-scoped engine preference `agent_model_recovery` to restore immediate failure.
取消、超时、切换文档或新聊天时废弃轮次,并取消网络及所有未执行任务。正在内核运行的单次命令可能无法立即中断,必须等其状态确定后才允许新轮次开始;迟到的模型回复不能进入新文档。保留已完成修改,不自动恢复旧快照。继续保留聊天时,给已交付但未执行的调用补齐 `isError=true` 的“本轮已停止,未执行”结果;实际执行状态不确定的结果明确标记,禁止自动继续。
用户手动建模造成修订变化时停止当前轮次,避免在旧上下文上继续修改。停止后可撤销本轮修改;如果之后已经有手动或新 AI 修改,禁用旧消息的“撤销这些更改”,使用正常撤销历史处理。
AI 修改后只标记为未保存。执行本轮期间暂停云端保存,正常结束或停止后使用既有 `.sc` 上传、确认接口,确认成功才显示云端已保存。保存过程中的版本冲突仍按工作空间规则处理。401 后保留本地设计,登录恢复后核对账号和项目归属再继续。
## 错误和部署配置
| HTTP / code | 处理 |
| --- | --- |
| 400 BAD_REQUEST / CAD_AI_INVALID_HISTORY / CAD_AI_INVALID_TOOL | 修复请求、历史对应关系、图片或工具参数 |
| 401 UNAUTHORIZED | 保留设计,恢复登录;清理其他账号的请求与会话 |
| 404 NOT_FOUND | 项目不存在、非本人或已删除,停止对该项目继续请求 |
| 409 CAD_AI_PROTOCOL_MISMATCH | 更新编辑器与工具适配器 |
| 413 REQUEST_TOO_LARGE / CAD_AI_INPUT_TOO_LARGE | 压缩截图、精简工具查询或裁剪完整历史轮次 |
| 429 CAD_AI_RATE_LIMITED / CAD_AI_BUSY | 按 Retry-After 等待,不自动重放建模 |
| 502 CAD_AI_PROVIDER_FAILURE | 模型输出或服务异常,保留设计和已知执行结果 |
| 502 CAD_AI_INVALID_MODEL_TOOL | Recoverable model tool validation failure; no tool from this rejected response ran. Preserve prior modifications and send `data.correction` as `context.modelRecovery` on the next model request. |
| 502 CAD_AI_OUTPUT_LIMIT | 单次模型输出达到预算,不执行不完整工具调用,保留设计;分阶段生成或提高 CAD_AI_MAX_OUTPUT_TOKENS |
| 503 CAD_AI_UNAVAILABLE / REDIS_UNAVAILABLE | 功能未开启、配置不全或依赖不可用 |
| 504 CAD_AI_TIMEOUT | Recover the model request within the task's retry budget; preserve completed modifications. |
| SSE error 的其他 code | 展示 message,保留设计并停止本轮 |
SSE 已建立后的错误以 error 事件返回,HTTP 仍可能是 200。服务端在客户端断开、超时和关停时取消上游并关闭响应体;并发许可在工作线程退出后释放,避免上游未停就接入更多任务。
```yaml
vibemake:
cad:
ai:
enabled: ${CAD_AI_ENABLED:false}
provider: ${CAD_AI_PROVIDER:doubao}
model: ${CAD_AI_MODEL:}
request-timeout: ${CAD_AI_REQUEST_TIMEOUT:300s}
max-output-tokens: ${CAD_AI_MAX_OUTPUT_TOKENS:16384}
heartbeat-interval: 10s
max-concurrent: ${CAD_AI_MAX_CONCURRENT:4}
requests-per-minute: ${CAD_AI_REQUESTS_PER_MINUTE:30}
max-model-calls-per-turn: ${CAD_AI_MAX_MODEL_CALLS_PER_TURN:12}
max-changes-per-turn: ${CAD_AI_MAX_CHANGES_PER_TURN:24}
```
CAD 模型连接使用独立的 `vibemake.cad.ai.providers` 配置,不读取或修改社区助手的 `AiProperties`。本地在 `.env` 中设置 `CAD_AI_PROVIDER=openai|doubao|deepseek` 后重启后端,并刷新 CAD 页面、开始新对话。前端仍使用平台指定的模型,Key 只保留在后端,浏览器不能指定任意服务地址。社区助手继续使用原有 `AI_*` 和 `ARK_*` 配置。
| CAD 配置 | OpenAI | 豆包 | DeepSeek |
| --- | --- | --- | --- |
| Key | `CAD_AI_OPENAI_API_KEY` | `CAD_AI_DOUBAO_API_KEY` | `CAD_AI_DEEPSEEK_API_KEY` |
| 模型 | `CAD_AI_OPENAI_MODEL` | `CAD_AI_DOUBAO_MODEL` | `CAD_AI_DEEPSEEK_MODEL` |
| 完整请求地址 | `CAD_AI_OPENAI_ENDPOINT`,以 `/responses` 结尾 | `CAD_AI_DOUBAO_ENDPOINT`,方舟 `/responses` | `CAD_AI_DEEPSEEK_ENDPOINT`,以 `/chat/completions` 结尾 |
| 思考程度 | `CAD_AI_OPENAI_REASONING_EFFORT`,默认 `high` | `CAD_AI_DOUBAO_REASONING_EFFORT`,默认 `default` | `CAD_AI_DEEPSEEK_REASONING_EFFORT`,默认 `default` |
| 思考开关 | 由所选模型支持的 effort 决定 | `CAD_AI_DOUBAO_THINKING=enabled|disabled` | `CAD_AI_DEEPSEEK_THINKING=enabled|disabled` |
`default` 表示不发送思考程度参数,其余值必须由实际模型支持,后端不自动降级或回退服务。OpenAI 发送 `reasoning.effort`,不发送方舟专用的 `thinking`;豆包默认保持原有 `thinking.type=enabled`;DeepSeek 发送 Chat Completions 的 `thinking` 与可选 `reasoning_effort`。可选的 `CAD_AI_OPENAI_USER_AGENT` 仅用于兼容需要特定 HTTP 客户端标识的网关,不影响社区助手。未设置独立豆包 Key 时,配置文件为旧部署保留 `ARK_API_KEY` 环境变量的读取兼容;其他两个服务不使用此回退。建议给三个 CAD profile 均填写独立 Key。旧的 `CAD_AI_MODEL` 仍作为 CAD 专用覆盖项保留;使用 profile 模型时应移除或留空,空值不会再沿用社区 `ARK_MODEL`。
OpenAI 和豆包保持原来的 Responses 工具、系统文本、17 个技能和浏览器循环,`store=false`,并请求 `include=["reasoning.encrypted_content"]`。`reasoning:[{id,encryptedContent}]` 用于无状态续调;DeepSeek 则使用可选 `reasoningContent` 保留同一对话的工具续调状态。两者均不作为可见回复或工具解释;用户 message 和 toolResult 不能注入这些字段。供应商状态不兼容时返回 `CAD_AI_PROVIDER_HISTORY_MISMATCH`,需要开始新对话。
DeepSeek 默认文本模型不支持图片,因此不在其能力目录中提供 `screenshot` 工具;带图片的旧历史或附件返回 `CAD_AI_IMAGE_UNSUPPORTED`,不会静默丢掉图片。OpenAI、豆包的图片能力仍取决于所配置模型和网关。能力接口增加 `provider`、`reasoningEffort`、`thinking` 和 `maxOutputTokens`,便于核对实际后端配置,绝不返回地址或 Key。
单次模型输出预算默认为 16384 token,可通过 CAD_AI_MAX_OUTPUT_TOKENS 配置(1024–65536,所选模型还必须支持该值)。该预算包含思考 token 和可见输出,与 300 秒请求超时独立。输出触顶的 response.incomplete 不作为成功,也不执行其中的不完整工具调用。
频率限制通过 Redis 共享,每次推理请求(含续调)计数;模型并发上限按后端实例计算。12 次推理和 24 条修改是网页执行器每个用户轮次的限制,后端能力接口提供该值,不持久跟踪浏览器的整轮操作。日志仅记录关联编码、模型、耗时、用量及错误,不能增加完整聊天或 Base64 调试输出。
网关仅对该 POST 接口允许 4 MiB 请求体,关闭 SSE 缓冲及缓存,读取超时大于模型请求超时并留出余量(默认建议 330 秒)。后端设置 X-Accel-Buffering:no,并每 10 秒发送心跳;具体网关仍需对应配置。其他接口正文配额不变,不改 OSS 或数据库。
上线顺序:部署后端且 CAD_AI_ENABLED=false → 前端适配 → 测试环境启用并完成真实模型联调 → 验收后生产启用。关闭开关会拒绝新请求;已经开始的请求按原有超时或客户端停止结束。必须使用已开通且支持工具调用和图片理解的模型。
## 联合验收清单
- 同一平台账号进入空白设计或本人项目,可以连续聊天、建模和修改参数,其他用户和删除项目不可访问。
- 工具卡显示真实结果,截图和选区能够进入模型上下文;工具执行前必须等到成功终态。
- 一条消息对应一个撤销组;停止后无后续排队命令,后续编辑不会被旧消息撤销覆盖。
- 切换文档、断流、请求重试和重复事件不会执行到错误文档或重复建模。
- 手动保存后刷新并重新打开 `.sc` 仍能编辑;聊天不恢复;AI 失败与登录过期不丢失本地修改。
- 浏览器构建及 API 响应中没有模型密钥;真实豆包工具调用、识图和流式输出均验证通过。
自动化模型替身和 HTTP 模拟服务覆盖后端协议及故障场景,不代表上述 makeCAD 网页适配已经完成,也不替代真实模型、撤销和云端保存联调。
后端提供默认跳过的 `ArkCadAiLiveTest`,验证当前配置模型的原生工具调用,以及 screenshot 图片结果回填后的识图。它只发送公开提示和生成的红色矩形图片,不读取真实 CAD。部署前安全注入 `CAD_AI_PROVIDER` 和所选 profile 的 `CAD_AI_<PROVIDER>_API_KEY/MODEL/ENDPOINT/REASONING_EFFORT` 后显式运行(会产生模型调用费用;图片测试仅适用于支持图片的模型):
另有显式开启的原生 MCP 联调:同时设置 `VIBEMAKE_CAD_AI_MCP_LIVE_TEST=true` 和 `VIBEMAKE_CAD_AI_MCP_CLI`(本机原生 CLI 绝对路径),可运行 `configuredModelAndNativeMcpAcceptTheAlignedBatchAndQuerySchemas`,验证真实模型发出的 25 步批量调用及分页查询由原生引擎接受。`publicSheetMetalPromptUsesValidatedToolsAgainstAnIsolatedNativeDesign` 使用公开钣金提示,在新的无界面设计中最多探测 20 次模型调用,仅用于协议排障,不代表最终几何或全部钣金要求验收通过;这些探测不读取或修改用户当前设计。
```sh
VIBEMAKE_CAD_AI_LIVE_TEST=true mvn -pl vibemake-service -am \
-Dtest=ArkCadAiLiveTest -Dsurefire.failIfNoSpecifiedTests=false test
```
这两项通过后,仍需完成浏览器内实际建模、撤销和云端保存联调。
-194
View File
@@ -1,194 +0,0 @@
# CAD 个人工作空间前端对接
网页 AI 助手使用独立的 `/api/cad/ai` 接口,复用平台登录,工具由浏览器执行;接口、工具循环、停止及撤销适配见 [CAD Web AI Agent 对接](frontend-cad-ai-agent.md)。AI 修改仍通过本文的原生 `.sc` 流程手动保存。
CAD 与 Vibemake 共用 `/api/auth/login`、`/api/auth/logout` 和 `/api/users/me`,使用同一个 `Authorization: Bearer <平台 token>`。CAD 工作空间使用独立的列表和保存接口,不创建 Git 仓库、不自动发布社区;可独立创建,也可从 `/api/workspace/projects` 中带 STEP 的本人项目创建关联。云端保存只支持当前用户的单个自包含原生 `.sc` 设计文件,不管理外部引用的多文件装配;STEP 仅作为前端首次导入来源。
文件沿用现有 OSS 资源规则:上传继承 Bucket 权限,读取使用 `OSS_PUBLIC_BASE_URL` 对应的普通 OSS/CDN 地址。工作空间和平台接口按用户隔离,文件直链的访问权限由现有 Bucket/CDN 配置决定;公开配置下,拿到直链即可读取文件。
数据库的当前文件和上传批次只保存 `/cad-projects/{项目编码}/{批次编码}/design.sc`,不含环境前缀;上传签名的 `formFields.key` 和实际访问地址仍包含当前环境根目录,前端原样使用。所有资源的存储规范及历史数据转换 SQL 见 [OSS 引用规范](oss-storage-paths.md)。
通用响应、上海时间格式、分页和跨域规则沿用 [Vibemake 接入约定](vibemake-api.md#接入约定)。CAD 所有接口返回 `Cache-Control: no-store`。业务编码为不透明字符串,不使用数据库 ID。
## 接口与数据
下表前缀为 `/api/cad/workspace/projects`。全部需要登录,成功均为 HTTP 200,JSON 为 `{code,message,data,requestId}`。
| 方法 | 相对路径 | 请求 | 成功 data |
| --- | --- | --- | --- |
| GET | 空 | `page=1&size=20&keyword=名称` | 项目分页 |
| POST | 空 | `{name,description?,coverUrl?}` | 项目 |
| GET | `/{cadProjectCode}` | 无 | 项目 |
| PATCH | `/{cadProjectCode}` | `{name?,description?,coverUrl?}` | 项目 |
| DELETE | `/{cadProjectCode}` | 无 | null |
| POST | `/{cadProjectCode}/uploads/signature` | `{fileName,sizeBytes,expectedVersion}` | 上传签名 |
| PUT | `/{cadProjectCode}/document` | `{uploadCode}` | 保存回执 |
| GET | `/{cadProjectCode}/document` | 无 | 文件读取信息 |
名称必填,去除首尾空白后 1~100 字符;描述最多 2000 字符,新建时默认空字符串。`coverUrl` 可选,传完整 HTTPS 地址,最多 2048 字符;新建省略、null 或空白表示没有封面。PATCH 省略或 null 表示保留,描述或封面传 `""` 可清空,至少提供一个非 null 字段。
项目:
```ts
interface CadProject {
cadProjectCode: string;
workspaceProjectCode: string | null; // 关联的当前工作区项目编码,独立项目为 null
initialStep: CadInitialStep | null; // 创建关联时固定的 STEP 来源,保存 .sc 后仍保留
name: string;
description: string;
coverUrl: string | null; // 完整 OSS/CDN 地址,无封面为 null
hasDocument: boolean;
version: number;
fileName: string;
sizeBytes: number;
savedAt: string | null;
createdAt: string;
updatedAt: string;
}
interface CadInitialStep {
downloadUrl: string; // 普通 OSS/CDN 地址,无临时签名
fileName: string; // 保留原始 STEP/STP 文件名、中文和大小写
sizeBytes: number;
}
interface CadUploadSignature {
uploadCode: string;
uploadUrl: string;
formFields: Record<string, string>;
expiresAt: string;
}
interface CadSaveResult {
cadProjectCode: string;
version: number;
savedAt: string;
}
interface CadDocument {
downloadUrl: string;
expiresAt: null;
version: number;
fileName: string;
sizeBytes: number;
}
```
新项目 `hasDocument=false、version=0、fileName=""、sizeBytes=0、savedAt=null`,未提供封面时 `coverUrl=null`。独立创建的项目 `workspaceProjectCode=null、initialStep=null`;有关联的 STEP 不代表已经保存了 `.sc`。列表、详情、创建及修改结果均包含相同的封面、关联编码和初始 STEP 字段。列表只包含本人未删除项目,按最近更新时间倒序;支持名称包含搜索。`page` 为 1~100000,`size` 为 1~100,默认 20,返回 `{items,page,size,total}`。同名项目允许存在。改名、描述和封面修改不改变文件保存版本或 savedAt。
## 从个人空间 STEP 项目进入编辑器
本人工作区项目详情中,`repoStatus === 'READY'` 且 `stepMainUrl` 非空时显示“编辑”。Fork 已复制 STEP 路径、文件名和大小,因此使用 Fork 后当前用户的 `projectCode`,不使用上游来源项目编码。
点击后调用以下接口,无请求体,平台 Token 放在 Authorization 请求头:
```http
POST /api/workspace/projects/{projectCode}/cad-project
```
成功 HTTP 200,`data` 为上述 `CadProject`,响应 `Cache-Control: no-store`。前端使用返回的 `cadProjectCode` 进入现有 CAD 编辑器路由,不把 Token 放 URL。首次创建继承当前项目的名称、描述、封面及 STEP 引用;重复点击、请求超时重试或多标签页并发均复用同一个有效关联,不自动重复创建。不同用户的 Fork 各自创建关联 CAD。请求使用 `cad-read` 限流,实际创建额外使用 `cad-create`,复用不消耗创建额度。
编辑器按以下顺序打开,包括直接从 CAD 工作空间进入的情况:
1. 读取 `GET /api/cad/workspace/projects/{cadProjectCode}` 的最新详情。
2. `hasDocument=true` 时使用 `GET .../{cadProjectCode}/document` 下载 `.sc` 并打开,以 `document.version` 作为编辑基础版本。读取失败显示错误并允许重试,不自动退回 STEP,避免用户误以为已有编辑丢失。
3. `hasDocument=false` 且 `initialStep` 非空时,fetch `initialStep.downloadUrl`,将原始文件字节和 `fileName` 交给编辑器的 STEP/STP 导入能力。导入失败保留同一个关联,提供重试;不创建新 CAD。
4. 导入成功后视为尚未云端保存,首次保存由前端导出完整 `.sc`,使用 `expectedVersion=0` 走原有上传签名与确认流程。后端不解析或转换 STEP,不把 STEP 当作已保存的原生文档,原生上传接口仍只接受 `.sc`。
5. `hasDocument=false` 且 `initialStep=null` 时进入普通空设计。
`initialStep` 固定为创建关联时的引用;工作区 STEP 替换或移除、名称描述封面变更均不覆盖已有关联 CAD,也不回写原工作区项目。后续保存的 `.sc` 是重新打开时的首选。STEP 的默认资源上限为 500 MiB,原始文件名最多 1024 字符;不套用 `.sc` 的 256 MiB 和 255 字符限制,前端需按编辑器实际能力处理导入错误,导出 `.sc` 后仍受 CAD 保存大小限制。
无关联且当前项目无 STEP 返回 `409 PROJECT_STEP_NOT_FOUND`;仓库未 READY 返回 `409 CONFLICT`;项目非本人、不存在或已删除返回 `404 NOT_FOUND`。已有关联时,即使 STEP 已移除,直接调用关联接口仍返回原 CAD;页面不再显示该“编辑”入口,用户仍可从 CAD 工作空间进入。
删除工作区项目不删除 CAD,已有 CAD 可独立打开和继续保存;删除 CAD 会释放关联,工作区仍有 STEP 时再次“编辑”创建新 CAD。删除前的 CAD 编码继续不可访问,不提供恢复。
## 项目封面
复用 [已有封面上传](vibemake-api.md#项目封面与-oss-直传) 的 `POST /api/uploads/project-covers/signature`,无需 CAD 项目编码,也不会创建 Git 项目。请求 `{contentType,fileSize}`,支持 JPG、PNG、WebP,最大 5 MiB;使用同一平台 Token 申请签名,取得 `uploadUrl、formFields、coverUrl`。
将全部 formFields 和图片通过 FormData 直传 OSS,不携带平台 Token。上传成功后,将签名返回的完整 `coverUrl` 放入新建请求,或提交 `PATCH /api/cad/workspace/projects/{cadProjectCode}`:
```json
{"coverUrl":"https://你的OSS或CDN域名/vibemake_dev/project-covers/用户编码/日期/文件名.png"}
```
封面上传遵循现有 `OSS_ENABLED` 开关和 OSS 规则;CAD 的 `.sc` 独立存储开关不代替封面上传开关。可以由前端截取 CAD 画布生成图片,后台不自动生成或更新封面。
平台托管封面在数据库 `cad_project.cover_url` 中保存 `/project-covers/...` 等无环境前缀的未编码路径;列表、详情和创建/修改结果中的 coverUrl 自动补当前环境前缀及 OSS/CDN 地址。沿用现有封面规则接受外部 HTTPS 图片链接并原样保存,不接受直接提交数据库相对路径。
只修改封面不更新 `.sc` 文件或版本,保存 `.sc` 也不会清空封面。换图、清空封面和删除 CAD 项目均不删除旧 OSS 图片。已有数据库部署前先执行 [CAD 封面增量 SQL](cad-database.md#已有数据库增加-cad-项目封面)。
## 保存和重新打开
1. 独立新设计首次保存先创建项目,保留返回的 `cadProjectCode` 和 `version=0`;从工作区进入的关联 CAD 直接复用返回的项目编码,不再创建空项目。
2. 使用 SolidCraft 原生序列化生成完整 `.sc`,不能仅上传 STL、STEP、GLB 或显示网格;原生文件保留参数及可编辑设计。需要由前端接通原生文件导出和导入桥接,当前本机/浏览器保存不等于云端保存。
3. 文件名须为不含路径和控制字符的 `.sc` 名称,最多 255 字符。文件非空,默认上限 268435456 字节(256 MiB)。`sizeBytes` 和 `expectedVersion` 必须是 JSON 整数,不接受字符串或小数。
4. 申请签名,将 `formFields` 全部原样写入 FormData,最后追加 `file`,POST 到 `uploadUrl`。不携带平台 Authorization,不手写 multipart Content-Type。OSS 成功为 HTTP 200,无需解析 JSON。
5. 上传完成后提交原 `uploadCode` 确认。后端核验对象大小、批次归属、截止时间和基础版本,成功才更新当前设计引用,并返回新版本。
6. 只有确认成功才显示云端已保存;序列化期间及上传期间又产生的修改仍应标为未保存。每个项目前端串行执行云端保存。
7. 打开项目先读详情;`hasDocument=true` 时 GET `document`,fetch `downloadUrl` 得到原始文件字节并交给 SolidCraft 打开;未保存且有 `initialStep` 时按上节导入 STEP,普通空项目进入新设计。**本次编辑基础版本使用 `document.version`**,文件与版本来自同一快照,不混用先前详情中的版本。
上传签名默认 15 分钟,未确认批次同一时刻过期;文件上传完成但确认已过期时,重新申请批次。`downloadUrl` 为普通 OSS/CDN 文件地址,不附加临时下载签名,`expiresAt` 为兼容前端保留且固定返回 null;前端直接读取地址,不做下载签名续期。业务时间为上海时间字符串,无时区后缀,解析时补 `+08:00`。
相同 `uploadCode` 重复确认返回首次保存回执,不重复增加版本。即使之后已有更新版本,重试旧批次也不会恢复旧文件;回执版本可能小于最新项目版本,需要时重新读取详情。网络超时先保留原批次并重试确认,不直接创建新项目或新批次。上传使用现有 `signObject` 策略及其禁止覆盖参数,每次申请使用新的批次对象键;OSS 上传超时先尝试确认,缺文件再处理上传,不无条件重复上传。
两个标签页使用相同基础版本保存时,只有一个成功,另一个收到 `CAD_VERSION_CONFLICT`。保留本地修改并提供重新打开最新设计、下载本地副本或另存新项目的处理入口;不能只换成最新版本号后自动覆盖。
离开、切换项目、退出登录前提示未保存修改。401 后保留设计并引导重新登录,重新登录后核对当前账号和项目归属再继续保存。推荐部署同源的可编辑 SolidCraft 构建;iframe 跨源集成如使用 postMessage,须校验 source 和精确 origin,平台 Token 不放 URL。现有 `?embed` 会关闭浏览器持久化等能力,不能直接充当云端保存桥接。
## 错误处理
| HTTP / code | 处理 |
| --- | --- |
| 400 `BAD_REQUEST` / `CAD_INVALID_FILE` | 校验名称、描述、文件和整数参数 |
| 401 `UNAUTHORIZED` | 保留本地修改,恢复登录 |
| 404 `NOT_FOUND` | 非本人、不存在或已删除的项目/批次,停止对此项目保存 |
| 404 `CAD_DOCUMENT_NOT_FOUND` | 空项目尚未保存文件 |
| 409 `PROJECT_STEP_NOT_FOUND` | 工作区项目无 STEP 且无有效关联,刷新项目详情 |
| 409 `CONFLICT` | 工作区项目仓库未就绪,核对创建或 Fork 状态 |
| 409 `CAD_VERSION_CONFLICT` | 保留修改,处理并发冲突 |
| 409 `CAD_FILE_MISSING` | 尚未上传完整,检查 OSS 上传结果后重试确认 |
| 409 `CAD_FILE_SIZE_MISMATCH` | 当前文件不变,重新申请并上传正确文件 |
| 409 `CAD_UPLOAD_EXPIRED` | 重新申请上传批次 |
| 413 `CAD_FILE_TOO_LARGE` / `REQUEST_TOO_LARGE` | 文件超限或 JSON 超限,调整请求 |
| 429 `RATE_LIMITED` | 按 Retry-After 等待后重试 |
| 502 `CAD_OSS_ERROR` | 保留当前设计及批次,稍后重试 |
| 503 `CAD_STORAGE_UNAVAILABLE` / `CAD_STORAGE_UNSAFE` | 存储未开启或本地 OSS 连接参数不完整,联系管理员 |
| 503 `CAD_CODE_BUSY` / `REDIS_UNAVAILABLE` | 暂时无法处理,保留输入后重试 |
删除为逻辑删除,之后列表、详情、文件地址获取、编辑及保存确认均不可访问,不提供恢复。上传失败、替换、删除均保留旧 OSS 对象,已有文件直链仍按 Bucket/CDN 规则访问,删除项目不会撤销已有直链。首期没有历史恢复和对象自动清理。
## 部署配置
先手工执行 [CAD 建表 SQL](cad-database.md),已有表先执行[工作区项目关联与初始 STEP 增量 SQL](cad-database.md#已有数据库增加工作区项目关联与初始-step),再部署后端并接入前端。CAD 与现有资源共用 `vibemake.oss` 的 Bucket、地域、Endpoint、AccessKey 和各环境根目录;`vibemake.cad.oss` 仅保留独立的 `enabled` 开关,文件存储默认关闭。关联创建及初始 STEP 地址生成不访问 OSS,不依赖 `.sc` 上传开关;云端保存仍需启用 CAD 存储。
```yaml
vibemake:
cad:
oss:
enabled: ${CAD_OSS_ENABLED:false}
```
| 配置项 | 默认值 / 要求 |
| --- | --- |
| `CAD_OSS_ENABLED` | false,配置齐全后设为 true |
| `OSS_REGION` | 与现有 OSS 共用,默认 cn-beijing |
| `OSS_ENDPOINT` | 与现有 OSS 共用,可选 HTTPS Endpoint;不填写时按地域生成 |
| `OSS_BUCKET` | 与现有资源共用同一个 Bucket |
| `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` | 与现有 OSS 共用,通过部署环境注入 |
| `OSS_PUBLIC_BASE_URL` | 与现有资源共用普通 OSS/CDN 访问基础地址,配置为空时使用 Bucket 域名 |
| `vibemake.oss.root-directory` | CAD 直接使用各环境根目录:test 为 vibemake_dev,prod 为 vibemake |
| `CAD_MAX_FILE_BYTES` | 268435456;配置范围为 1 字节至 OSS 表单上限 5 GiB,需同时兼容编辑器读取上限 |
| `CAD_UPLOAD_VALIDITY` | 默认 15m;范围 1 秒至 7 天 |
| `RATE_CAD_CREATE_PER_MINUTE` / `RATE_CAD_SIGN_PER_MINUTE` | 5 / 20,按当前用户独立限流 |
| `RATE_CAD_SAVE_PER_MINUTE` / `RATE_CAD_READ_PER_MINUTE` | 30 / 60,保存确认和文件地址读取尝试次数 |
CAD 独立开关与 `OSS_ENABLED` 分开控制:公共资源上传关闭时,只要共用连接参数完整,CAD 仍可独立开启。只有 `CAD_OSS_ENABLED` 继续生效;旧的 `CAD_OSS_BUCKET`、`CAD_OSS_REGION`、`CAD_OSS_ENDPOINT`、`CAD_OSS_ACCESS_KEY_ID`、`CAD_OSS_ACCESS_KEY_SECRET` 和 `CAD_OSS_ROOT_DIRECTORY` 均不再读取,可从 `.env` 移除。
上传签名仅在本地生成,保存确认只通过 HEAD 核验对象存在和大小;文件地址沿用现有 `OssResourcePaths.publicUrl` 规则生成。后端不查询 Bucket ACL、公共访问策略、版本控制状态或对象 ACL,不修改 Bucket 配置,也不为 CAD 单独强制 private ACL。
共用 RAM 凭据只需覆盖当前环境 `cad-projects/*` 的 `oss:PutObject`、`oss:GetObject`,分别用于普通文件上传和 HEAD 元数据读取。不额外要求 CAD 的 ACL 或 Bucket 配置读取/修改权限。不要给前端 RAM 密钥。
上传策略与原有 STEP 等资源相同,精确绑定对象键、大小、MIME、Content-Disposition 和禁止覆盖参数,不设置 `x-oss-object-acl`。文件是否公开、CDN 是否需要鉴权、同名对象覆盖行为均遵循已有 OSS/CDN 配置,应用不增加 CAD 专属限制;数据库仍校验归属、基础版本、批次截止时间和幂等回执。
旧的 `CAD_DOWNLOAD_VALIDITY` 不再读取。前端如曾按下载签名过期时间续期,需调整为直接读取普通地址,允许 `expiresAt=null`。
若此前使用独立 CAD Bucket 保存过文件,切换前需按原对象键复制到 `OSS_BUCKET`。若旧文件曾单独设为 private,且现有普通地址无法读取,需按已有资源访问方式调整为继承 Bucket(default)或配置相应的 CDN 回源授权;代码不会自动迁移文件或修改历史对象 ACL。
OSS/CDN 沿用现有 CORS 规则,允许真实编辑器来源的 POST、GET 和 Content-Type;需要时暴露 Content-Length 和 Content-Disposition。直传和文件读取不携带平台 Token。联调验证上传、确认保存、通过配置的普通 OSS/CDN 地址读取,以及原生设计重新打开后可继续编辑。API 自动化使用存储替身,不替代真实 OSS/CDN 和编辑器联调。
-128
View File
@@ -1,128 +0,0 @@
# PCB 个人工作空间前端对接
PCB 工作空间使用独立的 `/api/pcb/workspace/projects`,与 CAD 共用 `/api/auth/login`、`/api/auth/logout` 和 `/api/users/me`,使用同一个 `Authorization: Bearer <平台 token>`。个人空间提供独立 PCB 分类;列表只包含本人未删除的 PCB 项目,不创建 Git 仓库、不自动发布社区。本文约定后端接口,PCB 编辑器及宿主网页需另行接入。
每次手动保存上传一个完整工程 ZIP。数据库保存项目元数据、当前文件引用和上传回执,原理图、PCB、工程配置与工程内私有依赖由前端打包和还原。后端不解压 ZIP、不解析 KiCad 文件,也不验证 ZIP 内容是否可编辑;文件名和大小校验不能代替前端格式验证。
文件读取沿用 CAD 的普通 OSS/CDN 地址规则:平台接口按用户隔离,文件直链权限由现有 Bucket/CDN 决定。公开配置下,拿到链接即可下载。逻辑删除不会撤销已有文件链接。
## 接口与数据
下表前缀为 `/api/pcb/workspace/projects`。全部需要登录,成功 HTTP 200,响应为 `{code,message,data,requestId}`,响应包含 `Cache-Control: no-store`。分页、上海业务时间和跨域约定沿用 [Vibemake 接入约定](vibemake-api.md#接入约定)。业务编码是不透明字符串,客户端不使用数据库 ID。
| 方法 | 相对路径 | 请求 | 成功 data |
| --- | --- | --- | --- |
| GET | 空 | `page=1&size=20&keyword=名称` | `{items,page,size,total}` |
| POST | 空 | `{name,description?,coverUrl?}` | 项目 |
| GET | `/{pcbProjectCode}` | 无 | 项目 |
| PATCH | `/{pcbProjectCode}` | `{name?,description?,coverUrl?}` | 项目 |
| DELETE | `/{pcbProjectCode}` | 无 | null |
| POST | `/{pcbProjectCode}/uploads/signature` | `{fileName,sizeBytes,expectedVersion}` | 上传签名 |
| PUT | `/{pcbProjectCode}/document` | `{uploadCode}` | 保存回执 |
| GET | `/{pcbProjectCode}/document` | 无 | ZIP 文件读取信息 |
名称去除首尾空白后须为 1~100 字符,描述最多 2000 字符,新建默认空字符串。封面为完整 HTTPS 地址,最多 2048 字符,新建省略、null 或空白表示无封面。PATCH 省略或 null 表示保留;描述或封面传 `""` 可清空,至少提供一个非 null 字段。
同名项目允许存在。列表按最近更新时间倒序,同一时间按内部主键倒序稳定分页,主键不对外返回;名称支持包含搜索,关键词最多 100 字符。`page` 为 1~100000,`size` 为 1~100,默认 20。
```ts
interface PcbProject {
pcbProjectCode: string;
name: string;
description: string;
coverUrl: string | null;
hasDocument: boolean;
version: number;
fileName: string;
sizeBytes: number;
savedAt: string | null;
createdAt: string;
updatedAt: string;
}
interface PcbUploadSignature {
uploadCode: string;
uploadUrl: string;
formFields: Record<string, string>;
expiresAt: string;
}
interface PcbSaveResult {
pcbProjectCode: string;
version: number;
savedAt: string;
}
interface PcbDocument {
downloadUrl: string;
expiresAt: null;
version: number;
fileName: string;
sizeBytes: number;
}
```
空项目 `hasDocument=false、version=0、fileName=""、sizeBytes=0、savedAt=null`。名称、描述和封面修改只更新元数据,不改变文件版本或 savedAt。
## 工程 ZIP、保存和重新打开
ZIP 应保留工程原有目录和文件名,包含 `.kicad_pro`、`.kicad_sch`、`.kicad_pcb` 及工程实际使用的私有符号库、封装库、库表、3D 模型、图像等项目文件。文件按原始字节保存,二进制文件不能先解码为文本。全局标准库仍由编辑器提供;工程外的本机绝对路径依赖需由前端迁入工程并处理引用,后端不会自动收集。
PCB 前端现有“归档项目”按扩展名白名单过滤,不能直接作为完整云端保存范围。前端需先刷新所有编辑器的最新序列化结果、等待本地写入完成,再读取完整工程快照打包;不上传浏览器缓存、`.git`、工具目录和本地历史记录。解压时由前端校验路径及资源限额,完整导入成功后再切换当前工程。
1. 首次保存先创建项目,保留返回的 `pcbProjectCode` 和 `version=0`,后续上传失败复用该项目。
2. 从完整工程快照生成 ZIP。文件名为不含路径和控制字符的 `.zip` 名称,最多 255 字符,扩展名不区分大小写;文件非空,默认最大 268435456 字节(256 MiB)。
3. 申请签名,提交 ZIP 实际字节数及编辑基础版本。`sizeBytes` 和 `expectedVersion` 必须是 JSON 整数,不接受字符串、小数、负数或 null,sizeBytes 必须大于零。
4. 将所有 `formFields` 原样加入 FormData,最后追加 ZIP 文件,POST 到 `uploadUrl`。ZIP Blob MIME 使用 `application/zip`,不手写 multipart Content-Type,不携带平台 Authorization。OSS 成功为 HTTP 200,无需解析 JSON。
5. 上传后提交原 `uploadCode` 确认。只有成功回执才能显示云端已保存;同一项目串行保存,打包或上传期间的新修改继续标记为未保存。
6. 打开先读详情;空项目进入新工程,否则获取 `document`,fetch `downloadUrl` 得到 ZIP 并交给编辑器导入。**编辑基础版本使用 document.version**,不能混用此前详情的版本。
本期为手动云端保存,宿主保存按钮和 Ctrl+S 应接入上述链路。本地自动保存继续作为浏览器内恢复能力,不能显示为云端已保存。iframe 集成由宿主网页和编辑器完成;使用 postMessage 时校验精确 origin 与 source,平台 Token 不放 URL,直传和 OSS 文件读取不携带平台 Token。
签名及未确认批次默认 15 分钟后过期。业务时间采用上海时间、无时区后缀,前端解析时补 `+08:00`。下载地址为普通 OSS/CDN 地址,expiresAt 固定为 null,不需要下载签名续期。
相同 uploadCode 重复确认返回首次成功的 version 和 savedAt,不重复增加版本;即使已有更新版本,也不会重新绑定旧 ZIP。回执版本可能小于当前版本,需要时重新读项目。确认超时应保留原批次并重试确认;OSS 上传结果不明确时也先尝试确认,缺文件再处理上传,不盲目覆盖或重复创建项目。
两个标签页基于同一版本保存,仅一个成功,另一个收到 `PCB_VERSION_CONFLICT`。保留本地修改,提供重新打开最新工程、下载本地 ZIP 或另存项目入口,不能自动替换版本号后覆盖。401 时保留本地工程,重新登录后核对账号与归属;离开、切换工程、退出登录前处理未保存修改。
## 封面与错误处理
封面复用 `POST /api/uploads/project-covers/signature`,请求 `{contentType,fileSize}`,支持 JPG、PNG、WebP,最大 5 MiB。取得签名后直传图片,将完整 `coverUrl` 提交至 PCB 创建或 PATCH 接口;无需先创建 Git 项目。封面上传使用已有 `OSS_ENABLED` 开关,PCB 文件开关不代替它。
平台封面落库为 `/project-covers/...` 等环境相对路径,接口返回完整 URL;外部 HTTPS 图片沿用已有规则。工程保存保留封面,更新封面不改变工程版本;替换或清空封面、删除项目均保留原 OSS 对象。
| HTTP / code | 处理 |
| --- | --- |
| 400 `BAD_REQUEST` / `PCB_INVALID_FILE` | 检查元数据、ZIP 文件名及整数参数 |
| 401 `UNAUTHORIZED` | 保留工程,恢复登录后核对账号 |
| 404 `NOT_FOUND` | 项目或批次不存在、非本人或已删除,停止保存 |
| 404 `PCB_DOCUMENT_NOT_FOUND` | 空项目尚无云端 ZIP |
| 409 `PCB_VERSION_CONFLICT` | 保留本地修改,处理并发冲突 |
| 409 `PCB_FILE_MISSING` | 尚无上传对象,检查上传结果再重试确认 |
| 409 `PCB_FILE_SIZE_MISMATCH` | 当前文件不变,重新申请并上传正确文件 |
| 409 `PCB_UPLOAD_EXPIRED` | 重新申请批次 |
| 413 `PCB_FILE_TOO_LARGE` / `REQUEST_TOO_LARGE` | 文件或 JSON 请求超限 |
| 429 `RATE_LIMITED` | 按 Retry-After 等待后重试 |
| 502 `PCB_OSS_ERROR` | 保留工程及批次,稍后重试 |
| 503 `PCB_STORAGE_UNAVAILABLE` / `PCB_STORAGE_UNSAFE` | 存储未开启或连接不完整 |
| 503 `PCB_CODE_BUSY` / `REDIS_UNAVAILABLE` | 暂时无法处理,保留输入后重试 |
## 部署与联调
先手工执行 [PCB 建表 SQL](pcb-database.md),再部署后端,配置当前环境 `pcb-projects/*` 的 RAM 权限及 OSS/CDN CORS,最后开启 PCB 存储。应用不自动创建或修改业务表,回滚时保留两张表和已有 OSS 对象。
| 配置项 | 默认值 / 要求 |
| --- | --- |
| `PCB_OSS_ENABLED` | false,配置完成后显式开启 |
| `PCB_MAX_FILE_BYTES` | 268435456;允许 1 字节至 5 GiB,需兼容编辑器读取限额 |
| `PCB_UPLOAD_VALIDITY` | 15m,允许 1 秒至 7 天 |
| `RATE_PCB_CREATE_PER_MINUTE` / `RATE_PCB_SIGN_PER_MINUTE` | 每用户 5 / 20 |
| `RATE_PCB_SAVE_PER_MINUTE` / `RATE_PCB_READ_PER_MINUTE` | 每用户 30 / 60,含确认及读取重试 |
| `OSS_REGION、OSS_ENDPOINT、OSS_BUCKET、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET` | 共用现有 OSS 连接,前端不持有 RAM 密钥 |
| `OSS_PUBLIC_BASE_URL` | 共用普通 OSS/CDN 基础地址;为空时使用 Bucket 域名 |
| `vibemake.oss.root-directory` | test 为 vibemake_dev,prod 为 vibemake |
PCB 开关独立于 CAD 和公共资源开关;`OSS_ENABLED=false` 时,只要共用连接完整,PCB 仍可开启。适配器仅本地签名、HEAD 核验大小及生成普通地址,不读取或修改 Bucket ACL、对象 ACL、版本控制或公开策略,不单独设置 private ACL。
数据库仅存 `/pcb-projects/{pcbProjectCode}/{uploadCode}/project.zip`,真实 OSS key 为环境根目录加此路径。前端原样使用 formFields.key,不自行拼接环境前缀。格式见 [OSS 引用规范](oss-storage-paths.md)。
RAM 授权覆盖当前环境 `pcb-projects/*` 的 `oss:PutObject` 与 `oss:GetObject`,用于直传和 HEAD;读取权限按已有普通地址方式配置。CORS 允许实际宿主或编辑器来源的 POST、GET 和 Content-Type,需要时暴露 Content-Length、Content-Disposition。平台 API 使用既有来源白名单。
联调验证创建工程、上传、确认、刷新列表、下载 ZIP、重新打开并继续编辑,以及账号隔离和双标签版本冲突。后端自动化使用模拟 OSS,真实 OSS/CDN 与编辑器联调在部署环境完成。首期不提供历史恢复、对象清理或自动云端保存。
-617
View File
@@ -1,617 +0,0 @@
# 仓库 ZIP、TAR.GZ 下载与 HTTPS Git 前端对接文档
本文供前端开发独立对接已实现的仓库归档下载、Git 克隆信息和项目 Git 凭据管理。前置条件是网站已有登录态,并已取得项目的 `projectCode`。本文所有域名、编码、SHA 和 Token 示例均为占位值。
## 1. 功能范围
| 功能 | 工作区 | 社区 |
| --- | --- | --- |
| 下载 ZIP、TAR.GZ | 登录用户下载本人项目;默认最新 main,也支持历史提交 | 可匿名下载当前已发布版本 |
| clone、fetch、pull、push | 通过项目 Git Token 操作本人仓库 | 先 Fork 到自己的工作区,再使用副本的 Git 接入 |
| Git LFS | 支持实体上传、下载和 verify | 不提供社区 Git 协议入口 |
| 本地 push 后的网站变化 | 刷新工作区后显示最新内容和历史 | 保持原发布版本,用户手动发布后才更新 |
归档与 Git 的资源边界不同:
- ZIP、TAR.GZ 是仓库文件快照,不含提交历史;LFS 保留指针,不下载实体;子模块不递归下载。
- Git clone/fetch 获取 Git 数据;安装并启用 git-lfs 后,客户端可通过 LFS 协议获取实体。子模块仍需客户端自行处理,不会自动递归下载。
- 单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源均不会自动加入归档或 Git 仓库。仓库内本来就有的同类文件按仓库内容处理。
## 2. 地址、身份与通用约定
### 2.1 两类入口
浏览器调用本文 `/api/**` 接口;本地 Git/git-lfs 客户端使用后端返回的 `cloneUrl`,访问 `/git/**`。
```text
浏览器: /api/workspace/projects/{projectCode}/git → 获取连接信息
浏览器: /api/workspace/projects/{projectCode}/git/tokens → 管理项目 Git Token
终端: /git/projects/{projectCode}.git/... → Git/LFS 协议
```
这两类路径由同一个社区 API 应用处理。`/git` 不带 `/api` 前缀。`cloneUrl` 可能使用与业务 API 不同的公网域名,前端必须使用接口返回值,不自行拼接、替换域名或改成 `/api/git`。
前端只需配置业务 `API_BASE`,例如同源代理 `/api`,或后端提供的完整 `https://api.example.com/api`。后文请求示例的 `path` 均不再重复 `/api`。
### 2.2 两类 Token
| 凭据 | 获取方式 | 使用位置 |
| --- | --- | --- |
| 网站登录 Token | 现有网页登录流程 | 浏览器请求头 `Authorization: Bearer <网站登录 Token>` |
| 项目 Git Token | 本文创建凭据接口 | 本地 Git 的 HTTP Basic 密码;用户名使用连接信息中的 `username` |
两类 Token 不能互用。普通用户不需要 Gitea 账号;前端不接收、不配置 Gitea 管理凭据或技术账号凭据。项目 Git Token 继承现有网站登录的身份边界:当前邮箱加图片验证码不验证邮箱归属。
社区匿名下载建议不发送 Authorization;失效的网站 Token 即使用于公开接口,也可能导致 401。
### 2.3 JSON、编码与时间
成功的归档下载返回二进制,其余本文浏览器接口使用以下统一 JSON。所有成功响应均为 HTTP 200,包括创建、撤销;撤销成功 `data=null`。
```json
{
"code": "OK",
"message": "成功",
"data": null,
"requestId": "44444444444444444444444444444444"
}
```
失败使用非 2xx HTTP 状态及同样的包装,`code` 为错误码。按 HTTP 状态和 `code` 判断,不通过中文 `message` 区分错误;提示可展示 `message`,排查时提供 `requestId`。反向代理异常也可能返回非 JSON,前端需要兜底。
- `projectCode`、`userCode` 作为不透明字符串传递,兼容现有 12 位和历史 32 位编码;不要固定长度或使用数据库 ID。`tokenCode` 也是接口返回的业务编码。
- SHA 必须使用完整的 40 或 64 位十六进制字符串,不提交页面展示的缩写。
- 本文凭据时间为上海时间 `Asia/Shanghai`,格式如 `2026-11-03T10:00:00`,可能带小数秒、没有时区后缀;解析时补 `+08:00`,不要补 `Z`。
- 请求体使用 JSON 时设置 `Content-Type: application/json`。无需跨域 Cookie,不设置 `credentials: 'include'`。
- `/api/**` 按部署白名单支持跨域,暴露 `X-Request-Id`、`Content-Disposition`、`Retry-After`。本地开发可代理 `/api`;浏览器不需要代理或调用 `/git`。
## 3. 浏览器接口清单
以下路径均为完整路径;“登录”指网站 Bearer Token。
| 方法 | 路径 | 登录 | 成功 data / 响应 |
| --- | --- | --- | --- |
| GET | `/api/workspace/projects/{projectCode}/archive` | 必须,本人项目 | ZIP 或 TAR.GZ 附件 |
| GET | `/api/community/projects/{projectCode}/archive` | 可匿名 | 当前发布版本附件 |
| GET | `/api/workspace/projects/{projectCode}/git` | 必须,本人项目 | `GitConnection` |
| GET | `/api/workspace/projects/{projectCode}/git/tokens` | 必须,本人项目 | `PageResult<GitTokenView>` |
| POST | `/api/workspace/projects/{projectCode}/git/tokens` | 必须,本人项目 | `IssuedGitToken`,明文只返回一次 |
| DELETE | `/api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 必须,本人项目 | `null` |
## 4. ZIP、TAR.GZ 下载
### 4.1 请求参数与版本
两个归档接口使用以下查询参数,无请求体:
| 参数 | 工作区 | 社区 | 约束 |
| --- | --- | --- | --- |
| `format` | 可选 | 可选 | 省略为 `zip`;仅接受 `zip`、`tar.gz`,区分大小写。空字符串也返回 400 |
| `commitSha` | 可选 | 禁止 | 工作区省略时读取当前 main;指定时使用本项目完整提交 SHA。社区只要出现该参数就返回 400,包括 `commitSha=` |
```http
GET /api/workspace/projects/7m4k9x2p8q6r/archive?format=zip
Authorization: Bearer <网站登录 Token>
```
```http
GET /api/community/projects/7m4k9x2p8q6r/archive?format=tar.gz
```
工作区仅允许本人未删除且 READY 的项目;社区仅允许 READY、已发布且未删除的项目。其他用户的工作区项目返回 404。
服务端在受理时固定本次下载的完整 SHA。假设发布 A 后工作区又提交 B:社区下载 A,工作区默认下载 B,工作区传入 A 的 SHA 则下载 A。传输期间的新提交或重新发布不会切换本次版本;撤回或删除后的新社区下载返回 404。
### 4.2 成功响应与下载交互
| 项目 | ZIP | TAR.GZ |
| --- | --- | --- |
| HTTP 状态 | 200 | 200 |
| Content-Type | `application/zip` | `application/gzip` |
| 文件名 | `{projectCode}-{SHA前12位}.zip` | `{projectCode}-{SHA前12位}.tar.gz` |
响应带 `Content-Disposition: attachment`、`Cache-Control: no-store`、`X-Request-Id`。`Content-Length` 不保证存在。归档根目录、文件层级、符号链接及 `.gitattributes` 导出行为沿用 Gitea。
页面提供“下载 ZIP”“下载 TAR.GZ”,历史版本页面的工作区下载传入对应完整 SHA。点击后展示下载中状态、防止重复点击,提供取消;成功按 Blob 保存,失败先按 JSON 解析。工作区不能用无法附加 Bearer 请求头的普通下载链接,也不能把 Token 拼到 URL。
归档默认最大 1 GiB、上游处理和读取预算 5 分钟、每实例并发 2、每 IP 每分钟 10 次,部署可调整。此限制独立于 JSON 文件预览的 50 MiB 限制及单文件流式下载配置。通用请求拦截器不要使用 10~30 秒超时提前截断归档;如设置超时,应与后端约定,默认预留至少 400 秒。
发附件前的错误返回 JSON;传输开始后的错误会停止响应,此时 HTTP 可能仍为 200,不能再返回 JSON。网络错误、超时、取消后应丢弃残缺文件;没有长度信息时浏览器也不一定识别所有截断情况,解压失败应提示手动重新下载。不提供断点续传、下载任务或进度查询;没有总长度时不要展示虚构百分比。
### 4.3 下载错误
| HTTP / code | 前端处理 |
| --- | --- |
| 400 `BAD_REQUEST` | 检查 format、完整 SHA;社区删除 commitSha 参数 |
| 401 `UNAUTHORIZED` | 工作区引导登录;匿名社区请求移除失效 Token |
| 404 `NOT_FOUND` | 项目、提交不存在,或无权限、未发布、已撤回、已删除 |
| 409 `CONFLICT` | 工作区项目尚未就绪,刷新项目状态 |
| 413 `ARCHIVE_TOO_LARGE` | 告知归档超过服务端上限 |
| 429 `ARCHIVE_BUSY` / `RATE_LIMITED` | 参考 Retry-After,允许用户稍后手动重试 |
| 502 `GITEA_ERROR` | 上游归档异常,展示 requestId 便于排查 |
| 503 `GITEA_NOT_CONFIGURED` | 服务端仓库配置未完成,联系后端 |
| 504 `ARCHIVE_TIMEOUT` | 提示下载超时,可手动重新下载 |
| 499 `ARCHIVE_CANCELLED` | 发包前取消;浏览器主动取消通常直接抛出 AbortError |
## 5. Git 连接信息与凭据管理
以下四个接口全部使用网站 Bearer Token,响应均设置 `Cache-Control: no-store`。
### 5.1 获取连接信息
`GET /api/workspace/projects/{projectCode}/git`,无查询参数、无请求体。需要项目 READY。成功 data:
```json
{
"cloneUrl": "https://git.example.com/git/projects/7m4k9x2p8q6r.git",
"username": "111111111111",
"defaultBranch": "main",
"headCommitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"writeStatus": "IDLE",
"canPush": true
}
```
| 字段 | 类型 | 页面用途 |
| --- | --- | --- |
| `cloneUrl` | string | 克隆地址、复制命令;原样使用 |
| `username` | string | Git Basic 用户名,即当前网站用户 userCode |
| `defaultBranch` | string | 当前固定 `main` |
| `headCommitSha` | string | 本次读取到的工作区 main 完整 SHA |
| `publishedCommitSha` | string 或 null | 当前发布 SHA;未发布时为 null,发布状态仍以项目详情为准 |
| `writeStatus` | `IDLE` / `WRITING` / `REVIEW` | 仓库写入状态 |
| `canPush` | boolean | 当前写入状态、技术账号及 main 保护核验是否允许推送;实际推送仍会重新校验 |
`canPush=true` 也需要 READ_WRITE 凭据,不能理解为只读 Token 可以 push。`canPush=false` 时仍可展示克隆信息和凭据管理,不要仅凭它禁止创建首个读写 Token:创建读写 Token 时后端会初始化或核验 main 保护。
Git 是否可用由部署开关 `GIT_ENABLED` 控制。关闭时本接口及创建凭据返回 503 `GIT_UNAVAILABLE`,凭据列表和撤销仍可使用。当前没有单独的功能开关查询接口,前端按本接口结果展示“本地开发暂未启用”。
### 5.2 查询凭据列表
`GET /api/workspace/projects/{projectCode}/git/tokens?page=1&size=20`。
| 参数 | 默认值 | 范围 |
| --- | --- | --- |
| `page` | 1 | 1~100000 |
| `size` | 20 | 1~100 |
成功 data:
```json
{
"items": [
{
"tokenCode": "33333333333333333333333333333333",
"name": "我的笔记本",
"scope": "READ_WRITE",
"status": "ACTIVE",
"createdAt": "2026-11-03T10:00:00",
"expiresAt": "2027-02-01T10:00:00",
"revokedAt": null,
"lastUsedAt": null
}
],
"page": 1,
"size": 20,
"total": 1
}
```
列表包含有效、过期、已撤销凭据,按创建时间倒序,空列表 `items=[]`。不返回明文、摘要或数据库 ID。
| 字段 | 类型与含义 |
| --- | --- |
| `tokenCode` | string,撤销时使用的业务编码 |
| `name` | string,凭据名称 |
| `scope` | `READ_ONLY`:clone/fetch/pull、LFS 下载;`READ_WRITE`:同时允许 push main 和 LFS 上传 |
| `status` | `ACTIVE`:有效;`EXPIRED`:过期;`REVOKED`:已撤销或因账号会话版本变化失效 |
| `createdAt` / `expiresAt` | string,创建和到期时间 |
| `revokedAt` | string 或 null;会话版本导致失效时 status 可为 REVOKED,但此字段仍为 null |
| `lastUsedAt` | string 或 null;最近成功认证时间,最多每 5 分钟写回一次,不能视作实时在线状态 |
### 5.3 创建凭据
`POST /api/workspace/projects/{projectCode}/git/tokens`,JSON 请求:
```json
{
"name": "我的笔记本",
"scope": "READ_WRITE",
"expiresInDays": 90
}
```
| 字段 | 必填 | 约束 |
| --- | --- | --- |
| `name` | 是 | 非空,最多 64 字符;提交前去掉首尾空格,后端保存时也会去掉 |
| `scope` | 是 | 精确使用 `READ_ONLY` 或 `READ_WRITE` |
| `expiresInDays` | 否 | 整数 1~365;省略或 null 为 90 天 |
每项目默认最多 10 个有效凭据,服务端可调低额度;过期、已撤销及会话版本失效的凭据不占有效额度。达到额度返回 409 `CONFLICT`。读写凭据创建时后端会核验或初始化 main 保护;不兼容时拒绝创建,不覆盖已有更严格规则。
成功 data 为:
```json
{
"credential": {
"tokenCode": "33333333333333333333333333333333",
"name": "我的笔记本",
"scope": "READ_WRITE",
"status": "ACTIVE",
"createdAt": "2026-11-03T10:00:00",
"expiresAt": "2027-02-01T10:00:00",
"revokedAt": null,
"lastUsedAt": null
},
"token": "vbg_<仅本次响应返回的项目Git凭据明文>"
}
```
`credential` 是元数据,`token` 才是 Git 密码。明文仅返回一次,不能再次查询。成功后刷新凭据列表和连接信息,并在独立区域一次性展示明文、提供复制按钮。明文仅保留在当前展示状态,关闭弹窗、切换项目或离开页面时清除;不要写入 localStorage、sessionStorage、URL、埋点或日志,也不要直接记录整个创建响应。
创建请求不要自动重试。超时、断网或用户取消时可能已经创建成功;先刷新列表核对,无法取得明文的凭据应撤销后重新创建。
### 5.4 撤销凭据
`DELETE /api/workspace/projects/{projectCode}/git/tokens/{tokenCode}`,无请求体,成功 `data=null`。重复撤销同一已存在凭据也成功;不存在、属于其他项目或其他用户的凭据返回 404。
成功后刷新列表。撤销、过期、账号禁用或账号会话版本改变后,新的 Git/LFS 请求会被拒绝;已受理传输不保证立即中止或回滚。普通网站退出登录不撤销项目 Git Token。
当前没有修改凭据名称、修改权限、续期或重新查询明文的接口;需要调整时撤销并新建。
### 5.5 浏览器管理接口错误
| HTTP / code | 前端处理 |
| --- | --- |
| 400 `BAD_REQUEST` | 检查字段、枚举、名称长度、到期天数和分页参数 |
| 401 `UNAUTHORIZED` | 网站登录失效,按现有登录流程处理 |
| 404 `NOT_FOUND` | 项目或凭据不存在、已删除或不属于本人 |
| 409 `CONFLICT` | 创建凭据时可能为有效额度已满;连接信息或创建凭据时也可能为项目未就绪,展示服务端 message 并刷新核对 |
| 409 `PROJECT_BUSY` | 项目正在处理,稍后手动重试 |
| 503 `GIT_UNAVAILABLE` | 功能未启用或依赖不可用;已有凭据仍可查询和撤销 |
| 503 `GIT_POLICY_UNAVAILABLE` | 技术账号、仓库或 main 保护不兼容,联系后端处理 |
| 502 / 503 / 504 其他依赖错误 | 展示 message 和 requestId;创建结果不明时先核对列表,不自动重发 |
## 6. 页面流程与本地开发指引
### 6.1 页面入口和状态
1. 工作区和社区详情提供 ZIP、TAR.GZ 下载;“克隆与本地开发”只在本人工作区提供。社区展示“Fork 到我的工作区”,完成后进入新项目。
2. 打开本地开发面板时,可以并行获取连接信息和凭据列表;两者独立处理错误,功能关闭也保留列表、撤销入口。
3. 展示 cloneUrl、username、main SHA、发布 SHA、写入状态,以及创建、列表、撤销操作。列表行以 tokenCode 为标识。
4. 创建成功展示一次性明文,刷新列表和连接信息;复制命令中不包含任何 Token。
5. 提供“刷新工作区”按钮,重新读取当前目录、已打开文件、历史及连接信息;有未保存输入时保留输入并提示版本变化,不静默覆盖。
6. push 成功后仍显示“需要手动发布到社区”。刷新版本后让用户确认发布,不能自动调用发布接口。
| writeStatus | 建议提示与操作 |
| --- | --- |
| `IDLE` | 当前无写入保护;结合 canPush 展示推送可用性 |
| `WRITING` | 正在写入,请稍后刷新;暂缓新的网页保存、上传和发布 |
| `REVIEW` | 写入结果核对中;禁用新的仓库写入和发布,保留用户未保存输入,允许刷新核对 |
canPush=false 且 IDLE 时可提示“当前暂不可推送,请创建读写凭据或联系管理员核对配置”,不能仅凭此布尔值猜测唯一原因。canPush、SHA 和状态都是读取时的快照,不代替后端实时校验。没有面向前端的 push 任务或进度查询接口,不要求接入 Webhook。
### 6.2 可展示给用户的终端步骤
克隆前安装 Git 和 git-lfs。使用接口返回的实际 cloneUrl 替换下方占位符:
```bash
git lfs install
git -c credential.useHttpPath=true clone --single-branch --branch main <cloneUrl>
cd <本地仓库目录>
git config credential.useHttpPath true
git add .
git commit -m "更新项目"
git push origin main
# 后续拉取
git pull origin main
```
终端询问用户名时填写连接信息中的 `username`,密码填写刚创建的项目 Git Token。操作系统凭据管理器可保存凭据。同一域名的不同项目使用不同 Token,示例中的 `credential.useHttpPath=true` 必须保留。
仅允许 main 正常快进更新和合并提交,禁止强推、删除 main、推送其他分支或标签、多引用推送、push-options、signed-push 扩展;普通签名提交支持,本地作者、邮箱、时间、签名及 SHA 原样保留。已有其他分支和标签可读取,本期不清理历史数据。
LFS 支持实体上传、下载和 verify;不支持文件锁,锁创建/删除返回 501,locks/verify 返回空集合。只读 Token 不能 push 或上传 LFS。
本地版本落后时先 pull、处理冲突再 push,不提示用户强推。push 超时或断开不能直接当作失败,也不要自动重推;先刷新工作区和历史核对。
### 6.3 与现有网站接口配合
| 场景 | 已有接口与用法 |
| --- | --- |
| 社区 Fork | `POST /api/community/projects/{projectCode}/forks`,body 为 `{ "name": "我的副本", "publishedCommitSha": "社区详情的完整发布SHA" }`;成功 data 为新项目,使用其 projectCode 进入工作区 |
| 刷新根目录 | `GET /api/workspace/projects/{projectCode}/tree`;读取最新 main 时省略 commitSha;响应 data.commitSha 为本次版本 |
| 刷新文件 | `GET /api/workspace/projects/{projectCode}/files?path=...`;查询值用 URLSearchParams 编码,可传相同 commitSha 保持目录和文件版本一致 |
| 刷新历史 | `GET /api/workspace/projects/{projectCode}/commits?page=1&size=20` |
| 手动发布 | `PUT /api/workspace/projects/{projectCode}/publication`,body 为 `{ "commitSha": "用户确认发布的最新main完整SHA" }`;成功 data 为更新后的项目 |
| 刷新社区 | `GET /api/community/projects/{projectCode}`;社区目录和文件禁止传 commitSha |
上述工作区、Fork、发布接口使用网站 Bearer Token。发布版本已变化导致 409 时,刷新版本并让用户重新确认,不自动换 SHA 再发布。网页保存同样使用原编辑基准 SHA;409 时保留输入,处理差异后再提交。`updatedAt` 不代表仓库最新提交时间,版本比较使用 SHA;是否当前已发布使用项目详情的 `publishStatus`。
Fork 也是写操作,不自动重试;失败或超时先核对工作区列表。完整项目、目录、文件和 Fork 的类型及约束见 [用户端完整接口文档](vibemake-api.md)。
## 7. 可复用 TypeScript 示例
以下两个代码块可放入同一个前端模块。示例无需依赖完整接口文档中的 request 方法;`platformToken` 始终指网站登录 Token。
### 7.1 类型、JSON 请求和凭据管理
```typescript
const API_BASE = '/api'; // 同源代理;也可替换为部署提供的完整 API 基础地址,无末尾斜杠。
export interface ApiResponse<T> {
code: string;
message: string;
data: T;
requestId: string;
}
export interface PageResult<T> {
items: T[];
page: number;
size: number;
total: number;
}
export interface GitConnection {
cloneUrl: string;
username: string;
defaultBranch: string;
headCommitSha: string;
publishedCommitSha: string | null;
writeStatus: 'IDLE' | 'WRITING' | 'REVIEW';
canPush: boolean;
}
export type GitScope = 'READ_ONLY' | 'READ_WRITE';
export interface GitTokenView {
tokenCode: string;
name: string;
scope: GitScope;
status: 'ACTIVE' | 'EXPIRED' | 'REVOKED';
createdAt: string;
expiresAt: string;
revokedAt: string | null;
lastUsedAt: string | null;
}
export interface CreateGitTokenInput {
name: string;
scope: GitScope;
expiresInDays?: number | null;
}
export interface IssuedGitToken {
credential: GitTokenView;
token: string; // 仅本次展示,不持久化、不记录整个响应。
}
export class ApiError extends Error {
constructor(
public readonly status: number,
public readonly code: string,
message: string,
public readonly requestId: string | null,
public readonly retryAfter: string | null = null,
) {
super(message);
this.name = 'ApiError';
}
}
async function readEnvelope<T>(response: Response): Promise<ApiResponse<T>> {
let body: ApiResponse<T>;
try {
body = await response.json();
} catch {
throw new ApiError(response.status, 'BAD_RESPONSE', '接口响应异常,请稍后重试',
response.headers.get('X-Request-Id'), response.headers.get('Retry-After'));
}
if (!body || typeof body.code !== 'string' || typeof body.message !== 'string') {
throw new ApiError(response.status, 'BAD_RESPONSE', '接口响应格式异常',
response.headers.get('X-Request-Id'));
}
return body;
}
function responseError(response: Response, body: ApiResponse<unknown>): ApiError {
return new ApiError(response.status, body.code, body.message,
body.requestId ?? response.headers.get('X-Request-Id'),
response.headers.get('Retry-After'));
}
async function apiRequest<T>(
path: string,
platformToken: string,
options: { method?: 'GET' | 'POST' | 'DELETE'; body?: unknown; signal?: AbortSignal } = {},
): Promise<T> {
const headers: Record<string, string> = { Authorization: `Bearer ${platformToken}` };
if (options.body !== undefined) headers['Content-Type'] = 'application/json';
const response = await fetch(`${API_BASE}${path}`, {
method: options.method ?? 'GET',
headers,
credentials: 'omit',
cache: 'no-store',
body: options.body === undefined ? undefined : JSON.stringify(options.body),
signal: options.signal,
});
const body = await readEnvelope<T>(response);
if (!response.ok || body.code !== 'OK') throw responseError(response, body);
return body.data;
}
function gitPath(projectCode: string): string {
return `/workspace/projects/${encodeURIComponent(projectCode)}/git`;
}
export function getGitConnection(projectCode: string, platformToken: string, signal?: AbortSignal) {
return apiRequest<GitConnection>(gitPath(projectCode), platformToken, { signal });
}
export function listGitTokens(
projectCode: string, platformToken: string, page = 1, size = 20, signal?: AbortSignal,
) {
const query = new URLSearchParams({ page: String(page), size: String(size) });
return apiRequest<PageResult<GitTokenView>>(
`${gitPath(projectCode)}/tokens?${query}`, platformToken, { signal });
}
export function createGitToken(
projectCode: string, platformToken: string, input: CreateGitTokenInput, signal?: AbortSignal,
) {
return apiRequest<IssuedGitToken>(`${gitPath(projectCode)}/tokens`, platformToken, {
method: 'POST', body: { ...input, name: input.name.trim() }, signal,
}); // 不添加自动重试。
}
export function revokeGitToken(projectCode: string, tokenCode: string, platformToken: string) {
return apiRequest<null>(
`${gitPath(projectCode)}/tokens/${encodeURIComponent(tokenCode)}`,
platformToken, { method: 'DELETE' });
}
export function parseShanghaiTime(value: string): Date {
return new Date(`${value}+08:00`); // 仅用于本文无时区后缀的时间字段。
}
```
### 7.2 归档下载、文件保存与主动取消
```typescript
export async function downloadRepositoryArchive(
scope: 'workspace' | 'community',
projectCode: string,
format: 'zip' | 'tar.gz' = 'zip',
options: { platformToken?: string; commitSha?: string; signal?: AbortSignal } = {},
): Promise<void> {
if (scope === 'workspace' && !options.platformToken) throw new Error('请先登录');
if (scope === 'community' && options.commitSha !== undefined) {
throw new Error('社区归档仅支持当前已发布版本,请移除 commitSha');
}
const query = new URLSearchParams({ format });
if (options.commitSha !== undefined) query.set('commitSha', options.commitSha);
const response = await fetch(
`${API_BASE}/${scope}/projects/${encodeURIComponent(projectCode)}/archive?${query}`,
{
headers: options.platformToken
? { Authorization: `Bearer ${options.platformToken}` } : {},
credentials: 'omit',
cache: 'no-store',
signal: options.signal,
},
);
if (!response.ok) {
const failure = await readEnvelope<unknown>(response);
throw responseError(response, failure);
}
const expectedType = format === 'zip' ? 'application/zip' : 'application/gzip';
const actualType = response.headers.get('Content-Type')?.split(';')[0].trim().toLowerCase();
if (actualType !== expectedType) {
await response.body?.cancel();
throw new ApiError(response.status, 'BAD_RESPONSE', '接口未返回预期的压缩包',
response.headers.get('X-Request-Id'));
}
const blob = await response.blob(); // 收到响应头后,取消仍可中止响应体读取。
const requestId = response.headers.get('X-Request-Id');
const contentLength = response.headers.get('Content-Length');
if (contentLength !== null && blob.size !== Number(contentLength)) {
throw new ApiError(response.status, 'ARCHIVE_INCOMPLETE', '压缩包接收不完整,请重新下载', requestId);
}
if (options.signal?.aborted) throw new DOMException('下载已取消', 'AbortError');
const disposition = response.headers.get('Content-Disposition') ?? '';
const encodedName = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
const plainName = disposition.match(/filename="([^"]+)"/i)?.[1];
let filename = plainName ?? `${projectCode}.${format}`;
if (encodedName) {
try { filename = decodeURIComponent(encodedName); } catch { /* 使用后备文件名。 */ }
}
filename = filename.replace(/[\\/\u0000-\u001f\u007f]/g, '_');
const objectUrl = URL.createObjectURL(blob);
try {
const link = document.createElement('a');
link.href = objectUrl;
link.download = filename;
document.body.appendChild(link);
link.click();
link.remove();
} finally {
setTimeout(() => URL.revokeObjectURL(objectUrl), 1000);
}
}
// 示例:在点击事件中传入实际项目编码和网站登录 Token。
export async function handleWorkspaceDownload(
projectCode: string, platformToken: string, controller: AbortController,
) {
try {
await downloadRepositoryArchive('workspace', projectCode, 'zip', {
platformToken, signal: controller.signal,
});
} catch (error) {
if (controller.signal.aborted) return; // 用户主动停止,不提示“服务器错误”。
throw error; // 页面统一提示 ApiError.message 或网络异常,不记录 Token。
}
}
// 点击下载:创建并保留 const controller = new AbortController(),传给上面的函数。
// 点击停止或离开页面:controller.abort()。下一次下载必须创建新的 controller。
// 社区匿名下载:downloadRepositoryArchive('community', projectCode, 'tar.gz')。
```
`BAD_RESPONSE`、`ARCHIVE_INCOMPLETE` 是示例前端封装错误码,不是后端业务码。网络错误、用户取消及接收二进制时的异常未必有 JSON 或 requestId。Blob 会占用浏览器内存或存储,页面应限制重复下载;HTTP 200、Blob 保存成功均不能替代压缩包完整性校验。
## 8. Git 协议说明与用户故障提示
本节用于编写终端指引和排查,不要求前端实现 Git/LFS 协议。Git 客户端自动访问这些路径:
| 方法 | 路径 |
| --- | --- |
| GET | `/git/projects/{projectCode}.git/info/refs?service=git-upload-pack` |
| GET | `/git/projects/{projectCode}.git/info/refs?service=git-receive-pack` |
| POST | `/git/projects/{projectCode}.git/git-upload-pack` |
| POST | `/git/projects/{projectCode}.git/git-receive-pack` |
| Git LFS 客户端自动调用 | `/git/projects/{projectCode}.git/info/lfs/**` |
协议响应为 Git pkt-line/pack 或 LFS 标准结构,不是网站 ApiResponse。401 带 Basic challenge,429 带 Retry-After;LFS action 使用服务端签发的短期凭据,由 git-lfs 自动处理。不要用浏览器的 apiRequest 包装去请求上述路径,也不要将它们作为普通网页打开方式。
| 协议错误码/状态 | 给用户的处理指引 |
| --- | --- |
| 401 `GIT_UNAUTHORIZED` | 检查网站 userCode、项目 Git Token、是否过期或撤销;不要使用网站登录 Token |
| 403 `GIT_READ_ONLY` | 使用 READ_WRITE 凭据后再 push 或上传 LFS |
| 400 `GIT_COMMAND_REJECTED` | 仅推送 main,去掉其他引用及不支持的推送扩展 |
| 409 `GIT_STALE_MAIN` | 先拉取并处理冲突,再推送 |
| 409 `CONFLICT` / `PROJECT_BUSY` | 项目未就绪或正在处理,刷新核对 |
| 409 或 503 `REMOTE_RESULT_UNKNOWN` | 结果核对中,暂缓写入和发布,先刷新工作区及历史 |
| 429 `GIT_BUSY` | 请求频率或并发超限,稍后手动重试 |
| 413 `GIT_TRANSFER_TOO_LARGE` / `GIT_METADATA_TOO_LARGE` / `LFS_TOO_LARGE` | 请求超过服务端限制,缩小请求或联系管理员 |
| 503 `GIT_UNAVAILABLE` / `GIT_POLICY_UNAVAILABLE` | 功能或依赖暂不可用,联系管理员 |
| 504 `GIT_TIMEOUT` / 502 `GIT_UPSTREAM_ERROR` | 涉及 push 时先核对工作区,不能仅凭断网或超时判定未写入 |
| 501 `LFS_LOCKS_UNSUPPORTED` | 当前不支持 LFS 文件锁 |
原生 Git 也可能输出标准引用拒绝信息;不能仅凭 HTTP 200 判断 push 成功,应以 Git 客户端最终结果和刷新后的工作区 SHA 为准。
默认 Git pack 单次上限 5 GiB、LFS 单对象 1 GiB、元数据 8 MiB、LFS batch 最多 500 对象;单次 Git/LFS 请求预算 10 分钟。每实例读取/push/LFS 并发为 4/2/8;每用户每分钟 Git 120 次、LFS 600 次,每 IP 每分钟认证失败最多 20 次。均可由部署调整,与归档、JSON、multipart 和在线文件读取限制独立。
## 9. 前端联调验收
- [ ] 本人工作区和匿名社区均可下载 ZIP、TAR.GZ,文件名及解压后的中文路径、子目录、二进制正确。
- [ ] 发布 A 后提交 B:社区归档仍为 A,工作区默认 B,指定历史 SHA 可下载 A;社区请求不携带 commitSha。
- [ ] 下载处理 401、404、413、429、非 JSON 代理错误、取消、网络中断;限制重复点击并释放 Blob URL。
- [ ] 只有本人工作区提供本地开发入口;社区先 Fork,再使用新项目编码;非本人项目、已删除项目的管理请求被拒绝。
- [ ] 正确区分网站登录 Token、项目 Git Token、tokenCode;cloneUrl 原样使用,明文不进入缓存、URL、日志或埋点。
- [ ] 凭据列表支持分页、有效/过期/撤销状态和空时间;创建校验名称、权限、到期天数及额度,创建结果未知不自动重试。
- [ ] 一次性明文正确展示和复制,关闭展示后清除;列表无法重新获取明文;撤销后刷新列表。
- [ ] 功能关闭时展示不可用提示,仍可查询、撤销已有凭据;canPush=false 不直接阻止创建首个读写凭据。
- [ ] 按网站展示的地址、用户名和凭据完成 clone、commit、push、pull;同域名两个项目可使用不同凭据,LFS 正常上传下载。
- [ ] push 后刷新工作区显示最新目录、文件和历史,保留未保存输入;社区保持原版本,确认手动发布后才更新。
- [ ] 正确展示 WRITING、REVIEW;结果未知时不重复写入、不自动发布;只读、强推、其他引用等拒绝场景有明确指引。
部署联调前由后端确认 Git 功能已开启、数据库扩展已执行、返回的 cloneUrl 可达,公网 `/git/**` 保留路径转发至社区 API。归档代理读取超时默认至少 400 秒,Git/LFS 至少 660 秒并关闭请求、响应缓冲及缓存。前端不负责保存上游凭据或配置 Gitea。
完整业务接口见 [用户端接口文档](vibemake-api.md),部署细节见 [README](../README.md#https-git-网关)。
-75
View File
@@ -1,75 +0,0 @@
# 数据库 OSS 引用统一规范与存量转换
所有平台托管 OSS 资源的专用数据库字段统一保存**未进行 URL 编码、以 `/` 开头、不含域名和环境根目录的路径**。目录字段保留末尾 `/`。实际上传对象键、HEAD/复制使用的 key 和公开访问 URL 由 `vibemake.oss.root-directory` 与公开基础地址在运行时生成。
| 位置 | 数据库存储示例 | 实际 OSS key 示例 |
| --- | --- | --- |
| CAD 当前设计及上传批次 | `/cad-projects/{项目编码}/{批次编码}/design.sc` | `vibemake_dev/cad-projects/{项目编码}/{批次编码}/design.sc` |
| CAD 初始 STEP(initial_step_object_key) | `/project-resources/{工作区项目编码}/step/{批次编码}/model.step` | `vibemake_dev/project-resources/{工作区项目编码}/step/{批次编码}/model.step` |
| PCB 当前工程及上传批次 | `/pcb-projects/{项目编码}/{批次编码}/project.zip` | `vibemake_dev/pcb-projects/{项目编码}/{批次编码}/project.zip` |
| 平台托管封面(含 CAD、PCB 的 cover_url) | `/project-covers/{用户编码}/{日期}/{文件名}` | `vibemake_dev/project-covers/{用户编码}/{日期}/{文件名}` |
| URDF 主文件及目录 | `/urdf/{项目编码}/{批次编码}/...` | `vibemake_dev/urdf/{项目编码}/{批次编码}/...` |
| STEP、GLB、零件、拼装步骤、行走资源 | `/project-resources/{项目编码}/{类型}/{批次编码}/...` | `vibemake_dev/project-resources/{项目编码}/{类型}/{批次编码}/...` |
生产环境真实对象键使用 `vibemake/`;数据库格式相同。托管图片作为封面时,也可以引用 README 图片或其他受控资源目录,均按相同规则保存。外部 HTTPS 链接、带查询参数或片段的链接保持原有访问语义,不通过截断 URL 去掉参数或改写到其他环境。原始 Git README 内容、外部仓库来源地址不属于 OSS 绑定字段,不做全文替换。
新写入的 CAD 批次和保存确认已采用此格式。CAD 关联创建时也将初始 STEP 规范为相对路径,固定引用工作区项目的原对象,不复制或转换,具体表结构及增量 SQL 见 [CAD 数据库说明](cad-database.md#已有数据库增加工作区项目关联与初始-step);该字段为本次新增,无历史完整 key 需要迁移。项目完整保存、Fork 和导入工具状态回写统一规范资源引用;普通资源签名和确认继续使用已有相对路径。应用兼容读取当前环境的历史完整 key,但读取不自动迁移数据库。升级前签发的 CAD 批次仍可确认,确认时同时规范项目和该批次的引用。幂等重放保持原有回执规则。
## 现有数据手工转换 SQL
PCB 两张新表直接采用环境相对路径,建表见 [PCB 工作空间 SQL](pcb-database.md),无需执行下列 CAD 与社区资源的历史转换。
无需修改字段结构。先升级所有在线写入进程与导入工具,再暂停资源写入并备份业务库。在对应环境的业务数据库连接中执行;test 使用 `vibemake_dev`,prod 将 `@oss_root` 改为 `vibemake`。不会移动、复制或删除 OSS 对象,也不修改项目版本、保存时间、上传回执和业务更新时间。
仅当字段精确以当前环境和对应资源目录开头时转换,使用二进制前缀比较避免大小写或下划线通配符误匹配,不使用全局 REPLACE。已经是相对路径的记录、空值和其他环境路径不变;本转换可重复执行。
```sql
-- resource-path-all-bindings-migrate
SET @oss_root = 'vibemake_dev';
START TRANSACTION;
-- 仅去掉当前环境前缀,保留开头的 /;空绑定和其他环境不匹配。
UPDATE cad_project
SET document_object_key = SUBSTRING(document_object_key, CHAR_LENGTH(@oss_root) + 1)
WHERE BINARY LEFT(document_object_key, CHAR_LENGTH(@oss_root) + 14) = BINARY CONCAT(@oss_root, '/cad-projects/');
UPDATE cad_project_upload
SET object_key = SUBSTRING(object_key, CHAR_LENGTH(@oss_root) + 1)
WHERE BINARY LEFT(object_key, CHAR_LENGTH(@oss_root) + 14) = BINARY CONCAT(@oss_root, '/cad-projects/');
-- 项目资源的原始 key 与目录,统一为已有的环境相对格式。
UPDATE project
SET urdf_main_object_key = CASE WHEN BINARY LEFT(urdf_main_object_key, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
THEN SUBSTRING(urdf_main_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE urdf_main_object_key END,
urdf_prefix = CASE WHEN BINARY LEFT(urdf_prefix, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
THEN SUBSTRING(urdf_prefix, CHAR_LENGTH(@oss_root) + 1) ELSE urdf_prefix END,
step_object_key = CASE WHEN BINARY LEFT(step_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(step_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE step_object_key END,
model_glb_object_key = CASE WHEN BINARY LEFT(model_glb_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(model_glb_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE model_glb_object_key END,
model_parts_prefix = CASE WHEN BINARY LEFT(model_parts_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(model_parts_prefix, CHAR_LENGTH(@oss_root) + 1) ELSE model_parts_prefix END,
assembly_json_object_key = CASE WHEN BINARY LEFT(assembly_json_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(assembly_json_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE assembly_json_object_key END,
walking_resources_prefix = CASE WHEN BINARY LEFT(walking_resources_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(walking_resources_prefix, CHAR_LENGTH(@oss_root) + 1) ELSE walking_resources_prefix END
WHERE BINARY LEFT(urdf_main_object_key, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
OR BINARY LEFT(urdf_prefix, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
OR BINARY LEFT(step_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(model_glb_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(model_parts_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(assembly_json_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(walking_resources_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/');
COMMIT;
```
`project.cover_url` 的历史完整 HTTPS 地址还需要域名匹配和 URL 解码,不能直接用上述 SUBSTRING 处理。标准托管封面的预览、备份、转换和回退 SQL 见 [封面及 URDF 历史迁移](database.md#资源路径历史数据迁移)。按当前 OSS/CDN 及已配置历史基础地址逐个执行;非标准、编码或带参数的历史图片先核验,正常重新保存时应用会按受控资源规则转换,不盲目截断成路径。
## 验证和回退
- 抽查 CAD 两张表和 project 的资源字段均为 `/cad-projects/`、`/urdf/`、`/project-resources/` 等相对路径。
- 通过 API 重新获取的下载地址与转换前指向同一个真实对象,仍包含当前环境前缀。
- 核验升级前未确认 CAD 批次、重复确认、重新保存、Fork 继承和项目资源列表。
- 未转换的其他环境或异常路径单独核验,不能通过任意删除路径第一段重新定位对象。
- 旧 CAD 后端的 HEAD 使用完整 key,回滚前需同时恢复该次迁移备份中的 CAD 原值;不能只回滚代码。保留上线后的有效写入,不用旧备份覆盖新保存。
应用不会自动执行这些 SQL,本仓库不修改任何 `.sql` 文件。
-50
View File
@@ -1,50 +0,0 @@
# PCB 工作空间建表 SQL
在启用 PCB 接口前,由运维在现有 `vibemake` 数据库手工执行以下 SQL(MySQL 8.0.13+)。应用不自动建表,不修改现有项目表。所有业务时间按上海时间写入。
`id` 和归属外键仅供服务内部使用,对外使用 `pcb_project_code` 和 `upload_code`。两张表与 Git 项目无关联。上线顺序:执行 SQL → 部署后端 → 验证共用 OSS 配置及文件读取 → 开放前端入口。回滚代码时保留两张表和 OSS 对象。
```sql
CREATE TABLE pcb_project (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对外返回',
pcb_project_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT 'PCB项目唯一业务编码',
owner_user_id BIGINT NOT NULL COMMENT '所属用户内部主键,关联sys_user.id',
name VARCHAR(100) NOT NULL COMMENT 'PCB项目名称',
description VARCHAR(2000) NOT NULL DEFAULT '' COMMENT 'PCB项目描述',
cover_url VARCHAR(2048) NULL COMMENT 'PCB项目封面,平台OSS资源存无环境前缀的相对路径',
document_object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '' COMMENT '当前工程ZIP文件环境相对路径,以斜杠开头,不含域名和环境根目录',
file_name VARCHAR(255) NOT NULL DEFAULT '' COMMENT '当前工程ZIP文件名称',
size_bytes BIGINT NOT NULL DEFAULT 0 COMMENT '当前工程ZIP文件大小,单位字节',
version BIGINT NOT NULL DEFAULT 0 COMMENT '当前保存版本,空项目为0,每次成功保存递增',
saved_at DATETIME(3) NULL COMMENT '最近成功保存工程ZIP文件的上海时间',
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除标记,0未删除,1已删除',
created_at DATETIME(3) NOT NULL COMMENT '项目创建上海时间',
updated_at DATETIME(3) NOT NULL COMMENT '项目信息最近更新上海时间',
PRIMARY KEY (id),
UNIQUE KEY uk_pcb_project_code (pcb_project_code),
KEY idx_pcb_project_owner_list (owner_user_id, deleted, updated_at, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='PCB个人工作空间项目';
CREATE TABLE pcb_project_upload (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对外返回',
upload_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '上传批次唯一业务编码',
pcb_project_id BIGINT NOT NULL COMMENT '所属PCB项目内部主键,关联pcb_project.id',
expected_version BIGINT NOT NULL COMMENT '签发上传时的项目基础版本,用于并发保存校验',
object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '本批次工程ZIP文件环境相对路径,以斜杠开头,不含域名和环境根目录',
file_name VARCHAR(255) NOT NULL COMMENT '本批次工程ZIP文件名称',
size_bytes BIGINT NOT NULL COMMENT '本批次声明的文件大小,单位字节',
expires_at DATETIME(3) NOT NULL COMMENT '未确认批次的截止上海时间,与上传签名一致',
saved_version BIGINT NULL COMMENT '确认成功的版本号,空值表示尚未确认',
saved_at DATETIME(3) NULL COMMENT '首次确认成功上海时间,重复确认返回原值',
created_at DATETIME(3) NOT NULL COMMENT '批次创建上海时间',
updated_at DATETIME(3) NOT NULL COMMENT '批次最近更新上海时间',
PRIMARY KEY (id),
UNIQUE KEY uk_pcb_upload_code (upload_code),
KEY idx_pcb_upload_project (pcb_project_id, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='PCB工程ZIP文件上传与保存确认批次';
```
保存事务锁定当前用户的未删除项目和对应批次,按 `expected_version` 条件更新当前对象键和版本,同时写入批次回执。失败整体回滚。重放已确认批次只返回首次确认的版本和时间,不重新绑定旧对象;项目删除后仍拒绝重放。首期不清理上传批次或旧 OSS 对象,不提供历史恢复接口。
`document_object_key` 和 `object_key` 均保存 `/pcb-projects/{项目编码}/{批次编码}/project.zip`,不保存 `vibemake_dev/` 或 `vibemake/`。真实上传和读取在运行时补当前环境根目录。PCB 新建表直接采用该格式,无需执行 CAD 的历史路径转换 SQL。
-1751
View File
File diff suppressed because it is too large Load Diff
-9
View File
@@ -1,9 +0,0 @@
__pycache__/
*.pyc
.venv/
*.egg-info/
build/
dist/
benchmark/config.local.json
runs/
-79
View File
@@ -1,79 +0,0 @@
# CAD 零件分类知识库 · 0.1.0
community 项目内的中文 CAD 零件知识库,正式维护目录为 `knowledge/cad-parts/`。以 MCB 公开分类树作初始目录,借鉴 ISO 13584-42 的属性字典方法,保留离线资料、参数规则和有实测依据的生成规程。
原独立路径的兼容链接已删除,只维护 community 内这一份知识源。虚拟环境、私有配置和历史运行目录继续由 `.gitignore` 排除;生产构建不应打包它们。迁移记录见[迁移校验](reports/community-migration-20261111.json),旧路径删除与离线复核见[清理记录](reports/community-path-cleanup-20261111.json)。
**CAD 网页助手的知识工具与运行接线已实现,首轮真实网页 A/B 已完成。** 原版 17 个通用 Skill 保留,仅增加一个只读 `knowledge_lookup`,精确命中直接取得短规程;上下文由程序去重并管理失效。同题关闭知识未生成实体,开启后完成 20 齿完整结构;齿轮加独立轴也通过几何复核,见[题目、截图与实测报告](reports/gear-integration-20261111/README.md)。默认关闭,本机受控试验使用 `pilot`;少量样例不能证明总体成功率或速度提高。配置、接口、构建、测试和扩展见[项目维护入口](../../docs/cad-part-knowledge.md),完整设计见[实施方案](plans/cad-assistant-knowledge-integration-plan-20261111.md)。
当前交付 **203 类目录、6 个完整零件族、9 份共享特征、6 个完整示例和 60 条固定离线评测**。知识库检索和参数校验保持离线运行;另提供独立的豆包 → makeCAD CLI A/B 测试程序,用于实际生成、测量和截图,不经过 Codex 或应用内置聊天。
**生成用途已调整:旧六族长文保留为离线资料,不再推荐整包注入生成。** 新增 `generation-context` 只返回与引擎匹配、明确准入的短规程;没有合格规程就返回空文本,不增加提示词。当前有20份生成实验候选:原13份齿轮/机构规程,加上五个样板和两种人字齿;另保留1份退出加载的历史版本,均无正式准入条目。网页`pilot`按类型、条件和精确构建加载,`enabled`及离线`generation-context`默认不加载候选。参见[生成文本规则与证据](generation/README.md)、[本轮七类补全](reports/five-samples-herringbone-20261112/README.md)和[历史齿轮扩展](reports/gear-family-expansion-20261112/README.md)。
首轮齿传动扩展与定向补测已完成,逐类状态见 [当前覆盖与证据边界](reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)。9类单体已有有限正确实例,4类机构分别记录静态通过、证据不足或失败;不把目录覆盖解释为所有类别稳定成功。题目、原生设计、截图、公式错误与修订版本均保留。
五个旧样板与两种人字齿本轮已收尾:[14次正式A/B](reports/five-samples-herringbone-20261112/FORMAL-V1.md)、[五类产物副本改参](reports/five-samples-herringbone-20261112/EDITS-V1.md)、[独立v2取文发布](reports/five-samples-herringbone-20261112/ROUTING-V2.md)。两种人字齿已分别登记并有参考验证,正式生成仍未通过;0.1.1修订尚无新模型效果证据。原Skill和模型/工具循环不变,历史失败及未送达原始响应保留。
## 先阅读
- [新对话交接:当前版本、现场与下一步](generation/HANDOFF.md)
- [类别补全的工作方法与验收规范](generation/MAINTENANCE.md)
- [中文完整分类目录](references/classification/mcb-taxonomy.zh-CN.md)
- [可放进 Markdown 的 Mermaid 分类树](references/classification/mcb-taxonomy-mermaid.zh-CN.md)
- [六族知识覆盖清单](references/coverage.md)
- [Agent 入口 Skill](SKILL.md)
- [统一模板与属性规范](references/family-template.md)
- [接口与后续扩展](references/maintenance.md)
- [来源和翻译疑点](references/classification/sources.md)
- [验收报告](reports/acceptance.md)
- [豆包直接调用的六族 A/B 生成测试](benchmark/README.md)
## 六个样板
| 基础族 | 复杂族 |
| --- | --- |
| [带孔安装板](references/families/mounting-plate.md) | [带筋轴承座座体](references/families/ribbed-bearing-housing.md) |
| [台阶轴](references/families/stepped-shaft.md) | [渐开线直齿圆柱齿轮](references/families/involute-spur-gear.md) |
| [六角头螺栓](references/families/hex-head-bolt.md) | [带盖薄壁壳体](references/families/covered-thin-wall-enclosure.md) |
各族主文档的 YAML 保存属性真源,正文解释结构与策略;完整示例独立按需加载。索引和覆盖表由元数据生成,不维护重复的人工分类清单。
上述六族是离线资料入口。生成助手使用的新短规程、支持变体、参考/正式模型证据和缺口以`generation/catalog.json`、`generation/policy.json`及[七类补全报告](reports/five-samples-herringbone-20261112/README.md)为准;两种人字齿独立登记,不用带槽结构替代无槽连续结构。
## 快速运行
```bash
cd '/Users/lk/Projects/vibemake相关项目/community/knowledge/cad-parts'
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m cad_knowledge search '制作带筋轴承座'
.venv/bin/python -m cad_knowledge validate ribbed-bearing-housing --example
.venv/bin/python -m cad_knowledge generation-context involute-spur-gear --engine-build 5707e4ae25621c4a32c40108
```
如当前 Python 已有 PyYAML 与 jsonschema,可直接运行 `python3 -m cad_knowledge ...`。验证全部资料:
```bash
python3 -m cad_knowledge check
python3 -m cad_knowledge evaluate --report reports/acceptance.json
python3 -m unittest discover -s tests -v
```
文档修改后运行 `python3 -m cad_knowledge build` 更新分类视图、索引和覆盖清单。固定评测不需要网络或 Key。Skill 位于本目录,未自动安装到个人全局技能目录。
## 实际生成 A/B 测试
下述六族 CLI 程序保留用于复现历史实验;它自行运行工具循环,**不能代表 community 正式网页助手**。当前齿轮试点使用独立 `cad-generation-benchmark` 项目的网页脚本,复用正式助手,冻结原版指令、技能、工具、引擎和模型设置,仅 B 开放按需查询短操作规程。历史 B 的长文策略不作为当前正式生成的默认策略。
按照 [测试程序说明](benchmark/README.md) 配置本机 CLI 和豆包 Key 后运行:
```bash
python3 -m pip install -e '.[benchmark]'
python3 benchmark/run.py --out runs/doubao-ab-new
```
A 不加载零件族知识,B 加载对应零件族及共享特征;其余输入和预算相同。默认六族共 12 次生成,每次保存独立设计、逐轮模型与工具记录,以及 iso/top/front 截图。模型 HTTP 请求和 CAD 操作均不设置超时。
## 证据边界
分类目录覆盖不等于工程知识全覆盖。`retrieval_verified` 表示离线检索和参数规则验证,`geometry_validated=false`。真实生成测试的结果保存在各次运行目录,不自动提升知识文档的验证等级。自动检查只覆盖已实现的几何项目,单轮 A/B 结果不能证明总体成功率的提升。
-26
View File
@@ -1,26 +0,0 @@
---
name: cad-part-knowledge
description: 检索中文 CAD 零件分类、校验六族结构化参数,并按实际引擎版本选取已验证有生成收益的短操作规程。工程长文用于离线参考。
---
# CAD 零件知识检索与建模规划
分类与参数资料用于离线参考;生成补充文本单独准入。此入口不执行 CAD、不调用模型服务。
## 使用流程
1. 在本目录运行 `python3 -m cad_knowledge search '用户需求'`。读取候选、匹配依据和知识覆盖状态;完整分类图见[中文 Mermaid 分类树](references/classification/mcb-taxonomy-mermaid.zh-CN.md)。
2. 结合整段需求判断类别、否定范围、单/多零件和所需变体。检索结果不自动选类;通用“轴”“齿轮”等目录命中不能直接套用某个细分族。
3. 为正式生成取补充文本时,运行 `python3 -m cad_knowledge generation-context FAMILY_ID --engine-build ACTUAL_BUILD`。只注入返回的 `text`;为空时沿用原生成链路,不回退注入族长文。引擎版本必须来自当前能力信息,不猜测。检查返回清单与跳过原因。
4. 若任务是查阅工程资料或整理参数,可运行 `context FAMILY_ID`,再用 `validate FAMILY_ID --params request.json` 校验完整结构化对象。此处的 YAML、分类、完整示例不自动进入生成提示。不自动填示例尺寸,不静默降低精度。
5. 只有隔离的 A/B 试验才加 `generation-context ... --experimental` 读取候选规程,记录候选哈希及原生设计、工具过程和截图。候选成功回放不等于 LLM 读取后有收益。
可从[覆盖清单](references/coverage.md)查找六个族及支持边界。数学推导与示例通过族文档中的链接按需读取。
## 判断原则
用户需求优先于典型做法。族文档的“必须满足”只对所选试点轮廓生效;当前未覆盖的结构应保留原需求并报告缺口。分类名称不能代替工程定义,共享特征不能擅自扩大族范围。
修改需求应保留零件身份与参数依赖,重建完整参数对象并重新校验。文档和检索状态不证明 CAD 已成功生成,也不证明符合制造标准。
生成准入和文本保留标准见[生成文本规则](generation/README.md)。接口见[维护与接口说明](references/maintenance.md);新增离线工程资料前读取[统一模板](references/family-template.md)。
-70
View File
@@ -1,70 +0,0 @@
# 六族 A/B 实际生成测试
此程序保留为历史实验复现工具。其 B 组整包长文与自建工具循环不再作为正式生成的默认方案,也不等同于 community 网页助手。当前生成文本采用[单独准入](../generation/README.md),网页链路试验位于 `/Users/lk/Projects/cad-generation-benchmark/experiments/gear-recipe-20261111`。
`run.py` 从 Python **直接调用豆包 Chat Completions HTTP/SSE**,自行运行工具调用循环,并通过独立 `solidcraft-cli mcp --headless` 进程建模。生成链路不使用 Codex、ACP、makeCAD 内置聊天或任何其他模型。
每个零件的 A/B 条件使用独立模型会话与独立 CAD 进程。共同输入为相同需求、相同模型与思考设置、相同通用约定及该版本 CAD 的技术命令参考。B 额外读取对应族与共享特征,**不加载完整示例**。题目取自六个示例的“完整需求”;参数预期仅供运行后的评测使用。
## 配置
复制 `config.example.json` 为 `config.local.json`,填写本机 `solidcraft-cli` 路径。Key 可放在 `ARK_API_KEY` 环境变量中,也可通过 `env_file` 指向已有 `.env` 文件。读取文件不会执行其中的 shell 内容,Key 不写进模型提示、报告或命令行参数。
```json
{
"base_url": "https://ark.cn-beijing.volces.com/api/v3",
"model": "doubao-seed-2-1-lite-260915",
"api_key_env": "ARK_API_KEY",
"env_file": "/absolute/path/to/existing/.env",
"model_env": "CAD_AI_MODEL",
"cad_cli": "/absolute/path/to/solidcraft-cli",
"thinking": "disabled",
"reasoning_effort": null,
"max_tokens": 16000,
"max_model_turns": 48,
"workers": 2,
"views": ["iso", "top", "front"],
"image_width": 1200,
"image_height": 900
}
```
`model_env` 非空时从所选环境变量读取模型 ID;否则用 model。切换模型和思考设置后启动新一轮,不混用旧结果。thinking 可为 disabled、enabled、auto;reasoning_effort 仅在所选豆包版本支持时填写,拒绝时会原样记录错误,不静默换模型或降级思考程度。
模型请求、CAD 操作**均无超时截止时间**。max_tokens 是单次输出上限,max_model_turns 是两组相同的模型交互轮数预算,并非时间限制。达到预算会标记不完整并保留残留模型;服务端自身的超时也会记入错误。脚本不自动重发失败的生成请求。
## 运行
在知识库根目录执行。`python3 -m pip install -e '.[benchmark]'` 安装运行依赖;certifi 和 Pillow 用于证书与截图拼图。缺少 Pillow 时个别截图与 HTML 报告仍可用。
```bash
python3 benchmark/run.py --out runs/doubao-ab-001
python3 benchmark/run.py --out runs/doubao-ab-002 --repeat 3
python3 benchmark/run.py --out runs/plate-smoke --families mounting-plate --workers 1
python3 benchmark/run.py --out runs/doubao-ab-001 --report-only
python3 -m unittest discover -s benchmark -p 'test_*.py' -v
```
默认运行六族 × A/B × 1 次,共 12 个实际生成案例,最多两个案例并发。`--resume` 只跳过已经记录的案例,包括失败案例;不得用反复重跑覆盖失败来美化结果。配置或知识版本变化后应使用新输出目录。
## 产物
- `index.html`:A/B 截图并排页面,含结果、设计、测量与工具日志链接。
- `comparison.png`:来自实际渲染的六族 A/B 汇总图。
- `report.md`、`results.json`、`run-manifest.json`:状态、耗时、自动项结果、配置与知识文件哈希。
- `source-snapshot/`:该轮脚本与知识文档的源码快照;后续修改脚本不会覆盖原实验版本。新版程序还记录 CLI 的 SHA256,并拒绝在同一轮混用不同引擎文件。
- `r01/FAMILY_ID/A` 和 `B`:独立的案例记录。
每个案例保存原始需求、共同提示、B 组知识上下文及清单、逐轮请求与流式响应、完整对话、CAD 工具日志、原生 `.sc` 设计和可用时的 STEP。截图为实际模型渲染,包含 iso/top/front;轴承座和壳体另加剖视。三视图使用相同方向与分辨率,各模型自动适配画面,因此不能只凭屏幕大小判断尺寸。
失败也会尝试保存设计、测量和截图;截图可能显示不完整几何或空设计。模型说完成、工具无报错、成功保存和几何合格是不同结果,报告分别记录。
流式响应缺少结束标记时记录为传输不完整;输出长度截断或内容过滤时不执行该回复中的工具调用。原始流仍保留供诊断。
## 判断结果
自动检查包括可见实体数、闭合正体积、失败特征、已定义的包络尺寸、简单族解析体积,以及圆柱面的孔径/轴线/轴向范围。几何数据来自引擎,模型自述不作为测量证据。线性门限 0.05 mm、简单体积相对门限 0.2% 是测试检查门限,不是制造公差。
筋的全部连接、所有局部壁厚、真实渐开线误差、齿数和齿厚、六角头细项、壳盖精确面间距及参数修改行为尚未全面自动验证,均留在 manual_review_required 中。单次六族测试用于发现问题,不估计统计显著性或宣称完整建模成功率。
当前圆柱面检查比较轴线、半径和轴向跨度长度,**尚未自动比较该跨度的绝对起止位置或孔的开口方向**。因此,位于实体内部的封闭圆柱空腔也可能通过孔径/孔深检查,必须结合面拓扑、实际起止坐标或剖视复核。筋厚等未自动测量的尺寸也必须人工检查。
@@ -1,16 +0,0 @@
{
"base_url": "https://ark.cn-beijing.volces.com/api/v3",
"model": "doubao-seed-2-1-lite-260915",
"api_key_env": "ARK_API_KEY",
"env_file": null,
"model_env": null,
"cad_cli": "/absolute/path/to/solidcraft-cli",
"thinking": "disabled",
"reasoning_effort": null,
"max_tokens": 16000,
"max_model_turns": 48,
"workers": 2,
"views": ["iso", "top", "front"],
"image_width": 1200,
"image_height": 900
}
-649
View File
@@ -1,649 +0,0 @@
#!/usr/bin/env python3
"""Direct Doubao -> makeCAD CLI A/B benchmark. Never invokes Codex or ACP."""
from __future__ import annotations
import argparse
import base64
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime, timezone
import hashlib
import html
import json
import math
import os
from pathlib import Path
import re
import ssl
import subprocess
import sys
import threading
import time
import urllib.error
import urllib.request
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from cad_knowledge import KnowledgeBase # noqa: E402
FAMILIES = ["mounting-plate", "stepped-shaft", "hex-head-bolt", "ribbed-bearing-housing",
"involute-spur-gear", "covered-thin-wall-enclosure"]
ALLOWED_TOOLS = {"list_commands", "describe_command", "execute", "batch", "inspect_design",
"measure", "body_topology", "set_parameter", "check_parameters", "undo", "redo"}
PRINT_LOCK = threading.Lock()
RUNNER_VERSION = "0.2.0"
def sha256_file(path):
digest = hashlib.sha256()
with Path(path).open("rb") as source:
for block in iter(lambda: source.read(1024 * 1024), b""):
digest.update(block)
return digest.hexdigest()
def log(message):
with PRINT_LOCK:
print(f"[{datetime.now().astimezone().isoformat(timespec='seconds')}] {message}", flush=True)
def write_json(path, value):
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_suffix(path.suffix + ".tmp")
temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2, allow_nan=False) + "\n", encoding="utf-8")
temporary.replace(path)
def env_file(path):
result = {}
if not path:
return result
for line in Path(path).expanduser().read_text(encoding="utf-8").splitlines():
match = re.match(r"\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$", line)
if match:
key, value = match.groups()
if value.startswith(("'", '"')) and value.endswith(value[0]):
value = value[1:-1]
result[key] = value
return result
def load_config(path):
config = json.loads(Path(path).read_text(encoding="utf-8"))
values = {**env_file(config.get("env_file")), **os.environ}
key = values.get(config.get("api_key_env", "ARK_API_KEY"), "")
if not key:
raise ValueError("Doubao API key is missing; set api_key_env or env_file in local config")
if config.get("model_env"):
config["model"] = values.get(config["model_env"], config.get("model"))
if not config.get("model") or "doubao" not in config["model"].lower():
raise ValueError("This benchmark requires an explicit Doubao model ID")
config["cad_cli"] = str(Path(config["cad_cli"]).expanduser().resolve())
if not Path(config["cad_cli"]).is_file():
raise ValueError("cad_cli does not exist")
config.setdefault("max_model_turns", 48)
config.setdefault("max_tokens", 16000)
config.setdefault("workers", 2)
config.setdefault("thinking", "disabled")
config.setdefault("views", ["iso", "top", "front"])
config.setdefault("image_width", 1200)
config.setdefault("image_height", 900)
if config["thinking"] not in {"enabled", "disabled", "auto"}:
raise ValueError("thinking must be enabled, disabled or auto")
if not 1 <= config["workers"] <= 6 or not 1 <= config["max_model_turns"] <= 200:
raise ValueError("workers must be 1..6 and max_model_turns must be 1..200")
if not all(view in {"iso", "top", "front", "right", "back", "left", "bottom"} for view in config["views"]):
raise ValueError("views must be standard makeCAD view names")
config["api_key"] = key
return config
def public_config(config):
return {k: v for k, v in config.items() if k != "api_key"}
def redact(value, secret):
if isinstance(value, str):
return value.replace(secret, "[REDACTED]") if secret else value
if isinstance(value, list):
return [redact(item, secret) for item in value]
if isinstance(value, dict):
return {key: redact(item, secret) for key, item in value.items()}
return value
class MCP:
"""One private headless CAD process per condition; no UI chat backend."""
def __init__(self, executable, directory):
self.directory = Path(directory).resolve()
self.errors = (self.directory / "cad-stderr.log").open("w", encoding="utf-8")
self.events = (self.directory / "cad-events.jsonl").open("a", encoding="utf-8")
self.process = subprocess.Popen(
[executable, "mcp", "--headless", "--compact", "--allow-path", str(self.directory)],
stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=self.errors,
text=True, encoding="utf-8", cwd=self.directory)
self.counter = 0
self.initialization = self.rpc("initialize", {"protocolVersion": "2025-06-18", "capabilities": {},
"clientInfo": {"name": "doubao-cad-ab", "version": "0.1.0"}})
self.process.stdin.write(json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}) + "\n")
self.process.stdin.flush()
self.tools = self.rpc("tools/list", {})["tools"]
def rpc(self, method, params):
self.counter += 1
request = {"jsonrpc": "2.0", "id": self.counter, "method": method, "params": params}
started = time.monotonic()
self.process.stdin.write(json.dumps(request, ensure_ascii=False) + "\n")
self.process.stdin.flush()
while True:
line = self.process.stdout.readline()
if not line:
raise RuntimeError(f"CAD subprocess closed stdout (exit={self.process.poll()}); see cad-stderr.log")
reply = json.loads(line)
if reply.get("id") == self.counter:
break
# Image bytes stay in their PNGs, not duplicated into the tool log.
compact = json.loads(json.dumps(reply))
for item in compact.get("result", {}).get("content", []):
if item.get("type") == "image":
item["data"] = f"[base64 image, {len(item.get('data', ''))} chars]"
self.events.write(json.dumps({"request": request, "reply": compact,
"elapsed_s": time.monotonic() - started}, ensure_ascii=False) + "\n")
self.events.flush()
if "error" in reply:
raise RuntimeError(json.dumps(reply["error"], ensure_ascii=False))
return reply.get("result", {})
def call(self, name, arguments):
return self.rpc("tools/call", {"name": name, "arguments": arguments})
def close(self):
if self.process.poll() is None:
self.process.stdin.close()
try:
self.process.wait(timeout=5)
except subprocess.TimeoutExpired:
self.process.terminate()
self.process.wait()
self.errors.close()
self.events.close()
def tool_value(result):
texts = [item["text"] for item in result.get("content", []) if item.get("type") == "text"]
if len(texts) == 1:
try:
return json.loads(texts[0])
except json.JSONDecodeError:
return texts[0]
return texts
def tool_text(result):
return "\n".join(item["text"] for item in result.get("content", []) if item.get("type") == "text")
def stream_completion(config, messages, tools, directory, turn):
"""SSE request made directly to the configured provider, with no deadline."""
directory = Path(directory)
payload = {"model": config["model"], "messages": messages, "tools": tools,
"tool_choice": "auto", "stream": True, "max_tokens": config["max_tokens"],
"thinking": {"type": config["thinking"]}}
if config.get("reasoning_effort"):
payload["reasoning_effort"] = config["reasoning_effort"]
write_json(directory / f"request-{turn:03}.json", redact(payload, config["api_key"]))
request = urllib.request.Request(
config["base_url"].rstrip("/") + "/chat/completions",
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"), method="POST",
headers={"Content-Type": "application/json", "Authorization": "Bearer " + config["api_key"]})
try:
import certifi
context = ssl.create_default_context(cafile=certifi.where())
except ImportError:
context = ssl.create_default_context()
content, reasoning, calls, usage, finish = [], [], {}, None, None
with (directory / f"response-{turn:03}.jsonl").open("w", encoding="utf-8") as raw:
try:
# Explicitly no HTTP/request deadline. The provider may impose its own limits.
with urllib.request.urlopen(request, context=context, timeout=None) as response:
for line in response:
line = line.decode("utf-8").strip()
if not line.startswith("data:"):
continue
data = line[5:].strip()
if data == "[DONE]":
break
event = json.loads(data)
raw.write(json.dumps(redact(event, config["api_key"]), ensure_ascii=False) + "\n")
raw.flush()
if event.get("error"):
raise RuntimeError(json.dumps(event["error"], ensure_ascii=False))
if event.get("usage"):
usage = event["usage"]
for choice in event.get("choices", []):
if choice.get("finish_reason"):
finish = choice["finish_reason"]
delta = choice.get("delta", {})
if delta.get("content"):
content.append(delta["content"])
if delta.get("reasoning_content"):
reasoning.append(delta["reasoning_content"])
for item in delta.get("tool_calls", []):
index = item.get("index", 0)
current = calls.setdefault(index, {"id": "", "type": "function",
"function": {"name": "", "arguments": ""}})
if item.get("id"):
current["id"] = item["id"]
function = item.get("function", {})
current["function"]["name"] += function.get("name", "")
current["function"]["arguments"] += function.get("arguments", "")
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(redact(f"Doubao HTTP {exc.code}: {detail}", config["api_key"])) from None
if finish is None:
raise RuntimeError("Doubao stream ended without finish_reason; incomplete response retained")
if not content and not calls:
raise RuntimeError(f"Empty Doubao completion (finish_reason={finish})")
message = {"role": "assistant", "content": "".join(content) or None}
if calls:
message["tool_calls"] = [calls[index] for index in sorted(calls)]
result = {"message": message, "reasoning": "".join(reasoning), "usage": usage, "finish_reason": finish}
write_json(directory / f"completion-{turn:03}.json", redact(result, config["api_key"]))
return result
def extract_task(kb, family_id):
example = kb.documents[kb.families[family_id]["meta"]["example_id"]]
return example["body"].split("## 完整需求\n\n", 1)[1].split("\n\n## ", 1)[0].strip()
def base_prompt(kb, technical_reference):
return """You are building a CAD part in a private makeCAD headless session. Use only the provided
function tools to construct the requested geometry. This is an execution task, not a request for a plan.
Do not claim success until you actually inspect and measure the design. Read command contracts with
describe_command when needed; never invent commands or silently substitute requested structures.
Each independent call may use batch. Read a failed batch's index and fix the failure; avoid repeating
the entire build or retrying a command that is still running. Use named bodies and features.
Use engine geometry only; no external code execution, imported meshes or external CAD files.
The final response must state what was built, what is simplified or unsupported, and remaining errors.
The harness saves the design, measures it and captures screenshots after your final response; you do
not need to save files, export, render, choose a camera or change display appearance yourself.
Keep lengths in mm, Z up. The following common conventions and technical command reference are
identical for both conditions; any later family reference is additional knowledge, not a replacement
for the user's request. Do not load any complete worked example from a knowledge library.
""" + "\n\n" + kb.documents["common-conventions"]["body"] + "\n\n# CAD tool reference\n\n" + technical_reference
def run_agent(config, mcp, messages, directory, label):
schemas = [{"type": "function", "function": {"name": t["name"], "description": t["description"],
"parameters": t["inputSchema"]}} for t in mcp.tools if t["name"] in ALLOWED_TOOLS]
rounds, tool_errors, uses = 0, 0, []
history = Path(directory) / "conversation.json"
for turn in range(1, config["max_model_turns"] + 1):
rounds += 1
log(f"{label}: Doubao round {turn}")
completion = stream_completion(config, messages, schemas, directory, turn)
if completion.get("usage"):
uses.append(completion["usage"])
message = completion["message"]
messages.append(message)
calls = message.get("tool_calls", [])
if completion["finish_reason"] in {"length", "content_filter"}:
# Never execute a truncated tool-call prefix, even if it is valid JSON.
write_json(history, messages)
return {"ended": False, "stop_reason": completion["finish_reason"], "rounds": rounds,
"tool_errors": tool_errors, "usage": uses, "final_reply": message.get("content")}
if not calls:
write_json(history, messages)
return {"ended": completion["finish_reason"] == "stop",
"stop_reason": completion["finish_reason"], "rounds": rounds,
"tool_errors": tool_errors, "usage": uses, "final_reply": message.get("content")}
for call in calls:
name = call["function"]["name"]
log(f"{label}: {name}")
try:
arguments = json.loads(call["function"]["arguments"])
if name not in ALLOWED_TOOLS:
raise ValueError("Tool is outside this benchmark's advertised set")
result = mcp.call(name, arguments)
tool_errors += int(result.get("isError", False))
text = tool_text(result)
except (ValueError, RuntimeError) as exc:
tool_errors += 1
text = json.dumps({"error": str(exc)}, ensure_ascii=False)
messages.append({"role": "tool", "tool_call_id": call["id"], "content": text})
write_json(history, messages)
return {"ended": False, "stop_reason": "model_turn_budget", "rounds": rounds,
"tool_errors": tool_errors, "usage": uses, "final_reply": None}
def cylinder_matches(cylinder, radius, axis, origin, extent=None, tolerance=0.05):
if abs(cylinder.get("radius", -1) - radius) > tolerance:
return False
actual_axis = cylinder.get("axis", [])
if len(actual_axis) != 3 or abs(sum(a*b for a, b in zip(actual_axis, axis))) < 0.999:
return False
actual = cylinder.get("origin", [math.inf] * 3)
delta = [a-b for a, b in zip(actual, origin)]
parallel = sum(a*b for a, b in zip(delta, axis))
if math.sqrt(sum((a-parallel*b)**2 for a, b in zip(delta, axis))) > tolerance:
return False
if extent is not None:
ends = cylinder.get("extent", [])
if len(ends) != 2 or abs(abs(ends[1]-ends[0]) - extent) > tolerance:
return False
return True
def assess(family_id, params, derived, inspection, measurement, topologies):
"""Partial automatic geometry gates. Unmeasured properties remain explicit."""
checks = []
def check(name, passed, actual=None, expected=None):
checks.append({"name": name, "passed": bool(passed), "actual": actual, "expected": expected})
bodies = [b for b in inspection.get("bodies", []) if b.get("visible", True)] if isinstance(inspection, dict) else []
expected_count = 2 if family_id == "covered-thin-wall-enclosure" else 1
check("visible_body_count", len(bodies) == expected_count, len(bodies), expected_count)
measured = measurement.get("bodies", []) if isinstance(measurement, dict) else []
visible_names = {b["name"] for b in bodies}
measured = [b for b in measured if b.get("name") in visible_names]
check("closed_positive_solids", bool(measured) and len(measured) == len(bodies) and
all(b.get("closed") is True and b.get("volume_mm3", 0) > 0 for b in measured))
errors = [f for f in inspection.get("timeline", []) if f.get("error")] if isinstance(inspection, dict) else []
check("no_failed_timeline_features", not errors, errors)
if measured:
low = [min(b["bbox"]["min"][i] for b in measured) for i in range(3)]
high = [max(b["bbox"]["max"][i] for b in measured) for i in range(3)]
size = [h-l for h, l in zip(high, low)]
if family_id == "mounting-plate":
expected = [params["length"], params["width"], params["thickness"]]
elif family_id == "stepped-shaft":
expected = [derived["max_diameter"], derived["max_diameter"], derived["total_length"]]
elif family_id == "hex-head-bolt":
expected = None # Hexagon orientation is not fixed in the original request.
check("axial_total_length", abs(size[2] - derived["total_length"]) <= 0.05, size[2], derived["total_length"])
elif family_id == "ribbed-bearing-housing":
expected = [params["base_length"], params["base_width"], derived["total_height"]]
elif family_id == "involute-spur-gear":
expected = None # Angular orientation changes the XY bounding box slightly.
check("axial_total_length", abs(size[2] - derived["total_length"]) <= 0.05, size[2], derived["total_length"])
check("outside_envelope", all(abs(v-derived["addendum_diameter"]) < 0.5 for v in size[:2]), size[:2], derived["addendum_diameter"])
else:
expected = [params["outer_length"], params["outer_width"], derived["total_height"]]
if expected:
check("bounding_box_dimensions", all(abs(a-b) <= 0.05 for a, b in zip(size, expected)), size, expected)
if "volume" in derived:
volume = sum(b["volume_mm3"] for b in measured)
# 0.2% is an engine measurement gate, not a manufacturing tolerance.
check("analytic_volume", math.isclose(volume, derived["volume"], rel_tol=0.002, abs_tol=0.05), volume, derived["volume"])
cylinders = [c for topo in topologies.values() if isinstance(topo, dict) for c in topo.get("cylinders", [])]
def cyl(name, radius, axis, origin, extent=None):
check(name, any(cylinder_matches(c, radius, axis, origin, extent) for c in cylinders),
expected={"radius": radius, "axis": axis, "origin": origin, "extent_length": extent})
if family_id == "mounting-plate":
for i, h in enumerate(derived["holes"]):
cyl(f"hole_{i+1}_axis_radius_extent", h["diameter"]/2, [0, 0, 1], [h["x"], h["y"], 0], params["thickness"])
elif family_id == "stepped-shaft":
for i, segment in enumerate(params["segments"]):
cyl(f"shaft_segment_{i+1}", segment["diameter"]/2, [0, 0, 1], [0, 0, 0], segment["length"])
elif family_id == "hex-head-bolt":
cyl("nominal_shank", params["nominal_diameter"]/2, [0, 0, 1], [0, 0, 0], params["under_head_length"])
elif family_id == "ribbed-bearing-housing":
cyl("horizontal_bearing_bore", params["bore_diameter"]/2, [0, 1, 0], [0, 0, params["center_height"]])
if params.get("counterbore"):
cyl("counterbore_axis_radius", params["counterbore"]["diameter"]/2, [0, 1, 0], [0, 0, params["center_height"]], params["counterbore"]["depth"])
for i, h in enumerate(params["mount_holes"]):
cyl(f"vertical_mounting_hole_{i+1}", h["diameter"]/2, [0, 0, 1], [h["x"], h["y"], 0], params["base_thickness"])
elif family_id == "involute-spur-gear":
cyl("hub_outer_radius", params["hub_diameter"]/2, [0, 0, 1], [0, 0, 0])
cyl("axial_bore_radius", params["bore_diameter"]/2, [0, 0, 1], [0, 0, 0])
else:
for i, centre in enumerate(derived["fastener_centers"]):
for role, diameter, extent in [("boss_pilot", params["boss_pilot_diameter"], params["pilot_depth"]),
("lid_clearance", params["cover_hole_diameter"], params["lid_thickness"])]:
cyl(f"{role}_{i+1}", diameter/2, [0, 0, 1], [centre["x"], centre["y"], 0], extent)
manual = {
"mounting-plate": ["No unintended extra features; confirm exact outer origin and bore material side"],
"stepped-shaft": ["Check shoulder axial positions and native parameter-edit behaviour"],
"hex-head-bolt": ["Check regular hexagon across flats/head height and simplified-thread semantic marking"],
"ribbed-bearing-housing": ["Check both rib profiles, their connections, all local wall thicknesses and counterbore side"],
"involute-spur-gear": ["Verify 24 teeth, involute deviation, pitch-circle tooth thickness, keyway sizes and disclosed root simplification"],
"covered-thin-wall-enclosure": ["Check cavity dimensions, four rib connections, actual cover plane gap and shared interface dependencies"],
}[family_id]
return {"automatic_checks_passed": bool(checks) and all(c["passed"] for c in checks),
"checks": checks, "manual_review_required": manual, "full_geometry_certified": False,
"linear_check_tolerance_mm": 0.05, "volume_relative_tolerance": 0.002}
def capture(mcp, config, directory, family_id):
results = {}
for view in config["views"]:
path = Path(directory) / f"{view}.png"
result = mcp.call("screenshot", {"source": "model", "view": view, "path": str(path),
"grid": False, "axes": False, "width": config["image_width"], "height": config["image_height"]})
results[view] = {"path": path.name, "ok": path.exists() and not result.get("isError"), "info": tool_value(result)}
if family_id in {"ribbed-bearing-housing", "covered-thin-wall-enclosure"}:
plane = "YZ" if family_id == "ribbed-bearing-housing" else "XZ"
section = mcp.call("execute", {"command": "inspect.section", "params": {"plane": plane}})
if not section.get("isError"):
path = Path(directory) / "section.png"
result = mcp.call("screenshot", {"source": "model", "view": "iso", "path": str(path),
"grid": False, "axes": False, "width": config["image_width"], "height": config["image_height"]})
results["section"] = {"path": path.name, "ok": path.exists() and not result.get("isError"), "info": tool_value(result)}
mcp.call("execute", {"command": "inspect.section", "params": {"clear": True}})
return results
def run_case(config, kb, family_id, condition, directory, repeat):
directory = Path(directory).resolve()
directory.mkdir(parents=True, exist_ok=True)
started = time.monotonic()
label = f"{family_id}/{condition}/r{repeat}"
summary = {"family_id": family_id, "condition": condition, "repeat": repeat,
"model": config["model"], "thinking": config["thinking"], "status": "running",
"directory": str(directory), "provider_called_directly": True, "codex_used_for_generation": False}
write_json(directory / "result.json", summary)
mcp = None
try:
if config.get("cad_cli_sha256") and sha256_file(config["cad_cli"]) != config["cad_cli_sha256"]:
raise RuntimeError("CAD executable changed during this run; refusing to mix engine versions")
mcp = MCP(config["cad_cli"], directory)
# The runtime binary owns the technical contract, so its matching reference is used.
reference = None
for skill in ("makecad-modeling", "solidcraft-modeling"):
value = mcp.call("skill_reference", {"skill": skill, "file": "reference.md"})
if not value.get("isError"):
reference = tool_value(value)
if isinstance(reference, dict):
reference = json.dumps(reference, ensure_ascii=False)
if isinstance(reference, str) and reference.strip():
break
if not reference:
raise RuntimeError("No matching runtime command reference available")
system = base_prompt(kb, reference)
(directory / "common-prompt.md").write_text(system, encoding="utf-8")
messages = [{"role": "system", "content": system}]
if condition == "B":
context = kb.build_context([family_id], include_examples=False)
# common-conventions is already identical in both system prompts.
family_context = context["text"].split("\n\n---\n\n", 1)[1]
messages.append({"role": "system", "content": "Additional engineering reference; use only within the user's requested scope:\n\n" + family_context})
write_json(directory / "knowledge-manifest.json", context["manifest"])
(directory / "knowledge-context.md").write_text(family_context, encoding="utf-8")
else:
write_json(directory / "knowledge-manifest.json", [])
task = extract_task(kb, family_id)
(directory / "task.md").write_text(task + "\n", encoding="utf-8")
messages.append({"role": "user", "content": task})
summary["agent"] = run_agent(config, mcp, messages, directory, label)
summary["status"] = "completed" if summary["agent"]["ended"] else "budget_or_provider_stop"
except Exception as exc:
summary["status"] = "error"
summary["error"] = redact(f"{type(exc).__name__}: {exc}", config["api_key"])
log(f"{label}: {summary['error']}")
finally:
if mcp is not None:
for stage in ("inspect", "measure", "save", "export", "screenshots", "assessment"):
try:
if stage == "inspect":
result = mcp.call("inspect_design", {"measure": True, "sketches": False})
inspection = tool_value(result)
write_json(directory / "inspection.json", inspection)
elif stage == "measure":
measurement = tool_value(mcp.call("measure", {}))
write_json(directory / "measurement.json", measurement)
topologies = {}
for body in inspection.get("bodies", []) if isinstance(inspection, dict) else []:
topologies[body["name"]] = tool_value(mcp.call("body_topology", {"body": body["name"], "faces": "cylinders"}))
write_json(directory / "cylinders.json", topologies)
elif stage == "save":
result = mcp.call("save", {"path": str(directory / "design.sc")})
summary["native_saved"] = (directory / "design.sc").exists() and not result.get("isError")
elif stage == "export":
result = mcp.call("export", {"path": str(directory / "design.step")})
summary["step_exported"] = (directory / "design.step").exists() and not result.get("isError")
if result.get("isError"):
summary["export_error"] = tool_value(result)
elif stage == "screenshots":
summary["screenshots"] = capture(mcp, config, directory, family_id)
else:
example = kb.documents[kb.families[family_id]["meta"]["example_id"]]["meta"]
derived = kb.validate_params(family_id, example["params"])["derived"]
summary["assessment"] = assess(family_id, example["params"], derived, inspection, measurement, topologies)
write_json(directory / "assessment.json", summary["assessment"])
except Exception as exc:
summary.setdefault("artifact_errors", {})[stage] = redact(str(exc), config["api_key"])
mcp.close()
summary["elapsed_s"] = round(time.monotonic() - started, 3)
write_json(directory / "result.json", redact(summary, config["api_key"]))
log(f"{label}: {summary['status']}, {summary['elapsed_s']} s")
return summary
def report(directory):
directory = Path(directory).resolve()
results = [json.loads(p.read_text()) for p in sorted(directory.glob("r*/*/[AB]/result.json"))]
write_json(directory / "results.json", results)
rows = ["# 六类零件:豆包直接调用 A/B 生成记录", "",
"A:共同技术说明与通用流程。B:额外加载对应零件族与共享特征,不加载完整示例。每个条件独立进程、独立会话。",
"请求由 Python 直接发送给豆包,使用 makeCAD 命令行 MCP;生成链路不调用 Codex、ACP 或 makeCAD 内置聊天。",
"自动几何检查为部分检查,完整结构与齿形等仍需人工核对。不能据此报告全面建模成功率。", "",
"| 零件 | 组 | 状态 | 自动项通过/总数 | 耗时秒 | 截图 |", "| --- | --- | --- | --- | ---: | --- |"]
cards = []
for result in results:
path = Path(result["directory"]).relative_to(directory).as_posix()
checks = result.get("assessment", {}).get("checks", [])
count = f"{sum(c['passed'] for c in checks)}/{len(checks)}" if checks else "未测量"
pictures = result.get("screenshots", {})
links = " ".join(f"[{view}]({path}/{value['path']})" for view, value in pictures.items() if value["ok"])
rows.append(f"| {result['family_id']} | {result['condition']} | {result['status']} | {count} | {result.get('elapsed_s', 0)} | {links} |")
failed = [c["name"] for c in checks if not c["passed"]]
rows += []
image = f'<img src="{html.escape(path)}/iso.png" loading="lazy">' if pictures.get("iso", {}).get("ok") else '<p>未取得截图</p>'
details = html.escape(json.dumps({"failed_checks": failed, "error": result.get("error"),
"manual_review": result.get("assessment", {}).get("manual_review_required", [])}, ensure_ascii=False, indent=2))
cards.append(f'<article><h2>{html.escape(result["family_id"])} · {result["condition"]} · r{result["repeat"]}</h2>{image}<p>{html.escape(result["status"])} · {count} 自动检查 · {result.get("elapsed_s",0)} s</p><p><a href="{path}/result.json">结果</a> · <a href="{path}/design.sc">设计</a> · <a href="{path}/measurement.json">测量</a> · <a href="{path}/cad-events.jsonl">工具日志</a></p><details><summary>失败项和待核对项</summary><pre>{details}</pre></details></article>')
rows += ["", "## 查看记录", "", "[并排截图页面](index.html) · [全部结果 JSON](results.json) · [运行配置与来源快照](run-manifest.json)",
"", "每个案例目录保留 task.md、common-prompt.md、B 组知识上下文、逐轮请求/SSE 响应、conversation.json、cad-events.jsonl、measurement.json、assessment.json、design.sc 和实际截图。失败案例同样记录残留模型。"]
(directory / "report.md").write_text("\n".join(rows) + "\n", encoding="utf-8")
(directory / "index.html").write_text('<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>豆包 CAD A/B 对照</title><style>body{font:15px system-ui;margin:24px;background:#f3f5f7;color:#18212b}main{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:20px}article{background:white;padding:16px;border-radius:10px}h2{font-size:16px}img{width:100%;height:auto}pre{white-space:pre-wrap}a{color:#1756a9}</style><h1>六类零件:豆包 A/B 生成记录</h1><p>A:共同说明;B:增加零件知识。截图来自实际 makeCAD 渲染。自动检查只覆盖已实现的部分几何要求。</p><main>' + "\n".join(cards) + '</main></html>', encoding="utf-8")
try:
from PIL import Image, ImageDraw, ImageFont
font = ImageFont.truetype("/System/Library/Fonts/Supplemental/Arial.ttf", 18)
cell_w, cell_h = 600, 490
sheet = Image.new("RGB", (cell_w * 2, cell_h * max(1, (len(results)+1)//2)), "#edf0f3")
draw = ImageDraw.Draw(sheet)
for index, result in enumerate(results):
x, y = (index % 2) * cell_w, (index // 2) * cell_h
draw.text((x+12, y+10), f"{result['family_id']} / {result['condition']}", fill="#18212b", font=font)
path = Path(result["directory"]) / "iso.png"
if path.exists():
with Image.open(path) as im:
im = im.convert("RGB")
im.thumbnail((cell_w-20, cell_h-45))
sheet.paste(im, (x+(cell_w-im.width)//2, y+38))
sheet.save(directory / "comparison.png")
except (ImportError, OSError) as exc:
log(f"Contact sheet unavailable; individual PNGs and HTML are intact: {exc}")
return results
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--config", type=Path, default=ROOT / "benchmark/config.local.json")
parser.add_argument("--out", type=Path)
parser.add_argument("--families", nargs="+", choices=FAMILIES, default=FAMILIES)
parser.add_argument("--conditions", nargs="+", choices=["A", "B"], default=["A", "B"])
parser.add_argument("--repeat", type=int, default=1)
parser.add_argument("--workers", type=int)
parser.add_argument("--resume", action="store_true", help="Skip all recorded cases, including failures; never silently rerun a failed trial")
parser.add_argument("--report-only", action="store_true")
args = parser.parse_args()
output = (args.out or ROOT / "runs" / datetime.now().astimezone().strftime("doubao-ab-%Y%m%d-%H%M%S")).resolve()
if args.report_only:
report(output)
return 0
config = load_config(args.config)
config["cad_cli_sha256"] = sha256_file(config["cad_cli"])
if args.workers:
if not 1 <= args.workers <= 6:
parser.error("--workers must be 1..6")
config["workers"] = args.workers
if not 1 <= args.repeat <= 100:
parser.error("--repeat must be 1..100")
if output.exists() and any(output.iterdir()) and not args.resume:
parser.error("Output is nonempty; choose a new directory or --resume")
output.mkdir(parents=True, exist_ok=True)
kb = KnowledgeBase(ROOT)
manifest_path = output / "run-manifest.json"
source_files = {str(p.relative_to(ROOT)): hashlib.sha256(p.read_bytes()).hexdigest()
for folder in ["cad_knowledge", "references", "schemas", "benchmark"]
for p in sorted((ROOT/folder).rglob('*')) if p.is_file() and '__pycache__' not in p.parts and p.name != "config.local.json"}
manifest = {"created_at": datetime.now(timezone.utc).isoformat(), "runner_version": RUNNER_VERSION,
"config": public_config(config),
"families": args.families, "conditions": args.conditions, "repeat": args.repeat,
"source_hashes": source_files, "generation_provider": "Doubao direct HTTP SSE",
"http_timeout": None, "cad_operation_timeout": None, "full_examples_loaded": False,
"codex_used_for_generation": False}
if manifest_path.exists():
old = json.loads(manifest_path.read_text())
for key in ["config", "families", "conditions", "repeat", "source_hashes"]:
if old[key] != manifest[key]:
raise ValueError(f"Cannot resume with changed {key}; start a new run")
else:
write_json(manifest_path, manifest)
for name in source_files:
snapshot = output / "source-snapshot" / name
snapshot.parent.mkdir(parents=True, exist_ok=True)
snapshot.write_bytes((ROOT / name).read_bytes())
jobs = []
for repeat in range(1, args.repeat+1):
for family in args.families:
for condition in args.conditions:
directory = output / f"r{repeat:02}" / family / condition
if args.resume and (directory / "result.json").exists():
prior = json.loads((directory / "result.json").read_text())
if prior.get("status") != "running":
continue
raise ValueError(f"Interrupted trial exists at {directory}; preserve it and start a new run")
jobs.append((family, condition, directory, repeat))
log(f"Starting {len(jobs)} isolated trials; model={config['model']}, thinking={config['thinking']}, workers={config['workers']}; out={output}")
try:
with ThreadPoolExecutor(max_workers=config["workers"]) as pool:
futures = [pool.submit(run_case, config, kb, *job) for job in jobs]
for future in as_completed(futures):
future.result()
report(output)
finally:
results = report(output)
log(f"Recorded {len(results)} trials: {output / 'report.md'}")
return 0 if all(r["status"] == "completed" for r in results) else 1
if __name__ == "__main__":
raise SystemExit(main())
@@ -1,120 +0,0 @@
"""Transport and artifact tests; no paid model calls in the test suite."""
import importlib.util
import json
from pathlib import Path
import tempfile
import unittest
from unittest.mock import patch
SPEC = importlib.util.spec_from_file_location("cad_ab_runner", Path(__file__).with_name("run.py"))
runner = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(runner)
class Response:
def __init__(self, events):
self.events = events
def __enter__(self):
return self
def __exit__(self, *_args):
pass
def __iter__(self):
for event in self.events:
yield ("data: " + json.dumps(event) + "\n\n").encode()
yield b"data: [DONE]\n\n"
class RunnerTests(unittest.TestCase):
def test_stream_assembles_fragmented_tool_calls_without_request_deadline(self):
config = {"model": "doubao-test", "max_tokens": 100, "thinking": "disabled",
"api_key": "private-test-key", "base_url": "https://example.invalid/v3"}
events = [
{"choices": [{"delta": {"tool_calls": [{"index": 0, "id": "call-1", "function": {"name": "execute", "arguments": '{"command":'}}]}}]},
{"choices": [{"delta": {"tool_calls": [{"index": 0, "function": {"arguments": '"solid.box","params":{}}'}}]}, "finish_reason": "tool_calls"}]},
{"choices": [], "usage": {"total_tokens": 12}},
]
with tempfile.TemporaryDirectory() as directory:
with patch.object(runner.urllib.request, "urlopen", return_value=Response(events)) as opener:
result = runner.stream_completion(config, [], [], directory, 1)
self.assertIsNone(opener.call_args.kwargs["timeout"])
request = opener.call_args.args[0]
self.assertEqual(request.get_header("Authorization"), "Bearer private-test-key")
self.assertEqual(json.loads(request.data)["model"], "doubao-test")
self.assertEqual(result["message"]["tool_calls"][0]["function"]["name"], "execute")
self.assertEqual(json.loads(result["message"]["tool_calls"][0]["function"]["arguments"])["command"], "solid.box")
self.assertEqual(result["usage"]["total_tokens"], 12)
for path in Path(directory).iterdir():
self.assertNotIn("private-test-key", path.read_text())
def test_no_family_examples_leak_into_base_or_condition_context(self):
kb = runner.KnowledgeBase(runner.ROOT)
prompt = runner.base_prompt(kb, "engine reference")
self.assertNotIn("example-mounting-plate", prompt)
self.assertNotIn("parameter_schema", prompt)
context = kb.build_context(["involute-spur-gear"], include_examples=False)
ids = [item["doc_id"] for item in context["manifest"]]
self.assertIn("involute-spur-gear", ids)
self.assertFalse(any(item.startswith("example-") for item in ids))
def test_incomplete_stream_is_not_treated_as_a_final_answer(self):
config = {"model": "doubao-test", "max_tokens": 100, "thinking": "disabled",
"api_key": "private-test-key", "base_url": "https://example.invalid/v3"}
events = [{"choices": [{"delta": {"content": "partial answer"}}]}]
with tempfile.TemporaryDirectory() as directory:
with patch.object(runner.urllib.request, "urlopen", return_value=Response(events)):
with self.assertRaisesRegex(RuntimeError, "without finish_reason"):
runner.stream_completion(config, [], [], directory, 1)
self.assertTrue((Path(directory) / "response-001.jsonl").exists())
self.assertFalse((Path(directory) / "completion-001.json").exists())
def test_truncated_response_never_executes_tool_calls(self):
class CAD:
tools = []
def call(self, *_args):
raise AssertionError("A truncated response must not execute any tool")
completion = {"message": {"role": "assistant", "content": None, "tool_calls": [
{"id": "partial", "function": {"name": "execute", "arguments": "{}"}}]},
"finish_reason": "length"}
with tempfile.TemporaryDirectory() as directory:
with patch.object(runner, "stream_completion", return_value=completion):
result = runner.run_agent({"max_model_turns": 2}, CAD(), [], directory, "test")
self.assertFalse(result["ended"])
self.assertEqual(result["stop_reason"], "length")
def test_cylinder_check_compares_axes_not_arbitrary_axis_origin_coordinate(self):
cylinder = {"radius": 3, "axis": [0, 0, -1], "origin": [35, 15, 20], "extent": [12, 20]}
self.assertTrue(runner.cylinder_matches(cylinder, 3, [0, 0, 1], [35, 15, 0], 8))
self.assertFalse(runner.cylinder_matches(cylinder, 3, [0, 0, 1], [34, 15, 0], 8))
self.assertFalse(runner.cylinder_matches(cylinder, 3, [0, 1, 0], [35, 15, 0], 8))
def test_geometry_gates_fail_empty_design_and_keep_manual_checks(self):
kb = runner.KnowledgeBase(runner.ROOT)
params = kb.documents["example-mounting-plate"]["meta"]["params"]
derived = kb.validate_params("mounting-plate", params)["derived"]
result = runner.assess("mounting-plate", params, derived, {"bodies": [], "timeline": []}, {"bodies": []}, {})
self.assertFalse(result["automatic_checks_passed"])
self.assertTrue(result["manual_review_required"])
self.assertFalse(result["full_geometry_certified"])
def test_environment_file_is_parsed_as_data_not_executed(self):
with tempfile.TemporaryDirectory() as directory:
path = Path(directory) / ".env"
path.write_text("ARK_API_KEY='key'\nMODEL=doubao-test\nNOEXEC=$(touch forbidden)\n")
parsed = runner.env_file(path)
self.assertEqual(parsed["ARK_API_KEY"], "key")
self.assertEqual(parsed["NOEXEC"], "$(touch forbidden)")
self.assertFalse((Path(directory) / "forbidden").exists())
def test_public_manifest_removes_api_key(self):
self.assertEqual(runner.public_config({"api_key": "secret", "model": "doubao-test"}), {"model": "doubao-test"})
self.assertEqual(runner.redact({"detail": ["echo secret"]}, "secret"), {"detail": ["echo [REDACTED]"]})
if __name__ == "__main__":
unittest.main()
@@ -1,7 +0,0 @@
"""Offline, engine-independent CAD part knowledge. No model calls."""
from .library import KnowledgeBase
__version__ = "0.1.0"
__all__ = ["KnowledgeBase"]
@@ -1,93 +0,0 @@
"""Command-line access; read-only unless build or --report is requested."""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
import yaml
from jsonschema.exceptions import SchemaError, ValidationError
from .library import KnowledgeBase
from .render import build, generated_outputs
from .evaluation import evaluate
def _reject_constant(value):
raise ValueError(f"JSON non-finite constant is not allowed: {value}")
def main(argv=None):
parser = argparse.ArgumentParser(description="Offline CAD part knowledge")
parser.add_argument("--root", type=Path, help="Source checkout containing references/ and schemas/")
commands = parser.add_subparsers(dest="command", required=True)
search = commands.add_parser("search")
search.add_argument("query")
context = commands.add_parser("context")
context.add_argument("family_ids", nargs="+")
context.add_argument("--features", nargs="*", default=[])
context.add_argument("--examples", action="store_true")
context.add_argument("--format", choices=["json", "markdown"], default="json")
generation = commands.add_parser("generation-context", help="Admitted generation text only",
description="Offline text loader for registered generation type IDs and legacy family IDs; checks admission and hashes, not deployment versions or variant applicability conditions.")
generation.add_argument("family_ids", nargs="+", metavar="TYPE_OR_FAMILY_ID")
generation.add_argument("--engine-build", help="Optional diagnostic deployment label; never a loading condition")
generation.add_argument("--experimental", action="store_true", help="Explicit opt-in for isolated A/B trials")
generation.add_argument("--format", choices=["json", "markdown"], default="json")
validate = commands.add_parser("validate")
validate.add_argument("family_id")
inputs = validate.add_mutually_exclusive_group(required=True)
inputs.add_argument("--params", type=Path)
inputs.add_argument("--example", action="store_true")
commands.add_parser("check")
commands.add_parser("build")
evaluation = commands.add_parser("evaluate")
evaluation.add_argument("--report", type=Path)
args = parser.parse_args(argv)
try:
kb = KnowledgeBase(args.root)
if args.command == "search":
result = kb.search(args.query)
elif args.command == "context":
result = kb.build_context(args.family_ids, args.features, args.examples)
if args.format == "markdown":
print(result["text"])
return 0
elif args.command == "generation-context":
result = kb.build_generation_context(args.family_ids, args.engine_build,
experimental=args.experimental)
if args.format == "markdown":
print(result["text"], end="\n" if result["text"] else "")
return 0
elif args.command == "validate":
if args.example:
family = kb._require(args.family_id, "family")
params = kb.documents[family["meta"]["example_id"]]["meta"]["params"]
else:
params = json.loads(args.params.read_text(encoding="utf-8"), parse_constant=_reject_constant)
result = kb.validate_params(args.family_id, params)
elif args.command == "build":
result = build(kb)
elif args.command == "check":
result = kb.check()
for relative, expected in generated_outputs(kb).items():
file = kb.root / relative
if not file.exists() or file.read_text(encoding="utf-8") != expected:
result["errors"].append(f"Generated output missing/stale: {relative}; run build")
result["passed"] = not result["errors"]
else:
result = evaluate(kb)
if args.report:
args.report.parent.mkdir(parents=True, exist_ok=True)
args.report.write_text(json.dumps(result, ensure_ascii=False, indent=2, allow_nan=False) + "\n", encoding="utf-8")
print(json.dumps(result, ensure_ascii=False, indent=2, allow_nan=False))
return 0 if result.get("passed", result.get("valid", True)) else 1
except (OSError, ValueError, KeyError, yaml.YAMLError, SchemaError, ValidationError) as exc:
print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
return 2
if __name__ == "__main__":
sys.exit(main())
@@ -1,74 +0,0 @@
"""Fixed, offline requirement scenarios with explicit expected outcomes."""
from __future__ import annotations
import copy
import json
import math
from collections import Counter
from datetime import datetime, timezone
def equivalent(actual, expected):
if isinstance(expected, (int, float)) and not isinstance(expected, bool):
return isinstance(actual, (int, float)) and not isinstance(actual, bool) and math.isclose(actual, expected, rel_tol=1e-9, abs_tol=1e-9)
return actual == expected
def evaluate(kb):
cases = json.loads((kb.root / "evals/cases.json").read_text(encoding="utf-8"))
outcomes = []
for case in cases:
failures = []
try:
expect = case["expect"]
if case["action"] == "search":
actual = kb.search(case["query"])
ids = {c["family_id"] for c in actual["candidates"]}
if not set(expect.get("includes", [])).issubset(ids):
failures.append("Missing expected family candidate")
if expect.get("no_candidates") and ids:
failures.append("Unexpected specialized family for uncovered/broad query")
if not set(expect.get("flags", [])).issubset(actual["flags"]):
failures.append("Missing semantic-review flag")
if not set(expect.get("category_ids", [])).issubset({c["node_id"] for c in actual["category_hits"]}):
failures.append("Missing expected catalog entry")
if actual["selected_family_id"] is not None or not actual["needs_semantic_review"]:
failures.append("Retrieval must not make final selection")
elif case["action"] == "validate":
fid = case["family_id"]
example_id = kb.families[fid]["meta"]["example_id"]
params = copy.deepcopy(kb.documents[example_id]["meta"]["params"])
for edit in case.get("edits", []):
target = params
for key in edit["path"][:-1]:
target = target[key]
if edit.get("remove"):
del target[edit["path"][-1]]
else:
target[edit["path"][-1]] = edit["value"]
actual = kb.validate_params(fid, params)
if actual["valid"] != expect["valid"]:
failures.append(f"Expected valid={expect['valid']}, got {actual['valid']}")
if expect.get("group") and not actual[expect["group"]]:
failures.append(f"Expected diagnostic group: {expect['group']}")
for key, expected in expect.get("derived", {}).items():
if not equivalent(actual["derived"].get(key), expected):
failures.append(f"Derived expectation failed: {key}")
if actual["geometry_validated"]:
failures.append("Offline validation cannot claim CAD evidence")
else:
raise ValueError(f"Unknown action: {case['action']}")
outcomes.append({"id": case["id"], "group": case["group"], "scenario": case["scenario"],
"passed": not failures, "failures": failures, "actual": actual})
except (ValueError, KeyError, TypeError, IndexError) as exc:
outcomes.append({"id": case["id"], "group": case["group"], "scenario": case["scenario"],
"passed": False, "failures": [str(exc)]})
unique_ids = len({case["id"] for case in cases}) == len(cases)
counts = dict(Counter(case["group"] for case in cases))
structure_valid = len(cases) == 60 and unique_ids and counts == {"family": 36, "general": 12, "complex": 12}
return {"version": "0.1.0", "evaluated_at": datetime.now(timezone.utc).isoformat(),
"passed": structure_valid and all(o["passed"] for o in outcomes),
"case_count": len(cases), "passed_count": sum(o["passed"] for o in outcomes),
"group_counts": counts, "case_structure_valid": structure_valid,
"geometry_validated": False, "outcomes": outcomes}
@@ -1,104 +0,0 @@
"""Load admitted text by registered generation type or legacy family ID.
This offline loader checks document admission and integrity.
It does not resolve free-text queries or evaluate variant applicability facts;
the production CAD assistant's knowledge router remains a separate interface.
"""
from __future__ import annotations
import hashlib
import json
import re
def _generation_ids(kb):
ids = set(kb.families)
path = kb.root / "generation/catalog.json"
if not path.exists():
return ids
catalog = json.loads(path.read_text(encoding="utf-8"))
if catalog.get("schema_version") != 1 or not isinstance(catalog.get("types"), list):
raise ValueError("Invalid generation catalog")
registered = set()
for entry in catalog["types"]:
type_id = entry.get("id") if isinstance(entry, dict) else None
if not isinstance(type_id, str) or not re.fullmatch(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*", type_id):
raise ValueError(f"Invalid generation catalog type ID: {type_id}")
if type_id in registered:
raise ValueError(f"Duplicate generation catalog type ID: {type_id}")
registered.add(type_id)
return ids | registered
def _require_generation_id(value, registered):
if not isinstance(value, str) or value not in registered:
raise ValueError(f"Unknown registered generation ID: {value}")
def build_generation_context(kb, family_ids, engine_build=None, *, experimental=False):
"""Load selected IDs only, without inferring or checking variant conditions."""
if isinstance(family_ids, str) or not isinstance(family_ids, (list, tuple)):
raise ValueError("Family IDs must be a list")
registered = _generation_ids(kb)
for family_id in family_ids:
_require_generation_id(family_id, registered)
selected = set(family_ids)
registry = kb.root / "generation/policy.json"
result = {"mode": "experimental" if experimental else "admitted_only",
"engine_build": engine_build, "manifest": [], "skipped": [], "text": ""}
if not registry.exists():
result["skipped"].append({"reason": "generation_registry_missing"})
return result
policy = json.loads(registry.read_text(encoding="utf-8"))
if policy.get("schema_version") != 1 or not isinstance(policy.get("documents"), list):
raise ValueError("Invalid generation policy")
seen, sections = set(), []
for entry in policy["documents"]:
doc_id = entry["doc_id"]
if doc_id in seen:
raise ValueError(f"Duplicate generation document ID: {doc_id}")
seen.add(doc_id)
families = entry["family_ids"]
if not isinstance(families, list) or not families:
raise ValueError(f"Generation document needs family IDs: {doc_id}")
for family_id in families:
_require_generation_id(family_id, registered)
if not selected.intersection(families):
continue
reason = None
status = entry["status"]
if status not in {"experimental", "approved", "retired"}:
raise ValueError(f"Invalid generation status: {doc_id}")
if status != "approved" and not (experimental and status == "experimental"):
reason = "not_approved"
path = (kb.root / entry["path"]).resolve()
if not path.is_relative_to((kb.root / "generation").resolve()):
raise ValueError(f"Generation document outside registry: {doc_id}")
if reason:
result["skipped"].append({"doc_id": doc_id, "reason": reason})
continue
content = path.read_bytes()
digest = hashlib.sha256(content).hexdigest()
if digest != entry["sha256"]:
result["skipped"].append({"doc_id": doc_id, "reason": "content_changed"})
continue
if status == "approved":
evidence = entry.get("evidence", {})
required = ("engine_replay", "ab_comparison", "parameter_transfer")
if evidence.get("verdict") != "benefit_observed" or not all(evidence.get(key) for key in required):
result["skipped"].append({"doc_id": doc_id, "reason": "benefit_evidence_missing"})
continue
text = content.decode("utf-8").strip()
if text.startswith("---\n"):
raise ValueError(f"Generation text must be plain Markdown without metadata: {doc_id}")
if not text:
raise ValueError(f"Empty generation document: {doc_id}")
manifest = {key: entry[key] for key in ("doc_id", "version", "path", "sha256", "status")}
# Build metadata is diagnostic only; independently deployed clients
# must not lose knowledge because a deployment identifier changed.
manifest.update(engine_build=engine_build)
result["manifest"].append(manifest)
sections.append(text)
result["text"] = "\n\n---\n\n".join(sections)
return result
@@ -1,270 +0,0 @@
"""Registry, deterministic candidate retrieval and progressive context loading."""
from __future__ import annotations
import json
import re
import unicodedata
from pathlib import Path
import yaml
from jsonschema import Draft202012Validator
from .validation import validate_parameters
from .generation import build_generation_context
class UniqueLoader(yaml.SafeLoader):
"""Reject duplicate keys instead of silently replacing engineering values."""
def _mapping(loader, node, deep=False):
result = {}
for key_node, value_node in node.value:
key = loader.construct_object(key_node, deep=deep)
if key in result:
raise ValueError(f"Duplicate YAML key: {key}")
result[key] = loader.construct_object(value_node, deep=deep)
return result
UniqueLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _mapping)
def normalized(value):
return re.sub(r"\s+", " ", unicodedata.normalize("NFKC", value).casefold()).strip()
def matches(query, term):
term = normalized(term)
if not term:
return False
if re.search(r"[\u3400-\u9fff]", term):
return term in query
return re.search(r"(?<![a-z0-9])" + re.escape(term) + r"(?![a-z0-9])", query) is not None
def read_document(path):
text = path.read_text(encoding="utf-8")
if not text.startswith("---\n"):
return None
parts = text.split("\n---\n", 1)
if len(parts) != 2:
raise ValueError(f"Unterminated frontmatter: {path}")
meta = yaml.load(parts[0][4:], Loader=UniqueLoader)
if not isinstance(meta, dict):
raise ValueError(f"Frontmatter must be a mapping: {path}")
return meta, parts[1].strip()
class KnowledgeBase:
def __init__(self, root=None):
self.root = Path(root or Path(__file__).resolve().parents[1]).resolve()
self.documents = {}
schema = json.loads((self.root / "schemas/document.schema.json").read_text())
validator = Draft202012Validator(schema)
for path in sorted((self.root / "references").rglob("*.md")):
resolved = path.resolve()
if not resolved.is_relative_to(self.root / "references"):
raise ValueError(f"Document outside registry: {path}")
parsed = read_document(path)
if parsed is None:
continue
meta, body = parsed
validator.validate(meta)
doc_id = meta["doc_id"]
if doc_id in self.documents:
raise ValueError(f"Duplicate document ID: {doc_id}")
self.documents[doc_id] = {"meta": meta, "body": body,
"path": path.relative_to(self.root).as_posix()}
if meta["kind"] == "family":
Draft202012Validator.check_schema(meta["parameter_schema"])
self.families = {k: v for k, v in self.documents.items() if v["meta"]["kind"] == "family"}
self.catalog = json.loads((self.root / "references/classification/mcb-taxonomy.json").read_text())
self.nodes = {n["id"]: n for n in self.catalog["nodes"]}
self._check_references()
def _check_references(self):
def visit(doc_id, stack):
if doc_id not in self.documents:
raise ValueError(f"Unknown document reference: {doc_id}")
if doc_id in stack:
raise ValueError(f"Circular reference: {' -> '.join([*stack, doc_id])}")
meta = self.documents[doc_id]["meta"]
dependencies = meta.get("requires", [])
if dependencies and meta["kind"] != "feature":
raise ValueError(f"Only shared features may declare requires: {doc_id}")
for dep in dependencies:
if dep in self.documents and self.documents[dep]["meta"]["kind"] not in {"common", "feature"}:
raise ValueError(f"Shared dependency cannot load a family or example: {dep}")
visit(dep, [*stack, doc_id])
for doc_id, doc in self.documents.items():
visit(doc_id, [])
meta = doc["meta"]
if meta["kind"] == "family":
for fid in meta["feature_ids"]:
self._require(fid, "feature")
example = self._require(meta["example_id"], "example")
if example["meta"]["family_id"] != doc_id:
raise ValueError(f"Example belongs to another family: {doc_id}")
for nid in meta["classification"]["node_ids"]:
if nid not in self.nodes or nid == "mcb-root":
raise ValueError(f"Unknown classification node: {nid}")
if meta["kind"] == "example":
self._require(meta["family_id"], "family")
def _require(self, doc_id, kind):
if not isinstance(doc_id, str) or doc_id not in self.documents:
raise ValueError(f"Unknown registered ID: {doc_id}")
doc = self.documents[doc_id]
if doc["meta"]["kind"] != kind:
raise ValueError(f"Expected {kind}: {doc_id}")
return doc
def search(self, query):
if not isinstance(query, str) or not query.strip():
raise ValueError("Query must be non-empty text")
query = normalized(query)
candidates = []
for family_id, doc in self.families.items():
meta = doc["meta"]
terms = [meta["name_zh"], meta["name_en"], *meta["aliases"]]
hits = sorted({term for term in terms if matches(query, term)}, key=lambda s: (-len(s), s))
if hits:
candidates.append({"family_id": family_id, "name_zh": meta["name_zh"],
"matched_terms": hits, "knowledge_status": meta["status"]})
candidates.sort(key=lambda c: (-len(c["matched_terms"][0]), c["family_id"]))
category_hits = []
for node in self.catalog["nodes"]:
if node["id"] == "mcb-root":
continue
terms = [node["label_en"], re.sub(r"〔.*?〕", "", node["label_zh"]),
*node.get("aliases", [])]
hits = [term for term in terms if matches(query, term)]
if hits:
related = [{"family_id": fid, "relation": doc["meta"]["classification"]["relation"]}
for fid, doc in self.families.items()
if node["id"] in doc["meta"]["classification"]["node_ids"]]
category_hits.append({"node_id": node["id"], "name_zh": node["label_zh"],
"matched_terms": hits, "related_families": related,
"coverage": "related_family_available" if related else "catalog_only"})
flags = []
if re.search(r"不要|不需要|不是|排除|不含|\b(?:not|without|exclude)\b", query):
flags.append("negation")
if len(candidates) > 1:
flags.append("multi_family")
if re.search(r"或者|还是|或是|不确定|\bor\b", query):
flags.append("ambiguous")
if not candidates:
flags.append("catalog_only" if category_hits else "no_match")
return {"query": query, "candidates": candidates, "category_hits": category_hits,
"flags": flags, "needs_semantic_review": True, "selected_family_id": None}
def build_context(self, family_ids, feature_ids=None, include_examples=False):
if isinstance(family_ids, str) or isinstance(feature_ids, str):
raise ValueError("IDs must be lists, not strings")
family_ids = list(dict.fromkeys(family_ids))
feature_ids = list(dict.fromkeys(feature_ids or []))
for fid in family_ids:
self._require(fid, "family")
related_features = {dep for fid in family_ids for dep in self.families[fid]["meta"]["feature_ids"]}
for feature_id in feature_ids:
self._require(feature_id, "feature")
if family_ids and feature_id not in related_features:
raise ValueError(f"Feature unrelated to selected families: {feature_id}")
ordered = []
seen = set()
def add(doc_id):
if doc_id in seen:
return
for dep in self.documents[doc_id]["meta"].get("requires", []):
add(dep)
seen.add(doc_id)
ordered.append(doc_id)
add("common-conventions")
for fid in family_ids:
add(fid)
for feature_id in sorted(related_features | set(feature_ids)):
add(feature_id)
if include_examples:
for fid in family_ids:
add(self.families[fid]["meta"]["example_id"])
manifest, sections = [], []
for doc_id in ordered:
doc = self.documents[doc_id]
meta = doc["meta"]
manifest.append({"doc_id": doc_id, "version": meta["knowledge_version"],
"kind": meta["kind"], "path": doc["path"]})
# Parameter schemas and example inputs are part of usable knowledge.
# Stripping frontmatter would hide the very data the agent needs.
metadata = yaml.safe_dump(meta, allow_unicode=True, sort_keys=False).strip()
sections.append(f"<!-- {doc_id}@{meta['knowledge_version']} -->\n```yaml\n{metadata}\n```\n\n{doc['body']}")
return {"manifest": manifest, "text": "\n\n---\n\n".join(sections)}
def validate_params(self, family_id, params):
doc = self._require(family_id, "family")
return validate_parameters(family_id, doc["meta"]["parameter_schema"], params)
def build_generation_context(self, family_ids, engine_build=None, *, experimental=False):
"""No fallback to the archival family/feature context."""
return build_generation_context(self, family_ids, engine_build, experimental=experimental)
def check(self):
errors = []
nodes = self.catalog["nodes"]
if len(nodes) != 204 or len(self.nodes) != 204:
errors.append("Expected 203 unique categories plus one root")
counts = {d: sum(n["depth"] == d for n in nodes) for d in range(4)}
if counts != {0: 1, 1: 15, 2: 109, 3: 79}:
errors.append(f"Unexpected classification depths: {counts}")
for node in nodes:
visited = set()
current = node
while current["parent_id"] is not None:
if current["id"] in visited or current["parent_id"] not in self.nodes:
errors.append(f"Broken/circular classification: {node['id']}")
break
visited.add(current["id"])
parent = self.nodes[current["parent_id"]]
if current["depth"] != parent["depth"] + 1:
errors.append(f"Invalid depth: {current['id']}")
current = parent
if current["id"] != "mcb-root":
errors.append(f"Classification not rooted: {node['id']}")
leaves = sum(not any(child["parent_id"] == node["id"] for child in nodes) for node in nodes)
if leaves != 173:
errors.append(f"Expected 173 leaves, found {leaves}")
if len(self.families) != 6:
errors.append("Expected six pilot families")
examples = {}
for fid, doc in self.families.items():
def check_attributes(schema, path):
for key, attribute in schema.get("properties", {}).items():
required = {"title", "description", "x-unit", "x-datum", "x-constraints"}
if not required.issubset(attribute) or not any(k in attribute for k in ("type", "const")):
errors.append(f"Incomplete attribute dictionary: {fid}.{path}{key}")
check_attributes(attribute, f"{path}{key}.")
if "items" in attribute:
check_attributes(attribute["items"], f"{path}{key}[].")
check_attributes(doc["meta"]["parameter_schema"], "")
example = self.documents[doc["meta"]["example_id"]]["meta"]
result = self.validate_params(fid, example["params"])
examples[fid] = result
if not result["valid"]:
errors.append(f"Invalid example: {fid}")
for key, expected in example.get("expected_derived", {}).items():
actual = result["derived"].get(key)
if isinstance(expected, (int, float)):
import math
equal = isinstance(actual, (int, float)) and math.isclose(actual, expected, rel_tol=1e-9, abs_tol=1e-9)
else:
equal = actual == expected
if not equal:
errors.append(f"Example expectation mismatch: {fid}.{key}")
return {"passed": not errors, "errors": errors, "categories": len(nodes) - 1,
"depth_counts": counts, "leaves": leaves, "families": len(self.families),
"documents": len(self.documents), "examples": examples,
"geometry_validated": False}
@@ -1,67 +0,0 @@
"""Reproducible human-facing catalog, Mermaid and coverage views."""
from __future__ import annotations
import html
import json
def generated_outputs(kb):
nodes = kb.catalog["nodes"]
children = {n["id"]: [c for c in nodes if c["parent_id"] == n["id"]] for n in nodes}
def subtree(node):
return [node] + [n for child in children[node["id"]] for n in subtree(child)]
def diagram(selected):
included = {n["id"] for n in selected}
name = lambda nid: "root" if nid == "mcb-root" else "n" + nid.split("-")[1]
lines = ["flowchart LR"]
for n in selected:
lines.append(f' {name(n["id"])}["{html.escape(n["label_zh"], quote=True)}"]')
for n in selected:
if n["parent_id"] in included:
lines.append(f' {name(n["parent_id"])} --> {name(n["id"])}')
return "\n".join(lines)
full = diagram(nodes)
mermaid = ["# MCB 中文分类树:Mermaid", "",
"本文件由分类 JSON 生成。203 个类别,另加展示根节点;包含一级总览、完整图及 15 个完整分支图。",
"中文为工作译名,暂译/待核标记不是原始类别名称。编号与英文原名见[完整分类目录](mcb-taxonomy.zh-CN.md),来源见[来源说明](sources.md)。", "",
"## 一级总览", "", "```mermaid", diagram([n for n in nodes if n["depth"] <= 1]), "```", "",
"## 完整树", "", "```mermaid", full, "```", ""]
for branch in children["mcb-root"]:
mermaid += [f'## {branch["label_zh"]}', "", "```mermaid", diagram(subtree(branch)), "```", ""]
catalog = ["# MCB 中文完整分类目录", "",
"203 个分类节点:一级 15、二级 109、三级 79,173 个叶子。项目展示根节点不计入 203。",
"此完整性仅针对公开论文附录图 7,不代表所有机械零件。原文重复名称按路径区分,原文拼写保留。",
"[Mermaid 树](mcb-taxonomy-mermaid.zh-CN.md) · [来源与疑点](sources.md)", "",
"| 本地 ID | 中文工作译名 | 英文原名 | 父节点 | 层级 |", "| --- | --- | --- | --- | ---: |"]
catalog += [f'| {n["id"]} | {n["label_zh"]} | {n["label_en"]} | {n["parent_id"]} | {n["depth"]} |'
for n in nodes if n["depth"]]
coverage = ["# 知识覆盖清单", "",
"分类目录有 203 类,当前有 6 个项目零件族的工程知识。关联某个宽泛来源节点,不代表该节点下全部变体均已覆盖。",
"状态 `retrieval_verified` 仅表示固定离线检索和参数用例通过,`geometry_validated=false`。", "",
"| 零件族 | ID | MCB 关系 | 来源节点 | 状态 |", "| --- | --- | --- | --- | --- |"]
index = []
for fid, doc in sorted(kb.families.items()):
m = doc["meta"]
coverage.append(f'| [{m["name_zh"]}](families/{fid}.md) | `{fid}` | {m["classification"]["relation"]} | {", ".join(m["classification"]["node_ids"]) or "项目扩充"} | {m["status"]} |')
index.append({k: m[k] for k in ("doc_id", "name_zh", "name_en", "aliases", "classification", "feature_ids", "knowledge_version", "status")}
| {"path": doc["path"]})
coverage += ["", "每族范围、未覆盖变体、参数和精度要求以主文档为准。六个完整示例可从各主文档进入。",
"", "## 扩展状态", "", "其余目录节点仅提供检索线索,不生成空白 Skill 或空白工程文档。新增族的流程见[维护说明](maintenance.md)。"]
return {
"references/classification/mcb-taxonomy.zh-CN.md": "\n".join(catalog) + "\n",
"references/classification/mcb-taxonomy-mermaid.zh-CN.md": "\n".join(mermaid) + "\n",
"references/classification/mcb-taxonomy.zh-CN.mmd": full + "\n",
"references/coverage.md": "\n".join(coverage) + "\n",
"index.json": json.dumps({"version": "0.1.0", "generated_from": "family frontmatter", "families": index}, ensure_ascii=False, indent=2) + "\n",
}
def build(kb):
outputs = generated_outputs(kb)
for relative, content in outputs.items():
(kb.root / relative).write_text(content, encoding="utf-8")
return {"generated": list(outputs)}
@@ -1,192 +0,0 @@
"""Analytic checks for the six declared pilot profiles, never CAD validation."""
from __future__ import annotations
import math
from jsonschema import Draft202012Validator
def _path(parts):
return "$" + "".join(f"[{p}]" if isinstance(p, int) else f".{p}" for p in parts)
def _nonfinite(value, path=()):
if isinstance(value, float) and not math.isfinite(value):
yield _path(path)
elif isinstance(value, dict):
for key, item in value.items():
yield from _nonfinite(item, (*path, key))
elif isinstance(value, list):
for index, item in enumerate(value):
yield from _nonfinite(item, (*path, index))
def validate_parameters(family_id, schema, params):
result = {"family_id": family_id, "valid": False, "missing": [], "conflicts": [],
"unsupported": [], "derived": {}, "checks": [], "geometry_validated": False}
def conflict(path, message, code="relationship"):
result["conflicts"].append({"path": path, "code": code, "message": message})
for path in _nonfinite(params):
conflict(path, "Numbers must be finite", "nonfinite")
if result["conflicts"]:
return result
for error in sorted(Draft202012Validator(schema).iter_errors(params), key=lambda e: str(list(e.path))):
group = "missing" if error.validator == "required" else "unsupported" if error.validator in {"enum", "const", "additionalProperties"} else "conflicts"
result[group].append({"path": _path(error.path), "code": error.validator, "message": error.message})
if any(result[key] for key in ("missing", "conflicts", "unsupported")):
return result
def holes_in_plate(holes, length, width, margin=0, path="$.holes"):
for index, hole in enumerate(holes):
edge_clearance = min(length / 2 - abs(hole["x"]) - hole["diameter"] / 2,
width / 2 - abs(hole["y"]) - hole["diameter"] / 2)
if edge_clearance <= 0 or edge_clearance < margin:
conflict(f"{path}[{index}]", "Hole exceeds the plate or required edge margin")
for previous in holes[:index]:
distance = math.hypot(hole["x"] - previous["x"], hole["y"] - previous["y"])
if distance <= (hole["diameter"] + previous["diameter"]) / 2 + margin:
conflict(f"{path}[{index}]", "Holes touch/overlap or violate the required ligament")
p, d = params, result["derived"]
if family_id == "mounting-plate":
if ("holes" in p) == ("hole_pattern" in p):
result["missing" if "holes" not in p else "conflicts"].append(
{"path": "$", "code": "hole_layout", "message": "Provide exactly one of holes or hole_pattern"})
return result
if "holes" in p:
holes = p["holes"]
else:
pattern = p["hole_pattern"]
if pattern["rows"] * pattern["columns"] > 256:
conflict("$.hole_pattern", "At most 256 holes are supported", "capacity")
return result
holes = [{"x": pattern["origin_x"] + col * pattern["pitch_x"],
"y": pattern["origin_y"] + row * pattern["pitch_y"],
"diameter": pattern["diameter"]}
for row in range(pattern["rows"]) for col in range(pattern["columns"])]
holes_in_plate(holes, p["length"], p["width"])
d.update(holes=holes, hole_count=len(holes),
volume=p["length"] * p["width"] * p["thickness"] -
sum(math.pi / 4 * h["diameter"] ** 2 * p["thickness"] for h in holes))
result["checks"] = ["hole_edge_clearance", "hole_pair_separation", "analytic_volume"]
elif family_id == "stepped-shaft":
offset, positions = 0, []
for segment in p["segments"]:
positions.append({"start_z": offset, "end_z": offset + segment["length"]})
offset += segment["length"]
d.update(total_length=offset, max_diameter=max(s["diameter"] for s in p["segments"]),
segment_positions=positions,
volume=sum(math.pi / 4 * s["diameter"] ** 2 * s["length"] for s in p["segments"]))
if len({s["diameter"] for s in p["segments"]}) == 1:
conflict("$.segments", "A stepped shaft needs at least two different diameters")
result["checks"] = ["continuous_axial_chain", "distinct_step", "analytic_volume"]
elif family_id == "hex-head-bolt":
if p["across_flats"] <= p["nominal_diameter"]:
conflict("$.across_flats", "Head across-flats must exceed shank diameter in this pilot")
if p["thread_length"] > p["under_head_length"]:
conflict("$.thread_length", "Thread length exceeds under-head length")
d.update(total_length=p["under_head_length"] + p["head_height"],
head_circumdiameter=2 * p["across_flats"] / math.sqrt(3),
volume=math.pi / 4 * p["nominal_diameter"] ** 2 * p["under_head_length"] +
math.sqrt(3) / 2 * p["across_flats"] ** 2 * p["head_height"])
result["checks"] = ["head_shank_relation", "thread_extent", "simplified_volume"]
elif family_id == "ribbed-bearing-housing":
wall = p["min_wall"]
if p["base_thickness"] < wall:
conflict("$.base_thickness", "Base thickness is below requested minimum wall")
if p["boss_outer_diameter"] - p["bore_diameter"] < 2 * wall:
conflict("$.bore_diameter", "Insufficient radial wall around bearing bore")
if p["center_height"] - p["bore_diameter"] / 2 < p["base_thickness"] + wall:
conflict("$.center_height", "Bore breaks into base or violates its required ligament")
if not (p["base_thickness"] < p["center_height"] and 0 < p["pedestal_width"] < p["boss_outer_diameter"]):
conflict("$.pedestal_width", "Pedestal must rise from base to bore centre and intersect boss")
if p["boss_outer_diameter"] > p["base_length"] or p["boss_width"] > p["base_width"]:
conflict("$.boss_outer_diameter", "Boss footprint exceeds pilot base envelope")
if p["pedestal_width"] / 2 + p["rib_reach"] > p["base_length"] / 2 - wall:
conflict("$.rib_reach", "Rib reaches beyond base margin")
if p["rib_thickness"] > p["boss_width"] or p["rib_thickness"] < wall:
conflict("$.rib_thickness", "Rib thickness is outside the declared profile")
if p["base_thickness"] + p["rib_height"] > p["center_height"]:
conflict("$.rib_height", "Rib attachment extends above pedestal")
if p["pedestal_width"] / 2 < p["bore_diameter"] / 2 + wall:
conflict("$.pedestal_width", "Rib attachment lies too close to bore")
holes_in_plate(p["mount_holes"], p["base_length"], p["base_width"], wall, "$.mount_holes")
for i, hole in enumerate(p["mount_holes"]):
# Conservative plan envelope of pedestal and the two symmetric ribs.
rectangles = [(p["pedestal_width"] / 2, p["boss_width"] / 2),
(p["pedestal_width"] / 2 + p["rib_reach"], p["rib_thickness"] / 2)]
if any(math.hypot(max(abs(hole["x"]) - rx, 0), max(abs(hole["y"]) - ry, 0)) < hole["diameter"] / 2 + wall
for rx, ry in rectangles):
conflict(f"$.mount_holes[{i}]", "Mounting hole conflicts with support/rib footprint")
if "counterbore" in p:
c = p["counterbore"]
if not p["bore_diameter"] < c["diameter"] <= p["boss_outer_diameter"] - 2 * wall:
conflict("$.counterbore.diameter", "Counterbore must enlarge bore while retaining radial wall")
if c["depth"] >= p["boss_width"]:
conflict("$.counterbore.depth", "Counterbore eliminates the locating shoulder")
if p["center_height"] - c["diameter"] / 2 < p["base_thickness"] + wall:
conflict("$.counterbore.diameter", "Counterbore violates the base ligament")
d.update(total_height=max(p["base_thickness"], p["center_height"] + p["boss_outer_diameter"] / 2),
radial_wall=(p["boss_outer_diameter"] - p["bore_diameter"]) / 2,
bore_bottom=p["center_height"] - p["bore_diameter"] / 2,
rib_count=2, mounting_hole_count=len(p["mount_holes"]))
result["checks"] = ["declared_axes", "boss_wall", "pedestal_rib_attachment", "mounting_access"]
elif family_id == "involute-spur-gear":
module, teeth = p["module"], p["tooth_count"]
pitch = module * teeth
tip, root = module * (teeth + 2), module * (teeth - 2.5)
base = pitch * math.cos(math.radians(p["pressure_angle"]))
if p["hub_diameter"] > root:
conflict("$.hub_diameter", "Hub extends beyond root circle in this pilot")
if p["keyway_width"] >= p["bore_diameter"]:
conflict("$.keyway_width", "Keyway must open into the bore in this pilot")
corner_radius = math.hypot(p["bore_diameter"] / 2 + p["keyway_depth"], p["keyway_width"] / 2)
if corner_radius + p["min_wall"] >= min(p["hub_diameter"], root) / 2:
conflict("$.keyway_depth", "Bore/keyway breaks through hub or root ligament")
d.update(pitch_diameter=pitch, addendum_diameter=tip, root_diameter=root, base_diameter=base,
angular_pitch_deg=360 / teeth, tooth_thickness_at_pitch=math.pi * module / 2,
involute_start_radius=max(base, root) / 2,
involute_tip_parameter=math.sqrt((tip / base) ** 2 - 1),
total_length=p["face_width"] + p["hub_length"])
result["checks"] = ["reference_tooth_system", "circle_dependencies", "bore_keyway_ligament", "declared_root_simplification"]
elif family_id == "covered-thin-wall-enclosure":
inner_l = p["outer_length"] - 2 * p["wall_thickness"]
inner_w = p["outer_width"] - 2 * p["wall_thickness"]
inner_h = p["outer_height"] - p["bottom_thickness"]
if min(inner_l, inner_w, inner_h) <= 0:
conflict("$.wall_thickness", "Wall/bottom thickness eliminates the cavity")
radius = p["boss_outer_diameter"] / 2
x = p["outer_length"] / 2 - p["fastener_inset"]
y = p["outer_width"] / 2 - p["fastener_inset"]
if x <= radius or y <= radius:
conflict("$.fastener_inset", "Four corner bosses overlap or collapse to one axis")
if x + radius >= inner_l / 2 or y + radius >= inner_w / 2:
conflict("$.boss_outer_diameter", "Bosses must fit inside cavity; ribs connect them to walls")
if (p["boss_outer_diameter"] - p["boss_pilot_diameter"]) / 2 < p["min_wall"]:
conflict("$.boss_pilot_diameter", "Insufficient boss wall")
if not p["boss_pilot_diameter"] < p["cover_hole_diameter"] < p["boss_outer_diameter"]:
conflict("$.cover_hole_diameter", "Cover clearance hole must exceed pilot and fit over boss")
if p["fastener_inset"] - p["cover_hole_diameter"] / 2 < p["min_wall"]:
conflict("$.cover_hole_diameter", "Insufficient cover edge margin")
if p["boss_height"] > inner_h:
conflict("$.boss_height", "Boss protrudes above shell rim")
if p["pilot_depth"] > p["boss_height"] - p["min_wall"]:
conflict("$.pilot_depth", "Blind pilot removes the required bottom ligament")
if p["rib_height"] > p["boss_height"] or p["rib_thickness"] >= p["boss_outer_diameter"]:
conflict("$.rib_height", "Ribs must attach within boss height and diameter")
if min(p["wall_thickness"], p["bottom_thickness"], p["lid_thickness"], p["rib_thickness"]) < p["min_wall"]:
conflict("$.min_wall", "One of the declared walls is below the requested minimum")
centres = [{"x": sx * x, "y": sy * y} for sy in (-1, 1) for sx in (-1, 1)]
d.update(inner_length=inner_l, inner_width=inner_w, inner_height=inner_h,
fastener_centers=centres, cover_bottom_z=p["outer_height"] + p["assembly_gap"],
total_height=p["outer_height"] + p["assembly_gap"] + p["lid_thickness"], part_count=2)
result["checks"] = ["positive_cavity", "four_boss_spacing", "shared_interface_centers", "blind_hole_ligament", "two_separate_parts"]
else:
raise ValueError(f"No pilot validator registered: {family_id}")
for path in _nonfinite(d):
conflict(path, "Derived value is non-finite", "nonfinite_derived")
result["valid"] = not any(result[key] for key in ("missing", "conflicts", "unsupported"))
return result
@@ -1,711 +0,0 @@
package com.linkerbot.vibemake.service.cad.ai;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.linkerbot.vibemake.service.config.CadAiProperties;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.*;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.io.ClassPathResource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
/** Read-only, versioned CAD recipe routing. It never infers dimensions from prose. */
@Component
public class CadAiKnowledge {
public static final String PROTOCOL = "cad-knowledge-v1";
public static final String INSTRUCTIONS = "沿原通用技能建模。当前已明确的齿轮、齿条、蜗轮蜗杆及其机构,按需用knowledge_lookup读取已有专项构造规程;XZ草图造轴承座筋时可查询方向风险提示。普通板、轴、螺栓、座体、壳体无需查。仅补齐已明确条件后重查,不改需求凑命中;无适用内容沿原流程,有效上下文已有正文不重复读。用户要求优先于选配示例。";
private static final Logger log = LoggerFactory.getLogger(CadAiKnowledge.class);
private static final String RESOURCE_ROOT = "cad/ai/knowledge/";
private static final Set<String> SPUR_CONDITIONS = Set.of("module_mm", "teeth", "pressure_angle_deg", "profile_shift", "backlash_mm", "addendum_coefficient", "clearance_coefficient", "root_transition");
private static final List<Pattern> QUALIFIED_GEAR_NAMES = List.of(
Pattern.compile("(?:(?:内啮合|外啮合|内齿|外齿|内|外|渐开线|直齿|斜齿|螺旋|圆柱|环形|锥齿|圆锥)(?:的\\s*)?\\s*)+(?:齿轮|齿圈|轮)"),
Pattern.compile("\\b(?:(?:internal|external|involute|spur|helical|bevel|cylindrical|ring)\\s+)+gears?\\b"));
private static final Pattern UNCERTAIN_NEGATION = Pattern.compile("(?:不能|不得|不可|不允许|不准|不许|不应|不要|不是|并非|禁止|严禁|切勿|请勿|勿|避免|不生成|不创建|不制作|不建)\\s*(?:不|没有|禁止|避免|无\\s*(?:中央|中心)?(?:退刀槽|槽)(?=\\s*(?:[,,。;;\\n]|$)))|\\b(?:not|never|without)\\s+(?:not|no|without|avoid(?:ing)?|excluding|fail\\s+to)\\b");
private static final Pattern REFERENCE_CREATION = Pattern.compile("(?s).*(?:生成|制作|创建|构造|绘制|建模|只造|只做|做|造|建|画|当前待修改部件是|\\bmake|\\bcreate|\\bbuild|\\bmodel|\\bgenerate|\\bdraw)\\s*(?:一个|一件|一套|一只|一条|a\\b|an\\b|the\\b)?\\s*$");
private static final Pattern TARGET_INTENT = Pattern.compile("生成|制作|创建|构造|绘制|建模|只造|只做|修改|只查询|只查|当前待(?:建|修改)部件是|\\b(?:make|create|build|model|generate|draw|modify)\\b");
private static final Pattern JOINED_TARGET = Pattern.compile("(?s).*(?:和|与|及|以及|并|同时|另|再|\\band|\\balso)\\s*$");
private static final Pattern SHAFT_INTERFACE = Pattern.compile("齿轮(?:安装)?孔(?=\\s*(?:名义)?(?:直径|孔径|尺寸|为|=|[::])?\\s*\\d)");
private static final String REFERENCE_MODIFIERS = "(?:(?![,,。;;\\r\\n]|生成|制作|创建|构造|绘制|建模|修改|另|再|并|和|与|以及|\\b(?:create|build|generate|make|modify|and|also)\\b).){0,128}?";
private final ObjectMapper json;
private final CadAiProperties properties;
private final Map<String, JsonNode> types;
private final Map<String, JsonNode> factDefinitions;
private final List<Recipe> recipes;
private final Pattern referenceNames;
private final Pattern companionNames;
private record Recipe(JsonNode metadata, String text) {}
private record QualifiedGearName(String name, String type, int start, int end, boolean conflict) {}
@Autowired
public CadAiKnowledge(ObjectMapper json, CadAiProperties properties) throws IOException {
this(json, properties, readPolicy(json));
}
// Explicit policy keeps historical routing fixtures reproducible after utility withdrawals.
CadAiKnowledge(ObjectMapper json, CadAiProperties properties, JsonNode policy) throws IOException {
this.json = json;
this.properties = properties;
JsonNode catalog = read("generation/catalog.json");
types = validateCatalog(catalog);
referenceNames = referenceNames(types);
companionNames = Pattern.compile("(?:配套|匹配)" + REFERENCE_MODIFIERS + objectNames(types)
+ "(?=\\s*(?:的\\s*)?(?:中心距|轴向模数|法向模数|端面模数|模数|轴向压力角|压力角|分度(?:圆)?(?:直径|径)|孔径|轴径|安装孔|中心高|接口|配合))");
factDefinitions = validateFactDefinitions(catalog);
recipes = validateRecipes(policy);
log.info("CAD knowledge loaded: version={}, types={}, recipes={}", catalog.path("version").asText(), types.size(), recipes.size());
}
private static JsonNode readPolicy(ObjectMapper json) throws IOException {
try (InputStream input = new ClassPathResource(RESOURCE_ROOT + "generation/policy.json").getInputStream()) {
return json.readTree(input);
}
}
private JsonNode read(String path) throws IOException {
try (InputStream input = new ClassPathResource(RESOURCE_ROOT + path).getInputStream()) {
return json.readTree(input);
}
}
static Map<String, JsonNode> validateCatalog(JsonNode catalog) throws IOException {
if (catalog == null || catalog.path("schema_version").asInt() != 1 || !catalog.path("types").isArray())
throw new IOException("Invalid CAD knowledge catalog");
Map<String, JsonNode> index = new LinkedHashMap<>();
Set<String> registeredAliases = new HashSet<>();
for (JsonNode type : catalog.path("types")) {
String id = type.path("id").asText();
if (!id.matches("[a-z][a-z0-9-]{1,79}") || index.put(id, type) != null
|| type.path("name_zh").asText().isBlank() || !type.path("aliases").isArray()
|| !Set.of("group", "part", "mechanism").contains(type.path("kind").asText()))
throw new IOException("Invalid or duplicate CAD knowledge type");
Set<String> aliases = new HashSet<>();
for (JsonNode alias : type.path("aliases"))
if (!alias.isTextual() || alias.asText().isBlank() || !aliases.add(alias.asText()) || !registeredAliases.add(alias.asText().toLowerCase(Locale.ROOT)))
throw new IOException("Invalid CAD knowledge alias");
}
for (String id : index.keySet()) {
Set<String> visited = new HashSet<>();
String cursor = id;
while (cursor != null) {
if (!visited.add(cursor) || !index.containsKey(cursor)) throw new IOException("Broken or cyclic CAD knowledge hierarchy");
JsonNode parent = index.get(cursor).get("parent");
cursor = parent == null || parent.isNull() ? null : parent.asText();
}
for (JsonNode related : index.get(id).path("related_types"))
if (!index.containsKey(related.asText())) throw new IOException("Broken CAD knowledge type reference");
}
if (index.isEmpty()) throw new IOException("Empty CAD knowledge catalog");
return Map.copyOf(index);
}
/** Canonical property dictionary shared by tool schemas and recipe eligibility. */
static Map<String, JsonNode> validateFactDefinitions(JsonNode catalog) throws IOException {
JsonNode definitions = catalog.path("fact_definitions");
if (!definitions.isObject() || definitions.isEmpty() || definitions.size() > 64)
throw new IOException("Invalid CAD knowledge property dictionary");
Map<String, JsonNode> result = new TreeMap<>();
Iterator<Map.Entry<String, JsonNode>> entries = definitions.fields();
while (entries.hasNext()) {
Map.Entry<String, JsonNode> entry = entries.next();
JsonNode definition = entry.getValue();
if (!entry.getKey().matches("[a-z][a-z0-9_]{0,63}") || !definition.isObject()
|| !Set.of("number", "string", "boolean").contains(definition.path("type").asText())
|| !Set.of("mm", "deg", "count", "none").contains(definition.path("unit").asText())
|| !definition.path("description").isTextual() || definition.path("description").asText().isBlank()
|| definition.path("description").asText().length() > 160)
throw new IOException("Invalid CAD knowledge property definition");
result.put(entry.getKey(), definition);
}
return Collections.unmodifiableMap(result);
}
private List<Recipe> validateRecipes(JsonNode policy) throws IOException {
if (policy == null || policy.path("schema_version").asInt() != 1 || !policy.path("documents").isArray())
throw new IOException("Invalid CAD knowledge policy");
Set<String> ids = new HashSet<>();
List<Recipe> result = new ArrayList<>();
for (JsonNode document : policy.path("documents")) {
String id = document.path("doc_id").asText();
String path = document.path("path").asText();
String hash = document.path("sha256").asText();
if (!id.matches("[a-z][a-z0-9-]+") || !ids.add(id)
|| !document.path("version").asText().matches("\\d+\\.\\d+\\.\\d+")
|| !Set.of("retired", "experimental", "approved").contains(document.path("status").asText())
|| !path.matches("generation/(candidates|archive)/[a-z0-9-]+\\.md")
|| !hash.matches("[a-f0-9]{64}")) throw new IOException("Invalid CAD knowledge recipe metadata");
validatePublication(document);
byte[] bytes;
try (InputStream input = new ClassPathResource(RESOURCE_ROOT + path).getInputStream()) { bytes = input.readAllBytes(); }
verifyHash(bytes, hash);
if (bytes.length == 0 || bytes.length > 24 * 1024) throw new IOException("CAD knowledge recipe body exceeds transport budget");
if ("retired".equals(document.path("status").asText())) continue;
String role = document.path("content_role").asText("recipe");
if (!Set.of("recipe", "risk_hint").contains(role)) throw new IOException("Invalid CAD knowledge content role");
validateActivation(document.path("activation"));
if (!types.containsKey(document.path("type_id").asText()) || !document.path("conditions").isObject()
|| document.path("conditions").isEmpty() && !("risk_hint".equals(role) && document.has("activation")))
throw new IOException("Incomplete CAD knowledge recipe eligibility");
if (!document.path("conditions").isEmpty())
validateConditions(document.path("type_id").asText(), document.path("conditions"), factDefinitions);
result.add(new Recipe(document, new String(bytes, StandardCharsets.UTF_8)));
}
return List.copyOf(result);
}
private static void validateActivation(JsonNode activation) throws IOException {
if (activation.isMissingNode()) return;
if (!activation.isObject() || activation.size() != 2)
throw new IOException("Invalid CAD knowledge activation");
for (String field : List.of("all_terms", "any_terms")) {
JsonNode terms = activation.path(field);
if (!terms.isArray() || terms.isEmpty() || terms.size() > 8)
throw new IOException("Invalid CAD knowledge activation terms");
Set<String> unique = new HashSet<>();
for (JsonNode term : terms)
if (!term.isTextual() || term.asText().isBlank() || term.asText().length() > 40
|| !term.asText().equals(term.asText().strip().toLowerCase(Locale.ROOT)) || !unique.add(term.asText()))
throw new IOException("Invalid CAD knowledge activation term");
}
}
private static boolean activationMatches(JsonNode activation, String query) {
if (activation.isMissingNode()) return true;
// Keep operation terms together: a housing name containing 筋 must not activate an XZ bore operation.
for (String clause : query.split("[,,。;;\\n]")) {
boolean all = true;
for (JsonNode term : activation.path("all_terms")) if (!hasActivationTerm(clause, term.asText())) all = false;
if (!all) continue;
for (JsonNode term : activation.path("any_terms")) if (hasActivationTerm(clause, term.asText())) return true;
}
return false;
}
private static boolean hasActivationTerm(String query, String term) {
if (term.matches("[a-z0-9_]+"))
return Pattern.compile("(?<![a-z0-9_])" + Pattern.quote(term) + "(?![a-z0-9_])").matcher(query).find();
return query.contains(term);
}
static void validatePublication(JsonNode document) throws IOException {
if (!"approved".equals(document.path("status").asText())) return;
JsonNode evidence = document.path("evidence");
if (!"benefit_observed".equals(evidence.path("verdict").asText()))
throw new IOException("Approved CAD knowledge recipe lacks benefit evidence");
for (String field : List.of("engine_replay", "ab_comparison", "parameter_transfer")) {
JsonNode reference = evidence.path(field);
if (reference.isTextual() && !reference.asText().isBlank()) continue;
if (!reference.isArray() || reference.isEmpty()) throw new IOException("Approved CAD knowledge recipe lacks evidence references");
for (JsonNode item : reference)
if (!item.isTextual() || item.asText().isBlank()) throw new IOException("Invalid approved CAD knowledge evidence reference");
}
}
static void validateConditions(String type, JsonNode conditions) throws IOException {
try (InputStream input = new ClassPathResource(RESOURCE_ROOT + "generation/catalog.json").getInputStream()) {
validateConditions(type, conditions, validateFactDefinitions(new ObjectMapper().readTree(input)));
}
}
private static void validateConditions(String type, JsonNode conditions, Map<String, JsonNode> definitions) throws IOException {
if (!conditions.isObject() || conditions.isEmpty()) throw new IOException("Empty CAD recipe conditions");
Set<String> present = new HashSet<>();
Iterator<Map.Entry<String, JsonNode>> entries = conditions.fields();
while (entries.hasNext()) {
Map.Entry<String, JsonNode> entry = entries.next();
JsonNode rule = entry.getValue();
JsonNode definition = definitions.get(entry.getKey());
if (definition == null || !rule.isObject() || rule.isEmpty()) throw new IOException("Invalid CAD recipe condition");
present.add(entry.getKey());
if (!"number".equals(definition.path("type").asText())) {
JsonNode expected = rule.path("equals");
if (rule.size() != 1 || "string".equals(definition.path("type").asText())
&& (!expected.isTextual() || expected.asText().isBlank() || expected.asText().length() > 80)
|| "boolean".equals(definition.path("type").asText()) && !expected.isBoolean())
throw new IOException("Invalid CAD recipe property equality");
continue;
}
Iterator<Map.Entry<String, JsonNode>> rules = rule.fields();
while (rules.hasNext()) {
Map.Entry<String, JsonNode> field = rules.next();
if (!Set.of("min", "max", "min_exclusive", "abs_min", "abs_max", "equals", "integer").contains(field.getKey())
|| "integer".equals(field.getKey()) && !field.getValue().isBoolean()
|| !"integer".equals(field.getKey()) && (!field.getValue().isNumber() || !Double.isFinite(field.getValue().asDouble())))
throw new IOException("Invalid CAD recipe numeric condition");
}
if (rule.has("min") && rule.has("min_exclusive")) throw new IOException("Duplicate CAD recipe lower bound");
double lower = rule.path("min").asDouble(rule.path("min_exclusive").asDouble(Double.NEGATIVE_INFINITY));
double upper = rule.path("max").asDouble(Double.POSITIVE_INFINITY);
if (lower > upper || rule.has("min_exclusive") && lower == upper) throw new IOException("Empty CAD recipe range");
double absoluteLower = rule.path("abs_min").asDouble(0);
double absoluteUpper = rule.path("abs_max").asDouble(Double.POSITIVE_INFINITY);
if (absoluteLower < 0 || absoluteUpper < absoluteLower
|| !rangesIntersect(lower, upper, rule.has("min_exclusive"), absoluteLower, absoluteUpper)
&& !rangesIntersect(lower, upper, rule.has("min_exclusive"), -absoluteUpper, -absoluteLower))
throw new IOException("Empty CAD recipe absolute range");
if (rule.has("equals") && !numericConditionMatches(rule, rule.path("equals").asDouble()))
throw new IOException("Conflicting CAD recipe equality");
}
if ("involute-spur-gear".equals(type) && !present.containsAll(SPUR_CONDITIONS))
throw new IOException("Missing dependent involute spur gear conditions");
}
private static boolean rangesIntersect(double lower, double upper, boolean lowerExclusive, double otherLower, double otherUpper) {
double start = Math.max(lower, otherLower);
double end = Math.min(upper, otherUpper);
return start < end || start == end && !(lowerExclusive && start == lower);
}
private static boolean numericConditionMatches(JsonNode rule, double number) {
return Double.isFinite(number)
&& (!rule.has("equals") || Math.abs(number - rule.path("equals").asDouble()) < 1e-9)
&& (!rule.has("min") || number >= rule.path("min").asDouble())
&& (!rule.has("max") || number <= rule.path("max").asDouble())
&& (!rule.has("min_exclusive") || number > rule.path("min_exclusive").asDouble())
&& (!rule.has("abs_min") || Math.abs(number) >= rule.path("abs_min").asDouble())
&& (!rule.has("abs_max") || Math.abs(number) <= rule.path("abs_max").asDouble())
&& (!rule.path("integer").asBoolean() || number == Math.rint(number));
}
static void verifyHash(byte[] bytes, String expected) throws IOException {
try {
String actual = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes));
if (!actual.equals(expected)) throw new IOException("CAD knowledge recipe hash mismatch");
} catch (NoSuchAlgorithmException error) { throw new IOException("SHA-256 unavailable", error); }
}
public ObjectNode lookup(JsonNode arguments, String build) {
if ("off".equals(properties.getKnowledgeMode())) return answer("disabled", null, "专项知识已关闭;继续原助手流程,结果待验证。");
String original = arguments.path("query").asText();
if (original.toLowerCase(Locale.ROOT).matches("(?s)\\s*(?:解释|介绍|说明原理|比较|什么是|查询历史|explain|what is|compare|describe the principle).*"))
return answer("not_applicable", null, "此为说明或比较请求,无需加载建模规程;沿原助手回答。");
if (UNCERTAIN_NEGATION.matcher(currentPartQuery(original)).find())
return answer("ambiguous", null, "当前描述含双重否定或禁止范围不明确;先确认当前部件,不据此删除候选或加载规程。");
String query = positiveQuery(original);
if (query.isBlank()) return answer("ambiguous", null, "未确定当前待建部件;不加载被否定的规程。");
String selected = arguments.path("type_id").asText();
if (qualifiedGearNames(query).stream().anyMatch(QualifiedGearName::conflict))
return answer("ambiguous", selected.isBlank() ? null : selected, "当前内齿描述未明确为受支持的直齿类型,或包含冲突的内外齿限定;不加载相近规程。");
List<String> matches = coalesceMechanismComponents(candidates(query), selected);
matches = coalesceQualifiedPairName(query, matches, selected);
matches = coalesceSamePartNames(query, matches, selected);
if (!selected.isBlank() && !matches.contains(selected) && candidates(original.toLowerCase(Locale.ROOT)).contains(selected)
&& !query.equals(original.toLowerCase(Locale.ROOT)))
return answer("ambiguous", selected, "指定类型仅出现在被否定或非当前部件的文字中;不加载该规程。");
if (!selected.isBlank() && !types.containsKey(selected)) {
ObjectNode result = answer(matches.isEmpty() ? "uncovered" : "ambiguous", selected,
matches.isEmpty() ? "该类型未登记;继续原助手尝试,结果待验证。" : "指定ID未登记;query已命中候选,可省略type_id或使用返回的稳定ID重查。");
result.set("candidates", json.valueToTree(matches));
return result;
}
if (!selected.isBlank() && !matches.isEmpty() && !matches.contains(selected))
return answer("ambiguous", selected, "查询文字与指定类型不一致;请按当前部件确认类型,不能套用相近规程。");
if (selected.isBlank()) {
if (matches.size() != 1) return answer("ambiguous", null, "类型未明确;只为当前已确定的部件查询,不据传动角度猜齿制。").set("candidates", json.valueToTree(matches));
selected = matches.getFirst();
}
if (matches.size() > 1) return answer("ambiguous", selected, "包含不同类型;请仅查询当前确定的部件,不能合并加载相近规程。").set("candidates", json.valueToTree(matches));
JsonNode type = types.get(selected);
String conflictQuery = typeConflictQuery(selected, query);
for (JsonNode term : type.path("disqualifying_terms"))
if (conflictQuery.contains(term.asText().toLowerCase(Locale.ROOT)))
return answer("ambiguous", selected, "当前描述包含与该类型冲突的齿制信息;先区分类型,不加载近似规程。");
if (selected.endsWith("unspecified")) return answer("ambiguous", selected, "尚需区分齿线、节面或内外齿;不加载任何近似规程。").set("candidates", type.path("related_types"));
String finalSelected = selected;
List<Recipe> eligible = recipes.stream().filter(recipe -> finalSelected.equals(recipe.metadata().path("type_id").asText()))
.filter(recipe -> "approved".equals(recipe.metadata().path("status").asText()) || "pilot".equals(properties.getKnowledgeMode()) && "experimental".equals(recipe.metadata().path("status").asText())).toList();
if (eligible.isEmpty()) {
if ("mechanism".equals(type.path("kind").asText()))
return answer("uncovered", selected, "暂无机构规程;沿原流程设计,确定各部件类型后可分别查询,结果待验证。")
.set("related_types", type.path("related_types"));
return answer("uncovered", selected, "该类型暂无已准入规程;继续原助手尝试,结果待验证,勿套用相近齿制规程。");
}
List<Recipe> activated = eligible.stream().filter(recipe -> activationMatches(recipe.metadata().path("activation"), query)).toList();
if (activated.isEmpty()) return answer("not_applicable", selected, "当前操作无需额外提示;沿原通用技能继续,无需补参重查。");
JsonNode facts = arguments.path("facts");
List<Recipe> applicable = new ArrayList<>();
List<String> missing = new ArrayList<>();
List<String> conflicts = new ArrayList<>();
for (Recipe recipe : activated) {
List<String> absent = new ArrayList<>();
List<String> invalid = new ArrayList<>();
checkConditions(selected, recipe.metadata().path("conditions"), facts, absent, invalid);
if (absent.isEmpty() && invalid.isEmpty()) applicable.add(recipe);
missing.addAll(absent);
conflicts.addAll(invalid);
}
if (applicable.size() > 1) return answer("ambiguous", selected, "存在多个适用规程;需区分其变体条件,不自动选择相似项。");
if (applicable.isEmpty()) {
ObjectNode result = answer(conflicts.isEmpty() ? "needs_conditions" : "uncovered", selected,
conflicts.isEmpty() ? "正文未返回,尚未取得构造规程;仅当missing条件已明确采用时补齐并重查,不能据本结果声称已读取或适用。不为命中改变用户要求。" : "已给条件超出规程范围;继续原助手尝试,结果待验证,不自动改值。");
result.set("missing", json.valueToTree(missing.stream().distinct().toList()));
result.set("conflicts", json.valueToTree(conflicts.stream().distinct().toList()));
result.set("supported_conditions", activated.getFirst().metadata().path("conditions"));
return result;
}
Recipe recipe = applicable.getFirst();
String role = recipe.metadata().path("content_role").asText("recipe");
ObjectNode result = answer("matched", selected, "risk_hint".equals(role)
? "仅提示当前操作的已知风险,不是完整构造规程;新精简文本的模型收益未验证。"
: "适用当前部件;选配按用户要求,按正文表示与验证边界执行。");
result.putArray("documents").addObject().put("id", recipe.metadata().path("doc_id").asText())
.put("version", recipe.metadata().path("version").asText()).put("sha256", recipe.metadata().path("sha256").asText())
.put("status", recipe.metadata().path("status").asText()).put("content_role", role).put("text", recipe.text());
log.info("CAD knowledge matched: type={}, recipe={}, version={}", selected, recipe.metadata().path("doc_id").asText(), recipe.metadata().path("version").asText());
return result;
}
private ObjectNode answer(String status, String type, String reason) {
ObjectNode result = json.createObjectNode().put("status", status).put("reason", reason);
if (type != null) result.put("type_id", type);
result.putArray("documents");
result.putArray("missing");
return result;
}
private static boolean contains(JsonNode array, String value) {
for (JsonNode item : array) if (item.asText().equals(value)) return true;
return false;
}
static void checkConditions(String type, JsonNode conditions, JsonNode facts, List<String> missing, List<String> conflicts) {
Iterator<Map.Entry<String, JsonNode>> entries = conditions.fields();
while (entries.hasNext()) {
Map.Entry<String, JsonNode> entry = entries.next();
String name = entry.getKey();
JsonNode value = facts.get(name);
if (value == null || value.isNull()) { missing.add(name); continue; }
JsonNode rule = entry.getValue();
boolean valid;
if (rule.path("equals").isTextual() || rule.path("equals").isBoolean()) valid = rule.path("equals").equals(value);
else {
double number = value.asDouble(Double.NaN);
valid = value.isNumber() && numericConditionMatches(rule, number);
}
if (!valid) conflicts.add(name);
}
if ("involute-spur-gear".equals(type) && missing.isEmpty() && conflicts.isEmpty()) {
double module = facts.path("module_mm").asDouble();
double teeth = facts.path("teeth").asDouble();
double radius = module * teeth / 2;
double root = radius - (facts.path("addendum_coefficient").asDouble() + facts.path("clearance_coefficient").asDouble()) * module;
double base = radius * Math.cos(Math.toRadians(facts.path("pressure_angle_deg").asDouble()));
if (!Double.isFinite(root) || !Double.isFinite(base) || root <= 0 || root >= base) conflicts.add("root_radius_must_be_positive_and_below_base_radius");
}
if (!missing.isEmpty() || !conflicts.isEmpty()) return;
if ("internal-spur-gear".equals(type) && hasConditions(conditions, "module_mm", "teeth", "pressure_angle_deg", "outer_radius_mm")) {
double module = facts.path("module_mm").asDouble();
double pitch = module * facts.path("teeth").asDouble() / 2;
double root = pitch + 1.25 * module;
double tip = pitch - module;
double base = pitch * Math.cos(Math.toRadians(facts.path("pressure_angle_deg").asDouble()));
double outer = facts.path("outer_radius_mm").asDouble();
if (!Double.isFinite(root) || !Double.isFinite(tip) || !Double.isFinite(base)
|| !(outer > root && root > tip && tip > base && base > 0))
conflicts.add("internal_radii_must_satisfy_outer_gt_root_gt_tip_gt_base_gt_zero");
}
if (Set.of("helical-cylindrical-gear", "herringbone-gear", "double-helical-gear").contains(type)
&& hasConditions(conditions, "normal_module_mm", "teeth", "normal_pressure_angle_deg", "helix_angle_deg")) {
double module = facts.path("normal_module_mm").asDouble();
double cosine = Math.cos(Math.toRadians(facts.path("helix_angle_deg").asDouble()));
double pitch = module / cosine * facts.path("teeth").asDouble() / 2;
double pressure = Math.atan(Math.tan(Math.toRadians(facts.path("normal_pressure_angle_deg").asDouble())) / cosine);
double root = pitch - 1.25 * module;
double base = pitch * Math.cos(pressure);
double tip = pitch + module;
if (!Double.isFinite(root) || !Double.isFinite(base) || !Double.isFinite(tip)
|| !(root > 0 && root < base && base < tip))
conflicts.add("helical_radii_must_satisfy_zero_lt_root_lt_base_lt_tip");
}
if (Set.of("herringbone-gear", "double-helical-gear").contains(type)
&& hasConditions(conditions, "central_gap_mm", "face_width_mm")) {
double gap = facts.path("central_gap_mm").asDouble();
double width = facts.path("face_width_mm").asDouble();
if (!(gap >= 0 && gap < width)) conflicts.add("central_gap_must_leave_two_positive_width_arms");
}
if ("hex-head-bolt".equals(type)
&& hasConditions(conditions, "nominal_diameter_mm", "under_head_length_mm", "across_flats_mm", "thread_length_mm")) {
if (!(facts.path("across_flats_mm").asDouble() > facts.path("nominal_diameter_mm").asDouble()
&& facts.path("thread_length_mm").asDouble() <= facts.path("under_head_length_mm").asDouble()))
conflicts.add("hex_head_must_exceed_shank_and_thread_region_stay_below_head");
}
if ("ribbed-bearing-housing".equals(type) && hasConditions(conditions, "center_height_mm", "base_thickness_mm",
"boss_outer_diameter_mm", "bore_diameter_mm", "pedestal_width_mm", "rib_height_mm", "min_wall_mm")) {
double center = facts.path("center_height_mm").asDouble();
double base = facts.path("base_thickness_mm").asDouble();
double outer = facts.path("boss_outer_diameter_mm").asDouble();
double bore = facts.path("bore_diameter_mm").asDouble();
double wall = facts.path("min_wall_mm").asDouble();
if (!(center - outer / 2 >= base && center - bore / 2 - base >= wall
&& (outer - bore) / 2 >= wall && facts.path("pedestal_width_mm").asDouble() < outer
&& facts.path("rib_height_mm").asDouble() <= center - base))
conflicts.add("bearing_boss_pedestal_rib_and_bore_material_outside_recipe_domain");
}
if ("covered-thin-wall-enclosure".equals(type) && hasConditions(conditions, "length_mm", "width_mm", "height_mm",
"wall_thickness_mm", "bottom_thickness_mm", "lid_thickness_mm", "fastener_inset_mm",
"boss_outer_diameter_mm", "boss_height_mm", "pilot_depth_mm", "rib_height_mm", "min_wall_mm")) {
double length = facts.path("length_mm").asDouble();
double width = facts.path("width_mm").asDouble();
double height = facts.path("height_mm").asDouble();
double wall = facts.path("wall_thickness_mm").asDouble();
double bottom = facts.path("bottom_thickness_mm").asDouble();
double boss = facts.path("boss_height_mm").asDouble();
double diameter = facts.path("boss_outer_diameter_mm").asDouble();
double inset = facts.path("fastener_inset_mm").asDouble();
double minimum = facts.path("min_wall_mm").asDouble();
if (!(length > 2 * wall && width > 2 * wall && bottom < height && bottom + boss <= height
&& facts.path("pilot_depth_mm").asDouble() < boss && facts.path("rib_height_mm").asDouble() <= boss
&& inset - wall > diameter / 2 && length - 2 * inset > diameter && width - 2 * inset > diameter
&& wall >= minimum && bottom >= minimum && facts.path("lid_thickness_mm").asDouble() >= minimum))
conflicts.add("case_cavity_boss_blind_depth_fastener_or_wall_outside_recipe_domain");
}
if (Set.of("straight-bevel-gear", "spiral-bevel-gear").contains(type)
&& hasConditions(conditions, "module_mm", "teeth", "cone_angle_deg", "axial_height_mm", "geometry_representation")) {
double radius = facts.path("module_mm").asDouble() * facts.path("teeth").asDouble() / 2;
double apexHeight = radius / Math.tan(Math.toRadians(facts.path("cone_angle_deg").asDouble()));
double endScale = 1 - facts.path("axial_height_mm").asDouble() / apexHeight;
if (!Double.isFinite(radius) || !Double.isFinite(apexHeight) || !Double.isFinite(endScale)
|| !(endScale >= 0.45 && endScale <= 0.9))
conflicts.add("bevel_end_scale_must_be_between_045_and_09");
}
if ("worm".equals(type) && hasConditions(conditions, "axial_module_mm", "pitch_diameter_mm", "worm_starts", "axial_length_mm")) {
double module = facts.path("axial_module_mm").asDouble();
double root = facts.path("pitch_diameter_mm").asDouble() / 2 - 1.25 * module;
double pitch = Math.PI * module;
double lead = facts.path("worm_starts").asDouble() * pitch;
double length = facts.path("axial_length_mm").asDouble();
double turns = (length + 2 * lead) / lead;
if (!Double.isFinite(root) || !Double.isFinite(pitch) || !Double.isFinite(lead) || !Double.isFinite(turns)
|| !(root > 0.1 * module && length >= pitch && turns <= 200))
conflicts.add("worm_core_length_and_turns_outside_recipe_domain");
}
if ("worm-wheel".equals(type) && hasConditions(conditions, "module_mm", "teeth", "pressure_angle_deg", "pitch_diameter_mm", "face_width_mm", "geometry_representation")) {
double module = facts.path("module_mm").asDouble();
double pitch = module * facts.path("teeth").asDouble() / 2;
double wormRadius = facts.path("pitch_diameter_mm").asDouble() / 2;
double halfWidth = facts.path("face_width_mm").asDouble() / 2;
double major = pitch + wormRadius;
double minor = wormRadius - module;
double base = pitch * Math.cos(Math.toRadians(facts.path("pressure_angle_deg").asDouble()));
double midRadius = major - minor;
double radicand = minor * minor - halfWidth * halfWidth;
double endRadius = major - Math.sqrt(radicand);
double blankTip = pitch + 1.5 * module;
if (!Double.isFinite(base) || !Double.isFinite(midRadius) || !Double.isFinite(radicand)
|| !Double.isFinite(endRadius) || !Double.isFinite(blankTip)
|| !(minor > halfWidth && halfWidth > 0 && base < midRadius && midRadius < endRadius
&& endRadius < blankTip - 0.005 * module))
conflicts.add("worm_wheel_throat_outside_recipe_domain");
}
}
private static boolean hasConditions(JsonNode conditions, String... names) {
for (String name : names) if (!conditions.has(name)) return false;
return true;
}
private static String currentPartQuery(String query) {
return query.toLowerCase(Locale.ROOT).replaceFirst("(?s)^.*(当前只造|当前只做|当前待修改部件是|中先做|只造)", "$1");
}
private static String typeConflictQuery(String type, String query) {
// A clause declaring absent optional features does not assert those features.
// Do not cross a positive replacement, independent target, or clause boundary.
String focused = query;
if (Set.of("mounting-plate", "covered-thin-wall-enclosure").contains(type))
focused = query.replaceAll("(^|[,,。;;\\s])(?:无|没有|不加|不设(?:置)?|不含|不包含|不带|不留)[^,,。;;\\n\\d]*?(?=,|,|。|;|;|\\n|但|而|仍|却|保留|改用|改成|换成|另(?:做|加|有|带|留)|或(?:有|带|保留|生成)|$)", "$1");
if (!"herringbone-gear".equals(type)) return focused;
// Absence and a literal zero-width attribute are not a grooved tooth structure.
// Scope to complete attribute clauses; keep positive/uncertain conflicts and facts.
return focused.replaceAll("(^|[,,。;;\\s])(?:无|没有|不带|不设(?:置)?|不含|不留)\\s*(?:中央|中心)?\\s*(?:退刀槽|槽)(?=\\s*(?:[,,。;;\\n]|$))", "$1")
.replaceAll("(^|[,,。;;\\s])(?:中央|中心)?(?:退刀)?槽(?:的)?(?:轴向)?宽(?:度)?\\s*(?:为|等于|=|:|:)?\\s*0(?:\\.0+)?(?![\\d.])\\s*(?:mm|毫米)?(?=\\s*(?:[,,。;;\\n]|$))", "$1")
.replaceAll("\\bno\\s+(?:a\\s+)?(?:central\\s+)?(?:groove|gap)\\b(?=\\s*(?:[,.;]|$))", " ")
.replaceAll("\\b(?:central\\s+)?(?:gap|groove)(?:\\s+width)?\\s*(?:=|:|is|of)?\\s*0(?:\\.0+)?(?![\\d.])\\s*(?:mm)?(?=\\s*(?:[,.;]|$))", " ");
}
private String positiveQuery(String query) {
// A prohibited substitution stays negative through its entire clause. A verb such
// as “用” or “改成” inside that clause does not introduce a positive alternative.
String focused = currentPartQuery(query).replaceAll("(?:不得|禁止|严禁|不可|不能|切勿|请勿|勿|不允许|不准|不许|不应|避免|不要(?:将|把|使用|采用|用|以|拿)|\\b(?:do|must|should)\\s+not\\b|\\bnever\\b)[^,,。;;\\n]*", " ");
// Simple rejected alternatives can still precede an explicit replacement marker.
focused = focused.replaceAll("(?:不要|不是|不用|不做|不造|不需要|不生成|不创建|不制作|不建|改掉|\\bwithout\\b|\\bnot\\b)[^,,。;;\\n]*?(?=,|,|。|;|;|\\n|改用|换成|改成|而是|但(?:要)?(?:生成|制作|创建|构造)|$)", " ");
Matcher references = referenceNames.matcher(focused);
StringBuilder positive = new StringBuilder();
while (references.find()) {
// A reference object is not a creation target, unless the request explicitly
// creates that reference object. Keep dimensions as prose, never infer facts.
boolean created = REFERENCE_CREATION.matcher(focused.substring(0, references.start())).matches();
references.appendReplacement(positive, created ? Matcher.quoteReplacement(references.group()) : " ");
}
references.appendTail(positive);
focused = positive.toString();
Matcher companions = companionNames.matcher(focused);
positive = new StringBuilder();
while (companions.find()) {
String prefix = focused.substring(0, companions.start());
List<String> targets = candidates(prefix);
List<String> referencesOnly = candidates(companions.group());
// A companion with an interface dimension is a reference only after one
// explicit, different target. Joined or independently created parts remain.
boolean reference = targets.size() == 1 && !referencesOnly.contains(targets.getFirst())
&& TARGET_INTENT.matcher(prefix).find() && !JOINED_TARGET.matcher(prefix).matches()
&& !REFERENCE_CREATION.matcher(prefix).matches()
&& !TARGET_INTENT.matcher(focused.substring(companions.end()).split("[,,。;;\\r\\n]", 2)[0]).find();
companions.appendReplacement(positive, reference ? " " : Matcher.quoteReplacement(companions.group()));
}
companions.appendTail(positive);
focused = positive.toString();
Matcher interfaces = SHAFT_INTERFACE.matcher(focused);
positive = new StringBuilder();
while (interfaces.find()) {
String prefix = focused.substring(0, interfaces.start());
boolean reference = candidates(prefix).equals(List.of("stepped-shaft"))
&& TARGET_INTENT.matcher(prefix).find() && !JOINED_TARGET.matcher(prefix).matches()
&& !REFERENCE_CREATION.matcher(prefix).matches();
interfaces.appendReplacement(positive, reference ? "配合孔" : Matcher.quoteReplacement(interfaces.group()));
}
interfaces.appendTail(positive);
return positive.toString();
}
private static Pattern referenceNames(Map<String, JsonNode> types) {
String object = objectNames(types);
return Pattern.compile("(?:参考" + REFERENCE_MODIFIERS + object
+ "|\\breference\\s+(?:(?:existing|known)\\s+)?" + object
+ "|" + object + "\\s*(?:仅作为|只作为|作为|仅供|只供)\\s*参考)");
}
private static String objectNames(Map<String, JsonNode> types) {
Set<String> names = new HashSet<>();
for (JsonNode type : types.values()) for (JsonNode alias : type.path("aliases")) names.add(alias.asText().toLowerCase(Locale.ROOT));
String alternatives = names.stream().sorted(Comparator.comparingInt(String::length).reversed().thenComparing(Comparator.naturalOrder()))
.map(Pattern::quote).reduce((left, right) -> left + "|" + right).orElse("(?!)");
return "(?:" + alternatives + ")";
}
private List<String> coalesceMechanismComponents(List<String> matches, String selected) {
JsonNode mechanism = types.get(selected);
if (mechanism == null || !"mechanism".equals(mechanism.path("kind").asText()) || !matches.contains(selected)) return matches;
// An explicitly selected mechanism and its registered components describe one assembly.
// Never absorb an unrelated type, another mechanism, or an unregistered relationship.
Set<String> components = new HashSet<>();
for (JsonNode component : mechanism.path("related_types")) components.add(component.asText());
for (String id : matches) {
if (id.equals(selected) || components.contains(id)) continue;
JsonNode candidate = types.get(id);
boolean correspondingGeneralType = id.endsWith("unspecified") && candidate != null;
if (correspondingGeneralType) {
correspondingGeneralType = false;
for (JsonNode subtype : candidate.path("related_types"))
if (components.contains(subtype.asText())) correspondingGeneralType = true;
}
if (!correspondingGeneralType) return matches;
}
return List.of(selected);
}
private List<String> coalesceSamePartNames(String query, List<String> matches, String selected) {
// A shape description may repeat the general noun for the same specified part.
// Preserve separate components and every independently specified alternate subtype.
if (query.matches("(?s).*(?:另一个|另一件|另外|另做|另加|再做|再加|第二个|第二件|多个|各一个|分别|another|additional|second|separate|different|two gears|[两二2](?:个|只|件|种)).*")
|| query.matches("(?s).*(?:和|及|与|以及|and)\\s*(?:一个|一件|一只|one\\b|a\\b|an\\b|another|另|齿轮|gear\\b).*")) return matches;
List<String> specific = matches.stream().filter(id -> !id.endsWith("unspecified")).toList();
if (specific.size() != 1 || !selected.isBlank() && !selected.equals(specific.getFirst())) return matches;
String subtype = specific.getFirst();
return matches.stream().filter(id -> !id.endsWith("unspecified")
|| !contains(types.get(id).path("related_types"), subtype)).toList();
}
private List<String> coalesceQualifiedPairName(String query, List<String> matches, String selected) {
JsonNode part = types.get(selected);
JsonNode pair = types.get("gear-pair");
if (part == null || !"part".equals(part.path("kind").asText()) || pair == null
|| !matches.contains(selected) || !matches.contains("gear-pair")) return matches;
// A selected part may qualify the same noun as “double-helical gear pair”.
// Absorb only overlapping names; an independent pair remains another target.
for (JsonNode alias : pair.path("aliases")) {
String term = alias.asText().toLowerCase(Locale.ROOT);
int from = 0;
int at;
while ((at = query.indexOf(term, from)) >= 0) {
from = at + term.length();
String shared = "齿轮副".equals(term) ? "齿轮" : "gear pair".equals(term) ? "gear" : null;
if (shared == null) return matches;
boolean qualified = false;
for (JsonNode partAlias : part.path("aliases")) {
String name = partAlias.asText().toLowerCase(Locale.ROOT);
int start = at + shared.length() - name.length();
if (name.endsWith(shared) && start >= 0 && query.startsWith(name, start)
&& (!"gear".equals(shared) || start == 0 || !isLatinLetter(query.charAt(start - 1)))) {
qualified = true;
break;
}
}
if (!qualified) return matches;
}
}
return matches.stream().filter(id -> !"gear-pair".equals(id)).toList();
}
private static boolean isLatinLetter(char character) { return character >= 'a' && character <= 'z'; }
private static List<QualifiedGearName> qualifiedGearNames(String query) {
// Compose local name modifiers instead of adding complete user sentences as aliases.
// The span cannot cross punctuation or conjunctions into a different component.
List<QualifiedGearName> names = new ArrayList<>();
for (Pattern pattern : QUALIFIED_GEAR_NAMES) {
Matcher matcher = pattern.matcher(query);
while (matcher.find()) {
String name = matcher.group();
boolean internal = name.contains("内") || name.contains("internal");
boolean external = name.contains("外") || name.contains("external");
boolean qualified = name.matches("(?s).*(?:渐开线|直齿|斜齿|螺旋|圆柱|环形|锥齿|圆锥|involute|spur|helical|bevel|cylindrical|ring).*");
if ((!internal && !external) || !qualified) continue;
boolean straight = name.contains("直齿") || name.contains("spur");
boolean otherToothForm = name.matches("(?s).*(?:斜齿|螺旋|锥齿|圆锥|helical|bevel).*");
boolean conflict = internal && (external || !straight || otherToothForm);
String type = straight && !otherToothForm && !conflict
? internal ? "internal-spur-gear" : "involute-spur-gear" : null;
if (type != null || conflict)
names.add(new QualifiedGearName(matcher.group(), type, matcher.start(), matcher.end(), conflict));
}
}
return names;
}
private List<String> candidates(String query) {
record Hit(String id, String alias, int start, int end) {}
List<Hit> hits = new ArrayList<>();
for (Map.Entry<String, JsonNode> entry : types.entrySet()) for (JsonNode alias : entry.getValue().path("aliases")) {
String term = alias.asText().toLowerCase(Locale.ROOT);
int from = 0;
int at;
while ((at = query.indexOf(term, from)) >= 0) {
from = at + term.length();
if ("齿轮".equals(term) && query.startsWith("齿轮箱", at)) continue;
if (term.matches("[a-z -]+") && (at > 0 && isLatinLetter(query.charAt(at - 1))
|| at + term.length() < query.length() && isLatinLetter(query.charAt(at + term.length())))) continue;
hits.add(new Hit(entry.getKey(), term, at, from));
}
}
for (QualifiedGearName name : qualifiedGearNames(query))
if (name.type() != null) hits.add(new Hit(name.type(), name.name(), name.start(), name.end()));
// A general “gear” inside a precise alias is not an independent candidate.
return hits.stream().filter(hit -> hits.stream().noneMatch(other -> !other.id().equals(hit.id()) && other.start() <= hit.start() && other.end() >= hit.end() && other.alias().length() > hit.alias().length()))
.map(Hit::id).distinct().sorted().toList();
}
/** Runs during process-classes even when Maven is invoked with -DskipTests. */
public static void main(String[] arguments) throws IOException {
new CadAiKnowledge(new ObjectMapper(), new CadAiProperties());
}
}
@@ -1,702 +0,0 @@
package com.linkerbot.vibemake.service.cad.ai;
import static org.assertj.core.api.Assertions.*;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.linkerbot.vibemake.service.config.CadAiProperties;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.*;
import org.junit.jupiter.api.*;
class CadAiKnowledgeTest {
private static final String BUILD = "5707e4ae25621c4a32c40108";
private static final String EXPANSION_BUILD = "f3d62ce93f72db42f311a46e";
private final ObjectMapper json = new ObjectMapper();
private CadAiProperties properties;
private CadAiKnowledge knowledge;
@BeforeEach void setup() throws Exception {
properties = new CadAiProperties();
properties.setKnowledgeMode("pilot");
knowledge = HistoricalCadAiKnowledge.knowledge(json, properties);
}
private ObjectNode request(String query) {
ObjectNode input = json.createObjectNode().put("query", query);
input.putObject("facts").put("module_mm", 2).put("teeth", 24).put("pressure_angle_deg", 20)
.put("profile_shift", 0).put("backlash_mm", 0).put("addendum_coefficient", 1)
.put("clearance_coefficient", 0.25).put("root_transition", "radial-simplified");
return input;
}
@Test void fixedRoutingEvaluationCovers140DeclaredScenarios() throws Exception {
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v3.json"));
assertThat(suite.path("cases")).hasSize(140);
Map<String, Integer> counts = new HashMap<>();
for (JsonNode item : suite.path("cases")) {
counts.merge(item.path("group").asText(), 1, Integer::sum);
if (item.has("previous_query")) {
assertThat(knowledge.lookup(request(item.path("previous_query").asText()), item.path("previous_build").asText(BUILD)).path("status").asText())
.as(item.path("id").asText()).isEqualTo(item.path("previous_status").asText());
}
ObjectNode input = request(item.path("query").asText());
if (item.has("facts")) input.set("facts", item.path("facts").deepCopy());
ObjectNode facts = (ObjectNode) input.path("facts");
for (JsonNode field : item.path("remove_facts")) facts.remove(field.asText());
Iterator<Map.Entry<String, JsonNode>> overrides = item.path("fact_overrides").fields();
while (overrides.hasNext()) { Map.Entry<String, JsonNode> entry = overrides.next(); facts.set(entry.getKey(), entry.getValue()); }
JsonNode result = knowledge.lookup(input, item.path("build").asText(BUILD));
String expectedStatus = HistoricalCadAiKnowledge.runtimeStatus(item);
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo(expectedStatus);
if (item.has("type_id")) assertThat(result.path("type_id").asText()).as(item.path("id").asText()).isEqualTo(item.path("type_id").asText());
assertThat(result.path("documents").size()).as(item.path("id").asText()).isEqualTo("matched".equals(expectedStatus) ? 1 : 0);
if (item.has("doc_id")) assertThat(result.path("documents").get(0).path("id").asText())
.as(item.path("id").asText()).isEqualTo(item.path("doc_id").asText());
for (JsonNode field : item.path("missing")) assertThat(result.path("missing").toString())
.as(item.path("id").asText()).contains(field.asText());
for (JsonNode field : item.path("conflicts")) assertThat(result.path("conflicts").toString())
.as(item.path("id").asText()).contains(field.asText());
}
assertThat(counts).containsExactlyInAnyOrderEntriesOf(Map.ofEntries(
Map.entry("explicit",18), Map.entry("nested",12), Map.entry("ambiguous",10), Map.entry("negation",8),
Map.entry("multi_turn",12), Map.entry("unavailable",8), Map.entry("nonmodel",4), Map.entry("eligible",13),
Map.entry("missing",13), Map.entry("scope",13), Map.entry("compatibility",13), Map.entry("mechanism_component",4),
Map.entry("derived_domain",12)));
}
@Test void fixedRoutingV4KeepsHistoricalCasesAndChecksExplicitMechanismMembership() throws Exception {
JsonNode previous = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v3.json"));
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v4.json"));
assertThat(suite.path("cases")).hasSize(152);
for (int index = 0; index < 140; index++) assertThat(suite.path("cases").get(index)).isEqualTo(previous.path("cases").get(index));
for (JsonNode item : suite.path("cases")) {
if (!"mechanism_membership".equals(item.path("group").asText())) continue;
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
input.set("facts", item.path("facts").deepCopy());
if (item.has("input_type_id")) input.put("type_id", item.path("input_type_id").asText());
JsonNode result = knowledge.lookup(input, item.path("build").asText());
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo(item.path("status").asText());
assertThat(result.path("documents").size()).as(item.path("id").asText()).isEqualTo("matched".equals(item.path("status").asText()) ? 1 : 0);
if (item.has("doc_id")) assertThat(result.path("documents").get(0).path("id").asText()).isEqualTo(item.path("doc_id").asText());
}
}
@Test void fixedRoutingV5KeepsHistoricalCasesAndChecksScopedEngagementQualifiers() throws Exception {
JsonNode previous = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v4.json"));
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v5.json"));
assertThat(suite.path("cases")).hasSize(180);
for (int index = 0; index < 152; index++) assertThat(suite.path("cases").get(index)).isEqualTo(previous.path("cases").get(index));
List<org.junit.jupiter.api.function.Executable> checks = new ArrayList<>();
for (JsonNode item : suite.path("cases")) {
if (!"engagement_qualifier".equals(item.path("group").asText())) continue;
checks.add(() -> {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
input.set("facts", item.path("facts").deepCopy());
if (item.has("input_type_id")) input.put("type_id", item.path("input_type_id").asText());
ObjectNode original = input.deepCopy();
JsonNode result = knowledge.lookup(input, item.path("build").asText());
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo(item.path("status").asText());
assertThat(result.path("documents").size()).as(item.path("id").asText()).isEqualTo("matched".equals(item.path("status").asText()) ? 1 : 0);
if (item.has("type_id")) assertThat(result.path("type_id").asText()).as(item.path("id").asText()).isEqualTo(item.path("type_id").asText());
if (item.has("doc_id")) assertThat(result.path("documents").get(0).path("id").asText()).isEqualTo(item.path("doc_id").asText());
assertThat(input).isEqualTo(original);
});
}
assertThat(checks).hasSize(28);
org.junit.jupiter.api.Assertions.assertAll(checks);
}
@Test void fixedRoutingV6KeepsHistoryAndChecksProhibitionScopeAndExplicitRackPinionNames() throws Exception {
JsonNode previous = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v5.json"));
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v6.json"));
assertThat(suite.path("cases")).hasSize(222);
for (int index = 0; index < 180; index++) assertThat(suite.path("cases").get(index)).isEqualTo(previous.path("cases").get(index));
List<org.junit.jupiter.api.function.Executable> checks = new ArrayList<>();
for (int index = 180; index < suite.path("cases").size(); index++) {
JsonNode item = suite.path("cases").get(index);
checks.add(() -> {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
input.set("facts", item.path("facts").deepCopy());
if (item.has("input_type_id")) input.put("type_id", item.path("input_type_id").asText());
ObjectNode original = input.deepCopy();
JsonNode result = knowledge.lookup(input, item.path("build").asText());
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo(item.path("status").asText());
assertThat(result.path("documents").size()).as(item.path("id").asText()).isEqualTo("matched".equals(item.path("status").asText()) ? 1 : 0);
if (item.has("type_id")) assertThat(result.path("type_id").asText()).as(item.path("id").asText()).isEqualTo(item.path("type_id").asText());
if (item.has("doc_id")) assertThat(result.path("documents").get(0).path("id").asText()).isEqualTo(item.path("doc_id").asText());
for (JsonNode field : item.path("missing")) assertThat(result.path("missing").toString()).as(item.path("id").asText()).contains(field.asText());
assertThat(input).isEqualTo(original);
});
}
assertThat(checks).hasSize(42);
org.junit.jupiter.api.Assertions.assertAll(checks);
}
@Test void fixedRoutingV7PreservesHistoryAndSeparatesReferencesFromCreationTargets() throws Exception {
JsonNode previous = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v6.json"));
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v7.json"));
assertThat(suite.path("cases").size()).isGreaterThan(222);
for (int index = 0; index < 222; index++) assertThat(suite.path("cases").get(index)).isEqualTo(previous.path("cases").get(index));
List<org.junit.jupiter.api.function.Executable> checks = new ArrayList<>();
for (int index = 222; index < suite.path("cases").size(); index++) {
JsonNode item = suite.path("cases").get(index);
checks.add(() -> {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
input.set("facts", item.path("facts").deepCopy());
if (item.has("input_type_id")) input.put("type_id", item.path("input_type_id").asText());
ObjectNode original = input.deepCopy();
JsonNode result = knowledge.lookup(input, EXPANSION_BUILD);
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo(item.path("status").asText());
assertThat(result.path("documents").size()).as(item.path("id").asText()).isEqualTo("matched".equals(item.path("status").asText()) ? 1 : 0);
if (item.has("type_id")) assertThat(result.path("type_id").asText()).as(item.path("id").asText()).isEqualTo(item.path("type_id").asText());
if (item.has("doc_id")) assertThat(result.path("documents").get(0).path("id").asText()).isEqualTo(item.path("doc_id").asText());
assertThat(input).isEqualTo(original);
});
}
org.junit.jupiter.api.Assertions.assertAll(checks);
}
@Test void fixedRoutingV8KeepsHistoryAndRequiresQualifiedPinionTypes() throws Exception {
JsonNode previous = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v7.json"));
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v8.json"));
assertThat(suite.path("cases")).hasSize(287);
for (int index = 0; index < 268; index++) assertThat(suite.path("cases").get(index)).isEqualTo(previous.path("cases").get(index));
List<org.junit.jupiter.api.function.Executable> checks = new ArrayList<>();
for (int index = 268; index < suite.path("cases").size(); index++) {
JsonNode item = suite.path("cases").get(index);
checks.add(() -> {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
input.set("facts", item.path("facts").deepCopy());
JsonNode result = knowledge.lookup(input, EXPANSION_BUILD);
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo(item.path("status").asText());
assertThat(result.path("documents").size()).isZero();
if (item.has("type_id")) assertThat(result.path("type_id").asText()).as(item.path("id").asText()).isEqualTo(item.path("type_id").asText());
});
}
org.junit.jupiter.api.Assertions.assertAll(checks);
}
@Test void wormFactDescriptionsIdentifyTheReferenceObjectWithoutInferringValues() throws Exception {
JsonNode fields = HistoricalCadAiKnowledge.tools(json).definitions(true).stream().filter(tool -> "knowledge_lookup".equals(tool.name()))
.findFirst().orElseThrow().parameters().path("properties").path("facts").path("properties");
assertThat(fields.path("pitch_diameter_mm").path("description").asText()).contains("蜗杆", "参考", "蜗轮", "不是");
assertThat(fields.path("worm_starts").path("description").asText()).contains("参考", "蜗轮");
}
@Test void rackFactDescriptionsSeparateCircularToothCountAndRootBelowBaseThickness() throws Exception {
JsonNode fields = HistoricalCadAiKnowledge.tools(json).definitions(true).stream().filter(tool -> "knowledge_lookup".equals(tool.name()))
.findFirst().orElseThrow().parameters().path("properties").path("facts").path("properties");
assertThat(fields.path("teeth").path("description").asText()).contains("圆齿轮", "rack_teeth");
assertThat(fields.path("rack_teeth").path("description").asText()).contains("直齿齿条", "斜齿齿条", "完整齿数", "teeth");
assertThat(fields.path("base_height_mm").path("description").asText()).contains("直齿齿条", "斜齿齿条", "齿根", "底面", "不含齿高");
}
@Test void conflictResponseOffersRegisteredConditionsWithoutChangingInput() throws Exception {
ObjectNode input = json.createObjectNode().put("query", "直齿锥齿轮").put("type_id", "straight-bevel-gear");
input.set("facts", json.readTree("""
{"module_mm":2,"teeth":24,"pressure_angle_deg":20,"profile_shift":0,"backlash_mm":0,
"addendum_coefficient":1,"clearance_coefficient":0.25,"cone_angle_deg":45,"axial_height_mm":8,
"root_transition":"radial-simplified","geometry_representation":"natural-language approximation"}
"""));
ObjectNode original = input.deepCopy();
JsonNode result = knowledge.lookup(input, EXPANSION_BUILD);
assertThat(result.path("status").asText()).isEqualTo("uncovered");
assertThat(result.path("documents")).isEmpty();
assertThat(result.path("supported_conditions").path("geometry_representation").path("equals").asText())
.isEqualTo("homothetic-frontal-involute-bevel-v1");
assertThat(input).isEqualTo(original);
}
@Test void schemaListsPolicyRepresentationIdsAndPressureAngleApplicability() throws Exception {
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
JsonNode schema = tools.definitions(true).stream().filter(tool -> "knowledge_lookup".equals(tool.name())).findFirst().orElseThrow().parameters();
JsonNode fields = schema.path("properties").path("facts").path("properties");
JsonNode policy = HistoricalCadAiKnowledge.policy(json);
Set<String> expected = new TreeSet<>();
for (JsonNode document : policy.path("documents")) {
JsonNode value = document.path("conditions").path("geometry_representation").path("equals");
if (!"retired".equals(document.path("status").asText()) && value.isTextual()) expected.add(value.asText());
}
Set<String> actual = new TreeSet<>();
for (JsonNode value : fields.path("geometry_representation").path("enum")) if (value.isTextual()) actual.add(value.asText());
assertThat(actual).containsExactlyElementsOf(expected);
assertThat(fields.path("pressure_angle_deg").path("description").asText()).contains("直齿", "端面", "normal_pressure_angle_deg", "axial_pressure_angle_deg");
assertThat(fields.path("normal_pressure_angle_deg").path("description").asText()).contains("斜齿圆柱", "斜齿齿条");
assertThat(fields.path("axial_pressure_angle_deg").path("description").asText()).contains("ZA蜗杆");
ObjectNode input = request("齿轮副").put("type_id", "gear-pair");
((ObjectNode) input.path("facts")).putNull("geometry_representation");
tools.validateCall("knowledge_lookup", input);
((ObjectNode) input.path("facts")).put("geometry_representation", "invented-representation");
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", input)).isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
assertThat(CadAiKnowledge.INSTRUCTIONS).doesNotContain("一次查询").contains("补齐", "重查");
}
@Test void rootTransitionSchemaUsesPolicyValuesAndIdentifiesInternalCircularRoot() throws Exception {
JsonNode schema = HistoricalCadAiKnowledge.tools(json).definitions(true).stream().filter(tool -> "knowledge_lookup".equals(tool.name()))
.findFirst().orElseThrow().parameters().path("properties").path("facts").path("properties");
JsonNode root = schema.path("root_transition");
Set<String> values = new TreeSet<>();
for (JsonNode value : root.path("enum")) if (value.isTextual()) values.add(value.asText());
assertThat(values).containsExactly("circular-simplified", "radial-simplified", "sharp-simplified");
assertThat(root.path("description").asText()).contains("内直齿", "圆弧", "径向", "尖角", "internal-spur-gear", "circular-simplified");
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
for (String value : values) {
ObjectNode input = request("直齿轮");
((ObjectNode) input.path("facts")).put("root_transition", value);
tools.validateCall("knowledge_lookup", input);
}
ObjectNode input = request("内直齿轮").put("type_id", "internal-spur-gear");
((ObjectNode) input.path("facts")).put("teeth",40).put("outer_radius_mm",50);
ObjectNode original = input.deepCopy();
JsonNode result = knowledge.lookup(input, EXPANSION_BUILD);
assertThat(result.path("status").asText()).isEqualTo("uncovered");
assertThat(result.path("supported_conditions").path("root_transition").path("equals").asText()).isEqualTo("circular-simplified");
assertThat(input).isEqualTo(original);
((ObjectNode) input.path("facts")).putNull("root_transition");
tools.validateCall("knowledge_lookup", input);
assertThat(knowledge.lookup(input, EXPANSION_BUILD).path("status").asText()).isEqualTo("needs_conditions");
}
@Test void directlyLoadsOnlyUnchangedRecipeOnceConditionsAndBuildMatch() {
JsonNode result = knowledge.lookup(request("做一个渐开线直齿轮,不要凸台和键槽"), BUILD);
assertThat(result.path("status").asText()).isEqualTo("matched");
assertThat(result.path("documents")).hasSize(1);
assertThat(result.path("documents").get(0).path("sha256").asText())
.isEqualTo("70cf10a008e7f4183456579201d1f42fbc04511f4cb573a8afd784e2d730ab2d");
assertThat(result.path("documents").get(0).path("text").asText()).contains("sketch.equation_curve");
assertThat(result.toString()).doesNotContain("MCB", "完整分类树");
}
@Test void separatesGearTypesAndRequiresTheirOwnConditions() {
Map<String, String> inputs = Map.ofEntries(
Map.entry("斜齿轮", "helical-cylindrical-gear"), Map.entry("直齿锥齿轮", "straight-bevel-gear"), Map.entry("圆锥直齿轮", "straight-bevel-gear"), Map.entry("内啮合直齿轮", "internal-spur-gear"),
Map.entry("螺旋锥齿轮", "spiral-bevel-gear"), Map.entry("内直齿轮", "internal-spur-gear"),
Map.entry("直齿齿条", "straight-rack"), Map.entry("斜齿齿条", "helical-rack"),
Map.entry("蜗轮", "worm-wheel"), Map.entry("蜗杆", "worm"),
Map.entry("齿轮箱外壳", "gearbox-housing"), Map.entry("摆线齿轮", "other-geared-transmission"));
for (Map.Entry<String, String> input : inputs.entrySet()) {
JsonNode result = knowledge.lookup(json.createObjectNode().put("query", input.getKey()), EXPANSION_BUILD);
assertThat(result.path("type_id").asText()).as(input.getKey()).isEqualTo(input.getValue());
assertThat(result.path("documents")).isEmpty();
assertThat(result.path("status").asText()).isEqualTo(
Set.of("gearbox-housing", "other-geared-transmission").contains(input.getValue()) ? "uncovered" : "needs_conditions");
}
}
@Test void keepsAmbiguityAndMechanismBoundaries() {
for (String query : List.of("齿轮", "螺旋齿轮", "锥齿轮", "齿条", "平行轴传动", "90度传动")) {
JsonNode result = knowledge.lookup(request(query), BUILD);
assertThat(result.path("status").asText()).as(query).isEqualTo("ambiguous");
assertThat(result.path("documents")).isEmpty();
}
for (String query : List.of("蜗轮蜗杆机构", "齿轮齿条机构", "行星齿轮机构", "齿轮副")) {
JsonNode result = knowledge.lookup(json.createObjectNode().put("query", query), EXPANSION_BUILD);
assertThat(result.path("documents")).as(query).isEmpty();
assertThat(result.path("status").asText()).as(query).isEqualTo("needs_conditions");
assertThat(result.path("missing").toString()).contains("geometry_representation");
}
}
@Test void honorsNegatedAlternativesAndRejectsConflictingExplicitType() {
assertThat(knowledge.lookup(request("不要蜗杆,用直齿轮"), BUILD).path("status").asText()).isEqualTo("matched");
assertThat(knowledge.lookup(request("不要直齿轮,改成斜齿轮"), BUILD).path("type_id").asText()).isEqualTo("helical-cylindrical-gear");
assertThat(knowledge.lookup(request("直齿锥齿轮").put("type_id", "involute-spur-gear"), BUILD).path("status").asText()).isEqualTo("ambiguous");
assertThat(knowledge.lookup(request("不要齿轮"), BUILD).path("documents")).isEmpty();
assertThat(knowledge.lookup(request("不要直齿轮,只做外壳").put("type_id", "involute-spur-gear"), BUILD).path("documents")).isEmpty();
assertThat(knowledge.lookup(request("做一个spur gear和一个未明确的gear"), BUILD).path("status").asText()).isEqualTo("ambiguous");
}
@Test void requiresEveryCriticalConditionAndRejectsUnsupportedValuesWithoutChangingThem() {
ObjectNode complete = request("直齿轮");
List<String> fields = new ArrayList<>();
complete.path("facts").fieldNames().forEachRemaining(fields::add);
for (String field : fields) {
ObjectNode input = complete.deepCopy();
((ObjectNode) input.path("facts")).remove(field);
JsonNode result = knowledge.lookup(input, BUILD);
assertThat(result.path("status").asText()).as(field).isEqualTo("needs_conditions");
assertThat(result.path("missing").toString()).contains(field);
assertThat(result.path("documents")).isEmpty();
}
for (String field : List.of("pressure_angle_deg", "profile_shift", "backlash_mm", "addendum_coefficient", "clearance_coefficient")) {
ObjectNode input = complete.deepCopy();
((ObjectNode) input.path("facts")).put(field, 13);
JsonNode result = knowledge.lookup(input, BUILD);
assertThat(result.path("status").asText()).as(field).isEqualTo("uncovered");
assertThat(result.path("conflicts").toString()).contains(field);
assertThat(result.path("documents")).isEmpty();
assertThat(input.path("facts").path(field).asInt()).isEqualTo(13);
}
for (double teeth : List.of(17.0, 41.0, 24.5)) {
ObjectNode input = complete.deepCopy();
((ObjectNode) input.path("facts")).put("teeth", teeth);
assertThat(knowledge.lookup(input, BUILD).path("documents")).isEmpty();
}
}
@Test void respectsModeWithoutCouplingIndependentFrontendAndBackendBuilds() {
for (String build : Arrays.asList(null, "", "000000000000000000000000", "independent-frontend-release"))
assertThat(knowledge.lookup(request("直齿轮"), build).path("status").asText()).isEqualTo("matched");
properties.setKnowledgeMode("enabled");
assertThat(knowledge.lookup(request("直齿轮"), BUILD).path("status").asText()).isEqualTo("uncovered");
properties.setKnowledgeMode("off");
assertThat(knowledge.lookup(request("直齿轮"), BUILD).path("status").asText()).isEqualTo("disabled");
}
@Test void historicalBuildEvidenceIsOptionalAndDoesNotControlResourceInitialization() throws Exception {
List<JsonNode> metadata = Arrays.asList(null, json.nullNode(), json.createArrayNode(),
json.createArrayNode().add("old-release-label"), json.getNodeFactory().textNode("historical-note"),
json.createObjectNode().put("diagnostic", "not-an-admission-list"));
for (JsonNode value : metadata) {
JsonNode policy = HistoricalCadAiKnowledge.policy(json).deepCopy();
for (JsonNode item : policy.path("documents")) {
ObjectNode document = (ObjectNode) item;
if (value == null) document.remove("compatible_builds");
else document.set("compatible_builds", value.deepCopy());
}
CadAiKnowledge independent = new CadAiKnowledge(json, properties, policy);
JsonNode result = independent.lookup(request("创建外渐开线直齿轮"), null);
assertThat(result.path("status").asText()).isEqualTo("matched");
assertThat(result.path("documents")).isEqualTo(knowledge.lookup(request("创建外渐开线直齿轮"), BUILD).path("documents"));
}
}
@Test void buildValidationRejectsTamperedBodyAndBrokenCatalog() throws Exception {
assertThatThrownBy(() -> CadAiKnowledge.verifyHash("changed".getBytes(StandardCharsets.UTF_8), "0".repeat(64))).isInstanceOf(IOException.class);
JsonNode catalog = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/generation/catalog.json"));
((ObjectNode) catalog.path("types").get(0)).put("parent", "not-registered");
assertThatThrownBy(() -> CadAiKnowledge.validateCatalog(catalog)).isInstanceOf(IOException.class);
((ObjectNode) catalog.path("types").get(0)).put("parent", "gear-transmission");
assertThatThrownBy(() -> CadAiKnowledge.validateCatalog(catalog)).isInstanceOf(IOException.class);
}
@Test void rejectsHostileStringsAndNumericOverflowBeforeRecipeUse() throws Exception {
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
for (ObjectNode invalid : List.of(request(""), request("x".repeat(2001)), request("直齿轮").put("type_id", "x".repeat(81)))) {
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", invalid))
.isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
}
ObjectNode input = request("直齿轮");
((ObjectNode) input.path("facts")).put("module_mm", Double.MAX_VALUE);
assertThat(knowledge.lookup(input, BUILD).path("documents")).isEmpty();
((ObjectNode) input.path("facts")).put("module_mm", -2);
assertThat(knowledge.lookup(input, BUILD).path("conflicts").toString()).contains("module_mm");
((ObjectNode) input.path("facts")).put("root_transition", "x".repeat(81));
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", input))
.isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
}
@Test void rejectsMalformedConflictingAndIncompleteEligibilityRules() throws Exception {
JsonNode policy = HistoricalCadAiKnowledge.policy(json);
ObjectNode valid = (ObjectNode) policy.path("documents").get(1).path("conditions");
CadAiKnowledge.validateConditions("involute-spur-gear", valid);
for (String field : List.of("teeth", "root_transition")) {
ObjectNode invalid = valid.deepCopy(); invalid.remove(field);
assertThatThrownBy(() -> CadAiKnowledge.validateConditions("involute-spur-gear", invalid)).isInstanceOf(IOException.class);
}
ObjectNode invalid = valid.deepCopy();
((ObjectNode) invalid.path("teeth")).put("min", 99);
assertThatThrownBy(() -> CadAiKnowledge.validateConditions("involute-spur-gear", invalid)).isInstanceOf(IOException.class);
ObjectNode badType = valid.deepCopy();
((ObjectNode) badType.path("profile_shift")).put("equals", "zero");
assertThatThrownBy(() -> CadAiKnowledge.validateConditions("involute-spur-gear", badType)).isInstanceOf(IOException.class);
ObjectNode infinite = valid.deepCopy();
((ObjectNode) infinite.path("module_mm")).put("min_exclusive", Double.POSITIVE_INFINITY);
assertThatThrownBy(() -> CadAiKnowledge.validateConditions("involute-spur-gear", infinite)).isInstanceOf(IOException.class);
}
@Test void factsAllowMissingFieldsAndNullButNeverInventRequiredRecipeConditions() throws Exception {
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
ObjectNode request = request("外啮合渐开线直齿圆柱齿轮,基圆内齿根段允许径向直线连接到齿根圆,标注简化齿根");
ObjectNode facts = (ObjectNode) request.path("facts");
facts.remove("root_transition");
tools.validateCall("knowledge_lookup", request);
assertThat(knowledge.lookup(request, BUILD).path("missing").toString()).contains("root_transition");
facts.putNull("root_transition");
tools.validateCall("knowledge_lookup", request);
JsonNode result = knowledge.lookup(request, BUILD);
assertThat(result.path("status").asText()).isEqualTo("needs_conditions");
assertThat(result.path("documents")).isEmpty();
assertThat(result.path("missing").toString()).contains("root_transition");
assertThat(result.path("reason").asText()).contains("正文未返回", "不能据本结果声称已读取或适用");
facts.putNull("module_mm");
tools.validateCall("knowledge_lookup", request);
assertThat(knowledge.lookup(request, BUILD).path("missing").toString()).contains("module_mm");
facts.put("module_mm", 2).put("root_transition", "radial-simplified");
tools.validateCall("knowledge_lookup", request);
assertThat(knowledge.lookup(request, BUILD).path("status").asText()).isEqualTo("matched");
request.remove("facts");
tools.validateCall("knowledge_lookup", request);
assertThat(knowledge.lookup(request, BUILD).path("documents")).isEmpty();
}
@Test void repeatedGeneralNounForSameSpecifiedPartDoesNotRequireAnotherLookup() {
String actualQuery = "制作外啮合渐开线直齿圆柱齿轮:模数2.5,齿数24,压力角20°,零变位、零侧隙,齿顶高系数1,顶隙系数0.25,齿宽12,中心孔直径16,轴线Z,齿形工作段必须为渐开线,允许误差不超过0.03并明确标注;基圆内齿根段允许径向直线连接到齿根圆;需要等厚圆盘状齿轮,不要轮毂、键槽、减重孔。";
ObjectNode input = request(actualQuery).put("type_id", "involute-spur-gear");
((ObjectNode) input.path("facts")).put("module_mm", 2.5);
assertThat(knowledge.lookup(input, BUILD).path("status").asText()).isEqualTo("matched");
input.remove("type_id");
assertThat(knowledge.lookup(input, BUILD).path("status").asText()).isEqualTo("matched");
for (String query : List.of("做直齿轮,另一个未明确的gear", "做spur gear and another gear", "做直齿轮和一个未明确的齿轮", "做直齿轮和斜齿轮", "做直齿轮和齿轮")) {
assertThat(knowledge.lookup(request(query).put("type_id", "involute-spur-gear"), BUILD).path("status").asText())
.as(query).isEqualTo("ambiguous");
}
}
@Test void approvedPublicationRequiresBenefitVerdictAndAllEvidenceReferences() throws Exception {
ObjectNode recipe = json.createObjectNode().put("status", "experimental");
CadAiKnowledge.validatePublication(recipe);
recipe.put("status", "approved");
assertThatThrownBy(() -> CadAiKnowledge.validatePublication(recipe)).isInstanceOf(IOException.class);
ObjectNode evidence = recipe.putObject("evidence").put("verdict", "benefit_observed")
.put("engine_replay", "reports/replay").put("ab_comparison", "reports/ab");
evidence.putArray("parameter_transfer").add("reports/transfer20").add("reports/transfer32");
CadAiKnowledge.validatePublication(recipe);
for (String field : List.of("verdict", "engine_replay", "ab_comparison", "parameter_transfer")) {
ObjectNode invalid = recipe.deepCopy(); ((ObjectNode) invalid.path("evidence")).remove(field);
assertThatThrownBy(() -> CadAiKnowledge.validatePublication(invalid)).isInstanceOf(IOException.class);
}
evidence.put("verdict", "partial_benefit_completion_unstable");
assertThatThrownBy(() -> CadAiKnowledge.validatePublication(recipe)).isInstanceOf(IOException.class);
}
@Test void typeIdEnumComesFromCanonicalCatalogAndRejectsInventedIds() throws Exception {
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
JsonNode definition = tools.definitions(true).stream().filter(tool -> "knowledge_lookup".equals(tool.name())).findFirst().orElseThrow().parameters();
List<String> enumerated = new ArrayList<>();
for (JsonNode id : definition.path("properties").path("type_id").path("enum")) enumerated.add(id.asText());
JsonNode catalog = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/generation/catalog.json"));
assertThat(enumerated).containsExactlyElementsOf(CadAiKnowledge.validateCatalog(catalog).keySet().stream().sorted().toList());
ObjectNode invented = request("外啮合渐开线直齿圆柱齿轮").put("type_id", "spur_external_involute_gear");
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", invented)).isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
JsonNode recovery = knowledge.lookup(invented, BUILD);
assertThat(recovery.path("status").asText()).isEqualTo("ambiguous");
assertThat(recovery.path("candidates").toString()).contains("involute-spur-gear");
assertThat(recovery.path("documents")).isEmpty();
invented.remove("type_id");
tools.validateCall("knowledge_lookup", invented);
assertThat(knowledge.lookup(invented, BUILD).path("status").asText()).isEqualTo("matched");
}
@Test void gearFactsComeFromTheCatalogAndOnlyRecipeConditionsAreRequired() throws Exception {
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
ObjectNode helical = json.createObjectNode().put("query", "外啮合右旋斜齿圆柱齿轮").put("type_id", "helical-cylindrical-gear");
helical.putObject("facts").put("normal_module_mm", 2).put("teeth", 24)
.put("normal_pressure_angle_deg", 20).put("helix_angle_deg", 20).put("helix_hand", "right");
tools.validateCall("knowledge_lookup", helical);
assertThat(knowledge.lookup(helical, EXPANSION_BUILD).path("status").asText()).isEqualTo("needs_conditions");
ObjectNode spur = request("外渐开线直齿圆柱齿轮");
((ObjectNode) spur.path("facts")).remove("root_transition");
tools.validateCall("knowledge_lookup", spur);
assertThat(knowledge.lookup(spur, BUILD).path("missing").toString()).contains("root_transition");
ObjectNode unknown = helical.deepCopy();
((ObjectNode) unknown.path("facts")).put("private_unknown_field", 1);
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", unknown))
.isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
((ObjectNode) helical.path("facts")).put("helix_hand", 42);
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", helical))
.isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
}
@Test void validatesGearSpecificNumericAndTextConditionsFromCatalogDefinitions() throws Exception {
ObjectNode conditions = json.createObjectNode();
conditions.putObject("normal_module_mm").put("min_exclusive", 0);
conditions.putObject("helix_angle_deg").put("min_exclusive", 0).put("max", 40);
conditions.putObject("helix_hand").put("equals", "right");
CadAiKnowledge.validateConditions("helical-cylindrical-gear", conditions);
((ObjectNode) conditions.path("helix_hand")).put("equals", 42);
assertThatThrownBy(() -> CadAiKnowledge.validateConditions("helical-cylindrical-gear", conditions)).isInstanceOf(IOException.class);
}
@Test void absoluteAngleConditionsAllowSignedHelicesAndRejectConflictingBounds() throws Exception {
ObjectNode conditions = json.createObjectNode();
conditions.putObject("helix_angle_deg").put("abs_min", 5).put("abs_max", 25);
CadAiKnowledge.validateConditions("helical-cylindrical-gear", conditions);
ObjectNode facts = json.createObjectNode();
for (double angle : List.of(-25.0, -20.0, -5.0, 5.0, 20.0, 25.0)) {
facts.put("helix_angle_deg", angle);
assertThat(conditionConflicts("helical-cylindrical-gear", conditions, facts)).as("angle=%s", angle).isEmpty();
}
for (double angle : List.of(-25.01, -4.99, 0.0, 4.99, 25.01, Double.POSITIVE_INFINITY, Double.NaN)) {
facts.put("helix_angle_deg", angle);
assertThat(conditionConflicts("helical-cylindrical-gear", conditions, facts)).as("angle=%s", angle)
.containsExactly("helix_angle_deg");
}
for (String invalidRule : List.of(
"{\"abs_min\":-1}", "{\"abs_max\":-1}", "{\"abs_min\":26,\"abs_max\":25}",
"{\"abs_min\":5,\"abs_max\":25,\"equals\":0}",
"{\"abs_min\":5,\"abs_max\":25,\"min\":26}",
"{\"abs_min\":5,\"abs_max\":25,\"max\":-26}")) {
conditions.set("helix_angle_deg", json.readTree(invalidRule));
assertThatThrownBy(() -> CadAiKnowledge.validateConditions("helical-cylindrical-gear", conditions))
.as(invalidRule).isInstanceOf(IOException.class);
}
}
@Test void internalGearChecksRimAndInvoluteDomainWithoutApplyingExternalRootRule() throws Exception {
ObjectNode conditions = (ObjectNode) json.readTree("""
{"module_mm":{"min_exclusive":0},"teeth":{"min":1},
"pressure_angle_deg":{"equals":20},"outer_radius_mm":{"min_exclusive":0}}
""");
ObjectNode facts = json.createObjectNode().put("module_mm", 2).put("teeth", 40)
.put("pressure_angle_deg", 20).put("outer_radius_mm", 50);
assertThat(conditionConflicts("internal-spur-gear", conditions, facts)).isEmpty();
facts.put("outer_radius_mm", 42.5);
assertThat(conditionConflicts("internal-spur-gear", conditions, facts))
.containsExactly("internal_radii_must_satisfy_outer_gt_root_gt_tip_gt_base_gt_zero");
facts.put("outer_radius_mm", 50).put("teeth", 33);
assertThat(conditionConflicts("internal-spur-gear", conditions, facts))
.containsExactly("internal_radii_must_satisfy_outer_gt_root_gt_tip_gt_base_gt_zero");
facts.put("teeth", 34);
assertThat(conditionConflicts("internal-spur-gear", conditions, facts)).isEmpty();
facts.put("module_mm", Double.MAX_VALUE);
assertThat(conditionConflicts("internal-spur-gear", conditions, facts))
.containsExactly("internal_radii_must_satisfy_outer_gt_root_gt_tip_gt_base_gt_zero");
}
@Test void helicalGearChecksNormalToTransverseRadiiForBothHands() throws Exception {
ObjectNode conditions = (ObjectNode) json.readTree("""
{"normal_module_mm":{"min_exclusive":0},"teeth":{"min":1},
"normal_pressure_angle_deg":{"equals":20},"helix_angle_deg":{"abs_min":5,"abs_max":25}}
""");
ObjectNode facts = json.createObjectNode().put("normal_module_mm", 2).put("teeth", 24)
.put("normal_pressure_angle_deg", 20).put("helix_angle_deg", 20);
assertThat(conditionConflicts("helical-cylindrical-gear", conditions, facts)).isEmpty();
facts.put("helix_angle_deg", -20);
assertThat(conditionConflicts("helical-cylindrical-gear", conditions, facts)).isEmpty();
facts.put("teeth", 100);
assertThat(conditionConflicts("helical-cylindrical-gear", conditions, facts))
.containsExactly("helical_radii_must_satisfy_zero_lt_root_lt_base_lt_tip");
facts.put("teeth", 24).put("normal_module_mm", Double.MAX_VALUE);
assertThat(conditionConflicts("helical-cylindrical-gear", conditions, facts))
.containsExactly("helical_radii_must_satisfy_zero_lt_root_lt_base_lt_tip");
}
@Test void derivedGearChecksRequireDeclaredConditionsAndDoNotReplaceMissingFacts() throws Exception {
ObjectNode conditions = (ObjectNode) json.readTree("""
{"module_mm":{"min_exclusive":0},"teeth":{"min":1},
"pressure_angle_deg":{"equals":20},"outer_radius_mm":{"min_exclusive":0}}
""");
ObjectNode facts = json.createObjectNode().put("module_mm", 2).put("teeth", 40)
.put("pressure_angle_deg", 20).put("outer_radius_mm", 1);
assertThat(conditionConflicts("straight-rack", conditions, facts)).isEmpty();
ObjectNode withoutRim = conditions.deepCopy();
withoutRim.remove("outer_radius_mm");
assertThat(conditionConflicts("internal-spur-gear", withoutRim, facts)).isEmpty();
facts.remove("outer_radius_mm");
List<String> missing = new ArrayList<>();
List<String> conflicts = new ArrayList<>();
CadAiKnowledge.checkConditions("internal-spur-gear", conditions, facts, missing, conflicts);
assertThat(missing).containsExactly("outer_radius_mm");
assertThat(conflicts).isEmpty();
assertThat(facts.has("outer_radius_mm")).isFalse();
}
@Test void complexRecipeDomainsRejectInvalidScaleCoreAndThroatBeforeReturningText() throws Exception {
JsonNode suite = json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v2.json"));
Map<String, ObjectNode> fixtures = new HashMap<>();
for (JsonNode item : suite.path("cases")) if (item.path("group").asText().equals("eligible"))
fixtures.put(item.path("type_id").asText(), (ObjectNode) item.path("facts").deepCopy());
for (String type : List.of("straight-bevel-gear", "spiral-bevel-gear")) {
ObjectNode facts = fixtures.get(type).deepCopy().put("axial_height_mm", 25);
assertRejectedDomain(type, facts, "bevel_end_scale_must_be_between_045_and_09");
assertRejectedDomain(type, fixtures.get(type).deepCopy().put("module_mm", Double.MAX_VALUE),
"bevel_end_scale_must_be_between_045_and_09");
}
assertRejectedDomain("worm", fixtures.get("worm").deepCopy().put("pitch_diameter_mm", 4),
"worm_core_length_and_turns_outside_recipe_domain");
assertRejectedDomain("worm", fixtures.get("worm").deepCopy().put("axial_length_mm", 1),
"worm_core_length_and_turns_outside_recipe_domain");
assertRejectedDomain("worm", fixtures.get("worm").deepCopy().put("axial_length_mm", 2000),
"worm_core_length_and_turns_outside_recipe_domain");
assertRejectedDomain("worm", fixtures.get("worm").deepCopy().put("axial_module_mm", Double.MAX_VALUE),
"worm_core_length_and_turns_outside_recipe_domain");
assertRejectedDomain("worm-wheel", fixtures.get("worm-wheel").deepCopy().put("face_width_mm", 20),
"worm_wheel_throat_outside_recipe_domain");
assertRejectedDomain("worm-wheel", fixtures.get("worm-wheel").deepCopy().put("face_width_mm", 10),
"worm_wheel_throat_outside_recipe_domain");
assertRejectedDomain("worm-wheel", fixtures.get("worm-wheel").deepCopy().put("module_mm", Double.MAX_VALUE),
"worm_wheel_throat_outside_recipe_domain");
}
@Test void complexDerivedDomainsNeedDeclaredDependenciesAndDoNotOverrideMissingConditions() throws Exception {
ObjectNode bevel = (ObjectNode) json.readTree("""
{"module_mm":{"min_exclusive":0},"teeth":{"min":18},"cone_angle_deg":{"equals":45},
"axial_height_mm":{"min_exclusive":0},"geometry_representation":{"equals":"homothetic-frontal-involute-bevel-v1"}}
""");
ObjectNode worm = (ObjectNode) json.readTree("""
{"axial_module_mm":{"min_exclusive":0},"pitch_diameter_mm":{"min_exclusive":0},
"worm_starts":{"min":1},"axial_length_mm":{"min_exclusive":0}}
""");
ObjectNode wheel = (ObjectNode) json.readTree("""
{"module_mm":{"min_exclusive":0},"teeth":{"min":18},"pressure_angle_deg":{"equals":20},
"pitch_diameter_mm":{"min_exclusive":0},"face_width_mm":{"min_exclusive":0},
"geometry_representation":{"equals":"illustrative-helical-involute-with-toroidal-throat-v1"}}
""");
Map<String, ObjectNode> conditions = Map.of("straight-bevel-gear", bevel, "worm", worm, "worm-wheel", wheel);
Map<String, ObjectNode> facts = Map.of(
"straight-bevel-gear", json.createObjectNode().put("module_mm",2).put("teeth",24).put("cone_angle_deg",45)
.put("axial_height_mm",25).put("geometry_representation","homothetic-frontal-involute-bevel-v1"),
"worm", json.createObjectNode().put("axial_module_mm",2).put("pitch_diameter_mm",4).put("worm_starts",1).put("axial_length_mm",30),
"worm-wheel", json.createObjectNode().put("module_mm",2).put("teeth",32).put("pressure_angle_deg",20)
.put("pitch_diameter_mm",20).put("face_width_mm",20).put("geometry_representation","illustrative-helical-involute-with-toroidal-throat-v1"));
Map<String, String> dependency = Map.of("straight-bevel-gear","axial_height_mm", "worm","axial_length_mm", "worm-wheel","face_width_mm");
for (String type : conditions.keySet()) {
ObjectNode incompletePolicy = conditions.get(type).deepCopy();
incompletePolicy.remove(dependency.get(type));
assertThat(conditionConflicts(type, incompletePolicy, facts.get(type))).as(type).isEmpty();
ObjectNode missingFacts = facts.get(type).deepCopy();
missingFacts.remove(dependency.get(type));
List<String> missing = new ArrayList<>();
List<String> conflicts = new ArrayList<>();
CadAiKnowledge.checkConditions(type, conditions.get(type), missingFacts, missing, conflicts);
assertThat(missing).as(type).containsExactly(dependency.get(type));
assertThat(conflicts).as(type).isEmpty();
assertThat(conditionConflicts("straight-rack", conditions.get(type), facts.get(type))).as(type).isEmpty();
}
}
private void assertRejectedDomain(String type, ObjectNode facts, String conflict) {
String query = Map.of("straight-bevel-gear", "直齿锥齿轮", "spiral-bevel-gear", "螺旋锥齿轮", "worm", "蜗杆", "worm-wheel", "蜗轮").get(type);
ObjectNode input = json.createObjectNode().put("query", query).put("type_id", type);
input.set("facts", facts);
JsonNode result = knowledge.lookup(input, EXPANSION_BUILD);
assertThat(result.path("status").asText()).as(type).isEqualTo("uncovered");
assertThat(result.path("documents")).isEmpty();
assertThat(result.path("conflicts").toString()).contains(conflict);
}
private List<String> conditionConflicts(String type, JsonNode conditions, JsonNode facts) {
List<String> missing = new ArrayList<>();
List<String> conflicts = new ArrayList<>();
CadAiKnowledge.checkConditions(type, conditions, facts, missing, conflicts);
assertThat(missing).isEmpty();
return conflicts;
}
@Test void rejectsMalformedCanonicalPropertyDefinitions() throws Exception {
ObjectNode catalog = (ObjectNode) json.readTree(getClass().getResourceAsStream("/cad/ai/knowledge/generation/catalog.json"));
CadAiKnowledge.validateFactDefinitions(catalog);
ObjectNode definitions = (ObjectNode) catalog.path("fact_definitions");
((ObjectNode) definitions.path("normal_module_mm")).put("type", "array");
assertThatThrownBy(() -> CadAiKnowledge.validateFactDefinitions(catalog)).isInstanceOf(IOException.class);
((ObjectNode) definitions.path("normal_module_mm")).put("type", "number").put("unit", "unknown");
assertThatThrownBy(() -> CadAiKnowledge.validateFactDefinitions(catalog)).isInstanceOf(IOException.class);
}
@Test void schemaAllowsNoPathsAndNeverBatchesLookup() throws Exception {
CadAiTools tools = HistoricalCadAiKnowledge.tools(json);
tools.validateCall("knowledge_lookup", request("直齿轮"));
assertThatThrownBy(() -> tools.validateCall("knowledge_lookup", request("直齿轮").put("file", "/private")))
.isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
ObjectNode batch = json.createObjectNode();
batch.putArray("commands").addObject().put("command", "knowledge_lookup").set("params", request("直齿轮"));
assertThatThrownBy(() -> tools.validateCall("batch", batch)).isInstanceOf(com.linkerbot.vibemake.common.BusinessException.class);
assertThat(tools.definitions(false)).noneMatch(tool -> "knowledge_lookup".equals(tool.name()));
}
}
@@ -1,207 +0,0 @@
package com.linkerbot.vibemake.service.cad.ai;
import static org.assertj.core.api.Assertions.*;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.linkerbot.vibemake.service.config.CadAiProperties;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.*;
import org.junit.jupiter.api.Test;
/** Live policy tests; historical fixtures run separately against their frozen policy. */
class CadAiKnowledgeUtilityTest {
private static final String BUILD = "f3d62ce93f72db42f311a46e";
private final ObjectMapper json = new ObjectMapper();
private JsonNode resource(String path) throws IOException {
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/" + path)) {
if (input == null) throw new IOException("Missing resource: " + path);
return json.readTree(input);
}
}
private CadAiKnowledge live(String mode) throws IOException {
CadAiProperties properties = new CadAiProperties();
properties.setKnowledgeMode(mode);
return new CadAiKnowledge(json, properties);
}
private ObjectNode request(String query) {
return json.createObjectNode().put("query", query);
}
private ObjectNode completeRequest(JsonNode document) throws IOException {
String id = document.path("doc_id").asText();
if ("housing-y-bore".equals(id)) return request("创建带筋轴承座,用XZ草图造筋");
for (String suite : List.of("gear-routing-v8.json", "sample-parts-routing-v1.json")) {
for (JsonNode item : resource("evals/" + suite).path("cases")) {
if (!id.equals(item.path("doc_id").asText()) || !"matched".equals(item.path("status").asText()) || !item.has("facts")) continue;
ObjectNode input = request(item.path("query").asText()).put("type_id", document.path("type_id").asText());
input.set("facts", item.path("facts").deepCopy());
return input;
}
}
throw new IOException("No existing matched fixture for retained recipe: " + id);
}
@Test void preservesExistingGearRecipesAndOnlyPrunesBasicSamples() throws Exception {
JsonNode policy = resource("generation/policy.json");
Map<String, JsonNode> previous = new HashMap<>();
for (JsonNode document : HistoricalCadAiKnowledge.policy(json).path("documents"))
previous.put(document.path("doc_id").asText(), document);
int active = 0;
int retired = 0;
int recipes = 0;
int hints = 0;
int currentCharacters = 0;
int priorCharacters = 0;
for (JsonNode document : policy.path("documents")) {
if ("retired".equals(document.path("status").asText())) { retired++; continue; }
active++;
assertThat(document.path("status").asText()).isEqualTo("experimental");
if ("recipe".equals(document.path("content_role").asText())) {
recipes++;
JsonNode original = previous.get(document.path("doc_id").asText());
for (String field : List.of("path", "version", "sha256", "type_id", "conditions", "compatible_builds", "evidence"))
assertThat(document.path(field)).as(document.path("doc_id").asText() + " preserves " + field).isEqualTo(original.path(field));
} else {
hints++;
assertThat(document.path("doc_id").asText()).isEqualTo("housing-y-bore");
}
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/" + document.path("path").asText())) {
byte[] bytes = input.readAllBytes();
CadAiKnowledge.verifyHash(bytes, document.path("sha256").asText());
currentCharacters += new String(bytes, StandardCharsets.UTF_8).length();
}
if ("risk_hint".equals(document.path("content_role").asText()))
assertThat(document.path("evidence").path("current_text_model_effect").asText()).startsWith("not_tested");
}
for (JsonNode document : HistoricalCadAiKnowledge.policy(json).path("documents")) {
if ("retired".equals(document.path("status").asText())) continue;
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/" + document.path("path").asText())) {
priorCharacters += new String(input.readAllBytes(), StandardCharsets.UTF_8).length();
}
}
assertThat(active).isEqualTo(16);
assertThat(retired).isEqualTo(5);
assertThat(recipes).isEqualTo(15);
assertThat(hints).isEqualTo(1);
assertThat(currentCharacters).isLessThan(priorCharacters).isGreaterThan(priorCharacters / 2);
}
@Test void withdrawnTypesReturnNoBodyAndDoNotRequestConditions() throws Exception {
CadAiKnowledge knowledge = live("pilot");
Set<String> withdrawn = new HashSet<>();
for (JsonNode document : resource("generation/policy.json").path("documents"))
if ("retired".equals(document.path("status").asText()) && document.has("type_id")) withdrawn.add(document.path("type_id").asText());
Set<String> covered = new HashSet<>();
for (String suite : List.of("gear-routing-v8.json", "sample-parts-routing-v1.json")) {
for (JsonNode item : resource("evals/" + suite).path("cases")) {
String type = item.path("type_id").asText();
if (!"matched".equals(item.path("status").asText()) || !withdrawn.contains(type)) continue;
ObjectNode input = request(item.path("query").asText()).put("type_id", type);
input.set("facts", item.path("facts"));
JsonNode result = knowledge.lookup(input, BUILD);
assertThat(result.path("status").asText()).as(item.path("id").asText()).isEqualTo("uncovered");
assertThat(result.path("documents")).isEmpty();
assertThat(result.path("missing")).isEmpty();
covered.add(type);
}
}
assertThat(covered).containsExactlyInAnyOrderElementsOf(withdrawn);
}
@Test void housingHintOnlyActivatesForCurrentXzRibOperationWithoutDimensionQuestions() throws Exception {
CadAiKnowledge knowledge = live("pilot");
for (String query : List.of("创建带筋轴承座", "创建带筋轴承座,用XY草图造筋", "创建带筋轴承座,XZ草图开孔", "创建带筋轴承座,用XYZ草图造筋")) {
JsonNode result = knowledge.lookup(request(query), BUILD);
assertThat(result.path("status").asText()).as(query).isEqualTo("not_applicable");
assertThat(result.path("documents")).isEmpty();
assertThat(result.path("missing")).isEmpty();
}
for (String query : List.of("创建带筋轴承座,用XZ草图造筋", "create ribbed bearing housing with ribs sketched on XZ")) {
JsonNode result = knowledge.lookup(request(query), BUILD);
assertThat(result.path("status").asText()).as(query).isEqualTo("matched");
assertThat(result.path("documents").get(0).path("id").asText()).isEqualTo("housing-y-bore");
assertThat(result.path("documents").get(0).path("content_role").asText()).isEqualTo("risk_hint");
assertThat(result.path("missing")).isEmpty();
}
}
@Test void activationDoesNotOverrideWrongTypesNegationOrReferenceScope() throws Exception {
CadAiKnowledge knowledge = live("pilot");
for (ObjectNode input : List.of(
request("创建安装板,用XZ草图造筋").put("type_id", "ribbed-bearing-housing"),
request("创建带筋轴承座,不用XZ草图造筋"),
request("不创建XZ带筋轴承座,只创建安装板"),
request("参考XZ带筋轴承座,当前待建部件是台阶轴"))) {
JsonNode result = knowledge.lookup(input, BUILD);
assertThat(result.path("status").asText()).as(input.toString()).isNotEqualTo("matched");
assertThat(result.path("documents")).isEmpty();
}
}
@Test void activeDocumentsExposeTheirExactNewVersionHashAndRole() throws Exception {
CadAiKnowledge knowledge = live("pilot");
CadAiTools tools = new CadAiTools(json);
for (JsonNode document : resource("generation/policy.json").path("documents")) {
if ("retired".equals(document.path("status").asText())) continue;
ObjectNode input = completeRequest(document);
tools.validateCall("knowledge_lookup", input);
ObjectNode before = input.deepCopy();
JsonNode result = knowledge.lookup(input, BUILD);
assertThat(result.path("status").asText()).as(document.path("doc_id").asText()).isEqualTo("matched");
JsonNode returned = result.path("documents").get(0);
for (String key : List.of("version", "sha256", "status", "content_role"))
assertThat(returned.path(key)).isEqualTo(document.path(key));
CadAiKnowledge.verifyHash(returned.path("text").asText().getBytes(StandardCharsets.UTF_8), document.path("sha256").asText());
assertThat(input).isEqualTo(before);
for (String build : Arrays.asList(null, "", "0".repeat(24), "independent-frontend-release", "745a1240964583102b5bdc4f")) {
JsonNode independent = knowledge.lookup(input, build);
assertThat(independent.path("status").asText()).isEqualTo("matched");
assertThat(independent.path("documents")).isEqualTo(result.path("documents"));
}
assertThat(live("enabled").lookup(input, BUILD).path("documents")).isEmpty();
assertThat(live("off").lookup(input, BUILD).path("status").asText()).isEqualTo("disabled");
}
}
@Test void schemaDoesNotAdvertiseWithdrawnRepresentationsAndGenericSkillsStayIdentical() throws Exception {
JsonNode schema = new CadAiTools(json).definitions(true).stream().filter(tool -> "knowledge_lookup".equals(tool.name()))
.findFirst().orElseThrow().parameters();
List<String> representations = new ArrayList<>();
for (JsonNode value : schema.path("properties").path("facts").path("properties").path("geometry_representation").path("enum"))
if (value.isTextual()) representations.add(value.asText());
Set<String> expected = new HashSet<>();
Set<String> basic = Set.of("plate-through-holes", "shaft-cumulative-segments", "hex-bolt-simplified", "housing-y-bore", "enclosure-shared-interface");
for (JsonNode document : HistoricalCadAiKnowledge.policy(json).path("documents")) {
if ("retired".equals(document.path("status").asText()) || basic.contains(document.path("doc_id").asText())) continue;
JsonNode value = document.path("conditions").path("geometry_representation").path("equals");
if (value.isTextual()) expected.add(value.asText());
}
assertThat(representations).containsExactlyInAnyOrderElementsOf(expected);
assertThat(representations).doesNotContain("ribbed-housing-y-bore-z-mount-v1", "hex-bolt-simplified-thread-v1");
try (InputStream input = getClass().getResourceAsStream("/cad/ai/skills.json")) {
CadAiKnowledge.verifyHash(input.readAllBytes(), "026284eff26c8b4be1f7864219921a54828338973317c291f7e862b1cc452ef7");
}
}
@Test void rejectsMalformedActivationsAndUnguardedEmptyRecipes() throws Exception {
JsonNode original = resource("generation/policy.json");
for (String badActivation : List.of("{}", "{\"all_terms\":[],\"any_terms\":[\"筋\"]}",
"{\"all_terms\":[\"XZ\"],\"any_terms\":[\"筋\"]}", "{\"all_terms\":[\"xz\"],\"any_terms\":[\"\"]}")) {
JsonNode policy = original.deepCopy();
ObjectNode housing = (ObjectNode) policy.path("documents").get(17);
assertThat(housing.path("doc_id").asText()).isEqualTo("housing-y-bore");
housing.set("activation", json.readTree(badActivation));
assertThatThrownBy(() -> new CadAiKnowledge(json, new CadAiProperties(), policy)).isInstanceOf(IOException.class);
}
JsonNode policy = original.deepCopy();
((ObjectNode) policy.path("documents").get(17)).remove("activation");
assertThatThrownBy(() -> new CadAiKnowledge(json, new CadAiProperties(), policy)).isInstanceOf(IOException.class);
}
}
@@ -1,164 +0,0 @@
package com.linkerbot.vibemake.service.cad.ai;
import static org.assertj.core.api.Assertions.*;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.linkerbot.vibemake.service.config.CadAiProperties;
import java.io.InputStream;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.HexFormat;
import java.util.List;
import org.junit.jupiter.api.Test;
class CadAiSampleKnowledgeTest {
private final ObjectMapper json = new ObjectMapper();
@Test void sevenNewTypesRespectScopeFactsReferencesAndPublicationWithoutChangingGearHistory() throws Exception {
JsonNode suite;
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/sample-parts-routing-v1.json")) {
suite = json.readTree(input);
}
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/gear-routing-v8.json")) {
assertThat(HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(input.readAllBytes())))
.isEqualTo(suite.path("preserved_gear_v8_sha256").asText());
}
List<String> failures = new ArrayList<>();
for (JsonNode item : suite.path("cases")) {
CadAiProperties properties = new CadAiProperties();
properties.setKnowledgeMode(item.path("mode").asText("pilot"));
CadAiKnowledge knowledge = HistoricalCadAiKnowledge.knowledge(json, properties);
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
input.set("facts", item.path("facts").deepCopy());
if (item.has("selected_type")) input.put("type_id", item.path("selected_type").asText());
ObjectNode before = input.deepCopy();
JsonNode result = knowledge.lookup(input, item.path("build").asText(suite.path("engine_build").asText()));
String id = item.path("id").asText();
String expectedStatus = HistoricalCadAiKnowledge.runtimeStatus(item);
if (!result.path("status").asText().equals(expectedStatus))
failures.add(id + ": expected " + expectedStatus + " but " + result);
if ("matched".equals(expectedStatus) && "matched".equals(result.path("status").asText())) {
assertThat(result.path("type_id").asText()).as(id).isEqualTo(item.path("type_id").asText());
assertThat(result.path("documents")).as(id).hasSize(1);
if (item.has("doc_id")) assertThat(result.path("documents").get(0).path("id").asText()).as(id).isEqualTo(item.path("doc_id").asText());
assertThat(result.path("documents").get(0).path("text").asText()).as(id).isNotBlank();
} else if (!"matched".equals(result.path("status").asText())) {
assertThat(result.path("documents")).as(id).isEmpty();
}
assertThat(input).as(id + " preserves supplied facts").isEqualTo(before);
}
assertThat(failures).isEmpty();
}
@Test void propertyDictionaryAndRepresentationChoicesStayCanonical() throws Exception {
JsonNode schema = HistoricalCadAiKnowledge.tools(json).definitions(true).stream()
.filter(tool -> "knowledge_lookup".equals(tool.name())).findFirst().orElseThrow()
.parameters().path("properties").path("facts");
assertThat(schema.path("properties").has("central_gap_mm")).isTrue();
assertThat(schema.path("properties").has("hole_count")).isTrue();
assertThat(schema.path("properties").size()).isLessThanOrEqualTo(64);
assertThat(schema.path("properties").path("geometry_representation").toString())
.contains("herringbone-continuous-midplane-v1", "double-helical-root-core-gap-v1", "hex-bolt-simplified-thread-v1");
}
@Test void absentFeaturesAndAdditionalCurrentPartScopesStayDistinct() throws Exception {
JsonNode suite;
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/sample-parts-routing-v2.json")) {
suite = json.readTree(input);
}
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/sample-parts-routing-v1.json")) {
assertThat(HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(input.readAllBytes())))
.isEqualTo(suite.path("preserved_v1_sha256").asText());
}
JsonNode additional;
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/sample-parts-routing-v4.json")) {
additional = json.readTree(input);
}
CadAiProperties properties = new CadAiProperties();
properties.setKnowledgeMode("pilot");
CadAiKnowledge knowledge = HistoricalCadAiKnowledge.knowledge(json, properties);
for (JsonNode fixture : List.of(suite, additional)) for (JsonNode item : fixture.path("cases")) {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
if (item.has("selected_type")) input.put("type_id", item.path("selected_type").asText());
input.set("facts", item.path("facts").deepCopy());
ObjectNode before = input.deepCopy();
JsonNode result = knowledge.lookup(input, suite.path("engine_build").asText());
assertThat(result.path("status").asText()).as(item.path("id").asText())
.isEqualTo(item.path("status").asText());
if ("matched".equals(item.path("status").asText())) {
assertThat(result.path("documents")).hasSize(1);
assertThat(result.path("documents").get(0).path("id").asText()).isEqualTo(item.path("doc_id").asText());
} else assertThat(result.path("documents")).isEmpty();
assertThat(input).isEqualTo(before);
}
}
@Test void selectedPartRecognizesQualifiedPairNamesWithoutAbsorbingOtherTargets() throws Exception {
JsonNode suite;
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/sample-parts-routing-v3.json")) {
suite = json.readTree(input);
}
CadAiProperties properties = new CadAiProperties();
properties.setKnowledgeMode("pilot");
CadAiKnowledge knowledge = HistoricalCadAiKnowledge.knowledge(json, properties);
List<String> failures = new ArrayList<>();
for (JsonNode item : suite.path("cases")) {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
if (item.has("selected_type")) input.put("type_id", item.path("selected_type").asText());
input.set("facts", item.path("facts").deepCopy());
ObjectNode before = input.deepCopy();
JsonNode result = knowledge.lookup(input, suite.path("engine_build").asText());
String id = item.path("id").asText();
if (!result.path("status").asText().equals(item.path("status").asText())) {
failures.add(id + ": expected " + item.path("status").asText() + " but " + result);
continue;
}
if ("matched".equals(item.path("status").asText())) {
assertThat(result.path("type_id").asText()).as(id).isEqualTo(item.path("type_id").asText());
assertThat(result.path("documents")).as(id).hasSize(1);
assertThat(result.path("documents").get(0).path("id").asText()).as(id).isEqualTo(item.path("doc_id").asText());
} else assertThat(result.path("documents")).as(id).isEmpty();
for (String field : List.of("missing", "conflicts")) {
if (!item.has(field)) continue;
List<String> expected = new ArrayList<>();
for (JsonNode value : item.path(field)) expected.add(value.asText());
List<String> actual = new ArrayList<>();
for (JsonNode value : result.path(field)) actual.add(value.asText());
assertThat(actual).as(id + " " + field).containsExactlyInAnyOrderElementsOf(expected);
}
assertThat(input).as(id + " preserves supplied facts").isEqualTo(before);
}
assertThat(failures).isEmpty();
}
@Test void currentPartReferencesAndInterfaceDimensionsDoNotBecomeAdditionalTargets() throws Exception {
JsonNode suite;
try (InputStream input = getClass().getResourceAsStream("/cad/ai/knowledge/evals/sample-parts-routing-v5.json")) {
suite = json.readTree(input);
}
CadAiProperties properties = new CadAiProperties();
properties.setKnowledgeMode("pilot");
CadAiKnowledge knowledge = HistoricalCadAiKnowledge.knowledge(json, properties);
List<String> failures = new ArrayList<>();
for (JsonNode item : suite.path("cases")) {
ObjectNode input = json.createObjectNode().put("query", item.path("query").asText());
if (item.has("selected_type")) input.put("type_id", item.path("selected_type").asText());
input.set("facts", item.path("facts").deepCopy());
ObjectNode before = input.deepCopy();
JsonNode result = knowledge.lookup(input, null);
String id = item.path("id").asText();
if (!result.path("status").asText().equals(item.path("status").asText()))
failures.add(id + ": expected " + item.path("status").asText() + " but " + result);
if ("matched".equals(result.path("status").asText())) {
assertThat(result.path("type_id").asText()).as(id).isEqualTo(item.path("selected_type").asText());
assertThat(result.path("documents")).as(id).hasSize(1);
} else assertThat(result.path("documents")).as(id).isEmpty();
for (JsonNode field : item.path("missing"))
assertThat(result.path("missing").toString()).as(id).contains(field.asText());
assertThat(input).as(id + " never extracts or corrects supplied facts").isEqualTo(before);
}
assertThat(failures).isEmpty();
}
}
@@ -1,279 +0,0 @@
package com.linkerbot.vibemake.service.cad.ai;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.linkerbot.vibemake.bean.ai.CadAiContracts.CadAiTool;
import com.linkerbot.vibemake.common.BusinessException;
import java.io.IOException;
import java.io.InputStream;
import java.util.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.io.ClassPathResource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
/** 版本化工具 Schema;动态引擎参数仍由浏览器的原生命令注册表校验。 */
@Component
public class CadAiTools {
public static final String VERSION = "cad-agent-v1";
private static final Logger log = LoggerFactory.getLogger(CadAiTools.class);
private final List<CadAiTool> tools;
private final Map<String, CadAiTool> byName;
private final Map<String, Set<String>> skillFiles;
private final String instructions;
@Autowired
public CadAiTools(ObjectMapper json) throws IOException {
this(json, readKnowledgePolicy(json));
}
CadAiTools(ObjectMapper json, JsonNode knowledgePolicy) throws IOException {
JsonNode bundle;
try (InputStream input = new ClassPathResource("cad/ai/skills.json").getInputStream()) {
bundle = json.readTree(input);
}
if (bundle == null || !bundle.path("formatVersion").isInt() || bundle.path("formatVersion").asInt() != 1
|| !bundle.path("revision").asText().matches("[a-f0-9]{64}")
|| !bundle.path("workflow").isTextual() || bundle.path("workflow").asText().isBlank()
|| !bundle.path("skills").isArray() || bundle.path("skills").isEmpty())
throw new IOException("Invalid bundled CAD AI skills metadata");
Map<String, Set<String>> filesBySkill = new LinkedHashMap<>();
Set<String> allFiles = new TreeSet<>();
StringBuilder catalog = new StringBuilder(bundle.path("workflow").asText())
.append("\n\nAvailable makeCAD skills (read the relevant SKILL.md with skill_reference, then its needed references):\n");
for (JsonNode skill : bundle.path("skills")) {
String name = skill.path("name").asText();
String description = skill.path("description").asText();
JsonNode files = skill.path("files");
if (!name.matches("makecad-[a-z][a-z0-9-]*") || !skill.path("description").isTextual() || description.isBlank()
|| !files.isObject() || !files.path("SKILL.md").isTextual() || filesBySkill.containsKey(name))
throw new IOException("Invalid bundled CAD AI skill entry: " + name);
Set<String> paths = new TreeSet<>();
Iterator<Map.Entry<String, JsonNode>> entries = files.fields();
while (entries.hasNext()) {
Map.Entry<String, JsonNode> entry = entries.next();
String path = entry.getKey();
if (!path.matches("(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+\\.(?:md|py)")
|| !entry.getValue().isTextual() || entry.getValue().asText().isBlank())
throw new IOException("Invalid bundled CAD AI skill document: " + name + "/" + path);
paths.add(path);
}
filesBySkill.put(name, Set.copyOf(paths));
allFiles.addAll(paths);
catalog.append("- ").append(name).append(": ").append(description)
.append(" Files: ").append(String.join(", ", paths)).append('\n');
}
skillFiles = Map.copyOf(filesBySkill);
instructions = catalog.toString();
List<CadAiTool> definitions;
try (InputStream input = new ClassPathResource("cad/ai/" + VERSION + ".json").getInputStream()) {
definitions = new ArrayList<>(json.readValue(input, new TypeReference<List<CadAiTool>>() {}));
}
ObjectNode parameters = json.createObjectNode().put("type", "object").put("additionalProperties", false);
parameters.putArray("required").add("skill");
ObjectNode properties = parameters.putObject("properties");
ArrayNode names = properties.putObject("skill").put("type", "string")
.put("description", "技能名称;根据系统目录选择与当前任务相关的技能").putArray("enum");
filesBySkill.keySet().forEach(names::add);
ArrayNode paths = properties.putObject("file").put("type", "string").put("default", "SKILL.md")
.put("description", "该技能已打包的文档路径,默认 SKILL.md;不访问任意文件系统").putArray("enum");
allFiles.forEach(paths::add);
definitions.add(new CadAiTool("skill_reference", "读取 makeCAD 随版本打包的技能文档。只读、无文件系统访问;先读 SKILL.md,再读任务需要的参考文档。", parameters));
definitions.add(knowledgeDefinition(json, knowledgePolicy));
tools = List.copyOf(definitions);
Map<String, CadAiTool> index = new LinkedHashMap<>();
for (CadAiTool tool : tools) {
if (index.put(tool.name(), tool) != null) throw new IOException("Duplicate bundled CAD AI tool name: " + tool.name());
}
byName = Map.copyOf(index);
log.info("CAD AI skills loaded: revision={}, count={}", bundle.path("revision").asText(), skillFiles.size());
}
public List<CadAiTool> definitions() { return tools; }
public List<CadAiTool> definitions(boolean knowledgeEnabled) {
return tools.stream().filter(tool -> knowledgeEnabled || !"knowledge_lookup".equals(tool.name())).toList();
}
public String instructions() { return instructions; }
static CadAiTool knowledgeDefinition(ObjectMapper json) throws IOException {
return knowledgeDefinition(json, readKnowledgePolicy(json));
}
private static JsonNode readKnowledgePolicy(ObjectMapper json) throws IOException {
try (InputStream input = new ClassPathResource("cad/ai/knowledge/generation/policy.json").getInputStream()) {
return json.readTree(input);
}
}
private static CadAiTool knowledgeDefinition(ObjectMapper json, JsonNode policy) throws IOException {
ObjectNode parameters = json.createObjectNode().put("type", "object").put("additionalProperties", false);
parameters.putArray("required").add("query");
ObjectNode properties = parameters.putObject("properties");
properties.putObject("query").put("type", "string").put("minLength", 1).put("maxLength", 2000)
.put("description", "当前待建或待改的部件需求;明确保留否定及选配要求,复杂结构可查询已确定的部件");
ArrayNode typeIds = properties.putObject("type_id").put("type", "string").put("maxLength", 80)
.put("description", "可选;仅用enum中的稳定ID,未知时省略,由query识别,不猜写ID").putArray("enum");
JsonNode catalog;
try (InputStream input = new ClassPathResource("cad/ai/knowledge/generation/catalog.json").getInputStream()) { catalog = json.readTree(input); }
CadAiKnowledge.validateCatalog(catalog).keySet().stream().sorted().forEach(typeIds::add);
ObjectNode facts = properties.putObject("facts").put("type", "object").put("additionalProperties", false);
ObjectNode fields = facts.putObject("properties");
for (Map.Entry<String, JsonNode> entry : CadAiKnowledge.validateFactDefinitions(catalog).entrySet()) {
JsonNode definition = entry.getValue();
ObjectNode field = fields.putObject(entry.getKey()).put("description", definition.path("description").asText()
+ ("none".equals(definition.path("unit").asText()) ? "" : " (" + definition.path("unit").asText() + ")"));
field.putArray("type").add(definition.path("type").asText()).add("null");
if ("string".equals(definition.path("type").asText())) field.put("maxLength", 80);
}
Map<String, Map<String, Set<String>>> stringEqualities = new TreeMap<>();
for (JsonNode document : policy.path("documents")) {
if ("retired".equals(document.path("status").asText())) continue;
Iterator<Map.Entry<String, JsonNode>> conditions = document.path("conditions").fields();
while (conditions.hasNext()) {
Map.Entry<String, JsonNode> condition = conditions.next();
JsonNode expected = condition.getValue().path("equals");
if (expected.isTextual() && fields.has(condition.getKey())) {
stringEqualities.computeIfAbsent(condition.getKey(), key -> new TreeMap<>())
.computeIfAbsent(expected.asText(), key -> new TreeSet<>()).add(document.path("type_id").asText());
}
}
}
for (Map.Entry<String, Map<String, Set<String>>> entry : stringEqualities.entrySet()) {
ObjectNode field = (ObjectNode) fields.path(entry.getKey());
ArrayNode values = field.putArray("enum");
List<String> typeGuidance = new ArrayList<>();
for (Map.Entry<String, Set<String>> equality : entry.getValue().entrySet()) {
values.add(equality.getKey());
typeGuidance.add(equality.getKey() + ":" + String.join(",", equality.getValue()));
}
values.addNull();
field.put("description", field.path("description").asText() + ";当前规程登记值/类型:" + String.join(";", typeGuidance)
+ "。只填已明确采用的值,未知可省略;不代表其他变体受支持。");
}
facts.put("description", "仅填用户给定或当前计划明确采用的相关条件;未知可省略或填null。所需条件以查询返回missing为准,不为命中规程擅改需求或默认尺寸。");
return new CadAiTool("knowledge_lookup", "按需读取齿轮、齿条、蜗轮蜗杆及其机构的专项构造规程,或XZ轴承座筋方向提示。普通基础造型无需查询;只读,沿原通用技能执行。", parameters);
}
/** Only schema paths and fixed rule names; never retain argument values in diagnostics. */
public record ValidationIssue(String rule, String path) {}
public String diagnosticName(String name) { return name != null && byName.containsKey(name) ? name : "unknown"; }
public void validateCall(String name, JsonNode arguments) {
CadAiTool tool = name == null ? null : byName.get(name);
if (tool == null) throw invalid("unknown_tool", "$");
if (arguments == null || !arguments.isObject()) throw invalid("object_required", "$");
ValidationIssue issue = validateSchema(tool.parameters(), arguments, "$", 0);
if (issue != null) throw invalid(issue.rule(), issue.path());
if ("skill_reference".equals(name)) {
Set<String> files = skillFiles.get(arguments.path("skill").asText());
if (files == null || !files.contains(arguments.path("file").asText("SKILL.md"))) throw invalid("skill_file", "$.file");
}
if ("set_parameter".equals(name)) {
JsonNode value = arguments.get("value");
JsonNode expression = arguments.get("expression");
if (value == null && expression == null
|| value != null && expression != null && !value.asText().equals(expression.asText())) throw invalid("parameter_alias", "$.value");
}
if ("screenshot".equals(name) && arguments.has("view") && arguments.has("camera")) throw invalid("view_camera_conflict", "$.camera");
if ("execute".equals(name)) checkCommand(arguments.path("command").asText(), "$.command");
if ("batch".equals(name)) {
int index = 0;
for (JsonNode step : arguments.path("commands")) {
String command = step.path("command").asText();
String path = "$.commands[" + index + "]";
if (byName.containsKey(command)) {
if (Set.of("batch", "screenshot", "check_parameters", "body_topology", "skill_reference", "knowledge_lookup").contains(command)) throw invalid("unsupported_batch_tool", path + ".command");
try {
validateCall(command, step.has("params") ? step.get("params") : com.fasterxml.jackson.databind.node.JsonNodeFactory.instance.objectNode());
} catch (BusinessException error) {
if (error.details() instanceof ValidationIssue nested)
throw invalid(nested.rule(), path + ".params" + nested.path().substring(1));
throw error;
}
} else checkCommand(command, path + ".command");
index++;
}
}
}
private void checkCommand(String command, String path) {
if (!command.matches("[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+")) throw invalid("command_format", path);
// 后端只做已知危险命令的拒绝;浏览器还必须通过原生 gate,而不能把此处当作完整授权。
if (command.matches("(file|doc|ui|diagnostics|preferences|settings|app)\\..*")
|| Set.of("view.next_tab", "view.previous_tab", "component.edit_in_place", "component.finish_edit").contains(command))
throw invalid("command_not_allowed", path);
}
private ValidationIssue validateSchema(JsonNode schema, JsonNode value, String path, int depth) {
if (depth > 32) return new ValidationIssue("schema_depth", path);
JsonNode type = schema.path("type");
if (type.isArray()) {
boolean match = false;
for (JsonNode choice : type) match |= matches(choice.asText(), value);
if (!match) return new ValidationIssue("type", path);
} else if (type.isTextual() && !matches(type.asText(), value)) return new ValidationIssue("type", path);
if (schema.has("enum")) {
boolean match = false;
for (JsonNode choice : schema.path("enum")) match |= choice.equals(value);
if (!match) return new ValidationIssue("enum", path);
}
if (value.isTextual() && (value.asText().length() < schema.path("minLength").asInt(0)
|| value.asText().length() > schema.path("maxLength").asInt(Integer.MAX_VALUE))) return new ValidationIssue("string_length", path);
if (value.isTextual() && schema.has("pattern") && !value.asText().matches(schema.path("pattern").asText())) return new ValidationIssue("pattern", path);
if (value.isNumber() && (schema.has("minimum") && value.decimalValue().compareTo(schema.path("minimum").decimalValue()) < 0
|| schema.has("maximum") && value.decimalValue().compareTo(schema.path("maximum").decimalValue()) > 0)) return new ValidationIssue("number_range", path);
if (value.isObject()) {
for (JsonNode field : schema.path("required")) if (!value.has(field.asText())) return new ValidationIssue("required", path + "." + field.asText());
if (value.size() < schema.path("minProperties").asInt(0)) return new ValidationIssue("min_properties", path);
Iterator<Map.Entry<String, JsonNode>> fields = value.fields();
while (fields.hasNext()) {
Map.Entry<String, JsonNode> field = fields.next();
JsonNode property = schema.path("properties").get(field.getKey());
JsonNode additional = schema.get("additionalProperties");
if (property != null) {
ValidationIssue issue = validateSchema(property, field.getValue(), path + "." + field.getKey(), depth + 1);
if (issue != null) return issue;
} else if (additional != null && additional.isBoolean() && !additional.asBoolean()) return new ValidationIssue("additional_property", path + ".*");
else if (additional != null && additional.isObject()) {
ValidationIssue issue = validateSchema(additional, field.getValue(), path + ".*", depth + 1);
if (issue != null) return issue;
}
}
}
if (value.isArray()) {
if (value.size() < schema.path("minItems").asInt(0)) return new ValidationIssue("min_items", path);
if (value.size() > schema.path("maxItems").asInt(Integer.MAX_VALUE)) return new ValidationIssue("max_items", path);
if (schema.has("items")) {
for (int index = 0; index < value.size(); index++) {
ValidationIssue issue = validateSchema(schema.path("items"), value.get(index), path + "[" + index + "]", depth + 1);
if (issue != null) return issue;
}
}
}
return null;
}
private boolean matches(String type, JsonNode value) {
return switch (type) {
case "null" -> value.isNull();
case "object" -> value.isObject();
case "array" -> value.isArray();
case "string" -> value.isTextual();
case "boolean" -> value.isBoolean();
case "number" -> value.isNumber();
case "integer" -> value.isIntegralNumber();
default -> false;
};
}
private BusinessException invalid(String rule, String path) {
return new BusinessException(400, "CAD_AI_INVALID_TOOL", "CAD 工具名称或参数不符合协议", new ValidationIssue(rule, path));
}
}
@@ -1,49 +0,0 @@
package com.linkerbot.vibemake.service.cad.ai;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.linkerbot.vibemake.service.config.CadAiProperties;
import java.io.IOException;
import java.io.InputStream;
import java.util.Set;
/** Preserves the published v2 routing expectations, separately from the live utility policy. */
final class HistoricalCadAiKnowledge {
private static final Set<String> RETIRED_BUILD_GATE_CASES = Set.of(
"unavailable-01", "compatibility-involute-spur-gear", "compatibility-internal-spur-gear",
"compatibility-helical-cylindrical-gear", "compatibility-straight-rack", "compatibility-helical-rack",
"compatibility-worm", "compatibility-straight-bevel-gear", "compatibility-spiral-bevel-gear",
"compatibility-worm-wheel", "compatibility-gear-pair", "compatibility-rack-and-pinion",
"compatibility-worm-drive", "compatibility-planetary-gear-mechanism", "mounting-plate-exact-build-only",
"stepped-shaft-exact-build-only", "hex-head-bolt-exact-build-only", "ribbed-bearing-housing-exact-build-only",
"covered-thin-wall-enclosure-exact-build-only", "herringbone-gear-exact-build-only", "double-helical-gear-exact-build-only");
private HistoricalCadAiKnowledge() {}
static String runtimeStatus(JsonNode item) {
String recorded = item.path("status").asText();
// Preserve the historical JSON byte-for-byte while explicitly testing the sole
// intentional behaviour change: these complete requests no longer gate on build.
if (!"incompatible".equals(recorded)) return recorded;
if (!RETIRED_BUILD_GATE_CASES.contains(item.path("id").asText()))
throw new AssertionError("Undeclared historical build-gate expectation: " + item.path("id").asText());
return "matched";
}
static JsonNode policy(ObjectMapper json) throws IOException {
try (InputStream input = HistoricalCadAiKnowledge.class.getResourceAsStream(
"/cad/ai/knowledge/evals/policy-before-utility-pruning-v1.json")) {
if (input == null) throw new IOException("Missing historical CAD policy");
byte[] bytes = input.readAllBytes();
CadAiKnowledge.verifyHash(bytes, "773fa40bdd5daf51282037d6e46c9afce2dcf5820f2baff24a4db63bc186ee80");
return json.readTree(bytes);
}
}
static CadAiKnowledge knowledge(ObjectMapper json, CadAiProperties properties) throws IOException {
return new CadAiKnowledge(json, properties, policy(json));
}
static CadAiTools tools(ObjectMapper json) throws IOException {
return new CadAiTools(json, policy(json));
}
}
@@ -1,57 +0,0 @@
{
"created_utc": "2026-11-12T09:33:43.097868+00:00",
"reason": "Runtime contract changes from gated semantic routing to assistant-selected document reading. These sources and 531 fixed routing cases are historical, not passing tests of the new reader.",
"sources": {
"vibemake-service/src/main/java/com/linkerbot/vibemake/service/cad/ai/CadAiKnowledge.java": {
"archive": "CadAiKnowledge.java.txt",
"sha256": "c8713ae8a4167b094105f9534a932298b1200a6a55430108aa3fef033f04a490"
},
"vibemake-service/src/main/java/com/linkerbot/vibemake/service/cad/ai/CadAiTools.java": {
"archive": "CadAiTools.java.txt",
"sha256": "f1c03625e8f30ec2ff0270cbf29db64a6b6be5bf3ec489568353ed577c0f0bcf"
},
"vibemake-service/src/test/java/com/linkerbot/vibemake/service/cad/ai/CadAiKnowledgeTest.java": {
"archive": "CadAiKnowledgeTest.java.txt",
"sha256": "5cd62cf75c322c8b036ed4bcf2659d630d83350173cefa4fe9c76129c1a9c809"
},
"vibemake-service/src/test/java/com/linkerbot/vibemake/service/cad/ai/CadAiSampleKnowledgeTest.java": {
"archive": "CadAiSampleKnowledgeTest.java.txt",
"sha256": "3a9400c5d7b783c821739b83d92c5b5a96b0c7833851b28416f3a9ebd3d18457"
},
"vibemake-service/src/test/java/com/linkerbot/vibemake/service/cad/ai/CadAiKnowledgeUtilityTest.java": {
"archive": "CadAiKnowledgeUtilityTest.java.txt",
"sha256": "b9edce0ceb451023a8ca0f40d291f96750305e6e42e5cfc43ad73eb2e9c1b72e"
},
"vibemake-service/src/test/java/com/linkerbot/vibemake/service/cad/ai/HistoricalCadAiKnowledge.java": {
"archive": "HistoricalCadAiKnowledge.java.txt",
"sha256": "466e4bcab22895e6291a298aa9d41a0727b3ff4c8bf04f700aa9bab2229c2ad3"
}
},
"unchanged_fixtures": {
"gear-routing-v8.json": {
"sha256": "7067238293b32c04d65bfe79374fc7832d8942fb3f544a30e3e29ac346b1feb0",
"cases": 287
},
"sample-parts-routing-v1.json": {
"sha256": "7dd545958fe2440b9895c8762afc1864dfbad5f2155ad6a223c8d3f53a404336",
"cases": 129
},
"sample-parts-routing-v2.json": {
"sha256": "4246b07eef53d2da7cb15d1cf350ff94514648f8796a9ecefbe5d4f866a6e35c",
"cases": 26
},
"sample-parts-routing-v3.json": {
"sha256": "195a1febb4167d0cee56736f35f858d5df095227426985fd1cc2e5acb4aac571",
"cases": 34
},
"sample-parts-routing-v4.json": {
"sha256": "e1ea0fe4c549309e15fe220da48ca76c5da35e4579474cb99f2eaa328bcc1361",
"cases": 25
},
"sample-parts-routing-v5.json": {
"sha256": "d442585fdf7f9b1a7e1e28fe11211503a764a2dfd85b2c74147589128d02baff",
"cases": 30
}
},
"historical_fixed_cases": 531
}
File diff suppressed because it is too large Load Diff
@@ -1,41 +0,0 @@
{
"schema_version": 1,
"description": "保存两条真实失败;新读取协议只提交document_id,不复用原申请式参数。",
"cases": [
{
"id": "user-planetary-zh-original",
"original_lookup_arguments": {
"query": "创建一个简化但可检查的行星减速器:太阳轮、三个行星轮、内齿圈、行星架和同轴输出结构。未指定尺寸,采用常见的等模数参数,并保留参数化与可动机构语义。",
"type_id": "planetary-gear-mechanism",
"facts": {
"geometry_representation": "simple-spur-planetary-v1"
}
},
"before_reader_status": "ambiguous",
"reader_arguments": {
"document_id": "planetary-gear-mechanism"
},
"reader_status": "matched",
"source_doc_id": "straight-planetary-interface"
},
{
"id": "user-planetary-en-original",
"original_lookup_arguments": {
"query": "simple planetary gear mechanism with sun gear, three planet gears, internal ring gear, planet carrier; gears are all straight spur gears, module 2 mm, pressure angle 20 degrees, sun teeth 20, planet teeth 20, ring teeth 60, 8 mm face width. Simplified kinematic planetary mechanism representation, not detailed involute geometry.",
"type_id": "planetary-gear-mechanism",
"facts": {
"geometry_representation": "simple-spur-planetary-v1",
"module_mm": 2,
"teeth": 20,
"pressure_angle_deg": 20
}
},
"before_reader_status": "ambiguous",
"reader_arguments": {
"document_id": "planetary-gear-mechanism"
},
"reader_status": "matched",
"source_doc_id": "straight-planetary-interface"
}
]
}
@@ -1,535 +0,0 @@
{
"version": 1,
"description": "确定性路由72场景;不代表LLM语义或几何评测",
"cases": [
{
"id": "explicit-01",
"group": "explicit",
"query": "外渐开线直齿圆柱齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "explicit-02",
"group": "explicit",
"query": "渐开线直齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "explicit-03",
"group": "explicit",
"query": "直齿圆柱齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "explicit-04",
"group": "explicit",
"query": "直齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "explicit-05",
"group": "explicit",
"query": "spur gear",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "explicit-06",
"group": "explicit",
"query": "external involute spur gear",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "explicit-07",
"group": "explicit",
"query": "内直齿轮",
"status": "uncovered",
"type_id": "internal-spur-gear"
},
{
"id": "explicit-08",
"group": "explicit",
"query": "内齿圈",
"status": "uncovered",
"type_id": "internal-spur-gear"
},
{
"id": "explicit-09",
"group": "explicit",
"query": "helical gear",
"status": "uncovered",
"type_id": "helical-cylindrical-gear"
},
{
"id": "explicit-10",
"group": "explicit",
"query": "斜齿圆柱齿轮",
"status": "uncovered",
"type_id": "helical-cylindrical-gear"
},
{
"id": "explicit-11",
"group": "explicit",
"query": "直齿锥齿轮",
"status": "uncovered",
"type_id": "straight-bevel-gear"
},
{
"id": "explicit-12",
"group": "explicit",
"query": "straight bevel gear",
"status": "uncovered",
"type_id": "straight-bevel-gear"
},
{
"id": "explicit-13",
"group": "explicit",
"query": "螺旋锥齿轮",
"status": "uncovered",
"type_id": "spiral-bevel-gear"
},
{
"id": "explicit-14",
"group": "explicit",
"query": "spiral bevel gear",
"status": "uncovered",
"type_id": "spiral-bevel-gear"
},
{
"id": "explicit-15",
"group": "explicit",
"query": "直齿齿条",
"status": "uncovered",
"type_id": "straight-rack"
},
{
"id": "explicit-16",
"group": "explicit",
"query": "helical rack",
"status": "uncovered",
"type_id": "helical-rack"
},
{
"id": "explicit-17",
"group": "explicit",
"query": "worm wheel",
"status": "uncovered",
"type_id": "worm-wheel"
},
{
"id": "explicit-18",
"group": "explicit",
"query": "蜗杆",
"status": "uncovered",
"type_id": "worm"
},
{
"id": "nested-01",
"group": "nested",
"query": "在一个轴和壳体组合中,为输入轴建一个渐开线直齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "nested-02",
"group": "nested",
"query": "泵的传动部件已经选定为直齿圆柱齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "nested-03",
"group": "nested",
"query": "为齿轮箱的输出端做spur gear",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "nested-04",
"group": "nested",
"query": "复杂机构中当前只做external involute spur gear",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "nested-05",
"group": "nested",
"query": "当前待修改部件是直齿轮,保留其他壳体",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "nested-06",
"group": "nested",
"query": "轴上固定一个直齿轮,其他零件不处理",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "nested-07",
"group": "nested",
"query": "齿轮副内当前只造斜齿轮",
"status": "uncovered",
"type_id": "helical-cylindrical-gear"
},
{
"id": "nested-08",
"group": "nested",
"query": "复杂装置中先做蜗轮",
"status": "uncovered",
"type_id": "worm-wheel"
},
{
"id": "nested-09",
"group": "nested",
"query": "复杂装置中先做蜗杆",
"status": "uncovered",
"type_id": "worm"
},
{
"id": "nested-10",
"group": "nested",
"query": "角传动中已明确使用直齿锥齿轮",
"status": "uncovered",
"type_id": "straight-bevel-gear"
},
{
"id": "nested-11",
"group": "nested",
"query": "底座上的直齿齿条",
"status": "uncovered",
"type_id": "straight-rack"
},
{
"id": "nested-12",
"group": "nested",
"query": "只造齿轮箱外壳,不造内部齿轮",
"status": "uncovered",
"type_id": "gearbox-housing"
},
{
"id": "ambiguous-01",
"group": "ambiguous",
"query": "齿轮",
"status": "ambiguous"
},
{
"id": "ambiguous-02",
"group": "ambiguous",
"query": "螺旋齿轮",
"status": "ambiguous"
},
{
"id": "ambiguous-03",
"group": "ambiguous",
"query": "锥齿轮",
"status": "ambiguous"
},
{
"id": "ambiguous-04",
"group": "ambiguous",
"query": "齿条",
"status": "ambiguous"
},
{
"id": "ambiguous-05",
"group": "ambiguous",
"query": "平行轴传动",
"status": "ambiguous"
},
{
"id": "ambiguous-06",
"group": "ambiguous",
"query": "90度传动",
"status": "ambiguous"
},
{
"id": "ambiguous-07",
"group": "ambiguous",
"query": "一个减速装置",
"status": "ambiguous"
},
{
"id": "ambiguous-08",
"group": "ambiguous",
"query": "spindle transmission",
"status": "ambiguous"
},
{
"id": "ambiguous-09",
"group": "ambiguous",
"query": "直齿轮和斜齿轮一起",
"status": "ambiguous"
},
{
"id": "ambiguous-10",
"group": "ambiguous",
"query": "蜗杆与直齿轮一起",
"status": "ambiguous"
},
{
"id": "negation-01",
"group": "negation",
"query": "不要蜗杆,用直齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "negation-02",
"group": "negation",
"query": "不要斜齿轮,改成直齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "negation-03",
"group": "negation",
"query": "不是直齿锥齿轮,而是直齿轮",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "negation-04",
"group": "negation",
"query": "不要直齿轮,用蜗轮",
"status": "uncovered",
"type_id": "worm-wheel"
},
{
"id": "negation-05",
"group": "negation",
"query": "不要直齿轮,改成斜齿轮",
"status": "uncovered",
"type_id": "helical-cylindrical-gear"
},
{
"id": "negation-06",
"group": "negation",
"query": "不做螺旋锥齿轮,改用直齿锥齿轮",
"status": "uncovered",
"type_id": "straight-bevel-gear"
},
{
"id": "negation-07",
"group": "negation",
"query": "not helical gear, use spur gear",
"status": "matched",
"type_id": "involute-spur-gear"
},
{
"id": "negation-08",
"group": "negation",
"query": "不要齿轮",
"status": "ambiguous"
},
{
"id": "multi_turn-01",
"group": "multi_turn",
"query": "改成斜齿轮",
"status": "uncovered",
"type_id": "helical-cylindrical-gear",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-02",
"group": "multi_turn",
"query": "改成直齿锥齿轮",
"status": "uncovered",
"type_id": "straight-bevel-gear",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-03",
"group": "multi_turn",
"query": "改成蜗杆",
"status": "uncovered",
"type_id": "worm",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-04",
"group": "multi_turn",
"query": "改成内直齿轮",
"status": "uncovered",
"type_id": "internal-spur-gear",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-05",
"group": "multi_turn",
"query": "改成直齿齿条",
"status": "uncovered",
"type_id": "straight-rack",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-06",
"group": "multi_turn",
"query": "只修改齿轮箱外壳",
"status": "uncovered",
"type_id": "gearbox-housing",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-07",
"group": "multi_turn",
"query": "改成斜齿轮",
"status": "uncovered",
"type_id": "helical-cylindrical-gear",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-08",
"group": "multi_turn",
"query": "改成直齿锥齿轮",
"status": "uncovered",
"type_id": "straight-bevel-gear",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-09",
"group": "multi_turn",
"query": "改成蜗杆",
"status": "uncovered",
"type_id": "worm",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-10",
"group": "multi_turn",
"query": "改成内直齿轮",
"status": "uncovered",
"type_id": "internal-spur-gear",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-11",
"group": "multi_turn",
"query": "改成直齿齿条",
"status": "uncovered",
"type_id": "straight-rack",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "multi_turn-12",
"group": "multi_turn",
"query": "只修改齿轮箱外壳",
"status": "uncovered",
"type_id": "gearbox-housing",
"previous_query": "先建一个直齿轮",
"previous_status": "matched"
},
{
"id": "unavailable-01",
"group": "unavailable",
"query": "直齿轮",
"status": "incompatible",
"type_id": "involute-spur-gear",
"build": "000000000000000000000000"
},
{
"id": "unavailable-02",
"group": "unavailable",
"query": "直齿轮",
"status": "needs_conditions",
"type_id": "involute-spur-gear",
"remove_facts": [
"module_mm"
]
},
{
"id": "unavailable-03",
"group": "unavailable",
"query": "直齿轮",
"status": "needs_conditions",
"type_id": "involute-spur-gear",
"remove_facts": [
"root_transition"
]
},
{
"id": "unavailable-04",
"group": "unavailable",
"query": "直齿轮",
"status": "uncovered",
"type_id": "involute-spur-gear",
"fact_overrides": {
"teeth": 17
}
},
{
"id": "unavailable-05",
"group": "unavailable",
"query": "直齿轮",
"status": "uncovered",
"type_id": "involute-spur-gear",
"fact_overrides": {
"pressure_angle_deg": 25
}
},
{
"id": "unavailable-06",
"group": "unavailable",
"query": "直齿轮",
"status": "uncovered",
"type_id": "involute-spur-gear",
"fact_overrides": {
"profile_shift": 0.2
}
},
{
"id": "unavailable-07",
"group": "unavailable",
"query": "双曲面齿轮",
"status": "uncovered",
"type_id": "other-geared-transmission"
},
{
"id": "unavailable-08",
"group": "unavailable",
"query": "谐波齿轮",
"status": "uncovered",
"type_id": "other-geared-transmission"
},
{
"id": "nonmodel-01",
"group": "nonmodel",
"query": "解释直齿轮的原理",
"status": "not_applicable"
},
{
"id": "nonmodel-02",
"group": "nonmodel",
"query": "什么是渐开线直齿轮",
"status": "not_applicable"
},
{
"id": "nonmodel-03",
"group": "nonmodel",
"query": "explain a spur gear",
"status": "not_applicable"
},
{
"id": "nonmodel-04",
"group": "nonmodel",
"query": "比较斜齿轮和直齿轮",
"status": "not_applicable"
}
]
}
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -1,611 +0,0 @@
{
"version": "2.0.0",
"engine_build": "f3d62ce93f72db42f311a46e",
"extends": "sample-parts-routing-v1.json",
"preserved_v1_sha256": "7dd545958fe2440b9895c8762afc1864dfbad5f2155ad6a223c8d3f53a404336",
"source_red_case": "../reports/five-samples-herringbone-20261112/routing-failure-continuous-v1.json",
"cases": [
{
"id": "continuous-actual-formal-query",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "建立无槽连续人字齿轮示意模型:轴线Z,Z=0到16 mm;法向模数2 mm,齿数24,法向压力角20°;下半臂有符号螺旋角+20°,上半臂相反;两半等宽,中面同相连续,无中央退刀槽,中央槽宽0;零变位、零侧隙、齿顶高系数1、顶隙系数0.25;允许径向简化齿根;中心Z向D8通孔;单一连通实体;无轮毂、键槽、倒角。主要齿形和宽度使用原生参数,两臂共享参数链。检查渐开线端面、齿数、两臂旋向和中面连接。明确为参数/结构示意,不声称制造级尖脊、共轭接触或承载认证。",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "absent-central-groove",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮;无中央退刀槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "absent-central-slot",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽人字齿轮,没有中央槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "not-set-central-slot",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,不设置中央槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "not-carry-groove",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,不带退刀槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "zero-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,中央槽宽0",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "zero-gap-decimal",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,中央槽宽度=0.00 mm",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "zero-gap-chinese-unit",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮;中央退刀槽轴向宽为0毫米",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "english-no-groove",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "create a continuous herringbone gear; no central groove",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "english-zero-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "create a continuous herringbone gear; central gap width=0 mm.",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "herringbone-continuous"
},
{
"id": "positive-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,带中央退刀槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "positive-fractional-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,中央槽宽0.4 mm",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "positive-small-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,中央槽宽0.01 mm",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "contradictory-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,中央槽宽0,但另有退刀槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "internal-conflict",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,无中央退刀槽,内啮合",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "unequal-conflict",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,中央槽宽0,不等宽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "english-positive-gap",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "create a continuous herringbone gear; central gap width=0.5 mm.",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "uncertain-negation",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,不能没有退刀槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "zero-text-does-not-correct-facts",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,无中央退刀槽,中央槽宽0",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "uncovered"
},
{
"id": "grooved-type-cannot-hide-no-groove",
"type_id": "double-helical-gear",
"selected_type": "double-helical-gear",
"query": "制作带槽双斜齿轮,无槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "absent-clause-cannot-hide-positive-width",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,无中央槽宽4 mm",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "english-absence-cannot-hide-positive-width",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "create a continuous herringbone gear; no central groove width=4 mm.",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "english-double-negation",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "create a continuous herringbone gear; not no central groove",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "chinese-double-negation",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "制作无槽连续人字齿轮,并非无中央槽",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "negative-continuous-type-remains-valid-replacement",
"type_id": "double-helical-gear",
"selected_type": "double-helical-gear",
"query": "不要无槽人字齿轮,只制作带槽双斜齿轮",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"doc_id": "double-helical-gap"
},
{
"id": "continuous-second-formal-query-still-needs-explicit-facts",
"type_id": "herringbone-gear",
"selected_type": "herringbone-gear",
"query": "仅确认无槽连续人字齿轮的构造规则:两臂等宽,中央同相连续,中央槽宽0;轴线Z,法向模数2,24齿,法向压力角20°,下臂+20°、上臂-20°;要求参数示意、单体、中心通孔。",
"facts": {
"central_gap_mm": 0,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"teeth": 24
},
"status": "needs_conditions"
}
]
}
@@ -1,700 +0,0 @@
{
"version": "3.0.0",
"description": "Explicitly selected component recipes can recognize a qualified gear-pair noun without absorbing independent components or mechanisms.",
"engine_build": "f3d62ce93f72db42f311a46e",
"extends": "sample-parts-routing-v2.json",
"source_red_case": "/Users/lk/Projects/cad-generation-benchmark/experiments/compound-reducer-20261112/trial/request-004.json",
"cases": [
{
"id": "actual-compound-query-missing-facts",
"query": "构造带中央退刀槽的双斜齿轮副:法向模数2、法向压力角20°、螺旋角±15°、总齿宽20、中央槽2、两侧有效齿宽9;G1 20齿装Input_A,G2 30齿装Intermediate_B。需要确认分度直径、中心距、旋向、相位和可接受的几何表示。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20
},
"status": "needs_conditions",
"selected_type": "double-helical-gear",
"missing": [
"profile_shift",
"backlash_mm",
"addendum_coefficient",
"clearance_coefficient"
]
},
{
"id": "actual-compound-query-complete-facts",
"query": "构造带中央退刀槽的双斜齿轮副:法向模数2、法向压力角20°、螺旋角±15°、总齿宽20、中央槽2、两侧有效齿宽9;G1 20齿装Input_A,G2 30齿装Intermediate_B。需要确认分度直径、中心距、旋向、相位和可接受的几何表示。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "same-type-pair-with-two-counts",
"query": "制作两个双斜齿轮组成的双斜齿轮副,齿数分别为20和30。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "double-helical-pair-en",
"query": "create a double-helical gear pair, with 20 and 30 teeth.",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "double-helical-pair-en-space",
"query": "create a double helical gear pair.",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "herringbone-pair-zh",
"query": "制作无槽连续人字齿轮副。",
"type_id": "herringbone-gear",
"facts": {
"normal_module_mm": 2,
"teeth": 24,
"normal_pressure_angle_deg": 20,
"helix_angle_deg": 20,
"face_width_mm": 16,
"central_gap_mm": 0,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"root_transition": "radial-simplified",
"geometry_representation": "herringbone-continuous-midplane-v1"
},
"status": "matched",
"selected_type": "herringbone-gear",
"doc_id": "herringbone-continuous"
},
{
"id": "spur-pair-zh",
"query": "制作外渐开线直齿轮副。",
"type_id": "involute-spur-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 24,
"pressure_angle_deg": 20,
"root_transition": "radial-simplified"
},
"status": "matched",
"selected_type": "involute-spur-gear",
"doc_id": "gear-browser-equation-workflow"
},
{
"id": "spur-pair-en",
"query": "create an external involute spur gear pair.",
"type_id": "involute-spur-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 24,
"pressure_angle_deg": 20,
"root_transition": "radial-simplified"
},
"status": "matched",
"selected_type": "involute-spur-gear",
"doc_id": "gear-browser-equation-workflow"
},
{
"id": "helical-pair-zh",
"query": "制作斜齿圆柱齿轮副。",
"type_id": "helical-cylindrical-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"normal_module_mm": 2,
"teeth": 24,
"normal_pressure_angle_deg": 20,
"helix_angle_deg": 20,
"root_transition": "radial-simplified"
},
"status": "matched",
"selected_type": "helical-cylindrical-gear",
"doc_id": "helical-cylinder-whole-section"
},
{
"id": "bevel-pair-en",
"query": "create a straight bevel gear pair.",
"type_id": "straight-bevel-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 24,
"pressure_angle_deg": 20,
"cone_angle_deg": 45,
"axial_height_mm": 8,
"root_transition": "radial-simplified",
"geometry_representation": "homothetic-frontal-involute-bevel-v1"
},
"status": "matched",
"selected_type": "straight-bevel-gear",
"doc_id": "straight-bevel-scaled-section"
},
{
"id": "no-explicit-selection-preserves-choice",
"query": "构造带中央退刀槽的双斜齿轮副:法向模数2、法向压力角20°、螺旋角±15°、总齿宽20、中央槽2、两侧有效齿宽9;G1 20齿装Input_A,G2 30齿装Intermediate_B。需要确认分度直径、中心距、旋向、相位和可接受的几何表示。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous"
},
{
"id": "wrong-spur-selection-cannot-override-query",
"query": "构造带中央退刀槽的双斜齿轮副:法向模数2、法向压力角20°、螺旋角±15°、总齿宽20、中央槽2、两侧有效齿宽9;G1 20齿装Input_A,G2 30齿装Intermediate_B。需要确认分度直径、中心距、旋向、相位和可接受的几何表示。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "involute-spur-gear"
},
{
"id": "separate-pair-is-another-object",
"query": "制作双斜齿轮,另做齿轮副。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "different-bevel-part-preserved",
"query": "制作双斜齿轮副,再做直齿锥齿轮。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "extra-worm-preserved",
"query": "制作双斜齿轮副,另加蜗杆。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "second-mechanism-preserved",
"query": "制作双斜齿轮副和蜗轮蜗杆机构。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "mechanism-selection-does-not-infer-single-part",
"query": "构造带中央退刀槽的双斜齿轮副:法向模数2、法向压力角20°、螺旋角±15°、总齿宽20、中央槽2、两侧有效齿宽9;G1 20齿装Input_A,G2 30齿装Intermediate_B。需要确认分度直径、中心距、旋向、相位和可接受的几何表示。",
"type_id": "double-helical-gear",
"facts": {
"geometry_representation": "parallel-external-spur-pair-v1"
},
"status": "ambiguous",
"selected_type": "gear-pair"
},
{
"id": "different-spur-part-preserved",
"query": "制作双斜齿轮副与外渐开线直齿轮。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "different-pair-form-preserved",
"query": "制作双斜齿轮副与斜齿轮副。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "unqualified-pair-cannot-use-part-id",
"query": "制作齿轮副。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "negated-part-cannot-use-part-id",
"query": "不要双斜齿轮副,制作直齿轮。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "representation-conflict-preserved",
"query": "制作双斜齿轮副。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "uncovered-variant",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "uncovered",
"selected_type": "double-helical-gear",
"conflicts": [
"geometry_representation"
]
},
{
"id": "parameter-domain-conflict-preserved",
"query": "制作双斜齿轮副。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 40,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "uncovered",
"selected_type": "double-helical-gear",
"conflicts": [
"teeth"
]
},
{
"id": "repeated-same-part-name",
"query": "制作双斜齿轮副,双斜齿轮的轴线平行。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "independent-general-mechanism-preserved",
"query": "制作双斜齿轮副,并制作一对齿轮传动机构。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "punctuation-does-not-join-nouns",
"query": "制作双斜齿轮、齿轮副。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "independent-pair-en-preserved",
"query": "create a double-helical gear and a gear pair.",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "unknown-selection-preserved",
"query": "构造带中央退刀槽的双斜齿轮副:法向模数2、法向压力角20°、螺旋角±15°、总齿宽20、中央槽2、两侧有效齿宽9;G1 20齿装Input_A,G2 30齿装Intermediate_B。需要确认分度直径、中心距、旋向、相位和可接受的几何表示。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "unknown-gear-type"
},
{
"id": "latin-prefix-does-not-qualify-independent-pair",
"query": "create a double-helical gear, then a superdouble-helical gear pair.",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "unspecified-repeated-noun-remains-conservative",
"query": "制作双斜齿轮副,两个齿轮分别为20齿和30齿。",
"type_id": "double-helical-gear",
"facts": {
"central_gap_mm": 2,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 15,
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"root_transition": "radial-simplified",
"teeth": 20,
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "actual-bevel-pair-query-keeps-missing-facts",
"query": "当前待建第二级直齿锥齿轮副:G3、G4均20齿,大端模数2、压力角20°、轴交角90°、参考分锥角45°、沿锥距齿宽8;采用共同参考锥顶的缩放截面近似。请给出合法表示和关键构造检查。",
"type_id": "straight-bevel-gear",
"selected_type": "straight-bevel-gear",
"facts": {
"cone_angle_deg": 45,
"face_width_mm": 8,
"geometry_representation": "homothetic-frontal-involute-bevel-v1",
"pressure_angle_deg": 20,
"teeth": 20
},
"status": "needs_conditions",
"missing": [
"profile_shift",
"backlash_mm",
"addendum_coefficient",
"clearance_coefficient",
"module_mm",
"axial_height_mm",
"root_transition"
]
},
{
"id": "listed-worm-components-do-not-infer-mechanism",
"query": "当前待建第三级:C轴上的ZA圆柱蜗杆,右旋2头,轴向模数2,轴向压力角20°,分度直径20,有效长度28;D轴蜗轮32齿,端面模数2,端面压力角20°,齿宽7,参考蜗杆一致,喉部主半径42、母圆半径8,关于齿宽中面对称,两轴中心距42。请给出合法表示和关键构造检查。",
"type_id": "worm-drive",
"selected_type": "worm-drive",
"facts": {
"addendum_coefficient": 1,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"geometry_representation": "za-worm-and-illustrative-throat-wheel-v1",
"helix_hand": "right",
"lead_mm": 4,
"pitch_diameter_mm": 20,
"pressure_angle_deg": 20,
"teeth": 32,
"worm_starts": 2
},
"status": "ambiguous"
},
{
"id": "explicit-worm-mechanism-name-uses-existing-route",
"query": "当前待建第三级蜗轮蜗杆机构:C轴ZA蜗杆与D轴蜗轮,两轴中心距42。",
"type_id": "worm-drive",
"selected_type": "worm-drive",
"facts": {
"geometry_representation": "za-worm-and-illustrative-throat-wheel-v1"
},
"status": "matched",
"doc_id": "illustrative-worm-drive-interface"
},
{
"id": "explicit-worm-mechanism-keeps-representation-conflict",
"query": "当前待建第三级蜗轮蜗杆机构:C轴ZA蜗杆与D轴蜗轮,两轴中心距42。",
"type_id": "worm-drive",
"selected_type": "worm-drive",
"facts": {
"geometry_representation": "uncovered-variant"
},
"status": "uncovered",
"conflicts": [
"geometry_representation"
]
}
],
"continuation_source": "/Users/lk/Projects/cad-generation-benchmark/experiments/compound-reducer-20261112/trial-02-continuation-r2/terminal-assistant.json"
}
@@ -1,513 +0,0 @@
{
"version": "4.0.0",
"engine_build": "f3d62ce93f72db42f311a46e",
"extends": "sample-parts-routing-v3.json",
"source_red_case": "../reports/five-samples-herringbone-20261112/routing-failure-negative-features-v1.json",
"scope": "Continuous absent/zero groove repair plus user-authorized overlapping qualified gear-pair name coalescing. Explicit current part only; independent targets and conflicts remain rejected.",
"cases": [
{
"id": "pair-current-double-zh",
"group": "qualified-current-part-pair-name",
"query": "当前部件采用带槽双斜齿轮副中的双斜齿轮结构",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "pair-overlap-double-zh",
"group": "qualified-current-part-pair-name",
"query": "制作带槽双斜齿轮副,当前只构造已选的这一齿轮",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "pair-overlap-double-en",
"group": "qualified-current-part-pair-name",
"query": "create a double-helical gear pair",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "pair-overlap-double-en-spaced",
"group": "qualified-current-part-pair-name",
"query": "create a double helical gear pair",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"selected_type": "double-helical-gear",
"doc_id": "double-helical-gap"
},
{
"id": "pair-overlap-continuous-zh",
"group": "qualified-current-part-pair-name",
"query": "制作无槽连续人字齿轮副",
"type_id": "herringbone-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"selected_type": "herringbone-gear",
"doc_id": "herringbone-continuous"
},
{
"id": "pair-overlap-continuous-en",
"group": "qualified-current-part-pair-name",
"query": "create a continuous herringbone gear pair",
"type_id": "herringbone-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 0,
"clearance_coefficient": 0.25,
"face_width_mm": 16,
"geometry_representation": "herringbone-continuous-midplane-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "matched",
"selected_type": "herringbone-gear",
"doc_id": "herringbone-continuous"
},
{
"id": "pair-overlap-spur-zh",
"group": "qualified-current-part-pair-name",
"query": "制作外直齿轮副",
"type_id": "involute-spur-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 24,
"pressure_angle_deg": 20,
"root_transition": "radial-simplified"
},
"status": "matched",
"selected_type": "involute-spur-gear",
"doc_id": "gear-browser-equation-workflow"
},
{
"id": "pair-overlap-helical-en",
"group": "qualified-current-part-pair-name",
"query": "create a helical gear pair",
"type_id": "helical-cylindrical-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"normal_module_mm": 2,
"teeth": 24,
"normal_pressure_angle_deg": 20,
"helix_angle_deg": 20,
"root_transition": "radial-simplified"
},
"status": "matched",
"selected_type": "helical-cylindrical-gear",
"doc_id": "helical-cylinder-whole-section"
},
{
"id": "pair-no-explicit-part-stays-ambiguous",
"group": "qualified-current-part-pair-name",
"query": "制作带槽双斜齿轮副",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous"
},
{
"id": "pair-independent-target-zh",
"group": "qualified-current-part-pair-name",
"query": "制作带槽双斜齿轮,另做一个齿轮副",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "pair-independent-target-en",
"group": "qualified-current-part-pair-name",
"query": "create a double-helical gear and a separate gear pair",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "pair-overlap-plus-independent-pair",
"group": "qualified-current-part-pair-name",
"query": "create a double-helical gear pair and another gear pair",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "pair-bare-first-is-independent",
"group": "qualified-current-part-pair-name",
"query": "create a gear pair and a double-helical gear",
"type_id": "double-helical-gear",
"facts": {
"addendum_coefficient": 1,
"backlash_mm": 0,
"bore_diameter_mm": 8,
"central_gap_mm": 4,
"clearance_coefficient": 0.25,
"face_width_mm": 20,
"geometry_representation": "double-helical-root-core-gap-v1",
"helix_angle_deg": 20,
"helix_hand": "right",
"normal_module_mm": 2,
"normal_pressure_angle_deg": 20,
"profile_shift": 0,
"root_transition": "radial-simplified",
"teeth": 24
},
"status": "ambiguous",
"selected_type": "double-helical-gear"
},
{
"id": "pair-wrong-part-id",
"group": "qualified-current-part-pair-name",
"query": "制作带槽双斜齿轮副",
"type_id": "involute-spur-gear",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 24,
"pressure_angle_deg": 20,
"root_transition": "radial-simplified"
},
"status": "ambiguous",
"selected_type": "involute-spur-gear"
},
{
"id": "pair-explicit-mechanism-stays-mechanism",
"group": "qualified-current-part-pair-name",
"query": "制作外直齿轮副",
"type_id": "gear-pair",
"facts": {
"geometry_representation": "parallel-external-spur-pair-v1"
},
"status": "matched",
"selected_type": "gear-pair",
"doc_id": "fixed-axis-spur-pair"
},
{
"id": "pair-independent-plate",
"group": "qualified-current-part-pair-name",
"query": "制作带孔安装板和齿轮副",
"type_id": "mounting-plate",
"facts": {
"geometry_representation": "rectangular-plate-z-through-holes-v1",
"hole_count": 4
},
"status": "ambiguous",
"selected_type": "mounting-plate"
},
{
"id": "B-mounting-plate-v1-actual-negative-features",
"query": "建立一块矩形安装板:外形100 x 60 mm,厚8 mm,底面Z=0,XY中心在原点,四个沿Z的D6圆通孔,孔中心为(-35,-15)、(35,-15)、(-35,15)、(35,15),锐边,无沉孔、槽、倒角或其他结构。主要尺寸和孔位使用原生参数控制。",
"type_id": "mounting-plate",
"selected_type": "mounting-plate",
"facts": {
"geometry_representation": "rectangular-plate-z-through-holes-v1",
"hole_count": 4,
"min_wall_mm": null
},
"status": "matched",
"doc_id": "plate-through-holes"
},
{
"id": "B-covered-thin-wall-enclosure-v1-actual-negative-features",
"query": "建立可编辑的带盖薄壁壳体:底壳与独立平盖两个实体。底壳外形120×80,高40,侧壁厚3,底厚3,顶部开口;盖厚4,底面与壳顶间隙0.3。四个共享紧固孔中心距相邻外边10,壳内D10圆凸柱自内底面高37,柱顶向下D3盲孔深12;每柱一条沿Y连到邻近内壁的矩形筋,沿X厚2、由内底面起高12。盖四个D4通孔与柱孔同轴。不加螺钉、止口、铰链、圆角或倒角。采用两个连通实体的简化表示,保留共享紧固退边参数和主要尺寸参数。",
"type_id": "covered-thin-wall-enclosure",
"selected_type": "covered-thin-wall-enclosure",
"facts": {
"assembly_gap_mm": 0.3,
"bore_diameter_mm": 3,
"boss_height_mm": 37,
"boss_outer_diameter_mm": 10,
"bottom_thickness_mm": 3,
"fastener_inset_mm": 10,
"geometry_representation": "open-case-four-bosses-independent-flat-lid-v1",
"height_mm": 40,
"length_mm": 120,
"lid_thickness_mm": 4,
"min_wall_mm": 1.5,
"pilot_depth_mm": 12,
"rib_height_mm": 12,
"wall_thickness_mm": 3,
"width_mm": 80
},
"status": "matched",
"doc_id": "enclosure-shared-interface"
},
{
"id": "plate-positive-counterbore",
"query": "制作带孔安装板,含沉孔",
"type_id": "mounting-plate",
"selected_type": "mounting-plate",
"facts": {
"geometry_representation": "rectangular-plate-z-through-holes-v1",
"hole_count": 4
},
"status": "ambiguous"
},
{
"id": "plate-positive-after-but",
"query": "制作带孔安装板,无沉孔但保留盲孔",
"type_id": "mounting-plate",
"selected_type": "mounting-plate",
"facts": {
"geometry_representation": "rectangular-plate-z-through-holes-v1",
"hole_count": 4
},
"status": "ambiguous"
},
{
"id": "plate-independent-positive-feature",
"query": "制作带孔安装板,无沉孔、另加盲孔",
"type_id": "mounting-plate",
"selected_type": "mounting-plate",
"facts": {
"geometry_representation": "rectangular-plate-z-through-holes-v1",
"hole_count": 4
},
"status": "ambiguous"
},
{
"id": "plate-uncertain-absence",
"query": "制作带孔安装板,不能没有沉孔",
"type_id": "mounting-plate",
"selected_type": "mounting-plate",
"facts": {
"geometry_representation": "rectangular-plate-z-through-holes-v1",
"hole_count": 4
},
"status": "ambiguous"
},
{
"id": "enclosure-positive-hinge",
"query": "制作带盖薄壁壳体,有铰链",
"type_id": "covered-thin-wall-enclosure",
"selected_type": "covered-thin-wall-enclosure",
"facts": {
"assembly_gap_mm": 0.3,
"bore_diameter_mm": 3,
"boss_height_mm": 37,
"boss_outer_diameter_mm": 10,
"bottom_thickness_mm": 3,
"fastener_inset_mm": 10,
"geometry_representation": "open-case-four-bosses-independent-flat-lid-v1",
"height_mm": 40,
"length_mm": 120,
"lid_thickness_mm": 4,
"min_wall_mm": 1.5,
"pilot_depth_mm": 12,
"rib_height_mm": 12,
"wall_thickness_mm": 3,
"width_mm": 80
},
"status": "ambiguous"
},
{
"id": "enclosure-positive-after-but",
"query": "制作带盖薄壁壳体,不加螺钉但保留铰链",
"type_id": "covered-thin-wall-enclosure",
"selected_type": "covered-thin-wall-enclosure",
"facts": {
"assembly_gap_mm": 0.3,
"bore_diameter_mm": 3,
"boss_height_mm": 37,
"boss_outer_diameter_mm": 10,
"bottom_thickness_mm": 3,
"fastener_inset_mm": 10,
"geometry_representation": "open-case-four-bosses-independent-flat-lid-v1",
"height_mm": 40,
"length_mm": 120,
"lid_thickness_mm": 4,
"min_wall_mm": 1.5,
"pilot_depth_mm": 12,
"rib_height_mm": 12,
"wall_thickness_mm": 3,
"width_mm": 80
},
"status": "ambiguous"
},
{
"id": "enclosure-absence-and-snapfit",
"query": "制作带盖薄壁壳体,无铰链,保留卡扣",
"type_id": "covered-thin-wall-enclosure",
"selected_type": "covered-thin-wall-enclosure",
"facts": {
"assembly_gap_mm": 0.3,
"bore_diameter_mm": 3,
"boss_height_mm": 37,
"boss_outer_diameter_mm": 10,
"bottom_thickness_mm": 3,
"fastener_inset_mm": 10,
"geometry_representation": "open-case-four-bosses-independent-flat-lid-v1",
"height_mm": 40,
"length_mm": 120,
"lid_thickness_mm": 4,
"min_wall_mm": 1.5,
"pilot_depth_mm": 12,
"rib_height_mm": 12,
"wall_thickness_mm": 3,
"width_mm": 80
},
"status": "ambiguous"
}
]
}
@@ -1,520 +0,0 @@
{
"schema_version": 1,
"engine_build": null,
"description": "局部参考和配合接口只影响路由,不抽取或纠正facts;包含trial03五条原请求及保守反例。engine_build不是运行时准入条件。",
"cases": [
{
"id": "trial03-request010-original",
"query": "构造32齿示意蜗轮,端面模数2,压力角20°,齿宽7,参考2头、轴向模数2、分度直径20的右旋ZA蜗杆,中心距42,环面喉部主半径42、母圆半径8,喉部关于齿宽中面对称;采用允许表示并声明非共轭示意齿面。",
"selected_type": "worm-wheel",
"status": "needs_conditions",
"facts": {
"profile_shift": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 64,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
},
"missing": [
"backlash_mm"
]
},
{
"id": "trial03-request011-original",
"query": "构造ZA圆柱蜗杆,右旋,2头,轴向模数2,轴向压力角20°,分度圆直径20,有效长度28,与轴刚性连接;配套示意蜗轮中心距42。",
"selected_type": "worm",
"status": "needs_conditions",
"facts": {
"axial_length_mm": 28,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"geometry_representation": "za-worm-and-illustrative-throat-wheel-v1",
"helix_hand": "right",
"lead_mm": 4
},
"missing": [
"profile_shift",
"backlash_mm",
"addendum_coefficient",
"clearance_coefficient",
"root_transition"
]
},
{
"id": "trial03-request012-original",
"query": "构造一根独立台阶轴,5个轴段,齿轮孔15,配合两处轴承,轴向定位;按实际安装顺序给出可编辑表示。",
"selected_type": "stepped-shaft",
"status": "matched",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "trial03-request018-original",
"query": "只查询D轴蜗轮:32齿,端面模数2,压力角20°,齿宽7,零变位,配套右旋2头ZA蜗杆轴向模数2、轴向压力角20°、分度径20,中心距42,主喉半径42、母圆半径8,齿顶喉部居中对称;规程示意非共轭。",
"selected_type": "worm-wheel",
"status": "needs_conditions",
"facts": {
"profile_shift": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 64,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
},
"missing": [
"backlash_mm"
]
},
{
"id": "trial03-request019-original",
"query": "只查询一根独立实心台阶轴:5个有序轴段,齿轮安装孔名义直径15对应轴段,支持两处轴承及轴向定位。",
"selected_type": "stepped-shaft",
"status": "matched",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "create-reference-worm",
"query": "生成参考蜗杆",
"selected_type": "worm",
"status": "matched",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "create-one-reference-worm",
"query": "创建一个参考蜗杆",
"selected_type": "worm",
"status": "matched",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "create-qualified-reference-worm",
"query": "构造参考右旋2头ZA蜗杆",
"selected_type": "worm",
"status": "matched",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "two-targets-companion",
"query": "构造蜗杆和配套蜗轮",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "single-companion-target",
"query": "构造配套蜗轮",
"selected_type": "worm-wheel",
"status": "matched",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "also-create-companion",
"query": "配套蜗轮也一起生成",
"selected_type": "worm-wheel",
"status": "matched",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "companion-explicit-creation",
"query": "构造蜗杆;配套蜗轮也一起生成",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "reference-then-create",
"query": "构造蜗轮,参考右旋2头ZA蜗杆;再生成蜗杆",
"selected_type": "worm-wheel",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "another-part-after-shaft",
"query": "制作台阶轴,另做齿轮",
"selected_type": "stepped-shaft",
"status": "ambiguous",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "sole-gear-interface-target",
"query": "修改齿轮安装孔",
"selected_type": "stepped-shaft",
"status": "ambiguous",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "separate-gear-hole-operation",
"query": "制作台阶轴,并在齿轮上开孔",
"selected_type": "stepped-shaft",
"status": "ambiguous",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "joined-interface-target",
"query": "构造台阶轴和齿轮安装孔",
"selected_type": "stepped-shaft",
"status": "ambiguous",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "interface-unrelated-selected",
"query": "制作台阶轴,齿轮孔15",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "reference-wrong-selected",
"query": "构造蜗轮,参考右旋2头ZA蜗杆",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "reference-then-helical",
"query": "构造蜗轮,参考右旋ZA蜗杆,另做斜齿轮",
"selected_type": "worm-wheel",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "reference-contains-creation",
"query": "构造蜗轮,参考生成蜗杆",
"selected_type": "worm-wheel",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "reference-contains-another-creation",
"query": "构造蜗轮,参考要求另做蜗杆",
"selected_type": "worm-wheel",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "reference-alone",
"query": "参考2头右旋ZA蜗杆",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "bare-companion-stays-ambiguous",
"query": "构造蜗杆,配套蜗轮",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "companion-interface-dimension",
"query": "构造蜗杆,配套蜗轮中心距42",
"selected_type": "worm",
"status": "matched",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "companion-later-created",
"query": "构造蜗杆,配套蜗轮中心距42,另生成蜗轮",
"selected_type": "worm",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"axial_module_mm": 2,
"axial_pressure_angle_deg": 20,
"pitch_diameter_mm": 20,
"worm_starts": 2,
"axial_length_mm": 28,
"root_transition": "sharp-simplified"
}
},
{
"id": "double-negation-is-uncertain",
"query": "不能不要蜗杆,构造蜗轮",
"selected_type": "worm-wheel",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "generic-interface-without-main-intent",
"query": "台阶轴以及齿轮孔15",
"selected_type": "stepped-shaft",
"status": "ambiguous",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
},
{
"id": "reference-clause-boundary",
"query": "构造蜗轮,参考参数如下;另造蜗杆",
"selected_type": "worm-wheel",
"status": "ambiguous",
"facts": {
"profile_shift": 0,
"backlash_mm": 0,
"addendum_coefficient": 1,
"clearance_coefficient": 0.25,
"module_mm": 2,
"teeth": 32,
"pressure_angle_deg": 20,
"worm_starts": 2,
"pitch_diameter_mm": 20,
"face_width_mm": 7,
"root_transition": "radial-simplified",
"geometry_representation": "illustrative-helical-involute-with-toroidal-throat-v1"
}
},
{
"id": "query-only-interface-dimension",
"query": "只查询独立台阶轴,齿轮安装孔15对应轴段",
"selected_type": "stepped-shaft",
"status": "matched",
"facts": {
"geometry_representation": "coaxial-solid-stepped-shaft-v1",
"segment_count": 5,
"bore_diameter_mm": 15
}
}
]
}
-75
View File
@@ -1,75 +0,0 @@
# CAD 零件知识库:当前交接
更新:2026-11-12。先读本文及[维护规范](MAINTENANCE.md),再核对实际文件、进程和队列。本文不注入生成模型。[精简前交接快照](../reports/utility-pruning-20261112/handoff-before-utility-v1.txt)保存此前发布和试验细节。
## 球轴承增量(2026-11-12,当前优先读)
用户要求新增球轴承知识,并让画轴承时能选到。已新增`ball-bearing`/0.1.0,摘要覆盖轴承、球轴承、滚珠轴承、深沟球轴承及英文名称,正文仅补开放式单列深沟结构与必要风险:独立内外圈、滚道、球、保持架,避免单环;其他型式不能被擅自替换。引擎源码已核实`parts.insert`的bearing是`Shape::Ring`包络,没有滚珠,不能把插入成功当完整结构。原17通用Skill、工具循环和既有齿轮正文不改。
106项后端回归、冻结包按ID读全文/实际SHA和目录称呼检查通过。用户明确允许本轮更新共享8993,要求先确认所有生成停止;已核对正常登录浏览器的3个共享CAD页面均ready且无turn,后端日志无未结束模型请求后发布。2026-11-12 20:31(Asia/Shanghai)后端PID观察20738;JAR`/Users/lk/Projects/cad-generation-benchmark/experiments/ball-bearing-knowledge-20261112/backend-bearing-v1/vibemake-api-0.0.1-SNAPSHOT.jar`,SHA`80c647921b6c7a6298eb2d914bedffdc1b8c58b4fc1b997d57e6d267f56439b8`。严格从当时运行的varvel backend-v2包增量,仅变更球轴承正文及目录,原16项目录记录、所有class、其他资源、前端和引擎不变,不纳入另一任务未发布的目录/壳体改动。8092/8994未操作。
正式登录接口检查18/18通过(17份全文、1未知ID),3个页面取得的能力目录均含球轴承和各称呼,模型请求0。独立native及当前生产WASM(`745a1240964583102b5bdc4f`)参考均已完成;15×35×11、8球和20×47×14、9球改参分别得到11/12个闭合单壳实体,实际球体重心/体积/均布、两圈滚道切除体积与对应球窝核验通过。新建独立参考页面自动取得新目录,原生文件与两视图保留在外部`ball-bearing-knowledge-20261112/wasm-reference-v1/`;这是维护者回放,不是LLM成绩。详见[球轴承报告](../reports/ball-bearing-knowledge-20261112/README.md)。没有重发任何历史模型题,也没有声称正式助手选文或生成效果已经通过。旧页面需保存后刷新以重新加载能力目录。
## 最新读取流程、失败终态与真实结构参考(2026-11-12)
2026-11-12 18:51(Asia/Shanghai),按用户“改成512k”的要求,**8091/8993的CAD文本及结构化上下文上限已从262144提升至524288字节(512 KiB)并部署**。当前8993后端PID观察29813;冻结JAR为`/Users/lk/Projects/cad-generation-benchmark/experiments/context-window-20261112/limit-512k/backend/vibemake-api-0.0.1-SNAPSHOT.jar`,SHA`58a5d7132abe97710b644faae0b64af9290399be2a64a77f207d9054ad5d6641`。102项读取/协议/客户端/API测试通过,含此前282532字节失败输入、精确512 KiB边界、超过1字节及中文UTF-8计量。新旧包逐项比较仅三个相关class变化,通用Skill、工具、知识正文及其他运行资源一致。4个已登录页面能力接口均返回`textBytes=524288`,模型/推理配置及其他限制未变,模型请求0。前端未重建,现有页面需保存后刷新以重载能力声明;8092/8994未操作。**本次仅提升上限,自动上下文压缩未部署**;探索草稿留在外部`unreleased-compaction-draft/`,不得视为已完成。扩大上限不能保证无限长生成,仍可能触及字节数或历史项数限制;本次未重新生成减速箱。证据见外部`limit-512k/README.md`与`verification.json`,以下backend-v5/PID81365为历史记录。
用户最新明确要求:**原助手从目录自主选文档,目录中文件存在就读取**。生产读取器已移除正则分类、参数条件、状态、activation、构建版本和预登记哈希的拒读门槛;只接收`knowledge_lookup({document_id})`。当前阅读真源为`generation/reading-catalog.json`,16份正文原字节保留,分类和旧policy仅供离线维护。实际SHA只用于内容身份与上下文去重。`off`仅隐藏模型侧工具,`pilot`与`enabled`展示同一读取工具。保留原17个通用Skill和原工具循环。
2026-11-12 17:50已在**8091/8993**部署直读backend-v5,后端PID观察81365;前端PID2522与引擎`745a1240964583102b5bdc4f`未重建。前后端允许分别更新,不配对构建版本。冻结JAR为`/Users/lk/Projects/cad-generation-benchmark/experiments/compound-reducer-20261112/backend-v5/vibemake-api-0.0.1-SNAPSHOT.jar`,SHA`c8fc7edf40ad19010fef26cbee7f3988c798654f13268d845445bf2c2998f624`,101项新读取/协议/客户端/API测试通过;531条旧申请式用例仅离线归档,不能算新接口通过。旧知识调用历史已完成的配对可继续聊天,当前新请求按新Schema读取。
正式登录网页取文预检通过:16项全读、首项另测null/空/任意前后端构建标签、未知ID返回not_found;共21次读取请求,模型请求0。模型、high、原通用工具及原产品限制不变。证据位于外部实验目录`preflight-reader-v5/`。
行星读取复测于18:01自然结束:正式网页原样发送“做一个行星减速器”,OpenAI`gpt-6.1-terra/high`自主读取机构、外直齿轮及内直齿轮三份正文,耗时627.5秒,生成有齿实体;没有无齿占位回退、服务错误或人工修几何。10实体、6组件、0关节、0传动链接,完整减速器未验收。原生文件与检查还发现内齿圈闭合线偏离规程、体积偏大479.0 mm³,以及部分同组件行星轮/销轴不共轴。证据`trial-05-planetary-v5/`及`planetary-reader-v5-assessment.json`保留,旧无齿产物另存`user-planetary-before-v5/`。**18:04用户明确停止行星方向,后续不再开展行星复测或修订。**
18:04继续的三段复合减速箱试验已于**2026-11-12 18:18:36(Asia/Shanghai)自然终止,验收失败**。原完整题目`compound-reducer-20261112/prompt.md`在独立项目`http://localhost:8091/cad/editor/?project=zz8y783ds00k`原样提交;驱动`run-fresh-v5.mjs`、状态`fresh-v5-status.json`、输出`trial-06-fresh-v5/`、计划`plan-v5.json`均保留。耗时831.52秒,21次模型请求、4次知识读取;终态错误为`textBytes=282532/262144`,是请求上下文超限,不是总生成时间截止。21实体、39特征、77参数、2组件、2 occurrence、0关节、0运动链接,不能因网页ready或脚本completed认定完成。原生文件、多视图、请求及`trace-review-v1.json`、`inventory-review-v1.json`已保存;未人工修几何。
**用户最新纠正:停止无真实整机依据的混合结构,寻找已存在的复杂齿轮装配作为参照。**旧双斜齿→锥齿→蜗轮蜗杆题仅作历史失败样本,不自动重跑,不延续行星试验。已核对VARVEL官方RO/RV目录和维护手册,选为后续候选参照的是RO系列三级锥齿—斜齿减速箱、FRO贯通空心输出版本;同一套资料明确一对锥齿与两对斜齿,并有组件图、编号爆炸图。尚未冻结具体订货规格、完整内部参数及装配坐标,不声称原厂精确复刻。参照与失败分析位于`/Users/lk/Projects/cad-generation-benchmark/experiments/real-gearbox-reference-20261112/README.md`及`FAILURE-REVIEW.md`。本轮只整理来源和诊断,**未启动新生成、未修改生产代码或重启服务**。
两个程序问题仅定位,尚未修复:① `list_commands`按`bearing`返回空、按`screw`只找到`joint.screw`,但引擎实际有`parts.library/parts.insert`及6202;检索只搜索id/label/panel/tab、不搜params,助手因而自造轴承环。② 目录/命令说明与执行检查历史持续增长,最终压缩仍不能容纳下一请求。不能只换提示词就认定已解决,也不能把开销全部归因知识库。
网页测试Chrome驱动PID最后观察15626;旧PID23355已断开,PID操作前重核。可用已有`gear-family-expansion-20261111/attach_worker.mjs`给已登录驱动加载限定脚本,不复制登录状态。用户暂不修改生成期间场景交互,相关自动暂停/续作功能不要实现。所有生成仍由外部脚本驱动正式网页模型循环,Codex不能手工修几何冒充模型成功。不提交、不推送、不输出凭据。8994和8092由另一个独立试验使用,本轮未操作。
**以下为此前知识恢复和独立8092/8994的发布记录**,其旧准入、构建约束不适用于上面的新直读流程。操作前核对监听与PID,不把某一个独立冻结包当成共享源码当前策略。
## 当前目标与用户原则
用户要求只保留有用且尽可能少的知识:简单类别不补整套规程;没有额外收益则撤下;具体高风险只给短提示。保留原17个通用Skill、原指令/模型工具循环,不加分类Skill、第二Agent或强制读取步骤。
本轮正在将此原则落实到源码与独立发布,不能仅回复建议。不要重跑已执行模型题、修补被评分产物或覆盖历史失败。Java显式类型,不改SQL,不输出配置、Token等敏感信息。
## 当前知识选择(用户纠正后)
- 此前“20收至5”的齿轮撤下/缩写范围错误,已撤销。不能把未证明跨题目稳定收益当作无收益,不能把五类基础样板的结果扩大到已有齿轮知识。
- 原有13类齿轮/齿条/蜗轮蜗杆及机构规程完整保留;两种人字齿也恢复原0.1.1完整正文。状态仍experimental,不把原失败改成通过,不自动approved。
- 当前15份齿轮相关完整规程+1份XZ筋风险提示,共16份experimental、5份retired、0份approved。
- 五类基础样板继续精简:板、轴、螺栓、壳体不加载整套规程;普通座体不查,明确XZ造筋才返回方向提示。XZ短提示0.2.0模型效果仍未验证。
- 齿轮正文路径/版本/SHA/条件及原证据逐项恢复,原Skill/工具循环保持。[恢复更正报告](../reports/gear-knowledge-restoration-20261112/README.md)为当前决定;此前82%缩减含误删,不作为有效成果。
- 已从上一独立发布的冻结源码完成齿轮恢复,保留本轮原构建约束;不纳入工作区另一任务的版本策略和后续路由改动。正式接口24/24,模型请求0。
## 前阶段已证实,不重做
七类(五基础样板+两种人字)正式A/B14次已结束。A前五类均通过,B板/轴/座体/壳体通过,螺栓B交互锁缺头;两种人字A/B均未通过。B正文只送达轴、螺栓、座体、带槽双斜。座体与壳体B明显更慢,整体未证明收益。正式通过产物独立副本改参5/5,模型请求0。
前阶段v2路由114项后端测试、501条固定例、真实接口193/193通过;这是旧全量政策证据。0.1.1人字文本的模型效果未验证。[正式证据](../reports/five-samples-herringbone-20261112/FORMAL-V1.md)、[副本改参](../reports/five-samples-herringbone-20261112/EDITS-V1.md)、[原v2发布](../reports/five-samples-herringbone-20261112/ROUTING-V2.md)。旧齿轮v2-v5亦已归档,不重发;[历史覆盖](../reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)。
## 实际环境与发布边界
- community:`/Users/lk/Projects/vibemake相关项目/community`,唯一知识真源`knowledge/cad-parts`。
- 本轮外部证据:`/Users/lk/Projects/cad-generation-benchmark/experiments/utility-pruning-20261112`。
- 用户已确认将齿轮副名称合并一起验证发布,并使用独立8092/8994保留原引擎。共享8091/8993由其他任务管理,不能停止/重启。
- 精简前现场:8092前端PID8145、8994后端PID8135、已登录只读验证浏览器驱动PID10989。PID为临时观察值,操作前必须核对命令和监听。
- 精简前JAR在`.../five-samples-herringbone-20261112/frozen-backend-samples-v2/`,SHA `4b7aaa5bd886ccba1ea34b1be1be0789592ebc66ebb1c04f176f0dcab1b7185a`。不能覆盖该目录。
- 引擎`f3d62ce93f72db42f311a46e`原字节保留。按用户2026-11-12的明确要求,前端、后端和引擎允许独立更新;构建号不再作为知识加载门槛,也不再维护构建白名单。历史构建号只供诊断和证据检索;类型、条件、状态、权限和正文完整性校验保留。原Skill SHA `026284eff26c8b4be1f7864219921a54828338973317c291f7e862b1cc452ef7`。
- 浏览器正常登录,不复制登录存储/Token。只读接口验证禁止`/chat`,模型请求必须0。旧PID23355的浏览器已断开,不再attach。
- JDK21:`/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home`。启动器`scripts/java-with-env.py`字面读.env,不能source或回显。
## 当前独立发布与下一步
2026-11-12 17:31(Asia/Shanghai)核对:齿轮恢复包已在独立8092/8994运行。后端PID观察为65032,前端PID8145,已登录验证浏览器驱动PID10989;操作前仍需核对命令和监听。
JAR:`/Users/lk/Projects/cad-generation-benchmark/experiments/gear-knowledge-restoration-20261112/frozen-backend-restoration-v1/vibemake-api-0.0.1-SNAPSHOT.jar`,SHA `ab1f2eb6c890936989518598811125f2e85f762cb4cf48b7dbbb47545c901f14`。来源外部实验目录的`build-source-v2`及`source-freeze-v2.json`,121项后端测试通过;15份齿轮相关规程的版本/路径/SHA/条件及原证据与精简前一致。正式接口24/24通过,通用工具、Skill、原引擎及已观察前端文件不变,模型请求0。[恢复报告](../reports/gear-knowledge-restoration-20261112/README.md)、[最终核验](../reports/gear-knowledge-restoration-20261112/verification-v1.json)。
本轮独立包沿用户此前确认的发布范围保留原构建约束,不含工作区另一任务的取消构建限制/后续路由修改;不要将当前共享工作区自动当作已发布源码,也不要回滚对方改动。原5份错误精简包SHA `2550956bef3c00956d0d2ea5b41b01e499875dee0eca95b660df89a604b2ffbc`已被替换,仍留档为历史;原samples-v2完整包也保留。
当前纠正已完成。原有齿轮知识保留;只对五类基础样板按实际需要精简。`experimental`表示准入层次,不是没有收益,未证明稳定统计提升也不能作为批量撤下依据。人字齿已有失败和效果待证边界继续保留,XZ短提示模型效果仍未测。不自动重发旧模型题,任何后续模型验证须独立版本/cohort、保留旧失败。
@@ -1,246 +0,0 @@
# CAD 零件类别补全:工作方法与验收规范
本文件面向维护者和接手项目的编程助手,**不注入生成模型,不增加正式助手步骤**。运行接口以[项目维护入口](../../../docs/cad-part-knowledge.md)为准;生产阅读真源为[reading-catalog.json](reading-catalog.json)。[catalog.json](catalog.json)的类型/属性与[policy.json](policy.json)的旧准入记录仅供离线维护和历史复现。当前进度见[对话交接](HANDOFF.md)。
目标是提高原版CAD网页助手的生成质量或效率,积累“在现有工具中怎样构造、怎样避免已观察错误、怎样检查”。不能把文档数量、提示词篇幅或文件可读当成最终生成效果。
**当前原则(2026-11-12用户纠正后)**:原助手从短目录自主选文档,目录内文件存在就读取。后端不按分类、参数、状态、预登记哈希、构建或关键词拒读,不把知识库当工具能力白名单。原有齿轮规程已恢复;不能仅因尚未证明稳定收益批量撤下。普通基础样板继续原通用Skill;收录是维护者的编辑选择,正文中的条件和近似由助手结合需求理解。见[恢复更正](../reports/gear-knowledge-restoration-20261112/README.md)。
## 已确定的产品约束
- 知识源只维护在community的`knowledge/cad-parts/`,旧独立路径不提供兼容层。
- 保留原17个通用Skill、指令和原模型工具循环。仅提供`knowledge_lookup({document_id})`,不新建Agent、分类模型调用或强制预检步骤。
- 短目录包含稳定阅读ID、名称、用途和文件映射;不预加载全库正文,不要求用户使用规定词,也不以query二次否决模型选择。
- 前端、后端和引擎允许独立更新。构建号只作诊断,实际SHA256只作内容身份与去重,不构成读取许可。
- 目录或文件缺失返回`not_found`。这不代表工具不能做;继续原通用技能并保留用户要求。除用户明确要求运动学占位,不得将实际齿轮擅自降为无齿圆柱。
- 机构中的齿轮可按需分别读取机构、外直齿和内直齿文档,不强制一次读完所有部件,也不为知识库新增传动方案决策流程。
- 孔、键槽、轮毂等按用户要求选配,示例不能变强制结构;参数约束和近似写在正文,不要求模型为读取补参或改值。
- 复杂齿面允许明确标注的结构/参数近似,不声称制造级共轭、接触精度或承载认证。
- 正式模型试验由外部脚本驱动community网页助手,模型和工具循环不经过Codex内部;确定性参考与事后只读审计不能算模型生成成功。
## 每份文档维护什么
阅读目录的`id`当前沿用既有工程type ID作为文件别名,映射到一份canonical Markdown;记录名称、短用途、路径、原`source_doc_id`和版本。正文返回时计算实际SHA256,不要求预登记哈希。
正文只保留对构造有作用的知识:参数、基准、单位和表示边界;必要公式和原工具操作;草图/实体连接、需避免的错误;可据真实产物检查的尺寸、齿形、接口与编辑传播。分类背景、来源长文、完整审计与维护规则留离线。选配变化通常不新建文档,不重复通用Skill。
## 一次扩展的工作顺序
### 1. 先记录缺口
保存用户需求和真实失败,区分“未识别类型”“没取到正文”“取到了但没有遵循”“几何方法本身不可执行”“服务/测试中断”。一次仅针对已确认的瓶颈修改。正文没有送达的案例不能证明正文无效;有闭合实体也不能自动证明形状正确。
### 2. 用现有引擎走通参考
在真实编辑器完成正确实例,并保存原生设计、参数、工具过程、实际检查与截图。再改变至少一组关键参数检查公式和策略是否只适配一个固定实例。当前复杂齿面必须明确允许的近似;参考回放通过仍不计为模型生成成功。
### 3. 写有效文档并登记阅读目录
先决定是否需要新增正文;答案可以是“不增加”。已有通用Skill足够时停止扩写;具体风险可以只写短提示,在目录说明用途。保留完整有效构造单元,不把提示冒充完整教程。新修订仍独立标记效果未验证,不继承旧版本模型成绩;也不因尚未证明稳定收益自动删除已有齿轮文档。
正文放在`generation/candidates/`,在`reading-catalog.json`登记文件映射和短用途。参数条件、近似限制、参考构建和检查要求写在正文或离线证据,不作为读前审批。属性应说明对象、单位和基准,尤其是法向/端面/轴向、半径/直径、底厚/总高和当前件/参考件。
保持公式、命令和检查为完整有效单元,不为缩短字数截掉关键连接或必要边界,也不拆成必须串行读取的碎片。
### 4. 检查读取契约与目录
逐项检查阅读ID、canonical文件映射、短摘要、完整原文返回和实际SHA身份。当前Schema只有`document_id:string`,无ID枚举准入;不再提交query/type_id/facts。未知ID或文件不可读取返回`not_found`,不得加入分类、状态、条件、activation、预登记哈希或部署版本门槛。
文档选择质量通过正式助手测试观察:名称变体、否定、参考部件、多部件和后续修改应由助手理解,不继续为自然语言补后端正则。文件能读取不等于几何已正确生成。
旧531条固定路由样例与旧源码由`evals/archive/reader-contract-before-v5/manifest.json`索引,属于旧申请式协议历史,不计算为新读取器通过。旧对话已完成的knowledge调用封套可以继续传递并保持调用/结果配对,不重新执行,也不向当前模型展示旧Schema;新读取仍只用document_id。
### 5. 冻结后测试正式助手
A关闭知识,B按需开放知识。冻结共同题目、模型与思考设置、原指令与通用Skill、工具、引擎、前端、后端JAR和产品原有预算。外部脚本只提交需求、捕获过程和检查,不代替正式模型或工具循环,不给题目附加规程,不修补被评分模型。
在途测试不部署新源码。新修正只进入另一个明确编号的版本;新一轮继续保存自己的指纹。补测独立编号,保留原失败,不能以补测成功替换主对照。测试脚本是否有截止时间与产品原有单次请求/上下文限制分别记录。
每题至少保存以下材料;缺失项明确注明:
| 材料 | 用途 |
| --- | --- |
| 逐字题目、A/B开关、部署指纹 | 判断两组是否可比 |
| 网络/工具过程、真实知识请求和返回 | 判断正文是否送达及实际版本 |
| 终态服务提示与时间 | 区分服务异常、产品预算和正常结束 |
| 原生设计、实际检查与只读采样 | 判断几何和参数,不只看截图 |
| 多视图截图 | 保留外观对比与错误现场 |
| 审计结论与限制 | 分开记录已检查项及仍未验证项 |
不保存私钥、登录Token或带密钥的请求头到可提交证据。原生设计和截图涉及项目数据时按项目既有存储方式处理。
### 6. 按证据决定保留、修订或准入
服务终态、正文交付、实际几何、参数可编辑、完整编辑传播和生成收益分别判断,不用其中一个替代另一个。不同有效建模策略应接受同一套最终几何检查;源草图的形态不是最终几何的必要条件时,单独记录,不作为拒绝理由。
检查前先确认测量接口的来源和精度,报告保存所用接口、采样数量、容差和设计身份。当前引擎的 `model.edges.mid/length` 来自显示折线,不能作为精确曲线内点或弧长;`model.faces` 的面积、重心及平面法向也不能一概解释为精确曲面度量。`inspect.curvature_comb` 的边/面脚点属于实际几何记录的有限求值采样,源草图脚点则只证明源曲线。实体体积、重心和包围盒必须结合 `measured_by` 与对应实现解释。任何有限采样都不自动证明连续全域误差、共轭接触或制造能力。
原页面关闭后如需补证,可以原样重载保存设计,只做只读检查;必须核对原输入、规范文档、完整参数/特征及重载前后度量。补证另存为重载副本证据,不冒充原页面同一 revision;若核对不一致,就不能并入原结论。发现旧审计误读时保留原文件,另写语义更正,不通过覆盖历史数据制造通过。
参考、模型对照与关键参数迁移分别保留证据,不把单次并发耗时差当稳定加速比。旧`experimental/approved/retired`标签仅作离线历史;目录内文档均可读。`pilot`与`enabled`展示同一工具,`off`只控制是否向模型展示工具,不对已请求的目录文件增加读取门槛。
结果变差时先定位是哪一层,再决定缩减正文、修订方法、修路由或撤回文档。避免在没有送达正文的情况下盲目增加提示词。维护者可修订目录中的文件选择,但保留原文、失败证据和版本来源。
## 代码与资料分别改在哪里
以下路径相对于 community 根目录;只改当前任务需要的文件。新增一个已有接口能表达的类别,通常只涉及目录、规程、政策和测试,不应顺带重写通用 Skill 或前端流程。
| 位置 | 职责 | 维护注意 |
| --- | --- | --- |
| `knowledge/cad-parts/generation/reading-catalog.json` | 助手可自主选择的阅读ID、短用途和文件映射 | 生产读取真源,无读前审批条件 |
| `knowledge/cad-parts/generation/catalog.json` | 离线类型、别名、父类和属性 | 不据关键词否决读取 |
| `knowledge/cad-parts/generation/policy.json` | 旧状态、条件、哈希和证据历史 | 不参与生产读取 |
| `knowledge/cad-parts/generation/candidates/*.md` | 按需返回的实际知识正文 | 公式、工具、边界和检查保持完整 |
| `knowledge/cad-parts/evals/` | 当前读取契约样例和旧路由历史 | 明确区分新接口测试与历史字节保留 |
| `vibemake-service/src/main/java/com/linkerbot/vibemake/service/cad/ai/CadAiKnowledge.java` | 按ID读目录文件,计算实际内容身份 | 不做分类、条件、状态、哈希或构建准入 |
| `vibemake-service/src/main/java/com/linkerbot/vibemake/service/cad/ai/CadAiTools.java` | 原工具、单一读取Schema和短目录 | 不预加载正文,不加分类模型调用 |
| `vibemake-service/src/main/java/com/linkerbot/vibemake/service/cad/ai/CadAiProtocol.java` | 原工具协议和已完成旧history封套 | 不执行历史调用,不放宽当前新读取Schema |
| `vibemake-service/src/test/java/com/linkerbot/vibemake/service/cad/ai/CadAiKnowledgeTest.java` | 直读、实际SHA、缺文件、无门槛回归 | 旧531路由例不冒充当前通过 |
| `vibemake-service/src/main/resources/cad/ai/skills.json` | 原17个通用Skill | 保留原文并记录实际字节哈希 |
| `knowledge/cad-parts/references/` | 分类、长文、来源和完整示例 | 离线默认不返回生成模型 |
| `knowledge/cad-parts/reports/` | 图文报告、错误更正和证据 | 不覆盖原失败 |
网页宿主、引擎及外部测试脚本的实际仓库路径见[交接文档](HANDOFF.md)。若任务需要修改引擎或宿主,应先读取相应仓库的 `AGENTS.md` 和适用技能,不沿用 community 的规则冒充其他仓库的规则。
## 开始一个类别前,先写这份小任务单
任务单存入对应计划或报告,而不是追加到模型上下文。以下是字段模板,不是已经完成的事实:
```yaml
type_id: <稳定类型 ID>
object_scope: <当前件或机构,必需结构与选配结构>
supported_variant: <明确齿制/形态/参数范围>
representation: <精确构造部分、近似部分、未覆盖部分>
observed_failure: <原始需求、实际失败、证据路径>
hypothesis: <这次文字或路由改动具体解决什么>
engine_build: <实际网页构建 ID>
reference_cases: <标准实例与至少一组参数变化>
formal_cases: <完整需求、常用表达、边界/范围外与编辑需求>
acceptance: <最终结构、数学关系、接口和参数编辑的检查>
excluded_claims: <本轮不能证明的制造/接触/统计结论>
```
先界定对象再归类。以下三种情况分开:
- 同一类型的选配变化:例如外直齿轮有孔/无孔、带/不带轮毂,通常不新建类别。
- 不同几何构造方法:例如直齿与斜齿、外齿与内齿,需要明确类型和适用域。
- 多零件机构:机构规程只描述部件关系、坐标与接口;部件造型知识仍按需读取,不把所有部件长文预装到机构正文里。
## 短规程的正文模板
新类别可按下面的顺序写;根据实际需要删减标题,不机械补空章。正文无需复制维护流程、分类来源、测试历史或默认完整样例。
```markdown
# <类型>:<构造方法与版本>
<适用对象、明确近似和不支持的变体,用一小段写清楚。>
## 参数与坐标
<必要输入、单位、轴线、基准;区分当前件与参考件、半径与直径。>
<必要派生公式及其定义域;不虚构尺寸或标准规格。>
## 当前工具构造
<关键工具 ID、参数表达式、实体连接顺序、目标体与草图闭合关系。>
<易抄错且会导致真实失败的步骤可以给完整短 JSON。>
<孔、槽、轮毂仅按用户需求添加。>
## 检查
<最终实体/部件数、尺寸、曲线/曲面关系、位置与接口。>
<需要实际采样的项目,以及采样不能证明的事项。>
<关键参数修改后应如何重建和检查。>
```
正文的删减标准是作用,不是机械字数上限:每一段应能说明“删掉后可能重现哪种具体失败”。若只是介绍零件常识、重复原 Skill 或展开来源背景,放到离线资料。反之,不能为了短而删掉必要连接公式或适用条件。
实际经验:蜗轮根部圆弧的极坐标端点被模型改成错误乘法,导致整圈无法闭合。有效修订是引入明确的下一扇区端点参数和对应短工具调用,而不是再加一段“蜗轮一般长什么样”。这次修订仍须真实模型复测,不能因公式写得更清楚就预先宣布成功。
## 文档选择与上下文的最低要求
1. 助手根据当前任务选文档,区分目标、参考、否定对象和已完成部件,不要求用户说规定词。
2. 目录摘要短而明确,只含文件ID、名称、用途和必要边界;正文按需读,不预装整棵分类树或所有规程。
3. 参数和近似由助手结合需求理解;读取器不抽取、补齐或修改几何参数。
4. `matched`必须包含实际文件完整正文;`not_found`不是CAD能力不足,也不是擅自省略轮齿的理由。
5. 同轮按原文档ID、版本和实际SHA去重,正文裁剪后可重读;新用户轮次按原机制处理过期引用。
6. 工具目录、Schema、拓扑结果和恢复历史也占上下文;预算耗尽时统计实际来源,不只归因于知识正文。
## 故障出现后如何决定改哪里
| 已观察的证据 | 下一步定位 | 不应直接得出的结论 |
| --- | --- | --- |
| 模型没查知识工具 | 查询时机、可见 Schema、需求是否属于当前支持对象 | 文档正文无效 |
| 读取返回not_found | 请求document_id、阅读目录和文件打包路径 | CAD工具不支持该形状,或应把齿轮变成无齿圆柱 |
| 正文已送达但命令偏离公式 | 对比实际调用和正文,缩小最易误写的操作表达 | 检索再加一次即可解决 |
| 确定性参考也失败 | 工具能力、公式、连接方法和定义域 | 是 LLM 执行能力导致 |
| 多个实体但位置/孔轴错误 | 共享接口参数、局部/世界坐标、相位与变换 | 只要外观像机构就算通过 |
| 没产物且服务报错 | 请求终态、服务诊断与当时产品限制 | 规程齿形本身不正确 |
| 大工具结果被拒或上下文耗尽 | 请求历史中的目录、说明、检查结果和重复恢复 | 等于知识正文太长 |
| 审计失败与截图不符 | 设计身份、名称映射、测量来源、检查器适用策略 | 放宽容差或修补模型后算原结果通过 |
一次只改有证据支持的瓶颈。名称映射错误、测量语义更正与模型几何修正分别记录。若审计器最初只支持一种构造,需补同一套最终几何检查接受其他有效策略,不能强迫模型复制参考时间线才给通过。
## 运行验证的顺序与命令
以下是维护检查,不是生产助手新增步骤,也不会调用生成模型。所有命令先确认所在仓库。
在 community 根目录使用 JDK 21:
```bash
mvn -q -pl vibemake-api -am \
-Dtest=CadAiKnowledgeTest,CadAiSampleKnowledgeTest,CadAiKnowledgeUtilityTest,CadAiProtocolTest,ArkCadAiClientTest,CadAiTest \
-Dsurefire.failIfNoSpecifiedTests=false test
```
若改动了离线分类、族文档或离线规则,在 `community/knowledge/cad-parts` 执行:
```bash
python3 -m cad_knowledge check
python3 -m cad_knowledge evaluate
python3 -m unittest discover -s tests -v
```
这些 Python 命令检验的是保留的离线资料,不能代替 Java 正式路由或网页生成。源码测试通过后,**先确认没有在途试验**,才能打包:
```bash
mvn -q -pl vibemake-api -am \
-Dtest=CadAiKnowledgeTest,CadAiSampleKnowledgeTest,CadAiKnowledgeUtilityTest,CadAiProtocolTest,ArkCadAiClientTest,CadAiTest \
-Dsurefire.failIfNoSpecifiedTests=false package
```
打包本身就会改变 `target` JAR,不能只把“不要重启”当作冻结要求。发布前保存独立冻结副本、哈希、题目和部署记录;单独核对实际监听服务与启动文件。新包启动后先通过登录后的正式知识接口重放典型及完整条件查询,核对返回正文版本和哈希,再开始模型试验。静态测试、接口取文和模型生成是三层证据。
并行任务修改同一源码或评测时,测试前后固定文件边界,确认打包/冻结使用同一版本;不要覆盖对方修改或悄悄丢弃新增案例。正式对照需要保存各自部署字节,必要时使用独立端口。测试冻结用于保证证据可比,不是产品运行时的前后端版本锁,也不要求用户同步发布。独立浏览器仍正常登录,不复制登录存储。
正式测试采用现有外部网页驱动,具体运行入口以交接和当期 cohort 为准。历史六族 CLI 有自己的模型循环,不能冒充正式网页助手。原测试账号的登录会话由原浏览器进程持有,不导出登录凭据;进程失效后按正常登录流程恢复,不从历史文档复制凭据。
## 每类收尾的检查清单
- [ ] 对象、变体、精度层次、未覆盖项和选配边界已写明。
- [ ] 有当前引擎的参考原生设计、实际工具记录、截图及至少一组参数变化。
- [ ] 短正文与参考方法一致,没有靠固定示例尺寸才成立的隐藏前提。
- [ ] 类型、属性、政策、正文路径、文档版本、哈希和引用可校验;构建号仅记录,不设置加载门槛。
- [ ] 新回归保留旧例,确实覆盖本次原始失败,不靠放宽规则过关。
- [ ] 正式模型保存题目、冻结指纹、知识真实返回、终态、设计和截图。
- [ ] 最终几何采用已确认来源的度量和实际采样,审计器不偏袒某种时间线。
- [ ] 参数修改和重建/接口传播单独有证据;未执行则明确“未验证”。
- [ ] 失败、重试、补测、服务异常与测试中断均保留,没有跨版本拼 A/B。
- [ ] 无收益且无具体风险时已退出运行时加载;必要的风险提示仍为 `experimental`,不用目录齐全或参考通过自动准入。
- [ ] 更新证据入口和交接文档;运行状态注明采集时间,不把临时 PID 当成永久配置。
“类别已补全”应同时写明完成层次,例如“文档与参考构造完成、路由已验证、模型生成仍不稳定”。如果某类实测失败,本轮可以完整交付该失败及改进方向,但不能标记为生成效果已通过。
## 已形成的证据边界
- 9类单体、4类静态机构已有实际参考构造及相应独立检查;这与正式模型的结果分开。
- 复杂锥齿与示意蜗轮不升级为制造级共轭齿面,静态布局不升级为全周期接触/运动无干涉。
- v2模型试验与后续v5/v6/v7修正分开;v7另行冻结部署为v3,保存109项后端测试、268条路由和59条正式接口重放记录。取文检查仍不能代替模型几何。
- 正文去重不代表整体上下文一定小:工具Schema、拓扑结果、命令发现和错误恢复也占上下文。字符数与供应商token数分开记录。
当期证据入口以[对话交接](HANDOFF.md)为准;已有[扩展阶段报告](../reports/gear-family-expansion-20261112/README.md)、[v2 正式题目与截图](../reports/gear-family-expansion-20261112/FORMAL-AB-V2.md)及[v3 独立补测](../reports/gear-family-expansion-20261112/FOLLOWUP-V3.md)。本文不另维护一份逐题成绩表。
2026-11-12用户授权沿用本工作流补齐其余五个旧样板,并确认同时覆盖无槽连续人字齿与带中央退刀槽双斜齿;两者独立登记,不属于未经确认的范围扩张。任务及证据见[七类补全报告](../reports/five-samples-herringbone-20261112/README.md),仍须逐层报告参考、取文、正式模型、改参与收益,不因新增文件而自动准入。
## 新对话如何接手
先读本文件和 `HANDOFF.md`,再按问题读取相关类别正文、源码和证据;不要一次读取全部历史。先核对真实进程、队列、终态文件和冻结哈希,后决定继续哪个环节。不要从“上个对话说正在运行”推断进程现在仍活着,也不要从状态 JSON 单独推断模型已停止。
接手后首先复述三件事:当前目标、已证实的结果、下一步要补的证据。未完成试验先收尾,不重复发送;确定需要改动才创建新的版本或 cohort。每次结束会话前更新 `HANDOFF.md`,并保留详细结果在对应报告,避免交接文件无限膨胀。
-53
View File
@@ -1,53 +0,0 @@
# 生成知识:由助手选择文件,按需读取
知识源已归入 community 的 `knowledge/cad-parts/`,旧独立路径及其兼容链接已删除。CAD网页助手使用只读`knowledge_lookup({document_id})`:助手从[阅读目录](reading-catalog.json)自主选文档,文件存在就返回原文,不再先申请分类、补参数或通过准入检查。首轮真实网页 A/B 和组合结构结果见[齿轮实测与截图](../reports/gear-integration-20261111/README.md),配置与接口见[项目维护入口](../../../docs/cad-part-knowledge.md)。
原版通用 Skill 全部保留。知识库入口 `SKILL.md`、下述维护规则、分类与证据不常驻注入;助手只需要简短的查询说明,以及命中后真正有用的正文。重复与过期知识由程序处理。
新增类型和后续修订统一使用[类别补全工作方法与验收](MAINTENANCE.md);新对话先读[现场交接](HANDOFF.md)。两份文档只供维护者使用,明确如何区分参考回放、正文送达、实际几何和收益证据,不增加模型侧的读取步骤。
知识库仍有用途:分类用于定位,属性用于参数校验,历史资料用于分析。但这不代表整份族文档值得放进每次生成上下文。此前长文方案没有证明收益;无效内容占比、与工具不对应、重复要求和示例锚定都是待检验原因,不能仅凭变差就认定是 token 多导致。
现在把实际生成文本单独存放。`references/` 的分类树、YAML 参数字典、来源、长推导、完整示例与通用解释均保留供离线使用,默认不注入。历史 `context` API 与旧六族测试程序保持可复现,但不作为正式助手的推荐接入方式。
## 文本保留标准
一段补充应解决实际观察到的生成错误,并说明在当前工具中怎样操作。例如齿轮候选保留角度单位转换、单齿闭合、先 Join 后特征阵列、键槽连通及实际坐标检查;这些直接对应原失败。零件是什么、分类历史、重复的常识、未经试验的建议不进入生成补充。篇幅短是手段,最终依据是生成结果与耗时。
候选规程先在同版本真实引擎回放,再保持正式助手的模型、思考程度、指令、技能、工具、题目及引擎一致,比较 A 无补充与 B 仅追加规程。记录原生设计、过程、用时与截图;更换齿数或模数检查迁移。每次失败均保留,不用重试覆盖失败。服务异常且没有执行建模的案例单独归类,不计作几何质量失败。
生成收益记录在独立试验与人工证据索引中,几何结论需要审查产物。旧`policy.json`中的`approved`、`experimental`和证据字段只保留维护与历史意义,不控制生产读取。单次变好不足以宣称所有齿轮或所有模型都会提升;扩大适用范围需要新证据。若质量不提升且更慢,则缩减、修改或撤回该文本。
## 当前状态
2026-11-12新增[球轴承短规程](candidates/ball-bearing-open-deep-groove-v1.md),阅读ID为`ball-bearing`。目录覆盖轴承、球轴承、滚珠轴承、深沟球轴承及英文名称,保留原助手自主选文。针对“单环无滚珠”和内置标准件仅包络的实际缺口,补充独立内外圈、滚道、滚珠与保持架;不扩写所有轴承类别。源码、共享8993增量发布、参考构造与效果边界见[球轴承报告](../reports/ball-bearing-knowledge-20261112/README.md)。以下状态标签保留此前齿轮恢复的历史含义。
当前目录0.3.0保留28个工程类型、53个登记属性。按用户纠正,**原有13类齿轮相关规程完整保留**,两类人字齿也恢复原完整正文;仅精简五类基础样板。当前15份齿轮相关完整规程+1份XZ筋风险提示,共16份experimental、5份retired、0份approved。此前收至5份的齿轮撤下/缩写决定已撤销,不能把“未证明稳定收益”当作“无收益”。见[恢复更正](../reports/gear-knowledge-restoration-20261112/README.md)及[当前交接](HANDOFF.md)。
板、轴、螺栓、普通座体和壳体沿原通用Skill;仅XZ造筋按需提示方向风险。原齿轮[收益和覆盖记录](../reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)、七类[正式A/B与失败](../reports/five-samples-herringbone-20261112/README.md)完整保留,不重发模型题或把未通过改成通过。`experimental`是历史实验状态标签,并非无用结论,也不再作为读取门槛。下述外直齿首轮记录保留历史背景。
第一版[逐点展开规程](archive/involute-spur-gear-expanded-v1.md)已归档且未列入当前阅读目录(历史标签`retired`):24齿生成的工作齿廓正确,但缺键槽;32齿迁移时模型漏掉半径增长项,生成一圈圆包,不能准入。历史文件保留用于复现。
当前候选为[第二版方程曲线规程](candidates/involute-spur-gear-equation-v2.md),状态 `experimental`,原始验证引擎 build 为 `5707e4ae25621c4a32c40108`,该构建号仅记录历史证据。2026-11-12 按用户要求取消部署版本匹配,前后端可以独立更新,不再按 `compatible_builds` 拒绝知识。它使用原有 `sketch.equation_curve`,避免模型展开几十个采样点;20/24/32齿已完成真实引擎参考回放,LLM试验独立记录。尚不宣称全部生成流程已稳定通过。确定性回放是验证操作可执行,不能冒充 LLM 生成成功。
第二版真实网页助手试验中,20齿完整生成并通过实际曲线采样、体积与截图复核;24齿完成齿圈和轮毂后服务中断,未切孔槽;32齿完成正确单齿后服务中断,未阵列。三个单齿曲线均与解析渐开线相符,但整题完成尚不稳定;不将局部收益夸大为全流程稳定提升,保持实验状态。完整过程、原生设计和截图见独立项目 `cad-generation-benchmark/reports/gear-recipe-pilot-20261111/`。
集成后的新一轮正式网页测试单独记录:最终同版本 20 齿题 A 未生成实体,B 只读取一次 v2 后完成轮毂、孔、键槽和正确齿形;20 齿与独立轴的组合也通过两实体及齿形复核。另有较早后端的 24 齿纯圆孔、无轮毂/键槽成功样例,不混入最终配对。测试未人工修补几何;同版本质量收益已在这一题观察到,仍不估计总体成功率或速度。详细证据及两次无效接入试运行保存在[本轮报告](../reports/gear-integration-20261111/README.md)。
## 网页按目录读取
运行时真源为[reading-catalog.json](reading-catalog.json),当前登记17份原文。每项包含ID、名称、短用途、Markdown路径及原文档标识/版本;目录摘要在工具说明中提供给原助手,正文按需读取。模型调用:
```json
{"document_id":"involute-spur-gear"}
```
读取器仅按目录ID定位文件;存在则返回原文,不比较关键词、分类、参数、文档状态、构建版本或预登记哈希。适用范围与近似限制由助手结合正文理解。文件未找到返回`not_found`,不能据此认定工具没有该建模能力,也不能擅自省略轮齿。
同一轮有效上下文去重,正文被裁剪后允许重读;原始记录与推理状态保留。实际SHA只用于内容身份与去重。`CAD_AI_KNOWLEDGE_MODE=off`关闭模型侧工具展示,`pilot`与`enabled`展示同一阅读工具,不再按状态区分文件。
## 离线资料与历史边界
`catalog.json`、`policy.json`、族长文、参数字典与历史检索用例继续用于维护和复现,不作为网页读取门槛。Python `generation-context`保留原离线政策行为,与新的网页直读接口分开,不能用它的跳过原因解释生产助手是否能读文件。它的`--engine-build`仍仅是诊断标签。
旧申请式路由的源码和固定案例已归档;对应历史成绩不算新接口测试。新增目录文件应核对实际读取和上下文去重,再由正式网页助手生成并保留原生设计和截图。读取成功、参考回放成功与生成效果提升分别记录。发布现场见[交接](HANDOFF.md),接口与测试命令见[项目维护入口](../../../docs/cad-part-knowledge.md)。
@@ -1,40 +0,0 @@
# 外啮合零变位直齿轮:当前编辑器操作参考
适用:压力角20°、零变位、零侧隙、齿顶高系数1、顶隙系数0.25,简化径向齿根。尺寸取用户输入,不套示例尺寸。此规程已在当前引擎回放;模型读取后的收益正在试验。
## 参数和角度
`parameters.add` 必须显式传 `unit`:模数及半径、齿宽为 `mm`;齿数和无量纲滚动参数为 `""`;角度为 `deg`。不使用单位保留名 `m`。以下变量名是推荐参数名,需先创建再引用。
```text
gearModule = 用户模数 [mm]
gearTeeth = 用户齿数 [unit=""]
gearPressure = 20 deg
gearWidth = 用户齿宽 [mm]
pitchRadius = gearModule*gearTeeth/2 [mm]
baseRadius = pitchRadius*cos(gearPressure) [mm]
tipRadius = pitchRadius+gearModule [mm]
rootRadius = pitchRadius-1.25*gearModule [mm]
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad) [deg]
tipRoll = sqrt((tipRadius/baseRadius)^2-1) [unit=""]
```
无单位数传给 `sin/cos` 会按度解释;弧度数必须乘 `(1 rad)`。`atan(t)` 返回带单位角度,转成无单位弧度数必须除以 `(1 rad)`,不可直接算 `t-atan(t)`。
## 先正确单齿,再阵列
1. `solid.cylinder` 建齿根盘:`radius:"rootRadius", height:"gearWidth", operation:"new", body_name:"Gear", name:"GearRoot"`。
2. `sketch.create {plane:"XY",name:"GearToothProfile"}`,构造关于X轴对称的单齿。令 `t_i=tipRoll*i/N`,i=0…N;`r_i=baseRadius*sqrt(1+t_i^2)`;**上侧半角** `a_i=toothBaseAngle-(t_i-atan(t_i)/(1 rad))*(1 rad)`;上侧点 `[r_i*cos(a_i), r_i*sin(a_i)]`,下侧点取Y负号。应从基圆向齿顶收窄,不能把减号改成加号。
3. 用 `sketch.line {points:[...],infer:false}` 按顺序连接:下侧齿根点 `[rootRadius*cos(toothBaseAngle),-rootRadius*sin(toothBaseAngle)]` → 下侧基圆点 → 下侧i=1…N。所有坐标保留上述参数表达式;不能只填固定数值。
4. 用 `sketch.arc.three_point {start:下侧齿顶点,through:["tipRadius",0],end:上侧齿顶点}` 连接齿顶;再用 `sketch.line` 依次连接上侧i=N…0 → 上侧齿根点 → 最初下侧齿根点。最后一步已有首点时不要再加 `closed:true`,避免零长边。齿根两段是明确披露的径向简化。
5. 工作齿廓折线分段数N须满足 `tipRadius*(tipRoll/N)^2/8 <= 允许误差`;这是参数曲线二阶导数上界给出的插值距离界。当前试点模数1~4、齿数18~60时,每侧12段满足0.03mm;其他范围重新算N。不要只用3段并自称误差通过。
6. `sketch.solve` 必须为一个闭合区域且无失败,随后 `sketch.finish`。检查实际草图点坐标;两个意外区域通常说明自交,应修草图,不能随便选 `[1]` 继续。
7. `solid.extrude {sketch:"GearToothProfile",distance:"gearWidth",operation:"join",targets:["Gear"],name:"GearTooth"}`。该闭合单齿的底边弦位于齿根圆内部,与齿根盘有实体搭接。
8. `solid.pattern.circular {features:["GearTooth"],axis:"Z",count:"gearTeeth"}`。**阵列已经Join的单齿特征**,现有引擎会重复Join,保持一个实体;不要先建24个独立齿再猜Body编号逐个融合。
9. 加轮毂后切轴孔、键槽,使用用户给定坐标与高度。正X键槽可从 `X=0` 开始切到指定槽底,Y为±半槽宽,刀体贯穿全高并略超出端面,确保与轴孔相通;从轴孔半径开始切会留下月牙残料。明确 `operation` 和 `targets`。
## 阶段核对
单齿正确后才复制。模数2.5、24齿、20°的参考值:齿根半径26.875、基圆半径约28.190778624、分度半径30、齿顶半径32.5;基圆上侧半角约4.603958292°,齿顶上侧半角约1.576846918°,上侧齿顶XY约(32.487692786,0.894325136),齿距15°,分度圆弧齿厚约3.926990817mm。这些是验算锚点,不替代用户尺寸。
最后看顶视和等轴测,核对齿数、左右对称、向外收窄、齿间空隙;检查一实体、时间线无错、轮毂轴孔尺寸和键槽连通。实体闭合或自由度为零不证明齿形正确。精度结论来自实际折线与误差界,基圆以下说明为简化齿根。
@@ -1,36 +0,0 @@
# 球轴承:开放式单列深沟结构 v0.1.0
用于“轴承、球轴承、滚珠轴承、深沟球轴承 / bearing、ball bearing”及机构内的球轴承。仅说“轴承”时可明确说明采用开放式单列深沟球轴承作示意;已有型号、尺寸或其他型式要求时遵从需求,不能把角接触、推力、调心、滚子、滑动轴套或轴承座都改成此结构。缺少会影响安装的尺寸或型式时先确认。
## 必须保留的结构
- 内圈、外圈、两圈相向的环形滚道、沿节圆均布的独立球体;普通结构还应有保持架,可用带球窝的薄环简化。滚珠和套圈分别建体,不 Join 成一件,不用单环、贴图或名称代替滚珠。
- `parts.library {"family":"bearing"}` 可查型号的内径、外径、宽度;发现命令时直接查询 `parts.library`,不能因按 bearing 检索为空就认定没有标准件。当前内置 `parts.insert` 的 bearing 是 **envelope 包络圆环,没有内外圈与滚珠**,仅用户明确要求包络占位时可直接作为交付;完整球轴承应按下面构造。
- 开放式不加遮住滚珠的端盖。密封/防尘型可以遮挡,但需要内部结构时仍应保留实际球体;没有球体不能解释为“被密封盖挡住”。
## 参数和构造
统一局部轴线 +Z,端面 `z=0、B`,球心平面 `z=B/2`。`d、D、B` 分别为内径、外径、宽度,均为 mm。球径 `ballD`、整数球数 `ballCount`、节圆半径 `pitchR` 和滚道尺寸是内部参数,不能仅凭标准外形尺寸声称它们也是原厂值。未给内部数据时可采用以下**结构示意近似**,说明采用的值;不是制造级接触、公差或承载模型。
用 `parameters.add` 定义共享参数,长度单位 mm,**ballCount 的 unit 必须为 `""`**。派生长度:`pitchR=(D+d)/4`、`ballR=ballD/2`、`grooveR=ballR+clearance`、`lipOffset=0.65*ballR`。`clearance>0` 是示意避让量,不是标准轴承游隙等级。
先核对 `d<D`、`B>0`、`ballCount≥3`、`0<lipOffset<ballR<grooveR<B/2`、`d/2<pitchR-grooveR`、`pitchR+grooveR<D/2`,以及相邻球心弦长 `2*pitchR*sin(180 deg/ballCount)>ballD`。不满足时调整内部示意参数或确认需求,不能缩放用户指定的安装尺寸来硬塞滚珠。
1. 用 `solid.cylinder` 分别 New 内圈外圆 `radius=pitchR-lipOffset`、外圈外圆 `radius=D/2`,高均为 B;再分别 Cut 半径 `d/2`、`pitchR+lipOffset` 的贯穿孔。切孔从 `z=-1 mm` 开始,高 `B+2 mm`,每次显式指定对应 `targets`。
2. 对两圈分别用 `solid.torus` Cut 滚道:`major=pitchR`、`minor=grooveR`、`center=[0,0,"B/2"]`。major/minor **都是半径**。切削只指向当前套圈;不能切滚珠或将两圈合并。
3. 创建一个独立球,再对球体做整周圆周阵列,count 包含原球:
```json
{"command":"solid.sphere","params":{"radius":"ballR","center":["pitchR",0,"B/2"],"operation":"new","body_name":"Ball","name":"BallSeed"}}
{"command":"solid.pattern.circular","params":{"bodies":["Ball"],"axis":"Z","count":"ballCount","name":"Balls"}}
```
4. 简化保持架:在半径 `pitchR±cageT/2` 间建独立薄环,轴向从 `B/2-ballR-pocketGap-railT` 起,高 `2*(ballR+pocketGap+railT)`。先用一个半径 `ballR+pocketGap`、球心同首球的 `solid.sphere` 只 Cut 保持架,再以 `features:[首个球窝切除特征名]`、`axis:"Z"`、`count:"ballCount"` 阵列球窝。要求 `pocketGap、railT>0`、`cageT/2<lipOffset`、`ballR+pocketGap+railT<B/2`,并使相邻球窝不连通:`2*pitchR*sin(180 deg/ballCount)>2*(ballR+pocketGap)`;上下保留连续环带,保持架不能与球或套圈相交。
例如 `d=15、D=35、B=11、ballD=6、ballCount=8、clearance=0.04、cageT=0.8、pocketGap=0.12、railT=0.5` 是满足这些边界的一组示意参数;其中只有 d/D/B 对应6202外形,球数、球径、滚道和保持架不是6202原厂数据,不能默认用于所有轴承。
## 检查与改参
- 预期独立实体为内圈、外圈、N颗球和保持架,共 `N+3`;若按用户要求省略保持架则 `N+2`,明确说明。各实体闭合且时间线无错误,内径 d、外径 D、总宽 B 正确。
- 实测每颗球的球心都在 `z=B/2`、距轴 `pitchR`、间隔 `360 deg/N`,球半径 `ballR`;检查套圈确有凹滚道、保持架有对应球窝。用端视与斜视确认实际球体可见;不能只验实体名称、总包围盒或插入成功。
- 修改安装尺寸、球径、球数后重建,重新核对上述间距、壁厚、球数和球窝数。整体放入机构时让套圈、球和保持架共用同一组件定位或同一刚体变换,避免只移动套圈留下滚珠。静态共轴定位不等于已建立转动关系或完成接触校核。
@@ -1,31 +0,0 @@
# 带盖薄壁壳体:共享孔系、盲孔切入面与两实体 v1
`geometry_representation=open-case-four-bosses-independent-flat-lid-v1`:开口矩形底壳+独立平盖、四凸柱及到Y内壁的四条矩形筋。无止口/唇边、卡扣、密封及真实内螺纹;不生成螺钉。不得把单体外壳直接套成双件对象。
## 参数与坐标
mm:底壳L×W×H(H不含盖)、侧壁t、底厚b、盖厚k、轴向间隙g>=0;孔心退外边e、凸柱D/高h、底孔dp/盲深q、盖孔dc、筋厚tr/高hr、用户最小材料厚w。底壳XY居中、底Z=0,内底Z=b、开口Z=H;盖下表面Z=H+g。总高H+g+k,不把H同时当含盖总高。
只定义一组共享参数`fastenerX=L/2-e`、`fastenerY=W/2-e`,四孔心为(±fastenerX,±fastenerY),凸柱/底孔/盖孔共同引用。要求L>2t、W>2t、0<b<H、b+h<=H、0<hr<=h、0<q<h、dp<dc<D、(D-dp)/2>=w,t/b/k/tr>=w,e-t>D/2,L-2e>D且W-2e>D。筋从凸柱中心到相应Y内壁,长度e-t;要求0<tr<D。这些为本规程的独立四柱边界,不静默挪孔或把盲孔改通孔。
## 当前工具构造
1. new `Case`盒:corner=[-L/2,-W/2,0],长L宽W高H。再cut内腔box,corner=[-L/2+t,-W/2+t,b],长L-2t宽W-2t高H-b+1mm,targets=[Case],保证向+Z开口、保留底厚。
2. 四凸柱沿Z从b到b+h,join只指向Case。每条筋沿X从xi-tr/2到xi+tr/2,沿Z从b到b+hr:正Y侧cornerY=fastenerY,负Y侧cornerY=-W/2+t,宽均e-t,join targets=[Case]。筋与凸柱有体积重叠且接内壁;不能对负Y筋照抄正Y起点而使Y包络变大。
3. 最后从每个凸柱顶面向-Z切盲孔:
```json
{"command":"solid.cylinder","params":{"diameter":"pilotDiameter","height":"pilotDepth","base":["fastenerX","fastenerY","bottomThickness+bossHeight"],"axis":[0,0,-1],"operation":"cut","targets":["Case"],"name":"BlindPilot"}}
```
其余三孔只改变共享XY符号。不得从Z=0起切同样“深度”,那会形成错误底部开口或内部空腔。
4. 独立new `Lid`盒,corner=[-L/2,-W/2,H+g]、长L宽W高k。盖孔用相同XY参数、Z向贯穿盖厚,cut必须显式targets=[Lid];不能用默认所有体cut或把壳盖join。
## 检查与修改
恰好两个闭合主体,Case包络Z=[0,H]、Lid=[H+g,H+g+k],XY外形一致;g=0仍保持两件身份。检查内腔开口及基础尺寸L-2t、W-2t、H-b,凸柱/筋占用区不算无障碍空间。
逐个底孔实际Z=[b+h-q,b+h],顶部开口且盲底保留;逐个盖孔Z=[H+g,H+g+k]、轴线与对应底孔同轴。检查四条筋真实厚/高及两端连接,不由正体积或截图推定。
修改L/W/e后,两件全部四组对应孔和凸柱/筋同时传播;只改g只移动盖的Z,不改XY孔系或局部厚度;只改k不改底孔。保留原生参数并实际重建核对,参数名字存在不是传播通过。有限检查不证明装配工具可达、注塑、防水或强度。
@@ -1,84 +0,0 @@
# 带中央退刀槽双斜齿:连续根圆芯与反向齿带 v1.1
外啮合、等宽两齿带、中央退刀槽;`geometry_representation=double-helical-root-core-gap-v1`,槽宽G满足`0<G<W`。槽区仅去掉根圆以外的齿,保留连续根圆芯连接两臂;不是两个悬空齿轮。采用端面渐开线及反向等导程螺旋输运,齿根为径向简化,两臂在槽口同相而由连续芯连接,槽不代表刀具加工包络。不把它替换为无槽连续人字齿或单向斜齿;不声称退刀工艺或制造级槽根过渡、共轭接触或全周期无干涉。
## 参数与适用域
输入法向模数mn>0、齿数z=18~30整数、法向压力角αn=20°、有符号下半臂螺旋角β(绝对值5~25°)、含槽总轴向宽W>0、槽宽G>0;本版等宽、零变位/侧隙、齿顶系数1、顶隙0.25。上半臂旋向反转,不把β解释成两半都同号。可选轴孔/轮毂/键槽仅按用户要求,不据样例强加。
定义可编辑参数:
```text
normalModule=mn mm; gearTeeth=z; normalPressure=20 deg
helixAngle=β deg; gearWidth=W mm; centralGap=G mm
halfWidth=(gearWidth-centralGap)/2
transverseModule=normalModule/cos(helixAngle)
gearPressure=atan(tan(normalPressure)/cos(helixAngle))
pitchRadius=transverseModule*gearTeeth/2
baseRadius=pitchRadius*cos(gearPressure)
tipRadius=pitchRadius+normalModule
rootRadius=pitchRadius-1.25*normalModule
toothBaseAngle=90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll=sqrt((tipRadius/baseRadius)^2-1)
tipAngle=toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
halfTwist=halfWidth*tan(helixAngle)/pitchRadius*(1 rad)
```
所有半径/宽度单位mm、角度显式deg/rad、roll无量纲。要求`0<rootRadius<baseRadius<tipRadius`、tipAngle>0。若轴孔存在,直径/2须小于rootRadius且保留用户要求壁厚。
## 当前工具构造
先构造下齿带完整齿廓并扫掠成new实体Gear,延长根圆芯到中面,再镜像整个半体并合并。不要先做同rootRadius芯轴再join整圈扫掠:当前引擎参考出现重合圆柱面布尔失败。下臂截面Z=0、初相φ=0°;镜像保留两槽口相位并反转旋向。
下臂截面的构造是完整单元。令`P(r,a)=[r*cos(φ+a),r*sin(φ+a)]`,`A(t)=toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)`,`R(t)=baseRadius*sqrt(1+t^2)`:
1. `sketch.create {plane:XY,offset:0,name:LowerSection}`。
2. `sketch.line`从P(rootRadius,-toothBaseAngle)到P(baseRadius,-toothBaseAngle),infer:false;`sketch.equation_curve`用x=R(t)*cos(φ-A(t))、y=R(t)*sin(φ-A(t)),start=0,end=tipRoll,tolerance=0.002。
3. 齿顶`sketch.arc.three_point`:start=P(tipRadius,-tipAngle),through=P(tipRadius,0°),end=P(tipRadius,tipAngle);另一工作侧方程曲线用φ+A(t),同一t范围。
4. 第二条line从P(baseRadius,toothBaseAngle)到P(rootRadius,toothBaseAngle)。根圆弧start=P(rootRadius,toothBaseAngle)、through=P(rootRadius,180°/gearTeeth)、end=P(rootRadius,360°/gearTeeth-toothBaseAngle)。端点都用同一个rootRadius,不用rootX*cos(...)代替。
5. 本草图这六实体通常为`l1,s1,a1,s2,l2,a2`;读取实际创建ID后,用`sketch.pattern.circular {entities:这六实体,center:[0,0],count:gearTeeth}`闭合整圈;不要包含一条额外的单齿闭合弦。solve、finish。
两工作侧不要手动展开`φ±A(t)`的符号。下截面φ=0时,负侧角是`-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,正侧角是`toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)`;不是`-toothBaseAngle-inv`或`toothBaseAngle+inv`。在上面第2、3步各自的位置使用对应的原生命令,保留括号;两侧都取t=0到tipRoll:
```json
[
{
"command": "sketch.equation_curve",
"params": {
"x": "baseRadius*sqrt(1+t^2)*cos((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"y": "baseRadius*sqrt(1+t^2)*sin((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"start": 0,
"end": "tipRoll",
"tolerance": 0.002
}
},
{
"command": "sketch.equation_curve",
"params": {
"x": "baseRadius*sqrt(1+t^2)*cos((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"y": "baseRadius*sqrt(1+t^2)*sin((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"start": 0,
"end": "tipRoll",
"tolerance": 0.002
}
}
]
```
下臂路径:YZ草图局部直线`[[0,0],[0,halfWidth]]`,第二坐标对应世界+Z。`solid.sweep {sketch:"LowerSection",path_sketch:"LowerPath",path:[实际直线ID],orientation:"parallel",twist:"halfTwist",operation:"new",body_name:"Gear",name:"LowerTeeth"}`。
再从Z=halfWidth向中面延长半段槽宽的根圆芯,不让它与扫掠圆柱面全长重合:
```json
{"command":"solid.cylinder","params":{"radius":"rootRadius","height":"centralGap/2","base":[0,0,"halfWidth"],"operation":"join","targets":["Gear"],"name":"CentralRootBridge"}}
```
然后`solid.mirror {bodies:["Gear"],plane:{origin:[0,0,"gearWidth/2"],normal:[0,0,1]},combine:true,name:"OppositeHandHalf"}`。镜像后槽区全宽只有根圆芯,两臂仍一体,不能把centralGap作为两个独立齿轮的自由摆放间距。孔等减料最后cut且显式targets=[Gear]。
## 最终几何与编辑检查
一个闭合连通实体,无失败时间线,轴线Z,总宽W;槽区Z=[(W-G)/2,(W+G)/2]外圆半径为rootRadius,轴孔以外的芯仍连续;槽口两齿带同相、等宽(W-G)/2,不允许错半齿、槽区残齿或额外实体。沿+Z下臂角位置`θ(z)=z*tanβ/pitchRadius`;上臂`θ(z)=halfTwist-(z-halfWidth-centralGap)*tanβ/pitchRadius`,两端相位相同、两槽口同相,导数反号。槽内没有工作齿侧,不能对槽内硬套渐开线采样。仅“左右各一斜齿轮”不够。
实际最终齿侧采样:r在[baseRadius,tipRadius],t=sqrt((r/baseRadius)^2-1),应满足`arg(x+iy)-θ(z)=2*pi*k/z±[toothBaseAngle-(t-atan(t))]`(此检查式角度统一rad)。分别覆盖两臂、端面和两槽口邻域,检查端面齿数和径向范围;`inspect.curvature_comb`只用`combs[].teeth[][0]`实际求值脚点。model.edges.mid只作拾取,不当曲线真值。
体积预期`S*(W-G)+pi*rootRadius^2*G`再减贯穿轴孔体积;不能把S乘含槽总宽W。 解析截面面积可用`S=pi*rf^2+z*(rb^2*ta^3/3+ra^2*(A-ta+atan(ta))-rf^2*A)`,其中rf/rb/ra对应根/基/顶半径、ta=tipRoll、A=toothBaseAngle换成rad数值,atan同样为rad数值。最终拟合面仍须采样。改mn/z/β/W/G后两臂共用同一派生链,重建检查两槽口位置、实际槽宽/芯半径、halfTwist、反向旋向和连续性。有限采样不证明全域误差或制造接触能力。
@@ -1,57 +0,0 @@
# 带中央退刀槽双斜齿:连续根圆芯与反向齿带 v1
外啮合、等宽两齿带、中央退刀槽;`geometry_representation=double-helical-root-core-gap-v1`,槽宽G满足`0<G<W`。槽区仅去掉根圆以外的齿,保留连续根圆芯连接两臂;不是两个悬空齿轮。采用端面渐开线及反向等导程螺旋输运,齿根为径向简化,两臂在槽口同相而由连续芯连接,槽不代表刀具加工包络。不把它替换为无槽连续人字齿或单向斜齿;不声称退刀工艺或制造级槽根过渡、共轭接触或全周期无干涉。
## 参数与适用域
输入法向模数mn>0、齿数z=18~30整数、法向压力角αn=20°、有符号下半臂螺旋角β(绝对值5~25°)、含槽总轴向宽W>0、槽宽G>0;本版等宽、零变位/侧隙、齿顶系数1、顶隙0.25。上半臂旋向反转,不把β解释成两半都同号。可选轴孔/轮毂/键槽仅按用户要求,不据样例强加。
定义可编辑参数:
```text
normalModule=mn mm; gearTeeth=z; normalPressure=20 deg
helixAngle=β deg; gearWidth=W mm; centralGap=G mm
halfWidth=(gearWidth-centralGap)/2
transverseModule=normalModule/cos(helixAngle)
gearPressure=atan(tan(normalPressure)/cos(helixAngle))
pitchRadius=transverseModule*gearTeeth/2
baseRadius=pitchRadius*cos(gearPressure)
tipRadius=pitchRadius+normalModule
rootRadius=pitchRadius-1.25*normalModule
toothBaseAngle=90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll=sqrt((tipRadius/baseRadius)^2-1)
tipAngle=toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
halfTwist=halfWidth*tan(helixAngle)/pitchRadius*(1 rad)
```
所有半径/宽度单位mm、角度显式deg/rad、roll无量纲。要求`0<rootRadius<baseRadius<tipRadius`、tipAngle>0。若轴孔存在,直径/2须小于rootRadius且保留用户要求壁厚。
## 当前工具构造
先构造下齿带完整齿廓并扫掠成new实体Gear,延长根圆芯到中面,再镜像整个半体并合并。不要先做同rootRadius芯轴再join整圈扫掠:当前引擎参考出现重合圆柱面布尔失败。下臂截面Z=0、初相φ=0°;镜像保留两槽口相位并反转旋向。
下臂截面的构造是完整单元。令`P(r,a)=[r*cos(φ+a),r*sin(φ+a)]`,`A(t)=toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)`,`R(t)=baseRadius*sqrt(1+t^2)`:
1. `sketch.create {plane:XY,offset:0,name:LowerSection}`。
2. `sketch.line`从P(rootRadius,-toothBaseAngle)到P(baseRadius,-toothBaseAngle),infer:false;`sketch.equation_curve`用x=R(t)*cos(φ-A(t))、y=R(t)*sin(φ-A(t)),start=0,end=tipRoll,tolerance=0.002。
3. 齿顶`sketch.arc.three_point`:start=P(tipRadius,-tipAngle),through=P(tipRadius,0°),end=P(tipRadius,tipAngle);另一工作侧方程曲线用φ+A(t),同一t范围。
4. 第二条line从P(baseRadius,toothBaseAngle)到P(rootRadius,toothBaseAngle)。根圆弧start=P(rootRadius,toothBaseAngle)、through=P(rootRadius,180°/gearTeeth)、end=P(rootRadius,360°/gearTeeth-toothBaseAngle)。端点都用同一个rootRadius,不用rootX*cos(...)代替。
5. 本草图这六实体通常为`l1,s1,a1,s2,l2,a2`;读取实际创建ID后,用`sketch.pattern.circular {entities:这六实体,center:[0,0],count:gearTeeth}`闭合整圈;不要包含一条额外的单齿闭合弦。solve、finish。
下臂路径:YZ草图局部直线`[[0,0],[0,halfWidth]]`,第二坐标对应世界+Z。`solid.sweep {sketch:"LowerSection",path_sketch:"LowerPath",path:[实际直线ID],orientation:"parallel",twist:"halfTwist",operation:"new",body_name:"Gear",name:"LowerTeeth"}`。
再从Z=halfWidth向中面延长半段槽宽的根圆芯,不让它与扫掠圆柱面全长重合:
```json
{"command":"solid.cylinder","params":{"radius":"rootRadius","height":"centralGap/2","base":[0,0,"halfWidth"],"operation":"join","targets":["Gear"],"name":"CentralRootBridge"}}
```
然后`solid.mirror {bodies:["Gear"],plane:{origin:[0,0,"gearWidth/2"],normal:[0,0,1]},combine:true,name:"OppositeHandHalf"}`。镜像后槽区全宽只有根圆芯,两臂仍一体,不能把centralGap作为两个独立齿轮的自由摆放间距。孔等减料最后cut且显式targets=[Gear]。
## 最终几何与编辑检查
一个闭合连通实体,无失败时间线,轴线Z,总宽W;槽区Z=[(W-G)/2,(W+G)/2]外圆半径为rootRadius,轴孔以外的芯仍连续;槽口两齿带同相、等宽(W-G)/2,不允许错半齿、槽区残齿或额外实体。沿+Z下臂角位置`θ(z)=z*tanβ/pitchRadius`;上臂`θ(z)=halfTwist-(z-halfWidth-centralGap)*tanβ/pitchRadius`,两端相位相同、两槽口同相,导数反号。槽内没有工作齿侧,不能对槽内硬套渐开线采样。仅“左右各一斜齿轮”不够。
实际最终齿侧采样:r在[baseRadius,tipRadius],t=sqrt((r/baseRadius)^2-1),应满足`arg(x+iy)-θ(z)=2*pi*k/z±[toothBaseAngle-(t-atan(t))]`(此检查式角度统一rad)。分别覆盖两臂、端面和两槽口邻域,检查端面齿数和径向范围;`inspect.curvature_comb`只用`combs[].teeth[][0]`实际求值脚点。model.edges.mid只作拾取,不当曲线真值。
体积预期`S*(W-G)+pi*rootRadius^2*G`再减贯穿轴孔体积;不能把S乘含槽总宽W。 解析截面面积可用`S=pi*rf^2+z*(rb^2*ta^3/3+ra^2*(A-ta+atan(ta))-rf^2*A)`,其中rf/rb/ra对应根/基/顶半径、ta=tipRoll、A=toothBaseAngle换成rad数值,atan同样为rad数值。最终拟合面仍须采样。改mn/z/β/W/G后两臂共用同一派生链,重建检查两槽口位置、实际槽宽/芯半径、halfTwist、反向旋向和连续性。有限采样不证明全域误差或制造接触能力。
@@ -1,37 +0,0 @@
# 带槽双斜齿:齿侧符号、有效齿宽与连接提示
仅用于已选定的端面渐开线、径向简化齿根、等宽反向螺旋输运表示;不是完整建模教程。总宽`gearWidth=W`包含槽宽`centralGap=G`,必须`0<G<W`,槽区保留连续根圆芯。不据此声称加工包络或制造级共轭。
保留原生参数链,长度mm、角度显式deg/rad。输入法向模数`normalModule`、齿数`gearTeeth`、法向压力角`normalPressure`和有符号下半臂螺旋角`helixAngle`:
```text
halfWidth=(gearWidth-centralGap)/2
transverseModule=normalModule/cos(helixAngle)
gearPressure=atan(tan(normalPressure)/cos(helixAngle))
pitchRadius=transverseModule*gearTeeth/2
baseRadius=pitchRadius*cos(gearPressure)
tipRadius=pitchRadius+normalModule
rootRadius=pitchRadius-1.25*normalModule
toothBaseAngle=90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll=sqrt((tipRadius/baseRadius)^2-1)
halfTwist=halfWidth*tan(helixAngle)/pitchRadius*(1 rad)
```
已发生的错误是半齿角用`180 deg/gearTeeth`、twist直接用β,以及展开齿侧符号时写反。必须分别用`90 deg/gearTeeth`和`halfTwist`;有效单侧齿宽是`(W-G)/2`。要求`0<rootRadius<baseRadius<tipRadius`及`toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)>0`。
下截面Z=0、初相0时,两工作侧分别使用以下原生命令,保留括号;其余闭合与阵列沿原通用技能:
```json
[
{"command":"sketch.equation_curve","params":{"x":"baseRadius*sqrt(1+t^2)*cos((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","y":"baseRadius*sqrt(1+t^2)*sin((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","start":0,"end":"tipRoll","tolerance":0.002}},
{"command":"sketch.equation_curve","params":{"x":"baseRadius*sqrt(1+t^2)*cos((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","y":"baseRadius*sqrt(1+t^2)*sin((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","start":0,"end":"tipRoll","tolerance":0.002}}
]
```
下半完整轮廓沿+Z扫掠`halfWidth`,`orientation:parallel,twist:halfTwist,operation:new,body_name:Gear`。不要先建同根圆芯再Join完整扫掠,原参考在重合圆柱面处布尔失败。先从齿带末端连接半槽芯,再绕Z=`gearWidth/2`平面镜像整个半体并`combine:true`:
```json
{"command":"solid.cylinder","params":{"radius":"rootRadius","height":"centralGap/2","base":[0,0,"halfWidth"],"operation":"join","targets":["Gear"],"name":"CentralRootBridge"}}
```
核对一个连通实体、槽宽G、两侧齿带各`(W-G)/2`且旋向相反。槽口同相,槽区根圆芯连续、根圆外无残齿;不能用两只悬空齿轮代替。
@@ -1,21 +0,0 @@
# 平行轴外啮合直齿轮副:接口与相位 v1
实验候选。适用于已明确的单级、外啮合、渐开线直齿、平行轴、零变位轮副;不替用户选择泛称“减速装置”的传动方案。此文只补充接口、位置和相位;准备生成各齿轮时按需查询`involute-spur-gear`,不以运动约束代替齿形。
## 共同参数和位置
两轮必须同模数m、同压力角、兼容齿制。用户给出z1、z2与齿宽;分度半径r1=m*z1/2、r2=m*z2/2,零变位参考中心距a=r1+r2。不得拿齿顶半径相加作中心距。轴孔、轮毂、轴向台阶按各轮要求选配。若给出的中心距和这些条件冲突,明确指出,不改齿数或模数凑数。
标准坐标:主动轮轴Z、中心(0,0),从轮轴Z、中心(a,0),两轮齿宽在Z方向有共同区间,保留两个独立实体。圆孔随各自轮轴,不能把从轮的孔留在原点。共享m、压力角、齿宽、a用参数表达式;每轮独立命名参数、草图、特征和实体,防止同名targets指向错误对象。
## 装配相位
若单轮规程均以一齿中心朝本地+X构造,主动轮初相位φ1=0,从轮可取φ2=180 deg−180 deg/z2,使主动轮朝从轮的齿中心对准从轮朝主动轮的齿槽中心。任意φ1时用`φ2=180 deg−180 deg/z2−(z1/z2)*φ1`,相位允许加整齿距。不能两轮都默认零角度后只平移,使齿顶撞齿顶。
现有`solid.move`支持表达式translate和angle。先在各自本地原点建好轮与孔槽;从轮`solid.move {bodies:[从轮],axis:[0,0,1],angle:φ2,translate:[a,0,0]}`按绕世界原点旋转后平移。已经放置的轮再调整角度时,应先明确旋转中心,不直接绕全局原点使轮轴绕走。不得将两轮Join为一个实体。
## 检查和可选运动
检查两闭合实体、轴线平行、轴距a、齿宽重叠、齿数、各轮实际齿形与相位。用实际轮廓/孔轴和测量复核,不看实体名称就判定正确。零侧隙和简化齿根不是制造认证;静态相位正确也不能证明全过程无干涉。
仅用户要求运动时沿原机构Skill建组件、固定支承和两个revolute joint,保持原位置;使用`joint.gear {a:主动关节,b:从动关节,ra:r1,rb:r2}`,期望角速度比ω2/ω1=−z1/z2。驱动主动轮,实际读取从轮角度并检查moved,不用joint.gear生成齿形。参考20/30齿、m2:a50mm,主动转30°应对应从动−20°。未实际驱动时仅报告解析比值,不声称运动已验证。
@@ -1,23 +0,0 @@
# 平行轴外啮合直齿/斜齿轮副:轴距、相位和侧隙 v2
仅补轮副接口,各轮造型另读对应单轮规程。两轮为独立有齿实体;不靠移动轴心躲开错误相位,不以运动约束代替齿形。
直齿同模数、同压力角,`r_i=module*z_i/2`;斜齿同法向模数和压力角、螺旋角绝对值相同且旋向相反(统一沿同一轴向定义),`r_i=normalModule*z_i/(2*cos(helixAngle))`。零变位参考轴距 `a=r1+r2`,不能把齿顶半径相加。两轮齿宽必须在同一轴向区间重叠。
## 相位必须在共同截面定义
单轮规程从本地+X的齿中心开始。将两轮转换到同一轴向和同一横截面坐标,记连心线在主动轮处的角度为λ1、从轮处λ2=λ1+180°,两轮该截面的实际齿中心相位为φ1、φ2。齿对槽条件:
`z1*(λ1-φ1)+z2*(λ2-φ2) = 180 deg (mod 360 deg)`
可解 `φ2=λ2+(z1/z2)*(λ1-φ1)-180 deg/z2`,允许加从轮整齿距。两轮都零角度后平移,往往是齿对齿。例如20/60齿都从+X起齿、同样转为轴+Y、中心沿Z上下排布时,从轮补本轴3°;24/72则补2.5°。这些数值不能套用于任意连心线和已有相位。
斜齿在截面s的相位 `φ_i(s)=起面相位+toothTwist_i*(s-起面位置)/gearWidth_i`。共同起面、相同有效宽度、相反旋向时 `z1*toothTwist1+z2*toothTwist2=0`,同一相位关系沿齿宽保持;起面不一致必须先换算到同一s,不能忽略扭转只看端面。
`solid.move`绕世界原点旋转后平移。优先在本地原点建轮、孔槽和相位,再定位;已定位轮调角需保持轴心C:先移到原点再旋转并移回,或用平移补偿 `C-R*C`,否则轴心会绕走。
## 演示侧隙与检查
零侧隙的曲线拟合可能产生微小重叠。用户接受演示简化时可显式选择端面总切向侧隙j,例如0.1mm(演示选择,不是公差标准),均分到两轮:各轮齿厚减j/2,单轮规程的 `toothBaseAngle` 减 `(j/(4*pitchRadius))*(1 rad)`。尺寸仍用原模数和轴距;保留并报告j,检查齿顶角仍正。不得默默减齿数、缩轮或取消轮齿。
核对实际轴线、轴距、共同齿宽、齿数、旋向及齿对槽。使用实际轮廓与精确干涉检查;`unchecked`或布尔错误不是无干涉。零侧隙接触、有限曲线采样和静态无明显穿透均不代表运动全过程或制造级认证。仅用户要求运动时再用原机构Skill建立关节/传动关系。
@@ -1,65 +0,0 @@
# 外斜齿圆柱齿轮:完整截面与轴向扭转扫掠 v1.1
实验规程。外啮合、法向压力角20°、零变位/侧隙、法向齿顶高系数1、顶隙系数0.25;本版18~30齿、螺旋角绝对值5~25°,须`0<rootRadius<baseRadius`。基圆以下径向简化。输入模数必须明确是法向模数;左右旋按用户要求。不把斜齿轮当作直齿轮,也不声称制造级完整齿根。
## 参数
用`parameters.add`:长度`unit:"mm"`、角度`unit:"deg"`、无量纲`unit:""`。不使用保留名m或自变量t作用户参数。
```text
normalModule, gearWidth, boreDiameter = 用户尺寸 [mm]
gearTeeth = 用户齿数 [无量纲]
normalPressure = 20 deg
helixAngle = 右旋取正、左旋取负的用户螺旋角 [deg]
transverseModule = normalModule/cos(helixAngle) [mm]
gearPressure = atan(tan(normalPressure)/cos(helixAngle)) [deg]
pitchRadius = transverseModule*gearTeeth/2 [mm]
baseRadius = pitchRadius*cos(gearPressure) [mm]
tipRadius = pitchRadius+normalModule [mm]
rootRadius = pitchRadius-1.25*normalModule [mm]
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad) [deg]
tipRoll = sqrt((tipRadius/baseRadius)^2-1) [无量纲]
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad) [deg]
toothTwist = gearWidth*tan(helixAngle)/pitchRadius*(1 rad) [deg]
rootX = rootRadius*cos(toothBaseAngle) [mm]
rootY = rootRadius*sin(toothBaseAngle) [mm]
baseX = baseRadius*cos(toothBaseAngle) [mm]
baseY = baseRadius*sin(toothBaseAngle) [mm]
tipX = tipRadius*cos(tipAngle) [mm]
tipY = tipRadius*sin(tipAngle) [mm]
```
必须法向/端面量分开;不能直接用法向模数计算分度圆。`atan`结果带角度单位,除以`1 rad`才是弧度数。正twist沿+Z作右手旋转;沿+Z推进时,右旋齿的方位角增加。宽度不是导程:总扭转由上述公式重新计算。
## 先完成二维外轮廓,再整体扫掠
本引擎单齿扭转后再Join阵列的参考尝试出现布尔缝失败;使用以下完整截面方法,避免重复连接扭转齿面。先不建根圆柱,也不把每个齿单独扫掠。
`sketch.create {plane:"XY",name:"HelicalSection"}`,顺序建立一个**开口扇区链**:
1. `sketch.line` 下侧`[rootX,-rootY]→[baseX,-baseY]`,`infer:false`,得到l1。
2. `sketch.equation_curve`:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y取同角度的负正弦式;`start:0,end:"tipRoll",tolerance:0.002`,得到s1。tolerance必须数值字面量。
3. `sketch.arc.three_point`:`[tipX,-tipY]→[tipRadius,0]→[tipX,tipY]`,得到a1。
4. 第二条方程曲线x相同、y取正正弦,其他参数相同,得到s2。
5. `sketch.line` 上侧`[baseX,baseY]→[rootX,rootY]`,`infer:false`,得到l2。
6. 齿根间隙圆弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/gearTeeth),rootRadius*sin(180 deg/gearTeeth)]`,end=`[rootRadius*cos(360 deg/gearTeeth-toothBaseAngle),rootRadius*sin(360 deg/gearTeeth-toothBaseAngle)]`。
扇区末点恰是下一齿的下侧根点;**不要用一条弦闭合单齿**。随后:
```json
{"command":"sketch.pattern.circular","params":{"entities":["l1","s1","a1","s2","l2","a2"],"center":[0,0],"count":"gearTeeth"}}
```
该草图只应有一个完整齿圈闭合区域。`sketch.solve`、`sketch.inspect`确认后`sketch.finish`。
建立轴线扫掠路径:`sketch.create {plane:"YZ",name:"AxisPath"}`,`sketch.line {points:[[0,0],[0,"gearWidth"]],infer:false}`,得到路径l1,再`sketch.finish`。YZ局部x为世界Y,局部y为世界Z,故这条线正沿世界+Z。
```json
{"command":"solid.sweep","params":{"sketch":"HelicalSection","path_sketch":"AxisPath","path":["l1"],"orientation":"parallel","twist":"toothTwist","operation":"new","body_name":"Gear","name":"HelicalGearSweep"}}
```
轴孔、轮毂和键槽按用户要求后续独立添加;无轮毂/无键槽时不能套用样例强加。孔用圆柱贯穿切除,显式targets。不要对完整齿圈再次实体圆周阵列。
## 检查
一闭合实体、时间线无错误、齿数正确。端面实际曲线应为端面压力角对应的渐开线;上下端面的同一特征角差应为toothTwist,且轴向中部约为一半。用inspect.curvature_comb的edges分支取工作纵边和齿根纵边的实际曲线脚点,检查定半径及phase(z)=phase(0)+toothTwist*z/gearWidth;combs[].teeth[][0]才是脚点。model.edges.mid/length来自显示折线,不能据其弦中点判断真实齿面或根部偏差。截面积沿Z保持,体积应约等于端面齿圈面积乘齿宽再扣孔槽;体积正确不能单独证明旋向。至少改变齿数、模数或旋向进行复核。基圆以下径向简化、曲线拟合和有限采样均不等于制造认证。
@@ -1,71 +0,0 @@
# 外斜齿圆柱齿轮:完整截面与轴向扭转扫掠 v1.2
实验规程。外啮合、法向压力角20°、零变位/侧隙、法向齿顶高系数1、顶隙系数0.25;须`0<rootRadius<tipRadius`;根圆位于基圆内、外分别处理。当前独立参考回放为法向模数2、20/24/60/72齿、螺旋角20°,并非所有尺寸或生产WASM的验证。基圆以下径向简化。输入模数必须明确是法向模数;左右旋按用户要求。不把斜齿轮当作直齿轮,也不声称制造级完整齿根。
**构造选择:斜齿使用本规程的完整齿圈整体扭转,不套用直齿文档的单齿Join策略。先建完整有齿轮体,孔、轮毂、轴按用户要求后加。**
## 参数
用`parameters.add`:长度`unit:"mm"`、角度`unit:"deg"`、无量纲`unit:""`。不使用保留名m或自变量t作用户参数。
```text
normalModule, gearWidth, boreDiameter = 用户尺寸 [mm]
gearTeeth = 用户齿数 [无量纲]
normalPressure = 20 deg
helixAngle = 右旋取正、左旋取负的用户螺旋角 [deg]
transverseModule = normalModule/cos(helixAngle) [mm]
gearPressure = atan(tan(normalPressure)/cos(helixAngle)) [deg]
pitchRadius = transverseModule*gearTeeth/2 [mm]
baseRadius = pitchRadius*cos(gearPressure) [mm]
tipRadius = pitchRadius+normalModule [mm]
rootRadius = pitchRadius-1.25*normalModule [mm]
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad) [deg]
startRoll = sqrt(max((rootRadius/baseRadius)^2-1,0)) [无量纲]
rootAngle = toothBaseAngle-(startRoll-atan(startRoll)/(1 rad))*(1 rad) [deg]
tipRoll = sqrt((tipRadius/baseRadius)^2-1) [无量纲]
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad) [deg]
toothTwist = gearWidth*tan(helixAngle)/pitchRadius*(1 rad) [deg]
rootX = rootRadius*cos(rootAngle) [mm]
rootY = rootRadius*sin(rootAngle) [mm]
baseX = baseRadius*cos(toothBaseAngle) [mm]
baseY = baseRadius*sin(toothBaseAngle) [mm]
tipX = tipRadius*cos(tipAngle) [mm]
tipY = tipRadius*sin(tipAngle) [mm]
```
必须法向/端面量分开;不能直接用法向模数计算分度圆。`atan`结果带角度单位,除以`1 rad`才是弧度数。正twist沿+Z作右手旋转;沿+Z推进时,右旋齿的方位角增加。宽度不是导程:总扭转由上述公式重新计算。
## 先完成二维外轮廓,再整体扫掠
本引擎单齿扭转后再Join阵列的参考尝试出现布尔缝失败;使用以下完整截面方法,避免重复连接扭转齿面。先不建根圆柱,也不把每个齿单独扫掠。
`sketch.create {plane:"XY",name:"HelicalSection"}`,顺序建立一个**开口扇区链**:
1. 仅当`rootRadius<baseRadius`时,`sketch.line` 下侧`[rootX,-rootY]→[baseX,-baseY]`,`infer:false`,得到l1。
2. `sketch.equation_curve`:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y取同角度的负正弦式;`start:"startRoll",end:"tipRoll",tolerance:0.002`,得到s1。tolerance必须数值字面量。
3. `sketch.arc.three_point`:`[tipX,-tipY]→[tipRadius,0]→[tipX,tipY]`,得到a1。
4. 第二条方程曲线x相同、y取正正弦,其他参数相同,得到s2。
5. 仅当`rootRadius<baseRadius`时,`sketch.line` 上侧`[baseX,baseY]→[rootX,rootY]`,`infer:false`,得到l2。
6. 齿根间隙圆弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/gearTeeth),rootRadius*sin(180 deg/gearTeeth)]`,end=`[rootRadius*cos(360 deg/gearTeeth-rootAngle),rootRadius*sin(360 deg/gearTeeth-rootAngle)]`。
扇区末点恰是下一齿的下侧根点;**不要用一条弦闭合单齿**。随后:
```json
{"command":"sketch.pattern.circular","params":{"entities":["l1","s1","a1","s2","l2","a2"],"center":[0,0],"count":"gearTeeth"}}
```
上例六项仅用于根圆在基圆内。`rootRadius>=baseRadius`时省去l1、l2,阵列实体为`["s1","a1","s2","a2"]`;两条渐开线从根圆上的`startRoll`开始,根隙圆弧也使用`rootAngle`。不要从基圆继续画到根圆内部、补反向径向线,或更改模数/齿数来回避这一分支。恰好相等时也省去零长线。
该草图只应有一个完整齿圈闭合区域。`sketch.solve`、`sketch.inspect`确认后`sketch.finish`。
建立轴线扫掠路径:`sketch.create {plane:"YZ",name:"AxisPath"}`,`sketch.line {points:[[0,0],[0,"gearWidth"]],infer:false}`,得到路径l1,再`sketch.finish`。YZ局部x为世界Y,局部y为世界Z,故这条线正沿世界+Z。
```json
{"command":"solid.sweep","params":{"sketch":"HelicalSection","path_sketch":"AxisPath","path":["l1"],"orientation":"parallel","twist":"toothTwist","operation":"new","body_name":"Gear","name":"HelicalGearSweep"}}
```
轴孔、轮毂和键槽按用户要求后续独立添加;无轮毂/无键槽时不能套用样例强加。孔用圆柱贯穿切除,显式targets。不要对完整齿圈再次实体圆周阵列。
## 检查
一闭合实体、时间线无错误、齿数正确;孔半径须小于根半径,且`0<tipAngle<rootAngle<180 deg/gearTeeth`。端面实际曲线应为端面压力角对应的渐开线;上下端面的同一特征角差应为toothTwist,且轴向中部约为一半。用inspect.curvature_comb的edges分支取工作纵边和齿根纵边的实际曲线脚点,检查定半径及phase(z)=phase(0)+toothTwist*z/gearWidth;combs[].teeth[][0]才是脚点。model.edges.mid/length来自显示折线,不能据其弦中点判断真实齿面或根部偏差。截面积沿Z保持,体积应约等于端面齿圈面积乘齿宽再扣孔槽;体积正确不能单独证明旋向。至少改变齿数、模数或旋向进行复核。基圆以下径向简化、曲线拟合和有限采样均不等于制造认证。
@@ -1,65 +0,0 @@
# 外斜齿圆柱齿轮:完整截面与轴向扭转扫掠 v1
实验规程。外啮合、法向压力角20°、零变位/侧隙、法向齿顶高系数1、顶隙系数0.25;本版18~30齿、螺旋角绝对值5~25°,须`0<rootRadius<baseRadius`。基圆以下径向简化。输入模数必须明确是法向模数;左右旋按用户要求。不把斜齿轮当作直齿轮,也不声称制造级完整齿根。
## 参数
用`parameters.add`:长度`unit:"mm"`、角度`unit:"deg"`、无量纲`unit:""`。不使用保留名m或自变量t作用户参数。
```text
normalModule, gearWidth, boreDiameter = 用户尺寸 [mm]
gearTeeth = 用户齿数 [无量纲]
normalPressure = 20 deg
helixAngle = 右旋取正、左旋取负的用户螺旋角 [deg]
transverseModule = normalModule/cos(helixAngle) [mm]
gearPressure = atan(tan(normalPressure)/cos(helixAngle)) [deg]
pitchRadius = transverseModule*gearTeeth/2 [mm]
baseRadius = pitchRadius*cos(gearPressure) [mm]
tipRadius = pitchRadius+normalModule [mm]
rootRadius = pitchRadius-1.25*normalModule [mm]
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad) [deg]
tipRoll = sqrt((tipRadius/baseRadius)^2-1) [无量纲]
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad) [deg]
toothTwist = gearWidth*tan(helixAngle)/pitchRadius*(1 rad) [deg]
rootX = rootRadius*cos(toothBaseAngle) [mm]
rootY = rootRadius*sin(toothBaseAngle) [mm]
baseX = baseRadius*cos(toothBaseAngle) [mm]
baseY = baseRadius*sin(toothBaseAngle) [mm]
tipX = tipRadius*cos(tipAngle) [mm]
tipY = tipRadius*sin(tipAngle) [mm]
```
必须法向/端面量分开;不能直接用法向模数计算分度圆。`atan`结果带角度单位,除以`1 rad`才是弧度数。正twist沿+Z作右手旋转;沿+Z推进时,右旋齿的方位角增加。宽度不是导程:总扭转由上述公式重新计算。
## 先完成二维外轮廓,再整体扫掠
本引擎单齿扭转后再Join阵列的参考尝试出现布尔缝失败;使用以下完整截面方法,避免重复连接扭转齿面。先不建根圆柱,也不把每个齿单独扫掠。
`sketch.create {plane:"XY",name:"HelicalSection"}`,顺序建立一个**开口扇区链**:
1. `sketch.line` 下侧`[rootX,-rootY]→[baseX,-baseY]`,`infer:false`,得到l1。
2. `sketch.equation_curve`:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y取同角度的负正弦式;`start:0,end:"tipRoll",tolerance:0.002`,得到s1。tolerance必须数值字面量。
3. `sketch.arc.three_point`:`[tipX,-tipY]→[tipRadius,0]→[tipX,tipY]`,得到a1。
4. 第二条方程曲线x相同、y取正正弦,其他参数相同,得到s2。
5. `sketch.line` 上侧`[baseX,baseY]→[rootX,rootY]`,`infer:false`,得到l2。
6. 齿根间隙圆弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/gearTeeth),rootRadius*sin(180 deg/gearTeeth)]`,end=`[rootRadius*cos(360 deg/gearTeeth-toothBaseAngle),rootRadius*sin(360 deg/gearTeeth-toothBaseAngle)]`。
扇区末点恰是下一齿的下侧根点;**不要用一条弦闭合单齿**。随后:
```json
{"command":"sketch.pattern.circular","params":{"entities":["l1","s1","a1","s2","l2","a2"],"center":[0,0],"count":"gearTeeth"}}
```
该草图只应有一个完整齿圈闭合区域。`sketch.solve`、`sketch.inspect`确认后`sketch.finish`。
建立轴线扫掠路径:`sketch.create {plane:"YZ",name:"AxisPath"}`,`sketch.line {points:[[0,0],[0,"gearWidth"]],infer:false}`,得到路径l1,再`sketch.finish`。YZ局部x为世界Y,局部y为世界Z,故这条线正沿世界+Z。
```json
{"command":"solid.sweep","params":{"sketch":"HelicalSection","path_sketch":"AxisPath","path":["l1"],"orientation":"parallel","twist":"toothTwist","operation":"new","body_name":"Gear","name":"HelicalGearSweep"}}
```
轴孔、轮毂和键槽按用户要求后续独立添加;无轮毂/无键槽时不能套用样例强加。孔用圆柱贯穿切除,显式targets。不要对完整齿圈再次实体圆周阵列。
## 检查
一闭合实体、时间线无错误、齿数正确。端面实际曲线应为端面压力角对应的渐开线;上下端面的相同特征角差应为toothTwist,且中高处约为一半,不是把平直轮齿斜放。检查模型边的实际端点/中点、齿向和截图,不仅看特征名。截面积沿Z保持,体积应约等于对应端面齿圈面积乘齿宽再扣孔槽;只有体积正确不能证明旋向。至少改变齿数、模数或旋向进行复核。当前扫掠对基圆以下简化齿根还可能采用弦段连接,24齿参考中根部中高处径向差约0.0585mm;此近似只在简化齿根范围内,不能放宽工作齿廓检查。基圆以下简化、曲线/扫掠曲面拟合和采样均不等于制造认证。
@@ -1,68 +0,0 @@
# 斜齿齿条:法向齿制与平移扫掠规程 v1.1
实验候选,实际回放与正式助手生成效果须分别验证。适用法向压力角20°、零变位/侧隙、齿顶高系数1、顶隙系数0.25,1~96个完整齿,`0<abs(β)≤35°`。齿根为明确标注的尖角简化,不声称制造级包络或与指定小齿轮共轭。
## 坐标与必要参数
X为节距方向,Y为齿高,Z为齿宽,宽度从Z=0到Z=b。法向模数mn、完整齿数N、齿宽b、基体厚度和有符号齿线角β来自用户或明确采用的方案。**本规程β>0定义为沿+Z推进时齿线向+X偏移,β<0向-X**;不把这个坐标约定直接冒称圆柱齿轮的左右旋。只说左右旋而未确定坐标时,先明确齿线方向。
法向值不能冒充端面值:`pt=pi*mn/cos(β)`,`tan(αt)=tan(20°)/cos(β)`;齿高仍用mn,不用端面模数。不能把普通直齿条整体旋转,或给扫掠设置扭转角来代替斜齿齿条。
`parameters.add`长度`unit:"mm"`、角度`unit:"deg"`、计数/斜率`unit:""`。避免单位保留名m或曲线自变量t:
```text
rackNormalModule, rackWidth, baseThickness = 明确尺寸 [mm]
rackTeeth = N [整数]
rackNormalPressure = 20 deg
rackHelix = 有符号β [deg]
rackPitch = pi*rackNormalModule/cos(rackHelix) [mm]
transverseSlope = tan(rackNormalPressure)/cos(rackHelix) [无量纲]
addendum = rackNormalModule [mm]
dedendum = 1.25*rackNormalModule [mm]
halfTip = rackPitch/4-addendum*transverseSlope [mm]
halfRoot = rackPitch/4+dedendum*transverseSlope [mm]
rackShift = rackWidth*tan(rackHelix) [mm]
rackPadding = abs(rackShift) [mm]
rackLength = rackTeeth*rackPitch+rackPadding [mm]
firstCenter = rackPitch/2+(rackPadding-rackShift)/2 [mm]
joinOverlap = 0.05*rackNormalModule [mm]
halfJoin = rackPitch/4+(dedendum+joinOverlap)*transverseSlope [mm]
```
此样板选择`L=N*pt+abs(ΔX)`,为两端留空间,使所有Z截面都有N个完整齿。**不能在用户已指定总长时静默改成此长度**;若总长、端部余量、端部半齿或模数体系不同,先解决尺寸关系,本规程不提供固定总长裁齿变体。要求`0<halfTip<halfRoot<rackPitch/2`、`0<joinOverlap<baseThickness`,所有长度正、N为整数。
## 当前工具构造
基体:`solid.box {corner:[0,"-dedendum-baseThickness",0],length:"rackLength",width:"baseThickness",height:"rackWidth",operation:"new",body_name:"Rack",name:"RackBase"}`。
1. `sketch.create {plane:"XY",name:"HelicalRackToothProfile"}`。一次`sketch.line {closed:true,infer:false,points:[...]}`画下列四点,检查一个闭合区域后`sketch.finish`:
```json
[
["firstCenter-halfJoin","-dedendum-joinOverlap"],
["firstCenter-halfTip","addendum"],
["firstCenter+halfTip","addendum"],
["firstCenter+halfJoin","-dedendum-joinOverlap"]
]
```
2. `sketch.create {plane:"XZ",name:"RackTracePath"}`。XZ局部y是世界-Z,因此用`sketch.line {points:[["firstCenter",0],["firstCenter+rackShift","-rackWidth"]],infer:false}`画一条l1,然后`sketch.finish`。路径从单齿截面内部起,避免靠近路径另一端造成自动反向。
3. 扫掠并Join后再阵列特征:
```json
{"command":"solid.sweep","params":{"sketch":"HelicalRackToothProfile","path_sketch":"RackTracePath","path":["l1"],"orientation":"parallel","operation":"join","targets":["Rack"],"name":"HelicalRackTooth"}}
{"command":"solid.pattern.rectangular","params":{"features":["HelicalRackTooth"],"dir1":[1,0,0],"count1":"rackTeeth","spacing1":"rackPitch","name":"HelicalRackTeeth"}}
```
N=1省略阵列。必须`orientation:"parallel"`让每个XY截面保持不变,不能用默认垂直路径的朝向,也不加twist/scale。底边重叠进基体,但暴露根线Y=-dedendum处仍具有正确斜率。不能阵列整个基体,计数包含原齿。安装孔和背部结构按需求选配。
## 独立检查
应一个闭合实体、无失败时间线、两宽度端各N个完整平顶梯形齿。端面两侧`abs(dx/dy)=transverseSlope`,节线上齿厚pt/2,相邻中心距pt;齿顶宽2*halfTip。对应端部齿顶点应`ΔX=rackShift`且ΔZ=b;沿齿宽的实际边曲线采样也应在线上,不能只检查截面像齿条。每条工作面都是平面。
```text
体积 = [rackLength*baseThickness + N*(addendum+dedendum)*(halfTip+halfRoot)]*rackWidth
包围盒 = [0,-dedendum-baseThickness,0] 到 [rackLength,addendum,rackWidth]
```
体积不重复计入齿底与基体的重叠。N个齿中心在宽度中面关于L/2对称,整体质心X=L/2、Z=b/2;Y质心需按基体与梯形面积加权,不能填0。用`inspect.curvature_comb`边采样的`combs[].teeth[][0]`实际曲线脚点核对所有齿位、端面压力角和有符号齿线斜率;面采样核对共面性,再看截图与原生参数重建。`model.edges.mid/length`来自显示折线,不能作为精确曲线内点或弧长。公式自洽、单齿草图或包围盒正确均不能单独证明最终斜齿齿条正确。
@@ -1,68 +0,0 @@
# 斜齿齿条:法向齿制与平移扫掠规程 v1
实验候选,实际回放与正式助手生成效果须分别验证。适用法向压力角20°、零变位/侧隙、齿顶高系数1、顶隙系数0.25,1~96个完整齿,`0<abs(β)≤35°`。齿根为明确标注的尖角简化,不声称制造级包络或与指定小齿轮共轭。
## 坐标与必要参数
X为节距方向,Y为齿高,Z为齿宽,宽度从Z=0到Z=b。法向模数mn、完整齿数N、齿宽b、基体厚度和有符号齿线角β来自用户或明确采用的方案。**本规程β>0定义为沿+Z推进时齿线向+X偏移,β<0向-X**;不把这个坐标约定直接冒称圆柱齿轮的左右旋。只说左右旋而未确定坐标时,先明确齿线方向。
法向值不能冒充端面值:`pt=pi*mn/cos(β)`,`tan(αt)=tan(20°)/cos(β)`;齿高仍用mn,不用端面模数。不能把普通直齿条整体旋转,或给扫掠设置扭转角来代替斜齿齿条。
`parameters.add`长度`unit:"mm"`、角度`unit:"deg"`、计数/斜率`unit:""`。避免单位保留名m或曲线自变量t:
```text
rackNormalModule, rackWidth, baseThickness = 明确尺寸 [mm]
rackTeeth = N [整数]
rackNormalPressure = 20 deg
rackHelix = 有符号β [deg]
rackPitch = pi*rackNormalModule/cos(rackHelix) [mm]
transverseSlope = tan(rackNormalPressure)/cos(rackHelix) [无量纲]
addendum = rackNormalModule [mm]
dedendum = 1.25*rackNormalModule [mm]
halfTip = rackPitch/4-addendum*transverseSlope [mm]
halfRoot = rackPitch/4+dedendum*transverseSlope [mm]
rackShift = rackWidth*tan(rackHelix) [mm]
rackPadding = abs(rackShift) [mm]
rackLength = rackTeeth*rackPitch+rackPadding [mm]
firstCenter = rackPitch/2+(rackPadding-rackShift)/2 [mm]
joinOverlap = 0.05*rackNormalModule [mm]
halfJoin = rackPitch/4+(dedendum+joinOverlap)*transverseSlope [mm]
```
此样板选择`L=N*pt+abs(ΔX)`,为两端留空间,使所有Z截面都有N个完整齿。**不能在用户已指定总长时静默改成此长度**;若总长、端部余量、端部半齿或模数体系不同,先解决尺寸关系,本规程不提供固定总长裁齿变体。要求`0<halfTip<halfRoot<rackPitch/2`、`0<joinOverlap<baseThickness`,所有长度正、N为整数。
## 当前工具构造
基体:`solid.box {corner:[0,"-dedendum-baseThickness",0],length:"rackLength",width:"baseThickness",height:"rackWidth",operation:"new",body_name:"Rack",name:"RackBase"}`。
1. `sketch.create {plane:"XY",name:"HelicalRackToothProfile"}`。一次`sketch.line {closed:true,infer:false,points:[...]}`画下列四点,检查一个闭合区域后`sketch.finish`:
```json
[
["firstCenter-halfJoin","-dedendum-joinOverlap"],
["firstCenter-halfTip","addendum"],
["firstCenter+halfTip","addendum"],
["firstCenter+halfJoin","-dedendum-joinOverlap"]
]
```
2. `sketch.create {plane:"XZ",name:"RackTracePath"}`。XZ局部y是世界-Z,因此用`sketch.line {points:[["firstCenter",0],["firstCenter+rackShift","-rackWidth"]],infer:false}`画一条l1,然后`sketch.finish`。路径从单齿截面内部起,避免靠近路径另一端造成自动反向。
3. 扫掠并Join后再阵列特征:
```json
{"command":"solid.sweep","params":{"sketch":"HelicalRackToothProfile","path_sketch":"RackTracePath","path":["l1"],"orientation":"parallel","operation":"join","targets":["Rack"],"name":"HelicalRackTooth"}}
{"command":"solid.pattern.rectangular","params":{"features":["HelicalRackTooth"],"dir1":[1,0,0],"count1":"rackTeeth","spacing1":"rackPitch","name":"HelicalRackTeeth"}}
```
N=1省略阵列。必须`orientation:"parallel"`让每个XY截面保持不变,不能用默认垂直路径的朝向,也不加twist/scale。底边重叠进基体,但暴露根线Y=-dedendum处仍具有正确斜率。不能阵列整个基体,计数包含原齿。安装孔和背部结构按需求选配。
## 独立检查
应一个闭合实体、无失败时间线、两宽度端各N个完整平顶梯形齿。端面两侧`abs(dx/dy)=transverseSlope`,节线上齿厚pt/2,相邻中心距pt;齿顶宽2*halfTip。对应端部齿顶点应`ΔX=rackShift`且ΔZ=b;沿齿宽的直边中点也应在线上,不能只检查截面像齿条。每条工作面都是平面。
```text
体积 = [rackLength*baseThickness + N*(addendum+dedendum)*(halfTip+halfRoot)]*rackWidth
包围盒 = [0,-dedendum-baseThickness,0] 到 [rackLength,addendum,rackWidth]
```
体积不重复计入齿底与基体的重叠。N个齿中心在宽度中面关于L/2对称,整体质心X=L/2、Z=b/2;Y质心需按基体与梯形面积加权,不能填0。用实际`model.edges`端点/中点核对所有齿位、端面压力角和有符号齿线斜率,再看截图与原生参数重建。公式自洽、单齿草图或包围盒正确均不能单独证明最终斜齿齿条正确。
@@ -1,31 +0,0 @@
# 无槽人字齿:齿侧符号、扭转与合并提示
仅用于已选定的端面渐开线、径向简化齿根、等宽反向螺旋输运表示;不是完整建模教程。无槽必须`centralGap=0 mm`,不能用带槽双斜齿代替。不据此声称加工包络或制造级共轭。
保留原生参数链,长度mm、角度显式deg/rad。输入法向模数`normalModule`、齿数`gearTeeth`、法向压力角`normalPressure`、有符号下半臂螺旋角`helixAngle`和总宽`gearWidth`:
```text
halfWidth=(gearWidth-centralGap)/2
transverseModule=normalModule/cos(helixAngle)
gearPressure=atan(tan(normalPressure)/cos(helixAngle))
pitchRadius=transverseModule*gearTeeth/2
baseRadius=pitchRadius*cos(gearPressure)
tipRadius=pitchRadius+normalModule
rootRadius=pitchRadius-1.25*normalModule
toothBaseAngle=90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll=sqrt((tipRadius/baseRadius)^2-1)
halfTwist=halfWidth*tan(helixAngle)/pitchRadius*(1 rad)
```
已发生的错误是把半齿角写成`180 deg/gearTeeth`、把扫掠twist直接填成螺旋角β,以及展开齿侧符号时写反。半齿角必须`90 deg/gearTeeth`,twist用`halfTwist`。要求`0<rootRadius<baseRadius<tipRadius`及`toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)>0`。
下截面Z=0、初相0时,两工作侧分别使用以下原生命令,保留括号;其余闭合与阵列沿原通用技能,不用经验样条代替渐开线:
```json
[
{"command":"sketch.equation_curve","params":{"x":"baseRadius*sqrt(1+t^2)*cos((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","y":"baseRadius*sqrt(1+t^2)*sin((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","start":0,"end":"tipRoll","tolerance":0.002}},
{"command":"sketch.equation_curve","params":{"x":"baseRadius*sqrt(1+t^2)*cos((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","y":"baseRadius*sqrt(1+t^2)*sin((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))","start":0,"end":"tipRoll","tolerance":0.002}}
]
```
下半完整轮廓沿+Z扫掠`halfWidth`,`orientation:parallel,twist:halfTwist,operation:new`;再绕Z=`gearWidth/2`平面镜像整个半体并`combine:true`。不要先建同根圆芯再Join完整扫掠,原参考在重合圆柱面处布尔失败。核对一个连通实体、总宽正确、中面同相连续且两半旋向相反;只看到两只相向斜齿轮不足以通过。
@@ -1,84 +0,0 @@
# 无槽连续人字齿:中面同相的反向螺旋输运 v1.1
外啮合、等宽两臂、无中央退刀槽;`geometry_representation=herringbone-continuous-midplane-v1`、`central_gap_mm=0`。采用端面渐开线及反向等导程螺旋输运,齿根为径向简化,中面是几何尖脊而非加工刀具包络。不把它替换为带槽双斜齿或单向斜齿;不声称制造级中面过渡、共轭接触或全周期无干涉。
## 参数与适用域
输入法向模数mn>0、齿数z=18~30整数、法向压力角αn=20°、有符号下半臂螺旋角β(绝对值5~25°)、总轴向宽W>0;本版等宽、零变位/侧隙、齿顶系数1、顶隙0.25。上半臂旋向反转,不把β解释成两半都同号。可选轴孔/轮毂/键槽仅按用户要求,不据样例强加。
定义可编辑参数:
```text
normalModule=mn mm; gearTeeth=z; normalPressure=20 deg
helixAngle=β deg; gearWidth=W mm; centralGap=0 mm
halfWidth=(gearWidth-centralGap)/2
transverseModule=normalModule/cos(helixAngle)
gearPressure=atan(tan(normalPressure)/cos(helixAngle))
pitchRadius=transverseModule*gearTeeth/2
baseRadius=pitchRadius*cos(gearPressure)
tipRadius=pitchRadius+normalModule
rootRadius=pitchRadius-1.25*normalModule
toothBaseAngle=90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll=sqrt((tipRadius/baseRadius)^2-1)
tipAngle=toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
halfTwist=halfWidth*tan(helixAngle)/pitchRadius*(1 rad)
```
所有半径/宽度单位mm、角度显式deg/rad、roll无量纲。要求`0<rootRadius<baseRadius<tipRadius`、tipAngle>0。若轴孔存在,直径/2须小于rootRadius且保留用户要求壁厚。
## 当前工具构造
先构造下臂完整齿廓并扫掠成new实体Gear,再围绕中面镜像并合并。不要先做同rootRadius芯轴再join整圈扫掠:当前引擎参考出现重合圆柱面布尔失败。镜像下半体保持中面相位并反转旋向,也避免人工重抄上臂截面。下臂截面Z=0、初相φ=0°。
下臂截面的构造是完整单元。令`P(r,a)=[r*cos(φ+a),r*sin(φ+a)]`,`A(t)=toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)`,`R(t)=baseRadius*sqrt(1+t^2)`:
1. `sketch.create {plane:XY,offset:0,name:LowerSection}`。
2. `sketch.line`从P(rootRadius,-toothBaseAngle)到P(baseRadius,-toothBaseAngle),infer:false;`sketch.equation_curve`用x=R(t)*cos(φ-A(t))、y=R(t)*sin(φ-A(t)),start=0,end=tipRoll,tolerance=0.002。
3. 齿顶`sketch.arc.three_point`:start=P(tipRadius,-tipAngle),through=P(tipRadius,0°),end=P(tipRadius,tipAngle);另一工作侧方程曲线用φ+A(t),同一t范围。
4. 第二条line从P(baseRadius,toothBaseAngle)到P(rootRadius,toothBaseAngle)。根圆弧start=P(rootRadius,toothBaseAngle)、through=P(rootRadius,180°/gearTeeth)、end=P(rootRadius,360°/gearTeeth-toothBaseAngle)。端点都用同一个rootRadius,不用rootX*cos(...)代替。
5. 本草图这六实体通常为`l1,s1,a1,s2,l2,a2`;读取实际创建ID后,用`sketch.pattern.circular {entities:这六实体,center:[0,0],count:gearTeeth}`闭合整圈;不要包含一条额外的单齿闭合弦。solve、finish。
两工作侧不要手动展开`φ±A(t)`的符号。下截面φ=0时,负侧角是`-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,正侧角是`toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)`;不是`-toothBaseAngle-inv`或`toothBaseAngle+inv`。在上面第2、3步各自的位置使用对应的原生命令,保留括号;两侧都取t=0到tipRoll:
```json
[
{
"command": "sketch.equation_curve",
"params": {
"x": "baseRadius*sqrt(1+t^2)*cos((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"y": "baseRadius*sqrt(1+t^2)*sin((0 deg)-(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"start": 0,
"end": "tipRoll",
"tolerance": 0.002
}
},
{
"command": "sketch.equation_curve",
"params": {
"x": "baseRadius*sqrt(1+t^2)*cos((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"y": "baseRadius*sqrt(1+t^2)*sin((0 deg)+(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)))",
"start": 0,
"end": "tipRoll",
"tolerance": 0.002
}
}
]
```
下臂路径:YZ草图直线局部点`[[0,0],[0,halfWidth]]`,当前YZ局部第二坐标对应世界+Z。`solid.sweep {sketch:"LowerSection",path_sketch:"LowerPath",path:[实际直线ID],orientation:"parallel",twist:"halfTwist",operation:"new",body_name:"Gear",name:"LowerTeeth"}`。
然后调用完整镜像:
```json
{"command":"solid.mirror","params":{"bodies":["Gear"],"plane":{"origin":[0,0,"gearWidth/2"],"normal":[0,0,1]},"combine":true,"name":"OppositeHandHalf"}}
```
镜像的是半体,不是只复制源草图或让第二半与第一半同向旋转。孔等减料最后切,显式targets=[Gear];两半仍由同一参数链控制。
## 最终几何与编辑检查
一个闭合连通实体,无失败时间线,轴线Z,总宽W;中面Z=W/2同一齿的两工作侧必须同相连续,不允许错半齿、中间空隙、重叠第二实体。沿+Z下臂角位置`θ(z)=z*tanβ/pitchRadius`;上臂`θ(z)=halfTwist-(z-halfWidth)*tanβ/pitchRadius`,两端相位相同、中面同相,导数反号。仅“左右各一斜齿轮”不够。
实际最终齿侧采样:r在[baseRadius,tipRadius],t=sqrt((r/baseRadius)^2-1),应满足`arg(x+iy)-θ(z)=2*pi*k/z±[toothBaseAngle-(t-atan(t))]`(此检查式角度统一rad)。分别覆盖两臂、端面和中面邻域,检查端面齿数和径向范围;`inspect.curvature_comb`只用`combs[].teeth[][0]`实际求值脚点。model.edges.mid只作拾取,不当曲线真值。
体积可与同一端面实际/解析面积S乘W再减轴孔核对; 解析截面面积可用`S=pi*rf^2+z*(rb^2*ta^3/3+ra^2*(A-ta+atan(ta))-rf^2*A)`,其中rf/rb/ra对应根/基/顶半径、ta=tipRoll、A=toothBaseAngle换成rad数值,atan同样为rad数值。最终拟合面仍须采样。改mn/z/β/W后两臂共用同一派生链,重建检查中面位置、halfTwist、反向旋向和连续性。有限采样不证明全域误差或制造接触能力。
@@ -1,57 +0,0 @@
# 无槽连续人字齿:中面同相的反向螺旋输运 v1
外啮合、等宽两臂、无中央退刀槽;`geometry_representation=herringbone-continuous-midplane-v1`、`central_gap_mm=0`。采用端面渐开线及反向等导程螺旋输运,齿根为径向简化,中面是几何尖脊而非加工刀具包络。不把它替换为带槽双斜齿或单向斜齿;不声称制造级中面过渡、共轭接触或全周期无干涉。
## 参数与适用域
输入法向模数mn>0、齿数z=18~30整数、法向压力角αn=20°、有符号下半臂螺旋角β(绝对值5~25°)、总轴向宽W>0;本版等宽、零变位/侧隙、齿顶系数1、顶隙0.25。上半臂旋向反转,不把β解释成两半都同号。可选轴孔/轮毂/键槽仅按用户要求,不据样例强加。
定义可编辑参数:
```text
normalModule=mn mm; gearTeeth=z; normalPressure=20 deg
helixAngle=β deg; gearWidth=W mm; centralGap=0 mm
halfWidth=(gearWidth-centralGap)/2
transverseModule=normalModule/cos(helixAngle)
gearPressure=atan(tan(normalPressure)/cos(helixAngle))
pitchRadius=transverseModule*gearTeeth/2
baseRadius=pitchRadius*cos(gearPressure)
tipRadius=pitchRadius+normalModule
rootRadius=pitchRadius-1.25*normalModule
toothBaseAngle=90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll=sqrt((tipRadius/baseRadius)^2-1)
tipAngle=toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
halfTwist=halfWidth*tan(helixAngle)/pitchRadius*(1 rad)
```
所有半径/宽度单位mm、角度显式deg/rad、roll无量纲。要求`0<rootRadius<baseRadius<tipRadius`、tipAngle>0。若轴孔存在,直径/2须小于rootRadius且保留用户要求壁厚。
## 当前工具构造
先构造下臂完整齿廓并扫掠成new实体Gear,再围绕中面镜像并合并。不要先做同rootRadius芯轴再join整圈扫掠:当前引擎参考出现重合圆柱面布尔失败。镜像下半体保持中面相位并反转旋向,也避免人工重抄上臂截面。下臂截面Z=0、初相φ=0°。
下臂截面的构造是完整单元。令`P(r,a)=[r*cos(φ+a),r*sin(φ+a)]`,`A(t)=toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)`,`R(t)=baseRadius*sqrt(1+t^2)`:
1. `sketch.create {plane:XY,offset:0,name:LowerSection}`。
2. `sketch.line`从P(rootRadius,-toothBaseAngle)到P(baseRadius,-toothBaseAngle),infer:false;`sketch.equation_curve`用x=R(t)*cos(φ-A(t))、y=R(t)*sin(φ-A(t)),start=0,end=tipRoll,tolerance=0.002。
3. 齿顶`sketch.arc.three_point`:start=P(tipRadius,-tipAngle),through=P(tipRadius,0°),end=P(tipRadius,tipAngle);另一工作侧方程曲线用φ+A(t),同一t范围。
4. 第二条line从P(baseRadius,toothBaseAngle)到P(rootRadius,toothBaseAngle)。根圆弧start=P(rootRadius,toothBaseAngle)、through=P(rootRadius,180°/gearTeeth)、end=P(rootRadius,360°/gearTeeth-toothBaseAngle)。端点都用同一个rootRadius,不用rootX*cos(...)代替。
5. 本草图这六实体通常为`l1,s1,a1,s2,l2,a2`;读取实际创建ID后,用`sketch.pattern.circular {entities:这六实体,center:[0,0],count:gearTeeth}`闭合整圈;不要包含一条额外的单齿闭合弦。solve、finish。
下臂路径:YZ草图直线局部点`[[0,0],[0,halfWidth]]`,当前YZ局部第二坐标对应世界+Z。`solid.sweep {sketch:"LowerSection",path_sketch:"LowerPath",path:[实际直线ID],orientation:"parallel",twist:"halfTwist",operation:"new",body_name:"Gear",name:"LowerTeeth"}`。
然后调用完整镜像:
```json
{"command":"solid.mirror","params":{"bodies":["Gear"],"plane":{"origin":[0,0,"gearWidth/2"],"normal":[0,0,1]},"combine":true,"name":"OppositeHandHalf"}}
```
镜像的是半体,不是只复制源草图或让第二半与第一半同向旋转。孔等减料最后切,显式targets=[Gear];两半仍由同一参数链控制。
## 最终几何与编辑检查
一个闭合连通实体,无失败时间线,轴线Z,总宽W;中面Z=W/2同一齿的两工作侧必须同相连续,不允许错半齿、中间空隙、重叠第二实体。沿+Z下臂角位置`θ(z)=z*tanβ/pitchRadius`;上臂`θ(z)=halfTwist-(z-halfWidth)*tanβ/pitchRadius`,两端相位相同、中面同相,导数反号。仅“左右各一斜齿轮”不够。
实际最终齿侧采样:r在[baseRadius,tipRadius],t=sqrt((r/baseRadius)^2-1),应满足`arg(x+iy)-θ(z)=2*pi*k/z±[toothBaseAngle-(t-atan(t))]`(此检查式角度统一rad)。分别覆盖两臂、端面和中面邻域,检查端面齿数和径向范围;`inspect.curvature_comb`只用`combs[].teeth[][0]`实际求值脚点。model.edges.mid只作拾取,不当曲线真值。
体积可与同一端面实际/解析面积S乘W再减轴孔核对; 解析截面面积可用`S=pi*rf^2+z*(rb^2*ta^3/3+ra^2*(A-ta+atan(ta))-rf^2*A)`,其中rf/rb/ra对应根/基/顶半径、ta=tipRoll、A=toothBaseAngle换成rad数值,atan同样为rad数值。最终拟合面仍须采样。改mn/z/β/W后两臂共用同一派生链,重建检查中面位置、halfTwist、反向旋向和连续性。有限采样不证明全域误差或制造接触能力。
@@ -1,17 +0,0 @@
# 外六角螺栓:对边基准与简化螺纹 v1
仅非标准示意外六角头+圆柱杆的单体,`geometry_representation=hex-bolt-simplified-thread-v1`。simplified表示保留公称外径圆柱、记录螺纹区,不生成真实牙型。真实螺纹、内六角、法兰、螺母和标准规格查表不在本规程内;不把M8自动替换成样例尺寸。
## 参数与当前工具构造
明确正mm参数:公称杆径d、头下长度L、六角对边s、头高k、螺纹区长度b;可选螺距p只作语义标注。要求s>d、0<b<=L。轴为Z,杆端Z=0,承压面Z=L,头顶Z=L+k;含头总长不是L。
1. `solid.cylinder {diameter:"nominalDiameter",height:"underHeadLength",operation:"new",body_name:"Bolt"}`。
2. `headRadius=acrossFlats/sqrt(3)`,不是s/2。在`sketch.create {plane:"XY",offset:"underHeadLength",name:"HexHead"}`中,用`sketch.line`构造六顶点闭合折线:第i点`[headRadius*cos(i*60 deg),headRadius*sin(i*60 deg)]`,i=0…5,`closed:true,infer:false`。solve、finish后`solid.extrude {sketch:"HexHead",distance:"headHeight",operation:"join",targets:["Bolt"]}`。
3. 将threadLength、可选threadPitch保留为原生参数,并用`parameters.comment {name:"threadLength",comment:"简化螺纹区:杆端Z=0至threadLength;圆柱实体,无真实牙型"}`记录表示。不要切环槽或默认加倒角来假冒螺纹;如果导出只含实体,交付时说明语义标注可能需要伴随记录。
## 检查
一个闭合实体;杆径d、杆圆柱绝对Z区间[0,L]、六角头Z=[L,L+k],六个侧面、三组对边均为s。首顶点朝+X时Y包络±s/2,X包络±s/sqrt(3);其他合法绕Z相位也应以对边与六侧形状判断,不能只锁定参考相位。无倒角/切牙体积`pi*d^2*L/4+sqrt(3)*s^2*k/2`。
增大L应移动整个头部且不改k;增大k只增长头顶。改b/p不改变当前几何体积,语义应仍在。未核查标准表和真实牙型,不声称标准螺栓或制造级螺纹。
@@ -1,53 +0,0 @@
# 内渐开线直齿轮:环坯与齿槽切除规程 v1
实验候选,尚待真实引擎回放和正式助手生成验证。适用20°压力角、零变位、零侧隙、齿顶高系数1、顶隙系数0.25,36~100齿,并须满足内齿顶圆半径大于基圆半径。仅简化圆弧齿根槽底,不声称制造级包络齿根。模数、齿数、齿宽和外径来自用户;不能把外齿轮缩小后塞进圆环代替内齿轮。
## 参数与齿制方向
`parameters.add` 的长度用 `unit:"mm"`、角度用 `unit:"deg"`、无量纲用 `unit:""`。不使用单位保留名m,不创建t参数。
```text
gearModule, gearWidth, outerRadius = 用户尺寸 [mm]
gearTeeth = 用户齿数 [无量纲]
gearPressure = 20 deg
pitchRadius = gearModule*gearTeeth/2 [mm]
baseRadius = pitchRadius*cos(gearPressure) [mm]
tipRadius = pitchRadius-gearModule [mm]
rootRadius = pitchRadius+1.25*gearModule [mm]
spaceBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad) [deg]
tipRoll = sqrt((tipRadius/baseRadius)^2-1) [无量纲]
rootRoll = sqrt((rootRadius/baseRadius)^2-1) [无量纲]
tipAngle = spaceBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad) [deg]
rootAngle = spaceBaseAngle-(rootRoll-atan(rootRoll)/(1 rad))*(1 rad) [deg]
innerCloseRadius = tipRadius-0.25*gearModule [mm]
```
必须 `outerRadius>rootRadius>tipRadius>baseRadius>0`、`rootAngle>0`、`tipAngle<180 deg/gearTeeth`。不满足就报告范围缺口,不能对负数开方或改成外齿公式。**内齿的齿顶在内、齿根在外**。以下构造的是以+X为中心的一个空齿槽;实体齿中心在相邻槽之间。若用户要求一齿朝+X,应将整套槽的方位偏移半个齿距,不能混淆齿中心与槽中心。
## 环坯与一个可切除齿槽
先建外圆柱,再以 `radius:"tipRadius"` 的贯穿圆柱切开环坯,两个调用都显式指定 `operation`、`targets`。环坯名为`RingGear`。建立`sketch.create {plane:"XY",offset:-1,name:"RingSpaceProfile"}`。下列曲线在同一草图中按端点组成闭合轮廓;角度表达式中的`atan(t)/(1 rad)`不可省略单位换算。
```text
R(t)=baseRadius*sqrt(1+t^2)
A(t)=spaceBaseAngle-(t-atan(t)/(1 rad))*(1 rad)
```
1. `sketch.line` 从 `[innerCloseRadius*cos(tipAngle),-innerCloseRadius*sin(tipAngle)]` 到 `[tipRadius*cos(tipAngle),-tipRadius*sin(tipAngle)]`,`infer:false`。
2. `sketch.equation_curve {x:"baseRadius*sqrt(1+t^2)*cos(spaceBaseAngle-(t-atan(t)/(1 rad))*(1 rad))", y:"-baseRadius*sqrt(1+t^2)*sin(spaceBaseAngle-(t-atan(t)/(1 rad))*(1 rad))",start:"tipRoll",end:"rootRoll",tolerance:0.002}`。
3. `sketch.arc.three_point`:start=`[rootRadius*cos(rootAngle),-rootRadius*sin(rootAngle)]`、through=`[rootRadius,0]`、end=`[rootRadius*cos(rootAngle),rootRadius*sin(rootAngle)]`。这段是明确简化的齿根槽底圆弧。
4. 第二条方程曲线保持同一x,y改为正号,其他参数不变。
5. `sketch.line` 从上侧齿顶点经上侧innerCloseRadius点回到下侧innerCloseRadius点,`infer:false`。内侧闭合线位于已切除圆孔内,避免只贴到孔壁。
必须一个闭合区域,实际曲线半径从tipRadius增至rootRadius,两条工作齿廓均为渐开线。`tolerance`是数值字面量,不能写长度参数名。`sketch.finish`后:
```json
{"command":"solid.extrude","params":{"sketch":"RingSpaceProfile","distance":"gearWidth+2","operation":"cut","targets":["RingGear"],"name":"RingSpace"}}
{"command":"solid.pattern.circular","params":{"features":["RingSpace"],"axis":"Z","count":"gearTeeth"}}
```
阵列已切入环坯的**槽特征**,不阵列整个环坯;内孔与所有槽贯通,外缘仍为一个连续环。轮缘厚度由`outerRadius-rootRadius`检查,不能让槽切穿外圆。附加安装孔仅按需求添加,不能把“中心孔”再次按外齿轮轴孔切大而抹掉内齿。
## 检查
一闭合实体、无失败时间线、外径和齿宽正确、内齿数正确;顶视有向内伸出的齿且槽底未穿外缘。分度圆的实体齿厚与槽宽均应为`pi*gearModule/2`。独立采样两条实际样条,检查渐开线误差与tipRadius~rootRadius覆盖,再核对截面积/体积;仅外圆包围盒正确不能证明有内齿。改变模数、齿数、齿宽时重新检查适用不等式、参数重建和最薄轮缘。
@@ -1,58 +0,0 @@
# 外啮合零变位直齿轮:方程曲线操作规程 v2
适用:20°压力角、零变位、零侧隙、齿顶高系数1、顶隙系数0.25,当前试点18~40齿且齿根圆小于基圆;基圆以下径向简化。尺寸来自用户。当前引擎已成功回放20/24/32齿;LLM收益仍需试验。
## 参数
用 `parameters.add` 登记以下参数。长度显式 `unit:"mm"`,角度 `unit:"deg"`,无量纲 `unit:""`。不使用单位保留名m。工具 `describe_command` 接收 `{"id":"sketch.equation_curve"}`;引擎命令放在 execute 的 command/params 或 batch 的 commands 数组中。
```text
gearModule, gearWidth, hubDiameter, hubHeight, boreDiameter, keyWidth, keyReach = 用户尺寸 [mm]
gearTeeth = 用户齿数 [unit=""]
gearPressure = 20 deg
pitchRadius = gearModule*gearTeeth/2 [mm]
baseRadius = pitchRadius*cos(gearPressure) [mm]
tipRadius = pitchRadius+gearModule [mm]
rootRadius = pitchRadius-1.25*gearModule [mm]
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad) [deg]
tipRoll = sqrt((tipRadius/baseRadius)^2-1) [unit=""]
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad) [deg]
baseX = baseRadius*cos(toothBaseAngle) [mm]
baseY = baseRadius*sin(toothBaseAngle) [mm]
rootX = rootRadius*cos(toothBaseAngle) [mm]
rootY = rootRadius*sin(toothBaseAngle) [mm]
tipX = tipRadius*cos(tipAngle) [mm]
tipY = tipRadius*sin(tipAngle) [mm]
```
`atan(t)`为带单位角度,除以`1 rad`后才是无单位弧度数。按上述表达式处理角度。t是方程曲线的自变量,不创建名为t的用户参数。
## 可执行单齿
先 `solid.cylinder {radius:"rootRadius",height:"gearWidth",operation:"new",body_name:"Gear",name:"GearRoot"}`,再 `sketch.create {plane:"XY",name:"GearToothProfile"}`。
按顺序调用以下五条命令;两条方程曲线各只定义一次,不展开几十个采样点。x/y中的`baseRadius*sqrt(1+t^2)`是随t增长的半径,保留完整公式。
```json
[
{"command":"sketch.line","params":{"points":[["rootX","-rootY"],["baseX","-baseY"]],"infer":false}},
{"command":"sketch.equation_curve","params":{"x":"baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))","y":"-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))","start":0,"end":"tipRoll","tolerance":0.002}},
{"command":"sketch.arc.three_point","params":{"start":["tipX","-tipY"],"through":["tipRadius",0],"end":["tipX","tipY"]}},
{"command":"sketch.equation_curve","params":{"x":"baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))","y":"baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))","start":0,"end":"tipRoll","tolerance":0.002}},
{"command":"sketch.line","params":{"points":[["baseX","baseY"],["rootX","rootY"],["rootX","-rootY"]],"infer":false}}
]
```
调用`sketch.solve`及`sketch.inspect {sketch:"GearToothProfile"}`。必须一个闭合区域;实际样条点应从基圆增长到齿顶圆;齿顶圆弧的实际圆心为(0,0)、半径为tipRadius。出现小圆包或所有点半径相同就修正单齿,不能因为闭合就继续阵列。方程曲线由引擎按tolerance拟合并随参数重算;tolerance不是制造认证。
随后`sketch.finish`,`solid.extrude {sketch:"GearToothProfile",distance:"gearWidth",operation:"join",targets:["Gear"],name:"GearTooth"}`,再`solid.pattern.circular {features:["GearTooth"],axis:"Z",count:"gearTeeth"}`。该闭合单齿与根盘有实体搭接,阵列的是已Join的特征,保持单实体。
## 轮毂、孔、键槽和验收
在Z=gearWidth加入轮毂后再切孔槽,切除贯穿全高且超出端面1mm。轮毂和孔用solid.cylinder,显式operation/targets。当前正X键槽已回放的调用是:
```json
{"command":"solid.box","params":{"corner":[0,"-keyWidth/2",-1],"length":"keyReach","width":"keyWidth","height":"gearWidth+hubHeight+2","operation":"cut","targets":["Gear"],"name":"GearKeyway"}}
```
这里keyReach是用户给定的槽底X坐标,槽从孔腔切至该处,不能把矩形起点放在孔圆周而留下月牙。最后核对一闭合实体、无失败特征、顶视齿数/齿厚/齿间空隙、轮毂高度、贯通轴孔和键槽连通。包围盒正确不能证明齿形正确。24齿/模数2.5的验算锚点:基圆半径28.190778624、齿顶半径32.5、上侧齿顶点(32.487692786,0.894325136)。其他输入重新计算,不套此坐标。
@@ -1,17 +0,0 @@
# 带孔安装板:中心基准与独立通孔 v1
仅矩形等厚单体板、互不接触的圆形通孔,孔轴为局部Z。`geometry_representation=rectangular-plate-z-through-holes-v1`。不把沉孔、盲孔、长圆孔、折弯或夹层改成此结构;外形、孔数和孔径不取示例默认值。
## 参数与构造
长度L沿X、宽W沿Y、厚T从Z=0到T,均为正mm。逐孔输入`(xi,yi,di)`,孔心以板面中心为原点;“距边”先区分孔心退边和孔边净距。等径阵列只有用户明确要求时才使用,count是包含原孔的总数。
定义可编辑参数,再用`solid.box {corner:["-plateLength/2","-plateWidth/2",0],length:"plateLength",width:"plateWidth",height:"plateThickness",operation:"new",body_name:"Plate"}`。每孔用`solid.cylinder {diameter:"hole1Diameter",height:"plateThickness+2 mm",base:["hole1X","hole1Y",-1],operation:"cut",targets:["Plate"]}`,其余孔分别引用自己的参数;1mm只是切除工具的端部余量,不改变板厚。
切除前必须满足`abs(xi)+di/2<L/2`、`abs(yi)+di/2<W/2`,且任意孔心距`> (di+dj)/2`。重叠、相切或越界不静默改成联合槽。知识接口的hole_count只是布局声明,不替代逐孔位置检查。
## 检查与修改
一个闭合实体;绝对包络`[-L/2,L/2]×[-W/2,W/2]×[0,T]`,逐孔半径di/2、轴向Z、轴线XY=(xi,yi),材料内孔面从Z=0贯通到T。仅比较孔深长度会漏掉封闭内腔,须核对绝对区间和两个开口边界。体积`L*W*T-sum(pi*di^2*T/4)`仅适用于以上独立完整圆通孔。圆柱面可能分片,不能把面数直接当孔数。
改板厚后所有孔仍贯通新厚度;改孔坐标/直径只影响相应孔。重查边界、孔间材料、体积与时间线,不能靠最大外包络代替孔系验收。
@@ -1,30 +0,0 @@
# 单级直齿行星机构:几何闭合、相位与Willis关系 v1
实验候选。仅用于已明确的同模数、同压力角、零变位直齿太阳轮+等齿数等分行星轮+内齿圈+行星架。构造部件时按需读取`involute-spur-gear`和`internal-spur-gear`,不在此重复齿廓公式。齿轮分别保留,不能Join成一个实体;行星架和销可构成一个独立零件。
## 必须先满足的关系
太阳轮zs、行星轮zp、齿圈zr、行星数量n与m须明确。分度半径rs=m*zs/2、rp=m*zp/2、rr=m*zr/2;共同轨道半径a=rs+rp=rr−rp,因此`zr=zs+2*zp`。等分装配要求`(zs+zr)/n`为整数。相邻行星中心距`2*a*sin(180 deg/n)`必须大于两行星齿顶半径之和并留需求间隙;还要检查齿圈剩余壁厚。任一关系冲突应指出,不自动改齿数。
太阳轮和齿圈同轴Z且同心;行星中心为`(a*cosγi,a*sinγi)`、`γi=360 deg*i/n`,所有轮轴平行。齿宽Z区间相同。行星架位于齿轮端面之外,保留轴向间隙,销轴与行星孔同轴且有明确间隙;销只Join到行星架,不能误把行星轮一起连接。孔、架板厚度和销径是独立尺寸,不能凭类别猜标准值。
## 相位而不只是等分位置
以太阳轮本地一齿中心朝+X且φs=0,内齿圈单体规程以一**齿槽**中心朝+X。每个行星轮取:
```text
φpi = ((zs+zp)/zp)*γi + 180 deg - 180 deg/zp - (zs/zp)*φs
φr = (180 deg*(zp-1) - zs*φs)/zr
```
相位可加该轮整齿距。以上同时满足太阳轮外啮合与齿圈内啮合;不能三个行星全部同一绝对角度,仅按位置阵列。每轮先在原点完成齿形和孔,再用`solid.move {bodies:[轮],axis:[0,0,1],angle:φ,translate:[cx,cy,0]}`旋转后平移。各轮参数/草图/实体独立命名,共同模数、轨道半径和相位保留表达式。
参考zs18/zp18/zr54、n3满足闭合与等分;m1.5时轨道半径27mm,行星中心角0/120/240°。这些是试验值,不是默认方案。修改齿数或数量后重新检查装配条件、相位和邻轮间隙。
## 检查和按需运动
检查太阳轮1、内齿圈1、行星n个、行星架1个独立零件,孔轴/销轴、壁厚、轴向间隙、各部件齿形、齿数和相位;用实际端面轮廓与测量核验,不能凭名字判定。静态展示不必增加运动步骤。简化齿根不是制造级传动认证。
要求运动时先明确固定件、输入件和输出件。Willis关系为`zs*(ωs−ωc)+zr*(ωr−ωc)=0`。齿圈固定、太阳轮输入时`ωc/ωs=zs/(zs+zr)`,行星相对架速度`(ωp−ωc)/(ωs−ωc)=−zs/zp`。18/18/54示例:太阳转360°,架转90°,行星相对架转−270°,行星绝对自转−180°。不能把固定轴的两组joint.gear直接套到会公转的行星上。
沿原机构Skill建立同轴架关节及架上的行星revolute,采用既有约束/运动链接表达所选固定件的解析关系,驱动后读取各关节值、moved和行星中心轨迹。运动比值、无干涉检查和齿面接触分别验证;未实际驱动时仅记录解析预期。
@@ -1,23 +0,0 @@
# 直齿轮齿条传动:节线、相位与行程 v1
实验候选。仅用于已明确的渐开线直齿圆柱齿轮配直齿齿条,零变位、相同模数/压力角。此文补充组合接口;构造部件时按需分别查询`involute-spur-gear`与`straight-rack`,不复制整套齿廓,也不把运动链接当几何工具。
## 共同尺寸链
共同模数m、齿轮齿数z、齿条有效齿数N、齿宽及底板厚度由需求确定。齿距p=πm,齿轮分度半径r=m*z/2;齿条节线到轮轴的垂直距离为r,不是齿顶半径。齿条参考长度L=N*p;实际端部若需额外无齿长度单独记录,不混成完整齿数。两部件齿宽区间需要重叠。
标准坐标:齿条沿+X,节线Y=0,齿顶朝+Y;轮轴Z,轮心(Xc,r),初始Xc=L/2。Z方向两个部件同宽,保持两个独立实体。孔轴随轮心,不留在全局原点。各部件独立命名,m、p、r和Xc共享参数表达式。
## 初始相位
现有齿条参考第一个齿中心位于p/2,后续为(j+1/2)p。若N为偶数,Xc=L/2恰在齿槽中心,齿轮初相位φ=−90 deg,使其本地+X齿中心转向接触点的−Y。若N为奇数,Xc处是齿条齿中心,取φ=−90 deg−180 deg/z,让轮的齿槽对准。不要同时使齿条齿中心和齿轮齿中心对准接触点。
一般Xc时,取`φ=−90 deg−(Xc/p−N/2)*360 deg/z`是从偶数N标准槽中心移动的等价连续相位;奇数N还需上述半齿距偏置。修改Xc、齿数或齿条起点后重新核对,不只移动轮心。
在原点按单轮规程完成齿形和孔,再`solid.move {bodies:[齿轮],axis:[0,0,1],angle:φ,translate:[Xc,r,0]}`。齿条已按世界节线位置建立则不再移动。不要把齿轮与齿条Join,避免修改孔的cut误伤另一实体,显式targets。
## 复核与可选运动
检查两闭合实体、r和节线、齿距、齿数、齿侧压力角、相位、轴向重叠和实际初始齿顶/槽关系。行程必须在齿条有效齿段内,不能默认无限平移。仅静态生成时不必增加运动步骤。
要求运动时沿原机构Skill建齿轮revolute与沿X的齿条slider,固定支承,使用`joint.rack_pinion {a:轮关节,b:齿条关节,radius:r}`。本坐标中轮绕+Z正转,接触点切向速度为+X,齿条应向+X;若slider正轴反向则用reverse。位移s=r*θ_rad,关节角以度输入时`s=r*pi/180*θ_deg`。m2/z20,轮转30°对应齿条+10.4719755mm。驱动后读取实际位移与moved,并回到指定保存位置;未实测不能声称运动通过。
@@ -1,23 +0,0 @@
# 带筋轴承座裸座体:Y孔、Z安装孔与先并后切 v1
`geometry_representation=ribbed-housing-y-bore-z-mount-v1`:整体裸座体、底板、矩形支承、圆柱凸台、±X两侧三角筋;只按要求加安装圆通孔及负Y端同轴台阶。分体座、轴承、端盖、密封、油路不在本法内。
## 基准与参数
正mm:底板L×W×T,凸台外径D/Y向宽B、座孔d、中心高C(从底面Z=0量)、支承X宽P、筋厚t/Y向、外伸a/X向、高h/Z向,最小材料厚w。底板XY居中,凸台轴线`(0,Y,C)`。要求`0<P<D`、`C-D/2>=T`、`C-d/2-T>=w`、`(D-d)/2>=w`、`0<h<=C-T`,筋外端`P/2+a<L/2`,筋厚<=B。安装孔必须在板内且避让支承、凸台/筋的投影;缺尺寸先补齐,不复制样例。
## 当前工具构造
先生成连续加料主体,最后切孔,避免后加筋堵回座孔:
1. `solid.box`底板corner=`[-L/2,-W/2,0]`,new,命名Housing;支承corner=`[-P/2,-B/2,T]`、长P宽B高C-T,join targets=[Housing]。
2. 凸台`solid.cylinder {diameter:"bossDiameter",height:"bossWidth",base:[0,"-bossWidth/2","centerHeight"],axis:[0,1,0],operation:"join",targets:["Housing"]}`。
3. 两筋各在XZ草图,offset=`-ribThickness/2`。当前XZ草图局部第二坐标是世界负Z,右筋三点`[P/2,-T]、[P/2+a,-T]、[P/2,-T-h]`,左筋X取反,闭合折线solve/finish,`solid.extrude distance:ribThickness,operation:join,targets:[Housing]`。当前XZ法向+Y而局部y_dir为-Z;沿Y从-t/2到+t/2;不能把筋放在凸台端面或用矩形条代替三角筋。
4. 座孔显式axis=[0,1,0]、base=[0,-B/2-1,C]、height=B+2;cut只指向Housing。安装孔显式沿Z,base=[xi,yi,-1]、height=T+2,不能和座孔共用默认方向。
5. 可选负Y台阶大径Dc、深q:要求d<Dc<=D-2w、0<q<B。`solid.cylinder {diameter:"counterboreDiameter",height:"counterboreDepth",base:[0,"-bossWidth/2","centerHeight"],axis:[0,1,0],operation:"cut",targets:["Housing"]}`;从负Y外端向+Y切,不把q当贯穿宽度。
## 检查与修改
一个闭合连通实体,总高C+D/2,底面Z=0;圆柱座孔同轴于Y,负Y台阶实际区间[-B/2,-B/2+q],小径区间[-B/2+q,B/2](无台阶时为[-B/2,B/2]);每个Z向安装孔的材料内区间[0,T]。核对开口和肩面,不能只比较跨度长度。
两筋应在Y=±t/2之间,三角轮廓、厚度、底板连接和支承连接均检查;一体和正体积不能替代筋形状验收。局部壁厚含大孔端,不能沿用小径的名义径向壁厚。修改C/B/P、孔径或筋后重建并检查全部孔区间、连接和壁厚;实际曲面/边采样为有限验证,不证明强度、配合公差或制造能力。
@@ -1,56 +0,0 @@
# 螺旋锥齿轮:截面缩放与线性轴向扭转近似 v1
实验候选;参考操作尚需当前引擎回放。用户接受结构示意时使用;交付明确写“端面渐开线缩放+线性轴向扭转近似,径向简化齿根”。本模型有真实锥度和连续弯曲齿线,但不是Gleason/Klingelnberg等加工生成齿面,也不是恒螺旋角的对数螺旋或制造级共轭齿面。不得无说明地改为等径斜齿轮或三角齿。
## 参数含义和边界
外齿、零变位/侧隙;大端端面压力角20°、齿顶高系数1、顶隙系数0.25为本近似的显式假设。18~40齿、分度锥半角δ20~65°;中齿宽处齿线角绝对值5~35°。m是大端端面模数,不是法向模数。大端Z=0,小端Z=H。δ指轴线与分度锥母线夹角;H为轴向高度,母线齿宽b应换算H=b*cosδ。输入齿线角β定义在**轴向中高处的分度锥面上、相对朝小端的母线方向**;沿+Z方位角增加取正,反向取负,不能由截图猜旋向。若用户要求真实齿制、恒角对数齿线或未明确接受该近似,说明范围差异,不把近似当已满足。
用`parameters.add`,长度mm、角度deg、无量纲unit空字符串。独立输入`largeModule,gearTeeth,pitchConeAngle,axialHeight,boreDiameter,midfaceSpiralAngle`,派生:
```text
gearPressure = 20 deg
pitchRadius = largeModule*gearTeeth/2
baseRadius = pitchRadius*cos(gearPressure)
tipRadius = pitchRadius+largeModule
rootRadius = pitchRadius-1.25*largeModule
apexHeight = pitchRadius/tan(pitchConeAngle)
endScale = 1-axialHeight/apexHeight
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll = sqrt((tipRadius/baseRadius)^2-1)
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
totalToothTwist = axialHeight*tan(midfaceSpiralAngle)/(pitchRadius*(1+endScale)/2*cos(pitchConeAngle))*(1 rad)
rootX = rootRadius*cos(toothBaseAngle)
rootY = rootRadius*sin(toothBaseAngle)
baseX = baseRadius*cos(toothBaseAngle)
baseY = baseRadius*sin(toothBaseAngle)
tipX = tipRadius*cos(tipAngle)
tipY = tipRadius*sin(tipAngle)
```
`endScale,tipRoll,gearTeeth`无量纲;各Angle、totalToothTwist是角度;半径/坐标/高度mm。必须`0.45<=endScale<=0.9`、`0<rootRadius<baseRadius`、`0<tipAngle<toothBaseAngle<180 deg/gearTeeth`;孔半径低于小端齿根。atan结果带角度,除`1 rad`才变为弧度数。
## 一个完整截面整体扫掠
XY草图`BevelLargeSection`按以下顺序建立开口扇区链:
1. 下侧线l1:`[rootX,-rootY]→[baseX,-baseY]`,infer:false。
2. `sketch.equation_curve` s1:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y=`-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,`start:0,end:"tipRoll",tolerance:0.002`。
3. `sketch.arc.three_point` a1:start=`[tipX,-tipY]`、through=`[tipRadius,0]`、end=`[tipX,tipY]`。
4. 第二条方程曲线s2:x同s1、y去负号,范围和数值tolerance同s1。
5. 上侧线l2:`[baseX,baseY]→[rootX,rootY]`,infer:false。
6. `sketch.arc.three_point`根部间隙弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/gearTeeth),rootRadius*sin(180 deg/gearTeeth)]`,end=`[rootRadius*cos(360 deg/gearTeeth-toothBaseAngle),rootRadius*sin(360 deg/gearTeeth-toothBaseAngle)]`。
不加弦线闭合单齿。调用`sketch.pattern.circular {entities:["l1","s1","a1","s2","l2","a2"],center:[0,0],count:"gearTeeth"}`,形成唯一完整齿圈,solve后finish。不要逐齿扭转并布尔阵列,以免复杂齿面接缝失败。
轴线路径:`sketch.create {plane:"YZ",name:"BevelAxisPath"}`,`sketch.line {points:[[0,0],[0,"axialHeight"]],infer:false}`→l1,finish。YZ局部y为世界Z;路径起点必须在齿圈中心,不能放到齿中心使它自转。
```json
{"command":"solid.sweep","params":{"sketch":"BevelLargeSection","path_sketch":"BevelAxisPath","path":["l1"],"orientation":"parallel","scale":"endScale","twist":"totalToothTwist","operation":"new","body_name":"BevelGear","name":"BevelApproximateSweep"}}
```
圆柱通孔后续单独切除,base=[0,0,-1]、height=axialHeight+2,显式targets。轮毂、孔槽按用户选配,不强加。不要再次阵列完整齿圈,也不能让圆孔跟随截面缩放变成锥孔。
## 实际几何检查
一闭合实体、无时间线错误、两端齿数正确,半径随Z按`s(z)=1-z/apexHeight`缩小,轮齿相位按`theta(z)=totalToothTwist*z/axialHeight`变化。中高相位必须为总twist一半;同源基点、顶点和实际齿面采样逆转相位并除以s(z)后,应落在同一大端端面渐开线/径向根线轮廓。实际中高齿线角满足`tanβ=rp_mid*(totalTwist/H)*cosδ`;大小端齿线角不同,不能把β声称全宽恒定。体积为`A0*H*(1+s+s^2)/3`减圆孔体积,与正负旋向无关,故体积不能证明旋向。保存原生设计、iso/top/right截图并改变齿数、锥角和旋向复核。参考两例:m2/24齿/δ45°/H8/孔8/β+25°;m1.5/28齿/δ35°/H7/孔6/β-20°。这是显式近似的检查,不是制造认证。
@@ -1,15 +0,0 @@
# 实心台阶轴:有序段与累计基准 v1
`geometry_representation=coaxial-solid-stepped-shaft-v1`,2~16个正长度实心同轴圆柱段,至少两个相邻直径不同。锐利台肩;孔、键槽、螺纹、圆角不自动添加。本法不覆盖锥轴、偏心轴或空心轴。
## 参数与构造
轴为局部Z,有序输入`(d1,l1)…(dn,ln)`,单位mm,先确定从哪一个端面开始。每段长度是该段独占长度,不是距起点的累计位置。定义`segment1Start=0 mm`,其后`segmentIStart=segment(I-1)Start+segment(I-1)Length`。
首段`solid.cylinder {diameter:"segment1Diameter",height:"segment1Length",base:[0,0,"segment1Start"],operation:"new",body_name:"Shaft"}`;后续段使用自己的直径、长度、起点,`operation:"join",targets:["Shaft"]`。相接端面同轴、坐标来自同一累计链,不能把各圆柱都放在Z=0,不能把直径当半径。
## 检查与修改
一个闭合连通实体。逐段检查半径di/2、轴线X=Y=0、绝对Z区间`[sum(lj,j<i),sum(lj,j<=i)]`,包括每个中间台肩;总长`sum(li)`、最大直径`max(di)`,无附加减料时体积`sum(pi*di^2*li/4)`。同总长、同体积仍可能有错误台肩,不能仅验包围盒。
改第i段长度时,该段之前的起点不动,其后各段起止位置由累计表达式更新;只改直径不移动轴向分界。用`parameters.change`修改已存在参数并重查全部受影响区间,而非再添加一个同名参数。若要求总长固定但只指定某段加长,先确定由哪段吸收变化,不任意缩短末段。
@@ -1,59 +0,0 @@
# 直齿锥齿轮:端面渐开线截面缩放近似 v1.1
实验候选;参考操作尚需在当前引擎回放。仅用于用户接受的结构示意、可编辑参数模型,交付必须说明“端面渐开线沿共同锥顶缩放近似,径向简化齿根”。它不是球面渐开线或滚切生成的共轭齿面,不满足制造级齿形、齿轮副接触或强度要求。不得用三角齿或等径直齿轮替代。
## 范围与尺寸定义
外直齿、零变位、零侧隙;大端端面压力角20°、齿顶高系数1、顶隙系数0.25是本近似的显式假设。18~40齿,分度锥半角δ为轴线与分度锥母线夹角,20~65°。大端在Z=0,小端在Z=H,轴线+Z。模数m指本近似**大端端面模数**。H为轴向高度;若给出沿母线的齿宽b,换算H=b*cos(δ),不能把二者混同。小大端比须0.45~0.9,孔半径小于小端齿根半径;超范围不声称规程已经验证。
**安装坐标:大端中心为C、由大端指向小端的单位方向为u时,共顶点P=C+u*apexHeight,小端中心=C+u*axialHeight。先以同一P和两根轴确定各轮C、u,再放置几何;不能把母线齿宽直接沿轴挤出。**
## 可编辑参数
`parameters.add`长度`unit:"mm"`,角度`unit:"deg"`,无量纲`unit:""`。独立输入:`largeModule,gearTeeth,pitchConeAngle,axialHeight,boreDiameter`;不设用户未给的尺寸。以下派生式均保存为参数:
```text
gearPressure = 20 deg
pitchRadius = largeModule*gearTeeth/2
baseRadius = pitchRadius*cos(gearPressure)
tipRadius = pitchRadius+largeModule
rootRadius = pitchRadius-1.25*largeModule
apexHeight = pitchRadius/tan(pitchConeAngle)
endScale = 1-axialHeight/apexHeight
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll = sqrt((tipRadius/baseRadius)^2-1)
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
rootX = rootRadius*cos(toothBaseAngle)
rootY = rootRadius*sin(toothBaseAngle)
baseX = baseRadius*cos(toothBaseAngle)
baseY = baseRadius*sin(toothBaseAngle)
tipX = tipRadius*cos(tipAngle)
tipY = tipRadius*sin(tipAngle)
```
`tipRoll,endScale,gearTeeth`无量纲;Angle后缀参数有角度单位,其余上述几何量为mm。检查`0<rootRadius<baseRadius<tipRadius`、`0<tipAngle<toothBaseAngle<180 deg/gearTeeth`。`atan`结果除以`1 rad`才是弧度数。
## 完整齿圈再整体缩放扫掠
不要先建根圆锥再逐个布尔连接轮齿。`sketch.create {plane:"XY",name:"BevelLargeSection"}`。一个扇区链顺序建立:
1. `sketch.line {points:[["rootX","-rootY"],["baseX","-baseY"]],infer:false}`→l1。
2. 方程曲线s1:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`;y=`-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`。`sketch.equation_curve {x,y,start:0,end:"tipRoll",tolerance:0.002}`。
3. `sketch.arc.three_point {start:["tipX","-tipY"],through:["tipRadius",0],end:["tipX","tipY"]}`→a1。
4. 方程曲线s2:x同s1、y改正号,范围和数值字面量tolerance同s1。
5. 上侧径向线l2:`[baseX,baseY]→[rootX,rootY]`,infer:false。
6. 根部间隙圆弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/gearTeeth),rootRadius*sin(180 deg/gearTeeth)]`,end=`[rootRadius*cos(360 deg/gearTeeth-toothBaseAngle),rootRadius*sin(360 deg/gearTeeth-toothBaseAngle)]`。
扇区开口恰接下一齿,不能加弦线闭合单齿。`sketch.pattern.circular {entities:["l1","s1","a1","s2","l2","a2"],center:[0,0],count:"gearTeeth"}`。`sketch.solve`确认一个闭合齿圈,再`sketch.finish`。
`sketch.create {plane:"YZ",name:"BevelAxisPath"}`,画`sketch.line {points:[[0,0],[0,"axialHeight"]],infer:false}`→l1,再finish。YZ局部y是世界Z,此路径必须在轴线上。
```json
{"command":"solid.sweep","params":{"sketch":"BevelLargeSection","path_sketch":"BevelAxisPath","path":["l1"],"orientation":"parallel","scale":"endScale","twist":"0 deg","operation":"new","body_name":"BevelGear","name":"BevelApproximateSweep"}}
```
孔、轮毂、键槽按用户需求独立添加。孔可用`solid.cylinder {diameter:"boreDiameter",base:[0,0,-1],height:"axialHeight+2",operation:"cut",targets:["BevelGear"]}`。不对完整齿圈再次实体阵列。轴孔保持圆柱,不能随齿圈一起缩放成锥孔。
## 复核与交付
一闭合实体、无时间线错误、两端齿数均为gearTeeth。大小端对应点方位角相同,半径比endScale;每个同源轮齿母线延长应指向Z=apexHeight,不能只是带斜面的圆柱齿轮。实际截面工作齿廓匹配大端渐开线及其缩放,小端模数为largeModule*endScale,分度圆处角齿厚π/gearTeeth。若大端无孔截面积A0,则净体积`A0*H*(1+s+s^2)/3-pi*(boreDiameter/2)^2*H`。用实际曲线/曲面采样、测量和截图验证,特征名与完成文字不能代替几何证据。参考两例为m2/24齿/δ45°/H8/孔8,以及m1.5/28齿/δ35°/H7/孔6;它们是试验尺寸,不能作为其他需求默认值。
@@ -1,57 +0,0 @@
# 直齿锥齿轮:端面渐开线截面缩放近似 v1
实验候选;参考操作尚需在当前引擎回放。仅用于用户接受的结构示意、可编辑参数模型,交付必须说明“端面渐开线沿共同锥顶缩放近似,径向简化齿根”。它不是球面渐开线或滚切生成的共轭齿面,不满足制造级齿形、齿轮副接触或强度要求。不得用三角齿或等径直齿轮替代。
## 范围与尺寸定义
外直齿、零变位、零侧隙;大端端面压力角20°、齿顶高系数1、顶隙系数0.25是本近似的显式假设。18~40齿,分度锥半角δ为轴线与分度锥母线夹角,20~65°。大端在Z=0,小端在Z=H,轴线+Z。模数m指本近似**大端端面模数**。H为轴向高度;若给出沿母线的齿宽b,换算H=b*cos(δ),不能把二者混同。小大端比须0.45~0.9,孔半径小于小端齿根半径;超范围不声称规程已经验证。
## 可编辑参数
`parameters.add`长度`unit:"mm"`,角度`unit:"deg"`,无量纲`unit:""`。独立输入:`largeModule,gearTeeth,pitchConeAngle,axialHeight,boreDiameter`;不设用户未给的尺寸。以下派生式均保存为参数:
```text
gearPressure = 20 deg
pitchRadius = largeModule*gearTeeth/2
baseRadius = pitchRadius*cos(gearPressure)
tipRadius = pitchRadius+largeModule
rootRadius = pitchRadius-1.25*largeModule
apexHeight = pitchRadius/tan(pitchConeAngle)
endScale = 1-axialHeight/apexHeight
toothBaseAngle = 90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)
tipRoll = sqrt((tipRadius/baseRadius)^2-1)
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
rootX = rootRadius*cos(toothBaseAngle)
rootY = rootRadius*sin(toothBaseAngle)
baseX = baseRadius*cos(toothBaseAngle)
baseY = baseRadius*sin(toothBaseAngle)
tipX = tipRadius*cos(tipAngle)
tipY = tipRadius*sin(tipAngle)
```
`tipRoll,endScale,gearTeeth`无量纲;Angle后缀参数有角度单位,其余上述几何量为mm。检查`0<rootRadius<baseRadius<tipRadius`、`0<tipAngle<toothBaseAngle<180 deg/gearTeeth`。`atan`结果除以`1 rad`才是弧度数。
## 完整齿圈再整体缩放扫掠
不要先建根圆锥再逐个布尔连接轮齿。`sketch.create {plane:"XY",name:"BevelLargeSection"}`。一个扇区链顺序建立:
1. `sketch.line {points:[["rootX","-rootY"],["baseX","-baseY"]],infer:false}`→l1。
2. 方程曲线s1:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`;y=`-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`。`sketch.equation_curve {x,y,start:0,end:"tipRoll",tolerance:0.002}`。
3. `sketch.arc.three_point {start:["tipX","-tipY"],through:["tipRadius",0],end:["tipX","tipY"]}`→a1。
4. 方程曲线s2:x同s1、y改正号,范围和数值字面量tolerance同s1。
5. 上侧径向线l2:`[baseX,baseY]→[rootX,rootY]`,infer:false。
6. 根部间隙圆弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/gearTeeth),rootRadius*sin(180 deg/gearTeeth)]`,end=`[rootRadius*cos(360 deg/gearTeeth-toothBaseAngle),rootRadius*sin(360 deg/gearTeeth-toothBaseAngle)]`。
扇区开口恰接下一齿,不能加弦线闭合单齿。`sketch.pattern.circular {entities:["l1","s1","a1","s2","l2","a2"],center:[0,0],count:"gearTeeth"}`。`sketch.solve`确认一个闭合齿圈,再`sketch.finish`。
`sketch.create {plane:"YZ",name:"BevelAxisPath"}`,画`sketch.line {points:[[0,0],[0,"axialHeight"]],infer:false}`→l1,再finish。YZ局部y是世界Z,此路径必须在轴线上。
```json
{"command":"solid.sweep","params":{"sketch":"BevelLargeSection","path_sketch":"BevelAxisPath","path":["l1"],"orientation":"parallel","scale":"endScale","twist":"0 deg","operation":"new","body_name":"BevelGear","name":"BevelApproximateSweep"}}
```
孔、轮毂、键槽按用户需求独立添加。孔可用`solid.cylinder {diameter:"boreDiameter",base:[0,0,-1],height:"axialHeight+2",operation:"cut",targets:["BevelGear"]}`。不对完整齿圈再次实体阵列。轴孔保持圆柱,不能随齿圈一起缩放成锥孔。
## 复核与交付
一闭合实体、无时间线错误、两端齿数均为gearTeeth。大小端对应点方位角相同,半径比endScale;每个同源轮齿母线延长应指向Z=apexHeight,不能只是带斜面的圆柱齿轮。实际截面工作齿廓匹配大端渐开线及其缩放,小端模数为largeModule*endScale,分度圆处角齿厚π/gearTeeth。若大端无孔截面积A0,则净体积`A0*H*(1+s+s^2)/3-pi*(boreDiameter/2)^2*H`。用实际曲线/曲面采样、测量和截图验证,特征名与完成文字不能代替几何证据。参考两例为m2/24齿/δ45°/H8/孔8,以及m1.5/28齿/δ35°/H7/孔6;它们是试验尺寸,不能作为其他需求默认值。
@@ -1,67 +0,0 @@
# 直齿齿条:单齿梯形与直线阵列规程 v1
实验候选,尚待真实引擎回放和正式助手生成验证。适用20°压力角、零变位、零侧隙、齿顶高系数1、顶隙系数0.25的直齿齿条;根部采用明确标注的尖角简化,不声称滚刀包络齿根。直齿齿条的工作齿廓本来就是直线,不能误套圆齿轮渐开线或做成等腰三角齿。
## 坐标和参数
本规程X为节距方向,Y为齿高方向,Z为齿宽。节线Y=0,齿顶Y=ha,齿根Y=-hf。若需要齿朝+Z,整体采用对应的草图平面/坐标变换;不要只交换标签。尺寸来自用户,齿数是有效完整齿数,不是圆周齿数。
用`parameters.add`登记长度`unit:"mm"`、角度`unit:"deg"`、齿数`unit:""`:
```text
rackModule, rackWidth, baseThickness = 用户尺寸 [mm]
rackTeeth = 用户完整齿数 [整数]
rackPressure = 20 deg
rackPitch = pi*rackModule [mm]
addendum = rackModule [mm]
dedendum = 1.25*rackModule [mm]
halfPitchTooth = rackPitch/4 [mm]
halfTip = halfPitchTooth-addendum*tan(rackPressure) [mm]
halfRoot = halfPitchTooth+dedendum*tan(rackPressure) [mm]
rackLength = rackTeeth*rackPitch [mm]
firstCenter = rackPitch/2 [mm]
joinOverlap = 0.05*rackModule [mm]
halfJoin = halfPitchTooth+(dedendum+joinOverlap)*tan(rackPressure) [mm]
```
必须尺寸为正、rackTeeth为正整数、`0<halfTip<halfRoot<rackPitch/2`、`0<joinOverlap<baseThickness`。基座从X=0到rackLength,Y=-dedendum-baseThickness到-dedendum,Z=0到rackWidth;首齿中心firstCenter,后续中心增加rackPitch。若用户给的是总长、端部余量或半齿端,不得静默用`齿数*pi*m`替代,应明确端部构造后再做。
## 可执行构造
基座用:
```json
{"command":"solid.box","params":{"corner":[0,"-dedendum-baseThickness",0],"length":"rackLength","width":"baseThickness","height":"rackWidth","operation":"new","body_name":"Rack","name":"RackBase"}}
```
`sketch.create {plane:"XY",name:"RackToothProfile"}`,用一次`sketch.line`画四点闭合梯形,`closed:true,infer:false`:
```json
[
["firstCenter-halfJoin","-dedendum-joinOverlap"],
["firstCenter-halfTip","addendum"],
["firstCenter+halfTip","addendum"],
["firstCenter+halfJoin","-dedendum-joinOverlap"]
]
```
齿的两侧相对Y方向倾斜rackPressure;每向齿顶升高1mm,半齿厚减少`tan(rackPressure)`mm。底边伸入基座joinOverlap,实际暴露根线仍是Y=-dedendum。不能把齿底只接在基座边上,也不能用halfRoot替代halfJoin使工作边斜率发生变化。
检查`sketch.solve`一个闭合区域后`sketch.finish`:
```json
{"command":"solid.extrude","params":{"sketch":"RackToothProfile","distance":"rackWidth","operation":"join","targets":["Rack"],"name":"RackTooth"}}
{"command":"solid.pattern.rectangular","params":{"features":["RackTooth"],"dir1":[1,0,0],"count1":"rackTeeth","spacing1":"rackPitch","name":"RackTeeth"}}
```
阵列的是已Join的单齿特征,counts包含原齿;不要阵列整条基座,不要重复生成rackTeeth+1齿。安装孔、键槽和背面台阶由用户要求决定,不能从示例强加。
## 检查
应一闭合实体、无失败时间线、N个完整梯形齿和N-1个内部齿槽。节线上齿厚=`rackPitch/2`,相邻中心距=`rackPitch`;齿顶全宽=`2*halfTip`,根线齿宽=`2*halfRoot`。总包围盒为`rackLength × (baseThickness+addendum+dedendum) × rackWidth`;体积为:
```text
[rackLength*baseThickness+rackTeeth*(addendum+dedendum)*(halfTip+halfRoot)]*rackWidth
```
重叠部分已并入基座,不能再计一次。顶视检查齿尖平顶、两侧压力角、齿间实际空隙;仅体积正确不能替代齿数和轮廓检查。至少试改一次模数或齿数,确认节距、总长、齿厚及阵列随参数重建,并恢复用户值。
@@ -1,21 +0,0 @@
# 单级蜗轮蜗杆:正交轴接口与已标注示意装配 v1
实验候选。适用于已经明确采用单级圆柱蜗杆与蜗轮的需求。蜗杆按需读取`worm`规程,蜗轮按需读取`worm-wheel`。当前蜗轮是“环面喉部+输运渐开线斜齿示意”,不是配对蜗杆的滚切共轭包络。组合后仍须明确该限制,不能把两份单体检查升级成传动接触/制造认证。
## 参数与共同基准
明确蜗杆类型、模数体系、头数n、分度直径d1、有效长度L1、旋向,以及蜗轮齿数z2、宽度B2、孔和表示层次。本试点ZA蜗杆采用轴向模数;示意蜗轮以同一输入m作为其端面模数,这是模型约定,不宣称全部真实蜗杆传动都能如此等同。参数体系不同先换算或说明缺口,不能混填法向模数。
参考分度半径r1=d1/2、r2=m*z2/2,轴交角90°,零变位示意中心距a=r1+r2。蜗轮轴Z、中心(0,0,B2/2),齿宽Z=0~B2;蜗杆轴X,轴线经过(0,−a,B2/2),长度以X=0居中。两轴不相交,最短连线沿Y,距离a;不要把“正交”误画成两轴穿过同一中心。
蜗杆先在本地Z=0~L1生成,再`solid.move {bodies:[蜗杆],axis:[0,1,0],angle:"90 deg",translate:["-L1/2","-a","B2/2"]}`转成+X。蜗轮保持Z轴。各自孔沿各自轴,保留两个独立实体;所有Join/Cut/Intersect显式限定本部件targets。模数、a、B2、L1共享参数表达式;独立命名各自参数/特征,防止同名冲突。
## 相位与接触边界
蜗杆导程lead=n*pi*m,不是单个轴向齿距pi*m。静态展示可令L1为2个导程,使中点的基准螺旋齿脊经过所选接触径向;改变长度或旋向后需重算中间截面的齿脊相位。若当前ZA参考齿脊在本地+Y方向、轴向整导程处,转轴后朝向轮体;蜗轮中面选一齿槽中心朝−Y,按其实际扭转中面相位调整整体Z转角。不得因相位算式存在就声称没有穿透。
本示意蜗轮齿面不是蜗杆的共轭包络;即便中心距和初相位正确,也可能发生局部几何干涉。检查实际齿形、凹喉部、两轴位置、齿数/头数、间隙与截图,明确哪些接触尚未验证。若要求无干涉啮合,必须另做接触/包络验证;不能扩大中心距或把蜗杆移远后仍称标准啮合。
## 可选运动关系
只在用户要求运动时沿原机构Skill建立独立组件、固定支承和两正交revolute。解析转速绝对比`|ωwheel/ωworm|=n/z2`,旋转符号由所选旋向、观察轴和安装侧共同决定。用已有`joint.motion_link {a:蜗杆关节,b:蜗轮关节,ratio:带符号n/z2}`表达运动学关系;它不生成蜗轮齿面,也不模拟接触。2头/32齿示例蜗杆转360°时轮应转绝对22.5°;正负需用当前轴向约定核验。未驱动时只记录解析比值。运动比值正确不等于共轭传动正确。
@@ -1,15 +0,0 @@
# 示意蜗轮:根圆连接与喉部余量提示
仅用于已明确接受“输运渐开线斜齿+环面凹喉部”的结构示意。它不是配对蜗杆滚切齿面;不提供通用蜗轮设计流程,不据此宣称共轭或制造能力。尺寸取当前需求,不复制历史样例。
以下长度均为mm,角度显式deg/rad。`wheelModule`为本表示的端面模数,`wheelTeeth`为齿数,`wheelWidth`为轴向宽,`wormPitchRadius`为参考蜗杆分度半径。已观察到两处实际执行错误:
1. **根部圆弧端点必须落在同一根圆。** 定义原生参数`pitchRadius=wheelModule*wheelTeeth/2`、`rootRadius=pitchRadius-1.25*wheelModule`、`wheelPressure=20 deg`、`toothBaseAngle=90 deg/wheelTeeth+(tan(wheelPressure)-wheelPressure/(1 rad))*(1 rad)`。`rootX=rootRadius*cos(toothBaseAngle)`、`rootY=rootRadius*sin(toothBaseAngle)`;下一扇区点分别为`nextRootX=rootRadius*cos(360 deg/wheelTeeth-toothBaseAngle)`、`nextRootY=rootRadius*sin(360 deg/wheelTeeth-toothBaseAngle)`。不要再把rootX/rootY乘三角函数当根圆半径:
```json
{"command":"sketch.arc.three_point","params":{"start":["rootX","rootY"],"through":["rootRadius*cos(180 deg/wheelTeeth)","rootRadius*sin(180 deg/wheelTeeth)"],"end":["nextRootX","nextRootY"]}}
```
2. **喉部切除必须覆盖全宽。** 保留`blankTipRadius=pitchRadius+1.5*wheelModule`,这是待切除毛坯余量;不能改成1.25m。定义`throatMajor=pitchRadius+wormPitchRadius`、`throatMinor=wormPitchRadius-wheelModule`,要求`throatMinor>wheelWidth/2>0`。最终外缘上限为`r_limit(z)=throatMajor-sqrt(throatMinor^2-(z-wheelWidth/2)^2)`,须满足`r_limit(0)<blankTipRadius-0.005*wheelModule`;不足时说明该表示不适用,不改需求凑数。环面cut的major/minor是半径,中心Z=`wheelWidth/2`,targets必须是当前蜗轮。
用实际几何检查两端及中面都形成凹喉部、根圆连接连续。只看到一个闭合实体不足以排除上述错误。
@@ -1,72 +0,0 @@
# 蜗轮:斜齿与环面凹喉部示意 v1.1
实验候选,参考命令需当前引擎回放。仅用于用户接受的结构/参数模型,交付必须明确“环面喉部+输运渐开线斜齿示意,并非由配对蜗杆滚切包络生成”。本表示有实际凹喉部、齿数和齿向,不是把普通斜齿轮直接改名为蜗轮。它不能证明共轭、接触、效率、承载或制造级齿形;用户明确要求真实配对齿面时说明能力缺口,不声称满足。
## 表示定义和适用域
轮轴Z,宽度Z=0~B,中面Z=B/2。显式输入端面模数`wheelModule`、轮齿数`wheelTeeth`、轮宽`wheelWidth`、圆孔`boreDiameter`、参考蜗杆分度半径`wormPitchRadius`、头数`wormStarts`和`handSign`。参考蜗杆只用于示意尺度和齿向,不自动生成第二个零件。本表示规定参考轴向齿距πm,不能把未转换的法向模数直接填入。端面压力角20°、零侧隙/变位、根部1.25m径向简化都是本示意的显式约定。
18~40齿、参考头数1~4。handSign取+1表示随+Z方位角增加,-1相反;它是本模型的几何手性约定,不推断完整传动装配旋向。用户没有这些关键尺寸时沿原助手澄清,不从类别虚构标准规格。
## 全部尺寸保存为参数表达式
`parameters.add`长度mm、角度deg、无量纲unit空字符串;Angle参数带角度单位。定义:
```text
wheelPressure = 20 deg
pitchRadius = wheelModule*wheelTeeth/2
baseRadius = pitchRadius*cos(wheelPressure)
rootRadius = pitchRadius-1.25*wheelModule
blankTipRadius = pitchRadius+1.5*wheelModule
throatMajor = pitchRadius+wormPitchRadius
throatMinor = wormPitchRadius-wheelModule
wormLead = wormStarts*pi*wheelModule
referenceLeadAngle = handSign*atan(wormLead/(2*pi*wormPitchRadius))
wheelTwist = wheelWidth*tan(referenceLeadAngle)/pitchRadius*(1 rad)
toothBaseAngle = 90 deg/wheelTeeth+(tan(wheelPressure)-wheelPressure/(1 rad))*(1 rad)
tipRoll = sqrt((blankTipRadius/baseRadius)^2-1)
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
rootX = rootRadius*cos(toothBaseAngle)
rootY = rootRadius*sin(toothBaseAngle)
nextRootX = rootRadius*cos(360 deg/wheelTeeth-toothBaseAngle)
nextRootY = rootRadius*sin(360 deg/wheelTeeth-toothBaseAngle)
baseX = baseRadius*cos(toothBaseAngle)
baseY = baseRadius*sin(toothBaseAngle)
tipX = blankTipRadius*cos(tipAngle)
tipY = blankTipRadius*sin(tipAngle)
```
1.5m仅是**待切除毛坯**的加高量,不宣称最终齿制齿顶高为1.5m。目标喉部半径随高度为`r_limit(z)=throatMajor-sqrt(throatMinor^2-(z-wheelWidth/2)^2)`。中面为pitchRadius+wheelModule,端面更大,真实形成凹喉部。必须检查`0<rootRadius<baseRadius`、`throatMinor>wheelWidth/2>0`、孔半径小于rootRadius、`tipAngle>0`;并且`baseRadius<r_limit(B/2)<r_limit(0)<blankTipRadius-0.005*wheelModule`。否则不使用本版,不能静默加宽/缩小用户尺寸来凑命中。 毛坯半径大于最终喉部半径是后续切除所需的余量,不是几何冲突;只有上述不等式不成立才拒绝。
## 完整齿圈、整体扭转、再切喉部
1. `sketch.create {plane:"XY",name:"WheelBlankSection"}`。画下根线l1:`[rootX,-rootY]→[baseX,-baseY]`,infer:false。
2. `sketch.equation_curve` s1:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y=`-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,start:0,end:"tipRoll",tolerance:0.002。tolerance用数值字面量。
3. `sketch.arc.three_point` a1:start=`[tipX,-tipY]`,through=`[blankTipRadius,0]`,end=`[tipX,tipY]`。
4. s2方程x相同,y取正号,范围和拟合公差相同。
5. 上根线l2:`[baseX,baseY]→[rootX,rootY]`,infer:false。
6. 根部间隙圆弧a2直接使用下一扇区的根点参数,不能把`rootRadius`误写为`rootX/rootY`再乘cos;否则阵列后仍是断开的齿圈:
```json
{"command":"sketch.arc.three_point","params":{"start":["rootX","rootY"],"through":["rootRadius*cos(180 deg/wheelTeeth)","rootRadius*sin(180 deg/wheelTeeth)"],"end":["nextRootX","nextRootY"]}}
```
7. 开口扇区链不要用弦线闭合。`sketch.pattern.circular {entities:["l1","s1","a1","s2","l2","a2"],center:[0,0],count:"wheelTeeth"}`成为一个完整闭合齿圈,solve后finish。
8. YZ草图`WheelAxisPath`画`[[0,0],[0,"wheelWidth"]]`→l1,infer:false,finish。局部y是世界Z,路径必须沿轮轴。
```json
{"command":"solid.sweep","params":{"sketch":"WheelBlankSection","path_sketch":"WheelAxisPath","path":["l1"],"orientation":"parallel","twist":"wheelTwist","operation":"new","body_name":"WormWheelIllustration","name":"IllustrativeWheelBlankSweep"}}
```
下一步单独batch,形成真实凹喉部而非视觉倒角:
```json
{"command":"solid.torus","params":{"major":"throatMajor","minor":"throatMinor","center":[0,0,"wheelWidth/2"],"operation":"cut","targets":["WormWheelIllustration"],"name":"IllustrativeToroidalThroat"}}
```
环面轴为Z,切除毛坯外缘;不能把major/minor填成直径。若布尔失败,保留现场并说明,不以未切喉部的普通斜齿轮声称成功。圆孔后续用圆柱贯穿切除,显式targets。轮毂和孔槽按用户选配;不强加,不再次阵列完整齿圈。
## 可独立复核的结果
最终一闭合实体、时间线无错误、齿数正确、轴孔与位置正确。中面外缘比两端凹入;实际喉面满足`(sqrt(x^2+y^2)-throatMajor)^2+(z-B/2)^2=throatMinor^2`。实际喉部与上/下齿侧交线同时满足该环面与端面渐开线相位输运,phase(z)=wheelTwist*z/B;用实际曲线/曲面采样检查齿向,不能只看特征名。
体积参考按每个Z的截面计算:先把渐开线齿圈径向截到r_limit(z),积分其面积再减圆孔体积;不能拿未切喉部的斜齿轮体积当参考。参考两例:m2/32齿/参考蜗杆分度半径10与2头/B7/孔10/正手;m1.5/28齿/参考半径8与3头/B6/孔8/负手。它们不是通用默认值。保存原生设计、iso/top/right截图并做参数迁移;本规程始终是已标注的示意表示,不升级声称滚切共轭。
@@ -1,72 +0,0 @@
# 蜗轮:斜齿与环面凹喉部示意 v1.2
实验候选,参考命令需当前引擎回放。仅用于用户接受的结构/参数模型,交付必须明确“环面喉部+输运渐开线斜齿示意,并非由配对蜗杆滚切包络生成”。本表示有实际凹喉部、齿数和齿向,不是把普通斜齿轮直接改名为蜗轮。它不能证明共轭、接触、效率、承载或制造级齿形;用户明确要求真实配对齿面时说明能力缺口,不声称满足。
## 表示定义和适用域
轮轴Z,宽度Z=0~B,中面Z=B/2。显式输入端面模数`wheelModule`、轮齿数`wheelTeeth`、轮宽`wheelWidth`、圆孔`boreDiameter`、参考蜗杆分度半径`wormPitchRadius`、头数`wormStarts`和`handSign`。参考蜗杆只用于示意尺度和齿向,不自动生成第二个零件。本表示规定参考轴向齿距πm,不能把未转换的法向模数直接填入。端面压力角20°、零侧隙/变位、根部1.25m径向简化都是本示意的显式约定。
18~40齿、参考头数1~4。handSign取+1表示随+Z方位角增加,-1相反;它是本模型的几何手性约定,不推断完整传动装配旋向。用户没有这些关键尺寸时沿原助手澄清,不从类别虚构标准规格。
## 全部尺寸保存为参数表达式
`parameters.add`长度mm、角度deg、无量纲unit空字符串;Angle参数带角度单位。定义:
```text
wheelPressure = 20 deg
pitchRadius = wheelModule*wheelTeeth/2
baseRadius = pitchRadius*cos(wheelPressure)
rootRadius = pitchRadius-1.25*wheelModule
blankTipRadius = pitchRadius+1.5*wheelModule
throatMajor = pitchRadius+wormPitchRadius
throatMinor = wormPitchRadius-wheelModule
wormLead = wormStarts*pi*wheelModule
referenceLeadAngle = handSign*atan(wormLead/(2*pi*wormPitchRadius))
wheelTwist = wheelWidth*tan(referenceLeadAngle)/pitchRadius*(1 rad)
toothBaseAngle = 90 deg/wheelTeeth+(tan(wheelPressure)-wheelPressure/(1 rad))*(1 rad)
tipRoll = sqrt((blankTipRadius/baseRadius)^2-1)
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
rootX = rootRadius*cos(toothBaseAngle)
rootY = rootRadius*sin(toothBaseAngle)
nextRootX = rootRadius*cos(360 deg/wheelTeeth-toothBaseAngle)
nextRootY = rootRadius*sin(360 deg/wheelTeeth-toothBaseAngle)
baseX = baseRadius*cos(toothBaseAngle)
baseY = baseRadius*sin(toothBaseAngle)
tipX = blankTipRadius*cos(tipAngle)
tipY = blankTipRadius*sin(tipAngle)
```
1.5m仅是**待切除毛坯**的加高量,不宣称最终齿制齿顶高为1.5m。 **严格保留`blankTipRadius=pitchRadius+1.5*wheelModule`,不能改为`pitchRadius+(addendumCoefficient+clearanceCoefficient)*wheelModule`或1.25m;后者会让喉部只切中段、两端失效。**目标喉部半径随高度为`r_limit(z)=throatMajor-sqrt(throatMinor^2-(z-wheelWidth/2)^2)`。中面为pitchRadius+wheelModule,端面更大,真实形成凹喉部。必须检查`0<rootRadius<baseRadius`、`throatMinor>wheelWidth/2>0`、孔半径小于rootRadius、`tipAngle>0`;并且`baseRadius<r_limit(B/2)<r_limit(0)<blankTipRadius-0.005*wheelModule`。否则不使用本版,不能静默加宽/缩小用户尺寸来凑命中。 例如本试点m2/z32/rw10/B7:毛坯必须35,喉部中面34、端面约34.806253;34.5的毛坯不满足全宽切除条件。这些是核对值,不替代参数表达式。 毛坯半径大于最终喉部半径是后续切除所需的余量,不是几何冲突;只有上述不等式不成立才拒绝。
## 完整齿圈、整体扭转、再切喉部
1. `sketch.create {plane:"XY",name:"WheelBlankSection"}`。画下根线l1:`[rootX,-rootY]→[baseX,-baseY]`,infer:false。
2. `sketch.equation_curve` s1:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y=`-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,start:0,end:"tipRoll",tolerance:0.002。tolerance用数值字面量。
3. `sketch.arc.three_point` a1:start=`[tipX,-tipY]`,through=`[blankTipRadius,0]`,end=`[tipX,tipY]`。
4. s2方程x相同,y取正号,范围和拟合公差相同。
5. 上根线l2:`[baseX,baseY]→[rootX,rootY]`,infer:false。
6. 根部间隙圆弧a2直接使用下一扇区的根点参数,不能把`rootRadius`误写为`rootX/rootY`再乘cos;否则阵列后仍是断开的齿圈:
```json
{"command":"sketch.arc.three_point","params":{"start":["rootX","rootY"],"through":["rootRadius*cos(180 deg/wheelTeeth)","rootRadius*sin(180 deg/wheelTeeth)"],"end":["nextRootX","nextRootY"]}}
```
7. 开口扇区链不要用弦线闭合。`sketch.pattern.circular {entities:["l1","s1","a1","s2","l2","a2"],center:[0,0],count:"wheelTeeth"}`成为一个完整闭合齿圈,solve后finish。
8. YZ草图`WheelAxisPath`画`[[0,0],[0,"wheelWidth"]]`→l1,infer:false,finish。局部y是世界Z,路径必须沿轮轴。
```json
{"command":"solid.sweep","params":{"sketch":"WheelBlankSection","path_sketch":"WheelAxisPath","path":["l1"],"orientation":"parallel","twist":"wheelTwist","operation":"new","body_name":"WormWheelIllustration","name":"IllustrativeWheelBlankSweep"}}
```
下一步单独batch,形成真实凹喉部而非视觉倒角:
```json
{"command":"solid.torus","params":{"major":"throatMajor","minor":"throatMinor","center":[0,0,"wheelWidth/2"],"operation":"cut","targets":["WormWheelIllustration"],"name":"IllustrativeToroidalThroat"}}
```
环面轴为Z,切除毛坯外缘;不能把major/minor填成直径。若布尔失败,保留现场并说明,不以未切喉部的普通斜齿轮声称成功。圆孔后续用圆柱贯穿切除,显式targets。轮毂和孔槽按用户选配;不强加,不再次阵列完整齿圈。
## 可独立复核的结果
最终一闭合实体、时间线无错误、齿数正确、轴孔与位置正确。中面外缘比两端凹入;实际喉面满足`(sqrt(x^2+y^2)-throatMajor)^2+(z-B/2)^2=throatMinor^2`。实际喉部与上/下齿侧交线同时满足该环面与端面渐开线相位输运,phase(z)=wheelTwist*z/B;用实际曲线/曲面采样检查齿向,不能只看特征名。
体积参考按每个Z的截面计算:先把渐开线齿圈径向截到r_limit(z),积分其面积再减圆孔体积;不能拿未切喉部的斜齿轮体积当参考。参考两例:m2/32齿/参考蜗杆分度半径10与2头/B7/孔10/正手;m1.5/28齿/参考半径8与3头/B6/孔8/负手。它们不是通用默认值。保存原生设计、iso/top/right截图并做参数迁移;本规程始终是已标注的示意表示,不升级声称滚切共轭。
@@ -1,66 +0,0 @@
# 蜗轮:斜齿与环面凹喉部示意 v1
实验候选,参考命令需当前引擎回放。仅用于用户接受的结构/参数模型,交付必须明确“环面喉部+输运渐开线斜齿示意,并非由配对蜗杆滚切包络生成”。本表示有实际凹喉部、齿数和齿向,不是把普通斜齿轮直接改名为蜗轮。它不能证明共轭、接触、效率、承载或制造级齿形;用户明确要求真实配对齿面时说明能力缺口,不声称满足。
## 表示定义和适用域
轮轴Z,宽度Z=0~B,中面Z=B/2。显式输入端面模数`wheelModule`、轮齿数`wheelTeeth`、轮宽`wheelWidth`、圆孔`boreDiameter`、参考蜗杆分度半径`wormPitchRadius`、头数`wormStarts`和`handSign`。参考蜗杆只用于示意尺度和齿向,不自动生成第二个零件。本表示规定参考轴向齿距πm,不能把未转换的法向模数直接填入。端面压力角20°、零侧隙/变位、根部1.25m径向简化都是本示意的显式约定。
18~40齿、参考头数1~4。handSign取+1表示随+Z方位角增加,-1相反;它是本模型的几何手性约定,不推断完整传动装配旋向。用户没有这些关键尺寸时沿原助手澄清,不从类别虚构标准规格。
## 全部尺寸保存为参数表达式
`parameters.add`长度mm、角度deg、无量纲unit空字符串;Angle参数带角度单位。定义:
```text
wheelPressure = 20 deg
pitchRadius = wheelModule*wheelTeeth/2
baseRadius = pitchRadius*cos(wheelPressure)
rootRadius = pitchRadius-1.25*wheelModule
blankTipRadius = pitchRadius+1.5*wheelModule
throatMajor = pitchRadius+wormPitchRadius
throatMinor = wormPitchRadius-wheelModule
wormLead = wormStarts*pi*wheelModule
referenceLeadAngle = handSign*atan(wormLead/(2*pi*wormPitchRadius))
wheelTwist = wheelWidth*tan(referenceLeadAngle)/pitchRadius*(1 rad)
toothBaseAngle = 90 deg/wheelTeeth+(tan(wheelPressure)-wheelPressure/(1 rad))*(1 rad)
tipRoll = sqrt((blankTipRadius/baseRadius)^2-1)
tipAngle = toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)
rootX = rootRadius*cos(toothBaseAngle)
rootY = rootRadius*sin(toothBaseAngle)
baseX = baseRadius*cos(toothBaseAngle)
baseY = baseRadius*sin(toothBaseAngle)
tipX = blankTipRadius*cos(tipAngle)
tipY = blankTipRadius*sin(tipAngle)
```
1.5m仅是**待切除毛坯**的加高量,不宣称最终齿制齿顶高为1.5m。目标喉部半径随高度为`r_limit(z)=throatMajor-sqrt(throatMinor^2-(z-wheelWidth/2)^2)`。中面为pitchRadius+wheelModule,端面更大,真实形成凹喉部。必须检查`0<rootRadius<baseRadius`、`throatMinor>wheelWidth/2>0`、孔半径小于rootRadius、`tipAngle>0`;并且`baseRadius<r_limit(B/2)<r_limit(0)<blankTipRadius-0.005*wheelModule`。否则不使用本版,不能静默加宽/缩小用户尺寸来凑命中。
## 完整齿圈、整体扭转、再切喉部
1. `sketch.create {plane:"XY",name:"WheelBlankSection"}`。画下根线l1:`[rootX,-rootY]→[baseX,-baseY]`,infer:false。
2. `sketch.equation_curve` s1:x=`baseRadius*sqrt(1+t^2)*cos(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,y=`-baseRadius*sqrt(1+t^2)*sin(toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad))`,start:0,end:"tipRoll",tolerance:0.002。tolerance用数值字面量。
3. `sketch.arc.three_point` a1:start=`[tipX,-tipY]`,through=`[blankTipRadius,0]`,end=`[tipX,tipY]`。
4. s2方程x相同,y取正号,范围和拟合公差相同。
5. 上根线l2:`[baseX,baseY]→[rootX,rootY]`,infer:false。
6. 根部间隙圆弧a2:start=`[rootX,rootY]`,through=`[rootRadius*cos(180 deg/wheelTeeth),rootRadius*sin(180 deg/wheelTeeth)]`,end=`[rootRadius*cos(360 deg/wheelTeeth-toothBaseAngle),rootRadius*sin(360 deg/wheelTeeth-toothBaseAngle)]`。
7. 开口扇区链不要用弦线闭合。`sketch.pattern.circular {entities:["l1","s1","a1","s2","l2","a2"],center:[0,0],count:"wheelTeeth"}`成为一个完整闭合齿圈,solve后finish。
8. YZ草图`WheelAxisPath`画`[[0,0],[0,"wheelWidth"]]`→l1,infer:false,finish。局部y是世界Z,路径必须沿轮轴。
```json
{"command":"solid.sweep","params":{"sketch":"WheelBlankSection","path_sketch":"WheelAxisPath","path":["l1"],"orientation":"parallel","twist":"wheelTwist","operation":"new","body_name":"WormWheelIllustration","name":"IllustrativeWheelBlankSweep"}}
```
下一步单独batch,形成真实凹喉部而非视觉倒角:
```json
{"command":"solid.torus","params":{"major":"throatMajor","minor":"throatMinor","center":[0,0,"wheelWidth/2"],"operation":"cut","targets":["WormWheelIllustration"],"name":"IllustrativeToroidalThroat"}}
```
环面轴为Z,切除毛坯外缘;不能把major/minor填成直径。若布尔失败,保留现场并说明,不以未切喉部的普通斜齿轮声称成功。圆孔后续用圆柱贯穿切除,显式targets。轮毂和孔槽按用户选配;不强加,不再次阵列完整齿圈。
## 可独立复核的结果
最终一闭合实体、时间线无错误、齿数正确、轴孔与位置正确。中面外缘比两端凹入;实际喉面满足`(sqrt(x^2+y^2)-throatMajor)^2+(z-B/2)^2=throatMinor^2`。实际喉部与上/下齿侧交线同时满足该环面与端面渐开线相位输运,phase(z)=wheelTwist*z/B;用实际曲线/曲面采样检查齿向,不能只看特征名。
体积参考按每个Z的截面计算:先把渐开线齿圈径向截到r_limit(z),积分其面积再减圆孔体积;不能拿未切喉部的斜齿轮体积当参考。参考两例:m2/32齿/参考蜗杆分度半径10与2头/B7/孔10/正手;m1.5/28齿/参考半径8与3头/B6/孔8/负手。它们不是通用默认值。保存原生设计、iso/top/right截图并做参数迁移;本规程始终是已标注的示意表示,不升级声称滚切共轭。
@@ -1,66 +0,0 @@
# 圆柱蜗杆:ZA轴向直线齿形与实体螺旋齿规程 v1.1
实验候选,真实引擎回放与正式助手收益分别记录。当前采用**ZA型轴向直线齿形**、轴向压力角20°、零变位/侧隙、齿顶高系数1、顶隙系数0.25、平齿顶和简化尖角齿根,1~4头。明确要求ZI/ZN/ZK、包络蜗杆、鼓形、退刀槽或制造级啮合时不套用,也不把这份单体规程当作蜗轮已共轭的证据。
## 轴向参数与基准
Z为蜗杆轴,从Z=0到L。轴向模数mx、分度圆直径d、有效齿长L、头数s及左右旋必须明确;用户给法向模数时不能直接当mx。轴向齿距`px=pi*mx`,**一头转一整圈的导程`lead=s*px`**,不能多头时仍把px传给coil的pitch。导程角`atan(lead/(pi*d))`是派生值。
`parameters.add`长度`unit:"mm"`、角度`unit:"deg"`、头数`unit:""`:
```text
wormModule, wormPitchDiameter, wormLength = 明确轴向模数、d、L [mm]
wormStarts = 明确头数s [整数]
wormPressure = 20 deg
wormPitchRadius = wormPitchDiameter/2 [mm]
wormAxialPitch = pi*wormModule [mm]
wormLead = wormStarts*wormAxialPitch [mm]
wormRootRadius = wormPitchRadius-1.25*wormModule [mm]
wormTipRadius = wormPitchRadius+wormModule [mm]
wormProfileInner = wormRootRadius-0.1*wormModule [mm]
wormInnerHalfWidth = wormAxialPitch/4+(wormPitchRadius-wormProfileInner)*tan(wormPressure) [mm]
wormTipHalfWidth = wormAxialPitch/4-wormModule*tan(wormPressure) [mm]
```
要求`wormRootRadius>0.1*wormModule`、`wormLength>=wormAxialPitch`、`(wormLength+2*wormLead)/wormLead<=200`;轴向齿顶宽`2*wormTipHalfWidth>0`,根线齿宽`wormAxialPitch/2+2.5*wormModule*tan(wormPressure)<wormAxialPitch`。可选孔半径必须小于齿根半径。不能按轴向齿距解释头数,也不能把分度径当齿根径。
## 用当前coil工具生成实体齿
先生成延长的实心芯轴:
```json
{"command":"solid.cylinder","params":{"radius":"wormRootRadius","height":"wormLength+4*wormLead","base":[0,0,"-2*wormLead"],"operation":"new","body_name":"Worm","name":"WormCore"}}
```
1. `sketch.create {plane:"YZ",name:"WormAxialRidge"}`。YZ局部x=世界Y,表示半径;局部y=世界Z,表示轴向位置。一次`sketch.line {infer:false,points:[...]}`画闭合梯形,检查一个闭合区域并结束草图:
```json
[
["wormProfileInner","-wormLead-wormInnerHalfWidth"],
["wormTipRadius","-wormLead-wormTipHalfWidth"],
["wormTipRadius","-wormLead+wormTipHalfWidth"],
["wormProfileInner","-wormLead+wormInnerHalfWidth"],
["wormProfileInner","-wormLead-wormInnerHalfWidth"]
]
```
2. 以这个**轴向梯形草图**直接做螺旋扫掠并Join芯轴:
```json
{"command":"solid.coil","params":{"sketch":"WormAxialRidge","pitch":"wormLead","height":"wormLength+2*wormLead","axis":"Z","base":[0,0,0],"clockwise":false,"operation":"join","targets":["Worm"],"name":"WormRidge"}}
```
沿+Z,`clockwise:false`为右旋,左旋改`true`;保持pitch与height为正。给了sketch时,半径和起始相位由草图实际位置确定,**不再提供diameter、section_size、section或start_angle**。不能用默认圆截面coil画成弹簧,也不能将整个梯形围绕Z旋转成圆环。
3. s>1时`solid.pattern.circular {features:["WormRidge"],axis:"Z",count:"wormStarts",name:"WormStartsPattern"}`,阵列已Join的螺旋齿特征,计数包含原齿;s=1省略。每头相差360°/s,导程不变,不阵列整个芯轴。
4. 用`solid.cylinder {radius:"wormTipRadius+wormModule",height:"wormLength",base:[0,0,0],operation:"intersect",targets:["Worm"],name:"WormEndTrim"}`裁出Z=0~L,去掉两端延长段。轴孔和轴颈仅按需求添加,孔不得穿到齿根外,不生成蜗轮或轴承。
## 实际几何检查
一个闭合实体、无失败时间线,齿根与芯轴连成整体,包围盒径向±wormTipRadius、轴向0~L。轴向固定方位截面的工作齿面是直线,`abs(dz/dr)=tan(20°)`;同一半径的轴向齿距px,齿顶宽`px/2-2*mx*tan20°`。单条齿顶螺旋每转360°推进lead,不能把模型表面分段数当头数。
用`model.edges`定位轴向母线和齿顶/齿根边,再以`inspect.curvature_comb`边采样的`combs[].teeth[][0]`实际曲线脚点核对母线斜率、导程与旋向;`model.edges.mid/length`来自显示折线,不能作为精确曲线内点或弧长;在两个端面分别应有s组齿顶区间、2s个齿顶边界交点。多头既要端面间隔正确,也要沿轴重复节距正确,仅检查时间线count不够。
必要时以实际齿面运行`inspect.curvature_comb {faces:[实际选点],count:2,density:128}`,用其teeth的起点采样检查ZA螺旋面,之后`clear:true`关闭分析。以+Y为初始齿中心方位,右旋取h=1、左旋h=-1:`q=z-h*lead*(theta-pi/2)/(2*pi)`;工作齿面应满足`q=±[px/4-(r-d/2)*tan20°] (mod px)`。这区分实际工作面与只有外观相似的螺旋棱。
体积与根圆柱加螺旋齿占空积分核对,但有限长度蜗杆的X/Y质心通常不为0,不能假定轴对称。实际曲面采样是有限点检查,不等于全曲面误差证明、配对接触验证或制造认证;修改模数/头数/旋向后重新检查,保留简化声明。
@@ -1,66 +0,0 @@
# 圆柱蜗杆:ZA轴向直线齿形与实体螺旋齿规程 v1
实验候选,真实引擎回放与正式助手收益分别记录。当前采用**ZA型轴向直线齿形**、轴向压力角20°、零变位/侧隙、齿顶高系数1、顶隙系数0.25、平齿顶和简化尖角齿根,1~4头。明确要求ZI/ZN/ZK、包络蜗杆、鼓形、退刀槽或制造级啮合时不套用,也不把这份单体规程当作蜗轮已共轭的证据。
## 轴向参数与基准
Z为蜗杆轴,从Z=0到L。轴向模数mx、分度圆直径d、有效齿长L、头数s及左右旋必须明确;用户给法向模数时不能直接当mx。轴向齿距`px=pi*mx`,**一头转一整圈的导程`lead=s*px`**,不能多头时仍把px传给coil的pitch。导程角`atan(lead/(pi*d))`是派生值。
`parameters.add`长度`unit:"mm"`、角度`unit:"deg"`、头数`unit:""`:
```text
wormModule, wormPitchDiameter, wormLength = 明确轴向模数、d、L [mm]
wormStarts = 明确头数s [整数]
wormPressure = 20 deg
wormPitchRadius = wormPitchDiameter/2 [mm]
wormAxialPitch = pi*wormModule [mm]
wormLead = wormStarts*wormAxialPitch [mm]
wormRootRadius = wormPitchRadius-1.25*wormModule [mm]
wormTipRadius = wormPitchRadius+wormModule [mm]
wormProfileInner = wormRootRadius-0.1*wormModule [mm]
wormInnerHalfWidth = wormAxialPitch/4+(wormPitchRadius-wormProfileInner)*tan(wormPressure) [mm]
wormTipHalfWidth = wormAxialPitch/4-wormModule*tan(wormPressure) [mm]
```
要求`wormRootRadius>0.1*wormModule`、`wormLength>=wormAxialPitch`、`(wormLength+2*wormLead)/wormLead<=200`;轴向齿顶宽`2*wormTipHalfWidth>0`,根线齿宽`wormAxialPitch/2+2.5*wormModule*tan(wormPressure)<wormAxialPitch`。可选孔半径必须小于齿根半径。不能按轴向齿距解释头数,也不能把分度径当齿根径。
## 用当前coil工具生成实体齿
先生成延长的实心芯轴:
```json
{"command":"solid.cylinder","params":{"radius":"wormRootRadius","height":"wormLength+4*wormLead","base":[0,0,"-2*wormLead"],"operation":"new","body_name":"Worm","name":"WormCore"}}
```
1. `sketch.create {plane:"YZ",name:"WormAxialRidge"}`。YZ局部x=世界Y,表示半径;局部y=世界Z,表示轴向位置。一次`sketch.line {infer:false,points:[...]}`画闭合梯形,检查一个闭合区域并结束草图:
```json
[
["wormProfileInner","-wormLead-wormInnerHalfWidth"],
["wormTipRadius","-wormLead-wormTipHalfWidth"],
["wormTipRadius","-wormLead+wormTipHalfWidth"],
["wormProfileInner","-wormLead+wormInnerHalfWidth"],
["wormProfileInner","-wormLead-wormInnerHalfWidth"]
]
```
2. 以这个**轴向梯形草图**直接做螺旋扫掠并Join芯轴:
```json
{"command":"solid.coil","params":{"sketch":"WormAxialRidge","pitch":"wormLead","height":"wormLength+2*wormLead","axis":"Z","base":[0,0,0],"clockwise":false,"operation":"join","targets":["Worm"],"name":"WormRidge"}}
```
沿+Z,`clockwise:false`为右旋,左旋改`true`;保持pitch与height为正。给了sketch时,半径和起始相位由草图实际位置确定,**不再提供diameter、section_size、section或start_angle**。不能用默认圆截面coil画成弹簧,也不能将整个梯形围绕Z旋转成圆环。
3. s>1时`solid.pattern.circular {features:["WormRidge"],axis:"Z",count:"wormStarts",name:"WormStartsPattern"}`,阵列已Join的螺旋齿特征,计数包含原齿;s=1省略。每头相差360°/s,导程不变,不阵列整个芯轴。
4. 用`solid.cylinder {radius:"wormTipRadius+wormModule",height:"wormLength",base:[0,0,0],operation:"intersect",targets:["Worm"],name:"WormEndTrim"}`裁出Z=0~L,去掉两端延长段。轴孔和轴颈仅按需求添加,孔不得穿到齿根外,不生成蜗轮或轴承。
## 实际几何检查
一个闭合实体、无失败时间线,齿根与芯轴连成整体,包围盒径向±wormTipRadius、轴向0~L。轴向固定方位截面的工作齿面是直线,`abs(dz/dr)=tan(20°)`;同一半径的轴向齿距px,齿顶宽`px/2-2*mx*tan20°`。单条齿顶螺旋每转360°推进lead,不能把模型表面分段数当头数。
从实际`model.edges`读取轴向直线母线、齿顶/齿根螺旋边,核对母线斜率、导程与旋向;在两个端面分别应有s组齿顶区间、2s个齿顶边界交点。多头既要端面间隔正确,也要沿轴重复节距正确,仅检查时间线count不够。
必要时以实际齿面运行`inspect.curvature_comb {faces:[实际选点],count:2,density:128}`,用其teeth的起点采样检查ZA螺旋面,之后`clear:true`关闭分析。以+Y为初始齿中心方位,右旋取h=1、左旋h=-1:`q=z-h*lead*(theta-pi/2)/(2*pi)`;工作齿面应满足`q=±[px/4-(r-d/2)*tan20°] (mod px)`。这区分实际工作面与只有外观相似的螺旋棱。
体积与根圆柱加螺旋齿占空积分核对,但有限长度蜗杆的X/Y质心通常不为0,不能假定轴对称。实际曲面采样是有限点检查,不等于全曲面误差证明、配对接触验证或制造认证;修改模数/头数/旋向后重新检查,保留简化声明。
@@ -1,7 +0,0 @@
# XZ草图三角筋:方向与连接提示
仅用于当前已选择XZ草图构造轴承座筋的操作,不提供整套座体流程。
原引擎XZ草图的局部第二坐标对应世界−Z,法向为+Y。世界点(X,Z)应写成局部[X,−Z]。底板顶高T、筋高h、支承半宽P/2、外伸a时,右筋三点为`[P/2,-T]、[P/2+a,-T]、[P/2,-T-h]`;左筋X取反。所有尺寸取当前已确认参数。
筋沿Y居中且厚t时,草图offset=`-t/2`,沿法向挤出`t`并join到实际座体targets。随后再切座孔,避免后加筋堵孔。核对筋在底板上方、两侧均连接底板和支承;过去把局部第二坐标写成正数得到向下筋及三个shell。
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -1,142 +0,0 @@
{
"schema_version": 1,
"description": "助手自主选择的阅读目录。目录中的Markdown按ID直接读取;条件与近似由助手结合正文理解,不作为读前门槛。",
"documents": [
{
"id": "involute-spur-gear",
"name_zh": "外渐开线直齿圆柱齿轮",
"source_doc_id": "gear-browser-equation-workflow",
"version": "0.2.0",
"path": "generation/candidates/involute-spur-gear-equation-v2.md",
"summary": "仅外直齿渐开线构造;18–40齿、20°、零变位;斜齿请读专用整体扭转规程。"
},
{
"id": "internal-spur-gear",
"name_zh": "内直齿圆柱齿轮",
"source_doc_id": "internal-spur-equation-workflow",
"version": "0.1.0",
"path": "generation/candidates/internal-spur-gear-v1.md",
"summary": "内直齿圈渐开线构造;核对外半径、环体与简化齿根。"
},
{
"id": "helical-cylindrical-gear",
"name_zh": "斜齿圆柱齿轮",
"source_doc_id": "helical-cylinder-whole-section",
"version": "0.1.2",
"path": "generation/candidates/helical-cylindrical-gear-v1-2.md",
"summary": "外斜齿专用:完整齿圈整体扭转,根圆内/外分支;不要套用直齿单齿Join。"
},
{
"id": "straight-rack",
"name_zh": "直齿齿条",
"source_doc_id": "straight-rack-linear-flank",
"version": "0.1.0",
"path": "generation/candidates/straight-rack-v1.md",
"summary": "直齿齿条;直线齿廓、节线、齿根及线性阵列。"
},
{
"id": "helical-rack",
"name_zh": "斜齿齿条",
"source_doc_id": "helical-rack-parallel-sweep",
"version": "0.1.1",
"path": "generation/candidates/helical-rack-v1-1.md",
"summary": "斜齿齿条;法向参数与平行扫掠,保留齿形。"
},
{
"id": "worm",
"name_zh": "蜗杆",
"source_doc_id": "za-worm-sketch-coil",
"version": "0.1.1",
"path": "generation/candidates/worm-za-v1-1.md",
"summary": "ZA圆柱蜗杆;轴向参数、头数、导程与螺旋构造。"
},
{
"id": "straight-bevel-gear",
"name_zh": "直齿锥齿轮",
"source_doc_id": "straight-bevel-scaled-section",
"version": "0.1.1",
"path": "generation/candidates/straight-bevel-gear-scaled-section-v1-1.md",
"summary": "直齿锥齿轮;母线宽转轴向高度、共顶点定位与整体缩放;非制造级齿面。"
},
{
"id": "spiral-bevel-gear",
"name_zh": "螺旋锥齿轮",
"source_doc_id": "spiral-bevel-axial-twist",
"version": "0.1.0",
"path": "generation/candidates/spiral-bevel-gear-axial-twist-v1.md",
"summary": "螺旋锥齿轮;端面缩放加轴向扭转示意,非共轭齿面。"
},
{
"id": "worm-wheel",
"name_zh": "蜗轮",
"source_doc_id": "worm-wheel-toroidal-throat",
"version": "0.1.2",
"path": "generation/candidates/worm-wheel-toroidal-throat-illustration-v1-2.md",
"summary": "示意蜗轮;端面渐开线与环面喉部,不声称真实包络。"
},
{
"id": "gear-pair",
"name_zh": "平行轴外直齿和斜齿轮副",
"source_doc_id": "parallel-axis-gear-pair",
"version": "0.2.0",
"path": "generation/candidates/gear-pair-fixed-axis-v2.md",
"summary": "平行轴外直/斜齿副的轴距、共同截面相位和显式侧隙;各轮齿形另读。"
},
{
"id": "rack-and-pinion",
"name_zh": "齿轮齿条机构",
"source_doc_id": "straight-rack-pinion-interface",
"version": "0.1.0",
"path": "generation/candidates/rack-and-pinion-straight-v1.md",
"summary": "直齿齿条与小齿轮的坐标、相位和接口关系。"
},
{
"id": "worm-drive",
"name_zh": "蜗轮蜗杆机构",
"source_doc_id": "illustrative-worm-drive-interface",
"version": "0.1.0",
"path": "generation/candidates/worm-drive-illustrative-v1.md",
"summary": "ZA蜗杆与示意蜗轮机构;异面轴接口及表示边界。"
},
{
"id": "planetary-gear-mechanism",
"name_zh": "行星齿轮机构",
"source_doc_id": "straight-planetary-interface",
"version": "0.1.0",
"path": "generation/candidates/planetary-gear-mechanism-straight-v1.md",
"summary": "直齿太阳轮、行星轮、内齿圈及行星架接口;保留实体齿形。"
},
{
"id": "ball-bearing",
"name_zh": "球轴承(滚珠轴承、深沟球轴承)",
"source_doc_id": "ball-bearing-open-deep-groove",
"version": "0.1.0",
"path": "generation/candidates/ball-bearing-open-deep-groove-v1.md",
"summary": "轴承/bearing、球轴承/ball bearing及装配内球轴承:内外圈、滚道、独立滚珠和保持架;内置标准件仅包络,不能代替完整结构。轴套、滚子、裸座体另辨。"
},
{
"id": "ribbed-bearing-housing",
"name_zh": "整体式带筋轴承座座体",
"source_doc_id": "housing-y-bore",
"version": "0.2.0",
"path": "generation/candidates/xz-rib-orientation-risk-v2.md",
"summary": "仅XZ草图造筋方向风险提示;不是完整座体教程。"
},
{
"id": "herringbone-gear",
"name_zh": "无槽连续人字齿轮",
"source_doc_id": "herringbone-continuous",
"version": "0.1.1",
"path": "generation/candidates/herringbone-continuous-v1-1.md",
"summary": "无槽连续人字齿轮;中面连接与两侧相反旋向。"
},
{
"id": "double-helical-gear",
"name_zh": "带中央退刀槽双斜齿轮",
"source_doc_id": "double-helical-gap",
"version": "0.1.1",
"path": "generation/candidates/double-helical-central-gap-v1-1.md",
"summary": "带中央槽双斜齿轮;齿根芯连接、槽宽与两侧齿形。"
}
]
}
@@ -1,287 +0,0 @@
"""Emit deterministic current-browser references; never call a generation model.
Generated inputs and artifacts live in a new external experiment directory. Existing
files are opened exclusively, so historical failures and test jobs cannot be replaced.
"""
import argparse
import copy
import json
import math
from pathlib import Path
BUILD = "f3d62ce93f72db42f311a46e"
def cmd(command, **params):
return {"command": command, "params": params}
def params(definitions):
return [cmd("parameters.add", name=n, expression=e, unit=u) for n, e, u in definitions]
def mm(name, value):
return name, f"{value} mm", "mm"
def batch(commands):
return {"method": "engine.batch", "params": {"commands": commands, "rollback": True}}
def ref(type_id, definitions, phases, expected, facts, edit):
return {"type_id": type_id, "engine_build": BUILD,
"source": "deterministic_reference_not_model_generation",
"parameters": definitions, "facts": facts, "expected": expected,
"steps": [batch(params(definitions))] + [batch(p) for p in phases],
"parameter_edit": edit}
def plate(alternate=False):
length, width, thick = (120, 70, 10) if alternate else (100, 60, 8)
holes = [(-39, -16, 5), (36, -17, 7), (-38, 18, 6), (40, 20, 4)] if alternate else [
(-35, -15, 6), (35, -15, 6), (-35, 15, 6), (35, 15, 6)]
definitions = [mm("plateLength", length), mm("plateWidth", width), mm("plateThickness", thick)]
operations = [cmd("solid.box", corner=["-plateLength/2", "-plateWidth/2", 0], length="plateLength",
width="plateWidth", height="plateThickness", operation="new", body_name="Plate", name="PlateBlank")]
cylinders = []
for i, (x, y, d) in enumerate(holes, 1):
definitions += [mm(f"hole{i}X", x), mm(f"hole{i}Y", y), mm(f"hole{i}Diameter", d)]
operations += [cmd("solid.cylinder", diameter=f"hole{i}Diameter", height="plateThickness+2 mm",
base=[f"hole{i}X", f"hole{i}Y", -1], operation="cut", targets=["Plate"], name=f"Hole{i}")]
cylinders.append(cylinder(d / 2, [x, y, 0], [0, 0, 1], [0, thick], f"hole{i}"))
expected = {"bodies": [{"bbox": [[-length/2, -width/2, 0], [length/2, width/2, thick]],
"volume": (length*width-sum(math.pi*d*d/4 for _, _, d in holes))*thick,
"cylinders": cylinders}], "holes": holes}
return ref("mounting-plate", definitions, [operations], expected,
{"geometry_representation": "rectangular-plate-z-through-holes-v1", "hole_count": len(holes)},
{"name": "plateThickness", "expression": f"{thick+2} mm"})
def cylinder(radius, origin, axis, interval, role):
return {"radius": radius, "origin": origin, "axis": axis, "interval": interval, "role": role}
def shaft(alternate=False):
segments = [(24, 25), (16, 30), (10, 15)] if alternate else [(20, 40), (12, 20)]
definitions, operations, cylinders = [], [], []
z, volume = 0, 0
for i, (d, length) in enumerate(segments, 1):
start = "0 mm" if i == 1 else f"segment{i-1}Start+segment{i-1}Length"
definitions += [mm(f"segment{i}Diameter", d), mm(f"segment{i}Length", length), (f"segment{i}Start", start, "mm")]
operation = {"operation": "new", "body_name": "Shaft"} if i == 1 else {"operation": "join", "targets": ["Shaft"]}
operations.append(cmd("solid.cylinder", diameter=f"segment{i}Diameter", height=f"segment{i}Length",
base=[0, 0, f"segment{i}Start"], name=f"Segment{i}", **operation))
cylinders.append(cylinder(d/2, [0, 0, 0], [0, 0, 1], [z, z+length], f"segment{i}"))
z += length
volume += math.pi*d*d*length/4
radius = max(d for d, _ in segments)/2
expected = {"bodies": [{"bbox": [[-radius, -radius, 0], [radius, radius, z]], "volume": volume, "cylinders": cylinders}], "segments": segments}
return ref("stepped-shaft", definitions, [operations], expected,
{"geometry_representation": "coaxial-solid-stepped-shaft-v1", "segment_count": len(segments)},
{"name": "segment1Length", "expression": f"{segments[0][1]+10} mm"})
def bolt(alternate=False):
d, length, af, head, thread, pitch = (10, 40, 17, 7, 25, 1.5) if alternate else (8, 30, 14, 5, 20, 1.25)
definitions = [mm("nominalDiameter", d), mm("underHeadLength", length), mm("acrossFlats", af),
mm("headHeight", head), mm("threadLength", thread), mm("threadPitch", pitch),
("headRadius", "acrossFlats/sqrt(3)", "mm")]
points = [[f"headRadius*cos({i*60} deg)", f"headRadius*sin({i*60} deg)"] for i in range(6)]
phases = [[cmd("solid.cylinder", diameter="nominalDiameter", height="underHeadLength", operation="new", body_name="Bolt", name="SimplifiedShank")],
[cmd("sketch.create", name="HexHead", plane="XY", offset="underHeadLength"),
cmd("sketch.line", points=points, closed=True, infer=False), cmd("sketch.solve"), cmd("sketch.finish")],
[cmd("solid.extrude", sketch="HexHead", distance="headHeight", operation="join", targets=["Bolt"], name="HexHeadExtrude")],
[cmd("parameters.comment", name="threadLength", comment="简化螺纹区:杆端Z=0至threadLength;圆柱实体,无真实牙型"),
cmd("parameters.comment", name="threadPitch", comment="仅螺距语义标注,不切削真实螺旋牙型")]]
radius = af/math.sqrt(3)
expected = {"bodies": [{"bbox": [[-radius, -af/2, 0], [radius, af/2, length+head]],
"volume": math.pi*d*d*length/4+math.sqrt(3)*af*af*head/2,
"cylinders": [cylinder(d/2, [0, 0, 0], [0, 0, 1], [0, length], "shank")]}],
"across_flats": af, "head_z": [length, length+head], "thread_interval": [0, thread]}
facts = {"geometry_representation": "hex-bolt-simplified-thread-v1", "nominal_diameter_mm": d,
"under_head_length_mm": length, "across_flats_mm": af, "head_height_mm": head, "thread_length_mm": thread}
return ref("hex-head-bolt", definitions, phases, expected, facts,
{"name": "underHeadLength", "expression": f"{length+10} mm"})
def adaptive_simpson(f, a, b, eps=1e-9, depth=24):
def go(a, b, fa, fm, fb, whole, eps, depth):
mid = (a+b)/2
left_mid, right_mid = (a+mid)/2, (mid+b)/2
fl, fr = f(left_mid), f(right_mid)
left, right = (mid-a)*(fa+4*fl+fm)/6, (b-mid)*(fm+4*fr+fb)/6
if depth == 0 or abs(left+right-whole) <= 15*eps:
return left+right+(left+right-whole)/15
return go(a, mid, fa, fl, fm, left, eps/2, depth-1)+go(mid, b, fm, fr, fb, right, eps/2, depth-1)
fa, fm, fb = f(a), f((a+b)/2), f(b)
return go(a, b, fa, fm, fb, (b-a)*(fa+4*fm+fb)/6, eps, depth)
def housing(alternate=False):
L, W, T, D, bore, C, B, P, rt, reach, rh, cb, depth = (140, 80, 14, 64, 30, 50, 46, 46, 7, 20, 20, 38, 8) if alternate else (120, 70, 12, 60, 32, 45, 40, 44, 6, 18, 18, 40, 6)
hx, hy, hd = (56, 28, 9) if alternate else (48, 23, 8)
values = {"baseLength": L, "baseWidth": W, "baseThickness": T, "bossDiameter": D, "boreDiameter": bore,
"centerHeight": C, "bossWidth": B, "pedestalWidth": P, "ribThickness": rt, "ribReach": reach,
"ribHeight": rh, "counterboreDiameter": cb, "counterboreDepth": depth, "mountX": hx, "mountY": hy, "mountDiameter": hd}
definitions = [mm(n, v) for n, v in values.items()]
main = [cmd("solid.box", corner=["-baseLength/2", "-baseWidth/2", 0], length="baseLength", width="baseWidth", height="baseThickness", operation="new", body_name="Housing", name="Base"),
cmd("solid.box", corner=["-pedestalWidth/2", "-bossWidth/2", "baseThickness"], length="pedestalWidth", width="bossWidth", height="centerHeight-baseThickness", operation="join", targets=["Housing"], name="Pedestal"),
cmd("solid.cylinder", diameter="bossDiameter", height="bossWidth", axis=[0, 1, 0], base=[0, "-bossWidth/2", "centerHeight"], operation="join", targets=["Housing"], name="BearingBoss")]
phases = [main]
for side, sign in (("Left", -1), ("Right", 1)):
a = "-pedestalWidth/2" if sign < 0 else "pedestalWidth/2"
outside = f"{a}{'-' if sign<0 else '+'}ribReach"
phases.append([cmd("sketch.create", name=f"{side}Rib", plane="XZ", offset="-ribThickness/2"),
# Native XZ uses local (X,-Z), with normal +Y.
cmd("sketch.line", points=[[a, "-baseThickness"], [outside, "-baseThickness"], [a, "-baseThickness-ribHeight"]], closed=True, infer=False),
cmd("sketch.solve"), cmd("sketch.finish"),
cmd("solid.extrude", sketch=f"{side}Rib", distance="ribThickness", operation="join", targets=["Housing"], name=f"{side}RibExtrude")])
cut = [cmd("solid.cylinder", diameter="boreDiameter", height="bossWidth+2 mm", base=[0, "-bossWidth/2-1 mm", "centerHeight"], axis=[0, 1, 0], operation="cut", targets=["Housing"], name="BearingBore"),
cmd("solid.cylinder", diameter="counterboreDiameter", height="counterboreDepth", base=[0, "-bossWidth/2", "centerHeight"], axis=[0, 1, 0], operation="cut", targets=["Housing"], name="NegativeYCounterbore")]
cylinders = [cylinder(bore/2, [0, 0, C], [0, 1, 0], [-B/2+depth, B/2], "bearing-bore"),
cylinder(cb/2, [0, 0, C], [0, 1, 0], [-B/2, -B/2+depth], "negative-y-counterbore")]
for i, (sx, sy) in enumerate(((-1, -1), (1, -1), (-1, 1), (1, 1)), 1):
cut.append(cmd("solid.cylinder", diameter="mountDiameter", height="baseThickness+2 mm", base=[f"{sx}*mountX", f"{sy}*mountY", -1], operation="cut", targets=["Housing"], name=f"MountHole{i}"))
cylinders.append(cylinder(hd/2, [sx*hx, sy*hy, 0], [0, 0, 1], [0, T], f"mount{i}"))
phases.append(cut)
R, a = D/2, P/2
overlap = a*math.sqrt(R*R-a*a)+R*R*math.asin(a/R)
def rib_overlap(x):
if x >= R:
return 0
low, high = C-math.sqrt(R*R-x*x), C+math.sqrt(R*R-x*x)
top = T+rh*(1-(x-a)/reach)
return max(0, min(top, high)-max(T, low))
extra_ribs = 2*rt*(reach*rh/2-adaptive_simpson(rib_overlap, a, a+reach))
volume = L*W*T+(P*(C-T)+math.pi*R*R-overlap)*B+extra_ribs-math.pi*(bore/2)**2*B-math.pi*((cb/2)**2-(bore/2)**2)*depth-4*math.pi*(hd/2)**2*T
expected = {"bodies": [{"bbox": [[-L/2, -W/2, 0], [L/2, W/2, C+R]], "volume": volume, "cylinders": cylinders}],
"rib_sections": {"thickness": rt, "reach": reach, "height": rh, "base_z": T, "side_x": a},
"volume_method": "independent circle/rectangle union and adaptive Simpson rib overlap; no mesh or fitted volume"}
facts = {"geometry_representation": "ribbed-housing-y-bore-z-mount-v1", "center_height_mm": C, "base_thickness_mm": T,
"boss_outer_diameter_mm": D, "bore_diameter_mm": bore, "boss_width_mm": B, "pedestal_width_mm": P,
"rib_height_mm": rh, "min_wall_mm": 3}
return ref("ribbed-bearing-housing", definitions, phases, expected, facts,
{"name": "centerHeight", "expression": f"{C+5} mm"})
def enclosure(alternate=False):
L, W, H, t, bottom, lid, gap, inset, D, pilot, cover, bh, pd, rt, rh = (140, 90, 45, 3, 4, 5, 0.5, 12, 12, 4, 5, 41, 14, 2.5, 14) if alternate else (120, 80, 40, 3, 3, 4, 0.3, 10, 10, 3, 4, 37, 12, 2, 12)
values = {"caseLength": L, "caseWidth": W, "caseHeight": H, "wallThickness": t, "bottomThickness": bottom,
"lidThickness": lid, "assemblyGap": gap, "fastenerInset": inset, "bossDiameter": D, "pilotDiameter": pilot,
"coverHoleDiameter": cover, "bossHeight": bh, "pilotDepth": pd, "ribThickness": rt, "ribHeight": rh}
definitions = [mm(n, v) for n, v in values.items()]+[("fastenerX", "caseLength/2-fastenerInset", "mm"), ("fastenerY", "caseWidth/2-fastenerInset", "mm")]
main = [cmd("solid.box", corner=["-caseLength/2", "-caseWidth/2", 0], length="caseLength", width="caseWidth", height="caseHeight", operation="new", body_name="Case", name="CaseBlank"),
cmd("solid.box", corner=["-caseLength/2+wallThickness", "-caseWidth/2+wallThickness", "bottomThickness"], length="caseLength-2*wallThickness", width="caseWidth-2*wallThickness", height="caseHeight-bottomThickness+1 mm", operation="cut", targets=["Case"], name="OpenCavity")]
additions, cuts, cover_cuts, cylinders = [], [], [], []
cover_cylinders = []
for i, (sx, sy) in enumerate(((-1, -1), (1, -1), (-1, 1), (1, 1)), 1):
x, y = f"{sx}*fastenerX", f"{sy}*fastenerY"
# Each rib overlaps the boss and terminates at the inner Y wall.
rib_y = "fastenerY" if sy > 0 else "-caseWidth/2+wallThickness"
additions += [cmd("solid.cylinder", diameter="bossDiameter", height="bossHeight", base=[x, y, "bottomThickness"], operation="join", targets=["Case"], name=f"Boss{i}"),
cmd("solid.box", corner=[f"{x}-ribThickness/2", rib_y, "bottomThickness"], length="ribThickness", width="fastenerInset-wallThickness", height="ribHeight", operation="join", targets=["Case"], name=f"BossRib{i}")]
cuts += [cmd("solid.cylinder", diameter="pilotDiameter", height="pilotDepth", base=[x, y, "bottomThickness+bossHeight"], axis=[0, 0, -1], operation="cut", targets=["Case"], name=f"BlindPilot{i}")]
cover_cuts += [cmd("solid.cylinder", diameter="coverHoleDiameter", height="lidThickness+2 mm", base=[x, y, "caseHeight+assemblyGap-1 mm"], operation="cut", targets=["Lid"], name=f"CoverHole{i}")]
cylinders.append(cylinder(pilot/2, [sx*(L/2-inset), sy*(W/2-inset), 0], [0, 0, 1], [bottom+bh-pd, bottom+bh], f"blind-pilot{i}"))
cover_cylinders.append(cylinder(cover/2, [sx*(L/2-inset), sy*(W/2-inset), 0], [0, 0, 1], [H+gap, H+gap+lid], f"cover-hole{i}"))
cover_main = [cmd("solid.box", corner=["-caseLength/2", "-caseWidth/2", "caseHeight+assemblyGap"], length="caseLength", width="caseWidth", height="lidThickness", operation="new", body_name="Lid", name="IndependentLid")]
R, a = D/2, rt/2
rib_overlap = a*math.sqrt(R*R-a*a)+R*R*math.asin(a/R)
volume = L*W*H-(L-2*t)*(W-2*t)*(H-bottom)+4*math.pi*R*R*bh+4*(rt*(inset-t)-rib_overlap)*rh-4*math.pi*(pilot/2)**2*pd
expected = {"bodies": [{"bbox": [[-L/2, -W/2, 0], [L/2, W/2, H]], "volume": volume, "cylinders": cylinders},
{"bbox": [[-L/2, -W/2, H+gap], [L/2, W/2, H+gap+lid]], "volume": (L*W-4*math.pi*(cover/2)**2)*lid, "cylinders": cover_cylinders}],
"gap": gap, "inner_cavity": [L-2*t, W-2*t, H-bottom], "shared_fastener_xy": [L/2-inset, W/2-inset]}
facts = {"geometry_representation": "open-case-four-bosses-independent-flat-lid-v1", "length_mm": L, "width_mm": W,
"height_mm": H, "wall_thickness_mm": t, "bottom_thickness_mm": bottom, "lid_thickness_mm": lid,
"assembly_gap_mm": gap, "fastener_inset_mm": inset, "boss_outer_diameter_mm": D, "boss_height_mm": bh,
"pilot_depth_mm": pd, "rib_height_mm": rh, "min_wall_mm": 1.5}
return ref("covered-thin-wall-enclosure", definitions, [main, additions, cuts, cover_main+cover_cuts], expected, facts,
{"name": "fastenerInset", "expression": f"{inset+2} mm"})
def herringbone(grooved=False, alternate=False):
mn, teeth, beta = (1.5, 20, -15) if alternate else (2, 24, 20)
width, gap = ((18, 2) if alternate else (20, 4)) if grooved else ((18, 0) if alternate else (16, 0))
bore = 6 if alternate else 8
definitions = [mm("normalModule", mn), ("gearTeeth", str(teeth), ""), ("normalPressure", "20 deg", "deg"),
("helixAngle", f"{beta} deg", "deg"), mm("gearWidth", width), mm("centralGap", gap), mm("boreDiameter", bore),
("halfWidth", "(gearWidth-centralGap)/2", "mm"), ("transverseModule", "normalModule/cos(helixAngle)", "mm"),
("gearPressure", "atan(tan(normalPressure)/cos(helixAngle))", "deg"),
("pitchRadius", "transverseModule*gearTeeth/2", "mm"), ("baseRadius", "pitchRadius*cos(gearPressure)", "mm"),
("tipRadius", "pitchRadius+normalModule", "mm"), ("rootRadius", "pitchRadius-1.25*normalModule", "mm"),
("toothBaseAngle", "90 deg/gearTeeth+(tan(gearPressure)-gearPressure/(1 rad))*(1 rad)", "deg"),
("tipRoll", "sqrt((tipRadius/baseRadius)^2-1)", ""),
("tipAngle", "toothBaseAngle-(tipRoll-atan(tipRoll)/(1 rad))*(1 rad)", "deg"),
("halfTwist", "halfWidth*tan(helixAngle)/pitchRadius*(1 rad)", "deg")]
phases = []
for prefix, offset, phase, twist, path_start in (("Lower", 0, "0 deg", "halfTwist", 0),
("Upper", "halfWidth+centralGap", "halfTwist", "-halfTwist", "halfWidth+centralGap")):
def point(radius, angle):
return [f"{radius}*cos(({phase})+({angle}))", f"{radius}*sin(({phase})+({angle}))"]
a = "toothBaseAngle-(t-atan(t)/(1 rad))*(1 rad)"
profile = [cmd("sketch.create", plane="XY", offset=offset, name=prefix+"Section"),
cmd("sketch.line", points=[point("rootRadius", "-toothBaseAngle"), point("baseRadius", "-toothBaseAngle")], infer=False),
cmd("sketch.equation_curve", x=f"baseRadius*sqrt(1+t^2)*cos(({phase})-({a}))", y=f"baseRadius*sqrt(1+t^2)*sin(({phase})-({a}))", start=0, end="tipRoll", tolerance=0.002),
cmd("sketch.arc.three_point", start=point("tipRadius", "-tipAngle"), through=point("tipRadius", "0 deg"), end=point("tipRadius", "tipAngle")),
cmd("sketch.equation_curve", x=f"baseRadius*sqrt(1+t^2)*cos(({phase})+({a}))", y=f"baseRadius*sqrt(1+t^2)*sin(({phase})+({a}))", start=0, end="tipRoll", tolerance=0.002),
cmd("sketch.line", points=[point("baseRadius", "toothBaseAngle"), point("rootRadius", "toothBaseAngle")], infer=False),
cmd("sketch.arc.three_point", start=point("rootRadius", "toothBaseAngle"), through=point("rootRadius", "180 deg/gearTeeth"), end=point("rootRadius", "360 deg/gearTeeth-toothBaseAngle")),
cmd("sketch.pattern.circular", entities=["l1", "s1", "a1", "s2", "l2", "a2"], center=[0, 0], count="gearTeeth"), cmd("sketch.solve"), cmd("sketch.finish")]
path = [cmd("sketch.create", plane="YZ", name=prefix+"Path"),
cmd("sketch.line", points=[[0, path_start], [0, "halfWidth" if prefix=="Lower" else "gearWidth"]], infer=False), cmd("sketch.finish")]
if prefix == "Upper":
continue
phases += [profile, path, [cmd("solid.sweep", sketch=prefix+"Section", path_sketch=prefix+"Path", path=["l1"], orientation="parallel", twist=twist, operation="new", body_name="Gear", name=prefix+"Teeth")]]
if grooved:
# Extend only into the groove, avoiding coincident swept cylindrical faces.
phases += [[cmd("solid.cylinder", radius="rootRadius", height="centralGap", base=[0, 0, "halfWidth"], operation="join", targets=["Gear"], name="CentralRootBridge")]]
# Mirror the completed half+half-gap, so the bridge overlaps in the groove.
# Remove the excess half of the bridge before mirroring by using G/2.
phases[-1][0]["params"]["height"] = "centralGap/2"
phases += [[cmd("solid.mirror", bodies=["Gear"], plane={"origin": [0, 0, "gearWidth/2"], "normal": [0, 0, 1]}, combine=True, name="OppositeHandHalf")]]
phases += [[cmd("solid.cylinder", diameter="boreDiameter", height="gearWidth+2 mm", base=[0, 0, -1], operation="cut", targets=["Gear"], name="Bore")]]
beta_r, alpha_n = math.radians(beta), math.radians(20)
pitch = mn/math.cos(beta_r)*teeth/2
alpha = math.atan(math.tan(alpha_n)/math.cos(beta_r))
rb, ra, rf = pitch*math.cos(alpha), pitch+mn, pitch-1.25*mn
base_angle = math.pi/(2*teeth)+math.tan(alpha)-alpha
roll = math.sqrt((ra/rb)**2-1)
area = math.pi*rf*rf+teeth*(rb*rb*roll**3/3+ra*ra*(base_angle-roll+math.atan(roll))-rf*rf*base_angle)
expected = {"bodies": [{"bbox": [[-ra, -ra, 0], [ra, ra, width]],
"volume": (area-math.pi*(bore/2)**2)*(width-gap)+(math.pi*rf*rf-math.pi*(bore/2)**2)*gap,
"cylinders": [cylinder(bore/2, [0, 0, 0], [0, 0, 1], [0, width], "bore")]}],
"gear": {"normal_module": mn, "teeth": teeth, "beta_deg": beta, "width": width, "gap": gap,
"pitch_radius": pitch, "base_radius": rb, "tip_radius": ra, "root_radius": rf,
"base_angle_rad": base_angle, "half_width": (width-gap)/2, "half_twist_rad": (width-gap)/2*math.tan(beta_r)/pitch}}
type_id = "double-helical-gear" if grooved else "herringbone-gear"
facts = {"normal_module_mm": mn, "teeth": teeth, "normal_pressure_angle_deg": 20, "helix_angle_deg": beta,
"face_width_mm": width, "central_gap_mm": gap, "profile_shift": 0, "backlash_mm": 0,
"addendum_coefficient": 1, "clearance_coefficient": 0.25, "root_transition": "radial-simplified",
"geometry_representation": "double-helical-root-core-gap-v1" if grooved else "herringbone-continuous-midplane-v1"}
return ref(type_id, definitions, phases, expected, facts, {"name": "gearWidth", "expression": f"{width+4} mm"})
BUILDERS = {"mounting-plate": plate, "stepped-shaft": shaft, "hex-head-bolt": bolt,
"ribbed-bearing-housing": housing, "covered-thin-wall-enclosure": enclosure,
"herringbone-gear": lambda alternate=False: herringbone(False, alternate),
"double-helical-gear": lambda alternate=False: herringbone(True, alternate)}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("output", type=Path)
args = parser.parse_args()
args.output.mkdir(parents=True, exist_ok=True)
for type_id, builder in BUILDERS.items():
for alternate in (False, True):
data = builder(alternate)
path = args.output/f"reference-{type_id}-{'transfer' if alternate else 'standard'}.json"
with path.open("x") as stream:
json.dump(data, stream, ensure_ascii=False, indent=2)
stream.write("\n")
print(json.dumps({"references": 14, "engine_build": BUILD, "model_requests": 0}))
if __name__ == "__main__":
main()
@@ -1,280 +0,0 @@
"""Audit saved final geometry using scalar measures and actual comb evaluation feet.
Display edge midpoints are pick locations only. No model is generated or repaired.
An absent measurement fails the corresponding check rather than being inferred.
"""
import argparse
import copy
import hashlib
import json
import math
from pathlib import Path
LINEAR_TOL = 0.03
VOLUME_REL_TOL = 0.002
def read(path):
return json.loads(path.read_text())
def feet(batch):
return [[tooth[0] for tooth in comb.get("teeth", []) if len(tooth) == 2 and len(tooth[0]) == 3]
for comb in batch.get("value", {}).get("combs", [])]
def dot(a, b):
return sum(x*y for x, y in zip(a, b))
def radial(point, origin, axis):
v = [a-b for a, b in zip(point, origin)]
along = dot(v, axis)
return math.sqrt(max(0, dot(v, v)-along*along))
def cylinder_axis_matches(actual, expected):
axis, target = actual.get("axis", []), expected["axis"]
if len(axis) != 3 or abs(abs(dot(axis, target))-1) > 1e-6:
return False
if abs(actual.get("radius", -1)-expected["radius"]) > LINEAR_TOL:
return False
return radial(actual.get("origin", [math.inf]*3), expected["origin"], target) <= LINEAR_TOL
def wrap(angle, period):
return (angle+period/2) % period-period/2
def audit(directory, definition, allow_global_phase=False, parameter_role_map=None):
inspection = read(directory/"inspection.json")
expected = definition["expected"]
native = read(directory/"native-inventory.json")
samples = read(directory/"actual-edge-samples.json")
for supplement_path in sorted(directory.glob("actual-edge-samples-verified-*.json")):
supplement = read(supplement_path)
digest = hashlib.sha256((directory/"design.sc").read_bytes()).hexdigest()
if supplement.get("identity", {}).get("passed") is not True or supplement.get("source_native_sha256") != digest:
raise ValueError("Supplement does not verify the unchanged saved native design")
samples += supplement["batches"]
checks = []
def check(name, passed, actual=None, target=None):
checks.append({"name": name, "passed": bool(passed), "actual": actual, "expected": target})
bodies = inspection.get("bodies", [])
check("body_count", len(bodies) == len(expected["bodies"]), len(bodies), len(expected["bodies"]))
errors = [entry for entry in inspection.get("timeline", []) if entry.get("error") or entry.get("rolled_back")]
execution_path = directory/"reference-execution.json"
if execution_path.exists():
errors += [entry["value"]["failed"] for entry in read(execution_path) if entry.get("value", {}).get("failed")]
check("no_failed_features_or_batches", not errors, errors)
model_result = directory/"reference-result.json"
if model_result.exists():
check("deterministic_reference_sent_no_model_request", read(model_result).get("model_requests") == 0)
sampling_errors = [batch["value"] for batch in samples if batch.get("value", {}).get("error") or batch.get("value", {}).get("ok") is False]
check("actual_sample_tools_succeeded", not sampling_errors, sampling_errors)
# Roles come from actual geometry, never from reference body names.
remaining = list(bodies)
roles = []
for target in expected["bodies"]:
if not remaining:
roles.append(None)
continue
body = min(remaining, key=lambda b: abs(b["bbox"]["min"][2]-target["bbox"][0][2])+abs(b["bbox"]["max"][2]-target["bbox"][1][2]))
remaining.remove(body)
roles.append(body)
all_points = []
for role_index, (body, target) in enumerate(zip(roles, expected["bodies"])):
if body is None:
check(f"body{role_index}_present", False)
continue
name = body["name"]
curves = [curve for batch in samples if batch.get("body") == name for curve in feet(batch) if curve]
points = [p for curve in curves for p in curve]
all_points += points
faces = [face for entry in native if entry["command"] == "model.faces" and entry["body"] == name for face in entry["value"].get("faces", [])]
check(f"body{role_index}_closed_single_shell", body.get("closed") and body.get("volume_mm3", 0)>0 and body.get("kernel", {}).get("shells") == 1,
{k: body.get(k) for k in ("closed", "volume_mm3", "kernel")})
actual_box = [body["bbox"]["min"], body["bbox"]["max"]]
if "gear" in expected or definition["type_id"] == "hex-head-bolt":
# A legal Z rotation need not match the reference's X/Y extrema.
box_error = max(abs(actual_box[i][2]-target["bbox"][i][2]) for i in range(2))
else:
box_error = max(abs(a-b) for row_a, row_b in zip(actual_box, target["bbox"]) for a, b in zip(row_a, row_b))
check(f"body{role_index}_absolute_bounds", box_error <= LINEAR_TOL, actual_box, target["bbox"])
volume_error = abs(body.get("volume_mm3", 0)-target["volume"])/target["volume"]
check(f"body{role_index}_independent_volume", volume_error <= VOLUME_REL_TOL,
{"value": body.get("volume_mm3"), "relative_error": volume_error, "measured_by": body.get("measured_by")}, target["volume"])
for cylinder in target.get("cylinders", []):
matched = [face for face in faces if face.get("cylinder") and cylinder_axis_matches(face["cylinder"], cylinder)]
check(cylinder["role"]+"_analytic_axis_radius", bool(matched), [f["cylinder"] for f in matched], cylinder)
on_cylinder = [curve for curve in curves if len(curve)>1 and max(abs(radial(p, cylinder["origin"], cylinder["axis"])-cylinder["radius"]) for p in curve)<LINEAR_TOL]
axial = [dot(p, cylinder["axis"]) for curve in on_cylinder for p in curve]
span = [min(axial), max(axial)] if axial else None
check(cylinder["role"]+"_absolute_boundary_interval", span is not None and max(abs(a-b) for a, b in zip(span, cylinder["interval"])) <= LINEAR_TOL,
{"interval": span, "actual_feet": len(axial)}, cylinder["interval"])
type_id = definition["type_id"]
if type_id == "hex-head-bolt":
af, top = expected["across_flats"], expected["head_z"][1]
lines = []
for batch in samples:
for curve in feet(batch):
if len(curve)<2 or max(abs(p[2]-top) for p in curve)>LINEAR_TOL:
continue
a, b = curve[0], curve[-1]
length = math.hypot(b[0]-a[0], b[1]-a[1])
if length<0.1:
continue
nx, ny = -(b[1]-a[1])/length, (b[0]-a[0])/length
distance = nx*a[0]+ny*a[1]
if max(abs(nx*p[0]+ny*p[1]-distance) for p in curve)>LINEAR_TOL:
continue
if distance<0:
nx, ny, distance = -nx, -ny, -distance
angle = math.atan2(ny, nx) % (2*math.pi)
if not any(abs(wrap(angle-old[0], 2*math.pi))<1e-5 and abs(distance-old[1])<LINEAR_TOL for old in lines):
lines.append((angle, distance))
lines.sort()
gaps = [(lines[(i+1)%len(lines)][0]-lines[i][0]) % (2*math.pi) for i in range(len(lines))] if lines else []
check("six_regular_hex_flats_at_requested_across_flats", len(lines)==6 and all(abs(d-af/2)<LINEAR_TOL for _, d in lines) and all(abs(g-math.pi/3)<0.001 for g in gaps), lines, af)
# Accept explicit reviewed semantic mappings, rather than requiring reference names.
# Native parameters carry the simplified-thread semantics; rendered grooves do not.
mapping = parameter_role_map or {"thread_length": "threadLength", "thread_pitch": "threadPitch"}
actual_params = {p["name"]: p for p in inspection.get("params", [])}
length_param = actual_params.get(mapping.get("thread_length"))
pitch_param = actual_params.get(mapping.get("thread_pitch"))
pitch_expression = next(expression for name, expression, unit in definition["parameters"] if name == "threadPitch")
target_pitch = float(pitch_expression.split()[0])
text = json.dumps([length_param, pitch_param], ensure_ascii=False)
check("native_simplified_thread_semantics_retained", length_param is not None and pitch_param is not None
and length_param.get("error") is None and pitch_param.get("error") is None
and abs(length_param.get("value", -1)-expected["thread_interval"][1]) <= LINEAR_TOL
and abs(pitch_param.get("value", -1)-target_pitch) <= LINEAR_TOL
and "简化" in text and ("圆柱" in text or "无真实牙型" in text or "不生成真实" in text),
{"mapping": mapping, "parameters": [length_param, pitch_param]},
{"thread_interval": expected["thread_interval"], "pitch_mm": target_pitch})
if type_id == "ribbed-bearing-housing":
rib = expected["rib_sections"]
for sx in (-1, 1):
for sy in (-1, 1):
selected = [p for p in all_points if sx*p[0]>=rib["side_x"]-LINEAR_TOL and abs(p[1]-sy*rib["thickness"]/2)<LINEAR_TOL
and abs(p[2]-(rib["base_z"]+rib["height"]*(1-(abs(p[0])-rib["side_x"])/rib["reach"])))<LINEAR_TOL]
check(f"rib_{sx}_{sy}_actual_sloping_edge", len(selected)>=3 and max(abs(p[0]) for p in selected)>=rib["side_x"]+rib["reach"]-LINEAR_TOL,
{"feet": len(selected), "x_range": [min((p[0] for p in selected), default=None), max((p[0] for p in selected), default=None)]})
if type_id == "covered-thin-wall-enclosure" and len(roles)==2 and all(roles):
gap = roles[1]["bbox"]["min"][2]-roles[0]["bbox"]["max"][2]
check("lid_case_absolute_plane_gap", abs(gap-expected["gap"])<=LINEAR_TOL, gap, expected["gap"])
values = {n: float(e.split()[0]) for n, e, u in definition["parameters"] if u=="mm" and e.split()[0].replace('.', '', 1).replace('-', '', 1).isdigit()}
for sx in (-1, 1):
for sy in (-1, 1):
cx, cy = sx*expected["shared_fastener_xy"][0], sy*expected["shared_fastener_xy"][1]
rib_y = sy*(values["caseWidth"]/2-values["wallThickness"])
rib_top = values["bottomThickness"]+values["ribHeight"]
hits = [p for p in all_points if abs(abs(p[0]-cx)-values["ribThickness"]/2)<LINEAR_TOL and abs(p[2]-rib_top)<LINEAR_TOL
and min(cy, rib_y)-LINEAR_TOL<=p[1]<=max(cy, rib_y)+LINEAR_TOL]
check(f"boss_rib_{sx}_{sy}_reaches_y_wall", len(hits)>=3 and any(abs(p[1]-rib_y)<LINEAR_TOL for p in hits), {"actual_feet": len(hits)})
gear_details = None
if "gear" in expected:
gear = expected["gear"]
pitch, rb, ra, base_angle = gear["pitch_radius"], gear["base_radius"], gear["tip_radius"], gear["base_angle_rad"]
half, gap, width = gear["half_width"], gear["gap"], gear["width"]
rate = math.tan(math.radians(gear["beta_deg"]))/pitch
period = 2*math.pi/gear["teeth"]
flank_points = []
flank_curves = 0
for batch in samples:
for curve in feet(batch):
radii = [math.hypot(p[0], p[1]) for p in curve]
if not radii or min(radii)<rb-LINEAR_TOL or max(radii)>ra+LINEAR_TOL:
continue
if max(radii)-min(radii)<0.005 and max(p[2] for p in curve)-min(p[2] for p in curve)<0.1:
continue
flank_curves += 1
flank_points.extend(curve)
observations = []
for x, y, z in flank_points:
r = math.hypot(x, y)
if r<rb:
continue
roll = math.sqrt(max(0, (r/rb)**2-1))
tooth_half = base_angle-roll+math.atan(roll)
phase = z*rate if z<=half+LINEAR_TOL else half*rate-(z-half-gap)*rate
observations.append((r, wrap(math.atan2(y, x)-phase, period), tooth_half, z))
def errors(global_phase):
return [r*min(abs(wrap(angle-global_phase-h, period)), abs(wrap(angle-global_phase+h, period))) for r, angle, h, _ in observations]
phase = 0
if allow_global_phase and observations:
trial_points = observations[::max(1,len(observations)//200)]
candidates = [wrap(a-sign*h, period) for _, a, h, _ in trial_points for sign in (-1,1)]
def score(phi):
return sum(r*min(abs(wrap(a-phi-h, period)),abs(wrap(a-phi+h, period))) for r,a,h,_ in trial_points)
phase = min(candidates, key=score)
deviations = errors(phase)
z_groups = {"lower": sum(z<half-LINEAR_TOL for *_,z in observations),
"upper": sum(z>half+gap+LINEAR_TOL for *_,z in observations),
"lower_outer_end": sum(abs(z)<LINEAR_TOL for *_,z in observations),
"upper_outer_end": sum(abs(z-width)<LINEAR_TOL for *_,z in observations),
"lower_inner_end": sum(abs(z-half)<LINEAR_TOL for *_,z in observations),
"upper_inner_end": sum(abs(z-half-gap)<LINEAR_TOL for *_,z in observations)}
check("both_helical_hands_and_involute_final_edges", bool(deviations) and max(deviations)<=LINEAR_TOL,
{"max_error_mm": max(deviations, default=None), "actual_flank_feet": len(deviations), "curves": flank_curves, "global_phase_rad": phase})
check("both_arms_endplanes_and_inner_boundaries_sampled", all(count>=4 for count in z_groups.values()), z_groups)
for label, level in (("lower_outer",0),("upper_outer",width),("lower_inner",half),("upper_inner",half+gap)):
markers = {}
boundary_points = [p for p in flank_points if abs(p[2]-level)<=LINEAR_TOL]
transport = level*rate if level<=half+LINEAR_TOL else half*rate-(level-half-gap)*rate
for x,y,z in boundary_points:
r=math.hypot(x,y)
roll=math.sqrt(max(0,(r/rb)**2-1))
h=base_angle-roll+math.atan(roll)
angle=math.atan2(y,x)-transport-phase
sign=min((-1,1),key=lambda sign:abs(wrap(angle-sign*h,period)))
tooth=round((angle-sign*h)/period)%gear["teeth"]
markers.setdefault((tooth,sign),[]).append(r)
complete=sum(min(radii)<=rb+LINEAR_TOL and max(radii)>=ra-LINEAR_TOL for radii in markers.values())
check(label+"_all_final_involute_flanks_span_base_to_tip",complete==2*gear["teeth"],complete,2*gear["teeth"])
for label,lo,hi in (("lower",0,half),("upper",half+gap,width)):
interior=[z for *_,z in observations if lo+0.1<z<hi-0.1]
check(label+"_screw_motion_has_actual_interior_samples",len(interior)>=gear["teeth"]*4,len(interior))
if gap>0:
faces = [f for entry in native if entry["command"]=="model.faces" for f in entry["value"].get("faces", [])]
core = {"radius": gear["root_radius"], "origin": [0,0,0], "axis": [0,0,1], "interval": [half,half+gap]}
check("groove_has_analytic_root_core_cylinder", any(f.get("cylinder") and cylinder_axis_matches(f["cylinder"],core) for f in faces))
core_curves = [curve for batch in samples for curve in feet(batch) if curve and max(abs(math.hypot(p[0],p[1])-gear["root_radius"]) for p in curve)<LINEAR_TOL]
middle_points = [p for curve in core_curves for p in curve if half-LINEAR_TOL<=p[2]<=half+gap+LINEAR_TOL]
core_span = [min(p[2] for p in middle_points),max(p[2] for p in middle_points)] if middle_points else None
check("groove_root_boundary_absolute_interval", core_span is not None and max(abs(a-b) for a,b in zip(core_span,[half,half+gap]))<=LINEAR_TOL, core_span, [half,half+gap])
gear_details = {"finite_evaluation_only": True, "z_coverage": z_groups,
"not_verified": ["continuous full-surface bound", "conjugate contact", "manufacturing apex or groove root", "load capacity"]}
identity_source = directory/"design.sc" if (directory/"design.sc").exists() else directory/"document.json"
return {"type_id": type_id, "directory": str(directory.resolve()), "identity_source": identity_source.name,
"native_or_export_sha256": hashlib.sha256(identity_source.read_bytes()).hexdigest(),
"checks": checks, "passed": all(c["passed"] for c in checks), "passed_count": sum(c["passed"] for c in checks), "total": len(checks),
"body_role_mapping": [b["name"] if b else None for b in roles], "linear_tolerance_mm": LINEAR_TOL, "relative_volume_tolerance": VOLUME_REL_TOL,
"actual_edge_feet": len(all_points), "gear_sampling": gear_details,
"measurement_semantics": "smlib measures use corresponding surface integration/tight bounds. Face descriptors identify analytic axes/radii. Only combs[].teeth[][0] are actual finite curve evaluations; display mid/length are never precise curve measurements.",
"limitations": ["Finite boundary checks do not prove every interior surface or material point.", "Parameters and final geometry are not an edit-propagation test.", "No statistical benefit or manufacturing certification follows from a single case."]}
def cylinder(radius, origin, axis, interval, role):
return {"radius": radius, "origin": origin, "axis": axis, "interval": interval, "role": role}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("directory", type=Path)
parser.add_argument("definition", type=Path)
parser.add_argument("--output", type=Path, required=True)
parser.add_argument("--allow-global-phase", action="store_true")
parser.add_argument("--parameter-role-map", type=Path, help="Explicit reviewed native parameter names for semantic roles")
args = parser.parse_args()
result = audit(args.directory, read(args.definition), args.allow_global_phase,
read(args.parameter_role_map) if args.parameter_role_map else None)
with args.output.open("x") as stream:
json.dump(result, stream, ensure_ascii=False, indent=2)
stream.write("\n")
print(json.dumps({"type_id":result["type_id"],"passed":result["passed"],"score":f'{result["passed_count"]}/{result["total"]}',"failed":[x["name"] for x in result["checks"] if not x["passed"]]}))
if __name__ == "__main__":
main()
-154
View File
@@ -1,154 +0,0 @@
{
"version": "0.1.0",
"generated_from": "family frontmatter",
"families": [
{
"doc_id": "covered-thin-wall-enclosure",
"name_zh": "带盖薄壁壳体",
"name_en": "covered thin wall enclosure",
"aliases": [
"带盖壳体",
"薄壁带盖盒体",
"带盖薄壁盒体",
"covered-thin-wall-enclosure"
],
"classification": {
"relation": "project_extension",
"node_ids": [],
"note": "通用壳体未在 MCB 图 7 中明确列出;单独项目扩充,不改写原始分类,也不映射为齿轮箱。"
},
"feature_ids": [
"feature-thin-wall-boss",
"feature-ribs",
"feature-cover-interface",
"feature-holes"
],
"knowledge_version": "0.1.0",
"status": "retrieval_verified",
"path": "references/families/covered-thin-wall-enclosure.md"
},
{
"doc_id": "hex-head-bolt",
"name_zh": "六角头螺栓",
"name_en": "hex head bolt",
"aliases": [
"外六角螺栓",
"六角头螺钉",
"hexagonal head bolt",
"hex-head-bolt"
],
"classification": {
"relation": "narrower_than",
"node_ids": [
"mcb-125"
],
"note": "映射六角头螺钉与螺栓节点;本版仅外六角头、直杆和简化螺纹的项目轮廓。"
},
"feature_ids": [
"feature-hex-head",
"feature-simplified-thread"
],
"knowledge_version": "0.1.0",
"status": "retrieval_verified",
"path": "references/families/hex-head-bolt.md"
},
{
"doc_id": "involute-spur-gear",
"name_zh": "带轮毂和键槽的渐开线直齿圆柱齿轮",
"name_en": "involute spur gear",
"aliases": [
"渐开线直齿轮",
"直齿圆柱齿轮",
"带键槽直齿轮",
"involute-spur-gear"
],
"classification": {
"relation": "narrower_than",
"node_ids": [
"mcb-074"
],
"note": "按 Gears 下 Right spur gears 的并列语境理解;原文歧义保留,本族另行定义严格边界。"
},
"feature_ids": [
"feature-involute",
"feature-hub-keyway",
"feature-holes"
],
"knowledge_version": "0.1.0",
"status": "retrieval_verified",
"path": "references/families/involute-spur-gear.md"
},
{
"doc_id": "mounting-plate",
"name_zh": "带孔安装板",
"name_en": "mounting plate",
"aliases": [
"安装板",
"带孔板",
"矩形安装板",
"mounting-plate"
],
"classification": {
"relation": "narrower_than",
"node_ids": [
"mcb-089"
],
"note": "MCB 板件与圆板的项目细分;并非原树独立子类。"
},
"feature_ids": [
"feature-holes"
],
"knowledge_version": "0.1.0",
"status": "retrieval_verified",
"path": "references/families/mounting-plate.md"
},
{
"doc_id": "ribbed-bearing-housing",
"name_zh": "带筋轴承座座体",
"name_en": "ribbed bearing housing",
"aliases": [
"带筋轴承座",
"整体式轴承座座体",
"ribbed-bearing-housing"
],
"classification": {
"relation": "component_of",
"node_ids": [
"mcb-048"
],
"note": "座体是轴承座/带座轴承对象的部件,不把完整组件与单一座体当作同义类。"
},
"feature_ids": [
"feature-holes",
"feature-ribs",
"feature-coaxial-steps"
],
"knowledge_version": "0.1.0",
"status": "retrieval_verified",
"path": "references/families/ribbed-bearing-housing.md"
},
{
"doc_id": "stepped-shaft",
"name_zh": "台阶轴",
"name_en": "stepped shaft",
"aliases": [
"阶梯轴",
"台阶实心轴",
"stepped-shaft"
],
"classification": {
"relation": "narrower_than",
"node_ids": [
"mcb-051"
],
"note": "MCB Shafts 的连续同轴实心台阶轴细分。"
},
"feature_ids": [
"feature-coaxial-steps"
],
"knowledge_version": "0.1.0",
"status": "retrieval_verified",
"path": "references/families/stepped-shaft.md"
}
]
}

Some files were not shown because too many files have changed in this diff Show More