Skip to content

docs: synchronize runtime READMEs and remove internal logs #599

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pigbibi merged 1 commit into from
Oct 16, 2026
Merged

docs: synchronize runtime READMEs and remove internal logs #599

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 5 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ reaches a real order. It is an execution layer only: strategy research lives
in the strategy repositories, and snapshot/validation artifacts come from the
matching snapshot pipeline when a profile needs one.

[Chinese README](README.zh-CN.md)
English | [简体中文](README.zh-CN.md)

> Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only.

Expand Down Expand Up @@ -48,7 +48,7 @@ live-trading, order, token-refresh, notification, or reporting authority.
Access retains the service's existing Cloud Run IAM and internal ingress
protection; deploying and enabling this endpoint is a separate operational step.

## Runtime notification policy (NOTIFY-02, 2026-10-06)
## Runtime notification policy

Runtime-composed cycles keep healthy no-order success and successful dry-run
previews quiet, including previews whose existing `action_done` is true. Real
Expand All @@ -69,27 +69,9 @@ keeps its existing transition-key dedup path instead of gaining another cycle
message. Order hooks, issue notifications, execution markers/claims, strategy
and risk decisions, quantity/state, and scanner alerts-only policy are unchanged.

实现/合并阶段：[#561](https://github.com/QuantStrategyLab/LongBridgePlatform/pull/561)
已于 2026-10-06 合并为 `9a6ed81457795480ea46e45416fd8cc2d1b48548`。
修正后的 [PR CI](https://github.com/QuantStrategyLab/LongBridgePlatform/actions/runs/37459367684)
与该合并提交的 [main CI](https://github.com/QuantStrategyLab/LongBridgePlatform/actions/runs/37459907792)
均成功：各 1473 tests、154 subtests 通过，3 warnings；Ruff、依赖/pin/lockfile
与有界 workflow 测试也通过。本地定向合成回归及业务 AST 核对是补充证据。

首版 [CI](https://github.com/QuantStrategyLab/LongBridgePlatform/actions/runs/37457591638)
曾有 2 failed、1471 passed：非 USD fixture 错把独立 Quote failed 告警当作应静默；
V7 fixture 未接生产已有的显式 validation-only 静音 sink。后续只修两项测试接线/断言，
保留精确订单数量/价格与零提交约束，并验证真实 composer 的 silent=True 零通知、
silent=False 同一 REJECT 仍通知；没有给通用异常分类增加策略例外。

采用/业务阶段仍未验收：本任务没有部署、修改运行配置、读取 secret、连接券商、
发 Telegram 测试消息或调用模型。合并与 CI 通过不证明运行版本已采用、自然周期
静默/异常真实送达、有效路由同一性或跨服务去重；这些证据仍需分别核验。

Known pre-existing limit: final execution-report persistence failures in `main.py`
are logged rather than sent through a dedicated issue notification. This bounded
classification change does not add that separate alert path. Existing marker and
durable-command persistence issue notifications remain in place. Explicit
Final execution-report persistence failures in `main.py` are logged rather than
sent through a dedicated issue notification. Marker and durable-command
persistence failures have their existing issue notifications. Explicit
`validation_only` callers already request a silent cycle sink, and V7 validation
also mutes issue notifications. These isolated validation paths remain unchanged;
attention classification here is not proof that those sinks deliver errors.
Expand Down
40 changes: 39 additions & 1 deletion README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ LongBridge 兼容的券商连接执行，并在真实下单前经过区域化的
它只是执行层：策略研究逻辑留在策略仓库，snapshot/验证产物在 profile 需要时来自
对应的 snapshot pipeline。

[English README](README.md)
[English](README.md) | 简体中文

> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。

Expand All @@ -25,6 +25,42 @@ LongBridge 兼容的券商连接执行，并在真实下单前经过区域化的
- 凭据必须放在 GitHub Secrets、云密钥系统或券商专用密钥系统中，不能提交到 Git。
- 任何 live 下单路径启用前，都应先从 dry-run 或 paper mode 开始。

- 账户新增风险门先消费显式账户快照，再消费当前组合状态。它不从共享研究用的
PerformanceStore 推导生产漂移，也不补造缺失的可选漂移信息。缺少必需账户输入，
或证据处于 review、critical、invalid 状态时，仍会拒绝新增买入。

`GET /account-snapshot` 是独立的只读诊断入口，仅在
`LONGBRIDGE_ACCOUNT_SNAPSHOT_ENABLED=true` 精确设置时启用。它返回按币种区分的
现金、券商报告的余额行（`currency`、`net_assets`、`total_cash`）、仅含数量的持仓、
有界七日读取中已知且脱敏的未终结订单，以及已知近期执行数量。
响应始终是不完整的：SDK 读取不是原子操作，不能证明稳定券商账户 ID、唯一账户
写入者、完整挂单或执行记录、费用、市值，或经独立对账的权益。余额行来自同一次
已有 `account_balance` 读取，适用于 SG/HK/paper；不同币种不会求和，也不会将
余额行纳入稳定对账摘要。缺失或非有限余额会拒绝该快照，不影响独立的对账入口。
该入口不授予恢复、实盘交易、下单、token 刷新、通知或报告权限，沿用服务既有的
Cloud Run IAM 和内部入口保护；部署与启用是独立的运维操作。

## 运行通知策略

由 runtime composer 构建的周期会静默处理健康的无订单成功和成功的 dry-run 预览，
包括已有 `action_done=true` 的预览。真实 pending/submitted/filled 订单事实沿用
现有通知。显式 blocked/rejected/unknown 状态、对账或数据错误、插件加载错误，
在 live 和 dry-run 周期中都需要关注。单独的未知 `no_execute` 不算健康结果；
显式研究合同 `no_order=true` + `execution_authorized=false` 仍不执行交易。
只有已知排队命令与 `waiting_window` 同时存在，才表示正常的持久命令等待。
手动构建配置中保留显式 `notify_no_trade_cycles` 选项以兼容原有行为；runtime
composer 将它设为 false。这个选项不会恢复成功预览的通知。

分类器读取结构化事实和新增的通知原因元组；元组默认为空。已有的小账户、负现金
及等待卖出释放资金的阻断会提供该元组，不改变执行。账户新增风险告警继续使用
既有 transition-key 去重，不另增周期消息。订单钩子、issue 通知、执行标记和 claim、
策略与风险决策、数量和状态，以及 scanner 仅告警策略都保持原有语义。

`main.py` 中最终执行报告的持久化失败只记日志，没有专用 issue 通知。执行标记和
持久命令的持久化失败仍沿用已有 issue 通知。显式 `validation_only` 调用方使用静默
周期通知 sink，V7 validation 也静默 issue 通知。这些隔离验证路径的分类结果
不能证明 sink 实际送达错误通知。

## 普通 profile 与 snapshot-backed profile

普通 runtime profile 通常可以直接基于 market history 或 portfolio state 执行。Snapshot-backed profile 需要先从对应 snapshot pipeline 获取当前 artifact bundle，平台才应该执行。平台不应该自行判断策略资格，而应消费策略仓和 snapshot 仓发布的状态与产物。
Expand Down Expand Up @@ -68,3 +104,5 @@ uv run --no-sync python scripts/check_qpk_pin_consistency.py
## 许可证

详见 [LICENSE](LICENSE)。

显示与通知名称配置：[显示名称](docs/display-names.md)。
Loading