From 046624c1b2d7963ef733b4c9687d5dec14771388 Mon Sep 17 00:00:00 2001
From: ila <2+ila@noreply.git.ilapage.cn>
Date: Thu, 27 Aug 2026 17:02:51 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20DevHarness=204bbac?=
 =?UTF-8?q?f4=20=E5=B7=A5=E4=BD=9C=E6=B5=81=20(#108)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Troubleshooting.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Troubleshooting.md b/Troubleshooting.md
index acca451..b56d118 100644
--- a/Troubleshooting.md
+++ b/Troubleshooting.md
@@ -144,3 +144,12 @@
 
 如果迁移报告不支持的唯一性结构，不要手工删除约束或路由；在备份副本中核对实际约束和业务数据。正式迁移失败时保留错误并从迁移前备份恢复，不通过关闭唯一性绕过迁移。
 <!-- 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`。