前言¶

在 Python 裏接 AgentScope，常見卡點不是「能不能 import」，而是版本混用：文檔指向 2.x，倉庫裏仍是 ReActAgent、register_tool_function 等 1.x 寫法；模型、工具、會話狀態各有一套入口，改一處容易牽一片。自己翻官方文檔可以解決問題，但 Agent 往往缺少按任務拆分的核對清單和可複製的最小工程。

下面介紹 SkillHub 社區 Skill agentscope-builder（座標 @user_ea778c49/agentscope-builder）。它把 AgentScope 官方文檔與目標版本源碼對齊，引導 Agent 做搭建、調試、擴展或遷移，默認面向 AgentScope 2.x，並附帶參考文檔、最小單智能體模板和本地校驗腳本。

這是什麼¶

agentscope-builder 是一份基於通用 SKILL.md 格式的 Agent 技能包，簡介爲「AgentScope 框架搭建指南」。發佈者爲社區用戶 user_ea778c49，來源爲 community，SkillHub 分類爲 ai-agent，當前商店版本爲 1.0.2（技能包內 SKILL 正文標註的技能版本爲 2.0.0，示例覈驗基線爲 AgentScope 2.0.10、Python 3.11+，資料覈查日期 2026-10-16）。

官方入口：

• API 座標頁：https://api.skillhub.cn/user_ea778c49/agentscope-builder
• SkillHub 展示頁：https://www.skillhub.cn/skills/user_ea778c49/agentscope-builder

頁面標籤包含 requires_api_key=true：按包內最小模板跑通時，需要配置模型廠商密鑰（示例使用 DashScope 的 DASHSCOPE_API_KEY）。

核心功能¶

以下內容均來自已安裝技能包內的 SKILL.md 與配套文件，能力按任務類型組織。

版本邊界與遷移¶

1. 從項目依賴、鎖文件和入口判斷實際使用的 AgentScope 版本（含 importlib.metadata 查詢命令）。
2. 新項目默認按 2.x 覈對公開 API；1.x 項目先走維護與遷移參考，僅在用戶明確要求時再升主版本。
3. 資料衝突時以目標版本公開 API、源碼與文檔爲準；不把 QwenPaw 等應用層約定寫成框架硬性要求。

2.x 開發約定¶

技能內整理了 2.x 的推薦用法，並明確列出應避免的 1.x 模板寫法，例如：

• 使用 agentscope.agent.Agent、await agent.reply(message) / reply_stream。
• 工具通過 Toolkit(tools=[FunctionTool(fn)])；技能目錄與 MCP 通過 Toolkit 的 skills_or_loaders、mcps 接入。
• 會話與上下文：AgentState、ContextConfig；擴展側 ReActConfig、ModelConfig、InjectionConfig 與 middleware。
• 不要在 2.x 模板中使用 ReActAgent、memory=InMemoryMemory()、register_tool_function 等舊 API。

分主題參考文檔¶

技能包 references/ 下按任務索引，Agent 按需讀取：

最小可運行模板¶

assets/minimal-agent/ 提供完整單智能體示例（main.py、requirements.txt）：DashScope 模型、一個執行計算的 Python 工具、官方 console；遵循默認權限策略，純計算工具聲明爲只讀。

本地校驗腳本¶

包內 scripts/ 提供三類腳本（不替代真實聯調，但便於 Agent 自檢）：

• inspect_environment.py：報告已安裝版本與公開簽名，不聯網、不讀憑據。
• validate_skill.py：檢查 front matter、引用路徑與 Python 示例語法。
• smoke_test.py：在已安裝 AgentScope 2.0.10 的環境中用假模型驗證消息、工具確認、技能加載與狀態恢復。

安裝與啓用¶

安裝 SkillHub CLI¶

若本機尚未安裝 skillhub，可按 SkillHub 安裝說明執行（完整安裝含 CLI 與默認 Skill）：

command -v skillhub && skillhub --version

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

僅安裝 CLI 時：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安裝 agentscope-builder¶

安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能不會被識別。

skillhub install agentscope-builder --namespace user_ea778c49 --dir <skills 目錄>

SkillHub 頁面也支持讓 AI 按說明安裝：

請根據 https://skillhub.cn/install/skillhub.md，安裝 `@user_ea778c49/agentscope-builder`。

常見客戶端 skills 路徑（摘自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

安裝後通常需要重啓或刷新 Agent，使新技能被加載。包內 agents/openai.yaml 提供默認提示示例：使用 $agentscope-builder 按當前項目版本搭建可運行智能體並覈驗工具與狀態。

典型用法¶

1. 讓 Agent 啓用技能後的工作流¶

啓用技能後，Agent 應先確定項目 AgentScope 版本，再按上表讀取對應 reference。對新項目，技能建議順序爲：單 Agent + 一種模型 → 註冊工具 → 按需加載技能目錄與 MCP → 會話/長期記憶 → 多智能體或服務部署。

版本檢查示例（在項目 Python 環境中）：

python -c "from importlib.metadata import version; print(version('agentscope'))"

2. 從最小模板啓動¶

複製 assets/minimal-agent/ 到新項目目錄後：

python -m venv .venv
# 激活虛擬環境後：
python -m pip install -r requirements.txt
python main.py

通過當前 shell 設置 DASHSCOPE_API_KEY；可選 DASHSCOPE_MODEL。技能明確要求不要將真實憑據寫入源碼或版本庫。

3. 環境自檢¶

將路徑替換爲本機技能安裝目錄下的 scripts：

python /path/to/agentscope-builder/scripts/inspect_environment.py
python /path/to/agentscope-builder/scripts/inspect_environment.py --module agentscope.agent.Agent

修改技能或模板後：

python /path/to/agentscope-builder/scripts/validate_skill.py
python /path/to/agentscope-builder/scripts/smoke_test.py

適用場景與注意¶

適合誰

• 用 Python 基於 AgentScope 2.x 新建智能體，希望 Agent 按官方 API 寫入口、工具和狀態，而不是混用 1.x 片段。
• 維護 1.x 代碼庫，需要按技能內遷移文檔評估升級範圍。
• 需要模型接入、MCP、多智能體流水線或服務部署時，希望 Agent 按索引讀配套 reference，而不是一次性塞滿上下文。

限制與注意

• 標籤 requires_api_key=true：跑通官方示例模型需自備 API Key；技能強調憑據只通過環境變量注入。
• 技能正文中的 AgentScope 2.0.10 與 Python 3.11+ 是編寫時的核驗快照，上線前應在目標環境重新確認版本與文檔（stable 與 latest 可能不一致）。
• smoke_test.py 依賴已安裝的 AgentScope 2.0.10，不能代替真實廠商 API 或生產部署驗證。
• SkillHub 頁面統計（截至資料抓取）：評分 100000，下載 1126，安裝 2；社區來源，使用前應自行評估維護節奏與合規要求。

結尾¶

agentscope-builder 把 AgentScope 2.x 的約定、分主題參考、最小模板和校驗腳本收進一個 Skill，適合交給 coding Agent 做「按版本搭架子、少踩 1.x/2.x 混寫」類任務。安裝與座標以 SkillHub 爲準：

• https://www.skillhub.cn/skills/user_ea778c49/agentscope-builder
• https://api.skillhub.cn/user_ea778c49/agentscope-builder