@jackwener/opencli 1.7.21 → 1.8.0

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/publish-upload-id.test.js

@@ -0,0 +1,170 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  browserFetch: vi.fn(),
+  getUploadAuthV5Credentials: vi.fn(),
+  applyVideoUploadInner: vi.fn(),
+  commitVideoUploadInner: vi.fn(),
+  tosUpload: vi.fn(),
+  pollTranscode: vi.fn(),
+  imagexUpload: vi.fn(),
+}));
+
+vi.mock('./_shared/browser-fetch.js', () => ({ browserFetch: mocks.browserFetch }));
+vi.mock('./_shared/vod-upload.js', () => ({
+  getUploadAuthV5Credentials: mocks.getUploadAuthV5Credentials,
+  applyVideoUploadInner: mocks.applyVideoUploadInner,
+  commitVideoUploadInner: mocks.commitVideoUploadInner,
+}));
+vi.mock('./_shared/tos-upload.js', () => ({ tosUpload: mocks.tosUpload }));
+vi.mock('./_shared/transcode.js', () => ({ pollTranscode: mocks.pollTranscode }));
+vi.mock('./_shared/imagex-upload.js', () => ({ imagexUpload: mocks.imagexUpload }));
+
+describe('douyin publish upload identifier handling', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.getUploadAuthV5Credentials.mockResolvedValue({ access_key_id: 'ak', secret_access_key: 'sk', session_token: 'token' });
+    mocks.applyVideoUploadInner.mockResolvedValue({ video_id: 'apply-video-id', tos_upload_url: 'https://tos.example.com/bucket/key', auth: 'auth', session_key: 'session-key' });
+    mocks.commitVideoUploadInner.mockResolvedValue({ video_id: 'canonical-video-id', poster_uri: 'poster-uri' });
+    mocks.tosUpload.mockResolvedValue('object-key-returned-by-complete');
+    mocks.pollTranscode.mockResolvedValue({ width: 720, height: 1280, poster_uri: 'poster-uri' });
+    mocks.browserFetch.mockImplementation(async (_page, method, url) => {
+      if (method === 'POST' && String(url).includes('/aweme/create_v2/')) return { aweme_id: 'aweme-1' };
+      return { status_code: 0 };
+    });
+  });
+
+  it('uses CommitUploadInner Vid for create_v2, not the completed TOS object key', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'douyin-publish-id-'));
+    const video = path.join(tmpDir, 'video.mp4');
+    fs.writeFileSync(video, Buffer.from('fake-video'));
+
+    const { getRegistry } = await import('@jackwener/opencli/registry');
+    getRegistry().delete('douyin/publish');
+    await import('./publish.js');
+    const cmd = getRegistry().get('douyin/publish');
+    if (!cmd) throw new Error('douyin publish command not registered');
+
+    await cmd.func({}, {
+      video,
+      title: 'OpenCLI自测',
+      schedule: new Date(Date.now() + 3 * 60 * 60 * 1000).toISOString(),
+      caption: '',
+      visibility: 'private',
+      no_safety_check: true,
+    });
+
+    expect(mocks.commitVideoUploadInner).toHaveBeenCalledWith(
+      { video_id: 'apply-video-id', tos_upload_url: 'https://tos.example.com/bucket/key', auth: 'auth', session_key: 'session-key' },
+      { access_key_id: 'ak', secret_access_key: 'sk', session_token: 'token' },
+    );
+    expect(mocks.pollTranscode).not.toHaveBeenCalled();
+    const createCall = mocks.browserFetch.mock.calls.find((call) => String(call[2]).includes('/aweme/create_v2/'));
+    expect(createCall?.[3]?.body.item.common.video_id).toBe('canonical-video-id');
+    expect(createCall?.[3]?.body.item.common.video_id).not.toBe('object-key-returned-by-complete');
+  });
+
+  it('continues to create_v2 when the legacy fast detect API returns an empty response', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'douyin-publish-safety-'));
+    const video = path.join(tmpDir, 'video.mp4');
+    fs.writeFileSync(video, Buffer.from('fake-video'));
+    mocks.browserFetch.mockImplementation(async (_page, method, url) => {
+      if (method === 'POST' && String(url).includes('/post_assistant/fast_detect/pre_check')) {
+        throw new Error('Empty response from Douyin API (POST https://creator.douyin.com/aweme/v1/post_assistant/fast_detect/pre_check)');
+      }
+      if (method === 'POST' && String(url).includes('/post_assistant/fast_detect/poll')) return { status: -1, has_done: true, detect_result: { reason_code: 0 }, detect_list: [] };
+      if (method === 'POST' && String(url).includes('/aweme/create_v2/')) return { item_id: 'item-1' };
+      return { status_code: 0 };
+    });
+
+    const { getRegistry } = await import('@jackwener/opencli/registry');
+    getRegistry().delete('douyin/publish');
+    await import('./publish.js');
+    const cmd = getRegistry().get('douyin/publish');
+    if (!cmd) throw new Error('douyin publish command not registered');
+
+    await cmd.func({}, {
+      video,
+      title: 'OpenCLI自测',
+      schedule: new Date(Date.now() + 3 * 60 * 60 * 1000).toISOString(),
+      visibility: 'public',
+      caption: 'caption',
+      no_safety_check: false,
+    });
+
+    expect(mocks.browserFetch.mock.calls.some((call) => String(call[2]).includes('/post_assistant/fast_detect/pre_check'))).toBe(true);
+    expect(mocks.browserFetch.mock.calls.some((call) => String(call[2]).includes('/aweme/create_v2/'))).toBe(true);
+  });
+
+  it('unwraps Browser Bridge envelopes around cover ImageX evaluate results', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'douyin-publish-cover-'));
+    const video = path.join(tmpDir, 'video.mp4');
+    const cover = path.join(tmpDir, 'cover.jpg');
+    fs.writeFileSync(video, Buffer.from('fake-video'));
+    fs.writeFileSync(cover, Buffer.from('fake-cover'));
+    mocks.imagexUpload.mockResolvedValue('cover-store-uri');
+
+    const page = {
+      evaluate: vi.fn()
+        .mockResolvedValueOnce({
+          session: 'site:douyin:test',
+          data: { Result: { UploadAddress: { StoreInfos: [{ UploadHost: 'imagex.example.com', StoreUri: 'cover/key.jpg' }] } } },
+        })
+        .mockResolvedValueOnce({ session: 'site:douyin:test', data: { Result: {} } }),
+    };
+
+    const { getRegistry } = await import('@jackwener/opencli/registry');
+    getRegistry().delete('douyin/publish');
+    await import('./publish.js');
+    const cmd = getRegistry().get('douyin/publish');
+    if (!cmd) throw new Error('douyin publish command not registered');
+
+    await cmd.func(page, {
+      video,
+      cover,
+      title: 'OpenCLI自测',
+      schedule: new Date(Date.now() + 3 * 60 * 60 * 1000).toISOString(),
+      caption: '',
+      visibility: 'private',
+      no_safety_check: true,
+    });
+
+    expect(mocks.imagexUpload).toHaveBeenCalledWith(cover, {
+      upload_url: 'https://imagex.example.com/cover/key.jpg',
+      store_uri: 'cover/key.jpg',
+    });
+    const createCall = mocks.browserFetch.mock.calls.find((call) => String(call[2]).includes('/aweme/create_v2/'));
+    expect(createCall?.[3]?.body.item.cover.poster).toBe('cover-store-uri');
+  });
+
+  it('throws typed when cover ImageX apply returns the wrong shape', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'douyin-publish-cover-bad-'));
+    const video = path.join(tmpDir, 'video.mp4');
+    const cover = path.join(tmpDir, 'cover.jpg');
+    fs.writeFileSync(video, Buffer.from('fake-video'));
+    fs.writeFileSync(cover, Buffer.from('fake-cover'));
+
+    const page = { evaluate: vi.fn().mockResolvedValueOnce({ session: 'site:douyin:test', data: { Result: { UploadAddress: { StoreInfos: [] } } } }) };
+
+    const { getRegistry } = await import('@jackwener/opencli/registry');
+    getRegistry().delete('douyin/publish');
+    await import('./publish.js');
+    const cmd = getRegistry().get('douyin/publish');
+    if (!cmd) throw new Error('douyin publish command not registered');
+
+    await expect(cmd.func(page, {
+      video,
+      cover,
+      title: 'OpenCLI自测',
+      schedule: new Date(Date.now() + 3 * 60 * 60 * 1000).toISOString(),
+      caption: '',
+      visibility: 'private',
+      no_safety_check: true,
+    })).rejects.toThrow('UploadHost/StoreUri');
+    expect(mocks.imagexUpload).not.toHaveBeenCalled();
+  });
+});

package/clis/douyin/publish.js

@@ -2,7 +2,7 @@
  * Douyin publish — 8-phase pipeline for scheduling video posts.
  *
  * Phases:
- *   1. STS2 credentials
+ *   1. upload auth v5 credentials
  *   2. Apply TOS upload URL
  *   3. TOS multipart upload
  *   4. Cover upload (optional, via ImageX)
@@ -15,11 +15,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
-import { getSts2Credentials } from './_shared/sts2.js';
+import { getUploadAuthV5Credentials, applyVideoUploadInner, commitVideoUploadInner } from './_shared/vod-upload.js';
 import { tosUpload } from './_shared/tos-upload.js';
 import { imagexUpload } from './_shared/imagex-upload.js';
-import { pollTranscode } from './_shared/transcode.js';
 import { browserFetch } from './_shared/browser-fetch.js';
+import { requireObjectEvaluateResult } from './_shared/evaluate-result.js';
 import { generateCreationId } from './_shared/creation-id.js';
 import { validateTiming, toUnixSeconds } from './_shared/timing.js';
 import { parseTextExtra, extractHashtagNames } from './_shared/text-extra.js';
@@ -54,6 +54,36 @@ const DEFAULT_COVER_TOOLS_INFO = JSON.stringify({
     initial_cover_uri: '',
     cut_coordinate: '',
 });
+function isFastDetectRetryable(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes('post_assistant/fast_detect') && (message.includes('Empty response') || message.includes('404') || message.includes('Not Found') || message.includes('Timeout') || message.includes('timed out') || message.includes('Failed to fetch'));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function throwIfImagexError(action, payload) {
+    const error = payload?.ResponseMetadata?.Error ?? payload?.Error;
+    if (error) {
+        throw new CommandExecutionError(`${action}失败: ${JSON.stringify(error)}`);
+    }
+}
+async function tryFastDetectFetch(page, method, url, options) {
+    let lastError;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+        try {
+            return { ok: true, value: await browserFetch(page, method, url, options) };
+        } catch (error) {
+            if (!isFastDetectRetryable(error)) {
+                throw error;
+            }
+            lastError = error;
+            if (attempt < 3) {
+                await sleep(500 * attempt);
+            }
+        }
+    }
+    return { ok: false, error: lastError };
+}
 cli({
     site: 'douyin',
     name: 'publish',
@@ -106,19 +136,13 @@ cli({
                 throw new ArgumentError(`封面文件不存在: ${path.resolve(coverPath)}`);
             }
         }
-        // ── Phase 1: STS2 credentials ───────────────────────────────────────
-        const credentials = await getSts2Credentials(page);
+        // ── Phase 1: upload credentials ────────────────────────────────────
+        const credentials = await getUploadAuthV5Credentials(page);
         // ── Phase 2: Apply TOS upload URL ───────────────────────────────────
-        const vodUrl = `https://vod.bytedanceapi.com/?Action=ApplyVideoUpload&ServiceId=1128&Version=2021-01-01&FileType=video&FileSize=${fileSize}`;
-        const vodJs = `fetch(${JSON.stringify(vodUrl)}, { credentials: 'include' }).then(r => r.json())`;
-        const vodRes = (await page.evaluate(vodJs));
-        const { VideoId: videoId, UploadHosts, StoreInfos } = vodRes.Result.UploadAddress;
-        const tosUrl = `https://${UploadHosts[0]}/${StoreInfos[0].StoreUri}`;
-        const tosUploadInfo = {
-            tos_upload_url: tosUrl,
-            auth: StoreInfos[0].Auth,
-            video_id: videoId,
-        };
+        const tosUploadInfo = await applyVideoUploadInner(fileSize, credentials);
+        let coverUri = '';
+        let coverWidth = 720;
+        let coverHeight = 1280;
         // ── Phase 3: TOS upload ─────────────────────────────────────────────
         await tosUpload({
             filePath: videoPath,
@@ -130,22 +154,32 @@ cli({
             },
         });
         process.stderr.write('\n');
+        process.stderr.write('  提交上传...\n');
+        const committedVideo = await commitVideoUploadInner(tosUploadInfo, credentials);
+        const videoId = committedVideo.video_id;
+        process.stderr.write(`  上传已提交: ${videoId}\n`);
+        coverWidth = committedVideo.width || coverWidth;
+        coverHeight = committedVideo.height || coverHeight;
+        if (!coverUri && committedVideo.poster_uri) {
+            coverUri = committedVideo.poster_uri;
+        }
         // ── Phase 4: Cover upload (optional) ────────────────────────────────
-        let coverUri = '';
-        let coverWidth = 720;
-        let coverHeight = 1280;
         if (kwargs.cover) {
             const resolvedCoverPath = path.resolve(kwargs.cover);
             // 4A: Apply ImageX upload
             const applyUrl = `${IMAGEX_BASE}/?Action=ApplyImageUpload&ServiceId=${IMAGEX_SERVICE_ID}&Version=2018-08-01&UploadNum=1`;
             const applyJs = `fetch(${JSON.stringify(applyUrl)}, { credentials: 'include' }).then(r => r.json())`;
-            const applyRes = (await page.evaluate(applyJs));
-            const { StoreInfos: imgStoreInfos } = applyRes.Result.UploadAddress;
-            const imgUploadUrl = `https://${imgStoreInfos[0].UploadHost}/${imgStoreInfos[0].StoreUri}`;
+            const applyRes = requireObjectEvaluateResult(await page.evaluate(applyJs), '抖音封面申请上传地址响应异常');
+            throwIfImagexError('抖音封面申请上传地址', applyRes);
+            const imgStoreInfo = applyRes.Result?.UploadAddress?.StoreInfos?.[0];
+            if (!imgStoreInfo?.UploadHost || !imgStoreInfo?.StoreUri) {
+                throw new CommandExecutionError(`抖音封面申请上传地址响应缺少 UploadHost/StoreUri: ${JSON.stringify(applyRes).slice(0, 500)}`);
+            }
+            const imgUploadUrl = `https://${imgStoreInfo.UploadHost}/${imgStoreInfo.StoreUri}`;
             // 4B: Upload image
             const coverStoreUri = await imagexUpload(resolvedCoverPath, {
                 upload_url: imgUploadUrl,
-                store_uri: imgStoreInfos[0].StoreUri,
+                store_uri: imgStoreInfo.StoreUri,
             });
             // 4C: Commit ImageX upload
             const commitUrl = `${IMAGEX_BASE}/?Action=CommitImageUpload&ServiceId=${IMAGEX_SERVICE_ID}&Version=2018-08-01`;
@@ -158,19 +192,13 @@ cli({
           body: ${JSON.stringify(commitBody)}
         }).then(r => r.json())
       `;
-            await page.evaluate(commitJs);
+            const commitRes = requireObjectEvaluateResult(await page.evaluate(commitJs), '抖音封面提交上传响应异常');
+            throwIfImagexError('抖音封面提交上传', commitRes);
             coverUri = coverStoreUri;
         }
-        // ── Phase 5: Enable video ───────────────────────────────────────────
-        const enableUrl = `https://creator.douyin.com/web/api/media/video/enable/?video_id=${videoId}&aid=1128`;
-        await browserFetch(page, 'GET', enableUrl);
-        // ── Phase 6: Poll transcode ─────────────────────────────────────────
-        const transResult = await pollTranscode(page, videoId);
-        coverWidth = transResult.width;
-        coverHeight = transResult.height;
-        if (!coverUri) {
-            coverUri = transResult.poster_uri;
-        }
+        // The gateway upload flow returns a committed VOD upload result; the legacy
+        // enable/transend endpoints can hang for that flow, so create_v2 consumes
+        // the committed video_id and poster metadata directly.
         // ── Phase 7: Content safety check ───────────────────────────────────
         if (!kwargs.no_safety_check) {
             const safetyUrl = 'https://creator.douyin.com/aweme/v1/post_assistant/fast_detect/pre_check';
@@ -179,25 +207,42 @@ cli({
                 title,
                 desc: caption,
             };
-            await browserFetch(page, 'POST', safetyUrl, { body: safetyBody });
+            const preCheck = await tryFastDetectFetch(page, 'POST', safetyUrl, { body: safetyBody });
+            if (!preCheck.ok) {
+                process.stderr.write('  内容安全预检接口无响应，继续轮询检测结果。\n');
+            }
             const pollUrl = 'https://creator.douyin.com/aweme/v1/post_assistant/fast_detect/poll';
             const deadline = Date.now() + 30_000;
             let safetyPassed = false;
+            let pollUnavailableCount = 0;
             while (Date.now() < deadline) {
-                const pollRes = (await browserFetch(page, 'POST', pollUrl, {
-                    body: safetyBody,
-                }));
-                if (pollRes.status === 0) {
+                const poll = await tryFastDetectFetch(page, 'POST', pollUrl, { body: safetyBody });
+                if (!poll.ok) {
+                    pollUnavailableCount += 1;
+                    if (!preCheck.ok && pollUnavailableCount >= 3) {
+                        break;
+                    }
+                    await sleep(2000);
+                    continue;
+                }
+                pollUnavailableCount = 0;
+                const pollRes = poll.value;
+                if (pollRes.status === 0 || (pollRes.has_done === true && pollRes.detect_result?.reason_code === 0 && (pollRes.detect_list?.length ?? 0) === 0)) {
                     safetyPassed = true;
                     break;
                 }
                 if (pollRes.status === 1) {
                     throw new CommandExecutionError('内容安全检测不通过，请修改后重试', '使用 --no_safety_check 跳过');
                 }
-                await new Promise((r) => setTimeout(r, 2000));
+                await sleep(2000);
             }
             if (!safetyPassed) {
-                throw new CommandExecutionError('内容安全检测超时（30s），请稍后重试', '使用 --no_safety_check 跳过');
+                if (!preCheck.ok && pollUnavailableCount >= 3) {
+                    process.stderr.write('  内容安全预检持续无响应，跳过本地预检，交由 create_v2 后的平台审核。\n');
+                }
+                else {
+                    throw new CommandExecutionError('内容安全检测超时（30s），请稍后重试', '如确认要跳过本地预检，可使用 --no_safety_check；提交后仍会走抖音平台审核');
+                }
             }
         }
         // ── Phase 8: create_v2 publish ──────────────────────────────────────
@@ -266,12 +311,13 @@ cli({
             },
         };
         const publishUrl = `https://creator.douyin.com/web/api/media/aweme/create_v2/?read_aid=2906&${DEVICE_PARAMS}`;
+        process.stderr.write('  创建定时发布...\n');
         const publishRes = (await browserFetch(page, 'POST', publishUrl, {
             body: publishBody,
         }));
-        const awemeId = publishRes.aweme_id;
+        const awemeId = publishRes.aweme_id ?? publishRes.item_id;
         if (!awemeId) {
-            throw new CommandExecutionError(`发布成功但未返回 aweme_id: ${JSON.stringify(publishRes)}`);
+            throw new CommandExecutionError(`发布成功但未返回 aweme_id/item_id: ${JSON.stringify(publishRes)}`);
         }
         const url = `https://www.douyin.com/video/${awemeId}`;
         const publishTimeStr = new Date(timingTs * 1000).toLocaleString('zh-CN', {

package/clis/douyin/user-videos.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CliError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { fetchDouyinComments, fetchDouyinUserVideos } from './_shared/public-api.js';
 export const MAX_USER_VIDEOS_LIMIT = 20;
 export const USER_VIDEO_COMMENT_CONCURRENCY = 4;
@@ -27,8 +28,11 @@ async function fetchTopComments(page, awemeId, count) {
     try {
         return await fetchDouyinComments(page, awemeId, count);
     }
-    catch {
-        return [];
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        throw new CommandExecutionError(`Failed to fetch Douyin comments for video ${awemeId}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 cli({
@@ -53,6 +57,9 @@ cli({
         await page.goto(`https://www.douyin.com/user/${secUid}`);
         await page.wait(3);
         const awemeList = (await fetchDouyinUserVideos(page, secUid, limit)).slice(0, limit);
+        if (awemeList.length === 0) {
+            throw new EmptyResultError('douyin user-videos', `No videos were returned for sec_uid ${secUid}. Confirm the user exists and the Douyin session is valid.`);
+        }
         const videos = withComments
             ? await mapInBatches(awemeList, USER_VIDEO_COMMENT_CONCURRENCY, async (video) => ({
                 ...video,

package/clis/douyin/user-videos.test.js

@@ -8,6 +8,7 @@ vi.mock('./_shared/public-api.js', () => ({
     fetchDouyinComments: fetchDouyinCommentsMock,
 }));
 import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { DEFAULT_COMMENT_LIMIT, MAX_USER_VIDEOS_LIMIT, normalizeCommentLimit, normalizeUserVideosLimit } from './user-videos.js';
 describe('douyin user-videos', () => {
     beforeEach(() => {
@@ -105,4 +106,46 @@ describe('douyin user-videos', () => {
             },
         ]);
     });
+    it('throws EmptyResultError when the user videos API returns no rows', async () => {
+        const command = [...getRegistry().values()].find((cmd) => cmd.site === 'douyin' && cmd.name === 'user-videos');
+        expect(command?.func).toBeDefined();
+        if (!command?.func)
+            throw new Error('douyin user-videos command not registered');
+        fetchDouyinUserVideosMock.mockResolvedValueOnce([]);
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+        };
+        await expect(command.func(page, {
+            sec_uid: 'MS4w-empty',
+            limit: 3,
+            with_comments: true,
+            comment_limit: 5,
+        })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+    it('surfaces comment enrichment failures instead of returning empty comments', async () => {
+        const command = [...getRegistry().values()].find((cmd) => cmd.site === 'douyin' && cmd.name === 'user-videos');
+        expect(command?.func).toBeDefined();
+        if (!command?.func)
+            throw new Error('douyin user-videos command not registered');
+        fetchDouyinUserVideosMock.mockResolvedValueOnce([
+            {
+                aweme_id: '3',
+                desc: 'comment failure',
+                video: { duration: 2000, play_addr: { url_list: ['https://example.com/fail.mp4'] } },
+                statistics: { digg_count: 1 },
+            },
+        ]);
+        fetchDouyinCommentsMock.mockRejectedValueOnce(new Error('comment API down'));
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+        };
+        await expect(command.func(page, {
+            sec_uid: 'MS4w-test',
+            limit: 3,
+            with_comments: true,
+            comment_limit: 5,
+        })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
 });