1

Common-Changes

ila edited this page 2026-09-02 11:56:42 +08:00

Table of Contents

• 常见修改
• 风险分级
• 修改界面文案（计划）
• 增加一个参数设置项（计划）
• 修改 Wiki 文案
• 调整 Harness 检查
• 看懂 Agent 的修改

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

常见修改

本页说明典型改动要改哪里、验证什么、属于什么风险。产品代码尚未建立，涉及 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 解释这段代码在什么情况下会走到、失败时会发生什么。不要因为测试通过就默认边界没被破坏。