更新资源协议文档,新增registry子标签的定义与示例,明确资源注册与抽象引用机制,提升文档的清晰度和实用性。同时,删除不再使用的执行流程部分,优化文档结构。
This commit is contained in:
48
core/execution/deal-at-reference.execution.md
Normal file
48
core/execution/deal-at-reference.execution.md
Normal file
@ -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>
|
||||||
19
core/resource/execution.resource.md
Normal file
19
core/resource/execution.resource.md
Normal file
@ -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>
|
||||||
16
core/resource/thought.resource.md
Normal file
16
core/resource/thought.resource.md
Normal file
@ -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>
|
||||||
@ -1,50 +1,5 @@
|
|||||||
<role>
|
<role>
|
||||||
<execution>
|
|
||||||
<process>
|
|
||||||
# 资源处理流程
|
|
||||||
|
|
||||||
```mermaid
|
<personality>
|
||||||
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>
|
|
||||||
</role>
|
</role>
|
||||||
@ -31,10 +31,11 @@ PromptX默认支持以下通用且已有共识的协议,这些协议符合`@
|
|||||||
(* EBNF形式化定义 *)
|
(* EBNF形式化定义 *)
|
||||||
resource_element ::= '<resource' ' protocol="' protocol_name '"' '>' content '</resource>'
|
resource_element ::= '<resource' ' protocol="' protocol_name '"' '>' content '</resource>'
|
||||||
protocol_name ::= [a-zA-Z][a-zA-Z0-9_-]*
|
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>'
|
location_element ::= '<location>' markdown_content '</location>'
|
||||||
params_element ::= '<params>' markdown_content '</params>'
|
params_element ::= '<params>' markdown_content '</params>'
|
||||||
|
registry_element ::= '<registry>' markdown_content '</registry>'
|
||||||
|
|
||||||
markdown_content ::= (* 任何有效的Markdown文本,包括代码块、表格等 *)
|
markdown_content ::= (* 任何有效的Markdown文本,包括代码块、表格等 *)
|
||||||
```
|
```
|
||||||
@ -43,12 +44,13 @@ markdown_content ::= (* 任何有效的Markdown文本,包括代码块、表格
|
|||||||
|
|
||||||
### 子标签语义
|
### 子标签语义
|
||||||
|
|
||||||
resource标签包含两个核心子标签,用于定义资源协议的具体内容:
|
resource标签包含三个核心子标签,用于定义资源协议的具体内容:
|
||||||
|
|
||||||
- **location**:定义该资源协议的路径规则。通常采用EBNF形式化语法描述路径结构,并可包含示例说明。
|
- **location**:定义该资源协议的路径规则。通常采用EBNF形式化语法描述路径结构,并可包含示例说明。
|
||||||
- **params**:定义该资源协议支持的查询参数。通常采用表格形式列出参数名称、类型、描述和用法示例。
|
- **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行
|
- `@file://document.md?line=5-10` - 只获取文件的第5-10行
|
||||||
- `@http://api.example.com/data?format=json&cache=false` - 指定返回格式并禁用缓存
|
- `@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. 资源引用解析从左至右进行,先识别协议名称,再解析资源位置和查询参数
|
1. 资源引用解析从左至右进行,先识别协议名称,再解析资源位置和查询参数
|
||||||
@ -147,7 +179,8 @@ query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value}
|
|||||||
2. **立即加载义务**: 特别是对于@!前缀资源,AI必须立即执行工具调用获取内容
|
2. **立即加载义务**: 特别是对于@!前缀资源,AI必须立即执行工具调用获取内容
|
||||||
3. **自主判断懒加载**: 对于@?前缀资源,AI应记录位置但暂不加载,直到实际需要使用时
|
3. **自主判断懒加载**: 对于@?前缀资源,AI应记录位置但暂不加载,直到实际需要使用时
|
||||||
4. **加载验证**: AI应验证资源是否成功加载,并适当处理加载失败情况
|
4. **加载验证**: AI应验证资源是否成功加载,并适当处理加载失败情况
|
||||||
|
5. **注册表解析**: 对于使用`registry`注册的资源引用,AI应首先解析资源ID,找到对应的实际资源路径,然后再应用上述规则获取资源
|
||||||
|
|
||||||
这种主动获取模式确保AI能正确执行协议定义的资源加载语义,而不依赖系统层面的自动处理。
|
这种主动获取模式确保AI能正确执行协议定义的资源加载语义,而不依赖系统层面的自动处理。registry机制则提供了资源引用的抽象层,使资源组织更加灵活和模块化。
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user