OpenBrep

<p align="center">
  <img src="assets/logo.png" width="1525" alt="logo">
</p>

# OpenBrep

## 快速开始

1. 普通用户：从 [GitHub Releases](https://github.com/byewind1/openbrep/releases/latest) 下载 `OpenBrep-*-macOS.zip` 或 `OpenBrep-*-Windows.zip`
2. 解压后运行 `OpenBrep`
3. 命令行 / 开发者用户再使用 `git clone` 或 `pipx` 安装


[简体中文](README.zh-CN.md) | English

**OpenBrep — 面向 ArchiCAD 高阶用户和 GDL 开发者的 AI 工作台。编译验证、知识驱动、资产可追溯。**

> **Code Your Boundaries**

> 正式发布版本 v0.6.11 — macOS 安装包修复：补齐 Streamlit 冻结包前端资源与隐藏导入，并保留包级 smoke / browser smoke 验证能力。

---

## 问题与解法

你用 AI 写了一段 GDL 代码，想在 ArchiCAD 里测试。传统路径：

```
打开库对象编辑器 → 手动填参数 → 切 5 个 Script 窗口 → 粘代码 → 编译
```

**openbrep 把这个流程压缩到：**

```
描述需求（中文/英文皆可）→ AI 生成并填入脚本框 → 一键编译 → .gsm 拖入 ArchiCAD
```

或者导入已有 .gsm 文件，让 AI 帮你 debug、重构、加参数。

---

## 安装与启动

### 推荐：下载桌面包（普通用户）

访问 [GitHub Releases](https://github.com/byewind1/openbrep/releases/latest)，下载对应系统的压缩包：

- macOS：`OpenBrep-free-macOS.zip`
- Windows：`OpenBrep-free-Windows.zip`

Current macOS package compatibility: Apple Silicon only (`arm64`, M1/M2/M3/M4), macOS 14 Sonoma or later. Intel Mac is not covered by the current macOS zip.

On macOS, unzip it, open the `OpenBrep` folder, and double-click `OpenBrep.command`. On Windows, unzip it and run `OpenBrep.exe`. This path does not require users to learn `git clone`, `git pull`, or manual Python dependency installation first.

### 命令行安装（高级用户）

OpenBrep 是 Python 应用。正式发布到 PyPI 后，推荐用隔离工具安装：

```bash
pipx install "openbrep[ui]"
obr
```

或使用 uv：

```bash
uv tool install "openbrep[ui]"
obr
```

### 源码安装（开发者）

```bash
git clone https://github.com/byewind1/openbrep.git
cd openbrep
bash install.sh
obr
```

> 如果 `obr` 不可用，重开终端或运行 `source ~/.zshrc`
> 
> `obr` 默认仅在本机 `http://localhost:8501` 启动 UI，不会自动打开浏览器；请用你的常用浏览器手动访问或直接使用已收藏地址。

### 源码升级

```bash
cd openbrep
git pull origin main
bash install.sh   # 有新依赖时重跑，无害
obr
```

> 个人配置（config.toml / API Key）升级后保持不变，无需重新配置。

需要 Python 3.10+。真实编译（.gsm 输出）需要安装 ArchiCAD 28/29。

---

## CLI 模式

面向 GDL 开发者的终端工作流。
```bash
pip install -e "."

# 创建对象
openbrep create "做一个宽600mm深400mm的书架，4个层板" --output ./my_shelf

# 修改对象（基于磁盘上的 HSF 项目目录）
openbrep modify ./my_shelf "把层板改成6个，间距均匀分布"

# 查看帮助
openbrep --help
```

每次修改都读取完整项目状态，精确修改而非重写，自动编译验证。

> 开发者说明：如果你当前使用的是 `pip install -e "."` / `pip install -e ".[ui]"` 的 editable install，修改仓库源码后通常会立即生效，不需要重新安装；只有在变更 `pyproject.toml`、依赖、命令入口（如 `obr` / `obrcli`）或打包规则时，才建议重新安装一次。

---

## 功能一览

### 编辑器栏（左侧）

| 功能 | 说明 |
|---|---|
| 📂 **导入** | 拖入 `.gdl` / `.txt` / `.gsm` 文件；.gsm 经 LP_XMLConverter 解包为 HSF |
| 🔧 **编译 GSM** | HSF → .gsm，支持 Mock 模式（无需 ArchiCAD）和真实 LP_XMLConverter 编译 |
| 📥 **提取** | 从 AI 对话中扫描代码块，自动识别脚本类型（3D/2D/Param...）并写入编辑器 |
| **脚本标签页** | 6 个独立脚本框（3D / 2D / Master / Param / UI / Properties），每个均支持 streamlit-ace 语法高亮和全屏编辑 |
| **参数表** | 查看、手动添加参数；AI 生成的 paramlist.xml 可一键写入 |
| 🔍 **语法检查** | IF/ENDIF、FOR/NEXT、ADD/DEL 匹配，3D 末尾 END，2D 必须有 PROJECT2 |

### AI 对话栏（右侧）

| 功能 | 说明 |
|---|---|
| **🖼️ 图片即意图** | 上传建筑构件图片 → AI 识别几何、提取参数化维度 → 直接生成 GDL 脚本，无需文字描述 |
| **自然语言创建** | "做一个宽 600mm 深 400mm 的书架，4 个层板" → 自动生成全部脚本和参数 |
| **自然语言修改** | 已有项目时："把层板改成 5 个，材质加一个 shelfMat 参数" → AI 理解上下文按需修改 |
| **Debug 模式** | 包含 "为什么"/"检查"/"修复" 等词时，自动注入全部脚本上下文；AI 可以给出分析文字 + 代码修复 |
| **确认写入** | 已有项目的 AI 修改不会自动覆盖，消息下方出现 [✅ 写入] [❌ 忽略] 按钮 |
| **对话操作栏** | 每条 AI 消息下方：👍 👎 📋 🔄（好评/差评/复制/重新生成） |
| **多模型支持** | Claude / GLM / GPT / DeepSeek / Gemini / Ollama 本地，侧边栏切换 |

---

## 支持的 LLM

| 提供商 | 模型 | 说明 |
|---|---|---|
| Anthropic | claude-haiku / sonnet / opus | 推荐首选 |
| 智谱 | glm-5 / glm-4-flash | 国内可用，性价比高 |
| OpenAI | gpt-4o / gpt-4o-mini / o3-mini | |
| DeepSeek | deepseek-chat / deepseek-reasoner | |
| Google | gemini-2.5-flash / pro | |
| Ollama | qwen2.5 / qwen3 / deepseek-coder | 本地，无需 API Key |

---

## GSM 导入（AC29 支持）

侧边栏选择 LP_XMLConverter 模式，配置路径后可导入 .gsm 文件进行修改：

```
# ArchiCAD 29 路径（LP_XMLConverter 内嵌于 app bundle）
/Applications/GRAPHISOFT/Archicad 29/Archicad 29.app/Contents/MacOS/
  LP_XMLConverter.app/Contents/MacOS/LP_XMLConverter
```

也可直接在 `config.toml` 中写入，启动后自动读取。

---

## HSF 格式简介

.gsm 文件解压后是这样的目录结构（HSF）：

```
MyBookshelf/
├── libpartdata.xml     ← 对象身份（GUID、版本）
├── paramlist.xml       ← 参数定义（强类型）
├── ancestry.xml        ← 对象分类
└── scripts/
    ├── 1d.gdl          ← Master Script
    ├── 2d.gdl          ← 2D 平面符号
    ├── 3d.gdl          ← 3D 几何模型
    ├── vl.gdl          ← 参数逻辑（VALUES/LOCK）
    └── ui.gdl          ← 自定义界面
```

openbrep 以 HSF 为原生格式，每个脚本独立处理，AI 只读取与当前任务相关的脚本（减少 context 占用）。

---

## 项目结构

面向维护者和 AI 开发工具的架构规范见：

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- [docs/AI_DEVELOPMENT_GUIDE.md](docs/AI_DEVELOPMENT_GUIDE.md)
- 中文版：[docs/ARCHITECTURE.zh-CN.md](docs/ARCHITECTURE.zh-CN.md)、[docs/AI_DEVELOPMENT_GUIDE.zh-CN.md](docs/AI_DEVELOPMENT_GUIDE.zh-CN.md)

```
openbrep/
├── openbrep/
│   ├── hsf_project.py       # HSF 数据模型
│   ├── paramlist_builder.py # paramlist.xml 强类型生成
│   ├── gdl_parser.py        # .gdl → HSFProject
│   ├── compiler.py          # LP_XMLConverter 封装
│   ├── core.py              # Agent 主循环 + generate_only
│   ├── llm.p

... (truncated)