文件系统工具

taskflow_filesystem 提供完整的文件操作能力

---

📋 可用工具

工具名	功能	安全性
taskflow_filesystem_listDirectory	列出目录内容	✅ Low
taskflow_filesystem_readFile	读取文件内容	✅ High
taskflow_filesystem_writeFile	写入文件内容	✅ High
taskflow_filesystem_appendFile	追加内容到文件	✅ High
taskflow_filesystem_deleteFile	删除文件	✅ High
taskflow_filesystem_createDirectory	创建目录	✅ High
taskflow_filesystem_deleteDirectory	删除目录	✅ High
taskflow_filesystem_copyFile	复制文件	✅ High
taskflow_filesystem_moveFile	移动/重命名文件	✅ High
taskflow_filesystem_search	搜索文件	✅ Low
taskflow_filesystem_getInfo	获取文件信息	✅ Low

---

🔧 工具详解

listDirectory

列出目录内容。

参数：

{
  "path": "string",        // 目录路径（必填）
  "recursive": false,      // 是否递归（可选）
  "pattern": "*.ts"        // 匹配模式（可选）
}

示例：

Claude: 列出 src 目录的文件

调用：

{
  "name": "taskflow_filesystem_listDirectory",
  "arguments": {
    "path": "src",
    "recursive": true
  }
}

返回：

{
  "success": true,
  "items": [
    {"name": "index.ts", "type": "file", "size": 1024},
    {"name": "utils", "type": "directory"},
    {"name": "components", "type": "directory"}
  ]
}

---

readFile

读取文件内容。

参数：

{
  "path": "string",        // 文件路径（必填）
  "encoding": "utf-8"      // 编码（可选）
}

示例：

Claude: 读取 README.md 文件

调用：

{
  "name": "taskflow_filesystem_readFile",
  "arguments": {
    "path": "README.md"
  }
}

返回：

{
  "success": true,
  "content": "# TaskFlow AI\n...",
  "encoding": "utf-8",
  "size": 2048
}

---

writeFile

写入文件内容。

参数：

{
  "path": "string",        // 文件路径（必填）
  "content": "string",     // 文件内容（必填）
  "encoding": "utf-8"      // 编码（可选）
}

示例：

Claude: 创建一个新文件 src/utils.ts，内容是...

调用：

{
  "name": "taskflow_filesystem_writeFile",
  "arguments": {
    "path": "src/utils.ts",
    "content": "export function hello() { ... }"
  }
}

返回：

{
  "success": true,
  "path": "src/utils.ts",
  "size": 512
}

---

search

搜索文件。

参数：

{
  "path": "string",        // 搜索路径（必填）
  "pattern": "*.ts",       // 匹配模式（必填）
  "maxResults": 100        // 最大结果数（可选）
}

示例：

Claude: 搜索所有 .test.ts 文件

调用：

{
  "name": "taskflow_filesystem_search",
  "arguments": {
    "path": ".",
    "pattern": "*.test.ts"
  }
}

返回：

{
  "success": true,
  "results": [
    "src/utils.test.ts",
    "src/components/Button.test.ts"
  ],
  "count": 2
}

---

🔒 安全机制

路径验证

所有路径都经过严格验证：

// 防止路径遍历
validateFilePath('/etc/passwd')  // ❌ 拒绝

// 限制在工作目录内
validateFilePath('../secret.txt')  // ❌ 拒绝

// 允许相对路径
validateFilePath('src/index.ts')  // ✅ 允许

文件大小限制

操作	限制
读取	10 MB
写入	5 MB
追加	2 MB

敏感文件保护

以下文件默认禁止访问：

blockedFiles:
  - .env
  - .env.local
  - *.key
  - *.pem
  - id_rsa
  - .ssh/*

---

💡 使用技巧

技巧一：批量读取

Claude: 读取所有 .md 文件的内容

Claude 会依次调用 readFile 读取每个文件。

技巧二：文件对比

Claude: 比较 src/index.ts 和 dist/index.js 的区别

Claude 会读取两个文件并对比内容。

技巧三：代码搜索

Claude: 搜索包含 'TODO' 注释的文件

Claude 会使用 search 找到文件，然后 readFile 读取内容。

---

🐛 常见问题

Q: 读取大文件失败

A: 文件超过 10 MB 限制。建议：

1. 分块读取
2. 使用 head/tail 命令查看部分内容
3. 联系管理员提高限制

Q: 权限错误

A: 文件权限不足。检查：

ls -la your-file.txt
chmod 644 your-file.txt  # 添加读权限

Q: 路径不存在

A: 检查路径是否正确：

# 使用绝对路径
taskflow_filesystem_readFile {"path": "/absolute/path/to/file"}

# 或使用相对路径（相对于工作目录）
taskflow_filesystem_readFile {"path": "./relative/path/to/file"}

---

🔗 相关链接

• MCP 工具总览
• Shell 工具
• 安全机制说明

---

文件操作有问题随时问我