tikuAdapter: one search endpoint over many question bank APIs

The problem with eight providers and eight response formats

tikuAdapter is a question bank adapter that converts different question bank interfaces into one unified standard format, and the README is clear that it is intended to become a specification for question bank interfaces rather than just another client.

The use case it starts from is concrete. There are many question bank interfaces on the market, and if you want to use one provider's bank inside an answer script, you would otherwise write the integration yourself, with that provider's request shape, its token scheme and its answer format.

The supported input sources are listed with a ranking rule attached: free is preferred over paid. icodef and buguake are marked free, the latter reached through the Baidu easylearn course page. wanneng, Tikuhai, aidian, enncy and lemon are paid, each with its own site and its own token. On top of those there is a custom question bank option, configured in the configs directory, which is the escape hatch for a provider the project does not know about.

The audience is therefore narrow and easy to identify: students and developers building automatic answering scripts against these banks, and the tools around them. The repository topics are api, search-question and tiku, and the primary language is Go with the MIT licence.

The service also does more than search. It has a web interface reachable on the same port, where the banks can be added, edited and deleted and where the call log is recorded, and it keeps a local SQLite database so that a document can be parsed into a local bank. The last of those is listed with an unchecked box in the README, which means the Word document parsing is announced but not finished, and that is worth knowing before you plan around it.

One request shape and one answer shape

The API is a single POST endpoint, /adapter-service/search, and the request body carries the question, the options and the question type.

The type field is an integer with a small set of meanings: 0 for single choice, 1 for multiple choice, 2 for fill in the blank, 3 for true or false and 4 for question and answer. Sending the options along with the question matters, because the providers that answer with a letter need to know what the letters refer to.

The response is the part that justifies the whole project. It comes back with the platform index, the question as it was matched, the options, the type, and an answer object with several views of the same answer: the answer keys as letters, the keys joined into one string, the zero-based indexes of the correct options, the answer text for each index, the best answers as plain text, and the all-answer field which holds the answer both as plain text and as the option labels with their letters prefixed.

That last field exists because providers disagree about how they present the answer. Some return the letter, some return the text, some return the text with the letter attached. A caller that has to normalise that itself is doing the adapter's job in every script that uses it, and the all-answer field means a client can pick the presentation it needs without re-parsing.

The question type is echoed back too, which lets a client check that the provider it hit understood the question the same way it did.

Tokens per provider, and a URL that selects them

The provider selection happens in the URL rather than the body, and the parameter is called use.

If you leave use out, the service uses all the free banks. That default is the sensible one, and it is also the reason the free providers are ranked first in the list. When you do name them, the parameter takes a comma separated list, so a request against the paid wanneng bank and the free icodef bank looks like this:

http://localhost:8060/adapter-service/search?use=wanneng,icodef&icodefToken=UafYcHViJMGzSVNh

Each provider then has its own token parameter, and the README lists them with the value format and where to obtain it: wannengToken is a ten character value, icodefToken and enncyToken and aidianYToken and lemonToken are longer strings, and Tikuhai has its own token parameter too. Each row of the table also links to the site where the token comes from, which is a fair sign of how the arrangement works in practice.

The design consequence is that tokens travel in the query string rather than in a header or a body field. That is convenient for a script that only ever makes one kind of request, and it is also why the tokens should be treated as credentials in your logs, since a URL that contains a token is a URL that ends up in a log file.

For a paid bank, the token is the paid access, so the cost model of the service follows the cost model of the provider you point it at. The adapter does not resell access to any of them.

Deployment as a binary or as a container

There are two documented ways to run it, and the container route is the more interesting one.

The first is to download the executable from the GitHub releases, unzip it and run it. The releases are versioned as 0.1.0-beta tags, with the newest visible ones at beta.39, beta.40 and beta.41, the last two both published on the same day, 2026-09-20.

The second is Docker, and the README gives the build command:

docker build -t tiku-adapter .

and the run command:

docker run -d \
  --name tiku-adapter \
  -p 8060:8060 \
  -v ./data:/app/data \
  tiku-adapter

The volume mount is the part that matters. The data directory holds the SQLite database, and without the mount the database lives inside the container and disappears when the container is replaced.

The README then recommends the fuller form, which also mounts the configuration file:

docker run -d \
  --name tiku-adapter \
  -p 8060:8060 \
  -v ./data:/app/data \
  -v ./config.yaml:/app/config.yaml \
  tiku-adapter

The configuration file is where the database path is set, in the database section of config.yaml, and the default is tiku.db, with the README suggesting data/tiku.db for Docker deployments so that the path lines up with the mounted volume. That is a small detail that saves the situation where the container starts with an empty database because the file was written somewhere else.

There is more in the deployment document at deploy/README.md, and the configuration directory holds the per-provider settings including the custom question bank definitions and the rate limiting configuration.

A web interface on the same port, with default credentials

Opening http://localhost:8060 in a browser gives you the web version of the service, and the README describes what it does: creating, editing, deleting and querying the question banks, plus log records of what has been called.

It is the same port and the same process as the API, which is convenient for a small deployment and means one thing to run. The management functions are also the reason the service can hold provider configuration at all, since the tokens and the custom bank definitions need somewhere to be edited.

The default account is admin and the default password is 123456, and the README states that in plain text. That is a development convenience, and it is the first thing to change before the port is reachable by anything other than your own machine, since the interface can read and write the bank configuration and the tokens in it.

The web view is not a separate application. The repository has a web/ directory and a buildweb.sh script at the root, alongside the Go code in cmd/, internal/, pkg/ and sql/. The Go dependencies explain the stack: gin for the HTTP layer, gorm with its mysql driver and the gorm code generator for the database, glebarez/sqlite for the local database, viper for configuration, resty as the HTTP client for the upstream providers, gjson for parsing their responses, excelize for spreadsheets, a cron library for scheduled work, and an Elasticsearch client and an Aliyun OSS SDK for the pieces that talk to other stores.

The Go version requirement in go.mod is 1.21, and the module path is github.com/itihey/tikuAdapter.

Adding a provider, and the boundaries of the project

The contribution guide is short and specific, and it tells you exactly where a new provider goes.

You can look at internal/search/wanneng.go as the reference and implement the internal/search/search.go interface, and you write internal/search/search_test.go to test your provider. The pattern is one file per provider behind one interface, with a test beside it, which is the shape you would expect and which makes a new bank a small pull request rather than a redesign.

The project also asks for issues: if you find a question bank interface, raise an issue and the maintainer will add it.

There are limits worth stating. This is a search adapter for question banks, aimed at an answer-script ecosystem, and it is a 0.1.0 beta line with a fast release cadence rather than a stable API. The Word document parsing into a local bank is still an unchecked item in the feature list, so the local database exists but the document path into it is not finished. The free providers are rate limited by their own operators, which is why the README offers a rate limiting configuration and notes that personal use usually does not need it. And most of the providers are paid, with tokens that have to be bought and renewed.

The alternative is to call the providers directly from your own script. The difference in approach is that you then handle each provider's request format, each provider's token parameter and each provider's way of presenting the answer, and you keep that code in every client you write. The adapter moves that translation into one place and normalises the answer into a shape you can rely on, at the cost of a service to run and tokens to manage inside it.

Editorial conclusion

tikuAdapter suits somebody building a Chinese answer script or quiz tool who wants to try several question bank providers behind one call instead of writing a client per provider, and who is comfortable with a project on a 0.1.0 beta line. It does not suit a production service exposed to the internet, because the web interface ships with the default account admin and the password 123456 and the README does not document changing them, and it does not suit you if you need the Word document parsing, which the README still lists as unchecked. Check three things before you deploy it: that you have tokens for the providers you intend to use, since most of them are paid and each has its own token parameter, that the free providers are not the only ones you depend on, since the README offers a rate limiting configuration for them, and that you change the default web credentials before putting port 8060 anywhere other than your own machine.

Frequently asked questions

Official sources

1. DokiDoki1103/tikuAdapter on GitHub
2. Issues
3. License: MIT
4. README
5. Releases