apple-notes-writer
# Apple Notes Writer
将内容以完美格式写入Apple备忘录（macOS only）。
## 功能特性
- ✅ **HTML格式支持** - 标题、列表、粗体、斜体等丰富格式
- ✅ **Markdown转换** - 自动将Markdown转为Apple Notes支持的HTML
- ✅ **特殊字符转义** - 自动处理引号、反斜杠等棘手字符
- ✅ **文件夹管理** - 支持创建文件夹、指定目标文件夹
- ✅ **更新模式** - 可选择更新同名笔记或创建新笔记
## 使用方法
### 方式一：直接调用Python脚本
```bash
# 写入HTML格式内容
python scripts/apple_notes.py write \
--title "我的笔记" \
--content "<div><h1>标题</h1><p>内容</p></div>"
# 从Markdown文件写入
python scripts/apple_notes.py write \
--title "Markdown笔记" \
--file content.md \
--markdown
# 写入指定文件夹
python scripts/apple_notes.py write \
--title "工作笔记" \
--content "<div><p>内容</p></div>" \
--folder "工作"
# 更新已存在的笔记
python scripts/apple_notes.py write \
--title "我的笔记" \
--content "<div><p>新内容</p></div>" \
--update
# 读取笔记内容
python scripts/apple_notes.py read --title "我的笔记"
# 列出文件夹中的所有笔记
python scripts/apple_notes.py list --folder "工作"
# 创建新文件夹
python scripts/apple_notes.py create-folder --title "新项目"
```
### 方式二：在Python代码中使用
```python
from scripts.apple_notes import AppleNotesWriter, markdown_to_html
# 创建写入器
writer = AppleNotesWriter(account="iCloud")
# 写入HTML内容
html_content = """<div>
<h1>会议记录</h1>
<p>时间：2024年3月28日</p>
<ul>
<li>讨论项目进度</li>
<li>确定下周计划</li>
</ul>
</div>"""
result = writer.write(
title="会议记录",
content=html_content,
folder="工作",
update_existing=True
)
print(result) # SUCCESS: Note created/updated - 会议记录
# Markdown转HTML后写入
markdown_text = """
# 学习笔记
## 重点内容
- **第一点**：非常重要
- *第二点*：次要内容
### 总结
这是总结段落。
"""
html = markdown_to_html(markdown_text)
writer.write(title="学习笔记", content=html)
```
## 支持的HTML标签
Apple Notes原生支持以下HTML标签：
| 标签 | 效果 |
|------|------|
| `<h1>` `<h2>` `<h3>` | 大标题、中标题、小标题 |
| `<p>` | 段落 |
| `<br>` | 换行 |
| `<ul>` `<li>` | 无序列表（圆点） |
| `<ol>` `<li>` | 有序列表（数字） |
| `<b>` `<strong>` | 粗体 |
| `<i>` `<em>` | 斜体 |
| `<u>` | 下划线 |
| `<div>` | 容器（必须包裹内容） |
## HTML格式规范
### ✅ 正确示例
```html
<div>
<h1>大标题</h1>
<p>这是一个段落，包含<b>粗体文字</b>和<i>斜体文字</i>。</p>
<ul>
<li>列表项1</li>
<li>列表项2</li>
</ul>
</div>
```
### ❌ 错误示例
```html
<!-- 错误：没有外层div包裹 -->
<h1>标题</h1>
<p>内容</p>
<!-- 错误：使用不支持的标签 -->
<div>
<code>代码块</code> <!-- code标签不支持 -->
<img src="..."> <!-- img标签不支持 -->
</div>
<!-- 错误：未闭合的标签 -->
<div>
<p>内容
</div>
```
## Markdown转换规则
使用 `markdown_to_html()` 函数转换：
| Markdown | 转换结果 |
|----------|----------|
| `# 标题` | `<h1>标题</h1>` |
| `## 标题` | `<h2>标题</h2>` |
| `### 标题` | `<h3>标题</h3>` |
| `**粗体**` | `<b>粗体</b>` |
| `*斜体*` | `<i>斜体</i>` |
| `- 列表项` | `<ul><li>列表项</li></ul>` |
| `1. 列表项` | `<ol><li>列表项</li></ol>` |
| 空行 | `<br>` |
## 特殊字符与符号
### 自动转义的字符
脚本自动处理以下特殊字符：
| 字符 | 处理方式 |
|------|----------|
| `\` | 转义为 `\\` |
| `"` | 转义为 `\"` |
| `'` | 无需转义 |
| `\n` | 转为 `<br>` |
| `<` `>` | HTML转义（Markdown模式） |
### 推荐使用的特殊符号
Apple Notes完美支持以下Unicode符号：
| 符号 | 用途 | 示例 |
|------|------|------|
| ✓ | 完成/正确 | `<li>✓ 已完成</li>` |
| ✗ | 失败/错误 | `<li>✗ 失败</li>` |
| ⚠️ | 警告/注意 | `<p>⚠️ 重要提醒</p>` |
| ☐ | 待办复选框 | `<li>☐ 待办事项</li>` |
| ● | 列表圆点 | （`<ul>`自动显示） |
| → | 箭头/流程 | `<p>步骤1 → 步骤2</p>` |
| 📌 | 标记重点 | `<p>📌 核心结论</p>` |
| 💡 | 提示/想法 | `<p>💡 建议</p>` |
## 触发词
当用户提到以下内容时，使用此技能：
| 触发词 | 场景 |
|--------|------|
| "记笔记到备忘录" | 创建新笔记 |
| "写入Apple Notes" | 创建/更新笔记 |
| "创建备忘录" | 创建新笔记 |
| "更新备忘录" | 更新现有笔记 |
| "记录到备忘录" | 创建新笔记 |
| "保存到Apple备忘录" | 创建新笔记 |
| "添加到备忘录" | 追加内容 |
| "写入备忘录" | 创建新笔记 |
## 工作流程
1. **确认需求** - 了解笔记主题、目标文件夹
2. **准备内容** - 用HTML格式组织内容，或使用Markdown转换
3. **转义字符** - 使用内置函数处理特殊字符
4. **执行写入** - 运行AppleScript创建/更新笔记
5. **验证结果** - 确认内容正确写入
6. **反馈用户** - 报告完成情况和笔记位置
## 高级用法
### 更新现有笔记
通过笔记ID更新已有笔记：
```python
# 获取笔记ID后更新
note_id = "x-coredata://.../ICNote/p20"
script = f'''
tell application "Notes"
set targetNote to note id "{note_id}"
set body of targetNote to "{escaped_content}"
end tell
'''
subprocess.run(['osascript', '-e', script])
```
### 验证写入结果
```python
verify_script = f'''
tell application "Notes"
set targetNote to note id "{note_id}"
return body of targetNote
end tell
'''
result = subprocess.run(['osascript', '-e', verify_script],
capture_output=True, text=True)
print(result.stdout) # 打印笔记内容验证
```
## 完整示例
### 示例1：记录会议纪要
```python
from scripts.apple_notes import AppleNotesWriter
writer = AppleNotesWriter()
content = """<div>
<h1>产品评审会议纪要</h1>
<p><b>时间：</b>2024年3月28日 14:00</p>
<p><b>参会人：</b>张三、李四、王五</p>
<h2>讨论事项</h2>
<ul>
<li>确认Q2产品路线图</li>
<li>讨论新功能优先级</li>
<li>确定下周迭代计划</li>
</ul>
<h2>待办事项</h2>
<ul>
<li><b>张三</b>：完成需求文档（3月30日前）</li>
<li><b>李四</b>：准备技术方案（4月1日前）</li>
</ul>
<p>---</p>
<p><i>记录时间：2024-03-28 16:30</i></p>
</div>"""
writer.write(
title="产品评审会议纪要-20240328",
content=content,
folder="工作",
update_existing=True
)
```
### 示例2：从Markdown文件批量导入
```python
import os
from scripts.apple_notes import AppleNotesWriter, markdown_to_html
writer = AppleNotesWriter()
notes_dir = "/path/to/notes"
for filename in os.listdir(notes_dir):
if filename.endswith('.md'):
with open(os.path.join(notes_dir, filename), 'r') as f:
markdown_content = f.read()
html_content = markdown_to_html(markdown_content)
title = filename.replace('.md', '')
writer.write(
title=title,
content=html_content,
folder="导入的笔记"
)
print(f"已导入: {title}")
```
## 注意事项
1. **仅支持macOS** - 依赖AppleScript，Windows/Linux不可用
2. **iCloud账户** - 默认使用iCloud账户，可修改`account`参数
3. **文件夹必须存在** - 写入前确保目标文件夹已创建
4. **HTML标签限制** - 不支持`<code>`、`<img>`、`<table>`等复杂标签
5. **内容长度限制** - 单条笔记建议不超过10MB
## 故障排查
### 问题：笔记创建成功但格式错乱
**原因**：HTML标签未闭合或不支持
**解决**：检查所有标签是否正确闭合，只使用支持的标签
### 问题：特殊字符显示异常
**原因**：引号或反斜杠未正确转义
**解决**：使用脚本内置的转义函数，不要手动转义
### 问题：找不到文件夹
**原因**：文件夹不存在或名称错误
**解决**：先用`create-folder`创建文件夹，或检查文件夹名称
### 问题：AppleScript执行失败
**原因**：权限问题或Apple Notes未运行
**解决**：确保Apple Notes已安装并至少运行过一次，检查自动化权限
## 依赖
- macOS 10.14+
- Python 3.7+
- Apple Notes.app
## 许可证
MIT License
标签
skill
ai
