@jackwener/opencli 1.7.22 → 1.8.1

package/clis/douyin/_shared/vod-upload.js

@@ -0,0 +1,212 @@
+import * as crypto from 'node:crypto';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { unwrapEvaluateResult } from './evaluate-result.js';
+
+const AUTH_V5_URL = 'https://creator.douyin.com/web/api/media/upload/auth/v5/';
+const VOD_UPLOAD_HOST = 'https://vod.bytedanceapi.com/';
+const VOD_SPACE_NAME = 'aweme';
+
+function hmacSha256(key, data) {
+  return crypto.createHmac('sha256', key).update(data, 'utf8').digest();
+}
+
+function sha256Hex(data) {
+  const hash = crypto.createHash('sha256');
+  if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
+    hash.update(data);
+  } else {
+    hash.update(data ?? '', 'utf8');
+  }
+  return hash.digest('hex');
+}
+
+function nowDatetime() {
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+function canonicalQuery(url) {
+  return [...url.searchParams.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join('&');
+}
+
+function computeAws4Headers(url, credentials, options = {}) {
+  const parsedUrl = new URL(url);
+  const datetime = nowDatetime();
+  const date = datetime.slice(0, 8);
+  const method = options.method ?? 'GET';
+  const body = options.body ?? '';
+  const bodyHash = sha256Hex(body);
+  const headers = {
+    ...(options.headers ?? {}),
+    host: parsedUrl.host,
+    'x-amz-content-sha256': bodyHash,
+    'x-amz-date': datetime,
+    'x-amz-security-token': credentials.session_token,
+  };
+  const sortedHeaderKeys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
+  const canonicalHeaders = sortedHeaderKeys
+    .map((key) => `${key}:${String(headers[key]).trim()}`)
+    .join('\n') + '\n';
+  const signedHeaders = sortedHeaderKeys.join(';');
+  const canonicalRequest = [
+    method,
+    parsedUrl.pathname || '/',
+    canonicalQuery(parsedUrl),
+    canonicalHeaders,
+    signedHeaders,
+    bodyHash,
+  ].join('\n');
+  const service = 'vod';
+  const region = 'cn-north-1';
+  const credentialScope = `${date}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    'AWS4-HMAC-SHA256',
+    datetime,
+    credentialScope,
+    sha256Hex(canonicalRequest),
+  ].join('\n');
+  const kDate = hmacSha256(`AWS4${credentials.secret_access_key}`, date);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, service);
+  const kSigning = hmacSha256(kService, 'aws4_request');
+  const signature = hmacSha256(kSigning, stringToSign).toString('hex');
+  return {
+    ...headers,
+    Authorization: `AWS4-HMAC-SHA256 Credential=${credentials.access_key_id}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  };
+}
+
+function extractUserIdFromSessionToken(sessionToken) {
+  try {
+    const raw = sessionToken.startsWith('STS2') ? sessionToken.slice(4) : sessionToken;
+    const decoded = JSON.parse(Buffer.from(raw, 'base64').toString('utf8'));
+    const policy = JSON.parse(decoded.PolicyString || '{}');
+    const condition = policy?.Statement?.[0]?.Condition;
+    if (typeof condition === 'string') {
+      const parsedCondition = JSON.parse(condition);
+      return parsedCondition.UserId || '';
+    }
+  } catch {
+    return '';
+  }
+  return '';
+}
+
+export async function getUploadAuthV5Credentials(page) {
+  const result = unwrapEvaluateResult(await page.evaluate(`fetch(${JSON.stringify(AUTH_V5_URL)}, { credentials: 'include' }).then(r => r.json())`));
+  if (!result || Array.isArray(result) || typeof result !== 'object') {
+    throw new CommandExecutionError(`获取抖音上传授权失败: ${JSON.stringify(result)}`);
+  }
+  if (result.status_code !== 0) {
+    const message = result.status_msg ?? result.message ?? 'unknown error';
+    if (result.status_code === 401 || result.status_code === 403 || /login|cookie|auth|captcha|verify|forbidden|permission|登录|登陆|权限|验证|验证码/i.test(String(message))) {
+      throw new AuthRequiredError('creator.douyin.com', `获取抖音上传授权失败: ${message}`);
+    }
+    throw new CommandExecutionError(`获取抖音上传授权失败: ${JSON.stringify(result)}`);
+  }
+  if (!result.auth) {
+    throw new CommandExecutionError(`获取抖音上传授权失败: ${JSON.stringify(result)}`);
+  }
+  let auth;
+  try {
+    auth = JSON.parse(result.auth);
+  } catch (error) {
+    throw new CommandExecutionError(`解析抖音上传授权失败: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!auth.AccessKeyID || !auth.SecretAccessKey || !auth.SessionToken) {
+    throw new CommandExecutionError('抖音上传授权缺少 AccessKeyID/SecretAccessKey/SessionToken');
+  }
+  return {
+    access_key_id: auth.AccessKeyID,
+    secret_access_key: auth.SecretAccessKey,
+    session_token: auth.SessionToken,
+    user_id: extractUserIdFromSessionToken(auth.SessionToken),
+    expired_time: auth.ExpiredTime,
+    current_time: auth.CurrentTime,
+  };
+}
+
+export async function applyVideoUploadInner(fileSize, credentials) {
+  const params = new URLSearchParams({
+    Action: 'ApplyUploadInner',
+    Version: '2020-11-19',
+    SpaceName: VOD_SPACE_NAME,
+    FileType: 'video',
+    IsInner: '1',
+    FileSize: String(fileSize),
+  });
+  const url = `${VOD_UPLOAD_HOST}?${params.toString()}`;
+  const res = await fetch(url, { headers: computeAws4Headers(url, credentials), signal: AbortSignal.timeout(30000) });
+  const text = await res.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new CommandExecutionError(`申请抖音上传地址失败，非 JSON 响应: HTTP ${res.status} ${text.slice(0, 300)}`);
+  }
+  const error = payload?.ResponseMetadata?.Error;
+  if (!res.ok || error) {
+    throw new CommandExecutionError(`申请抖音上传地址失败: HTTP ${res.status} ${JSON.stringify(error ?? payload)}`);
+  }
+  const uploadNode = payload?.Result?.InnerUploadAddress?.UploadNodes?.[0];
+  const storeInfo = uploadNode?.StoreInfos?.[0];
+  const videoId = payload?.Result?.Vid || uploadNode?.Vid;
+  const sessionKey = uploadNode?.SessionKey ?? storeInfo?.SessionKey ?? payload?.Result?.SessionKey;
+  if (!uploadNode?.UploadHost || !storeInfo?.StoreUri || !storeInfo?.Auth || !videoId || !sessionKey) {
+    throw new CommandExecutionError(`申请抖音上传地址响应缺少必要字段: ${JSON.stringify(payload).slice(0, 500)}`);
+  }
+  return {
+    video_id: videoId,
+    tos_upload_url: `https://${uploadNode.UploadHost}/${storeInfo.StoreUri}`,
+    auth: storeInfo.Auth,
+    session_key: sessionKey,
+    upload_header: uploadNode.UploadHeader ?? {},
+    user_id: credentials.user_id ?? '',
+  };
+}
+
+
+export async function commitVideoUploadInner(uploadInfo, credentials) {
+  if (!uploadInfo?.session_key) {
+    throw new CommandExecutionError('抖音上传提交缺少 SessionKey');
+  }
+  const params = new URLSearchParams({
+    Action: 'CommitUploadInner',
+    Version: '2020-11-19',
+    SpaceName: VOD_SPACE_NAME,
+  });
+  const url = `${VOD_UPLOAD_HOST}?${params.toString()}`;
+  const body = JSON.stringify({ SessionKey: uploadInfo.session_key });
+  const headers = computeAws4Headers(url, credentials, {
+    method: 'POST',
+    body,
+    headers: { 'content-type': 'application/json;charset=UTF-8' },
+  });
+  const res = await fetch(url, { method: 'POST', headers, body, signal: AbortSignal.timeout(30000) });
+  const text = await res.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new CommandExecutionError(`提交抖音上传失败，非 JSON 响应: HTTP ${res.status} ${text.slice(0, 300)}`);
+  }
+  const error = payload?.ResponseMetadata?.Error;
+  if (!res.ok || error) {
+    throw new CommandExecutionError(`提交抖音上传失败: HTTP ${res.status} ${JSON.stringify(error ?? payload)}`);
+  }
+  const result = payload?.Result?.Results?.[0] ?? payload?.Result ?? {};
+  const videoId = result.Vid ?? result.VideoId ?? result.VideoID ?? result.vid ?? uploadInfo.video_id;
+  if (!videoId) {
+    throw new CommandExecutionError(`提交抖音上传响应缺少 video id: ${JSON.stringify(payload).slice(0, 500)}`);
+  }
+  const meta = result.Meta ?? result.VideoMeta ?? {};
+  return {
+    video_id: videoId,
+    poster_uri: result.PosterUri ?? result.PosterURI ?? result.SnapshotUri ?? result.SnapshotURI ?? '',
+    width: Number(meta.Width ?? meta.width ?? 720) || 720,
+    height: Number(meta.Height ?? meta.height ?? 1280) || 1280,
+    raw: result,
+  };
+}

package/clis/douyin/_shared/vod-upload.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getUploadAuthV5Credentials, applyVideoUploadInner } from './vod-upload.js';
+
+describe('douyin vod upload helpers', () => {
+  it('parses creator upload auth v5 credentials', async () => {
+    const page = { evaluate: async () => ({ status_code: 0, auth: JSON.stringify({ AccessKeyID: 'ak', SecretAccessKey: 'sk', SessionToken: 'token', ExpiredTime: 123, CurrentTime: 100 }) }) };
+    await expect(getUploadAuthV5Credentials(page)).resolves.toEqual({ access_key_id: 'ak', secret_access_key: 'sk', session_token: 'token', user_id: '', expired_time: 123, current_time: 100 });
+  });
+
+  it('unwraps browser bridge envelopes around upload auth payloads', async () => {
+    const payload = { status_code: 0, auth: JSON.stringify({ AccessKeyID: 'ak', SecretAccessKey: 'sk', SessionToken: 'token' }) };
+    const page = { evaluate: async () => ({ session: 'site:douyin:test', data: payload }) };
+    await expect(getUploadAuthV5Credentials(page)).resolves.toMatchObject({ access_key_id: 'ak', secret_access_key: 'sk', session_token: 'token' });
+  });
+
+  it('maps upload auth permission errors to AuthRequiredError', async () => {
+    const page = { evaluate: async () => ({ status_code: 401, status_msg: 'login required' }) };
+    await expect(getUploadAuthV5Credentials(page)).rejects.toBeInstanceOf(AuthRequiredError);
+  });
+
+  it('maps ApplyUploadInner response to TOS upload info', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({ ok: true, status: 200, text: async () => JSON.stringify({ ResponseMetadata: { RequestId: 'req' }, Result: { InnerUploadAddress: { UploadNodes: [{ Vid: 'video-id', SessionKey: 'session-key', UploadHost: 'tos.example.com', StoreInfos: [{ StoreUri: 'obj/key.mp4', Auth: 'space-auth' }] }] } } }) });
+    await expect(applyVideoUploadInner(1234, { access_key_id: 'ak', secret_access_key: 'sk', session_token: 'token' })).resolves.toEqual({ video_id: 'video-id', tos_upload_url: 'https://tos.example.com/obj/key.mp4', auth: 'space-auth', session_key: 'session-key', upload_header: {}, user_id: '' });
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain('Action=ApplyUploadInner');
+    expect(String(url)).toContain('Version=2020-11-19');
+    expect(init.headers.Authorization).toContain('AWS4-HMAC-SHA256 Credential=ak/');
+    expect(init.headers['x-amz-security-token']).toBe('token');
+    fetchSpy.mockRestore();
+  });
+
+  it('surfaces VOD API errors with context', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({ ok: true, status: 200, text: async () => JSON.stringify({ ResponseMetadata: { Error: { Code: 'AccessDenied', Message: 'denied' } } }) });
+    await expect(applyVideoUploadInner(1234, { access_key_id: 'ak', secret_access_key: 'sk', session_token: 'token' })).rejects.toBeInstanceOf(CommandExecutionError);
+    fetchSpy.mockRestore();
+  });
+});

package/clis/douyin/delete.js

@@ -1,19 +1,152 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { browserFetch } from './_shared/browser-fetch.js';
+import { requireObjectEvaluateResult } from './_shared/evaluate-result.js';
+
+const CREATOR_MANAGE_URL = 'https://creator.douyin.com/creator-micro/content/manage';
+const WORK_LIST_URL = '/janus/douyin/creator/pc/work_list?status=0&count=20&max_cursor=0&scene=star_atlas&device_platform=android&aid=1128';
+
+function readAwemeId(raw) {
+    const value = String(raw ?? '').trim();
+    if (!value) {
+        throw new ArgumentError('douyin delete aweme_id cannot be empty');
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new ArgumentError('douyin delete aweme_id must be a numeric id');
+    }
+    return value;
+}
+
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function deleteViaCreatorManage(page, workId) {
+    await page.goto(CREATOR_MANAGE_URL);
+    await sleep(3000);
+    await sleep(3000);
+    const result = requireObjectEvaluateResult(await page.evaluate(`
+    (async () => {
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+      const targetId = ${JSON.stringify(String(workId))};
+      const textOf = (node) => (node && (node.innerText || node.textContent) || '').trim();
+      const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
+
+      async function loadTarget() {
+        const res = await fetch(${JSON.stringify(WORK_LIST_URL)}, { credentials: 'include' });
+        const payload = await res.json();
+        const list = Array.isArray(payload.aweme_list) ? payload.aweme_list : [];
+        const matches = list
+          .map((entry, index) => ({ entry, index }))
+          .filter(({ entry }) => String(entry.aweme_id || '') === targetId || String(entry.item_id || '') === targetId);
+        if (matches.length === 0) {
+          return { ok: false, reason: 'not_found', status_code: payload.status_code, count: list.length };
+        }
+        if (matches.length !== 1) {
+          return { ok: false, reason: 'target_not_unique', count: matches.length };
+        }
+        const { entry: item, index } = matches[0];
+        const title = normalize(item.desc || item.caption || item.title || item.item_title || '');
+        return { ok: true, item, index, listCount: list.length, title };
+      }
+
+      function visibleWorkCards() {
+        const candidates = Array.from(document.querySelectorAll('[class*="video-card"]'))
+          .filter((element) => {
+            const text = normalize(textOf(element));
+            return text.includes('删除作品') && text.includes('继续编辑');
+          });
+        return candidates.filter((candidate) => !candidates.some((other) => other !== candidate && other.contains(candidate)));
+      }
+
+      const target = await loadTarget();
+      if (!target.ok) return target;
+
+      const allTab = Array.from(document.querySelectorAll('button,[role="button"],span,div'))
+        .find((element) => /^全部作品$/.test(normalize(textOf(element))));
+      allTab?.click();
+      await sleep(1000);
+      for (let attempt = 0; attempt < 20; attempt += 1) {
+        const cards = visibleWorkCards();
+        if (cards.length >= target.listCount && cards[target.index]) {
+          const card = cards[target.index];
+          const deleteButton = Array.from(card.querySelectorAll('button,[role="button"],span,div'))
+            .find((element) => /^删除作品$/.test(normalize(textOf(element))));
+          if (!deleteButton) return { ok: false, reason: 'delete_button_not_found', aweme_id: target.item.aweme_id, item_id: target.item.item_id, index: target.index, cardCount: cards.length };
+          deleteButton.click();
+          await sleep(800);
+          const confirmButton = Array.from(document.querySelectorAll('button,[role="button"]'))
+            .find((element) => ['确定', '确认', '删除'].includes(normalize(textOf(element))));
+          if (!confirmButton) return { ok: false, reason: 'confirm_button_not_found', aweme_id: target.item.aweme_id, item_id: target.item.item_id };
+          confirmButton.click();
+          for (let wait = 0; wait < 20; wait += 1) {
+            await sleep(500);
+            const after = await loadTarget();
+            if (!after.ok && after.reason === 'not_found') {
+              return { ok: true, aweme_id: target.item.aweme_id, item_id: target.item.item_id, title: target.title };
+            }
+          }
+          return { ok: false, reason: 'delete_not_confirmed', aweme_id: target.item.aweme_id, item_id: target.item.item_id };
+        }
+        await sleep(500);
+      }
+      return { ok: false, reason: 'card_not_found', aweme_id: target.item.aweme_id, item_id: target.item.item_id, index: target.index, listCount: target.listCount };
+    })()
+  `), '抖音后台管理删除响应异常');
+
+    if (!result?.ok) {
+        throw new CommandExecutionError(`抖音后台管理删除失败: ${JSON.stringify(result)}`);
+    }
+    return result;
+}
+
+async function findWorkListItem(page, workId) {
+    const data = await browserFetch(page, 'GET', `https://creator.douyin.com${WORK_LIST_URL}`, { timeoutMs: 8000 });
+    const list = data.data?.work_list ?? data.aweme_list ?? data.work_list ?? [];
+    if (!Array.isArray(list)) {
+        throw new CommandExecutionError('抖音作品列表响应缺少 work_list/aweme_list');
+    }
+    return list.find((entry) => String(entry.aweme_id || '') === workId || String(entry.item_id || '') === workId) || null;
+}
+
 cli({
     site: 'douyin',
     name: 'delete',
     access: 'write',
-    description: '删除作品',
+    description: '删除作品（优先使用创作者后台作品管理；找不到时回退到旧删除接口）',
     domain: 'creator.douyin.com',
     strategy: Strategy.COOKIE,
+    siteSession: 'persistent',
     args: [
-        { name: 'aweme_id', required: true, positional: true, help: '作品 ID' },
+        { name: 'aweme_id', required: true, positional: true, help: '作品 ID / item_id' },
     ],
     columns: ['status'],
     func: async (page, kwargs) => {
+        const awemeId = readAwemeId(kwargs.aweme_id);
+        try {
+            const deleted = await deleteViaCreatorManage(page, awemeId);
+            return [{ status: `✅ 已通过后台管理删除 ${deleted.aweme_id || awemeId}` }];
+        } catch (fallbackError) {
+            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+            if (!fallbackMessage.includes('"reason":"not_found"')) {
+                throw fallbackError;
+            }
+        }
+
+        const before = await findWorkListItem(page, awemeId);
+        if (!before) {
+            throw new CommandExecutionError(`抖音作品 ${awemeId} 未在作品列表中找到，未执行删除`);
+        }
         const url = 'https://creator.douyin.com/web/api/media/aweme/delete/?aid=1128';
-        await browserFetch(page, 'POST', url, { body: { aweme_id: kwargs.aweme_id } });
-        return [{ status: `✅ 已删除 ${kwargs.aweme_id}` }];
+        await browserFetch(page, 'POST', url, { body: { aweme_id: awemeId }, timeoutMs: 8000 });
+        const deadline = Date.now() + 10_000;
+        while (Date.now() < deadline) {
+            await sleep(500);
+            const after = await findWorkListItem(page, awemeId);
+            if (!after) {
+                return [{ status: `✅ 已删除 ${awemeId}` }];
+            }
+        }
+        throw new CommandExecutionError(`抖音作品 ${awemeId} 删除后仍在作品列表中，删除未确认`);
     },
 });

package/clis/douyin/delete.test.js

@@ -1,11 +1,100 @@
-import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { getRegistry } from '@jackwener/opencli/registry';
+
+const mocks = vi.hoisted(() => ({
+    browserFetch: vi.fn(),
+}));
+
+vi.mock('./_shared/browser-fetch.js', () => ({ browserFetch: mocks.browserFetch }));
+
 import './delete.js';
+
+function makePage({ evaluateResult, listBefore = [], listAfter = [] } = {}) {
+    let listCalls = 0;
+    mocks.browserFetch.mockImplementation(async (_page, method, url) => {
+        if (method === 'GET' && String(url).includes('/work_list?')) {
+            listCalls += 1;
+            return { aweme_list: listCalls === 1 ? listBefore : listAfter };
+        }
+        return { status_code: 0 };
+    });
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(evaluateResult ?? { ok: false, reason: 'not_found' }),
+        wait: vi.fn().mockResolvedValue(undefined),
+    };
+}
+
 describe('douyin delete registration', () => {
+    const command = getRegistry().get('douyin/delete');
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
     it('registers the delete command', () => {
         const registry = getRegistry();
         const values = [...registry.values()];
         const cmd = values.find(c => c.site === 'douyin' && c.name === 'delete');
         expect(cmd).toBeDefined();
     });
+
+    it('uses work_list id/index matching instead of title matching for fallback deletion', () => {
+        const source = readFileSync(new URL('./delete.js', import.meta.url), 'utf8');
+        expect(source).toContain('target_not_unique');
+        expect(source).toContain("String(entry.aweme_id || '') === targetId");
+        expect(source).toContain('cards[target.index]');
+        expect(source).not.toContain('text.includes(target.title)');
+    });
+
+    it('validates aweme_id before navigation', async () => {
+        const page = makePage();
+        await expect(command.func(page, { aweme_id: '' })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(page, { aweme_id: 'abc' })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('does not treat a missing work as successful delete', async () => {
+        const page = makePage({ listBefore: [], listAfter: [] });
+        const promise = command.func(page, { aweme_id: '123' });
+        const assertion = expect(promise).rejects.toBeInstanceOf(CommandExecutionError);
+        await vi.advanceTimersByTimeAsync(7000);
+        await assertion;
+    });
+
+    it('unwraps Browser Bridge envelopes around creator manage delete results', async () => {
+        const page = makePage({ evaluateResult: { session: 'site:douyin:test', data: { ok: true, aweme_id: '123' } } });
+        const promise = command.func(page, { aweme_id: '123' });
+        const assertion = expect(promise).resolves.toEqual([{ status: '✅ 已通过后台管理删除 123' }]);
+        await vi.advanceTimersByTimeAsync(7000);
+        await assertion;
+        expect(mocks.browserFetch).not.toHaveBeenCalled();
+    });
+
+    it('throws typed on malformed creator manage delete result', async () => {
+        const page = makePage({ evaluateResult: 'bad-shape' });
+        const promise = command.func(page, { aweme_id: '123' });
+        const assertion = expect(promise).rejects.toBeInstanceOf(CommandExecutionError);
+        await vi.advanceTimersByTimeAsync(7000);
+        await assertion;
+        expect(mocks.browserFetch).not.toHaveBeenCalled();
+    });
+
+    it('returns success only after fallback delete postcondition removes the target', async () => {
+        const page = makePage({
+            listBefore: [{ aweme_id: '123' }],
+            listAfter: [],
+        });
+        const promise = command.func(page, { aweme_id: '123' });
+        const assertion = expect(promise).resolves.toEqual([{ status: '✅ 已删除 123' }]);
+        await vi.advanceTimersByTimeAsync(8000);
+        await assertion;
+    });
 });

package/clis/douyin/hashtag.js

@@ -1,6 +1,40 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { browserFetch } from './_shared/browser-fetch.js';
-import { ArgumentError } from '@jackwener/opencli/errors';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireListField(res, field, action) {
+    if (!isPlainObject(res)) {
+        throw new CommandExecutionError(`douyin hashtag ${action}: API returned malformed payload`);
+    }
+    const list = res[field];
+    if (list === undefined || list === null) return [];
+    if (!Array.isArray(list)) {
+        throw new CommandExecutionError(`douyin hashtag ${action}: API returned malformed "${field}"`);
+    }
+    return list;
+}
+
+function validateHashtagArgs(kwargs) {
+    const action = kwargs.action;
+    if (action === 'search') {
+        const keyword = String(kwargs.keyword ?? '').trim();
+        if (!keyword) {
+            throw new ArgumentError('douyin hashtag search 需要 --keyword <关键词>', '示例: opencli douyin hashtag search --keyword 美食');
+        }
+        return;
+    }
+    if (action === 'suggest') {
+        const cover = String(kwargs.cover ?? '').trim();
+        if (!cover) {
+            throw new ArgumentError('douyin hashtag suggest 需要 --cover <cover_uri>', 'suggest 基于已上传的视频封面做 AI 推荐, 不是关键词搜索. 关键词搜索请用 `douyin hashtag search --keyword <词>`.');
+        }
+    }
+}
+
 cli({
     site: 'douyin',
     name: 'hashtag',
@@ -9,43 +43,70 @@ cli({
     domain: 'creator.douyin.com',
     strategy: Strategy.COOKIE,
     args: [
-        { name: 'action', required: true, positional: true, choices: ['search', 'suggest', 'hot'], help: 'search=关键词搜索 suggest=AI推荐 hot=热点词' },
-        { name: 'keyword', default: '', help: '搜索关键词（search/hot 使用）' },
-        { name: 'cover', default: '', help: '封面 URI（suggest 使用）' },
+        { name: 'action', required: true, positional: true, choices: ['search', 'suggest', 'hot'], help: 'search=关键词搜索 (--keyword 必填), suggest=AI推荐 (--cover 必填), hot=热点词 (--keyword 可选)' },
+        { name: 'keyword', default: '', help: '搜索关键词. search 必填; hot 可选; suggest 不使用 (传 --cover)' },
+        { name: 'cover', default: '', help: '封面 URI (cover_uri). suggest 必填; 其它 action 不使用' },
         { name: 'limit', type: 'int', default: 10 },
     ],
     columns: ['name', 'id', 'view_count'],
+    validateArgs: validateHashtagArgs,
     func: async (page, kwargs) => {
+        validateHashtagArgs(kwargs);
         const action = kwargs.action;
         if (action === 'search') {
-            const url = `https://creator.douyin.com/aweme/v1/challenge/search/?keyword=${encodeURIComponent(kwargs.keyword)}&count=${kwargs.limit}&aid=1128`;
+            const keyword = String(kwargs.keyword ?? '').trim();
+            const url = `https://creator.douyin.com/aweme/v1/challenge/search/?keyword=${encodeURIComponent(keyword)}&count=${kwargs.limit}&aid=1128`;
             const res = await browserFetch(page, 'GET', url);
-            return (res.challenge_list ?? []).map(c => ({
-                name: c.challenge_info.cha_name,
-                id: c.challenge_info.cid,
-                view_count: c.challenge_info.view_count,
-            }));
+            const list = requireListField(res, 'challenge_list', 'search');
+            const rows = list.flatMap(c => {
+                const info = c?.challenge_info;
+                if (!isPlainObject(info)) return [];
+                return [{
+                    name: info.cha_name,
+                    id: info.cid,
+                    view_count: info.view_count,
+                }];
+            });
+            if (list.length > 0 && rows.length === 0) {
+                throw new CommandExecutionError('douyin hashtag search: API returned challenges but none had stable challenge_info shape');
+            }
+            return rows;
         }
         if (action === 'suggest') {
-            const url = `https://creator.douyin.com/web/api/media/hashtag/rec/?cover_uri=${encodeURIComponent(kwargs.cover)}&aid=1128`;
+            const cover = String(kwargs.cover ?? '').trim();
+            const url = `https://creator.douyin.com/web/api/media/hashtag/rec/?cover_uri=${encodeURIComponent(cover)}&aid=1128`;
             const res = await browserFetch(page, 'GET', url);
-            return (res.hashtag_list ?? []).map(h => ({ name: h.name, id: h.id, view_count: h.view_count }));
+            const list = requireListField(res, 'hashtag_list', 'suggest');
+            return list.map(h => ({ name: h?.name ?? '', id: h?.id ?? '', view_count: h?.view_count ?? 0 }));
         }
         if (action === 'hot') {
-            const kw = kwargs.keyword;
+            const kw = String(kwargs.keyword ?? '').trim();
             const url = `https://creator.douyin.com/aweme/v1/hotspot/recommend/?${kw ? `keyword=${encodeURIComponent(kw)}&` : ''}aid=1128`;
             const res = await browserFetch(page, 'GET', url);
-            const items = res.hotspot_list
-                ?? res.all_sentences?.map(h => ({
-                    sentence: h.word ?? '',
-                    hot_value: h.hot_value,
-                    sentence_id: h.sentence_id ?? '',
-                }))
-                ?? [];
+            if (!isPlainObject(res)) {
+                throw new CommandExecutionError('douyin hashtag hot: API returned malformed payload');
+            }
+            const hotspotList = res.hotspot_list;
+            const allSentences = res.all_sentences;
+            if (hotspotList !== undefined && hotspotList !== null && !Array.isArray(hotspotList)) {
+                throw new CommandExecutionError('douyin hashtag hot: API returned malformed "hotspot_list"');
+            }
+            if (allSentences !== undefined && allSentences !== null && !Array.isArray(allSentences)) {
+                throw new CommandExecutionError('douyin hashtag hot: API returned malformed "all_sentences"');
+            }
+            const items = Array.isArray(hotspotList)
+                ? hotspotList
+                : Array.isArray(allSentences)
+                    ? allSentences.map(h => ({
+                        sentence: h?.word ?? '',
+                        hot_value: h?.hot_value,
+                        sentence_id: h?.sentence_id ?? '',
+                    }))
+                    : [];
             return items.slice(0, kwargs.limit).map(h => ({
-                name: h.sentence,
-                id: 'sentence_id' in h ? h.sentence_id : '',
-                view_count: h.hot_value,
+                name: h?.sentence ?? '',
+                id: h && 'sentence_id' in h ? h.sentence_id : '',
+                view_count: h?.hot_value ?? 0,
             }));
         }
         throw new ArgumentError(`未知的 action: ${action}`);