5

Common-Changes

ila edited this page 2026-08-26 22:47:50 +08:00

Table of Contents

• 常见修改指南
• 风险分级
• 修改用户端显示文案
• 修改 prompt template
• 增加或调整 ProviderModel
• 数据库与 go-admin 代码生成
• 修改 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.

常见修改指南

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

风险分级

级别	例子	处理方式
低	文案、注释、文档措辞；不改变产品行为的测试；单文件且只恢复已有明确行为的小缺陷	满足免单条件时直接提交，执行受影响的最小验证
中	已确认页面的小样式、只读字段、普通日志、mock Provider 配置、跨文件行为修改	建单并运行受影响测试
高	retryable、SSRF、密钥、迁移、租约/CAS、身份权限、删除/清理、发布和不可逆操作	必须建单；停止实施，由 Agent 分析并等待人工确认

新功能、API 或配置契约、数据库、权限、安全、并发、跨模块变化和重大 UI 必须建单。免单修改不得改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性；无法确定时建单。风险按影响判断，不按行数判断。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 代码生成

标准流程：

写 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 文案

只有长期事实发生变化时才修改 Wiki；Gitea Wiki 是长期文档事实来源：

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

$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. 执行：

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

不要为了让检查变绿而削弱安全、Wiki 主源或工单事实来源边界。archive/export 只用于用户明确要求的历史快照，不属于标准任务闭环。

看懂 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、生产代码生成或手工改共享/生产库；
• 写点数、删除数据/文件、运行清理任务或做不可逆回退；
• 调整上传/超时/租约/保留期限等未确认生产阈值；
• 改变已确认原型的结构、流程、状态、权限或异常处理；
• 真实上游测试可能反复消耗额度；
• 无法判断风险或同一位置两次仍无根因。

修改管理端系统模块

1. 导航名称、分组、路径或组件变化先修改版本化 migration，并保持 up/down 可验证；不要在运行时使用 AutoMigrate 或手工改共享库。
2. 新系统页面必须同时核对 sys_menu、sys_api、sys_menu_api_rule、sys_role_menu 和 sys_casbin_rule。动态组件写为相对 src/views 的路径，不带 @/views、前导斜杠或 .vue。
3. 菜单、接口和登录日志保持只读。需要新增写能力时必须另建工单并重新做权限、安全和 UI 设计，不得只恢复旧 API 模块中的函数。
4. 管理员状态和角色保护必须在 service 层保留；修改时同时覆盖当前管理员、最后管理员、内置角色改名/停用/删除。
5. 最小验证包括 Admin Go 全量测试、Admin UI lint/单测/生产构建、系统管理 Playwright E2E，以及 migration 静态测试。涉及 migration 时追加隔离 MySQL up/down/up。