Files
2026-11-12 20:40:21 +08:00

22 KiB
Raw Permalink Blame History

CAD 零件类别补全:工作方法与验收规范

本文件面向维护者和接手项目的编程助手,不注入生成模型,不增加正式助手步骤。运行接口以项目维护入口为准;生产阅读真源为reading-catalog.json。catalog.json的类型/属性与policy.json的旧准入记录仅供离线维护和历史复现。当前进度见对话交接。

目标是提高原版CAD网页助手的生成质量或效率,积累“在现有工具中怎样构造、怎样避免已观察错误、怎样检查”。不能把文档数量、提示词篇幅或文件可读当成最终生成效果。

当前原则(2026-11-12用户纠正后):原助手从短目录自主选文档,目录内文件存在就读取。后端不按分类、参数、状态、预登记哈希、构建或关键词拒读,不把知识库当工具能力白名单。原有齿轮规程已恢复;不能仅因尚未证明稳定收益批量撤下。普通基础样板继续原通用Skill;收录是维护者的编辑选择,正文中的条件和近似由助手结合需求理解。见恢复更正。

已确定的产品约束

  • 知识源只维护在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/ 图文报告、错误更正和证据 不覆盖原失败

网页宿主、引擎及外部测试脚本的实际仓库路径见交接文档。若任务需要修改引擎或宿主,应先读取相应仓库的 AGENTS.md 和适用技能,不沿用 community 的规则冒充其他仓库的规则。

开始一个类别前,先写这份小任务单

任务单存入对应计划或报告,而不是追加到模型上下文。以下是字段模板,不是已经完成的事实:

type_id: <稳定类型 ID>
object_scope: <当前件或机构,必需结构与选配结构>
supported_variant: <明确齿制/形态/参数范围>
representation: <精确构造部分、近似部分、未覆盖部分>
observed_failure: <原始需求、实际失败、证据路径>
hypothesis: <这次文字或路由改动具体解决什么>
engine_build: <实际网页构建 ID>
reference_cases: <标准实例与至少一组参数变化>
formal_cases: <完整需求、常用表达、边界/范围外与编辑需求>
acceptance: <最终结构、数学关系、接口和参数编辑的检查>
excluded_claims: <本轮不能证明的制造/接触/统计结论>

先界定对象再归类。以下三种情况分开:

  • 同一类型的选配变化:例如外直齿轮有孔/无孔、带/不带轮毂,通常不新建类别。
  • 不同几何构造方法:例如直齿与斜齿、外齿与内齿,需要明确类型和适用域。
  • 多零件机构:机构规程只描述部件关系、坐标与接口;部件造型知识仍按需读取,不把所有部件长文预装到机构正文里。

短规程的正文模板

新类别可按下面的顺序写;根据实际需要删减标题,不机械补空章。正文无需复制维护流程、分类来源、测试历史或默认完整样例。

# <类型>:<构造方法与版本>

<适用对象、明确近似和不支持的变体,用一小段写清楚。>

## 参数与坐标
<必要输入、单位、轴线、基准;区分当前件与参考件、半径与直径。>
<必要派生公式及其定义域;不虚构尺寸或标准规格。>

## 当前工具构造
<关键工具 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:

mvn -q -pl vibemake-api -am \
  -Dtest=CadAiKnowledgeTest,CadAiSampleKnowledgeTest,CadAiKnowledgeUtilityTest,CadAiProtocolTest,ArkCadAiClientTest,CadAiTest \
  -Dsurefire.failIfNoSpecifiedTests=false test

若改动了离线分类、族文档或离线规则,在 community/knowledge/cad-parts 执行:

python3 -m cad_knowledge check
python3 -m cad_knowledge evaluate
python3 -m unittest discover -s tests -v

这些 Python 命令检验的是保留的离线资料,不能代替 Java 正式路由或网页生成。源码测试通过后,先确认没有在途试验,才能打包:

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数分开记录。

当期证据入口以对话交接为准;已有扩展阶段报告、v2 正式题目与截图及v3 独立补测。本文不另维护一份逐题成绩表。

2026-11-12用户授权沿用本工作流补齐其余五个旧样板,并确认同时覆盖无槽连续人字齿与带中央退刀槽双斜齿;两者独立登记,不属于未经确认的范围扩张。任务及证据见七类补全报告,仍须逐层报告参考、取文、正式模型、改参与收益,不因新增文件而自动准入。

新对话如何接手

先读本文件和 HANDOFF.md,再按问题读取相关类别正文、源码和证据;不要一次读取全部历史。先核对真实进程、队列、终态文件和冻结哈希,后决定继续哪个环节。不要从“上个对话说正在运行”推断进程现在仍活着,也不要从状态 JSON 单独推断模型已停止。

接手后首先复述三件事:当前目标、已证实的结果、下一步要补的证据。未完成试验先收尾,不重复发送;确定需要改动才创建新的版本或 cohort。每次结束会话前更新 HANDOFF.md,并保留详细结果在对应报告,避免交接文件无限膨胀。