ila/yovision
1
0
Fork 0
Code Issues 14 Pull Requests 14 Actions Packages Projects Releases Wiki Activity

[CTR] 冻结 Sense/Brain→Bell 标准事件与证据引用契约 v1 #150

New Issue
Closed
opened 2026-08-29 21:04:54 +08:00 by ila · 5 comments
ila commented 2026-08-29 21:04:54 +08:00
Owner
Copy Link
Copy Source

状态

已完成（2026-08-31，用户验收通过）

基本信息

  • 类型：共享契约 / 跨项目协调
  • 主项目：YoVision contracts
  • 主 agent：单一 coordination agent
  • 所属 Epic：#7
  • 所属 MVP：#156
  • 来源：#124 对 Sense #73/#78、Brain #16、Bell #131–#133 的去重汇总
  • 生产者：Brain；Sense 可作为默认部署中的受控 gateway/relay 和证据所有者
  • 消费者：Bell
  • 前置：#8 已验收；实施前确认本工单技术设计
  • 契约事实源：contracts/events/v1/**、contracts/evidence/v1/**

目标

冻结匿名安全事件和证据逻辑引用契约 v1，使 Bell 以 (producer_id, source_event_id) 永久幂等接收，并保持 Event 不可变、Alert/ack/close 仍由 Bell 独占。

已确认边界与拟议设计

  • 标准事件包含 schema 版本、producer/source event ID、站点/逻辑设备/Profile 引用、事件类型、发生时间、规则/模型版本、匿名观测、区域引用、严重级别及证据逻辑引用/状态。
  • 原始 producer identity 在 Sense relay 后仍可追溯；relay 不把投递重试变成新的业务事件。
  • 证据只共享逻辑引用、类型、pending/processing/success/failed 状态、时间与完整性元数据；不得携带本机路径、摄像头凭据或长期可转发的签名 URL。
  • 相同幂等键和规范化载荷返回同一 Bell Event；相同键不同载荷稳定冲突并审计。
  • Brain 内部 candidate、Sense 本地 candidate/Outbox 和 Bell Event/Receipt/Alert 均保持内部模型，由显式 mapper 对接。
  • v1 只做兼容扩展；字段语义破坏发布新主版本，保留上一版本兼容窗口和回退样例。

非目标

不共享 Alert 状态机、用户/RBAC、数据库表、通知状态或运维告警；不实现证据存储、机器身份、connector、通知升级或 UI。

精确 write_paths

  • contracts/events/v1/**
  • contracts/evidence/v1/**
  • contracts/tests/events-v1/**
  • contracts/tests/evidence-v1/**

禁止写入：Sense/**、Brain/**、Bell/**、其他 contracts/**、根级部署和 docs/**。

验收标准

  • Event 与 evidence Schema/OpenAPI、规范化、幂等、错误和兼容说明完整
  • Brain/Sense producer mapper 与 Bell consumer mapper 字段责任明确
  • 匿名区域/越线样例、证据 pending/success/failed、重复/冲突和未知版本样例齐全
  • 不含凭据、内部路径、用户 token、人脸特征或 Alert/ack 状态
  • 生产者、relay、Bell 的契约测试和回退责任明确

验证

Schema/OpenAPI 校验、规范化/幂等向量、敏感字段拒绝、生产者与消费者 fixture 兼容、未知版本与证据降级测试。

风险与回退

错误幂等或事件语义会制造重复/漏报。协议未冻结不得上线 connector；回退保留旧版本接入，停用新版本生产者，不删除 Event/Receipt/Outbox 事实。

设计与文档影响

非 UI 任务，以事件/API/数据设计作为确认门禁；冻结后更新 Product-Requirements、Architecture、Business-Rules 和验证 Wiki。

## 状态 已完成（2026-08-31，用户验收通过） ## 基本信息 - 类型：共享契约 / 跨项目协调 - 主项目：YoVision contracts - 主 agent：单一 coordination agent - 所属 Epic：#7 - 所属 MVP：#156 - 来源：#124 对 Sense #73/#78、Brain #16、Bell #131–#133 的去重汇总 - 生产者：Brain；Sense 可作为默认部署中的受控 gateway/relay 和证据所有者 - 消费者：Bell - 前置：#8 已验收；实施前确认本工单技术设计 - 契约事实源：`contracts/events/v1/**`、`contracts/evidence/v1/**` ## 目标 冻结匿名安全事件和证据逻辑引用契约 v1，使 Bell 以 `(producer_id, source_event_id)` 永久幂等接收，并保持 Event 不可变、Alert/ack/close 仍由 Bell 独占。 ## 已确认边界与拟议设计 - 标准事件包含 schema 版本、producer/source event ID、站点/逻辑设备/Profile 引用、事件类型、发生时间、规则/模型版本、匿名观测、区域引用、严重级别及证据逻辑引用/状态。 - 原始 producer identity 在 Sense relay 后仍可追溯；relay 不把投递重试变成新的业务事件。 - 证据只共享逻辑引用、类型、pending/processing/success/failed 状态、时间与完整性元数据；不得携带本机路径、摄像头凭据或长期可转发的签名 URL。 - 相同幂等键和规范化载荷返回同一 Bell Event；相同键不同载荷稳定冲突并审计。 - Brain 内部 candidate、Sense 本地 candidate/Outbox 和 Bell Event/Receipt/Alert 均保持内部模型，由显式 mapper 对接。 - v1 只做兼容扩展；字段语义破坏发布新主版本，保留上一版本兼容窗口和回退样例。 ## 非目标 不共享 Alert 状态机、用户/RBAC、数据库表、通知状态或运维告警；不实现证据存储、机器身份、connector、通知升级或 UI。 ## 精确 write_paths - `contracts/events/v1/**` - `contracts/evidence/v1/**` - `contracts/tests/events-v1/**` - `contracts/tests/evidence-v1/**` 禁止写入：`Sense/**`、`Brain/**`、`Bell/**`、其他 `contracts/**`、根级部署和 `docs/**`。 ## 验收标准 - [x] Event 与 evidence Schema/OpenAPI、规范化、幂等、错误和兼容说明完整 - [x] Brain/Sense producer mapper 与 Bell consumer mapper 字段责任明确 - [x] 匿名区域/越线样例、证据 pending/success/failed、重复/冲突和未知版本样例齐全 - [x] 不含凭据、内部路径、用户 token、人脸特征或 Alert/ack 状态 - [x] 生产者、relay、Bell 的契约测试和回退责任明确 ## 验证 Schema/OpenAPI 校验、规范化/幂等向量、敏感字段拒绝、生产者与消费者 fixture 兼容、未知版本与证据降级测试。 ## 风险与回退 错误幂等或事件语义会制造重复/漏报。协议未冻结不得上线 connector；回退保留旧版本接入，停用新版本生产者，不删除 Event/Receipt/Outbox 事实。 ## 设计与文档影响 非 UI 任务，以事件/API/数据设计作为确认门禁；冻结后更新 Product-Requirements、Architecture、Business-Rules 和验证 Wiki。
ila commented 2026-08-29 21:21:13 +08:00
Author
Owner
Copy Link
Copy Source

设计确认（2026-08-29）

用户在 #124 验收闭环后的下一步中明确回复“已确认”。按上一条明确建议，本次确认覆盖 #148、#149、#150 的协议/状态设计与兼容、回退边界；工单进入“待实施”。

本次只放行后续实施，不代表功能验收，不关闭工单，也不扩展为对高风险 #151 机器身份认证、轮换和吊销方案的确认。

## 设计确认（2026-08-29） 用户在 #124 验收闭环后的下一步中明确回复“已确认”。按上一条明确建议，本次确认覆盖 #148、#149、#150 的协议/状态设计与兼容、回退边界；工单进入“待实施”。 本次只放行后续实施，不代表功能验收，不关闭工单，也不扩展为对高风险 #151 机器身份认证、轮换和吊销方案的确认。
ila commented 2026-08-31 08:46:41 +08:00
Author
Owner
Copy Link
Copy Source

实施完成证据（2026-08-31）

最终差异

  • 在 contracts/events/v1/** 冻结 Event、接收结果、problem JSON Schema 与 OpenAPI，规定原始 (producer_id, source_event_id) 永久幂等、RFC 8785/JCS + SHA-256 规范化、重复返回原 Event、载荷冲突稳定 409 并审计、未知版本 422。
  • 在 contracts/evidence/v1/** 冻结逻辑证据引用及查询 OpenAPI，覆盖 pending、processing、available、failed 和 404/410 降级；不授予对象访问，也不允许路径、凭据或签名 URL。
  • README 逐字段明确 Brain/Sense producer、Sense relay/evidence owner 与 Bell consumer/receipt 的责任、兼容窗口和停用新生产者的回退方式。
  • 提供危险区域、方向越线、证据 pending/success/failed、duplicate/conflict、未知版本及敏感字段拒绝 fixture；纯 Python 标准库测试可直接复制执行。

验证结果

  • python contracts/tests/events-v1/test_contract.py：7/7 通过。
  • python contracts/tests/evidence-v1/test_contract.py：4/4 通过。
  • python dev_scripts/harness.py check --strict：通过。
  • python -m unittest discover -s tests -v：48/48 通过。
  • git diff --check 与暂存差异检查：通过。
  • 写路径审计：提交仅含工单声明的四组 contracts/** 路径；未修改 Sense、Brain、Bell、其他 contracts、根级部署或 docs。

提交与评审

  • 提交：2a395aa12604baa641798d2ee73fca2635ea7b30
  • PR：#158 feature/150-event-evidence-contract → dev
  • PR 当前可合并，但按流程未合并、工单未关闭，等待用户验收。

未验证内容

尚未接入真实 Brain/Sense mapper、relay、Bell mapper 或 connector，未执行跨进程/并发幂等和生产证据存储验证；这些属于后续 connector/E2E 工单。机器身份和访问授权仍由未确认的 #151 处理。当前环境未安装第三方 JSON Schema/OpenAPI 校验器，已用受控关键词的依赖零契约测试验证全部样例、条件分支和引用。

文档影响

协议冻结会影响长期 Product-Requirements、Architecture、Business-Rules 和验证 Wiki。按三份并行契约工单的协调约定，本工单不并发修改 Wiki/docs/**，由根协调 agent 在 #148–#150 汇总后串行更新、回读并同步镜像；未创建任务归档。

## 实施完成证据（2026-08-31） ### 最终差异 - 在 `contracts/events/v1/**` 冻结 Event、接收结果、problem JSON Schema 与 OpenAPI，规定原始 `(producer_id, source_event_id)` 永久幂等、RFC 8785/JCS + SHA-256 规范化、重复返回原 Event、载荷冲突稳定 `409` 并审计、未知版本 `422`。 - 在 `contracts/evidence/v1/**` 冻结逻辑证据引用及查询 OpenAPI，覆盖 `pending`、`processing`、`available`、`failed` 和 404/410 降级；不授予对象访问，也不允许路径、凭据或签名 URL。 - README 逐字段明确 Brain/Sense producer、Sense relay/evidence owner 与 Bell consumer/receipt 的责任、兼容窗口和停用新生产者的回退方式。 - 提供危险区域、方向越线、证据 pending/success/failed、duplicate/conflict、未知版本及敏感字段拒绝 fixture；纯 Python 标准库测试可直接复制执行。 ### 验证结果 - `python contracts/tests/events-v1/test_contract.py`：7/7 通过。 - `python contracts/tests/evidence-v1/test_contract.py`：4/4 通过。 - `python dev_scripts/harness.py check --strict`：通过。 - `python -m unittest discover -s tests -v`：48/48 通过。 - `git diff --check` 与暂存差异检查：通过。 - 写路径审计：提交仅含工单声明的四组 `contracts/**` 路径；未修改 Sense、Brain、Bell、其他 contracts、根级部署或 docs。 ### 提交与评审 - 提交：`2a395aa12604baa641798d2ee73fca2635ea7b30` - PR：#158 `feature/150-event-evidence-contract` → `dev` - PR 当前可合并，但按流程未合并、工单未关闭，等待用户验收。 ### 未验证内容 尚未接入真实 Brain/Sense mapper、relay、Bell mapper 或 connector，未执行跨进程/并发幂等和生产证据存储验证；这些属于后续 connector/E2E 工单。机器身份和访问授权仍由未确认的 #151 处理。当前环境未安装第三方 JSON Schema/OpenAPI 校验器，已用受控关键词的依赖零契约测试验证全部样例、条件分支和引用。 ### 文档影响 协议冻结会影响长期 Product-Requirements、Architecture、Business-Rules 和验证 Wiki。按三份并行契约工单的协调约定，本工单不并发修改 Wiki/`docs/**`，由根协调 agent 在 #148–#150 汇总后串行更新、回读并同步镜像；未创建任务归档。
ila commented 2026-08-31 08:57:52 +08:00
Author
Owner
Copy Link
Copy Source

联合检查修订证据（2026-08-31）

联合检查发现首版提交把证据成功态写成 available，与 #150 验收措辞及 Sense 既有 pending/success/failed 边界不一致，会给 mapper 引入无必要转换。现已在原范围内统一修订：

  • evidence v1 状态枚举改为 pending | processing | success | failed；
  • success 严格要求 content_type 和 integrity；
  • failed、pending、processing 的互斥约束保持不变；
  • Schema、README、Event 兼容说明、OpenAPI 描述、success/敏感字段 fixture 和测试已同步；
  • 新增测试明确拒绝遗留 available，并分别验证 success 缺少 content_type 或 integrity 时失败。

追加提交：359c553，已推送到 PR #158。

重新验证：events 7/7、evidence 4/4、仓库 48/48、DevHarness strict、git diff --check 和暂存差异检查均通过。工单继续保持待验收，PR 未合并，工单未关闭。

## 联合检查修订证据（2026-08-31） 联合检查发现首版提交把证据成功态写成 `available`，与 #150 验收措辞及 Sense 既有 `pending/success/failed` 边界不一致，会给 mapper 引入无必要转换。现已在原范围内统一修订： - evidence v1 状态枚举改为 `pending | processing | success | failed`； - `success` 严格要求 `content_type` 和 `integrity`； - `failed`、`pending`、`processing` 的互斥约束保持不变； - Schema、README、Event 兼容说明、OpenAPI 描述、success/敏感字段 fixture 和测试已同步； - 新增测试明确拒绝遗留 `available`，并分别验证 `success` 缺少 `content_type` 或 `integrity` 时失败。 追加提交：`359c553`，已推送到 PR #158。 重新验证：events 7/7、evidence 4/4、仓库 48/48、DevHarness strict、`git diff --check` 和暂存差异检查均通过。工单继续保持待验收，PR 未合并，工单未关闭。
ila commented 2026-08-31 09:01:50 +08:00
Author
Owner
Copy Link
Copy Source

根协调联合复核（2026-08-31）

将 #148、#149、#150 的最终提交按完整提交链临时叠加到同一隔离 review worktree 后复核，未合并或推送 review 分支。

  • 公共命名统一为 snake_case，版本标识分别为 yovision.source-config/v1、yovision.runtime-status/v1、yovision.event/v1、yovision.evidence-reference/v1。
  • #149 已按 #148 的 config_id + integer revision 改为多配置流 configurations[]，不存在单一 revision 歧义。
  • #150 证据成功态已与确认设计统一为 success，保留 processing 中间态；旧 available 被测试拒绝。
  • 联合测试：#148 11/11、#149 14/14、events 7/7、evidence 4/4、仓库 48/48 全部通过。
  • 全部 42 个 JSON 文件可解析；DevHarness strict、git diff --check 通过；旧命名标记扫描为 0。
  • 三个 PR 均 open、mergeable、目标为 dev，尚未合并。
  • 长期 Wiki/核心镜像将在用户验收并确定协议冻结提交后由单一协调写入者串行处理，避免三个并行工单争用共享文档；当前未创建任务归档。

#150 最终 PR：#158，head 359c553452e0b91a532e07af8c9108e3436eb7bb。

## 根协调联合复核（2026-08-31） 将 #148、#149、#150 的最终提交按完整提交链临时叠加到同一隔离 review worktree 后复核，未合并或推送 review 分支。 - 公共命名统一为 snake_case，版本标识分别为 `yovision.source-config/v1`、`yovision.runtime-status/v1`、`yovision.event/v1`、`yovision.evidence-reference/v1`。 - #149 已按 #148 的 `config_id + integer revision` 改为多配置流 `configurations[]`，不存在单一 revision 歧义。 - #150 证据成功态已与确认设计统一为 `success`，保留 `processing` 中间态；旧 `available` 被测试拒绝。 - 联合测试：#148 11/11、#149 14/14、events 7/7、evidence 4/4、仓库 48/48 全部通过。 - 全部 42 个 JSON 文件可解析；DevHarness strict、`git diff --check` 通过；旧命名标记扫描为 0。 - 三个 PR 均 open、mergeable、目标为 `dev`，尚未合并。 - 长期 Wiki/核心镜像将在用户验收并确定协议冻结提交后由单一协调写入者串行处理，避免三个并行工单争用共享文档；当前未创建任务归档。 #150 最终 PR：#158，head `359c553452e0b91a532e07af8c9108e3436eb7bb`。
ila commented 2026-08-31 10:05:36 +08:00
Author
Owner
Copy Link
Copy Source

用户验收通过（2026-08-31 10:05 +08:00）

用户明确回复：#150通过。

合并与验证证据

  • 实现提交：359c553452e0b91a532e07af8c9108e3436eb7bb
  • 实现 PR：#158，已合并到 dev
  • 实现合并提交：23a85278cb882f417a91e85c312b701b8e32e470
  • 事件契约测试：7/7 通过
  • 证据契约测试：4/4 通过
  • 仓库测试：48/48 通过
  • python dev_scripts/harness.py check --strict：通过
  • git diff --check：通过

长期文档

已更新并在线回读：

  • Product-Requirements：c9970b0ee8b677b6be13f31af67b3206a3faf956
  • Architecture-and-Code-Map：812e822990d8c8e82445bd19ced67aca8c10aba4
  • Business-Rules-and-Glossary：bc4a1a7be268028fa85717b71f48f7dd75cc7e52
  • Local-Development-and-Verification：d11757b202117e028878802e1e8a9ba9df1a8e89

核心镜像提交：b548b05874788342d95aa307b21bf57f8df386b5；PR #161 已合并，合并提交：573113eb3b12567bb0de1b85f0ffa07bc85db1bf。镜像一致性检查通过。

边界

#153 产品 mapper/relay/ingress 和 #151 机器身份尚未实施；#151 仍为高风险安全设计，需单独人工确认。本次未创建任务归档。

## 用户验收通过（2026-08-31 10:05 +08:00） 用户明确回复：`#150通过`。 ### 合并与验证证据 - 实现提交：`359c553452e0b91a532e07af8c9108e3436eb7bb` - 实现 PR：#158，已合并到 `dev` - 实现合并提交：`23a85278cb882f417a91e85c312b701b8e32e470` - 事件契约测试：7/7 通过 - 证据契约测试：4/4 通过 - 仓库测试：48/48 通过 - `python dev_scripts/harness.py check --strict`：通过 - `git diff --check`：通过 ### 长期文档 已更新并在线回读： - Product-Requirements：`c9970b0ee8b677b6be13f31af67b3206a3faf956` - Architecture-and-Code-Map：`812e822990d8c8e82445bd19ced67aca8c10aba4` - Business-Rules-and-Glossary：`bc4a1a7be268028fa85717b71f48f7dd75cc7e52` - Local-Development-and-Verification：`d11757b202117e028878802e1e8a9ba9df1a8e89` 核心镜像提交：`b548b05874788342d95aa307b21bf57f8df386b5`；PR #161 已合并，合并提交：`573113eb3b12567bb0de1b85f0ffa07bc85db1bf`。镜像一致性检查通过。 ### 边界 #153 产品 mapper/relay/ingress 和 #151 机器身份尚未实施；#151 仍为高风险安全设计，需单独人工确认。本次未创建任务归档。
ila closed this issue 2026-08-31 10:05:36 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/ux
UI/UX 与交互原型
 kind/epic
长期产品目标
 kind/mvp
可独立验收的最小版本
 kind/task
单元实施任务
 priority/p0
首个纵切必需能力
 project/bell
Bell 项目
 project/brain
Brain 项目
 project/sense
Sense 项目
 scope/coordination
跨项目协调任务
 scope/independent
不依赖其他项目在线的项目内任务
No labels kind/task priority/p0 project/bell project/brain project/sense scope/coordination
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ila/yovision#150