docs: refresh translations for recent English changes (#3379)
This commit is contained in:
parent
d8b638304e
commit
c5d7d0b6d0
1 changed files with 3149 additions and 1047 deletions
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
translation:
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, ffe823cb0fedd488, f33651add1b59094]
|
||||
sections: [d65c098f37f5b6c3, dd0c2724d6f2877e, 6835bb3570c6714c, d30d3c20168b88b2, f5ef38dad59d6f76, 6e38a699ba57fbdf, 2b984a3bf37a0ddd]
|
||||
tool: 1
|
||||
---
|
||||
# 提示詞 {#prompts}
|
||||
|
|
@ -137,7 +137,52 @@ uv run mcp dev server.py
|
|||
```
|
||||
|
||||
!!! info
|
||||
如果讀過 **[工具](tools.md)**,這一頁的內容你都已經會了。同樣的裝飾器、同樣以 docstring 當描述、同樣的 `Annotated`/`Field`。唯一不同的是由誰觸發(使用者),以及結果去哪裡(進入對話)。
|
||||
如果讀過 **[工具](tools.md)**,到這裡為止的內容你都已經會了。同樣的裝飾器、同樣以 docstring 當描述、同樣的 `Annotated`/`Field`。唯一不同的是由誰觸發(使用者),以及結果去哪裡(進入對話)。
|
||||
|
||||
## 不只是文字 {#more-than-text}
|
||||
|
||||
`UserMessage` 和 `AssistantMessage` 凡是接受 `str` 的地方,也都接受內容區塊,或 `Image`/`Audio` 輔助類別。提示詞裡常見兩種情況:附上一份文件,以及附上一張圖片。
|
||||
|
||||
### 嵌入檔案 {#embedding-a-file}
|
||||
|
||||
```python title="server.py" hl_lines="5 12 21 23"
|
||||
--8<-- "docs_src/prompts/tutorial004.py"
|
||||
```
|
||||
|
||||
* 風格指南是位於 `style://python` 的資源(**[資源](resources.md)** 會介紹),從 `server.py` 旁邊的 `style-guide.md` 讀取。放任何一個 Markdown 檔案在那裡都可以。
|
||||
* `EmbeddedResource(resource=TextResourceContents(...))`(兩者都來自 `mcp.types`)把檔案連同 URI 和 MIME 類型當成第一則訊息帶上;引用它的請求以純文字接在後面。
|
||||
* 用嵌入而不是把指南貼進 f-string,用戶端就能把它顯示成附件,之後還能重新打開 `style://python`,而模型收到的是原封不動的檔案。二進位檔案則改用 `BlobResourceContents` 搭配 base64 的 `blob`。
|
||||
|
||||
算繪之後,第一則訊息的 `content` 是一個 `resource` 區塊:
|
||||
|
||||
```json
|
||||
{"type": "resource", "resource": {"uri": "style://python", "mimeType": "text/markdown", "text": "* Prefer early returns.\n..."}}
|
||||
```
|
||||
|
||||
### 附上圖片 {#attaching-an-image}
|
||||
|
||||
```python title="server.py" hl_lines="4 15"
|
||||
--8<-- "docs_src/prompts/tutorial005.py"
|
||||
```
|
||||
|
||||
* `Image` 是 **[圖片、音訊與圖示](media.md)** 裡的輔助類別。提示詞算繪時,`UserMessage` 會把它轉成 `ImageContent` 區塊(檔案以 base64 編碼,MIME 類型從 `.png` 推測);`Audio` 也以同樣方式變成 `AudioContent`。
|
||||
* 在 `server.py` 旁邊放任何一張名為 `architecture.png` 的 PNG。提示詞引數是字串,所以圖片一定來自伺服器;`component` 只提供文字。
|
||||
|
||||
```json
|
||||
{"type": "image", "data": "iVBORw0KGgoAAAANSUhEUg...", "mimeType": "image/png"}
|
||||
```
|
||||
|
||||
## 執行時變更清單 {#changing-the-list-at-runtime}
|
||||
|
||||
用戶端連著的時候也可以新增提示詞,例如讓使用者把一段指示存成自己的選單項目。先註冊提示詞,再發通知:
|
||||
|
||||
```python title="server.py" hl_lines="5 23-27"
|
||||
--8<-- "docs_src/prompts/tutorial006.py"
|
||||
```
|
||||
|
||||
* `mcp.add_prompt(Prompt.from_function(fn, name=..., description=...))` 註冊函式的效果和 `@mcp.prompt()` 完全一樣,`mcp.remove_prompt(name)` 則是反過來。`add_prompt` 遇到同名的既有項目會保留而不覆寫,所以這個工具會先移除舊的,讓儲存變成取代。`prompts/list` 會立即反映變更。
|
||||
* `await ctx.notify_prompts_changed()` 把 `notifications/prompts/list_changed` 送給每個在 `subscriptions/listen` 串流上監聽的 `2026-07-28` 用戶端(**[訂閱](../handlers/subscriptions.md)**)。呼叫端是 2026 之前的用戶端時,`await ctx.session.send_prompt_list_changed()` 會把通知送給它(**[服務舊版用戶端](../run/legacy-clients.md)**)。兩個都呼叫;沒有人可通知時,各自什麼都不做。
|
||||
* 收到通知的用戶端會再呼叫一次 `prompts/list`。在 Python 的 `Client` 裡寫成 `async with client.listen(prompts_list_changed=True) as sub:`,會產出 `PromptsListChanged` 事件。
|
||||
|
||||
## 重點回顧 {#recap}
|
||||
|
||||
|
|
@ -147,5 +192,7 @@ uv run mcp dev server.py
|
|||
* 回傳 `str` 會變成一則使用者訊息。回傳 `UserMessage`/`AssistantMessage` 的清單,可以替多輪對話起頭。
|
||||
* `title=` 和 `Field(description=...)` 是用戶端放在 UI 上的內容。
|
||||
* 缺少必填引數會讓整個請求失敗,沒有個別提示詞的錯誤結果。
|
||||
* 把 `EmbeddedResource` 或 `Image` 包進 `UserMessage`,就能附上文件或圖片。
|
||||
* 執行時用 `mcp.add_prompt(...)`/`mcp.remove_prompt(...)` 新增或移除提示詞,接著 `await ctx.notify_prompts_changed()` 和 `await ctx.session.send_prompt_list_changed()`。
|
||||
|
||||
伺服器端替提示詞(或資源範本)引數做自動完成,請見 **[自動完成](completions.md)**。
|
||||
|
|
|
|||
Loading…
Reference in a new issue