236 lines
9.5 KiB
Markdown
236 lines
9.5 KiB
Markdown
# TOOLS.md - Local Notes
|
||
|
||
Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.
|
||
|
||
### Ollama 本地模型使用规则
|
||
|
||
**通用规则**
|
||
- 只用已下载的模型，绝不自动下载新模型
|
||
- 需要未下载的模型时，先询问用户
|
||
|
||
**默认模型：kamekichi128/qwen3-4b-instruct-2507**
|
||
- 用途：邮件摘要、轻量分析
|
||
- 速度：快（~5秒）
|
||
- 无需额外参数，直接调用即可
|
||
|
||
**备选模型**
|
||
- `ministral-3:3b` - 速度快，格式清晰
|
||
- `gemma3:4b` - 适中速度
|
||
- `qwen3:4b` - 较慢，仅备用
|
||
|
||
### agent-browser 浏览器自动化
|
||
|
||
**注意：agent-browser 是独立的 CLI 工具，不是 OpenClaw 内置功能**
|
||
- 文档见 `~/.openclaw/workspace/skills/agent-browser/SKILL.md`
|
||
- 依赖 Chrome/Chromium（已安装于 `/usr/bin/google-chrome`）
|
||
|
||
### himalaya 邮件客户端
|
||
|
||
**本地配置：**
|
||
- 二进制：`~/.local/bin/himalaya`
|
||
- **安全包装器**：`~/.openclaw/workspace/scripts/himalaya.sh`（验证收件人）
|
||
- 配置：`~/.config/himalaya/config.toml`
|
||
- 文档：`~/.openclaw/workspace/skills/himalaya/SKILL.md`
|
||
|
||
**重要：发送邮件时必须使用包装器，不要直接调用 himalaya**
|
||
|
||
```bash
|
||
HIMALAYA=~/.openclaw/workspace/scripts/himalaya.sh
|
||
|
||
$HIMALAYA envelope list --page-size 20 # 列出邮件（直接透传）
|
||
$HIMALAYA message read <id> # 读取邮件（直接透传）
|
||
$HIMALAYA message delete <id> # 删除邮件（直接透传）
|
||
cat msg.txt | $HIMALAYA template send # 发送邮件（校验收件人）
|
||
```
|
||
|
||
**邮件发送规则：**
|
||
- **所有发送命令通过包装器**，自动校验收件人在通讯录中
|
||
- **youlu@luyanxin.com → mail@luyx.org**: 直接发送，无需确认（用户 SimpleLogin 别名）
|
||
- 其他所有对外邮件: 仍需确认
|
||
|
||
### 通讯录（contacts）
|
||
|
||
**目录**: `~/.openclaw/workspace/skills/contacts/`
|
||
**数据**: `~/.openclaw/workspace/contacts/`（vCard .vcf 文件，按 Migadu 地址簿分目录，CardDAV 同步）
|
||
|
||
```bash
|
||
CONTACTS=~/.openclaw/workspace/skills/contacts/scripts/contacts.sh
|
||
|
||
$CONTACTS list # 列出所有联系人
|
||
$CONTACTS add --name "小橘子" --email "x@y.com" --type work # 添加联系人
|
||
$CONTACTS delete --name "小橘子" # 删除联系人
|
||
$CONTACTS resolve "小橘子:work" # 解析为邮箱地址
|
||
```
|
||
|
||
**安全规则**:
|
||
- **添加联系人和发送邮件是独立操作**，不要在同一次请求中先 add 再 send
|
||
- 所有邮件发送（himalaya 和日历邀请）都会校验收件人在通讯录中
|
||
|
||
### 🌐 网页操作 - 工具选择决策表
|
||
|
||
| 场景 | 首选 | 次选 |
|
||
|------|------|------|
|
||
| 任何网页操作（抓取、点击、填表、截图） | `agent-browser` | `web_fetch` (仅纯文本) |
|
||
| Browser extension 有登录态/已打开页面 | `browser` (Chrome extension) | `agent-browser` |
|
||
| agent-browser 不可用 | `browser` | `web_fetch` |
|
||
|
||
**agent-browser 快速命令：**
|
||
```bash
|
||
agent-browser open <url>
|
||
agent-browser snapshot -i # 获取交互元素
|
||
agent-browser click @e1
|
||
agent-browser fill @e2 "text"
|
||
agent-browser close
|
||
```
|
||
|
||
### Email Processor 邮件自动处理
|
||
|
||
**目录**: `~/.openclaw/workspace/scripts/email_processor/`
|
||
**文档**: `README.md`（完整使用说明和标签更新流程）
|
||
**Cron**: 每天 08:30 / 17:00（PST）
|
||
|
||
**核心用法**:
|
||
```bash
|
||
./email-processor.sh scan # 扫描未读邮件
|
||
./email-processor.sh scan --recent 7 # 扫描最近7天
|
||
./email-processor.sh scan --dry-run # 测试模式（不执行）
|
||
./email-processor.sh review list # 查看待处理队列
|
||
./email-processor.sh review accept # 接受所有建议
|
||
./email-processor.sh review 1 delete # 处理第1封（删除）
|
||
./email-processor.sh stats # 查看统计
|
||
./email-processor.sh digest # 今日处理摘要
|
||
./email-processor.sh digest --recent 3 # 最近3天摘要
|
||
```
|
||
|
||
**置信度机制**:
|
||
- **阈值**: 85%（`config.json` 中 `automation.confidence_threshold`）
|
||
- **计算方式**: 基于 `(发件人邮箱, 标签)` 签名匹配历史决策
|
||
- **增长规则**: 每个匹配增加 10% 上限（9次一致决策达到85%+）
|
||
- **起步**: 新/未知发件人从 50% 开始
|
||
|
||
**标签分类（14个）**:
|
||
`receipt, billing, shipping, promotion, newsletter, security, social, reminder, confirmation, alert, personal, account, subscription, travel`
|
||
|
||
**何时需要更新标签**:
|
||
- 某发件人处理10+次后仍进队列（置信度<85%）
|
||
- 同一发件人历史决策不一致（有时删有时留）
|
||
- 详见 `README.md` 的 "Refining the Tag Taxonomy" 章节
|
||
|
||
**重要文件**:
|
||
- `config.json` — Ollama 配置和自动化阈值
|
||
- `data/decision_history.json` — 决策历史（学习数据）
|
||
- `data/pending_emails.json` — 待处理队列
|
||
- `logs/` — 处理日志
|
||
|
||
### Calendar 日历 + 待办
|
||
|
||
**文档**: `~/.openclaw/workspace/skills/calendar/SKILL.md`
|
||
**目录**: `~/.openclaw/workspace/skills/calendar/`
|
||
**默认发件人**: youlu@luyanxin.com
|
||
**默认时区**: America/Los_Angeles
|
||
**日历数据**: `~/.openclaw/workspace/calendars/home/`（事件）、`calendars/tasks/`（待办）
|
||
**运行方式**: `uv run`（依赖 `icalendar` 库）
|
||
|
||
**核心用法**:
|
||
```bash
|
||
SKILL_DIR=~/.openclaw/workspace/skills/calendar
|
||
|
||
# 发送日历邀请（--to 用通讯录名称，不要直接写邮箱地址）
|
||
$SKILL_DIR/scripts/calendar.sh send \
|
||
--to "小橘子:work" \
|
||
--subject "Lunch" --summary "Lunch at Tartine" \
|
||
--start "2026-03-20T12:00:00" --end "2026-03-20T13:00:00" \
|
||
--alarm 1h # 提前1小时提醒（默认1d，支持 1d/2h/30m）
|
||
|
||
# 发送周期性邀请（--start 必须落在 BYDAY 指定的那天！）
|
||
$SKILL_DIR/scripts/calendar.sh send \
|
||
--to "小橘子:work" \
|
||
--subject "Weekly Shot" --summary "Allergy Shot (Tue)" \
|
||
--start "2026-03-31T14:30:00" --end "2026-03-31T15:00:00" \
|
||
--rrule "FREQ=WEEKLY;COUNT=13;BYDAY=TU"
|
||
|
||
# 接受/拒绝邀请
|
||
$SKILL_DIR/scripts/calendar.sh reply --envelope-id 42 --action accept
|
||
|
||
# 事件管理（查看、搜索、删除）
|
||
$SKILL_DIR/scripts/calendar.sh event list
|
||
$SKILL_DIR/scripts/calendar.sh event list --search "Allergy"
|
||
# 取消周期性事件的单次（加 EXDATE，系列保留）
|
||
$SKILL_DIR/scripts/calendar.sh event delete --match "Allergy Shot" --date "2026-03-28"
|
||
# 删除整个周期性系列（需要 --all 安全标志）
|
||
$SKILL_DIR/scripts/calendar.sh event delete --match "Allergy Shot" --all
|
||
# 删除非周期性事件
|
||
$SKILL_DIR/scripts/calendar.sh event delete --match "Lunch"
|
||
|
||
# 待办管理
|
||
$SKILL_DIR/scripts/calendar.sh todo add --summary "跟进报销" --due "2026-03-25" --priority high
|
||
$SKILL_DIR/scripts/calendar.sh todo list
|
||
$SKILL_DIR/scripts/calendar.sh todo edit --match "报销" --due "2026-03-28"
|
||
$SKILL_DIR/scripts/calendar.sh todo complete --match "报销"
|
||
$SKILL_DIR/scripts/calendar.sh todo delete --match "报销"
|
||
$SKILL_DIR/scripts/calendar.sh todo check # 每日摘要（cron）
|
||
```
|
||
|
||
**支持操作**: 发送邀请 (`send`)、接受/拒绝/暂定 (`reply`)、事件管理 (`event list/delete --date/--all`)、待办管理 (`todo add/list/edit/complete/delete/check`)
|
||
**依赖**: himalaya（邮件）、vdirsyncer（CalDAV 同步）、khal（查看日历）、todoman（待办管理）
|
||
**同步**: 发送/回复/待办变更后自动 `vdirsyncer sync`，心跳也会定期同步
|
||
**注意**: 发送日历邀请属于对外邮件，需先确认
|
||
|
||
**安全规则**:
|
||
- **`send --to` 只接受通讯录中的联系人**，不认识的地址会被拒绝（防止地址幻觉）
|
||
- **添加联系人和发送邮件是独立操作**，不要在同一次请求中先 add 再 send
|
||
- 周期性邀请务必先 `--dry-run` 验证 ICS 内容
|
||
- **绝不用 `rm` 删日历 .ics 文件**，只用 `event delete`
|
||
- **取消周期性事件的单次用 `--date`**，不要用 `--all`（会删掉整个系列）
|
||
- 连续发多封邮件时，每封间隔 10 秒以上（Migadu SMTP 限频）
|
||
|
||
### Notesearch 笔记搜索
|
||
|
||
**目录**: `~/.openclaw/workspace/skills/notesearch/`
|
||
**配置**: `~/.openclaw/workspace/skills/notesearch/config.json`
|
||
**笔记库**: `/home/lyx/Documents/obsidian-yanxin`（Obsidian vault，git 管理）
|
||
|
||
基于向量搜索的笔记检索工具，使用 LlamaIndex + Ollama 嵌入模型索引 Obsidian 笔记。
|
||
|
||
```bash
|
||
NOTESEARCH=~/.openclaw/workspace/skills/notesearch/notesearch.sh
|
||
|
||
# 搜索笔记（返回相关片段 + 文件路径 + 相关性分数）
|
||
$NOTESEARCH search "allergy shots"
|
||
$NOTESEARCH search "project planning" --top-k 3
|
||
|
||
# 重建索引（笔记更新后需要重新索引）
|
||
$NOTESEARCH index
|
||
```
|
||
|
||
**工作流程**:
|
||
1. 用户提问 → 用 `search` 找到相关笔记片段
|
||
2. 如果需要完整内容 → `cat /home/lyx/Documents/obsidian-yanxin/<文件路径>`
|
||
3. 根据笔记内容回答用户问题
|
||
|
||
**注意**:
|
||
- 搜索基于语义（向量相似度），不仅仅是关键词匹配
|
||
- 笔记更新后需要运行 `$NOTESEARCH index` 重建索引
|
||
- 嵌入模型: `qwen3-embedding:0.6b`（通过 Ollama）
|
||
|
||
### OpenClaw Cron 定时任务
|
||
|
||
**规则**: 确定性 shell 任务用 `systemEvent`，需要 LLM 判断的用 `agentTurn`
|
||
|
||
```bash
|
||
# systemEvent 直接执行（不走 LLM）
|
||
openclaw cron edit <id> --session main \
|
||
--system-event 'exec:cd /path && command'
|
||
|
||
# 查看/测试
|
||
openclaw cron list
|
||
openclaw cron runs --id <id>
|
||
openclaw cron run <id> # 立即触发
|
||
```
|
||
|
||
**注意**: kimi-k2.5 工具使用弱，`agentTurn` 容易产生"已完成"幻觉。详见 MEMORY.md 2026-03-24 备份修复记录。
|
||
|
||
---
|
||
|
||
Add whatever helps you do your job. This is your cheat sheet.
|