7.5 KiB
7.5 KiB
resource 应用协议
TL;DR: resource标签用于定义资源协议，提供统一的资源引用方式，支持通过
@协议名://路径形式访问各类资源。
🔍 基本信息
标签名: <resource>
版本: 1.0.0
类别: 资源
状态: 草稿
创建日期: 2023-06-30
目的与功能
resource标签用于定义特定类型的资源协议，使开发者能够以标准化的方式描述如何引用和处理各种资源。通过这个标签，可以明确资源的引用语法、路径规则和查询参数，确保资源引用在不同环境中的一致性和可靠性。此标签是PromptX中资源引用协议（RP）在应用层面的具体实现方式。
主要功能包括：
- 定义资源协议的标识和引用方式
- 规范资源路径的语法结构和解析规则
- 指定资源支持的查询参数和格式
- 提供资源使用的示例说明
默认支持的通用协议
PromptX默认支持以下通用且已有共识的协议，这些协议符合@协议名://路径格式，遵循其业界标准语法和规则，无需在resource标签中重新定义：
| 协议名 | 描述 | 示例 |
|---|---|---|
| file | 文件系统资源 | @file://path/to/file.txt |
| http/https | HTTP/HTTPS网络资源 | @https://example.com/api/data |
| ftp/sftp | 文件传输协议 | @ftp://user:pass@host/path |
| ssh | 安全Shell协议 | @ssh://user@host/path |
这些通用协议的路径格式和查询参数遵循它们的标准规范。对于特定领域或自定义的协议，才需要使用resource标签进行详细定义。
📝 语法定义
(* EBNF形式化定义 *)
resource_element ::= '<resource' ' protocol="' protocol_name '"' '>' content '</resource>'
protocol_name ::= [a-zA-Z][a-zA-Z0-9_-]*
content ::= (markdown_content | location_element | params_element)+
location_element ::= '<location>' markdown_content '</location>'
params_element ::= '<params>' markdown_content '</params>'
markdown_content ::= (* 任何有效的Markdown文本，包括代码块、表格等 *)
🧩 语义说明
resource标签定义了一个资源协议，指定了如何使用@协议名://路径的形式引用和访问特定类型的资源。
标签包含的主要子元素及其语义：
- protocol属性：定义资源协议的名称，如
file、http、context等 - location子标签：定义资源路径的格式和规则，指定如何定位资源
- params子标签：定义资源支持的查询参数，指定如何处理资源的特定部分或格式
资源引用语法
资源引用使用@符号作为统一入口，遵循以下核心语法规则：
resource_reference ::= '@' protocol_name ':' resource_location [query_params]
resource_location ::= uri | nested_reference
uri ::= protocol_name '://' path
nested_reference ::= ['@'] protocol_name ':' resource_location
path ::= path_segment {'/' path_segment}
query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value}
基础资源引用
基础资源引用使用单一协议：
@protocol://path
例如：
@file://document.md- 引用文件系统中的文档@http://example.com/api/data.json- 引用网络资源@memory://user_preferences- 引用内存中的数据
嵌套资源引用
嵌套资源引用允许一个协议处理另一个协议的输出：
完整形式（内部使用@符号）：
@outer:@inner://path
简写形式（内部省略@符号）：
@outer:inner://path
例如：
@thinking:@file://method.md- 对文件内容应用thinking协议处理@execution:file://workflow.md- 对文件内容应用execution协议处理@outer:middle:inner://resource- 多层嵌套（从内向外处理）
路径通配符
路径支持以下通配符模式：
*- 匹配单层中的任意文件或目录，如@file://docs/*.md**- 匹配多层目录和文件，如@file://src/**/*.js*.ext- 匹配特定扩展名的文件，如@file://docs/*.txt*.{ext1,ext2}- 匹配多种扩展名，如@file://src/*.{js,ts}
查询参数
查询参数提供额外的资源处理指令：
@protocol://path?param1=value1¶m2=value2
例如：
@file://document.md?line=5-10- 只获取文件的第5-10行@http://api.example.com/data?format=json&cache=false- 指定返回格式并禁用缓存
解析规则
- 资源引用解析从左至右进行，先识别协议名称，再解析资源位置和查询参数
- 嵌套引用从内向外解析，内层资源引用的结果作为外层引用的输入
- 查询参数应用于资源加载后的处理阶段，不影响资源的基本定位
- 相对路径解析基于当前上下文的工作目录或基础路径
💡 最佳实践
以下是使用resource标签的一些推荐做法：
资源路径设计
资源路径设计应遵循以下原则：
- 使用直观、符合惯例的路径格式
- 支持绝对路径和相对路径
- 适当使用通配符增强灵活性
- 路径分隔符应统一使用
/
查询参数设计
查询参数设计应考虑以下因素：
- 参数名称应清晰表达其功能
- 参数值格式应明确定义
- 常见操作应有对应的参数支持（如范围指定、格式转换等）
- 参数组合应有明确的优先级规则
资源引用最佳实践
- 使用最合适的协议名称表示资源类型，提高语义明确性
- 嵌套引用时，如果清晰度很重要，使用完整形式（带内部@符号）
- 如果简洁性更重要，则使用简写形式（省略内部@符号）
- 保持资源路径的相对引用，以提高提示词的可移植性
- 合理使用通配符，避免过于宽泛的匹配模式
- 使用查询参数进行资源过滤，而不是在提示词中手动处理
- 避免过深的嵌套引用，建议不超过3层，保持可读性
表达风格推荐
- location: 优先使用EBNF格式正式描述语法规则，辅以简洁示例
- params: 使用表格形式列出参数，清晰展示名称、类型、描述和示例
📋 使用示例
自定义协议示例
以下示例展示了如何定义自定义资源协议：
# 路径规则 (EBNF)```ebnf
memory_path ::= [namespace '/'] memory_key
namespace ::= (letter | digit | '_' | '-')+
memory_key ::= (letter | digit | '_' | '-' | '.')+
```
## 示例
- @memory://user_preferences
- @memory://session/history
- @memory://system/config
| 参数名 | 类型 | 描述 | 示例 |
|-------|------|------|------|
| ttl | 数字 | 生存时间(秒) | ?ttl=3600 |
| default | 字符串 | 默认值 | ?default=empty |
| type | 字符串 | 值类型 | ?type=json |
```ebnf
context_path ::= [scope '/'] path
scope ::= (letter | digit | '_' | '-')+
path ::= path_segment {'/' path_segment}
path_segment ::= (letter | digit | '_' | '-' | '.')+
```
## 示例
- @context://global/settings
- @context://user/preferences
- @context://session/state
| 参数名 | 类型 | 描述 | 示例 |
|-------|------|------|------|
| mode | 字符串 | 上下文模式 | ?mode=read 或 ?mode=write |
| scope | 字符串 | 访问范围 | ?scope=local 或 ?scope=global |
| format | 字符串 | 返回格式 | ?format=json |