diff --git a/core/common/command-execution.thinking.md b/core/common/command-execution.thinking.md new file mode 100644 index 0000000..787a49f --- /dev/null +++ b/core/common/command-execution.thinking.md @@ -0,0 +1,137 @@ + + +# 命令行执行思维框架 + +## 核心思考维度 + +```mermaid +mindmap + root((命令行执行)) + 命令分析 + 目的理解 + 语法结构 + 预期输出 + 环境评估 + 平台差异 + 上下文状态 + 必要依赖 + 风险考量 + 数据安全 + 权限需求 + 可逆性 + 优化思考 + 效率提升 + 可读性 + 组合优化 + 结果解读 + 成功标志 + 异常分析 + 后续行动 +``` + +## 命令分析思考 + +### 目的理解 +- 这个命令要完成什么任务？ +- 这个命令在当前任务流程中的作用是什么？ +- 有没有更符合意图的替代命令？ + +### 语法结构 +- 命令的基本结构是否正确？ +- 参数使用是否恰当？ +- 是否存在语法优化空间？ + +### 预期输出 +- 预期得到什么样的输出？ +- 如何判断命令执行是否达到预期？ + +## 环境评估思考 + +```mermaid +flowchart TD + A[环境分析] --> B{平台类型?} + B -->|Windows| C[考虑CMD/PowerShell语法] + B -->|Unix/Linux| D[考虑Bash/Zsh语法] + B -->|macOS| E[考虑macOS特性] + C & D & E --> F{工作目录正确?} + F -->|否| G[调整工作目录] + F -->|是| H{依赖检查} + H -->|缺失| I[安装/加载依赖] + H -->|完整| J[环境就绪] + + style A fill:#4da6ff,stroke:#0066cc,color:white + style B fill:#ffa64d,stroke:#cc7a30,color:white + style F fill:#4dbb5f,stroke:#36873f,color:white + style H fill:#d94dbb,stroke:#a3378a,color:white +``` + +### 上下文状态 +- 当前工作目录是否正确？ +- 是否已经满足命令执行的前提条件？ +- 是否需要先设置环境变量？ + +## 风险考量思考 + +### 安全评估表 +| 风险类型 | 问题思考 | 缓解措施 | +|---------|---------|---------| +| 数据安全 | 命令是否会修改或删除重要数据？ | 检查命令范围，提前备份 | +| 权限控制 | 命令是否需要特定权限？ | 验证权限是否最小化 | +| 中断风险 | 命令是否可能造成系统中断？ | 评估执行时间点，准备回滚方案 | +| 可逆性 | 操作是否可逆？ | 设计回滚策略 | + +## 优化思考 + +### 效率提升 +- 能否通过管道组合多个命令？ +- 是否可以使用通配符简化操作？ +- 是否可以通过别名或函数封装常用操作？ + +### 命令优化示例 +``` +# 优化前 +find . -name "*.txt" | xargs grep "pattern" + +# 优化后 +grep -r "pattern" --include="*.txt" . +``` + +## 结果解读思考 + +```mermaid +stateDiagram-v2 + [*] --> 执行命令 + 执行命令 --> 成功: 返回码为0 + 执行命令 --> 失败: 返回码非0 + + 成功 --> 结果分析: 验证输出 + 失败 --> 错误分析: 诊断问题 + + 结果分析 --> 后续行动 + 错误分析 --> 修正策略 + + 修正策略 --> 执行命令: 重试 + 后续行动 --> [*] +``` + +### 异常分析思考 +- 错误信息揭示了什么问题？ +- 是命令本身错误还是环境问题？ +- 有没有常见的解决方案？ + +### 后续行动 +- 基于执行结果，下一步应该做什么？ +- 是否需要保存或处理输出？ +- 是否需要通知用户特定信息？ + +## 决策模型 + +处理命令行任务的决策模型: + +1. **理解** - 深入理解命令目的和上下文 +2. **评估** - 全面评估环境条件和执行风险 +3. **优化** - 思考如何使命令更高效和安全 +4. **执行** - 在适当条件下执行命令 +5. **分析** - 解读结果并决定后续行动 + + diff --git a/core/context/project-root-dir.executing.md b/core/context/project-root-dir.executing.md new file mode 100644 index 0000000..18e39df --- /dev/null +++ b/core/context/project-root-dir.executing.md @@ -0,0 +1,106 @@ + + +# 项目根目录感知执行流程 + +## 感知执行阶段 + +### A级感知（高可靠性） +```mermaid +flowchart TD + A[开始] --> B{检查IDE API} + B -->|可用| C[使用IDE API获取] + B -->|不可用| D[进入B级感知] + C --> E[验证结果] + E -->|通过| F[返回结果] + E -->|失败| D + + style A fill:#4da6ff,stroke:#0066cc,color:white + style B fill:#d94dbb,stroke:#a13b8f,color:white + style C fill:#4dbb5f,stroke:#36873f,color:white + style D fill:#ffa64d,stroke:#cc7a30,color:white + style E fill:#4dbbbb,stroke:#368787,color:white + style F fill:#71ff71,stroke:#3bc23b,color:white +``` + +1. IDE API调用 +```javascript +const rootDir = cursor.getWorkspaceRoot(); +``` + +2. 结果验证 +```bash +[ -d "${ROOT_DIR}" ] && [ -r "${ROOT_DIR}" ] && [ -x "${ROOT_DIR}" ] +``` + +### B级感知（中等可靠性） + +1. 版本控制检测 +```bash +find . -name ".git" -type d -exec dirname {} \; 2>/dev/null | head -n 1 +``` + +2. 包管理文件检测 +```bash +find . \( -name "package.json" -o -name "pom.xml" -o -name "requirements.txt" \) -type f -exec dirname {} \; 2>/dev/null | head -n 1 +``` + +3. 项目配置文件检测 +```bash +find . -name ".projectrc" -type f -exec dirname {} \; 2>/dev/null | head -n 1 +``` + +### C级感知（低可靠性） + +用户交互确认（仅在A、B级方法都失败时使用） +```bash +echo "请确认项目根目录是否为: $PWD [Y/n]" +read confirmation +``` + +## 验证阶段 + +1. 路径存在性验证 +```bash +[ -d "${ROOT_DIR}" ] +``` + +2. 权限验证 +```bash +[ -r "${ROOT_DIR}" ] && [ -x "${ROOT_DIR}" ] +``` + +3. 项目标志验证 +```bash +[ -e "${ROOT_DIR}/.git" ] || [ -e "${ROOT_DIR}/package.json" ] || [ -e "${ROOT_DIR}/pom.xml" ] +``` + +4. 路径合法性验证 +```bash +[[ "${ROOT_DIR}" =~ ^[/][a-zA-Z0-9._/-]+$ ]] +``` + +## 异常处理 + +1. IDE API不可用 +- 降级到B级感知方法 +- 记录错误信息并继续 + +2. 验证失败 +- 尝试下一级感知方法 +- 记录失败原因并继续 + +## 更新策略 + +1. 自动更新触发条件 +- 会话开始时 +- 工作目录变更时 +- 显式请求更新时 +- 置信度低于0.7时 + +2. 缓存策略 +- 会话内缓存：保持整个会话有效 +- 跨会话缓存：基于项目特征判断有效性 + +> 注意：此执行流程专注于项目根目录的感知机制，通过多级感知策略和严格的验证确保准确性。感知结果可由其他组件进行存储处理。 + + \ No newline at end of file diff --git a/core/context/project.context.md b/core/context/project.context.md new file mode 100644 index 0000000..ad50955 --- /dev/null +++ b/core/context/project.context.md @@ -0,0 +1,3 @@ + 项目根目录路径 + + diff --git a/core/memory/basic.memory.md b/core/memory/basic.memory.md new file mode 100644 index 0000000..6bf43cd --- /dev/null +++ b/core/memory/basic.memory.md @@ -0,0 +1,3 @@ + + 上下文记忆 + 经验知识体系 \ No newline at end of file diff --git a/core/project-base-integration.executing.md b/core/project-base-integration.executing.md new file mode 100644 index 0000000..22041b8 --- /dev/null +++ b/core/project-base-integration.executing.md @@ -0,0 +1,102 @@ + + +# 记忆持久化规则 + +## 记忆存储规则 + +1. 存储位置：记忆文件存储在项目根目录下的`.memory`目录中 +2. 目录创建：如果`.memory`目录不存在，需自动创建 +3. 文件命名：使用class名称作为文件名，如`.memory/{class}.context.md` +4. 文件格式：使用Markdown格式存储记忆内容，使用二级标题区分不同的context id + +## 记忆文件结构 + +记忆文件采用以下结构： + +```markdown +--- +class: class_name +--- + +## context_id_1 +context_content_1 + +## context_id_2 +context_content_2 +``` + +## 记忆操作流程 + +```mermaid +flowchart TD + A[开始] --> B{检查class文件是否存在} + B -->|存在| C[读取已有记忆文件] + B -->|不存在| D[创建新记忆文件] + C --> E{检查context id是否存在} + E -->|存在| F[更新已有context内容] + E -->|不存在| G[添加新context内容] + D --> G + F --> H[保存记忆文件] + G --> H + H --> I[结束] +``` + +# Context与Memory对接流程 + +## 文件组织规则 + +1. Context按class分组存储： +```xml +内容 +→ .memory/{class}.context.md +``` + +2. 在文件内通过二级标题区分不同id： +```markdown +## ${context.id} +${context.content} +``` + +## 对接流程 + +```mermaid +flowchart TD + A[Context感知] --> B[提取class] + B --> C[定位或创建class文件] + C --> D[定位或创建context id段落] + D --> E[更新context内容] + E --> F[保存文件] + + style A fill:#4da6ff,stroke:#0066cc,color:white + style B fill:#d94dbb,stroke:#a13b8f,color:white + style C fill:#4dbb5f,stroke:#36873f,color:white + style D fill:#ffa64d,stroke:#cc7a30,color:white + style E fill:#4dbbbb,stroke:#368787,color:white + style F fill:#71ff71,stroke:#3bc23b,color:white +``` + +### 示例结构 + +输入： +```xml + + /Users/sean/WorkSpaces/temp/promptx-init + +``` + +输出文件 (.memory/project.context.md)： +```markdown +--- +class: project +--- + +## rootDir +/Users/sean/WorkSpaces/temp/promptx-init + +## otherProjectContext +其他项目相关上下文内容... +``` + +> 注意：此对接流程采用按类分组的存储策略，减少文件数量，提高管理效率。每个class对应一个文件，文件内使用二级标题组织不同的context内容。 + + \ No newline at end of file diff --git a/core/resource/basic.resource.md b/core/resource/basic.resource.md new file mode 100644 index 0000000..76dd785 --- /dev/null +++ b/core/resource/basic.resource.md @@ -0,0 +1,41 @@ + +# Context 协议 + +## 语法 +@context://[class]/[id] + +## 说明 +用于引用系统定义的上下文信息。通过class和id组合访问相应的上下文内容，为AI提供情境感知能力。 + +## 使用方式 +1. 引用特定上下文: `@context://project/rootDir` - 引用project类中ID为"rootDir"的上下文 +2. 获取上下文信息: 系统会自动提取并提供指定ID的上下文内容 + + + +# Memory 协议 + +## 语法 +@memory://[id] + +## 说明 +用于引用记忆系统中存储的内容。通过记忆ID访问对应的记忆内容，记忆内容存储在项目根目录的`.memory`目录下。 + +## 使用方式 +1. 引用特定记忆: `@memory://context` - 引用ID为"context"的记忆 +2. 获取记忆内容: 系统会自动检索`.memory/context.md`文件并提取其内容 + + + +# Experience 协议 + +## 语法 +@experience://[class]/[id] + +## 说明 +用于引用系统积累的经验知识。通过class和id组合访问相应的经验内容，为AI提供经验复用能力。 + +## 使用方式 +1. 引用特定经验: `@experience://problem_solving/error_handling` - 引用problem_solving类中ID为"error_handling"的经验 +2. 获取经验知识: 系统会自动提取并应用指定的经验内容 + \ No newline at end of file diff --git a/protocol/application/context.protocol.md b/protocol/application/context.protocol.md new file mode 100644 index 0000000..37b07e2 --- /dev/null +++ b/protocol/application/context.protocol.md @@ -0,0 +1,81 @@ +# context 应用协议 + +> **TL;DR:** context标签用于定义AI系统中各类上下文信息的结构和语义，采用简单直观的HTML风格属性标记，专注于"什么是上下文"，是实现CAP(情境感知提示模式)的核心表达机制。 + +## 🔍 基本信息 + +**标签名:** `` + +### 目的与功能 + +context标签在提示工程中提供了情境信息的标准定义方式，主要功能包括： +- 定义上下文信息的名称和分类 +- 提供简洁明了的上下文描述 +- 支持基本的元数据标注 +- 为其他模式提供情境依赖的决策支持 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +context_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= text +text ::= (* 任何文本内容，用于简要描述上下文 *) +``` + +## 🧩 语义说明 + +context标签用于在提示词中定义上下文信息。采用简洁的HTML风格属性标记方式，通过id指定唯一标识符，通过class指定分类，标签内容直接描述该上下文的含义。它作为CAP模式的具体实现，为AI系统提供了清晰简洁的上下文定义能力。实际的上下文感知执行逻辑由executing协议负责实现。 + +## 💡 最佳实践 + +### 核心属性 + +context标签主要使用以下属性： + +- **id**: 定义上下文的唯一标识符，如`id="rootDir"`, `id="userName"` +- **class**: 定义上下文的分类/维度，如`class="project"`, `class="user"`, `class="system"` + + +### 内容组织 + +context标签内容应简洁明了，直接描述该上下文的含义和用途，无需复杂的结构和格式。 + +### 维度分类指南 + +使用class属性定义context维度时，建议遵循以下标准分类： + +- **project**: 项目相关上下文，如根目录、语言、框架等 +- **user**: 用户相关上下文，如用户名、偏好、技能水平等 +- **system**: 系统相关上下文，如操作系统、硬件资源等 +- **environment**: 环境相关上下文，如IDE、终端、网络状况等 +- **task**: 任务相关上下文，如当前目标、进度、限制条件等 + +## 📋 使用示例 + +```html + +项目根目录路径 + + +项目主要编程语言 + + +项目使用的框架列表 + + +操作系统类型 + + +用户名称 + + +集成开发环境类型 + + +当前任务的主要目标 +``` diff --git a/protocol/application/executing.protocol.md b/protocol/application/executing.protocol.md new file mode 100644 index 0000000..a329cd3 --- /dev/null +++ b/protocol/application/executing.protocol.md @@ -0,0 +1,128 @@ +# executing 应用协议 + +> **TL;DR:** executing标签用于定义结构化的执行流程，帮助AI系统按步骤完成任务，支持线性、条件和循环等流程控制。 + +## 🔍 基本信息 + +**标签名:** `` +**版本:** 1.0.0 +**类别:** 执行 +**状态:** 草稿 +**创建日期:** 2023-06-21 + +### 目的与功能 + +executing标签定义了AI系统执行任务的流程和步骤，它的主要功能是： +- 提供线性、有序的执行步骤 +- 支持条件分支和循环结构 +- 明确每个步骤的输入、处理和输出 +- 帮助AI系统进行精确、可靠的任务执行 +- 提供执行状态追踪和错误处理机制 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +executing_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= markdown_content +markdown_content ::= (* 任何有效的Markdown文本，可包含特定语法元素 *) +``` + +## 🧩 语义说明 + +executing标签表示一个完整的执行流程或任务处理过程。标签内容采用Markdown格式，通常包含有序步骤、条件判断、循环结构以及状态跟踪等元素，用于表达严谨的执行逻辑。executing标签特别适合表达算法实现、工作流程和任务执行计划，为AI提供明确的操作指导。 + +## 💡 最佳实践 + +以下是使用executing标签的一些建议做法，这些并非强制要求，仅作为参考： + +### 推荐属性 + +可以考虑使用以下属性来增强executing标签的语义： + +- **mode**: 指定执行模式，如`mode="sequential"`, `mode="conditional"`, `mode="iterative"`, `mode="parallel"` +- **context**: 指定执行上下文，如`context="local"`, `context="remote"`, `context="system"`, `context="user"` +- **priority**: 指定执行优先级，如`priority="high"`, `priority="normal"`, `priority="low"` +- **timeout**: 指定执行超时时间，如`timeout="30s"`, `timeout="5m"` + +### 内容组织 + +推荐在executing标签内使用以下结构组织内容： + +1. 以一级标题(`#`)定义执行任务的名称和目标 +2. 使用二级标题(`##`)标识主要执行阶段 +3. 使用有序列表表示执行步骤的精确顺序 +4. 使用代码块表示具体的命令或代码片段 +5. 使用表格记录输入参数和输出结果 +6. 使用引用块表示状态检查点和异常处理逻辑 + +### 可视化表达 + +不同类型的执行流程适合使用不同的Mermaid图表类型： + +- **流程图(flowchart)**: 适合表示执行步骤和条件分支 + ```mermaid + flowchart TD + A[开始] --> B{条件判断} + B -->|条件成立| C[执行步骤1] + B -->|条件不成立| D[执行步骤2] + C --> E[下一步] + D --> E + E --> F[结束] + ``` + +- **时序图(sequenceDiagram)**: 适合表示组件间的交互过程 + ```mermaid + sequenceDiagram + 参与者A->>参与者B: 请求数据 + 参与者B->>参与者C: 转发请求 + 参与者C-->>参与者B: 返回数据 + 参与者B-->>参与者A: 处理后返回 + ``` + +- **状态图(stateDiagram)**: 适合表示状态转换和执行阶段 + ```mermaid + stateDiagram-v2 + [*] --> 准备 + 准备 --> 执行中: 开始执行 + 执行中 --> 完成: 成功 + 执行中 --> 失败: 出错 + 失败 --> 重试: 可恢复 + 重试 --> 执行中 + 失败 --> [*]: 不可恢复 + 完成 --> [*] + ``` + +## 📋 使用示例 + + + + # 文件批量处理流程 + + ## 初始化阶段 + 1. 检查工作目录权限 + 2. 验证输入文件格式 + 3. 准备输出目录 + + ## 处理阶段 + ```bash + for file in $(ls *.txt); do + echo "处理文件: $file" + process_file "$file" >> log.txt + done + ``` + + ## 验证阶段 + | 检查项 | 预期结果 | 异常处理 | + |-------|---------|---------| + | 输出文件数量 | 等于输入文件数量 | 记录差异并重试 | + | 处理日志 | 无错误记录 | 分析错误类型并修复 | + + ## 完成阶段 + > 状态检查点：所有文件已处理并验证通过 + > 执行清理临时文件并生成处理报告 + \ No newline at end of file diff --git a/protocol/application/experience.protocol.md b/protocol/application/experience.protocol.md new file mode 100644 index 0000000..435da4e --- /dev/null +++ b/protocol/application/experience.protocol.md @@ -0,0 +1,75 @@ +# experience 应用协议 + +> **TL;DR:** experience标签用于定义AI系统中经验知识的结构和语义，采用简单直观的HTML风格属性标记，专注于"什么是经验"，是实现系统自我优化和经验积累的核心表达机制。 + +## 🔍 基本信息 + +**标签名:** `` + +### 目的与功能 + +experience标签在提示工程中提供了经验知识的标准定义方式，主要功能包括： +- 定义经验信息的名称和分类 +- 提供简洁明了的经验描述 +- 支持基本的元数据标注 +- 为系统提供可复用的问题解决知识 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +experience_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= text +text ::= (* 任何文本内容，用于简要描述经验 *) +``` + +## 🧩 语义说明 + +experience标签用于在提示词中定义经验知识。采用简洁的HTML风格属性标记方式，通过id指定唯一标识符，通过class指定经验的分类维度，标签内容直接描述该经验的含义。它作为系统知识积累的具体实现，为AI系统提供了清晰简洁的经验定义能力。 + +## 💡 最佳实践 + +### 核心属性 + +experience标签主要使用以下属性： + +- **id**: 定义经验的唯一标识符，如`id="solution_pattern"`，`id="error_response"` +- **class**: 定义经验的分类/维度，如`class="problem_solving"`，`class="system"`，`class="user"` + +### 内容组织 + +experience标签内容应简洁明了，直接描述该经验的含义和用途，无需复杂的结构和格式。 + +### 维度分类指南 + +使用class属性定义experience维度时，建议遵循以下标准分类： + +- **problem_solving**: 问题解决相关经验，如常见问题的解决方案和策略 +- **system**: 系统相关经验，如系统行为模式、限制和最佳实践 +- **user**: 用户相关经验，如用户交互模式和偏好 +- **domain**: 领域相关经验，如特定专业领域的知识和最佳实践 +- **optimization**: 优化相关经验，如性能提升和效率改进的方法 + +## 📋 使用示例 + +```html + +处理错误的最佳策略 + + +系统资源限制与应对策略 + + +用户交互偏好与行为模式 + + +代码优化方法论 + + +系统性能调优技巧 +``` + diff --git a/protocol/application/memory.protocol.md b/protocol/application/memory.protocol.md new file mode 100644 index 0000000..35958c9 --- /dev/null +++ b/protocol/application/memory.protocol.md @@ -0,0 +1,72 @@ +# memory 应用协议 + +> **TL;DR:** memory标签用于定义AI系统的记忆持久化能力，支持跨会话知识存储和检索，采用简单直观的方式表达记忆内容。 + +## 🔍 基本信息 + +**标签名:** `` + +### 目的与功能 + +memory标签定义了AI系统记忆的内容与标识，主要功能包括： +- 提供简洁的记忆内容定义方式 +- 通过唯一标识符区分不同记忆 +- 实现跨会话的信息传递能力 +- 支持记忆内容的简明描述 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +memory_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= text +text ::= (* 任何文本内容，用于描述记忆 *) +``` + +## 🧩 语义说明 + +memory标签用于在提示词中定义需要持久化的记忆内容。通过id属性提供唯一标识，标签内容直接描述该记忆的含义。它使系统能够保存和利用过去的交互经验和知识，从而增强系统在长期交互中的连续性和一致性。 + +## 💡 最佳实践 + +### 核心属性 + +memory标签主要使用以下属性： + +- **id**: 记忆的唯一标识符，如`id="context"`, `id="history"`, `id="preferences"` + +### 可选属性 + +在特定场景下，也可以使用以下可选属性： + +- **type**: 记忆类型，如`type="session"`, `type="long-term"`, `type="episodic"` +- **priority**: 记忆优先级，如`priority="high"`, `priority="normal"`, `priority="low"` + +### 内容组织 + +memory标签内容应简洁明了，直接描述该记忆的含义和用途，无需复杂的结构和格式。 + +## 📋 使用示例 + +```html + +上下文感知记忆 + + +用户对话历史记录 + + +用户个性化偏好设置 + + +项目相关信息和配置 + + +重要决策历史记录 +``` + +> **注意**: 实际的记忆存储和检索逻辑应由系统底层实现，memory标签专注于定义记忆的标识和基本含义。 \ No newline at end of file diff --git a/protocol/application/protocol-application-template.md b/protocol/application/protocol-application-template.md new file mode 100644 index 0000000..ff63fa8 --- /dev/null +++ b/protocol/application/protocol-application-template.md @@ -0,0 +1,93 @@ +# [标签名] 应用协议 + +> **TL;DR:** [一句话描述此标签的核心用途与价值] + +## 🔍 基本信息 + +**标签名:** `<标签名>` + + +### 目的与功能 + +[详细描述此标签的目的、解决的问题和提供的功能] + +## 🧰 设计原则 + +定义应用协议时，应当遵循以下核心设计原则： + +1. **约定大于配置**：减少明确的配置需求，优先使用合理的默认约定 +2. **职责单一**：每个协议应专注于单一功能或目的，避免过度复杂 +3. **最小可行产品(MVP)**：从最核心功能开始，确保基础用例能够正常工作 +4. **奥卡姆剃刀原则**：在同等条件下，应选择最简单的设计方案 +5. **一致性**：保持与其他协议的设计风格和使用模式一致 + +这些原则有助于确保协议设计的简洁性、可用性和可维护性。 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +tag_element ::= '<标签名' attributes? '>' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= markdown_content +markdown_content ::= (* 任何有效的Markdown文本，可包含特定语法元素 *) +``` + +## 🧩 语义说明 + +此标签用于[描述标签的主要用途和语义]。在提示词中，它表示[...]并协助AI[...]。 + +## 💡 最佳实践 + +以下是使用此标签的一些建议做法，这些并非强制要求，仅作为参考： + +### 推荐属性 + +可以考虑使用以下属性来增强标签的语义： + +- **属性1**: [属性说明和示例值] +- **属性2**: [属性说明和示例值] +- **属性3**: [属性说明和示例值] + +### 内容组织 + +推荐在标签内使用以下结构组织内容： + +1. [内容组织建议1] +2. [内容组织建议2] +3. [内容组织建议3] + +### 可视化表达（如适用） + +[如适用，描述此标签内容的可视化表达方式，如图表类型、格式建议等] + +### 扩展选项 + +根据MVP原则，标签应先实现核心功能。当核心功能稳定后，可考虑以下扩展方向： + +1. **高级属性**：添加可选的高级配置属性，但确保基本功能不依赖这些属性 +2. **集成能力**：提供与其他标签或协议的集成接口 +3. **专业化变体**：为特定场景开发的专门版本或扩展 +4. **性能优化**：针对高频使用场景的性能改进 + +扩展时应保持向后兼容性，并避免增加不必要的复杂度。 + +## 📋 使用示例 + +<标签名 属性1="值1" 属性2="值2"> + # 示例内容标题 + + ## 内容部分1 + 示例内容描述 + + ## 内容部分2 + - 要点1 + - 要点2 + + ``` + 代码或特殊格式示例（如适用） + ``` + diff --git a/protocol/application/resource.protocol.md b/protocol/application/resource.protocol.md new file mode 100644 index 0000000..2106d22 --- /dev/null +++ b/protocol/application/resource.protocol.md @@ -0,0 +1,37 @@ +# 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/role.protocol.md b/protocol/application/role.protocol.md new file mode 100644 index 0000000..ec1a401 --- /dev/null +++ b/protocol/application/role.protocol.md @@ -0,0 +1,121 @@ +# role 应用协议 + +> **TL;DR:** role标签定义AI系统在响应过程中扮演的单一专业角色，提供明确的职责、专业知识和行为准则，是实现RRP(角色响应协议)的核心表达机制。 + +## 🔍 基本信息 + +**标签名:** `` + +### 目的与功能 + +role标签为AI系统提供清晰的角色定义框架，主要功能包括： +- 定义AI需要扮演的专业角色特性和领域知识 +- 提供角色专有的行为准则和响应原则 +- 设置角色视角下的专业知识体系和术语 +- 明确角色的职责范围和响应边界 + +## 🧰 设计原则 + +定义role应用协议时，特别强调以下核心设计原则： + +1. **职责单一**：每个role专注于定义单一专业角色，不包含角色切换机制 +2. **约定大于配置**：使用合理的默认角色结构，减少复杂配置 +3. **最小可行产品**：专注于角色的核心定义要素，确保基础使用场景 +4. **奥卡姆剃刀原则**：保持角色定义的简洁性，避免不必要的复杂属性 +5. **一致性**：与其他协议保持一致的设计风格 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +role_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= markdown_content +markdown_content ::= (* 任何有效的Markdown文本，描述角色特性 *) +``` + +## 🧩 语义说明 + +role标签用于明确定义AI系统在特定场景中需要扮演的专业角色。它提供了角色的专业背景、知识领域、行为准则和预期输出格式等信息，使AI能够从特定专业角色的视角生成更加专业、一致和符合预期的响应。 + +## 💡 最佳实践 + +### 推荐属性 + +可以考虑使用以下属性来增强role标签的语义： + +- **name**: 角色名称，如`name="软件架构师"` +- **domain**: 专业领域，如`domain="系统设计"` +- **expertise**: 专业水平，如`expertise="expert"` +- **tone**: 沟通风格，如`tone="professional"` +- **perspective**: 思考视角，如`perspective="systems-thinking"` + +### 内容组织 + +推荐在标签内使用以下结构组织内容： + +1. **职责范围**: 明确定义角色的职责边界 +2. **专业知识**: 列出角色所具备的专业知识体系 +3. **行为准则**: 描述角色的专业行为标准 +4. **术语表**: 角色常用的专业术语定义 +5. **输出格式**: 角色回应的标准格式要求 + +### 可视化表达 + +角色知识结构可使用mermaid图表表示： + +```mermaid +mindmap + root((软件架构师)) + 系统设计 + 高可用性 + 可扩展性 + 性能优化 + 技术选型 + 框架评估 + 技术栈兼容性 + 架构模式 + 微服务 + 事件驱动 + 领域驱动 +``` + +## 📋 使用示例 + +```xml + + ## 职责范围 + - 分析系统需求并转化为技术架构设计 + - 评估并选择适合项目的技术栈和架构模式 + - 设计系统组件结构和交互关系 + - 确定非功能性需求的技术实现方案 + + ## 专业知识 + - 分布式系统架构设计原则 + - 微服务架构模式与实践 + - API设计与版本控制策略 + - 系统性能优化与可扩展性保障 + + ## 行为准则 + - 始终从整体系统视角思考问题 + - 关注架构决策对可维护性和未来扩展的影响 + - 使用准确的技术术语和清晰的图示表达设计思路 + - 平衡技术理想与实际约束，提供务实可行的方案 + + ## 术语表 + - **解耦**: 降低系统组件间的依赖程度 + - **服务边界**: 微服务架构中的职责划分边界 + - **技术债**: 设计或实现中的妥协导致的未来额外工作 + + ## 输出格式 + 架构设计文档应包含： + 1. 架构概述 + 2. 组件设计 + 3. 接口规范 + 4. 部署模型 + 5. 关键技术决策说明 + +``` \ No newline at end of file diff --git a/protocol/application/task.protocol.md b/protocol/application/task.protocol.md new file mode 100644 index 0000000..c89c810 --- /dev/null +++ b/protocol/application/task.protocol.md @@ -0,0 +1,190 @@ +# task 应用协议 + +> **TL;DR:** task标签用于定义可重用的任务模板，支持任务的静态描述和动态执行，是实现任务模板化和标准化执行的核心机制。 + +## 🔍 基本信息 + +**标签名:** `` + +### 目的与功能 + +task标签提供了任务模板化的框架，主要功能包括： +- 定义标准化的任务结构和执行流程 +- 支持任务的参数化配置和动态绑定 +- 提供任务执行的验证和约束条件 +- 实现任务模板的复用和组合 +- 容器化封装任务执行环境和上下文 + +## 🧰 设计原则 + +定义task应用协议时，特别强调以下核心设计原则： + +1. **职责单一**：每个task专注于定义单一完整的任务流程 +2. **约定大于配置**：使用合理的默认任务结构，减少不必要的配置 +3. **最小可行产品**：专注于任务定义的核心要素，确保基础执行场景 +4. **奥卡姆剃刀原则**：保持任务定义的简洁性，避免过度复杂的结构 +5. **一致性**：与其他协议保持一致的设计风格 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +task_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= markdown_content +markdown_content ::= (* 任何有效的Markdown文本，描述任务结构 *) +``` + +## 🧩 语义说明 + +task标签用于定义可重用的任务模板。它提供了任务的结构化描述，包括目标定义、执行环境和成功标准，使任务可以被标准化执行和重复使用。通过与role标签的配合，可以实现特定角色执行特定任务的精确控制。 + +## 💡 最佳实践 + +### 核心设计原则 + +在设计task标签时，建议遵循以下核心原则： + +1. **职责单一**：每个task专注于定义单一完整的任务流程 +2. **约定大于配置**：使用合理的默认任务结构，减少不必要的配置 +3. **最小可行产品**：专注于任务定义的核心要素，确保基础执行场景 +4. **奥卡姆剃刀原则**：保持任务定义的简洁性，避免过度复杂的结构 +5. **一致性**：与其他协议保持一致的设计风格 + +### 推荐属性 + +可以考虑使用以下属性来增强task标签的语义： + +- **id**: 任务唯一标识，如`id="code-review-task"` +- **type**: 任务类型，如`type="analysis"` +- **priority**: 任务优先级，如`priority="high"` +- **timeout**: 执行超时时间，如`timeout="30m"` +- **requires**: 依赖的角色或资源，如`requires="architect"` + +### OES框架内容组织 + +强烈推荐使用OES框架组织任务内容，这种结构借鉴了容器化思想，使任务更加清晰和可执行： + +1. **目标(Objective)** + - 明确定义任务的具体预期结果 + - 设定任务边界和约束 + - 说明任务的价值和意义 + +2. **环境(Environment)** + - **背景信息**：任务相关的上下文和背景 + - **资源需求**：执行任务所需的数据、工具和参考资料 + - **约束条件**：技术、业务和资源限制 + - **执行规范**：风格指南、质量标准和工作流程 + - **上下文关联**：与其他任务的关系和依赖 + +3. **成功标准(Success Criteria)** + - **基础达标**：最低要求和基本功能 + - **预期品质**：符合项目整体质量标准的指标 + - **验证方法**：如何验证任务是否成功完成 + - **结果格式**：交付物的具体格式和内容要求 + +### 任务网络构建 + +对于复杂项目，推荐构建任务网络，通过以下方式连接多个任务： + +1. **垂直连接**：上级任务的成功标准成为下级任务的目标 +2. **水平连接**：前序任务的产物成为后续任务的环境组成部分 + +### 可视化表达 + +任务执行流程可使用mermaid图表表示： + +```mermaid +graph TD + A[输入验证] --> B{参数检查} + B -->|通过| C[执行准备] + B -->|失败| H[错误处理] + C --> D[主要步骤] + D --> E[结果验证] + E -->|成功| F[输出结果] + E -->|失败| G[回滚处理] + H --> I[任务终止] + G --> I +``` + +## 📋 使用示例 + +```xml + + ## 目标(Objective) + 对提交的代码变更进行全面的代码审查，确保代码质量和一致性，并提供具体改进建议。 + 目标范围包括代码风格、性能、安全性和业务逻辑正确性评估。 + + ## 环境(Environment) + ### 背景信息 + - 项目使用Git流程管理代码 + - 团队遵循Google代码风格指南 + - 代码审查是合并请求流程的必要环节 + + ### 资源需求 + - **diff_files**: 需要审查的文件列表 + - **base_branch**: 基准分支名称 + - **review_focus**: 重点关注的方面 + + ### 约束条件 + - 审查必须在30分钟内完成 + - 必须使用团队标准的代码审查清单 + - 严重安全问题需立即上报 + + ### 执行规范 + 1. **预检查** + - 验证文件可访问性 + - 检查diff格式正确性 + - 确认审查权限 + + 2. **静态分析** + - 代码风格检查 + - 潜在问题扫描 + - 复杂度评估 + + 3. **逻辑审查** + - 业务逻辑正确性 + - 异常处理完整性 + - 性能影响评估 + + 4. **安全审查** + - 安全漏洞检查 + - 敏感信息扫描 + - 权限控制审查 + + ## 成功标准(Success Criteria) + ### 基础达标 + - 所有必要的检查项已完成 + - 没有严重或阻塞性问题 + - 代码符合团队编码标准 + + ### 预期品质 + - 提供至少3个有价值的改进建议 + - 验证测试覆盖率达到团队标准 + - 确认新代码没有引入性能退化 + + ### 结果格式 + ```json + { + "status": "approved|rejected|needs_revision", + "summary": "审查总结", + "issues": [ + { + "type": "security|performance|style", + "severity": "high|medium|low", + "description": "问题描述", + "suggestion": "改进建议" + } + ], + "metrics": { + "files_reviewed": 10, + "issues_found": 5, + "review_time": "25m" + } + } + ``` + +``` \ No newline at end of file diff --git a/protocol/application/thinking.protocol.md b/protocol/application/thinking.protocol.md new file mode 100644 index 0000000..19c5acc --- /dev/null +++ b/protocol/application/thinking.protocol.md @@ -0,0 +1,147 @@ +# thinking 应用协议 + +> **TL;DR:** thinking标签用于定义结构化的思考框架，帮助AI系统进行系统性分析和推理，支持Markdown和Mermaid图表表达思维过程。 + +## 🔍 基本信息 + +**标签名:** `` +**版本:** 1.0.0 +**类别:** 思考 +**状态:** 草稿 +**创建日期:** 2023-06-20 + +### 目的与功能 + +thinking标签定义了AI系统进行思考分析的框架和流程，它的主要功能是： +- 提供结构化的思维分析模式 +- 组织和展示概念关系与逻辑推理 +- 支持可视化思维导图和决策树 +- 帮助AI系统进行系统性、全面性的问题分析 + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +thinking_element ::= '' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= markdown_content +markdown_content ::= (* 任何有效的Markdown文本，包括Mermaid图表 *) +``` + +## 🧩 语义说明 + +thinking标签表示一个完整的思考过程或思维框架。标签内容采用Markdown格式，可以包含文本段落、列表、标题以及Mermaid图表等元素，用于表达结构化的思考方式。thinking标签特别适合表达概念关系、逻辑推理和系统性思考，为AI提供思考分析的参考框架。 + +## 💡 最佳实践 + +以下是使用thinking标签的一些建议做法，这些并非强制要求，仅作为参考： + +### 推荐属性 + +可以考虑使用以下属性来增强thinking标签的语义： + +- **type**: 指定思考类型，如`type="analysis"`, `type="design"`, `type="evaluation"`, `type="brainstorm"`, `type="problem-solving"` +- **domain**: 指定思考领域，如`domain="software"`, `domain="business"`, `domain="science"` +- **method**: 指定思维方法，如`method="systematic"`, `method="lateral"`, `method="critical"` + +### 内容组织 + +推荐在thinking标签内使用以下结构组织内容： + +1. 以一级标题(`#`)定义核心问题或思考主题 +2. 使用二级标题(`##`)划分思考的主要部分（如问题分析、方案设计、评估等） +3. 使用列表、表格等方式组织关键点和因素 +4. 使用Mermaid图表可视化思维过程（见下方推荐） +5. 在结尾提供结论或决策建议 + +### Mermaid图表选择 + +不同类型的思考场景适合使用不同的Mermaid图表类型： + +- **思维导图(mindmap)**: 适合概念分解、头脑风暴和关联分析 + ```mermaid + mindmap + root((核心问题)) + 因素A + 子因素A1 + 子因素A2 + 因素B + 子因素B1 + 因素C + ``` + +- **流程图(flowchart)**: 适合步骤分析、决策流程和算法思路 + ```mermaid + flowchart TD + A[起点] --> B{判断条件} + B -->|条件1| C[路径1] + B -->|条件2| D[路径2] + C --> E[结果1] + D --> F[结果2] + ``` + +- **类图(classDiagram)**: 适合概念关系和抽象模型设计 + ```mermaid + classDiagram + 概念A <|-- 子概念B + 概念A <|-- 子概念C + 概念A : 属性1 + 概念A : 属性2 + ``` + +- **甘特图(gantt)**: 适合项目规划和时间线分析 + ```mermaid + gantt + title 项目计划 + section 阶段1 + 任务1 :a1, 2023-01-01, 30d + 任务2 :after a1, 20d + section 阶段2 + 任务3 :2023-02-15, 28d + ``` + +- **状态图(stateDiagram)**: 适合状态转换和系统行为分析 + ```mermaid + stateDiagram-v2 + [*] --> 状态A + 状态A --> 状态B: 事件1 + 状态B --> 状态C: 事件2 + 状态C --> [*] + ``` + +## 📋 使用示例 + + + + # 问题分析框架 + + ## 核心问题 + 如何优化系统性能并保持代码可维护性 + + ## 因素分析 + 影响因素包括： + - 算法效率 + - 数据结构选择 + - 并发处理 + - 代码组织 + + ```mermaid + mindmap + root((性能优化)) + 算法层面 + 时间复杂度 + 空间复杂度 + 数据结构 + 查询效率 + 内存占用 + 系统架构 + 并发模型 + 资源管理 + ``` + + ## 结论 + 应优先考虑数据结构优化和并发处理模型调整 + diff --git a/protocol/pattern/dpml-resource.protocol.md b/protocol/pattern/dpml-resource.protocol.md new file mode 100644 index 0000000..6b637ff --- /dev/null +++ b/protocol/pattern/dpml-resource.protocol.md @@ -0,0 +1,235 @@ +# 资源引用(RP) 模式协议 + +> **TL;DR:** 资源引用协议定义了使用@符号统一引用各类资源的语法规则，支持基础资源定位和嵌套引用，实现提示词中的资源无缝集成。 + +## 🔍 协议概述 + +**协议名称:** 资源引用协议 (Resource Protocol, RP) +**版本:** 1.0.0 +**状态:** 草稿 +**作者:** PromptX团队 +**创建日期:** 2023-06-25 +**最后更新:** 2023-06-25 + +### 目的与范围 + +资源引用协议旨在提供一种统一的语法机制，使提示词能够无缝引用和整合各种类型的资源，包括文件、目录、网络资源以及特定的应用协议。本协议定义了资源定位的基本语法、组合规则和链式调用机制，使提示词能够更加灵活地整合和使用外部资源。 + +### 相关协议 + +- DPML核心协议：提供基础的标记语言结构 +- 应用协议：如thinking、executing等可以与资源协议组合使用 + +## 📝 语法规则 + +### 形式化定义 + +```ebnf +resource_reference ::= '@' protocol_name ':' resource_location [query_params] +resource_location ::= uri | nested_reference +uri ::= protocol_name '://' path +nested_reference ::= ['@'] protocol_name ':' resource_location + +protocol_name ::= alphanumeric_string +path ::= path_segment {'/' path_segment} +path_segment ::= alphanumeric_string | '.' | '..' | wildcard_pattern +wildcard_pattern ::= '*' | '**' | '*.' file_extension + +query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value} +param_name ::= alphanumeric_string +param_value ::= alphanumeric_string | quoted_string + +alphanumeric_string ::= (letter | digit | '_' | '-')+ +letter ::= 'a' | 'b' | ... | 'z' | 'A' | 'B' | ... | 'Z' +digit ::= '0' | '1' | ... | '9' +quoted_string ::= '"' {any_char_except_quote} '"' +file_extension ::= letter+ +``` + +### 词法元素 + +| 元素 | 形式 | 描述 | +|------|------|------| +| 资源引用标记 | @ | 所有资源引用都以@符号开始 | +| 协议名称 | 任意协议名 | 指定被引用资源的协议类型 | +| 协议分隔符 | : | 分隔协议名称和资源位置 | +| 协议路径分隔符 | :// | 用于URI路径的分隔符 | +| 路径段分隔符 | / | 分隔路径中的不同部分 | +| 查询参数开始 | ? | 标识查询参数的开始 | +| 参数分隔符 | & | 分隔多个查询参数 | +| 参数赋值 | = | 分隔参数名和参数值 | +| 通配符 | *, ** | 用于在路径中匹配一个或多个文件/目录 | + +### 组合规则 + +1. 单一协议引用：`@protocol://path`，例如`@file://document.md` +2. 嵌套协议引用：`@outer:@inner://path`，例如`@thinking:@file://method.md` +3. 嵌套协议简写：内部协议可省略@，例如`@outer:inner://path`，例如`@thinking:file://method.md` +4. 路径中支持通配符： + - `*` 匹配单层中的任意文件或目录，如`@file://docs/*.md` + - `**` 匹配多层目录和文件，如`@file://src/**/*.js` + - `*.ext` 匹配特定扩展名的文件，如`@file://docs/*.txt` + +这些规则构成了资源引用协议的核心，简洁而灵活地满足各种引用场景。 + +## 🧩 语义定义 + +### 核心概念 + +| 概念 | 定义 | 示例 | +|------|------|------| +| 基础资源 | 指向物理存储或网络位置的基本资源类型 | @file://document.txt | +| 应用协议 | 指向特定应用协议定义的资源 | @thinking://brainstorm | +| 资源路径 | 定位具体资源的路径信息 | projects/main/doc.md | +| 查询参数 | 提供资源处理或过滤的额外信息 | ?section=2&format=md | +| 嵌套引用 | 一个协议引用另一个协议 | @thinking:@file://method.md | +| 通配符 | 用于匹配多个资源的模式 | docs/*.md, src/**/*.js | + +### 解释规则 + +1. 资源引用解析从左至右进行，先识别协议名称，再解析资源位置和查询参数 +2. 嵌套引用从内向外解析，内层资源引用的结果作为外层引用的输入 +3. 如果资源类型未指定具体实现方式，则使用该类型的默认解释器 +4. 查询参数应用于资源加载后的处理阶段，不影响资源的基本定位 +5. 相对路径解析基于当前上下文的工作目录或基础路径 +6. 通配符解析遵循常见的glob模式规则 + +## ✅ 约束与验证 + +### 必要约束 + +1. 协议名称必须是已注册的协议类型 +2. 资源路径必须符合目标系统的路径要求和访问权限 +3. 嵌套引用的深度不应超过3层，以保持可读性和解析效率 +4. 查询参数必须是目标协议类型支持的参数 + +### 验证规则 + +资源引用的验证包括以下步骤： +1. 语法验证：检查是否符合EBNF定义的语法结构 +2. 协议验证：检查引用的协议类型是否已注册 +3. 路径验证：检查资源路径是否合法且可访问 +4. 参数验证：检查查询参数是否被目标协议类型支持 +5. 安全验证：检查资源引用是否符合安全策略 + +### 错误处理 + +当遇到无效的资源引用时，应采取以下处理方式： +1. 语法错误：返回错误描述，指出错误位置和期望格式 +2. 资源不存在：返回资源未找到的错误，可能提供相似资源的建议 +3. 访问受限：返回权限错误，并说明所需权限 +4. 参数无效：返回参数错误，说明支持的参数格式 +5. 解析超时：对于复杂的链式调用，如果解析时间超过预设限制，返回超时错误 + +## 🔄 扩展机制 + +### 扩展点 + +资源引用协议可在以下方面进行扩展： +1. 新的协议类型：注册新的协议 +2. 协议处理器：为协议类型定义处理逻辑 +3. 查询参数：扩展特定协议类型支持的查询参数 + +### 扩展规则 + +创建资源协议扩展时，应遵循以下规则： +1. 新协议类型必须使用唯一的标识符，避免与现有类型冲突 +2. 扩展必须提供完整的处理器实现，包括资源定位、加载和转换 +3. 扩展应提供错误处理机制和回退策略 +4. 扩展必须遵循基本的安全原则，不应引入新的安全风险 + +### 扩展示例 + +``` +// 定义新的协议类型 +@custom://resource-path?param=value + +// 嵌套协议示例 +@outer:@inner://path/to/resource + +// 多层嵌套示例 +@outer:middle:@inner://path +``` + +## 📋 使用示例 + +### 有效示例 + +``` +// 基础资源引用 +@file://documents/report.md + +// 含有通配符的引用 +@file://docs/*.md + +// 多层通配符引用 +@file://src/**/*.js + +// 特定扩展名通配符 +@file://project/*.{js,ts} + +// HTTP资源引用 +@http://example.com/api/data.json + +// 嵌套资源引用（完整形式） +@thinking:@file://method.md + +// 嵌套资源引用（简写形式） +@thinking:file://method.md + +// 多层嵌套（完整形式） +@outer:@middle:@inner://resource + +// 多层嵌套（简写形式） +@outer:middle:inner://resource + +// 带查询参数的引用 +@file://document.md?section=intro&format=html +``` + +### 无效示例 + +``` +// 缺少协议名称 +@://document.txt +// 错误原因: 必须指定协议名称 + +// 缺少资源路径 +@file:// +// 错误原因: 必须提供资源路径 + +// 非法字符在路径中 +@file://doc.txt +// 错误原因: 路径包含非法字符 + +// 查询参数格式错误 +@file://code.py?lines:10-20 +// 错误原因: 查询参数应使用=赋值 +``` + +## 💡 最佳实践 + +1. 使用最合适的协议名称表示资源类型，提高语义明确性 +2. 嵌套引用时，如果清晰度很重要，使用完整形式（带内部@符号） +3. 如果简洁性更重要，则使用简写形式（省略内部@符号） +4. 保持资源路径的相对引用，以提高提示词的可移植性 +5. 合理使用通配符，避免过于宽泛的匹配模式 +6. 使用查询参数进行资源过滤，而不是在提示词中手动处理 +7. 避免过深的嵌套引用，保持可读性 + +### 常见问题 + +**Q: 资源引用是否支持通配符?** +A: 是的，协议支持`*`（单层匹配）、`**`（多层匹配）和`*.ext`（特定扩展名匹配）等通配符模式 + +**Q: 如何引用资源的特定部分?** +A: 使用查询参数来指定资源的特定部分，如`@file://document.md?section=introduction` + +**Q: 如何处理多种文件扩展名的通配符?** +A: 可以使用花括号表示多选项，如`@file://src/*.{js,ts,jsx}`匹配多种扩展名 + +**Q: 嵌套引用有深度限制吗?** +A: 为了保持可读性，建议嵌套深度不超过3层，虽然语法上没有严格限制 + +**Q: 嵌套引用中的URI如何处理?** +A: 在嵌套引用中，内层URI会被完整处理后传递给外层协议，如`@outer:http://example.com`中，http协议的结果会传递给outer协议处理 \ No newline at end of file diff --git a/protocol/pattern/dpml.protocol.md b/protocol/pattern/dpml.protocol.md new file mode 100644 index 0000000..1f91b53 --- /dev/null +++ b/protocol/pattern/dpml.protocol.md @@ -0,0 +1,257 @@ +# DPML 模式协议 + +> **TL;DR:** DPML(Deepractice Prompt Markup Language)是一种结合了XML结构和Markdown内容的混合标记语言，专为提示词工程设计，提供清晰的语义结构同时保持自然语言的灵活性。 + +## 🔍 协议概述 + +**协议名称:** Deepractice Prompt Markup Language (DPML) +**版本:** 0.0.1 +**状态:** 草稿 +**作者:** PromptX Team +**创建日期:** 2023-06-20 +**最后更新:** 2023-06-20 + +### 目的与范围 + +DPML旨在为提示词工程提供一种标准化的表达方式，解决以下关键问题： +- 提供清晰的语义结构，区分不同类型的提示内容（思考框架、执行流程等） +- 保持自然语言提示词的灵活性和表现力 +- 支持提示词的组织、复用和模块化 +- 便于机器解析和处理，同时保持人类可读性 + +DPML适用于所有需要结构化表达提示词的场景，包括但不限于AI助手开发、复杂任务指令设计、自动化工作流程等。 + +### 相关协议 + +- **XML**: DPML的基本标签结构借鉴了XML +- **Markdown**: DPML的内容部分采用Markdown格式 + +## 📝 语法规则 + +### 形式化定义 + +```ebnf +document ::= element | (element document) +element ::= '<' tag attributes '>' content '' | '<' tag attributes '/>' +tag ::= name +attributes ::= (attribute attributes) | ε +attribute ::= name '="' value '"' +name ::= [A-Za-z][A-Za-z0-9_-]* +value ::= [^"]* +content ::= markdown_text | (element content) | ε +markdown_text ::= (* 任何有效的Markdown文本 *) +``` + +### 词法元素 + +| 元素 | 形式 | 描述 | +|------|------|------| +| 标签 | `...` | 定义语义单元，如``,`` | +| 自闭合标签 | `` | 无内容的标签，如`` | +| 属性 | `property="value"` | 标签配置信息，如`type="analysis"` | +| 内容 | Markdown格式文本 | 标签内的实际提示词文本 | +| 注释 | `` | 协议注释，不作为提示词内容 | + +### 组合规则 + +1. 标签可以嵌套，形成层次结构 +2. 一个标签可以有多个属性，属性名在同一标签中不能重复 +3. 标签必须正确闭合，要么是配对标签``，要么是自闭合标签`` +4. 内容部分可以是纯Markdown文本，也可以包含其他标签 +5. 根元素推荐使用``，但不强制要求 + +## 🧩 语义定义 + +### 核心概念 + +| 概念 | 定义 | 示例 | +|------|------|------| +| 提示单元 | 由标签定义的语义完整的提示组件 | `分析问题...` | +| 属性修饰 | 通过属性细化提示单元的行为特性 | `` | +| 内容表达 | 使用Markdown表达的实际提示文本 | `# 步骤\n1. 首先...` | +| 组合提示 | 多个提示单元组合形成完整提示 | `......` | + +### 解释规则 + +1. 标签名决定提示单元的主要语义类型（思考、执行等） +2. 属性提供额外的控制和元数据，影响提示单元的解释方式 +3. 内容部分按Markdown语法解析，保留其格式特性（标题、列表、强调等） +4. 嵌套标签表示包含关系，内层提示单元属于外层提示单元的组成部分 +5. 同级标签按顺序解释，表示提示流程的先后次序 + +## ✅ 约束与验证 + +### 必要约束 + +1. 标签名必须符合命名规则：以字母开头，可包含字母、数字、下划线和连字符 +2. 属性值必须使用双引号包围 +3. 标签必须正确闭合，开闭标签名称必须一致 +4. 标签嵌套必须正确，不允许交叉嵌套 +5. Markdown内容必须是有效的Markdown语法 + +### 验证规则 + +DPML文档可通过以下步骤验证： +1. 检查XML结构的有效性（标签配对、属性格式等） +2. 验证标签名是否属于预定义集合或符合扩展规则 +3. 检查必需属性是否存在且值有效 +4. 验证Markdown内容的格式有效性 +5. 检查引用资源的可访问性 + +### 错误处理 + +遇到语法错误时的处理优先级： +1. 标签结构错误（未闭合、交叉嵌套）：终止解析，报告错误位置 +2. 未知标签或属性：发出警告但继续解析，将其视为自定义扩展 +3. Markdown语法错误：尽可能宽容处理，按文本呈现 +4. 资源引用错误：报告无法访问的资源，但继续处理其他内容 + +## 🔄 扩展机制 + +### 扩展点 + +DPML提供以下扩展点： +1. 自定义标签：通过命名空间机制创建新的语义标签 +2. 自定义属性：为现有标签添加新的控制属性 +3. 内容增强：在Markdown中嵌入特殊语法或命令 +4. 外部引用：导入和复用外部DPML组件 + +### 扩展规则 + +1. 自定义标签应使用命名空间前缀：`` +2. 自定义属性可直接添加，但建议使用命名空间：`ns:property="value"` +3. 内容增强应使用明确的语法标记，避免与Markdown冲突 +4. 扩展必须向下兼容，标准解析器应能忽略无法理解的扩展而不中断处理 + +### 扩展示例 + +```xml + + + + + + + # 分析方法 + 使用**系统思维**方法 + + + + + 执行步骤... + + + +``` + +## 📋 使用示例 + +### 有效示例 + +**1. 基本思考-执行流程** +``` + + + # 问题分析 + 这是一个**数据处理**问题，需要考虑： + 1. 数据格式转换 + 2. 性能优化 + + + + # 执行步骤 + 1. 首先读取输入文件 + 2. 应用转换算法 + 3. 输出结果到目标位置 + + 确保全程**记录日志**以便调试。 + + +``` + +**2. 带属性的复杂结构** +``` + + + # 项目背景 + 客户需要一个数据可视化dashboard。 + + + + # 设计思路 + 采用模块化设计，分离数据层和视图层。 + + + ## 架构概念 + 使用React + D3.js组合 + + + + + # 实现步骤 + 1. 搭建基础框架 + 2. 实现数据连接器 + 3. 开发可视化组件 + + +``` + +**3. 资源引用** +``` + + + 参考API规范文档 + + API端点定义在源码的25-35行 + + + + 基于API规范进行设计... + + +``` + +### 无效示例 + +**1. 标签未闭合** +``` + + + 思考内容... + + + + 执行步骤... + + +``` +错误原因：``标签未正确闭合 + +**2. 属性格式错误** +``` + + + 思考内容... + + +``` +错误原因：属性值缺少双引号，应为`type="analysis"` + +## 💡 最佳实践 + +1. **语义清晰度**：选择表意明确的标签名，让提示结构一目了然 +2. **适度分层**：合理使用嵌套结构，避免过深的层次导致可读性下降 +3. **内容聚焦**：每个标签内容应关注单一职责，避免功能混杂 +4. **属性合理性**：只使用必要的属性，避免过度配置 +5. **一致性**：在整个项目中保持一致的DPML结构风格 + +### 常见问题 + +**Q: DPML与纯Markdown相比有什么优势？** +A: DPML提供了语义结构，使提示词的不同部分（思考、执行等）有明确区分，便于解析和处理，同时保留了Markdown的灵活性。 + +**Q: 如何在DPML中引用外部资源？** +A: 可以通过标签属性引用外部资源，如``，或使用特定的资源引用语法（参见资源引用协议）。 + +**Q: DPML的解析器需要特殊实现吗？** +A: DPML可以通过组合现有的XML解析器和Markdown解析器实现，先解析XML结构，再处理各标签内的Markdown内容。 \ No newline at end of file diff --git a/protocol/pattern/protocol-pattern-template.md b/protocol/pattern/protocol-pattern-template.md new file mode 100644 index 0000000..234c053 --- /dev/null +++ b/protocol/pattern/protocol-pattern-template.md @@ -0,0 +1,158 @@ +# 模式协议定义模板 + +> **TL;DR:** 本文档提供了定义PromptX模式协议的标准模板，包含语法、语义、约束和示例等关键要素，确保协议定义的一致性和完整性。 + +## 🧠 模式协议定义框架 + +模式协议是PromptX中最基础的表达规则集，定义了"如何表达"的基本语法和语义。本模板提供了定义模式协议的标准结构。 + +### 基本信息部分 + +```markdown +# [协议名称] 模式协议 + +> **TL;DR:** [一句话描述协议的核心目的和价值] + +## 🔍 协议概述 + +**协议名称:** [正式名称] +**版本:** [版本号，如1.0.0] + + +### 目的与范围 + +[详细描述此协议的目的、解决的问题和适用范围] + +### 相关协议 + +[列出与本协议相关的其他协议及其关系] +``` + +### 语法规则部分 + +```markdown +## 📝 语法规则 + +### 形式化定义 + +```ebnf +[使用EBNF或类似形式语言描述语法] +``` + +### 词法元素 + +| 元素 | 形式 | 描述 | +|------|------|------| +| [元素名] | [表示形式] | [简要描述] | +| ... | ... | ... | + +### 组合规则 + +1. [规则1] +2. [规则2] +3. ... +``` + +### 语义定义部分 + +```markdown +## 🧩 语义定义 + +### 核心概念 + +| 概念 | 定义 | 示例 | +|------|------|------| +| [概念1] | [定义描述] | [示例] | +| ... | ... | ... | + +### 解释规则 + +[详细说明如何解释协议元素，以及解释过程中的优先级或特殊情况] +``` + +### 约束与验证部分 + +```markdown +## ✅ 约束与验证 + +### 必要约束 + +1. [约束1] +2. [约束2] +3. ... + +### 验证规则 + +[说明如何验证协议实例的正确性] + +### 错误处理 + +[说明遇到错误时应如何处理] +``` + +### 扩展机制部分 + +```markdown +## 🔄 扩展机制 + +### 扩展点 + +[描述协议可以被扩展的方式和位置] + +### 扩展规则 + +[定义创建扩展时必须遵循的规则] + +### 扩展示例 + +[提供扩展的具体示例] +``` + +### 使用示例部分 + +```markdown +## 📋 使用示例 + +### 有效示例 + +``` +[提供3-5个有效使用的示例] +``` + +### 无效示例 + +``` +[提供2-3个无效使用的示例及错误原因] +``` +``` + +### 最佳实践部分 + +```markdown +## 💡 最佳实践 + +1. [最佳实践1] +2. [最佳实践2] +3. ... + +### 常见问题 + +**Q: [常见问题1]** +A: [问题解答] + +**Q: [常见问题2]** +A: [问题解答] +``` + +## 📊 协议定义检查清单 + +创建新的模式协议时，请确保包含以下内容： + +- [ ] 基本信息完整（名称、版本、状态等） +- [ ] 目的和范围清晰定义 +- [ ] 语法规则使用形式化方法描述 +- [ ] 语义定义完整且示例充分 +- [ ] 约束和验证规则明确 +- [ ] 扩展机制详细说明 +- [ ] 提供充分的有效和无效示例 +- [ ] 包含最佳实践和常见问题解答 \ No newline at end of file