publishport-opencli 1.8.4-pp.1

package/clis/douyin/draft.test.js

@@ -0,0 +1,335 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+import { wrapForEval } from '@jackwener/opencli/browser/utils';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { buildCoverCheckPanelTextJs } from './draft.js';
+import { createPageMock } from '../test-utils.js';
+// ─── Shared test helpers ────────────────────────────────────────────
+const tempDirs = [];
+function createTempVideo(name = 'demo.mp4') {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-douyin-draft-'));
+    tempDirs.push(dir);
+    const filePath = path.join(dir, name);
+    fs.writeFileSync(filePath, Buffer.from([0, 0, 0, 20, 102, 116, 121, 112]));
+    return filePath;
+}
+function createTempCover(videoPath, name = 'cover.jpg') {
+    const filePath = path.join(path.dirname(videoPath), name);
+    fs.writeFileSync(filePath, Buffer.from([0xff, 0xd8, 0xff, 0xd9]));
+    return filePath;
+}
+function getDraftCommand() {
+    const registry = getRegistry();
+    const cmd = [...registry.values()].find(c => c.site === 'douyin' && c.name === 'draft');
+    if (!cmd?.func)
+        throw new Error('douyin draft command not registered');
+    return cmd;
+}
+afterAll(() => {
+    for (const dir of tempDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+function createFakeTree(text, children = []) {
+    const node = {
+        textContent: text,
+        parentElement: null,
+        querySelectorAll: () => [],
+    };
+    node.querySelectorAll = () => {
+        const descendants = [];
+        for (const child of children) {
+            descendants.push(child, ...child.querySelectorAll('*'));
+        }
+        return descendants;
+    };
+    for (const child of children) {
+        child.parentElement = node;
+    }
+    return node;
+}
+describe('douyin draft registration', () => {
+    it('registers the draft command', () => {
+        const registry = getRegistry();
+        const values = [...registry.values()];
+        const cmd = values.find(c => c.site === 'douyin' && c.name === 'draft');
+        expect(cmd).toBeDefined();
+    });
+    it('extracts the higher quick-check panel instead of stopping at a header-only ancestor', () => {
+        const marker = createFakeTree('快速检测');
+        const state = createFakeTree('重新检测');
+        const header = createFakeTree('快速检测', [marker]);
+        const status = createFakeTree('重新检测', [state]);
+        const panel = createFakeTree('快速检测重新检测', [header, status]);
+        const body = createFakeTree('body', [panel]);
+        const g = globalThis;
+        const originalDocument = g.document;
+        g.document = {
+            body,
+            querySelectorAll: () => [marker, state],
+        };
+        try {
+            expect(eval(buildCoverCheckPanelTextJs())()).toBe('快速检测重新检测');
+        }
+        finally {
+            g.document = originalDocument;
+        }
+    });
+    it('returns empty when only header text exists and no exact quick-check state node is present', () => {
+        const marker = createFakeTree('快速检测');
+        const note = createFakeTree('检测说明');
+        const header = createFakeTree('快速检测检测说明', [marker, note]);
+        const body = createFakeTree('body', [header]);
+        const g = globalThis;
+        const originalDocument = g.document;
+        g.document = {
+            body,
+            querySelectorAll: () => [marker, note],
+        };
+        try {
+            expect(eval(buildCoverCheckPanelTextJs())()).toBe('');
+        }
+        finally {
+            g.document = originalDocument;
+        }
+    });
+    it('extracts the quick-check panel when busy state is rendered as a single 封面检测中 node', () => {
+        const marker = createFakeTree('快速检测');
+        const busy = createFakeTree('封面检测中');
+        const header = createFakeTree('快速检测', [marker]);
+        const status = createFakeTree('封面检测中', [busy]);
+        const panel = createFakeTree('快速检测封面检测中', [header, status]);
+        const body = createFakeTree('body', [panel]);
+        const g = globalThis;
+        const originalDocument = g.document;
+        g.document = {
+            body,
+            querySelectorAll: () => [marker, busy],
+        };
+        try {
+            expect(eval(buildCoverCheckPanelTextJs())()).toBe('快速检测封面检测中');
+        }
+        finally {
+            g.document = originalDocument;
+        }
+    });
+    it('uploads through the official creator draft page and saves the draft session', async () => {
+        const cmd = getDraftCommand();
+        const videoPath = createTempVideo('demo.mp4');
+        const page = createPageMock([
+            undefined,
+            { href: 'https://creator.douyin.com/creator-micro/content/post/video?enter_from=publish_page', ready: true, bodyText: '' },
+            undefined,
+            true,
+            true,
+            true,
+            { ok: true, text: '暂存离开', creationId: 'creation-001' },
+            {
+                href: 'https://creator.douyin.com/creator-micro/content/upload?enter_from=publish',
+                bodyText: '你还有上次未发布的视频，是否继续编辑？继续编辑放弃',
+            },
+        ]);
+        const rows = await cmd.func(page, {
+            video: videoPath,
+            title: '最小修复验证',
+            caption: 'opencli draft e2e',
+            cover: '',
+            visibility: 'friends',
+        });
+        expect(page.goto).toHaveBeenCalledWith('https://creator.douyin.com/creator-micro/content/upload');
+        expect(page.wait).toHaveBeenCalledWith({
+            selector: 'input[type="file"]',
+            timeout: 20,
+        });
+        expect(page.setFileInput).toHaveBeenCalledWith([videoPath], 'input[type="file"]');
+        const evaluateCalls = page.evaluate.mock.calls.map((args) => String(args[0]));
+        expect(evaluateCalls.some((code) => code.includes('填写作品标题'))).toBe(true);
+        expect(evaluateCalls.some((code) => code.includes('好友可见'))).toBe(true);
+        expect(evaluateCalls.some((code) => code.includes('暂存离开'))).toBe(true);
+        expect(rows).toEqual([
+            {
+                status: '✅ 草稿已保存，可在创作中心继续编辑',
+                draft_id: 'creation-001',
+            },
+        ]);
+    });
+    it('waits for the composer when upload processing is slower than the first few polls', async () => {
+        const cmd = getDraftCommand();
+        const videoPath = createTempVideo('slow.mp4');
+        const page = createPageMock([
+            undefined,
+            { href: 'https://creator.douyin.com/creator-micro/content/upload', ready: false, bodyText: '上传中 42%' },
+            { href: 'https://creator.douyin.com/creator-micro/content/upload', ready: false, bodyText: '转码中' },
+            { href: 'https://creator.douyin.com/creator-micro/content/post/video?enter_from=publish_page', ready: true, bodyText: '' },
+            undefined,
+            true,
+            true,
+            { ok: true, text: '暂存离开', creationId: 'creation-slow' },
+            {
+                href: 'https://creator.douyin.com/creator-micro/content/upload?enter_from=publish',
+                bodyText: '你还有上次未发布的视频，是否继续编辑？继续编辑放弃',
+            },
+        ]);
+        const rows = await cmd.func(page, {
+            video: videoPath,
+            title: '慢上传验证',
+            caption: '',
+            cover: '',
+            visibility: 'public',
+        });
+        expect(rows).toEqual([
+            {
+                status: '✅ 草稿已保存，可在创作中心继续编辑',
+                draft_id: 'creation-slow',
+            },
+        ]);
+        expect(page.wait).toHaveBeenCalledWith({ time: 0.5 });
+        const shortWaitCalls = page.wait.mock.calls.filter(([arg]) => JSON.stringify(arg) === JSON.stringify({ time: 0.5 }));
+        expect(shortWaitCalls).toHaveLength(2);
+    });
+    it('fails fast when the save action does not expose a draft creation id', async () => {
+        const cmd = getDraftCommand();
+        const videoPath = createTempVideo('missing-id.mp4');
+        const page = createPageMock([
+            undefined,
+            { href: 'https://creator.douyin.com/creator-micro/content/post/video?enter_from=publish_page', ready: true, bodyText: '' },
+            undefined,
+            true,
+            true,
+            { ok: true, text: '暂存离开', creationId: '' },
+        ]);
+        await expect(cmd.func(page, {
+            video: videoPath,
+            title: '缺失 creation id',
+            caption: '',
+            cover: '',
+            visibility: 'public',
+        })).rejects.toThrow('点击草稿按钮失败: creation-id-missing');
+    });
+    it('uses the dedicated cover upload input when a custom cover is provided', async () => {
+        const cmd = getDraftCommand();
+        const videoPath = createTempVideo('demo.mp4');
+        const coverPath = createTempCover(videoPath);
+        const page = createPageMock([
+            undefined,
+            { href: 'https://creator.douyin.com/creator-micro/content/post/video?enter_from=publish_page', ready: true, bodyText: '' },
+            undefined,
+            1,
+            { ok: false, reason: 'cover-input-pending' },
+            { ok: true, selector: '[data-opencli-cover-input="1"]' },
+            '快速检测检测中',
+            '快速检测重新检测',
+            true,
+            true,
+            { ok: true, text: '暂存离开', creationId: 'creation-002' },
+            {
+                href: 'https://creator.douyin.com/creator-micro/content/upload?enter_from=publish',
+                bodyText: '你还有上次未发布的视频，是否继续编辑？继续编辑放弃',
+            },
+        ]);
+        const rows = await cmd.func(page, {
+            video: videoPath,
+            title: '封面上传验证',
+            caption: '',
+            cover: coverPath,
+            visibility: 'public',
+        });
+        expect(page.setFileInput).toHaveBeenNthCalledWith(1, [videoPath], 'input[type="file"]');
+        expect(page.setFileInput).toHaveBeenNthCalledWith(2, [coverPath], '[data-opencli-cover-input="1"]');
+        const shortWaitCalls = page.wait.mock.calls.filter(([arg]) => JSON.stringify(arg) === JSON.stringify({ time: 0.5 }));
+        expect(shortWaitCalls).toHaveLength(2);
+        const evaluateCalls = page.evaluate.mock.calls.map((args) => String(args[0]));
+        expect(evaluateCalls.some((code) => code.includes('上传新封面'))).toBe(true);
+        expect(evaluateCalls.some((code) => code.includes("text.includes('快速检测检测')"))).toBe(false);
+        expect(() => {
+            for (const code of evaluateCalls) {
+                new Function(wrapForEval(code));
+            }
+        }).not.toThrow();
+        expect(rows).toEqual([
+            {
+                status: '✅ 草稿已保存，可在创作中心继续编辑',
+                draft_id: 'creation-002',
+            },
+        ]);
+    });
+    it('waits for a late cover-section update before treating the custom cover as ready', async () => {
+        const cmd = getDraftCommand();
+        const videoPath = createTempVideo('cover-race.mp4');
+        const coverPath = createTempCover(videoPath, 'cover-race.jpg');
+        const page = createPageMock([
+            undefined,
+            { href: 'https://creator.douyin.com/creator-micro/content/post/video?enter_from=publish_page', ready: true, bodyText: '' },
+            undefined,
+            1,
+            { ok: true, selector: '[data-opencli-cover-input="1"]' },
+            '快速检测重新检测',
+            '快速检测重新检测',
+            '快速检测重新检测',
+            '快速检测检测中',
+            '快速检测横/竖双封面缺失',
+            true,
+            true,
+            { ok: true, text: '暂存离开', creationId: 'creation-cover-race' },
+            {
+                href: 'https://creator.douyin.com/creator-micro/content/upload?enter_from=publish',
+                bodyText: '你还有上次未发布的视频，是否继续编辑？继续编辑放弃',
+            },
+        ]);
+        const rows = await cmd.func(page, {
+            video: videoPath,
+            title: '封面竞态验证',
+            caption: '',
+            cover: coverPath,
+            visibility: 'public',
+        });
+        expect(rows).toEqual([
+            {
+                status: '✅ 草稿已保存，可在创作中心继续编辑',
+                draft_id: 'creation-cover-race',
+            },
+        ]);
+        const shortWaitCalls = page.wait.mock.calls.filter(([arg]) => JSON.stringify(arg) === JSON.stringify({ time: 0.5 }));
+        expect(shortWaitCalls).toHaveLength(4);
+    });
+    it('accepts the same ready label after cover busy state when the quick-check panel actually transitioned', async () => {
+        const cmd = getDraftCommand();
+        const videoPath = createTempVideo('cover-same-ready.mp4');
+        const coverPath = createTempCover(videoPath, 'cover-same-ready.jpg');
+        const page = createPageMock([
+            undefined,
+            { href: 'https://creator.douyin.com/creator-micro/content/post/video?enter_from=publish_page', ready: true, bodyText: '' },
+            undefined,
+            1,
+            { ok: true, selector: '[data-opencli-cover-input="1"]' },
+            '快速检测重新检测',
+            '快速检测重新检测',
+            '快速检测检测中',
+            '快速检测重新检测',
+            true,
+            true,
+            { ok: true, text: '暂存离开', creationId: 'creation-cover-same-ready' },
+            {
+                href: 'https://creator.douyin.com/creator-micro/content/upload?enter_from=publish',
+                bodyText: '你还有上次未发布的视频，是否继续编辑？继续编辑放弃',
+            },
+        ]);
+        const rows = await cmd.func(page, {
+            video: videoPath,
+            title: '封面同文案验证',
+            caption: '',
+            cover: coverPath,
+            visibility: 'public',
+        });
+        expect(rows).toEqual([
+            {
+                status: '✅ 草稿已保存，可在创作中心继续编辑',
+                draft_id: 'creation-cover-same-ready',
+            },
+        ]);
+        const shortWaitCalls = page.wait.mock.calls.filter(([arg]) => JSON.stringify(arg) === JSON.stringify({ time: 0.5 }));
+        expect(shortWaitCalls).toHaveLength(3);
+    });
+});

package/clis/douyin/drafts.js

@@ -0,0 +1,24 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { browserFetch } from './_shared/browser-fetch.js';
+cli({
+    site: 'douyin',
+    name: 'drafts',
+    access: 'read',
+    description: '获取草稿列表',
+    domain: 'creator.douyin.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'limit', type: 'int', default: 20 },
+    ],
+    columns: ['aweme_id', 'title', 'create_time'],
+    func: async (page, kwargs) => {
+        const url = 'https://creator.douyin.com/web/api/media/aweme/draft/?aid=1128';
+        const res = (await browserFetch(page, 'GET', url));
+        const items = (res.aweme_list ?? []).slice(0, kwargs.limit);
+        return items.map((v) => ({
+            aweme_id: v.aweme_id,
+            title: v.desc,
+            create_time: new Date(v.create_time * 1000).toLocaleString('zh-CN', { timeZone: 'Asia/Tokyo' }),
+        }));
+    },
+});

package/clis/douyin/drafts.test.js

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './drafts.js';
+describe('douyin drafts registration', () => {
+    it('registers the drafts command', () => {
+        const registry = getRegistry();
+        const values = [...registry.values()];
+        const cmd = values.find(c => c.site === 'douyin' && c.name === 'drafts');
+        expect(cmd).toBeDefined();
+    });
+});

package/clis/douyin/hashtag.js

@@ -0,0 +1,114 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { browserFetch } from './_shared/browser-fetch.js';
+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',
+    access: 'read',
+    description: '话题搜索 / AI推荐 / 热点词',
+    domain: 'creator.douyin.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { 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 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);
+            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 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);
+            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 = 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);
+            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: h && 'sentence_id' in h ? h.sentence_id : '',
+                view_count: h?.hot_value ?? 0,
+            }));
+        }
+        throw new ArgumentError(`未知的 action: ${action}`);
+    },
+});

package/clis/douyin/hashtag.test.js

@@ -0,0 +1,171 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+const { browserFetchMock } = vi.hoisted(() => ({
+    browserFetchMock: vi.fn(),
+}));
+vi.mock('./_shared/browser-fetch.js', () => ({
+    browserFetch: browserFetchMock,
+}));
+import { getRegistry } from '@jackwener/opencli/registry';
+import './hashtag.js';
+describe('douyin hashtag', () => {
+    beforeEach(() => {
+        browserFetchMock.mockReset();
+    });
+    it('registers the hashtag command', () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find(c => c.site === 'douyin' && c.name === 'hashtag');
+        expect(cmd).toBeDefined();
+        expect(cmd?.args.some(a => a.name === 'action')).toBe(true);
+    });
+    it('has all expected args', () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find(c => c.site === 'douyin' && c.name === 'hashtag');
+        const argNames = cmd?.args.map(a => a.name) ?? [];
+        expect(argNames).toContain('action');
+        expect(argNames).toContain('keyword');
+        expect(argNames).toContain('cover');
+        expect(argNames).toContain('limit');
+    });
+    it('uses COOKIE strategy', () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find(c => c.site === 'douyin' && c.name === 'hashtag');
+        expect(cmd?.strategy).toBe('cookie');
+    });
+    it('registers action-specific validation so missing args fail before browser pre-navigation', () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        expect(cmd?.validateArgs).toBeTypeOf('function');
+        expect(() => cmd.validateArgs({ action: 'search', keyword: '', cover: '', limit: 10 }))
+            .toThrow(ArgumentError);
+        expect(() => cmd.validateArgs({ action: 'suggest', keyword: '速效救心丸', cover: '', limit: 10 }))
+            .toThrow(ArgumentError);
+        expect(() => cmd.validateArgs({ action: 'hot', keyword: '', cover: '', limit: 10 }))
+            .not.toThrow();
+        expect(browserFetchMock).not.toHaveBeenCalled();
+    });
+
+    it('search throws ArgumentError when --keyword is missing or blank (#1689)', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        await expect(cmd.func({}, { action: 'search', keyword: '', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func({}, { action: 'search', keyword: '   ', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        expect(browserFetchMock).not.toHaveBeenCalled();
+    });
+
+    it('suggest throws ArgumentError when --cover is missing (#1689 root cause)', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        await expect(cmd.func({}, { action: 'suggest', keyword: '速效救心丸', cover: '', limit: 10 }))
+            .rejects.toMatchObject({ code: 'ARGUMENT', message: expect.stringContaining('--cover') });
+        await expect(cmd.func({}, { action: 'suggest', keyword: '', cover: '   ', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        expect(browserFetchMock).not.toHaveBeenCalled();
+    });
+
+    it('hot accepts empty --keyword (it is optional for hot)', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ hotspot_list: [{ sentence: '热点1', hot_value: 100, sentence_id: 'h1' }] });
+        const rows = await cmd.func({}, { action: 'hot', keyword: '', cover: '', limit: 5 });
+        expect(rows[0]).toEqual({ name: '热点1', id: 'h1', view_count: 100 });
+        const url = browserFetchMock.mock.calls[0][2];
+        expect(url).not.toContain('keyword=');
+    });
+
+    it('search threads --keyword + count into the challenge/search URL', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({
+            challenge_list: [{ challenge_info: { cha_name: '美食', cid: '123', view_count: 5000 } }],
+        });
+        const rows = await cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 });
+        expect(rows).toEqual([{ name: '美食', id: '123', view_count: 5000 }]);
+        const url = browserFetchMock.mock.calls[0][2];
+        expect(url).toContain('challenge/search');
+        expect(url).toContain('keyword=' + encodeURIComponent('美食'));
+        expect(url).toContain('count=10');
+    });
+
+    it('suggest threads --cover into the hashtag/rec URL on success', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({
+            hashtag_list: [{ name: '推荐话题', id: 'h99', view_count: 1234 }],
+        });
+        const rows = await cmd.func({}, { action: 'suggest', keyword: '', cover: 'tos-cn-i-cover/abc', limit: 10 });
+        expect(rows).toEqual([{ name: '推荐话题', id: 'h99', view_count: 1234 }]);
+        const url = browserFetchMock.mock.calls[0][2];
+        expect(url).toContain('hashtag/rec');
+        expect(url).toContain('cover_uri=' + encodeURIComponent('tos-cn-i-cover/abc'));
+    });
+
+    it('search throws CommandExecutionError when API returns a non-object payload', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce(null);
+        await expect(cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('search throws CommandExecutionError when challenge_list has wrong shape', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ challenge_list: 'not-an-array' });
+        await expect(cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('search throws CommandExecutionError when challenges return but none parse', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({
+            challenge_list: [{ challenge_info: null }, { other_field: 1 }],
+        });
+        await expect(cmd.func({}, { action: 'search', keyword: '美食', cover: '', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('suggest throws CommandExecutionError when hashtag_list has wrong shape', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ hashtag_list: 'oops' });
+        await expect(cmd.func({}, { action: 'suggest', keyword: '', cover: 'tos-cn-i-cover/x', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('hot throws CommandExecutionError when hotspot_list has wrong shape', async () => {
+        const registry = getRegistry();
+        const cmd = [...registry.values()].find((c) => c.site === 'douyin' && c.name === 'hashtag');
+        browserFetchMock.mockResolvedValueOnce({ hotspot_list: { malformed: true } });
+        await expect(cmd.func({}, { action: 'hot', keyword: '', cover: '', limit: 5 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('parses the current hotspot recommendation shape', async () => {
+        const registry = getRegistry();
+        const command = [...registry.values()].find((cmd) => cmd.site === 'douyin' && cmd.name === 'hashtag');
+        expect(command?.func).toBeDefined();
+        if (!command?.func)
+            throw new Error('douyin hashtag command not registered');
+        browserFetchMock.mockResolvedValueOnce({
+            all_sentences: [
+                {
+                    word: '在公园花海里大晒一场',
+                    hot_value: 12141172,
+                    sentence_id: '2448416',
+                },
+            ],
+        });
+        const rows = await command.func({}, { action: 'hot', keyword: '', limit: 5 });
+        expect(rows).toEqual([
+            {
+                name: '在公园花海里大晒一场',
+                id: '2448416',
+                view_count: 12141172,
+            },
+        ]);
+    });
+});