diff --git a/README.zh-CN.md b/README.zh-CN.md index 3354c49..82969c9 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -13,7 +13,7 @@ UsEquityStrategies 是 QuantStrategyLab 的美股策略包。为 QuantStrategyLa - **策略包**：保存可复用策略代码、元数据和运行入口。 - **Snapshot 流水线**：生成 feature snapshot、ranking、回测和发布证据。 - **执行平台**：把策略接到券商、dry-run 检查、通知和 live 部署控制。 -- **共享基础设施**：沉淀契约、配置、适配器、插件和审计 workflow，供多仓复用。 +- **共享基础设施**：维护契约、配置、适配器、插件和审计 workflow，供多仓复用。 本仓库负责策略代码和元数据，不保存券商凭据，不直接提交订单，也不替代 live enable 前需要看的 snapshot 和回测证据。 diff --git a/docs/research/global_etf_confidence_vol_gate.md b/docs/research/global_etf_confidence_vol_gate.md index 149430e..e5d7703 100644 --- a/docs/research/global_etf_confidence_vol_gate.md +++ b/docs/research/global_etf_confidence_vol_gate.md @@ -1,13 +1,5 @@ # Global ETF Confidence Vol Gate Research - -## 中文摘要 - -- 用途：本文档围绕 `Global ETF Confidence Vol Gate Research`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Candidate`、`Production-Like Backtest Snapshot`、`Interpretation`、`Rollout Recommendation`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 _Updated: 2026-05-08_ ## Candidate diff --git a/docs/research/income_layer_design.md b/docs/research/income_layer_design.md index b542156..f144d6b 100644 --- a/docs/research/income_layer_design.md +++ b/docs/research/income_layer_design.md @@ -1,14 +1,7 @@ # Income Layer Design Conclusions +[简体中文](income_layer_design.zh-CN.md) -## 中文摘要 - -- 完整中文版见 [`income_layer_design.zh-CN.md`](income_layer_design.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。 -- 用途：本文档围绕 `Income Layer Design Conclusions`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Decision`、`Design Rules`、`Leveraged Profile Review`、`Core Default Review`、`Reading the Defaults`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 _Updated: 2026-06-04_ ## Decision diff --git a/docs/research/income_layer_design.zh-CN.md b/docs/research/income_layer_design.zh-CN.md index 1e13250..827a9fe 100644 --- a/docs/research/income_layer_design.zh-CN.md +++ b/docs/research/income_layer_design.zh-CN.md @@ -1,14 +1,6 @@ # 收入层设计研究结论 - -## English summary - -- Full English version: [`income_layer_design.md`](income_layer_design.md). This summary keeps an English entry point in the Chinese file. -- Purpose: this document covers `收入层设计研究结论` for `UsEquityStrategies`. -- Main topics: `结论`, `设计规则`, `杠杆策略实盘候选复核`, `核心默认参数复核`, `杠杆策略代表性扫参归档`. -- Read the boundaries, inputs, outputs, and permission requirements before running commands, CI jobs, dry-runs, releases, or runtime switches. -- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples. -- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body. +[English](income_layer_design.md) _更新日期：2026-06-04_ diff --git a/docs/research/mega_cap_leader_rotation.md b/docs/research/mega_cap_leader_rotation.md index 93ff2f9..549d0cc 100644 --- a/docs/research/mega_cap_leader_rotation.md +++ b/docs/research/mega_cap_leader_rotation.md @@ -1,13 +1,5 @@ # mega_cap_leader_rotation research brief - -## 中文摘要 - -- 用途：本文档围绕 `mega_cap_leader_rotation research brief`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Objective`、`Research And Runtime Scope`、`Signal Design`、`Retained Runtime Shape`、`Research Commands`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 Status: the static `mag7` / `expanded` variants remain research/backtest only. `mega_cap_leader_rotation_top50_balanced` is the retained runtime-enabled Top50 candidate. Narrow Top20 and aggressive Top50 profile exposure was removed diff --git a/docs/research/nasdaq_sp500_smart_dca.md b/docs/research/nasdaq_sp500_smart_dca.md index 503b306..116c668 100644 --- a/docs/research/nasdaq_sp500_smart_dca.md +++ b/docs/research/nasdaq_sp500_smart_dca.md @@ -1,14 +1,5 @@ # Nasdaq/S&P 500 Smart DCA Design - -## 中文摘要 - -- 用途：本文档围绕 `Nasdaq/S&P 500 Smart DCA Design`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Purpose`、`Research Basis`、`Default Instruments`、`Cadence`、`Sizing Rules`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 - ## Purpose `nasdaq_sp500_smart_dca` is a buy-only accumulation profile for cash-funded diff --git a/docs/us_equity_contract_gap_matrix.md b/docs/us_equity_contract_gap_matrix.md index a68ca2f..9f04bb7 100644 --- a/docs/us_equity_contract_gap_matrix.md +++ b/docs/us_equity_contract_gap_matrix.md @@ -1,13 +1,5 @@ # US equity contract gap matrix - -## 中文摘要 - -- 用途：本文档围绕 `US equity contract gap matrix`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Current Runtime Scope`、`Removed Research Profile Exposure`、`Canonical Input Vocabulary`、`Profile Matrix`、`Current Conclusions`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 _Updated: 2026-06-04_ This document tracks the current shared US equity strategy contract across diff --git a/docs/us_equity_notification_i18n_contract.md b/docs/us_equity_notification_i18n_contract.md index 4e25c42..c0b8e34 100644 --- a/docs/us_equity_notification_i18n_contract.md +++ b/docs/us_equity_notification_i18n_contract.md @@ -1,14 +1,7 @@ # US Equity Notification, i18n, and Log Contract +[简体中文](us_equity_notification_i18n_contract.zh-CN.md) -## 中文摘要 - -- 完整中文版见 [`us_equity_notification_i18n_contract.zh-CN.md`](us_equity_notification_i18n_contract.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。 -- 用途：本文档围绕 `US Equity Notification, i18n, and Log Contract`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Strategy Output`、`i18n Rules`、`Rendered Display Fields`、`Required Log Fields`、`Sidecar Plugin Messages`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 _Updated: 2026-05-29_ This document defines the strategy-layer payload shape that downstream platform repositories should use for Telegram messages, dry-run reports, and audit logs. Strategy code owns structured facts and translation keys; platform repositories own final layout, routing, and compaction. diff --git a/docs/us_equity_notification_i18n_contract.zh-CN.md b/docs/us_equity_notification_i18n_contract.zh-CN.md index 566e3d0..c0f5b83 100644 --- a/docs/us_equity_notification_i18n_contract.zh-CN.md +++ b/docs/us_equity_notification_i18n_contract.zh-CN.md @@ -1,14 +1,6 @@ # 美股策略通知、i18n 与日志契约 - -## English summary - -- Full English version: [`us_equity_notification_i18n_contract.md`](us_equity_notification_i18n_contract.md). This summary keeps an English entry point in the Chinese file. -- Purpose: this document covers `美股策略通知、i18n 与日志契约` for `UsEquityStrategies`. -- Main topics: `策略输出位置`, `i18n 规则`, `已渲染展示字段`, `日志格式`, `侧车插件通知文案`. -- Read the boundaries, inputs, outputs, and permission requirements before running commands, CI jobs, dry-runs, releases, or runtime switches. -- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples. -- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body. +[English](us_equity_notification_i18n_contract.md) _更新日期：2026-05-29_ diff --git a/docs/us_equity_portability_checklist.md b/docs/us_equity_portability_checklist.md index 647aff9..3531bc8 100644 --- a/docs/us_equity_portability_checklist.md +++ b/docs/us_equity_portability_checklist.md @@ -1,13 +1,5 @@ # US equity portability checklist - -## 中文摘要 - -- 用途：本文档围绕 `US equity portability checklist`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`1. Contract registration`、`2. Canonical inputs only`、`3. Output portability`、`4. Runtime-adapter matrix`、`5. Artifact-backed profiles`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 Use this checklist before enabling a US equity profile on any runtime. This document is intentionally shorter than the authoring template. It is a reviewer-facing list for portability sign-off. diff --git a/docs/us_equity_runtime_archive.zh-CN.md b/docs/us_equity_runtime_archive.zh-CN.md index bcec567..e2a6db2 100644 --- a/docs/us_equity_runtime_archive.zh-CN.md +++ b/docs/us_equity_runtime_archive.zh-CN.md @@ -1,14 +1,5 @@ # US equity runtime archive - -## English summary - -- Purpose: this document covers `US equity runtime archive` for `UsEquityStrategies`. -- Main topics: `归档总览`, `已删除的旧研究`, `归档口径`. -- Read the boundaries, inputs, outputs, and permission requirements before running commands, CI jobs, dry-runs, releases, or runtime switches. -- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples. -- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body. - _更新日期：2026-06-03_ 这份索引只记录当前 `runtime_enabled` 的美股 profile 及其可复查证据。 diff --git a/docs/us_equity_strategy_status.zh-CN.md b/docs/us_equity_strategy_status.zh-CN.md index 7ca65d7..59ae783 100644 --- a/docs/us_equity_strategy_status.zh-CN.md +++ b/docs/us_equity_strategy_status.zh-CN.md @@ -1,14 +1,5 @@ # 美股策略状态与研究手册 - -## English summary - -- Purpose: this document covers `美股策略状态与研究手册` for `UsEquityStrategies`. -- Main topics: `当前可配置 profiles`, `已移除的重复/较弱研究 profile 暴露`, `收入层默认启用口径`, `已归档回测摘要`, `研究中但未进入运行 profile 的方向`. -- Read the boundaries, inputs, outputs, and permission requirements before running commands, CI jobs, dry-runs, releases, or runtime switches. -- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples. -- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body. - _更新日期：2026-06-04_ 这份文档只记录当前可配置的美股策略 profile、输入形态和研究状态，不记录任何账户或服务正在运行的 profile。部署单元当前跑什么属于私有运行信息，应留在云端配置或私有运行记录里。 diff --git a/docs/us_equity_strategy_template.md b/docs/us_equity_strategy_template.md index 1313ffb..0dc9b8b 100644 --- a/docs/us_equity_strategy_template.md +++ b/docs/us_equity_strategy_template.md @@ -1,13 +1,5 @@ # US equity strategy template - -## 中文摘要 - -- 用途：本文档围绕 `US equity strategy template`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`What “done” looks like`、`Minimal repository footprint`、`1. Profile metadata and catalog registration`、``StrategyDefinition` must declare`、`Example`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 This document is the authoring template for **new** US equity strategy profiles in `UsEquityStrategies`. It is aligned with: diff --git a/docs/us_equity_value_mode_input_contract.md b/docs/us_equity_value_mode_input_contract.md index 8391908..6c58324 100644 --- a/docs/us_equity_value_mode_input_contract.md +++ b/docs/us_equity_value_mode_input_contract.md @@ -1,13 +1,5 @@ # US equity value-mode canonical input contract - -## 中文摘要 - -- 用途：本文档围绕 `US equity value-mode canonical input contract`，用于理解 `UsEquityStrategies` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Why this document exists`、`Fixed end-state summary`、`Shared contract rules for value-mode profiles`、`1. Canonical required inputs`、`2. Canonical portfolio object`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 This document fixes the **strategy-facing canonical input contract** for the current US equity value-mode profiles: @@ -32,8 +24,8 @@ strategy-facing canonical inputs: - `soxl_soxx_trend_income` uses `derived_indicators` + `portfolio_snapshot` - `nasdaq_sp500_smart_dca` uses `market_history` + `portfolio_snapshot` -This document defines the end-state contract that later P2/P4 code changes -should implement. +This document records the fixed value-mode input contract and the current +implementation status. Current implementation status: