yovision/docs/05-common-changes.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Common-Changes.- wiki_revision: becaa9f08fd07397da516c31e3d93362626df050 synchronized_at: 2026-08-27T09:05:21Z

常见修改指南

本页用途

帮助初级程序员在 Claude/Codex Agent 协助下处理简单 Bug 和小需求。这里说明常见入口、验证方法和停止条件，不代替工单和方案确认。

风险分级

等级	常见修改	处理方式
低风险	文案、简单校验、查询条件、独立 UI、小范围回归 Bug	初级程序员可在 Agent 协助下修改和验证
中风险	API、配置、依赖、跨模块逻辑、数据结构	由 Agent 实现，程序员理解差异并执行验证
高风险	权限、安全、并发、迁移、支付、删除数据、不可逆操作	停止修改，由 Agent 分析并等待人工确认

“代码行数少”不等于低风险。风险等级只决定由谁实施和验证，不改变建单门禁：新功能、缺陷修复、重构及行为变化仍需工单；只有 AGENTS.md 明确列出的非行为修改和纯显示文案豁免可以直接提交。

修改 Wiki 文案

1. 在相关工单确认目标。
2. 读取线上 Wiki 页面和当前 revision。
3. 修改线上 Wiki，不直接编辑 docs/。
4. 运行 python dev_scripts/harness.py sync。
5. 运行 python dev_scripts/harness.py sync --check。
6. 审查本地镜像差异并提交。

停止条件：页面需要删除、重命名或改变事实源边界。

增加工单字段

1. 阅读 .gitea/issue_template/task.md 和 Development-Workflow。
2. 判断字段是否影响所有任务，避免只为一个任务增加永久字段。
3. 修改模板和对应流程说明。
4. 为 Harness 检查增加或调整测试。
5. 创建一份示例工单草稿检查可读性。

停止条件：字段改变权限、审批或关闭条件。

调整 Harness 检查

1. 从 dev_scripts/harness.py 的 run_check() 开始读。
2. 新检查应输出具体文件和缺失内容。
3. 检查结构事实，不声称自动判断文档语义质量。
4. 在 tests/ 添加成功和失败用例。
5. 运行严格检查及全部测试。

停止条件：检查会删除、重写文件或依赖生产环境。

修复 Wiki 同步 Bug

1. 从 dev_scripts/wiki_docs.py 的 WikiClient、parse_mirror 和 sync_all 开始读。
2. 先编写能复现问题的测试。
3. 保持 Wiki → docs 单向关系。
4. 验证中文、路径编码、revision 和脏文件保护。
5. 使用测试页面验证时，不删除正式页面。

停止条件：需要自动删除/重命名页面、覆盖本地未提交修改或输出令牌。

看懂 Agent 的修改

审查时至少回答：

• 这次解决了哪个工单目标；
• 修改入口和调用路径在哪里；
• 有哪些行为变化；
• 增加或修改了哪些测试；
• 哪些内容没有验证；
• 是否更新了受影响的 Wiki 页面；
• 怎样回退。

回答不了时，让 Agent补充说明，不要仅凭“测试通过”验收。