个人理财助手

起服务（Docker，详见该仓库 README）

快速启动

```bash git clone https://github.com/SnowWarri0r/licai cd licai

启动

python run.py

演示模式（不录数据先看效果）

```bash python scripts/seed_demo.py --use # 备份你的 DB + 写入演示数据 (4 只 A股 + 11 笔外部资产)

重启服务器, 看演示效果

python scripts/seed_demo.py --restore # 看完恢复真实 DB ```

也可以 --peek 只生成 portfolio.demo.db 不动当前 DB。

复制配置模板

cp config.example.py config.py

或改 config.py 里的 tdx_base_url = "http://localhost:8080"

启动日志出现 `TDX 数据源已启用: <地址>` 即接通。**不配也能用**——详情页会收敛成只有「日」一个页签，实时行情、日线、看板与榜单都不依赖它。

<h3 id="zsxq">可选：知识星球（只读观点面）</h3>

现有情绪面全是指标（涨停/炸板/赚钱效应/连板高度），缺**文本面**——盘该怎么定性、社群在讲什么逻辑。接上之后 agent 多三个只读工具（`get_zsxq_digest` 读最近主题 / `search_zsxq` 按关键词搜 / `read_zsxq_file` 读附件正文），走知识星球官方 MCP 端点。

不用装 npm 包、不依赖系统 Keychain，填个 URL 就能跑；`services/mcp_http.py` 是个一百来行的极简 MCP streamable-HTTP 客户端（只实现 `tools/list` + `tools/call`，不引 SDK）。

五条约束（默认全关，不勾星球等于没这功能）：

- **只读白名单** — 远端 21 个工具里有 `create_topic` / `create_topic_comment` / `set_topic_digested` / `set_topic_tags` / `create_note` 这些写口，白名单（`_READ_TOOLS`）只放行取数的 10 个；万能口 `call_zsxq_api` 仅在「`GET` + 取文件直链」这一条组合下放行（见下方附件那条），其余一律拒且不发请求（有测试盯着）
- **可按星主收窄** — `scope=by_owner` 每个星球单独开关，默认不开：实测有的星球发帖人不算「星主/合伙人」，一开就筛成空（只剩几个月前的附件帖），所以默认全量、内容太杂再收
- **原文不落库** — 只在内存里过一遍送进模型，落 SQLite 的只该是提炼后的结论；不做成付费内容的本地镜像
- **附件按需读、不批量爬** — 帖子里的研报/会议记录（docx·pdf）可按 `file_id` 单份取正文（`read_zsxq_file`），字节只过内存不落盘、有大小上限、扫描件取不到文字会如实说明。取直链要走远端那个万能 `call_zsxq_api`，所以额外钉死成**只允许 `GET` + 只允许「取文件直链」这一条 path**（有测试覆盖 POST / 其他 path / 路径穿越都被拒）。**平台对每个附件按次计数**，所以只做按需单取，不做遍历下载
- **单独一档可信度** — 返回带 `stance=opinion`，回答里按 `[星球观点]` 标注并带作者日期；数字与结论一律以 `[实测]`/`[联网]` 为准，原文里的操作倾向只当「有人这么说」的舆情记录

api_key 拼在 URL 里，所以：**存本机数据库**（不进 `config.py`）、界面只回显 `host/path`、启动日志也只打脱敏值、只收 `https`。没接入时这三个工具不塞给模型（40 → 43 动态过滤），免得模型去调然后拿一串 error。

> 内容版权与平台条款属于你和知识星球之间的事：请用**自己的账号**、遵守所在星球的规则，本项目只提供只读通道。

<h3 id="provider">可选：扩展数据源（provider 插件）</h3>

上面数据源清单里的每一条都是**公开接口**：不要账号、不要凭证、不伪装客户端。装了这个项目，开箱就是这些。

有四样不在其中，只有商业终端才有——接它们要带**你自己的账号凭证**去打对方的接口：

| 缺的口径 | 自带公开源能到哪 |
|---|---|
| 深度龙虎榜席位的**身份标签**（知名游资 / 量化通道） | 东财只给裸营业部名；本地名号表 `data/seat_names.json` 能补一部分 |
| **板块级**集合竞价异动 | 盘口异动里有个股级的竞价事件，没有板块维度 |
| 机构**季报**行业增减仓 | 龙虎榜机构专用席位只反映短线盘口 |
| 三周以上的**涨停历史** | 东财涨停池只有滚动约 3 周 |

那是你自己与对方的关系，不该由这个仓库替所有装了它的人预置一条直连通道。所以**本仓库只定义协议，一个实现都不带**：自己写一个包（或装一个别人写的）实现 `services/providers/base.py` 的协议，再选中它。

然后在 设置 → 扩展数据源 里点选, 或:

export MARKET_PROVIDER='mypkg.myprovider:Provider'

包若在 `licai.providers` 入口点组里登记过，设置页会把它列成「已装可选」，点一下即可，不用手敲导入路径。

两条边界都有测试钉着：

- **装上 ≠ 启用** —— `pip install` 本身不会让任何数据源生效，仍要显式选一次
- **列候选只读打包元数据，不 import 任何 provider** —— 否则光是装上，它的代码就会在每次打开设置页时跑一遍

**不配也能用**，而且是默认状态。上表四样对应的界面各自收敛：

- 「资金·机构」是唯一整页依赖它的，没接时给一句说明而不是留白
- K 线浮层里那层席位身份标签提示「未接入 —— 上面的龙虎榜（东财口径）不受影响」
- 情绪温度计里那条第二数据源、涨停档案的历史回填与题材标签，直接不出现
- agent 少挂 4 个工具（40 而非 44）

其余一切照常。

协议、能力清单与一个最小实现见 [docs/providers.md](docs/providers.md)。

> 凭证与服务条款属于你和那个数据源之间的事：请用**自己的账号**、自行判断是否合规。本项目只定义接口形状，不内置任何实现、不分发任何凭证。

<h3 id="analyzer">可选：分析插件（analyzer）</h3>

provider 是**多一路数据**，analyzer 是**在已有行情上多一层计算**：输入某只票的前复权日K，输出对这段 K 线的结构化解读。你自己的量价模型、形态识别、风险打分，都可以做成一个包挂进来，不用改本仓库。

两者的区别：

| | provider | analyzer |
|---|---|---|
| 做什么 | 补数据源 | 在日K上算东西 |
| 同时启用 | 只能选一个 | 装几个挂几个，互不影响 |
| 入口点组 | `licai.providers` | `licai.analyzers` |

约定（完整说明在 services/analyzers.py 顶部）：

• 类上声明 name / display_name / min_bars（至少要多少根日K），可选 context_symbols（还需要哪些指数日K，比如 sh000852，由主程序取好传入）
• analyze(code, bars, stock_name, live_last, context) 返回一个 dict。前端只认一套通用展示结构：头部标签 chips、条目 items（标题 / 说明 / 徽标 / 若干统计）、近期出现过的日子 timeline、状态行和脚注。插件怎么算都行，翻译成这几个字段就会被渲染
• live_last 告诉插件末根是盘中未收盘的 bar（量只走了一部分），由插件自己决定要不要用它
• 可选的复盘接口 review_points / review_catalog：给定一串历史买入日，返回每天前一交易日收盘时的判定和对照统计，买点回看会把它们和你的实际结果并排列出
• 单个插件报错只影响它自己；一个都没装时，K 线弹窗和复盘页不出现任何插件相关的东西

装上以后，K 线弹窗头部多出插件的标签，主图下方多一块解读面板。和 provider 一样，本仓库只定义接口，不带任何实现。

🔍 问问市场 · 市场 AI 问答（独立页）

一个挂了 40 个数据工具（接知识星球+3、扩展数据源+4，满配 47）的问答 agent，自由问个股涨跌 / 市场风格 / 资金主线 / 产业链 / 自己的成交，它自己决定调哪些工具取数据（并行调用），再客观解读——只给客观信息，不给任何买卖建议。流式打字机展示每一步在调什么工具，支持多轮追问（"它明天呢"会顺着上文标的继续）。

工具覆盖七个维度

<details> <summary><b>行情 / 走势</b>：裸K量价具体给哪些字段</summary>

• 每日开 / 收 / 高 / 低位置 + 量比
• 单根 K 线形态：光头光脚阳 / 长上影十字…
• 结构形态扫描：头肩顶底 / 双顶 / 收敛三角 / 跳空缺口 / 量价背离 / 2B 假突破·假破位
• 多周期摘要：5d/20d/60d 涨幅、距 20 日高、均线排列

</details>

<details> <summary><b>资金面</b>：能回答哪几类具体问题</summary>

</details>

<details> <summary><b>其余四个维度</b>的细项</summary>

• 业绩面 — 个股问答时自动带业绩预告凭据
• 基本面 / 公司画像 — 公司画像：主营业务 + 细分行业 + 主营构成 + 控股/实控背景（判国资 / 央企 / 中科院系 / 民营）；客观红线清单：监管处罚 / 退市 / 业绩预亏 / 商誉减值 / 问询 / 减持 / 解禁抛压扫描
• 消息面 — 宏观快讯合了东财 + 财联社 + 同花顺 + 金十；read_url 把搜到的研报原文读全再下结论，免 key。A/港股走东财，美股换 Yahoo（东财的美股关键词搜索会返回几天前的旧稿，异动归因看的就是时点）
• 美股也有一手材料 — 公告走 SEC EDGAR，按 8-K 的 Item 编号说清是哪类事（1.01 重大协议 / 3.02 增发…），而不是只报个表单号；同业对比走 Yahoo 的相关标的
• 我的持仓 — 覆盖个股 + 场内 ETF + 场外基金（份额拆分自动折算），可按日期区间筛；含全资产配置问答（现金/理财框架 + 现状分析）与ETF 题材透视（问「我的 ETF 挂没挂羊头」直接出逐股贴题）
• 产业链全景 — 一览表列 环节 / 标的 / 角色 / 均线 / 5d / 60d / 距20高 / 量能，一眼看清整条链强弱分布

</details>

几条贯穿的"读盘原则"（来自实战反馈，固化进 agent）：

• 裸K量价为主轴，资金流只作线索 — 当下拆单 + 多子账户操作让"超大单=主力"的分档失真，所以以价格行为 + 量能为准，资金净流入只当参考，背离时点明
• 可信度分级 + 可溯源 — 关键数字标 [实测]（本地工具）/ [联网]（搜到的，带来源时间）/ [待核实]（仅记忆）；接了知识星球则多一档 [星球观点]（社群里某个人的看法，不作为数字依据）。联网结论正文带可点角标，点击直跳原文核实，底部列完整来源
• 分清"正在发生"和"背景脉络" — 几个月前的旧政策不冒充"这两天在炒"，行情数据周末锚定到最近交易日（不说成"今日"）
• 美股分时段说清楚 — 盘前/盘后的价格与正股时段的收盘价是两个时点，答案里分开写（"收盘 216.00 −7.8%，盘前 240.56 +11.4%"），不混成一个涨跌
• 严格不输出操作建议 — 描述"市场在奖励动量"可以，绝不说"所以你该追"；方向性进出永远留给你自己定

<details id="ask-run"> <summary><b>切走了那一轮还在不在</b>：跑在服务端，不挂在这个页面上</summary>

问一句要跑十几秒到一分钟（agent 要串好几轮工具）。这段时间里切到别的页、关掉抽屉、刷新、甚至关掉页面——那一轮都照跑，答完自己落库，回来接着看，没回来也能在历史里翻到。

原来不是这样，而且是两层原因叠在一起（只改一层现象还在）：

• 执行权在浏览器：切页 → 组件卸载 → abort() → 客户端断开 → 服务端的响应任务被取消，agent 在下一个 yield 处就地死掉。拿最小探针实测过：客户端一走，生成器当场 CANCELLED
• 落库在最后一步：会话是"存第一条消息"时才建的，而前端要等完整答案才存。一轮没答完就一行都不写——所以历史里连"我问过什么"都没有

现在开跑就建会话并把问题写进去（历史里立刻看得到），agent 在独立任务里跑到底，事件按序进缓冲，前端拿游标拉、断了照游标续拉。前端断开只是"不看了"。

• 走开不杀，所以给了明确的「停」；「新对话」只是不看了，它会自己跑完进历史
• 过程也落盘（ask_run 表，答案照旧进 ask_message）：服务重启（改代码 / 掉电）那一轮确实会死——asyncio 任务不可能跨进程活下来——但它跑到哪一步还在。启动时把上一进程留下的 running 全标成 interrupted，不自动重跑（重跑要再烧一遍 token，该不该跑由人决定）；再去跟看那一轮，会重放已经跑出来的步骤，末尾明说「跑到一半服务重启了，没跑完」再收尾，不让界面一直转
• 事件落盘按 0.5s 合并窗口写（每条都写就是一轮几十次开关连接），收尾必写

拿 kill -9 实测过：被杀时盘上是 running + 已落的事件；重启日志打出「上次没跑完的 agent 轮次 1 条, 已标记为中断」；再跟看那一轮，拿到已跑出的步骤 + 中断说明 + done。

</details>

<details> <summary><b>答错了怎么不再错第二遍</b>：回归评测集 + 纠正沉淀 + 缺口台账</summary>

prompt 里已经堆了几十条读盘原则，靠"再加一句嘱咐"来修 bug 的边际收益越来越低，而且改动无法验证——所以做了四件配套的事，全部离线、不影响正常问答：

闸门是刻意的：prompt 对单个词都敏感（曾因词表里缺"主题/标题"两个词让模型吞掉整句首句），自动往里加规则最容易造成规则互撞。所以只自动提案，不自动生效；否决的也留着，下次挖掘不会把它原样再提一遍。

两个踩出来的细节：

• 失败的答案当场落盘（logs/eval-fail-<用例>.txt），断言消息带上命中处的原文。因为一条用例跑一次要十万 token 且答案不稳定——实测同一条"一次挂一次过"，靠回头重跑分不清是真答错还是断言写歪了
• 断言别用裸子串。「涨跌」里含「跌」、「公司在未上市阶段」里含「未上市」，两次误报都是这么来的

</details>

4. 配置建议（AllocationAdvisor）

3 套预设模板（保守 / 平衡 / 激进）× 按总资产 4 档，显示当前 vs 目标配比 + 该加多少 / 该减多少。

分档是因为海外配置对小资金不划算（开户 / 汇兑 / 单笔门槛都有固定成本），所以海外比重随资金量上行：< ¥30 万 / ¥30-100 万 / ¥100-500 万 / > ¥500 万。

10 个桶按「实质」穿透——ETF / QDII 先按底层归到对应桶，不再有一个笼统的「基金」桶。以「¥30-100 万」这一档为例：

设计原则写在 AllocationAdvisor.jsx 的 TEMPLATE_MATRIX 上方：保守 = 现金+理财+债基 ≥ 60%；平衡 = 权益与稳健 50:50；激进 = 权益+加密 ≥ 70%。