# LangGraphStudy

**Repository Path**: laolin/lang-graph-study

## Basic Information

- **Project Name**: LangGraphStudy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 结构模型审查 LangGraph Starter

这是一个面向结构工程软件开发场景的 LangGraph 初始项目。它不是普通聊天机器人，而是一个可运行、可暂停、可恢复、可测试的“结构模型审查与受控修改工作流”。

项目默认使用规则解析器和本地 JSON 模型，不需要任何 LLM API Key。完成 LangGraph 基础学习后，可以逐步接入 OpenAI 结构化输出、AutoCAD/ObjectARX IPC、真实结构检查算法和 .NET 工具窗口。

## 1. 已包含的能力

- `StateGraph`、显式节点和条件边；
- 通过条件边循环执行检查计划；
- 使用 Reducer 累积 `findings`、`events` 和 `errors`；
- 使用运行时 `context_schema` 传递基础设施配置；
- 使用 SQLite Checkpointer 持久化 thread；
- 使用 `interrupt()` 在写模型前暂停；
- 使用 `Command(resume=...)` 恢复审批流程；
- 模型工作副本、写前快照、版本冲突检查和幂等 `operation_id`；
- 修改后重新执行检查并验证后置条件；
- Markdown 审查报告；
- 可选 OpenAI 结构化任务解析器；
- LangGraph Studio 配置；
- 单元测试、图路径测试和持久化 CLI 演示。

当前模拟检查包括：

1. 柱中心与最近轴线偏差；
2. 短梁几何跨度；
3. 墙柱包围盒近似重叠。

当前自动修改动作仅包括柱偏位修正。短梁和墙柱重叠通常涉及设计意图，因此第一版只报告，不自动修改。

> 本项目中的结构算法是学习用简化算法，不能直接作为正式结构设计或审查依据。

---

## 2. 环境要求

- Python 3.11 或更高版本；
- 推荐在独立虚拟环境中安装；
- 默认运行不需要网络和 API Key。

项目创建和测试时采用：

- LangGraph `1.2.9`；
- LangGraph SQLite Checkpoint `3.1.0`；
- Pydantic 2.x。

`pyproject.toml` 使用主版本兼容范围，便于后续升级；生产项目应进一步维护锁文件和升级回归测试。

---

## 3. 安装

### Windows PowerShell

```powershell
cd langgraph-structure-review-starter
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"
```

### Bash

```bash
cd langgraph-structure-review-starter
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
```

验证安装：

```bash
pytest
```

或执行完整质量检查：

```powershell
.\scripts\verify.ps1
```

Bash 使用 `./scripts/verify.sh`。交付时的实际验证记录见
`docs/05-运行验证记录.md`。

---

## 4. 第一次运行：只读审查

```bash
structure-review run \
  --model data/demo_model.json \
  --request "全面检查 3F，只检查不要修改。" \
  --thread-id demo-read-only
```

Windows PowerShell 可写成单行：

```powershell
structure-review run --model data/demo_model.json --request "全面检查 3F，只检查不要修改。" --thread-id demo-read-only
```

运行完成后主要输出位于：

```text
.runtime/
├── checkpoints.sqlite
└── threads/
    └── demo-read-only/
        ├── source_model.json
        ├── working_model.json
        └── report.md
```

- `source_model.json`：首次运行时保存的输入快照；
- `working_model.json`：本 thread 隔离的工作副本；
- `report.md`：最终审查报告；
- `checkpoints.sqlite`：LangGraph 的 thread 状态和检查点。

---

## 5. 人工审批、中断和恢复

启动允许修改的任务：

```bash
structure-review run \
  --model data/demo_model.json \
  --request "检查 3F 柱偏位，允许修改。" \
  --thread-id demo-approval
```

图运行到 `request_approval` 节点后会暂停，终端会显示中断载荷和待审批动作。此时进程可以退出，状态已经保存在 SQLite 中。

全部批准：

```bash
structure-review resume \
  --thread-id demo-approval \
  --decision approve_all
```

全部拒绝：

```bash
structure-review resume \
  --thread-id demo-approval \
  --decision reject_all \
  --comment "暂不修改模型"
```

部分批准：

```bash
structure-review resume \
  --thread-id demo-approval \
  --decision approve_selected \
  --approve-action action_xxxxxxxxxxxxxxxx
```

审批时修改动作参数，可新建 `edits.json`：

```json
{
  "action_xxxxxxxxxxxxxxxx": {
    "dx_mm": -20,
    "dy_mm": -20
  }
}
```

然后执行：

```bash
structure-review resume \
  --thread-id demo-approval \
  --decision approve_all \
  --edits-file edits.json
```

人工只能修改动作参数，不能借审批接口改变工具名、构件 ID 或预期模型版本。

---

## 6. 查看持久化状态

```bash
structure-review inspect --thread-id demo-approval
```

输出包括：

- 当前完整状态；
- 下一待执行节点；
- 检查点元数据；
- 当前任务信息。

一个 `thread_id` 应对应一个独立工作任务。不要用同一个 thread ID 启动无关的新任务；新任务应使用新 ID。

---

## 7. 导出图结构

```bash
structure-review diagram --output structure_review.mmd
```

生成 Mermaid 定义，可粘贴到支持 Mermaid 的 Markdown 编辑器中查看。
项目也已附带交付时生成的 `docs/structure_review_graph.mmd`。

核心拓扑如下：

```mermaid
flowchart TD
    START --> initialize_task
    initialize_task -->|有效| load_model
    initialize_task -->|失败| handle_failure
    load_model -->|有效| create_check_plan
    load_model -->|失败| handle_failure
    create_check_plan --> execute_next_check
    execute_next_check -->|仍有检查| execute_next_check
    execute_next_check -->|全部完成| analyze_findings
    analyze_findings --> create_action_proposals
    create_action_proposals -->|只读或无动作| generate_report
    create_action_proposals -->|允许修改且有动作| request_approval
    request_approval -->|批准| apply_changes
    request_approval -->|拒绝| generate_report
    apply_changes -->|成功| verify_changes
    apply_changes -->|失败| handle_failure
    verify_changes --> generate_report
    handle_failure --> generate_report
    generate_report --> END
```

---

## 8. 运行 Python 示例

只读：

```bash
python examples/run_read_only.py
```

中断与恢复：

```bash
python examples/run_with_approval.py
```

观察节点增量输出：

```bash
python examples/run_streaming.py
```

---

## 9. 可选：使用 OpenAI 解析自然语言任务

安装可选依赖：

```bash
pip install -e ".[llm]"
```

复制环境变量示例：

```bash
# Windows
copy .env.example .env

# Bash
cp .env.example .env
```

填写：

```text
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-5-mini
```

执行：

```bash
structure-review run \
  --planner openai \
  --model data/demo_model.json \
  --request "检查三层柱偏位和短梁，柱偏位容差 15mm，不要修改。" \
  --thread-id demo-openai
```

LLM 只负责把请求转换为 `ReviewTask`；几何判断、权限判断、版本校验和真实写操作仍由确定性代码完成。

---

## 10. 可选：LangGraph Studio

安装：

```bash
pip install -e ".[studio]"
```

复制 `.env.example` 为 `.env`。Studio 需要 LangSmith API Key；不希望上传 trace 时保持：

```text
LANGSMITH_TRACING=false
```

启动：

```bash
langgraph dev
```

`langgraph.json` 已将图入口配置为：

```text
src/structure_review_agent/graph.py:graph
```

CLI 与 Studio 的持久化机制不同：

- CLI 明确使用本地 SQLite Checkpointer；
- Agent Server/Studio 负责其运行环境中的 thread 存储。

---

## 11. 目录说明

```text
src/structure_review_agent/
├── graph.py                 # 图拓扑与 Studio 入口
├── state.py                 # LangGraph State 与 Reducer
├── context.py               # context_schema 运行时配置
├── schemas.py               # 任务、Finding、Action、Approval 数据协议
├── routing.py               # 条件边路由
├── cli.py                   # SQLite 持久化运行与恢复
├── domain/
│   └── model.py             # 简化结构模型 DTO
├── nodes/
│   ├── task_nodes.py        # 初始化、加载模型、生成计划
│   ├── check_nodes.py       # 检查循环、汇总、复核
│   ├── action_nodes.py      # 建议、interrupt、写操作
│   └── report_nodes.py      # 失败收敛与报告
├── services/
│   ├── planners.py          # 规则/OpenAI 任务解析器
│   ├── action_proposer.py   # Finding → ProposedAction
│   └── report_builder.py    # Markdown 报告
└── tools/
    ├── checks.py            # 确定性检查算法
    ├── registry.py          # 工具白名单/注册表
    └── repository.py        # 工作副本、版本、幂等写入
```

主要扩展边界：

- 新检查：增加 `CheckType`、检查函数并注册到 `CHECK_REGISTRY`；
- 新写动作：增加动作协议、Repository 执行函数和审批参数白名单；
- 新模型来源：替换 `JsonModelRepository` 或抽象为 Protocol；
- 新 LLM：实现 `TaskPlanner` 接口；
- AutoCAD 接入：把仓储读写替换为 Python ↔ ARX IPC；
- UI：把 interrupt 载荷显示到 .NET 工具窗口，再用相同 thread ID 恢复。

---

## 12. 重要设计约束

### 状态与运行配置分离

业务状态进入 Checkpointer；运行目录、解析器类型和模型名放入 `AppContext`。数据库连接和 LLM 客户端不进入 State。

### LLM 不直接写模型

LLM 最多产生结构化任务或建议。真实工具只接受白名单中的领域动作，不执行自由文本、Python 代码或 AutoCAD 命令字符串。

### `interrupt()` 节点保持无前置副作用

LangGraph 恢复中断时会从中断节点开头重新执行。因此 `request_approval` 在 `interrupt()` 之前只构造可序列化载荷，不写文件、不创建不可重复记录。

### Checkpoint 不等于 CAD 事务

LangGraph 负责工作流恢复；模型一致性仍由应用层负责。本项目通过以下机制示范：

- 工作副本；
- `expected_model_version`；
- 稳定 `operation_id`；
- 写前快照；
- 原子文件替换；
- 修改后复核。

接入 AutoCAD 后，应进一步映射为 `AcDbTransaction`、文档锁、Undo Mark 和 ARX 侧幂等操作日志。

---

## 13. 建议学习顺序

1. 阅读 `state.py` 和 `graph.py`，手绘节点与状态变化；
2. 给 `demo_model.json` 增加问题，观察检查循环；
3. 在 `routing.py` 增加一个分支；
4. 修改 Reducer，理解追加状态与覆盖状态的区别；
5. 手动执行中断、退出进程、再恢复；
6. 修改审批参数，使复核失败，观察后置条件；
7. 增加一个新只读检查；
8. 增加一个新受控写动作；
9. 接入一个真实的只读 IPC 工具；
10. 最后才考虑更自由的 Agent 或多智能体结构。

更详细的练习见 `docs/02-学习练习.md`。

---

## 14. 官方参考

- LangGraph Overview: https://docs.langchain.com/oss/python/langgraph/overview
- Graph API: https://docs.langchain.com/oss/python/langgraph/graph-api
- Runtime Context: https://docs.langchain.com/oss/python/langgraph/use-graph-api
- Persistence: https://docs.langchain.com/oss/python/langgraph/persistence
- Interrupts: https://docs.langchain.com/oss/python/langgraph/interrupts
- Streaming: https://docs.langchain.com/oss/python/langgraph/streaming
- Studio: https://docs.langchain.com/oss/python/langgraph/studio