From 28c3a319ae005e2396d5f8ac5ad1013e804ec900 Mon Sep 17 00:00:00 2001 From: zlt Date: Wed, 2 Sep 2026 11:50:59 +0800 Subject: [PATCH] =?UTF-8?q?README=20=E8=A1=A5=20HTTP=20=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E8=A1=A8=E4=B8=8E=E9=87=8C=E7=A8=8B=E7=A2=91=E7=9C=9F=E5=AE=9E?= =?UTF-8?q?=E7=8A=B6=E6=80=81=EF=BC=8C=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E8=B7=AF=E5=BE=84=E7=BA=A0=E6=AD=A3=EF=BC=9B=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=20CLAUDE.md=20=E9=A1=B9=E7=9B=AE=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 29 ++++++++++++++++++++------- 2 files changed, 82 insertions(+), 7 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..310fa02 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,60 @@ +# CLAUDE.md — akg-factor-bridge 项目指引 + +本文件写给之后在这个仓库工作的 Claude 会话。先读完再动手。 + +## 一句话定位 + +数据底座 astock-kg 与通用因子平台 quant_factor_service 之间的因子导出桥：基座只暴露只读视图，桥算全部子因子并在桥内合成复合因子 akg_score，写平台因子表并注册元数据；平台管存储、调度、评价。桥不 import 两边任何代码，靠 .env 三处数据库连接独立工作。 + +## 文档地图（先读哪份） + +- 唯一事实源：docs/量化因子导出与合成设计.md（v2.0）。注意：astock-kg 仓库 docs/ 下的同名文档是 v1、方案已被推翻，别读。 +- README.md：架构、六因子口径、HTTP 接口表、用法、上游约束、里程碑状态。 +- docs/选股说明_下游对接.md：选股计划的业务逻辑与下游对接。 +- docs/选股计划入池_对接说明.md：与决策系统夜间推理的对接（含池深与 PMS 下单候选深度的关系，第 7 节）。 + +## 部署与联动（2026-09-01 现状） + +- 桥部署在 192.168.16.155 的 8300 端口，常驻容器跑 uvicorn，**无热加载**：代码更新要在桥机拉代码并重启桥容器（重启前须经用户同意，避开每早 07:10 因子构建窗口）。 +- 上游：astock-kg 基座（PG 视图 sql/astock_kg_slot_views.sql），基座机 tlai4090 即 192.168.16.178（SSH 端口 2280，用户 tlai）。 +- 下游甲：决策系统 bionic_trader（192.168.16.188:38000），每晚认知扫描读 Mongo 股票池分组 AKG_PLAN（pool.py push 写入）。 +- 下游乙：PMS（tradingSystem 仓库）建仓不读 Mongo 池，直接调本桥 GET /plan 取主榜前 PMS_PLAN_TOP_N 名做下单候选。 +- 基座前端今日页的交易计划、个股页的计划判决，都代理本桥接口（基座 .env 的 AKG_BRIDGE_BASE）。 +- 时区：容器与各服务器为国际时间，调度排程按北京时间，谈时间先说清是哪一路。 + +## 纪律（历次用户令，逐条必守） + +1. 全程 Docker：不在宿主机直跑 pip、python、psql。开发机没有 Python 依赖环境是常态，需要真实依赖的测试用一次性容器跑（见下）。 +2. 只读优先：分析、对账、体检工具全是纯查询；写路径只有因子表写入（common.write_factor）、计划文件生成与 Mongo 入池（pool.py push）。动写路径前想清楚。 +3. 口径变更先看数据：改 UPSIDE_NEG_TOLERANCE、POOL_THEME_CAP 这类口径旋钮之前，先跑 score_lab.py 对比器拿读数，改口径属拍板事项。 +4. 代码里"勿回退"注释都是实测教训（例：观察档下界、锚强度排序），改动碰到就先读注释里的案例。 +5. 交易系统或因子平台仓库有哨兵断言测试，其登记清单已丢失：往平台侧加表、加调度前，必须先在那边仓库重建登记清单再动手。 +6. 提交信息用中文短句说清楚做了什么。 + +## 测试（改完必跑） + +纯逻辑单测三个，不连库。test_plan_verdict.py 全离线，开发机系统 Python 直接跑；另两个需要 pandas 与 fastapi 实体，在有 Docker 的机器用一次性容器跑全套： + + # 开发机（零依赖，秒出） + python3 test_plan_verdict.py + + # 基座机 tlai4090（全套三个，一次性容器，跑完即弃） + rm -rf ~/akg_tmp_bridge_test && git clone -q git@192.168.18.24:zlt/akg-factor-bridge.git ~/akg_tmp_bridge_test && docker run --rm -v ~/akg_tmp_bridge_test:/w -w /w python:3.12-slim bash -c "pip install -q -r requirements.txt; for t in test_plan_verdict.py test_pool_logic.py test_xxl_trigger.py; do echo == \$t ==; python \$t || exit 1; done"; docker run --rm -v ~/akg_tmp_bridge_test:/w python:3.12-slim rm -rf /w/data /w/__pycache__; rm -rf ~/akg_tmp_bridge_test + +预期：三个测试分别打出 ALL OK 与 ALL PASS。2026-09-01 实测全过。 + +## 代码地图 + +- run.py：命令行入口（views 自检、register 注册、build 构建、freeze 冻结、apply-views 建视图、probe 体检、push-pool 入池）。 +- factors.py：六因子构建器（upside、heat、event、transmission、gate、score）与事件极性表。 +- plan.py：当日计划装配与渲染（collect、generate）。 +- pool.py：计划写 Mongo 股票池 + 触发决策系统增量补扫（decide 是入池决策纯函数，有单测）。 +- plan_reconcile.py：逐票对账（explain 命令行）与结构化判决（verdict，供 API），同一段判决代码两种出口。 +- api.py：常驻 HTTP（/plan、/plan/verdict 等，端口 8300）。 +- xxl.py：XXL-JOB 调度触发入口（子进程执行保证每次重读 .env）。 +- freeze.py：每日输入冻结（可复现性的落地件，manifest.json 是审计线）。 +- tracks.py：赛道三路映射解析。score_lab.py：口径对比器。probe.py、chain_diag.py：体检工具。 + +## 已知上游约束 + +README"已知的上游约束"一节列了三条要在 astock-kg 侧修的（quiet 截断、成员抽样无排序、行情快照日错位）与传导覆盖偏低的主因（板块级异动源缺失），桥侧只告警、修不了。 diff --git a/README.md b/README.md index 8a9604a..5bacf6a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ astock-kg（知识图谱基座）↔ `quant_factor_service`（通用因子平台 子因子；**复合因子 `akg_score` 在桥内用自洽的景气度漏斗算出**，平台只负责注册/存储/ 调度/评价，不参与合成。 -> 设计与决策依据见本工程根目录 `量化因子导出与合成设计.md`（v2.0，唯一事实源）。 +> 设计与决策依据见本工程 `docs/量化因子导出与合成设计.md`（v2.0，唯一事实源）。 > ⚠️ `astock-kg/docs/` 下的同名文档还是 v1，讲的是**已被推翻**的平台拟合合成方案，别读。 > 本工程**不 import** 基座或平台任何代码，只靠 `.env` 里三处数据库连接工作， > 可单独部署于任意能连通三库的服务器。 @@ -162,10 +162,25 @@ docker compose exec akg-factor-bridge python run.py freeze --date 2026-07-24 `source_type` 不是这个字符串，事件因子会被过滤成空（会显式告警），按实际值改 `EVENT_SOURCE_TYPES`。 -## 未完成（设计 §8 里程碑） +## HTTP 接口（桥常驻 API，端口 8300，全部只读除 refresh） -- **G2**：`config/frontier_tracks.yml` + `tracks.py` + `data/track_members.csv` - （赛道门槛 C；需要基座先出第五/六个插槽视图 `v_factor_segment_members` / - `v_factor_segment_edges`——`industry_pools` 成员级没有 segment/layer，图谱在 Neo4j）。 -- **G3**：漏斗合成 `akg_score` + `akg_gate`（0/1 全池出行，让平台分层能读出门槛的价值）。 -- **G4**：回填与仪表盘（upside 历史重建走「给基座 `sync_consensus` 加 `asof` 参数」）。 +| 端点 | 作用 | +|---|---| +| `GET /health` | 存活探针 | +| `GET /plan/dates?limit=30` | 有计划文件的日期清单 | +| `GET /plan?date=&format=json\|md&top=&obs_top=` | 当日选股计划（基座今日页 `/plan/today` 与 PMS 下单候选都读它） | +| `POST /plan/refresh?date=` | 重生成当日计划文件 | +| `GET /plan/verdict?codes=300750,SH600438&date=` | 逐票『计划判决』（2026-08-18 PMS 对接加）：decision（main/observe/reject/absent）+ 与命令行 `plan_reconcile` 逐字同口径的 verdict_text + score/rank/tier/赛道/图谱证据。单票数据异常或代码形态认不出只报该票 error，不崩整批 | +| `GET\|POST /api/v1/xxl/daily-build?key=&steps=&date=` | XXL-JOB 平台触发盘前链（build→plan→push-pool，白名单步骤、单实例互斥、回调结案）；`.env` 不配 `XXL_TRIGGER_KEY` 则整组禁用 | + +逐票对账的命令行形态（同一段判决代码）： +`docker compose exec -T akg-factor-bridge python plan_reconcile.py 300750 [--date 2026-08-04]` + +## 里程碑状态（设计 §8） + +- **G2 赛道门槛 ✅**：`config/frontier_tracks.yml` + `tracks.py`，三路映射 + （环节锚 > 链锚 > 主题弱锚），基座插槽视图 `v_factor_segment_members` 已就位。 +- **G3 漏斗合成 ✅**（07-30 拍板）：`akg_gate` + `akg_score` 进 `FACTORS`， + `build all` 一并日更；两锚三档 + 两段式组内分。 +- **G4 回填与仪表盘（未完成）**：upside 历史重建走「给基座 `sync_consensus` 加 + `asof` 参数」，动工前先与基座侧排期。