docs(readme): lead with the agent landing line; the new editor replaces Re-Studio

- both READMEs open with the line to paste to a coding agent
- pillar 3 is now the code-first editor (screenshot added); Re-Studio and the
  standalone sca-web-editor references are gone
- update notes for 2.2, install and examples sections brought up to date
- remove the Re-Studio skill workflow and its demo media (10 MB)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-10-13 13:22:47 +08:00
parent 2f81fcdd18
commit 8816d511b0
8 changed files with 156 additions and 249 deletions
+8
View File
@@ -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
+75 -45
View File
@@ -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
</tr>
</table>
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.
<table>
<tr>
<td width="50%" align="center" valign="top">
<img src="img/capability/reverse_studio_mvp.gif" alt="re-studio: click faces, annotate intent, agent rebuilds"><br/>
<b>re-studio MVP</b> — 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 ·
<a href="img/capability/reverse_studio_mvp.mp4">▶ full video</a>
<td align="center" valign="top">
<img src="img/capability/editor.png" alt="sca edit on the u_link motor mount: a picked face, the selection cell it wrote, its properties"><br/>
<b>u_link motor mount in <code>sca edit</code></b> — a picked cylindrical face, the
<code>selected_face</code> cell the editor wrote for it, and its properties;
<code>sca example u_link</code> copies this workspace out
</td>
</tr>
</table>
@@ -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/)
+72 -29
View File
@@ -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 思考、每一
</tr>
</table>
旋转展示由独立的 [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 缓存。
<table>
<tr>
<td width="50%" align="center" valign="top">
<img src="img/capability/reverse_studio_mvp.gif" alt="re-studio:点选面、标注意图,agent 重建"><br/>
<b>re-studio MVP</b> —— 在 STEP 目标上点选面、逐条叠加操作意图与备注后提交;
agent 据此对连杆全部 37 个面做分类,从你的上下文出发开始重建 ·
<a href="img/capability/reverse_studio_mvp.mp4">▶ 完整视频</a>
<td align="center" valign="top">
<img src="img/capability/editor.png" alt="sca edit 打开 u_link 电机座:选中的面、编辑器写出的选择 cell 及其属性"><br/>
<b><code>sca edit</code> 中的 u_link 电机座</b> —— 选中的圆柱面、编辑器为它写出的
<code>selected_face</code> cell,以及它的属性;
<code>sca example u_link</code> 可把这个工作区复制出来
</td>
</tr>
</table>
@@ -121,17 +133,25 @@ CalculiX 静力 FEM(边界面按保真的 `interface.*` 标签选取,仿真
---
## 更新日志(2.1.3b1)
## 更新日志(2.2)
> **发布说明:** 预发布(beta)。用于生产前,请验证生成的定义、装配约束和制造几何。
> **版本提示:** 预发布(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 缓存取代。
- **新编辑器。** `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/)
@@ -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
<case_dir>/
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/<op_id>.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 <case_dir> --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 <case_dir> --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 <case_dir> --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.
@@ -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
Binary file not shown.

After

Width:  |  Height:  |  Size: 288 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.3 MiB

Binary file not shown.