Agent Wiki 把一個 Agent 的來源檔案非同步整理為相互連結的結構化 Markdown 頁面,形成可檢索的知識圖譜。頁面可以按路徑列出、讀取和搜尋,適合儲存需要跨會話共用的產品說明、操作手冊、專案約定和其他 Agent 級資料。
Wiki 對外提供頁面、連結、來源引用和搜尋能力,不提供實體三元組或圖查詢介面。需要圖資料庫式實體/關係查詢時,應使用其他資料模型。
前提條件
已建立記憶庫(任意輸入類型均可,Wiki 歸屬記憶庫 + 三段 Agent Scope)。
資源邊界
每個 Wiki 唯一歸屬於一個記憶庫和三段 Agent Scope:
memoryStoreName + appId / tenantId / agentIdWiki 不使用
runId,同一 Agent 的不同會話共用一個 Wiki。調用
GetWiki時服務自動擷取或建立該 Scope 對應的 Wiki,不需要wikiId、構建 ID 或任務 ID。三個欄位均必填、最長 128 位元組,不能包含
/,不允許使用萬用字元*。
支援的來源檔案
類型 | 副檔名 | 寫入方式 | 單檔案上限 |
Markdown、文本 |
|
| 100 KiB |
|
| 2,000,000 位元組 | |
Word |
|
| 2,000,000 位元組 |
Excel |
|
| 2,000,000 位元組 |
PowerPoint |
|
| 2,000,000 位元組 |
圖片 |
|
| 2,000,000 位元組 |
二進位檔案使用標準 Base64;副檔名、mediaType 和檔案簽名必須一致。
查詢 Wiki
擷取或建立當前 Agent Scope 的 Wiki,並查看最新構建狀態。首次調用會自動建立 Wiki。
控制台
開啟記憶庫,進入知識編譯 Wiki > 原始檔案(或知識圖譜),設定應用、租戶和智能體後查看 Wiki 狀態與頁面數。
SDK
當前 Agent Storage SDK 尚未封裝 Wiki 高層方法,使用底層 ots_client.request(Action, body) 調用。
Python
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
wiki = client.ots_client.request("GetWiki", {
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
})
print(f"狀態: {wiki.get('status')}, 頁面數: {wiki.get('pageCount')}, 待構建: {wiki.get('hasPendingChanges')}")API
調用 GetWiki 查詢 Wiki。完整欄位參見查詢 Wiki。
構建 Wiki
把 /.wiki/raw/ 下的來源檔案非同步編譯為一組新頁面並原子發布。
控制台
在知識編譯 Wiki > 原始檔案頁,點擊新增原始資料或批量上傳,把來源檔案寫入
/.wiki/raw/。點擊構建 Wiki,服務非同步編譯頁面。
在知識圖譜頁查看發行頁面;構建期間舊頁面保持可讀。
SDK
Python
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
# 1. 寫入來源檔案(AddItem 見「檔案記憶」文檔)
client.add_item({
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
"path": "/.wiki/raw/product/payment.md",
"content": "# 支付說明\n\n支付回調必須校正等冪鍵。",
})
# 2. 發起構建
resp = client.ots_client.request("IngestWiki", {
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
"clientToken": "wiki-build-001",
})
print(resp)API
調用 IngestWiki 構建 Wiki。完整欄位參見構建 Wiki。
IngestWiki 是非同步作業。相同 clientToken 可用於安全重試;響應中的 reused 表示複用了同一構建,skipped 表示來源沒有變化、無需重新構建。
常見構建狀態如下:
狀態 | 說明 |
| 構建已接收或正在處理 |
| 頁面正在產生、校正、建立索引或發布 |
| 新頁面已原子發布,可以讀取和搜尋 |
| 構建失敗,檢查 |
| 構建期間來源或目前的版本發生變化,應重新擷取狀態並發起新構建 |
列出頁面
按路徑順序分頁列出發行頁面中繼資料。
須先構建並發布後才有頁面可列;未構建時返回資源不存在。
limit預設 50、最大 100;nextToken不要解析或修改,翻頁期間頁面鎖定到同一發布版本。
控制台
在知識圖譜頁查看發行頁面列表(路徑、標題、摘要)。
SDK
Python
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.ots_client.request("ListWikiPages", {
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
"limit": 50,
})
for p in resp.get("pages", []):
print(p.get("path"), p.get("title"))API
調用 ListWikiPages 列出頁面。完整欄位參見列出 Wiki 頁面。
讀取頁面
按路徑讀取一個發行頁面的完整本文。
控制台
在知識圖譜頁點擊目標頁面,查看完整本文、來源引用和出入連結。
SDK
Python
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.ots_client.request("GetWikiPage", {
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
"path": "/wiki/payment-callback.md",
})
print(resp.get("content"))API
調用 GetWikiPage 讀取頁面。完整欄位參見讀取 Wiki 頁面。
搜尋網頁面
用自然語言在發行頁面中語義搜尋,返回命中頁面的路徑、標題、摘要和得分。
控制台
在知識檢索頁輸入關鍵詞,按標題、摘要和本文檢索已構建頁面。
SDK
Python
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.ots_client.request("SearchWikiPages", {
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
"query": "支付回調如何保證等冪",
"limit": 5,
})
for p in resp.get("pages", []):
print(f"[{p.get('score')}] {p.get('path')} - {p.get('title')}")API
調用 SearchWikiPages 搜尋網頁面。完整欄位參見搜尋 Wiki 頁面。
更新 Wiki
更新 Wiki 的顯示名稱或摘要。
控制台
在 Wiki 頁面點擊設定,修改名稱或摘要。
SDK
Python
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
client.ots_client.request("UpdateWiki", {
"memoryStoreName": "agent_memory",
"scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant"},
"name": "支付與對賬 Wiki",
"summary": "包含支付回調、對賬和等冪約定",
})API
調用 UpdateWiki 更新 Wiki。完整欄位參見更新 Wiki。
構建品質與限制
GetWiki.latestBuild.quality 提供來源覆蓋率、頁面引用情況和連結品質等指標,用於判斷頁面是否需要人工抽查;構建成功不代表每個來源都被完整表達,也不代表所有事實都經過業務驗證。
專案 | 限制 |
單個 Wiki 來源數 | 2000 |
單次構建唯一二進位來源數 | 50 |
單次構建來源總量 | 20 MiB |
單次構建頁面數 | 500 |
單個頁面本文 | 100 KiB |
單次構建頁面總量 | 20 MiB |
| 50 / 100 |
| 10 / 100 |