8.3 KiB
8.3 KiB
资源引用(RP) 模式协议
TL;DR: 资源引用协议定义了使用@符号统一引用各类资源的语法规则，支持基础资源定位和嵌套引用，实现提示词中的资源无缝集成。
🔍 协议概述
协议名称: 资源引用协议 (Resource Protocol, RP) 版本: 1.0.0 状态: 草稿 作者: PromptX团队 创建日期: 2023-06-25 最后更新: 2023-06-25
目的与范围
资源引用协议旨在提供一种统一的语法机制，使提示词能够无缝引用和整合各种类型的资源，包括文件、目录、网络资源以及特定的应用协议。本协议定义了资源定位的基本语法、组合规则和链式调用机制，使提示词能够更加灵活地整合和使用外部资源。
相关协议
- DPML核心协议：提供基础的标记语言结构
- 应用协议：如thinking、executing等可以与资源协议组合使用
📝 语法规则
形式化定义
resource_reference ::= '@' protocol_name ':' resource_location [query_params]
resource_location ::= uri | nested_reference
uri ::= protocol_name '://' path
nested_reference ::= ['@'] protocol_name ':' resource_location
protocol_name ::= alphanumeric_string
path ::= path_segment {'/' path_segment}
path_segment ::= alphanumeric_string | '.' | '..' | wildcard_pattern
wildcard_pattern ::= '*' | '**' | '*.' file_extension
query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value}
param_name ::= alphanumeric_string
param_value ::= alphanumeric_string | quoted_string
alphanumeric_string ::= (letter | digit | '_' | '-')+
letter ::= 'a' | 'b' | ... | 'z' | 'A' | 'B' | ... | 'Z'
digit ::= '0' | '1' | ... | '9'
quoted_string ::= '"' {any_char_except_quote} '"'
file_extension ::= letter+
词法元素
| 元素 | 形式 | 描述 |
|---|---|---|
| 资源引用标记 | @ | 所有资源引用都以@符号开始 |
| 协议名称 | 任意协议名 | 指定被引用资源的协议类型 |
| 协议分隔符 | : | 分隔协议名称和资源位置 |
| 协议路径分隔符 | :// | 用于URI路径的分隔符 |
| 路径段分隔符 | / | 分隔路径中的不同部分 |
| 查询参数开始 | ? | 标识查询参数的开始 |
| 参数分隔符 | & | 分隔多个查询参数 |
| 参数赋值 | = | 分隔参数名和参数值 |
| 通配符 | *, ** | 用于在路径中匹配一个或多个文件/目录 |
组合规则
- 单一协议引用：
@protocol://path，例如@file://document.md - 嵌套协议引用：
@outer:@inner://path，例如@thinking:@file://method.md - 嵌套协议简写：内部协议可省略@，例如
@outer:inner://path，例如@thinking:file://method.md - 路径中支持通配符：
*匹配单层中的任意文件或目录，如@file://docs/*.md**匹配多层目录和文件，如@file://src/**/*.js*.ext匹配特定扩展名的文件，如@file://docs/*.txt
这些规则构成了资源引用协议的核心，简洁而灵活地满足各种引用场景。
🧩 语义定义
核心概念
| 概念 | 定义 | 示例 |
|---|---|---|
| 基础资源 | 指向物理存储或网络位置的基本资源类型 | @file://document.txt |
| 应用协议 | 指向特定应用协议定义的资源 | @thinking://brainstorm |
| 资源路径 | 定位具体资源的路径信息 | projects/main/doc.md |
| 查询参数 | 提供资源处理或过滤的额外信息 | ?section=2&format=md |
| 嵌套引用 | 一个协议引用另一个协议 | @thinking:@file://method.md |
| 通配符 | 用于匹配多个资源的模式 | docs/.md, src/**/.js |
解释规则
- 资源引用解析从左至右进行，先识别协议名称，再解析资源位置和查询参数
- 嵌套引用从内向外解析，内层资源引用的结果作为外层引用的输入
- 如果资源类型未指定具体实现方式，则使用该类型的默认解释器
- 查询参数应用于资源加载后的处理阶段，不影响资源的基本定位
- 相对路径解析基于当前上下文的工作目录或基础路径
- 通配符解析遵循常见的glob模式规则
✅ 约束与验证
必要约束
- 协议名称必须是已注册的协议类型
- 资源路径必须符合目标系统的路径要求和访问权限
- 嵌套引用的深度不应超过3层，以保持可读性和解析效率
- 查询参数必须是目标协议类型支持的参数
验证规则
资源引用的验证包括以下步骤：
- 语法验证：检查是否符合EBNF定义的语法结构
- 协议验证：检查引用的协议类型是否已注册
- 路径验证：检查资源路径是否合法且可访问
- 参数验证：检查查询参数是否被目标协议类型支持
- 安全验证：检查资源引用是否符合安全策略
错误处理
当遇到无效的资源引用时，应采取以下处理方式：
- 语法错误：返回错误描述，指出错误位置和期望格式
- 资源不存在：返回资源未找到的错误，可能提供相似资源的建议
- 访问受限：返回权限错误，并说明所需权限
- 参数无效：返回参数错误，说明支持的参数格式
- 解析超时：对于复杂的链式调用，如果解析时间超过预设限制，返回超时错误
🔄 扩展机制
扩展点
资源引用协议可在以下方面进行扩展：
- 新的协议类型：注册新的协议
- 协议处理器：为协议类型定义处理逻辑
- 查询参数：扩展特定协议类型支持的查询参数
扩展规则
创建资源协议扩展时，应遵循以下规则：
- 新协议类型必须使用唯一的标识符，避免与现有类型冲突
- 扩展必须提供完整的处理器实现，包括资源定位、加载和转换
- 扩展应提供错误处理机制和回退策略
- 扩展必须遵循基本的安全原则，不应引入新的安全风险
扩展示例
// 定义新的协议类型
@custom://resource-path?param=value
// 嵌套协议示例
@outer:@inner://path/to/resource
// 多层嵌套示例
@outer:middle:@inner://path
📋 使用示例
有效示例
// 基础资源引用
@file://documents/report.md
// 含有通配符的引用
@file://docs/*.md
// 多层通配符引用
@file://src/**/*.js
// 特定扩展名通配符
@file://project/*.{js,ts}
// HTTP资源引用
@http://example.com/api/data.json
// 嵌套资源引用（完整形式）
@thinking:@file://method.md
// 嵌套资源引用（简写形式）
@thinking:file://method.md
// 多层嵌套（完整形式）
@outer:@middle:@inner://resource
// 多层嵌套（简写形式）
@outer:middle:inner://resource
// 带查询参数的引用
@file://document.md?section=intro&format=html
无效示例
// 缺少协议名称
@://document.txt
// 错误原因: 必须指定协议名称
// 缺少资源路径
@file://
// 错误原因: 必须提供资源路径
// 非法字符在路径中
@file://doc<ument>.txt
// 错误原因: 路径包含非法字符
// 查询参数格式错误
@file://code.py?lines:10-20
// 错误原因: 查询参数应使用=赋值
💡 最佳实践
- 使用最合适的协议名称表示资源类型，提高语义明确性
- 嵌套引用时，如果清晰度很重要，使用完整形式（带内部@符号）
- 如果简洁性更重要，则使用简写形式（省略内部@符号）
- 保持资源路径的相对引用，以提高提示词的可移植性
- 合理使用通配符，避免过于宽泛的匹配模式
- 使用查询参数进行资源过滤，而不是在提示词中手动处理
- 避免过深的嵌套引用，保持可读性
常见问题
Q: 资源引用是否支持通配符?
A: 是的，协议支持*（单层匹配）、**（多层匹配）和*.ext（特定扩展名匹配）等通配符模式
Q: 如何引用资源的特定部分?
A: 使用查询参数来指定资源的特定部分，如@file://document.md?section=introduction
Q: 如何处理多种文件扩展名的通配符?
A: 可以使用花括号表示多选项，如@file://src/*.{js,ts,jsx}匹配多种扩展名
Q: 嵌套引用有深度限制吗?
A: 为了保持可读性，建议嵌套深度不超过3层，虽然语法上没有严格限制
Q: 嵌套引用中的URI如何处理?
A: 在嵌套引用中，内层URI会被完整处理后传递给外层协议，如@outer:http://example.com中，http协议的结果会传递给outer协议处理