实战 · 从零到完整闭环
指南:把整件事跑起来
三个层级:L1 是只需 Node 的 Counter 教程,L2 区分银行生成路径与正式工作坊前置条件,L3 通过 MCP 查询图谱。本地生成命令不等于正式服务验收。下文分别说明银行的新技术通过与仍未签收的独立体验。
环境——先选范围
Node-only 教程与银行 source 范围需要 Node ≥ 22.13.0(node:sqlite)F-13。编译生成的 Scala 需要 JVM 与 sbt。正式 anchors/code/service 验收还需要显式配对材料;正式 code/service 范围限于原生 Darwin x64 / JDK11 F-28。将命令视为验收入口前,先读前置条件。
路径 A · 原生 Node
# macOS (Homebrew)
brew install node@22
# 或用 nvm
nvm install 22
node --version # 必须输出 v22.13.0 或更新
路径 B · Docker 用于 Node-only 工作
docker run --rm -it -v "$PWD":/work -w /work node:22 bash
这个容器是 Node 工作的一种选择,不能代替银行 code/service 已验收的原生环境。
便捷 Scala 编译 · JVM + sbt
# macOS
brew install openjdk@11 sbt
# 或 JVM 工作的 Docker 变体
docker run --rm -it -v "$PWD":/work -w /work sbtscala/scala-sbt:eclipse-temurin-11.0.24_9_1.10.11_2.13.14 bash
拿到工具链
npm 发布仍未完成(DEF-03);这里展示源码检出入口。零 npm 运行时依赖不包含银行工作坊的固定编译工具链、第三方依赖或运行时供给。只检出源码不等于取得完整配对验收候选(DEF-15)。
2026-11-12 另行复核:配套 CLI 工具包 0.5.0 的包 pin 校验、功能性离线安装、真实 prefix 移址与 Counter 0→2 更新通过,共 40 项命令观测 F-29。它与引擎 0.3.0 F-23、公开包交付及真人新人验收是不同维度。重复更新的零写入只指生成源码,不是图/证据零写入。详见证据摘要。
export TRUTHSRC_WORKSPACE="$PWD"
git clone https://github.com/co-arising/metarch-truthsrc.git
export TRUTHSRC_CLI="$TRUTHSRC_WORKSPACE/metarch-truthsrc/bin/truthsrc.js"
node "$TRUTHSRC_CLI" --help
在自己的练习区父目录运行;目录必须不存在。保持同一 shell,绝对路径变量在切换目录后仍有效;无需 npm 安装运行依赖。
L1 · Counter:生成一次,再修改一次
完成上面的工具准备后,仍在练习区父目录。counter-lab 必须不存在。下列命令显式指定项目与生成目录,不向作者根写入产物。
node "$TRUTHSRC_CLI" init counter-lab --format human
cd counter-lab
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --plan --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" status-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" query-project --project truthsrc.project.json --out generated --knowledge SetCount --format human
预览只列操作计划,不是文本 diff。生成后应见 inputs=current、evidence=verified、synchronized=true。它们证明来源与字节状态,不证明 Scala 或银行业务已经执行。
从真实位置反查,而不是猜文件或行号
Explorer 代码视图用于免安装浏览已发布的配对快照。银行来源/回锚快照已通过完整验证(F-30);下方本地步骤用于核验你自己的当前文件。
span 是半开 UTF-8 字节区间,不是行号。下面从当前已验证源码换算行号并反查;没有精确命中就停止,不补造位置。
node --input-type=module <<'NODE'
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
const cli = process.env.TRUTHSRC_CLI;
if (!cli) throw new Error('TRUTHSRC_CLI is required');
const base = ['--project', 'truthsrc.project.json', '--out', 'generated'];
const forward = JSON.parse(execFileSync(process.execPath, [cli, 'query-project', ...base,
'--knowledge', 'SetCount', '--format', 'json'], { encoding: 'utf8' }));
const loc = forward.result.flatMap(row => row.locations).find(item =>
item.file.endsWith('CounterRules.scala') && item.verification.spanVerified &&
item.freshness === 'current-bytes' && item.span.text.startsWith(' def SetCount('));
if (!loc) throw new Error('No verified current SetCount span; inspect status first');
const bytes = readFileSync(join('generated', loc.file));
const line = bytes.subarray(0, loc.span.start).toString('utf8').split('\n').length;
process.stdout.write(execFileSync(process.execPath, [cli, 'query-project', ...base,
'--file', loc.file, '--line', String(line), '--format', 'human'], { encoding: 'utf8' }));
NODE
验证与离线快照
node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" view-project --project truthsrc.project.json --out generated --html counter-map.html --knowledge SetCount --format human
打开新生成的 counter-map.html。它是固定只读快照,不会随磁盘自动刷新。
改初始值,观察过期,再同步
在 truth/example/contexts/example/aggregates/counter/aggregate.yaml 中,只将 count 的 "default": "0" 改为 "default": "2";仍在 counter-lab 执行:
node "$TRUTHSRC_CLI" status-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --plan --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --format human
node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --format human
更新前输入应为 changed,已有文件仍可为 unchanged——那只是它们仍等于上次生成的字节。更新后 verify 通过;最后一次重复应为 written=0,只指零生成源码写入,不是零证据写入。旧快照不覆盖;再次导出使用新的文件名。
已有目录或输出冲突时保留现场,检查归属与输入,不删除目录或手改 ledger 消红。后续 CLI 原文见工具仓 TUTORIAL.md。
可选进阶 · 改一条业务规则,不只改默认值
完成 0→2 闭环后,继续在自己的 counter-lab 中练习。不改银行、不改工具原始 scaffold,不需 JVM、数据库或 MCP。本练习批准的玩具需求是:id 非空时,SetCount 接受 0 到 100,含两端。改变初始默认值,并不会施加这个命令上限。
先确认边界,再改规则
先写下这些独立预期,不要从新条件自动生成答案。四例统一使用 id toy-counter、旧 count 2。业务预期与编辑范围由人批准,测试不能代签。
| 请求 count | 预期决策 | 预期事件 / 状态 |
|---|---|---|
| -1 | reject · NEGATIVE_COUNT | 不产生事件,旧状态不变。 |
| 0 | continue | CountSet(count=0),新 count 为 0。 |
| 100 | continue | CountSet(count=100),新 count 为 100。 |
| 101 | reject · NEGATIVE_COUNT | 不产生事件,旧状态不变。 |
把 Node-only Counter 检查脚本保存到作者树之外,将 COUNTER_CHECK 设为该文件的绝对路径,并保留安装步骤的 TRUTHSRC_CLI。脚本需要完整工具包中已文档化的 lib/domain-products oracle。修改前先运行:旧规则应在新增的 101 预期处失败。
: "${COUNTER_CHECK:?Set COUNTER_CHECK to the saved verify-counter-change.mjs absolute path}"
: "${TRUTHSRC_CLI:?Complete the CLI setup first}"
node "$COUNTER_CHECK" --project "$PWD/truthsrc.project.json"
修改已有守卫,保留其身份
在 truth/example/contexts/example/aggregates/counter/slices/set-count.slice.yaml 的 payload.guards 中找到已有的 ref: nonnegative-count 行。只把其中 cond 从 param.count >= 0 改为下方条件。保留前面的 nonempty-id 守卫、顺序、ref、errCode 和 onFail;不追加一条互相竞争的范围规则,也不修改生成的 Scala。
这是替换用的 JSON 成员片段,不是完整切片或 YAML 文件。
{
"kind": "invariantRef",
"ref": "nonnegative-count",
"errCode": "NEGATIVE_COUNT",
"cond": "param.count >= 0 && param.count <= 100",
"onFail": "reject"
}
复用此守卫意味着 -1 与 101 都返回 NEGATIVE_COUNT,即使其历史名称不够贴切。这是本玩具练习明确保留的错误策略,不是对生产 API 文案的建议。修改身份或错误策略需另行裁定;零始终有效。
检查作者输入、预览、更新,再完整验证
以下命令全部在 counter-lab 执行。手工只改玩具作者输入;生成写入 generated/ 及项目派生知识/证据。更新计划列的是操作,不是文本 diff。
node "$TRUTHSRC_CLI" validate --tree truth/example
node "$TRUTHSRC_CLI" roundtrip --tree truth/example
node "$TRUTHSRC_CLI" status-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --plan --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --format human
node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" query-project --project truthsrc.project.json --out generated --knowledge SetCount --format human
node "$COUNTER_CHECK" --project "$PWD/truthsrc.project.json"
此时四例应全部通过。脚本调用公共 compile-project CLI,重新接纳实际修改后的规则(该命令只收 --project,不收 --out),再用同一安装包的决策、绑定与折叠 oracle 求值,与固定预期对照;不是另写一段 JS 范围判断冒充验证。重放刻意只传 state/event,不传命令输入。
本入口支持工具 cb860b5c、包 0.5.0 的 Counter decision @4、dependencies/folds @6。包模块缺失、语法被拒绝或 profile 不同,应停止练习,不能回退到普通算术后假报成功。结果只证明已接纳产品的行为,没有执行生成的 Scala、HTTP 服务,也不是银行验收。生成的 verification cases 不自动成为独立业务测试。
正反两向闭环,还要读真实代码
从上面的 SetCount 正向查询找到当前已验证位置,打开真实生成规则与事件处理器,检查含端点比较、保留的拒绝码、载荷绑定与仅靠事件的赋值。对新的已验证字节重复前面的字节 span 换行号反查,回到作者声明,不复用旧的猜测行号。verify-project 检查来源/锚点一致性,不执行代码;若要声称目标运行时行为,还须另行实际运行生成代码的行为测试,预期仍应独立批准。
审阅后可重复 update:零生成源码写入只表示同步幂等,不是零证据写入。遇到归属、MANUAL 边界、输入或输出字节冲突,停止并保留现场,检查 status 与真实 diff;必要时另选明确自有的新练习目录,不删除 output、SQLite 或 ledger 消红。
L2 · 银行生成与正式工作坊范围
Node-only 真源检查、便捷生成与正式工作坊验收是不同入口。便捷 npm run project 可取得引擎,但正式 anchors/code/service 同时要求显式 clean1134 归档和已准备的 runtime-supply 目录。配套 CLI、完整配对源码材料及归档尚无确认的公开交付渠道(DEF-15)。不要把本页当成一条命令即可公开复演的承诺。
| 正式范围 | 必需输入与环境 |
|---|---|
| source | 自己的银行 checkout、完整相邻配套工具 checkout 与 Node。不需要 JVM、数据库或浏览器。拒绝无用的 --archive 和 --runtime-supply 参数。 |
| anchors | source 输入,加上--archive:已有 clean1134 归档的绝对路径(固定编译器/工具链与第三方依赖),以及--runtime-supply:已有且已准备的 0.3.0 receipt.json + maven/ 目录绝对路径,与项目匹配 F-23。两者缺一不可。 |
| code | 上述两份供给,加上原生 Darwin x64、由 --java-home 显式选择的已安装 x64 JDK11,以及 sandbox/Python 前置 F-28。 |
| service | code 全部前置,再加新的独占资源租约、可用 Docker/socket 与固定数据库镜像,以及显式 Playwright module 和 chrome-headless-shell 路径。service 不能省略浏览器。 |
正式验收不会隐式下载、prepare 或回退 P23。组合供给时排除归档中的旧引擎,选择独立锁定的 runtime supply;不重签原归档。旧离线包迁移仍单列(DEF-20)。详见已验范围与材料契约。
仅前置检查——先设置自己的真实路径
在自己的银行 checkout 根目录运行,并已取得相邻配套工具 checkout。将 BANK 设置为该 checkout 的绝对路径。code 范围还需将 ARCHIVE、RUNTIME_SUPPLY 与 JAVA_HOME_BANK 设置为上述已存在的本地绝对路径。这些是必填变量,不是下载地址或随页提供的文件。
source 前置检查不带 archive/runtime 参数。
: "${BANK:?Set BANK to your own bank checkout absolute path}"
node "$BANK/tools/bank-workshop.mjs" doctor --through source --format human
code 前置检查显式选择两份供给与已安装的 JDK。
: "${BANK:?Set BANK to your own bank checkout absolute path}"
: "${ARCHIVE:?Set ARCHIVE to the existing clean1134 archive absolute path}"
: "${RUNTIME_SUPPLY:?Set RUNTIME_SUPPLY to the prepared 0.3.0 supply directory absolute path}"
: "${JAVA_HOME_BANK:?Set JAVA_HOME_BANK to the installed x64 JDK11 absolute path}"
node "$BANK/tools/bank-workshop.mjs" doctor --through code \
--archive "$ARCHIVE" --runtime-supply "$RUNTIME_SUPPLY" \
--java-home "$JAVA_HOME_BANK" --format human
Doctor 是前置检查,不是验收。后续 verify 必须在银行 target/ 下从未使用的直接子目录创建新 run,父目录须已存在,路径须为规范绝对路径。不得复用旧 run。不带 --run 的 doctor 不检查该父目录。report/view 与独立 session start/status/stop 使用 run 的封存供给;session 拒绝 archive/runtime-supply override。后续修补需要新执行证据,不能给旧报告改标签。
便捷生成——不是工作坊验收配方
已有本地路径验证真源、生成至 generated/current/,将手写生产源码与生成项目一起编译,并验证锚点。首次生成可从 Maven Central 下载 SHA-256 钉定的引擎;这不证明上述正式供给已齐备,也不启动或签收服务。
: "${TRUTHSRC_WORKSPACE:?Complete the source setup first}"
cd "$TRUTHSRC_WORKSPACE"
git clone https://github.com/co-arising/bank-wealth-demo.git
cd bank-wealth-demo
npm run validate
npm run compile
node "$TRUTHSRC_CLI" graph --tree truth/bank-wealth --out bank.graph.sqlite
npm run project
cd generated/current && sbt compile
sbt test
cd ../.. && node "$TRUTHSRC_CLI" verify-project \
--project truthsrc.project.json --out generated/current
历史采集,2026-11-11:0 硬发现、157 个原子往返逐字节一致 F-01 F-02;235 个生成文件 F-04;534 个源文件、0 编译错误 F-06;23/23 项生成单元测试,不是独立手写测试 F-07;792 个锚点通过验证 F-05。不声称新服务候选仍有这些相同计数。
L3 · 可选:通过 MCP 协作查询图谱
MCP 是可选入口,不是 Counter CLI 闭环或规则变更练习的前置。它让智能体结合已声明的图谱与源码审阅规划变更。服务器提供 26 个读向工具 已验证。
注册服务器
# 在任意目录执行(路径指向你的 metarch-truthsrc 检出)
claude mcp add truthsrc -- node /absolute/path/to/metarch-truthsrc/bin/truthsrc.js mcp
安装查询技能
工具链自带一个技能,教智能体查询纪律(预算化的图谱行走、跟随 next_actions、blast_radius 的宁多报不漏报语义)。把它拷进你的项目:
mkdir -p .claude/skills
cp -r /absolute/path/to/metarch-truthsrc/skills/truthsrc .claude/skills/
练习:按影响半径规划一次增量变更
给智能体一个需求
试试:「我们需要改变定投扣款失败时的行为。在提出任何方案之前,先查询真源图谱中 SipInstallmentFailed 的影响半径,并报告受影响的切片、读模型和流水线。」
看纪律起作用
智能体应报告实际到达的节点、遍历限制与尚未建模的连接。本站快照的 55 节点结果只有聚合、命令、事件和切片,没有读模型或流水线 F-21;这些依赖要另外审阅,再对正确的作者输入起草提案。
套用编辑契约
由人确认业务预期与编辑范围。validate 和 roundtrip 检查各自的契约,不代替业务审批。用 generate-project --project truthsrc.project.json --out generated/current --update --plan 预览更新动作,再运行对应行为检查与回锚验证。计划不是文本 diff。
还附带:从既有代码库抽取树、从可达数据抽取树、或从一句话描述引导工作坊草稿的技能——见工具链仓库的 skills/。
红线与恢复
不要手改派生物或强行绕过红闸门。业务含义改真源,技术选择改绑定,解析/生成错误修共享工具链,外部效果改合法手写实现。保留冲突与失败证据。普通 graphstore 缓存与带回锚的项目知识库不是同一种资产;不能用一条 graph 命令替代所有恢复步骤,更不要随意删 SQLite。
卡住了?工具链 README 有诊断章节;事实页精确告诉你哪些声明在哪一天被验证——如果你的数字和我们的不一样,信你的终端。