diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..2e8bc09
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,32 @@
+# 故障排查
+
+## 本页用途
+
+按“现象 → 原因 → 检查 → 处理”定位 DevHarness 常见问题。处理后如果形成稳定结论，应更新本页；临时过程记录在工单。
+
+| 现象 | 常见原因 | 检查方法 | 处理 |
+|---|---|---|---|
+| `--strict` 提示项目档案未填写 | 新项目仍有占位内容 | 搜索 `<填写` | 先在 Wiki 填写真实内容，再导出镜像 |
+| 同步提示镜像有未提交改动 | 有人直接修改 docs，或上次镜像尚未提交 | `git status --short -- docs` | 确认来源；保留人工内容并先更新 Wiki，不要强制覆盖 |
+| Wiki 页面不存在 | 页面未创建、标题或映射错误 | 查看 Wiki 页面列表和 `wiki-docs.json` | 修正明确的页面或映射；不要自动删除本地文件 |
+| API 路径出现重复 `/api/v1` | `GITEA_URL` 已包含 API 后缀 | 查看非敏感 URL 配置 | 同步器会规范化；新工具也应接受两种写法 |
+| 公共仓库读取返回 401/403/404 | 环境令牌失效或属于其他实例 | 不打印令牌；尝试浏览公开页面 | 只读请求可安全降级匿名；写请求必须使用正确 PAT |
+| 中文 Wiki 页面读取 404 | `sub_url` 被重复百分号编码 | 查看页面列表返回的 `sub_url` | 保留已有 `%`，不要再次编码 |
+| Wiki 页面标题多出 `.-` | Gitea 1.25 的页面规范路径或更新时未显式传标题 | 对照页面 title 和 `sub_url` | 更新中文页面时显式保留原 title；不要猜测路径 |
+| `--check` 正文不一致 | Wiki 已更新但镜像未导出，或本地被修改 | 对照 revision 和 Git 差异 | 确认 Wiki 后运行正式同步 |
+| 单元测试能过但真实同步失败 | 测试使用模拟数据，网络或 Gitea 行为不同 | 查看工单“未验证部分” | 增加最小真实验证并记录服务端版本 |
+| Git 工作区包含无关修改 | 同时存在其他任务或人工工作 | `git status --short` | 保留并隔离无关修改，不重置用户工作 |
+
+## 排查顺序
+
+1. 读取完整错误信息，不只看最后一行。
+2. 检查当前工单、分支和工作区。
+3. 检查项目档案中的真实命令和环境。
+4. 用最小命令复现。
+5. 对照最近提交和 Wiki revision。
+6. 修复后增加回归测试或稳定排错条目。
+7. 无法验证的部分写回工单。
+
+## 必须停止的情况
+
+出现凭据泄露、数据损坏风险、权限边界变化、不可逆操作或不明来源的工作区改动时，立即停止并说明影响，不继续尝试破坏性修复。