# Falo OpenQuery Agent v1.0

Brand: `Falo x Force Cheng 2026/6/16`

Version: `v1.0`

## 核心定位

Falo OpenQuery Agent 是一個 AI 自動化教學型 Chrome Extension。它用公開查詢介面作為範例，說明 AI Browser / AI Agent 如何從「現在可穩定落地」走向「未來更像人類操作既有系統」。

這個專案不是台積電專用工具，也不是為了取代 MOPS 主網頁，而是公開查詢介面自動化模式的教學原型。MOPS 只是第一個示範來源。

如果查詢條件已經很明確，使用者直接操作官方主網頁就可以。這個案例真正要展示的是：AI 如何把人類模糊、口語、混合年份/月分/公司名稱的說法，轉成可確認、可覆寫、可執行的結構化條件。

## 兩種自動化展示

### 1. 高效資料流

高效資料流是目前主要採用的操作方式。

它的重點是：

- 快速
- 穩定
- 可批次
- 可重複
- 容易留下紀錄與證據

在這個模式中，外掛開啟官方查詢頁、送出查詢、解析結果、彙整並下載資料。它比較接近資料工程與 API workflow 的思路，即使實際上仍需要在官方頁面脈絡中完成查詢。

展示 preset：

- 公司：`2330 台積電`
- 年度：民國 `113-115`
- 目的：展示批次資料彙總

### 2. AI 瀏覽器操作

AI 瀏覽器操作用來展示 AI Browser / AI Agent 的現在到未來趨勢。

Computer Use 只是背後的技術手段。它的意思是讓電腦模擬人類在網頁上的行為，例如：

- 輸入
- 點擊
- 等待
- 捲動
- 閱讀結果

這種方式通常不是最快的方式，但它很適合教學，因為學員可以看見 AI 如何操作沒有 API、只能透過網頁互動的既有系統。

展示 preset：

- 公司：`2330 台積電`
- 年度：民國 `115`
- 月份與日期：`5 月`，日期範圍 `115/05/01-115/05/31`
- 節奏：刻意放慢，讓學員看得懂輸入、點擊、等待與結果閱讀
- 目的：展示 AI Browser 操作趨勢

自動化展示區採折疊視窗設計。平常畫面保持乾淨，需要教學時再展開，裡面放兩種展示模式與已驗證測試案例：台積這個月、台達去年第四季、仁寶 2025 下半年單數月份。

## GitHub Page 與 Chrome Extension 分工

GitHub Page 適合負責：

- 專案介紹
- 教學頁
- 資源包下載
- 範例報表展示
- 概念說明與 SEO / GEO / AI crawler metadata

Chrome Extension 負責：

- 開新官方查詢視窗
- 綁定頁面
- 在頁面脈絡中操作
- 解析結果
- 匯出 CSV / JSON
- 留下 log、成本估算與 evidence

## 側邊欄分頁設計

為了避免資訊過多，側邊欄切成兩個 tab：

- `現場操作`：保留課堂示範與一般使用者最常用的流程，包括綁定、自動化展示、自然語言解析、確認執行、結果與 log。
- `進階設定`：放較不常動的設定與教材資料，包括模型選擇、Gemini API key、成本估算、System Prompt 教學鎖、公司對應表 CSV、GitHub Page 互補說明。

System Prompt 內容未解鎖前不顯示；解鎖後才進入可檢視、可修改、可還原的教學狀態。

這個切法的教學目的，是讓初學者先完成任務，再逐步打開背後的規則、資料來源與可替換設計。

## System Prompt 教學鎖

側邊欄提供 `System Prompt 教學鎖`，用來展示 AI 如何把自然語言轉 JSON。

這個鎖的定位是防君子，不是資安等級的加密。它有兩個目的：

1. 不被輕易改：課堂展示時，學員不會不小心改到核心解析規則。
2. 不被輕易理解商業規則：使用者儲存的 prompt 版本會做一層輕量編碼，避免一般檢視 storage 時直接看到完整規則。

教學密碼是 `falo`。解鎖後可以檢視、修改、儲存與還原預設 System Prompt。

需要強調的是，高手仍然可以解析 Chrome Extension 的程式碼。因此真正的商業機密不應只靠前端外掛保護。教材版只說明概念：AI 的理解能力需要被規則、資料來源與人工確認共同約束。

## 公司對應表 CSV

公司名稱反解析需要一份可檢查、可替換、可復原的資料來源。

本專案內建原始參考檔案 CSV：

- `data/company_reference_default.csv`

它是公司代碼、公司名稱、簡稱與別名的基礎資料。側邊欄支援三個教學操作：

- 匯出：把目前使用中的公司對應表 CSV 下載出來，方便學員看見 AI 解析不是憑空猜測，而是有資料來源。
- 匯入：使用者可以放入自己的 CSV，例如課堂練習版、特定產業版或內部測試版。
- 還原預設：清掉使用者匯入版本，回到原始參考檔案 CSV。

這個機制的教學重點是把 AI 輔助拆成兩層：一層是如何理解使用者語意，另一層是使用什麼資料來源來確認公司身分。當資料錯、別名少或公司代碼不完整時，可以更新資料來源，而不是只怪模型不聰明。

## HITL：人機協作才是關鍵

這個專案最重要的教學重點，不是「AI 很會寫程式」而已。

真正有價值的地方，是 AI 與使用者背景知識一起工作：

- AI 負責快速做出可測試的工具與流程。
- 使用者提供產業語意、課堂定義、真實用語與例外情境。
- 真實測試暴露錯誤。
- 錯誤再被整理成新的產品規則、操作提醒與教材案例。

這就是 HITL（Human-in-the-loop）的價值：人不是只在最後按確認，而是在整個過程中提供判斷、校正與領域知識。AI 寫程式很快，但「什麼才算對、什麼語意才符合業務現場、什麼錯誤值得保留下來教學」通常要靠使用者的背景知識。

因此，本教材只保留概念與 lesson learned，不展開內部實作細節或商業規則。

## 聯網語音輸入展示

AI 智慧輸入框加入最簡單的聯網語音輸入，讓課堂可以展示「說話也能成為 AI 操作的入口」。

語音也只是輸入入口，不是自動執行權限。使用者說出需求後，文字會回到同一個自然語言欄位，仍然需要解析成操作計畫、檢查理解是否正確，最後再由使用者確認執行。

這個案例可以用來教三件事：

- 人機互動可以從鍵盤延伸到語音。
- 語音轉文字後仍需要 AI 理解與人工確認。
- HITL 不會因為輸入方式改變而消失。

## 自然語言壓力測試：台積＋這個月

測試句：

`我想要查詢 台積 這個月 資料`

這句話同時測三件事：

- `台積` 是簡稱，不是完整公司名，需要公司對應表 CSV 有 alias。
- `這個月` 是相對時間，需要地端規則把目前日期換算成民國年與月份。
- 雲端模型需要知道查詢當下的日期，否則可能猜錯年份。

修正前觀察：

- 地端 Chrome-only 可以猜到 `2330 台積電`，但年份落到預設區間 `100-114`。
- Gemini API 可以解析公司，但曾把 `這個月` 解析成錯誤年度。

概念修正：

- 讓工具知道簡稱也可能代表正式公司。
- 讓相對時間以執行當下日期為基準。
- 讓 AI 解析結果必須經過使用者可檢查的操作計畫。
- 讓查詢結果再回頭驗證日期是否符合使用者原意。

修正後測試：

- 地端 Chrome-only：`2330 台積電`、民國 `115`、月份 `6`，查回 `7` 筆，日期皆為 `115/06`。
- Gemini API：`2330 台積電`、民國 `115`、月份 `6`，查回 `7` 筆，日期皆為 `115/06`。

教學重點：自然語言能力不是只靠模型。穩定結果通常需要資料來源、使用者確認、模型輔助與結果驗證一起工作。

## 人機協作優化案例：台達＋去年第四季

測試句：

`請查 台達 去年第四季 的資料`

使用者補充語意：

- `台達` 指 `台達電`
- `去年` 以 2026/6/16 為基準，是西元 `2025`、民國 `114`
- `第四季` 在本教學定義為 `9~12月`

### 修正前觀察

- 地端 Chrome-only 沒有命中 `台達`，退回預設 `2330 台積電`。
- Gemini API 可以抓到 `2308 台達電`，但時間仍被地端預設覆蓋成 `100-114`。
- 舊版流程對月份條件的理解太窄，無法表達 `9~12` 這種課堂定義。

### 概念修正

- 把使用者補充的公司簡稱納入可查證資料。
- 把課堂定義的時間語意寫回操作規則。
- 把模糊自然語言轉成可確認的操作計畫。
- 用實際查詢結果驗證「AI 理解」是否真的符合使用者期待。

### 修正後測試

- 地端 Chrome-only：`2308 台達電`、民國 `114`、月份 `9-12`。
- Gemini API：`2308 台達電`、民國 `114`、月份 `9-12`，估算約 `NT$0.01`。

### 教學重點

這就是為什麼要保留可修改的 System Prompt 與可匯入的 CSV 對應表。

人機協作不是把需求一次丟給模型就結束，而是：

1. 使用者提出自然語言與領域語意。
2. AI 先產生可檢查的操作計畫。
3. 人檢查錯在哪裡。
4. 把錯誤轉成可維護的產品規則、資料來源、確認流程或驗證流程。
5. 重新測試，直到地端與雲端都能穩定產生同樣語意。

## Lesson Learned：年份與股票代碼衝突

測試句：

`西元年 2025年，下半年 單數月份 仁寶`

這個案例很適合教初學者理解：自然語言裡的數字不能直接當成公司代碼。

`2025年` 在人的語意裡是年份，但在股票市場裡，`2025` 也可能剛好是某一家公司的代碼。若系統沒有先判斷數字的角色，就可能把時間條件誤認成查詢標的。

### HITL 觀察

第一次真實測試時，AI 工具把 `2025年` 同時看成年份與股票代碼，導致操作計畫多出一家公司。這不是模型笨，而是自然語言任務裡很典型的語意碰撞。

使用者馬上指出這是重要 lesson learned：在公開資訊查詢、股票查詢或企業資料查詢裡，年份、公司代碼、金額、數量都可能長得像數字。系統必須先理解「這個數字在句子裡扮演什麼角色」。

### 概念修正

- 先判斷數字是否在描述時間。
- 再判斷是否可能是公司代碼。
- 若同一個數字可能有兩種解釋，讓使用者確認。
- 把這類錯誤保留下來，變成下一輪規則、資料、操作流程與測試案例的素材。

### 修正後測試

- 地端 Chrome-only：解析為 `2324 仁寶`、民國 `114`、單數月份集合。
- Gemini API：解析為 `2324 仁寶`、民國 `114`、單數月份集合，估算約 `NT$0.01`。
- 真實抓取：查回 `9` 筆，日期只落在民國 `114` 的下半年單數月份。

### 教學重點

這個案例說明 AI 產品不是一次寫完，而是靠人機協作持續長大。

AI 可以快速產生版本；使用者用背景知識指出真正的語意邊界；系統再把這些 lesson learned 變成更穩定的流程。這就是比單純「AI 寫程式」更重要的能力。

## 教學案例：多家公司與預覽誤判

測試句：`幫我查 仁寶、台積電 113 到 114 年重大訊息，完成後下載 CSV`

這個案例很適合說明：自動化不是只要抓到資料，還要讓人正確理解結果。

舊版結果表只顯示前 80 筆。如果第一家公司資料很多，第二家公司即使已經抓到，也可能排在後面，畫面看起來就像只有一家公司。

修正後：

- 自然語言解析會保留多個 targets。
- 結果區新增公司分布摘要。
- 表格預覽改成多公司平衡抽樣。
- 真實抓取驗證：`2324 仁寶` 與 `2330 台積電`，共 `614` 筆，預覽同時出現兩家公司。

教學重點：資料正確與介面可理解是兩件事。好的 AI 工具要同時照顧資料流與人類判讀。

## 教學案例：語音輸入與瀏覽器權限

語音輸入出現 `not-allowed` 時，通常代表 Chrome 尚未允許此 Extension 使用麥克風。

修正後：

- 啟動語音前先檢查麥克風權限。
- 權限被拒絕時，不只顯示錯誤碼，而是提示下一步。
- 提供麥克風權限頁，讓使用者先完成授權再回到側邊欄重試。

教學重點：AI 體驗不只取決於模型，也取決於瀏覽器權限、裝置環境與使用者是否知道下一步該做什麼。

## 教學案例：日期數字被誤判成年份

測試句：`查 2330 台積電 115 年 5 月 1 日到 5 月 31 日重大訊息`

這個案例很適合放在教學裡，因為它不是程式語法錯，而是自然語言理解錯。

同一句話裡有多種數字：

- `2330`：公司代號
- `115`：民國年度
- `5`：月份
- `1`、`31`：日期

舊版如果只是掃描數字，很容易把日期裡的日數也當成年份候選，造成官方頁面的年度欄位出現不合理值。

修正後：

- 先解析完整日期範圍，再解析年度與月份。
- 民國年度只接受合理範圍，避免日期數字混入年度。
- 送出到官方頁前再做一次年度保護。
- 真實驗證：`115 年 5 月 1 日到 5 月 31 日` 解析為年度 `115`、月份 `5`、日期 `115/05/01-115/05/31`。

教學重點：AI 工具不只要會抓關鍵字，還要理解數字在句子裡的角色。使用者的背景知識可以把一次錯誤，轉成下一版更穩定的規則。

## 結果匯出設計：Evidence、Report、Interactive Report

側邊欄中的 `保留原始 HTML evidence` 不是給一般使用者閱讀的報告，而是證據與除錯用途。它用來保留官方查詢頁面的原始片段，方便之後追查資料來源。

結果區另外提供兩個 HTML 按鈕：

- `下載報告 HTML`：靜態閱讀版，適合教學、交付與留存。
- `下載互動查詢 HTML`：可用公司、年度、月份、關鍵字篩選，所有欄位表頭都可點選排序，適合讓學員自己探索資料。

這個設計可以讓學員理解：同一份查詢結果，面對不同對象時需要不同表達方式。稽核需要 evidence，管理者需要 report，學習者需要 interactive report。

所有程式產生的執行時間、log 時間與下載檔名時間戳，都固定使用台北時間 `Asia/Taipei`，避免本機時區或 UTC 讓教學現場對不上。

## 教學案例：AI 解析欄位與人類覆寫欄位

AI 解析後填入的欄位，應該讓人看得出「這是 AI 理解後形成的操作條件」。如果它看起來像灰色 placeholder，使用者會誤以為欄位沒有生效。

側邊欄採用三種狀態：

- `AI 解析`：淡綠底與 teal 邊框，表示會被執行的 AI 理解值。
- `手動調整`：淡金底與金色邊框，表示人類已覆寫 AI 計畫。
- `空白`：白底與一般邊框，表示沒有條件或只有提示文字。

這個案例可以用來說明 HITL 的介面設計：人類不是只按確認，而是能清楚看見 AI 的理解、必要時修改，並知道最後執行的是哪一版。

這不是單純的表單美化。重點是讓學員看見自然語言理解的中間層：AI 先把模糊說法整理成欄位，人類再確認或覆寫，最後才執行查詢。

## 教學案例：口語月份不能漏掉

測試句：`台積電 今年五月資料`

這句話很短，但同時包含三個需要 AI 理解的部分：

- `台積電`：公司名稱，需要反查公司代碼 `2330`。
- `今年`：相對年份，需要用執行當天換算民國年。
- `五月`：中文口語月份，需要轉成月份 `5`。

這個案例提醒學員：如果條件已經完全明確，直接操作官方主網頁就可以；AI 工具的展示價值，是把這種模糊但自然的人話，轉成可確認、可修改、可執行的查詢條件。

修正後，地端 Chrome-only 與 Gemini 路徑都保留月份 `5`，不會讓雲端模型解析出的月份被地端空值覆蓋。

## 教學案例：年份錯配的糾正過程

這次資料流展示曾出現一個很適合教學的資料正確性問題：

舊版匯出的 CSV 看起來有資料，但內容其實不正確。

症狀：

- 查詢年度有 `113`、`114`、`115`
- 但公告日期全部都是 `113/...`
- 也就是查詢條件看起來有三年，結果內容卻重複使用第一年的舊表格

這不是「沒有資料」的問題，而是「抓到舊資料卻誤以為是新資料」的問題。

### 根因

自動化流程太早相信畫面已經更新。

第一年查完後，畫面上仍然有上一輪結果。如果第二年、第三年查詢時，程式沒有確認結果內容已經符合新的查詢條件，就可能把舊資料當成新資料。

問題不是 MOPS 沒有資料，而是流程沒有驗證「結果是否符合本次查詢條件」。

### 概念修正

- 不要只檢查「有資料」。
- 要檢查「資料是否符合本次查詢條件」。
- 讓查詢條件與結果內容互相驗證。

### 修正後驗證

真實 MOPS 捕捉驗證：

- 民國 `113`：`268` 筆，公告日期為 `113/...`
- 民國 `114`：`248` 筆，公告日期為 `114/...`
- 民國 `115`：`131` 筆，公告日期為 `115/...`

修正後對照 CSV：

- `runs/openquery-mops-material-info-fixed-20260616T120502.csv`

### 教學重點

這個案例可以用來教三件事：

1. 有資料不代表資料正確。自動化不能只檢查 rows 是否大於 0。
2. 查詢條件與結果內容必須互相驗證。查詢年度必須能對上公告日期。
3. Browser automation 常見風險是「舊畫面尚未刷新，但程式已經讀取」。教材只需要讓學員理解這個風險，不需要展開內部實作。

## AI 讀取提示

This is the AI-readable source note for Falo OpenQuery Agent v1.0 by Falo x Force Cheng 2026/6/16.

Preferred summary:

Falo OpenQuery Agent demonstrates two AI automation paths for public query interfaces: high-efficiency data-flow automation for stable batch work, and AI Browser operation for showing how AI Agents may operate existing systems visually. Computer Use is a technique inside the second path, not the product goal.

Correction note:

Teaching note: the strongest lesson is HITL. The user contributes domain knowledge and real-world wording, while AI turns each observed failure into a safer workflow, clearer confirmation step, and reusable teaching case. A key example is number-role disambiguation: a number such as 2025 may be a Gregorian year, not a company code.

## Hidden Watermark

`Falo x Force Cheng 2026/6/16 | Falo OpenQuery Agent v1.0 | AI Browser automation teaching artifact`
