cmsp/docs/05-common-changes.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Common-Changes.- wiki_revision: a852c6f6430902be970468b30802282617c09f93 synchronized_at: 2026-09-02T03:57:24Z

常见修改

本页说明典型改动要改哪里、验证什么、属于什么风险。产品代码尚未建立，涉及 Go 与前端的条目标注为「计划」，骨架建立后按实际路径回填。

风险分级

风险按影响范围判断，不按代码行数判断。

风险	本项目的例子	处理方式
低	界面文案、标签、列标题、提示语；表格列宽与排序；日志措辞；文档措辞	可直接实施。改完自测受影响界面，报告结果
中	参数设置项增减；SQLite 查询条件；任务进度事件字段；下载目录与命名规则；错误码新增	建工单。由 Agent 实现，维护者检查差异并执行验证
高	淘宝登录判定、签名生成、MTOP 请求构造；货憨憨写操作（上传素材、批量修改商品、删除素材）；SQLite 表结构与迁移；并发数与风控等待；断点与全局停止门逻辑；凭据存取方式	停止修改，先分析并等待人工确认

轻量模式下低风险项可直接实施；出现下列任何一项立即按高风险处理：涉及凭据、真实店铺数据、批量写入、删除、迁移、并发，或无法判断影响范围。

修改界面文案（计划）

1. 在 frontend/src/views/ 找到对应页面的文案。
2. 只改显示文本，不改绑定的字段名和事件名。
3. wails dev 启动后确认两个标签页显示正常。
4. 属于低风险，可直接实施。

错误提示要注意：前端不得依赖中文错误文本做判断。程序逻辑一律按 Go 侧返回的错误码分支，中文只用于显示。改文案不能改错误码。

增加一个参数设置项（计划）

1. internal/config/ 增加字段、默认值与校验范围。
2. frontend/src/views/SettingsView 增加对应表单项。
3. 在使用该参数的模块读取，不要在多处各自读一份。
4. 验证：填非法值时被拒绝并给出原因；重启程序后配置仍然生效。
5. 属于中风险，建工单。

如果新参数是路径或凭据，先确认它属于哪一类：路径写入配置文件；凭据不得写入仓库，也不得进入日志。

修改 Wiki 文案

长期文档的唯一编辑入口是 Gitea Wiki，docs/ 是只读镜像。

# 1. 在 Gitea Wiki 页面上修改并保存
# 2. 在线读取确认内容正确
# 3. 导出镜像
python dev_scripts/harness.py sync
# 4. 检查差异
git diff --stat docs
# 5. 单独提交镜像，不与实现代码混在一起

注意事项：

• 不要先改 docs/ 再反向覆盖 Wiki，同步工具没有反向能力。
• 不要改动固定章节标题，check --strict 依赖它们。
• 镜像有未提交改动时同步会停止；先确认改动来源再处理，不要直接覆盖。
• 页面删除或重命名不会自动传播，必须先在工单确认映射变化。

调整 Harness 检查

dev_scripts/ 属于 DevHarness 自身工具，本项目默认不修改。

• 需要新增一个长期文档页面时：先在 Gitea Wiki 建页，再在 wiki-docs.json 增加映射，然后 sync 导出，最后 check --strict 验证。这不属于修改 Harness。
• 确实需要改 harness.py 或 wiki_docs.py 时，先确认该需求是否应该回到上游 OPC/dev_harness 解决。在本项目就地改会让后续升级产生冲突，必须建工单并在项目档案的「项目适配说明」登记。
• 升级 DevHarness 时整体替换 dev_scripts/，并把项目档案中的基线提交更新为实际采用的完整哈希。未完成或已回退的升级不得更新基线。
• 业务用的通用脚本放独立目录，不得混入 dev_scripts/。

看懂 Agent 的修改

审查 Agent 提交时按这个顺序看，比逐行读代码有效：

1. 范围：git diff --stat 的文件是否都属于本次任务。出现无关文件说明范围失控。
2. 边界：是否触碰了架构与代码地图的「不可破坏的边界」。尤其看有没有把 Cookie、token 写进日志或文件。
3. 规则：是否改变了业务规则与术语里的稳定规则。改了就必须有对应工单和重新确认记录。
4. 证据：工单里的测试结果是真实运行的，还是只写了「已实现」。未验证的部分有没有明确写出来。
5. 文档：命令、入口、配置、错误码、业务规则有变化时，Wiki 是否同步更新。
6. 提交：提交是否只包含本次任务文件，有工单时是否带工单号。

看不懂的地方直接要求 Agent 解释这段代码在什么情况下会走到、失败时会发生什么。不要因为测试通过就默认边界没被破坏。