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。

22.4 KB
Raw Blame
/**
 * cindy-tools 公共类型 —— Cindy 意识系统的内部工具集契约。
 *
 * 本包统一承载 Cindy 意识系统向 agent 暴露的
 * 工具一律经 MCP 注册,host(apps/desktop main)通过 deps 注入真实实现,
 * 包内不感知 Electron / 沙箱 / DB(设计规范规则 2:package 解耦)。
 *
 * 首个成员:ghost 总机(docs/dev-rules/plugin-security-and-authoring.md 的网关模式)——
 * agent 工具箱里的插件发现/调用入口固定为 ghost_list / ghost_info / ghost_manual /
 * ghost_call,
 * 已装意识的增删即时反映在 ghost_info / ghost_list 的**返回内容**里。
 * 工具面(名称/schema/基线描述)版本内恒定;完整描述(含花名册快照)
 * 会话内恒定。
 */

/** 意识注册的单个工具(来自 ghost.json 的 tools 声明,host 透传)。 */
export interface CindyGhostToolInfo {
  name: string;
  description: string;
  /** JSON Schema(object)形态的参数声明;无参工具省略。 */
  parameters?: Record<string, unknown>;
}

/** Host 对单条配置要求的脱敏分类;只描述能力,不携带配置值。 */
export type CindyGhostSetupRequirementKind =
  | 'oauth'
  | 'secret'
  | 'connection'
  | 'plugin_config'
  | 'client_config';

/** Host 对单条配置要求的权威状态。 */
export type CindyGhostSetupRequirementState = 'missing' | 'expired' | 'satisfied';

/** Agent 可选择、但只能由 Host 执行的配置动作。 */
export type CindyGhostSetupAllowedAction =
  | {
      /** Host 生成的动作引用,Agent 不得自行构造或直接执行。 */
      id: string;
      kind:
        | 'oauth_connect'
        | 'open_plugin_settings'
        | 'manage_connection'
        | 'open_client_settings';
    }
  | {
      /** Host 生成的散列动作引用;不包含 Secret storage key。 */
      id: string;
      kind: 'inline_form';
      form: {
        fields: [
          {
            /** v1 单字段固定为 value;它不是 storage key。 */
            id: 'value';
            type: 'secret';
            label: string;
            description?: string;
            placeholder?: string;
            required: true;
            maxLength: number;
          },
        ];
      };
    };

/**
 * ghost_info / ghost_list 返回的 Host 权威配置评估。只含引用、展示信息和允许动作,
 * 禁止携带 Secret、Token、OAuth client secret 或 Connection 内容。
 */
export interface CindyGhostSetupAssessment {
  state: 'ready' | 'required';
  /** Host 单调递增的状态版本;Agent 回传 plan 时必须原样带回。 */
  revision: number;
  /** groups 之间 all-of;每组 items 之间按 mode(any-of)判定。 */
  groups: Array<{
    id: string;
    mode: 'any_of';
    items: Array<{
      /** Host 生成的稳定 requirement 引用,仅用于关联,不是可执行能力。 */
      ref: string;
      kind: CindyGhostSetupRequirementKind;
      label: string;
      description?: string;
      state: CindyGhostSetupRequirementState;
      actions: CindyGhostSetupAllowedAction[];
    }>;
  }>;
  /** 插件仍 ready 时的非阻塞重连建议;不得解释为 SETUP_REQUIRED。 */
  reauthSuggest?: {
    ghostId: string;
    secretKey: string;
    missingScopes: string[];
    missingScopeCount: number;
    requirement: {
      ref: string;
      kind: 'oauth';
      label: string;
      action: {
        id: string;
        kind: 'oauth_connect';
      };
    };
  };
}

/** Agent 为 Ask 风格配置卡编排的展示步骤;Host 校验后才可采用。 */
export interface CindyGhostSetupPlan {
  /** 生成本 plan 时看到的 assessment revision。 */
  assessmentRevision: number;
  /** 卡片正文;插件名称与 icon 仍只由 Host 提供。 */
  intro?: string;
  steps: Array<{
    id: string;
    requirementRefs: string[];
    title: string;
    description: string;
    /** 必须来自对应 requirement 的 allowed actions。 */
    actionId: string;
  }>;
}

/** ghost_info / ghost_list 共用的单段意识条目。 */
export interface CindyGhostInfo {
  id: string;
  /** null is root; a string is the organization slug. Omitted only on legacy hosts. */
  namespace?: string | null;
  name: string;
  /** 显式触发指令(用户敲 /<command> 点名调用);未声明则省略。 */
  command?: string;
  /** 插件作者提供的召回线索,仅作数据;Host 优先取 whenToUse,缺省回落 description。 */
  recall?: string;
  /** 随包手册的轻量一级索引;正文必须另行调用 ghost_manual 按需读取。 */
  manual?: CindyGhostManualIndexItem[];
  /** Manual-only 插件为空数组;发现或读取手册不授予插件工具能力。 */
  tools: CindyGhostToolInfo[];
  /**
   * Host 现查的配置评估。支持 Setup Runtime 的 Host 应尽量返回,但评估
   * 读取/计算失败时可省略;Agent 不得把字段缺失解释为 ready 或自行放行。
   */
  setup?: CindyGhostSetupAssessment;
}

/** ghost_call 的结构化失败分类(host 侧产生,总机原样透传给 agent)。 */
export type CindyGhostCallErrorCode =
  | 'GHOST_NOT_FOUND' // 未装入或已抽离
  | 'GHOST_AMBIGUOUS' // 同名多实例,需指定 namespace
  | 'GHOST_NAMESPACE_MISMATCH' // 插件已安装,但指定的 namespace 不匹配;按返回身份修正参数
  | 'GHOST_ASLEEP' // 沉睡中(用户可在主界面侧边栏「插件」中唤醒)
  | 'GHOST_RETIRED' // 功能已下线,不可唤醒或重试
  | 'GHOST_DISABLED_IN_WORKDIR' // 用户在当前工作目录停用了该意识(不要重试)
  | 'TOOL_NOT_FOUND' // 该意识没有这个工具
  | 'GHOST_CRASHED' // 电子脑执行中崩溃
  | 'TIMEOUT' // 执行超时(host 掐掉)
  | 'SETUP_REQUIRED' // 配置仍未就绪(无交互面或恢复前又变化);可带脱敏 assessment,未派发插件
  | 'SETUP_CANCELLED' // 用户取消插件配置;原调用未派发,不要自动重试
  | 'ATTACHMENT_INVALID' // attachments 里的媒体地址无法过户(格式/找不到/超数)
  | 'DIR_INVALID' // dir 目录无法过户(不存在/不在会话 workdir 内/超限额)
  | 'INTERNAL'; // 其它 host 侧错误

export type CindyGhostInfoErrorCode = Extract<
  CindyGhostCallErrorCode,
  'GHOST_NOT_FOUND' | 'GHOST_AMBIGUOUS' | 'GHOST_NAMESPACE_MISMATCH' | 'GHOST_ASLEEP' | 'GHOST_DISABLED_IN_WORKDIR' | 'GHOST_RETIRED'
>;

/** host 可见性判序回调(getAwakeGhost)的返回:只产可见性错误,不产 INTERNAL。 */
export type CindyGhostInfoHostResult =
  | { ok: true; ghost: CindyGhostInfo }
  | { ok: false; errorCode: CindyGhostInfoErrorCode; message: string; candidates?: Array<{ ghostId: string; namespace: string | null }> };

/** ghost_info 给模型的 wire 结果:host 结果之上,handler 兜底 catch 可产 INTERNAL。 */
export type CindyGhostInfoResult =
  | CindyGhostInfoHostResult
  | { ok: false; errorCode: 'INTERNAL'; message: string; errorType?: string };

/** ghost_info 与 ghost_manual 共用的手册索引/候选条目。 */
export interface CindyGhostManualIndexItem {
  /** 根索引为逻辑单元 name;未命中候选为可直接回填 path 的完整逻辑路径。 */
  name: string;
  description: string;
}

export type CindyGhostManualErrorCode =
  | CindyGhostInfoErrorCode
  | "MANUAL_PATH_NOT_FOUND"
  | "MANUAL_UNAVAILABLE"
  | "INTERNAL";

/** ghost_manual 固定信封;失败态额外携带稳定 errorCode/message。 */
export interface CindyGhostManualResult {
  ok: boolean;
  manual: CindyGhostManualIndexItem[];
  content: string;
  errorCode?: CindyGhostManualErrorCode;
  message?: string;
}

export type CindyGhostCallResult =
  | {
      ok: true;
      result: unknown;
      /** ready 语义不变;只在有非阻塞重连建议时由 Host 附加。 */
      setup?: CindyGhostSetupAssessment;
      /**
       * 本次调用期间由主机实际入库(cindy-media)的媒体地址账本(可选,
       * host 按 ghostId+callId 记账后随结果带回)。这是**主机侧事实**,
       * 意识代码删不掉——ghost_call 层在意识自己没声明任何媒体字段时,
       * 以 `xdt_media_produced` 注入返回体,兜底保证 IM/hook 出站至少
       * 能拿到产物地址(2026-07-16 实踩:意识画卡后删媒体字段,IM 用户
       * 收不到生成图)。
       */
      producedMedia?: string[];
      /**
       * 工具结果图片的文字描述(可选,host 视觉桥最佳努力附加)。纯文本模型
       * 拿不到 cindy-media:// 图片内容只能看到 URL 文本——host 把图片经
       * 外部多模态模型转成描述随结果带回,模型据此「看到」图而非幻觉编造。
       * 仅 host 侧注入的视觉桥能力存在且命中时附加;渲染层/IM 出站只消费
       * 固定媒体字段,不消费本字段(兼容性有回归测试锁定)。
       */
      xdt_media_descriptions?: Array<{ url: string; description: string }>;
      /**
       * Images the plugin shows the model (host-checked and re-encoded under
       * the inline budget). ghost_call returns them as MCP image content after
       * the JSON text; they are not part of the JSON.
       */
      images?: Array<{ data: string; mimeType: string }>;
      /** Images the plugin offered that did not fit the inline budget. */
      imagesOmitted?: number;
    }
  | {
      ok: false;
      errorCode: CindyGhostCallErrorCode | (string & {});
      message: string;
      /** 仅 SETUP_REQUIRED 可附 Host 生成的脱敏评估,供无交互面明确降级。 */
      setup?: CindyGhostSetupAssessment;
    };

/** ghost_forge_pack 的结构化失败分类(host 侧产生,原样透传给 agent)。 */
export type CindyForgePackErrorCode =
  | 'DIR_NOT_FOUND' // 目录不存在或不是目录
  | 'SOURCE_OUTSIDE_WORKDIR' // 源目录在工作目录外且未获当前会话权限,或会话工作目录缺失
  | 'PERMISSION_DENIED' // 工作目录外源码未获 Full Access / Auto 审阅 / 用户确认
  | 'WORKDIR_NOT_LOCAL' // 当前会话工作目录在远端或无法证明为本地
  | 'WORKDIR_READ_ONLY' // 当前会话禁止写入
  | 'SOURCE_IS_INSTALLED_PLUGIN' // 源目录命中 Host 管理的已安装插件或批准状态根
  | 'MANIFEST_INVALID' // ghost.json 缺失 / 不合法(message 带具体原因)
  | 'ENTRY_MISSING' // 清单声明的 entry / panel.html 等文件不在目录里
  | 'TOO_LARGE' // 文件数或总体积超上限
  | 'INTERNAL';

export type CindyForgePackResult =
  | {
      ok: true;
      /**
       * 作者副本的文件名提示(如 `demo-1.0.0.cindy`),不可用于访问。
       * 不是绝对路径,也不是 Host staging 路径;不要拿这个字段去读盘或发布。
       */
      cindyPath: string;
      id: string;
      name: string;
      version: string;
      /** 仅 intent=publish 返回;一次性、不可解析的 Host 发布票据。 */
      publishToken?: string;
      /** 打包结果说明;成功仅表示产物已生成,不表示已经安装。 */
      note: string;
    }
  | { ok: false; errorCode: CindyForgePackErrorCode; message: string };

/** ghost_forge_install 会先走 Forge 打包校验,再复用 Host 的本地安装/更新事务。 */
export type CindyForgeInstallResult =
  | {
      ok: true;
      action: 'installed' | 'updated';
      id: string;
      name: string;
      version: string;
      enabled: boolean;
      instanceId?: string;
      namespace?: string | null;
      note: string;
    }
  | {
      ok: false;
      errorCode: CindyForgePackErrorCode | (string & {});
      message: string;
      targets?: Array<{ instanceId: string; name: string; namespace: string | null; version: string; enabled: boolean }>;
      copyNamespace?: string | null;
    };

/** ghost_forge_publish 立即返回时的失败分类。传输开始后的失败走 status.errorCode。 */
export type CindyForgePublishErrorCode =
  | 'NOT_ORG_MEMBER'
  | 'SESSION_BOUNDARY_PENDING'
  | 'PUBLISH_TOKEN_INVALID'
  | 'PUBLISH_TOKEN_OWNER_MISMATCH'
  | 'INTERNAL';

export type CindyForgePublishResult =
  | {
      ok: true;
      transferId: string;
      uploadId: string | null;
      note: string;
    }
  | { ok: false; errorCode: CindyForgePublishErrorCode; message: string };

export type CindyForgePublishStatusResult =
  | {
      ok: true;
      transferId: string;
      uploadId: string | null;
      stage: string;
      status?: string | null;
      reviewStatus?: string | null;
      ghostId?: string | null;
      version?: string | null;
      bytesHashed?: number;
      bytesSent?: number;
      totalBytes?: number;
      errorCode?: string | null;
      message?: string | null;
    }
  | { ok: false; errorCode: 'NOT_FOUND' | 'INTERNAL'; message: string };

/** ghost_forge_scaffold 可生成的四种起步模板。 */
export type CindyForgeScaffoldTemplate =
  | 'plain'
  | 'agent-action'
  | 'node-json-rpc'
  | 'node-mcp';

export type CindyForgeScaffoldResult =
  | {
      ok: true;
      dir: string;
      template: CindyForgeScaffoldTemplate;
      /** 创建的相对文件路径;不会包含临时文件。 */
      files: string[];
      nextSteps: string[];
    }
  | {
      ok: false;
      errorCode: 'INVALID_INPUT' | 'TARGET_EXISTS' | 'WORKDIR_NOT_LOCAL' | 'WORKDIR_READ_ONLY' | 'PERMISSION_DENIED' | 'INTERNAL';
      message: string;
    };

/** Cindy Core 原生媒体能力;模型目录与调用说明均由 Model Access 动态下发。 */
export type CindyMediaCapability =
  | 'image.generate'
  | 'image.edit'
  | 'video.generate'
  | 'video.image_to_video';

/** 当前 Agent 专用的永久 media 工具与 Host 之间的稳定请求面。插件运行时代码不调用。 */
export type CindyMediaToolRequest =
  | { action: 'list_models'; capability?: CindyMediaCapability }
  | { action: 'resolve_local_path'; url: string }
  | { action: 'import_image'; path: string }
  | {
      action: 'prepare';
      /** 精确执行来源;插件配置返回 providerId 时必须原样传入。 */
      providerId?: string;
      modelId: string;
      capability: CindyMediaCapability;
    }
  | { action: 'request'; invocationId: string; body: Record<string, unknown> }
  | { action: 'poll'; invocationId: string };

/** host 注入的依赖:总机的全部真实能力都在这几个回调里。 */
export interface CindyGhostsMcpDeps {
  /** Cindy's own catalog, separate from installed plugins and provider app marketplaces. */
  searchMarket?(query: string): Promise<Record<string, unknown>>;
  installMarket?(request: { pluginId: string; releaseId: string }, signal?: AbortSignal): Promise<Record<string, unknown>>;
  /** Host-owned connection card. No URLs or credentials may be supplied by the model. */
  connectAccount?(target: { kind: 'plugin'; id: string; namespace?: string | null; reauthorize?: boolean } | { kind: 'host'; id: 'grok'; reauthorize?: boolean }, signal?: AbortSignal): Promise<Record<string, unknown>>;
  /** Cindy Core 原生媒体调用器;能力本身不依赖任何插件。 */
  callMedia?(request: CindyMediaToolRequest): Promise<Record<string, unknown>>;
  /**
   * 现查"已装且唤醒"的意识清单(总机不缓存——装/卸/唤醒/沉睡即时反映,
   * 这正是网关模式让老会话立即生效的机制)。
   */
  listAwakeGhosts(): Promise<CindyGhostInfo[]>;
  /**
   * 按 id 现查单个当前可用插件;与 ghost_call 共享同一可见性判定。
   * 判序:不存在 → 未登录 → 当前工作目录停用 → 未启用。
   */
  getAwakeGhost(ghostId: string, namespace?: string | null): Promise<CindyGhostInfoHostResult>;
  /**
   * 读取已声明的随包手册;Host 每次调用都重新执行插件可见性判定,且不启动沙箱。
   */
  readGhostManual(request: {
    ghostId: string;
    namespace?: string | null;
    path?: string;
  }): Promise<CindyGhostManualResult>;
  /**
   * 把工具调用派进目标意识的电子脑并等待结果(按需拉起沙箱、超时、
   * 崩溃分类全在 host 侧处理)。
   */
  callGhostTool(request: {
    ghostId: string;
    namespace?: string | null;
    tool: string;
    args: Record<string, unknown>;
    /** Host-only cancellation from the MCP request; never enters plugin args. */
    signal?: AbortSignal;
    /**
     * 媒体过户(可选):会话里用户媒体或当前 Agent / Core 工具生成结果的
     * 地址(xdt-image:// / cindy-media://blobs/ / 本机绝对路径,主机归一化并验归属)。
     * host 把每张图落媒体总仓、给目标意识记可读引用(人工确认的引渡才形成
     * 按张永久授权;工作目录/Full Access 等 Host 代办交接不冒充用户授权),
     * 再以指纹数组注入 args.attachments 交给意识。工具生成结果也必须由
     * Agent 显式传入,不会由 Host 自动回调插件——
     * 意识拿到的仍只是字符串指纹,摸不到路径与字节。
     */
    attachments?: string[];
    /**
     * 批量交接(可选):true 时本次调用**只做 attachments 过户、不派发
     * 工具**(tool/args 被忽略)。用途:agent 计划连续多次调用同一意识、
     * 每次用一个 workdir 外文件时,可把整批文件一次性交接。Ask 可整批确认;
     * Auto 沿用实际审批负责人,本地 Full Access 自动交接,
     * 且不会形成降档后仍生效的人工永久授权。
     * 普通调用 attachments 上限 4 项,grant_only 放宽(上限由 host 定)。
     */
    grantOnly?: boolean;
    /**
     * 目录过户(可选):要整体交给意识上传的本地目录**绝对路径**(部署
     * 构建产物等场景)。host 验证路径;workdir 内直接放行,workdir 外仅
     * 本地 Full Access 自动交接,Auto 沿用实际审批负责人,Ask 须确认;远程
     * 任务不能借档位自动授权控制端文件。随后收集
     * 文件并预检限额、发一次性限时票据,以 args.dir_deposit =
     * { token, file_count, total_bytes, rel_paths } 注入交给意识——意识拿到
     * 的只有票据与相对路径清单,摸不到绝对路径与文件字节;上传时经
     * fetch-request 的 uploadDir 报 token,主机凭票读盘代组 multipart。
     */
    dir?: string;
    /**
     * 下行落盘过户(可选):让意识把下载的文件存进的本地目录**绝对路径**
     * (附件下载等场景)。host 验证为已存在目录;workdir 内直接放行,
     * workdir 外本地 Full Access 自动交接,Auto 沿用实际审批负责人,Ask 须
     * 确认;远程任务不能借档位自动授权控制端文件。随后发限时票据,以 args.save_deposit = { token, dir_name } 注入
     * 交给意识——意识经 fetch-request 的 as:'file' + saveTo 报 token,主机
     * 把响应字节直接写进该目录(文件名消毒去重,不覆盖);意识全程摸不到
     * 绝对路径与文件字节。
     */
    saveDir?: string;
    /**
     * Agent 基于 ghost_info / ghost_list 返回的 setup 编排展示计划。Host 必须按最新
     * assessment 校验 revision、requirementRefs、actionId 和覆盖关系;
     * 本字段永不注入插件 args,也不代表授权或完成。
     */
    setupPlan?: CindyGhostSetupPlan;
    /**
     * agent 侧 tool_use id(卡槽③锚定用,可选):claude 路径由 MCP 请求的
     * `_meta["claudecode/toolUseId"]` 提供(未文档化 key,取不到属正常路径);
     * codex 路径无此值。host 把它登记给卡片服务,renderer 据此把进行中的
     * 卡片精确锚到消息流对应工具行。
     */
    agentToolUseId?: string;
  }): Promise<CindyGhostCallResult>;
  /**
   * 花名册快照(可选,同步):server 创建(= 会话装配)时调用一次,把
   * "已装且唤醒"的意识名单 + 召回线索写进 ghost_list 的工具
   * 描述——模型开局即认识本机意识,语义召回不再依赖字面词表命中。
   * 会话内工具定义恒定(prompt 缓存安全);装/卸/唤醒/沉睡在新会话生效,
   * 实时清单仍以 ghost_list 为准。缺省 = 不注入(描述与今日基线一致)。
   */
  getRosterItems?(): Array<Pick<CindyGhostInfo, 'id' | 'name' | 'command' | 'recall' | 'namespace'>>;
  /** 意识编写手册(markdown,随主机版本走;agent 写意识前先读)。 */
  forgeGuide(): Promise<string>;
  /**
   * 在新的目标目录创建一份安全起步骨架。目标已存在时必须拒绝,绝不覆盖
   * 用户文件;Node 模板只生成随包源码,不安装依赖。
   */
  forgeScaffold(request: {
    dir: string;
    template: CindyForgeScaffoldTemplate;
    id: string;
    name: string;
    description?: string;
    /** 省略时由正式版 Host 使用自身版本;开发构建必须明确填写。 */
    minCindyVersion?: string;
  }): Promise<CindyForgeScaffoldResult>;
  /**
   * 把一个源码目录校验并打包成 .cindy。只生成产物,不安装或更新插件;
   * publish 意图额外签发一次性发布票据。
   */
  forgePack(request: {
    dir: string;
    intent?: 'publish';
    /**
     * 用户明确选择 AI 图标后,由图片工具返回的 cindy-media 地址。Host
     * best-effort 把它嵌入包内;失败保留源码里的默认图标,不阻塞打包。
     */
    iconSource?: string;
  }): Promise<CindyForgePackResult>;
  /**
   * 重新校验并打包源码目录,然后把这次产生的确切包安装或原位更新。
   * 只有显式调用本工具才安装;forgePack 本身始终保持纯打包。
   */
  forgeInstall(request: { dir: string; iconSource?: string; targetInstanceId?: string; installCopy?: boolean; namespace?: string | null }): Promise<CindyForgeInstallResult>;
  /**
   * 消费 forgePack(intent=publish) 签发的一次性票据,把该次打包的确切字节
   * 提交到当前组织发布。立即返回 transferId / uploadId,传输在后台跑。
   */
  forgePublish(request: { token: string }): Promise<CindyForgePublishResult>;
  /** 查询一次后台发布传输的当前状态。 */
  forgePublishStatus(request: { transferId: string }): Promise<CindyForgePublishStatusResult>;
  /** Ordinary personal community author capability, separate from organization Forge publishing. */
  communityContribution?(request:
    | { action: 'prepare'; ghostId: string; namespace?: string | null }
    | { action: 'submit' | 'status' | 'cancel'; id: string }
    | { action: 'list'; query?: string; filter?: 'all' | 'pending' | 'needs_action' | 'published'; cursor?: string }
    | { action: 'detail'; pluginId: string; cursor?: string }
    | { action: 'submission'; pluginId: string; submissionId: string }
    | { action: 'cancel-review'; pluginId: string; release: { releaseId: string; sha256: string; revision: string } }
  ): Promise<unknown>;
  logger?: {
    info: (msg: string, meta?: Record<string, unknown>) => void;
    warn: (msg: string, meta?: Record<string, unknown>) => void;
  };
}