# opagent

## PAM Deploy Agent

本仓库正在把原有 `PAM_AUTO_DEPLY_SKILL.md` + `deploy.sh` / `deploy.ps1` 的组合，重构为一个 LangGraph-style 的 PAM 智能部署 Agent。

当前已加入 `pam_deploy_graph` Python 包，用于先落地 Agent Runtime 的核心骨架：

- PAM_HOME action 固定通过 `deploy.sh` / `deploy.ps1` 调用。
- PAM_NODE action 可通过 MCP runner 调用。
- 默认执行策略为 `hybrid_node_mcp`，即 HOME 脚本 action + NODE MCP。
- 离线策略为 `script_only`，全部 action 走脚本 action。
- `langgraph` 当前作为可选依赖；本地未安装时，核心 Agent、runner、router 和 parser 仍可独立测试。

## 当前代码骨架

```text
pam_deploy_graph/
  agent.py             # Agent runtime，参数归一化、预演、fake 全局流程
  action_router.py     # 按 action 路由到脚本、MCP 或 fake runner
  script_runner.py     # deploy.sh / deploy.ps1 action 调用封装
  mcp_runner.py        # PAM_NODE MCP runner 协议与 action -> tool 映射
  fake_runner.py       # 测试用 runner，不访问真实环境
  output_parser.py     # 解析 key=value、MCP JSON、待确认回滚标记
  skill_policy.py      # 从 PAM_AUTO_DEPLY_SKILL.md 加载 Skill 策略
  config_writer.py     # 生成脚本 action 所需 config 文件
  checkpoint_store.py  # 业务 checkpoint JSON 读写
  params_loader.py     # 读取 JSON 或 config.txt 风格参数文件
  graph.py             # 可选 LangGraph 集成入口
  cli.py               # CLI 入口

tests/
  test_action_router.py
  test_output_parser.py
  test_params_loader.py
  test_script_runner.py
  test_skill_policy.py
```

## 当前进度

已完成：

- 建立 Python 工程骨架和 `pyproject.toml`。
- 实现 `hybrid_node_mcp` 路由规则：PAM_HOME 走脚本 action，PAM_NODE 走 MCP。
- 实现 `script_only` 路由规则：所有 action 走脚本 action。
- 实现脚本 action 命令构造，避免调用脚本主流程。
- 实现 MCP runner 抽象和 PAM_NODE action 到 MCP tool 的默认映射。
- 实现脚本/MCP/fake action 结果统一为 `ActionResult`。
- 实现 `config.txt.example` 风格和 JSON 风格参数读取。
- 实现 fake 全局流程，便于不触碰真实环境地验证 Agent 路由。
- 添加基础测试，当前 `10 passed`。

未完成：

- 尚未接入真实 MCP client。
- 尚未安装并接入真实 LangGraph `StateGraph` 主图。
- 尚未实现 LLM 结构化意图识别、参数抽取和计划生成。
- 尚未实现人工确认 interrupt、断点续跑完整图流程和单 IP 子流程。
- 尚未执行真实脚本 action 或真实 PAM_NODE MCP 调用。

## 使用方式

预演：

```bash
python -m pam_deploy_graph.cli preview --config doc_scripts/config.txt.example --strategy fake
```

fake 全局流程验证：

```bash
python -m pam_deploy_graph.cli run-global --config doc_scripts/config.txt.example --strategy fake --confirm
```

测试：

```bash
pytest -q
```

## 下一步建议

1. 接入真实 PAM_NODE MCP client，实现 `McpToolClient.call_tool()`。
2. 用 fake runner 补齐完整部署主流程和单 IP 子流程测试。
3. 引入 LangGraph，把当前 Agent 节点接入 `StateGraph`。
4. 增加人工确认节点：参数确认、IP 范围确认、回滚确认。
5. 增加 LLM structured output：意图识别、参数抽取、部署计划、失败解释。
6. 完善 checkpoint 恢复：全局步骤跳过、成功 IP 跳过、pending rollback 恢复。
7. 在测试环境中做 smoke：HOME 脚本 `get-token/get-node-url` + NODE MCP `get-online-ips`。