參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

設計語言模型提示詞

您可以透過字串拼接來構建語言模型提示詞，但這很難組合功能並確保您的提示詞保持在語言模型的上下文視窗內。為了克服這些限制，您可以使用 @vscode/prompt-tsx 庫。

@vscode/prompt-tsx 庫提供以下功能：

  • 基於 TSX 的提示詞渲染：使用 TSX 元件組合提示詞，使其更具可讀性和可維護性
  • 基於優先順序的剪枝：自動剪枝提示詞中不那麼重要的部分，以適應模型的上下文視窗
  • 靈活的令牌管理：使用 flexGrow、flexReserve 和 flexBasis 等屬性來協同使用令牌預算
  • 工具整合：與 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 屬性協同調整檔案內容的大小以適應令牌預算。

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

首先，您定義一個包含基本指令的 UserMessage 元件。

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

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

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

步驟 2：包含檔案內容

現在，您可以使用 FileContext 元件包含檔案內容。您為其分配一個 1 的 flexGrow 值，以確保它在基本指令、使用者查詢和歷史之後渲染。

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

透過 flexGrow 值，元素在其傳遞給其 render() 和 prepare() 呼叫的 PromptSizing 物件中獲得任何未使用的令牌預算。您可以在 prompt-tsx 文件中閱讀有關 flex 元素行為的更多資訊。

步驟 3：包含歷史記錄

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

因此，為 History 元件分配一個 2 的 flexGrow 值，以確保它在所有其他元素（包括 <FileContext />）之後渲染。但是，也要設定一個 "/5" 的 flexReserve 值，以為歷史記錄保留總預算的 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 協同調整檔案內容的大小以適應令牌預算。

透過遵循此模式，您可以確保始終包含提示詞中最重要的部分，同時根據需要剪枝不那麼重要的部分以適應模型的上下文視窗。有關 getExpandedFiles 方法和 FileContextTracker 類的完整實現細節，請參閱 prompt-tsx 倉庫。

09/11/2025