diff --git a/README.md b/README.md index 0663a1b..1aac596 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ `uipath-explainator` 会按 UiPath 项目入口 `main.xaml` 递归提取 `Invoke Workflow` 和 `Invoke VBA`，复制到指定工作区，删除 `` 里的无效代码，再重新扫描并裁掉不再使用的文件，最后逐个调用 Gemini 生成说明文档。 +输出会自动拆成独立的 `code/` 与 `docs/` 两个子目录，避免说明文档和项目文件混在一起。 + ## 安装 ```bash @@ -26,7 +28,7 @@ GEMINI_MODEL=gemini-2.5-flash ```bash ./.venv/bin/python -m uipath_explainator \ /path/to/uipath-project \ - --output-dir workspace/project-copy \ + --output-dir workspace/project-bundle \ --force ``` @@ -40,11 +42,12 @@ GEMINI_MODEL=gemini-2.5-flash ## 输出内容 -输出目录会保留原项目的相对目录结构，并额外生成： +输出目录现在是一个 bundle 目录，里面固定包含： -- `manifest.json`: 扫描、剪枝、告警和分析结果清单 -- `OVERVIEW.md`: 总览说明书，除了文件数量，还会解释“初次扫描 -> 清理 Comment Out -> 二次扫描 -> 剪枝 -> Gemini 分析”的整条流水线逻辑 -- `*.analysis.md`: 每个最终保留文件对应的 Gemini 咨询式说明，固定包含： +- `code/`: 复制出来并经过清理、剪枝后的项目文件，保留原项目相对目录结构 +- `docs/manifest.json`: 扫描、剪枝、告警和分析结果清单 +- `docs/OVERVIEW.md`: 总览说明书，除了文件数量，还会解释“初次扫描 -> 清理 Comment Out -> 二次扫描 -> 剪枝 -> Gemini 分析”的整条流水线逻辑 +- `docs/*.analysis.md`: 每个最终保留文件对应的 Gemini 咨询式说明，固定包含： - 文件定位：这个文件在整个流程中的角色、触发方式、核心作用 - 流程拆解：按步骤说明它是怎么执行的 - 关键逻辑：条件判断、调用关系、边界情况 diff --git a/src/uipath_explainator/cli.py b/src/uipath_explainator/cli.py index 903e360..cfead57 100644 --- a/src/uipath_explainator/cli.py +++ b/src/uipath_explainator/cli.py @@ -11,7 +11,12 @@ from .pipeline import ProjectPipeline def build_parser() -> ArgumentParser: parser = ArgumentParser(description="Extract and explain UiPath project dependencies.") parser.add_argument("project_dir", type=Path, help="UiPath project root directory") - parser.add_argument("--output-dir", type=Path, default=Path("workspace"), help="Copied project output directory") + parser.add_argument( + "--output-dir", + type=Path, + default=Path("workspace"), + help="Output bundle directory containing separate code/ and docs/ folders", + ) parser.add_argument("--entry", default="main.xaml", help="Entry XAML file name") parser.add_argument("--env-file", type=Path, default=Path(".env"), help="Environment file for Gemini config") parser.add_argument("--model", help="Override GEMINI_MODEL") @@ -44,6 +49,8 @@ def main(argv: list[str] | None = None) -> int: report = pipeline.run(analyzer=analyzer) print(f"Output written to: {report.output_root}") + print(f"Code written to: {report.code_root}") + print(f"Docs written to: {report.docs_root}") print(f"Final files: {len(report.final_files)}") print(f"Pruned files: {len(report.pruned_files)}") print(f"Warnings: {len(report.warnings)}") diff --git a/src/uipath_explainator/pipeline.py b/src/uipath_explainator/pipeline.py index 38f6060..596ae29 100644 --- a/src/uipath_explainator/pipeline.py +++ b/src/uipath_explainator/pipeline.py @@ -12,6 +12,8 @@ from .scanner import ScanResult, crawl_dependencies, find_entry_file, read_text, class PipelineReport: project_root: Path output_root: Path + code_root: Path + docs_root: Path entry_file: Path initial_files: list[Path] final_files: list[Path] @@ -25,6 +27,8 @@ class PipelineReport: { "project_root": self.project_root.as_posix(), "output_root": self.output_root.as_posix(), + "code_root": self.code_root.as_posix(), + "docs_root": self.docs_root.as_posix(), "entry_file": self.entry_file.as_posix(), "initial_files": [item.as_posix() for item in self.initial_files], "final_files": [item.as_posix() for item in self.final_files], @@ -42,6 +46,8 @@ class ProjectPipeline: def __init__(self, project_root: Path, output_root: Path, entry_name: str, force: bool = False) -> None: self.project_root = project_root.resolve() self.output_root = output_root.resolve() + self.code_root = self.output_root / "code" + self.docs_root = self.output_root / "docs" self.entry_name = entry_name self.force = force @@ -56,8 +62,8 @@ class ProjectPipeline: self._copy_files(initial_rel_files) cleaned_files = self._clean_copied_xaml_files(initial_rel_files) - final_scan = crawl_dependencies(self.output_root, self.output_root / entry_rel) - final_rel_files = self._relative_files(final_scan, self.output_root) + final_scan = crawl_dependencies(self.code_root, self.code_root / entry_rel) + final_rel_files = self._relative_files(final_scan, self.code_root) pruned_files = self._prune_unused_files(initial_rel_files, final_rel_files) analysis_files = self._write_analysis(final_rel_files, analyzer) @@ -66,6 +72,8 @@ class ProjectPipeline: report = PipelineReport( project_root=self.project_root, output_root=self.output_root, + code_root=self.code_root, + docs_root=self.docs_root, entry_file=entry_rel, initial_files=initial_rel_files, final_files=final_rel_files, @@ -82,12 +90,13 @@ class ProjectPipeline: if not self.force: raise FileExistsError(f"Output directory already exists: {self.output_root}") rmtree(self.output_root) - self.output_root.mkdir(parents=True, exist_ok=True) + self.code_root.mkdir(parents=True, exist_ok=True) + self.docs_root.mkdir(parents=True, exist_ok=True) def _copy_files(self, relative_files: list[Path]) -> None: for relative_path in relative_files: source = self.project_root / relative_path - destination = self.output_root / relative_path + destination = self.code_root / relative_path destination.parent.mkdir(parents=True, exist_ok=True) copy2(source, destination) @@ -96,7 +105,7 @@ class ProjectPipeline: for relative_path in relative_files: if relative_path.suffix.lower() != ".xaml": continue - output_file = self.output_root / relative_path + output_file = self.code_root / relative_path original = read_text(output_file) updated = strip_comment_out_blocks(original) if updated != original: @@ -110,7 +119,7 @@ class ProjectPipeline: for relative_path in initial_files: if relative_path in final_set: continue - target = self.output_root / relative_path + target = self.code_root / relative_path if target.exists(): target.unlink() pruned.append(relative_path) @@ -119,7 +128,7 @@ class ProjectPipeline: def _cleanup_empty_dirs(self) -> None: directories = sorted( - [path for path in self.output_root.rglob("*") if path.is_dir()], + [path for path in self.code_root.rglob("*") if path.is_dir()], key=lambda item: len(item.parts), reverse=True, ) @@ -134,17 +143,17 @@ class ProjectPipeline: output_files: list[Path] = [] for relative_path in self._ordered_files(final_files): - content = read_text(self.output_root / relative_path) + content = read_text(self.code_root / relative_path) analysis = analyzer.analyze(relative_path, content) - analysis_path = self.output_root / f"{relative_path.as_posix()}.analysis.md" + analysis_path = self.docs_root / f"{relative_path.as_posix()}.analysis.md" analysis_path.parent.mkdir(parents=True, exist_ok=True) analysis_path.write_text(analysis, encoding="utf-8") output_files.append(Path(f"{relative_path.as_posix()}.analysis.md")) return output_files def _write_report_files(self, report: PipelineReport) -> None: - (self.output_root / "manifest.json").write_text(report.to_json(), encoding="utf-8") - (self.output_root / "OVERVIEW.md").write_text(self._build_overview(report), encoding="utf-8") + (self.docs_root / "manifest.json").write_text(report.to_json(), encoding="utf-8") + (self.docs_root / "OVERVIEW.md").write_text(self._build_overview(report), encoding="utf-8") def _build_overview(self, report: PipelineReport) -> str: warnings = "\n".join(f"- {item}" for item in report.warnings) or "- 无" @@ -155,6 +164,8 @@ class ProjectPipeline: - Project Root: `{report.project_root.as_posix()}` - Output Root: `{report.output_root.as_posix()}` +- Code Root: `{report.code_root.as_posix()}` +- Docs Root: `{report.docs_root.as_posix()}` - Entry File: `{report.entry_file.as_posix()}` - Initial Files: {len(report.initial_files)} - Final Files: {len(report.final_files)} @@ -167,18 +178,18 @@ class ProjectPipeline: ## Processing Logic 1. **Initial Scan**: 从入口文件开始递归扫描 `Invoke Workflow` 与 `Invoke VBA`，得到初始依赖集合。这个阶段会把 `Comment Out` 里的引用也一起算进去，因为此时还未清理失效代码。 -2. **Copy to Workspace**: 将初始依赖集合完整复制到输出目录，保持相对目录结构不变，确保后续裁剪只发生在工作区副本中。 +2. **Copy to Workspace**: 将初始依赖集合完整复制到 `code/` 目录，保持相对目录结构不变，确保后续裁剪只发生在代码副本中。 3. **Comment Cleanup**: 对已复制的 XAML 删除 `` 代码块，让后续扫描只看到当前真正生效的流程节点。 4. **Rescan After Cleanup**: 以清理后的入口文件重新递归扫描，得到清理后的实际依赖集合。 -5. **Prune Unused Files**: 删除首次扫描能到达、但二次扫描已不可达的文件。这些文件通常来自被注释掉的工作流、VBA，或清理后失效的调用链。 -6. **Gemini Analysis**: 仅针对最终保留文件生成 `*.analysis.md`，让说明文档与实际可执行流程保持一致。 +5. **Prune Unused Files**: 删除 `code/` 目录中首次扫描能到达、但二次扫描已不可达的文件。这些文件通常来自被注释掉的工作流、VBA，或清理后失效的调用链。 +6. **Gemini Analysis**: 仅针对最终保留文件在 `docs/` 目录生成 `*.analysis.md`，让说明文档与实际可执行流程保持一致。 ## How To Read This Output - `Initial Files`: 清理 `` 前扫描到的所有文件，代表“理论上被引用过”的集合。 -- `Final Files`: 清理后仍可达的文件，代表“当前实际流程会用到”的集合。 +- `Final Files`: 清理后 `code/` 目录中仍可达的文件，代表“当前实际流程会用到”的集合。 - `Cleaned XAML Files`: 被移除 `` 代码块的文件。 -- `Pruned Files`: 只在失效分支中出现、已从输出目录删除的文件。 -- `Analysis Files`: Gemini 生成的逐文件说明，重点解释该文件的流程、逻辑、数据与风险点。 +- `Pruned Files`: 只在失效分支中出现、已从 `code/` 目录删除的文件。 +- `Analysis Files`: `docs/` 目录下 Gemini 生成的逐文件说明，重点解释该文件的流程、逻辑、数据与风险点。 ## Cleaned XAML Files {cleaned} diff --git a/tests/test_pipeline.py b/tests/test_pipeline.py index 06c39f8..980ed57 100644 --- a/tests/test_pipeline.py +++ b/tests/test_pipeline.py @@ -83,6 +83,8 @@ class PipelineTests(unittest.TestCase): tmp_path = Path(tmp) project_root = tmp_path / "project" output_root = tmp_path / "workspace" + code_root = output_root / "code" + docs_root = output_root / "docs" (project_root / "Flows").mkdir(parents=True) (project_root / "Flows" / "Active.xaml").write_text(ACTIVE_XAML, encoding="utf-8") (project_root / "Flows" / "Old.xaml").write_text(OLD_XAML, encoding="utf-8") @@ -104,15 +106,21 @@ class PipelineTests(unittest.TestCase): self.assertIn("Scripts/Keep.bas", final_files) self.assertNotIn("Flows/Old.xaml", final_files) self.assertNotIn("Scripts/Drop.bas", final_files) - self.assertFalse((output_root / "Flows" / "Old.xaml").exists()) - self.assertFalse((output_root / "Scripts" / "Drop.bas").exists()) - self.assertTrue((output_root / "Flows" / "Active.xaml.analysis.md").exists()) + self.assertEqual(report.code_root, code_root.resolve()) + self.assertEqual(report.docs_root, docs_root.resolve()) + self.assertFalse((code_root / "Flows" / "Old.xaml").exists()) + self.assertFalse((code_root / "Scripts" / "Drop.bas").exists()) + self.assertTrue((code_root / "Flows" / "Active.xaml").exists()) + self.assertTrue((docs_root / "Flows" / "Active.xaml.analysis.md").exists()) + self.assertTrue((docs_root / "manifest.json").exists()) - overview = (output_root / "OVERVIEW.md").read_text(encoding="utf-8") + overview = (docs_root / "OVERVIEW.md").read_text(encoding="utf-8") self.assertIn("## Processing Logic", overview) self.assertIn("Initial Scan", overview) self.assertIn("## How To Read This Output", overview) self.assertIn("## Cleaned XAML Files", overview) + self.assertIn("Code Root", overview) + self.assertIn("Docs Root", overview) if __name__ == "__main__":