ossput 0.0.1

package/.cursor/skills/ossput/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: ossput
+description: >-
+  Uploads local files to Aliyun OSS via the ossput MCP server (presigned PUT),
+  lists objects and directory prefixes, and resolves multi-account profiles.
+  Use when the user mentions OSS, Aliyun upload, 阿里云, 图床, object storage,
+  ossput, or wants to put images/files on their bucket and get a public URL.
+---
+
+# ossput — 阿里云 OSS 直传
+
+## 前置条件
+
+1. 用户本机已安装 Node.js 18+。
+2. 终端已执行 `npx ossput setup`（注册 MCP，并将本 Skill 链接到 `~/.cursor/skills/ossput` 与 `~/.claude/skills/ossput`，**无需**复制到项目目录）。
+3. Cursor / Claude Desktop 的 `mcp.json` 已包含 **ossput**；凭证在 `~/.config/ossput/profiles/`，**禁止**在对话中向用户索要 AccessKey。
+
+未配置时：请用户在**终端**执行 `npx ossput setup`，然后重启 IDE / 新开 Agent 会话。可调用 `get_setup_status` 检查；用户本机可运行 `npx ossput doctor` 做完整诊断。
+
+## 选用哪个 profile
+
+解析顺序（高 → 低）：工具参数 `profile` → 环境变量 `OSSPUT_PROFILE` → 项目根 `.ossput.json` → 全局 `defaultProfile`。
+
+不确定时先调用 `list_profiles`，查看 `activeProfile` 与 `projectFile`。
+
+## 工具选用（默认路径）
+
+| 用户意图 | 工具 | 备注 |
+|----------|------|------|
+| 上传单个本地文件 | `upload_file` | 传 `localPath`；可选 `subdir` |
+| 上传多个本地文件 | `batch_upload_file` | `localPaths` 数组，单次最多 20 个 |
+| 看桶里有什么文件 | `list_objects` | 图片预览用 `format=markdown` |
+| 删除误传对象 | `delete_object` | **见下文「删除安全」**；默认关闭 |
+| 看有哪些目录前缀 | `list_directories` | 树形用 `format=markdown` |
+| 检查配置 / MCP | `get_setup_status` | |
+| 列出所有账号 | `list_profiles` | |
+| 高级：自管 PUT | `prepare_upload` → HTTP PUT → `confirm_upload` | 一般不必 |
+
+所有工具均可选 `profile` 覆盖当前项目绑定。
+
+## 对象路径规则（重要）
+
+最终 Key 形如：
+
+```text
+{profile.prefix}{subdir}{YYYY}/{MM}/{uuid}.{ext}
+```
+
+- `prefix`：profile 里配置的对象前缀，`/` 表示 Bucket 根目录。
+- `subdir`：上传/列表时传入的子目录，如 `ossput_test` → 实际为 `ossput_test/`。
+- 文件名默认 **UUID**，不是原文件名；会在 `subdir` 下再按 **UTC 年/月** 分子目录。
+
+向用户说明 URL 时，以工具返回的 `objectUrl` / `objectKey` 为准。
+
+## 安全与限制
+
+- 勿上传：`.env`、密钥文件、含 `credentials`/`secret` 等敏感路径（工具会拒绝）。
+- 单文件 ≤ **100MB**；仅支持单次 Presigned PUT（无分片）。
+- 使用 RAM 子账号，权限收窄到目标 Bucket 与前缀。
+
+## 删除安全（delete_object）
+
+删除为**破坏性操作**，须同时满足：
+
+1. Profile 中 **`allowDelete: true`**（默认 `false`，在 `~/.config/ossput/profiles/<name>.json` 手动开启）。
+2. 工具参数 **`confirm: true`** — 仅在用户**明确确认**要删该 `objectKey` 后传入。
+3. **`objectKey` 必须完整且准确** — 优先从 `list_objects` 或上传返回值复制，不要猜路径。
+4. **Key  scoped 到 profile 的 `prefix`** — 不能删除前缀外的对象；若 `prefix` 为桶根，还须至少 `子目录/文件名` 两段路径。
+
+**Agent 流程：** `list_objects` 展示 Key → 向用户确认 → 再 `delete_object`。若 `allowDelete` 为 false，提示用户在终端编辑 profile 开启（勿在对话中要 AK）。
+
+RAM 策略仅授予 `DeleteObject` 到必要前缀，与 `PutObject` 同级收窄。
+
+## 常见问题
+
+| 现象 | 处理 |
+|------|------|
+| MCP 工具不可用 | 用户执行 `npx ossput status`；重启 IDE；确认 `mcp.json` 指向有效 `dist/index.js` |
+| `not configured` | 终端 `npx ossput setup` |
+| 路径与预期不符 | 见上文「对象路径规则」；`list_objects` 用相同 `subdir` 查询 |
+| 多账号 | `profile add` / `profile use`；或工具传 `profile` |
+
+## 更多说明
+
+- 配置结构、CLI 命令：见仓库 [README.md](../../../README.md)
+- 工具参数：见 [reference.md](reference.md)
+- 对话示例与反模式：见 [examples.md](examples.md)

package/.cursor/skills/ossput/examples.md

@@ -0,0 +1,59 @@
+# ossput 示例对话
+
+## 1. 上传本地截图到 `ossput_test`
+
+**用户**：把这张截图传到 OSS 的 ossput_test 目录。
+
+**Agent 步骤**：
+
+1. `get_setup_status` — 确认 `configured: true`
+2. `upload_file` — `localPath=/Users/me/Desktop/shot.png`，`subdir=ossput_test`
+3. 回复用户工具返回的 `objectUrl`（Key 形如 `ossput_test/2026/05/<uuid>.png`）
+
+---
+
+## 2. 浏览已上传图片
+
+**用户**：看看 ossput_test 里有哪些图。
+
+**Agent**：`list_objects`，`subdir=ossput_test`，`format=markdown`，`imagesOnly=true`
+
+将返回的 Markdown（含图片预览）直接展示给用户。
+
+---
+
+## 3. 多账号项目
+
+**用户**：这个项目要用客户 A 的桶上传。
+
+**Agent**：
+
+1. `list_profiles` — 看是否有 `client-a`
+2. `upload_file` — `profile=client-a`，`localPath=...`，`subdir=deliverables/`
+
+若项目根有 `.ossput.json` 且已绑定 `client-a`，可省略 `profile` 参数。
+
+---
+
+## 4. 删除误传文件（需开启 allowDelete）
+
+**用户**：删掉刚才传错的那张图。
+
+**Agent**：
+
+1. `get_setup_status` — 确认 `allowDelete: true`，否则请用户在 profile JSON 中开启
+2. `list_objects` — 找到目标 `objectKey`，**向用户展示并确认**
+3. `delete_object` — `objectKey=...`，`confirm=true`（仅用户同意后）
+
+---
+
+## 反模式
+
+| 不要 | 原因 |
+|------|------|
+| 在对话里要 AccessKey | 应让用户终端执行 `npx ossput setup` |
+| 用 `prepare_upload` 做普通上传 | 优先 `upload_file` |
+| 上传后 list 用不同 `subdir` | 会与上传路径不一致，列不出文件 |
+| 假设 URL 含原文件名 | 默认为 UUID 文件名 |
+| 未确认就 `delete_object` | 必须先展示 objectKey 并取得用户同意，且 `confirm: true` |
+| 未开 `allowDelete` 仍尝试删除 | 提示编辑 profile，不要反复调用 |

package/.cursor/skills/ossput/reference.md

@@ -0,0 +1,78 @@
+# ossput 参考
+
+## 配置文件
+
+| 路径 | 内容 |
+|------|------|
+| `~/.config/ossput/config.json` | 索引：`defaultProfile`、`profiles` 列表（无密钥） |
+| `~/.config/ossput/profiles/{name}.json` | 单账号：region、bucket、prefix、AK（`chmod 600`）；可选 `publicBaseUrl`、`allowDelete`（默认 false） |
+| `{repo}/.ossput.json` | `{ "profile": "default" }`，可提交 Git |
+
+## MCP 工具参数摘要
+
+### upload_file
+
+- `localPath`（必填）：本机绝对或相对路径
+- `subdir`（可选）：逻辑子目录，如 `demo/`、`ossput_test`
+- `contentType`（可选）：不传则按扩展名推断
+- `profile`（可选）
+
+返回 JSON：`objectKey`、`objectUrl`、`size`、`exists` 等。
+
+### batch_upload_file
+
+- `localPaths`（必填）：本机路径数组，**最多 20 个**
+- `subdir`、`contentType`、`profile`（可选）
+- `stopOnError`（可选）：`true` 时遇错停止，默认继续其余文件
+
+返回：`succeeded` / `failed` 计数及每个文件的 `ok` + `result` 或 `error`。
+
+### delete_object
+
+- `objectKey`（必填）：完整对象 Key
+- `confirm`（必填）：**必须为 `true`**（表示用户已确认）
+- `profile`（可选）
+
+前置：profile 中 `allowDelete: true`。Key 须落在 profile `prefix` 下。删除前会 `head` 确认对象存在。
+
+### list_objects
+
+- `subdir`：列出该前缀下对象
+- `format`: `json` | `markdown`（图片预览用 markdown）
+- `imagesOnly`: `true` 仅图片
+- `maxKeys`：默认 100，最大 1000
+- `previewMax`：markdown 模式下最多预览张数
+
+### list_directories
+
+- `subdir`：从该前缀下列「子目录」
+- `format`: `json` | `markdown`
+
+### prepare_upload / confirm_upload
+
+用于自定义上传流程；`overwrite: true` 时保留原文件名（仍带年月目录）。常规场景用 `upload_file` 即可。
+
+## CLI（用户在终端执行）
+
+```bash
+npx ossput setup
+npx ossput profile list|add|show|use|default|rm
+npx ossput status
+npx ossput put <file> [file2 …] [--subdir name] [--stop-on-error]
+npx ossput rm <objectKey> --confirm
+npx ossput ls [subdir] [--markdown] [--images]
+npx ossput dirs [subdir] [--markdown]
+npx ossput --profile <name> <command>
+```
+
+## 示例对话流
+
+**上传一张本地图到 `ossput_test`：**
+
+1. `get_setup_status` 或 `list_profiles` 确认已配置
+2. `upload_file`：`localPath=/path/to/photo.jpg`，`subdir=ossput_test`
+3. 把返回的 `objectUrl` 给用户
+
+**浏览已上传图片：**
+
+`list_objects`：`subdir=ossput_test`，`format=markdown`，`imagesOnly=true`

package/.ossput.json.example

@@ -0,0 +1,3 @@
+{
+  "profile": "default"
+}

package/AGENTS.md

@@ -0,0 +1,16 @@
+# Agent 说明（ossput）
+
+本仓库提供 **ossput**：阿里云 OSS Presigned 直传的 MCP 服务 + CLI。
+
+## 上传到 OSS 时
+
+1. 确认 **ossput** MCP 已连接；未配置则让用户在终端运行 `npx ossput setup`（**不要**在对话里要 AccessKey）。`setup` 会把 Skill 装到 `~/.cursor/skills/ossput`（无需复制到项目目录）。
+2. 遵循用户级 Skill（`~/.cursor/skills/ossput/SKILL.md`，或本仓库开发版 [.cursor/skills/ossput/SKILL.md](.cursor/skills/ossput/SKILL.md)）：
+   - 优先 `upload_file`
+   - 先 `list_profiles` / 读 `.ossput.json` 确定 profile
+   - 注意 `subdir` 下会自动加 `年/月/UUID` 路径
+
+## 文档
+
+- 人类用户：[README.md](README.md)
+- Agent 细则：`.cursor/skills/ossput/SKILL.md`、`reference.md`

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## Unreleased
+
+## 0.0.1
+
+### Added
+
+- MCP：`upload_file`、`batch_upload_file`、`delete_object`、`list_objects`、`list_directories`、`list_profiles`、`get_setup_status`、`prepare_upload`、`confirm_upload`
+- CLI：`setup`、`status`、`put`（多文件）、`rm --confirm`、`ls`、`dirs`、`profile`、`doctor`、`skill install`
+- 多账号：`~/.config/ossput/profiles/` + 项目 `.ossput.json`；环境变量 `OSSPUT_PROFILE`、`OSSPUT_MCP`
+- Setup 向导：MCP 注册（Cursor / Claude Code）、连通性检测、可选 `publicBaseUrl` / `allowDelete`
+- Agent Skill：`.cursor/skills/ossput/`；`setup` 自动安装到用户目录（符号链接）
+- `docs/ram-policy.example.json`：RAM 最小权限策略示例
+- CI：Ubuntu（Node 18/20/22）+ Windows 冒烟
+
+### Changed
+
+- 上传使用 Node 内置 `fetch`（Node 18+），不依赖系统 `curl`
+- MCP 工具 `annotations`；失败返回 `isError` 与可执行提示
+
+### Notes
+
+- 上传对象 Key：`{prefix}{subdir}{YYYY}/{MM}/{uuid}.{ext}`
+- 单文件上限 100MB；删除需在 profile 开启 `allowDelete` 且 MCP/CLI 显式确认

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ossput contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# ossput
+
+[![CI](https://github.com/devoink/ossput/actions/workflows/ci.yml/badge.svg)](https://github.com/devoink/ossput/actions/workflows/ci.yml)
+
+Aliyun OSS direct upload for AI agents — MCP server + CLI. Presigned PUT via Node `fetch` (Node 18+). **Credentials live in `~/.config/ossput/profiles/`**, not in `mcp.json`.
+
+## Quick start
+
+```bash
+npx -y ossput setup
+```
+
+向导会：创建第一个 **profile**（账号）→ 检测连通性 → 注册 MCP → 可选写入项目 `.ossput.json`。
+
+完成后 **重启 IDE**，确认 **ossput** MCP 已连接。
+
+```bash
+ossput put ./photo.png --subdir demo/2026-05
+```
+
+## AI Agent：MCP 与 Skill
+
+| 能力 | 作用 | 如何启用 |
+|------|------|----------|
+| **MCP** | `upload_file` 等工具 | `npx ossput setup` 注册到 Cursor / Claude Desktop，重启 IDE |
+| **Skill** | 教 Agent 何时用 MCP、路径规则 | **`setup` 会自动安装到本机用户目录**（无需复制到项目） |
+
+```bash
+npx ossput setup              # OSS 配置 + MCP + Skill（用户级）
+npx ossput skill install      # 仅重装 Skill（升级 npm 包后可选）
+npx ossput setup --skip-skill # 不要安装 Skill
+```
+
+安装位置（符号链接指向 npm 包内 Skill，升级包后链接仍有效）：
+
+- Cursor：`~/.cursor/skills/ossput/`
+- Claude Code：`~/.claude/skills/ossput/`（可用 `/ossput` 调用）
+
+**不需要**把 `SKILL.md` 复制进每个项目的 `.cursor/skills/`。仓库内的 `.cursor/skills/ossput/` 仅用于开发与 npm 打包。
+
+Agent 细则见 [AGENTS.md](./AGENTS.md)。
+
+### Claude Code 的 MCP
+
+`ossput setup` 可将 MCP 写入 **`~/.claude.json`**（与 Cursor 的 `~/.cursor/mcp.json` 并列）。向导中勾选 **Claude Code** 即可；也可事后重新运行 `npx ossput setup` 仅注册 MCP。
+
+若未自动注册，可手动在 `~/.claude.json` 的 `mcpServers` 中加入与 Cursor 相同的 `node` + `dist/index.js` 条目。
+
+### Agent 须知（摘要）
+
+- 未配置 → 终端 `npx ossput setup`，**勿在对话中索要 AccessKey**
+- 上传 → MCP `upload_file`；看图 → `list_objects`（`format=markdown`）
+- 对象 Key：`{prefix}{subdir}{年}/{月}/{uuid}.ext`
+
+## 多账号 / 多项目
+
+| 文件 | 说明 |
+|------|------|
+| `~/.config/ossput/config.json` | 索引：`defaultProfile` + profile 列表（无密钥） |
+| `~/.config/ossput/profiles/{name}.json` | 单账号 OSS 配置（chmod 600） |
+| `{repo}/.ossput.json` | 项目绑定：`{ "profile": "default" }`（可提交 Git） |
+
+**解析优先级：** CLI/MCP 的 `profile` 参数 → `OSSPUT_PROFILE` → 项目 `.ossput.json` → 全局 `defaultProfile`
+
+```bash
+ossput profile add client-a      # 新增账号
+ossput profile list              # 列出账号
+ossput profile use default       # 当前目录写 .ossput.json
+ossput --profile client-a put ./x.zip
+```
+
+示例见 [config.index.example.json](./config.index.example.json)、[profiles.example/default.json](./profiles.example/default.json)、[.ossput.json.example](./.ossput.json.example)。
+
+## MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `upload_file` | Upload local file |
+| `batch_upload_file` | Batch upload (max 20 files per call) |
+| `delete_object` | Delete one object (`allowDelete` + `confirm: true`) |
+| `list_objects` | List files (`format=markdown` for image previews) |
+| `list_directories` | List folder prefixes |
+| `list_profiles` | List profiles + active profile in cwd |
+| `get_setup_status` | Config + MCP registration |
+| `prepare_upload` / `confirm_upload` | Advanced presign flow |
+
+All tools accept optional `profile` to override `.ossput.json`.
+
+## MCP configuration (manual)
+
+```json
+{
+  "mcpServers": {
+    "ossput": {
+      "command": "node",
+      "args": ["/absolute/path/to/ossput/dist/index.js"]
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+ossput setup
+ossput profile list|add|show|use|default|rm
+ossput status
+ossput doctor
+ossput put <file> [file2 …] [--subdir x] [--stop-on-error]
+ossput rm <objectKey> --confirm
+ossput ls [subdir] [--markdown] [--images]
+ossput dirs [subdir] [--markdown]
+ossput --profile <name> <command>
+```
+
+## Security
+
+- Use RAM users scoped to bucket prefix (`PutObject` / `HeadObject`).
+- Do not paste AccessKeys into chat; use `setup` / `profile add` in terminal.
+- Commit `.ossput.json` only; never commit `profiles/*.json`.
+- **Delete:** off by default; set `allowDelete: true` in profile only when needed. MCP requires `confirm: true` and `objectKey` under profile `prefix`. CLI: `ossput rm <key> --confirm`. RAM 示例见 [docs/ram-policy.example.json](./docs/ram-policy.example.json).
+
+## Limits
+
+- Single file ≤ 100MB
+- Presigned single PUT only (v1)
+- Requires **Node.js 18+**（内置 `fetch`，无需安装 curl）
+- CDN / 自定义域名：在 profile JSON 设置 `publicBaseUrl`（如 `https://cdn.example.com`）
+
+## Windows
+
+在 Windows 上路径通过 `%USERPROFILE%`（`os.homedir()`）解析，与 macOS/Linux 使用同一套逻辑，**未在 Windows CI 中完整验证**，以下为典型位置：
+
+| 用途 | 典型路径 |
+|------|----------|
+| OSS 配置 | `%USERPROFILE%\.config\ossput\` |
+| Cursor MCP | `%USERPROFILE%\.cursor\mcp.json` |
+| Claude Desktop MCP | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor Skill | `%USERPROFILE%\.cursor\skills\ossput\` |
+| Claude Code Skill | `%USERPROFILE%\.claude\skills\ossput\` |
+
+说明：
+
+- `.cursor`、`.config` 为隐藏文件夹，可在资源管理器中开启「隐藏的项目」，或在地址栏输入 `%USERPROFILE%\.cursor`。
+- Skill 安装优先创建 **junction**；失败时自动 **复制** 到上述目录（升级 npm 后若用复制方式，需再执行 `ossput skill install`）。
+- `chmod 600` 在 Windows 上权限语义较弱，请勿依赖其做访问控制；仍请勿将 `profiles/*.json` 提交到 Git。
+- 上传失败：运行 `ossput doctor`，确认 Node ≥18 且 Bucket 连通；检查 RAM 是否具备 `PutObject` 权限。
+
+## 对象路径说明
+
+`ossput put ./a.png --subdir ossput_test` 实际上传 Key 类似：
+
+```text
+ossput_test/2026/05/<uuid>.png
+```
+
+（另加 profile 配置的 `prefix`。）列表与上传使用相同 `subdir` 才能对齐。
+
+## Local development
+
+```bash
+cd ossput
+npm ci && npm run build
+node dist/index.js setup
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT

package/config.index.example.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "defaultProfile": "default",
+  "profiles": {
+    "default": { "label": "默认账号" },
+    "client-a": { "label": "客户 A 交付桶" }
+  }
+}

package/dist/batch-upload.d.ts

@@ -0,0 +1,28 @@
+import type { AppConfig } from "./types.js";
+import type { UploadFileResult } from "./types.js";
+export declare const MAX_BATCH_FILES = 20;
+export interface BatchUploadItemSuccess {
+    localPath: string;
+    ok: true;
+    result: UploadFileResult;
+}
+export interface BatchUploadItemFailure {
+    localPath: string;
+    ok: false;
+    error: string;
+}
+export type BatchUploadItemResult = BatchUploadItemSuccess | BatchUploadItemFailure;
+export interface BatchUploadResult {
+    subdir: string;
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: BatchUploadItemResult[];
+}
+export interface BatchUploadOptions {
+    subdir?: string;
+    contentType?: string;
+    /** 遇错即停；默认 false，继续上传其余文件 */
+    stopOnError?: boolean;
+}
+export declare function batchUploadFile(config: AppConfig, localPaths: string[], options?: BatchUploadOptions): Promise<BatchUploadResult>;

package/dist/batch-upload.js

@@ -0,0 +1,34 @@
+import { uploadFile } from "./upload-pipeline.js";
+import { validateSubdir } from "./validators.js";
+export const MAX_BATCH_FILES = 20;
+export async function batchUploadFile(config, localPaths, options = {}) {
+    if (localPaths.length === 0) {
+        throw new Error("localPaths cannot be empty");
+    }
+    if (localPaths.length > MAX_BATCH_FILES) {
+        throw new Error(`at most ${MAX_BATCH_FILES} files per batch (got ${localPaths.length})`);
+    }
+    const normalizedSubdir = validateSubdir(options.subdir);
+    const results = [];
+    for (const localPath of localPaths) {
+        try {
+            const result = await uploadFile(config, localPath, normalizedSubdir || undefined, options.contentType);
+            results.push({ localPath, ok: true, result });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            results.push({ localPath, ok: false, error });
+            if (options.stopOnError) {
+                break;
+            }
+        }
+    }
+    const succeeded = results.filter((r) => r.ok).length;
+    return {
+        subdir: normalizedSubdir,
+        total: localPaths.length,
+        succeeded,
+        failed: results.length - succeeded,
+        results,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<number>;