# TOOLS.md - Local Notes

Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.

## What Goes Here

Things like:

- Camera names and locations
- SSH hosts and aliases
- Preferred voices for TTS
- Speaker/room names
- Device nicknames
- Anything environment-specific

## Examples

```markdown
### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod
```

## Why Separate?

Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.

---

## Feishu Tools Gotchas

### 📄 飞书文档更新限制

**单次更新长度限制**：约 1.5 万字

使用 `feishu_update_doc` 的 `overwrite` 模式时，如果文档超过约 1.5 万字，内容会被截断。

**长文档更新策略**：
1. **避免** `overwrite` 模式更新超长文档
2. **使用** `replace_range` 模式分章节更新（通过 `selection_by_title` 或 `selection_with_ellipsis` 定位）
3. **或采用** 删除后重新创建策略（先删除云文档，再用 `feishu_create_doc` 创建完整版本）

**最佳工作流**：
- 在本地完成所有修改（本地文件编辑更可靠）
- 使用章节定位方式分段更新到飞书
- 或者本地生成完整版本后一次性创建新文档

---

### 📝 飞书文档更新注意事项

**更新前必做检查**：
1. 先用 `feishu_fetch_doc` 读取完整文档，确认要更新的内容
2. 回顾前文，确保不会重复已知信息（视角一致性）
3. 确认内容格式正确（段落分隔、对话格式）

**避免重复已知信息**：
- 角色A已经经历过的事件，不需要角色B再告诉A
- 只传递接收者不知道的新信息
- 例如：第2章主角和所长一起查看了现场，第3章所长就不需要再说"我们去了你家，客厅很正常"

**内容格式规范**：
- 章节标题后必须空一行
- 每个对话必须单独成段：
  ```markdown
  "对话内容，"他说。
  ```
- 段落之间必须空一行
- 每章末尾添加 `---` 分隔线

**精确定位更新**：
- 优先使用 `selection_with_ellipsis` 精确定位要替换的内容
- `selection_by_title` 可能定位到错误位置（导致内容重复）
- 复杂更新分步骤进行：先 `delete_range`，再 `insert_before`/`insert_after`

**更新后验证**：
- 再次用 `feishu_fetch_doc` 读取文档
- 确认内容正确，没有重复
- 确认格式规范（段落分隔、对话格式）

---

Add whatever helps you do your job. This is your cheat sheet.