diff --git a/Home.md b/Home.md index 54e519a..9adbcc8 100644 --- a/Home.md +++ b/Home.md @@ -1,48 +1,93 @@ # 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 或镜像。 ## 项目入口