Skip to content

AGENTS.md

Latest commit

 

History

History
150 lines (121 loc) · 8.76 KB

AGENTS.md

File metadata and controls

150 lines (121 loc) · 8.76 KB
Raw

Inalpha · AGENTS.md

多 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.md Python services 设计与职责拆分

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

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

  • 品牌名：始终大写 Inalpha（不写 inalpha / InAlpha / inAlpha） （元用法）
  • 市场覆盖：crypto + 美股 + A股 + 港股 + 全球单股 / 指数 + FRED 宏观； orchestration 按市场类型路由 venue，交易时段由市场日历处理
  • 命名约定：
    • Python 包：inalpha_<service>（snake_case） （占位符不匹配白名单）
    • tools：<service>.<verb> 或 mcp__<server>__<verb>
  • 不要碰：
    • .mastra/（gitignored 构建产物）
    • docs/miro/（gitignored 个人空间）
    • services/_shared/（基础设施稳定层，改前先谨慎评估）
  • tool description 必须三段式："功能 + 何时用 + 何时不用 + 坑"
  • GitHub 协作语言：commit message、branch name、PR / issue / Discussion 的标题与正文、 code review、release note 默认使用英文；仅在本地化内容、原文引用或参与者明确需要时使用其他语言
  • commit message：英文 + <type>(<scope>): <desc>，可标 Phase D-N

4. 起步（clone 之后）

cd packages/orchestration && pnpm i && cd ../..
for service in data paper research factor evolver; do
  (cd "services/$service" && uv sync)
done

# 配置统一 .env（所有 service 共享根目录一份 .env）
cp .env.example .env                    # 在 .env 里填 LLM_PROVIDER + 对应 *_API_KEY
                                        # 详见 README.md §Quick Start 的 provider/model 表
                                        # 运行 Evolver 还需生成 Ed25519 grant 公私钥
                                        # 见 services/evolver/README.md §配置与启动

# 启动开发 DB 并把 schema 升到最新（dev.sh 不会自动做这两步）
cp infra/.env.example infra/.env         # 与根 .env.example 的 DB 默认值一致
(cd infra && docker compose up -d)
(cd infra/migrations && uv sync && uv run alembic upgrade head)

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

# 手动起（如果想让各进程占用独立 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 services/factor   && uv run uvicorn inalpha_factor.main:app   --port 8004 --reload
cd services/evolver  && uv run uvicorn inalpha_evolver.main:app  --port 8005 --reload
cd packages/orchestration && pnpm dev

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

# 跨文件一致性检验（提交前跑一次）
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-12 + E1 生产闭环已落地：单 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 收口运维； D-12 完成 factor 血缘、衰减巡检与因子发现。research-hub 三方辩论已收口。 E1 已拆出 services/evolver:8005：真实 frozen bars、单代 unified-diff 变异、异步 owner-scoped 状态、显式逐次审批与可复现实验元数据；演化链路不会自动 promote、启动策略或下单。 当前收口项是冻结 LLM/定价快照、owner key 即时获取与 token/cost 审计；下一里程碑为 E2 best-parent 多代选择与 early stopping（issue #7），MAP-Elites / Island Model 后置。 详见 docs/04-current-state.md / CLAUDE.md §3 / 仓库根 README.md。

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

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

想做的事 去哪里
加新策略 services/paper/src/inalpha_paper/strategies/
调整策略演化 services/evolver/src/inalpha_evolver/
调整因子库 services/factor/src/inalpha_factor/
加新 tool packages/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、owner scope 或 LLM_CONFIG_ENCRYPTION_KEY：Evolver 只能转交由 orchestration 签发、绑定 owner / operation / config_id / digest 的短时 Ed25519 grant， 由 Dashboard 公钥验签并兑换当前 owner 的模型密钥；首次响应丢失时只允许两分钟内补偿 重试一次。严禁把明文 API key 写入运行记录或日志

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