agent_deply/packaging/README_linux_package.md

Linux 解压即用打包说明

目标

build_linux_self_contained.sh 会在 Linux x86_64 构建机上生成一个自带 Python 运行时和 Python 依赖的发布包。目标机器解压后可以直接运行，不需要额外安装 Python 或 pip 依赖。

构建机要求

• Linux x86_64
• bash
• python3，需要带 venv 模块
• 构建时需要访问 Python 包索引，用于安装 PyInstaller 和项目依赖

该脚本不支持在 Windows 上交叉构建 Linux 包。建议在和目标环境 glibc 版本相同或更旧的 Linux 发行版上构建，以提高二进制兼容性。

构建命令

bash packaging/build_linux_self_contained.sh

默认会安装 .[mcp,chat]，即包含 MCP 可选依赖和 chat 交互增强依赖。如果只想打最小包：

PACKAGE_EXTRAS= bash packaging/build_linux_self_contained.sh

构建产物：

dist/linux_self_contained/pam-deploy-agent-linux-x86_64/
dist/linux_self_contained/pam-deploy-agent-linux-x86_64.tar.gz

发布目录只会包含运行必需文件：

pam-deploy-agent-linux-x86_64/
  run.sh
  pam-deploy-agent
  doc_scripts/
    deploy.sh
    config.txt.example
    PAM_AUTO_DEPLY_SKILL.md
  prompts/
    action_review.txt
  mcp_client.example.json
  README.md
  LICENSE

说明：

• doc_scripts 不会打入项目设计文档、测试脚本、Windows bat/PowerShell 脚本。
• prompts/action_review.txt 会随发布包一起带上，作为当前默认 action 审核提示词的参照版本。
• 发布包内的 README.md 来自 packaging/README_packaged_agent.md，只说明打包后 Agent 的使用方式。
• 发布包内的 mcp_client.example.json 是 MCP server URL + 独立鉴权配置示例，需要按真实 MCP server 和 token 地址修改。
• 项目开发用 README 不会复制到发布包内。

解压后运行

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

run.sh --help 是发布包专用的中文帮助，会解释命令、参数、环境变量和常见示例。run.sh 会切换到发布目录再启动可执行程序，因此默认的 doc_scripts/... 相对路径可以正常工作。

本次发布包对应的运行时行为也已同步到包内 README.md：

• 每个 action 完成后都会自动执行一次 LLM/规则审核，只有审核通过才会把 action 记为 completed。
• action 审核输入不包含完整运行态 state_summary，只包含当前 action 的结构化结果和必要诊断日志，避免历史状态干扰大模型判断。
• create-download-task 支持可选 PARENT_VERSION_NUMBER，非空时会传给云下载接口的 parentVersionNumber；默认空值不发送，继承正在使用的版本规则。
• poll-download-progress 和 poll-upgrade-progress 是单次进度查询 action；Agent workflow 会按配置重复调用，每次返回后交给 LLM/规则判断是否完成并播报进度。
• verify-ip 会按 VERIFY_INTERVAL_SEC / VERIFY_MAX_ATTEMPTS 做应用健康检查重试，默认每 10 秒一次、最多 12 次，仍未通过才暂停。
• --analyze-actions 只控制是否把详细审核结果写入 events。
• action 失败或审核阻断后会保存 checkpoint 并暂停；修复外部环境后通过 resume 从当前 action 重试。
• 回滚不再属于主 workflow 自动分支；需要时使用 chat 内 rollback [IP] 或 CLI rollback --checkpoint ... 显式执行。
• chat 中非内置命令默认交给当前 LLM 普通对话，不会自动触发部署 workflow；普通对话优先流式展示，<think>...</think> 思考内容会被过滤；完整部署仍需 analyze / run 并人工确认。
• chat 支持 ask <问题>、log analyze <路径>、action propose <需求>、action run ...，可用于普通问答、日志尾部分析和确认后执行单 action；日志分析输出同样会过滤 <think> 内容。
• chat 支持执行中 Ctrl+C 中断后保存 checkpoint，再通过 resume 重试当前 action。
• chat 支持 set KEY=VALUE 和 load params <路径> 热更新当前运行任务参数。
• 进度查询和健康检查重试参数可通过 POLL_INTERVAL_SEC、DOWNLOAD_POLL_MAX_ATTEMPTS、UPGRADE_POLL_MAX_ATTEMPTS、VERIFY_INTERVAL_SEC、VERIFY_MAX_ATTEMPTS 配置。
• 支持通过 --llm-action-analysis-prompt-file 或 chat 内 llm config action_analysis_prompt_file=... 自定义 action 审核提示词。
• chat 支持 llm test [文本] 测试当前 LLM client 是否正常加载。
• 默认运行日志写入 logs/pam_deploy_agent.log，按天切分并默认保留 14 个历史日切文件，可通过 PAM_AGENT_LOG_FILE、PAM_AGENT_LOG_LEVEL 和 PAM_AGENT_LOG_RETENTION_DAYS 调整。
• 日志会脱敏 token、secret、api_key、Authorization 等字段；chat 普通对话和日志分析不会记录原始 <think> 内容；checkpoint 仍保存完整运行参数，请放在受控目录。

包大小评估

最终大小以脚本末尾打印的 du 结果为准。按当前依赖结构预估：

构建方式	压缩包大小	解压后大小	主要影响因素
默认包含 MCP 依赖	60-110 MB	160-300 MB	PyInstaller 运行时、langgraph、mcp 及其依赖
PACKAGE_EXTRAS= 最小包	45-75 MB	120-200 MB	PyInstaller 运行时、langgraph 及基础依赖

当前项目源码和脚本文档本身体积很小，包大小主要由 Python 运行时、PyInstaller bootloader、第三方依赖和动态库决定。