Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 首页会话行滑动操作的纯逻辑层(刻意不依赖 react / react-native,便于 node 单测):
* - createSwipeRowRegistry:同一时间只允许一行处于滑开状态的互斥注册表;
* - pinToggleAction / buildSessionActionMenu / swipeActionPatch:
* 「置顶态 → 动作与文案」「选项菜单模型」「动作 → RPC 补丁」的确定性映射,
* 补丁生成直接转发共享层 mobileSessionBulkPatch,不自己拼字段。
*/
import { i18n } from '@/i18n';
import { withTransientRemoteRetry } from '@/device-link/remoteRetry';
import {
mobileSessionBulkPatch,
type MobileSessionBulkPatch,
} from '@/session/sessionSelection';
/** swipe / 选项菜单可触发的全部动作。rename 无补丁形态(走重命名弹窗),单独排除。 */
export type SessionSwipeAction = 'pin' | 'unpin' | 'archive' | 'restore' | 'delete' | 'rename';
export interface SwipeRowRegistry {
/**
* 行开始滑开时上报(swipe 手势起手即调):自动关掉上一个打开的行,并把自己记为当前行。
* 同一行重复上报是 no-op(不会自己关自己)。
*/
onRowOpen(key: string, close: () => void): void;
/**
* 行自己关闭 / 卸载时注销。只有当前记录仍是自己时才清除 —— 关闭动画的回调可能晚于
* 下一行的 onRowOpen 到达,晚到的注销不能抹掉新行的记录。
*/
onRowClose(key: string): void;
/** 关闭当前打开的行;返回是否真的关了(供「打开态点击 = 只关闭不进会话」判断)。 */
closeOpenRow(): boolean;
}
/** 页面级单例(useMemo 持有),SectionList 各行共享同一实例实现互斥。 */
export function createSwipeRowRegistry(): SwipeRowRegistry {
let current: { key: string; close: () => void } | null = null;
return {
onRowOpen(key, close) {
if (current && current.key !== key) current.close();
current = { key, close };
},
onRowClose(key) {
if (current?.key === key) current = null;
},
closeOpenRow() {
if (!current) return false;
current.close();
current = null;
return true;
},
};
}
export interface LatestWriteGuard {
/**
* 开始一笔写:立即把本笔登记为该 key 下 fields 各字段的最新写。返回的 isLatest()
* 实时判断本笔是否仍是全部字段的最新(后续对同 key 的**交集字段**再 begin 才会使
* 旧笔过期;字段无交集的写互不取代)。observeFields 只观察当前代次、不使旧写过期,
* 用于确认前预检:后续 status 写能取消预检,取消预检不能丢弃此前的 status 写。
*/
begin(key: string, fields: readonly string[], observeFields?: readonly string[]): { isLatest(): boolean };
}
/**
* 「每 key 每字段最新写」守卫:同一会话并发多笔乐观写时,只有仍持有自己全部字段
* 最新权的一笔有资格重发 / 对账 / 回滚,被同字段新写取代的旧笔迟到结果一律作废——
* 否则旧笔失败的回滚(或慢回包的对账)会覆盖后续已成功的操作。
*
* 粒度按字段而非整会话(review P1:重命名 title 在退避中,用户随后置顶 pinnedAt,
* 两笔字段无交集——重命名不得被置顶取代而静默丢弃,否则乐观标题成幻影,下次同步
* 才跳回旧值)。同字段覆盖(置顶→取消置顶,归档→删除)才是真取代,旧笔让位。
*
* 计数器每 key:field 单调递增、**永不回收**(review P2:若最新笔终结时删掉登记,
* 下一笔会从 1 重新计数,与仍在途的旧笔序号撞车,旧笔迟到结果会误判自己是最新)。
* 代价是每个操作过的会话字段常驻一个 number,页面生命周期内可忽略。
*/
export function createLatestWriteGuard(): LatestWriteGuard {
const seqs = new Map<string, number>();
return {
begin(key, fields, observeFields = []) {
const mine = fields.map((field) => {
const slot = `${key} ${field}`;
const seq = (seqs.get(slot) ?? 0) + 1;
seqs.set(slot, seq);
return [slot, seq] as const;
});
const observed = observeFields.map((field) => {
const slot = `${key} ${field}`;
return [slot, seqs.get(slot)] as const;
});
return {
isLatest: () => [...mine, ...observed].every(([slot, seq]) => seqs.get(slot) === seq),
};
},
};
}
/**
* 从远端回包 / 本地旧快照中只挑出本笔负责的字段(外加远端时间戳 updatedAt)构成
* 对账 / 回滚补丁:字段级写序下,整对象覆盖会擦掉其它字段上后续写的乐观值
* (review P1 场景的另一半:重命名回包不得把置顶新写的 pinnedAt 冲回旧值)。
*
* updatedAt 单调不回退(review P2):两条无交集道并行时(title 重试 + pinnedAt),
* 晚 settle 的旧回包不得把另一道刚推进的 updatedAt 倒退——传入 floorUpdatedAt
* (调用时 store 里的当前值),仅当 source 的 updatedAt 更新时才带上(ISO 同格式,
* 字典序即时间序)。
*/
export function pickWriteFields<T extends object>(
source: T,
fields: readonly string[],
floorUpdatedAt?: string | null,
): Partial<T> {
const out: Record<string, unknown> = {};
for (const field of fields) {
if (field in source) out[field] = (source as Record<string, unknown>)[field];
}
const nextUpdatedAt = (source as Record<string, unknown>)['updatedAt'];
if (typeof nextUpdatedAt === 'string' && (!floorUpdatedAt || nextUpdatedAt > floorUpdatedAt)) {
out['updatedAt'] = nextUpdatedAt;
}
return out as Partial<T>;
}
export interface SessionWriteQueue {
/**
* 把一笔远端写挂到该 key 下 fields 各字段队列的队尾:所有交集字段的前笔 settle
* (成功/失败/让位)后才执行;无交集字段的写互不排队、并行出网。
*/
enqueue<T>(key: string, fields: readonly string[], task: () => Promise<T>): Promise<T>;
}
/**
* 每 key **按字段分道**的远端写串行化队列:同字段的 patch 依次出网(任一时刻同字段
* 至多一笔在途),消除「旧写先发滞留、新写后发先到、旧写晚到覆盖新值」的并发在途
* 乱序(review P1:服务端 patch-meta 是无版本条件的更新,到达序即写序;WS 级联链路
* 对单发送方保序,同字段发出序 = 用户操作序,到达序就正确)。
*
* 分道依据(review P2:归档/删除不得被前面重命名的整轮重试拖住):被控端
* patchSessionMetaInDb 是字段级 `UPDATE ... SET`,只写 patch 出现的字段——无交集
* 字段的两笔写在被控端乱序执行也互不覆盖,并行是安全的;需要写序的只有同字段。
*
* 前一笔失败不阻断下一笔;排队期间同字段新笔已 begin,在途旧笔会在下一次重发前因
* isLatest 屏障让位,新笔最多等一个退避间隔 + 一次在途请求。tail 登记与
* LatestWriteGuard 同款每 key:field 常驻,页面生命周期内可忽略。
*/
export function createSessionWriteQueue(): SessionWriteQueue {
const tails = new Map<string, Promise<unknown>>();
return {
enqueue<T>(key: string, fields: readonly string[], task: () => Promise<T>): Promise<T> {
const slots = fields.map((field) => `${key} ${field}`);
const prior = Promise.allSettled(slots.map((slot) => tails.get(slot) ?? Promise.resolve()));
const next = prior.then(task);
// 队尾只存吞掉结果/错误的影子,避免未消费的 rejection 链;结果仍由 next 交给调用方。
const shadow = next.then(() => undefined, () => undefined);
for (const slot of slots) tails.set(slot, shadow);
return next;
},
};
}
export interface PendingWriteTracker {
/** 登记一笔在途写(begin 时调用);返回幂等的 release,写 settle(成功/失败/让位)时调用。 */
track(key: string, fields: readonly string[]): () => void;
/**
* 过滤掉 patch 中本机有在途写的字段。被控端 `sessions:patched` push 是无差别广播,
* 同字段旧写的 push 回流会把本机更新的乐观意图滚回(review P2:pin RPC 在途时用户
* unpin,pin 的 push 到达把乐观 unpin 冲掉);在途字段以本机 pending 写为准,push
* 里这些字段丢弃,终态由本笔的对账/后续 push 收敛。
*
* localRow 传本地行当前值时,遮蔽留痕只记**差异遮蔽**:被控端先广播 push 再回
* invoke 响应(patchSessionMetaInDb 先 broadcast 后 return),本笔自己的 echo push
* 必然先于回包到达且值与本机乐观值相同——同值遮蔽零信息,不留痕,否则每次成功写
* 都会误触发全量 reseed(review P2)。不传 localRow 时保守留痕(宁多一次 reseed)。
*/
filterPatch<T extends Record<string, unknown>>(
key: string,
patch: T,
localRow?: Record<string, unknown> | null,
): Partial<T>;
/**
* 查询并清除「fields 中任一字段在途期间曾有 push 被遮蔽」标记。被遮的可能是**其它
* 控制端**的并发更新(review P1:手机重命名在途,桌面端改了同一标题):本机写成功
* 时回包权威覆盖无需理会;本机写**失败回滚**时被遮的远端值就此丢失,调用方应据此
* requestReseed 向被控端收敛。标记随 release 计数归零自动清除。
*/
consumeMaskedPush(key: string, fields: readonly string[]): boolean;
/**
* 该 key 当前有在途写的字段清单(无则空数组)。供全量列表对账(setDeviceSessions)
* 保护乐观意图:重连 / reseed 拉到的旧快照不得冲掉在途字段(review P1)。
*/
pendingFields(key: string): string[];
/**
* 全量对账 overlay 的留痕入口(review P2):overlay 用本地乐观值藏起了权威快照值,
* 与 push 遮蔽同样可能藏掉外部控制端的并发更新——快照值与本地值不同时记差异遮蔽
* (同一 masked 集,由 consumeMaskedPush 消费触发 reseed);同值零信息不留痕。
*/
noteMaskedValue(key: string, field: string, incoming: unknown, local: unknown): void;
}
/** 每 (key, field) 在途写计数器。track/release 配对;filterPatch 供 push 应用路径消费。 */
export function createPendingWriteTracker(): PendingWriteTracker {
const counts = new Map<string, number>();
const masked = new Set<string>();
return {
track(key, fields) {
const slots = fields.map((field) => `${key} ${field}`);
for (const slot of slots) counts.set(slot, (counts.get(slot) ?? 0) + 1);
let released = false;
return () => {
if (released) return;
released = true;
for (const slot of slots) {
const next = (counts.get(slot) ?? 1) - 1;
if (next <= 0) {
counts.delete(slot);
// 计数归零 = 该字段无在途写:清残留遮蔽标记,不污染下一笔写的失败判定
//(计数>1 时保留——同字段另一笔在途,其结局仍需要这个信息)。
masked.delete(slot);
} else {
counts.set(slot, next);
}
}
};
},
filterPatch<T extends Record<string, unknown>>(
key: string,
patch: T,
localRow?: Record<string, unknown> | null,
): Partial<T> {
const out: Record<string, unknown> = {};
for (const [field, value] of Object.entries(patch)) {
const slot = `${key} ${field}`;
if (counts.has(slot)) {
// 差异遮蔽才留痕:echo push(值与本机乐观值相同)零信息;元数据字段均为
// 标量(string|null),=== 即可。
if (!localRow || value !== localRow[field]) masked.add(slot);
} else {
out[field] = value;
}
}
return out as Partial<T>;
},
consumeMaskedPush(key, fields) {
let hit = false;
for (const field of fields) {
const slot = `${key} ${field}`;
if (masked.delete(slot)) hit = true;
}
return hit;
},
pendingFields(key) {
const prefix = `${key} `;
const fields: string[] = [];
for (const slot of counts.keys()) {
if (slot.startsWith(prefix)) fields.push(slot.slice(prefix.length));
}
return fields;
},
noteMaskedValue(key, field, incoming, local) {
if (incoming !== local) masked.add(`${key} ${field}`);
},
};
}
/**
* patch-meta 可写的全部元数据字段(与被控端 REMOTE_EDITABLE_META 同集)。
* 消费方:writeGuardFields 的移行写(delete/archive)全字段取代。
*/
export const SESSION_META_FIELDS = ['status', 'title', 'pinnedAt'] as const;
/**
* 写序登记字段:delete / archive 都是**移行**写——行从列表消失后,同会话 pending 的
* 重命名/置顶既失去 UI 载体(乐观值随行消失,放弃无幻影代价),继续重试还会在行
* 消失后冒出「重命名失败」弹窗或滞后更新已归档会话(review P2 两轮)——取代全部
* 元数据字段的写序让它们立即让位;restore(不移行)与其余动作按 patch 自身字段
* 登记(无交集写互不取代)。
*/
export function writeGuardFields(patch: { status?: string | null; [key: string]: unknown }): string[] {
if (patch.status === 'deleted' || patch.status === 'archived') return [...SESSION_META_FIELDS];
return Object.keys(patch);
}
/**
* 带「过期即放弃」屏障的瞬时重试执行器:每次(重)发前先查 isLatest,本笔已被同
* 会话后续写取代时返回 null 静默中止。isLatest 对账只能作废旧笔的**迟到回包**,
* 挡不住旧笔在重试退避期间把旧 patch **重发到远端**覆盖新写的结果(review P1:
* 置顶 A 退避中 → 取消置顶 B 成功 → 网络恢复后 A 重发旧 pinnedAt);屏障把这个
* 窗口收敛回单次在途请求的固有水平。null = 已让位:调用方不对账、不回滚、不提示,
* 本地与远端终态由取代它的新写负责收敛。
*
* send 会收到 assertStillLatest:过期即抛让位哨兵的同步断言。调用方应把它穿到
* 尽可能贴近实际发送的位置(invoke 的 preSend——连接就绪后、真正出网前;review P2:
* 重连等待最长 1.5s,期间被同字段新写取代的旧笔不该在重连后仍发出,否则其成功
* push 会把更新的乐观状态短暂滚回)。
*/
export async function retryPatchWhileLatest<T>(
isLatest: () => boolean,
send: (assertStillLatest: () => void) => Promise<T>,
): Promise<T | null> {
// 哨兵错误按引用识别;message 不含瞬时错误标记,withTransientRemoteRetry 不会重试它。
const stale = new Error('stale session write superseded');
const assertStillLatest = (): void => {
if (!isLatest()) throw stale;
};
try {
return await withTransientRemoteRetry(() => {
assertStillLatest();
return send(assertStillLatest);
});
} catch (err) {
if (err === stale) return null;
throw err;
}
}
/** 右滑按钮:按当前置顶态给出动作与文案(置顶区行天然拿到「取消置顶」)。 */
export function pinToggleAction(
pinnedAt: string | null | undefined,
): { action: 'pin' | 'unpin'; label: string } {
return pinnedAt
? { action: 'unpin', label: i18n.t('session.menu.unpin') }
: { action: 'pin', label: i18n.t('session.menu.pin') };
}
export interface SessionActionMenuItem {
action: SessionSwipeAction;
label: string;
/** 删除项标红 + 触发系统 Alert 二次确认。 */
destructive?: boolean;
}
/** 左滑主按钮 / 菜单归档项:按当前状态在归档与恢复之间切换。 */
export function statusToggleAction(
status: string | null | undefined,
): { action: 'archive' | 'restore'; label: string } {
return status === 'archived'
? { action: 'restore', label: i18n.t('session.menu.restore') }
: { action: 'archive', label: i18n.t('session.menu.archive') };
}
/** 「选项」菜单模型:重命名 → 置顶切换 → 归档/恢复 → 删除(文案与会话详情页菜单保持一致)。 */
export function buildSessionActionMenu(
pinnedAt: string | null | undefined,
status?: string | null,
): SessionActionMenuItem[] {
const pinToggle = pinToggleAction(pinnedAt);
const statusToggle = statusToggleAction(status);
return [
{ action: 'rename', label: i18n.t('session.menu.renameAction') },
{ action: pinToggle.action, label: pinToggle.label },
{ action: statusToggle.action, label: statusToggle.label },
{ action: 'delete', label: i18n.t('session.menu.deleteConversation'), destructive: true },
];
}
/** swipe 动作 → patchSessionMeta 补丁(rename 走重命名弹窗,不在此列)。 */
export function swipeActionPatch(
action: Exclude<SessionSwipeAction, 'rename'>,
now?: number,
): MobileSessionBulkPatch {
return mobileSessionBulkPatch(action, now);
}