ZCode AI 编程工作台安全边界解读：权限模型、数据行为与第三方组件声明

本文基于 ZCode 仓库 NOTICE.md 官方声明，系统梳理 AI 编程工作台在自动化执行、权限审批、网络请求、本地数据与第三方许可方面的边界与风险。读者将掌握 ZCode 的权限模式（plan/build/edit/yolo）如何影响工具放行、理解各运行形态（桌面端、Web、CLI、远端）在数据存储与网络行为上的差异，并学会在部署与使用中正确设置安全边界、识别未经核实的能力承诺。

一、声明总览：为什么需要一份“功能说明与第三方组件声明”

ZCode 是智谱 AI 提供的 AI 编程工作台，涵盖桌面应用、浏览器界面和终端 Agent，本仓库同时包含客户端、后端服务、共享 UI 与 Agent CLI 运行时。由于项目存在 Desktop（Electron）、Web / ZCode 命令行版（TUI + Web + Agent）、Agent CLI 三种主要运行形态，NOTICE.md 开篇即强调：各运行形态的功能、权限、存储位置和网络行为不同，不能将其中一种形态的默认设置理解为整个项目的统一设置。这句话是理解全文的钥匙——后续所有关于执行权限、数据目录、日志与凭据的结论，都必须按运行形态分别对待。

二、AI 输出、执行权限与自动化风险

2.1 模型输出不可视为事实或授权

NOTICE.md 明确：AI 生成的代码、命令、解释、文件和建议可能存在错误、遗漏、安全缺陷或第三方权利问题，必须结合实际文件、命令退出状态、工具结果和测试进行核查；模型声称“已完成”“已安全处理”或“已获授权”不构成事实或授权证明。这是对 AI 编程工具使用者的第一安全准则：重要操作前审查执行目标、接收方及影响，并保留可恢复的备份。

2.2 执行范围由操作系统账号决定，而非页面所在设备

文件、终端、Git、Agent 工具及外部进程在实际运行它们的操作系统账号权限范围内读写文件、启动进程和访问网络。在 Web 或远端工作区中，操作可能发生在服务端、SSH 主机、WSL 或容器环境，不能仅凭当前页面所在设备判断执行位置。尤其需要留意：

• 当前共享 Agent 执行适配器不提供默认的操作系统沙箱；
• 工作目录、工作区身份、Git worktree、浏览器页面隔离和 Node REPL 的运行上下文，均不应被当作所有工具的系统级隔离保证。

2.3 权限模式：build 默认与 yolo 回退

NOTICE.md 指出两处关键默认值，均可从源码得到印证：

1. 共享运行配置默认采用 build 权限模式。权限模式的合法取值定义于 adapters 配置 schema，包含 plan、build、edit、yolo、auto 五种。
2. 独立 CLI 通过 --prompt 执行非交互任务时，未指定 --mode 会采用 yolo。该默认值定义在 CLI 入口 run.ts：

const DEFAULT_HEADLESS_PROMPT_MODE: CliPermissionMode = "yolo";

并在 --prompt 分支中以 mode ?? DEFAULT_HEADLESS_PROMPT_MODE 回退（run.ts）。

这两种默认值意味着：交互会话、桌面会话、恢复的任务及宿主可使用各自配置、保存或传入的模式，是否逐次确认受工具声明、权限规则及运行模式影响。在权限判定核心 permission/service.ts 的 checkPermission 中可以看到分层逻辑：

• 需要用户交互的工具（capability.requiresUserInteraction）会触发 ask 确认；
• 声明 alwaysAsk 的工具必须经过用户确认，不能被权限模式的放行分支绕过（service.ts）；
• yolo 模式且未启用只读规划约束（planEnabled）时，普通工具直接放行（service.ts）——这正是 NOTICE.md 所述“未同时启用只读规划约束的 yolo 会放行普通工具操作”的源码依据。

需要强调：模型工具审批不是整个应用的统一权限开关，不能据此推定终端操作、插件进程或更新下载都会经过同一审批流程。

2.4 能力与业务钩子的影响边界

NOTICE.md 以表格形式列出各能力钩子的影响边界，这里完整继承并归纳为四组：

能力或业务钩子	可能产生的影响及边界
文件、Git、终端、Shell、Node REPL	可读写或删除数据、运行程序和访问网络；Git、包管理器及用户命令可能触发自身脚本和钩子。任务快照、Git 检查点和会话恢复不能替代对全部本地文件、数据库及外部服务的备份
用户及工作区指令、技能	工作区指令文件、技能文本、模板和脚本会影响模型计划；读取、安装或展示它们不代表内容可信、合法或经过官方安全审查
生命周期 Hooks	SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop 可触发命令或进程；输入可能包含提示词、工作路径、工具参数、工具结果和回复；Hook 还可补充上下文、改写工具输入或参与权限决策
工作区 Hook 信任	工作区 Hook 按工作区身份和声明摘要审查，声明变化会使原信任失效；该机制不等于对插件 Hook、MCP 配置或其他项目脚本的统一审核
插件与 MCP	启用插件可带入自动执行的 Hook、本地程序和远端工具；当前 Agent 运行配置将工作区级 MCP 纳入自动连接范围，启用 MCP 启动运行时时可能使用配置中的命令、环境变量、认证头或 OAuth 连接服务；插件 Hook 与工作区 Hook 使用不同准入路径
启动与安装脚本	桌面或终端为获取 Shell 环境可能执行登录 Shell 及其启动配置；依赖安装可运行原生模块构建等生命周期脚本，相关脚本可能早于模型任务运行，不应理解为仅执行模型逐项批准的命令
子代理、工作流与后台任务	可继续调用模型、执行命令并产生费用或外部副作用；停止会话、切换页面或取消某次请求，不能撤销已经完成的文件写入、发布、上传或其他外部操作
桌面定时任务与闲时任务	在调度器及执行宿主可用时按所存配置运行，可在窗口隐藏后继续执行；关闭窗口可能只是隐藏到后台或托盘；显式退出、休眠、断网、账号或模型不可用都可能影响执行；不能保证关机后仍运行或错过的任务一定补跑，独立 CLI 也不因包含 Cron 工具就自动具备持久调度服务
内嵌浏览器与 Browser Use	可访问网页、读取页面内容、截图或录制页面，并执行点击、输入、上传和下载；经用户操作导入或复用的浏览器登录状态可能允许访问私人数据、提交表单或改变远端账号中的内容
Computer Use	本仓库随附的 Computer Use 包为不可用占位实现，调用会返回不可用错误，不提供系统截图或操作能力。见 Computer Use 入口，其 execute 恒返回 "Computer Use is not available in this build." 且 isError: true
Web 服务与远端运行环境	网络可达范围、登录认证、进程账号和文件权限由具体部署共同决定；认证默认值因启动入口和监听地址而异
内容分享、导入与资源预览	可能读取或传输对话、代码、附件及生成物；导入的共享上下文、网页和文件属于外部输入，不能因来源显示为 ZCode 链接就自动视为可信指令或取得其中内容的版权授权

2.5 处理不可信项目的建议

网页、仓库内容、工具返回值和第三方指令可能包含诱导模型执行额外操作的内容。NOTICE.md 给出的处理原则是：处理不可信项目时，应限制运行账号、凭据和网络权限，并审查敏感操作。

2.6 远端服务的监听边界

自行部署 Web 或远端服务时，应按实际入口配置认证、传输保护和访问控制；应用账号登录不能代替部署层的安全边界。关键源码证据在 zcode-server-cli 核心 HTTP 服务：

const host = options.host ?? "127.0.0.1";
if (!isLoopbackHost(host)) {
  // 当前只有本机/SSH 隧道入口，Core 尚未接入 token middleware；对外监听必须 fail-closed。
  throw new Error(
    `Non-loopback host ${host} requires authentication before the server can listen`,
  );
}

这印证了 NOTICE.md 的表述：独立远端服务核心仅接受本机回环监听地址，未提供同等的外部账号鉴权，非回环监听会直接 fail-closed 拒绝启动。此外，HTTP／WS 与 HTTPS／WSS、SSH 的保护条件不同，不保证所有部署默认加密，也不保证远端主机或服务运营者无法访问其处理的数据。

三、上传接口、对外请求与业务用途

NOTICE.md 用一张大表列出各业务场景的用途、触发条件与数据范围。核心要点如下：

业务场景	业务用途、触发条件与数据范围（要点）
模型与辅助模型请求	任务执行、压缩、标题、记忆、历史会话提取、目标完成验证、AI Git 提交信息生成和模型连通性测试可调用模型；发送相关提示词、历史、代码、diff、工具结果或附件，连接测试使用固定探测消息；Anthropic 兼容调用会附加设备和会话标识
登录、授权、账号与 API 凭据	登录、授权码交换、登录状态轮询、账号及权益查询可发送授权状态、code、访问令牌等；登录后或账号配置解析时可能自动查询、获取或创建项目 API Key；当前内置账号适配器未实现账号刷新令牌交换
套餐、订单、支付与额度	额度重置同步、机会请求、状态轮询和已读核销可自动触发；仓库提供已注册的订单试算／创建／取消、续订、支付方式管理接口——服务方法存在不代表各发行形态均有可用购买界面
官方 Coding Plan 模型网关转发	对代码列出的两个官方 Anthropic 兼容模型端点按协议、主机、有效端口和路径匹配，命中时自动改发 ZCode 网关并保留认证信息；网关 origin 可由 ZCODE_BASE_URL／ZCODE_ENDPOINT_ORIGIN 配置改变；此转发未设置额外的逐次用户确认
提供商、业务配置与连通性检查	后台检查、配置刷新、服务检查可访问提供商目录、业务配置、帮助内容和 CDN；部分请求独立于模型任务运行，不要求每次手动刷新
搜索、网页处理与远程资源	当前 WebSearch 通过支持原生搜索的模型提供商执行；WebFetch 抓取的内容还可能连同处理提示发送给模型，不应把网页下载理解为后续仅在本地处理
MCP 连接、OAuth 与工具调用	启用 MCP 可自动连接工作区或插件声明的服务、协商协议、发现工具；OAuth 支持发现、客户端注册、授权交换及自动令牌刷新；工具调用可自动附加工作区绝对路径、工作区身份、会话标识等；工具审批不统一覆盖连接、发现和刷新流程
SSH／WSL／容器及其他执行环境	个人提供商配置、账号选择及允许同步的账号 API Key、OAuth 令牌等可在环境首次上线及配置变化时自动传入目标环境，没有单独的逐项凭据确认步骤；这些传输不必然到官方云端
Skills、MCP、插件与配置同步	可将技能或插件目录、市场来源及配置传至目标环境；MCP 配置可含命令参数、环境变量、请求头、认证信息和本机路径；部分插件选项有敏感字段筛选，但不构成对目录归档和所有配置的全面秘密检测
附件传输与媒体预览	附件加入输入区并具备执行会话后，可能在点击发送消息前开始预传输；本地文件路径可直接引用而不上传；本地或跨环境处理不等于公开发布
会话分享、浏览与导入	分享操作可向分享服务提交选中会话行的公开投影及可物化附件；正常 UI 发布流程要求先确认披露并校验确认时间；当前 UI 默认公开可导入，浏览与导入不以发布勾选为前提；本地删除或取消不保证外部已上传副本被删除
闲时任务票据与状态同步	可用性查询、取号排队、票据状态同步及核销会发送任务标识、票据标识及认证信息；这类请求不等于发送完整任务提示词
主动反馈、补充消息与诊断附件	反馈表单可发送正文、联系方式、截图及文件名；桌面日志选项默认不勾选；附件先向反馈服务申请上传凭证，再直传对象存储；文本处理规则不保证截图和任意文件已脱敏
安装、插件获取、远端部署与更新	会访问仓库、包服务、插件市场、CDN 或更新服务器；统一 CLI 安装脚本从配置的分发源读取版本清单并下载发行包；打包版会忽略 ZCODE_UPDATE_FEED_URL 环境变量及 --zcode-update-feed-url 启动参数的更新源覆盖（仅开发构建可用）
工具、Hook、工作流与自动任务的交付或发布	可向目标服务上传文件或生成物并改变外部服务状态；发布、发送、购买或部署完成后，本地取消或撤销不一定能恢复外部状态
开发测试、调试与请求录制	显式运行相关开发工具时，可向配置的真实模型或工具服务发送测试提示、样例资料及认证头；配置为真实上游的录制代理可转发请求，不能因名称含测试／录制就认为完全离线
构建、签名与维护者发布	可下载依赖、原生二进制和运行时、推送 Git、交给签名工具或 Apple 公证服务；CLI SEA 共享目录发布与上传会先校验第三方声明材料，校验失败会阻断发布流程

NOTICE.md 最后补充一条重要原则：上述业务用途仅针对本项目提供的接口。用户自行编写的脚本、配置的任意地址或另行安装的第三方组件，可能具有额外的数据发送行为；不能仅因通过 ZCode 启动，就推定其用途或接收方已经获得官方审核。

四、本地数据、日志与凭据

4.1 数据目录按运行形态分散

数据可能分别保存在桌面设备、浏览器、CLI 所在主机、SSH／WSL 环境及外部服务中。桌面和服务端的数据目录可受运行环境和启动配置影响（例如 README 提到可用 ZCODE_DATA_BASE_DIR 指定独立开发数据目录），包含设置、会话、附件、缓存、任务记录、插件和日志。独立 CLI 默认会话数据库位于 ~/.zcode/cli/db/db.sqlite。

关键认知：关闭窗口、退出登录、卸载客户端或删除一个工作区，不应被理解为已经清除其他环境、独立数据目录、备份和外部服务中的全部副本。

4.2 记忆功能默认值因形态而异

• 独立 CLI 的默认配置启用记忆（可从 bootstrap 运行时配置 看到 memoryEnabled: runtimeConfig.memory?.enabled !== false 的默认启用逻辑）；
• 桌面应用设置默认关闭。

启用后可分析已保存会话、持久化记忆，并在后续任务中复用，相关提取或整理可产生额外模型请求。自动化计划、运行记录和未完成任务也有各自的持久化位置，恢复这些记录不保证此前的外部操作被撤销或能够完整重放。

4.3 日志默认写入本地，但脱敏有限

共享 Agent 的模型输入输出日志在开发和生产运行中默认写入本地（测试环境除外）。日志可能含提示词、代码、上下文、工具参数和模型回复；请求头及部分图像、视频数据有脱敏处理，但不能认为所有用户文本均已脱敏。生产默认有轮转和裁剪，显式开启完整保留会改变该行为。桌面主进程、Host、调度器、Web 服务及远端守护进程还有各自的日志和崩溃记录。

4.4 凭据存储机制各不相同

NOTICE.md 指出三种不同的凭据存储机制，不可混为一谈：

• CLI 共享凭据文件使用加密机制，默认密钥可从本机环境信息派生，读取逻辑也接受明文记录；
• 桌面／Node 服务的凭据采用本地加密文件及可配置或环境派生的密钥，并非系统钥匙串；
• Web OAuth 凭据可保存在 localStorage。

模型配置、环境变量、插件／MCP 设置、SSH 配置及远端同步的数据也可能含有效凭据，不应把这些存储统一视为系统钥匙串、硬件隔离或“始终不离开本机”的保证。

4.5 浏览器数据与清理边界

内嵌浏览器使用持久化浏览数据；显式导入其他浏览器的 Cookies 和 LocalStorage 可使其获得相应登录状态。清理缓存与清理全部站点数据是不同操作，浏览器记录、下载文件、网页录制产物和模型日志也不一定由同一清理入口删除。

实操建议（NOTICE.md 原文要点）：

• 不要把真实密钥或 token 写入版本控制跟踪的文件；
• 复制日志、上传反馈、分享对话或备份数据目录前，应检查接收范围，避免将真实凭据、原始会话和私人项目内容提交到公开仓库或问题报告。

五、第三方许可与版权声明

本仓库第一方代码依照根 LICENSE 采用 Apache-2.0。该许可不替其他权利人新增授权，也不覆盖第三方软件、复制代码、原生二进制、字体、图标、网页素材及其他资源的独立条款。

具体依赖包清单见 THIRD-PARTY-NOTICES.md，该文件由 node scripts/licenses.mjs notices 从当前 workspace 生产依赖图、复制的源码/素材及原生搜索工具生成，是跨发行形态的保守并集——并非每个列出的组件都出现在每个平台上；版本、源码引用与哈希记录在 third-party/inventory.json 和 third-party/native-search/sources.json。文件同时声明：包元数据中的许可证标识仅是描述性的，不取代原始条款；版权持有人从不根据 npm 作者字段推断。

受第三方版权、许可及再分发条件等约束，本仓库不承诺提供官方产品的全部功能及活动政策，具体以实际发布的源码和构建产物为准。

六、实践清单：把声明变成部署与使用决策

综合 NOTICE.md 全文及上述源码证据，可将安全实践归纳为一份可直接落地的清单：

1. 按运行形态确认默认值：交互会话、--prompt 非交互 CLI、桌面会话的模式默认值不同（build 默认 vs yolo 回退），先确认自己处在哪种入口；
2. 处理不可信项目前收紧环境：限制运行账号、凭据和网络权限；不要依赖“工作区身份”“worktree 隔离”作为系统级沙箱；
3. 理解 yolo 的边界：yolo 会放行普通工具操作，交互类工具和声明 alwaysAsk 的工具仍有自己的规则；需要只读规划时同时启用规划约束；
4. 审查外部输入：网页、仓库内容、共享链接、插件与 MCP 配置都可能诱导额外操作，先审查敏感操作再执行；
5. 远端部署必须显式配置认证：独立远端核心默认仅监听 127.0.0.1，非回环监听会拒绝启动；按入口配置认证、传输保护和访问控制，应用账号登录不能替代部署层边界；
6. 区分清理语义：关闭窗口/退出登录/卸载 ≠ 清除全部副本；清理缓存 ≠ 清理全部站点数据；备份才是唯一可靠的恢复手段；
7. 凭据分类存放：真实密钥与 token 不进版本控制，了解 CLI/桌面/Web 三种凭据存储机制的区别，不要假设系统钥匙串保护；
8. 第三方合规：第一方代码为 Apache-2.0，第三方依赖的独立条款见 THIRD-PARTY-NOTICES.md，使用与再分发前核对对应组件的原始许可文本。

总结

NOTICE.md 是 ZCode 官方对“能做什么、默认怎么做、边界在哪、数据去哪、第三方权利如何划分”的完整技术声明。它与仓库源码（权限判定 service.ts、CLI 模式默认值 run.ts、远端监听保护 http.ts、Computer Use 占位实现 index.js）一一对应，构成可验证的安全事实基础。对于任何将 AI 编程工作台用于真实项目、CI 流水线或远端环境的团队，这份声明都应作为配置权限、设计部署拓扑与制定备份策略的起点——模型说“完成”不等于完成，页面显示“本地”不等于本地，每一次自动化都要回到执行账号、网络边界与恢复能力三个基本面上重新核对。