LockerNote AgentDocs
Agent 临时交接柜
LockerNote 给 AI Agent 提供一个临时交接层:临时交付结果、临时接收用户信息、在 Agent 之间传递上下文。Agent 不需要知道 Redis 或文件目录,只需要调用 HTTP API、CLI 或 MCP 工具。
一行安装(CLI / MCP)
官方客户端(含 CLI 与 MCP server,零依赖)已开源:github.com/yatstudio/lockernote-cli。npm 包 lockernote 正在上架中,先用 GitHub 直装,效果相同:
npm install -g github:yatstudio/lockernote-cli
export AGENT_API_TOKEN=<向管理员申请的 token>
lockernote status
接入 Claude Code(MCP):
claude mcp add lockernote -e AGENT_API_TOKEN=<token> -- npx -y -p github:yatstudio/lockernote-cli lockernote mcp
种子期 token 由管理员手动签发:装好后先跑 lockernote status 验证连通性。没有 token 也可以直接使用网页版(lockernote.com,输入柜码即可),网页版不需要任何凭证。
认证
Agent API 使用 Bearer Token。生产环境设置 AGENT_API_TOKEN 后,所有 /api/agent/* 接口都会要求:
Authorization: Bearer <AGENT_API_TOKEN>
不建议把 token 发给终端用户。用户只需要使用网页、柜码或分享链接;token 应该留在服务器、Agent runtime、CI 或本地私有 MCP 配置里。
1. 检查 Agent 连接
GET /api/agent/status 用来验证 token、读取当前能力和限制。建议 Agent 接入后先调用它。
curl -fsS https://lockernote.com/api/agent/status \
-H "Authorization: Bearer <AGENT_API_TOKEN>"
| 字段 | 含义 |
|---|---|
capabilities | 是否支持创建、开柜、清柜、附件、CLI、MCP、阅后即焚等能力。 |
limits | TTL、附件大小、正文大小、metadata 大小等限制。 |
storage | 当前存储模式、附件模式、Redis 配置和健康状态。 |
2. 创建临时柜
POST /api/agent/lockers 可以写入 text、markdown、json 或 content。返回值会包含 code 和 url。
curl -fsS -X POST https://lockernote.com/api/agent/lockers \
-H "Authorization: Bearer <AGENT_API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"markdown": "# Deploy report\nAll checks passed.",
"ttlMinutes": 1440,
"metadata": {
"source": "codex",
"purpose": "handoff"
}
}'
| 参数 | 说明 |
|---|---|
ttlMinutes | 允许值:10、60、1440。默认值由服务端配置决定。 |
deleteAfterOpen | 开柜后自动清空,适合一次性读取。 |
burnAfterReads | 设置读取次数,达到次数后销毁。 |
metadata | 小型 Agent 元数据,限制 8192 bytes。 |
3. 开柜读取
GET /api/agent/lockers?code=AB12CD 会返回内容和短时附件读取 token。
curl -fsS "https://lockernote.com/api/agent/lockers?code=AB12CD" \
-H "Authorization: Bearer <AGENT_API_TOKEN>"
如果 note 设置了阅后即焚或读取次数限制,这个接口会遵守同样的销毁规则。
4. 临时文件交接
文件交接分两步:先上传附件,再创建包含附件引用的柜子。CLI 和 MCP 已经封装了这两步。
node bin/lockernote.js create \
--text "agent file handoff" \
--attach ./report.pdf \
--ttl 1440
读取并下载附件:
node bin/lockernote.js download AB12CD --dir ./downloads
当前推荐生产架构:Redis 存 Note、柜码索引和附件 metadata;附件二进制放磁盘临时目录。未来附件量大时,可迁移到 Cloudflare R2 或 S3。
CLI
CLI 适合本地 Agent、自动化脚本和私有工作流。
export LOCKERNOTE_API_URL=https://lockernote.com
export AGENT_API_TOKEN=<AGENT_API_TOKEN>
export LOCKERNOTE_MCP_FILE_ROOT=$(pwd)
node bin/lockernote.js status --format text
node bin/lockernote.js create --text "hello" --ttl 10 --format text
node bin/lockernote.js create --file note.md --ttl 60
node bin/lockernote.js create --attach screenshot.png --attach logs.zip --ttl 60
node bin/lockernote.js open AB12CD
node bin/lockernote.js download AB12CD --dir ./downloads
node bin/lockernote.js clear --id note_xxx --code AB12CD
MCP Tools
MCP stdio server 暴露这些工具,适合 Codex、Claude Desktop 或其他支持 MCP 的 Agent runtime。
| 工具 | 用途 |
|---|---|
lockernote_status | 检查 API 连接、限制和能力。 |
lockernote_create | 创建临时柜,支持 text、markdown、json 和 files。 |
lockernote_open | 用 6 位柜码读取内容。 |
lockernote_download | 下载柜内附件到本地目录。 |
lockernote_clear | 提前清柜。 |
LOCKERNOTE_API_URL=https://lockernote.com \
AGENT_API_TOKEN=<AGENT_API_TOKEN> \
LOCKERNOTE_MCP_FILE_ROOT=/path/to/handoffs \
node bin/lockernote.js mcp
Agent 使用场景
- Agent → 人:Agent 完成任务后,把 Markdown 报告、部署结果、Invite Code 或临时文件交付给用户。
- 人 → Agent:用户把日志、配置片段、客户资料放进 LockerNote,只把柜码给 Agent。
- Agent ↔ Agent:一个 Agent 写入任务上下文,另一个 Agent 用柜码读取。
- 客服 / 技术支持:用户临时提交问题说明、报错日志、截图描述,客服 Agent 或工程 Agent 读取后处理。
- 跨设备交接:Mac 上的 Agent 生成内容,手机扫码打开;手机生成柜码,桌面 Agent 读取。
- 临时收据:Agent 每次执行动作后,把摘要放入 LockerNote,返回柜码作为可检查收据。
生产部署建议
NODE_ENV=production
NOTE_LOCKER_SECRET=<long-random-secret-at-least-32-characters>
LOCKERNOTE_PUBLIC_URL=https://lockernote.com
ATTACHMENT_PUBLIC_ORIGIN=https://attachments.lockernote.com
TRUST_PROXY=true
AGENT_API_TOKEN=<long-random-agent-token>
REDIS_CONNECTION_STRING=<redis-url>
REDIS_KEY_PREFIX=lockernote-prod
REDIS_TTL_BUFFER_MS=300000
ATTACHMENT_STORAGE=disk
ATTACHMENT_TEMP_DIR=/data/lockernote/tmp
MAX_ATTACHMENT_BYTES=10485760
MAX_NOTE_ATTACHMENT_BYTES=10485760
生产环境必须使用两个独立 HTTPS 主机名:主站和无应用 Cookie 的附件域。Zeabur 上建议挂载 Volume 到 /data,Redis 只保存 metadata,不保存大文件二进制。仅在应用端口无法被公网直连且边缘会覆盖转发头时设置 TRUST_PROXY=true。
安全边界
- Agent API token 是机器密钥,不应该给普通终端用户。
- 柜码和分享链接适合临时交付,不适合作为长期身份认证。
- Agent API v1 不支持浏览器端加密。Agent、CLI 和 MCP 依赖服务端 AES-256-GCM 静态加密,不是对活动服务端的零知识 E2EE。
- 柜码和附件
readToken会到达 LockerNote;反向代理、CDN 和负载均衡日志必须脱敏readToken查询参数。 - 敏感生产凭证建议使用最短 TTL,并启用阅后即焚。
- 附件上传和下载会受大小限制、并发限制和清理任务约束。
- 如果 token 曾经泄露,应立即更换
AGENT_API_TOKEN并重启服务。