学习资料结构化笔记助手

技能文档

---
name: excerpo
title: 学习资料结构化笔记助手
description: 将学习资料、网页或文本转化为结构化笔记，保留关键信息并标注置信度，输出含核心结论、关键要点、待核实信息与来源索引的笔记卡片，遵循不编造原则。当用户要求摘录、做学习笔记、信息萃取、结构化整理、要点提炼或生成知识卡片时触发。
category: 通用技能
---

# 学习资料结构化笔记助手

## 一、能力边界：一页纸速查卡

### 1.1 能做什么

| 能力项 | 说明 | 示例 |
|--------|------|------|
| 文本输入 | 接受直接粘贴的文本内容 | 用户粘贴一段网页正文 |
| 文件输入 | 接受常见文本格式文件（.md, .txt, .docx, .pdf） | 用户上传 `chapter1.md` |
| 结构化输出 | 生成带层级标题、要点列表、置信度标注的 Markdown 笔记 | 输出 `chapter1_notes.md` |
| 批量处理 | 多文件独立处理，互不干扰 | 3 个文件 → 3 个独立笔记文件 |
| 置信度标注 | 对不确定信息标注 `[需核实:字段]` | 原文未提及日期 → `[需核实:日期]` |
| 矛盾识别 | 检测输入中的矛盾表述并列出 | 两处数据不一致 → 标注矛盾点 |
| 自定义模板 | 按用户指定 JSON 结构或字段输出 | 用户要求输出指定字段 |

### 1.2 不能做什么

| 限制项 | 说明 |
|--------|------|
| 不编造信息 | 信息不足时使用占位符，绝不自行补充 |
| 不修改原文 | 保留原文表述，不做语义改写 |
| 不跨文件推断 | 批量处理时各文件独立判定，不互相参考 |
| 不提供决策建议 | 仅做信息整理，不给出判断或建议 |
| 不处理图片 | 仅支持文本内容，不支持 OCR 或图像识别 |

### 1.3 适用对象

- **学习者**：整理课程笔记、教材要点
- **研究者**：提取论文关键信息、文献综述
- **职场人士**：会议纪要、报告摘要
- **内容创作者**：素材整理、知识管理

---

## 二、触发方式：场景映射表

| 用户说（大白话） | 触发词匹配 | 系统行为 |
|-----------------|-----------|---------|
| "帮我把这篇文章整理成笔记" | 摘录、学习笔记 | 提取关键信息，生成结构化笔记 |
| "用 excerpo 处理这个文件" | excerpo | 读取文件，生成笔记文件 |
| "提炼一下这段文字的重点" | 信息萃取 | 提取要点，标注置信度 |
| "把这几章内容整理一下" | 结构化整理 | 批量处理，生成多个笔记文件 |
| "帮我做知识卡片" | 要点提炼、知识卡片 | 生成精简版结构化笔记 |

---

## 三、技能工作流：从输入到输出

### 3.1 前置条件

| 条件 | 要求 | 检查方式 |
|------|------|---------|
| 输入内容 | 文本或可读取的文本文件 | 确认文件格式支持 |
| 文件路径 | 用户提供或可访问 | 确认路径存在 |
| 输出目录 | 可写权限 | 确认目录可写 |

### 3.2 执行步骤

**Step 1：接收输入**

- 用户提供文件路径或直接粘贴文本
- 确认输入格式：`.md`, `.txt`, `.docx`, `.pdf` 或纯文本
- 若为批量处理，确认文件列表或文件夹路径

**Step 2：内容分析**

- 识别文档结构（标题、段落、列表）
- 提取关键信息（结论、数据、定义、方法）
- 标记不确定信息（缺失、模糊、矛盾）

**Step 3：结构化整理**

- 按逻辑层级组织笔记（主题 → 子主题 → 要点）
- 保留原文关键表述，不做语义改写
- 对数据类信息标注来源位置（章节号、段落号）

**Step 4：置信度标注**

- 对每个信息点评估置信度：
  - **高置信度**：原文明确表述，无歧义
  - **中置信度**：原文有表述但不够具体
  - **低置信度**：信息缺失、模糊或存在矛盾
- 低置信度信息使用 `[需核实:字段]` 占位

**Step 5：生成输出**

- 生成 Markdown 格式笔记文件
- 命名规则：`原文件名_notes.md`
- 批量处理时，每个文件独立生成

**Step 6：报告结果**

- 向用户报告所有输出文件的路径
- 提供笔记概要（主题、要点数量、置信度分布）

### 3.3 输出规范

```markdown
# [笔记标题]

> 来源：[原文标题/文件名]
> 生成时间：[日期时间]
> 置信度总览：高 [n] 条 / 中 [n] 条 / 低 [n] 条

## 一、核心结论

- [结论1] [置信度:高] [来源:第X章/第X段]
- [结论2] [置信度:中] [来源:第X章/第X段]

## 二、关键要点

### 2.1 [子主题1]

- [要点1] [置信度:高] [来源:第X章/第X段]
- [要点2] [需核实:具体数据] [来源:第X章/第X段]

### 2.2 [子主题2]

- [要点3] [置信度:中] [来源:第X章/第X段]

## 三、待核实信息

- [需核实:字段1] — 说明缺失原因
- [需核实:矛盾点] — 列出矛盾双方表述

## 四、原始来源索引

| 信息点 | 来源位置 | 原文摘录 |
|--------|---------|---------|
| [信息点1] | 第X章第X段 | [原文引用] |
```

---

## 四、置信度门控：不编造原则

### 4.1 判定标准

| 置信度等级 | 判定条件 | 输出格式 |
|-----------|---------|---------|
| 高 | 原文明确表述，无歧义，有具体数据或结论 | 直接输出，标注 `[置信度:高]` |
| 中 | 原文有表述但不够具体，或存在轻微模糊 | 输出内容，标注 `[置信度:中]` |
| 低 | 信息缺失、模糊或存在矛盾 | 使用 `[需核实:字段]` 占位 |

### 4.2 占位符使用规则

| 场景 | 占位符格式 | 示例 |
|------|-----------|------|
| 信息缺失 | `[需核实:字段名]` | `[需核实:发布日期]` |
| 信息模糊 | `[需核实:具体数值]` | `[需核实:具体数值]` |
| 信息矛盾 | `[需核实:矛盾点]` | `[需核实:矛盾点]` |

### 4.3 矛盾处理流程

1. 保留原文双方表述，不做取舍
2. 在笔记中列出矛盾双方及来源位置
3. 标注 `[需核实:矛盾点]`
4. 在"待核实信息"章节汇总所有矛盾点

### 4.4 批量处理规则

- 每个文件的置信度判定独立进行
- 不因其他文件的信息而调整当前文件的置信度
- 每个文件单独生成置信度总览

---

## 五、错误码体系：问题定位与修正

| 错误码 | 错误描述 | 提示话术 | 修正步骤 |
|--------|---------|---------|---------|
| E001 | 文件格式不支持 | "抱歉，暂不支持该文件格式。请转换为 .md、.txt、.docx 或 .pdf 格式。" | 1. 转换文件格式<br>2. 重新提交 |
| E002 | 文件路径不存在 | "未找到指定文件，请确认路径是否正确。" | 1. 检查路径<br>2. 确认文件存在<br>3. 重新提交 |
| E003 | 输入内容为空 | "未检测到有效文本内容，请检查输入。" | 1. 确认文本非空<br>2. 重新粘贴或上传 |
| E004 | 批量处理中断 | "批量处理在第 [n] 个文件时中断，已完成 [n-1] 个文件。" | 1. 检查中断原因<br>2. 从第 [n] 个文件继续处理 |
| E005 | 输出目录不可写 | "无法写入输出文件，请检查目录权限。" | 1. 更换输出目录<br>2. 修改目录权限<br>3. 重新处理 |
| E006 | 内容解析失败 | "无法解析输入内容，请检查文本格式。" | 1. 检查文本编码<br>2. 简化文本格式<br>3. 重新提交 |

---

## 六、FAQ 反模式：常见坑与规避

### 6.1 反模式对照表

| 反模式 | 错误做法 | 正确做法 |
|--------|---------|---------|
| 编造信息 | 信息缺失时自行补充猜测内容 | 使用 `[需核实:字段]` 占位，标注缺失 |
| 忽略矛盾 | 发现矛盾时只保留一方表述 | 保留双方表述，标注矛盾点 |
| 跨文件推断 | 批量处理时用文件 A 的信息补充文件 B | 各文件独立处理，互不影响 |
| 过度改写 | 将原文表述改写为更"专业"的语言 | 保留原文关键表述，仅做结构化整理 |
| 忽略来源 | 输出信息时不标注来源位置 | 所有数据类信息标注章节号或段落号 |

### 6.2 效率提升建议

| 场景 | 建议 |
|------|------|
| 自定义格式 | 明确指定 JSON 结构或特定字段，减少后续调整 |
| 批量处理 | 提前整理文件列表，按顺序命名，便于追踪 |
| 置信度调优 | 根据实际需求调整置信度判定标准，平衡完整性与准确性 |
| 工具链集成 | 结合其他自动化工具，构建信息处理流水线 |

---

## 七、渐进式披露：分层次阅读路径

### 7.1 速查卡（新手必读）

1. **能做什么**：将文本/文件转化为结构化笔记，标注置信度
2. **怎么触发**：说"用 excerpo 处理"或"帮我整理笔记"
3. **核心原则**：不编造、不修改、不跨文件推断
4. **输出格式**：Markdown 文件，含结论、要点、待核实信息
5. **出错怎么办**：查看错误码表，按提示修正

### 7.2 进阶路径（熟练用户）

1. **自定义模板**：指定 JSON 结构或特定字段输出
2. **批量处理**：多文件独立处理，命名规范与备份策略
3. **置信度门控调优**：根据场景调整判定标准
4. **工具链集成**：结合其他自动化工具构建处理流程

### 7.3 完整参考（深度用户）

- 阅读「三、标准流程」了解完整执行细节
- 阅读「四、置信度门控」掌握判定标准
- 阅读「五、错误码体系」定位问题
- 阅读「六、FAQ 反模式」规避常见坑

---

## 八、自定义与扩展

### 8.1 自定义输出模板

用户可指定输出格式：

```json
{
  "title": "笔记标题",
  "source": "原文来源",
  "key_points": ["要点1", "要点2"],
  "confidence": {
    "high": 5,
    "medium": 3,
    "low": 2
  },
  "pending_verification": ["待核实字段1", "待核实字段2"]
}
```

### 8.2 场景适配

| 场景 | 适配建议 |
|------|---------|
| 学术笔记 | 增加引用格式、文献索引字段 |
| 会议纪要 | 增加行动项、负责人、截止日期字段 |
| 知识管理 | 增加标签、分类、关联笔记字段 |

### 8.3 工具链集成

- 与文件管理工具结合，自动归档笔记
- 与搜索工具结合，快速检索笔记内容
- 与自动化脚本结合，定时处理新增资料

---

---

## 安装与使用

```bash
# 进入技能目录运行自检
python run.py --selftest

# 查看帮助
python run.py --help

# 执行核心功能
python run.py main --input file.txt
```

## 常见问题

**Q: 支持中文文件吗？**
A: 支持，内置 utf-8/gbk/gb18030 多编码容错。

**Q: 运行报错怎么办？**
A: 工具内置异常降级，错误会有明确提示；可先用 --dry-run 预览。

**Q: 如何确认功能正常？**
A: 运行 --selftest，全部通过即核心功能正常。

## 许可证

MIT

使用说明

# 学习资料结构化笔记助手

将学习资料、网页或文本转化为结构化笔记，保留关键信息并标注置信度，遵循不编造原则。

## 适用场景

- 摘录、做学习笔记、信息萃取、要点提炼、知识卡片
- 批量处理多份文档，逐个生成独立笔记

## 最简用法

```bash
python run.py --selftest          # 自检
python run.py main --input file.txt
```

```text
把这段网页正文整理成结构化学习笔记
```

## 说明

- 输出含核心结论、关键要点、待核实信息与原始来源索引
- 不确定信息标注 [需核实:字段]，不编造内容
- 内置 utf-8/gbk/gb18030 多编码容错，支持 --dry-run 预览

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。