{"id":"caba5c21-0d91-409e-ad5d-213901f4b3b2","slug":"disksense","kind":"skill","name":"DiskSense","summary":"便携式 AI 磁盘文件管理器 —— LLM Agent 驱动的磁盘分析/清理/回滚 CLI（Agent Skill 包，npm: disk-sense）","owner":"Nyaecho","repoUrl":"https://github.com/Nyaecho/DiskSense","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-21T08:27:13.000Z","addedAt":"2026-10-21T11:28:00.454Z","logoUrl":"https://avatars.githubusercontent.com/u/185469450?u=ada26a49e04b22e3743bf9672d4e863ae49aa381&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["cli","disk","disk-cleanup","llm-agent","recycle-bin","storage-analyzer","typescript","windows"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T20:37:16.320Z","sample":false,"url":"https://conduits.dev/tools/disksense","language":"TypeScript","transports":["stdio"],"install":{"npm":"disk-sense"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# DiskSense\n\n[![npm version](https://img.shields.io/npm/v/disk-sense?color=cb3837&logo=npm)](https://www.npmjs.com/package/disk-sense)\n[![CI](https://github.com/Nyaecho/DiskSense/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Nyaecho/DiskSense/actions/workflows/ci.yml)\n[![license](https://img.shields.io/github/license/Nyaecho/DiskSense)](LICENSE)\n[![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-0078d4?logo=windows)](https://www.npmjs.com/package/disk-sense)\n\n> 便携式 AI 磁盘文件管理器 —— 由 LLM Agent 驱动的本地磁盘语义化管理 CLI（Agent Skill 包）\n> Node/TypeScript 重写版；Python 历史版本归档于 [`python-legacy`](https://github.com/Nyaecho/DiskSense/tree/python-legacy) 分支\n\n融合 **Everything 的检索速度 + SpaceSniffer 的可视化 + 文件管理器的操作能力 + LLM 的语义推理**。\n\n```powershell\nnpm install -g disk-sense\n```\n\n- 开发规范：[CONTRIBUTING.md](CONTRIBUTING.md)\n- 环境：Windows 10/11 · Node.js ≥ 22\n\n---\n\n## 目录\n\n1. [它是什么](#它是什么)\n2. [快速开始](#快速开始)\n3. [在 Agent 平台使用](#在-agent-平台使用)\n4. [架构](#架构)\n5. [新鲜度账本（三层防线）](#新鲜度账本三层防线)\n6. [隐私与安全](#隐私与安全)\n7. [开发指南](#开发指南)\n\n---\n\n## 它是什么\n\nDiskSense 是一个 **Agent Skill 包**：`SKILL.md`（提示词）+ `disk-sense` CLI。Agent 加载后即可：\n\n| 能力 | 说明 |\n| :--- | :--- |\n| 极速扫描 | 本地 NTFS 盘优先 MFT 直读（需管理员，自动降级并发遍历），含 ctime 采集 |\n| 指纹聚合 | 百万文件 → 50~200 个「软件实体」档案（≤5000 Token），附语义信号 |\n| 语义信号 | `CACHE_DOMINANT`、`EXE_MISSING` 等结构化规则信号，Agent 即时推理 |\n| 快照版本化 | 同根重复扫描自动归档旧快照（每根保留 N 份），**永不覆盖丢失** |\n| 跨会话对比 | `diff_sessions` 新增/消失/变更 + 目录聚合 Top N；`growth_report` 按时间窗查增长 |\n| 高亮指令 | `viz_command` 记录高亮/标注指令（JSONL 持久化，可增量查询回放） |\n| 可逆操作 | 删除强制回收站 + $R 精确映射 + SQLite 日志 + 五步回滚 |\n| 新鲜度账本 | 会话级 `op_count` / 节点级 `stale` / 执行时预检，三层防过时改动 |\n| 无 daemon | 无后台服务；会话状态落盘 `%LOCALAPPDATA%\\disk-sense\\sessions.db`，npm 一装即用 |\n\n## 快速开始\n\n```powershell\n# 1. 安装（Node.js ≥ 20）\nnpm install -g disk-sense\n\n# 2. 验证（扫描 D:\\ 某目录）\ndisk-sense start_scan --drive D:/some/dir\n```\n\n无配置即可运行；卸载 = `npm uninstall -g disk-sense` 并删除 `%LOCALAPPDATA%\\disk-sense`。\n\n> MFT 直读需要管理员权限运行终端；普通权限自动降级为多线程遍历（速度略慢但功能等价）。\n\n## 在 Agent 平台使用\n\n### cc-switch / Claude Code / OpenCode / Codex\n\n本包是标准 Agent Skill（frontmatter 符合各家识别规则），安装方式二选一：\n\n```powershell\n# 方式 A：npm 全局安装 CLI + symlink 技能目录\nmkdir -p ~/.claude/skills\nmklink /J \"%USERPROFILE%\\.claude\\skills\\disk-sense-manager\" \"<仓库绝对路径>\"\n\n# 方式 B：仅 symlink（Agent 内通过 npx 调用 CLI）\nmklink /J \"%USERPROFILE%\\.agents\\skills\\disk-sense-manager\" \"<仓库绝对路径>\"\n```\n\n- Claude Code：会话内 `/disk-sense-manager` 显式调用，或说\"分析 D 盘空间\"按 description 自动触发\n- OpenCode：从 cwd 向上遍历加载 `.opencode/`、`.claude/`、`.agents/` 下的 `skills/*/SKILL.md`\n- Codex：认 `.agents/skills` 目录，显式调用 `$disk-sense-manager`\n\n## 架构\n\n```\n用户 ↔ Agent 聊天窗\n        │ Bash: disk-sense <tool>\n        ▼\n   disk-sense CLI（单进程，无 daemon）\n        │\n   ┌────┴─────┬──────────┬───────────┬────────────┬──────────┐\n   │ scanner  │aggregator│ rules     │ operator   │ state    │\n   │ mft.ts   │ 四角色映射│ engine.ts │ recycle-bin│ session  │\n   │ walk.ts  │ 伪实体   │ (YAML 规则)│ undo(SQLite)│ overlays │\n   └──────────┴──────────┴───────────┴────────────┴──────────┘\n```\n\n| 模块 | 职责 |\n| :--- | :--- |\n| `scanner/mft.ts` | koffi 开卷句柄 → FSCTL 定位 $MFT → Fixup/$FILE_NAME 解析；失败静默降级 |\n| `scanner/walk.ts` | libuv 线程池并发 readdir；Junction 防护、忽略模式、受限目录跳过 |\n| `aggregator.ts` | 种子提取、四角色映射、位置异常关联、global_anomalies 批量魔数 |\n| `magic.ts` | 文件头 16 字节魔数识别（全仓库唯一允许读文件字节处） |\n| `rules-engine.ts` | SafeEvaluator：受限算子白名单评估 YAML 条件树，绝不 eval |\n| `operator/recycle-bin.ts` | SHFileOperationW 回收站删除、$I/$R 解析、受控清空 |\n| `operator/file-operator.ts` | move/copy/compress + 五步回滚 + 保护路径拒绝 |\n| `operator/undo-manager.ts` | SQLite 操作日志、超期归档 |\n| `state/session.ts` | SQLite 会话库（live 行式 + 归档 gzip blob）+ 快照版本化 + op_count 新鲜度账本 |\n\n## 新鲜度账本（三层防线）\n\n无 daemon 化后「快照 vs 磁盘现状」的偏差由三层机制防护：\n\n| 层级 | 机制 | 回答的问题 |\n| :--- | :--- | :--- |\n| 会话级 | `op_count` + `recent_ops`（每次 execute/undo 后递增，rescan 归零） | 这份分析结论整体还可信吗 |\n| 节点级 | 受影响子树 `stale`/`stale_since` 标记（查询端点透传） | 这个子树的具体数字还准吗 |\n| 执行时 | 预检逐源校验存在性 + mtime 比对，冲突拒绝或告警 | 这条路径现在还能动吗 |\n\n所有分析类输出附带 `stale_hint`（如 `\"快照后已有 2 次操作\"`），Agent 据此决定是否 rescan。\n\n## 隐私与安全\n\n| 检查项 | 状态 |\n| :--- | :--- |\n| 读取文件正文（PDF/Word/TXT/图片） | ❌ 永不；仅 `magic.ts` 读 16 字节文件头判定格式 |\n| 数据上传 | ❌ 全部本地执行，零遥测 |\n| 删除可逆 | ✅ 强制回收站 + $R 精确映射 + SQLite 审计 |\n| 权限越界 | ❌ 永不 takeown/icacls；受限目录标记跳过 |\n| 便携无痕 | ✅ 零注册表/服务/自启；npm 卸载 + 删数据目录即清除 |\n| 稀疏文件 | ✅ 读取前比对实际占用，避免触发填充 |\n\n## 开发指南\n\n```powershell\nnpm install\nnpm test          # vitest（含真实回收站往返集成测试）\nnpm run typecheck # tsc --noEmit\nnpm run build     # 输出 dist/\n```\n\n- 提交规范 / 代码规范 / 隐私红线：[CONTRIBUTING.md](CONTRIBUTING.md)\n- MFT 解析器、规则引擎、聚合器均为纯函数，测试用合成字节，无需管理员权限\n- Python 历史实现见 `python-legacy` 分支（模块级对照移植）\n\n## 许可证\n\n[MIT](LICENSE) © 2026 Nyaecho\n"}