ima-note-cli

感谢Linux.do社区的支持 https://linux.do/t/topic/1773167 ima-note-cli 是一个基于 Python 的命令行工具，用于通过 IMA OpenAPI 管理个人笔记和知识库。

本项目参考了公开 skill：https://clawhub.ai/iampennyli/ima-skills，并结合仓库内的参考文档实现当前的 IMA CLI。

Features

当前已支持这些能力：

• 检查当前 IMA 凭证是否已配置
• 管理笔记：
  • 按标题或正文搜索笔记
  • 列出笔记本
  • 列出指定笔记本下的笔记
  • 按 doc_id 读取笔记纯文本内容
  • 从 Markdown 新建笔记
  • 向已有笔记追加 Markdown 内容
• 管理知识库：
  • 搜索知识库列表
  • 查看知识库详情
  • 浏览知识库内容
  • 在知识库内搜索文件/文件夹
  • 列出可添加内容的知识库
  • 将已有笔记添加到知识库
  • 导入 URL 到知识库
  • 上传本地文件到知识库

Skills

本项目自带两个相关 skill，建议优先从这里开始：

• skills/ima-note-cli：用于指导 ima-note 的安装、验证、凭证配置和常用命令使用
• skills/ima-note：用于提供 IMA 笔记 OpenAPI 的接口能力说明和字段参考

典型分工：

• 需要安装 CLI、排查 uv tool、验证 ima-note auth：用 ima-note-cli
• 需要理解笔记接口、参数、返回结构和工作流：用 ima-note

Installation

如果已经安装了 uv，可以直接从 GitHub 安装：

uv tool install git+https://github.com/Aimer779/ima-note-cli

安装完成后即可直接使用：

ima --help
ima auth

更新到最新版本：

uv tool install --reinstall git+https://github.com/Aimer779/ima-note-cli

卸载：

uv tool uninstall ima-note-cli

如果你是在本地开发这个项目，推荐使用：

git clone https://github.com/Aimer779/ima-note-cli
cd ima-note-cli
uv venv
uv pip install -e .

如果只想临时运行仓库代码，也可以直接使用 uv run，不强依赖全局安装。

如果你更偏好 pip：

pip install -e .

Credentials Configuration

CLI 会按下面顺序读取凭证：

1. 项目根目录的 .env
2. 进程环境变量

如果两者同时存在，环境变量优先。

如果你是通过 uv tool install 全局安装后在任意目录使用 ima，推荐直接配置系统环境变量，而不是依赖当前目录下的 .env。

Config ways in different OS

以下两个环境变量是必需的：

IMA_OPENAPI_CLIENTID=your_client_id
IMA_OPENAPI_APIKEY=your_api_key

Windows PowerShell，当前会话临时生效：

$env:IMA_OPENAPI_CLIENTID="your_client_id"
$env:IMA_OPENAPI_APIKEY="your_api_key"

Windows PowerShell，持久化到当前用户环境变量：

setx IMA_OPENAPI_CLIENTID "your_client_id"
setx IMA_OPENAPI_APIKEY "your_api_key"

Windows CMD，当前会话临时生效：

set IMA_OPENAPI_CLIENTID=your_client_id
set IMA_OPENAPI_APIKEY=your_api_key

Windows CMD，持久化到当前用户环境变量：

setx IMA_OPENAPI_CLIENTID "your_client_id"
setx IMA_OPENAPI_APIKEY "your_api_key"

macOS / Linux（bash / zsh），当前会话临时生效：

export IMA_OPENAPI_CLIENTID="your_client_id"
export IMA_OPENAPI_APIKEY="your_api_key"

macOS / Linux（zsh），持久化到 ~/.zshrc：

echo 'export IMA_OPENAPI_CLIENTID="your_client_id"' >> ~/.zshrc
echo 'export IMA_OPENAPI_APIKEY="your_api_key"' >> ~/.zshrc
source ~/.zshrc

macOS / Linux（bash），持久化到 ~/.bashrc：

echo 'export IMA_OPENAPI_CLIENTID="your_client_id"' >> ~/.bashrc
echo 'export IMA_OPENAPI_APIKEY="your_api_key"' >> ~/.bashrc
source ~/.bashrc

fish shell，当前会话临时生效：

set -x IMA_OPENAPI_CLIENTID "your_client_id"
set -x IMA_OPENAPI_APIKEY "your_api_key"

fish shell，持久化：

set -Ux IMA_OPENAPI_CLIENTID "your_client_id"
set -Ux IMA_OPENAPI_APIKEY "your_api_key"

验证配置：

ima auth

如果使用 setx，需要重新打开终端后再验证。

Windows terminal encoding

在部分 Windows 终端里，如果默认编码是 GBK，而搜索结果标题或摘要里包含 emoji 或其他非 GBK 字符，CLI 可能报错：

Error: 'gbk' codec can't encode character ...

从当前版本开始，ima auth 会在 Windows 下检查 PYTHONUTF8 和 PYTHONIOENCODING，如果未正确设置，会直接给出 PowerShell 或 CMD 的修复提示。

推荐按下面顺序处理：

1. 先把终端代码页切到 UTF-8
2. 再强制 Python 使用 UTF-8

PowerShell：

chcp 65001
$env:PYTHONUTF8="1"
$env:PYTHONIOENCODING="utf-8"

CMD：

chcp 65001
set PYTHONUTF8=1
set PYTHONIOENCODING=utf-8

然后重新执行命令：

ima note search "coding"

如果你希望持久化生效，可以在 Windows 里执行：

setx PYTHONUTF8 "1"
setx PYTHONIOENCODING "utf-8"

执行 setx 后需要重新打开终端。

必需字段：

IMA_OPENAPI_CLIENTID=your_client_id
IMA_OPENAPI_APIKEY=your_api_key

仓库中包含：

• .env.example：提交到仓库的模板文件
• .env：本地开发占位文件

推荐流程：

cp .env.example .env

然后把 .env 中的占位值替换为你在 https://ima.qq.com/agent-interface 获取到的真实凭证。

示例：

IMA_OPENAPI_CLIENTID=your_client_id
IMA_OPENAPI_APIKEY=your_api_key

Usage

查看帮助：

ima --help

检查凭证配置：

ima auth
ima auth --json

笔记命令：

ima note search "会议纪要"

按正文搜索笔记：

ima note search "项目排期" --search-type content

列出笔记本：

ima note folders
ima note folders --json

列出某个笔记本下的笔记：

ima note list --folder-id "user_list_xxx"
ima note list --folder-id "user_list_xxx" --json

读取指定笔记正文：

ima note get "your_doc_id"

新建笔记：

ima note create --title "测试标题" --content "正文内容"
ima note create --file "./note.md" --folder-id "folder_id"

追加内容到已有笔记：

ima note append "your_doc_id" --content "\n## 补充内容\n\n追加文本"
ima note append "your_doc_id" --file "./append.md"

知识库命令：

ima kb search-base "产品文档库"
ima kb show-base --kb-id "kb_xxx"
ima kb browse --kb-id "kb_xxx"
ima kb search "排期" --kb-id "kb_xxx"
ima kb addable
ima kb add-note --kb-id "kb_xxx" --doc-id "doc_xxx" --title "会议纪要"
ima kb add-url --kb-id "kb_xxx" --url "https://example.com/article"
ima kb add-file --kb-id "kb_xxx" --file "./report.pdf"

如果你是在本地开发，也可以直接运行模块入口：

uv run python -m ima_note_cli note search "会议纪要"
uv run python -m ima_note_cli kb search-base "产品文档库"

Development

运行测试：

uv run python -m unittest discover -s tests -v

如果已经安装为可执行命令，也可以直接运行：

ima note search "会议纪要"
ima kb browse --kb-id "kb_xxx"

Project Structure

ima-note-cli/
├── skills/
│   └── ...
├── src/
│   └── ima_note_cli/
│       ├── __init__.py         # 包初始化与版本导出
│       ├── __main__.py         # 模块入口，支持 `python -m ima_note_cli`
│       ├── api.py              # 兼容导出层
│       ├── cli.py              # 顶层 CLI：`ima auth` / `ima note` / `ima kb`
│       ├── config.py           # `.env` / 环境变量加载与凭证检查
│       ├── http.py             # 共享 HTTP 请求与错误处理
│       ├── notes_api.py        # IMA 笔记 API 客户端与数据模型
│       ├── notes_cli.py        # `ima note ...` 命令实现
│       ├── knowledge_api.py    # IMA 知识库 API 客户端与数据模型
│       ├── knowledge_cli.py    # `ima kb ...` 命令实现
│       └── knowledge_upload.py # 文件预检、COS 签名和上传流程
├── tests/
│   ├── _bootstrap.py           # 为 src 布局测试注入导入路径
│   ├── test_cli.py             # CLI 命令行为与输出回归测试
│   ├── test_config.py          # 配置加载、优先级和缺失场景测试
│   └── test_knowledge_upload.py# 知识库上传预检与签名测试
├── .env                        # 本地开发凭证文件
├── .env.example                # `.env` 模板文件
├── .gitignore                  # Git 忽略规则
├── pyproject.toml              # 项目元数据、构建配置和 CLI 入口定义
├── uv.lock                     # uv 锁文件，固定依赖解析结果
└── README.md                   # 项目说明、安装方式和使用文档