diff --git a/protocol/README.md b/protocol/README.md new file mode 100644 index 0000000..ef7bf11 --- /dev/null +++ b/protocol/README.md @@ -0,0 +1,118 @@ +# PromptX 协议文档 + +> **TL;DR:** PromptX协议体系包含基础协议定义和最佳实践指南，为不同角色（框架开发者、提示词开发者、提示词理解者）提供相应的参考资料。 + +## 目录结构 + +``` +protocol/ +├── base/ # 基础协议定义 - 语法和语义 +│ ├── thought.protocol.md +│ ├── execution.protocol.md +│ ├── resource.protocol.md +│ ├── memory.protocol.md +│ └── ... +├── practice/ # 最佳实践指南 - 实际应用建议和示例 +│ ├── thought-best-practice.md +│ ├── execution-best-practice.md +│ ├── resource-best-practice.md +│ ├── memory-best-practice.md +│ └── ... +├── template/ # 协议模板 - 用于创建新协议 +│ ├── protocol-pattern-template.md +│ ├── protocol-application-template.md +│ └── ... +└── README.md # 本文件 +``` + +## 角色定义与关注点 + +### 1. 框架开发者 + +**定义**：负责设计和维护DPML协议体系本身的开发人员。 + +**目标**： +- 设计一致且可扩展的协议体系 +- 保证协议间的互操作性 +- 优化协议的表达能力和效率 + +**应关注内容**： +- ✅ `base/` 所有协议定义 +- ✅ `practice/` 所有最佳实践 +- ✅ `template/` 所有协议模板 +- ✅ 协议之间的依赖和互操作 + +### 2. 提示词开发者 + +**定义**：使用DPML框架开发具体提示词的工程师或设计师。 + +**目标**： +- 设计高质量、结构化的提示词 +- 优化提示词的效果和性能 +- 复用现有协议和最佳实践 + +**应关注内容**： +- ✅ `base/` 相关协议的语法和语义 +- ✅ `practice/` 相关协议的最佳实践和示例 +- ❌ 协议内部实现细节 + +### 3. 提示词理解者 + +**定义**：需要解析和执行DPML结构化提示词的系统或组件（如AI模型、解析器等）。 + +**目标**： +- 准确理解提示词的语法和语义 +- 按预期执行提示词指令 + +**应关注内容**： +- ✅ `base/` 协议的语法定义和语义说明 +- ❌ 最佳实践和设计建议 +- ❌ 协议模板和开发方法 + +## 文档类型说明 + +### 协议文档 (`base/*.protocol.md`) + +协议文档定义了"**是什么**"和"**如何理解**"： +- 语法定义：标签结构、属性、嵌套规则等 +- 语义说明：各元素的含义和解释规则 +- 子标签语义：子标签的功能和互操作方式 + +这些文档面向**所有角色**，但主要服务于**提示词理解者**，提供基础的语法和语义规范。 + +### 最佳实践文档 (`practice/*-best-practice.md`) + +最佳实践文档探讨"**怎么用**"和"**用得更好**"： +- 设计建议：推荐的使用方法和模式 +- 风格指南：推荐的表达风格和格式 +- 实际示例：常见用例的具体实现 + +这些文档主要面向**提示词开发者**，帮助他们创建高质量的提示词。 + +### 模板文档 (`template/*.md`) + +模板文档提供了"**如何创建新协议**"的指导： +- 结构模板：新协议的标准结构 +- 内容要求：各节应包含的内容 +- 验证清单：完整性与一致性检查 + +这些文档专门面向**框架开发者**，用于扩展协议体系。 + +## 使用指南 + +### 作为框架开发者 + +1. 参考 `template/` 下的模板创建新协议 +2. 确保新协议与现有协议体系一致 +3. 同时提供协议定义和最佳实践文档 + +### 作为提示词开发者 + +1. 首先阅读相关协议的语法和语义 (`base/`) +2. 参考最佳实践和示例 (`practice/`) +3. 按协议规范构建提示词 + +### 作为提示词理解者 + +1. 重点关注协议的语法定义和语义说明 (`base/`) +2. 按规范解析和处理提示词 \ No newline at end of file diff --git a/protocol/base/resource.protocol.md b/protocol/base/resource.protocol.md index b5c2f56..17863e9 100644 --- a/protocol/base/resource.protocol.md +++ b/protocol/base/resource.protocol.md @@ -41,6 +41,18 @@ markdown_content ::= (* 任何有效的Markdown文本，包括代码块、表格 ## 🧩 语义说明 +### 子标签语义 + +resource标签包含两个核心子标签，用于定义资源协议的具体内容： + +- **location**：定义该资源协议的路径规则。通常采用EBNF形式化语法描述路径结构，并可包含示例说明。 +- **params**：定义该资源协议支持的查询参数。通常采用表格形式列出参数名称、类型、描述和用法示例。 + +location和params子标签共同构成资源协议的完整定义，前者规定了资源的定位方式，后者规定了资源的访问选项。这两部分内容决定了如何解析和处理资源引用。 + +### `@` 引用协议 + + resource标签定义了一个资源协议，指定了如何使用`@`符号作为统一入口，遵循以下核心语法规则： ```ebnf @@ -109,98 +121,4 @@ query_params ::= '?' param_name '=' param_value {'&' param_name '=' param_value} 3. 查询参数应用于资源加载后的处理阶段，不影响资源的基本定位 4. 相对路径解析基于当前上下文的工作目录或基础路径 -## 💡 最佳实践 -以下是使用resource标签的一些推荐做法： - -### 资源路径设计 - -资源路径设计应遵循以下原则： -- 使用直观、符合惯例的路径格式 -- 支持绝对路径和相对路径 -- 适当使用通配符增强灵活性 -- 路径分隔符应统一使用`/` - -### 查询参数设计 - -查询参数设计应考虑以下因素： -- 参数名称应清晰表达其功能 -- 参数值格式应明确定义 -- 常见操作应有对应的参数支持（如范围指定、格式转换等） -- 参数组合应有明确的优先级规则 - -### 资源引用最佳实践 - -1. 使用最合适的协议名称表示资源类型，提高语义明确性 -2. 嵌套引用时，如果清晰度很重要，使用完整形式（带内部@符号） -3. 如果简洁性更重要，则使用简写形式（省略内部@符号） -4. 保持资源路径的相对引用，以提高提示词的可移植性 -5. 合理使用通配符，避免过于宽泛的匹配模式 -6. 使用查询参数进行资源过滤，而不是在提示词中手动处理 -7. 避免过深的嵌套引用，建议不超过3层，保持可读性 - -### 表达风格推荐 - -- **location**: 优先使用EBNF格式正式描述语法规则，辅以简洁示例 -- **params**: 使用表格形式列出参数，清晰展示名称、类型、描述和示例 - -## 📋 使用示例 - -### 自定义协议示例 - -以下示例展示了如何定义自定义资源协议： - - - - # 路径规则 (EBNF) - - ```ebnf - memory_path ::= [namespace '/'] memory_key - namespace ::= (letter | digit | '_' | '-')+ - memory_key ::= (letter | digit | '_' | '-' | '.')+ - ``` - - ## 示例 - - @memory://user_preferences - - @memory://session/history - - @memory://system/config - - - - # 查询参数 - - | 参数名 | 类型 | 描述 | 示例 | - |-------|------|------|------| - | ttl | 数字 | 生存时间(秒) | ?ttl=3600 | - | default | 字符串 | 默认值 | ?default=empty | - | type | 字符串 | 值类型 | ?type=json | - - - - - - # 路径规则 (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 - - - - # 查询参数 - - | 参数名 | 类型 | 描述 | 示例 | - |-------|------|------|------| - | mode | 字符串 | 上下文模式 | ?mode=read 或 ?mode=write | - | scope | 字符串 | 访问范围 | ?scope=local 或 ?scope=global | - | format | 字符串 | 返回格式 | ?format=json | - - \ No newline at end of file diff --git a/protocol/practice/resource-best-practice.md b/protocol/practice/resource-best-practice.md new file mode 100644 index 0000000..155321a --- /dev/null +++ b/protocol/practice/resource-best-practice.md @@ -0,0 +1,101 @@ +# DPML资源模式提示词框架最佳实践 + +> **TL;DR:** 本文档提供DPML资源模式提示词框架的最佳实践指南，包括资源路径设计、查询参数设计、引用建议和具体示例。 + +## 💡 最佳实践 + +### 资源路径设计 + +资源路径设计应遵循以下原则： +- 使用直观、符合惯例的路径格式 +- 支持绝对路径和相对路径 +- 适当使用通配符增强灵活性 +- 路径分隔符应统一使用`/` + +### 查询参数设计 + +查询参数设计应考虑以下因素： +- 参数名称应清晰表达其功能 +- 参数值格式应明确定义 +- 常见操作应有对应的参数支持（如范围指定、格式转换等） +- 参数组合应有明确的优先级规则 + +### 资源引用最佳实践 + +1. 使用最合适的协议名称表示资源类型，提高语义明确性 +2. 嵌套引用时，如果清晰度很重要，使用完整形式（带内部@符号） +3. 如果简洁性更重要，则使用简写形式（省略内部@符号） +4. 保持资源路径的相对引用，以提高提示词的可移植性 +5. 合理使用通配符，避免过于宽泛的匹配模式 +6. 使用查询参数进行资源过滤，而不是在提示词中手动处理 +7. 避免过深的嵌套引用，建议不超过3层，保持可读性 + +### 表达风格推荐 + +- **location**: 优先使用EBNF格式正式描述语法规则，辅以简洁示例 +- **params**: 使用表格形式列出参数，清晰展示名称、类型、描述和示例 + +## 📋 使用示例 + +### 自定义协议示例 + +以下示例展示了如何定义自定义资源协议： + +```xml + + + # 路径规则 (EBNF) + + ```ebnf + memory_path ::= [namespace '/'] memory_key + namespace ::= (letter | digit | '_' | '-')+ + memory_key ::= (letter | digit | '_' | '-' | '.')+ + ``` + + ## 示例 + - @memory://user_preferences + - @memory://session/history + - @memory://system/config + + + + # 查询参数 + + | 参数名 | 类型 | 描述 | 示例 | + |-------|------|------|------| + | ttl | 数字 | 生存时间(秒) | ?ttl=3600 | + | default | 字符串 | 默认值 | ?default=empty | + | type | 字符串 | 值类型 | ?type=json | + + +``` + +```xml + + + # 路径规则 (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 + + + + # 查询参数 + + | 参数名 | 类型 | 描述 | 示例 | + |-------|------|------|------| + | mode | 字符串 | 上下文模式 | ?mode=read 或 ?mode=write | + | scope | 字符串 | 访问范围 | ?scope=local 或 ?scope=global | + | format | 字符串 | 返回格式 | ?format=json | + + +``` \ No newline at end of file diff --git a/protocol/template/protocol-application-template.md b/protocol/template/protocol-application-template.md deleted file mode 100644 index ff63fa8..0000000 --- a/protocol/template/protocol-application-template.md +++ /dev/null @@ -1,93 +0,0 @@ -# [标签名] 应用协议 - -> **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/template/protocol-framework-template.md b/protocol/template/protocol-framework-template.md new file mode 100644 index 0000000..ccb761f --- /dev/null +++ b/protocol/template/protocol-framework-template.md @@ -0,0 +1,58 @@ +# DPML{协议名称}模式提示词框架 + +> **TL;DR:** DPML{协议名称}模式提示词框架定义了{一句话描述协议核心功能和价值}，{补充说明特点或独特价值}。 + +### 目的与功能 + +DPML{协议名称}模式提示词框架{详细说明此框架的目的}，它的主要功能是： +- {功能点1} +- {功能点2} +- {功能点3} +- {功能点4} + +## 📝 语法定义 + +```ebnf +(* EBNF形式化定义 *) +{主标签}_element ::= '<{主标签}' attributes? '>' content '' +attributes ::= (' ' attribute)+ | '' +attribute ::= name '="' value '"' +name ::= [a-zA-Z][a-zA-Z0-9_-]* +value ::= [^"]* +content ::= (markdown_content | {子标签1}_element | {子标签2}_element | ... )+ + +{子标签1}_element ::= '<{子标签1}' attributes? '>' markdown_content '' +{子标签2}_element ::= '<{子标签2}' attributes? '>' markdown_content '' +... + +markdown_content ::= (* 任何有效的Markdown文本，可包含特定语法元素 *) +``` + +## 🧩 语义说明 + +{主标签}标签表示{对主标签的核心语义描述}。标签内容可以包含{数量}种不同{类型}的子标签，每个子标签都有明确的语义： + +- **{子标签1}**: {子标签1的语义描述} +- **{子标签2}**: {子标签2的语义描述} +- **{子标签3}**: {子标签3的语义描述} +- ... + +{这些子标签的组合关系、层次结构或互操作方式} + +{如有必要，对标签语义的补充说明} + +### {补充语义说明1，如 "优先级关系"、"组合规则" 等} + +{详细描述补充语义内容} + +1. **{项目1}** - {描述} +2. **{项目2}** - {描述} +3. ... + +{进一步说明这些补充语义的重要性或应用场景} + +### {补充语义说明2，如 "子标签的可选性" 等} + +{详细描述补充语义内容} + +{说明这些补充语义如何影响理解和使用} \ No newline at end of file diff --git a/protocol/template/protocol-pattern-template.md b/protocol/template/protocol-pattern-template.md deleted file mode 100644 index 234c053..0000000 --- a/protocol/template/protocol-pattern-template.md +++ /dev/null @@ -1,158 +0,0 @@ -# 模式协议定义模板 - -> **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