diff --git a/core/execution/deal-at-reference.execution.md b/core/execution/deal-at-reference.execution.md new file mode 100644 index 0000000..08c480e --- /dev/null +++ b/core/execution/deal-at-reference.execution.md @@ -0,0 +1,48 @@ + + + # 资源处理流程 + + ```mermaid + flowchart TD + A[识别资源引用] --> B{判断加载语义} + B -->|@!前缀| C[立即执行工具调用] + B -->|@?前缀| D[记录位置暂不加载] + B -->|@默认| E[根据上下文决定] + C --> F[验证加载结果] + E --> F + F -->|成功| G[处理资源内容] + F -->|失败| H[执行失败处理] + D --> I[等待使用触发] + I --> J[需要使用时加载] + J --> F + ``` + + + + 1. AI必须主动使用工具调用获取资源，不等待系统自动加载 + 2. 遇到@!前缀资源必须立即执行工具调用获取内容 + 3. 遇到@?前缀资源应记录位置但暂不加载 + 4. 必须验证资源是否成功加载并处理失败情况 + + + + 1. 工具调用能力限制（不同AI系统支持的工具不同） + 2. 资源访问权限限制 + 3. 资源大小和格式限制 + + + + 1. 优先处理关键资源，确保核心功能不受资源加载问题影响 + 2. 资源内容应适当缓存，避免重复加载 + 3. 大型资源考虑分段加载以优化性能 + + + + | 指标 | 通过标准 | 不通过标准 | + |------|---------|-----------| + | 加载及时性 | @!资源被立即加载 | 忽略加载语义前缀 | + | 错误处理 | 妥善处理加载失败 | 加载失败无响应 | + | 懒加载执行 | @?资源仅在需要时加载 | 过早加载或完全不加载 | + | 完整性 | 资源内容完整获取 | 内容截断或损坏 | + + \ No newline at end of file diff --git a/core/resource/execution.resource.md b/core/resource/execution.resource.md new file mode 100644 index 0000000..6ee89ab --- /dev/null +++ b/core/resource/execution.resource.md @@ -0,0 +1,19 @@ + + + + + 执行模式资源位置使用以下格式: + + ```ebnf + location ::= execution://{execution_id} + execution_id ::= [a-zA-Z][a-zA-Z0-9_-]* + ``` + + + + + | 执行ID | 文件路径 | + |--------|---------| + | deal-at-reference | @file://PromptX/core/execution/deal-at-reference.execution.md | + + \ No newline at end of file diff --git a/core/resource/thought.resource.md b/core/resource/thought.resource.md new file mode 100644 index 0000000..b20ab1e --- /dev/null +++ b/core/resource/thought.resource.md @@ -0,0 +1,16 @@ + + + 思维模式资源位置使用以下格式: + + ```ebnf + location ::= thought://{thought_id} + thought_id ::= [a-zA-Z][a-zA-Z0-9_-]* + ``` + + + + + | 思维ID | 文件路径 | + |--------|---------| + + \ No newline at end of file diff --git a/domain/test/test.role.md b/domain/test/test.role.md index c91aab5..b297ce6 100644 --- a/domain/test/test.role.md +++ b/domain/test/test.role.md @@ -1,50 +1,5 @@ - - - # 资源处理流程 - - ```mermaid - flowchart TD - A[识别资源引用] --> B{判断加载语义} - B -->|@!前缀| C[立即执行工具调用] - B -->|@?前缀| D[记录位置暂不加载] - B -->|@默认| E[根据上下文决定] - C --> F[验证加载结果] - E --> F - F -->|成功| G[处理资源内容] - F -->|失败| H[执行失败处理] - D --> I[等待使用触发] - I --> J[需要使用时加载] - J --> F - ``` - - - - 1. AI必须主动使用工具调用获取资源，不等待系统自动加载 - 2. 遇到@!前缀资源必须立即执行工具调用获取内容 - 3. 遇到@?前缀资源应记录位置但暂不加载 - 4. 必须验证资源是否成功加载并处理失败情况 - - - - 1. 工具调用能力限制（不同AI系统支持的工具不同） - 2. 资源访问权限限制 - 3. 资源大小和格式限制 - - - - 1. 优先处理关键资源，确保核心功能不受资源加载问题影响 - 2. 资源内容应适当缓存，避免重复加载 - 3. 大型资源考虑分段加载以优化性能 - - - - | 指标 | 通过标准 | 不通过标准 | - |------|---------|-----------| - | 加载及时性 | @!资源被立即加载 | 忽略加载语义前缀 | - | 错误处理 | 妥善处理加载失败 | 加载失败无响应 | - | 懒加载执行 | @?资源仅在需要时加载 | 过早加载或完全不加载 | - | 完整性 | 资源内容完整获取 | 内容截断或损坏 | - - + + + \ No newline at end of file diff --git a/protocol/tag/resource.tag.md b/protocol/tag/resource.tag.md index 69c6106..f9417cd 100644 --- a/protocol/tag/resource.tag.md +++ b/protocol/tag/resource.tag.md @@ -31,10 +31,11 @@ PromptX默认支持以下通用且已有共识的协议，这些协议符合`@ (* EBNF形式化定义 *) resource_element ::= '' content '' protocol_name ::= [a-zA-Z][a-zA-Z0-9_-]* -content ::= (markdown_content | location_element | params_element)+ +content ::= (markdown_content | location_element | params_element | registry_element)+ location_element ::= '' markdown_content '' params_element ::= '' markdown_content '' +registry_element ::= '' markdown_content '' markdown_content ::= (* 任何有效的Markdown文本，包括代码块、表格等 *) ``` @@ -43,12 +44,13 @@ markdown_content ::= (* 任何有效的Markdown文本，包括代码块、表格 ### 子标签语义 -resource标签包含两个核心子标签，用于定义资源协议的具体内容： +resource标签包含三个核心子标签，用于定义资源协议的具体内容： - **location**：定义该资源协议的路径规则。通常采用EBNF形式化语法描述路径结构，并可包含示例说明。 - **params**：定义该资源协议支持的查询参数。通常采用表格形式列出参数名称、类型、描述和用法示例。 +- **registry**：根据location和params定义注册抽象参数与具体资源的映射关系。通常采用表格形式列出ID到实际资源路径的映射。 -location和params子标签共同构成资源协议的完整定义，前者规定了资源的定位方式，后者规定了资源的访问选项。这两部分内容决定了如何解析和处理资源引用。 +这三个子标签共同构成资源协议的完整定义：location定义资源的定位格式，params定义资源的访问选项，registry将抽象ID映射到具体资源路径。标签应按照location、params、registry的顺序定义，确保registry可以基于前两个标签的内容建立正确的映射关系。 ### `@` 引用协议 @@ -132,6 +134,36 @@ query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value} - `@file://document.md?line=5-10` - 只获取文件的第5-10行 - `@http://api.example.com/data?format=json&cache=false` - 指定返回格式并禁用缓存 +#### 资源注册与抽象引用 + +使用registry定义的资源可以通过抽象ID引用，无需知道具体路径： +``` +@protocol://resource_id +``` + +例如定义了以下registry： +```xml + + + location ::= thought://{thought_id} + thought_id ::= [a-zA-Z][a-zA-Z0-9_-]* + + + + | 思维ID | 文件路径 | + |--------|---------| + | analytical | @file://PromptX/core/thoughts/analytical.thought.md | + | creative | @file://PromptX/core/thoughts/creative.thought.md | + + +``` + +使用时可以简单引用： +- `@thought://analytical` - 自动映射到对应文件 +- `@thought://creative` - 自动映射到对应文件 + +这种抽象引用机制提供了路由层，使资源引用与实际存储位置解耦，方便管理和移植。 + ### 解析规则 1. 资源引用解析从左至右进行，先识别协议名称，再解析资源位置和查询参数 @@ -147,7 +179,8 @@ query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value} 2. **立即加载义务**: 特别是对于@!前缀资源，AI必须立即执行工具调用获取内容 3. **自主判断懒加载**: 对于@?前缀资源，AI应记录位置但暂不加载，直到实际需要使用时 4. **加载验证**: AI应验证资源是否成功加载，并适当处理加载失败情况 +5. **注册表解析**: 对于使用`registry`注册的资源引用，AI应首先解析资源ID，找到对应的实际资源路径，然后再应用上述规则获取资源 -这种主动获取模式确保AI能正确执行协议定义的资源加载语义，而不依赖系统层面的自动处理。 +这种主动获取模式确保AI能正确执行协议定义的资源加载语义，而不依赖系统层面的自动处理。registry机制则提供了资源引用的抽象层，使资源组织更加灵活和模块化。