更新资源协议文档，新增registry子标签的定义与示例，明确资源注册与抽象引用机制，提升文档的清晰度和实用性。同时，删除不再使用的执行流程部分，优化文档结构。

2025-05-19 22:42:09 +08:00
parent e7aa2c7a60
commit 9bc0af574f
5 changed files with 123 additions and 52 deletions
--- a/core/execution/deal-at-reference.execution.md
+++ b/core/execution/deal-at-reference.execution.md
@ -0,0 +1,48 @@
+<execution>
+  <process>
+    # 资源处理流程
+    
+    ```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
+    ```
+  </process>
+  
+  <rule>
+    1. AI必须主动使用工具调用获取资源，不等待系统自动加载
+    2. 遇到@!前缀资源必须立即执行工具调用获取内容
+    3. 遇到@?前缀资源应记录位置但暂不加载
+    4. 必须验证资源是否成功加载并处理失败情况
+  </rule>
+  
+  <constraint>
+    1. 工具调用能力限制（不同AI系统支持的工具不同）
+    2. 资源访问权限限制
+    3. 资源大小和格式限制
+  </constraint>
+  
+  <guideline>
+    1. 优先处理关键资源，确保核心功能不受资源加载问题影响
+    2. 资源内容应适当缓存，避免重复加载
+    3. 大型资源考虑分段加载以优化性能
+  </guideline>
+  
+  <criteria>
+    | 指标 | 通过标准 | 不通过标准 |
+    |------|---------|-----------|
+    | 加载及时性 | @!资源被立即加载 | 忽略加载语义前缀 |
+    | 错误处理 | 妥善处理加载失败 | 加载失败无响应 |
+    | 懒加载执行 | @?资源仅在需要时加载 | 过早加载或完全不加载 |
+    | 完整性 | 资源内容完整获取 | 内容截断或损坏 |
+  </criteria>
+</execution>
--- a/core/resource/execution.resource.md
+++ b/core/resource/execution.resource.md
@ -0,0 +1,19 @@
+
+
+<resource protocol="execution">
+  <location>
+    执行模式资源位置使用以下格式:
+    
+    ```ebnf
+    location ::= execution://{execution_id}
+    execution_id ::= [a-zA-Z][a-zA-Z0-9_-]*
+    ```
+  </location>
+  
+  <registry>
+    <!-- 执行模式ID到文件路径的映射表 -->
+    | 执行ID | 文件路径 |
+    |--------|---------|
+    | deal-at-reference | @file://PromptX/core/execution/deal-at-reference.execution.md |
+  </registry>
+</resource> 
--- a/core/resource/thought.resource.md
+++ b/core/resource/thought.resource.md
@ -0,0 +1,16 @@
+<resource protocol="thought">
+  <location>
+    思维模式资源位置使用以下格式:
+    
+    ```ebnf
+    location ::= thought://{thought_id}
+    thought_id ::= [a-zA-Z][a-zA-Z0-9_-]*
+    ```
+  </location>
+  
+  <registry>
+    <!-- 思维模式ID到文件路径的映射表 -->
+    | 思维ID | 文件路径 |
+    |--------|---------|
+  </registry>
+</resource> 
--- a/domain/test/test.role.md
+++ b/domain/test/test.role.md
@ -1,50 +1,5 @@
 <role>
-<execution>
-  <process>
-    # 资源处理流程
-    
-    ```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
-    ```
-  </process>
-  
-  <rule>
-    1. AI必须主动使用工具调用获取资源，不等待系统自动加载
-    2. 遇到@!前缀资源必须立即执行工具调用获取内容
-    3. 遇到@?前缀资源应记录位置但暂不加载
-    4. 必须验证资源是否成功加载并处理失败情况
-  </rule>
-  
-  <constraint>
-    1. 工具调用能力限制（不同AI系统支持的工具不同）
-    2. 资源访问权限限制
-    3. 资源大小和格式限制
-  </constraint>
-  
-  <guideline>
-    1. 优先处理关键资源，确保核心功能不受资源加载问题影响
-    2. 资源内容应适当缓存，避免重复加载
-    3. 大型资源考虑分段加载以优化性能
-  </guideline>
-  
-  <criteria>
-    | 指标 | 通过标准 | 不通过标准 |
-    |------|---------|-----------|
-    | 加载及时性 | @!资源被立即加载 | 忽略加载语义前缀 |
-    | 错误处理 | 妥善处理加载失败 | 加载失败无响应 |
-    | 懒加载执行 | @?资源仅在需要时加载 | 过早加载或完全不加载 |
-    | 完整性 | 资源内容完整获取 | 内容截断或损坏 |
-  </criteria>
-</execution>
+
+<personality>
+
 </role>
--- a/protocol/tag/resource.tag.md
+++ b/protocol/tag/resource.tag.md
@ -31,10 +31,11 @@ PromptX默认支持以下通用且已有共识的协议，这些协议符合`@
 (* 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)+
+content ::= (markdown_content | location_element | params_element | registry_element)+

 location_element ::= '<location>' markdown_content '</location>'
 params_element ::= '<params>' markdown_content '</params>'
+registry_element ::= '<registry>' markdown_content '</registry>'

 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
+<resource protocol="thought">
+  <location>
+    location ::= thought://{thought_id}
+    thought_id ::= [a-zA-Z][a-zA-Z0-9_-]*
+  </location>
+  
+  <registry>
+    | 思维ID | 文件路径 |
+    |--------|---------|
+    | analytical | @file://PromptX/core/thoughts/analytical.thought.md |
+    | creative | @file://PromptX/core/thoughts/creative.thought.md |
+  </registry>
+</resource>
+```
+
+使用时可以简单引用：
+- `@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机制则提供了资源引用的抽象层，使资源组织更加灵活和模块化。