MuhDur/plsql-intelligence
GitHub: MuhDur/plsql-intelligence
基于 Rust 的离线、包感知 Oracle PL/SQL 代码智能引擎,提供依赖图分析、变更影响评估和自愈性解析覆盖率。
Stars: 2 | Forks: 0
# PL/SQL 智能引擎
基于 Rust 的离线、包感知 Oracle PL/SQL 代码智能工具,具备
自愈性覆盖率飞轮。
# [A] capture GapRecords
usr-loop cluster # [C] deduped GapClusters
usr-loop propose --from-scan # [D] one candidate diff
usr-loop propose --cluster-id ID # propose for a specific signature
usr-loop gate # run the sha-pinned §3 gate
usr-loop land --fixture F # [F] gate, then land or quarantine
usr-loop ledger # inspect the append-only ledger
usr-loop doctor # crate/schema versions, deps
```
`gate`/`land` 的退出码:`0` 已接纳/已合并,`3` 已拒绝/已隔离
(符合规范,不是 bug),`4` 门控 sha 固定中止,`9` I-PRIVACY 中止
(未持久化任何内容)。
### `plsql-mcp`
```
plsql-mcp info # server identity and tool tiers
plsql-mcp --robot-json capabilities # machine-readable agent contract
plsql-mcp serve # stdio MCP loop
plsql-mcp serve --listen ADDR # TCP MCP loop
```
### `plan-lint`
```
cargo run -p plan-lint -- # structural lint of plan.md
cargo run -p plan-lint -- --robot-json # machine-readable findings
cargo run -p plan-lint -- --doctor # health summary
```
## 设计承诺
- Rust Cargo workspace,每个组件一个 crate。
- 所有 CLI 接口都有 `doctor` 子命令和 `--robot-json` 输出,因此
agent 读取的是机器契约而不是猜测。
- 只要分析无法确定,就会有明确的 `UnknownReason` 记录;
完整性报告绝不会有虚假的“一切正常”。
- 解析器后端隔离:下游 crate 不得依赖
ANTLR 生成的类型。
- 整个 workspace 是 `#![forbid(unsafe_code)]` 的。
- 默认无遥测。
## 仓库工作流
1. 先阅读 `AGENTS.md` 和 `plan.md`。
2. 将 `plan.md` 视为预期架构和
范围的真理来源。如果代码和 `plan.md` 出现分歧,要么
有意识地修复其中之一。
3. 仅在 Beads 中追踪工作;`.beads/` 是权威的。
4. 切勿将私有材料复制到本仓库中。USR Loop 和
正确性测试框架在指定路径(由 `PLSQL_PRIVATE_ESTATE` 环境变量给出)原地读取私有环境,绝不持久化
其字节。
## 布局
- `plan.md`:主规范
- `AGENTS.md`:仓库操作规则
- `Cargo.toml`、`crates/`、`tools/`:Rust workspace
- `corpus/`:测试使用的公开和合成 PL/SQL fixture
- `docs/`:架构快照、计划、决策、集成指南
- `scripts/`:`usr_gate.sh`、`usr_acceptance.sh`、`accretion_tripwire.sh`、
`estate_correctness.sh`
- `.beads/`:Beads issue-tracker 状态(权威)
- `CHANGELOG.md`:发布说明日志以及 `coverage_index` 表
## 故障排除
| 症状 | 修复 |
|---------|-----|
| `usr-loop gate` 退出码为 4 | 门控 sha 固定不匹配。门控脚本已更改,但 `crates/plsql-accretion/gate.sha256` 中的 sha 未更新。这是故意的失败即关闭行为;仅能通过审查过的 commit 重新固定。 |
| `usr-loop gate`/`land` 退出码为 9 | G8 阶段的 I-PRIVACY 泄露信号。运行中止且未持久化任何内容,这符合设计。检查有问题的 fixture;不要削弱 G8。 |
| `usr_acceptance.sh` 退出码为 0 并带有“estate-absent”横幅 | 未配置私有环境(`PLSQL_PRIVATE_ESTATE` 未设置或为空),因此在此处未验证 DoD。在将变量指向私有环境的情况下运行它,或者依赖夜间的 CI。 |
| `--features antlr-codegen` 构建失败 | 代码生成使用固定的 nightly 工具链:`cargo +nightly-2026-05-11 build -p plsql-parser-antlr --features antlr-codegen`。 |
| 在真实环境中依赖图为空 | 这是解析器尚无法触及的方言尾部应有的表现;它们被记录为类型化的 `UnknownReason`,正是 USR Loop 的修复输入,而不是悄无声息的失败。 |
## 局限性
- 1.0 之前:API 在 1.0 之前随时可能变动。
- Live-DB MCP 工具通过 `tools/call` 进行调度,但需要活动的
Oracle 连接才能执行;如果没有连接,它们会返回类型化的
`RuntimeStateRequired` 响应,指出缺失的运行时状态,这是设计
使然 —— agent 可以在没有附加 Oracle 的情况下针对宣告的完整
接口规划会话。
- USR Loop 提议者不会自动合并。它会产生经过验证的
候选者;证明是自动且完整的,而合并的决定
受该证明和仓库正常审查的约束(依据 `D3`)。
- 真正有歧义的 Oracle 方言语法不会通过猜测来解决。
它们会变成诚实的类型化 `UnknownReason`(修复类 `d`):覆盖的是
诚实,绝不是捏造。
- 累加在签名类别上复合增长,而不是原始计数。长尾的
单例环境怪癖可能会保持开启状态;这是被报告出来的,而不是被掩盖的。
- `g` 类语法补丁是真正的语法工作,像其他所有内容一样受到门控:
速度较慢,但稳健。
- 引用完整性子集被路由到单独的未来计划中,而不是
在第一个版本中发布。
## 常见问题
**分析需要实时的 Oracle 数据库吗?** 不需要。分析是针对源代码和可选的 catalog 快照进行的离线分析。实时 catalog 提取
和 live-DB MCP 接口可用,但受 feature gate 控制。
**解析器是真的,还是启发式扫描器?** 是真的。该引擎通过
`plsql-parser-antlr` 中的 `antlr4rust` 进行解析,带有无损 token tape;
决策和证据在 `docs/decisions/D2-backend-final.md` 中。
**解析器无法处理的结构会怎样?** 它们会连同来源被记录
为类型化的 `UnknownReason`。完整性报告会真实地反映出这一点,
而不是报告虚假的“一切正常”结果。
**USR Loop 是否在真实环境中关闭了 N 个缺陷?** 这个声明在此处并不作为
既定的营销事实提出。机制已经实现,而
证明是可重新运行的 `scripts/usr_acceptance.sh` 加上夜间 CI。
本 README 记录了如何运行它,而不是无法验证的吹嘘。
**我能削弱门控以更快地合并补丁吗?** 不能。门控是
sha 固定的且失败即关闭;不匹配将中止。更改它需要
经过审查的 commit 和深思熟虑的 sha 更新。
**有代码是 `unsafe` 的吗?** 没有。整个 workspace 是
`#![forbid(unsafe_code)]` 的。
## 许可证
在以下两项许可证之下进行双重许可:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
由你选择。位于 `crates/plsql-parser-antlr/grammars/` 下的内置 ANTLR PL/SQL 语法
是 Apache-2.0 协议的,来源于
`antlr/grammars-v4`;署名保留在
`crates/plsql-parser-antlr/LICENSE-GRAMMARS.md` 中。
除非你明确声明,否则根据 Apache-2.0
许可证的规定,由你故意提交以包含在本作品中的任何贡献,均应按上述方式进行双重许可,不附加任何额外条款或
条件。
## 关于贡献
*关于贡献:* 请不要误会,但我不接受任何外部对我项目的贡献。我只是没有精力去审查任何东西,而且作品上署的是我的名字,所以我要对它造成的任何问题负责;因此,从我的角度来看,风险与回报是高度不对称的。我还得担心其他的“利益相关者”,这对于我主要是为自己免费制作的工具来说似乎是不明智的。你可以随意提交 issue,如果你想说明一个提议的修复,甚至可以提交 PR,但请知道我不会直接合并它们。相反,我会让 Claude 或 Codex 通过 `gh` 审查提交的内容,并独立决定是否以及如何解决它们。特别欢迎错误报告。如果这冒犯了你,我很抱歉,但我想避免浪费时间并伤害感情。我明白这与寻求社区贡献的流行开源精神不同,但这是我唯一能以这种速度前进并保持理智的方式。
### 与我合作
我帮助 enterprises 解决难题 —— 大规模数据库、系统现代化,以及供应商中立(云端或自托管)的生产环境中的 AI。正在数据库、Rust / C++ 或 AI 领域构建困难的东西吗?请联系我。
→ **[durakovic.ai](https://durakovic.ai)** · hello@durakovic.ai
[](https://github.com/MuhDur/plsql-intelligence/actions/workflows/ci.yml)
[](https://github.com/MuhDur/plsql-intelligence/actions/workflows/usr.yml)
[](#license)
[](#design-commitments)
[](rust-toolchain.toml)
```
# 构建整个 workspace 并运行每个测试
git clone https://github.com/MuhDur/plsql-intelligence
cd plsql-intelligence
cargo build --workspace && cargo test --workspace
```
## TL;DR
**问题。** 在庞大的 Oracle 环境中,PL/SQL 包、视图、
触发器和表构成了深度的依赖网络。修改一个列类型或
一个包规范,可能会悄无声息地导致数百个下游
对象失效;你往往要在生产环境重新编译失败时才会发现。现有工具
各自涵盖了其中一部分(SQL 部署、血缘产品、SAST 扫描器、
Oracle 自有的 SQLcl MCP server),但没有一个能在单一工作流中提供离线的、具备包感知能力的
PL/SQL 语义分析,并包含明确的未知项报告、依赖
推理以及重新编译规划。
**解决方案。** 一个分层的 Rust workspace,它通过真正的
ANTLR 后端解析 PL/SQL,构建包含名称解析和依赖
图语义的 IR,并报告变更影响。当分析器无法确定时,它会以类型化的 `UnknownReason` 如实报告,而不是
给出虚假的“一切正常”结果。这种诚实的未知项输出流为 **USR Loop** 提供了动力,它
将记录到的缺陷转化为经过验证的、隐私安全的解析器和底层
修复,从而使覆盖率随着使用而不断增加。
### 两个 MCP server:`oraclemcp` 和 `plsql-mcp`
本仓库包含了**完整的** PL/SQL 智能 MCP server,**`plsql-mcp`** —— 实时的
Oracle DB 工具,**外加**离线 PL/SQL 智能(解析/分析、依赖
图、血缘、SAST)以及受保护的写入操作。其无引擎核心被提取为
一个独立的、已发布的同胞项目,[**`oraclemcp`**](https://github.com/MuhDur/oraclemcp):
| | [`oraclemcp`](https://github.com/MuhDur/oraclemcp) | `plsql-mcp`(本仓库) |
|---|---|---|
| 范围 | 安全、只读的实时 **Oracle DB** 访问 | 超集:DB 访问 **+** PL/SQL **智能** + 受保护的写入 |
| 构建 | 无引擎、精简、快速 | 完整的纯 Rust ANTLR 引擎 |
| 安装 | `cargo install oraclemcp` · `docker run -i ghcr.io/muhdur/oraclemcp` | `cargo install --path crates/plsql-mcp` · `docker run -i ghcr.io/muhdur/plsql-mcp` |
| MCP registry | `io.github.MuhDur/oraclemcp` | `io.github.MuhDur/plsql-mcp` |
当 agent 只需要安全的数据库访问时,选用 `oraclemcp`;当
你需要深度的 PL/SQL 代码理解时,请使用
`plsql-mcp`(它包含了 `oraclemcp` 的所有功能)。
### 为什么使用它?
| 能力 | 它的作用 |
|------------|--------------|
| **离线优先** | 直接读取代码和 Oracle catalog 快照;分析无需实时数据库,默认无遥测 |
| **真正的解析器后端** | `antlr4rust`(`plsql-parser-antlr`),纯 Rust,无 JVM,带有无损 token tape(`reconstruct(tape) == input`) |
| **诚实的未知项** | 当分析无法确定时,它会发出类型化的 `UnknownReason`;完整性报告绝不会有虚假的“一切正常” |
| **依赖推理** | 语义 IR、名称解析、权限模型,以及可与 `ALL_DEPENDENCIES` 交叉检查的依赖图 |
| **USR Loop** | 自愈性飞轮:捕获的缺陷会成为隐私安全的 fixture、候选补丁,并经过 9 阶段的失败即关闭的一致性门控 |
| **已验证的累加** | 单调的 `coverage_index` 配合 CI 触发器,让“覆盖率不断复合增长”成为经过检查的属性,而不是一句口号 |
| **内存安全** | 整个 workspace 是 `#![forbid(unsafe_code)]` 的 |
### 对比情况
| | 需要实时 DB | 包感知的 PL/SQL 语义 | 诚实的未知项 | 离线分析 |
|---|:---:|:---:|:---:|:---:|
| SQL 部署工具(Liquibase, Flyway) | 是 | 否 | 否 | 否 |
| 血缘 / catalog 产品 | 视情况而定 | 部分 | 否 | 视情况而定 |
| 通用 SAST 扫描器 | 否 | 否 | 否 | 是 |
| Oracle SQLcl MCP server | 是 | 部分 | 否 | 否 |
| **PL/SQL 智能引擎** | **否** | **是** | **是** | **是** |
## 状态
这是处于活跃开发阶段的 1.0 之前软件。`plan.md` 是
权威规范;`docs/ARCHITECTURE.md` 是技术
架构快照。
- Cargo workspace 包含 22 个 `plsql-*` 引擎和分析 crate,以及 5 个
工具二进制文件(`crates/`, `tools/`)。无引擎的 MCP server 核心(8 个
`oraclemcp-*` crate:协议、工具注册表、失败即关闭的 SQL 守卫、
审计接收器、认证、遥测、配置、错误封装)已被提取到
独立、已发布的 [`oraclemcp`](https://github.com/MuhDur/oraclemcp) 仓库中;
`plsql-mcp` 现在从 crates.io 使用它们。单向边界
(`oraclemcp-*` 从不导入 `plsql-*` 引擎 crate)在构造上保持不变,
并在 oraclemcp 仓库的 CI 中强制执行。基础层和
产品层已实现;实时 Oracle catalog 提取、
`verify`/CI 级联路径,以及 live-DB MCP 工具接口均受 feature gate 控制,并针对容器化的 Oracle 23ai 进行了测试
(`live-xe` 套件,`make demo-oracle-xe-ci`)。
- **USR Loop**(Layer 5)已端到端实现:
`plsql-accretion` 库、`usr-loop` 工具、sha 固定的
一致性门控、单调触发器,以及可重新运行的验收
证明 `scripts/usr_acceptance.sh`。
- API 在 1.0 之前可能会发生变化。
- `AGENTS.md` 描述了自动化 agent 如何在本仓库中工作。
## 快速示例
```
# 构建 workspace 并运行完整的 test suite
cargo build --workspace
cargo test --workspace
# Clippy 采用项目的 deny-warning 策略
cargo clippy --workspace --all-targets -- -D warnings
# 检查 MCP server 及其 machine-readable contract
cargo run -p plsql-mcp -- info
cargo run -p plsql-mcp -- --robot-json capabilities
# 针对一个 estate 驱动 USR Loop(原地读取,不复制任何内容)
cargo run -p usr-loop -- scan /path/to/estate
cargo run -p usr-loop -- cluster /path/to/estate
cargo run -p usr-loop -- propose /path/to/estate --from-scan
cargo run -p usr-loop -- doctor
# USR Loop 的可重运行 Definition of Done
scripts/usr_acceptance.sh
```
## USR Loop(自愈性覆盖率飞轮)
大多数分析器会将解析错误和未解析的引用视为失败并丢弃。
而本工具将它们记录为类型化的、有来源的、可最小化的离线
工件,然后对其进行修复。完整的规范标准定义在
`docs/plans/2026-05-19-usr-loop-self-healing-coverage-flywheel.md` 中;
修复类策略和门控诚实性清单在
`docs/decisions/D3-usr-repair-class-policy.md` 中。
```
estate (read in place; no byte copied out)
│ plsql-engine analyze → typed diagnostics + UnknownReason + provenance
▼
[A] GAP CAPTURE filter repairable diagnostic classes → GapRecord
▼ (provenance only, never source bytes)
[B] MINIMIZE + smallest input that still triggers the same
PRIVACY-PROVE signature; every literal/identifier re-synthesized;
▼ a redaction-delta manifest proves zero leak
[C] CLUSTER/DEDUP N occurrences → 1 GapCluster, K representative
▼ fixtures
[D] PROPOSE one candidate diff, exactly one repair class
▼ (g grammar / l lowering / d typed degradation)
[E] CONFORMANCE GATE the 9-stage, fail-closed, sha-pinned bar
▼ pass ▼ fail
[F] LAND + LEDGER [F'] QUARANTINE-AS-OPEN-BEAD
apply on branch, file a provenanced bead naming the failing
add the fixture + stage; the gate is never weakened to admit it
a pinned test,
append one
content-addressed
ledger entry
▼
[G] ACCRETION TRIPWIRE the monotone coverage_index, CI-checked
```
### 不变量(规范的核心;每一项都被强制执行,而非空想)
| 不变量 | 它的保证 |
|-----------|--------------------|
| **I-PRIVACY** | 不会有任何客户的字节离开当前环境。每个持久化的工件都是重新合成的、结构等价的最小重现,并证明每个工件都不会泄露(门控阶段 G8)。隐私证明失败将中止运行且不进行任何持久化。 |
| **I-NO-REGRESSION** | 只有在被证明在整个语料库中保持行为一致时,补丁才会被合并:无损往返、后端一致性、黄金同构、单调非回归。提议、证明,然后合并;绝不自动合并未经验证的内容。 |
| **I-NO-GAMING** | 覆盖率的增加只有在目标签名的提取语义也有相应且可度量的提升时才算数。通过抑制诊断来“修复”缺陷会在 G7 阶段被自动拒绝。 |
| **I-DETERMINISM** | 相同的环境加上相同的引擎 commit 会产生字节完全相同的缺陷记录、fixture、签名和候选集。任何持久化的工件中都不包含挂钟时间、RNG 或 map 迭代顺序。 |
| **I-PROVENANCE** | 每条记录、fixture、候选、判定和落地的补丁都是内容寻址的,并将环境运行追溯到诊断、fixture、差异比对,再到门控结果。账本是只追加的。 |
| **I-ISOLATION** | 补丁仅触及 `.g4` 语法、`plsql-parser-antlr` 代码生成 / 底层转换,或类型化降级分类器;从不使下游 crate 依赖 ANTLR 类型,或以非附加方式破坏公共契约。 |
| **I-MONOTONIC-VALUE** | 被追踪的 `coverage_index` 在各个版本之间是单调非递减的。降低该指数的版本将无法通过 CI。 |
### 一致性门控
`scripts/usr_gate.sh` 运行九个有序阶段,必须全部通过,失败即关闭。
任何未通过的项都会拒绝候选并将其作为 bead 归档;门控
绝不会为了接纳补丁而被削弱。
| 阶段 | 检查 |
|-------|-------|
| G1 | 构建:`plsql-parser-antlr --features antlr-codegen` 和 workspace |
| G2 | 在完整语料库和每个先前的 MinFixture 上进行无损往返 |
| G3 | 后端一致性(`plsql-parser/tests/conformance.rs`) |
| G4 | 黄金同构,或明确列出并说明理由的黄金差异 |
| G5 | 绝不 panic 加上模糊测试目标,零崩溃 |
| G6 | 单调非回归(`scripts/estate_correctness.sh`,指标等于或高于基准) |
| G7 | 反作弊和诚实性:诊断仅在提取相应增加时才下降;姿态未被削弱 |
| G8 | 隐私:在候选和每个添加的 fixture 上验证脱敏差异;出现泄露将中止运行 |
| G9 | 添加的回归测试被变异测试消灭(如果回滚补丁则会失败) |
门控脚本已进行内容固定:`crates/plsql-accretion/gate.sha256`
保存了预期的 `sha256`,并且 `plsql-accretion` 的门控运行程序在出现不匹配时会中止。更改门控需要经过深思熟虑的、由人工审查的 commit
以及 sha 更新。`crates/plsql-accretion/tests/gate_selftest.rs` 向
门控输入一个对抗性三元组(一个仅抑制的补丁、一个泄露隐私的
fixture、一个破坏往返的补丁),并断言每一项都在其指定的
阶段被拒绝。
### `coverage_index` 和触发器
```
coverage_index = extracted_semantics_ratio (frozen public corpus
benchmark, never
private estate code)
+ distinct_resolved_gap_signatures (signature classes the
loop has permanently
closed, from the
append-only ledger)
```
`scripts/accretion_tripwire.sh`(一项必需的 CI 检查)断言
`coverage_index(HEAD) >= coverage_index(上个发布标签)`。降低该指数的发布将会失败。随时间变化的 `coverage_index` 表存在于
`CHANGELOG.md` 中;第一次发布确定性地为单调底线
播下了种子。
### 完成定义
`scripts/usr_acceptance.sh` 是唯一可重新运行的验收契约。
它不是“看起来构建好了”的检查:它驱动循环端到端地关闭一个私有的
当前环境中实际存在的缺陷,并断言每个
不变量都保持不变(来源、隐私安全 fixture、门控退出码 0 或正确的
隔离、严格的签名减少、严格的 `extracted_semantics_ratio`
增加、保持的姿态、账本仅追加一次、变异消灭的
测试、对抗性门控自测通过、两次运行字节完全一致)。当
未配置私有环境时,脚本退出码为 0,并显示醒目的
“estate-absent”横幅,表明在该环境中未验证 DoD。CI 每天晚上运行完整的验收证明
(`.github/workflows/usr.yml`)。
## 架构
workspace 是分层的(详情见 `plan.md` §5 和
`docs/ARCHITECTURE.md`)。下游 crate 绝不依赖于 ANTLR 生成的
类型。
| 层 | Crate | 职责 |
|-------|--------|--------------|
| 0 | `plsql-core`, `plsql-output`, `plsql-render`, `plsql-store` | 诊断、完整性/不确定性、输出形状、内容寻址缓存 |
| 1 | `plsql-parser`, `plsql-parser-antlr` |后端无关的解析器接口加上 ANTLR 后端 |
| 1.5 | `plsql-catalog` | Oracle catalog 快照模型以及实时提取 |
| 2 | `plsql-ir`, `plsql-symbols`, `plsql-privileges`, `plsql-depgraph` | 语义 IR、名称解析、权限模型、依赖图 |
| 3 | `plsql-engine` | 编排:单次运行的 `AnalysisRun`、`CompletenessReport` |
| 4 | `plsql-lineage`, `plsql-doc`, `plsql-bindgen`, `plsql-cicd`, `plsql-sast` | 血缘、文档、Rust 绑定、变更集规划、静态分析 |
| 5 | `plsql-mcp`, `plsql-accretion` | 统一的 MCP server 加上 USR Loop 库(无反向依赖) |
| MCP core (外部) | `oraclemcp-core`, `oraclemcp-guard`, `oraclemcp-db`, `oraclemcp-audit`, `oraclemcp-auth`, `oraclemcp-telemetry`, `oraclemcp-config`, `oraclemcp-error` | 无引擎 MCP server 核心:协议/注册表、失败即关闭的 SQL 守卫和操作级别状态、连接层、带外审计接收器、传输认证、遥测、配置以及结构化错误封装。`#![forbid(unsafe_code)]`;从不导入 `plsql-*` 引擎 crate(单向边界)。**已提取到独立的 [`oraclemcp`](https://github.com/MuhDur/oraclemcp) 仓库并从 crates.io 引用**:`plsql-mcp` 依赖于已发布的 `oraclemcp-core`/`-guard`/`-error`,而不是 workspace 内的副本 |
```
PL/SQL source + Oracle catalog snapshot
│
▼
plsql-parser-antlr (lossless tape + AST)
│
▼
plsql-ir → plsql-symbols → plsql-depgraph
│
▼
plsql-engine: AnalysisRun + CompletenessReport
│ │
▼ ▼
product surfaces typed UnknownReason exhaust
(lineage / docs / │
bindings / cicd / ▼
sast) plsql-accretion + usr-loop
(capture → fixture → gate → land)
```
工具二进制文件:`tools/usr-loop`(USR Loop 编排器)、
`tools/plan-lint`(`plan.md` 的结构化 lint)、
`tools/corpus-license-check`, `tools/corpus-bench`, `tools/corpus-grow`。
MCP server(`plsql-mcp`)是基于无引擎
`oraclemcp-*` 核心构建的单个二进制文件。它完成 MCP 握手,通过 `tools/list` 宣告完整的
工具接口 —— 每个工具都带有真实的参数
JSON-Schema 和只读 / 破坏性标注 —— 并端到端地调度
`tools/call`:静态分析和变更影响工具在进程内执行;当未配置活动的
Oracle 连接时,live-DB 工具会进行调度,并以类型化的
`RuntimeStateRequired` 响应(指出下一步要调用的工具)进行降级。零参数的
`oracle_capabilities` 工具会报告 feature flag 和接口,以便 agent
在第一次调用前就能了解情况,而失败的调用会返回
结构化的错误封装,带有机器可读的类别和模糊的
“did you mean” 建议。锁步测试确保注册表宣告的每个工具都有
一个调度分支。
## 安装
workspace 使用 `rust-toolchain.toml`(`nightly-2026-05-11`)中固定的 nightly 版本进行构建和测试。由于 live-DB 收敛工作依赖于
nightly 专属的 `asupersync` 特性,因此目前没有稳定的 MSRV 或
`rust-version` 基线。
### 从源码构建(推荐)
```
git clone https://github.com/MuhDur/plsql-intelligence
cd plsql-intelligence
cargo build --workspace --release
```
### 安装单个二进制文件
```
cargo install --path tools/usr-loop
cargo install --path crates/plsql-mcp
```
### 按 crate 迭代
在开发过程中,按 crate 构建可以保持较短的周期:
```
cargo build -p plsql-catalog
cargo test -p plsql-accretion
```
MCP 的 `live-db` feature 会拉取可选的 Oracle 驱动程序,并在运行时需要
Instant Client;有关各平台的设置,请参见 `docs/integrations/live-db/`。
## 命令参考
### `usr-loop`
USR Loop 编排器。全局的 `--robot-json` 标志会在每个子命令上发出单行
机器可读的封装。
```
usr-loop scan 标签:Oracle PL/SQL, Rust, SOC Prime, WebSocket, 代码智能, 依赖分析, 变更影响分析, 可视化界面, 开发工具, 网络流量审计, 请求拦截, 通知系统, 错误基检测, 静态代码分析