# 常见修改指南

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

## 风险分级

| 级别 | 例子 | 处理方式 |
|---|---|---|
| **低** | 页面显示文案、注释、文档措辞、日志文本 | 可以直接改，跑最小验证 |
| **中** | 现有页面的样式与布局微调、新增一个只读字段展示、增加一条日志 | 建单，按本页步骤改，跑完整验证 |
| **高** | 选路与 `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. 优先通过管理端页面配置（管理端接入前用种子命令，见 [本地开发与验证](04-local-development-and-verification.md)）。
2. 确认 `api_type` 选对：文生文用 `chat`，图生图用 `images_edits`。
3. 保存后用「连通性测试」打一次真实请求验证；没有该按钮时手工提交一次生成。
4. `api_key` 只填进配置，不要出现在工单、截图或日志里。

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

## 修改 Wiki 文案

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

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

```powershell
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. 验证：

   ```powershell
   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`；
- 需要删除数据、清理生成物或执行任何不可逆操作；
- 修改会改变已确认原型的页面结构、流程、状态、权限或异常处理；
- 你不确定这属于哪一级风险。