pixivflow 3.0.3 → 3.2.0

package/dist/topic/TopicPipeline.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicPipeline = void 0;
+exports.seedFallbackTag = seedFallbackTag;
+exports.selectWalkedTags = selectWalkedTags;
+exports.recallChannels = recallChannels;
 const promises_1 = require("node:timers/promises");
 const logger_1 = require("../logger");
 const pixiv_utils_1 = require("../utils/pixiv-utils");
@@ -14,6 +17,105 @@ const STOP_TAGS = new Set([
     '1000users入り', '5000users入り', '10000users入り', '500users入り', '100users入り',
     'pixiv', 'commission', 'skeb', '依頼絵', '仕事絵',
 ]);
+/** Normalization shared by the tag-relation filter and the pipeline itself. */
+function normalizeKey(value) {
+    return value.trim().normalize('NFKC').toLocaleLowerCase();
+}
+/**
+ * The tag the operator asked for, even when `tagRelations` filters it out.
+ *
+ * `deny` may drop the seed, but a space filtered down to nothing must still be
+ * usable: the pipeline then falls back to the seed tag alone, exactly like the
+ * resolver's `seedOnly()` degradation. `weight` defaults to the tag's `score`
+ * for spaces persisted before provenance existed.
+ */
+function seedFallbackTag(seedTag) {
+    if (seedTag.source === 'seed' && seedTag.weight !== undefined)
+        return seedTag;
+    return { ...seedTag, source: 'seed', weight: seedTag.weight ?? seedTag.score, seed: true };
+}
+/**
+ * Applies `topicDiscovery.tagRelations` to a resolved space (§tag-provenance).
+ *
+ * Deny beats allow, and deny is the only thing that can drop the seed tag. A
+ * tag whose provenance is unknown (a space persisted before `source` existed, or
+ * a hand-written space) is treated as `cooccurrence` so that `allowSources` can
+ * still narrow it while the default (all sources) keeps walking everything.
+ */
+function selectWalkedTags(tags, seedKey, relations = {}) {
+    const seedTag = tags.find((tag) => normalizeKey(tag.name) === seedKey);
+    const allowed = tags.filter((tag) => normalizeKey(tag.name) !== seedKey);
+    const deny = (relations.deny ?? []).map(normalizeKey);
+    const deniedKeys = new Set(deny);
+    const seedDenied = seedTag !== undefined && deniedKeys.has(seedKey);
+    if (seedDenied)
+        deniedKeys.clear(); // the seed fallback ignores deny
+    const allow = (relations.allow ?? []).map(normalizeKey);
+    const allowKeys = new Set(allow);
+    const open = allowKeys.size === 0;
+    const sources = relations.allowSources;
+    const sourceAllowed = (tag) => {
+        if (!sources || sources.length === 0)
+            return true;
+        const name = normalizeKey(tag.name);
+        if (allowKeys.has(name))
+            return true; // an explicit allow beats allowSources
+        const provenance = tag.source;
+        if (provenance === undefined)
+            return sources.includes('cooccurrence');
+        if (provenance === 'cooccurrence+autocomplete') {
+            return sources.includes('cooccurrence') || sources.includes('autocomplete');
+        }
+        return sources.includes(provenance);
+    };
+    const walked = allowed.filter((tag) => {
+        const name = normalizeKey(tag.name);
+        if (deniedKeys.has(name))
+            return false;
+        if (!open && !allowKeys.has(name))
+            return false;
+        return sourceAllowed(tag);
+    });
+    // No seed tag in the space at all: there is nothing to dominate, so fall back
+    // to walking the whole (filtered) space — the pre-provenance behaviour.
+    if (!seedTag)
+        return walked;
+    // A denied seed empties the space, exactly like the resolver's seedOnly():
+    // the operator still gets their own topic, and no related tag is walked.
+    if (seedDenied)
+        return [seedFallbackTag(seedTag)];
+    return [seedTag, ...walked];
+}
+/** Every spelling under which a set of resolved tags can be recognized. */
+function buildTagAliases(tags, matchTranslatedNames) {
+    const aliases = new Map();
+    for (const tag of tags) {
+        const primary = normalizeKey(tag.name);
+        const entry = { primary, weight: tag.weight ?? tag.score };
+        if (!aliases.has(primary))
+            aliases.set(primary, entry);
+        if (!matchTranslatedNames)
+            continue;
+        // The work-side `translated_name` for this tag is the same resolved tag: the
+        // space still exposes one tag, it is simply recognized under two keys.
+        const translated = tag.translatedName ? normalizeKey(tag.translatedName) : '';
+        if (translated && !aliases.has(translated))
+            aliases.set(translated, entry);
+    }
+    return aliases;
+}
+/** Which of the walked tags a `relatedTags` mode will actually search today. */
+function recallChannels(walked, seedKey, relatedMode) {
+    const seedTags = walked.filter((tag) => normalizeKey(tag.name) === seedKey);
+    // A space with no seed tag has nothing to protect: every remaining tag is the
+    // only channel there is, so the whole space is walked whatever the mode
+    // (pre-provenance fallback for a hand-written space).
+    if (seedTags.length === 0)
+        return [...walked];
+    if (relatedMode === 'never' || relatedMode === 'when_seed_insufficient')
+        return seedTags;
+    return [...seedTags, ...walked.filter((tag) => normalizeKey(tag.name) !== seedKey)];
+}
 /**
  * Resolves a topic to a tag space, collects that day's works across the tags,
  * filters by lightweight metadata relevance and ranks by local popularity, then
@@ -42,7 +144,6 @@ class TopicPipeline {
     async selectWorks(target, contentType, day, limit, discovery, collect) {
         const topic = (target.topic ?? '').trim();
         const { space } = await this.resolver.resolve(topic, contentType, discovery);
-        const tagScores = new Map(space.tags.map((t) => [this.key(t.name), t.score]));
         const maxPerTag = this.bound(collect.maxPerTag, COLLECT_DEFAULTS.maxPerTag, 5, 100);
         const maxCandidates = this.bound(collect.maxCandidates, COLLECT_DEFAULTS.maxCandidates, 20, 500);
         const minMetadataScore = collect.minMetadataScore ?? COLLECT_DEFAULTS.minMetadataScore;
@@ -55,11 +156,22 @@ class TopicPipeline {
         let rawCount = 0;
         let aiExcludedCount = 0;
         let duplicateRemovedCount = 0;
-        const tagNames = space.tags.map((t) => t.name);
         const seedKey = this.key(topic);
+        // §tag-provenance: apply tagRelations where the walked list is built, so the
+        // filter governs seedTags/relatedTags BEFORE any search is issued. The seed
+        // tag survives allow/allowSources; a deny entry that empties the space falls
+        // back to the seed tag alone, exactly like the resolver's seedOnly().
+        const matchTranslatedNames = discovery.matchTranslatedNames === true;
+        const walked = selectWalkedTags(space.tags, seedKey, discovery.tagRelations);
+        const tagNames = walked.map((t) => t.name);
         const seedTags = tagNames.filter((name) => this.key(name) === seedKey);
         const relatedTags = tagNames.filter((name) => this.key(name) !== seedKey);
+        // Ranking reads the documented semantic weight, falling back to `score` for
+        // spaces persisted before provenance existed. The two are always equal.
+        const tagScores = buildTagAliases(walked, matchTranslatedNames);
         const searchedTags = [];
+        // A hard seed tier: 'on' always, and the seed-first modes keep their layer.
+        const hardSeedTier = discovery.seedTier === 'on' || relatedMode !== 'always';
         const collectTag = async (tag) => {
             // Cancellation is checked between tags, so a cancelled run stops issuing
             // new searches even when the aborted request itself had already returned.
@@ -100,11 +212,11 @@ class TopicPipeline {
         if (seedTags.length === 0 || relatedMode === 'always') {
             // No seed tag in the space (hand-written space): keep walking everything
             // rather than returning nothing.
-            await runTags(seedTags.length === 0 ? tagNames : [...seedTags, ...relatedTags]);
+            await runTags(recallChannels(walked, seedKey, relatedMode).map((t) => t.name));
         }
         else {
             await runTags(seedTags);
-            const seedAccepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType).length;
+            const seedAccepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames).length;
             if (relatedMode === 'never') {
                 logger_1.logger.info('[TopicRecall] mode=never tag=' + topic + ' day=' + day + ' accepted=' + seedAccepted);
             }
@@ -118,19 +230,19 @@ class TopicPipeline {
         }
         const dedupedCount = byId.size;
         logger_1.logger.info('[TopicCollector] type=' + contentType + ' raw=' + rawCount + ' deduplicated=' + dedupedCount + ' aiExcluded=' + aiExcludedCount + ' searchedTags=' + searchedTags.length);
-        const accepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType);
-        const chosen = this.topByPopularity(accepted, limit, relatedMode === 'always' ? undefined : seedKey);
+        const accepted = this.acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames);
+        const chosen = this.topByPopularity(accepted, limit, hardSeedTier ? seedKey : undefined);
         const selected = chosen.map((e) => e.candidate);
         logger_1.logger.info('[MetadataTopicFilter] accepted=' + accepted.length);
         if (selected[0]) {
-            logger_1.logger.info('[PopularityRanker] selected=' + selected[0].id + ' popularity=' + selected[0].popularity.toFixed(1) + ' meta=' + selected[0].metadataScore.toFixed(2) + ' title=' + selected[0].title);
+            logger_1.logger.info('[PopularityRanker] selected=' + selected[0].id + ' popularity=' + selected[0].popularity.toFixed(1) + ' meta=' + selected[0].metadataScore.toFixed(2) + (hardSeedTier ? ' seedTier=on' : '') + ' title=' + selected[0].title);
         }
         return {
             works: chosen.map((e) => e.work),
             selection: {
                 candidates: [...byId.values()].map((e) => e.candidate),
                 selected,
-                resolvedTagCount: space.tags.length,
+                resolvedTagCount: walked.length,
                 searchedTags,
                 rawCount,
                 dedupedCount,
@@ -163,12 +275,16 @@ class TopicPipeline {
     }
     toCandidate(work, type) {
         const popularity = (0, pixiv_utils_1.calculatePopularityScore)(work);
+        const translatedTags = (work.tags ?? [])
+            .map((t) => t.translated_name)
+            .filter((name) => Boolean(name));
         return {
             id: work.id,
             type,
             title: work.title ?? '',
             caption: work.caption ?? '',
             tags: (work.tags ?? []).map((t) => t.name).filter(Boolean),
+            ...(translatedTags.length > 0 ? { translatedTags } : {}),
             bookmarks: Number(work.total_bookmarks ?? work.bookmark_count ?? 0) || 0,
             views: Number(work.total_view ?? work.view_count ?? 0) || 0,
             popularity,
@@ -184,16 +300,23 @@ class TopicPipeline {
      * the seed pass can be evaluated before deciding whether the related channel
      * is needed at all (§topic-recall).
      */
-    acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType) {
+    acceptedWorks(byId, seedKey, tagScores, minMetadataScore, limit, contentType, matchTranslatedNames) {
         const accepted = [];
+        const hitsSeed = (candidate) => {
+            if (candidate.tags.some((t) => this.key(t) === seedKey))
+                return true;
+            if (!matchTranslatedNames)
+                return false;
+            return (candidate.translatedTags ?? []).some((t) => this.key(t) === seedKey);
+        };
         for (const entry of byId.values()) {
-            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores);
+            entry.candidate.metadataScore = this.metadataScore(entry.candidate, seedKey, tagScores, matchTranslatedNames);
             if (entry.candidate.metadataScore >= minMetadataScore)
                 accepted.push(entry);
         }
         if (accepted.length === 0 && byId.size > 0) {
             const fallback = [...byId.values()]
-                .filter((e) => e.candidate.tags.some((t) => this.key(t) === seedKey))
+                .filter((e) => hitsSeed(e.candidate))
                 .sort((a, b) => b.candidate.popularity - a.candidate.popularity);
             accepted.push(...fallback.slice(0, Math.max(limit, 1)));
             logger_1.logger.warn('[MetadataTopicFilter] type=' + contentType + ' none above threshold ' + minMetadataScore + '; kept ' + accepted.length + ' seed-tag fallback');
@@ -204,25 +327,49 @@ class TopicPipeline {
      * Lightweight metadata relevance. Tags dominate (Pixiv's own taxonomy);
      * title/caption add smaller boosts. The seed tag is strong evidence.
      * No text model — case/symbol-insensitive substring matching only.
+     *
+     * `matchTranslatedNames` (default false) additionally counts a work's
+     * `translated_name` as a hit for the resolved tag it translates to, so a
+     * topic written in one language can still match works tagged in another. The
+     * translated name is matched against the resolved space — never added to
+     * `candidate.tags` — so the work is not reported as carrying a tag it lacks.
+     *
+     * A resolved tag counts at most ONCE per work, whether it matched through the
+     * tag name or through its translation (and a work that repeats a tag, as Pixiv
+     * payloads do for a tag plus its translation, does not double its weight).
      */
-    metadataScore(candidate, seedKey, tagScores) {
+    metadataScore(candidate, seedKey, tagScores, matchTranslatedNames) {
         let seedHit = false;
         let relatedSum = 0;
         let relatedHits = 0;
-        for (const tag of candidate.tags) {
-            const k = this.key(tag);
-            if (STOP_TAGS.has(k))
-                continue;
-            if (k === seedKey) {
+        let strongRelated = false;
+        // A resolved tag is matched through its own name, and — when the caller
+        // opted in — through the work-side translation of that tag. Either spelling
+        // maps back to the SAME resolved tag, so a work carrying both spellings
+        // counts once and never gets a double weight.
+        const countedTagKeys = new Set();
+        const consider = (candidateKey) => {
+            if (candidateKey === '' || STOP_TAGS.has(candidateKey))
+                return;
+            if (candidateKey === seedKey) {
                 seedHit = true;
-                continue;
-            }
-            const related = tagScores.get(k);
-            if (related !== undefined) {
-                relatedSum += Math.min(related, 0.6);
-                relatedHits += 1;
+                return;
             }
+            const aliases = tagScores.get(candidateKey);
+            if (!aliases || countedTagKeys.has(aliases.primary))
+                return;
+            countedTagKeys.add(aliases.primary);
+            relatedSum += Math.min(aliases.weight, 0.6);
+            relatedHits += 1;
+            if (aliases.weight >= 0.6)
+                strongRelated = true;
+        };
+        if (matchTranslatedNames) {
+            for (const tag of candidate.translatedTags ?? [])
+                consider(this.key(tag));
         }
+        for (const tag of candidate.tags)
+            consider(this.key(tag));
         const hayTitle = this.normalize(candidate.title);
         const hayCaption = this.normalize(candidate.caption);
         const titleSeed = !!seedKey && hayTitle.includes(seedKey);
@@ -239,7 +386,6 @@ class TopicPipeline {
         // deliberately does NOT clear the bar, so a hugely popular tangential work
         // cannot crowd out core topic works.
         let score = 0;
-        const strongRelated = [...tagScores.entries()].some(([k, w]) => w >= 0.6 && candidate.tags.some((t) => this.key(t) === k));
         if (titleSeed)
             score += 0.8;
         if (captionSeed)
@@ -256,12 +402,13 @@ class TopicPipeline {
      * alone. A work with a higher metadata score does NOT outrank a more popular
      * accepted work.
      *
-     * `seedKey` adds a single tier in front of that popularity order and is only
-     * passed by the seed-first recall modes (§topic-recall): when related tags
-     * were reached as a fallback, a work that actually carries the topic tag must
-     * outrank a related-only work, and popularity decides within each tier. The
-     * default mode passes no `seedKey`, so the documented popularity-only ranking
-     * is unchanged.
+     * `seedKey` adds a single tier in front of that popularity order and is
+     * passed by the seed-first recall modes (§topic-recall) and by
+     * `topicDiscovery.seedTier: 'on'` (§tag-provenance): a work that actually
+     * carries the topic tag outranks a related-only work, however popular the
+     * latter is, and popularity decides within each tier. With `seedTier: 'off'`
+     * and the default `relatedTags: 'always'` no `seedKey` is passed, so the
+     * documented popularity-only ranking is unchanged.
      */
     popCompare(a, b) {
         return b.popularity - a.popularity;

package/dist/topic/TopicResolver.js

@@ -97,6 +97,9 @@ class TopicResolver {
             name: seed,
             translatedName: suggested.find((t) => this.scorer.key(t.name) === this.scorer.key(seed))?.translated_name,
             score: 1,
+            weight: 1,
+            // The tag the operator asked for: the strongest provenance, never a hint.
+            source: 'seed',
             occurrences: topicWorks.length,
             coverage: 1,
             specificity: 1,
@@ -168,7 +171,7 @@ class TopicResolver {
             expiresAt: new Date(now + cacheDays * 24 * 60 * 60_000).toISOString(),
             sampleSize: 0,
             sampledWorks: 0,
-            tags: [{ name: seed, score: 1, occurrences: 0, coverage: 1, specificity: 1, suggested: false, seed: true }],
+            tags: [{ name: seed, score: 1, weight: 1, source: 'seed', occurrences: 0, coverage: 1, specificity: 1, suggested: false, seed: true }],
         };
     }
     ageDays(space) {

package/dist/topic/TopicTagScorer.js

@@ -99,10 +99,17 @@ class TopicTagScorer {
             const suggestionWeight = stat.suggested ? 1.1 : 1.0;
             const genericPenalty = GENERIC_TAG_PENALTY.has(k) ? 0.4 : 1.0;
             const raw = recall * specificity * suggestionWeight * genericPenalty;
+            const score = Number(raw.toFixed(4));
             resolved.push({
                 name: stat.name,
                 translatedName: stat.translatedName,
-                score: Number(raw.toFixed(4)),
+                score,
+                // `weight` is the same semantic number; ranking and diagnostics read it
+                // while `score` stays for backward compatibility (§tag-provenance).
+                weight: score,
+                // Both channels may agree on a tag; the combined provenance records
+                // that, which is strictly more informative than either alone.
+                source: stat.suggested ? 'cooccurrence+autocomplete' : 'cooccurrence',
                 occurrences: stat.topicDocs,
                 coverage: Number(coverage.toFixed(4)),
                 specificity: Number(specificity.toFixed(4)),
@@ -127,6 +134,10 @@ class TopicTagScorer {
                 name: name,
                 translatedName: sug.translated_name?.trim() || undefined,
                 score: AUTOCOMPLETE_ONLY_SCORE,
+                weight: AUTOCOMPLETE_ONLY_SCORE,
+                // Pixiv autocomplete is the only evidence for this tag: it never
+                // co-occurred in the bounded sample.
+                source: 'autocomplete',
                 occurrences: 0,
                 coverage: 0,
                 specificity: 1.0, // Pixiv-endorsed related; treated as specific but unobserved

package/dist/topic/types.d.ts

@@ -4,12 +4,34 @@
  * local models are used anywhere in this module.
  */
 export type TopicContentType = 'illustration' | 'novel';
+/**
+ * Where a resolved tag came from. Provenance is what lets a caller treat a weak
+ * expansion differently from the topic it was asked for (§tag-provenance):
+ *
+ * - `'seed'`: the tag the operator asked for. Always the strongest key.
+ * - `'cooccurrence'`: sampled together with the seed, but Pixiv autocomplete
+ *   does not relate it to the seed. Co-occurrence evidence only.
+ * - `'autocomplete'`: Pixiv autocomplete relates it to the seed, but it never
+ *   appeared in the sample. No co-occurrence evidence.
+ * - `'cooccurrence+autocomplete'`: both channels agree — the strongest related
+ *   provenance available.
+ */
+export type TagSource = 'seed' | 'cooccurrence' | 'autocomplete' | 'cooccurrence+autocomplete';
 /** A single related tag with a 0..1 relatedness score and provenance. */
 export interface ResolvedTag {
     name: string;
     translatedName?: string;
     /** Combined relatedness score (co-occurrence * specificity * suggestion). */
     score: number;
+    /**
+     * Semantic weight used for ranking, filtering and diagnostics. Always the
+     * same number as `score`; kept as a separate, documented field so ranking can
+     * be explained (and, later, adjusted) without redefining `score`.
+     * Optional: spaces persisted before provenance existed have neither field.
+     */
+    weight?: number;
+    /** Provenance of the tag. Optional for the same reason as `weight`. */
+    source?: TagSource;
     /** How many sampled works (of the seed search) carried this tag. */
     occurrences: number;
     /** Coverage of the sampled seed works (occurrences / sample size). */
@@ -57,6 +79,26 @@ export interface TopicDiscoveryOptions {
      * `'never'` searches the seed tag alone.
      */
     relatedTags?: RelatedTagMode;
+    /**
+     * Which resolved tags may become recall channels (§tag-provenance). Deny wins
+     * over allow; the seed tag is never dropped by `allow`/`allowSources`.
+     */
+    tagRelations?: TopicRelationsOptions;
+    /** Make the seed tag a hard ranking tier (default `'off'`). */
+    seedTier?: 'off' | 'on';
+    /** Count a work's translated tag names as tag hits (default false). */
+    matchTranslatedNames?: boolean;
+}
+/**
+ * Runtime shape of `TopicDiscoveryConfig.tagRelations`, declared here so the
+ * topic module does not depend on the config layer (the topic pipeline is also
+ * driven by hand-written targets in tests and by callers that never load a
+ * config file).
+ */
+export interface TopicRelationsOptions {
+    allowSources?: TagSource[];
+    allow?: string[];
+    deny?: string[];
 }
 export interface TopicCollectOptions {
     maxPerTag?: number;
@@ -76,6 +118,12 @@ export interface TopicCandidate {
     popularity: number;
     /** Metadata topic-relevance score computed by the filter stage. */
     metadataScore: number;
+    /**
+     * Translated tag names carried by the work, kept beside `tags` so
+     * `matchTranslatedNames` can compare them WITHOUT claiming the work itself
+     * carries a tag it does not (§tag-provenance). Default-off.
+     */
+    translatedTags?: string[];
     /** Pixiv AI classification copied from illustration search metadata. */
     aiType?: number;
 }

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILD = void 0;
 // GENERATED by scripts/write-version.js — do not edit manually.
-exports.BUILD = { version: '3.0.3', commit: 'b01a93d49e63' };
+exports.BUILD = { version: '3.2.0', commit: 'c195b909063c' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow-webui-backend",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "PixivFlow WebUI Backend - CommonJS module"
 }

package/examples/gateway/README.md

@@ -85,6 +85,10 @@ npx jest src/__tests__/delivery/gateway-reference-e2e.test.ts
 重启后带同一个 `idempotencyKey` 收敛；一条坏路由的失败不会影响另一条。写自己的网关时，
 让这个文件继续通过就是「你接对了」的最强证据。
 
+接平台那一步请用 [`examples/onebot-adapter/`](../onebot-adapter/README.md)：它是本节所述
+「最小转换进程」的可运行实例（QQ / OneBot v11），同样零依赖、同样不实现 QQ 协议。本参考网关
+与它是**互补**关系：一个证明「契约本身通不通」，另一个证明「平台映射写对了没有」。
+
 ## 它有意不做什么
 
 - 不保存任何东西到磁盘（去重表在内存里，进程重启即丢）—— 生产网关必须持久化，

package/examples/onebot-adapter/README.md

@@ -0,0 +1,139 @@
+# Example OneBot v11 adapter（QQ）
+
+一个**零依赖**的 OneBot v11 投递适配器，把 [Gateway Contract v1](../../docs/GATEWAY_CONTRACT.md)
+的三个端点翻译成 OneBot v11 的 HTTP API 调用。它是 [docs/GATEWAY.md](../../docs/GATEWAY.md) §5.3
+所描述的「最小转换进程」的**可运行实例**。
+
+```
+PixivFlow ──POST /deliver（契约 v1，带签名/幂等键）──▶ 本进程
+                                                      │ POST /send_group_msg
+                                                      ▼
+                                  NapCat / Lagrange / LLOneBot ──▶ QQ
+```
+
+## 它不是什么
+
+- **不实现 QQ 协议**，也不实现 OneBot 本身：QQ 会话属于你已经在跑的 OneBot 实现。
+- **不做扫码登录**：二维码由 NapCat 自己的面板显示，凭据不会经过本进程，也不会经过 PixivFlow
+  （见 GATEWAY.md §5.1/§5.2）。
+- **不做重试**：重试由 PixivFlow 的 outbox 负责；本进程只负责把一次请求翻译成一次 OneBot 调用，
+  并把「成功 / 待定 / 永久失败」如实翻译回契约词汇。
+- **不按平台长分支**：这就是适配器独立成进程的原因 —— PixivFlow 侧的契约里没有 QQ。
+
+只想先验证「契约本身通不通」、还不想碰 QQ，请先用
+[`examples/gateway/`](../gateway/README.md)（它只打印消息，不接平台）。
+
+## 跑起来
+
+```bash
+# 1. 先让 NapCat（或其它 OneBot v11 实现）的 HTTP API 在 3000 端口可用，并记下它的 token
+# 2. 起适配器
+ONEBOT_URL=http://127.0.0.1:3000 \
+ONEBOT_TOKEN=<napcat-token> \
+ONEBOT_TARGET=group:987654 \
+ADAPTER_TOKEN=<给 PixivFlow 用的 token> \
+node examples/onebot-adapter/server.mjs
+
+# 自检：起一个假 OneBot，跑完三个端点与去重逻辑，打印结果并退出（0 = 通过）
+node examples/onebot-adapter/server.mjs --selftest
+```
+
+启动时会拒绝「半配置」：`ONEBOT_URL` 缺失或 `ONEBOT_TARGET` 还是占位值 `group:0` 时，
+进程会打印 `config.problem` 并以退出码 2 结束 —— 发错群比不启动更糟。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `PORT` | 监听端口（默认 `8791`） |
+| `HOST` | 绑定地址（默认 `127.0.0.1`） |
+| `ADAPTER_TOKEN` | **给 PixivFlow 用的** token，校验 `Authorization: Bearer <token>`；未设置只告警（端点无鉴权） |
+| `ADAPTER_SECRET` | 设置后强制校验 `X-Webhook-Signature`（对**原始字节**做 HMAC，5 分钟时间窗） |
+| `ONEBOT_URL` | OneBot HTTP API 基址，如 `http://127.0.0.1:3000` |
+| `ONEBOT_TOKEN` | **给 OneBot 用的** token（与 `ADAPTER_TOKEN` 不要复用同一个值） |
+| `ONEBOT_TARGET` | 投递目标：`group:987654`（默认）或 `private:987654` |
+| `ONEBOT_TIMEOUT_MS` | 单次 OneBot 调用超时（默认 `15000`） |
+| `ONEBOT_MIN_SEND_INTERVAL_MS` | 两次 OneBot 调用之间的最小间隔（默认 `500`），用于限速 |
+| `ONEBOT_STATE_FILE` | 幂等账本（默认 `./.onebot-adapter-state.jsonl`，追加写 JSONL） |
+
+## 端点
+
+| 端点 | 行为 |
+| --- | --- |
+| `POST /deliver` | 验签 → 校验 Bearer → 解析 JSON → 校验 `schemaVersion` → 按 `idempotencyKey` 去重 → 发送消息段 → 上传附件 → 回契约 ACK 词 |
+| `GET /pairing` | 调 `get_login_info`：成功 `{status:"connected", account, nickname}`；可达但未登录 `{status:"waiting", reason}`（HTTP 200）；不可达 HTTP 503 `{status:"unreachable"}` |
+| `GET /health` | 调 `get_status`：`data.online !== false && data.good === true` 时 `{status:"connected", contractVersion:1, gateway:"pixivflow-onebot-adapter", onebot:{…}}`，否则 HTTP 503。**供运维用**，PixivFlow 的投递链路从不调用它 |
+
+未知路由回 `404 {status:"invalid"}`。
+
+## 翻译规则（这是整个文件的重点）
+
+**消息段**（契约 `message.parts` → OneBot `message` 数组，顺序保留）：
+
+| 契约 part | OneBot 段 |
+| --- | --- |
+| `{kind:"text"}` | `{type:"text", data:{text}}` —— 文案取自 `message.text`（契约里正文只出现在 `message.text`，`parts` 里只是一个位置标记），只消费一次 |
+| `{kind:"image", media}` | `{type:"image", data:{file}}` |
+| `{kind:"video", media}` | `{type:"video", data:{file}}` |
+| `{kind:"album"}` | PixivFlow 会展开成 N 个各自带 `media` 的 part，因此这里就是 N 个 `image`/`video` 段 |
+| `{kind:"file", media}` | **不是消息段**：走 `upload_group_file {group_id, file, name}`，再补发一条 `📎 附件：<name>` 提示消息 |
+
+`media.file` 的取值：`base64://<...>`（`base64` 传输，永远可用）或 `file://<绝对路径>`
+（`reference` 传输，要求 OneBot 能读到 PixivFlow 的磁盘 —— 这正是该传输的取舍，不做静默降级）。
+
+**ACK 映射**（OneBot 的 HTTP 状态码几乎永远是 200，成败在 `retcode`；契约的规则是「先看词，再看码」）：
+
+| OneBot 回答 | 本适配器回给 PixivFlow | 结果 |
+| --- | --- | --- |
+| `retcode 0` | `200 {status:"accepted", id:<message_id>}` | `delivered`，`remote_id` 就是平台消息号 |
+| `status:"async"` 或 `retcode 1` | `200 {status:"pending", reason}` | 保持待投递，**绝不报成功** |
+| `retcode 100/102/103/104/105/1400/1404` | `200 {status:"failed", reason}` | 永久失败，进死信，不无限重试 |
+| 未知 `retcode` | `502 {reason}`（**无状态词**） | 可重试，不猜 |
+| 网络不可达 / 超时 / HTTP ≥ 500 | `502 {reason}`（无状态词） | 可重试 |
+| HTTP `401/403/404` | 原样 4xx（无状态词） | 令牌/地址写错，修好即可重试 |
+| HTTP `429` | `429`（无状态词） | 限速，可重试 |
+| 非 JSON 响应体 | `502 {reason}`（无状态词） | 可重试 |
+
+**「无状态词」是刻意的**：契约里状态词优先于 HTTP 码，一旦回了 `failed` 就会进死信；
+所以凡是「请求本身有问题、但改配置后能成功」的情形，都只回一个裸 HTTP 码，让 PixivFlow 继续重试。
+
+## PixivFlow 侧配置
+
+```json
+{
+  "delivery": {
+    "targets": {
+      "qq-main": {
+        "type": "webhook",
+        "url": "http://127.0.0.1:8791/deliver",
+        "token": "${QQ_ADAPTER_TOKEN}",
+        "pairingUrl": "http://127.0.0.1:8791/pairing",
+        "capabilities": {
+          "maxTextLength": 4000,
+          "maxAttachmentsPerMessage": 9,
+          "album": true,
+          "albumMin": 2,
+          "albumMax": 9,
+          "minSendIntervalMs": 500
+        }
+      }
+    }
+  }
+}
+```
+
+跨机部署时把 `url`/`pairingUrl` 换成适配器所在主机的地址；若两者不在同一台机器上，
+`reference` 传输的本地路径对端读不到，请改用 `base64`
+（见 GATEWAY.md §6「`reference` 传输的文件可见性」）。
+
+## 验证
+
+| 层 | 命令/动作 | 证明的是什么 |
+| --- | --- | --- |
+| 适配器自身 | `node examples/onebot-adapter/server.mjs --selftest` | 段构造、ACK 映射、去重、`/pairing`、`/health`（假 OneBot，不接 QQ） |
+| 契约到底 | `npx jest src/__tests__/delivery/onebot-adapter-e2e.test.ts` | **真**投递运行时 → outbox → 适配器进程 → OneBot HTTP：`remote_id`、`pending` 不落地、`failed` 进死信、重放 `duplicate_existing` |
+| QQ 登录态 | NapCat 自己的面板 | 账号在线；**不证明** PixivFlow 能投递 |
+| 真实投递 | 跑一次下载 + `pixivflow delivery status` | 账本上的 `delivered` 与群里的那条消息 |
+
+`--selftest` 与上面的 jest 套件都不需要 QQ、不需要 NapCat：它们证明的是**翻译**正确，
+不是「QQ 已经通了」。