🚀 在 VS Code 中取得！

設計語言模型提示

您可以使用字串串連來建立語言模型提示，但很難組合功能並確保您的提示保持在語言模型的內容視窗內。為了克服這些限制，您可以使用 @vscode/prompt-tsx 程式庫。

@vscode/prompt-tsx 程式庫提供下列功能

  • 以 TSX 為基礎的提示轉譯：使用 TSX 元件撰寫提示，使其更易於閱讀和維護
  • 以優先順序為基礎的修剪：自動修剪提示中較不重要的部分，以符合模型的內容視窗
  • 彈性的 Token 管理：使用 flexGrow、flexReserve 和 flexBasis 等屬性，以協同方式使用 Token 預算
  • 工具整合：與 VS Code 的語言模型工具 API 整合

如需所有功能和詳細使用說明的完整概觀，請參閱完整 README。

本文說明使用此程式庫設計提示的實務範例。這些範例的完整程式碼可在 prompt-tsx 存放庫中找到。

管理對話記錄中的優先順序

在提示中包含對話記錄非常重要，因為它讓使用者能夠針對先前的訊息提出後續問題。但是，您需要確保其優先順序得到適當處理，因為記錄可能會隨著時間推移而變得龐大。我們發現，通常最合理的模式是依序優先處理

  1. 基本提示指示
  2. 目前使用者查詢
  3. 最近幾輪的聊天記錄
  4. 任何支援資料
  5. 盡可能符合剩餘記錄

基於這個原因，請在提示中將記錄分成兩個部分，其中最近的提示輪次優先於一般內容資訊。

在此程式庫中，樹狀結構中的每個 TSX 節點都有一個優先順序，在概念上類似於 zIndex，其中數字越高表示優先順序越高。

步驟 1：定義 HistoryMessages 元件

若要列出歷程訊息，請定義 HistoryMessages 元件。此範例提供了一個良好的起點，但如果您處理更複雜的資料類型，可能需要擴充它。

此範例使用 PrioritizedList 協助程式元件，它會自動為其每個子系指派遞增或遞減的優先順序。

import {
	UserMessage,
	AssistantMessage,
	PromptElement,
	BasePromptElementProps,
	PrioritizedList,
} from '@vscode/prompt-tsx';
import { ChatContext, ChatRequestTurn, ChatResponseTurn, ChatResponseMarkdownPart } from 'vscode';

interface IHistoryMessagesProps extends BasePromptElementProps {
	history: ChatContext['history'];
}

export class HistoryMessages extends PromptElement<IHistoryMessagesProps> {
	render(): PromptPiece {
		const history: (UserMessage | AssistantMessage)[] = [];
		for (const turn of this.props.history) {
			if (turn instanceof ChatRequestTurn) {
				history.push(<UserMessage>{turn.prompt}</UserMessage>);
			} else if (turn instanceof ChatResponseTurn) {
				history.push(
					<AssistantMessage name={turn.participant}>
						{chatResponseToMarkdown(turn)}
					</AssistantMessage>
				);
			}
		}
		return (
			<PrioritizedList priority={0} descending={false}>
				{history}
			</PrioritizedList>
		);
	}
}

步驟 2：定義 Prompt 元件

接下來，定義一個 MyPrompt 元件，其中包含基本指示、使用者查詢和具有適當優先順序的歷程訊息。優先順序值在同層級之間是本機的。請記住，您可能想要在觸及提示中的任何其他內容之前修剪較舊的訊息，因此您需要拆分兩個 <HistoryMessages> 元素

import {
	UserMessage,
	PromptElement,
	BasePromptElementProps,
} from '@vscode/prompt-tsx';

interface IMyPromptProps extends BasePromptElementProps {
	history: ChatContext['history'];
	userQuery: string;
}

export class MyPrompt extends PromptElement<IMyPromptProps> {
	render() {
		return (
			<>
				<UserMessage priority={100}>
					Here are your base instructions. They have the highest priority because you want to make
					sure they're always included!
				</UserMessage>
				{/* Older messages in the history have the lowest priority since they're less relevant */}
				<HistoryMessages history={this.props.history.slice(0, -2)} priority={0} />
				{/* The last 2 history messages are preferred over any workspace context you have below */}
				<HistoryMessages history={this.props.history.slice(-2)} priority={80} />
				{/* The user query is right behind the based instructions in priority */}
				<UserMessage priority={90}>{this.props.userQuery}</UserMessage>
				<UserMessage priority={70}>
					With a slightly lower priority, you can include some contextual data about the workspace
					or files here...
				</UserMessage>
			</>
		);
	}
}

現在，所有較舊的歷程訊息都會在程式庫嘗試修剪提示的其他元素之前修剪。

步驟 3：定義 History 元件

為了讓使用更輕鬆一點，請定義一個 History 元件，它會包裝歷程訊息，並使用 passPriority 屬性作為傳遞容器。使用 passPriority 時，其子系會被視為優先順序目的的包含元素的直接子系。

import { PromptElement, BasePromptElementProps } from '@vscode/prompt-tsx';

interface IHistoryProps extends BasePromptElementProps {
	history: ChatContext['history'];
	newer: number; // last 2 message priority values
	older: number; // previous message priority values
	passPriority: true; // require this prop be set!
}

export class History extends PromptElement<IHistoryProps> {
	render(): PromptPiece {
		return (
			<>
				<HistoryMessages history={this.props.history.slice(0, -2)} priority={this.props.older} />
				<HistoryMessages history={this.props.history.slice(-2)} priority={this.props.newer} />
			</>
		);
	}
}

現在，您可以使用和重複使用這個單一元素來包含聊天記錄

<History history={this.props.history} passPriority older={0} newer={80}/>

擴展檔案內容以符合

在本範例中，您想要在提示中包含使用者目前正在檢視的所有檔案的內容。這些檔案可能很大，以至於包含所有檔案可能會導致其文字被修剪！此範例示範如何使用 flexGrow 屬性以協同方式調整檔案內容的大小，以符合 Token 預算。

步驟 1：定義基本指示和使用者查詢

首先，您定義一個 UserMessage 元件，其中包含基本指示。

<UserMessage priority={100}>Here are your base instructions.</UserMessage>

然後，您可以使用 UserMessage 元件包含使用者查詢。此元件具有高優先順序，以確保它在基本指示之後立即包含在內。

<UserMessage priority={90}>{this.props.userQuery}</UserMessage>

步驟 2：包含檔案內容

您現在可以使用 FileContext 元件包含檔案內容。您可以為其指派 flexGrow 值 1，以確保它在基本指示、使用者查詢和歷程記錄之後轉譯。

<FileContext priority={70} flexGrow={1} files={this.props.files} />

使用 flexGrow 值，元素會在傳遞至其 render() 和 prepare() 呼叫的 PromptSizing 物件中取得任何未使用的 Token 預算。您可以在 prompt-tsx 文件中閱讀更多關於彈性元素行為的資訊。

步驟 3：包含歷程記錄

接下來，使用您先前建立的 History 元件包含歷程訊息。這有點棘手，因為您確實想要顯示一些歷程記錄，但也希望檔案內容佔用提示的大部分空間。

因此，請為 History 元件指派 flexGrow 值 2，以確保它在所有其他元素（包括 <FileContext />）之後轉譯。但是，也設定 flexReserve 值 "/5"，為歷程記錄保留總預算的 1/5。

<History
	history={this.props.history}
	passPriority
	older={0}
	newer={80}
	flexGrow={2}
	flexReserve="/5"
/>

步驟 3：合併提示的所有元素

現在，將所有元素合併到 MyPrompt 元件中。

import {
	UserMessage,
	PromptElement,
	BasePromptElementProps,
} from '@vscode/prompt-tsx';
import { History } from './history';

interface IFilesToInclude {
	document: TextDocument;
	line: number;
}

interface IMyPromptProps extends BasePromptElementProps {
	history: ChatContext['history'];
	userQuery: string;
	files: IFilesToInclude[];
}

export class MyPrompt extends PromptElement<IMyPromptProps> {
	render() {
		return (
			<>
				<UserMessage priority={100}>Here are your base instructions.</UserMessage>
				<History
					history={this.props.history}
					passPriority
					older={0}
					newer={80}
					flexGrow={2}
					flexReserve="/5"
				/>
				<UserMessage priority={90}>{this.props.userQuery}</UserMessage>
				<FileContext priority={70} flexGrow={1} files={this.props.files} />
			</>
		);
	}
}

步驟 4：定義 FileContext 元件

最後，定義一個 FileContext 元件，其中包含使用者目前正在檢視的檔案內容。由於您使用了 flexGrow，因此您可以使用 PromptSizing 中的資訊來實作邏輯，以取得每個檔案「感興趣」行周圍的盡可能多的行數。

為了簡潔起見，省略了 getExpandedFiles 的實作邏輯。您可以在 prompt-tsx 存放庫中查看。

import { PromptElement, BasePromptElementProps, PromptSizing, PromptPiece } from '@vscode/prompt-tsx';

class FileContext extends PromptElement<{ files: IFilesToInclude[] } & BasePromptElementProps> {
	async render(_state: void, sizing: PromptSizing): Promise<PromptPiece> {
		const files = await this.getExpandedFiles(sizing);
		return <>{files.map(f => f.toString())}</>;
	}

	private async getExpandedFiles(sizing: PromptSizing) {
		// Implementation details are summarized here.
		// Refer to the repo for the complete implementation.
	}
}

摘要

在這些範例中，您建立了一個 MyPrompt 元件，其中包含基本指示、使用者查詢、歷程訊息和具有不同優先順序的檔案內容。您使用了 flexGrow 以協同方式調整檔案內容的大小，以符合 Token 預算。

透過遵循此模式，您可以確保始終包含提示中最重要的部分，而較不重要的部分會根據需要進行修剪，以符合模型的內容視窗。如需 getExpandedFiles 方法和 FileContextTracker 類別的完整實作詳細資訊，請參閱 prompt-tsx 存放庫。

04/03/2025