@easynet/agent-runtime 1.0.3 → 1.0.5

package/apps/itermbot/README.md

@@ -0,0 +1,82 @@
+# iTermBot
+
+iTermBot is an application built on the **@easynet** agent framework. It runs two agents:
+
+1. **ReAct agent** — LangChain `createAgent` (ReAct pattern) with tools and memory.
+2. **Deep agent** — DeepAgents `createDeepAgent` with a persistent store backed by agent-memory.
+
+Both agents share:
+
+- **@easynet/agent-common** — YAML config (app, paths).
+- **@easynet/agent-model** — LLM and embedding models (falls back to module default config).
+- **@easynet/agent-memory** — Agent memory (recall/inject for ReAct; store adapter for Deep).
+- **@easynet/agent-tool** + **@easynet/agent-tool-buildin** — Tools (FS, HTTP, util, exec, etc.).
+
+## Prerequisites
+
+- Node.js >= 18
+- Ollama (or another OpenAI-compatible endpoint) for the LLM. Default config uses `http://localhost:11434/v1` and `qwen3:0.6b`.
+
+## Setup
+
+Build from source workspace:
+
+```bash
+cd apps/itermbot
+npm install
+npm run build
+```
+
+Tool support uses agent-tool’s `@easynet/agent-tool` and `@easynet/agent-tool-buildin` from the npm registry.
+
+## Config
+
+| File | Purpose |
+|------|--------|
+| `config/app.yaml` | App-level settings (`agent`, `printSteps`, prompt templates). |
+
+Agent profile defaults (model/memory/tool/skills) are resolved by `@easynet/agent-runtime`.
+Top-level app config only overrides runtime defaults.
+
+Tool config now falls back to `@easynet/agent-tool` module defaults when app-level tool config is not provided.
+
+## Usage
+
+- **Interactive (ReAct agent):**
+  ```bash
+  npm start
+  # or
+  npm run react
+  ```
+
+- **Interactive (Deep agent):**
+  ```bash
+  npm run deep
+  ```
+
+- **One-shot query:**
+  ```bash
+  node dist/index.js react "What time is it?"
+  node dist/index.js deep "Remember I prefer short answers."
+  ```
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Compile TypeScript to `dist/`. |
+| `npm start` | Run interactive with ReAct agent. |
+| `npm run react` | Same as start (ReAct). |
+| `npm run deep` | Interactive with Deep agent. |
+| `npm run typecheck` | Type-check only. |
+| `npm run test:llm` | Test LLM config (scripts/test-llm.mjs). |
+
+## Architecture
+
+- **src/index.ts** — CLI startup and orchestration.
+- **src/context.ts** — Shared `BotContext` builders (LLM/memory/tools/skills).
+- **src/config.ts** — App-level override adapter on top of runtime config.
+- **src/startup/** — startup UI, diagnostics, and panel color bootstrapping.
+- **src/iterm/** — iTerm session routing and target session prompt injection.
+
+Both agents use the same LLM, memory backend, and tool set; only the orchestration (ReAct vs Deep) differs.

package/apps/itermbot/config/app.yaml

@@ -0,0 +1,29 @@
+apiVersion: easynet.world/v1
+kind: AppConfig
+metadata:
+  name: itermbot
+spec:
+  agent: react
+
+  printSteps: false
+
+  promptTemplates:
+    itermPolicy: |
+      ## iTerm Operating Policy
+      - Target panel output is the remote source of truth.
+      - Never use local machine commands for system/project data collection.
+      - For remote operations/investigation, use `itermRunCommandInSession` in target panel.
+      - For current screen/panel analysis, never ask user to paste text; capture via no-op `:`.
+      - For full coverage, paginate with `outputOffsetLines + maxOutputLines`, summarize by chunk, then merge.
+      - If output is long, use bounded chunk analysis with interim summaries and one final conclusion.
+      - Prefer fast/low-cost commands; avoid heavy full scans/builds/tests unless required.
+      - Host may auto-update target panel when focus moves to a non-chat panel.
+      - Final response must be valid Markdown with stable formatting.
+      - Host may auto-recover target routing (reuse non-chat pane or auto-split); if still failing, ask user.
+    targetSession: |
+      ## Target Panel Session
+      Routed target panel (may change at runtime):
+      - sessionId: "{{sessionId}}"
+      - windowId: {{windowId}}
+      - tabIndex: {{tabIndex}}
+      Never use `windowId: 0` and never guess IDs.

package/apps/itermbot/config/tool.yaml

@@ -0,0 +1,19 @@
+apiVersion: easynet.world/v1
+kind: ToolConfig
+metadata:
+  name: itermbot-local-tool-config
+spec:
+  tools:
+    list:
+      - file:../../../agent-tool-buildin#itermCreateWindow
+      - file:../../../agent-tool-buildin#itermCreateTab
+      - file:../../../agent-tool-buildin#itermSplitPane
+      - file:../../../agent-tool-buildin#itermResizeWindow
+      - file:../../../agent-tool-buildin#itermRename
+      - file:../../../agent-tool-buildin#itermSetBackgroundColor
+      - file:../../../agent-tool-buildin#itermSetSessionColors
+      - file:../../../agent-tool-buildin#itermSendText
+      - file:../../../agent-tool-buildin#itermRunCommandInSession
+      - file:../../../agent-tool-buildin#itermListCurrentWindowSessions
+      - file:../../../agent-tool-buildin#itermGetSessionInfo
+      - file:../../../agent-tool-buildin#itermListWindows

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 在很少命令内迅速锁定“谁在吃空间”；默认只输出报告与建议，释放空间动作等你授权后再执行。