Merge pull request #78 from QuantStrategyLab/codex/bilingual-docs-20260601

Pigbibi · web-flow · commit 79744dc6d81f · 2026-06-01T03:57:30.000+08:00
Add bilingual docs summaries
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,13 @@
 # Contributing
 
+
+## 中文摘要
+
+- 用途：本文档围绕 `Contributing`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Ground Rules`、`Branching and Pull Requests`、`Local Verification`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 Thanks for contributing to `QuantPlatformKit`.
 
 ## Ground Rules
diff --git a/README.md b/README.md
@@ -2,6 +2,15 @@
 
 > ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
 
+
+## 中文摘要
+
+- 完整中文版见 [`README.zh-CN.md`](README.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。
+- 用途：本文档围绕 `QuantPlatformKit`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`What This Repository Is`、`Repository Workflow`、`Strategy Plugins`、`Package Layout`、`Development`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 Shared platform contracts, broker adapters, strategy-plugin helpers, and notification primitives for QuantStrategyLab repositories.
 
 [中文](./README.zh-CN.md)
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -2,6 +2,16 @@
 
 > ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
 
+
+## English summary
+
+- Full English version: [`README.md`](README.md). This summary keeps an English entry point in the Chinese file.
+- Purpose: this document covers `QuantPlatformKit` for `QuantPlatformKit`.
+- 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.
+
 `QuantPlatformKit` 是 QuantStrategyLab 的共享平台契约、券商适配工具、策略插件 helper 和通知基础能力仓库。
 
 [English](./README.md)
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,5 +1,13 @@
 # Security Policy
 
+
+## 中文摘要
+
+- 用途：本文档围绕 `Security Policy`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Reporting a Vulnerability`、`Secret and Credential Exposure`、`Scope Notes`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 Thanks for helping keep `QuantPlatformKit` safe.
 
 This repository is part of a shared platform library. Please do **not** open a public issue for vulnerabilities involving credentials, broker access, cloud resources, order execution, or secret material.
diff --git a/docs/platform_notification_outcomes.md b/docs/platform_notification_outcomes.md
@@ -1,5 +1,14 @@
 # Platform Notification Outcomes
 
+
+## 中文摘要
+
+- 完整中文版见 [`platform_notification_outcomes.zh-CN.md`](platform_notification_outcomes.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。
+- 用途：本文档围绕 `Platform Notification Outcomes`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Execution Stages`、`Skip Reasons`、`Notification Envelope`、`Platform Responsibilities`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 Platform runtimes should use the shared execution outcome and notification
 envelope helpers in `quant_platform_kit` instead of defining private stage or
 notification sink semantics in each repository.
diff --git a/docs/platform_notification_outcomes.zh-CN.md b/docs/platform_notification_outcomes.zh-CN.md
@@ -1,5 +1,14 @@
 # 平台通知与执行结果语义
 
+
+## English summary
+
+- Full English version: [`platform_notification_outcomes.md`](platform_notification_outcomes.md). This summary keeps an English entry point in the Chinese file.
+- Purpose: this document covers `平台通知与执行结果语义` for `QuantPlatformKit`.
+- Main topics: `执行 Stage`, `跳过原因`, `通知 Envelope`, `平台仓库职责`.
+- 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.
 平台运行时应复用 `quant_platform_kit` 里的共享执行结果和通知 envelope
 helper，不要在每个仓库里各自定义一套 stage 或通知投递语义。
 
diff --git a/docs/platform_repo_boundaries.md b/docs/platform_repo_boundaries.md
@@ -1,5 +1,14 @@
 # Platform Repository Boundaries
 
+
+## 中文摘要
+
+- 完整中文版见 [`platform_repo_boundaries.zh-CN.md`](platform_repo_boundaries.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。
+- 用途：本文档围绕 `Platform Repository Boundaries`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`QuantPlatformKit`、`Strategy Repositories`、`Platform Repositories`、`Practical Rule`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 This document describes how `QuantPlatformKit` fits with strategy repositories
 and broker platform repositories.
 
diff --git a/docs/platform_repo_boundaries.zh-CN.md b/docs/platform_repo_boundaries.zh-CN.md
@@ -1,5 +1,15 @@
 # 平台仓库职责边界
 
+
+## English summary
+
+- Full English version: [`platform_repo_boundaries.md`](platform_repo_boundaries.md). This summary keeps an English entry point in the Chinese file.
+- Purpose: this document covers `平台仓库职责边界` for `QuantPlatformKit`.
+- Main topics: `QuantPlatformKit`, `策略仓库`, `平台仓库`, `实用判断`.
+- 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.
+
 这份文档说明 `QuantPlatformKit` 如何与策略仓库、券商平台仓库协作。
 
 ## QuantPlatformKit
diff --git a/docs/quantconnect.md b/docs/quantconnect.md
@@ -1,5 +1,13 @@
 # QuantConnect Connector
 
+
+## 中文摘要
+
+- 用途：本文档围绕 `QuantConnect Connector`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Example`、`References`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 `quant_platform_kit.quantconnect` contains small, dependency-free helpers for platform repositories that deploy a strategy to QuantConnect Cloud while keeping account wiring and secrets outside this public repository.
 
 The connector supports:
diff --git a/docs/strategy_plugin_runtime_contract.md b/docs/strategy_plugin_runtime_contract.md
@@ -1,5 +1,14 @@
 # Strategy Plugin Runtime Contract
 
+
+## 中文摘要
+
+- 完整中文版见 [`strategy_plugin_runtime_contract.zh-CN.md`](strategy_plugin_runtime_contract.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。
+- 用途：本文档围绕 `Strategy Plugin Runtime Contract`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Ownership`、`Platform Mount Config`、`Plugin Definitions`、`Runtime Loader`、`Behavior Boundary`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
 [简体中文](./strategy_plugin_runtime_contract.zh-CN.md)
 
 This document describes how platform runtimes consume sidecar strategy plugin
diff --git a/docs/strategy_plugin_runtime_contract.zh-CN.md b/docs/strategy_plugin_runtime_contract.zh-CN.md
@@ -1,5 +1,15 @@
 # 策略插件运行时契约
 
+
+## English summary
+
+- Full English version: [`strategy_plugin_runtime_contract.md`](strategy_plugin_runtime_contract.md). This summary keeps an English entry point in the Chinese file.
+- Purpose: this document covers `策略插件运行时契约` for `QuantPlatformKit`.
+- Main topics: `职责边界`, `平台挂载配置`, `插件定义`, `Runtime Loader`, `行为边界`.
+- 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](./strategy_plugin_runtime_contract.md)
 
 本文档说明平台运行时如何消费侧车策略插件 artifact，例如上游 snapshot
diff --git a/docs/us_equity_cross_platform_strategy_spec.md b/docs/us_equity_cross_platform_strategy_spec.md
@@ -1,5 +1,15 @@
 # US equity cross-platform strategy spec
 
+
+## 中文摘要
+
+- 完整中文版见 [`us_equity_cross_platform_strategy_spec.zh-CN.md`](us_equity_cross_platform_strategy_spec.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。
+- 用途：本文档围绕 `US equity cross-platform strategy spec`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Goal`、`Scope`、`Design rule`、`Responsibility boundaries`、`Mandatory layers`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
+
 ## Goal
 
 All US equity strategies should be written once and be portable across the
diff --git a/docs/us_equity_cross_platform_strategy_spec.zh-CN.md b/docs/us_equity_cross_platform_strategy_spec.zh-CN.md
@@ -1,5 +1,15 @@
 # 美股策略跨平台设计规范
 
+
+## English summary
+
+- Full English version: [`us_equity_cross_platform_strategy_spec.md`](us_equity_cross_platform_strategy_spec.md). This summary keeps an English entry point in the Chinese file.
+- Purpose: this document covers `美股策略跨平台设计规范` for `QuantPlatformKit`.
+- 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.
+
 ## 目标
 
 所有美股策略都应该做到“一套策略代码，尽量在当前券商运行时复用”：
diff --git a/docs/us_equity_execution_translation_spec.md b/docs/us_equity_execution_translation_spec.md
@@ -1,5 +1,15 @@
 # US equity execution translation spec
 
+
+## 中文摘要
+
+- 完整中文版见 [`us_equity_execution_translation_spec.zh-CN.md`](us_equity_execution_translation_spec.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。
+- 用途：本文档围绕 `US equity execution translation spec`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。
+- 主要覆盖：`Goal`、`Native execution modes by platform`、`Translation boundary`、`Required inputs to translation`、``weight -> value` rules`。
+- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。
+- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。
+- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。
+
 ## Goal
 
 This document defines the P3 rule set for translating a unified US equity
diff --git a/docs/us_equity_execution_translation_spec.zh-CN.md b/docs/us_equity_execution_translation_spec.zh-CN.md
@@ -1,5 +1,15 @@
 # 美股执行翻译规范
 
+
+## English summary
+
+- Full English version: [`us_equity_execution_translation_spec.md`](us_equity_execution_translation_spec.md). This summary keeps an English entry point in the Chinese file.
+- Purpose: this document covers `美股执行翻译规范` for `QuantPlatformKit`.
+- Main topics: `目标`, `各平台当前原生执行模式`, `翻译层边界`, `翻译层允许依赖的输入`, ``weight -> value` 规则`.
+- 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.
+
 ## 目标
 
 这份文档定义 P3 阶段的统一规则：怎么把美股策略输出的统一
