一、host_workspace_write 工具
1.1 工具概述
功能 ：写入 host 工作区文件
核心特性：
- 直接访问 host 文件系统
- 支持 workspaceOnly 限制
- 自动创建父目录
- 参数标准化包装
- 边界检查
1.2 创建函数
位置：第 115018 行
javascript
function createHostWorkspaceWriteTool(root, options) {
return wrapToolParamNormalization(createWriteTool(root, {
operations: createHostWriteOperations(root, options)
}), CLAUDE_PARAM_GROUPS.write);
}1.3 Host 写入操作
位置：第 115057 行
javascript
async function writeHostFile(absolutePath, content) {
const resolved = path.resolve(absolutePath);
await fs$1.mkdir(path.dirname(resolved), { recursive: true });
await fs$1.writeFile(resolved, content, "utf-8");
}
function createHostWriteOperations(root, options) {
// 1. 无限制模式
if (!(options?.workspaceOnly ?? false)) {
return {
mkdir: async (dir) => {
const resolved = path.resolve(dir);
await fs$1.mkdir(resolved, { recursive: true });
},
writeFile: writeHostFile
};
}
// 2. workspaceOnly 模式（限制只能访问工作区）
return {
mkdir: async (dir) => {
const relative = toRelativeWorkspacePath(root, dir, { allowRoot: true });
const resolved = relative ? path.resolve(root, relative) : path.resolve(root);
await assertSandboxPath({
filePath: resolved,
cwd: root,
root
});
await fs$1.mkdir(resolved, { recursive: true });
},
writeFile: async (absolutePath, content) => {
await writeFileWithinRoot({
rootDir: root,
relativePath: toRelativeWorkspacePath(root, absolutePath),
data: content,
mkdir: true
});
}
};
}1.4 包装链
createWriteTool (外部库)
↓ (使用 Host 操作)
wrapToolParamNormalization (参数标准化)
↓ (CLAUDE_PARAM_GROUPS.write)
最终工具1.5 workspaceOnly 模式
javascript
// workspaceOnly = false（无限制）
├─ 可以写入任意路径
└─ 直接调用 fs.mkdir/fs.writeFile
// workspaceOnly = true（限制模式）
├─ 只能写入工作区内
├─ assertSandboxPath 检查边界
└─ writeFileWithinRoot 安全写入1.6 执行流程图
host_workspace_write 工具调用
↓
1. 参数标准化
├─ path/file_path/filePath/file → path
└─ content → content
↓
2. 验证必填参数
↓
3. 检查 workspaceOnly 限制
├─ 是 → 验证路径在工作区内
└─ 否 → 允许任意路径
↓
4. 创建父目录（mkdir -p）
↓
5. 写入文件（覆盖模式）
↓
6. 返回结果二、host_workspace_edit 工具
2.1 工具概述
功能 ：编辑 host 工作区文件
核心特性：
- 直接访问 host 文件系统
- 支持 workspaceOnly 限制
- 支持编辑失败恢复
- 参数标准化包装
- 边界检查
2.2 创建函数
位置：第 115021 行
javascript
function createHostWorkspaceEditTool(root, options) {
return wrapToolParamNormalization(
wrapEditToolWithRecovery(createEditTool(root, {
operations: createHostEditOperations(root, options)
}), {
root,
readFile: (absolutePath) => fs$1.readFile(absolutePath, "utf-8")
}),
CLAUDE_PARAM_GROUPS.edit
);
}2.3 Host 编辑操作
位置：第 115099 行
javascript
function createHostEditOperations(root, options) {
// 1. 无限制模式
if (!(options?.workspaceOnly ?? false)) {
return {
readFile: async (absolutePath) => {
const resolved = path.resolve(absolutePath);
return await fs$1.readFile(resolved);
},
writeFile: writeHostFile,
access: async (absolutePath) => {
const resolved = path.resolve(absolutePath);
await fs$1.access(resolved);
}
};
}
// 2. workspaceOnly 模式（限制只能访问工作区）
return {
readFile: async (absolutePath) => {
return (await readFileWithinRoot({
rootDir: root,
relativePath: toRelativeWorkspacePath(root, absolutePath)
})).buffer;
},
writeFile: async (absolutePath, content) => {
await writeFileWithinRoot({
rootDir: root,
relativePath: toRelativeWorkspacePath(root, absolutePath),
data: content,
mkdir: true
});
},
access: async (absolutePath) => {
let relative;
try {
relative = toRelativeWorkspacePath(root, absolutePath);
} catch {
return;
}
try {
await (await openFileWithinRoot({
rootDir: root,
relativePath: relative
})).fd;
} catch {
// 忽略错误
}
}
};
}2.4 编辑恢复包装
位置：第 114462 行（与 sandboxed_edit 共享）
javascript
function wrapEditToolWithRecovery(base, options) {
return {
...base,
execute: async (toolCallId, params, signal, onUpdate) => {
// 1. 读取参数
const { pathParam, oldText, newText } = readEditToolParams(params);
// 2. 解析绝对路径
const absolutePath = typeof pathParam === "string" ?
resolveEditPath(options.root, pathParam) : void 0;
// 3. 读取原始内容
let originalContent;
if (absolutePath && newText !== void 0) {
try {
originalContent = await options.readFile(absolutePath);
} catch {}
}
// 4. 执行编辑
try {
return await base.execute(toolCallId, params, signal, onUpdate);
} catch (err) {
// 5. 编辑失败处理
if (!absolutePath) throw err;
let currentContent;
try {
currentContent = await options.readFile(absolutePath);
} catch {}
// 6. 判断编辑是否已应用
if (typeof currentContent === "string" && newText !== void 0) {
if (didEditLikelyApply({
originalContent,
currentContent,
oldText,
newText
})) {
return buildEditSuccessResult(pathParam ?? absolutePath);
}
}
// 7. 添加不匹配提示
if (typeof currentContent === "string" &&
err instanceof Error &&
shouldAddMismatchHint(err)) {
throw appendMismatchHint(err, currentContent);
}
throw err;
}
}
};
}2.5 参数标准化
javascript
const CLAUDE_PARAM_GROUPS = {
edit: [
{
keys: ["path", "file_path", "filePath", "file"],
label: "path alias"
},
{
keys: ["oldText", "old_string", "old_text", "oldString"],
label: "oldText alias"
},
{
keys: ["newText", "new_string", "new_text", "newString"],
label: "newText alias",
allowEmpty: true
}
]
};2.6 执行流程图
host_workspace_edit 工具调用
↓
1. 参数标准化
├─ path 别名处理
├─ oldText 别名处理
└─ newText 别名处理
↓
2. 验证必填参数
↓
3. 检查 workspaceOnly 限制
↓
4. 读取原始内容
↓
5. 执行编辑（精确替换）
↓
6. 编辑失败处理
├─ 读取当前内容
├─ 判断是否部分成功
└─ 添加不匹配提示
↓
7. 返回结果三、关键机制对比
3.1 功能定位
| 特性 | host_workspace_write | host_workspace_edit |
|---|---|---|
| 用途 | 创建/覆盖文件 | 精确修改文件 |
| 写操作 | 覆盖写入 | 精确替换 |
| 恢复机制 | 不支持 | 支持 |
3.2 与沙盒工具对比
| 特性 | Host 工具 | 沙盒工具 |
|---|---|---|
| 文件系统 | Host 直接访问 | Bridge 隔离访问 |
| 性能 | 更快 | 桥接开销 |
| 安全性 | 较低 | 较高 |
| 使用场景 | 非沙盒模式 | 沙盒模式 |
3.3 workspaceOnly 模式
javascript
// workspaceOnly = false
├─ 可以访问任意路径
├─ 直接调用 fs 模块
└─ 无边界检查
// workspaceOnly = true
├─ 只能访问工作区
├─ assertSandboxPath 检查
├─ writeFileWithinRoot 安全写入
└─ readFileWithinRoot 安全读取四、Host 工具系列总结
4.1 两个 Host 工具
| 工具 | 功能 | 操作 |
|---|---|---|
| host_workspace_write | 写入 Host 文件 | fs.mkdir, fs.writeFile |
| host_workspace_edit | 编辑 Host 文件 | fs.readFile, fs.writeFile, fs.access |
4.2 共同特点
- 直接访问 host 文件系统
- 支持 workspaceOnly 限制
- 自动创建父目录
- 参数标准化（CLAUDE 别名）
- 边界检查（workspaceOnly 模式）
4.3 使用场景
非沙盒模式时：
├─ 读取文件 → read (或 host_workspace_read 如果存在)
├─ 写入文件 → host_workspace_write
└─ 编辑文件 → host_workspace_edit
沙盒模式时：
├─ 读取文件 → sandboxed_read
├─ 写入文件 → sandboxed_write
└─ 编辑文件 → sandboxed_edit五、使用示例
5.1 host_workspace_write 工具调用
用户 ：在工作区创建文件
大模型返回：
json
{
"tool_call": {
"name": "host_workspace_write",
"arguments": {
"path": "src/main.js",
"content": "console.log(\"Hello\");"
}
}
}执行结果：
json
{
"content": [{
"type": "text",
"text": "Successfully wrote 27 bytes to src/main.js"
}],
"details": {
"path": "src/main.js",
"bytesWritten": 27,
"workspaceOnly": true
}
}5.2 host_workspace_edit 工具调用
用户 ：修改工作区中的文件
大模型返回：
json
{
"tool_call": {
"name": "host_workspace_edit",
"arguments": {
"path": "src/main.js",
"oldText": "console.log(\"Hello\");",
"newText": "console.log(\"Hello, World!\");"
}
}
}执行结果：
json
{
"content": [{
"type": "text",
"text": "Successfully edited src/main.js"
}],
"details": {
"path": "src/main.js",
"workspaceOnly": true
}
}