yovision/AGENTS.md

Agent 开发规则

本仓库采用 DevHarness 工作流：Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的事实来源，Gitea Wiki 是长期开发文档的事实来源，Git 是代码与版本绑定资料的变更记录。docs/ 默认保存核心 Wiki 的只读镜像，docs/task/ 只保存人工明确要求的专项或历史兼容快照。人负责确认方案与验收，Agent 负责检查、实现、测试和留下证据。

开始工作前先阅读任务涉及目录中的 AGENTS.md。目录越深的规则越具体，但不得削弱上级安全规则。

项目档案 按需阅读，不作为每次任务的固定前置。出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。只为查命令不必打开项目档案。

常用命令

所有命令默认从仓库根目录执行，与项目档案保持一致。

用途	命令
查看工作区	git status --short --branch
检查模板结构	python dev_scripts/harness.py check --strict
运行单元测试	python -m unittest discover -s tests -v
导出核心 Wiki 镜像	python dev_scripts/harness.py sync
检查核心 Wiki 镜像	python dev_scripts/harness.py sync --check
创建可选任务快照	python dev_scripts/harness.py archive 123 "修复登录超时"
增量导出已有快照	python dev_scripts/harness.py export
全量导出已有快照	python dev_scripts/harness.py export --all

1. 永久规则

• 不把密码、令牌、Cookie、私钥、个人数据或生产数据写入代码、日志、工单、Wiki 和文档。
• 不执行未经用户明确授权的发布、付款、删除数据、破坏性迁移或其他不可逆操作。
• 保留用户已有和任务无关的工作区改动，不擅自重置、覆盖或混入提交。
• 发现需求与安全规则、已确认方案或现有数据冲突时，先停止实施并说明影响。
• 测试结果必须真实；未执行或无法覆盖的验证必须明确记录。

项目专用红线写入本文件的“项目专用规则”或对应子目录的 AGENTS.md，不要散落在聊天记录中。

2. 哪些改动需要工单

新功能、缺陷修复、重构以及任何用户可感知或改变程序行为的修改，必须先建立单元任务工单。

以下小改动可以直接提交，不要求工单：

• 只改错别字、注释或文档措辞；
• 只做格式化、导入排序或不跨文件的内部变量改名；
• 补充类型标注或文档字符串且不改变行为；
• 删除已经确认无人使用的死代码。
• 只修改用户看到的界面显示文案，并且满足本文件“工单与设计证据双门禁”的全部豁免条件。

除严格符合界面显示文案豁免的修改外，只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。

3. 需求到实施

1. 先复述目标，阅读相关代码、日志和文档，区分事实与假设。
2. 给出目标、非目标、方案、影响范围、风险、回退方式、验证方法和文档影响。
3. 方案没有得到用户明确确认前，只做只读诊断和方案整理，不实施正式代码。
4. 方案确认后，先建立单元任务工单，再修改代码。
5. 建立新工单不要求其他工单已经完成；开始实施前检查工单声明的前置工单。真实依赖未满足时保持“待实施”，允许并行时必须写明原因。
6. 开始实施前检查分支和工作区，明确哪些现有改动不属于本任务。
7. 严格按工单范围实现；新发现的问题先记录，不顺手混入当前任务。
8. 执行与风险相称的测试，把关键结果和未验证部分更新到工单。实施过程中出现计划外、当前无法解除的问题时才标记“阻塞”。
9. 只有长期事实变化时才修改 Wiki、读取确认，再运行 python dev_scripts/harness.py sync 导出本地镜像；没有长期文档影响时在工单说明原因并跳过 Wiki 同步。不得直接编辑镜像后反向覆盖 Wiki。

工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和文档影响；用户验收后再追加验收时间与结论，不重复覆盖或抄写已有证据。

Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。

Gitea 交互与工单最小读取

• 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
• MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
• 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
• 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
• 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
• 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
• 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。

新项目 Wiki 初始化门禁

• 从本模板创建新项目时，先创建 Gitea 远端仓库并启用工单和 Wiki，再配置 wiki-docs.json；不得把模板自带的本地 docs/ 当作新项目 Wiki 已初始化的证据。
• 优先使用项目已配置的 Gitea MCP 查询和写入 Wiki；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
• 先查询线上页面列表；Home 不存在时必须先创建 Home，在线回读正文并记录 revision，然后再逐页创建或更新其他核心映射页面。
• 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码。
• 产品编码前必须运行 python dev_scripts/harness.py sync --verify；全部成功才表示线上 Wiki 和核心镜像初始化完成。

工单与设计证据双门禁

• 纯界面显示文案只有在不改变业务含义、流程、权限、状态、接口、数据、法律/安全/支付/单位等高风险含义、国际化键、程序标识符、布局和可访问性，且没有任何不确定时，才免工单和原型；修改后执行最小界面检查。
• 新页面、独立用户功能、重大交互或导航变化，必须先用 Quant-UX 或其他合适工具制作可审阅原型；用户确认原型、文字需求和覆盖范围后，才能建立或放行实现工单并编写生产代码。
• 上述完整原型形成待审核版本后，默认直接通过 Quant-UX 或其他设计工具的线上链接审核，不要求每次导出本地 HTML。工单必须记录可访问链接、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围；线上链接无法访问或无法区分版本时停止审核，等待用户确认等效方案。
• 只有用户明确要求 导出原型 #N、导出全部原型，或项目专用规则明确要求离线交付时，才导出到 prototypes/<工单号>/<版本>/index.html。已确认的本地快照不得原位覆盖；版本目录内资源使用相对路径，导出后检查入口、主要交互和资源完整性，但不自动提交。
• 现有界面的小范围样式或布局调整使用标注截图、低保真图或明确复用的现有规范；新组件记录状态、错误和边界。两者只要不符合纯文案豁免就必须建单。
• 后端、接口、数据处理和定时任务不强制 UI 原型，但必须先确认架构、API、数据、状态或流程设计；恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。
• 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。
• 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。
• 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。
• 设计工具无法生成用户明确要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型可访问且版本明确时不因此阻塞线上审核。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制建立完整线上原型或导出 HTML。

自然语言快捷指令

快捷指令只是本工作流的自然语言别名，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收：

• 只分析：只读检查并给出方案；不建单、不修改，停在等待确认。
• 建工单：根据已确认方案创建单元任务工单；建单后停止，不修改代码。
• 执行工单 #N：检查工单和依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照；停在“待验收”。
• 建工单并做：依次建单和执行，建工单，做、建工单,做 含义相同；停在“待验收”。
• 继续工单 #N：优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续；关键前提未变化时不重复读取和分析仍有效的内容。
• 检查工单 #N：只读核对范围、验收、测试和证据并输出报告；不自动修复。
• 同步文档：读取 Wiki、导出核心 docs/ 并检查一致性，不处理任务归档；不修改 Wiki、不自动提交。
• 导出原型 #N：人工触发导出指定工单已确认的原型版本，按工单和版本写入 prototypes/；不扩展范围、不自动提交。
• 导出全部原型：人工触发导出当前项目已明确范围内的全部已确认原型；不自动提交。
• 导出任务归档：人工触发 python dev_scripts/harness.py export，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。
• 导出全部任务归档：人工触发 python dev_scripts/harness.py export --all，读取并导出全部线上任务归档；不删除本地文件、不自动提交。
• #N 验收通过：仅在用户明确验收后，在工单追加验收结论；按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档。

方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 #N 验收通过 外，快捷指令不得关闭待验收工单。原型和任务快照的导出必须由用户明确提出或项目专用规则明确要求，其他指令不得隐式执行。Gitea 工单不导出全文，docs/task/ 只是可能不完整的专项或历史兼容快照。详细语义见 开发工作流。

需求记录与流转

• 创建单元任务工单时，记录原始需求的来源、提出时间，以及能表达用户目的、场景和限制的少量关键原话或脱敏摘要；不得臆造用户原话。
• 工单中的目标、非目标、已确认方案、验收标准和文档影响构成确认后的正式任务需求。
• 影响范围、接口、数据、风险或验收的需求变化必须记录日期、内容、原因和用户确认；会改变已确认结果时先更新工单并等待再次确认。
• 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据；包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。
• 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出核心 docs/；单次任务的完成结果和验收保留在工单正文与评论。只有用户明确要求专项快照或项目专用规则要求时才创建 Wiki 任务快照并按需导出 docs/task/。Gitea 工单全文不导出到仓库。

详细记录边界见 开发工作流 与 业务规则和术语。

效率与范围控制

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

严格控制范围

• 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
• 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
• 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
• 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。

渐进执行和修复

• 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
• 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
• 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
• 不在真实证据出现前堆叠与已知风险无关的预防性检查。
• 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。

复用已验证事实

• 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
• 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
• 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
• Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。

明确停止条件

• 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
• “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
• 未影响当前验收的相邻问题只提示或建单，不顺手处理。

4. 工单层级

• 单元任务是唯一正式实施单位，记录方案、范围、验收标准、过程和测试结果。
• Epic 和 MVP 只维护目标、风险、汇总及 - [ ] #编号 / - [x] #编号 子工单索引，不复制单元任务全文。
• 新任务先建单元工单，再把编号同步到所属 MVP 和 Epic。
• 详细层级、状态和模板入口见 开发工作流 与 业务规则和术语。

5. 实施中的变化

• 范围、接口、数据结构、依赖、验收标准或风险变化时，先更新单元工单。
• 变化影响 MVP 或 Epic 时，同时更新父工单。
• 会改变用户已确认结果的变化，更新工单后必须再次等待用户确认。
• 阻塞、失败方案和新发现根因不能只留在聊天或代码注释中。
• Wiki 页面删除、重命名或事实源边界变化时，必须先更新工单并等待用户确认；同步工具不得自动传播删除或重命名。
• 工单状态应使用：待确认、待实施、进行中、阻塞、待验收、已完成。

6. Git 与验证

• 提交只包含当前工单相关文件。
• 实现提交信息引用工单号，例如：fix: 修复登录超时 (#123)。
• 不为流程制造空提交。
• 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。
• 不能验证的真机、生产、迁移或并发行为必须写入工单；存在明确要求的任务快照时再同步记录。
• Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 pwsh.exe，不得仅为设置编码重复启动一层 PowerShell。
• 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。
• 不得默认使用 -ExecutionPolicy Bypass；只有可信 .ps1确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。

7. 完成和验收

1. 逐项完成验收、测试和实现提交，在工单追加最终证据评论，记录最终方案、差异、结果、提交、遗留问题和文档影响。
2. 工单保持“待验收”，用户没有明确验收通过前不得关闭。
3. 有长期文档影响时，读取确认 Wiki，运行 python dev_scripts/harness.py sync --check 检查核心镜像，并把页面 revision 和镜像提交哈希写回工单；没有长期文档影响时不运行 Wiki 同步。
4. 用户验收通过后，在工单追加验收时间和结论，关闭单元工单，并同步更新 MVP 和 Epic；没有真实变化的 Wiki 不重复更新或检查。
5. 默认不创建任务归档。只有用户明确要求专项快照或项目专用规则明确要求时，才运行 python dev_scripts/harness.py archive <编号> "<短标题>"；export 和 export --all 同样必须显式触发。

MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才能关闭 MVP。Epic 的全部范围完成后才能关闭 Epic。

详细证据回写、可选快照和文档同步边界见 开发工作流。

8. 可维护性

• 优先使用直白、常见的实现；不要为了少写几行引入晦涩技巧。
• 类和函数保持单一职责，名称表达业务含义。
• 注释解释原因、边界和风险，不逐行翻译代码。
• 错误必须可定位，不静默吞掉失败。
• Wiki 文档先写结论和用途，再写步骤；示例命令应可直接复制，本地 docs/ 由同步工具生成。
• 面向初级维护者说明从哪里开始读、怎样运行和怎样验证。

修改风险

• 低风险修改可由初级程序员在 Agent 协助下处理；接口、配置、依赖、跨模块逻辑和数据结构由 Agent 实现并验证。
• 权限、安全、并发、迁移、支付、删除数据和不可逆操作属于高风险；高风险修改必须停止，由 Agent 分析并等待人工确认。
• 风险按影响范围判断，不按代码行数判断；示例见 常见修改指南。

文档影响

• 每个单元任务必须在工单中选择“无长期文档影响并说明原因”或列出需要更新的 Wiki 页面。
• 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。
• 部署命令变化时，有常驻服务的项目更新自己的 Deployment-and-Operations 页面（由 部署文档模板 复制建立）；没有常驻服务的项目记录为无部署文档影响，不创建空的部署页。
• 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。
• 必需核心页面及结构以 python dev_scripts/harness.py check --strict 和 新项目文档初始化 为准；稳定文档与可选历史快照的分工见 开发工作流。

9. 引导提交例外

从本模板创建全新仓库时，Gitea 远端和工单尚不存在，允许一次不带工单号的初始引导提交。该提交只能包含仓库骨架、Harness 规则和远端配置准备，不能包含产品功能。

远端建立并推送后，这个例外立即失效。

10. 项目专用规则

YoVision 分支治理

• explore 是旧实现的只读聚合快照，不接受新功能、修复或文档演进；需要恢复旧行为时从其来源提交读取证据，不在该分支续写产品。
• main 是用户审核基线，禁止直接开发、直接提交或未经用户明确审核的合并。
• 新任务分支必须从当前 dev 创建，完成后通过 PR 合回 dev；不得把功能分支直接合入 main。
• dev 完成集成测试后仍不能自动进入 main；只有用户明确表示审核/验收通过，Agent 才能执行 dev → main。
• 紧急修复也必须建单并取得用户对分支与合并路径的明确授权，不默认绕过 dev。

• 长期开发文档以 Gitea Wiki 为事实来源，单次任务证据以 Gitea 工单为事实来源；docs/ 默认保存显式映射生成的核心只读镜像，docs/task/ 是人工明确要求的专项或历史兼容快照，可能不完整或不是最新状态。
• 核心 Wiki 与镜像的固定顺序是：修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像。
• 默认不创建任务归档；archive、导出任务归档 或 导出全部任务归档 必须由用户明确提出或项目专用规则明确要求，且不得自动传播删除或重命名。
• 同步配置只允许写入 docs/ 下的 Markdown；发现核心镜像有未提交修改时必须停止。
• Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。
• dev_scripts/ 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。
• 本仓库包含 Sense/、Brain/、Bell/ 三个独立开发与交付单元；Sense 与 Bell 是认证、数据、部署和发布完全独立的销售产品，Brain 是无界面推理交付单元。
• 三个主 agent 默认分别只写自己的子项目目录；任务必须声明主 agent、子项目影响和精确 write_paths。
• contracts/、根级构建/部署配置和端到端测试属于共享写路径，只能由明确的协调工单和单一协调 agent 修改。
• 同一路径以及父子目录视为冲突；发现重叠时停止写入，不依靠事后合并解决并发所有权。
• 跨项目只共享版本化协议，不共享用户表、JWT、Cookie、数据库内部模型、摄像头凭据或业务实现代码。
• 旧仓库 D:\OPC\yovision_old 只读用于需求和证据追溯；不得继承旧任务状态，也不得不经筛选整树复制代码。
• 16 路是默认交付配额，不得成为数据库、数组、循环、分页、批处理或单机容量的硬上限。
• 开始子项目工作前还必须读取对应目录的 AGENTS.md；共享契约工作读取 contracts/AGENTS.md。

go-admin / go-admin-ui 精简与复用

• Sense、Bell 使用 go-admin 和 go-admin-ui 时遵循“最小可见、最小启用”：只呈现当前产品需要的菜单、路由、权限和接口，不把框架演示或无关管理能力暴露给用户。
• 快速交付阶段优先使用配置、菜单权限或路由开关隐藏不用模块。隐藏只移除用户入口，不等于禁用；权限或安全相关能力必须同时关闭前端入口与后端访问能力。
• 永久删除默认模块必须单独建立清理工单，先核对代码依赖、数据库对象、权限记录、构建影响、框架升级影响和回退方式，不在业务页面工单中顺手删除。
• 新页面优先复用现有布局、表格、表单、弹窗、上传、权限控制和请求封装；现有组件无法满足明确需求时才新增组件，并在工单中说明复用缺口。
• 新组件必须沿用项目现有的颜色、字号、间距、状态反馈、交互方式、命名和目录结构；不得引入与整体风格冲突的独立视觉体系。
• 不为单个页面直接改变底层公共组件的全局行为。确需全局修改或同时影响 Sense、Bell 时，必须单独建单并明确受影响页面、兼容方式和回归验证；跨产品影响按协同工单处理。
• UI 验收至少检查：没有多余入口、没有可见但不可用的失效入口、没有重复实现已有组件，并且视觉与交互保持一致。

Sense/Bell GoAdmin 技术基线

• goadmin-baseline.json 是 Sense、Bell 共用的 GoAdmin 上游与工具链版本事实来源；上游 URL 加完整 commit 是可复现标识，tag、package.json version、本机目录内容或本机已安装版本都不能替代 commit。
• D:\github\goadmin\go-admin、go-admin-ui、go-admin-doc 是当前机器的只读参考副本。Agent 可以读取和验证，不得在这些目录开发、修改或提交 yovision 产品代码。
• “基于 go-admin / go-admin-ui 二次开发”必须表现为从 goadmin-baseline.json 指定的两个完整上游 commit 导入或派生产品源码，并保留可核对的目录结构、框架启动链、通用认证/RBAC、菜单路由、请求封装及许可证来源；仅采用 Go、Vue、Element Plus、相似目录、页面外观或交互不算满足基线。
• 禁止用自建 net/http、自建认证/RBAC/会话框架或自制管理端外壳替代 go-admin/go-admin-ui 后仍声称是 GoAdmin 二次开发。确有上游能力无法满足时，必须在独立工单中说明缺口、保留上游扩展边界并等待用户确认。
• 每个 Sense/Bell 骨架、基础能力或框架相关工单开始实施前，必须读取任务相关的冻结 go-admin-doc 内容，并在工单中记录参考的文档主题或文件、继承的上游路径以及计划隐藏/禁用的默认模块。
• 初始化验收必须包含来源证据：上游 URL/commit、实际导入路径、保留的 MIT 文件、相对上游的裁剪/修改清单和构建测试；缺少任一项不得标记为 GoAdmin 骨架完成。
• Sense、Bell 必须从同一冻结基线分别初始化，保留独立代码、配置、构建、测试、版本和发布；不得通过共同修改参考仓库形成隐藏的共享实现。
• 复制或派生上游代码时必须保留对应 MIT 许可证和版权声明，并记录实际复制来源的 commit。
• go-admin-doc 只用于理解上游框架用法；yovision 的 Gitea Wiki、AGENTS.md 和 goadmin-baseline.json 仍是本项目事实来源。
• 变更任一上游 commit、Go、Node 或 pnpm 版本必须建立 Sense/Bell 协同升级工单，验证两个产品后再更新基线；不得在单端业务工单中静默升级。
• 当前冻结后端要求 Go 1.26.5；本机 Go 1.23.0 不满足要求，安装隔离的正确工具链并完成构建验证前，不得声称后端基线可构建。

三项目并行建单顺序

客户交付需要 Sense、Brain、Bell 并行推进时，固定使用以下顺序：

1. 由三个项目 agent 分别只读分析本项目需求，并行建立本项目的独立功能工单；每个工单只能有一个主项目、一个主 agent 和一组不重叠的 write_paths。
2. 三个项目 agent 不在本阶段创建或实施跨项目契约、根级编排和端到端工单；发现协同需求时只记录生产者、消费者、接口目的和依赖建议。
3. 三端独立工单建立后，由主 agent / dispatcher 统一汇总、去重，检查前置依赖、写路径冲突、契约归属和验收闭环。
4. 汇总完成后，再由主 agent 创建共享契约、根级构建/部署和端到端验收等协同工单，并为每个协同工单指定单一协调 agent。
5. 建单顺序不等于实施顺序。实施必须按真实依赖推进；独立骨架可以先并行，依赖共享契约的功能必须等待对应协同工单冻结版本后再实施。

主 agent / dispatcher 对工单集合的一致性负责：不得让三个项目重复实现同一事实源，不得保留重叠写路径，不得通过共享数据库、JWT、Cookie 或复制一份相似契约来绕过协同工单。三个项目 agent 可以提出协同工单草稿，但无权直接取得 contracts/ 或其他项目目录的写入所有权。