iriver/PromptX
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

修正context协议中的拼写错误，将“executing”更正为“execution”；删除不再使用的execution、resource、thought和protocol模板文档。

Browse Source
This commit is contained in:
sean
2025-05-16 11:00:27 +08:00
parent c07e598c05
commit a8e85761a2
7 changed files with 225 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
protocol/base/execution.protocol.md Normal file
View File

@ -0,0 +1,225 @@
# execution 应用协议
> **TL;DR:** execution标签用于定义结构化的执行框架，帮助AI系统完成任务，包含流程(Process)、指导原则(Guideline)、强制规则(Rule)、约束条件(Constraint)和评价标准(Criteria)五个核心子概念。
## 🔍 基本信息
**标签名:** `<execution>`
**版本:** 1.0.0
**类别:** 执行
**状态:** 草稿
**创建日期:** 2023-06-21
### 目的与功能
execution标签定义了AI系统执行任务的完整框架，它的主要功能是：
- 提供执行任务的结构化定义
- 明确执行的流程步骤、指导原则、规则、约束和评价标准
- 帮助AI系统进行精确、可靠的任务执行
- 提供执行状态追踪和错误处理机制
## 📝 语法定义
```ebnf
(* EBNF形式化定义 *)
execution_element ::= '<execution' attributes? '>' content '</execution>'
attributes ::= (' ' attribute)+ | ''
attribute ::= name '="' value '"'
name ::= [a-zA-Z][a-zA-Z0-9_-]*
value ::= [^"]*
content ::= (markdown_content | process_element | guideline_element | rule_element | constraint_element | criteria_element)+
process_element ::= '<process' attributes? '>' markdown_content '</process>'
guideline_element ::= '<guideline' attributes? '>' markdown_content '</guideline>'
rule_element ::= '<rule' attributes? '>' markdown_content '</rule>'
constraint_element ::= '<constraint' attributes? '>' markdown_content '</constraint>'
criteria_element ::= '<criteria' attributes? '>' markdown_content '</criteria>'
markdown_content ::= (* 任何有效的Markdown文本，可包含特定语法元素 *)
```
## 🧩 语义说明
execution标签表示一个完整的执行框架。标签内容可以包含五种不同概念的子标签，每个子标签都有明确的语义：
- **process**: 表示执行的具体步骤，包含正常和异常路径，是执行的核心路径定义
- **guideline**: 表示建议性指导原则，具有灵活性和可变通性，用于推荐最佳实践
- **rule**: 表示强制性行为准则，必须严格遵守，通常涉及安全、合规或核心质量要求
- **constraint**: 表示客观限制条件，客观存在且不可改变，需要被动适应
- **criteria**: 表示评价标准，用于判断执行结果是否满足要求
这五个子概念构成了完整的执行框架，从不同维度定义了AI系统如何执行任务。
## 💡 最佳实践
以下是使用execution标签的一些建议做法，这些并非强制要求，仅作为参考：
### 优先级关系
execution框架内的子概念具有内在的优先级关系：
1. **Constraint(约束)** - 最高优先级，不可违反
2. **Rule(规则)** - 次高优先级，必须遵循
3. **Guideline(指导原则)** - 较低优先级，推荐遵循但可灵活调整
4. **Process(流程)** - 定义执行路径，需在约束、规则框架内实施
5. **Criteria(标准)** - 评价依据，用于验证执行结果
在设计执行框架时，应遵循此优先级关系，确保低优先级元素不与高优先级元素冲突。
### 表达原则
各子概念推荐使用不同的表达方式：
#### process - 适合使用图形表达
流程是最适合使用图形表达的元素，推荐使用流程图或时序图：
```mermaid
flowchart TD
A[开始] --> B{条件判断}
B -->|条件成立| C[执行步骤1]
B -->|条件不成立| D[执行步骤2]
C --> E[下一步]
D --> E
E --> F[结束]
```
#### guideline - 适合使用列表表达
建议性指导原则适合使用有序或无序列表，突出推荐性质：
```
- 提供用户友好的错误信息
- 对敏感操作进行二次确认
- 使用渐进式信息收集方式
```
#### rule - 适合使用编号列表表达
强制性规则适合使用编号列表，突出其必须遵守的性质：
```
1. 密码必须包含大小写字母、数字和特殊字符
2. 敏感数据传输必须使用加密通道
3. 用户操作必须记录审计日志
```
#### constraint - 适合使用分类列表表达
约束条件适合使用分类列表，按约束类型组织：
```
技术约束：
- 服务器内存限制: 16GB
- 数据库连接数上限: 100
业务约束：
- 用户年龄限制: >13岁
- 服务区域限制: 指定国家/地区
```
#### criteria - 适合使用表格表达
评价标准最适合使用表格，清晰展示指标和目标值：
```
| 指标 | 目标值 | 最低要求 |
|-----|-------|---------|
| 响应时间 | <200ms | <500ms |
| 成功率 | >99% | >95% |
| 用户满意度 | >4.5/5 | >4/5 |
```
## 📋 使用示例
<execution domain="web" context="server">
<process>
# 用户注册流程
```mermaid
flowchart TD
A[开始] --> B[验证输入]
B --> C{输入有效?}
C -->|是| D[检查用户是否存在]
C -->|否| E[返回错误信息]
D --> F{用户存在?}
F -->|是| G[返回用户已存在]
F -->|否| H[创建用户]
H --> I[发送确认邮件]
I --> J[结束]
E --> J
G --> J
```
## 异常处理路径
1. 数据库连接失败：重试3次，仍失败则返回系统错误
2. 邮件服务不可用：将邮件加入队列，返回部分成功信息
3. 输入验证失败：返回具体的字段错误信息
</process>
<guideline>
# 用户体验建议
```mermaid
mindmap
root((注册体验))
表单设计
字段顺序从简单到复杂
实时字段验证
进度指示器
错误提示
友好明确的错误信息
提供修正建议
流程优化
最少必填字段
分步注册可选
```
- 使用渐进式表单，先收集必要信息，成功后再补充其他信息
- 提供社交媒体快捷注册选项
- 密码强度视觉指示器
</guideline>
<rule>
# 必须遵循的规则
1. 密码必须至少8个字符，包含大小写字母、数字和特殊字符
2. 用户邮箱必须通过验证才能激活账户
3. 敏感个人信息必须加密存储
4. 用户协议必须显式接受
5. IP地址和注册时间必须记录日志
</rule>
<constraint>
# 系统限制条件
```mermaid
graph TD
A[技术约束] --> B[数据库连接池上限: 100]
A --> C[API调用频率: 10次/秒]
D[业务约束] --> E[注册用户年龄: >13岁]
D --> F[服务区域: 指定国家/地区]
```
- 存储空间限制：用户头像最大2MB
- 处理时间约束：注册流程必须在3秒内完成
- 并发限制：同一IP每分钟最多5次注册请求
</constraint>
<criteria>
# 成功标准
| 指标 | 目标值 | 最低要求 |
|-----|-------|---------|
| 注册成功率 | >95% | >90% |
| 平均完成时间 | <60秒 | <90秒 |
| 邮箱验证率 | >80% | >70% |
| 表单放弃率 | <20% | <30% |
## 质量检查点
1. 所有必填字段已验证
2. 用户记录已正确创建
3. 确认邮件已发送或进入队列
4. 欢迎信息已显示
</criteria>
</execution>

224
protocol/base/resource.protocol.md Normal file
View File

@ -0,0 +1,224 @@
# resource 应用协议
> **TL;DR:** resource标签用于定义资源协议，提供统一的资源引用方式，支持通过`@协议名://路径`形式访问各类资源。
## 🔍 基本信息
**标签名:** `<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 ::= '<resource' ' protocol="' protocol_name '"' '>' content '</resource>'
protocol_name ::= [a-zA-Z][a-zA-Z0-9_-]*
content ::= (markdown_content | location_element | params_element)+
location_element ::= '<location>' markdown_content '</location>'
params_element ::= '<params>' markdown_content '</params>'
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&param2=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**: 使用表格形式列出参数，清晰展示名称、类型、描述和示例
## 📋 使用示例
### 自定义协议示例
以下示例展示了如何定义自定义资源协议：
<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>

270
protocol/base/thought.protocol.md Normal file
View File

@ -0,0 +1,270 @@
# thought 应用协议
> **TL;DR:** thought标签用于定义结构化的思考框架，帮助AI系统进行系统性分析和推理，支持四种思维模式：横向探索(exploration)、纵向推理(reasoning)、流程计划(plan)和批判挑战(challenge)。
## 🔍 基本信息
**标签名:** `<thought>`
**版本:** 1.0.0
**类别:** 思考
**状态:** 草稿
**创建日期:** 2023-06-20
### 目的与功能
thought标签定义了AI系统进行思考分析的框架和流程，它的主要功能是：
- 提供结构化的思维分析模式
- 组织和展示概念关系与逻辑推理
- 支持可视化思维导图和决策树
- 帮助AI系统进行系统性、全面性的问题分析
- 区分不同类型的思维模式：探索、推理、计划和挑战
## 📝 语法定义
```ebnf
(* EBNF形式化定义 *)
thought_element ::= '<thought' attributes? '>' content '</thought>'
attributes ::= (' ' attribute)+ | ''
attribute ::= name '="' value '"'
name ::= [a-zA-Z][a-zA-Z0-9_-]*
value ::= [^"]*
content ::= (markdown_content | exploration_element | reasoning_element | plan_element | challenge_element)+
markdown_content ::= (* 任何有效的Markdown文本，包括Mermaid图表 *)
exploration_element ::= '<exploration' attributes? '>' markdown_content '</exploration>'
reasoning_element ::= '<reasoning' attributes? '>' markdown_content '</reasoning>'
plan_element ::= '<plan' attributes? '>' markdown_content '</plan>'
challenge_element ::= '<challenge' attributes? '>' markdown_content '</challenge>'
```
## 🧩 语义说明
thought标签表示一个完整的思考过程或思维框架。标签内容可以包含四种不同思维模式的子标签，或直接使用Markdown格式表达思考内容。
子标签具有明确的语义：
- **exploration**: 表示跳跃思考，发散性思维，生成可能性，寻找多种可能性、创新点和关联性
- **reasoning**: 表示连续思考，收敛性思维，验证可能性，深入分析因果关系、逻辑链条
- **plan**: 表示秩序思考，结构性思维，固化可能性，设计行动步骤、决策路径、组织结构、系统架构
- **challenge**: 表示逆向跳跃思考，批判性思维，质疑可能性，寻找假设漏洞、识别潜在风险、测试极限条件
exploration和challenge是一对思维模式的正反两面：exploration向外发散寻找"可能是什么"，而challenge向内批判探究"可能不是什么"。二者都采用跳跃式思考，但方向相反。reasoning负责系统验证，而challenge主要提出问题点。
thought标签特别适合表达概念关系、逻辑推理和系统性思考，为AI提供思考分析的参考框架。
## 💡 最佳实践
以下是使用thought标签的一些建议做法，这些并非强制要求，仅作为参考：
### 图形化表达原则
thought标签内应以图形为主要表达方式，辅以简洁文字说明。这样做的优势：
- 思维结构直观可见
- 关系与逻辑一目了然
- 跨语言理解更容易
- 思维模式界限更清晰
### 各子标签推荐图形
每种思维模式都有最适合的图形表达方式：
#### exploration - 思维导图
用于表达横向思维和概念发散，简单文字仅需说明核心问题和主要分支。
```mermaid
mindmap
root((核心问题))
可能性A
子可能性A1
子可能性A2
可能性B
子可能性B1
可能性C
```
#### reasoning - 推理图
用于表达纵向思维和逻辑推导，文字说明只需点明前提和结论间的关系。
```mermaid
graph TD
A[前提] --> B[中间命题1]
A --> C[中间命题2]
B --> D[结论1]
C --> E[结论2]
```
#### plan - 流程图
用于表达计划思维和决策路径，文字仅需标注关键决策点和行动步骤。
```mermaid
flowchart TD
A[起点] --> B{判断条件}
B -->|条件成立| C[执行步骤1]
B -->|条件不成立| D[执行步骤2]
C --> E[结果1]
D --> F[结果2]
```
#### challenge - 逆向思维导图
用于表达批判性思维和风险探索，与exploration采用相似的图形表达，但关注的是潜在问题和限制条件。
```mermaid
mindmap
root((方案风险))
技术风险
可扩展性问题
性能瓶颈
实施风险
资源不足
时间限制
业务风险
用户接受度
```
### Mermaid图表分类参考表
下表系统地列出了各种Mermaid图表类型及其适用的思维模式：
| 图表类型 | 思维模式 | 适用场景 | 优势 |
|---------|----------|---------|------|
| 思维导图(mindmap) | Exploration/Challenge | 概念发散、头脑风暴、风险识别 | 展示中心概念及其分支关系 |
| 四象限图(quadrantChart) | Exploration/Challenge | 方案评估、风险分析、优先级划分 | 在两个维度上评估选项或风险 |
| 流程图(flowchart) | Reasoning/Challenge | 逻辑推导、算法思路、决策分析、故障分析 | 清晰表达推理过程中的逻辑关系 |
| 饼图(pie) | Reasoning | 比例分析、相对重要性评估 | 直观展示整体中各部分的占比 |
| 类图(classDiagram) | Plan | 结构设计、概念分类、系统架构 | 展示实体间的层次和组织关系 |
| 甘特图(gantt) | Plan | 项目规划、时间安排、任务依赖 | 展示任务的时间跨度和先后关系 |
| 序列图(sequenceDiagram) | Plan | 交互设计、通信计划、协作过程 | 清晰展示实体间的消息传递和时序 |
| 状态图(stateDiagram) | Plan | 状态管理、过程转换、行为模式 | 展示系统状态和触发转换的事件 |
| 实体关系图(erDiagram) | Plan | 数据结构设计、系统建模 | 展示实体间的关系和属性 |
| 时间线(timeline) | Reasoning | 历史分析、演变过程、发展轨迹 | 按时间顺序展示事件发展 |
| 用户旅程图(journey) | Plan | 体验设计、流程优化、情感映射 | 展示用户交互过程和体验变化 |
选择合适的图表类型能大幅提高思维表达的清晰度和直观性，建议根据具体思维模式和内容特点从上表中选择最佳匹配的图表类型。
## 📋 使用示例
<thought domain="software" focus="performance">
<exploration>
# 性能优化方向探索
```mermaid
mindmap
root((性能优化))
算法优化
时间复杂度
空间复杂度
数据结构
查询效率
内存占用
并发处理
线程模型
资源锁定
缓存策略
本地缓存
分布式缓存
```
</exploration>
<reasoning>
# 性能瓶颈分析
```mermaid
flowchart TD
A[高延迟问题] --> B{数据库查询?}
B -->|是| C[查询优化]
B -->|否| D{网络延迟?}
D -->|是| E[网络优化]
D -->|否| F[应用逻辑]
C --> G[索引优化]
C --> H[SQL重构]
E --> I[协议优化]
E --> J[连接池化]
F --> K[算法优化]
F --> L[缓存引入]
```
```mermaid
pie
title 延迟占比分析
"数据库查询" : 65
"网络传输" : 20
"应用逻辑" : 15
```
</reasoning>
<plan>
# 优化实施计划
```mermaid
gantt
title 性能优化项目计划
dateFormat YYYY-MM-DD
section 数据库优化
索引重建 :a1, 2023-06-01, 3d
查询重构 :a2, after a1, 5d
section 应用优化
缓存实现 :a3, 2023-06-01, 4d
算法优化 :a4, after a3, 7d
section 网络优化
连接池化 :a5, 2023-06-08, 2d
测试验证 :a6, after a2 a4 a5, 3d
```
```mermaid
sequenceDiagram
客户端->>缓存层: 数据请求
缓存层->>缓存层: 检查缓存
alt 缓存命中
缓存层-->>客户端: 返回缓存数据
else 缓存未命中
缓存层->>数据库: 查询数据
数据库-->>缓存层: 返回结果
缓存层->>缓存层: 更新缓存
缓存层-->>客户端: 返回数据
end
```
</plan>
<challenge>
# 方案风险评估
```mermaid
mindmap
root((性能优化风险))
缓存相关
一致性问题
内存溢出
数据库相关
连接耗尽
索引失效
查询超时
并发相关
死锁风险
资源争用
网络相关
超时问题
带宽限制
```
```mermaid
flowchart TD
A[缓存方案失效] --> B{原因分析}
B -->|高负载| C[连接池耗尽]
B -->|数据一致性| D[缓存过期策略问题]
B -->|极端情况| E[内存不足]
C --> F[增加连接上限]
D --> G[实施两阶段提交]
E --> H[添加内存监控和自动扩容]
I[查询优化失效] --> J{可能原因}
J -->|数据倾斜| K[分区优化]
J -->|索引失效| L[强制索引]
```
</challenge>
</thought>