feat(convention): listing↔detail id pairing rule + CI gate (#1297)

* feat(convention): listing↔detail id pairing rule + CI gate

Adds a hard convention: when a site exposes both a listing-class command
(search / hot / top / recent / ...) and a detail-class command (read /
paper / article / view / ...), every listing row MUST surface an id-shaped
column whose value round-trips into the detail command. Without that, an
agent has no way to follow up on a listing row except re-searching by
title or scraping URLs out of band — both of which break the agent-native
contract.

What's in this PR

- docs/conventions/listing-detail-id-pairing.md — full rule, examples
  table, why-it-matters, what counts as id-shaped, exemption taxonomy,
  how to add an id column to a listing.
- scripts/check-listing-id-pairing.mjs — validator that reads
  cli-manifest.json, classifies each entry as listing / detail / other,
  and fails when a listing on a site that also has a read-detail command
  is missing an id-shaped column. Exemption allowlist records WHY each
  pair is exempt so future maintainers know what to verify.
- npm run check:listing-id-pairing — strict-mode wrapper.
- CI: new step in build job runs the validator after the manifest
  freshness check on Linux.
- docs/developer/ts-adapter.md — cross-link from the adapter authoring
  guide.
- docs/.vitepress/config.mts — sidebar entries for the new conventions
  section.

Fixes brought to zero violations

- 1688/search: add offer_id (already extracted, just surfaced)
- bluesky/user: add uri (AT URI round-trips into bluesky/thread)
- tieba/search: add id + url (thread_id already extracted)
- tieba/hot: add url (rows are topics, not threads — url is the
  best-effort round-trip handle, doc'd as such)

Exemptions (intentional, doc'd in EXEMPT map with rationale)

- nowcoder/hot, bluesky/trending, twitter/trending — listing rows are
  topic strings, not posts.
- lesswrong/user, reddit/user — rows are profile-attribute key/value
  pairs, addressed by the username arg.
- discord-app/search — desktop UI session, message ids not extractable.
- notion/search — Strategy.UI Quick Find, page ids not exposed in DOM.

Validator output after this PR: 32 sites scanned, 75 listings checked,
7 exempted, 0 violations.

* fix(convention): tighten listing id gate

* fix(convention): close url-derived id loophole

Author: jackwener

.github/workflows/ci.yml

@@ -50,6 +50,14 @@ jobs:
             exit 1
           fi
 
+      # Guard: listing-class commands must surface an id-shaped column so their
+      # rows round-trip into the site's detail-class command. Without this, an
+      # agent has to re-search by title or scrape URLs to follow up on a row.
+      # See docs/conventions/listing-detail-id-pairing.md.
+      - name: Check listing↔detail id pairing
+        if: runner.os == 'Linux'
+        run: npm run check:listing-id-pairing
+
   # ── Unit tests (vitest shard) ──
   # PR: ubuntu + Node 22 only (fast feedback, 2 jobs).
   # Push to main/dev: full matrix for cross-platform/cross-version coverage (12 jobs).

cli-manifest.json

@@ -120,6 +120,7 @@
     ],
     "columns": [
       "rank",
+      "offer_id",
       "title",
       "price_text",
       "moq_text",
@@ -2990,6 +2991,7 @@
     ],
     "columns": [
       "rank",
+      "uri",
       "text",
       "likes",
       "reposts",
@@ -8699,6 +8701,7 @@
     ],
     "columns": [
       "rank",
+      "tid",
       "title",
       "url"
     ],
@@ -8883,6 +8886,7 @@
     ],
     "columns": [
       "rank",
+      "tid",
       "title",
       "author",
       "replies",
@@ -10262,6 +10266,7 @@
       }
     ],
     "columns": [
+      "id",
       "author",
       "content",
       "likes",
@@ -10415,6 +10420,7 @@
       }
     ],
     "columns": [
+      "id",
       "author",
       "content",
       "likes",
@@ -10489,6 +10495,7 @@
       }
     ],
     "columns": [
+      "id",
       "content",
       "type",
       "likes",
@@ -16508,7 +16515,8 @@
       "rank",
       "title",
       "discussions",
-      "description"
+      "description",
+      "url"
     ],
     "type": "js",
     "modulePath": "tieba/hot.js",
@@ -16635,10 +16643,12 @@
     ],
     "columns": [
       "rank",
+      "id",
       "title",
       "forum",
       "author",
-      "time"
+      "time",
+      "url"
     ],
     "type": "js",
     "modulePath": "tieba/search.js",
@@ -18764,6 +18774,7 @@
       }
     ],
     "columns": [
+      "id",
       "author",
       "text",
       "reposts",
@@ -18915,6 +18926,7 @@
     ],
     "columns": [
       "rank",
+      "id",
       "title",
       "author",
       "time",

clis/1688/search.js

@@ -294,7 +294,7 @@ cli({
             help: `结果数量上限（默认 ${SEARCH_LIMIT_DEFAULT}，最大 ${SEARCH_LIMIT_MAX}）`,
         },
     ],
-    columns: ['rank', 'title', 'price_text', 'moq_text', 'seller_name', 'location'],
+    columns: ['rank', 'offer_id', 'title', 'price_text', 'moq_text', 'seller_name', 'location'],
     func: async (page, kwargs) => {
         const query = String(kwargs.query ?? '');
         const limit = parseSearchLimit(kwargs.limit);

clis/bluesky/user.js

@@ -16,14 +16,15 @@ cli({
         },
         { name: 'limit', type: 'int', default: 20, help: 'Number of posts' },
     ],
-    columns: ['rank', 'text', 'likes', 'reposts', 'replies'],
+    columns: ['rank', 'uri', 'text', 'likes', 'reposts', 'replies'],
     pipeline: [
         { fetch: {
                 url: 'https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=${{ args.handle }}&limit=${{ args.limit }}',
             } },
         { select: 'feed' },
         { map: {
                 rank: '${{ index + 1 }}',
+                uri: '${{ item.post.uri }}',
                 text: '${{ item.post.record.text }}',
                 likes: '${{ item.post.likeCount }}',
                 reposts: '${{ item.post.repostCount }}',

clis/hupu/hot.js

@@ -8,7 +8,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of hot posts' },
     ],
-    columns: ['rank', 'title', 'url'],
+    columns: ['rank', 'tid', 'title', 'url'],
     pipeline: [
         { navigate: 'https://bbs.hupu.com/' },
         { evaluate: `(async () => {
@@ -33,6 +33,7 @@ cli({
 ` },
         { map: {
                 rank: '${{ index + 1 }}',
+                tid: '${{ item.tid }}',
                 title: '${{ item.title }}',
                 url: 'https://bbs.hupu.com/${{ item.tid }}.html',
             } },

clis/hupu/search.js

@@ -38,7 +38,7 @@ cli({
             help: '排序方式: general/createtime/replytime/light/reply'
         }
     ],
-    columns: ['rank', 'title', 'author', 'replies', 'lights', 'forum', 'url'],
+    columns: ['rank', 'tid', 'title', 'author', 'replies', 'lights', 'forum', 'url'],
     func: async (page, kwargs) => {
         const { query, page: pageNum = 1, limit = 20, forum, sort = 'general' } = kwargs;
         const searchUrl = getHupuSearchUrl(query, pageNum, forum, sort);
@@ -48,6 +48,7 @@ cli({
         // 处理结果：清理HTML标签，解码HTML实体
         const processedResults = results.slice(0, Number(limit)).map((item, index) => ({
             rank: index + 1,
+            tid: String(item.id || ''),
             title: decodeHtmlEntities(stripHtml(item.title)),
             author: item.username || '未知用户',
             replies: item.replies || '0',

clis/jike/feed.js

@@ -17,7 +17,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20 },
     ],
-    columns: ['author', 'content', 'likes', 'comments', 'time', 'url'],
+    columns: ['id', 'author', 'content', 'likes', 'comments', 'time', 'url'],
     func: async (page, kwargs) => {
         const limit = kwargs.limit || 20;
         // 1. 导航到即刻首页，等待 SPA 重定向到 /following
@@ -44,6 +44,7 @@ cli({
           if (!author && !content) continue;
 
           results.push({
+            id: data.id,
             author,
             content: content.replace(/\\n/g, ' ').slice(0, 120),
             likes: data.likeCount || 0,

clis/jike/search.js

@@ -18,7 +18,7 @@ cli({
         { name: 'query', type: 'string', required: true, positional: true },
         { name: 'limit', type: 'int', default: 20 },
     ],
-    columns: ['author', 'content', 'likes', 'comments', 'time', 'url'],
+    columns: ['id', 'author', 'content', 'likes', 'comments', 'time', 'url'],
     func: async (page, kwargs) => {
         const keyword = kwargs.query;
         const limit = kwargs.limit || 20;
@@ -44,6 +44,7 @@ cli({
           if (!author && !content) continue;
 
           results.push({
+            id: data.id,
             author,
             content: content.replace(/\\n/g, ' ').slice(0, 120),
             likes: data.likeCount || 0,

clis/jike/user.js

@@ -16,7 +16,7 @@ cli({
         },
         { name: 'limit', type: 'int', default: 20, help: 'Number of posts' },
     ],
-    columns: ['content', 'type', 'likes', 'comments', 'time', 'url'],
+    columns: ['id', 'content', 'type', 'likes', 'comments', 'time', 'url'],
     pipeline: [
         { navigate: 'https://m.okjike.com/users/${{ args.username }}' },
         { evaluate: `(() => {
@@ -39,6 +39,7 @@ cli({
 })()
 ` },
         { map: {
+                id: '${{ item.id }}',
                 content: '${{ item.content }}',
                 type: '${{ item.type }}',
                 likes: '${{ item.likes }}',

clis/tieba/hot.js

@@ -13,7 +13,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of items to return' },
     ],
-    columns: ['rank', 'title', 'discussions', 'description'],
+    columns: ['rank', 'title', 'discussions', 'description', 'url'],
     func: async (page, kwargs) => {
         const limit = normalizeTiebaLimit(kwargs.limit);
         // Use the default browser settle path so we do not scrape the previous page.