FundPilot

🧭 面向中国基金决策流程设计的开源工作台，围绕 API + CLI + OpenClaw Skill + Web UI 一体化构建。

更新时间：2026-03-26 11:45:00

English README

FundPilot 是一个面向中国基金投资与复盘流程的开源系统。
它从一开始就不是“只有网页”的项目，而是一个把下面四层一起设计的工作台：

• 📜 契约优先：openapi/ 是 HTTP 接口单一事实源
• 🧰 CLI 优先：人工操作和自动化任务共用同一套命令语义
• 🤖 Skill 优先：OpenClaw skill 只负责任务编排，不直接穿透内部实现
• 🌐 界面反映真实状态：前端展示系统当前真实行为，而不是自带一套偷偷分叉的逻辑

当前前端执行口径已经明确：

• web/：React 18 + Vite 主线前端
• frontend/：Nuxt 4 过渡原型，仅保留 legacy 参考、问题留档与迁移依据

✨ 仓库亮点

• ✅ 面向中国基金场景而不是泛化金融壳子
• ✅ API / CLI / Skill / Web 四层语义统一
• ✅ 公开仓与私有运行环境天然分离
• ✅ 本地工具链、数据库初始化、smoke 验证已成链
• ✅ OpenClaw skill 已有 registry、manifest、launcher、examples
• ✅ 后端已具备数据库驱动读路径，而不是纯 demo stub
• ✅ GitHub Actions CI 当前已打绿
• ✅ GitHub Dependabot 当前告警已清

🧱 当前开发状态

FundPilot 已经不是空架子，目前大致处于“可运行原型 + 向真实系统收口”的阶段。

已完成

• 🚀 本地 Go / Node / pnpm 工具链自举
• 🩺 health API / CLI / 前端纵向链路
• 🗂️ 第一批业务域命名边界：
  • portfolio
  • funds
  • reports
  • automation
• 🧪 API + CLI + skill 的 smoke 验证
• 🗃️ SQL migration 基线与 sample seed
• 📚 OpenClaw skill 文档、registry、manifest、launcher、examples
• 📊 React 主线前端已具备壳层、详情抽屉、页面 smoke 与 live smoke
• 🧠 数据库驱动的第一批后端行为：
  • funds
  • portfolio snapshot
  • reports daily
  • automation job run/status

正在推进

• 继续减少内存回退路径
• 在 Docker daemon 可用时完成本地 PostgreSQL 实库初始化验证
• 让 skill 包装从“可绑定”继续走向“可分发/可复用”
• 扩大前端业务页回归覆盖
• 收口剩余工作区模板与文档入口口径，让 web/ 成为唯一默认开发与验收前端

🏗️ 架构图

flowchart LR
  Skill["🤖 OpenClaw Skills"] --> CLI["🧰 FundPilot CLI"]
  Web["🌐 React Web UI"] --> API["🧱 Go API"]
  CLI --> API
  API --> DB["🗃️ PostgreSQL"]
  API --> Contract["📜 OpenAPI 3.1"]
  CLI --> Contract
  Skill --> Contract

Loading

🗂️ 仓库结构

FundPilot/
  .codex/               # 项目级 Codex 配置与自定义子代理
  .github/              # CI、Issue/PR 模板、仓库自动化
  backend/              # Go API、migration、seed、read model
  cli/                  # Go CLI，人工与自动化统一入口
  web/                  # React + Vite 主线前端
  frontend/             # Nuxt 4 过渡原型（legacy 参考）
  openapi/              # OpenAPI 3.1 契约
  skills/               # OpenClaw skills 文档、registry、manifest、示例
  scripts/              # 本地开发、数据库、smoke、skill 脚本
  docs/                 # 架构、运维、边界、决策文档
  tests/                # e2e / integration 测试入口
  AGENTS.md             # 项目代理行为规范
  ROADMAP.md            # 当前推进计划与里程碑

🧰 技术栈

• 后端： Go 1.26
• CLI： Go 1.26
• 前端主线： React 18 + Vite + React Router + Semi UI + Tailwind CSS
• 前端过渡层： Nuxt 4 + TypeScript（legacy 参考）
• 接口契约： OpenAPI 3.1 + Redocly CLI
• 数据库： PostgreSQL
• Skill 桥接： OpenClaw registry + manifest + launcher 脚本

🚀 快速开始

当前主要开发环境为 Windows + PowerShell。

1. 检查环境

.\scripts\check-env.ps1

2. 启动本地 Go 工具链

.\scripts\bootstrap-local-go.ps1
. .\scripts\dev-env.ps1

3. 安装依赖

corepack enable
corepack pnpm install

4. 初始化本地数据库

.\scripts\init-local-db.ps1

5. 运行主线 smoke

corepack pnpm web:test
corepack pnpm web:build
pwsh -File .\scripts\smoke-web-pages.ps1
pwsh -File .\scripts\smoke-web-interactions.ps1
pwsh -File .\scripts\smoke-web-theme.ps1
pwsh -File .\scripts\smoke-local-live.ps1

6. 本地直接打开网站

corepack pnpm dev:live
corepack pnpm web:open

说明：

• dev:live 会分别拉起本地 API 与 React web 服务
• web:open 会先检查 http://127.0.0.1:3200 可达，再用默认浏览器打开

🧪 验证命令

后端

cd backend
..\scripts\use-local-go.ps1 -GoArgs @('test', './...')

CLI

cd cli
..\scripts\use-local-go.ps1 -GoArgs @('test', './...')

新前端主线

cd web
corepack pnpm test
corepack pnpm build

旧前端过渡层

cd frontend
corepack pnpm test
corepack pnpm build

说明：

• web/ 是当前主线前端
• frontend/ 仅保留过渡验证、问题留档和迁移参考
• 默认前端验收链以 web:test / web:build / web:smoke / web:smoke:interactive / live:smoke 为准

契约与 skill 绑定

corepack pnpm openapi:lint
.\scripts\validate-skill-bindings.ps1

本地数据库相关

.\scripts\init-local-db.ps1
.\scripts\reset-local-db.ps1
.\scripts\verify-db-mode.ps1

🗃️ 本地数据库流

FundPilot 从一开始就区分：

• 公开仓：代码、契约、文档、脚本
• 私有运行环境：本地数据库、日志、fixtures、secrets

当前关键脚本：

• .\scripts\init-local-db.ps1
• .\scripts\reset-local-db.ps1
• .\scripts\verify-db-mode.ps1
• .\scripts\run-smoke.ps1
• .\scripts\build-and-deploy.sh
• .\scripts\manual-deploy-sgp1.sh
• .\scripts\test-cdp.ps1
• .\scripts\test-cdp-automated.js

说明：

• 若 Docker daemon 未启动，数据库相关脚本会明确失败并提示，不会静默回退
• 当前最大的环境侧阻塞就是“本机 Docker daemon 未启动时无法完成实库初始化验证”

🤖 OpenClaw Skills

FundPilot 不把 skill 当成“穿透内部代码的捷径”。
当前统一执行路径是：

OpenClaw Skill -> FundPilot CLI -> API / Domain

已落地资产：

• 技能文档：skills/openclaw/task-models-batch-1.md
• registry：skills/openclaw/registry.json
• manifest：skills/openclaw/manifest.v1.json
• skill 调用入口：scripts/invoke-openclaw-skill.ps1
• CLI launcher：scripts/invoke-fundpilot-cli.ps1
• 参数示例：skills/openclaw/examples

🖥️ 浏览器级验证

为了补足前端的“公网真实页面”和“本地 live 联调”验证，仓库当前提供了三类浏览器测试辅助：

• scripts/test-cdp.ps1：启动独立 Edge CDP 会话，适合人工验收
• scripts/test-cdp-automated.js：通过 Chrome DevTools Protocol 自动做站点冒烟
• scripts/smoke-web-pages.ps1：本地 web/ 页面级 smoke
• scripts/smoke-web-interactions.ps1：本地 web/ 交互级 smoke
• scripts/smoke-web-theme.ps1：本地 web/ 主题切换 smoke
• scripts/smoke-local-live.ps1：本地 API + web 的 live 联调 smoke
• scripts/open-local-web.ps1：本地站点可达后直接打开浏览器

其中 smoke-web-pages / smoke-web-interactions / smoke-local-live 已成为当前 React 主线的正式验收链。

🚢 部署辅助脚本

当前仓库还带有一组偏操作员导向的部署脚本：

• scripts/build-and-deploy.sh
• scripts/manual-deploy-sgp1.sh

它们目前定位为 sgp1 / canary 的辅助脚本，而不是最终的通用发布系统。

📚 关键文档

• 架构总览：docs/architecture/overview.md
• 视觉设计基线：docs/design/visual-design-foundation.md
• 命名与资源边界：docs/architecture/naming-and-resource-boundaries.md
• 数据模型基线：docs/architecture/data-model-baseline.md
• OpenClaw task 设计：docs/architecture/openclaw-task-skills.md
• 本地环境：docs/operations/local-setup.md
• HK + SGP1 切换手册：docs/operations/sgp1-hk-canary-cutover-runbook.md
• 文档入口：docs/README.md
• 前端切换计划：docs/architecture/frontend-cutover-plan.md
• 当前路线图：ROADMAP.md
• 项目代理规范：AGENTS.md

🛣️ 当前优先级

• 继续把 Funds / Reports / History / Portfolio / System 收口成统一工作区模板
• 扩展浏览器级写后可见 smoke，优先覆盖 reports -> dashboard 回流链
• 在 Docker daemon 可用时完成本地 PostgreSQL 真实初始化与验收
• 继续扩展 skill 绑定与 smoke 覆盖
• 逐步退役 frontend/，保持 web/ 为唯一主线前端

🤝 参与贡献

请先阅读：

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md

📄 License

FundPilot 使用 MIT License。