ZCode 工具系统与安全

工具运行时位于 apps/zcode-cli/packages/core/src/tool，拥有 registry / scheduler / executor / permission；agent-core 只消费工具生命周期结果继续 turn。

内置工具

core/src/tool/handlers/index.ts:78 的 builtInTools 与条件注册逻辑。当前工具池分组：

文件 / 搜索 / 执行

Read（文本、图片、视频、PDF）、Write、Edit、Bash、Glob、Grep、WebFetch、WebSearch。

ApplyPatch 有实现但当前从注册表注释掉。

会话 / 交互

TodoRead、TodoWrite、AskUserQuestion、EnterPlanMode、ExitPlanMode、Skill、ReadSessionContext、ReplyToChannel。

自动化

CronCreate/List/Update/Delete、OffPeakCreate/List。

子代理 / 协作

Agent、兼容别名 Task、SendMessage、RespondToCoordinator、TaskOutput、TaskStop、submit_result、escalate。

工作流

CreateWorkflow、AmendWorkflow、SaveWorkflow、ListSavedWorkflows、ListModels、EvalWorkflowSnippet、ListWorkflowRuns、GetWorkflowRun、ResumeWorkflowRun、ResolveWorkflowQuestion、FillWorkflowHole。

旧 Workflow 实现存在但当前未注册。详见 dynamic-workflow。

条件注册

js / mcp__node_repl__js：由 Browser Use 或 Computer Use 启用。
embedded-search 分支：隐藏 Glob/Grep，让 Bash 接管搜索。
dynamic workflow 关闭时：下架 11 个 workflow 工具。
Cron / OffPeak / Agent / Skill / 协作工具：按宿主能力或配置门控。

工具契约

core/src/tool/types.ts:69 定义 inputSchema / outputSchema 与元数据：

readOnly, destructive, concurrentSafe, sideEffectScope,
risk, timeout, output budget, approval, turn-control

调度器 core/src/tool/scheduler.ts:60 按这些元数据做拓扑排序并分组并发。Streaming 工具的执行门槛见 agent-core。

执行流水线

core/src/tool/executor/call-runner.ts:67 的执行顺序：

registry lookup
 → 初始 / 工具语义 / 输入解析校验
 → PreToolUse（hook）
 → 权限 / 审批
 → ToolCallStarted
 → handler + timeout / cancel
 → output schema
 → artifact / 截断
 → PostToolUse（hook）
 → events / telemetry
失败 → PostToolUseFailure

权限流程

core/src/tool/executor/permission-flow.ts:44：

project rules
mode
tool capability
Memory 文件保护
hook decision
user-once guard
具体风险审批
交互 broker
输入改写重判
授权持久化

权限模式与风险（NOTICE）

NOTICE.md 明确：

共享运行配置默认采用 build 权限模式；独立 CLI 通过 --prompt 执行非交互任务时，未指定 --mode 会采用 yolo。
是否逐次确认受工具声明、权限规则及运行模式影响；未同时启用只读规划约束的 yolo 会放行普通工具操作，交互类工具和明确要求确认的工具仍有各自规则。
模型工具审批不是整个应用统一的权限开关，不能据此推定终端操作、插件进程或更新下载都会经过同一审批流程。
当前共享 Agent 执行适配器不提供默认的 OS 沙箱：工作目录、workspace 身份、Git worktree、浏览器页面隔离和 Node REPL 运行上下文，都不能当作所有工具的系统级隔离保证。

Hook 运行时

工具生命周期挂点（PreToolUse / PermissionRequest / PostToolUse / PostToolUseFailure）由 Hook 运行时驱动，可 deny / ask / allow / replace tool input / add context。Hook 契约见 cli-tui 与 plugin-system。

Wiki AI

目录