添加初始文件结构
This commit is contained in:
sean
235
protocol/pattern/dpml-resource.protocol.md
Normal file
235
protocol/pattern/dpml-resource.protocol.md
Normal file
@ -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<ument>.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协议处理
|
||||
257
protocol/pattern/dpml.protocol.md
Normal file
257
protocol/pattern/dpml.protocol.md
Normal file
@ -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 '>' | '<' 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文本 *)
|
||||
```
|
||||
|
||||
### 词法元素
|
||||
|
||||
| 元素 | 形式 | 描述 |
|
||||
|------|------|------|
|
||||
| 标签 | `<tag>...</tag>` | 定义语义单元，如`<thinking>`,`<executing>` |
|
||||
| 自闭合标签 | `<tag />` | 无内容的标签，如`<import />` |
|
||||
| 属性 | `property="value"` | 标签配置信息，如`type="analysis"` |
|
||||
| 内容 | Markdown格式文本 | 标签内的实际提示词文本 |
|
||||
| 注释 | `<!-- comment -->` | 协议注释，不作为提示词内容 |
|
||||
|
||||
### 组合规则
|
||||
|
||||
1. 标签可以嵌套，形成层次结构
|
||||
2. 一个标签可以有多个属性，属性名在同一标签中不能重复
|
||||
3. 标签必须正确闭合，要么是配对标签`<tag></tag>`，要么是自闭合标签`<tag/>`
|
||||
4. 内容部分可以是纯Markdown文本，也可以包含其他标签
|
||||
5. 根元素推荐使用`<prompt>`，但不强制要求
|
||||
|
||||
## 🧩 语义定义
|
||||
|
||||
### 核心概念
|
||||
|
||||
| 概念 | 定义 | 示例 |
|
||||
|------|------|------|
|
||||
| 提示单元 | 由标签定义的语义完整的提示组件 | `<thinking>分析问题...</thinking>` |
|
||||
| 属性修饰 | 通过属性细化提示单元的行为特性 | `<executing priority="high">` |
|
||||
| 内容表达 | 使用Markdown表达的实际提示文本 | `# 步骤\n1. 首先...` |
|
||||
| 组合提示 | 多个提示单元组合形成完整提示 | `<thinking>...</thinking><executing>...</executing>` |
|
||||
|
||||
### 解释规则
|
||||
|
||||
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. 自定义标签应使用命名空间前缀：`<ns:tag>`
|
||||
2. 自定义属性可直接添加，但建议使用命名空间：`ns:property="value"`
|
||||
3. 内容增强应使用明确的语法标记，避免与Markdown冲突
|
||||
4. 扩展必须向下兼容，标准解析器应能忽略无法理解的扩展而不中断处理
|
||||
|
||||
### 扩展示例
|
||||
|
||||
```xml
|
||||
<!-- 命名空间定义 -->
|
||||
<prompt xmlns:ai="https://promptx.ai/ns/ai">
|
||||
<!-- 自定义标签 -->
|
||||
<ai:model type="gpt4">
|
||||
<!-- 标准标签 -->
|
||||
<thinking>
|
||||
# 分析方法
|
||||
使用**系统思维**方法
|
||||
</thinking>
|
||||
|
||||
<!-- 自定义属性 -->
|
||||
<executing ai:temperature="0.7">
|
||||
执行步骤...
|
||||
</executing>
|
||||
</ai:model>
|
||||
</prompt>
|
||||
```
|
||||
|
||||
## 📋 使用示例
|
||||
|
||||
### 有效示例
|
||||
|
||||
**1. 基本思考-执行流程**
|
||||
```
|
||||
<prompt>
|
||||
<thinking type="analysis">
|
||||
# 问题分析
|
||||
这是一个**数据处理**问题，需要考虑：
|
||||
1. 数据格式转换
|
||||
2. 性能优化
|
||||
</thinking>
|
||||
|
||||
<executing>
|
||||
# 执行步骤
|
||||
1. 首先读取输入文件
|
||||
2. 应用转换算法
|
||||
3. 输出结果到目标位置
|
||||
|
||||
确保全程**记录日志**以便调试。
|
||||
</executing>
|
||||
</prompt>
|
||||
```
|
||||
|
||||
**2. 带属性的复杂结构**
|
||||
```
|
||||
<prompt>
|
||||
<context type="background">
|
||||
# 项目背景
|
||||
客户需要一个数据可视化dashboard。
|
||||
</context>
|
||||
|
||||
<thinking type="design" priority="high">
|
||||
# 设计思路
|
||||
采用模块化设计，分离数据层和视图层。
|
||||
|
||||
<concept id="arch" domain="frontend">
|
||||
## 架构概念
|
||||
使用React + D3.js组合
|
||||
</concept>
|
||||
</thinking>
|
||||
|
||||
<executing steps="3">
|
||||
# 实现步骤
|
||||
1. 搭建基础框架
|
||||
2. 实现数据连接器
|
||||
3. 开发可视化组件
|
||||
</executing>
|
||||
</prompt>
|
||||
```
|
||||
|
||||
**3. 资源引用**
|
||||
```
|
||||
<prompt>
|
||||
<resource type="reference" src="docs/api-spec.md">
|
||||
参考API规范文档
|
||||
|
||||
API端点定义在源码的25-35行
|
||||
</resource>
|
||||
|
||||
<thinking>
|
||||
基于API规范进行设计...
|
||||
</thinking>
|
||||
</prompt>
|
||||
```
|
||||
|
||||
### 无效示例
|
||||
|
||||
**1. 标签未闭合**
|
||||
```
|
||||
<prompt>
|
||||
<thinking>
|
||||
思考内容...
|
||||
<!-- 缺少</thinking>标签 -->
|
||||
|
||||
<executing>
|
||||
执行步骤...
|
||||
</executing>
|
||||
</prompt>
|
||||
```
|
||||
错误原因：`<thinking>`标签未正确闭合
|
||||
|
||||
**2. 属性格式错误**
|
||||
```
|
||||
<prompt>
|
||||
<thinking type=analysis>
|
||||
思考内容...
|
||||
</thinking>
|
||||
</prompt>
|
||||
```
|
||||
错误原因：属性值缺少双引号，应为`type="analysis"`
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
1. **语义清晰度**：选择表意明确的标签名，让提示结构一目了然
|
||||
2. **适度分层**：合理使用嵌套结构，避免过深的层次导致可读性下降
|
||||
3. **内容聚焦**：每个标签内容应关注单一职责，避免功能混杂
|
||||
4. **属性合理性**：只使用必要的属性，避免过度配置
|
||||
5. **一致性**：在整个项目中保持一致的DPML结构风格
|
||||
|
||||
### 常见问题
|
||||
|
||||
**Q: DPML与纯Markdown相比有什么优势？**
|
||||
A: DPML提供了语义结构，使提示词的不同部分（思考、执行等）有明确区分，便于解析和处理，同时保留了Markdown的灵活性。
|
||||
|
||||
**Q: 如何在DPML中引用外部资源？**
|
||||
A: 可以通过标签属性引用外部资源，如`<resource src="path/to/file">`，或使用特定的资源引用语法（参见资源引用协议）。
|
||||
|
||||
**Q: DPML的解析器需要特殊实现吗？**
|
||||
A: DPML可以通过组合现有的XML解析器和Markdown解析器实现，先解析XML结构，再处理各标签内的Markdown内容。
|
||||
158
protocol/pattern/protocol-pattern-template.md
Normal file
158
protocol/pattern/protocol-pattern-template.md
Normal file
@ -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: [问题解答]
|
||||
```
|
||||
|
||||
## 📊 协议定义检查清单
|
||||
|
||||
创建新的模式协议时，请确保包含以下内容：
|
||||
|
||||
- [ ] 基本信息完整（名称、版本、状态等）
|
||||
- [ ] 目的和范围清晰定义
|
||||
- [ ] 语法规则使用形式化方法描述
|
||||
- [ ] 语义定义完整且示例充分
|
||||
- [ ] 约束和验证规则明确
|
||||
- [ ] 扩展机制详细说明
|
||||
- [ ] 提供充分的有效和无效示例
|
||||
- [ ] 包含最佳实践和常见问题解答
|
||||
Reference in New Issue
Block a user