更新resource协议文档,增加子标签语义说明,详细描述location和params子标签的功能与结构,提升文档的清晰度和可读性。同时,删除不再使用的协议模板文件,优化代码库结构。
This commit is contained in:
@ -41,6 +41,18 @@ markdown_content ::= (* 任何有效的Markdown文本,包括代码块、表格
|
||||
|
||||
## 🧩 语义说明
|
||||
|
||||
### 子标签语义
|
||||
|
||||
resource标签包含两个核心子标签,用于定义资源协议的具体内容:
|
||||
|
||||
- **location**:定义该资源协议的路径规则。通常采用EBNF形式化语法描述路径结构,并可包含示例说明。
|
||||
- **params**:定义该资源协议支持的查询参数。通常采用表格形式列出参数名称、类型、描述和用法示例。
|
||||
|
||||
location和params子标签共同构成资源协议的完整定义,前者规定了资源的定位方式,后者规定了资源的访问选项。这两部分内容决定了如何解析和处理资源引用。
|
||||
|
||||
### `@` 引用协议
|
||||
|
||||
|
||||
resource标签定义了一个资源协议,指定了如何使用`@`符号作为统一入口,遵循以下核心语法规则:
|
||||
|
||||
```ebnf
|
||||
@ -109,98 +121,4 @@ query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value}
|
||||
3. 查询参数应用于资源加载后的处理阶段,不影响资源的基本定位
|
||||
4. 相对路径解析基于当前上下文的工作目录或基础路径
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
以下是使用resource标签的一些推荐做法:
|
||||
|
||||
### 资源路径设计
|
||||
|
||||
资源路径设计应遵循以下原则:
|
||||
- 使用直观、符合惯例的路径格式
|
||||
- 支持绝对路径和相对路径
|
||||
- 适当使用通配符增强灵活性
|
||||
- 路径分隔符应统一使用`/`
|
||||
|
||||
### 查询参数设计
|
||||
|
||||
查询参数设计应考虑以下因素:
|
||||
- 参数名称应清晰表达其功能
|
||||
- 参数值格式应明确定义
|
||||
- 常见操作应有对应的参数支持(如范围指定、格式转换等)
|
||||
- 参数组合应有明确的优先级规则
|
||||
|
||||
### 资源引用最佳实践
|
||||
|
||||
1. 使用最合适的协议名称表示资源类型,提高语义明确性
|
||||
2. 嵌套引用时,如果清晰度很重要,使用完整形式(带内部@符号)
|
||||
3. 如果简洁性更重要,则使用简写形式(省略内部@符号)
|
||||
4. 保持资源路径的相对引用,以提高提示词的可移植性
|
||||
5. 合理使用通配符,避免过于宽泛的匹配模式
|
||||
6. 使用查询参数进行资源过滤,而不是在提示词中手动处理
|
||||
7. 避免过深的嵌套引用,建议不超过3层,保持可读性
|
||||
|
||||
### 表达风格推荐
|
||||
|
||||
- **location**: 优先使用EBNF格式正式描述语法规则,辅以简洁示例
|
||||
- **params**: 使用表格形式列出参数,清晰展示名称、类型、描述和示例
|
||||
|
||||
## 📋 使用示例
|
||||
|
||||
### 自定义协议示例
|
||||
|
||||
以下示例展示了如何定义自定义资源协议:
|
||||
|
||||
<resource protocol="memory">
|
||||
<location>
|
||||
# 路径规则 (EBNF)
|
||||
|
||||
```ebnf
|
||||
memory_path ::= [namespace '/'] memory_key
|
||||
namespace ::= (letter | digit | '_' | '-')+
|
||||
memory_key ::= (letter | digit | '_' | '-' | '.')+
|
||||
```
|
||||
|
||||
## 示例
|
||||
- @memory://user_preferences
|
||||
- @memory://session/history
|
||||
- @memory://system/config
|
||||
</location>
|
||||
|
||||
<params>
|
||||
# 查询参数
|
||||
|
||||
| 参数名 | 类型 | 描述 | 示例 |
|
||||
|-------|------|------|------|
|
||||
| ttl | 数字 | 生存时间(秒) | ?ttl=3600 |
|
||||
| default | 字符串 | 默认值 | ?default=empty |
|
||||
| type | 字符串 | 值类型 | ?type=json |
|
||||
</params>
|
||||
</resource>
|
||||
|
||||
<resource protocol="context">
|
||||
<location>
|
||||
# 路径规则 (EBNF)
|
||||
|
||||
```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
|
||||
</location>
|
||||
|
||||
<params>
|
||||
# 查询参数
|
||||
|
||||
| 参数名 | 类型 | 描述 | 示例 |
|
||||
|-------|------|------|------|
|
||||
| mode | 字符串 | 上下文模式 | ?mode=read 或 ?mode=write |
|
||||
| scope | 字符串 | 访问范围 | ?scope=local 或 ?scope=global |
|
||||
| format | 字符串 | 返回格式 | ?format=json |
|
||||
</params>
|
||||
</resource>
|
||||
Reference in New Issue
Block a user