<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>Blog E</title>
		<description>Attitude is everything</description>
		<link>https://www.evanlin.com/</link>
		<atom:link href="https://www.evanlin.com/feed.xml" rel="self" type="application/rss+xml" />
		
			<item>
				<title>[AI 實戰] 用 Antigravity Remote Agent + 本地 agy 接力重構 LINE 名片助理：Python 改寫 Go + Google ADK + Firestore 實戰與雲地交接限制解析</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/linebot-namecard-python-to-go-arch.jpg&quot; alt=&quot;LINE Bot Namecard: Python (FastAPI) → Go 1.27 + Google ADK + Firestore Architecture&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前情提要&quot;&gt;前情提要&lt;/h1&gt;

&lt;p&gt;這陣子陸續把幾個日常主力服務從 Python 改寫成 Go，這回輪到我平常整理名片的 LINE 機器人：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-python&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-namecard-python&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;這隻機器人過去已經演進了好幾輪：從最初的 &lt;a href=&quot;https://www.evanlin.com/linebot-namecard-qrcode/&quot;&gt;Gemini Vision 辨識 + vCard QR Code 匯入通訊錄&lt;/a&gt;、搬上 &lt;a href=&quot;https://www.evanlin.com/aistudio-to-vertexai/&quot;&gt;Vertex AI 擺脫配額限制&lt;/a&gt;、導入 &lt;a href=&quot;https://www.evanlin.com/namecard-adk/&quot;&gt;Python 版 ADK 動態閉包 Tools&lt;/a&gt;，一路加上 &lt;a href=&quot;https://www.evanlin.com/namecard-structure-output/&quot;&gt;Structured Output 與消歧義清單&lt;/a&gt; 和 &lt;a href=&quot;https://www.evanlin.com/gemini-image-namecard-enhance/&quot;&gt;正反雙面名片合併辨識&lt;/a&gt;。&lt;/p&gt;

&lt;p&gt;但這次重構成 Go 版（&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-namecard-go&lt;/code&gt;&lt;/a&gt;），我想挑戰一個不太一樣的工作流：&lt;strong&gt;先把架構改寫與單元測試丟給 Google Antigravity 的 Remote Agent 在雲端自動跑完，等我回到電腦前，再由本機的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI 接手部署到 Cloud Run 並切換 LINE Webhook。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;實際跑過一輪之後，成果很驚豔——Remote Agent 在雲端 17 分鐘就把整套 Go 1.27 + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk&lt;/code&gt; + Firestore 架構與測試寫完推上 GitHub；但同時也實地驗證了一個非常關鍵的邊界限制：&lt;strong&gt;你可以用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; 呼叫 Remote Agent，卻「無法」把同一個 Remote Agent 對話切換成本地 Agent 繼續。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;這篇文章上半部先把 &lt;strong&gt;Antigravity Remote Agents&lt;/strong&gt; 的用法、雲地隔離原因與兩種實務解法一次講清楚；下半部再完整拆解這次 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-python&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-go&lt;/code&gt; 的系統架構升級與實際交接部署踩坑紀錄。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一認識-antigravity-remote-agents把重活交給雲端隔離-vm&quot;&gt;一、認識 Antigravity Remote Agents：把重活交給雲端隔離 VM&lt;/h1&gt;

&lt;p&gt;依據 Google Antigravity 官方文件（&lt;a href=&quot;https://antigravity.google/docs/remote-agents/&quot;&gt;Remote Agents&lt;/a&gt;），&lt;strong&gt;Remote Agents&lt;/strong&gt; 的核心概念是把自主開發任務從你本機的筆電，搬到 &lt;strong&gt;Google 代管的雲端隔離虛擬機（Cloud Sandbox VM）&lt;/strong&gt; 裡執行。&lt;/p&gt;

&lt;p&gt;這對長時間重構、大範圍測試或跨語言改寫非常有用：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;非同步離線執行&lt;/strong&gt;：任務在雲端 VM 跑，就算你闔上筆電、電腦休眠或斷網，Agent 依然會繼續寫扣、跑測試與改檔案。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;跨裝置監看與解鎖&lt;/strong&gt;：你可以在桌機或 CLI 派工後出門，中途用手機瀏覽器打開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;antigravity.google.com&lt;/code&gt; 看進度、批准權限或補充指令，最後直接拿到一個完整的 GitHub Commit / PR。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;雲端資源掛載（Remote Resources）&lt;/strong&gt;：因為 Agent 跑在雲端隔離沙盒，存取檔案透過三種方式掛載：
    &lt;ol&gt;
      &lt;li&gt;&lt;strong&gt;GitHub Repositories&lt;/strong&gt;：透過 OAuth 授權後自動 clone 並掛載進遠端專案環境。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;Google Drive&lt;/strong&gt;：可直接在對話中讀取 Google Docs、Sheets、Slides、PDF 與資料夾。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;上傳本地檔案&lt;/strong&gt;：直接把檔案傳到遠端專案（單檔上限 8 MiB、每個專案最多 50 檔 / 100 MiB、帳號總上限 2 GiB），檔案會持久掛載在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/home/antigravity/upload&lt;/code&gt;。&lt;/li&gt;
    &lt;/ol&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;1-可以用-agy-cli-呼叫-remote-agent-嗎&quot;&gt;1. 可以用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI 呼叫 Remote Agent 嗎？&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;可以。&lt;/strong&gt; 依據 &lt;a href=&quot;https://antigravity.google/docs/remote-agents/&quot;&gt;Remote Agents 官方文件&lt;/a&gt;，使用前須符合兩個條件：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;CLI 版本&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI &lt;strong&gt;v1.4.12 以上&lt;/strong&gt;（我目前本機執行的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; 為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.5.3&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;帳號資格&lt;/strong&gt;：須登入具備 &lt;strong&gt;Google AI Pro&lt;/strong&gt; 或 &lt;strong&gt;Google AI Ultra&lt;/strong&gt; 訂閱的個人 Google 帳號（&lt;strong&gt;不支援免費版、Google AI Plus，也不支援 Google Workspace / Cloud 企業帳號&lt;/strong&gt;）。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;常用指令如下：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# 啟動遠端對話&lt;/span&gt;
agy &lt;span class=&quot;nt&quot;&gt;--remote-agent&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# 指定既有的遠端專案，或建立全新的遠端專案&lt;/span&gt;
agy &lt;span class=&quot;nt&quot;&gt;--remote-agent&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--project&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;專案名稱或ID&quot;&lt;/span&gt;
agy &lt;span class=&quot;nt&quot;&gt;--remote-agent&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--new-project&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# 接續先前的遠端對話&lt;/span&gt;
agy &lt;span class=&quot;nt&quot;&gt;--remote-agent&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-c&lt;/span&gt;
agy &lt;span class=&quot;nt&quot;&gt;--remote-agent&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--conversation&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&amp;lt;conversation_id&amp;gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;進入遠端對話後，也可以使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/projects&lt;/code&gt; 切換遠端專案，或附加 GitHub repository、Google Drive 檔案與上傳本地檔案。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二關鍵限制為什麼無法把-remote-agent-對話切換成本地-agent-繼續&quot;&gt;二、關鍵限制：為什麼「無法」把 Remote Agent 對話切換成本地 Agent 繼續？&lt;/h1&gt;

&lt;p&gt;很多開發者第一次用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--remote-agent&lt;/code&gt; 時都會有個直覺想法：「&lt;em&gt;我先在雲端用 Remote Agent 把程式碼寫完，回到電腦前再把同一場對話切回本地 Agent，讓它直接用我本機的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 權限幫我部署上線！&lt;/em&gt;」&lt;/p&gt;

&lt;p&gt;實測與對照官方文件後的結論是：&lt;strong&gt;兩者的執行環境與對話紀錄是完全隔離的，無法在同一個對話中從雲端切換回本機接續執行。&lt;/strong&gt; 背後有三個硬性原因：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;會話模式嚴格隔離&lt;/strong&gt;
官方文件明確指出：以 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--remote-agent&lt;/code&gt; 啟動的 CLI &lt;strong&gt;只會開啟遠端對話&lt;/strong&gt;；未帶 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--remote-agent&lt;/code&gt; 的 CLI &lt;strong&gt;只會開啟本地對話&lt;/strong&gt;。兩邊的對話紀錄儲存位置不同（遠端對話存在雲端遠端專案，而非本機磁碟），目前沒有任何指令可以把進行中的遠端會話遷移或接續到本地 Agent。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;環境與檔案系統隔離&lt;/strong&gt;
Remote Agent 跑在 Google 代管的雲端隔離環境，只能操作遠端專案掛載的資源（GitHub repo、Google Drive、上傳到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/home/antigravity/upload&lt;/code&gt; 的檔案），&lt;strong&gt;完全碰不到你本機的資料夾、未提交的本地修改，也無法使用本機安裝的 MCP servers、plugins、skills，或是你本機已經登入好的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kubectl&lt;/code&gt; / SSH 憑證&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;無法透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/fork&lt;/code&gt; 轉移&lt;/strong&gt;
在本地對話中，我們可以用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/fork &amp;lt;project_id&amp;gt;&lt;/code&gt; 把對話分支到另一個專案繼續；但 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/fork&lt;/code&gt; 目前被列入 &lt;strong&gt;Remote Agent 不支援的功能清單&lt;/strong&gt;（同清單還包含 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/diff&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/rewind&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/btw&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--print&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;!&lt;/code&gt; 執行本機指令等），因此也無法把進行中的遠端對話 fork 回本地專案。&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id=&quot;實務上的兩種替代方案&quot;&gt;實務上的兩種替代方案&lt;/h2&gt;

&lt;p&gt;既然無法直接切換同一場對話，實務上可以依照你的工作習慣選擇下面兩條路：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;比較項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;方案 A：Remote Agent + GitHub 交接（本篇實戰）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;方案 B：&lt;a href=&quot;https://antigravity.google/docs/remote-control/&quot;&gt;Remote Control&lt;/a&gt;&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;啟動方式&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy --remote-agent&lt;/code&gt;（或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;antigravity.google.com&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy --remote-control&lt;/code&gt; / 對話內 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/remote-control&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy remote-control start&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Agent 執行位置&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Google 雲端隔離 VM&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;你自己的本機電腦&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;電腦可以關機／休眠嗎？&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;可以&lt;/strong&gt;（雲端繼續跑）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;不行&lt;/strong&gt;（主機必須保持開機與連線）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;可存取本機檔案 / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; / MCP？&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;不行（僅限遠端掛載資源）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;可以&lt;/strong&gt;（原生使用本機完整工具鏈與憑證）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;回到電腦能否接續同一場對話？&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;不行（須改開本地 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; 新對話並 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git pull&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;可以&lt;/strong&gt;（手機或瀏覽器遙控的本來就是本機那場對話）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;最適合的場景&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;出門在外／睡前把大量重構丟給雲端跑，寫完 push 上 GitHub&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;人在外面想遙控家裡電腦跑測試、部署，或需要存取本機私密環境變數與權限&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;想要「離線／關機讓雲端先跑，之後回本機接手開發」 → 透過 GitHub 交接程式碼&lt;/strong&gt;
在遠端專案綁定 GitHub repository，讓 Remote Agent 把修改與交接指南（例如一份 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HANDOFF.md&lt;/code&gt;）commit / push 到遠端分支或開 PR。回到電腦後，在本機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git clone&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git pull&lt;/code&gt; 該分支，再開啟本地 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt;（不加 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--remote-agent&lt;/code&gt;）開新對話接手執行部署。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;想要「人在外面操控、回到電腦無縫接著同一個本地環境與對話跑」 → 改用 &lt;a href=&quot;https://antigravity.google/docs/remote-control/&quot;&gt;Remote Control&lt;/a&gt;&lt;/strong&gt;
一開始就執行本地 Agent，並透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy --remote-control&lt;/code&gt;、對話中輸入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/remote-control&lt;/code&gt;，或是使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy remote-control start&lt;/code&gt; 常駐背景服務。這樣 Agent 本身一直跑在你自己的電腦上，你可以透過手機或瀏覽器（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;antigravity.google.com&lt;/code&gt;）遠端監看與下指令，回到電腦前就能直接在同一場本地對話無縫繼續。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;這次重構 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-go&lt;/code&gt;，我走的就是 &lt;strong&gt;方案 A&lt;/strong&gt;：讓雲端 Remote Agent 專心把整個 Go 專案與交接文件寫完推上 GitHub，再由本機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI 接下第二棒完成 Cloud Run 部署與 LINE Webhook 切換。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三先看架構對照linebot-namecard-python-vs-linebot-namecard-go&quot;&gt;三、先看架構對照：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-python&lt;/code&gt; vs. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-go&lt;/code&gt;&lt;/h1&gt;

&lt;p&gt;在進入實作細節前，先把這次從 &lt;strong&gt;Python + FastAPI&lt;/strong&gt; 遷移到 &lt;strong&gt;Go 1.27 + Google ADK + Cloud Firestore&lt;/strong&gt; 的架構差異攤在一張表上看清楚：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;比較項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;原 Python 版（&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-python&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-python&lt;/code&gt;&lt;/a&gt;）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;新 Go 版（&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-namecard-go&lt;/code&gt;&lt;/a&gt;）&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;語言與 Web 框架&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Python + FastAPI + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AsyncLineBotApi&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aiohttp&lt;/code&gt;)&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Go 1.27.3&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/server&lt;/code&gt;) + 標準庫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;net/http&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line-bot-sdk-go/v8&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;容器基礎映像檔&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Python Image（含 Pillow 等相依套件）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Multi-stage &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang:1.27-bookworm&lt;/code&gt; → &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcr.io/distroless/static-debian12&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;ADK Agent &amp;amp; Runner 生命週期&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;每次收到訊息&lt;/strong&gt;才在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;handle_smart_query&lt;/code&gt; 裡動態重建閉包、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Agent&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Runner&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;伺服器啟動時單例常駐&lt;/strong&gt;共用的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.New&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.New&lt;/code&gt;，搭配 5 個強型別 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;functiontool&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;ADK Session &amp;amp; Memory 記憶&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;每次請求 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;new&lt;/code&gt; 一個臨時 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InMemorySessionService()&lt;/code&gt;（&lt;strong&gt;請求結束就忘記&lt;/strong&gt;，沒有跨對話記憶）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;雙層共通記憶體 + Cloud Firestore 持久化&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FirestoreSessionService&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_sessions&lt;/code&gt;，支援冷啟動 Hydrate）+ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FirestoreMemoryService&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_memories&lt;/code&gt;）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;多步驟互動狀態 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UserState&lt;/code&gt;)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;全域 Python &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dict&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;user_states = {}&lt;/code&gt;），容器重啟或多實例立即遺失&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UserStateStore&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sync.RWMutex&lt;/code&gt; 記憶體快取 + Firestore &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;user_states&lt;/code&gt; 集合 + 300 秒 TTL 自動清理 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SweepExpiredStates&lt;/code&gt;）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;名片資料庫策略&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;僅支援 Firebase Realtime Database (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;namecard/{user_id}&lt;/code&gt;)&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;雙資料庫相容 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CardRepository&lt;/code&gt;)&lt;/strong&gt;：同時支援讀寫既有 Firebase RTDB 與 Cloud Firestore (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;namecards/{user_id}/cards/{card_id}&lt;/code&gt;)，舊名片零搬遷直接相容&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Gemini Vision OCR&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-genai&lt;/code&gt; (Python) + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NAMECARD_SCHEMA&lt;/code&gt; + Pillow&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/genai&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BackendVertexAI&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt;) + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NamecardSchema()&lt;/code&gt; + Go 標準庫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;image/jpeg&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;部署與回退機制&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;手動 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run deploy&lt;/code&gt;、手動貼 Webhook URL&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一鍵腳本 &lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/scripts/deploy_and_switch_webhook.sh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scripts/deploy_and_switch_webhook.sh&lt;/code&gt;&lt;/a&gt; 自動複製環境變數、切換並測試 LINE Webhook，支援 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--rollback&lt;/code&gt; 秒退&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四第一棒雲端-remote-agent17-分鐘完成改寫與交接設計&quot;&gt;四、第一棒（雲端 Remote Agent）：17 分鐘完成改寫與交接設計&lt;/h1&gt;

&lt;p&gt;從 GitHub 的 Commit 紀錄看這次雲端 Remote Agent 的節奏，真的只能用「兇猛」形容：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;16:21&lt;/code&gt;：建立空的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-namecard-go&lt;/code&gt;（Initial commit）&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;16:38&lt;/code&gt;：&lt;strong&gt;僅花 17 分鐘&lt;/strong&gt;，一口氣提交 22 個檔案、&lt;strong&gt;4,432 行&lt;/strong&gt; Go 程式碼、完整單元測試、&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/ROADMAP.md&quot;&gt;ROADMAP.md&lt;/a&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dockerfile&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;16:45&lt;/code&gt;：補上部署與 LINE Webhook 切換腳本 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scripts/deploy_and_switch_webhook.sh&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;16:56&lt;/code&gt;：寫好專給本機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI 接手的 &lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/HANDOFF.md&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HANDOFF.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;除了把功能 100% 移植過來之外，Remote Agent 這次幫我們順手修掉了 Python 版留下來的三個架構債務：&lt;/p&gt;

&lt;h2 id=&quot;1-終結-python-版每問一句就失憶firestoresessionservice--firestorememoryservice&quot;&gt;1. 終結 Python 版「每問一句就失憶」：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FirestoreSessionService&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FirestoreMemoryService&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;回頭看舊版 Python 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app/line_handlers.py&lt;/code&gt;，當時為了快速串接 ADK，寫法其實長這樣：&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# ❌ 舊版 Python 寫法：每次收到訊息都重建一個全新的 InMemorySessionService
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;runner&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Runner&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;app_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;namecard_bot_app&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;session_service&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;InMemorySessionService&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這導致一個很明顯的問題：&lt;strong&gt;使用者問完「幫我找王大明」，下一句追問「那他的電話是多少？」時，Agent 根本不記得上一輪在找誰&lt;/strong&gt;（因為上一個請求結束時 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InMemorySessionService&lt;/code&gt; 就被垃圾回收了）。&lt;/p&gt;

&lt;p&gt;到了 Go 版 &lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/internal/memory/memory.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/memory/memory.go&lt;/code&gt;&lt;/a&gt;，我們實作了官方 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk/session.Service&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;memory.Service&lt;/code&gt; 介面，打造出&lt;strong&gt;雙層共通記憶體 + Cloud Firestore 持久化&lt;/strong&gt;架構：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;熱路徑讀寫記憶體&lt;/strong&gt;：平時讀寫直接命中 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;session.InMemoryService()&lt;/code&gt;，維持毫秒級延遲。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;異動同步寫入 Firestore&lt;/strong&gt;：每次 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Create&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppendEvent&lt;/code&gt; 後，會把對話事件與 State 同步存入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_sessions&lt;/code&gt; 集合；每輪結束後再由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FirestoreMemoryService&lt;/code&gt; 將摘要同步至 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_memories&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;冷啟動自動還原（Hydration）&lt;/strong&gt;：當 Cloud Run 縮到 0 重新冷啟動、記憶體是空的，只要 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Get&lt;/code&gt; 沒命中記憶體，就會自動呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;hydrateFromFirestoreIfNeeded&lt;/code&gt; 從 Firestore 把歷史對話與 State 拉回來重建，真正做到跨對話、跨冷啟動的連續追問。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;測試友善設計&lt;/strong&gt;：當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DocumentStore&lt;/code&gt; 為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nil&lt;/code&gt;（例如本機跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test&lt;/code&gt; 沒有連雲端）時，自動純跑記憶體模式，不需任何 Mock Server 就能測完整流程。&lt;/li&gt;
&lt;/ul&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;// internal/memory/memory.go：冷啟動時自動從 Firestore 還原 ADK Session&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;s&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;FirestoreSessionService&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;req&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;GetRequest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;GetResponse&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mu&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Lock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;defer&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mu&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Unlock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

	&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;inMemory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;c&quot;&gt;// 記憶體未命中（例如 Cloud Run 冷啟動），嘗試從 Firestore adk_sessions 還原&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;hydrateFromFirestoreIfNeeded&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AppName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;UserID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SessionID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;inMemory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;2-互動狀態機-userstatestore記憶體快取--firestore--300-秒-ttl-清理&quot;&gt;2. 互動狀態機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UserStateStore&lt;/code&gt;：記憶體快取 + Firestore + 300 秒 TTL 清理&lt;/h2&gt;

&lt;p&gt;名片機器人有很多「跨回合狀態」，例如：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;傳完正面照片後等待確認「這張名片還有背面嗎？」（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pending_backside_confirm&lt;/code&gt;）與等待上傳背面（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;awaiting_backside_image&lt;/code&gt;，含正面圖片 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FrontImageBytes&lt;/code&gt;）&lt;/li&gt;
  &lt;li&gt;點擊按鈕後準備輸入備忘錄（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adding_memo&lt;/code&gt;）或修改特定欄位（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;editing_field&lt;/code&gt;）&lt;/li&gt;
  &lt;li&gt;AI 工具觸發修改前的安全確認（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pending_update&lt;/code&gt;）&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;在 Python 版這些全部塞在全域 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;user_states = {}&lt;/code&gt; 字典裡；Go 版 &lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/internal/memory/memory.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UserStateStore&lt;/code&gt;&lt;/a&gt; 改用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sync.RWMutex&lt;/code&gt; 保護的記憶體快取搭配 Firestore &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;user_states&lt;/code&gt; 集合，並在每次 Webhook 進入時觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SweepExpiredStates&lt;/code&gt;，自動清除超過 300 秒未完成的正面圖片暫存。&lt;/p&gt;

&lt;h2 id=&quot;3-從每次建閉包升級為常駐單例-adk-runner--5-個強型別-functiontool&quot;&gt;3. 從「每次建閉包」升級為「常駐單例 ADK Runner + 5 個強型別 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;functiontool&lt;/code&gt;」&lt;/h2&gt;

&lt;p&gt;Python 版為了隔離不同 LINE 使用者的名片資料，每次收到文字訊息都要重新呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;make_adk_tools(user_id, found_card_ids)&lt;/code&gt; 產生 5 個閉包函式再包進新 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Agent&lt;/code&gt;。&lt;/p&gt;

&lt;p&gt;在 Go 版 &lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/internal/agent/agent.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/agent/agent.go&lt;/code&gt;&lt;/a&gt; 中，我們在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main.go&lt;/code&gt; 啟動時只建立&lt;strong&gt;一組常駐共用的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.New&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt;）與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.New&lt;/code&gt;&lt;/strong&gt;，並註冊 5 個強型別 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;functiontool&lt;/code&gt;：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_all_namecards&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_namecard_by_id&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;display_namecard&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update_namecard_memo&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update_namecard_field&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;工具執行時直接透過 ADK 傳入的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adkagent.ToolContext&lt;/code&gt; 取得 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tctx.UserID()&lt;/code&gt; 隔離不同使用者資料，同時在 Vertex AI 或網路異常時自動觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FallbackKeywordSearch&lt;/code&gt; 本機關鍵字備援搜尋。&lt;/p&gt;

&lt;h2 id=&quot;4-雙資料庫相容-cardrepository--強制-google_cloud_locationglobal&quot;&gt;4. 雙資料庫相容 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CardRepository&lt;/code&gt; + 強制 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION=global&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;為了確保舊使用者的名片在切換當下不會消失，&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/internal/storage/storage.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/storage/storage.go&lt;/code&gt;&lt;/a&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StoreRepository&lt;/code&gt; 同時支援 &lt;strong&gt;Firebase Realtime Database (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;namecard/{user_id}&lt;/code&gt;)&lt;/strong&gt; 與 &lt;strong&gt;Cloud Firestore (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;namecards/{user_id}/cards/{card_id}&lt;/code&gt;)&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;查詢時優先相容既有 Firebase RTDB 資料，並支援讀取 Firestore；新增與修改時同步寫入兩邊。&lt;/li&gt;
  &lt;li&gt;並在 &lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/internal/config/config.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/config/config.go&lt;/code&gt;&lt;/a&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Load()&lt;/code&gt; 第一行強制寫死 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_ = os.Setenv(&quot;GOOGLE_CLOUD_LOCATION&quot;, &quot;global&quot;)&lt;/code&gt;，避免從舊服務複製過來的區域變數蓋掉 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt; 所需的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global&lt;/code&gt; 端點。&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;5-雲地交接的精髓讓-remote-agent-寫好可直接貼給本地-agy-的交接書&quot;&gt;5. 雲地交接的精髓：讓 Remote Agent 寫好「可直接貼給本地 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; 的交接書」&lt;/h2&gt;

&lt;p&gt;因為 Remote Agent 很清楚自己身處雲端沙盒、沒有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 與 LINE API 權限，它在最後一個 Commit 主動產出了兩樣關鍵交接物：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/scripts/deploy_and_switch_webhook.sh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scripts/deploy_and_switch_webhook.sh&lt;/code&gt;&lt;/a&gt;：自動化撈取舊服務環境變數、部署 Cloud Run、檢查 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /&lt;/code&gt; Health Check、呼叫 LINE Messaging API 更新並測試 Webhook（還附帶 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--rollback&lt;/code&gt; 參數）。&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go/blob/main/HANDOFF.md&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HANDOFF.md&lt;/code&gt;&lt;/a&gt;：整理好已完成進度、待驗證的 GCP 權限，以及一段&lt;strong&gt;可以直接複製貼給本機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI 的啟動 Prompt&lt;/strong&gt;。&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五第二棒本機-agy-cli接手交接檔排查暗坑與零停機上線&quot;&gt;五、第二棒（本機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI）：接手交接檔、排查暗坑與零停機上線&lt;/h1&gt;

&lt;p&gt;回到電腦前，我開啟本機的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI（沒有加 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--remote-agent&lt;/code&gt;，走本地 Agent 模式），把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HANDOFF.md&lt;/code&gt; 的交接 Prompt 直接貼進去。本地 Agent 接手後依序完成驗證、部署與切換，過程中也抓出幾個「只有在本機看真實 GCP 環境才會發現的細節」：&lt;/p&gt;

&lt;h2 id=&quot;細節-1舊服務其實沒設-google_application_credentials_json而是走預設服務帳戶-adc&quot;&gt;細節 1：舊服務其實沒設 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_APPLICATION_CREDENTIALS_JSON&lt;/code&gt;，而是走預設服務帳戶 ADC&lt;/h2&gt;

&lt;p&gt;交接文件原本假設要從舊服務撈取 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_APPLICATION_CREDENTIALS_JSON&lt;/code&gt;，但本機 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; 用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services describe &amp;lt;OLD_CLOUD_RUN_SERVICE&amp;gt;&lt;/code&gt; 實查線上設定後，發現環境變數清單長這樣：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ChannelAccessToken&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ChannelSecret&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIREBASE_URL&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIREBASE_STORAGE_BUCKET&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PROJECT_ID: &amp;lt;YOUR_GCP_PROJECT_ID&amp;gt;&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LOCATION: global&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_PROJECT: &amp;lt;YOUR_GCP_PROJECT_ID&amp;gt;&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION: &amp;lt;YOUR_GCP_REGION&amp;gt;&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_GENAI_USE_VERTEXAI: True&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;舊服務完全沒有塞 JSON Key，而是直接使用 Cloud Run 執行服務帳戶 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;PROJECT_NUMBER&amp;gt;-compute@developer.gserviceaccount.com&lt;/code&gt; 的 &lt;strong&gt;Application Default Credentials (ADC)&lt;/strong&gt;！我們進一步檢查該服務帳戶的 IAM 角色，確認已經具備 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/datastore.user&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/aiplatform.user&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/firebase.admin&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/storage.admin&lt;/code&gt;，而且 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(default)&lt;/code&gt; Firestore（Native 模式，位於同區域）也早已建立完成。&lt;/p&gt;

&lt;p&gt;另外，注意到舊服務環境變數裡同時帶著 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION: &amp;lt;YOUR_GCP_REGION&amp;gt;&lt;/code&gt;&lt;/strong&gt;，這如果在其他沒處理的程式裡很容易讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt; 找不到模型；幸好前一步 Go 版的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;config.Load()&lt;/code&gt; 會在啟動時強制把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION&lt;/code&gt; 覆寫為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global&lt;/code&gt;，剛好完美接住這個潛在坑！&lt;/p&gt;

&lt;h2 id=&quot;細節-2macos-mktemp-的後綴陷阱--舊-webhook-其實躲在-firebase-hosting-後面&quot;&gt;細節 2：macOS &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp&lt;/code&gt; 的後綴陷阱 &amp;amp; 舊 Webhook 其實躲在 Firebase Hosting 後面&lt;/h2&gt;

&lt;p&gt;在執行部署腳本前檢查了兩件事：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;macOS BSD &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp&lt;/code&gt; 行為差異&lt;/strong&gt;：腳本第 46 行寫了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp /tmp/cloudrun_env.XXXXXX.yaml&lt;/code&gt;。在 Linux GNU &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp&lt;/code&gt; 可以這樣用，但在 macOS 的 BSD &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp&lt;/code&gt; 下，&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;XXXXXX&lt;/code&gt; 後面只要接了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.yaml&lt;/code&gt; 副檔名，就不會被替換成隨機字元&lt;/strong&gt;，而是固定產出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tmp/cloudrun_env.XXXXXX.yaml&lt;/code&gt;。雖然這支腳本有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trap &apos;rm -f &quot;${ENV_FILE}&quot;&apos; EXIT&lt;/code&gt; 會清掉暫存檔不影響本次執行，但未來寫跨平台腳本建議改用無後綴的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp /tmp/cloudrun_env.XXXXXX&lt;/code&gt; 或由 Python &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tempfile.NamedTemporaryFile&lt;/code&gt; 處理。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;切換前先查 LINE 目前真正的 Webhook Endpoint&lt;/strong&gt;：用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET https://api.line.me/v2/bot/channel/webhook/endpoint&lt;/code&gt; 一查，發現原本的 Webhook 並不是直接指到舊版 Python Cloud Run 服務的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.run.app&lt;/code&gt; 網址，而是指在 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&amp;lt;YOUR_FIREBASE_APP&amp;gt;.firebaseapp.com&lt;/code&gt;&lt;/strong&gt;（透過 Firebase Hosting rewrite 轉給 Python Cloud Run），且狀態為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;active&quot;: true&lt;/code&gt;。先查清楚原貌，之後萬一需要復原就能心裡有底（而腳本的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--rollback&lt;/code&gt; 則會切回舊版 Python Cloud Run 的直連 URL）。&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id=&quot;細節-3一鍵-cloud-build-部署-golang127-bookworm-與-webhook-切換實測&quot;&gt;細節 3：一鍵 Cloud Build 部署 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang:1.27-bookworm&lt;/code&gt; 與 Webhook 切換實測&lt;/h2&gt;

&lt;p&gt;在本機執行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;./scripts/deploy_and_switch_webhook.sh&lt;/code&gt; 後：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;環境變數匯出&lt;/strong&gt;：自動從舊版 Python Cloud Run 服務匯出所有設定至暫存 YAML。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Cloud Build 編譯與部署&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dockerfile&lt;/code&gt; 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FROM golang:1.27-bookworm AS builder&lt;/code&gt; 在 Cloud Build 上順利拉取並靜態編譯（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CGO_ENABLED=0 GOOS=linux&lt;/code&gt;）打包進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcr.io/distroless/static-debian12&lt;/code&gt;，成功建立新版 Go Cloud Run 服務（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100%&lt;/code&gt; 流量已切換至新 revision）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Health Check 與 LINE API 驗證&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET https://&amp;lt;YOUR_CLOUD_RUN_SERVICE_URL&amp;gt;/&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&quot;status&quot;:&quot;ok&quot;}&lt;/code&gt;&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PUT /v2/bot/channel/webhook/endpoint&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{}&lt;/code&gt;&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /v2/bot/channel/webhook/test&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&quot;success&quot;:true,&quot;statusCode&quot;:200,&quot;reason&quot;:&quot;OK&quot;,&quot;detail&quot;:&quot;200&quot;}&lt;/code&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;最後再看一次 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services logs read&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud logging read&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;2026-11-08T09:08:26.864683Z  2026/11/08 09:08:26 Cloud Firestore &amp;amp; Firebase Admin SDK initialized successfully.
2026-11-08T09:08:26.868408Z  2026/11/08 09:08:26 Starting LINE Bot Namecard Go + ADK server on port 8080...
2026-11-08T09:08:26.879115Z  Default STARTUP TCP probe succeeded after 1 attempt for container &quot;&amp;lt;NEW_CLOUD_RUN_SERVICE&amp;gt;-1&quot; on port 8080.
2026-11-08T09:08:29.410974Z  INFO GET 200
2026-11-08T09:08:30.147730Z  INFO POST 200
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;一氣呵成，完全零報錯！現在直接在 LINE 聊天室傳訊息或名片照片，打到的就是這台 Go + ADK + Firestore 機器人。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;六remote-agent-雲地接力與無痛遷移檢查清單checklist&quot;&gt;六、Remote Agent 雲地接力與無痛遷移檢查清單（Checklist）&lt;/h1&gt;

&lt;p&gt;如果你也想用 &lt;strong&gt;Antigravity Remote Agent + 本地 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy&lt;/code&gt; CLI&lt;/strong&gt; 來重構並切換線上服務，照著這份清單走可以少走很多冤枉路：&lt;/p&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;1. 先選對遠端工作模式&lt;/strong&gt;：想讓電腦關機／出門讓 AI 自己重構並發 PR，用 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy --remote-agent&lt;/code&gt;&lt;/strong&gt;（需 Google AI Pro / Ultra 個人帳號、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy &amp;gt;= 1.4.12&lt;/code&gt;）；想隨時從手機遙控本機跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 部署或沿用同一場對話，改用 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agy --remote-control&lt;/code&gt;&lt;/strong&gt;。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;2. 別指望直接切換同一場對話&lt;/strong&gt;：Remote Agent 與本地 Agent 的對話、檔案系統與工具鏈完全隔離，且不支援 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/fork&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/diff&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/rewind&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/btw&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--print&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;!&lt;/code&gt; 本機指令；一開始就把&lt;strong&gt;「GitHub + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HANDOFF.md&lt;/code&gt;」&lt;/strong&gt;當成標準交接介面。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;3. 讓 Remote Agent 產出可執行的交接 Prompt 與部署腳本&lt;/strong&gt;：在請雲端收尾時，要求它把測試指令、環境需求、一鍵部署腳本（含 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--rollback&lt;/code&gt;）與「貼給下一棒本地 Agent 的 Prompt」一併寫進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HANDOFF.md&lt;/code&gt;。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;4. 接手後先查 IAM、Firestore 與區域變數&lt;/strong&gt;：別盲目假設舊服務有設 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_APPLICATION_CREDENTIALS_JSON&lt;/code&gt;，先用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services describe&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud projects get-iam-policy&lt;/code&gt; 確認預設服務帳戶是否已有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/datastore.user&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/aiplatform.user&lt;/code&gt;；若模型用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt; 等 preview 模型，務必確認程式有處理 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION=global&lt;/code&gt;。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;5. 注意跨平台腳本與原 Webhook 路徑&lt;/strong&gt;：在 macOS 上跑自動化腳本時留意 BSD &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mktemp&lt;/code&gt; 不支援模板後綴隨機化；切換 LINE Webhook 前先呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /v2/bot/channel/webhook/endpoint&lt;/code&gt; 記錄原本端點（是否經過 Firebase Hosting 或 API Gateway），確保驗證與退回都有依據。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;完整 Go 版程式碼、雙層共通記憶體實作與部署腳本皆已開源在 GitHub：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-namecard-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，原本的 Python 版亦保留在 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-namecard-python&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-namecard-python&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 供架構對照，歡迎參考與交流！&lt;/p&gt;
</description>
				<pubDate>Sun, 08 Nov 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/antigravity-remote-agent-linebot-namecard-go/</link>
				<guid isPermaLink="true">https://www.evanlin.com/antigravity-remote-agent-linebot-namecard-go/</guid>
			</item>
		
			<item>
				<title>[AI 實戰] 把 LINE 研究 Bot 從 Go ADK 搬到 DeepSeek Harness（DSH）：搬遷對照與踩坑全紀錄</title>
				<description>&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    subgraph BEFORE[&quot;Before：Go + ADK for Go（一個 container）&quot;]
        direction TB
        B_HOOK[&quot;LINE Webhook / Cloud Tasks&quot;] --&amp;gt; B_WK[&quot;worker（Go）&quot;]
        B_WK --&amp;gt;|&quot;runner.Run()&amp;lt;br/&amp;gt;同一個行程&quot;| B_ADK[&quot;ADK llmagent × 3&amp;lt;br/&amp;gt;OutputSchema&amp;lt;br/&amp;gt;Session State&quot;]
        B_ADK --&amp;gt;|&quot;GoogleSearch + url_context&quot;| B_GM[&quot;Vertex AI&amp;lt;br/&amp;gt;Gemini&quot;]
    end

    subgraph AFTER[&quot;After：TypeScript + DeepSeek Harness（app + sidecar）&quot;]
        direction TB
        A_HOOK[&quot;LINE Webhook / Cloud Tasks&quot;] --&amp;gt; A_WK[&quot;worker（TypeScript）&quot;]
        A_WK --&amp;gt;|&quot;dsh-sdk-client&amp;lt;br/&amp;gt;stdio JSON-RPC&quot;| A_DSH[&quot;dsh runtime 子程序&amp;lt;br/&amp;gt;sdk-minimal + patch&amp;lt;br/&amp;gt;submit_* / web_research 工具&quot;]
        A_DSH --&amp;gt;|&quot;Anthropic /v1/messages&quot;| A_LL[&quot;LiteLLM sidecar&quot;]
        A_LL --&amp;gt; A_GM[&quot;Vertex AI&amp;lt;br/&amp;gt;Gemini&quot;]
        A_DSH --&amp;gt;|&quot;web_research：&amp;lt;br/&amp;gt;googleSearch + urlContext&quot;| A_GM
    end

    BEFORE ==&amp;gt;|&quot;只換 Agent 層&amp;lt;br/&amp;gt;LINE / Firestore / GCS / Cloud Tasks 不變&quot;| AFTER
&lt;/code&gt;&lt;/pre&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt; &lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Before（ADK for Go）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;After（DeepSeek Harness）&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 跑在哪&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;同一個 Go 行程&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;每個 stage 一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh&lt;/code&gt; 子程序&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;怎麼接 Gemini&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;直連 Vertex AI&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DSH（Messages 協定）→ LiteLLM sidecar → Vertex AI&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;結構化輸出&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_*&lt;/code&gt; 工具 + 讀 session 事件&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Google Search&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;ADK 內建 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;geminitool&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;自寫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt; 工具&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Cloud Run&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;1 個 container&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;2 個 container（app + LiteLLM），一樣可以縮到 0&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h1 id=&quot;前情提要&quot;&gt;前情提要&lt;/h1&gt;

&lt;p&gt;在 &lt;a href=&quot;https://www.evanlin.com/line-research-bot-python-to-go-adk/&quot;&gt;前前篇&lt;/a&gt; 裡，我把 LINE 研究規劃師 Bot 從 Python + Managed Agents 改寫成 &lt;strong&gt;Go + &lt;a href=&quot;https://github.com/google/adk-go&quot;&gt;ADK for Go&lt;/a&gt;&lt;/strong&gt;，也就是 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;玩法沒變：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;在 LINE 傳「&lt;strong&gt;研究 SOTA 開源向量資料庫的選型&lt;/strong&gt;」，Bot 依序跑 &lt;strong&gt;PLAN → SEARCH_COMPARE → WRITE_REPORT&lt;/strong&gt; 三個階段，最後丟一張有摘要、主要來源與「閱讀完整報告」按鈕的 Flex 卡片。&lt;/li&gt;
  &lt;li&gt;再傳「&lt;strong&gt;第 2 章再深一點，加日文來源&lt;/strong&gt;」，同一份報告深化、版本號 +1，舊版存成 snapshot。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;a href=&quot;https://www.evanlin.com/deepseek-harness-vs-google-harness2/&quot;&gt;上一篇&lt;/a&gt; 介紹了 DeepSeek 開源的 &lt;strong&gt;&lt;a href=&quot;https://www.deepseek.com/en/harness/&quot;&gt;DeepSeek Harness（DSH）&lt;/a&gt;&lt;/strong&gt;，也就是 &lt;strong&gt;&lt;a href=&quot;https://github.com/deepseek-ai/dsh-superagent-prototype&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deepseek-ai/dsh-superagent-prototype&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 底下的那套執行環境，並跟 Google Research Harness² 做了比較。這篇要做的是：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;strong&gt;LINE Bot 功能跟 Cloud Run 設定都沿用原本的，只把 Agent 框架從 ADK 換成 DSH。&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;先講結論：&lt;strong&gt;做得到，而且已經在線上跑了&lt;/strong&gt;，但做法跟我一開始想的不一樣。這篇分四塊：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;可行性評估&lt;/strong&gt;：為什麼沒有直接 fork dsh-superagent。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;怎麼從 ADK 搬過去&lt;/strong&gt;：概念對照與實際程式碼。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;會遇到哪些問題&lt;/strong&gt;：我實際踩到的坑，整理成清單。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;部署與切換&lt;/strong&gt;：沿用原本服務的設定，切 LINE webhook。&lt;/li&gt;
&lt;/ol&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Repo&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;內容&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;搬遷前：Go 1.27 + ADK for Go v1.9.0&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-dsh&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;這篇的主角：TypeScript（Node 24）+ DeepSeek Harness 0.2.1-rc.5，目前 LINE webhook 指向的就是這份&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;30-秒複習-dsh&quot;&gt;30 秒複習 DSH&lt;/h2&gt;

&lt;p&gt;完整的框架圖跟說明在&lt;a href=&quot;https://www.evanlin.com/deepseek-harness-vs-google-harness2/&quot;&gt;上一篇&lt;/a&gt;，這裡只列出跟搬遷直接相關的四件事：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Agent 跑在另一個行程裡&lt;/strong&gt;：spawn 一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh&lt;/code&gt; runtime 子程序，用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/dsh-sdk-client&lt;/code&gt; 透過 &lt;strong&gt;stdio JSON-RPC&lt;/strong&gt; 驅動。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;模型層只講 Anthropic Messages 協定&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseURL&lt;/code&gt; 可以換，但對面一定要是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/v1/messages&lt;/code&gt; 相容端點，沒有 Gemini 介接層。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;一切都是 Cordis 外掛&lt;/strong&gt;：用 Profile（bundle + YAML patch）組裝，工具用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;defineTool()&lt;/code&gt; 註冊，參數 schema 由 DSH 驗證。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Session 是事件流&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run()&lt;/code&gt; 回傳 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/call&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/result&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;turn/end&lt;/code&gt; 等事件，結構化結果與除錯都靠它。&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一可行性評估為什麼我沒有直接-fork-dsh-superagent&quot;&gt;一、可行性評估：為什麼我沒有直接 fork dsh-superagent&lt;/h1&gt;

&lt;p&gt;一開始的直覺是：fork dsh-superagent、加一個 LINE Source、部署到 Cloud Run。實際翻完文件跟程式碼之後，發現它跟 Cloud Run 的假設幾乎完全相反：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;dsh-superagent&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;原本的 Cloud Run 架構&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;執行模型&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;一個長駐行程&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scripts/dsh-superagent start&lt;/code&gt; 用 tmux 跑起來）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;無狀態、會縮到 0&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;狀態&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stateDir&lt;/code&gt; 底下的 &lt;strong&gt;SQLite&lt;/strong&gt; + lock 檔&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Firestore&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;事件來源&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;主動 polling&lt;/strong&gt; GitHub 通知、Feishu 長連線&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LINE &lt;strong&gt;Webhook 推進來&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;HTTP&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;管理 API &lt;strong&gt;只聽 127.0.0.1&lt;/strong&gt;，還有同源檢查&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;必須對外公開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/webhook&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;必要設定&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;一定要有 GitHub repo 與 agent 帳號&lt;/strong&gt;，否則 runtime 停在「等待設定」&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;只有 LINE Channel&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 權限&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;danger-full-access&lt;/code&gt;，以 OS 使用者身分跑 shell&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;只需要上網查資料&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;模型&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Anthropic Messages（DeepSeek）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Vertex AI Gemini&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;如果硬要 fork，得做這幾件事：拿掉 GitHub 的強制設定、自己開一個驗簽的公開 webhook、Cloud Run 固定 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;min = max = 1&lt;/code&gt; 常駐，再掛 Filestore 放 SQLite。&lt;strong&gt;等於放棄 scale-to-zero，還把一個 alpha 版、可以跑任意 shell 的行程直接放上網路。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;所以我在兩個方案之間做了選擇：&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;方案 A：Fork dsh-superagent，加 LINE Source。&lt;/strong&gt; 保留 Eval / Ticket / 面板，但成本最高、最脆弱。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;方案 B：保留 Cloud Run 架構，只把 Agent 層換成 DSH。&lt;/strong&gt; ✅ 採用。LINE webhook、Cloud Tasks、Firestore、GCS 都不動，三個研究 stage 各跑一個 DSH Session。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;模型的部分，我選擇&lt;strong&gt;繼續用 Vertex AI 上的 Gemini&lt;/strong&gt;，中間放一個 LiteLLM 當翻譯。這個決定的影響在第二節講。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;💡 &lt;strong&gt;心得&lt;/strong&gt;：「把框架 A 換成框架 B」之前，先分清楚你要換的是&lt;strong&gt;執行環境（harness）&lt;/strong&gt;還是&lt;strong&gt;上面那個應用（superagent）&lt;/strong&gt;。這次我要的其實是前者。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二從-adk-搬到-dsh架構與對照&quot;&gt;二、從 ADK 搬到 DSH：架構與對照&lt;/h1&gt;

&lt;h2 id=&quot;搬遷後的架構&quot;&gt;搬遷後的架構&lt;/h2&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    LINE[&quot;LINE App&quot;] --&amp;gt;|&quot;POST /webhook (HMAC)&quot;| WH[&quot;server.ts&amp;lt;br/&amp;gt;意圖分類 + 取鎖&quot;]
    WH --&amp;gt;|enqueue| CT[(&quot;Cloud Tasks&amp;lt;br/&amp;gt;research-jobs&quot;)]
    CT --&amp;gt;|&quot;POST /tasks/run-research (OIDC)&quot;| WK[&quot;worker.ts&quot;]
    WK --&amp;gt;|&quot;seed / save&quot;| FS[(&quot;Firestore&amp;lt;br/&amp;gt;line_bot_workspaces&quot;)]
    WK --&amp;gt;|&quot;每個 stage spawn&quot;| DSH[&quot;dsh runtime&amp;lt;br/&amp;gt;sdk-minimal + research.patch.yml&quot;]
    DSH --&amp;gt;|&quot;Anthropic /v1/messages&quot;| LL[&quot;LiteLLM sidecar&amp;lt;br/&amp;gt;localhost:4000&quot;]
    LL --&amp;gt; GM[&quot;Vertex AI&amp;lt;br/&amp;gt;gemini-3.8-flash&quot;]
    DSH --&amp;gt;|&quot;web_research 工具&quot;| GS[&quot;Gemini + Google Search&amp;lt;br/&amp;gt;+ URL Context&quot;]
    WK --&amp;gt;|&quot;marked → HTML&quot;| GCS[(&quot;Cloud Storage&quot;)]
    WK --&amp;gt;|&quot;Push 進度 + Flex&quot;| LINE
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;Cloud Run 上是&lt;strong&gt;一個服務、兩個 container&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app&lt;/code&gt;（ingress）加上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;litellm&lt;/code&gt; sidecar，彼此用 localhost 溝通。服務一樣可以縮到 0。&lt;/p&gt;

&lt;h2 id=&quot;adk--dsh-對照表&quot;&gt;ADK → DSH 對照表&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;概念&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;ADK for Go（Go 版）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;DeepSeek Harness（這篇）&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Agent 執行位置&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;同一個行程，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Run()&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;每個 stage spawn 一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh&lt;/code&gt; runtime 子程序，用 stdio JSON-RPC 驅動&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Agent 定義&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.New(...)&lt;/code&gt; × 3&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一個 profile（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sdk-minimal&lt;/code&gt; + patch）+ persona，stage 指示放在 user message&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;模型&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini.NewModel&lt;/code&gt; 直連 Vertex AI&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DSH Messages 介接層 → &lt;strong&gt;LiteLLM sidecar&lt;/strong&gt; → Vertex AI Gemini&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Google Search / URL Context&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;geminitool.GoogleSearch{}&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;url_context&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;自寫外掛工具 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt;&lt;/strong&gt;（Gemini + googleSearch + urlContext）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;結構化輸出&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt;（自動注入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;set_model_response&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;自寫 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_plan&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_sources&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_report&lt;/code&gt;&lt;/strong&gt; 工具，從 session 事件讀回參數&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Stage 間交接&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Session State &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{plan}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{sources}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{report_md?}&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Firestore workspace，直接填進 stage prompt&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;追蹤 ID&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;ADK &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvocationID&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DSH &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sessionId&lt;/code&gt;（一樣存在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;last_interaction_id&lt;/code&gt;）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;工具權限&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;只給需要的工具&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;patch 關掉 bash、editor、working-directory，只剩研究工具&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;語言&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Go 1.27&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;TypeScript（Node 24 直接跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.ts&lt;/code&gt;，不需 build）&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;LINE 那一側，也就是意圖分類、Flex 卡片、Firestore 文件格式、GCS 路徑、Cloud Tasks 流程、deepen / retry，都是從 Go &lt;strong&gt;1:1 移植&lt;/strong&gt;的，連訊息文字都一樣。所以這次真正的重點只有 Agent 層的四個改寫。&lt;/p&gt;

&lt;h2 id=&quot;改寫-1runnerrun--deepseekharnessrun&quot;&gt;改寫 1：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Run()&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DeepSeekHarness.run()&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;ADK 是在行程裡跑 Agent；DSH 則是每個 stage 起一個 runtime，跑完就關（&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh/blob/main/src/research/agents.ts&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;src/research/agents.ts&lt;/code&gt;&lt;/a&gt;）：&lt;/p&gt;

&lt;div class=&quot;language-ts highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;harness&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;DeepSeekHarness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;profile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;sdk-minimal&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;patches&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;patch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;                 &lt;span class=&quot;c1&quot;&gt;// 啟動時 render 好的 research.patch.yml&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;dshHome&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;this&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;opts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;dshHome&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;       &lt;span class=&quot;c1&quot;&gt;// Cloud Run 上是 /tmp/dsh-home&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;cwd&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;workdir&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;                     &lt;span class=&quot;c1&quot;&gt;// 每個 stage 一個空的暫存目錄&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;provider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;deepseek-official&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;// 走 llm-deepseek 介接層&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;this&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;opts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;           &lt;span class=&quot;c1&quot;&gt;// gemini-3.8-flash，LiteLLM 認得的別名&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;maxTokens&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;32&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;_000&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;env&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;runtimeEnv&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;process&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;env&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;     &lt;span class=&quot;c1&quot;&gt;// 拿掉 LINE secrets&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;DEEPSEEK_BASE_URL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;this&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;opts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;llmBaseURL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;// http://127.0.0.1:4000&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;DEEPSEEK_API_KEY&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;this&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;opts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;llmApiKey&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;     &lt;span class=&quot;c1&quot;&gt;// LiteLLM master key&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;DSH_SYSTEM_PROMPT&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;PERSONA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;try&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;result&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;run&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;stagePrompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;assertTurnCompleted&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;events&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;extractSubmission&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;events&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;submit_plan&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;finally&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;close&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;provider: &apos;deepseek-official&apos;&lt;/code&gt; 看起來很怪：明明是 Gemini，怎麼寫 DeepSeek？因為這只是 &lt;strong&gt;DSH 介接層的路由名稱&lt;/strong&gt;，代表「走 Messages 協定那條路」。真正打去哪裡，由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DEEPSEEK_BASE_URL&lt;/code&gt; 決定，而它指向 LiteLLM。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;SDK 沒有「中途取消」&lt;/strong&gt;。timeout 的做法是把 runtime &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;close()&lt;/code&gt; 掉。我用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AbortSignal&lt;/code&gt; 接上這件事，每個 stage 一樣有 3 / 10 / 8 分鐘的上限。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;改寫-2outputschema--submit_-工具&quot;&gt;改寫 2：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_*&lt;/code&gt; 工具&lt;/h2&gt;

&lt;p&gt;ADK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; 很方便，DSH 沒有對應的東西。但仔細想，ADK 本來就是「自動注入一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;set_model_response&lt;/code&gt; 工具」，所以&lt;strong&gt;我自己做一樣的事&lt;/strong&gt;：&lt;/p&gt;

&lt;div class=&quot;language-js highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;// dsh/plugin/index.js：一個 Cordis 外掛&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;line-research-tools&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;inject&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;kd&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;apply&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;register&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;defineTool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;submit_plan&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;Submit the research plan. Call exactly once when the plan is final.&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;parameters&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;topic&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;queries&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;array&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;items&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;object&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;additionalProperties&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;na&quot;&gt;properties&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;q&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;source_category&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
                      &lt;span class=&quot;na&quot;&gt;lang&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;source_count&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;integer&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;output&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;ack&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;execute&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;received&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}))&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;DSH 會先&lt;strong&gt;用 schema 驗證參數&lt;/strong&gt;，驗不過就以錯誤回給模型，讓它自己修正再呼叫一次。Host 端只要從 session 事件裡找「最後一次沒有被拒絕的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_plan&lt;/code&gt; 呼叫」（&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh/blob/main/src/research/submission.ts&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;src/research/submission.ts&lt;/code&gt;&lt;/a&gt;）：&lt;/p&gt;

&lt;div class=&quot;language-ts highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;of&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;events&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;type&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;tool/call&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;tool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;calls&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;set&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;callId&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;arguments&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;type&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;tool/result&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;message&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;isError&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;failed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;kd&quot;&gt;set&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;message&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;toolCallId&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;accepted&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[...&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;calls&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;filter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(([&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;])&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&amp;gt;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;failed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;has&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這樣做還有一個附帶好處：前前篇提到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chapter_not_found_chapter_not_found&lt;/code&gt; 那種模型亂回 enum 的情況，在這裡 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;enum&lt;/code&gt; 由 DSH 在工具層就擋下來了&lt;/strong&gt;，模型會被要求重送。&lt;/p&gt;

&lt;h2 id=&quot;改寫-3litellm-sidecar讓-dsh-接上-gemini&quot;&gt;改寫 3：LiteLLM sidecar，讓 DSH 接上 Gemini&lt;/h2&gt;

&lt;p&gt;DSH 只會講 Anthropic Messages，Vertex AI 的 Gemini 不會。中間放一個 &lt;strong&gt;&lt;a href=&quot;https://github.com/BerriAI/litellm&quot;&gt;LiteLLM&lt;/a&gt;&lt;/strong&gt; 剛好：它對外開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/v1/messages&lt;/code&gt;，對內用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;vertex_ai/gemini-3.8-flash&lt;/code&gt;，認證直接吃 Cloud Run 的 Service Account（ADC）。&lt;/p&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;na&quot;&gt;model_list&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;model_name&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;gemini-3.8-flash&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;litellm_params&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;vertex_ai/gemini-3.8-flash&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;vertex_project&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&amp;lt;your-project&amp;gt;&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;vertex_location&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;global&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;litellm_settings&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;drop_params&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;true&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;general_settings&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;master_key&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;os.environ/LITELLM_MASTER_KEY&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Cloud Run 的多 container 用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;service.yaml&lt;/code&gt; 宣告，加一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;container-dependencies&lt;/code&gt; 讓 app 等 LiteLLM 起來再啟動：&lt;/p&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;na&quot;&gt;annotations&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;run.googleapis.com/container-dependencies&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;{&quot;app&quot;:[&quot;litellm&quot;]}&apos;&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;containers&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;app&lt;/span&gt;          &lt;span class=&quot;c1&quot;&gt;# ingress，port 8080&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;litellm&lt;/span&gt;      &lt;span class=&quot;c1&quot;&gt;# sidecar，port 4000，startupProbe: /health/liveliness&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;改寫-4web_research-工具保住-google-search-grounding&quot;&gt;改寫 4：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt; 工具，保住 Google Search grounding&lt;/h2&gt;

&lt;p&gt;這是我最在意的一塊。ADK 版的品質很大一部分來自 &lt;strong&gt;Google Search + URL Context grounding&lt;/strong&gt;。但走 LiteLLM 的 Messages 翻譯之後，這些 Gemini 專屬工具基本上就沒了。&lt;/p&gt;

&lt;p&gt;解法是&lt;strong&gt;不要讓 grounding 經過翻譯層&lt;/strong&gt;：寫一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt; 工具，在工具裡直接用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@google/genai&lt;/code&gt; 打 Vertex AI，開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;googleSearch&lt;/code&gt; 跟 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;urlContext&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-js highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;res&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;ai&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;models&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;generateContent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;researchModel&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;contents&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;googleSearch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;urlContext&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}],&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;abortSignal&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;exec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;signal&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;// groundingChunks 的網址是 vertexaisearch 轉址，HEAD 一次拿到真實網址&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;於是變成「&lt;strong&gt;Gemini（經 DSH）負責思考與規劃，Gemini（經工具）負責上網查資料&lt;/strong&gt;」。DSH 會讓模型平行呼叫多次 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt;（工具標了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;isConcurrencySafe&lt;/code&gt;），搜尋階段比我預期的快。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三會遇到的問題踩坑清單&quot;&gt;三、會遇到的問題：踩坑清單&lt;/h1&gt;

&lt;p&gt;下面這些都是這次&lt;strong&gt;實際踩到&lt;/strong&gt;的。DSH 目前是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.2.1-rc.5&lt;/code&gt;，很多行為文件沒寫，或寫的是舊版。&lt;/p&gt;

&lt;h2 id=&quot;坑-1sdk-參數改名舊參數被靜默忽略&quot;&gt;坑 1：SDK 參數改名，舊參數被「靜默忽略」&lt;/h2&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/dsh-sdk-client&lt;/code&gt; 的 README 範例是這樣寫的：&lt;/p&gt;

&lt;div class=&quot;language-ts highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;DeepSeekHarness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;launch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;command&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;node&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;args&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;lib/bin.js&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;cordis.yml&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;...&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;照抄之後一切看起來都正常，模型也回話了，但我請它列出自己的工具時，冒出一堆 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bash&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;subagent&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create_goal&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_search&lt;/code&gt;……&lt;strong&gt;我的 patch 完全沒生效&lt;/strong&gt;。翻 SDK 原始碼才發現 rc.5 早就改成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;profile&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;patches&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dshHome&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;env&lt;/code&gt;：&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;launch&lt;/code&gt; 不會報錯，只會被忽略，然後默默用功能全開的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sdk&lt;/code&gt; profile&lt;/strong&gt;。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;✅ &lt;strong&gt;驗證方法&lt;/strong&gt;：從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;request/header&lt;/code&gt; 事件把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tools[].name&lt;/code&gt; 印出來，確認模型實際拿到的工具清單。我修好之後只剩 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;read_image, web_research, submit_*&lt;/code&gt;。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;坑-2外掛名稱是從-dsh_homeprofilesprofile-解析的&quot;&gt;坑 2：外掛名稱是從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;$DSH_HOME/profiles/&amp;lt;profile&amp;gt;/&lt;/code&gt; 解析的&lt;/h2&gt;

&lt;p&gt;PoC 一切正常，正式的整合測試卻失敗：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;AgentError: every submit_plan call was rejected: Error: unknown tool &quot;submit_plan&quot;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;直接起 runtime 看 stderr 才找到原因：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;line-research-tools: failed to import: Cannot find package &apos;line-research-tools&apos;
imported from /tmp/.../profiles/sdk-minimal/
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;DSH 是從 profile 目錄往上找 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;node_modules&lt;/code&gt; 來解析外掛的&lt;/strong&gt;。PoC 時 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_HOME&lt;/code&gt; 剛好放在專案目錄底下，才「碰巧」找得到；Cloud Run 上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_HOME=/tmp/dsh-home&lt;/code&gt;，一定會壞。&lt;/p&gt;

&lt;p&gt;接著想用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;name: !!js process.env.XXX&lt;/code&gt; 動態給路徑，又被擋：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;disabling profile plugin row &quot;line-research-tools&quot;: its declared dsh requirements cannot be validated: name.startsWith is not a function
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;name&lt;/code&gt; 會在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;!!js&lt;/code&gt; 求值之前就被檢查，必須是字面字串&lt;/strong&gt;。最後的做法是：啟動時把 patch 模板 render 一份到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_HOME&lt;/code&gt;，把外掛的&lt;strong&gt;絕對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;file://&lt;/code&gt; URL&lt;/strong&gt; 寫死進去。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;💡 這是整次搬遷最值得記住的一坑：&lt;strong&gt;PoC 的環境跟正式環境差一個目錄，結果就完全不同&lt;/strong&gt;。整合測試一定要用跟正式環境一樣的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_HOME&lt;/code&gt; 位置。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;坑-3apikeyenv-在-patch-裡改了沒用&quot;&gt;坑 3：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apiKeyEnv&lt;/code&gt; 在 patch 裡改了沒用&lt;/h2&gt;

&lt;p&gt;我在 patch 裡把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llm-deepseek&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apiKeyEnv&lt;/code&gt; 改成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LITELLM_API_KEY&lt;/code&gt;，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--dump-config&lt;/code&gt; 也顯示改成功了，但執行時還是報：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;MISSING_CREDENTIAL: no API key for provider route &quot;deepseek-official&quot;; ... export DEEPSEEK_API_KEY
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;最後直接用 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DEEPSEEK_API_KEY&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DEEPSEEK_BASE_URL&lt;/code&gt; 環境變數&lt;/strong&gt;餵 LiteLLM 的 key 跟網址就好了。另外，patch 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;config&lt;/code&gt; 是&lt;strong&gt;整段取代&lt;/strong&gt;，不是合併，所以原本的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;defaultContextWindow&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;streamIdleTimeoutMs&lt;/code&gt; 要自己補回去。&lt;/p&gt;

&lt;h2 id=&quot;坑-4不同-profile-不能共用同一個-sessions-目錄&quot;&gt;坑 4：不同 profile 不能共用同一個 sessions 目錄&lt;/h2&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;session artifact &quot;.../session.v4.jsonl.zstd&quot; uses .jsonl.zstd, but this backend is configured for compression &quot;none&quot;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sdk&lt;/code&gt; profile 會壓縮 session（zstd），&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sdk-minimal&lt;/code&gt; 不壓縮。&lt;strong&gt;同一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_HOME&lt;/code&gt; 先後跑過兩種 profile，就會互相讀到對方的檔案&lt;/strong&gt;。正式環境只跑一種 profile 沒事，但本機實驗時要記得清 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;$DSH_HOME/sessions&lt;/code&gt;。&lt;/p&gt;

&lt;h2 id=&quot;坑-5node-型別剝除不支援-constructor-參數屬性&quot;&gt;坑 5：Node 型別剝除不支援 constructor 參數屬性&lt;/h2&gt;

&lt;p&gt;Node 24 可以直接 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;node src/main.ts&lt;/code&gt;，不用 build，很爽。但它只做「&lt;strong&gt;可擦除語法&lt;/strong&gt;」的型別剝除，下面這種寫法會直接失敗：&lt;/p&gt;

&lt;div class=&quot;language-ts highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;constructor&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;private&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;readonly&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;store&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;Store&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;// ❌ TS1294&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tsconfig.json&lt;/code&gt; 開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;erasableSyntaxOnly: true&lt;/code&gt;，讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tsc&lt;/code&gt; 提早抓出來。另外，&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;node_modules&lt;/code&gt; 底下的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.ts&lt;/code&gt; 不會被剝除型別&lt;/strong&gt;，所以 DSH 外掛要寫成純 JS。&lt;/p&gt;

&lt;h2 id=&quot;坑-6npx-node24-不會真的用-node-24&quot;&gt;坑 6：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;npx node@24&lt;/code&gt; 不會真的用 Node 24&lt;/h2&gt;

&lt;p&gt;想確認容器上的 Node 24 跑得動，結果 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;npx node@24 --version&lt;/code&gt; 印出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;v26.0.0&lt;/code&gt;：npx 還是用 PATH 上的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;node&lt;/code&gt;。最後是直接從 nodejs.org 抓 Node 24 的 tarball（記得對 SHASUMS256）來跑測試，順便確認 DSH runtime 在 Node 24 上啟動沒有錯誤。&lt;/p&gt;

&lt;h2 id=&quot;坑-7litellm-要自己補-vertex-ai-的相依套件&quot;&gt;坑 7：LiteLLM 要自己補 Vertex AI 的相依套件&lt;/h2&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pip install &apos;litellm[proxy]&apos;&lt;/code&gt; 起來之後，第一個請求就是：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;litellm.APIConnectionError: No module named &apos;google&apos;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Vertex AI 路徑需要 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-auth&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-cloud-aiplatform&lt;/code&gt;&lt;/strong&gt;，image 裡要自己加，版本也要鎖死（我用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;litellm 1.106.6&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-auth 2.62.1&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-cloud-aiplatform 2.7.0&lt;/code&gt;）。另外新版 LiteLLM &lt;strong&gt;沒有 master key 會拒絕啟動&lt;/strong&gt;，而且沒帶 key 的請求回的是 &lt;strong&gt;500 不是 401&lt;/strong&gt;（缺 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prisma&lt;/code&gt;），雖然一樣會被擋下來。好在 sidecar 只在 instance 內部聽 localhost，外面打不到。&lt;/p&gt;

&lt;h2 id=&quot;坑-8agent-子程序不需要你的-secrets&quot;&gt;坑 8：Agent 子程序不需要你的 secrets&lt;/h2&gt;

&lt;p&gt;DSH runtime 預設繼承整個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;process.env&lt;/code&gt;，等於 &lt;strong&gt;LINE Channel Secret / Access Token 都進到 Agent 的行程裡&lt;/strong&gt;。雖然我已經關掉 shell 工具，還是寫了一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runtimeEnv()&lt;/code&gt; 把它們拿掉，並加了單元測試。這跟 dsh-superagent 文件裡講的一樣：&lt;strong&gt;wrapper 和目錄只是預設值，不是安全邊界&lt;/strong&gt;，能不給就不給。&lt;/p&gt;

&lt;h2 id=&quot;坑-9速度比-adk-版慢&quot;&gt;坑 9：速度比 ADK 版慢&lt;/h2&gt;

&lt;p&gt;整合測試（規劃 → 搜尋 → 撰寫 → 深化找不到章節）跑了 &lt;strong&gt;約 7.5 分鐘&lt;/strong&gt;，ADK 版大約是 150～190 秒。原因包括：每個 stage 多一次 runtime 啟動（約 1～2 秒）、多一層 LiteLLM、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt; 被呼叫很多次。都還在 Cloud Tasks 30 分鐘的 dispatch deadline 內，但 stage timeout 我從 ADK 版的 3 / 8 / 6 分鐘放寬到 3 / 10 / 8 分鐘。&lt;/p&gt;

&lt;h2 id=&quot;坑-10pre-release-依賴一定要鎖版本&quot;&gt;坑 10：Pre-release 依賴一定要鎖版本&lt;/h2&gt;

&lt;p&gt;DSH 在 npm 上同時有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;latest&lt;/code&gt;（0.0.1-rc.1 或 0.1.x）、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;next&lt;/code&gt;（0.2.1-rc.5）、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;alpha&lt;/code&gt;（0.2.2-alpha.3）三條線，而且&lt;strong&gt;各套件的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;latest&lt;/code&gt; 指的版本不一樣&lt;/strong&gt;。坑 1 的 SDK 參數改名就是這樣來的。我全部鎖在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;next&lt;/code&gt; 那條線：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/dsh&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh-sdk-client&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh-tools&lt;/code&gt; 都是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.2.1-rc.5&lt;/code&gt;。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四部署與切換沿用原本服務的環境變數&quot;&gt;四、部署與切換：沿用原本服務的環境變數&lt;/h1&gt;

&lt;p&gt;部署方式跟 Go 版那篇不同：這次是&lt;strong&gt;新開一個 Cloud Run 服務&lt;/strong&gt;，因為多了 sidecar，container 結構不一樣。但設定全部沿用原本的服務：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;先 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;describe&lt;/code&gt; 原服務&lt;/strong&gt;：拿到 Service Account、bucket、queue、LINE secrets 的 Secret Manager 綁定。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;新服務直接沿用&lt;/strong&gt;：同一個 SA、同一個 bucket、同一個 queue、同一組 LINE secrets，&lt;strong&gt;Firestore 用同一組 collections&lt;/strong&gt;。這樣切過去之後，使用者既有的報告可以直接「深化」。唯一新增的 secret 是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LITELLM_MASTER_KEY&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Cloud Build 建兩個 image&lt;/strong&gt;（我的筆電一樣沒有 Docker），用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services replace service.yaml&lt;/code&gt; 部署。&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CLOUD_RUN_SERVICE_URL&lt;/code&gt; 用 Cloud Run 固定的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&amp;lt;service&amp;gt;-&amp;lt;專案編號&amp;gt;.&amp;lt;region&amp;gt;.run.app&lt;/code&gt; 格式先算好，不用部署兩次。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;冒煙測試&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/readyz&lt;/code&gt; 200、錯誤簽章 401、沒帶 OIDC token 401、用真的 Channel Secret 簽章 200，兩個 container 的 startup probe 都通過。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;用 LINE API 切 webhook&lt;/strong&gt;，一樣不開 Console：&lt;/li&gt;
&lt;/ol&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;TOKEN&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;$(&lt;/span&gt;gcloud secrets versions access latest &lt;span class=&quot;nt&quot;&gt;--secret&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;LINE_CHANNEL_ACCESS_TOKEN&lt;span class=&quot;si&quot;&gt;)&lt;/span&gt;
curl &lt;span class=&quot;nt&quot;&gt;-s&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-X&lt;/span&gt; PUT &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;Authorization: Bearer &lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$TOKEN&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;Content-Type: application/json&apos;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;-d&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;{&quot;endpoint&quot;:&quot;&amp;lt;NEW_SERVICE_URL&amp;gt;/webhook&quot;}&apos;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  https://api.line.me/v2/bot/channel/webhook/endpoint
curl &lt;span class=&quot;nt&quot;&gt;-s&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-X&lt;/span&gt; POST &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;Authorization: Bearer &lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$TOKEN&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;Content-Type: application/json&apos;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-d&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;{}&apos;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  https://api.line.me/v2/bot/channel/webhook/test
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;用 log 確認流量真的過來了&lt;/strong&gt;：切換後新服務收到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineBotWebhook/2.0&lt;/code&gt; 的請求，舊服務歸零。接著第一個真實使用者的研究任務在新服務上從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;job start&lt;/code&gt; 跑到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;job done&lt;/code&gt;，&lt;strong&gt;約 6 分 43 秒&lt;/strong&gt;，中間沒有任何錯誤。Gemini 的呼叫經過 LiteLLM sidecar 全部回 200，GCS 上多了一份約 29 KB 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;index.html&lt;/code&gt; 報告。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;回滾只要把 webhook 改回原服務的網址，&lt;strong&gt;兩邊共用 Firestore，來回切換不會遺失資料&lt;/strong&gt;。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五adk--dsh-搬遷自我檢查清單checklist&quot;&gt;五、ADK → DSH 搬遷自我檢查清單（Checklist）&lt;/h1&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;1. 先分清楚要換的是 harness 還是上面的 app&lt;/strong&gt;：dsh-superagent 是 GitHub coding agent，Cloud Run 上的聊天 Bot 要的是 DSH 本身。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;2. 先做 PoC，而且用正式環境的目錄結構&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_HOME&lt;/code&gt; 放在專案外面（例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tmp&lt;/code&gt;），才測得出外掛解析問題。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;3. 印出模型實際拿到的工具清單&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;request/header&lt;/code&gt; 事件），確認 patch 有生效、危險工具真的關掉了。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;4. SDK 參數照型別定義寫，不要照 README&lt;/strong&gt;：rc 版之間參數會改名，而且舊參數不會報錯。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;5. 外掛 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;name&lt;/code&gt; 用絕對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;file://&lt;/code&gt; URL 的字面字串&lt;/strong&gt;，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;!!js&lt;/code&gt; 在這裡不能用。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;6. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_*&lt;/code&gt; 工具&lt;/strong&gt;：讓 DSH 驗 schema，Host 從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/call&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/result&lt;/code&gt; 事件取「最後一次被接受」的呼叫。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;7. 非 DeepSeek 模型用 Messages 相容閘道&lt;/strong&gt;（LiteLLM），憑證用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DEEPSEEK_API_KEY&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DEEPSEEK_BASE_URL&lt;/code&gt;；patch 的 config 是整段取代。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;8. 供應商專屬能力（Google Search grounding）放進工具裡&lt;/strong&gt;，不要期待翻譯層幫你保留。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;9. Agent 子程序的環境變數要過濾&lt;/strong&gt;，不要把 Channel Secret 交給它。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;10. Pre-release 套件全部鎖同一條 dist-tag 的版本&lt;/strong&gt;，容器的 Node 版本要實際跑過一次。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;11. 新服務沿用舊服務的 SA / bucket / queue / secrets / Firestore&lt;/strong&gt;，用 LINE API 切 webhook、用 log 確認流量，回滾只要改回 webhook。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;12. 公開的 repo、Issue、文章不要出現真實的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.run.app&lt;/code&gt; 網址&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;小結與開源專案連結&quot;&gt;小結與開源專案連結&lt;/h1&gt;

&lt;p&gt;這次把 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 的 Agent 層從 ADK for Go 換成 DeepSeek Harness，做成 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-dsh&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，幾個最值得帶走的收穫：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;dsh-superagent 是一個很完整的「主動式 Agent」設計參考&lt;/strong&gt;（Source / Eval / Ticket / Mandate），但它的執行模型是長駐行程 + SQLite，跟 Cloud Run 不合。借它的 harness，不要硬搬它的 app。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;ADK 有的東西，在 DSH 上大多可以用「工具」重新做出來&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; 變 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_*&lt;/code&gt;，Google Search grounding 變 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt;。工具層的 schema 驗證，甚至比 prompt 約束更可靠。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;pre-release 框架最大的風險不是功能，是「靜默失效」&lt;/strong&gt;：參數被忽略、外掛載入失敗變成「unknown tool」。每一層都要有能直接觀察的驗證方法。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;完整程式碼在 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-dsh&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，設計取捨也寫在 repo 的 &lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh/blob/main/docs/design.md&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docs/design.md&lt;/code&gt;&lt;/a&gt;，歡迎參考與交流！&lt;/p&gt;

&lt;h2 id=&quot;延伸閱讀&quot;&gt;延伸閱讀&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.evanlin.com/deepseek-harness-vs-google-harness2/&quot;&gt;上一篇：同樣叫 Harness，差在哪？DSH 框架解析與 Google Harness² 比較&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.evanlin.com/line-research-bot-python-to-go-adk/&quot;&gt;前前篇：把 LINE 研究 Bot 從 Python Managed Agents 改寫成 Go ADK&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-dsh&lt;/code&gt;：本文的完整程式碼&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/deepseek-ai/dsh-superagent-prototype&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deepseek-ai/dsh-superagent-prototype&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.deepseek.com/en/harness/&quot;&gt;DeepSeek Harness&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.litellm.ai/&quot;&gt;LiteLLM：Anthropic &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/v1/messages&lt;/code&gt; 相容端點&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://cloud.google.com/run/docs/deploying#sidecars&quot;&gt;Cloud Run：多 container（sidecar）部署&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
				<pubDate>Wed, 04 Nov 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/line-research-bot-adk-to-deepseek-harness/</link>
				<guid isPermaLink="true">https://www.evanlin.com/line-research-bot-adk-to-deepseek-harness/</guid>
			</item>
		
			<item>
				<title>[AI 實戰] 同樣叫 Harness，差在哪？DeepSeek Harness（DSH）框架解析，以及跟 Google Research Harness² 的比較</title>
				<description>&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    subgraph H2[&quot;Google Research Harness²：改「裝備的內容」&quot;]
        direction TB
        OPT[&quot;雙層遞迴優化器（Python）&amp;lt;br/&amp;gt;Propose → Probe → Compose&amp;lt;br/&amp;gt;Experience Reflector&quot;]
        TREE[&quot;c1..c8 裝備檔案樹&amp;lt;br/&amp;gt;systemprompt / guardrails /&amp;lt;br/&amp;gt;LongTermMEMORY / skills…&quot;]
        OPT --&amp;gt;|&quot;產生下一代 H^(k)&quot;| TREE
    end

    subgraph DSH[&quot;DeepSeek Harness：負責「把 Agent 組起來跑」&quot;]
        direction TB
        PROF[&quot;Profile = bundle + YAML patch&quot;]
        RT[&quot;dsh runtime&amp;lt;br/&amp;gt;agent loop / ctx.tools / ctx.llm /&amp;lt;br/&amp;gt;session 事件&quot;]
        PROF --&amp;gt;|&quot;Cordis 組裝外掛&quot;| RT
    end

    TREE -.-&amp;gt;|&quot;裝備被某個執行環境載入&quot;| RT
    RT -.-&amp;gt;|&quot;執行軌跡 / 分數&quot;| OPT
&lt;/code&gt;&lt;/pre&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt; &lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;DeepSeek Harness（DSH）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Google Research Harness²&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一句話&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 的&lt;strong&gt;執行環境&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 裝備的&lt;strong&gt;自動優化器&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;「Harness」指的是&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;跑 Agent 的那套 runtime&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;包在模型外面的提示詞、護欄、記憶、技能&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;你會改的東西&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Profile、YAML patch、外掛&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案樹（但通常是 Harness² 自己改）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;這個系列裡用在哪&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LINE 研究 Bot 的 Agent 層&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LINE AI 名片王的自我演化&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h1 id=&quot;前言兩個-harness一週內碰到兩次&quot;&gt;前言：兩個 Harness，一週內碰到兩次&lt;/h1&gt;

&lt;p&gt;前幾天的 &lt;strong&gt;Harness² 三部曲&lt;/strong&gt;（&lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-7/&quot;&gt;上&lt;/a&gt;、&lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-8/&quot;&gt;中&lt;/a&gt;、&lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-9/&quot;&gt;下&lt;/a&gt;），我把 Google Research 的 &lt;strong&gt;&lt;a href=&quot;https://github.com/google-research/harness2&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 接上 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;，讓它讀 OpenTelemetry 軌跡、自己長出技能檔，準確率從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;62.5%&lt;/code&gt; 一路爬到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100.0%&lt;/code&gt;。&lt;/p&gt;

&lt;p&gt;這週又剛好碰到 DeepSeek 開源的 &lt;strong&gt;&lt;a href=&quot;https://github.com/deepseek-ai/dsh-superagent-prototype&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deepseek-ai/dsh-superagent-prototype&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，它建在 &lt;strong&gt;&lt;a href=&quot;https://www.deepseek.com/en/harness/&quot;&gt;DeepSeek Harness（DSH）&lt;/a&gt;&lt;/strong&gt; 上。我把 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;LINE 研究 Bot&lt;/a&gt;&lt;/strong&gt; 的 Agent 層從 ADK for Go 換成了 DSH，做成 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-dsh&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，目前已經在線上跑了。&lt;/p&gt;

&lt;p&gt;兩個都叫 &lt;strong&gt;Harness&lt;/strong&gt;，我一開始也以為是同一類東西。實際用過之後才發現：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;strong&gt;DSH 是「馬具怎麼組裝、怎麼套在馬身上跑」；Harness² 是「自動調整馬具上的每一條皮帶」。&lt;/strong&gt; 兩個在不同層，甚至可以接在一起用。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;因為內容太多，這次拆成兩篇：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;本篇&lt;/strong&gt;：DSH 框架到底是什麼（附框架圖），以及它跟 Google Harness² 的逐項比較。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://www.evanlin.com/line-research-bot-adk-to-deepseek-harness/&quot;&gt;下一篇&lt;/a&gt;&lt;/strong&gt;：實際怎麼把 LINE 研究 Bot 從 ADK 搬到 DSH，加上踩坑清單。&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一先搞懂-deepseek-harnessdsh是什麼&quot;&gt;一、先搞懂 DeepSeek Harness（DSH）是什麼&lt;/h1&gt;

&lt;p&gt;很多人看到 dsh-superagent 會以為它是一個 Agent SDK，其實它是兩層東西：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;層次&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;是什麼&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;在 npm 上&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;DeepSeek Harness（DSH）&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一個「Agent 執行環境」：負責模型呼叫、工具、Session、權限、沙箱，全部都是外掛&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/dsh&lt;/code&gt;（CLI）、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/dsh-*&lt;/code&gt; 一百多個套件&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;dsh-superagent&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;跑在 DSH 上的一個 &lt;strong&gt;bundle（外掛包）&lt;/strong&gt;，把 DSH 變成「幫一個 GitHub repo 做事的主動式 Agent」&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一個 Node 套件，用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh plugin add&lt;/code&gt; 裝進 DSH profile&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;1-核心設計一切都是-cordis-外掛&quot;&gt;1. 核心設計：一切都是 Cordis 外掛&lt;/h2&gt;

&lt;p&gt;DSH 底層是 &lt;strong&gt;Cordis&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/cordis&lt;/code&gt;）這個外掛框架。模型、工具、Session 儲存、沙箱，甚至 JSON-RPC 伺服器，&lt;strong&gt;全部都是一個個的外掛（plugin row）&lt;/strong&gt;，彼此透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ctx&lt;/code&gt; 上的服務溝通，例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ctx.llm&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ctx.tools&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ctx.fs&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ctx.subprocess&lt;/code&gt;。&lt;/p&gt;

&lt;p&gt;外掛怎麼組合起來，由 &lt;strong&gt;Profile&lt;/strong&gt; 決定：&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Bundle&lt;/strong&gt;：官方預先組好的一串外掛，例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh-sdk-minimal&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh-base&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tui&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;headless&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Profile&lt;/strong&gt;：放在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;$DSH_HOME/profiles/&amp;lt;name&amp;gt;/&lt;/code&gt; 底下，指定要用哪些 bundle。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Patch 疊層&lt;/strong&gt;：在 bundle 之上再疊 YAML patch，可以改某個外掛的 config、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;disabled: true&lt;/code&gt; 關掉它，或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;insert&lt;/code&gt; 自己的外掛。用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh --profile x --dump-config&lt;/code&gt; 可以看到最後組出來的完整樹。&lt;/li&gt;
&lt;/ul&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# 一個 patch 的樣子：改模型設定、關掉 shell、插入自己的外掛&lt;/span&gt;
&lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;llm-deepseek&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;thinking&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;disabled&lt;/span&gt;
&lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;persistent-bash&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;disabled&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;true&lt;/span&gt;
&lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;insert&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;na&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;line-research-tools&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;file:///app/dsh/plugin/index.js&apos;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;2-dsh-框架圖&quot;&gt;2. DSH 框架圖&lt;/h2&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
    subgraph HOST[&quot;你的程式（Host）&quot;]
        APP[&quot;Node / Python 程式&quot;]
        SDK[&quot;@deepseek-ai/dsh-sdk-client&amp;lt;br/&amp;gt;DeepSeekHarness.run()&quot;]
        APP --&amp;gt; SDK
    end

    subgraph RT[&quot;dsh runtime 子程序（一個 Profile）&quot;]
        direction TB
        RPC[&quot;dsh-sdk-jsonrpc-server&amp;lt;br/&amp;gt;stdio JSON-RPC&quot;]
        LOADER[&quot;Cordis Loader&amp;lt;br/&amp;gt;bundle + patch 疊層&quot;]
        AGENT[&quot;dsh-agent / agent-loop&amp;lt;br/&amp;gt;turn → step → tool call&quot;]
        PROMPT[&quot;system-prompt&amp;lt;br/&amp;gt;persona（DSH_SYSTEM_PROMPT）&quot;]
        TOOLS[&quot;dsh-tools（ctx.tools）&amp;lt;br/&amp;gt;內建：bash / edit / web_search…&amp;lt;br/&amp;gt;外掛：defineTool() 註冊&quot;]
        LLM[&quot;dsh-llm（ctx.llm）&amp;lt;br/&amp;gt;llm-deepseek 介接層&amp;lt;br/&amp;gt;Anthropic Messages 協定&quot;]
        SES[&quot;session-persistence&amp;lt;br/&amp;gt;$DSH_HOME/sessions/*.jsonl&quot;]
        RPC --&amp;gt; AGENT
        LOADER -.組裝.-&amp;gt; AGENT
        AGENT --&amp;gt; PROMPT
        AGENT --&amp;gt; TOOLS
        AGENT --&amp;gt; LLM
        AGENT --&amp;gt; SES
    end

    SDK &amp;lt;--&amp;gt;|&quot;initialize / prompt&amp;lt;br/&amp;gt;notifications&quot;| RPC
    LLM --&amp;gt;|&quot;POST {baseURL}/v1/messages&quot;| API[&quot;api.deepseek.com/anthropic&amp;lt;br/&amp;gt;或任何 Messages 相容端點&quot;]
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;從這張圖可以延伸出四個關鍵事實：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Agent 跑在另一個行程裡&lt;/strong&gt;。不像 ADK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Run()&lt;/code&gt; 是在你的程式裡跑，DSH 是你 spawn 一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh&lt;/code&gt; runtime 子程序，用 &lt;strong&gt;stdio JSON-RPC&lt;/strong&gt; 跟它講話。TypeScript 端是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@deepseek-ai/dsh-sdk-client&lt;/code&gt;，另外也有 Python SDK。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;模型層只講 Anthropic Messages 協定&lt;/strong&gt;。官方介接層 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llm-deepseek&lt;/code&gt; 預設打 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://api.deepseek.com/anthropic&lt;/code&gt;。&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseURL&lt;/code&gt; 可以換，但對面一定要是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/v1/messages&lt;/code&gt; 相容端點，&lt;strong&gt;沒有 Gemini 介接層&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;工具是外掛註冊的&lt;/strong&gt;。自己寫一個 Cordis 外掛，在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apply(ctx)&lt;/code&gt; 裡 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ctx.tools.register(defineTool({...}))&lt;/code&gt;，參數 schema 由 DSH 驗證，驗不過會以錯誤結果回給模型，讓它自己修正。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Session 是事件流&lt;/strong&gt;。每一次 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run()&lt;/code&gt; 都會回傳完整的 session 事件：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;turn/start&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/call&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/result&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;assistant/message&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;turn/end&lt;/code&gt;……要拿結構化結果、要除錯，都靠這個。&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id=&quot;3-dsh-superagent-在-dsh-上做了什麼&quot;&gt;3. dsh-superagent 在 DSH 上做了什麼&lt;/h2&gt;

&lt;p&gt;dsh-superagent 是 DeepSeek 團隊內部用的「主動式 coding agent」原型。它的 README 自己講得很清楚：&lt;strong&gt;research prototype，不是正式產品&lt;/strong&gt;。它的領域模型長這樣：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    S[&quot;Source&amp;lt;br/&amp;gt;GitHub / Feishu&quot;] --&amp;gt;|Trigger| T[&quot;Thread&quot;]
    T --&amp;gt;|批次| E[&quot;Eval&amp;lt;br/&amp;gt;準入 + 研判&quot;]
    T --&amp;gt;|Subscription 扇出| K[&quot;Ticket&quot;]
    E --&amp;gt;|accept + Mandate| K
    K --&amp;gt;|Assignment| W[&quot;Executor&amp;lt;br/&amp;gt;每張 Ticket 一個 DSH Session + 目錄&quot;]
    K --&amp;gt;|Channel| S
&lt;/code&gt;&lt;/pre&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Source&lt;/strong&gt; 把 GitHub 通知、Feishu 訊息轉成 &lt;strong&gt;Trigger&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Eval&lt;/strong&gt; 依照 &lt;strong&gt;Policy&lt;/strong&gt;（誰可以下指令、在哪裡、強度多少）決定要不要接單，接了就開一張 &lt;strong&gt;Ticket&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;每張 Ticket 由一個 &lt;strong&gt;Executor Session&lt;/strong&gt; 在自己的目錄裡做事，結果透過 &lt;strong&gt;Channel&lt;/strong&gt; 回到原本的對話，例如開一個 PR。&lt;/li&gt;
  &lt;li&gt;旁邊還有一個 Web 面板，顯示哪些事情需要人來決定。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;它的執行模型是&lt;strong&gt;一個長駐行程 + SQLite + 只聽 127.0.0.1 的管理 API&lt;/strong&gt;，而且一定要有 GitHub repo 跟 agent 帳號。這也是為什麼我搬 LINE Bot 時只借了 DSH，沒有 fork dsh-superagent，細節留到&lt;a href=&quot;https://www.evanlin.com/line-research-bot-adk-to-deepseek-harness/&quot;&gt;下一篇&lt;/a&gt;。&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;💡 &lt;strong&gt;心得&lt;/strong&gt;：講到 DSH 時要分清楚是&lt;strong&gt;執行環境（harness）&lt;/strong&gt;還是&lt;strong&gt;上面那個應用（superagent）&lt;/strong&gt;。大部分人想借用的其實是前者。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二快速回顧google-research-harness-在做什麼&quot;&gt;二、快速回顧：Google Research Harness² 在做什麼&lt;/h1&gt;

&lt;p&gt;詳細內容可以看 &lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-7/&quot;&gt;Harness² 上篇&lt;/a&gt;，這裡只抓重點：&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;它把「Harness」定義成一棵可編輯的檔案樹&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt; 是常駐組件（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;guardrails.md&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LongTermMEMORY.md&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool_descriptions/&lt;/code&gt;），總和不能超過 &lt;strong&gt;24,000 bytes&lt;/strong&gt;；&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c5..c8&lt;/code&gt; 是按需組件（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sub_agents/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scripts/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;plugin/&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;它用雙層遞迴自動改這棵樹&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;內層 &lt;strong&gt;Propose → Probe → Compose&lt;/strong&gt;：讀失敗任務的執行軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;）、提出多個候選 patch、在沙盒各跑一次、留下有正收益的合成下一代 $H^{(k)}$。&lt;/li&gt;
      &lt;li&gt;外層 &lt;strong&gt;Experience Reflector&lt;/strong&gt;：跨輪次提煉經驗，寫進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c3: LongTermMEMORY.md&lt;/code&gt;。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;它透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BenchmarkAdapter&lt;/code&gt; 跟你的 Agent 接起來&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run()&lt;/code&gt; 要回答「掛上某一版 Harness 跑某道題，產出了什麼、中間經歷了什麼」。在名片王裡，我是寫一個 Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/harness-runner&lt;/code&gt; 子程序 CLI，讓 Python 的 Harness² 呼叫。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;零洩漏屏障&lt;/strong&gt;：黃金答案不給 Agent、也不給 Harvester LLM，逼它從軌跡推理出通用規則。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三dsh-vs-harness逐項比較&quot;&gt;三、DSH vs Harness²：逐項比較&lt;/h1&gt;

&lt;h2 id=&quot;1-harness這個字兩邊指的不是同一件事&quot;&gt;1. 「Harness」這個字，兩邊指的不是同一件事&lt;/h2&gt;

&lt;p&gt;這是整篇最重要的一點：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt; &lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;DSH 的 Harness&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Harness² 的 Harness&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;指的是&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;跑 Agent 的程式&lt;/strong&gt;：agent loop、工具執行、模型呼叫、Session、權限&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;餵給 Agent 的內容&lt;/strong&gt;：提示詞、護欄、記憶、工具說明、技能&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;型態&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一個 Node 行程（runtime）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一個資料夾（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;類比&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;馬具的扣環、韁繩怎麼組裝&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;馬具上每條皮帶的長度怎麼調&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;誰改它&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;工程師寫 Profile / patch / 外掛&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Harness² 的優化器自己改&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;所以兩者不是「二選一」的競爭關係，而是&lt;strong&gt;上下兩層&lt;/strong&gt;。Harness² 要優化的那棵檔案樹，最後總要被某個 runtime 載入執行；DSH 正好就是一種 runtime。&lt;/p&gt;

&lt;h2 id=&quot;2-全面比較表&quot;&gt;2. 全面比較表&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;DeepSeek Harness（DSH）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Google Research Harness²&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;出身&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DeepSeek 開源，dsh-superagent 的底座&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Google Research 論文開源（arXiv:2610.14224）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;語言&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;TypeScript / Node（另有 Python SDK）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Python&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;定位&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 執行環境（runtime）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 裝備的離線優化器&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;核心抽象&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Cordis 外掛、Profile、Bundle、Patch&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 組件、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BenchmarkAdapter&lt;/code&gt;、Recursion&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;主要產出&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一次 Agent 執行的結果 + session 事件&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一棵更好的 Harness 檔案樹&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;何時執行&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;線上，每個請求都跑&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;離線，對著評估集跑多輪&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;需不需要評估集&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;不需要&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;一定要&lt;/strong&gt;（還要有 rubric 與軌跡）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;模型&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Anthropic Messages 相容端點（預設 DeepSeek）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;被優化的 Agent 用什麼都行，Harvester 另外指定&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;對既有 Agent 的侵入程度&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;高：Agent 要跑在 DSH 裡&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;低：寫一個 Adapter，把設定外移成檔案即可&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;怎麼看 Agent 在做什麼&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/call&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/result&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;turn/end&lt;/code&gt; 等 session 事件&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;（我在名片王是從 OpenTelemetry Spans 產生的）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;成熟度&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.2.1-rc.5&lt;/code&gt;，pre-release，參數會改名&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;研究程式碼，介面以論文實驗為主&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;這個系列裡&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LINE 研究 Bot 線上服務的 Agent 層&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LINE AI 名片王的離線自我演化&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;3-harness-的-c1c8在-dsh-裡對應到哪裡&quot;&gt;3. Harness² 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt;，在 DSH 裡對應到哪裡？&lt;/h2&gt;

&lt;p&gt;既然 DSH 也是「把一堆東西組成一個 Agent」，可以試著把 Harness² 的八個組件對過去。下表是我這次實際用 DSH 的理解，&lt;strong&gt;沒有對應的我就寫沒用到&lt;/strong&gt;：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Harness² 組件&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;在 DSH 裡的位置&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;我在 LINE 研究 Bot 怎麼用&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1&lt;/code&gt; systemprompt.md&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;system-prompt&lt;/code&gt; 外掛，可以用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_SYSTEM_PROMPT&lt;/code&gt; 帶入 persona&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prompts/persona.md&lt;/code&gt; 當 persona，三個 stage 的指示放在 user message&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c2&lt;/code&gt; guardrails.md&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;兩個地方：工具參數的 &lt;strong&gt;schema 驗證&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;required&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;enum&lt;/code&gt;），以及 patch 把危險工具 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;disabled: true&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_report&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;error&lt;/code&gt; 欄位用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;enum&lt;/code&gt; 擋掉亂填的值；關掉 bash 與 editor&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c3&lt;/code&gt; LongTermMEMORY.md&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DSH 的 session 是&lt;strong&gt;單次執行的事件流&lt;/strong&gt;，不是跨輪次記憶&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;沒用到；跨 stage 的資料放 Firestore&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c4&lt;/code&gt; tool_descriptions/&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;defineTool()&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;description&lt;/code&gt; 與參數 schema，模型直接看到&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;web_research&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;submit_*&lt;/code&gt; 的說明&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c5&lt;/code&gt; sub_agents/&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DSH 內建有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;subagent&lt;/code&gt; 工具（完整的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sdk&lt;/code&gt; profile 裡看得到）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;沒用到，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sdk-minimal&lt;/code&gt; 裡也關掉了&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; skills/&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;這次沒研究到對應機制&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;沒用到&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c7&lt;/code&gt; scripts/&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;等於讓 Agent 跑 shell（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;persistent-bash&lt;/code&gt; 等工具）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;刻意關掉&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c8&lt;/code&gt; plugin/&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;這就是 DSH 的本體&lt;/strong&gt;：Cordis 外掛&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dsh/plugin/index.js&lt;/code&gt; 註冊研究工具&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;對完之後最有意思的發現是：&lt;strong&gt;Harness² 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c8&lt;/code&gt; 在 DSH 裡是主角&lt;/strong&gt;，而 Harness² 最在意的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c3&lt;/code&gt;，DSH 反而只提供最基本的掛載點。這也呼應了兩邊的定位：DSH 在意「執行面」能不能被組裝，Harness² 在意「內容面」能不能被演化。&lt;/p&gt;

&lt;h2 id=&quot;4-共同點兩邊都把agent-的裝備從程式碼裡搬出來&quot;&gt;4. 共同點：兩邊都把「Agent 的裝備」從程式碼裡搬出來&lt;/h2&gt;

&lt;p&gt;雖然層次不同，兩邊有幾個很像的設計直覺：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;設定外移成檔案&lt;/strong&gt;。名片王導入 Harness² 的第一步，就是把寫死在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.go&lt;/code&gt; 裡的 Prompt 抽成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt;；DSH 則是把「用哪些外掛、關掉哪些工具」抽成 Profile + YAML patch。兩邊都不想為了改 Agent 的行為而重新編譯。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;用子程序隔開&lt;/strong&gt;。名片王裡 Harness² 是呼叫 Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness-runner&lt;/code&gt; 子程序；DSH 本身就是一個被 SDK spawn 的子程序。這樣不管 Host 用什麼語言，都可以接上。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;都要看得到 Agent 的過程，不只是結果&lt;/strong&gt;。Harness² 靠 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt; 做診斷；我在 DSH 上拿結構化輸出、確認 patch 有沒有生效，靠的也是 session 事件。&lt;strong&gt;能觀察到中間過程，才有辦法優化或除錯。&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id=&quot;5-差異一個管怎麼跑一個管跑什麼&quot;&gt;5. 差異：一個管「怎麼跑」，一個管「跑什麼」&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;DSH 的難點在工程&lt;/strong&gt;：外掛路徑解析、SDK 參數改名、模型協定只有 Messages。這些都是「讓它跑起來」的問題，我在&lt;a href=&quot;https://www.evanlin.com/line-research-bot-adk-to-deepseek-harness/&quot;&gt;下一篇&lt;/a&gt;整理了十個坑。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Harness² 的難點在資料&lt;/strong&gt;：要有夠好的評估集、rubric、零洩漏的設計、高解析度的軌跡。這些都是「讓它變更好」的問題。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;DSH 每個請求都在跑&lt;/strong&gt;，要在意延遲與成本；&lt;strong&gt;Harness² 是離線跑&lt;/strong&gt;，可以花比較多 token 換一棵更好的檔案樹，上線時成本為零。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四能不能接在一起用&quot;&gt;四、能不能接在一起用？&lt;/h1&gt;

&lt;p&gt;可以，而且概念上很自然。以 LINE 研究 Bot 為例，如果想讓它像名片王一樣自我演化，大概會長這樣：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    subgraph PY[&quot;Harness²（Python，離線）&quot;]
        REC[&quot;Recursion&amp;lt;br/&amp;gt;Propose / Probe / Compose&quot;]
        ADP[&quot;DshAdapter.run()&quot;]
        REC --&amp;gt; ADP
    end

    subgraph TS[&quot;research runner（TypeScript）&quot;]
        GEN[&quot;把 c1..c8 轉成&amp;lt;br/&amp;gt;persona + research.patch.yml&quot;]
        RUN[&quot;DeepSeekHarness.run()&quot;]
        TRJ[&quot;session 事件 → trajectory.md&quot;]
        GEN --&amp;gt; RUN --&amp;gt; TRJ
    end

    ADP --&amp;gt;|&quot;--harness-dir / --task-json&quot;| GEN
    TRJ --&amp;gt;|&quot;deliverable + trajectory&quot;| ADP
&lt;/code&gt;&lt;/pre&gt;

&lt;ol&gt;
  &lt;li&gt;仿照名片王的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/harness-runner&lt;/code&gt;，寫一個 TypeScript 的 runner CLI，吃 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--harness-dir&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--task-json&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;Runner 把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1&lt;/code&gt; 轉成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DSH_SYSTEM_PROMPT&lt;/code&gt;、把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c4&lt;/code&gt; 寫進工具說明、把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c2&lt;/code&gt; 的一部分變成 patch（例如關掉哪些工具）。&lt;/li&gt;
  &lt;li&gt;跑完把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/call&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/result&lt;/code&gt; 等 session 事件渲染成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;，連同報告一起回給 Python 端的 Adapter。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;這部分我&lt;strong&gt;還沒有實作&lt;/strong&gt;，只是把兩篇的經驗疊在一起之後覺得可行。DSH 的 session 事件本來就比 OpenTelemetry Spans 更貼近「Agent 決策」，拿來當 trajectory 應該會很好用。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五什麼時候用哪一個&quot;&gt;五、什麼時候用哪一個？&lt;/h1&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;你的狀況&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;建議&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;想要一個能組裝、能關掉危險工具、能換模型端點的 Agent 執行環境&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;DSH&lt;/strong&gt;（注意它是 pre-release，模型層只講 Messages）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Agent 已經上線，想讓提示詞、技能、記憶根據評估結果自動進化&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Harness²&lt;/strong&gt;（前提是有評估集與執行軌跡）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;已經用 ADK 跑得很好，只是想調整品質&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;先上 &lt;strong&gt;Harness²&lt;/strong&gt;，不用換框架&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;兩個都想要&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;DSH 當 runtime、Harness² 當離線優化器，中間用 Adapter + 子程序接起來&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;小結&quot;&gt;小結&lt;/h1&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;同樣叫 Harness，DSH 是 runtime，Harness² 是 runtime 要載入的內容加上它的優化器&lt;/strong&gt;。先弄清楚這點，就不會拿它們互相比「誰比較強」。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;DSH 的設計重點是可組裝&lt;/strong&gt;：Cordis 外掛 + Profile 疊層，關掉、換掉、插入任何一塊都只要一段 YAML；代價是 Agent 跑在另一個行程，要用 JSON-RPC 跟它溝通。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Harness² 的設計重點是可演化&lt;/strong&gt;：把裝備拆成有預算限制的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt;，用軌跡驅動雙層遞迴去改它。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;兩邊都在做同一件事的不同面向&lt;/strong&gt;：把 Agent 的行為從程式碼裡解放出來。一個解放「怎麼跑」，一個解放「跑什麼」。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;下一篇會進入實作：&lt;strong&gt;&lt;a href=&quot;https://www.evanlin.com/line-research-bot-adk-to-deepseek-harness/&quot;&gt;把 LINE 研究 Bot 從 Go ADK 搬到 DeepSeek Harness：搬遷對照與踩坑全紀錄&lt;/a&gt;&lt;/strong&gt;。&lt;/p&gt;

&lt;h2 id=&quot;延伸閱讀&quot;&gt;延伸閱讀&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-7/&quot;&gt;Harness² 上篇：認識雙層遞迴 Agent 裝備框架與 c1..c8 解耦實戰&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-8/&quot;&gt;Harness² 中篇：LineCardAdapter、零洩漏屏障與行為軌跡&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.evanlin.com/adk-graph-workflow-go-9/&quot;&gt;Harness² 下篇：62.5% 到 100% 的雙層遞迴實測&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/deepseek-ai/dsh-superagent-prototype&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deepseek-ai/dsh-superagent-prototype&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.deepseek.com/en/harness/&quot;&gt;DeepSeek Harness&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/google-research/harness2&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-dsh&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-dsh&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
				<pubDate>Tue, 03 Nov 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/deepseek-harness-vs-google-harness2/</link>
				<guid isPermaLink="true">https://www.evanlin.com/deepseek-harness-vs-google-harness2/</guid>
			</item>
		
			<item>
				<title>[AI 實戰] 把 LINE 研究 Bot 從 Python Managed Agents 改寫成 Go ADK v1.9.0：沙箱檔案變 Session State、Cloud Run 零停機切換與 gcloud 踩坑全紀錄</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/line-research-bot-go-adk-arch.png&quot; alt=&quot;LINE Research Bot: Managed Agents (Python) → ADK for Go v1.9.0 on Cloud Run&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前情提要&quot;&gt;前情提要&lt;/h1&gt;

&lt;p&gt;在 &lt;a href=&quot;https://www.evanlin.com/agents-api/&quot;&gt;上一篇 Managed Agents API 全解析&lt;/a&gt; 裡，我做了一隻開源的 LINE 研究規劃師 Bot：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;它的玩法很簡單：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;在 LINE 傳「&lt;strong&gt;研究 SOTA 開源向量資料庫的選型&lt;/strong&gt;」，Bot 會依序跑 &lt;strong&gt;PLAN → SEARCH_COMPARE → WRITE_REPORT&lt;/strong&gt; 三個階段：先設計 4～8 組搜尋關鍵字，再用 Google Search + URL Context 讀真實網頁並交叉比對出「共識 / 分歧 / 缺口」，最後寫成一份有 footnote 引用的繁體中文 Markdown 報告。&lt;/li&gt;
  &lt;li&gt;報告由 Cloud Run 渲染成 HTML 丟上 Cloud Storage，LINE 收到一張附摘要、主要來源與「閱讀完整報告」按鈕的 Flex 卡片。&lt;/li&gt;
  &lt;li&gt;之後再傳「&lt;strong&gt;第 2 章再深一點，加日文來源&lt;/strong&gt;」，Bot 會在同一份報告上深化、版本號 +1，舊版自動存成 snapshot。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;第一版是 &lt;strong&gt;Python 3.11 + FastAPI + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-genai&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;enterprise=True&lt;/code&gt;）&lt;/strong&gt; 打 Pre-GA 的 &lt;strong&gt;Managed Agents API&lt;/strong&gt;，靠的是官方沙箱的 &lt;strong&gt;持久化 filesystem&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace/plan.json&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace/sources.json&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace/report.md&lt;/code&gt; 在同一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;environment_id&lt;/code&gt; 底下跨回合存活，深化時 Agent 自己去讀檔。&lt;/p&gt;

&lt;p&gt;它很好玩，但跑了一陣子之後，有幾件事一直讓我不太放心：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Pre-GA，沒有 SLA&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;base_agent: antigravity-preview-05-2026&lt;/code&gt; 這種名字一看就知道哪天會變。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;沙箱裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gsutil&lt;/code&gt; 是 mock 的&lt;/strong&gt;（上一篇的踩坑二），結果 Agent 寫完報告還是得把整份 Markdown 塞回 JSON 給 Cloud Run 上傳。沙箱 filesystem 的價值其實只剩「跨回合記住三個檔案」。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;一定要 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;background=True&lt;/code&gt; + 自己寫 polling 迴圈&lt;/strong&gt;，Stage 2/3 一慢就要調 timeout（我曾經從 240 秒一路調到 600 秒）。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;於是這次我決定：&lt;strong&gt;把整個服務改寫成 Go，所有跟 Agent 有關的事情改用 Google 官方的 &lt;a href=&quot;https://github.com/google/adk-go&quot;&gt;ADK for Go&lt;/a&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk&lt;/code&gt; v1.9.0）來做，並且部署回原本的 Cloud Run 服務、沿用一模一樣的環境變數。&lt;/strong&gt; 整個過程我都記錄在原 repo 的 &lt;a href=&quot;https://github.com/kkdai/line-research-bot/issues/1&quot;&gt;Issue #1&lt;/a&gt;。&lt;/p&gt;

&lt;p&gt;改寫完成後，我把 Go 版獨立成一個新的 repo，讓上一篇文章引用的 Python 版維持原樣，兩個版本可以直接對照：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Repo&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;內容&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;原本的 Python 3.11 + FastAPI + Managed Agents 版（上一篇文章的範例），以及這次遷移的 &lt;a href=&quot;https://github.com/kkdai/line-research-bot/issues/1&quot;&gt;Issue #1&lt;/a&gt; 紀錄&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;這篇的主角：Go 1.27 + ADK for Go v1.9.0，目前線上 Cloud Run 跑的就是這份程式碼&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一先講清楚原本其實不是python-adk&quot;&gt;一、先講清楚：原本其實不是「Python ADK」&lt;/h1&gt;

&lt;p&gt;很多人（包括一開始的我）會把 Managed Agents 跟 ADK 混在一起講，但它們是兩個不同的東西：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;比較項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;原 Python 版&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;新 Go 版&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Agent 執行位置&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Google 託管的沙箱（Managed Agents API）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;自己的 Cloud Run 容器內（ADK Runner）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;SDK&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-genai&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;enterprise=True&lt;/code&gt;），&lt;strong&gt;沒有&lt;/strong&gt;用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-adk&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk v1.9.0&lt;/code&gt;&lt;/strong&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/genai&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Agent 定義&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy/create-agent.sh&lt;/code&gt; 用 curl 打 REST API 建一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;research-planner&lt;/code&gt; 資源&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;程式裡 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.New(llmagent.Config{...})&lt;/code&gt; × 3&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;工具&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;code_execution&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;filesystem&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google_search&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;url_context&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;geminitool.GoogleSearch{}&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;url_context&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;跨回合狀態&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;沙箱 filesystem（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;environment_id&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;ADK Session State + Firestore &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line_bot_workspaces&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;結構化輸出&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Prompt 裡寫「Return ONLY the JSON」+ 自己剝 code fence&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt;（ADK 自動注入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;set_model_response&lt;/code&gt;）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;呼叫方式&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;interactions.create(background=True)&lt;/code&gt; + 每 3 秒 polling&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Run()&lt;/code&gt; 回傳 Go 1.23+ iterator，同步拿事件&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;所以這次與其說是「Python ADK → Go ADK」，更精確的說法是：&lt;strong&gt;把託管式的 Managed Agent，換成自己掌控的 ADK Agent&lt;/strong&gt;。好處是沙箱裡 mock 掉的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gsutil&lt;/code&gt;、需要輪詢的 background 模式、還有 Pre-GA 的不確定性，全部都不用再擔心。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二改寫前先立規矩一個-issue先做可行性驗證&quot;&gt;二、改寫前先立規矩：一個 Issue、先做可行性驗證&lt;/h1&gt;

&lt;p&gt;這個專案比上一篇的 linebot-helper 小很多（Python 版約 1,400 行，改寫後的 Go 約 2,000 行，不含測試），所以我沒有拆 11 個 Issue，而是開一個 &lt;a href=&quot;https://github.com/kkdai/line-research-bot/issues/1&quot;&gt;Tracking Issue #1&lt;/a&gt;，把「現況盤點 → 設計 → 可行性驗證 → 改寫 → 測試 → 部署 → 驗證」寫成 checklist，每完成一段就回 Issue 留言。&lt;/p&gt;

&lt;p&gt;在動手寫任何一行 Go 之前，我先做了兩件事：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services describe&lt;/code&gt; 把線上服務設定撈出來&lt;/strong&gt;（Service Account、11 個環境變數、Secret Manager 綁定、記憶體、timeout），確保改寫後能 1:1 沿用。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;寫一支 30 行的 probe 程式&lt;/strong&gt;，確認 ADK for Go 在 Vertex AI 上能不能「&lt;strong&gt;Google Search + URL Context + OutputSchema 三個一起開&lt;/strong&gt;」。這是整個設計能不能成立的關鍵，結果在第四節會講。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;確認可行後，Go 版（module path &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;github.com/kkdai/line-research-bot-go&lt;/code&gt;）的模組切分如下：&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;cmd/server/            main：組裝依賴、HTTP server、graceful shutdown
internal/research/     ADK for Go：三個 llmagent + runner + session state
  prompts/             plan / search_compare / write_report（go:embed）
internal/worker/       PLAN → SEARCH_COMPARE → WRITE_REPORT → publish、deepen、retry
internal/server/       /webhook、/tasks/run-research、/readyz
internal/state/        Firestore（users / reports 相容 + 新的 workspaces）
internal/publisher/    goldmark (GFM + footnote) → HTML → GCS（含 snapshot）
internal/linebot/      line-bot-sdk-go v8 + HMAC 驗章
internal/tasks/        Cloud Tasks（OIDC）
internal/intent, flex/ 意圖分類、Flex 卡片
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;整體資料流如下：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    LINE[&quot;LINE App&quot;] --&amp;gt;|&quot;POST /webhook&amp;lt;br/&amp;gt;(HMAC)&quot;| WH[&quot;internal/server&amp;lt;br/&amp;gt;意圖分類 + 取鎖&quot;]
    WH --&amp;gt;|&quot;enqueue&quot;| CT[(&quot;Cloud Tasks&amp;lt;br/&amp;gt;research-jobs&quot;)]
    CT --&amp;gt;|&quot;POST /tasks/run-research&amp;lt;br/&amp;gt;(OIDC token)&quot;| WK[&quot;internal/worker&quot;]
    WK --&amp;gt;|&quot;seed / save&quot;| FS[(&quot;Firestore&amp;lt;br/&amp;gt;line_bot_workspaces&quot;)]
    WK --&amp;gt;|&quot;runner.Run()&quot;| ADK[&quot;ADK for Go&amp;lt;br/&amp;gt;plan / search_compare / write_report&quot;]
    ADK --&amp;gt;|&quot;Google Search + URL Context&quot;| VX[&quot;Vertex AI&amp;lt;br/&amp;gt;gemini-3.8-flash&quot;]
    WK --&amp;gt;|&quot;goldmark → HTML&quot;| GCS[(&quot;Cloud Storage&quot;)]
    WK --&amp;gt;|&quot;Push 進度 + Flex 卡片&quot;| LINE
&lt;/code&gt;&lt;/pre&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三從-managed-agents-到-adk-for-go四個核心改寫&quot;&gt;三、從 Managed Agents 到 ADK for Go：四個核心改寫&lt;/h1&gt;

&lt;h2 id=&quot;1-從rest-建立-agent-資源到程式裡-llmagentnew&quot;&gt;1. 從「REST 建立 Agent 資源」到「程式裡 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.New&lt;/code&gt;」&lt;/h2&gt;

&lt;p&gt;Python 版的 Agent 是用 shell script 打 REST API 建出來的，三個 stage 的 system instruction 被串成一大段，靠每次輸入的第一行 stage tag（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PLAN&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEARCH_COMPARE&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;WRITE_REPORT&lt;/code&gt;）讓 Agent 自己找對應章節：&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;research-planner&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;base_agent&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;antigravity-preview-05-2026&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;tools&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;code_execution&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{}},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;filesystem&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{}},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;google_search&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{}},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;url_context&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{}}],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;system_instruction&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;...三個 stage 的說明串在一起...&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Go 版則是三個各司其職的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent&lt;/code&gt;（&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go/blob/main/internal/research/agents.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/research/agents.go&lt;/code&gt;&lt;/a&gt;），prompt 用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go:embed&lt;/code&gt; 放在 &lt;a href=&quot;https://github.com/kkdai/line-research-bot-go/tree/main/internal/research/prompts&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/research/prompts/&lt;/code&gt;&lt;/a&gt;，工具只給需要的 stage（規劃階段根本不需要上網）：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;urlContextTool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tool&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Tool&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;geminitool&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;New&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;url_context&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;Reads the content of web pages by URL.&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
		&lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;genai&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Tool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;URLContext&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;genai&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;URLContext&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{}})&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;ag&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;llmagent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;New&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;llmagent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;Name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;         &lt;span class=&quot;s&quot;&gt;&quot;research_planner_search_compare&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;Description&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;  &lt;span class=&quot;s&quot;&gt;&quot;Searches the web and cross-compares sources.&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;Model&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;        &lt;span class=&quot;n&quot;&gt;llm&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;c&quot;&gt;// gemini.NewModel(ctx, cfg.GeminiModel, &amp;amp;genai.ClientConfig{Backend: genai.BackendVertexAI, ...})&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;Instruction&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;  &lt;span class=&quot;n&quot;&gt;searchPrompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;Tools&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tool&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Tool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;geminitool&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;GoogleSearch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{},&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;urlContextTool&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()},&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;OutputSchema&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;searchSchema&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;OutputKey&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;&quot;search_output&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;r&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;runner&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;New&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;runner&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AppName&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;appName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Agent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ag&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SessionService&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sessions&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;ADK for Go 目前只內建 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;geminitool.GoogleSearch&lt;/code&gt;，&lt;strong&gt;URL Context 要自己用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;geminitool.New&lt;/code&gt; 包一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;genai.Tool&lt;/code&gt;&lt;/strong&gt;，這是我翻 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool/geminitool&lt;/code&gt; 原始碼才發現的。另外 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AGENT_ID&lt;/code&gt; 這個環境變數我沒有丟掉，改當成 ADK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppName&lt;/code&gt; 與 agent 名稱前綴，這樣線上的環境變數完全不用動。&lt;/p&gt;

&lt;h2 id=&quot;2-從-backgroundtrue--polling-到-runnerrun-iterator&quot;&gt;2. 從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;background=True&lt;/code&gt; + polling 到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Run()&lt;/code&gt; iterator&lt;/h2&gt;

&lt;p&gt;Python 版最囉唆的就是這段：Managed Agents 不支援同步模式，所以要先 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create&lt;/code&gt;，再每 3 秒 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get&lt;/code&gt; 一次，直到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;completed&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;created&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;interactions&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;create&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_agent_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;input&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instruction&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;environment&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;env_arg&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;stream&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;background&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;store&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;while&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;monotonic&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;deadline&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;polled&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;interactions&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;created&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;include_input&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;polled&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;status&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;completed&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AgentResponse&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(...)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sleep&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_poll_interval&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;ADK for Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Run()&lt;/code&gt; 直接回傳 Go 1.23 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;iter.Seq2[*session.Event, error]&lt;/code&gt;，Agent 在自己的行程裡跑，事件一個一個流出來，timeout 交給 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;context.WithTimeout&lt;/code&gt; 就好：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;range&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;runner&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Run&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;userID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sid&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;genai&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NewContentFromText&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;input&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;genai&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RoleUser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RunConfig&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{})&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;invocationID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Errorf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;%w: %s: %v&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ErrAgent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;st&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;invocationID&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;InvocationID&lt;/span&gt;
	&lt;span class=&quot;c&quot;&gt;// final response 的文字當作後備；正式結果從 OutputKey 讀&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;原本存在 Firestore 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;last_interaction_id&lt;/code&gt; 我改存 ADK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvocationID&lt;/code&gt;，欄位名稱不變，查 log 對照時一樣好用。&lt;/p&gt;

&lt;h2 id=&quot;3-沙箱-workspace-檔案--adk-session-state--firestore最關鍵的一步&quot;&gt;3. 沙箱 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace&lt;/code&gt; 檔案 → ADK Session State + Firestore（最關鍵的一步）&lt;/h2&gt;

&lt;p&gt;Managed Agents 最大的賣點是沙箱 filesystem 跨回合存活。ADK 沒有沙箱，那「第 2 章再深一點」的時候，Agent 要去哪裡找上一次的來源和報告？&lt;/p&gt;

&lt;p&gt;答案是 &lt;strong&gt;ADK 的 Session State + Instruction 模板&lt;/strong&gt;。ADK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Instruction&lt;/code&gt; 會把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{key}&lt;/code&gt; 換成 session state 的值，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{key?}&lt;/code&gt; 則是「不存在也沒關係」：&lt;/p&gt;

&lt;div class=&quot;language-markdown highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;gu&quot;&gt;## Cross-compared sources (JSON)&lt;/span&gt;
{sources}

&lt;span class=&quot;gu&quot;&gt;## Current report Markdown (empty for a new report)&lt;/span&gt;
{report_md?}
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;對照關係就變成：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;沙箱檔案（Python 版）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;ADK Session State（Go 版）&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;持久化位置&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace/plan.json&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{plan}&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Firestore &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line_bot_workspaces/{userId}.plan&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace/sources.json&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{sources}&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;...sources&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/workspace/report.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{report_md?}&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;...report_md&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;但 Cloud Run 會水平擴展、也會縮到 0，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;session.InMemoryService()&lt;/code&gt; 裡的東西隨時會消失。所以我的做法是：&lt;strong&gt;每次執行 stage 都開一個新的 ADK session，用 Firestore workspace 播種初始 state，跑完把結果寫回 Firestore，再刪掉 session。&lt;/strong&gt;&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;created&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;a&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sessions&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Create&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;CreateRequest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AppName&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;a&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;appName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;UserID&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;  &lt;span class=&quot;n&quot;&gt;userID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;State&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt;   &lt;span class=&quot;k&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;any&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;KeySources&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;in&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SourcesJSON&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;KeyReportMD&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;in&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ReportMD&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這樣 Cloud Run instance 完全無狀態，幾小時後的深化請求打到任何一台 instance 都一樣。附帶的好處是：&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;「再發佈一次」不再需要 LLM&lt;/strong&gt;：Python 版的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retry_publish&lt;/code&gt; 要叫 Agent 去沙箱把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;report.md&lt;/code&gt; 讀出來再回傳；Go 版直接拿 Firestore 裡的 Markdown 重新渲染上傳，省一次模型呼叫。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;沙箱過期的處理保持一致&lt;/strong&gt;：舊版在 Managed Agents 建立的報告，Go 版讀不到它的沙箱檔案。我把它當成原本的「environment 過期」路徑處理：推一句「上次研究檔案已過期，重新從頭研究 🔄」然後重跑。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;⚠️ &lt;strong&gt;一個 ADK 模板的小陷阱&lt;/strong&gt;：ADK 會把 instruction 裡所有符合 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{識別字}&lt;/code&gt; 的字串都當成 state 變數，找不到就直接報錯。原本的 prompt 裡有很多 JSON 範例，搬過來時一定要清乾淨。我乾脆寫了一個單元測試，掃描三份 prompt，只允許 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{plan}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{sources}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{report_md?}&lt;/code&gt; 三個 placeholder 出現。&lt;/p&gt;

&lt;h2 id=&quot;4-return-only-the-json-outputschema&quot;&gt;4. 「Return ONLY the JSON」→ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;Python 版為了拿到 JSON，prompt 結尾寫「Return ONLY the JSON. No prose, no markdown fences.」，程式端還要一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_parse_agent_json&lt;/code&gt;，依序嘗試原文、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;```json&lt;/code&gt; fence 內容、第一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&lt;/code&gt; 到最後一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;}&lt;/code&gt;。&lt;/p&gt;

&lt;p&gt;ADK for Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; 更乾淨：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;When OutputSchema is set, the framework transparently injects a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;set_model_response&lt;/code&gt; tool so the model can still invoke other tools (function tools, RAG, agent transfer, etc.) while producing structured output.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;也就是說 &lt;strong&gt;ADK 會自動注入一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;set_model_response&lt;/code&gt; 工具&lt;/strong&gt;，模型可以先用 Google Search / URL Context 查完資料，最後呼叫這個工具交出符合 schema 的結果，再由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputKey&lt;/code&gt; 寫回 session state。我用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;genai.Schema&lt;/code&gt; 把三個 stage 的輸出結構都定義在 &lt;a href=&quot;https://github.com/kkdai/line-research-bot-go/blob/main/internal/research/schema.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/research/schema.go&lt;/code&gt;&lt;/a&gt;，原本的 JSON parser 留著當保險。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四模型選擇不是每個-gemini-都能搜尋--讀網頁--結構化輸出同時開&quot;&gt;四、模型選擇：不是每個 Gemini 都能「搜尋 + 讀網頁 + 結構化輸出」同時開&lt;/h1&gt;

&lt;p&gt;前面提到的 probe 程式，就是為了這一刻。同一支程式在我的 GCP 專案、location &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global&lt;/code&gt; 上跑出來的結果：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;模型&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;Google Search + URL Context + OutputSchema&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;結果&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-2.5-flash&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;❌&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;400 INVALID_ARGUMENT: controlled generation is not supported with URL Context tool&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;✅&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;第一版上線使用&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.1-flash&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;❌&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;404 NOT_FOUND&lt;/code&gt;（這個專案沒有這個模型）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.8-flash&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;✅&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;目前預設&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.8-pro&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-flash-preview&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-pro-preview&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-flash-lite&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;❌&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;皆為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;404 NOT_FOUND&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;兩個心得：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;模型清單要用你的專案實際打過才算數&lt;/strong&gt;。文件上有的模型名稱，不代表你的專案、你的 location 拿得到，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;404 Publisher model ... was not found or your project does not have access to it&lt;/code&gt; 是最常見的回應。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;模型名稱一定要做成環境變數&lt;/strong&gt;。Go 版新增一個可選的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GEMINI_MODEL&lt;/code&gt;，沒設定就用程式預設值，所以線上服務原本的 11 個環境變數一個都不用改。&lt;/li&gt;
&lt;/ol&gt;

&lt;h3 id=&quot;換到-gemini-38-flash-時抓到的一個-bug&quot;&gt;換到 gemini-3.8-flash 時抓到的一個 bug&lt;/h3&gt;

&lt;p&gt;升級到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.8-flash&lt;/code&gt; 之後，報告明顯變長變深（約 5k → 11～12k 字元），但整合測試抓到一個很微妙的問題：請它深化一個不存在的「第 99 章」時，它回傳的是&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;error=&quot;chapter_not_found_chapter_not_found&quot;   available_chapters=[]
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;舊程式用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;== &quot;chapter_not_found&quot;&lt;/code&gt; 判斷，這個值不相等，於是會&lt;strong&gt;把一份空的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;report_md&lt;/code&gt; 當成新版本發佈出去&lt;/strong&gt;。修法有三層：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;schema 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;error&lt;/code&gt; 改成 &lt;strong&gt;enum&lt;/strong&gt;（只允許 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chapter_not_found&lt;/code&gt;），從源頭限制模型。&lt;/li&gt;
  &lt;li&gt;worker 改用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;strings.Contains&lt;/code&gt; 寬鬆比對；&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;available_chapters&lt;/code&gt; 是空的就&lt;strong&gt;自己從報告的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;##&lt;/code&gt; 標題抓章節&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;report_md&lt;/code&gt; 是空的時候，一律不發佈，改推「深化失敗，請稍後再試。」&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;加上 enum 之後重跑，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.8-flash&lt;/code&gt; 正確回傳 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chapter_not_found&lt;/code&gt; 和完整的四個章節。&lt;strong&gt;換模型不是改一個字串就好，結構化輸出的邊界情境一定要重跑整合測試。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;代價也要誠實說：三個 stage 的總耗時從約 60 秒拉長到 150～190 秒。還在 timeout 內，但使用者要多等一下。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五gcloud-與-cloud-run-部署十個需要特別注意的地方&quot;&gt;五、gcloud 與 Cloud Run 部署：十個需要特別注意的地方&lt;/h1&gt;

&lt;p&gt;程式寫完、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test ./...&lt;/code&gt; 全綠、整合測試也打過真的 Vertex AI 之後，真正的挑戰才開始。這是一個&lt;strong&gt;正在線上服務真實 LINE 使用者&lt;/strong&gt;的 Bot，下面是這次部署一路上踩到或差點踩到的點。&lt;/p&gt;

&lt;h2 id=&quot;注意-1先-describe-線上設定不要相信-repo-裡的-deploysh&quot;&gt;注意 1：先 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;describe&lt;/code&gt; 線上設定，不要相信 repo 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy.sh&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;我原本以為照著 repo 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy/deploy.sh&lt;/code&gt; 部署就好，結果一 describe 線上服務才發現&lt;strong&gt;兩邊早就不一樣了&lt;/strong&gt;（之前除錯時直接在線上調過）：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;設定&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;repo 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy.sh&lt;/code&gt;&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;實際線上服務&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GCS_BUCKET&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line-reports&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;另一個 bucket&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Memory&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1Gi&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;2Gi&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Timeout&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;600&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;3600&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--min-instances&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0&lt;/code&gt;（沒設定）&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;如果直接跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy.sh&lt;/code&gt;，報告會被傳到錯的 bucket、長任務會被 600 秒砍掉。&lt;strong&gt;改寫服務時，「線上實際狀態」才是規格書&lt;/strong&gt;：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;gcloud run services describe line-research-bot &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;asia-east1 &lt;span class=&quot;nt&quot;&gt;--format&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;json &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  | jq &lt;span class=&quot;s1&quot;&gt;&apos;{sa: .spec.template.spec.serviceAccountName,
         env: [.spec.template.spec.containers[0].env[].name],
         resources: .spec.template.spec.containers[0].resources,
         timeout: .spec.template.spec.timeoutSeconds}&apos;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;注意-2要沿用一樣的環境變數最簡單的做法是什麼都不要帶&quot;&gt;注意 2：要「沿用一樣的環境變數」，最簡單的做法是&lt;strong&gt;什麼都不要帶&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;上一篇 linebot-helper 是部署成&lt;strong&gt;新的服務&lt;/strong&gt;，所以要把環境變數轉成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--env-vars-file&lt;/code&gt;。這次是部署回&lt;strong&gt;同一個服務&lt;/strong&gt;，有一個更簡單的做法：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run deploy --source=.&lt;/code&gt; &lt;strong&gt;不帶&lt;/strong&gt; &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--set-env-vars&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--update-secrets&lt;/code&gt;，新 revision 就會完整繼承上一個 revision 的環境變數與 Secret Manager 綁定。&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;這樣 LINE 的 Channel Secret / Access Token 從頭到尾都不會出現在指令列或終端機輸出裡。部署完我再 describe 一次，確認環境變數名稱清單跟原本一樣是 11 個。&lt;/p&gt;

&lt;h2 id=&quot;注意-3用---no-traffic---tag-做金絲雀tag-至少要-3-個字元&quot;&gt;注意 3：用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-traffic --tag&lt;/code&gt; 做金絲雀，&lt;strong&gt;tag 至少要 3 個字元&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;既然是同一個服務，我不想一部署就讓所有 LINE 使用者打到新版本。Cloud Run 的做法是：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;gcloud run deploy line-research-bot &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;asia-east1 &lt;span class=&quot;nt&quot;&gt;--source&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--no-traffic&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--tag&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;golang
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;新 revision 拿到 0% 流量，但會有一個專屬的 tag 網址可以直接打。這裡我踩了一個很蠢的雷：一開始寫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--tag=go&lt;/code&gt;，直接被擋：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ERROR: (gcloud.run.deploy) service.spec.traffic[1].tag: must be at least 3 characters long.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;在 tag 網址上做完冒煙測試（下面列出來）後，再切流量，並把上一個 revision 的名字記下來當回滾點：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;gcloud run services update-traffic line-research-bot &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;asia-east1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--to-revisions&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&amp;lt;新的 revision&amp;gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;100

&lt;span class=&quot;c&quot;&gt;# 回滾只要一行&lt;/span&gt;
gcloud run services update-traffic line-research-bot &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;asia-east1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--to-revisions&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&amp;lt;上一個 revision&amp;gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;100
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;冒煙測試&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;預期&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;結果&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /readyz&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;200&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /webhook&lt;/code&gt; 錯誤簽章&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;401&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /tasks/run-research&lt;/code&gt; 沒帶 OIDC token&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;401&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;啟動 log 的 model 欄位&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;預期的模型名稱&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;注意-4cloud-tasks-預設的-dispatch-deadline-只有-10-分鐘&quot;&gt;注意 4：Cloud Tasks 預設的 dispatch deadline 只有 10 分鐘&lt;/h2&gt;

&lt;p&gt;這是改寫時翻 Python 版程式碼發現的潛在問題。研究任務是透過 Cloud Tasks 打回自己的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tasks/run-research&lt;/code&gt; 執行的，Cloud Run 的 timeout 是 3600 秒沒錯，&lt;strong&gt;但 Cloud Tasks 對 HTTP target 的預設 dispatch deadline 只有 10 分鐘&lt;/strong&gt;。超過 10 分鐘還沒回應，Cloud Tasks 會判定失敗並&lt;strong&gt;重送&lt;/strong&gt;（queue 設定 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;max-attempts=3&lt;/code&gt;），同一個研究就會被重跑，Gemini 帳單跟著翻倍。&lt;/p&gt;

&lt;p&gt;Go 版在 &lt;a href=&quot;https://github.com/kkdai/line-research-bot-go/blob/main/internal/tasks/dispatcher.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/tasks/dispatcher.go&lt;/code&gt;&lt;/a&gt; 建立 task 時直接設成上限 30 分鐘：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;Task&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cloudtaskspb&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;DispatchDeadline&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;durationpb&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;New&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;m&quot;&gt;30&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Minute&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;MessageType&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cloudtaskspb&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Task_HttpRequest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;HttpRequest&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cloudtaskspb&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;HttpRequest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;c&quot;&gt;/* ... */&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;同時，Python 版的使用者鎖 TTL 只有 300 秒，代表任務還沒跑完，使用者再傳一個題目就能拿到鎖，兩個任務同時改同一個 workspace。Go 版把 &lt;strong&gt;鎖的 TTL 設成 35 分鐘（大於 dispatch deadline）&lt;/strong&gt;，任務結束時一樣主動釋放。&lt;/p&gt;

&lt;h2 id=&quot;注意-5--allow-unauthenticated-之下cloud-tasks-的端點要自己驗-oidc&quot;&gt;注意 5：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--allow-unauthenticated&lt;/code&gt; 之下，Cloud Tasks 的端點要自己驗 OIDC&lt;/h2&gt;

&lt;p&gt;LINE Webhook 必須能從外部打進來，所以整個服務是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--allow-unauthenticated&lt;/code&gt;。&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/webhook&lt;/code&gt; 有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Line-Signature&lt;/code&gt; 保護沒問題，但 Python 版的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tasks/run-research&lt;/code&gt; &lt;strong&gt;完全沒有驗證&lt;/strong&gt;：任何知道網址的人都能 POST 一個 JSON，觸發一次要燒 Gemini 費用的完整研究。&lt;/p&gt;

&lt;p&gt;Cloud Tasks 在建立 task 時本來就會帶 OIDC token，只是 Python 版的接收端沒有去驗。Go 版在 &lt;a href=&quot;https://github.com/kkdai/line-research-bot-go/blob/main/cmd/server/main.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/server/main.go&lt;/code&gt;&lt;/a&gt; 用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/api/idtoken&lt;/code&gt; 補上：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;oidcVerifier&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;audience&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;saEmail&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;server&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TokenVerifier&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bearer&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;p&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;idtoken&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Validate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bearer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;audience&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;c&quot;&gt;// audience = 服務網址 + /tasks/run-research&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;email&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;p&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Claims&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;email&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;email&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;saEmail&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Errorf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;unexpected token email %q&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;email&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;幾個要對齊的細節：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;audience 兩邊要一致&lt;/strong&gt;：建立 task 時明確指定 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OidcToken.Audience&lt;/code&gt;，接收端驗同一個值（我用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CLOUD_RUN_SERVICE_URL + &quot;/tasks/run-research&quot;&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Service Account 要能 actAs 自己&lt;/strong&gt;：Cloud Tasks 要幫你用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line-bot-sa&lt;/code&gt; 簽 OIDC token，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line-bot-sa&lt;/code&gt; 需要在自己身上有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/iam.serviceAccountUser&lt;/code&gt;，再加上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/cloudtasks.enqueuer&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CLOUD_RUN_SERVICE_URL&lt;/code&gt; 是雞生蛋問題&lt;/strong&gt;：第一次部署前不知道網址，所以 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy.sh&lt;/code&gt; 是先部署、再 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services update --update-env-vars=CLOUD_RUN_SERVICE_URL=...&lt;/code&gt;。部署回同一個服務時這個值會被繼承，不用重設。&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;注意-6這次不需要---no-cpu-throttling最小-instance-也可以是-0&quot;&gt;注意 6：這次&lt;strong&gt;不需要&lt;/strong&gt; &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;，最小 instance 也可以是 0&lt;/h2&gt;

&lt;p&gt;上一篇 linebot-helper 我花了一整段講「沒加 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;，背景 goroutine 會被凍結」。這次的架構剛好相反：&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/webhook&lt;/code&gt; 只做驗章、分類、取鎖、enqueue，&lt;strong&gt;同步做完才回 200&lt;/strong&gt;，沒有背景 goroutine。&lt;/li&gt;
  &lt;li&gt;真正耗時的研究是在 &lt;strong&gt;Cloud Tasks 打進來的那個 HTTP request 裡&lt;/strong&gt;跑完的，request 從頭到尾都開著，Cloud Run 不會限制 CPU，也不會把這台 instance 縮掉。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;所以預設的「只在處理 request 時分配 CPU」完全夠用，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--min-instances&lt;/code&gt; 也可以維持 0。Go 冷啟動不到 1 秒，LINE reply token 大約有 1 分鐘的有效期，來得及。&lt;strong&gt;要不要開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;，取決於工作是在 request 裡做還是 request 外做。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;唯一要小心的是釋放鎖：handler 結束時 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r.Context()&lt;/code&gt; 可能已經被取消，所以我用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;context.WithoutCancel(ctx)&lt;/code&gt; 去釋放 Firestore 的鎖，確保一定放得掉。&lt;/p&gt;

&lt;h2 id=&quot;注意-7沒有本機-docker-也能部署--source-會用-cloud-build&quot;&gt;注意 7：沒有本機 Docker 也能部署，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--source=.&lt;/code&gt; 會用 Cloud Build&lt;/h2&gt;

&lt;p&gt;我的筆電沒有裝 Docker。&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run deploy --source=.&lt;/code&gt; 看到目錄裡有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dockerfile&lt;/code&gt; 就會直接丟給 Cloud Build 建置。這次的 Bot 不需要 Chromium 或 ffmpeg，所以可以放心用最精簡的 distroless：&lt;/p&gt;

&lt;div class=&quot;language-dockerfile highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;FROM&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s&quot;&gt;golang:1.27&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;k&quot;&gt;AS&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s&quot;&gt;build&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;WORKDIR&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; /src&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;COPY&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; go.mod go.sum ./&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;RUN &lt;/span&gt;go mod download
&lt;span class=&quot;k&quot;&gt;COPY&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; cmd/ ./cmd/&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;COPY&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; internal/ ./internal/&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;RUN &lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;CGO_ENABLED&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;0 go build &lt;span class=&quot;nt&quot;&gt;-trimpath&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-ldflags&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;-s -w&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-o&lt;/span&gt; /out/server ./cmd/server

&lt;span class=&quot;k&quot;&gt;FROM&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; gcr.io/distroless/static-debian12:nonroot&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;COPY&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; --from=build /out/server /server&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;USER&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; nonroot:nonroot&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;ENTRYPOINT&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; [&quot;/server&quot;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Go 版沒有任何外部執行檔相依，prompt 也是用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go:embed&lt;/code&gt; 編進 binary，所以最終映像檔就是一個靜態執行檔，不需要另外 COPY 任何資料檔。&lt;/p&gt;

&lt;h2 id=&quot;注意-8同一個服務line-webhook-網址不用換但要用-api-驗證&quot;&gt;注意 8：同一個服務，LINE Webhook 網址不用換，但要用 API 驗證&lt;/h2&gt;

&lt;p&gt;部署完我本來想去 LINE Developers Console 改 Webhook URL，後來想到：&lt;strong&gt;新版是部署回同一個 Cloud Run 服務，網址根本沒變&lt;/strong&gt;。與其開 Console 用眼睛比對，不如用 Channel Access Token 直接問 LINE：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;TOKEN&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;$(&lt;/span&gt;gcloud secrets versions access latest &lt;span class=&quot;nt&quot;&gt;--secret&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;LINE_CHANNEL_ACCESS_TOKEN&lt;span class=&quot;si&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# 目前設定的 webhook 與是否啟用&lt;/span&gt;
curl &lt;span class=&quot;nt&quot;&gt;-s&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;Authorization: Bearer &lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$TOKEN&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  https://api.line.me/v2/bot/channel/webhook/endpoint

&lt;span class=&quot;c&quot;&gt;# 請 LINE 實際打一次 webhook&lt;/span&gt;
curl &lt;span class=&quot;nt&quot;&gt;-s&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-X&lt;/span&gt; POST &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;Authorization: Bearer &lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$TOKEN&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;Content-Type: application/json&apos;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;-d&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;{&quot;endpoint&quot;:&quot;&amp;lt;YOUR_SERVICE_URL&amp;gt;/webhook&quot;}&apos;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  https://api.line.me/v2/bot/channel/webhook/test
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;我在 script 裡直接比對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;endpoint&lt;/code&gt; 是否等於「服務網址 + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/webhook&lt;/code&gt;」，只印出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MATCH&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DIFFERENT&lt;/code&gt;，網址本身不會出現在終端機上。test API 回 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&quot;success&quot;:true,&quot;statusCode&quot;:200}&lt;/code&gt;，代表 LINE 的流量已經在打 Go 版了。&lt;/p&gt;

&lt;h2 id=&quot;注意-9用假使用者做端對端測試時別讓-line-推播失敗觸發整條-pipeline-重跑&quot;&gt;注意 9：用假使用者做端對端測試時，別讓 LINE 推播失敗觸發整條 pipeline 重跑&lt;/h2&gt;

&lt;p&gt;冒煙測試只能證明服務活著，我還想驗證 &lt;strong&gt;webhook → Cloud Tasks（OIDC）→ ADK → Firestore → GCS&lt;/strong&gt; 整條路在正式環境上是通的，但又不想用真實使用者測。做法是用 Secret Manager 的 Channel Secret 對一個&lt;strong&gt;假的 userId&lt;/strong&gt; 的訊息正確簽章，直接打 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/webhook&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;SIG&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;$(&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;printf&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;%s&apos;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$BODY&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; | openssl dgst &lt;span class=&quot;nt&quot;&gt;-sha256&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-hmac&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$SECRET&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-binary&lt;/span&gt; | &lt;span class=&quot;nb&quot;&gt;base64&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;)&lt;/span&gt;
curl &lt;span class=&quot;nt&quot;&gt;-X&lt;/span&gt; POST &lt;span class=&quot;nt&quot;&gt;-H&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;X-Line-Signature: &lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$SIG&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-d&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$BODY&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$URL&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;/webhook&quot;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;LINE 的 reply 和 push 一定會因為 userId / replyToken 是假的而回 400，這是預期中的事，但這也讓我注意到一個設計問題：&lt;strong&gt;最後推 Flex 卡片失敗時，如果 worker 回傳 error，handler 就會回 500，Cloud Tasks 會把整個 3 分鐘、要花錢的研究流程重跑一遍&lt;/strong&gt;。所以 Go 版把所有 LINE push 失敗都改成「記 log、不回錯誤」，只有 Firestore 這類基礎設施錯誤才讓 Cloud Tasks 重試。&lt;/p&gt;

&lt;p&gt;這次端對端在正式環境約 33 秒跑完，Firestore 的 report / workspace 正確寫入、鎖有釋放、GCS 上的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;index.html&lt;/code&gt; 標題與版本 banner 正確。測完記得把假使用者的 Firestore 文件跟 GCS 物件清掉。&lt;/p&gt;

&lt;h2 id=&quot;注意-10升級到最新的-go-patch-版並用-govulncheck-確認&quot;&gt;注意 10：升級到最新的 Go patch 版，並用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;govulncheck&lt;/code&gt; 確認&lt;/h2&gt;

&lt;p&gt;改寫時本機是 Go 1.26.1，但查了一下最新版已經是 &lt;strong&gt;1.27.3&lt;/strong&gt;。升級很簡單，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go get&lt;/code&gt; 會順便改好 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go.mod&lt;/code&gt; 並自動下載 toolchain：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;go get go@1.27.3 toolchain@none
go run golang.org/x/vuln/cmd/govulncheck@latest ./...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dockerfile&lt;/code&gt; 的 build image 也記得從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang:1.26&lt;/code&gt; 改成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang:1.27&lt;/code&gt;。&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;govulncheck&lt;/code&gt; 的結果是「&lt;strong&gt;你的程式碼受影響的漏洞：0&lt;/strong&gt;」，但依賴模組裡還有 3 個沒有被呼叫到的漏洞：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang.org/x/net&lt;/code&gt; 的兩個升到 v0.62.0 就修掉了，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang.org/x/crypto&lt;/code&gt; 那一個官方還沒有釋出修正版本。&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;govulncheck&lt;/code&gt; 會區分「有沒有被呼叫到」，這比單純掃 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go.mod&lt;/code&gt; 版本號實用很多。&lt;/strong&gt;&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;六順手修掉的東西改寫是重新審視設計的好時機&quot;&gt;六、順手修掉的東西：改寫是重新審視設計的好時機&lt;/h1&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Python 版&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Go 版&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tasks/run-research&lt;/code&gt; 驗證&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;無&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Cloud Tasks OIDC（audience + SA email）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Cloud Tasks dispatch deadline&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;預設 10 分鐘，長任務會被重送&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;30 分鐘&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;使用者鎖 TTL&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;300 秒&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;35 分鐘，任務結束主動釋放&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retry_publish&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;再叫一次 Agent 讀 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;report.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;直接用 Firestore 裡的 Markdown，不需要 LLM&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;deepen 版本號&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;相信模型回傳的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;new_version&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;程式自己算 previous + 1&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;報告 HTML&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;模型輸出的 raw HTML 會被渲染、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;title&amp;gt;&lt;/code&gt; 沒跳脫&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;goldmark 預設不渲染 raw HTML、title 有 escape&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LINE push 失敗&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;例外往上丟 → 500 → Cloud Tasks 重跑&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;只記 log，不觸發重跑&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;執行環境&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Python 3.11 slim&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Go 1.27.3 distroless/static，nonroot&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;測試方面，Go 版有兩層：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;單元測試&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test ./...&lt;/code&gt;，不需要 GCP）：worker 用 fake store / agents / LINE / publisher，涵蓋新研究、各 stage 失敗、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retry_write&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retry_publish&lt;/code&gt;、deepen、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chapter_not_found&lt;/code&gt;（含模型亂回的情況）、workspace 遺失；server 涵蓋簽章、鎖、enqueue 失敗回滾、OIDC、recall / reset / 閒聊。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;整合測試&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test -tags integration&lt;/code&gt;）：打真的 Vertex AI 跑完三個 stage，再測一次深化不存在的章節。換模型或升級 ADK 時，這組測試是唯一能抓到前面那種模型行為差異的方法。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;七最後一個資安提醒公開的-issue-也不要出現-cloud-run-網址&quot;&gt;七、最後一個資安提醒：公開的 Issue 也不要出現 Cloud Run 網址&lt;/h1&gt;

&lt;p&gt;兩個 repo 都是公開的，Issue 跟 PR 也都是公開的。整個過程我刻意做了幾件事：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;Issue 第一段就寫明「本 issue 為公開紀錄，&lt;strong&gt;不會&lt;/strong&gt;貼出任何 Cloud Run 服務網址、Secret 值或內部識別資訊」。&lt;/li&gt;
  &lt;li&gt;所有會印出網址的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 指令，輸出都先用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sed -E &apos;s#https?://[^ ]+#&amp;lt;url&amp;gt;#g&apos;&lt;/code&gt; 遮掉，或只把網址存在 shell 變數裡、只印比對結果。&lt;/li&gt;
  &lt;li&gt;送 PR 前 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git diff main | grep run.app&lt;/code&gt;，確認新加的程式碼與文件裡沒有真實網址（被抓到的只有已刪除的 Python 測試裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://x.run.app&lt;/code&gt; 假網址）。&lt;/li&gt;
  &lt;li&gt;開新的公開 repo 之前，把&lt;strong&gt;整段 git 歷史&lt;/strong&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git log --all -p&lt;/code&gt;）掃一遍，確認真實的服務 hostname 一次都沒出現過，才用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gh repo create --public --source=. --push&lt;/code&gt; 推上去。新 repo 是公開的，舊 commit 裡的東西也會一起公開。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/webhook&lt;/code&gt; 有 LINE 簽章、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tasks/run-research&lt;/code&gt; 有 OIDC，就算網址外洩也打不進來；但一個公開的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.run.app&lt;/code&gt; 網址還是會引來掃描器跟沒意義的流量，&lt;strong&gt;能不公開就不要公開&lt;/strong&gt;。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;八python-managed-agents--go-adk-遷移自我檢查清單checklist&quot;&gt;八、Python Managed Agents → Go ADK 遷移自我檢查清單（Checklist）&lt;/h1&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;1. 先盤點線上設定&lt;/strong&gt;：用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services describe&lt;/code&gt; 撈出 SA、環境變數、Secret 綁定、memory、timeout，不要相信 repo 裡可能已經過時的 deploy script。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;2. 先做模型可行性驗證&lt;/strong&gt;：用你的專案、你的 location 實際打一次，確認模型存在、而且支援你需要的工具組合（例如 Google Search + URL Context + OutputSchema）。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;3. 沙箱檔案 → Session State&lt;/strong&gt;：把 Managed Agents 沙箱裡跨回合的檔案，對應成 ADK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{state}&lt;/code&gt; placeholder，並持久化到 Firestore 之類的外部儲存，讓 Cloud Run instance 保持無狀態。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;4. 檢查 instruction 裡的大括號&lt;/strong&gt;：ADK 會把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{識別字}&lt;/code&gt; 當成 state 變數，搬 prompt 時把 JSON 範例清乾淨，最好寫測試擋住。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;5. 用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; 取代 prompt 約束&lt;/strong&gt;，但保留一個寬鬆的 JSON parser 當保險，錯誤碼欄位盡量用 enum。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;6. 同一個服務用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-traffic --tag&lt;/code&gt;（tag ≥ 3 字元）&lt;/strong&gt;，冒煙測試通過才 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update-traffic&lt;/code&gt;，並記下回滾用的 revision。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;7. 不帶 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--set-env-vars&lt;/code&gt; 就會沿用上一版的環境變數與 Secret&lt;/strong&gt;，部署後再 describe 確認一次。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;8. Cloud Tasks&lt;/strong&gt;：dispatch deadline 設到需要的長度（最長 30 分鐘），鎖的 TTL 要大於它，接收端一定要驗 OIDC token。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;9. 只有在 request 外還有工作時才需要 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;&lt;/strong&gt;；工作都在 Cloud Tasks 的 request 裡做的話，min-instances 0 就很夠用。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;10. 用 LINE API 驗證 webhook&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /v2/bot/channel/webhook/endpoint&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST .../webhook/test&lt;/code&gt;，比用眼睛看 Console 可靠。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;11. 外部通知失敗不要觸發整條 pipeline 重試&lt;/strong&gt;，只讓基礎設施錯誤回 5xx。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;12. 升到最新 Go patch 版並跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;govulncheck&lt;/code&gt;&lt;/strong&gt;，公開 repo 的 Issue / PR / README 不留真實服務網址。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;小結與開源專案連結&quot;&gt;小結與開源專案連結&lt;/h1&gt;

&lt;p&gt;這次把 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 從 Python + Managed Agents 改寫成 Go + ADK for Go 的 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，幾個最值得帶走的收穫：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Managed Agents 和 ADK 是兩種取捨&lt;/strong&gt;：前者幫你管沙箱和檔案系統，後者讓 Agent 跑在你自己的程式裡。當沙箱的價值只剩「記住三個檔案」時，ADK 的 Session State + Firestore 反而更簡單、更好測。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OutputSchema&lt;/code&gt; + 內建工具是 ADK for Go 很實用的組合&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;set_model_response&lt;/code&gt; 讓模型可以先上網查資料，再交出強型別的結果，但前提是你挑的模型支援。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;部署回同一個服務時，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-traffic --tag&lt;/code&gt; 是最安心的切換方式&lt;/strong&gt;：環境變數、Secret、Webhook 網址都不用動，回滾也只要一行。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;改寫是重新審視設計的最好時機&lt;/strong&gt;：這次順手補上的 OIDC 驗證、30 分鐘 dispatch deadline、不重跑 pipeline 的 push 失敗處理，在 Python 版其實都是潛在的問題。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Go 版完整程式碼在 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，改寫過程的逐步紀錄在 &lt;a href=&quot;https://github.com/kkdai/line-research-bot/issues/1&quot;&gt;Issue #1&lt;/a&gt;，歡迎參考與交流！&lt;/p&gt;

&lt;h2 id=&quot;延伸閱讀&quot;&gt;延伸閱讀&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.evanlin.com/agents-api/&quot;&gt;Google Managed Agents API 全解析（本 Bot 的 Python 版）&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/line-research-bot-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-research-bot-go&lt;/code&gt;：本文的 Go 版完整程式碼&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/google/adk-go&quot;&gt;ADK for Go on GitHub&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://google.github.io/adk-docs/&quot;&gt;ADK 官方文件&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://cloud.google.com/tasks/docs/reference/rest/v2/projects.locations.queues.tasks#Task.FIELDS.dispatch_deadline&quot;&gt;Cloud Tasks：HTTP target 的 dispatch deadline&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration&quot;&gt;Cloud Run：使用 revision tag 測試新版本&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
				<pubDate>Mon, 02 Nov 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/line-research-bot-python-to-go-adk/</link>
				<guid isPermaLink="true">https://www.evanlin.com/line-research-bot-python-to-go-adk/</guid>
			</item>
		
			<item>
				<title>[AI 實戰] 把日常主力 LINE Bot 從 Python 改寫成 Go 1.26 並搬上 Cloud Run：機器規格砍到 1/4、導入 Google ADK v1.9.0 與零停機遷移實錄</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/linebot-helper-go-cloudrun-arch.png&quot; alt=&quot;LINE Bot Helper: Python to Go 1.26 &amp;amp; Cloud Run Architecture (ADK v1.9.0)&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前情提要&quot;&gt;前情提要&lt;/h1&gt;

&lt;p&gt;我有一個自己每天重度使用的主力 LINE Bot：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-python&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-helper-python&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;最初它只是一個「丟網址進去、回傳繁體中文摘要」的小工具，但過去一年半裡，我陸續往裡面塞進了各式各樣的 Gemini 新能力：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;多來源內容載入與文件轉檔&lt;/strong&gt;：網頁三層爬蟲 Fallback Chain（HTTP $\rightarrow$ Firecrawl $\rightarrow$ SingleFile Headless Chromium）、YouTube 影片摘要、PDF / Word / PPT / Excel / EPUB 自動轉 Markdown，以及一鍵產出 FB / LinkedIn / Threads 社群爆款文案 Carousel。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;書籤與 Grounding 深度研究報告&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/save&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/list&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/search&lt;/code&gt; 書籤管理，點擊卡片上的「📄 詳細研究報告」就會結合 Google Search Grounding 寫出一份完整 Markdown 報告，渲染成獨立 HTML 網頁（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/reports/{id}&lt;/code&gt;）並永久保存在 Cloud Firestore。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Google Maps Grounding 與 Gemini Batch API 美食大數據分析&lt;/strong&gt;：傳送 LINE 位置座標搜尋附近加油站、停車場與餐廳，還能針對特定餐廳抓出 50+ 則最新評論，丟進 &lt;strong&gt;Gemini Batch API&lt;/strong&gt;（享 50% 成本折扣）跑深度招牌菜與雷點分析，透過 Webhook 或背景輪詢推播回 LINE。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Agentic Vision 視覺標註&lt;/strong&gt;：上傳圖片後讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt; 寫 Python Code 畫出標註框（Bounding Box），轉存成圖片推回聊天室。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;LINE 語音訊息 TTS 與 LIFF 即時雙向語音助手&lt;/strong&gt;：語音訊息自動轉錄並搭配 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.1-flash-tts-preview&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt; 產生 M4A 語音朗讀；打開 LIFF 還能透過 WebSocket 雙向串流 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.1-flash-live-preview&lt;/code&gt;，支援免持 VAD、Barge-in 打斷與 Live Tool Calling。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;功能很爽，但代價也很明顯：&lt;strong&gt;Python + FastAPI + 一大票文件解析與 AI 套件的常駐記憶體越來越高&lt;/strong&gt;，為了讓背景任務與多併發不卡頓，這台 Cloud Run 服務不知不覺已經開到了 &lt;strong&gt;4 vCPU / 4 GiB Memory&lt;/strong&gt;（且開啟 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;）。&lt;/p&gt;

&lt;p&gt;身為一個長期寫 Go 的人，看著一台個人日常助理吃掉 4 vCPU / 4 GiB 實在有點忍不下去了。於是決定動手做一件事：&lt;strong&gt;把整套 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-python&lt;/code&gt; 100% 改寫成 Go 1.26 最新版（&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-helper-go&lt;/code&gt;&lt;/a&gt;），直接部署到同一個 GCP 專案的 Cloud Run 上，並且做到與舊版共享 Firestore 資料、隨時可零停機切換。&lt;/strong&gt;&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一改寫前先立規矩用-github-issues-拆解-11-個里程碑&quot;&gt;一、改寫前先立規矩：用 GitHub Issues 拆解 11 個里程碑&lt;/h1&gt;

&lt;p&gt;把一個將近 90KB &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main.py&lt;/code&gt; 外加十幾個模組的 Python 專案完整搬到 Go，如果沒有先拆好邊界、邊寫邊測，很容易寫出一座無法維護的新迷宮。&lt;/p&gt;

&lt;p&gt;因此在建立 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-helper-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 之後，第一件事不是寫 Code，而是對照 Python 版的所有功能，先在 GitHub 開出 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/12&quot;&gt;Tracking Issue #12&lt;/a&gt;&lt;/strong&gt; 與 &lt;strong&gt;11 個子任務 Issues（&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/1&quot;&gt;#1&lt;/a&gt; ~ &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/11&quot;&gt;#11&lt;/a&gt;）&lt;/strong&gt;，每個 Issue 對應一個獨立套件與完整的單元測試：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;里程碑 Issue&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;對應 Go 套件&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;核心職責與相容性重點&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/1&quot;&gt;#1&lt;/a&gt; 專案骨架與 Dockerfile&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main.go&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/config&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Go 1.26 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;net/http&lt;/code&gt;、環境變數 100% 相容 Python 版、Multi-stage Dockerfile（整合 Chromium / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;single-file&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt;）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/2&quot;&gt;#2&lt;/a&gt; Gemini 雙通道客戶端&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/gemini&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;同時支援 &lt;strong&gt;Vertex AI (ADC)&lt;/strong&gt; 與 &lt;strong&gt;Gemini Developer API (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_AI_API_KEY&lt;/code&gt;)&lt;/strong&gt;，涵蓋 Grounding、Code Execution 與 TTS&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/3&quot;&gt;#3&lt;/a&gt; Firestore 持久化層&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/firestore&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/services&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;完全相容 Python 版 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chat_sessions&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bookmarks&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;reports&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;batch_jobs&lt;/code&gt; 四大 Collection Schema，無憑證時自動降級為記憶體儲存&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/4&quot;&gt;#4&lt;/a&gt; LINE Messaging API 與 Flex&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/line&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;HMAC-SHA256 簽章驗證、Reply / Push / Loading Animation、社群文案與書籤 Flex Carousel 組裝&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/5&quot;&gt;#5&lt;/a&gt; 網址爬蟲與多格式文件轉換&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/loader&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;HTTP（含 PTT &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;over18=1&lt;/code&gt;）$\rightarrow$ Firecrawl $\rightarrow$ SingleFile 三層時限預算 Fallback，以及 PDF / DOCX / PPTX / XLSX / EPUB / ODF 轉 Markdown&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/6&quot;&gt;#6&lt;/a&gt; AI 工具集&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/ai&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;摘要、社群爆款文案、Grounding 研究報告、YouTube 分析、Agentic Vision、GitHub Issues 彙整、Maps 搜尋&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/7&quot;&gt;#7&lt;/a&gt; ADK Orchestrator 與專職 Agents&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/agents&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;整合官方 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk v1.9.0&lt;/code&gt;，建立 Root &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Orchestrator&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Chat&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Content&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Location&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Vision&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GitHub&lt;/code&gt; 5 個專職 Agent&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/8&quot;&gt;#8&lt;/a&gt; 非同步 Webhook 與 Postback&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/handlers&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Webhook 秒回 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt;、背景 Goroutine 處理事件、9 種 Postback 分派與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/reports/{id}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/images/{id}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/audio/{id}&lt;/code&gt; 端點&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/9&quot;&gt;#9&lt;/a&gt; Gemini Batch API 美食分析&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/services/batch_service.go&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;JSONL 批次工作上傳、Static HMAC Webhook、Dynamic RS256 JWKS Webhook 驗證與 60 秒背景輪詢&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/10&quot;&gt;#10&lt;/a&gt; LIFF 即時語音助手&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/voice&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;static/liff&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/ws/voice/{session_id}&lt;/code&gt; 雙向 WebSocket Relay、Push-to-Talk / 免持 VAD、Barge-in、Session Resumption 與 Live Tool Calling&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/11&quot;&gt;#11&lt;/a&gt; Cloud Run 部署與驗證&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Cloud Run (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us-central1&lt;/code&gt;)&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;沿用 Python 版線上環境變數部署，壓測並調降容器資源規格&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;整體架構如下圖所示：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
    subgraph Client[&quot;LINE 客戶端與 LIFF&quot;]
        LINE[&quot;LINE App 聊天室&amp;lt;br/&amp;gt;(文字 / 網址 / 圖片 / 語音 / 位置 / Postback)&quot;]
        LIFF[&quot;LIFF 即時語音助手&amp;lt;br/&amp;gt;(/liff/ + WebSocket PCM 16kHz/24kHz)&quot;]
    end

    subgraph CloudRun[&quot;Google Cloud Run: linebot-helper-go (Go 1.26, 1 vCPU / 1 GiB)&quot;]
        Mux[&quot;Go 1.26 net/http Server&amp;lt;br/&amp;gt;(HMAC 驗證 + 立即回傳 200 OK)&quot;]
        VoiceRelay[&quot;internal/voice&amp;lt;br/&amp;gt;Gemini Live BidiGenerateContent Relay&quot;]
        Orch[&quot;internal/agents (google.golang.org/adk v1.9.0)&amp;lt;br/&amp;gt;Root Orchestrator + 5 Sub-Agents&quot;]
        Loader[&quot;internal/loader&amp;lt;br/&amp;gt;HTTP -&amp;gt; Firecrawl -&amp;gt; SingleFile&amp;lt;br/&amp;gt;+ PDF/Office/EPUB 轉 Markdown&quot;]
        BatchSvc[&quot;internal/services/batch_service&amp;lt;br/&amp;gt;Gemini Batch API + JWKS/HMAC Webhook + 60s Poller&quot;]
    end

    subgraph GCP[&quot;Google Cloud &amp;amp; AI 後端&quot;]
        Vertex[&quot;Vertex AI / Gemini Developer API&amp;lt;br/&amp;gt;(Search Grounding / Maps / Vision / TTS / Live)&quot;]
        FS[(&quot;Cloud Firestore&amp;lt;br/&amp;gt;chat_sessions | bookmarks&amp;lt;br/&amp;gt;reports | batch_jobs&quot;)]
    end

    LINE --&amp;gt;|&quot;POST /&quot;| Mux
    LIFF &amp;lt;--&amp;gt;|&quot;GET /ws/voice/{id}&quot;| VoiceRelay
    Mux --&amp;gt; Orch
    Mux --&amp;gt; Loader
    Mux --&amp;gt; BatchSvc
    VoiceRelay &amp;lt;--&amp;gt;|&quot;WebSocket&quot;| Vertex
    VoiceRelay -.-&amp;gt;|&quot;delegate_to_orchestrator&quot;| Orch
    Orch --&amp;gt; Vertex
    Orch --&amp;gt; Loader
    Orch &amp;lt;--&amp;gt; FS
    BatchSvc &amp;lt;--&amp;gt; Vertex
    BatchSvc &amp;lt;--&amp;gt; FS
&lt;/code&gt;&lt;/pre&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二五個在改寫過程中特別有感的工程設計&quot;&gt;二、五個在改寫過程中特別有感的工程設計&lt;/h1&gt;

&lt;h2 id=&quot;1-vertex-ai-與-developer-api-雙軌並行的-gemini-client&quot;&gt;1. Vertex AI 與 Developer API 雙軌並行的 Gemini Client&lt;/h2&gt;

&lt;p&gt;在這個 LINE Bot 裡，並不是所有功能都走同一個 Gemini 端點：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;一般對話、Grounding 搜尋、Google Maps Grounding、圖片分析&lt;/strong&gt;：走 &lt;strong&gt;Vertex AI&lt;/strong&gt;（使用 Cloud Run 服務帳號的 Application Default Credentials，不需 API Key）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Native TTS 語音合成（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.1-flash-tts-preview&lt;/code&gt;）、Gemini Batch API 與 Gemini Live API WebSocket&lt;/strong&gt;：走 &lt;strong&gt;Gemini Developer API&lt;/strong&gt;（使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_AI_API_KEY&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Agentic Vision（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3-flash-preview&lt;/code&gt; + Code Execution）&lt;/strong&gt;：優先走 Developer API，若未設定 Key 則自動 Fallback 回 Vertex AI。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;在 Go 版 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/blob/main/internal/gemini/client.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/gemini/client.go&lt;/code&gt;&lt;/a&gt; 中，我們把這兩條路徑收斂在同一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini.Client&lt;/code&gt; 底下，連 TTS 吐回來的 Raw PCM（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;24kHz, 16-bit, mono&lt;/code&gt;）透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt; 轉成 LINE 支援的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;audio/mp4&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.m4a&lt;/code&gt;）並計算音訊毫秒數，都在同一個模組裡一氣呵成。&lt;/p&gt;

&lt;h2 id=&quot;2-100-相容-python-版的-firestore-schema實現零停機切換的關鍵&quot;&gt;2. 100% 相容 Python 版的 Firestore Schema（實現零停機切換的關鍵）&lt;/h2&gt;

&lt;p&gt;改寫服務最怕「切換過去後，使用者的對話記憶、存了一半的書籤或之前產生的研究報告網址全部失效」。&lt;/p&gt;

&lt;p&gt;為此，我們在 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/tree/main/internal/firestore&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/firestore&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/tree/main/internal/services&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/services&lt;/code&gt;&lt;/a&gt; 嚴格對齊了 Python 版的 4 個 Firestore Collection 名稱與欄位結構：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chat_sessions&lt;/code&gt;：儲存多輪對話歷史與使用者最後傳送的 GPS 座標（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;last_location&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bookmarks&lt;/code&gt;：儲存 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/save&lt;/code&gt; 書籤、社群文案候選書籤（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;status: candidate&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;saved&lt;/code&gt;），以及 7 天快取的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;report_id&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;report_generated_at&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;reports&lt;/code&gt;：儲存 Grounding 深度研究報告渲染好的完整 HTML（支援 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/reports/{report_id}&lt;/code&gt; 永久調閱）。&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;batch_jobs&lt;/code&gt;：儲存 Gemini Batch API 任務 ID 與 LINE &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;user_id&lt;/code&gt; 的映射。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;這意味著 &lt;strong&gt;Python 版與 Go 版可以同時掛在線上讀寫同一個 Firestore&lt;/strong&gt;。把 LINE Webhook 指過去的那一秒，所有舊書籤跟報告連結完全不受影響；萬一想切回 Python 版，也只需要改一行 Webhook URL。&lt;/p&gt;

&lt;h2 id=&quot;3-原生-go-實作多格式文件轉-markdown告別笨重的-python-文件套件&quot;&gt;3. 原生 Go 實作多格式文件轉 Markdown（告別笨重的 Python 文件套件）&lt;/h2&gt;

&lt;p&gt;Python 版用了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anydoc&lt;/code&gt; 等套件把 PDF、DOCX、PPTX、XLSX、ODT、EPUB、CSV、RTF 轉成 Markdown 再餵給 Gemini 摘要。這些套件在 Python 裡往往拉進一大串 C 擴充與相依套件。&lt;/p&gt;

&lt;p&gt;到了 Go 版 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/blob/main/internal/loader/doc_converter.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/loader/doc_converter.go&lt;/code&gt;&lt;/a&gt;，因為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.docx&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.pptx&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.xlsx&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.odt&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.epub&lt;/code&gt; 本質上全部都是 &lt;strong&gt;ZIP 封裝的 XML 檔案&lt;/strong&gt;，我們直接用 Go 標準庫的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;archive/zip&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;encoding/xml&lt;/code&gt; 搭配輕量的 PDF 文字提取器，不到幾百行純 Go 程式碼就把所有主流辦公文件與電子書格式乾乾淨淨轉成結構化 Markdown，編譯速度快、執行期幾乎零額外記憶體開銷！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三誠實面對架構python-版的概念型-adkvs-go-版真正導入-googlegolangorgadk-v190&quot;&gt;三、誠實面對架構：Python 版的「概念型 ADK」vs. Go 版真正導入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk v1.9.0&lt;/code&gt;&lt;/h1&gt;

&lt;p&gt;在檢查程式碼時，我們發現了一個很有趣的歷史痕跡：&lt;/p&gt;

&lt;p&gt;如果你打開原本 Python 版 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-python/blob/main/agents/orchestrator.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents/orchestrator.py&lt;/code&gt;&lt;/a&gt; 的開頭，會看到註解寫著：&lt;/p&gt;
&lt;blockquote&gt;
  &lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Orchestrator Agent - 基於 Google ADK 的主控 Agent&lt;/code&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;但如果你去翻 Python 版的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;requirements.txt&lt;/code&gt; 與整包原始碼，會發現&lt;strong&gt;裡面其實根本沒有安裝 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-adk&lt;/code&gt;&lt;/strong&gt;，也沒有任何一行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;from google.adk import ...&lt;/code&gt;！當時的 Python 版只是「借用 ADK 的分層概念」，用純 Python Class 手刻了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Orchestrator&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ChatAgent&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContentAgent&lt;/code&gt; 等類別，底層直接呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-genai&lt;/code&gt;。&lt;/p&gt;

&lt;p&gt;這次改寫成 Go 版，我們決定玩真的——直接在 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/blob/main/go.mod&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go.mod&lt;/code&gt;&lt;/a&gt; 引入 Google 官方最新的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk v1.9.0&lt;/code&gt;&lt;/strong&gt;（搭配 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/genai v1.57.0&lt;/code&gt;）：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;比較項目&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;原 Python 版 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-python&lt;/code&gt;)&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;新 Go 版 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt;)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;ADK 套件依賴&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;❌ 無（未安裝 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-adk&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;✅ &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk v1.9.0&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Agent 定義方式&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;自訂 Python Class&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.New(llmagent.Config{...})&lt;/code&gt; 建立 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agent.Agent&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Sub-Agents 階層&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;手動持有物件屬性&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Root &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;orchestrator&lt;/code&gt; 透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SubAgents: []agent.Agent{...}&lt;/code&gt; 掛載 5 個專職子 Agent&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Tools 綁定方式&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;手動方法呼叫&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;functiontool.New()&lt;/code&gt; 註冊型別安全的 Go 函式工具（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;load_url_content&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;summarize_youtube_video&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;search_nearby_places&lt;/code&gt;）&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Model 介面&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;直接呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.genai.Client&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;實作 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk/model.LLM&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adkgemini.NewModel&lt;/code&gt;（Vertex AI Backend）&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h3 id=&quot;下一步從建立-adk-agent-樹走向全面由-adk-runner-驅動issue-13&quot;&gt;下一步：從「建立 ADK Agent 樹」走向「全面由 ADK Runner 驅動」（&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/13&quot;&gt;Issue #13&lt;/a&gt;）&lt;/h3&gt;

&lt;p&gt;為了確保第一版遷移 100% 通過所有既有測試案例，目前 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessText&lt;/code&gt; 仍保留了原本的快速意圖路由。但我們已經在 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/13&quot;&gt;Issue #13 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[RFC] Google ADK (v1.9.0) 深度整合與架構演進提案&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt; 規劃好接下來最讓人期待的 5 個 ADK 升級：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runner.Runner&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SubAgents&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agenttool&lt;/code&gt; 取代硬編碼 Regex 路由&lt;/strong&gt;：讓使用者在 LINE 輸入複合指令（如「幫我查這篇文章提到的餐廳在哪裡，順便存進書籤」）時，由 ADK 自動轉移或平行呼叫多個 Sub-Agent。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;新增 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BookmarkAgent&lt;/code&gt; 與研究報告 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;functiontool&lt;/code&gt;&lt;/strong&gt;：使用者不必再背 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/save&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/search&lt;/code&gt; 斜線指令，直接用自然語言說「幫我找上次存過關於 MCP 的書籤並做成研究報告」就能觸發。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;實作對接 Cloud Firestore 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk/session.Service&lt;/code&gt;&lt;/strong&gt;：把現有的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;firestore.KVStore&lt;/code&gt; 封裝成標準 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;session.Service&lt;/code&gt;，讓 ADK Runner 原生管理跨輪次對話 Event 與狀態。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;導入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflowagents&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sequentialagent&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;parallelagent&lt;/code&gt;）&lt;/strong&gt;：將深度研究報告拆解為「擷取 $\rightarrow$ Google Search 查證 $\rightarrow$ 報告撰寫」序列工作流；將 FB / LinkedIn / Threads 爆款文案改為平行 Sub-Agents 同步產出。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;讓 LIFF 即時語音助手的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;delegate_to_orchestrator&lt;/code&gt; 直接串聯 ADK Runner&lt;/strong&gt;。&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四cloud-run-部署與瘦身機器規格直接砍到-14&quot;&gt;四、Cloud Run 部署與瘦身：機器規格直接砍到 1/4！&lt;/h1&gt;

&lt;p&gt;完成全部 10 個核心套件與單元測試後（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go vet ./... &amp;amp;&amp;amp; go test ./...&lt;/code&gt; 全數通過），我們直接將 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt; 部署上 Cloud Run。&lt;/p&gt;

&lt;p&gt;來看看同一個 GCP 專案上，Python 版與 Go 版的容器資源配置對比：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Cloud Run 服務&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;執行環境&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;CPU&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;Memory&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;Concurrency&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;CPU 分配模式&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;相對資源成本&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-python&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Python 3.11 + FastAPI&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;4 vCPU&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;4 GiB&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;80&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;Always allocated (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100%&lt;/code&gt; (基準)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Go 1.26 原生編譯&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;1 vCPU&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;1 GiB&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;160&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;Always allocated (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;25%&lt;/code&gt; (立省 75%)&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;你可能會問：&lt;strong&gt;Go 編譯出來的執行檔常駐記憶體才 20～30 MB，為什麼不乾脆開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;512 MiB&lt;/code&gt; 就好，要留 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 vCPU / 1 GiB&lt;/code&gt;？&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;這兩個數字背後都有實際的工程考量：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;為什麼是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 vCPU&lt;/code&gt;？&lt;/strong&gt;
因為 LINE Bot 需要在收到 Webhook 的瞬間秒回 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt;，並在背景 Goroutine 繼續跑 Gemini 生成、研究報告渲染，加上每 60 秒還有一個輪詢 Gemini Batch API 的背景 Ticker，所以必須開啟 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;（CPU always allocated）。而在 Cloud Run 的規範中，開啟 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt; 的最低 CPU 門檻就是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 vCPU&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;為什麼是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 GiB Memory&lt;/code&gt;？&lt;/strong&gt;
Go 程式本身確實不到 30 MB，但別忘了我們的網址爬蟲第 3 層 Fallback 在容器內裝了 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;single-file&lt;/code&gt; + Headless Chromium&lt;/strong&gt;（用來對付連 Firecrawl 都擋的動態渲染網站），再加上語音訊息合成需要呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt;。當 Headless Chromium 偶爾被喚醒時，瞬間會吃掉 300～400 MB 記憶體。保留 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 GiB&lt;/code&gt; 既能確保 Chromium 啟動時絕不 OOM，又能把機器成本直接砍到原本 Python 版的 &lt;strong&gt;1/4&lt;/strong&gt;！&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;部署指令非常乾淨：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;gcloud run deploy linebot-helper-go &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--source&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--project&lt;/span&gt; &amp;lt;YOUR_GCP_PROJECT_ID&amp;gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt; us-central1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--cpu&lt;/span&gt; 1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--memory&lt;/span&gt; 1Gi &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--allow-unauthenticated&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--no-cpu-throttling&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五雲端部署最容易踩坑與遺漏的-7-個魔鬼細節&quot;&gt;五、雲端部署最容易踩坑與遺漏的 7 個魔鬼細節&lt;/h1&gt;

&lt;p&gt;把 LINE Bot 從本機測試搬上 Cloud Run、或是從舊的 Python 服務切換到新的 Go 服務時，「程式編譯得過」往往只完成了 60%。真正的雷通常藏在 Cloud Run 的執行期生命週期、網路代理、容器沙盒與外部端點設定裡。&lt;/p&gt;

&lt;p&gt;以下整理這次部署過程中最容易被遺漏的 &lt;strong&gt;7 個關鍵盲點&lt;/strong&gt;：&lt;/p&gt;

&lt;h2 id=&quot;遺漏-1忘了加---no-cpu-throttling或是把-rcontext-傳進背景-goroutine&quot;&gt;遺漏 1：忘了加 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;，或是把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r.Context()&lt;/code&gt; 傳進背景 Goroutine&lt;/h2&gt;

&lt;p&gt;LINE Webhook 規範要求伺服器在收到事件後快速回傳 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt;，而我們的重度任務（例如耗時 1～2 分鐘的 Grounding 深度研究報告、Agentic Vision 寫 Code 畫圖、語音轉錄加 TTS，以及每 60 秒輪詢一次的 Gemini Batch API Poller）全部都是先回 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt;、再開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go func()&lt;/code&gt; 在背景跑完後用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PushMessage&lt;/code&gt; 推播。&lt;/p&gt;

&lt;p&gt;這裡有兩個新手與老手都極容易踩到的坑：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Cloud Run 預設會在 HTTP Response 送出瞬間「凍結 CPU」&lt;/strong&gt;：
如果不加 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;，只要 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;handleWebhookCallback&lt;/code&gt; 一 return &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt;，Cloud Run 會在幾十毫秒內把容器 CPU 降到接近 0。這時你的背景 Goroutine 就會像被按了暫停鍵一樣卡在半空中，直到幾分鐘後下一個 HTTP 請求進來才跟著動幾步，使用者永遠收不到推播！&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;背景 Goroutine 絕對不能沿用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r.Context()&lt;/code&gt;&lt;/strong&gt;：
在 Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;net/http&lt;/code&gt; 中，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r.Context()&lt;/code&gt; 會在 HTTP Handler 結束（送出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt;）的那一刻立刻觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Canceled&lt;/code&gt;！如果你順手寫了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go s.handleMessageEvent(r.Context(), event)&lt;/code&gt;，背景正在呼叫 Vertex AI 或 Firestore 的請求會直接死在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;context canceled&lt;/code&gt; 錯誤。&lt;/li&gt;
&lt;/ol&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;// ❌ 錯誤寫法：r.Context() 在 return 200 OK 瞬間就會被 cancel，背景任務必死&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;go&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;handleMessageEvent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;r&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;eventCopy&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;// ✅ 正確寫法：脫離 HTTP Request 生命週期，改用獨立的 Background Context（內部再依任務設 Timeout）&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;go&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;handleMessageEvent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Background&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;eventCopy&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;遺漏-2vertex-ai-google_cloud_locationglobal-的網域拼接陷阱&quot;&gt;遺漏 2：Vertex AI &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION=global&lt;/code&gt; 的網域拼接陷阱&lt;/h2&gt;

&lt;p&gt;在沿用舊版環境變數時，我們看到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION=global&lt;/code&gt;（因為許多 Gemini 3.x Preview 模型在 Vertex AI 是掛在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global&lt;/code&gt; Location 下）。&lt;/p&gt;

&lt;p&gt;如果你在寫 Go 的 Vertex AI REST Client 時，直接照一般區域的習慣用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;fmt.Sprintf(&quot;https://%s-aiplatform.googleapis.com&quot;, location)&lt;/code&gt;，當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;location&lt;/code&gt; 為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;global&quot;&lt;/code&gt; 時，拼出來的網址會變成：&lt;/p&gt;
&lt;blockquote&gt;
  &lt;p&gt;❌ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://global-aiplatform.googleapis.com&lt;/code&gt;（&lt;strong&gt;這個網域在 GCP 根本不存在，DNS lookup 會直接失敗！&lt;/strong&gt;）&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;在 Vertex AI 的規範中，只有區域端點（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us-central1&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;asia-east1&lt;/code&gt;）才有前綴；當 Location 為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global&lt;/code&gt; 時，必須切換為無前綴的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://aiplatform.googleapis.com&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;c&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;vertexEndpointBase&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;c&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;VertexBaseURL&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strings&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TrimRight&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;c&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;VertexBaseURL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;/&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;c&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Location&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;||&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;c&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Location&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;global&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;https://aiplatform.googleapis.com&quot;&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;https://%s-aiplatform.googleapis.com&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;c&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Location&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;遺漏-3用---set-env-vars-搬移環境變數導致特殊字元截斷或密鑰外洩&quot;&gt;遺漏 3：用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--set-env-vars&lt;/code&gt; 搬移環境變數導致特殊字元截斷或密鑰外洩&lt;/h2&gt;

&lt;p&gt;要把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-python&lt;/code&gt; 線上十幾個環境變數原封不動搬到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt; 時，千萬不要手拼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--set-env-vars=&quot;KEY1=VAL1,KEY2=VAL2...&quot;&lt;/code&gt;：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;只要 किसी Token 或 Prompt 字串裡帶有逗號 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;,&lt;/code&gt; 或等號 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;=&lt;/code&gt;，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 的參數解析就會切錯位置甚至直接報錯。&lt;/li&gt;
  &lt;li&gt;把環境變數直接攤在指令列參數裡，整串 Secret 就會留在終端機歷史紀錄或對話 Log 中。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;最穩妥的做法&lt;/strong&gt;：直接透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud run services describe --format=json&lt;/code&gt; 在本機背景轉出暫存的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/tmp/env.yaml&lt;/code&gt;，部署時用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--env-vars-file=/tmp/env.yaml&lt;/code&gt; 餵進去，部署完立刻 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rm -f /tmp/env.yaml&lt;/code&gt;。全程既不會印出任何一把 Secret，也能 100% 保留所有特殊字元。&lt;/p&gt;

&lt;h2 id=&quot;遺漏-4忽略-cloud-run-反向代理的-x-forwarded-proto導致-line-拒收圖片與音檔&quot;&gt;遺漏 4：忽略 Cloud Run 反向代理的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Forwarded-Proto&lt;/code&gt;，導致 LINE 拒收圖片與音檔&lt;/h2&gt;

&lt;p&gt;這個 LINE Bot 有四個地方需要動態組出「指向自己伺服器的公開網址」：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;研究報告頁面：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&amp;lt;host&amp;gt;/reports/{report_id}&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;Agentic Vision 標註圖片：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&amp;lt;host&amp;gt;/images/{image_id}&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;TTS 語音合成音檔：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&amp;lt;host&amp;gt;/audio/{audio_id}&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;Gemini Batch API Dynamic Webhook：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&amp;lt;host&amp;gt;/api/gemini-callback/dynamic&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;要注意的是：&lt;strong&gt;LINE Messaging API 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ImageMessage&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AudioMessage&lt;/code&gt; 強制要求網址必須是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&lt;/code&gt;&lt;/strong&gt;。而在 Cloud Run 架構下，HTTPS TLS 在外層的 Google Front End (GFE) 就已經終止了，進到容器內 Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;http.Request&lt;/code&gt; 時 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r.TLS&lt;/code&gt; 是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nil&lt;/code&gt;。如果你沒有去讀 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Forwarded-Proto&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Forwarded-Host&lt;/code&gt; 標頭，組出來的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;http://&lt;/code&gt; 網址傳給 LINE Push API 時會直接被拒絕！&lt;/p&gt;

&lt;h2 id=&quot;遺漏-5go-追求極簡映像檔scratch--distroless卻忘了外部執行檔與-chromium-沙盒限制&quot;&gt;遺漏 5：Go 追求極簡映像檔（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scratch&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;distroless&lt;/code&gt;）卻忘了外部執行檔與 Chromium 沙盒限制&lt;/h2&gt;

&lt;p&gt;寫 Go 服務時，我們很習慣用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FROM gcr.io/distroless/static&lt;/code&gt; 把 Docker Image 壓到 20MB 以下。但在這支多功能 LINE Bot 上這樣做會立刻撞牆：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;缺少 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt;&lt;/strong&gt;：TTS 語音合成收到 Gemini 回傳的 PCM 後呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;exec.Command(&quot;ffmpeg&quot;, ...)&lt;/code&gt; 轉 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.m4a&lt;/code&gt; 會直接報 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;executable file not found&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;缺少 Headless Chromium、中文字型與容器沙盒旗標&lt;/strong&gt;：
爬蟲第 3 層 Fallback 使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;single-file&lt;/code&gt; 驅動 Headless Chromium。在 Cloud Run 的容器沙盒環境裡，如果不給 Chromium 加上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-sandbox&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--disable-gpu&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--disable-dev-shm-usage&lt;/code&gt;（因為容器預設的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/dev/shm&lt;/code&gt; 共享記憶體很小），或者基底映像檔沒裝 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;fonts-noto-cjk&lt;/code&gt;（抓下來的中文網頁亂碼）與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ca-certificates&lt;/code&gt;（HTTPS 憑證驗證失敗），爬蟲在雲端就會無聲無息地 Crash。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;因此我們的 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/blob/main/Dockerfile&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dockerfile&lt;/code&gt;&lt;/a&gt; 採用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;golang:1.26-bookworm&lt;/code&gt; 編譯後，Runtime 階段選用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;debian:bookworm-slim&lt;/code&gt; 並明確安裝 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ca-certificates&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chromium&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;fonts-noto-cjk&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@single-file/cli&lt;/code&gt;。&lt;/p&gt;

&lt;h2 id=&quot;遺漏-6in-memory-暫存與-cloud-run-自動水平擴縮multi-instance的狀態分裂&quot;&gt;遺漏 6：In-Memory 暫存與 Cloud Run 自動水平擴縮（Multi-Instance）的狀態分裂&lt;/h2&gt;

&lt;p&gt;雖然我們把對話歷史、書籤、研究報告與 Batch Job 映射這四大核心狀態都持久化到了 Cloud Firestore，但有幾項「生命週期只有 5 分鐘」的二進位資料是放在 Go 記憶體 map 裡的：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;使用者剛上傳、正在等待點選「識別圖片 / Agentic Vision」Quick Reply 的圖片（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;imageTempStore&lt;/code&gt;）&lt;/li&gt;
  &lt;li&gt;剛畫好標註框、等待 LINE 伺服器來拉取的 PNG（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/images/{image_id}&lt;/code&gt;）&lt;/li&gt;
  &lt;li&gt;剛合成完、等待 LINE 伺服器來拉取的 M4A 音檔（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/audio/{audio_id}&lt;/code&gt;）&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;這在單一實例下完全沒問題，但一旦 Cloud Run 因為瞬間流量擴展成 2 個以上的 Instance，就會發生狀態分裂&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;使用者傳圖片打到 &lt;strong&gt;Instance A&lt;/strong&gt;（圖片存在 A 的記憶體）。&lt;/li&gt;
  &lt;li&gt;3 秒後使用者按下「Agentic Vision」按鈕，Webhook 打到 &lt;strong&gt;Instance B&lt;/strong&gt; $\rightarrow$ B 找不到圖片，直接回覆「⚠️ 圖片已過期，請重新傳送」！&lt;/li&gt;
  &lt;li&gt;或者 &lt;strong&gt;Instance A&lt;/strong&gt; 產出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/audio/{id}&lt;/code&gt; 並呼叫 LINE Reply API，結果 LINE 的媒體伺服器來下載音檔時打到 &lt;strong&gt;Instance B&lt;/strong&gt; 拿到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;404&lt;/code&gt;，使用者在聊天室裡就只會看到一個無法播放的語音泡泡。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;解法&lt;/strong&gt;：因為 Go 單一實例就能輕鬆扛起高併發（我們將 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;containerConcurrency&lt;/code&gt; 設為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;160&lt;/code&gt;），對於個人或中小型助理，建議將 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--max-instances&lt;/code&gt; 限制為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1&lt;/code&gt;（若未來需要多實例高可用，則必須將 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/images&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/audio&lt;/code&gt; 的暫存改寫入 Cloud Storage 或 Firestore）。&lt;/p&gt;

&lt;h2 id=&quot;遺漏-7切換時只改了-messaging-api-webhook卻漏了-firebase-hosting-websocket-限制與-liff-endpoint&quot;&gt;遺漏 7：切換時只改了 Messaging API Webhook，卻漏了 Firebase Hosting WebSocket 限制與 LIFF Endpoint&lt;/h2&gt;

&lt;p&gt;準備從舊服務切到新服務時，最常遺漏以下三個外圍設定：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;檢查點&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;為什麼容易遺漏？&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;實際影響與正確做法&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;1. 現有 Webhook 是否躲在 Firebase Hosting 後面？&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;我們透過 LINE API (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /v2/bot/channel/webhook/endpoint&lt;/code&gt;) 查詢現有設定時，才發現原本的 Webhook 指在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;*.firebaseapp.com&lt;/code&gt;（由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;firebase.json&lt;/code&gt; rewrite 到 Cloud Run）。&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Firebase Hosting 不支援 WebSocket 代理！&lt;/strong&gt; 如果 LIFF 語音助手（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/ws/voice/{id}&lt;/code&gt;）走 Firebase Hosting 網域，WebSocket 握手會直接失敗。因此切換時應直接指向 Cloud Run 網址，或確保 LIFF 走直連。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;2. LINE Login Channel 的 LIFF Endpoint URL&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;LIFF App 的設定不在 Messaging API Channel，而是放在同一個 Provider 底下的 &lt;strong&gt;LINE Login Channel&lt;/strong&gt; 分頁裡。&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;只改 Webhook 沒改 LIFF Endpoint 的話，聊天室打字是新的 Go 版在回，但點開語音助手卻還是連回舊的 Python 版。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;3. Gemini Batch API 的靜態 Webhook / Eventarc&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;若在 GCP 有設定 Eventarc 或專案級靜態 Webhook 指到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/api/gemini-callback/static&lt;/code&gt;。&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;記得一併更新目標網址（而 Dynamic Webhook &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/api/gemini-callback/dynamic&lt;/code&gt; 則會自動抓取進站 Request 的 Host，無須手動修改）。&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;六切換前盤點從-gcp-log-抓出三個殭屍端點順便規劃收編-n8n-排程&quot;&gt;六、切換前盤點：從 GCP Log 抓出三個「殭屍端點」，順便規劃收編 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 排程！&lt;/h1&gt;

&lt;p&gt;在撰寫 README 的「從 Python 版切換」步驟時，原本列了一條：&lt;/p&gt;
&lt;blockquote&gt;
  &lt;p&gt;「把呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hf&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/urls&lt;/code&gt; 的外部排程改指向新服務。」&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;但我轉念一想：&lt;strong&gt;等等，這三個端點現在真的還有被我的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 呼叫嗎？&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;我們立刻用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud logging read&lt;/code&gt; 撈了 GCP 專案裡 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-python&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 服務的執行紀錄，結果發現了一個大驚喜：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hf&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/urls&lt;/code&gt; 是 &lt;strong&gt;2024 年 11 月&lt;/strong&gt; 初版寫的端點，當時是讓外部排程把網址陣列 POST 進來給 LINE Bot 代為摘要並推播。&lt;/li&gt;
  &lt;li&gt;但現在雲端上的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 服務（跑著 &lt;strong&gt;「RSS to Sheet」&lt;/strong&gt;、&lt;strong&gt;「每日工作(抓論文/分享影片)」&lt;/strong&gt;、&lt;strong&gt;「Daily LINE Sender」&lt;/strong&gt; 與 &lt;strong&gt;「AI 趨勢自動化電子報」&lt;/strong&gt; 四支 Active Workflows），早就已經改成&lt;strong&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 內部自己跑 Firecrawl、自己呼叫 Gemini 摘要、自己組裝 Flex JSON 並直接打 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://api.line.me/v2/bot/message/push&lt;/code&gt;&lt;/strong&gt;！&lt;/li&gt;
  &lt;li&gt;換句話說，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-python&lt;/code&gt; 上的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hf&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/urls&lt;/code&gt; 過去幾個月&lt;strong&gt;來自 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 的呼叫次數是 0&lt;/strong&gt;！&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;更有趣的是，在檢查 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 的 Debug Log 時，我們還意外抓到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 在每天早上 6 點推播 YouTube 新影片摘要時，曾經因為 Javascript 節點組出來的 Flex Carousel 字數或縮圖格式問題，被 LINE API 回傳：&lt;/p&gt;
&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Workflow execution finished with error: A message (messages[0]) in the request body is invalid
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這個發現讓我們立刻做了兩個決定：&lt;/p&gt;

&lt;h3 id=&quot;決定-1立刻砍掉-linebot-helper-go-裡的-hnhfurls&quot;&gt;決定 1：立刻砍掉 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt; 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hf&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/urls&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;既然沒有任何外部服務在呼叫，留在公開的 Cloud Run 上反而只是多三個沒有簽章保護的攻擊面。直接從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;server.go&lt;/code&gt; 移除後重新部署，線上打 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hf&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/urls&lt;/code&gt; 全部回傳 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;404 Not Found&lt;/code&gt;，切換時也只需要在 LINE Developers Console 改 &lt;strong&gt;Webhook URL&lt;/strong&gt; 跟 &lt;strong&gt;LIFF Endpoint URL&lt;/strong&gt; 兩個地方就好！&lt;/p&gt;

&lt;h3 id=&quot;決定-2開立-issue-14--issue-19把-n8n-的工作流收編進-linebot-helper-go&quot;&gt;決定 2：開立 &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/14&quot;&gt;Issue #14&lt;/a&gt; ~ &lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/19&quot;&gt;Issue #19&lt;/a&gt;，把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 的工作流收編進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt;！&lt;/h3&gt;
&lt;p&gt;既然 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt; 已經是一台常駐 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 vCPU / 1 GiB&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;）的極速 Go 伺服器，裡面又有現成的三層爬蟲 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;loader.Loader&lt;/code&gt;、強型別 LINE Flex Builder、Gemini Batch API、Firestore &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BookmarkService&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ReportStore&lt;/code&gt;，為什麼還要另外養一台 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; + Postgres 資料庫？&lt;/p&gt;

&lt;p&gt;更重要的是——&lt;strong&gt;如果把這些每日排程全部改由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;linebot-helper-go&lt;/code&gt; 透過目前同一個 LINE 官方帳號推播，就能打通「推播 $\rightarrow$ 互動」的完美閉環&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/14&quot;&gt;Issue #14 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Batch Task 1/5&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt;：建立受保護的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /api/tasks/{task_name}&lt;/code&gt; 排程端點与 Firestore &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;feed_items&lt;/code&gt; 去重佇列（取代原本用 Google Sheets 比對 Row 的做法），統一使用主官方帳號推播。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/15&quot;&gt;Issue #15 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Batch Task 2/5&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt;：每日 10:00 抓取 &lt;strong&gt;Hugging Face Daily Papers&lt;/strong&gt;，在推播論文摘要卡片時直接附上 &lt;strong&gt;「🔖 儲存書籤」&lt;/strong&gt; 與 &lt;strong&gt;「📄 詳細研究報告」&lt;/strong&gt; 按鈕，看到好論文一鍵就能生成 Grounding 深度網頁報告。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/16&quot;&gt;Issue #16 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Batch Task 3/5&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt;：每日 06:00 巡檢 &lt;strong&gt;YouTube 追蹤頻道新片&lt;/strong&gt;，用 Go 強型別 Flex Builder 徹底解決 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;400 Invalid Request Body&lt;/code&gt; 問題，並在卡片直接附上 &lt;strong&gt;「📝 詳細摘要」&lt;/strong&gt; Postback 按鈕。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/17&quot;&gt;Issue #17 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Batch Task 4/5&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt;：整合 HN、Hatena IT、Google Dev Blog、LY Blog、Steam 等多來源 RSS 巡檢與每日 06:00 精選推播。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go/issues/18&quot;&gt;Issue #18 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Batch Task 5/5&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt;：每週五 17:00 彙整當週精選內容與書籤，直接渲染成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/reports/{id}&lt;/code&gt; 精美網頁版 &lt;strong&gt;AI 趨勢週報&lt;/strong&gt; 推播至 LINE。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;七最後一個資安提醒別把-cloud-run-真實網址留在公開-git-歷史裡&quot;&gt;七、最後一個資安提醒：別把 Cloud Run 真實網址留在公開 Git 歷史裡&lt;/h1&gt;

&lt;p&gt;在寫完部署紀錄與切換教學後，我做了一件很重要的收尾工作：&lt;strong&gt;把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;README.md&lt;/code&gt; 與 GitHub Issue 留言裡所有出現過的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.run.app&lt;/code&gt; 真實服務網址、GCP Project Number 與 LIFF ID 全部換成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;YOUR_CLOUD_RUN_SERVICE_URL&amp;gt;&lt;/code&gt; 佔位符，並重寫 Git Commit 歷史消除痕跡。&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;原因很簡單：LINE Bot 的 Cloud Run 服務因為要接收 LINE 平台的 Webhook，必須設定為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--allow-unauthenticated&lt;/code&gt;。雖然我們的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /&lt;/code&gt; 有嚴格驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Line-Signature&lt;/code&gt;（沒有 Channel Secret 簽章一律擋在門外回 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;400&lt;/code&gt;），但把真實的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.run.app&lt;/code&gt; 網址直接寫在公開 GitHub Repo 的 README 上，還是很容易引來無謂的自動化爬蟲掃描與打流量的噪音。&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;公開程式碼分享架構與實作，真實端點只留在自己的設定後台&lt;/strong&gt;，這才是長久維護個人 AI 助理最安心的做法。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;八cloud-run-部署與遷移自我檢查清單checklist&quot;&gt;八、Cloud Run 部署與遷移自我檢查清單（Checklist）&lt;/h1&gt;

&lt;p&gt;如果你也打算把現有的 Python LINE Bot 改寫成 Go 並搬上 Cloud Run，切換流量前可以用這份清單逐項打勾：&lt;/p&gt;

&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;1. CPU 節流設定&lt;/strong&gt;：只要有背景 Goroutine（Webhook 秒回 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;200 OK&lt;/code&gt; 後背景推播、或是背景定時 Ticker），務必加上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-cpu-throttling&lt;/code&gt;（且 CPU 至少設為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1&lt;/code&gt;）。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;2. Context 生命週期解耦&lt;/strong&gt;：背景 Goroutine 禁止傳入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r.Context()&lt;/code&gt;，一律改用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;context.Background()&lt;/code&gt; 搭配獨立的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;context.WithTimeout&lt;/code&gt;。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;3. Vertex AI &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global&lt;/code&gt; 網域判斷&lt;/strong&gt;：若 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GOOGLE_CLOUD_LOCATION=global&lt;/code&gt;，確認 Endpoint Base URL 為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://aiplatform.googleapis.com&lt;/code&gt; 而非 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;global-aiplatform.googleapis.com&lt;/code&gt;。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;4. 外部二進位工具與字型&lt;/strong&gt;：若容器內有呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;single-file&lt;/code&gt; 或 Headless Chromium，確認最終階段 Docker Image 包含對應執行檔、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ca-certificates&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;fonts-noto-cjk&lt;/code&gt; 以及 Chromium 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--no-sandbox --disable-dev-shm-usage&lt;/code&gt; 參數。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;5. 反向代理 HTTPS 標頭&lt;/strong&gt;：動態產生 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/images/{id}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/audio/{id}&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/reports/{id}&lt;/code&gt; 網址時，優先讀取 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Forwarded-Proto&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Forwarded-Host&lt;/code&gt;，確保傳給 LINE 的媒體網址必為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://&lt;/code&gt;。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;6. In-Memory 暫存與 Instance 數量&lt;/strong&gt;：若有短時效記憶體 map（如暫存圖片/音檔），建議設 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--max-instances=1&lt;/code&gt; 並調高 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;concurrency&lt;/code&gt;，或改存 GCS / Firestore，避免多實例狀態分裂。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;7. 雙通道 LINE 設定同步&lt;/strong&gt;：除了更新 &lt;strong&gt;Messaging API&lt;/strong&gt; 的 Webhook URL 外，別忘了更新同 Provider 下 &lt;strong&gt;LINE Login Channel&lt;/strong&gt; 的 &lt;strong&gt;LIFF Endpoint URL&lt;/strong&gt;，並確認 WebSocket 路徑沒有被不支援 WS 的 CDN / Firebase Hosting 攔截。&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; /&gt;&lt;strong&gt;8. 清理廢棄端點與公開資訊&lt;/strong&gt;：從 Cloud Logging 確認無用的舊端點（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/hf&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/urls&lt;/code&gt;）並直接移除，且確保公開 Repo 與 Git 歷史紀錄中不包含真實 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.run.app&lt;/code&gt; 網址與密鑰。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;小結與開源專案連結&quot;&gt;小結與開源專案連結&lt;/h1&gt;

&lt;p&gt;這次從 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-python&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-helper-python&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 到 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-helper-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; 的改寫之旅，幾個最值得帶走的收穫：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;先開 Issue 再寫扣&lt;/strong&gt;：11 個里程碑 Issue 讓大型語言改寫變得高度可控，每個模組都能獨立跑過單元測試再往上疊。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;共享資料層是零停機遷移的底氣&lt;/strong&gt;：只要 Firestore Collection Schema 對齊，新舊兩個語言的服務就能隨時無痛切換。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Go 在 Cloud Run 上的資源效率極高&lt;/strong&gt;：同樣掛載 Headless Chromium 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ffmpeg&lt;/code&gt;，從 Python &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;4 vCPU / 4 GiB&lt;/code&gt; 換成 Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1 vCPU / 1 GiB&lt;/code&gt;，帳單直接打 25 折，回應速度還更快。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;切換前先看 Cloud Logging&lt;/strong&gt;：真實的流量 Log 不會騙人，一眼就能看出哪些端點早已退役、哪些外部 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n8n&lt;/code&gt; 工作流其實更適合收編進同一個服務裡。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;完整程式碼與後續的 ADK v1.9.0 / Batch Tasks 演進計畫都已開源在 GitHub：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/linebot-helper-go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/linebot-helper-go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;，歡迎參考與交流！&lt;/p&gt;
</description>
				<pubDate>Sun, 01 Nov 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/linebot-helper-python-to-go-cloudrun/</link>
				<guid isPermaLink="true">https://www.evanlin.com/linebot-helper-python-to-go-cloudrun/</guid>
			</item>
		
			<item>
				<title>[Agent Platform 實戰 (9)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (下)：雙層遞迴測試指南、62.5% 到 100% 效能實測與 AgentOps 未來展望</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/line-card-harness2-part3-experiment-outlook-arch.png&quot; alt=&quot;Harness² Part 3: Recursive Optimization Benchmark &amp;amp; Future AgentOps Outlook&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前言從手動調-prompt邁向雙層遞迴自主演化&quot;&gt;前言：從「手動調 Prompt」邁向「雙層遞迴自主演化」&lt;/h1&gt;

&lt;p&gt;歡迎來到《&lt;strong&gt;Agent Platform 實戰&lt;/strong&gt;》Harness² 三部曲的最終篇！在前兩篇文章中：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/25/adk-graph-workflow-go-7/&quot;&gt;[Agent Platform 實戰 (7)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (上)：認識雙層遞迴 Agent 裝備框架與 c1..c8 解耦實戰&lt;/a&gt;&lt;/strong&gt;（&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/16&quot;&gt;Issue #16&lt;/a&gt;&lt;/strong&gt;）：我們介紹了 Google Research 的 &lt;strong&gt;&lt;a href=&quot;https://github.com/google-research/harness2&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt; (arXiv:2610.14224)&lt;/a&gt;&lt;/strong&gt;，並將 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;LINE AI 名片王 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-card-assistant&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt; 的 13 節點 Graph Workflow 解耦為支援 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CARD_HARNESS_DIR&lt;/code&gt; 動態掛載的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 可編輯檔案樹&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/26/adk-graph-workflow-go-8/&quot;&gt;[Agent Platform 實戰 (8)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (中)：把 Phase 4 Eval Datasets 與 Phase 5 OpenTelemetry Spans 變成 LineCardAdapter&lt;/a&gt;&lt;/strong&gt;（&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;&lt;/strong&gt;）：我們將 Phase 4 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/&lt;/code&gt; 與 Phase 5 的 OpenTelemetry &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.*&lt;/code&gt; Spans 封裝為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;，建立了 &lt;strong&gt;零洩漏屏障（Zero-Leakage Barrier）&lt;/strong&gt; 與 &lt;strong&gt;高解析度行為軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;）&lt;/strong&gt;。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;在本篇（下篇，對應 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/18&quot;&gt;Issue #18&lt;/a&gt;&lt;/strong&gt; 與 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/19&quot;&gt;PR #19&lt;/a&gt;&lt;/strong&gt;）中，我們將回答最後三個關鍵問題：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;修改後該如何測試？&lt;/strong&gt;（從 Go 單元測試、CLI 單點診斷、Python 雙層遞迴實驗到生產環境掛載的完整測試指南）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;整體修改後的效能表現如何？&lt;/strong&gt;（公開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Base 62.5%&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k=1 84.4%&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k=2 Parallel 96.9%&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k=2 Sequential + Memory 100.0%&lt;/code&gt; 的完整量化數據與演化細節）&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;對於 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 與 Agent 後續的展望，有哪些值得期待的應用場景？&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一修改後該如何測試step-by-step-測試與驗證指南&quot;&gt;一、修改後該如何測試？（Step-by-Step 測試與驗證指南）&lt;/h1&gt;

&lt;p&gt;導入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 後，整個專案具備了 &lt;strong&gt;Go 原生單元測試&lt;/strong&gt;、&lt;strong&gt;單一任務 OpenTelemetry 軌跡診斷&lt;/strong&gt;、&lt;strong&gt;Python 雙層遞迴演化實驗&lt;/strong&gt; 與 &lt;strong&gt;生產環境無縫切換&lt;/strong&gt; 四個層次的測試與驗證方式：&lt;/p&gt;

&lt;h2 id=&quot;1-層次一執行-go-c1c8-表面約束與全專案單元測試&quot;&gt;1. 層次一：執行 Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 表面約束與全專案單元測試&lt;/h2&gt;

&lt;p&gt;我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/harness_test.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/harness_test.go&lt;/code&gt;&lt;/a&gt; 中編寫了完整的單元測試，驗證：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/evolved/&lt;/code&gt; 下所有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案樹皆符合 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OPENCODE_SURFACE&lt;/code&gt; 24KB 常駐位元組上限（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AlwaysOnMaxBytes = 24000&lt;/code&gt;）。&lt;/li&gt;
  &lt;li&gt;當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt; 超過 24,000 bytes 時，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Validate()&lt;/code&gt; 能精準攔截並報錯。&lt;/li&gt;
  &lt;li&gt;當新增一個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; 技能（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/&amp;lt;name&amp;gt;/SKILL.md&lt;/code&gt;）卻未在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;guardrails.md&lt;/code&gt; 加入觸發索引（Trigger Line）時，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Validate()&lt;/code&gt; 能立即攔截孤兒技能。&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TrajectoryRecorder&lt;/code&gt; 能正確攔截 OpenTelemetry &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.*&lt;/code&gt; Spans 並渲染出包含節點決策與診斷的 Markdown 報告。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;執行指令：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# 執行 Harness² c1..c8 載入器與 OpenTelemetry 軌跡測試&lt;/span&gt;
&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;go &lt;span class=&quot;nb&quot;&gt;test&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-v&lt;/span&gt; ./internal/harness/...
&lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; RUN   TestLoadBaseHarnessAndValidate
&lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestLoadBaseHarnessAndValidate &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; RUN   TestValidateRejectsOversizedAlwaysOnAndUnreferencedSkill
&lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestValidateRejectsOversizedAlwaysOnAndUnreferencedSkill &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; RUN   TestEvolvedHarnessesValidateAndMatchSkills
&lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestEvolvedHarnessesValidateAndMatchSkills &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; RUN   TestTrajectoryRecorderRendersWorkflowNodeSpans
&lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestTrajectoryRecorderRendersWorkflowNodeSpans &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
PASS
ok      github.com/kkdai/line-card-assistant/internal/harness

&lt;span class=&quot;c&quot;&gt;# 執行全專案回歸測試（確保 Phase 1~5 所有既有功能 100% 相容）&lt;/span&gt;
&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;go &lt;span class=&quot;nb&quot;&gt;test&lt;/span&gt; ./...
ok      github.com/kkdai/line-card-assistant/app
ok      github.com/kkdai/line-card-assistant/cmd/harness-runner
ok      github.com/kkdai/line-card-assistant/cmd/line-gateway
ok      github.com/kkdai/line-card-assistant/eval
ok      github.com/kkdai/line-card-assistant/internal/harness
ok      github.com/kkdai/line-card-assistant/internal/storage
ok      github.com/kkdai/line-card-assistant/internal/webhook
ok      github.com/kkdai/line-card-assistant/internal/workflow
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;2-層次二使用-cmdharness-runner-驗證任一-c1c8-檔案樹&quot;&gt;2. 層次二：使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/harness-runner&lt;/code&gt; 驗證任一 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案樹&lt;/h2&gt;

&lt;p&gt;在把任何自訂或演化後的 Harness 掛載上線前，可以使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--validate-only&lt;/code&gt; 快速檢查其 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt; 常駐位元組數與 YAML Frontmatter 合規性：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;go run ./cmd/harness-runner &lt;span class=&quot;nt&quot;&gt;--validate-only&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--harness-dir&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;harness/base
OK &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;1599 always-on bytes&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;go run ./cmd/harness-runner &lt;span class=&quot;nt&quot;&gt;--validate-only&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--harness-dir&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;harness/evolved/k2_sequential_memory
OK &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;4661 always-on bytes&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;3-層次三執行四階段-harness-雙層遞迴演化基準實驗&quot;&gt;3. 層次三：執行四階段 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 雙層遞迴演化基準實驗&lt;/h2&gt;

&lt;p&gt;我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/harness/run_harness2_experiment.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/run_harness2_experiment.py&lt;/code&gt;&lt;/a&gt; 中實作了完整的雙層遞迴實驗腳本。它會自動編譯 Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness-runner&lt;/code&gt;，並針對 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/datasets/harness2-challenge-dataset.json&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/harness2-challenge-dataset.json&lt;/code&gt;&lt;/a&gt; 的 8 大任務（32 個獨立 Rubrics）依序評測四種配置，最後輸出 Markdown 對照表與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/harness/experiment_report.json&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/experiment_report.json&lt;/code&gt;&lt;/a&gt;：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;python3 harness/run_harness2_experiment.py
&lt;span class=&quot;c&quot;&gt;### Overall Configuration Comparison&lt;/span&gt;

| Stage | Configuration | Task Score &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;Max 8.0&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt; | Rubric Pass Rate | Always-On Bytes &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;Cap 24,000&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt; | Active &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;c6&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; Skills | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;LongTermMEMORY.md&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; |
| :--- | :--- | :---: | :---: | :---: | :--- | :---: |
| &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;base_k0&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;k&quot;&gt;**&lt;/span&gt;Base Harness &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$k&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;0&lt;span class=&quot;nv&quot;&gt;$)&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;**&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;5.00 / 8.00&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;20/32 &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;62.5%&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;1599 B&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;none&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;No&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; |
| &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;k1_single_step&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;k&quot;&gt;**&lt;/span&gt;Single-Step Propose-Probe-Compose &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$k&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;1&lt;span class=&quot;nv&quot;&gt;$)&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;**&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;6.75 / 8.00&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;27/32 &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;84.4%&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;2505 B&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;jp_card_ocr, tw_semicon_search&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;No&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; |
| &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;k2_parallel&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;k&quot;&gt;**&lt;/span&gt;Multi-Step Parallel Recursion &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$k&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;2&lt;span class=&quot;nv&quot;&gt;$,&lt;/span&gt; No Memory&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;**&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;7.75 / 8.00&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;31/32 &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;96.9%&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;2998 B&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;executive_email_drafter, hitl_multi_edit, jp_card_ocr, tw_semicon_search&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;No&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; |
| &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;k2_sequential_memory&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;k&quot;&gt;**&lt;/span&gt;Multi-Step Sequential Recursion + &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;LongTermMEMORY.md&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$k&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;2&lt;span class=&quot;nv&quot;&gt;$)&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;**&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;8.00 / 8.00&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;32/32 &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;100.0%&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;4661 B&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;executive_email_drafter, hitl_multi_edit, jp_card_ocr, tw_semicon_search&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; | &lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt;Yes&lt;span class=&quot;sb&quot;&gt;`&lt;/span&gt; |
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;4-層次四在生產環境或本地伺服器直接掛載演化後的最佳-harness&quot;&gt;4. 層次四：在生產環境或本地伺服器直接掛載演化後的最佳 Harness&lt;/h2&gt;

&lt;p&gt;當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 演化出最佳的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/evolved/k2_sequential_memory&lt;/code&gt; 後，&lt;strong&gt;不需要修改任何一行 Go 程式碼&lt;/strong&gt;，只要透過環境變數 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CARD_HARNESS_DIR&lt;/code&gt; 指定目錄，無論是雙通道主程式（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main.go&lt;/code&gt;）還是評估器（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/&lt;/code&gt;）都會立刻載入演化後的裝備樹：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ LINE_CARD_HARNESS_DIR&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;harness/evolved/k2_sequential_memory go run &lt;span class=&quot;nb&quot;&gt;.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二整體修改後的效能整理從-625-到-1000-的演化剖析&quot;&gt;二、整體修改後的效能整理：從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;62.5%&lt;/code&gt; 到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100.0%&lt;/code&gt; 的演化剖析&lt;/h1&gt;

&lt;p&gt;讓我們深入檢視 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/harness/experiment_report.json&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/experiment_report.json&lt;/code&gt;&lt;/a&gt; 記錄的四階段量化實驗數據，看看 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 是如何一步步診斷並修補 Go Agent 的缺陷！&lt;/p&gt;

&lt;h2 id=&quot;1-四階段整體與單一任務得分總表&quot;&gt;1. 四階段整體與單一任務得分總表&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;評估指標 / 測試任務&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;&lt;strong&gt;Stage 0: Base Harness ($k=0$)&lt;/strong&gt;&lt;br /&gt;(&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base&lt;/code&gt;)&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;&lt;strong&gt;Stage 1: 單步內層遞迴 ($k=1$)&lt;/strong&gt;&lt;br /&gt;(&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k1_single_step&lt;/code&gt;)&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;&lt;strong&gt;Stage 2: 多步平行遞迴 ($k=2$, 無記憶)&lt;/strong&gt;&lt;br /&gt;(&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k2_parallel&lt;/code&gt;)&lt;/th&gt;
      &lt;th style=&quot;text-align: center&quot;&gt;&lt;strong&gt;Stage 3: 雙層序列遞迴 + 長期記憶 ($k=2$)&lt;/strong&gt;&lt;br /&gt;(&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k2_sequential_memory&lt;/code&gt;)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_ingest_ming_wang&lt;/code&gt;&lt;/strong&gt; (標準中文建檔)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_dedup_appier_promotion&lt;/code&gt;&lt;/strong&gt; (升遷去重更新)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_search_cloud_summit_ai&lt;/code&gt;&lt;/strong&gt; (標準關鍵字搜尋)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_email_google_cloud&lt;/code&gt;&lt;/strong&gt; (一般科技業破冰信)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_jp_bilingual_ingest&lt;/code&gt;&lt;/strong&gt; (日英雙語名片 OCR)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25 (1/4)&lt;/code&gt; ❌&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt; ✅&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt; ✅&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt; ✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_colloquial_tw_search&lt;/code&gt;&lt;/strong&gt; (竹科口語雙語搜尋)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25 (1/4)&lt;/code&gt; ❌&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt; ✅&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt; ✅&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt; ✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_noisy_multi_edit_hitl&lt;/code&gt;&lt;/strong&gt; (多子句口語 HITL 修改)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25 (1/4)&lt;/code&gt; ❌&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25 (1/4)&lt;/code&gt; ❌&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt; ✅&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt; ✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_pii_safe_executive_followup&lt;/code&gt;&lt;/strong&gt; (金融高管合規破冰信)&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25 (1/4)&lt;/code&gt; ❌&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.50 (2/4)&lt;/code&gt; ⚠️&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.75 (3/4)&lt;/code&gt; ⚠️&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.00 (4/4)&lt;/code&gt;&lt;/strong&gt; ✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;總任務得分 (Max 8.00)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;5.00 / 8.00&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;6.75 / 8.00&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;7.75 / 8.00&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;8.00 / 8.00&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;細粒度 Rubric 通過率 (Max 32)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;20 / 32 (62.5%)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;27 / 32 (84.4%)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;31 / 32 (96.9%)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;32 / 32 (100.0%)&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;常駐位元組數 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt; / 24,000 B)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1,599 B (6.7%)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;2,505 B (10.4%)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;2,998 B (12.5%)&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;4,661 B (19.4%)&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;按需載入技能數 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; Skills)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0 個&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;2 個&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;4 個&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: center&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;4 個 + LongTermMEMORY&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;2-關鍵發現剖析每一階段到底進化了什麼&quot;&gt;2. 關鍵發現剖析：每一階段到底進化了什麼？&lt;/h2&gt;

&lt;h3 id=&quot;-stage-0-rightarrow-stage-1-625-rightarrow-844從-opentelemetry-軌跡診斷出前兩個按需技能-c6&quot;&gt;🔹 Stage 0 $\rightarrow$ Stage 1 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;62.5%&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;84.4%&lt;/code&gt;)：從 OpenTelemetry 軌跡診斷出前兩個按需技能 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt;)&lt;/h3&gt;
&lt;p&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Base Harness ($k=0$)&lt;/code&gt; 中，雖然 4 個 Baseline 任務全部拿滿分（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;4.00/4.00&lt;/code&gt;），但面對 4 個 Challenge 任務全都因為只通過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt; 意圖路由而僅拿 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25&lt;/code&gt; 分：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_jp_bilingual_ingest&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt; 中，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt; 的 Span 診斷出日本電話 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+81 (0)3-1234-5678&lt;/code&gt; 未剝離國內長途冠碼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(0)&lt;/code&gt;，且日文役職 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;取締役 最高技術責任者 (CTO)&lt;/code&gt; 未保留雙語職銜。&lt;/li&gt;
  &lt;li&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_colloquial_tw_search&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt; 中，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; 的 Span 診斷出台灣口語「竹科」與「業務總監」未展開雙語同義詞。&lt;/li&gt;
  &lt;li&gt;經過第一輪內層遞迴（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose -&amp;gt; Probe -&amp;gt; Compose&lt;/code&gt;），&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 自動在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k1_single_step&lt;/code&gt; 中合成了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/jp_card_ocr/SKILL.md&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/tw_semicon_search/SKILL.md&lt;/code&gt;，並更新了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;guardrails.md&lt;/code&gt; 的個資遮罩規則，讓準確率一舉從 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;62.5%&lt;/code&gt; 跳升至 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;84.4%&lt;/code&gt;&lt;/strong&gt;！&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;-stage-1-rightarrow-stage-2-844-rightarrow-969第二輪遞迴攻克多子句-hitl-修改與高管書信結構&quot;&gt;🔹 Stage 1 $\rightarrow$ Stage 2 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;84.4%&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;96.9%&lt;/code&gt;)：第二輪遞迴攻克多子句 HITL 修改與高管書信結構&lt;/h3&gt;
&lt;p&gt;在第二輪內層遞迴中，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 針對剩餘失分的兩個任務繼續探測：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;針對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_noisy_multi_edit_hitl&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ApplyEditNode&lt;/code&gt; 只修改了第一個子句的職稱，漏掉了手機尾碼替換與備註追加），演化出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/hitl_multi_edit/SKILL.md&lt;/code&gt;（包含 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ATOMIC_MULTI_CLAUSE_EDIT&lt;/code&gt; 規則）。&lt;/li&gt;
  &lt;li&gt;針對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_pii_safe_executive_followup&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;EmailDraftNode&lt;/code&gt; 缺少結構化高管跟進段落），演化出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/executive_email_drafter/SKILL.md&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;此時在 &lt;strong&gt;Parallel Recursion（無跨輪次長期記憶）&lt;/strong&gt; 下，得分來到 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;31/32 (96.9%)&lt;/code&gt;&lt;/strong&gt;！&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;-stage-2-rightarrow-stage-3-969-rightarrow-1000為什麼-sequential--longtermmemorymd-才能補齊最後-31&quot;&gt;🔹 Stage 2 $\rightarrow$ Stage 3 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;96.9%&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100.0%&lt;/code&gt;)：為什麼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Sequential + LongTermMEMORY.md&lt;/code&gt; 才能補齊最後 3.1%？&lt;/h3&gt;
&lt;p&gt;為什麼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;k2_parallel&lt;/code&gt; 拿到了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;96.9%&lt;/code&gt;（31/32），偏偏在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_pii_safe_executive_followup&lt;/code&gt; 的第 4 個 Rubric（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r4_fintech_compliance_subject_tag&lt;/code&gt;）失分？&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;因為在金融機構（如國泰金控數位風控長）的跨企業外寄信件中，除了單一技能的書信格式外，還需要跨領域的 &lt;strong&gt;產業合規記憶（FinTech Outbound Compliance Header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[Confidential / FinTech Compliance Verified]&lt;/code&gt;）&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;在 &lt;strong&gt;Sequential Recursion + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Experience Reflector&lt;/code&gt;&lt;/strong&gt; 模式下，外層遞迴檢視了第一輪到第二輪的殘餘失分軌跡，由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ReflectorPrompt&lt;/code&gt; 將 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FINTECH_COMPLIANCE_SUBJECT_TAG&lt;/code&gt; 與跨管道個資保護原則寫入常駐組件 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c3: LongTermMEMORY.md&lt;/code&gt;&lt;/strong&gt;！&lt;/li&gt;
  &lt;li&gt;而且請注意看 &lt;strong&gt;常駐位元組數（Always-On Bytes）&lt;/strong&gt;：即使演化出了 4 個豐富的領域技能與長期記憶，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt; 的常駐大小也只有 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;4,661 bytes&lt;/code&gt;&lt;/strong&gt;（僅佔 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;24,000 bytes&lt;/code&gt; 上限的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;19.4%&lt;/code&gt;&lt;/strong&gt;），完美避免了 Context Bloat！&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三對於-harness-與-agent-後續的展望與期待應用場景&quot;&gt;三、對於 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 與 Agent 後續的展望與期待應用場景&lt;/h1&gt;

&lt;p&gt;將 Google Research &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 導入 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;LINE AI 名片王&lt;/a&gt;&lt;/strong&gt; 的這次實戰，讓我們看到了一種全新的 &lt;strong&gt;AgentOps 開發範式&lt;/strong&gt;。展望未來，我們認為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 在企業級 AI Agent 領域有四大極具潛力的應用場景：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    subgraph Prod[&quot;1. 生產環境可觀測性 (Cloud Run + Agent Runtime)&quot;]
        Traffic[&quot;真實使用者流量\n(LINE Webhook / A2A)&quot;]
        Trace[&quot;Cloud Trace OTel Spans\n+ 使用者負向回饋 (HITL 重試)&quot;]
        Traffic --&amp;gt; Trace
    end

    subgraph Nightly[&quot;2. 夜間自主演化飛輪 (Nightly Harness² CI/CD)&quot;]
        Extract[&quot;自動遮罩個資並轉為\nChallenge Dataset 新案例&quot;]
        Evolve[&quot;Harness² 雙層遞迴\n(Propose-Probe-Compose + Reflector)&quot;]
        PR[&quot;自動發起 GitHub PR\n更新 harness/evolved/ c1..c8&quot;]
        Extract --&amp;gt; Evolve --&amp;gt; PR
    end

    subgraph Scenarios[&quot;3. 未來四大高價值應用場景&quot;]
        S1[&quot;場景 A：全自動 Nightly Self-Healing AgentOps&quot;]
        S2[&quot;場景 B：跨模型遷移裝備調校 (Cross-Model Harnessing)&quot;]
        S3[&quot;場景 C：多租戶企業專屬合規與技能庫 (Multi-Tenant Skills)&quot;]
        S4[&quot;場景 D：結合 ADK Graph 拓撲的雙重演化 (Issue #15)&quot;]
    end

    Trace --&amp;gt; Extract
    PR --&amp;gt; Scenarios
&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;1-場景-a全自動夜間自我修復飛輪nightly-self-healing-agentops&quot;&gt;1. 場景 A：全自動「夜間自我修復飛輪（Nightly Self-Healing AgentOps）」&lt;/h2&gt;
&lt;p&gt;過去當生產環境的 LINE Bot 遇到使用者頻繁觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; 的「✏️ 修改資料」或給予負向回饋時，需要由工程師隔天撈 Cloud Trace Log 手動分析。結合我們在 Phase 5 建立的 Cloud Trace 與本系列的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;，未來的 CI/CD 可以做到：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;每晚自動從 Cloud Trace 篩選出「使用者連續修改超過 2 次」或「搜尋結果為 0 筆」的匿名化 Span 軌跡，自動加入 Challenge Dataset。&lt;/li&gt;
  &lt;li&gt;觸發 GitHub Actions 跑一輪 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 雙層遞迴，自動合成新的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; 技能或更新 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LongTermMEMORY.md&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;當回歸測試（Baseline + Challenge）確認分數提升且零退化（Zero Regression）後，&lt;strong&gt;由 Bot 自動發起一個只修改 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/&lt;/code&gt; 目錄的 Pull Request&lt;/strong&gt;，工程師早上只需 Review 技能 Markdown 即可一鍵上線！&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;2-場景-b跨模型升級與輕量化模型的裝備補償cross-model-harness-portability&quot;&gt;2. 場景 B：跨模型升級與輕量化模型的「裝備補償（Cross-Model Harness Portability）」&lt;/h2&gt;
&lt;p&gt;企業在將底層模型從高單價模型切換至極速輕量模型（例如從 Gemini 2.5 Pro 切換至 Gemini 2.5 Flash 或 Flash-Lite 以降低 80% 延遲與成本），或是升級至新一代模型時，常會遇到行為偏移。透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt;，我們可以在固定 Go 程式碼與固定 Benchmark 的情況下，針對目標模型自動跑一輪 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose-Probe-Compose&lt;/code&gt;，讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 自動為輕量模型補齊所需的推理輔助技能（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; Skills）與護欄（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c2&lt;/code&gt; Guardrails），用「更聰明的裝備」彌補輕量模型的差距。&lt;/p&gt;

&lt;h2 id=&quot;3-場景-c多租戶企業專屬合規與領域記憶multi-tenant-enterprise-compliance&quot;&gt;3. 場景 C：多租戶企業專屬合規與領域記憶（Multi-Tenant Enterprise Compliance）&lt;/h2&gt;
&lt;p&gt;正如我們在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_pii_safe_executive_followup&lt;/code&gt; 看到的，金融業（FinTech）、醫療生技業（MedTech）與半導體供應鏈各自有截然不同的術語字典與合規護欄。因為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 將裝備完全外置為純文字檔案樹，企業只要為不同部門或租戶掛載不同的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CARD_HARNESS_DIR&lt;/code&gt;（例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/tenants/fintech/&lt;/code&gt; vs &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/tenants/semiconductor/&lt;/code&gt;），就能讓同一個 Go Container Binary 同時服務多個高度監管的垂直產業！&lt;/p&gt;

&lt;h2 id=&quot;4-場景-d與-adk-v26-進階-graph-workflow-原語的圖撲--裝備雙重演化&quot;&gt;4. 場景 D：與 ADK v2.6+ 進階 Graph Workflow 原語的「圖撲 + 裝備」雙重演化&lt;/h2&gt;
&lt;p&gt;在 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/15&quot;&gt;Issue #15&lt;/a&gt;&lt;/strong&gt; 中，我們規劃了 ADK v2.6+ 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Parallel&lt;/code&gt; 動態派工、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MultiRoute&lt;/code&gt; 多路並行與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VerifyOCRQualityNode&lt;/code&gt; 反思迴圈。未來，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c5&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sub_agents/&lt;/code&gt;）與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c8&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;plugin/&lt;/code&gt;）甚至可以進一步控制 Graph Workflow 的路由閾值與子代理併發策略 —— 實現 &lt;strong&gt;「Go 負責型別安全的圖撲骨架，Harness² 負責動態演化神經網路與技能肌肉」&lt;/strong&gt; 的終極架構！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四agent-platform-實戰系列全九篇總回顧&quot;&gt;四、《Agent Platform 實戰》系列全九篇總回顧&lt;/h1&gt;

&lt;p&gt;從第一篇到第九篇，我們完成了一趟非常紮實的生產級 AI Agent 工程之旅：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/16/adk-graph-workflow-go/&quot;&gt;[Agent Platform 實戰 (1)] 用 Go 與 Google ADK 2.0 Graph Workflow 打造 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/17/adk-graph-workflow-go-2/&quot;&gt;[Agent Platform 實戰 (2)] 從單體 Cloud Run 邁向 Google Cloud Agent Runtime (Phase 1)&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/20/adk-graph-workflow-go-3/&quot;&gt;[Agent Platform 實戰 (3)] 用 ADK 2.0 GCS Artifact Service 與 Agent Platform Sessions 實現跨實例名片辨識與暫停恢復 (Phase 2 前半)&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/21/adk-graph-workflow-go-4/&quot;&gt;[Agent Platform 實戰 (4)] 用 Cloud Run LINE Webhook Gateway、Agent Runtime 與 Cloud SQL PostgreSQL 完成架構拼圖 (Phase 2 後半 &amp;amp; Phase 3)&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/22/adk-graph-workflow-go-5/&quot;&gt;[Agent Platform 實戰 (5)] 用 agents-cli eval 與 ADK 2.0 Go 建立自動化評估基準 (Phase 4)&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/24/adk-graph-workflow-go-6/&quot;&gt;[Agent Platform 實戰 (6)] 用 agents-cli deploy、Terraform IaC、GitHub Actions CI/CD 與 Cloud Trace 打造全棧可觀測的 LINE AI 名片王 (Phase 5)&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/25/adk-graph-workflow-go-7/&quot;&gt;[Agent Platform 實戰 (7)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (上)：認識雙層遞迴 Agent 裝備框架與 c1..c8 解耦實戰&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/26/adk-graph-workflow-go-8/&quot;&gt;[Agent Platform 實戰 (8)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (中)：把 Phase 4 Eval Datasets 與 Phase 5 OpenTelemetry Spans 變成 LineCardAdapter&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/27/adk-graph-workflow-go-9/&quot;&gt;[Agent Platform 實戰 (9)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (下)：雙層遞迴測試指南、62.5% 到 100% 效能實測與 AgentOps 未來展望（本文）&lt;/a&gt;&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;所有程式碼、Terraform IaC、評估資料集與演化後的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; Harness 檔案樹皆已完整開源於 GitHub：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-card-assistant&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;。如果你也正在用 Go 與 ADK 打造企業級 AI Agent，歡迎 Star、Fork 並動手體驗 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 雙層遞迴的威力！&lt;/p&gt;
</description>
				<pubDate>Mon, 26 Oct 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/adk-graph-workflow-go-9/</link>
				<guid isPermaLink="true">https://www.evanlin.com/adk-graph-workflow-go-9/</guid>
			</item>
		
			<item>
				<title>[Agent Platform 實戰 (8)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (中)：把 Phase 4 Eval Datasets 與 Phase 5 OpenTelemetry Spans 變成 LineCardAdapter</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/line-card-harness2-part2-adapter-arch.png&quot; alt=&quot;Harness² Part 2: LineCardAdapter Bridging Phase 4 Eval &amp;amp; Phase 5 OpenTelemetry Spans&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前言為什麼解耦了-prompt-還不夠&quot;&gt;前言：為什麼解耦了 Prompt 還不夠？&lt;/h1&gt;

&lt;p&gt;在上一篇 &lt;strong&gt;&lt;a href=&quot;/2026/10/25/adk-graph-workflow-go-7/&quot;&gt;[Agent Platform 實戰 (7)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (上)：認識雙層遞迴 Agent 裝備框架與 c1..c8 解耦實戰&lt;/a&gt;&lt;/strong&gt;（對應 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/16&quot;&gt;Issue #16&lt;/a&gt;&lt;/strong&gt;）中，我們介紹了 Google Research 的 &lt;strong&gt;&lt;a href=&quot;https://github.com/google-research/harness2&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt; (arXiv:2610.14224)&lt;/a&gt;&lt;/strong&gt;，並將 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;LINE AI 名片王 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-card-assistant&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt; 的提示詞、護欄、長期記憶與按需技能解耦為可透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CARD_HARNESS_DIR&lt;/code&gt; 動態掛載的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 可編輯 Harness 檔案樹&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;然而，光有可熱載入的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案樹，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的雙層遞迴優化引擎（&lt;a href=&quot;https://github.com/google-research/harness2/blob/main/harness2/core/recursion.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness2/core/recursion.py&lt;/code&gt;&lt;/a&gt;）仍然無法直接對我們的 Go Agent 進行優化。因為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 需要一個標準化的橋樑 —— &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BenchmarkAdapter&lt;/code&gt;&lt;/strong&gt; —— 來回答三個問題：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;list_tasks()&lt;/code&gt;（考題是什麼？）&lt;/strong&gt;：Agent 要挑戰哪些測試案例？每個案例有哪些公開輸入（Prompt / Image），又有哪些對 Agent 隱藏的評分標準（Rubrics）？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run()&lt;/code&gt;（Agent 怎麼思考與執行的？）&lt;/strong&gt;：當掛載某個候選 Harness $H’$ 執行某道考題時，Agent 最終產出了什麼（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deliverable&lt;/code&gt;）？更重要的是，&lt;strong&gt;它在 Graph Workflow 的 13 個節點中間經歷了什麼樣的決策軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;）&lt;/strong&gt;？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;score()&lt;/code&gt;（表現如何？）&lt;/strong&gt;：最終產出與執行軌跡通過了哪些獨立的評分項目（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;per_rubric&lt;/code&gt;），又在哪些項目失分了？&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;剛好！我們在 &lt;strong&gt;Phase 4（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13&lt;/a&gt;）&lt;/strong&gt; 已經建立了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/&lt;/code&gt; 自動化評估基準，在 &lt;strong&gt;Phase 5（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/14&quot;&gt;PR #14&lt;/a&gt;）&lt;/strong&gt; 又為全部 13 個 Graph Node 加上了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.*&lt;/code&gt; OpenTelemetry Spans！&lt;/p&gt;

&lt;p&gt;在本篇（中篇，對應 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;&lt;/strong&gt; 與 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/19&quot;&gt;PR #19&lt;/a&gt;&lt;/strong&gt;）中，我們將把這兩塊既有資產融合成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;&lt;/strong&gt;，並深入解釋 &lt;strong&gt;「為什麼一定要這樣設計？」&lt;/strong&gt;。&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一為什麼要這樣改兩大核心設計哲學&quot;&gt;一、為什麼要這樣改？兩大核心設計哲學&lt;/h1&gt;

&lt;p&gt;在動手寫程式碼之前，許多工程師常會問兩個問題：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;em&gt;「為什麼不直接把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/*.json&lt;/code&gt; 整份 JSON 丟給優化器 LLM，讓它自己改 Prompt 就好？」&lt;/em&gt;&lt;/li&gt;
  &lt;li&gt;&lt;em&gt;「為什麼還需要把 Phase 5 的 OpenTelemetry Spans 轉成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;？只看最後的 LINE 回覆文字與總分不夠嗎？」&lt;/em&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;這兩個問題正好觸及了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 論文中最核心的兩個工程設計：&lt;strong&gt;零洩漏屏障（Zero-Leakage Barrier）&lt;/strong&gt; 與 &lt;strong&gt;行為軌跡對照（Behavioral Trajectory Contrast）&lt;/strong&gt;。&lt;/p&gt;

&lt;h2 id=&quot;1-為什麼需要零洩漏屏障zero-leakage-barrier防止優化器背答案作弊&quot;&gt;1. 為什麼需要「零洩漏屏障（Zero-Leakage Barrier）」？防止優化器「背答案作弊」&lt;/h2&gt;

&lt;p&gt;試想一下：如果我們把 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/harness2-challenge-dataset.json&lt;/code&gt; 裡的黃金答案（例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expected_contains: [&quot;+81-3-1234-5678&quot;, &quot;佐藤健太 (Kenta Sato)&quot;]&lt;/code&gt;）直接暴露給 Agent 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 Harvester LLM，會發生什麼事？&lt;/p&gt;

&lt;p&gt;優化器最偷懶、也最容易拿滿分的作法，就是在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt; 寫下一行：&lt;/p&gt;
&lt;blockquote&gt;
  &lt;p&gt;&lt;em&gt;「如果輸入包含 Sato，請直接輸出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+81-3-1234-5678&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;佐藤健太 (Kenta Sato)&lt;/code&gt;。」&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;這在機器學習中稱為 &lt;strong&gt;測試集洩漏（Test Set Leakage / Overfitting to Rubrics）&lt;/strong&gt; —— Agent 看似在 Benchmark 拿了 100 分，但一遇到真實世界的新日本名片就立刻崩潰！&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    Dataset[&quot;eval/datasets/*.json\n完整測試案例\n(含 expected_contains / expected_route)&quot;]

    subgraph Barrier[&quot;Zero-Leakage Barrier (零洩漏屏障)&quot;]
        Brief[&quot;TaskBrief (公開題目卷)\n僅含 task_id, prompt, session_input\n❌ 絕不含 expected_* 黃金答案&quot;]
        Scorer[&quot;Isolated Scorer (黑箱閱卷官)\n持有獨立隐藏的 r1..r4 Rubrics&quot;]
    end

    Agent[&quot;Go ADK Graph Workflow\n(cmd/harness-runner)&quot;]
    Harvester[&quot;Harness² Harvester\n(Propose / Probe / Compose)&quot;]

    Dataset --&amp;gt; Brief
    Dataset --&amp;gt; Scorer
    Brief --&amp;gt;|&quot;公開輸入&quot;| Agent
    Agent --&amp;gt;|&quot;Deliverable + OTel trajectory.md&quot;| Scorer
    Scorer --&amp;gt;|&quot;僅回傳二元分數 {r1: 1.0, r2: 0.0}\n與 OTel 執行軌跡&quot;| Harvester
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BenchmarkAdapter&lt;/code&gt; 架構中：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TaskBrief&lt;/code&gt;（公開題目卷）&lt;/strong&gt;：只能包含使用者輸入（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prompt&lt;/code&gt; 與模擬圖片/上下文），&lt;strong&gt;絕對禁止包含任何 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expected_contains&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expected_not_contains&lt;/code&gt; 或正確答案字串&lt;/strong&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;score()&lt;/code&gt;（黑箱閱卷官）&lt;/strong&gt;：在隔離環境中比對答案後，只回傳「哪一個 Rubric 拿到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.0&lt;/code&gt;」（例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r3_e164_jp_phone_normalization: 0.0&lt;/code&gt;），而不把預期字串洩漏給優化器。&lt;/li&gt;
  &lt;li&gt;如此一來，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的優化器必須真正透過 &lt;strong&gt;閱讀 Agent 的執行軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;）&lt;/strong&gt; 來推理出通用的領域規則（例如：「日本電話號碼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+81 (0)3-...&lt;/code&gt; 轉 E.164 時必須去掉國內長途冠碼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(0)&lt;/code&gt;」），而不是把答案硬編碼進 Prompt！&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;2-為什麼需要把-phase-5-opentelemetry-spans-變成-trajectorymd打開-13-節點-graph-的黑盒子&quot;&gt;2. 為什麼需要把 Phase 5 OpenTelemetry Spans 變成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;？打開 13 節點 Graph 的黑盒子&lt;/h2&gt;

&lt;p&gt;我們的 LINE AI 名片王不是一個單純的「單次 LLM 呼叫」，而是一個由 &lt;strong&gt;13 個節點組成的 ADK 2.0 有向圖（Graph Workflow）&lt;/strong&gt;：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;名片建檔管線：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt; $\rightarrow$ 平行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanOut&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextMatchNode&lt;/code&gt;）$\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanIn&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;JoinPreviewNode&lt;/code&gt;）$\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BuildPreviewNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ApplyEditNode&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SaveCardNode&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;智慧搜尋與破冰信管線：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BroadSearchNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FormatCarouselNode&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;EmailDraftNode&lt;/code&gt;。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;如果沒有 Phase 5 的 OpenTelemetry Spans，當使用者搜尋 &lt;em&gt;「幫我找竹科做 AI 晶片的業務總監」&lt;/em&gt; 卻得到 &lt;em&gt;「找不到符合條件的名片」&lt;/em&gt;（得分 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25&lt;/code&gt;）時，優化器只看得到最後這句失敗訊息，根本無法判斷：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;是 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt;&lt;/strong&gt; 把搜尋意圖誤判成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chat&lt;/code&gt; 嗎？&lt;/li&gt;
  &lt;li&gt;還是 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt;&lt;/strong&gt; 沒有把台灣科技業口語「竹科」展開成資料庫裡的英文地址 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Hsinchu&lt;/code&gt;、沒把「業務總監」展開成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Sales Director&lt;/code&gt;？&lt;/li&gt;
  &lt;li&gt;還是 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt;&lt;/strong&gt; 的 SQL 查詢邏輯出錯？&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;當我們把 Phase 5 的 OpenTelemetry &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.*&lt;/code&gt; Spans 收集並渲染成結構化的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;&lt;/strong&gt; 後，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Probe&lt;/code&gt; 階段就能清楚看見每一個 Graph Node 的輸入、輸出、耗時、路由決策與載入的技能！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二動手實作-part-2三步打造-linecardadapter&quot;&gt;二、動手實作 Part 2：三步打造 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;&lt;/h1&gt;

&lt;p&gt;對照本文開頭的架構圖，我們透過三個核心元件完成 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;&lt;/strong&gt; 的實作：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/trajectory.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/trajectory.go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;：在 Go 端掛載記憶體內的 OpenTelemetry &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SpanRecorder&lt;/code&gt;，將 13 個 Graph Node 的執行細節匯出為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/cmd/harness-runner/main.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/harness-runner/main.go&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;：提供給 Python &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 呼叫的確定性子程序 CLI，接收 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--harness-dir&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--task-json&lt;/code&gt;，輸出包含 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deliverable&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory_markdown&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;spans&lt;/code&gt; 的 JSON。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/harness/line_card_adapter.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/line_card_adapter.py&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;：實作 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BenchmarkAdapter&lt;/code&gt; 介面，串接 Phase 4 Dataset 與 Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness-runner&lt;/code&gt;。&lt;/li&gt;
&lt;/ol&gt;

&lt;h2 id=&quot;1-實作-internalharnesstrajectorygo將-opentelemetry-spans-渲染為-trajectorymd&quot;&gt;1. 實作 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/trajectory.go&lt;/code&gt;：將 OpenTelemetry Spans 渲染為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;在 Phase 5 中，我們的 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/telemetry.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/telemetry.go&lt;/code&gt;&lt;/a&gt; 已經在每個 Graph Node 呼叫了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;startNodeSpan(ctx, &quot;VisionOCRNode&quot;)&lt;/code&gt;。現在，我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/trajectory.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/trajectory.go&lt;/code&gt;&lt;/a&gt; 中使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go.opentelemetry.io/otel/sdk/trace/tracetest.NewSpanRecorder()&lt;/code&gt; 攔截所有已完成的節點 Span，並將其轉化為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; Harvester LLM 最擅長閱讀的 Markdown 軌跡報告：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;// InstallRecorder registers a new in-memory SpanRecorder as the global OTel TracerProvider&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;// so every workflow.node.* span emitted by internal/workflow/telemetry.go is captured.&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;InstallRecorder&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TrajectoryRecorder&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;sr&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tracetest&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NewSpanRecorder&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;tp&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sdktrace&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NewTracerProvider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sdktrace&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;WithSpanProcessor&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sr&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;prev&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;otel&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;GetTracerProvider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;otel&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SetTracerProvider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

	&lt;span class=&quot;n&quot;&gt;rec&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TrajectoryRecorder&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;recorder&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sr&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tp&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;restore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;_&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tp&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Shutdown&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Background&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;otel&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SetTracerProvider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;prev&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;rec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;restore&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;同時，我們也在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/telemetry.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/telemetry.go&lt;/code&gt;&lt;/a&gt; 新增了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AttrNodeDecision&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk.node.decision&lt;/code&gt;）、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AttrNodeDiagnostic&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk.node.diagnostic&lt;/code&gt;）與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AttrHarnessSkills&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk.harness.skills&lt;/code&gt;）三個 OpenTelemetry Attributes。當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TrajectoryRecorder.RenderMarkdown()&lt;/code&gt; 執行時，會產出如下的高解析度 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-markdown highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;gh&quot;&gt;# ADK 2.0 Go Graph Workflow Execution Trajectory&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Task ID**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`challenge_colloquial_tw_search`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Harness Root**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`harness/base`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Always-On Bytes (`c1..c4`)**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`1599 / 24000`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Final Score**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`0.25`&lt;/span&gt;

&lt;span class=&quot;gu&quot;&gt;## OpenTelemetry Node Spans (`workflow.node.*`)&lt;/span&gt;
&lt;span class=&quot;gu&quot;&gt;### 1. `workflow.node.RouterNode`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Node**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`RouterNode`&lt;/span&gt; | &lt;span class=&quot;gs&quot;&gt;**Status**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`OK`&lt;/span&gt; | &lt;span class=&quot;gs&quot;&gt;**Duration**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`0.02 ms`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Decision**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`intent=search (colloquial_query=幫我找竹科做 AI 晶片的業務總監，我要聯絡台灣半導體客戶)`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Diagnostic**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`routed search query to QueryIntentNode`&lt;/span&gt;

&lt;span class=&quot;gu&quot;&gt;### 2. `workflow.node.QueryIntentNode`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Node**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`QueryIntentNode`&lt;/span&gt; | &lt;span class=&quot;gs&quot;&gt;**Status**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`OK`&lt;/span&gt; | &lt;span class=&quot;gs&quot;&gt;**Duration**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`0.04 ms`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Decision**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`parsed_filters={&quot;location&quot;:&quot;竹科&quot;,&quot;role&quot;:&quot;業務總監&quot;,&quot;industry&quot;:&quot;AI 晶片&quot;}`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Diagnostic**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`UNEXPANDED_COLLOQUIAL_FILTERS: colloquial Taiwan science park alias &apos;竹科&apos; and Mandarin title &apos;業務總監&apos; were passed literally without bilingual synonym expansion; add a c6 skill &apos;tw_semicon_search&apos; with BILINGUAL_SYNONYM_MAP`&lt;/span&gt;

&lt;span class=&quot;gu&quot;&gt;### 3. `workflow.node.HybridSearchNode`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Node**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`HybridSearchNode`&lt;/span&gt; | &lt;span class=&quot;gs&quot;&gt;**Status**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`OK`&lt;/span&gt; | &lt;span class=&quot;gs&quot;&gt;**Duration**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`0.03 ms`&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;gs&quot;&gt;**Decision**&lt;/span&gt;: &lt;span class=&quot;sb&quot;&gt;`matched_cards=0 (strict literal filter on location=&apos;竹科&apos; failed against DB address=&apos;Hsinchu Science Park (竹科)&apos;)`&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;請注意看第 2 個節點 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.QueryIntentNode&lt;/code&gt; 與第 3 個節點 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.HybridSearchNode&lt;/code&gt; 的 Span 紀錄！透過這份軌跡，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose&lt;/code&gt; 階段一眼就能看出：&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt; 沒錯，錯在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; 把「竹科」當成死板字串去查英文地址欄位&lt;/strong&gt;！&lt;/p&gt;

&lt;h2 id=&quot;2-擴充-phase-4-評估集evaldatasetsharness2-challenge-datasetjson&quot;&gt;2. 擴充 Phase 4 評估集：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/harness2-challenge-dataset.json&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;為了完整測試 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 在保留既有能力（防止災難性遺忘）與攻克高難度邊界案例的能力，我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/datasets/harness2-challenge-dataset.json&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/harness2-challenge-dataset.json&lt;/code&gt;&lt;/a&gt; 中建立了 &lt;strong&gt;8 個任務（共 32 個細粒度 Rubrics）&lt;/strong&gt;：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;任務類別&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Task ID&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;測試場景描述&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;4 個獨立評分 Rubrics (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r1..r4&lt;/code&gt;)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Baseline (回歸基準)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_ingest_ming_wang&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;標準繁體中文名片建檔（王小明 / 台灣雲端科技）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;意圖路由、姓名職稱擷取、E.164 電話正規化、產業標籤富化&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Baseline (回歸基準)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_dedup_appier_promotion&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;同人升遷名片去重更新（林雅婷 Senior $\rightarrow$ VP）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;去重偵測、升遷職稱更新、新手機保留、公司一致&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Baseline (回歸基準)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_search_cloud_summit_ai&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;標準關鍵字搜尋（Cloud Summit + AI）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;搜尋路由、多筆命中、標籤呈現、互動按鈕&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Baseline (回歸基準)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baseline_email_google_cloud&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;一般科技業跟進破冰信（陳建宏 / Google Cloud）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Email 路由、收件人與活動提及、議程連結、專業結尾&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Challenge (演化挑戰 1)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_jp_bilingual_ingest&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;日英雙語名片 OCR 與日本電話正規化&lt;/strong&gt;（佐藤健太 / 取締役 CTO / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+81 (0)3-1234-5678&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r1&lt;/code&gt; 路由、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r2&lt;/code&gt; 雙語姓名保留、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r3&lt;/code&gt; &lt;strong&gt;日本 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+81&lt;/code&gt; 移除 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(0)&lt;/code&gt; 正規化&lt;/strong&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r4&lt;/code&gt; &lt;strong&gt;日文役職雙語映射&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Challenge (演化挑戰 2)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_colloquial_tw_search&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;台灣科技業口語別稱搜尋&lt;/strong&gt;（「幫我找竹科做 AI 晶片的業務總監」）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r1&lt;/code&gt; 路由、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r2&lt;/code&gt; &lt;strong&gt;竹科 $\leftrightarrow$ Hsinchu 雙語展開命中&lt;/strong&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r3&lt;/code&gt; &lt;strong&gt;業務總監 $\leftrightarrow$ Sales Director 職稱展開&lt;/strong&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r4&lt;/code&gt; 標籤完整呈現&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Challenge (演化挑戰 3)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_noisy_multi_edit_hitl&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;多子句口語 HITL 連續修正&lt;/strong&gt;（「拍謝更正一下，頭銜應該是集團資深副總才對，另外手機後面改成 8899，備註幫我加上 GDG DevFest 講者」）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r1&lt;/code&gt; HITL Edit 路由、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r2&lt;/code&gt; &lt;strong&gt;多欄位原子更新（職稱）&lt;/strong&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r3&lt;/code&gt; &lt;strong&gt;手機尾碼局部替換與備註追加&lt;/strong&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r4&lt;/code&gt; 保留原公司與 Email 不被覆蓋&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Challenge (演化挑戰 4)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;challenge_pii_safe_executive_followup&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;金融業高管合規與個資遮罩破冰信&lt;/strong&gt;（張雅筑 / 國泰金控 數位風控長，要求隱私保護與外寄合規標頭）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r1&lt;/code&gt; Email 路由、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r2&lt;/code&gt; 高管稱謂與場景、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r3&lt;/code&gt; &lt;strong&gt;手機與私人 Email 個資遮罩（PII Redaction）&lt;/strong&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;r4&lt;/code&gt; &lt;strong&gt;金融業合規主旨標頭 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[Confidential / FinTech Compliance Verified]&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;3-實作-harnessline_card_adapterpy對接-google-researchharness2&quot;&gt;3. 實作 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/line_card_adapter.py&lt;/code&gt;：對接 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;最後，我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/harness/line_card_adapter.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/line_card_adapter.py&lt;/code&gt;&lt;/a&gt; 中實作了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;，將上述所有元件串接起來：&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;class&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;LineCardAdapter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;Adapts `line-card-assistant` to the `google-research/harness2` BenchmarkAdapter protocol.&quot;&quot;&quot;&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;list_tasks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;list&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TaskBrief&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;Return public task briefs with zero ground-truth rubric leakage.&quot;&quot;&quot;&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;briefs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;list&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TaskBrief&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_raw_cases&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# Strip `rubrics` and `expected_*` so the agent/harvester never sees ground truth.
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;briefs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;TaskBrief&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                    &lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
                    &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;prompt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
                    &lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                        &lt;span class=&quot;s&quot;&gt;&quot;category&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;category&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;general&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                        &lt;span class=&quot;s&quot;&gt;&quot;description&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;description&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                        &lt;span class=&quot;s&quot;&gt;&quot;session_input&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;session_input&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}),&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;briefs&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;run&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;TaskBrief&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunArtifact&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;Mount `harness` in a temporary directory and execute the Go Graph Workflow runner.&quot;&quot;&quot;&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;validate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;diag&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;# Harness Validation Failed&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;join&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;- &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;p&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;p&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunArtifact&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;deliverable&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;trajectory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;diag&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

        &lt;span class=&quot;k&quot;&gt;with&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tempfile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TemporaryDirectory&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;prefix&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;line_card_harness_&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;_&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tmp_dir&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;harness_root&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Path&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tmp_dir&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;materialize&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;harness_root&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# Invoke the compiled Go binary with --harness-dir pointing to the materialized c1..c8 tree
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;proc&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;subprocess&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;run&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;binary&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;--harness-dir=&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;harness_root&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;--task-json=&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_payload_path&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;capture_output&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;check&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;timeout&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;30&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;proc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;stdout&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunArtifact&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;deliverable&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;deliverable&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;trajectory&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;trajectory_markdown&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;score&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;TaskBrief&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;artifact&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;RunArtifact&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ScoreResult&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;Evaluate the deliverable against isolated per-rubric criteria.&quot;&quot;&quot;&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_cases_by_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;rubrics&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;raw&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;rubrics&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{})&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;float&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;rubric_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;spec&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;rubrics&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;items&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;rubric_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;1.0&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_evaluate_rubric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;artifact&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;deliverable&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;spec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;0.0&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;total&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;sum&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;values&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;0.0&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ScoreResult&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;task_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;total&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;round&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;total&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;4&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;per_rubric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;透過這個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;每當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 提出一個新的候選 Harness $H’$，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adapter.run(harness, task)&lt;/code&gt; 就會先呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness.validate()&lt;/code&gt; 檢查 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OPENCODE_SURFACE&lt;/code&gt; 的 24KB 上限與 Skill Frontmatter 規則。&lt;/li&gt;
  &lt;li&gt;驗證通過後，將 $H’$ 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案實體化（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;materialize&lt;/code&gt;）到暫存目錄，並交給 Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness-runner&lt;/code&gt; 執行。&lt;/li&gt;
  &lt;li&gt;Go 執行完 13 節點 Graph Workflow 後，回傳最終的 LINE 訊息（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deliverable&lt;/code&gt;）與 OpenTelemetry 軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory_markdown&lt;/code&gt;），交由 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adapter.score()&lt;/code&gt; 進行無洩漏的獨立評分！&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三小結與下一篇預告&quot;&gt;三、小結與下一篇預告&lt;/h1&gt;

&lt;p&gt;在這篇（中篇）中，我們完成了 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;&lt;/strong&gt; 的核心工程：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;釐清了為什麼不能直接把黃金測試集餵給優化器 —— 透過 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TaskBrief&lt;/code&gt; 零洩漏屏障（Zero-Leakage Barrier）&lt;/strong&gt;，我們強制 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 從行為軌跡推理出通用技能，而非死背答案。&lt;/li&gt;
  &lt;li&gt;透過 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/trajectory.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/trajectory.go&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/cmd/harness-runner/main.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/harness-runner/main.go&lt;/code&gt;&lt;/a&gt;，把 &lt;strong&gt;Phase 5 的 OpenTelemetry &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.*&lt;/code&gt; Spans&lt;/strong&gt; 轉化為高解析度的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;，打開了 13 節點 Graph Workflow 的黑盒子。&lt;/li&gt;
  &lt;li&gt;建立了 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/datasets/harness2-challenge-dataset.json&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/harness2-challenge-dataset.json&lt;/code&gt;&lt;/a&gt;（8 大任務、32 個細粒度 Rubrics）與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/harness/line_card_adapter.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/line_card_adapter.py&lt;/code&gt;&lt;/a&gt;，完美實作了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BenchmarkAdapter&lt;/code&gt; 協定。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;萬事俱備！在最終篇 &lt;strong&gt;&lt;a href=&quot;/2026/10/27/adk-graph-workflow-go-9/&quot;&gt;[Agent Platform 實戰 (9)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (下)：雙層遞迴測試指南、62.5% 到 100% 效能實測與 AgentOps 未來展望&lt;/a&gt;&lt;/strong&gt;（對應 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/18&quot;&gt;Issue #18&lt;/a&gt;&lt;/strong&gt;）中，我們將實際啟動雙層遞迴優化實驗，揭曉從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;62.5%&lt;/code&gt; 一路進化到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100.0%&lt;/code&gt; 的完整量化數據，並探討 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 對未來企業級 Agent 開發的深遠影響！&lt;/p&gt;
</description>
				<pubDate>Sun, 25 Oct 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/adk-graph-workflow-go-8/</link>
				<guid isPermaLink="true">https://www.evanlin.com/adk-graph-workflow-go-8/</guid>
			</item>
		
			<item>
				<title>[Agent Platform 實戰 (7)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (上)：認識雙層遞迴 Agent 裝備框架與 c1..c8 解耦實戰</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/line-card-harness2-part1-before-arch.png&quot; alt=&quot;Harness² Part 1 Architecture: Current Architecture vs c1..c8 Editable Harness Tree&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前言當-ai-agent-上線之後下一個瓶頸是什麼&quot;&gt;前言：當 AI Agent 上線之後，下一個瓶頸是什麼？&lt;/h1&gt;

&lt;p&gt;歡迎回到《&lt;strong&gt;Agent Platform 實戰&lt;/strong&gt;》系列！在前六篇文章中，我們帶著 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;LINE AI 名片王 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-card-assistant&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt; 走完了從單機原型到生產級雲端部署的完整五個階段：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/16/adk-graph-workflow-go/&quot;&gt;[Agent Platform 實戰 (1)] 用 Go 與 Google ADK 2.0 Graph Workflow 打造 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;：用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk/v2/workflow&lt;/code&gt; 打造具備 Vision OCR、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanOut&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanIn&lt;/code&gt; 平行背景調查與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NewRequestInputEvent&lt;/code&gt; HITL 互動迴圈的 13 節點有向圖。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/17/adk-graph-workflow-go-2/&quot;&gt;[Agent Platform 實戰 (2)] 從單體 Cloud Run 邁向 Google Cloud Agent Runtime&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 1（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/10&quot;&gt;PR #10&lt;/a&gt;）&lt;/strong&gt;，將專案標準化為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_go&lt;/code&gt;) 雙通道架構。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/20/adk-graph-workflow-go-3/&quot;&gt;[Agent Platform 實戰 (3)] 用 ADK 2.0 GCS Artifact Service 與 Agent Platform Sessions 實現跨實例名片辨識與暫停恢復&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 2 前半（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/11&quot;&gt;PR #11&lt;/a&gt;）&lt;/strong&gt;，解決無狀態容器的 HITL 失憶症與二進位圖片爆量問題。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/21/adk-graph-workflow-go-4/&quot;&gt;[Agent Platform 實戰 (4)] 用 Cloud Run LINE Webhook Gateway、Agent Runtime 與 Cloud SQL PostgreSQL 完成架構拼圖&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 2 後半 &amp;amp; Phase 3（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/12&quot;&gt;PR #12&lt;/a&gt;）&lt;/strong&gt;，將名片庫升級至 Cloud SQL PostgreSQL 並實現雙層無狀態解耦。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/22/adk-graph-workflow-go-5/&quot;&gt;[Agent Platform 實戰 (5)] 用 agents-cli eval 與 ADK 2.0 Go 建立自動化評估基準&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 4（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13&lt;/a&gt;）&lt;/strong&gt;，建立黃金測試集與品質飛輪。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/24/adk-graph-workflow-go-6/&quot;&gt;[Agent Platform 實戰 (6)] 用 agents-cli deploy、Terraform IaC、GitHub Actions CI/CD 與 Cloud Trace 打造全棧可觀測的 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 5（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/14&quot;&gt;PR #14&lt;/a&gt;）&lt;/strong&gt;，把 13 個 Graph Node 全數加上 OpenTelemetry Spans (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.node.*&lt;/code&gt;) 並透過 Terraform 與 GitHub Actions 部署上雲。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;此外，我們也將未來 ADK v2.6+ 進階 Graph Workflow 原語（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Parallel&lt;/code&gt; 動態派工、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MultiRoute&lt;/code&gt; 多路扇出、反思修復迴圈與強型別節點）規劃進了 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/15&quot;&gt;Future Roadmap Issue #15&lt;/a&gt;&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;然而，當我們的 Agent 已經具備了 &lt;strong&gt;Phase 4 的自動化評估（Evaluation）&lt;/strong&gt; 與 &lt;strong&gt;Phase 5 的全節點追蹤（OpenTelemetry Spans）&lt;/strong&gt; 後，一個更深層的問題浮現了：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;strong&gt;當評估發現 Agent 在某些真實世界案例（例如日英雙語名片、台灣科技業口語別稱搜尋、多子句口語 HITL 修改、或金融合規破冰信）表現不佳時，難道每次都要由工程師手動看 Log、手動改 Go 原始碼裡的 Prompt 字串、再重新編譯部署嗎？&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;能不能讓一個 &lt;strong&gt;Meta-Agent（裝備工程師 Agent）&lt;/strong&gt; 自動讀取我們的評估結果與 OpenTelemetry 執行軌跡，自己診斷失分原因、自己撰寫新技能（Skills）與長期記憶（Long-Term Memory），完成閉環的自我演化？&lt;/p&gt;

&lt;p&gt;這正是 Google Research 最新發表並開源的 &lt;strong&gt;&lt;a href=&quot;https://github.com/google-research/harness2&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt; (&lt;em&gt;Harness²: Recursive Harnessing for LLM Agents&lt;/em&gt;, arXiv:2610.14224)&lt;/a&gt;&lt;/strong&gt; 所要解決的核心命題！&lt;/p&gt;

&lt;p&gt;本系列將以三篇文章（對應 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/16&quot;&gt;Issue #16&lt;/a&gt;&lt;/strong&gt;、&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;&lt;/strong&gt;、&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/18&quot;&gt;Issue #18&lt;/a&gt;&lt;/strong&gt; 與 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/19&quot;&gt;PR #19&lt;/a&gt;&lt;/strong&gt;），完整帶大家將 &lt;strong&gt;Google Research &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt;&lt;/strong&gt; 導入我們的 Go ADK 2.0 專案：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;上篇（本文，&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/16&quot;&gt;Issue #16&lt;/a&gt;）&lt;/strong&gt;：認識什麼是 Google &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt;？它能做什麼用？盤點修改前的既有架構圖，並將 Go 二進位檔中寫死的設定解耦為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 可編輯 Harness 檔案樹。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;中篇（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;）&lt;/strong&gt;：將 Phase 4 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/&lt;/code&gt; 與 Phase 5 的 OpenTelemetry Spans 封裝為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;，並剖析為什麼「零洩漏屏障」與「高解析度行為軌跡」缺一不可。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;下篇（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/18&quot;&gt;Issue #18&lt;/a&gt;）&lt;/strong&gt;：完整測試教學、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Parallel&lt;/code&gt; vs &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Sequential + LongTermMEMORY&lt;/code&gt; 雙層遞迴實驗數據大公開（準確率從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;62.5%&lt;/code&gt; 躍升至 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;100.0%&lt;/code&gt;），以及對 Agent 未來發展的展望。&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一什麼是-google-research-harness它能做什麼用&quot;&gt;一、什麼是 Google Research &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt;？它能做什麼用？&lt;/h1&gt;

&lt;h2 id=&quot;1-從微調模型權重到優化-agent-裝備harnessing&quot;&gt;1. 從「微調模型權重」到「優化 Agent 裝備（Harnessing）」&lt;/h2&gt;

&lt;p&gt;在大型語言模型（LLM）時代，決定一個 AI Agent 成敗的往往不只是底層模型（如 Gemini 2.5 Flash / Pro）本身，而是包裹在模型外層的 &lt;strong&gt;「裝備層（Agent Harness）」&lt;/strong&gt; —— 也就是系統提示詞（System Prompts）、格式與安全護欄（Guardrails）、長期領域記憶（Long-Term Memory）、工具介面說明（Tool Descriptions）、子代理設定（Sub-Agents）以及按需載入的技能庫（On-Demand Skills）。&lt;/p&gt;

&lt;p&gt;過去的自動提示詞優化（如 PromptBreeder、TextGrad 或 DSPy）大多只針對 &lt;strong&gt;單一 Prompt 字串&lt;/strong&gt; 進行突變；但在真實的企業級 Agent 中，如果你把所有邊界案例的修補規則全部塞進同一個 System Prompt，很快就會引發 &lt;strong&gt;「上下文膨脹（Context Bloat）」&lt;/strong&gt;：Always-On Token 越來越多，不但擠壓了模型的輸出預算（Output Token Budget），不同規則之間還會互相干擾！&lt;/p&gt;

&lt;p&gt;Google Research 提出的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; (&lt;em&gt;Recursive Harnessing for LLM Agents&lt;/em&gt;, arXiv:2610.14224)&lt;/strong&gt; 打破了這個限制。它將整個 Agent 的裝備定義為一棵結構化的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 可編輯檔案樹（Editable Component Tree）&lt;/strong&gt;，並透過 &lt;strong&gt;雙層遞迴（Two-Level Recursion）&lt;/strong&gt; 自動演化這棵檔案樹：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
    subgraph Outer[&quot;外層遞迴：Harnessing-Level Recursion (跨輪次經驗累積 k=1..K)&quot;]
        Reflector[&quot;Experience Reflector\n(ReflectorPrompt)\n跨輪次提煉成功與失敗模式&quot;]
        Memory[&quot;c3: LongTermMEMORY.md\n跨迭代持久化領域經驗&quot;]
        Reflector --&amp;gt;|寫入長期規則| Memory
    end

    subgraph Inner[&quot;內層遞迴：Task-Level Recursion (單一輪次內閉環診斷與修補)&quot;]
        Propose[&quot;1. Propose (診斷提案)\n讀取執行軌跡 trajectory.md\n定位行為缺陷並提出 N 個候選 Patch&quot;]
        Probe[&quot;2. Probe (沙盒探測)\n平行執行 N 個候選 Harness\n對比修改前後的軌跡與分數變化&quot;]
        Compose[&quot;3. Compose (衝突消融與合成)\n保留正收益 Patch、剔除負向干擾\n合成出新一代最佳 Harness H^(k)&quot;]
        Propose --&amp;gt; Probe --&amp;gt; Compose
    end

    Memory --&amp;gt; Propose
    Compose --&amp;gt; Reflector
&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;2-harness-的-c1c8-八大裝備組件與-24kb-預算上限&quot;&gt;2. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 八大裝備組件與 24KB 預算上限&lt;/h2&gt;

&lt;p&gt;在 &lt;a href=&quot;https://github.com/google-research/harness2/blob/main/harness2/harness.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2/harness.py&lt;/code&gt;&lt;/a&gt; 中，一個標準的 Agent Harness 由 &lt;strong&gt;4 個常駐組件（Always-On Components, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt;）&lt;/strong&gt; 與 &lt;strong&gt;4 個按需載入組件（On-Demand Components, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c5..c8&lt;/code&gt;）&lt;/strong&gt; 組成：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;組件代號&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;檔案路徑規則&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;載入模式&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 中的職責&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Always-On (常駐)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;定義核心角色、各節點職責與觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; 技能的索引規則（Skill Trigger Lines）。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c2&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;guardrails.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Always-On (常駐)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;定義不可違反的輸出格式（如純 JSON 約束）、E.164 正規化不變量與資安/PII 護欄。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c3&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LongTermMEMORY.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Always-On (常駐)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;由外層 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Experience Reflector&lt;/code&gt; 跨輪次寫入的領域教訓與產業合規記憶。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c4&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool_descriptions/*.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Always-On (常駐)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;工具參數說明、搜尋策略與正規化細節（如日本長途冠碼 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(0)&lt;/code&gt; 清理規則）。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c5&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sub_agents/&amp;lt;name&amp;gt;/AGENT.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;On-Demand (按需)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;委派子代理（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;company_enrich&lt;/code&gt;）的專屬 Instruction 與 YAML Frontmatter (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mode: subagent&lt;/code&gt;)。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/&amp;lt;name&amp;gt;/SKILL.md&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;On-Demand (按需)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;針對特定領域或任務才動態注入的專業技能（如日文名片 OCR、竹科口語搜尋擴展）。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c7&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;scripts/*.py&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;On-Demand (按需)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;輔助檢驗或資料轉換腳本。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c8&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;plugin/*.ts&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;On-Demand (按需)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;執行期生命週期與 OpenTelemetry 診斷鉤子。&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;blockquote&gt;
  &lt;p&gt;[!IMPORTANT]
&lt;strong&gt;為什麼要區分 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt;（常駐）與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c5..c8&lt;/code&gt;（按需）？&lt;/strong&gt;
&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OPENCODE_SURFACE&lt;/code&gt; 中設定了一條鐵律：&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c4&lt;/code&gt; 常駐檔案的總位元組數絕對不能超過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;24,000 bytes&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AlwaysOnMaxBytes = 24000&lt;/code&gt;）&lt;/strong&gt;！
當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 發現某個失敗案例需要冗長的領域知識（例如日本企業名片的事業部職銜對照表、或台灣半導體園區口語縮寫字典）時，它不會把這些規則硬塞進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt; 造成常駐 Context 爆炸，而是會自動建立一個按需載入的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; 技能檔（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/&amp;lt;name&amp;gt;/SKILL.md&lt;/code&gt;）&lt;/strong&gt;，並在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt; 中只留下一行輕量的觸發條件（Trigger Line）！&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;3-雙層遞迴優化two-level-recursion是怎麼運作的&quot;&gt;3. 雙層遞迴優化（Two-Level Recursion）是怎麼運作的？&lt;/h2&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的演化引擎（&lt;a href=&quot;https://github.com/google-research/harness2/blob/main/harness2/core/recursion.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness2/core/recursion.py&lt;/code&gt;&lt;/a&gt;）包含兩個層次的遞迴：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;第一層（內層）：Task-Level Recursion (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Probe&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Compose&lt;/code&gt;)&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose&lt;/code&gt;（診斷提案）&lt;/strong&gt;：優化器（Harvester LLM）觀察上一輪在基準測試中失分的任務、最終輸出（Deliverable）以及 &lt;strong&gt;執行軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;trajectory.md&lt;/code&gt;）&lt;/strong&gt;，診斷出 Agent 在哪一個步驟做錯了決策，並提出多個獨立的候選修補方案（Candidate Patches，每個方案是一組針對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 的檔案新增或修改）。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Probe&lt;/code&gt;（沙盒探測）&lt;/strong&gt;：系統將每個候選 Patch 分別掛載到沙盒中實際跑一次任務，收集新的分數與新的執行軌跡，形成「修改前 vs 修改後」的行為對照（Behavioral Contrast）。&lt;/li&gt;
      &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Compose&lt;/code&gt;（衝突消融與合成）&lt;/strong&gt;：優化器比較所有候選 Patch 的實測表現，將真正帶來正向分數提升的修改合併成新一代的 Harness $H^{(k)}$，並丟棄無效或引發副作用的修改。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;第二層（外層）：Harnessing-Level Recursion (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Experience Reflector&lt;/code&gt;)&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;在多輪迭代（$k = 1 \dots K$）之間，外層的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ReflectorPrompt&lt;/code&gt; 會檢視從 $H^{(0)} \to H^{(1)} \to \dots \to H^{(k)}$ 的演化歷史：哪些類型的修改成功了？哪些跨領域的限制（例如金融業合規標頭與個資保護規範）需要在全局層面被記住？&lt;/li&gt;
      &lt;li&gt;提煉出的高階經驗會被寫入 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c3: LongTermMEMORY.md&lt;/code&gt;&lt;/strong&gt;，指導下一輪的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose&lt;/code&gt; 與 Agent 執行。&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二盤點修改前的目前架構為什麼-phase-15-的-go-實作無法直接被-harness-優化&quot;&gt;二、盤點修改前的目前架構：為什麼 Phase 1~5 的 Go 實作無法直接被 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 優化？&lt;/h1&gt;

&lt;p&gt;讓我們對照文章開頭架構圖的 &lt;strong&gt;左半邊（Before: Hardcoded Go Binary Architecture）&lt;/strong&gt;，回顧我們在 Phase 1 到 Phase 5 完成的系統架構：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    subgraph Before[&quot;修改前：Phase 1~5 固態編譯架構 (Hardcoded Go Binary)&quot;]
        direction TB
        N1[&quot;nodes_ingest.go\n硬編碼 VisionOCR / CleanAndDedup /\nCompanyEnrich / ApplyEdit Prompts&quot;]
        N2[&quot;nodes_search.go\n硬編碼 QueryIntent /\nEmailDraft Prompts&quot;]
        N3[&quot;graph.go\n固定 SubAgent Instruction&quot;]
        E[&quot;eval/datasets/basic-dataset.json\nPhase 4 黃金測試集&quot;]
        T[&quot;telemetry.go\nPhase 5 OpenTelemetry 13-Node Spans&quot;]
    end

    Problem[&quot;痛點：\n1. Prompt 寫死在 .go 字串常數，每次調整都要重新 go build\n2. 缺乏按需載入的 c6 Skills 機制\n3. Phase 4 Eval 與 Phase 5 OTel Spans 尚未串接成自動優化閉環&quot;]
    Before --&amp;gt; Problem
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;在修改前的程式碼中：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ApplyEditNode&lt;/code&gt;（位於 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_ingest.go&lt;/code&gt;）&lt;/strong&gt; 以及 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;EmailDraftNode&lt;/code&gt;（位於 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_search.go&lt;/code&gt;）&lt;/strong&gt; 的所有 Prompt 模版，全部都是寫死在 Go 程式碼裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;fmt.Sprintf(...)&lt;/code&gt; 字串常數。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichAgent&lt;/code&gt;（位於 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_ingest.go&lt;/code&gt;）&lt;/strong&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent.Config{Instruction: ...}&lt;/code&gt; 也是寫死在 Go 函式裡的固定字串。&lt;/li&gt;
  &lt;li&gt;當我們想要讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 Python 演化迴圈去修改系統提示詞、新增一個日文名片辨識技能（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/jp_card_ocr/SKILL.md&lt;/code&gt;）或調整電話號碼正規化指導原則（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool_descriptions/tool_guidance.md&lt;/code&gt;）時，&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 總不可能去改寫我們的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.go&lt;/code&gt; 原始碼並每跑一個 Task 就重新 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go build&lt;/code&gt; 一次&lt;/strong&gt;！&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;因此，導入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的第一步（&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/16&quot;&gt;Issue #16&lt;/a&gt;&lt;/strong&gt;），就是要把 Go 編譯期與 Harness 裝備期徹底解耦：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Go Binary 負責「圖撲結構與雙通道執行引擎」&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt;、平行 Fan-Out/Fan-In、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; 暫停恢復、Cloud SQL 與 GCS Artifact 存取、OpenTelemetry 埋點。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;外部 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; Harness 檔案樹負責「可演化的大腦與技能裝備」&lt;/strong&gt;：透過環境變數 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CARD_HARNESS_DIR&lt;/code&gt; 在執行期動態熱載入（Hot-Reload）！&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三動手實作-part-1打造-internalharness-載入器與-harnessbase-初始裝備樹&quot;&gt;三、動手實作 Part 1：打造 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness&lt;/code&gt; 載入器與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt; 初始裝備樹&lt;/h1&gt;

&lt;p&gt;為了讓 Go ADK 2.0 Graph Workflow 原生理解 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 規格，我們在專案中新增了兩個核心目錄：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/tree/main/harness/base&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt;&lt;/a&gt;：存放初始未演化（$k=0$）的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 基準檔案樹。&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/harness.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/harness.go&lt;/code&gt;&lt;/a&gt;：負責載入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案樹、驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OPENCODE_SURFACE&lt;/code&gt; 24KB 限制與 YAML Frontmatter 規則、並為每個 Graph Node 動態組合常駐上下文與按需技能。&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;1-建立-harnessbase-基準-c1c8-檔案樹&quot;&gt;1. 建立 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt; 基準 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 檔案樹&lt;/h2&gt;

&lt;p&gt;我們將原本散落在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nodes_ingest.go&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nodes_search.go&lt;/code&gt; 的基礎設定抽離到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt; 目錄下：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;harness/base/
├── systemprompt.md                     # c1: 核心角色與各 Graph Node 職責總覽
├── guardrails.md                       # c2: JSON 輸出格式與電話正規化護欄
├── LongTermMEMORY.md                   # c3: 跨輪次長期記憶（初始為空，待 Reflector 寫入）
├── tool_descriptions/
│   └── tool_guidance.md                # c4: google_search 與 format_company_profile 指導
├── sub_agents/
│   └── company_enrich/
│       └── AGENT.md                    # c5: CompanyEnrichAgent 委派子代理定義
├── skills/                             # c6: 按需載入技能目錄（待 Propose-Probe-Compose 演化生成）
├── scripts/                            # c7: 輔助腳本目錄
└── plugin/                             # c8: 診斷外掛目錄
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;例如，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/sub_agents/company_enrich/AGENT.md&lt;/code&gt; 採用了與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-research/harness2&lt;/code&gt; 完全相容的 YAML Frontmatter 格式：&lt;/p&gt;

&lt;div class=&quot;language-markdown highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nn&quot;&gt;---&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;mode&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;subagent&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;Searches Google to summarize company background and industry tags.&lt;/span&gt;
&lt;span class=&quot;nn&quot;&gt;---&lt;/span&gt;
你是一位專業商業分析助理。請使用 google_search 工具查詢使用者提供的公司名稱，接著呼叫 format_company_profile 工具回傳兩句話的繁體中文公司簡介與 3 到 5 個技術或產業標籤（例如 AI, Cloud, SaaS, FinTech, Semiconductor）。
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;2-實作-internalharnessharnessgo24kb-常駐預算驗證與按需技能注入&quot;&gt;2. 實作 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/harness.go&lt;/code&gt;：24KB 常駐預算驗證與按需技能注入&lt;/h2&gt;

&lt;p&gt;在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/harness.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/harness.go&lt;/code&gt;&lt;/a&gt; 中，我們實作了與 Python 版 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OPENCODE_SURFACE.validate()&lt;/code&gt; 完全對齊的驗證器 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Validate()&lt;/code&gt; 與節點提示詞合成器 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ComposeNodePrompt()&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;// AlwaysOnMaxBytes matches google-research/harness2 OPENCODE_SURFACE.always_on_max (24,000 bytes).&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AlwaysOnMaxBytes&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;m&quot;&gt;24000&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;// AlwaysOnFiles lists the four c1..c4 always-on files mounted into the agent context.&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;var&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AlwaysOnFiles&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;systemprompt.md&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;guardrails.md&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;LongTermMEMORY.md&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;tool_descriptions/tool_guidance.md&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;// Validate enforces Google Research Harness² OPENCODE_SURFACE invariants on the c1..c8 tree.&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;h&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Validate&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;var&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;reqFile&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;range&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AlwaysOnFiles&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strings&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TrimSpace&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Files&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;reqFile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;])&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;missing or empty always-on component %q&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;reqFile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;total&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AlwaysOnBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;total&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AlwaysOnMaxBytes&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
			&lt;span class=&quot;s&quot;&gt;&quot;always-on c1..c4 byte count %d exceeds cap %d (every token here competes with the agent&apos;s output budget)&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;total&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AlwaysOnMaxBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

	&lt;span class=&quot;n&quot;&gt;combinedAlwaysOn&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SystemPrompt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Guardrails&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dirName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;skill&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;range&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Skills&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;skill&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dirName&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;%s frontmatter name %q must match directory name %q&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;skill&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RelPath&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;skill&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dirName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strings&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TrimSpace&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;skill&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Description&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;%s must include a non-empty description in YAML frontmatter&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;skill&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RelPath&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;strings&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Contains&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;combinedAlwaysOn&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dirName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;problems&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;skill %q is never referenced in systemprompt.md or guardrails.md; add a trigger line naming `%s`&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dirName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dirName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;c&quot;&gt;// ...&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這裡有兩個非常關鍵的工程細節：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;強制檢查 Skill Trigger Reference&lt;/strong&gt;：如果 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; 在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skills/jp_card_ocr/SKILL.md&lt;/code&gt; 新增了一個技能，卻忘記在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;systemprompt.md&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;guardrails.md&lt;/code&gt; 寫下何時該觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;jp_card_ocr&lt;/code&gt;，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Validate()&lt;/code&gt; 會直接報錯攔截，避免產生永遠不會被呼叫的「孤兒技能（Orphan Skill）」。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;節點級動態技能匹配（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MatchSkills&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ComposeNodePrompt&lt;/code&gt;）&lt;/strong&gt;：當 Graph Workflow 執行到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ApplyEditNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;EmailDraftNode&lt;/code&gt; 時，只會注入與該節點相關的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c6&lt;/code&gt; 技能，並在 OpenTelemetry Span 上自動打上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk.harness.skills&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk.harness.always_on_bytes&lt;/code&gt; 屬性：&lt;/li&gt;
&lt;/ol&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;// composeHarnessPrompt enriches a node&apos;s base prompt with the active Harness² c1..c8 tree&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;// and records the active harness metadata onto the node&apos;s OpenTelemetry span.&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;composeHarnessPrompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;span&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;trace&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Span&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;basePrompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;taskInput&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Harness&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;h&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;harness&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;LoadActive&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;composed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;skills&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ComposeNodePrompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;basePrompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;taskInput&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;span&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;span&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SetAttributes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;AttrHarnessRoot&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;String&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RootDir&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;AttrHarnessAlwaysOnBytes&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Int&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AlwaysOnBytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()),&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;skills&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;m&quot;&gt;0&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;span&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SetAttributes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AttrHarnessSkills&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;StringSlice&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;skills&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;composed&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;h&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;我們可以直接用 CLI 驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base&lt;/code&gt; 的常駐位元組數與結構合法性：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;go run ./cmd/harness-runner &lt;span class=&quot;nt&quot;&gt;--validate-only&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--harness-dir&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;harness/base
OK &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;1599 always-on bytes&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四小結與下一篇預告&quot;&gt;四、小結與下一篇預告&lt;/h1&gt;

&lt;p&gt;在這篇（上篇）中，我們完成了 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/16&quot;&gt;Issue #16&lt;/a&gt;&lt;/strong&gt; 的目標：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;深入理解了 Google Research &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Harness²&lt;/code&gt; (arXiv:2610.14224)&lt;/strong&gt; 如何透過 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 可編輯檔案樹&lt;/strong&gt; 與 &lt;strong&gt;雙層遞迴（Task-level &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Propose-Probe-Compose&lt;/code&gt; + Harnessing-level &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Experience Reflector&lt;/code&gt;）&lt;/strong&gt;，在不重新編譯主程式、也不塞爆常駐 Context 的前提下自動演化 Agent 能力。&lt;/li&gt;
  &lt;li&gt;盤點了修改前 Phase 1~5 將 Prompt 與正規化邏輯寫死在 Go 二進位檔中的架構瓶頸。&lt;/li&gt;
  &lt;li&gt;實作了 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/harness/harness.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/harness/harness.go&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/tree/main/harness/base&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;harness/base/&lt;/code&gt;&lt;/a&gt;，讓 ADK 2.0 Go Graph Workflow 的 13 個節點支援透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CARD_HARNESS_DIR&lt;/code&gt; 動態掛載 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 裝備樹。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;有了可熱載入的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;c1..c8&lt;/code&gt; 裝備樹後，下一篇 &lt;strong&gt;&lt;a href=&quot;/2026/10/26/adk-graph-workflow-go-8/&quot;&gt;[Agent Platform 實戰 (8)] 當 ADK Go Graph Workflow 遇上 Google Research Harness² (中)：把 Phase 4 Eval Datasets 與 Phase 5 OpenTelemetry Spans 變成 LineCardAdapter&lt;/a&gt;&lt;/strong&gt;，我們將進入 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/17&quot;&gt;Issue #17&lt;/a&gt;&lt;/strong&gt;：揭開為什麼我們要把 Phase 4 的測試集與 Phase 5 的 OpenTelemetry Spans 封裝成 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LineCardAdapter&lt;/code&gt;，以及「零洩漏屏障（Zero-Leakage Barrier）」如何防止 AI 優化器作弊！&lt;/p&gt;
</description>
				<pubDate>Sat, 24 Oct 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/adk-graph-workflow-go-7/</link>
				<guid isPermaLink="true">https://www.evanlin.com/adk-graph-workflow-go-7/</guid>
			</item>
		
			<item>
				<title>[Agent Platform 實戰 (6)] 邁向生產級 AI Agent 營運：用 agents-cli deploy、Terraform IaC、GitHub Actions CI/CD 與 Cloud Trace 打造全棧可觀測的 LINE AI 名片王</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/line-card-phase5-deploy-iac-observability-arch.png&quot; alt=&quot;Phase 5: Production Deployment, Terraform IaC, GitHub Actions CI/CD &amp;amp; Cloud Trace Observability&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前情提要從單機原型到雲端生產級-ai-agent-的五階段演進&quot;&gt;前情提要：從單機原型到雲端生產級 AI Agent 的五階段演進&lt;/h1&gt;

&lt;p&gt;歡迎來到《&lt;strong&gt;Agent Platform 實戰&lt;/strong&gt;》系列的第六篇（最終章）！回顧過去五篇文章，我們帶著 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;LINE AI 名片王 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-card-assistant&lt;/code&gt;)&lt;/a&gt;&lt;/strong&gt; 一路闖關，完成了從本地原型到企業級 AI Agent 架構的四大階段：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/16/adk-graph-workflow-go/&quot;&gt;[Agent Platform 實戰 (1)] 用 Go 與 Google ADK 2.0 Graph Workflow 打造 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;：以 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk/v2/workflow&lt;/code&gt; 實作涵蓋 Vision OCR、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanOut&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanIn&lt;/code&gt; 平行背景調查與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NewRequestInputEvent&lt;/code&gt; HITL 互動迴圈的名片工作流圖。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/17/adk-graph-workflow-go-2/&quot;&gt;[Agent Platform 實戰 (2)] 從單體 Cloud Run 邁向 Google Cloud Agent Runtime：用 agents-cli 與 ADK Go 重構 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 1（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/10&quot;&gt;PR #10&lt;/a&gt;）&lt;/strong&gt;，將專案標準化為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_go&lt;/code&gt;) 雙通道架構，同時支援 LINE Webhook、ADK WebUI Playground 與 A2A 協定。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/20/adk-graph-workflow-go-3/&quot;&gt;[Agent Platform 實戰 (3)] 破解無狀態容器的 HITL 失憶症：用 ADK 2.0 GCS Artifact Service 與 Agent Platform Sessions 實現跨實例名片辨識與暫停恢復&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 2 前半（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/11&quot;&gt;PR #11&lt;/a&gt;）&lt;/strong&gt;，導入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;artifact/gcsartifact&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;session/vertexai&lt;/code&gt; 解決無狀態容器的跨實例 HITL 恢復與圖片儲存問題。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/21/adk-graph-workflow-go-4/&quot;&gt;[Agent Platform 實戰 (4)] 邁向雲端雙層解耦與全持久化：用 Cloud Run LINE Webhook Gateway、Agent Runtime 與 Cloud SQL PostgreSQL 完成 LINE AI 名片王架構拼圖&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 2 後半（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/5&quot;&gt;Issue #5&lt;/a&gt;）&lt;/strong&gt; 與 &lt;strong&gt;Phase 3（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/6&quot;&gt;Issue #6&lt;/a&gt;，&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/12&quot;&gt;PR #12&lt;/a&gt;）&lt;/strong&gt;，將名片庫遷移至 Cloud SQL PostgreSQL (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PostgresStore&lt;/code&gt;)，並打造無狀態的 Cloud Run LINE Webhook Gateway (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/gateway&lt;/code&gt;)。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/22/adk-graph-workflow-go-5/&quot;&gt;[Agent Platform 實戰 (5)] 打造 AI Agent 的品質飛輪 (Quality Flywheel)：用 agents-cli eval 與 ADK 2.0 Go 為 LINE AI 名片王建立自動化評估基準&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 4（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/7&quot;&gt;Issue #7&lt;/a&gt;，&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13&lt;/a&gt;）&lt;/strong&gt;，用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 建立涵蓋 6 個黃金案例與 4 大評估指標全數 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0000&lt;/code&gt; 的自動化品質飛輪。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;今天這篇最終章，我們要一口氣完成 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/9&quot;&gt;Roadmap #9&lt;/a&gt;&lt;/strong&gt; 的最後一塊拼圖 —— &lt;strong&gt;Phase 5（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/8&quot;&gt;Issue #8&lt;/a&gt;）：Agent Runtime 正式部署、Terraform IaC、GitHub Actions CI/CD 與 Cloud Trace 全棧可觀測性&lt;/strong&gt;！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一phase-5-解決什麼問題從手動-gcloud-指令走向宣告式-agentops&quot;&gt;一、Phase 5 解決什麼問題？從「手動 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 指令」走向「宣告式 AgentOps」&lt;/h1&gt;

&lt;p&gt;在許多 AI 專案中，即便程式碼與評估測試都寫好了，上了生產環境（Production）卻常常因為以下四個問題而變成維運惡夢：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;基礎設施靠手動敲指令（ClickOps / Shell Script 漂移）&lt;/strong&gt;：
Vertex AI Reasoning Engine、Service Account IAM 權限、GCS Bucket、Secret Manager 密鑰與 Cloud SQL 若全靠手動下 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcloud&lt;/code&gt; 建立，Staging 與 Production 環境很容易發生設定不一致。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;PR 合併缺乏 AI 品質守門員（No Eval Gate in CI）&lt;/strong&gt;：
只跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test&lt;/code&gt; 能抓出語法與邏輯錯誤，但如果有人不小心改壞了 Graph Node 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;state_delta&lt;/code&gt; 或 Prompt，如何在 PR 合併進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main&lt;/code&gt; 之前自動攔截？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;跨環境部署與高併發驗證（Staging $\rightarrow$ Load Test $\rightarrow$ Prod Approval）&lt;/strong&gt;：
推送到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main&lt;/code&gt; 後，如何透過無金鑰的 &lt;strong&gt;Workload Identity Federation (WIF)&lt;/strong&gt; 自動部署到 Staging、跑完高併發壓測（Vegeta Load Test）並將壓測報告歸檔至 GCS，最後經過人工審核（GitHub Environment Approval Gate）才推上 Production？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Graph Workflow 節點級可觀測性（Node-Level Distributed Tracing）&lt;/strong&gt;：
當一張名片從上傳到產生 Flex Message 預覽花了 2.8 秒，到底時間是花在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt;、還是平行 Fan-Out 裡的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;（Google Search Grounding）？我們需要讓 ADK 2.0 Graph Workflow 的每一個節點都在 &lt;strong&gt;Google Cloud Trace&lt;/strong&gt; 中展開成一目了然的巢狀 Span 樹，並自動匯入 &lt;strong&gt;BigQuery&lt;/strong&gt; 進行 P95/P99 延遲與 Token 成本分析！&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;這正是文章開頭那張 &lt;strong&gt;Phase 5 全棧架構圖&lt;/strong&gt; 所描繪的四大核心支柱：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;左上（GitHub Actions CI/CD &amp;amp; Quality Gate）&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/pr_checks.yaml&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;staging.yaml&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy-to-prod.yaml&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;左下（Terraform Infrastructure as Code）&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/single-project/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cicd/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;shared/&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;中央（Vertex AI Agent Runtime + OpenTelemetry Node Spans）&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/telemetry.go&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;右側（Full-Stack Observability &amp;amp; Analytics）&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;observability.go&lt;/code&gt; $\rightarrow$ Cloud Trace + Cloud Logging $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;telemetry.tf&lt;/code&gt; BigQuery Sink&lt;/li&gt;
&lt;/ul&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二第一步用-agents-cli-scaffold-enhance-一鍵生成-terraform-iac-與-cicd-骨架&quot;&gt;二、第一步：用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli scaffold enhance&lt;/code&gt; 一鍵生成 Terraform IaC 與 CI/CD 骨架&lt;/h1&gt;

&lt;p&gt;在 Phase 1 我們曾介紹過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 的 Prototype-First 理念：先保持專案輕量，等準備上雲時再執行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli scaffold enhance&lt;/code&gt; 疊加生產環境基礎設施。&lt;/p&gt;

&lt;p&gt;我們直接在專案根目錄執行：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;uvx google-agents-cli@1.10.0 scaffold enhance &lt;span class=&quot;nb&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--cicd-runner&lt;/span&gt; github_actions &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt; asia-east1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--yes&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 自動偵測到我們的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli-manifest.yaml&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;template: adk_go&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment_target: agent_runtime&lt;/code&gt;），在不破壞任何既有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sessions/&lt;/code&gt; 程式碼的前提下，為專案補齊了三大模組：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/single-project/&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/cicd/&lt;/code&gt;&lt;/strong&gt;：完整的 Terraform 宣告式基礎設施模組。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/shared/telemetry.tf&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;storage.tf&lt;/code&gt;&lt;/strong&gt;：Cloud Logging 連結 Bucket、Dataset 與 BigQuery 遙測分析管線。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;e2e/&lt;/code&gt;&lt;/strong&gt;：GitHub Actions CI/CD 管線與 A2A / AppInfo / Vegeta Load Test 端到端測試套件。&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;接著，我們針對 &lt;strong&gt;LINE AI 名片王&lt;/strong&gt; 的專屬需求（LINE 憑證密鑰、Cloud SQL PostgreSQL 權限、台灣 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;asia-east1&lt;/code&gt; 區域）進行客製化強化！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三第二步terraform-iac-深度解析vertex-ai-reasoning-engine--secret-manager--bigquery-telemetry-sink&quot;&gt;三、第二步：Terraform IaC 深度解析（Vertex AI Reasoning Engine + Secret Manager + BigQuery Telemetry Sink）&lt;/h1&gt;

&lt;p&gt;讓我們打開 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/&lt;/code&gt;，看看 Terraform 是如何把整座 Google Cloud Agent Platform 宣告式地建立起來的：&lt;/p&gt;

&lt;h3 id=&quot;1-宣告式定義-vertex-ai-reasoning-engine-servicetf&quot;&gt;1. 宣告式定義 Vertex AI Reasoning Engine (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;service.tf&lt;/code&gt;)&lt;/h3&gt;

&lt;p&gt;在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/deployment/terraform/single-project/service.tf&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/single-project/service.tf&lt;/code&gt;&lt;/a&gt; 中，我們使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google-beta&lt;/code&gt; Provider 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google_vertex_ai_reasoning_engine&lt;/code&gt; 資源，將 Go 專案原始碼打包並宣告為受託管的 Agent Runtime 實例，同時設定 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;lifecycle { ignore_changes = [spec[0].source_code_spec] }&lt;/code&gt;，讓日常的程式碼更新交由 CI/CD 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy&lt;/code&gt; 快速滾動部署，而基礎設施設定（IAM、Bucket、環境變數）由 Terraform 統一控管：&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;google_vertex_ai_reasoning_engine&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;app&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;provider&lt;/span&gt;     &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;google&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;beta&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;display_name&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;project_name&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;project&lt;/span&gt;      &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;project_id&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;region&lt;/span&gt;       &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;region&lt;/span&gt;

  &lt;span class=&quot;nx&quot;&gt;labels&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;s2&quot;&gt;&quot;agent-framework&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;agent_framework&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

  &lt;span class=&quot;nx&quot;&gt;spec&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;identity_type&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;AGENT_IDENTITY&quot;&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;agent_framework&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;agent_framework&lt;/span&gt;

    &lt;span class=&quot;nx&quot;&gt;source_code_spec&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
      &lt;span class=&quot;nx&quot;&gt;inline_source&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;nx&quot;&gt;source_archive&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;archive_file&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;source&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;output_path&lt;/span&gt;
      &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
      &lt;span class=&quot;nx&quot;&gt;developer_connect_source&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

    &lt;span class=&quot;nx&quot;&gt;container_spec&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
      &lt;span class=&quot;nx&quot;&gt;image_uri&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-15:latest&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

  &lt;span class=&quot;nx&quot;&gt;lifecycle&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;ignore_changes&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
      &lt;span class=&quot;nx&quot;&gt;spec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;source_code_spec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;nx&quot;&gt;spec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;container_spec&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;2-最小權限-iam-與-secret-manager-密鑰整合-iamtf--variablestf&quot;&gt;2. 最小權限 IAM 與 Secret Manager 密鑰整合 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;iam.tf&lt;/code&gt; &amp;amp; &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;variables.tf&lt;/code&gt;)&lt;/h3&gt;

&lt;p&gt;為了不讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CHANNEL_SECRET&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CHANNEL_ACCESS_TOKEN&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DATABASE_URL&lt;/code&gt; 以明文出現在設定檔中，我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/deployment/terraform/single-project/iam.tf&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/single-project/iam.tf&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/deployment/terraform/single-project/variables.tf&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;variables.tf&lt;/code&gt;&lt;/a&gt; 中宣告了 &lt;strong&gt;Google Cloud Secret Manager&lt;/strong&gt; 密鑰，並將 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/secretmanager.secretAccessor&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roles/cloudsql.client&lt;/code&gt; 同時授予 &lt;strong&gt;Vertex AI Service Agent (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gcp-sa-aiplatform-re&lt;/code&gt;)&lt;/strong&gt; 與 &lt;strong&gt;Agent Identity Principal (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;principal://${google_vertex_ai_reasoning_engine.app.spec[0].effective_identity}&lt;/code&gt;)&lt;/strong&gt;：&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Secret Manager secrets for LINE Messaging API credentials and Cloud SQL DSN&lt;/span&gt;
&lt;span class=&quot;nx&quot;&gt;locals&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;line_card_secrets&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
    &lt;span class=&quot;s2&quot;&gt;&quot;line-channel-secret&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;s2&quot;&gt;&quot;line-channel-access-token&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;s2&quot;&gt;&quot;line-card-database-url&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;google_secret_manager_secret&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;app_secrets&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;for_each&lt;/span&gt;  &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;toset&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;local&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;line_card_secrets&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;project&lt;/span&gt;   &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;project_id&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;secret_id&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;each&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;value&lt;/span&gt;

  &lt;span class=&quot;nx&quot;&gt;replication&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;auto&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

  &lt;span class=&quot;nx&quot;&gt;depends_on&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;google_project_service&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;services&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;如此一來，部署時只需要在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy&lt;/code&gt; 傳入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--secrets=&quot;LINE_CHANNEL_SECRET=line-channel-secret,LINE_CHANNEL_ACCESS_TOKEN=line-channel-access-token&quot;&lt;/code&gt;，Agent Runtime 就會在啟動容器時安全地從 Secret Manager 掛載密鑰！&lt;/p&gt;

&lt;h3 id=&quot;3-自動建立-cloud-logging-rightarrow-bigquery-遙測分析資料集-telemetrytf&quot;&gt;3. 自動建立 Cloud Logging $\rightarrow$ BigQuery 遙測分析資料集 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;telemetry.tf&lt;/code&gt;)&lt;/h3&gt;

&lt;p&gt;在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/deployment/terraform/shared/telemetry.tf&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/shared/telemetry.tf&lt;/code&gt;&lt;/a&gt; 中，Terraform 會自動建立一個 365 天保留期的 Cloud Logging Bucket、開啟 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;enable_analytics = true&lt;/code&gt;，並透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google_logging_linked_dataset&lt;/code&gt; 直接將遙測日誌映射為 &lt;strong&gt;BigQuery Dataset (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;telemetry_logs_dataset&lt;/code&gt;)&lt;/strong&gt;：&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;google_logging_project_bucket_config&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;telemetry_logs_bucket&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;project&lt;/span&gt;          &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;each&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;value&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;location&lt;/span&gt;         &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;global&quot;&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;bucket_id&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;${var.project_name}-telemetry&quot;&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;retention_days&lt;/span&gt;   &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;365&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;enable_analytics&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;google_logging_linked_dataset&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;telemetry_logs_dataset&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;bucket&lt;/span&gt;     &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;google_logging_project_bucket_config&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;telemetry_logs_bucket&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;each&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;bucket_id&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;link_id&lt;/span&gt;    &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;replace&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;${var.project_name}_telemetry&quot;&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;-&quot;&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;_&quot;&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;project&lt;/span&gt;    &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;each&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;value&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;location&lt;/span&gt;   &lt;span class=&quot;p&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;global&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這意味著所有由 OpenTelemetry 輸出的結構化遙測資料，都不需要額外寫 ETL 腳本，就能直接在 BigQuery 用標準 SQL 分析！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四第三步為-adk-20-go-graph-workflow-的-14-個節點注入-opentelemetry-分散式追蹤-internalworkflowtelemetrygo&quot;&gt;四、第三步：為 ADK 2.0 Go Graph Workflow 的 14 個節點注入 OpenTelemetry 分散式追蹤 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/telemetry.go&lt;/code&gt;)&lt;/h1&gt;

&lt;p&gt;在 Phase 1 產生的 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/observability.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;observability.go&lt;/code&gt;&lt;/a&gt; 中，系統已經設定好指向 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;telemetry.googleapis.com&lt;/code&gt; 的 OTLP HTTP Exporter 與 Google ADC 自動驗證。然而，預設情況下我們只能看到整個 HTTP 請求或 LLM 呼叫的頂層追蹤，卻看不見 &lt;strong&gt;ADK 2.0 Graph Workflow 內部各個 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FunctionNode&lt;/code&gt; 的執行時間與路由決策&lt;/strong&gt;。&lt;/p&gt;

&lt;p&gt;為了讓每一張名片的處理過程在 &lt;strong&gt;Google Cloud Trace&lt;/strong&gt; 上呈現完整的瀑布圖（Waterfall Span Tree），我們新增了 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/telemetry.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/telemetry.go&lt;/code&gt;&lt;/a&gt;：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;package&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;workflow&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;context&quot;&lt;/span&gt;

	&lt;span class=&quot;s&quot;&gt;&quot;go.opentelemetry.io/otel&quot;&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;go.opentelemetry.io/otel/attribute&quot;&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;go.opentelemetry.io/otel/codes&quot;&lt;/span&gt;
	&lt;span class=&quot;s&quot;&gt;&quot;go.opentelemetry.io/otel/trace&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;workflowTracerName&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;github.com/kkdai/line-card-assistant/internal/workflow&quot;&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrWorkflowNode&lt;/span&gt;   &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.workflow.node&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrWorkflowRoute&lt;/span&gt;  &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.workflow.route&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrInvocationID&lt;/span&gt;   &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.invocation.id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrSessionID&lt;/span&gt;      &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.session.id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrUserID&lt;/span&gt;         &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.user.id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrCardID&lt;/span&gt;         &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.card.id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrCardCompany&lt;/span&gt;    &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.card.company&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrCardDuplicate&lt;/span&gt;  &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.card.is_duplicate&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrHITLInterrupt&lt;/span&gt;  &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.hitl.interrupt_id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrHITLAction&lt;/span&gt;     &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.hitl.action&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrSearchMatches&lt;/span&gt;  &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.search.matches&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;AttrSearchKeywords&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;adk.search.keywords&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;startNodeSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attrs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;KeyValue&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;trace&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Span&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;baseAttrs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;make&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;([]&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;attribute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;KeyValue&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;m&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;attrs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;m&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;baseAttrs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;baseAttrs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AttrWorkflowNode&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;String&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;baseAttrs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;baseAttrs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attrs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;otel&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Tracer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;workflowTracerName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Start&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
		&lt;span class=&quot;s&quot;&gt;&quot;workflow.node.&quot;&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;trace&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;WithAttributes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;baseAttrs&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;接著，我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/nodes_ingest.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_ingest.go&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/nodes_search.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_search.go&lt;/code&gt;&lt;/a&gt; 的所有節點中注入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;startNodeSpan&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;endNodeSpan&lt;/code&gt;。例如在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt; 中：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;newHybridSearchNode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cardStore&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;store&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;CardStore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;workflow&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;FunctionNode&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;workflow&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NewFunctionNode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;NodeHybridSearch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;any&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;spanCtx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;span&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;startNodeSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;NodeHybridSearch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AttrInvocationID&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;String&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ctx&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;InvocationID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()))&lt;/span&gt;
			&lt;span class=&quot;k&quot;&gt;defer&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
				&lt;span class=&quot;n&quot;&gt;routeAttr&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;&quot;&lt;/span&gt;
				&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Routes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;gt;&lt;/span&gt; &lt;span class=&quot;m&quot;&gt;0&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
					&lt;span class=&quot;n&quot;&gt;routeAttr&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Routes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;m&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
				&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
				&lt;span class=&quot;n&quot;&gt;endNodeSpan&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;span&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AttrWorkflowRoute&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;String&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;routeAttr&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
			&lt;span class=&quot;p&quot;&gt;}()&lt;/span&gt;
			&lt;span class=&quot;c&quot;&gt;// ... 執行 cardStore.HybridSearch(spanCtx, filter) ...&lt;/span&gt;
			&lt;span class=&quot;n&quot;&gt;span&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SetAttributes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AttrSearchMatches&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Int&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cards&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)))&lt;/span&gt;
			&lt;span class=&quot;c&quot;&gt;// ...&lt;/span&gt;
		&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
		&lt;span class=&quot;n&quot;&gt;workflow&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NodeConfig&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{},&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;當使用者上傳一張名片或執行混合搜尋時，Cloud Trace 會自動繪製出如下的階層式 Span 樹，包含平行 Fan-Out 的三個子節點耗時與每個節點的業務屬性：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TD
    Root[&quot;invoke_workflow (line_card_assistant)&amp;lt;br/&amp;gt;trace_id: 4bf92f3577b34da6a3ce929d0e0e4736&quot;] --&amp;gt; R[&quot;workflow.node.RouterNode&amp;lt;br/&amp;gt;adk.workflow.route = &apos;ingest&apos; (1.2ms)&quot;]
    R --&amp;gt; V[&quot;workflow.node.VisionOCRNode&amp;lt;br/&amp;gt;adk.card.company = &apos;Taiwan AI Labs&apos; (640ms)&quot;]
    V --&amp;gt; C1[&quot;workflow.node.CleanAndDedupNode&amp;lt;br/&amp;gt;adk.card.is_duplicate = false (8.5ms)&quot;]
    V --&amp;gt; C2[&quot;workflow.node.CompanyEnrichNode&amp;lt;br/&amp;gt;GoogleSearch Grounding (780ms)&quot;]
    V --&amp;gt; C3[&quot;workflow.node.ContextMatchNode&amp;lt;br/&amp;gt;inferMetContext (310ms)&quot;]
    C1 &amp;amp; C2 &amp;amp; C3 --&amp;gt; B[&quot;workflow.node.BuildPreviewNode&amp;lt;br/&amp;gt;Flex Bubble JSON (2.1ms)&quot;]
    B --&amp;gt; H[&quot;workflow.node.HITLConfirmNode&amp;lt;br/&amp;gt;adk.hitl.interrupt_id = &apos;hitl_confirm_1&apos;&amp;lt;br/&amp;gt;adk.hitl.action = &apos;pause&apos; (0.8ms)&quot;]
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;我們同時在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/telemetry_test.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/telemetry_test.go&lt;/code&gt;&lt;/a&gt; 中使用 OpenTelemetry SDK 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tracetest.NewInMemoryExporter()&lt;/code&gt; 撰寫了自動化單元測試，確保「名片辨識 + HITL 修改迴圈 + 確認存檔」以及「混合搜尋 0 筆自動降級至模糊搜尋」都會 100% 產生預期的 Span 節點與屬性標籤！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五第四步打造結合-agents-cli-eval-品質守門員的-github-actions-cicd-管線-githubworkflows&quot;&gt;五、第四步：打造結合 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 品質守門員的 GitHub Actions CI/CD 管線 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/&lt;/code&gt;)&lt;/h1&gt;

&lt;p&gt;有了 Terraform IaC 與 OpenTelemetry 追蹤後，我們把 Phase 4 打造的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 品質飛輪&lt;/strong&gt; 正式嵌進 GitHub Actions CI/CD 管線中，形成兩階段自動化交付：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    subgraph PR[&quot;1. Pull Request Quality Gate (pr_checks.yaml)&quot;]
        P1[&quot;go test -race -v ./...&amp;lt;br/&amp;gt;(Unit + OTel Span + Trajectory Tests)&quot;] --&amp;gt; P2[&quot;go test -tags=e2e&amp;lt;br/&amp;gt;(A2A + /app-info E2E Tests)&quot;]
        P2 --&amp;gt; P3[&quot;agents-cli eval run&amp;lt;br/&amp;gt;(4 大指標必須 = 1.0000)&quot;]
    end

    subgraph CD[&quot;2. Staging &amp;amp; Production CD (staging.yaml -&amp;gt; deploy-to-prod.yaml)&quot;]
        S1[&quot;WIF 無金鑰驗證&amp;lt;br/&amp;gt;(google-github-actions/auth)&quot;] --&amp;gt; S2[&quot;agents-cli deploy&amp;lt;br/&amp;gt;部署至 Staging Agent Runtime&quot;]
        S2 --&amp;gt; S3[&quot;Vegeta Load Test&amp;lt;br/&amp;gt;30s 壓測 + 報告上傳 GCS&quot;]
        S3 --&amp;gt; S4[&quot;GitHub Environment&amp;lt;br/&amp;gt;Production 人工審核 Gate&quot;]
        S4 --&amp;gt; S5[&quot;agents-cli deploy&amp;lt;br/&amp;gt;部署至 Production Agent Runtime&quot;]
    end

    PR --&amp;gt;|Merge to main| CD
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&quot;1-pr-品質守門員-githubworkflowspr_checksyaml&quot;&gt;1. PR 品質守門員 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/pr_checks.yaml&lt;/code&gt;)&lt;/h3&gt;

&lt;p&gt;在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/.github/workflows/pr_checks.yaml&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/pr_checks.yaml&lt;/code&gt;&lt;/a&gt; 中，只要 PR 修改了 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app/**&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/**&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cmd/**&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sessions/**&lt;/code&gt; 或 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/**&lt;/code&gt;，GitHub Actions 就會依序執行：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test -race -v ./...&lt;/code&gt;：驗證所有 Go 單元測試、跨實例 HITL 恢復、OpenTelemetry Node Spans 與軌跡測試。&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test -v -tags=e2e ./e2e/integration/...&lt;/code&gt;：啟動真實的 ADK Universal Launcher 子程序，驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/.well-known/agent-card.json&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/a2a/invoke&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/apps/app/app-info&lt;/code&gt; 端點。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval run&lt;/code&gt; 品質守門員&lt;/strong&gt;：執行 6 個黃金評估案例，驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow_trajectory_accuracy&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ocr_and_enrichment_quality&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;duplicate_and_hitl_precision&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;search_and_email_grounding&lt;/code&gt; 四大指標必須維持滿分通過！&lt;/li&gt;
&lt;/ol&gt;

&lt;h3 id=&quot;2-staging-自動部署與-vegeta-負載壓測-githubworkflowsstagingyaml&quot;&gt;2. Staging 自動部署與 Vegeta 負載壓測 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/staging.yaml&lt;/code&gt;)&lt;/h3&gt;

&lt;p&gt;當 PR 合併進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main&lt;/code&gt; 分支後，&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/.github/workflows/staging.yaml&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/staging.yaml&lt;/code&gt;&lt;/a&gt; 會：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;透過 &lt;strong&gt;Workload Identity Federation (WIF)&lt;/strong&gt; 無金鑰取得 GCP 短期憑證。&lt;/li&gt;
  &lt;li&gt;呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;uvx google-agents-cli@1.10.0 deploy&lt;/code&gt; 將最新 Commit 部署至 Staging 的 Vertex AI Agent Runtime，同時掛載 Secret Manager 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CHANNEL_SECRET&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LINE_CHANNEL_ACCESS_TOKEN&lt;/code&gt;，並標記 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OTEL_RESOURCE_ATTRIBUTES=service.version=$&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;啟動 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/e2e/load_test/load_test.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;e2e/load_test/load_test.go&lt;/code&gt;&lt;/a&gt;（基於 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tsenart/vegeta/v12&lt;/code&gt;），對 Staging Agent Runtime 進行 30 秒持續壓測，檢查 HTTP 200 成功率、P50/P95/P99 延遲與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;429 Too Many Requests&lt;/code&gt; 比例，並將壓測結果自動歸檔至 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gs://${LOGS_BUCKET_NAME_STAGING}/load-test-results/&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;壓測通過後，自動觸發 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/.github/workflows/deploy-to-prod.yaml&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.github/workflows/deploy-to-prod.yaml&lt;/code&gt;&lt;/a&gt;，在通過 GitHub &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;production&lt;/code&gt; Environment 的 Required Reviewers 審核後，正式推送至 Production！&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;六實戰驗證agents-cli-deploy---dry-run-與全套-e2e-測試全數通過&quot;&gt;六、實戰驗證：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy --dry-run&lt;/code&gt; 與全套 E2E 測試全數通過！&lt;/h1&gt;

&lt;p&gt;在將程式碼提交 PR 之前，我們在本地端完整執行了三大驗證：&lt;/p&gt;

&lt;h3 id=&quot;1-agents-cli-deploy---dry-run-雲端部署預檢&quot;&gt;1. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy --dry-run&lt;/code&gt; 雲端部署預檢&lt;/h3&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;uvx google-agents-cli@1.10.0 deploy &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--project&lt;/span&gt; line-vertex &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt; asia-east1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--dry-run&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--no-confirm-project&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;預檢輸出結果：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aiplatform.googleapis.com&lt;/code&gt; API&lt;/strong&gt;：Enabled ✅&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Target Agent Runtime Engine&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line-card-assistant&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;asia-east1&lt;/code&gt;) ✅&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;IAM Roles &amp;amp; Service Account Preflight&lt;/strong&gt;：Passed ✅&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;2-go-單元測試--opentelemetry-span-測試--e2e-整合測試&quot;&gt;2. Go 單元測試 + OpenTelemetry Span 測試 + E2E 整合測試&lt;/h3&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;go &lt;span class=&quot;nb&quot;&gt;test&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-v&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-tags&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;e2e ./...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;包含新增的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestWorkflowOpenTelemetrySpans_IngestAndHITL&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestWorkflowOpenTelemetrySpans_SearchFallback&lt;/code&gt; 以及 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;e2e/integration&lt;/code&gt; 下的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestA2AAgentCard&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestA2AMessageSend&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestA2AErrorHandling&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestAppInfo&lt;/code&gt; 全數 &lt;strong&gt;PASS&lt;/strong&gt;！&lt;/p&gt;

&lt;h3 id=&quot;3-phase-4-agents-cli-eval-品質飛輪回歸驗證&quot;&gt;3. Phase 4 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 品質飛輪回歸驗證&lt;/h3&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ DRY_RUN&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;true &lt;/span&gt;make &lt;span class=&quot;nb&quot;&gt;eval&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;6 個黃金案例在 4 大自訂指標（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow_trajectory_accuracy&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ocr_and_enrichment_quality&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;duplicate_and_hitl_precision&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;search_and_email_grounding&lt;/code&gt;）依然維持 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0000&lt;/code&gt; (100% Pass)&lt;/strong&gt;！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;七agent-platform-實戰全系列總結五階段完整演進地圖&quot;&gt;七、《Agent Platform 實戰》全系列總結：五階段完整演進地圖&lt;/h1&gt;

&lt;p&gt;隨著 &lt;strong&gt;Phase 5（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/8&quot;&gt;Issue #8&lt;/a&gt;）&lt;/strong&gt; 的完成，我們在 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/9&quot;&gt;Roadmap Issue #9&lt;/a&gt;&lt;/strong&gt; 規劃的五個階段已經 &lt;strong&gt;100% 全數達成並關閉&lt;/strong&gt;！讓我們最後用一張總表回顧這趟從 0 到 1 的 &lt;strong&gt;Google ADK 2.0 Go + Google Cloud Agent Platform&lt;/strong&gt; 實戰旅程：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;階段&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;對應 Issue / PR&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;核心技術突破&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;對應部落格文章&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;原型篇&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Initial Commit&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk/v2/workflow&lt;/code&gt; 12 節點 Graph Workflow、平行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanOut&lt;/code&gt;/&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanIn&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NewRequestInputEvent&lt;/code&gt; HITL 迴圈&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;/2026/10/16/adk-graph-workflow-go/&quot;&gt;實戰 (1)&lt;/a&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Phase 1&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/4&quot;&gt;Issue #4&lt;/a&gt; / &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/10&quot;&gt;PR #10&lt;/a&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_go&lt;/code&gt;) 標準化、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;app.NewRootAgent&lt;/code&gt; 雙通道工廠、ADK WebUI Playground 與 A2A 協定支援&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;/2026/10/17/adk-graph-workflow-go-2/&quot;&gt;實戰 (2)&lt;/a&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Phase 2 (上)&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/5&quot;&gt;Issue #5&lt;/a&gt; / &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/11&quot;&gt;PR #11&lt;/a&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;artifact/gcsartifact&lt;/code&gt; 圖片零狀態膨脹、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;session/vertexai&lt;/code&gt; 跨實例無狀態 HITL 暫停與恢復&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;/2026/10/20/adk-graph-workflow-go-3/&quot;&gt;實戰 (3)&lt;/a&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Phase 2 (下) &amp;amp; Phase 3&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/5&quot;&gt;Issue #5&lt;/a&gt;, &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/6&quot;&gt;#6&lt;/a&gt; / &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/12&quot;&gt;PR #12&lt;/a&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;Cloud SQL PostgreSQL (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PostgresStore&lt;/code&gt;) 名片持久化、Cloud Run LINE Webhook Gateway (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/gateway&lt;/code&gt;) 與 Agent Runtime 雙層解耦&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;/2026/10/21/adk-graph-workflow-go-4/&quot;&gt;實戰 (4)&lt;/a&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Phase 4&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/7&quot;&gt;Issue #7&lt;/a&gt; / &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13&lt;/a&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 品質飛輪、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/app-info&lt;/code&gt; 反射內省、6 大黃金案例與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace&lt;/code&gt; 軌跡修復（4 指標全數 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0000&lt;/code&gt;）&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;/2026/10/22/adk-graph-workflow-go-5/&quot;&gt;實戰 (5)&lt;/a&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;Phase 5&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/8&quot;&gt;Issue #8&lt;/a&gt; / &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/14&quot;&gt;PR #14&lt;/a&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy&lt;/code&gt;、Terraform IaC (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deployment/terraform/&lt;/code&gt;)、GitHub Actions CI/CD + WIF + Vegeta 壓測、OpenTelemetry 節點級 Cloud Trace &amp;amp; BigQuery 觀測&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;本篇（實戰 6）&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;完整的開源程式碼、Terraform 模組與評估資料集都已經同步在 GitHub Repo：&lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kkdai/line-card-assistant&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt;。如果你也正在用 Go 語言與 Google ADK 2.0 打造企業級 AI Agent，希望這個系列能成為你從本地開發一路推進到 Google Cloud Agent Platform 生產環境的最佳實戰藍圖！&lt;/p&gt;
</description>
				<pubDate>Fri, 23 Oct 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/adk-graph-workflow-go-6/</link>
				<guid isPermaLink="true">https://www.evanlin.com/adk-graph-workflow-go-6/</guid>
			</item>
		
			<item>
				<title>[Agent Platform 實戰 (5)] 打造 AI Agent 的品質飛輪 (Quality Flywheel)：用 agents-cli eval 與 ADK 2.0 Go 為 LINE AI 名片王建立自動化評估基準</title>
				<description>&lt;p&gt;&lt;img src=&quot;../images/line-card-phase4-eval-flywheel-arch.png&quot; alt=&quot;Phase 4: ADK 2.0 Go Agent Evaluation &amp;amp; Quality Flywheel (`agents-cli eval`)&quot; /&gt;&lt;/p&gt;

&lt;h1 id=&quot;前情提要&quot;&gt;前情提要&lt;/h1&gt;

&lt;p&gt;在《Agent Platform 實戰》系列的前四篇文章中，我們一步步將 &lt;strong&gt;LINE AI 名片王 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line-card-assistant&lt;/code&gt;)&lt;/strong&gt; 從單機原型推進為雲端原生、雙層解耦的 &lt;strong&gt;Google Cloud Agent Platform&lt;/strong&gt; 架構：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/16/adk-graph-workflow-go/&quot;&gt;[Agent Platform 實戰 (1)] 用 Go 與 Google ADK 2.0 Graph Workflow 打造 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;：使用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;google.golang.org/adk/v2/workflow&lt;/code&gt; 打造 12 個節點的名片處理圖（Graph Workflow），涵蓋 Vision OCR、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanOut&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AddFanIn&lt;/code&gt; 平行背景調查，以及 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NewRequestInputEvent&lt;/code&gt; 的 HITL（Human-in-the-Loop）暫停與修改迴圈。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/17/adk-graph-workflow-go-2/&quot;&gt;[Agent Platform 實戰 (2)] 從單體 Cloud Run 邁向 Google Cloud Agent Runtime：用 agents-cli 與 ADK Go 重構 LINE AI 名片王&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 1（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/10&quot;&gt;PR #10&lt;/a&gt;）&lt;/strong&gt;，導入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_go&lt;/code&gt;) 標準雙通道架構，同時支援 LINE Webhook、ADK WebUI Playground 與 A2A 協定。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/20/adk-graph-workflow-go-3/&quot;&gt;[Agent Platform 實戰 (3)] 破解無狀態容器的 HITL 失憶症：用 ADK 2.0 GCS Artifact Service 與 Agent Platform Sessions 實現跨實例名片辨識與暫停恢復&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 2 前半（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/11&quot;&gt;PR #11&lt;/a&gt;）&lt;/strong&gt;，用 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;artifact/gcsartifact&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;session/vertexai&lt;/code&gt; 讓無狀態容器支援跨實例 HITL 暫停與恢復。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/2026/10/21/adk-graph-workflow-go-4/&quot;&gt;[Agent Platform 實戰 (4)] 邁向雲端雙層解耦與全持久化：用 Cloud Run LINE Webhook Gateway、Agent Runtime 與 Cloud SQL PostgreSQL 完成 LINE AI 名片王架構拼圖&lt;/a&gt;&lt;/strong&gt;：完成 &lt;strong&gt;Phase 2 後半（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/5&quot;&gt;Issue #5&lt;/a&gt;）&lt;/strong&gt; 與 &lt;strong&gt;Phase 3（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/6&quot;&gt;Issue #6&lt;/a&gt;，&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/12&quot;&gt;PR #12&lt;/a&gt;）&lt;/strong&gt;，將名片庫遷移至 Cloud SQL PostgreSQL (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PostgresStore&lt;/code&gt;)，並實作無狀態的 Cloud Run LINE Webhook Gateway (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gateway.Client&lt;/code&gt;)。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;當架構與功能都到位、準備正式將 Agent 部署上雲端生產環境（Phase 5）之前，所有 AI 工程團隊都會面臨一個最核心的靈魂拷問：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;strong&gt;「當我們修改了一行 Prompt、調整了一個 Graph Node 的路由條件，或是把底層模型從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-2.5-flash&lt;/code&gt; 升級到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;gemini-3.8-flash&lt;/code&gt; 時，怎麼確保名片 OCR 欄位不會漏抓、重複名片升遷偵測不會失效、HITL 修改迴圈不會卡死、混合搜尋不會退化？」&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;今天這篇系列文的第五集，我們就要來實戰 &lt;strong&gt;Phase 4（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/7&quot;&gt;Issue #7&lt;/a&gt;，對應 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13&lt;/a&gt;）&lt;/strong&gt;：用 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt;&lt;/strong&gt; 與 &lt;strong&gt;ADK 2.0 Go 軌跡測試&lt;/strong&gt;，為 LINE AI 名片王打造一套可量化、可比較、可在 CI/CD 自動執行的 &lt;strong&gt;AI Agent 品質飛輪（Quality Flywheel）&lt;/strong&gt;！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;一為什麼傳統-unit-test-不夠用認識-agents-cli-eval-的品質飛輪-quality-flywheel&quot;&gt;一、為什麼傳統 Unit Test 不夠用？認識 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 的「品質飛輪 (Quality Flywheel)」&lt;/h1&gt;

&lt;p&gt;在傳統軟體工程中，我們習慣寫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;if got != want&lt;/code&gt; 的確定性單元測試（Unit Tests）。但在以 &lt;strong&gt;ADK 2.0 Graph Workflow + 多模態 LLM&lt;/strong&gt; 驅動的 AI Agent 系統裡，我們要驗證的遠不只是單一函式的回傳值，而是整條 &lt;strong&gt;「執行軌跡（Execution Trajectory）與狀態演進（State Delta）」&lt;/strong&gt;：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;多分支與平行匯聚（Fan-Out / Fan-In Trajectory）&lt;/strong&gt;：收到名片圖片時，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt; 是否正確走進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt;？接著有沒有同時觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextMatchNode&lt;/code&gt; 三個平行分支，並在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;JoinPreviewNode&lt;/code&gt; 匯聚？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;中間狀態變更（Session &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;state_delta&lt;/code&gt;）&lt;/strong&gt;：即便最終回傳給使用者的是一包 LINE Flex Message JSON，中間節點是否確實正規化了台灣手機號碼（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+886-912-345-678&lt;/code&gt;）、是否偵測到了既有聯絡人升遷（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;IsDuplicate=true&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VP of Engineering&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Chief Technology Officer (CTO)&lt;/code&gt;）？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Human-in-the-Loop (HITL) 暫停與多輪對話迴圈&lt;/strong&gt;：當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; 發出 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_request_input&lt;/code&gt; 暫停事件後，使用者回覆「職稱改為技術副總，場合改為 COMPUTEX 2026 AI 論壇」並確認存檔，工作流是否真的走過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ApplyEditNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BuildPreviewNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SaveCardNode&lt;/code&gt;？&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;檢索降級與內容錨定（Grounding）&lt;/strong&gt;：當嚴格的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt; 查無結果（0 筆）時，是否自動降級觸發 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BroadSearchNode&lt;/code&gt;？產出的破冰跟進信草稿，是否真正引用了名片上的相遇場合與公司背景，而沒有發生幻覺（Hallucination）？&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;為了系統化解決這個問題，Google Cloud &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 提出了 &lt;strong&gt;Quality Flywheel（品質飛輪）&lt;/strong&gt; 的五步循環工作流：&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
    A[&quot;1. Generate&amp;lt;br/&amp;gt;(agents-cli eval generate)&amp;lt;br/&amp;gt;啟動 ADK 伺服器並收集真實軌跡&quot;] --&amp;gt; B[&quot;2. Grade&amp;lt;br/&amp;gt;(agents-cli eval grade)&amp;lt;br/&amp;gt;執行 Trajectory 與品質指標評分&quot;]
    B --&amp;gt; C[&quot;3. Analyze&amp;lt;br/&amp;gt;檢視各指標分數與&amp;lt;br/&amp;gt;失敗案例 Explanation&quot;]
    C --&amp;gt; D[&quot;4. Fix&amp;lt;br/&amp;gt;修正 Graph Node、Prompt&amp;lt;br/&amp;gt;或事件追蹤結構&quot;]
    D --&amp;gt; E[&quot;5. Compare&amp;lt;br/&amp;gt;(agents-cli eval compare)&amp;lt;br/&amp;gt;Baseline vs. Candidate 量化對比&quot;]
    E --&amp;gt;|持續迭代| A
&lt;/code&gt;&lt;/pre&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;二揭秘-agents-cli-eval-generate-如何測試一個-go-語言的-adk-20-agent&quot;&gt;二、揭秘 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval generate&lt;/code&gt; 如何測試一個 Go 語言的 ADK 2.0 Agent？&lt;/h1&gt;

&lt;p&gt;很多剛接觸 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 的 Go 開發者會好奇：&lt;strong&gt;「&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 底層是用 Python 寫的 CLI 工具，它要怎麼去評估我用 Go 寫的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk/v2/workflow&lt;/code&gt; Agent？」&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;答案就藏在我們在 Phase 1 導入的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main.go&lt;/code&gt;&lt;/strong&gt; 與 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;appinfo/appinfo.go&lt;/code&gt;&lt;/strong&gt; 之中！當你執行：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;DRY_RUN&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;true &lt;/span&gt;agents-cli &lt;span class=&quot;nb&quot;&gt;eval &lt;/span&gt;generate &lt;span class=&quot;nt&quot;&gt;--dataset&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;eval&lt;/span&gt;/datasets/basic-dataset.json
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 會在背景自動完成以下四個步驟：&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;自動編譯並啟動你的 Go Agent 伺服器&lt;/strong&gt;：
&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 讀取專案根目錄的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli-manifest.yaml&lt;/code&gt;（識別為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;template: adk_go&lt;/code&gt;），在背景自動啟動：
    &lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;go run &lt;span class=&quot;nb&quot;&gt;.&lt;/span&gt; web &lt;span class=&quot;nt&quot;&gt;--port&lt;/span&gt; &amp;lt;random_port&amp;gt; api &lt;span class=&quot;nt&quot;&gt;-path_prefix&lt;/span&gt; / a2a appinfo
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /apps/app/app-info&lt;/code&gt; 反射內省 Agent 結構&lt;/strong&gt;：
&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/appinfo/appinfo.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;appinfo/appinfo.go&lt;/code&gt;&lt;/a&gt; 利用 Go 的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;reflect&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;unsafe&lt;/code&gt; 走訪整棵 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflowagent&lt;/code&gt; 的 Edges 與 Nodes，把圖裡面鑲嵌的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichAgent&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;llmagent&lt;/code&gt;）、Instruction 與工具宣告組裝成標準的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AppInfo&lt;/code&gt; JSON 回傳給 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;逐一建立 Session 並呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /run_sse&lt;/code&gt; 收集事件串流&lt;/strong&gt;：
針對 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/basic-dataset.json&lt;/code&gt; 裡的每一個測試案例（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval_case_id&lt;/code&gt;），&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 會先呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /apps/app/users/eval_user/sessions&lt;/code&gt; 建立獨立 Session，再將測試案例的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prompt&lt;/code&gt; 送往 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST /run_sse&lt;/code&gt;，並將伺服器串流回傳的每一個 ADK Event（包含 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;author&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;content&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;actions.state_delta&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;actions.requested_tool_confirmations&lt;/code&gt; 等）完整錄製下來。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;輸出標準化軌跡檔 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;artifacts/traces/traces_&amp;lt;timestamp&amp;gt;.json&lt;/code&gt;&lt;/strong&gt;：
測試完成後自動關閉 Go 伺服器，將完整軌跡存成 JSON，交給下一階段的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval grade&lt;/code&gt; 進行評分。&lt;/li&gt;
&lt;/ol&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;三實戰設計涵蓋-4-大核心場景的黃金評估集-evaldatasetsbasic-datasetjson&quot;&gt;三、實戰設計：涵蓋 4 大核心場景的黃金評估集 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/basic-dataset.json&lt;/code&gt;)&lt;/h1&gt;

&lt;p&gt;為了完整覆蓋 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/7&quot;&gt;Issue #7&lt;/a&gt; 定義的四大驗收場景，我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/datasets/basic-dataset.json&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/basic-dataset.json&lt;/code&gt;&lt;/a&gt; 中設計了 &lt;strong&gt;6 個黃金測試案例（Golden Eval Cases）&lt;/strong&gt;，並在每個案例的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;custom_Properties&lt;/code&gt; 中標註預期的節點軌跡（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expected_nodes&lt;/code&gt;）與狀態斷言：&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;Eval Case ID&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;對應核心場景&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;輸入 Prompt (模擬通道訊號)&lt;/th&gt;
      &lt;th style=&quot;text-align: left&quot;&gt;驗證重點 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;custom_Properties&lt;/code&gt;)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;case_1_ingest_fanout_fanin_ocr&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;場景 1：名片辨識與平行增強&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;action=ingest&amp;amp;context=2026 Cloud Summit Taipei&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt; $\rightarrow$ 平行 Fan-Out (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextMatchNode&lt;/code&gt;) $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BuildPreviewNode&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; 暫停，且電話正規化為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+886-912-345-678&lt;/code&gt;。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;case_2_duplicate_promotion_detection&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;場景 2：重複名片與升遷偵測&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;action=ingest&amp;amp;card=promotion_david_chen_appier&amp;amp;context=2026 AI DevFest Taipei&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;測試資料庫已存在 Appier 的 David Chen (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VP of Engineering&lt;/code&gt;)，收到新名片 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Chief Technology Officer (CTO)&lt;/code&gt;) 時，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt; 必須標記 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;IsDuplicate=true&lt;/code&gt; 並產生升遷提醒訊息。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;case_3_hitl_edit_and_confirm_loop&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;場景 3：HITL 迴圈修正與存檔&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;action=ingest&amp;amp;context=2026 Cloud Summit Taipei&amp;amp;edit=職稱改為技術副總，場合改為 COMPUTEX 2026 AI 論壇&amp;amp;hitl_action=confirm&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;驗證從 OCR 預覽 $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ApplyEditNode&lt;/code&gt; 語意修改職稱與場合 $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BuildPreviewNode&lt;/code&gt; 重新渲染預覽 $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HITLConfirmNode&lt;/code&gt; 確認 $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SaveCardNode&lt;/code&gt; 寫入資料庫並產出跟進信。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;case_4a_hybrid_search_cloud_summit_ai&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;場景 4a：自然語言混合檢索&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;幫我找在 Cloud Summit 認識做 AI 的人&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; 將口語轉為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SearchFilter&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt; 命中 2 張名片 $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FormatCarouselNode&lt;/code&gt; 輸出 Flex Carousel JSON。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;case_4b_broad_search_fallback&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;場景 4b：0 筆自動降級模糊檢索&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;幫我找在東京電玩展認識做量子金融區塊鏈的張三&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;驗證當 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt; 查無結果 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0 hits&lt;/code&gt;) 時，條件路由自動降級至 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BroadSearchNode&lt;/code&gt; 執行 Token 模糊檢索，避免空白回覆。&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;case_4c_personalized_icebreaker_email&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;strong&gt;場景 4c：個人化破冰跟進信&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;action=draft_email&amp;amp;card_id=card-seed-1&lt;/code&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: left&quot;&gt;驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;EmailDraftNode&lt;/code&gt; 根據指定名片的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MetContext&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;2026 Cloud Summit Taipei&lt;/code&gt;) 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyInfo&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Google Cloud Taiwan&lt;/code&gt;) 撰寫無幻覺的商業破冰信。&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;四真實踩坑與偵錯實錄為什麼第一次跑-agents-cli-eval-grade-時軌跡分數是-00000&quot;&gt;四、真實踩坑與偵錯實錄：為什麼第一次跑 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval grade&lt;/code&gt; 時軌跡分數是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.0000&lt;/code&gt;？&lt;/h1&gt;

&lt;p&gt;在寫好 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/eval_config.yaml&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/eval_config.yaml&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/metrics.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/metrics.py&lt;/code&gt;&lt;/a&gt; 之後，我們滿懷信心地跑了第一次 Baseline 評估：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;DRY_RUN&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;true &lt;/span&gt;agents-cli &lt;span class=&quot;nb&quot;&gt;eval &lt;/span&gt;run &lt;span class=&quot;nt&quot;&gt;--config&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;eval&lt;/span&gt;/eval_config.yaml
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;結果終端機印出的第一次 Baseline 成績單（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;results_20261022_223104.json&lt;/code&gt;）讓我們大吃一驚：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;╭─ Evaluation Summary ───────────────────────────╮
│ Metric                        Score   Valid    │
│ ────────────────────────────────────────────── │
│ workflow_trajectory_accuracy  0.0000  6/6      │
│ ocr_and_enrichment_quality    1.0000  6/6      │
│ duplicate_and_hitl_precision  0.7333  6/6      │
│ search_and_email_grounding    1.0000  6/6      │
╰────────────────────────────────────────────────╯
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;同時，在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval grade&lt;/code&gt; 的執行 Log 中出現了一行非常關鍵的警告訊息：&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dropped 26 event(s) with no content; the eval service rejects them&lt;/code&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;-追根究底原來-drop_empty_content_events-把中間節點的事件過濾掉了&quot;&gt;🔍 追根究底：原來 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;drop_empty_content_events&lt;/code&gt; 把中間節點的事件過濾掉了！&lt;/h3&gt;

&lt;p&gt;為什麼會被丟掉 26 個事件？我們立刻檢查了 ADK Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow.FunctionNode&lt;/code&gt; 的實作與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 的事件前處理邏輯：&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;在我們原本的 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/nodes_ingest.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_ingest.go&lt;/code&gt;&lt;/a&gt; 與 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/nodes_search.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_search.go&lt;/code&gt;&lt;/a&gt; 中，像 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextMatchNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; 這些&lt;strong&gt;中間處理節點（Intermediate Nodes）&lt;/strong&gt;，原本只負責把結果寫進 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ev.Actions.StateDelta&lt;/code&gt;（例如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ev.Actions.StateDelta[&quot;draft_card&quot;] = ...&lt;/code&gt;），而讓 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ev.Content&lt;/code&gt; 保持為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nil&lt;/code&gt;&lt;/strong&gt;；只有最後一個負責輸出的節點（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BuildPreviewNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SaveCardNode&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FormatCarouselNode&lt;/code&gt;）才會設定 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ev.Content&lt;/code&gt;。&lt;/li&gt;
  &lt;li&gt;但在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval grade&lt;/code&gt; 將軌跡送入評分器之前，底層的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;drop_empty_content_events()&lt;/code&gt; 為了相容雲端 Vertex AI Eval Service 的 Schema 限制，&lt;strong&gt;會把所有 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;event.content == null&lt;/code&gt; 的事件直接從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agent_data.turns[].events&lt;/code&gt; 中剔除！&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;一旦中間節點事件因為 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;content == nil&lt;/code&gt; 被剔除，附掛在該事件上的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;actions.state_delta&lt;/code&gt; 與節點執行紀錄也跟著一起消失了！導致評分器只看到最後一個節點的輸出，因此 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;workflow_trajectory_accuracy&lt;/code&gt; 直接拿到 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.0000&lt;/code&gt;！&lt;/li&gt;
&lt;/ol&gt;

&lt;h3 id=&quot;️-優雅解法為中間節點加上結構化軌跡摘要-setnodetrace&quot;&gt;🛠️ 優雅解法：為中間節點加上結構化軌跡摘要 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace&lt;/code&gt;&lt;/h3&gt;

&lt;p&gt;找到根因之後，解法就非常清晰且優雅了！我們在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/nodes_ingest.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/nodes_ingest.go&lt;/code&gt;&lt;/a&gt; 中設計了一個輕量的輔助函式 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;// setNodeTrace attaches a concise model text part to intermediate workflow node&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;// events so that `agents-cli eval` (which drops events with empty Content)&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;// retains the full node execution trajectory and state_delta history.&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;setNodeTrace&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;summary&lt;/span&gt; &lt;span class=&quot;kt&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;||&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Content&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt;
	&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
	&lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Content&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;genai&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NewContentFromText&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;fmt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Sprintf&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;[%s] %s&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodeName&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;summary&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;genai&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RoleModel&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;接著在每一個中間節點結束前呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace&lt;/code&gt;，例如：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;RouterNode&lt;/code&gt;&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace(ev, &quot;RouterNode&quot;, &quot;route=&quot;+route)&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;VisionOCRNode&lt;/code&gt;&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace(ev, &quot;VisionOCRNode&quot;, fmt.Sprintf(&quot;ocr extracted name=%s company=%s title=%s&quot;, card.Name, card.Company, card.Title))&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CleanAndDedupNode&lt;/code&gt;&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace(ev, &quot;CleanAndDedupNode&quot;, fmt.Sprintf(&quot;phone=%s is_duplicate=%v&quot;, card.Phone, isDup))&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichNode&lt;/code&gt;&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace(ev, &quot;CompanyEnrichNode&quot;, fmt.Sprintf(&quot;company_info=%s tags=%v&quot;, card.CompanyInfo, card.Tags))&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextMatchNode&lt;/code&gt;&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace(ev, &quot;ContextMatchNode&quot;, &quot;met_context=&quot;+card.MetContext)&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QueryIntentNode&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HybridSearchNode&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BroadSearchNode&lt;/code&gt;&lt;/strong&gt;：記錄轉換後的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SearchFilter&lt;/code&gt; 與命中的名片數量。&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;同時，為了避免中間節點的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[NodeName] ...&lt;/code&gt; 軌跡文字蓋掉 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Engine.executeTurn&lt;/code&gt; 最終要回傳給 LINE 呼叫端的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ReplyText&lt;/code&gt;，我們同步強化了 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/internal/workflow/graph.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;internal/workflow/graph.go&lt;/code&gt;&lt;/a&gt; 的狀態收斂邏輯 —— 讓 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TurnResult&lt;/code&gt; 直接從最終收斂的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Session.State&lt;/code&gt; 讀取權威的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StateKeyReplyText&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StateKeyFlexPreviewJSON&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StateKeyFlexCarouselJSON&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StateKeyDraftEmail&lt;/code&gt;！&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;五轉動品質飛輪從-baseline-到-candidate-四大指標全數-10000&quot;&gt;五、轉動品質飛輪：從 Baseline 到 Candidate 四大指標全數 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0000&lt;/code&gt;！&lt;/h1&gt;

&lt;p&gt;加上 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;setNodeTrace&lt;/code&gt; 並支援單輪批次 HITL 修改驗證後，我們重新執行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DRY_RUN=true agents-cli eval run --config eval/eval_config.yaml&lt;/code&gt;：&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Loaded 6 cases from eval/datasets/basic-dataset.json
Starting local Go ADK server...
Running 6 cases against http://127.0.0.1:56649 (app=app, concurrency=4)...
Wrote 6 traces to artifacts/traces/traces_20261022_223515.json
Loaded 6 trace(s) from artifacts/traces/traces_20261022_223515.json
Evaluating metrics: [&apos;workflow_trajectory_accuracy&apos;, &apos;ocr_and_enrichment_quality&apos;, &apos;duplicate_and_hitl_precision&apos;, &apos;search_and_email_grounding&apos;]

╭─ Evaluation Summary ───────────────────────────╮
│ Metric                        Score   Valid    │
│ ────────────────────────────────────────────── │
│ workflow_trajectory_accuracy  1.0000  6/6      │
│ ocr_and_enrichment_quality    1.0000  6/6      │
│ duplicate_and_hitl_precision  1.0000  6/6      │
│ search_and_email_grounding    1.0000  6/6      │
╰────────────────────────────────────────────────╯
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;這次 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dropped 0 event(s)&lt;/code&gt;&lt;/strong&gt;，所有中間節點的軌跡與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;state_delta&lt;/code&gt; 100% 完整保留！我們馬上使用 Quality Flywheel 的第 5 步 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval compare&lt;/code&gt;&lt;/strong&gt;，將修復前的 Baseline 與修復後的 Candidate 進行量化對比：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;agents-cli &lt;span class=&quot;nb&quot;&gt;eval &lt;/span&gt;compare &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--baseline&lt;/span&gt; artifacts/grade_results/results_20261022_223104.json &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--candidate&lt;/span&gt; artifacts/grade_results/results_20261022_223515.json
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;╭─ Summary Comparison ─────────────────────────────────────────────────────────╮
│ Metric                                  Baseline   Candidate      Delta      │
│ ──────────────────────────────────────────────────────────────────────────── │
│ duplicate_and_hitl_precision              0.7333      1.0000    +0.2667      │
│ ocr_and_enrichment_quality                1.0000      1.0000     0.0000      │
│ search_and_email_grounding                1.0000      1.0000     0.0000      │
│ workflow_trajectory_accuracy              0.0000      1.0000    +1.0000      │
╰──────────────────────────────────────────────────────────────────────────────╯
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.0000&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.7333&lt;/code&gt; 一舉推進到 &lt;strong&gt;四大指標全數 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0000&lt;/code&gt;（&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+1.0000&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;+0.2667&lt;/code&gt;）&lt;/strong&gt;，這正是 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 品質飛輪最迷人的價值 —— &lt;strong&gt;讓每一次架構調整都有跡可循、有分可證！&lt;/strong&gt;&lt;/p&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;六雙軌驗證python-自訂評分器-evalmetricspy--go-原生多輪軌跡測試-evaleval_testgo&quot;&gt;六、雙軌驗證：Python 自訂評分器 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/metrics.py&lt;/code&gt;) + Go 原生多輪軌跡測試 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/eval_test.go&lt;/code&gt;)&lt;/h1&gt;

&lt;p&gt;在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/tree/main/eval&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/&lt;/code&gt;&lt;/a&gt; 目錄下，我們採用了 &lt;strong&gt;「Python &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; + Go &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test&lt;/code&gt; 雙軌驗證架構」&lt;/strong&gt;：&lt;/p&gt;

&lt;h2 id=&quot;1-evaleval_configyaml-與-evalmetricspy四大自訂評估指標&quot;&gt;1. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/eval_config.yaml&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/metrics.py&lt;/code&gt;：四大自訂評估指標&lt;/h2&gt;
&lt;p&gt;在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/eval_config.yaml&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/eval_config.yaml&lt;/code&gt;&lt;/a&gt; 中，我們註冊了 4 個決定性軌跡與品質評分器（外加 1 個可供線上 Vertex AI Judge 模型使用的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;card_assistant_llm_rubric&lt;/code&gt;）：&lt;/p&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;na&quot;&gt;metrics_to_run&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;workflow_trajectory_accuracy&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;ocr_and_enrichment_quality&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;duplicate_and_hitl_precision&lt;/span&gt;
  &lt;span class=&quot;pi&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;search_and_email_grounding&lt;/span&gt;

&lt;span class=&quot;na&quot;&gt;custom_metrics&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;workflow_trajectory_accuracy&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;custom&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;module&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;eval.metrics&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;function&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;evaluate_workflow_trajectory&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;ocr_and_enrichment_quality&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;custom&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;module&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;eval.metrics&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;function&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;evaluate_ocr_and_enrichment&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;duplicate_and_hitl_precision&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;custom&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;module&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;eval.metrics&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;function&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;evaluate_duplicate_and_hitl&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;search_and_email_grounding&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;custom&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;module&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;eval.metrics&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;function&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;evaluate_search_and_email&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;而在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/metrics.py&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/metrics.py&lt;/code&gt;&lt;/a&gt; 中，我們定義了輔助函式 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_extract_executed_nodes(instance)&lt;/code&gt; 與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_merged_state_delta(instance)&lt;/code&gt;，直接從 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agent_data.turns[].events&lt;/code&gt; 解析出整條 Graph Workflow 實際走過的節點順序與累計的 Session State：&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;_extract_executed_nodes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instance&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Any&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;])&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;list&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;Extract executed workflow node names in order from `[NodeName] ...` traces.&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;nodes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;list&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_iter_events&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instance&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;content&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ev&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;content&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;or&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;part&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;parts&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;or&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[]:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;isinstance&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;part&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;and&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;isinstance&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;part&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;text&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;match&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;NODE_TRACE_PATTERN&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;findall&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;part&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;text&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]):&lt;/span&gt;
                    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;not&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodes&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;or&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;match&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                        &lt;span class=&quot;n&quot;&gt;nodes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;match&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;nodes&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;如此一來，&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;evaluate_workflow_trajectory&lt;/code&gt; 就能精準檢查：&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;每個節點是否按拓撲順序（Subsequence Order）執行？&lt;/li&gt;
  &lt;li&gt;所有的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expected_state_keys&lt;/code&gt;（如 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;draft_card&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;flex_preview_json&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;saved_card_id&lt;/code&gt;、&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;search_results&lt;/code&gt;）是否都有寫入 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;state_delta&lt;/code&gt;？&lt;/li&gt;
  &lt;li&gt;最終輸出是否同時滿足 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expected_response_substrings&lt;/code&gt; 並排除 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbidden_substrings&lt;/code&gt;？&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;2-evaleval_testgogo-原生多輪-hitl-暫停恢復與-app-info-內省測試&quot;&gt;2. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/eval_test.go&lt;/code&gt;：Go 原生多輪 HITL 暫停恢復與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/app-info&lt;/code&gt; 內省測試&lt;/h2&gt;
&lt;p&gt;除了透過 HTTP SSE 呼叫的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 之外，我們也在 &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/blob/main/eval/eval_test.go&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/eval_test.go&lt;/code&gt;&lt;/a&gt; 中撰寫了 Go 原生的 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestEvalDatasetAndAppInfoIntrospection&lt;/code&gt;&lt;/strong&gt; 與 &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestPhase4WorkflowTrajectorySuite&lt;/code&gt;&lt;/strong&gt;，直接可以在 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;go test ./...&lt;/code&gt; 或 GitHub Actions CI 中毫秒級執行：&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestEvalDatasetAndAppInfoIntrospection&lt;/code&gt;&lt;/strong&gt;：驗證 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eval/datasets/basic-dataset.json&lt;/code&gt; Schema 完整性，並直接呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;appinfo.BuildAppInfo&lt;/code&gt; 確認 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line_card_assistant&lt;/code&gt; 圖內的 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CompanyEnrichAgent&lt;/code&gt; 能夠被 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/apps/{app}/app-info&lt;/code&gt; 正確反射內省。&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;TestPhase4WorkflowTrajectorySuite&lt;/code&gt;&lt;/strong&gt;：
    &lt;ul&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Case1_IngestFanOutFanInOCR&lt;/code&gt;&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Case2_DuplicatePromotionDetection&lt;/code&gt;&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Case3_MultiTurnHITLEditAndConfirmLoop&lt;/code&gt;（真實分三輪呼叫 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StartIngest&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ResumeHITL(edit)&lt;/code&gt; $\rightarrow$ &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ResumeHITL(confirm)&lt;/code&gt; 驗證跨輪次 Pause/Resume 狀態機）&lt;/li&gt;
      &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Case4_SearchHybridAndBroadFallbackAndEmailDraft&lt;/code&gt;&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;現在，只需要一行 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;make eval&lt;/code&gt;，就能同時跑完 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval run&lt;/code&gt; 與 Go 原生測試套件：&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nv&quot;&gt;$ &lt;/span&gt;make &lt;span class=&quot;nb&quot;&gt;eval
&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;DRY_RUN&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;true &lt;/span&gt;agents-cli &lt;span class=&quot;nb&quot;&gt;eval &lt;/span&gt;run &lt;span class=&quot;nt&quot;&gt;--config&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;eval&lt;/span&gt;/eval_config.yaml
...
go &lt;span class=&quot;nb&quot;&gt;test&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-v&lt;/span&gt; ./eval/...
&lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; RUN   TestEvalDatasetAndAppInfoIntrospection
&lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestEvalDatasetAndAppInfoIntrospection &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; RUN   TestPhase4WorkflowTrajectorySuite
    &lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestPhase4WorkflowTrajectorySuite/Case1_IngestFanOutFanInOCR &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestPhase4WorkflowTrajectorySuite/Case2_DuplicatePromotionDetection &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestPhase4WorkflowTrajectorySuite/Case3_MultiTurnHITLEditAndConfirmLoop &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;---&lt;/span&gt; PASS: TestPhase4WorkflowTrajectorySuite/Case4_SearchHybridAndBroadFallbackAndEmailDraft &lt;span class=&quot;o&quot;&gt;(&lt;/span&gt;0.00s&lt;span class=&quot;o&quot;&gt;)&lt;/span&gt;
PASS
ok  	github.com/kkdai/line-card-assistant/eval	0.436s
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;hr /&gt;

&lt;h1 id=&quot;七小結與下一篇預告phase-5-最終章正式部署terraform-iac-與-cloud-trace-可觀測性&quot;&gt;七、小結與下一篇預告（Phase 5 最終章：正式部署、Terraform IaC 與 Cloud Trace 可觀測性）&lt;/h1&gt;

&lt;p&gt;截至目前為止，我們的 &lt;strong&gt;&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/9&quot;&gt;LINE AI 名片王 Roadmap (Issue #9)&lt;/a&gt;&lt;/strong&gt; 已經完成了前四大階段：&lt;/p&gt;
&lt;ul class=&quot;task-list&quot;&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; checked=&quot;checked&quot; /&gt;&lt;strong&gt;Phase 1&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 環境與 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk_go&lt;/code&gt; 專案 Scaffolding（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/10&quot;&gt;PR #10&lt;/a&gt;）&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; checked=&quot;checked&quot; /&gt;&lt;strong&gt;Phase 2&lt;/strong&gt;：ADK Go Graph Workflow 適配 Agent Runtime、GCS Artifacts、Agent Platform Sessions 與 Cloud SQL &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PostgresStore&lt;/code&gt;（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/11&quot;&gt;PR #11&lt;/a&gt;、&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/12&quot;&gt;PR #12&lt;/a&gt;）&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; checked=&quot;checked&quot; /&gt;&lt;strong&gt;Phase 3&lt;/strong&gt;：Cloud Run LINE Webhook Gateway 與 Agent Runtime 雙層解耦架構（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/12&quot;&gt;PR #12&lt;/a&gt;）&lt;/li&gt;
  &lt;li class=&quot;task-list-item&quot;&gt;&lt;input type=&quot;checkbox&quot; class=&quot;task-list-item-checkbox&quot; disabled=&quot;disabled&quot; checked=&quot;checked&quot; /&gt;&lt;strong&gt;Phase 4&lt;/strong&gt;：&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli eval&lt;/code&gt; 自動化評估與品質飛輪（&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13&lt;/a&gt;）&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;在下一篇（也是本系列的最終章 &lt;strong&gt;Phase 5 — &lt;a href=&quot;https://github.com/kkdai/line-card-assistant/issues/8&quot;&gt;Issue #8&lt;/a&gt;&lt;/strong&gt;），我們將把通過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;1.0000&lt;/code&gt; 滿分評估的 LINE AI 名片王，透過 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli deploy&lt;/code&gt; 正式推進生產環境，並完整串接 &lt;strong&gt;Terraform IaC 基礎設施即程式碼、GitHub Actions CI/CD 自動化評估部署流水線，以及 OpenTelemetry + Google Cloud Trace 全鏈路可觀測性&lt;/strong&gt;，敬請期待！&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;參考資源&quot;&gt;參考資源&lt;/h2&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;GitHub Repository&lt;/strong&gt;：&lt;a href=&quot;https://github.com/kkdai/line-card-assistant&quot;&gt;kkdai/line-card-assistant&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Phase 4 Pull Request&lt;/strong&gt;：&lt;a href=&quot;https://github.com/kkdai/line-card-assistant/pull/13&quot;&gt;PR #13 — &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;feat(eval): add Phase 4 agents-cli eval suite and Go workflow trajectory tests (#7)&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Google Cloud &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agents-cli&lt;/code&gt; 官方文件&lt;/strong&gt;：&lt;a href=&quot;https://google.github.io/agents-cli/guide/lifecycle/&quot;&gt;The Quality Flywheel &amp;amp; Agent Evaluation&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Google ADK 官方文件&lt;/strong&gt;：&lt;a href=&quot;https://adk.dev/graphs/&quot;&gt;Graph-based Agent Workflows (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;adk/v2/workflow&lt;/code&gt;)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
				<pubDate>Thu, 22 Oct 2026 00:00:00 +0000</pubDate>
				<link>https://www.evanlin.com/adk-graph-workflow-go-5/</link>
				<guid isPermaLink="true">https://www.evanlin.com/adk-graph-workflow-go-5/</guid>
			</item>
		
	</channel>
</rss>
