docs: update README for handtuned JSON workflow

Document the recommended load-JSON → export URDF path and demote Zhipu to optional.

README.md

@@ -1,99 +1,102 @@
 # step2urdf-tool
 
-Local fork/extension of **[step2urdf](https://github.com/Democratizing-Dexterous/step2urdf)** (UI same product as https://step2urdf.top/), plus a small **FastAPI** backend that proxies **智谱 (Zhipu)** for link/joint suggestions.
+基于 **[step2urdf](https://github.com/Democratizing-Dexterous/step2urdf)**（与 https://step2urdf.top/ 同类 UI）的本地扩展：浏览器内 STEP 解析 + 结构树编辑 + URDF 导出，可选 FastAPI 后端做智谱建议。
 
-Geometry parse + URDF export stay in the **browser** (OpenCASCADE WASM). The backend only helps propose a kinematic draft; you refine axes in the 3D view, then use step2urdf’s own **导出 URDF**.
+**当前推荐路径**：用手调 JSON（`data/handtuned_arm.json`）直接导入连杆/关节/Solid 绑定，再导出 URDF——**不依赖智谱**。
 
-## Architecture
+## 架构
 
 ```
-Browser (Vite :5678)                    FastAPI (:8787)
+Browser (Vite :5678)                    FastAPI (:8787，可选)
 ┌─────────────────────────────┐         ┌──────────────────────────┐
-│ step2urdf UI (frontend/)    │  /api/* │ ZHIPU_API_KEY (server)   │
+│ step2urdf UI (frontend/)    │  /api/* │ POST /api/propose（智谱） │
-│ OCCT WASM · links/joints    │ ──────► │ POST /api/propose        │
+│ OCCT WASM · links/joints    │ ──────► │ /api/health              │
-│ Export URDF (client ZIP)    │         │ optional /api/parse      │
+│ 加载手调 JSON / 导出 URDF    │         │                          │
 └─────────────────────────────┘         └──────────────────────────┘
 ```
 
-Upstream source is under `frontend/` — see `frontend/UPSTREAM.md` for commit SHA.
+几何解析与 URDF 导出都在**浏览器**完成。上游说明见 `frontend/UPSTREAM.md`。
 
-The old MVP static page is demoted to **http://127.0.0.1:8787/legacy/** only.
+## 快速开始
 
-## Quick start (dev)
+### 1. 后端（可选；仅智谱 / health 需要）
-
-### 1. Backend
 
 ```bash
 cd ~/Projects/step2urdf-tool
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
-cp .env.example .env
+cp .env.example .env   # 智谱功能才需要填 ZHIPU_API_KEY
-# edit .env → set ZHIPU_API_KEY (never commit .env)
 python -m app.main
 ```
 
-API: http://127.0.0.1:8787/api/health
+API：http://127.0.0.1:8787/api/health
 
-### 2. Frontend (primary UI)
+### 2. 前端（主界面）
 
-Needs Node 20+ and pnpm 10 (see `frontend/package.json` `packageManager`).
+需要 Node 20+、pnpm 10。
 
 ```bash
-export PATH="$HOME/.local/node/bin:$PATH"   # if pnpm lives here
+export PATH="$HOME/.local/node/bin:$PATH"
 cd ~/Projects/step2urdf-tool/frontend
 pnpm install
-pnpm dev
+pnpm dev --host 127.0.0.1 --port 5678
 ```
 
-Open: **http://127.0.0.1:5678**  
+打开：**http://127.0.0.1:5678**（`/api` 代理到 `:8787`）
-Vite proxies `/api` → FastAPI `:8787`.
 
-Test STEP: `/home/lxqs/A7_step/A7_assembly.STEP`
+### 3. 手调 JSON → URDF（推荐）
 
-### 3. Zhipu button
+1. 导入与手调时相同的 STEP（Solid 编号需一致，如 `Solid_0`…）
+2. 左侧 **Robot Structure** 底部点 **「加载手调 JSON」**  
+   - 读取 `frontend/public/handtuned_arm.json`（与 `data/handtuned_arm.json` 同步）  
+   - 或 **「选择 JSON…」** 选本地文件
+3. 核对结构树、坐标系是否贴在零件上
+4. **导出 URDF**
 
-After importing a STEP:
+JSON 约定：
 
-1. Left panel → **智谱建议关节**
+| 字段 | 含义 |
-2. Confirm/edit part names + profile (`a7` / `generic`) + optional hint
+|------|------|
-3. **请求智谱建议** → preview joints
+| `unit_linear` | 默认 `"m"`；导入时线性量 ×1000 → 页面内部 mm |
-4. **应用到结构树** → writes into step2urdf `useURDFStore` (links, joints, solid binds by name)
+| `links[].solid_names` | 零件归属（`Solid_N`） |
-5. Tweak joint origins/axes in 3D (edge pick / axis offset) — LLM values are approximate
+| `joints[].origin_xyz/rpy` | 相对 **parent link**；限位在 `limits` |
-6. **导出 URDF** (native step2urdf exporter)
+| `base_link.origin_xyz` | 基坐标系在 STEP 世界中的位置（米） |
 
-## Environment
+导入时：挂在 `base_link` 下的关节会烘焙成 STEP 世界坐标（与页面 FK / 拾取边一致），导出时再按 base 扣回 URDF 相对量。
 
-| Variable | Meaning |
+### 4. 智谱建议（可选，旧路径）
-|----------|---------|
-| `ZHIPU_API_KEY` | Required for LLM propose |
-| `ZHIPU_MODEL` | Default `glm-4-plus` |
-| `HOST` / `PORT` | FastAPI default `127.0.0.1:8787` |
 
-## Layout
+需后端已配置 `ZHIPU_API_KEY`。左侧曾有「智谱建议关节」入口；现主流程以手调 JSON 为准。A7 金标逻辑仍在 `app/services/a7_gold.py`。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `ZHIPU_API_KEY` | 仅智谱 propose 需要；勿提交 `.env` |
+| `ZHIPU_MODEL` | 默认 `glm-4-plus` |
+| `HOST` / `PORT` | FastAPI，默认 `127.0.0.1:8787` |
+
+## 目录
 
 ```
-frontend/                 # step2urdf Vue/Vite app (+ Zhipu panel)
+frontend/                 # step2urdf Vue/Vite
-  UPSTREAM.md
+  public/handtuned_arm.json
-app/
+  src/.../applyHandtunedJson.ts
-  main.py                 # FastAPI: /api/propose, CORS, /legacy
+data/handtuned_arm.json   # 手调源数据（与 public 同步）
-  services/zhipu.py       # Zhipu chat → RobotDraft JSON
+app/                      # FastAPI（智谱 / health / legacy）
-  services/profiles.py    # a7 / generic seed grouping
+requirements.txt
-  static/                 # legacy MVP UI (/legacy)
-data/jobs/                # optional server-side parse jobs
 ```
 
-## Production-ish (optional)
+## 生产构建（可选）
 
 ```bash
 cd frontend && pnpm build
-# FastAPI serves frontend/dist at / when present
+python -m app.main   # 若存在 frontend/dist，可由 FastAPI 托管
-python -m app.main
 ```
 
-## Known gaps
+## 注意
 
-- Joint **origin/axis** from Zhipu are estimates — always refine in the 3D viewer before trusting Export.
+- Solid 绑定按 **名称**（`Solid_N`）；换 STEP 或剖分结果不同会导致部分未绑定。
-- Solid binding matches by **part name**; rename mismatches need manual bind.
+- 手调 JSON 的 xyz 是相对父连杆的米制数值；不要在导入后再整体 ×1000。
-- Server `/api/export` is legacy; prefer the UI exporter.
+- 服务端 `/api/export` 为遗留接口；请用页面 **导出 URDF**。
-- Deep auto-snap from LLM to OCCT edge features is not implemented yet.