Skip to content

docs(readme): 数据时效性纪律 + Roadmap #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mirror29 merged 1 commit into from
May 27, 2026
Merged

docs(readme): 数据时效性纪律 + Roadmap #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
<img src="https://img.shields.io/badge/typescript-5.x-1A1714.svg" alt="TypeScript" />
</p>

<p><em>Every factor proposed, every strategy mutated, every order routed — logged, versioned, reviewable. The LLM writes the code; the engineering harness signs every decision.</em></p>
<p><em>Every factor proposed, every strategy mutated, every order routed — logged, versioned, reviewable. Every number the agents reason on — sourced, <code>as_of</code>-stamped, freshness-checked. The LLM writes the code; the engineering harness signs every decision.</em></p>

</div>

Expand All @@ -30,6 +30,8 @@

Inalpha is a **professional quant agent framework, governed by engineering discipline**. It treats LLM agents not as black-box signal generators, but as code-writing collaborators bounded by hooks, permissions, plan-then-execute approval, and a one-shot signature on every order path.

**Source-attributed by default.** Below the decision harness sits a data discipline: every bar, every quote, every macro print the agents reason on carries its source, its `as_of` timestamp, and a freshness check. Financial reasoning that quietly ages into stale data is the most common way an agent fails *without anyone noticing* — Inalpha refuses to compile that failure mode.

Four capability lines sit on top of that harness:

- **Factor lab** — agents formalize, compute, IC-test, multiple-testing-check, and register factors; every hypothesis is logged with author, timestamp, and the economic-story gate decision.
Expand Down Expand Up @@ -124,6 +126,35 @@ Inalpha splits *scheduling* from *compute*. The agent runtime fans out the grid

---

## Roadmap

Where each capability stands today. Live module inventory and the end-to-end decision sequence diagram live in [`docs/04-current-state.md`](docs/04-current-state.md).

| Status | Capability | Phase | Highlight |
|---|---|---|---|
| ✅ Shipped | Plan/Exec audit trail + Hooks + Permission Engine | D-8a | three-step orders · one-shot signing token · 5 lifecycle hook events · allow / ask / deny tri-state |
| ✅ Shipped | Research → strategy → backtest lineage | D-8c | `deep_dive → compose_strategy → run_backtest` with `research_id` / `backtest_id` threaded through |
| ✅ Shipped | LLM-authored strategies — E1 MVP | D-9 | three sandbox gates (AST · subprocess · `Strategy` contract) + multi-objective fitness + baseline auto-run |
| ✅ Shipped | Risk engine at the HTTP boundary | D-9 | declarative `risk_rules.toml` · pre-trade `enforce` · `risk_locks` table with independent commit |
| ✅ Shipped | Bull / bear researcher debate | D-9 | opposing-stance researchers under `services/research` |
| ✅ Shipped | Scheduler / cron agent mode | D-9 | `scheduler_jobs` + advisory lock + `/api/scheduler/*` management plane |
| ✅ Shipped | RiskGuard per-account isolation | D-9.1a | `RiskGuardFactory` removes cross-account state bleed |
| ⏭️ In Flight | Risk engine — remaining rules | D-9 closing | `cooldown` / `stoploss_guard` / `market_hours` need real `trade_repo` + `market_calendar` |
| ⏭️ In Flight | `askUserChoice` front-end | D-10 (issue #2) | brings the `ask` permission state back from workaround |
| ⏭️ In Flight | `permissions.yaml` configuration | D-8b (issue #4) | replaces the hard-coded `defaults.ts` |
| 🗓️ Planned | Live runner | D-10 (issue #1) | tick-driven `on_bar` writing `paper_positions` / `paper_trades` |
| 🗓️ Planned | Strategy evolution — E2 | D-11 | multi-generation loop + MAP-Elites + Island Model + `unified-diff` mutations |
| 🗓️ Planned | Research-hub nested supervisor | D-10+ | 4 analysts + bull/bear/risk debate as a single closed loop |
| 🗓️ Planned | Factor discovery — L0 → L1 | D-11+ | walk-forward IC + multiple-testing correction + `factor_candidates` table |
| 🔬 Exploring | Skills as procedural memory | TBD | reusable markdown skills with auto-discovery |
| 🔬 Exploring | Alpha Zoo cold start | E1+ | seed factor library with public alphas (Qlib / Kakushadze / GTJA) |
| 🔬 Exploring | E4 `evolve_strategy` MCP tool | E4 | evolution loop exposed to the orchestrator as one MCP tool |
| 🔬 Exploring | Analog backtesting | TBD | similarity-window-driven backtest range selection (STUMPY) |

> **Legend** — ✅ Shipped: behavior already lives in `main` · ⏭️ In Flight: actively in this phase · 🗓️ Planned: scoped for an upcoming phase, not started · 🔬 Exploring: research recorded, no commit date.

---

## Built on the shoulders of

Inalpha is not invented from scratch. It selectively inherits proven designs from prior work, with explicit boundaries around **what we take and what we leave**:
Expand Down
33 changes: 32 additions & 1 deletion README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
<img src="https://img.shields.io/badge/typescript-5.x-1A1714.svg" alt="TypeScript" />
</p>

<p><em>每个因子提案、每次策略变异、每笔订单路由——都有日志、有版本、可复核。LLM 只负责写代码，工程纪律为每个决策背书。</em></p>
<p><em>每个因子提案、每次策略变异、每笔订单路由——都有日志、有版本、可复核。Agent 推理依据的每一个数字——都有来源、有 <code>as_of</code> 时点、有 freshness 校验。LLM 只负责写代码，工程纪律为每个决策背书。</em></p>

</div>

Expand All @@ -30,6 +30,8 @@

Inalpha 是一个**用工程纪律驱动的专业量化 agent 框架**。它不把 LLM 当作黑箱信号源，而把它视作受 hooks / permissions / plan-exec / 一次性签名约束的代码协作者——每一步关键动作都留痕、可版本化、可复核。

**数据默认溯源。** 决策护栏之下还有一道数据纪律：agent 推理依据的每一根 K 线、每一笔报价、每一个宏观数据点，都带来源、带 `as_of` 时间戳、带 freshness 校验。金融推理悄无声息地"用着过期数据继续讲故事"，是 agent 最常见、也最不易被察觉的失败模式——Inalpha 拒绝把这种失败模式编译进系统。

在这套护栏之上，铺开四条能力线：

- **因子实验室。** Agent 负责 formalize、compute、IC 检验、多重检验校正、register；每个假设都带作者、时间戳与经济故事门的判定记录。
Expand Down Expand Up @@ -124,6 +126,35 @@ Inalpha 把*调度*和*算力*分开：agent runtime 负责扇出网格、聚合

---

## Roadmap

每条能力的当前进度。已落地模块清单与端到端决策时序图见 [`docs/04-current-state.md`](docs/04-current-state.md)。

| 状态 | 能力 | Phase | 关键点 |
|---|---|---|---|
| ✅ 已上线 | Plan/Exec 审计链 + Hooks + Permission Engine | D-8a | 三步下单 · 一次性签名 token · 5 类生命周期 hook · allow / ask / deny 三态 |
| ✅ 已上线 | 研究 → 策略 → 回测 lineage | D-8c | `deep_dive → compose_strategy → run_backtest` 全链路串 `research_id` / `backtest_id` |
| ✅ 已上线 | LLM 自创策略 — E1 MVP | D-9 | 三道沙盒（AST 审计 / 子进程 / `Strategy` 协议契约） + 多目标 fitness + baseline 自动并跑 |
| ✅ 已上线 | 风控引擎落到 HTTP 边界 | D-9 | 声明式 `risk_rules.toml` · 撮合前 `enforce` · `risk_locks` 表（独立 commit） |
| ✅ 已上线 | Bull / Bear 研究员辩论 | D-9 | `services/research` 立场对抗研究员 |
| ✅ 已上线 | Scheduler / cron agent 模式 | D-9 | `scheduler_jobs` + advisory lock + `/api/scheduler/*` 管理面 |
| ✅ 已上线 | RiskGuard 账户级隔离 | D-9.1a | `RiskGuardFactory` 去除跨账户状态串联 |
| ⏭️ 进行中 | 风控引擎 — 剩余规则激活 | D-9 收尾 | `cooldown` / `stoploss_guard` / `market_hours` 需接 `trade_repo` + `market_calendar` |
| ⏭️ 进行中 | `askUserChoice` 前端 | D-10（issue #2） | 把 permission 的 `ask` 路径从 workaround 救回 |
| ⏭️ 进行中 | `permissions.yaml` 配置化 | D-8b（issue #4） | 替代 `defaults.ts` 硬编码 |
| 🗓️ 已规划 | Live runner | D-10（issue #1） | 行情 tick 驱动 `on_bar`、写 `paper_positions` / `paper_trades` |
| 🗓️ 已规划 | 策略进化 — E2 | D-11 | 多代演化 + MAP-Elites + Island Model + `unified-diff` 变异 |
| 🗓️ 已规划 | Research-hub 嵌套 supervisor | D-10+ | 4 analyst + bull/bear/risk debate 闭环 |
| 🗓️ 已规划 | 因子发现 — L0 → L1 | D-11+ | walk-forward IC + 多重检验校正 + `factor_candidates` 表 |
| 🔬 探索中 | Skills as procedural memory | 待定 | 可复用 markdown skill + auto-discovery |
| 🔬 探索中 | Alpha Zoo 冷启动 | E1+ | 公开 alpha 库播种（Qlib / Kakushadze / GTJA） |
| 🔬 探索中 | E4 `evolve_strategy` MCP tool | E4 | 进化循环以单个 MCP tool 暴露给 orchestrator |
| 🔬 探索中 | Analog backtesting | 待定 | 历史相似窗口驱动回测区间（STUMPY） |

> **图例** — ✅ 已上线：行为已在 `main` 中 · ⏭️ 进行中：当前 phase 在做 · 🗓️ 已规划：未来 phase 已 scope、未开工 · 🔬 探索中：调研在档、无 commit 日期。

---

## Built on the shoulders of

Inalpha 不是从零发明——它有选择地继承前人的最优解，并明确**借鉴边界**：
Expand Down
Loading