From 2c41287656577564fc7b78b6cf8554ce81e16003 Mon Sep 17 00:00:00 2001
From: ila <ila2002@qq.com>
Date: Sat, 8 Aug 2026 08:56:30 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E5=B8=B8=E8=A7=81?=
 =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=8C=87=E5=8D=97=20(#2)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Common-Changes.-.md | 70 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 Common-Changes.-.md

diff --git a/Common-Changes.-.md b/Common-Changes.-.md
new file mode 100644
index 0000000..33df131
--- /dev/null
+++ b/Common-Changes.-.md
@@ -0,0 +1,70 @@
+# 常见修改指南
+
+## 本页用途
+
+帮助初级程序员在 Claude/Codex Agent 协助下处理简单 Bug 和小需求。这里说明常见入口、验证方法和停止条件，不代替工单和方案确认。
+
+## 风险分级
+
+| 等级 | 常见修改 | 处理方式 |
+|---|---|---|
+| 低风险 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下修改和验证 |
+| 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 |
+| 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
+
+“代码行数少”不等于低风险。
+
+## 修改 Wiki 文案
+
+1. 在相关工单确认目标。
+2. 读取线上 Wiki 页面和当前 revision。
+3. 修改线上 Wiki，不直接编辑 `docs/`。
+4. 运行 `python scripts/sync_wiki_docs.py`。
+5. 运行 `python scripts/sync_wiki_docs.py --check`。
+6. 审查本地镜像差异并提交。
+
+停止条件：页面需要删除、重命名或改变事实源边界。
+
+## 增加工单字段
+
+1. 阅读 `.gitea/issue_template/task.md` 和 Development-Workflow。
+2. 判断字段是否影响所有任务，避免只为一个任务增加永久字段。
+3. 修改模板和对应流程说明。
+4. 为 Harness 检查增加或调整测试。
+5. 创建一份示例工单草稿检查可读性。
+
+停止条件：字段改变权限、审批或关闭条件。
+
+## 调整 Harness 检查
+
+1. 从 `scripts/check_harness.py` 的 `main()` 开始读。
+2. 新检查应输出具体文件和缺失内容。
+3. 检查结构事实，不声称自动判断文档语义质量。
+4. 在 `tests/` 添加成功和失败用例。
+5. 运行严格检查及全部测试。
+
+停止条件：检查会删除、重写文件或依赖生产环境。
+
+## 修复 Wiki 同步 Bug
+
+1. 从 `scripts/wiki_docs.py` 的 `WikiClient`、`parse_mirror` 和 `sync_all` 开始读。
+2. 先编写能复现问题的测试。
+3. 保持 Wiki → docs 单向关系。
+4. 验证中文、路径编码、revision 和脏文件保护。
+5. 使用测试页面验证时，不删除正式页面。
+
+停止条件：需要自动删除/重命名页面、覆盖本地未提交修改或输出令牌。
+
+## 看懂 Agent 的修改
+
+审查时至少回答：
+
+- 这次解决了哪个工单目标；
+- 修改入口和调用路径在哪里；
+- 有哪些行为变化；
+- 增加或修改了哪些测试；
+- 哪些内容没有验证；
+- 是否更新了受影响的 Wiki 页面；
+- 怎样回退。
+
+回答不了时，让 Agent补充说明，不要仅凭“测试通过”验收。