220 lines
10 KiB
Markdown
220 lines
10 KiB
Markdown
---
|
||
name: fpga-goldenref-flow
|
||
description: >
|
||
Run the fpga-goldenref-flow LangGraph design-and-execution workflow for the
|
||
project at E:\LangGraph_Design\fpga-goldenref-flow. Drives the compiled graph
|
||
in-process (NO langgraph dev server) via a persistent SQLite checkpointer:
|
||
submits a run, surfaces the human-review interrupt (plans are summarised in the
|
||
Claude conversation for the user to approve/reject), resumes execution, and
|
||
displays the final summary — all within the Claude session.
|
||
|
||
Trigger whenever the user says any of: "run FPGA flow", "start FPGA workflow",
|
||
"invoke fpga-goldenref-flow", "run goldenref flow", "启动 FPGA 工作流",
|
||
"运行 FPGA 设计流程", "跑一下 FPGA flow", "run the FPGA agent",
|
||
"execute the FPGA design pipeline", or any request to interact with the
|
||
LangGraph agent inside this project. Also trigger when the user wants to approve
|
||
or reject the generated plan, or resume a paused fpga-goldenref-flow run.
|
||
---
|
||
|
||
## 驱动方式：进程内驱动（无 dev server）
|
||
|
||
工作流是一张 LangGraph 图，由 `scripts\run_fpga_local.py` **在本进程内**驱动
|
||
（已移除 langgraph dev server 路径）。直接 `build_graph()` + **SqliteSaver 持久化**
|
||
驱动编译好的图，状态存在 `<output_dir>\.fpga_flow_local.sqlite`，按 `thread_id`
|
||
持久化，`start`/`resume`/`continue` 各自独立进程调用都能接续。
|
||
|
||
```powershell
|
||
conda run -n langgraph python `
|
||
"C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py" `
|
||
start --input-dir "E:\<proj>\Notes" --output-dir "E:\<proj>\fpga_runs"
|
||
```
|
||
|
||
为什么是进程内驱动：`langgraph dev` 是**内存存储的开发服务器**，对本项目这种长耗时、
|
||
多模块、反复中断续跑的执行不可靠——重启丢线程、run 队列被 cancel 残留堵成永久
|
||
`pending`、watchfiles `--reload` 自激。进程内驱动没有这些问题（无队列、无内存丢失、
|
||
无 reload），状态全部落在 SQLite。
|
||
|
||
---
|
||
|
||
## Project info
|
||
|
||
| Item | Value |
|
||
|---|---|
|
||
| Root | `E:\LangGraph_Design\fpga-goldenref-flow` |
|
||
| Conda env | `langgraph` (`C:\Users\bowei\.conda\envs\langgraph`) |
|
||
| Graph name | `fpga_goldenref_flow` (在 `langgraph.json` 里声明；进程内驱动直接 `build_graph()`) |
|
||
| Default input dir | `Notes/` (contains PR00.md, Task00.md) |
|
||
| Helper script | `C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py` |
|
||
|
||
---
|
||
|
||
## Full workflow
|
||
|
||
> **入口约束**：下面每一步都通过 helper 脚本 `run_fpga_local.py` 在 `langgraph`
|
||
> conda 环境里执行。不要直接 `import` `app.*` 在别处运行，统一走 helper 脚本以保证
|
||
> SQLite 持久化与退出码一致。
|
||
|
||
### Step 1 — Submit a new run
|
||
|
||
**Before calling the script, determine the two key paths:**
|
||
- `--input-dir` — the directory that holds the project's requirement files (e.g. `Notes/`). Use an absolute path or a path relative to the current shell's CWD.
|
||
- `--output-dir` — the directory where all generated files (task folders, plan.md, summary.md) and the run's checkpoint DB + session file will be written. **This must be inside the caller's project directory, not inside the workflow development directory.** Use the absolute path to the project being worked on, e.g. `E:\MyProject\fpga_runs`.
|
||
|
||
Run the helper script using the `langgraph` conda environment:
|
||
```powershell
|
||
conda run -n langgraph python `
|
||
"C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py" `
|
||
start `
|
||
--input-dir "E:\<project-path>\Notes" `
|
||
--output-dir "E:\<project-path>\fpga_runs"
|
||
```
|
||
|
||
Optional flag: `--prompt "additional context"` if the user supplied extra requirements.
|
||
|
||
> **Rule:** always pass `--output-dir` as an absolute path pointing into the calling project.
|
||
> If omitted, files fall back to `<input-dir-parent>/runs` which may or may not be in the project directory.
|
||
|
||
The script prints `[INFO] Thread : <id>` and `[INFO] Output dir : <path>` (note them
|
||
for resume), then node-level progress (`-> node_name`) as the graph runs.
|
||
|
||
**Exit codes:**
|
||
| Code | Meaning |
|
||
|---|---|
|
||
| 0 | Workflow completed — jump to Step 4 |
|
||
| 1 | Error — read the output, diagnose, report to user |
|
||
| 2 | An interrupt fired — read the `[INTERRUPT]` payload's `action` and branch (see below) |
|
||
| 3 | Codex unavailable — workflow stopped (no downgrade). Resume from checkpoint later with `continue`. |
|
||
|
||
**Two interrupts fire in order — branch on `action` in the `[INTERRUPT]` payload:**
|
||
1. `"action": "select_plan_model"` — first, right after decomposition → **Step 1.5**.
|
||
2. `"action": "confirm_plan"` — later, after plans are generated → **Step 2**.
|
||
|
||
### Step 1.5 — Select plan model (first interrupt)
|
||
|
||
When the `[INTERRUPT]` payload has `"action": "select_plan_model"`, the workflow has
|
||
finished decomposition and is waiting for the user to pick the Claude model used to
|
||
**author/revise** the plans (review stays on Codex). The payload includes `default`
|
||
(Opus 4.8) and the decomposition overview.
|
||
|
||
Ask the user which model (use AskUserQuestion), offering **Opus 4.8 (default/recommended)**,
|
||
**Fable 5**, **Sonnet 4.6**. Then resume with the choice:
|
||
```powershell
|
||
conda run -n langgraph python `
|
||
"C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py" `
|
||
resume --output-dir "E:\<project-path>\fpga_runs" `
|
||
--plan-model opus # or: fable | sonnet | a full id like claude-opus-4-8
|
||
```
|
||
The workflow then generates plans with that model and stops again at the
|
||
`confirm_plan` interrupt (exit 2) → go to Step 2.
|
||
|
||
### Step 2 — Human review (Claude reads plans, asks user)
|
||
|
||
When the script exits with code 2 (`confirm_plan`) it prints:
|
||
- `[INTERRUPT]` — the raw interrupt payload (may include a message)
|
||
- `[PLAN] <task_id>: <path>` — absolute paths to generated plan files
|
||
- `[REQ] <task_id>: <path>` — absolute paths to requirement files
|
||
|
||
For each plan path, read the file:
|
||
```powershell
|
||
Get-Content "<plan_path>" -Encoding utf8
|
||
```
|
||
|
||
Then **summarise the plan for the user** in 3–5 bullet points per task and ask:
|
||
|
||
> "FPGA 工作流已生成以下设计计划，请确认是否批准继续执行：
|
||
> …bullet points…
|
||
> **批准（继续执行）还是拒绝（请说明需要修改的地方）？**"
|
||
|
||
Wait for the user's answer before proceeding to Step 3.
|
||
|
||
### Step 3 — Resume the workflow
|
||
|
||
> **并发安全(MANDATORY)**：`resume` 必须绑定到本次运行的工程，绝不能依赖全局会话文件。
|
||
> **总是带上 `--output-dir`**（与 `start` 时完全相同的绝对路径），这样多个工程并发时
|
||
> 各自的会话文件与 SQLite 互不串。等价地，也可以用 `--thread-id "<start 打印的 Thread id>"`
|
||
> 直接指定线程，完全绕过会话文件（最稳）。省略两者只在「同一时间只有一个工程在跑」时才安全。
|
||
|
||
**If the user approves:**
|
||
```powershell
|
||
conda run -n langgraph python `
|
||
"C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py" `
|
||
resume --output-dir "E:\<project-path>\fpga_runs"
|
||
```
|
||
(Default behaviour is approved — no extra flag needed.)
|
||
|
||
**If the user rejects:**
|
||
```powershell
|
||
conda run -n langgraph python `
|
||
"C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py" `
|
||
resume --output-dir "E:\<project-path>\fpga_runs" `
|
||
--rejected --feedback "<user feedback verbatim>"
|
||
```
|
||
|
||
> Use the **same `--output-dir`** you passed at `start` (it is printed on the
|
||
> `[INFO] Output dir :` line). Alternatively pass `--thread-id "<id>"` from the
|
||
> `[INFO] Thread :` line at start.
|
||
|
||
After rejection the workflow loops back to plan generation; you will likely hit
|
||
exit code 2 again with new plans — repeat Step 2.
|
||
|
||
> **Codex 不可用 (exit 3)**：若任一 resume/start 以 exit 3 退出，说明 codex(gpt-5.5)
|
||
> 额度被占满，工作流已停在断点（状态已存 SQLite，不降级）。等 codex 空出来后从断点续跑：
|
||
> ```powershell
|
||
> conda run -n langgraph python `
|
||
> "C:\Users\bowei\.claude\skills\fpga-goldenref-flow\scripts\run_fpga_local.py" `
|
||
> continue --output-dir "E:\<project-path>\fpga_runs"
|
||
> ```
|
||
|
||
### Step 4 — Show results
|
||
|
||
When the script exits with code 0 it prints `[SUMMARY]` followed by the contents
|
||
of `<output-dir>\summary.md`. Present this to the user.
|
||
|
||
If the user wants to inspect a specific task's plan or requirement:
|
||
```
|
||
<output-dir>\<task_id>\plan.md
|
||
<output-dir>\<task_id>\requirement.md
|
||
```
|
||
|
||
The `output-dir` is the value passed to `--output-dir` at start time (printed in the
|
||
`[INFO] Output dir :` line) and is also stored in the session file.
|
||
|
||
---
|
||
|
||
## Session state (per-project — concurrency safe)
|
||
|
||
Between `start` and `resume` the helper writes a small session file **inside the
|
||
run's own `output_dir`**, so concurrent projects never share it:
|
||
```
|
||
<output_dir>\.fpga_flow_session.json
|
||
```
|
||
It holds `thread_id` and `output_dir`. `resume`/`continue` locate it via the
|
||
`--output-dir` you pass (hence Step 3 requires it). It is deleted automatically when
|
||
the run completes successfully.
|
||
|
||
**Isolation guarantees for concurrent projects:**
|
||
- Graph state (`MainState`/`FpgaState`, checkpoints) is isolated by `thread_id`
|
||
inside that run's own `<output_dir>\.fpga_flow_local.sqlite` — different projects
|
||
use different output dirs and different DBs, and cannot see each other's state.
|
||
- Generated files are isolated by `output_dir`.
|
||
- The session pointer is isolated by living inside each `output_dir`. **Always
|
||
pass `--output-dir` (or `--thread-id`) to `resume`** so it never reads another
|
||
project's session.
|
||
|
||
To abandon a paused run and start fresh, delete that project's
|
||
`<output_dir>\.fpga_flow_session.json` (and, if you want a clean checkpoint,
|
||
`<output_dir>\.fpga_flow_local.sqlite`) before calling `start`.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Fix |
|
||
|---|---|
|
||
| `ModuleNotFoundError` | `conda run -n langgraph pip install langgraph langgraph-checkpoint-sqlite` |
|
||
| `No session file found` | Must call `start` before `resume` (or pass `--thread-id`) |
|
||
| Empty `[PLAN]` lines | Look in `<output_dir>\` for `plan.md` files under each `<task_id>` folder |
|
||
| `interrupted` never advances | Make sure `--rejected` flag is accompanied by `--feedback` text |
|
||
| exit 3 (Codex 不可用) | Wait for codex quota, then `continue --output-dir <same path>` from the checkpoint |
|
||
| Stale state after editing `app\*` | In-process driver imports fresh each run; just re-run `start`/`continue`. To reset a thread, delete that run's `.fpga_flow_local.sqlite`. |
|