# luoome

> **织机 + 罗网 — 汇聚网罗有价值的信息数据，在面对变化的市场时提供准确的建议。**

luoome 是一个可自行部署的个人投资管理 **advisor agent**。它把账户、持仓、交易、行情、
Strategy、Watchlist、AlertPlan、笔记与建议能力的 34 个核心 Agent Tool 通过 MCP / DSH 暴露，其余纯 UI CRUD 由 Web/CLI 直接调用 Application Service；所有数据织成可追溯事实。

- 作为 **Web** 管理看板、持仓、Strategy、Watchlist 与 AlertPlan
- 作为 **MCP server** 被 Claude Desktop / OpenClaw / Hermes 等 agent 直接调用，并让它们替你做"分析 → 建议 → 行动"的推理

Web、CLI 和 MCP 共用本地 SQLite 数据库（`$LUOOME_HOME/luoome.db`）和单主用户多账户模型（`Account`）。
无需邮箱注册、订阅或独立控制平面进程；后台自动任务（Strategy 日循环、账户计划盘后/盘中盯盘、收盘报告截止、账户绩效估值与策略自治）在 Web 进程开启 `LUOOME_EXPOSE_WRITE=true` 与 `LUOOME_EXPOSE_EXTERNAL=true` 时内置运行。

## 名字

**luoome = 织机 + 罗网**

- **织**：把分散的行情、财报、新闻、StrategySignal、历史持仓织成一张连贯的认知
- **罗**：把市场里有价值的信息数据罗（网）进来，不漏关键信号
- **me**：me，你（用户）是这一切的中心，不是旁观者

面对不断变化的市场，luoome 不替你下单，但**会主动告诉你**：哪里有机会、哪里有风险、哪些决策需要你确认。

## 设计原则

- **Advisor-first**：每一份数据最终都服务于"可执行的投资建议"，不是堆数据。
- **Agent-first**：投研分析能力收敛为 34 个粗粒度 Agent Tool（行情/策略/账户/建议/计划），纯 UI CRUD 属于 Application Service，不给 LLM 伪造工具面。
- **数据自持**：SQLite 保存在本机 `$LUOOME_HOME/luoome.db`，不经过任何云服务。
- **Schema-driven**：Zod schema 是 tool I/O 的事实来源，自动生成 TypeScript 类型、MCP tool 定义、OpenAI function calling schema。
- **Workflow ≠ Tool**：tool 是原子能力，workflow 是组合；workflow 内置编排，tool 暴露给上层 agent。
- **No magic**：每个数据源 / 适配器 / LLM 都显式可插拔，运行时可见。
- **Human-in-the-loop**：建议 ≠ 行动。advice 永远不直接触发交易；下单始终需要人确认。

## 它做什么

### 数据维度（读 + 写）

- 账户（支持单机多账户创建与切换，通过 `X-Luoome-Account-Id` 按请求绑定）
- 持仓、交易、笔记、预警
- 行情快照、日线、技术指标
- 版本化 Strategy + StrategyResult / StrategySignal
- 多来源 Watchlist + 持久的 Strategy → Watchlist 显式订阅 + AlertPlan / WatchTrigger
- 风控指标（VaR、Sharpe、最大回撤、集中度）

### 分析维度（只读）

- PnL、风险敞口、行业暴露
- Strategy 扫描、评分与可解释规则结果
- 只有用户明确订阅后，published operational StrategyRun 才能同步目标 Watchlist；complete 才能结束
  缺失来源，partial/failed 只标 stale，evaluation/trial/withheld/non-publishing/failed 不改 Watchlist
- 多源行情交叉验证
- LLM 推理总结（每日复盘、个股分析）

### 建议维度（核心）

- **个股建议**：基于技术面、基本面、StrategySignal 与 LLM 综合判断，输出 buy / sell / hold / watch / avoid 决策
- **持仓建议**：每个持仓的继续持有 / 加仓 / 减仓 / 清仓建议
- **市场观点**：每日大盘观点、行业轮动、热点板块
- **风险预警**：跌破止损位、触发风控规则、异常波动
- **账户决策与复盘**：对建议、交易计划或成交记录复盘结论、教训标签与关联成交，单表覆盖更新
- **confidence 校准**：按当前账户的明确反馈展示各信心桶的填报盈利占比与样本数，缺失盈亏不计为零

每条建议都带：**决策 + 信心度 + 有效期 + 核心论点 + 支持证据 + 反证 + 风险点 + 免责声明**。

## 仓库结构

Bun workspace monorepo：

```txt
packages/
  core/        纯领域类型 + 不变量（无 IO）
  db/          Drizzle schema + repository 实现
  tools/       34 个核心 Agent Tool 注册表 + Zod → TS/MCP/OpenAI 自动生成
  adapters/    行情 / LLM / 通知 / 券商 等外部依赖适配
  workflows/   内置编排：review / scan / diagnose / advise
  mcp/         MCP server，把 tool registry 暴露给外部
  cli/         命令行入口
apps/
  web/         Hono + 同源静态仪表盘 + 单进程后台调度
  agent-runtime/ DeepSeek Harness (DSH) + Cordis 独立 Agent Host
docs/          全部文档（架构 / 路线图 / 安全 / 交接 / 用户手册 / 设计文档 / backlog）
homebrew/
  luoome.rb    Homebrew formula（brew tap KowL/luoome && brew install luoome）
```

## 环境变量

Web、CLI 和 MCP 共用下列单机环境变量：

| 变量 | 默认 | 说明 |
|---|---|---|
| `LUOOME_HOME` | `~/.luoome` | 数据目录（含 `luoome.db`、`ai-models.json`） |
| `LUOOME_MARKET_PROVIDER` | 必填 | 仅支持 `real`：Eastmoney → Tencent → Sina；全源失败明确报错 |
| `LUOOME_MARKET_SOURCES` | `eastmoney,tencent,sina` | 行情数据源启用顺序；可显式加入 `tushare`（需 `TUSHARE_TOKEN`）/ `fuyao`（需 `FUYAO_API_KEY`） |
| `LUOOME_PORTFOLIO_BENCHMARK_STOCK_ID` | `000300.SH` | 账户绩效默认 benchmark；首期为沪深300，可用真实指数日线覆盖时才显示可用 |
| `LUOOME_STOCK_UNIVERSE_SOURCES` | `eastmoney,sina` | 股票目录数据源顺序；支持 `eastmoney,sina,tushare` |
| `LUOOME_LIMIT_UP_LADDER_SOURCES` | `eastmoney` | 连板天梯数据源顺序；当前仅注册 `eastmoney` |
| `TUSHARE_TOKEN` | — | 任一路由显式启用 `tushare` 时必填 |
| `LUOOME_MCP_CONFIG` | `$LUOOME_HOME/mcp-servers.json` | Web Agent 的受控只读 MCP 客户端配置；服务需显式启用、工具和场景白名单，见[接入说明](./docs/USER_GUIDE.md#只读-mcp-服务供内置-agent-使用) |
| `LUOOME_AI_CONFIG` | `$LUOOME_HOME/ai-models.json` | AI SDK 模型目录；默认路径缺失时自动生成，格式见 [`ai-models.example.json`](./ai-models.example.json) |
| provider 密钥变量 | 由目录指定 | `apiKeyEnv` 引用环境变量名，密钥不写入模型目录 |
| `LUOOME_RESEARCH_VAULT` | — | 单机 Obsidian Vault 绝对路径 |
| `LUOOME_RESEARCH_ROOT` | `Research` | Vault 内参与研究索引扫描的相对目录 |
| `LUOOME_RESEARCH_MANAGED_ROOT` | `Research/Luoome` | luoome 可创建受管研究文件的相对目录，必须位于 research root 内 |
| `LUOOME_RESEARCH_REMOTE_SYNC` | 关 | `=git`：启用独立 Git-only Vault 拉取 workflow；仍需 write/external 双 opt-in |
| `LUOOME_EXPOSE_WRITE` | 关 | `=true`：允许 write 类能力 |
| `LUOOME_EXPOSE_EXTERNAL` | 关 | `=true`：允许 external 类能力 |
| `LUOOME_EXPOSE_TRADE` | 关（**硬卡**） | `=true` 时 MCP server 启动即抛错退出（trade 永不暴露） |
| `LUOOME_FEISHU_WEBHOOK_URL` | — | 飞书通知 webhook；可在 Web 设置页配置 |
| `LUOOME_A_SHARE_HOLIDAYS` | — | 追加 A 股休市日（逗号分隔 `YYYY-MM-DD`），与内置日历 union |
| `LUOOME_HOLIDAYS_FILE` | `$LUOOME_HOME/holidays.json` | 节假日历文件路径；文件损坏静默 fallback 到内置 |
| `LUOOME_STRATEGY_SCHEDULE_LEASE_MINUTES` | `30` | Strategy schedule claim 租约分钟数；范围 5～240 |
| `LUOOME_STRATEGY_DATA_CONCURRENCY` | `8` | Strategy 日线准备并发；范围 1～64 |
| `LUOOME_STRATEGY_DATA_MAX_STALENESS_TRADING_DAYS` | `1` | Strategy 成员日线允许陈旧交易日数；范围 0～30 |
| `LUOOME_STRATEGY_DATA_MAX_RETRIES` | `2` | Strategy 单成员行情最大重试次数；范围 0～5 |
| `LUOOME_STRATEGY_DATA_REQUEST_TIMEOUT_MS` | `20000` | Strategy 单成员行情请求超时（毫秒）；范围 500～120000 |
| `LUOOME_HOST` / `LUOOME_PORT` | `127.0.0.1` / `5173` | Web 服务监听地址和端口 |
| `LUOOME_LOG` | info | `debug` / `info` / `warn` / `error` / `silent` |

默认行情链路无需供应商密钥：报价由东方财富、腾讯、新浪按顺序提供；指数有东方财富与腾讯，
分钟 OHLCV 有腾讯原生 K 线。批量报价逐源补齐缺失股票，最后只对剩余项逐股重试；
已成功的报价保留原来源。缺失时间的报价会标记 `retrieval`，不能作为盘中行动的可信时间证据。
Tushare 与扶摇继续按显式配置接入，各能力与最近运行状态可通过 `get_market_data_status` 查询。

AI 模型由 adapters 内的 AI SDK Provider Registry 统一管理。`providers` 可声明
`openai-compatible`、`anthropic` 或 `gateway`，`profiles.generation` 与
`profiles.agent` 可分别选择 `provider:model`、默认生成参数和运行预算。旧
`LUOOME_LLM_*` / `LUOOME_AGENT_*` 不再读取。

模型目录支持 Kimi 与 DeepSeek preset：Kimi 默认使用 `kimi-k3`、
`https://api.moonshot.cn/v1` 和 `MOONSHOT_API_KEY`；DeepSeek 默认使用
`deepseek-v4-pro`、`https://api.deepseek.com` 和 `DEEPSEEK_API_KEY`。两者均通过
OpenAI-compatible Chat Completions 接入。

Web、CLI 和 MCP 共用 `$LUOOME_HOME` 下的模型目录与环境配置，也可在 Web「设置」页直接修改并热生效。

## 文档

| 文档 | 用途 |
|---|---|
| [docs/README.md](./docs/README.md) | **完整文档导航**：产品需求、技术设计、运维手册与历史归档 |
| [docs/USER_GUIDE.md](./docs/USER_GUIDE.md) | 用户手册：安装 / CLI / Web / MCP / 多账户 / 复盘 / 校准 / FAQ |
| [skills/luoome/SKILL.md](./skills/luoome/SKILL.md) | 外部 Agent 接入：Skill 编排 + luoome MCP typed tools |
| [AGENTS.md](./AGENTS.md) | 编码 Agent 开发规范：架构边界、实现约定、测试与安全规则 |
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | 架构核心：模块、概念、数据流、安全模型、advisor 模型 |
| [docs/ROADMAP.md](./docs/ROADMAP.md) | 版本演进与交付状态 |
| [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md) | 贡献者指南：开发环境、测试与扩展方式 |
| [docs/SECURITY.md](./docs/SECURITY.md) | 副作用分级、鉴权、密钥与审计要求 |

## 快速启动

```bash
# 一键安装（macOS / Linux，无需 git clone，自动装 Bun + 源码 + luoome 命令）
curl -fsSL https://raw.githubusercontent.com/KowL/luoome/main/install.sh | sh

# Windows（PowerShell 5.1+）
irm https://raw.githubusercontent.com/KowL/luoome/main/install.ps1 | iex

# 或者从本仓库安装依赖
bun install

# 启动单机 Web（当同时设置 LUOOME_EXPOSE_WRITE=true 与 LUOOME_EXPOSE_EXTERNAL=true 时自动挂载后台调度循环）
LUOOME_MARKET_PROVIDER=real LUOOME_EXPOSE_WRITE=true LUOOME_EXPOSE_EXTERNAL=true bun run web
```

浏览器打开 `http://127.0.0.1:5173`，首次使用可在「设置」页创建真实账户并在顶栏切换。

`./bin/luoome start`、`restart` 和 `web serve` 也可启动单机 Web，默认后台运行，日志追加到
`$LUOOME_HOME/logs/luoome.log`；需要前台调试时加 `--foreground`。

## 自动任务

当 `LUOOME_EXPOSE_WRITE=true` 与 `LUOOME_EXPOSE_EXTERNAL=true` 同时开启时，Web 进程内置启动策略日循环、收盘报告截止检查、盘中账户计划盯盘、账户绩效估值与策略自治调度。

单机 CLI 的 `watch` 与 `workflow run` 能力也可由外部 cron 显式触发，每次 workflow 运行落一条 `WorkflowRun` 审计：

```cron
# 盘后数据闭环：目录完整快照 + 相关股票前复权日线 + 数据健康汇总
30 16 * * 1-5  luoome workflow run post-market-data
# 盘后补齐信号 T+1/T+3/T+5 真实表现（未到期样本保持 pending）
10 18 * * 1-5   luoome workflow run complete-strategy-observations
# 收盘复盘与周报：报告先保存，通知失败只会把 WorkflowRun 降为 partial
0 18 * * 1-5   luoome workflow run closing-report --mode scheduled
0 19 * * 5     luoome workflow run weekly-report --mode scheduled
# 开盘简报：周一会自动读取前一交易日，而不是自然日前一天
0 9 * * 1-5    luoome workflow run opening-report --mode scheduled
# 可选 Research Vault Git 拉取：仅干净工作树 + fast-forward，先备份再重建索引
```

- 预警试跑不写正式触发或改变边沿状态。盘中循环持有执行租约；失败及中断投递由后续盘中循环补偿，当日最多尝试三次，重试间隔 1 分钟、5 分钟，仍受每日额度限制。
- `post-market-data`：非交易日跳过；目录失败不阻断相关股票日线，局部失败返回 `partial`。
- 内置 `run-strategy-schedules`：每次 tick 原子抢占到期配置；非交易日或暂停策略跳过并推进，
  多实例与手工正式运行由租约防重。策略启用推荐政策后，完成运行会按评分、排名、每轮上限和冷却
  生成可追溯 Advice，并可通知；Advice 失败不回滚运行，且不会自动交易。
- `complete-strategy-observations`：以信号基准后的第 N 根 qfq 日线补齐事实观察；日线不足时
  保持 `pending`，当前无指数日线时 benchmark 明确标记 unavailable；配置的 T+n 节点完成后可触发
  对应股票的阶段 Advice。也可手工运行 `strategy-recommendations`，输入策略、运行和推荐政策。
  `strategy-daily-cycle` 在发布正式运行后会自动创建 T+1/T+3/T+5 候选并补全到期观察。
- 历史缺口用 `luoome tools call backfill_strategy_observation_candidates --input '{"since":"2026-08-12T00:00:00+08:00","limit":100}'` 显式补建；只补候选、不自动补全，重复执行幂等，单次最多 500 个 run。
- 三类报告 workflow 在 `scheduled` 模式默认通知；可在 `--input` 中显式传
  `{"notify":false}` 关闭。相同类型、范围与周期重复运行会更新同一份 Report。
- `sync-stock-universe` 仍可单独人工执行；完整分页通过校验后原子提交，12 小时内有成功版本时默认跳过。

## 状态

**当前模型 — Strategy + 统一 Watchlist + AlertPlan**

- 看板聚合账户 PnL、建议、AlertPlan 健康度和最近触发
- 持仓完整录入闭环与交易流水
- Strategy 不可变版本、校验、发布、dry-run/正式运行与信号事实
- Watchlist 支持 manual / strategy / ai / portfolio / import 多来源与研究阶段
- Strategy → Watchlist 需要显式持久订阅；可在 Strategy 设置页或对应 Tool 中取消，重复 producerRun 幂等
- AlertPlan 引用 Watchlist，提供单轮试跑、全局心跳与 Trigger 审计
- Web 默认仅监听 `127.0.0.1`，mutation 统一显式能力开关 + 同源校验
- `luoome start` 与 `web serve` 启动单机多账户 Web 并内置挂载后台自动任务

历史演进见 [docs/ROADMAP.md](./docs/ROADMAP.md)。