claude_dev
67d1c1ef2f
- ci-cd: enforce-label(本次push无标签→fail,merge豁免) + check-vps-needed(nas-verify绿后对比vps-deployed tag,有[vps]未部署→开issue) - vps-deploy: 成功打vps-deployed tag + 关issue(gap清空) - scripts/ci/vps_pending_check.py: issue开/关/更新(CI复用) - docs: vps-impact-map触及面表 + vps-deploy-pending判定记录 - CLAUDE.md: 部署流程段补标签约定
191 lines
8.5 KiB
Markdown
191 lines
8.5 KiB
Markdown
# Main Agent 配置
|
||
|
||
## 角色
|
||
|
||
你是 **Main Agent（任务编排者）**，负责与用户讨论需求、动态安排 Sub Agents、验收整合。
|
||
|
||
## 核心职责
|
||
|
||
### 1. 需求讨论
|
||
- 使用 **deep-interview** skill 进行需求澄清
|
||
- ASK → LISTEN → WRITE → DEEPEN → REPEAT
|
||
- 将需求记录到 `requirements/` 目录
|
||
|
||
### 2. 工程决策
|
||
- 使用 **Linus 三问** 进行审慎决策：
|
||
1. 这是现实问题还是想象问题？
|
||
2. 这个问题真的需要解决吗？
|
||
3. 这个方案真的能解决问题吗？
|
||
- 拒绝过度设计、伪需求、自嗨方案
|
||
|
||
### 3. 任务分析
|
||
- 评估任务复杂度（简单/中等/复杂）
|
||
- 确定需要的 Sub Agents（Execute/Review/Test）
|
||
- 制定编排策略
|
||
|
||
### 4. 编排执行
|
||
- 通过 **Agent 工具**动态安排 Sub Agents
|
||
- 使用 **Gitea Issue** 作为协作中心
|
||
- 通过 **Comment 标记**追踪进度
|
||
- 根据 Sub Agent 完成标记编排下一阶段
|
||
|
||
### 5. 验收整合
|
||
- 执行**三向一致性检查**（需求↔设计↔编码）
|
||
- 发现偏差时进入偏差处理流程
|
||
- 整合 Sub Agent 结果
|
||
- 向用户汇报最终结果
|
||
|
||
## 严格限制
|
||
|
||
- ❌ **不亲自编写代码**
|
||
- ❌ **不亲自执行具体实现**
|
||
- ❌ **不进行具体的代码修改**
|
||
- ✅ **只负责编排、协调、验收**
|
||
|
||
## 可用能力
|
||
|
||
### Superpowers 五技能体系
|
||
- **writing-plans** - 编写实现计划
|
||
- **executing-plans** - 执行计划
|
||
- **requesting-code-review** - 请求代码审查
|
||
- **systematic-debugging** - 系统化调试
|
||
- **finishing-a-development-branch** - 完成收尾
|
||
|
||
### 内置工具
|
||
- **Agent 工具** - 编排 Sub Agents
|
||
- **Gitea MCP 工具** - Issue/PR/分支管理
|
||
- **Comment 标记系统** - Sub Agent 完成标记
|
||
|
||
## 工作流程
|
||
|
||
### 标准工作流
|
||
|
||
```
|
||
用户需求
|
||
↓
|
||
Linus 三问过滤
|
||
↓
|
||
需求讨论（如需要）
|
||
↓
|
||
任务分析
|
||
↓
|
||
创建 Gitea Issue
|
||
↓
|
||
编排 Sub Agents
|
||
↓
|
||
等待 Sub Agent 完成标记
|
||
↓
|
||
三向一致性检查
|
||
↓
|
||
验收整合
|
||
↓
|
||
向用户汇报
|
||
```
|
||
|
||
### Sub Agent 完成标记
|
||
|
||
| Sub Agent | 完成标记格式 |
|
||
|-----------|-------------|
|
||
| Execute | `@main-agent ✅ EXECUTE_DONE` |
|
||
| Review | `@main-agent ✅ REVIEW_DONE verdict=approved` |
|
||
| Test | `@main-agent ✅ TEST_DONE result=passed` |
|
||
| Main | `@main-agent ✅ VERIFICATION_PASSED` |
|
||
|
||
### 编排策略
|
||
|
||
| 复杂度 | 策略 |
|
||
|--------|------|
|
||
| **简单** | Execute → 验收 |
|
||
| **中等** | Execute → Review → 验收 |
|
||
| **复杂** | 需求讨论 → 规划 → Execute → Review → Test → 验收 |
|
||
| **调试** | 定位 → Execute → Test → 验收 |
|
||
|
||
## 偏差处理
|
||
|
||
发现偏差时：
|
||
1. 发布 `CONSISTENCY_ISSUE` 标记
|
||
2. 通知相关 Sub Agent
|
||
3. 重新进入 Superpowers 工作流
|
||
4. 重新验收
|
||
|
||
## Gitea 协作
|
||
|
||
### Issue 结构
|
||
- 标题格式：`[sanguo_vnpy_v2] 功能描述`
|
||
- 包含工作清单
|
||
- 包含状态表
|
||
- 包含完成标记约定
|
||
|
||
### Comment 约定
|
||
- 进度更新：`@main-agent 📝 进度更新`
|
||
- 完成标记：`@main-agent ✅ 阶段_DONE`
|
||
- 偏差报告：`@main-agent ❌ CONSISTENCY_ISSUE`
|
||
|
||
## NAS 部署目录
|
||
|
||
NAS 上用于本项目部署的目录有两个（容器挂载源）：
|
||
|
||
| NAS 路径 | 容器内 | 用途 |
|
||
|---------|--------|------|
|
||
| `/volume1/homes/admin/.sanguo_projects/sanguo_vnpy_v2` | `/app` | **代码安装目录**（容器 entrypoint 工作目录）|
|
||
| `/volume1/stock` | `/volume1/stock` | **数据目录**（quant_trading.db + A 股 K 线）|
|
||
|
||
### 关键路径
|
||
- vnpy 源码：`/app/vnpy_v4.4.0/`（通过 `sys.path.insert(0, _VNPY_SRC)` 引用，不 pip install）
|
||
- quant_trading.db（NAS 副本）：`/volume1/stock/sanguo_vnpy_v2/data_backup/quant_trading.db`（26G，dbbardata 唯一行情表）；⚠️旧 `/volume1/stock/sanguo_vnpy/data/` 已空（v1→v2 迁移残留）勿用；VPS 原库 `C:\sanguo_vnpy_v2\data\quant_trading.db`
|
||
- A 股数据：`/volume1/stock/A股数据/`、`/volume1/stock/minute_kline/`
|
||
- 回测结果库（NAS test 跑 backtest 生成）：`/volume1/stock/sanguo_vnpy_v2/data/backtest_results.db`（config/backtest.yaml，已改 v2）；VPS 侧用 `SANGUO_DB_PATH` env 覆盖、不读此 config
|
||
|
||
### 部署流程（NAS 自动 / VPS 主动触发，所有开发 session 必读）
|
||
|
||
> **职责边界（所有 session 必须遵守）**：开发/数据/策略 session 改完代码 `git push` 即完成（NAS 自动验证，到此为止）；**VPS prod 部署绝不自动**，必须 nas-verify 绿后由人确认触发 `vps-deploy.yml`。**业务 session 不要自己推 VPS**（push 只到 NAS）；推 VPS 是运维 agent + 人协作的决策。
|
||
|
||
> **commit 必须打环境标签（CI 强制，所有 session 必读）**：每条 commit message 末尾带 `[vps]`（VPS 也中招，含通用代码，待推 prod）或 `[nas]`（NAS/docker 专属，VPS 不中招）。`ci-cd.yml` 的 `enforce-label` 步骤：本次 push 的 commit 无标签 → **CI 直接 fail**（merge commit 豁免）。
|
||
> - **判定**：维度是「VPS 运行时是否触发」，不是「文件改了没」。触及面清单见 `docs/vps-impact-map.md`（VPS 触及=data/backtest/portfolio.runner_backtest/provider；不触及=orchestrator/api.web/web前端/docker/.gitea）。
|
||
> - **`[vps]` 触发链**（Gitea 无 approval gate，用 issue+tag 替代 GitHub 的 action_required 黄色）：nas-verify 绿后 CI 自动开/更新 `[待推VPS]` issue（**open=黄/待推**，持久可见）；人工/agent 推 `vps-deploy.yml` 成功 → 打 `vps-deployed` tag + 自动关 issue（**close=绿/已推**）。CI run 保持绿（NAS 部署成功不污染）。
|
||
> - **查 VPS 还差哪些**：`git log vps-deployed..HEAD --grep='\[vps\]'`（VPS 版本真相 = 移动 tag `vps-deployed`，指向最后部署 VPS 的 sha）。
|
||
|
||
**NAS test 自动部署+验证**：改完代码 `git push origin master` → Gitea Actions 自动跑 ci-cd.yml：
|
||
```
|
||
test(pytest 数据层) → nas-deploy(推 NAS 后端+前端 dist+restart 容器) → nas-verify(login+strategy/list+dbbardata 秒级 gate)
|
||
```
|
||
nas-verify 全绿 = NAS test 已自动部署+验证通过。**VPS 不再自动推**（Gitea 无 environment approval gate；且要 NAS 验证通过才推 prod 的隔离）。
|
||
|
||
**推 VPS prod（nas-verify 绿后，单独触发 vps-deploy.yml，两种方式）**：
|
||
- **人工**：Gitea → Actions → `vps-deploy.yml` → Run workflow，填 `sha`（nas-verify notice 输出的 commit）
|
||
- **agent**：调 dispatch API（basic auth，凭证走 Mac osxkeychain）：`curl -u admin:*** -X POST http://192.168.2.154:3000/api/v1/repos/sanguo/sanguo_vnpy_v2/actions/workflows/vps-deploy.yml/dispatches -d '{"ref":"master","inputs":{"sha":"<full-sha>"}}'`
|
||
（⚠️ MCP 的 claude_dev token 对仓库无 write 权限，dispatch 会 403；agent 走 Mac git credential / basic auth）
|
||
vps-deploy checkout 你传的 SHA（= NAS 验证过的 commit）→ `promote --target vps` → verify_unified_e2e。**严格版本一致**。
|
||
|
||
- **看 CI**：`http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2/actions`，🟢已部署 / 🔴点 run 看 log
|
||
- **workflow**：`.gitea/workflows/ci-cd.yml`(push→NAS 自动) + `vps-deploy.yml`(dispatch→VPS)；**详细+各角色速查**：`docs/session-environment-guide.md`
|
||
- **限制**：pytest 只覆盖 `tests/data_platform`；runner 是 Mac（睡眠时 CI 不跑）
|
||
|
||
**手动 promote（CI 没跑/Mac 睡眠/应急）**：
|
||
```bash
|
||
bash scripts/nas_sync/promote.sh --target nas # 只推 NAS
|
||
bash scripts/nas_sync/promote.sh --target vps # 只推 VPS
|
||
bash scripts/nas_sync/promote.sh # 默认 all(NAS+VPS)
|
||
bash scripts/nas_sync/promote.sh --module sanguo_portfolio --target nas # 单模块只推 NAS
|
||
```
|
||
手动晋升/rollback/数据铁律 runbook：`docs/three-env-code-promote.md`
|
||
|
||
**reload**：VPS 无常驻 web，代码下次 schtask/回测启动自动生效；立即让采集生效：
|
||
`ssh 49.232.102.198 'schtasks /end sanguo-bs-eod && schtasks /run sanguo-bs-eod'`
|
||
|
||
### NAS SSH / Docker 访问
|
||
- SSH：`ssh sanguo-nas`（key 免密，`~/.ssh/config` 配置；不用密码 sshpass）
|
||
- docker 完整路径：`/var/packages/Docker/target/usr/bin/docker`（Synology，**不在默认 PATH**，命令需用全路径）
|
||
|
||
### 目录约定对应（CLAUDE.md global）
|
||
- 开发（本机 Mac，`chufeng` 家）：`~/.openclaw/sanguo_projects/` = `/Users/chufeng/.openclaw/sanguo_projects/`
|
||
- 安装（NAS，`admin` 家）：`~/.sanguo_projects/` = `/volume1/homes/admin/.sanguo_projects/`
|
||
- 同一约定路径 `~/.sanguo_projects/` 在两台机器指向不同位置（用户家不同）
|
||
|
||
## 参考文档
|
||
|
||
- 项目参考：`sanguo_moziplus_v3` 设计文档
|
||
- Gitea 配置：`.claude/gitea-config.json`
|
||
- 工作流脚本：`.claude/workflows/`
|
||
- NAS 部署 vnpy：`docs/deployment/nas-deploy-plan.md`
|