bitzorcas
中EN

Concept

CLI 与受控工具

选择 Consumer Solution 模板、代码生成、Schema、Seed、Workflow 与数据库维护入口，并理解每个工具的写入面、权限和证据边界。

Last updated

BitzOrcas 的 Tooling 分为“生成客户解决方案”“生成客户拥有的源码骨架”和“受控运维/迁移”三类。它们都不应进入应用运行时依赖图，但风险完全不同：模板写新目录，Codegen 写 staging；Schema/Workflow/Database 工具可连接真实数据库，必须进入审批与审计流程。

工具全景

BitzOrcas Tooling

可分发模板包与脚手架

可视化与架构工作台

开发期源码生成

受控运维与迁移

治理

BitzOrcas.Cli (bitz)
交互式 Consumer 脚手架

Modern.Templates
Consumer Solution

BitzOrcas Suite (bitz suite)
双模建模 / Diff / DDL / Git / ER

CodeGeneration.Cli
聚合/用例骨架

SchemaMaintenance
drift/migration/seed

SeedData.Exporter
legacy→owner CSV

Workflow.Migrator
bitzorcas/saury definition→DSL

DatabaseMaintenance
backup/restore/export

Upgrade.Cli (bitz-upgrade)
plan/apply/rollback 版本

mcp-bitzsaury
底座/老代码/PRD 只读检索

ErrorCatalog.Cli
强类型错误清单

仓库有四个可分发产物：BitzOrcas.Modern.Templates 模板包与 bitz（BitzOrcas.Cli，内置 Suite 双模工作台）、bitz-codegen（CodeGeneration.Cli）、bitz-upgrade（Upgrade.Cli）三个 PackAsTool 工具。其余工具是 net10.0 独立 EXE，应从匹配发布 Commit 的仓库源码运行。文档中的短名称不是已发布 global tool 的承诺。

能力与风险矩阵

工具输入写入面默认安全边界不能证明
BitzOrcas.Cli (bitz)场景预设 + 正交维度旗标新 Consumer Solution 目录（含前端工程）fail-fast 参数解析 + 依赖自愈 + 双 ORM Golden 门禁生产 License/部署已完成
BitzOrcas Suite (bitz suite)领域实体模型 + CLI 交互上下文物理源码切片原子写入（仅按需写入当前模块）内存只读 Diff 审阅 + Git 历史隔离 + 严格 Schema 校验业务规则逻辑闭环
Modern TemplatesProfileChoice + RuntimeAdapter新 Consumer Solution15 个 Profile + 原生物理生成 + 隔离 restore生产 License/部署已完成
CodeGeneration.Clibusiness-slice schema v1.codegen-output 原子落位旧 inline/module/use-case 入口 fail-closed 审计；BOCG3xx 零写入业务规则和授权正确
SchemaMaintenancemetadata + SQL Serverscript/schema；或只读check/dry run/SafeOnly零停机和业务数据兼容
SeedData.Exporterlegacy staging14 个 owner CSV关系歧义 fail-closedPII 合规和 replay 幂等
Workflow.MigratorBitzOrcas 五表或 Saury 定义表definition + published binding + sidecar 报告DryRun + source 探测在途实例已迁移、语义等价
DatabaseMaintenanceSQL Server/backup/table.bak、restore、exportRESTORE token + path guardsRTO、真实恢复可用性
Upgrade.Cli升级 map + 目标版本仅 Directory.Packages.propsplan/rollback，不可逆步骤失败关闭业务源/配置正确性
BitzSaury migration MCP底座、老代码、PRD 仓库路径无；12 个工具均只读环境变量路径 + stdio 协议隔离迁移语义正确、代码已合规
ErrorCatalog.Cli仓库源码（src/**/*.cs）0008-error-catalog.json 清单--check 漂移门禁运行时错误行为

选择工具时先问“要生成什么证据”，不要因为它们都在 src/Tooling 就套用相同 Runbook。

bitz：新一代交互式脚手架

bitz CLI 以场景预设与正交维度（拓扑/租户/ORM/平台能力/业务切片/沙箱/前端）替代 bitzorcas-compose.py 静态 15 枚举矩阵，是推荐的 Consumer Solution 创建通道：交互式向导或纯旗标脚本模式生成商业包组合宿主、SqlSugar/EF Core 两个持久化 ORM 适配器、随工程交付的测试工程与 --migrate-schema/--seed-only 运维命令，并支持 bitz add/remove module 存量工程模块增删。与下方 dotnet new bitzorcas-host 模板矩阵共存期间契约同源（已验证消费者工程基线），退役条件登记于 0004-template-upgrade-map.json。

BitzOrcas Suite：现代化双模建模工作台

BitzOrcas Suite 是集成在 CLI 内的轻量级可视化架构工作台（通过 bitz suite 或 bitz suite --web 唤起）。它专为消除 DDD 垂直切片研发中的样板文件样板代码与认知负荷而设计，提供：

  • 实体设计器与属性网格：可视配置字段类型、不变量约束、主外键关系与租户隔离特性；
  • 虚拟文件系统（VFS）内存代码审阅：集成 Monaco Editor 进行物理文件与生成结果的双栏 Diff 比对；
  • 多方言 DDL 实时预览：生成 SQL Server 与 PostgreSQL 语法定义及字段中文注释，支持拖拽居中与全屏查看；
  • 光标锚定 ER 图拓扑导轨：平滑缩放平移，并支持一键导出高清 Retina 2x PNG、矢量 SVG 与 Mermaid 脚本；
  • 物理 Git 时间轴与修改比对抽屉：多维 Commit 检索、第二宽视口（Expand to Menu）自适应展开、左侧 36px 快捷折叠导轨与双栏文件变更审查。

详见独立实操指南：BitzOrcas Suite 架构工作台完整手册。

Consumer Solution 模板章节

解决方案模板不是一个页面能讲清的开关列表，按下面顺序阅读：

顺序页面解决的问题
1模板与组合选型15 种正式组合分别适合什么业务
2创建 Consumer Solution安装、生成、restore、build、test、运行
3生成结果解剖Host、Profile、商业包、manifest 与客户源码
4参数与组合约束全部参数、默认值、允许值与稳定诊断
5模板故障排查生成、Feed、Generator、License 分阶段定位

模板输出的 Starter Module 归 Consumer 所有；Framework、Workflow 与 Licensing 从商业包消费。不要把模板目录误读成产品源码副本。

代码生成入口

代码生成器有聚合模式与用例模式。当前最可靠入口是：

Terminal window
# 商业 Feed 本地安装；或从匹配 Commit 的源码 dotnet run 运行同一入口。
dotnet new tool-manifest
dotnet tool install BitzOrcas.CodeGeneration.Cli \
  --version 1.0.0-alpha1 --add-source <commercial-feed>


dotnet bitz-codegen --business-slice ./design/matter-intakes.v1.json \
  --output .codegen-output

生产入口只认严格校验的切片 Schema（行业中立统一聚合 + 单条 Create 命令）；旧的 --inline/--module/--use-case 是 fail-closed 审计入口——零 C#、写诊断清单、退出码 2。生成后必须人工接 slnx、补业务不变量与真实测试 fixture。

Schema 与 Seed 的分工

Schema Maintenance比较编译期 metadata 与 SQL Server 实际 schema，也能离线检查 CSV 长度。Seed Exporter从批准的 legacy snapshot 生成 owner-local CSV。

Legacy snapshot

Seed Exporter

候选 owner CSV

Schema --validate-seed

SeedRunner replay contracts

Compiled metadata

Schema drift check

Target SQL Server

Seed length校验不是幂等/依赖/敏感数据证明；schema drift clean 也不证明 seed 正确。两条链在发布前汇合，但证据不可互换。

Workflow 定义迁移

Workflow Migrator只迁移定义。source 区分 BitzOrcas 五表与 Saury T_WorkflowDefinition*；未指定时按源库表探测。Saury 额外写出 sidecar 报告，供业务模块实现 IBusinessIntegrationCallback。未知节点、未转译条件与无审批人只记 warning，dry-run 必须逐流程审查。

kebab-case 命令行开关在绑定 Migrator section 之后叠加，优先于 JSON 与 MIGRATOR_ 环境变量。连接串仍建议放在 gitignored appsettings.local.json。

BitzSaury 迁移检索

BitzSaury 迁移 MCP提供 3 个 stdio Server、12 个只读工具，按环境变量连接 BitzOrcasVNext、Saury/BitzOrcas 老仓库和迁移知识库。它用于迁移前查证契约与旧行为，不执行代码转换，也不写数据库。

Database Maintenance

Database Maintenance直接调用 SQL Server BACKUP/RESTORE，并可 SELECT * 导出单表。Backup path 必须同时被 SQL Server 服务与 CLI 看见；Restore 使用 WITH REPLACE 且没有 dry run；Export 不做 tenant filter 或字段脱敏。

这类工具必须在隔离恢复环境演练。RESTORE VERIFYONLY 通过不是 GA 灾备证据，真实 restore、应用 smoke、RTO/RPO 和链路对账缺一不可。

通用安全工作流

绑定 Commit/SDK

确认输入与目标身份

Preview / dry run / check

Owner + 安全/DBA 审批

隔离环境实际执行

业务与技术验证

归档命令/退出码/制品

按 Runbook 执行目标环境

所有工具都要记录源码 Commit、.NET SDK、工作目录、配置来源、输入 snapshot、目标身份、命令、退出码、耗时和未覆盖风险。只保存最后一行“成功”无法审计。

Secret 与日志

  • 连接串优先使用 secret store 注入到 gitignored local settings 或短生命周期 environment。
  • 不在 PR、shell history、CI command echo 中写明文 password/license。
  • 工具虽会掩码部分 Password/Pwd，仍不能保证 stack trace 和 driver log 安全。
  • Workflow JSON、Seed CSV、table export 和 backup 都可能含 PII/Secret，按敏感制品存储。
  • 临时目录具有最小权限、加密、到期清理和失败制品隔离。

工作目录语义

这些 EXE 使用 Directory.GetCurrentDirectory() 加载 appsettings 与解析相对路径。从仓库根运行和进入项目目录运行可能得到不同 local config/output。Runbook 必须固定 cwd 或全部使用绝对路径。

Terminal window
# 运行前记录证据上下文。
pwd
git rev-parse HEAD
dotnet --info | sed -n '1,36p'


# 查看 Tooling 项目真实 packability/output type。
rg -n '<OutputType>|<IsPackable>|<TargetFramework>' \
  src/Tooling --glob '*.csproj'

退出码不是统一协议

Schema、Workflow 与 Database tools 都使用 0/1/2/3/99 大体形态，但 code 2 的业务含义不同，Seed Exporter 和 Codegen 也没有同一套显式退出码目录。自动化应按工具和 mode 解释，不能写一个全局 exit 2 = drift。

尤其要注意：Database Log backup 在 SIMPLE recovery 下会 skipped 但 code 0；Workflow code 0 仍可能有 warnings；Schema check code 2 是预期 drift 证据。

完成门禁

  • 工具来源 Commit 与目标版本一致；
  • 当前项目是否 packable/可安装没有被文档夸大；
  • 输入 snapshot、目标 database/tenant/path 明确且二次确认；
  • 只读/preview/dry-run 证据先于实际写入；
  • 高权限身份与 Export 只读身份分离；
  • 部分成功、取消和重跑行为进入 Runbook；
  • 生成制品完成 PII/Secret 与 owner 审查；
  • 技术验证与业务 smoke 都通过；
  • 未实现能力和人工补偿措施被明确记录；
  • 临时输出、local settings 和运行日志没有进入 Git。

另见

本章核心导航

100%

滚轮或按钮缩放 · 放大后拖动画面 · 双击切换 100% / 200%