diff --git a/.gitignore b/.gitignore index f423352..f2f406a 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ __pycache__/ *.json *.html *.txt +/tests # C extensions *.so diff --git a/inkwell.py b/inkwell.py index 047b821..690d263 100644 --- a/inkwell.py +++ b/inkwell.py @@ -23,7 +23,7 @@ import http.client from urllib.parse import urlsplit -__Version__ = 'v1.5 (2024-12-31)' +__Version__ = 'v1.5.1 (2025-01-01)' BASE_PATH = os.path.dirname(os.path.abspath(__file__)) CONFIG_JSON = f"{BASE_PATH}/config.json" HISTORY_JSON = "history.json" #历史文件会自动跟随程序传入的配置文件路径 diff --git a/pic/scr1.png b/pic/scr1.png new file mode 100644 index 0000000..a9968fb Binary files /dev/null and b/pic/scr1.png differ diff --git a/pic/scr2.png b/pic/scr2.png new file mode 100644 index 0000000..f6a8efc Binary files /dev/null and b/pic/scr2.png differ diff --git a/pic/scr3.png b/pic/scr3.png new file mode 100644 index 0000000..f7ec4be Binary files /dev/null and b/pic/scr3.png differ diff --git a/pic/scr4.png b/pic/scr4.png new file mode 100644 index 0000000..86d6d25 Binary files /dev/null and b/pic/scr4.png differ diff --git a/pic/scr5.png b/pic/scr5.png new file mode 100644 index 0000000..8276dda Binary files /dev/null and b/pic/scr5.png differ diff --git a/pic/scr6.png b/pic/scr6.png new file mode 100644 index 0000000..f274889 Binary files /dev/null and b/pic/scr6.png differ diff --git a/readme.md b/readme.md index 8dd021e..61cace3 100644 --- a/readme.md +++ b/readme.md @@ -1,104 +1,117 @@ -# 简介 -Inkwell是一个运行于终端的Ai助手，主要为Kindle设计，也适用于其他系统的终端 -1. Python >= 3.8 -2. 单文件设计，不依赖任何第三方库 -3. 支持openai/google/xai/anthropic/mistral/groq/perplexity/alibaba -4. 支持多个api key自动轮换 -5. 支持多个api服务器自动轮换 -6. 支持在终端显示格式化后的markdown文本 -7. 支持对读书摘要笔记(My Clippings)进行AI总结和提问学习 -8. 支持将会话历史导出为格式良好的电子书或发送至邮件 - - -# 安装 -1. 确保Kindle已经越狱，并且安装了KUAL和 [Python3](https://www.mobileread.com/forums/showthread.php?t=225030) -2. 将inkwell.zip解压到Kindle书籍根目录(/mnt/us) - - -# 配置 -有两种配置方法，任选其一： -1. 在电脑上直接打开inkwell目录下的 `config.json`，填写对应字段，然后拷贝到Kindle -2. 点击KUAL菜单项`Inkwell Setup`，然后根据向导完成配置过程，不明白的步骤直接回车即可 - -## 配置项说明 -* provider: 提供AI服务的公司。`openai/google/xai/anthropic/mistral/groq/perplexity/alibaba` -* model: 每个AI服务提供的Model -* api_key: Api秘钥，可以多个，使用分号分隔 -* api_host: 如果是第三方提供的API服务，可以填写此项，多个地址使用分号分隔 -* display_style: 文本显示模式。`markdown` - 格式化markdown文本；`markdown_table` - 格式化markdown文本和表格；`plaintext` - 显示为纯文本 -* chat_type: API会话模式。`multi_turn` - 正常的多轮对话模式；`single_turn` - 针对一些不支持多轮对话的第三方API服务，程序内使用字符串拼接模拟多轮对话 -* token_limit: 输入上下文token限制，不建议填写太大 -* max_history: 保存的历史会话个数。每个会话里面的轮数不受限 -* prompt: 会话使用的系统prompt名字，default/custom为特殊值，其他为prompts.txt的自定义名字 -* custom_prompt: 如 `prompt="custom"`，则使用此配置 -* smtp_sender: 可选，邮件发送人地址 -* smtp_host: 可选，SMTP服务器地址和端口，比如: `smtp.gmail.com:587` -* smtp_username: 可选，SMTP用户名 -* smtp_password: 可选，SMTP秘钥 - - -# 用法 -1. 不带参数执行，自动使用同一目录下的配置文件 config.json -2. 需要不同的配置可以传入config参数 `python3 Inkwell.py --config path/to/config.json` -3. 如果需要进入程序马上可以选择读书摘要进行AI提问，可以添加命令行参数 `--clippings` -4. 支持发送多行文本，输入一个空行马上启动发送 -5. 任何时候输入 `?` 进入菜单界面，`q` 退出 - - -# 其他功能说明 -## 针对读书摘要进行AI提问 -Inkwell有一个比较方便的功能，在读书过程中碰到不懂的或需要了解更多背景信息的内容，在阅读界面选择对应的内容后，进入Inkwell的`clippings`界面，显示最近的9个摘要（9为最新的），可以将一个或多个摘要文本发送给AI，并且进行多轮提问。 -这是比较重要的功能，所有有多个入口点，任选一个： -1. 启动参数 `--clippings` -2. 主界面输入 `c` -3. 菜单界面输入 `c` - - -## 导出会话 -Inkwell运行于kterm终端，Kterm滚动体验不是很好，如果碰到多轮的长对话，很难查看稍久之前的信息，而且kterm的显示缓冲区也有限，太长的会话就看不到更前面的内容了。 -使用导出功能将会话导出为电子书后，使用Kindle内置阅读器打开，阅读和跳转体验会更好，还可以查词或永久保存。 -可以导出单个或多个会话为一本电子书，示范命令格式如下，每个命令执行完成后，Kindle的书库界面会自动出现对应图书： -``` -e0: 导出当前会话 -e1: 导出第一个历史会话 -e1-3: 导出第一到第三个历史会话 -e1,3-5: 导出第一个，第三个，第四个，第五个历史会话 -``` - - -## 菜单界面的命令简介 -* `数字0`：回到当前会话 -* `数字1及以上`：切换到某个历史会话，然后继续聊天 -* `c`：进入`clippings`界面，选择某个读书摘要或笔记发送给AI并进行提问 -* `d开头`：删除某个或某些历史会话，`d0`, `d1`, `d1-3`, `d1,3-5` -* `e开头`：导出某个或某些历史会话为电子书，`e0`, `e1`, `e1-3`, `e1,3-5` -* `m`：选择其他model，默认为临时，下次启动恢复原先model，如果需要保存到配置文件，在数字后添加一个叹号 -* `n`：新建一个会话 -* `p`：选择其他prompt，可以参考下面的“自定义prompt”章节 -* `q`：退出程序 -* `?`：显示命令帮助 - - -## 自定义prompt -Inkwell支持方便切换prompt -1. 可以在配置时输入 `Custom prompt` -2. 可以手动编辑配置文件，在 `custom_prompt` 区段填写，然后将 `prompt` 修改为 `custom` -3. 在`inkwell.py`同目录下创建文件 `prompts.txt`，可以写入多个prompt，然后在程序内切换，格式为 -``` -prompt name -content line1 -content line2 -... - -prompt name -content line1 -content line2 -... - -... -``` - - -# 其他信息 -AI聊天对键盘要求比较高，如果对默认键盘布局不满意，可以使用作者的 [kterm键盘设计器](https://github.com/cdhigh/kterm_kb_layouter) 来制作自定义的布局。 - +__English__ · [简体中文](readme_zh.md) + +--- + +# Introduction +**Inkwell** is a terminal-based AI assistant primarily designed for Kindle but also compatible with other terminal systems. + +1. **Python >= 3.8** +2. Single-file design, no third-party library dependencies. +3. Displays formatted Markdown text in the terminal. +4. Summarizes and enables interactive Q&A with Kindle **My Clippings** (reading highlights and notes). +5. Exports conversation history as well-formatted eBooks or sends them via email. +6. Supports multiple AI providers: OpenAI, Google, xAI, Anthropic, Mistral, Groq, Perplexity, Alibaba. +7. Automatically switch between multiple API keys. +8. Automatically switch between multiple API servers. + + + +**Screen shots** +![scr1](pic/scr1.png) ![scr2](pic/scr2.png) +![scr3](pic/scr3.png) ![scr4](pic/scr4.png) +![scr5](pic/scr5.png) ![scr6](pic/scr6.png) + + + +# Installation +1. Ensure your Kindle is jailbroken and has **KUAL** and [Python3](https://www.mobileread.com/forums/showthread.php?t=225030) installed. +2. Extract `inkwell.zip` to the Kindle’s root directory (`/mnt/us`). + +# Configuration +There are two ways to configure Inkwell: +1. Open the `config.json` file in the Inkwell directory on your computer, edit the fields, and copy it back to your Kindle. +2. Select `Inkwell Setup` from the **KUAL menu** and follow the wizard. Simply press Enter for any unclear steps. + +### Configuration Options +- **provider**: AI provider. Supported values: `openai/google/xai/anthropic/mistral/groq/perplexity/alibaba`. +- **model**: The model provided by the chosen AI service. +- **api_key**: API keys (multiple keys separated by semicolons). +- **api_host**: Third-party API server addresses (separated by semicolons). +- **display_style**: Text display mode. Options: + - `markdown`: Formatted Markdown text. + - `markdown_table`: Formatted Markdown with table support. + - `plaintext`: Plain text. +- **chat_type**: Chat session mode. + - `multi_turn`: Standard multi-turn conversation. + - `single_turn`: Simulated multi-turn for APIs that don’t support stateful sessions. +- **token_limit**: Context token limit (keep reasonable). +- **max_history**: Maximum number of saved conversation histories (conversation length is unlimited). +- **prompt**: System prompt for conversations. Options: + - `default/custom`: Special values. + - Others refer to names in `prompts.txt`. +- **custom_prompt**: Used when `prompt="custom"`. +- **smtp_sender**: Optional, email sender address. +- **smtp_host**: Optional, SMTP server and port (e.g., `smtp.gmail.com:587`). +- **smtp_username**: Optional, SMTP username. +- **smtp_password**: Optional, SMTP password. + + +# Usage +1. Click the KUAL menu item to enter. There is no need to enable Wi-Fi in advance; the script will automatically turn Wi-Fi on and off when exiting. +2. Clicking a menu item labeled with `Clippings` allows you to immediately select book highlights for AI interaction. +3. Supports sending multiple lines of text. Enter an empty line to trigger sending. +4. Enter `?` at any time to open the menu, and `q` to exit. + + +# Additional Features + +## AI-Assisted Q&A with Reading Highlights +You can send selected reading highlights to the AI for further exploration, gaining deeper insights or understanding. +### Access options: +1. Use the `--clippings` startup argument. +2. Enter `c` in the main interface. +3. Enter `c` in the menu. + +## Exporting Conversations +As **kterm** has limited scrollback and poor long-dialogue handling, Inkwell can export conversations as eBooks for better navigation and readability. Exported eBooks automatically appear in the Kindle library and can be emailed if SMTP settings are configured. + +Example commands: +``` +e0: Export current conversation. +e1: Export the first history conversation. +e1-3: Export conversations 1 to 3. +e1,3-5: Export conversations 1, 3, 4, and 5. +``` + +## Menu Command Overview +- **`0`**: Return to the current conversation. +- **`1` or higher**: Switch to a specific history conversation and continue chatting. +- **`c`**: Open **clippings** for AI-assisted Q&A. +- **`d`**: Delete one or multiple history conversations (e.g., `d0`, `d1-3`). +- **`e`**: Export one or multiple history conversations (e.g., `e0`, `e1-3`). +- **`m`**: Temporarily switch models (add `!` to save to configuration). +- **`n`**: Start a new conversation. +- **`p`**: Switch prompts (refer to custom prompt section). +- **`q`**: Exit. +- **`?`**: Show command help. + +## Custom Prompts +Inkwell supports easy switching between prompts: +1. Enter a custom prompt during configuration. +2. Edit `custom_prompt` in the configuration file and set `prompt` to `custom`. +3. Add prompts to `prompts.txt` in the Inkwell directory. Example format: + ``` + prompt_name + content line1 + content line2 + ... + + another_prompt_name + content line1 + ... + + ``` + +# Additional Information +1. Inkwell runs on **kterm**. Basic kterm operations include two-finger taps for the menu, font scaling, keyboard toggling, and screen rotation. +2. For custom keyboard layouts, use the [kterm keyboard designer](https://github.com/cdhigh/kterm_kb_layouter). diff --git a/readme_zh.md b/readme_zh.md new file mode 100644 index 0000000..0ebd2e3 --- /dev/null +++ b/readme_zh.md @@ -0,0 +1,121 @@ +[English](readme.md) · __简体中文__ + +--- + +# 简介 +**Inkwell**是一个运行于终端的Ai助手，主要为Kindle设计，也适用于其他系统的终端 +1. **Python >= 3.8** +2. 单文件设计，不依赖任何第三方库 +3. 支持在终端显示格式化后的markdown文本 +4. 支持对Kindle读书摘要笔记(My Clippings)进行AI总结和提问学习 +5. 支持将会话历史导出为格式良好的电子书或发送至邮件 +6. 支持openai/google/xai/anthropic/mistral/groq/perplexity/alibaba +7. 支持多个api key自动轮换 +8. 支持多个api服务器自动轮换 + + +**屏幕截图** +![scr1](pic/scr1.png) ![scr2](pic/scr2.png) +![scr3](pic/scr3.png) ![scr4](pic/scr4.png) +![scr5](pic/scr5.png) ![scr6](pic/scr6.png) + + +# 安装 +1. 确保Kindle已经越狱，并且安装了**KUAL**和 [Python3](https://www.mobileread.com/forums/showthread.php?t=225030) +2. 将`inkwell.zip`解压到Kindle书籍根目录(`/mnt/us`) + +# 配置 +有两种配置方法，任选其一： +1. 在电脑上直接打开inkwell目录下的 `config.json`，填写对应字段，然后拷贝到Kindle +2. 点击KUAL菜单项`Inkwell Setup`，然后根据向导完成配置过程，不明白的步骤直接回车即可 + +## 配置项说明 +- **provider**: 提供AI服务的公司。`openai/google/xai/anthropic/mistral/groq/perplexity/alibaba` +- **model**: 每个AI服务提供的Model +- **api_key**: Api秘钥，可以多个，使用分号分隔 +- **api_host**: 如果是第三方提供的API服务，可以填写此项，多个地址使用分号分隔 +- **display_style**: 文本显示模式。 + - `markdown` - 格式化markdown文本； + - `markdown_table` - 格式化markdown文本和表格； + - `plaintext` - 显示为纯文本 +- **chat_type**: API会话模式。 + - `multi_turn` - 正常的多轮对话模式； + - `single_turn` - 针对一些不支持多轮对话的第三方API服务，程序内使用字符串拼接模拟多轮对话 +- **token_limit**: 输入上下文token限制，不建议填写太大 +- **max_history**: 保存的历史会话个数。每个会话里面的轮数不受限 +- **prompt**: 会话使用的系统prompt名字， + - `default/custom`为特殊值； + - 其他为`prompts.txt`的自定义名字 +- **custom_prompt**: 如 `prompt="custom"`，则使用此配置 +- **smtp_sender**: 可选，邮件发送人地址 +- **smtp_host**: 可选，SMTP服务器地址和端口，比如: `smtp.gmail.com:587` +- **smtp_username**: 可选，SMTP用户名 +- **smtp_password**: 可选，SMTP秘钥 + + +# 用法 +1. 点击KUAL对应菜单项进入，不需要提前打开WIFI，脚本会自动开启WIFI，退出时自动关闭WIFI +2. 点击有`Clippings`字样的菜单项会马上可以选择读书摘要进行AI提问 +3. 支持发送多行文本，输入一个空行启动发送 +4. 任何时候输入 `?` 进入菜单界面，`q` 退出 + + +# 其他功能说明 +## 针对读书摘要进行AI提问 +Inkwell有一个比较方便的功能，在读书过程中碰到不懂的或需要了解更多背景信息的内容，在阅读界面选择对应的内容后，进入Inkwell的`clippings`界面，显示最近的9个摘要（9为最新的），可以将一个或多个摘要文本发送给AI，并且进行多轮提问。 +这是比较重要的功能，所有有多个入口点，任选一个： +1. 启动参数 `--clippings` +2. 主界面输入 `c` +3. 菜单界面输入 `c` + + +## 导出会话 +Inkwell运行于kterm终端，Kterm滚动体验不是很好，如果碰到多轮的长对话，很难查看稍久之前的信息，而且kterm的显示缓冲区也有限，太长的会话就看不到更前面的内容了。 +将会话导出为电子书后，使用Kindle内置阅读器打开，阅读和跳转体验会更好，还可以查词或永久保存。 +可以导出单个或多个会话为一本电子书，示范命令格式如下，每个命令执行完成后，Kindle的书库界面会自动出现对应图书： +如果需要，还可以将导出的电子书发送至电子邮箱（需要提前设置配置文件中以 `smtp` 开头的四个配置项） +``` +e0: 导出当前会话 +e1: 导出第一个历史会话 +e1-3: 导出第一到第三个历史会话 +e1,3-5: 导出第一个，第三个，第四个，第五个历史会话 +``` + + +## 菜单界面的命令简介 +* `数字0`：回到当前会话 +* `数字1及以上`：切换到某个历史会话，然后继续聊天 +* `c`：进入`clippings`界面，选择某个读书摘要或笔记发送给AI并进行提问 +* `d开头`：删除某个或某些历史会话，`d0`, `d1`, `d1-3`, `d1,3-5` +* `e开头`：导出某个或某些历史会话为电子书，`e0`, `e1`, `e1-3`, `e1,3-5` +* `m`：选择其他model，默认为临时，下次启动恢复原先model，如果需要保存到配置文件，在数字后添加一个叹号 +* `n`：新建一个会话 +* `p`：选择其他prompt，可以参考下面的“自定义prompt”章节 +* `q`：退出程序 +* `?`：显示命令帮助 + + +## 自定义prompt +Inkwell支持方便切换prompt +1. 可以在配置时输入 `Custom prompt` +2. 可以手动编辑配置文件，在 `custom_prompt` 区段填写，然后将 `prompt` 修改为 `custom` +3. 在`inkwell.py`同目录下创建文件 `prompts.txt`，可以写入多个prompt，然后在程序内切换，格式为 +``` +prompt_name +content line1 +content line2 +... + +another_prompt_name +content line1 +... + +... +``` + + + +# 其他信息 +1. Inkwell运行于kterm上，kterm的基本操作是双指点按弹出菜单，可以缩放字体大小，打开关闭键盘，屏幕旋转等 +2. AI聊天对键盘要求比较高，如果对默认键盘布局不满意，可以使用作者的 [kterm键盘设计器](https://github.com/cdhigh/kterm_kb_layouter) 来制作自定义的布局。 +