pyqauto 0.3.0__tar.gz

pyqauto-0.3.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.3.0 - 2026-06-18
+
+- Renamed the PyPI package, Python import package, CLI command, and GitHub
+  repository to `pyqauto`.
+- Replaced the former `aquote-router` package name and `aquote_router` import
+  path with `pyqauto`.
+- Kept the public quote, K-line, source policy, diagnostics, and audit behavior
+  unchanged.
+- Added migration documentation for users moving from the old package name.
+- Kept the release path on GitHub Actions Trusted Publishing only; no local
+  twine upload or password-based PyPI publishing is used.
+
+## 0.2.2 - 2026-06-17
+
+- Bundled default source policy and pytdx server config as package data.
+- Added the short `aquote` import alias and simple module-level functions such as
+  `quote`, `quotes`, `kline`, and `daily`.
+- Allowed `QuoteRouter.from_config()` to run without user-supplied config paths.
+- Preserved compatibility for legacy `config/source_policy.example.yaml` and
+  `config/pytdx_servers.example.json` example paths when local files are absent.
+- Updated public examples and quickstart docs to avoid requiring copied config files.
+
+## 0.2.1 - 2026-06-15
+
+- Added and documented pytdx server probe diagnostics.
+- Added `pyqauto probe-pytdx`.
+- Strengthened K-line timeout troubleshooting docs.
+- Strengthened live check docs for active local pytdx pools.
+- Clarified that active local server pools are not committed to Git.
+- Kept the project boundary unchanged and added no investment advice workflow.
+
+## 0.2.0 - 2026-06-15
+
+- Added `daily_kline`.
+- Added unified `kline`.
+- Documented all supported minute K-line periods including `15m`.
+- Added `DATA_SOURCES`, `API_REFERENCE`, `KLINE_GUIDE`, `RETURN_FIELDS`, and `CLI_REFERENCE`.
+- Added troubleshooting, error code, symbol, time, unit, upstream risk, roadmap and adapter contributor docs.
+- Added stable error codes and enhanced `pyqauto diagnose --json`.
+- Added issue templates for bug reports, data source failures, adapter requests and documentation issues.
+- Added offline tests for open-source maintenance and diagnostics workflows.
+
+## 0.1.0 - 2026-06-14
+
+- Initial open-source release.
+- Added pytdx server pool routing with primary, hot backup and backup roles.
+- Added easyquotation Sina and Tencent fallback for realtime APIs.
+- Added pytdx-only minute kline routing.
+- Added source policy, normalized quote model, JSONL audit and SQLite audit.
+- Added CLI, examples, tests, GitHub Actions and release checklist.

pyqauto-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+We follow the Contributor Covenant spirit: be respectful, constructive and focused on improving the project.
+
+Harassment, discrimination, spam and abusive behavior are not acceptable in project spaces.
+
+Maintainers may edit, hide or remove content that is hostile, off-topic or unsafe for public collaboration.

pyqauto-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thank you for helping improve pyqauto.
+
+## Development
+
+```bash
+python -X utf8 -m pip install -e ".[dev,test]"
+python -X utf8 -m pytest -q
+python -X utf8 scripts/check_release.py
+```
+
+## Rules
+
+- Keep Python source files UTF-8.
+- Use explicit `encoding="utf-8"` for text reads and writes.
+- Default tests must not connect to live quote sources.
+- Live smoke tests must require `ENABLE_LIVE_SMOKE_TEST=1`.
+- Add adapter tests before adding a real data source.
+- Preserve normalized fields and audit schema compatibility.
+- Do not commit private configuration, credentials or local absolute paths.
+
+## Pull Requests
+
+Every pull request should include:
+
+- What changed.
+- Which tests ran.
+- Whether source policy or audit schema changed.
+- Any user-visible compatibility notes.

pyqauto-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aquote-router contributors
+
+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.

pyqauto-0.3.0/MANIFEST.in

@@ -0,0 +1,25 @@
+include README.md
+include README.zh-CN.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include CODE_OF_CONDUCT.md
+include pyproject.toml
+recursive-include config *.json *.yaml
+recursive-include pyqauto/config *.json *.yaml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include scripts *.py *.bat
+recursive-include tests *.py
+prune logs
+exclude config/pytdx_servers.active.local.json
+exclude config/pytdx_servers.local.json
+exclude LIVE_CHECK_REPORT.md
+exclude LIVE_CHECK_SUMMARY.json
+exclude LIVE_CHECK_LOG.txt
+exclude PYTDX_SERVER_POOL_REFRESH_REPORT.md
+exclude PYTDX_SERVER_POOL_REFRESH_SUMMARY.json
+exclude PYTDX_SERVER_POOL_REFRESH_LOG.txt
+global-exclude *.jsonl
+global-exclude *.sqlite3

pyqauto-0.3.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: pyqauto
+Version: 0.3.0
+Summary: A-share quote source router with pytdx failover, easyquotation fallback and audit trail
+Author: pyqauto contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tabman2026/pyqauto
+Project-URL: Repository, https://github.com/tabman2026/pyqauto
+Project-URL: Documentation, https://github.com/tabman2026/pyqauto/tree/main/docs
+Project-URL: Issues, https://github.com/tabman2026/pyqauto/issues
+Project-URL: Changelog, https://github.com/tabman2026/pyqauto/blob/main/CHANGELOG.md
+Keywords: a-share,stock-market,quote-router,market-data,pytdx,easyquotation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: easyquotation>=0.7
+Requires-Dist: pytdx>=1.72
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: docs
+Dynamic: license-file
+
+# pyqauto
+
+pyqauto 是一个面向 A 股行情获取的 Python 行情源自动选择工具，支持 pytdx 主备切换、easyquotation fallback、实时行情、分钟K线、日K、统一 kline 接口、source policy 和 JSONL / SQLite 审计追踪。
+
+Python A-share quote auto-selector with pytdx failover, easyquotation fallback, K-line APIs and audit trail.
+
+```bash
+python -X utf8 -m pip install pyqauto -i https://pypi.org/simple
+```
+
+```python
+from pyqauto import QuoteRouter
+```
+
+```bash
+pyqauto realtime 000001 600000
+pyqauto kline 000001 --period 15m --count 10
+pyqauto probe-pytdx --json
+```
+
+本项目不提供投资建议，不生成候选股池，不生成买卖点，不接入真实交易，不保证公开免费行情源 100% 准确、实时、完整、可用。
+
+[![PyPI version](https://img.shields.io/pypi/v/pyqauto.svg)](https://pypi.org/project/pyqauto/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyqauto.svg)](https://pypi.org/project/pyqauto/)
+[![CI](https://github.com/tabman2026/pyqauto/actions/workflows/ci.yml/badge.svg)](https://github.com/tabman2026/pyqauto/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/tabman2026/pyqauto?display_name=tag)](https://github.com/tabman2026/pyqauto/releases)
+
+It is designed for research scripts that need A股行情, A股实时行情, A股K线,
+分钟K线, 15分钟K线, 日K, source policy, 数据源 fallback, 行情审计, `trace_id`,
+JSONL, and SQLite audit records in one small Python package. Realtime routing
+uses pytdx first, then easyquotation Sina and Tencent fallback according to
+policy.
+
+Boundary: this project is data access infrastructure only. It does not provide investment advice,
+account login, order execution, screening, timing signals, or performance claims.
+
+## 中文文档
+
+- 中文快速开始：[README.zh-CN.md](README.zh-CN.md)
+- 新手从这里开始：[docs/NEW_USER_START_HERE.md](docs/NEW_USER_START_HERE.md)
+- K线使用指南：[docs/KLINE_GUIDE.md](docs/KLINE_GUIDE.md)
+- 数据源说明：[docs/DATA_SOURCES.md](docs/DATA_SOURCES.md)
+- 常见问题排查：[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+
+English start here: [docs/NEW_USER_START_HERE.md](docs/NEW_USER_START_HERE.md)
+
+Data source policy: [docs/DATA_SOURCES.md](docs/DATA_SOURCES.md)
+
+Issue guide: [docs/ISSUE_GUIDE.md](docs/ISSUE_GUIDE.md)
+
+Examples: [realtime](examples/realtime_quotes_demo.py),
+[15m K-line](examples/minute_kline_15m_demo.py), and
+[daily K-line](examples/daily_kline_demo.py)
+
+## Install
+
+```bash
+python -X utf8 -m pip install pyqauto
+```
+
+## Minimal Realtime Quote
+
+```python
+import pyqauto as aq
+
+record = aq.quote("000001")
+print(record.to_dict())
+```
+
+Default source policy and pytdx server config are bundled in the package.
+Import and call functions directly. No local config files are required.
+
+## Minimal 15m K-line
+
+```python
+bars = aq.kline("000001", period="15m", count=120)
+print(bars[0].to_dict())
+```
+
+## K-line Timeout Check
+
+K-line APIs are pytdx-only. If a K-line call times out, first probe the pytdx
+server pool for the current network:
+
+```bash
+pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
+```
+
+Then pass the active local pool explicitly:
+
+```bash
+pyqauto kline 000001 --period 15m --count 10 \
+  --pytdx-servers config/pytdx_servers.active.local.json --json
+```
+
+`config/pytdx_servers.active.local.json` is a local diagnostic result and should
+not be committed.
+
+## Features
+
+- `realtime_quotes`, `full_realtime_quotes`, and `index_realtime` route through
+  `pytdx -> easyquotation_sina -> easyquotation_tencent`.
+- `minute_kline`, `daily_kline`, and unified `kline` are pytdx-only.
+- pytdx servers are ordered by `primary -> hot_backup -> backup`, then by
+  `latency_ms`.
+- `probe-pytdx` can generate a local active pytdx server pool for diagnostics.
+- Return models include `source`, `source_level`, `is_fallback`,
+  `fallback_from`, and `trace_id`.
+- JSONL and SQLite audit logs record attempts, `fallback_chain`,
+  `selected_source`, duration, record count, and final error details.
+- The default test suite is offline. Live smoke checks require explicit opt-in.
+
+Local development:
+
+```bash
+python -X utf8 -m pip install -e ".[dev,test]"
+```
+
+## Quick Start
+
+```python
+import pyqauto as aq
+
+aq.configure(
+    audit_jsonl_path="logs/pyqauto_audit.jsonl",
+    audit_sqlite_path="logs/pyqauto_audit.sqlite3",
+)
+
+records = aq.quotes(["000001", "600000"])
+for record in records:
+    print(record.to_dict())
+```
+
+K-line examples:
+
+```python
+aq.minute("000001", period="15m", count=120)
+aq.daily("000001", count=120)
+aq.kline("000001", period="1d", count=120)
+```
+
+## Public API
+
+```python
+aq.quote("000001")
+aq.quotes(["000001", "600000"])
+aq.full_quotes(["000001", "600000"])
+aq.index(["000001", "399001"])
+aq.minute("000001", period="15m", count=120)
+aq.daily("000001", count=120)
+aq.kline("000001", period="1d", count=120)
+aq.diagnose()
+```
+
+For advanced use, `from pyqauto import QuoteRouter` remains available.
+
+## CLI
+
+```bash
+pyqauto realtime 000001 600000
+pyqauto full 000001 600000
+pyqauto full-realtime 000001 600000
+pyqauto index 000001 399001
+pyqauto minute 000001 --period 15m --count 120
+pyqauto daily 000001 --count 120
+pyqauto kline 000001 --period 15m --count 120
+pyqauto kline 000001 --period 1d --count 120
+pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
+pyqauto diagnose --json
+```
+
+Use `--json` for complete output, especially when table columns are too wide.
+CLI failures return a non-zero exit code and a structured project error code.
+
+When K-line calls time out, first refresh a local pytdx pool:
+
+```bash
+pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
+```
+
+Then pass the active local pool explicitly:
+
+```bash
+pyqauto kline 000001 --period 15m --count 10 \
+  --pytdx-servers config/pytdx_servers.active.local.json --json
+```
+
+`config/pytdx_servers.active.local.json` is an observed local diagnostic result
+and should not be committed. Free pytdx server availability changes by network,
+region, and time; this project does not promise that every environment can
+connect at every time.
+
+## Source Policy
+
+Default realtime routing:
+
+```text
+realtime_quotes: pytdx -> easyquotation_sina -> easyquotation_tencent
+full_realtime_quotes: pytdx -> easyquotation_sina -> easyquotation_tencent
+index_realtime: pytdx -> easyquotation_sina -> easyquotation_tencent
+```
+
+Default K-line routing:
+
+```text
+minute_kline: pytdx only
+daily_kline: pytdx only
+kline: pytdx only
+```
+
+K-line APIs never fall back to easyquotation and never fabricate bars.
+Realtime APIs may fall back to `easyquotation_sina` or `easyquotation_tencent`
+after pytdx failures, but K-line APIs do not use easyquotation fallback.
+
+## Core Docs
+
+- [Quickstart](docs/QUICKSTART.md)
+- [Start here](docs/NEW_USER_START_HERE.md)
+- [API reference](docs/API_REFERENCE.md)
+- [K-line guide](docs/KLINE_GUIDE.md)
+- [Data sources](docs/DATA_SOURCES.md)
+- [Issue guide](docs/ISSUE_GUIDE.md)
+- [Return fields](docs/RETURN_FIELDS.md)
+- [CLI reference](docs/CLI_REFERENCE.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Error codes](docs/ERROR_CODES.md)
+- [Symbol rules](docs/SYMBOL_RULES.md)
+- [Units](docs/UNITS.md)
+- [Source policy](docs/SOURCE_POLICY.md)
+- [Audit trail](docs/AUDIT_TRAIL.md)
+- [Time and trading day](docs/TIME_AND_TRADING_DAY.md)
+- [Upstream license and risk](docs/UPSTREAM_LICENSE_AND_RISK.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Contributor adapter guide](docs/CONTRIBUTOR_ADAPTER_GUIDE.md)
+- [Maintainer checklist](docs/MAINTAINER_CHECKLIST.md)
+
+## Audit Trail
+
+Each routed call receives a `trace_id`. Audit records include:
+
+- `api_name`
+- `symbols`
+- `started_at`, `finished_at`, `duration_ms`
+- `selected_source`, `selected_source_level`
+- `attempts`
+- `fallback_chain`
+- `success`
+- `error_type`, `error_message`
+- `record_count`
+
+See [docs/AUDIT_TRAIL.md](docs/AUDIT_TRAIL.md).
+
+## Risk Notice
+
+This package does not produce market data. It calls upstream public Python
+libraries and their public interfaces. Upstream data may be delayed,
+unavailable, incomplete, or structurally changed. Users are responsible for
+validating data quality and following the terms of each upstream project.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

pyqauto-0.3.0/README.md

@@ -0,0 +1,263 @@
+# pyqauto
+
+pyqauto 是一个面向 A 股行情获取的 Python 行情源自动选择工具，支持 pytdx 主备切换、easyquotation fallback、实时行情、分钟K线、日K、统一 kline 接口、source policy 和 JSONL / SQLite 审计追踪。
+
+Python A-share quote auto-selector with pytdx failover, easyquotation fallback, K-line APIs and audit trail.
+
+```bash
+python -X utf8 -m pip install pyqauto -i https://pypi.org/simple
+```
+
+```python
+from pyqauto import QuoteRouter
+```
+
+```bash
+pyqauto realtime 000001 600000
+pyqauto kline 000001 --period 15m --count 10
+pyqauto probe-pytdx --json
+```
+
+本项目不提供投资建议，不生成候选股池，不生成买卖点，不接入真实交易，不保证公开免费行情源 100% 准确、实时、完整、可用。
+
+[![PyPI version](https://img.shields.io/pypi/v/pyqauto.svg)](https://pypi.org/project/pyqauto/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyqauto.svg)](https://pypi.org/project/pyqauto/)
+[![CI](https://github.com/tabman2026/pyqauto/actions/workflows/ci.yml/badge.svg)](https://github.com/tabman2026/pyqauto/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/tabman2026/pyqauto?display_name=tag)](https://github.com/tabman2026/pyqauto/releases)
+
+It is designed for research scripts that need A股行情, A股实时行情, A股K线,
+分钟K线, 15分钟K线, 日K, source policy, 数据源 fallback, 行情审计, `trace_id`,
+JSONL, and SQLite audit records in one small Python package. Realtime routing
+uses pytdx first, then easyquotation Sina and Tencent fallback according to
+policy.
+
+Boundary: this project is data access infrastructure only. It does not provide investment advice,
+account login, order execution, screening, timing signals, or performance claims.
+
+## 中文文档
+
+- 中文快速开始：[README.zh-CN.md](README.zh-CN.md)
+- 新手从这里开始：[docs/NEW_USER_START_HERE.md](docs/NEW_USER_START_HERE.md)
+- K线使用指南：[docs/KLINE_GUIDE.md](docs/KLINE_GUIDE.md)
+- 数据源说明：[docs/DATA_SOURCES.md](docs/DATA_SOURCES.md)
+- 常见问题排查：[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+
+English start here: [docs/NEW_USER_START_HERE.md](docs/NEW_USER_START_HERE.md)
+
+Data source policy: [docs/DATA_SOURCES.md](docs/DATA_SOURCES.md)
+
+Issue guide: [docs/ISSUE_GUIDE.md](docs/ISSUE_GUIDE.md)
+
+Examples: [realtime](examples/realtime_quotes_demo.py),
+[15m K-line](examples/minute_kline_15m_demo.py), and
+[daily K-line](examples/daily_kline_demo.py)
+
+## Install
+
+```bash
+python -X utf8 -m pip install pyqauto
+```
+
+## Minimal Realtime Quote
+
+```python
+import pyqauto as aq
+
+record = aq.quote("000001")
+print(record.to_dict())
+```
+
+Default source policy and pytdx server config are bundled in the package.
+Import and call functions directly. No local config files are required.
+
+## Minimal 15m K-line
+
+```python
+bars = aq.kline("000001", period="15m", count=120)
+print(bars[0].to_dict())
+```
+
+## K-line Timeout Check
+
+K-line APIs are pytdx-only. If a K-line call times out, first probe the pytdx
+server pool for the current network:
+
+```bash
+pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
+```
+
+Then pass the active local pool explicitly:
+
+```bash
+pyqauto kline 000001 --period 15m --count 10 \
+  --pytdx-servers config/pytdx_servers.active.local.json --json
+```
+
+`config/pytdx_servers.active.local.json` is a local diagnostic result and should
+not be committed.
+
+## Features
+
+- `realtime_quotes`, `full_realtime_quotes`, and `index_realtime` route through
+  `pytdx -> easyquotation_sina -> easyquotation_tencent`.
+- `minute_kline`, `daily_kline`, and unified `kline` are pytdx-only.
+- pytdx servers are ordered by `primary -> hot_backup -> backup`, then by
+  `latency_ms`.
+- `probe-pytdx` can generate a local active pytdx server pool for diagnostics.
+- Return models include `source`, `source_level`, `is_fallback`,
+  `fallback_from`, and `trace_id`.
+- JSONL and SQLite audit logs record attempts, `fallback_chain`,
+  `selected_source`, duration, record count, and final error details.
+- The default test suite is offline. Live smoke checks require explicit opt-in.
+
+Local development:
+
+```bash
+python -X utf8 -m pip install -e ".[dev,test]"
+```
+
+## Quick Start
+
+```python
+import pyqauto as aq
+
+aq.configure(
+    audit_jsonl_path="logs/pyqauto_audit.jsonl",
+    audit_sqlite_path="logs/pyqauto_audit.sqlite3",
+)
+
+records = aq.quotes(["000001", "600000"])
+for record in records:
+    print(record.to_dict())
+```
+
+K-line examples:
+
+```python
+aq.minute("000001", period="15m", count=120)
+aq.daily("000001", count=120)
+aq.kline("000001", period="1d", count=120)
+```
+
+## Public API
+
+```python
+aq.quote("000001")
+aq.quotes(["000001", "600000"])
+aq.full_quotes(["000001", "600000"])
+aq.index(["000001", "399001"])
+aq.minute("000001", period="15m", count=120)
+aq.daily("000001", count=120)
+aq.kline("000001", period="1d", count=120)
+aq.diagnose()
+```
+
+For advanced use, `from pyqauto import QuoteRouter` remains available.
+
+## CLI
+
+```bash
+pyqauto realtime 000001 600000
+pyqauto full 000001 600000
+pyqauto full-realtime 000001 600000
+pyqauto index 000001 399001
+pyqauto minute 000001 --period 15m --count 120
+pyqauto daily 000001 --count 120
+pyqauto kline 000001 --period 15m --count 120
+pyqauto kline 000001 --period 1d --count 120
+pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
+pyqauto diagnose --json
+```
+
+Use `--json` for complete output, especially when table columns are too wide.
+CLI failures return a non-zero exit code and a structured project error code.
+
+When K-line calls time out, first refresh a local pytdx pool:
+
+```bash
+pyqauto probe-pytdx --json --output config/pytdx_servers.active.local.json
+```
+
+Then pass the active local pool explicitly:
+
+```bash
+pyqauto kline 000001 --period 15m --count 10 \
+  --pytdx-servers config/pytdx_servers.active.local.json --json
+```
+
+`config/pytdx_servers.active.local.json` is an observed local diagnostic result
+and should not be committed. Free pytdx server availability changes by network,
+region, and time; this project does not promise that every environment can
+connect at every time.
+
+## Source Policy
+
+Default realtime routing:
+
+```text
+realtime_quotes: pytdx -> easyquotation_sina -> easyquotation_tencent
+full_realtime_quotes: pytdx -> easyquotation_sina -> easyquotation_tencent
+index_realtime: pytdx -> easyquotation_sina -> easyquotation_tencent
+```
+
+Default K-line routing:
+
+```text
+minute_kline: pytdx only
+daily_kline: pytdx only
+kline: pytdx only
+```
+
+K-line APIs never fall back to easyquotation and never fabricate bars.
+Realtime APIs may fall back to `easyquotation_sina` or `easyquotation_tencent`
+after pytdx failures, but K-line APIs do not use easyquotation fallback.
+
+## Core Docs
+
+- [Quickstart](docs/QUICKSTART.md)
+- [Start here](docs/NEW_USER_START_HERE.md)
+- [API reference](docs/API_REFERENCE.md)
+- [K-line guide](docs/KLINE_GUIDE.md)
+- [Data sources](docs/DATA_SOURCES.md)
+- [Issue guide](docs/ISSUE_GUIDE.md)
+- [Return fields](docs/RETURN_FIELDS.md)
+- [CLI reference](docs/CLI_REFERENCE.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Error codes](docs/ERROR_CODES.md)
+- [Symbol rules](docs/SYMBOL_RULES.md)
+- [Units](docs/UNITS.md)
+- [Source policy](docs/SOURCE_POLICY.md)
+- [Audit trail](docs/AUDIT_TRAIL.md)
+- [Time and trading day](docs/TIME_AND_TRADING_DAY.md)
+- [Upstream license and risk](docs/UPSTREAM_LICENSE_AND_RISK.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Contributor adapter guide](docs/CONTRIBUTOR_ADAPTER_GUIDE.md)
+- [Maintainer checklist](docs/MAINTAINER_CHECKLIST.md)
+
+## Audit Trail
+
+Each routed call receives a `trace_id`. Audit records include:
+
+- `api_name`
+- `symbols`
+- `started_at`, `finished_at`, `duration_ms`
+- `selected_source`, `selected_source_level`
+- `attempts`
+- `fallback_chain`
+- `success`
+- `error_type`, `error_message`
+- `record_count`
+
+See [docs/AUDIT_TRAIL.md](docs/AUDIT_TRAIL.md).
+
+## Risk Notice
+
+This package does not produce market data. It calls upstream public Python
+libraries and their public interfaces. Upstream data may be delayed,
+unavailable, incomplete, or structurally changed. Users are responsible for
+validating data quality and following the terms of each upstream project.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).