GOAI · 港美股期权智能投研终端

把自然语言期权观点，变成一张带数据来源、定价依据、账户风控与审计链的可核验决策卡。

📖 目录

• 项目简介
• 功能说明
• 架构概览
• 安装步骤
• 使用方法
  • 独立模式（不依赖 DSH）
  • DSH 模式（对话 Agent 编排）
  • 十角色辩论运行时
• 测试与质量
• 项目结构
• 核心原则
• 边界与安全
• 贡献指南
• 许可证
• 免责声明
• 相关文档

✨ 项目简介

GOAI 是 GOAI 世界人工智能开源大赛 · Boundless Agents（无界应用）· 金融服务赛道 的参赛项目，面向有基础期权认知的用户：把自然语言表达的观点，转成带数据来源、港股产品规则、确定性定价、账户风控和审计记录的决策卡。

产品定位是研究与决策支持，不是投资建议，不提供实盘自动交易。

Hero 场景：腾讯 HK.00700 业绩前方向不确定，账户 10 万港币，评估长跨式是否值得交易。

视觉说明：主视觉、管线图和数据板是 Image 2 生成的品牌化设计示意，不代表实时行情或投资收益；终端截图来自仓库已有的 Replay 端到端证据。

系统针对每个场景输出四种产品结果之一：

NO_TRADE 是成功结果。系统不会为了展示下单而调低门槛。

项目形态：一个运行在 DeepSeek Harness（DSH）上的「大号金融插件」。 Python 确定性引擎守护全部金融数字与审计链，DSH 负责 Agent 编排、工具注册、人机审批与对话体验。评审也可以完全不装 DSH，用 python -m src.ui_server 独立运行——两条入口共享同一引擎契约。架构权威文档见 docs/DSH_ARCHITECTURE.md。

🚀 功能说明

确定性引擎与审计

• 五阶段端到端决策管线：场景解析 → 冻结快照 → 自研定价引擎 → Edge/Risk/Action 门控 → 可溯源决策卡 + 审计留痕（src/decision_pipeline.py）；
• 自研定价引擎：Black–Scholes、通用美式二叉树、IV 求解、bump-and-reprice Greeks；港股离散股息 escrowed-spot 定价口径已进入引擎 / IV / Greeks / 管线全链路；
• 港股产品规格解析与模型路由：区分美式/欧式、周选/月选、实物/现金交割等市场差异；
• JSONL + SHA-256 审计链：决策卡、辩论结论、会话度量全程留痕，可校验、可导出（GET /api/decision-card）。

数据层

• SDK 无关的 typed Gateway 合同：稳定快照哈希、typed error、DataEnvelope 统一 LIVE/REPLAY 语义；
• 双 Gateway：Futu Live 只读行情/账户 Gateway 与同合同的确定性 Replay Gateway（不导入 Futu SDK）；
• 线程安全 Snapshot Recorder：严格 JSONL 校验与 legacy 快照迁移读取；
• 实时行情两个阶段：GOAI_DATA_MODE=live 只读报价链路（OpenD 不可用显式报 OPEND_UNAVAILABLE，绝不静默回退 Replay）；GET /api/stream SSE 推送/订阅（默认 2s diff 轮询，GOAI_LIVE_FEED=push 走真实 OpenD 订阅，失败自动回退并推 warning 事件）；
• 多标的项目工作区（data/workspaces.json）：为不同公司分别绑定期权快照、历史行情与投研资料，切换项目后整条研究管线跟随。

Agent 编排（DSH）

• Cordis 插件族：Base Mode（goai-core + goai-run + goai-chat）保证基本使用，goai-macro / goai-research / goai-backtest 为可选插件，用户在 harness/config/goai.plugins.json 勾选；
• GOAI Options Terminal agent preset：一键挂载产品人格、铁律与工作流；
• 十角色多 Agent 辩论运行时：LLM 只出文字，数字/verdict 仍由引擎产出，离线自动回退；
• 项目级 futu-options-agent 工作流：goai_* tools 可用时优先走 DSH 工具。

研究支持

• 投研证据整理与影响研判：公告 / 财报 / 新闻 / 研报 / 行业数据 → 股价与期权影响；Futu 新闻/公告/研报适配器只做格式转换与来源留痕，不虚构时间与标题；
• 宏观研判：情绪量化 + IV 情绪晴雨表 + 政策事件库 + 政治经济学 + 求是检验（只输出定性可能性级别，不产生概率）；
• 政策事件库 + 宏观来源自动监控：美联储/ECB 官方 RSS、FRED、BLS、SEC EDGAR 与中国官方 HTML 来源，DRAFT 入库 → 复核 → promote ACTIVE，Windows 计划任务已注册；
• 知识库检索：中英别名检索 46+ 结构化来源（research/kb_search.py）；
• 腾讯业绩跨式历史回测原型。

研究终端

8 视图桌面研究终端（总览 / 决策卡 / 期权链 / 宏观 / 投研 / 政策库 / 分歧 / 审计），Bloomberg 式深色设计语言，支持对话抽屉、项目工作区、Ctrl+K 研究助理、实时推送状态徽章与静态回退。

决策卡：机会、风险与下一步集中呈现	辩论视图：分歧点、证据引用与研究共识

数据板是产品信息架构的视觉示意：把收益曲线、Greeks、IV 与证据来源放在同一研究面上；真实数字仍以冻结快照和确定性引擎输出为准。

当前状态

完整产品边界与验收标准见 精简版 PRD（v0.8）。

🏗️ 架构概览

五阶段流程的视觉摘要：

flowchart LR
    TERM["🖥️ 桌面研究终端<br/>ui/"] --> API
    DSH["🧠 DSH 编排层<br/>goai-* 插件族 · agent preset"] --> API
    API["引擎契约 src/ui_server.py<br/>JSON API · 127.0.0.1:8000"] --> GW["数据网关<br/>ReplayGateway / FutuLiveGateway 只读"]
    GW --> SNAP[("冻结快照<br/>canonical JSONL")]
    GW --> OPEN["Futu OpenD<br/>127.0.0.1:11111 · 只读"]
    GW --> PIPE["五阶段决策管线<br/>解析 → 快照 → 定价 → 门控 → 决策卡"]
    PIPE --> DEB["十角色辩论<br/>LLM 只出文字"]
    PIPE --> AUD[("审计链<br/>JSONL + SHA-256")]

一句话流程：

DSH 编排层（host 插件 + model tools + skills + preset）
        → 引擎契约（ui_server JSON API，127.0.0.1:8000）
        → Python 引擎（数值铁律：gateway / pricing / pipeline / debate / audit）

📦 安装步骤

环境要求

安装

# 1. 克隆仓库
git clone https://github.com/Alyosha28/GOAi_competition.git
cd GOAi_competition

# 2. 创建并激活虚拟环境
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 3. 安装核心依赖
pip install -r requirements.txt

# 4.（可选）桌面壳（PySide6 + QtWebEngine）
pip install -r requirements-desktop.txt

# 5.（可选）历史行情与 30 日实现波动率（OpenBB / yfinance）
pip install -r requirements-openbb.txt

# 6.（可选）配置 LLM 辩论运行时
Copy-Item .env.example .env   # 然后编辑填入 DEEPSEEK_API_KEY

环境变量

完整配置见 .env.example（.env 已 gitignore，密钥不入库；进程环境变量优先于 .env）。

🎯 使用方法

独立模式（不依赖 DSH，评审可用）

端到端决策管线（无需 OpenD，使用冻结快照）：

python -m src.decision_pipeline

输出 data/decision_card_*.json 与 research/audit/audit_log.jsonl 哈希链记录。

8 视图研究终端（总览 / 决策卡 / 期权链 / 宏观 / 投研 / 政策库 / 分歧 / 审计，含十角色辩论 dock）：

python -m src.ui_server --port 8000

访问 http://127.0.0.1:8000/。对话面板输入自然语言（POST /api/chat）直接驱动「场景解析 → 五阶段管线 → 十角色辩论」；无 DeepSeek key 自动离线回退，Demo 不崩。

只读 API 一览：

桌面壳（可选）：

python -m src.desktop_app

知识库检索：

python research\kb_search.py 流动性
python research\kb_search.py "IV crush" --tag earnings

# 证据整理与影响研判（公告/财报/新闻/研报/行业数据 → 股价与期权影响）
python -m src.research_evidence
python -m src.decision_pipeline --research-items data/research_items_hero.json

# Futu 新闻/公告/研报适配：把 futu-news-search / futu-stock-digest 的真实输出转成 canonical 条目
python -m src.research_sources --keyword Tencent --api-json <news_search_响应.json> --out data/research_items_futu.json
python -m src.research_sources --keyword Tencent --markdown <skill输出.txt> --out data/research_items_futu.json
python -m src.decision_pipeline --research-items data/research_items_futu.json

# 宏观研判（情绪量化 + IV 情绪晴雨表 + 政策事件库 + 政治经济学 + 求是检验）
python -m src.macro_assessment --snapshot data/hero_inputs.json --items data/research_items_hero.json --policy data/policy_events
python -m src.decision_pipeline --research-items data/research_items_hero.json --macro-policy data/policy_events --policy-id fed-fomc-2025-05

# 政策事件库健康检查（核验状态计数、无来源/无 URL/过期标记）
python -m src.policy_library --library data/policy_events

# 自动接入重大金融事件 / 重大金融政策 / 宏观数据（通胀、利率、贸易、就业）
python -m src.macro_source_watcher --dry-run                          # 试跑一轮，不写库
python -m src.macro_source_watcher --run-once                         # 跑一轮并 DRAFT 入库
python -m src.macro_source_watcher --daemon --interval-minutes 60     # 后台定时监控
python -m src.policy_draft_workflow --library data/policy_events      # 复核 DRAFT 摘要与提升就绪度
python -m src.policy_draft_workflow --library data/policy_events --promote <event_id>  # 条件满足才提升 ACTIVE

powershell -ExecutionPolicy Bypass -File scripts\install_watcher_task.ps1 -Minutes 60  # 注册
powershell -ExecutionPolicy Bypass -File scripts\install_watcher_task.ps1 -Remove      # 移除

DSH 模式（对话 Agent 编排）

编排层是 Cordis 插件族（DSH 底层即 Cordis 内核）：Base Mode（goai-core + goai-run + goai-chat）保证基本使用，宏观/投研/回测为可选插件，用户在 harness/config/goai.plugins.json 勾选加载哪些（详见 docs/PLUGIN_ARCHITECTURE.md）。

在 DSH 会话中直接说：

「用 goai_state 看当前决策卡」或「goai_chat：腾讯业绩前方向不确定，账户 10 万港币，评估跨式」

插件自动拉起引擎并返回带快照哈希与门控的决策卡摘要。

• DSH 重启后插件需要重新注册：运行 harness\bootstrap.ps1 获取注册指引，把 harness\plugins\goai-*.host.js（启用者）内容交给会话助手执行 cordis_define + cordis_run 即可（旧单体 goai-bridge.host.js 为 LEGACY 回退，与插件族二选一）。
• agent preset 入口（推荐）：新建 DSH 会话选 GOAI Options Terminal；同步/校验 preset 用 harness\verify_preset.ps1（-Sync 一键同步到 ~\.dsh\.agent-presets），真实挂载冒烟用 node harness\smoke_preset.mjs。
• 已知兼容性问题：若 DSH web profile 装了实验性 @deepseek-ai/dsh-tool-search，preset 层工具会对模型不可见，需先跑 harness\fix_dsh_tool_visibility.ps1（新建会话即生效，无需重启；已运行会话保持旧限制，详见 harness/README.md）。

十角色辩论运行时（LLM 只出文字，数字仍来自自研引擎）

POST /api/chat（或 DSH 的 goai_chat 工具）在五阶段确定性管线之上附加一层「十角色多 Agent 辩论」（src/agents/，参考 TradingAgents 的多角色质证思路）：

1. 首轮：九个分析角色（数据官 / 新闻公告 / 研报对比 / 宏观政策 / 情绪舆情 / 技术资金流 / 期权策略 / 风险管理 / 审计官）并行给出文字结论与证据引用，主席（orchestrator）选出最多 3 个真正影响决策的分歧点；
2. 次轮：只调用分歧相关的角色回辩，主席汇总 research_consensus（summary / stance / confidence / evidence_refs / open_questions）。

铁律（运行时强制）：LLM 输出只解析为文本 + 枚举（stance/confidence）+ 证据引用，引用按白名单过滤（编造的 evidence id 记入 dropped_refs）；所有数字、verdict 与门控仍由冻结快照与自研引擎产出，辩论不改变确定性结论。单角色失败绝不拖垮整场；无 key / 网络失败 / 超时自动回退确定性管线，Demo 不崩。每个角色的结论与最终共识经 SHA-256 哈希链写入 research/audit/audit_log.jsonl（agent_output:<role> / debate_consensus 事件，密钥片段脱敏）。

默认使用 DeepSeek 的 OpenAI 兼容接口（https://api.deepseek.com/v1），零新增依赖（stdlib urllib）。配置方式：复制 .env.example 为 .env 并填写密钥（.env 已 gitignore，密钥不入库；真实环境变量优先于 .env）：

Copy-Item .env.example .env   # 然后编辑填入 DEEPSEEK_API_KEY
python -m src.ui_server --port 8000

未配置密钥时终端顶栏显示「LLM · offline 确定性回退」，页面底部第五面板（十角色辩论 dock）展示每轮每个角色的结论、回辩、证据引用、分歧点与研究共识，全部动态文本用 textContent 渲染防注入。真实调用前请先在 DeepSeek 控制台充值/确认额度，端点缺 key 返回 401 属正常。

🧪 测试与质量

以下命令直接来自当前 tests/ 测试入口：

python -m unittest discover -s tests -v
ruff check src/gateway.py src/payload_validation.py src/futu_adapter.py src/futu_account_worker.py src/replay_adapter.py src/snapshot_recorder.py src/decision_inputs.py tests
mypy --ignore-missing-imports src/gateway.py src/payload_validation.py src/futu_adapter.py src/futu_account_worker.py src/replay_adapter.py src/snapshot_recorder.py src/decision_inputs.py

全量回归：tests/ 覆盖 Gateway 合同、安全边界与离线集成测试，最新全量运行 496 项全绿（python -m unittest discover -s tests -v，含 live 实时链路测试，2026-08-16 实测）。pytest / unittest 双入口可用：

python -m pytest tests -q
python -m unittest discover -s tests -v

📁 项目结构

授权行情、账户数据、订单回执和本地审计日志不进入公开仓库。

🧭 核心原则

1. LLM 只做工具编排和解释，不生成金融数字；场景解析由确定性引擎完成。
2. 行情和账户事实来自 Futu 或明确标记的 Replay；计算来自确定性引擎。
3. 理论价值与 bid/ask、费用、滑点后的可成交口径分开。
4. 风险硬门一票否决；PASS 不代表盈利、成交或投资建议。
5. 比赛版本无实盘入口；模拟动作也必须由用户独立确认。
6. DSH 编排层不重算任何数字，只透传引擎结果；JS 与 LLM 同等受此约束。

🛡️ 边界与安全

Futu Gateway 边界

产品运行时不直接执行 .agents/skills/futuapi 下的 CLI，也不把 SDK Context、Bash 或任意方法调用权交给 Agent。现有 skill 保留为开发诊断和 API 规则参考；正式数据流为：

Decision Agent / UI
        → DecisionInputService
        → MarketDataGateway / AccountReadGateway
        → ReplayGateway 或 FutuLiveGateway
        → 本地 fixture 或 127.0.0.1:11111 OpenD

• P0a 只装配 ReplayGateway，不会导入 Futu SDK 或连接 OpenD；
• P0b 才装配 FutuLiveGateway，仅注册读取能力并使用服务端账户别名；
• P0c 模拟执行是独立边界，当前 Gateway 不包含下单、改单、撤单或解锁方法；
• 当前没有 Futu MCP。单一 Python 宿主直接扩展 typed Boundary 已覆盖当前需求，也避免再增加一层协议和工具发现攻击面；只有出现多宿主或跨语言复用需求后，才在同一 Boundary 外增加本地只读 MCP facade；
• DSH 编排层（goai-* tools）只通过 ui_server 的 JSON API 触达引擎，不越过 DecisionInputService 边界直接调用 SDK；
• Agent 侧唯一粗粒度只读入口 refresh_decision_inputs。

Replay 数据一致性：Replay 默认只读取带完整 schema、内容哈希和业务语义校验的 canonical JSONL。as_of_utc 在 Gateway 构造时固定；每次查询只选择该时点之前、默认 60 秒一致性窗口内的同请求快照，不会按调用顺序拼接不同批次。旧 OpenD 日志包裹的 .json 只用于显式迁移：必须设置 allow_legacy=True，结果标记为 PARTIAL/unverified，不能作为正式发布证据。

Live 验证边界：Live 验证前需由用户手动启动并登录 OpenD；Gateway 不会自动启动、登录或解锁。健康检查未通过时只返回 typed error，不会静默切换为 Replay。2026-08-12 已用正式 FutuLiveGateway.health() 验证本机 OpenD ready=true、行情与交易会话均已登录、server 1009；该验证没有查询账户、订阅或交易。行情 Context 使用 SDK 官方异步初始化与连接等待上限；真实账户读取放在固定 schema、20 秒硬截止且可终止的本地 worker 中，避免 SDK 同步构造无限重试阻塞 Agent 进程。该 worker 是内部安全边界，不是 MCP，也不暴露任意调用。DecisionInputService.max_refresh_seconds 是在组件调用之间和返回后检查的协作式预算，不是整个刷新任务的强制 wall-clock 截止；若未来需要严格的全链路 SLA，应把完整刷新也放入可终止的监督进程，并把剩余预算传递给各数据调用。

自研引擎边界

项目不声称发明 Black–Scholes 或二叉树。自研工作集中在：

• 港股产品规格解析与模型路由；
• IV、Greeks 和情景损益的可复算实现；
• bid/ask、费用、滑点和 tick 的 executable-cost 口径；
• Edge、账户风险和动作门控；
• 数据、计算与决策审计。

当前引擎仍是原型，不能用于真实资金决策。

数据与安全

• 不提交 .env、密钥、交易密码、账户号或订单号；
• 不公开分发账户授权行情和原始 Futu 快照；
• 外部文本按不可信数据处理，不能修改数值、风控或权限；
• 任何模拟提交功能都必须在独立确认和提交前复核之后启用；
• 快照内的 SHA-256 用于发现误改和损坏，不是对恶意本地写入者的身份认证。当前部署假设 fixture 目录由单一受信任用户控制；多用户或不可信目录上线前必须增加 owner-only ACL、签名/HMAC manifest、bundle sequence 和回滚保护。

🤝 贡献指南

欢迎以 Issue 和 Pull Request 形式参与。项目处于比赛阶段，仓库公开用于团队协作与评审。

开发流程

1. Fork 仓库并创建功能分支（feat/、fix/、docs/ 前缀）；
2. 安装开发环境（见 安装步骤），配置 .env（可选）；
3. 修改代码/文档，并配套新增或更新测试；
4. 本地全量回归通过后提交 PR，用中文描述动机、改动与验证结果。

代码规范与验证

ruff check src tests          # 代码风格与静态检查
mypy --ignore-missing-imports src  # 类型检查（核心 Gateway 模块）
python -m pytest tests -q     # 全量测试
python -m unittest discover -s tests -v  # 备选入口

• 数字铁律：LLM 输出只解析为文本 + 枚举 + 证据引用；所有金融数字、verdict、gate 必须来自确定性引擎，不得在 JS 层或 LLM 层重算。
• 审计铁律：默认审计走 audit_log.py 子进程；测试必须注入 fake sink 或关闭审计；审计链只增不减。
• 编码注意：中文文件请保持 UTF-8 无 BOM；不要用 PowerShell 直接改写中文 JSON（避免 BOM 与编码混改问题）。
• 前端契约：保留现有 DOM ID、API 契约与静态快照回退能力；重构不得改变入口文件（ui/index.html / ui/styles.css / ui/app.js / ui/data.js）。

PR 检查清单

• [ ] 新增功能有对应测试，全量回归通过
• [ ] 未引入实盘入口或绕过审计/门控的路径
• [ ] 未提交密钥、账户号、订单号或授权行情
• [ ] 文档（README / docs/ / 相关子 README）已同步
• [ ] 已阅读 NOTICE.md 许可声明（仓库尚未选定开源许可证）

📄 许可证

仓库目前公开用于团队协作和比赛审阅，尚未选定开源许可证；公开不等于授予复制、修改或再分发许可。第三方依赖与服务遵循各自许可与数据授权条款。详见 NOTICE.md。

⚠️ 免责声明

本项目仅用于研究、教育和比赛演示，不构成投资建议。比赛版本无实盘入口；任何模拟动作都必须由用户独立确认。金融数字仅供研究参考，不能用于真实资金决策。

📚 相关文档