From 4c4a9241e02a9197fb20b316df48b21349cf7cfe Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Fri, 16 Oct 2026 23:12:59 +0800
Subject: [PATCH 1/2] docs: bilingual README (en + zh-CN)

---
 README.md       | 96 ++++++++++++++++++++++++++++---------------------
 README.zh-CN.md | 78 ++++++++++++++++++++++------------------
 2 files changed, 99 insertions(+), 75 deletions(-)

diff --git a/README.md b/README.md
index 82b6dd6..e8f9b59 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,79 @@
 # QuantStrategyPlugins
 
-[Chinese README](README.zh-CN.md)
+Sidecar strategy plugin package that emits QuantPlatformKit-compatible signal artifacts.
 
-> Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only.
+English | [简体中文](README.zh-CN.md)
 
-## What this repository is
+## Status
 
-QuantStrategyPlugins is a QuantStrategyLab strategy plugin package. It provides sidecar strategy plugins such as market-regime controls, notification artifacts, and research-only plugin outputs.
+Experimental. Use at your own risk. This project is not financial advice and
+does not guarantee any trading result. Its outputs are research evidence, not
+trading instructions.
 
-It supports the system but does not decide which strategy should be live. Strategy eligibility remains in the strategy and snapshot repositories; broker execution remains in the platform repositories.
+## What this is
 
-## QSL architecture role
+QuantStrategyPlugins provides sidecar strategy plugins: market-regime controls,
+shadow signals, and research-only output. Each plugin emits a signal envelope
+that QuantPlatformKit consumers can read. Plugins run locally against price
+history and write artifacts, so strategy and pipeline repositories can add
+regime and risk context without changing broker-facing code. It is aimed at
+engineers extending strategy behavior.
 
-- **Layer**: `strategy-lib`.
-- **Responsibility**: sidecar strategy plugin package.
-- **Owns**: plugin contracts, market-regime controls, notification/research plugin outputs.
-- **Consumes**: QuantPlatformKit and strategy/pipeline consumers.
-- **Must not**: decide live eligibility or connect to brokers directly.
+## What this is not
 
-## Design boundary
+It does not decide live eligibility. It does not connect to a broker or place
+orders. It does not grant execution authority.
 
-- Keep contracts stable and versioned where downstream repositories depend on them.
-- Prefer backward-compatible changes unless a coordinated migration is planned.
-- Keep secrets and environment-specific settings outside the shared library code.
-- Document changes that affect multiple platforms or strategy packages.
+## Quick start
 
-## Repository layout
+Requires Python 3.11 or newer.
 
-- `src/`: library and runtime code.
-- `tests/`: unit, contract, and regression tests.
-- `docs/`: runbooks, design notes, evidence, and integration contracts.
-- `.github/workflows/`: CI, scheduled jobs, release, or deployment workflows.
-- `scripts/`: operator scripts and local helpers.
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+```
 
-## Quick start
+Inspect the plugin runner options. The runner reads a TOML config passed with
+`--config`; a sample is at `docs/examples/strategy_plugins.example.toml`.
 
 ```bash
-python -m pip install -e '.[test,ai]'
-python -m pytest -q
+qsp-run-strategy-plugins --help
+```
+
+The default install does not include the optional AI audit client. Install
+`.[ai]` only if you use that client; it adds the pinned AI gateway client but
+does not enable audits, configure credentials, or grant execution authority.
+
+## Configuration
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `YFINANCE_PROXY` | No | none | Proxy override for Yahoo Finance price downloads. |
+| `HTTPS_PROXY` | No | none | Proxy for outbound price downloads. |
+| `HTTP_PROXY` | No | none | Proxy for outbound price downloads. |
+| `ALL_PROXY` | No | none | Fallback proxy for outbound price downloads. |
+
+The optional AI audit client reads its endpoint and token from the environment.
+It stays disabled unless you configure and enable it.
+
+## Repository layout
+
+```
+src/        plugin implementations and signal envelopes
+scripts/    plugin runner and research scripts
+docs/       lifecycle policy and plugin design notes
+tests/      unit and contract tests
 ```
 
-The default runtime install (`python -m pip install .`) does not include the AI
-client. Install `.[ai]` only for an approved AI consumer; it adds the pinned,
-standard-library-only AIAuditBridge SDK, not the gateway service. Installation
-does not enable AI audits, configure credentials, or grant execution authority.
-The full test suite uses the real installed SDK with synthetic HTTP responses;
-it does not call a model or verify production authentication.
+## Contributing
 
-## Useful docs
-- [`docs/plugin_lifecycle_policy.md`](docs/plugin_lifecycle_policy.md)
-- [`docs/market-regime-control-plan.md`](docs/market-regime-control-plan.md)
-- [`docs/market-regime-control-plan.zh-CN.md`](docs/market-regime-control-plan.zh-CN.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Community and security
+## Security
 
-- See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request scope, local verification, and documentation expectations.
-- Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for maintainer and contributor conduct.
-- Report credential, automation, broker, exchange, or cloud-resource vulnerabilities through [SECURITY.md](SECURITY.md); do not open public issues for secrets or live-execution risk.
+See [SECURITY.md](SECURITY.md). Do not open a public issue for a vulnerability.
+Keep credentials, private data, and external service tokens out of Git and logs.
 
 ## License
 
-See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index eb8848d..710e1c0 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,58 +1,66 @@
 # QuantStrategyPlugins
 
-[English README](README.md)
+输出与 QuantPlatformKit 兼容的信号产物的 sidecar 策略插件包。
 
-> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。
+[English](README.md) | 简体中文
 
-## 这个仓库是什么
+## 状态
 
-QuantStrategyPlugins 是 QuantStrategyLab 的策略插件包。提供 market-regime control、通知 artifact 和研究侧 plugin 输出等 sidecar 策略插件。
+实验性项目，使用风险自负。本项目不构成投资建议，也不保证任何交易结果。它的输出是研究证据，不是交易指令。
 
-它支撑系统运行，但不决定哪个策略应该 live。策略资格由策略仓和 snapshot 仓负责；券商执行由平台仓负责。
+## 简介
 
-## QSL 架构角色
+QuantStrategyPlugins 提供 sidecar 策略插件：市场状态控制、shadow 信号和仅研究的输出。每个插件输出一个 QuantPlatformKit 消费方可读取的信号信封。插件在本地基于价格历史运行并写出产物，让策略仓与管线仓在不改券商对接代码的前提下补充市场状态与风险上下文。它面向扩展策略行为的工程师。
 
-- **层级**：`策略库`。
-- **职责**：sidecar 策略插件包。
-- **事实源/归属**：plugin contracts、market-regime controls、notification/research plugin outputs。
-- **消费对象**：QuantPlatformKit 和 strategy/pipeline consumers。
-- **禁止事项**：决定 live eligibility 或直接连接券商。
+## 不适用范围
 
-## 设计边界
+它不决定实盘资格。它不连接券商，也不提交订单。它不授予执行权限。
 
-- 下游仓库依赖的契约要保持稳定，必要时做版本化。
-- 除非有协同迁移计划，否则优先保持向后兼容。
-- 密钥和环境专属配置不要写进共享库代码。
-- 会影响多个平台或策略包的改动，需要在文档中说明。
+## 快速开始
 
-## 仓库结构
+需要 Python 3.11 或更高版本。
 
-- `src/`：库代码和运行时代码。
-- `tests/`：单元测试、契约测试和回归测试。
-- `docs/`：运行手册、设计说明、证据和集成契约。
-- `.github/workflows/`：CI、定时任务、发布或部署 workflow。
-- `scripts/`：运维脚本和本地辅助工具。
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+```
 
-## 快速开始
+查看插件 runner 的选项。runner 通过 `--config` 读取 TOML 配置，示例见 `docs/examples/strategy_plugins.example.toml`。
 
 ```bash
-python -m pip install -e .
-python -m pytest -q
+qsp-run-strategy-plugins --help
+```
+
+默认安装不包含可选的 AI 审阅客户端。只有需要该客户端时才安装 `.[ai]`；它会加入固定版本的 AI gateway 客户端，但不会启用审阅、配置凭据或授予执行权限。
+
+## 配置
+
+| 变量 | 必填 | 默认值 | 用途 |
+|---|---|---|---|
+| `YFINANCE_PROXY` | 否 | 无 | Yahoo Finance 价格下载所用的代理覆盖。 |
+| `HTTPS_PROXY` | 否 | 无 | 出站价格下载所用的代理。 |
+| `HTTP_PROXY` | 否 | 无 | 出站价格下载所用的代理。 |
+| `ALL_PROXY` | 否 | 无 | 出站价格下载的回退代理。 |
+
+可选的 AI 审阅客户端从环境变量读取端点与 token，未配置并启用时保持关闭。
+
+## 仓库结构
+
+```
+src/        插件实现与信号信封
+scripts/    插件 runner 与研究脚本
+docs/       生命周期策略与插件设计说明
+tests/      单元与契约测试
 ```
 
-## 延伸文档
+## 参与贡献
 
-- [`docs/plugin_lifecycle_policy.zh-CN.md`](docs/plugin_lifecycle_policy.zh-CN.md)
-- [`docs/market-regime-control-plan.md`](docs/market-regime-control-plan.md)
-- [`docs/market-regime-control-plan.zh-CN.md`](docs/market-regime-control-plan.zh-CN.md)
-- [`docs/strategy-plugin-signal-envelope-v2.zh-CN.md`](docs/strategy-plugin-signal-envelope-v2.zh-CN.md)：纯本地、仅设计的确定性信号 envelope；未接入 runtime。
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-## 社区和安全
+## 安全
 
-- 贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，确认 PR 范围、本地校验和文档要求。
-- 讨论、issue 和 review 请遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
-- 涉及密钥、自动化、券商/交易所或云资源的漏洞请按 [SECURITY.md](SECURITY.md) 私密报告；不要为 secret 或实盘风险开公开 issue。
+见 [SECURITY.md](SECURITY.md)。安全漏洞不要开公开 issue，也不要让凭据、私有数据和外部服务 token 进入 Git 或日志。
 
 ## 许可证
 
-详见 [LICENSE](LICENSE)。
+MIT，见 [LICENSE](LICENSE)。

From cfc17798808cf729a3b20d8757592c0254311031 Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Sat, 17 Oct 2026 00:31:47 +0800
Subject: [PATCH 2/2] docs: fix README review findings (en + zh-CN)

---
 README.md       | 18 ++++++++++++++----
 README.zh-CN.md | 13 +++++++++++--
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index e8f9b59..981d429 100644
--- a/README.md
+++ b/README.md
@@ -28,8 +28,19 @@ orders. It does not grant execution authority.
 
 Requires Python 3.11 or newer.
 
+Minimal runtime install (library and plugin runner only, without the optional
+AI audit client):
+
+```bash
+python -m pip install .
+```
+
+Full test suite. The tests import the optional AI audit client, so install the
+`test` and `ai` extras to match CI (`.github/workflows/ci.yml`), then run
+pytest:
+
 ```bash
-python -m pip install -e '.[test]'
+python -m pip install -e '.[test,ai]'
 python -m pytest -q
 ```
 
@@ -40,9 +51,8 @@ Inspect the plugin runner options. The runner reads a TOML config passed with
 qsp-run-strategy-plugins --help
 ```
 
-The default install does not include the optional AI audit client. Install
-`.[ai]` only if you use that client; it adds the pinned AI gateway client but
-does not enable audits, configure credentials, or grant execution authority.
+The `ai` extra adds the pinned AI gateway client; installing it does not enable
+audits, configure credentials, or grant execution authority.
 
 ## Configuration
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 710e1c0..6666c57 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -20,8 +20,17 @@ QuantStrategyPlugins 提供 sidecar 策略插件：市场状态控制、shadow 
 
 需要 Python 3.11 或更高版本。
 
+最小运行时安装（仅库与插件 runner，不含可选的 AI 审阅客户端）：
+
+```bash
+python -m pip install .
+```
+
+完整测试：测试会导入可选的 AI 审阅客户端，因此需安装 `test` 与 `ai` extra
+以匹配 CI（`.github/workflows/ci.yml`），再运行 pytest：
+
 ```bash
-python -m pip install -e '.[test]'
+python -m pip install -e '.[test,ai]'
 python -m pytest -q
 ```
 
@@ -31,7 +40,7 @@ python -m pytest -q
 qsp-run-strategy-plugins --help
 ```
 
-默认安装不包含可选的 AI 审阅客户端。只有需要该客户端时才安装 `.[ai]`；它会加入固定版本的 AI gateway 客户端，但不会启用审阅、配置凭据或授予执行权限。
+`ai` extra 会加入固定版本的 AI gateway 客户端；安装它不会启用审阅、配置凭据或授予执行权限。
 
 ## 配置