ATKONBASE

外观

更新日志 ​

本页记录 ATKONBASE 对集成方可感知的对外能力变更——新增 / 调整的 V1 与公开分享端点、SDK 用法变化、契约调整、行为修正等。纯内部重构、构建基建调整等对集成方不可见的变更不在此列。

条目按日期倒序排列。标注 Breaking 的条目表示对已对接代码可能造成不兼容影响，升级前请重点关注。

2026-07-30 ​

新增 ​

  • 公开分享元信息新增「是否可下载」字段：GET /public/s/{tenantCode}/{token} 返回的元信息新增只读 canDownload——false 表示该链接只授了浏览权。自建取件界面的集成方请读取该字段决定是否呈现下载入口：只授浏览权的链接现在可以正常读元信息与浏览目录，拒绝点移到了下载环节，不读该字段会渲染出必然失败的下载入口。随 Java / TypeScript SDK 2.3.0 提供。

变更 ​

  • 公开分享端点的权限位按端点分别判定：元信息端点持 READ(1) 或 DOWNLOAD(2) 任一即可读，目录浏览（/list）要求 READ，字节下载（/download）要求 DOWNLOAD。此前三条路径一律要求 DOWNLOAD，只授 READ 的链接连元信息都取不到、表现与链接失效无从区分；现在这类链接元信息与目录浏览照常可用，仅下载以 174001 SHARE_LINK_UNAVAILABLE 拒绝。撤销 / 过期 / IP 白名单三项校验在三条路径上口径不变。
  • 分享链接创建结果中的 url 字段值与语义不变（相对 API 基地址的公开消费路径），分享模式篇已按此更正字段说明——此前文档误述为完整可分发地址。

2026-07-27 ​

变更 ​

  • 改密后该账号全部登录会话立即失效：自助修改密码或由管理员重置密码后，该账号已签发的全部登录会话立即失效（含发起本次修改的会话），且无法凭刷新令牌恢复，须用新密码重新登录。开放接口自助改密（POST /v1/users/me/changePassword）同样生效。
  • 新密码长度统一要求 6~128 位：改密接口按此口径校验，接口描述与 SDK 生成的字段说明同步标注。

修复 ​

  • 分片上传初始化的落点口径与直接上传对齐：POST /v1/versions/initChunkedUpload 新建文档时 containerId 可留空，留空即落当前租户默认容器（与 POST /v1/versions/upload 同语义）；初始化、分片传输与合并全链路同步放行，受权限控制的调用方不会再在首片被拒。显式指定 containerId 时的写权限检查不变。
  • 平台自动动作写入的创建人 / 更新人信息补全：Webhook 投递、定时清理、数据导出、通讯录增量同步等后台动作此前写入的数据缺少创建人 / 更新人标识，现在有明确受理人的动作记录该受理人、无受理人的系统动作统一记录为 SYSTEM；读取文档 / 衍生物审计字段的集成方可感知。

2026-07-26 ​

新增 ​

  • PDF 版本自动具备预览衍生物：源文件为 PDF 时平台自动派生 PREVIEW 衍生物，衍生物列表中可见，可按 kind=PREVIEW 取内联预览链接。该派生直接引用源文件字节、不复制一份新字节，也不额外计入存储用量。客户端显式上传的预览件优先级更高：上传件覆盖派生件，派生与重新派生都不会覆盖已上传的预览件。

变更 ​

  • 衍生物「不适用」状态覆盖「本就不适用」场景：某加工类型对该版本本就不适用时（文件类型不路由该加工、类型级能力未开启、超出体积上限），衍生物列表现在返回一条「不适用」终态记录，不再整行缺席。此前「尚未处理完」与「本就不适用」都表现为列表里没有该项、无法区分，现可直接按状态判定。重新派生按当次适用性复位，不适用的加工类型不参与。

2026-07-25 ​

修复 ​

  • 修复官方 Java SDK 上传中文等非 ASCII 文件名文件时，请求在客户端即报错、无法发出的问题（versionUpload / versionUploadChunk / renditionUpload 三个上传入口均受影响）：现按标准 multipart 语义以 UTF-8 原文提交文件名，服务端保存并回显的原始文件名为上传原文。TypeScript SDK 无此问题。随 Java / TypeScript SDK 2.2.1 提供。

2026-07-22 ​

新增 ​

  • 自建检索模式开箱即得中文检索能力：部署基线捆绑的检索组件内置中文分词，全新部署无需再手工安装分词插件即可使用中文全文检索，混合检索在自建模式下完整可用。

变更 ​

  • 生产环境默认关闭 OpenAPI 接口描述端点与 swagger-ui 页面：不再无鉴权暴露全量接口面；排障需要时可经部署配置临时开启，本地 / 开发环境行为不变。

修复 ​

  • 修复本地 / 单机部署运行 OAuth 授权码流、且平台对外基地址未显式配置时，登录跳转指向不可达地址的问题：现按请求自身的协议与主机自动解析；生产部署仍以显式配置的对外地址为准。

2026-07-21 ​

新增 ​

  • 新增资源级字段直绑（POST /v1/resourceFieldBindings/{bind,unbind,update,getByResource,getUsagePage}）：可把单个字段直接绑定到某个文档或容器实例，无需为此新建一次性模板。字段随即进入该资源的表单 Schema，可写值、可校验，绑定时可覆盖必填、默认值、排序三项配置。
    • 直绑一个该资源类型上已有的字段时自动退化为「配置覆盖」：仅调整必填 / 默认值 / 排序，字段仍归原分组、仍标记为来自类型层，其余属性不受影响。
    • 表单 Schema 的字段来源新增「本资源直绑」一档，与「类型给的」「资源模板给的」并列，便于在界面上区分并给出对应解绑入口。
    • 绑定 / 解绑 / 按资源查询各成一套；按资源查询（getByResource）会区分新增型与覆盖型直绑，并同时给出字段定义原值、本资源覆盖值与最终生效值。解绑后字段离开表单 Schema，已写入的值保留并以遗留字段形态呈现（与解除资源模板绑定同待遇）。
    • 容器上的直绑字段只属于该容器自身，不随子文档 / 子容器创建被拷贝下去；需要整棵子树共享一组字段仍绑模板。文档切换类型后，其直绑字段与已写入的值不受影响。
    • 更新覆盖配置端点（update）可单独调整已直绑字段的必填 / 默认值 / 排序，无须解绑重绑，字段不会短暂离开表单 Schema；也可把某项覆盖显式清空、回落到跟随字段定义（与「本次不改动该项」是两种可区分的意图）。
    • 字段使用点盘点端点（getUsagePage）：给定字段可查出直绑它的文档与容器，按资源类别分别分页；结果按调用者对资源的访问权限过滤，无权访问的资源不出现、也不计入总数。
    • 新增校验错误码 182088 与 182090-182096，详见元数据错误码 182*。

变更 ​

  • 元数据表单字段来源标签更新：新增「本资源直绑」一档，原「本资源配置」改称「资源模板」，两者在结果中可区分。
  • 字段定义删除新增一道拦截：被任一文档或容器直绑引用的字段拒绝删除（错误码 182088）；想删除时先用字段使用点盘点查出这些资源并逐个解绑。
  • 文档类型切换预检说明明确化：预检比对仅覆盖类型层字段，本文档的字段直绑与资源模板绑定不随切换清除、切换后仍然有效。
  • 服务启动窗口内统一返回「服务未就绪」（HTTP 503，错误码 178009）：实例启动尚未完成时接口不再返回具有误导性的「授权不足」（HTTP 403），而是返回可自愈的 503，启动完成后自动恢复。两种情形可按状态码区分——503/178009 稍后重试即恢复，403 需调整部署授权档位。该修正同样覆盖启动窗口内的登录能力集与菜单下发。详见系统 / 功能门错误码 178*。
  • 单文档就绪度诊断结论改按「还剩哪几条召回路能查到」判定：某一步出了异常但两条召回路都还能查到内容时，该步降为提示并说明现有检索内容仍可用，结论指向真正让内容查不到的那一步。诊断码取值集合不变，已有的码映射无需调整；诊断结论文案现区分断点程度（两条召回路都查不到、还是只有其中一条查不到）。
  • 内容就绪度总览的派生覆盖维不再让 OCR 全文产物参与红黄灯判定：该产物不进任何检索通路，其失败不影响内容可被检索；计数仍如实展示，只是不计入灯档与失败占比。

修复 ​

  • 修复绑定提交在并发重复、或「先解绑后重绑同一目标」等序列下返回系统错误（HTTP 500）而非可读业务提示的问题，覆盖字段绑类型 / 模板绑类型 / 模板绑资源 / 字段直绑资源四条绑定路径：此类请求现返回明确的「已绑定」业务提示并就地复活，不再 500。
  • 修复彻底删除文档 / 容器后，其资源级模板绑定关系未被一并清理、残留为孤儿并永久阻止相关模板删除的问题。
  • 修复文档类型切换预检把资源级绑定（字段直绑、资源级模板绑定）提供的字段误报为「将变遗留」的问题——这些字段锚在文档上、切换后仍然有效。
  • 修复文档类型切换时用目标类型默认值覆写经资源级绑定已持有值的问题：这类字段不再被误报为「新增必填」而阻断切换，切换后其已有值原样保留；确无值的字段按切换后生效配置（资源级绑定覆盖优先）填入正确默认值。
  • 修复单文档就绪度诊断在文档仅靠资源级绑定获得可检索字段时，误报「元数据字段全部不可检索」的问题——该步现按文档实际生效的字段集判定。
  • 修复内容就绪度诊断把健康文档报成故障的一批误报：OCR 全文识别失败而正文抽取与切分正常的文档、全量重派生进行期间产物正在重建但既有检索内容未受影响的文档，均不再被报成断点；结构上不会产出某类产物的文件（压缩包、音视频、图片的文本抽取，以及未开启 OCR 全文能力的 PDF）不再被报成「待派生」。
  • 修复归档文档遮蔽真实断点的问题：归档只让语义检索不可用，此前它会占住结论位、使同一文档上真正的派生失败或索引失败无从暴露；现归档文档若管线健康仍报归档，管线确有故障时结论指向故障本身。归档文档的诊断文案现如实区分「文档级全文检索仍可见」与「切分级混合检索、语义检索均不可见」。
  • 检索能力关闭的部署形态现可正常启动并受理请求，检索相关能力按预期降级。

2026-07-20 ​

新增 ​

  • 新增 AI 就绪度评估：回答「我的内容能不能被 AI 用、不能用的卡在哪」，把此前散落的处理链状态（派生、检索索引、语义检索就绪、OCR 质量、发布状态、类型配置）聚合为一份可自查的体检报告。
    • 就绪度总览端点（GET /v1/readiness/summary）：返回「可被 AI 检索文档数 / 存活文档总数」计数比、统计域分桶（活跃 / 归档 / 回收站 / 未发布 / 已发布），以及五个维度（派生覆盖、检索索引覆盖、OCR 质量、发布与新鲜度、类型配置缺口）的红黄绿灯档、计数器与问题文档样本（每维最多 20 条）；不产出合成总分。支持按容器（直属文档）与按业务类型过滤，两者可组合。
    • 单文档就绪度诊断端点（GET /v1/readiness/documents/{docId}）：按真实处理链顺序对一份文档做九步漏斗检查（存活 → 生命周期 → 已发布 → 新鲜度 → 派生 → 语义检索就绪 → 检索索引 → OCR 质量 → 类型配置），逐步返回通过 / 阻断 / 提示 / 跳过与稳定诊断码，直接回答「为什么 AI 查不到这份文档」。
    • 诊断码为稳定枚举契约（如 NOT_PUBLISHED、DERIVATION_FAILED、NO_INDEX_MEMBER），集成方可按码映射自己的排查文案；派生失败附产物种类与失败原因，语义检索不可用附「全文检索仍可召回」降档说明，归档文档如实标注两条召回路的可见性差异。九步全部无阻断时返回终态提示码 PIPELINE_ALL_CLEAR，表示内容侧管线无异常、用户仍查不到时可明确转向权限方向排查。
    • 类型配置缺口维可识别两类常见配置问题：类型未开启 OCR 全文能力但其下存在 PDF 文档、类型的元数据字段全部未开启可检索。
    • 检索能力关闭的部署形态下，检索索引维、语义检索维及总览就绪率如实呈现「不适用」而非误报故障。
    • 新增只读授权范围 client:content:readiness:read（默认不预授，需在控制台显式授予客户端后方可调用）。就绪度判定阈值（红灯失败占比、OCR 低覆盖两档）支持部署级配置调整。

2026-07-17 ​

新增 ​

  • 新增统一预览地址端点（POST /v1/versions/preview-url）：集成方只需传版本 ID，平台自动判断可预览性并在源文件与预览衍生物之间分流，直接返回可用的内联预览地址（previewable=true 时带 url，并标注地址来自源文件还是预览衍生物）；源与预览衍生物都不支持内联时返回明确的「不可预览」结果并引导改走下载（previewable=false，无签发副作用）。无需集成方自行判断文件类型，也不必在多个签发端点间选路或靠 catch 错误码反推。该端点只签发内联预览地址，下载仍走 POST /v1/versions/signed-url?mode=download。

  • 版本查询 / 列表结果新增源文件可内联预览标识 sourcePreviewable（POST /v1/versions/get、版本列表）：仅按源文件类型判定该版本源文件本身能否内联预览，集成方可在列表页批量筛选，无需逐个探测。含预览衍生物回退的权威分流仍以 POST /v1/versions/preview-url 为准。

  • 文档文本接口新增页级 OCR 覆盖率 coverage（GET /v1/versions/text）：扫描件 / 图片文本的每页在原有页级置信度 confidence 之外，新增 coverage（该页多少文本出自 OCR，0~1，与 confidence 同域）。二者配合可正确解读识别质量——覆盖率极低时该页置信度只代表零星补识字符、不代表整页。

变更 ​

  • 页级状态收窄为结构维度，识别质量分档移交消费方（Breaking）：文档文本接口的页级状态 ocrStatus 现只表结构维度（ok / empty / failed / unprocessed），不再返回质量档判定——识别质量好坏的分界属业务决策，由集成方按 confidence + coverage 两个原始信号自行分档，平台不代拍。

2026-07-11 ​

变更 ​

  • 优化文档（尤其扫描件、图片型 PDF）上传后到可检索 / 可消费的端到端加工延迟：抽取出的纯文本现优先就绪、可更快用于检索与消费，不再被同一文档较慢的 OCR 等后续加工阻塞而延后；各类衍生物的就绪先后顺序也变得稳定可预期，便于集成方编排上传后的状态轮询与下游消费。

2026-07-06 ​

新增 ​

  • 文档文本接口支持结构化 OCR 版面输出（GET /v1/versions/text）：扫描件 / 图片来源的 OCR 结果新增可选的结构化版面明细——携带 includeLayout=true 时逐页返回：正文版面块（正文、标题、列表、图片、表格等各带类型标签与坐标，多栏文档按人眼阅读顺序排列）、块内行 / span 级明细（文本、坐标与识别分数，并区分 OCR 识别来源与数字文本层来源、不冒充识别分数）、表格以 HTML 片段返回（标准 <table> 结构，合并单元格用 colspan / rowspan 承载结构，直接渲染或解析即得表格）；页眉、页脚、页码等非正文内容单列于被弃块、不计入页文本。结果顶层自描述坐标系（原点 / 单位 / 分辨率，PDF 用点坐标、图片用像素坐标）、识别引擎版本与结构版本。可用于按版面切段、坐标高亮、低置信内容降权与表格结构还原。不携带 includeLayout 时响应形态与体积不变。
  • OCR 文本覆盖文档全部物理页：通过文档文本接口获取扫描件 / 图片文本时，结果现覆盖全部页——空白页、识别失败页与超量未处理页均如实出条目，并默认携带页级状态与页级平均识别置信度，页号连续不偏移；识别失败或超时不再被伪装成「正常的空白页」。
  • 扫描件 OCR 输出确定性可复现：同一文件重复调用返回稳定一致的结果（版面块序、行文本、表格 HTML、页级状态均可复现）；识别引擎版本串涵盖影响结果的完整配置指纹，集成方据此可判断结果是否可能变化、是否需重跑比对基线。

变更 ​

  • 文档文本接口对扫描件的「识别失败」与「确无文字」明确区分：识别失败（含超时 / 超量未处理）返回失败状态（FAILED）与失败原因，确无文字返回「不适用」状态（NOT_APPLICABLE），二者不再被误报为可用的空文本；失败与确无内容终态下仅返回状态与原因、不返回页级明细。

2026-07-05 ​

新增 ​

  • 部署授权档位分级功能门控：平台按部署授权档位开放能力——基础档含文档管理；进阶档在此之上增加检索能力（全文检索 / 语义检索 / 检索配置）；完整档包含全部能力。调用当前档位未开放的能力端点时统一以 HTTP 403 拒绝并返回专用错误码 178008（LICENSE_FEATURE_NOT_LICENSED），集成方可据 HTTP 状态与错误码分流、按部署实际档位隐藏或禁用相应入口；授权状态在运行期变化（如到期后自动失效）时即时生效。详见系统 / 功能门错误码 178*。

修复 ​

  • 修复已归档或已移入回收站的文档，其内容片段仍可能出现在语义检索结果与签发内容中的问题：此类文档现已正确排除在语义检索之外，恢复为「活动」状态后重新可被检索。
  • 修复无文字图片（照片 / 图表 / logo）、空白扫描件、纯白 PDF 等「确无内容」文件被误标为处理失败的问题：此类文件现统一标记为「不适用」正常终态，文档文本接口返回确无内容语义；损坏文件与不支持的格式仍照常判为处理失败。

2026-07-04 ​

新增 ​

  • 文档文本与衍生物新增「不适用」终态（NOT_APPLICABLE）：无文本层的扫描件、OCR 识别无文字、正文抽取产出为空等「确无内容」场景有了明确的一等状态表达——不再计入处理失败，也区别于处理中。文档文本接口（GET /v1/versions/text）与衍生物列表（GET /v1/renditions/list）据此返回该状态。

变更 ​

  • 文档文本接口失败原因精确化：真实处理失败（源文件读取失败、解析异常）返回真实失因，确无文本返回「不适用」，二者不再混淆。
  • 优化全文检索与语义检索接口的端到端响应延迟。

修复 ​

  • 修复扫描件 / 图片 PDF 的正文抽取被误报为「无可提取文本」处理失败，以及源文件真实读取失败被伪装成「无可提取文本」、真实故障原因丢失的问题。
  • 修复 OCR 识别无文字时误发「文档文本就绪」事件通知的问题。
  • 对无独立文件的衍生物请求下载 / 直读链接时，返回可读的说明并引导改用文档文本接口获取，不再是含义不明的通用错误。

2026-07-03 ​

修复 ​

  • 修复文件删除后重新上传逐字节相同内容时偶发上传失败的问题，删除过的内容现可正常重新上传。
  • 修复内容相同的重复文档正文抽取偶发失败、导致无法进入全文检索与语义检索的问题。

2026-06-29 ​

新增 ​

  • 客户端上传衍生物（预览件）：集成方上传源文档后，可携源版本上传自产的预览件（如源 Word 对应的 PDF）交平台托管——上传即就绪、无需轮询，且不产生新的文档版本。仅接受可内联渲染的文件类型（PDF / 图片（SVG 除外）/ 纯文本 / 音视频）；对同一源版本重复上传同类预览件以新件覆盖、始终保留一份。当前可由客户端上传的衍生物类型为预览件（PREVIEW），经 POST /v1/renditions/upload 上传。相关校验错误码见衍生物 180*。
  • 取衍生物短时直读链接（POST /v1/renditions/signed-url）：按版本 + 类型签发限时直读 URL，支持 preview（内联）/ download（附件）两种模式，可直接在自有页面 <iframe> / <embed> 内联渲染预览件；链接有效期默认 5 分钟、上限 1 小时。
  • 衍生物列表查询（GET /v1/renditions/list）：列出某源版本下的全部衍生物及其类型、状态、大小、格式与来源（客户端上传 / 平台派生）。
  • 「预览件上传完成」事件通知（rendition.uploaded）：预览件上传成功后推送，集成方可免轮询异步获知预览件就绪、随后取链接渲染。
  • 官方 Java / TypeScript SDK 同步覆盖这批衍生物端点（经 client.actAsToken(...).api(V1RenditionApi) 调用），并补充上述上传 / 直读校验的命名错误码常量。

修复 ​

  • 修复文档移入回收站再恢复后，全文检索与语义检索结果可能丢失的问题：文档在回收站期间其检索内容予以保留，恢复后检索结果立即复原。

2026-06-28 ​

变更 ​

  • Breaking｜建模授权归一：调用建模 / Schema 域接口所需的授权从原「查询内容类型」「读取元数据 Schema」两项独立授权合并为单一「建模 Schema 读」授权，并新增「建模 Schema 写」授权。两项均为高权能力、默认不授予任何 API Client——调用建模读 / 写接口前，需在控制台「客户端管理 → scope 授权」为对应 Client 显式授予。原两项独立授权已退役：此前依赖它们调用内容类型查询 / 元数据 Schema 读取的集成，请改授「建模 Schema 读」。
  • Breaking｜文档文本接口的来源标注取值规范化：文档文本接口（/v1/versions/text）响应中标注文本来源的 source 字段，非 OCR 识别的「文本抽取」来源取值规范为 EXTRACTED（OCR 取值与来源语义均不变）。该接口于 2026-06-27 首次发布；如已对该字段做取值分支判断，请将「文本抽取」分支改用 EXTRACTED。

新增 ​

  • 建模 / Schema 域逐对象 CRUD 开放到 V1：新增对内容类型（含容器类型与文档类型）、字段定义、模板与模板字段编织、受控词表与术语、以及类型-字段 / 类型-模板 / 资源-模板三类绑定的程序化逐对象管理端点（创建 / 更新 / 删除 / 排序，模板与词表另含字段编织、术语批量与排序等）。此前只能在控制台手动建模或走声明式整包同步，现可经 V1 API 程序化逐对象管理。资源-模板绑定会校验调用方对目标文档 / 容器的访问权限。官方 Java / TypeScript SDK 同步覆盖这批端点（经 client.actAsToken(...).api(V1XxxApi) 调用）；相关入参 / 约束校验错误码见元数据 182*、内容类型 183*、模板 184* 错误码参考。调用前提见上「Breaking｜建模授权归一」。
  • ACL 授权条目「来源」标注：ACL 授权条目的响应新增 origin 字段，区分授权的三种来源——MANUAL（手动设置）/ INHERIT（从上层继承）/ POLICY（策略派生），便于在展示或核对授权时区分条目由来。
  • SDK 补 Identity Broker 授权码兑换错误码常量：官方 Java / TypeScript SDK 的错误码常量集合补充授权码兑换可能命中的三个命名常量——授权码失效（BROKER_AUTH_CODE_INVALID）、PKCE 校验失败（BROKER_PKCE_VERIFICATION_FAILED）、回调地址不一致（BROKER_REDIRECT_URI_MISMATCH），可据此对 oauth.exchangeCode 的兑换失败做分支处理；错误码参考同步新增对应条目。

2026-06-27 ​

新增 ​

  • 单点登录（同租户多业务系统免重登）：终端用户通过授权码流登录过某个接入业务系统后，浏览器再发起同一租户下其它业务系统的登录时会跳过登录页、直接完成授权回跳，无需重新输入账密或重走上游 SSO；登录会话带绝对过期与闲置超时治理（长时间不活动后自动失效，活跃使用则滑动续期）。免登仅在同一租户内共享，跨租户仍需重新登录；每个业务系统仍各自获得独立的访问凭证，互不影响。
  • 单点登出：终端用户可主动结束在 ATKONBASE 的登录会话，登出后同一租户下其它接入业务系统再次发起登录时不再免登、须重新认证。登出仅结束登录会话，不影响各业务系统已签发、仍在有效期内的访问凭证；浏览器无有效会话时重复登出也不会报错。
  • 托管登录页白标：可为每个接入业务系统配置授权码流登录页的 logo（外链图片地址）与标题，终端用户看到的是接入业务系统自己的品牌；logo 与标题均为可选，留空时回退平台默认品牌。白标只作用于该业务系统的托管登录页，不影响其它接入方。
  • 托管登录页图形验证码：账密连续输错达阈值后，登录页会要求输入图形验证码方可继续登录，验证码图片可点击刷新更换、一次有效；未达阈值的正常登录无需验证码。验证码错误 / 过期与账号密码错误会给出不同提示，便于区分。
  • 官方 Java / TypeScript SDK 新增 Identity Broker 授权码流接入原语 oauth.buildAuthorizeUrl / oauth.exchangeCode：自动生成授权链接、自动处理 PKCE 与 state 防伪校验、用授权码兑换访问凭证，业务方接入降到两个路由、无需自行拼装授权 URL 与做 CSRF 校验。两套 SDK 接入体验一致；客户端密钥与凭证仅在业务后端使用，不经 SDK 暴露到浏览器。

变更 ​

  • 账密登录新增连续失败保护：同一账号短时间内多次输错密码后，平台会对其登录尝试临时限流，偶发输错与正常登录不受影响，限流随时间自动恢复、不会锁死账号；该保护对授权码流托管登录页与受信委派账密入口一致生效。

2026-06-26 ​

新增 ​

  • 授权码流登录接入（ATKONBASE 作为登录中枢）：引入标准 OAuth2 授权码流——业务系统把终端用户重定向到平台授权入口，平台托管登录页（账密、已配置的上游 SSO 同屏可选）完成认证后带授权码回跳业务系统，业务后端用授权码兑换出平台用户令牌、照常调用接口。业务系统无需自建用户体系，对平台背后对接的上游身份源完全无感。授权码流内置安全约束：强制 PKCE、回调地址精确匹配、授权码一次性消费且分钟级失效。
  • 授权码流回调地址登记：可为每个 API Client 登记一个授权码流回调地址，按精确匹配校验（协议、主机、路径、查询需完全一致，不支持前缀或通配）。一个 Client 对应一个回调落点，多环境 / 多入口请各自登记独立 Client。

2026-06-25 ​

新增 ​

  • OAuth2 上游身份源接入：可配置 OAuth2 协议的上游身份源（授权 / 令牌 / 用户信息端点、客户端凭证、用户字段映射），终端用户经浏览器授权回调即可登录——平台以授权码换取访问令牌后调用身份源的用户信息端点，按配置的字段映射定位稳定身份；首次登录的用户自动写入用户体系，被禁用的用户登录被拒。
  • 上游凭证换取用户访问令牌接口（POST /v1/auth/ssoExchange）：业务系统提交上游登录凭证（钉钉免登 authCode 或 OIDC / OAuth2 浏览器授权码），即可换取代表该用户的访问令牌，并以该令牌调用 V1 接口、由平台按用户身份落地权限；租户由调用方凭据上下文绑定确定，不接受前端传入。配套上游 OAuth2 换令牌链路的错误码已补入错误码参考。
  • 访问令牌续期与登出接口（POST /v1/auth/refresh、POST /v1/auth/logout）：业务系统持续期令牌即可维持长会话；主动登出按令牌精确失效目标用户令牌，不影响调用方自身的凭据登录态。
  • 按版本获取文档文本接口（GET /v1/versions/text）：按版本直取文档文本，数字件与扫描件统一形态返回，响应标注文本来源（OCR 识别 / 文本抽取）；同时给出整篇拼接文本与按页结构，OCR 来源时每页携带页级置信度，支持按页参数取单页文本。文本尚未产出时返回「处理中」可轮询、不返回半成品；产出失败返回「失败」并附原因；该类文件无文本可取（如纯二进制文件、无文本层且未开启 OCR 的 PDF）返回明确的「不适用」状态。
  • 「文档文本就绪」webhook 事件（document.text_ready）：文档文本产出就绪后推送，集成方可免轮询及时获取；仅对真正产出了文本的文档推送，无文本衍生物的文档不会误推。
  • 官方 Java / TypeScript SDK 新增「上游凭证换取用户访问令牌」「访问令牌续期」「登出」及「解析当前用户（资料 / 主部门 / 所属部门 / 角色 / 权限码）」便捷方法，业务系统后端可一行调用完成接入，强 / 弱委派通道调用形态一致。

变更 ​

  • 用户被禁用后，其已签发的访问令牌在调用时即时失效、请求被拒，并返回明确的业务错误而非系统级异常。

2026-06-24 ​

新增 ​

  • 按文档 ID 下载文件接口：只需文档 ID 即可下载文件，无需先查版本列表——默认下载该文档的当前版本，也可指定版本号下载历史版本（指定版本会校验其确属该文档）；支持断点续传，与原有按版本下载的响应行为一致。

变更 ​

  • 扫描件 / 图片的文字识别准确度提升，中文识别更准；进入全文检索、语义检索与文本获取接口的文本质量随之提高。

2026-06-23 ​

修复 ​

  • 修复官方 Java SDK 调用任一返回时间字段的接口时反序列化报错的问题：此前带时间字段（如版本元信息、签名 URL 等）的响应会因时间格式不匹配导致整次调用失败，现可正常解析。
  • 修复使用官方 SDK（Java / TypeScript）提交带过期时间的写请求（如分享授权过期时间）被服务端拒绝的问题，现可正常提交。

变更 ​

  • 官方 Java SDK 的运行环境要求放宽到 JDK 8：仍在 JDK 8 的集成方现可直接引用官方 Java SDK，无需升级 JDK。
  • 官方 SDK 对时间字段的请求与响应统一采用 yyyy-MM-dd HH:mm:ss（不带时区偏移的本地时间）表示，Java 与 TypeScript 两端口径一致；传入 / 读取时间字段时直接使用各端原生时间类型，无需自行格式化或换算时区。

2026-06-22 ​

新增 ​

  • 新增「模型 Schema 声明式导入」接口（POST /v1/schema/import）：可将一份导出的内容建模 Schema（内容类型 / 字段定义 / 词表与术语 / 模板及其字段、绑定关系）整包编程式导入当前租户，适用于环境晋升（dev→prod）、租户 Schema 初始化与复制等场景。导入支持「先预检、后落库」两段式——预检（dryRun=true，默认）只计算不写库，按实体列出将新建 / 更新（并标出变更字段）/ 无变更 / 跳过 / 冲突（并说明原因）的完整计划；确认无误后再以 dryRun=false 正式导入。导入为增量合并、整体生效：只新增与更新、不删除导入文件中未包含的已有定义，且要么全部成功、要么全部不变（不会出现导入到一半的中间态）；存在结构性不兼容（如已有字段的类型 / 基数变更）、引用了不存在的词表 / 字段 / 父类型、或会放松既有访问控制时整体拒绝并指出原因，对同一份文件重复导入不产生多余变更。调用方需获授「导入模型 Schema」权限范围，并以 API 客户端身份调用。导出文件带格式版本标识，导入时据此判断兼容性，不兼容的格式会被整体拒绝。
  • 新增 JSON 元数据字段类型：可创建用于承载不定结构结构化数据（如外部系统原始 payload）的字段，支持写入与原样回读，并受字段级访问控制管控。该类型为受约束的存储型字段——不参与全文检索与条件过滤；非法 JSON 或超过 16KB 大小上限的内容会被拒绝。

2026-06-18 ​

新增 ​

  • 新增文档处理状态查询接口（GET /v1/documents/status）：上传文档后可直接查询指定文档 / 版本的处理状态（处理中 / 已就绪 / 各阶段失败及原因），并获知内容派生与语义检索内容是否已就绪（「可安全发布」信号）、文档当前已发布版是否线上可检索，无需再轮询检索或盲等即可掌握处理进度。

2026-06-17 ​

新增 ​

  • 扫描件与无文本层 PDF 发布后，其文字内容经 OCR 抽取，现可被关键词检索命中与语义检索召回；此前这类文件既无法关键词命中、也无法语义召回。
  • 图片文件（截图，拍照的证件 / 票据 / 合同等）上传后，图中文字经 OCR 进入检索，可被检索命中。

变更 ​

  • 扫描件的关键词检索可用性提前：其正文不再等语义检索内容生成完成，发布后即可凭 OCR 文字被关键词检索命中，语义召回随后补齐。

修复 ​

  • 修复大体量扫描件 / 多页无文本层 PDF 整本 OCR 因处理超时被中断而失败的问题；现这类低吞吐文件的 OCR 可正常完成，其文字内容得以进入关键词与语义检索、被正常召回。
  • 修复在新建租户内发布的首批文档可能长时间停在「未索引」、关键词检索查不到、需管理员手工重建索引才生效的问题；现内容处理完成会自动触发该文档的索引，处理就绪后自动进入全文检索，无需人工干预。

2026-06-16 ​

新增 ​

  • 新增资源级「拒绝（DENY）」授权能力：可在已授权的基础上，对指定主体单独收紧或拒绝其对容器 / 文档的访问，拒绝优先于允许生效，并在全部读取路径一致兑现——关键词检索、语义检索、容器 / 文档列表、权限查询与校验，被拒主体不会从任一通道获得该资源。
  • 新增字段级「拒绝（DENY）」授权能力：可在容器 / 角色已授予某字段读写的基础上，对指定主体单独拒绝其对该字段的访问，把单个字段收紧到低于容器默认；字段级拒绝跨本文档与所有上层容器全局生效，并在字段值读取、列表展示、按字段检索、字段写入各处一致遮蔽。

变更 ​

  • Breaking ACL 授权接口（POST /v1/acl/set、POST /v1/acl/batch-set）的权限掩码字段 permissionMask 更名为 allowMask，语义不变（仍为 ALLOW 位掩码）；并新增可选 denyMask 字段承载上述拒绝位（最终有效权限 = 允许位聚合后扣除拒绝位）。按原字段名读写授权掩码的集成需迁移到 allowMask，官方 SDK 升级到最新版即已对齐。
  • 超过 50MB 的文档统一调整为「仅元数据可检索」：其标题与元数据字段仍可被关键词检索命中，但不再生成全文与语义检索内容。此前部分较大文件存在「能语义检索却无全文」的不一致，现已统一。

修复 ​

  • 上传 → 索引链路的可靠性显著增强：文档上传后，即便服务在处理过程中重启或中断，也会自动接管续做、分钟级自愈，稳定进入全文与语义检索，不再出现「永久无法被检索且无任何提示」的情况；通过 URL 异步拉取摄入的文档若在拉取处理中途中断，也会被自动重新处理，不再卡在「处理中」。
  • 删除 / 取消发布 / 随容器级联删除后的检索一致性增强：这些下线操作随业务变更一同可靠持久化，服务节点中断不再导致已删除或已取消发布的文档继续出现在检索结果中。
  • 对内容收窄访问权限、或调整元数据使其退出检索范围后，旧内容会可靠地从检索结果中清出；若清除遇瞬时故障会自动退避重试、分钟级完成，持久失败时在文档列表 / 详情以索引失败状态标记，便于排查。
  • 并发上传相同内容的文件、或以「登记已有对象」/「预签名直传」方式重复提交相同内容时，不再偶发存储失败或唯一约束冲突报错——重复内容会自动复用平台已有文件。
  • 修复仅指定角色（不填权限掩码）的 ACL 授权静默不生效的问题：此前只指定角色、未填权限掩码的授权不会授予任何权限，现按该角色对应的权限位正确授权，与直接指定掩码的授权口径一致。

2026-06-15 ​

移除 ​

  • Breaking 退役按内容域平铺的回收站分页查询接口（容器 POST /v1/containers/trash/getPage、文档 POST /v1/documents/trash/getPage）。其能力已由统一回收站接口（POST /v1/trash/getRootPage + POST /v1/trash/getBatchDetail）完整覆盖，原调用方改用统一回收站接口即可，列表与批次展开功能不受影响。

修复 ​

  • 修复 Java SDK 因默认 User-Agent 含非 ASCII 字符被底层 HTTP 客户端拒绝、导致所有接口调用直接抛异常失败的问题。现默认 User-Agent 为稳定的 ASCII 标识，无需手动覆盖即可正常发起调用，自定义 User-Agent 的能力保持可用（建议升级到最新 Java SDK）。
  • 修复同一主体（用户 / 角色 / 部门）被多个权限来源（手工授权 + 权限策略）同时命中时，部分授权未能生效、不同来源相互覆盖、最终有效权限与预期不一致的问题。现各来源授权各自独立留存并按权限位叠加，撤销某一来源不影响其它来源，有效权限为各来源之和；对已由权限策略授予访问权的主体发起分享也不再被误判拒绝。

2026-06-14 ​

新增 ​

  • 新增统一回收站查询接口：POST /v1/trash/getRootPage 按「删除批次」聚合分页（容器与文档合并视图，列表项为每次删除的批次根），POST /v1/trash/getBatchDetail 展开某一删除批次内包含的子容器与文档。
  • 官方 SDK（Java / TypeScript）新增一行式快速初始化 withClientCredentials(服务地址, clientId, clientSecret)（服务地址只需填写一次），以及按单次调用指定代授权身份的链式用法 actAsToken(用户令牌)（代表已登录用户）/ actAsSource(来源, 来源ID)（代表外部身份），两者在类型层面无法误同时叠加。

变更 ​

  • 删除容器改为递归级联：删除含子容器或文档的容器时，整棵子树（所有子容器与文档）一次性移入回收站，不再因「容器下存在未删除的子项」而被拒绝（符合文件夹删除直觉）；从回收站恢复也按「删除批次」整批还原同一次删除的整棵子树。删除子树规模超过单次上限时会被拒绝并提示分批删除（错误码 175032）。
  • 官方 SDK 代授权身份从「客户端级配置」改为「按单次调用指定」：同一个客户端实例即可并发代表多个终端用户 / 外部身份调用，共享同一连接与凭据刷新，集成方的服务端代理 / 多租户网关场景不再需要为每个用户单独创建客户端实例。v1 SDK 接口调用同时统一了错误处理——业务错误与 HTTP 错误自动抛出携带真实 HTTP 状态码的异常，可直接通过返回对象取业务数据，无需再手动解包响应。

修复 ​

  • 修复 RAG 检索（POST /v1/rag/retrieve）在遇到瞬时故障时较高概率直接失败的问题：现遇瞬时抖动会自动短暂重试，单次抖动不再直接导致检索不可用。

2026-06-13 ​

新增 ​

  • 新增「RAG 审计型签发」接口组，让「AI 消费了哪些内容」可事后追溯：
    • POST /v1/rag/sign：在按权限召回授权内容的同一次调用里额外拿到一份回执（能力 token、签发标识与有效期），系统同时为每次签发留存一条只增不改的审计记录（谁、何时、基于什么查询、拿到了哪些内容）。召回口径与原有 RAG 检索完全一致（同一套强一致权限过滤、同样的返回内容与定位信息）；原有的纯检索接口（POST /v1/rag/retrieve）保持不变，可继续用作不留档的轻量召回。需显式授予 scope client:rag:sign 后调用。
    • POST /v1/rag/verify：持回执中的能力 token 回查签发事实——是否为本系统签发、是否仍在有效期、签发给哪个用户、当时交付了哪些内容标识（不回正文）。持 token 即可验证，无需代表具体用户、也不限定由签发它的同一客户端调用；适合出站闸口 / 合规系统在喂给 AI 前或事后核对。需 scope client:rag:verify。
    • POST /v1/rag/issuances：按用户主体 + 时间范围分页正查本租户的签发记录（含签发用户、签发时刻、经哪个客户端、基于什么查询、拿到了哪些内容标识与有效期，不回正文），适合合规 / 审计场景按主体追溯「某用户的 AI 消费历史」。仅返回本租户数据；因可枚举消费历史、敏感度较高，使用独立于回执验证的 scope client:rag:issuance。

2026-06-12 ​

新增 ​

  • 文档列表与详情接口新增索引可观测能力：indexStatus 新增「未索引」（NOT_INDEXED）取值（未发布或无可检索内容的文档），并新增 indexFailReason 字段——索引失败时直接返回失败原因摘要（仅失败状态填充），便于集成方排查某文档为何未进入全文检索结果。

2026-06-11 ​

新增 ​

  • 全文检索（POST /v1/search/query）结果条目新增携带命中文档的元数据字段：按调用方身份的字段级权限投影——有字段权限的主体可看到受控字段值，无权限时该值自动隐藏，与详情 / 列表读取的可见性口径一致。

变更 ​

  • Breaking 租户管理员不再默认获得内容下载权限：下载改为需对其主体显式授予下载权限后方可放行。原依赖租户管理员身份直接下载内容的集成，需为相应主体补授下载权限。
  • 安全加固：声明为「可搜索 + 访问受控」的字段，其值不进入全文索引——全文检索不会命中或回显受控字段值，受控字段值的可见性一律由字段级权限决定。

修复 ​

  • 修复用户上传文档后、本人立即检索不到自己刚上传文档的问题：现资源创建者自创建起即持有该资源的完整权限（即便所在容器无显式授权、或仅以较小权限授予本人），可检索命中并管理自己创建的内容。
  • 修复两类导致「已发布文档按正文检索不到」的健壮性问题：上传与系统内已有内容相同的文件时，偶发正文不进入全文检索、内容下载失败（现自动校验并修复）；文档重新建立索引时，正文偶发从检索结果中暂时丢失（现保留原有可检索正文并自动恢复）。
  • 修复文档切换内容类型后，其全文检索结果仍停留在旧类型口径的问题：现切换后该文档的可检索内容自动同步到新类型（含类型编码与元数据）；内容类型的能力声明（如是否进入全文检索、是否受字段级权限管控）调整后，关联文档的检索口径同样自动同步刷新。

2026-06-10 ​

修复 ​

  • 修复 RAG 检索（POST /v1/rag/retrieve）在部分请求下偶发失败或返回空结果的问题，检索可用性显著提升。

2026-06-08 ​

新增 ​

  • 上传 / 新建文档时目标容器改为可选：未指定 containerId 时，文档自动归入当前租户的「默认容器」（首次需要时由系统自动创建并维护），无需先创建或选定容器即可上传。默认容器不可删除 / 改名 / 移动（操作返回错误码 175031 DEFAULT_CONTAINER_PROTECTED），确保上传落点始终稳定可用。
  • 新增系统维护模式的对外契约：平台进入维护窗口期间，除鉴权令牌签发、公开分享访问与健康检查外的 V1 端点统一返回错误码 178004 MAINTENANCE_MODE_ACTIVE（msg 携带维护原因文案），便于集成方识别维护窗口并优雅降级；维护结束后原请求原样重发即可。含义与处理建议见错误码参考。

2026-06-07 ​

修复 ​

  • 修复中文密集长文档的部分内容在 RAG 检索中无法被召回的问题：现长文档可完整参与语义召回。

2026-06-06 ​

新增 ​

  • 新增 RAG 检索接口 POST /v1/rag/retrieve：按查询文本召回调用方有权访问的内容片段（chunk），返回片段正文、定位坐标（span）与源文档 / 版本标识，可回链原文，供集成方构建 RAG（检索增强生成）应用。支持按容器限定检索范围（containerId），并可指定返回条数（topK，默认 10、上限 100）。
  • 新增「RAG 检索」授权范围 client:rag:retrieve：与全文检索独立授权，默认不预授任何客户端，需显式授权后方可调用。
  • 全文检索新增周期性一致性自愈：个别文档的更新如因瞬时故障漏同步、或索引内容与已发布版本出现偏差，后台对账会自动补齐纠正，使检索结果最终与已发布内容保持一致。

变更 ​

  • Breaking 全文检索（关键词 / 混合检索）的结果范围调整为「仅已发布版本」：文档的可检索内容随其发布版本更新；未发布 / 草稿状态、以及无任何可检索正文与元数据的文档不再进入全文检索结果。
  • Breaking 全文检索索引改为最终一致刷新：文档发布、内容 / 元数据 / 权限变更后，其检索可见性在下一次索引同步周期生效，不再保证修改后即时可检索。依赖「写入后立即可检索」的集成需调整预期或在业务侧做短暂重试。

修复 ​

  • 修复已到期但尚未被系统回收的分享在状态查询中仍显示「有效」的问题：现实时返回「已过期」，与分享的真实可用状态一致。

2026-06-02 ​

变更 ​

  • Breaking 字段「敏感等级」（公开 / 内部 / 受限三档）模型下线，收敛为「访问受控」单一开关 + 字段级授权：
    • 字段能力声明中的 FIELD_SENSITIVITY（取值 PUBLIC / INTERNAL / RESTRICTED）已移除，由布尔能力 ACCESS_CONTROLLED（访问受控）取代；读取字段定义与模型 Schema 导出的集成方需改按 ACCESS_CONTROLLED 处理。
    • 原两个敏感字段可见性授权范围 client:storage:metadata:sensitive:internal / client:storage:metadata:sensitive:restricted 同步下线；受控字段值的访问改由客户端「所代表用户」获得的字段级读 / 写授权决定。
    • 迁移采用『默认拒绝』口径：原「内部 / 受限」字段一律转为「访问受控」且默认对所有人不可见，需由管理方对相应主体重新授予字段级读 / 写权限后方可恢复访问；原「公开」字段保持透传、不受影响。
  • 受控字段在详情查看、列表、结构化检索与写入各场景下，一致地按字段级权限管控；对受控字段无查看权限的用户，按该字段值筛选不再命中相关内容，避免经检索结果反推受控字段取值。「访问受控」既可对单个字段声明，也可对内容类型声明（后者使该类型及其子类型下的字段统一受控）。

修复 ​

  • 修复创建内容时携带「必填 + 访问受控」字段值被错误拒绝的问题：现创建者可正常携带受控字段值完成创建（创建容器与上传新建文档两条路径），创建完成后该字段的读写仍按字段级权限管控。
  • 请求体格式错误（字段取值非法、JSON 语法错误等）现返回指明出错字段或位置的可读提示，不再笼统返回「服务器内部错误」，便于调用方区分请求问题与服务端故障。

2026-05-31 ​

新增 ​

  • V1 接口错误码大幅扩充，并同步至 Java / TypeScript SDK 的错误码常量。覆盖文件上传 / 下载（/v1/versions/*）、服务端摄入（/v1/ingest/*）、元数据值读写与列表筛选（/v1/metadata/values/*、资源表单 Schema、字段定义查询、模型 Schema 导出）、内容类型（/v1/contentTypes/*）、文档生命周期（/v1/documents/*）、容器生命周期（/v1/containers/*）、站内分享与分享链接（/v1/share-grants/*、/v1/share-links/*）、内容 ACL（/v1/acl/*）以及资源访问前置校验等链路。集成方可据具体业务 code 区分上传冲突 / 会话状态 / 配额超限 / 元数据校验失败 / 资源状态不允许此操作 / 作用域不足等失败原因，而非笼统错误。各码含义、典型触发条件与处理建议见错误码参考。
  • 新增「V1 ACL 端点需委派用户身份」错误码：调用 /v1/acl/* 时若会话仅有客户端凭证、未下发用户身份（用户 token 或 act-as 委派头），返回明确错误码而非通用错误。
  • 新增「检索入参不足」错误码：调用 /v1/search/query 时 keyword 与 fields 至少需提供其一，否则返回明确错误码。

变更 ​

  • 至此全部 V1 接口的错误响应均携带稳定业务错误码（此前部分场景仅返回通用错误 code=1）。集成方可对全部 V1 接口按响应体 code 做统一识别与处理。注意通用 code=1 兜底分支仍需保留——少数未指定具体错误码的业务异常、参数缺失 / 类型不匹配等仍以 code=1 + msg 返回，集成方不应假设错误码集合封闭，请保留通用兜底分支处理未指定码。

修复 ​

  • 修复通过外部 URL 异步摄入（大文件 / 大小未知场景）建立的文档与版本「创建者」信息缺失的问题：现与同步上传一致，可正确追溯创建者。

2026-05-30 ​

新增 ​

  • TypeScript SDK 新增错误码常量集合 errorCodes，与 Java SDK 同口径对齐。集成方可直接引用具名常量（如 errorCodes.PERMISSION_DENIED）识别和处理 V1 接口错误，无需直接写死数字码。

2026-05-29 ​

新增 ​

  • V1 字段定义查询与模型 Schema 导出接口新增字段敏感性保护：默认未获授权的集成方仅能读到「公开」字段，「内部 / 受限」字段不再返回。新增两个授权 scope client:storage:metadata:sensitive:internal 与 client:storage:metadata:sensitive:restricted，可按客户端单独授予；获授后方可在上述接口中读到对应敏感级别的字段。

变更 ​

  • Breaking V1 字段定义查询与模型 Schema 导出接口的字段结构调整：原先各自独立返回的「是否可搜索 / 是否可筛选 / 敏感等级」三个字段，现统一并入字段的 capabilities（能力声明）对象一并返回；已对接这些字段的集成方需改按 capabilities 结构读取。

2026-05-28 ​

新增 ​

  • 公开分享消费侧错误码纳入对外契约与 SDK 常量：SHARE_LINK_UNAVAILABLE (174001)、SHARE_LINK_QUOTA_EXCEEDED (174008)、PASSWORD_REQUIRED (174009)、PASSWORD_INVALID (174010)、PASSWORD_NOT_REQUIRED (174011)、IP_NOT_ALLOWED (174013)、SHARE_LINK_PATH_INVALID (174014)。集成方消费 /public/s/{tenantCode}/{token}/... 公开分享链路时，可直接用这些错误码（及 Java SDK 中对应常量）识别失败原因；错误码参考的《Share 错误码》同步补齐了各码含义、典型触发条件与处理建议。

变更 ​

  • Breaking 权限不足 / Scope 不足的接口响应统一为 HTTP 200 + 业务错误码（102001 权限不足、102002 Scope 不足），不再以 HTTP 403 区分。集成方应按响应体 code 判定失败原因；原依赖 403 状态码判断权限 / Scope 失败的代码需相应调整。

2026-05-27 ​

新增 ​

  • 新增服务端摄入能力：在客户端直传之外，提供两条由服务端把内容引入系统的入口（适用于迁移、批量灌库与外部系统同步），建立的版本与上传路径共享一致的版本链、权限继承、元数据、配额与 Webhook 治理。
    • POST /v1/ingest/from-url：提交外部 URL 与目标容器 / 文档，服务端拉取内容并建立正式版本。小文件同步返回结果版本；大文件或大小未知时自动转为异步任务，先返回受理回执，完成后通过 document.updated Webhook 通知。
    • POST /v1/ingest/register-object：对已通过预签名直传或带外迁移放入存储的对象，仅登记为正式版本而不重新搬运字节，按存储中对象的真实大小计入配额。
    • GET /v1/ingest/task：查询「从 URL 异步拉取」任务的处理状态，成功时返回结果文档与版本标识，失败时返回失败原因。

修复 ​

  • 修复本地存储部署形态下 POST /v1/versions/signed-url 签发的一次性直读链接无法下载文件的问题：此前消费该链接始终返回签名无效，导致单机 / 本地部署的签名直读链路不可用，现已可在链接有效期内正常取得文件字节。

2026-05-26 ​

新增 ​

  • 新增 V1 端点 POST /v1/versions/presign-upload：客户端声明文件元信息（originalFilename / sizeBytes / mimeType）与上传目标（已有文档传 docId，新建文档传 containerId + title）后，服务端完成鉴权与存储配额预检，返回一个限时的预签名 PUT URL（presignedUrl + expiresAt）；客户端据此将文件字节直接 PUT 至对象存储，适合大附件与高并发上传。响应 mode=presigned 表示已签发直传 URL；当存储后端不支持预签名时返回 mode=fallback，并在 fallbackEndpoint 指明改用既有 /v1/versions/upload，保持单一上传代码路径。PUT 时必须按 signedHeaders 携带与签名一致的请求头（首版为 Content-Type）。
  • 新增 V1 端点 POST /v1/versions/finalize-upload：客户端完成直传后以 presign 返回的 uploadId 回调本端点，服务端校验对象已就位、实测大小与声明一致、配额未超限且具备资源访问权限，通过后才创建新版本并完成版本链衔接、ACL 继承、元数据写入、配额计量与 document.created 事件触发；任一校验失败均拒绝建版。响应结构与 /v1/versions/upload 一致（docId / versionId / versionNo 等）。未在有效期内 finalize 的会话及其残留对象由平台自动回收。
  • 新增 V1 端点 POST /v1/versions/signed-url：以 versionId 请求一个短时直读 URL，服务端鉴权后签发，客户端拿到 url 后直接 GET 即可取得文件字节，无需再经上传 / 下载端点中转。有效期由 expiresInSec 指定，缺省 300 秒、上限 3600 秒。
  • /v1/versions/signed-url 支持 mode=preview：签发的 URL 以 Content-Disposition: inline + 实际 MIME 类型响应，浏览器无需下载即可在新标签页直接渲染图片 / PDF / 纯文本 / 音视频；mode=download 则以 attachment 形态触发下载。预览模式实施 MIME 白名单（image/*、application/pdf、text/plain、audio/*、video/*），出于安全考虑 image/svg+xml 不在白名单内；命中白名单之外的类型时端点返回错误并提示改用 mode=download。

修复 ​

  • 修复 /v1/containers/update 在请求体未携带 containerId 时返回「资源不存在: null」这类误导性信息的问题：现明确返回「请求体必须指定 containerId」（业务码 CONTAINER_ID_REQUIRED），便于客户端识别参数缺失场景。

2026-05-25 ​

新增 ​

  • 新增 /v1/metadata/values/getBatch 批量查询元数据端点：传入单一 resourceType 与一组 resourceId（上限 200），一次返回各资源的元数据值，替代逐资源调用 values/get。逐资源做 READ 鉴权——无权或不存在的资源不出现在结果中（二者不作区分），可读但无值的资源以空值列表返回，按 resourceId 匹配即可。
  • Webhook 事件投递能力正式上线：此前订阅可创建但平台不实际推送，现在业务操作提交后会异步向订阅 URL 投递事件（至少一次送达、失败按指数退避重试），event-types 列出的 8 类事件（document.created / document.updated / document.deleted / document.archived、container.created / container.updated / container.deleted、acl.changed）均已接入真实触发点。投递以明文 JSON 传输、暂不携带签名。
  • Webhook 订阅新增可选的出站投递授权 token（请求字段 deliveryToken）：配置后，平台投递本订阅的事件时以 Authorization: Bearer <token> 请求头携带，供接收端校验推送确实来自本平台。该字段为只写凭据，不在订阅详情、列表或保存响应中回显；保存时显式传值即覆盖、传空字符串即清除、不传则保持原值。

变更 ​

  • /v1/containers/update 改用 containerId 定位目标容器，不再要求传入内部 id（与 get / delete / move 等端点一致），无需再先调 containers/get 取主键后才能更新。
  • /v1/containers/update 明确 metadataColumns 为只读输出字段：更新容器时该字段写时忽略，容器元数据的修改请走 /v1/metadata/values/set。注意 create 仍会写入 metadataColumns，与 update 语义不同。
  • 明确 V1 通道错误约定并纳入接口契约：HTTP 200 不代表业务成功，需校验响应体 code（0 成功 / 1 业务失败）；仅认证失败、权限不足、资源不存在、请求头校验失败与服务端内部错误返回非 2xx，且 401 / 403 / 404 / 500 的错误响应信封已统一为标准 ResponseDTO。约定与各端点错误响应已在契约中显式建模，据此生成的 SDK 可直接消费。
  • 使用委派（act-as）请求头调用 V1 端点时，请求头组合非法现明确返回 HTTP 400 并纳入接口契约：互斥头 X-Atk-User-Token 与 X-Atk-Act-As-Source / X-Atk-Act-As-Source-Id 同时携带返回业务码 INVALID_DELEGATION_HEADERS；X-Atk-Act-As-Source 与 X-Atk-Act-As-Source-Id 未成对携带返回 INCOMPLETE_ACT_AS_HEADERS。
  • /v1/documents/update 不再受理 state 字段：内容状态变更请改用归档 / 删除 / 恢复等专用接口，更新时传入任意状态值将被拒绝（此前字段描述误示可设置 ACTIVE / ARCHIVED，与实际行为不符，现已更正）。

修复 ​

  • 修复 /v1/containers/get 与 /v1/containers/create 返回体中 metadataColumns 恒为空的问题：现返回该容器的全量元数据（含未在列表展示的字段，如颜色），值形态与分页列表一致。
  • 修复某些情况下创建或更新 Webhook 订阅失败、导致 Webhook 功能不可用的问题。
  • 修复仅更新容器名称 / 描述、或切换容器 ACL 继承开关时，订阅方收不到 container.updated 事件推送的问题：现在容器的任意属性更新都会触发一次该事件（容器类型变更的既有推送行为不变）。

2026-05-24 ​

文档 ​

  • 开发者门户「指南」补齐四篇能力模式篇：认证与身份双通道、ACL 与继承、文件上传链路均提供可复制的完整示例；Webhook 页如实说明「订阅可配、投递推送 / 签名 / 重试尚未上线」，提示勿据此对接投递。

2026-05-22 ​

新增 ​

  • V1 通道响应统一携带服务端生成的 X-Request-Id 响应头与响应体 rid 字段，拿到错误响应时可凭该 ID 联系支持团队精确定位单次调用。
  • 模型 Schema 导出响应顶层新增 enumDefinitions 枚举字典，可直接消费各字段合法枚举值列表。
  • 模型 Schema 导出（V1）新增 includeSystem 查询参数：V1 默认仅返回业务可见类型。

变更 ​

  • 文件上传端点（V1 upload 与 uploadChunk）请求契约升级为规范 multipart/form-data：业务字段统一打包进 metadata JSON part，不再以 URL query 承载；长 title 或大 metadata 不再触发 URL 长度限制，用户输入也不再出现在访问日志；据此生成的 SDK 可直接使用。
  • Breaking：字段定义与模板的「适用目标」由 DOCUMENT / CONTAINER / ALL 三值单选改为 DOCUMENT / CONTAINER 多选集合；对应 targetType 字段统一替换为 applicableTargets（数组）。原 ALL 模板继承后等价于同时适用文档与容器，行为与历史一致。
  • 系统类型 code 由 document-root / container-root 改名为 document_root / container_root，与自定义类型命名形态对齐。

2026-05-08 ​

新增 ​

  • V1 版本下载接口（/v1/versions/download）支持 HTTP Range 请求：HTML5 <video> 可任意 seek、PDF.js 可范围加载、超大文件断点续传；响应头新增 Accept-Ranges: bytes。
  • V1 版本接口新增分片上传三端点（initChunkedUpload / uploadChunk / completeChunkedUpload），可在 V1 通道断点续传与并发分片上传大文件。
  • V1 文档 / 容器各新增 4 个批量端点（batchDelete / batchMove / 回收站 batchRestore / batchPurge），单批最多 100 条，支持部分失败语义；统一返回 BatchResultDTO（{ success: [...], failed: [{id, code, msg}] }）。
  • 回收站超期文档 / 容器自动彻底清除（默认 30 天）；支持租户级「回收站保留天数」覆盖；V1 列表返回 purgeAt 倒计时字段；新增 GET /v1/system/getTrashRetention 查询当前生效保留天数。
  • V1 文档列表 DTO 新增 mimeType、originalFilename、currentVersionNo；当前用户接口 DTO 新增 tenantCode、tenantName、displayName；新增 GET /v1/contentTypes/getByCode。

2026-05-07 ​

新增 ​

  • v1 SDK 新增按容器 / 按文档获取实例级表单 Schema 的接口，返回含资源级模板叠加字段、遗留字段与当前值，并标注每个字段来源类型。
  • v1 SDK 新增按容器查祖先链接口（GET /v1/containers/getAncestors），可在容器树 UI 实现「展开到指定节点 / 反显已选目标」。
  • atkonbase-sdk 新增公开分享通路（独立 AtkonbasePublicClient）：覆盖匿名分享链接元信息查询、密码校验、下载 URL 拼接与文件夹浏览（list / buildDownloadUrl），与 V1 client 类型层物理隔离。
  • 公开分享支持「文件夹分享」：可对整个文件夹生成公开链接，外部访问者逐层浏览与按需下载；元信息接口新增 shareKind（FILE / FOLDER）与 rootName。
  • 新增「读取当前租户存储用量」接口（GET /v1/tenants/me/storage，scope client:storage:tenant:read）：默认返回逻辑用量，可选物理用量；返回值带约 5 分钟缓存延迟，应视为采样值。

变更 ​

  • v1 容器子查询接口（GET /v1/containers/getChildren）支持 containerId 留空返回根容器列表，每条新增 hasChildren 字段，作为容器树懒加载起点。

移除 ​

  • Breaking：v1 容器全树查询接口 GET /v1/containers/getTree 下线，统一切到懒加载（getChildren 取子层 + getAncestors 取祖先链）；SDK 方法 containerGetTree 同步移除，旧调用返回 404。

2026-05-06 ​

新增 ​

  • 创建 Webhook 时事件类型由服务端统一校验，传入未支持或已废弃的类型会被拒绝并提示具体值。
  • TypeScript / Java SDK 新增查询 Webhook 事件类型清单的方法（webhookListEventTypes）。
  • 创建文档后会自动为订阅 document.created（或通配 *）的活跃 Webhook 生成投递记录，可在投递列表查看。

修复 ​

  • 修复账密 / SSO / V1 代账密登录及刷新接口返回的登录用户 ID 与展示名为空的问题；SDK 接入方现可稳定取到登录用户标识（纯应用模式 client_credentials 仍按设计不返回这两字段）。

2026-05-05 ​

新增 ​

  • 集成方现可通过 V1 接口为本地账密用户颁发 user token，无需让用户跳转到控制台登录页。

变更 ​

  • V1 SDK（TypeScript / Java）按 17 个业务域拆分为独立 API 类，方法定位更直观；Java SDK 新增 act-as 三 header 透传支持，可调用 V1 强通道接口。

2026-05-03 ​

新增 ​

  • OpenAPI / Swagger UI / SDK codegen 产物标题与描述统一为 ATKONBASE API 品牌名。
  • V1 集成接口的 OpenAPI 文档显式声明三个「代表用户」请求头（强通道用户 Token、弱通道来源 + 来源 ID），SDK codegen 时即可在 V1 端点方法签名上看到对应可选参数，并明确强弱通道互斥与弱通道双头成对规则及错误码。
  • TypeScript SDK 在构造 Client 与每次请求时即时校验互斥 / 成对约束，配置错误立即抛错。

变更 ​

  • TypeScript SDK 鉴权配置由「clientToken / session 双模式」简化为单一 V1 形态：clientToken 必填，按需可选 userToken 或 actAs。

移除 ​

  • Breaking：旧版手写 Java SDK 模块整体下线，老 import 不再可用；后续 Java SDK 由 OpenAPI codegen 路线独立发布并随其提供迁移指南。
  • TypeScript SDK 移除旧的会话令牌鉴权模式与对应类型导出。

2026-05-01 ​

新增 ​

  • API Client 可按 Client 显式启用 / 关闭「允许代表用户调用」（弱通道，请求头主张代表用户身份），默认关闭。
  • V1 集成接口支持以请求头携带「代表用户」身份调用：用户已通过 ATKONBASE 登录时走强通道（用户会话 Token），用户身份由集成方系统侧已认证时走弱通道（来源 + 来源 ID，需 Client 已显式获授权）。
  • 用户角色 / 部门 / 状态变更后，下一次 V1 调用即时反映新权限范围，收回权限不再需要等待 Token 过期。

变更 ​

  • 安全加固：收紧 V1 跨租户调用的身份与权限校验；SSO 登录回调的租户归属处理一并加固。

移除 ​

  • Breaking：V1 集成接口 /v1/auth/token-exchange 端点下线，grant_type=jwt-bearer 协议不再支持；集成方今后仅通过 client_credentials 经 /v1/auth/token 获取 Token。
  • Breaking：Java SDK 移除 asUser() 派生客户端入口与 AssertionProvider 配置项；SDK 仅承载 APP_ONLY 服务间调用，「代表用户」语义改由 V1 请求头双通道承接。

2026-04-30 ​

变更 ​

  • Breaking：V1 用户类响应（/v1/users/me/detail 等）移除 name 字段，用户昵称统一以 nickname 返回。面向不通过官方 SDK 直接对接 V1 的消费方：原依赖 name 的代码需切换为 nickname。

2026-04-29 ​

变更 ​

  • ACL 授权主体从单一「Principal」抽象升级为多态模型（用户 / 角色 / 部门）：授权时分别选择三类主体可分别授权，granteeType 取值为 USER / ROLE / DEPARTMENT。

2026-04-26 ​

新增 ​

  • SSO 单点登录首次登录由系统自动建档：通过 OIDC 协议（CAS / 标准 OIDC IdP）首次登录的用户无需事先在控制台手工同步即可直接登录，系统按 IdP 返回标识自动落库，登录后默认无菜单权限由管理员后续按需绑定（钉钉协议仍要求先经全量同步）。
  • 业务方 V1 接口新增「当前用户自服务」入口（/v1/users/me，6 个端点）：覆盖基本信息、详情（主部门 / 所有部门 / 所有角色 / 权限码并集）、资料更新、改密、部门归属、角色归属；改密接口对外部身份源接管的用户直接拒绝并提示联系来源管理员。
  • 业务方 V1 部门接口补齐祖先链与下级查询端点（/v1/departments/listAncestors、/v1/departments/listDescendants）。

移除 ​

  • Breaking：业务终端用户接入通道（/portal/*）整族下线，相关应用配置入口一并移除；业务用户场景统一通过 V1 接口（含强 / 弱双通道）承接。
  • Breaking：principal 抽象的同步与解析端点整族（/v1/principals 同步 / 解析）下线，统一改用 /v1/users/*、/v1/roles/*、/v1/departments/* 或 /v1/principals/resolve。

2026-04-25 ​

移除 ​

  • Breaking：审计与元数据变更历史能力下线——Console / V1 元数据历史端点移除；SDK 移除审计与元数据历史相关类（PageAuditRequest、GetAuditRequest、AuditEventResult、PageMetadataHistoryRequest、MetadataHistoryResult）。元数据当前值仍可读写，但不再记录历史轨迹。

2026-04-24 ​

新增 ​

  • V1 业务身份 API 新增「用户部门归属」与「用户持有角色」读端点：一次请求拿到某用户的主部门 + 全部归属部门、全部业务角色，无需从部门 / 角色反查。
  • V1 部门 / 角色 API 新增「批量加成员 / 批量移成员」端点：批内任意一条违反「本地部门只接受本地来源用户 / 外部来源部门只接受同源用户」规则会整批回滚。
  • V1 业务用户更新接口扩展「主部门 / 归属部门 / 持有角色」字段，一次请求完成用户归属完整调整（主部门必须出现在归属部门列表内）。

变更 ​

  • 跨来源成员关系写入做后端硬校验：把外部来源用户加入本地部门、或把本地用户加入外部来源部门的请求会被直接拒绝。

2026-04-23 ​

新增 ​

  • 新增 V1 业务身份 API：/v1/users/*、/v1/roles/*、/v1/departments/* 覆盖业务用户 / 角色 / 部门的分页、详情、按部门 / 角色查成员、创建、更新、禁用、设凭据、删除；/v1/principals/resolve 提供按 principal_id 反查业务主体的统一能力。
  • 新增 6 条 client scope：client:identity:{user|role|department}:{read|write}。

变更 ​

  • 外部身份源同步单条失败不再导致整批回滚，按成功 / 失败条数汇报。

移除 ​

  • Breaking：旧 V1 /v1/principals/* 业务 API 路径整族（getPage / get / save / batchSave / update / upsert / relations/* 等）下线，集成方须改用 /v1/users/*、/v1/roles/*、/v1/departments/* 或 /v1/principals/resolve。

2026-04-22 ​

新增 ​

  • 新增「站内分享」：资源所有者可把容器或文档分享给系统内其他用户 / 角色 / 部门，接收方登录后自动获得相应访问权限；支持 VIEW / EDIT 两档预设、过期时间（最长 90 天）、撤销、附言。

2026-04-21 ​

新增 ​

  • 容器支持按容器关闭 ACL 继承，配合新建文档时给创建者自动授全位权限，实现「同一容器内每人只见自己文件」的个人空间场景。

2026-04-20 ​

新增 ​

  • ACL Policy 支持一条规则同时授权给多个主体、匹配多个容器类型，无需重复建规则；自定义授权方式提供 6 个权限位（READ / DOWNLOAD / WRITE / DELETE / SHARE / MANAGE）。

变更 ​

  • ACL Policy 不再需要手工填写「Policy 编码」，由系统自动生成唯一 ID。

移除 ​

  • ACL Policy 的 policyCode 字段从 API 中移除。

2026-04-19 ​

新增 ​

  • 新增外链分享下载：资源管理员可为文档或版本生成带 token 的公开下载链接，支持有效期、访问密码、最大访问次数、IP 白名单；匿名用户凭链接即可下载，无需登录。创建者可查看每条链接的访问记录，管理员可强制撤销。

2026-04-18 ​

新增 ​

  • 新增业务终端用户接入通道（/portal/*）：第三方前端可服务业务用户，支持账密、OIDC 单点登录、钉钉免登三种登录方式，并可访问文档 / 容器 / 版本 / 元数据 / 搜索 / ACL 等核心能力。

注：该通道已于 2026-04-26 整族下线，业务用户场景改由 V1 强 / 弱双通道承接。

2026-04-16 ​

新增 ​

  • API Client 容器访问策略支持「全租户」选项，可一键授权访问当前租户全部容器；容器访问策略提供「禁止访问 / 白名单 / 全租户」三档，默认禁止访问。
  • 内容类型支持「直接字段」：无需创建模板即可给类型挂字段，并可覆盖必填与默认值。

变更 ​

  • 创建容器 / 上传文档时「类型」改为可选，不选择时自动使用默认类型并应用其必填字段。

修复 ​

  • 归档状态的文档可正常取消归档、移入回收站；容器移动接口不再因省略目标父容器参数返回 500。

2026-04-13 ​

新增 ​

  • Java SDK 新增 TRUSTED_DELEGATED 认证模式，支持通过 client.asUser() 代用户调用 API，并提供 AssertionProvider 回调接口自定义 assertion 签名；APP_ONLY 与 TRUSTED_DELEGATED 可在同一客户端内共存。（注：该用法已于 2026-05-01 改由 V1 请求头双通道承接。）

修复 ​

  • 文件上传时多值元数据字段填写单个值、布尔类型字段写入不再校验失败；布尔字段在分页筛选中查询结果正确。

2026-04-12 ​

新增 ​

  • 新增 Deny 类型 ACL Policy（拒绝权限策略）；新增 Policy Dry Run 预览（创建前预估影响资源数量与样本）；新增已有 Policy 更新条件的 Diff 预览。

变更 ​

  • Policy 分页查询支持按授权类型（ALLOW / DENY）筛选；ACL 条目区分手动 / 继承 / Policy 自动生成三类来源。

2026-04-11 ​

新增 ​

  • 创建子容器时自动继承父容器的元数据模板和字段值。

修复 ​

  • 容器反归档此前未检查祖先容器是否已归档，可能导致状态不一致，现已补齐祖先链拦截。

2026-04-10 ​

新增 ​

  • ACL 设置接口支持通过角色名（viewer / editor / manager）设置权限，检查接口支持通过权限名称（READ / WRITE 等）检查；ACL 列表与有效权限响应新增角色标签与 Principal 名称、来源类型。SDK 新增角色常量与强类型权限检查响应。
  • 新增 ACL Policy 引擎：支持创建 / 查询 / 更新 / 删除 / 启停 Policy 规则、声明式权限自动化、存量资源回溯扫描、影响查询，并提供全套 Java SDK 支持。手动设置的权限不受 Policy 自动化影响。
  • 钉钉集成新增角色同步，SSO 登录用户不再需要管理员手工分配角色。

变更 ​

  • 权限拒绝响应从 HTTP 200 + 错误码改为 HTTP 403 + 结构化错误体，错误体包含人类可读消息与机器可读详情；权限码校验失败同样返回 HTTP 403。

2026-04-07 ​

修复 ​

  • 安全加固：收紧敏感（RESTRICTED）元数据字段的写入权限校验。

2026-04-06 ​

新增 ​

  • 新增 V1 搜索接口（TRUSTED_DELEGATED 模式）：支持按标题 / 正文 / 文件名 / 元数据跨字段搜索文档，可按类型、时间范围与自定义元数据字段精确过滤；支持 PDF / Word / Excel / PPT / 纯文本 / HTML 正文检索；搜索结果严格遵循 ACL，用户只能搜到有读权限的文档。
  • 元数据字段敏感性分级：支持 PUBLIC / INTERNAL / RESTRICTED 三级可见性控制，统一覆盖所有元数据读写路径（V1 按敏感级跳过无权字段）。
  • 新增文档类型级版本保留策略（最大版本数、保留天数），系统定时自动清理超出策略的历史版本。

修复 ​

  • 安全加固：收紧 ACL 端点对 APP_ONLY / TRUSTED_DELEGATED 调用方的访问控制。

2026-04-05 ​

新增 ​

  • 新增容器统计 API（GET /v1/containers/stats），返回容器下文档数、子容器数、存储量。
  • 新增批量 ACL 权限查询（POST /v1/acl/batchCheck）；SDK 新增对应请求 / 结果类。
  • 新增元数据变更历史能力（V1 metadata/history/getPage 端点 + SDK MetadataHistoryResult），记录字段值 old/new 快照。（注：该能力已于 2026-04-25 完全下线。）

修复 ​

  • 用户创建的顶层容器可正常删除 / 归档 / 取消归档 / 恢复 / 清除；系统根容器不可执行生命周期操作。

2026-04-04 ​

新增 ​

  • 容器元数据继承（Copy-on-Create）：文档创建时自动继承容器的可继承模板绑定和元数据值。

变更 ​

  • 容器现可绑定 targetType=DOCUMENT 的模板（资源级与类型级同步放宽）。

修复 ​

  • 字段默认值清空（defaultValue=""）未生效的问题；受信委派模式下列表端点补齐容器范围过滤，权限收敛正确。

2026-04-03 ​

变更 ​

  • 创建文档 / 容器时类型处于 DEPRECATED / DISABLED 状态给出区分的错误提示。

修复 ​

  • 多值元数据字段传入纯非法操作符（不含 $add/$remove）时返回「不支持的增量操作符」而非「多值字段必须提供数组」。