feat(linux-do): refactor adapters with unified feed, tags, user commands (#434)

* feat(linux-do): refactor adapters with unified feed, tags, user commands

- Replace hot/latest/category with unified `feed` command (tag/category/view routing)
- Add `tags`, `user-topics`, `user-posts` commands
- Add static data files for categories and tags lookup
- Fix error handling: use CliError subclasses instead of raw Error
- Fix Discourse API field mapping in search (tags, created)
- Add strategy: cookie to all YAML adapters
- Update docs and README command listings
- Update E2E tests for new command signatures

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* review: resolve linux-do feed from live metadata

* fix: restore linux-do CI

* fix: harden linux-do compatibility

* refactor: stabilize linux-do command migration

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: 3 people

README.md

@@ -164,7 +164,7 @@ Run `opencli list` for the live registry.
 | **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | Browser |
 | **jimeng** | `generate` `history` | Browser |
 | **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | Browser |
-| **linux-do** | `hot` `latest` `search` `categories` `category` `topic` | Public |
+| **linux-do** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | Browser |
 | **stackoverflow** | `hot` `search` `bounties` `unanswered` | Public |
 | **steam** | `top-sellers` | Public |
 | **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | Browser |

README.zh-CN.md

@@ -166,7 +166,7 @@ npm install -g @jackwener/opencli@latest
 | **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | 浏览器 |
 | **jimeng** | `generate` `history` | 浏览器 |
 | **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | 浏览器 |
-| **linux-do** | `hot` `latest` `search` `categories` `category` `topic` | 公开 |
+| **linux-do** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | 浏览器 |
 | **stackoverflow** | `hot` `search` `bounties` `unanswered` | 公开 |
 | **steam** | `top-sellers` | 公开 |
 | **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | 浏览器 |

docs/adapters/browser/linux-do.md

@@ -6,37 +6,198 @@
 
 | Command | Description |
 |---------|-------------|
-| `opencli linux-do hot` | 热门话题 |
-| `opencli linux-do latest` | 最新话题 |
-| `opencli linux-do categories` | 板块列表 |
-| `opencli linux-do category` | 板块话题 |
-| `opencli linux-do search` | 搜索话题 |
-| `opencli linux-do topic` | 话题详情 |
+| `opencli linux-do feed` | Browse topics (site-wide, by tag, or by category) |
+| `opencli linux-do categories` | List all categories |
+| `opencli linux-do tags` | List popular tags |
+| `opencli linux-do search <query>` | Search topics |
+| `opencli linux-do topic <id>` | View topic posts |
+| `opencli linux-do user-topics <username>` | Topics created by a user |
+| `opencli linux-do user-posts <username>` | Replies posted by a user |
 
-## Usage Examples
+## feed
+
+Browse topic listings. Defaults to latest topics when called with no arguments.
+
+- Supports filtering by `--tag`, `--category`, or both
+- `--tag` accepts tag name, slug, or ID
+- `--category` accepts category name, slug, ID, or `Parent / Child` path for sub-categories
+- Use `--view` to switch between latest / hot / top
+
+### Basic
 
 ```bash
-# Hot topics this week
-opencli linux-do hot --limit 20
+# Latest topics (default)
+opencli linux-do feed
+
+# Hot topics
+opencli linux-do feed --view hot
+
+# Top topics — default period is weekly
+opencli linux-do feed --view top
+opencli linux-do feed --view top --period daily
+opencli linux-do feed --view top --period monthly
 
-# Hot topics by period
-opencli linux-do hot --period daily
-opencli linux-do hot --period monthly
+# Sort by views descending
+opencli linux-do feed --order views
+
+# Sort by created time ascending
+opencli linux-do feed --order created --ascending
+
+# Limit results
+opencli linux-do feed --limit 10
+
+# JSON output
+opencli linux-do feed -f json
+```
 
-# Latest topics
-opencli linux-do latest --limit 10
+### Filter by tag
+
+```bash
+# By tag name, slug, or ID — all equivalent
+opencli linux-do feed --tag "ChatGPT"
+opencli linux-do feed --tag chatgpt
+opencli linux-do feed --tag 3
+
+# Tag + hot view
+opencli linux-do feed --tag "ChatGPT" --view hot
+
+# Tag + top view with period
+opencli linux-do feed --tag "OpenAI" --view top --period monthly
+```
+
+### Filter by category
+
+Supports both top-level and sub-categories. Sub-categories auto-resolve their parent path.
+
+```bash
+# Top-level category — name, slug, or ID
+opencli linux-do feed --category "开发调优"
+opencli linux-do feed --category develop
+opencli linux-do feed --category 4
 
-# List all categories
+# Sub-category
+opencli linux-do feed --category "开发调优 / Lv1"
+opencli linux-do feed --category "网盘资源"
+
+# Category + hot / top view
+opencli linux-do feed --category "开发调优" --view hot
+opencli linux-do feed --category "开发调优" --view top --period weekly
+```
+
+### Category + tag
+
+Combine `--category` and `--tag` to narrow results within a category.
+
+```bash
+opencli linux-do feed --category "开发调优" --tag "ChatGPT"
+opencli linux-do feed --category "网盘资源" --tag "OpenAI"
+opencli linux-do feed --category 94 --tag 4 --view top --period monthly
+```
+
+### Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--view V` | `latest`, `hot`, `top` | `latest` |
+| `--tag VALUE` | Tag name, slug, or ID | — |
+| `--category VALUE` | Category name, slug, or ID | — |
+| `--limit N` | Number of results | `20` |
+| `--order O` | `default`, `created`, `activity`, `views`, `posts`, `category`, `likes`, `op_likes`, `posters` | `default` |
+| `--ascending` | Sort ascending instead of descending | off |
+| `--period P` | `all`, `daily`, `weekly`, `monthly`, `quarterly`, `yearly` (only with `--view top`) | `weekly` |
+
+Output columns: `title`, `replies`, `created`, `likes`, `views`, `url`
+
+## categories
+
+List forum categories with optional sub-category expansion.
+
+```bash
 opencli linux-do categories
+opencli linux-do categories --subcategories
+opencli linux-do categories --limit 50
+```
+
+When `--subcategories` is enabled, sub-categories are rendered as `Parent / Child` so the `name` value can be copied directly into `opencli linux-do feed --category ...`.
+
+Output columns: `name`, `slug`, `id`, `topics`, `description`
+
+## tags
 
-# Search topics
+List tags sorted by usage count.
+
+```bash
+opencli linux-do tags
+opencli linux-do tags --limit 50
+```
+
+Output columns: `rank`, `name`, `count`, `url`
+
+## search
+
+Search topics by keyword.
+
+```bash
 opencli linux-do search "NixOS"
+opencli linux-do search "Docker" --limit 10
+opencli linux-do search "Claude" -f json
+```
 
-# View topic details
-opencli linux-do topic 12345
+Output columns: `rank`, `title`, `views`, `likes`, `replies`, `url`
 
-# JSON output
-opencli linux-do hot -f json
+## topic
+
+View posts within a topic (first page).
+
+```bash
+opencli linux-do topic 1234
+opencli linux-do topic 1234 --limit 50
+opencli linux-do topic 1234 --main_only -f json | jq -r '.[0].content'
+```
+
+Notes:
+- `--main_only` returns only the main post row and keeps the body untruncated
+
+Output columns: `author`, `content`, `likes`, `created_at`
+
+## user-topics
+
+List topics created by a user.
+
+```bash
+opencli linux-do user-topics neo
+opencli linux-do user-topics neo --limit 10
+```
+
+Output columns: `rank`, `title`, `replies`, `created_at`, `likes`, `views`, `url`
+
+## user-posts
+
+List replies posted by a user.
+
+```bash
+opencli linux-do user-posts neo
+opencli linux-do user-posts neo --limit 10
+```
+
+Output columns: `index`, `topic_user`, `topic`, `reply`, `time`, `url`
+
+## Compatibility
+
+The legacy commands below are still available as compatibility wrappers while `feed` becomes the canonical entrypoint:
+
+```bash
+opencli linux-do latest
+opencli linux-do hot --period weekly
+opencli linux-do category develop 4
+```
+
+Preferred modern forms:
+
+```bash
+opencli linux-do feed --view latest
+opencli linux-do feed --view top --period weekly
+opencli linux-do feed --category 4
 ```
 
 ## Prerequisites

docs/adapters/index.md

@@ -25,7 +25,7 @@ Run `opencli list` for the live registry.
 | **[jike](/adapters/browser/jike)** | `feed` `search` `post` `topic` `user` `create` `comment` `like` `repost` `notifications` | 🔐 Browser |
 | **[jimeng](/adapters/browser/jimeng)** | `generate` `history` | 🔐 Browser |
 | **[yollomi](/adapters/browser/yollomi)** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | 🔐 Browser |
-| **[linux-do](/adapters/browser/linux-do)** | `hot` `latest` `categories` `category` `search` `topic` | 🔐 Browser |
+| **[linux-do](/adapters/browser/linux-do)** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | 🔐 Browser |
 | **[chaoxing](/adapters/browser/chaoxing)** | `assignments` `exams` | 🔐 Browser |
 | **[grok](/adapters/browser/grok)** | `ask` | 🔐 Browser |
 | **[doubao](/adapters/browser/doubao)** | `status` `new` `send` `read` `ask` | 🔐 Browser |

src/build-manifest.test.ts

@@ -143,4 +143,27 @@ describe('manifest helper rules', () => {
       modulePath: 'xueqiu/fund-holdings.js',
     });
   });
+
+  it('captures deprecated metadata for TS adapters', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
+    tempDirs.push(dir);
+    const file = path.join(dir, 'legacy.ts');
+    fs.writeFileSync(file, `
+      import { cli } from '../../registry.js';
+      cli({
+        site: 'demo',
+        name: 'legacy',
+        description: 'legacy command',
+        deprecated: 'legacy is deprecated',
+        replacedBy: 'opencli demo new',
+      });
+    `);
+
+    expect(scanTs(file, 'demo')).toMatchObject({
+      site: 'demo',
+      name: 'legacy',
+      deprecated: 'legacy is deprecated',
+      replacedBy: 'opencli demo new',
+    });
+  });
 });

src/build-manifest.ts

@@ -38,6 +38,8 @@ export interface ManifestEntry {
   columns?: string[];
   pipeline?: Record<string, unknown>[];
   timeout?: number;
+  deprecated?: boolean | string;
+  replacedBy?: string;
   /** 'yaml' or 'ts' — determines how executeCommand loads the handler */
   type: 'yaml' | 'ts';
   /** Relative path from clis/ dir, e.g. 'bilibili/hot.yaml' or 'bilibili/search.js' */
@@ -199,6 +201,8 @@ function scanYaml(filePath: string, site: string): ManifestEntry | null {
       columns: cliDef.columns,
       pipeline: cliDef.pipeline,
       timeout: cliDef.timeout,
+      deprecated: (cliDef as Record<string, unknown>).deprecated as boolean | string | undefined,
+      replacedBy: (cliDef as Record<string, unknown>).replacedBy as string | undefined,
       type: 'yaml',
       navigateBefore: cliDef.navigateBefore,
     };
@@ -269,6 +273,17 @@ export function scanTs(filePath: string, site: string): ManifestEntry | null {
       if (navStringMatch) entry.navigateBefore = navStringMatch[1];
     }
 
+    const deprecatedBoolMatch = src.match(/deprecated\s*:\s*(true|false)/);
+    if (deprecatedBoolMatch) {
+      entry.deprecated = deprecatedBoolMatch[1] === 'true';
+    } else {
+      const deprecatedStringMatch = src.match(/deprecated\s*:\s*['"`]([^'"`]+)['"`]/);
+      if (deprecatedStringMatch) entry.deprecated = deprecatedStringMatch[1];
+    }
+
+    const replacedByMatch = src.match(/replacedBy\s*:\s*['"`]([^'"`]+)['"`]/);
+    if (replacedByMatch) entry.replacedBy = replacedByMatch[1];
+
     return entry;
   } catch (err) {
     // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.

src/clis/linux-do/categories.yaml

@@ -2,9 +2,14 @@ site: linux-do
 name: categories
 description: linux.do 分类列表
 domain: linux.do
+strategy: cookie
 browser: true
 
 args:
+  subcategories:
+    type: boolean
+    default: false
+    description: Include subcategories
   limit:
     type: int
     default: 20
@@ -20,13 +25,39 @@ pipeline:
         let data;
         try { data = await res.json(); } catch { throw new Error('响应不是有效 JSON - 请先登录 linux.do'); }
         const cats = data?.category_list?.categories || [];
-        return cats.slice(0, ${{ args.limit }}).map(c => ({
-          name: c.name,
-          slug: c.slug,
-          id: c.id,
-          topics: c.topic_count,
-          description: (c.description_text || '').slice(0, 80),
-        }));
+        const showSub = ${{ args.subcategories }};
+        const results = [];
+        const limit = ${{ args.limit }};
+        for (const c of cats.slice(0, ${{ args.limit }})) {
+          results.push({
+            name: c.name,
+            slug: c.slug,
+            id: c.id,
+            topics: c.topic_count,
+            description: (c.description_text || '').slice(0, 80),
+          });
+          if (results.length >= limit) break;
+          if (showSub && c.subcategory_ids && c.subcategory_ids.length > 0) {
+            const subRes = await fetch('/categories.json?parent_category_id=' + c.id, { credentials: 'include' });
+            if (subRes.ok) {
+              let subData;
+              try { subData = await subRes.json(); } catch { continue; }
+              const subCats = subData?.category_list?.categories || [];
+              for (const sc of subCats) {
+                results.push({
+                  name: c.name + ' / ' + sc.name,
+                  slug: sc.slug,
+                  id: sc.id,
+                  topics: sc.topic_count,
+                  description: (sc.description_text || '').slice(0, 80),
+                });
+                if (results.length >= limit) break;
+              }
+            }
+          }
+          if (results.length >= limit) break;
+        }
+        return results;
       })()
 
   - map:
@@ -36,6 +67,4 @@ pipeline:
       topics: ${{ item.topics }}
       description: ${{ item.description }}
 
-  - limit: ${{ args.limit }}
-
 columns: [name, slug, id, topics, description]