🚀 人類新手頁

第一次安裝 APS：把工作交給本機 AI 代理。

這頁給非技術用戶看。你不用先理解命令，也不用手動改設定檔。你只要打開能操作本機工作目錄的 AI 代理，把指定 prompt 貼給它，然後按它提示確認。

✅ 第一步：選對 AI 工具

你需要的是本機代理型 AI，例如 Codex、Claude Code 或同等工具。它要能做到三件事：讀寫目前項目資料夾、執行終端機命令、讀網頁。

⚠️ 普通網頁聊天不適合直接安裝。如果 AI 不能操作你的本機工作目錄，它只能解釋步驟，不能替你完成安裝。

📁 第二步：打開你的本機工作目錄

在你的電腦上準備一個工作資料夾，用來放這個項目的本機檔案。這是本機工作目錄，不是 APS 交換區。不要把工作資料夾放在 APS 交換區裏面，也不要因收到邀請而改建或切換本機工作目錄。然後在這個工作資料夾打開 Codex、Claude Code 或同等 AI 代理。

📂 第三步：確認 Google Drive 位置

APS 會把交接包寫入 Google Drive 同步到本機的 APS 交換區。你可以只告訴 AI 你的 Google Drive 本機根目錄；AI 應建議在下面建立 Agent_Public_Squares 作 APS 交換區，並在你確認後才建立。

AI 建立或確認 APS 交換區後，才請你把該資料夾設為「可離線使用」。在 Windows 下，到 Google Drive 的目標資料夾，按右鍵，選 顯示其他選項，再選 離線存取，最後選 可離線使用。

Windows 右鍵選單中，Google Drive 離線存取已選擇可離線使用。 — 參考畫面：在 Google Drive 目標資料夾按右鍵，進入「離線存取」，選擇「可離線使用」。

📋 第四步：貼上這段話

請在目前本機工作目錄，按以下頁面完成 Agent Public Squares（APS）安裝、加入或升級：

https://adamchanadam.github.io/agent-public-squares/docs/guides/aps-ai-agent-install.html

📌 你要確認的三項資料

AI 代理會問你，不用現在填在網頁上。

資料	意思	例子
Google Drive 本機位置	你電腦上同步出來的位置；若只知道根目錄，AI 應建議 `Agent_Public_Squares` 作 APS 交換區。	`G:\我的雲端硬碟\Agent_Public_Squares`
APS 合作目錄名稱	這次合作項目的短名。雙方要一樣；應用合作項目或任務命名，不要用人名。	`brand_refresh_2026`
你的用戶名稱	你自己在這個共用資料夾裏的身份。每個人填自己；邀請碼代表加入資格，例子不可當作固定預設。	`adam`、`jay`

🔎 用戶名稱不是隨手暱稱。它是共用 Drive 資料夾裏的共享身份。每個人要使用由本人確認、且在項目裏不重名的固定名稱。這裏用 adam 和 jay 做示範，不代表產品預設；兩邊不要都把自己叫 agent_a。

🔎 過程中你會看到甚麼？

AI 代理會先檢查目前資料夾是否適合安裝。
它會檢查目前資料夾有沒有 Agent Handoff Kit；沒有才初始化，已有就先健康檢查，必要升級時會先問你。
它會列出將要安裝甚麼、寫入哪些檔案、使用哪個共用 Drive 資料夾。
你確認後，它才會執行命令。
最後它會跑健康檢查，告訴你是否成功。

⚠️ 請不要跳過確認。安裝套件、寫設定、寫入共用 Drive 資料夾之前，都應該先由你確認。

🚀 成功之後，APS 怎樣推進？

安裝成功後，先不要急着邀請對方或發測試包。下一步是建立「共同目標與分工」。直白講，就是先讓 AI 幫你寫一份夠安全開始的起步基準：目標是甚麼、誰在參與、第一步做甚麼、甚麼不可做、怎樣算完成。未定的地方可以先標明，之後一路做一路修。

正常情況下，AI 安裝成功後會直接帶你進入下一步，不需要你另外學命令。若 AI 沒有自動接上，你才貼下面這句作為手動觸發：

請先幫我建立這個 APS 項目的共同目標與分工，先做到夠安全開始，再按狀態決定是否保存、邀請協作者、讓對方確認，或整理第一輪交接草稿。

📌 不用一次填完整計劃。共同目標與分工不是大表格。起步時先有共同目標、自己的用戶名稱、第一個可做小步、明顯不可做事項和最小驗收方式；其他角色、第一輪分工、邀請對象或詳細驗收，可以先寫「未定」。

你實際要做的是推進自己的項目，不是學 APS。要交給協作者時，最穩定的說法是直接提 APS：請用 APS 把這段工作交接給 Jay，先整理草稿，等我確認後才寫入共用 Drive。 這樣說，是為了讓 AI 走 APS 交接流程，而不是一般聊天式工作安排。AI 會整理交接草稿並等你確認後寫入 APS。日常備用入口是：要看整體狀態，說 Check APS；要看對方有沒有新交接，說 check Drive。APS 只整理已同步資料和下一步風險，不會自動通知對方，也不會自動打開對方的 AI。

🛠️ 人工備用命令

一般新手不用自己打。只有在 AI 代理要求你手動執行，或你想排錯時才看這段。

npx --yes @adamchanadam/agent-handoff-kit@latest init --dry-run --root "<目前項目資料夾>"
npx --yes @adamchanadam/agent-handoff-kit@latest init --yes --root "<目前項目資料夾>"
npm install --save-dev @adamchanadam/aps@latest
npx aps init --dry-run
npx aps init --hub-root "<AI 建議並經你確認的 APS 交換區路徑>" --project <APS_合作目錄名稱> --agent-id <自己的_用戶名稱> [--invite-code <邀請碼>]
npx aps doctor

不要用 npx aps init --help 查用法；查用法請用 npx aps --help。非互動終端先用 --dry-run 預覽，正式設定時帶齊 --hub-root、--project、--agent-id；受邀加入時再帶 --invite-code。