@easynet/agent-runtime 1.0.3 → 1.0.4

package/apps/itermbot/config/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "../dist",
+    "rootDir": "../src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["../src/**/*"],
+  "exclude": ["../node_modules", "../dist"]
+}

package/apps/itermbot/macos_disk_usage_agent_plan.md

@@ -0,0 +1,244 @@
+# macOS 硬盘占用调查 AI Agent 方案（快速定位大户）
+
+> 目标：让 Agent 用**最少的命令**在 macOS 上快速定位“占空间最大的目录/文件类别”，并输出结构化报告。  
+> 默认原则：**只读调查**（不删除、不改系统状态），除非你明确授权。
+
+---
+
+## 0) 核心思路：分层探测 + 剪枝 + 并行
+
+- **分层探测**：先看 `/System/Volumes/Data`（数据卷）一级目录，再对“大户”逐层下钻。
+- **剪枝**：小于阈值就停止下钻；耗时过长就跳过并记录。
+- **并行**：同时扫 2~4 个路径即可（避免把机器打爆）。
+- **专项黑洞检查**：Time Machine 本地快照、iOS 备份、Xcode、Docker、Homebrew、Caches 等。
+
+---
+
+## 1) 全局画像（最快判断是不是快照/卷层面问题）
+
+### 1.1 盘与卷的占用
+```bash
+df -h
+diskutil list
+diskutil apfs list
+```
+
+**判断点**
+- `df -h`：哪个挂载点 `%Used` 最高（常见 `/`、`/System/Volumes/Data`）。
+- `diskutil apfs list`：看 APFS Container 空间分配/可用空间是否异常。
+
+### 1.2 Time Machine 本地快照是否吞空间（常见）
+```bash
+tmutil listlocalsnapshots /
+```
+
+> ⚠️ 注意：下面命令可能会释放空间（会改变系统状态），默认**不要**让 Agent 自动执行。  
+> 只在你明确授权时执行：
+```bash
+tmutil thinlocalsnapshots / 10000000000 4
+```
+
+---
+
+## 2) 快速定位“大目录”：两层 du 下钻（只扫 Data）
+
+> macOS 系统/数据分卷；真正长胖的通常在 **Data**：  
+> `/System/Volumes/Data`
+
+### 2.1 扫 Data 一级目录（速度非常快）
+```bash
+sudo du -xhd 1 /System/Volumes/Data 2>/dev/null | sort -h
+```
+
+常见大户：
+- `/System/Volumes/Data/Users`
+- `/System/Volumes/Data/Library`
+- `/System/Volumes/Data/private/var`
+
+### 2.2 对大户再下钻一级
+例如 `Users` 很大：
+```bash
+sudo du -xhd 1 /System/Volumes/Data/Users 2>/dev/null | sort -h
+```
+
+再对你的 home 下钻：
+```bash
+sudo du -xhd 1 /System/Volumes/Data/Users/<you> 2>/dev/null | sort -h
+```
+
+---
+
+## 3) 常见“容量黑洞”专项检查清单（优先级从高到低）
+
+> 建议：Agent 在定位到用户目录后，先跑这些固定路径，能极大提升命中率。
+
+### 3.1 用户目录常见大头
+
+#### Downloads / Desktop
+```bash
+du -hd 1 ~/Downloads | sort -h | tail -n 30
+du -hd 1 ~/Desktop   | sort -h | tail -n 30
+```
+
+#### iPhone / iPad 备份（极常见）
+```bash
+du -hd 1 ~/Library/Application\ Support/MobileSync/Backup 2>/dev/null | sort -h
+```
+
+#### Mail / Messages / Photos
+```bash
+du -hd 1 ~/Library/Mail 2>/dev/null | sort -h
+du -hd 1 ~/Library/Messages 2>/dev/null | sort -h
+du -hd 1 ~/Pictures 2>/dev/null | sort -h
+```
+
+#### Caches / Containers
+```bash
+du -hd 1 ~/Library/Caches 2>/dev/null | sort -h | tail -n 50
+du -hd 1 ~/Library/Containers 2>/dev/null | sort -h | tail -n 50
+```
+
+---
+
+### 3.2 开发者机器常见大头
+
+#### Xcode / iOS 模拟器 / DerivedData
+```bash
+du -hd 1 ~/Library/Developer/Xcode 2>/dev/null | sort -h
+du -hd 1 ~/Library/Developer/CoreSimulator 2>/dev/null | sort -h
+du -hd 1 ~/Library/Developer/Xcode/DerivedData 2>/dev/null | sort -h
+```
+
+#### Docker（常见爆仓）
+```bash
+du -sh ~/Library/Containers/com.docker.docker 2>/dev/null
+du -sh ~/Library/Group\ Containers/group.com.docker 2>/dev/null
+```
+
+#### Homebrew（Cellar / Cache）
+```bash
+du -sh /opt/homebrew/Cellar 2>/dev/null
+du -sh /opt/homebrew/Caskroom 2>/dev/null
+du -sh ~/Library/Caches/Homebrew 2>/dev/null
+```
+
+---
+
+## 4) 更深层“兜底扫描”（可选，但很管用）
+
+> 这个会更慢一些，但能找出 `node_modules`、`venv`、`build`、大型缓存目录等。
+
+```bash
+sudo du -xhd 4 /System/Volumes/Data/Users/<you> 2>/dev/null | sort -h | tail -n 50
+```
+
+---
+
+## 5) 并行扫描模板（控制并发 2~4）
+
+```bash
+printf "%s\n" "/System/Volumes/Data/Users" "/System/Volumes/Data/Library" "/System/Volumes/Data/private/var" | xargs -I{} -P 3 sh -c 'sudo du -xhd 1 "{}" 2>/dev/null | sort -h | tail -n 20; echo "---- {} ----"'
+```
+
+建议参数：
+- `-P 2` 或 `-P 3`：更稳
+- 扫描深度先从 `-d 1` 起步
+
+---
+
+## 6) Agent 速度关键：剪枝规则（强烈建议写进策略）
+
+### 6.1 仅扫描目标范围
+- 只扫 `/System/Volumes/Data`（避免系统目录与无意义扫描）
+- `du` 使用 `-x` 不跨文件系统，避免扫到外接盘/其它挂载点
+
+### 6.2 下钻与停止条件（推荐默认值）
+- **深度阶梯**：`1 → 2 → 3`（很少需要 > 4）
+- **继续下钻阈值**：
+  - 目录大小 **> 20GB** 或
+  - 占本层总量 **> 25%**
+- **停止条件**：
+  - 本层最大目录 **< 5GB**：停止下钻，换下一个路径
+  - 扫描某目录超过 **20s**：记录为“耗时过长”，跳过（后面专项处理）
+
+### 6.3 安全策略（默认只读）
+- 默认禁止执行会改变系统状态的命令（例如：
+  - `tmutil thinlocalsnapshots ...`
+  - `rm -rf ...`
+  - `docker system prune ...`
+  - 清理 Xcode DerivedData 等）
+- 这些动作仅在你明确授权后执行（Agent 在报告中列出候选与影响范围）。
+
+---
+
+## 7) 报告输出格式（建议 Agent 统一输出）
+
+1. **磁盘概览**
+   - `df -h`（只保留关键行：`/` 与 `/System/Volumes/Data`）
+2. **Top 大目录（分层）**
+   - Data 一级 top 10
+   - `Users` 一级 top 10
+   - 你的 home 一级 top 10（或进一步下钻结果）
+3. **专项黑洞检查结果**
+   - Time Machine 本地快照数量与日期范围
+   - iOS Backup 大小
+   - Xcode / Docker / Homebrew / Caches / Containers 大小
+4. **清理候选清单（仅建议，不执行）**
+   - `路径` + `大小` + `风险说明`（例如“仅缓存，可重建”、“可能包含重要备份”等）
+5. **需要你确认后才能执行的释放空间动作**
+   - 列出命令与预期效果、潜在影响、回滚/恢复建议
+
+---
+
+## 8) 最小可用 Agent 逻辑（伪代码）
+
+```text
+root = "/System/Volumes/Data"
+
+run df -h, diskutil apfs list
+run tmutil listlocalsnapshots /
+
+top1 = du(depth=1, path=root)
+candidates = pick(top1, size>20GB or share>25%)
+
+for c in candidates:
+  top2 = du(depth=1, path=c)
+  if max(top2) < 5GB: continue
+  subc = pick(top2, size>20GB or share>25%)
+  repeat until depth_limit=3 or stop_condition
+
+run blackhole_checks (iOS backup, caches, xcode, docker, brew...)
+compile report
+```
+
+---
+
+## 9) 你可以直接复用的“命令清单”（按执行顺序）
+
+### 9.1 全局
+```bash
+df -h
+diskutil apfs list
+tmutil listlocalsnapshots /
+```
+
+### 9.2 分层定位
+```bash
+sudo du -xhd 1 /System/Volumes/Data 2>/dev/null | sort -h
+sudo du -xhd 1 /System/Volumes/Data/Users 2>/dev/null | sort -h
+sudo du -xhd 1 /System/Volumes/Data/Users/<you> 2>/dev/null | sort -h
+```
+
+### 9.3 黑洞专项
+```bash
+du -hd 1 ~/Library/Application\ Support/MobileSync/Backup 2>/dev/null | sort -h
+du -hd 1 ~/Library/Caches 2>/dev/null | sort -h | tail -n 50
+du -hd 1 ~/Library/Developer/Xcode 2>/dev/null | sort -h
+du -sh ~/Library/Containers/com.docker.docker 2>/dev/null
+du -sh /opt/homebrew/Cellar 2>/dev/null
+```
+
+---
+
+## 总结
+这套方案用 **Data 卷优先 + du 分层下钻 + 剪枝/超时/并行 + 黑洞路径专项检查**，让 Agent 在很少命令内迅速锁定“谁在吃空间”；默认只输出报告与建议，释放空间动作等你授权后再执行。