Files

T

cfdaily de4fc122a5 auto-sync: 2026-06-06 07:50:06

2026-06-06 07:50:06 +08:00

22 KiB

Raw Blame History

三国团队工具链与开发流程设计

状态: v0.4 — 主公审阅后修订作者: 庞统（副军师）🐦 评审: 司马懿（仲达）🗡️ 日期: 2026-06-06 v0.4 变更: 主公 6 条反馈（需求review前置、E2E用户触发、测试分工、审查默认司马懿、项目维度组织、分支保护说明）定位: 普适工具链和开发流程，适用于三国团队所有项目，与 moziplus 2.0 解耦

§1. 设计原则

#	原则	说明
1	声明式 + 代码执行分离	规则声明在配置中，执行由框架代码保证，不依赖 Agent 自觉（来源: moziplus-quality-governance）
2	能自动就自动	CI/CD/部署能自动触发就不手动，人只做决策和审查
3	Skill 固化流程	所有流程通过 Skill（提示词）固化，不靠口头约定
4	分级治理	按风险级别选择流程严格度，不搞一刀切（来源: quality-gate-patterns）
5	验证才算完	Agent 说"完成"不算，CI 通过 + 产出物存在才算（来源: 幻觉门控）
6	每个项目自带部署	部署脚本归项目管，工具链负责触发和验证，不替项目做部署决策
7	需求/问题必须经过 Review	所有需求和问题提交前必须经过 Review，不直接进入开发
8	项目维度组织	所有内容（Issue、CI、部署、Skill 配置）以项目为单位组织，支持多项目并行

§2. 基础设施层

2.1 代码托管：Gitea（唯一）

项	配置
地址	`http://192.168.2.154:3000`
版本	v1.23.4
认证	HTTP + token（待配置）
权限	cfdaily 用户；姜维持有 admin 权限（启用 Actions、分支保护等）

2.2 CI/CD：Gitea Actions

项	配置
Runner	Mac mini 裸机，act-runner（Go 二进制）
配置文件	`.gitea/workflows/*.yml`，每个项目自管
语法	兼容 GitHub Actions（v1.23.4 已验证支持）
触发	push / PR / tag

2.3 部署目标

环境	位置	说明
Mac mini 本机	`~/.sanguo_projects/<project>/`	主力开发和运行环境
NAS Docker	`192.168.2.154`	部分服务（Gitea、回测等）

§3. 分支策略

3.1 采用 Trunk-Based Development（简化版）

选 Trunk-Based 而非 Git Flow 的理由：

团队小（<10 人），不需要复杂的 release 分支
AI Agent 参与编码，Agent 在短生命周期 feature 分支上工作，完成后快速合并
CI 是安全网，main 分支始终可部署，feature 分支通过 CI 才能合并

前提条件：Agent 必须知道当前所在分支。git-workflow Skill 需注入 git branch --show-current 到 Agent 上下文（仲达 Q1 补充）。

3.2 分支规则

分支类型	命名	生命周期	合并方式	适用场景
`main`	`main`	永久	—	始终可部署
feature	`feat/<issue-N>-<简述>`	<3天	PR → CI → Review → merge	新功能
bugfix	`fix/<issue-N>-<简述>`	<1天	PR → CI → merge	Bug 修复
hotfix	`hotfix/<简述>`	<2小时	直接 push main + CI + 自动回滚	紧急修复

3.3 分支保护规则

main 分支：
- 不允许直接 push（hotfix 除外）
- PR 必须通过 CI（至少 unit + integration tests）
- PR 必须至少 1 人 Review（人或 Agent）
- hotfix 直接 push main 后必须触发 CI（至少 lint + unit），CI 失败则自动 revert（M1 修订）
feature/bugfix 分支：
- 无保护，自由 push
- 合并前必须 CI 通过

3.4 Commit 规范

<type>(<scope>): <subject>

<body>

type	说明
`feat`	新功能
`fix`	Bug 修复
`refactor`	重构（不改行为）
`test`	测试相关
`docs`	文档
`chore`	构建/工具/配置

§4. 问题管理

4.1 问题来源

来源	入口	处理方式
主公口头	庞统记录	创建 Gitea Issue
司马懿 Review	Review 意见	创建 Gitea Issue，关联 PR
自动化测试失败	CI 报告	自动评论到已有 Issue，或手动创建
用户测试反馈	人工报告	创建 Gitea Issue
Agent 运行发现	Agent 日志	创建 Gitea Issue

4.2 Issue 标签体系

标签	颜色	说明
`bug`	红	功能异常
`feature`	蓝	新功能需求
`improvement`	绿	改进优化
`security`	橙	安全相关
`risk:high/standard/low`	分级色	风险级别（见 §6.1 判定规则）
`priority:high/medium/low`	黄/灰	优先级
`blocked`	紫	阻塞中

4.3 Issue 状态流转

Open → In Progress → Review → Closed
  ↑                                  ↓
  └──── Reopened ←───────────────────┘

§5. CI/CD 管道设计

5.1 通用 CI 流程（所有项目共享骨架）

每个项目在 .gitea/workflows/ci.yml 自定义具体步骤，但遵循统一骨架。

注：Gitea Actions v1.23.4 不支持 paths 过滤触发条件。通过路径判断放在 job 级别的 if 条件中，使用确定支持的语法。（M4 修订）

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  # Job 1: 后端测试
  backend:
    # 只在有 Python 代码变更时跑
    runs-on: [self-hosted, mac-mini]
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        run: |
          python3 -m venv .venv
          .venv/bin/pip install -e ".[dev]"
      - name: Lint
        run: .venv/bin/ruff check src/
      - name: Unit Tests
        run: .venv/bin/pytest tests/unit/ -m "not e2e" --tb=short
      - name: Integration Tests
        run: .venv/bin/pytest tests/integration/ --tb=short
      - name: Coverage Report
        run: .venv/bin/pytest --cov=src --cov-report=term-missing

  # Job 2: 前端构建
  frontend:
    # 只在有前端目录时跑
    runs-on: [self-hosted, mac-mini]
    steps:
      - uses: actions/checkout@v4
      - name: Install & Build
        run: |
          cd src/frontend
          npm ci
          npm run build
      - name: Type Check
        run: cd src/frontend && npx tsc --noEmit

实际使用时：每个项目根据实际情况删减 job。没有前端的删 frontend job，没有 Python 的删 backend job。

5.2 CI 门控级别

级别	触发条件	跑什么	阻断行为
快速	feature 分支 push	lint + unit tests	软阻断：失败标红，创建 PR 时如果最近一次 CI 失败则不允许进入 Review（S2 修订）
标准	PR 到 main	lint + unit + integration + coverage	阻断 merge
完整	tag / main push	标准 + build（E2E 仅 tag 触发）	阻断部署
手动	手动触发	完整 + 特定检查	按需

5.3 覆盖率渐进策略（仲达 Q3 补充）

当前多数项目从未跑过覆盖率，直接设阈值不现实。分三阶段：

阶段	时间	覆盖率策略	说明
P1	启用后 2 周	只报告不阻断	先拿基线数据
P2	启用后 1 月	40% 阈值，低于警告不阻断	逐步提升
P3	启用后 2 月+	60% 阈值，低于阻断	正式生效

5.4 CI 结果反馈

✅ 通过 → PR 可合并
❌ 失败 → PR 阻断，自动评论失败信息
覆盖率低于阈值 → P1 只报告，P2 警告，P3 阻断

§6. 代码审查流程

6.1 风险级别判定规则（M2 修订）

风险级别不由改动者自评，按以下规则自动判定 + 非改动者确认：

自动判定规则（在 CI 或 PR 模板中检查）：

规则	级别	触发条件
涉及核心模块	高	改动文件匹配 `*/spawner`、`*/ticker`、`*/dispatcher`、`*/router`、`*/guardrails`、`*/strategy`、`*/risk`
涉及资金/安全	高	改动包含交易逻辑、风控规则、密钥管理、资金操作
数据库 schema 变更	高	改动匹配 `/migrations/`、`*/schema`、`**/models.py` 中的表定义
常规功能开发	标准	不匹配高风险规则的 src/ 下改动
文档/测试/配置	低	改动仅在 `docs/`、`tests/`、`.md`、`.yaml`（非 guardrails）

确认机制：

PR 创建时自动标注风险级别（基于 git diff 文件路径）
审查者（或庞统）确认或升级——只能升级不能降级
改动者可以申请升级（但不能申请降级）

6.2 审查方式（按风险分级）

风险级别	审查方式	审查者
高	固定 Review（必须）	司马懿（专职）
标准	交叉 Review（必须）	按改动领域分配（见 §6.3）
低	简化走查	至少 1 人快速确认 + CI 通过（S5 修订：不跳过，简化）

6.3 交叉审查分配（S1 修订）

标准风险按改动领域分配审查者，不搞固定轮转：

改动领域	审查者	说明
业务逻辑（策略/交易/数据）	关羽或张飞（交叉）	两人都懂业务
基础设施（部署/框架/工具）	姜维 → 找庞统或司马懿交叉	基础设施姜维独占，交叉找其他人
数据获取/清洗	赵云 → 找张飞交叉	数据线赵云独占
API/前端	张飞或姜维	谁更相关谁审
无法判断	庞统分配	兜底

分配原则：审查者和改动者不能是同一人。

6.4 审查清单（Skill 固化）

审查清单通过 Skill 提示词固化，不依赖审查者自觉。基础清单 + 项目类型变体：

基础清单（所有项目通用）：

1. 正确性
   - [ ] 代码逻辑正确，无死循环/空指针/边界遗漏
   - [ ] 异常处理完整（网络超时、文件不存在、参数非法）
   - [ ] 改动范围和 Issue/需求描述一致（不多不少）

2. 一致性
   - [ ] 命名规范统一（变量/函数/文件）
   - [ ] 和已有代码风格一致

3. 安全性
   - [ ] 无硬编码密钥/密码/Token
   - [ ] 用户输入有校验
   - [ ] 文件操作有路径校验

4. 可维护性
   - [ ] 复杂逻辑有注释（为什么，不是做什么）
   - [ ] 无重复代码（DRY）
   - [ ] 关键参数可配置，无魔法数字

5. 测试覆盖
   - [ ] 新功能有对应测试
   - [ ] Bug 修复有回归测试
   - [ ] CI 通过

结论：通过 / 不通过（附具体行号和修改方向）

量化策略项目变体（追加项）：

6. 量化策略专项
   - [ ] 止损逻辑完整（触发条件、执行路径、异常兜底）
   - [ ] 仓位计算正确（滑点、手续费已计入）
   - [ ] 回测参数和实盘参数分离

6.5 审查时效

改动大小	期望审查时间
< 100 行	2 小时内
100-500 行	半天内
> 500 行	1 天内

§7. 部署流程

7.1 部署触发

触发方式	适用场景	流程
自动（tag 触发）	正式发布	打 tag → CI 完整跑（含 E2E）→ 自动执行 deploy 脚本 → 健康检查
自动（main push）	日常迭代	push main → CI 标准跑 → 自动执行 deploy 脚本 → 健康检查
手动	紧急/调试	手动执行项目 deploy 脚本

7.2 项目部署脚本规范

每个项目必须提供 scripts/deploy.sh，接口统一：

#!/usr/bin/env bash
# deploy.sh — 项目部署脚本
#
# 必须支持的参数：
#   --source=DIR      源码目录（CI 自动传入：源码 checkout 路径）
#   --target=DIR      安装目标目录（CI 自动传入：安装路径）
#   --skip-build      跳过构建步骤
#   --health-check    部署后执行健康检查
#   --version         输出当前部署版本（tag + commit hash + 部署时间）
#   --rollback        回滚到上一个已记录的部署版本
#
# 必须维护的文件：
#   data/deploy-history.jsonl — 最近 10 个部署版本记录
#     每行: {"tag":"v1.2.3","commit":"abc123","timestamp":"2026-06-06T12:00:00+08:00","status":"success"}
#
# 必须返回：
#   0 = 成功
#   非0 = 失败（stderr 输出原因）

7.3 自动部署 Workflow

# .gitea/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  deploy:
    needs: [ci]  # 依赖 CI 通过
    runs-on: [self-hosted, mac-mini]
    steps:
      - uses: actions/checkout@v4
      - name: Record current version
        run: bash scripts/deploy.sh --version
      - name: Deploy
        run: bash scripts/deploy.sh --source="$GITHUB_WORKSPACE" --health-check
      - name: Rollback on failure
        if: failure()
        run: bash scripts/deploy.sh --rollback

7.4 健康检查

每个项目的 deploy 脚本必须包含健康检查：

HTTP 服务：curl -sf http://localhost:<port>/api/health
数据服务：数据连通性检查
定时任务：PM2 状态检查

7.5 回滚策略（M3 修订）

版本记录：

每次 deploy 成功后，记录 tag + commit + 时间戳到 data/deploy-history.jsonl（保留最近 10 条）
--version 读取最后一行输出当前版本
--rollback 读取倒数第二行，checkout 对应 commit，重新 deploy

回滚流程：

deploy.sh --rollback 读取上一个成功版本
git checkout <previous-commit>
重新执行 deploy（不含 rollback）
健康检查

已知限制：

revert 可能产生合并冲突 → 部署失败时人工介入
数据库变更回滚需人工介入 → schema 变更必须向前兼容（只加字段不删/不改），违反此规范由 CI 检查拦截（或人工 Review 拦截）

§8. 验证流程集成

8.1 验证来源和层级

验证来源	层级	触发时机	自动化程度
Lint	机械	每次 push	100% 自动
单元测试	机械	每次 push	100% 自动
集成测试	语义	PR 到 main	100% 自动
覆盖率	语义	PR 到 main	渐进自动（见 §5.3）
Code Review	共识	PR 到 main	人工（Skill 辅助）
E2E 测试	共识	tag 发布时（非每次部署）	半自动
用户测试	共识	部署后	手动

8.2 三阶段门控（来源: quality-gate-patterns）

机械门控 (CI 快速) → 语义门控 (CI 标准 + Review) → 共识门控 (E2E + 用户验证)
    零成本              中等成本                    高成本
  语法/lint/编译     API 契约/业务逻辑            端到端/用户体验

快速门控是开发期辅助反馈，不替代标准门控
PR 合入必须经过标准门控（机械 + 语义），这个顺序不可跳过（S3 修订）
机械失败 → 立即阻断，不看 Review
语义失败 → 可以 Review 但不能合并
共识阶段 → E2E 仅 tag 发布时跑，日常靠标准门控

8.3 测试失败 → Issue 关联

CI 失败时，如果已有 Issue → 自动评论失败信息
CI 失败时，如果无 Issue → 不自动创建（避免 Issue 爆炸），由改动者手动创建

8.4 机械门控前提条件（仲达 Q6 补充）

P1 必须先配好以下工具，否则机械门控跑不起来：

工具	用途	安装
`ruff`	Python lint + format	`pip install ruff`
`pytest-cov`	覆盖率	`pip install pytest-cov`
`act-runner`	CI 执行器	下载 Go 二进制

§9. 完整开发流程（端到端）

9.1 场景 A：新功能开发

1. 问题入口
   └─ 主公口头 / 需求文档 → 庞统创建 Gitea Issue #N

2. 分支创建
   └─ git checkout -b feat/issue-N-xxx
   └─ Agent 或人工编码（git-workflow Skill 注入分支信息到 Agent 上下文）

3. 开发过程中
   └─ 每个 commit → push → CI 快速门控（lint + unit）
   └─ CI 失败 → 标红但不阻断开发 → 修好再 push

4. 开发完成
   └─ git push origin feat/issue-N-xxx
   └─ 创建 PR → 自动标注风险级别（基于改动文件路径）
   └─ CI 标准门控（lint + unit + integration + coverage）

5. 审查
   └─ CI 通过后进入审查
   └─ 审查者确认风险级别（只升不降）
   └─ 按风险级别分流：
       ├─ 高风险 → 司马懿专职审查
       ├─ 标准风险 → 按改动领域分配交叉审查者
       └─ 低风险 → 简化走查（至少 1 人确认）
   └─ 审查不通过 → 修改 → push → CI → 再审
   └─ 审查通过 → merge

6. 部署
   └─ merge 到 main → 自动触发 CI + deploy workflow
   └─ deploy.sh 执行 → 记录版本 → 健康检查
   └─ 部署成功 → Issue #N 关闭
   └─ 部署失败 → 自动回滚 → 人工介入

7. 验证
   └─ 日常迭代：标准门控已覆盖
   └─ 正式发布（tag）：E2E 测试
   └─ 发现问题 → 新开 Issue

9.2 场景 B：Bug 修复

1. 问题入口
   └─ CI 失败 / 司马懿 Review / 运行时发现
   └─ 创建 Gitea Issue #N，标注 bug + 风险级别

2. 根因定位（bugfix-workflow Skill）
   └─ 调查根因（不猜，看日志/复现）
   └─ 在 Issue 中记录根因

3. 修复
   └─ git checkout -b fix/issue-N-xxx
   └─ 修改代码 + 添加回归测试（必须）
   └─ push → PR → CI → Review

4. 合并+部署
   └─ merge → auto deploy → 健康检查
   └─ Issue #N 关闭

5. 验证
   └─ 确认原 bug 不再复现

9.3 场景 C：紧急修复（hotfix）（M1/S5 修订）

1. 判断是否需要 hotfix
   └─ 标准：线上故障影响核心功能，等 PR 流程代价过高
   └─ 庞统或主公确认

2. 直接在 main 上修
   └─ git commit → push main
   └─ CI 必须触发（lint + unit），不可跳过
   └─ auto deploy → 健康检查
   └─ CI 失败 → 自动 revert → 人工介入

3. 事后复盘（hotfix-workflow Skill）
   └─ 24 小时内必须完成：
       ├─ 补 Gitea Issue（记录根因 + hotfix 内容）
       ├─ 司马懿 Review（事后审查代码质量）
       └─ 复盘记录（为什么需要 hotfix、如何避免）
   └─ 超时未复盘 → 下次 hotfix 权限暂停

§10. Skill 清单（流程固化）（S4 修订）

以下流程通过 Skill 固化到对应 Agent：

Skill 名	固化什么	适用 Agent
`git-workflow`	分支创建/命名/合并规范、commit 规范、PR 创建流程、当前分支注入上下文	所有编码 Agent（张飞、姜维、关羽）
`code-review`	风险级别判定规则、审查清单（基础+项目变体）、审查标准、结论格式	司马懿（主审查）、所有轮查 Agent
`ci-cd-ops`	CI 配置规范、deploy 脚本规范、健康检查标准、版本记录规范	姜维（平台）、所有项目维护者
`bugfix-workflow`	根因定位流程、回归测试要求、Issue 关联	张飞、姜维
`hotfix-workflow`	hotfix 判断标准、直接 push main 流程、CI 必跑、24h 复盘要求	庞统（协调）、张飞、姜维
`testing-workflow`	什么时候跑什么测试、怎么写测试、测试数据隔离规范	所有编码 Agent
`release-workflow`	tag 规范、changelog、发布流程、数据库 schema 变更向前兼容规范	庞统（协调）

§11. 实施路线

阶段	内容	前置条件	耗时
P0: 基础启用	Gitea admin 开启 Actions + 部署 act-runner（Mac mini 裸机）	主公操作 NAS	30 分钟
P1: CI 骨架	模板 CI workflow + pytest-cov + ruff + 覆盖率基线测量	P0	1 天
P2: 流程 Skill	7 个 Skill 编写（见 §10）	无	2-3 天
P3: 自动部署	部署 workflow + 项目 deploy.sh 规范化 + 版本记录	P1	1-2 天
P4: 渐进收紧	覆盖率阈值 P1→P2→P3、E2E 集成	P1-P3	按需

P1 必须先就位的工具（否则机械门控跑不起来）：

ruff（lint）
pytest-cov（覆盖率）
act-runner（CI 执行器）

§12. 评审记录

v0.1 → v0.2 修订清单

编号	类型	问题	修订内容
M1	必须修	hotfix 安全网不足	§3.3 明确 hotfix push main 后 CI 必跑，失败自动 revert；§9.3 统一流程
M2	必须修	风险级别谁来定	§6.1 新增自动判定规则（按文件路径）+ 非改动者确认机制（只升不降）
M3	必须修	回滚策略过于简单	§7.2 新增 `--version` 参数和 deploy-history.jsonl；§7.5 重写回滚策略
M4	必须修	CI 语法问题	§5.1 删除 `hasPython()`/`hasFrontend()` 伪函数，改为每个项目按需删减 job
S1	建议改	轮查配对不合理	§6.3 改为按改动领域分配，不再固定轮转
S2	建议改	快速门控"不阻断"是噪音	§5.2 改为"软阻断"，PR 进入 Review 前检查最近 CI 状态
S3	建议改	三阶段门控说明不清	§8.2 补充：快速门控是开发辅助，PR 合入必须标准门控
S4	建议改	Skill 遗漏	§10 增加 testing-workflow、hotfix-workflow、release-workflow（含 schema 变更）
S5	建议改	hotfix 复盘无时限	§9.3 加 24 小时复盘约束，超时暂停 hotfix 权限
Q1	评审回答	Trunk-Based 够用吗	§3.1 补充前提：Agent 必须知道当前分支，git-workflow Skill 注入
Q3	评审回答	覆盖率基线缺失	§5.3 新增渐进策略（P1 只报告 → P2 40% → P3 60%）
Q6	评审回答	机械门控前提未就绪	§8.4 新增工具清单，§11 标注 P1 必须先就位

§13. 待讨论

Gitea admin 权限：需要主公用 admin 账号改 app.ini 启用 Actions
分支保护：是否在 Gitea 里配 branch protection（要求 CI 通过才能 merge）？
数据库 schema 变更检查：是否需要 CI 自动检测 schema 不兼容变更（如删字段、改类型）？还是靠人工 Review？
E2E 触发策略：tag 发布时自动跑 E2E，但 E2E 需要 spawn 真实 Agent（耗时 10-30 分钟），接受这个成本吗？

22 KiB Raw Blame History Unescape Escape