better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md

@@ -0,0 +1,180 @@
+---
+title: "Jupyter Notebook — 通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）"
+sidebar_label: "Jupyter Notebook"
+description: "通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Jupyter Notebook
+
+通过实时 Jupyter 内核进行迭代式 Python 开发（hamelnb）。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 通过 `hermes skills install official/data-science/jupyter-notebook` 安装 |
+| 路径 | `optional-skills/data-science/jupyter-notebook` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `jupyter`, `notebook`, `repl`, `data-science`, `exploration`, `iterative` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Jupyter Notebook（hamelnb 实时内核）
+
+通过实时 Jupyter 内核为你提供一个**有状态的 Python REPL**（交互式解释器）。变量在多次执行之间持久保留。当你需要逐步构建状态、探索 API、检查 DataFrame 或迭代复杂代码时，请使用此工具而非 `execute_code`。
+
+## 何时使用本 Skill 与其他工具
+
+| 工具 | 使用场景 |
+|------|----------|
+| **本 skill** | 迭代式探索、跨步骤保持状态、数据科学、机器学习、"试试看再检查" |
+| `execute_code` | 需要访问 Hermes 工具（web_search、文件操作）的一次性脚本。无状态。 |
+| `terminal` | Shell 命令、构建、安装、git、进程管理 |
+
+**经验法则：** 如果你会为某个任务打开 Jupyter notebook，就使用本 skill。
+
+## 前置条件
+
+1. 必须安装 **uv**（检查：`which uv`）
+2. 必须安装 **JupyterLab**：`uv tool install jupyterlab`
+3. 必须有一个正在运行的 Jupyter 服务器（参见下方"设置"部分）
+
+## 设置
+
+hamelnb 脚本位置：
+```
+SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"
+```
+
+如果尚未克隆：
+```
+git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb
+```
+
+### 启动 JupyterLab
+
+检查是否已有服务器在运行：
+```
+uv run "$SCRIPT" servers
+```
+
+如果未找到服务器，启动一个：
+```
+jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
+  --IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
+sleep 3
+```
+
+注意：已禁用 token/password 以供本地 agent 访问。服务器以无头模式运行。
+
+### 为 REPL 使用创建 Notebook
+
+如果你只需要一个 REPL（无需现有 notebook），创建一个最小化的 notebook 文件：
+```
+mkdir -p ~/notebooks
+```
+写入一个包含一个空代码单元格的最小 .ipynb JSON 文件，然后通过 Jupyter REST API 启动一个内核会话：
+```
+curl -s -X POST http://127.0.0.1:8888/api/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python3"}}'
+```
+
+## 核心工作流
+
+所有命令均返回结构化 JSON。始终使用 `--compact` 以节省 token。
+
+### 1. 发现服务器和 notebook
+
+```
+uv run "$SCRIPT" servers --compact
+uv run "$SCRIPT" notebooks --compact
+```
+
+### 2. 执行代码（主要操作）
+
+```
+uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact
+```
+
+状态在多次 execute 调用之间持久保留。变量、导入、对象均会保留。
+
+多行代码可使用 `$'...'` 引号语法：
+```
+uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact
+```
+
+### 3. 检查实时变量
+
+```
+uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
+uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
+```
+
+### 4. 编辑 notebook 单元格
+
+```
+# 查看当前单元格
+uv run "$SCRIPT" contents --path <notebook.ipynb> --compact
+
+# 插入新单元格
+uv run "$SCRIPT" edit --path <notebook.ipynb> insert \
+  --at-index <N> --cell-type code --source '<code>' --compact
+
+# 替换单元格源码（使用 contents 输出中的 cell-id）
+uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \
+  --cell-id <id> --source '<new code>' --compact
+
+# 删除单元格
+uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact
+```
+
+### 5. 验证（重启并全部运行）
+
+仅在用户要求进行干净验证，或你需要确认 notebook 能从头到尾运行时使用：
+
+```
+uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact
+```
+
+## 实践经验提示
+
+1. **服务器启动后首次执行可能超时** —— 内核需要片刻时间初始化。如果超时，重试即可。
+
+2. **内核 Python 是 JupyterLab 的 Python** —— 包必须安装在该环境中。如需额外的包，请先将其安装到 JupyterLab 工具环境中。
+
+3. **`--compact` 标志可显著节省 token** —— 始终使用它。不加此标志时 JSON 输出可能非常冗长。
+
+4. **纯 REPL 使用时**，创建一个 scratch.ipynb，无需关心单元格编辑。反复使用 `execute` 即可。
+
+5. **参数顺序很重要** —— 子命令标志（如 `--path`）必须放在子子命令**之前**。例如：`variables --path nb.ipynb list`，而非 `variables list --path nb.ipynb`。
+
+6. **如果会话尚不存在**，需要通过 REST API 启动一个（参见"设置"部分）。没有实时内核会话，工具无法执行代码。
+
+7. **错误以 JSON 形式返回**，包含 traceback —— 读取 `ename` 和 `evalue` 字段以了解出错原因。
+
+8. **偶发的 websocket 超时** —— 某些操作（尤其是内核重启后）首次尝试可能超时。在上报问题前先重试一次。
+
+9. **如果 websocket 在此主机上持续超时**，强制使用 zmq 传输：
+   `uv run "$SCRIPT" execute --transport zmq ...`。症状：每次 execute 都返回
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped"。内核实际上运行正常（REST 显示 execution_state=idle 且
+   execution_count 递增）—— 只是 websocket 回复通道损坏。zmq 传输直接使用
+   jupyter_client，可绕过此问题。
+
+10. **为纯 REST 使用启动新服务器时**，添加
+    `--ServerApp.disable_check_xsrf=True` —— 否则 POST /api/sessions 会返回
+    `"'_xsrf' argument missing from POST"`，导致内核会话创建失败。
+
+## 超时默认值
+
+脚本每次执行的默认超时为 30 秒。对于长时间运行的操作，传入 `--timeout 120`。初始设置或大量计算时，建议使用较宽松的超时值（60 秒以上）。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/devops/devops-docker-management.md

@@ -0,0 +1,297 @@
+---
+title: "Docker 管理"
+sidebar_label: "Docker 管理"
+description: "管理 Docker 容器、镜像、卷、网络和 Compose 栈——生命周期操作、调试、清理及 Dockerfile 优化"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Docker 管理
+
+管理 Docker 容器、镜像、卷、网络和 Compose 栈——生命周期操作、调试、清理及 Dockerfile 优化。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选——使用 `hermes skills install official/devops/docker-management` 安装 |
+| 路径 | `optional-skills/devops/docker-management` |
+| 版本 | `1.0.0` |
+| 作者 | sprmn24 |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `docker`, `containers`, `devops`, `infrastructure`, `compose`, `images`, `volumes`, `networks`, `debugging` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Docker 管理
+
+使用标准 Docker CLI 命令管理 Docker 容器、镜像、卷、网络和 Compose 栈。除 Docker 本身外无需额外依赖。
+
+## 适用场景
+
+- 运行、停止、重启、删除或检查容器
+- 构建、拉取、推送、标记或清理 Docker 镜像
+- 使用 Docker Compose（多服务栈）
+- 管理卷或网络
+- 调试崩溃的容器或分析日志
+- 检查 Docker 磁盘使用情况或释放空间
+- 审查或优化 Dockerfile
+
+## 前提条件
+
+- Docker Engine 已安装并运行
+- 用户已加入 `docker` 组（或使用 `sudo`）
+- Docker Compose v2（现代 Docker 安装已包含）
+
+快速检查：
+
+```bash
+docker --version && docker compose version
+```
+
+## 快速参考
+
+| 任务 | 命令 |
+|------|---------|
+| 运行容器（后台） | `docker run -d --name NAME IMAGE` |
+| 停止并删除 | `docker stop NAME && docker rm NAME` |
+| 查看日志（跟踪） | `docker logs --tail 50 -f NAME` |
+| 进入容器 Shell | `docker exec -it NAME /bin/sh` |
+| 列出所有容器 | `docker ps -a` |
+| 构建镜像 | `docker build -t TAG .` |
+| Compose 启动 | `docker compose up -d` |
+| Compose 停止 | `docker compose down` |
+| 磁盘使用情况 | `docker system df` |
+| 清理悬空资源 | `docker image prune && docker container prune` |
+
+## 操作流程
+
+### 1. 确定操作域
+
+判断请求属于哪个领域：
+
+- **容器生命周期** → run、stop、start、restart、rm、pause/unpause
+- **容器交互** → exec、cp、logs、inspect、stats
+- **镜像管理** → build、pull、push、tag、rmi、save/load
+- **Docker Compose** → up、down、ps、logs、exec、build、config
+- **卷与网络** → create、inspect、rm、prune、connect
+- **故障排查** → 日志分析、退出码、资源问题
+
+### 2. 容器操作
+
+**运行新容器：**
+
+```bash
+# 后台服务，带端口映射
+docker run -d --name web -p 8080:80 nginx
+
+# 带环境变量
+docker run -d -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=mydb --name db postgres:16
+
+# 带持久化数据（命名卷）
+docker run -d -v pgdata:/var/lib/postgresql/data --name db postgres:16
+
+# 开发环境（绑定挂载源码）
+docker run -d -v $(pwd)/src:/app/src -p 3000:3000 --name dev my-app
+
+# 交互式调试（退出后自动删除）
+docker run -it --rm ubuntu:22.04 /bin/bash
+
+# 带资源限制和重启策略
+docker run -d --memory=512m --cpus=1.5 --restart=unless-stopped --name app my-app
+```
+
+关键参数：`-d` 后台运行，`-it` 交互式+tty，`--rm` 自动删除，`-p` 端口（宿主机:容器），`-e` 环境变量，`-v` 卷，`--name` 名称，`--restart` 重启策略。
+
+**管理运行中的容器：**
+
+```bash
+docker ps                        # 运行中的容器
+docker ps -a                     # 所有容器（包括已停止的）
+docker stop NAME                 # 优雅停止
+docker start NAME                # 启动已停止的容器
+docker restart NAME              # 停止并重启
+docker rm NAME                   # 删除已停止的容器
+docker rm -f NAME                # 强制删除运行中的容器
+docker container prune           # 删除所有已停止的容器
+```
+
+**与容器交互：**
+
+```bash
+docker exec -it NAME /bin/sh          # Shell 访问（如可用则使用 /bin/bash）
+docker exec NAME env                   # 查看环境变量
+docker exec -u root NAME apt update    # 以指定用户运行
+docker logs --tail 100 -f NAME         # 跟踪最后 100 行日志
+docker logs --since 2h NAME            # 最近 2 小时的日志
+docker cp NAME:/path/file ./local      # 从容器复制文件
+docker cp ./file NAME:/path/           # 向容器复制文件
+docker inspect NAME                    # 完整容器详情（JSON）
+docker stats --no-stream               # 资源使用快照
+docker top NAME                        # 运行中的进程
+```
+
+### 3. 镜像管理
+
+```bash
+# 构建
+docker build -t my-app:latest .
+docker build -t my-app:prod -f Dockerfile.prod .
+docker build --no-cache -t my-app .              # 全量重新构建
+DOCKER_BUILDKIT=1 docker build -t my-app .       # 使用 BuildKit 加速
+
+# 拉取与推送
+docker pull node:20-alpine
+docker login ghcr.io
+docker tag my-app:latest registry/my-app:v1.0
+docker push registry/my-app:v1.0
+
+# 检查
+docker images                          # 列出本地镜像
+docker history IMAGE                   # 查看层信息
+docker inspect IMAGE                   # 完整详情
+
+# 清理
+docker image prune                     # 删除悬空（未标记）镜像
+docker image prune -a                  # 删除所有未使用镜像（谨慎！）
+docker image prune -a --filter "until=168h"   # 删除 7 天前未使用的镜像
+```
+
+### 4. Docker Compose
+
+```bash
+# 启动/停止
+docker compose up -d                   # 后台启动所有服务
+docker compose up -d --build           # 启动前重新构建镜像
+docker compose down                    # 停止并删除容器
+docker compose down -v                 # 同时删除卷（会销毁数据）
+
+# 监控
+docker compose ps                      # 列出服务
+docker compose logs -f api             # 跟踪指定服务的日志
+docker compose logs --tail 50          # 所有服务最后 50 行日志
+
+# 交互
+docker compose exec api /bin/sh        # 进入运行中服务的 Shell
+docker compose run --rm api npm test   # 一次性命令（新容器）
+docker compose restart api             # 重启指定服务
+
+# 验证
+docker compose config                  # 验证并查看解析后的配置
+```
+
+**最简 compose.yml 示例：**
+
+```yaml
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgres://user:pass@db:5432/mydb
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: mydb
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+### 5. 卷与网络
+
+```bash
+# 卷
+docker volume ls                       # 列出卷
+docker volume create mydata            # 创建命名卷
+docker volume inspect mydata           # 详情（挂载点等）
+docker volume rm mydata                # 删除（使用中则失败）
+docker volume prune                    # 删除未使用的卷
+
+# 网络
+docker network ls                      # 列出网络
+docker network create mynet            # 创建桥接网络
+docker network inspect mynet           # 详情（已连接的容器）
+docker network connect mynet NAME      # 将容器连接到网络
+docker network disconnect mynet NAME   # 断开容器连接
+docker network rm mynet                # 删除网络
+docker network prune                   # 删除未使用的网络
+```
+
+### 6. 磁盘使用与清理
+
+清理前始终先进行诊断：
+
+```bash
+# 检查空间占用
+docker system df                       # 摘要
+docker system df -v                    # 详细分解
+
+# 针对性清理（安全）
+docker container prune                 # 已停止的容器
+docker image prune                     # 悬空镜像
+docker volume prune                    # 未使用的卷
+docker network prune                   # 未使用的网络
+
+# 激进清理（请先与用户确认！）
+docker system prune                    # 容器 + 镜像 + 网络
+docker system prune -a                 # 同时包含未使用镜像
+docker system prune -a --volumes       # 全部清除——包括命名卷
+```
+
+**警告：** 未经用户确认，切勿运行 `docker system prune -a --volumes`。此命令会删除可能包含重要数据的命名卷。
+
+## 常见问题
+
+| 问题 | 原因 | 解决方法 |
+|---------|-------|-----|
+| 容器立即退出 | 主进程结束或崩溃 | 检查 `docker logs NAME`，尝试 `docker run -it --entrypoint /bin/sh IMAGE` |
+| "port is already allocated" | 该端口已被其他进程占用 | 使用 `docker ps` 或 `lsof -i :PORT` 查找 |
+| "no space left on device" | Docker 磁盘已满 | 执行 `docker system df` 后针对性清理 |
+| 无法连接到容器 | 容器内应用绑定到 127.0.0.1 | 应用须绑定到 `0.0.0.0`，检查 `-p` 映射 |
+| 卷权限被拒绝 | 宿主机与容器 UID/GID 不匹配 | 使用 `--user $(id -u):$(id -g)` 或修复权限 |
+| Compose 服务间无法互通 | 网络错误或服务名称错误 | 服务使用服务名作为主机名，检查 `docker compose config` |
+| 构建缓存失效 | Dockerfile 层顺序错误 | 将不常变动的层放在前面（依赖在源码之前） |
+| 镜像过大 | 未使用多阶段构建，缺少 .dockerignore | 使用多阶段构建，添加 `.dockerignore` |
+
+## 验证
+
+每次 Docker 操作后，验证结果：
+
+- **容器已启动？** → `docker ps`（检查状态为 "Up"）
+- **日志无异常？** → `docker logs --tail 20 NAME`（无报错）
+- **端口可访问？** → `curl -s http://localhost:PORT` 或 `docker port NAME`
+- **镜像已构建？** → `docker images | grep TAG`
+- **Compose 栈健康？** → `docker compose ps`（所有服务状态为 "running" 或 "healthy"）
+- **磁盘已释放？** → `docker system df`（对比清理前后）
+
+## Dockerfile 优化建议
+
+审查或创建 Dockerfile 时，建议以下改进：
+
+1. **多阶段构建** — 将构建环境与运行时分离，减小最终镜像体积
+2. **层顺序** — 将依赖放在源码之前，避免变更使缓存层失效
+3. **合并 RUN 命令** — 减少层数，缩小镜像体积
+4. **使用 .dockerignore** — 排除 `node_modules`、`.git`、`__pycache__` 等
+5. **固定基础镜像版本** — 使用 `node:20-alpine` 而非 `node:latest`
+6. **以非 root 用户运行** — 添加 `USER` 指令以提升安全性
+7. **使用 slim/alpine 基础镜像** — 使用 `python:3.12-slim` 而非 `python:3.12`

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/devops/devops-inference-sh-cli.md

@@ -0,0 +1,173 @@
+---
+title: "Inference Sh Cli — 通过 inference 运行 150+ AI 应用"
+sidebar_label: "Inference Sh Cli"
+description: "通过 inference 运行 150+ AI 应用"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Inference Sh Cli
+
+通过 inference.sh CLI（infsh）运行 150+ AI 应用——图像生成、视频创作、LLM、搜索、3D、社交自动化。使用终端工具。触发词：inference.sh、infsh、ai apps、flux、veo、image generation、video generation、seedream、seedance、tavily
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选——使用 `hermes skills install official/devops/inference-sh-cli` 安装 |
+| 路径 | `optional-skills/devops/inference-sh-cli` |
+| 版本 | `1.0.0` |
+| 作者 | okaris |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `AI`, `image-generation`, `video`, `LLM`, `search`, `inference`, `FLUX`, `Veo`, `Claude` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在该 skill 被触发时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# inference.sh CLI
+
+通过简单的 CLI 在云端运行 150+ AI 应用。无需 GPU。
+
+所有命令均使用**终端工具**来运行 `infsh` 命令。
+
+## 使用场景
+
+- 用户要求生成图像（FLUX、Reve、Seedream、Grok、Gemini image）
+- 用户要求生成视频（Veo、Wan、Seedance、OmniHuman）
+- 用户询问 inference.sh 或 infsh
+- 用户希望运行 AI 应用而无需管理各个提供商的 API
+- 用户要求 AI 驱动的搜索（Tavily、Exa）
+- 用户需要生成头像/口型同步
+
+## 前置条件
+
+`infsh` CLI 必须已安装并完成认证。使用以下命令检查：
+
+```bash
+infsh me
+```
+
+如未安装：
+
+```bash
+curl -fsSL https://cli.inference.sh | sh
+infsh login
+```
+
+完整安装详情请参阅 `references/authentication.md`。
+
+## 工作流程
+
+### 1. 始终先搜索
+
+不要猜测应用名称——始终通过搜索找到正确的应用 ID：
+
+```bash
+infsh app list --search flux
+infsh app list --search video
+infsh app list --search image
+```
+
+### 2. 运行应用
+
+使用搜索结果中的精确应用 ID。始终使用 `--json` 获取机器可读的输出：
+
+```bash
+infsh app run <app-id> --input '{"prompt": "your prompt here"}' --json
+```
+
+### 3. 解析输出
+
+JSON 输出包含指向生成媒体的 URL。使用 `MEDIA:<url>` 格式将其呈现给用户以内联显示。
+
+## 常用命令
+
+### 图像生成
+
+```bash
+# 搜索图像应用
+infsh app list --search image
+
+# FLUX Dev with LoRA
+infsh app run falai/flux-dev-lora --input '{"prompt": "sunset over mountains", "num_images": 1}' --json
+
+# Gemini 图像生成
+infsh app run google/gemini-2-5-flash-image --input '{"prompt": "futuristic city", "num_images": 1}' --json
+
+# Seedream (ByteDance)
+infsh app run bytedance/seedream-5-lite --input '{"prompt": "nature scene"}' --json
+
+# Grok Imagine (xAI)
+infsh app run xai/grok-imagine-image --input '{"prompt": "abstract art"}' --json
+```
+
+### 视频生成
+
+```bash
+# 搜索视频应用
+infsh app list --search video
+
+# Veo 3.1 (Google)
+infsh app run google/veo-3-1-fast --input '{"prompt": "drone shot of coastline"}' --json
+
+# Seedance (ByteDance)
+infsh app run bytedance/seedance-1-5-pro --input '{"prompt": "dancing figure", "resolution": "1080p"}' --json
+
+# Wan 2.5
+infsh app run falai/wan-2-5 --input '{"prompt": "person walking through city"}' --json
+```
+
+### 本地文件上传
+
+CLI 会在提供路径时自动上传本地文件：
+
+```bash
+# 放大本地图像
+infsh app run falai/topaz-image-upscaler --input '{"image": "/path/to/photo.jpg", "upscale_factor": 2}' --json
+
+# 从本地文件生成图生视频
+infsh app run falai/wan-2-5-i2v --input '{"image": "/path/to/image.png", "prompt": "make it move"}' --json
+
+# 带音频的头像
+infsh app run bytedance/omnihuman-1-5 --input '{"audio": "/path/to/audio.mp3", "image": "/path/to/face.jpg"}' --json
+```
+
+### 搜索与研究
+
+```bash
+infsh app list --search search
+infsh app run tavily/tavily-search --input '{"query": "latest AI news"}' --json
+infsh app run exa/exa-search --input '{"query": "machine learning papers"}' --json
+```
+
+### 其他类别
+
+```bash
+# 3D 生成
+infsh app list --search 3d
+
+# 音频 / TTS
+infsh app list --search tts
+
+# Twitter/X 自动化
+infsh app list --search twitter
+```
+
+## 注意事项
+
+1. **不要猜测应用 ID**——始终先运行 `infsh app list --search <term>`。应用 ID 会变更，新应用也会频繁添加。
+2. **始终使用 `--json`**——原始输出难以解析。`--json` 标志提供包含 URL 的结构化输出。
+3. **检查认证状态**——如果命令因认证错误失败，请运行 `infsh login` 或确认 `INFSH_API_KEY` 已设置。
+4. **长时间运行的应用**——视频生成可能需要 30-120 秒。终端工具的超时时间应该足够，但请提前告知用户可能需要等待片刻。
+5. **输入格式**——`--input` 标志接受 JSON 字符串。请确保正确转义引号。
+
+## 参考文档
+
+- `references/authentication.md` — 安装、登录、API 密钥
+- `references/app-discovery.md` — 搜索和浏览应用目录
+- `references/running-apps.md` — 运行应用、输入格式、输出处理
+- `references/cli-reference.md` — 完整 CLI 命令参考