感谢Linux.do社区的支持 https://linux.do/t/topic/1773167
ima-note-cli 是一个基于 Python 的命令行工具，用于通过 IMA OpenAPI 管理个人笔记和知识库。
本项目参考了公开 skill：https://clawhub.ai/iampennyli/ima-skills，并结合仓库内的参考文档实现当前的 IMA CLI。
当前已支持这些能力：
- 检查当前 IMA 凭证是否已配置
- 管理笔记：
- 按标题或正文搜索笔记
- 列出笔记本
- 列出指定笔记本下的笔记
- 按
doc_id读取笔记纯文本内容 - 从 Markdown 新建笔记
- 向已有笔记追加 Markdown 内容
- 管理知识库：
- 搜索知识库列表
- 查看知识库详情
- 浏览知识库内容
- 在知识库内搜索文件/文件夹
- 列出可添加内容的知识库
- 将已有笔记添加到知识库
- 导入 URL 到知识库
- 上传本地文件到知识库
本项目自带两个相关 skill，建议优先从这里开始：
skills/ima-note-cli：用于指导ima-note的安装、验证、凭证配置和常用命令使用skills/ima-note：用于提供 IMA 笔记 OpenAPI 的接口能力说明和字段参考
典型分工：
- 需要安装 CLI、排查
uv tool、验证ima-note auth：用ima-note-cli - 需要理解笔记接口、参数、返回结构和工作流：用
ima-note
如果已经安装了 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 .CLI 会按下面顺序读取凭证：
- 项目根目录的
.env - 进程环境变量
如果两者同时存在，环境变量优先。
如果你是通过 uv tool install 全局安装后在任意目录使用 ima，推荐直接配置系统环境变量，而不是依赖当前目录下的 .env。
以下两个环境变量是必需的：
IMA_OPENAPI_CLIENTID=your_client_id
IMA_OPENAPI_APIKEY=your_api_keyWindows 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_keyWindows 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 ~/.zshrcmacOS / Linux（bash），持久化到 ~/.bashrc：
echo 'export IMA_OPENAPI_CLIENTID="your_client_id"' >> ~/.bashrc
echo 'export IMA_OPENAPI_APIKEY="your_api_key"' >> ~/.bashrc
source ~/.bashrcfish 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 终端里，如果默认编码是 GBK，而搜索结果标题或摘要里包含 emoji 或其他非 GBK 字符，CLI 可能报错：
Error: 'gbk' codec can't encode character ...
从当前版本开始，ima auth 会在 Windows 下检查 PYTHONUTF8 和 PYTHONIOENCODING，如果未正确设置，会直接给出 PowerShell 或 CMD 的修复提示。
推荐按下面顺序处理：
- 先把终端代码页切到
UTF-8 - 再强制 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查看帮助：
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 "产品文档库"运行测试：
uv run python -m unittest discover -s tests -v如果已经安装为可执行命令，也可以直接运行：
ima note search "会议纪要"
ima kb browse --kb-id "kb_xxx"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 # 项目说明、安装方式和使用文档