Skip to content
AH23333Public

About

Vibe project Restruct Pipe

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

255 Commits

Folders and files

Repository files navigation

vrp — Vibe 项目重构分析管道

面向通用 AI 的 vibe 项目重构分析管道:把 AI 堆出来的仓库变成有事实基础、可验证、可执行重构的对象。

  • 主用户:通用 AI agent(不绑定特定 Agent/MCP 框架)——产物是文件与数据库,不是服务
  • 辅用户:vibe 开发者(人类)——两条消费线分开:AI 消费深层数据(facts.db/MCP),vibe 开发者消费 report/chain 用户产物(AI 梳理职责/层规则/病理体检报告),目标是「理解项目、判断梳理意见、做决定」
  • 纯 Python 标准库(≥3.11,零第三方运行时依赖),全管道 CLI 子进程化、可审计可重放

管道一览

S0 precheck ─→ S1 CBM 索引 ─→ S1.5 ETL(facts.db) ─→ xcheck 交叉验证
                    │
                    ├─→ S2 病理检测(ast-grep/死代码/变异三引擎/P4·P2 补位)
                    ├─→ S3 校验器组(锚定/覆盖率/证据闸门)
                    ├─→ S4 freeze(基线快照 + 变更预筛)
                    ├─→ S5 dossier(五视图装配 + repomap + 任务型预算)
                    ├─→ S6 重构事务(G1-G5 闸门 + git 原子提交/回滚)
                    ├─→ S7 enforce(架构执法:21 引擎违例 → P9 findings)
                    └─→ S8 report(archify 报告 + SARIF/Mermaid 降级链)

核心产物:<repo>/.vrp/facts.db(规范化事实层 + 注解宿主)与 dossier.json(信息架构装配);重构事务(T1 重命名/T2 删死码/T3 建调用方/T4 内容微调)在其上声明、验证、执行。

安装

pip install -e .                       # 纯标准库,无第三方依赖
$env:CBM_CACHE_DIR = "D:\cbm-cache"    # CBM 缓存目录(必须显式设置)

环境自举(work/ 工具沙箱重建)

外部工具全部钉版本收录在 bootstrap.py(纯标准库):六个 npm 沙箱 (ast-grep/knip/jscpd/Stryker/repomix/code-atlas)+ difftastic 0.72.0 下载解压 + pytest/mutmut/vulture 及深度测试依赖。work/ 不入 git(~600MB),删掉后一条命令重建:

python bootstrap.py                    # 幂等:已装则跳过
python bootstrap.py --skip-npm --skip-pip --skip-difft   # 只看就绪状态报告

前置:Python ≥ 3.11、Node.js + npm、git。系统级手动安装项: CBM(S1 索引核心,0.12.1)、 Node.js。cargo-mutants 可选(--with-cargo-mutants 开关,需 Rust 工具链)。

快速开始

vrp run <repo>                          # S0→S1→ETL→xcheck 全管道
vrp s2 <repo>                           # 病理检测(findings + 差异登记簿)
vrp mutate-run <repo> --budget N        # 变异执行(Python/TS/Rust 三引擎)
vrp dossier <repo> --task T1            # 五视图装配(T1-T4 预算)
vrp transact <repo> tx.json             # 重构事务(声明→闸门→原子提交或回滚)
vrp transact <repo> tx.json --preview   # diff 预览(difflib+difftastic 工具组,无闸门不改树)
vrp verdicts <repo>                     # verdict 历史(open 项自动回馈进 dossier evidence)
vrp curate <repo>                       # AI 梳理工件验收入库(.vrp/ai/ slices/structure;--reject 用户否决留痕)
vrp curate-auto <repo>                  # 内置 LLM 梳理循环(零 agent 路径):配好 .vrp/config.json 的 API key 即自动跑 dossier→slices→structure→enforce→drift(契约 §6;全自动+全留痕 .vrp/auto/)
vrp drift <repo>                       # 梳理工件漂移查询面(只读):stale 原因 + fid_ledger 反查重定位候选 remap;stored active 实际漂移 → rc=1
vrp remap <repo>                       # 漂移恢复半自动环:drift 的唯一候选 remap 一键写回 .vrp/ai/*.json(unresolved 诚实上报 → rc=1;再跑 vrp curate 复活)
vrp refresh <repo>                     # 漂移恢复一键环:S0→S1→ETL→xcheck→drift→remap→curate→report(代码变更后工件全链路自动追平)
vrp seams <repo>                       # 缝合线查询面(#143,只读,学 unwind seams):active structure 模块间跨界边聚合(总数/by_type/top 边样本/未分配与内部计数)——模块依赖图原料(strangler 重建顺序)
vrp propose <repo>                     # 重组切片提议(#143,学 unwind slices propose):确定性分区草案(顶层目录播种+边权贪心凝聚+平衡帽)→ .vrp/proposals/structure-proposal.json(curate structure 输入格式;不在 .vrp/ai/ 不旁路 curate——采纳=改写后放 .vrp/ai/ 全量重验)
vrp traces <repo> --file f.json [--label L]  # 运行时调用证据导入(#144,学 CBM ingest_traces):观测调用路径/裸对(qn 键,reindex-proof)→ facts.db runtime_calls 独立表(不并入静态 facts,CALLS 边/视图零动);per label 整批替换(CBM "whole runs age out together");收据带对账三分类(agreed/observed_only=静态漏报信号/static_only=死代码佐证);写入经 _open_facts_rw(M4 硬闸)
vrp coverage <repo> [--path P ...] [--kind K ...]  # 索引完备性核验面(#145,只读,学 CBM check_index_coverage):引用 graph 文件前先核验——--path 逐路径 status 六态(unusable/partial/unresolved_calls/skipped/excluded/no_recorded_issue)+recommended_action(exact+祖先目录匹配,cap 128);无 --path=coverage_gaps 盘点(kind 分布+样本);no_recorded_issue 非完备证明(clean means no recorded gap)
vrp impact <repo> [--base B] [--path P ...] [--depth N] [--direction D] [--no-tests]  # 变更影响+建议测试查询面(#146,只读,学 CBM detect_changes/test_impact):默认 worktree 相对 HEAD diff hunk 行区间重叠播种(--base=merge-base..HEAD∪worktree;--path=显式播种跳过 git;零重叠/hunk cap 超限回退整文件播种——绝不静默欠播种)→ 多源 BFS 影响面(CALLS/CALL_REFERENCE,depth clamp 15,行 cap 5000 触顶 saturated 诚实)→ 建议测试(test_linkage 消费按测试文件聚合);suggested ≠ sufficient——建议面非 gate 面,全量测试由消费方决定
vrp enforce <repo>                      # S7 架构执法:curate 入库的 structure 按语言路由执行(.py→import-linter;.ts/.js→dependency-cruiser;.go→go list 原生导入图;.rs→内置 use 解析器;.java→内置 package/import 解析器;.cs→内置 namespace/using 解析器;.kt→内置 package/import 解析器;.c/.cc/.cpp→内置 #include 解析器;.php→内置 namespace/use 解析器;.scala→内置 package/import 解析器;.rb→内置 module/require 解析器;.dart→内置 import 解析器;.swift→内置 Package.swift target 解析器;.zig→内置 @import 解析器;.lua→内置 require 解析器;.m/.mm→内置 #import 解析器),违例落 P9 findings
vrp report <repo>                       # S8 静态报告(.vrp/report/:IR+SARIF+Mermaid+archify html+fusion.html 融合报告(构想v9 V-2:六风格单页总览——仪表盘/叙事/结构图/下钻/双引擎对账/数据切片,vendored ECharts 零外链,chain 同批联动行级跳转 #L{n},主题令牌与 chain 同源三预设);R7' 多级颗粒度——archify 图链成功出 chain/(替代 L1/L2),否则 L1 模块页+L2 符号页;archify 缺失降级不阻塞;用户产物信息架构——How to read/Project overview(AI 梳理职责+层规则)/Pathology checkup(P 码人话体检)/Deep data 折叠(AI 材料归拢);报告产物密钥卫生——chain 源码页命中高置信密钥探测器(云 token/JWT/私钥块/URL 凭据)渲染层掩蔽 [VRP-MASKED:type:preview…](行数不变 #L 锚点保持),命中清单落 .vrp/SECRETS.local.md 本地勿提交;finding 影响面——切片行锚定符号调用图 BFS 直达/传递可达(dc/dx/uc/xc+top 调用方/被调名单),BFS 帽截断下界诚实注记,无锚行注记不可算))
vrp session <repo> begin|end|report     # 全信任模式(§3.3):初末 facts.db 快照 → 计数 diff + 双 L0 图并排 + verdict 时间线

CLI 命令

命令 用途
precheck git 快照/语言普查/命令发现
index / status CBM 索引(缓存)/ 状态查询
etl CBM → facts.db 五级证据路由
xcheck code-atlas 四元组交叉验证 → 差异登记簿
run S0→S1→ETL→xcheck 一发
s2 病理检测:ast-grep 9 规则 + 死代码 + knip/vulture + jscpd
mutate-plan / mutate-run 变异预算采样 / 变异执行(mutmut·Stryker·cargo-mutants)
validate / gate 锚定+覆盖率校验 / AI claim 证据闸门
freeze 基线命令执行 + graph 快照 + 变更预筛
dossier 七节装配(架构/简报/repomap/五视图/证据/摘要/rawpack 指针)
transact / transact-batch 重构事务单发(--preview diff 预览)/ 目录批处理
verdicts verdict 历史查询(--tid 单条详情;dossier evidence 自动内嵌 open 项)
curate AI 梳理工件验收(slices/structure 确定性验证全过才入库;--reject 否决留痕 decisions 表;复验失效标 stale)
curate-auto 内置 LLM 梳理循环(零 agent 路径,构想v7 §13):.vrp/config.json 配 OpenAI-compatible API key → 自动六步(dossier 取材→slices→structure→enforce→drift→summary);无 function calling(确定性校验器即工具,拒收回执重试≤3);循环只走 curate 数据面不触重构事务;全自动+全留痕 .vrp/auto/(key 不落盘)
drift 梳理工件漂移统一查询面(只读):每次 etl/事务 promote/MCP 提交自动复验(F2 假 active 窗口已关);drift 逐条给 fresh/missing_fids/missing_edges + fid_ledger(fid 身份史,跨 etl 存续)反查重定位候选——qn 未变给 remap 映射,qn 消亡给同文件域候选(cap 10);remap 是提议不旁路,重提仍全量重验;stored active 实际漂移 → 退出码 1
remap 漂移恢复半自动环:drift 的唯一候选 remap 一键写回 .vrp/ai/*.json 工作工件(只改 fid 引用不触 facts.db);多候选/无候选/文件缺失 → unresolved 诚实上报 rc=1;写回后 vrp curate 全量重验复活 active
refresh 漂移恢复一键环:S0→S1→ETL→xcheck→drift→remap→curate→report(代码变更后 curate 工件全链路自动追平;remap unresolved 或 curate 拒收 → rc=1)
enforce S7 架构执法(构想v7 §4/§8.2/§9):structure(active) → 层 DAG+rules 生成 forbidden 契约 → 按语言路由执行——.py→import-linter(VRP_IMPORT_LINTER_BIN 覆盖);.ts/.tsx/.js/.jsx/.mjs/.cjs→dependency-cruiser(typescript 5.9.3 钉版沙箱,VRP_DEPCRUISE_BIN 覆盖);.go→go list 原生导入图(go list -e -json,传递闭包 BFS 最短链,go.mod module 指令四形态 mini-parse(裸/带引号/行首缩进/括号块——go 1.26 探针实证,未闭合块拒绝、// 注释剥离,BOM go.mod 工具链拒绝真值对齐),根包锚定文件路径无 "./" 前缀,嵌套 internal/vendor 是真实包不计 vendor(仅模块根 vendor/ 跳过=go list 排除对齐),VRP_GO_BIN 覆盖);.rs→内置源级 use 解析器(纯 stdlib 零工具链依赖,mod 树+传递闭包 BFS 最短链,生产行内 mod use 边计入(use 视图行内体保留+ctx 走查器下钻,self/super 相对路径解析 super=enclosing,边归属性=所在文件模块——rustc 探针实证),macro_rules 定义体跳过(模板非真实边——定义体内 use 不误计、模板 mod 声明不入树),普通串跨行合法(kt/cs/java 未闭合串行截断家族修法不适用——rustc 探针实证),cfg(test) 排除,glob 导入不展开(边指 glob 根——诚实局限),orphan .rs 诚实计数);.java→内置源级 package/import 解析器(纯 stdlib 零工具链依赖,容器=Java 包,Java 自由格式——package/import 段间点号两侧空白/换行宽容+捕获组去空白(javac 21 探针实证),文本块转义感知扫描(转义引号技巧产出裸三引号不提前闭合——javac/jshell 21 探针实证),未闭合普通串换行截断(JLS 3.10.5 串内禁换行),4 连引号开符缺行终止符走串分支优雅降级,/test/java/ 测试源根排除,传递闭包 BFS 最短链,orphan 无包文件诚实计数);.cs→内置源级 namespace/using 解析器(纯 stdlib 零工具链依赖,容器=C# 命名空间,自由格式段间空白/注释宽容+global:: 限定符支持(dotnet 9 探针实证),未闭合普通串换行截断(C# 普通串不得含字面换行——CS1010),空串/转义首字符 off-by-one 防吞码,tests 测试目录排除,传递闭包 BFS 最短链,orphan 无命名空间文件诚实计数);.kt→内置源级 package/import 解析器(纯 stdlib 零工具链依赖,容器=Kotlin 包,/test/kotlin/ 测试源根排除,嵌套块注释/raw string/分号可选/as 别名词法,声明终止 `[;\r\n]
report S8 静态报告:三 IR(architecture/sequence/timeline)→ archify validate+render(缺失降级 Mermaid-only)→ .vrp/report/(report.html 无时间戳字节级复现+SARIF 2.1.0);R7' 多级颗粒度(构想v7 §11):archify 模块交互图链成功 → chain/ 静态多页互链(dataflow/目录树/符号网格/整文件源码页=唯一代码视图,三段式原子提交失败降级)替代 L1/L2;失败/缺失 → L1 模块页(modules/)+ L2 符号页(symbols/)互链兜底;V-2 融合报告(构想v9 §11):fusion.html 六风格单页总览(仪表盘/叙事/结构图/下钻/双引擎对账/数据切片;纯 stdlib FR 布局确定性;vendored ECharts 5.6.0 零外链;chain 同批联动行级跳转 #L{n}(render_chain 行级锚点+file_caps);主题令牌与 chain 同源三预设(render_theme 单一权威));渲染 chrome 全英文,数据(模块名/AI 梳理职责)原样
session 全信任模式(构想v7 §3.3):begin/end 出初末 facts.db 快照(sqlite backup 安全复制),report 出初末计数 diff(四组)+ 双 L0 架构图并排 + 会话窗口 verdict 时间线;不做图 diff(诚实版)
mcp AI 接口层:MCP server over stdio(per-repo;pip install vrp[mcp];nav_/curate_/tx_/render_/session_*/enforce/query_facts/drift_report/dossier/seams/coverage/impact 三十件)

重构事务与闸门

事务失败即整体回滚(git 原子性),verdict 落 .vrp/verdicts/:

闸门 检查 稳定规则码
G0 apply 前置校验 gate/G0/apply-edits
G1 提交后重索引(旁路 ETL) gate/G1/parse-errors
G2 lint/typecheck gate/G2/static-check
G3 测试套件 gate/G3/test
G4 声明等价:五信号——符号集/使用边/悬垂引用/verify_changes/difftastic 结构 diff(同符号体内偷改可抓) undeclared-change edge-mismatch dangling-reference verify-broken structural-change
G5 死代码单调性 gate/G5/dead-code-increase
G6 git 提交失败→回滚树+诚实 aborted 裁决(提交先于记账:如全 no-op edits 无可提交,绝不留 DB=committed 却无 git 提交的假象) gate/G6/commit-failed

外部信号缺失/超时一律诚实降级(skipped / 诚实记录),不伪造结果。

测试

python -m pytest -q                        # 快速层 1505 例 ~4-8min(默认排除 deep)
python -m pytest -m deep -q                # 深度层 1523 例 ~15-30min(真实工具全外链 E2E)
python -m pytest -m "deep or not deep" -q  # 全量 3028 例(阶段性完工验收)

深度层含:双仓基准(TS 1887 符号 / Python 66132 符号·25 万边)、序贯事务 E2E、闸门假阳性性质(合法 rename 零误报×15、丢边加边必抓×25)、fuzz、五视图污染清扫、freeze 字节级复现、三语言变异执行 E2E、difftastic G4 E2E。

发布

开发与测试全在本地完成(工具链沙箱、verify 仓、CBM 缓存均为本地资源);GitHub(AH23333/VRP)仅作 push 与 release 目标,不做 CI/Actions。

  • 本地门禁:.githooks/pre-push(git config core.hooksPath .githooks 激活)——推送前快速层 1505 例全绿才放行(~4-8min);跳过用 git push --no-verify
  • 发布:GitHub release API 打 tag 发版(v0.1.0 起)

外部工具(可选,缺失则降级)

CBM(索引)、code-atlas(交叉验证/MCP)、ast-grep、mutmut 2.4.5 / Stryker 10.1.1 / cargo-mutants(变异)、difftastic 0.72.0(结构 diff)、knip / vulture / jscpd、repomix(rawpack)、archify v3.2.0(S8 渲染,bootstrap.py --with-archify 装,VRP_ARCHIFY_MJS 覆盖)。二进制沙箱化于 work/,路径可用环境变量覆盖(VRP_*_BIN / VRP_DIFFTASTIC_BIN 等)。

  • 子进程 CPU 优先级(#147,学 TSA local_low_impact):重型子进程(CBM 索引/变异引擎/freeze 基线/archify 等 procs.run_tree 全链+s4_freeze/s5_cabrief 流式通道)默认 BELOW_NORMAL(Windows creationflags 0x4000 纯 stdlib)/nice -n 15(POSIX,which 探测缺失回退)——不抢占交互前台,空闲机满速、争时机让位,只影响调度不影响结果(确定性零影响)。逃生门:VRP_CHILD_PRIORITY=normal 恢复普通优先级(专用 CI 机/基准场景)。

文档(docs/)

  • 《产品目标.md》——定位与成功判据(主流程四环)
  • 《构想v6-核验后S1-S5定稿.md》——S1-S5 权威技术方案(§12-13 为实测/实施记录)
  • 《构想v7-AI梳理层与S7-S8定稿.md》——当前权威:主流程四环/MCP 接口层/curate/S7-S8/批次 R1'-R4'
  • 《构想v8-多层级下钻展示层.md》——展示层历史:多层级下钻(网格/代码页/rel 条/目录树),V-0→V-0.9 全程实录
  • 《构想v9-融合报告形态.md》——展示层当前权威(定稿候选):六风格融合报告形态(仪表盘+叙事+力导向图+下钻+对比+数据切片,单 HTML 静态),V-9 原型待拍板
  • 《渲染层方案.md》——archify 渲染层方案
  • 《跨项目实测报告-2026-11-10.md》——跨项目实测
  • 《契约/事务契约.md》——事务 schema/G 码对照/生产指南(AI 生产方必读)
  • 《契约/梳理工件契约.md》——梳理工件(slices/structure)schema 唯一权威格式说明(AI 生产方必读,配置 skills/vrp-curation/ 生产指南)
  • 《交接文档.md》——接手即读(环境/E2E 基准数字/代码地图/下一步)
  • 《踩坑历史.md》——实测坑与纪律
  • 构想 v1-v6——历史方案,只读

平台

主开发环境 Windows + PowerShell 5.1;Python ≥3.11;产物尽可能落 D 盘。

About

Vibe project Restruct Pipe

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages