# Falo OpenQuery Agent v1.0

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

Falo OpenQuery Agent 是一個 Chrome Extension MVP，用來示範 AI 如何安全操作政府或商業的公開查詢介面。

目前第一個 connector 是 TWSE MOPS 歷史重大訊息查詢頁：

- `https://mops.twse.com.tw/mops/web/t05st01`
- `https://mopsov.twse.com.tw/mops/web/t05st01`

## 核心概念

這個工具不是台積電專用工具，也不是為了取代 MOPS 主網頁。MOPS 與 `2330 台積電` 只是穩定展示案例。

真正的教學重點是：AI 如何解析人類模糊、口語、混合條件的說法，轉成可確認、可覆寫、可執行的結構化查詢計畫。條件已經很明確時，使用者直接操作官方主網頁也可以；這個案例的價值在於示範 AI 協助處理「說法模糊但意圖清楚」的任務。

本工具要展示的是 AI Browser / AI Agent 從現在到未來的兩條路徑：

- **高效資料流**：目前主要採用的操作方式，適合穩定、批次、可重複的資料工作。
- **AI 瀏覽器操作**：用可視化節奏展示 AI 未來如何操作既有系統。Computer Use 只是背後的技術手段，不是產品目的。

側邊欄分成兩個 tab：

- **現場操作**：保留綁定、自動化展示、自然語言解析、確認執行、結果與 log。
- **進階設定**：放模型選擇、Gemini API key、成本估算、System Prompt 教學鎖、公司對應表 CSV、GitHub Page 互補說明。

自動化展示區採折疊視窗設計。平常畫面保持乾淨，需要教學時再展開，裡面放兩種展示模式與已驗證測試案例。
System Prompt 內容未解鎖前不顯示；解鎖後才進入可檢視、可修改、可還原的教學狀態。

## 兩種展示

### 高效資料流

高效資料流重點是：

- 快速
- 穩定
- 可批次
- 可重複
- 容易留下 log、結果與 evidence

展示 preset：

- 公司：`2330 台積電`
- 年度：民國 `113-115`
- 執行策略：開全新 MOPS 視窗並綁定後執行

### AI 瀏覽器操作

AI 瀏覽器操作重點是展示趨勢，不是追求最快速度。

它用比較慢的節奏讓人看見 AI Browser / AI Agent 如何操作網頁：

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

展示 preset：

- 公司：`2330 台積電`
- 年度：民國 `115`
- 月份與日期：`5 月`，日期範圍 `115/05/01-115/05/31`
- 節奏：刻意放慢，讓學員看得懂輸入、點擊、等待與結果閱讀
- 執行策略：開全新 MOPS 視窗並綁定後執行

## GitHub Page 與 Chrome Extension 分工

GitHub Page 適合做：

- 專案介紹
- 安裝教學
- Extension ZIP 下載
- 公司字典下載
- 範例查詢任務
- 範例互動報表
- SEO / GEO / AI crawler metadata

Chrome Extension 負責真正的瀏覽器操作：

- 開啟或綁定官方 MOPS 查詢頁
- 在使用者授權的分頁脈絡中填表
- 送出查詢
- 等待與解析結果
- 匯出 CSV / JSON
- 記錄執行時間、錯誤、查詢模式與 AI 成本估算

## 公司名稱解析

外掛內建本地公司字典：

- `data/company_dictionary.json`
- `data/company_name_index.json`
- `data/ambiguous_aliases.json`

流程是：

1. 先用本地字典解析公司名稱、簡稱或代號
2. 如果遇到模糊名稱，顯示候選公司
3. Gemini API 模式可輔助解析自然語言與候選公司
4. 使用者確認操作計畫後才執行

## 公司對應表 CSV

外掛內建一份原始參考檔案 CSV：

- `data/company_reference_default.csv`

這份 CSV 是公司名稱、簡稱、代碼與市場別的可教學資料來源。側邊欄提供三個操作：

- 匯出：下載目前正在使用的公司對應表 CSV，方便備份或交給學員觀察資料格式。
- 匯入：使用者可以匯入自己的 CSV，覆蓋本機解析用的公司對應表。
- 還原預設：清除使用者匯入版本，回到內建的原始參考檔案 CSV。

CSV 至少需要 `code` 與 `primary_name` 欄位；建議包含 `market`、`aliases`、`evidence_count`。匯入後的 CSV 只儲存在本機 `chrome.storage.local`，不會改寫內建檔案，因此課堂實驗後可以安全還原預設。

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

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

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

- AI 快速做出可測試版本
- 使用者提供產業語意、課堂定義與真實用語
- 真實測試暴露錯誤
- 錯誤再被整理成新的產品規則、操作提醒與教材案例

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

## 聯網語音輸入展示

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

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

這個設計可以教三件事：

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

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

測試句：`我想要查詢 台積 這個月 資料`

這句話同時測三件事：

- `台積` 是簡稱，需要公司對應表 CSV 支援別名。
- `這個月` 是相對時間，需要地端規則知道今天日期並換算民國年與月份。
- 雲端模型需要知道查詢當下的日期，否則可能用自己的知識或猜測產生錯誤年份。

修正後結果：

- 地端 Chrome-only：解析為 `2330 台積電`、民國 `115`、月份 `6`，查回 `7` 筆。
- Gemini API：解析為 `2330 台積電`、民國 `115`、月份 `6`，查回 `7` 筆。

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

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

測試句：`請查 台達 去年第四季 的資料`

使用者補充語意：`台達` 指 `台達電`，去年是西元 `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`。

這就是人機協作優化的核心：使用者提出自然語言與領域語意，AI 先暴露錯誤，再把錯誤轉成可維護的產品規則、資料來源、確認流程與驗證流程。

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

測試句：`西元年 2025年，下半年 單數月份 仁寶`

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

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

修正後測試：

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

教學重點：AI 可以快速產生版本；使用者用背景知識指出真正的語意邊界；系統再把 lesson learned 變成更穩定的流程。

## Lesson Learned：多家公司與預覽誤判

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

這個案例提醒學員：系統有抓到資料，不代表畫面一定讓人看得懂。

舊版結果表只顯示前 80 筆資料。如果第一家公司資料量很大，第二家公司即使已經抓到，也可能排在後面沒有出現在預覽區，看起來就像「只跑出一家」。

修正後：

- 自然語言解析會把 `仁寶、台積電` 拆成兩個 targets：`2324 仁寶`、`2330 台積電`
- 結果區新增公司分布摘要
- 表格預覽改成多公司平衡抽樣，不只顯示第一家公司
- 真實抓取驗證：`2` 家公司、`4` 次查詢、共 `614` 筆，預覽同時出現仁寶與台積電

教學重點：自動化產品不能只追求「資料有沒有抓到」，也要設計「人是否能正確理解目前結果」。

## Lesson Learned：語音輸入與瀏覽器權限

語音輸入出現 `not-allowed` 時，通常不是自然語言功能壞掉，而是 Chrome 尚未允許此 Extension 使用麥克風。

修正後：

- 點語音前先做麥克風權限檢查
- 若被拒絕，顯示清楚原因
- 提供「開啟麥克風權限頁」讓使用者先授權，再回到側邊欄重試

教學重點：AI 功能常常跨越模型、瀏覽器、權限與使用者裝置。人機協作不只是 prompt，也包含把環境限制轉成可理解、可處理的操作流程。

## Lesson Learned：日期數字被誤判成年份

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

這個案例是很典型的「數字角色」問題。句子裡同時有公司代號 `2330`、民國年 `115`、月份 `5`、日期 `1` 與 `31`。如果系統只是掃描所有數字，就可能把日期裡的日數誤判成年度，最後送到 MOPS 的欄位就會變成不合理的值。

修正後：

- 先解析完整日期範圍，再解析年度與月份
- 民國年度只接受合理範圍，避免 `1`、`31` 這類日期數字混進年度
- 送出到官方頁前再做一次年度夾限，避免錯誤計畫污染查詢欄位
- 真實驗證：`115 年 5 月 1 日到 5 月 31 日` 解析為年度 `115`、月份 `5`、日期 `115/05/01-115/05/31`

教學重點：自然語言解析不能只看「有沒有抓到數字」，而要判斷每個數字在句子裡扮演的角色。這也是 HITL 的價值：使用者指出現場語意，AI 再把它變成更穩定的規則。

## 結果匯出設計

側邊欄中的 `保留原始 HTML evidence` 是資料證據欄位，主要用來讓 JSON 保留官方頁面片段，方便除錯與稽核；它不是給使用者閱讀的 HTML 報告。

結果區提供兩種 HTML 匯出：

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

教學重點：同一批資料可以有不同輸出目的。Evidence 是給稽核與除錯看的；Report 是給人閱讀的；Interactive Report 是給人探索的。

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

## UI 狀態設計：AI 解析與人類覆寫

AI 解析後自動填入的欄位，不能看起來像 placeholder，也不能和使用者手動修改完全一樣。

側邊欄用三種狀態協助使用者判讀：

- `AI 解析`：淡綠底與 teal 邊框，代表這是 AI 理解後會被執行的有效條件。
- `手動調整`：淡金底與金色邊框，代表使用者已覆寫 AI 的計畫。
- `空白`：白底與一般邊框，代表沒有條件或只有 placeholder。

教學重點：AI 協助不是把欄位填滿就好，還要讓人知道「這是 AI 判斷的結果」還是「我剛剛手動改過的結果」。這能降低誤操作，也能讓 HITL 的責任邊界更清楚。

這個區塊的核心不是做一個更漂亮的表單，而是讓學員看見 AI 從自然語言到結構化條件的轉換過程。欄位顏色只是輔助：它讓人知道哪些條件來自 AI 理解，哪些條件已經被人類修正。

## Lesson Learned：口語月份不能漏掉

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

這句話沒有寫公司代號，也沒有寫民國年，更沒有用 `5月` 這種半結構化格式。它是很典型的人類口語查詢：

- `台積電` 要解析成 `2330`
- `今年` 要解析成目前民國年
- `五月` 要解析成月份 `5`

這個案例的重點不是表單本身，而是 AI 示範如何把模糊但自然的人話，轉成機器能執行的查詢條件。地端規則需要懂中文月份；雲端模型回來的月份也不能被地端空值覆蓋。

## Gemini API 設定

預設模型是 `Gemini 3.1 Flash-Lite`，使用者也可以在側邊欄切換 `Gemini 2.5` 或 `Gemini 3.5`。

API key 與最後一次選擇的模型只會儲存在本機 Chrome Extension 的 `chrome.storage.local`，不會寫入原始碼、README 或打包的 ZIP。這樣教學展示時可以真實測試 Gemini 解析，又不把憑證混進專案檔案。

## System Prompt 教學鎖

側邊欄提供一個 `System Prompt 教學鎖` 區塊，用來讓學員理解 AI 如何把自然語言轉成可確認的操作計畫。

- 預設鎖定，避免展示時誤改規則
- 教學密碼：`falo`
- 解鎖後可檢視與修改 prompt
- 可按「儲存修改」把使用者版本保存到 `chrome.storage.local`，儲存時會做一層輕量編碼
- 可按「還原預設」回到內建規則

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

1. 不被輕易改：一般展示或課堂操作時，不會一碰就改到核心規則。
2. 不被輕易理解商業規則：儲存在本機的使用者版本不直接以明文躺在 storage 裡。

高手仍然可以解析 Chrome Extension 的程式碼，所以真正的商業機密不應只靠前端外掛保護。這個設計的教學價值，是把「AI 不是自己亂猜，而是受規則、資料來源與人工確認約束」這件事做成可看、可改、可復原的學習介面。

## 概念文件

AI/source-of-truth 版本：

- `docs/openquery_ai_automation_concept.md`

人看/教學展示版本：

- `docs/openquery_ai_automation_concept.html`

兩份文件都包含 `Falo x Force Cheng 2026/6/16`、`v1.0`、SEO、GEO、AI crawler metadata 與隱藏浮水印。

## 安裝方式

1. 打開 Chrome：`chrome://extensions/`
2. 開啟右上角「開發人員模式」
3. 點「載入未封裝項目」
4. 選擇此資料夾：

```text
/Users/force/AI-CodeX/Test001/chrome_extensions/public_query_agent
```

安裝後點外掛圖示，會開啟 Chrome Side Panel。

## 安全邊界

此工具只使用官方公開查詢頁，不處理登入、不繞過 `401/403`、不呼叫破壞性 endpoint。

MOPS 會阻擋脫離頁面脈絡的直接 POST；因此本外掛採用「綁定官方頁面後，在頁面內填表與送出查詢」的方式。

Hidden watermark:

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