product-cli

Product

Product Framework 的命令行工具和 MCP 服务——将软件指定为可验证的 What/How 图。

Product Framework 是一项开放标准，用于将软件产品描述为一个互联的机器可读图：What（领域模型 + 事件模型——实体、命令、事件、读模型、基于抽象交互对象进行类型化的 UI 步骤、系统、触发器、决策器、投影器）、How（契约、屏幕组合 / 具体化模型、交付功能），以及它们之间的类型化链接。该图可以驱动生成、把关验证，并解释自身——因此，“描述这个系统”是一个查询，而不是一份过时的文档。

此仓库提供参考工具：一个 Rust 二进制文件（product），以及一个 MCP 服务，让 Agent 能直接编写和验证该图。无需数据库，也无需服务——该图以 YAML/Turtle 格式存放在 .product/ 下。

$ product init --demo                 # scaffold + seed the bookstore What model
$ product domain new system sys-shop --system-kind application \
      --purpose "consumer e-commerce" --target-classes gui
$ product domain validate --strict    # per-node shapes + graph-level completeness
$ product decider derive Order        # derive an aggregate's executable signature
$ product decider validate Order-decider
$ product mcp --http                  # MCP server + a live Event-Modeling web view at /

---

安装

# from source
cargo install --path product-cli

此二进制文件内置了 What→How→Build Claude Code skills。 product init 会将它们写入新仓库的 .claude/skills/（传入 --no-skills 可选择不安装）；product skills install 会（重新）安装它们，而 product skills install --global 会将它们安装到 ~/.claude/skills/，供所有 项目使用。启动新的 Claude Code 会话以加载它们，然后运行 /product-session。

选择 Agent CLI

product session start（以及 product author domain）会在 Agent CLI 中运行 What→How→Build 会话——Claude Code 或 GitHub Copilot CLI。CLI 按以下顺序解析：

1. --cli claude|copilot 标志，否则
2. 仓库 .product/config.toml 中的 [author].cli，否则
3. $XDG_CONFIG_HOME/product/config.toml（或 ~/.config/product/config.toml）中的 全局用户默认值，否则
4. claude。

# .product/config.toml — make this repo default to Copilot CLI
[author]
cli = "copilot"

使用 product init --cli copilot 在新仓库中生成脚手架，或者将相同的 [author] 配置块写入 ~/.config/product/config.toml，为所有仓库设置个人 默认值。配置默认值后，运行 product session start 无需 --cli 标志。

60 秒快速浏览

product init --demo                   # a worked What model to explore
product domain list                   # the captured nodes, by kind
product domain show Order             # one node and its links
product domain export                 # the graph as RDF/Turtle
product domain validate               # §3.1/§3.2 per-node conformance shapes
product domain validate --strict      # + §3.2.0/§3.2.5/§3.4/§4.5 completeness checks
product decider derive Order          # §3.3 — derive decide/evolve signature
product decider simulate Order-decider  # run its flow-derived scenarios
product guide                         # where you are + the next step

模型

• What — product domain … 用于记录领域模型 + 事件模型；product decider …（§3.3）和 product projector …（§3.4）让行为和读 模型可执行；product primitive …（§3.5）用于命名不可约算法。
• How — product how、product feature、product build、product seam、 product preview 涵盖 How 契约、交付功能、屏幕接缝，以及 §11/§12 设计系统 / 内容存储预览配置。
• 所有内容都会根据框架的 SHACL 形状 + SPARQL 规则进行验证； 记录的 What 会序列化为 Turtle（product domain export）。

MCP + Web 视图

product mcp --http 会启动 MCP 服务（框架工具：product_domain_*、 product_decider_*、product_projector_*，……），并在 / 提供实时 Web 视图， 呈现当前 What 图的三个关联视图——系统 （产品 → 系统与旅程地图，§3.0）、领域（一个有界上下文的 ER 图，§3.1），以及 流程（系统的事件模型，以事件建模泳道呈现——按聚合事件流展示触发器 / 命令 / 视图，§3.2）。 节点详情面板、What→How→Build 阶段步骤条、深色 / 浅色主题和实时 SSE 刷新也一并提供。

ddd — 决策驱动设计治理

此工作区还附带 ddd（crates ddd-core、ddd-lsp、ddd-mcp、 ddd-cli），这是一个独立工具，使用独立存储：仓库本地的 .ddd/ 图，其中包含 谓词、闭包声明、决策、分析器 / 检查器清单、模式实例、接缝声明和拦截事件行 （规范、总 PRD、格式：迁移）。

cargo run -p ddd-cli -- init        # scaffold .ddd/
ddd validate                        # schema + ontology rules (CI gate)
ddd diff --sarif build.sarif        # declared vs. detected rules (CI gate)
ddd report escapes                  # diff + cadence + basis-loss report, each section stating its coverage
ddd why CA2007                      # rule -> decision -> principal -> claims (or: detected but unfiled)
ddd render                          # static self-contained HTML projection of the graph
ddd serve                           # the ddd_* MCP surface (stdio)
ddd warmup                          # pre-load the LSP hosts (Roslyn solution load)
ddd what                            # What-graph boundaries carrying no declaration

治理 What（框架图）

ddd what 将 .product/ What 图视为第三个受治理的表面，与 C# 和 Bicep 并列。它不需要语言服务器：product-core 已将 What 作为类型化数据管理，因此适配器可直接从 DomainGraph 读取种类和容器，并通过相同的策略表机制处理它们（ddd-core/src/surface.rs，与 LSP 适配器共享）。

两种行。边界种类无论连接到什么，都是表面：系统（§3.2.5）、上下文映射（§3.1）、旅程交叉点（§3.0.1）、质量需求（§3.6）。已发布种类只有在 §3.2.0 的 Translation 携带它们时才是表面——Translation 监视的 View、它发出的 Command，以及该 View 投影的 Events。其他一切都属于各自系统的内部内容，无需声明。

已发布/内部这一划分，是 What 对应于 C# 可见性的概念，而且至关重要：最初的表格将每个事件和命令都视为边界，而 DDD-what-02 中的测量否定了这一点（39 个中有 0 个跨越任何边界）。请参阅 dec/ddd/what-published-qualifier。

当接缝声明的 contract_location 为 what:<element-id> 时，该边界即视为已治理。--strict 会将其设为 CI 门禁；默认情况下只报告而不失败，因此可以先根据真实图谱校准表格。

MCP 表面（M3/M4）

ddd serve 通过 stdio 暴露 ddd_* 工具命名空间：面向 C# 的 LSP 语言智能（roslyn-language-server --stdio --autoLoadProjects，官方预发布 .NET 全局工具）和面向 Bicep 的语言智能（来自 Azure.Bicep.LangServer 的 bicep-ls）——find_symbol、references、hover、diagnostics（通过规则 ID 与清单联接，与 SARIF 路径使用相同的联接方式）、signature、rename（负责计算；应用通过拦截器处理）——以及治理工具 why、graph_query、declare_seam、declare_pattern、accept_risk。

三个 declare/accept 工具都接受 amend: true，用于修订已提交的条目。该标志在创建和修订两种操作中都必须显式指定——创建不会静默覆盖，修订也不会静默创建——两者按字段划分：修订判断内容（verdict_knowledge、义务回答、理由），而身份信息和 LSP 衍生证据（contract_location、metadata）会原样保留，因此拦截记录仍由机器生成。

ddd_apply_edit 会通过各语言的契约表面分类器处理每项编辑（策略表，PRD §9）：非表面编辑会应用；只有存在匹配的同会话声明时，表面编辑才会应用；否则会被拒绝，并返回结构化需求，其中的事实（符号、种类、签名、可见性、引用计数）已预先填充，判断字段则留空（dec/ddd/rejection-facts-prefilled）。模式：intercept: enforce | warn | off，通过 intercept_by_class 按制品类别配置（配置格式 3）；adapter.csharp.internal_is_surface 可切换库仓库的处理方式（dec/ddd/internal-not-surface）。每项已分类的表面结果都会作为一行记录在 .ddd/seams/events/ 下——这就是对应关系数据集。主机会按需启动、进行健康检查，并在崩溃后重新启动；Roslyn 加载解决方案期间，工具会明确返回 {"status": "loading"}，而不是一直挂起。CI 使用符合 fixture 要求的模拟主机运行（dec/ddd/fixtures-not-sdk）；若要运行受门控的真实主机测试，请确保两个工具都在 PATH 中，并设置 DDD_LSP_E2E=1。

ddd diff 会将 .ddd/manifest/ 下的清单与每种语言检测到的两个来源进行比较，并报告 UNGOVERNED（已检测到，但没有清单条目）、STALE（存在清单条目，但配置和发射内容中均不存在）以及 UNCITED_SUPPRESSION（存在配置或源代码内的抑制项，但没有风险接受记录）：

• 已配置 — 从 .editorconfig（仅解析 dotnet_diagnostic.<ID>.severity 行；会记录区段 glob，但绝不进行求值——刻意不做成 editorconfig 引擎）、bicepconfig.json（analyzers.core.rules 级别）和根目录的 Cargo.toml（[workspace.lints.clippy]，用于本仓库自身的门禁）中解析。 分析器包默认启用的规则没有配置行，只会通过生成的源文件呈现——当一个来源覆盖某条规则时，diff 会说明这一点。

• 已生成 — 来自实际构建的 SARIF 2.1 文件，由一个共享模块导入。使用以下命令生成（已在 M2 根据当前工具文档验证）：

  • C#：dotnet build -p:ErrorLog=diag.sarif%2Cversion=2.1 — MSBuild ErrorLog 属性；必须指定 version=2.1（默认值为 SARIF 1.0），而 %2C 用于在命令行中转义逗号（也可以在项目中设置 <ErrorLog>）。
  • Bicep：bicep lint main.bicep --diagnostics-format sarif > bicep.sarif （也可使用 az bicep lint）。

  不同工具链对源代码内抑制的处理方式不同：C# 编译器仍会将被 #pragma 抑制的诊断记录到 SARIF 中（并标记为已抑制），因此 UNCITED_SUPPRESSION 能检测到它；Bicep 的 #disable-next-line 会将 诊断从输出中完全移除，因此检测无法发现 Bicep 源代码内的抑制——仅涵盖 level: off 配置抑制。

使用 --sarif 或 .ddd/config.yaml 中的 detect.sarif 列表，将文件传给 ddd diff。本仓库以身作则：.ddd/manifest/clippy.yaml 将 clippy::unwrap_used 映射到其决策，ddd diff 会根据工作区 lint 表验证该决策。

构建与测试

cargo build
cargo t                                          # full suite (alias: test --no-fail-fast)
cargo clippy -- -D warnings -D clippy::unwrap_used

架构和贡献者工作流请参阅 CLAUDE.md，规范请参阅 docs/product-framework-open.md。

许可证

请参阅 LICENSE。