字huozi.app

文档

huozi 是一个 Agent 原生的云盘 —— 通过 MCP 暴露文件树,任何 MCP 客户端(Claude Code / Cursor / Hermes / OpenClaw / Cowork / 任意 Agent)都能把它当作共享工作区。本文档覆盖 Cloud / Edge 两个版本、两条 pipeline(RFC 8252 OAuth + RFC 8628 device flow)、以及 16 个 MCP 工具。

目录

文档按下面分类组织。每张卡片是一个独立子页(深度链接友好);右侧/顶部边栏在所有 /docs 页都能切换。

Getting started

复制粘贴一行,Agent 自己装。或者按你客户端的原生 CLI / GUI 装。

Cloud vs Edge

两个版本如何不同(登录、workspace 模型、注册),以及怎么选。

两条 pipeline

RFC 8252 OAuth-on-first-use(本地终端)vs RFC 8628 device flow(Agent 自己装)。

HTTP API reference

/.well-known、/auth、/oauth、/mcp、/llms.txt —— 端点契约 + curl 示例。

MCP tools reference

16 个 huozi_* 工具:Claude Code 方言 5 个 + huozi 扩展 11 个。

Agent integration

llms.txt 协议、?for=<kind> 过滤、agent_kind 枚举。

Self-host (Edge)

一行 curl 部署到你自己的 Cloudflare 账号。

Source code

MIT 授权,GitHub 上的 huozi-cloud Worker + Next.js app。

Concepts

术语含义
Workspace一棵带版本历史的文件树,R2 后端。地址 ws_<slug>。
Connection一个 api_key 发给一个 Agent(你笔电的 Claude Code、CI runner 等)。可独立撤销。
Commit每次 write / edit / delete 都产生一个 commit。通过 huozi_history 工具按文件查询。
EditionCloud(huozi.app 托管,多 workspace,OTP 登录)或 Edge(部署到你自己的 Cloudflare,单 workspace,密码登录)。详见 /docs/editions.

MCP tools

16 个工具,分四类。前 5 个与 Claude Code 文件工具方言完全等价;其余是 huozi 扩展(原子批处理、不可变历史、二进制资产、公开分享、身份)。

Claude Code 方言 (5)

工具用途
huozi_read按行读取文件(支持 offset/limit 分页)。返回 cat -n 风格的文本,或会话已缓存时返回 file_unchanged。
huozi_write一次 commit 创建或覆盖文件。
huozi_edit字符串替换式精修:old_string → new_string。要求 old_string 在文件内唯一,或加 replace_all。返回 unified diff。
huozi_glob快速路径列举,D1 索引后端。
huozi_grep正则搜索,FTS5 trigram 预过滤,比遍历快 50 倍。

目录与版本 (6)

工具用途
huozi_list_tree把一个 prefix 列成目录树。深度有限、可分页;空目录隐式存在(folder 存在 iff 其下有文件)。
huozi_mkdir用一个隐藏的 .huozi-keep 标记保留空目录名。
huozi_mv重命名或移动文件。原子 commit;历史链跨重命名保留。
huozi_rm删除文件。记为单独 commit,通过 huozi_history 可见(可恢复)。
huozi_batch_edit跨一个或多个文件的 N 个编辑,作为一个 commit 原子应用。每文件独立结果;写入前做 staleness 检查。
huozi_history文件的 commit 日志:sha、author、操作(create/edit/write/batch)、+/- 行数、message。

二进制 / 资产 (3)

工具用途
huozi_upload入站二进制,base64 流式存进 R2。返回 SHA-1 + size;文件出现在 workspace 树中。
huozi_download拿到一个时限签名 URL 直接从 R2 取二进制 —— 不经 Worker 代理。
huozi_image_render服务端 SVG → PNG(resvg-wasm)。给需要像素而不是 markup 的 Agent 用。

发布与身份 (3)

工具用途
huozi_template拉一个 HTML 脚手架(deck / story / paper / mobile / page 五选一)给 Agent 填。
huozi_share把一个文件发布成 huozi.app/p/<slug> 跟踪当前字节的实时 URL。编辑立即生效。
huozi_whoami返回当前 principal、workspace 与 scope prefix。Agent 行动前用于自检。

更多