diff --git a/protocol/application/context.protocol.md b/protocol/application/context.protocol.md index 37b07e2..afd2919 100644 --- a/protocol/application/context.protocol.md +++ b/protocol/application/context.protocol.md @@ -29,7 +29,7 @@ text ::= (* 任何文本内容,用于简要描述上下文 *) ## 🧩 语义说明 -context标签用于在提示词中定义上下文信息。采用简洁的HTML风格属性标记方式,通过id指定唯一标识符,通过class指定分类,标签内容直接描述该上下文的含义。它作为CAP模式的具体实现,为AI系统提供了清晰简洁的上下文定义能力。实际的上下文感知执行逻辑由executing协议负责实现。 +context标签用于在提示词中定义上下文信息。采用简洁的HTML风格属性标记方式,通过id指定唯一标识符,通过class指定分类,标签内容直接描述该上下文的含义。它作为CAP模式的具体实现,为AI系统提供了清晰简洁的上下文定义能力。实际的上下文感知执行逻辑由execution协议负责实现。 ## 💡 最佳实践 diff --git a/protocol/application/resource.protocol.md b/protocol/application/resource.protocol.md deleted file mode 100644 index 2106d22..0000000 --- a/protocol/application/resource.protocol.md +++ /dev/null @@ -1,37 +0,0 @@ -# resource 应用协议 - -> **TL;DR:** resource标签用于定义资源协议,提供统一的引用方式。 - -## 🔍 基本信息 - -**标签名:** `` -**版本:** 1.0.0 -**类别:** 资源 -**状态:** 草稿 -**创建日期:** 2023-06-30 - -### 目的与功能 - -resource标签用于定义特定类型的资源协议,使开发者能够以标准化的方式描述如何引用和处理各种资源。通过这个标签,可以明确资源的引用语法、处理规则和使用方式,确保资源引用在不同环境中的一致性和可靠性。此标签是PromptX中资源引用协议(RP)在应用层面的具体实现方式。 - -## 📝 语法定义 - -``` -内容 -``` - -## 📝 语义说明 - -resource标签定义资源协议,使其可以使用`@协议名://路径`形式在提示词中引用。标签内容应包含协议的基本描述和用法。 - -## 使用示例 - - -# Context 协议 - -## 语法 -@context://[scope]/[path] - -## 说明 -用于引用和设置上下文环境。 - \ No newline at end of file diff --git a/protocol/application/execution.protocol.md b/protocol/base/execution.protocol.md similarity index 100% rename from protocol/application/execution.protocol.md rename to protocol/base/execution.protocol.md diff --git a/protocol/base/resource.protocol.md b/protocol/base/resource.protocol.md new file mode 100644 index 0000000..15803e9 --- /dev/null +++ b/protocol/base/resource.protocol.md @@ -0,0 +1,224 @@ +# resource 应用协议 + +> **TL;DR:** 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 +(* EBNF形式化定义 *) +resource_element ::= '' content '' +protocol_name ::= [a-zA-Z][a-zA-Z0-9_-]* +content ::= (markdown_content | location_element | params_element)+ + +location_element ::= '' markdown_content '' +params_element ::= '' markdown_content '' + +markdown_content ::= (* 任何有效的Markdown文本,包括代码块、表格等 *) +``` + +## 🧩 语义说明 + +resource标签定义了一个资源协议,指定了如何使用`@协议名://路径`的形式引用和访问特定类型的资源。 + +标签包含的主要子元素及其语义: + +- **protocol属性**:定义资源协议的名称,如`file`、`http`、`context`等 +- **location子标签**:定义资源路径的格式和规则,指定如何定位资源 +- **params子标签**:定义资源支持的查询参数,指定如何处理资源的特定部分或格式 + +### 资源引用语法 + +资源引用使用`@`符号作为统一入口,遵循以下核心语法规则: + +```ebnf +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` - 指定返回格式并禁用缓存 + +### 解析规则 + +1. 资源引用解析从左至右进行,先识别协议名称,再解析资源位置和查询参数 +2. 嵌套引用从内向外解析,内层资源引用的结果作为外层引用的输入 +3. 查询参数应用于资源加载后的处理阶段,不影响资源的基本定位 +4. 相对路径解析基于当前上下文的工作目录或基础路径 + +## 💡 最佳实践 + +以下是使用resource标签的一些推荐做法: + +### 资源路径设计 + +资源路径设计应遵循以下原则: +- 使用直观、符合惯例的路径格式 +- 支持绝对路径和相对路径 +- 适当使用通配符增强灵活性 +- 路径分隔符应统一使用`/` + +### 查询参数设计 + +查询参数设计应考虑以下因素: +- 参数名称应清晰表达其功能 +- 参数值格式应明确定义 +- 常见操作应有对应的参数支持(如范围指定、格式转换等) +- 参数组合应有明确的优先级规则 + +### 资源引用最佳实践 + +1. 使用最合适的协议名称表示资源类型,提高语义明确性 +2. 嵌套引用时,如果清晰度很重要,使用完整形式(带内部@符号) +3. 如果简洁性更重要,则使用简写形式(省略内部@符号) +4. 保持资源路径的相对引用,以提高提示词的可移植性 +5. 合理使用通配符,避免过于宽泛的匹配模式 +6. 使用查询参数进行资源过滤,而不是在提示词中手动处理 +7. 避免过深的嵌套引用,建议不超过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) + + ```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 | + + \ No newline at end of file diff --git a/protocol/application/thought.protocol.md b/protocol/base/thought.protocol.md similarity index 100% rename from protocol/application/thought.protocol.md rename to protocol/base/thought.protocol.md diff --git a/protocol/application/protocol-application-template.md b/protocol/template/protocol-application-template.md similarity index 100% rename from protocol/application/protocol-application-template.md rename to protocol/template/protocol-application-template.md diff --git a/protocol/pattern/protocol-pattern-template.md b/protocol/template/protocol-pattern-template.md similarity index 100% rename from protocol/pattern/protocol-pattern-template.md rename to protocol/template/protocol-pattern-template.md