Inalpha

June 17, 2026 · View on GitHub

多 AI 工具兼容的协作入口。任何 AI 编程工具——Cursor / OpenAI Codex / Aider / Continue / Cline / Claude Code / Sourcegraph Cody——读取本文件即获得 Inalpha 项目的硬约束与导航。 Claude Code 用户额外读 CLAUDE.md（项目级 memory，含 Claude Code 专属细节）。

1. 项目一句话定位

Inalpha = AI agent 编排 + 多 Python kernel 的量化实验框架：agent 自己挑有效因子择时、写完整策略代码、在审计下自我进化，下单必经机器审批（LLM 不直连）；研究可叫"投资大师团"辩论，外加一个硬隔离于决策的狐神签彩蛋。工程模式重度借鉴 Claude Code 的 hooks / permissions / plan-exec / MCP。采用 AGPL-3.0（见 LICENSE）：随便用，但魔改后做托管服务必须公开源码。

2. 先读这些

文件何时读
README.md / README.zh-CN.md项目首页（双语）
CLAUDE.md用 Claude Code 时（其他工具也建议读，内容重叠 80%）
docs/00-context.md项目背景、边界、不做什么
docs/01-architecture-overview.md三层架构总图
docs/03-kernel-design.mdPython services 设计与职责拆分

内部设计文档、决策记录、思考过程在私人空间维护，不入开源仓库。

3. 协作硬约束（任何 AI 工具必须遵守）

  • 品牌名：始终大写 Inalpha（不写 inalpha / InAlpha / inAlpha） （元用法）
  • 市场约束：仅 crypto，不涉及 A 股 / 美股盘前盘后逻辑
  • 命名约定：
    • Python 包：inalpha_<service>（snake_case） （占位符不匹配白名单）
    • tools：<service>.<verb> 或 mcp__<server>__<verb>
  • 不要碰：
    • .mastra/（gitignored 构建产物）
    • docs/miro/（gitignored 个人空间）
    • services/_shared/（基础设施稳定层，改前先谨慎评估）
  • tool description 必须三段式："功能 + 何时用 + 何时不用 + 坑"
  • commit message：中文 + <type>(<scope>): <desc>，可标 Phase D-N

4. 起步（clone 之后）

pnpm i                                  # Node 包（packages/orchestration）
uv sync                                 # Python 包（services/*）

# 配置统一 .env（所有 service 共享根目录一份 .env）
cp .env.example .env                    # 在 .env 里填 LLM_PROVIDER + 对应 *_API_KEY
                                        # 详见 README.md §Quick Start 的 provider/model 表

# DB schema 升到最新（dev.sh 不会自动跑；漏跑会导致 paper 服务 500：表不存在）
cd infra/migrations && uv run alembic upgrade head && cd ../..

# 一键起所有 service（推荐）
bash scripts/dev.sh                     # data:8001 + paper:8002 + research:8003 + mastra:4111
bash scripts/dev.sh logs                # 跟随日志
bash scripts/dev.sh stop                # 停止全部

# 手动起（如果想要 4 个独立 terminal）
cd services/data     && uv run uvicorn inalpha_data.main:app     --port 8001 --reload
cd services/paper    && uv run uvicorn inalpha_paper.main:app    --port 8002 --reload
cd services/research && uv run uvicorn inalpha_research.main:app --port 8003 --reload
cd packages/orchestration && pnpm dev

# 操作者控制台（apps/dashboard）—— 推荐的功能主入口，只读运行时看板
# 组合 / Live Runner / Agent 活动 / 策略实验室 / 因子库 / 风控；黑白双主题 + en/中
# 直接读根 .env（service URL + JWT_SECRET 继承），后端起着即可连
cd apps/dashboard && pnpm i && pnpm dev    # → http://localhost:3001
# 设计语言见 apps/dashboard/design.md；agent 对话功能后续也会并入控制台

# 跨文件一致性检验（提交前跑一次）
bash scripts/check-consistency.sh

# D-9 定时 agent 模式（默认关，需 SCHEDULER_ENABLED=true 起 mastra）
cd packages/orchestration
pnpm scheduler:trigger --list                  # 列全部 jobs
pnpm scheduler:trigger daily_btc_deep_dive     # 手动触发一次
# admin 页：直接 open scripts/scheduler-admin.html（默认连 4111）

# D-9 LLM 自创策略 E1 MVP（orchestrator 内置策略不够用时自动走）
# 链路：research.deep_dive → compose_strategy（拒绝时） → paper.author_strategy(code=...)
#       → paper.run_backtest(candidateId=...) → fitness 排序 → paper.promote_candidate
#         （permission ask · 用户在对话里二次确认）→ paper.start_strategy 按行情自动跑（D-11）
# 入口：services/paper/src/inalpha_paper/strategy_authoring/（三道沙盒 + fitness）
#       packages/orchestration/src/tools/strategy.ts（4 个 tool：author / list / get / promote）

5. 各工具的额外建议

  • Claude Code：本文件 + CLAUDE.md 同时加载；.claude/settings.local.json 是个人配置（不入 git）
  • Cursor：本文件是 .cursorrules 等价物；也可在 .cursor/rules/ 下 link
  • OpenAI Codex / GitHub Codex CLI：AGENTS.md 是它默认查找的标准位置
  • Aider：aider --read AGENTS.md 启动
  • Continue / Cline：把本文件路径加入 system prompt 配置
  • GitHub Copilot：考虑同时维护 .github/copilot-instructions.md（短版本指向此文件）

6. 当前 Phase 状态

Phase D-11（多市场模拟盘）已落地：单 orchestrator + plan/exec 三件套 （create_plan / approve_plan / execute_plan）+ hooks + permissions deny + approval_token 状态机（D-8/D-9）→ LLM 自创策略沙盒 + 风控引擎 + 多市场数据 （D-9/D-10）→ 跨币种 cash + live runner（promoted 候选按行情自动跑，机器审批 走护栏内 plan/exec）。D-11.1 收口了 live runner 的信任边界与健壮性 （candidate 归属校验 / per-account run 上限 / 错误可重试分类）；D-11.2 收口运维（PnL 净口径扣手续费 / 运行时长 TTL auto-stop / build 退避 + 错误分类）。factor 库（services/factor:8004，pandas-ta/Alpha101/qlib + IC 有效性）已落地、策略族扩到 6。 下一里程碑：research-hub 嵌套 supervisor（issue #6）/ E2 多代演化（issue #7）。 详见 docs/04-current-state.md / CLAUDE.md §3 / 仓库根 README.md。

Phase 状态可能漂移——以 scripts/check-consistency.sh 的检查结果为准。

7. 该往哪里改（任务路由）

想做的事去哪里
加新策略services/paper/src/inalpha_paper/strategies/
加新 toolpackages/orchestration/src/tools/
调整内核services/_shared/ 之外的 services 模块
不确定先开 issue 讨论，再动

8. 红线（任何 AI 工具都不能跨）

  • ❌ 不绕过设计决策直接改架构（先讨论再动）
  • ❌ 不 commit .mastra/ / .env / node_modules/ / docs/miro/ / 任何 secret
  • ❌ 不在 services/_shared/ 加项目特有逻辑（破坏复用）
  • ❌ 不写跳过测试 / 跳过 hook 的 commit（--no-verify 等）——遇阻先 ask user
  • ❌ 不在不公开源码的前提下把 Inalpha（或其修改版）当作网络服务对外提供（LICENSE: AGPL-3.0；需闭源 / 托管 SaaS 请提 issue 谈双重许可）
  • ❌ 多租户上线前不给每用户发各自 JWT：promote 审批的 askCache 已按已认证 sub 隔离（mastra identity middleware 从 Bearer 注入 → with-hooks 读），但 dashboard 现给所有人发同一个 CONSOLE_SUBJECT 常量 token；要真隔离须让 dashboard 按登录用户发各自 JWT，否则所有人共享一个 sub scope（A 的审批被 B 复用）。详 #91 / mastra/index.ts identityMiddleware

本文件是协议入口，短小为美。详细规则在公开的 docs/00-03 与 docs/brand/。