# iMBrace 學習，每一頁合併於單一檔案 ==================== index.md ==================== --- level: '0' track: - sell - build - deploy --- # 關於本課程 這門課程帶你認識 iMBrace：理解它、看它運作、在上面開發，並把它做好，提供英文、繁體中文與簡體中文。它與 SDK 文件並行：文件是參考資料，課程則是帶著截圖、一步一步走過這些內容的導覽路線。請在下方挑選適合你的路徑。 ## 下載 - [AI 程式碼工具的建置指南（.zip）](https://engineer.imbrace.co/learn/imbrace-build-guide-community.zip) - [整門課程，給 AI 工具讀取（llms-full.txt）](https://engineer.imbrace.co/zh-tw/learn/llms-full.txt) 合作夥伴套件（示範腳本、交付與部署指南、一個練習用組織）不提供下載，請向你的 iMBrace 聯絡人索取。 ## 挑選你的路徑 - [向客戶介紹 iMBrace](/zh-tw/learn/understand/overview.md) - 它是什麼、現在能做什麼，以及實際運作的平台導覽。 - [在 iMBrace 上開發](/zh-tw/learn/build-it/set-up-your-coding-tool.md) - 設定你的程式碼工具，然後建置一個能運作的小型退貨櫃台，並讓它等一個人做決定。 - [使用 AI 程式碼工具開發](/zh-tw/learn/build-guide.md) - 把建置指南交給你的工具，或提供整門課程合併成的單一檔案。 - **成為 iMBrace 合作夥伴** - 合作夥伴套件內含示範腳本、交付與部署指南，以及一個練習用組織。 ### 每條路徑上的所有頁面，依序排列 **向客戶介紹 iMBrace。** [iMBrace 是什麼](/zh-tw/learn/understand/overview.md)，接著 [iMBrace 現在能做什麼](/zh-tw/learn/understand/capability-truth-table.md)，接著 [平台導覽](/zh-tw/learn/see-it-work/platform-tour.md)，接著 [履歷篩選，從頭到尾](/zh-tw/learn/see-it-work/cv-screening.md)或 [銷售報價](/zh-tw/learn/see-it-work/sales-quoting.md)。 **在 iMBrace 上開發。** [設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md)，接著 [基本組成元件](/zh-tw/learn/build-it/building-blocks.md)，接著 [教學](/zh-tw/learn/build-it/vibe-coding-tutorial.md)，接著 [讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)，接著 [與 AI 程式碼工具協作](/zh-tw/learn/build-it/working-with-ai.md)，接著 [建置得好](/zh-tw/learn/build-it-well/index.md)。動手實作的教學約需一小時； 讓它等一個人做決定是第二次實作。 **使用 AI 程式碼工具開發。** 從 [AI 工具的建置指南](/zh-tw/learn/build-guide.md)開始。你的工具也可以讀取 [整門課程合併成的單一檔案](https://engineer.imbrace.co/zh-tw/learn/llms-full.txt)。 **成為 iMBrace 合作夥伴。** 合作夥伴套件另附示範腳本、交付與部署指南，以及一個練習用組織。請向你的 iMBrace 聯絡人索取。 ==================== understand/overview.md ==================== --- level: '0' track: - sell - build - deploy verified_on: 2026-09-29 --- # iMBrace 是什麼 iMBrace 是一套企業級 AI 平台。它為企業提供能根據自身核准知識回答問題的 AI 代理人、能讀取文件並將其轉換為結構化紀錄的軟體，以及能執行日常業務流程的工作流。企業可以完全在自有伺服器上執行，也可以在私有雲端或以 SaaS 方式執行。企業自行選擇資料存放的位置，以及由哪個 AI 模型讀取資料。 ## 聰明，也精準 iMBrace 讓理解力強的 AI 與精確的步驟相互搭配，使整個業務流程能夠從頭到尾可靠地執行。 - 代理人理解使用者的提問，並依據企業自身核准的知識回答。知識範圍內沒有的內容，代理人會直接說明。 - 工作流精確地完成工作：分派、檢查、計算，以及更新其他業務系統，每一次都以同樣的方式進行。 - 重要的決定由人來做：工作流會等待合適的人核准，然後自動接續執行。 兩者結合，執行的是真實的業務流程，而不只是對話。 ## 為什麼要治理 在企業系統內工作的 AI 代理人需要明確的控管。iMBrace 將這些控管內建於平台之中。 - 存取權限分層設計：依團隊區分，讓每個人只能看到自己所屬團隊的知識與資料；依角色區分，讓每個人的權限對應到他該管理或該使用的內容；在企業版安裝中，還能依紀錄中的個別欄位區分，讓同一張「數據表」（Data Board）對不同讀者顯示不同的詳細程度。 - 平台會記錄整個系統中的活動——登入、檔案上傳、頻道變更，以及數據表的變更——每一筆都有時間戳記，若是由某人執行，也會標明是誰做的。在企業版安裝中，這項記錄還會延伸到 AI 代理人的活動。 - 工作流可以在重要的決策點暫停，等待指定的核准人——需要的話可以等上數小時或數天。核准人在自己原本工作的地方做決定：一封附有「核准」與「拒絕」按鈕的電子郵件，每個按鈕都會開啟一個讓他們確認的頁面。單單打開連結，不會決定任何事。一旦他們確認，同一個工作流就會自動接續執行，完成原本的工作。是誰核准、核准了什麼、何時核准，都會一併記錄下來。 - 這些規則由平台本身的檢查機制強制執行，而不是靠輸入在提示詞裡的任何文字。 - 企業自行決定平台在哪裡執行、使用哪個 AI 模型，包括一個完全不離開自家機房的模型。 ## 各部分如何協同運作 客戶與員工透過自己已經在用的管道接觸平台：網頁即時聊天視窗、WhatsApp，或其他已連接的頻道。代理人依據企業核准的知識來回答問題。當有事情需要處理時，工作流會執行它，並視需要連接企業其他的業務系統。平台從文件中擷取的任何內容，或產生的任何紀錄，都會存放到一張結構化的數據表上——而這筆紀錄，正是讓答案或行動事後都能被查核的原因。一整套治理規則貫穿整個流程。 畫面：圖解：iMBrace 如何運作，從通訊頻道到代理人、工作流與數據表，統一於一層治理控管之下 *iMBrace 如何運作：通訊頻道連接代理人，並以核准的知識為後盾；工作流執行工作；結果落於數據表 - 全都在同一層治理控管之下。* 以上就是這個平台的整體樣貌。[iMBrace 現在能做什麼](/zh-tw/learn/understand/capability-truth-table.md) 依領域逐一列出細節，並附上頁面或畫面，讓你可以親自確認每一項能力。 ==================== understand/capability-truth-table.md ==================== --- level: '0' track: - sell - build - deploy verified_on: '2026-09-30' --- # iMBrace 現在能做什麼 以下每一列都是 iMBrace 現在就能運作的能力，都已對照真實頁面或產品本身確認過——不是計畫，也不是藍圖。凡標示「（企業版安裝）」的項目，代表該能力僅屬於這類安裝；其餘項目則一般皆可使用。版本與價格的問題，請洽詢你的 iMBrace 聯絡窗口。 ## 觸及客戶與員工 | 你可以做什麼 | 在哪裡查看 | |---|---| | 透過 WhatsApp、Facebook Messenger、Instagram、LINE、WeChat、電子郵件，或你自己網站上的網頁即時聊天視窗與客戶對話，所有訊息都整合在同一個共用收件匣中 | 產品：「對話」（Conversations） | | 每一則對話都會追蹤自己的狀態——線上、逾期、需要客服人員、待處理或已結案——讓你的團隊隨時掌握哪些對話需要回覆 | 產品：「對話」 | | 依團隊分派對話，可以採先到先服務模式，或讓團隊中的每個人都能自由加入對話 | 產品：「團隊管理」（Teams）、「對話」 | ## 代理人與知識 | 你可以做什麼 | 在哪裡查看 | |---|---| | 建立擁有自己的個性、語氣與核心任務的 AI 代理人，並提供參考資料供其回答問題——支援 PDF、Word、純文字、CSV 或 Excel 檔案 | 產品：「AI智能助手」（AgentIQ） | | 讓代理人直接使用組織既有的知識，不必重新上傳 | 產品：「AI智能助手」、「知識模組」（Knowledge） | | 將知識資料夾或「數據表」（Data Board）限定給特定團隊，讓只有那些團隊裡的人才能看到其中的內容 | 產品：「知識模組」 | | 在較長的來回對話中維持代理人的脈絡：它會記得同一場對話中先前的內容 | 產品：「AI智能助手」、進階設定 | | 設定一個協調型代理人，將任務的一部分交給一個或多個專門的子代理人處理 | 產品：建立你的 AI－協調器（Orchestrator） | | 在自動化的工作流中呼叫代理人或文件擷取步驟，讓 AI 步驟成為更大流程的一部分，而不是另開一個對話 | 產品：工作流－AI 代理人技能 | ## 文件 | 你可以做什麼 | 在哪裡查看 | |---|---| | 將 PDF 或圖片——發票、表單、收據、合約、名片等——轉換成結構化紀錄，使用的是能讀懂版面配置的模型，而非固定範本 | https://engineer.imbrace.co/zh-tw/sdk/document-ai | | 只需設定一次擷取邏輯，存成一個「文件模型」（Document Model），之後可套用在同類型的每一份文件上；版本紀錄會顯示它的每一次變更 | 產品：「文件模組」（DocIQ）、「文件模型」 | | 將擷取結果直接送到數據表，對應到你選擇的欄位，需要的話也能同時送到多張數據表 | 產品：「文件模組」 | | 告訴文件模組你的文件使用哪種語言，以提升擷取準確度，包括含有手寫內容的文件 | 產品：「文件模組」、「設置」（Settings） | | 將參考資料上傳到知識資料夾，支援多種格式——PDF、Word、PowerPoint、Excel、CSV、影片或圖片檔案 | 產品：「知識模組」 | | 限制哪些團隊可以使用特定的文件模型，做法與限制知識資料夾相同 | 產品：「文件模組」、「文件模型」 | ## 資料與工作流 | 你可以做什麼 | 在哪裡查看 | |---|---| | 在一張共用的數據表上維護結構化紀錄，讓每個工作流、代理人與使用者都能讀取與寫入 | 產品：「知識模組」、「數據表」（DataIQ） | | 依連接頻道收到的訊息、排程，或數據表紀錄的變更——新增、刪除，或指定欄位被更新——來啟動工作流 | 產品：工作流、「流程營運模組」（FlowOps） | | 透過預先建置的連接器，從工作流內部連接到外部系統——iMBrace 原生整合超過 100 種服務，從 CRM、試算表到工單系統都涵蓋在內 | 產品：「應用整合」（Integrations） | | 將連接器的憑證保存在組織自己的儲存區，與工作流本身分開存放，讓分享或匯出的工作流定義不會帶有任何金鑰 | https://engineer.imbrace.co/zh-tw/sdk/workflows | | 在重要的決策點暫停工作流，停在原處等待特定的人做出決定，對方回覆後，同一次執行就會接著往下走，並記錄是誰做了決定、決定了什麼，以及何時做的。若一直沒有人回覆，這次執行會維持暫停、清楚可見，也不會有任何東西送出去 | 產品：「流程營運模組」（FlowOps） | | 在對方原本工作的地方請他們決定：一封附有事實卡片與兩個按鈕（「核准」與「拒絕」）的電子郵件，每個按鈕都會開啟一個頁面，讓他們在頁面上按下「確認」。打開連結不會決定任何事，而且一旦有一個答案被確認，另一個按鈕就會失效 | 產品：「流程營運模組」（FlowOps），以及寄出的郵件卡片 | | 在答案出來之後把事情做完：核准後，完成的 PDF 與 Excel 文件會以電子郵件寄給提出請求的人；被拒絕時，會通知那個人，也不會有任何文件送出。本來就符合規則的請求則不需要核准，文件會直接寄出 | 產品：「流程營運模組」（FlowOps），以及提出請求的人的收件匣 | ## 存取與治理 | 你可以做什麼 | 在哪裡查看 | |---|---| | 將知識資料夾或數據表限定給特定團隊，讓每個人只能看到自己所屬的團隊 | 產品：「團隊管理」、「存取控制」（Access Control） | | 依團隊內的角色設定成員的權限——例如團隊管理員與代表的差別 | 產品：「團隊管理」 | | 將紀錄中的個別欄位限定給特定角色，讓同一張數據表能對不同的讀者顯示不同的詳細程度（企業版安裝） | 產品：「存取控制」 | | 回顧整個平台的活動紀錄——登入、檔案上傳、頻道變更，以及數據表的變更——每一筆都有時間戳記，若是由某人執行，也會標明是誰做的 | 產品：「審計記錄」（Audit Log） | | 將活動紀錄延伸到 AI 代理人的行動（企業版安裝） | 產品：「審計記錄」 | | 存取規則由平台本身的權限檢查機制強制執行，而不是靠寫在提示詞裡的任何文字 | 產品 | ## 執行環境 | 你可以做什麼 | 在哪裡查看 | |---|---| | 以代管服務的方式執行 iMBrace，跑在 iMBrace 自己的雲端上，完全不需要安裝任何東西 | https://engineer.imbrace.co/zh-tw/getting-started/setup | | 將 iMBrace 安裝在你自己的基礎設施上——單一的地端伺服器，或私有雲端部署——取代代管服務 | https://engineer.imbrace.co/zh-tw/install/kubernetes | | 選擇由哪個 AI 模型回答每個代理人的問題——可以使用系統預設，也可以連接並自行管理提供者，逐一模型設定 | 產品：「LLM 提供者」（LLM Providers） | ## 在其上開發 | 你可以做什麼 | 在哪裡查看 | |---|---| | 使用官方 SDK（TypeScript 或 Python）針對 iMBrace 進行開發 | https://engineer.imbrace.co/zh-tw/sdk/installation | | 透過一組網址與一把金鑰，將 AI 程式開發工具連接到正式運作中的組織——預設為唯讀，直到你逐一開啟寫入權限為止 | https://engineer.imbrace.co/zh-tw/mcp/overview | | 讓你的程式開發工具取得平台自身的架構地圖，使它第一次就能寫出正確的程式碼，而不必猜測方法名稱 | https://engineer.imbrace.co/llms.txt | | 從終端機管理數據表、代理人、工作流與文件擷取工作 | https://engineer.imbrace.co/zh-tw/cli/overview | ==================== see-it-work/platform-tour.md ==================== --- level: '1' track: - sell - build - deploy verified_on: 2026-09-29 --- # 平台導覽 這是一個 iMBrace 組織的側邊欄，依照畫面排列的順序逐一走過：應用程式、「分析模組」（InsightsIQ）、「知識模組」（Knowledge）、「行動模組」（Actions）、「治理控管模組」（Governance）與「設置」（Settings）。每個區域只做一次簡短停留——它是做什麼用的、打開後會看到什麼，以及那裡有什麼值得展示給客戶看。在第一次示範之前先讀過一遍，之後在帶別人走一遍平台時，把它當作檢查清單開著備用。 ## 應用程式 應用程式是與客戶或同仁的對話真正發生的地方。它會先打開「對話」（Conversations），這是一個共用收件匣，匯集每一則從已連接頻道進來的訊息，並附有依檢視方式與狀態篩選的標籤——線上、逾期、需要客服、待處理、已結案。不論訊息是從哪個頻道進來的，都會出現在同一份清單裡。可以向客戶展示一則對話即時進來的畫面，或篩選出逾期項目，證明沒有任何一則訊息被晾在一旁沒人回覆。 畫面：應用程式側邊欄，顯示對話收件匣與其狀態篩選 *1 「應用程式」（Applications）>「對話」（Conversations）。2 共用收件匣的「狀態」篩選。* ## 分析模組 分析模組是直接與代理人對話、觀察它如何處理一個問題的地方。它會先打開對話首頁：一個用來選擇要詢問哪一位代理人的選擇器，以及一個用來輸入問題的輸入框。輸入一個真實的問題，展示答案送達的過程——答案背後是組織自己核准的知識，如果答案不在其中，它也會直接說明。實際運作請見：[履歷篩選，從頭到尾](/zh-tw/learn/see-it-work/cv-screening.md)與[銷售報價](/zh-tw/learn/see-it-work/sales-quoting.md)。 畫面：分析模組的聊天畫面，含代理人選擇器與輸入框 *1 「分析模組」（InsightsIQ）。2 代理人選擇器。* ## 知識模組 知識模組保存組織所知道的一切：用來讀取文件的模型、用來存放結構化紀錄的數據表，以及代理人用來回答問題所依據的資料。 ## 文件模組（DocIQ） 文件模組是文件模型把一份非結構化檔案——發票、表單、履歷——轉換成結構化紀錄的地方。它會先打開「文件模型」（Document Models），這是一個已依類別整理好的模型庫，例如財務與會計、人力資源、業務與客戶，旁邊還有文件數據表與處理記錄。打開一個已經符合客戶自己文件格式的模型，展示它如何逐一欄位擷取出資料。 畫面：文件模組的文件模型分頁，含分類列 *1 「知識模組」（Knowledge）>「文件模組」（DocIQ）。2 一張文件模型卡片。* ## 數據表（DataIQ） 數據表是結構化紀錄真正存放的地方：一份由你自己設計列與具型別欄位的數據表。它會先打開數據表卡片，每張卡片顯示一個數據表的名稱，以及它存有多少筆紀錄。打開一個數據表，直接從表格上讀一筆真實的資料列——這一筆資料，正是工作流的步驟、代理人的技能，或文件模型的擷取結果，共同讀取與寫入的對象。 畫面：數據表卡片列表，顯示各數據表的紀錄筆數 *1 「知識模組」（Knowledge）>「數據表」（DataIQ）。2 一張數據表卡片。* 文件模組的文件模型，與 DataIQ 中的數據表，是每一個 iMBrace 建置成果都有的[五大基本組成元件](/zh-tw/learn/build-it/building-blocks.md)中的兩個；接下來的行動模組，則保存另外三個——代理人、工作流與頻道。 ## 通訊模組（CommsIQ） 通訊模組與文件模組、數據表並列，擁有自己的「全部」（All）分頁。 ## 知識庫（KB） 知識庫是參考資料直接上傳進來的地方——PDF、Word、PowerPoint、Excel、CSV、影片或圖片檔案——並整理成資料夾，讓代理人可以直接依據它回答，不必有人重新輸入一次內容。如果客戶自己的資料已經上傳，打開對應的資料夾，展示代理人的回答直接引用自其中的內容。 ## 行動模組 行動模組是另外三個元件所在的地方：負責對話的代理人、負責執行工作的工作流，以及負責來回傳遞訊息的頻道。 ## AI智能助手（AgentIQ） AI智能助手是建立與設定代理人的地方。它會先打開三個分頁——「市場」（Marketplace）、「我的 AI」（My AI）與「啟用中的 AI」（Active AI）——其中「啟用中的 AI」列出每一個已經在運作的代理人，各自有自己的卡片：Sales Quoting 代理人的卡片上寫著「把一句話寫成的請求，轉換成一份 Quillmoor Components 的報價單。」打開一個代理人的「行為設定」（Behavior Settings），捲到「功能」（Skills），就能準確看到它設定成會呼叫哪些工作流，每一個都是為特定工作打造並命名的。 畫面：AI智能助手的啟用中的 AI 分頁，列出組織的所有助手 *1 「行動模組」（Actions）>「AI智能助手」（AgentIQ）。2 Sales Quoting 助手的卡片。* ## 流程營運模組（FlowOps） 流程營運模組是建立並監看工作流的地方：一連串步驟，一經觸發就會自動依序執行——讀取數據表、進行運算、等待決策、發送訊息。它會直接打開目前正在執行的工作流清單。打開其中一個，指出它等待對的人做出決策的那個步驟，再展示一旦對方做出決策，它就會自動接著往下走、完成剩下的工作。關於這個決策實際在哪裡做出，請見：[人工核准](/zh-tw/learn/build-it-well/human-approval.md)。 畫面：流程營運模組的工作流清單 *1 「行動模組」（Actions）>「流程營運模組」（FlowOps）。2 工作流清單中的一列。* ## 連接模組（ConnectIQ） 連接模組以兩種方式把平台向外連接。它的「渠道設定」（Channels）分頁列出一個人實際聯繫到代理人的管道——一個網頁小工具（Web Widget）（使用中、允許上傳檔案），還有可以新增 LINE、Facebook、Instagram、WeChat 與 WhatsApp 的項目。它的 MCP 分頁，則是 AI 程式設計工具用來直接連接、查看並在一個組織上建置所需要的位址與金鑰——完整指南在 [engineer.imbrace.co/mcp/overview](https://engineer.imbrace.co/zh-tw/mcp/overview/)。先展示頻道設定，也就是客戶自己的客戶已經在用的應用程式，再把 MCP 留給技術背景的聽眾。 畫面：連接模組的渠道設定分頁，列出網頁小工具與各通訊頻道 *1 「行動模組」（Actions）>「連接模組」（ConnectIQ）。2 「網頁小工具」通訊頻道。* ## 治理控管模組 治理控管模組是平台自己保存的紀錄，記下發生過什麼事，不需要任何人特地要求。它的首頁分頁「審計記錄」（Audit Log），為整個組織內的活動加上時間戳記並歸屬到相關對象——登入、檔案上傳、頻道變更、數據表的變更——所以事後都能查核；旁邊還有硬體指標、Token 用量與對話記錄（AI Tracing）。打開審計記錄，展示一筆真實的紀錄：改了什麼、是誰改的，以及什麼時候改的。 畫面：治理控管模組的審計記錄分頁，含時間戳的活動紀錄 *1 「治理控管模組」（Governance）。2 審計記錄的「類型」欄。* ## 設置 就示範而言，設置指的是「團隊管理」（Teams）與「組織成員」（Org Members）。團隊管理——分為「所有團隊」（All Teams）與「我的團隊」（My Teams）——是管理組織存取權限、並設定成員角色的地方，一位團隊管理員（Team Admin）與一位代表（Representative），各自只看得到自己所屬的團隊；組織成員則列出組成這個組織的所有人。打開團隊管理，展示一個人的存取權限如何對應到他實際負責的工作。 畫面：設置的團隊管理分頁，顯示所有團隊與我的團隊 *1 「設置」（Settings）。2 「團隊管理」（Teams）分頁。* 以上就是側邊欄的導覽路徑——與客戶一起打開一次，每個區域都已經有東西可以展示給他們看。 ==================== see-it-work/cv-screening.md ==================== --- level: '1' track: - sell - build - deploy verified_on: 2026-09-29 --- # 履歷篩選，從頭到尾 Lumenvale Software 的招募人員手上有一份職缺說明和十份履歷要公平比較，卻沒有簡單的方法能對照紀錄，檢查入圍名單背後的判斷依據。iMBrace 會把職缺說明轉換成一組經過確認的篩選條件，依這些條件為每份履歷評分，並以履歷本身的文字作為佐證，最後交回一份經過排序、招募人員既能質疑、也能信任的入圍名單。 ## 整個流程，一步一步來 以下是完整的故事，從頭到尾： 1. 招募人員手上有一份職缺說明，以及十份應徵客戶成功經理職位的履歷。 2. 「文件模組」（DocIQ）是 iMBrace 的文件閱讀工具，會讀取這份職缺說明，並找出其中要求的重點。 畫面：一筆職缺說明紀錄開啟在數據表中，需求條列被擷取為欄位 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　職缺說明的需求條列，被讀取為「Requirement Lines」欄位。* 3. 一個名為 Criteria Architect 的代理人，會根據這些要求提出一組篩選條件，每一項都會標示出它的依據來源。 4. 招募人員會在「數據表」（DataIQ）上檢視這些條件，勾選要採用的項目，然後按下「儲存」（Save）。 畫面：條件清單數據表，每一列的核准欄位都已打勾 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　每一項條件都已核准，在「approved」欄位打勾。* 5. 接著輸入這十份履歷。每一份都會成為獨立的一筆紀錄，候選人的完整工作經歷與學歷都會被讀出來。 畫面：一份履歷寫入為數據表中的獨立紀錄，身分欄位與工作經歷都讀取為結構化欄位 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　一位應徵者的紀錄，包括「Current / Most Recent Title」等欄位。3　同一筆紀錄的「Work History」欄位。* 6. 第二個代理人 Evidence Assessor，會依核准後的條件為每份履歷評分，並引用履歷中支持每項分數的確切文字。 畫面：條件證據數據表，顯示某候選人一項評分背後引用的履歷原文 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　一項評分背後、引自履歷的原文，在「quote_given」欄位。* 7. 分數會顯示在 Candidate Scorecard 上，依符合程度由高到低排序。 畫面：候選人評分卡數據表，每位候選人都有一個符合百分比 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　每位候選人的符合百分比，在「fit_pct」欄位。* 8. 招募人員會在「分析模組」（InsightsIQ）——iMBrace 這款會附上出處作答的對話工具——中，向第三個代理人 Screening Analyst 詢問入圍名單，以及某位候選人為何排在這個名次。回答會附上背後引用的履歷原文。 畫面：InsightsIQ 的回覆：通過符合度門檻的候選人入圍名單 *1　側邊欄的「分析模組」（InsightsIQ）。2　Screening Analyst 的入圍名單回覆。* 畫面：InsightsIQ 的回覆，說明某候選人的排名與其履歷缺口 *1　側邊欄的「分析模組」（InsightsIQ）。2　Screening Analyst 說明某候選人排名原因的回覆。* ## 人在哪裡做決定 招募人員會在任何一份履歷被評分之前，先核准這些條件：逐一勾選，再於 Criteria 數據表上按下「儲存」（Save）。這個步驟放在評分開始之前，確保每份履歷都是依招募人員真正同意過的標準來衡量，而不是代理人自行認定的標準。 ## 不用寫程式就能調整的內容 履歷評分所依據的條件，以及候選人需要達到的等級，都是數據表上的一列資料。 | 資料列 | 控制的內容 | |---|---| | Criteria 數據表上的每一項條件 | 履歷要拿來比對的項目——必要條件、加分條件，或警示條件——以及招募人員是否已核准這一項。 | | Level Expectations 數據表上的每一行 | 在特定職涯路線下，達到某個等級代表什麼樣子，讓一項條件可以指向某個等級，而不是一條固定的規則。 | 新增、編輯或下架一列資料，下一份被評分的履歷就會套用這項變更——不需要重新建置。 ## 動手試試看 如果你是合作夥伴，你的練習組織一開始就已經安裝好履歷篩選，並使用 Lumenvale Software 的職缺說明與履歷；你的合作夥伴工具包中的示範腳本則會帶你完整跑一遍實際操作，從核准條件一路到產生入圍名單。其他人則可以請自己的 iMBrace 聯絡窗口，在屬於自己的組織上展示它的運作情形。 ==================== see-it-work/sales-quoting.md ==================== --- level: '1' track: - sell - build - deploy verified_on: 2026-10-03 --- # 銷售報價 Quillmoor Components 的業務團隊依照一份龐大的目錄，為工業用緊固件與配件報價，任何讓毛利率低於 Quillmoor 底線的折扣，都需要先經過主管點頭，才能送出。iMBrace 能把一句白話的請求，轉換成一份已定價的報價單。當毛利率低於底線時，工作會停下來等主管；主管從一封電子郵件回覆，同一個工作就會接著往下走，把完成的文件寄給提出請求的人。 ## 整個流程，一步一步來 以下是完整的故事，從頭到尾： 1. 業務人員用白話向這個名為 Sales Quoting 的代理人提出報價請求：說明客戶、產品與數量。他們也可以附上自己的電子郵件地址，完成的文件就會寄到那裡；沒有附上時，文件會寄給業務窗口。 2. 這個代理人會讀取 SQ Catalogue 和 SQ Pricing Rules 這兩張「數據表」（DataIQ），裡面存放 Quillmoor 的產品資料與定價規則。 畫面：SQ Catalogue 數據表列出 Quillmoor 的產品，含 SKU *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　「SQ Catalogue」數據表，Quillmoor 的產品與 SKU。* 畫面：SQ Pricing Rules 數據表，含 approval_threshold 折扣規則 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　折扣規則列，在「approval_threshold」欄位。* 3. 它會算出報價內容，並逐行寫入 SQ Quotations 和 SQ Quotation Lines 這兩張數據表。 畫面：InsightsIQ 的回覆：一份逐行定價、含總額的新報價單 *1　側邊欄的「分析模組」（InsightsIQ）。2　Sales Quoting 代理人的回覆：逐行定價的新報價單。* 4. 接著由 iMBrace 自己，根據已寫入的各行明細檢查毛利率——不是聽代理人怎麼說。毛利率達到底線的報價單不需要核准：它的文件會自動製作完成，並以電子郵件寄給提出請求的人。 5. 毛利率低於底線的報價單則會等待。它的狀態顯示為等待核准，背後的工作流（iMBrace 中一經觸發就會自行執行各個步驟的引擎）會在決策點暫停。在「流程營運模組」（FlowOps）裡，這份報價單的執行會標示為 Paused（已暫停）：它沒有失敗，也還沒有完成，而是停在原處，等一個人回覆。 畫面：SQ Quotations 數據表，一列報價單的狀態為 awaiting approval *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　報價單自身的狀態：awaiting approval（待核准）。* 畫面：流程營運模組的執行清單，這份報價單的執行標示為 Paused（已暫停） *1　「行動模組」（Actions）>「流程營運模組」（FlowOps）。2　這份報價單的執行，標示為 Paused（已暫停）：它正在等主管處理。* 6. 主管會收到一封電子郵件。那是一張卡片，載明做決定所需的一切——客戶、品項、折扣、毛利率、總額與政策底線——並附有兩個按鈕：「核准」與「拒絕」。 畫面：主管收到的核准郵件：一張卡片列出客戶、折扣、毛利率、總額與政策底線，並附有「核准」與「拒絕」按鈕 *1　卡片：客戶、折扣、毛利率、總額與政策底線。2　「核准」與「拒絕」按鈕。* 7. 每個按鈕都會開啟一個頁面，顯示所選的結果。單單打開頁面，不會決定任何事；只有按下頁面上的「確認」，才會記錄這項決定。一旦有一個答案被確認，另一個按鈕就會失效，所以一份報價單只會有一個答案。 畫面：從「核准」按鈕開啟的確認頁面：顯示報價單、客戶與總額，以及一個「確認」按鈕 *1　所選的結果，以及它適用的報價單。2　「確認」按鈕：按下之前，不會決定任何事。* 畫面：按下「確認」之後顯示的頁面：報價單已核准，文件正在寄出 *按下「確認」之後的頁面：報價單已核准，文件正在寄給提出請求的人。* 8. 同一次執行會從停下來的地方接續下去。平台會記錄是誰核准、何時核准——也就是 Approved By 與 Approved At，這兩欄代理人無法寫入——接著製作 PDF 與 Excel 檔案，並以電子郵件寄給提出請求的人；如果一開始沒有附上地址，則寄給業務窗口。 畫面：流程營運模組的執行清單，同一次執行現在標示為 Succeeded（成功） *1　「行動模組」（Actions）>「流程營運模組」（FlowOps）。2　同一次執行，現在標示為 Succeeded（成功）：它從等待的地方接續下去，並且完成。* 畫面：SQ Quotations 數據表，該列狀態為 approved，且 Approved By 與 Approved At 已填入 *1　「知識模組」（Knowledge）>「數據表」（DataIQ）。2　這份報價單的資料列：狀態為 approved（已核准），Approved By 與 Approved At 已填入。* 畫面：提出請求的人收到的郵件：報價單已核准、可以寄送，附有一份 PDF 與一份 Excel 檔案 *1　告知提出請求的人，報價單已核准、可以寄送的郵件。2　兩個附件：PDF 與 Excel 檔案。* 如果主管改按「拒絕」，這項拒絕會被記錄下來，不會製作任何文件，並且會通知提出請求的人。 ## 人在哪裡做決定 毛利率低於底線的報價單，必須等主管決定後，才能送出任何東西。它之所以停在那裡，是因為規則本身不允許的折扣，理應永遠由人來決定——而且每一次都由 iMBrace 本身以同樣的方式檢查，而不是靠記憶。 主管在自己原本工作的地方做決定：收件匣，事實與兩個按鈕就在眼前。在他們回覆之前，不會有任何東西送出。如果一直沒有人回覆，報價單會維持暫停、清楚可見——在它自己的數據表上，也在「流程營運模組」裡——也不會寄出任何文件。等他們回覆時，同一次執行會繼續下去——不是重新開始——並把事情做完。 這就是這個使用案例要展示的：iMBrace 在人做決定的期間，替這次執行保留它的進度，等對方回覆再接續下去。這次執行接觸的，是人、訊息與文件——一位主管、一封電子郵件，以及一份完成的報價單。 ## 不用寫程式就能調整的內容 報價單所依據的檢查規則，以及 Quillmoor 販售的所有品項，都是數據表上的一列資料。 | 資料列 | 控制的內容 | |---|---| | SQ Pricing Rules 數據表上的每一條規則 | Quillmoor 期望的毛利率，以及低於多少就必須由主管核准的毛利率底線。 | | SQ Catalogue 數據表上的每一項產品 | Quillmoor 販售的品項，以及對應的價格。 | | SQ Terms 數據表上的每一行 | 每份報價上都會出現的文字，例如有效期限、交貨與付款條件。 | 更改一列資料，下一份寫出的報價就會套用這項更新——不需要重新建置。 ## 動手試試看 如果你是合作夥伴，你的練習組織一開始就已經安裝好 Sales Quoting，並使用 Quillmoor Components 的目錄與定價規則；你的合作夥伴工具包中的示範腳本則會帶你完整跑一遍實際操作，從第一次請求，經過主管透過電子郵件核准，到提出請求的人收件匣裡那份完成的報價單。其他人則可以請自己的 iMBrace 聯絡窗口，在屬於自己的組織上展示它的運作情形。 ==================== build-it/index.md ==================== --- level: '2' track: - build --- # 建置 課程前面幾個級別說明了 iMBrace 是什麼，並展示一個使用案例從頭到尾的運作方式。這個級別則換你親自建置一個。 ## 這個級別能讓你做到什麼 完成後，你就能用自己既有的任何 AI 程式碼工具，在測試組織上建置一個能運作的小型退貨櫃台，並讓它等一個人做決定。不需要任何人交給你原始碼——你只需要一個測試組織、一把金鑰，以及透過 MCP 連接好的程式碼工具。 - [設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md)——測試組織與金鑰，以及將你的程式碼工具連接到該組織。請先完成這一步。 - [Vibe coding on iMBrace：動手建置](/zh-tw/learn/build-it/vibe-coding-tutorial.md)——書面教學。請依順序操作；它的設計是在真實的測試組織上，從頭到尾完整走過一遍。 - [讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)——第二次實作，從已經完成的櫃台開始，讓它以電子郵件詢問一個人，並在向顧客承諾任何事之前等候答覆。 - [與 AI 程式碼工具協作](/zh-tw/learn/build-it/working-with-ai.md)——確保你的工具所建置的成果值得信賴的原則與防護措施。 ## 開始之前 - 一個測試組織與一把 API 金鑰。絕不要使用正式環境的金鑰。 - 任何能維持 MCP 連線並讀取文字檔的 AI 程式碼工具。這份教學刻意不指名特定工具——你目前使用的任何一種都適用。 - 教學課程大約一小時。讓它等一個人做決定是第二次實作，需要兩個你能讀取的電子郵件地址。 ## 完成這個級別之後 第 3 級「建置得好」，是這個頁面所教的習慣背後的方法：為什麼每一項都重要、少了它會是什麼樣子，以及如何在客戶發現之前先看出差異。第 2 級讓你建置出一個能運作的代理人；第 3 級則決定它是否值得交付上線。 ==================== build-it/set-up-your-coding-tool.md ==================== --- level: '2' track: - build verified_on: 2026-09-29 --- # 設定你的程式碼工具 五個步驟，大約十五分鐘。完成後，你的 AI 程式碼工具就能看到測試組織中已有的內容，並依據 SDK 撰寫程式碼，不必用猜的。 **方向在這裡，事實在那裡。** SDK、CLI 與 MCP 的文件放在 [engineer.imbrace.co](https://engineer.imbrace.co/zh-tw/)，並依它自己的節奏更新。本頁只為每個步驟指出該讀哪一頁，不複製任何內容，因為複製來的參考資料會過時，而過時的參考資料比沒有還糟。 *最後一次核對網站的時間：2026 年 9 月 23 日。* ## 1. 測試組織與 API 金鑰 一律在測試組織中建置，絕不在正式環境中建置。把 API 金鑰當成組織自己的密碼來看待：它會以所屬角色的完整權限行動。正式環境的金鑰絕不能放進程式碼工具、測試執行或建置管線中。 測試組織可以架設在 iMBrace 的雲端上，也可以架設在你自己的安裝環境中——無論是你自己的伺服器，或是私有雲。負責維運你安裝環境的人可以建立一個測試組織。 如何從儀表板產生金鑰：請見 [API 金鑰指南](https://engineer.imbrace.co/zh-tw/guides/api-key/)。 畫面：設置的建立外部權杖分頁，含到期欄位與建立權杖按鈕 *1 「設置」（Settings）>「建立外部權杖」（Generate External Token）分頁。2 「建立權杖」按鈕。* ## 2. 安裝 SDK 並設定憑證 請照著文件的[設定指南](https://engineer.imbrace.co/zh-tw/getting-started/setup/)做：它會說明如何安裝 SDK、設定憑證，並把用戶端指向你的組織。把金鑰放進一個絕不提交的 `.env` 檔案中，並且只給你的程式碼工具變數名稱，不要給實際的值：貼進與程式碼工具對話中的正式金鑰，就是一把你不再能掌控的金鑰。 ## 3. 將你的程式碼工具連接到組織 平台的閘道搭載了一個 Model Context Protocol（MCP）伺服器，因此不需要安裝或執行任何東西。你只要把伺服器位址與金鑰交給你的工具，它就能看到該金鑰所屬角色允許的範圍，不多也不少——而且在你加入寫入權限之前，只能看到其中可讀的部分（詳見下文）。 各工具個別的設定步驟都在 [MCP 頁面](https://engineer.imbrace.co/zh-tw/mcp/overview/)上。請直接照那裡的步驟做，而不要用複製下來的版本，因為位址與旗標由該網站決定，隨時可能變動。如果你比較想執行本機伺服器，[CLI](https://engineer.imbrace.co/zh-tw/cli/overview/)也做得到。 這個連線涵蓋的範圍： - **在你加入寫入權限之前，它是唯讀的。** 工具一開始只能查看，無法變更任何東西。MCP 頁面上有加入「建立與更新」的旗標，也有加入「刪除」的旗標。請只在測試組織中使用它們。 - **代理人與檔案上傳則要透過 SDK**，或平台自己的畫面進行。 - **能否使用取決於你的安裝環境與版本。** 負責維運你安裝環境的人可以確認是否已啟用。若尚未啟用，你的工具就改用 SDK 或 CLI 運作。 連線就緒後，你的工具就同時擁有兩邊的資訊：這份指南回答「這應該怎麼建置」，而組織本身回答「這裡現在有什麼」以及「那個工作流上一次執行做了什麼」。 ## 4. 把 SDK 自己的地圖交給你的工具 當你的工具依據 SDK 撰寫程式碼時，它應該去抓取網站的 [llms.txt](https://engineer.imbrace.co/llms.txt)，並讀取它指向的頁面，而不是憑記憶作答。網站的 [vibe coding 指南](https://engineer.imbrace.co/zh-tw/guides/vibe-coding/)說明了在每一種工具中要如何把它交出去。 如果你的機器連不到這個網站——例如處在一個隔離的網路環境中——你所安裝的 SDK 本身就帶有每個方法的說明：TypeScript 套件裡有型別定義，Python 套件裡則有可讀的原始碼。你的工具可以改讀這些內容。不論哪一種情況，它都絕不能憑猜測寫出方法名稱。 ## 5. 驗證設定是否正確 請你的工具做兩件事，然後自己親自檢查兩者的結果： 1. 「列出這個組織中的 board。」它應該透過 MCP 連線來回答。在一個全新的組織上，空清單就是正確答案，不是失敗。 2. 「發出一次唯讀的 SDK 呼叫來列出 board，並把輸出結果顯示給我看。」透過 SDK 應該會拿到同一份清單。 如果這兩個結果都與你在平台上看到的一致，就表示你已經設定完成。只要有一項不一致，就代表是憑證或連線出了問題；請先在這裡把它排除，再開始建置任何東西。 ## 接下來 [教學課程](/zh-tw/learn/build-it/vibe-coding-tutorial.md)會帶你和你的工具一步一步建置出一個能運作的小型代理人。[與 AI 程式碼工具協作](/zh-tw/learn/build-it/working-with-ai.md)則說明要抱持什麼樣的態度，才能讓它建置出來的東西值得信任。 ==================== build-it/vibe-coding-tutorial.md ==================== --- level: '2' track: - build verified_on: 2026-09-30 --- # Vibe coding on iMBrace：動手建置 這是課程的第 2 級：動手建置。前面的級別會示範一個完整運作的使用案例；這一頁則換你自己動手建置一個。 完成後，你會在自己的測試組織中，擁有一個能運作的小型退貨櫃台：兩張數據表、一條任何人都能編輯的退款規則、一個計算步驟，以及一位能在對話中受理退貨的助理。它刻意做得很小，因為重點不在這個櫃台本身，而在於四個習慣——這些習慣能讓你在 iMBrace 上建置的任何東西都值得信任，第 3 級（建置得好）會深入介紹。下一課[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)會以這個櫃台為基礎，加上第五個習慣：在向顧客承諾任何事之前，先由一個人做決定。 ## 你將建置的內容 想像一家虛構公司 Harbor Bicycle Co.，在網路上銷售並維修自行車。你要為它建置退貨櫃台。當顧客寫信要求退貨時，這個櫃台應該要： 1. 把這筆申請記錄成「數據表」（board）上的一列，而不是留在聊天紀錄裡。 2. 依照 Harbor 任何人都能編輯的規則算出退款金額，而不是靠模型自己做運算。 3. 讓一位助理在對話中受理退貨：它會記錄這筆退貨，不說出任何退款金額，也不做任何承諾——因為還沒有人做出決定。 櫃台刻意停在這裡。Decision、Decided by 和 Decided at 三個欄位會保持空白：它們是[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)在有人答覆電子郵件時填入的紀錄——絕不是靠在儲存格裡打字。 這裡的一切都不是 Harbor Bicycle Co. 的真實系統——這家公司並不存在。在把成果展示給任何人看之前，記得把公司、商品和規則換成你自己的內容。 ## 你需要準備的東西 - 一個測試組織和一組 API 金鑰。如果你還沒有，[API 金鑰指南](https://engineer.imbrace.co/zh-tw/guides/api-key/) 說明了如何從儀表板產生金鑰。這裡請使用測試組織的金鑰——絕不要使用正式環境的金鑰。 - 一個透過 MCP 連接到該組織的 AI 程式碼工具，讓它能直接看到你的數據表和工作流，而不是用猜的。這一頁不指定特定工具；任何能建立 MCP 連線、又能讀取文字檔的程式碼助理都適用。[MCP 指南](https://engineer.imbrace.co/zh-tw/mcp/overview/) 有你所用工具的確切連線步驟——請先完成連線，再開始下面的步驟 1。如果你的安裝環境未啟用 MCP，[設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md) 說明了改用 SDK 的做法。 - 如果你的工具偏好直接寫 SDK 程式碼，而不是直接呼叫平台，請安裝你所用語言的 SDK： ```bash npm install @imbrace/sdk ``` ```bash pip install imbrace ``` 不論哪一種方式，你的工具最後都需要兩個環境變數：`IMBRACE_API_KEY` 和 `IMBRACE_ORGANIZATION_ID`。把它們放在本機的 `.env` 檔案中，絕不提交到任何地方；如果可以只把變數名稱交給程式碼工具，就不要把實際金鑰貼進與它的對話裡。 - 大約一小時。大部分時間花在閱讀平台回傳給你的內容——這正是這一整頁想培養的習慣。 這一頁會用到幾個詞：**「數據表」**是你自己定義的結構化表格——由列與具型別的欄組成，就像一份輕量版的 CRM 表。**「工作流」（也稱為 flow）**是一經觸發就會自動依序執行的一連串步驟。**「原生步驟」**是平台內建的現成步驟——不必自己寫、不必自己架設，也沒有自己的金鑰要管理。**「代理人」**則是使用者或頻道會與之對話的介面；產品在畫面上把代理人列在**「AI智能助手」**（AgentIQ）選單之下。 ## 操作步驟 ### 1. 動手之前先看一看 先別急著打開編輯器，讓你的程式碼工具先確認目前已經有哪些東西存在。 **你輸入的內容**大致如下： > 在我們動手之前：這個組織裡目前已經有哪些數據表？另外，請在平台的原生工作流步驟目錄中，搜尋任何與寄送和讀取電子郵件相關的步驟。 **你應該會看到**：在全新的測試組織中，數據表清單是空的——這是正常現象，不是失敗。如果這個組織原本就已經有其他工作內容，這次檢查看到的會是其他既有的數據表——這也沒關係；等你在步驟 2 建立好自己的數據表之後，依名稱到那裡尋找它就好。不論是哪一種情況，你也都會看到一小份電子郵件相關原生步驟的清單，旁邊可能還會列出你沒問到的其他頻道。把這份清單讀過一遍。這是第一個習慣：在考慮自己動手寫之前，先找出平台已經內建的步驟。工具從零寫出來的步驟，會讓你多一組要保管的憑證、多一段要維護的程式碼；原生步驟則兩者都不用。這份清單上的電子郵件步驟，正是[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)會用到的。 ### 2. 建立用來存放退貨申請的數據表 **你輸入的內容**： > 建立一個名為 Return Requests 的數據表，包含以下欄位：Customer name、Order reference、Item、Condition、Price、Refund amount、Decision、Decided by、Decided at。 **你應該會看到**：組織中出現一個新的數據表，有這九個欄位，但還沒有任何列。請到平台裡打開它，親眼確認欄位名稱與型別——不要只相信工具對自己做了什麼的摘要說明。最後三個欄位 Decision、Decided by 和 Decided at，是一個人的答覆所留下的紀錄：這一課不會填入它們，[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)才會。 如果你的工具說它無法建立任何東西，代表它的 MCP 連線是唯讀的——這是預設值。請依照 MCP 頁面的說明加入寫入權限（在連線位址上加一個旗標），而且務必只在測試組織上這麼做。 ### 3. 新增兩筆測試資料列 請使用合成資料。就算是在測試組織中，也絕不使用真實的顧客或訂單資訊。 **你輸入的內容**： > 在 Return Requests 新增兩列資料，顧客姓名和訂單編號請用明顯是假的內容。第一列：一頂未拆封的安全帽，價格 45。第二列：一個用過的自行車鎖，價格 28。Refund amount、Decision、Decided by 和 Decided at 欄位先留空。 **你應該會看到**：兩列資料，Condition 分別是「unopened」和「used」，Price 已經填好，最後四個欄位是空的。 畫面：Return Requests 數據表已開啟，顯示欄位與兩筆資料列 *1「知識模組」（Knowledge）>「數據表」（DataIQ）。2 Return Requests 數據表的欄位與資料列。* ### 4. 把退款規則放在有人能修改的地方，而不是寫進一句話裡 這是第二個習慣，也是這一頁最重要的一個。直接在代理人的指示裡寫「未拆封全額退款，用過的退一半」會更快，但請不要這麼做。寫進代理人指示裡的規則，除非有人去編輯這個代理人，否則無法修改，也無法向顧客引述，事後更無法稽核。而以資料列形式存在的規則，這三件事都做得到。 **你輸入的內容**： > 建立第二個數據表，名為 Refund Rules，包含兩個欄位：Condition 和 Refund percent。新增兩列資料：unopened、100；used、50。 **你應該會看到**：一個兩列兩欄的數據表。Harbor Bicycle Co. 的任何人都能打開它，把 50 改成 60，完全不必動到工作流或代理人。 畫面：Refund Rules 數據表，任何人都能編輯的兩筆規則 *1「知識模組」（Knowledge）>「數據表」（DataIQ）。2 Refund Rules 數據表的兩筆資料列。* ### 5. 建立工作流，把運算交給一個小步驟處理 **你輸入的內容**： > 在 Return Requests 這個數據表上建立一個名為 Calculate refund amount 的工作流，只要有一列被新增或修改就會執行。它應該：讀取該列的 Condition，到 Refund Rules 上查出對應的那一列，用一個單純的計算步驟把 Price 乘上 Refund percent，再把結果寫進 Refund amount。數據表的讀取和寫入請使用原生步驟。只有乘法運算本身需要你自己寫一個步驟，而且要保持單純——它只接收兩個數字、回傳一個數字，不碰其他任何東西。這個步驟裡不能有網路呼叫，也不能有憑證。 **你應該會看到**：一個可以在平台自己的編輯器裡從頭讀到尾、完全不必打開任何程式碼的工作流。裡面大部分步驟都是原生步驟，只有一個是你的工具寫的簡短計算步驟，而且短到十秒內就能讀完。如果你的工具有提供測試執行選項，就手動執行一次，確認未拆封安全帽的 Refund amount 是 45，用過的自行車鎖是 14。 畫面：Calculate refund amount 工作流：讀取資料表、計算步驟與寫回資料表，從上到下 *1「Find the matching...」查找 Refund Rules 上符合的資料列（原生步驟）。2「Calculate refund (...)」唯一一行手寫的計算步驟。3「Write Refund amo...」把結果寫回資料列（原生步驟）。* 這是第三個習慣：模型很擅長判斷該套用哪一條規則，但不適合被信任在無人監督、每一次都要在壓力下默默算對乘法。把運算交給一個計算步驟去做。讓模型負責判斷，讓程式碼負責計算。 ### 6. 建立代理人 代理人可以透過 SDK 的 AI Agent 方法建立（網站上有相關說明），也可以在平台的 AI智能助手畫面中建立，這個步驟會用到其中一種方式。不論哪一種，你的工具都可以幫你寫好代理人的指示。 **你輸入的內容**： > 首先建立一個名為 Log return request 的工作流，讓代理人可以把它當成工具呼叫。這個工作流接收 Customer name、Order reference、Item、Condition 和 Price，在 Return Requests 上建立一列只包含這五個值的資料，不寫入其他任何內容。接著建立一個名為 Return Desk Assistant 的代理人，只給它這一個工具——而不是整個數據表本身。它的工作是：當顧客描述想退貨的商品時，用這個工具記錄下來，並回覆對方申請正在審核中。它絕不能說出退款金額，也絕不能做出任何承諾——因為人還沒有做出決定。 畫面：AI智能助手的代理清單，Return Desk Assistant 卡片 *1「行動模組」（Actions）>「AI智能助手」（AgentIQ）。2 Return Desk Assistant 代理卡片。* 為什麼給工具而不是給整個數據表：如果代理人拿到整個數據表的存取權，它就能寫入任何欄位，包括 Decision——等於能自己核准自己的申請。工具則只能寫入顧客提供的那五個欄位，所以決定權留在人的手上（下一課會建置一個人如何做決定）。這是第四個習慣：只給代理人一個範圍很窄的工具，對應它必須做的那一件事。 還有一點值得寫進代理人自己的指示裡：Refund Rules 是以精確比對的方式查找，所以要告訴代理人在填寫 Condition 時，使用規則本身的那兩個詞——「unopened」或「used」——絕不要用顧客自己的說法，也不要翻譯它。凡是工作流會以精確比對方式查找資料列的數據表，只要是由能理解自然語言的代理人負責寫入，都需要同樣的細心。 **你應該會看到**：對新建立的代理人說類似「我想退貨，訂單 HB-2044，一頂還沒拆封的安全帽。我叫 Morgan Ellery，訂單金額是 39」，就會在 Return Requests 上產生一列填好這些細節的資料，並得到類似「你的退貨申請已經記錄，正由團隊審核中」的回覆——沒有金額、沒有承諾。幾秒鐘之後，那一列的 Refund amount 會自動填入：未拆封安全帽是 39。目前還沒有人審核這筆申請；[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)會加上負責審核的人。如果你的工具草擬的指示讓代理人自己猜一個退款數字，這裡就該抓出來：把指示退回去，要求把金額從代理人能說的內容裡拿掉。接著請它自己核准這筆申請：它應該做不到，因為它的工具裡沒有任何東西能寫入 Decision。 畫面：Return Desk Assistant 的回覆：已記錄並交由審核，沒有金額也沒有承諾 *1「分析模組」（InsightsIQ）。2 AI智能助手的回覆沒有提到金額，也沒有任何承諾。* ## 如何確認它真的可行 不要把程式碼工具對自己做了什麼的摘要說明當成證據。一段聽起來合理、描述建置成功的說法很容易寫出來，也很容易被誤認為真的成功——請親自去看。 - 打開 Return Requests。兩列資料的 Refund amount 都應該正確：45 和 14。兩列的 Decision、Decided by 和 Decided at 都是空的。 - 打開 Calculate refund amount 的執行紀錄，讀取每次執行的實際狀態，而不是摘要說明：每次執行都顯示為已完成。 - 用一筆新編的退貨案例去跟 Return Desk Assistant 對話。確認出現了一列新資料，它的 Refund amount 幾秒鐘後會自動填入，而且代理人的回覆沒有任何金額、也沒有任何承諾。 - 請這個助理核准一筆申請。確認 Decision 仍然是空的：代理人沒有辦法寫入這個欄位。 如果上面任何一項不成立，這其實比一個看起來沒問題、實際上卻不行的建置更有價值。修好失敗的那一項，然後再檢查一次。 ## 接下來可以做的事 - 接著進行[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)，這是第二次實作。它從這個櫃台開始，讓它在向顧客承諾任何事之前，先以電子郵件詢問一個人。 - 試著加入第二種 Condition——例如商品退回時少了包裝盒——並新增第二列規則。確認你不需要動到工作流或代理人，就能改變退款比例。 - 閱讀第 3 級「建置得好」，了解這些習慣背後更完整的方法——它會說明是什麼讓像這樣的建置，在交給真實顧客而不只是測試組織時，依然禁得起考驗。 - 關於 SDK、CLI 或 MCP 連線本身的任何內容，[engineer.imbrace.co](https://engineer.imbrace.co/zh-tw/) 是保持最新的權威來源——這一頁會比那裡更快過時。[設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md) 有完整的設定說明。 ==================== build-it/make-it-wait-for-a-person.md ==================== --- level: '2' track: - build verified_on: 2026-10-02 --- # 讓它等一個人做決定 這一課要讓[教學課程](/zh-tw/learn/build-it/vibe-coding-tutorial.md)裡的退貨櫃台等一個人做決定。每一筆新的退貨，都會寄一封附有「核准」與「拒絕」兩個按鈕的電子郵件給值班主管；在對方答覆之前，不會向顧客承諾任何事。對方答覆之後，同一次工作流的執行會接續下去：它在該列寫入決定、審核者的姓名與時間，然後通知顧客。 這是第二次實作。請從已經完成的櫃台開始；你在教學課程中建置的東西，一樣都不會丟掉。 ## 你將建置的內容 一筆會先等一個人、之後才有任何東西送到顧客手上的退貨。你要從自己的收件匣，扮演審核者 Jordan Vance——Harbor Bicycle Co. 的值班主管。 1. 一筆新的退貨進入數據表，退款金額和先前一樣自動算出。 2. 櫃台把這筆退貨的事實，連同「核准」與「拒絕」兩個按鈕，用電子郵件寄給審核者，然後暫停。等待期間，不會有任何東西送給顧客。 3. 每個按鈕都會開啟一個顯示所選結果的頁面。打開頁面不會決定任何事；只有頁面上的「確認」（Confirm）按鈕才會。 4. 審核者一確認，同一次執行就會接續下去：它在該列寫入 Decision、Decided by 和 Decided at，再寄電子郵件給顧客——如果核准，內容是退款金額；如果沒有，就是一段不含金額的簡單致歉。 沒有人需要在儲存格裡打字來做決定。這裡的一切都不是 Harbor Bicycle Co. 的真實系統——在把成果展示給任何人看之前，記得把公司、審核者和用語換成你自己的內容。 ## 你需要準備的東西 - 你在[教學課程](/zh-tw/learn/build-it/vibe-coding-tutorial.md)中完成的櫃台，位於同一個測試組織：Return Requests 與 Refund Rules 兩張數據表、Calculate refund amount 工作流（新增的一列會自動得到它的 Refund amount），以及 Return Desk Assistant。 - 同一個 AI 程式碼工具，如同教學課程中一樣，透過 MCP 連接到該組織，並具備寫入權限。 - 兩個你能讀取的電子郵件地址：一個用來扮演審核者，一個用來扮演顧客。兩個指向同一個收件匣的地址也可以，例如你郵件帳號的別名。只使用你自己的地址——絕不使用真實顧客的地址，也不使用同事的地址。 - 組織裡一個名為 Gmail 的電子郵件連線，或是一位能登入來建立它的人。步驟 1 會說明去哪裡查看。 這一頁會用到幾個詞：**「執行」**是工作流跑一次；**「已暫停」**的執行，是停在它的等待步驟，等有人答覆之後，再從同一個位置接續下去。**「審核者」**是收到電子郵件的人；Decided by 記錄的就是他的姓名。**「一次性連結」**是只能用來回答一次、結尾帶有隨機代碼的位址；櫃台只保留這個代碼的**「指紋」**——一種單向打亂的結果，可以用來核對代碼，卻無法還原出代碼。答覆之後，這個連結會告訴你這筆退貨已經做出決定。**「確認頁面」**是電子郵件裡的按鈕所開啟的頁面：它顯示所選的結果，而且只有頁面上的「確認」按鈕才會記錄它。**「核准任務」**是執行建立出來、並等待答覆的項目，有「核准」與「拒絕」兩個答案；作答的人不需要看到它。**「決定連結」**是核准任務針對某一個答案自己附帶的連結：一打開它就會做出決定，所以它只留在私有數據表（步驟 2 會建置），絕不放進電子郵件。**「程式碼步驟」**是你的工具寫出來的小步驟，相對於平台內建的原生步驟。 ## 操作步驟 在下面的提示詞裡，方括號標示的是要填入的值，由你的工具填入。其中只有兩個要由你自己提供：你能讀取的那兩個電子郵件地址，審核者的地址在步驟 3，顧客的地址在步驟 4 和 5。 ### 1. 把櫃台準備好 先做兩件小事：留一個位置放顧客的地址，以及設定電子郵件連線。 **你輸入的內容**： > 在 Return Requests 新增一個 Customer email 欄位（純文字）。其他每一列都保持原樣。 確認通知會寄到該列上的地址，所以櫃台需要這個欄位。電子郵件本身則是透過平台自己的連線寄出，絕不透過工作流裡的任何東西。請打開「行動模組」（Actions）>「流程營運模組」（FlowOps）>「更多」>「連線」：電子郵件憑證就在那裡，是一個有名稱的連線，名為 Gmail。如果沒有，就需要有人在每個組織裡各登入 Gmail 一次來建立它——請在步驟 3 之前完成。使用「連線」清單提供的新增連線按鈕，並以你能讀取的 Google 帳號登入；櫃台的電子郵件會從那個帳號寄出。 畫面：流程營運模組的「連線」清單，顯示一個名為 Gmail 的連線 *1「流程營運模組」（FlowOps）>「更多」>「連線」。2 唯一一個名為 Gmail 的連線。* 這一課是針對 Gmail 連線撰寫並檢查的。如果你使用其他種類的電子郵件連線，請在貼上之前，把步驟 3 第 9 點裡的 Gmail 這個詞換成它的名稱，並在信任這次執行之前，先確認兩封郵件都有送達。 這是教學課程第一個習慣「使用平台內建的東西」一路延續下來的結果：憑證屬於平台本身的連線儲存區，永遠不屬於某個工作流。如果之後你匯出工作流，請打開匯出的檔案，確認裡面沒有任何金鑰或密碼。 **你現在應該會看到**：Return Requests 有十個欄位，Customer email 是最後一個，每一列都是空的；「連線」清單中有一個名為 Gmail 的連線。 ### 2. 建立確認決定的頁面 在請任何人做決定之前，先決定他們在哪裡作答。審核者會從一封附有兩個按鈕的電子郵件做決定，每個按鈕都會開啟 iMBrace 上的一個頁面，顯示所選的結果並請他們確認。這個步驟要建置那個頁面，以及它用來核對一次性連結的私有數據表。步驟 3 則建置寄出電子郵件的工作流。 請先讀提示詞下方的白話說明，再把整段提示詞貼上。它是寫給你的工具看的，所以你不需要看懂裡面的每一個技術用語。 **你貼上的內容**，放在同一則訊息裡： > 建置一個用來確認決定的地方，分成兩個部分。 > > 第一部分：一個名為 Return Decision Links 的私有數據表，包含這些純文字欄位：Fingerprint、Group、Action、Order reference、Decision link、Expires at、Used at、Used action、Created at。不要有 Link-type 欄位。Decision link 會存放核准任務中承載決定的連結，而核准任務由下一個步驟建立。這個數據表只有工作流會用，不要交給任何代理人。 > > 第二部分：一個名為 Confirm a return decision 的工作流，以公開頁面的形式作答——不需要登入，也不需要金鑰。請使用會直接回應呼叫端的觸發條件，並以原始 HTML（content type 為 text/html）回覆。頁面位址帶有一個名為 t 的隨機代碼。運作方式如下： > > 1. 從 t 取得代碼（一般造訪時取自位址；按下頁面自己的按鈕時，取自名為 t 的表單欄位）。算出它的單向指紋。只比對指紋；絕不儲存或顯示代碼。 > 2. 在 Return Decision Links 上找出具有該指紋的那一列。沒有代碼，或找不到該列：顯示一個簡單的頁面，上面寫著「This link is not valid.」，沒有按鈕。 > 3. 如果有這一列，就讀取與它同屬一個 Group 的每一列，並依 Order reference 讀取 Return Requests 上的那筆退貨。連結有三種狀態：有效（尚未使用、尚未過期）、已使用（Used at 已填入）或已過期（超過 Expires at）。 > 4. 單純造訪只會顯示頁面，不會改變任何東西。有效：顯示「Approve return [order reference]?」（或「Reject return [order reference]?」）、顧客、商品與退款金額、一個把代碼回傳的 Confirm 按鈕，以及這一行字：「Nothing is decided until you press Confirm.」已使用：顯示「This return has already been decided.」已過期：顯示「This link has expired.」 > 5. 只有在有效的連結上按下 Confirm 時：先使用 Decision link 裡的連結（一個不帶任何憑證的單純 GET；即使失敗也要繼續往下，這樣才能讀到它的狀態）。如果狀態是 200 到 299，就把該 Group 的兩列都標示為已使用（Used at 設為現在的時間，Used action 設為該動作），並顯示「Return [order reference] approved」（或「rejected」），再加一行說明正在寄電子郵件通知顧客。如果失敗，就不要改變任何東西，讓連結仍然可以使用，並顯示「Your decision was not recorded. Try the button again in a minute.」 > > 每一條路徑都以一個頁面作結。頁面請用一個小的程式碼步驟來建置，它只負責把值轉成文字，並對它插入的每一個值做跳脫處理：不能有網路呼叫，也不能有憑證。數據表的讀取與寫入、那次呼叫以及各個回應，請使用原生步驟。發布之後，請告訴我頁面位址。 **白話說明。** 先是私有數據表。每一列存放一個按鈕的一次性連結（以指紋的形式保存，絕不保存代碼本身），以及那個按鈕的決定連結，由步驟 3 填入。Group 把一筆退貨的兩個按鈕綁在一起。只有工作流會用這個數據表，所以不會交給任何代理人。接著是頁面，逐點說明： 1. 頁面從連結中讀取代碼，只保留它的指紋，所以代碼本身不會被儲存在任何地方。 2. 對不上任何一列的連結，會得到一個簡單的「無效」頁面，沒有按鈕。 3. 對得上的連結，會依私有數據表判斷是有效、已使用還是已過期；頁面顯示的事實，則取自那筆退貨自己的那一列。 4. 單純造訪只會顯示事實與一個「確認」按鈕。郵件掃描程式和預覽功能會打開它們找到的每一個連結，所以打開連結絕不能決定任何事。 5. 只有「確認」會做出決定。頁面先記錄答案，再讓兩個按鈕一起失效，所以一筆退貨只會被決定一次；如果記錄失敗，就不會有任何改變，頁面也會如實說明。 大部分步驟都是原生步驟。其餘是小的程式碼步驟，只根據拿到的值做運算；沒有任何一個會發出網路呼叫或持有憑證。 **你現在應該會看到**：在「知識模組」（Knowledge）>「數據表」（DataIQ）裡，多了一個新的數據表 Return Decision Links，有九個欄位，沒有任何列。在「行動模組」（Actions）>「流程營運模組」（FlowOps）裡，有一個已發布的工作流 Confirm a return decision；打開這個工作流，就能進入它的執行紀錄。請向你的工具索取頁面的位址，在無痕視窗中打開它：先是位址後面什麼都不加，接著只加上 `?t=`（後面不接任何東西），最後加上 `?t=notacode`。每一次你都會看到同一個簡單的頁面，上面寫著「This link is not valid.」，沒有按鈕。在執行紀錄裡，每一次造訪都顯示為一次已完成的執行，而且沒有任何數據表被改變。 畫面：以沒有連結的方式打開確認頁面：只有一句簡單的話，沒有按鈕 *以沒有連結的方式打開的頁面：只有一句簡單的話，沒有按鈕。* 這個簡單的頁面就是正確的第一個答案：沒有連結，就沒有東西可決定，也沒有按鈕可按。你會在步驟 4 看到帶著真實連結的頁面。 如果你看到的不是那一句話，請把你看到的內容原原本本告訴你的工具，請它讓工作流以一個不需要登入的網頁作答，然後再打開一次位址，確認之後再繼續。 這個頁面背後的規則：電子郵件裡的連結不是決定。打開連結只會顯示一個頁面；只有「確認」才會做出決定。隨機代碼絕不儲存，只儲存它的指紋，而存放指紋的數據表是私有的。[人工核准](/zh-tw/learn/build-it-well/human-approval.md)說明了原因。 ### 3. 以電子郵件詢問、等候答覆，再通知顧客 櫃台就是在這個步驟開始等待。一個工作流以電子郵件詢問一個人，然後停在等待步驟，只有在對方確認之後，同一次執行才會把決定寫到該列，並通知顧客。請把整段提示詞放在同一則訊息交給你的工具——詢問的那一半和完成的那一半是一體的——並且在它說工作流已發布之前，先不要新增任何退貨。你在這裡要提供的值只有審核者的地址。和步驟 2 一樣，請先讀提示詞下方的白話說明：提示詞是寫給你的工具看的。 **你貼上的內容**，放在同一則訊息裡： > 建置一個名為 Apply return decision 的工作流，以電子郵件請一個人做決定，等候答覆，然後把工作完成。它在 Return Requests 某一列的 Refund amount 被寫入時啟動——是 Refund amount 上的「column updated」（欄位更新）自動化，而不是「row created」（新增資料列）。審核者是 Jordan Vance，地址為 [你自己的地址]。請依序執行： > > 1. 讀取該列。除非 Order reference 與 Refund amount 都已填入，而且 Decision 是空的，否則什麼都不做。 > 2. 依這個 Order reference 讀取 Return Decision Links，依 Created at 由新到舊排序，只取一列。如果有傳回一列而且它的 Used at 是空的，或是讀取失敗，就表示已經有人正在被詢問：到此為止。不建立第二個任務，也不寄第二封電子郵件。 > 3. 用平台自己的日期步驟取得目前的時間（UTC）。 > 4. 用一個小的程式碼步驟把該列變成決定卡片：標題「Return [order reference] needs a decision」、一行摘要，以及一張列出 Customer、Order reference、Item、Condition、Price 和 Refund amount 的表格。上面不要有決定期限。 > 5. 用平台自己的任務步驟建立一個核准任務：以那張卡片作為它的說明，並設兩個選項，Approve（綠色）和 Reject（紅色）。把它指派給我的 API 金鑰所代表的使用者。絕不要讓受指派者留空，也絕不要指派給同事。 > 6. 用一個小的程式碼步驟產生兩個隨機代碼，一個給 Approve、一個給 Reject，並為每一個代碼算出單向指紋——方法與確認頁面所用的相同。每一個一次性連結，就是 Confirm a return decision 頁面的位址，加上 ?t= 和它的代碼，有效期限為七天。核准任務也為每一個答案附帶自己的決定連結，也就是承載決定的那個連結：只在這一點讀取它們，其他地方都不要讀取，也絕不要把它們放進電子郵件、頁面、Return Requests 的資料列或任何回覆裡。 > 7. 用原生的數據表步驟，在 Return Decision Links 寫入兩列，每個按鈕一列：指紋、Group（任務的 id，兩列相同）、Action、Order reference、Decision link（核准任務中那個答案的決定連結，以純文字存放）、Expires at 和 Created at。Used at 與 Used action 保持空白。絕不儲存代碼。 > 8. 用一個小的程式碼步驟，把同一張卡片轉成附有兩個按鈕的 HTML 電子郵件，Approve（綠色）和 Reject（紅色），每個按鈕都只指向第 6 點產生的一次性連結，絕不指向決定連結，另外加上這一行：「Each button opens a page where you confirm. Nothing is decided by opening a link.」 > 9. 用平台自己針對 Gmail 的 Send Email 步驟寄出，透過組織的 Gmail 連線，並使用組織所提供的該步驟最新版本。如果還沒有電子郵件連線，就停下來告訴我：需要有人登入才能建立它。寄件者名稱為「Harbor Bicycle Returns Desk」，名稱中不要有逗號。主旨為「Return [order reference] needs your decision」。 > 10. 等待核准任務（也就是等候答覆的那個任務步驟）。第 5 到第 10 點必須連續執行：中間不能有任何東西，而且在第 10 點之前的任何地方，都不能有會暫停或休眠的步驟。 > > 當答覆回來、執行接續下去時： > > 11. 再依 Order reference 讀取一次那筆退貨。 > 12. 依答覆處理。只有在 Decision 仍然是空的、而且你剛讀到的那一列就是啟動這次執行的那一列時，Approve 或 Reject 才算數；其他情況一律不寫入任何東西。Approve：取得時間（UTC）；在該列寫入 Decision「Approved」、Decided by「Jordan Vance (confirmed by email)」以及 Decided at；然後才寄電子郵件給 Customer email 上的顧客地址，主旨為「Your Harbor Bicycle return is approved」，內容是純文字，寫明退款金額。Reject：做法相同，但 Decision 寫入「Rejected」，主旨為「Your Harbor Bicycle return was not approved」，內容是一段簡單的致歉，不寫任何退款金額，並請對方聯絡退貨櫃台。 > > 每一次數據表的讀取與寫入、任務、等待、時鐘以及電子郵件，都請使用原生步驟。小的程式碼步驟只用在第 4、6 和 8 點。 **白話說明**，逐點來看。詢問的那一半： 1. 除非這筆退貨已經準備好，否則什麼都不做：它有訂單編號和退款金額，而且還沒有人做出決定。 2. 同一時間只詢問一次：如果這筆退貨已經在等待答覆，就到此為止，這樣對該列的第二次寫入就不會啟動第二次詢問。 3. 讀取時鐘，讓連結有一個到期時間。 4. 把審核者需要的事實放在同一張卡片上。 5. 建立執行要等待的核准任務：一個有兩個答案（「核准」與「拒絕」）的項目，指派給你的 API 金鑰所代表的使用者。 6. 產生兩個一次性連結，每個按鈕一個，並取得核准任務自己的決定連結。只有這一點會從核准任務取得它們；從那之後，它們只存在於私有數據表中，而且只有確認頁面會使用。 7. 把每個按鈕的指紋和它的決定連結存到私有數據表，確認頁面會在那裡找到它們。 8. 把卡片變成附有兩個按鈕的電子郵件。 9. 透過組織的 Gmail 連線，把它寄給審核者。 10. 等待。執行在這裡暫停，並保留它的位置，直到審核者作答。 完成的那一半，在答覆之後： 11. 再讀取一次那筆退貨，讓執行依它現在的樣子作業。 12. 先寫入 Decision、Decided by 和 Decided at，再寄電子郵件給顧客。只有同一列的第一個答覆才算數；其他一律不寫入任何東西。 第 4、6 和 8 點是小的程式碼步驟，和教學課程裡的計算步驟同一類：每一個都只根據拿到的值做運算，不發出網路呼叫，也不持有憑證。 **你現在應該會看到**：在「行動模組」（Actions）>「流程營運模組」（FlowOps）裡，Apply return decision 已發布，Calculate refund amount 則維持不變。打開 Apply return decision，從頭開始讀：建立核准任務的步驟、透過 Gmail 寄出電子郵件的步驟，以及等待的步驟，依這個順序出現，而且在等待之前沒有任何會暫停的東西。要檢查它，請你的工具依序列出 Apply return decision 的步驟（只要名稱），再拿這份清單和畫布上的步驟比對。也請它確認，這裡產生的指紋，用的是和 Confirm a return decision 裡相同的方法。先不要新增退貨；步驟 4 會做這件事。 如果你的工具提出問題，就回答它。如果它建置出來的東西和編號的各點不一致，請它把工作流改成符合這些要點，然後再讀一次步驟。 請依每個步驟的狀態來讀一次執行。步驟的內容可能含有會做出決定的連結，所以你完全不需要打開任何一個步驟。在真實的組織裡，只讓負責審查建置成果的人打開執行紀錄和 Return Decision Links 數據表，並清除舊的執行。 畫面：Apply return decision 工作流：寄信給審核者的步驟，接著是等待的步驟 *1 側邊欄的「流程營運模組」（FlowOps）。2 寄信給審核者的步驟。3 等待決定的步驟。* ### 4. 試試核准 現在照審核者會做的方式跑一遍。每一筆測試退貨都用一個新的訂單編號，也就是數據表上還沒有的編號：櫃台是靠訂單編號來追蹤每一筆退貨的。 **你輸入的內容**： > 在 Return Requests 新增一列：Customer name 填 Morgan Ellery，Order reference 填 HB-3001，Item 填 helmet，Condition 填 unopened，Price 填 45，Customer email 填 [你用來扮演顧客的地址]。Refund amount、Decision、Decided by 和 Decided at 先留空。 **你現在應該會看到**，一個時刻接著一個時刻： 1. 幾秒鐘之內，該列的 Refund amount 就會填入：45。Decision、Decided by 和 Decided at 仍然是空的。在「行動模組」（Actions）>「流程營運模組」（FlowOps）裡，Apply return decision 的執行紀錄多了一次新的執行，而這次執行已暫停。建立核准任務和寄出電子郵件的步驟標示為成功。在它等待期間，請你的工具只查詢核准任務的狀態和受指派者：它是開啟的，而且已指派。 畫面：Apply return decision 的執行紀錄：新的一次執行已暫停 *1 側邊欄的「流程營運模組」（FlowOps）。2 Apply return decision 的新執行，已暫停。* 2. 審核者的收件匣裡有一封電子郵件，主旨就是你要求的那一個。它列出這筆退貨的事實——顧客、訂單編號、商品、狀況、價格和退款金額——以及兩個按鈕，「核准」與「拒絕」。Return Decision Links 現在有兩列，每個按鈕一列，Used at 都是空的。 畫面：審核者收到的電子郵件，附有「核准」與「拒絕」按鈕 *審核者收到的電子郵件：這筆退貨的事實，以及「核准」與「拒絕」兩個按鈕。* 3. 打開「核准」。頁面會顯示所選的結果：顧客、商品和退款金額，並有一個「確認」按鈕。沒有任何東西改變。如果你想，可以再打開一次：執行仍然是暫停的，該列仍然沒有決定。 畫面：從「核准」按鈕開啟的確認頁面 *確認頁面：這筆退貨的事實，以及一個「確認」按鈕。按下之前，不會決定任何事。* 4. 按下「確認」。頁面會說明這筆退貨已核准，並且正在寄電子郵件通知顧客。在「流程營運模組」裡，剛才暫停的那次執行就是完成的那一次，這筆退貨不會留下任何暫停的執行。在數據表上，該列現在顯示 Decision 為 Approved，Decided by 為 Jordan Vance (confirmed by email)，並有一個 Decided at 時間。顧客的收件匣裡有一封寫明退款金額的電子郵件，而 Return Decision Links 的兩列都已填入 Used at。 畫面：Return Requests 捲動至 Decision、Decided by 和 Decided at，由這次執行寫入 *1「知識模組」（Knowledge）>「數據表」（DataIQ）。2 Decision、Decided by 和 Decided at，由這次執行寫入。* 畫面：同一次 Apply return decision 執行，已完成，其兩個 Send Email (Gmail) 步驟標示為成功 *1 側邊欄的「流程營運模組」（FlowOps）。2 同一次執行，已完成，其兩個 Send Email (Gmail) 步驟標示為成功。* 5. 回到審核者的電子郵件，打開「拒絕」。頁面會說明這筆退貨已經做出決定。兩個按鈕會一起失效，所以一筆退貨只會被決定一次。 這是第五個習慣：決定是由發出詢問的那次執行寫在資料列上的一個值——答案、審核者的姓名和時間——而不是有人在聊天室裡打「看起來沒問題」，也不是有人去編輯的儲存格。在有人作答之前，不會有任何東西送到顧客手上，執行就只是等待。 Decided by 顯示你指定的審核者姓名，後面接著「(confirmed by email)」：這項決定是從該審核者自己的電子郵件確認的，所以請把這封郵件留在自己手上，不要轉寄。 如果這個步驟裡有任何一項檢查不成立，請一個環節一個環節往回查。Refund amount 有填入嗎？Apply return decision 有沒有新的執行，它是已暫停，而不是失敗？建立任務和寄出電子郵件的步驟有標示為成功嗎？接著看看你的垃圾郵件匣。告訴你的工具是哪一項檢查卡住了，請它只修那一件事。 ### 5. 試試拒絕 用相反的方式回答第二筆退貨。 **你輸入的內容**： > 在 Return Requests 新增一列：Customer name 填 Riley Okafor，Order reference 填 HB-3002，Item 填 bike lock，Condition 填 used，Price 填 28，Customer email 填 [同一個顧客地址]。Refund amount、Decision、Decided by 和 Decided at 先留空。 **你現在應該會看到**： 1. 開頭和先前一樣：幾秒鐘之內出現一次新的已暫停執行，審核者的收件匣裡有一封附有兩個按鈕的電子郵件。 2. 打開「拒絕」，然後按下「確認」。頁面會說明這筆退貨已拒絕。同一次執行從已暫停變成已完成，該列顯示 Decision 為 Rejected，Decided by 和 Decided at 也已填入。 3. 顧客的收件匣裡有一封郵件，說明這筆退貨未獲核准：一段簡單的致歉，以及一行請對方聯絡退貨櫃台的話，不含任何退款金額。 4. 打開同一封郵件裡的「核准」：頁面會說明這筆退貨已經做出決定。這筆退貨沒有任何核准的電子郵件寄給顧客。 ## 如何確認它真的可行 不要把程式碼工具對自己做了什麼的摘要說明當成證據。一段聽起來合理、描述建置成功的說法很容易寫出來，也很容易被誤認為真的成功——請親自去看。這些檢查大部分你已經在步驟 4 和 5 跑過了。額外多出來的，是按鈕位址的檢查、核准任務的回讀、同一時間只詢問一次、連線，以及助理。如果你要再跑一筆退貨，請用新的訂單編號。 ### 核准 1. **它會等待。** 新的 Apply return decision 執行在幾秒鐘之內就會暫停，其建立核准任務和寄出電子郵件的步驟標示為成功。在該列上，Refund amount 已填入，Decision、Decided by 和 Decided at 是空的。在它等待期間，請你的工具只查詢核准任務的狀態和受指派者：它是開啟的，而且已指派。 2. **一封郵件，沒有捷徑。** 這筆退貨恰好收到一封電子郵件，附有兩個按鈕。請你的工具把你收到的郵件中兩個按鈕的位址印出來，每個代碼都縮短顯示。每一個都是確認頁面的位址，後面接著 `?t=` 和一個代碼，沒有其他任何東西。請把代碼留給自己。 3. **造訪不會決定任何事。** 打開「核准」兩次。你會得到一個只有一個按鈕的頁面，執行仍然是暫停的，而且 Return Decision Links 的兩列 Used at 仍然是空的。 4. **「確認」才會做出決定。** 按下「確認」。剛才暫停的那次執行會完成，這筆退貨不會留下任何暫停的執行。Decision 是 Approved，Decided by 是審核者的姓名，後面接著「(confirmed by email)」，Decided at 是一個時間，而且顧客的地址收到了寫明退款金額的電子郵件。Return Decision Links 的兩列都已填入 Used at。 5. **另一個按鈕會失效。** 從同一封郵件按「拒絕」，頁面會說明這筆退貨已經做出決定。 6. **核准任務的狀態一致。** 請你的工具只查詢它的狀態：現在顯示已回答為「Approve」。絕不要印出它的連結。 ### 拒絕 1. **開頭相同。** 一次已暫停的執行，和一封附有兩個按鈕的電子郵件。 2. **「拒絕」會做出決定。** 按下「拒絕」，再按「確認」。同一次執行從已暫停變成已完成。Decision 是 Rejected，Decided by 和 Decided at 已填入，核准任務顯示已回答為「Reject」。 3. **沒有任何金額送到顧客手上。** 顧客收到的郵件說明這筆退貨未獲核准：一段簡單的致歉，以及一行請對方聯絡退貨櫃台的話。請檢查其中有沒有退款金額——裡面沒有提到退款金額，也沒有任何等於價格的金額。 4. **沒有任何核准通知寄出。** 顧客沒有收到這筆退貨的任何核准郵件，而且「核准」按鈕現在會說明這筆退貨已經做出決定。 ### 同一時間只詢問一次、連線與助理 - 再新增一筆退貨，並讓它保持等待。這筆退貨只用於這項檢查，並且不要對它作答。修改它的 Condition。不會有第二封電子郵件寄出，而且第一次執行仍然是暫停的。可能會出現第二次很短的執行並立刻結束：那是步驟 3 的第 2 點把它停下來。 - 打開「行動模組」（Actions）>「流程營運模組」（FlowOps）>「更多」>「連線」，確認電子郵件憑證是一個有名稱的連線，Gmail，而不是寫在某個步驟裡的文字。 - 請你的工具讀回 Return Desk Assistant 的設定：只有一項技能，Log return request，沒有任何數據表，所以連結和決定都留在工作流手上。 如果上面任何一項不成立，這其實比一個看起來沒問題、實際上卻不行的建置更有價值。修好失敗的那一項，然後再檢查一次。 ## 接下來可以做的事 - 讓一筆退貨一直沒有人作答。執行會維持暫停，等待期間不會有任何東西送到顧客手上。你在步驟 3 要求的連結，有效期限為七天。 - 用一筆新編的退貨去跟 Return Desk Assistant 對話，並觀察 Apply return decision 的執行紀錄。在你決定助理所記錄的那筆退貨之前，先把顧客的地址填進該列的 Customer email。 - 閱讀[人工核准](/zh-tw/learn/build-it-well/human-approval.md)，了解這一課背後的方法：決定要放在哪裡、什麼讓關卡守得住，以及如何證明它從頭到尾都接上了線路。 - 請見[基本組成元件](/zh-tw/learn/build-it/building-blocks.md)，了解櫃台的每個部分在畫面上的位置：數據表、工作流、代理人和電子郵件連線。 - 關於 SDK、CLI 或 MCP 連線本身的任何內容，[engineer.imbrace.co](https://engineer.imbrace.co/zh-tw/) 是保持最新的權威來源——這一頁會比那裡更快過時。[設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md) 有完整的設定說明。 ==================== build-it/working-with-ai.md ==================== --- level: '2' track: - build verified_on: '2026-09-23' --- # 與 AI 程式碼工具協作 現在，在 iMBrace 上大多數的建置工作都可以交給 AI 程式碼工具完成。這沒有問題，而且幾乎不會改變「完成」這件事的定義。這一頁要說的，就是真正會改變的部分。 ## 立場 **工具負責協助，由人來決策。** 這不是因為工具能力不足，而是因為責任無法轉移。必須有人簽核確認這個建置成果可以運作，而這個人不能是寫出它的那個東西。 **絕不採信建置成果對自己的回報。** AI 工具讓這個問題更為突出：一份令人信服的「測試通過」摘要很容易產生，也很難與真正通過的結果區分。要親自執行它、親眼看著它跑，並且到平台上查看結果。你沒有親眼看到的綠燈，就不算綠燈。 **誠實說出目前的狀態。** 建置成果的每一個部分，都只會是以下三種狀態之一： - **proposed（已提出）**——已設計，但尚未建置； - **built（已建置）**——已建置，但尚未在平台上實際執行並檢查過； - **live（已上線）**——已在平台上執行，且結果已由人檢查過。 沒有人會因為狀態是「built（已建置）」而被苛責。把從未執行過的東西寫成「live（已上線）」，才是真正的失敗。 ## 該給工具什麼 - **這份指南的 `AGENTS.md`**，或是管轄你眼前這項工作的那一頁就好，不要一次全部都給——讀了所有東西的工具，留給你問題本身的空間反而更少。 - **SDK 自己的地圖**，在它撰寫 SDK 程式碼時，從 [engineer.imbrace.co](https://engineer.imbrace.co/llms.txt) 即時抓取，絕不使用舊的副本。 - **組織本身**，透過 MCP 連線取得——當問題是關於現在有什麼、或發生過什麼事的時候，請見[設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md)。 ## 防護措施 - **絕不把憑證放進工作流、程式碼步驟、提示詞，或任何已提交的檔案中。** 憑證只存放在組織的連線儲存區，或本機一個絕不提交的 `.env` 檔案裡。 - **程式碼步驟必須是「純」的**——輸入數字、輸出結果，不做網路呼叫、不用金鑰——否則就要清楚說明為什麼不是。 - **拒絕回答也是一種資料，不是錯誤。** 「我找不到這個」本身就是一個有效、有用的答案。 - **被跳過的檢查絕不算通過。** 如果測試無法執行，就要說它沒有執行。 - 測試資料、記錄、提示詞或範例中**不得含有個人資料**，一律用虛構的。 - **寫給一個陌生人看。** 句子要平實清楚，不用簡稱代號，也不寫只有當時在對話裡的人才看得懂的內容。 ## 最重要的幾個習慣 1. **先看商業成果。** 誰會用它、現在卡在哪裡、它能解開什麼。回答一個沒有人問過的問題，答案再聰明也是錯的。 2. **先由人畫出草圖。** 在工具提出設計之前，先讓人畫出這個使用案例——它的輪廓、組成部分，以及哪裡該由人來決策。這樣設計才會真正屬於這個人。 3. **用證據表達不同意見。** 當工具認為這個人的想法有誤時，要立刻連同證據說出來，而不是默默照著要求去做。 4. **每一個主張都要有依據。** 一筆 board 資料列、一個執行 id、一段貼上的輸出結果。沒有依據，就不能主張。 5. **更正紀錄時要註明日期。** 當某項發現或決策紀錄後來證實有誤時，就在原地註明日期說明，並保留原文可見。 6. **交由另一個人審查。** 在成果上線之前，由沒有參與建置的人執行[審查清單](/zh-tw/learn/build-it-well/review-checklist.md)。 7. **程序的繁簡要與變更的大小相稱。** 小變更只需簡短的紀錄。 ## 委派要保持淺層 如果你的工具把工作交給它自己的助手，請把交接保持在最上層，給每個助手完整的說明，並且親自檢查每一項結果：當助手說它修好了什麼，就打開檔案親自看一看。 ## 「完成」代表什麼 是另一個人可以安裝的東西、一份他們可以照著做的說明、一個他們可以執行的測試，以及每個部分都誠實標示的狀態。 ==================== build-it/building-blocks.md ==================== --- level: '2' track: - build verified_on: 2026-09-29 --- # 基本組成元件 iMBrace 上的每一個使用案例，不論看起來有多不一樣，都是用同樣的五樣東西建置而成：一張數據表、一個代理人、一個文件模型、一個工作流，以及一個頻道。本頁會為每一樣東西命名、說明它的用途，並指出它在產品中的位置，讓你第一次打開訓練用組織時，側邊欄上不會有任何東西是個謎。最後會說明延伸其中一樣東西、或把它交給別人的三種方式：技能、MCP 連線，以及安裝模組。 ## 一張數據表 數據表是一張你自己定義的結構化表格——由列與具型別的欄組成，就像一份輕量版的 CRM 表。它的用途是存放一個建置需要記住的任何東西：一份退貨申請清單、一份標好價格的報價單，或是一組可供他人編輯的規則。 在側邊欄中，這位於**「知識模組」（Knowledge）> 「數據表」（DataIQ）**之下（SDK 及其權限範圍稱它為 board，也稱 databoard；英文產品名稱則是 DataIQ）。其他每一個元件都會讀取或寫入某張數據表：工作流的每個步驟、代理人唯一那個範圍很窄的工具，以及文件模型自己擷取出的結果，最終都會落在數據表上。 畫面：一張數據表以列與具型別欄位的形式開啟 *1 「知識模組」（Knowledge）> 「數據表」（DataIQ）。2 這張數據表的具型別欄位。* 讓一張數據表值得信賴的習慣：把商業人員可能需要調整的規則——門檻值、費率、上限——放進數據表中，變成一列可編輯的資料，絕不要放進代理人自己的指示裡。[八大原則](/zh-tw/learn/build-it-well/the-eight-principles.md)說明了原因。 用程式碼實作：[數據表](https://engineer.imbrace.co/zh-tw/reference/board/)。 ## 一個代理人 代理人是一個人或一個頻道會與之對話的介面。它的用途是進行對話本身：理解對方在要求什麼，並呼叫正確的工具去執行。 在側邊欄中，這位於**「行動模組」（Actions）> 「AI智能助手」（AgentIQ）**之下。使用者是透過頻道找到代理人的，而它是靠呼叫一個工作流來行動——也就是下方會提到的其中一項技能——任何對數據表的讀取或寫入，實際上都發生在那裡。 畫面：AI智能助手的「啟用中的 AI」分頁，一張卡片一個助手 *1 「行動模組」（Actions）> 「AI智能助手」（AgentIQ）。2 Sales Quoting 代理人的卡片。* 讓一個代理人值得信賴的習慣：只給它一個範圍很窄的工具，對應它必須做的那一件事，絕不給它整張數據表，這樣它就能記錄一筆申請，但永遠無法自己寫下核准這筆申請的決定。[人工核准](/zh-tw/learn/build-it-well/human-approval.md)說明了為什麼代理人絕不能自己寫下這個決定。 用程式碼實作：[AI 代理人](https://engineer.imbrace.co/zh-tw/reference/ai-agent/)。 ## 一個文件模型 文件模型會告訴擷取功能該從一份檔案中取出什麼內容。它的用途是把一份非結構化的文件——一張發票、一份表單、一張掃描的裝箱單——轉換成數據表能容納的結構化欄位。 在側邊欄中，這位於**知識模組 > 「文件模組」（DocIQ）**之下的**「文件模型」（Document Models）**分頁。它擷取出來的內容會變成數據表上的資料列，而同一張數據表接著會被工作流或代理人讀取。 畫面：文件模組的「文件模型」分頁，開啟其中一個模型的擷取欄位 *1 知識模組 > 「文件模組」（DocIQ） > 「文件模型」（Document Models）。2 該模型的欄位表。* 讓一個文件模型值得信賴的習慣：先採用平台本身的預設模型，之後才考慮自己另外寫一個，並讓擷取功能對準單一數據表自己的欄位，而不是讓模型的選擇隨機發生。[文件模型](/zh-tw/learn/build-it-well/document-models.md)說明了應該依照什麼順序去嘗試。 用程式碼實作：[Document AI](https://engineer.imbrace.co/zh-tw/sdk/document-ai/)。 ## 一個工作流 工作流（也稱為 flow）是一經觸發就會自動依序執行的一連串步驟。它的用途是把實際的工作，依固定、可檢核的順序完成：讀取一張數據表、執行一項計算、等待某人做決定、發送一則訊息。 在側邊欄中，這位於**行動模組 > 「流程營運模組」（FlowOps）**之下（SDK 及其權限範圍稱它為 workflow；英文產品名稱則是 FlowOps）。工作流會讀取並寫入數據表，也可以是代理人所呼叫的唯一一項工具，並且既能由數據表的變動啟動，也能由頻道事件啟動。 畫面：流程營運模組的工作流清單 *1 行動模組 > 「流程營運模組」（FlowOps）。2 流程營運模組的工作流清單。* 讓一個工作流值得信賴的習慣：先用平台本身現成的步驟建置，任何你自己必須寫的步驟都保持單純——只根據拿到的值做運算，不持有任何屬於自己的憑證。[原生優先](/zh-tw/learn/build-it-well/native-first.md)說明了這麼做能帶來什麼好處。 用程式碼實作：[工作流](https://engineer.imbrace.co/zh-tw/reference/workflow/)。 ## 一個頻道 頻道是一個人實際接觸到代理人的地方——一個網站聊天視窗、WhatsApp、電子郵件，或另一個已連接的通訊應用程式——也是回覆訊息會送達的地址。 在側邊欄中，這位於**行動模組 > 「連接模組」（ConnectIQ）**之下的**「渠道設定」（Channels）**分頁。頻道是與代理人展開對話的方式，工作流也可以把頻道的某個事件當成自己的觸發條件。 畫面：連接模組的「渠道設定」分頁，列出網頁小工具與各通訊頻道 *1 行動模組 > 「連接模組」（ConnectIQ） > 「渠道設定」（Channels）。2 網頁小工具的頻道清單。* 讓一個頻道值得信賴的習慣：把它的登入資訊，設定成組織自己的連線，只設定一次，絕不讓它以一個值的形式存在於工作流裡。像代管郵件服務這種需要有人登入的連線，由一個人針對整個組織設定一次；郵件伺服器連線則用伺服器自己的詳細資料設定一次即可。[原生優先](/zh-tw/learn/build-it-well/native-first.md)說明了為什麼一個流程裡不該帶有任何憑證。 用程式碼實作：[頻道](https://engineer.imbrace.co/zh-tw/reference/channel/)。 ## 延伸並交付它們的三種方式 ### 技能——代理人能做什麼 技能是把一個工作流交給代理人，當成它可以呼叫的一個具名工具。它的用途是把代理人實際能做的事，延伸到對話之外——記錄一筆資料、查詢某項資訊、執行一項計算——一律透過工作流進行，絕不直接把數據表交給代理人。 在代理人的設定中，這位於**「行為設定」（Behavior Settings）**分頁下的**「功能」（Skills）**區塊裡（畫面上標示為「功能」，也就是本課程所稱的技能；SDK 的完整流程指南裡稱這些為 tools，歸在 Workflows 之下）。在這裡加入一個工作流，代理人就能在對話中呼叫它；它的描述文字，就是代理人判斷「現在是不是該用它」的依據。 畫面：AI智能助手的「行為設定」分頁，其「功能」清單 *1 「行為設定」（Behavior Settings）。2 AI智能助手的「行為設定」分頁，其「功能」清單。* 用程式碼實作：[完整流程指南](https://engineer.imbrace.co/zh-tw/sdk/full-flow-guide/)。 ### MCP 連線——程式碼工具如何看到一個組織 MCP 連線讓一個 AI 程式碼工具能直接看到並變更一個組織，而不是靠別人轉述才知道。它的用途是建置：用一個位址與一把金鑰把程式碼工具指向組織，它就能在寫下任何一行內容之前，先列出組織裡已經有哪些數據表與工作流。 在側邊欄中，這位於**行動模組 > 連接模組**之下的**MCP**分頁，而且它開啟的正是你原本會直接去讀的那份指南：[engineer.imbrace.co/mcp/overview](https://engineer.imbrace.co/zh-tw/mcp/overview/)。[設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md)會一步步示範如何用這種方式，把程式碼工具連接到一個測試組織。 畫面：連接模組的 MCP 分頁，開啟 MCP 連線指南 *連接模組的 MCP 分頁，開啟 MCP 連線指南* 用程式碼實作：[MCP 伺服器指南](https://engineer.imbrace.co/zh-tw/mcp/overview/)。 ### 安裝模組 安裝模組會把一整個使用案例——它的工作流、代理人設定與數據表——以單一套件的形式，一步到位複製進一個組織。它交給對方的是一個現成可用的起點，而不是一份要親手照做的說明。你的 iMBrace 聯絡窗口會把模組安裝進你的組織。 安裝完成後，它的數據表、工作流與代理人，會出現在各自平常所在的畫面裡——數據表、流程營運模組與 AI智能助手——管理員可以像對待組織裡其他任何東西一樣，在那裡檢視與編輯它們。若只需要單一個代理人，**AI智能助手**底下也有一個**「市場」（Marketplace）**分頁，提供現成的代理人範本可供套用。 畫面：AI智能助手的「市場」分頁，提供現成範本 *1 AI智能助手 > 「市場」（Marketplace）。2 現成範本卡片。* 用程式碼實作：[SDK 總覽](https://engineer.imbrace.co/zh-tw/sdk/overview/)。 ## 它們如何組合在一起 來自教學課程與[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)的 Harbor Bicycle Co. 退貨櫃台，一次用到了全部五種元件。顧客與 Return Desk Assistant 對話。這個代理人負責傾聽，而它唯一的技能——一個名為 Log return request 的工作流——會在 Return Requests 這張數據表上寫入一列新的資料。第二個工作流會依 Refund Rules 這張數據表算出退款金額。另一個工作流則負責詢問值班主管：它寄出一張附有「核准」與「拒絕」按鈕的卡片，然後等待。每個按鈕都會開啟一個讓主管確認的頁面；接著工作流從暫停的地方接續下去，把決定、審核者的姓名和時間記錄在該列，並以電子郵件通知顧客。這裡完全用不到文件模型，因為沒有任何東西是以檔案形式送達的——如果退貨是以一張掃描的裝箱單送來，就會先由文件模型讀取，再變成同一張數據表上的一列資料。 Harbor 的每一個元件，都可以打包成單一模組，安裝進第二個組織，讓它的數據表、工作流與代理人設定一起帶過去，交給那個組織自己的管理員開啟與調整。而讓程式碼工具一開始就能建置出這一切的同一條 MCP 連線，之後也能用它來檢查成果：列出數據表、讀取工作流最近一次的執行紀錄。 一步一步親手建置，請見[教學課程](/zh-tw/learn/build-it/vibe-coding-tutorial.md)；接著再讓它等一個人做決定，請見[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)。 ==================== build-guide.md ==================== --- level: '2' track: - build --- # AI 工具的建置指南 iMBrace 建置指南就是本課程的[建置得好](/zh-tw/learn/build-it-well/index.md)各頁、每一個好的 iMBrace 建置成果背後的原則，加上[設定你的程式碼工具](/zh-tw/learn/build-it/set-up-your-coding-tool.md)、[教學課程](/zh-tw/learn/build-it/vibe-coding-tutorial.md)與[讓它等一個人做決定](/zh-tw/learn/build-it/make-it-wait-for-a-person.md)——全部打包成 AI 程式碼工具自己就能讀取的純文字檔案，而不是一份需要你讀完再講給它聽的頁面。 ## 適用對象 任何正在用 Claude Code、Codex、Cursor，或其他能讀取專案檔案的 AI 程式碼工具，在 iMBrace 上建置的人。 ## 使用方式 先下載下方的指南，再把你的工具指向它。三種簡短做法： **Claude Code。** 把指南解壓縮到你的專案裡。它自己的 `CLAUDE.md` 只有一行：`@AGENTS.md`，所以只要你專案的 `CLAUDE.md` 會讀到它——不論是直接讀到，還是透過你自己加的一行 `@` 指向解壓縮後的資料夾——Claude Code 就會照著讀到 `AGENTS.md`。也可以改用技能：指南裡也附了一份 `SKILL.md`，所以把解壓縮後的資料夾安裝成 Claude Code 技能，效果一樣，而且完全不用改動 `CLAUDE.md`。 **Codex 及其他會讀取 `AGENTS.md` 的工具。** 把指南解壓縮，讓它的 `AGENTS.md` 落在你專案的根目錄，或是在你自己根目錄的 `AGENTS.md` 裡加一行指向它。任何已經遵循這個慣例的工具，都會用同樣的方式讀到它。 **Cursor。** 指南附了一個 `.cursor/rules/imbrace.mdc` 檔案。把指南解壓縮到你的專案裡，Cursor 就會讀到這條規則，而它會指向 `AGENTS.md` 本身的方法內容。 ## 事實從哪裡來 這份指南只談方法：如何把設計與建置做好。它從不複製 SDK、CLI 或 MCP 的事實，因為複製來的事實會過時。它會告訴你的工具即時抓取 [https://engineer.imbrace.co/llms.txt](https://engineer.imbrace.co/llms.txt)，並讀取它指向的那一頁。把你的工具連接到測試組織的方式也一樣：見 [MCP 指南](https://engineer.imbrace.co/zh-tw/mcp/overview/)。 ## 下載 - [AI 程式碼工具的建置指南（.zip）](https://engineer.imbrace.co/learn/imbrace-build-guide-community.zip) - [整門課程，給 AI 工具讀取（llms-full.txt）](https://engineer.imbrace.co/zh-tw/learn/llms-full.txt) - **可瀏覽的檔案**——`AGENTS.md` 及其他檔案，都在 [engineer.imbrace.co/learn/agent-pack/README.md](https://engineer.imbrace.co/learn/agent-pack/README.md) 之下 - **整份指南合併成單一檔案**，適合只讀取單一文件、而非整個資料夾的工具：[英文](https://engineer.imbrace.co/learn/llms-full.txt)、[繁體中文](https://engineer.imbrace.co/zh-tw/learn/llms-full.txt)、[簡體中文](https://engineer.imbrace.co/zh-cn/learn/llms-full.txt) ==================== build-it-well/index.md ==================== --- level: '3' track: - build verified_on: '2026-09-23' --- # 建置得好 一場展示證明的是某個東西能運作一次。建置得好，代表它能持續運作：使用真實資料、承受真實負載、有真人確實參與其中，而且不需要靠任何人刻意記得要小心。 這與寫更多程式碼無關。讓一個建置成果穩固的，大多是你在動手寫任何東西之前所做的設計選擇：你用哪些元件組裝它、由誰在哪個環節簽核、哪些工作交給平台本身的能力而非自訂程式碼，以及哪些內容絕不離開建置本身的設定。 ## 八大原則，一句話說明 1. **溯源性（Provenance）**——答案中的每一個數字都能追溯回它的出處，否則答案會直接說明查無此資料。 2. **確定性（Determinism）**——由 AI 判斷該套用哪一條規則；規則本身以資料的形式存在，可供人員編輯；運算則始終以相同、可靠的方式進行。 3. **模組化（Modularity）**——建置成果是由各自只做一件事、且有清楚介接規範的元件組裝而成，而不是一團龐大糾結的自訂邏輯。 4. **領域無關的核心（Domain-free cores）**——可重複使用的邏輯不帶有任何客戶名稱或特定業務細節；所有屬於單一企業的特有內容，都以設定的形式帶入。 5. **人為治理（Human governance）**——一個真正的決定是被記錄下來的事實——誰決定的、決定了什麼、何時決定的——而不是在聊天視窗裡打一個友善的「好」。 6. **原生優先（Native-first）**——在寫任何自訂程式碼之前，先使用平台本身已經提供的功能；建置成果中不應該存放任何登入憑證。 7. **可維運性（Operability）**——建置成果可以被重設、測試，並由他人獨立查核，而不是只能由建置者本人執行一次。 8. **安全與主權（Security and sovereignty）**——憑證、密鑰與敏感資料只留在設定中，絕不進入建置本身的邏輯。 ## 這一頁涵蓋什麼，其餘頁面涵蓋什麼 | 頁面 | 內容 | |---|---| | [八大原則](/zh-tw/learn/build-it-well/the-eight-principles.md) | 完整說明每一項原則：它的意思、做得好是什麼樣子、做壞了會是什麼樣子，以及你該問自己建置成果的問題。 | | [使用案例的形狀](/zh-tw/learn/build-it-well/use-case-shapes.md) | 業務使用案例常見的九種形狀，以及每一種通常由哪些元件組裝而成。 | | [人工核准](/zh-tw/learn/build-it-well/human-approval.md) | 一個人如何從附有「核准」與「拒絕」按鈕的電子郵件做出決定，並在頁面上確認——以及為什麼聊天室裡的一句回覆並不算是決定。 | | [原生優先](/zh-tw/learn/build-it-well/native-first.md) | 為什麼要先動用平台本身的能力，再考慮寫程式碼，以及這麼做能帶來什麼好處。 | | [文件模型](/zh-tw/learn/build-it-well/document-models.md) | 如何選擇「文件模組」（DocIQ）要從文件中擷取什麼：優先採用預設設定、視需要擴充，最後才考慮自行撰寫。 | | [反模式](/zh-tw/learn/build-it-well/anti-patterns.md) | 一再被建置出來的錯誤、每一種的代價，以及修正方式。 | | [審查清單](/zh-tw/learn/build-it-well/review-checklist.md) | 同一套八大原則審查，整理成一份檢查清單，方便你在交付前對自己的建置成果進行檢查。 | 這一切都不需要死記硬背。挑選符合你眼前所面對決定的頁面，運用其中的問題，然後繼續前進。 ==================== build-it-well/the-eight-principles.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 八大原則 八個概念，區分出「只能運作一次」與「持續運作」的建置。它們都不需要新奇的技術。多數是關於一段邏輯該放在哪裡、由誰來變更的決定。 ## 1. 溯源性 **這代表什麼。** 答案中的每一個數字，都能追溯到它的出處；若資料中沒有答案，回覆會明確說明。一個沒有來源佐證的數字，並不是「有來源數字的簡化版」——它是完全不同性質的東西，而這個差異在有人依據它採取行動之前，是看不出來的。 **做得好的樣子。** - 答案中的每一個數字，都附上其所依據的紀錄，以及資料更新至哪一天。 - 每一句引述都會與其聲稱出處的文件核對，且答案會說明它出現在該文件的哪個位置。 - 當資料中沒有答案時，回覆會明確說明，不會捏造數字來填補空缺。 - 每一種答案都有固定的格式——哪些數字、來自哪些來源、依什麼順序排列。固定的格式能在書面規則本身無法做到的地方，擋下捏造的數字。 **會怎麼出錯。** - **言之鑿鑿的摘要。** 由 AI 產出、讀起來很順的數字，背後卻什麼依據也沒有。它能通過審查，正是因為讀起來很順。 - **裝飾用的來源標註。** 來源清單只列出文件名稱，卻沒有指出具體的列或段落，導致沒有人能不重做一遍就核對該數字。 - **被悄悄淡化的發現。** 一個曾被標記的問題，在後續處理中被悄悄降級，卻沒有人注意到它已經變了。 - **只是存在的引述。** 檢查「引述句是否出現在來源中」，只能證明這句話存在，不能證明它支持所引用的結論。 **該問的問題。** 1. 挑一個近期答案中的數字。你能不問建置這個系統的人，就追溯到它的出處紀錄嗎？ 2. 答案是否附有資料的更新日期？ 3. 取一句引述。系統能證明它出現在來源中，並說出位置嗎？ 4. 當資料無法回答問題時，使用者實際上會看到什麼？ 5. 每一句引述，是否真的支持它所附加的結論，還是只是剛好出現在來源裡？ ## 2. 確定性 **這代表什麼。** 由 AI 判斷該套用哪一條規則，但規則本身是一份使用者可以閱讀、可以修改的資料。運算永遠以同一種方式執行。任何有實際影響的結果，都不會在 AI 自身的推理過程中被算出來；同一個問題問兩次，會得到相同的答案。 **做得好的樣子。** - 運算永遠經過同一個專屬的計算步驟，且每一項輸入都會顯示出來。 - 規則以使用者可以編輯的資料列或欄位存在，因此調整門檻值不需要開發人員或新版本發布。 - 系統尚未支援的規則，會明確拒絕執行，而不是被悄悄略過或用猜的。 **會怎麼出錯。** - **寫進提示詞裡的規則手冊。** 限制、標準或門檻值被寫進 AI 的指示中，沒有人能編輯、引用或稽核它們。 - **可以跳過的計算步驟。** 沒有任何機制強制 AI 使用專屬的計算步驟，於是在負荷較大時，它會自行算出結果——通常是對的，直到某次不對了，而且不會有任何提示。 - **混在一起的規則。** 系統自動套用的數字，與 AI 應當照原文引用的文字，被儲存在同一處，導致分不清哪個是哪個。 - **用否定句寫的規則。** 用「不可以發生什麼」的方式寫成的規則，無論是人還是模型，都容易讀反。把每一條規則寫成你想看到的條件，並把「兩者擇一」的要求維持為一條規則，而不是拆成兩條。 **該問的問題。** 1. 輸出中的每一個數字，具體是在哪裡被計算出來的？ 2. 業務人員能不能在不找開發人員的情況下，自行調整門檻值或限制？ 3. 把同一個問題問兩次，兩次答案是否完全一致？ 4. 當系統遇到一條它還沒被教過的規則時，目前會發生什麼事？ ## 3. 模組化 **這代表什麼。** 一個建置是由多個元件組裝而成，每個元件都有明確的職責與明確的介接方式，而不是一大團客製邏輯糾結在一起。只有當兩個各自獨立、指名可查的用途，都確實照原樣在使用同一個元件時，它才算「共用」——而不是因為它看起來像可以重複使用。 **做得好的樣子。** - 每個元件只做一件事，有明確定義的輸入與輸出，並且可以單獨測試。 - 被稱為共用的元件，確實有兩個真實的使用者，照原樣在使用它，其中至少一個用途並非它最初被建置的目的。 - 若兩個版本的差異在於內部細節被改動過，那它們老實說就是兩個不同的元件，而不是一個元件假裝通用。 **會怎麼出錯。** - **名義上共用。** 一個被標為可重複使用的元件，實際上只有一個真實使用者，於是下一個團隊繼承了一個從未成立的承諾。 - **另立門戶的副本。** 因為需要再多做一點調整，有人把整個元件複製了一份，而不是把它參數化。結果變成有兩份東西要維護，卻共用同一個名字。 - **沒有使用者的元件。** 因為看起來「大概用得到」而被建置出來，卻要永遠維護下去，實際使用次數頂多一次。 **該問的問題。** 1. 挑一個被標為共用的元件。指名它的兩個真實、各自獨立的使用者。 2. 是否有任何「變體」，其差異其實來自核心邏輯被改動，而不是來自設定？ 3. 一個元件能不能在不使用真實帳號、不連接網路的情況下，單獨測試？ 4. 建置中是否存在沒有真實、指名使用者的東西？它為什麼存在？ ## 4. 領域無關的核心 **這代表什麼。** 建置核心的可重複使用邏輯——代理人的核心指示、共用技能——不帶有任何客戶名稱、特定業務流程，或屬於單一公司的細節。所有屬於特定公司的內容，都以設定的形式提供，與核心並列，而不是寫死在核心裡。 **做得好的樣子。** - 核心讀起來像是在描述一個角色或一項工作，而不是把某一家公司的流程寫成一段文字。 - 每一項屬於特定公司的細節，都透過設定提供，核心本身不包含任何超出該設定所宣告範圍的內容。 - 只要更換設定，同一個核心就能服務不同的公司或不同的產業，不需要改動核心本身。 **會怎麼出錯。** - **寫死的業務內容。** 提示詞或邏輯本體中帶有某一家公司的產品清單、專有名詞或流程，一旦該公司的資料變動，內容立刻過時。 - **通用元件裡的公司名稱。** 一個以某筆交易或某位客戶命名的元件，下一個團隊若不重新命名、重新改寫就無法重複使用。 - **不誠實的設定。** 設定中宣告了卻從未被核心實際使用的項目，或是核心使用了卻從未在設定中宣告的項目——導致沒有人能說清楚核心究竟依賴了什麼。 - **寫死的位址。** 工作流中寫入了某台機器的網路位址，將建置綁死在單一網路上，一旦搬遷安裝環境，就得逐一找出並修改每個用到它的步驟。請以安裝環境自己的內部名稱來指稱服務，並向負責維運的人員確認。 **該問的問題。** 1. 在核心邏輯中搜尋公司名稱、帳號識別碼，或屬於特定客戶的用語。找到了什麼？ 2. 只更換設定，這個核心能不能服務不同的公司或產業？ 3. 設定中的每一項是否都確實被核心使用？核心是否完全不使用任何未宣告的項目？ 4. 是否有任何工作流中包含機器的網路位址？ ## 5. 人為治理 **這代表什麼。** 關卡是針對特定項目所記錄下來的決定——誰做的決定、決定了什麼、什麼時候決定的——而且預設為「失敗時關閉」：沒有記錄到決定，就不會有任何輸出發出去。使用者預設在自己原本工作的地方做決定——一封附有「核准」與「拒絕」按鈕的電子郵件，每個按鈕都會開啟一個確認頁面；但決定是否被記錄下來，則不是可以選擇的事。 **做得好的樣子。** - 關卡會根據底層資料自行算出答案，而不是直接相信 AI 在同一輪對話中剛說的話。 - 決定會被記錄下來，包括誰做的決定、決定了什麼、什麼時候——由系統本身擷取，而不是只出現在對話紀錄裡。 - 使用者在自己原本工作的地方做決定，文件就在眼前：一封按鈕會開啟確認頁面的電子郵件。單單打開連結，不會決定任何事；只有頁面上的「確認」才會。 - 任何有實際影響的事項都不會被自動核准。缺少決定會擋下輸出，而不是預設放行。 - 提出請求只是暫停流程，不是結束流程。一旦決定確立，同一個執行程序會自行繼續下去——完成工作，或通知提出請求的人——不需要有人再回來問一次。 **會怎麼出錯。** - **背後空無一物的關卡。** 一個要靠使用者手動更新的狀態欄位，卻沒有任何機制在監看它或依據其變動採取行動。看起來像有把關，實際上什麼也沒把。 - **填在儲存格裡的決定。** 使用者被要求在數據表裡選一個值來核准。那個值藏在一個他們沒有理由打開的表格裡，要儲存後才會生效，也讓人感覺不像是在做決定。 - **一打開就做出決定的連結。** 一個只要被造訪就會記錄決定的按鈕，會被第一個打開它的郵件掃描程式或預覽功能替人做出決定。 - **對話式的「好」。** 使用者對 AI 輸入「好」，卻沒有任何持久的紀錄留下，於是這個決定只存在於一份不會再有人讀的對話紀錄裡。 - **輕信的關卡。** 核准步驟直接採用 AI 提出的數字，而不是自行獨立算出，於是一個錯誤的數字能夠核准自己。 - **自我核准的代理人。** 代理人能透過它用來做其他事情的同一個工具，自行寫入決定——狀態、核准與否、決定者。用來記錄決定的欄位，應該在紀錄建立時就取得初始值，並拒絕代理人之後的任何寫入。 - **把「尚無結果」讀成「通過」。** 一項尚未執行、或執行失敗的檢查，會讓紀錄看起來和真正通過的一模一樣。為每一筆紀錄——包括明確通過的——都標註結果，並讓所有後續步驟等待這個結果，沒有結果就拒絕繼續。 - **問了就卡住的請示。** 決定被記錄下來了，之後卻沒有任何動作。提出請求的人得自己注意並主動追蹤後續。 **該問的問題。** 1. 出示最近一次決定的紀錄。誰、決定了什麼、什麼時候？ 2. 如果核准者無法出面，還會有任何東西被放行嗎？ 3. 關卡是自行算出答案，還是相信別人交給它的數字？ 4. 審核者原本在哪裡工作、他們看到什麼？那條路徑是否曾以那個人的身分從頭到尾走過一遍？單單打開連結，會不會決定任何事？ 5. 如果同一個決定送達兩次，會發生什麼事？ 6. 代理人能不能寫入記錄決定的欄位？ 7. 當檢查還沒為紀錄標註結果時，後續步驟會怎麼做？ 8. 分別核准它、拒絕它，以及讓其中一項保持未回應。在每一種情況下，流程是否都會自行繼續——完成工作，或回報結果——不需要有人問第二次？ 關於使用者如何從一封電子郵件做出決定、確認頁面做了什麼，以及為什麼單靠一句聊天回覆並不算是決定，請參見[人工核准](/zh-tw/learn/build-it-well/human-approval.md)。 ## 6. 原生優先 **這代表什麼。** 如果平台本身已經提供了做某件事的方式——搬移資料、發送訊息、等待某人處理、連接到另一個系統——就使用那個方式，而不是自己寫客製程式碼來做。如果你能把某項能力指名為平台的功能，用客製程式碼重新打造它，只會把這項能力藏起來、隨時間變得不易維護，而且通常最後會需要一組內建方式原本完全不需要的憑證。 **做得好的樣子。** - 建置可以透過平台自身的元件，一步一步讀懂，連非開發人員也能理解。 - 與其他系統的連線，儲存在平台自身的連線儲存區中，範圍受限且可重複使用，絕不會內嵌在建置的邏輯裡。 - 在確實需要客製程式碼的地方，它只針對拿到的輸入進行運算，不會自行呼叫其他任何東西。 - 任何例外都會被寫下來：考慮過哪項平台能力、為什麼沒有使用它，以及什麼條件下能夠停用這段客製程式碼。 **會怎麼出錯。** - **手工打造的捷徑。** 客製程式碼做了平台早已提供的事，通常是因為沒有人事先確認過。它通常會需要一組內建方式原本不需要的憑證，而且建置一旦搬到別的地方就會壞掉。 - **包裝過的腳本。** 一大段客製邏輯，表面上加了一層薄薄的 AI。它能得出正確答案，卻完全無法證明這個設計是否禁得起考驗。 - **不動聲色的憑證。** 一組登入資訊或金鑰被嵌在建置的某個角落，沒有人記錄下來，結果也從來沒有人回頭把它移除。 **該問的問題。** 1. 打開這個建置。非開發人員能不能說出每個步驟在做什麼？ 2. 在建置中搜尋任何看起來像憑證或存取金鑰的東西。找到了什麼？ 3. 針對每一段客製程式碼：曾經考慮過哪項平台能力？為什麼它不夠用？ 4. 把建置搬到不同的帳號或環境。什麼東西會壞掉？ 更多內容請見[原生優先](/zh-tw/learn/build-it-well/native-first.md)。 ## 7. 可維運性 **這代表什麼。** 讓建置持續運作，是建置工作本身的一部分，而不是事後才補上的想法：要有辦法把它重設回已知狀態、要有一組固定的測試案例可以用來評分、建置的每一種運作模式都真的被實際執行過，還要有第二道獨立的檢查，來確認第一道檢查的成果。 **做得好的樣子。** - 建置的每個部分都有測試，可以在不使用真實帳號或憑證的情況下執行，而且這些測試會在任何東西發布之前自動執行。 - 一組固定的測試案例，每次都用同樣的方式評分；無法執行的案例會被回報為「已跳過」，絕不會被悄悄算成通過。 - 第二道獨立的檢查會審視主要流程，並標出不一致之處，而不會自己悄悄把它修好。 - 建置可以在平台內部被重設回起始狀態，而不是靠某個人從自己的筆電手動還原。 - 工具傳回的錯誤訊息保持簡短，而且每一段對話的篇幅，都依執行它的模型的上下文長度來設計。 **會怎麼出錯。** - **沒被親眼看過的綠燈。** 一份「測試通過」的報告，是貼上去的，而不是真的被人看著跑過一遍。 - **各自的評分方式。** 每個建置都自創一套比對結果與預期的方式，導致任何兩次回報的分數都代表不同的意思。 - **無法重設的示範。** 一個只能成功運作一次的建置，之後每次要再展示，都得靠開發者本人手動把它重新組回去。 - **未經稽核的通過。** 一個結果就這樣被相信了，因為從來沒有其他人查核過它。 - **把狀態當成結果。** 一個步驟的狀態只能告訴你這個步驟跑過了；它原本該產出的紀錄，才能告訴你工作真的完成了。要查的是紀錄。 - **被盲目信任的標準答案。** 測試的標準答案是人寫的，可能有錯。當某個結果與標準答案不一致時，也要檢查標準答案本身，並同時依照原始版本與修正後的版本回報結果。 **該問的問題。** 1. 你是否親自執行了測試，並且親眼看著它通過？ 2. 固定的測試集放在哪裡？上一次評分是什麼時候？ 3. 重設這個建置。它是否會回到完全相同的狀態？ 4. 是什麼在獨立檢查主要流程？上一次發現不一致是什麼時候？ 5. 沒有參與建置的人，能不能只靠套件與文件就把它安裝並執行起來？ 6. 對每一個步驟而言，哪一筆紀錄能證明它的工作確實發生過？ ## 8. 安全與主權 **這代表什麼。** 在這類平台上，一組憑證是通往大量資源的鑰匙，而不是一組只對應單一小東西的密碼。要以這種心態對待它：範圍設定得越窄越好、存放在設定中、絕不內嵌在建置自身的邏輯裡、絕不提交進共用文件，也絕不作為工作上下文的一部分交給 AI 程式碼工具。 **做得好的樣子。** - 建置透過平台自身的連線來存取其他系統，因此其邏輯完全不含任何憑證，可以安全地被分享或搬遷。 - 任何刻意保留的例外，都會直接寫在建置本身上，說明它是什麼，以及在什麼情況下就不再需要它。 - 自動化檢查會在任何東西發布之前攔下其餘的問題：形似憑證的文字、內部機器名稱或檔案路徑、個人聯絡資訊，一概不放行。 - 敏感欄位的遮蔽，是由平台本身對底層資料強制執行的，而不是邏輯中一個可能被跳過或遺忘的步驟。存放未遮蔽原始識別碼的儲存區，永遠不會連接到任何 AI。 - 哪些 AI 模型能讀取資料，是依每個安裝環境、每個組織各自設定的。在讓個人資料進入系統之前，要向負責該安裝環境的人員確認：它所使用的每一個模型——無論用於對話、讀取文件或搜尋——都在部署範圍之內執行。 **會怎麼出錯。** - **圖方便的捷徑。** 為了回答一個棘手的問題，暫時把存放原始敏感資料的儲存區，直接連到 AI 上。「兩者分離」原本就是整個保障的關鍵，卻就這樣悄悄失效了。 - **藏在匯出檔裡的憑證。** 一份共用套件之所以能運作，是因為裡面帶著一組有效憑證，卻被交給了團隊以外的人。 - **無法分辨的憑證。** 流程中沒有任何標示，能把用完即丟的測試憑證與正式使用中的憑證區分開來，導致建置可能誤用錯誤的一組。請為測試憑證與正式憑證分別標示，並在分享或執行建置之前，先確認它持有的是哪一種。 - **未經檢查的匯出檔。** 分享匯出檔之前沒有先打開檢查過。每一份匯出檔在離開團隊之前都要先打開，確認裡面不含任何憑證、客戶資料或個人資訊。 - **傳進 webhook 裡的憑證。** 執行歷史會保留每次執行的輸入內容，以便日後查核——這正是憑證絕不該出現在 webhook 呼叫中的原因。應傳送識別碼，讓工作流使用已儲存的連線。 **該問的問題。** 1. 在即將分享出去的所有內容中，搜尋任何看起來像憑證的東西。找到了什麼？ 2. AI 程式碼工具能存取的憑證，是不是範圍受限、用完即丟的那一種？ 3. 敏感欄位的遮蔽，是由平台強制執行的，還是靠某個可能被跳過的步驟？ 4. 誰能看到未遮蔽的原始資料？實際上是什麼機制，阻止了 AI 被連接到它？ 5. 你上一次分享出去的套件，裡面實際上裝了什麼？ 6. 哪些 AI 模型會讀取這個建置的資料？其中是否有任何一個在部署範圍之外？ ==================== build-it-well/use-case-shapes.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 使用案例的形狀 大多數業務使用案例，其實沒有乍看之下那麼不同。看得夠多之後，你會發現它們可以歸納成少數幾種反覆出現的形狀。找出你的問題屬於哪一種形狀，你就有了第一版該組裝什麼的草案——這是拿來討論、修正的起點，不是定案的設計。 以下每一種形狀，先說明它看起來像什麼，再列出它通常是用哪些元件組裝而成。這裡列的是元件的種類與作用，不是特定產品——實際的組裝元件收錄在平台自己的元件庫中。 ## 1. 交易解算 **它看起來像：**有人用平實的話，要求算出或配置好一項有價格、有規格的東西——報價、預約，或是為他量身算出的一個特定方案。 **通常組裝自：** - 一個針對這類交易調校過的代理人 - 一個查詢既有紀錄的技能 - 一個搜尋相符紀錄的技能 - 一個執行運算、並顯示所用到每一項輸入值的技能 - 一個儲存運算結果紀錄的技能 - 一個依範本組合文件的技能 - 一個在任何東西送出之前，先以附確認頁面的電子郵件請人核准的技能 - 一個把完成文件寄給提出要求者的技能 - 在容量有限的情況下，一個依實際仍可用的數量（而非原始總量）保留名額的技能 ## 2. 擷取後台 **它看起來像：**文件陸續送達——發票、申請表、表單——需要變成經過檢查、結構化的紀錄。 **通常組裝自：** - 一個讀取送入文件的代理人 - 平台自身的文件擷取功能 - 一個在讀取前先把文件拆成各個部分的技能 - 一個比對兩筆紀錄的技能，遇到牽涉第三方來源時也能做三方比對 - 一個依規則檢查擷取數值的技能 - 一個找出重複紀錄的技能，即使寫法略有不同也找得出來 - 一個儲存紀錄的技能 - 一個在任何結果不夠明確通過時，請人做決定的技能 - 一個把結果訊息寄出的技能 - 一個獨立稽核前一輪處理結果的步驟 ## 3. 洞察服務台 **它看起來像：**有人用平實的語言，詢問企業內部某處已經存在的資料。 **通常組裝自：** - 一個專門用來回答資料問題的代理人 - 一個查詢底層紀錄、並回傳它實際執行的查詢內容（而非只給答案、不附推演過程）的技能 - 一個將紀錄分組並加總的技能 - 一個執行運算的技能 - 一個以電子郵件寄出答案的技能 - 一項新紀錄一出現，就把它連回其上層紀錄的自動化機制 當一個數字必須經得起查證時，使用上面那個查詢技能——它會連同答案一起回傳它實際執行的查詢內容，讓任何人事後都能核對這個數字。 ## 4. 對話式入口 **它看起來像：**一個任何人都可能上門的管道——聊天視窗、訊息應用程式、收件匣——而建置內容必須先弄清楚對方是誰，才能做任何有用的事。 **通常組裝自：** - 一個駐守在該管道上的代理人 - 一個驗證傳送者真實身分的技能 - 一個尋找相符紀錄的技能，並在找不到相符項目時有合理的備援做法 - 平台自身的文件擷取功能，用來處理以檔案形式傳送的內容 - 一個篩檢傳入自由文字、找出不該自動處理內容的技能 - 一個請人做決定的技能 - 一個核發一次性存取連結的技能 - 一個寄送訊息的技能 - 一個儲存紀錄的技能 ## 5. 多代理人審查 **它看起來像：**一個案件必須依照規則手冊來判斷，而這個判斷真的需要不只一種觀點——由一位主導者協調多位專才。 **通常組裝自：** - 一位主導代理人、一位或多位專責評估的代理人、一位規則手冊讀取者，以及一位報告撰寫者 - 一個查詢底層紀錄的技能 - 一個依規則檢查數值的技能 - 一個核對引用內容與其來源是否相符的技能 - 一個比對紀錄的技能 - 一個執行運算的技能 - 一個儲存結果紀錄的技能 - 一個請人做決定的技能 - 一個獨立稽核整個案件的步驟 ## 6. 自動填寫式 CRM **它看起來像：**筆記、通話與訊息不斷湧入，需要轉換成紀錄，且是由人來確認，而不是由人一筆一筆手動輸入。 **通常組裝自：** - 一個讀取送入筆記與訊息的代理人 - 一個把送入文件拆成各個部分的技能 - 一個核對引用內容的技能 - 一個儲存紀錄（包括任何隸屬於它們的巢狀子紀錄）的技能 - 一個持續記錄異動內容與時間的技能 - 一個在任何內容被視為定案之前，請人確認的技能 - 一個撰寫簡短報告的技能 - 一個撰寫並寄送電子郵件的技能 - 一項等待一連串相關活動穩定下來才動作的自動化機制，而不是一收到第一筆就動手、卻在其餘項目到齊時發現做錯了 ## 7. 合約與文件管理 **它看起來像：**一份長文件——合約、協議、長篇申報文件——驅動出一筆工作紀錄，以及一份必須依此執行的待辦排程。 **通常組裝自：** - 一個（有時是兩個協同運作的）讀取該文件的代理人 - 一個拆分文件、並將內容送到正確處理流程的技能 - 一個擷取大量欄位、並核對結果是否涵蓋完整欄位清單的技能 - 一個核對引用內容的技能 - 一個依規則檢查數值的技能 - 一個填寫範本的技能 - 一個核發一次性存取連結的技能 - 一個儲存產生檔案的技能 - 一項依固定週期執行整個流程的排程自動化機制 ## 8. 知識套件 **它看起來像：**使用者針對一批文件——政策、手冊、過往往來紀錄——提出問題。 這是最容易憑直覺做出錯誤選擇的一種形狀，所以值得拆成兩種來看： - **「我該怎麼做這件事」**是道地的搜尋型問題。平台自身內建的文件檢索功能，對一批文件就能處理得很好，不需要在它之上另外搭建任何東西。 - **「有多少」或「哪一份文件在哪一頁提到這件事」**則是計數與引用型問題，最好用紀錄來回答，而不是靠檢索。把每一頁都個別索引成一筆紀錄，再用一個查詢這些紀錄的技能，以及一個將紀錄分組並加總的技能。這樣一來，計數與引用就能做到精確無誤。 ## 9. 治理展示 **它看起來像：**這個建置的重點在於展示誰可以看到什麼——存取權限、遮蔽與稽核——而不是任何單一筆交易。 **通常組裝自：** - 平台自身的存取管理、檢視層級遮蔽、模型治理，以及讀取稽核 - 一個把代理人輸出內容中敏感欄位遮蔽起來的技能 - 一個篩檢文字的技能 - 一個核發一次性存取連結的技能 - 在平台的檢視層級遮蔽之外，再加一層對代理人自身答案的輸出檢查 ==================== build-it-well/human-approval.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 人工核准 每個重要的建置都會有一個時刻，需要有人先點頭同意，某件事才能送出去。請先設計這個時刻：要請誰決定、他們原本在哪裡工作、眼前有哪份文件、他們看到什麼，以及他們回覆之後會發生什麼事。 ## 決策是一回事，介面是另一回事 決策的部分，會根據背後的紀錄推算出該發生什麼事，在還沒有人做出決定時拒絕繼續進行，並且記錄下是誰做的決定、決定了什麼，以及什麼時候做的。這個部分不會因建置不同而改變。 介面——也就是一個人實際在哪裡、用什麼方式做出這個決策——依使用案例而選，但預設並不是可以隨意挑的：一個人在自己原本工作的地方做決策。對大多數審核者來說，那就是他們的收件匣。 ## 預設做法：附有「核准」與「拒絕」的電子郵件 審核者會收到一封電子郵件，裡面有做決策所需的一切：相關事實、文件本身（報價單、履歷、合約）的連結或附件，以及建議的處理方式。下方是兩個按鈕，「核准」與「拒絕」。 1. 建置暫停下來，並寄信給審核者。等待期間，不會有任何東西送出去。 2. 審核者閱讀這封郵件，文件就在眼前。 3. 按下其中一個按鈕，會開啟一個確認頁面，顯示他們所選的結果。單單打開頁面，不會決定任何事。 4. 只有在頁面上按下「確認」，才會記錄這項決策。另一個按鈕隨後就會失效，所以一個人只會給出一個答案。 5. 同一個執行程序接著往下走：完成工作——例如把文件寄給業務人員——並告訴提出請求的人發生了什麼事。 在建置任何東西之前，先用五行字寫下這個時刻：要請誰決定、他們原本在哪裡工作、眼前有哪份文件、他們看到什麼，以及他們回覆之後會發生什麼事。接著記住三件事。 - **以人、訊息和文件為主。** 這個時刻是一個人、一封郵件和那份文件，而不是一張表格。數據表只是它背後的紀錄。 - **郵件是一張卡片，而不是一則通知。** 如果審核者得另外打開別的東西才能做決定，就表示這張卡片少了一項事實。 - **每一條分支，都要結束在提出請求的人看得到的地方：** 已核准、已拒絕、已逾期、無人回覆。 ## 其他方式，以及何時使用 | 介面 | 運作方式 | 適用時機 | |---|---|---| | **附確認頁面的電子郵件** | 每種結果各一個按鈕；點開按鈕會顯示一個頁面，在上面確認才會寫入決策 | 預設做法，適用於每一位在收件匣裡工作的審核者 | | **紀錄上的一個欄位** | 一個人在數據表上切換狀態欄位；儲存之後，下一步就會觸發 | 備用做法，只在審核者原本就每天使用那個數據表工作時才用。不適合一般業務人員 | 不要要求業務人員藉由在數據表裡選一個值來核准。那個值藏在一個他們沒有理由打開的表格裡，要儲存後才會生效，也讓人感覺不像是在做決策。 哪些介面可以使用，取決於你的安裝環境與版本；你的 iMBrace 聯絡窗口可以幫你確認。不論你選擇哪一種，在依賴它之前，先以審核者的身分親自走一遍：他們收到郵件、打開、確認，然後建置把事情做完。 ## 不能通融的規則 **在聊天室裡友善地打一聲「好」，本身並不算是一項決策。** 那只是流程控制——它可能只是讓對話繼續下去——但它不會留下任何持久的紀錄，讓日後有人能夠指出：這件事在這個時間，由這個人核准。決策是一筆與特定項目綁定的紀錄，記錄了是誰在什麼時候做出決定。 還有兩條值得牢記的規則： - **關卡自己算出答案。** 它會根據背後的紀錄重新計算結果，而不是相信同一次互動中剛被告知的數字。一個只相信別人告訴它什麼的關卡，會很樂意核准一個錯誤的數字。 - **沒有決策，就沒有輸出。** 不是預設放行，也不是過一段時間逾時就自動放行。只要還沒有人做出決定，就不會有任何東西送出去。 ## 讓關卡真正守住的細節 - **打開連結，不會決定任何事。** 人、郵件掃描程式或預覽功能都可能打開它。造訪只會顯示頁面；只有確認那一步才會做出決策。 - **每個人一封郵件、一組按鈕。** 在你自己的紀錄上，記下這組按鈕屬於誰、他們何時確認，這樣「由誰核准」永遠來自你自己的紀錄。 - **第二個答案不會改變任何事。** 一旦有一個答案被確認，另一個結果就會失效，而且暫停之後的那一步，重複執行也是安全的。 - **確認頁面如實呈現。** 只有在決策確實被記錄下來之後，才顯示「完成」；如果沒有記錄成功，就明白說出來。 - **等建置真的在等待答案時，才寄出郵件。** - **代理人絕不能有寫入決策的能力。** 用來記錄決策的欄位，應該在紀錄建立時就設定好起始值，並拒絕代理人之後對它做任何寫入——只給代理人範圍狹窄、碰不到這些欄位的工具。 - **「尚未有結果」絕不能被看成「通過」。** 一項還沒執行，或執行失敗的檢查，會讓紀錄看起來和真正通過的一模一樣。請在每一筆紀錄上都蓋上結果戳記，包括乾淨無虞的那些，並讓之後每一個步驟都等待這個戳記、沒有它就拒絕繼續。 - **數據表的編輯，要到按下「儲存」（Save）之後才會生效。** 如果審核者確實使用數據表，請從已儲存的狀態測試這個關卡，並在給他們的操作說明中，加入「按下『儲存』」這一步。 ## 證明關卡確實有接上線路，而不只是擺在那裡 一個控制點的好壞，取決於它究竟綁定了什麼。把這個介面接到真正依賴它的東西上，並以審核者的身分，把整條路徑從頭到尾實際跑過一遍：對每一種結果——核准、拒絕、無人回覆——都啟動一次執行，從他們實際會收到的那封郵件回覆，然後確認工作已完成，或提出請求的人已被告知，而且不需要任何人再提示。在這件事做完之前，關卡都不算建好。 ==================== build-it-well/native-first.md ==================== --- level: '3' track: - build verified_on: '2026-09-23' --- # 原生優先 在寫自訂程式碼做某件事之前，先確認平台本身是不是已經能做到。這不是風格上的偏好。它會影響你的建置執行起來要花多少成本、搬遷時有多安全，以及日後別人要看懂它有多容易。 ## 一句話說完這個概念 如果有人能夠指出一項功能，並把它說成是平台的一個特色，那麼這項功能幾乎可以肯定早已內建在平台裡。自己用自訂程式碼重做一次，會把它的運作方式藏進一段得有人去讀才看得懂的程式碼裡，往往隨著平台演進而愈用愈過時，而且很常到頭來需要一個內建做法根本用不到的登入憑證。 ## 平台開箱即有的典型功能 這類平台本身就內建了大量現成功能：讀寫結構化紀錄、透過常見管道寄送電子郵件與聊天訊息、行事曆、試算表、檔案儲存、處理送入的文件、暫停流程等待人來處理、由一個流程呼叫另一個流程、在流程中做路由與迴圈，以及乾淨地停止一次執行。與各帳號及其他系統的連線，存放在平台自己的連線儲存區裡——只需設定一次，由建置參照使用，絕不會寫進建置自己的邏輯裡。 在寫下第一行自訂程式碼之前，值得先查一查平台目前的功能清單，看看有沒有現成的做法已經能完成這件事。新功能經常上線，最安全的預設做法永遠是先查再建。 ## 什麼時候真的有理由用自訂程式碼 以下兩件事必須同時成立： 1. **沒有任何內建功能能完成這件事**，而且你能具體說出自己查過什麼、為什麼那樣做不夠。 2. **這段程式碼是純粹的**——它只針對拿到的數值做運算，本身不會拿著自己的憑證去呼叫其他系統。如果它真的需要連到其他系統，也是透過平台自己的其中一個連線去做，而不是靠寫死在程式碼裡的金鑰。 任何偏離原生優先原則的例外，都應該明白寫下來：考慮過什麼、為什麼沒有採用，以及未來要滿足什麼條件才能撤除這段自訂程式碼。把這樣的例外當成一筆暫時、有名有姓的技術債來看待，而不是一個悄悄變成永久的選擇——一旦平台推出對應的內建做法，就立刻撤除它。 ## 為什麼這件事比聽起來還重要 - **建置裡永遠不該存放任何憑證。** 一個只使用平台自身連線的建置，裡面不會有任何登入資訊、API 金鑰，或任何同類的東西。這代表這個建置本身可以安全地分享、匯出，或搬到另一個帳號——裡面沒有任何東西需要輪替、遮蔽，或讓人擔心。 - **使用內建功能建置出來的東西，非工程背景的人也讀得懂。** 他們可以打開它，一步一步看清楚每個部分在做什麼，完全不必打開任何程式碼。自訂程式碼則會把這一切藏在一道只有工程師才讀得懂的牆後面。 - **它經得起搬遷。** 把一個用內建功能組成的建置匯出到另一個帳號，完全不需要重新接線。一個把憑證寫死在裡面的建置，搬過去就會壞掉，更糟的情況是，它會悄悄用錯的帳號權限繼續運作，卻不動聲色。像 Gmail 這類使用服務商登入的連線，是由有權限的人針對每個帳號各自授權一次；郵件伺服器（SMTP）連線則是用伺服器的詳細資訊設定一次即可。 ## 好的樣子是什麼 - 這個建置在平台自己的畫面裡可以一步一步讀下去，不必打開任何程式碼就看得懂。 - 在建置邏輯裡搜尋任何看起來像憑證的東西，什麼都找不到。 - 如果有任何一段自訂程式碼，都附有一則說明，寫出考慮過哪一項內建功能、為什麼它不夠用。 - 把這個建置搬到另一個帳號，它的行為完全不會變。 ## 一個實際範例 以一個報價代理人為例：寄出完成的文件完全不需要任何自訂程式碼——讀取紀錄、依狀態路由、格式化日期、寄出郵件、更新紀錄，這些步驟全部都是內建的。核准步驟的做法也一樣，用一個內建的任務，暫停流程直到有人做出決定，接著自動接續下去，把文件寄出。自訂程式碼通常只會用在少數幾件事上：運算本身、一次資料庫查詢、最後的驗證檢查，以及文件本身的版面配置。 ==================== build-it-well/document-models.md ==================== --- level: '3' track: - build verified_on: '2026-09-23' --- # 文件模型 當「文件模組」（DocIQ）讀取一份文件時——履歷、發票、採購單——**「文件模型」（document model）**會告訴它該擷取什麼內容、填進哪一筆紀錄。取得文件模型有三種方式，而且有嚴格的先後順序。 1. **採用組織的預設模型。** 平台內建了一個龐大的模型庫，包括履歷、發票、採購單和到職清單。採用其中一個不需要任何成本，而且日後這個組織上的每個建置，看到的都會是同一組欄位。 2. **只有在真的缺少某個欄位時，才擴充預設模型。** 請洽你的 iMBrace 聯絡窗口。把欄位加進預設模型，會讓所有組織都看得到這個欄位，而不是為單一客戶另外複製一份模型。 3. **只有在完全沒有預設模型可用時，才自行撰寫**，而且要用平台自己的風格來寫，這樣日後如果平台推出預設模型，才能乾淨俐落地取代它。 ## 不該做的事 - **把管理文件模型當成一個獨立、刻意的步驟，絕不是建置過程中的附帶結果。** 在建置實際執行之外，另外新增或修改文件模型，這樣每個讀取同一種文件類型的建置，指向的都會是同一個模型。 - **不要把模型的選擇交給運氣。** 只要一個步驟固定讀取同一種文件，就明確告訴它該用哪個模型，這樣每份文件都會落在你預期的那個數據表上。 ## 用你自己的文件驗證 在一項設計真正依賴它之前，先用你自己的幾份文件，逐一檢查以下每一點： - **龐大的模型。** 有幾十個欄位的模型，拆成幾次、各自聚焦的驗證會比較容易做。不論模型大小，都要拿每次的結果對照欄位清單，確認每個欄位都有被顧到。 - **巢狀的列。** 發票上的品項、履歷中工作經歷裡的每一份工作：在你的測試集中，確認每一個子項目，都會落在與其父項目相連結的數據表上。 - **本質上是一張表格的文件**——像是價目表、對帳單——其實是許多筆紀錄，而不是一筆。要把它當成一列一列來讀取。 - **看起來不像那個類型的文件。** 在測試集裡放進一些不典型的例子——像是沒有職責說明區塊的職缺說明、缺少標準標題的表單——並確認代理人會把無法辨識的文件如實回報為「無法辨識」，而不是回報成功。 - **組織層級的設定。** 「文件模組」的模型設定，是整個組織共用的。把你的建置測試時所用的設定，記錄在測試集旁邊，並在設定變動時重新跑一次整個測試集。 - **模型在哪裡執行。** 哪個模型會讀取你的文件，是依安裝環境與組織分別設定的。如果個人資料必須留在自有機房內，請在第一份真實文件送進去之前，請負責維運該安裝環境的人確認：「文件模組」所用的每一個模型——不論是用於讀取還是搜尋——都是在該安裝環境內部執行的。 ## 值得投入的設計選擇 - **模型愈少，愈省成本、也愈準確。** 分類時，會把每份文件拿去和組織裡的每一個模型比對，所以每一個沒在用的模型，都會增加成本，也多一個出錯的機會。只保留你真正會用到的模型；只要一個步驟固定讀取同一種文件，就把它指向那份文件的數據表，讓模型固定下來。 - **任何你會拿來分組或製圖的欄位，都給它一組封閉的詞彙表。** 把允許的值列在該欄位的說明裡，這樣分組和製圖，用的就會是一組固定、已知的詞彙。 - **描述每一種文件類型時，同時說明它是什麼、也說明它不是什麼。** 能點名出那些長得很像、但其實不是同一種類型的說明，才是真正能把它們區分開來的關鍵。 ==================== build-it-well/anti-patterns.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 反模式 以下每一項在當下看起來都很合理，這正是為什麼值得事先把它們一一點名出來。 ## 背後空無一物的關卡 一個原本該由人去更新的狀態欄位，卻沒有任何東西真的在關注它或依據它的變化採取行動。**代價：**它在審查時看起來像是有把關機制，實際上到了正式環境卻完全沒有——東西送出去了，卻沒有人真的核准過。**解法：**把這個欄位接上真正依賴它的東西，並且完整跑過整條路徑——包括「還沒有人做決定」這種情況——確認到底，才能說它已經完成。 ## 填在儲存格裡的決定 一個人被要求在數據表裡編輯一個值來核准。**代價：**那個值藏在一個他們沒有理由打開的表格裡，要儲存後才會生效，沒有一個業務人員會把它當成在做決定——於是核准來得很晚，或根本不來。**解法：**在他們原本工作的地方請他們決定：一封卡片式的電子郵件，按鈕會開啟確認頁面，文件就在眼前，之後再把決定記錄到那一列上。請參見[人工核准](/zh-tw/learn/build-it-well/human-approval.md)。 ## 問了就卡住的請示 一個建置向某人請示決定，卻在那裡停住。決定被記錄下來了，但下游什麼都沒有跟著動：文件沒有寄出，提出請示的人也沒有被告知，得靠他自己發現，再回頭重新問一次。**代價：**它通過得了審查，卻在正式環境中失敗——工作記錄下來了卻沒有做完，得靠人手動去追。**解法：**把「請示」設計成一有答案（核准、駁回，或懸而未決）就會自動接續下去，讓流程自己把事情做完，或至少自己回報結果。 ## 言之鑿鑿的摘要 一段 AI 產生、讀起來順暢，但背後其實什麼都沒有支撐的答案。**代價：**它正因為讀起來很有說服力才能通過審查，於是有人依據一個誰也追溯不出來源的數字做出決定。**解法：**要求每一個數字都必須附上它所依據的紀錄；答案不在資料裡時，就直接明講，而不是硬填一個進去。 ## 可以跳過的計算步驟 沒有任何機制強制把運算導向一個專屬、可查核的步驟，於是負載一高，AI 就自己把算式算完了。**代價：**它大部分時候算得沒錯，這才是危險所在——出錯的情況少見又不出聲，很容易一直沒被發現，直到有人去查核。**解法：**每一次都把所有運算導向同一個專屬的計算步驟，並顯示所用的輸入值。 ## 寫進提示詞裡的規則手冊 把限制、標準或門檻寫進 AI 的指示裡，而不是當成可編輯的資料存放。**代價：**業務人員沒辦法自己改一個數字，得經過工程師；也沒有人能查出某個案件到底是哪一條規則觸發的。**解法：**把規則當成資料，存放在非工程背景的人也能直接開啟、編輯的紀錄上。 ## 另立門戶的副本 把一個已經在運作的建置內部邏輯複製一份，做出一個近乎相同的版本來對付新案件，而不是把原本那個參數化。**代價：**多了兩份要維護、卻會悄悄愈走愈遠的東西，而且下一個接手的人往往根本不知道還有第二份副本存在。**解法：**用參數化取代複製。如果真的需要獨立的第二個版本，就給它自己的名字、自己的文件說明，而不是讓它冒充成原本那一個。 ## 手工打造的捷徑 用自訂程式碼去做平台早已內建的事，通常只是因為沒有人事先查過。**代價：**它通常需要一個原生做法根本用不到的憑證，而且一旦建置搬到別的帳號，就會馬上失靈。**解法：**寫任何程式碼之前，先查過平台目前的功能清單。詳見[原生優先](/zh-tw/learn/build-it-well/native-first.md)。 ## 未經核對的擷取結果 不加比對就直接信任一份擷取結果，沒有拿它和原本要求的內容核對。**代價：**沒有人拿輸出結果對照欄位清單時，漏掉一個欄位很容易被忽略過去。**解法：**每一次都拿結果對照欄位清單核對，欄位清單一長，就拆成好幾個各自專注的檢查步驟來做。 ## 檢索式計數 把計數或引用型的問題——「有多少」「哪一份文件、在哪一頁說的」——當成搜尋型問題來處理。**代價：**這類問題需要結構化紀錄才能精確回答；光靠檢索沒辦法把推演過程攤開來看。**解法：**把材料索引成結構化紀錄，再去查詢它們。把搜尋與檢索留給真正的「我該怎麼做」型問題。 ## 搶先觸發 一個流程對一連串相關活動裡最早出現的第一筆就做出反應，而不是等這一波活動穩定下來。**代價：**結果在其餘相關項目到齊之前就已經產生，等它們一到，這個結果不是錯誤就是不完整。**解法：**等這一波活動安靜下來，再一次性、依完整全貌採取行動。 ## 輕信的關卡 一個核准步驟，讀的是 AI 剛剛提出的數字，而不是自己依底層紀錄獨立算一次。**代價：**一個錯誤的數字可能就這樣核准了自己，因為從來沒有人拿它和源頭核對過。**解法：**這個關卡永遠自己重新推算一次答案。 ## 自我回報 一個建置自己回報自己的成功——一段看起來煞有其事、貼上來的結果，或是一個從來沒有人真正看著它跑過的「已完成」「上線中」狀態。**代價：**對一個從未被真正觀察過的狀態，卻有了信心。**解法：**自己動手跑一次，親眼看著它發生，唯有真的有人看過它運作，才能說它可以動了。 ## 繞過隱私防線的捷徑 為了回答一個棘手的問題，暫時把一份原始、敏感的資料庫直接接上 AI。**代價：**敏感資料與 AI 之間的隔離，正是整個隱私保證的全部內容，而這麼做，哪怕只是一瞬間，也已經讓這個保證悄悄失效。**解法：**絕不連接，哪怕只是短暫一下。如果一個問題真的需要原始資料才能回答，那就代表這個問題根本不該問這個 AI。 ## 藏在提示詞裡的標準答案 把預期答案——示範時該顯示的數字——直接寫進代理人自己的指示裡。**代價：**示範會通過，背後的工具卻是錯的，而且要等到有人問了一個真正的問題，才會被發現。**解法：**預期數值只放在測試集裡，絕不放進指示裡；代理人上線前的檢查，會拒絕任何含有這些數值的指示。 ## 把記憶當成資料來源 代理人用它記得的內容，或是很久以前附加給它的某份文件，去回答一個即時資料的問題，而不是去讀眼前的來源。**代價：**一個講得很篤定、內容卻是昨天數字的答案。**解法：**回答即時資料問題的代理人，不附加任何文件；給它一條固定規則，絕不把數字存進記憶、也絕不憑記憶作答；並保留一道能抓出過時答案的測試問題。至於需要維持一場對話的代理人，則要保留該對話自己的歷史紀錄——它需要靠這個，才能在後續堅持自己稍早說過的話。 ## 數字有爭議就讓步 某人提出自己的數字，代理人就放棄它原本正確、由工具算出來的數字，去附和對方。**代價：**答案變成了對話中最有把握的那個人說了算。**解法：**給代理人一條質疑規則——重新跑一次工具、試著用工具重現對方的數字，並清楚說明每個數字各自涵蓋什麼。 ## 樞紐分析表的快照 把轉換後試算表裡的樞紐分析表，當成它還在即時運算來讀。當一份 Excel 活頁簿被轉成 Google Sheets 時，裡面的樞紐分析表會停在轉換當下顯示的數值，不再更新。**代價：**從樞紐分析表拿到的每一個數字，都凍結在轉換當天，不管底下的資料列多新都一樣。**解法：**從原始資料列直接運算，並在任何顯示樞紐分析表的地方註明這一點。 ## 一次塞進整份工作表 把一整份龐大的試算表或表格，一次全部丟給代理人在單一輪對話裡處理。**代價：**這已經超過代理人一次能消化的量，後續的一切都建立在一份看似完整、實則只讀了一部分的內容上。**解法：**用平台自身的讀取步驟來讀取，在一個計算步驟中加總，只把算好的數字連同它們所依據的資料列、篩選條件與日期一起交給代理人。詳見[原生優先](/zh-tw/learn/build-it-well/native-first.md)。 ## 沒人用的共用元件 因為感覺上「應該會有用」而建置出來的東西，結果從來沒有真的被重複使用，卻還是持續被維護著。**代價：**持續投入維護成本，卻換不回任何價值，還讓人誤以為這個建置比實際上更模組化。**解法：**除非至少有兩個真實、獨立、有名有姓的需求存在，否則不要把某個東西標記為「可重複使用」。 ==================== build-it-well/review-checklist.md ==================== --- level: '3' track: - build verified_on: '2026-09-30' --- # 審查清單 這份審查清單，和內部使用的審查完全相同，只是改寫成你可以親自對自己的建置執行的版本。大約需要一小時，而且如果執行審查的人不是建置這個東西的人，會有用得多。 ## 如何執行 1. 把下面的評分表複製一份，放在你正在審查的建置旁邊。 2. 依序檢視每項原則的問題，這些問題取自[八大原則](/zh-tw/learn/build-it-well/the-eight-principles.md)。 3. 為每個問題評分：**已達成**、**部分達成**、**尚未達成**，或**不適用**。 4. 每個分數都需要一個**佐證**——某個具體、能證明這個分數的東西：一筆特定的紀錄、一段你親眼看著發生並貼上來的結果、一張實際行為的截圖。沒有任何佐證的分數，只是一個意見，不是審查。 5. 任何評為**尚未達成**的項目，要嘛在上線前修好，要嘛就寫一則附上日期的說明，記下是誰接受了這個缺口，以及原因。 ## 讓這件事值得做的幾條規則 - **審查者不是建置者。** 審查自己作品的人，往往只找得到自己原本就已經知道的問題。 - **實際執行，不要只是看過就算。** 不要因為一項測試看起來應該會過，就假設它真的會過。實際執行它，親眼看結果。 - **「不適用」需要理由。** 這是一個正當的分數，但沉默不算——寫下為什麼這個問題在這裡不適用。 - **部分達成不等於通過。** 它是一個有名字、有負責人的缺口，最好還附上一個日後要重新檢視的日期。 - **這份審查的對象是建置，不是人。** 目的是讓成果變得更好，而不是對建置的人做出評斷。 ## 1. 溯源性 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 不需要別人幫忙，能不能從輸出結果中的一個數字，直接追到它背後的紀錄？ | | | | | 2 | 答案有沒有附上「截至」的日期？ | | | | | 3 | 被引用的那一行，有沒有對照來源、並附上位置來證明？ | | | | | 4 | 當資料無法回答這個問題時，使用者會看到什麼？ | | | | | 5 | 每一行被引用的內容，是不是真的支持它的結論，還是只是剛好出現在來源裡？ | | | | ## 2. 確定性 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 每個數字，具體是在哪裡計算出來的？ | | | | | 2 | 業務人員能不能在不需要開發人員協助的情況下，自行更改門檻值？ | | | | | 3 | 同一個問題問兩次，會不會得到同樣的答案？ | | | | | 4 | 當系統遇到一條它還沒有實作的規則時，會發生什麼事？ | | | | ## 3. 模組化 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 任何被標示為「共用」的東西，請說出兩個真實、各自獨立的使用情境。 | | | | | 2 | 有沒有任何變體，實際上是靠修改內容做出差異，而不是靠設定？ | | | | | 3 | 一個元件能不能在沒有正式帳號、也沒有網路連線的情況下，單獨被測試？ | | | | | 4 | 這個建置裡，有沒有任何東西找不到一個真實、指名道姓的使用者？ | | | | ## 4. 領域無關的核心 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 核心邏輯裡，有沒有出現公司名稱，或特定客戶才有的細節？ | | | | | 2 | 只要改變設定，這個核心能不能拿去服務另一間公司？ | | | | | 3 | 設定裡的每一項，是不是都真的有被用到；而每一個被用到的項目，是不是都有在設定裡宣告？ | | | | | 4 | 有沒有任何工作流裡，包含某台機器的網路位址？ | | | | ## 5. 人為治理 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 出示最近一次決策的紀錄。是誰、決定了什麼、什麼時候？ | | | | | 2 | 如果核准者聯繫不上，還會不會有東西被送出去？ | | | | | 3 | 這個關卡是自己算出答案，還是相信別人交給它的答案？ | | | | | 4 | 審核者原本在哪裡工作？那條路徑是否曾以他們的身分從頭到尾走過一遍？單單打開連結，會不會決定任何事？ | | | | | 5 | 同一個決策送達兩次，會發生什麼事？ | | | | | 6 | 代理人能不能寫入記錄決策的欄位？ | | | | | 7 | 當檢查還沒有在紀錄上蓋章時，後面的步驟會怎麼處理？ | | | | | 8 | 分別核准一筆、拒絕一筆，再留一筆不處理。每一種情況，流程是不是都會自己往下走？ | | | | ## 6. 原生優先 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 一個不是開發人員的人，能不能看懂這個建置，說出每一步在做什麼？ | | | | | 2 | 搜尋整個建置，會不會找到任何長得像憑證的東西？ | | | | | 3 | 每一段自訂程式碼，當初考慮過、後來又放棄了哪個內建功能？為什麼？ | | | | | 4 | 把這個建置搬到另一個帳號上，會有什麼東西壞掉？ | | | | ## 7. 可維運性 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 你有沒有親自執行過測試，並且親眼看著它們通過？ | | | | | 2 | 固定測試集放在哪裡？上一次評分是什麼時候？ | | | | | 3 | 重置之後，這個建置會不會回到完全相同的起始狀態？ | | | | | 4 | 有什麼東西是獨立在檢查主要路徑的？它上一次和主要路徑的結果不一致，是什麼時候？ | | | | | 5 | 一個完全不認識這個建置的人，光靠套件和文件，能不能把它裝起來、跑起來？ | | | | | 6 | 每一個步驟，是哪一筆紀錄能證明它真的執行過？ | | | | ## 8. 安全與主權 | # | 問題 | 分數 | 佐證 | 備註 | |---|---|---|---|---| | 1 | 即將被分享出去的東西裡，有沒有任何長得像憑證的內容？ | | | | | 2 | 任何 AI 工具能存取到的憑證，是不是範圍有限、用完即可丟棄的？ | | | | | 3 | 敏感欄位的遮蔽，是由平台強制執行，還是靠一個可能被跳過的步驟？ | | | | | 4 | 誰能看到未經遮蔽的原始資料？實際上是什麼機制，阻止了 AI 被連接到這份資料？ | | | | | 5 | 你上一次分享出去的套件，實際上包含了什麼？ | | | | | 6 | 有哪些 AI 模型會讀取這個建置的資料？其中有沒有任何一個在部署環境之外？ | | | | ## 已接受的缺口 | 缺口 | 目前為什麼可以接受 | 接受者 | 日期 | 何時重新檢視 | |---|---|---|---|---| | | | | | |