qlib-sync 0.1.0__tar.gz

qlib_sync-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.env
+.pytest_cache/
+.DS_Store
+uv.lock
+_site/
+.claude/

qlib_sync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 randyy179
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qlib_sync-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: qlib-sync
+Version: 0.1.0
+Summary: Safely install and update a local Qlib China A-share dataset, with an MCP server for AI assistants.
+Project-URL: Homepage, https://github.com/randyy179/qlib-sync
+Project-URL: Issues, https://github.com/randyy179/qlib-sync/issues
+Project-URL: Changelog, https://github.com/randyy179/qlib-sync/releases
+Author: randyy179
+License: MIT
+License-File: LICENSE
+Keywords: a-share,china,market-data,mcp,qlib,quant,stock
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: <3.13,>=3.10
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pyqlib>=0.9.6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qlib-sync
+
+[![CI](https://github.com/randyy179/qlib-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/randyy179/qlib-sync/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qlib-sync)](https://pypi.org/project/qlib-sync/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/randyy179/qlib-sync/blob/main/LICENSE)
+
+[中文说明](https://github.com/randyy179/qlib-sync/blob/main/README.zh-CN.md)
+
+**Website:** [randyy179.github.io/qlib-sync](https://randyy179.github.io/qlib-sync/)
+
+<!-- mcp-name: io.github.randyy179/qlib-sync -->
+
+**One command to install and keep current a local [Qlib](https://github.com/microsoft/qlib) China A-share dataset, and an MCP server so AI assistants can read it.**
+
+```bash
+pip install qlib-sync
+qlib-sync cn update
+```
+
+Or without installing anything first: `uvx qlib-sync cn update`.
+
+![qlib-sync updating the dataset: status, download with progress, checksum, summary, then an instant no-op](https://raw.githubusercontent.com/randyy179/qlib-sync/main/docs/assets/demo-update.gif)
+
+That installs the daily community release from
+[chenditc/investment_data](https://github.com/chenditc/investment_data) into
+`~/.qlib/qlib_data/cn_data`, the location Qlib reads by default. Run the same command again
+any time; when the data is already current it finishes in about a second.
+
+## Why not just `wget` and `tar`?
+
+<img src="https://raw.githubusercontent.com/randyy179/qlib-sync/main/docs/assets/comic.jpg" width="560" alt="Four-panel comic: a download dies at 99% at night; the next day 550 MB arrive and nothing changed; the qlib-sync robot checks the data and stamps it verified, keeping the old copy safe; the researcher sips tea and asks an AI for Moutai's recent closes">
+
+Qlib's README points A-share users to the community release with a `wget` and `tar` one-liner.
+That works until it doesn't:
+
+- **An interrupted or truncated download** extracts into a half-written dataset, or fails
+  after the old one has already been overwritten.
+- **Upstream republishes releases.** In November 2026 a data error was found and corrected
+  ([investment_data#163](https://github.com/chenditc/investment_data/issues/163)) and releases
+  were republished under the same date. A date check alone never sees the fix.
+- **Every check downloads 550 MB**, even when nothing changed.
+
+The investment_data README itself describes a careful manual process: download the release
+manifest, check the archive with its `validate_archive.py`, then extract. qlib-sync runs the
+same checks automatically on every update and adds what a manual process cannot: it skips the
+download when nothing changed, extracts beside the live data and swaps it in with rollback
+(rather than extracting on top of the existing folder), and picks up republished releases.
+
+qlib-sync treats the dataset like a production system:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/randyy179/qlib-sync/main/docs/assets/update-flow-dark.svg">
+  <img alt="Update flow: check the manifest, download, verify, stage, swap; any failure puts the previous dataset back" src="https://raw.githubusercontent.com/randyy179/qlib-sync/main/docs/assets/update-flow-light.svg">
+</picture>
+
+| Step | What happens |
+|---|---|
+| Check | Reads the release's 500-byte manifest. Already current: done, nothing downloaded. |
+| Download | Resumes interrupted downloads; shows progress; optional mirror for slow links to GitHub. |
+| Verify | Size and sha256 from the manifest; the same release checks as upstream's `validate_archive.py` (every index pool and the future calendar reach the manifest's dates, release marked publishable); archive paths and links are checked before extraction. |
+| Stage | Extracts next to the active dataset; refuses downgrades. |
+| Swap | Renames the new dataset into place, then runs a real Qlib read. |
+| Roll back | Any failure after the swap moves the previous dataset back. |
+| Report | New trading days, newly listed and delisted symbols. |
+
+The checks catch broken, truncated, or tampered packages. They cannot catch wrong values inside a
+correctly published release (like the one in #163); for that, keep a rollback copy with
+`--keep-backup`.
+
+## Commands
+
+```bash
+qlib-sync status                  # every local Qlib dataset at a glance
+qlib-sync cn status               # local date, pools, and whether a newer release exists
+qlib-sync cn update               # install or update (add --json for machine-readable output)
+qlib-sync cn health-check         # structure checks plus a real Qlib read
+qlib-sync cn restore --list       # rollback backups; restore --yes switches back
+```
+
+Useful options for `cn update`:
+
+| Option | Effect |
+|---|---|
+| `--data-dir PATH` | Install somewhere other than `~/.qlib/qlib_data/cn_data` |
+| `--mirror URL` | Download through a prefix-style GitHub proxy such as `https://ghfast.top` (or set `QLIB_SYNC_MIRROR`) |
+| `--keep-backup` | Keep the previous dataset for one rollback |
+| `--protect FILE` | Carry a custom stock pool in `instruments/` across updates (repeatable) |
+| `--force` | Reinstall even when the dates match |
+
+**The update replaces the whole `cn_data` folder.** Anything you added there is lost unless you
+pass it with `--protect`.
+
+### Mirrors
+
+From mainland China, GitHub downloads can be slow or fail. Pass a mirror and qlib-sync downloads
+the package through it while still reading the manifest from GitHub directly when it can, so the
+checksum does not depend on the mirror. Mirrors are third-party services; qlib-sync does not
+endorse any of them.
+
+## Python
+
+```python
+from qlib_sync import update_cn, status_cn, health_check_cn
+
+result = update_cn()                 # raises qlib_sync.UpdateError on failure; data unchanged
+print("\n".join(result.summary_lines()))
+print(result.new_trading_days, result.added_symbols)
+```
+
+## Use it from your AI assistant
+
+qlib-sync includes an [MCP](https://modelcontextprotocol.io) server, the open standard most AI
+tools use to call local tools. Any MCP client that can start a local command works, whichever
+model it runs: Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, or a local model. The server
+runs on your machine and reads the dataset there; there is no service to host and nothing
+leaves your computer. It is listed in the [MCP Registry](https://registry.modelcontextprotocol.io)
+as `io.github.randyy179/qlib-sync`.
+
+Every client needs the same two things: the command `uvx` and the arguments `qlib-sync mcp`.
+
+| Client | How to add qlib-sync |
+|---|---|
+| Claude Desktop | Download `qlib-sync.mcpb` from the [latest release](https://github.com/randyy179/qlib-sync/releases/latest) and open it |
+| Claude Code | `claude mcp add qlib-sync -- uvx qlib-sync mcp` |
+| OpenAI Codex CLI | `codex mcp add qlib-sync -- uvx qlib-sync mcp` |
+| Cursor | The JSON below, in `~/.cursor/mcp.json` |
+| Gemini CLI | The JSON below, in `~/.gemini/settings.json` |
+| Qwen Code | The JSON below, in `~/.qwen/settings.json` |
+| Tencent CodeBuddy, ByteDance Trae, Alibaba Tongyi Lingma | MCP settings, add a server manually, paste the JSON below |
+| Cherry Studio | Settings, MCP servers, add: type STDIO, command `uvx`, arguments `qlib-sync` and `mcp` on separate lines |
+| VS Code (Copilot agent mode) | `.vscode/mcp.json`: `{ "servers": { "qlib-sync": { "type": "stdio", "command": "uvx", "args": ["qlib-sync", "mcp"] } } }` |
+
+```json
+{ "mcpServers": { "qlib-sync": { "command": "uvx", "args": ["qlib-sync", "mcp"] } } }
+```
+
+Menu names and file locations change between versions; check your client's MCP documentation
+if a path above has moved. Tested with Claude Code and OpenAI Codex CLI.
+
+Web chat apps such as ChatGPT connect only to remote MCP servers over the internet, so they
+cannot start this local server.
+
+Set `QLIB_SYNC_DATA_DIR` to use a dataset outside `~/.qlib/qlib_data/cn_data`, and
+`QLIB_SYNC_MIRROR` to download through a mirror.
+
+| Tool | Does |
+|---|---|
+| `cn_status` | Local latest date, pools, and whether an update is available |
+| `cn_update` | Install or update (safe to call: failures restore the previous data) |
+| `cn_health_check` | Structure checks plus a real Qlib read |
+| `cn_get_prices` | Daily bars for up to 20 symbols; real traded prices by default, adjusted on request |
+| `cn_list_pool` | Members of csi300, csi500, and other pools on a date |
+
+Then ask things like *"Is my A-share data current? What did Moutai close at over the last
+week?"* Symbols accept `600519`, `SH600519`, or `600519.SH`.
+
+![Claude Code answering from the local dataset through qlib-sync: data freshness, Moutai closes, CSI 300 size](https://raw.githubusercontent.com/randyy179/qlib-sync/main/docs/assets/demo-claude.gif)
+
+[`skills/qlib-sync/SKILL.md`](https://github.com/randyy179/qlib-sync/blob/main/skills/qlib-sync/SKILL.md) teaches an assistant when to update,
+how to read each failure, and the price conventions. It uses the open `SKILL.md` format that
+Claude, Codex, and other agents load from their skills folder; any assistant can also simply
+be pointed at the file.
+
+## Daily updates
+
+A run that finds nothing new costs one small request, so schedule it daily. See
+[docs/scheduling.md](https://github.com/randyy179/qlib-sync/blob/main/docs/scheduling.md) for cron and launchd examples.
+
+## Data and credits
+
+All data comes from [chenditc/investment_data](https://github.com/chenditc/investment_data)
+(Apache-2.0). qlib-sync only downloads the public release; it does not host or redistribute
+data. Prices follow Qlib's convention: `$close` is adjusted and the real price is
+`$close / $factor`.
+
+qlib-sync is an independent project, not affiliated with Microsoft or the Qlib team.
+
+Supported: macOS and Linux, Python 3.10 to 3.12 (pyqlib does not publish wheels for newer
+versions yet; `uvx` picks a compatible Python automatically).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+## License
+
+MIT

qlib_sync-0.1.0/README.md

@@ -0,0 +1,190 @@
+# qlib-sync
+
+[![CI](https://github.com/randyy179/qlib-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/randyy179/qlib-sync/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qlib-sync)](https://pypi.org/project/qlib-sync/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[中文说明](README.zh-CN.md)
+
+**Website:** [randyy179.github.io/qlib-sync](https://randyy179.github.io/qlib-sync/)
+
+<!-- mcp-name: io.github.randyy179/qlib-sync -->
+
+**One command to install and keep current a local [Qlib](https://github.com/microsoft/qlib) China A-share dataset, and an MCP server so AI assistants can read it.**
+
+```bash
+pip install qlib-sync
+qlib-sync cn update
+```
+
+Or without installing anything first: `uvx qlib-sync cn update`.
+
+![qlib-sync updating the dataset: status, download with progress, checksum, summary, then an instant no-op](docs/assets/demo-update.gif)
+
+That installs the daily community release from
+[chenditc/investment_data](https://github.com/chenditc/investment_data) into
+`~/.qlib/qlib_data/cn_data`, the location Qlib reads by default. Run the same command again
+any time; when the data is already current it finishes in about a second.
+
+## Why not just `wget` and `tar`?
+
+<img src="docs/assets/comic.jpg" width="560" alt="Four-panel comic: a download dies at 99% at night; the next day 550 MB arrive and nothing changed; the qlib-sync robot checks the data and stamps it verified, keeping the old copy safe; the researcher sips tea and asks an AI for Moutai's recent closes">
+
+Qlib's README points A-share users to the community release with a `wget` and `tar` one-liner.
+That works until it doesn't:
+
+- **An interrupted or truncated download** extracts into a half-written dataset, or fails
+  after the old one has already been overwritten.
+- **Upstream republishes releases.** In November 2026 a data error was found and corrected
+  ([investment_data#163](https://github.com/chenditc/investment_data/issues/163)) and releases
+  were republished under the same date. A date check alone never sees the fix.
+- **Every check downloads 550 MB**, even when nothing changed.
+
+The investment_data README itself describes a careful manual process: download the release
+manifest, check the archive with its `validate_archive.py`, then extract. qlib-sync runs the
+same checks automatically on every update and adds what a manual process cannot: it skips the
+download when nothing changed, extracts beside the live data and swaps it in with rollback
+(rather than extracting on top of the existing folder), and picks up republished releases.
+
+qlib-sync treats the dataset like a production system:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/update-flow-dark.svg">
+  <img alt="Update flow: check the manifest, download, verify, stage, swap; any failure puts the previous dataset back" src="docs/assets/update-flow-light.svg">
+</picture>
+
+| Step | What happens |
+|---|---|
+| Check | Reads the release's 500-byte manifest. Already current: done, nothing downloaded. |
+| Download | Resumes interrupted downloads; shows progress; optional mirror for slow links to GitHub. |
+| Verify | Size and sha256 from the manifest; the same release checks as upstream's `validate_archive.py` (every index pool and the future calendar reach the manifest's dates, release marked publishable); archive paths and links are checked before extraction. |
+| Stage | Extracts next to the active dataset; refuses downgrades. |
+| Swap | Renames the new dataset into place, then runs a real Qlib read. |
+| Roll back | Any failure after the swap moves the previous dataset back. |
+| Report | New trading days, newly listed and delisted symbols. |
+
+The checks catch broken, truncated, or tampered packages. They cannot catch wrong values inside a
+correctly published release (like the one in #163); for that, keep a rollback copy with
+`--keep-backup`.
+
+## Commands
+
+```bash
+qlib-sync status                  # every local Qlib dataset at a glance
+qlib-sync cn status               # local date, pools, and whether a newer release exists
+qlib-sync cn update               # install or update (add --json for machine-readable output)
+qlib-sync cn health-check         # structure checks plus a real Qlib read
+qlib-sync cn restore --list       # rollback backups; restore --yes switches back
+```
+
+Useful options for `cn update`:
+
+| Option | Effect |
+|---|---|
+| `--data-dir PATH` | Install somewhere other than `~/.qlib/qlib_data/cn_data` |
+| `--mirror URL` | Download through a prefix-style GitHub proxy such as `https://ghfast.top` (or set `QLIB_SYNC_MIRROR`) |
+| `--keep-backup` | Keep the previous dataset for one rollback |
+| `--protect FILE` | Carry a custom stock pool in `instruments/` across updates (repeatable) |
+| `--force` | Reinstall even when the dates match |
+
+**The update replaces the whole `cn_data` folder.** Anything you added there is lost unless you
+pass it with `--protect`.
+
+### Mirrors
+
+From mainland China, GitHub downloads can be slow or fail. Pass a mirror and qlib-sync downloads
+the package through it while still reading the manifest from GitHub directly when it can, so the
+checksum does not depend on the mirror. Mirrors are third-party services; qlib-sync does not
+endorse any of them.
+
+## Python
+
+```python
+from qlib_sync import update_cn, status_cn, health_check_cn
+
+result = update_cn()                 # raises qlib_sync.UpdateError on failure; data unchanged
+print("\n".join(result.summary_lines()))
+print(result.new_trading_days, result.added_symbols)
+```
+
+## Use it from your AI assistant
+
+qlib-sync includes an [MCP](https://modelcontextprotocol.io) server, the open standard most AI
+tools use to call local tools. Any MCP client that can start a local command works, whichever
+model it runs: Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, or a local model. The server
+runs on your machine and reads the dataset there; there is no service to host and nothing
+leaves your computer. It is listed in the [MCP Registry](https://registry.modelcontextprotocol.io)
+as `io.github.randyy179/qlib-sync`.
+
+Every client needs the same two things: the command `uvx` and the arguments `qlib-sync mcp`.
+
+| Client | How to add qlib-sync |
+|---|---|
+| Claude Desktop | Download `qlib-sync.mcpb` from the [latest release](https://github.com/randyy179/qlib-sync/releases/latest) and open it |
+| Claude Code | `claude mcp add qlib-sync -- uvx qlib-sync mcp` |
+| OpenAI Codex CLI | `codex mcp add qlib-sync -- uvx qlib-sync mcp` |
+| Cursor | The JSON below, in `~/.cursor/mcp.json` |
+| Gemini CLI | The JSON below, in `~/.gemini/settings.json` |
+| Qwen Code | The JSON below, in `~/.qwen/settings.json` |
+| Tencent CodeBuddy, ByteDance Trae, Alibaba Tongyi Lingma | MCP settings, add a server manually, paste the JSON below |
+| Cherry Studio | Settings, MCP servers, add: type STDIO, command `uvx`, arguments `qlib-sync` and `mcp` on separate lines |
+| VS Code (Copilot agent mode) | `.vscode/mcp.json`: `{ "servers": { "qlib-sync": { "type": "stdio", "command": "uvx", "args": ["qlib-sync", "mcp"] } } }` |
+
+```json
+{ "mcpServers": { "qlib-sync": { "command": "uvx", "args": ["qlib-sync", "mcp"] } } }
+```
+
+Menu names and file locations change between versions; check your client's MCP documentation
+if a path above has moved. Tested with Claude Code and OpenAI Codex CLI.
+
+Web chat apps such as ChatGPT connect only to remote MCP servers over the internet, so they
+cannot start this local server.
+
+Set `QLIB_SYNC_DATA_DIR` to use a dataset outside `~/.qlib/qlib_data/cn_data`, and
+`QLIB_SYNC_MIRROR` to download through a mirror.
+
+| Tool | Does |
+|---|---|
+| `cn_status` | Local latest date, pools, and whether an update is available |
+| `cn_update` | Install or update (safe to call: failures restore the previous data) |
+| `cn_health_check` | Structure checks plus a real Qlib read |
+| `cn_get_prices` | Daily bars for up to 20 symbols; real traded prices by default, adjusted on request |
+| `cn_list_pool` | Members of csi300, csi500, and other pools on a date |
+
+Then ask things like *"Is my A-share data current? What did Moutai close at over the last
+week?"* Symbols accept `600519`, `SH600519`, or `600519.SH`.
+
+![Claude Code answering from the local dataset through qlib-sync: data freshness, Moutai closes, CSI 300 size](docs/assets/demo-claude.gif)
+
+[`skills/qlib-sync/SKILL.md`](skills/qlib-sync/SKILL.md) teaches an assistant when to update,
+how to read each failure, and the price conventions. It uses the open `SKILL.md` format that
+Claude, Codex, and other agents load from their skills folder; any assistant can also simply
+be pointed at the file.
+
+## Daily updates
+
+A run that finds nothing new costs one small request, so schedule it daily. See
+[docs/scheduling.md](docs/scheduling.md) for cron and launchd examples.
+
+## Data and credits
+
+All data comes from [chenditc/investment_data](https://github.com/chenditc/investment_data)
+(Apache-2.0). qlib-sync only downloads the public release; it does not host or redistribute
+data. Prices follow Qlib's convention: `$close` is adjusted and the real price is
+`$close / $factor`.
+
+qlib-sync is an independent project, not affiliated with Microsoft or the Qlib team.
+
+Supported: macOS and Linux, Python 3.10 to 3.12 (pyqlib does not publish wheels for newer
+versions yet; `uvx` picks a compatible Python automatically).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+## License
+
+MIT

qlib_sync-0.1.0/README.zh-CN.md

@@ -0,0 +1,156 @@
+# qlib-sync
+
+[English](README.md)
+
+**网站：**[randyy179.github.io/qlib-sync](https://randyy179.github.io/qlib-sync/)
+
+**一条命令安装并保持更新本地 [Qlib](https://github.com/microsoft/qlib) A 股数据，并提供 MCP server，让 AI 助手直接读取。**
+
+```bash
+pip install qlib-sync
+qlib-sync cn update
+```
+
+也可以不预先安装，直接运行：`uvx qlib-sync cn update`。
+
+![qlib-sync 更新数据：查看状态、带进度下载、校验、汇报变化，再运行一次瞬间完成](docs/assets/demo-update.gif)
+
+数据来自 [chenditc/investment_data](https://github.com/chenditc/investment_data) 每天的社区发布，安装到 Qlib 默认读取的位置 `~/.qlib/qlib_data/cn_data`。原来的 Qlib 代码不用改。之后随时再运行同一条命令，数据已是最新时大约 1 秒结束。
+
+## 为什么不直接 `wget` 加 `tar`？
+
+<img src="docs/assets/comic.jpg" width="560" alt="四格漫画：深夜下载 A 股数据断在 99%；第二天又下了 550MB 结果啥也没变；qlib-sync 机器人先校验再替换、出错自动回滚；研究员喝着茶让 AI 直接读最新数据">
+
+Qlib 的 README 推荐用 `wget` 下载社区数据包再用 `tar` 解压。平时没问题，但会遇到这些情况：
+
+- **下载中断或不完整**：解压出半截数据，或者旧数据已经被覆盖了才发现失败。
+- **上游会重新发布**：2026 年 11 月，上游发现并修正了一处数据错误（[investment_data#163](https://github.com/chenditc/investment_data/issues/163)），用同一个日期重新发布了数据包。只比较日期的话，永远拿不到修复后的数据。
+- **每次检查都要下载 550MB**，即使什么都没变。
+
+investment_data 自己的 README 也给出了一套严谨的手动流程：下载发布清单（manifest），用它的 `validate_archive.py` 校验数据包，再解压。qlib-sync 每次更新都自动执行同样的校验，并补上手动流程做不到的部分：没有新数据时不下载；在旧数据旁边解压，校验通过后整体切换、失败回滚（而不是直接解压覆盖到现有目录）；能拿到上游重新发布的修复版。
+
+qlib-sync 把本地数据当生产系统来管理：
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/update-flow-dark.svg">
+  <img alt="更新流程：读 manifest、下载、校验、准备、切换；任何一步失败都会恢复原有数据" src="docs/assets/update-flow-light.svg">
+</picture>
+
+| 步骤 | 做什么 |
+|---|---|
+| 检查 | 先读发布附带的 500 字节 manifest。已是最新就结束，不下载 |
+| 下载 | 支持断点续传、显示进度；网络慢时可走镜像 |
+| 校验 | 核对大小和 sha256；执行与上游 `validate_archive.py` 相同的发布检查（各指数成分和未来交易日历都与 manifest 日期一致、发布标记为可发布）；解压前检查路径和链接是否安全 |
+| 准备 | 解压到旧数据旁边的临时目录；拒绝降级 |
+| 切换 | 把新数据换上去，再用 Qlib 实际读一次 |
+| 回滚 | 切换后任何一步失败，自动换回旧数据 |
+| 汇报 | 新增了哪些交易日、新上市和退市的股票 |
+
+这些校验能挡住损坏、不完整或被篡改的数据包，**挡不住上游正常发布的数据里本身的数值错误**（比如 #163 那种）。需要防这类问题时，可以加 `--keep-backup` 保留一份可回滚的旧数据。
+
+## 命令
+
+```bash
+qlib-sync status                  # 所有本地 Qlib 数据集一览
+qlib-sync cn status               # 本地到哪天、有哪些股票池、远端有没有更新
+qlib-sync cn update               # 安装或更新（加 --json 输出机器可读结果）
+qlib-sync cn health-check         # 结构检查加一次真实的 Qlib 读取
+qlib-sync cn restore --list       # 查看备份；restore --yes 换回备份
+```
+
+`cn update` 的常用选项：
+
+| 选项 | 作用 |
+|---|---|
+| `--data-dir 路径` | 安装到 `~/.qlib/qlib_data/cn_data` 以外的位置 |
+| `--mirror 地址` | 通过前缀式 GitHub 代理下载，如 `https://ghfast.top`（也可设环境变量 `QLIB_SYNC_MIRROR`） |
+| `--keep-backup` | 保留一份旧数据用于回滚 |
+| `--protect 文件名` | 更新后保留 `instruments/` 里自定义的股票池文件（可重复使用） |
+| `--force` | 日期相同也重新安装 |
+
+**注意：更新会替换整个 `cn_data` 目录。** 你自己放进去的文件，除非用 `--protect` 指定，否则会丢失。
+
+### 国内镜像
+
+在国内访问 GitHub 下载经常很慢甚至失败。指定镜像后，数据包走镜像下载，manifest 仍尽量直接从 GitHub 读取，这样校验值不依赖镜像本身。镜像是第三方服务，qlib-sync 不对任何镜像做担保。
+
+```bash
+qlib-sync cn update --mirror https://ghfast.top
+```
+
+## 在 Python 里使用
+
+```python
+from qlib_sync import update_cn, status_cn, health_check_cn
+
+result = update_cn()                 # 失败时抛出 qlib_sync.UpdateError，原有数据不受影响
+print("\n".join(result.summary_lines()))
+print(result.new_trading_days, result.added_symbols)
+```
+
+## 在你的 AI 助手中使用
+
+qlib-sync 自带一个 [MCP](https://modelcontextprotocol.io) server。MCP 是大多数 AI 工具调用本地工具的开放标准，所以只要你用的工具能启动本地命令，就能接入，不管它背后用的是哪个模型：Claude、GPT、Gemini、DeepSeek、通义千问、Kimi、智谱 GLM，或者本地部署的开源模型都可以。
+
+MCP server 在你本机运行，读取你电脑上的数据，不需要搭建任何服务器，数据也不会离开你的电脑。也可以在 [MCP Registry](https://registry.modelcontextprotocol.io) 搜索 `io.github.randyy179/qlib-sync`。
+
+各个工具需要填的内容都一样：命令 `uvx`，参数 `qlib-sync mcp`。
+
+| 工具 | 接入方式 |
+|---|---|
+| Claude Desktop | 从[最新发布](https://github.com/randyy179/qlib-sync/releases/latest)下载 `qlib-sync.mcpb`，双击安装 |
+| Claude Code | `claude mcp add qlib-sync -- uvx qlib-sync mcp` |
+| OpenAI Codex CLI | `codex mcp add qlib-sync -- uvx qlib-sync mcp` |
+| 腾讯 CodeBuddy、字节 Trae、阿里通义灵码 | 在 MCP 设置里手动添加服务器，粘贴下面的 JSON |
+| Cherry Studio | 设置 → MCP 服务器 → 添加：类型选 STDIO，命令填 `uvx`，参数分两行填 `qlib-sync` 和 `mcp` |
+| 通义千问 Qwen Code | 把下面的 JSON 写进 `~/.qwen/settings.json` |
+| Cursor | 把下面的 JSON 写进 `~/.cursor/mcp.json` |
+| Gemini CLI | 把下面的 JSON 写进 `~/.gemini/settings.json` |
+| VS Code（Copilot Agent 模式） | `.vscode/mcp.json`：`{ "servers": { "qlib-sync": { "type": "stdio", "command": "uvx", "args": ["qlib-sync", "mcp"] } } }` |
+
+```json
+{ "mcpServers": { "qlib-sync": { "command": "uvx", "args": ["qlib-sync", "mcp"] } } }
+```
+
+各工具的菜单名称和配置文件位置会随版本变化，找不到时以该工具的 MCP 官方文档为准。已实测：Claude Code、OpenAI Codex CLI。
+
+ChatGPT 这类网页聊天应用只能连接互联网上的远程 MCP server，无法启动本地程序，所以暂时用不了。
+
+数据不在默认位置时设置环境变量 `QLIB_SYNC_DATA_DIR`；需要走镜像时设置 `QLIB_SYNC_MIRROR`。
+
+| 工具 | 作用 |
+|---|---|
+| `cn_status` | 本地数据到哪天、有哪些股票池、有没有更新 |
+| `cn_update` | 安装或更新（可放心调用：失败会自动恢复旧数据） |
+| `cn_health_check` | 结构检查加一次真实的 Qlib 读取 |
+| `cn_get_prices` | 最多 20 只股票的日线；默认返回真实成交价，可选复权价 |
+| `cn_list_pool` | 某天沪深 300、中证 500 等股票池的成分股 |
+
+接好之后可以直接问："我的 A 股数据是最新的吗？茅台最近一周收盘价多少？" 股票代码写 `600519`、`SH600519`、`600519.SH` 都可以。
+
+![Claude Code 通过 qlib-sync 读取本地数据回答：数据是否最新、茅台收盘价、沪深 300 成分数量](docs/assets/demo-claude.gif)
+
+[`skills/qlib-sync/SKILL.md`](skills/qlib-sync/SKILL.md) 教 AI 什么时候该更新、每种错误怎么处理、价格口径是什么。它采用开放的 `SKILL.md` 格式，Claude、Codex 等工具可以直接从 skills 目录加载；其他 AI 助手也可以直接让它读这个文件。
+
+## 每天自动更新
+
+没有新数据时只花一次很小的请求，所以每天定时跑就行。cron 和 launchd 的配置示例见 [docs/scheduling.md](docs/scheduling.md)。
+
+## 数据来源与致谢
+
+全部数据来自 [chenditc/investment_data](https://github.com/chenditc/investment_data)（Apache-2.0 协议）。qlib-sync 只下载其公开发布的文件，不托管、不分发数据。价格遵循 Qlib 的约定：`$close` 是复权价，真实价格是 `$close / $factor`。
+
+qlib-sync 是独立项目，与微软及 Qlib 团队无关。
+
+支持 macOS 和 Linux，Python 3.10 到 3.12（pyqlib 暂未发布更新版本的安装包；用 `uvx` 时会自动选择兼容的 Python）。
+
+## 开发
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+## 协议
+
+MIT