# Fetobe Notes Agent 接入说明

Fetobe Notes 是一个多用户、多 Vault 的 Markdown 记录平台。网页、CLI 和 MCP 共用相同的账号状态、Token scope、Vault 所有权、回收站和 revision 冲突规则。

## 推荐接入

1. 用户在 /settings/account 创建个人 API Token。只读任务使用 read，确需写入时才使用 read-write。
2. 本地构建 Fetobe Notes 客户端：npm ci && npm run build:cli。
3. 使用 dist-cli/nb.js 保存 server、Token 和 profile，Token 不应写入项目仓库或 MCP 配置。
4. 运行 dist-cli/mcp-server.js，通过标准 stdio MCP 接入 Codex、Claude Code 或其他客户端。

完整的人类可读步骤：/agents

## Agent 工作规则

- 先调用 list_vaults，后续内容操作始终使用准确 vaultId。
- 读取笔记时保留返回的 revision。
- update_note、rename_path、move_path_to_trash、restore_note_revision 必须使用当前 baseRevision。
- 遇到 REVISION_CONFLICT 时重新读取并合并，禁止无条件覆盖。
- 删除默认进入回收站；永久删除属于破坏性操作，应取得用户明确同意。
- 不请求、不回显、不记录用户的 Bearer Token。
- 不尝试访问其他账号的 Vault，也不要从 Vault 名称猜测 ID。

## 能力范围

- Vault：列出、读取、创建、更新、归档、恢复与隔离删除。
- 笔记：文件树、最近内容、搜索、读取、创建和 revision 保护更新。
- 路径：创建目录、重命名、移动、删除与恢复。
- 历史：列出版本、读取历史正文、恢复为新版本。
- 附件与回收站：遵循当前 Token scope 和 Vault 所有权。

## 认证失败

Token 过期或撤销、账号未审批或停用、scope 不足、Vault 不属于当前用户时，服务端会拒绝请求。不要尝试绕过；请让用户在网页端处理账号或 Token。