R2 Agent 共享工作区（R2 Agent Store）

中文名：R2 Agent 共享工作区
英文名：R2 Agent Store
技术标识：r2-agent-store

面向 AI Agent 的 Cloudflare R2 共享存储、磁盘挂载与经验证的跨 Agent 文件交接。

作者：王晶晶律师 · 四川恒和信律师事务所
支持：微信公众号「隔壁王律师」
主页/联系：http://weixin.qq.com/r/mp/xiARCabEX-sgreJq93XU
发布/安装页：https://skillhub.cn/skills/user_112fc3c5/r2-agent-store

Single-bucket object storage skill for agent use. This is the core
edition: it manages one configured bucket with full file operations and
mount support, and intentionally contains no multi-bucket, chunking, or
web-UI capabilities.

When to Use

Use this skill whenever the agent needs to persist, retrieve, inspect,
synchronize, or delete objects in the configured Cloudflare R2 bucket, or
mount the bucket as a local drive for manual management.

Typical scenarios:

• Shared workspace / shared cloud drive: multiple agents or humans
  share one bucket as a common file area (共享工作区 / 共享网盘).
• Offload local files: upload finished artifacts to R2 and remove the
  local copy to free disk space (上传后移除本地副本).
• Cross-machine persistence: keep task outputs, documents, and datasets
  on durable storage instead of an ephemeral local disk.
• Cross-agent handoff: upload a verified file under a unique task_id
  and return a copy-ready prompt that another agent can act on directly.
• Manual browsing: mount (FUSE) or serve (WebDAV) the bucket so a human
  can manage files with the OS file manager.

How Agents Invoke This Skill

This is a prompt-and-scripts skill, not a single shell command. After the user
installs it, the Agent can invoke it in either of these ways:

1. Natural language: ask for an operation in Chinese or English, for
   example “把这个文件上传到 R2 共享工作区”, “列出 documents/ 下的文件”, or
   “把已验证的报告交给另一个 Agent”. The description above supplies the
   trigger phrases.
2. Explicit technical name: include r2-agent-store in the request, for
   example 请使用 r2-agent-store，把 ./report.pdf 上传到 documents/report.pdf， 上传后校验大小，不要覆盖已有对象.

The human-facing name is R2 Agent 共享工作区（R2 Agent Store）; the
installation and script identifier is r2-agent-store. Do not invent a slash
command such as /r2-agent-store, and do not ask the user to run a script when
the Agent can safely run the appropriate scripts/r2_*.py entry point itself.
The Agent must show progress, preview destructive operations, and report
verification results. For a cross-agent handoff, use the copy-ready template in
templates/agent-handoff.txt and never include credentials.

Capabilities

• Single-bucket object CRUD: upload, download, list, stat, guarded delete, and
  copy/mirror sync.
• Verification-oriented transfers: size checks, optional local SHA-256 output,
  overwrite protection, and safe local-copy removal only after verification.
• Cross-agent handoffs: task_id namespaces, immutable task inputs, verified
  size/hash metadata, and a standalone receiving-Agent prompt.
• Human file access: FUSE/macFUSE/WinFsp where available, plus a local WebDAV
  service with proxy-bypassing HTTP and mounted-filesystem checks.
• Safety coordination: advisory locks, destructive-operation confirmations,
  protected _quota/ and _manifest/ prefixes, and bounded retries for
  transient R2 errors.

This core edition intentionally does not provide multi-bucket pooling, chunked
storage, or a web UI.

Prerequisites

• rclone installed (>= 1.59; >= 1.75 recommended)
• Python 3.7+ (Python 3.9+ recommended)
• an r2 remote configured in the user's rclone.conf (see references/quickstart-zh.md and references/setup.md)
• access to the configured bucket

Storage Model

R2 is object storage. Everything that looks like a directory is just a key
prefix. Prefixes simulate hierarchy; they are not POSIX directories. Keys
are case-sensitive and up to 1024 bytes long.

Default Bucket

agent-data

Prefix Rules

Key shape: <domain>/<type>/<date-or-id>/<filename>. See
references/key-schema.md for the full grammar.

Scripts

All scripts live in scripts/ and are Python 3, cross-platform.

Common conventions:

• Remote name defaults to r2, bucket to agent-data; both overridable via
  --remote / --bucket.
• Exit code 0 means success; non-zero means failure with a message on
  stderr. Exit code 4 means a macOS WebDAV mount could not be proven
  persistent and may require a Finder GUI-session mount. Exit code 75 is an
  intentional provisional WebDAV result: run --webdav-verify in a new
  top-level command, and only that verifier may return 0. Quota and other
  operational failures are non-zero; never retry blindly. Use
  --allow-over-quota only when the user has explicitly accepted the extra
  cost.
• Every write is verified unless --no-verify is passed.
• Progress reporting: when performing file operations, tell the user
  what is happening with the concrete file, e.g. 正在读取 <file>,
  正在修改 <file>, 正在保存 <file>, 正在上传 <file> -> <key>,
  正在下载 <key> -> <file>, 正在删除 <key>. Never perform silent
  file operations.
• Mounting guidance: prefer r2_webdav.py when FUSE-style mounting is
  impractical (macOS kext authorization, Homebrew rclone without mount
  support, Windows without WinFsp). WebDAV works from Finder / Explorer /
  Linux file managers with no kernel extension. On macOS, connect to
  http://127.0.0.1:8080/; use the literal IPv4 address rather than
  localhost, and do not append the bucket or a sub-prefix. Opening the URL in
  a browser is read-only browsing, not a mounted disk. Never treat a
  mount_webdav zero exit status or a brief mount table entry as proof of a
  persistent mount: verify a changed mountpoint device ID and directory access
  in a new command after mounting. Agent sandboxes that reap the mount helper
  require Finder mounting in a macOS GUI session. Never generate a
  *.command/.terminal wrapper, automate Terminal, or request broader macOS
  permissions to bypass the sandbox; the user must use Finder Cmd+K, followed
  by --webdav-verify against the actual mounted POSIX path. Local WebDAV
  probes must bypass HTTP_PROXY/HTTPS_PROXY/ALL_PROXY; the bundled
  r2_webdav_check.py does this automatically, while manual curl commands
  use --noproxy '*'. If HTTP 207 is fine but the mount path returns EIO/ENOENT,
  run the checker with --mountpoint and --mount-probe-key, then restart the
  owning rclone WebDAV service. Read references/webdav.md before mounting or
  diagnosing a WebDAV workflow.

WebDAV Environment Decision

Before attempting any macOS mount, check whether the execution environment is
WorkBuddy, an agent sandbox, a non-TTY process, or a process ancestry containing
WorkBuddy/Sandbox/OpenCode. In that environment the mount helper cannot persist.

Stop immediately. Do not try mount_webdav, .command, AppleScript,
open -a Terminal, setsid, or FUSE again. Lead with the solution instead
of a failure narrative, in this exact order:

1. Terminal option — user executes it: provide a copyable command such as
   mkdir -p <mountpoint> && /sbin/mount_webdav -v R2 <url> <mountpoint>.
   For an unauthenticated loopback endpoint, omit -i. If the server requires
   credentials, tell the user to add -i before -v.
2. Finder option — GUI steps: Finder → Cmd+K → enter the URL → Connect →
   enter credentials only if prompted → note the actual /Volumes/... path.
3. Verification: provide the fully populated
   r2_mount.py --webdav-verify command. Finder users must replace
   <FINDER_POSIX_MOUNTPOINT> with the real mounted path.

The agent must not execute Option 1 itself. It should wait for the user to mount
and then run the verifier. A zero exit code from mount_webdav, a brief mount
table entry, or a browser listing is never a reason to keep retrying.

Safety Rules

1. Never print, log, or commit R2 credentials.
2. Never overwrite an immutable original by default (overwrite = false).
3. Prefer unique object keys; never let two agents write the same key
   concurrently without a lock. The lock is advisory and is NOT acquired
   automatically by upload/sync/delete — a worker must run r2_lock.py acquire first (exit code 3 = LOCK BUSY).
4. Never use destructive sync (rclone sync) unless explicitly required and
   previewed with --dry-run. Sync silently excludes _quota/ and
   _manifest/; direct sync to either protected prefix is refused.
5. Preview any destructive delete (prefix, bulk, or bucket contents) before
   execution and require explicit confirmation. Bulk operations silently
   exclude _quota/ and _manifest/; direct deletion under either prefix is
   refused. Deleting the bucket itself remains forbidden.
6. Verify important uploads (key exists, size matches) after completion.
7. Retry transient 429 / 500 / 503 / network failures with bounded
   exponential backoff; never retry hard errors.

Lock honesty: the advisory lock is a coordination convention, not
enforcement. Upload's overwrite check is stat-then-write, so concurrent
writes to the same key have a small race window; only holding the lock
(advisory) closes it. See references/safety-rules.md for the full
boundaries.

Usage Examples

Upload a document:

python3 scripts/r2_upload.py --source ./report.pdf --key documents/2026/report.pdf

List a prefix:

python3 scripts/r2_list.py --prefix documents/ --recursive --size

Download with verification:

python3 scripts/r2_download.py --key documents/2026/report.pdf --dest ./report.pdf

Safe directory copy (never deletes on destination):

python3 scripts/r2_sync.py --source ./outputs --dest-prefix outputs/run-42 --mode copy

Preview and then purge bucket contents while silently preserving protected
internal metadata:

python3 scripts/r2_delete.py --all --dry-run
python3 scripts/r2_delete.py --all --confirm-bucket agent-data --yes

Mount for manual management with FUSE/macFUSE/WinFsp (human use only):

python3 scripts/r2_mount.py --mountpoint ~/r2

Serve the bucket over WebDAV, then verify the complete write path:

export R2_WEBDAV_USER='<webdav-user>'
read -s R2_WEBDAV_PASSWORD && export R2_WEBDAV_PASSWORD
python3 scripts/r2_webdav.py
# In another terminal:
python3 scripts/r2_webdav_check.py --user "$R2_WEBDAV_USER"
unset R2_WEBDAV_USER R2_WEBDAV_PASSWORD

On macOS, connect Finder to http://127.0.0.1:8080/. In a normal interactive
terminal, the CLI mount path is:

python3 scripts/r2_mount.py --webdav --mountpoint "$HOME/R2WebDAV"
# RC=75 is expected and means provisional only. After the command returns,
# run this as a NEW top-level command; only this verifier may return 0:
python3 scripts/r2_mount.py --webdav-verify --mountpoint "$HOME/R2WebDAV"

In WorkBuddy or another agent sandbox, do not run the CLI mount yourself. Put
these two choices first in the response: (1) a /sbin/mount_webdav command
for the user to run in Terminal, and (2) Finder Cmd+K steps. After the user
mounts, use the mounted volume's actual POSIX path (often /Volumes/R2), not
the CLI's ~/R2WebDAV, when running --webdav-verify in a new command. Follow
references/webdav.md for the exact response template and diagnosis.

Cross-Agent File Handoff

When the user asks to share a file with another agent, do not return only a
local path or a bare task ID. Use this sequence:

1. Generate one task_id in the form
   TASK-<YYYYMMDD>-<HHMMSS>-<8 lowercase hex characters> before uploading.
2. Upload the immutable source to
   tasks/<task_id>/input/<safe-filename> with r2_upload.py --checksum; do
   not pass --overwrite.
3. Verify the uploaded object with r2_stat.py. If verification fails, report
   the error and do not issue a handoff prompt.
4. Tell the user the file is ready, then return a fenced, copy-ready prompt
   based on templates/agent-handoff.txt. Fill in the task ID, remote, bucket,
   exact object key, byte size, SHA-256, purpose, and processing requirements.

The prompt must stand alone in the receiving agent's session. It must tell the
agent to use the installed R2 Agent 共享工作区 skill (technical name:
r2-agent-store), stat and download the object, verify size and SHA-256,
preserve the shared input, write results under tasks/<task_id>/output/, and
include the task ID in its final response. Never put credentials or unrelated
local paths in the prompt. A task ID coordinates work but does not grant
storage access.

Read references/agent-handoff.md for the full workflow and example.

Verification

After important writes, verify the key exists and the reported size matches
the source. Use r2_stat.py.

For macOS WebDAV, --webdav returns 75 after a provisional check; this is
not success. Run r2_mount.py --webdav-verify as a new top-level command after
the mount attempt returns. A valid mount has the same non-local device ID and
directory access throughout the continuous verification window. A zero
mount_webdav exit code, a process briefly appearing in ps, or a brief
mount table entry is not sufficient. If the mount is reaped at an agent
session boundary, report that a Finder GUI-session mount is required.

Troubleshooting

See references/troubleshooting.md.

References

• references/quickstart-zh.md — 中文从 Cloudflare 配置、安装到 Agent 调用的完整教程
• references/setup.md - first-time setup guide (bucket, token, config)
• references/key-schema.md — object key grammar
• references/agent-handoff.md — task-ID-based cross-agent sharing and copy-ready prompt
• references/safety-rules.md — safety rules and lock honest boundaries
• references/webdav.md — tested WebDAV startup, OS mounting, verification, and troubleshooting
• references/troubleshooting.md — common errors and fixes
• templates/manifest.json — task manifest template
• templates/agent-handoff.txt — copy-ready prompt for the receiving agent

Author and License

作者：王晶晶律师 · 四川恒和信律师事务所
支持：微信公众号「隔壁王律师」
联系：http://weixin.qq.com/r/mp/xiARCabEX-sgreJq93XU

本 Skill 按 Apache-2.0 许可发布。Copyright 2026 王晶晶（四川恒和信律师事务所）。