内容
# MCP ACS 文件系统管理器
适用于 AI 代理的高级文件系统操作，集成 MCP 并具有严格的安全边界。数字防御 AI 能力套件的一部分。
## 功能
### 🚀 高级文件操作
- **批量操作**：原子执行多个文件操作（复制、移动、删除）
- **目录监视**：实时监控目录的文件系统更改
- **文件搜索**：按文件名、内容或元数据搜索，索引快速
- **校验和计算**：使用 MD5、SHA-1、SHA-256、SHA-512 验证文件完整性
- **磁盘使用分析**：分析目录大小并识别大文件
### 🔒 安全第一
- **工作区隔离**：所有操作都限制在工作区根目录内
- **10 层路径验证**：多个安全检查防止路径遍历
- **硬编码阻止列表**：系统路径和敏感文件始终被阻止
- **速率限制**：通过可配置的操作限制防止滥用
- **审计日志**：完整的审计日志记录用于取证
- **平台特定安全**：自动检测和强制执行 OS 特定安全边界
### 🤖 AI 集成
- **Copilot 聊天参与者**：在 Copilot 聊天中使用 `@filesystem`
- **语言模型工具**：AI 代理直接访问文件系统操作
- **MCP 协议**：标准模型上下文协议集成
- **安全边界**：AI 代理在严格、可配置的限制内运行
- **语言服务器协议**：文件系统操作的智能代码补全、悬停信息和诊断
### 🛠️ 开发人员体验
- **类型安全设置**：使用 TypeScript 类型的集中式配置管理
- **智能错误处理**：分类错误，带有用户友好的消息和恢复建议
- **LSP 集成**：悬停路径以查看元数据，获取补全建议，并查看诊断信息
- **跨平台支持**：自动平台检测和路径归一化，适用于 Windows、macOS 和 Linux
## 安装
1. 从 VS Code 市场安装
2. 或通过命令行安装：
```bash
code --install-extension DigitalDefiance.mcp-acs-filesystem
```
## 快速入门
### 与 Copilot 结合使用
询问 Copilot 执行文件操作：
```
@filesystem 批量复制 src 目录下所有 .ts 文件到 backup 目录
@filesystem 搜索 src 目录下包含 "TODO" 的文件
@filesystem 计算 package.json 的 sha256 校验和
@filesystem 分析 node_modules 目录的磁盘使用情况
@filesystem 监视 src 目录的更改
```
### 使用命令
- **Ctrl+Shift+F Ctrl+Shift+S**：搜索文件
- **Ctrl+Shift+F Ctrl+Shift+B**：批量操作
- 或使用命令面板：`MCP 文件系统：...`
## 配置
### 安全设置
```json
{
"mcp-filesystem.security.workspaceRoot": "${workspaceFolder}",
"mcp-filesystem.security.allowedSubdirectories": [],
"mcp-filesystem.security.blockedPaths": [
".git",
".env",
"node_modules",
".ssh"
],
"mcp-filesystem.security.blockedPatterns": [
"*.key",
"*.pem",
"*.env",
"*secret*",
"*password*"
]
}
```
### 服务器设置
```json
{
"mcp-filesystem.server.autoStart": true,
"mcp-filesystem.server.timeout": 30000,
"mcp-filesystem.server.logLevel": "info"
}
```
### 资源限制
```json
{
"mcp-filesystem.resources.maxFileSize": 104857600,
"mcp-filesystem.resources.maxBatchSize": 1073741824,
"mcp-filesystem.resources.maxOperationsPerMinute": 100
}
```
### UI 设置
```json
{
"mcp-filesystem.ui.refreshInterval": 5000,
"mcp-filesystem.ui.showNotifications": true,
"mcp-filesystem.ui.showSecurityWarnings": true,
"mcp-filesystem.ui.confirmDangerousOperations": true
}
```
### 操作设置
```json
{
"mcp-filesystem.operations.enableBatch": true,
"mcp-filesystem.operations.enableWatch": true,
"mcp-filesystem.operations.enableSearch": true,
"mcp-filesystem.operations.enableChecksum": true
}
```
## 可用操作
### 批量操作
原子执行多个文件操作，失败时自动回滚：
- 复制多个文件/目录
- 移动多个文件/目录
- 删除多个文件/目录
### 目录监视
监控目录的更改，支持事件过滤：
- 递归监视
- 事件类型过滤（创建、修改、删除、重命名）
- 基于模式的过滤
### 文件搜索
快速文件搜索，支持多种模式：
- 文件名模式匹配
- 内容搜索（全文）
- 元数据过滤（大小、日期、类型）
- 大型代码库的索引搜索
### 校验和操作
验证文件完整性：
- MD5、SHA-1、SHA-256、SHA-512 算法
- 批量校验和计算
- 校验和验证
### 磁盘使用分析
分析存储使用情况：
- 递归目录大小计算
- 最大文件/目录识别
- 文件类型分析
- 可用磁盘空间查询
## 安全边界
### AI 代理不能执行的操作
- ❌ 访问工作区根目录外的文件
- ❌ 访问系统目录（/etc、/sys、C:\Windows 等）
- ❌ 访问 SSH 密钥、AWS 凭证或其他敏感文件
- ❌ 创建指向工作区外的符号链接
- ❌ 绕过速率限制
- ❌ 禁用审计日志
- ❌ 修改工作区根目录
### AI 代理可以执行的操作（在工作区内）
- ✅ 读取、写入和删除文件
- ✅ 创建和导航目录
- ✅ 按名称或内容搜索文件
- ✅ 监视目录的更改
- ✅ 计算校验和
- ✅ 创建符号链接（在工作区内）
- ✅ 批量操作
- ✅ 同步目录
## MCP 服务器配置
扩展程序自动为 Copilot 集成配置 MCP 服务器。要手动添加到您的 workspace：
1. 运行命令：`MCP 文件系统：添加到 Copilot MCP 服务器`
2. 或手动添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"mcp-filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@ai-capabilities-suite/mcp-filesystem"]
}
}
}
```
## 示例
### 批量复制文件
```typescript
// 询问 Copilot：
@filesystem 批量复制 src 目录下所有 TypeScript 文件到 backup 目录
// 或直接使用 MCP 工具：
{
"operations": [
{ "type": "copy", "source": "src/file1.ts", "destination": "backup/file1.ts" },
{ "type": "copy", "source": "src/file2.ts", "destination": "backup/file2.ts" }
],
"atomic": true
}
```
### 监视目录
```typescript
// 询问 Copilot：
@filesystem 递归监视 src 目录下的 TypeScript 文件
// 或使用 MCP 工具：
{
"path": "src",
"recursive": true,
"filters": ["*.ts", "*.tsx"]
}
```
### 搜索文件
```typescript
// 询问 Copilot：
@filesystem 在 src 目录下搜索包含 "TODO" 的文件
// 或使用 MCP 工具：
{
"query": "TODO",
"searchType": "content",
"fileTypes": [".ts", ".tsx", ".js"]
}
```
## 语言服务器功能
扩展程序包括一个语言服务器协议（LSP）实现，提供智能代码协助：
### 悬停信息
悬停文件系统路径以查看：
- 文件元数据（大小、权限、修改时间）
- 安全边界信息
- 可用的 MCP 文件系统工具
### 代码补全
获取智能补全建议：
- MCP 文件系统工具名称
- 常见文件系统路径
- 操作参数
### 诊断信息
实时警告和错误：
- 路径超出工作区根目录
- 被阻止的路径和模式
- 危险的文件系统操作
- 需要验证的符号链接操作
### 代码操作
快速修复常见问题：
- 转换为工作区相对路径
- 删除被阻止的路径引用
- 将同步操作转换为异步操作
- 打开安全设置
## 故障排除
### 服务器未启动
1. 检查输出面板：`视图 > 输出 > MCP ACS 文件系统管理器`
2. 验证 Node.js 是否已安装：`node --version`
3. 检查设置中的服务器路径
4. 尝试重启 VS Code
5. 查看服务器日志以获取详细的错误信息
### 权限错误
1. 验证工作区根目录是否可访问
2. 检查被阻止的路径配置
3. 查看审计日志以获取安全违规信息
4. 确保文件在工作区边界内
5. 检查平台特定的安全边界
### 性能问题
1. 降低 `maxOperationsPerMinute` 以限制速率
2. 对大型代码库使用索引搜索
3. 限制目录监视深度
4. 检查磁盘空间和文件大小
5. 调整 `ui.refreshInterval` 以减少 UI 更新
### 配置错误
1. 打开设置：`Ctrl+,`（或 `Cmd+,` 在 macOS 上）
2. 搜索“mcp-filesystem”
3. 验证所有设置都有有效值
4. 检查输出面板中的验证错误
5. 如有必要，重置为默认值
### LSP 不工作
1. 检查语言服务器是否在输出面板中运行
2. 验证激活事件是否触发（打开 TypeScript/JavaScript 文件）
3. 尝试重新加载窗口：`开发人员：重新加载窗口`
4. 检查冲突的扩展程序
5. 查看输出面板中的 LSP 日志
### 错误消息
扩展程序提供分类错误消息：
- **用户错误**：无效输入或文件未找到 - 检查路径和权限
- **系统错误**：磁盘空间或内存问题 - 检查系统资源
- **网络错误**：MCP 服务器连接问题 - 重启服务器
- **安全错误**：被阻止的路径或边界违规 - 查看安全设置
- **配置错误**：无效设置 - 检查配置值
每个错误都包含恢复建议，帮助您快速解决问题。
## 支持
- **问题**：[GitHub 问题](https://github.com/digital-defiance/ai-capabilities-suite/issues)
- **文档**：[GitHub 仓库](https://github.com/digital-defiance/ai-capabilities-suite)
- **电子邮件**：<info@digitaldefiance.org>
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## AI 能力套件的一部分
此扩展程序是数字防御 AI 能力套件的一部分，其中包括：
- **MCP ACS 进程管理器**：具有安全边界的进程管理
- **MCP ACS 截图**：跨平台截图捕获
- **MCP ACS 调试器**：高级调试功能
- **MCP ACS 文件系统管理器**：高级文件操作（此扩展程序）
访问 [Digital Defiance](https://digitaldefiance.org) 以获取更多信息。
