新版参考锚点与来源基点操作请从 完整使用手册 开始。最短路径：从中央“快捷模型 / 长方体 / 打开文件”开始，或点击视口上方“参考锚点 → 编辑”精确设置新实体插入位置和方向；选目标实体后使用加工工具；保存 .webcad 保留历史和锚点。视口只显示一个可隐藏的小号呼吸球锚点，原始世界坐标保持固定。AI 使用同一页面的 window.webcad.api.connect() 读取实时能力，详见 页面 API。静态 IIS 站点不需要新增后台服务；旧世界坐标和旧工程语义仍保留。
WebCAD 是浏览器中的三维建模工作台，面向小型五金、板件、框扣和参数化实体设计。几何由浏览器 Worker 中的 OpenCascade/Replicad 计算。正常使用发布后的静态页面：HTTPS 或本机 localhost 静态托管即可，不需要 WebCAD 应用服务。
项目目的、AI 使用方式、文件边界、快捷模型要求、80% 覆盖验收口径与开发规范统一见 PROJECT.md。
AI 优先入口是 window.webcad.api.connect({queries:[能力关键词]})，一次取得精简实时状态与相关工具；随后 getTools({ids}) 批量读取完整契约。卡片和文档支持哈希复用，搜索共用界面名称与中英文相关度索引。可下载 automation/index.json 与 automation/tool-library.mjs 构建宿主离线库，完整快照不应反复送入模型上下文。机制与缓存边界见 工具发现。兼容入口是 window.webcad.api.info()。获授权且具备页面脚本执行能力的客户端可读取当前工程，随后用 searchTools、getTool、readDocs 查询当前工具契约；建模、测量、视图与文件方法操作同一个页面工程。接口目录与调用边界见 页面 API。页面暴露 JS 函数不等于现有 ChatGPT 侧边栏已具备调用权限；这一点需在实际侧边栏中单独验证。
AI 先读发布页的 llms.txt / automation/quickstart.md，再通过宿主实际支持的页面脚本通道调用 await window.webcad.api.run(request)，一批完成建模、测量和导出。AI 通过宿主已授权的页面脚本通道后台调用公开 API；JSON 面板仅供用户明确要求时手工调试，不能作为 AI 自动回退入口。无脚本通道时报告实际限制。CLI/MCP 保留为旧开发工具，不是默认产品入口；不能把 CLI 测试称为侧栏接入验收。
按需文档从 automation/manifest.json 找到单个 tools/<id>.json 与 docs/<id>.md；完整知识库为 automation/knowledge.md / index.json，AI 面板可直接下载。新增工具必须同时提供 AI 接口与文档，构建检查工具栏动作的对应关系。外观、显隐、改名、拆散、预览及视图设置也有公开接口，详见 readDocs({docId:'api.ui-coverage'})。
M0/M1 已建立完整工程上下文、revision、选择令牌与命令事务。严格契约范围以当前 getTool() 的 strictContract/contractStatus 和 src/operation-registry.js 为准；未迁移工具仍是 advisory，工具存在不代表任意目标均可加工。旧 MCP 文档和 M2A 报告保留为开发历史，不是正常运行入口或新页面 API 的验收证明。
显式手工/API/表达式尺寸按原值建模，鼠标交互步长与内核容差分别管理。工具卡公开 numericInputPolicy 和已标注参数的 unit/quantityKind/quantizationPolicy；执行回执 numericInput 可核对请求和实际参数。保存来源的轮廓加料支持共享面融合，仍拒绝分离或仅边/点接触。改参按实际引用依赖检查，人工与 API 共用保护；不安全面/边引用返回具体 affectedFeatureIds。
页面接口已接出命名参数与尺寸绑定：getState() 返回参数定义及计算值，execute 的 document.parameters 动作可一次更新参数并重建关联特征，形成一个撤销步骤。页面“参数表”允许用户只改数值；四孔板示例和具体限制见 页面 API。浏览器和侧边栏的现场验收仍以单独测试记录为准。
- 基本实体、草图、拉伸、旋转、扫掠、放样、布尔、阵列、孔槽、圆角、倒角、抽壳与分割。
- 镜像平面可精确偏置；线性/圆周阵列可选择独立组合或融合单实体；倒角支持等距离、双距离、距离加角度及支撑方向交换。
- 孔向导支持平底或带包含角的盲孔钻尖，区分圆柱段孔深与钻尖总深度；草图约束支持同心圆、点在线上和点在圆上。
- 可编辑解析轮廓、参数矩形/圆角矩形/长圆、精确等距偏移与边框、轮廓修复、投影、修剪/延伸/二维圆角，以及轮廓到实体的加工。
- 精确关系测量、干涉/间隙、指定位置连续材料壁厚、解析平面拔模检查；受限四侧棱柱拔模与普通/沉孔/沉头孔向导。
- 实体/面/边选择，精确 XYZ 移动，面上鼠标取孔位，组合和拆散多实体复合模型。
- 浏览器本地读取
.logo.json、受限 SVG 和粘贴的 SVG / 闭合路径，先复核尺寸与轮廓；复杂格式转换需另行部署服务。 - 矢量路径可生成面或实体；统一 LOGO 自动识别精确目标面。平面支持凹凸和拔模，曲面限等深凹刻；新工具拔模初值 0°，深度需明确填写。
- STEP/BREP 导入、STEP/STL/BREP 导出、
.webcad自包含参数历史保存、金属材质预览与中英文界面。
将构建好的 dist/ 连同所需许可证放在 HTTPS 或本机 localhost 静态托管位置，打开页面并等待建模内核就绪。部署在子路径时应按托管路径设置 Vite base，并验证 Worker、WASM 与资源 URL。file:// 双击方式不承诺兼容。此仓库的 Node/npm 用于开发、构建与测试；静态页面不应依赖旧 /mcp、/ai-bridge 或本机文件转换服务。
- 在“编辑”中使用箭头选择实体、面或边；移动工具支持相对 XYZ 位移和绝对包围盒中心位置。
- “创建 → 导入路径”可导入或粘贴闭合二维轮廓，并生成平面或实体。
- 选择实体的目标面与放置点后使用“加工 → LOGO”，核对轮廓、尺寸、深度与曲面限制，先预览再应用。
- 多个实体用“组合”统一管理而不融合；“拆散”仅适用于本来包含多个 solid 的复合模型。已经布尔融合为单个实体的模型需要用分割或切除处理。
- 点“新建”，再用“创建 → 长方体”输入尺寸；或绘制 XY 草图后拉伸，也可使用预设轮廓拉伸、旋转成型。
- 选中实体，在右侧参数面板修改尺寸并应用。点历史特征可以修改较早的步骤，后续形状会重建。
- 建圆柱作刀具体，使用“编辑 → 移动 / 旋转”调整位置和比例。按 Ctrl 选板件与刀具体，点“相减”，在任务内明确指定保留主体和工具；可以保留工具原件。
- 简单圆孔直接选择实体，再点“加工 → 打孔”，输入孔直径、孔深、坐标起点及 X/Y/Z 切入方向；原 API 的 radius 半径语义保持兼容。常见沉孔和沉头孔使用“孔向导”。
- “编辑 → 直线阵列 / 环形阵列”按步进位移或指定轴心复制实体。数量包含原件，阵列存为一个复合实体；环形 360° 时均匀环绕，部分角度包含起点与终点。
- 选择“边”模式，再选边做圆角或倒角；整件全部边须明确勾选，没有范围时拒绝。抽壳需要选择待移除的面。无效半径、厚度或几何会显示错误，不自动缩小尺寸。
- 左键拖动旋转，滚轮缩放，右键拖动平移；“视图”提供标准方向、正交/透视切换、适合窗口、实体/边线/线框、网格、测量和截图。
- “保存工程”可生成
.webcad工程并保留参数、历史和导入源字节；“导出”可生成 STEP、STL 或 BREP，可选择只导出选中的实体。生成 Blob、触发下载和已核验写入是不同状态；具体保存能力以当前页面接口和浏览器授权为准。
撤销/重做按钮和 Ctrl+Z / Ctrl+Shift+Z 用于回退编辑。浏览器本地自动恢复不能替代保存工程；清除浏览器站点数据会删除本地恢复数据。
| 格式 | 用途 |
|---|---|
.webcad |
保存、重新打开可继续编辑的 WebCAD 工程 |
.step / .stp |
导入精确几何，继续布尔加工、变换和修饰；导出供常见 CAD 软件交换 |
.brep / .brp |
OpenCascade 精确几何交换 |
.stl |
导出三角网格供切片/打印；不支持作为精确实体导入编辑 |
| IGES/IGS、DWG/DXF | 当前静态版没有原本的本机转换；可先用现有 CAD 工具离线转 STEP |
STEP 是精确实体交换格式，但不包含本工程的参数历史。导入其他 CAD 软件的 STEP 无法恢复其原始草图、约束或特征树。若要保留 WebCAD 参数编辑能力，请同时保存 .webcad。
这是简单零件的本机建模工作台，不是 Creo / SolidWorks 的完整替代。尚无完整草图约束求解、装配配合系统、工程图标注出图、通用自由曲面设计、IGS 自动修补或跨多面/接缝的曲面 LOGO 包覆。自由轮廓草图在 XY 平面，预设轮廓可用指定平面。复杂或损坏的外来 STEP、特别小的特征和过大的圆角等仍可能建模失败。大型模型的速度和容量取决于浏览器内存及机器性能。STL/IGES/DWG 的编辑不在支持范围；只读查看器为保留的独立入口。后续建模能力见 路线图。
本机验收记录不随仓库提交；可按下文的开发命令复现构建与测试。
npm install
npm run dev
npm run buildnpm run dev 是开发服务；npm run build 生成可静态托管的 dist/。更新源代码后重新构建并刷新页面。测试脚本与旧本机服务只用于开发和历史回归。
原 CadViewer 保留于 cad-viewer/，字体与只读资源在 cad-data/。第三方许可见 LICENSE.md、THIRD_PARTY_NOTICES.md、LICENSES/ 和 CORRESPONDING_SOURCE.md；复制、分发时须一并保留。
顶部“示例”可打开带孔安装支架、圆角扣框和薄壁盒。示例保留完整操作历史，适合先修改尺寸熟悉软件。
浏览器操作与独立 STEP 实体验证可按下文的开发命令复现。
右侧「属性 → 外观」集中设置原色和金属材质。“工程默认渲染”支持设计原色、浅金、镍、24K 金、枪色、四种哑光效果、仿古黄铜及仿古银；选中实体可以跟随工程或单独指定材质。“设计原色”支持颜色选择和重置，改色会将选中实体切回设计原色；切换金属材质仍保留原色数值。所有外观设置随 .webcad 工程保存并支持撤销，选择高亮保留实体颜色。金属预览使用摄影棚 HDR 和仿古参考纹理，在浏览器本机渲染。
这是显示设置，不修改几何、尺寸或 STEP/STL/BREP 导出内容。选择“设计色”可回到原来的建模配色。
当前页面接口以 页面 API 为准。每个打开页面有独立运行标识，修改须携带当前 sessionId、documentId、documentInstanceId 和 expectedRevision；调用结果须检查是否真正提交及渲染。旧连接说明仅记录历史开发路径。
客户端连接配置示例（客户端字段名可能不同）：
{"mcpServers":{"webcad":{"url":"http://127.0.0.1:667/mcp"}}}原 21 个工具与 M2A 文件流程的协议说明保留在 历史 MCP 指南，供开发回归参考；不作为页面自动化能力的当前说明。
标题和工具图标已缩小，右上角切换中文 / English，浏览器记住语言。建模页的“快捷模型”共 17 类，并在每个名称旁显示简易线稿图标。扣环类包括圆圈、大开口 C 环、D 扣、独立圆横杆 D 扣、方扣、日字扣和四圆弧旦扣；板壳和回转件包括平垫圈、独立内外圆角平面框、双孔圆角安装板、双空心柱安装板、圆角双柱薄壁壳、直角双柱薄壁壳、双柱圆牌底座、圆筒、沉孔／沉头孔刀具和法兰轴套。支持适用模板的圆线／圆角方线和实际开口；字段分别说明内尺寸、截面 R、轮廓内 R、壁厚、柱距与横杆尺寸。模板生成真实 BRep 并保留参数历史，不包含任意图纸自动识别或复杂活动结构。
高级页新增扫掠、放样、平面分割、实体提取、选平面钻孔和推拉。扫掠支持三维折线路径与圆／矩形截面；放样支持两个平行截面。草图提供闭合折线、矩形、圆、圆角矩形、圆弧扇形／弓形；交互折线可限定水平／竖直，不是完整的参数约束求解器。
视图页提供移动／旋转手柄、剖切显示与几何点吸附。先选边／面再测量，可读取真实长度、圆半径或面积；未选拓扑时为两点测距。属性栏可给选中零件单独指定金属材质，设置随 .webcad 工程保存，STEP 不携带该渲染外观。参数窗支持预览、应用和取消；预览不会写入工程。
现有操作目录包含 slot 圆头槽；长度、宽度和深度使用 mm，刀具起点为全局中心坐标。具体参数与能力边界通过当前页面 getTool 读取；没有实际去除目标实体材料的加工不应提交部分结果。
历史 MCP 指南记录原协议与文件工作流。当前静态版没有原本的本机 IGES 转换器及服务端矢量转换器；这些格式不能因旧测试通过而视为页面原生能力。
原始 IGS 样本用于提炼双空心柱安装板、法兰轴套、圆角双柱薄壁壳、双柱圆牌底座、大开口 C 环等参数模板，以及圆头槽加工操作。2026-09-23 新增的 50 份去重样本、四视图记录和按样本定义的覆盖矩阵见 IGS50 复核报告；这些功能不表示对源 IGS 曲面集合的修复、闭合或完整原件复刻。
原 IGS 保持只读；散面读取不等于实体修复或完整产品复刻。模板示范尺寸不冒充原货号的公称尺寸；新增模板是可调的通用参数模型，不含螺纹，也不自动推断源图尺寸。
工具按「编辑 / 创建 / 加工 / 视图」分组：快速模型与轮廓成型在创建，布尔、孔槽、面边加工与拆分在加工，变换/手柄/阵列在编辑。工具栏下方显示当前选择要求，单实体工具在多选时禁用；面上打孔/拉伸需要一个面，抽壳需要开口面。曲面能否执行面加工仍由几何内核校验。属性栏按「外观 → 实测尺寸 → 可编辑参数」排列，右栏加宽，窄窗工具栏可横向滚动。网格、吸附、显示模式和投影开关跟随实际视口状态。
“加工 → LOGO”只有一个入口：导入经核对的 .logo.json 或受限 SVG，在一个精确目标面上放置。平面可凹刻、凸字、拔模；圆柱等受支持曲面可做单面等深凹刻。孔洞、镜像、旋转、缩放、偏移与历史参数保留；不支持跨面包覆或坏图自动修形。详见 LOGO 工作流。
.logo.json、受限单色闭合 SVG 和粘贴的 SVG / 路径文本在浏览器本地解析；无需 /api/logo-import。DXF、DWG、PDF、AI 与位图转换需另行部署并验证服务，当前静态版不提供。具体输入边界见 LOGO 工作流。