uipath-explainator/README.md

UiPath Explainator

uipath-explainator 会按 UiPath 项目入口 main.xaml 递归提取 Invoke Workflow 和 Invoke VBA，复制到指定工作区，删除 <ui:CommentOut> 里的无效代码，再重新扫描并裁掉不再使用的文件，最后逐个调用 Gemini 生成说明文档。

输出会自动拆成独立的 code/ 与 docs/ 两个子目录，避免说明文档和项目文件混在一起。

安装

./.venv/bin/pip install -e .

配置

把 .env.example 复制成 .env，至少填入：

GEMINI_API_KEY=your_api_key
GEMINI_BASE_URL=
GEMINI_MODEL=gemini-2.5-flash

GEMINI_BASE_URL 留空时走官方默认地址；如果你前面挂了代理或网关，可以填自定义地址。 这里填写网关根地址即可，例如 https://your-gateway.example.com，不要自己追加 /v1beta、/v1alpha 或 /v1。

使用

./.venv/bin/python -m uipath_explainator \
  /path/to/uipath-project \
  --output-dir workspace/project-bundle

常用参数：

• --entry: 入口文件名，默认 main.xaml
• --env-file: 自定义 .env 路径
• --model: 临时覆盖 .env 里的模型名
• --skip-analysis: 只做复制、清理和剪枝，不调用 Gemini
• --force: 删除并重建已有输出目录；不加时会默认续跑，并跳过“已成功分析且源码未变化”的文件
• --log-level: 日志级别，支持 DEBUG / INFO / WARNING / ERROR / CRITICAL
• --log-file: 把完整日志同时写入文件，便于回溯扫描、剪枝和 Gemini 分析过程

中途中断后，直接对同一个 --output-dir 再运行一次即可继续。程序会复用 docs/ 里的本地分析缓存，只把新增文件、内容有变化的文件，以及上次失败的文件重新发给 Gemini。

输出内容

输出目录现在是一个 bundle 目录，里面固定包含：

• code/: 复制出来并经过清理、剪枝后的项目文件，保留原项目相对目录结构
• docs/manifest.json: 扫描、剪枝、告警和分析结果清单
• docs/OVERVIEW.md: 总览说明书，除了文件数量，还会解释“初次扫描 -> 清理 Comment Out -> 二次扫描 -> 剪枝 -> Gemini 分析”的整条流水线逻辑
• docs/*.analysis.md: 每个最终保留文件对应的 Gemini 咨询式说明，固定包含：
  • 文件定位：这个文件在整个流程中的角色、触发方式、核心作用
  • 流程拆解：按步骤说明它是怎么执行的
  • 关键逻辑：条件判断、调用关系、边界情况
  • 数据与依赖：输入、输出、变量、外部文件或系统
  • 咨询视角：业务含义、风险点、无法确认的信息
  • 场景范例：帮助交接和理解的示例

当前实现约束

• 只解析能静态识别出来的 Invoke Workflow / Invoke VBA 文件路径。
• 对动态拼接路径会记录 warning，但不会猜测。
• Invoke VBA 默认识别常见文本型 VBA 文件扩展名：.txt、.bas、.vb、.vbs、.vba、.cls、.frm。

日志说明

运行时默认输出 INFO 级别日志，会记录：

• CLI 启动参数、配置加载结果、是否启用 Gemini
• 依赖扫描开始/结束、文件数量、warning 数量
• 复制、清理 Comment Out、二次扫描、剪枝、生成文档等阶段摘要

如果需要看更细的文件级排查信息，直接把日志级别调到 DEBUG：

./.venv/bin/python -m uipath_explainator \
  /path/to/uipath-project \
  --output-dir workspace/project-bundle \
  --log-level DEBUG \
  --log-file workspace/project-bundle/run.log

DEBUG 会额外记录每个文件的复制、依赖解析、路径解析、剪枝、分析文档写出等细节。