@jackwener/opencli 1.3.3 → 1.4.1

package/src/clis/douban/utils.ts

@@ -1,9 +1,173 @@
 /**
- * Douban movie adapter utilities.
+ * Douban adapter utilities.
  */
 
+import { CliError } from '../../errors.js';
 import type { IPage } from '../../types.js';
 
+function clampLimit(limit: number): number {
+  return Math.max(1, Math.min(limit || 20, 50));
+}
+
+async function ensureDoubanReady(page: IPage): Promise<void> {
+  const state = await page.evaluate(`
+    (() => {
+      const title = (document.title || '').trim();
+      const href = (location.href || '').trim();
+      const blocked = href.includes('sec.douban.com') || /登录跳转/.test(title) || /异常请求/.test(document.body?.innerText || '');
+      return { blocked, title, href };
+    })()
+  `);
+  if (state?.blocked) {
+    throw new CliError(
+      'AUTH_REQUIRED',
+      'Douban requires a logged-in browser session before these commands can load data.',
+      'Please sign in to douban.com in the browser that opencli reuses, then rerun the command.',
+    );
+  }
+}
+
+export async function loadDoubanBookHot(page: IPage, limit: number): Promise<any[]> {
+  const safeLimit = clampLimit(limit);
+  await page.goto('https://book.douban.com/chart');
+  await page.wait(4);
+  await ensureDoubanReady(page);
+  const data = await page.evaluate(`
+    (() => {
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const books = [];
+      for (const el of Array.from(document.querySelectorAll('.media.clearfix'))) {
+        try {
+          const titleEl = el.querySelector('h2 a[href*="/subject/"]');
+          const title = normalize(titleEl?.textContent);
+          let url = titleEl?.getAttribute('href') || '';
+          if (!title || !url) continue;
+          if (!url.startsWith('http')) url = 'https://book.douban.com' + url;
+
+          const info = normalize(el.querySelector('.subject-abstract, .pl, .pub')?.textContent);
+          const infoParts = info.split('/').map((part) => part.trim()).filter(Boolean);
+          const ratingText = normalize(el.querySelector('.subject-rating .font-small, .rating_nums, .rating')?.textContent);
+          const quote = Array.from(el.querySelectorAll('.subject-tags .tag'))
+            .map((node) => normalize(node.textContent))
+            .filter(Boolean)
+            .join(' / ');
+
+          books.push({
+            rank: parseInt(normalize(el.querySelector('.green-num-box')?.textContent), 10) || books.length + 1,
+            title,
+            rating: parseFloat(ratingText) || 0,
+            quote,
+            author: infoParts[0] || '',
+            publisher: infoParts.find((part) => /出版社|出版公司|Press/i.test(part)) || infoParts[2] || '',
+            year: infoParts.find((part) => /\\d{4}(?:-\\d{1,2})?/.test(part))?.match(/\\d{4}/)?.[0] || '',
+            price: infoParts.find((part) => /元|USD|\\$|￥/.test(part)) || '',
+            url,
+            cover: el.querySelector('img')?.getAttribute('src') || '',
+          });
+        } catch {}
+      }
+      return books.slice(0, ${safeLimit});
+    })()
+  `);
+  return Array.isArray(data) ? data : [];
+}
+
+export async function loadDoubanMovieHot(page: IPage, limit: number): Promise<any[]> {
+  const safeLimit = clampLimit(limit);
+  await page.goto('https://movie.douban.com/chart');
+  await page.wait(4);
+  await ensureDoubanReady(page);
+  const data = await page.evaluate(`
+    (() => {
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const results = [];
+      for (const el of Array.from(document.querySelectorAll('.item'))) {
+        const titleEl = el.querySelector('.pl2 a');
+        const title = normalize(titleEl?.textContent);
+        let url = titleEl?.getAttribute('href') || '';
+        if (!title || !url) continue;
+        if (!url.startsWith('http')) url = 'https://movie.douban.com' + url;
+
+        const info = normalize(el.querySelector('.pl2 p')?.textContent);
+        const infoParts = info.split('/').map((part) => part.trim()).filter(Boolean);
+        const releaseIndex = (() => {
+          for (let i = infoParts.length - 1; i >= 0; i -= 1) {
+            if (/\\d{4}-\\d{2}-\\d{2}|\\d{4}\\/\\d{2}\\/\\d{2}/.test(infoParts[i])) return i;
+          }
+          return -1;
+        })();
+        const directorPart = releaseIndex >= 1 ? infoParts[releaseIndex - 1] : '';
+        const regionPart = releaseIndex >= 2 ? infoParts[releaseIndex - 2] : '';
+        const yearMatch = info.match(/\\b(19|20)\\d{2}\\b/);
+        results.push({
+          rank: results.length + 1,
+          title,
+          rating: parseFloat(normalize(el.querySelector('.rating_nums')?.textContent)) || 0,
+          quote: normalize(el.querySelector('.inq')?.textContent),
+          director: directorPart.replace(/^导演:\\s*/, ''),
+          year: yearMatch?.[0] || '',
+          region: regionPart,
+          url,
+          cover: el.querySelector('img')?.getAttribute('src') || '',
+        });
+        if (results.length >= ${safeLimit}) break;
+      }
+      return results;
+    })()
+  `);
+  return Array.isArray(data) ? data : [];
+}
+
+export async function searchDouban(page: IPage, type: string, keyword: string, limit: number): Promise<any[]> {
+  const safeLimit = clampLimit(limit);
+  await page.goto(`https://search.douban.com/${encodeURIComponent(type)}/subject_search?search_text=${encodeURIComponent(keyword)}`);
+  await page.wait(2);
+  await ensureDoubanReady(page);
+  const data = await page.evaluate(`
+    (async () => {
+      const type = ${JSON.stringify(type)};
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const seen = new Set();
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+      for (let i = 0; i < 20; i += 1) {
+        if (document.querySelector('.item-root .title-text, .item-root .title a')) break;
+        await sleep(300);
+      }
+
+      const items = Array.from(document.querySelectorAll('.item-root'));
+
+      const results = [];
+      for (const el of items) {
+        const titleEl = el.querySelector('.title-text, .title a, a[title]');
+        const title = normalize(titleEl?.textContent) || normalize(titleEl?.getAttribute('title'));
+        let url = titleEl?.getAttribute('href') || '';
+        if (!title || !url) continue;
+        if (!url.startsWith('http')) url = 'https://search.douban.com' + url;
+        if (!url.includes('/subject/') || seen.has(url)) continue;
+        seen.add(url);
+        const ratingText = normalize(el.querySelector('.rating_nums')?.textContent);
+        const abstract = normalize(
+          el.querySelector('.meta.abstract, .meta, .abstract, p')?.textContent,
+        );
+        results.push({
+          rank: results.length + 1,
+          id: url.match(/subject\\/(\\d+)/)?.[1] || '',
+          type,
+          title,
+          rating: ratingText.includes('.') ? parseFloat(ratingText) : 0,
+          abstract: abstract.slice(0, 100) + (abstract.length > 100 ? '...' : ''),
+          url,
+          cover: el.querySelector('img')?.getAttribute('src') || '',
+        });
+        if (results.length >= ${safeLimit}) break;
+      }
+      return results;
+    })()
+  `);
+  return Array.isArray(data) ? data : [];
+}
+
 /**
  * Get current user's Douban ID from movie.douban.com/mine page
  */

package/src/clis/doubao/ask.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, getDoubaoTranscriptLines, getDoubaoVisibleTurns, sendDoubaoMessage, waitForDoubaoResponse } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoTranscriptLines, getDoubaoVisibleTurns, sendDoubaoMessage, waitForDoubaoResponse } from './utils.js';
 
 export const askCommand = cli({
   site: 'doubao',

package/src/clis/doubao/new.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, startNewDoubaoChat } from './common.js';
+import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, startNewDoubaoChat } from './utils.js';
 
 export const newCommand = cli({
   site: 'doubao',

package/src/clis/doubao/read.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, getDoubaoVisibleTurns } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoVisibleTurns } from './utils.js';
 
 export const readCommand = cli({
   site: 'doubao',

package/src/clis/doubao/send.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, sendDoubaoMessage } from './common.js';
+import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, sendDoubaoMessage } from './utils.js';
 
 export const sendCommand = cli({
   site: 'doubao',

package/src/clis/doubao/status.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, getDoubaoPageState } from './common.js';
+import { DOUBAO_DOMAIN, DOUBAO_CHAT_URL, getDoubaoPageState } from './utils.js';
 
 export const statusCommand = cli({
   site: 'doubao',

package/src/clis/doubao-app/ask.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { SEL, injectTextScript, clickSendScript, pollResponseScript } from './common.js';
+import { SEL, injectTextScript, clickSendScript, pollResponseScript } from './utils.js';
 
 export const askCommand = cli({
   site: 'doubao-app',

package/src/clis/doubao-app/new.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { clickNewChatScript } from './common.js';
+import { clickNewChatScript } from './utils.js';
 
 export const newCommand = cli({
   site: 'doubao-app',

package/src/clis/doubao-app/read.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { readMessagesScript } from './common.js';
+import { readMessagesScript } from './utils.js';
 
 export const readCommand = cli({
   site: 'doubao-app',

package/src/clis/doubao-app/send.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { injectTextScript, clickSendScript } from './common.js';
+import { injectTextScript, clickSendScript } from './utils.js';
 
 export const sendCommand = cli({
   site: 'doubao-app',

package/src/clis/douyin/_shared/browser-fetch.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { IPage } from '../../../types.js';
+import { browserFetch } from './browser-fetch.js';
+
+function makePage(result: unknown): IPage {
+  return {
+    goto: vi.fn(), evaluate: vi.fn().mockResolvedValue(result),
+    getCookies: vi.fn(), snapshot: vi.fn(), click: vi.fn(),
+    typeText: vi.fn(), pressKey: vi.fn(), scrollTo: vi.fn(),
+    getFormState: vi.fn(), wait: vi.fn(), tabs: vi.fn(),
+    closeTab: vi.fn(), newTab: vi.fn(), selectTab: vi.fn(),
+    networkRequests: vi.fn(), consoleMessages: vi.fn(),
+    scroll: vi.fn(), autoScroll: vi.fn(),
+    installInterceptor: vi.fn(), getInterceptedRequests: vi.fn(),
+    screenshot: vi.fn(),
+  } as unknown as IPage;
+}
+
+describe('browserFetch', () => {
+  it('returns parsed JSON on success', async () => {
+    const page = makePage({ status_code: 0, data: { ak: 'KEY' } });
+    const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
+    expect(result).toEqual({ status_code: 0, data: { ak: 'KEY' } });
+  });
+
+  it('throws when status_code is non-zero', async () => {
+    const page = makePage({ status_code: 8, message: 'fail' });
+    await expect(
+      browserFetch(page, 'GET', 'https://creator.douyin.com/api/test')
+    ).rejects.toThrow('Douyin API error 8');
+  });
+
+  it('returns result even when no status_code field', async () => {
+    const page = makePage({ some_field: 'value' });
+    const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
+    expect(result).toEqual({ some_field: 'value' });
+  });
+});

package/src/clis/douyin/_shared/browser-fetch.ts

@@ -0,0 +1,45 @@
+import type { IPage } from '../../../types.js';
+import { CommandExecutionError } from '../../../errors.js';
+
+export interface FetchOptions {
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Execute a fetch() call inside the Chrome browser context via page.evaluate.
+ * This ensures a_bogus signing and cookies are handled automatically by the browser.
+ */
+export async function browserFetch(
+  page: IPage,
+  method: 'GET' | 'POST',
+  url: string,
+  options: FetchOptions = {}
+): Promise<unknown> {
+  const js = `
+    (async () => {
+      const res = await fetch(${JSON.stringify(url)}, {
+        method: ${JSON.stringify(method)},
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+          ...${JSON.stringify(options.headers ?? {})}
+        },
+        ${options.body ? `body: JSON.stringify(${JSON.stringify(options.body)}),` : ''}
+      });
+      return res.json();
+    })()
+  `;
+
+  const result = await page.evaluate(js);
+
+  if (result && typeof result === 'object' && 'status_code' in result) {
+    const code = (result as { status_code: number }).status_code;
+    if (code !== 0) {
+      const msg = (result as { status_msg?: string }).status_msg ?? 'unknown error';
+      throw new CommandExecutionError(`Douyin API error ${code}: ${msg}`);
+    }
+  }
+
+  return result;
+}

package/src/clis/douyin/_shared/creation-id.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { generateCreationId } from './creation-id.js';
+
+describe('generateCreationId', () => {
+  it('starts with "pin"', () => {
+    expect(generateCreationId()).toMatch(/^pin/);
+  });
+
+  it('has 4 random lowercase-alphanumeric chars after "pin"', () => {
+    expect(generateCreationId()).toMatch(/^pin[a-z0-9]{4}/);
+  });
+
+  it('ends with a numeric timestamp (ms)', () => {
+    const before = Date.now();
+    const id = generateCreationId();
+    const after = Date.now();
+    const ts = parseInt(id.replace(/^pin[a-z0-9]{4}/, ''), 10);
+    expect(ts).toBeGreaterThanOrEqual(before);
+    expect(ts).toBeLessThanOrEqual(after);
+  });
+
+  it('generates unique IDs', () => {
+    const ids = new Set(Array.from({ length: 100 }, generateCreationId));
+    expect(ids.size).toBe(100);
+  });
+});

package/src/clis/douyin/_shared/creation-id.ts

@@ -0,0 +1,8 @@
+const CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
+
+export function generateCreationId(): string {
+  const random = Array.from({ length: 4 }, () =>
+    CHARS[Math.floor(Math.random() * CHARS.length)]
+  ).join('');
+  return 'pin' + random + Date.now();
+}

package/src/clis/douyin/_shared/imagex-upload.test.ts

@@ -0,0 +1,113 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { CommandExecutionError } from '../../../errors.js';
+import { imagexUpload } from './imagex-upload.js';
+import type { ImageXUploadInfo } from './imagex-upload.js';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTempImage(ext = '.jpg'): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'imagex-test-'));
+  const filePath = path.join(dir, `cover${ext}`);
+  fs.writeFileSync(filePath, Buffer.from([0xff, 0xd8, 0xff, 0xe0])); // minimal JPEG header bytes
+  return filePath;
+}
+
+const FAKE_UPLOAD_INFO: ImageXUploadInfo = {
+  upload_url: 'https://imagex.bytedance.com/upload/presigned/fake',
+  store_uri: 'tos-cn-i-alisg.example.com/cover/abc123',
+};
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('imagexUpload', () => {
+  let imagePath: string;
+
+  beforeEach(() => {
+    imagePath = makeTempImage('.jpg');
+  });
+
+  afterEach(() => {
+    // Clean up temp files
+    try {
+      fs.unlinkSync(imagePath);
+      fs.rmdirSync(path.dirname(imagePath));
+    } catch {
+      // ignore cleanup errors
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('throws CommandExecutionError when image file does not exist', async () => {
+    await expect(
+      imagexUpload('/nonexistent/path/cover.jpg', FAKE_UPLOAD_INFO),
+    ).rejects.toThrow(CommandExecutionError);
+
+    await expect(
+      imagexUpload('/nonexistent/path/cover.jpg', FAKE_UPLOAD_INFO),
+    ).rejects.toThrow('Cover image file not found');
+  });
+
+  it('PUTs the image and returns store_uri on success', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: vi.fn().mockResolvedValue(''),
+    });
+    vi.stubGlobal('fetch', mockFetch);
+
+    const result = await imagexUpload(imagePath, FAKE_UPLOAD_INFO);
+
+    expect(result).toBe(FAKE_UPLOAD_INFO.store_uri);
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const [url, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(FAKE_UPLOAD_INFO.upload_url);
+    expect(init.method).toBe('PUT');
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe(
+      'image/jpeg',
+    );
+  });
+
+  it('uses image/png Content-Type for .png files', async () => {
+    const pngPath = makeTempImage('.png');
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: vi.fn().mockResolvedValue(''),
+    });
+    vi.stubGlobal('fetch', mockFetch);
+
+    try {
+      await imagexUpload(pngPath, FAKE_UPLOAD_INFO);
+      const [, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+      expect((init.headers as Record<string, string>)['Content-Type']).toBe(
+        'image/png',
+      );
+    } finally {
+      try {
+        fs.unlinkSync(pngPath);
+        fs.rmdirSync(path.dirname(pngPath));
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  it('throws CommandExecutionError on non-2xx PUT response', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      text: vi.fn().mockResolvedValue('Forbidden'),
+    });
+    vi.stubGlobal('fetch', mockFetch);
+
+    await expect(imagexUpload(imagePath, FAKE_UPLOAD_INFO)).rejects.toThrow(
+      CommandExecutionError,
+    );
+    await expect(imagexUpload(imagePath, FAKE_UPLOAD_INFO)).rejects.toThrow(
+      'ImageX upload failed with status 403',
+    );
+  });
+});

package/src/clis/douyin/_shared/imagex-upload.ts

@@ -0,0 +1,76 @@
+/**
+ * ImageX cover image uploader.
+ *
+ * Uploads a JPEG/PNG image to ByteDance ImageX via a pre-signed PUT URL
+ * obtained from the Douyin "apply cover upload" API.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CommandExecutionError } from '../../../errors.js';
+
+export interface ImageXUploadInfo {
+  /** Pre-signed PUT target URL (provided by the apply cover upload API) */
+  upload_url: string;
+  /** Image URI to use in create_v2 (returned from the apply step) */
+  store_uri: string;
+}
+
+/**
+ * Detect MIME type from file extension.
+ * Falls back to image/jpeg for unknown extensions.
+ */
+function detectContentType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case '.png':
+      return 'image/png';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    default:
+      return 'image/jpeg';
+  }
+}
+
+/**
+ * Upload a cover image to ByteDance ImageX via a pre-signed PUT URL.
+ *
+ * @param imagePath - Local file path to the image (JPEG/PNG/etc.)
+ * @param uploadInfo - Upload URL and store_uri from the apply cover upload API
+ * @returns The store_uri (= image_uri for use in create_v2)
+ */
+export async function imagexUpload(
+  imagePath: string,
+  uploadInfo: ImageXUploadInfo,
+): Promise<string> {
+  if (!fs.existsSync(imagePath)) {
+    throw new CommandExecutionError(
+      `Cover image file not found: ${imagePath}`,
+      'Ensure the file path is correct and accessible.',
+    );
+  }
+
+  const imageBuffer = fs.readFileSync(imagePath);
+  const contentType = detectContentType(imagePath);
+
+  const res = await fetch(uploadInfo.upload_url, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': contentType,
+      'Content-Length': String(imageBuffer.byteLength),
+    },
+    body: imageBuffer as unknown as BodyInit,
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new CommandExecutionError(
+      `ImageX upload failed with status ${res.status}: ${body}`,
+      'Check that the upload URL is valid and has not expired.',
+    );
+  }
+
+  return uploadInfo.store_uri;
+}

package/src/clis/douyin/_shared/sts2.ts

@@ -0,0 +1,20 @@
+import type { IPage } from '../../../types.js';
+import type { Sts2Credentials } from './types.js';
+import { AuthRequiredError } from '../../../errors.js';
+
+const STS2_URL =
+  'https://creator.douyin.com/aweme/mid/video/sts2/?scene=web&aid=1128&cookie_enabled=true&device_platform=web';
+
+/**
+ * Fetch STS2 temporary credentials from the creator center.
+ * These are used to authenticate Node.js-side TOS multipart uploads.
+ * Returns: { access_key_id, secret_access_key, session_token, expired_time }
+ */
+export async function getSts2Credentials(page: IPage): Promise<Sts2Credentials> {
+  const js = `fetch(${JSON.stringify(STS2_URL)}, { credentials: 'include' }).then(r => r.json())`;
+  const res = await page.evaluate(js) as { data: Sts2Credentials };
+  if (!res?.data?.access_key_id) {
+    throw new AuthRequiredError('creator.douyin.com', 'STS2 credentials missing');
+  }
+  return res.data;
+}

package/src/clis/douyin/_shared/text-extra.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { parseTextExtra, extractHashtagNames, type HashtagInfo } from './text-extra.js';
+
+describe('parseTextExtra', () => {
+  it('returns empty array for text with no hashtags', () => {
+    const result = parseTextExtra('普通文本内容', []);
+    expect(result).toEqual([]);
+  });
+
+  it('produces type-1 entry for each hashtag', () => {
+    const hashtags: HashtagInfo[] = [
+      { name: '话题', id: 12345, start: 5, end: 8 },
+    ];
+    const result = parseTextExtra('普通文本 #话题', hashtags);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      type: 1,
+      hashtag_name: '话题',
+      hashtag_id: 12345,
+      start: 5,
+      end: 8,
+    });
+  });
+
+  it('sets hashtag_id to 0 when not found', () => {
+    const hashtags: HashtagInfo[] = [
+      { name: '未知话题', id: 0, start: 0, end: 5 },
+    ];
+    const result = parseTextExtra('#未知话题', hashtags);
+    expect(result[0].hashtag_id).toBe(0);
+  });
+});
+
+describe('extractHashtagNames', () => {
+  it('extracts hashtag names from text', () => {
+    expect(extractHashtagNames('hello #foo and #bar')).toEqual(['foo', 'bar']);
+  });
+
+  it('returns empty array when no hashtags', () => {
+    expect(extractHashtagNames('no hashtags here')).toEqual([]);
+  });
+});

package/src/clis/douyin/_shared/text-extra.ts

@@ -0,0 +1,33 @@
+export interface HashtagInfo {
+  name: string;
+  id: number;
+  start: number;
+  end: number;
+}
+
+export interface TextExtraItem {
+  type: number;
+  hashtag_id: number;
+  hashtag_name: string;
+  start: number;
+  end: number;
+  caption_start: number;
+  caption_end: number;
+}
+
+export function parseTextExtra(_text: string, hashtags: HashtagInfo[]): TextExtraItem[] {
+  return hashtags.map((h) => ({
+    type: 1,
+    hashtag_id: h.id,
+    hashtag_name: h.name,
+    start: h.start,
+    end: h.end,
+    caption_start: 0,
+    caption_end: h.end - h.start,
+  }));
+}
+
+/** Extract hashtag names from text (e.g. "#话题" → ["话题"]) */
+export function extractHashtagNames(text: string): string[] {
+  return [...text.matchAll(/#([^\s#]+)/g)].map((m) => m[1]);
+}