ilaandClaude Opus 5
3895c873ec
- 从 dev_harness (3696663) 复制流程骨架：AGENTS/CLAUDE、工单模板、harness 工具与测试、通用流程文档 - 按需求方案改写为 chorus：项目档案、架构与代码地图、业务规则、本地验证、常见修改、故障排查、产品需求总览 - 需求分期为 MVP-0（跑通全流程最小闭环）/ MVP-1 / MVP-2 - AGENTS.md 增加 12 条 chorus 专用红线 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
94 lines
5.0 KiB
Markdown
94 lines
5.0 KiB
Markdown
# 常见修改指南
|
||
|
||
本页面向接手简单维护的初级程序员。每一类修改都给出改哪里、验证什么、什么时候必须停下来。
|
||
|
||
## 风险分级
|
||
|
||
| 级别 | 例子 | 处理方式 |
|
||
|---|---|---|
|
||
| **低** | 页面显示文案、注释、文档措辞、日志文本 | 可以直接改，跑最小验证 |
|
||
| **中** | 现有页面的样式与布局微调、新增一个只读字段展示、增加一条日志 | 建单，按本页步骤改，跑完整验证 |
|
||
| **高** | 选路与 `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`；
|
||
- 需要删除数据、清理生成物或执行任何不可逆操作；
|
||
- 修改会改变已确认原型的页面结构、流程、状态、权限或异常处理；
|
||
- 你不确定这属于哪一级风险。
|