loopforge 1.8.0 → 1.15.1

package/skills/prompt-techniques/references/few-shot.md

@@ -1,174 +1,174 @@
-# Few-Shot Prompting
-
-## Purpose
-
-适合已有示例、需要复用格式、标签或表达风格的任务。通过提供 1-5 组输入/输出示例让模型理解任务模式和输出风格。用于标准 CRUD 模块、常规单元测试等有固定范式的任务。
-
-## Input Requirements
-
-- **用户任务**：说明希望模型完成什么任务。
-- **输出格式**：说明最终回答的结构、字段、长度、语言或代码格式。
-- **可选少样本示例**：用户可以在第一次请求中直接提供 1~5 组 `输入 -> 期望输出`，或 `输入 -> 推理过程 -> 期望输出`，用于展示任务模式、判断依据和输出风格。
-- **可选信息**：角色设定、待处理文本、约束条件、目标用户或使用场景。
-
-示例不是必需项。若用户已经附上案例，直接吸收案例中的输入输出映射和输出风格；若未检测到案例，不要追问或中断流程，按零样本提示生成，并在生成结果中简短说明"未检测到用户案例，因此按零样本提示生成"。不要替用户编造隐藏思维链；只保存用户明确提供或可公开展示的推理摘要。
-
-## Recommended JSON Input
-
-```json
-{
-  "task": "从客服对话中抽取客户诉求和情绪",
-  "role": "你是一名严谨的信息抽取提示词设计师",
-  "examples": [
-    {
-      "input": "客户：我等了三天还没收到退款。",
-      "reasoning": "用户关注退款进度，表达等待过久带来的不满。",
-      "output": "{\"诉求\":\"查询退款进度\",\"情绪\":\"不满\"}"
-    }
-  ],
-  "target_input": "{用户输入的客服对话}",
-  "output_format": "仅输出 JSON，字段为 诉求、情绪。",
-  "constraints": ["不要输出解释", "字段缺失时填 null"],
-  "persist_sample": true
-}
-```
-
-## Case Injection Pipeline
-
-### Step 1: 检测（Detect）
-
-检查用户请求中是否包含 `examples` 字段或自然语言描述的输入→输出样例。识别示例中的输入输出映射和输出风格。
-
-### Step 2: 校验（Validate）
-
-- 如果提供 `examples`，校验数量为 1~5。
-- 每组必须有非空 `input` 和 `output`；`reasoning` 可选。
-- 示例应与用户任务同类型，避免混入无关领域案例。
-- 没有示例时不要臆造示例，按零样本生成即可。
-
-### Step 3: 格式化（Format）
-
-将示例格式化为清晰的结构，插入生成 Prompt 的示例区：
-
-```
-示例 1:
-输入: {input}
-推理过程: {reasoning}  （可选，无则省略此块）
-输出: {output}
-
-示例 2:
-输入: ...
-输出: ...
-```
-
-### Step 4: 注入（Inject）
-
-将格式化后的示例插入到最终的 Prompt 中，位于任务指令之后、目标输入之前。在 Prompt 末尾放置目标输入，要求模型按示例风格输出。
-
-## Method Steps
-
-1. 从用户提供的示例中提取输入到输出的映射规则。
-2. 在最终 Prompt 中包含 1-5 组格式化的示例（推荐 2-3 个）。
-3. 示例应展示：输入 → 期望输出 的完整对应关系。
-4. 在 Prompt 末尾放置目标输入，要求模型按示例风格输出。
-5. 如果用户未提供示例，退回 zero-shot 并简短说明。
-
-## Dynamic Sample Persistence
-
-> **Status: Future feature — not yet implemented.** The `persist_sample: true` flag
-> and sample library described below are a planned enhancement. Currently, samples
-> live only within the session — they are not persisted across sessions by any
-> script. The checkpoint.py + hydrate.py vault stores prompts and summaries, not
-> raw input→output examples.
-
-当用户明确要求"把这个例子保存下来""加入样例库"或 payload 设置 `persist_sample: true` 时，将本轮示例追加到样本库。追加条目应包含：
-
-- 任务、角色、输出格式、待处理内容占位和约束。
-- 1~5 组用户示例（输入、可选推理过程、输出）。
-- 本轮生成的完整少样本 Prompt。
-
-若示例里包含隐私、密钥、真实身份信息或用户没有明确要求持久化，先脱敏或仅保存在 session 临时区。追加而非覆盖已有样本。
-
-## When to Use
-
-- 任务有固定的输入输出模式（如代码转换、格式化、分类）。
-- 用户能提供高质量示例。
-- 输出风格或格式需要严格遵循约定。
-- 常见场景：标准 CRUD 模块、单元测试编写、代码风格转换、文本分类。
-
-## Example Use Cases
-
-- "根据这些示例，把后面的函数也写成同样的风格"
-- "参考前两个单元测试，为这个新函数写测试"
-- "模仿这两个 API 端点的写法，实现第三个端点"
-
-## Prompt Output Template
-
-当你用 Few-Shot 技术生最终提示词时，**必须**按以下 8 节骨架输出。技术特定的第 5 节格式要求见下方详细说明。
-
-### 章节骨架
-
-| # | 章节 | 必需 | 说明 |
-|---|------|------|------|
-| 1 | 角色 | ✓ | 领域专家 + 技术栈，如"你是一名资深 Go 后端工程师，精通 Gin + MySQL" |
-| 2 | 任务 | ✓ | 一句话说清要做什么 |
-| 3 | 输入 | ✓ | 目标数据/代码/模块的描述 |
-| 4 | 输出格式 | ✓ | 编号列表，每项对应下方具体实现的子节。如"1. DDL, 2. API接口, 3. 校验逻辑, 4. 业务代码, 5. 单元测试" |
-| 5 | **格式参考示例（Few-Shot）** | ✓ | 见下方详细格式规范 |
-| 6 | 具体实现要求 | ✓ | 按输出格式的编号逐节展开，含代码示例、DDL、API 示例等 |
-| 7 | 硬约束 | ✓ | 编号列表，含技术栈、范围值、架构限制等 |
-| 8 | 生成要求 | ✓ | 编号列表，最终验收标准 |
-
-### 第 5 节格式规范：格式参考示例（Few-Shot）
-
-这是本技术最关键的章节。必须包含：
-
-**A. 2-3 组输入→输出对**，每组格式：
-
-```
-### 示例 N：[场景描述]
-
-**输入：**
-[具体的输入数据，如 API 请求体、代码片段、数据结构]
-
-**输出：**
-[对应的期望输出，如 API 响应、代码结果、处理结果]
-
-**映射规则：** [一句话解释输入如何变成输出]
-```
-
-**B. 输入→输出映射规则总结框**：一个 ASCII 框图，汇总所有示例中提取的通用规则。
-
-格式范本（来自 MCP 黄金标准 `prompt_02_vital_signs`）：
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    数值校验映射规则                               │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  输入值 → 判断1: 是否在有效范围内？                              │
-│    ├─ 否 → 返回错误码 + 拒绝录入                                 │
-│    └─ 是 → 判断2: 是否在正常范围内？                             │
-│         ├─ 是 → status: "normal"                                │
-│         └─ 否 → status: "abnormal" + warning                    │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### 质量自检
-
-- [ ] 示例是**任务领域的真实输入→输出对**，不是"提示词设计的元示例"
-- [ ] 每组示例有明确的映射规则说明
-- [ ] 映射规则总结框放在所有示例之后
-- [ ] 输出格式的编号与具体实现要求的子节编号一一对应
-- [ ] 硬约束≥8 条，含技术栈、数值范围、架构限制
-
-## Notes
-
-- 少样本示例如果存在，必须体现"输入如何变成输出"，不要只写输出格式骨架。
-- "推理过程"应是可公开的简要判断依据，用来帮助样例复用；不要保存隐藏思维链、敏感信息或不可公开的内部分析。
-- 示例应与用户任务同类型，避免混入无关领域案例；没有示例时不要臆造示例，按零样本生成即可。
-- 示例数量优先 2~3 个；任务简单可用 1 个，格式复杂可用 4~5 个。
-- 输出格式要量化，如字段名、顺序、句数、Markdown 样式或 JSON Schema。
-- 生成的 Prompt 中保留 `{用户输入的文本}` 等占位符，除非用户已经提供真实待处理内容。
-- 案例仅供参考，不可直接复制为用户任务的生成内容。
+# Few-Shot Prompting
+
+## Purpose
+
+适合已有示例、需要复用格式、标签或表达风格的任务。通过提供 1-5 组输入/输出示例让模型理解任务模式和输出风格。用于标准 CRUD 模块、常规单元测试等有固定范式的任务。
+
+## Input Requirements
+
+- **用户任务**：说明希望模型完成什么任务。
+- **输出格式**：说明最终回答的结构、字段、长度、语言或代码格式。
+- **可选少样本示例**：用户可以在第一次请求中直接提供 1~5 组 `输入 -> 期望输出`，或 `输入 -> 推理过程 -> 期望输出`，用于展示任务模式、判断依据和输出风格。
+- **可选信息**：角色设定、待处理文本、约束条件、目标用户或使用场景。
+
+示例不是必需项。若用户已经附上案例，直接吸收案例中的输入输出映射和输出风格；若未检测到案例，不要追问或中断流程，按零样本提示生成，并在生成结果中简短说明"未检测到用户案例，因此按零样本提示生成"。不要替用户编造隐藏思维链；只保存用户明确提供或可公开展示的推理摘要。
+
+## Recommended JSON Input
+
+```json
+{
+  "task": "从客服对话中抽取客户诉求和情绪",
+  "role": "你是一名严谨的信息抽取提示词设计师",
+  "examples": [
+    {
+      "input": "客户：我等了三天还没收到退款。",
+      "reasoning": "用户关注退款进度，表达等待过久带来的不满。",
+      "output": "{\"诉求\":\"查询退款进度\",\"情绪\":\"不满\"}"
+    }
+  ],
+  "target_input": "{用户输入的客服对话}",
+  "output_format": "仅输出 JSON，字段为 诉求、情绪。",
+  "constraints": ["不要输出解释", "字段缺失时填 null"],
+  "persist_sample": true
+}
+```
+
+## Case Injection Pipeline
+
+### Step 1: 检测（Detect）
+
+检查用户请求中是否包含 `examples` 字段或自然语言描述的输入→输出样例。识别示例中的输入输出映射和输出风格。
+
+### Step 2: 校验（Validate）
+
+- 如果提供 `examples`，校验数量为 1~5。
+- 每组必须有非空 `input` 和 `output`；`reasoning` 可选。
+- 示例应与用户任务同类型，避免混入无关领域案例。
+- 没有示例时不要臆造示例，按零样本生成即可。
+
+### Step 3: 格式化（Format）
+
+将示例格式化为清晰的结构，插入生成 Prompt 的示例区：
+
+```
+示例 1:
+输入: {input}
+推理过程: {reasoning}  （可选，无则省略此块）
+输出: {output}
+
+示例 2:
+输入: ...
+输出: ...
+```
+
+### Step 4: 注入（Inject）
+
+将格式化后的示例插入到最终的 Prompt 中，位于任务指令之后、目标输入之前。在 Prompt 末尾放置目标输入，要求模型按示例风格输出。
+
+## Method Steps
+
+1. 从用户提供的示例中提取输入到输出的映射规则。
+2. 在最终 Prompt 中包含 1-5 组格式化的示例（推荐 2-3 个）。
+3. 示例应展示：输入 → 期望输出 的完整对应关系。
+4. 在 Prompt 末尾放置目标输入，要求模型按示例风格输出。
+5. 如果用户未提供示例，退回 zero-shot 并简短说明。
+
+## Dynamic Sample Persistence
+
+> **Status: Future feature — not yet implemented.** The `persist_sample: true` flag
+> and sample library described below are a planned enhancement. Currently, samples
+> live only within the session — they are not persisted across sessions by any
+> script. The checkpoint.py + hydrate.py vault stores prompts and summaries, not
+> raw input→output examples.
+
+当用户明确要求"把这个例子保存下来""加入样例库"或 payload 设置 `persist_sample: true` 时，将本轮示例追加到样本库。追加条目应包含：
+
+- 任务、角色、输出格式、待处理内容占位和约束。
+- 1~5 组用户示例（输入、可选推理过程、输出）。
+- 本轮生成的完整少样本 Prompt。
+
+若示例里包含隐私、密钥、真实身份信息或用户没有明确要求持久化，先脱敏或仅保存在 session 临时区。追加而非覆盖已有样本。
+
+## When to Use
+
+- 任务有固定的输入输出模式（如代码转换、格式化、分类）。
+- 用户能提供高质量示例。
+- 输出风格或格式需要严格遵循约定。
+- 常见场景：标准 CRUD 模块、单元测试编写、代码风格转换、文本分类。
+
+## Example Use Cases
+
+- "根据这些示例，把后面的函数也写成同样的风格"
+- "参考前两个单元测试，为这个新函数写测试"
+- "模仿这两个 API 端点的写法，实现第三个端点"
+
+## Prompt Output Template
+
+当你用 Few-Shot 技术生最终提示词时，**必须**按以下 8 节骨架输出。技术特定的第 5 节格式要求见下方详细说明。
+
+### 章节骨架
+
+| # | 章节 | 必需 | 说明 |
+|---|------|------|------|
+| 1 | 角色 | ✓ | 领域专家 + 技术栈，如"你是一名资深 Go 后端工程师，精通 Gin + MySQL" |
+| 2 | 任务 | ✓ | 一句话说清要做什么 |
+| 3 | 输入 | ✓ | 目标数据/代码/模块的描述 |
+| 4 | 输出格式 | ✓ | 编号列表，每项对应下方具体实现的子节。如"1. DDL, 2. API接口, 3. 校验逻辑, 4. 业务代码, 5. 单元测试" |
+| 5 | **格式参考示例（Few-Shot）** | ✓ | 见下方详细格式规范 |
+| 6 | 具体实现要求 | ✓ | 按输出格式的编号逐节展开，含代码示例、DDL、API 示例等 |
+| 7 | 硬约束 | ✓ | 编号列表，含技术栈、范围值、架构限制等 |
+| 8 | 生成要求 | ✓ | 编号列表，最终验收标准 |
+
+### 第 5 节格式规范：格式参考示例（Few-Shot）
+
+这是本技术最关键的章节。必须包含：
+
+**A. 2-3 组输入→输出对**，每组格式：
+
+```
+### 示例 N：[场景描述]
+
+**输入：**
+[具体的输入数据，如 API 请求体、代码片段、数据结构]
+
+**输出：**
+[对应的期望输出，如 API 响应、代码结果、处理结果]
+
+**映射规则：** [一句话解释输入如何变成输出]
+```
+
+**B. 输入→输出映射规则总结框**：一个 ASCII 框图，汇总所有示例中提取的通用规则。
+
+格式范本（来自 MCP 黄金标准 `prompt_02_vital_signs`）：
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    数值校验映射规则                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  输入值 → 判断1: 是否在有效范围内？                              │
+│    ├─ 否 → 返回错误码 + 拒绝录入                                 │
+│    └─ 是 → 判断2: 是否在正常范围内？                             │
+│         ├─ 是 → status: "normal"                                │
+│         └─ 否 → status: "abnormal" + warning                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 质量自检
+
+- [ ] 示例是**任务领域的真实输入→输出对**，不是"提示词设计的元示例"
+- [ ] 每组示例有明确的映射规则说明
+- [ ] 映射规则总结框放在所有示例之后
+- [ ] 输出格式的编号与具体实现要求的子节编号一一对应
+- [ ] 硬约束≥8 条，含技术栈、数值范围、架构限制
+
+## Notes
+
+- 少样本示例如果存在，必须体现"输入如何变成输出"，不要只写输出格式骨架。
+- "推理过程"应是可公开的简要判断依据，用来帮助样例复用；不要保存隐藏思维链、敏感信息或不可公开的内部分析。
+- 示例应与用户任务同类型，避免混入无关领域案例；没有示例时不要臆造示例，按零样本生成即可。
+- 示例数量优先 2~3 个；任务简单可用 1 个，格式复杂可用 4~5 个。
+- 输出格式要量化，如字段名、顺序、句数、Markdown 样式或 JSON Schema。
+- 生成的 Prompt 中保留 `{用户输入的文本}` 等占位符，除非用户已经提供真实待处理内容。
+- 案例仅供参考，不可直接复制为用户任务的生成内容。