<div align="center">
<h1 align="center"> Tsugu Beta3 </h1>
<div align="center">
</div>
✨<img src="./logo.jpg" width="100" width="30" height="30" alt="tsugu"/>✨
_⚡️ Python 编写的 [Tsugu](https://github.com/Yamamoto-2/tsugu-bangdream-bot?tab=readme-ov-file) 前端 ----- 第三次迭代的设计产物。⚡️_
</div>
<p align="center">
<a href="https://github.com/Yamamoto-2/tsugu-bangdream-bot">
<img src="https://img.shields.io/badge/tsugubangdream bot - api-yellow" alt="license">
</a>
<a href="https://github.com/kumoSleeping/tsugu-python-frontend?tab=MIT-1-ov-file">
<img src="https://img.shields.io/github/license/kumoSleeping/tsugu-python-frontend" alt="license">
</a>
<a href="https://pypi.org/project/tsugu/">
<img src="https://img.shields.io/pypi/v/tsugu.svg" alt="license">
</a>
</p>
---
## 📜 Introduction
Tsugu-b3是 [Tsugu](https://github.com/Yamamoto-2/tsugu-bangdream-bot?tab=readme-ov-file) 的第一个非官方前端, 自诞生以来致力于用户友好、开发自由.
自QQ官方机器人推出以来, Tsugu-b3 主要为 Tsugu QQ 官方机器人提供支持, 并稳定运行至今.
在未来, Tsugu-b3 依靠高阶函数设计, 也能随时为在各种环境下提供支持。
得益于此设计方式, Tsugu-b3 完全支持命令行下的使用, 为整体前后端的单元测试提供便捷思路.
---
## 📦 Install & Cli-Example
```shell
pip install tsugu
tsugu -h
tsugu 查卡 686
```
API powered by <a href="https://github.com/WindowsSov8forUs/tsugu-api-python?tab=readme-ov-file">tsugu-api-python</a>
Command matching provided by <a href="https://github.com/ArcletProject/Alconna">Alconna</a>
***
## 🛠 Related Projects
- [entari-plugin-tsugu](https://github.com/kumoSleeping/entari-plugin-tsugu)
- [lgr-tsugu-py](https://github.com/kumoSleeping/lgr-tsugu-py)
- [tsugu-bangdream-bot-py](https://github.com/zhaomaoniu/tsugu-bangdream-bot-py) | 已无人维护
## 📜 Feat
- 为改善用户体验，本包与 `koishi 插件` 在部分行为上略有不同。
- 更加详细的帮助信息。
- 默认不需要命令头后跟上完整的空格（可关闭）。
- `绑定玩家` `解除绑定` `刷新验证吗` 等自验证策略。
- 基于 `Alconna` 的真 “可选参数” 。
- 车站相关功能不主动支持绑定账号的配队信息，但被动渲染车站给出的配队信息。
- 参数错误时输出完整的命令帮助信息。
- 略有不同的车站屏蔽词策略。
- 增加 `上传车牌` 命令，但仍然支持自动从文本开头提取车牌。
- `主账号` 和 `解除绑定` 的不同行为。
- 争议功能
- 暂时支持 玩家状态 \<serverName\> 策略
- 暂不支持 shortcut类指令
- 暂不支持 `国服模式` `国服玩家状态` 等指令
- 而应该使用 `主服务器 国服` `玩家状态 国服` 等指令式响应。
- 暂不支持 Tsugu 内部车站互通，只通 `bangdori station` 。
- 为了适应官方 BOT 的特性，本包提供了隐式一些非通用方法。
- 当解除绑定用户数据库返回特定值时会被认定为安全模式，触发直接解除绑定操作。
## 🔧 Development
```shell
pip install -r req
pip install pillow
```
---
## 📚 Async & Higher-Order Function
`cmd_generator` 是一个异步方法，用于直接处理用户输入的自然语言并处理，调用传入的 `send_func` 发送结果
- `message` (str)：用户输入的自然语言
- `user_id` (str)：用户的 `channel_id` 或 `user_id`，当 `platform` 为 `red` 、 `chronocat` 、 `onebot` 时，该值一般为用户 QQ 号
- `platform` (str)：用户的平台（默认值：`red`）
- `send_func`（Awaitable）：期望一个接受 `result` 参数的异步方法，用于发送结果，具体需要实现的方法请参考下方示例
```python
import asyncio
from tsugu import cmd_generator
from loguru import logger
async def _test_send_eg(result):
if isinstance(result, list): [logger.success(item['string']) for item in result if item["type"] == "string"]
asyncio.run(cmd_generator(message='查卡 -h', user_id='114514', platform='satori',send_func=_test_send_eg))
```
## ✏️ Config
通过 **环境变量** 或通过项目下 **`.env`** 文件配置。
```zsh
tsugu -e
```
查看可选的环境变量配置
> 优先级: .env 文件 > 环境变量 > b3 默认 > Tsugu Api Python 默认
Raw data
{
"_id": null,
"home_page": "https://github.com/kumoSleeping/ChatTsuguPy",
"name": "tsugu",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "kumoSleeping",
"author_email": "zjr2992@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/d6/b2/bbc587c365b00581e69795d800ade55042dcf3df1c25001e0244b57a0baa/tsugu-6.4.1.tar.gz",
"platform": null,
"description": "\n\n\n<div align=\"center\">\n\n\n<h1 align=\"center\"> Tsugu Beta3 </h1>\n\n\n<div align=\"center\">\n\n</div>\n\n\u2728<img src=\"./logo.jpg\" width=\"100\" width=\"30\" height=\"30\" alt=\"tsugu\"/>\u2728\n\n\n\n\n_\u26a1\ufe0f Python \u7f16\u5199\u7684 [Tsugu](https://github.com/Yamamoto-2/tsugu-bangdream-bot?tab=readme-ov-file) \u524d\u7aef ----- \u7b2c\u4e09\u6b21\u8fed\u4ee3\u7684\u8bbe\u8ba1\u4ea7\u7269\u3002\u26a1\ufe0f_\n\n\n\n</div>\n\n<p align=\"center\">\n<a href=\"https://github.com/Yamamoto-2/tsugu-bangdream-bot\">\n <img src=\"https://img.shields.io/badge/tsugubangdream bot - api-yellow\" alt=\"license\">\n </a>\n\n<a href=\"https://github.com/kumoSleeping/tsugu-python-frontend?tab=MIT-1-ov-file\">\n <img src=\"https://img.shields.io/github/license/kumoSleeping/tsugu-python-frontend\" alt=\"license\">\n </a>\n<a href=\"https://pypi.org/project/tsugu/\">\n <img src=\"https://img.shields.io/pypi/v/tsugu.svg\" alt=\"license\">\n </a>\n</p>\n\n---\n\n## \ud83d\udcdc Introduction\n\nTsugu-b3\u662f [Tsugu](https://github.com/Yamamoto-2/tsugu-bangdream-bot?tab=readme-ov-file) \u7684\u7b2c\u4e00\u4e2a\u975e\u5b98\u65b9\u524d\u7aef, \u81ea\u8bde\u751f\u4ee5\u6765\u81f4\u529b\u4e8e\u7528\u6237\u53cb\u597d\u3001\u5f00\u53d1\u81ea\u7531.\n\n\u81eaQQ\u5b98\u65b9\u673a\u5668\u4eba\u63a8\u51fa\u4ee5\u6765, Tsugu-b3 \u4e3b\u8981\u4e3a Tsugu QQ \u5b98\u65b9\u673a\u5668\u4eba\u63d0\u4f9b\u652f\u6301, \u5e76\u7a33\u5b9a\u8fd0\u884c\u81f3\u4eca.\n\n\u5728\u672a\u6765, Tsugu-b3 \u4f9d\u9760\u9ad8\u9636\u51fd\u6570\u8bbe\u8ba1, \u4e5f\u80fd\u968f\u65f6\u4e3a\u5728\u5404\u79cd\u73af\u5883\u4e0b\u63d0\u4f9b\u652f\u6301\u3002\n\n\u5f97\u76ca\u4e8e\u6b64\u8bbe\u8ba1\u65b9\u5f0f, Tsugu-b3 \u5b8c\u5168\u652f\u6301\u547d\u4ee4\u884c\u4e0b\u7684\u4f7f\u7528, \u4e3a\u6574\u4f53\u524d\u540e\u7aef\u7684\u5355\u5143\u6d4b\u8bd5\u63d0\u4f9b\u4fbf\u6377\u601d\u8def.\n\n---\n\n## \ud83d\udce6 Install & Cli-Example\n\n```shell\npip install tsugu\ntsugu -h\ntsugu \u67e5\u5361 686\n```\n\nAPI powered by <a href=\"https://github.com/WindowsSov8forUs/tsugu-api-python?tab=readme-ov-file\">tsugu-api-python</a> \nCommand matching provided by <a href=\"https://github.com/ArcletProject/Alconna\">Alconna</a> \n\n***\n\n## \ud83d\udee0 Related Projects\n\n- [entari-plugin-tsugu](https://github.com/kumoSleeping/entari-plugin-tsugu) \n\n- [lgr-tsugu-py](https://github.com/kumoSleeping/lgr-tsugu-py)\n- [tsugu-bangdream-bot-py](https://github.com/zhaomaoniu/tsugu-bangdream-bot-py) | \u5df2\u65e0\u4eba\u7ef4\u62a4\n\n\n## \ud83d\udcdc Feat\n\n- \u4e3a\u6539\u5584\u7528\u6237\u4f53\u9a8c\uff0c\u672c\u5305\u4e0e `koishi \u63d2\u4ef6` \u5728\u90e8\u5206\u884c\u4e3a\u4e0a\u7565\u6709\u4e0d\u540c\u3002\n - \u66f4\u52a0\u8be6\u7ec6\u7684\u5e2e\u52a9\u4fe1\u606f\u3002\n - \u9ed8\u8ba4\u4e0d\u9700\u8981\u547d\u4ee4\u5934\u540e\u8ddf\u4e0a\u5b8c\u6574\u7684\u7a7a\u683c\uff08\u53ef\u5173\u95ed\uff09\u3002\n - `\u7ed1\u5b9a\u73a9\u5bb6` `\u89e3\u9664\u7ed1\u5b9a` `\u5237\u65b0\u9a8c\u8bc1\u5417` \u7b49\u81ea\u9a8c\u8bc1\u7b56\u7565\u3002\n - \u57fa\u4e8e `Alconna` \u7684\u771f \u201c\u53ef\u9009\u53c2\u6570\u201d \u3002\n - \u8f66\u7ad9\u76f8\u5173\u529f\u80fd\u4e0d\u4e3b\u52a8\u652f\u6301\u7ed1\u5b9a\u8d26\u53f7\u7684\u914d\u961f\u4fe1\u606f\uff0c\u4f46\u88ab\u52a8\u6e32\u67d3\u8f66\u7ad9\u7ed9\u51fa\u7684\u914d\u961f\u4fe1\u606f\u3002\n - \u53c2\u6570\u9519\u8bef\u65f6\u8f93\u51fa\u5b8c\u6574\u7684\u547d\u4ee4\u5e2e\u52a9\u4fe1\u606f\u3002\n - \u7565\u6709\u4e0d\u540c\u7684\u8f66\u7ad9\u5c4f\u853d\u8bcd\u7b56\u7565\u3002\n - \u589e\u52a0 `\u4e0a\u4f20\u8f66\u724c` \u547d\u4ee4\uff0c\u4f46\u4ecd\u7136\u652f\u6301\u81ea\u52a8\u4ece\u6587\u672c\u5f00\u5934\u63d0\u53d6\u8f66\u724c\u3002\n - `\u4e3b\u8d26\u53f7` \u548c `\u89e3\u9664\u7ed1\u5b9a` \u7684\u4e0d\u540c\u884c\u4e3a\u3002\n- \u4e89\u8bae\u529f\u80fd\n - \u6682\u65f6\u652f\u6301 \u73a9\u5bb6\u72b6\u6001 \\<serverName\\> \u7b56\u7565\n - \u6682\u4e0d\u652f\u6301 shortcut\u7c7b\u6307\u4ee4\n - \u6682\u4e0d\u652f\u6301 `\u56fd\u670d\u6a21\u5f0f` `\u56fd\u670d\u73a9\u5bb6\u72b6\u6001` \u7b49\u6307\u4ee4\n - \u800c\u5e94\u8be5\u4f7f\u7528 `\u4e3b\u670d\u52a1\u5668 \u56fd\u670d` `\u73a9\u5bb6\u72b6\u6001 \u56fd\u670d` \u7b49\u6307\u4ee4\u5f0f\u54cd\u5e94\u3002\n - \u6682\u4e0d\u652f\u6301 Tsugu \u5185\u90e8\u8f66\u7ad9\u4e92\u901a\uff0c\u53ea\u901a `bangdori station` \u3002\n- \u4e3a\u4e86\u9002\u5e94\u5b98\u65b9 BOT \u7684\u7279\u6027\uff0c\u672c\u5305\u63d0\u4f9b\u4e86\u9690\u5f0f\u4e00\u4e9b\u975e\u901a\u7528\u65b9\u6cd5\u3002\n - \u5f53\u89e3\u9664\u7ed1\u5b9a\u7528\u6237\u6570\u636e\u5e93\u8fd4\u56de\u7279\u5b9a\u503c\u65f6\u4f1a\u88ab\u8ba4\u5b9a\u4e3a\u5b89\u5168\u6a21\u5f0f\uff0c\u89e6\u53d1\u76f4\u63a5\u89e3\u9664\u7ed1\u5b9a\u64cd\u4f5c\u3002\n\n## \ud83d\udd27 Development\n\n```shell\npip install -r req\npip install pillow\n```\n\n---\n\n## \ud83d\udcda Async & Higher-Order Function\n`cmd_generator` \u662f\u4e00\u4e2a\u5f02\u6b65\u65b9\u6cd5\uff0c\u7528\u4e8e\u76f4\u63a5\u5904\u7406\u7528\u6237\u8f93\u5165\u7684\u81ea\u7136\u8bed\u8a00\u5e76\u5904\u7406\uff0c\u8c03\u7528\u4f20\u5165\u7684 `send_func` \u53d1\u9001\u7ed3\u679c\n- `message` (str)\uff1a\u7528\u6237\u8f93\u5165\u7684\u81ea\u7136\u8bed\u8a00\n- `user_id` (str)\uff1a\u7528\u6237\u7684 `channel_id` \u6216 `user_id`\uff0c\u5f53 `platform` \u4e3a `red` \u3001 `chronocat` \u3001 `onebot` \u65f6\uff0c\u8be5\u503c\u4e00\u822c\u4e3a\u7528\u6237 QQ \u53f7\n- `platform` (str)\uff1a\u7528\u6237\u7684\u5e73\u53f0\uff08\u9ed8\u8ba4\u503c\uff1a`red`\uff09\n- `send_func`\uff08Awaitable\uff09\uff1a\u671f\u671b\u4e00\u4e2a\u63a5\u53d7 `result` \u53c2\u6570\u7684\u5f02\u6b65\u65b9\u6cd5\uff0c\u7528\u4e8e\u53d1\u9001\u7ed3\u679c\uff0c\u5177\u4f53\u9700\u8981\u5b9e\u73b0\u7684\u65b9\u6cd5\u8bf7\u53c2\u8003\u4e0b\u65b9\u793a\u4f8b\n\n\n```python\nimport asyncio\nfrom tsugu import cmd_generator\nfrom loguru import logger\n\nasync def _test_send_eg(result):\n if isinstance(result, list): [logger.success(item['string']) for item in result if item[\"type\"] == \"string\"]\n\nasyncio.run(cmd_generator(message='\u67e5\u5361 -h', user_id='114514', platform='satori',send_func=_test_send_eg))\n\n\n```\n\n## \u270f\ufe0f Config\n\n\u901a\u8fc7 **\u73af\u5883\u53d8\u91cf** \u6216\u901a\u8fc7\u9879\u76ee\u4e0b **`.env`** \u6587\u4ef6\u914d\u7f6e\u3002\n\n```zsh\ntsugu -e\n```\n\u67e5\u770b\u53ef\u9009\u7684\u73af\u5883\u53d8\u91cf\u914d\u7f6e\n> \u4f18\u5148\u7ea7: .env \u6587\u4ef6 > \u73af\u5883\u53d8\u91cf > b3 \u9ed8\u8ba4 > Tsugu Api Python \u9ed8\u8ba4\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tsugu Python Frontend",
"version": "6.4.1",
"project_urls": {
"Homepage": "https://github.com/kumoSleeping/ChatTsuguPy"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c597462bdd82c4eb00cdf29906408365f3a0b1019c1c0755982a8e58827b0600",
"md5": "cae58d9ba7689d05714f9eaf12e8abc0",
"sha256": "ac161f3c1bba29244af55e2e173e2a11cedeecbb6cb2af1b2ee0639fd14b239e"
},
"downloads": -1,
"filename": "tsugu-6.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cae58d9ba7689d05714f9eaf12e8abc0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19988,
"upload_time": "2025-09-07T01:56:28",
"upload_time_iso_8601": "2025-09-07T01:56:28.036495Z",
"url": "https://files.pythonhosted.org/packages/c5/97/462bdd82c4eb00cdf29906408365f3a0b1019c1c0755982a8e58827b0600/tsugu-6.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d6b2bbc587c365b00581e69795d800ade55042dcf3df1c25001e0244b57a0baa",
"md5": "7a2c56adbdfd2ea78fb8ae17eb254014",
"sha256": "f11087d141693ba1bce4853e4bccfef9dd3b41adde0f8b27b28d23625cb215b8"
},
"downloads": -1,
"filename": "tsugu-6.4.1.tar.gz",
"has_sig": false,
"md5_digest": "7a2c56adbdfd2ea78fb8ae17eb254014",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20776,
"upload_time": "2025-09-07T01:56:29",
"upload_time_iso_8601": "2025-09-07T01:56:29.296337Z",
"url": "https://files.pythonhosted.org/packages/d6/b2/bbc587c365b00581e69795d800ade55042dcf3df1c25001e0244b57a0baa/tsugu-6.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 01:56:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kumoSleeping",
"github_project": "ChatTsuguPy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tsugu"
}
JSON
