Pigbibi · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/README.md b/README.md
@@ -1,63 +1,79 @@
 # QuantAdvisorResearch
 
-[Chinese README](README.zh-CN.md)
+Research publishing system that turns public web and RSS evidence into traceable advisory reports.
 
-> 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
 
-QuantAdvisorResearch is a QuantStrategyLab research publishing system. It publishes research-oriented advisory content from web and RSS evidence without placing orders.
+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 produces research, audit, or orchestration artifacts. It should not submit broker orders or mutate live allocations by itself.
+## What this is
 
-## QSL architecture role
+QuantAdvisorResearch builds and publishes research-oriented advisory content
+from public web and RSS evidence. It is the deterministic composition layer of
+the advisory research system: it combines upstream evidence into advisory
+reports, market-confirmation and recommendation-review artifacts, and a static
+site, keeping each output traceable to its source. It is aimed at researchers
+and reviewers who need the published reasoning, not at live trading.
 
-- **Layer**: `research`.
-- **Responsibility**: research-oriented advisory publishing system.
-- **Owns**: traceable advisory reports and web/RSS evidence summaries.
-- **Consumes**: public web/RSS inputs and research signal context.
-- **Must not**: submit orders, allocation changes, or account advice automatically.
+## What this is not
 
-## Output boundary
+It does not place broker orders. It does not change allocations. It does not
+produce automatic trading instructions or auto-approvals, and its reports are
+not investment advice.
 
-- Treat generated reports as evidence or review material, not automatic trading instructions.
-- Keep source traceability and artifact timestamps visible.
-- Require human review before using outputs in downstream strategy or platform changes.
-- Keep credentials, private data, and external service tokens out of Git and logs.
+## 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
+The build and publish entry points print usage and required arguments when run
+with `--help`:
 
 ```bash
-python -m pip install -e .
-python -m pytest -q
+qar-build-advisory-artifacts --help
+qar-build-advisory-report --help
+qar-publish-advisory-site --help
+```
+
+## Configuration
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | No | none | Bot token used to send advisory notifications. |
+| `TELEGRAM_CHAT_ID` | No | none | Chat that receives advisory notifications. |
+| `NOTIFY_LANG` | No | `zh` | Language used for notifications. |
+
+Report and notification contracts live in [`docs/advisory_contract.md`](docs/advisory_contract.md)
+and [`docs/notification_format.md`](docs/notification_format.md).
+
+## Repository layout
+
+```
+src/        library code and command implementations
+scripts/    command-line helpers
+docs/       design notes and output contracts
+examples/   sample inputs
+data/       local working output
+tests/      unit and contract tests
 ```
 
-## Useful docs
+## Contributing
 
-- [`docs/advisory_contract.md`](docs/advisory_contract.md)
-- [`docs/data_factor_roadmap.md`](docs/data_factor_roadmap.md)
-- [`docs/data_factor_roadmap.zh-CN.md`](docs/data_factor_roadmap.zh-CN.md)
-- [`docs/notification_format.md`](docs/notification_format.md)
-- [`docs/notification_format.zh-CN.md`](docs/notification_format.zh-CN.md)
-- [`docs/system_design.md`](docs/system_design.md)
-- [`docs/system_design.zh-CN.md`](docs/system_design.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).
-
-[Project scope and operating reference](docs/project-reference.md).
+MIT. See [LICENSE](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -1,61 +1,67 @@
 # QuantAdvisorResearch
 
-[English README](README.md)
+把公开网页与 RSS 证据转成可追溯研究型咨询报告的研究发布系统。
 
-> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。
+[English](README.md) | 简体中文
 
-## 这个仓库是什么
+## 状态
 
-QuantAdvisorResearch 是 QuantStrategyLab 的研究发布系统。基于网页和 RSS 证据发布研究型内容，不执行订单。
+实验性项目，使用风险自负。本项目不构成投资建议，也不保证任何交易结果。它的输出是研究证据，不是交易指令。
 
-它产出研究、审计或编排类 artifact，不应自行提交券商订单，也不应直接修改 live allocation。
+## 简介
 
-## QSL 架构角色
+QuantAdvisorResearch 基于公开网页与 RSS 证据构建并发布研究型咨询内容。它是咨询研究系统中的确定性合成层：把上游证据合成为咨询报告、市场确认与建议复核产物，以及一个静态站点，并保持每个输出都可追溯到来源。它面向需要查看已发布推理过程的研究者和审阅者，不面向实盘交易。
 
-- **层级**：`研究/证据`。
-- **职责**：研究型 advisory 发布系统。
-- **事实源/归属**：可追溯 advisory reports 和 web/RSS 证据摘要。
-- **消费对象**：公开 web/RSS 输入和 research signal context。
-- **禁止事项**：自动提交订单、allocation changes 或账户建议。
+## 不适用范围
 
-## 输出边界
+它不提交券商订单。它不改变仓位分配。它不产生自动交易指令或自动批准，其报告也不构成投资建议。
 
-- 生成报告应作为证据或审阅材料，不是自动交易指令。
-- 保留来源可追溯性和 artifact 时间戳。
-- 输出用于下游策略或平台改动前，需要人工 review。
-- 凭据、私人数据和外部服务 token 不能提交到 Git，也不能写入日志。
+## 快速开始
 
-## 仓库结构
+需要 Python 3.11 或更高版本。
 
-- `src/`：库代码和运行时代码。
-- `tests/`：单元测试、契约测试和回归测试。
-- `docs/`：运行手册、设计说明、证据和集成契约。
-- `.github/workflows/`：CI、定时任务、发布或部署 workflow。
-- `scripts/`：运维脚本和本地辅助工具。
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+```
 
-## 快速开始
+构建与发布入口使用 `--help` 打印用法和必填参数：
 
 ```bash
-python -m pip install -e .
-python -m pytest -q
+qar-build-advisory-artifacts --help
+qar-build-advisory-report --help
+qar-publish-advisory-site --help
+```
+
+## 配置
+
+| 变量 | 必填 | 默认值 | 用途 |
+|---|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | 否 | 无 | 发送咨询通知所用的 bot token。 |
+| `TELEGRAM_CHAT_ID` | 否 | 无 | 接收咨询通知的会话。 |
+| `NOTIFY_LANG` | 否 | `zh` | 通知使用的语言。 |
+
+报告与通知契约见 [`docs/advisory_contract.md`](docs/advisory_contract.md) 和 [`docs/notification_format.md`](docs/notification_format.md)。
+
+## 仓库结构
+
+```
+src/        库代码和命令实现
+scripts/    命令行辅助脚本
+docs/       设计说明与输出契约
+examples/   示例输入
+data/       本地工作输出
+tests/      单元与契约测试
 ```
 
-## 延伸文档
+## 参与贡献
 
-- [`docs/advisory_contract.md`](docs/advisory_contract.md)
-- [`docs/data_factor_roadmap.md`](docs/data_factor_roadmap.md)
-- [`docs/data_factor_roadmap.zh-CN.md`](docs/data_factor_roadmap.zh-CN.md)
-- [`docs/notification_format.md`](docs/notification_format.md)
-- [`docs/notification_format.zh-CN.md`](docs/notification_format.zh-CN.md)
-- [`docs/system_design.md`](docs/system_design.md)
-- [`docs/system_design.zh-CN.md`](docs/system_design.zh-CN.md)
+见 [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)。