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:
@@ -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
|
||||
|
||||
@@ -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
@@ -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.
Reference in New Issue
Block a user