DEV Community: 张洲诚（Zack.ZHANG）

The Explicit Cache Was Cheaper on Paper. Then I Changed One Question.

张洲诚（Zack.ZHANG） — Fri, 04 Sep 2026 10:23:09 +0000

Building a Knowledge Base from Scratch, EP07. The paradigm arc continues, and the bill from EP06 finally gets audited.

Where EP06 left off

I ended EP06 with a confession. The "compile once, break even after about 6 questions" math only works if the cache keeps hitting. When it doesn't, the compiled side costs 44% more per question than retrieval. And I had no idea when the cache expired. That's entirely up to the server.

There was a loose thread too. Bailian offers an explicit cache. You mark the knowledge-base prefix yourself, pay ¥15 per million tokens to create it, ¥1 on a hit. On paper that hit price beats the implicit one, ¥1.5. But the rules are completely different, and I wanted to know how.

So this episode runs both caches against each other. Same assets as EP06: the compiled artifact (a 7,929-token prompt prefix), qwen3.8-max, the same system message, the same four questions. Eleven paid calls, ¥0.93 total.

The headline finding first: the explicit cache doesn't hit the way I assumed. It doesn't match on prefix. That changes the final answer.

The price table, including a TTL hiding in a type name

bl model list --model qwen3.8-max needs no authentication. Prices pulled on the spot:

Tier	Price	Relative to input
Input	¥12 / M	100%
Output	¥36 / M	n/a
Implicit hit	¥1.5 / M	12.5%
Explicit creation	¥15 / M	125%
Explicit hit	¥1 / M	8.33%

One detail deserves its own paragraph. The billing type name for explicit creation is input_token_cache_creation_5m. The 5-minute TTL is right there in the field name. Didn't have to guess from documentation; the price list confessed on its own.

That 5 minutes comes back repeatedly. It's one of the explicit cache's structural weaknesses.

Was last episode's cache still alive

The first test group answers EP06's open question: how long does the implicit cache actually live?

Method: rerun the exact message assembly from EP06. Same artifact as the user message, question appended, four different questions, controlled intervals.

Call	Time	Since last hit	Hit tokens	Cost
A1	13:25:39	two days	0	¥0.1075
A2	13:25:59	20 seconds	7,168	¥0.0345
A3	13:35:31	9m 32s	7,168	¥0.0285
A4	13:49:30	13m 59s	7,168	¥0.0419

Three findings.

After two days, the cache was gone. A1's 7,929 input tokens billed at full price. EP06's warning about low-frequency usage getting a cold start every time now has its own data.

Twenty seconds apart, it hit, and the hit count, 7,168, matches EP06's five calls digit for digit. The two episodes' data line up.

A3 and A4 were the surprise. A hit 9.5 minutes later, another 14 minutes after that. By A4, the cache had survived 23.5 minutes since first being hit. The implicit cache lives at least 14 minutes, dies within two days, and the exact boundary in between is opaque. Far longer than my intuition. I'd assumed an automatic cache would last minutes at best.

The CLI has no cache command, but it has one pathway

I grepped bailian-cli's entire reference documentation for "cache" and "缓存". Zero hits. No dedicated cache command.

But the official API's explicit cache works through structure markers inside the messages array, and bl text chat has a --messages-file flag that forwards whatever structure you give it. The pathway already exists. Pass it through.

The implicit group is the old shape, user as a single string:

[
 {"role": "system", "content": "You are the customer service assistant for Nuannu Home Furnishing."},
 {"role": "user", "content": "(full compiled artifact)\n\n---\nThe above is the company knowledge base. User question: How do I submit reimbursement invoices?"}
]

The explicit group splits user into an array and hangs cache_control on the knowledge-base block:

[
 {"role": "system", "content": "You are the customer service assistant for Nuannu Home Furnishing."},
 {"role": "user", "content": [
   {"type": "text", "text": "(full compiled artifact)\n\n---\nThe above is the company knowledge base.",
    "cache_control": {"type": "ephemeral"}},
   {"type": "text", "text": "User question: How do I submit reimbursement invoices?"}
 ]}
]

Both expand to identical text, same model, same parameters. The only difference is the marker. Single variable.

Whether the pass-through worked can't be left to vibes. I fixed the criterion in advance: the explicit group's usage must contain fields the implicit group never showed. A change in cached_tokens alone doesn't count; that could just be an implicit hit.

B0, the explicit group's first call, returned:

"prompt_tokens_details": {
  "cache_creation": {"ephemeral_5m_input_tokens": 7923},
  "cache_creation_input_tokens": 7923,
  "cache_type": "ephemeral",
  "cached_tokens": 0
}

Three new fields, all present. ephemeral_5m_input_tokens even matches the billing type name from the price list. Pass-through confirmed: 7,923 tokens went through explicit creation. The answer itself was normal, 291 characters, correctly based on the 2026 reimbursement policy.

And a bonus observation running the other direction: B0 came 31 seconds after A4, which had just hit the implicit cache for 7,168. Yet B0's cached_tokens was 0. Hang the marker, and you're no longer an implicit player.

Change the question, pay for creation again

Next came what I expected to be the main event: B0 creates, B1 asks a different question immediately after, hits the knowledge prefix, pays the ¥1 hit price.

That's not what happened.

Call	Question	Interval	Created	Cost
B0	q1 reimbursement	n/a	7,923	¥0.1305
B1	q2 free shipping	12 seconds	7,929	¥0.1365
B2	q4 Xinjiang sofa	15 seconds	7,936	¥0.1418

B1 came 12 seconds after B0, sharing a 7,900-token common prefix. No hit. Full-price creation all over again.

If the explicit cache matched on prefix, B1 would have hit the knowledge block B0 created. It didn't. For "one fixed knowledge prefix plus ever-changing questions," the most standard shape of knowledge-base Q&A, the explicit cache pays the 125% creation price every single time.

How hits are actually judged: a nine-second controlled experiment

Three steps, each 9 seconds apart.

B3: byte-identical messages to B0, sent 8 minutes later. B0's cache was created at 13:50:01. The official TTL is 5 minutes. B3 went out at 13:58:14, 8m 13s after creation. Result: re-created 7,923, no hit. The 5-minute TTL is real. When it expires, it's gone, and the 125% creation premium evaporates with it.

B4: byte-identical to B3 (same question), sent 9 seconds later. Hit. 7,923 tokens, zero creation, ¥0.0202 total. The cheapest single call of the entire episode, 29% below even the implicit group's best.

B5: differs from B4 only in the question text, sent 9 seconds later. No hit. Re-created 7,926.

Five data points, all pointing one way:

Bailian's explicit cache judges hits by "entire request identical," not "common prefix." The whole messages array must match byte for byte. Differ by one question and you miss.

This is a different semantic from Anthropic's prefix caching, where everything before the marker counts as long as the prefix matches. The standard pattern there is exactly "fixed knowledge base, varying questions." Port that intuition over and every question pays 125%, six times the implicit steady state.

The explicit cache's niche narrows to one thing: repeating an identical request. Multiple agents running the same prompt in parallel, batch retries, evaluation-set reruns. Outside those, it can't help.

Two channels, two separate ledgers

The experiment matrix planted a cross-check: after explicit caches had been created, send an unmarked request in the implicit style and see whether the two channels connect.

D1 ran 9 seconds after B0 and B1, two explicit creations. Implicit assembly, question q3. It hit, for 7,168, the implicit count, not the 7,923 that had just been explicitly created.

That number is itself the evidence. If the channels shared cache, D1 would have picked up the 7,923 entry, which covers more of the prompt. What it actually got was the implicit ledger's 1,024-aligned 7,168.

Add B0's finding that marked requests can't ride the implicit cache, and all four directions are tested: explicit doesn't eat implicit, implicit doesn't eat explicit, explicit creation doesn't break the implicit chain, and the two channels keep entirely separate books.

Practical corollary: running explicit-cache experiments leaves the implicit cache untouched. The two workloads can coexist without interfering.

The quirk in implicit hits: 1,024-token alignment

One more pattern in the A-group data, easy to miss at first.

A2, A3, A4 and D1 all hit for exactly 7,168. Their prompt totals ranged from 7,929 to 7,942 depending on question length. The hit count never moved.

7,168 = 7 × 1,024. The implicit cache stores in 1,024-token blocks, and the tail of the common prefix that doesn't fill a block never enters the cache. Every call leaves about 767 tokens billed at full price, forever ineligible for the discount.

Priced out properly, the implicit discount isn't as deep as advertised. The effective input rate is ¥2.515 per million, 21% of list, not the headline 12.5%. That percentage only holds for the tokens that actually make it into cache.

The explicit cache has no such truncation. Its created and hit counts are 7,923, covering 99.9% of the prompt. Explicit hits are not only cheaper per token (¥1 vs ¥1.5), they cover more of the prompt. A genuine hidden advantage, locked away behind "change the question and you miss."

The cost account: when does explicit pay off

Four steady states side by side, effective input rates:

Steady state	Effective input price	Relative	Source
Full-price cold start	¥12.00 / M	100%	A1
Implicit steady state	¥2.515 / M	21.0%	A2
Explicit creation	¥15.00 / M	125%	B0-B5
Explicit hit	¥1.008 / M	8.4%	B4

First, the standard shape of knowledge-base Q&A: one prefix, five different questions in a row. Implicit total ¥0.1750, explicit total ¥0.5946. That's 3.4×, and per-question steady state is worse: 0.1189 ÷ 0.0200 = 5.96×. In this scenario explicit is pure downside.

Now explicit's sweet spot: the same messages resent verbatim, within 5 minutes.

Repeats	Implicit total	Explicit total	Gap
3	¥0.1349	¥0.1349	break even
5	¥0.1747	¥0.1509	explicit saves 13.6%
10	¥0.2741	¥0.1909	explicit saves 30.4%

Ask the identical question 3 times within 5 minutes and explicit starts winning; the more repeats, the more it saves, up to 60% at the limit. Change the question even once and it snaps back to 6× more expensive per call. And the TTL doesn't forgive: if no hit comes within 5 minutes, the 125% creation premium evaporates entirely.

Wrapping up: how to place this compiled artifact

Eleven calls done, and EP06's question gets a straight answer.

Your workload	How to place it
Customer-service Q&A: fixed prefix, ever-changing questions	Implicit. Configure nothing.
Identical-request reruns: eval sets, batch retries, parallel agents on one prompt	Explicit marker, breaks even at call 3
Low-frequency, a few queries a day	Neither cache saves you; consider going back to retrieval
Getting more implicit hits	Control the cadence: follow-ups within 14 minutes land

My own artifact lands in row one: configure nothing, rely on implicit. Customer-service questions always vary; the explicit 125% premium can't be dodged there. The one thing worth doing is pacing: keep questions inside the expiry boundary so that 7,168-token prefix stays warm.

A note for later: when batch evaluations or multi-agent runs show up, come back and hang the marker. That's the one arena where explicit wins.

What's next

One problem in the paradigms arc is still untouched. Everything through EP06 shared a default: everyone can read the whole library. Real companies don't work that way. Reimbursement policies are for finance and travelers; customer data belongs to the service team only. Compilation kneads the whole library into one artifact, and permissions are the first gate it has to survive. Next episode: cut the same library into two permission views and see what compiled artifacts, retrieval-side metadata filtering, and agent prompts can each defend.

Everything here was measured with Model Studio's CLI (bl). Full usage figures, reasoning traces and compiled artifacts from all 11 calls are archived in the project repo. Command signatures may shift between versions, so check the official docs. API keys are free to obtain, with a free tier for new accounts.

It Found a Contradiction I Didn't Plant. Then It Answered as if Nothing Was Wrong.

张洲诚（Zack.ZHANG） — Thu, 03 Sep 2026 10:20:21 +0000

Building a Knowledge Base from Scratch, EP06. The paradigm arc starts here.

Where EP05 left off

My library holds two shipping documents. One says free shipping over ¥59, the other says over ¥99. Nothing anywhere says which is current. Both came back in the same retrieval call, the ¥59 one actually scoring higher at 0.6557 to 0.5755, and the agent quietly picked one. It never mentioned a second number existed.

Version conflicts it handled fine, because the 2026 expense policy contains the sentence "the 2023 edition is hereby superseded." Metadata sitting in the corpus, readable by anyone with context. The threshold documents carry nothing, so there was nothing to read.

Five episodes of retrieval hit that wall. This episode changes the paradigm instead of the plumbing: have the model read the entire library once, write it up as structured knowledge pages, then answer from those pages with no retrieval at all.

Karpathy's LLM Wiki gist frames the two as interpreter versus compiler. RAG interprets your library at question time, every time. LLM Wiki compiles once and then executes. Three directories (raw/ read-only sources, wiki/ pages with [[wikilink]] cross-references, schema/ conventions), three operations (Ingest, Query, Lint).

One thing to flag before anything else. That gist carries its own disclaimer: "This document is intentionally abstract. It describes the idea, not a specific implementation." So the secondhand write-ups claiming "Karpathy's research shows accuracy falls off a cliff past a certain document count" are straightforwardly false. There is no experiment in that document. Somebody attached fabricated numbers to a design note and the numbers spread.

This episode runs the idea against a real library: zj0knmrbye from EP02, eight documents, 27 chunks, with the dirty data I planted in EP03 still in place. Not a single character changed.

The command surface

One entry point, bl text chat with --messages-file:

bl text chat --model qwen3.8-max --messages-file messages.json \
  --max-tokens 8000 --enable-thinking --thinking-budget 3000 --output json

messages.json is a plain messages array, one system turn and one user turn carrying the full text of all eight documents merged, 8,811 characters.

Two practical notes if you're on Windows. Put non-ASCII system prompts inside the messages file, never on the command line, because PowerShell mangles the encoding on the way through. And write results to a UTF-8 file instead of printing them: one emoji in the output is enough to make print raise UnicodeEncodeError against the console's GBK codec.

Thinking stays on deliberately. The EP05 agent app runs with thinking enabled, so compiling with it off would have made the comparison meaningless.

The messy spreadsheet got the least dignified treatment available. openpyxl dumps every cell to text, and the empty columns left by merged cells, the misaligned headers and the notes stranded on a second worksheet all survive verbatim:

Shipping zone |  | Lead time and fee

Why I ran two nearly identical compiles

Karpathy's Ingest step includes an instruction to "flag contradictions between new and existing content." If I copy that in and the model duly flags the ¥59/¥99 conflict, the result tells me nothing. I can't separate "giving the model global visibility worked" from "telling the model to hunt for contradictions worked." The EP05 agent's prompt contained nothing like that instruction.

So, two runs differing by one line:

A1a, neutral. Build topic pages, merge same-topic content, produce an index.md, cross-link with [[page name]], cite the source document for every fact, add nothing the documents don't state. The words "contradiction," "conflict," "59" and "99" appear nowhere.
A1b, Karpathy's version. Same text plus one line: "5. While ingesting, flag contradictions between new and existing content."

Reading rule fixed in advance: if A1a finds the conflict, credit goes to global visibility. If only A1b finds it, credit goes to the prompt and the conclusion shrinks accordingly.

Measured usage from --output json:

Run	Input	Output	of which reasoning	Wall time	Cost
A1a neutral	5,905	9,594	1,725	179.7s	¥0.4162 (~$0.059)
A1b Karpathy	5,918	8,757	2,100	175.8s	¥0.3863 (~$0.054)

Pricing from bl model list --model qwen3.8-max, which needs no authentication: ¥12 per million input, ¥36 per million output. USD figures use 7.1 CNY/USD on the run date and are there for scale, not accounting. finish_reason was stop on both, so the coverage gaps below are choices, not truncation.

Finding 1: the neutral run built a conflict table on its own

A1a produced a section I never asked for:

## Free shipping threshold and fees

> ⚠️ Document conflict: 01-shipping-and-logistics and 13-shipping-fee-table-clean
>   disagree on the free shipping threshold and the fee amount.
>   Treat the amount shown at checkout as authoritative.

| Item | 01-shipping-and-logistics | 13-clean / 14-messy |
| Standard zone threshold | ¥59 | ¥99 |
| Fee below threshold | ¥10 | ¥8 |
| Remote zone threshold | free over ¥129 | excluded from promo, ¥15 surcharge |

Same two documents as last episode, same conflict, and the retrieval side picked one silently. Nobody told this run to look for contradictions. It put both versions side by side and volunteered a resolution, defer to checkout, that it lifted from a throwaway line buried in the messy spreadsheet.

By the rule I fixed in advance, the conclusion stands: what did the work was global visibility, not the instruction.

A1b flagged more explicitly, three conflicts under a 🔴 marker with source columns. It also declined a fake one: document 02 gives a one-year appliance warranty, document 15 lists warranty periods for wood furniture, hardware and mattresses and says nothing about appliances. Its note reads "different product categories; no direct conflict, but the information is complementary." Refusing to pad the count tells you more than an extra flag would.

Finding 2: the second conflict wasn't on my list

When I seeded dirty data in EP03 I designed exactly two conflicts: the shipping threshold and the policy version pair. The third one A1b found by itself, in how the two documents define remote zones:

01-shipping-and-logistics: Xinjiang, Tibet, Inner Mongolia, Qinghai, Ningxia, Hainan
13-shipping-fee-table-clean: Xinjiang, Tibet, Gansu, Qinghai, Inner Mongolia, Ningxia

One list has Hainan and no Gansu. The other has Gansu and no Hainan. I checked the sources. The model was right.

I built this library and ran five episodes of experiments against it. That mismatch sat there the whole time and I never noticed. This carries more weight than finding the traps I set on purpose: with a planted trap you can reasonably suspect I hinted at it somewhere. I couldn't have hinted at this one.

The academic name is inter-context conflict, one of three categories in the EMNLP 2024 survey Knowledge Conflicts for LLMs. Retrieval rarely surfaces this class, because two chunks that disagree usually don't get read together and nothing in the pipeline is responsible for comparing them.

Finding 3: the sharpest objection didn't reproduce

The strongest critique I found is about overwrite behavior: during compilation the new revision silently replaces the old one, even though somebody may still be running the old value. The example is a hardware datasheet where Rev 6 specifies 100nF and Rev 7 changes it to 220nF, so the engineer holding a Rev 6 board can no longer look up the value that applies to them.

My two expense policies are structurally the same case. Neither run overwrote anything. A1a kept both editions as separate index entries, gave each a standalone page with its full allowances, put a banner on the old one (⚠️ Superseded. Effective 2023-04-01, replaced 2026-02-01. Historical reference only.), and [[link]]ed the two pages to each other.

The boundary matters though: both documents state their effective dates and supersession relationship in their own body text. The metadata was there to read. EP05's line about a decision layer rescuing conflicts that carry evidence holds in this paradigm too.

Finding 4: what verification caught

Fabricated values, orphaned pages and dropped information can't be assessed by reading output and nodding. I scripted it: pull every numeric token out of the artifact and look for it in the source corpus, then check every [[link]] against the set of headings.

Check	A1a neutral	A1b Karpathy	Objection tested
Artifact size	12,089 chars / 578 lines	10,089 chars / 433 lines	reference
Numbers traced to source	73 distinct, 0 unfound	71 distinct, 0 unfound	fabrication: didn't occur
`[[link]]` integrity	42 links / 11 targets, 0 broken	7 links / 7 targets, 0 broken	orphans: didn't occur
18 key facts spot-checked	18/18	17/18	dropped info: partly occurred

Both runs lost the same thing: the timestamp on the messy spreadsheet's footer, "subject to change, latest support response governs (updated 2024.6)."

That is not decoration. Document 01, the other side of the threshold conflict, carries no date at all. So "which of these two is more recent" has exactly one clue in the entire library, and compilation dropped it. What compilation loses is precisely the metadata arbitration depends on.

A1b dropped three more things A1a kept, including the manual's own note that "version v3.1 (March 2026) is superseded." Sit with that one: A1b flagged the expense policy's version relationship more explicitly and simultaneously lost the manual's. It also came in 2,000 characters shorter with [[link]] count down from 42 to 7. Attention is zero-sum inside a fixed output budget. Copying Karpathy's instruction in isn't a free upgrade, it's a trade.

The cold water: the artifact says "conflict," the answer doesn't

A compiled artifact isn't for human reading, it's context for the model. So the real test is loading it as context and asking the exact EP05 questions, side by side. Terms: the compiled side's system prompt is one sentence naming its role, matching the EP05 app. The artifact used is A1a, the neutral one, because using the more explicitly annotated A1b would be stacking the deck.

Shipping threshold question, compiled side:

Standard zones: free over ¥99 / ¥8 fee below ¥99
Remote zones (Xinjiang, Tibet, Gansu, Qinghai, Inner Mongolia, Ningxia):
  excluded from promotional free shipping, ¥15 surcharge applies

> Note: our rules changed recently, so please treat the shipping
>   amount shown at checkout as authoritative

Retrieval side: "Orders over ¥99 ship free (remote zones excepted). Below ¥99, an ¥8 fee applies."

Both report one number. Neither mentions ¥59. And the compiled side does something slightly worse: the artifact it's reading says "document conflict" in plain text, and the answer rephrases that as "our rules changed recently." Nothing in the library says the rules ever changed. That framing is invented, and it converts uncertainty into false confidence.

So the accurate claim isn't that compilation surfaces conflicts to users. It's that compilation solves finding the conflict and does nothing about telling anyone. Two separate jobs, and that gist only covers the first.

I reran the version questions too, formal and colloquial phrasing. Both sides answered correctly from the 2026 edition, 30 days to submit, five business days to review. Switching paradigms bought nothing there, for the same reason as before: the metadata was intact and retrieval was already handling it.

Where they actually diverge

The fourth question got it out: a customer in Xinjiang wants a sofa, can you ship it, is cash on delivery available, how is shipping calculated? Answering forces the remote-zone rules from both documents into one answer.

Retrieval side:

- Remote zone orders ship free over ¥129; below that, an ¥8 remote surcharge
  applies on top of the standard fee.
- Remote zones are excluded from promotional free shipping and require
  a ¥15 fee adjustment.

Those two bullets are mutually exclusive. Presented as a numbered list, they read like two rules that both apply. A support agent reading this to a customer contradicts themselves mid-sentence.

Compiled side, same question:

| Source document | Rule |
| 01-shipping-and-logistics | Free over ¥129 in remote zones, ¥8 surcharge below |
| 13/14-shipping-fee-table | Remote zones excluded from promo, ¥15 adjustment |

> ⚠️ The two documents conflict. Treat the checkout amount as authoritative.

Split by source, with a warning. Cleanest divergence in the episode, and the mechanism is easy to state: the compiled side put those two rules next to each other once, at compile time, judged them incompatible, and that judgment persisted in the artifact. The retrieval side never saw the library whole. It got two chunks and had no basis for deciding they were incompatible.

Put that with the previous section and the gain is narrow and specific: compilation pays off when two conflicting rules have to enter the same answer, because it knows they conflict. On simple single-fact questions it picks one silently, exactly like retrieval.

Cost went the opposite way from what I expected

I assumed this section would be where compilation died. Stuffing an entire library into context on every question has to cost more than retrieving a few chunks. It doesn't.

The four compiled-side questions ran back to back, and from the second one on prompt_tokens_details.cached_tokens had a value:

Call	Input	Cached	Output	Cost
Q1	7,929	0	370	¥0.1085
Q2	7,935	7,168	388	¥0.0339
Q3	7,932	7,168	287	¥0.0303
Q4	7,942	7,168	665	¥0.0440

The artifact prefix bills at the cache-hit rate, ¥1.5 per million, 12.5% of standard input. Only the few hundred tokens that change pay full price. Input cost per question fell from ¥0.0951 to ¥0.0200, and I configured nothing. The server matched the prefix implicitly.

Head to head:

Same question	Compiled (cache hit)	Retrieval	Delta
Shipping threshold	¥0.0339	¥0.0753	compiled 55% cheaper
Xinjiang sofa (cross-document)	¥0.0440	¥0.1431	compiled 69% cheaper

Two reasons. The retrieval side's 4,739 input tokens get no discount at all, everything at ¥12. And retrieval generates more output, because it emits tool calls and restates what it retrieved: 1,510 tokens against 665 on the cross-document question, and output is the expensive line item at ¥36 per million.

Compiling costs ¥0.4162 once. Steady-state savings averaged ¥0.0703 per question, so ¥0.4162 ÷ ¥0.0703 ≈ 6. Roughly six questions in, the compile pays for itself.

That 6 rests entirely on the cache. Look at Q1 again: with no cache hit, compiled costs ¥0.1085 against retrieval's ¥0.0753, which is 44% more. Heavy consecutive use breaks even at six and then runs half to two thirds cheaper. Sparse occasional use pays a cold start every single time and never breaks even.

My four questions ran inside a minute of each other, so the second one hit. How long the prefix survives is a server-side policy question, and you'll want to measure it against your own traffic. Which lines up with the boundary Karpathy drew himself: if you just need to look one thing up, RAG is fine. He offered that as intuition. This is the invoice.

Writing a human decision back in

The other RAG criticism in that gist is the absence of accumulation. Every question starts from zero, so yesterday's conclusion doesn't carry. A compiled artifact is a file, so you can write conclusions into it.

I simulated what an operations team would do, appended to the end of A1a: operations confirms ¥99 and ¥8 are current, the ¥59 and ¥10 figures are pre-2024 and must not be used, agents must also tell the customer the threshold changed, and the remote-zone conflict is not yet decided so escalate to a team lead. That last line is deliberate: one conflict resolved, one explicitly left open, so I could see whether it distinguishes them.

Same shipping question, new answer:

Current rule: free shipping over ¥99 / ¥8 fee below ¥99

⚠️ Heads up: this threshold changed recently. If you've seen "free over ¥59"
   somewhere, that's the old rule and no longer applies. ¥99 is current.

One more thing: remote zones have their own rules. If your delivery address
   is in one of them, let me know and I'll confirm the details for you.

¥59 appears in a customer-facing answer for the first time, with the correct disposition attached. On the conflict I left undecided it didn't force an answer, it asked for the delivery address and offered human follow-up. And the internal instruction to escalate didn't leak.

There's a practical finding buried in this call. cached_tokens was still 7,168. The arbitration log went at the end, so the prefix didn't change and the cache survived. Append rather than insert, and incremental maintenance stays cheap.

The cost of all this is that a human made the call. Compilation didn't tell me whether ¥59 or ¥99 was right. It put the disagreement in front of me.

Limits

The context window is not the constraint here. bl model list --model qwen3.8-max reports a 1,000,000 window and 991,808 max input tokens. Those 8,811 characters compile to 5,905 input tokens, so 991,808 ÷ 5,905 ≈ 168. The library can grow 168× before the window matters.

One asymmetry belongs on the table. The compiled side read the full text dump of the messy spreadsheet; the retrieval side read the 11 chunks it was split into. The compiled side genuinely saw a more complete table. That follows from the definitions, compilation eats documents and retrieval eats chunks, but part of the divergence on the cross-document question comes from seeing more, and that part shouldn't be credited to the paradigm.

Update costs are lopsided. Change one document and the compiled side re-runs the whole compile, ¥0.4162 and about three minutes, and the new artifact invalidates the cache prefix so the next question pays ¥0.1085 instead of ¥0.0339. The retrieval side re-uploads and re-indexes that one document at effectively zero cost.

Cases where I'd skip compilation, in priority order:

Libraries needing per-user access control. A compiled artifact merges cross-department knowledge onto shared pages, which breaks permission boundaries by construction. A retrieval pipeline can pin tenant_id and filter before search. I haven't seen this objection raised publicly.
Libraries that change often, per the update cost above.
Sparse, occasional questions, where no cache hit means every question costs more.
One-off lookups. Karpathy's own boundary.
Personal knowledge management, which inverts the enterprise case. Organizing material is itself how learning happens. A company library exists for other people to query, so automating it costs nothing. Automate your own study notes and the learning stops.

Try it

npm install -g bailian-cli
bl auth login --api-key sk-xxxxx
bl model list --model qwen3.8-max
bl text chat --model qwen3.8-max --messages-file messages.json --output json

Ten billed calls, ¥1.27 total, about eighteen cents.

My read: this isn't a choice between two options. On this library, compilation delivered visible conflicts and durable decisions. It did not deliver disclosure to the end user, so you'll need prompt or process work to cover that gap. And the economics rest entirely on cache hits, so a change in question cadence flips the math.

Last episode I said the curation debt comes due no matter what. Switching paradigms changes one word: compilation will itemize the debt for you, but you still pay it. It put a mismatch that had been sitting in my library for five episodes right in front of me, and in the same pass it threw away the timestamp needed to settle it.

Next episode continues the paradigm arc. I fed the artifact in as one block and got implicit cache hits from the second question on, which saved real money, but I have no idea when that prefix expires because it's entirely server-side. Model Studio also offers explicit caching, ¥15 per million to create and ¥1 per million on hits, with rules that work nothing like the implicit path. EP07 runs both against this same artifact.

Everything here was measured with Model Studio's CLI (bl). Full usage figures, reasoning traces and compiled artifacts from all 10 calls are archived in the project repo. Command signatures may shift between versions, so check the official docs. API keys are free to obtain, with a free tier for new accounts.

Retrieval Ranked the Expired Policy First. The Agent Ignored It.

张洲诚（Zack.ZHANG） — Thu, 03 Sep 2026 09:49:36 +0000

Building a Knowledge Base from Scratch, EP05. The advanced arc begins.

The setup

Last episode closed the fundamentals arc with a cliffhanger: my knowledge base holds an expired 2023 expense policy, the 2026 rewrite that contradicts it, and eleven broken-spreadsheet fragments. Fixed retrieval ranks the expired policy first, 0.7226 to 0.7055, and no reranker setting moves it. The colloquial version of the invoice question drops the current policy out of the top five entirely.

This episode wires the library into an agent and watches what it does. Eight controlled runs, same library both sides. The control group is EP04's fixed retrieval. The experiment group is a new agent application in the console: pick a model (qwen3.8-max, chosen from bl model list --capability TG, which lays out fifty-four conversational models with context windows and prices), associate the knowledge base, switch on the thinking process, publish.

One command, and the agent's whole reasoning comes out:

bl app call --app-id 32d619eeea744a31ad892e3873afe487 --prompt "报销发票怎么提交" --has-thoughts --stream

The --stream flag matters. --has-thoughts alone returns only the answer. With both flags, the output arrives in three marked segments: [Thinking] (the judgment), [Action] (the tool call, search_knowledgebase in every run this episode), and [Observation] (the tool's return, embedding the full retrieval JSON: scores, the rewrite field, the reranker name, total 27). Cheapest agent-audit mechanism I know of.

A trap before the start

My first instinct was to skip the console step and call the retrieval service that the platform auto-created back in EP02. Its ID was on file.

bl app call --app-id aid-4d6b2f2fddd047c794a5f88963ef397b --prompt "报销发票怎么提交" --has-thoughts

HTTP 403, App.AccessDenied. The API key was fine. That resource is a retrieval pipeline built for bl knowledge search --agent-id, not an agent application. The official docs seal it: the old RAG-augmented applications stopped accepting new instances in May 2024, and the official path is associating your knowledge base with an agent application. Two kinds of resources, two roads. The 403 is the border post.

One design note on the application: the system prompt is a single sentence, "you are the customer-service assistant for Nuanwu Home Furnishing." Deliberately minimal. The exam questions are whether the agent notices the version conflict, rewrites colloquial questions, and admits ignorance on its own. Write those hints into the prompt and you're grading the prompt, not the agent.

Discovery 1: the expired policy still ranked first. The answer used the current one.

The agent's retrieval results had the old policy first, 0.5655 to 0.4713. The answer was pure 2026 policy: electronic invoices, thirty days to upload through Enterprise WeChat, five working days for review. The old policy's fifteen-working-days-and-staple-paper routine never appeared.

The thinking trace holds the pivot line: "我应该以现行版为准回答" (I should answer based on the version currently in force). The agent had read the current policy's opening sentence, "the 2023 version is hereby superseded." That sentence is metadata the document carries about itself. The retrieval layer sorts by textual relevance. The decision layer reads context and picks.

The reverse check made it solid. Ask "住宿标准是多少" (what's the lodging cap) and this query's ordering flips, current policy first at 0.8512. Same answer either way. The ranking swings with the query. The answer doesn't swing with the ranking.

Discovery 2: the colloquial question got rescued, and the rescue is visible

EP04's most painful result: ask "发票交了之后多久能报下来" (how long until the money lands) and the current policy falls out of the top five, replaced by the old policy at 0.4700 plus four spreadsheet fragments.

The agent answered correctly. Five working days, citing the current policy. The interesting part was in the Observation metadata, a rewrite field:

"rewrite": "发票报销多久能报下来报销周期"

The server had rewritten the colloquial question into document-style phrasing before retrieval. EP04 mentioned the enableRewrite config with no behavioral evidence. Now the evidence exists: control group direct search on the same question produces the 0.47-range fragment pileup; the agent channel has the current policy comfortably present. Two layers in relay, both on by default, zero code.

Discovery 3: the broken fragment got used as evidence

Ask "新疆买沙发能发货吗" (can a sofa ship to Xinjiang). The agent's retrieval: the broken-spreadsheet fragment first at 0.8305, the clean document second at 0.7245. Then my favorite passage of the episode, the agent comparing sources:

The clean version provides general information about large-furniture delivery but doesn't specifically exclude remote areas.

It noticed the granularity gap. The fragment has rotten formatting but is an explicit clause naming remote regions. The clean document is complete but vague on this specific question. The final answer is stitched: the no-large-items conclusion from the fragment, the 6-8 day window and 15 yuan surcharge context from the clean document. The eleven fragments went from retrieval killers to the decision layer's ugly-but-usable evidence.

Discovery 4: it decided not to search at all

Second turn, with --session-id attached, asking what the 2023 policy said. No tool call this turn. The trace: "based on the previously retrieved results, the 2023 policy states: review takes about 10 working days." It reused the previous turn's slices, answered correctly, and volunteered a comparison with the current process. "Who decides what to search" includes the third case: who decides not to. Sessions expire after one hour without requests, so pace your experiments.

Discovery 5: honest refusal

Ask it to compare shipping policies with IKEA. The library holds nothing about IKEA. The trace: "I should not compare ourselves with other companies in a way that fabricates." The answer states its own policy in full (all library-sourced), declines to speak for IKEA, and redirects: tell me what you care about and I'll walk you through our terms. A move straight out of human customer-service training.

The turn: it rescued the version conflict, and silently fumbled the threshold conflict

Then the cold water, from an unplanned discovery. The shipping answer contained "in-stock items ship within 48 hours of payment." Suspicious, since neither shipping document seemed to say that. I searched the library specifically. Real content, document 01, retrieval score 0.9456. False alarm on the hallucination, but the search surfaced the real problem: the library holds two free-shipping thresholds. Document 01 says free shipping over 59 yuan. Document 13, the clean table, says free over 99. Both were in the agent's retrieval results that turn, 01 scoring higher at 0.6557 to 0.5755.

The agent took the 48-hour timeframe from 01 and the free-shipping-over-99 rule from 13. By topic, from each what it needed. Not one word about the 59-versus-99 conflict. It silently output one of two contradictory policies.

Compare with the version conflict and the boundary is exact. The expense policies carry their arbitration basis in plain text: "the 2023 version is hereby superseded." The agent reads that and arbitrates. The shipping documents carry nothing. The agent can't arbitrate, and doesn't even register that arbitration is needed; from its seat these look like two topics, not one conflict.

The deepest finding of the episode: the decision layer rescues conflicts that carry evidence chains and cannot rescue conflicts missing metadata. Gartner's much-quoted number says 80% of enterprise agent projects never reach production over hallucination and consistency problems. This experiment is a micro-footnote: the agent's judgment filled real retrieval-layer holes, and the metadata debt in the library it cannot carry for you.

Command surface notes

--pipeline-ids: with the application already associated to a library, passing the correct ID changes nothing (redundant), and passing a fake one (fakeid123) also changes nothing, silently, no error, still the mounted library. You think you switched. You didn't. Same pattern as EP04's --rerank-mode accepting garbage values. A parameter's presence in the CLI table is not a promise the server validates it.

--session-id: first call's response carries the ID, pass it back for automatic context, cloud storage expires after one idle hour.

Try it

npm install -g bailian-cli
bl auth login --api-key sk-xxxxx
bl app call --app-id your-app-id --prompt "your policy question" --has-thoughts --stream

Before you ship an agent on top of a real document library, take your most conflict-prone business rules, run them with --has-thoughts --stream, and read the Observation sections. Two documents present, two different numbers, one silent answer: that's the failure you want to find before your users do.

All eight agent calls and retrieval controls ran for real on the Bailian CLI; full thinking traces and request IDs are kept in the project repo. CLI install: Bailian CLI docs. API key: get one free, new accounts include free quota.

We Maxed Out the Reranker. The Expired Policy Still Won.

张洲诚（Zack.ZHANG） — Fri, 28 Aug 2026 10:07:32 +0000

Building a Knowledge Base from Scratch, EP04

The setup

Last episode I polluted my knowledge base on purpose: an expired 2023 expense policy next to the 2026 rewrite, a broken spreadsheet that shattered into 11 of the library's 27 slices. The old policy outranked the current one at 0.7226 versus 0.7055. The standard advice for this failure mode is the same everywhere you read: turn on the reranker.

This episode answers it with twenty-two commands, not opinions. Same library (zj0knmrbye), baseline re-run first: five scores identical to the EP03 verification file, digit for digit. The library hadn't drifted. Everything below stands on that.

Discovery 1: reranking was already on

Before touching any parameter, I read the library's configuration:

bl knowledge info --index-id zj0knmrbye

There in the output: rerankModelName: qwen3-rerank. If you picked a ranking model when creating the library, it has been scoring every query since day one. So adding --rerank to the command changed nothing, all five results identical. The flag confirms the status quo. It doesn't start anything.

The proof that parameters do reach the server: swapping the model.

bl knowledge retrieve --index-id zj0knmrbye --query "报销发票怎么提交" --rerank --rerank-model qwen3-rerank-hybrid

All five scores shifted, from the 0.72 range to the 0.68 range. Different model, different scoring scale. But note the ordering didn't budge. Hold that thought.

The mode trap

--rerank-mode sits right there in the parameter table with three values: qa, similar, custom. I tried the aggressive version, custom mode with the instruction "优先返回2026年现行版制度", prefer the policy currently in force.

Results identical to baseline. Then I filled the mode field with a value that doesn't exist, xxx. The command ran fine. No error. When an invalid value produces no complaint, the parameter isn't being consumed at query time at all. The official docs have the matching sentence: the ranking model's mode is selectable only at library creation and cannot be changed afterward.

A flag being in the parameter table is not a promise you can set it at query time. This one is a library-level setting, locked at birth.

The arithmetic constraint

The recall parameters, --dense-similarity-top-k and --sparse-similarity-top-k, control how many candidates each lane feeds into the reranker's pool. Tested one lane at a time: nothing changes, this library's default is hybrid recall, both lanes or nothing. Both lanes at 5+5: the total field in the JSON drops from 27 (the whole library) to 6 (the merged candidate pool), and from third place down the cast changes.

Then the extreme values. Recall lanes at 1 and 1, rerank window at 10. The server refused it outright, HTTP 400:

{"message": "dense_similarity_top_k + sparse_similarity_top_k >= rerank_top_n", "api_code": "Index.InvalidParameter"}

The two recall lanes combined must be able to fill the rerank window. One plus one is two; two can't fill ten; rejected. The server states the pipeline's arithmetic constraint in the error itself. Honestly the best architecture documentation I've read all week.

One more behavior worth knowing: rerank window at 100 with both recall lanes at 200 returned only 17 of the library's 27 slices. The missing ten were dropped by the rerankMinScore 0.2 gate. What you ask for is a ceiling. What clears the bar is what you get.

The main event: rerank versus dirty data

Four controlled runs against the EP03 failure cases. --rerank alone. --rerank-mode similar. Custom mode with the explicit instruction to prefer the 2026 policy. The fragment question with --rerank. Every single one returned results identical to baseline, digit for digit. The expired policy held first at 0.7226. The broken-spreadsheet fragment held first at 0.7982.

The mechanism is not mysterious. A reranker scores candidate chunks by textual relevance to the query. The old policy's line, "staple the reimbursement form with original invoices and hand them to the accountant", reads exactly like an answer to "how do I submit invoices". A reranker scoring accurately still operates inside the frame of "more relevant goes first". It doesn't know which policy was superseded. That was never its job.

The model swap confirms it from the other side: qwen3-rerank-hybrid changed every score and moved zero rankings. Ordering is decided by textual relevance. The model choice sets the scale.

The phrasing gap

Parameters can't rescue dirty data, and it turns out they can't rescue phrasing either. Same fact, two askings. Literal: "报销发票怎么提交", the two policy versions neck and neck. Colloquial: "发票交了之后多久能报下来", how long until the money lands. The top five collapsed to the old policy at 0.4700 followed by four broken-spreadsheet fragments. The current policy fell out of the top five entirely.

Same pattern on the freight question. "新疆买沙发能发货吗" finds the answer fragment at 0.7982. Rephrase as "偏远地区买大件家具送不送", do you deliver big furniture to remote areas, and the winner becomes a fragment about free delivery in East China, 0.7420, purely on the literal match of the words for "large items". The actual answer fell to third.

Retrieval matches wording, not intent. Your users don't phrase questions the way your documents phrase answers. The enableRewrite setting in the library config is the platform's library-level compensation for exactly this.

A correction I owe

EP02 and EP03 both claimed knowledge base ingestion has no CLI command, console only. Wrong. bl knowledge --help lists 31 knowledge subcommands, and doc upload is one of them. I ran the full loop this episode: upload a temporary markdown file, watch the status come back PARSE_SUCCESS, clean up with file delete. With --index-id, upload and ingest complete in one step.

How the error happened: the local reference file with all 31 commands already existed at EP02 verification time. I checked the few I needed that day and treated "what I checked" as "what exists". A partial audit is not a full conclusion. Second episode in a row in that pit.

Two exhaust pipes, one engine

retrieve is now marked deprecated, with a successor called search that routes through a deployed retrieval service. Same query on both paths: five scores identical digit for digit. The differences are all in shape. search returns text as structured blocks, document name, title, body, ready for an agent's context. Its metadata carries the rerank score, the query score, and a cost_time of 321ms. And its total field counts actual results (5) instead of the candidate pool (27).

Tuning and experiments: retrieve, the full parameter surface is in your hands. Agent integration: search. Same engine underneath, so the twenty-two findings apply to both.

The triage order

Twenty-two commands compressed into a checklist, walked from the top:

Is the evidence present at all? Correct answer missing from the top five means corpus or phrasing problems. No parameter helps.
Run the two-phrasing check. Same fact, literal and colloquial. A drifting top result tells you more than any single high score.
Only then, parameters. top-k sizes the pool, top-n sizes the plate, and the arithmetic constraint is enforced with a 400.
Keep expectations for rerank level. It puts the more relevant first. It doesn't manufacture correct answers.

Try it

npm install -g bailian-cli
bl auth login --api-key sk-xxxxx
bl knowledge info --index-id your-library-id
bl knowledge retrieve --index-id your-library-id --query "how do i submit invoices"

Take the rule you trust least in your own documents, ask about its procedure in two different phrasings, and watch whether the top result survives the rephrase. That stability, or lack of it, is the honest health check of your library.

All twenty-two retrievals ran for real on the Bailian CLI against the zj0knmrbye knowledge base; request IDs are kept in the project repo. CLI install: Bailian CLI docs. API key: get one free, new accounts include free quota for 90 days.

I Fed Two Versions of a Policy to My Knowledge Base. The Expired One Won.

张洲诚（Zack.ZHANG） — Fri, 28 Aug 2026 09:57:55 +0000

Building a Knowledge Base from Scratch, EP03

The setup

EP02 built a knowledge base with three clean, hand-written FAQ files and retrieval worked great. Real companies don't hand you clean files. So this time I ingested five documents of the kind that actually cross your desk: a 2023 expense policy nobody deleted, the 2026 rewrite that contradicts it in six places, the same freight table twice (once as sectioned Markdown, once as a merged-cell Excel with a note rotting in a corner of sheet two), and a 5,000-word support manual.

All five went into the EP02 library (zj0knmrbye), no fresh index, because a real library grows one file at a time. Eight documents, 27 slices, smart chunking. Then ten retrieval queries, three failures.

One detour first

The CLI has a bl file upload command. It is not ingestion. It uploads to DashScope temporary storage, expires in 48 hours, and its mandatory --model flag gives away the purpose: binding a file to a model for multimodal calls. A parcel locker, not a warehouse. Knowledge-base ingestion still lives in the web console, drag and drop.

Failure 1: version blindness

bl knowledge retrieve --index-id zj0knmrbye --query "报销发票怎么提交"

(How do I submit invoices for reimbursement?) Top hit at 0.7226: the 2023 version, demanding paper invoices stapled and delivered to the accountant within 15 working days. The current 2026 version came second at 0.7055 with e-invoices uploaded within 30 days. The gap is 0.017.

Three queries total, both versions neck and neck every time, largest gap 0.05. The winner is decided by whose phrasing matches the question, nothing else. I named the files "2023旧版" and "2026现行版"; filenames don't participate in retrieval at all. There is no version awareness in the retrieval layer. The old version doesn't just coexist, it occasionally wins.

Failure 2: the carrier matters more than the content

Same freight information, two carriers. Ask "新疆买沙发能发货吗" (can a sofa ship to Xinjiang?) and a fragment from the raw Excel takes first at 0.7982:

时效运费:6-8天不发大件（沙发床垫餐桌）差价15

The word "sofa" is literally in there, so the score is fair. But the fragment can't answer anything: 15 RMB is the difference from what? The clean Markdown version came second at 0.6894 with a complete, forwardable rule.

Worse numbers hide in the structure. The 6KB Excel expanded into 11 of the library's 27 slices (the console's slice view counts exactly that), 40%. Its stale corner note, "以上如有变动以客服最新答复为准（2024.6 更新）", crashed the top five in six of my ten queries on high-frequency words alone. One offhand spreadsheet became the library's permanent noise floor.

And one accident I didn't plant: asking the free-shipping threshold returned both 满99包邮 from the new table and 满59包邮 from the EP02 FAQ. Two true-at-the-time documents, zero reconciliation. Retrieval serves both. It doesn't arbitrate.

Failure 3: what smart chunking actually does

The 5,000-word manual finally triggers chunking. Three findings. Titles ride along: each slice carries the headings of its sections, and they participate in matching, so heading hierarchy is load-bearing infrastructure, not typography. Cross-chapter slices exist (a slice starts with the tail of 4.5, then chapter five) but semantics survived. Tables keep their content and lose their syntax: a two-column Markdown table came back as pipe-joined rows, 场景|建议话术|, information intact, structure gone.

Also: the manual's version line, "版本：v3.2 ｜更新日期：2026 年 6 月", landed in slice one. Retrieval ranking ignores it. The generation-stage model reads it. In a version conflict, that line is the only thing downstream that can tell old from new.

The checklist

Delete expired versions before ingestion (the 2023 file outranked the 2026 one).
One fact, one number, reconciled across files (59 and 99 both came back).
Defuse Excel: unmerge, re-home corner notes, consolidate sheets, or convert to Markdown (6KB became 40% of all slices).
Structure long documents with headings; they become the chunker's road signs.
Write version and date in the body's first line, not the filename.

Zero code. The right people to execute it are the document owners, finance and ops and support leads, not the person holding the CLI.

Honest limits

The messy Excel frequently outscores the clean document; if you audit data quality by score, it will fool you. Audit by whether the returned content can answer the question. Smart chunking boundaries aren't controllable from your side, though the console does offer manual slice editing. And my library is now polluted on purpose; production libraries shouldn't be.

Try it

npm install -g bailian-cli
bl auth login --api-key sk-xxxxx

Collect your real documents, run the five-item checklist, ingest in the console, then verify: pick the rule you trust least, ask about its procedure, and check whether the top two hits are two versions of the same document. If they are, the checklist wasn't finished.

All ten retrievals ran for real on the Bailian CLI against a Model Studio knowledge base; request IDs are kept in the project repo. CLI install: Bailian CLI docs. API key: get one free, new accounts include free quota for 90 days.

I Split One Fact Across Two Files to Test If RAG Retrieval Actually Works

张洲诚（Zack.ZHANG） — Mon, 24 Aug 2026 10:26:42 +0000

Building a Knowledge Base from Scratch, EP02

The promise from last time

Last episode I ran three experiments on the "paste a file into chat" habit: half a document and the model improvises, the wrong edition and it waves you through, a new window and it remembers nothing. I promised that next time we'd build a real knowledge base. This is that episode.

The setup: a fictional small store ("Cozy Home," home goods and small appliances) with three Markdown support FAQs: shipping policy, returns & warranty, payments & invoices. Each file is 1-2KB. Plus one deliberate trap.

The trap

I split the cash-on-delivery information across two files. Which regions support COD lives in the shipping policy. The 3 RMB collection fee lives in the payments doc. This mirrors how real companies operate: ops writes shipping rules, finance writes payment rules, and nobody answers for the other document's completeness.

If retrieval works the way RAG claims, asking "does COD cost extra?" should surface both files at once. If it's just fancy keyword matching, it won't.

Building the library

Honest disclosure first: there is no CLI command for creating the knowledge base. The bl CLI's knowledge group currently has exactly one command, retrieve. Ingesting documents happens in the web console: standard edition, file connector, drag in three files, wait for the status to flip to active. Ten minutes, zero code. The store owner could have done it.

The console hands you a knowledge base ID (mine was zj0knmrbye). Every retrieval command points at it.

The retrieval

bl knowledge retrieve --index-id zj0knmrbye --query "新疆可以货到付款吗"

The query is Chinese because the documents are Chinese. The CLI doesn't care. What comes back is JSON:

{
  "data": {
    "total": 3,
    "nodes": [
      {
        "score": 0.8299149870872498,
        "metadata": {
          "doc_name": "01-发货与物流政策",
          "content": "……货到付款仅支持华东、华南主要城市。偏远地区（新疆、西藏等）不支持货到付款，请选择在线支付。货到付款订单需额外支付 3 元代收服务费。……"
        }
      },
      {
        "score": 0.48945897817611694,
        "metadata": { "doc_name": "03-支付与发票说明" }
      }
    ]
  }
}

score is the relevance ranking. doc_name tells you which file the answer came from. content is the original passage, verbatim, not a processed conclusion.

Five queries, three findings

Query	Hits	What it proved
Does COD work for Xinjiang?	Shipping 0.83 + Payments 0.49	Cross-file recall
Free shipping threshold?	Shipping 0.68	Factual hit
My humidifier arrived broken	Returns 0.75	Semantic match (zero keyword overlap)
Can coupons stack?	Payments 0.54 (only hit)	Below-threshold filtering
Does COD cost extra?	Shipping 0.82 + Payments 0.77	Both files, high scores

The humidifier query had no keyword overlap with the docs at all. It hit at 0.75, returning 「电器类商品（如加湿器、小夜灯）提供 1 年保修，非人为损坏免费维修或换新」, which translates to "electrical products (humidifiers, night lights) carry a 1-year warranty, free repair or replacement for non-artificial damage." The query says "broken"; the passage says "non-artificial damage." That's semantic retrieval, not string matching.

The coupon query returned exactly one result out of a three-document library: 「新人券：首单满 59 减 10，仅限新注册会员，不可与其他优惠叠加」, "the newcomer coupon cannot be combined with other offers." "Stack with" matched "combined." The other two docs weren't dragged in to pad the answer. If you're wiring this into a downstream system, don't assume the nodes array has a fixed length.

The COD fee query was the payoff. Shipping policy at 0.82, payments doc at 0.77. Shipping returned 「货到付款仅支持华东、华南主要城市（上海、杭州、南京、广州、深圳、厦门等）」, "COD is supported in major east and south China cities only." Payments returned 「需额外支付 3 元代收服务费」, "an extra 3 RMB collection fee applies." The retrieval assembled both without being told where anything lived. That's the entire value proposition of RAG in one response: you don't need to know which file the answer lives in.

Three small observations for builders

Small documents don't get chunked. Each KB-scale FAQ came back as one whole slice. Bigger documents will get sliced, and where the cuts land determines retrieval quality. That's the next episode's topic.

No model selection. The command has no --model flag. The knowledge base ships with its retrieval model built in.

The output is JSON by default. No extra flags. jq one-liner gets you the top hit's content. Wiring retrieval into an existing system costs close to nothing.

Honest limits

The library was tiny (three files), so chunking never came up, which is the best case. Retrieval returns raw passages, not phrased answers; don't paste them straight into customer replies. And score is a within-query ranking signal, not a percentage: in my runs, 0.54 was the only correct answer to one question while 0.49 was a bystander in another. Never filter by absolute score.

Try it

npm install -g bailian-cli
bl auth login --api-key sk-xxxxx

Write three Markdown files from your own domain, build the library in the console (ten minutes), copy the index ID, and run one retrieval. Then ask a question whose answer spans two of your files. Watch what comes back.

All five retrievals ran for real on the Bailian CLI against a Model Studio knowledge base. Commands and full JSON responses are kept in the project repo. CLI install: Bailian CLI docs. API key: get one free.

I Handed My AI the Company Policy. It Never Asked If the File Was Still Valid

张洲诚（Zack.ZHANG） — Fri, 21 Aug 2026 10:32:38 +0000

Building a Knowledge Base from Scratch, EP01

Everyone worries about LLM hallucinations on company-internal questions. In 2026, the standard move is pasting a policy file into the chat first, so hallucination feels handled. I ran three controlled experiments on that move itself, and found three failure modes that have nothing to do with hallucination: it improvises around missing files, it never questions the version you hand it, and it forgets everything by the next session.

This post walks through all three with reproducible commands. It's the first episode of a series that builds a knowledge base from zero.

The setup

Tool: Bailian CLI (bl), the CLI for Alibaba Cloud's Model Studio
Model: Qwen3.8-Max
Question domain: a company travel policy. A real reimbursement answer spans the policy PDF, an OA announcement, a shared-drive form template, and a group-chat notice. No one pastes all four every time.

Install and authenticate if you want to follow along:

npm install -g bailian-cli
bl auth login --api-key sk-xxxxx

An API key with free quota is available in the Model Studio console.

Experiment 1: paste half the policy

I pasted only the standards section (450 RMB cap for first-tier cities, over-cap not reimbursed, 30-day filing window) and left out the approval-process section, then asked whether a 550 booking could be reimbursed and what the process was.

bl text chat --model qwen3.8-max --message "根据以下公司制度回答问题：《星野科技差旅报销制度（2026年3月修订）》（一）住宿标准：一线城市450元/晚，二线城市350元/晚，其他城市300元/晚。单人单晚超出标准部分原则上不予报销。（二）报销时限：出差返回后30日内在财务系统提交，逾期视为放弃。问题：我下周去上海出差，订了550元一晚的酒店，能报销吗？具体流程是什么？"

The standards half was flawless: 450 cap, 100 over, reimbursed at 450. The process half started leaking. It admitted the document "doesn't specify an exception process," then filled the gap with industry common sense: invoice, payment record, trip approval form. None of that was in the text I gave it. Its reasoning log said it plainly: the policy doesn't detail this, but suggestions can still be offered.

The control run with the full policy produced the complete chain: OA approval form, two director signatures, four evidence types, 30-day deadline. One file of distance between the two answers.

Experiment 2: paste the outdated version

I swapped in the 2023 edition (cap 600, every other clause identical) and asked: booking at 600 gets fully reimbursed, right? If so I'll place the order.

bl text chat --model qwen3.8-max --message "根据以下公司制度回答问题：《星野科技差旅报销制度（2023年1月修订）》（一）住宿标准：一线城市600元/晚，二线城市450元/晚，其他城市350元/晚。单人单晚超出标准部分原则上不予报销；因会议安排等特殊情况超标的，须出差前在OA系统提交《超标住宿审批单》，经部门总监与财务总监双签后方可报销。（二）报销时限：出差返回后30日内在财务系统提交，逾期视为放弃。问题：我下周去上海出差，准备订600元一晚的酒店，按这个制度能全额报销吧？没问题我就下单了。"

It ran a diligent checklist: city tier, tax-inclusive pricing, single occupancy, the 30-day window. It even warned that 601 would tip it over. Then it waved me through: no over-cap, fully reimbursable, no approval form needed.

Not once did it ask whether a 2023 policy is still in effect. The 2026 revision caps it at 450. Booking at 600 on the old file means paying 150 a night out of pocket. The AI said nothing wrong; the file was wrong, and the model has neither the duty nor the ability to suspect your file.

Experiment 3: new window, no file

bl text chat --model qwen3.8-max --message "我们公司规定一线城市出差住宿费每晚报销上限是多少？"

The reply: I don't have your company's internal policy. Everything you pasted yesterday is gone.

Why this argues for a knowledge base

The manual-paste move has a structural flaw beyond inconvenience: you usually don't know which file the answer lives in. Reimbursement spans the policy, the OA notice, the group announcement. Support spans the product page, the after-sales doc, the latest Excel from ops. You can't paste what you can't find.

RAG (retrieval-augmented generation) fixes all four gaps at once: ingest every source in every format once, retrieve across files at query time, serve everyone the same currently-effective version, retire old versions at the document layer. Store, retrieve, answer. That's the architecture behind most internal Q&A systems since 2023, and the frontier keeps moving: agents that decide what to retrieve (Agentic RAG), Karpathy's compile-don't-retrieve LLM Wiki proposal from this April, and PixelRAG's screenshot-based retrieval.

The series continues with EP02, where we build an actual knowledge base in the Model Studio console, load the policy, announcements, and FAQ together, and query it with one command. Fifteen minutes, end to end.

All commands and raw responses are kept in the project repo for verification. CLI docs: Bailian CLI.

DeepSeek Harness Got 4,000+ Plugins in a Week — All Eyes, No Hands

张洲诚（Zack.ZHANG） — Wed, 19 Aug 2026 07:00:36 +0000

Everyone's reviewing the philosophy. I went through the plugin directory instead.

DeepSeek open-sourced DeepSeek Harness (DSH) on August 13. A week later: 160k stars, 4,000+ third-party plugins. The coverage has mostly been about the "everything is a plugin" pitch: model, tools, session, sandbox, even the UI is swappable.

Neat. But I had a more specific question: across those 4,000 plugins, what is everyone actually bolting onto this thing?

So I spent an evening going through the plugin directories. Found a pattern, found a gap, and filled the gap with a single command. Details below.

What people are actually installing

The category map as of mid-August:

Category	What it does	Representatives
Workbench	VS Code-style sidebar workbench	DSH-better-sidebar
Long-term memory	Cross-session project memory	dsh-memory-evolve, EverOS, dsh-persist
Vision (image reading)	Give the text-only model sight	ModLens, dsh-tool-describe-image
File references	@-mention files in the input	dsh-at-file
Multi-agent	Spin up sub-agent teams	dsh-agent-teams
Claude Code migration	Move configs/skills/history over	dsh-claude-move
Memes	Virtual pets, mini-games	deepseek-manners

Memory is a three-way race, vision has two clear leaders, and the long tail is everything else.

An easy-to-miss detail: one provider keeps showing up

DSH's chat models are text-only, so "reading images" was the first gap the ecosystem filled. The two leading vision plugins both default to Qwen-VL on Alibaba's Bailian (Model Studio) platform.

dsh-tool-describe-image has you set a DASHSCOPE_API_KEY in setup, default model qwen-vl-plus (one config line swaps to qwen-vl-max)
ModLens's OpenAI-compatible channel example uses Bailian's compatible-mode endpoint as the base URL, sample model qwen3-vl-plus

Two authors who don't know each other, same default choice. Meanwhile in the memory lane, EverOS (local-first memory layer) configures its LLM in standard OpenAI-compatible form and defaults to OpenRouter, but points at Bailian's endpoint just fine. And DSH itself doesn't lock the main model; custom providers and base URLs are first-class settings.

So inside DeepSeek's own ecosystem, the community has voted Bailian into three seats: the eyes, the memory engine, and the backup model slot. Nobody planned that. Config files did.

The gap: eyes everywhere, no hands

Here's what I did not find in the directory: a single plugin that lets the agent produce image, video, or audio files.

Every vision plugin solves "looking in." Nothing solves "making out."

This bit me personally. I had an agent in DSH build me a small Pomodoro timer web app. Code came out clean. But when I wanted to share it with friends (a decent card image, a short demo clip), the agent could only suggest tools for me to go use. The 90% was automated; the last 10% meant leaving the session, opening a design tool and a screen recorder.

Filling the spot without writing a plugin

Writing a DSH plugin is real dev work. Filling the "generation" seat isn't, for three architectural reasons:

DSH's standard mode ships a shell tool: the agent can run commands, so any CLI is already its tool
Bailian's CLI (bl) wraps image generation, image editing, and video generation as subcommands; the agent discovers flags via --help on its own
bl reads the same DASHSCOPE_API_KEY environment variable as the vision plugins. If you've configured one for reading images, you're already done

If you haven't: grab a free API key from the Bailian console, install the CLI (npm install -g bailian-cli, Node.js 18+; full docs), and store the key once:

bl auth login --api-key sk-your-key

Then tell the agent the ground rules once: every image, image edit, and video request in this project gets done with bl. That's the whole setup. Everything below: the prompts I typed were plain English; the commands are the agent's work.

Scenario 1: A share card for the finished project

What I said: "Make a share card for FocusTick. Dark background, a clean tomato-timer glyph in the center, the tool name below. Restrained, lots of whitespace."

What the agent ran:

bl image generate --prompt "product share card, dark background, flat-style tomato timer glyph at center, tool name FocusTick in clean type below, generous whitespace, restrained minimal design" --size 1280*720 --model qwen-image-3.0-pro --watermark false --out-dir ./assets --out-prefix focustick-card

A 1280×720 PNG lands in assets/ as focustick-card.png. Two things I learned: my first prompt omitted "generous whitespace" and the render came out cluttered; two words and a rerun fixed it, and iterating on a prompt is much cheaper than iterating on a workflow. And --out-prefix is a habit worth teaching the agent; without it, outputs default to the name image and become indistinguishable after a few runs.

Scenario 2: Wrong vibe. Edit, don't regenerate.

Friends pointed out the app is light-themed; a dark card felt disjointed.

What I said: "Switch the card's background to off-white. Don't touch the glyph or layout."

What the agent ran:

bl image edit --image ./assets/focustick-card.png --prompt "replace the dark background with an off-white light background, keep the tomato glyph, text, and overall composition exactly unchanged" --out-dir ./assets --out-prefix focustick-card-light

Key distinction: image edit is local modification. The composition you already liked survives. A fresh generate washes it away and redraws everything. Both files sit side by side (focustick-card / focustick-card-light), which is exactly what the prefix naming buys you. Bonus: --image can be passed multiple times for merges and composites, a rabbit hole for another post.

Scenario 3: "A static image doesn't show me how it works"

What I said: "Take the home screen screenshot and make a 5-second demo video. Slow push-in. Save it to assets."

What the agent ran:

bl video generate --image ./screenshots/home.png --prompt "camera slowly pushes toward the interface, cards gently appearing one by one, clean product-demo style, calm pacing" --duration 5 --download ./assets/focustick-demo.mp4

Three technical notes: passing --image auto-switches to image-to-video mode; video is an async task, so the agent waiting is not the agent stuck; and --download writes the mp4 on completion. Without it you get a task ID and need a separate download command.

The meter is running

These are real billable calls, and the agent runs them automatically. Three images in a burst means three charges. Two commands to have in place before you start:

bl usage freetier --all   # auto-stop when the free tier runs out
bl usage free --expiring 30  # remaining quota per model (needs bl auth login --console once)

Honest caveats on the free tier: it's valid for 90 days (not forever), and each model has its own quota. Running one dry doesn't auto-switch to another. Anyone claiming "permanent free quota" is misinformed.

Who should bother

If you build things inside DSH (small tools, personal sites, demos) and regularly hand something outward (cards, clips, illustrations), this closes the loop: code, assets, README, all in one session, no context-switching to a design app.

If your output is just code and text, skip it: running a bl command by hand when needed works fine; routing it through the agent isn't the point.

The takeaway I'd keep: 4,000+ plugins voted on what the ecosystem wants, and the "seeing" vote went to Qwen-VL. The "generating" seat is still empty, and filling it didn't take a new plugin, just one command already on the PATH.

To see what Bailian can do before committing, start from the console, more informative than any roundup, mine included.

Stop Rerolling AI Video: Lock a Keyframe First, Generate Once

张洲诚（Zack.ZHANG） — Mon, 17 Aug 2026 09:21:04 +0000

The saved video you never manage to remake

You scroll past a great short clip, tap Save, and think "I'll make something like this someday." When someday comes, every shot looks trivial in isolation — and together you have no idea where to start. What you saved is a finished product, not a structure.

The bigger wall is what creators call rerolling: the same prompt can return a cinematic shot or a broken mess. Industry coverage keeps citing creators pulling 20 generations for 1 usable take. That's not one vendor's bug — it's the current mechanism of video models, and every reroll bills per second.

(Quick scoping note: I've previously written about one-shot short-film pipelines, pre-production assets for short dramas, and prompt-writing methodology. This post is about single creative clips — the entry point is deconstructing a reference video's technique. They stand alone. And the stance throughout: extract the technique, never the content — every example here is a generic technique description, nothing points at a specific creator's work.)

The fix: move the decisions to the cheap step

Pure text-to-video hands composition, props, color grade, and background to the model's dice. Four random variables per generation, each one a potential reroll.

The fix is decision-frontloading: lock the first frame with an image model (cheap, synchronous, seconds), pick the best of several candidates, and only then let the video model do the one thing left — motion.

Step one costs nothing but attention: break the reference into a structure list — shot rhythm (cut length, push/pull), transitions (what bridges two shots), information density (one beat per shot or three). Manual scrubbing works fine; if you already run an agent, tools like Agent-Reach (70k+ stars on GitHub) can have it read YouTube videos and comment sections for a first draft. The comment section is free audience research: whatever moment the top comments celebrate is the hook — note the placement technique, not the content.

The command chain

Keyframe, four candidates in one call:

bl image generate --prompt "Product photography: a cup of latte on a dark walnut wood table, soft side lighting, delicate steam rising, shallow depth of field" --size 16:9 --n 4

--n 4 returns four images (max 6) — picking one moves your taste decisions to a near-free, seconds-fast step. --size takes the ratio directly; keep it aligned with the video's --ratio.

Then image-to-video as an async job:

bl video generate --image <keyframe-url> --prompt "Camera slowly pushes in toward the cup, steam rising and curling softly" --ratio 16:9 --no-wait
bl video task get --task-id <task-id>
bl video download --task-id <task-id> --out demo.mp4

With --image present, the model switches from text-to-video to image-to-video automatically. --no-wait returns a task ID immediately; poll later, download when SUCCEEDED. (--no-wait and --async are equivalent; --poll-interval only matters in blocking mode — 5s default for generate, 15s for edit.)

Head-to-head test log (Aug 17)

Same scene description, two paths, same day:

Image-to-video (keyframe-driven): 2m 03s submit-to-done. 5s 1080P. Smooth push-in, subject consistent start to finish — usable on the first pass
Text-to-video (no keyframe): 2m 21s. Decent quality, but the model improvised: a saucer, two table lamps, a café interior, wrong table color. For any brief with visual constraints, that's a rejected take and a paid reroll

Nearly identical wall-clock time. The difference isn't speed, it's hit certainty: the keyframe route confines randomness to the image candidates (pickable, near-free), leaving the video step a single variable — whether the motion follows the prompt.

Going vertical? --ratio 9:16, and --size 9:16 on the keyframe. That's it.

The honest ledger

Video calls are priced far above text, and a fresh account's free quota drains fast on video. Flip the guard before you start:

bl usage freetier --all

With it on, generation auto-stops when the free quota is exhausted instead of silently billing. Check your real bill afterwards with bl usage stats — that's the only cost number I'd quote, and the one you should verify on your own account.

Free-quota terms per official docs (the "valid forever" claim going around is wrong): each model has its own quota (on the order of 1M tokens), 90-day validity, Beijing region only, no renewal after expiry, no auto-switching across models. Unit pricing: per-second billing, set by resolution tier (720P/1080P) and duration — I deliberately quote no dollar figure; use the official model page.

Where this route ends

Strongly narrative multi-shot sequences need film-level orchestration — a different route. Single generations are duration-bounded (5s default), so long-form means segments + editing (the generated clips are footage; OpenCut, the 80k+ star open-source CapCut alternative, takes it from there). And copying someone else's work was never on the table — technique out, original content in. Check the model's commercial license terms before client work.

Setup: Node.js 18+, npm install -g bailian-cli, then bl auth login — get an API key in the console; CLI install guide; Model Studio console.

Personal practice log. Commands and timings measured 2026-08-17; cost figures should be verified against your own bl usage stats.

I Stopped Guessing Which LLM to Use — It's One Command and My Own Numbers Now

张洲诚（Zack.ZHANG） — Fri, 14 Aug 2026 11:41:52 +0000

The freelance gig that stalled on question one

Last month I took on a freelance build: a customer-support bot for a DTC store. Three hard constraints — it must understand photos customers upload, sustain ~50k calls a day, and the budget was thin.

The code wasn't the hard part. Question one was: which model.

I opened the model catalog and stared. The Qwen family alone spans flash/plus/max tiers with dated snapshots; below that, a dozen third-party models. Every one has a spec page and a price sheet. None has a row that says "support bot, image input, cost-sensitive."

Benchmarks didn't help — they measure someone else's scenario (long-context recall, competition math). Free-tier roundups are static snapshots that rot in a quarter, and they tell you who has quota, never what your project should run on. Asking a general-purpose LLM was the worst option: it confidently recommended a model I'd never seen in the catalog. I checked. It doesn't exist. Training memory is the wrong tool for a question whose answer is live data.

Context worth naming: OmniRoute, a free MIT-licensed AI gateway, crossed 47k GitHub stars this month — one endpoint, 330+ providers. People clearly want model selection to stop being their job. But a gateway solves "route me to whatever's cheap and alive," not "which model fits this scenario."

The one command

What closed the ticket was a subcommand in Model Studio's CLI, bl. (My previous post was about an agent reading provider docs locally — that solved lookup; this one hands the decision to the terminal. They stand alone.)

npm install -g bailian-cli
bl auth login

Node.js 18+. API key at login — get one in the console; the CLI install guide covers prerequisites.

Then I wrote the client's constraints as one sentence:

bl advisor recommend --message "E-commerce support bot that reads product screenshots uploaded by customers, ~50k calls/day, cost is the priority"

Ten seconds: intent analysis plus three ranked picks. The top one (trimmed from real output):

{
  "model": "qwen3.7-flash-2026-07-15",
  "category": "Cost-optimized",
  "contextWindow": 1000000,
  "reason": "The model is specifically designed for cost-optimized, high-concurrency scenarios ... ideal for handling 50,000 daily API calls under a low budget.",
  "docUrl": "https://help.aliyun.com/document_detail/3016807.html"
}

Every pick carries a docUrl to the official spec-and-pricing page. Treat the ranking as the starting point, then verify against the doc.

How it thinks: three stages

--dry-run runs the first two stages only — intent analysis and candidate recall — skipping the final LLM ranking (and its cost):

{
  "intent": {
    "scenarioHints": ["high-concurrency", "consumer-facing", "low-latency", "cost-sensitive", "image-input", "text-output"],
    "inputModality": ["Image"],
    "budget": "low",
    "qualityPreference": "cost-optimized"
  },
  "candidateCount": 50,
  "candidates": [{ "model": "qwen3.5-27b", "score": 0.509 }, "...50 total"]
}

Plain language becomes structured constraints: "understands screenshots" → inputModality: Image; "~50k calls/day" → high-concurrency. Candidate recall reads live catalog data — that's the honest difference from asking a chatbot, which will invent a plausible-sounding model that doesn't exist.

Change the scenario, change the answer

My partner's contract-review tooling (legal-tech, precision-first, a few dozen contracts a day) got a completely different result from the same command: budget: medium, qualityPreference: flagship, and a top pick of farui-plus — a legal-domain model I'd never heard of, because leaderboard authors don't test vertical-domain legal models.

That's the dividing line: a leaderboard gives every scenario the same answer; scenario-based selection gives each scenario its own.

Your account's real numbers

One prerequisite that will bite you: the usage/quota commands authenticate against the console, not your API key. Key-only auth gets you exactly this (my real output):

{
  "error": {
    "code": 3,
    "message": "No console access token found.",
    "hint": "Run `bl auth login --console` or set DASHSCOPE_ACCESS_TOKEN."
  }
}

Fix: bl auth login --console (coexists with your key). Then:

bl usage free --expiring 30          # quota expiring within 30 days
bl usage stats --days 30 --workspace-id <id>   # real usage distribution
bl quota check --model qwen3.7-flash-2026-07-15  # RPM/TPM headroom

usage stats requires --workspace-id — bl workspace list finds it, or pin it with bl config set workspace_id <id>.

Free-tier traps (checked against the docs)

Quota expires: 30–90 days depending on model, from activation. Doesn't pause, doesn't renew, doesn't roll over. Hence --expiring 30 in your calendar
Per-model quota: typically 1M tokens each, not mergeable. A dated snapshot and the undated latest are separate models with separate quotas
No failover on exhaustion: calls just start billing (on completed accounts). Pin --model in scripts at your own risk — or use the kill switch: bl usage freetier --model <m> --on returns AllocationQuota.FreeTierOnly instead of charging

What it is not

It recommends within Model Studio's catalog — not a cross-vendor comparison. It produces a ranked starting point, not a verdict. Gateways (OmniRoute et al.) solve routing and availability; this solves scenario fit. Stack them if you like — someone still has to fill the gateway's fallback list.

The takeaway

Catalogs and prices shift monthly, so model selection is a recurring decision, not a one-time one. Making it a repeatable command beats being told the right answer once. Entry point: the Model Studio console.

All commands verified against bailian-cli 1.4.2; outputs shown are real runs. Free-tier terms checked against official docs at publication time.

One System Prompt, Five Text Jobs: Compliance Screening, Review Tagging and Contract Extraction from the Terminal

张洲诚（Zack.ZHANG） — Wed, 12 Aug 2026 09:12:13 +0000

The backlog

A friend's small Etsy/Shopify shop got its product page rejected twice for over-claiming — and her keyword-blacklist checker had passed it both times, because those tools match strings, not meaning ("quietest" flags, "quiet-operation benchmark" sails through).

Fixing that led to counting everything else her shop publishes or receives and never reads: 300+ negative reviews sitting in the dashboard, hundreds of pre-sale messages, a 20-page supplier agreement. Pasting any of it into a chatbot produces prose — "customers seem unhappy with shipping" — which answers nothing you can act on. Which issue? How many? Enterprise review-analytics SaaS answers that for four figures a year, which a one-person shop won't pay.

Here's what worked instead: Alibaba Cloud Model Studio's CLI (bl), a system prompt that acts as a JSON schema, and a shell loop. Five kinds of text, one pattern. Show and tell below.

Setup

npm install -g bailian-cli
bl auth login

Node 18+. API key from the Model Studio console — free tier included, and bl usage free shows what's left. Install guide here.

The one command everything else is a variation of

bl text chat --model qwen-turbo --quiet --system "You are a review analyzer. Output JSON only, no extra text. Fields: sentiment(positive/negative/neutral), dimension(quality/shipping/support/price/other), severity(high/medium/low), summary(under 12 words). If undeterminable, use 'unknown' — do not guess." --message "Stopped heating after three days and support took a week to reply."

{"sentiment": "negative", "dimension": "quality", "severity": "high", "summary": "failed in three days, slow support"}

Three schema rules I learned the hard way:

"JSON only, no extra text" — otherwise you get a polite "Sure! Here's the analysis:" prefix and your parser dies
Enumerate the allowed values — otherwise "shipping", "delivery" and "logistics" show up as three different dimensions and your group-by is confetti
"Use 'unknown', don't guess" — otherwise a review that just says "fine" gets a confidently invented label

The loop (this is the whole "batch framework")

mkdir -p out
while IFS= read -r line; do
  bl text chat --model qwen-turbo --quiet --system "You are a review analyzer. Output JSON only. Fields: sentiment, dimension(quality/shipping/support/price/other), severity(high/medium/low), summary(under 12 words). Use 'unknown' if undeterminable." --message "$line" >> out/results.jsonl
done < reviews.txt

300 reviews, ~15 minutes, one JSON per line. Aggregation for small files: feed it back —

bl text chat --system "Input is line-delimited JSON of review analyses. Output a stats table: count by dimension descending, high-severity count per group, one-line summary of top three issues." --message "$(cat out/results.jsonl)"

For thousands of rows, do the counting in jq or a pivot table instead — deterministic math shouldn't run on a probabilistic model.

The result that mattered

Shipping damage: 41 mentions. Product quality: 38. Support: 22. Her gut said quality was the top complaint; the data said shipping damage. She took the "41" to her carrier the next morning. The gap between gut and data is the product here.

Accuracy, honestly: 28/30 on a manual spot check. The two misses were sarcasm — every model's weak spot, not fixed by paying for a bigger one.

Same pattern, different system prompts

Ad compliance pre-check: JSON array of {quote, risk_type, explanation, suggested_rewrite} — caught an implied health claim ("say goodbye to lung-harming fumes") that no keyword blacklist would ever match. It's a self-check aid, not legal advice.
Contract clause extraction: {payment_terms, liability, dispute_resolution} with the load-bearing instruction "quote verbatim, never paraphrase" — paraphrased legal text is subtly wrong legal text.
Support inbox tagging: {intent, keyword} over a few hundred messages; compatibility questions turned out to be half of pre-sale volume, so the compatibility chart moved up the product page.
The inverse case — one long competitor analysis — flips the model strategy: default flagship, --max-tokens 8000 (default 4096 truncates long reports), and "never fabricate figures" in the system prompt.

Cost

bl usage stats --days 7 says the entire evening — 700+ calls — cost pocket change, mostly inside the free tier. The SaaS quote she'd gotten starts at four figures annually.

When not to do this

Forty reviews? Just read them. Can't write down what "high severity" means? The model can't tag it either. Anything with legal weight? This locates and drafts; a human decides.

If you've got a text backlog of your own, start with one review and one command: free tier here.

Curious: has anyone wired this kind of tagging loop into a scheduled job with drift monitoring? That's the part I haven't built yet.

I Installed a Pile of Agent Skills. It Still Couldn't Hand Me a File.

张洲诚（Zack.ZHANG） — Mon, 10 Aug 2026 01:58:09 +0000

The moment that made me look at my setup differently

Last week I needed to ship a post. It needed a cover image with the title rendered into it, plus an audio version for the team channel.

I asked my agent. It gave me a completely reasonable answer: use a design tool for the image, find a TTS service for the voiceover, here are some options you might like.

I had a pile of skills installed at that point. It understood my codebase. It matched my writing style. It could not hand me a single file.

Everything I'd installed was on the input side

If you've been watching GitHub trending, you've seen the same wave I have. In the last week of July, three of the top 20 fastest-growing repos were skills:

graphify — about +4,900 stars that week. Turns your codebase, docs, and PDFs into a queryable knowledge graph. Code parsing runs locally through tree-sitter AST, nothing leaves your machine.
hallmark — about +4,800. Exists purely to strip AI-slop out of design and copy.
i-have-adhd — about +3,270. Stops the agent from burying the answer under three paragraphs of preamble.

Plus find-skills sitting north of 60K subscribers, with half the tutorials now opening with "install this one first."

I lined up what I'd actually installed:

Skill	What it handles	What it produces
graphify	Reads code, docs, PDFs	Graph data + analysis
hallmark	Governs style	Text
i-have-adhd	Governs output structure	Text
find-skills	Finds other skills	A list

Every one either helps the agent understand something, or helps it say things better. Both genuinely useful. Both stop at text.

The moment you need an artifact — a PNG, an MP3, an MP4, text lifted out of a screenshot — there's nothing in the toolset. The agent recommending external tools isn't a cop-out. It has no output path.

The ecosystem has been hot for months and the output side is still close to empty.

Bonus: why some skills never seem to fire

This one bugged me for a while, and the Claude Code docs answer it directly (as of July 2026):

When the agent starts a session, it builds a manifest of every available skill along with its description, then uses the description field to decide whether any skill matches the request.

Two things fall out of that:

1. description is a routing key, not a docstring. The agent isn't reading through your skill files inferring intent — it's matching against descriptions. Skills whose descriptions spell out trigger scenarios and keywords get picked far more reliably. If you write your own skills, that field earns more attention than the body.

2. The manifest is built at session start. Anything installed mid-conversation may be invisible for the rest of it. Restart the session after installing — that's not superstition, it's how the manifest works.

Also worth knowing: Claude Code skills follow the Agent Skills open standard, which applies across multiple AI tools. The mental model transfers when you switch harnesses.

Filling the gap

Alibaba's Model Studio team maintains a skills repo (modelstudioai/skills, Apache-2.0) covering exactly the output side — image, speech, video, vision — all on top of one CLI called bl.

Same install motion you already know:

npx skills add modelstudioai/skills
npx skills add modelstudioai/cli --all -g

Node.js 18+, plus an API key (grab one here, or read the CLI install docs). Restart the session afterward — see above.

What changes: you stop memorizing commands. You describe the outcome, the agent assembles the call.

Cover image with the title rendered in

bl image generate --prompt "Clean technical article cover, dark background, crisp title text centered in frame, smaller subtitle beneath, faint geometric lines and terminal window motifs, flat design, no clutter" --size 16:9 --model qwen-image-2.0-pro --watermark false --out-dir ./covers

Both the title and subtitle landed correctly in the composition, and the terminal motifs showed up as asked. Text is part of the image — no second pass to overlay it.

A behavior worth knowing about: --size accepts a ratio (16:9) or pixels joined by an asterisk (1280*720). Write it the habitual way as 1280x720 and the CLI does not complain locally — run --dry-run --output json and you'll see "size": "1280x720" sitting in the request body, forwarded as-is. If you're scripting this, normalize upstream. Also --watermark defaults to true, so clean output needs it set explicitly.

Text to speech

bl speech synthesize --list-voices --model cosyvoice-v3-flash
bl speech synthesize --text-file ./intro.txt --voice longxiaochun_v3 --rate 0.9 --out ./intro.mp3

You can't invent a voice name — run --list-voices first. The default model returns a couple dozen voices as IDs plus a one-line style note (longxiaochun_v3, longcheng_v3, longtian_v3, …), all bilingual EN/ZH.

Speech rate is --rate (0.5–2.0), not --speed — which is the flag everyone reaches for first, myself included.

Reading a screenshot

bl vision describe --image ./error-screenshot.png --prompt "Transcribe the error message and key stack frames verbatim"

The command is bl vision describe — vision is the group, describe is the subcommand. Local paths work directly; upload happens inside the command.

Video, and one gotcha

bl video generate is async. Pair it with bl video task get and bl video download --task-id <id> --out <path>. Note that --poll-interval defaults differ per command — 5 seconds for video generate, 15 for video edit and video ref. Don't copy one polling value across all of them.

The money part

Output-side calls cost money, and here's the part worth sitting with: the agent decides how many calls to make. Ask for three candidate covers and that's three billable calls. That's a different mental model from text-only skills.

Set the guardrail before you start playing:

bl usage freetier --all          # auto-stop when free quota runs out
bl usage free --expiring 30      # console command — run `bl auth login --console` first
bl usage stats --days 30

Two things to verify rather than assume:

Free tier is not permanent. Validity windows, per-model allocation, and regional eligibility all have specific rules — check the official quota page for your account's region. Third-party "free tier roundup" posts get this wrong often enough that they're not worth trusting.
Quota does not fail over. When one model's allocation is exhausted, nothing routes you to a model that still has budget. You change the model parameter yourself.

Who this is for

Worth it if you're already installing skills and regularly need the agent to produce files — covers, voiceovers, demo clips, text out of screenshots. The flow stays in one place, no shuttling assets between tools.

Skip it if your work lives entirely in code and prose. It'll sit unused and still consume manifest context.

Different tool if you need precise composition control or batch-consistent style — a local ComfyUI node graph wins there, at the cost of a GPU and a workflow to maintain. Not the same problem.

One genuinely useful side note: that repo also maintains a curated index of third-party skills tracked from Anthropic, Vercel, Google Labs and others, flagged for whether the team actually verified them working, grouped into skill management, code, design, docs, video, and testing. If you're in the hunting phase, that list saves time on its own.

Console's here if you want to poke at it.

Closing

The thing this skill wave makes easy to miss: an agent's ceiling is the ceiling of the tools in its hands.

graphify gives it eyes for code structure. hallmark gives it taste. The output side lets it actually hand you the thing. None of them compete — you fill whichever gap is costing you.

Asking for a cover and a voiceover no longer gets me a list of tool recommendations.

Anyone else run into the "installed but never fires" thing? Curious whether the description-matching explanation matches what you've seen.