https://github.com/adamchanadam/agent-public-squares
AI agent handoff over Google Drive for Codex, Claude Code, and cross-machine collaboration.
https://github.com/adamchanadam/agent-public-squares
agent-handoff agent-public-squares ai-agent ai-agents ai-collaboration claude-code cli codex collaboration cross-machine developer-tools github-pages google-drive handoff local-ai npm-package project-handoff workflow-automation
Last synced: 4 days ago
JSON representation
AI agent handoff over Google Drive for Codex, Claude Code, and cross-machine collaboration.
- Host: GitHub
- URL: https://github.com/adamchanadam/agent-public-squares
- Owner: Adamchanadam
- License: apache-2.0
- Created: 2026-05-22T17:08:11.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T09:50:26.000Z (11 days ago)
- Last Synced: 2026-06-27T10:14:08.408Z (11 days ago)
- Topics: agent-handoff, agent-public-squares, ai-agent, ai-agents, ai-collaboration, claude-code, cli, codex, collaboration, cross-machine, developer-tools, github-pages, google-drive, handoff, local-ai, npm-package, project-handoff, workflow-automation
- Language: JavaScript
- Homepage: https://adamchanadam.github.io/agent-public-squares/docs/index.html
- Size: 6.87 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Agent Public Squares
Agent Public Squares（APS）讓同一個項目的多位用戶，透過共用 Google Drive，把任務交接給彼此的本機 AI 代理。
它適合需要多人合作、AI 代理分工、項目交接和可追蹤交接包的小團隊或個人項目。每個交接包只發給一位協作對象；APS 不是群聊、不是自動派工，也不會自動通知對方。
最適合新手的安裝方法，不是先學命令，而是請 Codex、Claude Code 或同等本機 AI 代理帶你安裝。
## 目前可信狀態
APS 仍是前期測試版，但不是概念稿。這個 repo 目前已提供可安裝的 npm 套件、GitHub release、Apache 2.0 授權、AI 代理安裝與升級指引、加入邀請頁、日常使用入口和本地品質檢查命令。
| 項目 | 目前狀態 |
|---|---|
| 本頁對應版本 | `@adamchanadam/aps@0.2.38` |
| 對應 GitHub release 標籤 | `v0.2.38` |
| 授權 | Apache License 2.0 |
| 支援環境 | Node.js 18 或以上 |
| 建議用途 | 受控實際試行、雙方 AI 交接測試、日常協作流程打磨 |
| 不建議用途 | 不可中斷、不可出錯、沒有人工覆核的重要生產流程 |
這個定位刻意保守：它讓新用戶知道 APS 可以試、可以回報、可以逐步成長，但不會把早期工具包裝成已成熟平台。
## 快速開始
- 第一次使用：[先看人類新手頁](https://adamchanadam.github.io/agent-public-squares/docs/guides/aps-onboarding-walkthrough.html)
- 交給本機 AI 安裝或升級：[AI 代理安裝與升級指引](https://adamchanadam.github.io/agent-public-squares/docs/guides/aps-ai-agent-install.html)
- 收到邀請：[加入 APS 協作邀請](https://adamchanadam.github.io/agent-public-squares/docs/guides/aps-join-invite.html)
- 查看整體狀態：在已安裝 APS 的項目中對 AI 說 `Check APS`
- 查看新交接：在已安裝 APS 的項目中對 AI 說 `check Drive`
## 為甚麼值得試
- 用 Google Drive 做交換層，不要求協作者共用同一部電腦或同一個 AI 對話。
- 每份交接包都有收件人、版本、主題、狀態和可追蹤記錄，不靠口頭摘要猜測。
- 安裝主路徑交給本機 AI 代理執行；人類可只指出 Google Drive 本機根目錄和合作目的，AI 會建議 APS 交換區、APS 合作目錄名稱和自己的用戶名稱。
- 一個合作項目只應有一個 APS 合作目錄；合作目錄按項目或任務命名，不按發起人、電腦或 AI 名稱命名。
- 邀請新協作者使用一次加入邀請碼；邀請碼代表可加入某個 APS 合作目錄，不代表受邀者的用戶名稱。受邀者把邀請中的剪刀區塊貼給自己的 AI，再在自己電腦上選定名稱。
- 文件明確說明哪些事 APS 不會做，例如不會自動通知對方、不會自動派工、不會替人類省略確認。
- repo 保留本地品質檢查命令，方便後續版本持續驗證核心流程。
## 成長路線
APS 的成長重點不是先做大型平台，而是先把跨機 AI 協作中最容易出錯的交接、確認、收件和狀態檢查做好。
| 階段 | 重點 |
|---|---|
| 現在 | 穩定安裝、邀請、發送、收件、狀態檢查和新手文件 |
| 下一步 | 擴大真實雙方試用、改善錯誤提示、增加更多回歸檢查 |
| 之後 | 根據 issue 和實測結果，逐步加強多協作者流程、文件索引和支援材料 |
歡迎先用小型真項目試行。遇到不清楚、安裝不順或交接語意不準的地方，請用 [GitHub Issues](https://github.com/Adamchanadam/agent-public-squares/issues) 回報；早期回饋會直接影響下一批功能和文件優先序。
## 常見問題
### Agent Public Squares 是甚麼？
Agent Public Squares 是一個幫本機 AI 代理交接項目任務的工具。它把共同目標、目前狀態、下一步、真源指標、接收方開工條件、風險和限制寫成交接包，讓協作對象可以在自己的電腦上叫 AI 讀取並判斷能否接手。
### APS 解決甚麼問題？
APS 解決的是「同一個項目裡，不同用戶的 AI 代理怎樣清楚分工、交接和查狀態」的問題。它用共用 Google Drive 資料夾保存交接包，避免接手方靠聊天記憶或口頭摘要猜測。
### APS 適合誰？
APS 適合使用 Codex、Claude Code 或同等本機代理型 AI 的用戶，尤其是需要多人合作、AI 代理分工、項目交接和風險檢查的項目。
### APS 目前是否生產級？
不是。本頁對應的 `@adamchanadam/aps@0.2.38` 是可用於受控實際試行的前期測試版，不應承諾為不可中斷、不可出錯的生產級工具。
## 文件與支援入口
- [公眾入口頁](https://adamchanadam.github.io/agent-public-squares/docs/index.html)：給第一次認識 APS 的讀者
- [完整教學中心](https://adamchanadam.github.io/agent-public-squares/docs/guides/index.html)：集中查看所有安裝、加入和日常使用頁面
- [npm 套件頁](https://www.npmjs.com/package/@adamchanadam/aps)：查看目前公開套件版本
- [GitHub Issues](https://github.com/Adamchanadam/agent-public-squares/issues)：回報問題或提出改進建議
## 第一次安裝或既有項目升級
在你想使用 APS 的本機工作目錄打開 Codex、Claude Code 或同等本機代理型 AI，貼上以下整段。這同一段也適用於已有 APS 的項目升級；詳細規則由頁面交給 AI 讀取和執行：
```text
請在目前本機工作目錄，按以下頁面完成 Agent Public Squares（APS）安裝、加入或升級：
https://adamchanadam.github.io/agent-public-squares/docs/guides/aps-ai-agent-install.html
```
AI 會按頁面規則先只讀檢查，再判斷新安裝、受邀加入或既有項目升級。你仍然要確認三件資料；若你只知道 Google Drive 本機根目錄，AI 應建議預設 APS 交換區，例如 `Agent_Public_Squares`，並在你確認後建立：
- Google Drive 同步到本機的位置，或 AI 建議的 APS 交換區路徑
- 這個合作項目的 APS 合作目錄名稱
- 你自己的用戶名稱
AI 會問你這三件事。APS 合作目錄應用合作項目或任務命名，例如 `community_open_day_parent_notice`、`client_site_rebuild_launch`，不要用任何人名、電腦名、AI 名稱或發起人名稱。不要把任何人電腦上的本機路徑照抄到自己電腦；每部電腦都要使用自己看到的 Google Drive 本機路徑。邀請碼不替你命名，你的用戶名稱由你自己確認。若雙方都各自發了邀請，先選定其中一個 APS 合作目錄作唯一合作空間；另一個邀請碼不要用，避免兩邊分裂成兩套互不相見的交接。
AI 建立或確認 APS 交換區後，請把該資料夾設為「可離線使用」。在 Windows 下，到 Google Drive 的目標資料夾，按右鍵，選「顯示其他選項」→「離線存取」→「可離線使用」。參考圖在 [第一次安裝教學](https://adamchanadam.github.io/agent-public-squares/docs/guides/aps-onboarding-walkthrough.html)。
普通網頁聊天 AI 如果不能讀寫你的本機工作目錄，就不適合直接安裝。它最多只能解釋步驟。
## 安裝後先做甚麼
第一位用戶安裝完成後，不應立即邀請對方或發測試包。先叫 AI 建立這個項目「夠安全開始」的共同目標與分工：
```text
請先幫我建立這個 APS 項目夠安全開始的共同目標與分工，再決定是否邀請或發給協作者確認。
```
共同目標與分工不是要你一開始寫完整項目計劃。起步時先定好五件事：共同目標、自己的用戶名稱、第一個可做小步、明顯不可做事項、最小驗收方式。每人長期角色、完整第一輪分工、第一個邀請對象、第一輪交接對象和詳細驗收標準，可以先標為「未定」或「待確認」。八項仍然是 AI 的檢查框架，不是新手一開始必填表；如有截止日期、優先級、品牌語氣、審批點、合規限制、輸出格式、語言、預算或時間限制，可以叫 AI 加入。
這不是每位用戶各自一份的私人草稿。一個 APS 合作目錄只應有一份目前有效的共同目標與分工；可以修訂出新版本，但不應平行存在兩套互相打架的口徑。未定的地方要如實標出，不要為了填滿欄位而假裝已定。確認後，AI 應主動問是否要本機保存、發給已確認的協作者確認，或先邀請對方再發確認包。要讓對方透過 APS 收到，應一對一發出交接包，而不是只把檔放進 `_hub` 根目錄。這一步可以避免每一邊的 AI 各自理解項目目標和分工，令後面的交接口徑不一致。
你不用知道 APS 裏面下一條命令是甚麼，也不需要主動輸入 `npx` 指令。AI 應該按目前狀態推進：沒有共同基準就先建立；已有基準但未落地就先保存或發確認包；已有基準但未有協作者，就主動替你生成含一次加入邀請碼的可轉發邀請。對方要在自己的電腦、自己的本機工作目錄、自己的 Google Drive 本機路徑完成加入；對方用戶名稱由對方自己確認。
項目持續進行時，共同目標與分工可以改，但要當成修訂目前有效版本，不要另開第二份。只有共同目標、長期角色、驗收標準、不可做事項或會影響多個交接包的分工邊界改變時，才修訂它；普通 bugfix、單次交付、補資料、審閱或某一輪任務細節，應用普通 APS 交接包或 `revise`。若有三位或以上協作者，同一份基準要逐一發給受影響協作者確認；後加入的協作者應先收到最新基準，不應自行重建一份。
## APS 做甚麼
你要把一部分項目任務交給指定協作者時，APS 會把一句「你接手吧」變成一份可追蹤的交接包。
交接包會說清楚：
- 共同目標是甚麼
- 目前做到哪裡
- 請對方做甚麼
- 哪些地方不要誤解
- 真源指標在哪裡，例如共享文件、連結、檔名、版本、頁碼、段落或 APS packet 位置
- 對方在自己電腦上甚麼條件下才可以開工
- 還有甚麼風險或未決事項
對方那邊不用靠記憶猜。他應先在自己的項目資料夾叫 AI `Check APS`，核對自己是否已收到並確認最新版共同目標與分工，再決定是否讀普通交接。當某件交接被判斷為可開工，才叫 AI `check Drive` 讀交接包正文、真源指標與請他做的事。`Check APS` 的主線在 AI terminal：先回答交接包是否如期、自己有甚麼要跟進、下一句要叫 AI 做甚麼。排錯用的數量、同步、路徑、來源編號和完整追溯資料不會預設丟給用戶；需要深入排錯時才用 `check-aps --full`。APS Live 已納入 APS 產品標準，定位是交接期間的交接追蹤工作台與即時對齊頁；用戶需要看階段、跟協作者對齊、收 feedback / comment、補資料、推進或退回前，可由 `Check APS` 生成 / 更新 APS Live 交接追蹤頁並保持開啟至本輪交接完成。沒有必須由 Live 修復的卡點，只代表 Live 不是強制修復路徑，不代表不能用作工作台。正式狀態仍要回到 terminal，經用戶批准後才寫回 APS 紀錄。這不是通知送達證明，也不是已完成真兩機可靠性證明。
## 功能一覽
簡單說，APS 是一個用共用 Google Drive 連接多位協作者本機 AI 的交接信箱。它支援一對一交接、版本記錄和處理收據；通知、確認和決策仍然由人掌握。
### 設定與安裝
| 想做的事 | 對 AI 說法 / 備用命令 | APS 會做甚麼 |
|---|---|---|
| 初始化本機項目 | `init` | 安裝 APS，建立本機設定和共用 Drive 交接結構 |
| 升級 APS | `upgrade` | npm 更新後刷新本機橋接和 skill，不覆寫既有交接包和設定 |
| 查看或修改本機設定 | `config` | 顯示或更新 APS 交換區路徑、APS 合作目錄名稱和自己的用戶名稱 |
| 檢查是否正常 | `doctor` | 只讀檢查通道、收據、衝突檔和基本結構 |
### 協作對象
| 想做的事 | 對 AI 說法 / 備用命令 | APS 會做甚麼 |
|---|---|---|
| 邀請新協作者 | 對 AI 說「邀請協作者」；備用命令 `peer invite` | 當共同基準已確認但未有協作者時，AI 會主動建議這一步；它產生一次加入邀請碼和可交給對方 AI 的加入邀請，受邀者加入時自行確認用戶名稱。用戶名稱由對方自己確認，發起人不需要預先知道 |
| 維護已約定用戶名稱的協作者 | 維護 / 兼容命令 `peer add` | 只在雙方已明確約定對方用戶名稱、而且需要補登 provisional peer 或 starter pack 時使用；一般邀請新協作者不要用這條路 |
| 重發維護用加入教學 | 維護 / 兼容命令 `peer starter` | 只為已約定用戶名稱的協作者重新產生 starter pack；一般新協作者仍用「邀請協作者」一次加入邀請 |
| 查看協作者 | `peers` | 列出已確認和暫定的協作對象 |
同一個項目可以有多位協作者，但每個交接包仍然是一對一發送，必須指定收件人。
### 發送交接
| 想做的事 | 對 AI 說法 / 備用命令 | APS 會做甚麼 |
|---|---|---|
| 發送交接包 | `publish --to` | 把任務、上下文、證據和風險整理成交接包，發給指定對象 |
| 發正式交接 | `publish --to ... --strict-handoff --items ...` | 要求共同目標、雙方任務、真源指標、接收方開工條件、風險和請對方處理的事項齊全 |
| 修訂已發出的交接 | `revise` | 在同一條交接線上發出新版本，保留歷史 |
| 撤回交接 | `withdraw` | 在對方處理前撤回最新版本 |
| 收結交接線 | `close` | 對方回覆或完成後，標記該交接線已完成 |
| 查發送狀態 | `status --packet-id` | 查看某個交接包是否已處理、已撤回或已收結 |
### 接收交接
| 想做的事 | 對 AI 說法 / 備用命令 | APS 會做甚麼 |
|---|---|---|
| 查看新交接 | `check-drive` / `inbox` | 查看對方是否有未處理交接 |
| 標記已處理 | `consume` | 在自己的收據中標記某個版本已處理，並寫下具體處理說明 |
| 退回交接 | `decline` | 在資料不足或無法處理時，正式退回某個版本給發送方 |
### 狀態與概覽
| 想做的事 | 對 AI 說法 / 備用命令 | APS 會做甚麼 |
|---|---|---|
| 查看整體狀態 | `check-aps` | 在 AI terminal 先判斷交接包是否如期、自己有甚麼要跟進、下一句要叫 AI 做甚麼；排錯資料、來源編號和完整追溯資料只在需要時用 `check-aps --full` 展開 |
| 打開交接工作台 | `Check APS` 或「打開 APS Live」 | 交接期間用來看階段、跟協作者即時對齊、收回饋、補資料或整理下一步；沒有必須修復的卡點不代表不能打開 |
| 建立背景索引 | `context` / `context add` / `context html` | 把已讀交接整理成項目背景索引；只作背景，不取代交接包 |
### APS 不會做的事
| APS 不會做 | 原因 |
|---|---|
| 不會自動通知對方 | 通知仍由人手發出 |
| 不會自動觸發對方 AI | 對方要在自己的電腦上先主動 `Check APS`，確認共同基準後才按需要 `check Drive` |
| 不會替你分享或修改 Google Drive 權限 | Drive 權限由人管理 |
| 不會未經確認就發包、處理、退回、撤回或收結 | 所有關鍵動作都要人確認 |
| 不會多收件人群發 | 每個交接包仍然是一對一 |
## 目前狀態
本頁對應版本是：
```text
@adamchanadam/aps@0.2.38
```
它已經可以安裝，並可用於受控實際試行。它仍是前期測試版，不應承諾為生產級工具。
適合：真項目中的受控試行、雙方 AI 交接測試、日常協作流程打磨。
不適合：不可中斷、不可出錯、沒有人工覆核的重要生產流程。
## 它不是甚麼
Agent Public Squares 不是自動通知系統。
它不會在對方電腦彈出提示，也不會自動打開對方的 AI。發出交接後，你仍然要把 AI 生成的摘要通知貼到 WhatsApp、Email、Telegram 或你們平常使用的通訊工具。對方第一次或不確定狀態時，應先在自己的電腦上 `Check APS`；確認共同基準與交接狀態後，再按需要 `check Drive` 讀具體交接。
它也不是群組任務平台。
同一個項目可以有多位協作對象，但每一份交接包仍然只發給一位對象。
## 命令備用路徑
如果你熟悉終端機，也可以手動執行。新項目順序是：
```powershell
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 "" --project --agent-id <自己的_用戶名稱> [--invite-code <邀請碼>]
npx aps doctor
```
不要用 `npx aps init --help` 查用法，因為 `init` 可能進入互動邏輯。查用法請用 `npx aps --help`；非互動終端要用 `--dry-run` 預覽，正式設定時傳入 `--hub-root`、`--project`、`--agent-id`；受邀加入時再傳入 `--invite-code`。
既有項目升級：
```powershell
npm install --save-dev @adamchanadam/aps@latest
npx aps upgrade
npx aps doctor
```
命令只是備用路徑。新手主路徑仍然是請本機 AI 代理讀取 AI 代理安裝與升級指引，再由它帶你一步一步完成。
## 日常怎樣用
你不需要記住很多命令。最理想的用法，是直接向 AI 說你想做甚麼。
APS 的日常精神是「按狀態推進」，不是叫你背命令。AI 應該先判斷現在卡在共同基準、協作者加入、確認包、正式交接、收件、退回、修訂還是收結，然後給你一個可以立即做的下一步。
交給對方接手：
```text
幫我用 APS 交給指定協作者接手。
```
查看對方有沒有新交接：
```text
check Drive
```
查看 APS 整體狀態：
```text
Check APS
```
這會讓 AI 顯示收件、發件、協作對象、下一步與風險摘要；它只整理本機已同步資料，不是自動派工，也不是背景自動監察。
查對方是否已處理：
```text
看看對方處理了沒有。
```
AI 應該先整理交接定義、缺漏與風險，讓你確認後才寫入共用 Drive 資料夾。它不應該未經確認就發正式交接包。
## 授權
Apache License 2.0