Skip to content

Latest commit

 

History

History
242 lines (181 loc) · 9.28 KB

README_en.md

File metadata and controls

242 lines (181 loc) · 9.28 KB

A Python toolkit integrating LLM chat, Feishu/Lark bots, DNS management, SSL certificates, and more.

Installation

pip install chattool --upgrade
pip install "chattool[lark]"  # installs ChatLark; use chatlark for Feishu/Lark bot helpers
pip install "chattool[setup]"  # installs ChatUp; use chatup workspace/hermes/cc-connect

Minimum supported Python version: 3.10.

Features

1. Environment Management (chatenv)

Centralized configuration with automatic secret masking and hidden input for sensitive fields.

# Interactive init (sensitive fields hidden automatically)
chatenv init -i

# Init only specific service config
chatenv init -i -t openai
chatenv init -i -t feishu

# View config (secrets auto-masked)
chatenv cat

# Filter by type
chatenv cat -t feishu

# Set / get individual values
chatenv set OPENAI_API_KEY=sk-xxx
chatenv get OPENAI_API_KEY

# Profile management
chatenv save work && chatenv use work

2. Chat (chattool.Chat)

OpenAI-compatible chat objects with multi-turn dialogue, batch processing, async concurrency, and streaming.

from chattool import Chat

# Multi-turn dialogue
chat = Chat("Hello!")
resp = chat.get_response()
chat.user("How are you?")
chat.get_response()
chat.save("chat.json", mode="w")

# Async concurrency
import asyncio
base = Chat().system("You are a helpful assistant")
tasks = [base.copy().user(f"Topic {i}").async_get_response() for i in range(5)]
responses = asyncio.run(asyncio.gather(*tasks))

# Streaming
async for chunk in Chat().user("Write a poem").async_get_response_stream():
    if chunk.delta_content:
        print(chunk.delta_content, end="", flush=True)

3. Feishu/Lark Bot (moved to ChatLark)

Feishu/Lark bot helpers have moved out of ChatTool into the standalone ChatLark package. Use the first-level chatlark CLI. Model-calling commands are intentionally not wired back through ChatTool.

pip install "chattool[lark]"
chatlark send USER_ID "Hello"
chatlark send "Hello"                  # Uses FEISHU_DEFAULT_RECEIVER_ID
chatlark send -t chat_id "Hello team" # Uses FEISHU_DEFAULT_CHAT_ID
chatlark info
chatlark serve echo
chatlark serve webhook
from chatlark import LarkBot

bot = LarkBot()
bot.send_text("ou_xxx", "open_id", "Hello!")

@bot.on_message
def handle(ctx):
    ctx.reply(f"Received: {ctx.text}")

bot.start()

4. DNS Management (moved to ChatDNS)

DNS record management, DDNS, IP detection, and DNS-01 certificate automation now live in the standalone ChatDNS package. Use the first-level chatdns CLI:

chatdns --help
chatdns records test.example.com
chatdns set test.example.com -v 1.2.3.4
chatdns ddns -d example.com -r home --monitor
chatdns ddns -d example.com -r nas --ip-type local --local-ip-cidr 192.168.1.0/24
chatdns cert apply -d example.com -e admin@example.com --provider aliyun --staging
chatdns cert check -d example.com

Install through ChatTool's optional dependency with pip install "chattool[dns]". The nested chattool dns command has been removed so ChatTool no longer carries duplicate DNS/certificate business logic.

5. AI Image Generation (chatimg)

Image provider tools have moved to the standalone ChatImg package. Install it through ChatTool's optional dependency when you want the ChatArch aggregate install path:

pip install "chattool[images]"

chatimg pollinations generate "a cat in space" -o cat.png
chatimg siliconflow generate "a cute dog" -o dog.png
chatimg codex generate "a watercolor fox"
chatimg openai generate "a clean app icon"

The nested chattool image command has been removed so ChatTool no longer carries duplicate image provider business logic.

6. Nginx Config Generation (chattool nginx)

chattool nginx --list
chattool nginx proxy-pass --set SERVER_NAME=app.example.com --set PROXY_PASS=http://127.0.0.1:8080
chattool nginx websocket-proxy ./websocket.conf --set SERVER_NAME=ws.example.com --set PROXY_PASS=http://127.0.0.1:3000
chattool nginx -i

7. Local Services (chattool serve)

chattool serve local ./cli-tree.html --host 127.0.0.1 --port 8765
chattool serve local ./reports --html cli-tree.html --port 8765
chattool serve local . --html index.html --dry-run

serve local opens a local HTML file or directory through a configurable local port. If TARGET is omitted, it defaults to the current directory; -i uses the shared interactive prompt flow.

8. Other Tools

Tool Command Description
Network Tools chatnet (from chattool[arch] / ChatNet) Scan hosts, check ports, validate links, and inspect service URLs through the standalone ChatNet package
Nginx Config chattool nginx Generate template-based reverse proxy and static site configs
MCP Server chattool mcp info / chattool mcp inspect Inspect MCP server capabilities (JSON supported)
Screenshot chattool serve capture Local webpage screenshot service
Local HTML chattool serve local Serve a local HTML file or directory
Cert Mgmt chattool serve cert / chattool client cert SSL certificate distribution
Setup chatup codex/claude/opencode/hermes ChatTool setup has moved to the standalone ChatUp package. Install chattool[setup] or chatup, then use first-level chatup ... commands.
CRS chatcrs Install chattool[crs] or ChatCRS; the parent no longer embeds CRS commands, client code, or its config provider.
Workspace chatup workspace Create a collaboration workspace around a core project with projects/ as the execution container and workspace-level files as the general-use protocol layer; supports --with-chattool, --with-chatblog, and --with-memory
Skills chattool skill install Install ChatTool skills to Codex / Claude / OpenCode
CC-Connect chattool cc Quick cc-connect setup and start

Environment Profiles

Since ChatTool 7.0.0, typed env profiles live under ~/.chatarch/envs by default. Set CHATARCH_HOME to redirect the ChatArch root. The old ~/.config/chattool/envs path is no longer read as a fallback.

To manually copy legacy profiles into the new root from a repository checkout:

python scripts/migrate_chattool_envs_to_chatarch.py --dry-run
python scripts/migrate_chattool_envs_to_chatarch.py

CLI Tree

chattool --tree is generated from the real Click/LazyGroup registry to lock the current parent command surface.

chattool  # Unified entry point for ChatTool services and scripts.
├── --help  # Show help for the current command.
├── --version  # Show package version.
├── --tree  # Print the registered CLI tree.
├── browser  # Browser automation helpers.
├── cc  # cc-connect helper commands.
├── client  # Remote client tools.
├── docker  # Docker utility commands.
├── explore  # Research and data exploration helpers.
├── mcp  # MCP server inspection and launch helpers.
├── nginx  # Nginx configuration generation helpers.
├── serve  # Local service helpers.
├── skill  # Install and manage ChatTool skills.
└── tplogin  # TP-Link router helpers.

PyPI Package Scaffolding

pip install "chattool[pypi]"
chatpypi init mychat
chatpypi init mycli -t chatarch
chatpypi init -i                  # Interactive template, mkdocs, and workflow options
chatpypi probe mychat
chatpypi mychat

ChatTool no longer embeds chattool pypi; install chattool[pypi] or ChatPyPI and use the standalone chatpypi CLI. The chattool[arch] extra installs the parallel ChatArch tools: ChatGH, ChatUp, ChatPyPI, ChatNet, ChatLark, and ChatImg. Use --without-mkdocs or --without-workflows to skip optional scaffold files.

chatpypi probe <name> checks the exact project name on PyPI by default and prints a concise blocking result plus useful package metadata, including the latest release date, when the name already exists.

License

MIT License. See the LICENSE file for details.

Changelog

  • 5.3.0 — Feishu/Lark bot (messaging, event routing, AI chat), CLI tools (chattool lark, chattool serve lark)
  • 5.0.0 — DNS management (Aliyun/Tencent), DDNS, SSL cert auto-renewal, centralized env config
  • 4.1.0 — Unified Chat API (sync/async/stream), env-based configuration
  • For earlier changes, please refer to the repository commits.