docs: 同步 DevHarness 长期文档 (#108)

2026-08-27 17:16:50 +08:00
parent 266bf236b8
commit a3d1bdfb14
16 changed files with 875 additions and 121 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Project-Profile.-
-wiki_revision: 84cb91d5fb87fcb711c04c1f94b5c09ebe8c22a1
-synchronized_at: 2026-08-15T06:45:18Z
+wiki_revision: 5e6d18991d69aad15311aae811f35206aa0b5ee6
+synchronized_at: 2026-08-27T09:04:26Z
 <!-- gitea-wiki-mirror:end -->

 # 项目档案
@@ -22,6 +22,18 @@ synchronized_at: 2026-08-15T06:45:18Z
 | 当前阶段 | 进入 GoAdmin 源码派生重建：旧实现归档于 `explore`，`main` 为审核基线，`dev` 为集成开发分支 |
 | 历史来源 | `D:\OPC\yovision_old`，只读追溯 |

+## DevHarness 来源与基线
+
+| 项目 | 内容 |
+|---|---|
+| 上游仓库 | `https://git.ilapage.cn/OPC/dev_harness` |
+| 本次升级前基线 | `f23c2cf81f9792495f696d49e88d79b16cf29810` |
+| 当前目标基线 | `4bbacf4d7fb265984396bb5589c544105043fa0b` |
+| 升级日期 | 2026-08-27 |
+| 识别方式 | 初始导入文件 blob 与上游历史逐项对照；完整 commit 是基线标识 |
+
+YoVision 采用 DevHarness 的共同工作流、统一 `harness.py` 命令、Gitea 工单/Wiki 事实源边界和模板；项目适配保留三项目并行与写路径所有权、`explore/main/dev` 分支治理、Sense/Bell GoAdmin 固定基线、UI 精简复用门禁和现有产品文档结构。升级不得整页覆盖项目事实，也不得复制 DevHarness 自身任务状态。
+
 ## 子项目与交付单元

 | 单元 | 职责 | 技术栈目标 | 独立构建/测试/发布 | 规则入口 | 共享边界 |
@@ -57,9 +69,9 @@ synchronized_at: 2026-08-15T06:45:18Z
 当前初始化阶段可执行：

 ```powershell
-python dev_scripts/check_harness.py --strict
+python dev_scripts/harness.py check --strict
 python -m unittest discover -s tests -v
-python dev_scripts/sync_wiki_docs.py --check
+python dev_scripts/harness.py sync --check
 git diff --check
 ```

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Development-Workflow.-
-wiki_revision: 2bb60b79073439babfda05140ce813d197de81d9
-synchronized_at: 2026-08-14T01:06:22Z
+wiki_revision: b377b601b04074b834c4c9f6fbd37434b3d19d22
+synchronized_at: 2026-08-27T09:04:39Z
 <!-- gitea-wiki-mirror:end -->

 # 开发工作流
@@ -11,10 +11,94 @@ synchronized_at: 2026-08-14T01:06:22Z
 ## 事实来源边界

 - Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
+- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。
 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。

+## Gitea 交互与工单最小读取
+
+- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
+- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
+- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
+- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
+- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
+- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
+- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。
+
+## 新项目 Wiki 初始化门禁
+
+从 DevHarness 创建新项目时，本地 `docs/` 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：
+
+1. 先创建 Gitea 远端仓库并启用 Wiki，再把 `wiki-docs.json` 指向该仓库。
+2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
+3. 查询线上页面列表；没有 `Home` 时先创建 `Home`，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
+4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 `docs/` 文件替代这项证据。
+5. 运行 `python dev_scripts/harness.py sync --verify`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
+
+Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。
+
+## 工单与设计证据双门禁
+
+开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。
+
+### 先判断是否需要工单
+
+只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型：
+
+- 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案；
+- 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果；
+- 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义；
+- 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符；
+- 不造成明显布局、截断、换行、可访问性或支持平台问题；
+- 有任何不确定时不使用豁免。
+
+豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。
+
+### 再判断设计证据
+
+| 修改类型 | 最低设计证据 | 正式编码门禁 |
+|---|---|---|
+| 纯显示文案且满足全部豁免条件 | 无原型 | 完成最小界面检查即可 |
+| 现有界面的小范围样式或布局调整 | 标注截图或低保真线框图；没有设计不确定性时说明复用的现有规范 | 工单确认设计证据后编码 |
+| 新组件但复用现有设计体系 | 组件状态、错误和边界说明；按需提供低保真图 | 工单确认状态和复用边界后编码 |
+| 新页面、独立用户功能、重大交互或导航变化 | Quant-UX 或其他合适工具制作的可审阅原型 | 用户确认原型和文字需求后才能编写生产代码 |
+| 后端、接口、数据处理或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后编码，不制作无意义的 UI 原型 |
+| 恢复既有确认行为的 Bug | 原设计、已确认截图、复现步骤或现有验收证据 | 确认是恢复而不是改变行为后修复 |
+
+采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。
+
+### 线上原型审核与按需导出
+
+新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，默认直接通过线上原型审核，不要求每次导出本地 HTML：
+
+- 可编辑设计源保存在 Quant-UX 或原设计工具；工单和 Wiki 只保存链接、版本与确认记录，不复制为第二份可编辑事实来源。
+- 线上链接必须能被确认人访问，并能通过版本、revision、复制版本或确认日期识别本次审核对象；无法访问或无法区分版本时停止审核，等待用户确认等效方案。
+- 提交审核前检查主要页面、流程、状态和交互可访问，并删除令牌、真实账号、个人信息和生产数据。
+- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，更新线上原型并重新确认；不得用旧确认覆盖新版本。
+- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 仍只使用双门禁表规定的最低证据，不强制建立完整线上原型。
+
+只有用户明确发出 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线交付时，才导出本地 HTML：
+
+- 指定工单的快照放入 `prototypes/<工单号>/<版本>/index.html`；全部导出时也按工单和版本分目录，先在工单明确导出范围。
+- 图片、样式、脚本和字体使用版本目录内的相对路径；需要网络资源才能显示时不得标记为可离线浏览。
+- 已确认的本地快照不得原位覆盖；新版本使用新目录，已有快照继续作为历史审核证据。
+- 导出后检查入口、主要交互和资源完整性；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。
+- 导出指令只生成或更新请求范围内的快照并报告结果，不自动提交；用户未明确要求时不得顺带导出其他原型。
+- 设计工具无法生成用户要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型仍可访问且版本明确时，不因此阻塞线上审核。
+
+### 记录和重新确认
+
+需要设计证据的工单必须记录：
+
+- 原型或设计的线上链接、对应事实来源，以及链接可访问性；
+- 版本、revision、复制版本或确认日期，以及审核版本的识别方式；
+- 状态：无、草稿、已确认或已废弃；
+- 只有显式导出时才记录本地 HTML 路径、版本和资源检查结果；
+- 确认人和确认时间；
+- 本次确认覆盖的页面、组件、流程和边界；
+- 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。
+
+页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新原型或文字需求并重新确认，再继续正式编码。只读技术检查可以在确认前进行；确需可行性代码验证时，必须由用户明确同意，隔离为不可进入生产的技术验证，不得悄悄扩展成正式实现。
 ## 一次任务怎样完成

 ### 1. 讨论
@@ -67,35 +151,50 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新
 - Git 提交哈希；
 - 相关 Wiki 页面及 revision。

-长期文档遵循唯一顺序：
+工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。
+
+只有长期事实发生变化时才执行核心文档闭环：

 ```text
-修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
+修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像
 ```

-不得先编辑 `docs/` 再反向覆盖 Wiki。
+没有长期文档影响时，在工单写明原因并跳过 Wiki 更新和核心镜像同步；默认任务流程不创建任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。

 ### 4. 待验收

 实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。

-### 5. 归档和关闭
+### 5. 待验收和关闭

-使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像：
+实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。
+
+用户明确验收通过后：
+
+1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据；
+2. 关闭单元工单并勾选所属 MVP/Epic 子任务；
+3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki；
+4. 默认不创建或导出任务归档。
+
+任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行：

 ```powershell
-python dev_scripts/new_task_archive.py 123 "修复登录超时"
+python dev_scripts/harness.py archive 123 "修复登录超时"
+python dev_scripts/harness.py export        # 增量导出已有归档
+python dev_scripts/harness.py export --all  # 全量导出已有归档
 ```

-归档内容以 Wiki 页面为主源；本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
+可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。

 ## 文档同步规则

- 映射保存在 `wiki-docs.json`，每个 Wiki 页面对应唯一仓库路径。
- 同步脚本只实现 Wiki → `docs/`，不提供反向同步。
+- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。
+- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。
+- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。
 - 镜像头必须记录页面名、页面地址、revision 和同步时间。
 - 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
- `--check` 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。
+- 核心同步的 `--check` 只检查核心镜像，不要求线上任务归档全部存在于本地。
+- 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
 - 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
 - Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
 - 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
@@ -129,6 +228,8 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 - 业务规则、安全边界或权限变化；
 - 日志位置、错误定位或常见处理方式变化。

+部署命令的落点：有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由[部署文档模板](Deployment-Template.-)复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。
+
 普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。

 ## 需求记录与流转
@@ -149,20 +250,20 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 |
 | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 |
 | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` |
-| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | `docs/task/` |
+| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 |

 任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。

-## 稳定文档与任务归档
+## 稳定文档与可选历史快照

 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。
- 新人先读稳定主题页，只有追查历史原因时才读任务归档。
- 任务产生的长期结论必须合并到主题页，不能只留在归档。
+- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。
+- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。
+- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。

 ## 效率与范围控制

-本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。
+本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。

 ### 严格控制范围

@@ -200,20 +301,26 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 |---|---|---|
 | `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 |
 | `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 |
-| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” |
+| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” |
 | `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
 | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
 | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
-| `同步文档` | 读取 Wiki，导出已映射的 `docs/` 镜像并检查一致性 | 显示结果和差异；不修改 Wiki、不自动提交 |
-| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，导出并提交镜像，推送、同步父工单并关闭任务 | 工单“已完成”并关闭 |
+| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 |
+| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本；按工单和版本写入 `prototypes/` | 显示路径和检查结果；不扩展范围、不自动提交 |
+| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果；不自动提交 |
+| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
+| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
+| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 |

 补充边界：

 - 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。
 - 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
- `同步文档` 发现镜像有未提交改动时停止，不覆盖现有修改。
- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存 Wiki 最终任务归档的镜像。
+- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
+- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。
+- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。
+- Gitea 工单是单次任务唯一事实来源，不导出全文；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。

 ## 什么时候重新确认方案

@@ -235,8 +342,9 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 | 讨论过程和临时方案 | 是 | 否 | 否 |
 | 实施进度和阻塞 | 是 | 否 | 否 |
 | 长期有效的最终方案 | 链接 | 是 | 镜像 |
-| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 |
-| 提交哈希 | 是 | 任务归档 | 镜像 |
+| 测试结果与未验证内容 | 是 | 否 | 否 |
+| 提交哈希和验收结论 | 是 | 否 | 否 |
+| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 |
 | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |

 ## go-admin / go-admin-ui 开发约束
@@ -2,8 +2,8 @@
 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: 8df12aa3e136b1faee9c2dffb58ca39b045bc49f
-synchronized_at: 2026-08-17T02:54:44Z
+wiki_revision: ee5b5507bf8a8a834e07f223f1a90c2f67a70d6f
+synchronized_at: 2026-08-27T09:14:31Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -35,9 +35,9 @@ Bell 也可接收合成事件、传感器平台或第三方系统事件；Sense
 | Brain 推理 | `Brain/` | `Brain/AGENTS.md`；后续包入口 | `Brain/` 内测试与契约测试 | 高：模型、GPU、隐私、事件语义 |
 | Bell 产品 | `Bell/` | `Bell/AGENTS.md`；待 GoAdmin 派生工单建立 README/入口 | 待新骨架建立 | 高：GoAdmin 派生、认证、事件与告警状态机 |
 | 共享契约 | `contracts/` | `contracts/AGENTS.md` | 三端消费者/生产者测试 | 高：兼容性与跨项目影响 |
-| Harness | `dev_scripts/` | `check_harness.py` | `tests/` | 中 |
+| Harness | `dev_scripts/` | `harness.py check --strict` | `tests/` | 中 |
 | 工单模板 | `.gitea/issue_template/` | `task.md` | Harness 严格检查 | 中 |
-| Wiki 镜像 | `docs/` | `docs/README.md` | `sync_wiki_docs.py --check` | 低；禁止直接编辑 |
+| Wiki 镜像 | `docs/` | `docs/README.md` | `harness.py sync --check` | 低；禁止直接编辑 |

 旧 Sense、Bell 入口仅存在于 `explore` 快照，不是 `main` / `dev` 当前代码地图。三个项目的新入口必须随新骨架工单建立；不得把旧自研基础框架复制回 `dev`。

@@ -142,3 +142,11 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea

 交付包同时提供检查、迁移、管理员初始化、停止、备份和恢复入口。停止脚本只操作当前包且监听配置端口的 Sense 进程树；备份密码只进入子进程环境；恢复要求数据库名和二次短语确认。包不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。
 <!-- sense-windows-delivery:end -->
+
+
+## DevHarness 执行路径
+
+- `dev_scripts/harness.py check --strict` 检查核心结构、YoVision GoAdmin 基线和项目规则。
+- `dev_scripts/harness.py sync` 只从 Gitea Wiki 导出 `wiki-docs.json` 映射的核心镜像；`sync --check` 只检查一致性。
+- `archive`、`export` 和 `export --all` 只在人工明确要求时处理可选任务快照，任务快照不进入核心映射。
+- `dev_scripts/wiki_docs.py` 负责 Gitea Wiki 读取、revision、镜像头、脏文件保护和安全路径校验。
@@ -2,8 +2,8 @@
 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: 2bcd90c508180eb9a2f9fe37b62115d7d9207e18
-synchronized_at: 2026-08-15T01:13:04Z
+wiki_revision: 96fca4d2aa411725282bd3911c133efc75f7146a
+synchronized_at: 2026-08-27T09:04:59Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -146,3 +146,11 @@ synchronized_at: 2026-08-15T01:13:04Z
 - 鼠标可点击/拖动顶点；键盘必须能添加、移动和删除顶点。错误在绘制区域附近以可被辅助技术感知的文字给出，并提供撤销、清空和未保存关闭确认。
 - 区域配置是 Sense 内部事实；#69 不发布 Brain 契约。后续 Sense→Brain 配置协议必须由独立协调工单从当前版本投影生成，不能共享数据库模型。
 <!-- sense-area:end -->
+
+
+## DevHarness 任务证据边界
+
+- Gitea 工单正文与评论是单次任务的需求、变化、实现、测试、提交和验收事实来源。
+- Gitea Wiki 只保存长期有效的项目事实；核心页面由 `wiki-docs.json` 显式映射。
+- `docs/task/` 是按人工明确要求形成的专项或历史兼容快照，可能不完整或不是最新状态，不得替代工单。
+- 默认不创建、导出或更新任务快照；导出过程不自动删除本地历史文件。
@@ -2,8 +2,8 @@
 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: 925a16a72bd5840697b5c61489a97018134b3930
-synchronized_at: 2026-08-27T08:07:04Z
+wiki_revision: 7ede95108304cec08572d9da5ce1f41116e4970d
+synchronized_at: 2026-08-27T09:05:09Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -19,6 +19,12 @@ synchronized_at: 2026-08-27T08:07:04Z

 Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/CUDA 以及 PostgreSQL、MediaMTX 精确版本仍将在对应骨架工单冻结。旧仓库环境不自动成为新项目事实。

+## Windows PowerShell 与 UTF-8
+
+- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不为设置编码重复启动一层 PowerShell。
+- 文本文件读写在命令支持时显式指定 UTF-8。文件解码与控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才调整当前进程输出编码或 Python UTF-8 环境变量。
+- 不默认使用 `-ExecutionPolicy Bypass`。只有可信脚本确实被策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。
+
 ## 第一次运行

 1. 检查工作区：
@@ -32,7 +38,7 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的
 2. 检查 Harness：

   ```powershell
-   python dev_scripts/check_harness.py --strict
+   python dev_scripts/harness.py check --strict
   ```

   预期：输出“DevHarness 检查通过”。
@@ -48,7 +54,7 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的
 4. 对照 Wiki：

   ```powershell
-   python dev_scripts/sync_wiki_docs.py --check
+   python dev_scripts/harness.py sync --check
   ```

   预期：全部映射一致。
@@ -81,8 +87,8 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的

 ```powershell
 python -m unittest discover -s tests -v
-python dev_scripts/check_harness.py --strict
-python dev_scripts/sync_wiki_docs.py --check
+python dev_scripts/harness.py check --strict
+python dev_scripts/harness.py sync --check
 git diff --check
 git status --short
 ```
@@ -2,8 +2,8 @@
 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
+wiki_revision: becaa9f08fd07397da516c31e3d93362626df050
+synchronized_at: 2026-08-27T09:05:21Z
 <!-- gitea-wiki-mirror:end -->

 # 常见修改指南
@@ -20,15 +20,15 @@ synchronized_at: 2026-08-11T10:30:43Z
 | 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 |
 | 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |

-“代码行数少”不等于低风险。
+“代码行数少”不等于低风险。风险等级只决定由谁实施和验证，不改变建单门禁：新功能、缺陷修复、重构及行为变化仍需工单；只有 AGENTS.md 明确列出的非行为修改和纯显示文案豁免可以直接提交。

 ## 修改 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`。
+4. 运行 `python dev_scripts/harness.py sync`。
+5. 运行 `python dev_scripts/harness.py sync --check`。
 6. 审查本地镜像差异并提交。

 停止条件：页面需要删除、重命名或改变事实源边界。
@@ -45,7 +45,7 @@ synchronized_at: 2026-08-11T10:30:43Z

 ## 调整 Harness 检查

-1. 从 `dev_scripts/check_harness.py` 的 `main()` 开始读。
+1. 从 `dev_scripts/harness.py` 的 `run_check()` 开始读。
 2. 新检查应输出具体文件和缺失内容。
 3. 检查结构事实，不声称自动判断文档语义质量。
 4. 在 `tests/` 添加成功和失败用例。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: 1a452e9aafdfe01580f37f9179584b89516cf992
-synchronized_at: 2026-08-15T07:59:38Z
+wiki_revision: 046624c1b2d7963ef733b4c9687d5dec14771388
+synchronized_at: 2026-08-27T09:05:32Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -152,3 +152,12 @@ synchronized_at: 2026-08-15T07:59:38Z

 如果迁移报告不支持的唯一性结构，不要手工删除约束或路由；在备份副本中核对实际约束和业务数据。正式迁移失败时保留错误并从迁移前备份恢复，不通过关闭唯一性绕过迁移。
 <!-- sense-media-path-constraint:end -->
+
+
+## DevHarness 同步排错
+
+1. 先运行 `python dev_scripts/harness.py check --strict` 定位结构或项目规则问题。
+2. 镜像不一致时运行 `python dev_scripts/harness.py sync --check`；不得直接修改 `docs/` 后反向覆盖 Wiki。
+3. 若同步提示本地镜像有未提交修改，先核对改动归属并停止覆盖。
+4. Wiki 页面缺失、没有 revision、MCP/API 凭据不可用或映射准备删除/重命名时停止，由工单确认后处理。
+5. PowerShell 显示乱码时先区分文件编码和控制台输出编码，不默认另起 PowerShell 或使用 `-ExecutionPolicy Bypass`。
@@ -2,8 +2,8 @@
 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
+wiki_revision: 66d63c1e43de4dc54bb7c16ec6eb462a07bab15c
+synchronized_at: 2026-08-27T09:05:42Z
 <!-- gitea-wiki-mirror:end -->

 # 新项目文档初始化
@@ -26,7 +26,81 @@ synchronized_at: 2026-08-11T10:30:50Z

 把项目专用红线写入根目录或子目录 `AGENTS.md`。

-### 2. 识别子项目与交付单元
+#### 需求总览启用条件
+
+从模板创建项目时保留 Product-Requirements-Overview 这一核心页面。仅有探索性想法时可以只记录已确认目标和待确认项；形成 MVP、长期需求超过少量工单或开始制作原型时，必须建立并持续维护需求索引，把需求领域、状态、主题 Wiki、工单、原型和验收入口关联起来。不要复制完整工单或聊天记录。
+
+### 2. 选择建设基线
+
+确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。
+
+至少检查：
+
+- 核心功能、架构和支持平台是否匹配，哪些能力可以直接保留；
+- 许可证是否允许预期的使用、修改、分发和商业模式；不确定时交由负责人或法律专业人员确认；
+- 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性；
+- 已知安全问题、依赖健康度、供应链风险和安全响应方式；
+- 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护；
+- 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发；
+- 是否能够固定上游仓库和基线版本，并建立合并上游更新、兼容验证和退出方案。
+
+满足适配、许可证、安全、维护和总成本条件时，优先在该基线上二次开发。不存在合适基线，或引入后会增加不可接受的许可证、安全、架构或维护风险时，可以从零开发，但必须记录排除候选项目和选择从零开发的主要原因。
+
+采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。
+
+#### 工程基线裁剪
+
+所有项目采用最小工程基线，不按项目规模免除事实和验收要求：
+
+- 用完整 Git commit 和核验日期固定“当前事实”的代码基线；
+- 分开记录“当前已经实现什么”和“目标规范要求什么”，不得用目标描述宣称现有能力；
+- 写明证据路径、可确认行为、未覆盖范围和证据不能证明什么；
+- 明确目标、非目标、安全边界和可判定的验收标准；
+- 跨子项目接口或契约指定唯一事实来源和各端验证命令。
+
+当前事实以指定 commit 的代码、可执行测试和运行证据为依据；目标行为以人工批准的契约、ADR 和业务规则为依据。两者冲突时登记为带编号的差距或缺陷，不允许现有错误实现覆盖目标规范，也不允许目标设计冒充当前实现。
+
+出现跨团队或跨仓库协作、外部交付、接口或状态机复杂、权限安全、迁移并发、明显文档漂移等情况时，采用增强工程基线：按需增加 GAP-ID 差距表、带状态的 ADR、接口与数据契约、需求追踪测试矩阵，以及 PR、RC、Definition of Done 分层门禁。SRS、SAD、安全、运维和测试文档按风险与读者选择，不强制小型单人项目建立完整文档集。
+
+#### 判断案例
+
+以下案例用于说明判断方式，不代表必须选择某种技术或具体开源项目。
+
+##### 案例一：适合基于成熟项目二次开发
+
+计划开发企业内部管理系统。候选项目已经具备用户、权限、审计日志、基础数据管理和自动化测试；功能与目标架构基本匹配，许可证允许预期使用，项目持续维护，发布与升级流程完整，预计只需修改业务模块和界面。
+
+- 结论：优先基于该项目二次开发。
+- 原因：可以减少通用功能的开发和验证成本，定制范围可控。
+- 记录：上游仓库、基线版本、许可证、保留功能、定制模块和上游升级方式。
+
+##### 案例二：项目成熟但许可证不兼容
+
+候选项目功能完整、维护活跃、文档充分，但许可证与当前产品的闭源分发、商业模式或交付条件不兼容。
+
+- 结论：不采用该项目作为建设基线。
+- 原因：技术成熟度不能消除许可证风险；不确定结论必须交由负责人或法律专业人员确认。
+- 记录：候选项目、许可证限制、确认人员和排除原因。
+
+##### 案例三：功能相似但改造成本过高
+
+候选项目表面上覆盖大部分功能，但数据模型、权限体系和部署结构与目标项目差异很大，需要大量删除模块、重写主要接口，并长期维护上游冲突。
+
+- 结论：不直接基于完整项目二次开发，可以评估只复用合适的组件或设计思路。
+- 原因：二次开发的总成本、理解成本和长期维护风险已经高于自主实现核心业务。
+- 记录：主要结构差异、改造估算、长期维护风险和最终选择。
+
+##### 案例四：只复用成熟框架或组件
+
+没有功能高度匹配的完整开源产品，但存在成熟的应用框架、更新组件、日志组件或通信库。
+
+- 结论：从零开发业务功能，同时复用经过评估的成熟框架或组件。
+- 原因：复用基础能力不等于必须采用完整产品，可以避免被不匹配的业务架构绑定。
+- 记录：每个依赖的用途、版本、许可证、安全边界、升级方式和可替换方案。
+
+每个案例的实际评估都必须记录候选项目、判断依据、最终选择、未采用原因，以及升级或退出方式。
+
+### 3. 识别子项目与交付单元

 先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认：

@@ -40,19 +114,21 @@ synchronized_at: 2026-08-11T10:30:50Z

 把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。

-### 3. 建立 Gitea
+### 4. 建立 Gitea

-创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。
+创建远端仓库并完成允许的初始引导提交，开启工单和 Wiki；必须先有远端仓库，才能填写该仓库的线上 Wiki。配置项目已有的 Gitea MCP 和安全凭据；优先使用 MCP，MCP 不可用或不支持所需写操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只通过环境或 MCP 安全配置提供。

-### 4. 修改镜像配置
+任何产品功能开发在引导提交后都必须先有单元任务工单，并且必须通过第 8 步的线上 Wiki 初始化门禁。

-把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；核心主题映射保留。
+### 5. 修改镜像配置

-确认当前目录确实是新项目副本、且 DevHarness 历史归档不需要保留后，移除属于 DevHarness 的任务归档映射和对应 `docs/task/` 镜像。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。
+把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射。可选任务快照不逐页登记，默认任务流程不创建。
+
+确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。

 不要把 PAT 写入配置。

-### 5. Agent 检查项目事实
+### 6. Agent 检查项目事实

 Agent 只读检查：

@@ -65,7 +141,7 @@ Agent 只读检查：

 区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。

-### 6. 确定交付对象和文档
+### 7. 确定交付对象和文档

 由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定：

@@ -77,25 +153,36 @@ Agent 只读检查：

 按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。

-### 7. 先创建线上 Wiki
+### 8. 先创建线上 Wiki
+
+#### 在线创建与回读门禁
+
+1. 使用配置好的 Gitea MCP 查询目标仓库的 Wiki 页面列表；MCP 不可用时使用 Gitea API，并记录回退原因。
+2. 如果 `Home` 不存在，先创建 `Home`。创建后立即在线回读正文并记录 revision；`Home` 可读取后才能继续。
+3. 依照 `wiki-docs.json` 逐页创建或更新其他核心页面。每页写入后在线回读正文，记录页面名和 revision。
+4. 本地 `docs/` 是模板或 Wiki 镜像；本地文件存在、标题完整或 `harness.py check --strict` 通过，都不能单独证明线上 Wiki 已初始化。
+5. 页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码；Gitea 恢复后从首个失败页面继续。

 至少创建或填写：

 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。
+3. Product-Requirements-Overview；
+4. Architecture-and-Code-Map；
+5. Business-Rules-and-Glossary；
+6. Local-Development-and-Verification；
+7. Common-Changes；
+8. Troubleshooting；
+9. Development-Workflow；
+10. Delivery-Documentation-Guide；
+11. Audience-Document-Template；
+12. Task-Archive-Template。

-Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。
+Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。

-### 8. 人工确认
+部署页按需创建，不属于必需核心页面：项目负责人确认存在需要部署的常驻服务时，复制[部署文档模板](Deployment-Template.-)在本项目 Wiki 建立 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）；确认没有常驻服务时，在初始化工单记录原因，不创建该页面。
+
+### 9. 人工确认

 项目负责人至少确认：

@@ -103,29 +190,33 @@ Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图
 - 关键业务规则和状态；
 - 权限、安全和数据边界；
 - 真实运行、测试和部署命令；
+- 本项目是否有需要部署的常驻服务；
 - 哪些修改属于高风险；
 - 交付对象、文档可见范围和外部信息边界。

-### 9. 导出镜像并检查
+### 10. 导出镜像并检查

 ```powershell
-python dev_scripts/sync_wiki_docs.py
-python dev_scripts/check_harness.py --strict
-python dev_scripts/sync_wiki_docs.py --check
+python dev_scripts/harness.py sync --verify
 python -m unittest discover -s tests -v
 ```

-只有线上 Wiki 确认后才导出 `docs/`。旧项目的任务归档不能带入新项目历史。
+只有线上 Wiki 确认后才导出核心 `docs/`。默认不创建或导出任务归档；用户明确要求专项快照时才运行 `archive`、`export` 或 `export --all`。旧项目的任务归档快照不能带入新项目历史。
+
+`harness.py sync --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。

 ## 完成标准

 初级程序员应能仅依靠 Home 和链接页面回答：

 - 项目解决什么问题；
+- 当前有哪些长期需求、状态如何，详细规则、工单、原型和验收入口在哪里；
 - 怎样启动和运行测试；
 - 常用功能从哪个目录和入口开始读；
 - 一个简单修改通常要改哪里、验证什么；
 - 哪些情况必须停止并交给 Agent 或负责人；
+- 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发；
+- 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么；
 - 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布；
 - 跨子项目共享什么接口或契约，其唯一事实来源在哪里；
 - 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。
@@ -2,8 +2,8 @@
 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
+wiki_revision: 54e7c774b679f582d210c08179de31d6e12ed9b4
+synchronized_at: 2026-08-27T09:05:54Z
 <!-- gitea-wiki-mirror:end -->

 # 已有项目接入 DevHarness 指南
@@ -23,7 +23,7 @@ synchronized_at: 2026-08-11T10:30:53Z
 | 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 |
 | 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 |
 | Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 |
-| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 |
+| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 |
 | 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 |

 从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。
@@ -71,7 +71,7 @@ Agent 在提出方案前只读检查：
 - 多个应用共同完成一条产品或业务链路；
 - 由同一团队维护，仓库权限基本一致；
 - 接口变更需要在一个工单中同步修改或验证多端；
- 共享契约、业务规则和任务归档放在一起更容易保持一致；
+- 共享契约和业务规则由同一项目维护并指定唯一事实来源；
 - 仓库体积、测试时间和工具性能尚未明显影响开发；
 - 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。

@@ -131,7 +131,42 @@ Agent 在提出方案前只读检查：

 ### 7. 提交和验收

-提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。
+提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 Wiki revision 或“无长期文档影响”；保持工单“待验收”，等待用户明确验收后再关闭。默认不创建任务归档。
+
+## 后续升级
+
+已接入的项目必须以 Project-Profile 中记录的 DevHarness 来源和当前基线为起点升级，不得重新复制整个模板，也不得用“最新版本”代替可复现的目标提交。
+
+### 升级步骤
+
+1. 读取目标项目的 Project-Profile，确认 DevHarness 来源仓库、当前基线完整提交、最后升级日期和项目适配说明；字段缺失时先补齐可验证事实，无法确认则停止。
+2. 选择一个明确、已审阅的 DevHarness 目标提交，记录旧基线和新基线。先比较两个上游提交之间的变化，再判断这些变化如何作用于目标项目。
+3. 只读比较与 Harness 有关的 `AGENTS.md`、`CLAUDE.md`、工单模板、`dev_scripts/`、Harness 测试和核心 Wiki 结构，把差异分为“直接采用、按项目改写、冲突待确认、不采用”。不得把 DevHarness 的项目事实、工单或任务归档带入目标项目。
+4. 在目标项目建立单元任务工单，写明升级范围、差异分类、项目专用规则、风险、回退、验证和文档影响。会改变产品行为的内容必须拆成独立任务。
+5. 按工单最小合并，保留目标项目更具体的业务、安全、权限和目录规则，以及 Git 历史和无关工作区修改。无法判断哪一方规则有效时停止并等待负责人确认。
+6. 长期文档先更新目标项目 Wiki，读取确认后再同步目标项目的核心 `docs/` 镜像；不得用 DevHarness 的本地镜像覆盖目标项目文档。
+7. 执行目标项目规定的必要检查和受影响测试，提交并回写证据。工单保持“待验收”。
+8. 用户验收通过后，确认目标项目 Project-Profile 已记录新 DevHarness 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。
+
+### 升级停止条件
+
+除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。
+
+### 可复制升级指令
+
+```text
+请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到
+<DevHarness 目标完整提交哈希>。
+
+先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目
+适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及
+风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git
+历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在
+当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。
+工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。
+```
+
+路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。

 ## 冲突处理和停止条件

@@ -175,8 +210,8 @@ Agent 在提出方案前只读检查：

 严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、
 任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出
-本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持
-为“待验收”；未经我明确验收，不关闭工单。
+本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后
+保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。
 ```

 路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。
@@ -192,7 +227,7 @@ Agent 在提出方案前只读检查：
 - [ ] 已为每类长期文档明确事实来源和迁移状态。
 - [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。
 - [ ] Harness 检查已按目标项目调整并通过。
- [ ] 必要测试、未验证部分、提交和归档证据已记录。
+- [ ] 必要测试、未验证部分、提交和最终证据已记录。
 - [ ] 工单处于待验收，未提前关闭。

 ## 回退原则
@@ -2,12 +2,63 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Product-Requirements
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Requirements.-
-wiki_revision: e6c6e0d7f658a7c1040fe569026e7d0ec581701a
-synchronized_at: 2026-08-17T02:54:53Z
+wiki_revision: e912a1ca1410e01680a0f11f6199ccb42cd8fe8f
+synchronized_at: 2026-08-27T09:06:08Z
 <!-- gitea-wiki-mirror:end -->

 # 产品需求

+## 本页用途
+
+本页同时承担 YoVision 产品需求正文与需求总览索引，保留已经确认的 Sense、Brain、Bell 和跨项目要求，不因 DevHarness 升级重命名或拆分事实源。
+
+## 事实来源边界
+
+- 长期产品目标、边界和稳定需求记录在本页。
+- 单次任务的范围、变化、实现和验收记录在对应 Gitea 工单。
+- 原型用于确认页面、流程与交互，不替代正式需求和验收标准。
+
+## 当前需求索引
+
+- 产品边界：PR-BND-001～PR-BND-003。
+- Sense：SEN-001 起，按 P0、P1/P2 管理。
+- Brain：BRN-001 起，按 P0、P1/P2 管理。
+- Bell：BEL-001 起，按 P0、P1/P2 管理。
+- 跨项目与非功能要求：见本页第 6 节及对应协调工单。
+
+## 登记规则
+
+新增或变化的长期需求必须有来源、状态、所属产品、优先级和验收边界；会改变已确认结果时先更新工单并重新取得用户确认。
+
+## 原型与设计资产
+
+### 原型门禁
+
+新页面、独立用户功能、重大交互或导航变化必须先形成可审阅原型；小范围 UI 使用标注截图、低保真图或明确复用规范；非 UI 任务使用架构、API、数据、状态或流程设计。
+
+### 线上原型与按需 HTML 快照
+
+默认使用可访问且版本明确的线上原型审核。只有用户明确要求或项目规则要求时，才导出 `prototypes/<工单号>/<版本>/index.html`；已确认快照不得原位覆盖。
+
+### 原型确认记录
+
+实现工单记录设计链接或路径、版本/revision、访问检查、确认人、确认时间和覆盖范围。结构、流程、状态、权限或异常处理发生实质变化时必须重新确认。
+
+## 状态规则
+
+需求使用拟议、已确认、实施中、已交付、已废弃等状态；工单状态仍按待确认、待实施、进行中、阻塞、待验收、已完成管理，两者不得混用。
+
+## 更新时机
+
+产品边界、长期业务规则、需求优先级或验收边界变化时更新本页；单次实现细节、测试日志和提交哈希只写工单。
+
+## 最小验收清单
+
+- 需求有稳定编号、所属产品、优先级、来源和验收边界。
+- 跨项目需求只有一个契约或协调事实源。
+- 需要原型的变更已有可访问、可识别版本并完成确认。
+- 不包含密码、令牌、生产数据或完整聊天记录。
+
 ## 1. 产品范围与优先级

 YoVision 首个可交付目标是在民办寄宿学校以默认 16 路高风险点位形成完整闭环：
@@ -2,55 +2,100 @@
 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
+wiki_revision: 8ba2aba01f287ec5ab9cafda3d719bfd9e7fc459
+synchronized_at: 2026-08-27T09:04:13Z
 <!-- gitea-wiki-mirror:end -->

 # YoVision 文档中心

-YoVision 是单仓三项目的智能视频事件平台。Sense 负责设备与媒体，Brain 负责推理与事件生成，Bell 负责事件预警和处置。Sense 与 Bell 是可独立销售、部署和验收的产品；Brain 是独立构建的推理交付单元。
+DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。

 ## 第一次阅读

-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.-)：建单、确认、实施、验收和归档。
+建议按以下顺序，用 10～20 分钟建立整体认识：
+
+1. [项目档案](Project-Profile.-)：项目目标、环境、命令和目录边界。
+2. [产品需求总览](Product-Requirements-Overview.-)：长期需求、状态、原型和验收入口。
+3. [架构与代码地图](Architecture-and-Code-Map.-)：功能从哪里开始读、测试在哪里。
+4. [业务规则与术语](Business-Rules-and-Glossary.-)：重要名词、状态和不能破坏的规则。
+5. [本地开发与验证](Local-Development-and-Verification.-)：怎样运行、测试和排错。
+6. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。
+7. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。
+8. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和可选快照流程。
+
+从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)；向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。

 ## 五分钟开始

+在仓库根目录执行：
+
 ```powershell
 git status --short --branch
-python dev_scripts/check_harness.py --strict
+python dev_scripts/harness.py check --strict
 python -m unittest discover -s tests -v
-python dev_scripts/sync_wiki_docs.py --check
+python dev_scripts/harness.py sync --check
 ```

-预期：工作区变更归属清楚，Harness 与测试通过，Wiki 镜像一致。业务代码尚未初始化时，不应臆造 Sense、Brain 或 Bell 的构建命令。
+预期结果：
+
+- 工作区没有不属于当前任务的修改；
+- Harness 输出“DevHarness 检查通过”；
+- 所有单元测试通过；
+- 所有 Wiki 映射显示“一致”。
+
+如果失败，先看[故障排查](Troubleshooting)，不要直接重置工作区或覆盖本地文档。

 ## 简单修改从哪里开始

-| 修改类型 | 先读 | 主要验证 |
+| 想做什么 | 先读哪里 | 主要验证 |
 |---|---|---|
-| 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 同步检查 |
+| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
+| 查看或更新产品需求 | Product-Requirements-Overview、对应主题 Wiki 和工单 | 状态、链接和事实来源核对 |
+| 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 |
+| 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 |
+| 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 |
+| 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 |
+| 增加结构检查 | `dev_scripts/harness.py` | 成功与失败测试 |
+| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 |
+
+权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。

 ## 事实来源

 | 信息 | 事实来源 |
 |---|---|
-| 实时任务状态、方案确认和验收过程 | Gitea 工单 |
-| 长期需求、架构、规则、操作与归档 | Gitea Wiki |
-| API/Schema/迁移及代码版本事实 | Git 仓库 |
-| 离线文档 | `docs/` Wiki 只读镜像 |
-| 历史需求和旧证据 | `D:\OPC\yovision_old`，只读参考，不是当前状态 |
+| 任务状态、讨论、阻塞、验收过程 | Gitea 工单 |
+| 长期产品需求的统一导航和状态 | Gitea Wiki 的 Product-Requirements-Overview |
+| 架构、业务规则、开发规范、操作手册和交付文档 | Gitea Wiki |
+| 源码和与特定代码版本强绑定的文档 | Git 仓库 |
+| 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |
+| 单次任务需求、实现、测试和验收 | Gitea 工单；专项 Wiki 快照仅在人工明确要求时创建 |
+
+本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。
+
+## 项目入口
+
+- [Gitea 工单](https://git.ilapage.cn/OPC/dev_harness/issues)
+- [产品需求总览](Product-Requirements-Overview.-)
+- [代码仓库](https://git.ilapage.cn/OPC/dev_harness)
+- [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)
+- [交付文档指南](Delivery-Documentation-Guide.-)
+- [岗位文档模板](Audience-Document-Template.-)
+- [可选任务归档模板（兼容）](Task-Archive-Template.-)
+
+## 同步原则
+
+```text
+修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
+```
+
+- 核心页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射；普通同步不处理任务归档。
+- 默认不创建任务归档；只有用户明确要求专项快照或项目专用规则要求时，才创建 Wiki 归档并按需导出到 `docs/task/`。
+- 镜像头记录来源页面、Wiki revision 和同步时间。
+- 已映射镜像存在未提交修改时同步必须停止。
+- 页面删除、重命名和映射变更必须人工确认。
+- 长期事实发生变化而核心 Wiki 或必要同步失败时，相关任务不能标记为完成；没有长期文档变化时不运行 Wiki 同步，未请求可选归档不阻止任务完成。
+- 凭据、个人数据和生产数据不得进入 Wiki 或镜像。

 ## 项目入口

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Delivery-Documentation-Guide
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.-
-wiki_revision: 3d95c9d392e81cf59d2af1f6f21d8e67f580b68f
-synchronized_at: 2026-08-15T03:02:47Z
+wiki_revision: 5b295898612f86ac2301ea243df76fb284912317
+synchronized_at: 2026-08-27T09:06:55Z
 <!-- gitea-wiki-mirror:end -->

 # 交付文档指南
@@ -79,7 +79,6 @@ synchronized_at: 2026-08-15T03:02:47Z

 开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。

-<!-- sense-mvp:start -->
 ## Sense MVP 岗位操作路径

 Sense 面向网管、实施人员和非技术现场人员，菜单按日常任务组织：工作台 → 设备管理 → 视频接入 → 视频服务 → 实时监看 → 区域与警戒线。普通操作优先展示中文状态与下一步，不要求用户理解 ONVIF、RTSP 或 MediaMTX 内部模型。
@@ -134,3 +133,7 @@ Sense 面向网管、实施人员和非技术现场人员，菜单按日常任
 <!-- sense-media:end -->

 <!-- sense-admission:end -->
+
+## 部署与运维文档
+
+YoVision 已有 Sense Windows 交付包和本机 Supervisor 常驻实例，因此维护 `Deployment-and-Operations` 页面。部署命令、服务身份、配置来源、端口、日志、启动停止、回退或升级方式变化时必须先更新该 Wiki 页面，再同步本地镜像。
@@ -0,0 +1,82 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Deployment-and-Operations
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.-
+wiki_revision: 367c6aed6eaeece793622431c7d1b11b1b9dbec5
+synchronized_at: 2026-08-27T09:07:20Z
+<!-- gitea-wiki-mirror:end -->
+
+# YoVision 部署与运维
+
+## 文档信息
+
+- 系统：YoVision
+- 当前常驻实例：Sense
+- 适用环境：Windows 本机开发/验收与 Sense Windows 交付包
+- 维护入口：工单 #108 后由长期 Wiki 持续维护
+- 安全边界：本文不记录数据库密码、管理员密码、摄像头凭据、JWT/会话密钥或 Gitea token
+
+## 部署范围与边界
+
+当前可核对的常驻服务是 Sense。Brain 尚未初始化，Bell 新 GoAdmin 基线尚未完成，因此不在本页提供虚构的生产部署命令。三个交付单元保持独立配置、数据、身份、版本和发布边界；跨项目编排必须另建协调工单。
+
+## 目录与入口
+
+- Sense 项目目录启动入口：`Sense\start_sense.bat`
+- Windows 交付包：`Sense\dist\sense-windows-amd64`
+- 包内启动入口：`Sense\dist\sense-windows-amd64\start-sense.bat`
+- 包内配置：`Sense\dist\sense-windows-amd64\config\sense.env`
+- 项目配置源：`Sense\config\sense.env`
+- 构建入口：`Sense\scripts\build\build-windows.bat`
+- 本机 Supervisor 根目录：`D:\supervisor`
+
+`Sense\start_sense.bat` 只定位并调用交付包入口、透传参数和退出码；它不读取配置、不自动构建，也不直接启动 Go 或 Node 开发服务。MediaMTX 是否随包启动由 Sense 包内运行脚本和配置控制。
+
+## 配置与秘密
+
+- 生产模式必须提供有效 PostgreSQL 连接和应用安全配置；变量名及无敏感示例以项目或交付包中的 `.env.example` 为准。
+- 配置文件和进程环境中的秘密不得提交到 Git、工单、Wiki、日志或示例。
+- Sense、Bell 必须使用不同数据库角色、用户库、JWT/会话密钥和 Cookie；Brain 使用独立机器身份。
+- 修改服务账号、权限、端口、数据库、媒体二进制或持久化目录前必须建立相应工单并说明回退。
+
+## 构建与启动
+
+从 Sense 目录生成 Windows 包：
+
+```powershell
+Sense\scripts\build\build-windows.bat
+```
+
+生成包并正确配置后，可从仓库根运行：
+
+```powershell
+Sense\start_sense.bat
+```
+
+临时演示模式可透传 `demo` 参数；演示数据随进程停止而丢失，不得作为生产部署。
+
+## Supervisor 常驻实例
+
+本机 Supervisor 的 YoVision Sense 实例由工单 #106 建立。Supervisor 配置、启动停止命令、工作目录、环境文件和日志位置以 `D:\supervisor` 中的当前实例配置为准。修改该外部目录前必须建立工单并确认精确目标；仓库不得复制其中的秘密。
+
+## 健康检查与日志
+
+- 默认 Sense 访问地址以当前配置为准；已验收的本机默认地址为 `http://127.0.0.1:18080/`。
+- 先确认端口监听和 HTTP 页面，再检查 Sense 结构化日志、PostgreSQL 连接、数据库迁移以及 MediaMTX 进程和路径状态。
+- 日志不得输出数据库密码、摄像头凭据、会话 Cookie、JWT secret 或 token。
+- 具体视频、迁移和登录故障按 `Troubleshooting` 页面处理。
+
+## 停止、升级与回退
+
+- 手工前台启动时在原控制台正常终止进程；Supervisor 托管时使用该实例的受控停止方式，避免同时启动第二个占用相同端口的进程。
+- 升级前记录当前 Git 提交、交付包版本、数据库备份/恢复方案和配置差异。
+- 数据库迁移、凭据、权限或不可逆操作属于高风险，必须另建工单并等待确认。
+- 回退优先恢复上一已验收交付包和对应配置；涉及数据库迁移时只能使用该迁移工单确认的回退方案。
+
+## 最小验收
+
+- 启动入口、工作目录、配置来源和端口与实际一致。
+- Sense 页面与必要 API 可访问，数据库迁移成功。
+- MediaMTX 启用时进程、路径和播放链路状态可定位。
+- Supervisor 不会与手工进程重复占用端口。
+- 日志和文档没有秘密；未验证的 Brain、Bell、真机或生产行为明确标注。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Task-66-Sense视频接入与Profile
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-66-Sense%E8%A7%86%E9%A2%91%E6%8E%A5%E5%85%A5%E4%B8%8EProfile.-
-wiki_revision: 322feb232fc03c3a9ba22f65504cf3e151fb0e57
-synchronized_at: 2026-08-14T09:15:26Z
+wiki_revision: 87b3a59f3f27df1f1fb357f6c13a1e31cdde5e05
+synchronized_at: 2026-08-27T09:13:37Z
 <!-- gitea-wiki-mirror:end -->

 # 66 Sense视频接入与Profile
@@ -32,6 +32,13 @@ synchronized_at: 2026-08-14T09:15:26Z
 - 复用 GoAdmin JWT/Casbin/操作审计、迁移和 go-admin-ui BasicLayout、Element Plus Form/Dialog/Table/Tag、动态菜单与权限按钮。
 - implementation_operator、site_admin 可发现和探测，viewer 只读保存结果。

+## 修改文件
+
+- 后端入口与业务：`Sense/server/app/admin/router/sense_admission.go`、`Sense/server/app/sense/admission/**`、`Sense/server/app/sense/onvif/**`、`Sense/server/app/sense/rtsp/**`。
+- 数据与验证：`Sense/server/cmd/migrate/migration/version/2026081417000_profile.go`、`Sense/server/tests/admission/postgres_test.go`。
+- 前端：`Sense/ui/src/api/sense/admission.js`、`Sense/ui/src/views/sense/admission/**`、`Sense/ui/src/views/sense/device/index.vue` 及对应单元测试。
+- 完整文件清单以实现提交 `2bb1614` 和 PR #84 的 Git diff 为准。
+
 ## 验收结果

 | 标准 | 结果 |
@@ -54,7 +61,7 @@ synchronized_at: 2026-08-14T09:15:26Z
 - PostgreSQL 17：迁移与重复迁移通过；migration=1、tables=2、menus=3、policies=7。
 - SENSE_ADMISSION_TEST_DATABASE_URL 隔离测试：写入 Profile、重开连接、读取主子码流通过。
 - Wiki 镜像检查：通过。
- 未验证部分：未连接客户或实验室真实摄像机；真实厂商 Digest/RTSP 兼容、网络 ACL、设备校时和目标浏览器留待授权现场验收，不声称已通过。
+**未验证部分**：未连接客户或实验室真实摄像机；真实厂商 Digest/RTSP 兼容、网络 ACL、设备校时和目标浏览器留待授权现场验收，不声称已通过。

 ## 回退

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Task-67-Sense视频服务生命周期与状态对账
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-67-Sense%E8%A7%86%E9%A2%91%E6%9C%8D%E5%8A%A1%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E4%B8%8E%E7%8A%B6%E6%80%81%E5%AF%B9%E8%B4%A6.-
-wiki_revision: 4642924705d7a3406874ef532579fb2d6a25a88b
-synchronized_at: 2026-08-14T10:13:23Z
+wiki_revision: 718765b6b8eff5f4c81612ea8720272c97cd1a25
+synchronized_at: 2026-08-27T09:13:38Z
 <!-- gitea-wiki-mirror:end -->

 # 67 Sense视频服务生命周期与状态对账
@@ -30,6 +30,13 @@ synchronized_at: 2026-08-14T10:13:23Z
 - 接入成功后幂等建立路由；冷启动恢复 desired=running，明确 stopped 路径保持停止；稳定路径只刷新状态，不重复下发或增加版本。
 - 复用 GoAdmin JWT/Casbin/操作审计、迁移、动态菜单和 go-admin-ui BasicLayout、Element Plus Descriptions/Table/Tag/Button/MessageBox。

+## 修改文件
+
+- 后端入口与业务：`Sense/server/app/admin/router/sense_media.go`、`Sense/server/app/sense/media/**`、`Sense/server/app/sense/reconcile/**`。
+- 数据、配置与验证：`Sense/server/cmd/migrate/migration/version/2026081419000_media*`、`Sense/server/config/mediamtx/mediamtx.yml.example`、`Sense/server/tests/media/**`。
+- 前端：`Sense/ui/src/api/sense/media.js`、`Sense/ui/src/views/sense/media/**` 及对应单元测试。
+- 完整文件清单以实现提交 `19f9bfa` 和 PR #85 的 Git diff 为准。
+
 ## 验收结果

 | 标准 | 结果 |
@@ -53,7 +60,7 @@ synchronized_at: 2026-08-14T10:13:23Z
 - PostgreSQL 17 定向迁移：3 个菜单、12 条角色策略、1 条迁移记录通过。
 - Wiki 镜像检查：通过。
 - 已处理测试安全问题：MediaMTX 自动 TLS 文件的工作目录已固定到外部配置目录；临时证书/私钥未进入最终提交或远端。
- 未验证部分：未连接客户真实摄像机和现场网络；真实上游持续拉流、reader 变化、端口 ACL 和目标浏览器留待授权现场验收。
+**未验证部分**：未连接客户真实摄像机和现场网络；真实上游持续拉流、reader 变化、端口 ACL 和目标浏览器留待授权现场验收。
 - 已知相邻问题：空白 PostgreSQL 执行完整上游迁移链时，在到达 #67 前被旧 `sys_config` 初始化字段长度问题中止；#67 定向迁移已通过，空库安装链应由 #70/#71 单独复核，不在本工单混改上游初始化。

 ## 回退
@@ -0,0 +1,282 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Deployment-Template
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-Template.-
+wiki_revision: 75bd653ab2f3314a37eb9086e18152129941befa
+synchronized_at: 2026-08-27T09:07:38Z
+<!-- gitea-wiki-mirror:end -->
+
+# 部署文档模板
+
+> 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。
+>
+> 本模板面向项目内部维护者。面向客户或外部运维岗位的部署说明属于交付文档，使用[岗位文档模板](Audience-Document-Template.-)。
+>
+> 标准栈为 nginx 反向代理 + supervisor 进程托管，示例按 Python 服务（gunicorn / uvicorn）编写。实际技术栈不同时替换命令，但保留章节结构和“每条命令写明预期结果”的要求。
+
+## 本页用途
+
+让维护者能够在一台干净的服务器上完成首次部署、日常运维、健康检查和回滚。所有命令默认以具备 sudo 权限的账号在服务器上执行，示例以 Linux 为主。
+
+## 安全边界
+
+- 本页只写配置项的**名称和来源**，不写任何真实密码、令牌、私钥、证书内容、生产数据库地址或个人数据。
+- 需要凭据的步骤写明“从哪里取”，例如运维密码库条目名或环境变量名。
+- 涉及删除数据、数据库迁移和不可逆操作的步骤必须给出醒目警告、影响范围和回退条件。
+
+## 服务概览
+
+| 项目 | 内容 |
+|---|---|
+| 服务名（supervisor program） | `<myapp>` |
+| 代码部署目录 | `/srv/<myapp>` |
+| 运行账号 | `<myapp>` |
+| 运行时 | Python `<3.x>` |
+| 应用服务器 | gunicorn / uvicorn |
+| 本地监听地址 | `127.0.0.1:<8000>` |
+| 进程数 | `<n>` |
+| 对外域名与路径 | `https://<example.com>/` |
+| 依赖的外部服务 | 数据库 / 缓存 / 对象存储 / 无 |
+| 日志目录 | `/var/log/<myapp>/` |
+
+服务只监听 `127.0.0.1`，不直接对外暴露端口；所有外部访问经 nginx 转发。
+
+## 环境要求
+
+| 组件 | 版本要求 | 检查命令 | 预期结果 |
+|---|---|---|---|
+| 操作系统 | `<Ubuntu 22.04>` | `cat /etc/os-release` | 输出与要求一致 |
+| Python | `<3.11+>` | `python3 --version` | 输出版本号且不低于要求 |
+| nginx | `<1.18+>` | `nginx -v` | 输出版本号 |
+| supervisor | `<4.2+>` | `supervisord --version` | 输出版本号 |
+
+未安装时：
+
+```bash
+sudo apt update
+sudo apt install -y nginx supervisor python3-venv
+```
+
+**预期结果**：`systemctl status nginx` 与 `systemctl status supervisor` 均为 `active (running)`。
+
+## 首次部署
+
+### 1. 创建运行账号与目录
+
+```bash
+sudo useradd --system --home /srv/<myapp> --shell /usr/sbin/nologin <myapp>
+sudo mkdir -p /srv/<myapp> /var/log/<myapp>
+sudo chown -R <myapp>:<myapp> /srv/<myapp> /var/log/<myapp>
+```
+
+**预期结果**：`id <myapp>` 输出该账号；两个目录存在且属主为 `<myapp>`。
+
+服务账号使用 `nologin`，不允许直接登录。
+
+### 2. 取得代码
+
+```bash
+sudo -u <myapp> git clone <仓库地址> /srv/<myapp>/app
+cd /srv/<myapp>/app && sudo -u <myapp> git rev-parse HEAD
+```
+
+**预期结果**：输出本次部署的完整提交哈希，记录到部署记录中。
+
+### 3. 安装依赖
+
+```bash
+sudo -u <myapp> python3 -m venv /srv/<myapp>/venv
+sudo -u <myapp> /srv/<myapp>/venv/bin/pip install -r /srv/<myapp>/app/requirements.txt
+```
+
+**预期结果**：pip 以 `Successfully installed ...` 结束，无 ERROR。
+
+### 4. 落位配置文件
+
+```bash
+sudo install -o <myapp> -g <myapp> -m 600 /dev/null /srv/<myapp>/app.env
+sudo -u <myapp> vi /srv/<myapp>/app.env
+```
+
+**预期结果**：`ls -l /srv/<myapp>/app.env` 显示权限 `-rw-------` 且属主为 `<myapp>`。
+
+配置项清单见下方“配置与凭据来源”。配置文件不进入 Git。
+
+### 5. 数据库初始化或迁移
+
+<!-- 无数据库时删除本节。 -->
+
+> **注意**：迁移可能不可逆。执行前必须先备份，并确认回退方式。
+
+```bash
+sudo -u <myapp> /srv/<myapp>/venv/bin/python -m <myapp>.manage migrate
+```
+
+**预期结果**：输出全部迁移已应用，无失败项。
+
+## supervisor 配置
+
+写入 `/etc/supervisor/conf.d/<myapp>.conf`：
+
+```ini
+[program:<myapp>]
+command=/srv/<myapp>/venv/bin/gunicorn <myapp>.wsgi:application --workers <n> --bind 127.0.0.1:<8000> --timeout 60
+directory=/srv/<myapp>/app
+user=<myapp>
+environment=PATH="/srv/<myapp>/venv/bin",APP_ENV_FILE="/srv/<myapp>/app.env"
+autostart=true
+autorestart=true
+startsecs=5
+stopasgroup=true
+killasgroup=true
+stopwaitsecs=30
+stdout_logfile=/var/log/<myapp>/stdout.log
+stderr_logfile=/var/log/<myapp>/stderr.log
+stdout_logfile_maxbytes=50MB
+stdout_logfile_backups=5
+```
+
+> 异步框架使用 uvicorn 时把 `command` 换成：
+> `/srv/<myapp>/venv/bin/uvicorn <myapp>.asgi:app --host 127.0.0.1 --port <8000> --workers <n>`
+
+不要在 `environment` 里写明文密码或令牌；敏感值放在 `app.env`，由应用读取。
+
+加载配置并启动：
+
+```bash
+sudo supervisorctl reread
+sudo supervisorctl update
+sudo supervisorctl start <myapp>
+sudo supervisorctl status <myapp>
+```
+
+**预期结果**：`reread` 输出 `<myapp>: available`；`status` 显示 `RUNNING` 且 uptime 持续增长。出现 `BACKOFF` 或 `FATAL` 时查看 `stderr.log`。
+
+## nginx 配置
+
+写入 `/etc/nginx/sites-available/<myapp>.conf` 并软链到 `sites-enabled`：
+
+```nginx
+server {
+    listen 80;
+    server_name <example.com>;
+
+    access_log /var/log/nginx/<myapp>.access.log;
+    error_log  /var/log/nginx/<myapp>.error.log;
+
+    client_max_body_size <20m>;
+
+    location /static/ {
+        alias /srv/<myapp>/app/static/;
+        expires 7d;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:<8000>;
+        proxy_http_version 1.1;
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout    <60s>;
+    }
+}
+```
+
+<!-- WebSocket 需求存在时，在对应 location 增加 Upgrade 与 Connection 头；无此需求时删除本注释。 -->
+
+启用并生效：
+
+```bash
+sudo ln -sf /etc/nginx/sites-available/<myapp>.conf /etc/nginx/sites-enabled/<myapp>.conf
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+**预期结果**：`nginx -t` 输出 `syntax is ok` 与 `test is successful`；reload 无输出且 `systemctl status nginx` 仍为 `active (running)`。
+
+`nginx -t` 未通过时不要 reload，先修正配置。
+
+<!-- 需要 HTTPS 时在此记录证书来源、签发方式和续期检查命令；证书内容和私钥不得写入本页。 -->
+
+## 配置与凭据来源
+
+| 配置项 | 用途 | 来源 | 是否敏感 |
+|---|---|---|---|
+| `APP_ENV_FILE` | 指向配置文件路径 | supervisor 配置 | 否 |
+| `<DATABASE_URL>` | 数据库连接 | `/srv/<myapp>/app.env`，值取自运维密码库条目 `<条目名>` | 是 |
+| `<SECRET_KEY>` | 会话与签名 | 同上 | 是 |
+| `<LOG_LEVEL>` | 日志级别 | `/srv/<myapp>/app.env` | 否 |
+
+敏感值只记录取用位置，不在本页、工单、日志和提交中出现真实内容。
+
+## 日常运维
+
+| 操作 | 命令 | 预期结果 |
+|---|---|---|
+| 查看状态 | `sudo supervisorctl status <myapp>` | `RUNNING`，uptime 持续增长 |
+| 重启服务 | `sudo supervisorctl restart <myapp>` | 输出 `stopped` 后 `started` |
+| 停止服务 | `sudo supervisorctl stop <myapp>` | 输出 `stopped` |
+| 实时日志 | `sudo supervisorctl tail -f <myapp> stderr` | 持续输出应用日志 |
+| 应用日志 | `sudo tail -n 200 /var/log/<myapp>/stderr.log` | 输出最近日志 |
+| 接入层日志 | `sudo tail -n 200 /var/log/nginx/<myapp>.error.log` | 输出 nginx 错误 |
+| 重载 nginx | `sudo nginx -t && sudo systemctl reload nginx` | 测试通过后无中断生效 |
+
+修改 supervisor 配置后必须 `reread` + `update`，只 `restart` 不会加载新配置。
+
+## 健康检查
+
+每次部署、重启和回滚后必须全部执行：
+
+```bash
+sudo supervisorctl status <myapp>
+curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:<8000><健康检查路径>
+curl -sS -o /dev/null -w "%{http_code}\n" https://<example.com><健康检查路径>
+sudo tail -n 50 /var/log/<myapp>/stderr.log
+```
+
+**预期结果**：状态为 `RUNNING`；两个 `curl` 均返回 `200`；日志无新增异常堆栈。
+
+任何一项不符合时不视为部署成功，按“升级与回滚”处理。
+
+## 升级与回滚
+
+### 升级
+
+```bash
+cd /srv/<myapp>/app
+sudo -u <myapp> git rev-parse HEAD          # 记录当前提交，回滚需要
+sudo -u <myapp> git fetch --all
+sudo -u <myapp> git checkout <目标提交或标签>
+sudo -u <myapp> /srv/<myapp>/venv/bin/pip install -r requirements.txt
+sudo -u <myapp> /srv/<myapp>/venv/bin/python -m <myapp>.manage migrate   # 无数据库时删除
+sudo supervisorctl restart <myapp>
+```
+
+**预期结果**：restart 后 `status` 为 `RUNNING`，随后健康检查全部通过。
+
+升级前必须记录当前提交哈希；涉及数据库迁移时必须先备份。
+
+### 回滚
+
+```bash
+cd /srv/<myapp>/app
+sudo -u <myapp> git checkout <升级前记录的提交>
+sudo -u <myapp> /srv/<myapp>/venv/bin/pip install -r requirements.txt
+sudo supervisorctl restart <myapp>
+```
+
+**预期结果**：健康检查全部通过。
+
+> **注意**：已执行的数据库迁移通常不能通过切回代码撤销。存在迁移时必须先确认迁移是否向后兼容；不兼容时按备份恢复流程处理，并停止自行操作、联系负责人。
+
+### 备份与恢复
+
+<!-- 记录备份对象、频率、保存位置、保留期和恢复步骤；无持久化数据时说明原因。 -->
+
+## 已知限制
+
+<!-- 记录本环境无法验证的部分，例如未做过真实回滚演练、未验证高并发表现、灰度或多机部署尚未支持。不得留空，无限制时写“无”。 -->
+
+- <!-- 填写 -->