115ctln

115 网盘 CLI 工具 + pi agent 插件 — 基于 115pan-node 的 TypeScript 实现

115ctl 的 Node.js 重构版，使用 115pan-node SDK (v0.0.2)，提供完整的 115 云盘文件管理和 pi agent 深度集成。

🚨 风险警告 — 115 网盘风控须知

115 网盘对 API 请求频率极其敏感，错误的操作方式会导致账号被风控甚至封禁。 AI Agent 使用本工具时必须遵守以下规则。

核心原则

| 原则 | 说明 | |:-----|:------| | 🔴 单线程串行 | 所有写操作必须串行执行，禁止并发。多线程 rename 会导致文件系统损坏（见 Issue #1） | | ⏱ 操作间隔 | 每个写操作间至少间隔 3 秒。批量操作时每 10-15 个操作暂停 30 秒 | | 🐢 宁慢勿快 | 115 没有提供官方 API，所有接口均属逆向。宁可操作慢，不可被封控 | | 📋 先预览再执行 | 批量操作前先用 ls/stat/find 确认目标，减少无效请求 |

禁止行为

❌ ThreadPoolExecutor + 并发 rename      → 文件变空目录，不可恢复
❌ 每秒超过 3 次 API 请求                 → 触发 429 风控
❌ 短时间内大量删除/移动操作              → 账号临时限制
❌ 忽略 429 错误继续请求                  → 冷却期延长甚至封禁

推荐做法

# ✅ 串行 rename
115ctln rename /path/file1 new_name1
sleep 3
115ctln rename /path/file2 new_name2

# ✅ 小批量删除，间隔执行
115ctln rm /path/file1
sleep 3
115ctln rm /path/file2

# ✅ 操作前先用 --dry-run 风格预览（ls/stat）
115ctln ls /path --json          # 先看有什么
115ctln stat /path/file --json   # 再看是不是要操作的

环境变量调优

| 变量 | 说明 | 默认 | |:-----|:------|:-----| | _115CTLN_WRITE_DELAY | 写操作间隔（毫秒） | 3000 | | DEBUG 或 NODE_ENV=debug | 显示完整错误调用栈（调试用） | 关闭 |

🎯 设计目标

| 维度 | 说明 | |:-----|:------| | 替代 115ctl | 使用 115pan-node 替代 115driver，从 Go 迁移到 TypeScript | | Pi Agent 原生集成 | 同时提供 CLI 和 pi extension 两种入口 | | 渐进兼容 | CLI 命令和参数尽可能与 115ctl 保持一致 |

🏗 架构

115ctln/
├── src/
│   ├── index.ts          ← pi extension 入口（注册11个自定义工具）
│   ├── cli.ts            ← CLI 入口（commander）
│   ├── client.ts         ← CloudClient — 115pan-node 封装层
│   ├── config.ts         ← 配置加载（兼容 media115/config.toml）
│   ├── util.ts           ← 工具函数（解析器、分类器）
│   ├── types.ts          ← 共享类型定义
│   ├── commands/         ← CLI 命令实现（与工具共享逻辑）
│   │   ├── ls.ts, stat.ts, mv.ts, rename.ts, rm.ts, mkdir.ts
│   │   ├── find.ts, tree.ts, scan.ts, doctor.ts, auth.ts
│   │   └── link.ts, share.ts
│   └── tools/            ← (预留) 纯 tool 实现
├── SKILL.md              ← pi agent skill 描述
├── USAGE.md              ← 使用规范
└── package.json

两种使用方式

CLI                           Pi Extension
───────                       ─────────────
node dist/cli.js ls /JAV      LLM 调用 list_files
node dist/cli.js mv a b       LLM 调用 move_file
node dist/cli.js scan /JAV    LLM 调用 scan_videos

🚀 安装

# 1. 克隆
git clone http://192.168.2.222:13050/yxin/115ctln.git
cd 115ctln

# 2. 安装依赖
npm install

# 3. 构建
npm run build

# 4. 全局安装（可选）
npm link

⚡ 快速开始

# 配置 cookies
export 115_COOKIES="UID=...; CID=...; SEID=..."

# 检查连接
115ctln doctor --json

# 列出目录
115ctln ls /JAV --json

# 移动文件
115ctln mv /src/file.mp4 /dst/

🔌 Pi Extension 集成

在 ~/.pi/settings.json 中添加：

{
  "packages": ["/path/to/115ctln"]
}

重启 pi 后，LLM 自动获得 11 个自定义工具（list_files、stat_file、move_file 等）。

📋 功能对照

| 功能 | 115ctl (Go) | 115ctln (TS) | |:-----|:-----------:|:------------:| | ls / ls -R | ✅ | ✅ | | stat / stat --by-id | ✅ | ✅ | | mv / mv --by-id | ✅ | ✅ | | rename / rename --by-id | ✅ | ✅ | | rm / rm --by-id | ✅ | ✅ | | mkdir | ✅ | ✅ | | find | ✅ | ✅ | | tree | ✅ | ✅ | | scan / scan -R | ✅ | ✅ | | doctor | ✅ | ✅ | | auth qr | ✅ | ✅ | | link | ⏳ (需 OpenList) | ✅ (115原生) | | share | ✅ (需 OpenList) | ⏳ | | upload | ✅ (需 OpenList) | ⏳ | | sync (缓存) | ✅ | ⏳ | | batch-rename | ✅ | ⏳ | | Pi extension 工具 | ❌ | ✅ |

📄 License

MIT