deesum/orglens

# 🔍 OrgLens  ## 1. 本工具的目标用户是谁？ | 角色 | 他们如何使用 OrgLens | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | **技术架构师 (Technical Architect)** | 对陌生或接手的 org 进行快速健康度评估，识别热点区域，用证据证明重构的必要性，设定治理基线。 | | **系统集成商 (SI) / 交付主管** | 生成按优先级排序的修复积压工作，导出到 Jira，按团队/发布列车分配任务，并跨迭代追踪趋势。 | | **Salesforce 开发者** | 清楚查看具体是哪条规则失败、在哪失败、为何重要以及如何修复，并提供指向官方规则文档的一键链接。 | | **交付 / 工程经理** | 随时间追踪单一的健康分数，根据质量阈值为拉取请求设置门禁，并向利益相关者汇报进展。 | | **QA / 发布工程师** | 将 OrgLens 集成到 CI 中，在代码质量下降时触发失败或警告。 | ## 2. 它提供什么价值？ - **减少“考古”时间。** 架构师通常需要花费数小时梳理元数据以了解技术债。OrgLens 能在几秒钟内生成分结构化的评估。 - **优先级排序，而不仅是一堆发现结果。** 每个问题都会按严重程度 × 影响范围 × 工作量进行排名，以便团队优先修复最重要的问题。 - **可操作、有证据支撑的指导。** 每个发现都会展示 _是什么、在哪里、为什么以及如何修复_ — 并附带指向确切规则文档的深度链接。 - **快速见效。** 自动展示高严重程度/低工作量的项目，以获得最佳的投资回报率。 - **长期治理。** 快照 + 趋势增量可展示质量在各版本发布间是在改善还是在下降。 - **集成到交付流程中。** 生成适配 Jira 的 CSV 积压工作列表（包含负责团队和发布列车标签）；为拉取请求提供 CI 门禁。 ## 3. 功能概览 **分析引擎** - 集成 Salesforce Code Analyzer (PMD + ESLint) - 内置 **轻量级备用扫描器**（即使没有 Java 也能运行 — 见备注） - 发现 Apex、LWC、Flow、Aura、自定义对象/字段、权限集、Flexipages、自定义标签、静态资源、Visualforce - 依赖关系图 + **影响范围** 评分 - 加权 **健康分数**，包含类别细分（安全性、可维护性、可靠性、性能、可操作性） - 用于分析覆盖率的置信度指标 - **自动 Java 检测** — 查找已安装的 JDK（Homebrew、系统路径、SDKMAN），因此即使 macOS 的 `/usr/bin/java` 存根会阻挡运行，完整的 Salesforce Code Analyzer 也能正常执行；仅当不存在任何 JDK 时才回退到轻量级扫描器 - **引擎感知** — 基于 **Salesforce Code Analyzer v5** 构建；可查看每个扫描引擎（PMD、ESLint、RetireJS、Regex、Copy/Paste Detector、Salesforce Graph Engine、Flow 以及内置的轻量级引擎）及其安装状态和安装/启用方法；可自由选择要运行的引擎 - **可插拔的扫描器适配器** — 额外的工具可接入同一个“引擎”面板，并输入到 **唯一的综合健康分数** 中：**Semgrep** (SAST)、**Gitleaks** (密钥扫描) 和 **npm audit** (依赖项 CVE)。缺失的工具会附带安装说明展示，并被优雅地跳过。添加更多工具（Snyk、CodeQL、SonarQube、OWASP Dependency-Check）只需编写单个适配器文件 — 请参阅 [添加扫描引擎](#adding-a-scan-engine) - **规则管理** — 列出所有引擎中可用的规则（`orglens rules` — 包含 700 多条规则），然后可以从 UI、CLI 标志或配置文件（`ruleOverrides.disabled` / `ruleOverrides.severity`）中禁用规则或覆盖其严重程度 - 内置于 HTML 报告和 UI 中的 **评分指南**，解释了健康分数、字母等级、严重程度、置信度和优先级的含义 **架构智能** - 数字健康分数旁附带 **字母等级 (A–F)** - **What-If 模拟器** — 预测如果你修复特定规则、组件或严重程度分组能带来的分数提升效果（“修复 X → 分数变为 Y”） - **修复路线图** — 将按优先级排序的技术债打包到基于工作量加权的迭代中，并预测每次迭代后的分数 - **所有权** 视图 — 通过可配置的路径匹配规则 (`ownership.rules`) 按负责团队对发现结果进行分组 - 基于治理快照构建的 **分数历史迷你图** **交互式 HTML 报告** - 颜色编码的 KPI 仪表板和 **严重程度分布** 条形图 - **规则摘要**，带有指向每个规则官方文档的深度链接 - AI/启发式 **建议** 卡片 - **快速见效**（高影响力、低工作量） - **所有问题** 表格：严重程度徽章、组件列、紧凑路径以及逐行的规则文档链接 - **筛选**：支持按搜索、严重程度、工作量、元数据类型进行筛选，以及点击过滤组件热点标签 — 可通过可关闭的筛选标签组合所有条件 - **可排序** 列 + 支持将筛选后的视图 **导出为 CSV** - **领域 Playbooks**（Apex / LWC / Flow 修复步骤） - **另存为 PDF** 按钮（为打印优化、省墨样式表） **交付集成** - JSON / Markdown / HTML 输出 - 导出适配 Jira 的 CSV 积压工作（`--backlog-out`，包含所有者列） - 通过 REST API **直接创建 Jira issue**（`--create-jira`，默认为试运行） - 通过 Markdown 摘要 (`--summary-out`) + GitHub Action 实现 **PR 评论机器人** - **Diff 模式** — 对比两份报告以查看新增与已解决的发现 - **提问模式** — 使用您的 LLM 密钥对报告进行自然语言问答 - 具备可配置阈值的 CI 门禁 - 用于趋势追踪的治理快照 - 用于点击式扫描的本地浏览器 UI ## 4. 前置条件（以及各自的安装方法） | # | 前置条件 | 是否必需？ | 用途 | | --- | -------------------------- | ----------------------- | --------------------------------- | | 1 | **Node.js 20+** | ✅ 必需 | 运行 OrgLens CLI/UI | | 2 | **Git** | ✅ 必需 | 克隆代码仓库 | | 3 | **Java (JDK 17)** | ⭐ 强烈推荐 | 启用完整的 PMD/ESLint 扫描 | | 4 | **Salesforce CLI (`sf`)** | ⭐ 推荐 | 提供 Code Analyzer 插件 | | 5 | **Code Analyzer 插件** | ⭐ 推荐 | 完整的规则引擎 | | 6 | **OpenAI / Anthropic key** | ◻ 可选 | AI 编写的建议 | ### 4.1 Node.js 20+ **macOS (Homebrew):** ``` brew install node ``` **Windows:** 从 [nodejs.org](https://nodejs.org/) 下载 LTS 安装程序，或者： ``` winget install OpenJS.NodeJS.LTS ``` **Linux / 跨平台 (nvm):** ``` curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 20 && nvm use 20 ``` 验证： ``` node -v # expect v20.x or higher ``` ### 4.2 Git **macOS:** `brew install git`（或 `xcode-select --install`） **Windows:** `winget install Git.Git` **Linux:** `sudo apt install git` / `sudo dnf install git` ``` git --version ``` ### 4.3 Java (JDK 17) — 用于完整扫描 PMD 和 Salesforce Graph Engine 需要 JDK 11+。**您不必配置 `JAVA_HOME` 或 `PATH`** — OrgLens 会自动检测通过 Homebrew、系统路径（`/Library/Java/JavaVirtualMachines`、`/usr/lib/jvm`）或 SDKMAN 安装的 JDK，并能解决 macOS `/usr/bin/java` 存根阻挡扫描程序的问题。只需安装一个 JDK 即可： **macOS (Homebrew):** ``` brew install openjdk@17 ``` **Windows:** `winget install EclipseAdoptium.Temurin.17.JDK` **Linux:** `sudo apt install openjdk-17-jdk` 就是这样。要确认 OrgLens 检测到了什么，请运行 `orglens rules` — 页脚会打印出它正在使用的 JDK 路径（或告知未找到）。如果不存在任何 JDK，OrgLens 仍会运行其内置的轻量级扫描器。 ### 4.4 Salesforce CLI ``` npm install -g @salesforce/cli sf --version ``` ### 4.5 Salesforce Code Analyzer 插件 (v5) ``` sf plugins install code-analyzer sf plugins # confirm "code-analyzer" is listed sf code-analyzer rules -r all # optional: preview the full ruleset ``` ### 4.6 (可选) 额外扫描引擎 OrgLens 还接入了外部工具 — 安装您想要的任何工具，它们会在引擎面板中自动亮起： ``` brew install semgrep # SAST (JS/TS/Apex, OWASP) brew install gitleaks # secret scanning # npm audit 随 Node.js 附带（对于包含 package.json 的项目会自动使用） ``` ### 4.7 (可选) AI 提供商密钥 设置您拥有的任意一项： ``` export OPENAI_API_KEY="sk-..." # 或者 export ANTHROPIC_API_KEY="sk-ant-..." ``` ## 5. 安装 OrgLens ``` # 1. 克隆 git clone https://github.com/deesum/orglens.git cd orglens # 2. 安装依赖 npm install # 3. 构建 npm run build # 4. 将 `orglens` 命令设置为全局可用 npm link ``` 验证安装： ``` orglens --version orglens --help ``` ## 6. 快速开始（2 分钟内首次运行） 将 OrgLens 指向任何 Salesforce 项目文件夹。它会自动检测元数据根目录（`force-app/main/default`、`apps/*/force-app/main/default` 等）— 您**无需**确切指向元数据文件夹。 ``` orglens analyze --repo "/path/to/your/salesforce-project" --format html ``` 这会将 `orglens-report.html`（以及 `orglens-backlog.csv`）写入项目文件夹。在任何浏览器中打开该 HTML 文件： ``` open orglens-report.html # macOS # 或者直接双击它 ``` 就是这么简单。最少必需的输入项是 `--repo`。 ## 7. 使用浏览器 UI 更喜欢点击操作？启动本地 UI： ``` orglens ui --repo "/path/to/your/salesforce-project" --port 4173 ``` 打开 **http://127.0.0.1:4173**。  在这里您可以： - 输入 / 确认项目路径（唯一必填字段） - 阅读内置的 **评分指南** 说明（健康分数、等级、严重程度） - 选择组件**类型**（Apex、LWC、Flow 等） — 选择一种类型会自动选中其包含的组件 — 并可选地缩小范围到特定的**组件名称**（复选框会准确显示选中了什么） - **加载规则与引擎**，查看每个扫描引擎和所有可用规则 - 选择输出格式、运行**模式**、CI 阈值和 AI 提供商 - 在 **高级选项** 下设置 `package.xml`、目标 org、团队、发布列车和积压工作路径 - 点击 **运行扫描器** 并在界面内预览报告（或在新标签页中打开）  ### 扫描引擎与规则面板 点击 **加载规则与引擎** 填充目录：  - 每个 **引擎卡片** 都会显示其状态 — `已安装`、`需要 Java` 或 `未安装` — 在不可用时附带安装说明，并带有一个复选框，用于在运行中包含/排除该引擎（Salesforce Graph Engine 默认关闭，因为它比较占用资源） - **规则表格** 列出了各引擎中所有可用的规则及其引擎、默认严重程度和文档链接。使用搜索框和 **引擎筛选器** 缩小列表范围 - 取消勾选规则的复选框即可**禁用**它，或使用下拉菜单**覆盖其严重程度**；**全选 / 全不选 / 重置严重程度** 可进行批量操作 - 您的选择将在下一次 **运行扫描器** 时生效 ## 8. 使用 CLI **基础用法：** ``` orglens analyze --repo . --format html ``` **限定到特定的组件类型/名称：** ``` orglens analyze --repo . --format html \ --component-types ApexClass,Flow \ --components DistanceCalculator,FSL_Capture_WOLI_Location ``` **带有所有权标签、适配 Jira 的积压工作：** ``` orglens analyze --repo . --format html \ --team "FSL-Architecture" --release-train "R2" \ --backlog-out "./orglens-backlog.csv" ``` **用于下游工具的 JSON：** ``` orglens analyze --repo . --format json --out ./orglens-report.json ``` ## 9. 理解报告 HTML 报告的结构从上到下完全符合架构师的工作流： 1. **概述** — 健康分数、发现总数、置信度、扫描器状态、依赖关系图大小、工作量组合、严重程度分布、按类别划分的分数，以及受影响最大的组件标签。 2. **规则摘要** — 触发的每条规则、触发次数、最高严重程度、示例文件，以及指向确切规则参考的 **“查看文档 ↗”** 链接。 3. **建议** 链接到证据发现的 AI 或启发式修复建议。 4. **快速见效** — 高严重程度、低工作量、需要优先解决的问题。 5. **所有问题** — 完整的已按优先级排序的表格。每行的规则名称都链接到其具体的文档。按搜索/严重程度/工作量/类型/组件进行筛选，并将筛选后的结果集导出为 CSV。 6. **Playbooks** — 特定于领域的修复 + 验证步骤。 7. **趋势增量** — 与上一个快照相比的分数和发现结果的变化。 8. **积压工作** — 可导入 Jira 的项目计数。 **健康分数区间：** `85+` 健康 · `70–84` 需要关注 · `<70` 存在风险。 ## 10. 运行模式（本地 / CI / 治理） **本地（默认）** — 一次性的架构评估： ``` orglens analyze --repo . --format html --mode local ``` **CI 门禁** — 当分数降至阈值以下时失败/警告（非常适合 PR）： ``` orglens analyze --repo . --format json --mode ci --threshold 70 # 当 gate 失败时退出代码非零 ``` **治理** — 持久化快照，以便随着时间推移积累趋势增量： ``` orglens analyze --repo . --format md --mode governance ``` ## 11. AI 建议（可选） 在没有 API key 的情况下，OrgLens 会生成可靠的启发式建议。提供 key 后，它将生成更丰富、有证据链接的指导： ``` export OPENAI_API_KEY="sk-..." # or ANTHROPIC_API_KEY orglens analyze --repo . --format html --provider openai ``` 建议始终与具体的发现 ID 绑定，以确保其有据可循（不会产生幻觉式的建议）。 ## 12. 故障排除 | 症状 | 原因 | 修复方式 | | ------------------------------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | “使用了轻量级备用检查” / 发现结果过少 | 未找到 JDK，导致 PMD/Graph Engine 无法运行 | 安装 JDK 11+（`brew install openjdk@17`）。OrgLens 会自动检测它 — 无需设置 `JAVA_HOME`/`PATH` | | 尽管已安装 Java，却提示“无法定位 Java 运行时” | macOS `/usr/bin/java` 存根遮蔽了真实的 JDK | 自动修复 — OrgLens 会探测 Homebrew/系统/SDKMAN 的 JDK，并为扫描器注入 `JAVA_HOME` | | 某个 Salesforce 引擎显示“未安装” | 缺少 Salesforce Code Analyzer v5 插件 | `sf plugins install code-analyzer`（引擎面板会显示确切的命令） | | Semgrep / Gitleaks 显示“未安装” | PATH 中找不到外部工具 | `brew install semgrep` / `brew install gitleaks`（引擎卡片会显示该命令）；npm audit 需要存在 `package.json` | | `orglens: command not found` | 未运行 `npm link` / 未重新加载 shell | 重新运行 `npm run build && npm link`，打开一个新终端 | | UI 显示旧版本 | 陈旧的 `orglens ui` 服务器仍在运行旧的构建 | `pkill -f "dist/cli.js ui"`，接着运行 `npm run build`，重启服务器，强制刷新 (`Cmd/Ctrl+Shift+R`) | | 未找到组件 | 项目路径错误 | 传入项目根目录；OrgLens 会自动检测其下方的 `force-app/main/default` | | 建议为空 | 没有 API key | 设置 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY`（可选） | ## 13. 命令参考 ### `orglens analyze` | 选项 | 默认值 | 描述 | | -------------------------------- | ---------------------- | --------------------------------------------------------------------- | | `--repo ` | _(必填)_ | 项目根目录（自动检测元数据根目录） | | `--package ` | — | 用于缩小扫描范围的 `package.xml` | | `--target-org ` | — | Salesforce org 别名（保留用于检索流程） | | `--format ` | `html` | 输出格式 | | `--out ` | `orglens-report.` | 报告输出路径 | | `--mode ` | `local` | 运行模式 | | `--config ` | — | Agent 配置 YAML | | `--provider ` | — | 用于生成建议的 LLM 提供商 | | `--threshold ` | — | CI 失败阈值 (mode=ci) | | `--team ` | `Architecture` | 用于积压工作导出的负责团队 | | `--release-train ` | `R1` | 用于积压工作导出的发布列车 | | `--backlog-out ` | `orglens-backlog.csv` | 适配 Jira 的 CSV 输出路径 | | `--component-types ` | — | 以逗号分隔的需包含的类型列表 | | `--components ` | — | 以逗号分隔的需包含的组件名称列表 | | `--summary-out ` | — | 输出一份简洁的 Markdown 摘要（用于 PR 评论） | | `--create-jira` | off | 从积压工作中创建 Jira issue（除非使用 `--jira-execute`，否则为试运行） | | `--jira-execute` | off | 真正创建 Jira issue（需要设置 `JIRA_*` 环境变量） | | `--disable-rules ` | — | 需要从结果中排除的、以逗号分隔的规则名称 | | `--severity-overrides ` | — | 以逗号分隔的 `规则名=严重程度` 键值对（例如 `ApexDoc=low`） | | `--engines ` | 扫描器默认值 | 以逗号分隔的要运行的引擎（例如 `pmd,eslint`） | ### `orglens rules` 列出每个扫描引擎及其提供的**所有**规则（包含跨 PMD、ESLint、RetireJS、Regex、Copy/Paste Detector、Salesforce Graph Engine、Flow、内置轻量级引擎，以及像 Semgrep、Gitleaks 和 npm audit 这样的可插拔适配器在内的 700 多条规则），每条规则均附带其默认严重程度、类别和一个**文档链接**（源自引擎本身，因此可深度链接到具体规则）。未安装或需要 Java 的引擎会附带安装说明进行标记。可据此决定禁用或重新调整优先级的对象，然后通过 `--disable-rules` / `--severity-overrides` / `--engines`、配置文件（`ruleOverrides`）或浏览器 UI 中的 **规则面板** 反馈这些选择。 | 选项 | 默认值 | 描述 | | ---------- | ------- | ------------------------------- | | `--json` | off | 以 JSON 格式输出目录 | ``` orglens rules orglens analyze --repo ./force-app \ --engines pmd,eslint \ --disable-rules ApexDoc,TodoComment \ --severity-overrides ApexCRUDViolation=critical ``` ### 添加扫描引擎 OrgLens 将每个扫描器视为一个**可插拔适配器**，因此其发现结果会被标准化为相同的严重程度等级，并汇总为一个健康分数。 内置适配器：**Semgrep**、**Gitleaks** 和 **npm audit**（分别使用 `brew install semgrep`、`brew install gitleaks` 安装；npm 随 Node.js 一起提供）。 未安装的引擎会附带安装说明列出并被跳过 — 它们绝不会导致运行失败。 要添加新工具（例如 Snyk、CodeQL、SonarQube、OWASP Dependency-Check）： 1. 创建 `src/scanner/adapters/.ts`，实现 `ScannerAdapter` 接口（`detect()`、`isApplicable()`、`run()` 和 `rules()` 目录）。 2. 将工具的输出映射到 `AnalyzerFinding`（使用 `adapters/util.ts` 中的 `buildFinding` — 它会从文件路径推断元数据类型/组件）。 3. 在 `src/scanner/adapters/registry.ts` 中注册它。 完成 — 该引擎随后将出现在 `orglens rules`、UI 的引擎面板（附带安装状态）、`--engines` 选择器以及综合分数中。 ### `orglens diff` 对比两份 JSON 报告，以查看两次运行之间发生了什么变化。 | 选项 | 默认值 | 描述 | | ------------------- | ------------ | --------------------------------- | | `--baseline ` | _(必填)_ | 基准报告 JSON | | `--current ` | _(必填)_ | 当前报告 JSON | | `--out ` | — | 将 Markdown 差异写入文件 | ``` orglens diff --baseline before.json --current after.json --out diff.md ``` ### `orglens ask` 针对生成的 JSON 报告提出自然语言问题（需要 LLM key）。 | 选项 | 默认值 | 描述 | | -------------------------------- | --------------------- | ----------------------------------- | | `` | _(必填)_ | 您的问题（位置参数） | | `--report ` | `orglens-report.json` | JSON 报告的路径 | | `--config ` | — | Agent 配置 YAML | | `--provider ` | — | LLM 提供商 | ``` orglens ask "Which components carry the most critical debt and why?" ``` ### 创建 Jira issue 设置这些环境变量，然后运行 `orglens analyze --create-jira --jira-execute`： ``` export JIRA_BASE_URL="https://your-domain.atlassian.net" export JIRA_EMAIL="you@example.com" export JIRA_API_TOKEN="" export JIRA_PROJECT_KEY="ORG" export JIRA_ISSUE_TYPE="Task" # optional, defaults to Task ``` 如果没有 `--jira-execute`，该命令将执行安全的试运行，并打印出它将要创建的内容。 ### 所有权与路线图配置 向 `agent.config.yml` 添加 `ownership` 和 `roadmap` 块（参见 `agent.config.example.yml`），以将发现结果路由给各个团队并调整迭代容量。 ### `orglens ui` | 选项 | 默认值 | 描述 | | ---------------------- | ----------- | ----------------------------- | | `--repo ` | 当前目录 | 项目根目录 | | `--package ` | — | 用于缩小范围的 `package.xml` | | `--target-org ` | — | Salesforce org 别名 | | `--port ` | `4173` | UI 服务器端口 | ## 许可证 采用 [MIT 许证](./LICENSE) © 2026 Deepak Sumra 发布。 ## 项目文档 - `docs/quickstart.md` — 浓缩版快速入门 - `docs/config-reverse-engineer-agent/architecture.md` — 架构设计 - `docs/config-reverse-engineer-agent/github-setup.md` — GitHub 设置 - `docs/config-reverse-engineer-agent/agent-operating-instructions.md` — Agent 操作模式

标签：AI分析, MITM代理, Petitpotam, Salesforce, 技术债务, 自动化攻击