flyfile 0.1.0__tar.gz

flyfile-0.1.0/.github/workflows/gh-release.yml

@@ -0,0 +1,31 @@
+on:
+  push:
+    tags:
+      - 'v*'
+
+name: Create Release
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Create Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract tag name
+        id: extract_tag
+        run: echo "TAG_NAME=$(echo ${GITHUB_REF#refs/tags/})" >> $GITHUB_ENV
+
+      - name: Create Release and Generate Notes
+        id: create_release
+        uses: softprops/action-gh-release@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          name: Release ${{ env.TAG_NAME }}
+          draft: false
+          prerelease: false
+          generate_release_notes: true

flyfile-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,48 @@
+name: Upload Python Package
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: build release distributions
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+
+      - name: upload dists
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

flyfile-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

flyfile-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: flyfile
+Version: 0.1.0
+Summary: Agent-native data transfer: push/pull/send anything between agents and machines
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: flaxkv2>=0.2.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: zstandard>=0.22
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flyfile
+
+Agent-native data transfer. Push/pull anything (text, files, directories) through a central
+server, or stream it directly client-to-client. Built for AI agents: JSON output everywhere,
+stable exit codes, content-addressed dedup, burn-after-read.
+
+```bash
+pip install flyfile
+
+# server (single worker; data lives in LMDB via flaxkv2)
+flyfile serve --port 8632 --token SECRET
+
+# client
+export FLYFILE_SERVER=http://host:8632 FLYFILE_TOKEN=SECRET
+echo "build log" | flyfile push - --name buildlog --tag ci --ttl 2h
+flyfile push ./model.bin --reads 1            # burn after one read
+flyfile push ./dataset/                       # dirs stream as tar, no temp files
+flyfile ls --tag ci --json
+flyfile preview k3x9m2pq                      # peek without consuming reads
+flyfile pull k3x9m2pq -o ./model.bin
+
+# client → client (server relays the stream, nothing is stored)
+flyfile send ./results/          # prints: code: amber-falcon
+flyfile recv amber-falcon        # on the other machine
+```
+
+## Agent contract
+
+- **JSON everywhere**: `--json`, or automatic when stdout is not a TTY. Progress goes to
+  stderr, data to stdout. Never prompts.
+- **Exit codes (stable)**: 0 ok · 2 usage · 3 not found · 4 auth · 5 conflict ·
+  6 expired/burned · 7 network (retryable) · 1 other.
+- **Errors** are JSON on stderr: `{"error", "message", "retryable", "suggestion"}`.
+- **Idempotent push**: content-addressed (sha256). Re-pushing the same bytes is instant
+  (`"deduped": true`).
+- **`flyfile preview <id>`** reads the head of an object (or a dir's file manifest)
+  without downloading and without consuming burn-after-read counts.
+- **`flyfile schema [cmd]`** dumps the command tree as JSON for introspection.
+- **`flyfile send --json`** emits NDJSON events; the `code` event arrives before the
+  transfer starts, so an agent can hand it to the receiver immediately.
+
+## Design notes
+
+- Storage is [flaxkv2](https://github.com/KenyonY/flaxkv) (LMDB): metadata and 8 MiB
+  content chunks in one env. The LMDB file does not shrink after deletes (free pages are
+  reused; file size ≈ historical peak).
+- Compression (zstd-3) happens on the *client*; the server stores/relays compressed bytes.
+  Each 8 MiB chunk of a large upload is an independent zstd frame, so parallel upload,
+  resume, and parallel download all work per-chunk.
+- Burn-after-read: the read is claimed atomically when chunk 0 (or `/content`) is fetched.
+  Later chunks of an in-flight parallel download are served during a grace period
+  (default 15 min) even after the object burns.
+- Run exactly **one** uvicorn worker: relay pairing and the burn-claim lock are in-process.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest
+scripts/bench.sh   # 1 GiB loopback throughput smoke test
+```

flyfile-0.1.0/README.md

@@ -0,0 +1,61 @@
+# flyfile
+
+Agent-native data transfer. Push/pull anything (text, files, directories) through a central
+server, or stream it directly client-to-client. Built for AI agents: JSON output everywhere,
+stable exit codes, content-addressed dedup, burn-after-read.
+
+```bash
+pip install flyfile
+
+# server (single worker; data lives in LMDB via flaxkv2)
+flyfile serve --port 8632 --token SECRET
+
+# client
+export FLYFILE_SERVER=http://host:8632 FLYFILE_TOKEN=SECRET
+echo "build log" | flyfile push - --name buildlog --tag ci --ttl 2h
+flyfile push ./model.bin --reads 1            # burn after one read
+flyfile push ./dataset/                       # dirs stream as tar, no temp files
+flyfile ls --tag ci --json
+flyfile preview k3x9m2pq                      # peek without consuming reads
+flyfile pull k3x9m2pq -o ./model.bin
+
+# client → client (server relays the stream, nothing is stored)
+flyfile send ./results/          # prints: code: amber-falcon
+flyfile recv amber-falcon        # on the other machine
+```
+
+## Agent contract
+
+- **JSON everywhere**: `--json`, or automatic when stdout is not a TTY. Progress goes to
+  stderr, data to stdout. Never prompts.
+- **Exit codes (stable)**: 0 ok · 2 usage · 3 not found · 4 auth · 5 conflict ·
+  6 expired/burned · 7 network (retryable) · 1 other.
+- **Errors** are JSON on stderr: `{"error", "message", "retryable", "suggestion"}`.
+- **Idempotent push**: content-addressed (sha256). Re-pushing the same bytes is instant
+  (`"deduped": true`).
+- **`flyfile preview <id>`** reads the head of an object (or a dir's file manifest)
+  without downloading and without consuming burn-after-read counts.
+- **`flyfile schema [cmd]`** dumps the command tree as JSON for introspection.
+- **`flyfile send --json`** emits NDJSON events; the `code` event arrives before the
+  transfer starts, so an agent can hand it to the receiver immediately.
+
+## Design notes
+
+- Storage is [flaxkv2](https://github.com/KenyonY/flaxkv) (LMDB): metadata and 8 MiB
+  content chunks in one env. The LMDB file does not shrink after deletes (free pages are
+  reused; file size ≈ historical peak).
+- Compression (zstd-3) happens on the *client*; the server stores/relays compressed bytes.
+  Each 8 MiB chunk of a large upload is an independent zstd frame, so parallel upload,
+  resume, and parallel download all work per-chunk.
+- Burn-after-read: the read is claimed atomically when chunk 0 (or `/content`) is fetched.
+  Later chunks of an in-flight parallel download are served during a grace period
+  (default 15 min) even after the object burns.
+- Run exactly **one** uvicorn worker: relay pairing and the burn-claim lock are in-process.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest
+scripts/bench.sh   # 1 GiB loopback throughput smoke test
+```

flyfile-0.1.0/docs/README.md

@@ -0,0 +1,37 @@
+# flyfile 文档
+
+面向 AI agent 的数据传输系统：客户端 ↔ 服务端存取 + 客户端 → 客户端直传，
+支持字符串/文件/文件夹，阅后即焚/TTL/永久，元数据可查询。
+
+## 文档目录
+
+```
+docs/
+├── README.md              # 本文档：总览与目录
+├── architecture.md        # 架构：存储模型、传输机制、生命周期、C2C 中转
+├── cli.md                 # CLI 参考：命令、退出码契约、agent 使用范式
+├── api.md                 # HTTP API 参考
+└── flaxkv2-feedback.md    # dogfooding 过程中发现的 flaxkv2 改进点
+```
+
+## 核心心智模型
+
+- **一切皆 object**：text / file / dir 统一对象模型，dir 以流式 tar 传输（不落临时文件）
+- **元数据一等公民**：name/tags/description/sha256/TTL/阅后即焚次数全部可查询
+- **CLI 即 API 契约**：JSON 输出 + 稳定退出码，agent 直接消费
+- **chunk 原生**：存储与传输的最小单元都是 8 MiB 块——并行、续传、秒传共用一套机制
+- **单一存储引擎**：flaxkv2 (LMDB)，元数据与数据块同一个 env，跨表原子写
+
+## 快速开始
+
+见根目录 [README.md](../README.md)。
+
+## 性能基线（loopback，1 GiB 不可压随机数据）
+
+| 操作 | 吞吐 |
+|---|---|
+| push（4 并发分块） | ~420 MiB/s |
+| pull（4 并发分块） | ~467 MiB/s |
+| 重复 push（秒传） | 0.7s（纯本地 hash 时间） |
+
+运行 `scripts/bench.sh` 复现。实际瓶颈在网络带宽，不在 flyfile。

flyfile-0.1.0/docs/api.md

@@ -0,0 +1,43 @@
+# HTTP API 参考
+
+前缀 `/api/v1`，除 `/health` 外均需 `Authorization: Bearer <token>`（token 为空则不校验）。
+错误体统一：`{"error": "<code>", "message": "...", "retryable": bool, "suggestion"?}`。
+
+## 对象
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| HEAD | `/blobs/{sha256}` | 秒传探测：200 已有 / 404 |
+| PUT | `/objects/stream` | 流式上传。元数据走 `x-ff-*` header（见下），body 为存储态字节流（chunked，无需 Content-Length）。返回 201 + 对象 JSON（含 `deduped`） |
+| GET | `/objects` | 查询。`name`（glob）、`tag`（可重复，AND）、`kind`、`created_after/before`（epoch 秒）、`limit`（默认 50）、`offset` |
+| GET | `/objects/{id}` | 元数据（含 num_chunks/chunking/compression，供下载规划）。404 不存在 / 410 已死 |
+| GET | `/objects/{id}/chunks/{idx}` | 下载第 idx 块（存储态字节）。**idx=0 原子认领 1 次 read**，失败 410；idx>0 不检查（宽限期语义） |
+| GET | `/objects/{id}/content` | 单流下载（全部块拼接，存储态），计 1 次 read。响应头 `x-ff-compression/sha256/size/kind/name` |
+| GET | `/objects/{id}/preview?bytes=N` | 不计 read。text/file → `{is_text, text, hex_head}`；dir → `{manifest}` |
+| PATCH | `/objects/{id}` | 更新 name/tags/description/manifest/ttl |
+| DELETE | `/objects/{id}` | 删除，blob refcount-- |
+
+`x-ff-*` 上传 header：`name`（URL-quoted）、`kind`（text/file/dir）、`compression`（none/zstd）、
+`tags`（逗号分隔，各自 URL-quoted）、`description`（URL-quoted）、`ttl`（秒）、`max-reads`、`content-type`。
+
+## 分块上传
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/uploads` | `{sha256, size, chunk_size, compression, meta}`。blob 已存在 → 201 `{object, deduped: true}`（秒传）；否则 `{upload_id, num_chunks}` |
+| PUT | `/uploads/{id}/chunks/{idx}` | body 为该块存储态字节（aligned：独立 zstd frame）。幂等 |
+| GET | `/uploads/{id}` | `{received: [...]}` 供断点续传 |
+| POST | `/uploads/{id}/complete` | 服务端流式解压校验 sha256。422 校验失败（清理会话）；409 缺块 |
+
+## C2C 中转
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/channels/{code}/send?timeout=N` | body 流式转发给接收端，元数据走 `x-ff-*`。409 code 被占 / 408 无人接收 |
+| GET | `/channels/{code}/recv?timeout=N` | 流式响应，`x-ff-*` 回填。408 无发送方 |
+| GET | `/channels/{code}` | `{state: none / waiting_sender / waiting_receiver / active}` |
+
+## 其它
+
+- `GET /health`（免认证）：`{status, version}`
+- `GET /api/v1/stats`：`{objects, blobs, stored_bytes, logical_bytes}`

flyfile-0.1.0/docs/architecture.md

@@ -0,0 +1,69 @@
+# 架构
+
+## 存储模型（flaxkv2 / LMDB，单 env 四个 sub_db）
+
+| sub_db | key | value |
+|---|---|---|
+| objects | 对象 id（8 字符 nanoid） | 元数据 dict（name/kind/tags/sha256/expires_at/max_reads/read_count/...） |
+| blobs | sha256（未压缩内容） | {size, stored_size, compression, chunking, num_chunks, refcount} |
+| chunks | `{sha256}:{idx:08d}` | 该块的存储态字节（zstd frame 或 raw） |
+| uploads | upload_id | 分块上传会话（received 列表、meta） |
+
+- **对象与 blob 分离 + refcount**：同内容多对象共享一份数据（dedup / 秒传）
+- **查询走全扫描 + Python 过滤**：单租户万级对象毫秒级，不维护二级索引（KISS）
+- **跨表原子写**用 `cross_db_txn`；**条件更新**（阅后即焚认领）用进程内锁串行化——
+  cross_db_txn 是"收集-提交"模型，事务内不可读，应用层锁在单 worker 下正确且最简
+- **已知取舍**：LMDB 文件删除后不收缩（空闲页复用，大小 ≈ 历史峰值水位）
+
+## 传输机制
+
+压缩（zstd-3）永远发生在**客户端**，服务端只存/转发存储态字节（零压缩 CPU）。
+跳过压缩：扩展名黑名单（zip/jpg/mp4/...）或前 128KiB 试压比 >0.95。
+
+两种 blob 形态（`chunking` 字段）：
+
+| | aligned | stream |
+|---|---|---|
+| 产生方式 | 分块上传（文件） | 流式上传（stdin/text/dir-tar） |
+| 块边界 | 每 8MiB **原始**偏移一块，各自独立 zstd frame | 单一 zstd 流按 8MiB **存储**字节切块 |
+| 下载 | 可并行拉块 + pwrite 定点写 + 按块续传 | 顺序流式解压 |
+
+多个独立 zstd frame 拼接仍是合法 zstd 流，所以两种形态共用同一套顺序解压代码。
+
+**push 决策树**（客户端）：
+- stdin / dir → `PUT /objects/stream`（边 tar 边压边传，无临时文件）
+- 文件 → 本地 sha256 → `POST /uploads`（服务端已有 blob 则秒传返回）→
+  并发 4 PUT 各块（独立 frame，幂等可重传）→ `complete`（服务端流式解压校验 sha256）
+- 续传：`~/.cache/flyfile/uploads.json` 按 (path,size,mtime,sha256) 找回会话，只补缺失块
+
+**pull 决策树**：aligned 且多块 → 并行拉块、解压后 pwrite 到 `.part` 预分配文件、
+`.part.json` 记进度、完成后整体 sha256 校验再原子 rename；否则单流 `/content`。
+dir 边解压边 untar，事后校验 sha256。
+
+**chunk 级网络重试**：分块路径的每个 PUT/GET 对传输层错误（连接被掐、瞬断）做
+3 次指数退避重试——WAN 上单连接瞬断是常态（跨洋实测 13 块并发上传曾被掐掉 3 块），
+分块 + 幂等使重试天然安全；应用层错误（4xx/410）不重试直接抛。
+
+## 生命周期（阅后即焚 / TTL）
+
+双保险：
+1. **惰性过滤**：所有读路径检查 `expires_at` / `read_count < max_reads`，
+   语义正确性不依赖后台任务
+2. **后台 sweeper**（60s 一轮）：物理删除已死对象 → blob refcount-- → 为 0 删全部 chunk
+   → 清理 24h 僵尸上传会话
+
+read 计数在下载**开始**时原子认领（`/content` 或 chunk 0），失败返回 410。
+并发 N+1 个请求恰好 N 个成功。**宽限期**：焚毁后 15 分钟内 chunk 仍可按 idx>0 拉取，
+保证在途并行下载能收尾；宽限期内不接受新的读（认领已失败）。
+
+## C2C 中转（relay）
+
+`POST /channels/{code}/send` ↔ `GET /channels/{code}/recv`，进程内
+`asyncio.Queue(16 × ≤1MiB)` 配对转发，**数据不经过存储层**，队列满即背压。
+先到方等待对方（默认 300s 超时 408）。取件码 `word-word` 由客户端生成。
+
+## 约束
+
+- **单 uvicorn worker**：relay 配对与阅后即焚锁都在进程内。垂直扩展够用
+  （瓶颈在网络 I/O，事件循环 + to_thread 足以打满带宽）
+- 认证是单 token Bearer，v1 单租户；token 为空则完全开放（仅限内网）

flyfile-0.1.0/docs/cli.md

@@ -0,0 +1,70 @@
+# CLI 参考
+
+命令 `flyfile`（别名 `ff`）。完整参数用 `flyfile <cmd> --help` 或 `flyfile schema <cmd>`（JSON）。
+
+## Agent 契约
+
+- **JSON 输出**：`--json` 强制；stdout 非 TTY 时自动。数据走 stdout，进度/提示走 stderr，永不交互
+- **错误**：stderr 一行 JSON `{"error", "message", "retryable", "suggestion"}`
+- **退出码（跨版本稳定）**：
+
+| 码 | 含义 | | 码 | 含义 |
+|---|---|---|---|---|
+| 0 | 成功 | | 5 | 冲突（目标已存在 / channel 被占） |
+| 2 | 用法错误 | | 6 | 已过期或已焚毁 (410) |
+| 3 | 不存在 | | 7 | 网络错误（retryable=true） |
+| 4 | 认证失败 | | 1 | 其他 |
+
+- **幂等**：push 内容寻址（重复 push 秒传，`"deduped": true`）；chunk 重传幂等；`rm --if-exists` 不存在时退 0
+
+## 配置
+
+优先级：命令行 `--server/--token` > 环境变量 `FLYFILE_SERVER/FLYFILE_TOKEN` >
+`~/.flyfile/config.yaml`（`flyfile config set server http://host:18632`）。
+
+## 命令
+
+```bash
+# 存取
+echo "text" | flyfile push - --name note --ttl 2h      # stdin → text 对象
+flyfile push model.bin --reads 1 --tag ckpt            # 阅后即焚
+flyfile push ./dataset/ --description "训练集 v2"       # 目录（流式 tar）
+flyfile pull <id或名字>                                # text → stdout；file/dir → ./name
+flyfile pull big100 -o out.bin --force                 # 名字解析：唯一命中直接用
+flyfile pull "log*" --latest                           # glob + 多命中取最新；歧义时报 exit 5 并列候选
+flyfile pull <id> -o -                                 # 强制 stdout（可接管道）
+
+# 查询 / 管理（info/preview 不消耗 read 次数；均支持 id 或名字 + --latest）
+flyfile ls --tag ckpt --kind file --since 2d --json
+flyfile info <id>
+flyfile preview <id> --bytes 4096                      # 文本头部 / dir 文件清单
+flyfile rm <id> [--if-exists]
+flyfile stats
+
+# C2C 直传（不落服务器存储）
+flyfile send ./results/ --json    # NDJSON: {"event":"code","code":"amber-falcon"} → done
+flyfile recv amber-falcon -o ./results/
+
+# 服务端 / 自省
+flyfile serve --port 8632 --data-dir /data --token SECRET
+flyfile schema [cmd]              # 命令树 JSON
+flyfile version
+```
+
+## Agent 使用范式
+
+```bash
+# 1. 传结果给另一台机器上的 agent：send 的 code 事件在传输开始前就输出，
+#    拿到 code 立即通过其它信道告知对方，无需等待传输完成
+flyfile send big.tar --json | while read -r ev; do ... done
+
+# 2. 先看再拉：preview 不消耗阅后即焚次数
+flyfile preview k3x9m2pq --json | jq -r .text
+flyfile pull k3x9m2pq
+
+# 3. 判断可重试：exit code 7 或 error body 里 retryable=true 才值得重试
+flyfile pull $ID || { [ $? -eq 7 ] && retry; }
+
+# 4. 管道串联
+flyfile pull $LOG_ID -o - | grep ERROR | flyfile push - --name errors --ttl 1h
+```

flyfile-0.1.0/docs/flaxkv2-feedback.md

@@ -0,0 +1,42 @@
+# flaxkv2 dogfooding 反馈（来自 flyfile 开发，flaxkv2 0.2.14）
+
+flyfile 把 flaxkv2 用作唯一存储引擎（元数据 + 8MiB 数据块）。总体验证结论：
+**能胜任**——8MiB value 写 2.6 GB/s / 读 4.4 GB/s（页缓存加成），map_size 自动扩容、
+cross_db_txn、多线程并发、写删后空闲页复用全部符合预期。以下是过程中发现的改进点：
+
+## 1. 缺少 `pop(key, default)` 方法
+
+`RawLmdbDict` 有 `get/__contains__/__delitem__` 但没有 `pop`——这是最常用的
+"存在即删"字典习语。flyfile 只能自己包一个 try/del/except KeyError（`store.py` 的 `_pop`）。
+建议在 `BaseLmdbDict` 补 `pop`（顺手可加 `setdefault`）。
+
+## 2. 实例缓存 + close 的语义陷阱（最重要）
+
+`db_instance_manager` 让同进程内同 (name, path, sub_db) 返回**同一个实例**。
+后果：A 处 `close()` 会把 B 处正在用的"另一个"db 一起关掉（`self._db = None`，
+后续访问报 `AttributeError: 'NoneType' object has no attribute 'get'`）。
+
+flyfile 测试里踩到：测试代码对同一 data_dir 开了第二个 Store 并 close，
+把正在运行的服务端句柄关了。对使用者来说这是很难排查的 spooky action at a distance。
+
+建议之一：close 也走引用计数（第 N 次 close 才真关）；或 close 后自动失效重开；
+或至少在文档里显著标注"同参数实例是共享的，close 影响所有持有者"。
+
+## 3. `keys()` / `items()` 返回完整 list
+
+大库上容易误用导致内存峰值。`keys_iter()/items_iter()` 已经存在且好用（还支持
+prefix/start/stop），但默认名字 `items()` 更顺手、更危险。建议文档强调，或让
+`items()` 返回迭代器（破坏兼容，可放大版本）。
+
+## 4. cross_db_txn 是"收集-提交"模型，事务内不可读
+
+做"读-判断-写"条件更新（flyfile 的阅后即焚计数认领）时用不上，只能退回应用层锁。
+LMDB 本身的写事务是支持事务内读的；如果 cross_db_txn 能提供 `txn.get()`（在同一
+write txn 里读），条件更新就能做到真正的存储层原子。这是把 flaxkv2 用于
+"并发状态机"类场景（计数器、队列认领、乐观锁）的关键缺口。
+
+## 5. 小点
+
+- `keys_count()` 很实用，但藏得深，SKILL.md 没提
+- 8MiB bytes value 实测无问题，SKILL.md 中"不要存大对象（超过几 MB 考虑外存）"
+  的表述可以放宽为具体数字（例如"单 value 建议 ≤16MiB，分块场景实测 8MiB 无压力"）

flyfile-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flyfile"
+version = "0.1.0"
+description = "Agent-native data transfer: push/pull/send anything between agents and machines"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "httpx>=0.27",
+    "typer>=0.12",
+    "zstandard>=0.22",
+    "flaxkv2>=0.2.14",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+flyfile = "flyfile.cli.main:app"
+ff = "flyfile.cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flyfile"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "B006"]

flyfile-0.1.0/scripts/bench.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# 1 GiB loopback 吞吐冒烟：目标是瓶颈在磁盘/回环而不在 flyfile 代码。
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+PY=.venv/bin/python
+FF=.venv/bin/flyfile
+WORK=$(mktemp -d)
+DATA=$WORK/data
+PORT=18632
+trap 'kill $SERVER_PID 2>/dev/null || true; rm -rf "$WORK"' EXIT
+
+echo "== generating 1 GiB random file =="
+head -c 1G /dev/urandom > "$WORK/big.bin"
+
+$FF serve --host 127.0.0.1 --port $PORT --data-dir "$DATA" --token bench >/dev/null 2>&1 &
+SERVER_PID=$!
+for i in $(seq 50); do curl -sf "http://127.0.0.1:$PORT/health" >/dev/null && break; sleep 0.2; done
+
+export FLYFILE_SERVER=http://127.0.0.1:$PORT FLYFILE_TOKEN=bench
+
+echo "== push (chunked parallel, incompressible -> raw) =="
+T0=$(date +%s.%N)
+ID=$($FF push "$WORK/big.bin" --json | $PY -c "import sys,json;print(json.load(sys.stdin)['id'])")
+T1=$(date +%s.%N)
+$PY -c "print(f'push: {1024/($T1-$T0):.0f} MiB/s ({$T1-$T0:.1f}s)')"
+
+echo "== pull (parallel chunk fetch) =="
+T0=$(date +%s.%N)
+$FF pull "$ID" -o "$WORK/big.out" --json >/dev/null
+T1=$(date +%s.%N)
+$PY -c "print(f'pull: {1024/($T1-$T0):.0f} MiB/s ({$T1-$T0:.1f}s)')"
+
+cmp "$WORK/big.bin" "$WORK/big.out" && echo "integrity: ok"
+
+echo "== dedup re-push =="
+T0=$(date +%s.%N)
+$FF push "$WORK/big.bin" --json | $PY -c "import sys,json;d=json.load(sys.stdin);assert d['deduped'],d"
+T1=$(date +%s.%N)
+$PY -c "print(f'dedup push: {$T1-$T0:.2f}s (hash only)')"
+
+echo "== LMDB file size =="
+du -sh "$DATA"
+
+echo "== churn: write+delete 5 rounds, file size should plateau =="
+for r in $(seq 5); do
+  head -c 128M /dev/urandom > "$WORK/churn.bin"
+  CID=$($FF push "$WORK/churn.bin" --json | $PY -c "import sys,json;print(json.load(sys.stdin)['id'])")
+  $FF rm "$CID" >/dev/null
+  echo "round $r: $(du -sh "$DATA" | cut -f1)"
+done

flyfile-0.1.0/src/flyfile/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"