a11904b7c5
- 为 pam_deploy_graph 生产代码补充中文模块、类、函数/方法文档字符串 - 将原有英文说明和主要英文异常提示改为中文 - 新增当前整体逻辑结构流程图文档，覆盖模块结构、执行链路、action 路由、人工确认和 checkpoint 续跑 - 新增 Linux 自带运行环境打包脚本，使用 PyInstaller 生成解压即用目录和 tar.gz - 新增 Linux 打包说明，包含构建命令、运行方式、依赖说明和包大小评估 - 同步 README，补充流程图、打包方式、产物路径和大小预估 - 更新相关测试断言以匹配中文错误提示
251 lines
9.9 KiB
Markdown
251 lines
9.9 KiB
Markdown
# 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 风格参数文件
|
||
llm/ # LLM structured output 接口、真实 HTTP client、提示词、规则 fallback 和 guardrails
|
||
graph.py # LangGraph StateGraph 集成入口
|
||
mcp_client.py # MCP session/callable adapter 与 client 配置读取
|
||
interactive.py # 常驻式 CLI 对话框，会话命令、确认和续跑
|
||
cli.py # CLI 入口
|
||
|
||
tests/
|
||
test_action_router.py
|
||
test_output_parser.py
|
||
test_params_loader.py
|
||
test_script_runner.py
|
||
test_skill_policy.py
|
||
test_interactive_cli.py
|
||
|
||
docs/
|
||
current_logic_flow.md # 当前整体逻辑结构流程图
|
||
|
||
packaging/
|
||
build_linux_self_contained.sh # Linux 解压即用包构建脚本
|
||
README_linux_package.md # Linux 打包说明和包大小评估
|
||
```
|
||
|
||
## 当前进度
|
||
|
||
已完成：
|
||
|
||
- 建立 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 路由。
|
||
- 实现逐 IP 处理骨架：升级、轮询、启动、校验、日志下载。
|
||
- 实现单 IP 失败后的待回滚确认状态，不自动执行回滚。
|
||
- 实现人工确认入口：`confirm --decision approve|reject` 只处理待确认回滚。
|
||
- 实现 checkpoint 自动保存和 `resume` 续跑：全局步骤、成功 IP、单 IP 已完成 action 会跳过。
|
||
- 实现 LLM structured output 骨架：意图识别、参数抽取、部署计划生成。
|
||
- 实现 OpenAI-compatible 真实 LLM client，支持 `base_url` / `api_key` / `model` 配置。
|
||
- 固化真实 LLM 提示词：意图识别、参数抽取、部署计划生成均要求 JSON structured output。
|
||
- 增加规则 fallback `RuleBasedLlmClient`，用于本地开发和测试。
|
||
- 增加 LLM 输出 guardrails，禁止计划中出现可执行脚本命令和非法 action。
|
||
- 引入 `langgraph` 依赖，并提供 `build_langgraph()` 图工厂。
|
||
- 引入 MCP client adapter，可包装 SDK session 或普通 callable，并提供 JSON client 配置读取。
|
||
- 本地已安装 `langgraph` 和 `mcp`，并完成 LangGraph fake 全局流程 smoke。
|
||
- CLI `analyze` 输出已做敏感字段脱敏。
|
||
- 增加 `chat` 常驻式 CLI 对话框，支持自然语言分析、参数设置、执行确认、回滚确认、状态查看和续跑。
|
||
- 添加基础测试，当前本地结果为 `31 passed, 1 skipped`。
|
||
|
||
未完成：
|
||
|
||
- 尚未接入真实 MCP session；当前已把 client adapter、tool 映射和配置格式准备好。
|
||
- 尚未执行真实脚本 action 或真实 PAM_NODE MCP 调用。
|
||
|
||
## LLM 配置
|
||
|
||
默认不配置 LLM 时，`analyze` 使用本地规则 fallback。配置真实 LLM 后，会走 OpenAI-compatible `/chat/completions`：
|
||
|
||
```powershell
|
||
$env:PAM_LLM_BASE_URL="https://your-llm.example.com/v1"
|
||
$env:PAM_LLM_API_KEY="your-api-key"
|
||
$env:PAM_LLM_MODEL="your-model-name"
|
||
|
||
python -m pam_deploy_graph.cli analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境"
|
||
```
|
||
|
||
也可以直接用 CLI 参数覆盖环境变量：
|
||
|
||
```bash
|
||
python -m pam_deploy_graph.cli analyze \
|
||
--config doc_scripts/config.txt.example \
|
||
--text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境" \
|
||
--llm-base-url https://your-llm.example.com/v1 \
|
||
--llm-api-key your-api-key \
|
||
--llm-model your-model-name
|
||
```
|
||
|
||
真实 LLM 调用位置在 `pam_deploy_graph/llm/openai_compatible.py`，提示词在 `pam_deploy_graph/llm/prompts.py`。发送给 LLM 的 `base_params` 会脱敏，`CLIENT_SECRET` 不会进入 prompt；本地生成计划后仍会执行 guardrails 校验。
|
||
|
||
## MCP Client 配置
|
||
|
||
真实 MCP session 由外部接入，Agent 只依赖同步 `call_tool(name, arguments)` 接口。接入方式：
|
||
|
||
```python
|
||
from pam_deploy_graph.agent import PamDeployAgent
|
||
from pam_deploy_graph.mcp_client import SessionMcpToolClient, load_mcp_client_config
|
||
from pam_deploy_graph.mcp_runner import McpActionRunner
|
||
|
||
config = load_mcp_client_config("mcp_client.json")
|
||
client = SessionMcpToolClient(session) # session 是你接入真实 MCP 后得到的 SDK session
|
||
runner = McpActionRunner(client=client, tool_names=config.tool_names or None)
|
||
agent = PamDeployAgent(mcp_runner=runner)
|
||
```
|
||
|
||
`mcp_client.json` 示例：
|
||
|
||
```json
|
||
{
|
||
"server_name": "pam-node-prod",
|
||
"tool_names": {
|
||
"get-online-ips": "pam_get_online_ips",
|
||
"create-download-task": "pam_create_download_task",
|
||
"poll-download-progress": "pam_poll_download_progress",
|
||
"upgrade-ip": "pam_upgrade_ip",
|
||
"poll-upgrade-progress": "pam_poll_upgrade_progress",
|
||
"start-ip": "pam_start_ip",
|
||
"stop-ip": "pam_stop_ip",
|
||
"verify-ip": "pam_verify_ip",
|
||
"download-log": "pam_download_log",
|
||
"rollback-ip": "pam_rollback_ip"
|
||
}
|
||
}
|
||
```
|
||
|
||
如果不传 `tool_names`，`McpActionRunner` 会使用上面的默认 action -> tool 映射。
|
||
|
||
## 使用方式
|
||
|
||
整体逻辑结构流程图：
|
||
|
||
```text
|
||
docs/current_logic_flow.md
|
||
```
|
||
|
||
Linux 解压即用打包：
|
||
|
||
```bash
|
||
bash packaging/build_linux_self_contained.sh
|
||
```
|
||
|
||
构建产物会输出到：
|
||
|
||
```text
|
||
dist/linux_self_contained/pam-deploy-agent-linux-x86_64/
|
||
dist/linux_self_contained/pam-deploy-agent-linux-x86_64.tar.gz
|
||
```
|
||
|
||
目标机器解压后运行：
|
||
|
||
```bash
|
||
tar -xzf pam-deploy-agent-linux-x86_64.tar.gz
|
||
cd pam-deploy-agent-linux-x86_64
|
||
./run.sh --help
|
||
./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json
|
||
```
|
||
|
||
包大小以构建脚本末尾打印的 `du` 结果为准。按当前依赖估算：默认包含 MCP 依赖时压缩包约 60-110 MB、解压后约 160-300 MB；使用 `PACKAGE_EXTRAS=` 构建最小包时压缩包约 45-75 MB、解压后约 120-200 MB。
|
||
|
||
交互式对话框：
|
||
|
||
```bash
|
||
python -m pam_deploy_graph.cli chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/chat-demo.json
|
||
```
|
||
|
||
启动后可输入自然语言需求或会话命令：
|
||
|
||
```text
|
||
PAM> 请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境
|
||
PAM> preview
|
||
PAM> set VERSION_NUMBER=2.0.6
|
||
PAM> run
|
||
即将执行真实 action；确认执行请输入 yes: yes
|
||
PAM> status
|
||
PAM> approve
|
||
PAM> resume
|
||
PAM> exit
|
||
```
|
||
|
||
`chat` 默认仍要求在会话内显式输入 `run` 和 `yes` 才会执行 action；如果某个 IP 失败，会提示输入 `approve` 或 `reject [原因]`。`chat` 也支持 `--llm-base-url` / `--llm-api-key` / `--llm-model`，配置方式和 `analyze` 一致。
|
||
|
||
预演：
|
||
|
||
```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
|
||
```
|
||
|
||
fake 完整部署流程验证：
|
||
|
||
```bash
|
||
python -m pam_deploy_graph.cli run-deploy --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json --confirm
|
||
```
|
||
|
||
如果某个 IP 失败并进入待回滚确认，先查看输出中的 `confirmation`，再人工决定：
|
||
|
||
```bash
|
||
python -m pam_deploy_graph.cli confirm --checkpoint runtime/checkpoints/demo.json --decision approve --confirm
|
||
python -m pam_deploy_graph.cli resume --checkpoint runtime/checkpoints/demo.json --confirm
|
||
```
|
||
|
||
拒绝回滚：
|
||
|
||
```bash
|
||
python -m pam_deploy_graph.cli confirm --checkpoint runtime/checkpoints/demo.json --decision reject --note "人工决定暂不回滚" --confirm
|
||
```
|
||
|
||
checkpoint 用于断点续跑，会保存完整运行状态和参数。为了支持真实续跑，Agent 写入 checkpoint 时不会脱敏参数；请把 checkpoint 放在受控目录中。如果不传 `--checkpoint`，流程仍可运行，但不能跨进程 `resume`。
|
||
|
||
结构化理解和计划生成：
|
||
|
||
```bash
|
||
python -m pam_deploy_graph.cli analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境"
|
||
```
|
||
|
||
测试：
|
||
|
||
```bash
|
||
pytest -q
|
||
```
|
||
|
||
## 下一步建议
|
||
|
||
1. 接入真实 PAM_NODE MCP session，并用 `SessionMcpToolClient` 包装。
|
||
2. 在测试环境中做 smoke：HOME 脚本 `get-token/get-node-url` + NODE MCP `get-online-ips`。
|
||
3. 把当前 checkpoint/confirmation 语义继续接入 LangGraph interrupt/checkpointer。
|
||
4. 继续细化参数确认、IP 范围确认的交互式 UI 或上层编排。
|