# IMA Markdown 文件上传流程（media_type=7）

## 什么时候用此流程

当用户说"沉淀到 IMA"时，必须用此文件上传流程，而不是 URL 导入或笔记导入。

## 完整流程

### 1. 写 .md 文件

```bash
mkdir -p /tmp/ima_upload
cat > /tmp/ima_upload/文章标题.md << 'EOF'
# 文章标题

> 来源：XXX

## 摘要

...

## 核心亮点

- ...

[原文链接](url)
EOF
```

### 2. preflight 检查

```python
pf = subprocess.run(
    ["node", f"{SKILL_DIR}/knowledge-base/scripts/preflight-check.cjs",
     "--file", filepath],
    capture_output=True, text=True
)
meta = json.loads(pf.stdout)
# meta = {pass, file_name, file_ext, file_size, media_type, content_type}
```

### 3. create_media（获取 COS 凭证）

```python
r = ima_api("openapi/wiki/v1/create_media", {
    "file_name": fname,
    "file_size": meta["file_size"],
    "content_type": meta["content_type"],
    "knowledge_base_id": kb_id,
    "file_ext": meta["file_ext"]
})
cos = r["data"]["cos_credential"]
media_id = r["data"]["media_id"]
```

### 4. COS 上传

```python
cu = subprocess.run([
    "node", f"{SKILL_DIR}/knowledge-base/scripts/cos-upload.cjs",
    "--file", filepath,
    "--secret-id", cos["secret_id"],
    "--secret-key", cos["secret_key"],
    "--token", cos["token"],
    "--bucket", cos["bucket_name"],
    "--region", cos["region"],
    "--cos-key", cos["cos_key"],
    "--content-type", meta["content_type"],
    "--start-time", str(cos["start_time"]),
    "--expired-time", str(cos["expired_time"]),
    "--timeout", "300000"
], capture_output=True, text=True, timeout=30)
# 非0退出 = 上传失败
```

### 5. add_knowledge

```python
r = ima_api("openapi/wiki/v1/add_knowledge", {
    "media_type": 7,
    "media_id": media_id,
    "title": title,  # 文章中文标题
    "knowledge_base_id": kb_id,
    "file_info": {
        "cos_key": cos["cos_key"],
        "file_size": meta["file_size"],
        "file_name": fname
    }
})
```

## 注意事项

- **COS 凭证不能通过 terminal() 读取**（Hermes redact_secrets 会把 token 替换成 `***`）。必须用 Python `subprocess.run()` 捕获原始 stdout。
- **create_media 的 content_type 不能带 charset 参数**（如 `text/markdown; charset=utf-8` 会被拒）。用纯 MIME 类型 `text/markdown`。
- **文件命名 = `<文章中文标题>.md`**。不要用英文 slug 或 temp name。
- **media_type=7** 是 Markdown 文件。**绝对不要用 media_type=11**（笔记）或 `import_urls`。