xiaomai
0bdebd5368
Introduce --log-level and --log-file CLI arguments. Add execution time tracking and detailed logs across all modules.
86 lines
3.3 KiB
Markdown
86 lines
3.3 KiB
Markdown
# UiPath Explainator
|
||
|
||
`uipath-explainator` 会按 UiPath 项目入口 `main.xaml` 递归提取 `Invoke Workflow` 和 `Invoke VBA`，复制到指定工作区，删除 `<ui:CommentOut>` 里的无效代码，再重新扫描并裁掉不再使用的文件，最后逐个调用 Gemini 生成说明文档。
|
||
|
||
输出会自动拆成独立的 `code/` 与 `docs/` 两个子目录，避免说明文档和项目文件混在一起。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
./.venv/bin/pip install -e .
|
||
```
|
||
|
||
## 配置
|
||
|
||
把 `.env.example` 复制成 `.env`，至少填入：
|
||
|
||
```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`。
|
||
|
||
## 使用
|
||
|
||
```bash
|
||
./.venv/bin/python -m uipath_explainator \
|
||
/path/to/uipath-project \
|
||
--output-dir workspace/project-bundle \
|
||
--force
|
||
```
|
||
|
||
常用参数：
|
||
|
||
- `--entry`: 入口文件名，默认 `main.xaml`
|
||
- `--env-file`: 自定义 `.env` 路径
|
||
- `--model`: 临时覆盖 `.env` 里的模型名
|
||
- `--skip-analysis`: 只做复制、清理和剪枝，不调用 Gemini
|
||
- `--force`: 允许覆盖已有输出目录
|
||
- `--log-level`: 日志级别，支持 `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`
|
||
- `--log-file`: 把完整日志同时写入文件，便于回溯扫描、剪枝和 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`：
|
||
|
||
```bash
|
||
./.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 \
|
||
--force
|
||
```
|
||
|
||
`DEBUG` 会额外记录每个文件的复制、依赖解析、路径解析、剪枝、分析文档写出等细节。
|