形态裁决:light / PRO 的定位与演进路径(待拍板)

[LAWTED]

本 issue 记录一次形态裁决的完整思考过程,结论尚未拍板,相关实现见 #7(草稿,建议先不合)。
写下来是为了让决策脉络可追溯——中间有几处我的判断被推翻过,过程比结论更值得留存。

一、先把三种形态的定义钉死

之前混用了「轻形态 / 托管形态 / light / pro」等说法,导致讨论里出现过实质性误解。统一如下:

	light	PRO
机器	用户自己的	我们提供一台常驻机(Mac mini)
agent	用户自己已有的 Claude Code	我们部署 Claude Code
IM 接入	无	反代到飞书 / 钉钉
我们交付什么	vault + 接入方式 + skill	机器 + agent + IM + vault + skill

light 的前提假设是「团队里每个人已经有 Claude Code」。 这条假设成不成立,决定了这家公司
能不能走 light——它是采纳问题,不是技术问题。

二、现状与适配判断

• 现有付费客户全部是 PRO。light 目前零外部客户。
• HA7CH 自己适合 light——团队人手一个 Claude Code,前提假设天然成立。
  light 的第一个用例是我们自己(dogfooding)。

这条很重要:light 不是「一个没人要的形态」,而是「第一个客户是我们自己」。自己先用起来,
再谈对外交付。

三、一个必须记下来的判断修正

讨论中我一度以为某个 PRO 客户在跑 light,并基于此推导了一整套云端分层架构。事实是它从
一开始就是 PRO,早期试过的云端方案已废弃并从仓库移除。

修正之后的关键认知:

在 PRO 模式下,vault 就在那台常驻机的磁盘上,agent 直接 Grep/Read——
「本地读不到云上文件」「传输 GB 级原件」「服务端搜索截断」这些问题全都不存在。

所以云端分层那套东西,解决的是 light 的问题,不是 PRO 的问题。这也解释了为什么 PRO 客户
用得好好的——它们根本没走那条路。

四、技术裁决(已实测验证,与形态无关)

这几条在任何形态下都成立,建议直接固化为约定:

1. MCP 是控制面,不是数据通道

MCP 的工具参数是模型逐 token 生成的字符串。一个 4 MB 文件 ≈ 550 万 base64 字符
≈ 150 万 token 输出。agent 内联二进制的实测上限约 100–150 KB。

所以「让 agent 通过 MCP 读写整个 vault」在体量上就是死的,与服务端写得好不好无关。
原件必须走独立的字节通道(流式 HTTP),由脚本/CLI 搬运,不经过模型。

2. vault 按访问模式分层

层	判定	怎么处理
index	文本文件,且路径中无 _originals 段	全量同步到每个客户端,agent 用 rg 全速搜
originals	路径中任一层目录名为 _originals	不同步,按需单取
history	_history/ 开头	只读,不同步
blob	其余二进制	不同步,按需取

判定按路径片段而非顶层前缀——真实 vault 里 _originals/ 是嵌套在各项目里的。
<项目>/_ocr/ 下的 OCR 产物是 .md,自动落进 index 层。

典型 vault 里结构化 markdown 只占总体积的千分之几,所以 index 层的增量同步是毫秒级的。
「唯一一份 + 全员即时可见 + 本地全速 grep」三者可以同时成立——要同步的从来不是那些 GB。

3. 穿透搜索靠的是文本投影,不是原件

扫描件没有文字层时,grep 在任何形态下都是零命中——本地也好云上也好。这是 ingest 工序
问题(需要 OCR 产出 _ocr/ 文本层),不是架构问题。

且纯影像类原件(现场照片、证书扫描)即使 OCR 也搜不出内容,只能靠入库时写一句描述进 index 层。

4. 可发现性与字节可以分离

原件字节不出内网时,把原件清单(路径 / 大小 / hash / 在哪台机器)作为文本放进 index 层。
于是所有客户端都知道这份原件存在、多大、在哪,即使取不到字节——溯源链完整。

这条是「原件不上云」这个约束下的关键手法。

5. 同一套接口契约,多个后端实现

GET  /manifest       清单(只 list 不读内容,带整体 ETag → 无改动时空往返)
GET  /raw/<path>     流式读(Range / If-None-Match)
PUT  /raw/<path>     流式写

同一份契约可以有两个实现:对象存储后端(云上)、文件系统后端(常驻机上)。
客户端代码一行不用改,只是指向不同 endpoint。 这是形态之间能渐进迁移的技术前提。

五、实测撞出来的 9 个静默出错

共同点:使用者会拿到错误答案而不自知。#7 里已全部修复并有回归测试(56 项全绿)。

#	问题	后果
1	搜索全局命中数封顶后终止扫描	后面的文件一个字节没读,提示只说「已截断」
2	单个超预算文件导致 break scan	该范围任何搜索永久返回 0 命中
3	截断原因不区分	分不清是「没有」还是「没搜到」
4	目录列举的前缀查询恒返回空	按名称前缀筛选完全不可用
5	覆盖写的 CAS 窗口仅毫秒	「上午读、下午写」静默抹掉他人改动,双方零提示
6	声称支持 6 MB base64 二进制	agent 实际搬不动(见裁决 1),白试
7	中文作者名经 HTTP header 传输	直接抛异常(header 值只能是 ByteString)
8	写入后不更新本地清单	下次同步把该文件当「远端新增」冲掉本地改动
9	同步遇冲突后保留旧版本号	合并完也永远提交不进去(死锁)

7–9 是在真实大体量库上跑测试撞出来的,假数据测不出来。

⚠️ 第 5、8、9 条与形态无关,PRO 现在就有这个风险:两个人先后让 bot 改同一份报告,
或者一个人在 IM 里改、另一个人在自己机器上改同一个文件,一样会静默覆盖。
修法是强制 read-before-write(写入必须带读取时拿到的版本号,过期即拒),
逻辑与存储后端无关,可以原样搬到本地实现。

六、light 落地的最简架构(如果走这条)

对已有常驻机的公司,light 不是另一套部署,而是「那台机器多开一个端口」:

常驻机(唯一真相源)
  ├── vault/            md + 原件,全在本机磁盘
  ├── Claude Code       常驻 bot ──→ 飞书 / 钉钉        ← PRO 的部分
  └── anc-serve         暴露 /manifest + /raw           ← 新增,约 150 行
          ↑
          │  Tailscale / 内网
          │
   成员自己的 Claude Code                                ← 这就是 light
       anc pull → 本地 index 镜像,直接 rg

零云依赖、零额外成本、原件不出内网。

对没有常驻机的公司(如果将来有),才需要把 index 层放到对象存储上——那就是 #7 实现的东西。

关于「原件不上云」时的取件降级

成员在外网取不到原件时,必须明确报错并给替代路径,不能静默失败:

✗ 原件服务不可达
  这份原件确实存在:12.3 MB,2026-07-20 入库,在「所内常驻机」
  取它的三条路:
    1. 连上内网 / Tailscale 后重试
    2. 在 IM 里 @bot 要这份文件
    3. 只需要内容的话:已有 OCR 文本 → 直接读 _ocr/ 下的对应 md

补充一条容易踩的:Cloudflare Tunnel 不满足「原件不上 Cloudflare」的严格解释——
数据不落对象存储,但要经过 CF 边缘且 TLS 在那里终止。要 CF 完全不碰原件,走 Tailscale
或纯内网。

七、成本(如果走云端 index)

R2 公开定价:存储 $0.015/GB·月
(前 10 GB 免费),出网免费。含 Workers Paid($5/月)的实际月账单:100 GB → $6.4,
500 GB → $12.4,1 TB → $19.9。

出网免费是「按需取原件」这个设计能成立的前提——换成按流量计费的对象存储,同样的用法
会变成随使用量波动的不可预测开销。

但结论不是「几百 GB 上云不贵所以全上」,而是大部分本来就不该上:影像、压缩包、账套占了
体积的大头,而它们的在线价值最低(纯图像 grep 不到,没人在线拆 zip)。

八、待拍板

1. light 是独立产品形态,还是 PRO 的附加能力?
   倾向后者:对已有常驻机的公司,它就是多开一个端口;对我们自己(无客户机器、人手 Claude Code),
   它是主形态。
2. HA7CH 自己先用 light 跑起来? 前提假设天然成立,适合 dogfooding。
   需要先确定我们自己的 vault 放什么、原件形态如何(这决定走 git 还是走对象存储)。
3. feat(light): 云上 index 分层实现 —— 无常驻机场景(待裁决,见 #8) #7 合不合? 它实现的是「无常驻机 + 云上 index」这条路。若近期没有这类客户,
   建议保持草稿,当作接口契约与教训的沉淀。
4. 写入护栏要不要先落到 PRO? 第 5/8/9 条的风险 PRO 现在就有。这件事与形态裁决无关,
   可以独立推进。

九、优先级建议

1. 备份——原件若只在一台机器上,而档案有法定保存年限,这台机器挂了就是事故。
   比任何架构演进都急,且与形态无关。
2. 写入护栏——强制 read-before-write。PRO 现在就有静默覆盖风险。
3. light 落地(anc-serve + 双 endpoint)——服务的是每家公司里的少数几个人,
   价值真实但不紧急;对 HA7CH 自己则是主路。
4. feat(light): 云上 index 分层实现 —— 无常驻机场景(待裁决,见 #8) #7 那条云端路线——等真有无常驻机的客户再启用。

相关

• feat(light): 云上 index 分层实现 —— 无常驻机场景(待裁决,见 #8) #7 云端 index 分层实现(草稿):四条接口、CLI(init/pull/status/open/push)、
  56 项回归测试、形态选型文档 docs/VAULT-FORMS.md
• 已知缺口:>100 MB 单文件需要 multipart 分片,尚未实现;anc init 的形态自动探测与
  报价尚未实现