优化打包脚本逻辑

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

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/...` 相对路径可以正常工作。
 
 ## 包大小评估
 

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 映射能力。

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>
+      指定目标工作站 IP。可重复传入多次。
+
+  --confirm
+      非交互命令执行真实 action 前必须显式传入。
+      chat 模式会在会话中要求输入 run 和 yes。
+
+LLM 参数：
+  --llm-base-url <URL>
+      OpenAI-compatible LLM 服务地址，例如 https://example.com/v1
+
+  --llm-api-key <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"
 

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}",