# IMA Markdown 上传 API

用于将用户选中的单篇 Markdown 知识笔记上传到 `daily` knowledge base。

## 凭证

- `IMA_OPENAPI_CLIENTID`
- `IMA_OPENAPI_APIKEY`
- `IMA_DAILY_KNOWLEDGE_BASE_ID`
- `IMA_DAILY_KNOWLEDGE_BASE_NAME`

凭证定位和恢复见 `ima-credential-chain.md`。不要在终端输出完整密钥。

## 上传前检查

- 文件名为 `<完整文章标题>.md`；
- `title` 为完整文章标题，不带 `.md`；
- Markdown 符合 `ima-format-quickref.md`；
- 内容可追溯到当前 Run Artifact；
- 用户已经明确选择该文章；
- 目标知识库已经解析并验证。

## 1. Preflight

调用 IMA Skill 的 `preflight-check.cjs` 检查文件类型、扩展名、大小和 MIME。

预期：

```text
file_ext=md
content_type=text/markdown
media_type=7
```

## 2. Create Media

```text
POST /openapi/wiki/v1/create_media
```

请求核心字段：

```json
{
  "file_name": "<完整文章标题>.md",
  "file_size": 0,
  "content_type": "text/markdown",
  "knowledge_base_id": "<daily-kb-id>",
  "file_ext": "md"
}
```

保存返回的 `media_id` 和 `cos_credential`。COS 临时凭证只在进程内传递，不打印到聊天或日志。

## 3. COS Upload

使用 IMA Skill 提供的 `cos-upload.cjs`，通过参数数组调用并检查：

- 进程 `returncode`；
- `stderr`；
- HTTP 上传结果。

不要拼接包含凭证的 Shell 字符串，也不要把多条 JSON 响应重定向到同一个文件。

## 4. Add Knowledge

```text
POST /openapi/wiki/v1/add_knowledge
```

核心字段：

```json
{
  "media_type": 7,
  "media_id": "<media-id>",
  "title": "<完整文章标题>",
  "knowledge_base_id": "<daily-kb-id>",
  "file_info": {
    "cos_key": "<cos-key>",
    "file_size": 0,
    "file_name": "<完整文章标题>.md"
  }
}
```

## 5. 验证

上传成功不能只依据本地命令退出码。验证目标 knowledge base 中存在对应标题或返回对象，并向用户报告最终结果。

失败时明确报告发生在 Preflight、Create Media、COS Upload 或 Add Knowledge 的哪一步，不改用 URL 导入或 Notes 类型绕过错误。