企业官网建设流程全解析

Local-First 安全详解：zvec-grep 数据边界、远程模型授权与本地鉴权机制

【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep

zvec-grep（zg）是一个"本地优先"（Local-First）的工作区搜索工具，面向人类开发者和 AI Agent 提供统一的搜索接口：代码、文档与结构化数据都留在你的机器上，只有在你明确授权后，内容才会发送给远程嵌入模型。本文带你完整了解它的三层安全设计：数据边界、远程模型授权、本地鉴权存储。

什么是 Local-First 安全？

大多数搜索/索引工具会把文件内容当作"过路数据"，而 zvec-grep 的安全模型从一开始就回答了一个关键问题：

我的代码会流向哪里？

答案分两种模式：

• 本地模式（默认）：源文件、索引、本地嵌入模型全部停留在本机，查询文本也绝不离开机器。
• 远程模式（可选）：当且仅当你显式选择远程嵌入模型并授权后，已披露的数据（查询文本、变更文件等）才会发送到指定端点。

一句话总结：Local by default, remote only with your permission.

第一层：数据边界——文件都放在哪？

zvec-grep 把所有本地数据收敛到两个可预期的位置：

本地模型（如local/potion-code-16m-v2）从 Hugging Face 下载后缓存到本机；若下载失败，会自动回退到固定版本、经完整性校验的 ModelScope 副本。模型选型与缓存策略详见 07-embedding.md。

第二层：远程模型授权——发数据前先"问路"

当你选择远程嵌入模型（例如qwen/qwen3.7-text-embedding）时，zvec-grep 会先制定授权计划，再决定是否需要询问你。计划逻辑位于 planner.ts，核心规则：

• 只有远程模型才需要授权：本地模型（provider 为local）永远不触发授权流程，数据天然不出本机。
• 披露内容精确到"发什么"：授权计划会明确列出本次操作要发送的数据类别——
  • 索引操作：selected workspace files（全量或仅变更文件）
  • 向量查询：query text（你的查询文本）
  • 纯词法搜索或索引已新鲜时：零数据发送，无需授权
• 授权提示透明可读：提示框会显示From（哪个工作区）→To（哪个 provider/model 与端点主机），并注明 "API charges may apply"。格式由 prompt.ts 生成。
• Agent 场景同样受保护：当 MCP 宿主不支持授权交互时，Agent 必须改用宿主自带提问工具向你确认，且在未收到决定前不会发送任何远程数据（见 03-mcp.md）。

一次典型的授权交互

Remote Embedding authorization Send query text and changed workspace files? From my-project To qwen/qwen3.7-text-embedding api.example-host.com API charges may apply.

你在交互中选择"允许 / 仅用本地 / 取消"三种之一。允许后，授权范围是当前工作区，而不是全局。

第三层：本地鉴权——带签名的"许可证"

授权一旦授予，zvec-grep 会把它落盘为一份带 HMAC 签名的授权文档，实现位于 store.ts：

1. 指纹锁定目标：工作区根路径先做realpath规范化再取 SHA-256 指纹，与 provider、模型、端点一起构成"目标指纹"（见 target.ts）。换端点、换模型、换目录，旧授权自动失效。
2. HMAC-SHA256 签名：每次授权由本机签名密钥对授权内容签名；验证时使用timingSafeEqual恒定时间比较，抵御时序攻击。
3. 严格文件权限：授权文件与密钥文件均以0600写入、目录0700，并带读写锁防止并发写坏文档。
4. 可随时吊销：revoke/revokeAll支持按目标吊销或清空整个工作区的所有授权，吊销会同步清理多根目录下的副本。

用 CLI 管理授权

管理逻辑位于 auth.ts，三个动作覆盖完整生命周期：

# 查看当前工作区的授权状态与有效性 zg --auth status # 显式授予某远程模型对当前工作区的授权 zg --auth grant # 一键吊销所有远程嵌入授权 zg --auth revoke

授权管理器 manager.ts 还负责"已有授权直接放行、否则走交互"的判定，确保每次远程调用前都会复核签名是否仍然有效。

给新手的 4 条安全建议

1. 默认什么都不用配：本地模型模式下，代码与查询文本永远不出机器，这是最省心的用法。
2. 选远程模型前先想清楚：远程嵌入会发送披露的数据，且可能产生 API 费用。
3. 离开团队/换端点前：跑一次zg --auth revoke干净离场。
4. 多工作区隔离：授权是工作区级的，A 项目的授权对 B 项目无效，天然防止"一次授权，处处放行"。

小结

zvec-grep 的 Local-First 安全不是口号，而是三层可验证的机制：

数据留在本地是默认，流向远程是例外——而例外，必须由你亲自签字。更多设计细节可参考 docs/05-architecture.md 与 docs/04-pipeline.md。

【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep