@zhin.js/adapter-juejin 0.0.0-stage → 0.1.0

package/lib/protocol.d.ts

@@ -0,0 +1,192 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
+/**
+ * 掘金（Juejin）评论协议辅助（Experimental，非官方 Web 接口）。
+ *
+ * 契约见 docs/adr/0035-comment-reply-adapter-contract.md（掘金是第二个实现）：
+ * - 一条评论楼 = 一个 conversation：`article:<articleId>:<rootCommentId>`，parent = `article:<articleId>`
+ * - 文章 id 是 19 位十进制字符串（`https://juejin.cn/post/<id>`），超过 2^53，**绝不能**转成 number。
+ * - 读：`POST /interact_api/v1/comment/list`（`item_type=2` 文章，`sort=0` 最新在前），一级评论 + 每楼内联的前几条回复。
+ * - 写：`POST /interact_api/v1/reply/publish`（只回复已有评论楼，带 `reply_to_comment_id`；回复楼中楼时再带 `reply_to_reply_id`）。
+ */
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** 文章评论区 item_type（`interact_api` 里 2 = 文章，4 = 沸点；本 adapter 只支持文章）。 */
+export declare const JUEJIN_ARTICLE_ITEM_TYPE = 2;
+/** 掘金 Web 端 client_type / aid。 */
+export declare const JUEJIN_CLIENT_TYPE = 2608;
+/** 回复长度上限（保守取值；超过直接拒绝，不截断）。 */
+export declare const JUEJIN_COMMENT_MAX_LENGTH = 1000;
+/** 默认轮询间隔下限（秒）。 */
+export declare const JUEJIN_MIN_POLL_INTERVAL_SEC = 60;
+/** 单次拉取的最新一级评论条数（接口上限 50；默认 20）。 */
+export declare const JUEJIN_COMMENT_PAGE_SIZE = 20;
+/** 未登录 / Cookie 失效：`{"err_no":403,"err_msg":"must login"}`。 */
+export declare const JUEJIN_LOGIN_REQUIRED_CODE = 403;
+/**
+ * 被视为风控 / 频控信号的 HTTP 状态：立即熔断，不自动重试。
+ * 403 / 429 = 网关拦截或限流（与 `err_no: 403` 未登录不同：那是 HTTP 200 + JSON）。
+ */
+export declare const JUEJIN_RISK_HTTP_STATUSES: ReadonlySet<number>;
+/**
+ * `err_msg` 命中这些关键字时视为风控（掘金没有公开的风控错误码表，只能按文案判断，宁可多熔断）：
+ * 频繁 / 过快 / 太快 / 风控 / 验证码 / 人机 / 安全验证 / captcha / verify / too many / too frequent / rate limit。
+ */
+export declare const JUEJIN_RISK_MESSAGE: RegExp;
+/** 响应不是 JSON（例如被重定向到验证页）时使用的伪错误码。 */
+export declare const JUEJIN_NON_JSON_CODE = -2;
+export type JuejinSendMode = 'review' | 'off';
+/** 审批后两次真实发送之间的默认最小间隔（秒）与下限。 */
+export declare const JUEJIN_DEFAULT_SEND_INTERVAL_SEC = 30;
+export declare const JUEJIN_MIN_SEND_INTERVAL_SEC = 10;
+/** One endpoint config after AdapterIndex expands `<instanceKey>.endpoints`. */
+export interface JuejinEndpointConfig extends EndpointProfileConfiguration {
+    readonly id: string;
+    /** @internal Assigned only for fresh Adapter identities; imported records retain their original data path. */
+    readonly stateDirectoryId?: string;
+    /** 掘金网页登录态 Cookie 整串（至少含 `sessionid`）。请用 `${JUEJIN_COOKIE}` 注入，切勿写进仓库。 */
+    readonly cookie?: string;
+    /** 白名单文章：文章 id（字符串）或 `https://juejin.cn/post/<id>` 链接。只轮询这些文章。 */
+    readonly articles?: readonly (string | number)[];
+    /** 轮询间隔秒数，最小 60。 */
+    readonly pollIntervalSec?: number;
+    /** 出站模式：`review`（默认，进草稿队列）/ `off`（禁止出站）。 */
+    readonly sendMode?: JuejinSendMode;
+    /** 审批后两次真实发送的最小间隔秒数（默认 30，最小 10）。 */
+    readonly minSendIntervalSec?: number;
+    /** 草稿的本地目录（默认 `data/juejin`，相对进程工作目录）。不要放进仓库。 */
+    readonly dataDir?: string;
+    /** 新草稿 / 登录失效时主动提醒到哪个聊天会话（可选）。 */
+    readonly notify?: JuejinNotifyTarget;
+    readonly apiBaseUrl?: string;
+}
+/** 主动提醒目标：另一个已接入聊天平台里的会话（通常是你和机器人的私聊）。 */
+export interface JuejinNotifyTarget {
+    readonly adapter: string;
+    readonly endpoint: string;
+    readonly kind?: 'private' | 'group' | 'channel';
+    readonly id: string | number;
+}
+export interface ResolvedJuejinNotifyTarget {
+    readonly adapter: string;
+    readonly endpoint: string;
+    readonly kind: 'private' | 'group' | 'channel';
+    readonly id: string;
+}
+export interface ResolvedJuejinConfig {
+    readonly context: 'juejin';
+    readonly id: string;
+    readonly stateDirectoryId?: string;
+    readonly cookie?: string;
+    /** 白名单文章 id（十进制字符串，去重后保持配置顺序）。 */
+    readonly articles: readonly string[];
+    readonly pollIntervalMs: number;
+    readonly sendMode: JuejinSendMode;
+    readonly minSendIntervalMs: number;
+    readonly dataDir: string;
+    readonly notify?: ResolvedJuejinNotifyTarget;
+    readonly apiBaseUrl: string;
+}
+export declare const JUEJIN_DEFAULT_DATA_DIR = "data/juejin";
+export declare const JUEJIN_DEFAULT_API_BASE_URL = "https://api.juejin.cn";
+/** 掘金 id（文章 / 评论 / 回复 / 用户）都是十进制字符串；`'0'` 表示「没有」。 */
+export declare function isJuejinId(value: unknown): value is string;
+/**
+ * 白名单文章：`7129482663794049032` 或 `https://juejin.cn/post/7129482663794049032`（可带 query / hash）。
+ * YAML 里不加引号的 19 位数字会丢精度，直接拒绝，避免回复到错误的文章。
+ */
+export declare function parseArticleRef(value: string | number): string;
+export declare function resolveJuejinConfig(config: JuejinEndpointConfig): ResolvedJuejinConfig;
+export interface JuejinApiEnvelope<T> {
+    readonly err_no: number;
+    readonly err_msg?: string;
+    readonly data?: T;
+    readonly cursor?: string;
+    readonly count?: number;
+    readonly has_more?: boolean;
+}
+export interface JuejinUserInfo {
+    readonly user_id?: string;
+    readonly user_name?: string;
+    readonly avatar_large?: string;
+}
+/** `comment/list` 的一条楼中楼回复（`reply_infos[i]`）。注意顶层 `reply_id` 是会丢精度的 JSON number，只用 `reply_info.reply_id`。 */
+export interface JuejinReplyEntry {
+    readonly reply_id?: unknown;
+    readonly reply_info?: {
+        readonly reply_id?: string;
+        /** 所在评论楼（一级评论 id）。 */
+        readonly reply_comment_id?: string;
+        readonly user_id?: string;
+        /** 回复的是哪条楼中楼回复；`'0'` = 直接回复一级评论。 */
+        readonly reply_to_reply_id?: string;
+        readonly reply_to_user_id?: string;
+        readonly item_id?: string;
+        readonly item_type?: number;
+        readonly reply_content?: string;
+        readonly ctime?: number;
+        readonly digg_count?: number;
+    };
+    readonly user_info?: JuejinUserInfo;
+    /** 回复者是否文章作者。 */
+    readonly is_author?: boolean;
+}
+/** `comment/list` 的一条一级评论。 */
+export interface JuejinCommentEntry {
+    readonly comment_id?: string;
+    readonly comment_info?: {
+        readonly comment_id?: string;
+        readonly user_id?: string;
+        readonly item_id?: string;
+        readonly item_type?: number;
+        readonly comment_content?: string;
+        readonly ctime?: number;
+        readonly digg_count?: number;
+        readonly reply_count?: number;
+    };
+    readonly user_info?: JuejinUserInfo;
+    /** 评论者是否文章作者。 */
+    readonly is_author?: boolean;
+    /** 内联预览：每楼最早的几条回复（实测 2 条），不是全量。 */
+    readonly reply_infos?: readonly JuejinReplyEntry[] | null;
+}
+/** 归一化后的评论（一级评论或楼中楼回复）。 */
+export interface JuejinComment {
+    readonly kind: 'comment' | 'reply';
+    /** 评论 id（一级）或回复 id（楼中楼）。 */
+    readonly id: string;
+    readonly articleId: string;
+    /** 所在评论楼的根（一级评论 id）。 */
+    readonly rootId: string;
+    /** 直接回复的对象：楼中楼回复的 `reply_to_reply_id`，否则为根。 */
+    readonly parentId: string;
+    readonly userId: string;
+    readonly userName?: string;
+    readonly text: string;
+    /** 秒级时间戳。 */
+    readonly ctime: number;
+    readonly diggCount: number;
+    /** 平台标记的「作者」评论（白名单是自己的文章，所以作者 = 自己）。 */
+    readonly isAuthor: boolean;
+}
+/**
+ * 把一页 `comment/list` 摊平成评论 + 内联回复。缺 id、id 不是十进制字符串、不属于这篇文章的条目一律丢弃
+ * （宁可漏，也不回错楼）。
+ */
+export declare function flattenComments(articleId: string, entries: readonly JuejinCommentEntry[] | null | undefined): JuejinComment[];
+/** 评论区资源会话 id（评论楼的 parent）：`article:<articleId>`。 */
+export declare function articleResourceId(articleId: string): string;
+/** 评论楼会话 id：`article:<articleId>:<rootCommentId>`。 */
+export declare function threadConversationId(articleId: string, rootCommentId: string): string;
+export interface ParsedThreadId {
+    readonly articleId: string;
+    readonly root: string;
+}
+export declare function parseThreadConversationId(id: string): ParsedThreadId | undefined;
+export declare function juejinThreadConversation(endpointKey: string, articleId: string, rootCommentId: string): ConversationRef;
+/** 文章页链接（掘金没有可靠的单条评论锚点，审批时到文章评论区对照）。 */
+export declare function articleUrl(articleId: string): string;
+/** 出站 payload 里 `reply` 段指向的评论 / 回复 id（十进制字符串才认）。 */
+export declare function outboundReplyTarget(payload: unknown): string | undefined;
+/** 出站：评论只支持纯文本；mention 降级为 `@昵称`。 */
+export declare function formatOutboundText(payload: unknown): string;
+/** 审批前校验回复正文；合法返回 undefined。 */
+export declare function validateReplyText(message: string): string | undefined;

package/lib/protocol.js

@@ -0,0 +1,214 @@
+/** 文章评论区 item_type（`interact_api` 里 2 = 文章，4 = 沸点；本 adapter 只支持文章）。 */
+export const JUEJIN_ARTICLE_ITEM_TYPE = 2;
+/** 掘金 Web 端 client_type / aid。 */
+export const JUEJIN_CLIENT_TYPE = 2608;
+/** 回复长度上限（保守取值；超过直接拒绝，不截断）。 */
+export const JUEJIN_COMMENT_MAX_LENGTH = 1000;
+/** 默认轮询间隔下限（秒）。 */
+export const JUEJIN_MIN_POLL_INTERVAL_SEC = 60;
+/** 单次拉取的最新一级评论条数（接口上限 50；默认 20）。 */
+export const JUEJIN_COMMENT_PAGE_SIZE = 20;
+/** 未登录 / Cookie 失效：`{"err_no":403,"err_msg":"must login"}`。 */
+export const JUEJIN_LOGIN_REQUIRED_CODE = 403;
+/**
+ * 被视为风控 / 频控信号的 HTTP 状态：立即熔断，不自动重试。
+ * 403 / 429 = 网关拦截或限流（与 `err_no: 403` 未登录不同：那是 HTTP 200 + JSON）。
+ */
+export const JUEJIN_RISK_HTTP_STATUSES = new Set([403, 429]);
+/**
+ * `err_msg` 命中这些关键字时视为风控（掘金没有公开的风控错误码表，只能按文案判断，宁可多熔断）：
+ * 频繁 / 过快 / 太快 / 风控 / 验证码 / 人机 / 安全验证 / captcha / verify / too many / too frequent / rate limit。
+ */
+export const JUEJIN_RISK_MESSAGE = /频繁|过快|太快|风控|验证码|人机|安全验证|captcha|verify|too many|too frequent|rate limit/iu;
+/** 响应不是 JSON（例如被重定向到验证页）时使用的伪错误码。 */
+export const JUEJIN_NON_JSON_CODE = -2;
+/** 审批后两次真实发送之间的默认最小间隔（秒）与下限。 */
+export const JUEJIN_DEFAULT_SEND_INTERVAL_SEC = 30;
+export const JUEJIN_MIN_SEND_INTERVAL_SEC = 10;
+export const JUEJIN_DEFAULT_DATA_DIR = 'data/juejin';
+export const JUEJIN_DEFAULT_API_BASE_URL = 'https://api.juejin.cn';
+const ID = /^[1-9]\d{0,19}$/u;
+/** 掘金 id（文章 / 评论 / 回复 / 用户）都是十进制字符串；`'0'` 表示「没有」。 */
+export function isJuejinId(value) {
+    return typeof value === 'string' && ID.test(value);
+}
+/**
+ * 白名单文章：`7129482663794049032` 或 `https://juejin.cn/post/7129482663794049032`（可带 query / hash）。
+ * YAML 里不加引号的 19 位数字会丢精度，直接拒绝，避免回复到错误的文章。
+ */
+export function parseArticleRef(value) {
+    if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+        throw new TypeError(`Juejin article id ${String(value)} lost precision; quote it as a string in the config`);
+    }
+    const raw = String(value).trim();
+    if (ID.test(raw))
+        return raw;
+    const url = /^https?:\/\/(?:www\.)?juejin\.cn\/post\/([1-9]\d{0,19})(?:[/?#].*)?$/iu.exec(raw);
+    if (url)
+        return url[1];
+    throw new TypeError(`Juejin article must be an article id or https://juejin.cn/post/<id> link, got "${raw}"`);
+}
+function resolveNotifyTarget(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const adapter = typeof value.adapter === 'string' ? value.adapter.trim() : '';
+    const endpoint = typeof value.endpoint === 'string' ? value.endpoint.trim() : String(value.endpoint ?? '').trim();
+    const id = String(value.id ?? '').trim();
+    const kind = value.kind ?? 'private';
+    if (!adapter || !endpoint || !id)
+        throw new TypeError('Juejin notify requires adapter, endpoint and id');
+    if (kind !== 'private' && kind !== 'group' && kind !== 'channel') {
+        throw new TypeError(`Juejin notify.kind must be private, group or channel, got "${String(kind)}"`);
+    }
+    return Object.freeze({ adapter, endpoint, kind, id });
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */)
+        end -= 1;
+    return value.slice(0, end);
+}
+/** Cookie 只允许单行；换行会被当成 header 注入。 */
+function resolveCookie(value) {
+    const cookie = typeof value === 'string' ? value.trim() : '';
+    if (!cookie)
+        return undefined;
+    if (/[\r\n]/u.test(cookie))
+        throw new TypeError('Juejin cookie must be a single line');
+    return cookie;
+}
+export function resolveJuejinConfig(config) {
+    const id = typeof config.id === 'string' ? config.id.trim() : '';
+    if (!id)
+        throw new TypeError('Juejin endpoint requires a non-empty id');
+    const sendMode = config.sendMode ?? 'review';
+    if (sendMode !== 'review' && sendMode !== 'off') {
+        // auto 直发刻意不开放（ADR 0035 §3）。
+        throw new TypeError(`Juejin sendMode must be "review" or "off", got "${String(sendMode)}"`);
+    }
+    const interval = Math.max(JUEJIN_MIN_POLL_INTERVAL_SEC, Number.isFinite(config.pollIntervalSec) ? Number(config.pollIntervalSec) : JUEJIN_MIN_POLL_INTERVAL_SEC);
+    const sendInterval = Math.max(JUEJIN_MIN_SEND_INTERVAL_SEC, Number.isFinite(config.minSendIntervalSec) ? Number(config.minSendIntervalSec) : JUEJIN_DEFAULT_SEND_INTERVAL_SEC);
+    const cookie = resolveCookie(config.cookie);
+    const notify = resolveNotifyTarget(config.notify);
+    return {
+        context: 'juejin',
+        id,
+        ...(config.stateDirectoryId ? { stateDirectoryId: config.stateDirectoryId } : {}),
+        ...(cookie ? { cookie } : {}),
+        articles: Object.freeze([...new Set((config.articles ?? []).map(parseArticleRef))]),
+        pollIntervalMs: interval * 1000,
+        sendMode,
+        minSendIntervalMs: sendInterval * 1000,
+        dataDir: config.dataDir?.trim() || JUEJIN_DEFAULT_DATA_DIR,
+        ...(notify ? { notify } : {}),
+        apiBaseUrl: trimTrailingSlashes(config.apiBaseUrl?.trim() || JUEJIN_DEFAULT_API_BASE_URL),
+    };
+}
+/**
+ * 把一页 `comment/list` 摊平成评论 + 内联回复。缺 id、id 不是十进制字符串、不属于这篇文章的条目一律丢弃
+ * （宁可漏，也不回错楼）。
+ */
+export function flattenComments(articleId, entries) {
+    const out = [];
+    for (const entry of entries ?? []) {
+        const info = entry?.comment_info;
+        const id = info?.comment_id ?? entry?.comment_id;
+        const userId = info?.user_id ?? entry?.user_info?.user_id;
+        if (!isJuejinId(id) || !isJuejinId(userId) || info?.item_id !== articleId)
+            continue;
+        out.push(Object.freeze({
+            kind: 'comment', id, articleId, rootId: id, parentId: id, userId,
+            ...(entry.user_info?.user_name ? { userName: entry.user_info.user_name } : {}),
+            text: info.comment_content ?? '', ctime: Number(info.ctime) || 0, diggCount: Number(info.digg_count) || 0,
+            isAuthor: entry.is_author === true,
+        }));
+        for (const child of entry.reply_infos ?? []) {
+            const reply = child?.reply_info;
+            if (!reply || !isJuejinId(reply.reply_id) || reply.reply_comment_id !== id || !isJuejinId(reply.user_id))
+                continue;
+            if (reply.item_id !== undefined && reply.item_id !== articleId)
+                continue;
+            const target = reply.reply_to_reply_id;
+            out.push(Object.freeze({
+                kind: 'reply', id: reply.reply_id, articleId, rootId: id,
+                parentId: isJuejinId(target) ? target : id, userId: reply.user_id,
+                ...(child.user_info?.user_name ? { userName: child.user_info.user_name } : {}),
+                text: reply.reply_content ?? '', ctime: Number(reply.ctime) || 0, diggCount: Number(reply.digg_count) || 0,
+                isAuthor: child.is_author === true,
+            }));
+        }
+    }
+    return out;
+}
+// ── Conversation ids ─────────────────────────────────────────────────────────
+/** 评论区资源会话 id（评论楼的 parent）：`article:<articleId>`。 */
+export function articleResourceId(articleId) {
+    return `article:${articleId}`;
+}
+/** 评论楼会话 id：`article:<articleId>:<rootCommentId>`。 */
+export function threadConversationId(articleId, rootCommentId) {
+    return `${articleResourceId(articleId)}:${rootCommentId}`;
+}
+export function parseThreadConversationId(id) {
+    const match = /^article:([1-9]\d{0,19}):([1-9]\d{0,19})$/u.exec(id);
+    if (!match)
+        return undefined;
+    return { articleId: match[1], root: match[2] };
+}
+export function juejinThreadConversation(endpointKey, articleId, rootCommentId) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'channel',
+        id: threadConversationId(articleId, rootCommentId),
+        parent: { kind: 'channel', id: articleResourceId(articleId) },
+    };
+}
+/** 文章页链接（掘金没有可靠的单条评论锚点，审批时到文章评论区对照）。 */
+export function articleUrl(articleId) {
+    return `https://juejin.cn/post/${articleId}`;
+}
+/** 出站 payload 里 `reply` 段指向的评论 / 回复 id（十进制字符串才认）。 */
+export function outboundReplyTarget(payload) {
+    const items = Array.isArray(payload) ? payload : [payload];
+    for (const item of items) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const seg = item;
+        if (seg.type !== 'reply')
+            continue;
+        const id = String(seg.data?.id ?? seg.data?.message_id ?? '').trim();
+        if (isJuejinId(id))
+            return id;
+    }
+    return undefined;
+}
+/** 出站：评论只支持纯文本；mention 降级为 `@昵称`。 */
+export function formatOutboundText(payload) {
+    if (typeof payload === 'string')
+        return payload.trim();
+    if (payload == null)
+        return '';
+    const items = Array.isArray(payload) ? payload : [payload];
+    return items.map((item) => {
+        if (typeof item === 'string')
+            return item;
+        const seg = item;
+        switch (seg.type) {
+            case 'text':
+                return String(seg.data?.text ?? '');
+            case 'mention':
+            case 'at':
+                return `@${String(seg.data?.name ?? seg.data?.id ?? '')} `;
+            default:
+                return '';
+        }
+    }).join('').trim();
+}
+/** 审批前校验回复正文；合法返回 undefined。 */
+export function validateReplyText(message) {
+    if (!message)
+        return 'Empty Juejin reply';
+    if ([...message].length > JUEJIN_COMMENT_MAX_LENGTH)
+        return `Juejin reply exceeds ${JUEJIN_COMMENT_MAX_LENGTH} characters`;
+    return undefined;
+}

package/lib/review.d.ts

@@ -0,0 +1,29 @@
+/** Draft review presentation; endpoint methods remain the approval and delivery authority. */
+import { type Locale } from 'zhin.js/i18n';
+import type { JuejinReplyDraft } from './drafts.js';
+import { type JuejinNotice } from './endpoint.js';
+import type { JuejinEndpointDirectory, JuejinEndpointView } from './endpoint-directory.js';
+export interface DraftPresentation {
+    readonly locale?: Locale;
+    /** Bound to the current command index, owner namespace and actual chat prefix. */
+    readonly formatCommand?: (localPath: string) => string | undefined;
+}
+/** 主动提醒的文案（新草稿 / 登录失效）。 */
+export declare function formatNotice(notice: JuejinNotice, presentation?: DraftPresentation): string;
+/** 草稿所在文章的链接（Console / 列表展示）。 */
+export declare function draftArticleUrl(draft: Pick<JuejinReplyDraft, 'articleId'>): string;
+export declare function formatDraft(draft: JuejinReplyDraft, options?: {
+    readonly full?: boolean;
+    readonly locale?: Locale;
+}): string;
+export declare function findDraft(registry: JuejinEndpointDirectory, id: string): {
+    endpoint: JuejinEndpointView;
+    draft: JuejinReplyDraft;
+} | undefined;
+export declare function draftEditUsage(presentation?: DraftPresentation): string;
+export declare function listDraftsText(registry: JuejinEndpointDirectory, presentation?: DraftPresentation): string;
+export declare function showDraftText(registry: JuejinEndpointDirectory, id: string, presentation?: DraftPresentation): string;
+export declare function editDraftText(registry: JuejinEndpointDirectory, id: string, message: string, presentation?: DraftPresentation): string;
+export declare function discardDraftText(registry: JuejinEndpointDirectory, id: string, presentation?: DraftPresentation): string;
+export declare function approveDraftText(registry: JuejinEndpointDirectory, id: string, presentation?: DraftPresentation): Promise<string>;
+export declare function reviewErrorText(id: string, error: unknown, locale?: Locale): string;

package/lib/review.js

@@ -0,0 +1,156 @@
+/** Draft review presentation; endpoint methods remain the approval and delivery authority. */
+import { createMessages } from 'zhin.js/i18n';
+import { JuejinReviewError } from './endpoint.js';
+import { JUEJIN_COMMENT_MAX_LENGTH, articleUrl } from './protocol.js';
+const LIST_LIMIT = 10;
+const t = createMessages({
+    sending: { 'zh-CN': '（发送中）', en: ' (sending)' },
+    interrupted: { 'zh-CN': '（上次发送结果未知，可能已经发出，请先到掘金确认）', en: ' (last send outcome is unknown and may have been posted; check Juejin first)' },
+    noticeDraft: { 'zh-CN': '掘金有一条新评论回复等你审批：', en: 'A new Juejin comment reply is waiting for your approval:' },
+    noticeReview: { 'zh-CN': '去 Console「掘金评论审批」页处理，或：{command}', en: 'Review it on the Console "Juejin comment review" page, or: {command}' },
+    noticeReviewConsole: { 'zh-CN': '去 Console「掘金评论审批」页处理', en: 'Review it on the Console "Juejin comment review" page' },
+    noticeExpired: { 'zh-CN': '掘金登录已失效（Cookie 来自配置 / 环境变量），暂时无法发送评论。请更新 Cookie 后重启。', en: 'Your Juejin login has expired (cookie from config or environment), so replies cannot be posted. Update the cookie and restart.' },
+    original: { 'zh-CN': '  原评论 {author}：{text}', en: '  Original comment by {author}: {text}' },
+    reply: { 'zh-CN': '  拟回复：{text}', en: '  Proposed reply: {text}' },
+    empty: { 'zh-CN': '没有待审的掘金评论草稿', en: 'No Juejin comment drafts are awaiting review.' },
+    more: { 'zh-CN': '（只显示最新 {shown} 条，共 {total} 条）', en: '(Showing the latest {shown} of {total} drafts)' },
+    list: { 'zh-CN': '待审草稿 {count} 条：', en: '{count} drafts awaiting review:' },
+    sendHint: { 'zh-CN': '发送：{command}', en: 'Send: {command}' },
+    editHint: { 'zh-CN': '改写：{command}', en: 'Edit: {command}' },
+    dropHint: { 'zh-CN': '丢弃：{command}', en: 'Discard: {command}' },
+    content: { 'zh-CN': '<新内容>', en: '<new content>' },
+    editUsage: { 'zh-CN': '用法：{command} <id> {content}', en: 'Usage: {command} <id> {content}' },
+    editRequired: { 'zh-CN': '请提供草稿的新内容。当前环境无法确定改写指令的调用方式。', en: 'Provide new draft text. The edit command invocation is unavailable in this environment.' },
+    missing: { 'zh-CN': '找不到草稿 {id}', en: 'Draft {id} was not found.' },
+    edited: { 'zh-CN': '已改写，还没发出：', en: 'Updated; not sent yet:' },
+    approveHint: { 'zh-CN': '确认无误后：{command}', en: 'After reviewing, approve with: {command}' },
+    dropped: { 'zh-CN': '已丢弃草稿 {id}（未发送）', en: 'Draft {id} discarded without sending.' },
+    sent: { 'zh-CN': '已发到掘金：{url}', en: 'Posted to Juejin: {url}' },
+    failed: { 'zh-CN': '草稿 {id} 操作失败：{error}', en: 'Draft {id} operation failed: {error}' },
+    busy: { 'zh-CN': '草稿 {id} 正在发送，请稍等', en: 'Draft {id} is being sent. Please wait.' },
+    disabled: { 'zh-CN': '当前不允许出站（sendMode 为 off，或文章已不在白名单）', en: 'Outbound is not allowed (sendMode is off, or the article is no longer whitelisted).' },
+    circuit: { 'zh-CN': '掘金风控熔断，草稿 {id} 已保留未发。请到网页端确认账号状态，处理后重启插件。', en: 'Juejin risk controls stopped this endpoint. Draft {id} is retained and was not sent. Check the account on the website, resolve the issue, then restart the plugin.' },
+    cookie: { 'zh-CN': '掘金未登录或登录已失效，无法发送（草稿已保留）。请更新 JUEJIN_COOKIE 后重启。', en: 'Not signed in to Juejin or the login expired, so the draft was kept unsent. Update JUEJIN_COOKIE and restart.' },
+    limited: { 'zh-CN': '发得太快了，请 {seconds} 秒后再发（草稿 {id} 已保留）', en: 'Sending too quickly. Try again after {seconds} seconds; draft {id} is retained.' },
+    invalid: { 'zh-CN': '草稿内容不合法：回复不能为空，且不能超过 {limit} 个字符。', en: 'Invalid draft: replies must be nonempty and at most {limit} characters.' },
+    unknown: { 'zh-CN': '掘金没有确认结果，草稿 {id} 可能已经发出。请先到文章评论区确认，再决定重发或丢弃。', en: 'Juejin did not confirm the result; draft {id} may already be posted. Check the article comments before resending or discarding.' },
+    platform: { 'zh-CN': '掘金返回错误，草稿 {id} 已保留：{error}', en: 'Juejin returned an error; draft {id} is retained: {error}' },
+});
+/** 主动提醒的文案（新草稿 / 登录失效）。 */
+export function formatNotice(notice, presentation = {}) {
+    const { locale, formatCommand } = presentation;
+    switch (notice.kind) {
+        case 'draft': {
+            const command = formatCommand?.('juejin-draft send');
+            return [t(locale, 'noticeDraft'), formatDraft(notice.draft, { locale }),
+                command === undefined ? t(locale, 'noticeReviewConsole') : t(locale, 'noticeReview', { command: `${command} ${notice.draft.id}` })].join('\n');
+        }
+        case 'login_expired':
+            return t(locale, 'noticeExpired');
+    }
+}
+/** 草稿所在文章的链接（Console / 列表展示）。 */
+export function draftArticleUrl(draft) {
+    return articleUrl(draft.articleId);
+}
+function excerpt(text, max = 60) {
+    const chars = [...text.replace(/\s+/g, ' ').trim()];
+    return chars.length > max ? `${chars.slice(0, max).join('')}…` : chars.join('');
+}
+export function formatDraft(draft, options = {}) {
+    const { locale } = options;
+    const lines = [`[${draft.id}] ${draftArticleUrl(draft)}${draft.status === 'sending' ? t(locale, 'sending') : ''}${draft.interrupted ? t(locale, 'interrupted') : ''}`];
+    if (draft.context)
+        lines.push(t(locale, 'original', { author: draft.context.author, text: options.full ? draft.context.text : excerpt(draft.context.text) }));
+    lines.push(t(locale, 'reply', { text: options.full ? draft.message : excerpt(draft.message) }));
+    return lines.join('\n');
+}
+export function findDraft(registry, id) {
+    for (const endpoint of registry.values()) {
+        const draft = endpoint.drafts.get(id);
+        if (draft)
+            return { endpoint, draft };
+    }
+    return undefined;
+}
+export function draftEditUsage(presentation = {}) {
+    const command = presentation.formatCommand?.('juejin-draft edit');
+    return command === undefined ? t(presentation.locale, 'editRequired')
+        : t(presentation.locale, 'editUsage', { command, content: t(presentation.locale, 'content') });
+}
+export function listDraftsText(registry, presentation = {}) {
+    const { locale, formatCommand } = presentation;
+    const drafts = [...registry.values()].flatMap(endpoint => endpoint.drafts.list());
+    if (drafts.length === 0)
+        return t(locale, 'empty');
+    const shown = drafts.slice(-LIST_LIMIT);
+    const lines = [t(locale, 'list', { count: drafts.length }), ...shown.map(draft => formatDraft(draft, { locale }))];
+    if (drafts.length > shown.length)
+        lines.push(t(locale, 'more', { shown: shown.length, total: drafts.length }));
+    const hints = [];
+    for (const [action, key] of [['send', 'sendHint'], ['edit', 'editHint'], ['drop', 'dropHint']]) {
+        const command = formatCommand?.(`juejin-draft ${action}`);
+        if (command !== undefined)
+            hints.push(t(locale, key, { command: `${command} <id>${action === 'edit' ? ` ${t(locale, 'content')}` : ''}` }));
+    }
+    if (hints.length)
+        lines.push('', hints.join('\n'));
+    return lines.join('\n');
+}
+export function showDraftText(registry, id, presentation = {}) {
+    const found = findDraft(registry, id);
+    return found ? formatDraft(found.draft, { full: true, locale: presentation.locale }) : t(presentation.locale, 'missing', { id });
+}
+export function editDraftText(registry, id, message, presentation = {}) {
+    const { locale, formatCommand } = presentation;
+    const found = findDraft(registry, id);
+    if (!found)
+        return t(locale, 'missing', { id });
+    try {
+        const draft = found.endpoint.editDraft(id, message);
+        const command = formatCommand?.('juejin-draft send');
+        return [t(locale, 'edited'), formatDraft(draft, { full: true, locale }),
+            ...(command === undefined ? [] : [t(locale, 'approveHint', { command: `${command} ${id}` })])].join('\n');
+    }
+    catch (error) {
+        return reviewErrorText(id, error, locale);
+    }
+}
+export function discardDraftText(registry, id, presentation = {}) {
+    const found = findDraft(registry, id);
+    if (!found)
+        return t(presentation.locale, 'missing', { id });
+    try {
+        return t(presentation.locale, found.endpoint.discardDraft(id) ? 'dropped' : 'missing', { id });
+    }
+    catch (error) {
+        return reviewErrorText(id, error, presentation.locale);
+    }
+}
+export async function approveDraftText(registry, id, presentation = {}) {
+    const found = findDraft(registry, id);
+    if (!found)
+        return t(presentation.locale, 'missing', { id });
+    try {
+        const { draft } = await found.endpoint.approveDraft(id);
+        return `${t(presentation.locale, 'sent', { url: draftArticleUrl(draft) })}\n${excerpt(draft.message, 120)}`;
+    }
+    catch (error) {
+        return reviewErrorText(id, error, presentation.locale);
+    }
+}
+export function reviewErrorText(id, error, locale) {
+    if (!(error instanceof JuejinReviewError))
+        return t(locale, 'failed', { id, error: error instanceof Error ? error.message : String(error) });
+    switch (error.code) {
+        case 'not_found': return t(locale, 'missing', { id });
+        case 'busy': return t(locale, 'busy', { id });
+        case 'send_disabled': return t(locale, 'disabled');
+        case 'circuit_open': return t(locale, 'circuit', { id });
+        case 'no_cookie': return t(locale, 'cookie');
+        case 'rate_limited': return t(locale, 'limited', { id, seconds: Math.ceil((error.retryAfterMs ?? 0) / 1000) });
+        case 'invalid_message': return t(locale, 'invalid', { limit: JUEJIN_COMMENT_MAX_LENGTH });
+        case 'unknown_outcome': return t(locale, 'unknown', { id });
+        case 'platform_error': return t(locale, 'platform', { id, error: error.message });
+    }
+}

package/lib/self-profile.d.ts

@@ -0,0 +1,9 @@
+import { type EndpointProfile } from 'zhin.js/adapter';
+import type { JuejinClient } from './client.js';
+interface JuejinSelfProfileOptions {
+    readonly client: Pick<JuejinClient, 'getSelf'>;
+    readonly reportAccount: (id: string) => void;
+}
+/** Experimental Juejin adapter exposes a read-only profile from the logged-in Web identity. */
+export declare function createJuejinSelfProfile({ client, reportAccount }: JuejinSelfProfileOptions): EndpointProfile;
+export {};

package/lib/self-profile.js

@@ -0,0 +1,14 @@
+import { createEndpointOperation } from 'zhin.js/adapter';
+/** Experimental Juejin adapter exposes a read-only profile from the logged-in Web identity. */
+export function createJuejinSelfProfile({ client, reportAccount }) {
+    return Object.freeze({
+        writableFields: Object.freeze([]),
+        async read({ signal }) {
+            const self = await createEndpointOperation({ signal }).prepare(() => client.getSelf());
+            if (!self)
+                throw new Error('Juejin account is not logged in');
+            reportAccount(self.userId);
+            return { ...(self.userName ? { nickname: self.userName } : {}), ...(self.avatar ? { avatar: self.avatar } : {}) };
+        },
+    });
+}

package/lib/storage.d.ts

@@ -0,0 +1,11 @@
+/** endpoint id → 安全的目录名（只留字母数字和 `_.-`，其余替换成 `_`）。 */
+export declare function endpointDirectoryName(endpointId: string): string;
+export declare function writeJsonAtomic(file: string, value: unknown, mode?: number): void;
+/** 读不到、不是 JSON 都返回 undefined；调用方自行校验结构。 */
+export declare function readJson(file: string): unknown;
+export declare function removeFile(file: string): void;
+export declare class JuejinStateFiles {
+    readonly directory: string;
+    constructor(rootDir: string, endpointId: string);
+    get draftsFile(): string;
+}