Files

T

ila 0920621e7d chore: 简化单人开发工作流 (#48 )

2026-08-24 16:05:01 +08:00

5.9 KiB

Raw Blame History

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

常见修改指南

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

风险分级

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

新功能、API 或配置契约、数据库、权限、安全、并发、跨模块变化和重大 UI 必须建单。免单修改不得改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性；无法确定时建单。风险按影响判断，不按行数判断。internal/core 新增 Gin/go-admin/gobreaker/imaging import 也是高风险边界破坏。

修改用户端显示文案

在 portal/web/templates/ 定位文案。
不改模板名、字段、国际化键、流程暗示、布局或可访问性。
启动 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

Provider 只配置 base_url 和加密 Key；在 ProviderModel 选择 api_type、模型、能力、extra_body 和超时。
验证 URL 会经过 DNS/DialContext、redirect、IPv6、代理和结果 URL 防护。
自动验证使用 mock。管理端“连通性测试”必须由操作者点击、单次低成本、带审计和冷却。
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 检查

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

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

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

看懂 Agent 的修改

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

必须停止的情况

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

5.9 KiB Raw Blame History Unescape Escape