dsh-caduceus 0.7.0 → 0.10.5

package/dist/commands/dispatch.js

@@ -4,14 +4,14 @@
  *
  * The surface owns eight commands; every other slash line is forwarded to the
  * harness command registry (`runHarnessCommand`), except Web-only commands that
- * make no sense on a chat surface. `/export` is the required minimum; the list
- * is intentionally small and explicit.
+ * make no sense on a chat surface. `/export` is now implemented by the surface
+ * itself, so the list is intentionally empty; keep the seam for future entries.
  *
  * @module dsh-caduceus/commands/dispatch
  */
 import { parseCommand } from './parse.js';
 /** Commands that exist only in the Web UI and are refused on Feishu. */
-export const WEB_ONLY_DENYLIST = ['export'];
+export const WEB_ONLY_DENYLIST = [];
 /** True when a slash-command name must not be forwarded to the harness. */
 export function isWebOnlyCommand(name) {
     return WEB_ONLY_DENYLIST.includes(name.toLowerCase());

package/dist/commands/parse.d.ts

@@ -1,5 +1,5 @@
 /** Commands dsh-caduceus owns. Keep in sync with README's command table. */
-export declare const COMMAND_NAMES: readonly ["new", "sessions", "rename", "resume", "adopt", "selfcheck", "doctor", "stop", "status", "persona", "whoami", "help"];
+export declare const COMMAND_NAMES: readonly ["new", "sessions", "rename", "resume", "adopt", "selfcheck", "doctor", "stop", "status", "persona", "whoami", "export", "permission", "usage", "help"];
 export type CommandName = (typeof COMMAND_NAMES)[number];
 export interface CommandSpec {
     readonly name: CommandName;
@@ -38,6 +38,14 @@ export type ParsedCommand = {
     readonly action: PersonaAction;
 } | {
     readonly kind: 'whoami';
+} | {
+    readonly kind: 'export';
+    readonly json?: boolean;
+} | {
+    readonly kind: 'permission';
+    readonly preset?: string;
+} | {
+    readonly kind: 'usage-report';
 } | {
     readonly kind: 'help';
 } | {
@@ -57,5 +65,10 @@ export type ParsedCommand = {
  * never rewrites a user's text.
  */
 export declare function parseCommand(raw: string): ParsedCommand;
-/** The reply body for `/help`, one line per owned command. */
+/** dsh commands that already pass through the harness registry. */
+export declare const DSH_NATIVE_COMMANDS: readonly {
+    readonly name: string;
+    readonly description: string;
+}[];
+/** The reply body for `/help`: owned commands plus dsh native passthroughs. */
 export declare function helpText(): string;

package/dist/commands/parse.js

@@ -11,7 +11,7 @@
  */
 import { stripLeadingMentions } from '../mentions.js';
 /** Commands dsh-caduceus owns. Keep in sync with README's command table. */
-export const COMMAND_NAMES = ['new', 'sessions', 'rename', 'resume', 'adopt', 'selfcheck', 'doctor', 'stop', 'status', 'persona', 'whoami', 'help'];
+export const COMMAND_NAMES = ['new', 'sessions', 'rename', 'resume', 'adopt', 'selfcheck', 'doctor', 'stop', 'status', 'persona', 'whoami', 'export', 'permission', 'usage', 'help'];
 /** Command metadata; `helpText()` and the README command table both derive from it. */
 export const COMMAND_SPECS = [
     { name: 'new', usage: '/new', description: '为当前聊天/话题新建会话，旧会话保留' },
@@ -25,6 +25,9 @@ export const COMMAND_SPECS = [
     { name: 'status', usage: '/status', description: '显示本会话的运行状态、步数与起止时间' },
     { name: 'persona', usage: '/persona [show|sync]', description: '查看或同步 SOUL 人格块' },
     { name: 'whoami', usage: '/whoami', description: '显示你的 open_id、当前会话与身份' },
+    { name: 'export', usage: '/export [--json]', description: '把当前会话导出为 markdown 或 JSONL 并发回文件' },
+    { name: 'permission', usage: '/permission [档位]', description: '查看或切换当前会话的权限档位（中文）' },
+    { name: 'usage', usage: '/usage', description: '查看本会话 token 用量（本回合/上回合/合计）' },
     { name: 'help', usage: '/help', description: '显示命令表' },
 ];
 function usageResult(command, reason) {
@@ -66,6 +69,23 @@ export function parseCommand(raw) {
             return rest === '' ? { kind: 'status' } : usageResult('status', '/status 不接受参数');
         case 'whoami':
             return rest === '' ? { kind: 'whoami' } : usageResult('whoami', '/whoami 不接受参数');
+        case 'export': {
+            if (rest === '')
+                return { kind: 'export' };
+            if (rest === '--json')
+                return { kind: 'export', json: true };
+            return usageResult('export', '用法：/export [--json]');
+        }
+        case 'usage':
+            return rest === '' ? { kind: 'usage-report' } : usageResult('usage', '/usage 不接受参数');
+        case 'permission': {
+            if (rest === '')
+                return { kind: 'permission' };
+            const parts = rest.split(/\s+/);
+            if (parts.length > 1)
+                return usageResult('permission', '用法：/permission [档位]');
+            return { kind: 'permission', preset: parts[0] };
+        }
         case 'help':
             return { kind: 'help' };
         case 'rename':
@@ -108,11 +128,22 @@ export function parseCommand(raw) {
             return { kind: 'passthrough', raw };
     }
 }
-/** The reply body for `/help`, one line per owned command. */
+/** dsh commands that already pass through the harness registry. */
+export const DSH_NATIVE_COMMANDS = [
+    { name: 'compact', description: '压缩当前会话上下文' },
+    { name: 'goal', description: '查看/管理当前目标' },
+    { name: 'plan', description: '查看/切换计划模式' },
+    { name: 'feedback', description: '提交反馈' },
+];
+/** The reply body for `/help`: owned commands plus dsh native passthroughs. */
 export function helpText() {
     const lines = ['dsh-caduceus 命令：'];
     for (const spec of COMMAND_SPECS)
         lines.push(`${spec.usage} — ${spec.description}`);
-    lines.push('其他 /命令 与普通消息原样交给 dsh。');
+    lines.push('', 'dsh 原生命令（透传）：');
+    for (const command of DSH_NATIVE_COMMANDS) {
+        lines.push(`/${command.name} — ${command.description}`);
+    }
+    lines.push('', '其他 /命令 与普通消息原样交给 dsh。');
     return lines.join('\n');
 }

package/dist/config.d.ts

@@ -1,5 +1,7 @@
 import z from '@deepseek-ai/schemastery';
 import type { ApprovalPolicy, BridgeConfig, BusyMode } from './bridge/types.js';
+import type { LangSetting } from './i18n.js';
+import type { MetricsMode } from './metrics.js';
 /** Raw entry config as written in the profile. */
 export interface GatewayConfig {
     readonly appId?: string;
@@ -23,7 +25,7 @@ export interface GatewayConfig {
     readonly questionCard?: boolean;
     /** Interactive card timeout in ms (default 300000). */
     readonly interactiveTimeoutMs?: number;
-    /** Session approval policy; IM humans are present, so default `ask`. */
+    /** Session approval policy override; undefined keeps dsh's own policy. */
     readonly approvalPolicy?: ApprovalPolicy;
     /** Emoji reactions on inbound/turn-end (default true). */
     readonly reactions?: boolean;
@@ -51,6 +53,12 @@ export interface GatewayConfig {
     readonly mediaRoots?: readonly string[];
     /** Admin open-id allowlist; empty disables access control (default). */
     readonly admins?: readonly string[];
+    /** UI language: zh (default), en, or auto (settings/env, fallback zh). */
+    readonly lang?: LangSetting;
+    /** Export cache retention in hours (default 24). */
+    readonly exportCacheMaxAgeHours?: number;
+    /** Process-card/usage metrics mode (default compact). */
+    readonly metrics?: MetricsMode;
 }
 /** Schemastery schema for the `caduceus-gateway` entry. */
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
@@ -82,6 +90,9 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     maxSendImageBytes: z<number, number, "plain">;
     mediaRoots: z<string[], string[], "plain">;
     admins: z<string[], string[], "plain">;
+    lang: z<"zh" | "en" | "auto", "zh" | "en" | "auto", "plain">;
+    exportCacheMaxAgeHours: z<number, number, "plain">;
+    metrics: z<"off" | "compact" | "detailed", "off" | "compact" | "detailed", "plain">;
 }>>, Schemastery.ObjectT<NoInfer<{
     appId: z<string, string, "plain">;
     appSecret: z<string, string, "plain">;
@@ -111,6 +122,9 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     maxSendImageBytes: z<number, number, "plain">;
     mediaRoots: z<string[], string[], "plain">;
     admins: z<string[], string[], "plain">;
+    lang: z<"zh" | "en" | "auto", "zh" | "en" | "auto", "plain">;
+    exportCacheMaxAgeHours: z<number, number, "plain">;
+    metrics: z<"off" | "compact" | "detailed", "off" | "compact" | "detailed", "plain">;
 }>>, "plain">;
 /** Default card patch throttle: half of Feishu's 5 QPS budget. */
 export declare const DEFAULT_CARD_THROTTLE_MS = 400;
@@ -137,8 +151,6 @@ export declare const DEFAULT_REACTIONS = true;
 export declare const DEFAULT_REACTION_ON_START = "OnIt";
 export declare const DEFAULT_REACTION_ON_DONE = "DONE";
 export declare const DEFAULT_REACTION_ON_FAIL = "CROSS_MARK";
-/** Default session approval policy: ask, so dangerous actions prompt a card. */
-export declare const DEFAULT_APPROVAL_POLICY: ApprovalPolicy;
 /** Default interactive-card switches/timeout. */
 export declare const DEFAULT_APPROVAL_CARD = true;
 export declare const DEFAULT_QUESTION_CARD = true;
@@ -160,7 +172,9 @@ export interface ResolvedGatewayConfig {
     readonly approvalCard: boolean;
     readonly questionCard: boolean;
     readonly interactiveTimeoutMs: number;
-    readonly approvalPolicy: ApprovalPolicy;
+    readonly approvalPolicy?: ApprovalPolicy;
+    readonly lang: LangSetting;
+    readonly exportCacheMaxAgeHours: number;
 }
 export interface ConfigEnv {
     readonly FEISHU_APP_ID?: string;

package/dist/config.js

@@ -40,6 +40,9 @@ export const Config = z.object({
     maxSendImageBytes: z.natural().min(1).required(false),
     mediaRoots: z.array(z.string()).required(false),
     admins: z.array(z.string()).required(false),
+    lang: z.union([z.const('zh'), z.const('en'), z.const('auto')]).required(false),
+    exportCacheMaxAgeHours: z.natural().min(1).required(false),
+    metrics: z.union([z.const('off'), z.const('compact'), z.const('detailed')]).required(false),
 });
 /** Default card patch throttle: half of Feishu's 5 QPS budget. */
 export const DEFAULT_CARD_THROTTLE_MS = 400;
@@ -66,8 +69,6 @@ export const DEFAULT_REACTIONS = true;
 export const DEFAULT_REACTION_ON_START = 'OnIt';
 export const DEFAULT_REACTION_ON_DONE = 'DONE';
 export const DEFAULT_REACTION_ON_FAIL = 'CROSS_MARK';
-/** Default session approval policy: ask, so dangerous actions prompt a card. */
-export const DEFAULT_APPROVAL_POLICY = 'ask';
 /** Default interactive-card switches/timeout. */
 export const DEFAULT_APPROVAL_CARD = true;
 export const DEFAULT_QUESTION_CARD = true;
@@ -117,6 +118,7 @@ export function resolveGatewayConfig(config = {}, env = process.env, cwd = proce
         maxSendImageBytes: config.maxSendImageBytes ?? DEFAULT_MAX_SEND_IMAGE_BYTES,
         mediaRoots: config.mediaRoots ?? [],
         admins: config.admins ?? [],
+        metrics: config.metrics ?? 'compact',
     };
     return {
         ...(appId === undefined || appSecret === undefined ? {} : { credentials: { appId, appSecret } }),
@@ -127,6 +129,10 @@ export function resolveGatewayConfig(config = {}, env = process.env, cwd = proce
         approvalCard: config.approvalCard ?? DEFAULT_APPROVAL_CARD,
         questionCard: config.questionCard ?? DEFAULT_QUESTION_CARD,
         interactiveTimeoutMs: config.interactiveTimeoutMs ?? DEFAULT_INTERACTIVE_TIMEOUT_MS,
-        approvalPolicy: config.approvalPolicy ?? DEFAULT_APPROVAL_POLICY,
+        ...(config.approvalPolicy === undefined
+            ? {}
+            : { approvalPolicy: config.approvalPolicy }),
+        lang: config.lang ?? 'zh',
+        exportCacheMaxAgeHours: config.exportCacheMaxAgeHours ?? 24,
     };
 }

package/dist/export.d.ts

@@ -0,0 +1,44 @@
+import type { LoggerLike } from './logger.js';
+export type ExportRole = 'user' | 'assistant' | 'tool';
+export interface ExportMessage {
+    readonly role: ExportRole;
+    readonly text: string;
+    readonly toolName?: string;
+}
+export interface SessionExportData {
+    readonly messages: readonly ExportMessage[];
+    /** Original uncompressed JSONL when available. */
+    readonly rawJsonl?: string;
+}
+export type SessionExportProvider = (sessionId: string) => SessionExportData | undefined | Promise<SessionExportData | undefined>;
+export declare const EXPORT_MAX_BYTES: number;
+export declare function truncateExport(text: string): string;
+export declare function parseSessionEvents(events: readonly unknown[]): ExportMessage[];
+/** Locate the newest `session[.vN].jsonl[.zstd]` belonging to one session. */
+export declare function findSessionLog(sessionId: string, dshHome: string): string | undefined;
+/**
+ * Read a session log directly from `$DSH_HOME/sessions`.
+ *
+ * @throws Error with a user-readable message when the log or zstd support is missing.
+ */
+export declare function readSessionLogFile(sessionId: string, dshHome?: string): SessionExportData | undefined;
+/** Markdown export with a bounded file size. */
+export declare function renderExportMarkdown(input: {
+    readonly sessionId: string;
+    readonly title?: string;
+    readonly now: number;
+    readonly messages: readonly ExportMessage[];
+}): string;
+/** Raw JSONL export (one normalized message per line, bounded). */
+export declare function renderExportJsonl(messages: readonly ExportMessage[]): string;
+/** Write one export file into the cache directory; returns the absolute path. */
+export declare function writeExportFile(directory: string, scopeKind: string, sessionId: string, extension: 'md' | 'jsonl', content: string, now: number): string;
+export interface ExportCacheCleanupResult {
+    readonly removed: number;
+    readonly kept: number;
+}
+/**
+ * Remove export-cache files older than `maxAgeHours`. A missing directory is
+ * fine; any filesystem error is logged as one warn and never thrown.
+ */
+export declare function cleanupExportCache(directory: string, maxAgeHours: number, now?: number, logger?: LoggerLike): ExportCacheCleanupResult;

package/dist/export.js

@@ -0,0 +1,222 @@
+/**
+ * `/export`: render one dsh session as markdown (or raw JSONL) for Feishu.
+ *
+ * The Web UI exports ZIPs with a browser-side download; IM must do its own
+ * rendering, so this module reads the session log (provided by a service seam or
+ * the on-disk JSONL/Zstd log) and writes a bounded local file that the MEDIA
+ * chain can send.
+ *
+ * @module dsh-caduceus/export
+ */
+import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, sep } from 'node:path';
+import { zstdDecompressSync } from 'node:zlib';
+export const EXPORT_MAX_BYTES = 5 * 1024 * 1024;
+const TRUNCATED_MARKER = '\n\n> 导出内容超过 5MB，已截断。\n';
+export function truncateExport(text) {
+    return truncateUtf8(text, TRUNCATED_MARKER);
+}
+function truncateUtf8(text, marker) {
+    if (Buffer.byteLength(text, 'utf8') <= EXPORT_MAX_BYTES)
+        return text;
+    const budget = EXPORT_MAX_BYTES - Buffer.byteLength(marker, 'utf8');
+    return Buffer.from(text, 'utf8').subarray(0, Math.max(0, budget)).toString('utf8') + marker;
+}
+function textFromContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const record = block;
+        if (record.type === 'text' && typeof record.text === 'string')
+            parts.push(record.text);
+    }
+    return parts.join('\n');
+}
+export function parseSessionEvents(events) {
+    return messagesFromJsonl(events.map((event) => JSON.stringify(event)).join('\n'));
+}
+function messagesFromJsonl(raw) {
+    const messages = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof event !== 'object' || event === null)
+            continue;
+        const record = event;
+        const type = typeof record.type === 'string' ? record.type : '';
+        const data = (record.data ?? {});
+        const message = (data['message'] ?? {});
+        const text = textFromContent(message['content'] ?? data['content']);
+        if (text.length === 0)
+            continue;
+        if (type === 'user/message') {
+            messages.push({ role: 'user', text });
+        }
+        else if (type === 'assistant/message') {
+            messages.push({ role: 'assistant', text });
+        }
+        else if (type === 'tool/result') {
+            const toolName = (typeof data['toolName'] === 'string' && data['toolName']) ||
+                (typeof data['name'] === 'string' && data['name']) ||
+                (typeof message['name'] === 'string' && message['name']) ||
+                'tool';
+            messages.push({ role: 'tool', toolName, text });
+        }
+    }
+    return messages;
+}
+/** Locate the newest `session[.vN].jsonl[.zstd]` belonging to one session. */
+export function findSessionLog(sessionId, dshHome) {
+    const root = join(dshHome, 'sessions');
+    const candidates = [];
+    const walk = (dir, depth) => {
+        if (depth > 8)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(path, depth + 1);
+                continue;
+            }
+            if (!/^session(?:\.[^/]+)?\.jsonl(?:\.zstd)?$/.test(entry.name))
+                continue;
+            if (!path.split(sep).includes(sessionId))
+                continue;
+            try {
+                candidates.push({ path, mtime: statSync(path).mtimeMs });
+            }
+            catch {
+                // ignore unreadable files
+            }
+        }
+    };
+    walk(root, 0);
+    return candidates.sort((left, right) => right.mtime - left.mtime)[0]?.path;
+}
+/**
+ * Read a session log directly from `$DSH_HOME/sessions`.
+ *
+ * @throws Error with a user-readable message when the log or zstd support is missing.
+ */
+export function readSessionLogFile(sessionId, dshHome = process.env['DSH_HOME'] ?? join(homedir(), '.dsh')) {
+    const path = findSessionLog(sessionId, dshHome);
+    if (path === undefined)
+        return undefined;
+    const bytes = readFileSync(path);
+    let raw;
+    if (path.endsWith('.zstd')) {
+        const decompress = zstdDecompressSync;
+        if (typeof decompress !== 'function') {
+            throw new Error('当前 Node.js 不支持 zstd 解压，无法读取会话日志');
+        }
+        raw = decompress(bytes).toString('utf8');
+    }
+    else {
+        raw = bytes.toString('utf8');
+    }
+    return { messages: messagesFromJsonl(raw), rawJsonl: raw };
+}
+/** Markdown export with a bounded file size. */
+export function renderExportMarkdown(input) {
+    const lines = [
+        '# dsh 会话导出',
+        '',
+        `- sessionId: ${input.sessionId}`,
+        `- 标题: ${input.title ?? '（无标题）'}`,
+        `- 导出时间: ${new Date(input.now).toISOString()}`,
+        `- 消息数: ${input.messages.length}`,
+        '',
+    ];
+    for (const message of input.messages) {
+        lines.push(`## ${message.role}${message.toolName === undefined ? '' : `: ${message.toolName}`}`);
+        lines.push('```');
+        lines.push(message.text);
+        lines.push('```');
+        lines.push('');
+    }
+    return truncateUtf8(lines.join('\n'), TRUNCATED_MARKER);
+}
+/** Raw JSONL export (one normalized message per line, bounded). */
+export function renderExportJsonl(messages) {
+    const raw = messages.map((message) => JSON.stringify(message)).join('\n') + '\n';
+    return truncateUtf8(raw, TRUNCATED_MARKER.trim());
+}
+/** Timestamp used in readable export filenames. */
+function exportStamp(now) {
+    const date = new Date(now);
+    const pad = (value) => String(value).padStart(2, '0');
+    return (String(date.getFullYear()) +
+        pad(date.getMonth() + 1) +
+        pad(date.getDate()) +
+        '-' +
+        pad(date.getHours()) +
+        pad(date.getMinutes()) +
+        pad(date.getSeconds()));
+}
+/** Write one export file into the cache directory; returns the absolute path. */
+export function writeExportFile(directory, scopeKind, sessionId, extension, content, now) {
+    mkdirSync(directory, { recursive: true });
+    const kind = scopeKind.replace(/[^a-z0-9-]+/gi, '-') || 'chat';
+    const target = join(directory, `caduceus-${kind}-${sessionId.slice(-8)}-${exportStamp(now)}.${extension}`);
+    writeFileSync(target, content);
+    return target;
+}
+/**
+ * Remove export-cache files older than `maxAgeHours`. A missing directory is
+ * fine; any filesystem error is logged as one warn and never thrown.
+ */
+export function cleanupExportCache(directory, maxAgeHours, now = Date.now(), logger) {
+    let entries;
+    try {
+        entries = readdirSync(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            logger?.warn(`export cache cleanup failed for ${directory}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return { removed: 0, kept: 0 };
+    }
+    const maxAgeMs = maxAgeHours * 60 * 60 * 1000;
+    let removed = 0;
+    let kept = 0;
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.startsWith('caduceus-'))
+            continue;
+        const path = join(directory, entry.name);
+        try {
+            const age = now - statSync(path).mtimeMs;
+            if (age > maxAgeMs) {
+                unlinkSync(path);
+                removed += 1;
+            }
+            else {
+                kept += 1;
+            }
+        }
+        catch (error) {
+            logger?.warn(`export cache cleanup skipped ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    logger?.info(`export cache: removed=${removed} kept=${kept}`);
+    return { removed, kept };
+}

package/dist/home.d.ts

@@ -34,5 +34,7 @@ export declare function defaultSoulCandidatePaths(env?: HomeEnv): readonly strin
 export declare function defaultAgentsFile(env?: HomeEnv): string;
 /** Legacy target written by older caduceus builds: `<DSH_AGENTS_HOME>/AGENTS.md`. */
 export declare function legacyAgentsFile(env?: HomeEnv): string;
+/** Export cache directory: `<DSH_HOME>/caduceus/cache/exports`. */
+export declare function defaultExportCacheDir(env?: HomeEnv): string;
 /** Default durable log file: `<DSH_HOME>/caduceus/caduceus.log`. */
 export declare function defaultLogPath(env?: HomeEnv): string;

package/dist/home.js

@@ -62,6 +62,10 @@ export function defaultAgentsFile(env) {
 export function legacyAgentsFile(env) {
     return join(agentsHome(env), 'AGENTS.md');
 }
+/** Export cache directory: `<DSH_HOME>/caduceus/cache/exports`. */
+export function defaultExportCacheDir(env) {
+    return join(dshHome(env), 'caduceus', 'cache', 'exports');
+}
 /** Default durable log file: `<DSH_HOME>/caduceus/caduceus.log`. */
 export function defaultLogPath(env) {
     return join(dshHome(env), 'caduceus', 'caduceus.log');

package/dist/i18n.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Surface i18n for the permission UI.
+ *
+ * Language order:
+ * 1. explicit plugin config `lang: zh|en` (never consults settings/env);
+ * 2. `lang: auto` -> host `locale.preference`;
+ * 3. `lang: auto` -> LC_ALL/LANG, accepted only when the value starts with
+ *    `zh` or `en` (C/C.UTF-8/POSIX/empty are ignored);
+ * 4. zh.
+ *
+ * Settings access is best-effort and never cached: a missing service must not
+ * break or stick on a failure.
+ *
+ * @module dsh-caduceus/i18n
+ */
+export type Lang = 'zh' | 'en';
+export type LangSetting = Lang | 'auto';
+export interface PermissionLineData {
+    readonly name: string;
+    readonly sandbox?: string;
+    readonly approval?: string;
+}
+export interface Dict {
+    permissionTitle(currentLabel: string): string;
+    customLabel: string;
+    usage: string;
+    approvalLine(label: string, approval: string): string;
+    approvalLabel(value: string): string;
+    switchSucceeded(label: string, hint: string): string;
+    unknownPreset(name: string, available: string): string;
+    switchedElsewhere(text: string): string;
+}
+/** Official display label for one preset; unknown presets keep their raw name. */
+export declare function presetLabel(lang: Lang, name: string): string;
+export declare function t(lang: Lang): Dict;
+/**
+ * Resolve the effective language.
+ *
+ * Overload note: `resolveLang(provider)` is treated as `lang: auto` with that
+ * settings provider (kept for the original call sites).
+ */
+export declare function resolveLang(langOrProvider?: LangSetting | (() => unknown), maybeProvider?: () => unknown): Lang;

package/dist/i18n.js

@@ -0,0 +1,94 @@
+/** Official dsh preset labels (client ui-permission-presets locales). */
+const ZH_LABELS = {
+    'read-only': '仅可查看',
+    'workspace-write': '工作区内修改',
+    'danger-full-access': '完全权限',
+    auto: '自动审查（EXP）',
+};
+const EN_LABELS = {
+    'read-only': 'Read Only',
+    'workspace-write': 'Workspace Write',
+    'danger-full-access': 'Full access',
+    auto: 'Auto review (EXP)',
+};
+/** Official display label for one preset; unknown presets keep their raw name. */
+export function presetLabel(lang, name) {
+    const labels = lang === 'en' ? EN_LABELS : ZH_LABELS;
+    return labels[name] ?? name;
+}
+function approvalLabelZh(value) {
+    if (value === 'ask')
+        return '人工确认';
+    if (value === 'never')
+        return '从不';
+    return value;
+}
+function approvalLabelEn(value) {
+    if (value === 'ask')
+        return 'manual confirmation';
+    if (value === 'never')
+        return 'never';
+    return value;
+}
+const ZH = {
+    permissionTitle: (label) => '权限 · 当前：' + label,
+    customLabel: '自定义（不匹配任何预设）',
+    usage: '用法：/permission <档位>，或点下方按钮',
+    approvalLine: (label, approval) => '档位 ' + label + ' · 审批 ' + approval,
+    approvalLabel: approvalLabelZh,
+    switchSucceeded: (label, hint) => '已切换到 ' + label + '（' + hint + '）',
+    unknownPreset: (name, available) => '未知档位 ' + name + '，可用：' + available,
+    switchedElsewhere: (text) => '已执行 /permission（dsh 原文：' + text + '）',
+};
+const EN = {
+    permissionTitle: (label) => 'Permission · current: ' + label,
+    customLabel: 'Custom (matches no preset)',
+    usage: 'Usage: /permission <preset>, or tap a button below',
+    approvalLine: (label, approval) => 'preset ' + label + ' · approval ' + approval,
+    approvalLabel: approvalLabelEn,
+    switchSucceeded: (label, hint) => 'Switched to ' + label + ' (' + hint + ')',
+    unknownPreset: (name, available) => 'Unknown preset ' + name + '; available: ' + available,
+    switchedElsewhere: (text) => 'Ran /permission (dsh output: ' + text + ')',
+};
+export function t(lang) {
+    return lang === 'en' ? EN : ZH;
+}
+/**
+ * Resolve the effective language.
+ *
+ * Overload note: `resolveLang(provider)` is treated as `lang: auto` with that
+ * settings provider (kept for the original call sites).
+ */
+export function resolveLang(langOrProvider, maybeProvider) {
+    const configured = typeof langOrProvider === 'function' ? 'auto' : (langOrProvider ?? 'auto');
+    const provider = typeof langOrProvider === 'function' ? langOrProvider : maybeProvider;
+    // Explicit configuration always wins over settings and environment.
+    if (configured === 'zh' || configured === 'en')
+        return configured;
+    try {
+        const settings = provider?.();
+        if (settings !== undefined && settings !== null) {
+            const candidate = settings;
+            let section;
+            if (typeof candidate.get === 'function')
+                section = candidate.get('locale');
+            else if (typeof candidate.describe === 'function') {
+                section = candidate.describe().find((entry) => entry.ns === 'locale')?.value;
+            }
+            const record = section;
+            const value = typeof record?.get === 'function' ? record.get() : record;
+            const preference = value?.preference;
+            if (preference === 'zh' || preference === 'en')
+                return preference;
+        }
+    }
+    catch {
+        // Missing/partial settings service: fall through to environment.
+    }
+    const locale = (process.env['LC_ALL'] ?? process.env['LANG'] ?? '').trim().toLowerCase();
+    if (locale.startsWith('zh'))
+        return 'zh';
+    if (locale.startsWith('en'))
+        return 'en';
+    return 'zh';
+}