xuefeng-agent: a local Chinese college-application advisor with a 24-province admissions database

The problem xuefeng-agent solves, and who it is actually for

Chinese gaokao volunteers fill dozens of parallel choices, and the ordering rule differs by province: Zhejiang allows 80 volunteer slots, Shandong 96, while provinces still on the old system submit 8 to 12 school choices. A family therefore has to match a rank, not a score, against two years of cut-off tables, then split the list into chong, wen and bao tiers. That is a spreadsheet job most families do badly.

xuefeng-agent targets exactly that job. It is a Python web server that serves a single chat page, extracts province, rank and subject preferences from free text, queries a local admissions database, optionally searches the web, and hands the combined context to a large language model. The README frames the audience as non-technical: there is a Windows batch launcher, a Mac shell script, and a separate beginner tutorial file. The secondary audience is developers who want to fork the retrieval pipeline.

The project is explicit that it is not a wrapper around a chatbot. The distinguishing asset is the bundled database: 24 provinces, roughly 420,000 rows, covering 2024 and 2025 official投档线, described as decompressing from 27.6 MB to 143 MB on first run.

How the retrieval pipeline turns a sentence into a chong/wen/bao list

The README documents a five-stage data flow. A user message such as a Zhejiang candidate with rank 10500 asking for computer science goes through extraction first: the model normalises colloquial input, so "一万三" becomes 13000 and "川籍" becomes Sichuan. Province, rank and intended majors come out as structured fields.

The second stage is a local database query keyed on those majors. The README states that saying "要计算机" returns only computer-related programmes and that medicine, law and accounting are filtered out. The third stage is a web search, using a Tavily key when one is configured and Baidu as a fallback. The fourth stage merges database rows and search results into a single context block for the LLM. The fifth stage produces the tiered answer, with every line tagged either [DB] or [联网] so the reader can see which source a number came from.

The README also documents a v3 behaviour switch. If the user fills in the bundled 自定义数据.xlsx with two years of scores and ranks, the agent analyses only that file and skips the system database, and the web search changes target from cut-off lines to campus conditions, dormitories, canteens and flagship majors. This is a sensible design: once a family has its own verified numbers, the bundled database is a liability rather than an asset. The README claims tolerance for malformed input, correcting 700分 to 700, 河南省 to 河南, and reversed score/rank pairs, though it does not describe the validation code behind those corrections.

Installing xuefeng-agent on Windows and running a first query

The README's Windows path assumes no command line. You install Python from python.org and tick Add to PATH, download the repository ZIP and unpack it, then double-click the launcher. The repository root contains 启动.bat for Windows and 启动.command for macOS, which matches the two documented flows.

1. 装 Python（python.org，勾选 Add to PATH）
2. 下载本项目 ZIP → 解压到桌面
3. 双击 启动.bat → 浏览器自动打开
4. 点右上角 API设置 → 填 DeepSeek Key → 保存测试
5. 打字提问

Those five lines are the README's Windows quick-start, reproduced as written. On macOS the documented path is to enter the folder in Terminal, start the server, then open the HTML entry file.

python3 server.py

After the server is running, the README says to open 打开我.html in the browser. Before any question works, you configure a model. The README describes a settings button in the top right of the page where you paste an API key and optionally change the base URL and model name. Any OpenAI-compatible endpoint is accepted, and the README lists DeepSeek as the first choice, with Tongyi Qianwen, Zhipu GLM and GPT-4o as alternatives.

The README states the key is stored in the browser, not on a server, and that no data is uploaded. A first real use is then a single sentence containing province, rank and major preference, for example the Zhejiang case in the README. The expected output is a three-tier list where each school line carries a score, a rank and a [DB] or [联网] tag.

Where xuefeng-agent breaks down or is the wrong tool

The database stops at 2024 and 2025. The README's own disclaimer says admission data changes every year and that the current-year figures published by each provincial examination authority and each school's admissions site take precedence. A family filling in 2026 choices is therefore working from historical cut-offs, and the agent has no documented mechanism for ingesting the new year's tables except the manual Excel route or the rebuild scripts.

Those rebuild scripts, rebuild_db.py and clean_data.py, are listed in the project structure but the README does not document their inputs, their command-line arguments or the schema they expect. Anyone wanting to extend coverage beyond the bundled 24 provinces has to read the source. That is a real gap for a project whose main claim is data breadth.

The README also does not document rollback, versioning of the database file, or any migration path when the schema changes between releases. The stated update procedure is to re-download the ZIP and overwrite the folder, which will discard any edits a user made locally unless they kept them elsewhere.

Finally, the interface is a browser chat page. The README says mobile is not supported and lists only Windows and Mac. A parent who wants to check a list on a phone during a school visit cannot use it as shipped. And because every answer is generated by a language model over retrieved rows, the disclaimer's warning about factual errors applies to the prose around the numbers, not just the numbers.

How xuefeng-agent differs from a general search or chatbot workflow

The obvious alternative is to skip the project and do the retrieval by hand: paste a province's cut-off table into a general chat model and ask for a tiered list. The difference is where the numbers come from. A general model has to recall cut-off figures from training data or from whatever you paste, and it has no way to tag a line as database-sourced. xuefeng-agent forces the numbers through a local query first and marks the provenance, which is the whole point of the [DB] tag.

A second alternative is the provincial examination authority's own volunteer-filling system, which is authoritative for the current year and is the only place a submission actually happens. xuefeng-agent does not submit anything and does not claim to. It is a planning aid that sits before that system, and the README's disclaimer points users back to it.

A third comparison is with the commercial AI volunteer-filling apps that the README alludes to when it says it is not a shell. Those typically run as hosted services. xuefeng-agent runs locally, which is why the README can state that keys and data stay on the machine. The trade-off is that you supply the model and pay per call. The README estimates a few tenths of a yuan for several hundred DeepSeek conversations, which is a claim about pricing, not a benchmark, and pricing changes.

Licence, maintenance and the cost of upgrading

The README states the project is AGPL v3 and describes it as strongly copyleft. The repository badge also says AGPL v3, while the repository metadata reports the licence as NOASSERTION, which usually means the licence file could not be matched automatically. Treat the README and the LICENSE file as the source of truth and read the file itself rather than the badge.

The README's own table is unusually blunt about consequences: personal study and non-commercial use are free, forking and republishing requires keeping the original attribution and repository address and staying on AGPLv3, and providing the tool as a network service requires publishing the complete source including modifications. Commercial or closed-source use is listed as forbidden, and the author reserves the right to grant separate commercial licences. If you plan to wrap this in a paid product, that is the clause to read first. This is a description of the project's stated terms, not legal advice.

On maintenance, the last push to the default branch was on 2026-06-27. There are no retrieved releases, so there is no tagged version to pin. Upgrading means downloading the ZIP again and overwriting the folder, per the README, and the database decompresses itself on first run. Budget for re-checking your own Excel file after each overwrite, because the README does not describe a merge step.

Editorial conclusion

Adopt xuefeng-agent if you are a Chinese high-school family or a developer who wants a self-hosted, browser-driven advisor over provincial cut-off data, and you are comfortable supplying your own model API key. Do not adopt it if you need an English-language tool, a mobile app, or a closed-source commercial product, because the AGPL v3 terms forbid that and the README states the author reserves separate commercial licensing. Before relying on it, open admission_clean.db.gz after first run and compare a handful of rows against the current-year tables published by the provincial examination authority, since the README itself says the database covers 2024 and 2025 only.

Frequently asked questions

Official sources

1. Issues
2. README
3. ziqihe10-droid/xuefeng-agent on GitHub