diff --git a/CHANGELOG.md b/CHANGELOG.md index 01b3ad8b..3596e4c2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and ## Unreleased +### Removed + +- Re-Studio, the reverse-engineering studio (the `Re-mode` workspace of the + standalone sca-web-editor), and its skill workflow + `reverse-engineering-studio.md`. `sca edit` replaces the standalone editor; + STEP reconstruction continues through the inspection API and the + `step-reconstruction` workflow. + ### Added - `sca edit [WORKSPACE]`: the web editor, now part of the SDK diff --git a/README.md b/README.md index 72c132b3..9bdc4d65 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,18 @@ [中文说明](README.zh-CN.md) +**Start here.** Paste this line to your coding agent (Claude Code, Codex, OpenCode, …): + +```text +Read physpace.dev/sca/landing.md and landing me on this sdk. +``` + +It installs the SDK, installs the skill for itself, opens a real example in the +code-first editor, and shows you how to work with it. SimpleCADAPI is a +parametric CAD SDK built for agents: a model is a notebook of code, every +dimension is a named parameter, selection is by what geometry *is*, and every +step reports back why it worked or failed. + ## What Can It Do Four capability pillars. Every case below is a **real, reproducible session**: @@ -45,9 +57,8 @@ deterministic face tags that survive re-parameterization, and synchronized -Turntables are rendered by the standalone [sca-web-editor](https://github.com/PhySpace/sca-web-editor)'s -BRep renderer (face shading + wide edges); one full turn = 48 deterministic -azimuth steps driven through its `gif-harness.html`. +Turntables are rendered with BRep shading and wide edges; one full turn = 48 +deterministic azimuth steps. ### 2 · Assembly Modeling @@ -80,23 +91,25 @@ notebook, composed with `scad.use` from part and sub-assembly notebooks. the package plus STEP / editable FCStd / MJCF; `render_showcase.py` renders the views above. -### 3 · Reverse Engineering +### 3 · Code-first Editor -Import a STEP, inspect its BREP in the browser, and click the geometric -entities you care about — each pick lands as a tag in an annotation composer -next to operation intents (sketch · boolean · fillet · pattern …) and a free -note. Your reverse-engineering hunches ride on concrete face tags, so the -agent receives a narrowed search space instead of guessing from scratch — -and the whole human-agent session is recorded and replayable. +`sca edit` opens a browser editor over a directory of notebooks, built for +working *with* an agent. The notebook's cells are on the left and the live +model is in the middle; a slider or toggle appears for every parameter. Click a +solid, face, edge or vertex and the editor writes a `scad.ql` selection cell +into the notebook file (autosaved), so your coding agent reads what you picked +from disk and "chamfer these two edges" needs no ids. Copy a cell's reference +to tell the agent which cell to change. A log dock shows which cells are being +re-evaluated. The editor and `sca run` share one runtime and one per-cell +cache. -
-re-studio: click faces, annotate intent, agent rebuilds
-re-studio MVP — click faces on the STEP target, stack operation -chips and notes per pick, submit; the agent classifies all 37 faces of a -link rod and starts rebuilding from your context · -▶ full video +		 +sca edit on the u_link motor mount: a picked face, the selection cell it wrote, its properties
+u_link motor mount in sca edit — a picked cylindrical face, the +selected_face cell the editor wrote for it, and its properties; +sca example u_link copies this workspace out
@@ -136,20 +149,31 @@ the full crank cycle sweeps clean in the same sim · --- -## Update Notes (2.1.3b1) +## Update Notes (2.2) > **Release notice:** Pre-release (beta). Validate generated definitions, > assembly constraints, and manufacturing geometry before production use. -SimpleCADAPI 2.1.3b1 ships the addon ecosystem: a `sca` CLI that installs -third-party skill+tooling repositories (`sca addon init/add/update/remove/list`), -a strict `sca-addon.toml` descriptor with platform and `[compat] sca` gates, and -a consumer-facing `.scadpkg` format spec written so an agent given the document -alone can produce a correct parser or exporter. See the -[full English update notes](docs/updates/2.1.3b1.md) for the CLI contract, the -two legal integration modes, and the tag channel. 2.1.2's script-anchored part -cache ([docs/updates/2.1.2.md](docs/updates/2.1.2.md)) has since been replaced -by the notebook runtime and its cell cache. +- **New editor.** `sca edit` is part of the SDK now (`pip install + "simplecadapi[editor]"`). It runs a workspace's notebooks in a marimo kernel + with the SDK's own cell executor, previews the live model straight from the + solids, writes your viewport picks as selection code, and lets an agent see + what you see (`sca snapshot`). **Re-Studio is removed**: the reverse- + engineering studio (the `Re-mode` workspace of the standalone sca-web-editor) + is gone, and the standalone sca-web-editor is replaced by `sca edit`. STEP + reconstruction continues through the inspection API and the skill's + step-reconstruction workflow. +- **One runtime, one cache.** The editor, `sca run` and + `simplecadapi.runtime.run_notebook()` share the per-cell cache, so what one + computed the others restore. Notebook parameters come from `# ---- params + ----` cells with an optional `# ui:` comment; local modules (shared + dimensions) get their own view in the editor. +- **Landing path.** `docs/landing.md` is the script an agent follows to install + the SDK and its skill and open an example; `sca example u_link` copies the + bundled workspace and `sca skill where` shows where the skill goes. +- Earlier: 2.1.3b1 shipped the addon ecosystem (`sca addon ...`, the + `sca-addon.toml` descriptor, the `.scadpkg` format spec); see its + [update notes](docs/updates/2.1.3b1.md). Every example model is a notebook; its export scripts load the product with `run_notebook`, capture one `.scadpkg`, and translate AP242 `.step` and @@ -175,13 +199,15 @@ in a compact public API for creating solids, applying features, tagging semantic intent, querying topology, exporting manufacturing files, and translating recorded models into FreeCAD workflows. -Current release: `simplecadapi==2.1.3`. +Package: `simplecadapi` on PyPI (the 2.2 line is pre-release; 2.1.4 is the latest stable). ## What It Provides - Models as [marimo](https://marimo.io) notebooks: plain `.py` files that are the only source of truth, one feature per cell, a per-cell cache for incremental headless runs (`sca run`), and notebook composition (`scad.use`). +- A code-first web editor, `sca edit`: live model, parameter controls, viewport + picks written back as selection code, built for working alongside an agent. - OCP-native shape types: `Vertex`, `Edge`, `Wire`, `Face`, and `Solid`. - Functional modeling operations for primitives, profiles, extrude, revolve, loft, sweep, booleans, transforms, patterns, fillets, chamfers, and shells. @@ -205,13 +231,8 @@ Current release: `simplecadapi==2.1.3`. ## Install -The shortest way: paste this to your coding agent and it does the rest -(installs the SDK, installs the skill for itself, opens an example in the -editor and walks you through it): - -```text -Read physpace.dev/sca/landing.md and landing me on this sdk. -``` +The shortest way is the line at the top of this page: paste it to your coding +agent and it does the rest. By hand: @@ -360,10 +381,14 @@ sca export out/bracket.scadpkg --output-dir out/exports # AP242 STEP, STL, OBJ sca edit . # web editor over this directory of notebooks ``` -`sca edit` (`pip install "simplecadapi[editor]"`) is a code-first editor: the -notebook's cells on the left, the live model on the right, and a slider or -toggle for every parameter (`# ---- params ----` cells; a `# ui:` comment on -the line picks the control). See `docs/skill/references/docs/guides/notebook-runtime.md`. +`sca edit` (`pip install "simplecadapi[editor]"`) is the code-first editor +described above: the notebook's cells on the left, the live model in the +middle, a slider or toggle for every parameter (`# ---- params ----` cells; a +`# ui:` comment on the line picks the control), and your viewport picks written +back as `selected_*` selection cells. See +`docs/skill/references/docs/guides/notebook-runtime.md` and +`docs/skill/references/domains/editor-collaboration.md` (how an agent works with +what you picked and which cell you mean). ## Notebook Runtime @@ -585,7 +610,7 @@ print("carrier", face["geometry"]["type"]) ``` Use the [Reconstruction Agent test specification](docs/skill/references/docs/guides/reconstruction-agent-test-prompt.md) -for controlled runs and the [STEP BREP reverse-engineering guide](docs/skill/references/workflows/reverse-engineering-studio.md) +for controlled runs and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reconstruction.md) for the inspection primitives, modeling loop, replay checks, and acceptance gates. ## Physical Units And Tolerances @@ -680,10 +705,12 @@ uv run --extra gmsh python examples/ap242_gmsh_volume_mesh/export_fem_mesh.py uv run --extra fem python examples/ap242_gmsh_volume_mesh/run_calculix.py ``` -Reverse engineering runs in the `Re-mode` workspace of the standalone -[sca-web-editor](https://github.com/PhySpace/sca-web-editor) against a target -STEP (see `examples/bowl_connector/` and the -[reverse-engineering studio workflow](docs/skill/references/workflows/reverse-engineering-studio.md)). +To try the editor on a real model, `sca example u_link` copies a motor mount +(two part notebooks and the assembly that fixes them) out of the package, and +`sca edit u_link_motor_mount` opens it; from a checkout, +`sca edit examples/u_link_motor_mount`. Reconstructing a STEP file (see +`examples/bowl_connector/`) is driven by the agent through the inspection API +and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reconstruction.md). ## Documentation @@ -693,8 +720,11 @@ STEP (see `examples/bowl_connector/` and the - 2.1.0 update notes: [`docs/updates/2.1.0.md`](docs/updates/2.1.0.md) - Reconstruction Agent test specification: [`docs/skill/references/docs/guides/reconstruction-agent-test-prompt.md`](docs/skill/references/docs/guides/reconstruction-agent-test-prompt.md) -- Reverse-engineering studio workflow: - [`docs/skill/references/workflows/reverse-engineering-studio.md`](docs/skill/references/workflows/reverse-engineering-studio.md) +- Landing script for agents: [`docs/landing.md`](docs/landing.md) +- Editor collaboration (selection, cell references, parameters): + [`docs/skill/references/domains/editor-collaboration.md`](docs/skill/references/domains/editor-collaboration.md) +- STEP reconstruction workflow: + [`docs/skill/references/workflows/step-reconstruction.md`](docs/skill/references/workflows/step-reconstruction.md) - Notebook runtime and product build workflow: [`docs/skill/references/docs/guides/notebook-runtime.md`](docs/skill/references/docs/guides/notebook-runtime.md) - Public API reference: [`docs/skill/references/docs/api/`](docs/skill/references/docs/api/) diff --git a/README.zh-CN.md b/README.zh-CN.md index f550d5a3..00af8ec5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,6 +6,17 @@ [English](README.md) +**从这里开始。** 把下面这句话发给你的 coding agent（Claude Code、Codex、OpenCode 等）： + +```text +Read physpace.dev/sca/landing.md and landing me on this sdk. +``` + +它会帮你安装 SDK、为自己安装 skill、在 code-first 编辑器里打开一个真实示例，并 +教你怎么和它一起工作。SimpleCADAPI 是为 agent 设计的参数化 CAD SDK：模型就是一个 +代码 notebook，每个尺寸都是命名参数，按“几何是什么”来选择对象，每一步都会反馈 +成功或失败的原因。 + ## 它能做什么 四块能力支柱。下面每个 case 都是**真实、可复现的会话**：回放 demo 是单文件离线 @@ -41,8 +52,7 @@ HTML，忠实回放完整录制的对话（用户输入、Agent 思考、每一 -旋转展示由独立的 [sca-web-editor](https://github.com/PhySpace/sca-web-editor) 的 BRep -渲染器渲染（面着色 + 宽棱边），一圈 = 48 个确定性方位角步进，经其 `gif-harness.html` 驱动生成。 +旋转展示使用 BRep 着色加宽边线渲染；转一整圈 = 48 个确定性方位角步进。 ### 2 · 装配体建模 @@ -72,20 +82,22 @@ HTML，忠实回放完整录制的对话（用户输入、Agent 思考、每一 `uv run python examples/integrated_bldc_joint_actuator/export_all.py` 导出装配包和 STEP / 可编辑 FCStd / MJCF；`render_showcase.py` 渲染上述视图。 -### 3 · 逆向工程 +### 3 · Code-first 编辑器 -导入 STEP，在浏览器里检查 BREP，直接点选你关注的几何对象——每次点选都会以标签 -形式落进标注输入框，旁边配上操作意图（sketch · boolean · fillet · 阵列…）和自由 -备注。你的逆向思路挂在具体的面标签上，agent 收到的是被收窄的搜索空间，而不是从 -零盲猜——人机协作全程录制、可回放。 +`sca edit` 在浏览器里打开一个面向“与 agent 协作”的编辑器，作用于一个 notebook +目录。左边是 notebook 的 cell，中间是实时模型，每个参数都有滑块或开关。点选实体、 +面、边或顶点后，编辑器会把一个 `scad.ql` 选择 cell 写进 notebook 文件（自动保存）， +你的 coding agent 直接从磁盘读到你选了什么，“给这两条边倒角”不需要任何 id。复制 +cell 引用就能告诉 agent 要改哪个 cell。底部日志面板显示哪些 cell 正在重算。编辑器 +与 `sca run` 共用同一个运行时和同一份逐 cell 缓存。 -
-re-studio：点选面、标注意图，agent 重建
-re-studio MVP —— 在 STEP 目标上点选面、逐条叠加操作意图与备注后提交； -agent 据此对连杆全部 37 个面做分类，从你的上下文出发开始重建 · -▶ 完整视频 +		 +sca edit 打开 u_link 电机座：选中的面、编辑器写出的选择 cell 及其属性
+sca edit 中的 u_link 电机座 —— 选中的圆柱面、编辑器为它写出的 +selected_face cell，以及它的属性； +sca example u_link 可把这个工作区复制出来
@@ -121,17 +133,25 @@ CalculiX 静力 FEM（边界面按保真的 `interface.*` 标签选取，仿真 --- -## 更新日志（2.1.3b1） - -> **发布说明：** 预发布（beta）。用于生产前，请验证生成的定义、装配约束和制造几何。 - -SimpleCADAPI 2.1.3b1 带来插件生态：`sca` 命令行安装第三方 skill+工具仓库 -（`sca addon init/add/update/remove/list`）、带平台与 `[compat] sca` 硬门的 -严格 `sca-addon.toml` 描述文件，以及面向消费者的 `.scadpkg` 格式规范——把 -文档交给 agent 即可写出正确的解析器/导出器。CLI 契约、两种合法集成模式与 -tag 通道见[完整中文更新说明](docs/updates/2.1.3b1.zh-CN.md)。2.1.2 的脚本 -锚定 part cache（[docs/updates/2.1.2.zh-CN.md](docs/updates/2.1.2.zh-CN.md)） -已由 notebook 运行时及其 cell 缓存取代。 +## 更新日志（2.2） + +> **版本提示：** 预发布（beta）。投入生产前请验证生成的定义、装配约束和制造几何。 + +- **新编辑器。** `sca edit` 现在是 SDK 的一部分（`pip install + "simplecadapi[editor]"`）。它用 SDK 自己的 cell 执行器在 marimo 内核里运行工作 + 区的 notebook，直接由实体生成实时预览，把你在视口里的点选写成选择代码，并让 + agent 看到你看到的（`sca snapshot`）。**Re-Studio 已移除**：逆向工程 studio + （独立 sca-web-editor 的 `Re-mode` 工作区）不再存在，独立的 sca-web-editor 由 + `sca edit` 取代。STEP 重建继续通过检查 API 和 skill 的 step-reconstruction + 工作流进行。 +- **一个运行时，一份缓存。** 编辑器、`sca run` 和 + `simplecadapi.runtime.run_notebook()` 共用逐 cell 缓存，一方算过的另一方直接 + 复用。notebook 参数来自 `# ---- params ----` cell，可加 `# ui:` 注释指定控件； + 本地模块（共用尺寸）在编辑器里有独立视图。 +- **落地路径。** `docs/landing.md` 是 agent 安装 SDK 和 skill、打开示例时遵循的 + 脚本；`sca example u_link` 复制内置工作区，`sca skill where` 显示 skill 的安装位置。 +- 之前：2.1.3b1 带来插件生态（`sca addon ...`、`sca-addon.toml` 描述文件、 + `.scadpkg` 格式规范），见[更新说明](docs/updates/2.1.3b1.zh-CN.md)。 每个示例模型都是 notebook；导出脚本用 `run_notebook` 载入产品，捕获一个 `.scadpkg`，再从同一个产品包转换出 AP242 `.step` 和可编辑 `.FCStd`。 @@ -153,13 +173,15 @@ tag 通道见[完整中文更新说明](docs/updates/2.1.3b1.zh-CN.md)。2.1.2 SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK，提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API，可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件，以及将记录的模型转换为 FreeCAD 工作流。 -当前版本：`simplecadapi==2.1.3`。 +包：PyPI 上的 `simplecadapi`（2.2 系列为预发布；2.1.4 是最新稳定版）。 ## 核心能力 - 模型即 [marimo](https://marimo.io) notebook：普通 `.py` 文件就是唯一的真相 来源，一个 cell 一个特征，按 cell 缓存实现增量无头运行（`sca run`），并可用 `scad.use` 组合 notebook。 +- Code-first 网页编辑器 `sca edit`：实时模型、参数控件，视口点选写回为选择代码， + 为与 agent 协作而设计。 - 由 notebook 生成的规范 `.scadpkg` 产品包，用于交换和发布，不会反过来作为模型 输入。 - 基于 OCP 的 `Vertex`、`Edge`、`Wire`、`Face` 和 `Solid` 类型。 @@ -176,12 +198,19 @@ SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK，提供清晰的函数式 ## 安装 -使用 pip： +最快的方式是页面顶部那句话：发给你的 coding agent，剩下的它来做。 + +手动安装，使用 pip： ```bash pip install simplecadapi ``` +代码优先编辑器（`sca edit`）需要 `editor` extra：`pip install "simplecadapi[editor]"`； +`uv tool install "simplecadapi[editor]"` 或 `pipx install "simplecadapi[editor]"` +不用虚拟环境就能把 `sca` 放进 PATH。`sca example u_link` 把内置示例工作区复制出来， +再用 `sca edit` 打开。 + 使用 uv： ```bash @@ -309,8 +338,17 @@ marimo edit bracket.py # 响应式编辑器 sca run bracket.py # 运行并输出 JSON 报告 sca run bracket.py --set width=80 --out out/bracket.scadpkg sca export out/bracket.scadpkg --output-dir out/exports # AP242 STEP、STL、OBJ +sca edit . # 这个目录 notebook 的网页编辑器 ``` +`sca edit`（`pip install "simplecadapi[editor]"`）就是上面介绍的 code-first +编辑器：左边是 notebook 的 cell，中间是实时模型，每个参数一个滑块或开关 +（`# ---- params ----` cell；一行末尾的 `# ui:` 注释选择控件），视口点选写回为 +`selected_*` 选择 cell。详见 +`docs/skill/references/docs/guides/notebook-runtime.md` 和 +`docs/skill/references/domains/editor-collaboration.md`（agent 如何使用你的选择和 +指定的 cell）。 + ## Notebook 运行时 marimo 编辑器、`sca run` 和 Python 里的 `simplecadapi.runtime.run_notebook()` @@ -512,7 +550,7 @@ print("carrier", face["geometry"]["type"]) 受控测试请使用 [Reconstruction Agent 测试规范](docs/skill/references/docs/guides/reconstruction-agent-test-prompt.md)， 检查原语、建模循环、回放检查和验收门槛请阅读 -[STEP BREP 逆向工程指南](docs/skill/references/workflows/reverse-engineering-studio.md)。 +[STEP 重建工作流](docs/skill/references/workflows/step-reconstruction.md)。 ## FreeCAD 转换 @@ -553,9 +591,11 @@ uv run --extra gmsh python examples/ap242_gmsh_volume_mesh/export_fem_mesh.py uv run --extra fem python examples/ap242_gmsh_volume_mesh/run_calculix.py ``` -逆向工程在独立的 [sca-web-editor](https://github.com/PhySpace/sca-web-editor) -的 `Re-mode` 工作区里针对目标 STEP 进行（见 `examples/bowl_connector/` 和 -[逆向工程 studio 工作流](docs/skill/references/workflows/reverse-engineering-studio.md)）。 +想在真实模型上试用编辑器：`sca example u_link` 把一个电机座（两个零件 notebook 加 +把它们固定在一起的装配）从包里复制出来，`sca edit u_link_motor_mount` 打开它； +在源码仓库里则是 `sca edit examples/u_link_motor_mount`。重建 STEP 文件（见 +`examples/bowl_connector/`）由 agent 通过检查 API 和 +[STEP 重建工作流](docs/skill/references/workflows/step-reconstruction.md)驱动。 ## 文档 @@ -565,8 +605,11 @@ uv run --extra fem python examples/ap242_gmsh_volume_mesh/run_calculix.py - 2.1.0 更新说明：[`docs/updates/2.1.0.zh-CN.md`](docs/updates/2.1.0.zh-CN.md) - Reconstruction Agent 测试规范： [`docs/guides/reconstruction-agent-test-prompt.md`](docs/skill/references/docs/guides/reconstruction-agent-test-prompt.md) -- STEP BREP 逆向工程指南： - [`docs/guides/step-brep-reverse-engineering.md`](docs/skill/references/workflows/reverse-engineering-studio.md) +- Agent 落地脚本：[`docs/landing.md`](docs/landing.md) +- 编辑器协作（选择、cell 引用、参数）： + [`docs/skill/references/domains/editor-collaboration.md`](docs/skill/references/domains/editor-collaboration.md) +- STEP 重建工作流： + [`docs/skill/references/workflows/step-reconstruction.md`](docs/skill/references/workflows/step-reconstruction.md) - Notebook 运行时与产品构建工作流： [`docs/guides/notebook-runtime.md`](docs/skill/references/docs/guides/notebook-runtime.md) - 公共 API 参考：[`docs/api/`](docs/skill/references/docs/api/) diff --git a/docs/skill/references/workflows/reverse-engineering-studio.md b/docs/skill/references/workflows/reverse-engineering-studio.md deleted file mode 100644 index 91b135a3..00000000 --- a/docs/skill/references/workflows/reverse-engineering-studio.md +++ /dev/null @@ -1,171 +0,0 @@ -# Workflow: Reverse-Engineering Studio (human-in-the-loop) - -Drive the interactive reconstruction studio (the standalone [sca-web-editor](https://github.com/PhySpace/sca-web-editor) re-mode) as the agent -side of a two-actor loop: a human annotates the STEP target in the browser, -the agent reconstructs from those annotations, and the browser displays the -artifacts for the next refinement round. - -## Goal and scope - -Use when a human operator is available to supply feature intent for a STEP -target — the variable that pure LLM+inspection reconstruction cannot recover -from geometry alone. The human picks entities, draws regions, tags operation -tips, and writes free text; the agent turns each submission into FTC code and -verification artifacts. Without an operator, stay on the autonomous path -(`step-reconstruction.md`). - -## Hard rules - -- **Only the human's browser writes `re_work/submission.json`.** The agent - must never POST `/api/submit` or author the submission file; the submission - is the ground-truth human signal and the training record depends on it being - genuine. -- The agent writes artifacts; it does not edit geometry in the UI. The UI has - no geometry-editing surface — code is the single source of truth. -- **Artifact scripts are self-contained.** Any transcription — including - contours and fitted curves — must end up as parameter literals inside the - rebuild script; it must not read the target STEP, sidecars, or generated - blocks at rebuild time. One-shot extraction harnesses live beside the case - (e.g. `re_work/extract_*.py`) and their output is pasted in as literals. -- Verification stays external to the modeling scripts (same rule as - everywhere else): run verifiers, comparison renders, and evaluation reports - as separate steps. - -## Session layout - -```text -/ - target.step - re_work/ - annotations.jsonl # append-only annotation events (UI authoritative) - submission.json # atomic handoff: annotations + server-side context - submission.seq - session.ndjson # full event recording (selections, resolves, submits, - # artifact versions) — the training-data side channel - snapshots/snap-N.png # viewport snapshot submitted with round N - extract_*.py # agent one-shot extraction harnesses (optional) - rebuild.py # agent artifact: FTC reconstruction source (self-contained) - rebuilt.step - rebuilt.scadpkg # captured v3 product package (loads in the UI) - comparison.png # render_step_comparison_rpath shared-camera diff - evaluation.json # external verification report (verdict + named gaps) -``` - -`submission.json` carries: - -- per annotation: the free-form `text` (chips serialize inline as - `[face:12](face:12)` / `[fillet](op:fillet)`), `entity_ids` (canonical ids - like `face:12`), `operations` (referenced operation tip ids), the screen - polygon, and a server-composed context card per entity - (`describe_entity` geometry, bounds, capped adjacency). Unresolvable ids - are listed in `unresolved_entity_ids` — treat them as data errors, never - silently dropped input. -- `operation_context`: the full tip for every referenced operation (see - below), so the agent receives the doc pointers without scraping. -- the round `note` and the viewport `snapshot`. - -## The studio UI (what the operator does) - -- **Select / draw** (left viewport): face/edge/vertex/body picking with - persistent highlight; circle and lasso drawing resolve a screen region to - entity ids server-side. -- **Free-form composer**: picked entities land in the text input as inline - atomic chips (color-coded face/edge/vertex/body), peers of plain text. The - operation palette above it lists five categories — **sketch** (constrained - profiles), **solid build** (extrude/revolve/sweep/loft/booleans), - **modify** (fillet/chamfer), **surface** (patch/fill/gordon/ruled), - **pattern** (linear/radial) — and each button inserts an operation chip. - Tagging an operation next to entity tags declares *what the agent should - read* for those entities. Enter commits an annotation (IME-safe: candidate - confirmation never submits), Shift+Enter inserts a newline, the chip row - shows committed annotations per round. -- **Right side**: the rebuilt viewport (loads the agent's v3 package), the - shared-camera comparison image, and tabs for the highlighted rebuild source - (feature rows reveal their source lines), the feature DAG tree, the - evaluation report, the last submission, and a context preview showing - exactly what the agent will see (minus server-added entity context). -- **SUBMIT** hands the round to the waiting agent; the UI then polls artifact - versions and refreshes automatically. - -## Operation tips (content is markdown, not code) - -Each palette entry is a packaged prompt defined by -`sca_web_editor/operations/.md` in the sca-web-editor repo: YAML-style frontmatter (`label`, -`category`, `api`, `reads`, `doc_refs`) plus the hint text as body. The -registry loader validates and serves them (`GET /api/operations`) and -`compose_submission` embeds the tips for every referenced operation. - -- Tuning or adding a tip is a markdown edit — no frontend or code change; - file edits are picked up via mtime without a server restart. -- `reads` declares which geometric features of the tagged entities the - operation consumes (context assembly guidance); `doc_refs` are - repo-relative skill references the agent should read first; the body is the - imperative usage note. -- Malformed files are named in the payload `errors` list and logged — the - registry never silently drops a broken file. - -## Agent loop - -1. Start the studio and hand the URL to the operator (all commands run from a - checkout of [sca-web-editor](https://github.com/PhySpace/sca-web-editor)): - - ```bash - uv run python -m sca_web_editor --daemon - ``` - - The detached server binds `127.0.0.1:7170` and opens - `http://127.0.0.1:7170/`, the single Web Editor entry. Choose `Re-mode` - in the mode switcher. During development run `npm run dev` in the - sca-web-editor repo, which proxies `/api` and `/rpc`. - -2. Block on the next submission (stay under the Bash tool timeout): - - ```bash - uv run python -m sca_web_editor --wait-only --timeout 590 - ``` - - Exit 0 = fresh submission; 124 = timeout (re-check `re_work/submission.json` - once before falling back to chat); 1 = server died (restart with - `--daemon`, the browser tab reconnects). - -3. Read `re_work/submission.json`. Annotations are intent hints, not geometry - truth — an `exact_copy`-style region still needs measured parameters or - literal transcription. The per-entity context cards carry measured - geometry (radii, lengths, centers); anything beyond them comes from the - inspection API in a separate harness, never from inside the rebuild - script. - -4. Reconstruct per the reconstruction contract: FTC feature blocks per - `discipline/feature-tree-convention.md`, blends as boolean-seam fillets - via `ql-playbook.md` Pattern B selectors re-resolved immediately after - the producing union. Two kernel-ordering facts that keep the tree - buildable: - - - Cut through-bores **before** blend fillets — a filleted body can reject - later boolean cuts in OCC. Bore each ring into a tube first, then union - the transcribed body, then blend. - - Curved freeform contours go through the geometry transcription tier — - sample, `fit_cubic_bspline_control_points`, then pass the fitted - literals to `make_spline_redge` / `make_three_point_arc_redge` / - `make_segment_redge` (the fitter's `to_dict()` returns - `unique_knots` paired with `multiplicities`; the full `knots` vector is - not the edge-constructor contract). - -5. Write the artifact set into `re_work/` (names are fixed — the UI polls - them): `rebuild.py` (self-contained), `rebuilt.step`, - `rebuilt.scadpkg` (via `scad.capture`), `comparison.png` (via - `render_step_comparison_rpath`), `evaluation.json` (verdict plus named - gaps — an approximation stop must say what is unrecovered). - -6. Loop to step 2 for the next refinement round. Finish with: - - ```bash - uv run python -m sca_web_editor --shutdown - ``` - -## Data output - -`re_work/session.ndjson` is the training record: every selection, region -resolve, annotation event, operation-chip insert, submission, and artifact -version, with timestamps. Keep it alongside the artifact set when harvesting -cases; it is the trajectory, not just the endpoint pair. diff --git a/docs/skill/references/workflows/step-reconstruction.md b/docs/skill/references/workflows/step-reconstruction.md index f11a114e..202a6004 100644 --- a/docs/skill/references/workflows/step-reconstruction.md +++ b/docs/skill/references/workflows/step-reconstruction.md @@ -8,10 +8,7 @@ acceptance. Use when the deliverable is an editable/replayable model reproducing a target `.step`/`.stp`. Not for read-only questions about a STEP file — those stay in -`domains/step-inspection.md` without reconstruction. When a human operator is -available to annotate feature intent on the target, run the variant workflow -`references/workflows/reverse-engineering-studio.md` instead of this -autonomous path. +`domains/step-inspection.md` without reconstruction. ## Task decomposition diff --git a/img/capability/editor.png b/img/capability/editor.png new file mode 100644 index 00000000..e8fde3af Binary files /dev/null and b/img/capability/editor.png differ diff --git a/img/capability/reverse_studio_mvp.gif b/img/capability/reverse_studio_mvp.gif deleted file mode 100644 index 9ed3cafd..00000000 Binary files a/img/capability/reverse_studio_mvp.gif and /dev/null differ diff --git a/img/capability/reverse_studio_mvp.mp4 b/img/capability/reverse_studio_mvp.mp4 deleted file mode 100644 index c9b57a74..00000000 Binary files a/img/capability/reverse_studio_mvp.mp4 and /dev/null differ