chore: 升级 DevHarness 工作流 (#108)

README.md

@@ -8,7 +8,48 @@ YoVision 是一个单仓多项目的智能视频事件平台，包含三个可
 
 Sense 与 Bell 是账户、数据、部署和发布边界完全独立的两个销售产品；Brain 是无界面的独立推理交付单元，默认随 Sense 部署。跨项目协作只通过 `contracts/` 中的版本化契约。
 
-开始工作前阅读 [AGENTS.md](AGENTS.md) 和 [文档中心](docs/README.md)。本仓库采用 DevHarness：Gitea 工单记录任务过程，Gitea Wiki 保存长期文档，`docs/` 是 Wiki 的只读镜像。
+开始工作前阅读 [AGENTS.md](AGENTS.md) 和 [文档中心](docs/README.md)。本仓库采用 DevHarness：Gitea 工单是单次任务唯一事实来源，Gitea Wiki 保存长期文档，`docs/` 默认保存核心 Wiki 的只读镜像。
+
+## 工作闭环
+
+```text
+讨论需求或缺陷
+  -> 阅读代码并提出方案
+  -> 人工确认方案
+  -> 创建 Epic / MVP / 单元任务工单
+  -> Agent 实现并测试
+  -> 提交代码并集中回写工单证据
+  -> 人工验收后记录结论并关闭工单
+  -> 长期事实变化时才同步 Wiki
+```
+
+默认不创建任务归档；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。
+
+## 首次初始化顺序
+
+1. 创建 Gitea 远端仓库并推送当前引导提交，启用工单和 Wiki。
+2. 配置 `wiki-docs.json` 和安全访问方式；优先使用已配置的 Gitea MCP，MCP 不可用时才使用 Gitea API并记录原因。
+3. 查询线上 Wiki；`Home` 不存在时先创建并回读 `Home`，取得 revision 后再创建其他核心页面。
+4. 本地 `docs/` 的存在不能证明线上 Wiki 已初始化。
+5. 开始产品编码前运行：
+
+   ```powershell
+   python dev_scripts/harness.py sync --verify
+   ```
+
+YoVision 已完成远端与 Wiki 初始化，上述步骤用于维护者理解门禁和以后建立新仓库。
+
+## 常用命令
+
+```powershell
+python dev_scripts/harness.py check --strict
+python dev_scripts/harness.py sync
+python dev_scripts/harness.py sync --check
+python -m unittest discover -s tests -v
+git diff --check
+```
+
+只有明确要求时才运行 `python dev_scripts/harness.py archive <编号> "<标题>"`、`export` 或 `export --all`。
 
 ## 分支模型
 
@@ -18,3 +59,15 @@ Sense 与 Bell 是账户、数据、部署和发布边界完全独立的两个
 - 只有用户明确审核通过，才能将 `dev` 合入 `main`。
 
 Sense 与 Bell 的新实现必须从根 `goadmin-baseline.json` 冻结的 go-admin 和 go-admin-ui 完整提交派生，开发时必须核对对应 commit 的 go-admin-doc。仅参考 GoAdmin 的技术栈、布局或视觉不属于本项目认可的二次开发。
+
+## Harness 目录
+
+```text
+AGENTS.md                         Agent 通用规则与 YoVision 专用门禁
+CLAUDE.md                         Claude Code 入口和三项目角色路由
+.gitea/issue_template/            Epic、MVP、单元任务模板
+docs/                             核心 Wiki 只读镜像及可选历史快照
+wiki-docs.json                    核心 Wiki 页面显式映射
+dev_scripts/harness.py            check / sync / archive / export 单一入口
+dev_scripts/wiki_docs.py          Gitea Wiki 客户端与镜像生成库
+```