BCC 架构闭环迁移计划（Rust 主线）

更新时间：2026-02-14

1. 目标（双主线，不混用）

本计划拆成两条线，避免把 bugfix 当成唯一主线：

新项目主线（Greenfield）

从设计输入出发（模块/端口/关系），直接产出可执行 BDD 基线。
不依赖历史提交记录。

存量项目补强线（Brownfield）

从现有代码 + 历史提交（含 bugfix）提炼回归场景。
为主线补充真实缺陷覆盖。

最终原则：Rust CLI 是主线，TypeScript 脚本只做过渡桥接。

2. 当前现状（事实）

已在 Rust（BCC 主线）：

bcc extract：tree-sitter 多语言结构提取（Elixir/TypeScript/PHP）。
bcc trace：文档覆盖审计。
bcc bugfix：历史 bugfix -> 场景 DSL（collect/context/generate/organize）。

仍在 TypeScript（过渡资产）：

scripts/audit-backend-ast.ts
scripts/audit-backend-trace.ts
scripts/backend-docs/trace2contract-*
scripts/openclaw-backend-docs/*（与部分脚本重复）

关于 BDDC 执行模型（必须明确）：

BDDC 不是“单命令全自动替代人决策”。
实际是“Agent/提示词驱动实现 + bddc 命令门禁验收”：
- annotations.check
- registry.scaffold/upsert
- instructions.docs
- domain.autowire
- check

TS 辅助脚本能力清单（已按脚本核对）：

结构事实抽取

audit-backend-ast.ts
能力：输出 backend-docs-ast.json/.md，含导出、依赖、调用、副作用。

文档覆盖审计

audit-backend-trace.ts
能力：输出 backend-docs-audit.{json,md,tsv}，支持缺口 seed。

架构映射与门禁（arch 迁移主目标）

trace2contract-map.ts
trace2contract-v2-research.mjs
trace2contract-v3-validate.mjs
能力：模块映射、关系矩阵 diff、target/transition/gates 回放。

文档生产与质量审阅

fill-backend-trace-docs.ts
render-backend-trace-docs.ts
build-review-queue.ts
build-review-samples.ts
audit-review-quality.ts
validate-callchain-ast.ts
codex-manual-review-*.sh

npm 入口（openclaw 现状）

docs:trace:ast / docs:trace:ast:write
docs:trace:status / docs:trace:report
docs:trace:fill / docs:trace:render
docs:trace:queue / docs:trace:quality / docs:trace:samples
docs:trace:t2c:map

迁移边界（避免混淆）：

bcc arch 优先承接第 3 类能力（映射/矩阵/门禁）。
第 1/2 类可并入 extract/trace 演进。
第 4 类属于“文档生产工具链”，不是 arch 核心阻塞项。

3. 目标链路（双链路闭环）

3.1 新项目主线（Greenfield）

bcc compile ... / bcc arch matrix ...
输入设计 DSL，形成模块边界与关系约束。
bcc arch validate ...
校验设计与实现演化的一致性（target/transition/gates）。
bcc bdd seed ...
从模块端口/契约生成“场景种子包”。
Agent 执行 BDDC 相关技能（注解/指令/DSL 场景补齐）。
bddc check ...
编译 + lint + 测试门禁。

说明：新项目主线不依赖 bugfix。

3.2 存量项目补强线（Brownfield）

bcc extract ... + bcc arch validate ...
获取真实依赖与架构偏差。
bcc arch export-module-map ...
导出模块映射（供 bugfix 消费）。
bcc bugfix ...
从历史修复生成回归场景（增量覆盖）。
Agent 修订与归并场景。
bddc check ...
纳入统一门禁。

说明：bugfix 是补强线，不是主线。

4. 两条线产物必须对齐（硬约束）

新项目线与 bugfix 线最终都必须落到同一场景包结构，保证可并轨：

contexts/：上下文输入（JSON）
scenarios/：原子场景（.dsl）
features/：按模块归并后的场景（.dsl）
coverage.md：按模块覆盖统计

也就是说：

新项目线新增的 bcc bdd seed 产物，最终要能进入与 bcc bugfix generate/organize 相同的后续路径。
不能出现两套不兼容目录结构或两套不兼容 DSL 封装格式。

5. Rust 实现状态（v0）

5.1 `bcc arch`（已实现）

bcc arch matrix

输入：模块边界、规则 seed、关系约束。
输出：target.yaml、transition.yaml、gates.yaml。

bcc arch validate

输入：target/transition/gates + 实际依赖矩阵。
输出：scenario-validation.tsv、gate-evaluation.tsv、validation-report.md。

bcc arch export-module-map

输出：module_map.json（兼容 bcc bugfix --module-map 所需结构）。

bcc arch report

输出架构债务与优先级（blocked/temporary/keep）。

5.2 `bcc bdd seed`（已实现 v0）

建议：bcc bdd seed

输入：模块/端口/关系/约束（来自 compile + arch）。
输出：对齐第 4 节的统一场景包结构（至少 contexts/ + scenarios/ 初稿）。
由 Agent 补全语义细节后，再进入 organize 与 bddc 门禁。

5.3 统一数据模型（最小）

module_registry：模块边界/职责/层级。
relation_actual：实际模块依赖（提取聚合）。
relation_target：目标允许/禁止关系。
relation_transition：迁移期临时放行/阻塞关系。
gates：验收阈值（unexpected、forbidden、密度、双向对）。
scenario_pack_meta：场景包版本与来源（design/bugfix）。

5.4 仍待完成（v1+）

迁移完成后：

下线 scripts/openclaw-backend-docs/* 重复副本。
将 TS 辅助脚本从主验证链路剥离，Rust 产物作为架构评估与回归基线。

5.5 下一个迭代缺口（v2+）

结合当前 TS 原型脚本（audit-backend-ast.ts / audit-backend-trace.ts）与 Rust 现状，下一批建议优先补这 5 项：

仓库级 AST 快照命令

现状：bcc extract 以单文件为单位。
缺口：缺少“一次扫描仓库并输出 backend-docs-ast.json 口径”的命令。

trace2contract 事实层聚合

现状：bcc arch matrix/validate 需要外部喂 ast/actual JSON。
缺口：缺少从快照直接聚合 relation_actual/module_map 的内建子命令。

bdd seed generate 语义增强

现状：v0 为模板替换，已能产出统一目录结构。
缺口：尚未接入模型生成与质量回检（与 bugfix generate/check/fix 同口径）。

产物一致性治理

现状：bcc extract/arch 已形成稳定主链路。
缺口：CI 仍需更完整覆盖模块间约束变化边界（特别是复杂依赖的历史回归防线）。
目标：将边界变化与场景退化一并纳入主线门禁（沿用 cli_arch_bdd 与 bdd seed check 结果）。

验证命令的门禁策略配置

现状：arch validate 支持 --fail-on-gate / --fail-on-forbidden（布尔值）。
缺口：需要补一组 CLI 集成测试，确保 CI 中可稳定切换“严格门禁/报告模式”。

bdd seed 质量回检

进展：已增加 bcc bdd seed --step check|fix，产出 quality-check.json / quality-fix.json。
剩余：将 check 结果纳入主线 CI 门禁并做历史趋势对比。

6. 当前运行边界

现有实现使用 Rust 命令链路作为单一真值源：extract -> arch -> bdd。 TS 脚本保留仅作局部分析辅助，不进入主 CI 门禁，也不作为架构正确性判定依据。

7. 与 BDD 覆盖联动（必须落地）

架构整改不能只停在“图好看”，要进入行为验证：

blocked edge（必须移除）
每条至少 1 条反向保护场景（防回归）。
temporary edge（迁移允许）
每条至少 1 条过渡场景（限定可接受窗口）。
keep edge（长期保留）
关键链路保持主场景覆盖。

执行方式：

bcc arch validate 产出边清单。
新项目线用 bcc bdd seed，存量线用 bcc bugfix，两者都落统一场景包。
Agent 执行 BDDC 提示词/技能补全与修订。
bddc check 作为最终行为门禁。

BDD 覆盖口径（文档内固定，不靠口头约定）：

场景包结构口径

必须统一为 contexts/、scenarios/、features/、coverage.md。
bugfix 线由 generate/organize 直接产出该结构。
新项目线 bcc bdd seed 也必须产出同口径结构。

编译与运行口径

必须执行 bddc check（或等价链路），至少覆盖：
- compile（DSL -> 测试代码）
- lint（语义与规范）
- test（生成测试执行）
失败即门禁失败，不得仅提交“已生成 DSL”。

架构到场景的覆盖口径

blocked edge：每条至少 1 条防回归场景。
temporary edge：每条至少 1 条过渡期场景。
keep edge：关键链路保持主场景覆盖。
覆盖证据写入 coverage.md（或等价可追溯报告）。

Agent 执行口径

生成与修订由 Agent 执行（注解/registry/DSL）。
验收统一收口到 bddc check，不以“模型回答成功”代替测试成功。

8. 验收标准（Definition of Done）

迁移完成定义：

bcc arch 可独立完成矩阵生成、验证、导出。
新项目可不依赖 bugfix，直接从设计生成可执行 BDD 基线并通过 bddc check。
存量项目可通过 bugfix 持续补充回归场景并并入同一场景包。
两条线产物目录与 DSL 口径完全对齐（contexts/scenarios/features/coverage.md）。
bugfix --module-map 直接消费 bcc arch export-module-map 输出。
文档与 CI 默认路径指向 Rust 实现。

9. 判断（实话）

这条路可行且价值高。

你已具备 Rust 核心（extract/trace/bugfix），不是从零开始。
主要工作量在“命令整合 + 数据模型收敛 + 场景包统一 + 门禁收口”。
一旦落地，BCC 会从“分析工具”升级为“设计与存量双栈的架构/测试编译器”。

10. CLI 子命令与参数（v0 冻结版）

本节作为实现口径，先冻结命令名与参数语义。
实现阶段可以补参数，但不改已有参数含义（避免反复重命名）。

10.1 `bcc arch matrix`

用途：从模块规则 + AST 事实生成 target/transition/gates 初稿。

用法：

bcc arch matrix \
  --seed-file docs/backend-trace/module-registry.seed.yaml \
  --ast-file docs/backend-trace/artifacts/backend-docs-ast.json \
  --out-dir docs/backend-trace/trace2contract/seed \
  --version v3 \
  --emit all

参数（v0）：

--seed-file <PATH>：模块规则输入（必填）
--ast-file <PATH>：AST 快照输入（必填）
--out-dir <PATH>：输出目录（默认：docs/backend-trace/trace2contract/seed）
--version <STRING>：版本前缀（默认：v3）
--emit <all|target|transition|gates>：输出范围（默认：all）
--force：覆盖已有输出（默认关闭）

输出（v0 固定）：

<out-dir>/<version>.target-matrix.yaml
<out-dir>/<version>.transition-matrix.yaml
<out-dir>/<version>.gates.yaml

10.2 `bcc arch validate`

用途：用实际依赖回放 target/transition/gates，给出门禁结果。

用法：

bcc arch validate \
  --target docs/backend-trace/trace2contract/seed/v3.target-matrix.yaml \
  --transition docs/backend-trace/trace2contract/seed/v3.transition-matrix.yaml \
  --gates docs/backend-trace/trace2contract/seed/v3.gates.yaml \
  --actual docs/backend-trace/artifacts/trace2contract/versions/v1/relation_matrix.actual.json \
  --out-dir docs/backend-trace/artifacts/trace2contract/versions/v3-draft \
  --profile both \
  --fail-on-gate

参数（v0）：

--target <PATH>：target 矩阵（必填）
--transition <PATH>：transition 矩阵（必填）
--gates <PATH>：门禁规则（必填）
--actual <PATH>：实际关系矩阵（必填）
--out-dir <PATH>：输出目录（默认：docs/backend-trace/artifacts/trace2contract/versions/v3-draft）
--profile <target|transition|both>：回放范围（默认：both）
--fail-on-gate：任一 profile gate fail 时返回非 0（默认开启）
--fail-on-forbidden：存在 forbidden 边即返回非 0（默认开启）

输出（v0 固定）：

<out-dir>/scenario-validation.tsv
<out-dir>/gate-evaluation.tsv
<out-dir>/v3-validation-report.md
<out-dir>/summary.json

10.3 `bcc arch export-module-map`

用途：导出 bcc bugfix --module-map 可直接消费的 JSON。

用法：

bcc arch export-module-map \
  --module-map docs/backend-trace/artifacts/trace2contract/module_map.json \
  --module-registry docs/backend-trace/artifacts/trace2contract/module_registry.json \
  --out docs/backend-trace/artifacts/module_map.bugfix.json \
  --mapping-mode file

参数（v0）：

--module-map <PATH>：trace2contract module_map.json（必填）
--module-registry <PATH>：模块名来源（可选，默认自动探测）
--out <PATH>：输出文件（默认：docs/backend-trace/artifacts/module_map.bugfix.json）
--mapping-mode <file|dir>：映射粒度（默认：file）
--include-module-names：输出 module_names（默认开启）

输出 JSON 结构（v0 固定）：

{
  "mapping": {
    "src/foo/bar.ts": "gateway_control_plane"
  },
  "module_names": {
    "gateway_control_plane": "网关控制平面"
  }
}

10.4 `bcc arch report`

用途：汇总架构债务，给整改优先级报告。

用法：

bcc arch report \
  --scenario-validation docs/backend-trace/artifacts/trace2contract/versions/v3-draft/scenario-validation.tsv \
  --gate-evaluation docs/backend-trace/artifacts/trace2contract/versions/v3-draft/gate-evaluation.tsv \
  --summary docs/backend-trace/artifacts/trace2contract/versions/v3-draft/summary.json \
  --out docs/backend-trace/artifacts/trace2contract/versions/v3-draft/arch-report.md \
  --top 20

参数（v0）：

--scenario-validation <PATH>：scenario-validation.tsv（必填）
--gate-evaluation <PATH>：gate-evaluation.tsv（必填）
--summary <PATH>：summary.json（必填）
--out <PATH>：输出报告路径（默认：<out-dir>/arch-report.md）
--top <N>：输出 top N 重点边（默认：20）
--format <md|json>：输出格式（默认：md）

10.5 `bcc bdd seed`

用途：新项目主线的场景种子生成器；输出口径与 bugfix generate/organize 对齐。

用法：

bcc bdd seed \
  --source contracts/modules \
  --output output/ \
  --step organize \
  --edge-class all \
  --prompt-template compiler/bcc/prompts/bdd_seed_generate.txt

参数（v0）：

--source <PATH>：设计输入目录（模块契约/场景约束）（必填）
-o, --output <PATH>：输出目录（必填）
-s, --step <context|generate|organize>：执行阶段（默认：organize）
--module <CSV>：按模块过滤（可选）
--edge-class <blocked|temporary|keep|all>：按边类型生成（默认：all）
--limit <N>：最多处理 N 个场景单元（可选）
--prompt-template <PATH>：generate 阶段 prompt（可选）
--force：覆盖已有输出（默认关闭）

输出目录口径（v0 固定）：

output/contexts/*.json
output/scenarios/*.dsl
output/features/*.dsl
output/coverage.md

10.6 返回码约定（v0）

0：成功
1：输入参数或文件错误
2：门禁失败（fail-on-gate / fail-on-forbidden）

10.7 与现有命令兼容约束（v0）

bcc bugfix --module-map 必须直接兼容 bcc arch export-module-map 输出。
bcc bdd seed 的 generate/organize 输出结构必须与 bcc bugfix 同口径。
不允许两套互不兼容的场景目录结构并存。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

BCC 架构闭环迁移计划（Rust 主线）

1. 目标（双主线，不混用）

2. 当前现状（事实）

3. 目标链路（双链路闭环）

3.1 新项目主线（Greenfield）

3.2 存量项目补强线（Brownfield）

4. 两条线产物必须对齐（硬约束）

5. Rust 实现状态（v0）

5.1 `bcc arch`（已实现）

5.2 `bcc bdd seed`（已实现 v0）

5.3 统一数据模型（最小）

5.4 仍待完成（v1+）

5.5 下一个迭代缺口（v2+）

6. 当前运行边界

7. 与 BDD 覆盖联动（必须落地）

8. 验收标准（Definition of Done）

9. 判断（实话）

10. CLI 子命令与参数（v0 冻结版）

10.1 `bcc arch matrix`

10.2 `bcc arch validate`

10.3 `bcc arch export-module-map`

10.4 `bcc arch report`

10.5 `bcc bdd seed`

10.6 返回码约定（v0）

10.7 与现有命令兼容约束（v0）

FilesExpand file tree

架构闭环迁移计划.md

Latest commit

History

架构闭环迁移计划.md

File metadata and controls

BCC 架构闭环迁移计划（Rust 主线）

1. 目标（双主线，不混用）

2. 当前现状（事实）

3. 目标链路（双链路闭环）

3.1 新项目主线（Greenfield）

3.2 存量项目补强线（Brownfield）

4. 两条线产物必须对齐（硬约束）

5. Rust 实现状态（v0）

5.1 bcc arch（已实现）

5.2 bcc bdd seed（已实现 v0）

5.3 统一数据模型（最小）

5.4 仍待完成（v1+）

5.5 下一个迭代缺口（v2+）

6. 当前运行边界

7. 与 BDD 覆盖联动（必须落地）

8. 验收标准（Definition of Done）

9. 判断（实话）

10. CLI 子命令与参数（v0 冻结版）

10.1 bcc arch matrix

10.2 bcc arch validate

10.3 bcc arch export-module-map

10.4 bcc arch report

10.5 bcc bdd seed

10.6 返回码约定（v0）

10.7 与现有命令兼容约束（v0）

5.1 `bcc arch`（已实现）

5.2 `bcc bdd seed`（已实现 v0）

10.1 `bcc arch matrix`

10.2 `bcc arch validate`

10.3 `bcc arch export-module-map`

10.4 `bcc arch report`

10.5 `bcc bdd seed`