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

247 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`,并保留详细结果在对应报告,避免交接文件无限膨胀。