diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md new file mode 100644 index 0000000..49853a1 --- /dev/null +++ b/docs/00-project-profile.md @@ -0,0 +1,80 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Project-Profile +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Project-Profile.- +wiki_revision: 4a78dc8673d88b05f1c62b254242180a68465ccd +synchronized_at: 2026-08-11T10:30:26Z + + +# 项目档案 + +## 基本信息 + +| 项目 | 内容 | +|---|---| +| 名称 | YoVision | +| 仓库 | `ila/yovision` | +| 默认分支 | `main` | +| 一句话目标 | 将现有视频设备升级为能够自动形成异常证据并把预警追到人确认处置的安全基础设施 | +| 首期客户场景 | 民办寄宿学校，默认 16 路高风险点位 | +| 首期规则 | 越线、危险区域、聚集等匿名安全规则；不启用人脸 | +| 产品形态 | Sense 与 Bell 两个独立销售产品，Brain 为独立推理交付单元 | +| 当前阶段 | 新仓库文档与开发流程初始化，业务代码尚未迁移 | +| 历史来源 | `D:\OPC\yovision_old`，只读追溯 | + +## 子项目与交付单元 + +| 单元 | 职责 | 技术栈目标 | 独立构建/测试/发布 | 规则入口 | 共享边界 | +|---|---|---|---|---|---| +| Sense | ONVIF/RTSP、设备台账、MediaMTX、实时监看、区域配置、运维与 Outbox | Go；Vue 3 + Element Plus；PostgreSQL | 是；可在没有 Bell 时独立运行 | `Sense/AGENTS.md` | 通过版本化源/事件/证据契约与 Brain、Bell 集成 | +| Brain | 解码、检测、姿态、跟踪、ReID、区域判定、事件 mapper | Python/CUDA | 是；无界面，默认随 Sense 交付 | `Brain/AGENTS.md` | 只消费媒体/配置契约并输出标准事件 | +| Bell | 外部事件接入、规则、Alert、ack/close、联系人、排班、升级、通知、审计 | Go；Vue 3 + Element Plus；PostgreSQL | 是；可用合成或第三方事件独立验收 | `Bell/AGENTS.md` | 发布事件接入与证据接口，不读取 Sense 内部状态 | +| contracts | 三端共享的 OpenAPI、JSON Schema、SQL 契约和兼容说明 | 版本化文档与契约测试 | 随受影响项目验证 | `contracts/AGENTS.md` | 唯一共享事实来源，不承载业务代码 | + +三个项目允许不同版本和发布节奏。技术栈不同不是拆仓理由；若未来团队权限、发布责任或仓库性能长期分离，再以独立工单评估拆仓。 + +## 技术栈与运行环境 + +- Sense/Bell：目标采用固定上游版本的 GoAdmin server 与 go-admin-ui，首阶段保持 Vue 3 + Element Plus + Vue CLI，不同时迁移 TypeScript/Vite。 +- Brain：Python、CUDA/NVIDIA 主路径；模型许可必须在商用前确认。 +- 正式数据库：PostgreSQL；Sense 与 Bell 使用独立数据库角色和数据边界。 +- 媒体：MediaMTX 独立二进制，由 Sense 管理配置和生命周期。 +- 证据：客户侧 MinIO/S3 兼容对象存储；常态录像优先留在客户已有 NVR。 +- 首期验证平台：NVIDIA x86/Jetson；M1-M3 不承诺 GB/T 28181、信创或原生 App。 + +业务代码尚未初始化，具体 Go/Python/Node 版本必须在对应骨架工单中冻结后更新本页。 + +## 阅读入口 + +- 新维护者：Home → Product-Requirements → Architecture-and-Code-Map。 +- Sense agent：根 `AGENTS.md` → `Sense/AGENTS.md` → 当前工单。 +- Brain agent：根 `AGENTS.md` → `Brain/AGENTS.md` → 事件契约 → 当前工单。 +- Bell agent：根 `AGENTS.md` → `Bell/AGENTS.md` → 当前工单。 +- 协调 agent：Multi-Agent-Collaboration → `contracts/AGENTS.md` → 所有受影响工单。 + +## 常用命令 + +当前初始化阶段可执行： + +```powershell +python dev_scripts/check_harness.py --strict +python -m unittest discover -s tests -v +python dev_scripts/sync_wiki_docs.py --check +git diff --check +``` + +Sense、Brain、Bell 的构建、运行和测试命令尚待各自骨架工单建立，不以旧仓库命令冒充新仓库事实。 + +## 环境、配置与凭据 + +- Gitea 凭据仅通过 MCP 安全配置或进程环境提供。 +- 摄像头密码、JWT secret、数据库连接、对象存储和通知供应商凭据不得提交。 +- Sense 与 Bell 必须使用不同用户库、JWT/会话密钥、Cookie、Casbin 策略和数据库角色。 +- Brain 不接收交互式用户会话；机器身份按调用方和实例独立分配。 +- `.env.example` 只能放变量名和无敏感示例，不放真实地址、客户名或 token。 + +## 负责人确认的边界 + +- 单仓包含 Sense、Brain、Bell 三个开发项目。 +- 计划由三名主 agent 尽量并行处理各自独立工单；需要跨项目协作时再建立协调工单并启用新 agent。 +- 旧仓库在新纵切验收前保留，不删除、不覆盖。 diff --git a/docs/01-workflow.md b/docs/01-workflow.md new file mode 100644 index 0000000..6fd51b9 --- /dev/null +++ b/docs/01-workflow.md @@ -0,0 +1,240 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Development-Workflow +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Development-Workflow.- +wiki_revision: 5bb7c174f711aa5655cb8c9b28afed7cfacd60d5 +synchronized_at: 2026-08-11T10:30:31Z + + +# 开发工作流 + +## 事实来源边界 + +- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。 +- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。 +- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。 +- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。 + +## 一次任务怎样完成 + +### 1. 讨论 + +用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。 + +### 2. 建单 + +方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。 + +新产品或较大版本先建立 Epic，再建立 MVP： + +```text +[Epic] 产品或长期目标 +└── [MVP] 第一个可交付版本 + ├── #101 单元任务 + ├── #102 单元任务 + └── #103 单元任务 +``` + +每个单元任务都应目标单一，能够独立测试、提交和回退。 + +#### 依赖与并行 + +建立新工单不要求其他工单已经完成，也不按工单编号限制实施顺序。每个单元任务必须声明： + +- 前置工单，没有时填写“无”； +- 是否允许与未完成的前置工单并行； +- 判断可以或不可以并行的原因。 + +开始修改前，Agent 检查工单声明的前置工单： + +- 没有前置工单，或前置工单已经完成，可以进入“进行中”； +- 前置工单未完成且存在实际依赖时，不得开始实施，工单保持“待实施”； +- 与前置工单没有实施冲突、允许并行时，可以进入“进行中”，但必须在工单写明原因； +- 已经进入实施后出现计划外、当前无法解除的问题，才使用“阻塞”。 + +依赖不改变单元任务边界。依赖满足后，该任务仍须拥有独立的范围、提交、测试和回退方式。 + +### 3. 实施 + +Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。 + +重要进度及时写回工单： + +- 已确认的根因； +- 方案或范围变化； +- 测试结果； +- 阻塞和未验证内容； +- Git 提交哈希； +- 相关 Wiki 页面及 revision。 + +长期文档遵循唯一顺序： + +```text +修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像 +``` + +不得先编辑 `docs/` 再反向覆盖 Wiki。 + +### 4. 待验收 + +实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。 + +### 5. 归档和关闭 + +使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像： + +```powershell +python dev_scripts/new_task_archive.py 123 "修复登录超时" +``` + +归档内容以 Wiki 页面为主源；本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。 + +## 文档同步规则 + +- 映射保存在 `wiki-docs.json`，每个 Wiki 页面对应唯一仓库路径。 +- 同步脚本只实现 Wiki → `docs/`，不提供反向同步。 +- 镜像头必须记录页面名、页面地址、revision 和同步时间。 +- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。 +- `--check` 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。 +- 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。 +- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。 +- 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。 + +## 面向初级维护者的修改边界 + +| 风险 | 示例 | 处理方式 | +|---|---|---| +| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 | +| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 | +| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | + +风险由影响范围决定，不按代码行数判断。 + +## 每个任务的文档影响 + +单元任务必须明确选择： + +- 不影响长期文档，并说明原因； +- 更新项目档案或运行验证； +- 更新架构与代码地图； +- 更新业务规则与术语； +- 更新常见修改或故障排查； +- 新增或调整其他 Wiki 页面。 + +以下变化必须更新相关 Wiki： + +- 启动、测试、部署或排错命令变化； +- 模块入口、目录职责或主要调用路径变化； +- 配置项、API、数据结构或状态变化； +- 业务规则、安全边界或权限变化； +- 日志位置、错误定位或常见处理方式变化。 + +普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。 + +## 需求记录与流转 + +聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录： + +- 原始需求的来源和提出时间； +- 能表达用户目的、使用场景和限制的少量关键原话； +- 整理后的目标、非目标、确认方案、验收标准和文档影响； +- 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。 + +只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 + +需求按以下边界流转： + +| 内容 | 事实来源 | 本地镜像 | +|---|---|---| +| 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | +| 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | +| 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | +| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | `docs/task/` | + +任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。 + +## 稳定文档与任务归档 + +- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 +- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。 +- 新人先读稳定主题页，只有追查历史原因时才读任务归档。 +- 任务产生的长期结论必须合并到主题页，不能只留在归档。 + +## 效率与范围控制 + +本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 + +### 严格控制范围 + +- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。 +- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。 +- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。 +- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。 + +### 渐进执行和修复 + +- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。 +- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。 +- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。 +- 不在真实证据出现前堆叠与已知风险无关的预防性检查。 +- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。 + +### 复用已验证事实 + +- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。 +- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。 +- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。 +- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。 + +### 明确停止条件 + +- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。 +- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。 +- 未影响当前验收的相邻问题只提示或建单，不顺手处理。 + +## 自然语言快捷指令 + +快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。 + +| 指令 | 执行动作 | 停止位置 | +|---|---|---| +| `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 | +| `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 | +| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” | +| `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” | +| `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 | +| `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 | +| `同步文档` | 读取 Wiki，导出已映射的 `docs/` 镜像并检查一致性 | 显示结果和差异；不修改 Wiki、不自动提交 | +| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，导出并提交镜像，推送、同步父工单并关闭任务 | 工单“已完成”并关闭 | + +补充边界： + +- 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。 +- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。 +- `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。 +- `同步文档` 发现镜像有未提交改动时停止，不覆盖现有修改。 +- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存 Wiki 最终任务归档的镜像。 + +## 什么时候重新确认方案 + +以下变化必须先更新工单，再由用户确认： + +- 交付结果或用户操作发生变化； +- 增加或删除接口、数据库字段或迁移； +- 安全边界、权限或不可逆操作发生变化； +- 原方案不可行，需要更换主要技术路线； +- 任务范围明显扩大； +- Wiki 页面删除、重命名或事实源边界改变。 + +普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。 + +## 工单、Wiki 与 Git 分别写什么 + +| 信息 | Gitea 工单 | Gitea Wiki | Git / `docs` 镜像 | +|---|---:|---:|---:| +| 讨论过程和临时方案 | 是 | 否 | 否 | +| 实施进度和阻塞 | 是 | 否 | 否 | +| 长期有效的最终方案 | 链接 | 是 | 镜像 | +| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 | +| 提交哈希 | 是 | 任务归档 | 镜像 | +| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md new file mode 100644 index 0000000..c17bb8c --- /dev/null +++ b/docs/02-architecture-and-code-map.md @@ -0,0 +1,81 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Architecture-and-Code-Map +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.- +wiki_revision: 04b5eaea579729e427f1b2b8962399e861d5eb53 +synchronized_at: 2026-08-11T10:30:34Z + + +# 架构与代码地图 + +## 项目定位 + +YoVision 采用单仓三项目、两个销售产品的结构。单仓用于保持共享契约和端到端验证一致，不代表共享认证、数据库或发布生命周期。 + +```text +摄像头 / RTSP / ONVIF + │ + v +Sense（设备、媒体、区域、运维） + │ 版本化媒体/配置契约 + v +Brain（推理、跟踪、区域判定、事件 mapper） + │ 标准事件契约 + v +Bell（事件入站、规则、Alert、ack/close、升级、通知） +``` + +Bell 也可接收合成事件、传感器平台或第三方系统事件；Sense 与 Brain 不得成为 Bell 的启动依赖。Sense 未配置 Bell 时仍可完成设备接入、实时监看、区域配置、运维和本地事件查看。 + +## 代码地图 + +| 能力 | 路径 | 首个阅读入口 | 验证位置 | 风险 | +|---|---|---|---|---| +| Sense 产品 | `Sense/` | `Sense/AGENTS.md`；后续 README/入口 | `Sense/` 内测试 | 高：设备、媒体、凭据、并发对账 | +| Brain 推理 | `Brain/` | `Brain/AGENTS.md`；后续包入口 | `Brain/` 内测试与契约测试 | 高：模型、GPU、隐私、事件语义 | +| Bell 产品 | `Bell/` | `Bell/AGENTS.md`；后续 README/入口 | `Bell/` 内测试 | 高：认证、事件、告警状态机、通知 | +| 共享契约 | `contracts/` | `contracts/AGENTS.md` | 三端消费者/生产者测试 | 高：兼容性与跨项目影响 | +| Harness | `dev_scripts/` | `check_harness.py` | `tests/` | 中 | +| 工单模板 | `.gitea/issue_template/` | `task.md` | Harness 严格检查 | 中 | +| Wiki 镜像 | `docs/` | `docs/README.md` | `sync_wiki_docs.py --check` | 低；禁止直接编辑 | + +业务代码尚未迁入；具体函数、路由和测试入口必须随各项目骨架工单更新，不复制旧仓库代码地图。 + +## 两条主要执行路径 + +### 独立产品路径 + +```text +Sense：独立登录 → 添加摄像头 → ONVIF/RTSP 验证 → 实时画面 → 绘制区域 + +Bell：独立登录 → 接收合成/第三方事件 → 规则匹配 → Alert → ack → close +``` + +### 可选集成路径 + +```text +Sense/Brain 生成事件 +→ Sense 持久 Outbox 或 Brain 可靠投递 +→ Bell 版本化事件 API +→ (producer_id, source_event_id) 幂等入站 +→ Rule → Alert → Delivery/Escalation → ack/close +``` + +集成断开不得阻断任一产品核心能力；恢复后按 Outbox 和幂等收据继续。 + +## 数据与安全边界 + +- Sense 与 Bell 拥有独立账户、会话、RBAC、审计、数据库角色和备份恢复。 +- Brain 业务无状态，不持有用户、Alert 或通知真相。 +- 产品间不做跨库 SQL，不共享 JWT/Cookie，不发送摄像头凭据或内部文件路径。 +- `contracts/` 是跨项目字段与语义唯一事实来源；发布契约不可原地破坏。 +- MediaMTX 是数据面独立进程；GoAdmin/GORM 只承担管理面和普通 CRUD。 + +## 不可破坏的边界 + +- 16 是默认配额，不是数组、数据库、分页或循环硬上限。 +- Event 与 Alert 分离；Event 不可变，状态变化与处置结果只追加。 +- 模型输出观测，规则作业务判定；模型升级不能暗改事件语义。 +- 业务预警与运维告警分开。 +- Area/设备/规则在各独立产品内有自己的业务投影，不以共享数据库同步。 +- 单项目工单不得顺带修改其他项目；共享契约变更必须由协调工单统筹。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md new file mode 100644 index 0000000..26d6cd2 --- /dev/null +++ b/docs/03-business-rules-and-glossary.md @@ -0,0 +1,68 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Business-Rules-and-Glossary +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.- +wiki_revision: 7a9645a7ca7f4b3478d27afb2d441238431f501e +synchronized_at: 2026-08-11T10:30:38Z + + +# 业务规则与术语 + +## 核心术语 + +| 术语 | 定义 | +|---|---| +| Sense | 独立销售的视频接入、媒体、区域配置和运维产品 | +| Brain | 无界面的推理交付单元，输出观测和标准事件 | +| Bell | 独立销售的事件预警与处置产品 | +| Device | 设备根实体；通过 modality/capabilities 表达视频、雷达、门磁等能力 | +| Site | 一个客户部署中的站点边界 | +| Area | 多边形区域、警戒线及其隐私/准入策略 | +| Event | 已发生的不可变结构化事实及证据引用 | +| Alert | Bell 根据一个或多个 Event 和规则创建的处置对象 | +| ack | 明确由某人接手 Alert，不等同于消息已送达或已看到 | +| Outbox | 与本地状态同事务持久化、可重试投递的消息队列记录 | +| producer identity | Bell 为每个外部产品实例分配的机器身份 | +| 场景包 | 规则模板、升级策略、话术和报表口径的版本化配置包 | + +## 工单状态 + +- 待确认：需求或方案等待负责人确认。 +- 待实施：方案已确认，但依赖或排期尚未满足。 +- 进行中：主 agent 正在工单声明的写路径内实施。 +- 阻塞：出现计划外且当前无法解除的问题。 +- 待验收：实现、测试和文档证据完成，等待负责人验收。 +- 已完成：负责人明确验收并完成归档、关闭。 + +旧仓库任务的 DONE 不继承到新仓库。所有迁移项初始均为“待迁移”，必须用新代码、新测试和新验收重新证明。 + +## 稳定业务规则 + +1. Sense 与 Bell 完全独立认证；同一自然人在两个产品中是两个账户。 +2. 任一产品可独立部署、升级、备份、恢复和验收，另一产品不作为启动依赖。 +3. Brain 不拥有用户、Alert、通知或业务审计真相。 +4. 产品集成使用机器身份和版本化契约，不共享数据库、用户会话或内部模型。 +5. Bell 以 `(producer_id, source_event_id)` 保持跨重启幂等。 +6. Event 不可变；误报只追加 outcome/反馈，不改写原始事实。 +7. `sent`、`delivered`、`seen`、`ack` 是不同事实；无回执不能当成功。 +8. 未 ack 自动升级且进程重启后续跑；并发 ack 只有首个成功者成为处置人。 +9. 联系人、排班和升级策略共享主数据但分对象、分版本；投递创建时固化实际收件人、通道和解析版本。 +10. 静默必须限时并自动恢复，单次不超过 4 小时。 +11. 默认 16 路，按 32/64/128 横向扩展；128 路不等于单机或单 GPU 承诺。 +12. 首期 S2 民办寄宿学校只做匿名规则，不启用人脸。 +13. 家庭卧室、卫生间禁止摄像头，只能使用非成像传感器。 +14. 摄像头凭据、客户数据、真实视频、JWT secret 和生产配置不得进入仓库、工单或 Wiki。 +15. 业务预警与设备/媒体/推理运维告警使用不同通道和责任人。 + +## 新项目需要补充什么 + +以下事实必须由后续工单和负责人确认后补充： + +- GoAdmin/go-admin-ui 的固定上游 commit、许可证记录和裁剪模块； +- Go、Node、Python、CUDA、PostgreSQL、MediaMTX 的精确版本； +- Sense/Bell 数据库 schema、Cookie 名称、部署域名和备份命令； +- Brain 模型、推理 FPS、硬件容量和商用许可； +- 试点最终留存期、通知供应商和验收阈值； +- 三个交付单元的正式版本与发布流程。 + +未确认项不得从旧代码或模板默认值推断为当前事实。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md new file mode 100644 index 0000000..9bbd0de --- /dev/null +++ b/docs/04-local-development-and-verification.md @@ -0,0 +1,90 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Local-Development-and-Verification +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.- +wiki_revision: be0864a5bdbe06bd8358f2d013aa7313ab13e73b +synchronized_at: 2026-08-11T10:30:41Z + + +# 本地开发与验证 + +## 环境要求 + +| 工具 | 当前用途 | 检查命令 | +|---|---|---| +| Git | 版本和工作区保护 | `git --version` | +| Python 3 | Harness 脚本和测试 | `python --version` | +| Gitea | 工单与 Wiki | 浏览仓库或调用 MCP | +| Gitea PAT | Wiki 写入 | 仅由 MCP 或 `GITEA_TOKEN` 提供，不打印 | + +Go、Node、CUDA、PostgreSQL、MediaMTX 的精确要求将在对应项目骨架工单冻结；当前不把旧仓库环境当作新项目事实。 + +## 第一次运行 + +1. 检查工作区： + + ```powershell + git status --short --branch + ``` + + 预期：显示 `main` 和本任务创建的引导文件，没有来源不明改动。 + +2. 检查 Harness： + + ```powershell + python dev_scripts/check_harness.py --strict + ``` + + 预期：输出“DevHarness 检查通过”。 + +3. 运行 Harness 测试： + + ```powershell + python -m unittest discover -s tests -v + ``` + + 预期：全部测试为 `ok`。 + +4. 对照 Wiki： + + ```powershell + python dev_scripts/sync_wiki_docs.py --check + ``` + + 预期：全部映射一致。 + +## 子项目命令状态 + +| 项目 | 构建 | 测试 | 运行 | 当前状态 | +|---|---|---|---|---| +| Sense | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 | +| Brain | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 | +| Bell | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 | + +不得复制旧仓库命令来填空。每个骨架工单必须同时建立 README、可复制命令和最小测试。 + +## 常用调试方式 + +- Harness 语法：`python -m compileall -q dev_scripts tests`。 +- 单测：`python -m unittest tests.test_harness_docs -v`。 +- 查看差异：`git diff --check`、`git diff`。 +- 查看 Wiki 配置：只查看 `wiki-docs.json`，不得打印 token。 +- 跨项目问题先验证契约，再分别验证生产者和消费者，不直接修改两端猜测修复。 + +## 测试数据与日志 + +- 只使用合成或脱敏事件、合成 RTSP 和明确授权的实验室设备。 +- 不提交真实视频、客户名称、地址、手机号、摄像头密码或通知凭据。 +- 日志必须可按 request/event/alert ID 追踪，但不得记录 Authorization、Cookie 或连接密钥。 + +## 完成修改前 + +```powershell +python -m unittest discover -s tests -v +python dev_scripts/check_harness.py --strict +python dev_scripts/sync_wiki_docs.py --check +git diff --check +git status --short +``` + +业务工单还必须运行其声明的子项目测试；跨契约工单必须运行所有受影响项目的契约测试。未执行部分写入工单。 diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md new file mode 100644 index 0000000..4f010b7 --- /dev/null +++ b/docs/05-common-changes.md @@ -0,0 +1,78 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Common-Changes +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Common-Changes.- +wiki_revision: edfcd6dd2cd254d31e88e980558e467b5fe758a3 +synchronized_at: 2026-08-11T10:30:43Z + + +# 常见修改指南 + +## 本页用途 + +帮助初级程序员在 Claude/Codex Agent 协助下处理简单 Bug 和小需求。这里说明常见入口、验证方法和停止条件，不代替工单和方案确认。 + +## 风险分级 + +| 等级 | 常见修改 | 处理方式 | +|---|---|---| +| 低风险 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下修改和验证 | +| 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 | +| 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | + +“代码行数少”不等于低风险。 + +## 修改 Wiki 文案 + +1. 在相关工单确认目标。 +2. 读取线上 Wiki 页面和当前 revision。 +3. 修改线上 Wiki，不直接编辑 `docs/`。 +4. 运行 `python dev_scripts/sync_wiki_docs.py`。 +5. 运行 `python dev_scripts/sync_wiki_docs.py --check`。 +6. 审查本地镜像差异并提交。 + +停止条件：页面需要删除、重命名或改变事实源边界。 + +## 增加工单字段 + +1. 阅读 `.gitea/issue_template/task.md` 和 Development-Workflow。 +2. 判断字段是否影响所有任务，避免只为一个任务增加永久字段。 +3. 修改模板和对应流程说明。 +4. 为 Harness 检查增加或调整测试。 +5. 创建一份示例工单草稿检查可读性。 + +停止条件：字段改变权限、审批或关闭条件。 + +## 调整 Harness 检查 + +1. 从 `dev_scripts/check_harness.py` 的 `main()` 开始读。 +2. 新检查应输出具体文件和缺失内容。 +3. 检查结构事实，不声称自动判断文档语义质量。 +4. 在 `tests/` 添加成功和失败用例。 +5. 运行严格检查及全部测试。 + +停止条件：检查会删除、重写文件或依赖生产环境。 + +## 修复 Wiki 同步 Bug + +1. 从 `dev_scripts/wiki_docs.py` 的 `WikiClient`、`parse_mirror` 和 `sync_all` 开始读。 +2. 先编写能复现问题的测试。 +3. 保持 Wiki → docs 单向关系。 +4. 验证中文、路径编码、revision 和脏文件保护。 +5. 使用测试页面验证时，不删除正式页面。 + +停止条件：需要自动删除/重命名页面、覆盖本地未提交修改或输出令牌。 + +## 看懂 Agent 的修改 + +审查时至少回答： + +- 这次解决了哪个工单目标； +- 修改入口和调用路径在哪里； +- 有哪些行为变化； +- 增加或修改了哪些测试； +- 哪些内容没有验证； +- 是否更新了受影响的 Wiki 页面； +- 怎样回退。 + +回答不了时，让 Agent补充说明，不要仅凭“测试通过”验收。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md new file mode 100644 index 0000000..f675362 --- /dev/null +++ b/docs/06-troubleshooting.md @@ -0,0 +1,41 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Troubleshooting +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting +wiki_revision: 632e07b6cd22f6e3ae07c23ed58439ea2beecff2 +synchronized_at: 2026-08-11T10:30:46Z + + +# 故障排查 + +## 常见问题 + +| 现象 | 常见原因 | 检查 | 处理 | +|---|---|---|---| +| 三个 agent 修改同一文件 | 工单写路径重叠或共享契约未设协调任务 | 查看工单“子项目影响”和 `git status` | 停止写入，由协调 agent 重排范围 | +| 一端测试通过、集成失败 | 契约副本漂移或兼容语义不一致 | 对照 `contracts/` 与三端契约测试 | 以契约事实源修复，不复制第二份 schema | +| Sense 依赖 Bell 才能启动 | 把可选 connector 写成强依赖 | 在 Bell 停止时启动 Sense | 改为 Outbox/可选配置，暴露降级状态 | +| Bell 接受 Sense 用户 token | 认证边界被混用 | 检查 issuer、audience、Cookie 和用户表 | 立即停止，恢复独立认证与机器身份 | +| `--strict` 缺页面或章节 | Wiki 未创建/未同步或模板结构损坏 | 查看 `wiki-docs.json` 与 Wiki | 先修 Wiki，读取确认后重新同步 | +| Wiki 同步提示本地脏镜像 | 直接编辑了 `docs/` | `git status --short -- docs` | 保留内容，先更新 Wiki；不要强制覆盖 | +| Gitea 401/403 | token 属于其他实例、过期或权限不足 | 不打印 token；验证目标 URL | 写操作停止，修复安全配置 | +| env 无法解析 | 使用 `KEY:VALUE` 而非 `KEY=VALUE` | 只检查键名和格式 | 改为标准 env 格式，不输出值 | + +## 排查顺序 + +1. 停止继续修改并读取完整错误。 +2. 核对当前工单、主 agent、子项目和允许写路径。 +3. 确认问题属于单项目、共享契约还是环境。 +4. 用最小命令复现，先处理第一个可行动错误。 +5. 契约问题先检查唯一事实来源，再检查生产者和消费者。 +6. 修复后运行受影响测试和 Wiki 一致性检查。 +7. 无法验证的部分写回工单。 + +## 必须停止的情况 + +- 凭据、真实视频、个人信息或生产数据可能泄露； +- 需要共享 Sense/Bell 用户、JWT、Cookie、数据库或摄像头密码； +- 多个 agent 写路径重叠且无法证明单写入者； +- 契约破坏性变化没有新版本、迁移和回退方案； +- 涉及删除、不可逆迁移、发布或生产变更但没有明确授权； +- 工作区出现来源不明且与当前任务重叠的修改。 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md new file mode 100644 index 0000000..a34ece9 --- /dev/null +++ b/docs/07-new-project-documentation-setup.md @@ -0,0 +1,133 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: New-Project-Documentation-Setup +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/New-Project-Documentation-Setup.- +wiki_revision: 8ac3aaf5a1cc5479f2a37a07fec6510b6dcc9cab +synchronized_at: 2026-08-11T10:30:50Z + + +# 新项目文档初始化 + +## 本页用途 + +从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。 + +## 初始化顺序 + +### 1. 建立项目边界 + +由项目负责人确认： + +- 项目名称和一句话目标； +- 用户和主要使用场景； +- 技术栈和支持环境； +- Gitea 仓库、默认分支和维护者； +- 安全、权限、数据和发布红线。 + +把项目专用红线写入根目录或子目录 `AGENTS.md`。 + +### 2. 识别子项目与交付单元 + +先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认： + +- 职责和目录边界； +- 技术栈、依赖和支持环境； +- 构建、测试和运行命令； +- 是否拥有独立版本号和发布方式； +- 适用的根目录或子目录 `AGENTS.md`； +- 与其他子项目共享的接口、数据或业务流程； +- 共享契约的唯一事实来源和兼容要求。 + +把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。 + +### 3. 建立 Gitea + +创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。 + +### 4. 修改镜像配置 + +把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；核心主题映射保留。 + +确认当前目录确实是新项目副本、且 DevHarness 历史归档不需要保留后，移除属于 DevHarness 的任务归档映射和对应 `docs/task/` 镜像。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。 + +不要把 PAT 写入配置。 + +### 5. Agent 检查项目事实 + +Agent 只读检查： + +- README、配置和依赖文件； +- 启动入口； +- 主要模块和目录规则； +- 测试、格式和静态检查命令； +- 日志、示例配置和测试数据； +- 已存在的接口、数据模型和状态。 + +区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。 + +### 6. 确定交付对象和文档 + +由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定： + +- 需要完成的工作； +- 所需文档类型； +- 文档可见范围； +- 适用版本、负责人和验证人； +- 不得对外披露的内部信息。 + +按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。 + +### 7. 先创建线上 Wiki + +至少创建或填写： + +1. Home； +2. Project-Profile； +3. Architecture-and-Code-Map； +4. Business-Rules-and-Glossary； +5. Local-Development-and-Verification； +6. Common-Changes； +7. Troubleshooting； +8. Development-Workflow； +9. Delivery-Documentation-Guide； +10. Audience-Document-Template； +11. Task-Archive-Template。 + +Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。 + +### 8. 人工确认 + +项目负责人至少确认： + +- 一句话目标和业务术语； +- 关键业务规则和状态； +- 权限、安全和数据边界； +- 真实运行、测试和部署命令； +- 哪些修改属于高风险； +- 交付对象、文档可见范围和外部信息边界。 + +### 9. 导出镜像并检查 + +```powershell +python dev_scripts/sync_wiki_docs.py +python dev_scripts/check_harness.py --strict +python dev_scripts/sync_wiki_docs.py --check +python -m unittest discover -s tests -v +``` + +只有线上 Wiki 确认后才导出 `docs/`。旧项目的任务归档不能带入新项目历史。 + +## 完成标准 + +初级程序员应能仅依靠 Home 和链接页面回答： + +- 项目解决什么问题； +- 怎样启动和运行测试； +- 常用功能从哪个目录和入口开始读； +- 一个简单修改通常要改哪里、验证什么； +- 哪些情况必须停止并交给 Agent 或负责人； +- 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布； +- 跨子项目共享什么接口或契约，其唯一事实来源在哪里； +- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。 + +回答不了的问题应继续补充主题文档，而不是堆入任务归档。 diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md new file mode 100644 index 0000000..8bca003 --- /dev/null +++ b/docs/08-existing-project-adoption.md @@ -0,0 +1,200 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Existing-Project-Adoption-Guide +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Existing-Project-Adoption-Guide.- +wiki_revision: dfb92b4551c317a08f49e68d0262258157da6d04 +synchronized_at: 2026-08-11T10:30:53Z + + +# 已有项目接入 DevHarness 指南 + +## 本页用途 + +本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。 + +接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。 + +## 与新项目初始化的区别 + +| 场景 | 新项目初始化 | 已有项目接入 | +|---|---|---| +| 项目事实 | 从代码骨架和负责人确认开始建立 | 优先保留并核对已有事实 | +| 规则文件 | 可以从模板建立第一版 | 必须合并已有规则，不能直接覆盖 | +| 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | +| 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | +| Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | +| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 | +| 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | + +从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。 + +## 接入前只读盘点 + +Agent 在提出方案前只读检查： + +- 根目录和相关子目录中的 `AGENTS.md`、`CLAUDE.md` 及其他 Agent 规则； +- README、现有 `docs/`、Wiki 页面、工单模板和任务状态； +- Git 默认分支、远端、提交历史、未提交修改和忽略规则； +- 语言、框架、依赖、启动入口、主要模块和目录职责； +- 格式检查、静态检查、单元测试和必要集成测试命令； +- 配置、日志、接口、数据模型、权限、安全、部署和发布边界； +- 已完成、进行中、阻塞和待验收任务； +- 现有长期文档的事实来源、负责人和更新方式。 + +输出时区分： + +1. 从代码、配置或现有系统确认的事实； +2. 项目负责人确认的业务规则； +3. 尚待确认的假设； +4. DevHarness 与现有规则的冲突； +5. 与接入无关、必须保留的工作区改动。 + +只读盘点不授权修改文件、创建 Wiki、迁移文档或改变工单状态。 + +## 已有内容保护原则 + +- 保留 Git 历史、分支、标签和当前任务状态。 +- 保留已有 `AGENTS.md`、README、规则和项目专用红线；DevHarness 规则按冲突结果增量合并。 +- 保留与接入无关的未提交改动，不重置、不覆盖、不混入提交。 +- 不复制 DevHarness 的 `docs/task/`、任务归档映射和历史工单。 +- 不因采用 Wiki-first 就立即删除原本地文档；先逐页确认事实来源和迁移状态。 +- 不把模板占位值当成项目事实，不臆造技术栈、命令、业务规则、凭据或环境。 +- 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。 +- 页面删除、重命名、历史清理和事实来源切换必须单独确认。 + +## 多应用单仓库判断 + +一个 Git 仓库可以包含多个技术栈不同、能够独立构建和发布的应用或终端。技术栈不同本身不是拆仓理由；先把每个子项目和交付单元记录到 Project-Profile，再根据实际协作边界判断。 + +### 适合继续单仓库 + +- 多个应用共同完成一条产品或业务链路； +- 由同一团队维护，仓库权限基本一致； +- 接口变更需要在一个工单中同步修改或验证多端； +- 共享契约、业务规则和任务归档放在一起更容易保持一致； +- 仓库体积、测试时间和工具性能尚未明显影响开发； +- 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。 + +### 可以考虑拆仓 + +- 长期由不同团队独立负责并需要不同访问权限； +- 发布周期、版本策略和验收负责人已经完全独立； +- 某个应用被多个产品复用或需要单独对外提供； +- 仓库体积、检出、索引或测试耗时已经持续影响效率； +- 共享接口已经版本化、兼容周期明确，并有跨仓契约测试； +- 跨应用任务很少，拆仓后的协调成本低于继续共仓。 + +不满足这些条件时，优先保持单仓库并完善边界，不为了目录整洁或技术栈不同而拆仓。 + +### 保持单仓库时的最小规则 + +- 根目录 `AGENTS.md` 只放共同流程、安全和跨项目规则，技术栈专用规则写入子目录 `AGENTS.md`。 +- 每个交付单元拥有自己的构建、测试、版本和发布方式，不强制统一版本。 +- 单元任务必须声明只影响哪个子项目、是否跨子项目、是否修改共享接口，以及各端需要执行的验证。 +- 共享接口或契约只能指定一个事实来源；其他文档引用它，不复制一个“差不多”的版本。 +- 跨子项目契约变更在同一工单中更新事实来源，并验证所有受影响端。 +- 拆仓属于事实来源、任务和发布边界变化，必须另建工单、确认迁移和回退方案后实施。 + +## 增量接入顺序 + +### 1. 确认差异方案 + +根据盘点结果列出目标、非目标、复用项、改写项、冲突项、影响范围、风险、回退、验证和文档影响。方案得到用户明确确认前不实施。 + +### 2. 建立单元任务工单 + +使用目标项目的 Gitea 建立接入工单，记录原始需求、范围、依赖、方案和验收标准。目标项目没有可用 Gitea 时，先提交完整工单草稿并说明阻塞，不默认绕过。 + +### 3. 接入共同规则和工单流程 + +优先增量合并根规则、Claude 入口和单元任务模板。项目专用安全、业务和目录规则继续有效；冲突时由负责人决定最终表述。 + +### 4. 确定长期文档事实来源 + +为每份已有文档标记： + +- 保留在 Git：与特定代码版本强绑定； +- 迁移到 Wiki：长期架构、业务规则、开发规范或操作说明； +- 合并：内容重复但各有有效事实； +- 暂不迁移：事实未确认或当前不影响接入； +- 停止维护：必须由负责人确认，不能由 Agent 自行删除。 + +切换到 Wiki-first 的页面必须先在线上创建或更新、读取确认，再建立 `wiki-docs.json` 映射并导出本地镜像。避免 Wiki 和手写本地文档长期形成双事实源。 + +### 5. 接入 Harness 工具 + +仅复制当前项目实际需要的 `dev_scripts/` 工具、配置和测试。业务脚本使用独立目录。根据目标项目调整核心页面、路径、命令和结构检查，不照搬 DevHarness 项目值。 + +### 6. 分阶段验证 + +先验证工单和规则入口，再验证 Wiki 映射，最后启用严格检查。每阶段采用“执行 → 首个真实错误 → 最小修复 → 继续”的闭环，不用一次接入全部旧文档。 + +### 7. 提交和验收 + +提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。 + +## 冲突处理和停止条件 + +出现以下情况时停止实施并请求负责人确认： + +- 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突； +- 无法判断某份文档应该保留、迁移、合并还是停止维护； +- 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档； +- 需要改变接口、数据库、权限、部署、发布或其他产品行为； +- 工作区存在可能与接入文件重叠的未知修改； +- Gitea、Wiki、凭据或远端权限不可用； +- 真实命令、环境或业务规则无法从证据或负责人确认。 + +相邻问题最多提示或另建工单，不混入接入任务。 + +## 可复制 Agent 指令 + +### 只分析 + +```text +请把 的文档模板和开发流程接入当前已有项目。 + +先只分析，不修改文件、工单或 Wiki： + +1. 阅读 DevHarness 的 AGENTS.md、README.md、项目档案、开发工作流、 + 新项目文档初始化和已有项目接入指南。 +2. 阅读当前项目已有的 Agent 规则、README、docs、Gitea 工单模板、 + Wiki 配置、代码入口、测试命令和目录结构。 +3. 列出已有规则、文档、任务状态、Git 历史和未提交改动。 +4. 对比后列出可复用项、必须改写项、冲突项、旧文档处理方式、 + 最小接入范围、风险、回退、验证和文档影响。 +5. 不复制 DevHarness 任务归档，不覆盖、删除或重命名已有内容， + 不把模板占位值当成项目事实。 +6. 输出方案后停止，等待我确认。 +``` + +### 方案确认后实施 + +```text +按照已确认方案建工单并做。 + +严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、 +任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出 +本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持 +为“待验收”；未经我明确验收，不关闭工单。 +``` + +路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。 + +## 最小验收清单 + +- [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。 +- [ ] 已识别所有子项目和独立交付单元。 +- [ ] 跨子项目共享契约已经指定唯一事实来源。 +- [ ] 已明确复用、改写、冲突和暂不处理内容。 +- [ ] 已保留项目专用规则、历史和无关改动。 +- [ ] 未复制 DevHarness 历史归档或模板项目事实。 +- [ ] 已为每类长期文档明确事实来源和迁移状态。 +- [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。 +- [ ] Harness 检查已按目标项目调整并通过。 +- [ ] 必要测试、未验证部分、提交和归档证据已记录。 +- [ ] 工单处于待验收，未提前关闭。 + +## 回退原则 + +接入应拆成可回退的小提交。普通回退恢复本次新增或修改的规则、配置、检查和镜像映射，不触碰原有业务提交。Wiki 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。 diff --git a/docs/09-product-requirements.md b/docs/09-product-requirements.md new file mode 100644 index 0000000..19192d5 --- /dev/null +++ b/docs/09-product-requirements.md @@ -0,0 +1,141 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Product-Requirements +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Requirements.- +wiki_revision: f0d16a60406eed6fd6968c6555c599554bbd1fae +synchronized_at: 2026-08-11T10:30:56Z + + +# 产品需求 + +## 1. 产品范围与优先级 + +YoVision 首个可交付目标是在民办寄宿学校以默认 16 路高风险点位形成完整闭环： + +```text +设备接入 → 稳定供流 → 推理/规则 → 事件与证据 +→ Bell 预警 → ack/升级/close → 误报反馈 +``` + +需求优先级： + +- P0：独立纵切、首个端到端闭环、安全与可恢复边界。 +- P1：形成可交付产品所需的配置、运维和扩展能力。 +- P2：后续场景、规模或体验增强。 + +## 2. 产品独立性要求 + +### PR-BND-001 Sense 与 Bell 独立销售 + +- 两者各自拥有登录、用户、角色、菜单、审计、数据库、版本、安装包和备份恢复。 +- 同一自然人在两个产品中也视为两个独立账户。 +- 不共享用户 ID、密码、JWT、Cookie、Casbin 策略或数据库角色。 +- 任一产品不以另一产品为启动依赖。 + +### PR-BND-002 Brain 独立交付 + +- Brain 可独立构建、测试、版本化和发布，默认随 Sense 产品部署。 +- Brain 无交互式账户，不持有 Alert、ack、通知或全局审计真相。 +- Brain 与 Sense/Bell 仅通过版本化契约交互。 + +### PR-BND-003 可选产品集成 + +- 产品间使用独立机器身份，不复用管理员密码或浏览器 token。 +- 不允许跨数据库查询、共享文件目录或复制内部表结构临时打通。 +- Bell 不读取摄像头密码；事件只携带逻辑设备引用和必要证据引用。 + +## 3. Sense 需求 + +### P0 + +- **SEN-001 独立登录与权限**：Sense 自有用户、角色、菜单、会话和审计；至少覆盖管理员、实施/运维、站点管理员和只读边界。 +- **SEN-002 设备台账**：以 Device 为根实体，通过 `modality` 和 `capabilities` 表达 video/radar/contact/button/wearable/other；首期只完整实现 video，未实现适配器显示 `adapter_not_ready`。 +- **SEN-003 ONVIF/RTSP 接入**：支持发现或手工添加、Profiles、StreamUri、主/子码流、校时、认证失败、重新探测和凭据更新。 +- **SEN-004 批量开通**：默认 16 路可导入、预校验、待激活、逐项成功/失败、仅重试失败项；部分成功不做整体回滚。 +- **SEN-005 MediaMTX 管理**：媒体代理保持独立进程；Sense 管理期望配置、生命周期、reader、上游拉流和对账收敛。 +- **SEN-006 实时监看**：支持设备列表、单路实时画面、主/子 Profile、加载/空/失败/重连状态；128 路站点使用分页或虚拟列表，不一次加载全部视频。 +- **SEN-007 区域配置**：支持多边形区域、方向警戒线、设备关联和版本化配置；能力/Profile 变化时显式提示几何重新校准。 +- **SEN-008 独立本地事件查看**：未安装 Bell 时仍可查看本地事件候选和证据状态。 +- **SEN-009 运维中心**：展示设备/媒体/推理期望态与实际态、未收敛差异、退避、下次重试、认证失败、时间漂移、孤儿安全闸和审计。 +- **SEN-010 安全凭据**：摄像头密码只写不读、不回显、不进日志；更新后自动重试并显示脱敏结果。 + +### P1/P2 + +- **SEN-011 容量与配额**：默认 16 路；32/64/128 可配置和分片扩展；新增/启用时校验配额，配额不可读时拒绝相关写入但保持已有流与读取。 +- **SEN-012 边缘节点**：展示节点版本、在线时长、承载数、控制隧道、视频数据面和补传队列；断网缓存，恢复补传。 +- **SEN-013 Media/Brain 分片**：容量来自压测而非硬编码；分片故障影响范围可观察，跨分片迁移需独立高风险工单。 +- **SEN-014 Bell connector**：使用持久 Outbox 投递标准事件/审计；Bell 不可用不阻断 Sense，恢复后幂等补投。 +- **SEN-015 设备运维告警**：离线、认证、漂移、收敛、分片和隧道异常不进入 Bell 业务预警队列。 + +## 4. Brain 需求 + +### P0 + +- **BRN-001 输入适配**：从版本化源契约读取 RTSP/媒体引用、设备逻辑标识和区域配置，不读取 Sense 数据库。 +- **BRN-002 解码与推理**：建立可替换的解码、检测、姿态、跟踪、ReID 和规则判定流水线；模型输出与业务规则分层。 +- **BRN-003 匿名安全规则**：首期支持越线、危险区域、聚集等匿名规则；不启用人脸。 +- **BRN-004 区域语义**：支持多边形、警戒线方向、时段、持续时间和冷却语义；坐标与 Profile/分辨率绑定且版本化。 +- **BRN-005 标准事件**：输出冻结 JSON Schema，包含 producer/source event ID、租户/站点/设备逻辑引用、规则/模型版本、时间、观测、区域和证据引用。 +- **BRN-006 幂等与重试**：同一输入事实重试不得制造语义不同的重复事件；投递失败可恢复并可观测。 +- **BRN-007 隐私**：事件不得包含摄像头密码、内部文件路径、客户隐私明文或未经授权的人脸特征。 + +### P1/P2 + +- **BRN-008 证据**：生成抓拍和含 pre-roll 的片段引用；证据失败可形成明确的降级事件，不伪装完整成功。 +- **BRN-009 容量**：按模型、分辨率、FPS、batch 和硬件建立每 16 路逻辑分片基线；不承诺单 GPU 128 路。 +- **BRN-010 效果评估**：按规则版本分别报告召回率、每路每天误报数和样本量，不使用跨场景统一“准确率”。 +- **BRN-011 人脸后置**：默认关闭；仅在单独授权、影响评估、底库合法性、撤回/删除和加密审计完成后进入独立试点。 + +## 5. Bell 需求 + +### P0 + +- **BEL-001 独立登录与 RBAC**：Bell 自有用户、角色、会话、密码策略和审计，不接受 Sense 用户 token。 +- **BEL-002 外部事件 API**：接收 Sense、Brain、其他 NVR、传感器或第三方标准事件；每实例独立 producer identity。 +- **BEL-003 幂等入站**：以 `(producer_id, source_event_id)` 保证永久稳定收据和跨重启幂等。 +- **BEL-004 Event 不可变**：校验后持久化结构化事件和证据引用；误报或处置不改写原始事件。 +- **BEL-005 规则与 Alert**：规则命中创建 Alert；Event 与 Alert 多对多、双向可导航，抑制的 Event 不伪装成已投递。 +- **BEL-006 Alert 生命周期**：至少支持 open/ack/close；并发 ack 仅首个服务端成功者成为处置人，后到者看到真实结果。 +- **BEL-007 自动升级**：未 ack 按版本化升级链继续；重启后恢复未完成链路，恢复成功/失败可观察。 +- **BEL-008 投递事实**：sent/delivered/seen 与 ack 分离；不支持回执、未知、可重试失败和最终失败均明确展示。 +- **BEL-009 双路径通知**：试点至少本地 Web/声光加短信或语音；生产前两条独立路径，其中一条可绕过互联网，并支持供应商健康和故障切换。 +- **BEL-010 联系人/排班/升级**：人员与已验证通道、值班组、站点时区、周轮换、生效日期、临时替班、空档/重叠检查、版本发布和审计分对象建模。 +- **BEL-011 投递快照**：创建投递时固化实际收件人、通道、排班和升级策略版本；后续修改不改写历史。 +- **BEL-012 交接与静默**：交接覆盖未 ack、处置中和升级中 Alert，升级不中断；静默最多 4 小时并自动恢复。 + +### P1/P2 + +- **BEL-013 事件与审计中心**：筛选、分页、批量处置、总数、时间线和安全深链；不一次加载全部记录。 +- **BEL-014 规则版本**：试运行展示命中样本和影响；回滚创建新版本，不改写历史版本。 +- **BEL-015 去重聚合**：支持设备冷却、站点聚合、已处置抑制和静默，并在 Alert 中解释聚合原因。 +- **BEL-016 保留策略**：事件片段、抓拍、元数据、审计和训练样本分别配置并记录到期删除；技术默认 30 天，最终期限由客户/法务确认。 +- **BEL-017 对外集成**：版本化 OpenAPI/Webhook，签名密钥只写不读，重试和失败告警可见；客户平台不接管 Bell 状态机。 +- **BEL-018 场景包**：版本化导入/导出、站点应用差异和升级路径；新场景尽量纯配置交付。 + +## 6. 跨项目非功能要求 + +- **NFR-001 可用性**：断线重连、先落库后投递、Outbox、对账收敛和重启恢复是基础能力。 +- **NFR-002 安全**：最小权限、全链路审计、秘密仓库外管理、无 query token、无默认密码/JWT secret/演示入口。 +- **NFR-003 隔离**：Sense/Bell 数据库角色只能访问本产品数据；部署在同机也使用不同域名或明确隔离 Cookie Path/策略。 +- **NFR-004 可观察**：设备在线、流状态、推理延迟、事件量、未收敛项、投递 SLA 和恢复失败可监控。 +- **NFR-005 容量**：媒体、解码、推理、证据和 UI 分别压测；16 不硬编码，128 不等于单机承诺。 +- **NFR-006 可维护**：每个交付单元有独立 README、构建/测试/发布命令、版本和子目录规则。 +- **NFR-007 契约兼容**：破坏性变更发新版本；生产者和所有消费者必须有契约测试。 +- **NFR-008 隐私合规**：最少收集、最少展示、目的完成后删除；未成年人、家庭、人脸试点分别经过法务/客户门禁。 + +## 7. 首期非目标 + +- 不直接复制旧仓库整棵目录、go.mod、迁移或任务状态。 +- M1-M3 不实现 GB/T 28181、信创适配、原生 App、异构传感器完整适配或人脸。 +- 不实现高空抛物专用算法。 +- 不承诺未经现场数据验证的召回率、误报率或 128 路单机能力。 +- 不在框架初始化工单中同时完成 GoAdmin 升级、TypeScript、Vite 和全部业务重写。 + +## 8. 最小产品验收 + +- Sense 在 Bell 未安装/未启动时可独立登录，完成摄像头接入、实时查看和区域配置。 +- Brain 可用合成输入产生符合契约的匿名区域事件，并在 Bell 不可用时明确重试/降级。 +- Bell 在 Sense/Brain 未启动时可用合成或第三方事件完成 Alert → ack → close。 +- Sense 账号不能登录 Bell，Bell 账号不能登录 Sense。 +- 三个项目独立构建、测试和版本化；Sense/Bell 独立迁移、备份、恢复和打包。 +- 集成断开不阻断各自核心能力，恢复后按 Outbox 和幂等收据继续。 diff --git a/docs/10-requirements-migration-matrix.md b/docs/10-requirements-migration-matrix.md new file mode 100644 index 0000000..ea690c0 --- /dev/null +++ b/docs/10-requirements-migration-matrix.md @@ -0,0 +1,59 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Requirements-Migration-Matrix +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Requirements-Migration-Matrix.- +wiki_revision: 3e430119f84e38ccdb22c166f88df2b733df096f +synchronized_at: 2026-08-11T10:30:58Z + + +# 需求迁移矩阵 + +## 使用原则 + +- 旧仓库 `D:\OPC\yovision_old` 是只读需求与证据来源，不是当前实现状态。 +- “旧任务 DONE”只证明旧原型曾有对应证据，不代表本仓库已经完成。 +- 每项初始状态均为“待迁移”；只有新工单、新代码、新测试和负责人验收后才能完成。 +- 迁移行为和验收标准，不整树复制旧代码、历史工单、claim/PR 状态、秘密或生产数据。 + +## 旧任务到新项目 + +| 旧任务 | 有效能力/证据 | 目标 | 新仓库处理 | 初始状态 | +|---|---|---|---|---| +| T-001 指定摄像头准入 | Hikvision 单样机 ONVIF/RTSP、校时、断线恢复的实验室证据 | Sense | 作为兼容性测试输入；重新冻结设备/固件与新实现验收 | 待迁移 | +| T-002 架构开放问题 | 已确认的产品目标、隐私、容量和场景边界 | 根文档/三端 | 已提炼入 Product-Requirements；后续逐项建单 | 文档已提炼，功能待迁移 | +| T-003 Sense 骨架 | ONVIF/RTSP、MediaMTX、设备状态的旧实现经验 | Sense | 基于新 GoAdmin 边界重新建立骨架，不复制整树 | 待迁移 | +| T-004 Sense/Bell 原型 | 已确认页面流程、响应式与状态覆盖 | Sense/Bell | 作为 UI 验收输入；按独立登录和产品边界重建设计 | 待迁移 | +| T-005 原型评审 | Sense/Bell 模块缺口与修正裁决 | Sense/Bell | 纳入各 MVP backlog，不继承旧任务状态 | 待迁移 | +| T-006 五路混合源 | 单实机 + 合成 RTSP、故障恢复证据 | Sense | 新实现建立同等或更强的集成测试 | 待迁移 | +| T-007 客户真实多路 | 未完成的现场门禁 | Sense | 保留为未来试点工单，不能宣称已验证 | 未开始 | +| T-008 设备/配额契约 | 设备 API 与配额投影设计经验 | Sense/contracts | 按独立产品边界重新发布契约；避免 Bell 成为 Sense 启动依赖 | 待重裁决 | +| T-009 双 Schema | PostgreSQL 权限和隔离测试经验 | Sense/Bell | 改为产品级独立数据库/角色；不复制旧共享库假设 | 待迁移 | +| T-010 Area/审计 Outbox | 策略版本、准入和 transactional outbox | Sense/Bell/contracts | 保留版本投影和 Outbox模式；重新裁决各产品自身 Area 真相 | 待重裁决 | +| T-011 Sense Control API | 幂等、并发和 PostgreSQL 一致性边界 | Sense/contracts | 逐端点评估并在新 OpenAPI 中重发版本 | 待迁移 | +| T-012 对账安全闸 | fencing、孤儿受控处置、多实例可观测 | Sense | 迁移领域行为与测试，不强迫改写为通用 CRUD | 待迁移 | +| T-014 16 路基线 | 16 路批量收敛与容量脚本经验 | Sense | 新栈重跑；16 仍为默认配额而非硬上限 | 待迁移 | +| T-015 Bell Event | v0.1 校验、不可变 PostgreSQL 存储 | Bell/contracts | 作为事件契约候选基线，复核后发布新仓库版本 | 待迁移 | +| T-016 审计 relay | Outbox、幂等补投、机器接口 | Sense/Bell/contracts | 合并到可选 connector 设计，使用独立机器身份 | 待迁移 | +| T-017 Brain 原型 | 单路匿名区域事件、可视化和运行时经验 | Brain | 重建 Brain 骨架和合成输入验收 | 待迁移 | +| T-018 Sense 纵切 | 设备管理与实时监看最小纵切 | Sense | 作为 Sense 第一纵切验收基线 | 待迁移 | +| T-019 Brain→Bell | 可靠事件入站和契约测试经验 | Brain/Bell/contracts | 由协调工单发布契约并验证两端 | 待迁移 | +| T-020 Bell 纵切 | Event→Rule→Alert→ack 最小可见链路 | Bell | 作为 Bell 第一纵切验收基线并补 close/重启恢复 | 待迁移 | + +## 旧文档裁决 + +| 来源 | 处理 | +|---|---| +| `docs/01-vision.md`、`02-requirements.md`、`07-user-stories.md` | 提炼有效产品目标和验收，不复制旧三系统同仓假设 | +| `docs/raw/08-三系统职责划分.md` | 保留职责分层；用当前“三项目、两产品”裁决覆盖冲突内容 | +| `docs/raw/09`～`15` 原型评审 | 作为 UI/模块 backlog 与验收证据来源，不视为现有页面 | +| `docs/raw/16-Sense与Bell独立产品重建建议.md` | 采纳产品独立性、账户安全、可选集成和迁移原则；“两个仓库”被负责人明确改为“单仓三项目” | +| `docs/raw/contracts/`、`docs/contracts/` | 作为候选输入；必须经新协调工单复核、版本化后进入 `contracts/` | +| `docs/tasks/` | 不复制；只在本矩阵保存脱离旧过程状态的能力摘要 | + +## 不得迁移 + +- 摄像头账号密码、真实视频、客户数据、手机号、地址和本机生产配置； +- 旧 Issue/PR/claim 状态和任务归档； +- 已被后续评审否决的草稿和“Bell 统一账号/共享数据库”假设； +- 未经许可证复核的模型、依赖或上游代码； +- 未经逐包依赖评估与新测试证明的整树代码。 diff --git a/docs/11-multi-agent-collaboration.md b/docs/11-multi-agent-collaboration.md new file mode 100644 index 0000000..46c782f --- /dev/null +++ b/docs/11-multi-agent-collaboration.md @@ -0,0 +1,94 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Multi-Agent-Collaboration +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Multi-Agent-Collaboration.- +wiki_revision: 29c737b262eac4c850c1edc4c1b51cb07a694291 +synchronized_at: 2026-08-11T10:31:01Z + + +# 多 Agent 协作 + +## 目标 + +三名主 agent 尽量并行推进 Sense、Brain、Bell 的独立工单；只有跨项目契约、根级构建或端到端流程需要协作时，才建立协调工单并启用新的协调 agent。 + +## 固定所有权 + +| 角色 | 默认写路径 | 禁止默认写入 | +|---|---|---| +| Sense agent | `Sense/**` | `Brain/**`、`Bell/**`、`contracts/**`、根级共享文件 | +| Brain agent | `Brain/**` | `Sense/**`、`Bell/**`、`contracts/**`、根级共享文件 | +| Bell agent | `Bell/**` | `Sense/**`、`Brain/**`、`contracts/**`、根级共享文件 | +| 协调 agent | 工单明确列出的 `contracts/**`、根文件、端到端测试和必要三端适配点 | 未列入工单的相邻功能 | + +同一路径及父子目录视为冲突。文件少并不允许多个 agent 同时写；单写入者比事后合并更重要。 + +## 工单类型 + +### 单项目工单 + +- 只有一个主项目和一个主 agent。 +- `write_paths` 只能覆盖本项目目录及明确的 Wiki 页面。 +- 不修改共享契约；若发现契约需要变化，停止并提出协调工单。 +- 只运行本项目和必要回归验证。 + +### 协调工单 + +适用于： + +- 新增/修改 OpenAPI、JSON Schema、SQL 共享契约； +- Sense↔Brain、Brain/Sense→Bell 端到端链路； +- 根级 CI、compose、版本清单或发布编排； +- 同一验收必须跨两个以上项目才能成立。 + +协调工单必须写明：生产者、消费者、契约唯一事实来源、兼容策略、各端适配工单、集成顺序、回退和全套验证。协调 agent 是共享路径的唯一写入者；主 agent 可以提供只读分析或在不重叠的分支工单实施各自适配。 + +## 推荐并行模型 + +```text +Epic / MVP +├─ Sense 单元工单 ── Sense agent +├─ Brain 单元工单 ── Brain agent +├─ Bell 单元工单 ─── Bell agent +└─ 集成协调工单 ──── coordination agent + ├─ 冻结 contracts 版本 + ├─ 汇总三端适配状态 + └─ 运行端到端验收 +``` + +协调工单可以先冻结契约，三个适配工单再并行；契约未冻结前不得用复制字段、共享表或临时 JWT 打通。 + +## 领取与交接 + +1. 领取前检查前置工单、活跃 agent 和写路径重叠。 +2. Issue 记录主 agent、分支、精确写路径、契约版本和验证命令。 +3. 新增写路径必须先更新工单并由 dispatcher/负责人复核。 +4. 交接记录已完成事实、未完成步骤、测试证据、工作区状态和风险，不复制内部推理。 +5. 一个 agent 同时最多一个活跃主工单；只读评审不取得写路径所有权。 + +## Git 与集成建议 + +- 分支建议：`agent//-`。 +- 每个工单独立提交和 PR；提交信息引用 Issue。 +- 不通过长期共享工作树让三个 agent 同时写；使用独立 worktree/分支或平台隔离工作区。 +- 共享契约先合并或固定 revision，再让消费者适配；不能各自维护“差不多”的 schema。 +- PR 合并前检查默认分支上的契约版本与任务证据，避免基于过期分支验收。 + +## 验证矩阵 + +| 变化 | 最少验证 | +|---|---| +| Sense 内部 | Sense 单测/集成测试、凭据泄露检查 | +| Brain 内部 | Brain 单测、合成输入、事件 schema | +| Bell 内部 | Bell 单测/数据库/状态机测试 | +| 事件契约 | Schema 校验、Brain/Sense 生产者测试、Bell 消费者与幂等测试 | +| 证据契约 | Sense/Brain 生成、Bell 授权请求、降级和超时测试 | +| 根级部署 | 三端独立启动、停止任一产品的隔离测试、端到端测试 | + +## 停止条件 + +- 两个 agent 的写路径出现重叠； +- 需要修改共享契约但没有协调工单； +- 需要跨库查询、共享用户/JWT/Cookie 或摄像头凭据； +- 契约破坏性变化没有新版本和回退； +- 三端对字段语义存在分歧且无法从事实源裁决。 diff --git a/docs/12-product-roadmap.md b/docs/12-product-roadmap.md new file mode 100644 index 0000000..b86d49a --- /dev/null +++ b/docs/12-product-roadmap.md @@ -0,0 +1,86 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Product-Roadmap +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Roadmap.- +wiki_revision: 2d5b8550109a8ff0795ad46dd0f96c85929fb506 +synchronized_at: 2026-08-11T10:31:04Z + + +# 产品路线图 + +## 阶段 0：仓库与契约基线 + +- 完成 DevHarness、Gitea Wiki、工单模板和三项目目录规则。 +- 冻结两销售产品、三交付单元、认证/数据边界。 +- 分别验证 GoAdmin/go-admin-ui 固定版本、PostgreSQL、许可证和裁剪策略。 +- 复核旧事件契约，建立新 `contracts/` 版本与消费者测试。 + +出口：三个项目能独立构建/测试，Sense/Bell 独立登录骨架成立，默认秘密和演示入口已移除。 + +## 阶段 1：三条独立纵切 + +### Sense + +```text +独立登录 → 添加实验室摄像头 → ONVIF/RTSP 验证 +→ MediaMTX 实时画面 → 绘制区域 +``` + +### Brain + +```text +合成/实验室视频 → 解码 → 匿名检测/跟踪 +→ 区域/越线判定 → 标准事件 +``` + +### Bell + +```text +独立登录 → 合成事件 → 规则匹配 +→ Alert 详情 → ack → close +``` + +出口：任一纵切不依赖其他项目启动；各自有最小 UI/API、测试和可复制命令。 + +## 阶段 2：可选端到端闭环 + +```text +Sense/Brain Event → 持久 Outbox/可靠投递 +→ Bell 幂等入站 → Alert → 通知 → ack/升级/close +``` + +- 建立机器身份、事件 API、错误码、幂等和兼容周期。 +- 验证 Bell 断开不阻断 Sense；恢复后补投。 +- 验证 Sense/Brain 断开时 Bell 仍处理已接收事件和其他事件源。 +- 加入误报反馈与不可变事件 outcome。 + +## 阶段 3：首期学校 MVP + +- 默认 16 路，越线、危险区域、聚集三类匿名规则。 +- 设备批量开通、认证失败恢复、对账和运维中心。 +- 联系人、排班、升级链、双路径投递、交接与静默。 +- dry-run 不少于 2 周，冻结机位、规则版本、样本窗口和标注口径。 +- 规则级召回率、每路每天误报数、样本量和投递/ack SLA。 + +出口：客户/法务完成未成年人影像、告示/备案、权限和留存期门禁；现场阈值在验收附件确认。 + +## 阶段 4：容量、证据与场景包 + +- 32/64/128 路媒体、推理、证据和 UI 分项压测与分片。 +- 异步证据切片、保留与到期删除举证。 +- 场景包版本、差异预览、导入/导出和站点升级。 +- 第二/第三场景尽量纯配置交付；若需修改通用底座，先复盘分层。 + +## 后置能力 + +- 非视频传感器完整适配在独立里程碑推进。 +- 人脸最早在单独合规试点，默认关闭且不能替代匿名 ReID。 +- GB/T 28181、信创适配、原生 App、高空抛物专用算法均独立立项。 + +## 全程停止条件 + +- 新框架不能稳定支持 PostgreSQL、独立权限或领域状态机； +- 需求在三个项目间归属不清； +- 契约未冻结却尝试共享数据库、用户会话或内部文件； +- 新纵切尚未验收却删除或覆盖旧仓库； +- 许可证、隐私或客户/法务门禁未满足却进入生产试点。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..96865af --- /dev/null +++ b/docs/README.md @@ -0,0 +1,60 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Home +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Home +wiki_revision: 1a2dadc746ce76e182150ca93fc4a1ec192c6b6a +synchronized_at: 2026-08-11T10:30:24Z + + +# YoVision 文档中心 + +YoVision 是单仓三项目的智能视频事件平台。Sense 负责设备与媒体，Brain 负责推理与事件生成，Bell 负责事件预警和处置。Sense 与 Bell 是可独立销售、部署和验收的产品；Brain 是独立构建的推理交付单元。 + +## 第一次阅读 + +1. [项目档案](Project-Profile.-)：目标、子项目、技术栈和边界。 +2. [产品需求](Product-Requirements.-)：功能、质量、安全和非目标。 +3. [架构与代码地图](Architecture-and-Code-Map.-)：职责、数据流和代码入口。 +4. [业务规则与术语](Business-Rules-and-Glossary.-)：不可破坏的领域规则。 +5. [需求迁移矩阵](Requirements-Migration-Matrix.-)：旧项目需求怎样进入新仓库。 +6. [多 Agent 协作](Multi-Agent-Collaboration.-)：三名主 agent 和协调任务的写路径规则。 +7. [本地开发与验证](Local-Development-and-Verification.-)：当前可执行命令和待补门禁。 +8. [开发工作流](Development-Workflow.-)：建单、确认、实施、验收和归档。 + +## 五分钟开始 + +```powershell +git status --short --branch +python dev_scripts/check_harness.py --strict +python -m unittest discover -s tests -v +python dev_scripts/sync_wiki_docs.py --check +``` + +预期：工作区变更归属清楚，Harness 与测试通过，Wiki 镜像一致。业务代码尚未初始化时，不应臆造 Sense、Brain 或 Bell 的构建命令。 + +## 简单修改从哪里开始 + +| 修改类型 | 先读 | 主要验证 | +|---|---|---| +| Sense 单项目 | Project-Profile、`Sense/AGENTS.md` | Sense 自身测试 | +| Brain 单项目 | Product-Requirements、`Brain/AGENTS.md` | Brain 自身测试与事件契约测试 | +| Bell 单项目 | Business-Rules、`Bell/AGENTS.md` | Bell 自身测试 | +| 共享契约 | Multi-Agent-Collaboration、`contracts/AGENTS.md` | 三端消费者/生产者契约测试 | +| 长期文档 | 对应 Wiki 页面 | Wiki 同步检查 | + +## 事实来源 + +| 信息 | 事实来源 | +|---|---| +| 实时任务状态、方案确认和验收过程 | Gitea 工单 | +| 长期需求、架构、规则、操作与归档 | Gitea Wiki | +| API/Schema/迁移及代码版本事实 | Git 仓库 | +| 离线文档 | `docs/` Wiki 只读镜像 | +| 历史需求和旧证据 | `D:\OPC\yovision_old`，只读参考，不是当前状态 | + +## 项目入口 + +- [代码仓库](https://git.ilapage.cn/ila/yovision) +- [Gitea 工单](https://git.ilapage.cn/ila/yovision/issues) +- [产品路线图](Product-Roadmap.-) +- [故障排查](Troubleshooting) diff --git a/docs/delivery/README.md b/docs/delivery/README.md new file mode 100644 index 0000000..f141842 --- /dev/null +++ b/docs/delivery/README.md @@ -0,0 +1,80 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Delivery-Documentation-Guide +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.- +wiki_revision: e0b43bfada515ff95831debc4378de41a8ad969a +synchronized_at: 2026-08-11T10:31:06Z + + +# 交付文档指南 + +## 本页用途 + +本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。 + +最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。 + +## 什么时候需要交付文档 + +出现以下任一情况时，应在单元任务工单中评估并更新交付文档： + +- 新增或改变用户可见功能、操作步骤、界面、权限或限制； +- 改变安装、配置、部署、备份、恢复、监控或升级方法； +- 改变外部 API、数据格式、集成条件或兼容范围； +- 改变常见故障的识别、处理或支持方式； +- 发布新版本或交付客户验收。 + +纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。 + +## 受众与文档选择 + +| 交付对象 | 典型文档 | 需要回答的问题 | +|---|---|---| +| 最终用户 | 用户使用说明 | 怎样完成日常操作，失败后怎么办 | +| 管理员 | 管理员指南 | 怎样配置用户、权限和系统参数 | +| 运维人员 | 部署与运维指南 | 怎样安装、启停、监控、备份和恢复 | +| 客服或一线支持 | 支持与排错指南 | 怎样识别问题、收集信息和升级处理 | +| 集成人员 | 接口与集成指南 | 怎样认证、调用接口和处理兼容性 | +| 验收或项目负责人 | 发布、升级与验收说明 | 本次交付了什么，怎样验证和回退 | + +一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。 + +## 内部文档与交付文档边界 + +交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。 + +面向客户或公开的文档不得包含： + +- 内部工单链接、聊天记录、内部决策过程或任务归档； +- 内部网络地址、仓库路径、无必要的源码模块名和调试细节； +- 密码、令牌、Cookie、私钥、个人数据或生产数据； +- 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段； +- 未承诺的路线图、期限和功能。 + +交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。 + +## 编写和维护流程 + +1. 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。 +2. 使用[岗位文档模板](Audience-Document-Template.-)按需创建文档，不创建没有明确读者的空页面。 +3. 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。 +4. 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。 +5. 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。 +6. 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。 +7. 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地 `docs/` 镜像。 + +具体项目创建的岗位文档应增加到 `wiki-docs.json` 的显式映射中。本模板自身的指南和模板镜像位于 `docs/delivery/`。 + +## 最小验收清单 + +- [ ] 文档有明确受众、适用版本、可见范围和负责人。 +- [ ] 前置条件、操作步骤和预期结果完整且可以对应。 +- [ ] 常见失败、恢复方法、安全提示和已知限制已说明。 +- [ ] 关键步骤由目标岗位视角验证，或明确记录未验证项。 +- [ ] 外部版本不含内部链接、敏感数据和无关实现细节。 +- [ ] 本次功能变化涉及的交付文档已更新并与版本一致。 +- [ ] Wiki 已读取确认，本地镜像检查一致。 + +## 不在本页解决的内容 + +开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。 diff --git a/docs/delivery/audience-document-template.md b/docs/delivery/audience-document-template.md new file mode 100644 index 0000000..670ed0c --- /dev/null +++ b/docs/delivery/audience-document-template.md @@ -0,0 +1,96 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Audience-Document-Template +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Audience-Document-Template.- +wiki_revision: 2b44e14c41aaa6aacb5925a4eb12c449749b9aad +synchronized_at: 2026-08-11T10:31:10Z + + +# 岗位文档模板 + +> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。 + +## 文档信息 + +| 字段 | 内容 | +|---|---| +| 文档名称 | | +| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 | +| 适用版本 | | +| 最后验证日期 | YYYY-MM-DD | +| 负责人 | | +| 可见范围 | 内部 / 指定客户 / 公开 | +| 相关产品或模块 | | + +## 目的与适用范围 + +说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。 + +## 前置条件 + +- 所需权限： +- 所需环境或设备： +- 已完成的准备： +- 需要提前获得的信息： + +不得在这里填写真实密码、令牌、个人数据或生产数据。 + +## 操作步骤 + +### 任务一：<明确的操作目标> + +1. <执行动作> +2. <执行动作> +3. <执行动作> + +**预期结果**：<读者可以观察到的成功结果> + +**失败时**：<先检查什么；何时停止并联系支持> + +每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。 + +## 常见错误与恢复 + +| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 | +|---|---|---|---| +| | | | | + +只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。 + +## 安全与权限 + +- 本岗位允许执行的操作： +- 明确禁止或需要审批的操作： +- 敏感信息处理规则： +- 数据、日志和截图脱敏要求： +- 删除、发布、迁移或其他高风险操作的确认要求： + +## 已知限制 + +- 支持的环境和版本： +- 当前不支持的场景： +- 兼容性限制： +- 未验证的环境或步骤： + +## 支持与升级处理 + +- 支持渠道： +- 服务时间或响应约定： +- 联系支持前需要收集的信息： +- 不得提交的信息： +- 需要升级到下一岗位或负责人的条件： + +## 版本记录 + +| 日期 | 适用版本 | 变更内容 | 验证人 | +|---|---|---|---| +| | | | | + +## 交付前检查 + +- [ ] 目标岗位能够理解术语和步骤。 +- [ ] 前置条件、步骤与预期结果一一对应。 +- [ ] 关键流程已按目标岗位视角验证。 +- [ ] 常见错误、恢复方法和升级条件清楚。 +- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。 +- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。 diff --git a/docs/templates/task-archive.md b/docs/templates/task-archive.md new file mode 100644 index 0000000..5ef7dfa --- /dev/null +++ b/docs/templates/task-archive.md @@ -0,0 +1,50 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Task-Archive-Template +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-Archive-Template.- +wiki_revision: 08fe74e95b01c0a44edf0dba21e2ba3b78b71a71 +synchronized_at: 2026-08-11T10:31:13Z + + +# <工单号> <标题> + +- 类型：需求 / 缺陷 / 重构 +- 所属 Epic：# +- 所属 MVP / 版本：# +- 状态：待验收 / 已完成 +- 日期：YYYY-MM-DD +- Gitea 工单：<链接> +- Wiki 页面：<页面名> +- Wiki revision：见本地镜像头 + +## 背景与目标 + + + +## 最终方案 + + + +## 修改文件 + +- `<文件>`：<改动说明> + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| | 通过 / 未通过 | + +## 测试 + +- 执行命令：`<命令>` +- 结果： +- **未验证部分**： + +## 遗留问题 + + + +## 相关提交 + +- `<提交哈希>` <提交说明>