LockerNoteDocs AgentDocs

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、阅后即焚等能力。
limitsTTL、附件大小、正文大小、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 并重启服务。