diff --git a/docs/活动开发规范.md b/docs/活动开发规范.md index 74b8679..d604022 100644 --- a/docs/活动开发规范.md +++ b/docs/活动开发规范.md @@ -105,7 +105,7 @@ activities// | ① identity | `activityId / name / packageVersion / category / sdkVersion / checksum / signature?` | **无 paradigm**;`sdkVersion` 与 SDK 精确相等否则拒装;**改了包内容必须升 packageVersion**(同版重装 no-op,改了不升版 = 静默丢失) | | ② contract | 七件契约(§4.3) | | | ③ declarations | `models[] / tools[] / ledger[] / listeners[] / harness` | 运行时**只读这里**的工具与模型声明;监听时限必配否则 `dangling-listener` 拒装 | -| ④ assets | `businessModel{cmmnXml, narrative, dmn} / skills / viewTemplates / cardSchemas / distillHooks` | CMMN 与说明书**同版本发布不允许分叉**(空任一即拒装) | +| ④ assets | `businessModel{cmmnXml, narrative, dmn} / skills / viewTemplates / cardSchemas / distillHooks` | CMMN 与说明书**同版本发布不允许分叉**(空任一即拒装);**关键表单逐张配 HTML 报告模版**(执行与验收都要,待处理与成果同模版,§9.3) | | ⑤ samples | `{name, input, message?, expect:{ports[], payloadShape?}}[]` | **至少 1 条**;首装无历史时以静态审 + 样例集替代回放审 | | ⑥ entry | `{file, checksum}` | 指 .js 产物 | @@ -345,20 +345,35 @@ discretionaryItem/itemControl/…)。**表外构件直接拒**(`assertSubset` | 类 | 字段(PRD `model.ts:106-133` ↔ WOS `card.ts:279-350`) | 用途 | |---|---|---| -| **执行** | `ask`(工作要求)/ `steps[]`(作业指导书分步要点)/ `standard?`(完成标准)/ `basedOn?`(报告正文取自哪份过程成果 —— 人要在数据上作判断,就得把数据摆在表单旁)/ `blocks?` / `fields[]`(回填表单,字段可带 **ai 拟值**)/ `submitLabel?` | 做 AI 的工作要求 —— **原「补全」并入此类**;⚠️ 工具未命中转人也走这张卡(第 12 章②) | +| **执行** | `ask`(工作要求)/ `steps[]`(作业指导书分步要点)/ `standard?`(完成标准)/ `basedOn?`(报告正文取自哪份过程成果 —— 人要在数据上作判断,就得把数据摆在表单旁)/ `blocks?` / `fields[]`(回填表单,字段可带 **ai 拟值**)/ `submitLabel?` | 做 AI 的工作要求 —— **原「补全」并入此类**;回填报告用活动持有的 HTML 模版(§9.3);⚠️ 工具未命中转人也走这张卡(第 12 章②) | | **验收** | `deliverable / criteria(L1-L5)/ actions?(待落地动作意向,读/写)/ portChoice? / passLabel?` | 收 AI 的成果:放行 / 驳回(必附意见) | 对话区另有三张卡:**决策**(选择题,recommend + 后果说明)、**fill 补全卡**(就地要几个 小信息;「没法填的理由」是另一条必走之路)、**rate 评价卡 —— 暂不做**(schema 在,不接)。 -### 9.3 视图模版 +### 9.3 HTML 报告模版:活动持有,一单一模版贯穿始终 -活动推视图两条路:`pushView(blocks)`(结构化块,11 型:callout/kv/badges/table/bars/donut/ +**活动的每一张关键表单,都必须有对应的 HTML 报告模版** —— 模版是**活动自己持有的资产** +(`assets.viewTemplates`,随包版本冻结),不是系统临场生成的。三条硬规矩: + +1. **执行与验收都要配**:执行工单的回填报告、验收工单的成果报告,各有其模版 —— + 人办工单时看到的不是一堆裸字段,是一份**已排好版的报告**(AI 拟值已填、可编辑, + 数据摆在表单旁边,`basedOn` 引用的过程成果就嵌在报告正文里); +2. **从待处理工单到工作成果报告是同一张模版**:工单在办时,卡面 = 报告模版 + + 作业指导 / 验收判据;办结后**指导与判据卸下,只剩报告** —— 它原样进「工作成果」 + 页签成为归档件。不许为「在办」与「归档」各做一张模版:两张迟早长歪, + 人回头核对时对不上账。语义出处:PRD ViewRegion 头注「一张工单 → 卡组一 + (HTML 报告 · AI 已填好、可编辑)+ 卡组二(作业指导 / 验收判据);办结后只剩 + 报告卡 —— 指导与判据是办理时的参照,不进归档件」; +3. **一个局面一张模版**(受理中/已分类/待放行……):局面变了换模版, + 不在一张模版里堆条件分支。 + +推送两条路:`pushView(blocks)`(结构化块,11 型:callout/kv/badges/table/bars/donut/ mail/cards/waiting/files,`card.ts:103-201`)与 `pushHtml(html)`(HTML 模版)。 模版纪律(`activity-sdk/src/view.ts`):容器是 `sandbox=""` iframe,**无脚本执行权、 样式必须自带**;数据由基座推送时填(`data-slot` 取值、`data-rows` 逐行展开); SDK 给了 `viewShell / kvCard / tableCard / noteCard / stagesCard` 拼装件,照 -`activities/quote-intake/src/views/report.ts` 用。**一个局面一张模版**(受理中/已分类/待放行)。 +`activities/quote-intake/src/views/report.ts` 用。 ### 9.4 运行时的卡怎么到人(✅ 链路) @@ -392,7 +407,7 @@ listeners / llmCalls / writes` —— 断言活动这一回合做了什么。工 ### 11.2 自测四段(照 `activities/quote-intake/__tests__/activity.test.ts`) 1. **清单合规**:过 `activityManifestSchema`;监听时限已配;L1/L2 判据可机检;禁区非空 + 调人预算 > 0; -2. **案例模型**:CMMN 双表示齐备;触达世界的项全标 manualActivationRule;末尾有收口验收项; +2. **案例模型与模版**:CMMN 双表示齐备;触达世界的项全标 manualActivationRule;末尾有收口验收项;**关键表单逐张有报告模版**(执行/验收都配、无脚本、待处理与成果同模版); 3. **DMN**:逐规则求值断言(同输入必同结论、优先级、任意格); 4. **入口**:mock host 跑 run —— 各局面的 outcome、推了什么视图、说了什么话、守卫真的拦 (无脚本/裸调用/时限必配)。