Jin Ce Zhi Suan: an A-share backtesting tool organised as a Tang dynasty bureaucracy

Why the whole pipeline is named after a Tang dynasty bureaucracy

The organising idea is borrowed wholesale from the three departments and six ministries system of the Tang dynasty, and it drives both the module layout and the runtime flow. Three offices sit on the main decision path. The Crown Prince office handles data validation and distribution before anything else runs. The Secretariat generates the strategy signals. The Department of State Affairs reviews those signals and can block them. The Department of State Administration handles execution scheduling and capital settlement once a signal survives review.

Six functional ministries sit underneath. The Ministry of Personnel registers strategies and manages their lifecycle, so a strategy has a defined state rather than being a file someone edits. The Ministry of Revenue handles cash, cost and net value accounting. The Ministry of Rites produces performance reports and strategy rankings. The Ministry of War does matching and execution. The Ministry of Justice records violations and risk events, and it is also the destination for any signal the review office rejects. The Ministry of Works cleans market data and computes indicators.

The README's own flowchart makes the review gate explicit:

flowchart LR
  A[行情数据源] --> B[太子院 CrownPrince]
  B --> C[中书省 ZhongshuSheng]
  C --> D[门下省 MenxiaSheng]
  D -->|通过| E[尚书省 ShangshuSheng]
  D -->|否决| F[刑部 XingBuJustice]
  E --> G[兵部 BingBuWar]
  E --> H[户部 HuBuRevenue]
  E --> I[礼部 LiBuRites]

Two paths leave the review office, and that is the whole point of the design. A passing signal goes on to execution, settlement and reporting; a rejected one is routed to the justice ministry as a recorded event. Most backtesting frameworks treat risk control as a threshold you set and forget. Here it is a separate stage with its own veto, which also means the rejection history is a dataset rather than a log line.

Getting it running: pip install, then python server.py

The README documents a three-minute path. Install Python 3.8 or newer, ideally in a virtual environment, then install the dependencies from the root of the project:

pip install -r requirements.txt

If you want to pin the interpreter explicitly, the README gives the module form of the same command. Then you start the server:

python server.py

One detail worth knowing before you run it: the README states that startup automatically checks the dependencies declared in `requirements.txt` and attempts to install any that are missing, and that this can make the first launch noticeably slower. A process that installs packages on your behalf at startup is a real design decision, and it means the first run writes to your Python environment without asking.

The requirements file is where the data source story becomes concrete. Beyond the usual analysis stack of pandas, numpy, tqdm, matplotlib, mplfinance, seaborn and Pillow, it pulls in five separate market data clients: AkShare, Tushare, pytdx, mootdx, baostock and jqdatasdk. Storage is covered three ways, with pymysql, psycopg2-binary and duckdb, and the duckdb pin is the only version constraint in the file, at 1.5.2 up to but not including 1.6. The web layer is FastAPI with uvicorn, pydantic, starlette and sse-starlette for server-sent events, plus pystray, which points at a system tray icon and explains the `desktop_launcher.py` and `desktop.spec` files at the repository root.

The README also lists optional one-click launchers, a Windows batch file and a shell script for Linux and macOS, and a port override given as `python server.py --prot 8001`. That flag is spelled `prot` in the documentation, not `port`, which is the kind of detail that costs a reader an hour if you assume it is a typo and edit the source.

Keys go in a private file, and the priority order is documented

Configuration is split across three files, and the split is the most security-relevant decision in the project. `config.json` holds the default settings and is committed. `config.private.json.example` and `custom_strategies.private.json.example` are templates for the two files you are expected to create yourself and keep out of version control.

The README is explicit that secrets must never go into `config.json`, and gives the shape of the private file:

{
  "data_provider": {
    "tushare_token": "你的token",
    "default_api_key": "你的api_key",
    "llm_api_key": "你的llm_key",
    "strategy_llm_api_key": "你的strategy_llm_key"
  }
}

Four credentials, and two of them are for language models rather than market data. The resolution order is given as environment variables first, then `config.private.json` or whatever file the `private_config_path` setting points at, then `config.json`. Putting environment variables at the top of that list is the right call for deployment, since it is the only layer that does not require editing a file on disk.

The committed tree is a reminder that not everything stayed tidy. Alongside the expected `src/`, `data/`, `docs/`, `scripts/` and `tests/` directories, the root carries `debug_headers.txt`, `debug_task_keys.json`, `debug_task_keys.txt`, `server_stdout.log`, `import_profile.txt` and `graphify-build.log`, plus a `graphify-out/` directory. There is also a `.claude_dashboard_script_check.js` file and a `.trae/` directory, which are tooling configuration rather than application code. Debug artefacts left in the repository root are harmless to a local user and a genuine problem if you fork the project, since anything committed there is committed for your fork too.

Natural-language stock screening that produces structured conditions

The feature that distinguishes this from a general backtester is the AI condition screening tool. You describe a screening idea in Chinese, a large language model parses it, and the output is split into two parts: structured filtering conditions that narrow a universe to candidates, and separate buy and sell execution rules that the backtest engine then follows. The README's own example is a three-part description: a limit-up within five days, volume contracting to less than half afterwards, and RSI sitting in an oversold range.

The two-part split matters. The screener and the executor are different jobs, and keeping them separate means the model is being asked to translate a description rather than to decide a trade. The README frames the result as going from an idea to a backtestable strategy in one step, which is a fair description of the workflow even though the model's output still has to survive the risk review stage before anything executes.

The dependency list supports that this uses a hosted model service rather than a local one. `zhipuai` appears in the requirements file, and two of the four private credentials are LLM keys, one for the screening tool and one described as the strategy LLM key. So the tool that decides your screening conditions needs network access to a model provider, and the keys live in the same file as your market data token.

Beyond screening, the README describes a strategy evolution board reached from the operations workbench, where generation, evaluation and iteration run as a loop. It also describes formula and sector-pool tooling: TDX formula conversion, BLK file parsing and batch watch boards. Those are all TongdaXin, the Chinese desktop trading platform, conventions, which tells you the project is aimed at people who arrived from that ecosystem.

A licence that is not a standard open source licence

The project carries a LICENSE file at the repository root, but the terms inside it are not one of the standard licences. The README describes the model as free for personal non-commercial use and requiring authorisation for anything commercial, with a written commercial licence contact address.

The free tier covers personal study, academic research and local personal use where you are not providing a commercial service to others. The paid side lists selling the project or a derivative, hosting it as a service or SaaS, repackaging it for resale or distribution or agency work, and any direct or indirect revenue-generating deployment. Where a commercial agreement and the repository terms conflict, the README says the agreement wins, and disputes are governed by PRC law.

The disclaimer section is unusually long and unusually specific. It states that the tool provides historical data display, statistics, backtesting and code debugging for learning purposes, that it is not stock-recommendation software or investment consulting software, that historical backtest results do not predict future returns, and that the developer holds no securities investment consulting qualification. It then enumerates third parties that might use the software under the project's name, naming personal users, institutions, private investor communities, teahouses and clubs, inns, hotels and rental properties, and dealers and channel partners, and disclaims any liability for what they do. A separate line exempts the developer from claims about software stability, continuity and security.

For an engineer evaluating this, the practical reading is that the code is readable and the grant is narrow. If your use is research or a personal tool, the terms are clear. If you plan to run it for other people or charge for it, that is a commercial conversation rather than an open source decision, and the README gives an address for it.

Release cadence, the community layer, and what the docs leave out

The release history shows a project shipping steadily through 2026. V1.4.0 landed on 2026-04-26, V1.5.0 on 2026-05-17, and V1.6.1 on 2026-06-27 with a note that the AI condition screening received a full upgrade. The last push was dated 2026-07-20 and the repository is not archived.

Alongside the code there is a paid community layer. The README describes a paid group offering installation and deployment tutorials, an explanation of the three-department and six-ministry architecture with source walkthroughs, and ongoing question answering and bug triage, with a limited coupon offer for new members. It positions itself as technical study and tool learning, explicitly not stock recommendation, and names its audience as quant hobbyists, Python developers and people building their own research tooling. That layer is the honest commercial counterpart to the licence terms: the software is free for study, and the paid part is the guided path through it.

What the README does not cover is as notable. There is no API reference, no database schema, no deployment guidance beyond the launcher scripts, and no explanation of the strategy interface that custom strategies must implement. The `custom_strategies.private.json.example` file implies a JSON schema for user strategies, and the directory listing shows `src/strategy_intent/` for parsing and generating strategy intent, but the contract between a custom strategy and the backtest engine is left to the source. The repository does have a `docs/` directory and a `tests/` directory, so some of that documentation likely exists there rather than on the README page.

For a first run, the README's suggested pacing is the most useful thing on the page: get one strategy passing end to end, then add portfolios and batch runs, and only then touch strategy evolution. That order matches the architecture, since the review office and the justice ministry only produce meaningful records once there is a real flow running through them.

Editorial conclusion

The unusual part of this project is not the data source count but the review gate. A signal generated by the strategy layer has to pass a separate risk layer that can veto it before any order reaches the execution and settlement layer, and the README is explicit that the risk office holds a single-vote block covering stop losses, drawdown and position limits. That structure is worth reading in the source tree even if you never run the tool, because `src/ministries/` maps one directory per named function and makes the flow easy to audit. If you do run it, the honest sequence the README recommends is one stock, one strategy, one backtest, and only then the portfolio, batch and evolution boards. The two things to settle before anything else are the licence, which requires written commercial authorisation for hosting or resale, and the private key file, which the README keeps deliberately outside version control.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. ScottZt/jin-ce-zhi-suan on GitHub