应用接入 JMOS 指南

来源：仓库 docs/应用接入JMOS指南.md · 版本 0ca44f9 · 契约依据为 9-18 缓存 v0.1，待实时复核 · 契约原文不随本站发布

更新日期：2026-10-09，Asia/Shanghai。适用对象：做界面的 UI/UX 同事（包括刚入门的）、写服务的后端同事。

本文说明一个应用怎样“接入 JMOS”：前端怎样长得像 JMOS、怎样出现在应用中心和工作台里、怎样把数据和提交交给可替换的适配器；后端怎样按 JMOS 架构找到负责的模块、按版本化契约对接、不绕路。全文用 13 故障诊断 做贯穿示例，对应的可运行样张在 prototypes/app-integration-13/。

依据与时效（请先读）

• 分层原则以本仓 JMOS 前后端分层与契约边界（docs/JMOS前后端分层与契约边界.md） 为准，本文是它的操作手册，不改变其中任何规则。
• 架构与契约来自契约仓 jmos-n31（HEAD 3e081bfb6c1c09ff49301bc65c3ac6d7f8ad7637，提交于 2026-09-22 15:55 UTC+8），契约为设计 v0.1、contract_version 0.1.0、审批 D-S4，由生成器确定性生成、不手改。Bridge 缓存最近全量同步为 2026-09-18 19:13:44 UTC+8；14 份文档的摘要与 来源记录（reviews/2026-10-07/layering/bridge-contract-sources.json） 一致。
• 未完成实时复核：2026-10-07 门户不可达；2026-10-09 14:08 UTC+8 本机 jmos status 因配置键不匹配无法运行（未修改配置）。下文所有契约事实都是“9-18 缓存 + 契约 v0.1”，待实时复核。设计线正在修订 v0.2，换版后需重核本文引用。
• 契约原文里没有的东西，本文一律写作 契约缺口，不猜路径、不补字段。

1. 一页总览

一句话：页面只管显示和交互；数据、判断和提交都经过“能力接口 → 适配器 → JMOS 模块”这条路，演示和正式可以一键切换，正式失败时如实报错，不偷偷换回演示数据。

flowchart LR
  subgraph 前端["前端（本仓）"]
    V["页面视图<br/>HTML/CSS/图表/局部交互"] --> U["前端用例<br/>加载·草稿·提交·重试"]
    U --> P{{"能力接口<br/>如 diagnosisPort"}}
    P --> D["演示适配器<br/>固定数据·可重置"]
    P --> F["正式适配器<br/>按契约映射"]
    U --> H["宿主桥接<br/>导航·主题·上下文·生命周期"]
  end
  B["初始化入口 boot<br/>选择并注入适配器"] -.-> P
  F -->|"浏览器入口（多数仍是契约缺口）"| E["entry / mat 等 JMOS 模块"]
  E --> S["dsvc 读取 · upc 身份 · rt→down 受控写 · twin→ver→eval 排练与签发"]
  H <-->|"postMessage（只编排，不做业务）"| W["07 工作台 / 05 应用中心"]

接入一个应用的完整流程：

flowchart TD
  A["1 写清能力：用户在这页要做什么"] --> B["2 经 Bridge 查模块归属与契约<br/>记录路径·版本·审批·来源·同步时间"]
  B --> C["3 定义能力接口（port）<br/>方法、结果信封、错误语义"]
  C --> D["4 写演示适配器<br/>把剧本/样例/模拟提交搬进来"]
  D --> E["5 页面改为只依赖接口<br/>导航与提交分开"]
  E --> F["6 写正式适配器骨架<br/>已定字段映射，缺的标契约缺口"]
  F --> G["7 登记：05 应用中心、07 工作台、问小锦"]
  G --> H["8 验收：视觉对照、交互、两种适配器、内嵌"]
  H --> I["9 契约补齐后逐项接通<br/>真实集成另行验收"]

2. 前端接入清单：设计基础

新应用首先要“看起来、用起来就是 JMOS”。这些是硬要求，来源见各行。

13 示例：13 原本就满足以上各项，接入样张没有改任何颜色、圆角、字体或布局；新增的两处样式（第 6 步“尚未提交”、接入状态面板）只用已有变量，见 §9。

3. 登记：出现在 05 应用中心和 07 工作台

JMOS 里“应用存在”的权威是 reg 注册中心（architecture.json 节点 reg：制品与能力目录，“一切契约的挂靠点”）。但契约仓目前没有 reg__* 契约目录，前端拿不到权威目录 —— 这是 契约缺口。在补齐之前，UI 仓里按下面的位置静态登记，并且把“目录存在”“有权限”“运行健康”“业务摘要”当成四件不同的事。

重复清单本身是已登记的耦合（分层文档“05 及 07：重复应用清单”），以后应收敛为“单一展示目录 + 可替换目录适配器”，届时目录适配器对接 reg。

4. 宿主桥接：页面和工作台之间能说什么

内嵌在 07（iframe）时，页面与宿主只交换导航、主题、上下文、视图生命周期四类消息。审批、执行、计数这类业务事实不能靠 postMessage 决定。

要求：来源与载荷校验集中在宿主桥接适配器里做；“视图已就绪”“消息已投递”“服务已受理”“业务已完成”分开记录。页面不读别的页面的全局变量，也不覆盖别的页面的函数。

5. 能力接口与适配器：演示和正式怎么装配

5.1 三件东西

1. 能力接口（port）：用业务语言写的一组方法，例如“读取诊断”“生成变更草稿”“提交到待确认”。页面和用例只认它。
2. 演示适配器：实现接口，返回固定、可复现、可重置的数据；演示状态放在独立命名空间（例如 sessionStorage 的 jmos-demo/13，?demo-reset=1 清空）。剧本、样例数据、模拟提交、演示时钟都放这里。
3. 正式适配器：实现同一接口，按契约组请求、解析信封、转换错误。失败时返回真实错误或降级，绝不回退成演示数据。

5.2 结果统一用响应信封的外形

所有方法返回 Promise<Result>，外形沿用 contracts/_common/response-envelope.schema.json（v0.1.0）：

前端可以加一个自己的 source: 'demo'|'bridge' 字段区分来源，但要注明它不属于契约。注意：现有错误码只覆盖 ev/dsvc/gw/upc/obs，mat、entry、reg 没有错误码表（契约缺口），前端在缺口期用 frontend.* 前缀标记自己产生的错误，不冒充服务端码。

5.3 装配：初始化入口显式选择

// boot.js —— 启动时明确选一个，不做“失败就换另一个”
const q = new URLSearchParams(location.search);
const port = q.get('adapter') === 'bridge'
  ? JMDiagnosisBridgeAdapter.create({ /* 身份、范围等由宿主或登录流程提供 */ })
  : JMDiagnosisDemoAdapter.create();
const app = JMDiagnosisApp.create({ port, host: JMHostBridge.create(window) });
JMDiagnosisView.mount(app);
app.start(q.get('case'));

页面上要有一个默认收起的“接入状态”说明（13 样张在左栏底部），告诉看的人当前是演示还是正式、契约版本、数据来自哪里。

5.4 写操作的三条前端规矩

• 导航不是提交：切步骤、自动播放、刷新、深链到某一步，都只改视图；提交只在用户点明确的提交按钮时发生。
• 幂等：同一份草稿重复点提交，用同一个幂等键（对应 X-Idempotency-Key）；按钮防连点不等于服务端幂等。
• 以服务确认推进：只有服务受理后才显示“已提交”、才通知宿主；超时且结果未知时先查证，不能当失败重试。

6. 状态与存储归属

7. 后端按 Bridge 接入

7.1 先查模块归属（每个新能力都走一遍）

1. 用 Bridge 查：jmos status 确认连接与同步时间，再查模块、上下游连线和完整契约（Bridge 的 MCP 工具或门户）。查不到实时结果时，用 Bridge 缓存或契约仓原文，并在登记表写明“缓存/原文，同步时间，待实时复核”。
2. 在 architecture.json 找节点：看 layer_name、one_liner、target、分期任务 phase_tasks、认领状态 status。节点之间的连线 E-xx 才是服务间约定。
3. 找契约目录：contracts/<from>__<to>/（每条连线一个）或 contracts/<node>__north/（北向公共契约）。每个目录只有 README.md、openapi.yaml、asyncapi.yaml、mcp-tools.yaml、*.schema.json；README 写明连线标签、形态、contract_version、N/N-1 截止、审批编号。
4. 记录：原文路径、版本、审批、来源（实时/缓存）、同步时间、明确字段、开放问题（待定）、浏览器能否直接调用。
5. 服务间连线 ≠ 浏览器 API。E-21、E-25、E-26 等是服务之间的约定，前端不能直接调用；浏览器能调用哪个入口必须有北向或专门的消费契约，没有就是契约缺口。

7.2 模块职责（摘自 architecture.json，事实源 v0，抽取于 2026-09-11）

7.3 硬规则

1. 不旁路：不从页面或应用后端直连 PLC、MES、数据库或内部服务；读取走 dsvc，模型走 gw。
2. 写设备只走 rt → down（E-25）：contracts/rt__down/ 规定写入经 POST /v1/down/intents，并明确禁止直连 PLC/DB。请求里 confirm_token_ref、capability_token_ref、lock_id 是三样东西，不能合并成一个“已授权”。
3. 审批、下发、读回分开：E-26（contracts/entry__rt/）的确认令牌 token_id / long_task_id / intent_id / watch_authority / evidence_pack_ref 各指不同实体，过期令牌不会被自动执行；E-25 的命令状态（accepted / dispatched / readback / rejected / voided / aborted，枚举待定）与 readback_match 分开显示。审批通过 ≠ 已执行 ≠ 读回一致。
4. 响应信封：所有业务响应带 status ok/degraded/error、错误码、证据引用、correlation_id、contract_version（contracts/_common/response-envelope.schema.json）。OAuth 响应按其协议，不套信封。
5. 公共头（contracts/_common/headers.yaml）：Authorization（Bearer，UPC 签发）、X-Actor-Id（{kind}:{id}，human/agent/tool）、条件必需的 X-On-Behalf-Of、X-Access-Scope（只能是子集，不扩权）、X-Correlation-Id（UUIDv7）、X-Contract-Version、写请求的 X-Idempotency-Key；X-Read-Semantics 只用于 dsvc，X-Model-Policy 只用于 gw。
6. 身份走 upc：令牌由 upc 签发（E-10 contracts/upc__entry/：POST /v1/upc/tokens:issue 只返回 token_ref / expires_at / scope，不回明文）；委托主体、执行主体、责任主体、授权主体分别保留（GET /v1/upc/assertions 的 exec_subject / duty_subject / authz_subject）。前端的“能不能点”不是授权。
7. 排练不是执行证明：twin → ver（E-07 contracts/twin__ver/）给出的 docket_ref 只是证据清单引用，尚未裁决；裁决在 ver → eval（E-20）。3D 动画不能充当试算结果。
8. 密钥不进仓：密钥只放被忽略的 .secrets/，不打印、不提交、不明文发布。

7.4 前端能用的后端结果怎么显示

7.5 契约缺口登记表（模板）

每个应用接入时复制此表，逐项填写。“能力存在、界面已做、演示通过、契约对齐、服务接通、集成通过”分别记录，不能互相代替。

8. 每个应用的接入步骤、验收表与自查清单

8.1 接入步骤

1. 拍基线：独立页与 07 内嵌、浅/深、390 触屏/768/1440/2560 各截一组，记下已批准的交互。
2. 写能力表：页面上每个“读、判断、写”的动作列出来，标出属于哪个模块（§7.2）。
3. 查契约：按 §7.1 登记，缺的进 §7.5。
4. 定义能力接口：方法名用业务语言；每个方法返回信封外形；写清哪些只读、哪些是写。
5. 抽演示适配器：把页面里的剧本、样例数据、模拟提交、演示时钟原样搬过去，页面不再内嵌数据。
6. 页面只依赖接口：保持原 HTML 结构和类名，像素不变；把“导航”和“提交”拆开；跨页只传结构化数据和证据引用。
7. 正式适配器骨架：已定字段写映射；未定的标 TODO 契约缺口；在接通前不发真实请求，返回“未接通”。
8. 登记（§3）并检查宿主消息只在允许范围（§4）。
9. 验收（§8.2），记录结果和截图，人眼看过再下结论。
10. 契约补齐后逐个方法接通正式适配器；真实授权、幂等并发、受控写、审计属于集成验收，演示通过不算。

8.2 验收表

8.3 新应用自查清单

• 只用色彩 v1 已有变量，没有新 HEX / rgba / color-mix，没有暖色或新装饰
• 图标全部来自 icons/jmos-icons.js
• 圆角、细线、状态标签与同类组件一致
• 有模块导航时，手机底栏用方案 A 配方
• ?theme=、本地偏好、宿主 jmos-theme 三条路都能切主题；图表随主题重绘
• 390 到 2560 无级自适应，无横向溢出；触屏可用；减少动态效果生效
• 加载 assist.js 并声明页号，可问对象被标记，/ 就地打开
• 已在 05、07（META/SCENE、需要时 FLUIDP）、mvp.js JM_APPS、assist.js PAGES 登记
• 页面不含业务数据、剧本或模拟提交；都在演示适配器里
• 页面不直接用 fetch、localStorage（主题除外）、postMessage；经接口或宿主桥接
• 导航与提交分开；提交幂等；受理后才显示成功、才通知宿主
• 跨页只传结构化数据与证据引用，不传 HTML
• ?adapter=bridge 时显示“未接通”或真实错误，不回退演示数据
• 默认收起的接入状态说明写清当前层次与契约版本
• 每个契约引用带路径、版本、审批、来源与同步时间；缺口已登记
• 后端：读取走 dsvc、模型走 gw、身份走 upc、写设备只走 rt→down，审批/下发/读回分开
• 演示页写明“演示数据为虚构示例”；不提交密钥，不明文发布

9. 贯穿示例：13 故障诊断

样张：prototypes/app-integration-13/（node prototypes/app-integration-13/server.mjs，本机 （本机预览地址））。原页 app/jmos/13-故障诊断.html 未改。

9.1 能力表与模块归属

9.2 拆掉的两处耦合

1. 第 5 步到第 6 步不再连带提交。原页里任何“去第 6 步”的点击都会弹“已提交到待确认”并发队列消息。样张中：步骤条、下一步、键盘、自动播放、深链都只切换视图；第 5 步的主按钮改为 data-submit，只有点它才调用 submitChange，受理后再跳到第 6 步。未提交时进入第 6 步显示“变更单尚未提交”的预览态（合规改动，见 §9.4）。
2. 跨页不再传 HTML。原页发给 07 的 jmos:queue 携带拼好 HTML 的队列项。样张发送 {type:'jmos:queue', v:2, id, change, evidence_refs}：change 是结构化变更（对象、变更前后、生效条件、检查、升级、执行方式、时间线），evidence_refs 是信封格式的证据引用。07 里由投影脚本把它渲染成 10 现有的队列项格式，经验证与原页产生的队列项完全一致；以后应由 10 直接渲染结构化数据。

9.3 正式适配器的契约映射（摘要）

完整映射与缺口表见 app-integration-13.md 与 prototypes/app-integration-13/integration/diagnosis-bridge-adapter.js。

9.4 相对原页的可见变化（全部列出）

仍未拆的耦合（不在本样张范围）：assets/assist.js 内部依赖页面全局 go 和 DOM；“问小锦”链接的上下文仍是静态文本；反馈按钮（有帮助/不准确）的写入尚无契约。

10. 术语速查