跳到主要內容

【2026 最新】Mastra Factory 教學:一張 Issue 怎麼交付 PR?六步核對批准、Preview 與身分

最後更新: ·
Mastra Factory 教學:Issue 接單、計畫批准與 PR 交付的逐關簽收

你把一張「修改首頁按鈕」的 Issue 交給 Agent,下一步卻不知道該去哪裡看:有沒有進單?計畫批准後改了哪些檔案?PR 又是用誰的帳號提出?這篇 Mastra Factory 教學,帶你把這條交付路線拆成能逐項核對的步驟。

本文專為第一次接觸軟體工廠的讀者寫,名詞會先翻成白話。你會拿到一張可複製的練習 Issue、計畫改稿範例,以及 Preview、程式差異與 GitHub 身分的驗收清單。動手部分需要 GitHub 測試倉庫、Node.js/npm、Git,以及有權使用的模型與執行環境。

以下依 2026 年 11 月 22 日查閱的官方文件、公開套件與原始碼整理,採文件導讀與操作驗收的寫法;AlphaLab 未在本次連接帳號完成 Issue 到 PR 的端到端執行。先用不含客戶資料、正式金鑰的測試倉庫練習。

先說結論:Factory=接單+執行環境+逐關簽收

把 Factory 想成有工單、工作桌和簽收欄的裝修隊。模型負責想與寫,sandbox 是動工的工作桌,Issue 是需求單;你接受任務、批准計畫、決定合併 PR,則是不同的簽收。這句口訣是幫助理解的比喻。

今天的完成標準很小:同一張 Issue 有可追蹤的卡片、範圍清楚的計畫、看得見的修改與檢查,最後留下能審閱的 PR。先把每個交接點接好,再提高自動化程度。

一、Mastra Factory 教學先認四個零件

官方產品頁把 Factory 定位成可設定的軟體交付環境。它把倉庫、持續工作的 coding agent、需求接收、計畫、實作與 PR 審查串起來。你可以理解成「管理程式修改流程的應用」,底下再使用 Mastra 的執行能力。

  • Repository(程式碼倉庫):真正要修改的專案。Factory Server 自己的專案與目標倉庫分開放,避免把管理工具的設定混進產品。
  • Model(模型):調查、規畫與撰寫的能力來源;帳號能用哪個模型,要到供應商與 Factory 連線各自確認。
  • Sandbox(執行工作區):存放專案副本、相依套件並執行指令的地方;要再確認它位於本機或雲端。
  • Board 與 Session(看板與工作對話):前者記錄進度與規則,後者保存問題、命令、檔案與修改,供你接續判斷。

Agent 與執行層的分工,可以先讀 Agent Harness 是什麼。這裡真正要學的是把能力接進交付程序:卡片到了下一欄,還要找得到相應的成果。

Mastra Factory 教學:Intake、Planning、Building 與 Review 的交付驗收流程
AlphaLab 原創流程示意:接到需求、批准計畫、查看修改、審閱 PR,分別留下不同證據;不是產品介面截圖。

二、Mastra Factory 教學六步:從一張 Issue 到可審閱的 PR

第 1 步:「管理工具放哪裡?」先建獨立專案

先分開兩個資料夾。假設你的測試網站已在 GitHub,有初始 commit,且 README 記錄了能執行的啟動與檢查命令。在它外面的資料夾開終端機,先執行 node --version、npm --version 與 git --version。

本次公開的 create-factory 為 0.5.1;其 Node 門檻與下載後模板的要求應一起看。本文準備 Node.js 22.19.0 以上,涵蓋本次模板的最低要求(固定版本設定)。CLI 參考文件說明,預設流程會登入平台、安裝相依套件並配置資源。確認組織與費用後,再於目標倉庫外執行:

npx create-factory@0.5.1 factory-issue-lab
cd factory-issue-lab

這裡固定安裝器版本,下載的模板與解析出的相依套件仍可能更新。保存生成後的 package.json、lockfile 與版本筆記,別把一個 CLI 版號當成整套環境已鎖死。

先在編輯器檢查 .env 是否已有非空的 FACTORY_CREDENTIAL_ENCRYPTION_KEY。若已有,保留並安全備份;若缺少,才用 openssl rand -base64 32 產生一次,寫入該設定。官方入門與 README 對是否自動產生的描述有出入,檢查實際檔案能避免誤覆蓋。金鑰換掉,原本加密儲存的憑證可能就讀不回來。

確認加密設定後,再執行 npm run dev,開啟終端機印出的本機 URL,登入並建立 Factory。

如果改用 --no-platform,依 官方入門自行配置認證、儲存與 sandbox,再啟動。它省略平台配置,並不等於應用已具備可工作的全部服務;本篇初學路線先維持同一種配置。

第 2 步:「倉庫看得見,為什麼沒進單?」分開兩個開關

先接工作現場,再選接單來源。在 Choose your codebase 選測試網站;若沒出現,用 Manage GitHub connection 檢查安裝的是哪個 GitHub 帳號/組織,以及 App 是否獲准存取該倉庫。練習時只授權需要的倉庫。

選好 codebase 後,依 onboarding 連接有權使用的模型供應商並選模型;後續可在 Settings → Models 更改。先核對憑證是個人或組織範圍,模型授權與倉庫授權各有自己的開關。

接著到 Settings → Work Intake → GitHub issues,開啟 Sync GitHub issues,勾選測試倉庫,等到儲存完成,再回 Work → Intake。Intake 文件明載來源選擇為組織共用;更動前先確認自己操作的是測試組織的來源。

此時才新增下面這張 Issue。舊 backlog 的處理在目前文件與程式有差異,驗收先用「接好來源後新建的一張」,比用歷史 Issue 猜同步是否成功更清楚。把來源號碼、標題與 GitHub 連結對上同一張卡,才算通過進單這一關。

標題:首頁「開始使用」按鈕補上鍵盤焦點樣式

需求:沿用現有設計,讓鍵盤使用者能辨認目前焦點。

驗收條件:
- 只改首頁指定按鈕與必要樣式,不新增套件。
- Tab 能移到按鈕,焦點輪廓清楚,Enter 維持原連結行為。
- 以 390px 與 1280px 視窗檢查文字、版面與焦點。
- 使用 README 已有的檢查命令,記錄結果與未完成項。
- 提供 Preview 與 PR,交由人審閱後決定是否合併。

390px 與 1280px 是這次練習自己訂的驗收寬度,不是 Factory 的規格。若你的測試網站沒有這顆按鈕,先把 Issue 改成確實存在的頁面與元件;不要要求 Agent 先猜專案裡有什麼。

第 3 步:「先調查,還是直接動工?」保留計畫簽收

先讓每個階段等你啟動。到看板的 Configure 檢查各 phase(階段)的 Start on its own;練習維持關閉。也檢查計畫出口的 Approve on its own,維持人工批准。設定位置與作用見 Boards and rules。

啟動調查前,先依 FactorySandbox 參考文件 核對 provider。本次已發布套件的預設本機開發路線使用本機工作區;若你要雲端隔離與遠端 Preview,先明確配置遠端供應商並核對日誌,再開始 run。別把 localhost 的管理畫面當成雲端執行的證明。

在 Intake 選 Investigate,開啟卡片的 Session。先回答 Agent 對元件位置、現有設計或檢查方法的提問。接受任務時,依卡片選單選 Accept and plan,接著檢查計畫;不要為了跳過等待而直接選 Build。

Work items 文件把接受任務、批准計畫與合併 PR 分成不同決定。讀計畫時至少核對:要改哪些檔案、怎麼維持滑鼠操作、用哪些現有命令、如何交 Preview 與 PR。若它要新增一整套 UI 套件,先在同一個 Session 回覆:

請先修訂計畫:僅修改現有首頁按鈕的焦點樣式,不新增套件,也不調整導覽。請列出實際檔案、現有檢查命令,以及 390px/1280px 的鍵盤驗收方式;修訂完成後等待我批准。

重新讀完修訂版再批准,並把批准的範圍記下。這樣中途改稿有具體邊界;「Agent 已看過需求」與「你同意這份實作計畫」就能分開核對。

第 4 步:「它說測試通過,證據在哪?」對檔案與輸出

從 Building 追到實際工具輸出。在 Session 的檔案與 changes 視圖看 diff(修改前後差異),對照首頁元件與樣式是否真在計畫範圍內。再讀每個檢查的命令、工作目錄、退出結果;失敗要保留,跳過也要保留。

依 Session 操作文件,遇到命令失敗時先查錯誤與 setup,再在原 Session 給具體下一步。例如相依套件沒裝好,先補正倉庫的 setup;別反覆開新 run,把同一個前置錯誤變成多筆帳單。

每次 Session 的副本要能安裝專案所需套件。到 Settings → Repositories 展開倉庫,填它真正支援的 Setup 命令。本文不替你的專案杜撰 npm test;有 lint、build 或瀏覽器測試,就逐項記結果。改了按鈕後,仍須手動做下一步的鍵盤驗收。

第 5 步:「畫面能開就交貨?」Preview、diff、PR 身分一起驗

先確認工作桌的位置。Sandbox 文件區分雲端供應商與直接在 Factory Server 主機執行的 LocalSandbox。查啟動日誌,雲端再對到供應商控制台的同一 Session;本機則確認獨立工作目錄。獨立資料夾不等於虛擬機隔離,測試時避免把正式環境憑證交給它。

要求 Agent:「啟動此倉庫文件中的開發伺服器,回報命令、port 與 Preview 連結。」Preview 文件說明,遠端預覽需要具備網路能力的 sandbox;本機執行則開自己機器的 port。平台預覽預設要求組織登入,練習保留 Public preview links 關閉。

在 Preview 實際按 Tab、Enter,縮放到 Issue 的兩個寬度,再看 PR 的 Files changed 與檢查結果。Preview 驗畫面與操作,diff 驗修改範圍,CI 驗已設定的檢查。三者各有工作,缺一項就在驗收紀錄寫缺一項,別用「頁面打得開」代簽全部。

PR 身分另做一輪對帳。GitHub 設定文件把 App 倉庫連線與 sandbox 的 GitHub CLI token 分開:Settings → Repositories → GitHub CLI tokens 可設定 classic personal access token(傳統個人存取權杖),另有 reviewer token。遇到 sandbox 的 gh 授權失敗時,再依該節檢查類型、帳號與倉庫存取範圍;先別為排錯任意擴大權限。若執行使用這些 token,帳號權限與審查身分就跟該憑證有關。不要只看到 App 已安裝,就推定 PR 一定由某個 bot 提出。

  • 開 PR 頁面,記下建立者與來源 branch;若帳號不符合預期,先停在審閱。
  • 打開 commit 詳細資料,另看 author、committer 與簽章狀態;它們回答的問題各不相同。
  • 審查帳號也核對,尤其沒有獨立 reviewer token 時;同一帳號的回報不當成第二位獨立審查者。
  • 保留 Issue、Session、Preview、PR、檢查輸出與同一版 commit 的對應,避免看了新版畫面卻審舊版 diff。

Preview 無回應時先查 server 是否仍在執行、port 是否正確,以及 sandbox 是否已暫停。官方文件指出暫停也會停止 server;請 Agent 重啟後再開。遇到 Host 拒絕,先查開發伺服器設定與預覽主機名,不要直接把私人測試環境改成公開可存取。

第 6 步:「練完怎麼收工?」留下收據,再撤除測試權限

先完成審閱,再決定是否合併。Review items 文件明確區分 Agent 審查結束與 PR 合併。這次測試可以停在可審閱的 PR;若要合併,照倉庫原有流程確認驗收條件與必需檢查。

在筆記留一份「執行收據」:日期、CLI/模板/相依版本、模型識別、sandbox 供應商與資源、執行時間、重試原因、模型用量與平台用量。平台計費頁把運算、連線、資料流量與觀測事件分列;模型費用再依你連接的供應商核對。軟體開源與這次執行花多少錢,要分開記帳。

收工時先確認 PR 和需要的修改已推送,關閉測試來源同步;若共用 App 或 token,先核對它是否還供其他專案使用,再透過 GitHub 正常設定撤除這次測試授權、撤銷專用 token。平台上的測試專案、sandbox 與其他資源也逐一確認並依需要停止或刪除;單純關閉本機終端機,不當成遠端資源已清除的收據。

Mastra Factory 教學驗收清單:Preview、程式差異與 PR 身分分開核對
AlphaLab 原創驗收圖:畫面、修改範圍、執行身分三條證據分開查看,再決定是否合併。

三、三個常見卡點:先找交接點,再重跑

Intake 空白:依序查 App 倉庫權限、連結的 codebase、Work Intake 的同步開關與來源、儲存是否完成;使用剛建立的 Issue 對號。這些都對了,再讀 官方排錯流程與伺服器日誌,別先建立十張相同 Issue。

卡片等待:分清「等人啟動」「等接受任務」「等計畫批准」「命令失敗」。前三種是不同的工作決定,最後一種才要讀工具錯誤。新版內建 Work 階段與較早專案可能不同,看到 Triage 時先看該專案設定,不必硬套別人的看板截圖。

預覽正常,PR 卻多改檔:回到批准過的範圍,要求撤回無關修改,重新跑受影響的檢查。若 sandbox 已壞,要先保存已推送的成果;重建會丟掉未提交推送的工作區內容,不能把重建當成無成本的重新整理。

四、常見問題:八個先講答案的判斷

1. 已連 GitHub,Issue 就一定進來嗎?

先查 Intake。倉庫連線與來源同步是兩個步驟;用新建 Issue 的號碼、標題與連結逐項驗收。

2. 接受任務,就是批准實作嗎?

分開看。接受是讓任務離開 Intake;批准計畫才是同意那份實作安排,PR 合併再做一次決定。

3. 本機開了 Factory,程式一定在雲端跑嗎?

不一定。先查實際 sandbox 供應商與啟動日誌;本機工作區和雲端虛擬機的隔離邊界不同。

4. Preview 連結開不起來,代表程式壞了嗎?

先查執行狀態。開發伺服器、port、登入與 sandbox 暫停都在排查範圍,不能只憑連結失敗就定根因。

5. PR 會用我的個人帳號嗎?

要查憑證與實際 PR。App 連線、CLI token、reviewer token 與 commit 身分分別核對,不預設固定作者。

6. 舊 Issue 沒出現,就重複新增全部嗎?

先用一張新單驗收。當前文件與程式對歷史匯入有差異,別大量複製 backlog 來試同步。

7. 這篇證明 Factory 能替團隊省多少時間嗎?

本篇提供操作與驗收方法。團隊節省量需要用自己的任務,記錄等待、檢查、重做與合併時間後比較。

8. 完全新手今天先做到哪裡?

先讓一張新 Issue 進 Intake,讀懂它的調查與計畫。能指出預計修改的檔案及驗收方法,再批准下一關。

給新手的三個重點

  • 接好倉庫,再接 Intake;卡片與原始 Issue 要對得上。
  • 接受任務、批准計畫、合併 PR 分開簽收,改稿留在同一份工作脈絡。
  • 驗收同時看 Preview、diff、檢查與身分,最後把資源與權限收乾淨。

接著閱讀

左右滑動查看更多推薦

下一步:先替一張工單完成逐關簽收

回到那句口訣:Factory=接單+執行環境+逐關簽收。今天先用一個小修改完成四份紀錄:Issue、批准的計畫、修改與檢查、可審閱的 PR。四份能對上,再把同一份方法用到第二張工單。

想繼續補齊開發觀念,可以到 AlphaLab AI 專區找下一個主題,或用 AlphaLab 課程安排自己的練習路線。先練會驗收一次,再讓 Agent 多跑一步。

ALPHALAB 社群

有問題?來 Telegram 聊

和 Terry、編輯、其他網友一起討論這篇文章。提問、分享觀點,回覆更即時。

加入 Telegram 討論

📩 訂閱 AlphaLab 電子報

週日 Weekly 週報+週二、週四 Alpha Signal,每週最多三封。

我們不會 spam,隨時可退訂。已訂閱?管理訂閱偏好(會寄登入連結到你的信箱)

主題篩選與退訂說明

寄送日期以台灣時間為準。主題偏好會篩選每期精選,並非每篇新文章的即時通知;當期符合主題的文章不足時會略過寄送。

未勾選任何主題會收到所有主題的精選,並不會停止寄信。

取消勾選 Alpha Signal 可停止週二、週四短報,仍保留週日週報。若要停止所有電子報,請使用信件底部的「取消訂閱」。