@ai_mind/ade-plugin-sdk 0.0.0-stage → 0.1.0

package/types/ade-types.d.ts

@@ -0,0 +1,712 @@
+// 由 sdk/scripts/sync-types.mjs 从 ADE 宿主生成，请勿手工修改。
+export interface Project {
+    /** Absolute path of the project directory */
+    path: string;
+    /** Display name (basename) */
+    name: string;
+    /** Last opened timestamp */
+    lastOpened: number;
+}
+export interface Worktree {
+    /** Absolute path of the worktree directory */
+    path: string;
+    /** Branch name (null when detached) */
+    branch: string | null;
+    /** Commit hash the worktree points to */
+    commit: string;
+    /** True when this is the main working tree of the git repo */
+    main: boolean;
+    /** True when this worktree is the project directory itself (non-git "current dir" mode) */
+    current: boolean;
+}
+export interface FileNode {
+    name: string;
+    path: string;
+    type: 'file' | 'dir';
+    /** Children, only present when type === 'dir' and expanded */
+    children?: FileNode[];
+}
+/** 复制/创建副本后实际写入磁盘的条目 */
+export interface CopiedEntry {
+    path: string;
+    type: 'file' | 'dir';
+}
+/**
+ * 文件探测结果：路径不存在/不可访问时用 kind='missing' 表达，不抛错。
+ * 编辑器靠它区分「不是文件」（目录、已删除）与「临时读到一半」。
+ */
+export interface FileStat {
+    mtimeMs: number;
+    size: number;
+    kind: 'file' | 'dir' | 'other' | 'missing';
+}
+/** A chat adapter entry (built-in or registered by a plugin) */
+export interface ChatAdapterInfo {
+    id: string;
+    label: string;
+    description?: string;
+    kind: 'terminal' | 'sdk';
+    /** Spawn command for terminal adapters */
+    command?: string;
+    /** Plugin that registered this adapter, if any */
+    plugin?: string;
+    /**
+     * 该 agent CLI 的「YOLO / 跳过权限确认」参数（如 qoder 的 --dangerously-skip-permissions）。
+     * 未声明表示该 CLI 没有这类参数，设置页不提供 YOLO 开关。
+     */
+    yoloFlag?: string;
+}
+export type { PluginInfo } from './plugins.js';
+export interface OpenTab {
+    path: string;
+    name: string;
+}
+export interface ChatSessionInfo {
+    id: string;
+    adapterId: string;
+    adapterLabel: string;
+    worktree: string;
+    cwd: string;
+    running: boolean;
+    /** 适配器是否支持原生结构化对话（聊天视图） */
+    chatSupported: boolean;
+    /** 底层 agent CLI 的会话标识（聊天视图与终端视图共用，切换不丢内容） */
+    cliSessionId?: string;
+    /** 该标识是否已经持久化，可安全传给 CLI/App Server 执行 resume。 */
+    cliSessionResumable?: boolean;
+    /** 协议是否原生流式输出（true 时渲染层直接显示增量；false 用打字机动画） */
+    streaming?: boolean;
+    /** CLI/插件当前是否可用；历史中的会话在适配器缺失时仍可查看 */
+    available?: boolean;
+    /** 适配器是否支持把本地文件作为对话附件发送 */
+    attachmentSupported?: boolean;
+    /** 适配器实际接受的附件类型；路径引用不属于附件。 */
+    attachmentKinds?: ChatAttachmentKind[];
+}
+/** 从 CLI --help 解析出的可配置选项（新会话对话框动态渲染，与 CLI 对齐） */
+export interface CliOption {
+    /** 长选项名，如 --model */
+    flag: string;
+    /** 短选项名，如 -m */
+    short?: string;
+    /** 是否接收参数值 */
+    takesValue: boolean;
+    /** help 中声明的可选值（choices），无则自由输入 */
+    choices?: string[];
+    /** 面向用户的中文字段名；未提供时由 flag 生成。 */
+    label?: string;
+    /** 选项值的显示名（传给 CLI / App Server 的仍是原始 value）。 */
+    choiceLabels?: Record<string, string>;
+    /** 选项值的补充说明，用于 title 提示。 */
+    choiceDescriptions?: Record<string, string>;
+    /** 依赖另一个配置项时，按其值提供不同 choices（例如模型对应的思考等级）。 */
+    dependsOn?: string;
+    choicesByValue?: Record<string, string[]>;
+    /** CLI/App Server 的当前默认值；空配置仍表示跟随 provider 默认。 */
+    defaultValue?: string;
+    defaultValuesByValue?: Record<string, string>;
+    description: string;
+    /** 是否为核心配置项（协议声明，显示在对话配置条上；其余在「更多配置」） */
+    core?: boolean;
+}
+/** agent CLI 返回的模型选择项；value 是实际传给 --model 的值。 */
+export interface CliModelOption {
+    value: string;
+    label: string;
+    /** 面向用户的分组标题，例如“默认（Default）”。 */
+    group?: string;
+    description?: string;
+    /** 模型上下文窗口（tokens），CLI 输出可解析时提供（如 pi --list-models 的 context 列） */
+    contextWindow?: number;
+}
+/** 结构化消息内容块（原生对话视图的数据单元） */
+export type StructuredBlock = {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'plan';
+    text?: string;
+    steps?: Array<{
+        step: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    }>;
+} | {
+    type: 'file_change';
+    changes: Array<{
+        path: string;
+        kind: string;
+        diff?: string;
+    }>;
+    status?: string;
+} | {
+    type: 'diff';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+    /** 工具执行结果（渲染层按 tool_use_id 挂载） */
+    result?: {
+        content: string;
+        isError?: boolean;
+    };
+} | {
+    type: 'tool_result';
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+};
+export type ChatAttachmentKind = 'image' | 'file';
+/** 用户在图形化对话中附加的本地文件。 */
+export interface ChatAttachment {
+    path: string;
+    name: string;
+    /** image / file；不依赖渲染进程自行猜测 MIME。 */
+    kind: ChatAttachmentKind;
+}
+export interface ChatMessageRecord {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content?: string;
+    blocks?: StructuredBlock[];
+    attachments?: ChatAttachment[];
+    /** 消息是否已产出完整内容（结构化事件按 messageId 更新）。 */
+    done?: boolean;
+    /** 排队、发送或取消状态；缺省表示已完成的普通历史消息。 */
+    status?: 'queued' | 'sending' | 'cancelled' | 'error';
+    createdAt: number;
+    /** 用于把 CLI 原生历史与 ADE 辅助消息安全合并。 */
+    source?: 'ade' | 'provider' | 'system';
+}
+export interface ChatApprovalQuestion {
+    id: string;
+    header: string;
+    question: string;
+    secret?: boolean;
+    options?: Array<{
+        label: string;
+        description?: string;
+    }>;
+}
+/** agent 在一轮对话中等待用户确认或补充输入。 */
+export interface ChatApprovalRequest {
+    requestId: string;
+    kind: 'command' | 'file_change' | 'user_input';
+    title: string;
+    detail?: string;
+    command?: string;
+    cwd?: string;
+    url?: string;
+    questions?: ChatApprovalQuestion[];
+    allowForSession?: boolean;
+}
+export interface ChatApprovalResponse {
+    decision?: 'accept' | 'accept_for_session' | 'decline' | 'cancel';
+    answers?: Record<string, string[]>;
+}
+export interface ChatTokenUsage {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    reasoningOutputTokens?: number;
+    totalTokens?: number;
+    contextWindow?: number;
+    /** provider 直接给出的上下文占用比例（0-1），如 qoder 的 context_usage_ratio；展示时优先于推算 */
+    contextUsedRatio?: number;
+    /** 产生该统计的模型（用于按模型列表推断上下文窗口） */
+    model?: string;
+}
+/** 主进程持久化、渲染进程直接水合的完整会话快照。 */
+export interface ChatSessionRecord {
+    info: ChatSessionInfo;
+    /** 会话记录的创建来源；用于避免 provider 扫描与 daemon/relay 记录互相覆盖。 */
+    origin?: 'desktop-created' | 'relay-created' | 'provider-indexed';
+    /** 0.21.3 写入的兼容字段；读取后迁移到 origin。 */
+    externalOrigin?: 'relay-created';
+    /** 是否作为当前工作区中的已打开会话展示；关闭后仍保留在历史中。 */
+    open: boolean;
+    kind: 'terminal' | 'sdk';
+    chatSupported: boolean;
+    view: 'terminal' | 'chat';
+    messages: ChatMessageRecord[];
+    /** 有界终端回放缓冲；完整上下文仍由 CLI 自己持久化。 */
+    raw: string;
+    turnRunning: boolean;
+    config: Record<string, string>;
+    projectPath: string | null;
+    name: string;
+    createdAt: number;
+    lastActiveAt: number;
+    updatedAt: number;
+    queuedCount: number;
+    pendingApproval?: ChatApprovalRequest | null;
+    usage?: ChatTokenUsage;
+}
+export interface ChatHistoryFile {
+    version: 1;
+    sessions: ChatSessionRecord[];
+}
+/** 结构化对话事件（主进程解析 agent CLI 协议后广播给渲染层） */
+export interface StructuredEvent {
+    kind: 'init' | 'message' | 'tool_result' | 'result' | 'exit' | 'error' | 'approval' | 'approval_resolved' | 'usage';
+    /** CLI 会话标识（init/result 事件携带） */
+    sessionId?: string;
+    messageId?: string;
+    role?: 'user' | 'assistant' | 'system';
+    blocks?: StructuredBlock[];
+    attachments?: ChatAttachment[];
+    /** tool_result 事件：对应的 tool_use id */
+    toolUseId?: string;
+    /** tool_result 事件：工具输出；result 事件：本轮最终文本；error 事件：错误消息 */
+    content?: string;
+    text?: string;
+    isError?: boolean;
+    model?: string;
+    message?: string;
+    approval?: ChatApprovalRequest;
+    usage?: ChatTokenUsage;
+    done?: boolean;
+}
+/** 单个 worktree 记忆的编辑区状态（打开文件、活动标签、各文件浏览位置） */
+export interface WorktreeTabState {
+    openTabs: string[];
+    activeTab: string | null;
+    dirty: Record<string, boolean>;
+    /** 各文件在该 worktree 下的滚动位置（px），用于切回时恢复浏览位置 */
+    scrolls: Record<string, number>;
+}
+export type AreaKey = 'project' | 'worktree' | 'files' | 'editor' | 'chat' | 'dingtalk' | 'aone';
+export type AoneCategory = 'req' | 'bug' | 'task';
+/** a1 CLI 可用性与 BUC 登录状态。 */
+export interface AoneStatus {
+    available: boolean;
+    authenticated: boolean;
+    message: string;
+    executable?: string;
+    version?: string;
+    account?: {
+        username?: string;
+        name?: string;
+        employeeId?: string;
+        email?: string;
+    };
+}
+export interface AoneFieldOption {
+    identifier: string;
+    displayValue: string;
+    value: string;
+}
+export interface AoneWorkItemType {
+    identifier: string;
+    displayName: string;
+    category: AoneCategory;
+    isDefault: boolean;
+    statuses: AoneFieldOption[];
+    priorities: AoneFieldOption[];
+}
+/** 同名状态在不同工作项类型中可能使用不同 identifier，按显示值合并为一列。 */
+export interface AoneBoardColumn {
+    key: string;
+    name: string;
+    typeIds: string[];
+    identifiers: Record<string, string>;
+}
+export interface AoneMember {
+    employeeId: string;
+    realName: string;
+    nickname: string;
+    status?: string;
+    roleName?: string;
+}
+export interface AoneView {
+    identifier: string;
+    name: string;
+    type?: string;
+    category?: string;
+}
+export interface AoneWorkItem {
+    id: string;
+    title: string;
+    url: string;
+    category: AoneCategory;
+    typeIdentifier?: string;
+    typeName?: string;
+    status: string;
+    assignee?: string;
+    assigneeId?: string;
+    priority?: string;
+    sprint?: string;
+    module?: string;
+    updatedAt?: string;
+}
+export interface AoneBoardData {
+    project: {
+        id: string;
+        name: string;
+        description?: string;
+    };
+    types: AoneWorkItemType[];
+    columns: AoneBoardColumn[];
+    cards: AoneWorkItem[];
+    members: AoneMember[];
+    views: AoneView[];
+    loadedAt: string;
+}
+export interface AoneBoardRequest {
+    /** 项目 ID，或包含项目 ID 的 Aone 工作项 URL。 */
+    project: string;
+    categories?: AoneCategory[];
+    filter?: string;
+    view?: string;
+    refreshMetadata?: boolean;
+}
+export interface AoneWorkItemField {
+    identifier: string;
+    label: string;
+    value: unknown;
+    displayValue?: string;
+    format?: string;
+    className?: string;
+    required?: boolean;
+}
+export interface AoneComment {
+    id: string;
+    author?: string;
+    createdAt?: string;
+    content: string;
+}
+export interface AoneActivity {
+    actionType?: string;
+    eventTime?: string;
+    operator?: string;
+    property?: string;
+    oldValue?: string;
+    newValue?: string;
+}
+export interface AoneRelationItem {
+    type?: string;
+    id?: string;
+    title?: string;
+    status?: string;
+    assignee?: string;
+    name?: string;
+    url?: string;
+}
+export interface AoneAttachment {
+    id: string;
+    name: string;
+    size?: string;
+    creator?: string;
+    createdAt?: string;
+}
+export interface AoneWorkItemDetail {
+    id: string;
+    title: string;
+    url: string;
+    description?: string;
+    creator?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    fields: AoneWorkItemField[];
+    comments: AoneComment[];
+    activity: AoneActivity[];
+    relations: Record<string, AoneRelationItem[]>;
+    attachments: AoneAttachment[];
+    /** 辅助数据失败不应阻塞详情主体，用中文提示降级项。 */
+    partialErrors: string[];
+}
+export interface AoneCreateField {
+    identifier: string;
+    displayName: string;
+    required: boolean;
+    format?: string;
+    className?: string;
+    aliases: string[];
+    options: AoneFieldOption[];
+}
+export interface AoneCreateRequest {
+    projectId: string;
+    category: AoneCategory;
+    typeId: string;
+    title: string;
+    description?: string;
+    fields?: Record<string, string | string[]>;
+}
+export interface AoneUpdateRequest {
+    id: string;
+    status?: string;
+    assignee?: string;
+    sprint?: string;
+    priority?: string;
+    module?: string;
+}
+export type ThemeMode = 'light' | 'dark' | 'system';
+export type Density = 'standard' | 'compact';
+export interface AppearanceSettings {
+    /** 浅色 / 深色 / 跟随系统 */
+    theme: ThemeMode;
+    /** 强调色（hex，如 #0a7cff） */
+    accent: string;
+    /** UI 密度 */
+    density: Density;
+    /** 侧栏毛玻璃（macOS vibrancy） */
+    vibrancy: boolean;
+}
+export interface EditorSettings {
+    /** 正文字体栈 */
+    fontFamily: string;
+    /** 正文字号（px） */
+    fontSize: number;
+    /** 行高 */
+    lineHeight: number;
+    /** 字距（em） */
+    letterSpacing: number;
+    /** 代码字体栈 */
+    codeFontFamily: string;
+    /** 代码字号（px） */
+    codeFontSize: number;
+    /** 有预览的代码块（mermaid/svg/latex）默认只看图 */
+    previewOnlyByDefault: boolean;
+}
+export interface AgentSettings {
+    /** 从「新对话」列表隐藏的 adapter id */
+    hidden: string[];
+    /**
+     * 启用 YOLO（跳过权限确认）的 adapter id：新建会话时自动把该 CLI 的
+     * yoloFlag 并入会话配置；已有会话保持创建时的设置不变。
+     */
+    yolo: string[];
+}
+export interface DingTalkSettings {
+    cli: 'dws' | 'dwsx';
+    dwsxPath: string;
+    /** 留空使用 DWSX_DATA_DIR 或 ~/.local/share/dwsx，与终端共用登录态 */
+    dwsxDataDir?: string;
+    /** dws CLI 路径；留空时自动从 PATH 与常见目录探测 */
+    dwsPath: string;
+}
+export interface AppSettings {
+    appearance: AppearanceSettings;
+    editor: EditorSettings;
+    agents: AgentSettings;
+    dingtalk: DingTalkSettings;
+}
+/** 应用状态（原 state.json + localStorage ade-areas 的统一归宿） */
+export interface AdeState {
+    projects: Project[];
+    areasVisible: Record<AreaKey, boolean>;
+    worktreeTabs: Record<string, WorktreeTabState>;
+    /** 插件功能区域的显示状态，以插件 ID 和区域 ID 组合为 key。 */
+    pluginAreasVisible?: Record<string, boolean>;
+}
+/** ~/.ade/settings.json 的完整结构 */
+export interface AdeSettingsFile {
+    version: 2;
+    settings: AppSettings;
+    state: AdeState;
+}
+/** settings:set 的增量补丁：各节按 key 浅合并，数组字段整体替换 */
+export interface SettingsPatch {
+    settings?: {
+        appearance?: Partial<AppearanceSettings>;
+        editor?: Partial<EditorSettings>;
+        agents?: Partial<AgentSettings>;
+        dingtalk?: Partial<DingTalkSettings>;
+    };
+    state?: Partial<AdeState>;
+}
+/** 设置页 Agent 列表项（桌面可新建的适配器 + 当前隐藏状态） */
+export interface AgentSettingInfo extends ChatAdapterInfo {
+    hidden: boolean;
+}
+/** dws / 钉钉集成状态（设置页与钉钉面板共用） */
+export interface DingTalkStatus {
+    cliKind?: 'dws' | 'dwsx';
+    dataDirectory?: string;
+    available: boolean;
+    authenticated: boolean;
+    version?: string;
+    /** dws 0.x 旧版接口线：上传走 doc create 而非 doc import */
+    legacy?: boolean;
+    message: string;
+    executable?: string;
+}
+/** 钉钉在线文档搜索结果条目 */
+export interface DingTalkDocItem {
+    nodeId: string;
+    name: string;
+    docType?: string;
+    url?: string;
+    createTime?: number | string;
+    modifiedTime?: number | string;
+    creatorUid?: string;
+    creatorName?: string;
+    creatorNick?: string;
+    workspaceId?: string;
+    workspaceName?: string;
+}
+export type DingTalkDocDownloadFormat = 'dingdoc' | 'markdown';
+/** 钉钉听记列表条目 */
+export interface DingTalkMinutesItem {
+    taskUuid: string;
+    title: string;
+    url?: string;
+    startTime?: number | string;
+    status?: string;
+    creatorUid?: string;
+    creatorName?: string;
+    creatorNick?: string;
+}
+/** 下载到本地的结果 */
+export interface DingTalkDownloadResult {
+    kind: 'doc' | 'minutes';
+    path: string;
+    title?: string;
+    url?: string;
+    taskUuid?: string;
+    /** dingdoc / dingmin 文件夹等场景下应打开的首选文件 */
+    entryPath?: string;
+    /** 钉钉文档/听记下载格式 */
+    format?: 'dingdoc' | 'dingmin' | 'markdown';
+}
+/** 可作为上传目标的钉钉知识库 / 个人空间 */
+export interface DingTalkUploadWorkspace {
+    workspaceId: string;
+    name: string;
+    /** org = 组织知识库；mine = 「我的文档」个人空间 */
+    type: 'org' | 'mine';
+}
+/** 知识库内的文件夹节点（上传目标位置选择） */
+export interface DingTalkUploadFolderNode {
+    nodeId: string;
+    name: string;
+}
+/** 粘贴钉钉链接后解析出的上传目标 */
+export interface DingTalkUploadTarget {
+    /** 知识库 ID / URL */
+    workspace: string;
+    /** 文件夹 ID / URL */
+    folder: string;
+    /** 给人看的位置描述 */
+    label: string;
+    /** 链接指向文档本身时：可作为覆盖上传目标 */
+    document?: {
+        nodeId: string;
+        name: string;
+    };
+}
+/** 上传本地 Markdown 为钉钉文档的结果 */
+export interface DingTalkUploadResult {
+    success: boolean;
+    documentUrl?: string;
+    nodeId?: string;
+    documentName?: string;
+    taskId?: string;
+    message?: string;
+    /** 随文档上传的本地图片（含 SVG）统计；无本地图片时不存在 */
+    images?: {
+        total: number;
+        inserted: number;
+        /** 上传失败的本地图片文件名 */
+        missing: string[];
+        /** 未能清理的占位块数量 */
+        leftoverPlaceholders: number;
+    };
+}
+/**
+ * dwsx JSONML 读取范围。不传 scope = 整篇 canonical body（root）；
+ * outline 只取标题大纲（fragment，heading 带 uuid，可当块 ID）。
+ */
+export type DingTalkJsonmlScope = 'outline' | 'tags' | 'section' | 'range';
+/** dwsx doc read --content-format jsonml 的读取选项 */
+export interface DingTalkJsonmlReadOptions {
+    scope?: DingTalkJsonmlScope;
+    /** scope=tags：只取指定标签的块 */
+    tags?: string[];
+    /** scope=range：起始块 ID（可从块列表 / outline 的 uuid 取） */
+    startBlockId?: string;
+    /** scope=range：结束块 ID */
+    endBlockId?: string;
+    /** scope=section/outline：最大层级 */
+    maxDepth?: number;
+    /** 指定文档历史版本 */
+    version?: number | string;
+    /** 落盘路径；留空写入 ADE 钉钉缓存目录，读回文件即覆盖前的备份 */
+    outputPath?: string;
+}
+/** JSONML canonical body（["root"|"fragment", attrs, ...blocks]）读取结果 */
+export interface DingTalkJsonmlDocument {
+    nodeId: string;
+    jsonml: unknown[];
+    contentFormat: 'jsonml';
+    /** 落盘备份路径，可直接作为 overwriteDocJsonml 的 filePath 回写 */
+    savedPath?: string;
+    bytes?: number;
+    revision?: string;
+    scope?: DingTalkJsonmlScope;
+}
+/**
+ * JSONML 覆盖输入：裸数组 / { jsonml: [...] } / { jsonml: "…" } / 读回落盘的信封。
+ * filePath 与对象形态都接受，ADE 与 dwsx 一样逐层解包。
+ */
+export type DingTalkJsonmlInput = unknown[] | {
+    jsonml: unknown;
+} | {
+    filePath: string;
+};
+/** JSONML 整篇覆盖结果 */
+export interface DingTalkJsonmlWriteResult {
+    success: boolean;
+    message?: string;
+    nodeId?: string;
+    documentUrl?: string;
+    documentName?: string;
+    chunksWritten?: number;
+}
+/** 块 element 写入结果（dwsx doc block update / insert） */
+export interface DingTalkBlockWriteResult {
+    success: boolean;
+    message?: string;
+}
+/** 日志等级：error > warn > info > debug */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** 单条日志 */
+export interface LogEntry {
+    id: number;
+    /** ISO 时间戳 */
+    time: string;
+    level: LogLevel;
+    /** 模块标签，如 chat / daemon / renderer */
+    scope: string;
+    message: string;
+    /** 错误堆栈 / 附加数据 */
+    detail?: string;
+}
+/** 日志列表过滤条件 */
+export interface LogFilter {
+    /** 最低严重级别：debug 表示全部 */
+    level?: LogLevel;
+    scope?: string;
+    query?: string;
+    limit?: number;
+}
+/** 可恢复的钉钉上传任务，正文与图片分别记录完成状态。 */
+export interface DingTalkUploadJob {
+    filePath: string;
+    title?: string;
+    folder?: string;
+    workspace?: string;
+    nodeId?: string;
+    status: 'running' | 'failed' | 'completed';
+    step: string;
+    error?: string;
+    result?: DingTalkUploadResult;
+    steps: {
+        label: string;
+        status: 'running' | 'completed' | 'failed';
+    }[];
+}