<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Common-Changes.-
wiki_revision: d7d778dd5f6e2a2b007371c6ce07f8adc4469638
synchronized_at: 2026-08-20T08:30:34Z
<!-- gitea-wiki-mirror:end -->

# 常见修改指南

本页面向接手维护的初级程序员。先判断风险，再按工单范围修改；数据库、权限、密钥、SSRF、队列和生产代码生成都不是“顺手调整”。

## 风险分级

| 级别 | 例子 | 处理方式 |
|---|---|---|
| 低 | 不改变含义/布局/可访问性的显示文案，注释，文档措辞 | 最小验证；符合豁免时可不建单 |
| 中 | 已确认页面的小样式、只读字段、普通日志、mock Provider 配置 | 建单并运行受影响测试 |
| 高 | retryable、SSRF、加密/轮换、迁移、租约/CAS、身份权限、点数写入、删除/清理 | 停止，Agent 分析并等待人工确认 |

风险按影响判断，不按行数判断。`internal/core` 新增 Gin/go-admin/gobreaker/imaging import 也是高风险边界破坏。

## 修改用户端显示文案

1. 在 `portal/web/templates/` 定位文案。
2. 不改模板名、字段、国际化键、流程暗示、布局或可访问性。
3. 启动 portal，在 375/768/1024 宽度检查文字不溢出、不遮挡且状态含义准确。

错误提示、按钮含义或会影响用户判断的文字不是纯显示豁免，必须建单。

## 修改 prompt template

默认模板是 `prompt_templates` 数据，不是 Go 常量：

- MVP-0 只读取 kind 默认模板，第一张图 primary、其余 reference；
- 2026-08-20 已确认 `chat` 与 `images_edits` 中性默认模板；只开放 `{{.UserPrompt}}`，具体内容见业务规则，不得改回 cmhub 电商文案；
- MVP-1 才允许用户 role_rule、每图 role/note 和排序；
- 修改后优先用 mock 生成并核对 `rendered_prompt`，真实上游只做一次经授权的低成本验收。

## 增加或调整 ProviderModel

1. Provider 只配置 `base_url` 和加密 Key；在 ProviderModel 选择 `api_type`、模型、能力、`extra_body` 和超时。
2. 验证 URL 会经过 DNS/DialContext、redirect、IPv6、代理和结果 URL 防护。
3. 自动验证使用 mock。管理端“连通性测试”必须由操作者点击、单次低成本、带审计和冷却。
4. API Key 不得出现在参数回显、响应、日志、截图、工单或 Wiki。

新增协议形态必须建高风险工单，补齐 retryable 与 SSRF 测试。

## 数据库与 go-admin 代码生成

标准流程：

```text
写 migrations up/down → 空 MySQL 8 up/down/up
→ 隔离 codegen 库执行 up → go-admin-ui 导入已有表
→ 配置/预览/生成 → 人工审查
→ 菜单/API 配置转成可逆 SQL → 从空库全量重放
```

- 不在应用启动、部署或生产执行 AutoMigrate。
- AutoMigrate 只可由人工在额外可丢弃数据库研究固定提交结构，用完销毁。
- “生成迁移脚本”不是业务 DDL；`/gen/todb` 会改菜单，`/gen/toproject` 会写源码。
- 生成文件不是可信输入：检查敏感字段、权限、路由、路径、重复代码和无关格式化。
- 生产必须不注册 dev-tools 路由，隐藏菜单不够。

## 修改 Wiki 文案

长期文档以 Gitea Wiki 为事实来源：

```text
修改 Wiki → 在线回读 revision → sync 导出 docs → sync --check → 提交
```

```powershell
$env:GITEA_URL = "https://git.ilapage.cn"
python dev_scripts/harness.py sync
python dev_scripts/harness.py sync --check
```

不得直接编辑带 `generated: true` 的镜像。新建项目专用页面时更新 `wiki-docs.json` 和 Home 导航；若要把它提升为所有项目强制核心文档，再同步修改 Harness 与成功/失败测试。

## 调整 Harness 检查

1. 修改 `CORE_DOCUMENT_REQUIREMENTS`、`REQUIRED_FILES` 或模板字段。
2. 同时补成功和失败用例。
3. 执行：

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

不要为了让检查变绿而削弱安全、Wiki 主源或任务归档边界。

## 看懂 Agent 的修改

1. **范围**：文件与工单一致，无无关重构。
2. **依赖**：core 只含 GORM/标准库；platform 通过接口注入。
3. **同步链路**：提交不调用上游、不读写点数。
4. **状态**：不把 running 退回 pending；最终写入校验 lease_token，旧 worker 更新 0 行。
5. **错误**：retryable 四类正确，attempts/error 脱敏落库。
6. **安全**：请求/redirect/result URL 都走 SSRF；文件访问校验用户归属；浏览器写操作有 CSRF。
7. **迁移**：所有表和配置都有 up/down、空库验证，无 AutoMigrate。
8. **生成代码**：差异已人工审查，生产 dev-tools 不存在。
9. **UI**：完整状态、375/768/1024、键盘、焦点、44px、reduced-motion。
10. **证据**：测试是真实执行结果，未验证项写入工单。

## 必须停止的情况

- 修改 retryable、熔断、SSRF、密钥、租约/CAS、身份权限或迁移；
- 执行 AutoMigrate、`/gen/todb`、生产代码生成或手工改共享/生产库；
- 写点数、删除数据/文件、运行清理任务或做不可逆回退；
- 调整上传/超时/租约/保留期限等未确认生产阈值；
- 改变已确认原型的结构、流程、状态、权限或异常处理；
- 真实上游测试可能反复消耗额度；
- 无法判断风险或同一位置两次仍无根因。