dsh-file-manager-cli

dsh-file-manager-cli

一个安全的 DeepSeek Harness (dsh) 文件和目录管理插件，所有操作都限制在 dsh 启动工作目录内，确保安全性。

🚀 功能特性

• ✅ 安全隔离: 所有文件操作都限制在 dsh 工作目录内
• ✅ 符号链接防护: 防止通过符号链接离开工作目录
• ✅ 递归创建: 支持创建多级目录结构
• ✅ glob 批量匹配: fs-find 支持 * / ? / ** 通配，可叠加多条 --exclude 排除规则
• ✅ 冲突策略可选: 目标已存在时可选 skip（默认）/ overwrite / rename，不静默覆盖
• ✅ 中文界面: 完整的中文错误提示和使用说明
• ✅ 简洁命令: 提供直观的文件管理命令

📦 安装

通过 npm 安装

npm install dsh-file-manager-cli

手动安装

• 下载插件包

npm pack

• 安装到 dsh profile

dsh plugin --profile web add ./dsh-file-manager-cli-0.2.0.tgz

🔧 使用方法

基本命令

命令	描述	示例
/fs-list <相对路径>	列出目录内容	/fs-list docs
/fs-mkdir <相对路径>	创建目录（支持递归）	/fs-mkdir projects/app
/fs-touch <相对路径>	创建空文件	/fs-touch notes.txt
/fs-find <glob> [选项]	按 glob 批量匹配文件/目录	/fs-find "src/**/*.js" --exclude=node_modules/**
/fs-rm <相对路径>	删除文件或空目录	/fs-rm temp.log

选项一览

命令	选项	说明
/fs-mkdir、/fs-touch	--on-conflict=skip|overwrite|rename	目标已存在时的处理策略，默认 skip（fs-touch 的 overwrite 会清空已有内容）
/fs-find	--exclude=<glob>	排除规则，可重复多次；作用在相对工作根的路径上
/fs-find	--type=file|dir|all	匹配类型，默认 file
/fs-find	--max=N	最多输出多少条，默认 500

选项统一使用 --key=value 形式，与路径之间以空格分隔。

使用示例

# 列出当前目录内容
/fs-list

# 创建 docs 目录
/fs-mkdir docs

# 在 docs 目录下创建 article.md 文件
/fs-touch docs/article.md

# 创建多级目录结构
/fs-mkdir projects/frontend/src

# 删除文件
/fs-rm temp.txt

# 批量查找所有 JS 文件（排除依赖目录）
/fs-find "**/*.js" --exclude=node_modules/**

# 只看目录，最多 20 条
/fs-find "src/**" --type=dir --max=20

# 已存在时不覆盖，派生新文件名
/fs-touch notes.txt --on-conflict=rename

注意事项

• 所有路径必须是相对路径，不能使用绝对路径
• 不能删除 dsh 工作根目录
• 只能删除文件和空目录，不支持递归删除
• 路径中不能包含空格
• fs-find 默认只列文件，需要目录请加 --type=dir；扫描与输出均有上限（扫描 5000 项、输出 500 条）
• fs-find 的 glob 与 --exclude 都按相对工作根的路径匹配，例如 --exclude=node_modules/**

🛠️ 开发

本地开发

• 克隆项目

git clone <repository-url>
cd dsh-file-manager-cli

• 安装依赖

npm install

• 创建调试配置文件 debug.patch.yml:

- insert:
    - id: file-manager
      name: "绝对路径/dsh-file-manager-cli/index.js"

• 启动 dsh Web 进行测试

dsh web --patch ./debug.patch.yml

开发脚本

npm run check    # 语法检查
npm run test     # 运行测试
npm run lint     # ESLint 检查
npm run format   # Prettier 格式化

打包发布

npm pack                       # 构建 tarball
npm publish                    # 发布到 npm

🏗️ 架构设计

核心组件

• 入口文件 (index.js): 插件主入口，定义命令和处理器
• Bundle 配置 (cordis.patch.yml): 声明插件集成配置
• 包配置 (package.json): 定义元数据和脚本

安全机制

• 路径验证: 确保所有操作都在工作目录内
• 符号链接检测: 防止路径遍历攻击
• 输入验证: 严格的参数检查
• 错误处理: 友好的中文错误提示

🔒 安全说明

本插件设计时就考虑了安全性：

• 所有文件操作都使用相对路径
• 自动解析和验证路径的真实位置
• 防止通过符号链接离开工作目录
• 禁止删除工作根目录
• 提供清晰的错误信息，不暴露敏感路径

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-file-manager-cli
• npm：https://www.npmjs.com/package/dsh-file-manager-cli

典型场景

1. 批量重命名

用户：把这些文件加上日期前缀

按规则批量重命名，执行前会列出改名对照，确认后再落地。

2. 目录整理

用户：把这些散落的文件按类型归到子目录

移动前先输出计划清单（源 → 目标），避免误移。

3. 安全的复制/移动

用户：把 build 产物复制到发布目录

带存在性检查与覆盖提示，不做静默覆盖。

4. 清理前的清单核对

用户：这些临时文件可以删了

先列出待删清单与体积，确认后再执行（删除属高风险操作，务必逐项确认）。

安全边界

• 操作前列清单：移动/重命名/删除类操作先输出完整对照清单，确认后才执行。
• 不静默覆盖：目标已存在时报告冲突而不是直接覆盖。
• 路径校验：拒绝空路径与非法字符，操作限定在指定目录范围内。
• 删除不可逆：删除类操作请先经 dsh-fs-inspector 确认体积与影响面，并遵循工作区删除规范。
• 不做递归强制删除：不提供 -rf 式的一键清除能力。

RoadMap

v0.3（计划）

• dry-run 开关（先预览、显式确认后执行）
• 批量复制/移动（复用 glob 匹配与冲突策略）
• 操作日志落盘（可追溯每次移动/重命名）

v0.4（展望）

• 与 dsh-workspace-journal 联动记录文件操作历史
• 回收站式软删除（保留恢复窗口）

版本说明

• 0.2.0：新增 fs-find glob 批量匹配与 --exclude 排除规则；fs-mkdir / fs-touch 新增 --on-conflict=skip|overwrite|rename 冲突策略（默认 skip，不静默覆盖）；补齐 test-plugin.js（50 项断言）。
• 0.1.5：路径安全加固——符号链接逃逸校验、Windows 保留设备名拦截。
• 0.1.0：初始版本——fs-list / fs-mkdir / fs-touch / fs-rm 四个基础命令。

FAQ

Q：会直接删除文件吗？ 删除类操作会先列出清单并要求确认，且不提供强制递归删除。真正的删除动作请遵循工作区删除规范执行。

Q：重命名会覆盖同名文件吗？ 不会静默覆盖，会报告冲突。

Q：支持相对路径吗？ 支持，按调用时的工作目录解析。

Q：操作失败会留下半个文件吗？ 写入类操作采用"先写临时文件再原子替换"的方式，失败不会污染原文件。

其他插件集成说明

协作插件	集成方式
dsh-fs-inspector	操作前后用 dir_size / recent_files 掌握目录变化
dsh-folder-tree	先看目录树定位目标，再用本插件增删
dsh-hash-checksum	删除/覆盖前记录摘要，便于事后核对
dsh-workspace-journal	重要文件操作记录到工作日志

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

• Fork 本仓库
• 创建特性分支 (git checkout -b feature/AmazingFeature)
• 提交更改 (git commit -m 'Add some AmazingFeature')
• 推送到分支 (git push origin feature/AmazingFeature)
• 创建 Pull Request

📞 支持

如果遇到问题，请：

• 查看文档和错误信息
• 搜索现有的 Issues
• 创建新的 Issue 描述问题