trades-runtime

Trades-Runtime

面向现场行业的私有 TypeScript 运行时，用于影子优先的 AI 操作系统／企业运营智能层。现场行业：暖通空调、管道、电气、下水道及跨行业业务。

作者／身份： 仅限 Aziel Eliab。参见 IDENTITY.md。导出内容中不包含法定姓名、住址或县名。
版本： 1.0.0（Local Softwares 1.0，可安装）
角色： trades-runtime
许可证： Apache-2.0
发布： 免费软件（Apache-2.0）。克隆并在自己的机器上运行本地影子系统。Aziel Eliab 是作者，不是运营者，也没有在运行公司试点。
公共 Worker（如已部署）： https://trades-runtime.vibelock.workers.dev
在 Glama 上试用（计划中的目录条目）： https://glama.ai/mcp/servers/AzielEliab/trades-runtime — 打包文件在仓库内（glama.json、Dockerfile、cli/mcp-stdio.mjs）。不要仅凭此 git 树就将 Install Server 视为已上线。检查日期：2026-10-02：Glama Latest/releaseVersion 为 1.0.0-local。公共徽章仍为 1.0.0-local，与仓库内的 Softwares 引用版本 1.0.0 不一致。正在等待追齐。Official MCP Registry 仍显示 1.0.0-local。此版本不会重新发布该条目。Local Softwares 1.0。此差距不代表 Field 1.0 声明，也不代表 Office Softwares 1.0。此版本不会 Make Release。参见 docs/GLAMA.md。
状态： 1.0.0 可安装的 Local Softwares 1.0（Track L 门槛；尚未启动试点；live_backends false；不代表 Field 1.0 声明）— 0.4.12 增加常用命令（help、softwares、version、health），方便用户无需阅读整篇 README 即可了解产品；桌面功能保持冻结（尚未启动试点）— 0.4.11 在 VibeLock Worker 上提供免费的人类 UI（浏览器／PWA），无需先下载；可选的计数打包；运营者桌面仍在本地（尚未启动试点）— 0.4.10 在 Monitoring 桌面上提供本地工时追踪、服务覆盖开关和合适技师建议（尚未启动试点）— 0.4.9 为 ServiceTitan 和 ProBooks 片段提供本地入站质量报告、带拒绝写回功能的警报转行动占位项，以及 Option C 启动门槛准备面板（尚未启动试点）— 0.4.8 提供本地行驶里程和驾驶表现、员工及部门表现排名榜、跨部门协作建议，以及该排行榜旁的员工摩擦率（尚未启动试点）— 0.4.7 提供适配区域市场的零件成本、按技师统计的 trainingNeeded、部门良好与不良行为标记，以及本地车辆计数（尚未启动试点）— 0.4.6 提供按电话分类的原因、回访／保修／未分类筛选器、回环式每周回访率摘要，以及技师晨会（尚未启动试点）— 0.4.5 提供本地回访和保修计数、警报摘要导出、评分说明，以及预约拦截收据（尚未启动试点）— 0.4.4 优化本地运营者桌面（主题、泳道视图、可打印快照；尚未启动试点）— 0.4.3 Option C BYO 试点准备（本地运行手册 + npm run pilot:prep；尚未启动试点）— 0.4.2 在运营者桌面上提供本地警报规则 — 0.4.1 在 0.4.0 通用即插即用基础上增加具名的现场行业应用供应商配置 — 与仓库内的 Property Intelligence v1.0 保持步调一致 — 纯实时核心 + 诚实的占位实现 — BYO 本地 ServiceTitan + ProBooks + 现场行业应用入站 — 不提供实时写入、租户数据、ST/ProBooks 写回、电话回传、DOI、托管上传器或生产级公司操作系统声明 — Option C 代码已就绪／尚未启动试点 — Option D 尚未启动

产品是 src/ 中的软件。docs/ 是精简的本地目录／UI。GitHub Pages 有意禁用（live_backends: false）。没有 Pages 工作流。绝不发布 PDF。 实现规范位于仓库根目录的 specs/（不在 docs/ 下）。

长期规则：Aziel 发送的每份 PDF 都是需要实现为软件代码的规范。 文档记录：TR-1.0-GATE-2026-09-28（Track L 本地 Softwares 1.0 门槛；试点尚未启动）· TR-COMMANDS-2026-09-27（通用 CLI 命令 help、softwares、version、health；desk 已冻结；试点尚未启动）· TR-OPS-2026-09-27（本地时间追踪、覆盖开关、合适技术人员建议；试点尚未启动）· TR-DESK-VIEW-2026-09-27（本地显示/隐藏复选框；Softwares 卡片网格保持不变；试点尚未启动）· TR-MOBILE-DESK-2026-09-27（适配手机屏幕宽度的本地 desk；Softwares 卡片保持不变；试点尚未启动）· TR-QUALITY-2026-09-27（入站质量、告警操作占位项、Option C 启动门槛；试点尚未启动）· TR-DRIVE-2026-09-27（行驶里程、驾驶表现、员工和部门排名榜；试点尚未启动）· TR-SOFTWARES-2026-09-27（零件成本和市场适配、trainingNeeded、部门行为标记、本地卡车数量；试点尚未启动）· TR-HUDDLE-2026-09-26（逐通电话分类原因、来电筛选、每周回拨率、晨会；试点尚未启动）· TR-CALLS-2026-09-26（回拨和保修数量、告警摘要、评分原因、预约拦截回执；试点尚未启动）· TR-DESK-POLISH-2026-09-25（本地 desk 润色；试点尚未启动）· TR-OPTION-C-PILOT-RUNBOOK-2026-10-02（人工 Option C 启动路径；目录试点尚未启动）· TR-PILOT-START-2026-10-02（在操作员隔离环境中明确执行 pilot:start --branch；不是 Field 1.0；不是 Office Softwares 1.0）· TR-OPTION-C-PREP-2026-09-25（Option C 盒子准备；试点尚未启动）· TR-ALERTS-2026-09-25（本地告警规则）· TR-VENDOR-2026-09-25（命名供应商配置）· TR-DESK-2026-09-25（通用即插即用 + 本地人工 desk）· TR-AUDIT-2026-09-18C · TR-AUDIT-2026-09-18B · TR-AUDIT-2026-09-18 · TR-AUDIT-2026-09-17 · TR-CUT-2026-09-17 · TR-BOT-2026-09-17（常设简报）· TR-BYO-2026-09-17（修订 TR-BOT §9 和 TR-CUT R2–R3）。

在本机试用

合并此仓库不会启动试点。该软件由 Aziel Eliab 编写。他不是运营者，也不是客户，并且没有在此仓库上经营商店。live_backends 保持为 false。不进行回写。全新克隆无需 ServiceTitan 或 ProBooks 租户，也无需任何密钥。

git clone https://github.com/AzielEliab/trades-runtime.git
cd trades-runtime
npm install
npm test
npm run demo
npm run shadow:office
npm run shadow:field
npm run desk

你将看到：

• npm run demo 会在终端打印一个合成的影子日。这是一个测试夹具。它不是某家公司的结果，也不会打印准确率百分比。
• npm run shadow:office 会在名为 sample-shop 的样例分支上运行办公室影子模式。测试夹具已位于 test/fixtures/sample-branch/office/。回执会显示 office_softwares_1_0: false、pilot_started: false 和 live_backends: false。你将看到已接纳的样例工单、晨会计数、以清单形式呈现的入站数据质量，以及拒绝回写的警报桩。此命令不会加载现场标记。
• npm run shadow:field 会从 test/fixtures/sample-branch/field/ 在同一个样例分支上运行现场影子模式。你将看到本地标记（needsParts、safetyHold、vanDown，以及一行只标注名称但未指定车辆的记录，不会凭空编造车辆）、工时卡、覆盖地点和合适技师建议。field_softwares_1_0 为 false。这不是实时 GPS 数据流，也不是 Field 1.0。它与办公室影子模式是不同的命令。
• npm run desk 会打开本地工作台，地址为 http://127.0.0.1:4174/ 。如果入站文件夹为空，页面会标记为合成演示。它不是你的公司，也不是实时租户。将你自己的导出文件放入 data/inbound/ 是可选操作，且文件会留在你的机器上。

只有当你在自己的机器上拥有真实分支后，才执行：

npm run pilot:prep
npm run pilot:start -- --branch <branchId>

这是唯一会将 pilot_started 设为 true 的软件路径，而且只会在你的隔离环境中设置。若分支缺失或无效、准备工作尚未就绪，或入站数据为空或仅包含合成数据时使用 --claim-company，此路径都会拒绝执行。已发布的目录仍保持 pilot_started 为 false。模式仍为 SHADOW-SEALED。写入需要运营者批准；默认关闭。该回执不是实时公司操作系统，不是 Office Softwares 1.0，也不是 Field 1.0。

安装、测试、演示

npm install
npm test
npm run typecheck
npx tsx src/cli.ts help
npx tsx src/cli.ts softwares
npx tsx src/cli.ts version
npx tsx src/cli.ts health
npm run demo
npm run byo:admit-demo
npm run drop-in:demo
npm run desk
npm run shadow:office
npm run shadow:field
npm run pilot:prep
npm run pilot:start -- --branch <branchId>
npm run health:local
npm run shadow:sealed-demo
npm run manifest
npm run mcp

help 会打印命令列表（--help 和 -h 的效果相同）。softwares 会列出每个模块的 slug、状态和一行通俗说明（Softwares 不区分大小写）。version 会打印产品名称和版本，然后打印一行说明：live_backends false、pilot_started false（--version 和 -V 的效果相同）。health 与 health-local 一样，会显示本地状态说明卡。未知命令会提示该命令未知，然后打印帮助文本，并以非零状态码退出。不带命令也会打印帮助并以零状态码退出。

npm test 会运行宪法规则测试，包括 Human Authority、confidence≠truth、仅将 CrossTrade 用于次级路由、v0.2 recognition / pricebook lock / mission board / location economics、0.3.3 执行主干（FragGate 入站、持久化回执、runAction）、仅追加 JSONL 回执的重启重放（data/receipts.jsonl 或 {tmpdir}/tr-replay-*/receipts.jsonl）、合成 BYO 接纳演示、通用即插即用演示、本地运营者工作台、Option C 密封影子模式脚手架（不自动晋升、engagement 回退、必填结算字段），以及 Option C 试点准备（机器检查、合成接纳、工作台启动、pilot_started: false）。

CI（.github/workflows/ci.yml）会在针对 main 的拉取请求和推送时运行 npm ci、npm run typecheck 和 npm test。GitHub Pages 已有意禁用——不要将 github.io URL 视为测试门槛。

npm run demo 会运行一个合成影子日：Call-Fit、密封反事实、人类覆盖、哈希链回执、轨迹重定基。

软件概览

领域	路径	状态
规范 ID / 事件 / 模式	src/core/	纯实时
置信度 ≠ 事实	src/core/confidence.ts	纯实时
链 A/B/C/D	src/core/chains.ts	纯实时
人类权限	src/core/human-authority.ts	纯实时
TradesCoherence、EvidencePacket、DecisionGate、ReceiptLedger、Shadow、Trajectory	src/inherited/	纯实时
Call-Fit、经济性、CrossTrade、链 D、劳动力、Decision Fabric、分析	src/domain/	纯实时
通信（事件流渠道）	src/domain/communications.ts	纯实时
认可（质量门控）	src/domain/recognition.ts	纯实时
每日任务看板	src/domain/mission-board.ts	纯实时
回访和保修标签	src/domain/call-class.ts	纯实时
晨会 + trainingNeeded	src/domain/huddle-board.ts	纯实时
行驶里程和驾驶表现	src/domain/drive-miles.ts	纯实时
员工和部门排名看板	src/domain/performance-board.ts	纯实时
协同工作和跨部门建议	src/domain/work-together.ts	纯实时
员工摩擦率	src/domain/friction.ts	纯实时
入站质量报告	src/domain/inbound-quality.ts	纯实时
警报操作存根	src/desk/alert-actions.ts	纯实时
选项 C 启动门	src/spine/option-c-start-gate.ts	纯实时
本地职位和 Monitoring 视图	src/domain/local-positions.ts	纯实时
价目表（ST 影子 + 当前/上次成本 + LOCK）	src/domain/pricebook.ts	纯实时
卡车库存计数 / 履约	src/domain/truck-stock.ts	纯实时
天气 / 需求 / 月相（实验性）	src/domain/weather-demand.ts	纯实时
维护路由（需求优先）	src/domain/maintenance-routing.ts	纯实时
Property Intelligence v1.0	src/domain/property-*.ts、neighborhood-*.ts、regional-recalibration.ts	纯实时
FragGate 入站	src/spine/fraggate-inbound.ts	纯实时
持久化回执	src/spine/durable-receipts.ts	纯实时
runAction() 主干	src/spine/run-action.ts	纯实时
Actor / 权限注册表	src/core/actor-registry.ts	纯实时
Shadow 模式	src/core/shadow-modes.ts	纯实时
参与规则（不是命令）	src/core/engagement-rules.ts	纯实时
单分支 Shadow 配置	src/core/shadow-branch.ts	纯实时
结算测试框架	src/core/settlement-harness.ts	纯实时
ServiceTitan Shadow（仅导入；通过审批门写回）	src/spine/servicetitan-shadow.ts	纯实时
ProBooks Shadow（仅导入、对等入站；通过审批门写回）	src/spine/probooks-shadow.ts	纯实时
本地 BYO 入站布局	src/spine/inbound-layout.ts	纯实时
本地入站配置（无云账户）	src/spine/local-inbound-config.ts	纯实时
通用 trades-app 即插即用	src/spine/drop-in.ts	纯实时
trades-app Shadow（仅导入；通过审批门写回）	src/spine/trades-app-shadow.ts	纯实时
本地人工操作员工作台（包含 AZTrades shell）	src/desk/	纯实时
AZTrades 外勤时间（打卡、用餐、驾驶）	src/desk/field-time.ts	纯实时
AZTrades 作业定价	src/desk/job-price.ts	纯实时
SupplyHouse 公共 GET	src/desk/supplyhouse-public.ts	纯实时
AZTrades 房产卡片	src/desk/property-card.ts	纯实时
AZTrades 本地登录	src/desk/local-login.ts	纯实时
AZTrades shell 渲染	src/desk/aztrades-render.ts	纯实时
AZTrades 提示偏好	src/desk/hint-prefs.ts	纯实时
合成即插即用演示	src/demo/drop-in.ts	纯实时
运行时隔离（每个实例各自保存回执）	src/spine/runtime-isolate.ts	纯实时
合成 BYO 准入演示	src/demo/byo-admit.ts	纯实时
合成密封 Shadow 演示	src/demo/shadow-sealed.ts	纯实时
选项 C 试点准备	src/spine/option-c-prep.ts	纯实时
本地健康卡片	src/spine/health-local.ts	纯实时
履约状态机	src/domain/fulfillment-machine.ts	纯实时
任务看板时钟	src/domain/mission-board.ts	纯实时
PI 接入作业	src/domain/property-jobs.ts	纯实时
§18 冻结 + v0.2 治理规则	src/rules/constitution.ts	纯实时
写入权限（全部 / 所选，autoApprove 关闭）	src/approvals/permissions.ts	纯实时
审批门（每次调用均需确认是/否、单次使用、限时有效、哈希链日志）	src/approvals/gate.ts	纯实时
由操作员配置的写回后端	src/approvals/backends.ts	纯实时（不附带任何后端）
带审批门控写入工具的本地 MCP	src/approvals/local-mcp.ts	纯实时
ServiceTitan / ProBooks 实时写入	src/approvals/	需要操作员审批；默认关闭；此仓库未配置后端

需审批的写入操作

写入操作需要操作员审批；默认关闭。

运行时通过工具调用或操作执行的所有写入操作，都会经过同一个审批关口：src/approvals/gate.ts。未经审批，不会执行任何写入。

1. 写入工具调用会创建一条待审批请求，列出工具、目标和载荷摘要。此时尚未写入任何内容。

2. 本地人工操作员通过 loopback 工作台上的写入权限与审批面板（http://127.0.0.1:4174/#approvals-board）或在终端中回答是或否：

   npm run approvals                 # list pending requests
   npm run approve -- <id> yes       # run that one call once
   npm run approve -- <id> no        # refuse it; the refusal is recorded
   

3. 选择“是”后，该调用只会执行一次。审批仅可使用一次。待处理请求会在 approvalTtlSeconds 秒后过期（默认值为 900）。已过期的审批会失败。

4. 每条请求、拒绝、决定、过期记录和执行结果，都会追加到 data/runtime/<instanceId>/approvals.jsonl。该文件是基于现有持久化回执存储（src/spine/durable-receipts.ts）构建的哈希链。凭据绝不会写入其中。

5. 请求者不能审批自己的请求。本地 MCP 没有批准或拒绝工具。工作台的批准/拒绝端点和设置端点仅限 loopback 访问。这些端点需要使用嵌入在工作台页面中的进程级工作台令牌；会拒绝任何携带 mcp-session-id 的请求，并拒绝跨源浏览器请求。

权限设置

这些设置位于工作台面板、data/runtime/<instanceId>/permissions.json（复制 data/runtime/permissions.json.example）以及 npm run permissions 中。

模式	功能
selected（默认）	仅启用你选定的权限。默认是 selected 且未选中任何权限，这与只读模式相同。
all	启用所有写入权限，且每次调用仍需回答是或否。只有同时设置 autoApprove: true 才会跳过提示。

autoApprove 默认关闭，且仅在 all 模式下生效。在 selected 模式下会被忽略。启用后，已启用的写入操作无需逐次回答是或否即可执行，但每次操作仍会记录日志。

npm run permissions                                        # show current settings
npm run permissions -- --enable field_events.write         # selected mode: turn one on
npm run permissions -- --disable field_events.write
npm run permissions -- --mode all                          # every permission on, still asks per call
npm run permissions -- --mode all --auto-approve on        # no per-call prompt (off by default)

每项权限都对应此仓库中的一个实际写入路径：

权限	工具	写入内容
servicetitan.writeback	trades_runtime_servicetitan_writeback	ServiceTitan API；仅通过由操作员配置的本地后端
probooks.writeback	trades_runtime_probooks_writeback	ProBooks API；仅通过由操作员配置的本地后端
tradesapp.writeback	trades_runtime_tradesapp_writeback	另一个 trades app API；仅通过由操作员配置的本地后端
alerts.ack	trades_runtime_alert_ack	确认本地工作台提醒（alert-state.json）
field_flags.write	trades_runtime_field_flag_raise	在 field-flags/ 下写入本地现场标记
field_events.write	trades_runtime_field_event_record	在 field-events.jsonl 中记录打卡、用餐或行车事件

关闭的权限会返回明确的拒绝消息，并记录该拒绝。

工作台自身的按钮（例如作业价格、打卡事件、标记、覆盖开关和提醒确认）代表操作员直接在此机器上执行操作，因此不会经过审批关口。审批关口适用于工具调用和 Agent 操作。

写回后端和凭据

此仓库不附带任何后端或凭据。已提交的目录中，live_backends 保持为 false。只有同时满足以下两项时，才会运行 ServiceTitan、ProBooks 或 trades-app 写回：

• 操作者在自己的机器上写入了 data/runtime/<instanceId>/write-backends.json（复制 data/runtime/write-backends.json.example）。其中包含 https baseUrl 和环境变量的名称，绝不包含密钥本身。拒绝内联令牌。
• 操作者批准了这次调用。

否则，调用会返回 no-backend-configured，且不会写入任何内容。供应商错误会报告为 vendor-error。这两种情况都不会被转换为成功。请求形状（method、path、body）会按原样传递给供应商。此仓库尚未针对实际的 ServiceTitan 或 ProBooks 租户进行测试。

本地 MCP

npm run desk 还会在仅限环回地址的 POST http://127.0.0.1:4174/mcp 上提供 JSON-RPC MCP。stdio 客户端可以桥接到它：

TRADES_RUNTIME_URL=http://127.0.0.1:4174 npm run mcp

在 tools/list 中，写入工具带有 requiresApproval: true、其 permission 和 permissionEnabled。调用其中一项会返回 { "status": "pending", "approvalId": ... }，或者在权限关闭时拒绝调用。trades_runtime_approvals_list 和 trades_runtime_approval_status 为只读。公开的赠送版 Worker（trades-runtime.vibelock.workers.dev）保持只读。它不持有任何租户数据，因此无内容可写入。

这并不表示 Field 1.0 或 Office Softwares 1.0 已就绪，也不会启动试点。pilot_started 保持为 false。

BYO 入站（TR-BYO-2026-09-17）

每位用户都将自己的 ServiceTitan 和自己的 ProBooks 接入自己的本地运行时。创作节点 / GitHub 不是数据托管方。没有中央转储。没有托管上传器。没有向外联络。

该机器上的本地入站数据（内容已加入 gitignore）：

• data/inbound/servicetitan/ — 用户放置的 ST 导出文件或只读拉取数据
• data/inbound/probooks/ — 用户放置的 ProBooks 账簿 / 项目 / 成本 / 供应商文件
• data/inbound/trades-app/ — 其他现场服务 / 工单 / 价格簿 / 客户 / 预约导出文件。具名配置：Jobber、Housecall Pro、Service Fusion、QuickBooks-shaped books、ServiceM8、AccuLynx、SuccessWare、Xero、FieldEdge、ServiceTrade。若没有指纹匹配，则使用通用 CSV/JSON。
• data/runtime/<instanceId>/receipts.jsonl 和 ledger.jsonl — 按运行时实例隔离

不使用 data/tenants/（这个词暗示托管式多租户服务）。可选的本地配置只列出路径或只读端点提示——不涉及云账户，且运行时不会调用这些提示。令牌保留在用户的机器或其密封保险库中。

FragGate 的一等 sourceKind 值：servicetitan（MEDIUM，已哈希，live:false write:false）、probooks（相同）、trades-app（相同，通用类别）、operator-file（在来源标记为 servicetitan、probooks 或 trades-app 之前为 LOW；仍不代表事实）、human（Chain C 上带有操作者 ID 的经理更正）。包装 ≠ 已验证。拒绝抓取、中央转储、托管上传和静默提升为 VERIFIED。

通用即插即用（TR-DESK-2026-09-25）

ServiceTitan 和 ProBooks 仍是具名的同级类别。第三种入站类别 trades-app 可接收同一系列的导出文件，无需为每个供应商单独编写文档。即插即用功能会识别 JSON/CSV 的结构，并应用映射配置文件。0.4.1 会优先使用具名配置文件（当键、表头或文件名匹配时）：Jobber、Housecall Pro、Service Fusion、QuickBooks Online、QuickBooks Desktop、ServiceM8、AccuLynx、SuccessWare、Xero、FieldEdge 和 ServiceTrade。否则会使用通用 JSON 或通用 CSV。仍符合 ServiceTitan 或 ProBooks 格式的文件会保留在相应的同级类别中。现在，ServiceM8、SuccessWare 和 ServiceTrade 文件通过各自的平台连接器接入，因此每个平台只有一种接入路径（参见 data/inbound/README.md）。参见 TR-VENDOR-2026-09-25。

npm run drop-in:demo

该演示会将合成测试样例从 test/fixtures/byo/ 复制到临时入站目录，通过 FragGate 接入这些文件，为数据包生成哈希，写入临时隔离收据，并验证写入操作仍会抛出异常。这不是客户数据导出文件。

真实导出文件仍保存在被 git 忽略的投放文件夹中。data/inbound/local.json（从 local.json.example 复制而来）可以指定路径和读取端点提示。这些提示仅供操作人员参考。此流程不会获取这些端点的数据。

平台同级类别（TR-PLATFORMS-2026-10-19）

Jobber、Housecall Pro、Square、QuickBooks Online、FieldEdge、Service Fusion，以及（第二波，TR-PLATFORMS-2-2026-10-19）Successware、Workiz、ServiceTrade、BuildOps、FieldPulse、Kickserv、mHelpDesk、ServiceM8、Simpro、Commusoft 和 Wintac，都是一等入站同级类别。Successware 是由所有者指定的。其他十个平台根据公开研究（Software Advice 2026 年管道行业列表、独立的 HVAC 调度排名和供应商开发者文档）选出，而非依据使用数据。我们不宣称其市场份额。每个平台的选择理由和来源见 src/spine/platforms/catalog-wave2.ts。每个平台都有自己的文件夹 data/inbound/<kind>/。将 JSON 或 CSV 导出文件放入对应文件夹后，系统会根据供应商文档中定义的对象名称进行映射，再以 MEDIUM、未验证、live: false 状态接入。

你也可以通过 npm run pull -- <platform> 自行拉取数据。这是对供应商公开文档所述 API 发起的只读调用。保存令牌的环境变量名称列在 data/inbound/local.json 中。仓库、Pages 或 Worker 中都不会保存凭据。

平台	模式	原因
Jobber	文件投递 + 按文档说明的 API 拉取	提供公开的 GraphQL API（X-JOBBER-GRAPHQL-VERSION）。
Housecall Pro	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API；供应商在 MAX 套餐中提供该 API。
Square	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API（客户、付款、发票、预约、团队）。Square 没有工作对象，因此不会凭空创建。
QuickBooks Online	文件投递 + 按文档说明的 API 拉取	提供公开的 Accounting API 查询端点。
Service Fusion	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API；供应商在 Pro 套餐中提供该 API。
FieldEdge	仅文件投递	API 需要通过合作伙伴计划才能使用，因此未提供拉取功能。
Workiz	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API v2，地址为 https://api.workiz.com/crm/api（Bearer 密钥；Developer API 附加组件）。
ServiceTrade	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API（OAuth2 bearer）。
FieldPulse	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API（x-api-key，令牌由 FieldPulse 支持团队提供）。
ServiceM8	文件投递 + 按文档说明的 API 拉取	提供公开的 JSON REST API（X-API-Key）。
Simpro	文件投递 + 按文档说明的 API 拉取	每个版本均提供公开的 REST API；需要设置版本 URL 和公司 ID。
Commusoft	文件投递 + 按文档说明的 API 拉取	提供公开的 REST API v2（Bearer 密钥）；回访工单会关联到其父工单。
Successware	仅文件投递	没有公开的 API 文档；仅通过合作伙伴提供集成。
BuildOps	仅文件投递	API 文档需要邀请才能查看。
Kickserv	文件投递 + 按文档说明的 API 拉取	提供 XML REST API（使用员工 API 令牌进行 Basic 身份验证；Premium 套餐），由一个无依赖项的小型读取器读取。
mHelpDesk	仅文件投递	未找到公开的 API。
Wintac	仅文件投递	桌面软件；导出为 CSV。

每个平台还会标注映射置信度：documented、partial 或 guessed。已记录：FieldEdge、Workiz、ServiceTrade。部分记录：FieldPulse、Kickserv、mHelpDesk、Simpro，以及本轮未重新核验的平台。推测：Successware、BuildOps、Wintac。桌面端的平台列表会显示哪些映射器需要通过实际门店导出数据进行确认。来源和详细信息见 data/inbound/README.md。

门店导出数据由各门店提供；本仓库不包含任何此类数据。将你自己的导出文件放入 data/inbound/<kind>/，然后运行 npm run mapping:check -- <kind> <file>。该命令会报告已匹配、未匹配和缺失的必填字段，并将初始覆盖配置写入 data/runtime/<instanceId>/mappings/<kind>.json。该文件保存在本地并由 git 忽略，其优先级高于内置映射器。推测的映射需要通过你的导出数据确认，而不是由本仓库确认。请参阅 data/inbound/README.md 中的“你自己的导出数据”。

所有这些都只针对测试样例进行了测试。未在实际租户环境中测试。 每个平台的 <kind>.writeback 都会经过审批关卡。该功能默认关闭，并会在每次调用时询问是或否。如果未配置后端，则会返回 no-backend-configured。它绝不会报告实际上并未发生的成功。运行 npm run platforms 可列出平台。

本地合规、收入和运维模块（TR-MODULES-2026-10-19）

每个模块都会读取一个本地文件 data/runtime/<instanceId>/<module>.json（已加入 gitignore；示例见 data/runtime/*.json.example），以及已接收的入站数据行中已有的数据。每个模块在 http://127.0.0.1:4174/ 上都有一个操作台面板、一个 JSON 路由，以及一个本地 MCP 读取工具。写入需要单独的权限，并且每次调用都必须获得操作员同意。

模块	操作台路由 / 读取工具	写入权限
制冷剂日志（EPA 608 / AIM Act）	/api/refrigerant · trades_runtime_refrigerant	refrigerant.write
许可证和检查	/api/permits · trades_runtime_permits	permits.write
维护协议	/api/agreements · trades_runtime_agreements	agreements.write
制造商保修索赔	/api/warranty-claims · trades_runtime_warranty_claims	warranty_claims.write
卡车库存与明日需求	/api/truck-stock · trades_runtime_truck_stock	truck_stock.write
回访根因	/api/callbacks · trades_runtime_callbacks	callbacks.write

根据 2026-10-19 查阅的 eCFR，制冷剂规则如下：

• 泄漏率依据 40 CFR 82.152 计算。
• 第 608 节的泄漏维修要求适用于满充量达到或超过 50 lb 的 ODS 制冷剂（40 CFR 82.157）。
• AIM Act 规则自 2026-01-01 起适用于满充量达到或超过 15 lb 的 HFC 制冷剂，但不包括住宅和轻型商用空调（40 CFR 84.106）。
• 触发率分别为：商用制冷 20%，工业流程 30%，舒适性制冷和其他设备 10%。

这只是记录辅助工具，不是向 EPA 提交的文件，也不构成法律建议。

这些模块绝不会估算数值：

• 风险收入只使用商家提供的价格：每份协议的价格，或可选的方案价格表（settings.planPrices）。两者都没有的协议会计为价格未知。示例价格是合成占位值。
• 只有商家输入保修申报期限后，才会显示相应期限。
• 从未盘点过的货车库存是未知，而不是零。
• 回访只有通过明确的引用才会关联到原始工单。

live_backends 和 pilot_started 都保持为 false。

人工操作员工作台

工作台是面向人工操作员的界面。公共 Worker MCP 仍是一个不带此界面的只读桥接层。在操作员的机器上，工作台的环回 POST /mcp 允许 Agent 请求写入。写入需要操作员批准；默认关闭。请参阅需经批准的写入。

npm run desk
# http://127.0.0.1:4174/

npm run shadow:field 和 npm run shadow:office 会打印同一份桌面快照的本地影子读取。这两个命令和桌面页面都会读取 data/runtime/<instanceId>/field-events.jsonl（打卡上班、打卡下班、开始用餐、结束用餐、开车回家）以及 data/runtime/<instanceId>/job-prices.json 中的工作价格记录（手动输入的零件成本、人工费、任务费用、利润率、已锁定的折扣）。它们不会维护第二份事件日志。此桌面上的 AZTrades Shell 仅限本地软件。live_backends false。pilot_started false。不是 Field 1.0。这不是 Office Softwares 1.0。ServiceTitan、Jobber 以及其他自带配置仅以只读方式接入。写入需要操作员批准；默认关闭。SupplyHouse 在有编号返回时提供公开 GET；不可用时（403 或无编号）保留手动输入的成本；没有下单路径。此读取不会凭空编造价格。其他具名供应商在获得许可账户前均为空。物业卡片仅记录公司历史。在接入获准来源前，不连接 Zillow、Redfin 和县评估师。本地登录：首位用户获准；后续用户需要更高级别的审批。此 Shell 不会向 ServiceTitan 或 Jobber 写回。 它仅绑定到 127.0.0.1。页面显示工单／完成情况图表、容量图表、任务看板和技术看板、晨间碰头会、履约进度、提醒和评分。回访、保修电话和未分类项会显示在指标和任务看板中。每行电话记录都会注明分类原因（如果导出数据提供了标签）；如果导出数据未提供，则显示未分类。页面、/api/snapshot、/api/view、/api/receipt 和 SSE 流均支持筛选参数 ?calls=callback、?calls=warranty 和 ?calls=not-classified。/api/calls/week.json 提供按业务类别划分的过去一周回访率。/api/huddle 会打印晨间碰头会内容，/api/huddle.json 则以 JSON 格式返回相同看板。晨间碰头会会根据流程观察结果列出 trainingNeeded（严重程度和原因）。它不是技能评分。同一页面还显示零件成本、部门行为和车辆数量。/api/stock 会读取车辆和仓库的库存数量。行驶里程和驾驶表现显示在按员工和部门排名的表现看板旁。可选里程文件路径为 data/runtime/<instanceId>/drive-miles.json 或 data/inbound/drive-miles.json。本地导出数据获准接入后，缺失的文件会保持未知。空文件夹工作台会显示合成演示数据。该演示数据既不是公司导出数据，也不是远程信息处理数据流。排名不是技能评分，也不会设置 trainingNeeded。此处不声称使用任何 GPS 供应商。协作看板会列出来自 Chain D、跨工种和表彰标记的积极协作，并指出服务技术人员（必要时）和安装人员应由谁或哪个业务类别配对或交接。/api/work-together 会返回该看板。员工摩擦率显示在同一表现看板和 /api/friction 中。它统计本机上的交接失败、协调标记、明确记录的回访和延迟交接。导出数据没有相关记录时，状态保持未知。摩擦排名第 1 表示已知摩擦最高，并非表现最佳。它不是托管式人力资源系统，也不会设置 trainingNeeded。这些路由仅在本机运行。每项评分和节奏区间都附有简短说明。本机当前触发的提醒规则可通过 /api/alerts/digest.json 和 /api/alerts/digest.csv 导出为 JSON 或 CSV。如果存在阻止预订的原因，/api/receipt 会打印该原因；如果没有任何阻止项，也会注明。规范 TR-DESK-POLISH-2026-09-25 增加了间距和字体样式、储存在此浏览器中的浅色／深色主题（trades-desk-theme）、业务类别视图，以及可通过 /api/receipt 打印的快照。业务类别是时段数量，或者导出数据提供的已知工种标记（hvac、plumbing、electrical、sewer、cross-trades）。城市名称不属于业务类别。页面不会绘制地图。快照是操作员可打印或保存为 PDF 的 HTML。快照会引用本地回执标识符，但不包含回执正文。该页面上的任何内容都不会向外部发送数据。评分依据任务节奏、证据可信度区间、验证状态（UNVERIFIED）和 recommendBlock。在 BYO 数据投放中，预测置信度会保持隐藏。记录的合成影子日置信度仅在合成演示中显示，并标注为测试夹具。空的入站文件夹会显示合成演示数据。放入文件后，下一次 SSE 更新（约 2 秒后）会反映变化，标签将切换为 BYO-admitted；如果所有文件都声明 synthetic: true，则切换为 BYO-admitted synthetic drill。

本地告警规则（TR-ALERTS-2026-09-25）

本地阈值由相同的评分驱动：容量（开放时段，仅在存在服务区域时）、逾期任务（根据任务时钟统计未完成的行）、信任等级（证据可信度下限，或本机记录的下降）、预约拦截（recommendBlock），以及验证停滞（从最早一次观测起，验证评分持续 N 分钟为 UNVERIFIED 或 CONFLICTED）。不会计算准确率百分比。时钟缺失时不会凭空判定停滞。BYO 服务台的开放时段为空时，不会凭空计算利用率百分比。

将 data/runtime/alerts.json.example 复制到 data/runtime/<instanceId>/alerts.json（已加入 gitignore）。data/inbound/local.json 可以设置 alertsPath 或 alerts 对象。服务台横幅会显示未确认的规则。告警面板会显示有效规则、历史记录和确认操作。确认操作是在 127.0.0.1 上执行的本地 POST，只会写入 alert-state.json。可选钩子会追加到本地 JSONL 文件或向回环地址（127.0.0.1、localhost、::1）发送 POST。任何其他 webhook 主机都会被拒绝。不会向外部发送数据。

入站质量、告警占位项和 Option C 启动门槛（TR-QUALITY-2026-09-27）

/api/inbound-quality 和 /api/inbound-quality.txt 会对本机已有的 ServiceTitan 和 ProBooks 片段进行评分。服务台图表会根据本地报告，按 sourceKind 展示数量、检查清单评分分布和主要缺陷类别。文件夹为空时会使用带标签的合成样例。检查清单不是准确率百分比，也不是实时租户数据拉取。文件会写入 data/runtime/<instanceId>/inbound-quality.json、.txt 和 .jsonl。

/api/alert-actions 仅返回占位项。触发的告警会展开显示标签、原因说明、所需的人工授权，以及 refused: write-back。面板上有《人工授权规则》。占位项不会调用 ServiceTitan 或 ProBooks。

/api/option-c-start-gate 会列出启动条件。每个门槛均保持阻止状态，直至条件满足。Option C 仍处于准备阶段，须由人工操作员启动真实试点。Option D 不在范围内。不会进行切换。随附的目录将 pilot_started 保持为 false。live_backends 保持为 false。面板不会启动试点。

/api/monitoring 提供统一的服务台视图：本地或演示用的技术人员和卡车位置标记、工时卡、覆盖范围交互式地图、合适技术人员建议、行驶评分卡、技术人员评分卡、调度式来电看板和 KPI 图表。位置标记来自 data/runtime/<instanceId>/positions.json、data/inbound/positions.json，或从本地里程文件复制的坐标。复制 data/runtime/positions.json.example。文件夹为空时会使用带标签的合成演示数据。被拒绝的文件不会由该演示数据替代。里程总数仍不考虑坐标。地址地图仍不绘制。这不是实时 GPS 数据流，也不属于远程信息处理供应商。视图会在本地文件发生变化时重新计算。仅供监控。面板上仍显示《人工授权规则》。不会向 ServiceTitan 或 ProBooks 回写任何内容。

/api/time-tracking 是本地工时看板：当前呼叫的计时时长、已用时间、预计剩余时间，以及空闲或行驶时段。将 data/runtime/time-cards.json.example 复制到 data/runtime/<instanceId>/time-cards.json 或 data/inbound/time-cards.json。服务台会在 data/runtime/<instanceId>/ 下写入 time-tracking.json 和 time-tracking.jsonl。本地导出文件获准接入后，缺失文件会保持为空。文件夹为空时，服务台会标注使用合成演示数据。该演示数据不是公司的考勤时钟，也不是 GPS 数据流。

/api/coverage 提供邮政编码、县、市以及道路或高速公路，并可开关显示。将 data/runtime/coverage.json.example 复制到 data/runtime/<instanceId>/coverage.json 或 data/inbound/coverage.json。开关会保存在本机的 coverage-layers.json 中（POST /api/coverage/layers）。数量统计来自该本地文件中的地点、任务和技术人员。不是实时地图图块供应商。地址地图仍不绘制。 /api/right-tech（以及 /api/tech-fit）会根据地理位置、预计剩余时间和技能匹配度，为待处理或已排期的任务排列技师。可选参数 ?job=。仅提供建议。不自动派单。不回写。路程阻碍和较长的本地驾驶时间会作为标记。地理位置不是唯一因素。

操作员可以开启或关闭看板、指标、KPI、技师、评分、图表、泳道、警报、呼叫列和任务衡量指标。所有选项默认开启。选择会存储在此浏览器的 trades-desk-view 中，不会发送到本机以外。见 TR-DESK-VIEW-2026-09-27。

同一页面在约 375px 的屏幕上也可使用。固定域导航可跳转至各个看板。页眉链接、监控图表和宽表格会在页面内滚动，而不会撑宽页面。主题、筛选器、确认、存根披露、打印，以及任何 input、select 或 textarea 的高度至少为 44px，并带有安全区域内边距。宽窗口下的 Softwares 卡片网格保持不变。仍然没有租户数据录入表单。见 TR-MOBILE-DESK-2026-09-27。此版本不包含公开 Worker 卡片。

公开 Worker 可将 npx tsx src/cli.ts desk 和 /local-desk 作为安装说明引用。它不托管调度台、警报钩子或租户指标。本仓库不会部署 Worker。

npm run byo:admit-demo 是操作员软件证明，使用 test/fixtures/byo/ 下的合成测试数据。它会将这些测试数据复制到临时入站目录，通过 FragGate 以 servicetitan + probooks 身份接纳，对数据包进行哈希处理，将隔离收据写入临时 data/runtime/<id>/，打印哈希，并证明封装器 ≠ VERIFIED，同时 ST/ProBooks 写入操作仍会抛出异常。它不是客户数据导出。创作节点不是数据托管方。

真实用户导出文件只能存放在该用户本机的 data/inbound/{servicetitan,probooks,trades-app}/ 下（除 .gitkeep 外均被 git 忽略）。

继承的名称仅来自 specs/aziel-runtime-inheritance.txt。这不是对 aziel-runtime Softwares 的整体复制。

阶梯（如实）

选项	含义	状态
A	仅合并	已完成
B	本地骨干	已在软件中完成
C	单分支影子模式	代码已就绪 / 尚未开始试点
D	建议锁定试点	尚未开始

选项 C 的软件已经存在（命名分支、参与规则、封存结算测试框架、合成演示）。这不是公司试点或实地试点。不要告诉 GM 公司 OS 已上线。不要把选项 C 伪装成正在进行的公司试点。选项 D 仍为否。

TR-OPTION-C-PREP-2026-09-25 是操作员工作站检查清单：本地安装、入站投递文件夹、示例配置、合成数据准入、操作台和警报、SHADOW-SEALED 预期、拒绝写入证明，以及注意事项。npm run pilot:prep 会运行这些检查并打印回执。ready: true 表示机器已通过检查。该回执会让 pilot_started 保持为 false。此命令不会针对公司实际数据开启封存日，也不会写入 ServiceTitan、ProBooks 或任何行业应用。

TR-OPTION-C-PILOT-RUNBOOK-2026-10-02 说明了操作员如何使用已发布的命令启动真实试点。准备检查通过后，操作员工作站上的人员运行 npm run pilot:start -- --branch <branchId>（CLI pilot-start）。必须指定一个命名分支。此命令会重新运行准备检查。如果分支缺失或无效、准备检查尚未就绪，或使用 --claim-company 但入站数据为空或仅包含合成数据，命令就会拒绝执行。成功后，只会为该隔离环境写入 data/runtime/<instanceId>/pilot.json 和 receipts.jsonl 中的一条记录。已发布目录、默认健康状态、glama.json 和赠送版 Worker 固定为 1.0.0，且 pilot_started 保持为 false。模式保持为 SHADOW-SEALED。live_backends 保持为 false。写入需要操作员批准；默认关闭。显式更改模式不会启动试点。回执说明这不是实时运行的公司 OS、不是 Field 1.0，也不是 Office Softwares 1.0。合并本文档不会启动试点。必须由人工在真实且已通过准备检查的分支上运行命令。TR-PILOT-START-2026-10-02 是发布该命令时的提交。本仓库不会部署 Worker，也不会执行 Make Release。

仍须由人工／操作员完成：在他们的工作站上建立真实的 ServiceTitan 接入路径、指定一位 GM，并针对他们的实际数据运行封存日。作者节点不持有该数据转储。准备回执不等于试点。

公开赠送版 Worker

经操作员授权的公开入口是 Cloudflare Worker：

https://trades-runtime.vibelock.workers.dev

Worker 脚本名称：trades-runtime（采用与 aziel-runtime.vibelock.workers.dev 相同的 vibelock workers.dev 账号模式）。源代码：workers/giveaway/。

它的功能：

• 本 VibeLock 主机上的人工赠送版 UI（浏览器 / PWA）：提供诚实说明、引用、MCP、技能和统计信息，无需先下载即可使用
• 可选的 Apache-2.0 计数版 tarball，位于 GET /download（仅在经过验证的 gzip 200 响应后增加计数）
• /local-desk 引用本地 npx tsx src/cli.ts desk 安装。它不托管租户指标或实时公司看板
• 面向 AI 客户端的精简只读 /openapi.json 和 POST /mcp（仅提供健康状态 / 统计信息 / 引用 / 技能）
• Growth-ON 爬取入口：/robots.txt（完整 Allow + Content-Signal）、/sitemap.xml、/ai.txt、/humans.txt、/.well-known/mcp.json、/person.jsonld、/graph.jsonld
• 面向 Glama / Claude Desktop / Cursor 的 Stdio MCP 桥接：npm run mcp → cli/mcp-stdio.mjs（转发至 Worker POST /mcp）
• 如实的 Workers KV 计数器（COUNTS）：views 和 downloads 从 0 开始；仅在成功返回 200 响应后递增；不抽样、不预置、不虚增

部署（操作员／使用 wrangler auth 的设备）

此仓库不会部署 Worker。在 vibelock 账户上首次部署：

npm ci
npm test
cd workers/giveaway
npm ci
npx wrangler kv namespace create COUNTS
# paste the printed id into wrangler.jsonc kv_namespaces[0].id
npm run pack
npx wrangler deploy

之后从仓库根目录部署：

npm run giveaway:pack
cd workers/giveaway && npx wrangler deploy

本地冒烟测试（Miniflare KV，无需 Cloudflare 身份验证）：

npm run giveaway:pack
cd workers/giveaway
npx wrangler dev
# GET http://127.0.0.1:8787/  /download  /v1/health  /v1/stats  /robots.txt  /sitemap.xml  /ai.txt

计数器：参见 workers/giveaway/README.md。

Glama（Install Server 包）

预期的列表页面：在 Glama 上试用

文档中记录了列表页面 URL，方便 Agent 和用户查找。Git 包（glama.json + Dockerfile + cli/mcp-stdio.mjs）是 Glama 索引并托管 stdio 进程所需的内容。**仅凭此 Git 树，不声称 Install Server 已上线。**步骤：docs/GLAMA.md。

不要捏造 Glama TDQS 评分。列表页面 Latest 仍衡量 1.0.0-local，与仓库内 Softwares 引用版本 1.0.0 不一致。等待追赶更新。这个差距既不代表 Field 1.0，也不代表 Office Softwares 1.0。

检查日期：2026-10-02：Glama Latest/releaseVersion 为 1.0.0-local（见 https://glama.ai/mcp/servers/@AzielEliab/trades-runtime 上的 latestRelease.version）。公开徽章仍显示 1.0.0-local，与仓库内 Softwares 引用版本 1.0.0 不一致。等待追赶更新。Official MCP Registry 仍衡量 1.0.0-local。此版本不会重新发布它。本地 Softwares 1.0。这个差距不代表 Field 1.0 声明，也不代表 Office Softwares 1.0。glama.json 版本是仓库内的声明文件（1.0.0），目前仍与公开徽章 1.0.0-local 不一致。等待追赶更新。此仓库中的 Worker 源码版本为 1.0.0。giveaway Worker 的版本固定值为 1.0.0。检查日期：2026-09-28：已在运行的 Worker 仍为 0.4.12。此版本不会部署，也不会 Make Release。pilot_started false。live_backends false。

本地／Docker：

npm run mcp
# or
node cli/mcp-stdio.mjs
docker build -t trades-runtime-mcp .
docker run --rm -i trades-runtime-mcp

Pages（有意禁用）

GitHub Pages 有意禁用。不存在 .github/workflows/pages.yml。不要添加 Pages 部署工作流。不要在仓库上启用 Pages。不要将 github.io URL 视为在线产品入口。

软件可免费克隆。GitHub Pages 保持关闭。不要启用 Pages。不要在 docs/ 下添加 PDF。如果 Worker 已部署，浏览器 UI 地址为 https://trades-runtime.vibelock.workers.dev。此仓库不会部署该 Worker。计数用 tarball 为可选项。

本地 UI 预览（保持 Pages 关闭）：

python3 -m http.server 4173 --directory docs

机器目录：docs/v1/runtime.json。模块 UI：/modules/。

本项目不是什么（§1.2）

不是简单的派单优化器。不是以收入作为技能指标的排行榜。不是固定的早间路线规划器。不是会暗中凌驾于人类之上的自主黑箱。不是将照片作为不当行为的证明。不是燃油优先。不是自动实施 30 天回访惩罚。不是 PDF 门户。

许可证

Apache License 2.0。参见 LICENSE。