企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• RAG
• AI 写作
• 后端
• 桌面应用

本篇指南讲解 Toonflow 内置的「工作区文件」工具（@toonflow/tool-workspace）——它赋予 AI Agent 阅读、列出和编辑当前工作区内文件的能力，是 Agent 完成"阅读分镜脚本并总结""把设定保存为角色设定文档"等任务的基础设施。读完本文，你将掌握该工具的触发方式、功能边界、只读模式的配置方法，并理解它如何在 packages/toolScaffold 框架与统一文件层之上实现路径约束与并发安全。

工具定位与适用场景

「工作区文件」是 Toonflow 的 Agent 工具（Tool Plugin）之一，面向"文件读写"这一高频操作场景。它让 Agent 能够：

• 读取并理解项目中的既有素材，例如分镜脚本、角色设定、大纲文本；
• 将对话中产生的结构化内容落盘为文件，例如把一段设定保存为角色设定.md；
• 在既有文件上进行精准的局部编辑，而不是整文件重写。

在 Toonflow 的创作流程中，它通常与画布节点、技能（Skill）配合使用：Agent 先读取工作区里的剧本草稿，再据此驱动后续的图片生成、视频生成等节点。工具本身不生成媒体，只负责"文档侧"的读写，因此与 packages/tools 下的askUser、canvas、skillOperator等插件互补。

使用方式：先打开项目，再下达任务

该工具的使用入口非常简单，无需显式调用命令。先选择或打开一个项目（即确立当前工作区），然后直接以自然语言给出文件名称与任务即可，例如：

• "阅读分镜.md 并总结"
• "把这段设定保存为角色设定.md"
• "在 剧本.md 中把第二幕的开头改写得更紧张一些"

两点关键约定：

1. 文件位置相对于当前工作区：Agent 解析路径时以context.cwd（宿主注入的当前工作区路径）为根，用户无需提供绝对路径。
2. 修改前先读取：工具在设计上遵循"先读后写"原则——修改已有内容之前，Agent 会先读取相关文件，确认上下文后再执行编辑，避免盲改破坏原稿。

支持的功能清单

配置：插件市场中的「工作区文件」

工具配置入口为：设置 → 插件市场 → 已安装 → 找到「工作区文件」→ 点击「配置」。

当前唯一配置项为「只读模式」（readOnly），默认关闭。在 packages/tools/workspace/src/index.ts 中，配置结构由 Zod 严格校验：

const configSchema = z.object({ readOnly: z.boolean().default(false) }).strict();

要点：

• 默认关闭：Agent 可以自由读写工作区文件；
• 开启后：工具只提供文件读取（read）与目录列表（ls），不再注册写入（write）与编辑（edit）工具；
• 作用范围：只读模式仅限制本工具，不会关闭画布操作等其他工具的修改能力；
• 生效时机：配置保存后写入data/settings.json的toolConfigs（参见 apps/server/src/utils/conf/index.ts 中toolConfigs的存储结构），下一次发送消息时生效。

从源码可以看到，只读模式是通过"不注册写工具"实现的。在 src/index.ts 中，只有当!readOnly时才把写入与编辑工具插入工具列表；同时，只读模式下还会向 Agent 追加动态提示词规则：

...(readOnly ? ["当前文件工具只支持读取，不能用它们写入或编辑文件；其他工具的能力以各自说明为准。"] : [])

这样 Agent 在只读模式下会主动约束自己，而不是尝试后失败。该机制在 MCP 侧也有对应拦截：apps/server/src/utils/mcp/tools.ts中，当工作区工具处于只读模式时，除list、readBinary之外的写操作会直接抛出"当前工作区文件工具为只读模式"的错误。

源码级原理：工具如何注册与运行

「工作区文件」遵循 Toonflow 统一的工具插件框架（详见 packages/toolScaffold/readme.md）：工具包以.tool.js单文件发布，安装、升级、卸载均处理该文件；src/index.ts默认导出ToolPlugin，实现validateConfig与createTools两个接口。

createTools接收宿主注入的context，其中包含当前工作区cwd、已校验的工具配置config与统一文件能力files。工具通过宿主提供的 SDK 构造函数生成标准工具定义：

• 读取工具sdk.createReadToolDefinition(cwd, ...)：包装readFile、access、detectImageMimeType，用于读取文件与判断图片类型；
• 目录工具sdk.createLsToolDefinition(cwd, ...)：包装exists、stat、readdir，用于列出与探查目录；
• 写入工具sdk.createWriteToolDefinition(cwd, ...)：包装writeFile、mkdir，用于新建文件；
• 编辑工具sdk.createEditToolDefinition(cwd, ...)：包装readFile、access、writeFile，用于局部编辑。

注意读取类操作在调用files时都传入了readOnly = true（如files.readFile(path, true)）。这正是"全局技能目录只读可读"的实现入口：按 apps/server/src/agent/tools/index.ts 的resolvePath逻辑，当readOnly为真且目标路径落在全局技能目录（skillsDirectory）内时，允许以技能目录为根进行读取；而写入始终限定在当前工作区cwd内。

安全边界：能做什么，不能做什么

工具的安全设计是"边界清晰、权限收敛"：

• 修改限定在工作区内：无论读写，路径解析都以当前工作区为根，无法越出项目目录操作任意系统文件；
• 没有删除、重命名能力：工具包未注册remove、rename类操作，Agent 无法通过本工具删除或改名文件；
• 不执行终端命令：工具不提供 shell/命令执行能力，杜绝通过文件工具触发任意命令执行；
• 全局技能目录只读：技能资料可读不可写，保护技能资产不被对话内容意外篡改；
• 只读模式只约束自身：如前述，readOnly开关不影响画布等其他工具。

需要说明的是，工具插件本质上是可信的服务端代码，拥有服务器进程权限，并不是沙箱（见 packages/toolScaffold/readme.md 中的安全提示）。上述边界针对的是"本工具的行为约束"，因此实践中应仅安装可信来源的工具文件。

底层支撑：统一文件层的读写安全

工作区工具的所有文件操作都经由宿主的统一文件层context.files（packages/file/src/index.ts），而不是直接调用系统 API。该文件层在并发安全上有两个值得注意的设计：

1. 读写互斥与等待超时：同一文件的读与写通过信号量互斥，写入操作独占全部许可（同文件最多 64 个并发读），FIFO 队列防止后到的读写插队；等待超过 30 秒会以EBUSY中止（见 packages/file/src/access.ts）。
2. 原子写入：writeAtomic先写临时文件再重命名落盘，避免写入中途崩溃导致目标文件处于半写状态；exclusive模式通过硬链接保证"不覆盖已有文件"的语义（见 packages/file/src/index.ts）。

这意味着 Agent 高频率读写工作区文件时，不会互相踩踏，也不会产生残缺文件——这一层安全由框架统一提供，工作区工具无需自行实现。

小结

「工作区文件」工具是 Toonflow 中"文档进出 Agent 工作流"的关键通道：它以自然语言即可驱动，覆盖列目录、读文件、写文件、编辑与技能阅读，并通过「只读模式」提供了从"可写"到"只读"的一键收敛。结合 packages/toolScaffold 插件框架与 packages/file 统一文件层的源码实现，可以确认其路径约束、写权限控制与并发安全均由框架级机制保障。对希望自定义工具行为的开发者而言，packages/tools/workspace/src/index.ts 是一个结构清晰、可直接参考的最小插件实现样例。

• 人工智能
• AI 应用
• AI Agent
• RAG
• AI 写作
• 后端
• 桌面应用