English | 中文版
這是
anthropics/commerce-agents的 Windows-first 維護型 fork，沿用 Apache License 2.0 與完整 Git 歷史。產品行為跟隨上游；本維護線補上繁中文件、Windows 開發／驗收 gate，以及逐筆審查的上游追蹤。差異見FORK.md，維護決策見docs/DECISIONS.md。
Claude 上的兩個商務 agent 參考實作：一個購物 agent（給商家嵌進自己的 App，服務顧客）， 一個商家 agent（給商家後台員工用）。每個 agent 的 prompt、skills、工具合約與安全閘門都只 定義一次，同時跑在 Messages API、Claude Agent SDK 與 Managed Agents 三條路徑上；四個可執行的 垂直領域範例（零售、旅遊、電信、娛樂）展示同一套函式庫在不同業態下的樣子。
Note
所有公司、品牌、產品與人物均為虛構，唯一的公司是 ACME。這個 repo 不會真的下單、不會真的
刷卡、不會真的改動上線中的商品：checkout 只把購物車渲染出來交給宿主完成，商家端的每一筆
寫入都要等人核准後才生效。商業規則、授權與合規是實際部署時要自己補上的。
需要 Python 3.11+ 與 Node 22。
git clone https://github.com/SanHsien/commerce-agents.git && cd commerce-agents
python -m venv .venv && .venv\Scripts\activate # Windows PowerShell；macOS/Linux 用 source .venv/bin/activate
pip install -r requirements.txt # 七個套件與其釘選版本的依賴
copy .env.example .env # 填入 ANTHROPIC_API_KEY
cd examples && npm ci && cd .. # 八個 Web App 共用一個 npm workspace
python scripts/run_demo.py retail # API :8000 + 購物前台 :3000--merchant 改成只啟動商家後台，--all 兩者都啟動。四個垂直範例：retail（前台 :3000／
後台 :3100）、travel（:3001／:3101）、telecom（:3002／:3102）、entertainment（:3003／
:3103）；各自的 README 附上可以在前台與後台試的對話開場。
commerce-builder plugin 會照這個 repo 的函式庫，針對你自己的系統生成一個 agent（或審查一個
既有的）：
claude plugin marketplace add SanHsien/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent 幫我的商店建一個購物助理其餘指令 /add-commerce-flow、/author-commerce-evals、/review-commerce-agent 見
plugins/commerce-builder/。
購物 agent 負責搜尋、比較、規劃、填購物車、回答訂單與政策問題，並記住顧客告訴它的事。
五個流程是 shopping-agent/skills/ 底下的 skills；部署方要在
StorefrontBackend 上接上自己的商品、
購物車、訂單與政策系統。
商家 agent 負責解釋績效、維護商品頁、處理庫存與訂單警示、調價與促銷、草擬行銷活動；每一
筆寫入都是一筆待核准的變更，由宿主的核准介面套用。五個流程是
merchant-agent/skills/ 底下的 skills；部署方要在
MerchantBackend 上接上自己的分析、商品、
庫存、定價與行銷系統。
| 目錄 | 內容 |
|---|---|
commerce-common/ |
兩個角色共用的東西：設定、fencing、記憶、skills、grounding、呈現層、executor 框架、事件 |
shopping-agent/core/ |
購物型別、StorefrontBackend、prompt、工具合約、閘門、executor |
shopping-agent/runtime-messages-api/ |
ShoppingAgent，跑在 Messages API 上的對話迴圈 |
shopping-agent/runtime-agent-sdk/ |
跑在 Claude Agent SDK 上的購物 agent，附一個 console |
shopping-agent/managed-agents/ |
Managed Agents 用的 manifest 與購物前台 MCP server |
merchant-agent/core/ |
商家型別、MerchantBackend、prompt、工具合約、變更護欄、閘門、executor |
merchant-agent/runtime-messages-api/ |
MerchantAgent 與跑在 Messages API 上的分析代理 |
merchant-agent/runtime-agent-sdk/ |
跑在 Claude Agent SDK 上的商家 agent，附一個會核准變更的 console |
merchant-agent/managed-agents/ |
Managed Agents 用的 manifest、商家 MCP server、排程摘要 |
examples/ |
四個垂直範例，共用 host 程式碼（demo_common/）與共用 Web 程式碼（web-shared/） |
plugins/commerce-builder/ |
Claude Code plugin |
docs/ |
safety.md（安全規則清單）、backends.md（怎麼接自己的系統）、deployment.md（其他平台） |
tests/ |
跨套件的測試；每個套件也有自己的 tests/ |
scripts/ |
install.sh、run_demo.py、smoke_chat.py、screenshot_tour.py、check.py、deploy_managed_agent.sh、verify_all.py |
完整介面細節（三種跑法、安全機制、四個垂直範例、部署到其他平台）見英文原版
README.en.md；那份文件是上游持有的鏡像，本 fork 不覆寫它，維護範圍見
FORK.md。
.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.venv\Scripts\pwsh.exe -NoProfile -File tools\dev_check.ps1 # 或用系統 pwshtools/dev_check.ps1 依序跑 ruff check → ruff format --check → pytest →
scripts/check.py → tools/check_links.py → tools/check_divergence.py →
tools/check_pin_bounds.py，是本 fork 在 Windows 上的一鍵 gate。要逐項手跑：
.venv\Scripts\python.exe -m ruff check .
.venv\Scripts\python.exe -m ruff format --check .
.venv\Scripts\python.exe -m pytest -q
.venv\Scripts\python.exe scripts\check.pyrequirements-dev.txt 裝 pytest、pytest-asyncio、ruff（本 fork 直接跟上游最新版走，不因為
「這是上游持有的宣告檔」保留落後版本），以及一行只在 Windows 安裝的 tzdata（帶
sys_platform == "win32" 環境標記）——Windows 版 CPython 沒有系統 IANA 時區資料庫，少了它
會有 4 個上游時鐘測試在本機紅、在上游 Ubuntu CI 綠。本 fork 的維護工具只用標準函式庫，沒有
新增任何 runtime 依賴。
上游有一筆測試斷言檔案權限是 POSIX 的 0o600，Windows 沒有這個語意；本 fork 把這一行斷言
改成平台條件式（Windows 上跳過，其餘照常驗證），不再靠 --deselect 整支跳過。這與
requirements-dev.txt、.github/workflows/ci.yml 的差異一併登記在
docs/DIVERGENCE.md，由 tools/check_divergence.py 機器檢查登記表
與實際改動一致；決策脈絡見 docs/DECISIONS.md。
依賴更新走 Dependabot，三個生態系（pip／npm／github-actions）全開，用 groups 併成
一個 PR、ignore 掉七個從本地路徑安裝的 in-repo 套件。tools/check_pin_bounds.py 會在每個
PR 上比對 requirements 的 exact pin 與各 pyproject.toml 宣告的範圍——scripts/check.py
不讀 requirements，這是唯一擋得住「pin 升出宣告範圍」的檢查。PR 一律人工讀 diff 後合併。
原始著作權 2026 Anthropic PBC，以 Apache License 2.0 授權；這是一份參考實作，
不由 Anthropic 維護、也不接受回貢。本 fork 的授權與來源說明見 NOTICE.md。