OpenCode 中文教程

Appearance

Prompt 工程规范 ​

本文档定义了 OpenCode 教程中提示词的编写规范，确保所有模板保持一致的高质量。

🎯 核心原则 ​

1. 结构化优先（Structure First） ​

每个模板必须包含明确的结构层次：

角色定义 → 任务说明 → 输入规范 → 输出规范 → 示例 → 约束条件

2. Few-shot 必备（Example-Driven） ​

复杂任务必须提供 1-2 个具体示例，让模型理解预期输入/输出格式。

3. 显式思维链（Chain of Thought） ​

对于推理类任务，明确引导"先分析，再输出"的步骤式思考。

4. 量化评估标准（Quantified Criteria） ​

任何评分/评估必须有明确的评分维度和每个分数段的定义。

5. 错误处理机制（Graceful Degradation） ​

模板应包含：输入不完整时如何处理、遇到歧义时如何澄清、超出能力范围时如何反馈。

6. 自检机制（Self-Verification） ​

复杂任务输出前进行自我检查，确保符合要求。

7. 占位符一致性（Consistent Placeholders） ​

全文档使用统一的占位符语法，清晰区分必填和选填。

📋 标准模板结构 ​

markdown
## 角色
你是[专业身份]，擅长[核心能力]。[额外的身份锚定描述]

## 任务
[清晰描述要完成的任务]

## 输入信息
### 必填项
- 变量名：【变量说明】

### 选填项
- 变量名：【变量说明?】（默认：xxx）

## 输出规范
按以下结构输出：
1. [输出项1]
2. [输出项2]
...

## 示例

### 输入
[具体输入示例]

### 输出
[对应的理想输出]

## 约束条件
- ✅ 应该：[正面行为]
- ❌ 避免：[负面行为]

## 自检清单
完成前确认：
- [ ] [检查项1]
- [ ] [检查项2]

## 错误处理
- 如果缺少关键信息，请先询问用户
- 如果任务超出范围，说明原因并建议替代方案

🏷️ 占位符规范 ​

语法 ​

类型语法示例
必填变量【变量名】【编程语言】
选填变量【变量名?】【框架?】
带默认值【变量名=默认值】【风格=轻松】
多选一【选项1/选项2/选项3】【玄幻/都市/言情】
文本块[粘贴区域描述][粘贴代码]

示例对比 ​

❌ 差的写法：

类型：玄幻/都市/言情
语言：语言
粘贴代码

✅ 好的写法：

类型：【玄幻/都市/言情/悬疑/科幻】
语言：【编程语言】

[粘贴代码]

📊 评分标准规范 ​

任何使用评分的模板，必须定义评分标准：

示例：代码质量评分 ​

分数可读性性能安全性测试覆盖
9-10命名清晰、注释完整O(n)或更优无漏洞>90%
7-8命名合理、关键注释O(n log n)低风险70-90%
5-6基本可读O(n²)中风险50-70%
<5难以理解O(n³)+高风险<50%

综合得分计算：可读性×0.3 + 性能×0.3 + 安全性×0.25 + 测试覆盖×0.15

👤 角色定义规范 ​

要素 ​

  1. 专业身份：你是谁
  2. 核心能力：擅长什么
  3. 服务对象：为谁服务（可选）
  4. 风格特点：工作风格（可选）

示例 ​

❌ 差的写法：

你是一个助手。

✅ 好的写法：

你是资深技术文档工程师，擅长将复杂代码解释得通俗易懂。
你的解释被初学者评价为"终于看懂了"。

⚖️ 约束条件规范 ​

使用 ✅ 和 ❌ 明确区分正面和负面行为：

markdown
## 约束条件
- ✅ 问题要具体到行号
- ✅ 每个问题都要有修复建议
- ✅ 肯定做得好的地方
- ❌ 避免主观偏好替代客观标准
- ❌ 避免只批评不给方案

🔧 错误处理规范 ​

每个模板都应该包含错误处理部分：

markdown
## 错误处理
- 如果信息不足，列出需要补充的信息并说明为什么需要
- 如果问题超出能力范围，说明并建议求助渠道
- 如果有多个独立问题，建议逐个处理

✅ 自检清单规范 ​

复杂任务应包含自检清单：

markdown
## 自检清单
完成前确认：
- [ ] 每个主角都有清晰的弧线
- [ ] 起承转合节奏合理
- [ ] 核心冲突能贯穿全文
- [ ] 亮点足以吸引目标读者

🤖 Agent/Skill description 规范 ​

结构模板 ​

yaml
description: |
  [一句话说明核心能力]
  提供：[该 Skill 包含的资源]
  适用：[触发场景1]、[触发场景2]
  不适用：[边界场景1]、[边界场景2]

示例 ​

❌ 差的写法：

yaml
description: 代码审查专家

✅ 好的写法：

yaml
description: |
  代码审查专家，专注安全漏洞、性能问题、代码质量。
  适用场景：PR 审查、代码健康检查、安全审计。
  不适用：代码生成、功能实现、测试编写。

📝 检查清单 ​

发布模板前，确认以下事项：

  • [ ] 有明确的角色定义
  • [ ] 输入信息区分必填/选填
  • [ ] 有完整的输出规范
  • [ ] 复杂任务有 Few-shot 示例
  • [ ] 评分类有量化标准
  • [ ] 有约束条件（✅/❌）
  • [ ] 有错误处理机制
  • [ ] 占位符语法统一
  • [ ] 无格式错误

相关资源 ​