本機處理常式開發與測試 development
在本機開發處理常式時,請使用此參考。 如需處理常式結果合約,請參閱自訂產生的處理常式。
要求
- Node.js 24或更新版本。
- npm.
- 連結的處理常式存放庫的本機複製。
針對LLM Apps受管理基礎結構,請先要求存放庫存取權,然後再按照此參考操作。 本機處理常式執行不需要Adobe憑證,但受保護的上游服務仍需要其自己的授權存取權。
專案結構
目前的處理常式樣版遵循此配置:
your-llm-app/
├── entry.js # Webpack entry — do not modify
├── actions/ # One folder per action
│ └── echo/
│ └── index.js # Example handler
├── test/
│ ├── actions/
│ │ └── echo.test.js
│ ├── fixtures/
│ │ └── actions.json
│ ├── html-transform.js
│ ├── jest.setup.js
│ └── server.test.js
├── server/
│ └── local.js # Local dev server (port 9080)
├── actions.json # Gitignored — optional local metadata
├── app.config.yaml # Adobe I/O Runtime config
├── webpack.config.js
└── package.json
要點:
entry.js是webpack進入點。 在建置時,它會發現每個actions/*/index.js檔案,並將它們整合到單一dist/index.js中。 請勿修改進入點。actions.json已授權。 部署管道會自動從LLM Apps中的動作中繼資料寫入它。- 測試在
test/actions/下存放,不在actions/內。 組建會探索處理常式進入點並整合其匯入;將測試保留在該探索樹之外。 - 動作路徑使用程式碼識別碼或其連字格式。 例如,
search_products解析為actions/search_products/index.js,或針對產生的程式碼actions/search-products/index.js。 顯示名稱不是查詢鍵。 - 處理常式匯入支援的資料 (例如產生的
data.json)時,會將其整合。
本機開發
若要在本機開發和測試沒有Adobe憑證的處理常式,請執行:
npm install
npm run dev:local
開發命令會使用webpack建置專案,並在http://localhost:9080上啟動純Node.js HTTP伺服器。 在處理常式或本機中繼資料變更後,停止並重新執行npm run dev:local;命令不會監視檔案。
使用不同的連線埠:
PORT=9081 npm run dev:local
本機中繼資料行為
目前的UI不提供actions.json下載,即使樣板README和執行階段啟動橫幅提及一個。 本機伺服器也會在沒有填入檔案的情況下啟動:當檔案遺失時,組建會建立{"actions":[]},而執行階段會退回處理常式探索。
探索對於列出處理常式很有用,但不是完整的引數測試模式。 如果沒有輸入結構描述,MCP SDK會呼叫具有執行階段內容作為其第一個引數的處理常式,而不是使用一般(args, extra)簽章。 SDK不會轉送提供的動作引數。
針對具有引數的MCP呼叫,建立代表性中繼資料符合動作編輯器的僅限本機 actions.json。 對於樣版echo處理常式:
{
"actions": [
{
"name": "echo",
"description": "Echo the supplied message.",
"inputSchema": {
"type": "object",
"properties": {
"message": { "type": "string" }
},
"required": ["message"]
}
}
]
}
當actions陣列非空白時,執行階段只會登入陣列中命名的動作。 使用每個動作的程式碼識別碼做為name。 即使是沒有引數的動作,也需要有"properties": {}的物件結構描述以保留一般處理常式簽章。
本機中繼資料不會更新UI或部署設定。 執行階段會驗證支援的型別、必填欄位、列舉和陣列專案,但不是每個JSON結構描述限制;驗證處理常式中的長度、範圍、巢狀物件和商業規則。 樣板整合測試使用test/fixtures/actions.json作為代表性中繼資料。
本機應用程式變數
應用程式變數透過extra.variables而非process.env到達處理常式。 從@adobe/llm-apps-runtime使用getVariable(extra, name)閱讀。 若要在建立後模擬非敏感設定:
npm run build
node server/local.js \
--param 'LLMA_VARIABLE_NAMES=["GREETING_PREFIX"]' \
--param GREETING_PREFIX=Howdy
提供JSON資訊清單和具名值。 在測試其一般(args, extra)合約時,使用輸入結構描述在本機actions.json中包含處理常式。 命令列標幟不會從平台載入應用程式設定。 請參閱設定應用程式變數和密碼以取得特定於環境的部署設定。
使用curl測試
新增上述本機echo中繼資料後,建置並啟動伺服器,然後執行:
# List all registered tools
curl -sX POST "http://localhost:9080" \
-H 'content-type: application/json' \
-H 'accept: application/json;q=1.0, text/event-stream;q=0.5' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Call the boilerplate echo action (returns "Echo: hello")
curl -sX POST "http://localhost:9080" \
-H 'content-type: application/json' \
-H 'accept: application/json;q=1.0, text/event-stream;q=0.5' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"echo","arguments":{"message":"hello"}}}'
使用MCP檢查器測試
npx @modelcontextprotocol/inspector
將 傳輸型別 設定為streamable-http並將 URL 設定為http://localhost:9080。
測試
處理常式單元測試在test/actions/下執行,並直接呼叫匯出的函式,而不使用MCP結構描述驗證:
// test/actions/echo.test.js
const handler = require('../../actions/echo/index.js')
test('echoes the message', async () => {
const result = await handler({ message: 'hello' })
expect(result.content[0].text).toBe('Echo: hello')
})
test('always returns content parts', async () => {
const result = await handler({})
expect(Array.isArray(result.content)).toBe(true)
})
使用下列專案執行測試:
npm test # configured Jest suite
npm test -- --runInBand test/actions/echo.test.js # one boilerplate action
有些產生的測試會使用Node的內建測試執行器,而非Jest。 檢查測試匯入,並使用相符的執行器,例如,匯入node:test的檔案node --test test/actions/search-products.test.js。 將檔案放置在test/actions/下後,驗證產生的相對匯入。
單元測試本身不會驗證中繼資料、MCP驗證、Widget載入或主機行為。 使用代表性中繼資料測試本機端點,然後在支援的LLM平台上測試已部署的應用程式。
本機測試通過後,推送變更並遵循部署變更。