myspace-cli 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. myspace_cli-1.2.0/PKG-INFO +284 -0
  2. myspace_cli-1.2.0/README.md +265 -0
  3. myspace_cli-1.2.0/myspace_cli.egg-info/PKG-INFO +284 -0
  4. myspace_cli-1.2.0/myspace_cli.egg-info/SOURCES.txt +9 -0
  5. myspace_cli-1.2.0/myspace_cli.egg-info/dependency_links.txt +1 -0
  6. myspace_cli-1.2.0/myspace_cli.egg-info/entry_points.txt +2 -0
  7. myspace_cli-1.2.0/myspace_cli.egg-info/requires.txt +3 -0
  8. myspace_cli-1.2.0/myspace_cli.egg-info/top_level.txt +1 -0
  9. myspace_cli-1.2.0/pyproject.toml +34 -0
  10. myspace_cli-1.2.0/setup.cfg +4 -0
  11. myspace_cli-1.2.0/space_cli.py +847 -0
myspace_cli-1.2.0/PKG-INFO ADDED
@@ -0,0 +1,284 @@
1
+ Metadata-Version: 2.4
2
+ Name: myspace-cli
3
+ Version: 1.2.0
4
+ Summary: A macOS disk space analysis CLI: health, index, app usage, big files.
5
+ Author-email: Your Name <you@example.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/kennyz/space-cli
8
+ Project-URL: Issues, https://github.com/kennyz/space-cli/issues
9
+ Keywords: disk,space,cleanup,macos,cli
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: MacOS
13
+ Classifier: Environment :: Console
14
+ Classifier: Topic :: System :: Filesystems
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+ Provides-Extra: mcp
18
+ Requires-Dist: mcp<2,>=1; extra == "mcp"
19
+
20
+ # space-cli - Mac OS 磁盘空间分析工具
21
+
22
+ 很多人的Mac电脑都会出现磁盘空间不够用，付费软件太贵或者难以使用。
23
+
24
+ space-cli是一个开源的Mac OS命令行小工具，用于分析磁盘空间健康度并找出占用空间最大的目录。
25
+
26
+ 本软件采用**最严安全原则**，所有操作采用只读模式，不会尝试改写和破坏用户电脑的任何数据，也不会上传任何数据到外网，严格保护用户的隐私。
27
+
28
+ ## 功能特性
29
+
30
+ - 🔍 **磁盘健康度检测** - 评估磁盘空间使用情况，提供健康状态建议
31
+ - 📊 **目录大小分析** - 递归分析目录大小，找出占用空间最大的文件夹
32
+ - 💻 **系统信息显示** - 显示Mac系统版本和基本信息
33
+ - 📄 **报告导出** - 将分析结果导出为JSON格式报告
34
+ - ⚡ **高性能** - 优化的算法，快速分析大型文件系统
35
+ - 🎯 **灵活配置** - 支持自定义分析路径和显示数量
36
+ - 🗂️ **索引缓存** - 目录大小结果本地索引缓存（`~/.spacecli/index.json`），支持TTL与重建提示
37
+ - 🧩 **应用分析** - 汇总 `Applications`、`Library`、`Caches`、`Logs` 等路径估算应用占用，给出卸载建议
38
+ - 🏠 **用户目录深度分析** - 针对 `~/Library`、`~/Downloads`、`~/Documents` 分别下探并展示Top N目录
39
+ - 🗄️ **大文件分析** - 扫描并列出指定路径下最大的文件，支持数量和最小体积阈值
40
+ - ⏱️ **支持MCP调用** - 支持你自己的AI Agent无缝调用磁盘空间信息
41
+
42
+ ## 安装
43
+
44
+ ### 方法1：直接使用（推荐）
45
+
46
+ ```bash
47
+ # 克隆或下载项目
48
+ git clone https://github.com/kennyz/space-cli
49
+ cd MacDiskSpace
50
+
51
+ # 给脚本添加执行权限
52
+ chmod +x space_cli.py
53
+
54
+ # 运行
55
+ python3 space_cli.py
56
+ ```
57
+
58
+ ### 方法2：创建全局命令
59
+
60
+ ```bash
61
+ # 复制到系统路径
62
+ sudo cp space_cli.py /usr/local/bin/space-cli
63
+ sudo chmod +x /usr/local/bin/space-cli
64
+
65
+ # 现在可以在任何地方使用
66
+ space-cli
67
+ ```
68
+
69
+ ### 方法3：通过 pip 安装（发布到 PyPI 后）
70
+
71
+ ```bash
72
+ python3 -m pip install --upgrade spacecli
73
+
74
+ # 直接使用命令
75
+ space-cli --help
76
+
77
+ # 或者作为模块调用
78
+ python3 -m space_cli --help
79
+ ```
80
+
81
+ ## 使用方法
82
+
83
+ ### 基本用法
84
+
85
+ ```bash
86
+ # 分析根目录（默认）
87
+ python3 space_cli.py
88
+
89
+ # 分析指定路径
90
+ python3 space_cli.py -p /Users/username
91
+
92
+ # 显示前10个最大的目录
93
+ python3 space_cli.py -n 10
94
+
95
+ # 快捷分析当前用户目录（含用户目录深度分析）
96
+ python3 space_cli.py --home
97
+ ```
98
+
99
+ ### 高级用法
100
+
101
+ ```bash
102
+ # 只显示磁盘健康状态
103
+ python3 space_cli.py --health-only
104
+
105
+ # 只显示目录分析
106
+ python3 space_cli.py --directories-only
107
+
108
+ # 导出分析报告
109
+ python3 space_cli.py --export disk_report.json
110
+
111
+ # 分析用户目录并导出报告
112
+ python3 space_cli.py -p /Users -n 15 --export user_analysis.json
113
+
114
+ # 使用索引缓存（默认开启）
115
+ python3 space_cli.py --use-index
116
+
117
+ # 强制重建索引
118
+ python3 space_cli.py --reindex
119
+
120
+ # 设置索引缓存有效期为 6 小时
121
+ python3 space_cli.py --index-ttl 6
122
+
123
+ # 非交互，不提示使用缓存
124
+ python3 space_cli.py --no-prompt
125
+
126
+ # 分析应用目录占用并给出卸载建议（按应用归并）
127
+ python3 space_cli.py --apps -n 20
128
+
129
+ # 大文件分析（显示前20个，阈值2G）
130
+ python3 space_cli.py --big-files --big-files-top 20 --big-files-min 2G
131
+
132
+ # 将含大文件分析的结果写入导出报告
133
+ python3 space_cli.py --big-files --export report.json
134
+
135
+
136
+ ```
137
+
138
+
139
+ ### 命令行参数
140
+
141
+ | 参数 | 说明 | 默认值 |
142
+ |------|------|--------|
143
+ | `-p, --path` | 要分析的路径 | `/` |
144
+ | `-n, --top-n` | 显示前N个最大的目录 | `20` |
145
+ | `--health-only` | 只显示磁盘健康状态 | - |
146
+ | `--directories-only` | 只显示目录分析 | - |
147
+ | `--export FILE` | 导出报告到JSON文件 | - |
148
+ | `--use-index` | 使用索引缓存（默认） | - |
149
+ | `--no-index` | 禁用索引缓存 | - |
150
+ | `--reindex` | 强制重建索引 | - |
151
+ | `--index-ttl` | 索引缓存有效期（小时） | `24` |
152
+ | `--no-prompt` | 非交互模式，不提示使用缓存 | - |
153
+ | `--apps` | 分析应用目录空间与卸载建议 | - |
154
+ | `--home` | 将分析路径设置为当前用户目录 | - |
155
+ | `--big-files` | 启用大文件分析 | - |
156
+ | `--big-files-top` | 大文件列表数量 | `20` |
157
+ | `--big-files-min` | 大文件最小阈值（K/M/G/T） | `0` |
158
+ | `--version` | 显示版本信息 | - |
159
+ | `-h, --help` | 显示帮助信息 | - |
160
+
161
+ ## 输出示例
162
+
163
+ ### 磁盘健康状态
164
+ ```
165
+ ============================================================
166
+ 🔍 磁盘空间健康度分析
167
+ ============================================================
168
+ 磁盘路径: /
169
+ 总容量: 500.0 GB
170
+ 已使用: 400.0 GB
171
+ 可用空间: 100.0 GB
172
+ 使用率: 80.0%
173
+ 健康状态: ⚠️ 警告
174
+ 建议: 磁盘空间不足，建议清理一些文件
175
+ ```
176
+
177
+ ### 目录分析
178
+ ```
179
+ ============================================================
180
+ 📊 占用空间最大的目录
181
+ ============================================================
182
+ 显示前 20 个最大的目录:
183
+
184
+ 1. /Applications
185
+ 大小: 15.2 GB (3.04%)
186
+
187
+ 2. /Users/username/Library
188
+ 大小: 8.5 GB (1.70%)
189
+
190
+ 3. /System
191
+ 大小: 6.8 GB (1.36%)
192
+ ```
193
+
194
+ ### 大文件分析
195
+ ```
196
+ ============================================================
197
+ 🗄️ 大文件分析
198
+ ============================================================
199
+ 1. /Users/username/Downloads/big.iso -- 大小: 7.2 GB (1.44%)
200
+ 2. /Users/username/Movies/clip.mov -- 大小: 3.1 GB (0.62%)
201
+ ```
202
+
203
+
204
+ ## MCP Server（可选）
205
+
206
+ 本项目提供 MCP Server，方便在支持 MCP 的客户端中以“工具”的形式调用：
207
+
208
+ ### 安装依赖
209
+ ```bash
210
+ python3 -m pip install mcp
211
+ ```
212
+
213
+ ### 启动MCP服务
214
+ ```bash
215
+ python3 mcp_server.py
216
+ ```
217
+
218
+ ### MCP暴露的工具
219
+ - `disk_health(path="/")`
220
+ - `largest_directories(path="/", top_n=20, use_index=True, reindex=False, index_ttl=24)`
221
+ - `app_analysis(top_n=20, use_index=True, reindex=False, index_ttl=24)`
222
+ - `big_files(path="/", top_n=20, min_size="0")`
223
+
224
+ 以上工具与 CLI 输出保持一致的逻辑（索引缓存、阈值等），适合与 IDE/Agent 集成。
225
+
226
+
227
+ ## 性能优化
228
+
229
+ - 使用递归算法高效计算目录大小
230
+ - 跳过无法访问的系统文件和隐藏文件
231
+ - 支持中断操作（Ctrl+C）
232
+ - 内存优化的文件遍历
233
+ - 单行滚动进度避免输出刷屏
234
+
235
+ ## 故障排除
236
+
237
+ ### 权限问题
238
+ 如果遇到权限错误，可以尝试：
239
+ ```bash
240
+ # 使用sudo运行（谨慎使用）
241
+ sudo python3 space_cli.py
242
+
243
+ # 或者分析用户目录
244
+ python3 space_cli.py -p /Users/$(whoami)
245
+ ```
246
+
247
+ ### 性能问题
248
+ 对于大型文件系统，分析可能需要较长时间：
249
+ - 使用 `--directories-only` 跳过健康检查
250
+ - 减少 `-n` 参数值
251
+ - 分析特定子目录而不是根目录
252
+ - 使用 `--big-files-min` 提高阈值可减少扫描文件数量
253
+ - 使用 `--use-index`/`--reindex`/`--index-ttl` 控制索引的使用与刷新
254
+
255
+ ## 系统要求
256
+
257
+ - macOS 10.12 或更高版本
258
+ - Python 3.6 或更高版本
259
+ - 足够的磁盘空间用于临时文件
260
+
261
+ ## 许可证
262
+
263
+ MIT License
264
+
265
+ ## 贡献
266
+
267
+ 欢迎提交Issue和Pull Request来改进这个工具！
268
+
269
+ ## 更新日志
270
+
271
+ ### v1.0.0
272
+ - 初始版本发布
273
+ - 基本的磁盘健康度检测
274
+ - 目录大小分析功能
275
+ - JSON报告导出
276
+ - 命令行参数支持
277
+
278
+ ### v1.1.0
279
+ - 新增交互式菜单（无参数时出现），默认执行全部项目
280
+ - 新增 `--home` 用户目录快速分析与用户目录深度分析
281
+ - 新增应用分析缓存（`~/.cache/spacecli/apps.json`）
282
+ - 新增大文件分析 `--big-files`/`--big-files-top`/`--big-files-min`
283
+ - 导出报告在启用大文件分析时包含 `largest_files`
284
+ - 单行滚动进度显示
myspace_cli-1.2.0/README.md ADDED
@@ -0,0 +1,265 @@
1
+ # space-cli - Mac OS 磁盘空间分析工具
2
+
3
+ 很多人的Mac电脑都会出现磁盘空间不够用，付费软件太贵或者难以使用。
4
+
5
+ space-cli是一个开源的Mac OS命令行小工具，用于分析磁盘空间健康度并找出占用空间最大的目录。
6
+
7
+ 本软件采用**最严安全原则**，所有操作采用只读模式，不会尝试改写和破坏用户电脑的任何数据，也不会上传任何数据到外网，严格保护用户的隐私。
8
+
9
+ ## 功能特性
10
+
11
+ - 🔍 **磁盘健康度检测** - 评估磁盘空间使用情况，提供健康状态建议
12
+ - 📊 **目录大小分析** - 递归分析目录大小，找出占用空间最大的文件夹
13
+ - 💻 **系统信息显示** - 显示Mac系统版本和基本信息
14
+ - 📄 **报告导出** - 将分析结果导出为JSON格式报告
15
+ - ⚡ **高性能** - 优化的算法，快速分析大型文件系统
16
+ - 🎯 **灵活配置** - 支持自定义分析路径和显示数量
17
+ - 🗂️ **索引缓存** - 目录大小结果本地索引缓存（`~/.spacecli/index.json`），支持TTL与重建提示
18
+ - 🧩 **应用分析** - 汇总 `Applications`、`Library`、`Caches`、`Logs` 等路径估算应用占用，给出卸载建议
19
+ - 🏠 **用户目录深度分析** - 针对 `~/Library`、`~/Downloads`、`~/Documents` 分别下探并展示Top N目录
20
+ - 🗄️ **大文件分析** - 扫描并列出指定路径下最大的文件，支持数量和最小体积阈值
21
+ - ⏱️ **支持MCP调用** - 支持你自己的AI Agent无缝调用磁盘空间信息
22
+
23
+ ## 安装
24
+
25
+ ### 方法1：直接使用（推荐）
26
+
27
+ ```bash
28
+ # 克隆或下载项目
29
+ git clone https://github.com/kennyz/space-cli
30
+ cd MacDiskSpace
31
+
32
+ # 给脚本添加执行权限
33
+ chmod +x space_cli.py
34
+
35
+ # 运行
36
+ python3 space_cli.py
37
+ ```
38
+
39
+ ### 方法2：创建全局命令
40
+
41
+ ```bash
42
+ # 复制到系统路径
43
+ sudo cp space_cli.py /usr/local/bin/space-cli
44
+ sudo chmod +x /usr/local/bin/space-cli
45
+
46
+ # 现在可以在任何地方使用
47
+ space-cli
48
+ ```
49
+
50
+ ### 方法3：通过 pip 安装（发布到 PyPI 后）
51
+
52
+ ```bash
53
+ python3 -m pip install --upgrade spacecli
54
+
55
+ # 直接使用命令
56
+ space-cli --help
57
+
58
+ # 或者作为模块调用
59
+ python3 -m space_cli --help
60
+ ```
61
+
62
+ ## 使用方法
63
+
64
+ ### 基本用法
65
+
66
+ ```bash
67
+ # 分析根目录（默认）
68
+ python3 space_cli.py
69
+
70
+ # 分析指定路径
71
+ python3 space_cli.py -p /Users/username
72
+
73
+ # 显示前10个最大的目录
74
+ python3 space_cli.py -n 10
75
+
76
+ # 快捷分析当前用户目录（含用户目录深度分析）
77
+ python3 space_cli.py --home
78
+ ```
79
+
80
+ ### 高级用法
81
+
82
+ ```bash
83
+ # 只显示磁盘健康状态
84
+ python3 space_cli.py --health-only
85
+
86
+ # 只显示目录分析
87
+ python3 space_cli.py --directories-only
88
+
89
+ # 导出分析报告
90
+ python3 space_cli.py --export disk_report.json
91
+
92
+ # 分析用户目录并导出报告
93
+ python3 space_cli.py -p /Users -n 15 --export user_analysis.json
94
+
95
+ # 使用索引缓存（默认开启）
96
+ python3 space_cli.py --use-index
97
+
98
+ # 强制重建索引
99
+ python3 space_cli.py --reindex
100
+
101
+ # 设置索引缓存有效期为 6 小时
102
+ python3 space_cli.py --index-ttl 6
103
+
104
+ # 非交互，不提示使用缓存
105
+ python3 space_cli.py --no-prompt
106
+
107
+ # 分析应用目录占用并给出卸载建议（按应用归并）
108
+ python3 space_cli.py --apps -n 20
109
+
110
+ # 大文件分析（显示前20个，阈值2G）
111
+ python3 space_cli.py --big-files --big-files-top 20 --big-files-min 2G
112
+
113
+ # 将含大文件分析的结果写入导出报告
114
+ python3 space_cli.py --big-files --export report.json
115
+
116
+
117
+ ```
118
+
119
+
120
+ ### 命令行参数
121
+
122
+ | 参数 | 说明 | 默认值 |
123
+ |------|------|--------|
124
+ | `-p, --path` | 要分析的路径 | `/` |
125
+ | `-n, --top-n` | 显示前N个最大的目录 | `20` |
126
+ | `--health-only` | 只显示磁盘健康状态 | - |
127
+ | `--directories-only` | 只显示目录分析 | - |
128
+ | `--export FILE` | 导出报告到JSON文件 | - |
129
+ | `--use-index` | 使用索引缓存（默认） | - |
130
+ | `--no-index` | 禁用索引缓存 | - |
131
+ | `--reindex` | 强制重建索引 | - |
132
+ | `--index-ttl` | 索引缓存有效期（小时） | `24` |
133
+ | `--no-prompt` | 非交互模式，不提示使用缓存 | - |
134
+ | `--apps` | 分析应用目录空间与卸载建议 | - |
135
+ | `--home` | 将分析路径设置为当前用户目录 | - |
136
+ | `--big-files` | 启用大文件分析 | - |
137
+ | `--big-files-top` | 大文件列表数量 | `20` |
138
+ | `--big-files-min` | 大文件最小阈值（K/M/G/T） | `0` |
139
+ | `--version` | 显示版本信息 | - |
140
+ | `-h, --help` | 显示帮助信息 | - |
141
+
142
+ ## 输出示例
143
+
144
+ ### 磁盘健康状态
145
+ ```
146
+ ============================================================
147
+ 🔍 磁盘空间健康度分析
148
+ ============================================================
149
+ 磁盘路径: /
150
+ 总容量: 500.0 GB
151
+ 已使用: 400.0 GB
152
+ 可用空间: 100.0 GB
153
+ 使用率: 80.0%
154
+ 健康状态: ⚠️ 警告
155
+ 建议: 磁盘空间不足，建议清理一些文件
156
+ ```
157
+
158
+ ### 目录分析
159
+ ```
160
+ ============================================================
161
+ 📊 占用空间最大的目录
162
+ ============================================================
163
+ 显示前 20 个最大的目录:
164
+
165
+ 1. /Applications
166
+ 大小: 15.2 GB (3.04%)
167
+
168
+ 2. /Users/username/Library
169
+ 大小: 8.5 GB (1.70%)
170
+
171
+ 3. /System
172
+ 大小: 6.8 GB (1.36%)
173
+ ```
174
+
175
+ ### 大文件分析
176
+ ```
177
+ ============================================================
178
+ 🗄️ 大文件分析
179
+ ============================================================
180
+ 1. /Users/username/Downloads/big.iso -- 大小: 7.2 GB (1.44%)
181
+ 2. /Users/username/Movies/clip.mov -- 大小: 3.1 GB (0.62%)
182
+ ```
183
+
184
+
185
+ ## MCP Server（可选）
186
+
187
+ 本项目提供 MCP Server，方便在支持 MCP 的客户端中以“工具”的形式调用：
188
+
189
+ ### 安装依赖
190
+ ```bash
191
+ python3 -m pip install mcp
192
+ ```
193
+
194
+ ### 启动MCP服务
195
+ ```bash
196
+ python3 mcp_server.py
197
+ ```
198
+
199
+ ### MCP暴露的工具
200
+ - `disk_health(path="/")`
201
+ - `largest_directories(path="/", top_n=20, use_index=True, reindex=False, index_ttl=24)`
202
+ - `app_analysis(top_n=20, use_index=True, reindex=False, index_ttl=24)`
203
+ - `big_files(path="/", top_n=20, min_size="0")`
204
+
205
+ 以上工具与 CLI 输出保持一致的逻辑（索引缓存、阈值等），适合与 IDE/Agent 集成。
206
+
207
+
208
+ ## 性能优化
209
+
210
+ - 使用递归算法高效计算目录大小
211
+ - 跳过无法访问的系统文件和隐藏文件
212
+ - 支持中断操作（Ctrl+C）
213
+ - 内存优化的文件遍历
214
+ - 单行滚动进度避免输出刷屏
215
+
216
+ ## 故障排除
217
+
218
+ ### 权限问题
219
+ 如果遇到权限错误，可以尝试：
220
+ ```bash
221
+ # 使用sudo运行（谨慎使用）
222
+ sudo python3 space_cli.py
223
+
224
+ # 或者分析用户目录
225
+ python3 space_cli.py -p /Users/$(whoami)
226
+ ```
227
+
228
+ ### 性能问题
229
+ 对于大型文件系统，分析可能需要较长时间：
230
+ - 使用 `--directories-only` 跳过健康检查
231
+ - 减少 `-n` 参数值
232
+ - 分析特定子目录而不是根目录
233
+ - 使用 `--big-files-min` 提高阈值可减少扫描文件数量
234
+ - 使用 `--use-index`/`--reindex`/`--index-ttl` 控制索引的使用与刷新
235
+
236
+ ## 系统要求
237
+
238
+ - macOS 10.12 或更高版本
239
+ - Python 3.6 或更高版本
240
+ - 足够的磁盘空间用于临时文件
241
+
242
+ ## 许可证
243
+
244
+ MIT License
245
+
246
+ ## 贡献
247
+
248
+ 欢迎提交Issue和Pull Request来改进这个工具！
249
+
250
+ ## 更新日志
251
+
252
+ ### v1.0.0
253
+ - 初始版本发布
254
+ - 基本的磁盘健康度检测
255
+ - 目录大小分析功能
256
+ - JSON报告导出
257
+ - 命令行参数支持
258
+
259
+ ### v1.1.0
260
+ - 新增交互式菜单（无参数时出现），默认执行全部项目
261
+ - 新增 `--home` 用户目录快速分析与用户目录深度分析
262
+ - 新增应用分析缓存（`~/.cache/spacecli/apps.json`）
263
+ - 新增大文件分析 `--big-files`/`--big-files-top`/`--big-files-min`
264
+ - 导出报告在启用大文件分析时包含 `largest_files`
265
+ - 单行滚动进度显示