berry-agent-sdk 0.1.0-alpha.2

package/dist/src/agent/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * agent 件 — loop 骨架的类型面（04 篇 §2 回调面 11 项 + 入口两式签名）。
+ *
+ * loop 是纯机制：全部策略经注入回调表达、全部状态经事件与投影回流——
+ * conversation 是缺省供给方（组装回调并注入），loop 不知道 conversation 存在。
+ * 类型独立成件：loop.ts 只留双 while 骨架本体（≤150 行形态铁律的码面兑现）。
+ */
+import type { AgentMessage } from '../contracts/index.js';
+import type { AssistantMessage, LlmContext, Message, StreamFn, ThinkingLevel, ToolResultMessage } from '../contracts/index.js';
+import type { AgentTool, AgentToolCall, AgentToolResult, ToolUpdateCallback } from '../contracts/index.js';
+import type { AgentEvent, AgentEventSink } from './events.js';
+/** loop 运行上下文（messages 是活数组——loop 读写、驱动侧共享同引用） */
+export interface AgentContext {
+    /** 系统提示词（每次请求组装进 LlmContext） */
+    systemPrompt?: string;
+    /** 会话消息活数组（种子/流终值/工具结果都在此累积） */
+    messages: AgentMessage[];
+    /** 本 run 可用工具集（缺省空——纯对话 run） */
+    tools?: AgentTool[];
+    /**
+     * 闸①幂等账本（04 §2 call_id 幂等决策）：call_id → 既有结果消息。挂
+     * context（driver 终身单实例持有）→ 批内 + 跨轮 + 重试续入三域同律共享
+     * （重试续入 = 新 startRun 同 context——已执行条目直接回执既有结果）。
+     * 只持既有结果消息的引用（消息本就活在 messages 数组——零复制零逐出）；
+     * 超帽丢尾腿与中止配对腿不进账本（未执行条目无「既有结果」可回执）。
+     * 懒初始化（executeToolBatch 首达建账）。
+     */
+    toolResultLedger?: Map<string, ToolResultMessage>;
+}
+/** beforeToolCall 决策（守门行安装点）：block = 不执行直接回错误结果；terminate 记账批内一致裁决 */
+export interface BeforeToolCallDecision {
+    /** 拒因（进 isError 结果 content；守门 deny 面） */
+    block?: string;
+    /** 终止旗标——批内全 terminate 才 terminate（单件否决不放大） */
+    terminate?: boolean;
+}
+/** turn 间换装变更（prepareNextTurn 返回——换 context/model/thinkingLevel 的唯一时机） */
+export interface TurnAdjustment {
+    /** 换模型（下一 turn 起生效） */
+    model?: string;
+    /** 换思考档位（下一 turn 起生效） */
+    thinkingLevel?: ThinkingLevel;
+}
+/**
+ * loop 回调面（04 §2 全部注入点——缺省供给方 conversation）。
+ * loop 层零重试：失败即 run failed；turn auto-retry/overflow 兜底归 conversation 件。
+ */
+export interface AgentLoopConfig {
+    /** 流式调用体（永不抛——契约见 contracts/llm.ts StreamFn；金样回放轨 seam） */
+    streamFn: StreamFn;
+    /** 模型 id（prepareNextTurn 可逐轮换装） */
+    model: string;
+    /** 思考档位（会话态投影入 run——run 内经 prepareNextTurn 可换） */
+    thinkingLevel?: ThinkingLevel;
+    /** timeline 消息 → LLM 消息转写（自定义角色降写、瞬态注入剥离；null = 剥离） */
+    convertToLlm: (message: AgentMessage) => Message | Message[] | null;
+    /** 请求组装最后关口（记忆检索瞬态注入在此挂） */
+    transformContext?: (context: LlmContext) => LlmContext | Promise<LlmContext>;
+    /**
+     * 每次模型请求前钩（03 §2.4 agent_pre_step 发射窗——04 §2/§5）：loop
+     * while 体顶、steering 消费与 turn_start 之前调用；返回 'stop' 即本 turn
+     * 不起模型请求、run 以 stopReason 'stop' 收 completed（预算刹停不产生
+     * dangling turn）。驱动侧分派 waterfall（载荷 PreStepInput——提醒注入
+     * 槽 + 刹车位）。
+     */
+    preModelRequest?: (context: AgentContext) => 'stop' | void | Promise<'stop' | void>;
+    /** 凭证取用（缺省 undefined 走 llm 层持久化凭证链） */
+    getApiKey?: (model: string) => string | undefined;
+    /** turn 终止裁决（停止词、预算尽、打断——返回 true 优雅停 completed） */
+    shouldStopAfterTurn?: (context: AgentContext, lastMessage: AssistantMessage) => boolean | Promise<boolean>;
+    /** turn 间准备（todo 同段回显/goal 轮间沉淀注入窗 + 换装唯一时机） */
+    prepareNextTurn?: (context: AgentContext) => void | TurnAdjustment | Promise<void | TurnAdjustment>;
+    /** busy 注入通道取件（每 turn 顶查——返回空数组即无） */
+    getSteeringMessages?: () => AgentMessage[];
+    /** idle 起跑通道取件（自然停候选时查——空即 run 收 completed） */
+    getFollowUpMessages?: () => AgentMessage[];
+    /** 工具调用前置钩子（守门行安装点；可返回 block 拒因或 terminate 旗标） */
+    beforeToolCall?: (toolCall: AgentToolCall, context: AgentContext) => BeforeToolCallDecision | void | Promise<BeforeToolCallDecision | void>;
+    /** 工具结果后置钩子（字段级整体替换——返回新消息替换默认组装形） */
+    afterToolCall?: (toolCall: AgentToolCall, result: AgentToolResult, message: AgentContext['messages'][number], context: AgentContext) => AgentMessage | void | Promise<AgentMessage | void>;
+    /** 工具执行体替换点（测试注金样 seam 同族；缺省走 tool.execute） */
+    toolExecution?: (tool: AgentTool, toolCallId: string, arguments_: Record<string, unknown>, signal?: AbortSignal, onUpdate?: ToolUpdateCallback) => Promise<AgentToolResult>;
+    /** 活体事件汇（10 型内存直推） */
+    onEvent?: AgentEventSink;
+    /** 中止信号（透传 streamFn 与工具 execute——协作面） */
+    signal?: AbortSignal;
+    /**
+     * 单响应工具批调用数上限（04 §2 闸②）：单次模型响应的工具批超帽即丢尾
+     * ——被丢 calls 逐个配对 isError toolResult（原因注明超限）+ 丢弃计数暴露
+     * （ToolBatchOutcome.droppedCount，非静默）。缺省
+     * DEFAULT_MAX_TOOL_CALLS_PER_RESPONSE（32）；负值按 0 处理（0 = 拒全批）。
+     */
+    maxToolCallsPerResponse?: number;
+}
+/** run 结算（终态恰三值——Job 结算、审批对收口、预算记账截断的锚） */
+export interface RunResult {
+    status: import('./events.js').RunStatus;
+    /** 末次流终态（诊断面；status 三值与 stopReason 的映射见 loop.ts endRun） */
+    stopReason?: import('../contracts/llm.js').StopReason;
+    /** stopReason=error 时的错误文本（终值消息 errorMessage 同源） */
+    errorMessage?: string;
+}
+/** 活体事件发射器（loop 与辅助件共用的小闭包形——void/Promise 双形兼容） */
+export type EmitFn = (event: AgentEvent) => void;

package/dist/src/agent/types.js

@@ -0,0 +1,9 @@
+/**
+ * agent 件 — loop 骨架的类型面（04 篇 §2 回调面 11 项 + 入口两式签名）。
+ *
+ * loop 是纯机制：全部策略经注入回调表达、全部状态经事件与投影回流——
+ * conversation 是缺省供给方（组装回调并注入），loop 不知道 conversation 存在。
+ * 类型独立成件：loop.ts 只留双 while 骨架本体（≤150 行形态铁律的码面兑现）。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/src/channels/ask-queue.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 提问队列（07 §4.3 提问队列机制正文——2026-09-06 channels 纵切批补写）：
+ * 阻塞原语（confirm/select/input）与审批 ask 统一入 per-session FIFO——
+ * 队首才呈现、应答即出队、后继顶上（「无并存态」即此律）。
+ *
+ * 收口三则（规范同条）：会话关闭按 sessionId 清队（余项按取消语义收场——
+ * 保守值同撤销面）；run 打断信号穿透队内该 run 发起的 ask（signal 由调用方
+ * ui-core 携带，队列不感知 run）；队列是内存态、崩溃即丢（durable 真相在
+ * 审批日志不在队列——与 04 §4 PendingMessageQueue 同纪）。
+ *
+ * 队列持在通道核、呈现形态归后端（TUI overlay 是队首呈现之一）——本类只管
+ * 排序与收口，backend 编舞（竞速/撤销说明行）归 ui-core。
+ */
+import type { AskKind } from './types.js';
+/** 队项钩子：start = 晋升队首（发后端）；cancel = 取消收场（含在飞态——保守值 + 撤销归 ui-core） */
+export interface AskHooks {
+    /** 晋升队首：真正发给后端（overlay 占焦等呈现态由此起） */
+    readonly start: () => void;
+    /** 取消收场：排队中（未 start）与在飞（已 start 未 settle）两态都可达——保守值结算 + 后端撤销 */
+    readonly cancel: () => void;
+}
+/**
+ * 提问队列（per-session FIFO）。同会话严格串行（队首在飞时后继排队）；
+ * 异会话队列独立（各自队首并行——呈现并存的裁决归后端 overlay 层）。
+ */
+export declare class AskQueue {
+    private readonly sessions;
+    private ensure;
+    /** 入队：会话队列空闲即直晋队首（start 同步调用——FIFO 无空转窗）；否则排队 */
+    enqueue(sessionId: string, kind: AskKind, hooks: AskHooks): void;
+    /**
+     * 队首落定（应答/保守值收场都算——由 ui-core 在 promise 链尾调用）：
+     * 出队、后继顶上。未知会话/已清队 no-op（clearSession 后迟到落定不炸）。
+     */
+    settled(sessionId: string): void;
+    /**
+     * 会话收口（04 §9 归属围栏通道侧执法）：清排队项 + 取消在飞队首——
+     * 全部走 cancel（保守值同撤销面：confirm→false / select·input→''、
+     * approval→cancelled 语义由 ui-core 落）。
+     */
+    clearSession(sessionId: string): void;
+    /** 观察面：会话在飞+排队项 kind 序列（测试与 /help 类诊断面消费） */
+    pending(sessionId: string): readonly AskKind[];
+}

package/dist/src/channels/ask-queue.js

@@ -0,0 +1,83 @@
+/**
+ * 提问队列（07 §4.3 提问队列机制正文——2026-09-06 channels 纵切批补写）：
+ * 阻塞原语（confirm/select/input）与审批 ask 统一入 per-session FIFO——
+ * 队首才呈现、应答即出队、后继顶上（「无并存态」即此律）。
+ *
+ * 收口三则（规范同条）：会话关闭按 sessionId 清队（余项按取消语义收场——
+ * 保守值同撤销面）；run 打断信号穿透队内该 run 发起的 ask（signal 由调用方
+ * ui-core 携带，队列不感知 run）；队列是内存态、崩溃即丢（durable 真相在
+ * 审批日志不在队列——与 04 §4 PendingMessageQueue 同纪）。
+ *
+ * 队列持在通道核、呈现形态归后端（TUI overlay 是队首呈现之一）——本类只管
+ * 排序与收口，backend 编舞（竞速/撤销说明行）归 ui-core。
+ */
+/**
+ * 提问队列（per-session FIFO）。同会话严格串行（队首在飞时后继排队）；
+ * 异会话队列独立（各自队首并行——呈现并存的裁决归后端 overlay 层）。
+ */
+export class AskQueue {
+    sessions = new Map();
+    ensure(sessionId) {
+        let q = this.sessions.get(sessionId);
+        if (q === undefined) {
+            q = { pending: [], active: null };
+            this.sessions.set(sessionId, q);
+        }
+        return q;
+    }
+    /** 入队：会话队列空闲即直晋队首（start 同步调用——FIFO 无空转窗）；否则排队 */
+    enqueue(sessionId, kind, hooks) {
+        const q = this.ensure(sessionId);
+        if (q.active === null) {
+            q.active = { kind, hooks };
+            hooks.start();
+        }
+        else {
+            q.pending.push({ kind, hooks });
+        }
+    }
+    /**
+     * 队首落定（应答/保守值收场都算——由 ui-core 在 promise 链尾调用）：
+     * 出队、后继顶上。未知会话/已清队 no-op（clearSession 后迟到落定不炸）。
+     */
+    settled(sessionId) {
+        const q = this.sessions.get(sessionId);
+        if (q === undefined)
+            return;
+        if (q.active === null)
+            return; // 空转（迟到落定）——幂等
+        const next = q.pending.shift();
+        if (next === undefined) {
+            q.active = null; // 队列清空（会话条目留存——防高频重建；clearSession 才真清）
+        }
+        else {
+            q.active = next;
+            next.hooks.start();
+        }
+    }
+    /**
+     * 会话收口（04 §9 归属围栏通道侧执法）：清排队项 + 取消在飞队首——
+     * 全部走 cancel（保守值同撤销面：confirm→false / select·input→''、
+     * approval→cancelled 语义由 ui-core 落）。
+     */
+    clearSession(sessionId) {
+        const q = this.sessions.get(sessionId);
+        if (q === undefined)
+            return;
+        const all = q.active === null ? [...q.pending] : [q.active, ...q.pending];
+        q.pending.length = 0;
+        q.active = null;
+        this.sessions.delete(sessionId);
+        // 逐项 cancel：在飞与排队同语义收场（cancel 实现须幂等——settled 迟到不双结）
+        for (const item of all)
+            item.hooks.cancel();
+    }
+    /** 观察面：会话在飞+排队项 kind 序列（测试与 /help 类诊断面消费） */
+    pending(sessionId) {
+        const q = this.sessions.get(sessionId);
+        if (q === undefined)
+            return [];
+        return q.active === null ? q.pending.map((p) => p.kind) : [q.active.kind, ...q.pending.map((p) => p.kind)];
+    }
+}
+//# sourceMappingURL=ask-queue.js.map

package/dist/src/channels/ask-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-queue.js","sourceRoot":"","sources":["../../../../../src/channels/ask-queue.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/commands.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 命令面注册表与分发（03 §2.2 registerCommand 签名定形 + §2.7 冲突律；
+ * 2026-09-06 channels 纵切批）。
+ *
+ * 两律：①后写胜出——命令名是可换实现位（用户插件覆盖 core: 同名命令 =
+ * 显式换装正道），撞名不拒、胜出即生效；②词法违例拒——命令名主段连字符式
+ * + 可选冒号子段，非法名拒绝注册（CHANNEL_COMMAND_INVALID——与
+ * AGENT_ROLE_INVALID 同构：撞名不拒、格式拒）。
+ */
+import type { Disposer } from '../context/index.js';
+import type { CommandArgs, CommandHandler, CommandSpec } from './types.js';
+/**
+ * 命令面注册表。注册即生效（03 §2.1——下一次消费点重取，不待重启）；
+ * 全部方法同步（注册/查询/解析零 I/O，分发是唯一异步面）。
+ */
+export declare class CommandRegistry {
+    private readonly commands;
+    /** 注册代币发生器（每注册一枚新 token——disposer 校验「自己仍是现任」用） */
+    private tokenSeed;
+    /**
+     * 注册命令（后写胜出）。词法违例抛 CHANNEL_COMMAND_INVALID；撞名静默覆盖
+     * （03 §2.7：胜出即生效无拒码）。
+     *
+     * @returns disposer——注销该命令；若已被后写覆盖则 no-op（不误注接任者）
+     */
+    register(name: string, handler: CommandHandler, description?: string): Disposer;
+    /** 命令清单（/help 与 @-mention 补全面的消费面——注册序） */
+    list(): readonly CommandSpec[];
+    /** 按名查询（分发前置——后写胜出者即现任） */
+    get(name: string): CommandSpec | undefined;
+    /**
+     * 解析输入行（同步纯函数面）：`/name rest...` → { name, args }；
+     * 非 `/` 开头返回 null（普通消息路——去哪归驱动侧/conversation 裁决，
+     * 命令面只报「不是命令」）。
+     */
+    parse(input: string): {
+        name: string;
+        args: CommandArgs;
+    } | null;
+    /**
+     * 分发输入行：命中注册命令 → 执行 handler 返回 true；未命中（非命令形或
+     * 名不在册）返回 false——「未注册的 /词 怎么处置（提示未知命令 or 当普通
+     * 消息进 run）」是驱动侧语义，归 conversation 件。
+     *
+     * sessionId 位（ix-2 新建）：发起会话透传进 CommandArgs（CLI 面缺席）——
+     * 插件命令 handler 可显式携带（ctx.ui opts.sessionId 透传），ambient 自动
+     * 锚另由 host 侧 ALS 承载（两轨并行——显式位是插件可见面、ALS 是零自觉面）。
+     */
+    dispatch(input: string, sessionId?: string): Promise<boolean>;
+}
+/**
+ * 引号感知词切分（03 §2.2 定形：shell 词法的最小实现——不进 glob/变量展开）。
+ * 规则：裸词按空白切；'单引号' 保字面（内部再无转义）；"双引号" 保内部空格；
+ * 引号未闭合按行尾收口（宽容收场——终端输入无第二行可续）。
+ */
+export declare function tokenize(raw: string): string[];

package/dist/src/channels/commands.js

@@ -0,0 +1,130 @@
+/**
+ * 命令面注册表与分发（03 §2.2 registerCommand 签名定形 + §2.7 冲突律；
+ * 2026-09-06 channels 纵切批）。
+ *
+ * 两律：①后写胜出——命令名是可换实现位（用户插件覆盖 core: 同名命令 =
+ * 显式换装正道），撞名不拒、胜出即生效；②词法违例拒——命令名主段连字符式
+ * + 可选冒号子段，非法名拒绝注册（CHANNEL_COMMAND_INVALID——与
+ * AGENT_ROLE_INVALID 同构：撞名不拒、格式拒）。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 命令名词法（03 §2.2 定形：^[a-z][a-z0-9-]*(:[a-z0-9-]+)?$——/memory-export 与 /skill:name 实况同形） */
+const COMMAND_NAME_RE = /^[a-z][a-z0-9-]*(?::[a-z0-9-]+)?$/;
+/**
+ * 命令面注册表。注册即生效（03 §2.1——下一次消费点重取，不待重启）；
+ * 全部方法同步（注册/查询/解析零 I/O，分发是唯一异步面）。
+ */
+export class CommandRegistry {
+    commands = new Map();
+    /** 注册代币发生器（每注册一枚新 token——disposer 校验「自己仍是现任」用） */
+    tokenSeed = 0;
+    /**
+     * 注册命令（后写胜出）。词法违例抛 CHANNEL_COMMAND_INVALID；撞名静默覆盖
+     * （03 §2.7：胜出即生效无拒码）。
+     *
+     * @returns disposer——注销该命令；若已被后写覆盖则 no-op（不误注接任者）
+     */
+    register(name, handler, description) {
+        if (!COMMAND_NAME_RE.test(name)) {
+            throw new BaseError('CHANNEL_COMMAND_INVALID', `命令名词法违例：${JSON.stringify(name)}（主段连字符式 + 可选冒号子段，小写）`);
+        }
+        const token = { seed: this.tokenSeed++ };
+        this.commands.set(name, { name, handler, description, token });
+        return () => {
+            // 只有现任可注（token 相等 = 未被后写覆盖）——后写的接任者不因旧 disposer 被误注
+            const current = this.commands.get(name);
+            if (current !== undefined && current.token === token) {
+                this.commands.delete(name);
+            }
+        };
+    }
+    /** 命令清单（/help 与 @-mention 补全面的消费面——注册序） */
+    list() {
+        return [...this.commands.values()].map(({ token: _token, ...spec }) => spec);
+    }
+    /** 按名查询（分发前置——后写胜出者即现任） */
+    get(name) {
+        const entry = this.commands.get(name);
+        return entry === undefined
+            ? undefined
+            : { name: entry.name, handler: entry.handler, description: entry.description };
+    }
+    /**
+     * 解析输入行（同步纯函数面）：`/name rest...` → { name, args }；
+     * 非 `/` 开头返回 null（普通消息路——去哪归驱动侧/conversation 裁决，
+     * 命令面只报「不是命令」）。
+     */
+    parse(input) {
+        if (!input.startsWith('/'))
+            return null;
+        // 首空白分割命令名与实参原文（命令名自身无空白——词法保证）
+        const rest = input.slice(1);
+        const sep = rest.search(/\s/);
+        const name = sep === -1 ? rest : rest.slice(0, sep);
+        const raw = sep === -1 ? '' : rest.slice(sep + 1).trim();
+        if (!COMMAND_NAME_RE.test(name))
+            return null;
+        return { name, args: { raw, argv: tokenize(raw) } };
+    }
+    /**
+     * 分发输入行：命中注册命令 → 执行 handler 返回 true；未命中（非命令形或
+     * 名不在册）返回 false——「未注册的 /词 怎么处置（提示未知命令 or 当普通
+     * 消息进 run）」是驱动侧语义，归 conversation 件。
+     *
+     * sessionId 位（ix-2 新建）：发起会话透传进 CommandArgs（CLI 面缺席）——
+     * 插件命令 handler 可显式携带（ctx.ui opts.sessionId 透传），ambient 自动
+     * 锚另由 host 侧 ALS 承载（两轨并行——显式位是插件可见面、ALS 是零自觉面）。
+     */
+    async dispatch(input, sessionId) {
+        const parsed = this.parse(input);
+        if (parsed === null)
+            return false;
+        const spec = this.commands.get(parsed.name);
+        if (spec === undefined)
+            return false;
+        await spec.handler(sessionId !== undefined ? { ...parsed.args, sessionId } : parsed.args);
+        return true;
+    }
+}
+/**
+ * 引号感知词切分（03 §2.2 定形：shell 词法的最小实现——不进 glob/变量展开）。
+ * 规则：裸词按空白切；'单引号' 保字面（内部再无转义）；"双引号" 保内部空格；
+ * 引号未闭合按行尾收口（宽容收场——终端输入无第二行可续）。
+ */
+export function tokenize(raw) {
+    const out = [];
+    let current = '';
+    let hasCurrent = false;
+    let quote = null;
+    for (const ch of raw) {
+        if (quote !== null) {
+            if (ch === quote) {
+                quote = null; // 引号闭合——段继续累积（拼接态 "ab'cd ef'" 保空格）
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            hasCurrent = true; // 空引号段 '' 也是一段（与裸词不同——显式空串）
+            continue;
+        }
+        if (ch === ' ' || ch === '\t') {
+            if (hasCurrent) {
+                out.push(current);
+                current = '';
+                hasCurrent = false;
+            }
+            continue;
+        }
+        current += ch;
+        hasCurrent = true;
+    }
+    // 行尾：未闭合引号宽容收口（current 原样成段）；尾段在
+    if (hasCurrent)
+        out.push(current);
+    return out;
+}
+//# sourceMappingURL=commands.js.map

package/dist/src/channels/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../../../src/channels/commands.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/engine/cell.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 缓冲件（07 篇 §4.1 自研引擎节件 3——批 10b 引擎核心）。
+ *
+ * cell 网格模型：每格「码点面 + 样式 + 列宽」三元；宽字符续格与主流终端
+ * 续格形同构（差分按格直比无需行结构感知）；多码点字素覆写摘痕防新旧混叠；
+ * 字素面参与差分自证（同首码点不同字素不得判等——grapheme 存整素串，格直比
+ * 即字素比对，结构自证）。帧路径零分配：网格跨帧复用、clear 只摘格、
+ * resize 是唯一重分配点。
+ */
+import type { Cell, CellBuffer, CellStyle, CursorState } from './types.js';
+/** 全缺省样式常量（格的缺省样式——比较归一用，冻结防漂） */
+export declare const EMPTY_STYLE: Readonly<CellStyle>;
+/** 样式相等（缺省位归一比较——undefined 与 false 同为缺省） */
+export declare function styleEquals(a: CellStyle, b: CellStyle): boolean;
+/**
+ * 单格相等（差分按格直比原语）：null 归一到默认空格格后三元比对——
+ * 「写入的缺省空格」与「未写格」判等（不产生假变更帧）；
+ * 续格（width 0）与空格格判不等（续格是宽字素一部分，占位语义不可丢）。
+ */
+export declare function cellEquals(a: Cell | null, b: Cell | null): boolean;
+/**
+ * CellGrid——CellBuffer 协议实装（一维数组行主序网格；行 / 列界外静默吸收）。
+ *
+ * 摘痕算法（setCell 内执法）：覆写区 [col, col+w) 内既有格若属某宽字素
+ * （首格或续格），先整字摘除（首格 + 全部续格）再写新字素——防「旧宽字素
+ * 右半残留在新字素续格下」的新旧混叠。
+ */
+export declare class CellGrid implements CellBuffer {
+    columns: number;
+    rows: number;
+    /** 网格（行主序一维；null = 未写格——语义投影为缺省空格） */
+    private grid;
+    /** 本帧光标声明终值（末次声明为准；clearCursor 置 null） */
+    private cursorState;
+    constructor(columns?: number, rows?: number);
+    /** 摘格清屏（网格结构复用零分配——帧间清屏 / 全量重绘入口） */
+    clear(): void;
+    getCell(row: number, col: number): Cell | null;
+    setCell(row: number, col: number, grapheme: string, style?: CellStyle): void;
+    writeText(row: number, col: number, text: string, style?: CellStyle): number;
+    setCursor(row: number, col: number): void;
+    clearCursor(): void;
+    get cursor(): CursorState | null;
+    /**
+     * 几何变更（唯一重分配点）：网格整体弃置重分配、内容不搬运——
+     * 「resize 弃旧换新（不做原地搬运——宽字符 reflow 后必失真）」的缓冲侧
+     * 承接，清屏 + 全量重绘兜底归引擎编排件（批 10c）。
+     */
+    resize(columns: number, rows: number): void;
+    /**
+     * 摘痕原语：把 [col, col+span) 区间（含右邻溢出格——被覆字素可能右探一格）
+     * 内牵连的既有宽字素整字摘除。逐格查：续格回溯首格、首格顺摘续格。
+     */
+    private eraseWideGraphemes;
+}

package/dist/src/channels/engine/cell.js

@@ -0,0 +1,144 @@
+import { graphemeWidth, splitGraphemes } from './width.js';
+/** 全缺省样式常量（格的缺省样式——比较归一用，冻结防漂） */
+export const EMPTY_STYLE = Object.freeze({});
+/** 默认格（未写格的语义投影：缺省空格——cellEquals 归一基准） */
+const DEFAULT_CELL = Object.freeze({
+    grapheme: ' ',
+    style: EMPTY_STYLE,
+    width: 1,
+});
+/** 样式相等（缺省位归一比较——undefined 与 false 同为缺省） */
+export function styleEquals(a, b) {
+    return ((a.fg ?? null) === (b.fg ?? null) &&
+        (a.bg ?? null) === (b.bg ?? null) &&
+        !!a.bold === !!b.bold &&
+        !!a.italic === !!b.italic &&
+        !!a.underline === !!b.underline &&
+        !!a.dim === !!b.dim &&
+        !!a.inverse === !!b.inverse);
+}
+/**
+ * 单格相等（差分按格直比原语）：null 归一到默认空格格后三元比对——
+ * 「写入的缺省空格」与「未写格」判等（不产生假变更帧）；
+ * 续格（width 0）与空格格判不等（续格是宽字素一部分，占位语义不可丢）。
+ */
+export function cellEquals(a, b) {
+    const na = a ?? DEFAULT_CELL;
+    const nb = b ?? DEFAULT_CELL;
+    return na.grapheme === nb.grapheme && na.width === nb.width && styleEquals(na.style, nb.style);
+}
+/**
+ * CellGrid——CellBuffer 协议实装（一维数组行主序网格；行 / 列界外静默吸收）。
+ *
+ * 摘痕算法（setCell 内执法）：覆写区 [col, col+w) 内既有格若属某宽字素
+ * （首格或续格），先整字摘除（首格 + 全部续格）再写新字素——防「旧宽字素
+ * 右半残留在新字素续格下」的新旧混叠。
+ */
+export class CellGrid {
+    columns;
+    rows;
+    /** 网格（行主序一维；null = 未写格——语义投影为缺省空格） */
+    grid;
+    /** 本帧光标声明终值（末次声明为准；clearCursor 置 null） */
+    cursorState = null;
+    constructor(columns = 80, rows = 24) {
+        this.columns = columns;
+        this.rows = rows;
+        this.grid = new Array(columns * rows).fill(null);
+    }
+    /** 摘格清屏（网格结构复用零分配——帧间清屏 / 全量重绘入口） */
+    clear() {
+        this.grid.fill(null);
+        this.cursorState = null;
+    }
+    getCell(row, col) {
+        if (row < 0 || row >= this.rows || col < 0 || col >= this.columns)
+            return null;
+        return this.grid[row * this.columns + col] ?? null; // noUncheckedIndexedAccess 归一
+    }
+    setCell(row, col, grapheme, style = EMPTY_STYLE) {
+        // 越界写静默吸收（渲染契约「越界写由缓冲吸收」——组件可信任缓冲兜底）
+        if (row < 0 || row >= this.rows || col < 0 || col >= this.columns)
+            return;
+        const width = graphemeWidth(grapheme);
+        if (width === 0)
+            return; // 零宽字素不占格（splitGraphemes 已合流，防御位）
+        // 摘痕：覆写区内既有宽字素整字摘除（见类注——防新旧混叠）
+        this.eraseWideGraphemes(row, col, width);
+        // 写首格 + 续格（宽字素右界越界时续格截断丢弃——缓冲兜底；渲染层
+        // truncateToWidth 已保证整字不跨界，此为双保险）
+        const base = row * this.columns;
+        this.grid[base + col] = { grapheme, style, width: width };
+        if (width === 2 && col + 1 < this.columns) {
+            this.grid[base + col + 1] = { grapheme: '', style, width: 0 };
+        }
+    }
+    writeText(row, col, text, style) {
+        let cursor = col;
+        for (const g of splitGraphemes(text)) {
+            this.setCell(row, cursor, g, style);
+            cursor += graphemeWidth(g);
+        }
+        return cursor;
+    }
+    setCursor(row, col) {
+        this.cursorState = { row, col, visible: true };
+    }
+    clearCursor() {
+        this.cursorState = null;
+    }
+    get cursor() {
+        return this.cursorState;
+    }
+    /**
+     * 几何变更（唯一重分配点）：网格整体弃置重分配、内容不搬运——
+     * 「resize 弃旧换新（不做原地搬运——宽字符 reflow 后必失真）」的缓冲侧
+     * 承接，清屏 + 全量重绘兜底归引擎编排件（批 10c）。
+     */
+    resize(columns, rows) {
+        this.columns = columns;
+        this.rows = rows;
+        this.grid = new Array(columns * rows).fill(null);
+        this.cursorState = null;
+    }
+    /**
+     * 摘痕原语：把 [col, col+span) 区间（含右邻溢出格——被覆字素可能右探一格）
+     * 内牵连的既有宽字素整字摘除。逐格查：续格回溯首格、首格顺摘续格。
+     */
+    eraseWideGraphemes(row, col, span) {
+        const base = row * this.columns;
+        for (let i = col; i <= Math.min(col + span, this.columns - 1); i++) {
+            const cell = this.grid[base + i];
+            if (!cell)
+                continue;
+            if (cell.width === 0) {
+                // 续格：回溯其首格并整字摘除
+                let head = i - 1;
+                while (head >= 0) {
+                    const probe = this.grid[base + head];
+                    if (probe && probe.width !== 0)
+                        break;
+                    head--;
+                }
+                if (head >= 0 && this.grid[base + head]?.width === 2) {
+                    this.grid[base + head] = null;
+                    // 顺摘首格右侧全部续格（可能多格？——续格恰一格，但防御性扫到非续格止）
+                    let tail = head + 1;
+                    while (tail < this.columns && this.grid[base + tail]?.width === 0) {
+                        this.grid[base + tail] = null;
+                        tail++;
+                    }
+                }
+                this.grid[base + i] = null;
+            }
+            else if (cell.width === 2) {
+                // 首格：摘自己 + 右侧续格
+                this.grid[base + i] = null;
+                if (i + 1 < this.columns && this.grid[base + i + 1]?.width === 0) {
+                    this.grid[base + i + 1] = null;
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=cell.js.map