1.1 批量工具的三条使用边界（都是实测）

先 dryRun 再写。 ima_upload_dir 必须先以 dryRun: true 看清单：ima 开放接口 没有删除能力，误传只能到客户端手工处理。
duplicatePolicy: 'skip' 让重跑幂等，判重按文件名（check_repeated_names），所以内容更新要换文件名，否则会被判为已存在而跳过。
URL 导入是就地更新：同一 URL 重复导入返回逐字节相同的 media_id、条目数不增加（实测两次导入 13 → 13 条）。这是本插件唯一可用的"刷新"机制，因为接口没有删除；而 add_knowledge（文件上传）没有 upsert，每次上传都是新的永久条目。

3. 安装与配置

3.1 安装（宿主平面一行）

dsh plugin --profile web add C:\Users\\.dsh\plugins\dsh-ima-kb

插件必须放在 $DSH_HOME/plugins/ 之下、仓库之外：本机主仓库只负责 preset，不承载 Cordis 插件。

3.2 配置行

写进 $DSH_HOME/profiles/web/cordis.patch.yml。必须用 insert: 包装 —— 没有它的行是 "按 id 覆盖既有行"，对这个不存在的 id 只会记一条警告然后跳过：

- insert:
    - id: ima-kb
      name: 'dsh-ima-kb'
      config:
        clientIdRef: IMA_OPENAPI_CLIENTID
        apiKeyRef: IMA_OPENAPI_APIKEY
        requestTimeoutMs: 20000
        maxRetries: 2
        searchConcurrency: 4
        maxRows: 25
        skipKnowledgeBaseIds: []
        preferOwned: true
        bulkMaxFiles: 600
        bulkConcurrency: 2

整段替换，不是合并：patch 覆盖的是这一行的整个 config，所以省略任何一个键它都会 静默退回默认值。bulkMaxFiles 是批量工具单次处理的上限（也用于批量查重的文件数）， bulkConcurrency 是批量上传的并发数（也是 ima_import_urls 的并发批次数）。

3.3 凭证

绝不把密钥写进 cordis.yml。 配置里只写引用名，值存在 $DSH_HOME/.credentials.yaml 的 refs: 段：

version: 1
refs:
  IMA_OPENAPI_CLIENTID: 
  IMA_OPENAPI_APIKEY:

该文件由 dsh-credentials-local 用 chokidar 监听，改动会热加载，无需重启。凭证在 https://ima.qq.com/agent-interface 生成（需先登录 ima 账号）。

3.2 配置行

写进 $DSH_HOME/profiles/web/cordis.patch.yml。必须用 insert: 包装 —— 没有它的行是 "按 id 覆盖既有行"，对这个不存在的 id 只会记一条警告然后跳过：

- insert:
    - id: ima-kb
      name: 'dsh-ima-kb'
      config:
        clientIdRef: IMA_OPENAPI_CLIENTID
        apiKeyRef: IMA_OPENAPI_APIKEY
        requestTimeoutMs: 20000
        maxRetries: 2
        searchConcurrency: 4
        maxRows: 25
        skipKnowledgeBaseIds: []
        preferOwned: true
        bulkMaxFiles: 600
        bulkConcurrency: 2

安装

说明文档

1.1 批量工具的三条使用边界（都是实测）

3. 安装与配置

3.1 安装（宿主平面一行）

3.2 配置行

3.3 凭证

3.2 配置行