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

docs/06-troubleshooting.md

@@ -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`。