HunterCode 本地AI投研终端架构深度剖析:6大核心容器 + Temporal 调度如何撑起一套私有化系统
HunterCode 本地AI投研终端架构深度剖析:6大核心容器 + Temporal 调度如何撑起一套私有化系统
HunterCode(hunter-community)是一套开源、可自托管的本地 AI 投研终端,覆盖 A股 / 港股 / 美股,由 6 大核心容器 + Temporal 工作流调度组成:对话推理在你机器上跑,仓位数据不出你的硬盘(BYOK · Apache 2.0)。本文带你从 docker-compose.yml 出发,看懂这套系统的分层架构、职责边界,以及 Temporal 如何以"六大交易时点"驱动一套崩溃可恢复的模拟交易闭环。
一、为什么是"容器化 + 工作流"双引擎?
先给新手一个心智模型。HunterCode 的难点在于它同时要干两件性质完全不同的事:
| 场景 | 特点 | 需要的能力 |
|---|---|---|
| 交互式投研对话(查行情、读财报、多智能体辩论) | 请求驱动、延迟敏感 | 常驻服务、流式响应 |
| 定时交易流程(开盘同步、撮合、收盘对账) | 时间驱动、绝不能漏 | 持久化调度、崩溃恢复、幂等重试 |
前者靠 6 个核心容器组成的常驻服务栈解决,后者靠 Temporal 工作流调度(外加 fin-worker / paper 两个专用容器)解决。这也是为什么部署文件里会出现 profiles: ["fin"]——智能炒股模块是一组可选组件,单独拉起。
二、6 大核心容器总览:一次 docker compose up -d 起了什么
全部编排定义在 docker-compose.yml(根目录),只引用预构建镜像,无需本地构建。默认栈共 6 个常驻容器:
| 容器 | 镜像 | 一句话职责 | 暴露端口(默认) |
|---|---|---|---|
postgres |
postgres:16-alpine | 业务库 + Temporal 元数据库,数据卷 hunter_pg_data 持久化 |
5442 |
redis |
redis:7-alpine | 缓存与会话 | 6379 |
api |
hunter-community-api | FastAPI 业务中枢:行情、选股、策略、MCP 反调、多智能体投研 | 8100 |
web |
hunter-community-web | Next.js 前端,五大工作台 + 聊天界面 | 3100 |
opencode(主机名 daemon) |
hunter-community-opencode | Agent 推理内核(AtomCode 5.1.0 Fork),常驻会话、MCP 工具执行、hook 加速 | 内部 13456 |
llm-shim |
hunter-community-llm-shim | 大模型协议清洗层:修复并行 tool_calls 的 index、剥离思考标签 | 内部 3999 |
💡
opencode服务在网络里同时挂了daemon与opencode两个别名(见 compose 中networks.default.aliases),这是从 OpenCode 内核平滑换核到 AtomCode 内核留下的兼容设计。
容器之间的依赖链
compose 用 depends_on + condition: service_healthy 保证启动顺序,形成一条清晰的健康检查链:
postgres / redis(健康)
└─→ api(健康)
├─→ paper ─→ fin-worker
├─→ web(还依赖 opencode)
└─→ opencode(还依赖 llm-shim)
一个值得新手注意的细节:api 对上游 LLM 的调用默认先经过 llm-shim(LLM_SHIM_URL=http://llm-shim:3999/v1)。为什么多这一层?因为实测某些网关在流式返回并行工具调用时不携带 index 字段,严格按 OpenAI 协议的客户端会把多个工具调用合并成一个脏调用,进而触发工具死循环。llm-shim 内置的 ToolCallIndexer 会按 id 首次出现顺序把 index 补回去(配置动机详见 deploy/env.example 的注释)。
三、fin 画像:智能炒股的四件套
在 compose 里加 --profile fin 会额外拉起 4 个容器,构成"智能炒股"闭环:
| 容器 | 镜像 | 职责 |
|---|---|---|
temporal |
temporalio/auto-setup:1.25 | 工作流引擎,元数据存在 postgres 的 temporal 库 |
temporal-ui |
temporalio/ui:2.34.0 | 工作流可视化面板(仅绑 127.0.0.1:8233) |
paper |
hunter-community-paper | 全仓唯一模拟账本 + 确定性风控 |
fin-worker |
hunter-community-fin-worker | Temporal Worker + 策略意图→命令翻译层 |
启动命令只有一条(见 fin-worker README):
docker compose --profile fin up -d
paper:唯一能写账本的服务
apps/paper/README.md 用三条"不能破的边界"定义了它的性格:
- 只做模拟 ——
PAPER_MODE必须是PAPER,否则拒绝启动; - 只追加 —— 账本表在数据库层只授
INSERT/SELECT(受限角色fin_paper_rw),服务里不存在改历史/删流水的端点,指向管理员角色直接起不来; - 余额是算出来的 —— 不存"余额字段",可用/冻结 = 流水最后一行。
fin-worker:只翻译、不下判断
fin-worker README 同样列了三条边界:不碰账本(依赖里没有数据库驱动,源码守卫测试 tests/test_no_ledger_access.py 会当场变红)、不做策略分析、不带兜底调度(全仓不允许第二个调度器)。它只做一件事:把已成形的 StrategyDecision 翻译成 paper 的 HTTP 命令。
四、Temporal 调度深度解析:六大交易时点如何运转
4.1 调度只认一个"权威"
apps/fin-worker/app/schedules.py 的注释写得非常直白:Schedule 建在 Temporal 服务端,不是 Worker 进程里。这意味着:
- 杀掉并重启
fin-worker,调度不会丢(重启后ensure_schedules发现日历已存在,原样复用); - 没有 crontab、没有进程内
while True定时器——"留了兜底就等于两套调度器都以为自己是权威"。
4.2 三个市场 × 六类角色
时点定义在 apps/fin-worker/app/points.py:同一套角色形状,每个市场各自一组时刻,时区用 IANA 名(Asia/Shanghai / Asia/Hong_Kong / America/New_York),夏令时交给 Temporal 的 ScheduleSpec(time_zone_name=...) 自动跟随。
| 市场 | 时区 | 六个时点(当地) |
|---|---|---|
CN_A |
Asia/Shanghai | 09:15 / 09:30 / 11:30 / 13:00 / 14:55 / 15:30 |
HK |
Asia/Hong_Kong | 09:15 / 09:30 / 12:00 / 13:00 / 15:55 / 16:15 |
US |
America/New_York | 09:15 / 09:30 / 12:00 / 14:55 / 15:55 / 16:15 |
六个角色(POINT_SHAPE)与业务含义:
| 角色 | Temporal 工作流 | 干什么 |
|---|---|---|
preopen (09:15) |
fin.point_0915 |
同步交易日历 + T+1 日切 |
decide (09:30) |
fin.point_0930 |
策略出意图 → 提交委托 |
match_a/b/c |
fin.point_1130/1300/1455 |
挂单再撮合(尾盘一次) |
close (15:30) |
fin.point_1530 |
收盘撤单 → 估值 → 对账 |
另外还有三条 K 线 ETL 触发(fin.market_etl,A 股/港股/美股各一条)。
节假日怎么处理? cron 表达式只负责"周一到周五"(1-5),节假日由工作流第一步读 fin_market_calendar 挡掉,且分三种情况:交易日继续、非交易日跳过、日历缺数据则跳过并告警(未知 ≠ 交易日)。某市场非交易日空跑,不影响其他市场照常执行。
4.3 崩溃恢复与"不重复下单"
workflows.py 里所有时点工作流都继承同一个 _PausableWorkflow(支持暂停/恢复/查询当前任务),核心保障机制:
- 可持久化:工作流状态存在 Temporal 服务端,不在 Worker 进程里;
- 可恢复:Worker 被杀重启后,未完成工作流从执行历史恢放,未完成 Activity 重试;
- 幂等重试:Activity 是 at-least-once 语义,所以每处写操作都带业务幂等键(app/bridge/idem.py,从"项目 + 交易日 + 时点 + decision_id"推导,不含随机数)。重试拿到同一个键 → paper 的
fin_idempotency表返回原回执 →fin_trade绝不会多出第二笔; - 业务检查点:每个时点在
fin_job表登记一条 checkpoint,写清"跑到哪一步"。
4.4 盘后进化链路:复盘 → 影子 → 观察 → 提案
六个时点之外,收盘后还串着一条"受控自进化"工作流链(延迟均可配,见 fin-worker README 的环境变量):
15:30 收盘对账
→ ReviewWorkflow(+30min 盘后复盘,沉淀经验)
→ ShadowWorkflow(+15min 独立影子盘验证)
→ ObserveWorkflow(+30min 观察)
→ ProposeWorkflow(+2min 生成白名单参数提案,收紧方向自动生效)
全程留痕可回滚,PAPER_MODE 恒为模拟盘——这正是"本地 AI 投研"与"实盘交易"之间最安全的一条线。
五、交互面:api 容器里的多智能体投研引擎
调度栈管"定时",api 容器管"即时"。其中最有代表性的是价格异动多智能体分析引擎 apps/api/agents/graph.py,纯 Python asyncio 实现(不依赖 LangGraph),流程是:
Phase 1(并行): MarketAnalyst + SentinelNewsAgent
↓ 条件路由:触发止损条件?
YES → ExitStrategyAdvisor → RiskJudge → FinalDecision
NO → BullResearcher ⇄ BearResearcher(多空辩论 2 轮)
→ ComprehensiveJudge → RiskJudge → FinalDecision
共享状态容器定义在 agents/state.py,辩论历史、已核实事实、过滤后事实都挂在 EnhancedAgentState 上。20 个 MCP 服务(含 8 个券商只读 MCP,共 66 个工具)+ 22 个金融 SKILL(见 skills/ 目录)则由 daemon 容器在执行层调用,API 侧通过 HERMES_API_URL=http://api:8000 与 ATOMCODE_DAEMON_URL=http://daemon:13456 形成互调闭环。
六、架构要点速记(给想动手改的人)
- 改行情/选股/策略逻辑 → 看
apps/api/app/(routers 76 个、services 221 个文件,按业务域组织); - 改对话内核行为 → 优先用 hook / SKILL 配置,而不是改
daemon镜像(设计纪律:"不改内核,只依赖四个外部接口",见 docs/design/技术方案v0.1.md); - 改交易时点 → 只改数据库
fin_market_rule.points(db/migrations/0030_market_rule.sql 落表),DEFAULT_POINTS只是兜底; - 想加第二调度器 → 测试会拦住你:apps/fin-worker/tests/ 里
test_workflows.py明确断言"无兜底 crontab / 进程内定时器"。
七、如何把这套架构跑起来
一键部署脚本与示例配置都在仓库内:
- 环境变量样例(含每个变量为什么这么填的注释):deploy/env.example
- 一键部署:
bash deploy/up.sh(源码栈),或直接docker compose up -d(预构建镜像栈) - 云平台模板:deploy/ 下提供 Zeabur / Sealos / Railway / 1Panel / Coolify 五套模板
- 数据库迁移按序号执行:db/migrations/(0001 → 0058)
一句话总结:HunterCode 的架构精髓是**"职责边界写死在代码里"**——账本只有一个入口(paper)、调度只有一个权威(Temporal)、推理只走一条清洗过的模型链路(llm-shim → daemon),而 Temporal 的持久化工作流 + 业务幂等键,让这套跑在本地硬盘上的模拟交易系统具备了生产级的可靠性。所有数据本地化、所有过程可审计,这就是"本地 AI 投研终端"区别于云端 SaaS 的根本所在。
⚠️ 免责声明:本项目是投研分析工具,所有输出为 AI 生成内容,仅供研究参考,不构成任何投资建议。投资有风险,决策需谨慎。






