<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>Open Source on eatmoreduck 多吃鸭&#39;s Blog | AI Tools in Practice and Risk-Control R&amp;D</title>
    <link>https://blog.xiaohuangyu.space/en/tags/open-source/</link>
    <description>Recent content in Open Source on eatmoreduck 多吃鸭&#39;s Blog | AI Tools in Practice and Risk-Control R&amp;D</description>
    <generator>Hugo</generator>
    <language>en</language>
    <lastBuildDate>Tue, 17 Nov 2026 23:59:14 +0800</lastBuildDate>
    <atom:link href="https://blog.xiaohuangyu.space/en/tags/open-source/feed.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>Two Dots That Made Spring Boot Skip an Entire Configuration Tree</title>
      <link>https://blog.xiaohuangyu.space/en/p/spring-boot-configtree-dotdot-en/</link>
      <pubDate>Tue, 17 Nov 2026 20:13:44 +0800</pubDate>
      <guid>https://blog.xiaohuangyu.space/en/p/spring-boot-configtree-dotdot-en/</guid>
      <description>&lt;p&gt;My pull request #52666 was merged into Spring Boot. You can run into the same bug setting up your own project. In my Spring Boot 4.0.9 repro, I put &lt;code&gt;app/&lt;/code&gt; and &lt;code&gt;config/&lt;/code&gt; side by side, ran the program from &lt;code&gt;app/&lt;/code&gt;, and set this one line in &lt;code&gt;application.properties&lt;/code&gt;. &lt;a href=&#34;https://github.com/spring-projects/spring-boot/pull/52666&#34;&gt;Spring Boot PR #52666&lt;/a&gt;&lt;/p&gt;&#xA;&lt;div class=&#34;highlight&#34;&gt;&lt;pre tabindex=&#34;0&#34; class=&#34;chroma&#34;&gt;&lt;code class=&#34;language-properties&#34; data-lang=&#34;properties&#34;&gt;&lt;span class=&#34;line&#34;&gt;&lt;span class=&#34;cl&#34;&gt;&lt;span class=&#34;na&#34;&gt;spring.config.import&lt;/span&gt;&lt;span class=&#34;o&#34;&gt;=&lt;/span&gt;&lt;span class=&#34;s&#34;&gt;configtree:../config/&lt;/span&gt;&#xA;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;The directory existed and the import raised no error, but &lt;code&gt;demo.banner&lt;/code&gt; was missing. I changed the import to an absolute path to the same directory, and the value came back. An application with a fallback value can keep running until you notice it’s doing something unexpected.&lt;/p&gt;</description>
      <content:encoded><![CDATA[<p>My pull request #52666 was merged into Spring Boot. You can run into the same bug setting up your own project. In my Spring Boot 4.0.9 repro, I put <code>app/</code> and <code>config/</code> side by side, ran the program from <code>app/</code>, and set this one line in <code>application.properties</code>. <a href="https://github.com/spring-projects/spring-boot/pull/52666">Spring Boot PR #52666</a></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.config.import</span><span class="o">=</span><span class="s">configtree:../config/</span>
</span></span></code></pre></div><p>The directory existed and the import raised no error, but <code>demo.banner</code> was missing. I changed the import to an absolute path to the same directory, and the value came back. An application with a fallback value can keep running until you notice it’s doing something unexpected.</p>
<h2 id="how-i-found-it">How I found it</h2>
<p>I was reading Spring Boot’s external configuration code to see where it handles unusual paths. In a configuration tree, each file supplies a value and its path supplies the key. A file named <code>demo.banner</code> containing <code>hello-configtree</code> gives you a property named <code>demo.banner</code>. Nested directories become dot-separated parts of the key. <a href="https://docs.spring.io/spring-boot/reference/features/external-config.html#features.external-config.files.configtree">Spring Boot configuration tree documentation</a></p>
<p>I noticed a filter that skipped a file if any path segment started with <code>..</code>. That makes sense for internal entries like Kubernetes’ <code>..data</code>. What caught my eye was that the code passed the full path to the filter. What would happen if the two dots were outside the configuration directory, as in <code>../config/</code>? I reduced the question to one file and two paths to the same directory.</p>
<h2 id="reproduce-the-configtree-bug-on-spring-boot-409">Reproduce the configtree bug on Spring Boot 4.0.9</h2>
<p>I ran this on macOS with JDK 21 and Spring Boot <strong>4.0.9</strong> from Maven Central. The program uses Spring Boot’s Config Data loading path. It doesn’t need a web server.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p configtree-demo/app configtree-demo/config
</span></span><span class="line"><span class="cl"><span class="nb">printf</span> <span class="s1">&#39;%s\n&#39;</span> hello-configtree &gt; configtree-demo/config/demo.banner
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> configtree-demo/app
</span></span></code></pre></div><p>Create <code>pom.xml</code> in <code>app/</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt">&lt;project</span> <span class="na">xmlns=</span><span class="s">&#34;http://maven.apache.org/POM/4.0.0&#34;</span><span class="nt">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&lt;modelVersion&gt;</span>4.0.0<span class="nt">&lt;/modelVersion&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&lt;groupId&gt;</span>example<span class="nt">&lt;/groupId&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&lt;artifactId&gt;</span>configtree-demo<span class="nt">&lt;/artifactId&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&lt;version&gt;</span>1.0.0<span class="nt">&lt;/version&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&lt;dependencies&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&lt;dependency&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&lt;groupId&gt;</span>org.springframework.boot<span class="nt">&lt;/groupId&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&lt;artifactId&gt;</span>spring-boot<span class="nt">&lt;/artifactId&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&lt;version&gt;</span>4.0.9<span class="nt">&lt;/version&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&lt;/dependency&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&lt;/dependencies&gt;</span>
</span></span><span class="line"><span class="cl"><span class="nt">&lt;/project&gt;</span>
</span></span></code></pre></div><p>Then create <code>Demo.java</code> alongside it. The fallback makes it obvious when the property is missing.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span><span class="w"> </span><span class="nn">org.springframework.boot.context.config.ConfigDataEnvironmentPostProcessor</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kn">import</span><span class="w"> </span><span class="nn">org.springframework.core.env.StandardEnvironment</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Demo</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="n">String</span><span class="o">[]</span><span class="w"> </span><span class="n">args</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="kd">var</span><span class="w"> </span><span class="n">env</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">StandardEnvironment</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">ConfigDataEnvironmentPostProcessor</span><span class="p">.</span><span class="na">applyTo</span><span class="p">(</span><span class="n">env</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">System</span><span class="p">.</span><span class="na">out</span><span class="p">.</span><span class="na">println</span><span class="p">(</span><span class="s">&#34;demo.banner=&#34;</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">env</span><span class="p">.</span><span class="na">getProperty</span><span class="p">(</span><span class="s">&#34;demo.banner&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;&lt;missing&gt;&#34;</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Run both imports from <code>app/</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mvn -q dependency:build-classpath -Dmdep.outputFile<span class="o">=</span>classpath.txt
</span></span><span class="line"><span class="cl">javac -cp <span class="s2">&#34;</span><span class="k">$(</span>cat classpath.txt<span class="k">)</span><span class="s2">&#34;</span> Demo.java
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">java -Dspring.config.import<span class="o">=</span>configtree:../config/ <span class="se">\
</span></span></span><span class="line"><span class="cl">  -cp <span class="s2">&#34;.:</span><span class="k">$(</span>cat classpath.txt<span class="k">)</span><span class="s2">&#34;</span> Demo
</span></span><span class="line"><span class="cl"><span class="c1"># demo.banner=&lt;missing&gt;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">java <span class="s2">&#34;-Dspring.config.import=configtree:</span><span class="k">$(</span><span class="nb">cd</span> ../config <span class="o">&amp;&amp;</span> <span class="nb">pwd</span> -P<span class="k">)</span><span class="s2">/&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -cp <span class="s2">&#34;.:</span><span class="k">$(</span>cat classpath.txt<span class="k">)</span><span class="s2">&#34;</span> Demo
</span></span><span class="line"><span class="cl"><span class="c1"># demo.banner=hello-configtree</span>
</span></span></code></pre></div><p>The JVM flag makes the two runs easy to compare. I also tested the <code>application.properties</code> version shown above and got the same result. This non-wildcard import resolves the relative path from the process’s working directory and requires a trailing slash.</p>
<h2 id="where-the-files-went-missing">Where the files went missing</h2>
<p><code>ConfigTreeConfigDataResource</code> calls <code>Paths.get(path).toAbsolutePath()</code>. In this case, that prepends the working directory and leaves the <code>..</code> segment in place. The directory exists, so the loader goes on to create a <code>ConfigTreePropertySource</code>. <a href="https://github.com/spring-projects/spring-boot/blob/5b88a2ad273ea810ae0aa56cf8819bac33521e95/core/spring-boot/src/main/java/org/springframework/boot/context/config/ConfigTreeConfigDataResource.java#L23-L38">Path handling before the fix</a></p>
<p>The old code filters the full path in the <code>Files.find</code> predicate before it makes the path relative to the configuration root. Every visited file has the same <code>app/../config/</code> prefix. Its <code>..</code> segment matches <code>startsWith(&quot;..&quot;)</code>, so every file is skipped. The property source exists, but its property map is empty. <a href="https://github.com/spring-projects/spring-boot/blob/5b88a2ad273ea810ae0aa56cf8819bac33521e95/core/spring-boot/src/main/java/org/springframework/boot/env/ConfigTreePropertySource.java#L200-L247">File discovery before the fix</a></p>
<h2 id="what-changed-upstream">What changed upstream</h2>
<p>The merged code uses the <code>Files.find</code> predicate to select regular files and symbolic links and keeps following links. It then calls <code>sourceDirectory.relativize(path)</code> to get a path within the tree. <code>getName(relativePath)</code> checks for the same two-dot prefix. If a segment inside the tree matches, it returns <code>null</code> and the property isn’t registered. For the example above, it sees <code>demo.banner</code> and registers it. <a href="https://github.com/spring-projects/spring-boot/blob/aff28f4f77acc49c3f7d1bf4725d841a21ddf6e1/core/spring-boot/src/main/java/org/springframework/boot/env/ConfigTreePropertySource.java#L201-L245">Merged implementation</a></p>
<p>I compiled <code>ConfigTreePropertySource</code> from each of the two upstream commits and swapped just that class on the same 4.0.9 classpath. The old class printed <code>&lt;missing&gt;</code> for the relative path, and the merged class printed <code>hello-configtree</code>. I also tested a normally named link, <code>linked.banner</code>, pointing to <code>..data/linked.banner</code>. The merged code read the link’s value and listed only <code>demo.banner</code> and <code>linked.banner</code>, so the internal entry wasn’t registered separately.</p>
<p>The upstream regression test writes a file named <code>a</code>, reaches its directory through <code>&lt;name&gt;/../&lt;name&gt;</code>, and asserts that <code>getPropertyNames()</code> returns exactly <code>a</code>. <a href="https://github.com/spring-projects/spring-boot/blob/aff28f4f77acc49c3f7d1bf4725d841a21ddf6e1/core/spring-boot/src/test/java/org/springframework/boot/env/ConfigTreePropertySourceTests.java#L96-L114">Regression test</a></p>
<p>The fix was merged into <code>4.0.x</code> on November 13, 2026 (China Standard Time). The PR is assigned to the <code>4.0.10</code> milestone. If you hit the issue on your current version, using an absolute import path without <code>..</code> works around it.</p>
<h2 id="come-talk-about-open-source">Come talk about open source</h2>
<p>I’d like to write up the Drools bug involving capitalized annotations next. If you’re reading source code, preparing an upstream PR, or stuck on a reproduction, come talk about it in the WeChat group. <strong>Scan the code to add me on WeChat with “进群” in your friend request</strong>, and I’ll send you an invitation.</p>
<img src="https://www.eatmoreduck.com/assets/wechat-personal-qr.png" alt="Scan to add eatmoreduck on WeChat and request a group invitation" width="220" height="220" loading="lazy">
<p>For more write-ups, you can also follow the <strong>多吃鸭</strong> WeChat public account.</p>
<img src="https://www.eatmoreduck.com/assets/official-account.jpg" alt="QR code for the 多吃鸭 WeChat public account" width="220" height="220" loading="lazy">
<p><a href="https://www.eatmoreduck.com/">eatmoreduck 多吃鸭</a></p>
]]></content:encoded>
    </item>
    <item>
      <title>Why Orca Took Two Months to Support ZCode: The Blocker Was Evidence, Not Code</title>
      <link>https://blog.xiaohuangyu.space/en/p/orca-zcode-harness-two-months-en/</link>
      <pubDate>Mon, 02 Nov 2026 10:40:00 +0800</pubDate>
      <guid>https://blog.xiaohuangyu.space/en/p/orca-zcode-harness-two-months-en/</guid>
      <description>&lt;p&gt;Last week I found a card in Orca&amp;rsquo;s settings: GLM Coding Plan, plan site set to Zhipu BigModel, API key showing Saved, and three usage rows underneath — 5-hour window at 5%, weekly at 92%, MCP monthly at 26%.&lt;/p&gt;&#xA;&lt;p&gt;I paused. Since when did Orca support ZCode as an agent?&lt;/p&gt;&#xA;&lt;p&gt;Following that thread turned out to be more interesting than &amp;ldquo;they added an agent.&amp;rdquo; From the first issue to the release, 63 days passed, and six separate PRs were all closed without merging. What finally landed the work was Z.ai open-sourcing ZCode on September 20.&lt;/p&gt;</description>
      <content:encoded><![CDATA[<p>Last week I found a card in Orca&rsquo;s settings: GLM Coding Plan, plan site set to Zhipu BigModel, API key showing Saved, and three usage rows underneath — 5-hour window at 5%, weekly at 92%, MCP monthly at 26%.</p>
<p>I paused. Since when did Orca support ZCode as an agent?</p>
<p>Following that thread turned out to be more interesting than &ldquo;they added an agent.&rdquo; From the first issue to the release, 63 days passed, and six separate PRs were all closed without merging. What finally landed the work was Z.ai open-sourcing ZCode on September 20.</p>
<p>One note before we start: I wrote about ZCode&rsquo;s privacy problems earlier (the encrypted snapshot thing). This post is only about integration. Two separate questions — whether a tool can be wired into another tool, and whether it uploads your files behind your back.</p>
<h2 id="timeline-two-months-stuck-five-days-after-the-source-dropped">Timeline: two months stuck, five days after the source dropped</h2>
<p>In UTC:</p>
<table>
  <thead>
      <tr>
          <th>When</th>
          <th>What happened</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>July 25</td>
          <td>Issue <a href="https://github.com/stablyai/orca/issues/10564">#10564</a> asks for ZCode as a first-class agent</td>
      </tr>
      <tr>
          <td>July 26</td>
          <td>First PR, #10654, opened</td>
      </tr>
      <tr>
          <td>Mid-August to mid-September</td>
          <td>#13965, #14556, #16227, #16228 all opened and all closed unmerged</td>
      </tr>
      <tr>
          <td>September 20</td>
          <td>One more attempt, #21756</td>
      </tr>
      <tr>
          <td><strong>September 20, later that day</strong></td>
          <td><strong>Z.ai open-sources <a href="https://github.com/zai-org/ZCode">zai-org/ZCode</a> under Apache-2.0</strong></td>
      </tr>
      <tr>
          <td>September 25</td>
          <td>PR <a href="https://github.com/stablyai/orca/pull/22464">#22464</a> merges to main</td>
      </tr>
      <tr>
          <td><strong>September 26, 22:36 UTC</strong></td>
          <td><strong>v1.4.214 ships — ZCode becomes a first-class harness</strong></td>
      </tr>
      <tr>
          <td>September 27</td>
          <td>The site changelog lists &ldquo;ZCode agent harness&rdquo; as the headline of v1.4.215</td>
      </tr>
  </tbody>
</table>
<p>One detail worth noting: v1.4.214 and v1.4.215 are one day apart because 1.4.215 is 1.4.214 plus a single profile fix. The site changelog picked the later number, which is why the &ldquo;official&rdquo; announcement reads September 27.</p>
<p>Follow-ups filled in the rest:</p>
<ul>
<li><strong>v1.4.218</strong>: ZCode session history lands in AI Vault, Coding Plan quota appears in usage</li>
<li><strong>v1.4.221</strong>: you can link a GLM Coding Plan without installing ZCode at all (that is the card in my screenshot)</li>
<li><strong>v1.4.229</strong>: sign-in reuses the existing setup terminal, conversations read in recorded order</li>
<li><strong>v1.4.232</strong>: the GLM key can be stored on a remote host</li>
</ul>
<h2 id="the-real-blocker-evidence-not-code">The real blocker: evidence, not code</h2>
<p>The PR writeup makes it clear that the six earlier attempts died on two things nobody could prove.</p>
<p>The first was <strong>provenance</strong>. Review on #21756 objected that <code>zcode</code> might just be an unofficial third-party client, and labeling it as Z.ai&rsquo;s agent would be inaccurate. Before the source was public, nobody could answer that — you could only point at some binary on someone&rsquo;s machine and say &ldquo;probably fine.&rdquo;</p>
<p>The second was worse: <strong>do the hooks actually fire?</strong></p>
<p>ZCode supports hooks in <code>~/.zcode/cli/config.json</code>, and there was an open bug report (zai-org/feedback#32) saying configured hooks never fired. Orca&rsquo;s whole status system rests on hooks — the sidebar dot, the action-required badge, the completion notification all depend on the agent POSTing lifecycle events. If hooks never fire, wiring ZCode in gives you a panel that permanently reads &ldquo;idle.&rdquo;</p>
<p>Every one of those six PRs built its state machine on the assumption that hooks work. And you cannot code-review an assumption.</p>
<p>Open-sourcing answered both questions at once. Five days later, the PR author put it plainly:</p>
<blockquote>
<p>written against the real source (agent CLI 0.16.9) rather than guessed at.</p>
</blockquote>
<h2 id="six-things-reading-the-source-changed">Six things reading the source changed</h2>
<p>The #22464 writeup lists six findings that changed the implementation after reading the source. This is the most informative part of the whole story — nearly every one of them is a place where somebody had already guessed wrong.</p>
<p><strong>One: ZCode&rsquo;s hook payloads already carry Claude-compatible aliases.</strong></p>
<p>Next to its own camelCase fields, ZCode&rsquo;s hook runner writes a Claude-shaped set: <code>hook_event_name</code>, <code>session_id</code>, <code>tool_name</code>, <code>tool_input</code>, <code>transcript_path</code>, <code>last_assistant_message</code>. The source comments say this is deliberate.</p>
<p>So Orca needed no new parser. ZCode routes through the existing Claude-compatible vendor path and only needs its own identity. That also explains why six PRs kept churning the same code: everyone assumed a separate adapter layer was required. It wasn&rsquo;t.</p>
<p><strong>Two: <code>hooks.enabled</code> defaults to <code>false</code>.</strong></p>
<p>That is the actual cause of &ldquo;configured hooks never fire.&rdquo; Declaring <code>hooks.events</code> isn&rsquo;t enough; the runtime was never switched on. Orca&rsquo;s installer sets the flag, and if a user later turns it back off, the status check reports <code>partial</code> instead of pretending everything is fine.</p>
<p>In short: <strong>nothing was broken. It was never plugged in.</strong></p>
<p><strong>Three: <code>PermissionRequest</code> only fires once the approval card is already on screen.</strong></p>
<p>This one is valuable. The event races the user&rsquo;s answer and can never fire for an auto-approved call — so it&rsquo;s a trustworthy signal that the pane is blocked.</p>
<p>Compare that to agents where the equivalent event fires along several paths and you end up guessing with timeouts.</p>
<p><strong>Four: ZCode&rsquo;s clarification tool is literally <code>AskUserQuestion</code>, with Claude&rsquo;s exact shape.</strong></p>
<p>A <code>questions</code> array, an <code>options</code> array. Orca reuses its existing question card with zero new UI.</p>
<p><strong>Five: it renames its own process to <code>zcode-cli</code>.</strong></p>
<p>So process recognition cannot match the launch command. Without the source, you find this out from users reporting &ldquo;the pane won&rsquo;t detect the agent.&rdquo;</p>
<p><strong>Six: it emits no OSC title at all, and its banner animates forever.</strong></p>
<p>Terminal programs normally write their title with an OSC sequence, and agents use that to decide what&rsquo;s running. ZCode sends none, and repaints its banner continuously.</p>
<p>So readiness can&rsquo;t wait for the screen to go quiet; it waits for the composer box to appear. The PR even keeps a test that pins down the negative result, so nobody re-attempts screen scraping.</p>
<h2 id="local-test-the-desktop-apps-bundled-cli-cant-open-a-tui">Local test: the desktop app&rsquo;s bundled CLI can&rsquo;t open a TUI</h2>
<p>Since I was already in the weeds, I checked my own machine.</p>
<ul>
<li>Orca: <strong>1.4.245</strong></li>
<li>ZCode desktop: <strong>3.17.1</strong></li>
<li><code>zcode</code> on PATH: <strong>none</strong></li>
</ul>
<p>That last one is the point. The ZCode desktop app ships an engine inside the bundle:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs --version
</span></span><span class="line"><span class="cl"><span class="c1"># 0.17.1</span>
</span></span></code></pre></div><p>The version prints. Everything looks fine. Then try to open a session:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs tui
</span></span><span class="line"><span class="cl"><span class="c1"># Error: Cannot find package &#39;@zcode/tui&#39; imported from</span>
</span></span><span class="line"><span class="cl"><span class="c1"># /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs</span>
</span></span></code></pre></div><p>The reason is simple: <strong>the desktop build ships the engine without the text interface</strong>, because it draws its own window and never needs one. Version, <code>doctor</code>, one-shot prompts all work. Only sessions fail — and sessions are exactly what Orca wants.</p>
<p>Orca later added a specific notice for this (PR #22730). It deliberately does not match the &ldquo;TUI requires an interactive terminal&rdquo; message, because that string is localized and Chinese users would never hit the rule; it matches Node&rsquo;s module-resolution error, <code>Cannot find package '@zcode/tui'</code>, which is never translated.</p>
<p>So the official requirement is written plainly in the docs: <strong>install a <code>zcode</code> build with a terminal UI.</strong> A terminal build, not the desktop app.</p>
<h2 id="another-trap-which-file-the-hooks-live-in">Another trap: which file the hooks live in</h2>
<p>Orca&rsquo;s docs say it writes hooks into <code>~/.zcode/cli/config.json</code>. On my machine that file is 565 bytes with no <code>hooks</code> section and no <code>setting.json</code> next to it.</p>
<p>That&rsquo;s expected — I never installed the CLI, so the installer never ran.</p>
<p>But a Windows user&rsquo;s report in the issue is worth remembering: current <code>zcode-app-cli</code> (3.15.x and later) <strong>no longer reads hooks from <code>config.json</code></strong>. That file is now a legacy/migration source; <code>~/.zcode/cli/setting.json</code> is what actually takes effect. He hand-wrote the same hook structure into <code>setting.json</code>, the startup log&rsquo;s <code>hookCount</code> went from 0 to normal, and events started firing.</p>
<p>The same report has three more details:</p>
<ul>
<li><code>zcode login zai</code> completing OAuth is not enough. For <code>account:*</code> providers the CLI additionally requires a Coding Plan API-key credential; with browser auth alone, every turn fails with <code>Model creation failed</code>. You have to run <code>/login</code> in the TUI, pick &ldquo;Z.AI Coding Plan API Key,&rdquo; and paste the key.</li>
<li>With the desktop app running, it periodically rewrites <code>~/.zcode/v2/provider_config.json</code> and clobbers manual model selection. Quit it before configuring the CLI.</li>
<li>ZCode records usage locally in <code>~/.zcode/cli/db/db.sqlite</code>, so Orca can track quota without touching any undocumented billing endpoint.</li>
</ul>
<h2 id="how-to-actually-use-this">How to actually use this</h2>
<p>Two cases. Don&rsquo;t mix them up.</p>
<p><strong>You only want quota and history</strong>: the desktop app is enough. The GLM Coding Plan link added in v1.4.221 is independent — no CLI needed. Save the key and you get the 5-hour, weekly, and MCP usage rows. The 92% in my screenshot came from that path.</p>
<p><strong>You want ZCode running as an agent inside an Orca pane</strong>: install a <code>zcode</code> that has a TUI. The official route is building the command-line distribution from <code>zai-org/ZCode</code> (<code>pnpm build:zcode</code>, which installs to <code>~/.zcode/runtime</code> and links into <code>~/.local/bin</code>). There&rsquo;s also a community <code>zcode-app-cli</code> that extracts the runtime from a pinned desktop release and wraps a TUI around it; people have reported it working on both macOS and Windows in that issue thread.</p>
<p>After installing, check two things: <code>command -v zcode</code> points at the new install, and <code>~/.zcode/cli/setting.json</code> contains all seven events — <code>SessionStart</code>, <code>UserPromptSubmit</code>, <code>PreToolUse</code>, <code>PostToolUse</code>, <code>PostToolUseFailure</code>, <code>PermissionRequest</code>, <code>Stop</code>.</p>
<h2 id="one-last-thing">One last thing</h2>
<p>What gets me about this story isn&rsquo;t &ldquo;another agent got wired up.&rdquo; It&rsquo;s what blocked it for two months.</p>
<p>None of those six PRs were rejected for bad code. They were rejected on <strong>the form of the argument</strong>: you say it should work, but you can&rsquo;t show evidence.</p>
<p>Anyone who maintains an open-source project knows this loop — someone files an issue, someone says &ldquo;works on my machine,&rdquo; and nobody can prove it will work on yours. What moves things is rarely more enthusiasm. It&rsquo;s a source tree someone else can check.</p>
<p>On that note, I checked the quota while writing this. Weekly is at 92%. If you&rsquo;re planning to run anything heavy, wait for next week.</p>
<hr>
<p>References:</p>
<ul>
<li>Orca issue <a href="https://github.com/stablyai/orca/issues/10564">#10564</a>, PRs <a href="https://github.com/stablyai/orca/pull/22464">#22464</a> and <a href="https://github.com/stablyai/orca/pull/22730">#22730</a></li>
<li>Docs: <a href="https://www.onorca.dev/docs/agents/supported">https://www.onorca.dev/docs/agents/supported</a>, <a href="https://www.onorca.dev/docs/agents/usage-tracking">https://www.onorca.dev/docs/agents/usage-tracking</a></li>
<li>Z.ai&rsquo;s open-source repo: <a href="https://github.com/zai-org/ZCode">https://github.com/zai-org/ZCode</a> (Apache-2.0)</li>
</ul>
]]></content:encoded>
    </item>
  </channel>
</rss>
