chorus/docs/05-common-changes.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Common-Changes.- wiki_revision: becf3fdead14674cb74a7a48c4792c06eb9d454b synchronized_at: 2026-08-20T03:29:30Z

常见修改指南

本页面向接手简单维护的初级程序员。每一类修改都给出改哪里、验证什么、什么时候必须停下来。

风险分级

级别	例子	处理方式
低	页面显示文案、注释、文档措辞、日志文本	可以直接改，跑最小验证
中	现有页面的样式与布局微调、新增一个只读字段展示、增加一条日志	建单，按本页步骤改，跑完整验证
高	选路与 retryable 判定、熔断参数、SSRF 校验、密钥加解密、数据库迁移、队列租约、身份与权限、点数余额写入、删除数据或不可逆操作	停止，交给 Agent 分析并等待人工确认方案

判断不了级别时按高风险处理。“看起来只改一行”不是低风险的理由——retryable 的一行就能烧光所有上游配额。

修改用户端显示文案

1. 在 portal/web/templates/ 中定位文案所在模板。
2. 只改用户看到的文字，不要顺手改变量名、模板名、CSS 类名或字段名。
3. 验证：go build ./...，启动 go run ./portal，在浏览器确认该页面文字与布局。

纯显示文案且不改变语义、流程、权限、状态、接口、布局或可访问性时不需要建单，但仍要做最小界面检查。改的是错误提示的含义、按钮的行为暗示或任何影响用户判断的措辞时，按中风险建单处理。

修改角色规则默认模板

角色规则不是代码常量，是数据：改 prompt_templates 表中对应 kind 的默认模板，或通过管理端页面修改。

• 不要把角色规则写回 Go 代码里——三层覆盖（管理端模板 → 用户端可编辑框 → 每张图 role/note）是已确认的设计。
• 改完用一次真实生成验证，检查 generations.rendered_prompt 是否如预期。

增加或调整一个上游 Provider

1. 优先通过管理端页面配置（管理端接入前用种子命令，见 本地开发与验证）。
2. 确认 api_type 选对：文生文用 chat，图生图用 images_edits。
3. 保存后用「连通性测试」打一次真实请求验证；没有该按钮时手工提交一次生成。
4. api_key 只填进配置，不要出现在工单、截图或日志里。

新增的是一种上游协议形态（而非一家新服务商）时属于高风险：需要在 internal/core/provider/ 新增实现，必须建单并补齐 mock 测试。

修改 Wiki 文案

长期文档的事实来源是 Gitea Wiki，docs/ 是只读镜像（Wiki 初始化完成后生效）。

修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像

python dev_scripts/harness.py sync
python dev_scripts/harness.py sync --check

不要直接编辑带 generated: true 头的本地文件。Wiki 尚未初始化的阶段允许直接改 docs/，但必须在工单说明，并在初始化时把内容搬到 Wiki。

调整 Harness 检查

dev_scripts/harness.py 的 check 子命令负责校验必需文件、核心文档章节和工单模板字段。

1. 修改 CORE_DOCUMENT_REQUIREMENTS、REQUIRED_FILES 或模板字段列表。

2. 在 tests/ 中同时补充成功用例和失败用例——只有成功用例的检查等于没有检查。

3. 验证：

   python -m unittest discover -s tests -v
   python dev_scripts/harness.py check --strict
   

新增核心文档时必须同时更新 wiki-docs.json 映射、docs/README.md 导航和 Harness 检查，三者缺一会导致同步或检查失败。

看懂 Agent 的修改

审查 Agent 提交时按这个顺序看：

1. 范围：改动文件是否都落在工单声明的范围内？出现工单没提到的文件要问清楚。
2. 边界：internal/core 里有没有混进 gin 或 go-admin 的 import？生成链路有没有碰点数？
3. 状态机：generations.status 的写入是否只沿 pending → running → succeeded | failed 前进？
4. 失败路径：retryable 的分支有没有写反？失败时 attempts、error_code、error_message 是否都落库？
5. 迁移：表结构变更有没有对应 SQL 文件？down 能不能跑？
6. 测试：新增逻辑有没有测试，测试是否覆盖失败分支而不只是happy path。
7. 文档：入口、命令、规则变了，docs/ 是否同步评估过。

任何一条答不上来就退回让 Agent 解释，不要凭“测试过了”放行。

必须停止的情况

遇到以下情况停止修改，交给 Agent 分析并等待人工确认：

• 需要改选路、熔断、retryable、SSRF、加解密、队列租约中的任意一项；
• 需要新增或修改数据库迁移；
• 需要触碰身份认证、权限或 API Key；
• 需要写入点数余额或 point_ledger；
• 需要删除数据、清理生成物或执行任何不可逆操作；
• 修改会改变已确认原型的页面结构、流程、状态、权限或异常处理；
• 你不确定这属于哪一级风险。