From ba85e61379f76a67f65b8c73d807d7d6f465ab75 Mon Sep 17 00:00:00 2001 From: dark Date: Mon, 1 Jun 2026 15:26:09 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=89=93=E5=8C=85=E8=84=9A?= =?UTF-8?q?=E6=9C=AC=E9=80=BB=E8=BE=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + packaging/README_linux_package.md | 22 ++++- packaging/README_packaged_agent.md | 122 ++++++++++++++++++++++++ packaging/build_linux_self_contained.sh | 105 ++++++++++++++++---- pam_deploy_graph/agent.py | 4 +- 5 files changed, 235 insertions(+), 20 deletions(-) create mode 100644 packaging/README_packaged_agent.md diff --git a/README.md b/README.md index 411ce56..9ff6542 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,8 @@ dist/linux_self_contained/pam-deploy-agent-linux-x86_64/ dist/linux_self_contained/pam-deploy-agent-linux-x86_64.tar.gz ``` +发布包内的 `doc_scripts` 只包含运行必需文件：`deploy.sh`、`config.txt.example`、`PAM_AUTO_DEPLY_SKILL.md`。发布包内的 `README.md` 使用 `packaging/README_packaged_agent.md`，只介绍打包后 Agent 的使用方式。 + 目标机器解压后运行： ```bash diff --git a/packaging/README_linux_package.md b/packaging/README_linux_package.md index 86a009b..7edf9d8 100644 --- a/packaging/README_linux_package.md +++ b/packaging/README_linux_package.md @@ -32,6 +32,26 @@ dist/linux_self_contained/pam-deploy-agent-linux-x86_64/ dist/linux_self_contained/pam-deploy-agent-linux-x86_64.tar.gz ``` +发布目录只会包含运行必需文件： + +```text +pam-deploy-agent-linux-x86_64/ + run.sh + pam-deploy-agent + doc_scripts/ + deploy.sh + config.txt.example + PAM_AUTO_DEPLY_SKILL.md + README.md + LICENSE +``` + +说明： + +- `doc_scripts` 不会打入项目设计文档、测试脚本、Windows bat/PowerShell 脚本。 +- 发布包内的 `README.md` 来自 `packaging/README_packaged_agent.md`，只说明打包后 Agent 的使用方式。 +- 项目开发用 README 不会复制到发布包内。 + ## 解压后运行 ```bash @@ -41,7 +61,7 @@ cd pam-deploy-agent-linux-x86_64 ./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json ``` -`run.sh` 会切换到发布目录再启动可执行程序，因此默认的 `doc_scripts/...` 相对路径可以正常工作。 +`run.sh --help` 是发布包专用的中文帮助，会解释命令、参数、环境变量和常见示例。`run.sh` 会切换到发布目录再启动可执行程序，因此默认的 `doc_scripts/...` 相对路径可以正常工作。 ## 包大小评估 diff --git a/packaging/README_packaged_agent.md b/packaging/README_packaged_agent.md new file mode 100644 index 0000000..de44e02 --- /dev/null +++ b/packaging/README_packaged_agent.md @@ -0,0 +1,122 @@ +# PAM 部署 Agent 解压即用包 + +这是打包后的 PAM 部署 Agent 使用说明。该包已包含 Python 运行时和 Python 依赖，目标 Linux 机器解压后即可运行。 + +## 目录说明 + +```text +pam-deploy-agent-linux-x86_64/ + run.sh # 推荐入口，带中文帮助 + pam-deploy-agent # PyInstaller 生成的可执行程序 + doc_scripts/ + deploy.sh # Linux 脚本 action 入口 + config.txt.example # 参数配置示例 + PAM_AUTO_DEPLY_SKILL.md + README.md # 当前说明 + LICENSE +``` + +`doc_scripts` 只保留运行必需文件，不包含项目设计文档、测试脚本或 Windows 脚本。 + +## 查看帮助 + +```bash +./run.sh --help +``` + +查看某个子命令的原始参数： + +```bash +./run.sh chat --help +./run.sh run-deploy --help +``` + +## 交互式使用 + +推荐先用 fake 策略验证流程： + +```bash +./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/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 +``` + +## 一次性命令 + +只做理解和计划生成，不执行： + +```bash +./run.sh analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境" +``` + +预演 action 路由： + +```bash +./run.sh preview --config doc_scripts/config.txt.example --strategy fake +``` + +执行 fake 完整部署流程： + +```bash +./run.sh run-deploy --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json --confirm +``` + +处理失败后的回滚确认： + +```bash +./run.sh confirm --checkpoint runtime/checkpoints/demo.json --decision approve --confirm +./run.sh resume --checkpoint runtime/checkpoints/demo.json --confirm +``` + +拒绝回滚： + +```bash +./run.sh confirm --checkpoint runtime/checkpoints/demo.json --decision reject --note "人工决定暂不回滚" --confirm +``` + +## LLM 配置 + +不配置 LLM 时会使用本地规则 fallback。真实 LLM 使用 OpenAI-compatible `/chat/completions`： + +```bash +export PAM_LLM_BASE_URL="https://your-llm.example.com/v1" +export PAM_LLM_API_KEY="your-api-key" +export PAM_LLM_MODEL="your-model-name" + +./run.sh analyze --config doc_scripts/config.txt.example --text "请分析这次部署" +``` + +也可以用 CLI 参数： + +```bash +./run.sh analyze \ + --config doc_scripts/config.txt.example \ + --text "请分析这次部署" \ + --llm-base-url https://your-llm.example.com/v1 \ + --llm-api-key your-api-key \ + --llm-model your-model-name +``` + +## 策略说明 + +- `fake`：全部使用 fake runner，不访问真实环境。 +- `script_only`：全部 action 走脚本。 +- `hybrid_node_mcp`：PAM_HOME 走脚本，PAM_NODE 走 MCP。 + +## 注意事项 + +- 执行真实 action 前请确认配置文件中的 `HOME_BASE_URL`、`CLIENT_ID`、`CLIENT_SECRET`、`AIRPORT_CODE`、`APP_NAME`、`MODULE_NAME`、`VERSION_NUMBER`、`ZIP_FILE_PATH`。 +- `checkpoint` 会保存完整运行参数，请放在受控目录。 +- 真实 MCP session 需要你在外部接入；当前包包含 MCP client adapter 和 action 映射能力。 diff --git a/packaging/build_linux_self_contained.sh b/packaging/build_linux_self_contained.sh index 07141fd..0f4758c 100644 --- a/packaging/build_linux_self_contained.sh +++ b/packaging/build_linux_self_contained.sh @@ -62,8 +62,14 @@ python -m PyInstaller \ echo "==> 组装发布目录" mkdir -p "$RELEASE_DIR" cp -a "$BUILD_DIR/pyinstaller_dist/$APP_NAME/." "$RELEASE_DIR/" -cp -a doc_scripts "$RELEASE_DIR/doc_scripts" -cp -a README.md "$RELEASE_DIR/README.md" + +mkdir -p "$RELEASE_DIR/doc_scripts" +cp -a doc_scripts/deploy.sh "$RELEASE_DIR/doc_scripts/deploy.sh" +cp -a doc_scripts/config.txt.example "$RELEASE_DIR/doc_scripts/config.txt.example" +cp -a doc_scripts/PAM_AUTO_DEPLY_SKILL.md "$RELEASE_DIR/doc_scripts/PAM_AUTO_DEPLY_SKILL.md" +chmod +x "$RELEASE_DIR/doc_scripts/deploy.sh" + +cp -a packaging/README_packaged_agent.md "$RELEASE_DIR/README.md" cp -a LICENSE "$RELEASE_DIR/LICENSE" cat > "$RELEASE_DIR/run.sh" <<'RUN_SCRIPT' @@ -71,25 +77,90 @@ cat > "$RELEASE_DIR/run.sh" <<'RUN_SCRIPT' set -euo pipefail DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cd "$DIR" + +print_help() { + cat <<'HELP_TEXT' +PAM 部署 Agent 解压即用包 + +用法： + ./run.sh <命令> [参数] + +常用命令： + chat 启动交互式对话框。推荐从这里开始使用。 + analyze 只做自然语言理解和部署计划生成，不执行 action。 + preview 根据配置预演 action 路由和关键参数。 + run-global 执行全局阶段：token、版本、上传、发布、Node URL、下载任务。 + run-deploy 执行完整部署流程：全局阶段 + 逐 IP 阶段。 + resume 从 checkpoint 继续执行。 + confirm 处理待人工确认事项，目前用于失败 IP 回滚确认。 + +通用参数： + --config <路径> + 参数配置文件。支持 config.txt 风格和 JSON。打包内置示例： + doc_scripts/config.txt.example + + --strategy <策略> + 执行策略： + fake 全部使用 fake runner，不访问真实环境。 + script_only 全部 action 走脚本。 + hybrid_node_mcp PAM_HOME 走脚本，PAM_NODE 走 MCP。 + + --checkpoint <路径> + checkpoint JSON 路径。用于断点续跑和人工确认恢复。 + 示例：runtime/checkpoints/demo.json + + --target-ip + 指定目标工作站 IP。可重复传入多次。 + + --confirm + 非交互命令执行真实 action 前必须显式传入。 + chat 模式会在会话中要求输入 run 和 yes。 + +LLM 参数： + --llm-base-url + OpenAI-compatible LLM 服务地址，例如 https://example.com/v1 + + --llm-api-key + LLM API Key。也可通过环境变量 PAM_LLM_API_KEY 提供。 + + --llm-model <模型名> + LLM 模型名称。也可通过环境变量 PAM_LLM_MODEL 提供。 + +LLM 环境变量： + PAM_LLM_BASE_URL + PAM_LLM_API_KEY + PAM_LLM_MODEL + +示例： + ./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json + + ./run.sh analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境" + + ./run.sh run-deploy --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json --confirm + + ./run.sh confirm --checkpoint runtime/checkpoints/demo.json --decision approve --confirm + ./run.sh resume --checkpoint runtime/checkpoints/demo.json --confirm + +查看子命令原始参数： + ./run.sh chat --help + ./run.sh run-deploy --help + +说明： + 1. 本包已包含 Python 运行时和 Python 依赖，目标机器不需要安装 Python 包。 + 2. doc_scripts 只包含运行必需文件：deploy.sh、config.txt.example、PAM_AUTO_DEPLY_SKILL.md。 + 3. checkpoint 会保存完整运行参数，请放在受控目录。 +HELP_TEXT +} + +if [[ $# -eq 0 || "${1:-}" == "-h" || "${1:-}" == "--help" || "${1:-}" == "help" ]]; then + print_help + exit 0 +fi + exec "$DIR/pam-deploy-agent" "$@" RUN_SCRIPT chmod +x "$RELEASE_DIR/run.sh" -cat > "$RELEASE_DIR/使用说明.txt" <<'USAGE_TEXT' -PAM 部署 Agent Linux 解压即用包 - -使用方式： - ./run.sh --help - ./run.sh chat --config doc_scripts/config.txt.example --strategy fake --checkpoint runtime/checkpoints/demo.json - ./run.sh analyze --config doc_scripts/config.txt.example --text "请用 MCP 预演部署 HET PAM Node 版本 2.0.5，不要动环境" - -说明： - 1. 该包已包含 Python 运行时和 Python 依赖，目标机器不需要额外安装 Python 包。 - 2. 真实 LLM 仍需通过 PAM_LLM_BASE_URL、PAM_LLM_API_KEY、PAM_LLM_MODEL 或 CLI 参数配置。 - 3. 真实 MCP session 仍需由你在外部接入后传给 Agent；当前包已包含 MCP client adapter。 - 4. checkpoint 会保存完整运行参数，请放在受控目录。 -USAGE_TEXT - echo "==> 生成 tar.gz" tar -C "$DIST_DIR" -czf "$ARCHIVE_PATH" "$RELEASE_NAME" diff --git a/pam_deploy_graph/agent.py b/pam_deploy_graph/agent.py index b472bf6..ee04687 100644 --- a/pam_deploy_graph/agent.py +++ b/pam_deploy_graph/agent.py @@ -133,7 +133,7 @@ class PamDeployAgent: ) def preview(self, params: dict[str, Any], strategy: ExecutionStrategy = "hybrid_node_mcp") -> str: - """渲染部署预演，展示参数和 action 路由。""" + """渲染部署预览，展示参数和 action 路由。""" normalized = self.normalize_params(params) routes = build_action_backends(strategy) if strategy == "hybrid_node_mcp": @@ -146,7 +146,7 @@ class PamDeployAgent: home_backend = "fake" node_backend = "fake" lines = [ - "## PAM 部署预演", + "## PAM 部署预览", "", f"- 执行策略: {strategy}", f"- PAM_HOME: {home_backend}",