redskillhub-upload 1.0.0 → 1.0.2

package/README.md

@@ -1,100 +1,165 @@
-# SkillHub Upload CLI
+# redskillhub-upload
 
-Node.js CLI for uploading local Skills to 小红书 SkillHub.
+用于将本地 Skill 发布到小红书 SkillHub 的命令行工具。
 
-支持 macOS 和 Windows（PowerShell / cmd）。要求 Node.js 18 或更高版本；包含空格或中文的本地路径应使用双引号包裹。
+CLI 负责完整发布链路：登录授权、本地校验、重新打包、上传、参数确认和最终提交。输入可以是 Skill 目录，也可以是 `.zip` 文件。
 
-Install from the public npm registry:
+## 环境要求
+
+- Node.js 18 或更高版本
+- macOS
+- Windows（PowerShell / cmd）
+
+路径包含空格或中文时，请使用双引号包裹。
+
+## 安装
 
 ```bash
 npm install -g redskillhub-upload
 ```
 
-The CLI owns the executable flow: authorization, local packaging, upload, submit prompts, and final submit. `skill/SKILL.md` is a thin agent workflow that translates chat requests into CLI invocations.
+确认安装成功：
 
-Publish input can be a local Skill directory or a `.zip` file. User-provided zip archives are unpacked and validated as source containers; the zip uploaded to COS is always regenerated by this CLI after local validation.
+```bash
+redskillhub-upload whoami
+```
 
-## API Endpoints
+## 发布 Skill
 
-All paths and hosts are centralized in `cli/config.mjs` (`PATHS` + `DEFAULT_API_BASE` / `BETA_API_BASE`).
+发布本地目录：
 
-| Path Key | Path | Host | Description |
-|----------|------|------|-------------|
-| `UPLOAD_TOKEN` | `/api/sns/v2/red_skill/upload/permit` | `DEFAULT_API_BASE` | 获取上传授权（COS 临时凭证） |
-| `SUBMIT_SKILL_VERSION` | `/api/sns/v1/openapi/skillhub/submit_skill_version` | `DEFAULT_API_BASE` | 提交 skill 版本 |
-| `CREATE_CLI_OAUTH_DEVICE_CODE` | `/api/sns/v1/creator/red_skill/create_cli_oauth_device_code` | `DEFAULT_API_BASE` | 创建 CLI OAuth 设备码 |
-| `POLL_CLI_OAUTH_DEVICE_TOKEN` | `/api/sns/v1/creator/red_skill/poll_cli_oauth_device_token` | `DEFAULT_API_BASE` | 轮询 CLI OAuth 授权状态 |
-| `EXCHANGE_CLI_OAUTH_TOKEN` | `/api/sns/v1/creator/red_skill/exchange_cli_oauth_token` | `DEFAULT_API_BASE` / `BETA_API_BASE` | 通过 SkillHub 服务端换取 access_token |
-| `REFRESH_CLI_OAUTH_TOKEN` | `/api/sns/v1/creator/red_skill/refresh_cli_oauth_token` | `DEFAULT_API_BASE` / `BETA_API_BASE` | 通过 SkillHub 服务端续期 access_token |
+```bash
+redskillhub-upload publish "/absolute/path/to/skill"
+```
 
-- `DEFAULT_API_BASE` = `https://edith.xiaohongshu.com` — 生产业务接口
-- `BETA_API_BASE` = `https://edith.beta.xiaohongshu.com` — beta 业务接口
-- 所有命令都支持 `--env prod|beta`，默认 `prod`；`--env beta` 时业务接口使用 `BETA_API_BASE`
-- prod 沿用 `~/.skillhub-upload`，beta 使用 `~/.skillhub-upload/beta`，凭证、待授权、二维码、标签缓存和临时包相互隔离
-- 业务接口 host 可通过 `--api-base` 参数或 `SKILLHUB_UPLOAD_API_BASE` 环境变量覆盖
-- OAuth token 换取与刷新统一走 SkillHub 服务端 broker，CLI 不保存 appSecret
+发布 ZIP：
 
-## Auth Flow
+```bash
+redskillhub-upload publish "/absolute/path/to/skill.zip"
+```
+
+Agent 模式：
 
-`publish` 会自动保证登录可用，不需要先执行 `whoami` 或 `login`：
+```bash
+redskillhub-upload publish "/absolute/path/to/skill" --agent
+```
 
-1. access_token 有效：直接继续发布
-2. access_token 过期但 refresh_token 有效：自动调用 `refreshToken` 静默续期后继续发布
-3. 首次登录或 refresh_token 也过期：自动进入设备码 OAuth（`createCliOauthDeviceCode` → 用户授权 → `pollCliOauthDeviceToken` → `exchangeToken`），授权成功后原地继续发布
+`publish` 会自动检查登录状态，无需预先执行 `login` 或 `whoami`。
 
-`login` / `whoami` 仍保留用于手动登录和状态诊断。
+## 登录授权
 
-设备码响应中的 `authorize_common_url` 专用于生成二维码，`authorize_h5_url` 专用于返回可点击/复制的授权链接。登录时优先提示用户使用小红书 App 扫描二维码；只有无法扫码时，才引导用户使用手机自带浏览器打开 H5 链接。
+首次发布或登录凭证失效时，CLI 会自动进入扫码授权流程：
 
-## Local Dry Run
+1. 优先提示使用小红书 App 扫描二维码。
+2. 无法扫码时，使用手机自带浏览器打开授权链接。
+3. 授权成功后，当前发布流程会自动继续。
+
+CLI 会复用有效的 access token，并在 refresh token 可用时静默续期。token 换取和刷新统一由 SkillHub 服务端处理，CLI 不保存 appSecret，也不会在正常输出中展示 token 明文。
+
+手动登录：
 
 ```bash
-cd tools/redskillhub-upload
-npm install
-node cli/index.mjs publish test/fixtures/minimal-skill --dry-run --agent --source original --tag-id 101,102 --yes
+redskillhub-upload login
 ```
 
-Dry-run examples may use numeric tag IDs because the backend contract accepts `contentTagIds`. Multiple tags are comma-separated; `--tag` can also accept display names resolved from the live tag dictionary.
+Agent 模式登录：
 
-## Commands
+```bash
+redskillhub-upload login --agent
+```
+
+取消正在等待的登录：
+
+```bash
+redskillhub-upload login --cancel
+```
+
+查看登录状态：
 
 ```bash
-redskillhub-upload login --env prod
-redskillhub-upload login --agent --env prod
-redskillhub-upload login --cancel --env prod
-redskillhub-upload tags --env prod
-redskillhub-upload publish "/absolute/path/to/skill" --env prod
-redskillhub-upload publish "/absolute/path/to/skill" --agent --env prod
-redskillhub-upload publish "/absolute/path/to/skill.zip" --agent --env prod
-redskillhub-upload whoami --env prod
-redskillhub-upload logout --env prod
+redskillhub-upload whoami
 ```
 
-所有命令默认使用生产环境。验证 beta 环境时在命令末尾追加 `--env beta`，例如：
+退出登录：
 
 ```bash
-redskillhub-upload login --agent --env beta
-redskillhub-upload tags --env beta
-redskillhub-upload publish "/absolute/path/to/skill" --agent --env beta
-redskillhub-upload whoami --env beta
-redskillhub-upload logout --env beta
+redskillhub-upload logout
 ```
 
-Windows 路径示例：
+## 发布参数
+
+查看可用标签：
+
+```bash
+redskillhub-upload tags
+```
+
+指定原创内容和标签：
+
+```bash
+redskillhub-upload publish "/absolute/path/to/skill" --source original --tag "效率工具,内容创作"
+```
+
+转载内容需要提供来源：
+
+```bash
+redskillhub-upload publish "/absolute/path/to/skill" --source repost --repost-source "来源名称" --tag "内容创作"
+```
+
+只生成并检查待提交数据，不上传或提交：
+
+```bash
+redskillhub-upload publish "/absolute/path/to/skill" --dry-run --agent --source original --tag "效率工具"
+```
+
+真实发布前，CLI 会展示待提交信息并要求明确确认。未收到 `submit` 时不会执行最终提交。
+
+## Windows 示例
+
+PowerShell 和 cmd 中均使用双引号包裹路径：
+
+```powershell
+redskillhub-upload publish "C:\Users\name\path\to\skill" --agent
+```
+
+向 Agent 模式写入确认指令：
 
 ```powershell
-redskillhub-upload publish "C:\Users\name\path\to\skill" --agent --env prod
-node -e "process.stdout.write('submit\n')" | redskillhub-upload publish "C:\Users\name\path\to\skill" --agent --source original --tag "效率工具" --env prod
+node -e "process.stdout.write('submit\n')" | redskillhub-upload publish "C:\Users\name\path\to\skill" --agent --source original --tag "效率工具"
 ```
 
-## Agent Protocol
+## Agent 输出协议
+
+Agent 模式通过逐行结构化输出与调用方通信：
+
+- `PROMPT:<json>`：需要用户或 Agent 处理的交互信息。
+- `RESULT_JSON:<json>`：命令最终状态和结果。
+- `UPLOAD_PROGRESS:<number>`：上传进度。
+
+登录提示中的二维码图片路径位于 `PROMPT.qrCodePath`。Agent 应把该文件作为图片发送给用户，不能只展示本地路径。二维码无法使用时，再展示 `PROMPT.authorizeH5Url`。
+
+## 本地包校验
+
+CLI 会校验 Skill 目录或 ZIP 内容，并重新生成最终上传包：
 
-See `docs/protocol.md` for the line protocol:
+- 拒绝符号链接和越界路径。
+- 忽略系统元数据和隐藏文件。
+- 限制文件类型、单文件大小和总包大小。
+- 校验 `SKILL.md` 和必要的元数据。
+- 计算最终 ZIP 的大小与 SHA-256。
 
-- `PROMPT:<json>` requests user or agent input.
-- `RESULT_JSON:<json>` reports terminal command state.
-- `UPLOAD_PROGRESS:<number>` reports upload progress.
+用户提供的 ZIP 只作为输入容器，不会被原样上传。
 
-See `docs/design.md` for the full tool architecture, auth/upload flow, boundaries, and verification plan.
+## 本地开发
 
-Dry-run never calls external services. Real OAuth, COS upload, and submit adapters are wired; production use depends on the SkillHub OpenAPI endpoints being reachable and configured.
+```bash
+npm install
+npm test
+npm pack --dry-run
+```
+
+执行 dry-run：
+
+```bash
+node cli/index.mjs publish "/absolute/path/to/skill" --dry-run --agent --source original --tag-id 101,102 --yes
+```

package/cli/auth.mjs

@@ -427,15 +427,12 @@ export async function login({
     throw error;
   }
 
-  console.log(authorizationCode);
-  console.log(codeVerifier);
   const token = await exchangeToken({
     authorizationCode,
     codeVerifier,
     tokenUrl: `${apiBase}${PATHS.EXCHANGE_CLI_OAUTH_TOKEN}`,
     fetchImpl
   });
-  console.log(token);
   await writeCredentials(buildCredentialsFromToken(token, now(), 'OAS_TOKEN_EXCHANGE_INVALID_RESPONSE'), env, flags);
   await clearPendingAuth(env, flags);
   return maskCredentials(await readCredentials(env, flags));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redskillhub-upload",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "publishConfig": {
     "access": "public",