Skip to content

按用途分类补齐 Core API 文档,并按每日小批次推进 #232

Description

@vilicvane

@code3d/core 的每个面向使用者的 API 补齐可独立查阅的文档,先确定用途分类,再分批逐步实现。采用每天少量推进的节奏,兼顾内容质量、审阅成本和搜索可发现性。

全部清单已实现并通过验收,原有 16 个 section、16 笔独立提交完整保留;本次合并时同步当前主分支的独立 frame、group options、metadata / withMetadata 及 tooling 契约,现有 95 个细页。兼容整合提交为 b4fe7de02f59acbd2614a592a4b8ce0586243b22,最终本地主分支合并提交为 36ba351b363c85f8de3c12e69733a86f5d6bb805core: merge complete api reference documentation,含 Closes #232)。根入口 52 个值 / 83 个类型、tooling 83 个值 / 73 个类型,以及公开成员、Replicad / Three.js 互操作入口均已覆盖。95 页独立来源基准有效,297 条来源均能解析到真实提交。

当前状态为 CLOSED:已验收、合并并推送到远端 main。2026-09-23 正常推送后,GitHub 远端 main 与 commit API 均确认 36ba351b363c85f8de3c12e69733a86f5d6bb805Closes #232 已自动关闭 issue,工作状态标签已清理。主分支和任务工作区均 clean,保留 code3d-issue-232-core-api-docs-p61-0922 和本地 5185/5186 服务。本次未推送版本 tag 或发包。

此次远端 网站构建 已成功:95 页源码核对、326 个 HTML/Markdown 页面的链接/锚点/资源检查和 code3d-www artifact 上传通过。部署 job 按既有条件跳过,本次没有线上发布。CI 的 4 个浏览器示例分片、全 workspace 类型/测试、npm 包安装与示例验证、App 构建均通过,网站图片生成仍在运行,最终结果待更新。

验收入口:完整导出索引按用途浏览Tooling 总览App 示例。这些地址仅为本地预览,不代表线上发布或搜索引擎收录。

以下分节保留各批次交付历史;其中“下一节”“尚未完成”描述反映当时状态,最终进度以上述总览及已完成清单为准。

本地主分支集成(2026-09-23)

  • 用户明确授权合并。主分支基线为 4510ccf3db597382d48dff779f1a56e9dc98ec81,其中已包含独立坐标架、模型 metadata 和统一空间追踪的新 API;先在任务工作区完成语义兼容,再无冲突集成到 main。
  • 新增 frame 细页和 frame.ts 作者入口,使该页继续使用独立实现来源;FrameObject、参考求解和生命周期仍在 runtime。group.ts 同步 {name, frame}、显式坐标选择和选项检查器,frame 不作为几何成员。
  • model-data 原 URL 改为 readonly metadata / withMetadata 的唯一现行说明,覆盖 symbol 键、浅层值快照、主输入继承与进程内边界。删除旧 get/setModelData 说明;补齐 Frame、GroupOptions、ModelMetadata、isFrame、modelOperationObject、Frame annotation owner 及追踪联合分支。
  • 同步导航、类型/导出索引、受影响 App 示例与源码 context;审核共享源码影响后显式刷新 61 页来源记录,保留逐页核对版本语义。现为 95 页、297 条来源。
  • 验证通过:Core 类型检查与 547 项行为测试;11 项空间/参考检查、35 项参数和导出、3 项目录/示例、3 项真实 gallery 编译检查;8 页 TypeScript 示例类型检查与执行、完整覆盖审计。初次 App 检查引用旧 gears 构建产物导致导出失配,统一重建打包后对应检查全部通过。
  • App/Web 构建和 Web 类型检查通过;326 个 HTML/Markdown 页面的链接、锚点、资源与搜索入口有效。Host Chrome 检查 7 个受影响页面的桌面/手机布局、来源哈希、导航、搜索及 placement 13 个标签;frame-only 测量的渲染与导出回归通过。既有宿主 Chrome 和开发服务不属于测试驱动的资源上限。
  • main 合并结果与任务工作区已验收 tree 完全相同;主区再次检查 95 页源码基准和 diff 通过。最终合并 36ba351b363c85f8de3c12e69733a86f5d6bb805 的双亲为 4510ccfb4fe7de;本地集成已完成;现已按用户授权推送,并核实 issue 自动关闭及标签清理。

点、曲线与轮廓(2026-09-22,已本地提交)

用户已验收本节,并授权继续补齐所有分类、每节单独提交。此节提交为 69d231fb775befdb3cd098291b4097ccd52d8966core: document points curves and profilesrefs #232);继续沿用原工作区 code3d-issue-232-core-api-docs-p61-0922、分支及 owner w1:p61

  • 完成 point、line、arc、bezier、spline、circle、ellipse、rectangle、regularPolygon 九页。每页包含真实示例、配图、签名/重载、坐标/原点、参考、测量、约束与默认值,以及独立源码核对记录。
  • 九个构造器分别归同名模块,curve-model.ts 共享曲线装配与点列校验,planar-face-model.ts 共享平面法向归一和资源释放。通用模型、面创建和拓扑参考继续由 runtime 拥有;有限坐标校验归 validation,坐标表示转换归 spatial。同步 root/authoringApi 导出,无旧模块转发入口,不新增包,不改变公开签名与模型值语义。
  • 复用 Basic shapes 源码,新增九个 source contexts 和九张真实模型截图;保留 box 为示例默认标签。分类入口、README、sidebar、相关 API 链接和内部架构说明同步,regularPolygon 稳定地址为 /docs/packages/core/api/regular-polygon/
  • 已实测并说明:点与模型原点的区别、line 两个重载、arc 的中间输入点不一定等于 midpoint、Bézier 控制点与曲线包围盒、spline 近似拟合/可能超出采样点范围、参数中点与半弧长的区别、平面 +Y 法向、椭圆半轴顺序、奇数多边形包围盒中心与 circumcenter 的区别。旧总览的“interpolating spline”已纠正。
  • 共享有限坐标校验搬迁使 validation 文件发生变化;确认原正数校验行为未变后,显式复核并更新旧八页基准。共 17 页源码检查通过;旧图元实现来源记录实际提交 1baef99,新增/修改且未提交的源码不伪造提交哈希。
  • 验证通过:Core 构建、公开类型和 537 项测试;App 参数工具 17 项及示例目录/Basic shapes 2 项测试;源码核对和 Markdown 发布 13 项测试。九页实际 TypeScript 示例编译、执行通过,并验证尺寸、面积、曲线长度、参考点、原点变换、平面法向与挤出、默认值及非法输入。
  • App/Web 构建通过,Web 类型检查 0 错误/警告/提示;163 个 HTML/Markdown 页面的链接、锚点与资源检查通过;格式、diff 和 17 页哈希检查通过。
  • Host Chrome 验收通过:九页桌面/手机布局、图片、唯一 sidebar、canonical、HTML/Markdown 核对版本及哈希一致,分类链接与 spline 搜索正常;Basic shapes 的 17 个标签逐个切换及图片解码通过、默认仍为 box,无 pageerror。未选中标签按组件既定行为懒加载,浏览器检查已按真实切换方式验证。九张模型图均逐张查看。
  • 本地验收:分类入口splineregularPolygon。5185/5186 服务继续保留。
  • 交付复核通过:47 个文件均属于此节;Prettier、diff 和 17 页源码基准检查通过,提交后 42 条来源全部可按内容匹配解析到真实提交;工作区 clean。已有 Core 537 项、App 19 项、文档 13 项及示例、构建和浏览器验收证据复核通过。其他分类未完成,下一节为成形操作。现有 CI 的哈希入口已在 1baef99 中,但因尚未推送,远端暂未生效。

成形操作(2026-09-22,已本地提交)

按最新授权每 section 一次本地提交,本节为 2e2cf49d64dba98b613224b6ae39aa632d6d2eb0core: document shape construction operationsrefs #232);未合并、推送或发布,后续继续完成全部清单。

  • 完成 extrude、revolve、sweep、loft、wrap、thicken 六页,等价方法、重载、配置类型、坐标/原点、结果与失败条件跟随对应页;累计 23 页独立源码核对记录。
  • 六 API 作者入口及检查器从 runtime 拆到对应模块;extrude、loft、wrap、thicken 原几何算法迁至 *-geometry.ts,四份算法内容逐字不变。模型方法、求解、身份和资源管理仍归 runtime;同步 root/authoringApi 与内部算法测试导入,无公开 API 或行为变化。
  • 新增共享 operations/shape-construction.ts 真实 App 示例及六个检查视图/配图,默认封面为 shape-construction.png。网站分类 sidebar、README、旧章节锚点及细页链接、内部架构说明均已同步,原技术正文归入各 API 页。
  • 特别说明 signed extrusion、revolve 的总轴向 advance 与 pitch 的区别、sweep 起始对齐、loft 顺序/孔/ruled 分支、wrap 共面布局与曲面边界,以及 thicken 曲率/方向/数值验证限制。
  • 验证通过:Core 构建、公开类型与 537 项测试;App 参数/检查器 51 项及示例 2 项;六页实际 TypeScript 示例编译执行;源码记录 4 项测试;公共包打包;App/Web 构建与 Web 类型 0 错误/警告/提示;176 个 HTML/Markdown 页面的链接、锚点、资源与搜索检查。
  • Host Chrome 六页桌面/移动布局、图片、唯一 sidebar、canonical、HTML/Markdown 哈希一致,分类链接、搜索及六标签画廊均通过;六张模型图逐张查看。构建中发现并修复 description YAML 引号与默认图片路径,最终构建和浏览器验收通过。
  • 交付复核:35 个文件均属于本节;Prettier、diff、23 页源码基准通过。提交后 65 条来源全部解析到真实匹配提交,工作区 clean。测试/渲染驱动受 3 GiB RAM、零 swap 和截止时间限制;已有宿主 Chrome 与开发服务不在驱动 cgroup 内。
  • 本地入口:extrudewrap完整示例。保留 5185/5186 服务;下一节为布尔运算与实体修饰。

布尔运算与实体修饰(2026-09-22,已本地提交)

本节提交为 bb707e248ef98fe97db48020a396fd20bf3265eccore: document booleans and solid modificationsrefs #232)。仅本地提交,其他分类继续按每 section 一笔推进。

  • 完成 union、cut、intersect、fillet、chamfer、shell 六个独立参考页;等价 cut 方法、修饰方法参数、拓扑选择、坐标/材质/接口继承和失败条件均已说明。累计 29 页有独立源码基准。
  • 三个布尔作者入口及检查器分别归同名文件,boolean-model.ts 共享操作数校验;cut 实例方法直接调用 runtime 原有组合机制。finishing 方法和原生拓扑算法继续共享,不改变公开签名、模型值语义或成形算法。
  • 新增共享真实 operations/solid-operations.ts 示例、六个检查视图和六张模型配图,默认封面 solid-operations.png。更新分类导航、README、总览、shell 指南及内部架构说明;确认 runtime 的拆分影响后显式复核成形六页基准。
  • 核对并说明 disconnected union、intersection 无公共体积、cut 非空工具与全局求解、空边选择被拒绝而 shell 空开口列表表示封闭腔体、拓扑 ID 路径、shell 内外偏移及单连通实体限制。
  • 验证通过:Core 构建、公开类型与 537 项测试;App 检查/参数 51 项及目录/本节示例 2 项;六页实际 TypeScript 示例编译执行;公共包打包;App/Web 构建;Web 类型 0 错误/警告/提示;189 个 HTML/Markdown 页面链接、锚点、资源和搜索检查。
  • Host Chrome 六页桌面/移动布局、图片、唯一 sidebar、canonical、HTML/Markdown 哈希、分类/搜索与六标签画廊通过,六张配图逐张查看。一次范围过宽的全量 App 示例运行已停止,以上结论仅包含完成的本节 53 项,不声称全量示例通过。
  • 交付复核:33 个文件均在范围内,Prettier、diff、29 页基准通过;提交后 91 条来源匹配真实提交,工作区 clean。未合并、推送或线上发布,5185/5186 服务保留。
  • 本地入口:unionshell完整示例。下一节为原点与局部变换。

原点与局部变换(2026-09-22,已本地提交)

本节提交为 ba87040b2557ca591196b75843c879b6a318d01ccore: document origins and local transformsrefs #232)。仅本地提交,其他分类继续按每 section 一笔推进。

  • 完成 originPoint、originVertex、originOffset、originCenter、model.rotate、scaled 六页。说明各模型 capability、单值/数组重载、点参考与顶点 ID、原点重表达、完整布局居中、固定 XYZ 顺序、局部零点缩放及测量比例。
  • originCenter 作者函数、单值/数组重载和检查器归独立 origin-center.ts,使用既有 isModelObject 校验保持行为;模型变换、组装配、拓扑、约束与参考身份继续归 runtime。公开 API 不变。
  • 共享真实 operations/local-transforms.ts 示例、六个检查视图与六张配图;README、sidebar、旧总览锚点、原点指南和内部架构同步。runtime 纯拆分后显式复核成形与布尔 12 页基准,累计 35 页。
  • 验证通过:Core 构建、公开类型和 537 项;App 本节示例/目录 2 项与检查器 51 项;六页实际 TypeScript 示例编译执行,包括坐标、整体布局、缩放尺寸/体积与旋转不变量断言;公共包打包,App/Web 构建与 Web 类型 0 错误/警告/提示;202 个 HTML/Markdown 页面链接、锚点、资源和搜索检查。
  • Host Chrome 六页桌面/移动、图片、唯一 sidebar、canonical、HTML/Markdown 基线、分类链接、搜索与六标签画廊通过。六图逐张查看。渲染焦点与 rotated 变量的歧义通过更具体 context 修复,目录定位和最终渲染均通过。
  • 交付复核:36 个文件均属于本节,Prettier、diff、35 页源码基准通过;提交后 110 条来源匹配真实提交,工作区 clean。未合并、推送或线上发布,5185/5186 服务保留。
  • 本地入口:originCentermodel.rotate完整示例。下一节为组合与相对摆放。

组合与相对摆放(2026-09-22,已本地提交)

本节提交为 757c8003e4ef2c3e4b4e85561e186a82a1dd1c39core: document groups and relative placementrefs #232)。仅本地提交,其他分类继续按每 section 一笔推进。

  • 完成 group、expose、relate、on、align、offset、rotate、pivot、pivotVertex、pivotPoint、axisEdge、axisLine、coupleRotation 13 页,完整说明签名、重载、返回/配置、旋转链偏移成员、求解阶段、self/外部引用身份、角度全转数与支持限制。
  • 11 个自由作者入口分别拆到同名模块;group 与 inspectGroupMembers 同归 group.ts,originCenter 更新对应依赖和核对来源。runtime 提供内部参考解析和旋转表达式机制,关系上下文经既有 currentRelationSelf 获取,公开调用和求解行为保持一致。
  • 共享真实 constraints/placement-api.ts 示例、13 个检查视图与 13 张模型图;分类导航、README、relations 指南、总览旧锚点/细页链接及内部架构同步。逐项确认 runtime 纯拆分后显式复核旧 18 页,累计 48 页源码基准。
  • 验证通过:Core 构建、公开类型与 537 项;App 本节示例/目录 2 项及检查器 51 项;13 页实际 TypeScript 示例编译执行;公共包打包,App/Web 构建,Web 类型 0 错误/警告/提示;229 个 HTML/Markdown 页面链接、锚点、资源和搜索检查。
  • Host Chrome 13 页桌面/手机布局、图片、唯一 sidebar、canonical、HTML/Markdown 哈希、分类与搜索、13 标签画廊全通过;13 张图片逐张查看。source focus 名称子串冲突通过示例变量 bed/datum 消除,目录与最终渲染通过。
  • 交付复核:67 文件均属于此节,Prettier、diff、48 页基准通过;提交后 156 条来源匹配真实提交,工作区 clean。未合并、推送或线上发布,5185/5186 服务保留。
  • 本地入口:relatecoupleRotation完整示例。下一节为拓扑与参考元素。

拓扑与参考元素(2026-09-22,已本地提交)

本节提交为 e158009a3475b9419808e4abf3b12f4dce687866core: document topology and referencesrefs #232)。仅本地提交,其他分类继续按每 section 一笔推进。

  • 完成 vertex/vertices、edge/edges、surface/surfaces、reference elements、directional bounds、flip/reverse 六页,覆盖各模型/参考的选择能力、ID 路径/顺序/重复/空数组、子拓扑归属、frame/origin/center/axis/plane/曲线点与朝向语义。
  • 共享真实 operations/topology-api.ts 示例、四个检查视图及四张模型图;README、分类导航、拓扑指南、总览旧锚点及细页入口同步。本节没有 Core 运行时代码变化。
  • 交付复核修正 reference-elements 文案:regularPolygon 的 center 是初始局部包围盒中心,不能误称外接圆中心;构造器的 axis 位置单独定义,regularPrism 的中央轴不一定经过偏移的包围盒中心。以 runtime 公开类型、初始化与已有图元页交叉核对。
  • 页面增长触发 Cloudflare 100 条响应头规则限制,必要支持修复将包 Markdown 的相同 canonical 映射归并为 /docs/packages/*.md:splat/。非标准映射和其它独立规则保留,Markdown-only agent 文档不添加 HTML canonical;Web README 同步。150 页、站点 base path、特殊 index 映射及非标准映射共四项验证通过。
  • 本节 App 示例/目录 2 项、六页实际 TypeScript 示例编译执行、canonical 4 项、App/Web 构建及 Web 类型 0 错误/警告/提示通过;242 个 HTML/Markdown 页的链接/锚点/资源/搜索检查通过。纯文案修正后再次 Web 构建和全部 242 页检查通过;无 Core 实现变更,沿用先前 Core 537 项证据。
  • Host Chrome 六页桌面/手机布局、图片、唯一 sidebar、canonical、HTML/Markdown 哈希、分类/搜索与四标签画廊通过,四图逐张查看。
  • 交付复核:20 文件范围、Prettier、diff、54 页源码基准通过;提交后 175 条来源匹配真实提交,工作区 clean。未合并、推送或线上发布,5185/5186 服务保留。
  • 本地入口:vertex参考元素完整示例。下一节为几何测量。

几何测量(2026-09-22,已本地提交)

本节提交为 420a6c5dac163eaa4cbff6939344fa4f8e51a75fcore: document geometry measurementsrefs #232)。仅本地提交,其他分类继续按每 section 一笔推进。

  • 完成 distance、length、area、volume、bounds、position 六页,涵盖全部签名、接收模型/参考类型、单位、变换比例、数值快照、查询时机、求解架与实例歧义;配置/返回类型 DistanceAxis、ModelBounds 跟随页面。
  • distance 作者入口和检查器原样移至 distance.ts,runtime 仅新增内部 DistanceInspectData 导出;实际有限几何测量、静态查询与求解代码不变。root/authoringApi 与内部架构说明同步,全部 runtime 相关页面复核后显式更新基准,累计 60 页。
  • 前四页复用既有真实 App 测量示例和已验证配图;bounds/position 使用可直接运行的同一坐标小例。主总览正文移入细页,旧 anchors 保留,README、sidebar 和相关入链更新。
  • 验证通过:Core 构建、公开类型和 537 项;App 四个测量示例及目录共 5 项;检查器/参数相关 63 项(以实际日志计数);六页实际 TypeScript 编译执行;公共包打包、App/Web 构建、Web 类型 0 错误/警告/提示;254 个 HTML/Markdown 页的链接、锚点、资源和搜索检查。迁移中发现的相对链接已修复,最终构建通过。
  • Host Chrome 六页桌面/手机布局、图片、唯一 sidebar、canonical、HTML/Markdown 基线、分类/搜索全部通过。
  • 交付复核:52 文件范围、Prettier、diff、60 页基准通过;提交后 191 条来源匹配真实提交,工作区 clean。未合并、推送或线上发布,5185/5186 服务保留。
  • 本地入口:distanceboundsposition。下一节为草图实体、约束、派生与区域提取,并覆盖 sketch plane/relate。

草图(2026-09-22,已本地提交)

按每 section 一次本地提交的授权,本节为 9f66bcbf99cc0b76a09d8965071140b6ce953da7core: document sketch entities constraints and regionsrefs #232)。

  • 完成 sketch、sketch-entities、sketch-constraints、sketch-derive、sketch-faces、sketch-relate 六页,覆盖全部 Sketch / SketchEntry / SketchConstraint 分支与参数、point / derive、face / faces、plane / relate;说明局部坐标、只读上游引用、约束方向和剩余自由度、封闭区域及洞/岛、不可变空间摆放和编辑上下文。
  • 本节没有 Core 源码变更。每页有独立 sourceReview;分类入口、README、sidebar、agent 草图指南和相关链接同步。旧 API 总览保留原锚点,将交互手势说明集中到草图工作流指南。
  • 新增共享 App 示例 sketches/sketch-api.ts、六个 source contexts 和六张真实截图;分别展示基本圆盘、弧线与孔/别名、约束矩形、派生圆环、多个区域、贴面开孔,并用数值断言验证几何结果。为清楚呈现贴面孔,将该示例相机方向设为 [1, 2, 1] 后重渲染并逐张查看。
  • 验证通过:示例及目录 2 项测试、六页真实 TypeScript 示例编译执行、App/Web 构建、Web 类型检查 0 错误/警告/提示;267 个 HTML/Markdown 页面的链接、锚点和资源检查通过;Host Chrome 六页桌面/手机、源码哈希、canonical、搜索及六个画廊标签验收通过。
  • 交付复核通过:20 个文件属于本节,公开类型与文档签名相符,Prettier 和 diff 检查通过;66 页来源基准一致,210 条来源均解析到真实提交和链接;提交后工作区 clean。5185/5186 服务继续保留。尚未合并、推送或发布,下一节为文字与字体(text、font、googleFont),issue 保持 OPEN / status:in-progress。

文字与字体(2026-09-22,已本地提交)

本节提交为 3d2db0c82c1ae0e6723ecd77fa6f571b326d1681core: document text and font resourcesrefs #232)。

  • 完成 text、font、googleFont 三页,覆盖全部参数和 Font 字段、共享基线与多面返回、字形间距/字偶距、异步资源与同步几何、Google Unicode 子集及缓存。复用已验证的真实 text 示例和配图;同步 README、sidebar、旧锚点入口、文字工作流与内部架构。
  • 按此前讨论的独立 API 来源方案,text 作者入口移入同名模块,既有字形算法逐字移至 text-geometry;googleFont 作者入口移入同名模块,CSS/URL 解析逐字移至 google-font-sources。font 共享解析/解码/资源构造内部 helpers,runtime 移除对 text/font 的依赖;root、authoring、tooling 和测试导入同步。公开调用方式及算法未变,交付复核已确认两份算法文件和两个作者函数原样搬迁。
  • 核对实际 App 缓存实现后,将旧固定 1 GiB / 10% 磁盘描述改为 Settings → Cache 的配置预算,并将相关 App 资源实现列入页面来源。其他 runtime 依赖页面经复核刷新基准。
  • 验证通过:Core 构建/公开类型及 537 项测试,目录及真实 text 示例 2 项,三页 TypeScript 示例编译执行(Google Play 实际网络加载、本地 DejaVu fixture);打包、App/Web 构建、Web 类型检查 0 错误/警告/提示,273 个 HTML/Markdown 页面链接及资源检查;Host Chrome 三页桌面/手机、哈希、canonical、搜索和图片验收。
  • App 联合检查中 63 项参数/检查器和 1 项模型资源测试通过;resource-cache 文件因旧 googleFont 私有导入失败,修复导入后单独重跑其 13 项全部通过。该次联合命令不记为整体成功。
  • 交付复核:67 个文件属于本节,格式/diff 与 69 页来源基准检查通过,225 条来源均解析到真实提交链接;工作区 clean,5185/5186 服务保留。未合并、推送或发布;下一节为材质与外观,issue 保持 OPEN / status:in-progress。

材质与外观(2026-09-22,已本地提交)

本节提交为 be0d9a67434b9294bd3288b801fb48b93c42df9dcore: document materials and appearancerefs #232)。

  • 完成 material 和 Three.js integration 两页,覆盖颜色/透明度、完整材质替换、组继承、不可变像素快照、原生材质导入、纹理与 UV、序列化支持范围及导出表现。复用实际 App materials 示例,新增三个画廊上下文和三张真实渲染图;同步 README、sidebar、分类入口并保留旧锚点。无 Core 源码变更。
  • 交付时依据实际解析器定向核验 transparent、HSL/HSLA 和 RGB/RGBA。RGB 分支支持斜杠/百分比 alpha 并钳制到 0–1;HSL 走旧解析器,现代 HSL 透明度可能被忽略。文档已明确旧式逗号 HSL 和 0–1 数字 HSLA alpha 的写法,并说明 transparent 为全透明黑色,避免误称全部颜色都支持现代 CSS 语法。Three 子路径说明与实际导出一致,UV 文档补充 runtime 来源。
  • 验证通过:示例目录和 materials 实例 2 项测试,两页 TypeScript 示例类型检查与实际执行,三个图像渲染并逐张查看,App/Web 构建、Web 类型检查 0 错误/警告/提示。文案修正后重新构建 Web,278 个 HTML/Markdown 页面的链接、锚点和资源检查通过;Host Chrome 两页桌面/手机、源码哈希、Markdown、canonical、导航、搜索和三个画廊标签复验通过。
  • 交付复核:9 个文件属于本节,Prettier、diff、71 页来源基准通过;232 条来源均解析到真实提交链接。提交后工作区 clean,服务保留;未合并、推送或发布。后续为参数、时间与缓存,其余类型总览、扩展及工具集成继续保留在清单中;issue 保持 OPEN / status:in-progress。

参数、时间与缓存(2026-09-22,已本地提交)

本节提交为 e13113755850e48f94d06f4234c480502999d847core: document inputs time and cachingrefs #232)。

  • 完成 input、timeOffset、cache 三页,涵盖完整签名和选项、输入身份/冲突/边界、播放时间、缓存重载/数据所有权/参数编码/结果 codecs/定义身份/持久化和错误。同步 README、sidebar、API 分类与 runtime 旧锚点;旧缓存正文迁入细页,将易过时的固定容量改为 host 配置说明。无源码变更。
  • 逐项核对实现:input 的 step 为控件步进,Core 不量化返回值;timeOffset 校验最终选中的值,宿主已给值时不校验未使用的默认值;cache 的自定义 encoder/decoder 只影响结果持久化,参数仍按标准数据编码生成键。定向运行验证 4.25 在 step=1 时保留、相同名称声明冲突抛错、宿主负时间覆盖无穷/NaN 默认值、独立无穷时间抛错。
  • 验证通过:三页首个 TypeScript 示例类型检查和真实执行;Web 构建、284 个 HTML/Markdown 页面的链接/锚点/资源检查,Web 类型检查 0 错误/警告/提示;Host Chrome 三页桌面/手机、源码哈希、Markdown、canonical、导航和搜索验收。
  • 交付复核:实际为 7 个文件,Prettier、diff 和 74 页来源基准通过;238 条来源全部解析到真实提交链接。工作区 clean,服务保留;未合并、推送或发布。下一节为模型、参考与能力类型总览,扩展及工具集成和最终覆盖核对仍待完成;issue 保持 OPEN / status:in-progress。

模型与类型总览(2026-09-22,已本地提交)

本节提交为 5b7b6fe43a934bf63d85a3aac1dbda0280b7da88core: document model types and capabilitiesrefs #232)。

  • 新增 model-types 一页,集中说明六种模型别名、模型 kind 与 anchor kind 映射、Vec3、所有公共能力接口/方法及继承关系;连接各 API 的操作和关联类型主说明。同步 README、API 总览、模型值指南和 sidebar,无源码变更。
  • 核对公开声明:抽象 Model 无公开 kind 判别字段;SolidModel<{}> 不要求具名 axis,但仍有几何 center;EdgeModel<{}> 不要求默认 start/midpoint/end。有限参考具备查询能力而不具备模型创建和独立摆放方法,flip/reverse 返回引用;Groups 不具备几何特有能力,泛型 Elements 和返回 kind 的保留/覆盖语义明确。
  • 验证通过:页面首个 TypeScript 示例类型检查和真实执行,Web 构建及 286 个 HTML/Markdown 页面的链接/锚点/资源检查,Web 类型检查 0 错误/警告/提示;Host Chrome 页面桌面/手机、源码哈希、Markdown、canonical、导航与搜索验收。
  • 交付复核:5 个文件,Prettier、diff、75 页来源基准通过,240 条来源解析到真实提交链接;工作区 clean,服务保留。未合并、推送或发布,下一节为扩展开发入口,之后仍需工具集成及最终覆盖核对;issue 保持 OPEN / status:in-progress。

扩展开发入口(2026-09-22,已本地提交)

本节提交为 c600453b38ab9b497e23f0a14cf0b927c401cee7core: document extension development APIsrefs #232)。

  • 完成 define-primitive、model-data、inspectors、inspect-group-members、annotations 五页,覆盖 Replicad 自定义实体/类型入口/原生资源所有权/缓存、包元数据、全部公共 Inspector 与 closure/context 字段、数组成员检查和被动标注。同步 README、sidebar、API 与自定义图元指南,将 runtime 长技术正文迁到细页并保留 Source inspection / Getter inspection / Call data 原锚点。
  • 无源码变更。核对元数据 set 为原地关联且仅 relate/material 自动保留、后续 set 不影响既有复制值的映射;inspectGroupMembers 按同序数组配对;Replicad 子路径仅将上游名称重导出为类型,运行时函数/类取自 replicad 对象。同步检查器结果限制与对应 App 来源、标注候选选择与渲染来源。
  • 交付复核补正 InspectContext 描述为被检查调用的返回值,避免与 inspector 返回混淆;补回迁移时遗漏的实际曲线端点切线/反向箭头说明,并加入 runtime 来源基准。
  • 验证通过:五页首个 TypeScript 示例类型检查和真实执行,Web 类型检查 0 错误/警告/提示;五页 Host Chrome 桌面/手机、哈希、Markdown、canonical、导航与搜索验收。交付文案修订后重新 Web 构建,296 个 HTML/Markdown 页面的链接/锚点/资源检查通过,inspectors/annotations 两页定向浏览器复验通过。
  • 最终 10 个文件,格式/diff、80 页来源基准通过,254 条来源全部解析到真实提交链接。工作区 clean,服务保留;未合并、推送或发布。工具集成入口及最终覆盖核对仍待完成,issue 保持 OPEN / status:in-progress。

工具集成入口(2026-09-22,已本地提交)

本节提交为 6fa3cb8911b45c79242a1779d27a5df570bd4c93core: document tooling integration APIsrefs #232)。

  • 新增 tooling 总入口及 12 篇职责专题,共 13 页:输入/时间作用域、资源安装、缓存、草图快照/求解、草图曲线/区域、求值/生命周期、关系预览、模型快照、空间数学、拓扑、材质、检查记录。原草图专题按快照与解析几何拆成两个阅读页,仍作为一节提交。同步 README、API/runtime 入口及 sidebar,无源码变更。
  • 独立对照源码公开导出、发布声明清单与文档标题:154 个导出(81 个值、73 个类型)全部在唯一专题条目中。每项签名、字段、可选值及 union 分支有说明;共用作者类型链接主说明,未重导出的辅助类型明确由结果推断。ModelObject、RelationObject、Constraint、RelationExpression 均为 type-only 导出,不宣称可从 tooling 导入构造器。
  • 生命周期说明覆盖串行全局上下文、finally 恢复、完整运行图收集、共享几何在同一次 dispose 中去重、保留原生快照的借用/克隆边界和单独释放。跨 Worker 使用编码输入及普通查询结果,精确区分 bounds 二元组、RenderMesh、拓扑分页和私有实现记录。
  • 验证通过:13 页首个 TypeScript 示例类型检查及真实执行,Web 构建及 322 个 HTML/Markdown 页面的链接/锚点/资源检查,Web 类型检查 0 错误/警告/提示;Host Chrome 13 页桌面/手机、哈希、Markdown、canonical、导航和搜索验收。契约专项验证编码 query batches、bounds 元组、render mesh、保留拓扑分页、metadata 映射复制、材质 opacity 和重合曲线相交行为。
  • 验证期间修正草图 circle 示例嵌套,并修正专项 driver 对共享 material copy 分次 dispose 的错误;最终 driver、网站构建及浏览器均通过,文档已明确一次释放完整共享图。
  • 交付复核:17 个文件,Prettier/diff 与 93 页来源基准通过,288 条来源均解析到真实提交链接;工作区 clean,服务保留。未合并、推送或发布。各分类已本地完成,下一步为最终导出索引和旧总览收口核对;issue 保持 OPEN / status:in-progress。

最终覆盖与导航收口(2026-09-22,已本地提交)

第 16 节提交 2a246d203a79baca10374ef9b4aabdaaa89b4642core: complete API documentation coverageCloses #232)完成全部已列内容的本地交付。

  • 新增完整 exports 索引,逐项映射 53 个根入口值、80 个根入口类型、模型/引用/旋转链成员和互操作子路径;补全 ElementKind / Anchor 泛型与 TopologyId / TopologyKind 别名说明。旧 origin/relations 重复技术正文收拢为主说明链接,README/sidebar 同步。此节 6 个文件,无源码变更。
  • 独立复核发布声明与文档归属:根入口 133 项、tooling 154 项一致,每个公开 API 都有主说明;94 细页各有唯一 sidebar、示例、签名和 sourceReview。对照本任务开始前 38e2d27,api.md 和 runtime.md 的原有标题/锚点全部保留。Three.js / Replicad 透传范围按集成限制及上游参考组织,内部导出不冒充公共构造器。
  • 最终验证:导出索引 TypeScript 示例类型检查/实际执行、AST 覆盖检查、Prettier/diff、94 页源码核对通过;294 条来源记录均能解析到匹配内容的真实提交与链接。Web 构建及 324 个 HTML/Markdown 页面的链接、锚点、图片和资源检查通过,Web 类型检查 0 错误/警告/提示;Host Chrome 索引桌面/手机、哈希、Markdown、canonical、导航与搜索验收通过。
  • 前述各节的 Core 537 项回归、所涉 App 参数/检查器/资源/示例测试、逐页真实 TypeScript 示例、打包/双构建、配图和浏览器验收记录均已复核;本节无源码变化,未重复无关昂贵测试。没有把曾失败的中间命令报告为成功,修复及对应复验已在各节记录。
  • 全部分节提交数经 Git 确认为 16;最终工作区 clean。网站预览和 App 开发端口分别返回 HTTP 200。没有合并、推送、部署或停止服务;所有内容完成后状态转为 OPEN / status:review,等待用户验收与后续已授权集成操作。

范围与组织

  • 导航采用“用途分类 → API 文档”。覆盖公开函数、实例方法、属性、草图实体与约束,以及关联类型;不能只统计根入口导出的函数。
  • 建模 API 为主要阅读入口;扩展开发、工具集成独立组织。以实际入口、公开类型和行为为准,不把 runtime.ts 的全部导出都当成建模 API。
  • Code3D 自己定义的公开 API 逐项对应文档页或明确锚点。Three.js、Replicad 透传能力说明 Code3D 的集成方式与限制,链接上游参考,不复制第三方整套 API 文档。@internal 导出在覆盖核对中标明内部用途,不作为正常建模入口推荐。
  • 等价函数与方法合写,例如 extrude(face, distance)face.extrude(distance)。同名但不同语义的入口分清,例如模型 .rotate() 与关系中的 rotate(),并互相链接。
  • 配置类型跟随 API 页面,例如 LoftOptionsRevolveConfig;共用的模型、参考和能力类型另设总览,明确不同模型支持的成员。
  • 继续以 packages/core/README.mdpackages/core/docs/ 为唯一内容来源,由现有网站管线生成 HTML 与纯 Markdown。沿用现有英文文档语言与风格。概念和教程解释整体机制,API 参考解释具体调用,避免重复维护完整技术正文。

建模 API 分类

分类 主要覆盖范围
实体图元 boxcylindersphereellipsoidfrustumregularPrismtubecoil
点、曲线与轮廓 pointlinearcbeziersplinecircleellipserectangleregularPolygon
草图 sketch、实体与约束、.point().derive().face().faces();草图摆放与参考
文字与字体 textfontgoogleFont
成形操作 extruderevolvesweeploftwrapthicken,包含对应模型方法
布尔运算与实体修饰 unioncutintersect.fillet().chamfer().shell()
原点与局部变换 .originPoint().originVertex().originOffset()originCenter.rotate().scaled()
组合与相对摆放 group.expose().relate()onalignoffsetrotatepivot / pivotVertex / pivotPointaxisEdge / axisLine、旋转链的偏移成员、coupleRotation
拓扑与参考元素 顶点/边/面单项与集合选择;frameorigincenteraxisplane、六向边界、曲线端点;id / kind.flip().reverse()
几何测量 distance.length.area.volume.bounds().position()
材质与外观 .material()、颜色写法、@code3d/core/three 入口及材质集成限制
参数、时间与缓存 inputtimeOffsetcache

另外两个入口:

  • 扩展开发definePrimitivereplicadgetModelData / setModelData、自定义检查器、captureInspectDatainspectGroupMembersdimensionboundsAnnotationanchorAnnotation 及关联类型。
  • 工具集成@code3d/core/tooling,按运行环境与资源初始化、模型求值及生命周期、快照与源码检查、关系和操作跟踪、草图工具、空间与拓扑工具、材质处理、内核缓存等用途组织。

完整导出与成员清单已在本 issue 下方按文档归属记录;首批核对根入口、子路径、公开接口继承成员及类型。后续新增 API 同步维护。

分批实施清单

以下为建议推进顺序;一个分类可以跨多天完成。根据真实使用需求调整顺序时同步更新本 issue。

  • 核对完整 API 覆盖清单;确定分类导航、稳定 URL 和旧章节迁移方式,完成 box 作为首个参考页面。(已本地提交,尚未推送)
  • box 为样板拆出源码职责,建立每页独立版本、文件哈希及提交来源核对机制。(本地验证完成)
  • 实体图元:box、cylinder、sphere、ellipsoid、frustum、regularPrism、tube、coil 全部完成独立文档与源码核对。(已本地提交,尚未推送)
  • 点、曲线与轮廓:九个 API 独立文档、实现拆分、配图与源码核对完成。(已本地提交 69d231f,尚未推送)
  • 成形操作:extrude、revolve、sweep、loft、wrap、thicken 六页及等价方法、配置类型完成。(已本地提交 2e2cf49,尚未推送)
  • 布尔运算与实体修饰:union、cut、intersect、fillet、chamfer、shell 六页及等价方法完成。(已本地提交 bb707e2,尚未推送)
  • 原点与局部变换:originPoint、originVertex、originOffset、originCenter、model.rotate、scaled 六页完成。(已本地提交 ba87040,尚未推送)
  • 组合与相对摆放:group、expose、relate、on、align、独立变换、pivot/axis 链与 coupleRotation 共 13 页完成。(已本地提交 757c800,尚未推送)
  • 拓扑与参考元素:单项/集合选择、参考元素、方向边界与 flip/reverse 六页完成。(已本地提交 e158009,尚未推送)
  • 几何测量:distance、length、area、volume、bounds、position 六页完成。(已本地提交 420a6c5,尚未推送)
  • 草图实体、约束、派生与区域提取,含 plane / relate(9f66bcb,已本地提交)。
  • 文字与字体(3d2db0c,已本地提交)。
  • 材质与外观(be0d9a6,已本地提交)。
  • 参数、时间与缓存(e131137,已本地提交)。
  • 模型、参考与能力类型总览,并核对各 API 的关联类型(5b7b6fe,已本地提交)。
  • 扩展开发入口(c600453,已本地提交)。
  • 工具集成入口(6fa3cb8,已本地提交)。
  • 最终逐项核对覆盖情况、文档入口、旧章节迁移和全部链接(2a246d2,已本地提交)。

已按用户最新授权补齐全部清单,每个 section 单独提交;复杂 section 分步实现与验证后形成一笔完整提交。以完整、可验证的内容为发布单位,不上线空白占位页,也不为凑每日数量拆出只有签名的薄页。首批的全量核对与导航工作可跨多天,不能为了完成计划而仓促铺开全部页面。

具体目录与导航结构在首批开工前说明调整理由、方案及影响;随文档批次逐步拆出对应 API 的实现模块;box 样板及后续两类 API 沿此方案执行,不新增包。迁移已有参考内容时,同批更新来源、入链和锚点,保留仍有阅读价值的概念说明,不留下两份相互漂移的 API 正文。对已有可访问 URL 的必要变更明确处理跳转和 canonical。

源码核对方案(已确认)

  • 随文档逐步拆出 API 实现,box 的构造、几何与检查器归入独立文件,API 汇总入口单独组织以避免循环依赖;通用模型机制仍共享。
  • 细粒度页面各自保存核对时包版本、相关源码路径与 SHA-256 内容哈希;已有匹配提交时记录提交哈希,未提交内容不伪造提交来源。
  • 独立检查命令只报告文件变化、缺失和未建基准的页面;人工复核后显式更新指定页面,构建不能自动刷新基准。HTML 与 Markdown 使用同一页面元数据。
  • 文件列表是人工维护的核对范围,不声称自动覆盖传递依赖;共享机制变更需沿调用方复核受影响页面。

每页内容与每批验收

  • 说明用途、导入方式、完整签名与重载、适用模型类型、参数、返回值、单位、默认值、失败条件和当前限制。区分 TypeScript 必填参数与编辑中运行时默认值。
  • 有最小可运行示例,解释实际结果;需要观察几何时复用 App 的真实示例与图片,并链接完整源码。避免只改名称和参数的同质页面。
  • 空间 API 明确坐标所属、原点和关系求解语义;查询 API 明确返回普通数值/引用还是新模型,以及适用模型种类。
  • 每个 API 有唯一主要说明位置和稳定可链接锚点;等价调用不重复成页,相关 API 和概念互相链接。
  • 校对当前源码、公开声明和既有行为验证;对本批示例做相称的类型/执行验证。遵循 Web 文档约定,运行受影响的文档检查与网站构建,核验 HTML、Markdown、链接、锚点和资源。
  • 完成本批后更新 issue:实际覆盖 API、文档链接、验证结果、源码状态与线上发布状态、下一批范围。只有整个分类核对完成才勾选对应项。
  • 提交、推送和发布沿用各次实际授权;每日推进计划不自动创建定时执行任务。

SEO 与发布节奏

每日小批次是持续维护和质量控制的节奏,不把每日更新次数作为排名保证。Google 明确说明,仅为了让站点显得“更新鲜”而增删内容并不能提升整体排名;优先提供对读者完整、有帮助且准确的内容。参考 Google 的内容质量指南

每页使用准确且有区分度的 title、H1、description,自然说明 API 名称、Code3D 与实际建模用途;通过分类入口、README、概念页及相关 API 建立可抓取的内部链接。HTML 与 Markdown 共用内容来源,延续现有 canonical 机制,避免近似重复的关键词页面。参考 Google Search Essentials

发布时核验实际页面、canonical、sitemap 与可抓取性。若提供 lastmod/lastUpdated,只反映真实内容更新,不因构建或发布日期统一刷新;站点地图中的 lastmod 应对应实质变更。参考 Google sitemap 指南

搜索效果在发布后通过 Search Console 的索引、展示和点击趋势观察;源码完成、线上发布、搜索收录分别记录,不把构建成功或站内搜索命中当成 Google 已收录。

现有基础

Solid Primitives 扩展批次(2026-09-22,已本地提交)

  • 在 box 基础上新增 cylinder、sphere、ellipsoid、frustum、regularPrism、tube、coil 七个完整参考页。每页包含真实示例与图片、签名、参数、坐标与参考元素、测量、约束、运行时编辑默认值及关联 API。
  • 每个构造器的参数标注、专属几何和校验归入独立源码文件;ellipsoid 的几何构造跟随 API,coil 净空校验保留在 coil 模块。通用模型机制与正数校验继续共享;同步公开入口、authoringApi 汇总与内部测试导入。公开调用方式和模型行为保持一致。
  • 八页各自记录核对版本、实现文件与 validation.ts 的 SHA-256。新增文件现已包含在 1baef99a1318fc694825ec0a48d4d39635a3a130;提交后复验八页全部基准通过,16 条来源均能按内容匹配解析到该提交,不需要自动改写基准。
  • 复用现有 Basic shapes 示例,在共享 sourceContextSets 中增加八个图元视图;使用本地构建并打包的实际 Core 生成七张新增 PNG,已逐张查看。现有 box 图片继续复用,没有复制建模源码。
  • 完成 Solid primitives 八项 sidebar、API 总览、README 与相关链接;保留旧分类锚点,移除已迁入细页的重复总览说明。regularPrism 的稳定 URL 为 /docs/packages/core/api/regular-prism/,标题仍使用准确 API 名。
  • 文档中特别核对:圆柱半径/直径、椭球三半轴、圆台两端半径和零半径限制、棱柱外接半径/跨平行边尺寸/旋转/奇数边形包围盒中心、管壁与通孔、线圈实际高度/分数圈/斜向净空。
  • 验证通过:Core 构建、类型检查和 537 项测试;App 参数工具 17 项测试;示例注册/定位与 Basic shapes 几何 2 项测试;源码核对及 Markdown 发布 13 项测试;八页实际示例的 TypeScript 编译与执行,尺寸、体积、轴、圆台变体、棱柱旋转、分数圈中心和文档错误案例核对;八页源码基准检查。
  • App/Web 构建、Web 类型检查(0 错误/警告/提示)通过;145 个 HTML/Markdown 页面的链接、锚点和资源检查通过;格式与 diff 检查通过。
  • Host Chrome 验收通过:八页桌面/手机布局、唯一 sidebar 入口、图片、canonical、HTML/Markdown 核对版本与哈希一致;分类链接、coil 搜索和 Basic shapes 页面正常,无 pageerror。测试与渲染驱动采用 3 GiB RAM、禁 swap 和截止时间限制;既有宿主 Chrome 与独立开发服务不在驱动 cgroup 内。
  • 本地验收入口:Solid primitivescoilregularPrism。继续沿用同一任务工作区及 5185/5186 服务。
  • 本地提交:1baef99a1318fc694825ec0a48d4d39635a3a130core: document solid primitives with source review baselines),使用 refs #232。提交前再次核对 50 个文件、源码基准、Prettier 与 diff,通过后提交;工作区 clean。未合并、推送或线上发布,总 issue 保持打开,其他 API 分类继续按清单推进。
  • 源码哈希检查通过 Web build 接入现有 Push/PR CI 与主分支部署流程;本次仅本地提交,远端 CI 尚未包含这些改动。

第一批交付状态(2026-09-22,已随 Solid Primitives 批次提交)

  • 任务工作区:code3d-issue-232-core-api-docs-p61-0922;分支同名去掉 code3d- 前缀;owner w1:p61。包含文档、导航、源码职责拆分与源码核对工具;公开 API、模型行为与状态语义保持一致。
  • 新增 packages/core/docs/api/box.md:用途、真实 App 示例与既有图片、签名、参数、局部坐标、参考元素、测量、校验和编辑默认值。
  • Core API 总览增加 12 类用途导航;README 增加详细页入口;Starlight 导航为 API reference → Solid primitives → box。未完成的其他 API 继续链接到现有章节,不创建占位页。
  • 目录选择:新增包内 docs/api/,详细页使用固定 /docs/packages/core/api/<api-name>/ 地址;分类由 sidebar 组织,避免以后调整分类时改动 URL。现有总览和旧锚点保留,后续逐项把技术正文归入对应详细页。Web README 已说明这套维护方式。
  • box.ts 统一箱体构造、参数标注、几何创建和尺寸检查器;validation.ts 共享正数校验;authoring-api.ts 汇总作者入口,避免运行时反向依赖 box。同步 root/tooling 导出、资源生命周期测试和编辑器源码跳转夹具,无旧入口转发层。
  • box.mdsourceReview 独立保存核对时包版本、两个源码路径和 SHA-256。HTML 与 Markdown 共用该记录,折叠区展示源码与匹配提交;首次建立基准时两个源文件尚未提交,因此不伪造提交哈希;现已随本批提交,构建可按内容匹配并生成链接。
  • npm run docs:sources:check --workspace @code3d/web 只读检查;npm run docs:sources:review --workspace @code3d/web -- packages/core/docs/api/box.md 在复核后显式刷新该页。Web 构建先检查基准,缺失或过期时失败;不因发包、构建或无关文件变动自动刷新。
  • Web README、内部建模架构和持续重构技能已同步逐页核对流程;人工维护的文件列表不代替共享机制改动的影响分析。
  • 完整导出清单经过源入口与公开声明核对,见下方;涵盖继承成员、配置/返回类型、草图联合分支、互操作和内部导出边界。
  • 验证:Core 构建、类型检查与 537 项测试通过;App 参数装饰/源码检查的 51 项测试通过;13 项源码核对及 Markdown 发布测试通过(含无关变更、缺失文件、显式刷新、发包不刷新页面、未提交/已提交来源);App/Web 构建及 Web 类型检查通过;131 个 HTML/Markdown 页面链接、锚点与资源检查通过;页面实际 TypeScript 示例通过类型检查与执行,尺寸/面积/体积/拓扑数量/默认值/三个参数错误均验证;格式与 diff 检查通过。
  • Host Chrome 验收通过:桌面与手机布局、展开的源码哈希区、HTML/Markdown 核对信息一致、分类链接、唯一 sidebar 入口、图片加载、canonical、Pagefind 搜索;Monaco 原生/参数语言服务测试确认跳转到 box.ts,浏览器无 pageerror。测试驱动受 3 GiB RAM、禁 swap 和截止时间约束;宿主 Chrome 和独立 App 开发服务器不属于该驱动资源上限。
  • 本地预览:box 页面分类入口。预览服务保留在本会话 pane w1:p6G;App 开发服务位于 http://127.0.0.1:5186/,pane w1:p6H;本机地址仅供本地验收。
  • 本批已包含在上方 Solid Primitives 提交 1baef99a1318fc694825ec0a48d4d39635a3a130;尚未合并、推送或线上发布,根 issue 保持打开,其余分类继续按总清单推进。

API 覆盖核对清单(最终复核)

基于最终合并提交 36ba351 的真实导出、构建后公开声明和继承成员核对:根入口 52 个公开值 + 83 个类型;tooling 83 个值 + 73 个类型;Replicad 集成新增 2 个值 + 1 个类型。入口计数包含重复重导出的类型,不代表独立 API 数。Node 根入口仅增加自动初始化后重导出相同 API。

状态统一说明:下列全部分类、公开成员及类型均已实现细粒度参考并完成本地验收。 当前主说明映射见完整导出索引。下表保留最初分类和既有章节链接供追溯;新页面均已推送到远端 main。所有配置字段、重载、联合分支和返回结构归对应函数或类型页,不单独发布薄页。

根入口:公开函数和值、类型

分类/当前阅读入口 函数和值 类型
实体图元 boxcylindersphereellipsoidfrustumregularPrismtubecoil
点、曲线与轮廓 pointlinearcbeziersplinecircleellipserectangleregularPolygon
草图 sketch SketchSketchEntrySketchConstraintSketchOptionsSketchPointSketchPositionSketchArcDirection
文字与字体 textfontgoogleFont FontGoogleFontOptionsTextOptions
成形操作 extruderevolvesweeploftwrapthicken LoftOptionsRevolveConfigWrapOptions
布尔与实体修饰 unioncutintersect SolidModificationCapabilities
原点与局部变换 originCenter
组合与相对摆放 groupframeoffsetrotateonalignpivotpivotVertexpivotPointaxisEdgeaxisLinecoupleRotation ConstraintTransformationRelationPivotChainPivotRotationAxisChainAxisRotationRotationCouplingConfigFrameGroupOptionsElementSourcesExposedValueExposedElementsMergedElementsNamedElements
拓扑与参考元素 AnchorPointAnchorLineAnchorFaceAnchorFrameAnchorBoundDirectionalBoundsVertexEdgeSurfaceSolidVertexTopologyCapabilitiesEdgeTopologyCapabilitiesSurfaceTopologyCapabilitiesEdgeIdSurfaceIdVertexIdTopologyIdTopologyKindCanonicalElementsPlanarElementsCurveElementsElementKind
几何测量 distance DistanceAxisModelBounds
参数、时间与缓存 inputtimeOffsetcache InputOptionsCacheOptions
扩展开发:模型附加数据与检查器 模型 .metadata / .withMetadata()inspectGroupMemberscaptureInspectDatadimensionboundsAnnotationanchorAnnotation ModelMetadataDimensionDimensionSegmentBoundsAnnotationAnchorAnnotationPreviewValueInspectResultInspectCallInspectClosureExecutionInspectContextFactoryInspectClosureInspectContextInspector
模型与共用类型 ModelSolidModelFaceModelEdgeModelVertexModelGroupModelModelCapabilitiesGeometryCapabilitiesGeometryQueryCapabilitiesModelForKindModelKindModelGeometryKindModelElementKindVec3

材质与外观没有根入口自由函数:.material() 见下面模型成员,Three.js 子路径见互操作入口。box 的主页面为 packages/core/docs/api/box.md;后续 API 页沿用 packages/core/docs/api/<api-name>.md 的固定 URL,分类只影响导航。

模型、参考、草图与旋转链成员

下表列出公开能力中去重后的成员;相同名字按所属值解释。具体模型支持范围沿公开能力接口核对,用户自定义的具名成员由 expose() 说明。

归属 成员/文档归属
所有模型(含 GroupModel) metadatawithMetadata() → 模型 metadata; originframe → 拓扑与参考;bounds()position() → 测量;relate()expose() → 组合与摆放;originOffset()originPoint()rotate() → 原点与局部变换;material() → 材质;updownleftrightfrontback → 方向边界
几何模型(不含 group) center → 参考;originCenter()originVertex()scaled() → 原点与局部变换
顶点拓扑能力 vertex()vertices() → 拓扑选择
边拓扑能力 edge()edges(),并继承顶点选择 → 拓扑选择
面拓扑能力 surface()surfaces(),并继承边和顶点选择 → 拓扑选择
SolidModel cut() → cut;fillet()chamfer()shell() → 实体修饰;areavolume → 测量;默认 CanonicalElements.center / axis → 参考
FaceModel extrude()revolve()sweep()thicken() → 等价函数页;area → 测量;flip() → 参考朝向;默认 PlanarElements.center / plane → 参考
EdgeModel length → 测量;reverse() → 参考方向;默认 CurveElements.start / midpoint / end → 曲线参考
独立 Frame .origin.relate() → frame;不提供几何、bounds 或模型成员能力
FrameAnchor/LineAnchor/FaceAnchor/Bound FrameAnchor.originLineAnchor.reverse()FaceAnchor.flip()Bound.flip() → 参考元素;PointAnchor 无普通可读字段
Vertex/Edge/Surface kindidcenter、六向边界及各自拓扑选择;Edge 另有 start / midpoint / end / length / reverse(),Surface 另有 area / flip() → 拓扑、测量与参考
Solid 引用 kindcenter、六向边界、面/边/顶点选择、areavolume → expose 得到的引用与测量
Sketch planerelate()point()derive()face()faces() → 草图;SketchPoint 的 sketch / id → 点引用
旋转链 PivotChain.pivotOffset()PivotRotation.rotate()(含继承);AxisChain.axisOffset()AxisRotation.rotate()(含继承)→ 相应旋转选择器;完成的 Transformation 不提供后续变换链
Font familystyle → 字体资源
查询和配置值 ModelBounds.minimum / maximum / size → bounds;其余字段由所属配置或结果类型页完整说明

草图实体联合分支:pointlinecirclearc。约束联合分支:fixedhorizontalverticalparallelperpendicularangle(直线方向/两线夹角两种形式)、coincidentmidpointlengthradiussweepxy。均归草图文档,并保留点编号与上游 SketchPoint 引用的区别。

Tooling 入口

以下各行分别归工具集成的对应专题。类型重导出复用主说明;方法和结果字段跟随所属类型,不在建模 API 主导航中重复展示。所有项目已在 12 篇工具集成专题中完成,见Tooling 总入口

专题 值与类型
参数、时间与缓存标识 beginModelInputsbeginTimeOffsetidentifyCachedFunctionModelInputValuesModelInputDefinition
运行环境、字体及资源 installFontEngineinstallModelResourceLoaderModelResourceModelResourceLoadergoogleFontSourcesgoogleFontUrlinstallOpenCascadedescribeOpenCascadeException
内核缓存 clearKernelOperationCachekernelOperationCacheStatssetKernelCacheBudgetsetKernelCachePersistenceThresholdsetKernelArtifactStoresetKernelExternalBytesKernelArtifactStore
草图求解与几何工具 SketchConstraintErrorinstallSketchSolverassertSketchDragConnectionsisSketchsketchDefinitionsketchDragRequiresSolversketchEntityParameterssketchFramesketchPointResolversketchSourcesnapshotSketchsolveSketchSnapshotwithSketchEntityParametersSketchSketchArcDirectionSketchArcSnapshotSketchCircleSnapshotSketchConstraintSketchEntitySnapshotSketchEntrySketchLineSnapshotSketchOptionsSketchPointAddressSketchPointSnapshotSketchPositionSketchSnapshotsketchCurveIntersectionsSketchCurveIntersectionsketchArcGeometrysketchCurveBoundssketchCurveClosestParametersketchCurveGeometrysketchCurvePositionsketchCurveTolerancesketchPositiveAngleSketchCurvesketchRegionsSketchRegion
求值、模型身份与生命周期 authoringApibeginModelEvaluationbeginModelInspectiondisposeModelObjectsisModelObjectisFrameisSolidModelmodelObjectRuntimeInforelatedModelObjectsretainModelGeometryModelObjectModelObjectRuntimeInfoModelGeometrySnapshotModelKindModelGeometryKindRelationObject
关系求解与跟踪 relationPreviewcurrentRelationSelfrelationSelectionPreviewrelationTraceReferenceinstrumentRelationisConstraintisRelationExpressionConstraintConstraintAnchorSnapshotRelationExpressionRelationPreviewConstraintSnapshotTransformationSnapshotRelationStageSnapshotRelationSpatialReferenceConstraintTraceReferenceRelationTraceReferenceRotationReferenceSnapshot
模型操作、参考与快照 createModelSnapshotterexecuteSnapshotQueryBatchinstrumentModelOperationmodelOperationObjectmodelElementReferencepreviewAnchorReferencemodelTopologyIdsmodelTopologyReferenceplanModelSnapshotQueriesElementKindElementSnapshotModelElementReferenceModelOperationInputRoleModelOperationInstrumentationModelOperationKindModelOperationSelectionSnapshotModelOperationSnapshotModelParameterDimensionModelSnapshotObjectModelSpatialOperationModelTopologyReferenceParameterKindParameterTargetParameterUsageRenderMeshSnapshotQuerySnapshotQueryBatchSnapshotQueryResultSourceRefTransform
空间运算 composeTransformsidentityRigidTransforminvertTransformquaternionAxisAnglerelativeTransformrotateVectorrotationAroundtransformsAreEquivalentxyzRotationQuaternionRigidTransformVec3
拓扑检查与 ID TopologyGeometryTopologyInspectionTopologyInspectionItemTopologyInspectionOptionsEdgeIdSurfaceIdTopologyIdTopologyKindVertexIdTopologyIdSetcompareTopologyIdsformatTopologyIdisTopologyIdsameTopologyIdtopologyIdKey
材质与颜色 captureModelMaterialmodelMaterialColorModelMaterialSnapshotparseModelColorModelColor
源码检查数据 recordInspectionCallsinspectionIdentity

需要随所属 tooling API 一起说明的对象成员:TopologyIdSet 的构造参数、迭代、size / has / add / delete / clearKernelArtifactStorependingWriteBytes / get / getMany / set / touch / touchMany / delete / flushModelResourceLoader.load / bundle / decodedModelGeometrySnapshot.shapes / inspect / disposeSnapshotQueryBatch 的查询数据和 encode / acceptSketchConstraintError.constraintsbeginModelInputs() 返回的 definitions / finish() 等作用域退出入口。ModelObject / RelationObject 的正常建模成员链接上述主说明,工具专用 nodeId / sourceRefs / parameters / solvePose / previewElement 归运行时类型。所有快照联合分支和字段均随类型正文核对。内部品牌、私有字段、受保护成员不作为用户 API。

互操作入口与内部导出

  • @code3d/core/replicaddefinePrimitivereplicadReplicad → 自定义图元与互操作;上游类型透传,以及 replicad 所暴露的上游功能 → 说明 Code3D 运行时绑定和资源所有权后链接上游。Node 子入口先初始化相同运行时。已在 definePrimitive and Replicad 页面完成。
  • @code3d/core/three:原样转出 Three.js → 材质与外观/Three.js 集成入口,说明共享依赖实例、支持的材质与纹理限制,链接上游完整参考。已在 Three.js integration 页面完成。
  • 根入口源码标记 @internal、构建声明已剔除的 6 个值:relateexposeinspectTopologyReferenceinspectLengthinspectAreainspectVolume。用于执行与检查,不作为普通建模自由函数补页;模型 .relate() / .expose() 仍是公开 API。

核对依据包括公开声明的继承成员和源文件中的联合分支。此清单记录文档归属与进度,不替代实际类型签名;API 变动时同步调整同一 issue 的清单。

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions