JoniPraia/plugadvpl
GitHub: JoniPraia/plugadvpl
为 Totvs Protheus 的 ADVPL/TLPP 源码建立本地 SQLite+FTS5 元数据索引，让 Claude Code 以极低 token 成本实现架构理解、调用图查询和字段级影响分析。
Stars: 11 | Forks: 5
# plugadvpl
[](https://pypi.org/project/plugadvpl/)
[](https://pypi.org/project/plugadvpl/)
[](LICENSE)
[](https://github.com/JoniPraia/plugadvpl/actions/workflows/ci.yml)
[](https://pypi.org/project/plugadvpl/)
[](https://github.com/JoniPraia/plugadvpl/stargazers)
## 为什么选择 plugadvpl
- **节省 token。** 一个普通的 `.prw` 文件有 1,000 到 10,000 行。直接读取需要消耗 5k 到 50k token。使用 plugadvpl，可以通过结构化的元数据来回答相同的问题——在实际项目中可**节省约 16 倍的上下文**。
- **经过实战检验的解析器。** 其函数、表、内嵌 SQL 和调用图的提取器移植自作者的内部解析器，并在大约 **2,000 个 ADVPL 源码**上进行了验证。这绝非周末的练手实验。
- **MIT 许可，无遥测，100% 本地运行。** SQLite 索引文件存放在您仓库内的 `.plugadvpl/index.db` 中。没有任何数据会离开您的机器。支持离线使用。
## 演示
**不使用插件的场景** — 提问：“解释一下函数 `FATA050`”：
```
Claude → Read FATA050.prw # arquivo inteiro
→ ~12.000 tokens consumidos
→ resposta vaga, sem call graph, sem saber quem usa
```
**使用 plugadvpl 的场景**：
```
Claude → /plugadvpl:arch FATA050.prw # capabilities, tabelas, funções, includes
→ /plugadvpl:callers FATA050 # quem chama
→ Read FATA050.prw offset=234 limit=46 # range exato, só se preciso
→ ~730 tokens consumidos (≈ 16× menor)
→ resposta com contexto: módulo, MVC, tabelas SA1/SC5, PE relacionado
```
## 快速安装 (单行命令)
**Windows (PowerShell):**
```
irm https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.ps1 | iex
```
**macOS / Linux:**
```
curl -sSL https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.sh | sh
```
此脚本将会：
1. 如果尚未安装，则安装 `uv` (Astral 的 Python 包管理器)
2. 通过 `uv tool install` 全局安装 `plugadvpl`
3. 打印后续步骤
接下来只需运行：
```
cd
plugadvpl init
plugadvpl ingest
plugadvpl status
```
## 更新到新版本
最简单的方法——适用于所有平台——是**再次运行安装的
单行命令**。它会检测是否缺少 `uv`，如有需要则进行安装，并
重新安装 `plugadvpl`，拉取 PyPI 上的最新版本。
**Windows (PowerShell):**
```
irm https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.ps1 | iex
```
**macOS / Linux:**
```
curl -sSL https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.sh | sh
```
如果您已经安装了 `uv` 并且只想强制拉取新版本（uv 有时会使用缓存）：
```
uv cache clean plugadvpl
uv tool install plugadvpl --reinstall --force
plugadvpl version
```
### Claude Code 插件与 CLI 是分开的
CLI (`plugadvpl`, Python) 和 Claude Code 插件 (skills + agents + hook) 是
**两个独立更新的组件**。更新其中一个不会影响另一个。
要更新插件：
```
/plugin marketplace update plugadvpl-marketplace
```
(在 Claude Code CLI 中使用；在 VSCode 扩展中请使用 `/plugin` UI)。
如果遇到卡住的情况（`uv` 消失了、插件已更新但 slash command 看起来仍是旧版、
uvx 缓存保留了旧版本），请查看 FAQ 中的[更新故障排除](docs/FAQ.md#troubleshooting-de-atualização)。
## 快速开始
```
# 1. 前提条件：uv (高速 Python 包管理器)
winget install astral-sh.uv # Windows
# 或者：curl -LsSf https://astral.sh/uv/install.sh | sh # Linux/macOS
# 2. 安装 Claude Code 插件 — 见下文部分
# （路径因原生 CLI 和 VSCode 扩展而异）
# 3. 打开你的 Protheus 项目并运行：
/plugadvpl:init # cria .plugadvpl/index.db, fragment CLAUDE.md, .gitignore
/plugadvpl:ingest # parser paralelo, ~30–60s para 2.000 fontes
```
完成。从现在开始，Claude 会在打开任何 `.prw` 文件之前先查询索引。要您自己进行检查：
```
/plugadvpl:arch FATA050.prw # visão arquitetural de um fonte
/plugadvpl:callers MaFisRef # quem chama essa função
/plugadvpl:tables SA1 # quem lê/grava/reclock na SA1
/plugadvpl:param MV_LOCALIZA # onde esse parâmetro é usado
/plugadvpl:lint --severity error # encontrar problemas críticos
```
## 安装 Claude Code 插件 (可选，用于 slash commands)
除了 CLI，plugadvpl 还是一个 **Claude Code 插件**，它增加了：
- Slash 命令 `/plugadvpl:arch`、`/plugadvpl:find`、`/plugadvpl:callers` 等。
- 15 个 Claude 会自动加载的主题知识技能 (advpl-mvc, advpl-tlpp, advpl-pontos-entrada 等)
- `SessionStart` 钩子，可检测 ADVPL 项目并建议运行 `/plugadvpl:init`
- 4 个专业子代理 (analyzer, impact-analyzer, code-generator, reviewer-bot)
安装方式取决于您在哪里使用 Claude Code：
### 选项 A — Claude Code CLI (终端 `claude`)
在 CLI 的聊天中：
```
/plugin marketplace add https://github.com/JoniPraia/plugadvpl.git
/plugin install plugadvpl
```
接受信任对话框即可。完成。
### 选项 B — Claude Code VSCode 扩展
该扩展**不支持**在聊天中直接使用 `/plugin install`（这是 Claude Code 的官方限制）。请使用 UI：
1. 在聊天中输入 `/plugin` (不带参数) — 这将打开 **Manage Plugins** 面板
*另一种方式*：`Ctrl+Shift+P` → "Claude Code: Manage Plugins"
2. **Marketplaces** 选项卡 → 点击 **Add** 按钮 → 粘贴 `https://github.com/JoniPraia/plugadvpl.git`
3. **Plugins** 选项卡 → 找到 `plugadvpl` → 点击 **Install for you (user scope)**
4. 接受信任对话框
请重启 Claude Code 以确保技能、钩子和 slash 命令被正确加载。
### 验证
在任何路径下的聊天中输入：
```
/plugadvpl:status
```
如果输出包含索引的计数器信息，说明插件已成功安装并运行。
## 可用命令
Python CLI 提供了 **18 个子命令** (自 v0.3.0 起)，并在 Claude Code 插件的 slash 命令中进行了镜像。
| 命令 | 功能 |
|---|---|
| `/plugadvpl:init` | 创建 `.plugadvpl/index.db`，在 `CLAUDE.md` 中添加片段，并在 `.gitignore` 中添加条目 |
| `/plugadvpl:ingest` | 扫描并索引所有源码 (`--workers N`, `--incremental`, `--no-content`, `--redact-secrets`) |
| `/plugadvpl:reindex <文件>` | 重新索引单个文件 (在手动编辑后使用) |
| `/plugadvpl:status` | 显示版本、计数器，可选择检查过期文件 (`--check-stale`) |
| `/plugadvpl:find <术语>` | 组合搜索：函数 → 文件 → 内容 (FTS) |
| `/plugadvpl:callers <函数>` | 谁调用了该函数 (反向调用图) |
| `/plugadvpl:callees <函数>` | 该函数调用了什么 (正向调用图) |
| `/plugadvpl:tables ` | 谁使用了表 `T` (`--mode read/write/reclock`) |
| `/plugadvpl:param ` | 参数 `MV_*` 出现的位置 |
| `/plugadvpl:arch <文件>` | **架构视图** — 请务必在执行 `Read` 前使用 |
| `/plugadvpl:lint [文件]` | Lint 结果 (`--severity`, `--regra`, `--cross-file`) |
| `/plugadvpl:doctor` | 诊断 (编码、孤立文件、FTS 同步、lookups) |
| `/plugadvpl:grep <模式>` | 在代码块中进行文本搜索 (`--mode fts/literal/identifier`) |
| `/plugadvpl:help` | 列出命令 (相当于 CLI 的 `--help` 快捷方式) |
| **`/plugadvpl:ingest-sx `** | **(v0.3.0)** 导入以 CSV 导出的 SX 字典 (sx1..sxg) |
| **`/plugadvpl:impacto <字段>`** | **(v0.3.0)** **杀手级功能** — 交叉对比源码 ↔ SX3 ↔ SX7 ↔ SX1 中对某字段的引用 (支持 `--depth 1..3`) |
| **`/plugadvpl:gatilho <字段>`** | **(v0.3.0)** SX7 触发器链 起点 → 终点 (支持 `--depth 1..3`) |
| **`/plugadvpl:sx-status`** | **(v0.3.0)** SX 字典各表的记录计数 |
完整参考：[docs/cli-reference.md](docs/cli-reference.md)。
## 内置技能
除了 18 个命令包装器 (每个 CLI 子命令对应一个，外加 `setup` 辅助命令) 之外，该插件还包含 **18 项知识技能**，Claude 会根据上下文加载它们：
| 技能 | 何时加载 |
|---|---|
| `plugadvpl-index-usage` | 核心技能 — 在读取任何 ADVPL 源码前强制查询索引 |
| `advpl-fundamentals` | 匈牙利命名法、命名规范、模块前缀、195 个受限函数 |
| `advpl-encoding` | cp1252 (.prw) 与 utf-8 (.tlpp) — 默认保留编码 |
| `advpl-mvc` | MenuDef/ModelDef/ViewDef、钩子 bCommit/bTudoOk、FWFormStruct |
| `advpl-mvc-avancado` | MVC 事件、交叉验证、FWMVCRotAuto |
| `advpl-tlpp` | 现代 TLPP — 面向对象、命名空间、注解 |
| `advpl-embedded-sql` | BeginSql/EndSql, TCQuery, `%xfilial%`, `%notDel%`, `%table%` |
| `advpl-pontos-entrada` | User Function NOME(PARAMIXB)、通过 PARAMIXB[最后一个元素] 返回 |
| `advpl-webservice` | REST (`WSRESTFUL`, `@Get/@Post`) 与 SOAP (`WSSERVICE`/`WSMETHOD`) |
| `advpl-web` | Web 接口 — Webex / HTML / WebExpress |
| `advpl-jobs-rpc` | `RpcSetEnv`, `StartJob`, `MsRunInThread`、Job 中禁止使用的函数 |
| `advpl-matxfis` | 财税模块 (NF-e, SPED, ECF, REINF，SF2/SD2/SF3 集成) |
| `advpl-advanced` | 线程、IPC、调试、深度面向对象 |
| `advpl-dicionario-sx` | SX1/SX2/SX3/SX5/SX6/SX7/SIX/SXA/SXB 结构 (v0.2.0) |
| `advpl-dicionario-sx-validacoes` | 嵌入在 X3_VALID/INIT/WHEN/VLDUSER、X7_REGRA、X1_VALID、X6_VALID/INIT 中的 ADVPL 表达式 — 用于影响分析的指南 (v0.3.0) |
| `advpl-refactoring` | 6 种包含 before/after 的模式 (DbSeek 循环, 重复的 Posicione, 硬编码 IFs, AxCadastro→MVC, 循环中的字符串拼接, 无 Begin Transaction 的 RecLock) — 当请求为“改进”/“重构”/“运行缓慢”时使用 (v0.3.3) |
| `advpl-debugging` | 生产环境中排名前 30 的常见错误 + 调试方法 (ConOut, MemoWrite, FwLogMsg, varInfo) — 当用户粘贴 AppServer.log 的 traceback 时使用 (v0.3.3) |
| `advpl-code-review` | 24 条 BP/SEC/PERF/MOD 规则 — 13 条单文件规则 (v0.1) + 11 条跨文件规则 `SX-001..SX-011` (v0.3.0) |
此外还包括：**4 个专业代理** (`advpl-analyzer`, `advpl-impact-analyzer`, `advpl-code-generator`, `advpl-reviewer-bot`) 和 **1 个 SessionStart 钩子** (Node.js)，负责跨平台引导 `.plugadvpl/`。
## 工作原理
```
.prw / .tlpp parser strip-first SQLite + FTS5 slash command
(seu projeto) ───▶ (regex sobre conteúdo ─▶ 22 tabelas físicas ─▶ /plugadvpl:*
sem comentário/string) + 2 FTS5 virtuais (Claude consulta)
paralelo adaptive + 6 lookups TOTVS
```
`plugadvpl ingest` 会扫描项目，并行解析每个源文件 (`ProcessPoolExecutor`，对于少于 200 个文件的项目会回退到单线程)，将元数据（函数、调用、表、MV_*、内嵌 SQL、PEs、REST 端点、Jobs 等）持久化到 SQLite 中，并重建两个 FTS5 索引——一个是使用 `tokenchars '_-'` 的 `unicode61` 索引（将 `A1_COD` 和 `FW-Browse` 保持为一个 token），另一个是用于精确子字符串搜索（如 `SA1->A1_COD`、`%xfilial%`）的 trigram 索引。
当您向 Claude 提出关于项目的问题时，slash 命令会在 SQLite 中运行一次低成本的查询，并仅返回关键信息——函数、行范围、调用者、表——大约只需 700 个 token。详情请参阅 [docs/architecture.md](docs/architecture.md)。
## 系统要求
- 支持**插件**的 **Claude Code** (CLI 或 IDE 扩展)
- 通过 `uvx`/`uv` 安装的 **Python 3.11+** (无需手动创建 venv)
- 包含 `.prw`、`.prx`、`.tlpp 或 `.apw` 源码的 **Protheus 项目**
- 操作系统：Windows、Linux 或 macOS (CI 运行在 3 个操作系统 × 3 个 Python 版本的矩阵上)
## 当前状态
**v0.3.0 — 宇宙 2：SX 字典 (杀手级功能 `impacto`)。**
- 18 个子命令，37 项技能 (18 个知识技能 + 18 个 CLI 包装器 + 1 个安装辅助)，4 个代理，1 个钩子
- 33 个物理表 (22 个源码表 + 11 个 SX 表) + 2 个 FTS5 + 6 个 lookups
- 250+ 测试 (单元测试 + 集成测试 + 基准测试 + e2e_local)
- 基准测试（约 2,000 个源文件）：使用 `--workers 8` 时 ingest 耗时 <60 秒；导入完整的 SX 字典
（约 42 万行）耗时 <30 秒
- SX Schema 与解析器基于作者先前的内部项目
**路线图。**
- **v0.1** *(已发布)* — 宇宙 1：源码解析器、FTS5、13 条单文件 lint 规则、14 个 CLI 子命令。
- **v0.2** *(已发布)* — 将 21k 行 ADVPL/TLPP 参考文档内嵌到 5 个新技能和 6 个强化技能中。
- **v0.3** *(已发布)* — 宇宙 2 (SX 字典)：导入 SX1..SXG，`impacto`/`gatilho`/`sx-status` 命令，11 条跨文件规则 SX-001..SX-011。
- **v0.4** *(下一阶段)* — 宇宙 3 (可追溯性)：PE × 原始点图谱、MVC × 表 × 字段、死代码检测、跨客户端差异比对。
详情请参阅 [docs/ROADMAP.md](docs/ROADMAP.md) 及规范文档 `docs/superpowers/specs/2026-05-11-plugadvpl-design.md` (§15)。
## 文档
- [docs/cli-reference.md](docs/cli-reference.md) — 包含语法、选项和示例的 18 个子命令完整参考
- [docs/schema.md](docs/schema.md) — SQLite schema (22 个表 + 2 个 FTS5 + Mermaid 图 + 实用查询)
- [docs/architecture.md](docs/architecture.md) — 流程、组件、关键决策及贡献新提取功能的指南
- [CONTRIBUTING.md](CONTRIBUTING.md) — 本地环境设置、测试夹具、代码风格、提交规范
- [CHANGELOG.md](CHANGELOG.md) — 发布历史
- [SECURITY.md](SECURITY.md) — 漏洞报告政策
## 免责声明 / 商标
**Protheus**、**ADVPL**、**TLPP** 和 **TOTVS** 是 **TOTVS S.A.** 拥有的产品和注册商标。
本插件是一个独立项目，与 TOTVS、其特许经营商或代表**没有任何隶属关系**。
### 关于使用与开发
- 本插件**不使用、不重新分发、也不暴露任何 Protheus 标准产品的源代码**（TOTVS 内部例程、RPO、官方源码）。
- 本工具是在自定义源码（User Functions、MVC 自定义、入口点、
WebServices、Jobs 以及由客户在其环境中编写的其他 `.prw`/`.tlpp`/`.prx` 文件）**上独家开发和验证的**。
- 内置的目录（原生函数、受限函数、ERP 模块、
标准入口点）仅包含在 [TDN — TOTVS Developers Network](https://tdn.totvs.com/) 上**公开文档化的名称和元数据**。
未包含任何专有源代码。
- 在 `skills//exemplos/` 目录下分发的 `.prw`/`.tlpp` 示例是
**作者原创的代码**，旨在说明自定义模式（并非派生自 TOTVS 标准源码）。
- 每位用户都有责任确保自己拥有使用本插件索引的源文件的访问和分析权限（通常指其自己公司或签约客户的自定义代码）。
## 许可证
[MIT](LICENSE) © 2026 JoniPraia.
标签：ADVPL, AST解析, Claude, CVE检测, DLL 劫持, ERP, FTS5, LLM插件, MIT开源, Protheus, Python, RAG, SQLite, TLPP, Token优化, TOTVS, 代码分析, 代码搜索, 代码索引, 代码解析器, 代码辅助, 元数据提取, 全文检索, 凭证管理, 函数调用图, 大语言模型, 幻觉缓解, 无后门, 本地知识库, 检索增强生成, 离线开发, 进程保护, 逆向工具, 错误基检测, 静态代码分析