todo: "做个注册模块"            →     entry → l1_register → l1_login → exit
                                      ↳ 每个节点 = plan + checkpoints + 验收标准
                                      ↳ 每条边 = 类型化依赖（谁先谁后、谁验证谁）
                                      ↳ 每个状态 = 状态机强制流转（不能跳步）

npm install -g @lukawi/super-plumber

graph --version     # 输出 0.1.0 即成功
graph --help        # 查看全部 11 个命令
which graph         # 确认命令位置（Windows: where graph）

mkdir ~/my-first-graph && cd ~/my-first-graph
graph init -l "我的第一个拓扑图"

# 1. 初始化
graph init -l "用户注册模块"

# 2. 创建节点（-i id、-l 标签、--level 层级、--plan-desc 计划、--dod 完成标准可重复）
graph create-node -i l1_register -l "注册功能" -t task --level 1 \
  --plan-desc "实现邮箱+密码注册" --dod "注册接口可用" --dod "密码加密存储"

graph create-node -i l1_login -l "登录功能" -t task --level 1 \
  --plan-desc "实现登录与会话" --dod "登录接口可用"

# 3. 添加依赖边（l1_login 依赖 l1_register）
graph add-edge -i e1 -s l1_register -t l1_login --type depends_on

# 4. 查看状态
graph status

# 5. 校验（引用完整性 + 拓扑排序 + 环检测）
graph validate

# 6. 可视化
graph serve    # 浏览器打开 http://localhost:8934

graph init -l "用户注册模块"

entry:
  description: "开发用户注册模块，支持邮箱+密码注册与登录"
  defined_by: human
  level: 0
exit:
  description: "可用的注册/登录功能，全部测试通过"
  acceptance_criteria:
    - "注册接口可用"
    - "登录后能保持会话"
  defined_by: human
  level: 0

# 主干节点：带计划、完成标准、负责人
graph create-node -i l1_register -l "注册功能" -t task --level 1 \
  --plan-desc "实现邮箱+密码注册：接口、校验、存储" \
  --dod "注册接口返回 200" --dod "密码 bcrypt 加密" --dod "重复邮箱报错" \
  --assigned-to "backend-agent"

# 子节点：细化到可执行粒度
graph create-node -i l2_reg_api -l "注册接口" -t task --level 2 \
  --plan-desc "POST /register 接口" --dod "接口测试通过"

graph create-node -i l2_reg_store -l "用户存储" -t task --level 2 \
  --plan-desc "用户表 + 密码加密" --dod "存储层测试通过"

graph update-node -i l1_register \
  --add-checkpoint '{"id":"cp1","label":"接口开发"}' \
  --add-checkpoint '{"id":"cp2","label":"密码加密"}' \
  --add-checkpoint '{"id":"cp3","label":"联调测试"}'

# 查看节点完整内容
graph update-node -i l1_register --show

graph add-edge -i e1 -s l1_register -t l1_login --type depends_on
graph add-edge -i e2 -s l2_reg_api -t l2_reg_store --type depends_on
graph add-edge -i e3 -s l2_reg_api -t l1_register --type validates   # 验证关系
graph add-edge -i e4 -s l1_register -t l1_login --type shares_context # 共享上下文

graph validate

✅ 节点: 3 个
✅ 边: 4 条
✅ 拓扑排序: 3 节点通过
✅ 循环检测: 无环路
📊 校验结果: 0 错误, 0 警告

# 状态机：pending → ready → running → passed
graph update-status -i l1_register -s ready      # 前置完成，进入待执行
graph update-status -i l1_register -s running    # 认领（claim）：记录开始时间（记录执行者需 MCP 传 claim_by）
graph update-status -i l1_register -s passed     # 完成

# 试试非法跳步——会被状态机拦住：
graph update-status -i l1_login -s running
# ❌ Invalid transition: pending → running. Allowed: [ready, cancelled]

// graph_update_checkpoint: { node_id: "l1_register", checkpoint_id: "cp1", status: "passed" }
// graph_update_execution_report: { node_id: "l1_register", summary: "注册功能完成", artifacts: ["dist/register.js"] }

SCRIPTS=~/.pi/agent/skills/plumber-flow/scripts

# 认领 ready 节点（记录 claim_by + started_at；非 ready 节点会被状态机拦截）
node $SCRIPTS/graph-claim.mjs l1_register backend-agent

# 每完成一个检查点就上报一次（报告完的进度不会丢）
node $SCRIPTS/graph-checkpoint.mjs l1_register cp1 passed

# 交付交接单（summary + artifacts + blockers + notes）
node $SCRIPTS/graph-report.mjs l1_register "注册功能完成" "dist/register.js,test/register.test.js" "" "密码加密采用 bcrypt"

graph export --mermaid -o flow.mmd    # 导出 Mermaid 流程图
graph serve                           # 打开 http://localhost:8934 看力导向图

pending ──► ready ──► running ──► passed ──► blocked
                     │   │
                     │   └──► failed ──► pending   （重试，attempts 累加）
                     ▼
              cancelled（终止态）
        blocked ──► ready / failed / cancelled

graph-mcp

{
  "mcpServers": {
    "super-plumber": {
      "command": "graph-mcp"
    }
  }
}

{
  "mcp": {
    "super-plumber": {
      "type": "local",
      "command": ["graph-mcp"],
      "enabled": true
    }
  }
}

graph serve
# 打开 http://localhost:8934

.graph/                    # 运行时目录（graph init 生成，已在 .gitignore）
├── graph.yaml             # 图定义：入口/出口/根上下文 + 节点/边引用列表
├── nodes/*.yaml           # 节点文件：plan / checkpoints / expected_outcome / execution_report
├── edges/*.yaml           # 边文件：source / target / type / contract
├── snapshots/             # 版本快照（预留）
└── index/                 # 派生索引（graph.json / meta.json，可删可重建）

# 从源码构建
git clone https://github.com/LUKAWI/super-plumber
cd super-plumber
npm install
npm run build && npm --prefix web-ui run build

# 测试（96 个用例：状态机/拓扑/CLI/MCP 协议）
npm test

# 本地链接全局（开发调试用）
npm link
graph --version

Tests: 96/96 ✅ | CLI: 11 命令 | MCP: 9 工具 | 状态机: 7 态 14 转换 | 边类型: 7 种 | Web UI: Svelte 5 + D3.js