Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .agents/skills/floatboat-workbench/references/llm.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Calls that name no model use `DEFAULT_LLM_MODEL` (`gemini-3.8-flash`, exported b

## Conversations, tools and reasoning

Pass `messages` instead of `prompt` (one or the other) for multi-turn calls: `{ role: 'system' | 'user', content }`, `{ role: 'user', content: [{ type: 'text', text }, { type: 'image', image }] }` and `{ role: 'tool', toolCallId, content }`. Append the previous result's `assistant` unchanged; its `hostState` is encrypted reasoning material the Host needs for the next turn. Do not edit it; if it is altered or the account changes, the Host continues without it instead of failing. `reasoning: 'off' | 'low' | 'medium' | 'high'` sets reasoning effort and falls back to off on models without it.
Pass `messages` instead of `prompt` (one or the other) for multi-turn calls: `{ role: 'system' | 'user', content }`, `{ role: 'user', content: [{ type: 'text', text }, { type: 'image', image }] }` and `{ role: 'tool', toolCallId, content }`. Append the previous result's `assistant` unchanged; its `hostState` is encrypted reasoning material the Host needs for the next turn. Do not edit it; if it is altered or the account changes, the Host continues without it instead of failing. `reasoning: 'off' | 'low' | 'medium' | 'high'` sets reasoning effort and falls back to off on models without it. `webSearch: true` on `generateText` or `streamText` lets the model use its provider's built-in web search for questions about current facts; it defaults to false, falls back to false on models whose `listModels` entry lacks `webSearch: true` and on Gemini calls that also pass `tools`, and adds latency and cost, so expose it as a user choice rather than turning it on for every call.

Tools run in your app, not in the Host. Pass `tools: [{ name, description?, parameters }]` (`parameters` is a JSON Schema with `type: 'object'`) and optionally `toolChoice: 'auto' | 'none' | 'required' | { name }` to `generateText` or `streamText`. When `finishReason` is `TOOL_CALLS`, run each entry of `toolCalls` (`{ id, name, input, inputError? }`) yourself, then call again with the history plus `result.assistant` and one tool message per call. `inputError` means the arguments failed the schema; return it as the tool result so the model can correct itself. Cap the number of rounds and check permissions before any tool writes data.

Expand All @@ -30,7 +30,7 @@ for (let round = 0; round < 5; round++) {

## Model catalog

`listModels({ kind? })` returns `models` (`id`, `kinds` of `text`/`speech`/`image`/`decision`/`rerank`, `inputs` of `text`/`image`, `source`), per-kind `defaults`, and `media`. Text models follow the same release, membership and local-model rules as the Floatboat chat model picker. `defaults.text` is the text default (`gemini-3.8-flash` when allowed); local models are listed with `source: 'local'` but are never a default. Speech, image, decision and rerank models come from a list Floatboat configures remotely (the first entry of each kind is its default), so `media` is always `available`; the platform may change these lists without an app update. Choose models from this result rather than hard-coding names.
`listModels({ kind? })` returns `models` (`id`, `kinds` of `text`/`speech`/`image`/`decision`/`rerank`, `inputs` of `text`/`image`, `source`, and for text models `webSearch` telling whether `webSearch: true` takes effect), per-kind `defaults`, and `media`. Text models follow the same release, membership and local-model rules as the Floatboat chat model picker. `defaults.text` is the text default (`gemini-3.8-flash` when allowed); local models are listed with `source: 'local'` but are never a default. Speech, image, decision and rerank models come from a list Floatboat configures remotely (the first entry of each kind is its default), so `media` is always `available`; the platform may change these lists without an app update. Choose models from this result rather than hard-coding names.

## Speech and images

Expand Down Expand Up @@ -63,7 +63,7 @@ const result = await app.host.llm.decide({

## Required Host operations

`pnpm workbench:check` and Floatboat builds scan the server code and write Host operations newer than the baseline (for example `llm.rerank`, or `llm.messages` / `llm.tools` / `llm.reasoning` / `llm.images` when text calls use those fields) to `manifest.requires.operations`. Older Floatboat clients then ask the user to update instead of failing at runtime. Commit the field with your code; the build only adds entries, so remove one by hand only when the code no longer uses it.
`pnpm workbench:check` and Floatboat builds scan the server code and write Host operations newer than the baseline (for example `llm.rerank`, or `llm.messages` / `llm.tools` / `llm.reasoning` / `llm.webSearch` / `llm.images` when text calls use those fields) to `manifest.requires.operations`. Older Floatboat clients then ask the user to update instead of failing at runtime. Commit the field with your code; the build only adds entries, so remove one by hand only when the code no longer uses it.

## Errors and billing

Expand Down
4 changes: 4 additions & 0 deletions sdk/host-contracts.mts
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,8 @@ export type ModelInput = ModelConversation & {
export type TextModelInput = ModelInput & {
tools?: ToolDefinition[];
toolChoice?: ToolChoice;
/** 使用模型供应商自带的联网搜索,默认 false;模型不支持时 Host 按 false 处理。 */
webSearch?: boolean;
};

export type ModelKind = 'text' | 'speech' | 'image' | 'decision' | 'embedding' | 'rerank';
Expand All @@ -94,6 +96,8 @@ export interface ModelCatalogEntry {
kinds: ModelKind[];
inputs: Array<'text' | 'image'>;
source: 'platform' | 'local';
/** 文本模型是否支持 webSearch;未标注时按不支持处理。 */
webSearch?: boolean;
}

export interface ModelCatalog {
Expand Down
4 changes: 2 additions & 2 deletions tests/authoring.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -206,12 +206,12 @@ test('检查扫描服务端新 Host 操作写入 requires,只用基线操作
app.route('POST', '/api/search', async ({ host }) => {
const { embed } = host.llm;
const vectors = await embed({ model: 'embed-test', input: ['a'] });
const answer = await host.llm.generateText({ messages: [{ role: 'user', content: 'hi' }] });
const answer = await host.llm.generateText({ messages: [{ role: 'user', content: 'hi' }], webSearch: true });
return { size: vectors.embeddings.length, text: answer.text };
});
await app.listen();`));
const checked = await checkApplication(root);
assert.deepEqual(checked.requires, { operations: ['llm.embed', 'llm.messages'] });
assert.deepEqual(checked.requires, { operations: ['llm.embed', 'llm.messages', 'llm.webSearch'] });
assert.deepEqual(JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8')).requires, checked.requires);
});

Expand Down
1 change: 1 addition & 0 deletions tooling/compiler/host-operations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ const TEXT_FEATURE_FIELDS: Readonly<Record<string, string>> = {
tools: 'llm.tools',
toolChoice: 'llm.tools',
reasoning: 'llm.reasoning',
webSearch: 'llm.webSearch',
};
/** 旧客户端严格校验会拒收的 Agent 调用字段。 */
const AGENT_FEATURE_FIELDS: Readonly<Record<string, string>> = { instructions: 'agent.instructions' };
Expand Down
1 change: 1 addition & 0 deletions tooling/contracts/workbenchOperations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ export const WORKBENCH_SDK_FEATURES = [
'llm.messages',
'llm.tools',
'llm.reasoning',
'llm.webSearch',
'agent.instructions',
'agent.tools',
] as const;
Expand Down
Loading