Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

19.0 KB
Raw Blame
/**
 * shared/hookControlIpc.ts
 * ---------------------------------------------------------------------------
 * Cindy IM relay(hook-control) 的 IPC 通道名与线上类型 —— main / preload /
 * renderer 三端共享的唯一契约(模式对齐 deviceLinkIpc.ts)。
 *
 * 功能背景: desktop 主动外连公司中心部署的 IM hook 服务(WS 拨出),
 * 接收 Slack / Telegram 归一化后的任务派发。产品形态是**每 provider 一条内置连接**:
 *   - Slack / Telegram 地址分别来自运行期端点清单;
 *   - 鉴权用登录 JWT(与 device-link 同模型), 没有密钥概念, 用户零输入;
 *   - 用户可操作面 = provider 独立开关 / 账号绑定 / 工作目录清单。
 */

// 内置服务器地址来自运行期端点清单(main 侧分别读取 slackHookWsUrl 与
// telegramHookWsUrl;Slack 的本地 urlOverride 只覆盖 Slack);
// 烘焙常量 SLACK_HOOK_DEFAULT_URL 已随 2026-07 端点清单重构退役。

/**
 * 由 WS 服务器地址推导 Slack App 安装链接: wss→https / ws→http, 去尾斜杠后拼
 * bolt InstallProvider 的固定路径 /slack/install(directInstall 模式, 302 直跳
 * Slack 授权页)。安装是 workspace 级一次性动作, 与本机连接/绑定状态无关。
 */
export function slackHookInstallUrl(wsUrl: string): string {
  return `${wsUrl.replace(/^ws(s?):\/\//, 'http$1://').replace(/\/+$/, '')}/slack/install`;
}

export const HOOK_CONTROL_INVOKE = {
  /** 取当前快照(配置 + 运行时状态 + 绑定状态)。 */
  GET: 'maker:hook-control:get',
  /** 总开关。 */
  SET_ENABLED: 'maker:hook-control:set-enabled',
  /** Slack Bot 是否发送本设备上下线通知。 */
  SET_LIFECYCLE_ANNOUNCEMENT: 'maker:hook-control:set-lifecycle-announcement',
  /** 覆写工作目录清单(别名 -> 本地绝对路径, 全量替换)。 */
  SET_WORKSPACES: 'maker:hook-control:set-workspaces',
  /**
   * 设置某个 provider 派发任务的默认工作目录(null / 「对话」= 内置伪目录)。
   * 进程内通道, 没有跨版本兼容问题 —— 原 set-x-default-workspace 直接改名。
   */
  SET_PROVIDER_DEFAULT_WORKSPACE: 'maker:hook-control:set-provider-default-workspace',
  SET_X_COMPANION: 'maker:hook-control:set-x-companion',
  /** 发起 Slack 账号绑定(bind.start; SIWS OIDC, 无参数)。 */
  BIND_START: 'maker:hook-control:bind-start',
  /** 解除 Slack 账号绑定(bind.revoke)。 */
  BIND_REVOKE: 'maker:hook-control:bind-revoke',
  /** 拉取绑定用户的全部目录偏好快照(经 WS prefs.get, 10s 超时)。 */
  PREFS_GET: 'maker:hook-control:prefs-get',
  /** 部分更新某目录偏好(经 WS prefs.set; null = 清空回默认)。 */
  PREFS_SET: 'maker:hook-control:prefs-set',
  /** (multi-team)添加新 Slack workspace 绑定(bind.start 空 teamId, 授权页自选)。 */
  ADD_BINDING: 'maker:hook-control:add-binding',
  /** (multi-team)给指定 team 重新授权(bind.start 带 teamId, pin 授权页)。 */
  REBIND_TEAM: 'maker:hook-control:rebind-team',
  /** (multi-team)解绑指定 team;通讯专用行只撤本机 grant,不撤账号授权。 */
  REVOKE_TEAM: 'maker:hook-control:revoke-team',
  SET_SLACK_COMMUNICATIONS: 'maker:hook-control:set-slack-communications',
  /** (multi-team)取消在途的添加/重绑授权(bind.revoke{pendingOnly} + 本地清 pending)。 */
  CANCEL_PENDING_BIND: 'maker:hook-control:cancel-pending-bind',
  /** 独立开关一个 Cindy IM provider;不会改动其它 provider。 */
  SET_PROVIDER_ENABLED: 'maker:hook-control:set-provider-enabled',
  /** 发起 provider-neutral(Telegram / X)一次性绑定。 */
  PROVIDER_BIND_START: 'maker:hook-control:provider-bind-start',
  /** 取消当前 provider-neutral 绑定尝试。 */
  PROVIDER_BIND_CANCEL: 'maker:hook-control:provider-bind-cancel',
  /** 解除当前 provider-neutral principal 与本设备的绑定。 */
  PROVIDER_BIND_REVOKE: 'maker:hook-control:provider-bind-revoke',
  /** 在本机安全打开 provider 的绑定链接 / bot 主页 / 加群链接。 */
  PROVIDER_OPEN_ACTION: 'maker:hook-control:provider-open-action',
  /** 读取 provider-neutral(Telegram / X)独立的 workspace 偏好。 */
  PROVIDER_PREFS_GET: 'maker:hook-control:provider-prefs-get',
  /** 更新 provider-neutral(Telegram / X)独立的 workspace 偏好。 */
  PROVIDER_PREFS_SET: 'maker:hook-control:provider-prefs-set',
  /** 读取官方 Telegram bot 的回应、引用与群激活设置。 */
  TELEGRAM_BEHAVIOR_GET: 'maker:hook-control:telegram-behavior-get',
  /** 部分更新官方 Telegram bot 的回应或引用设置。 */
  TELEGRAM_BEHAVIOR_SET: 'maker:hook-control:telegram-behavior-set',
  /** 列出官方 Telegram bot 已见过的群,并合并服务端激活设置。 */
  TELEGRAM_GROUPS_LIST: 'maker:hook-control:telegram-groups-list',
  /** 更新一个官方 Telegram 群的参与模式。 */
  TELEGRAM_GROUP_ACTIVATION_SET: 'maker:hook-control:telegram-group-activation-set',
  /** 读取工作目录模型来源偏好(纯本地, 不经 WS; 见 workspaceProviderSourceStore)。 */
  WORKSPACE_PROVIDER_SOURCE_GET: 'maker:hook-control:workspace-provider-source-get',
  /** 写/清一条工作目录模型来源偏好(纯本地)。 */
  WORKSPACE_PROVIDER_SOURCE_SET: 'maker:hook-control:workspace-provider-source-set',
} as const;

export const HOOK_CONTROL_EVENT = {
  /** 状态推送(完整快照; 连接与绑定状态变化都走这里)。 */
  STATUS_CHANGED: 'maker:hook-control:status-changed',
  /** 目录偏好快照推送(prefs.state; 含 Slack /model 卡改动的实时同步)。 */
  PREFS_CHANGED: 'maker:hook-control:prefs-changed',
  /** provider-neutral 偏好快照推送(Telegram / X 消费)。 */
  PROVIDER_PREFS_CHANGED: 'maker:hook-control:provider-prefs-changed',
  /** 官方 Telegram 行为配置快照推送(含其它客户端写入)。 */
  TELEGRAM_BEHAVIOR_CHANGED: 'maker:hook-control:telegram-behavior-changed',
  /** 目录模型来源偏好全量推送(本地写入后广播全窗口, 多窗口设置页同步)。 */
  WORKSPACE_PROVIDER_SOURCE_CHANGED: 'maker:hook-control:workspace-provider-source-changed',
} as const;

/** 目录来源偏好条目总量上限(渠道×目录×team 现实规模远小于此;防被攻破的
 * renderer 用海量唯一 teamId 无限追加撑爆本地文件)。 */
export const HOOK_WORKSPACE_PROVIDER_SOURCE_MAX_ENTRIES = 256;

/**
 * Cindy relay 当前支持的客户端 provider。协议包 HOOK_PROVIDERS 的手抄副本
 * (shared 层刻意不引协议包)——协议 bump 新增 provider 时必须手动同步。
 */
export type HookProvider = 'slack' | 'telegram' | 'x';

/** provider-neutral 状态机(非 slack legacy 线)覆盖的 provider。 */
export type NeutralHookProvider = Exclude<HookProvider, 'slack'>;

/** provider-neutral 绑定状态(与本仓 slack-hook-protocol v1 严格同形)。 */
export type ProviderBindingState =
  | 'none'
  | 'pending'
  | 'awaiting_confirmation'
  | 'confirmed'
  | 'denied'
  | 'expired'
  | 'failed'
  | 'revoked'
  | 'superseded';

/** renderer 可见的 provider-neutral 绑定快照;不含任何 token/secret。 */
export interface ProviderBindingView {
  provider: HookProvider;
  state: ProviderBindingState;
  attemptId: string | null;
  bindingId: string | null;
  principalId: string | null;
  principalName: string | null;
  scopeId: string | null;
  scopeName: string | null;
  connectUrl: string | null;
  expiresAt: number | null;
  reason: string | null;
  remediationUrl: string | null;
  actions: string[];
}

/** provider-neutral(Telegram / X)的独立设置与绑定视图。 */
export interface ProviderHookView {
  /** Local companion assignment, currently only used by the official X provider. */
  companionBotId?: string | null;
  enabled: boolean;
  /** 该 provider 平级 hook 服务的运行期端点;空值表示当前环境尚未部署。 */
  url: string;
  status: HookConnectionStatus;
  lastError: string | null;
  /** 已收到 welcome,且双方成功协商完整 provider 能力。 */
  available: boolean;
  /** 尚未收到任何 welcome;用于首开时先显示入口、连接后再权威收敛。 */
  capabilityPending: boolean;
  /** Telegram 行为设置增量能力;旧 main 快照缺省时按 false。 */
  behaviorAvailable?: boolean;
  binding: ProviderBindingView | null;
  /**
   * 派发任务时使用的默认工作目录别名(null = 内置「对话」伪目录)。
   *
   * **目前只有 X 会给出非 null 值**: Slack / Telegram 能在会话里当场选目录,
   * X 一次交互只有一条公开推文, 没有承载选择面板的位置, 只能靠这个预设。
   */
  defaultWorkspace: string | null;
}

/** @deprecated 兼容别名;新代码用 ProviderHookView。 */
export type TelegramHookView = ProviderHookView;

/** 绑定卡可打开的链接类别;'add-to-group' 仅 Telegram 使用。 */
export type ProviderOpenAction = 'connect' | 'provider' | 'add-to-group';

/** @deprecated 兼容别名;新代码用 ProviderOpenAction。 */
export type TelegramOpenAction = ProviderOpenAction;

/**
 * Slack 账号绑定状态(与 hook-protocol 的 BindUpdateState 一致, 本文件为
 * renderer 侧独立声明, 避免 shared 层引协议包)。阶段 4 起绑定走 Sign in with
 * Slack(OIDC):
 *   none 未绑定 / pending 已生成授权链接·等浏览器授权(authorizeUrl 非空) /
 *   confirmed 已绑定 / denied 授权被拒 / expired 授权超时 /
 *   failed 流程失败(如老服务器、workspace 未安装) / revoked 被解除(含被新设备顶掉)
 */
export type HookBindingState =
  'none' | 'pending' | 'confirmed' | 'denied' | 'expired' | 'failed' | 'revoked';

/** Slack 绑定快照(server 经 bind.update 推送, main 缓存最新一帧)。 */
export interface HookBindingView {
  state: HookBindingState;
  slackUserId: string | null;
  slackUserName: string | null;
  message: string | null;
  /**
   * SIWS OIDC 授权链接(仅 state=pending 时非空): 桌面端用系统浏览器打开它
   * 完成 Slack 授权。远程控制场景下 openExternal 落在被控机, 故设置页同时
   * 给「复制链接」兜底(规则 26)。
   */
  authorizeUrl: string | null;
  /**
   * 结构化失败原因(仅 state=failed 时可能非空, 透传 bind.update.reason)。
   * 已知值 'not-installed': 授权的 Slack workspace 未安装 App(授权本身不要求
   * 安装, 但 bot 无 token 收发消息), 设置页据此显示「安装 Slack App」引导行
   * (判定走本字段, 不解析 message 文案, 规则 9)。
   */
  reason: string | null;
  /**
   * 按 workspace 定制的安装链接(仅 not-installed 时可能非空, 透传
   * bind.update.installUrl): 带 team 参数, 安装授权页预选到刚授权的
   * workspace。老 server 不下发时回退 slackHookInstallUrl 通用链接。
   */
  installUrl: string | null;
  /**
   * 绑定所在 Slack workspace 显示名(仅 confirmed 时可能非空, 透传
   * bind.update.teamName): 状态行展示「已绑定 @xxx(workspace)」。老 server
   * 不下发时为 null, 回退只显示用户名。
   */
  teamName: string | null;
}

/** binding.reason 已知值(与 hook-protocol 的 BIND_FAIL_REASON_NOT_INSTALLED 对齐)。 */
export const HOOK_BIND_REASON_NOT_INSTALLED = 'not-installed';

/** binding.reason 已知值(multi-team): 该 team 被同用户在另一台设备顶掉。 */
export const HOOK_BIND_REASON_SUPERSEDED = 'superseded';

/**
 * (multi-team)本地合成的终止态 reason: 「添加 workspace」授权落在已绑定的
 * 活跃 team 上(用户没在 Slack 授权页右上角切换 workspace)。仅 desktop 本地
 * 使用, 不过网线; renderer 据此显示切换指引而非通用失败文案。
 */
export const HOOK_BIND_REASON_ALREADY_BOUND = 'already-bound';

/**
 * (multi-team)单个已确认的 Slack workspace 绑定行(bind.state 快照 +
 * confirmed/revoked 事件维护; displaced 行来自本地缓存 diff 或 superseded 事件)。
 */
export interface HookTeamBindingView {
  teamId: string;
  /** workspace 显示名; 安装档案缺名时 null(回退显示 teamId)。 */
  teamName: string | null;
  slackUserId: string;
  slackUserName: string | null;
  /**
   * true = 本机不是该 team 的 Bot 接收设备(换绑、通讯专用 OAuth 或缓存缺失)。
   * 是否仍可通讯由独立 communicationsEnabled 决定;删除新 server 的通讯行
   * 只撤本机 grant,旧 server 行仅清本地缓存。
   */
  displaced: boolean;
  /** undefined = 未收到独立通讯授权,不能从 displaced 或本地缓存推断。 */
  communicationsEnabled?: boolean;
}

/**
 * (multi-team)在途授权状态 —— 原单绑定状态机中「非 confirmed」的部分拆出来
 * 单独承载: 添加/重绑 workspace 的授权流(pending)与其终止态(denied/expired/
 * failed)。confirmed/revoked 只落到 bindings 列表, 不出现在这里。
 */
export interface HookPendingBindView {
  purpose?: 'communications';
  state: 'pending' | 'denied' | 'expired' | 'failed';
  message: string | null;
  /** 仅 pending 时非空(SIWS OIDC 授权链接, 复制链接兜底用)。 */
  authorizeUrl: string | null;
  /** 结构化失败原因(如 not-installed), 语义同 HookBindingView.reason。 */
  reason: string | null;
  installUrl: string | null;
  /** 重绑指定 team 时的目标 team; 添加新 workspace 时 null。 */
  teamId: string | null;
  /**
   * 本次授权流的发起意图 —— 决定终止态重试走哪个入口。add = 添加新
   * workspace(重试回 addBinding, 授权页可切换); rebind = 定向重绑指定
   * team(重试 pin 到 teamId)。不能靠 teamId 推断: add 流授权中途 server
   * 也会回显用户所选 team 的 teamId(含 denied/expired/failed 终止态)。
   */
  intent: 'add' | 'rebind';
}

/**
 * 连接运行时状态:
 *  - disabled:   开关关闭, 不建连
 *  - connecting: 正在建连 / 退避重连中(含已开 WS 但尚未收到 welcome)
 *  - connected:  握手完成(hello -> welcome), 可收派发
 *  - standby:    同机另一实例已持有 first-wins 连接, 本实例低频探测接管
 *  - error:      最近一次连接失败(仍在退避重试), lastError 给原因
 */
export type HookConnectionStatus = 'disabled' | 'connecting' | 'connected' | 'standby' | 'error';

/** 渲染层可见的 Cindy IM 快照;顶层字段保持 Slack 兼容。 */
export interface SlackHookView {
  enabled: boolean;
  /** Slack Bot 是否发送本设备上下线私聊通知。 */
  lifecycleAnnouncement: boolean;
  /** 实际生效的服务器地址(默认内置值; 被 urlOverride 覆写时为覆写值)。 */
  url: string;
  /** 工作区别名 -> 本地绝对路径。协议里只跑别名, 路径不出本机。 */
  workspaces: Record<string, string>;
  status: HookConnectionStatus;
  lastError: string | null;
  /**
   * Slack 账号绑定状态(legacy 单绑定视图); 未连接过 / server 未推送时为
   * null(按未绑定显示)。multi-team 模式下由 bindings/pendingBind 映射而来
   * (在途授权优先, 否则首个未 displaced 绑定), 供老消费点继续读取。
   */
  binding: HookBindingView | null;
  /**
   * (multi-team)已确认绑定列表(含 displaced 行)。老 server / 未连接时来自
   * 本地缓存(冷启动「已关闭 · N 个绑定已保留」的数据源)。
   */
  bindings: HookTeamBindingView[];
  /** (multi-team)在途授权状态; 无在途流程时 null。 */
  pendingBind: HookPendingBindView | null;
  /** server 是否宣告 multi-team 能力(welcome.features; renderer 据此显示「添加」入口)。 */
  serverMultiTeam: boolean;
  /** 新 server 将通讯授权与唯一 Bot 接收设备分离。 */
  serverSlackCommunications?: boolean;
  /** 平级 Telegram hook 服务状态;Slack 旧字段保持原形。 */
  telegram: ProviderHookView;
  /** 平级 X (Twitter) hook 服务状态。 */
  x: ProviderHookView;
}

/** 工作区别名的合法格式(与 hook server 侧约定一致)。 */
export const HOOK_WORKSPACE_ALIAS_RE = /^[A-Za-z0-9_-]{1,32}$/;

/**
 * 保留别名「对话」: 内置的伪工作目录, 与真实目录同级 —— 桌面端把它恒定加进
 * 上报给 server 的目录清单(排第一), Slack 侧所有目录选择卡自然多一个 chat
 * 选项; 派发到 chat 的任务不落任何仓库, 每个会话分配独立的 app 托管对话
 * 目录(userData/dialogues/..., workspaceKind='dialogue', 落侧边栏「对话」
 * 分组)。server 对别名透传不校验, 解析完全在桌面端; 用户不能用它命名真实
 * 目录(store 校验拦截)。偏好按 (用户, 'chat') 存, 与真实目录同一套体系。
 */
export const HOOK_CHAT_WORKSPACE_ALIAS = 'chat';

/**
 * 单目录会话偏好(与协议 WorkspacePrefsEntry 同形, shared 层独立声明避免
 * 引协议包)。null = 未设置, 跟随桌面端草稿默认(权限默认完全访问)。
 * 数据正本在本机 hook-workspace-prefs.json; hook server 的 user_prefs 只作
 * /model 卡镜像。
 */
/**
 * 工作目录的模型来源偏好条目(纯客户端)。
 * 按本表与本机目录 model 组合后经 effectiveSourceIdForModel 收窄派发。
 */
export interface HookWorkspaceProviderSourceEntry {
  agentDeviceId?: string | null;
  channel: 'slack' | 'telegram' | 'x';
  /** Slack multi-team 归属; Telegram / X / 单绑定为 null。 */
  teamId: string | null;
  workspace: string;
  providerId: string;
}

export interface HookWorkspacePrefs {
  workspace: string;
  model: string | null;
  effort: string | null;
  agentKind: string | null;
  permissionMode: string | null;
  /**
   * (multi-team)偏好归属的 Slack workspace(prefs.state 条目透传)。老 server /
   * 单绑定语境下缺省 —— renderer 按 teamId 过滤显示时对缺省值宽松匹配。
   */
  teamId?: string | null;
}

/** 偏好快照(设置页读本机正本)。bound 表示该渠道是否已关联账号。 */
export interface HookPrefsView {
  bound: boolean;
  prefs: HookWorkspacePrefs[];
}

/** provider-neutral 偏好快照;selector 与协议帧同形。 */
export interface ProviderPrefsView extends HookPrefsView {
  provider: HookProvider;
  bindingId: string | null;
  scopeId: string | null;
}

export type TelegramHookEmojiReactions = 'off' | 'minimal' | 'expressive';
export type TelegramHookReplyQuoteDm = 'off' | 'first';
export type TelegramHookReplyQuoteGroup = 'off' | 'first' | 'all';
export type TelegramHookGroupActivationMode = 'mention' | 'always';

/** 官方 Telegram bot 的有效行为快照;数据正本在 telegram-hook-server。 */
export interface TelegramHookBehavior {
  emojiReactions: TelegramHookEmojiReactions;
  replyQuoteDm: TelegramHookReplyQuoteDm;
  replyQuoteGroup: TelegramHookReplyQuoteGroup;
}

export interface TelegramHookBehaviorState extends TelegramHookBehavior {
  bound: boolean;
  bindingId: string;
  /** 只列偏离默认值的群;缺席 = mention。 */
  groupActivation: Record<string, 'always'>;
}

export type TelegramHookBehaviorPatch = Partial<TelegramHookBehavior>;

export interface TelegramHookKnownGroup {
  chatId: string;
  chatName: string | null;
  activation: TelegramHookGroupActivationMode;
}

/** 偏好部分更新 patch(undefined 不动, null 显式清空)。 */
export interface HookPrefsPatch {
  model?: string | null;
  effort?: string | null;
  agentKind?: string | null;
  permissionMode?: string | null;
}