rqark-tui 0.9.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. rqark_tui-0.9.7/.gitea/workflows/pypi-hub.yaml +31 -0
  2. rqark_tui-0.9.7/.gitea/workflows/pypi.yaml +32 -0
  3. rqark_tui-0.9.7/.gitignore +177 -0
  4. rqark_tui-0.9.7/.python-version +1 -0
  5. rqark_tui-0.9.7/.vscode/settings.json +37 -0
  6. rqark_tui-0.9.7/AGENTS.md +7 -0
  7. rqark_tui-0.9.7/LICENSE +18 -0
  8. rqark_tui-0.9.7/PKG-INFO +191 -0
  9. rqark_tui-0.9.7/README.md +168 -0
  10. rqark_tui-0.9.7/pyproject.toml +81 -0
  11. rqark_tui-0.9.7/src/rqark_tui/app.py +139 -0
  12. rqark_tui-0.9.7/src/rqark_tui/tui/__init__.py +591 -0
  13. rqark_tui-0.9.7/src/rqark_tui/tui/clipboard.py +35 -0
  14. rqark_tui-0.9.7/src/rqark_tui/tui/commands.py +25 -0
  15. rqark_tui-0.9.7/src/rqark_tui/tui/components/dialog.py +139 -0
  16. rqark_tui-0.9.7/src/rqark_tui/tui/components/file_match.py +233 -0
  17. rqark_tui-0.9.7/src/rqark_tui/tui/components/footer.py +345 -0
  18. rqark_tui-0.9.7/src/rqark_tui/tui/components/header.py +78 -0
  19. rqark_tui-0.9.7/src/rqark_tui/tui/components/main.py +775 -0
  20. rqark_tui-0.9.7/src/rqark_tui/tui/components/popup.py +145 -0
  21. rqark_tui-0.9.7/src/rqark_tui/tui/components/quit_handler.py +110 -0
  22. rqark_tui-0.9.7/src/rqark_tui/tui/components/session.py +190 -0
  23. rqark_tui-0.9.7/src/rqark_tui/tui/event_handler.py +231 -0
  24. rqark_tui-0.9.7/src/rqark_tui/tui/image_attach.py +66 -0
  25. rqark_tui-0.9.7/src/rqark_tui/tui/session.py +59 -0
  26. rqark_tui-0.9.7/tests/test_agents.py +49 -0
  27. rqark_tui-0.9.7/tests/test_chat_input.py +523 -0
  28. rqark_tui-0.9.7/tests/test_clipboard.py +99 -0
  29. rqark_tui-0.9.7/tests/test_commands.py +69 -0
  30. rqark_tui-0.9.7/tests/test_dialog.py +127 -0
  31. rqark_tui-0.9.7/tests/test_event_bridge.py +141 -0
  32. rqark_tui-0.9.7/tests/test_event_handler.py +855 -0
  33. rqark_tui-0.9.7/tests/test_file_match.py +191 -0
  34. rqark_tui-0.9.7/tests/test_image_attach.py +127 -0
  35. rqark_tui-0.9.7/tests/test_message_pane.py +1004 -0
  36. rqark_tui-0.9.7/tests/test_popup.py +191 -0
  37. rqark_tui-0.9.7/tests/test_quit_handler.py +253 -0
  38. rqark_tui-0.9.7/tests/test_restore.py +80 -0
  39. rqark_tui-0.9.7/tests/test_session_tabs.py +231 -0
  40. rqark_tui-0.9.7/tests/test_sessions.py +885 -0
  41. rqark_tui-0.9.7/tests/test_tui.py +641 -0
  42. rqark_tui-0.9.7/uv.lock +1598 -0
@@ -0,0 +1,31 @@
1
+ name: Publish to PyPI Hub
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - 'v*'
7
+ workflow_dispatch:
8
+
9
+ jobs:
10
+ publish:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - name: Checkout code
14
+ uses: actions/checkout@v4
15
+
16
+ - name: Install uv
17
+ uses: astral-sh/setup-uv@v3
18
+ with:
19
+ enable-cache: true
20
+
21
+ - name: Set up Python
22
+ run: uv python install 3.14
23
+
24
+ - name: Build the package
25
+ run: uv build
26
+
27
+ - name: Publish to PyPI
28
+ env:
29
+ UV_PUBLISH_USERNAME: __token__
30
+ UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
31
+ run: uv publish
@@ -0,0 +1,32 @@
1
+ name: Build and Publish with uv
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - 'v*'
7
+ workflow_dispatch:
8
+
9
+ jobs:
10
+ release:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - name: Checkout code
14
+ uses: actions/checkout@v4
15
+
16
+ - name: Install uv
17
+ uses: astral-sh/setup-uv@v3
18
+ with:
19
+ enable-cache: true
20
+
21
+ - name: Set up Python
22
+ run: uv python install 3.14
23
+
24
+ - name: Build the package
25
+ run: uv build
26
+
27
+ - name: Publish to Gitea PyPI
28
+ env:
29
+ UV_PUBLISH_URL: ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/pypi
30
+ UV_PUBLISH_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
31
+ UV_PUBLISH_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
32
+ run: uv publish
@@ -0,0 +1,177 @@
1
+ # ---> Python
2
+ # Byte-compiled / optimized / DLL files
3
+ __pycache__/
4
+ *.py[cod]
5
+ *$py.class
6
+ .rqark
7
+
8
+ # C extensions
9
+ *.so
10
+
11
+ # Distribution / packaging
12
+ .Python
13
+ build/
14
+ develop-eggs/
15
+ dist/
16
+ downloads/
17
+ eggs/
18
+ .eggs/
19
+ lib/
20
+ lib64/
21
+ parts/
22
+ sdist/
23
+ var/
24
+ wheels/
25
+ share/python-wheels/
26
+ *.egg-info/
27
+ .installed.cfg
28
+ *.egg
29
+ MANIFEST
30
+
31
+ # PyInstaller
32
+ # Usually these files are written by a python script from a template
33
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
34
+ *.manifest
35
+ *.spec
36
+
37
+ # Installer logs
38
+ pip-log.txt
39
+ pip-delete-this-directory.txt
40
+
41
+ # Unit test / coverage reports
42
+ htmlcov/
43
+ .tox/
44
+ .nox/
45
+ .coverage
46
+ .coverage.*
47
+ .cache
48
+ nosetests.xml
49
+ coverage.xml
50
+ *.cover
51
+ *.py,cover
52
+ .hypothesis/
53
+ .pytest_cache/
54
+ cover/
55
+
56
+ # Translations
57
+ *.mo
58
+ *.pot
59
+
60
+ # Django stuff:
61
+ *.log
62
+ local_settings.py
63
+ db.sqlite3
64
+ db.sqlite3-journal
65
+
66
+ # Flask stuff:
67
+ instance/
68
+ .webassets-cache
69
+
70
+ # Scrapy stuff:
71
+ .scrapy
72
+
73
+ # Sphinx documentation
74
+ docs/_build/
75
+
76
+ # PyBuilder
77
+ .pybuilder/
78
+ target/
79
+
80
+ # Jupyter Notebook
81
+ .ipynb_checkpoints
82
+
83
+ # IPython
84
+ profile_default/
85
+ ipython_config.py
86
+
87
+ # pyenv
88
+ # For a library or package, you might want to ignore these files since the code is
89
+ # intended to run in multiple environments; otherwise, check them in:
90
+ # .python-version
91
+
92
+ # pipenv
93
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
94
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
95
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
96
+ # install all needed dependencies.
97
+ #Pipfile.lock
98
+
99
+ # UV
100
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
101
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
102
+ # commonly ignored for libraries.
103
+ #uv.lock
104
+
105
+ # poetry
106
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
107
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
108
+ # commonly ignored for libraries.
109
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
110
+ #poetry.lock
111
+
112
+ # pdm
113
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
114
+ #pdm.lock
115
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
116
+ # in version control.
117
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
118
+ .pdm.toml
119
+ .pdm-python
120
+ .pdm-build/
121
+
122
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
123
+ __pypackages__/
124
+
125
+ # Celery stuff
126
+ celerybeat-schedule
127
+ celerybeat.pid
128
+
129
+ # SageMath parsed files
130
+ *.sage.py
131
+
132
+ # Environments
133
+ .env
134
+ .venv
135
+ env/
136
+ venv/
137
+ ENV/
138
+ env.bak/
139
+ venv.bak/
140
+
141
+ # Spyder project settings
142
+ .spyderproject
143
+ .spyproject
144
+
145
+ # Rope project settings
146
+ .ropeproject
147
+
148
+ # mkdocs documentation
149
+ /site
150
+
151
+ # mypy
152
+ .mypy_cache/
153
+ .dmypy.json
154
+ dmypy.json
155
+
156
+ # Pyre type checker
157
+ .pyre/
158
+
159
+ # pytype static type analyzer
160
+ .pytype/
161
+
162
+ # Cython debug symbols
163
+ cython_debug/
164
+
165
+ # PyCharm
166
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
167
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
168
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
169
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
170
+ #.idea/
171
+
172
+ # Ruff stuff:
173
+ .ruff_cache/
174
+
175
+ # PyPI configuration file
176
+ .pypirc
177
+
@@ -0,0 +1 @@
1
+ 3.14
@@ -0,0 +1,37 @@
1
+ {
2
+ /*
3
+ * BASE
4
+ */
5
+ "files.encoding": "utf8",
6
+ "editor.linkedEditing": true, // 使得同時編輯相同變數或符號更容易。
7
+ "editor.bracketPairColorization.enabled": true, // 啟用括號配對著色功能。
8
+ "editor.guides.bracketPairs": true, // 在括號間顯示視覺導引線
9
+ "explorer.compactFolders": false,
10
+ /*
11
+ * GIT
12
+ */
13
+ "git.autofetch": true,
14
+ "git.enableSmartCommit": true,
15
+ "git.confirmSync": false,
16
+ /*
17
+ * PYTHON
18
+ */
19
+ "python.analysis.inlayHints.callArgumentNames": "partial",
20
+ "python.analysis.inlayHints.functionReturnTypes": true,
21
+ "python.analysis.inlayHints.pytestParameters": true,
22
+ "python.analysis.inlayHints.variableTypes": true,
23
+ "python.analysis.autoSearchPaths": true,
24
+ "python.analysis.autoIndent": true,
25
+ "python.analysis.autoFormatStrings": true, // 在字串內輸入“{”時,是否自動加上“f”前綴。
26
+ "python.analysis.completeFunctionParens": true,
27
+ "python.analysis.typeEvaluation.analyzeUnannotatedFunctions": true, // 為函數補全添加括號。
28
+ "python.analysis.typeEvaluation.strictSetInference": true,
29
+ "python.analysis.includeAliasesFromUserFiles": false,
30
+ "python.analysis.typeCheckingMode": "basic",
31
+ "python.analysis.typeEvaluation.strictDictionaryInference": true,
32
+ "python.analysis.typeEvaluation.strictListInference": true,
33
+ /*
34
+ * JUPYTER
35
+ */
36
+ "jupyter.exportWithOutputEnabled": false,
37
+ }
@@ -0,0 +1,7 @@
1
+ # Rules
2
+ - 禁寫註解
3
+ - 運行 `uv run ruff check --fix` + `uv run ty check --fix`(主力)
4
+ - 偶爾行 `uv run pyright` / `uv run mypy` 輔助確認 type safety
5
+
6
+ # 特點
7
+ - app chat 無限 retry 係設計
@@ -0,0 +1,18 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 RedQueenArk
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
6
+ associated documentation files (the "Software"), to deal in the Software without restriction, including
7
+ without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
+ copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
9
+ following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be included in all copies or substantial
12
+ portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
15
+ LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
16
+ EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
17
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
18
+ USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,191 @@
1
+ Metadata-Version: 2.5
2
+ Name: rqark-tui
3
+ Version: 0.9.7
4
+ Summary: Terminal chat client for LLM coding agents, built on Textual
5
+ Project-URL: Homepage, https://github.com/Red-Queen-Ark/rqark-tui
6
+ Project-URL: Repository, https://github.com/Red-Queen-Ark/rqark-tui
7
+ Project-URL: Issues, https://github.com/Red-Queen-Ark/rqark-tui/issues
8
+ Author: RedQueenArk
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agent,chat,llm,textual,tui
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Terminals
17
+ Requires-Python: >=3.14
18
+ Requires-Dist: rqark-app==0.11.8
19
+ Requires-Dist: rqark-core==0.5.0
20
+ Requires-Dist: textual>=8.2.8
21
+ Requires-Dist: wcwidth>=0.8.3
22
+ Description-Content-Type: text/markdown
23
+
24
+ # rqark-tui
25
+
26
+ 基於 [Textual](https://textual.textualize.io/) 的終端聊天客戶端,用於與 LLM 驅動的 coding agent 對話。
27
+
28
+ `rqark-tui` 只是介面層,實際的聊天引擎(provider 管理、session 儲存、串流、重試)由 [`rqark-app`](https://pypi.org/project/rqark-app/) 提供。
29
+
30
+ ## 功能特色
31
+
32
+ - 串流式聊天:reasoning、Markdown 內容、tool call 與 tool result 即時顯示
33
+ - agent 由 `~/.rqark/agents/*.yml` 定義(人格、prompt、工具),首次執行會用內建三個預設(Angel Holiday、Diana、Wednesday)填入該目錄;可在執行中用 `/agents` 切換
34
+ - 預設 agent 記在 `rqark-data-cloud`(每個用戶每個 source 一個):有設定 `cloud.yml` 時開場自動讀回並選中它;改預設請用 `rqark-data-cloud-web-ui` 的 Agent Defaults 頁
35
+ - 每個專案目錄獨立 session:`~/.rqark/dir_caches.json` 記錄專案目錄 → session 對應,在同一專案重開即恢復上次對話
36
+ - 多 provider 設定(依 `priority` 排序),API 連續失敗 3 次自動 failover;`app.chat` 無限重試為設計行為,context 超長時自動摘要壓縮後續跑
37
+ - Thinking 區塊與 tool result 預設收合,可按 `▶` / `▼` 展開
38
+ - `/stop` 中斷時保留已收到的部分內容
39
+ - 滑鼠拖曳選取跨行文字;`Ctrl+C` 複製選取、`Ctrl+A` 全選、每則訊息右上 `[copy]` 按鈕整則複製(同時寫入 app 內部與系統剪貼簿)
40
+ - 多個 session 同時運行:每條 session 有自己的訊息窗、worker 同 transcript,切 tab 即可望返另一條嘅即時進度,互不阻塞
41
+ - Agent plan 以浮動 popup 顯示進度(` ` 待辦 / `>` 進行中 / `x` 完成 / `-` 取消),只顯示目前 session 嘅 plan
42
+ - Subagent 輸出留在所屬 session 內,以 `Agent - <id>` 分塊顯示
43
+ - 新 session 首則訊息送出後背景自動產生標題(標題會顯示在 tab 上)
44
+
45
+ ## 安裝
46
+
47
+ 需要 Python ≥ 3.14。
48
+
49
+ ```bash
50
+ uv tool install rqark-tui
51
+ ```
52
+
53
+ 或加入專案:
54
+
55
+ ```bash
56
+ uv add rqark-tui
57
+ ```
58
+
59
+ pip 亦可:
60
+
61
+ ```bash
62
+ pip install rqark-tui
63
+ ```
64
+
65
+ ## 設定
66
+
67
+ 設定集中在使用者家目錄的 `~/.rqark/`(跨專案共用,不會污染各專案目錄):
68
+
69
+ ```text
70
+ ~/.rqark/
71
+ ├── providers.yml # provider 清單(不存在時自動建立空白範本)
72
+ ├── agents/ # 每個 agent 一個 .yml(不存在時用內建預設填入)
73
+ ├── dir_caches.json # 專案目錄(cwd hash)→ session 對應
74
+ └── sessions/tui/ # 每 session 一個 .jsonl
75
+ ```
76
+
77
+ `dir_caches.json` 以啟動時的所在目錄(cwd hash)為 key,故每個專案各自保留 session。
78
+
79
+ `agents/*.yml` 範例(`name` 用大駝峰類名,tool 名稱見 `rqark-core` 的 `TOOLS` 表;`params` 視 tool 而定):
80
+
81
+ ```yaml
82
+ name: Diana
83
+ description: ''
84
+ prompts:
85
+ - name: RolePrompt
86
+ params:
87
+ agent_name: Diana
88
+ user_name: Sir
89
+ tools:
90
+ - name: Gitea
91
+ params:
92
+ username: diana
93
+ token: '...'
94
+ base_url: https://gitea.example
95
+ - name: WebSearch
96
+ ```
97
+
98
+ 改完 `agents/*.yml` 要重開程式才生效;`/agents` 只會在已載入的 agent 之間切換。因為 YAML 直接存到本機,內含 token 的 agent 檔建議 `chmod 600`(`~/.rqark` 本身不在任何 repo 內)。
99
+
100
+ 預設 agent 不存本機檔案,而是記在 `rqark-data-cloud`,key 為 app 的 source(本程式用 `TUI`,同一套值亦蓋在 session 上)。有設定 `cloud.yml` 時,開場會讀回該 source 的預設 agent 並選中它;本程式**只讀不寫**,改預設請到 `rqark-data-cloud-web-ui` 的 Agent Defaults 頁(或直接用 `PUT /api/agent-defaults/{source}`)。agent 本身被刪或不再公用時,該預設會一併消失,開場就照 `agents/*.yml` 的次序用第一個。
101
+
102
+ `providers.yml` 範例:
103
+
104
+ ```yaml
105
+ - name: inhouse
106
+ model_name: gemma4:e4b-mlx
107
+ api_key: '-'
108
+ api_base: http://127.0.0.1:11434/v1
109
+ priority: 1
110
+
111
+ - model_name: deepseek-v4-flash
112
+ api_key: sk-xxxx
113
+ api_base: https://api.deepseek.com
114
+ priority: 3
115
+ ```
116
+
117
+ 可用欄位:`name`、`model_name`、`api_key`、`api_base`、`priority`(小者優先),以及選擇性的 `reasoning_effort`、`thinking`、`temperature`、`top_p`、`seed`、`frequency_penalty`、`presence_penalty`、`combine`。provider 依 `priority` 升序使用,失敗自動輪替。
118
+
119
+ ## 使用
120
+
121
+ ```bash
122
+ rqark-tui
123
+ ```
124
+
125
+ 在相同專案目錄再次執行,會接返該目錄記住嘅所有對話(每條開一個 tab,最近用過嘅排最前,畫面顯示第一條)。
126
+
127
+ 畫面由上至下:header(agent / model / 標題)、session tab、訊息窗、popup(plan 或選單,需要時才出現)、輸入框。
128
+
129
+ ```text
130
+ <header>
131
+ <session tab> [Session 1] [Session 2] [+]
132
+ <main>
133
+ <popup>
134
+ <footer>
135
+ ```
136
+
137
+ ### 多個 session
138
+
139
+ - 點 `+`(或輸入 `/new`)開一條新 session;每條 session 各自有訊息紀錄、進行中的回應同輸入草稿
140
+ - 切 tab 只換上面嘅訊息窗,背景 session 照樣繼續串流,切返去就見到完整內容
141
+ - 正在回應嘅 session,tab 會變黃色;該 session 未完成前唔可以再送訊息(其他 session 不受影響)
142
+ - `/stop`、`/clear`、`/close` 只作用於目前 session
143
+ - 移除 session 有兩種方法,效果一樣:點 tab 上面嘅 `×`、或輸入 `/close`;兩者都會先彈確認 dialog(`Enter`/`Esc` 取消、`Ctrl+E` 確認、或直接點按鈕)
144
+ - 確認後會終止該 session 進行中嘅回應,再刪除它嘅對話紀錄(之後無法復原);最後一條 session 唔可以關(要清空就用 `/clear`),因為畫面永遠要有一條 session
145
+ - 關掉程式再喺同一目錄開返,之前嘅 session 會逐條還原成 tab;已經刪咗嘅則唔會再還原
146
+
147
+ ### 快捷鍵
148
+
149
+ | 按鍵 | 功能 |
150
+ | --- | --- |
151
+ | `Enter` | 送出訊息 |
152
+ | `Shift+Enter`(或 `Ctrl+Enter`、`Ctrl+J`) | 換行 |
153
+ | `Ctrl+C` | 複製選取範圍(未選取時)/複製訊息面板選取 |
154
+ | `Ctrl+A` | 於訊息面板全選 |
155
+ | `Ctrl+E` | 離開(再次按或 `Enter` 於 Quit 確認) |
156
+ | `Esc` × 3 | 離開(同上,會先跳出確認) |
157
+ | `Tab` / `↑` / `↓` | popup 中移動選項 |
158
+ | `Esc` | 關閉 popup / 取消 |
159
+
160
+ 滑鼠操作:拖曳選取跨行文字、點 `[copy]` 複製整則訊息、點 `▶` / `▼` 展開或收合 thinking/tool result、點 session tab 切換 session、點 `+` 開新 session、點 tab 上嘅 `×` 關閉該 session。
161
+
162
+ > macOS 終端(如 Terminal.app)若吞掉修飾鍵,程式會直接讀取實體鍵盤狀態,確保 `Shift/Ctrl+Enter` 仍可換行。
163
+
164
+ ### 斜線指令
165
+
166
+ 輸入 `/` 會帶出完成清單,`Enter` 立即執行。
167
+
168
+ | 指令 | 功能 |
169
+ | --- | --- |
170
+ | `/clear` | 清除目前對話(刪除 session 檔,保留 tab) |
171
+ | `/close` | 關閉目前 session(確認後刪除 session 檔並收起 tab) |
172
+ | `/compact` | 將目前對話壓縮成一段 summary(壓縮期間顯示 `Compacting…`,之後只帶 summary 同新訊息續聊) |
173
+ | `/new` | 開一條新 session(同點 `+` 一樣) |
174
+ | `/stop` | 停止目前回應(已收到的部分內容會存下) |
175
+ | `/models` | 切換 model(picker 顯示目前可用 provider) |
176
+ | `/agents` | 切換 agent(只影響目前 session;預設 agent 請在 `rqark-data-cloud-web-ui` 改) |
177
+
178
+ 回應進行中會擋下一般訊息(顯示 "Still processing — please wait"),但斜線指令不受限制,`/stop` 即逃生門。
179
+
180
+ ## 開發
181
+
182
+ ```bash
183
+ uv sync
184
+ uv run rqark-tui # 直接執行
185
+ uv run ruff check --fix
186
+ uv run ty check --fix
187
+ uv run pyright # 輔助確認 type safety
188
+ uv run mypy
189
+ ```
190
+
191
+ 規格:Python ≥ 3.14、ruff line-length 240、單引號風格、型別檢查以 `ruff` + `ty` 為主。
@@ -0,0 +1,168 @@
1
+ # rqark-tui
2
+
3
+ 基於 [Textual](https://textual.textualize.io/) 的終端聊天客戶端,用於與 LLM 驅動的 coding agent 對話。
4
+
5
+ `rqark-tui` 只是介面層,實際的聊天引擎(provider 管理、session 儲存、串流、重試)由 [`rqark-app`](https://pypi.org/project/rqark-app/) 提供。
6
+
7
+ ## 功能特色
8
+
9
+ - 串流式聊天:reasoning、Markdown 內容、tool call 與 tool result 即時顯示
10
+ - agent 由 `~/.rqark/agents/*.yml` 定義(人格、prompt、工具),首次執行會用內建三個預設(Angel Holiday、Diana、Wednesday)填入該目錄;可在執行中用 `/agents` 切換
11
+ - 預設 agent 記在 `rqark-data-cloud`(每個用戶每個 source 一個):有設定 `cloud.yml` 時開場自動讀回並選中它;改預設請用 `rqark-data-cloud-web-ui` 的 Agent Defaults 頁
12
+ - 每個專案目錄獨立 session:`~/.rqark/dir_caches.json` 記錄專案目錄 → session 對應,在同一專案重開即恢復上次對話
13
+ - 多 provider 設定(依 `priority` 排序),API 連續失敗 3 次自動 failover;`app.chat` 無限重試為設計行為,context 超長時自動摘要壓縮後續跑
14
+ - Thinking 區塊與 tool result 預設收合,可按 `▶` / `▼` 展開
15
+ - `/stop` 中斷時保留已收到的部分內容
16
+ - 滑鼠拖曳選取跨行文字;`Ctrl+C` 複製選取、`Ctrl+A` 全選、每則訊息右上 `[copy]` 按鈕整則複製(同時寫入 app 內部與系統剪貼簿)
17
+ - 多個 session 同時運行:每條 session 有自己的訊息窗、worker 同 transcript,切 tab 即可望返另一條嘅即時進度,互不阻塞
18
+ - Agent plan 以浮動 popup 顯示進度(` ` 待辦 / `>` 進行中 / `x` 完成 / `-` 取消),只顯示目前 session 嘅 plan
19
+ - Subagent 輸出留在所屬 session 內,以 `Agent - <id>` 分塊顯示
20
+ - 新 session 首則訊息送出後背景自動產生標題(標題會顯示在 tab 上)
21
+
22
+ ## 安裝
23
+
24
+ 需要 Python ≥ 3.14。
25
+
26
+ ```bash
27
+ uv tool install rqark-tui
28
+ ```
29
+
30
+ 或加入專案:
31
+
32
+ ```bash
33
+ uv add rqark-tui
34
+ ```
35
+
36
+ pip 亦可:
37
+
38
+ ```bash
39
+ pip install rqark-tui
40
+ ```
41
+
42
+ ## 設定
43
+
44
+ 設定集中在使用者家目錄的 `~/.rqark/`(跨專案共用,不會污染各專案目錄):
45
+
46
+ ```text
47
+ ~/.rqark/
48
+ ├── providers.yml # provider 清單(不存在時自動建立空白範本)
49
+ ├── agents/ # 每個 agent 一個 .yml(不存在時用內建預設填入)
50
+ ├── dir_caches.json # 專案目錄(cwd hash)→ session 對應
51
+ └── sessions/tui/ # 每 session 一個 .jsonl
52
+ ```
53
+
54
+ `dir_caches.json` 以啟動時的所在目錄(cwd hash)為 key,故每個專案各自保留 session。
55
+
56
+ `agents/*.yml` 範例(`name` 用大駝峰類名,tool 名稱見 `rqark-core` 的 `TOOLS` 表;`params` 視 tool 而定):
57
+
58
+ ```yaml
59
+ name: Diana
60
+ description: ''
61
+ prompts:
62
+ - name: RolePrompt
63
+ params:
64
+ agent_name: Diana
65
+ user_name: Sir
66
+ tools:
67
+ - name: Gitea
68
+ params:
69
+ username: diana
70
+ token: '...'
71
+ base_url: https://gitea.example
72
+ - name: WebSearch
73
+ ```
74
+
75
+ 改完 `agents/*.yml` 要重開程式才生效;`/agents` 只會在已載入的 agent 之間切換。因為 YAML 直接存到本機,內含 token 的 agent 檔建議 `chmod 600`(`~/.rqark` 本身不在任何 repo 內)。
76
+
77
+ 預設 agent 不存本機檔案,而是記在 `rqark-data-cloud`,key 為 app 的 source(本程式用 `TUI`,同一套值亦蓋在 session 上)。有設定 `cloud.yml` 時,開場會讀回該 source 的預設 agent 並選中它;本程式**只讀不寫**,改預設請到 `rqark-data-cloud-web-ui` 的 Agent Defaults 頁(或直接用 `PUT /api/agent-defaults/{source}`)。agent 本身被刪或不再公用時,該預設會一併消失,開場就照 `agents/*.yml` 的次序用第一個。
78
+
79
+ `providers.yml` 範例:
80
+
81
+ ```yaml
82
+ - name: inhouse
83
+ model_name: gemma4:e4b-mlx
84
+ api_key: '-'
85
+ api_base: http://127.0.0.1:11434/v1
86
+ priority: 1
87
+
88
+ - model_name: deepseek-v4-flash
89
+ api_key: sk-xxxx
90
+ api_base: https://api.deepseek.com
91
+ priority: 3
92
+ ```
93
+
94
+ 可用欄位:`name`、`model_name`、`api_key`、`api_base`、`priority`(小者優先),以及選擇性的 `reasoning_effort`、`thinking`、`temperature`、`top_p`、`seed`、`frequency_penalty`、`presence_penalty`、`combine`。provider 依 `priority` 升序使用,失敗自動輪替。
95
+
96
+ ## 使用
97
+
98
+ ```bash
99
+ rqark-tui
100
+ ```
101
+
102
+ 在相同專案目錄再次執行,會接返該目錄記住嘅所有對話(每條開一個 tab,最近用過嘅排最前,畫面顯示第一條)。
103
+
104
+ 畫面由上至下:header(agent / model / 標題)、session tab、訊息窗、popup(plan 或選單,需要時才出現)、輸入框。
105
+
106
+ ```text
107
+ <header>
108
+ <session tab> [Session 1] [Session 2] [+]
109
+ <main>
110
+ <popup>
111
+ <footer>
112
+ ```
113
+
114
+ ### 多個 session
115
+
116
+ - 點 `+`(或輸入 `/new`)開一條新 session;每條 session 各自有訊息紀錄、進行中的回應同輸入草稿
117
+ - 切 tab 只換上面嘅訊息窗,背景 session 照樣繼續串流,切返去就見到完整內容
118
+ - 正在回應嘅 session,tab 會變黃色;該 session 未完成前唔可以再送訊息(其他 session 不受影響)
119
+ - `/stop`、`/clear`、`/close` 只作用於目前 session
120
+ - 移除 session 有兩種方法,效果一樣:點 tab 上面嘅 `×`、或輸入 `/close`;兩者都會先彈確認 dialog(`Enter`/`Esc` 取消、`Ctrl+E` 確認、或直接點按鈕)
121
+ - 確認後會終止該 session 進行中嘅回應,再刪除它嘅對話紀錄(之後無法復原);最後一條 session 唔可以關(要清空就用 `/clear`),因為畫面永遠要有一條 session
122
+ - 關掉程式再喺同一目錄開返,之前嘅 session 會逐條還原成 tab;已經刪咗嘅則唔會再還原
123
+
124
+ ### 快捷鍵
125
+
126
+ | 按鍵 | 功能 |
127
+ | --- | --- |
128
+ | `Enter` | 送出訊息 |
129
+ | `Shift+Enter`(或 `Ctrl+Enter`、`Ctrl+J`) | 換行 |
130
+ | `Ctrl+C` | 複製選取範圍(未選取時)/複製訊息面板選取 |
131
+ | `Ctrl+A` | 於訊息面板全選 |
132
+ | `Ctrl+E` | 離開(再次按或 `Enter` 於 Quit 確認) |
133
+ | `Esc` × 3 | 離開(同上,會先跳出確認) |
134
+ | `Tab` / `↑` / `↓` | popup 中移動選項 |
135
+ | `Esc` | 關閉 popup / 取消 |
136
+
137
+ 滑鼠操作:拖曳選取跨行文字、點 `[copy]` 複製整則訊息、點 `▶` / `▼` 展開或收合 thinking/tool result、點 session tab 切換 session、點 `+` 開新 session、點 tab 上嘅 `×` 關閉該 session。
138
+
139
+ > macOS 終端(如 Terminal.app)若吞掉修飾鍵,程式會直接讀取實體鍵盤狀態,確保 `Shift/Ctrl+Enter` 仍可換行。
140
+
141
+ ### 斜線指令
142
+
143
+ 輸入 `/` 會帶出完成清單,`Enter` 立即執行。
144
+
145
+ | 指令 | 功能 |
146
+ | --- | --- |
147
+ | `/clear` | 清除目前對話(刪除 session 檔,保留 tab) |
148
+ | `/close` | 關閉目前 session(確認後刪除 session 檔並收起 tab) |
149
+ | `/compact` | 將目前對話壓縮成一段 summary(壓縮期間顯示 `Compacting…`,之後只帶 summary 同新訊息續聊) |
150
+ | `/new` | 開一條新 session(同點 `+` 一樣) |
151
+ | `/stop` | 停止目前回應(已收到的部分內容會存下) |
152
+ | `/models` | 切換 model(picker 顯示目前可用 provider) |
153
+ | `/agents` | 切換 agent(只影響目前 session;預設 agent 請在 `rqark-data-cloud-web-ui` 改) |
154
+
155
+ 回應進行中會擋下一般訊息(顯示 "Still processing — please wait"),但斜線指令不受限制,`/stop` 即逃生門。
156
+
157
+ ## 開發
158
+
159
+ ```bash
160
+ uv sync
161
+ uv run rqark-tui # 直接執行
162
+ uv run ruff check --fix
163
+ uv run ty check --fix
164
+ uv run pyright # 輔助確認 type safety
165
+ uv run mypy
166
+ ```
167
+
168
+ 規格:Python ≥ 3.14、ruff line-length 240、單引號風格、型別檢查以 `ruff` + `ty` 為主。