DeepSeek-cli v2.2.0
全异步、高可扩展的 AI 聊天服务后端,支持多模型适配、增量流式 Markdown 渲染、工具调用系统、上下文压缩和终端交互界面。
快速开始
1. 安装依赖
项目使用 Python ≥ 3.9。
方式一:一键安装(推荐)
# 安装全部核心依赖
pip install httpx Pygments beautifulsoup4 chardet aiofiles qrcode \
Pillow psutil PyYAML typing_extensions
# 可选加速(推荐)
pip install orjson h2
# 安装开发依赖(测试 / 代码检查 / 提交钩子)
pip install pytest pytest-asyncio pytest-xdist pytest-cov ruff mypy pre-commit orjson h2
方式二:通过项目安装(自动读取 pyproject.toml,推荐)
# 安装核心依赖
pip install .
# 核心依赖 + 高性能 JSON / HTTP2
pip install ".[perf,http2]"
# 安装开发依赖(测试/代码检查等)
pip install ".[dev]"
依赖库说明:
| 包 | 用途 | 必需 |
|---|---|---|
httpx |
HTTP 请求库 | ✅ |
Pygments |
代码语法高亮 | ✅ |
beautifulsoup4 |
HTML 抓取解析(web_fetch) |
✅ |
chardet |
字符编码检测(read) |
✅ |
aiofiles |
异步文件操作 | ✅ |
qrcode |
终端二维码生成(微信 ClawBot 登录) | ✅ |
Pillow |
图像解码/归一化(read_image、图片上传) |
✅ |
psutil |
状态栏 CPU/内存、Shell 探测(缺失时回退平台实现) | ✅ |
PyYAML |
插件清单 / 技能 frontmatter(缺失时回退内置 YAML 子集解析) | ✅ |
typing_extensions |
Python < 3.11 的 dataclass_transform 支持 |
✅(<3.11) |
orjson |
高性能 JSON 编解码(缺失时回退标准库 json) |
可选 |
h2 |
HTTP/2 支持(配置 enable_http2 生效前提) |
可选 |
可选依赖缺失时程序仍可运行,只是对应能力降级(由
pip install ".[perf,http2]"启用)。Cygwin / MSYS2 平台限制:
orjson(Rust 扩展,无该平台 wheel)、psutil(上游 setup.py 明确拒绝 cygwin)、ruff(Rust 二进制,无该平台 wheel)在该平台没有可安装的 发行版,requirements*.txt与pyproject.toml已用sys_platform标记跳过,程序按上表 自动降级;Pillow在该平台锁8.4.0(9.5+ 源码构建在 jpeg 探测阶段失败);pre-commit按 Python 版本锁定(3.9/3.10 →4.3.0,≥3.11 →4.7.0)。
2. 配置
方式一:配置文件 + 模型选择器(推荐)
LLM 访问参数(API 密钥 / 接口地址 / 模型名 / 提供商)的唯一来源是模型档案
(model_profiles)——首次运行未配置档案时会自动打开模型选择器引导配置
(/models 可随时打开;新增只需三步:① 选提供商 → ② 选/填模型名(可从该
提供商内置模型列表 ↑↓ 选择,也可输入自定义名)→ ③ 填 API 密钥)。
创建配置文件 ~/.chat_config/chatrc.json:
{
"model_profiles": [
{
"provider": "deepseek",
"model": "deepseek-v4-flash",
"api_key": "sk-你的API密钥",
"base_url": "https://api.deepseek.com/v1/chat/completions",
"name": "DeepSeek Flash",
"temperature": "0.3",
"reasoning_effort": "high",
"multimodal": "true"
}
],
"active_model_profile": 0,
"reasoning_effort": "max",
"temperature": 0.2,
"thinking_enabled": true,
"max_context_chars": 3000000,
"max_output_chars": 1000000,
"max_retries": 10,
"retry_base_sec": 30,
"empty_response_max_retries": 0,
"max_session_messages": 0,
"keep_recent_messages": 0,
"theme": "dark",
"max_context_tokens": 1000000,
"summary_token_budget": 100000,
"auto_force_compress_threshold": 600000,
"enable_notifications": true,
"notify_on_chat_completion": true,
"image_upload_optimize": true,
"image_upload_keep_recent": 4,
"image_upload_max_dimension": 1568,
"image_upload_quality": 80,
"mcp_servers": [],
"performance": {
"http_client": {
"connect_timeout": 30,
"read_timeout": 120,
"write_timeout": 120,
"max_connections": 100,
"max_connections_per_host": 20,
"keep_alive_timeout": 15,
"enable_pool": true,
"enable_http2": true
}
}
}
model_profiles:模型档案列表(每个档案含provider/model/api_key/base_url/name,以及可选的temperature(0.0~2.0)与reasoning_effort(low / medium / high / max);base_url留空则用提供商 默认地址;生成参数留空则沿用全局temperature/reasoning_effort默认值)。thinking_enabled:思考模式开关(默认true)。Ctrl+T 可随时切换并 持久化;关闭时 DeepSeek V4 请求注入thinking.type=disabled(官方默认 enabled,必须显式关闭),状态栏模型名后显示[off]。也可用/config set thinking_enabled false或python chat.py config set thinking_enabled false设置。 温度与该开关联动:官方文档明确「思考模式不支持temperature」(设置 不报错但会被忽略),因此思考模式开启时请求不携带temperature(/models温度字段标注「思考模式开启,不生效」),关闭思考模式后再发送并生效;presence_penalty/frequency_penalty同理。multimodal("true"/"false",默认"false")声明该模型是否支持 多模态读图:true时才会向模型加载read_image工具,false时该工具不 进入工具集、执行也会被拒绝(在/models界面「多模态读图」字段设置)。active_model_profile:当前生效档案下标(由模型选择器写入,-1= 未选择)。empty_response_max_retries:模型返回完全空响应(无正文/无推理/无工具 调用)时的自动重发上限。0(默认)= 无限重试,直到拿到有效回答或用户ESC中断——空响应不是「调用失败」而是「没拿到回答」,请求健康、尚未渲染 任何内容、重发幂等安全,因此不占用max_retries瞬时错误预算,也 不输出错误(连续多次未恢复时给一条弱提示);等待按 2→4→8→15 秒封顶。>0= 有界重试(内部调用方如压缩摘要、SubAgent 恒为有界,快速失败)。
配置文件位于 ~/.chat_config/chatrc.json,首次运行时自动创建(使用默认值)。
方式二:环境变量
仅流式输出节奏类参数支持环境变量覆盖(LLM 访问参数已不再支持环境变量—— API 密钥 / 接口地址 / 模型名 / 提供商只能通过模型档案配置):
| 环境变量 | 说明 | 示例 |
|---|---|---|
CHAT_STAGGER_MIN_DELAY |
流式输出最小延迟 | export CHAT_STAGGER_MIN_DELAY="0.1" |
CHAT_STAGGER_MAX_DELAY |
流式输出最大延迟 | export CHAT_STAGGER_MAX_DELAY="0.5" |
已移除:
CHAT_API_KEY/CHAT_BASE_URL/CHAT_MODEL/CHAT_LOW_MODEL以及 RC 旧键api_key/base_url/model/provider/low_model/models(加载配置时自动清理)。
支持的多模型 Provider
| Provider | 适配器 | 说明 |
|---|---|---|
deepseek |
DeepSeekAdapter |
DeepSeek 官方 API(默认)。内置模型:deepseek-flash(V4.1 Flash,最新一代、原生多模态视觉)、deepseek-v4-pro(V4-Pro 旗舰);旧名 deepseek-v4-flash / deepseek-v4-flash-vision-exp 已下线并由 V4.1 Flash 承接(保留以兼容旧配置)。deepseek-chat / deepseek-reasoner 已退役 |
custom |
OpenAICompatAdapter |
任意 OpenAI 兼容 API(OpenAI / 通义千问 / 本地 Ollama 的 OpenAI 兼容端点等),自动检测 reasoner 模型 |
anthropic |
AnthropicAdapter |
Anthropic Claude 系列模型(API 格式自动转换)。内置模型:claude-opus-5-5(默认,官方推荐)、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5-1、claude-opus-5、claude-sonnet-5、claude-haiku-4-5-20251001、claude-opus-4-8、claude-sonnet-4-6 |
glm |
OpenAICompatAdapter |
智谱 GLM(open.bigmodel.cn)。内置模型:glm-5.3(默认,旗舰)、glm-5.3-flash / glm-5.3-flashx(原生多模态)、glm-5.2、glm-5.1、glm-5、glm-4.7 |
mimo |
OpenAICompatAdapter |
小米 MiMo(token-plan-cn)。内置模型:mimo-v2.6-pro(默认)/ mimo-v2.6-flash / mimo-v2.6-pro-ultraspeed(全模态理解);mimo-v2.5-pro / mimo-v2.5 将于 2026-10-21 下线(保留候选便于迁移) |
上表「内置模型」即
/models新增档案时「模型名」字段的候选来源(随各提供商 官方最新模型更新,候选行标注「默认」与计费单价;deepseek/anthropic为 美元 / 百万 tokens,glm/mimo以人民币计价故不内置单价);候选之外仍可 直接键入任意自定义模型名。
模型名以
ollama开头时按OllamaAdapter路由(本地 Ollama 部署,默认localhost:11434);该路由由模型名决定,不需要provider: ollama。
3. 启动
交互式对话(默认)
python chat.py
启动终端交互界面,进入多轮对话。
单次问答模式
python chat.py -p "你好,请介绍一下自己"
输入一句话,大模型回答完成后立即退出,适合脚本调用。
从保存的会话恢复
python chat.py --load <会话ID>
指定模型
python chat.py -m deepseek-v4-pro # 按模型名匹配已有「模型档案」并设为当前
python chat.py --model deepseek-v4-pro
LLM 访问参数唯一来源 = 模型档案,因此 -m / --model 只能选择已有档案
(按档案的 model 或 name 匹配)——档案不存在时会列出可用档案并提示先运行
/models 新增。
多模态视觉(deepseek-flash)
deepseek-flash(DeepSeek V4.1 Flash)是 DeepSeek 最新一代模型,原生支持
多模态视觉理解,图片按 token 计费。旧模型名 deepseek-v4-flash 与
deepseek-v4-flash-vision-exp 已下线,请求统一路由到 V4.1 Flash(按相同
单价计费,同样具备视觉能力)。接入方式:
# 先确保模型档案中有该模型(/models 界面新增,或 config set model_profiles),
# 再按名选择:
python chat.py -m deepseek-flash
该模型支持两种图片输入方式(图片仅支持出现在用户消息中):
用户消息直接传图:在输入中携带本地图片路径、
或 裸 http(s) 图片 URL,CLI 自动转换为图片 content blocks(本地图片自动 base64 内联,URL 原样传递):分析 /path/to/screenshot.png 里的报错信息 看下 拖动文件输入路径:把文件从文件管理器拖入终端窗口(输入框),终端会把 路径文本注入为「粘贴」——CLI 自动识别并规范化为干净路径(去引号、还原 反斜杠转义、解析
file://URI、Cygwin/MSYS 下把 Windows 路径转为 POSIX 路径),多文件每行一个、含空格路径用双引号包裹;非路径文本(自然语言、 代码)原样输入不受影响。图片路径因此同样可直接拖入传图。 关闭:python chat.py config set tui_drop_path_normalize false。read_image 工具(按模型开关加载):模型档案的「多模态读图」 (
multimodal)为true时才向该模型加载read_image工具;为false时工具不进入工具集、执行也会被拒绝。开启后 AI 代理可主动调用read_image读取本地图像(DSH 对齐:路径参数file_path;支持全部 Pillow 可解码格式,无扩展名按文件内容识别;自动应用 EXIF 方向并规范化为 8-bit sRGB;大图自动降采样到 2048×2048 总像素预算 / 4 MiB 目标,返回文本给出原尺寸与坐标换算倍数;图片字节持久化到内容寻址附件库, 工具结果返回附件引用)。本项目保留分块/灰度/旋转/翻转/缩放扩展。 在/models编辑模型档案的「多模态读图」字段即可切换(默认 false)。
上传前图片瘦身(默认开启):图片随会话历史累积,而每轮 API 请求都会 重传整个历史(发送副本会把附件引用展开为 base64 data URI),图片一多 请求体便随图片数量线性膨胀(实测 6 张 1080p 截图 ≈ 47MB/请求),表现为 "图片多了每次都很卡"。客户端在发送副本上自动做三件事: ① 折叠——仅保留最近
image_upload_keep_recent张图片,更早的图片块替换为 文本占位;② 压缩——超过image_upload_max_dimension长边或体积阈值的图片 降采样并重编码为 JPEG;③ 编码缓存——同一图片不重复解码/编码。 该优化不改动会话存档、TUI 显示与read_image的附件引用(存档保留 引用,发送副本才展开为 data URI)。python chat.py config set image_upload_optimize false # 关闭优化 python chat.py config set image_upload_keep_recent 8 # 多保留几张(0=不折叠) python chat.py config set image_upload_max_dimension 1024 # 上传长边上限 python chat.py config set image_upload_quality 80 # JPEG 质量 1~100图片 token 统计:图片按 token 计费,
/usage的输入 token 来自 API 真实 usage(已含图片 token);上下文使用率百分比(模式行main · N%)与压缩 判断另按图像尺寸估算视觉 token(ceil(w/patch) * ceil(h/patch),默认patch=28;长边按image_upload_max_dimension降采样、仅计image_upload_keep_recent张),可用multimodal_image_token_patch(分块边长)与multimodal_image_token_default(无法读尺寸时每图占用)覆盖。
非多模态模型下,用户消息中的图片引用保持纯文本原样传递(模型不可见图片)。 如有多模态模型未被内置模式识别,可通过配置扩展:
python chat.py config set multimodal_models '["my-vision-model"]'
详细日志模式
python chat.py -v # INFO 级别日志
python chat.py -vv # DEBUG 级别日志
会话管理
python chat.py session list # 列出所有保存的会话
python chat.py session delete <会话ID> # 删除指定会话
python chat.py session export <会话ID> # 导出会话(打印到 stdout)
python chat.py session export <会话ID> -o chat.json # 导出到文件
查看版本
python chat.py --version
python chat.py version
完整命令一览
| 命令 | 说明 |
|---|---|
python chat.py |
交互式对话(默认) |
python chat.py -p "你好" |
单次问答模式 |
python chat.py --load abc123 |
从会话恢复 |
python chat.py -m deepseek-v4-pro |
选择模型(按名匹配已有模型档案) |
python chat.py -v |
INFO 级别日志 |
python chat.py -vv |
DEBUG 级别日志 |
python chat.py session list |
列出所有会话 |
python chat.py session delete abc123 |
删除会话 |
python chat.py session export abc123 |
导出会话 |
python chat.py config |
显示全部配置(含敏感值脱敏) |
python chat.py config get temperature |
查询单个配置 |
python chat.py config set temperature 0.7 |
设置配置并持久化 |
python chat.py config reset temperature |
重置配置为默认值 |
python chat.py --version |
显示版本信息 |
python chat.py clawbot |
微信 ClawBot 远程控制(扫码登录) |
python chat.py clawbot --re-login |
强制重新扫码登录 |
3.5 微信 ClawBot 远程控制(clawbot)
通过微信官方 ClawBot 插件协议(iLink Bot API)实现远程发命令 + 结果显示:
python chat.py clawbot # 启动(复用缓存凭证或扫码登录)
python chat.py clawbot --re-login # 强制重新扫码登录
登录:终端会直接渲染微信官方登录二维码(手机扫码即可,无需打开文件),扫码确认后自动进入监听模式。
远程发命令(在微信里给 ClawBot 发消息):
| 微信消息 | 功能 |
|---|---|
| 普通文本 | AI 对话(DeepSeek 会话引擎,可自动调用文件/Shell 等工具) |
/shell <命令> |
远程执行 Shell 命令并回显结果 |
/clear |
清空当前会话上下文 |
/new |
开始新会话 |
/status |
显示模型、会话与连接状态 |
/time |
显示连接剩余时间 |
/model <名称> |
切换模型 |
/help |
显示帮助 |
安全配对:首次发消息的用户需回复终端打印的配对码完成授权,之后该用户的所有命令都被处理;已授权用户持久化在 ~/.chat_config/clawbot_allowed.json。
其他说明:
- 每个微信用户有独立会话(LRU 上限 20 个),结果分段回显到微信
- 输入状态指示("正在输入")自动发送/取消
- iLink 连接有效期 24 小时,到期前自动提醒并支持扫码重连
4. 快捷操作(终端交互模式下)
以下快捷键仅在终端交互式对话(
python chat.py)中生效。
| 快捷键 | 功能 |
|---|---|
Enter |
发送消息 |
Esc |
清空当前输入框内容(空闲时单次按下;AI 生成中为中断当前回复) |
Ctrl+G |
使用 vim 编辑器编辑当前输入内容(支持 $EDITOR 环境变量) |
Ctrl+O |
编辑当前会话中的已有消息(触发 /editmsg 命令) |
Ctrl+N |
循环切换对话模型(只在模型档案中选择:/models 新增的模型档案;未配置时提示先用 /models 新增) |
Ctrl+P / ↑ |
浏览输入历史(上一条) |
↓ |
浏览输入历史(下一条) |
Ctrl+R |
反向历史搜索(配置门控;默认重试上一轮) |
Ctrl+T |
切换思考模式(Thinking)开关,默认开启;关闭后 DeepSeek V4 请求注入 thinking.type=disabled,状态栏模型名后显示 [off](主题请用 /theme 切换) |
Ctrl+L |
清屏 |
Ctrl+D |
退出程序(输入为空时) |
Ctrl+Z |
撤销输入编辑(连续同类编辑合并为一步) |
Ctrl+Y |
重做输入编辑 |
Ctrl+B |
主 Agent 运行模式循环切换(空模式 → 简单模式 → 标准模式 → 空模式) |
Ctrl+C(首次) |
中断当前 AI 回复 |
Ctrl+C(再次) |
强制退出程序 |
Tab |
自动补全(命令名、会话 ID 等) |
Shift+Tab |
补全反向循环 |
PgUp / PgDn |
补全弹窗翻页 |
Ctrl+A / Home |
光标移到行首 |
Ctrl+E / End |
光标移到行尾 |
Ctrl+F / → |
光标右移一字符 |
Ctrl+B(编辑) |
光标左移一字符(← 键) |
Ctrl+← / → |
词跳转(等价 Alt+B / Alt+F) |
Ctrl+W / Alt+Backspace |
删除光标前一个词 |
Alt+D |
删除光标后一个词 |
Ctrl+U |
删除光标到行首 |
Ctrl+K |
删除光标到行尾 |
↑ / ↓(补全可见) |
移动补全高亮 |
F1 / Ctrl+/ |
打开/关闭帮助速查视图(命令行上 Enter 直接执行、Tab 填入输入框) |
F2 |
打开/关闭命令面板(模糊检索全部斜杠命令:输入即筛选,↑↓/PgUp/PgDn 选择,Enter 执行,Tab 填入输入框,Esc/F2 关闭;最近使用命令置顶) |
F11 |
打开/关闭文件变更审查器(沙盒 diff / 回滚 / 历史时间线 / 统计;打开后按一次 F11 或 Esc 即关闭) |
F12 |
打开/关闭会话日志 / 投影浏览器 |
Ctrl+H |
打开/关闭轨迹视图(DSH 风格台账 + 检查器) |
命令面板(F2):无需记住命令名——输入任意关键词即可按名称 / 别名 / 描述 / 分组做子序列模糊匹配;右侧实时显示命令详情、别名、同组命令与操作 方式;
Enter立即执行,Tab只填入输入框(便于补充/load <ID>等参数)。 最近执行过的命令会在空查询时置顶(★ 标记),面板在 AI 流式输出期间也能 立即打开。状态栏同时展示工作区信息(⎇ 分支 当前目录,可在插件清单中 按status_segment_workspace禁用/替换)与所有 Agent 的累计输入/输出 token(◆ 入 1.2Mt · 出 3.4kt;输入量按各 Agent 上下文增量累计——本次 input − 同 Agent 上次 input,首次/缩小/切模型计全量,不含内部压缩/标题 调用,空闲时也常驻;过窄时整段上移到顶部分隔线右侧)。
5. 斜杠命令(终端交互模式下)
在对话输入框中以 / 开头输入命令:
命令投递规则(2026-10-22):斜杠命令提交后直接执行,不进入用户消息队列。 AI 生成 / 其他命令执行期间,只有展示 / 审查类命令(
/usage、/changes) 立即执行,其余命令等当前轮 / 当前命令结束后再执行。/changes在流式输出 期间可直接打开并实时刷新,但回滚动作(x/u/X/R)会暂停到生成结束。 以下命令例外——始终经 消息队列串行执行(会改写会话历史、触发新一轮生成、改写上下文预算或独占交互界面):/clear/load/retry/edit/editmsg/deitmsg/compact/context/loop/model/models/config/plugin/theme/export/search。普通用户消息始终经消息队列。命令面板(F2)/ 帮助视图(F1)执行的 命令与输入框 Enter 同路径。显示(2026-10-22):用户消息、按 Enter 后的斜杠命令回显、
exit回显统一 使用白色粗体 + tool_card 背景色整行满宽显示(背景色与工具卡同源:ui_defaults.tool_card_bg,默认 236);命令输出随后显示。命令面板 / 帮助视图 执行命令同样先回显。
| 命令 | 别名 | 功能 |
|---|---|---|
/clear |
— | 清空对话(保留系统提词) |
/loop <N> <提词> |
— | 按批次循环执行提词:N 为批次数(必须显式正整数;省略或 0 报错)。每批内只要 LLM 返回 continue=true 就继续执行(不设运行次数上限),每次使用上一轮生成的续跑提词;continue=false 表示本批完成、批次数减一,减到 0 结束。每批开始时清空对话并重新使用最初的提词;用户输入 / ESC 立即终止整个循环。流式生成中可省略提词:输入 /loop <批次数> 立即接管当前正在生成的一轮,以当前会话最早的一条人类用户消息为提词,当前轮直接计为第 1 批第 1 次运行(不重跑、不清空),本轮结束后生成续跑提词继续;空闲时省略提词仍报用法错误。聊天区不显示 LLM 输入 / 输出原文(只显示 continue / compact 解析结果与提词);续跑提词 JSON 含 compact 字段:模型分析数据后若最后一次回答出现「上下文不够 / 上下文不足 / token 不够」等借口即返回 compact=true,/loop 判定为 true(无论 continue 真假)即调用 check_and_compress(force=True) 执行一次全量上下文压缩(保留系统提词;不可用 / 失败只提示并继续);循环浮窗显示当前批与本次运行的已运行时长。判定不接受理由 / 借口 / 推诿:改动类任务没有实际修改与验证证据就继续运行(纯问答 / 分析类按回答是否完整结束) |
/pet [on|off] |
— | 召唤/收回爱吃大白饭的蓝色大肥鱼宠物(娘化萌版):无边框、透明背景右侧 40 列浮窗;干饭、咀嚼、打嗝、追饭粒、吃撑躺平、跳舞、吃 tok 等 22 种动作,端着饭碗、冒热气、掉饭粒,并随机冒泡说干饭/撒娇/治愈台词(无参数 = 召唤/收回切换) |
/pin |
— | 标记重要消息(压缩时保留) |
/compact |
— | 压缩上下文历史:把最旧的平衡范围替换为一条结构化检查点(保留近期尾部),报告压缩条数与节省 token;压缩过程在模式行显示 compact · N |
/context [256k|1m|tokens] |
— | 显示当前上下文窗口、使用率与压缩预算(阈值/保留尾部/剪枝);带参数写入模型上下文窗口,后续请求与自动压缩按新容量实时计算 |
/editmsg |
— | 编辑当前会话消息(同 Ctrl+O) |
/retry |
/r |
重新生成上一条回答 |
/edit |
— | 编辑并重新发送上一条输入 |
/model |
— | 切换模型(无参数时打开模型选择器,只在模型档案中选择——RC 顶层 models 字段已移除,不列内置 provider 模型;亦支持序号/名称直接切换) |
/models |
— | 模型选择器(全屏界面:↑↓/jk 选择 · Enter 应用 · a 新增 · c 复制 · e 编辑 · d 删除 · r 刷新模型档案)。新增只需三步:① 选提供商(接口地址自动填好)→ ② 选/填模型名(进入「模型名」字段后 ↑/↓ 从该提供商内置模型列表选择——候选行标注「默认」与计费单价,亦可直接键入自定义模型名)→ ③ 填 API 密钥(显示名留空则用模型名);表单还提供 温度(0.0~2.0,留空沿用全局默认)、思考级别(low/medium/high/max,留空沿用全局默认)与 多模态读图(true/false:true 才加载 read_image 工具;默认 false),保存后按模型生效(全局 /temperature、/reasoning 命令已由本界面取代);列表行同时显示模型名与接口主机,选中详情行展示完整模型名/提供商/接口地址/脱敏密钥/温度/思考级别/多模态读图;字段输入支持光标编辑(←/→ · Home/End · Delete · Ctrl+A/Ctrl+E · Ctrl+U);/ 搜索 · n/N/p 匹配 · f 过滤 · ? 帮助(表单内亦可) · y 复制信息 · Esc 关闭 |
/usage |
— | 右侧用量浮窗(token 用量(输入(Agent 新增)按各 Agent 上下文增量累计;缓存命中率 dsh 口径:命中 / (命中 + 未命中),缓存明细与费用仍按 API 每次请求计费口径)/ 上下文窗口 / 费用估算,按帧实时刷新;宽度为终端 60%(上限 60 列);再次输入 /usage 关闭。AI 流式生成期间也可开关,不阻塞生成) |
/config |
— | 显示/编辑程序配置(无参数打开独立配置界面:↑↓/jk 选择、Enter 编辑、Esc 关闭;枚举/布尔/模型走选择界面、list/dict 子 JSON 走递归结构化编辑界面(Enter 逐层下钻嵌套 · 标量编辑 · a 追加 · d 删除 · Esc 逐级返回、顶层保存)、数值/字符串走输入界面;亦支持 show/list/get <键>/set <键> <值>/reset <键>) |
/load <ID> |
— | 加载保存的对话 |
/sessions |
— | 列出所有保存的对话 |
/export [路径] |
— | 导出当前对话为 Markdown(含 SubAgent 聊天信息) |
/theme [名称] |
— | 无参数打开主题选择器(全屏界面:↑↓/jk 即时预览 · Enter 确认 · Esc 恢复原主题 · / 搜索 · f 过滤 · n/N/p 匹配定位 · PgUp/PgDn 滚动 · ? 帮助);带名称直接切换(dark / light / high-contrast / nord / dracula / gruvbox / tokyo-night / catppuccin) |
/changes |
— | 文件变更审查器(全屏界面,F11 快捷打开/关闭:打开后按一次 F11 或 Esc 即关闭;流式输出期间可直接打开并实时刷新,回滚动作等生成结束后可用):左栏文件列表按 t 切目录树、m 切消息维度、s 轮换排序(路径/次数/最近/索引)、T 循环类型过滤;右栏按 d 在差异 / 历史时间线(该文件逐次修改 + diff)间切换、i 统计面板、r 回滚预览;x 回滚该文件 · u 撤销回滚 · X 回滚全部 · R 回滚到消息索引 · y 复制路径 · c 复制差异 · w/W 导出变更报告(md/json)· / 搜索 · f 过滤 · ? 帮助 · Esc/F11 关闭(可加文件名过滤) |
/logs |
— | 会话日志 / 投影浏览器(全屏界面,F12 快捷打开):左栏事件流(#seq 图标 类型 时间 摘要)+ 右栏按 v 循环四模式——事件详情(data 展开)/ 消息投影(derive_messages 模型历史)/ 投影状态(turnBoundary 等投影单元 snapshot)/ 一致性校验(SessionLog.verify「模型可见即已记录」);F 跟随最新(随会话日志增长实时刷新)/ r 刷新 / / 搜索 · n/N/p 定位 · f 过滤 · ? 帮助 · Esc 关闭 |
exit |
— | 退出程序 |
SubAgent 聊天记录持久化:每个 SubAgent 的完整内部对话(system 提示词 / 任务指令 / 助手回复 / 工具调用与结果)会在其运行结束时记录到父 Agent,并随会话自动保存到
~/.chat/msg_list/<id>.json的subagents字段;/load加载会话时同步恢复,/export导出 markdown 时一并包含。
工具系统(Tool System)
AI 代理在对话中可调用以下工具完成各类操作。共 19 个内置工具,涵盖文件操作、代码搜索、网络请求、用户交互等能力。
除内置工具外,还可通过 MCP(Model Context Protocol) 接入外部服务器提供的工具, 注册后与内置工具同构调用(详见下方 MCP 外部工具接入)。
工具列表
| 工具名 | 缩写 | 分类 | 并行安全 | 功能说明 |
|---|---|---|---|---|
read |
rd | IO | ✅ | 读取文件内容,支持指定行号范围、自动编码检测,可显示行号(默认关闭) |
write |
wr | IO | ✅ | 覆盖写入文件,自动创建父目录,原子写入 |
edit |
ed | IO | ❌ | 精确替换文件中的文本(old_string → new_string),支持 use_regex 正则替换 |
grep |
gp | 搜索 | ✅ | 在项目源码中搜索正则表达式,自动排除非源码目录 |
glob |
gl | 搜索 | ✅ | 按文件名/路径通配符查找文件和目录,支持 ** 跨目录(如 **/*.py、**/*)与 {a,b} 大括号展开(如 **/*.{c,h,cpp,hpp,cc,py,mk}) |
ls |
ls | IO | ✅ | 列出目录内容,支持详细格式和隐藏文件显示 |
bash |
bs | 执行 | ❌ | 执行 shell 命令(安全沙盒保护,禁止替代专用工具) |
bash_opt |
bo | 执行 | ❌ | 按 task_id 操作后台 bash 任务:read(增量读取当前输出并清空缓冲,立即返回;只读观察、不接管任务)/ wait(等待完成取输出;超时返回结构化 JSON,任务继续运行)/ kill(杀死整个进程树并校验,未死自动补杀)/ stdin(发送文本输入;编码缺省 UTF-8;newline 控制换行)/ close_stdin(发送 EOF/EOT)/ keys(发送光标键盘消息:有 GUI 窗口时注入窗口,否则写入终端 PTY/stdin;支持 ctrl+c、esc/pageup、f1-f20)/ screenshot(窗口或整屏截图存为 PNG,需 path;可选 crop、window、screen=true/primary/序号)/ move(移动到窗口内 x/y)/ hover(移动到目标点停留)/ click(左右中键、双击:button/count)/ drag(拖动:from_x/from_y → to_x/to_y)/ scroll(滚轮 direction/amount)/ key(窗口级按键,如 ctrl+s)/ type(向窗口逐字符输入 Unicode 文本)/ release(释放全部按下的键与鼠标按钮);坐标以窗口截图左上角为原点,支持 center/50%/center+20 等语义坐标 |
cp |
cp | IO | ✅ | 复制文件或目录,保留元数据,支持沙盒撤回 |
mv |
mv | IO | ✅ | 移动文件或目录,支持跨文件系统 |
rm |
rm | IO | ❌ | 删除文件或目录(删除前自动备份到沙盒) |
mkdir |
mk | IO | ✅ | 创建目录,支持递归创建父目录 |
read_image |
ri | IO | ✅ | 读取图像文件内容(DSH 对齐:路径参数 file_path;全部 Pillow 可解码格式,无扩展名按内容识别;自动 EXIF 方向 + 8-bit sRGB 规范化;大图自动降采样到 2048×2048 总像素预算 / 4 MiB 目标并给出原尺寸坐标倍数;图片持久化到内容寻址附件库并返回附件引用);仅当模型档案「多模态读图」=true 时加载(/models 设置,默认 false;false 时工具不进入工具集且执行被拒绝)。本项目保留分块读取与图像操作(灰度/旋转/翻转/缩放)扩展。发送前客户端会自动瘦身(折叠旧图+压缩大图+编码缓存),缓解多图场景每轮重传导致的请求卡顿 |
web_search |
ws | 网络 | ❌ | DeepSeek 官方原生联网搜索(Anthropic 兼容 Messages API + web_search_20250305),返回来源列表(标题/URL/摘要) |
web_fetch |
— | 网络 | ✅ | 获取指定 URL 的网页全文(自动提取正文,SSRF 防护,仅 http/https) |
user_select |
us | 交互 | ❌ | 向用户显示交互式选择界面(单选/多选/1 分钟无操作超时回退/非交互回退,选项为 {label, description} 对象、说明可多行且与选项同参数传入;支持并发提问——多个问题可同一轮同时弹出、以 tab 形式一起回答)。超时按空闲计时:每次按键/滚动重置 1 分钟倒计时,持续操作永不超时;自定义输入编辑期间暂停计时(标题区不显示/递减倒计时),提交或退出后恢复(外部编辑器 Ctrl+G 期间同样暂停)。TUI(对齐 Claude Code AskUserQuestion v2.1.308):tab 栏 ← [x] 标题 [ ] 标题 √ 提交 →(当前 tab 反色,header 仅用于 tab 标签);问题页单行问题文本(无 chip / 分割线),右侧显示位置/多选已选数/倒计时;选项形如 > 1. 标签,选中整行背景高亮,说明写在 options[].description 并缩进显示在选项下方(选中项按原文多行展开、超宽自动换行;其余选项折叠单行);多选 [√]/[ ],列表末尾追加 提交 项;自定义输入为普通编号项 其他(自定义输入…)(Enter 进入多行编辑:Shift+Enter/Ctrl+O 换行、Enter 提交、Esc 返回;空输入框光标常显,空输入 Enter 提示「输入不能为空」;输入内容按原文多行显示、超宽自动换行,长内容以光标为中心滚动);支持 1-9 快选(单选立即确认、多选切换勾选)、Home/End/PgUp/PgDn 导航;主提示 Enter 选择 · Tab/←→ 切换 · Esc 取消 + 次要快捷键第二行;长列表显示 ▲ 上方 N 项 / ▼ 下方 M 项;多选支持 a 全选/全不选、c 清空;自定义输入支持 Ctrl+U 清空/Ctrl+W 删词/←→↑↓ 移动光标/Ctrl+O 换行;Submit 页为 检查你的答案 + • 问题 / → 答案(自定义多行答案逐行显示) + > 1. 提交答案 / 2. 取消,支持 PgUp/PgDn 分页滚动与 1-9 跳题 |
subagent |
sa | Agent | ❌ | 并行派发子 Agent 执行独立任务(支持类型:map/review/plan/execute);直接后台执行,立即返回 {"task_id": "sa-xxx"} JSON,完成后结果自动插入对话(或由 subagent_opt 管理)。后台 subagent 仅主 Agent 可派发;在主 Agent 所有运行模式(空/简单/标准)与所有 preset(standard/minimal/code)下均可用,不被屏蔽 |
subagent_opt |
so | Agent | ❌ | 按 task_id 操作后台 subagent 任务(subagent 直接后台启动):read(读取当前状态与已产生的结果,立即返回)/ wait(等待完成取结果,timeout 秒,默认 300/0 无限)/ kill(取消后台 subagent 任务)/ wait_all(等待所有后台 subagent 任务完成,返回每个任务结果的 JSON 数组,无需 task_id)/ list(列出当前所有 agent 的 agent 类型与 task_id,无需 task_id,含主 Agent;返回 {"count": N, "agents": [{task_id, agent_type, description, status}, ...]})/ release(释放调用方自己持有的文件沙盒锁)。仅主 Agent 可用;在主 Agent 所有运行模式与所有 preset 下均可用,不被屏蔽 |
skill |
sk | 技能 | ✅ | 加载技能(skill)的完整指令(技能目录随系统提示词注入,任务与技能匹配或点名技能时调用) |
工具分类
| 分类 | 工具 | 说明 |
|---|---|---|
| 文件 IO | read, write, edit, ls, cp, mv, rm, mkdir, read_image | 读写文件、目录操作、文件管理、图像读取 |
| 代码搜索 | grep, glob | 正则搜索源码、通配符查找文件 |
| 命令执行 | bash, bash_opt | 安全沙盒中执行 shell 命令;按 task_id 操作后台 bash 任务(bash 后台任务注册在 bash 专用表 _background_tasks),含读取/等待/终止/终端输入、窗口截图(screenshot,含整屏与多显示器截取)与 GUI 鼠标键盘输入注入(move/hover/click/drag/scroll/key/type/release,支持语义坐标) |
| 网络访问 | web_search, web_fetch | 网页搜索(DeepSeek 官方原生搜索)与网页全文获取 |
| 用户交互 | user_select | 交互式选择弹窗(单选/多选/1 分钟无操作超时回退;options[].description 说明并入选项、选中项多行展开其余折叠单行;支持并发提问,多问题 tab 一起显示;Claude 风格 tab 栏 ← [x] 标题 ... √ 提交 → + > 指针选项 + 选项下方说明/标题元信息/序号数字键快选/Home-End-PgUp-PgDn 导航/两行提示/长列表上下指示/多选 [√]+a 全选 c 清空/自定义输入多行编辑(Shift+Enter/Ctrl+O 换行、光标常显、空输入提示、输入中暂停超时、长内容按光标滚动)/输入 Ctrl+U Ctrl+W 与 ←→↑↓ 光标移动/Submit 检查你的答案 分页与 1-9 跳题、多行答案逐行显示) |
| Agent 调度 | subagent, subagent_opt | 并发派发原子 Agent 执行独立任务;按 task_id 操作后台 subagent 任务(subagent 后台任务注册在独立表 _subagent_tasks,与 bash 后台任务分表隔离) |
| 技能 | skill | 加载可用技能(skill)的完整指令 |
工具设计原则
- 纯异步 — 所有工具均基于
asyncio,不阻塞事件循环 - 沙盒安全 — 文件操作自动备份,支持撤回(undo)
- 元数据系统 — 每工具声明并行安全、网络依赖、超时估计等元数据,供调度层优化
- 双端适配 — 同时支持终端(
display())渲染路径
工具权限系统(v2.2.0+)
不同 SubAgent 类型对工具有不同的访问权限,通过 Func.can_use() 统一检查:
@classmethod
def can_use(cls, tool_name: str, agent_type: str = "execute", path: str | None = None) -> tuple[bool, str | None]:
"""检查指定类型的 agent 能否使用某工具。"""
- agent_type 注入 — SubAgent 在
_handle_tool_calls()中自动注入func.agent_type = self.agent_type - 排除规则 — 定义在
src/core/subagent.py的_TOOL_EXCLUSION_MAP(详见下方 SubAgent 类型表) - 路径白名单 —
FileToolBase._validate_path_and_size()对 plan Agent 实施路径限制,仅允许写入~/.chat/plan/目录,防止误写项目源码 - 主 Agent 委派工具恒可用 —
subagent/subagent_opt在主 Agent 的所有运行模式(空/简单/标准,Ctrl+B 切换)与所有 preset(standard/minimal/code)下均不被屏蔽:空模式过滤(filter_schemas_for_empty_mode)与 preset 过滤(PresetsService.apply_to_agent)都对其豁免,名单单一真源为src/core/agent_types.py::DELEGATION_TOOLS,内置 preset 声明也不再排除它们(SubAgent 类型排除表边界不变)
MCP 外部工具接入(Model Context Protocol)
除 19 个内置工具外,本 CLI 还支持接入外部 MCP 服务器(Model Context Protocol 2025-06-18), 把第三方工具(文件系统、数据库、浏览器、自定义服务……)无缝变成模型可调用的工具。
配置
在 ~/.chat_config/chatrc.json 顶层添加 mcp_servers(列表,默认 []):
{
"mcp_servers": [
{
"name": "filesystem",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"agents": ["execute"],
"timeout": 30
},
{
"name": "remote",
"transport": "http",
"url": "https://example.com/mcp",
"headers": {"Authorization": "Bearer xxx"}
}
]
}
也可用 /config 界面或 CLI 编辑:
python chat.py config set mcp_servers '[{"name":"fs","transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}]'
字段说明
| 字段 | 适用 | 默认 | 说明 |
|---|---|---|---|
name |
必填 | — | 服务器唯一名(工具名前缀 + 状态显示) |
transport |
可选 | stdio |
stdio / http(Streamable HTTP)/ sse(旧式 HTTP+SSE) |
command |
stdio 必填 | — | 可执行文件(如 npx / uvx / python) |
args |
stdio 可选 | [] |
命令行参数 |
env |
stdio 可选 | {} |
追加/覆盖子进程环境变量 |
cwd |
stdio 可选 | 当前目录 | 子进程工作目录 |
url |
http/sse 必填 | — | MCP 端点(仅 http/https) |
headers |
http/sse 可选 | {} |
附加请求头(如 Authorization) |
enabled |
可选 | true |
是否启用(false 时跳过连接) |
agents |
可选 | ["execute"] |
允许使用该服务器工具的 SubAgent 类型(map/review/plan/execute) |
timeout |
可选 | 30 |
单次请求超时(秒,上限 600) |
parallel_safe |
可选 | false |
是否声明并行安全(影响工具 DAG 调度) |
inherit_env |
stdio 可选 | false |
是否把当前进程全部环境变量继承给子进程;默认只透传基础变量白名单(PATH/HOME/temp/LANG 等)+ env,避免凭据类环境变量外泄给第三方 server |
description |
可选 | "" |
人类可读说明(仅展示) |
行为
- 启动连接 —
chat.py启动时(交互 / 单次 / clawbot 模式统一入口)连接全部启用的服务器, 完成initialize握手 →tools/list发现工具 → 以mcp__<server>__<tool>名字注册进工具注册表; 单个服务器连接失败只记 WARNING 并跳过,不阻断应用启动。 - 调用 — 模型调用 MCP 工具的方式与内置工具完全一致(工具卡、轨迹、token 统计、审计日志、
沙盒记录等链路自动生效);结果文本直接回传,图片结果在多模态模型下自动转成
image_urlcontent blocks(非多模态模型只回占位文本)。 - 权限 — MCP 工具默认仅
execute型 Agent 可用(主 Agent + execute SubAgent);map/review/plan只读型 Agent 默认被排除(避免只读审查链路写入外部系统), 可用agents字段按服务器显式放开(如["execute", "review"])。 - 提示词 — 已连接的服务器与工具清单会注入系统提示词(
## MCP 外部工具章节,无 MCP 配置时不注入); 该章节按目标 agent 类型过滤,只读型 SubAgent 不会看到自己被排除的 MCP 工具。 - 关闭 — 进程退出时关闭全部连接(terminate stdio 子进程 / DELETE HTTP 会话)、 注销动态工具与权限策略。
- 零开销 — 未配置
mcp_servers时不建立任何连接、不注册任何工具、不导入 mcp 子系统。
实现结构(src/mcp/)
| 模块 | 职责 |
|---|---|
protocol.py |
JSON-RPC 报文构造/解析、协议版本协商、方法名与头部常量 |
config.py |
mcp_servers 解析与校验(字段清洗、非法条目跳过、同名去重) |
transport.py |
传输层:StdioTransport(子进程)/ HttpTransport(Streamable HTTP)/ SseTransport(旧式 HTTP+SSE) |
client.py |
单服务器客户端:initialize 握手 + tools/list(cursor 分页)+ tools/call,结果归一化 |
tool.py |
MCP 工具 → 动态 Func 子类(名称清洗限长、schema 归一化、图片转 content blocks) |
manager.py |
进程级单例:连接编排、工具注册、调用路由、权限策略、状态与提示词章节 |
光标坐标追踪系统(CursorTracker)
新增于 v2.2.0,全局统一的终端光标坐标追踪基础设施,消除分散在各渲染组件中的坐标推算累积误差。
核心 API
| 方法 | 功能 |
|---|---|
move_to(row, col) |
写 ANSI CUP 序列 + 更新内部坐标 |
move_xy(col, row) |
0-based → 1-based 转换入口 |
set(row, col) |
仅更新内部状态,不写终端 |
record_newlines(n) |
追加 n 行后自动更新行号 + 列号复位 |
record_move_down(n) |
下移 n 行(滚动场景) |
save() / restore(pos) |
检查点模式(返回/恢复 CursorPosition 快照),支持渲染前后坐标范围对比 |
pos → CursorPosition |
获取当前坐标快照 |
集成架构
ChatUIConsumer
└── CursorTracker(唯一实例,构造注入到所有子系统)
├── ContentRenderer → _do_content / _do_tool_output 等 14 种渲染后调用 record_newlines()
├── RenderEngine → _phase_render 记录渲染坐标范围,position_cursor 同步最终光标
├── _BottomBar → force_redraw / sync_bottom_lines / ensure_cursor_* 中 set 光标位置
└── _CompletionPopup → render / render_cycle_update 中 set 弹窗行坐标
设计决策
- 单线程使用 — 仅在 render 线程中操作,无需锁
- 1-based 坐标 — 与终端 ANSI CUP 序列一致
- 轻量无依赖 — 仅标准库,零外部依赖
- 检查点模式 —
save/restore支持嵌套渲染场景的坐标回退
Agent 工作流程
本项目的核心是 Main-Sub Agent 架构,通过 subagent 委派任务给不同类型的子 Agent。
┌──────────────────────────────────────────────────────────────────┐
│ Main Agent │
│ 主控 Agent,负责任务调度(6 步工作流) │
│ │
│ ① 规划 ─→ ② 探底分析 ─→ ③ 修改执行 ─→ ④ 审查 ─→ ⑤ 验证(完成)│
└───────┬───────┬───────┬───────┬───────┘
│ │ │ │
│dispatch│dispatch│dispatch│dispatch
▼ ▼ ▼ ▼
┌─────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐
│ plan │ │ map │ │ review │ │ execute │
│ SubAgent │ │ SubAgent │ │ SubAgent │ │ SubAgent │
│ │ │ │ │ │ │ │
│ 计划型 │ │ 只读分析型 │ │ 代码审查型 │ │ 执行型 │
│ │ │ │ │ │ │ │
│ • 任务拆解 │ │ • 项目探底 │ │ • P0-P3 │ │ • 读/写文件 │
│ • 依赖分析 │ │ • 模块地图 │ │ 分级审查 │ │ • 修改代码 │
│ • 资源估算 │ │ • 调用链 │ │ • 循环审查 │ │ • 创建文件 │
│ • 风险识别 │ │ • 引用关系 │ │ • 阻断策略 │ │ • 测试运行 │
│ • 动态重规划│ │ │ │ │ │ • 执行验证 │
└─────────────┘ └────────────┘ └────────────┘ └──────────────┘
工作流说明
1. 规划 ──→ 委派 plan SubAgent 制定结构化计划(任务拆解、依赖分析、风险评估)
│
2. 探底 ──→ 委派 map SubAgent 获取模块地图 + 调用链分析
│ (只读分析,不修改代码)
│
3. 修改 ──→ 基于探底结果执行代码修改
│ 多个独立目标可并发派发 execute SubAgent
│
4. 审查 ──→ 委派 review SubAgent 逐文件审查
│ P0/P1/P2 阻断修复,P3 纳入记录
│ 最多三轮循环审查
│
5. 验证 ──→ 语法检查 → 构建/编译 → 加测试 → 运行测试 → 运行验证
SubAgent 类型
各类型 SubAgent 通过 _TOOL_EXCLUSION_MAP(定义在 src/core/subagent.py)控制工具可用性。
| 类型 | 可用工具 | 用途 |
|---|---|---|
| plan | 只读分析 + write/edit/mkdir(仅限 ~/.chat/plan/ 目录) |
任务拆解、依赖分析、生成计划文件到 ~/.chat/plan/ |
| map | 只读(read/grep/glob/ls 等只读工具) | 项目探底、模块地图、调用链追踪、引用关系分析 |
| review | 只读 + web_search(无 bash/bash_opt 等任何 shell 执行工具) | Code Review、P0-P3 分级审查、跨文件一致性验证 |
| execute | 全工具(不含 user_select/subagent/subagent_opt/web_search) | 读/写/改代码、执行测试、通用任务 |
工具排除策略(与
src/core/subagent.py的_TOOL_EXCLUSION_MAP一致):execute 排除subagent/subagent_opt/user_select/web_search;map 排除bash/bash_opt/write/edit/rm/mv/cp/mkdir/web_search/subagent/subagent_opt/user_select;review 排除bash/bash_opt/write/edit/rm/mv/cp/mkdir/subagent/subagent_opt/user_select(纯只读审查:仅 read/grep/glob/ls/web_search,无任何 shell 执行能力);plan 排除bash/bash_opt/rm/mv/cp/subagent/subagent_opt/user_select,write/edit/mkdir 仅限~/.chat/plan/目录。subagent_opt与后台 subagent 均仅主 Agent 独有:SubAgent 工具白名单全类型排除 + 工具运行时isinstance(agent, SubAgent)双保险。SubAgent 在_handle_tool_calls()中注入agent_type到 Func 实例,Func.can_use()进行统一检查。FileToolBase._validate_path_and_size()额外实施 plan Agent 路径白名单校验。
并发调度策略
多个独立分析/审查任务同时触发时,同轮并发派发多个 SubAgent(如同时分析多个模块、同时审查多个文件),互不阻塞,缩短总执行时间。
通用浮动窗口(Floating Windows)
任意组件都能在 TUI 上叠加一个浮动窗口(/loop 进度窗即用此机制实现)。浮窗是绝对定位覆盖层:不占文档高度,关闭后下一帧整帧重建,被覆盖内容原样还原。
层级:src/tui/app/floating.py(规格 / 渲染包装 / 优先级排序)→ src/tui/ink/_floating.py(布局后锚点解析与平移)→ src/tui/ink/components.py(帧末合成 _overlay_floating)。
打开 / 更新 / 关闭(命令层)
from src.tui.app.floating import FloatingWindowSpec, window_hit_test
chat_ui.open_floating_window(FloatingWindowSpec(
id="my-window", # 唯一 id;同 id 重复 open = 替换
render=MyContent, # 函数组件:props = model/window/width/height/geometry
width=30, # 总宽(含边框);None = 内容自适应
x="right", # int / "left" / "center" / "right"
bottom="bottom_area", # 默认:底部框上方一行(向上展开)
priority=100, # 数值大 = 上层
))
chat_ui.update_floating_window("my-window", scroll_top=3) # 不可变替换
chat_ui.close_floating_window("my-window") # False = 窗口不存在
chat_ui.clear_floating_windows() # 关闭全部
规格字段
| 字段 | 默认 | 说明 |
|---|---|---|
id |
必填 | 唯一标识(strip 后非空;空白/重复 id 被拒绝/丢弃) |
render |
None |
内容组件(props={"model","window","width","height","geometry"});hooks 可用 |
priority |
0 |
叠放顺序(升序绘制,高优先级在上) |
width |
30 |
总宽(含边框),钳制到终端宽度;None = 自适应 |
x |
"right" |
左边界列:int / "left" / "center" / "right" |
bottom |
"bottom_area" |
底行锚点:int / "bottom_area" / "input_top" / "input_bottom" / "doc_bottom" / "doc_top" |
top |
None |
顶行锚点(与 bottom 同时给出时优先) |
offset_x / offset_y |
0 |
额外列/行偏移 |
border / border_color / background |
True / 默认深青 / black |
边框与背景;background=None = 透明(只覆盖实际字符列) |
padding_x / padding_y / title |
1 / 0 / "" |
内边距与可选标题行 |
max_height |
None |
可见高度上限;超出部分裁剪(绝不把窗口下推去盖底部框) |
scroll_top |
0 |
内容滚动偏移(配合 max_height 查看后续内容) |
allow_cover_bottom |
False |
允许覆盖底部框(状态栏/输入区);默认被裁到其上方 |
over_fullscreen |
False |
允许显示在模态全屏视图之上;默认全屏视图下隐藏 |
close_on_escape |
False |
Esc 关闭窗口(on_close 由 bridge 自动注入) |
on_close / idle_static |
None / False |
关闭回调 / 内容只依赖自身 props 时允许空闲帧复用 |
refresh_interval |
None |
时间驱动内容的刷新间隔(秒;None = 每帧刷新,默认)。计时器/进度动画可接受有限帧率时按需声明——空闲态不再因「有浮窗」永久关掉空闲帧复用,由会话到期强制重建一帧。/loop 浮窗不声明(保持每帧刷新) |
锚点语义
bottom_area= 底部框上方一行(bottom_area_top - 1,语义边界)——底行锚定在其上时窗口不覆盖底部框(状态栏 + 输入区 / 模态底部视图)。input_top= 输入区顶部分隔线(CPU/MEM 行)本身——窗口底行落在该行会覆盖它;需要保留分隔线时用bottom_area。- 底行锚点 +
offset_y=-1= 再上移一行;顶行锚点同理。 - 绝对坐标可落在文档任意位置;超出视口上方的内容被裁剪(保留锚定侧),不会把窗口整体下移到可覆盖底部框的位置。
交互
props["geometry"](每帧原地更新):x/y/width/height/content_height/screen_x/screen_y/visible/hidden_reason。screen_*是终端可见坐标。window_hit_test(window, col, row)→ 命中时返回窗口内局部坐标(配合use_mouse_input)。- 键位/焦点由内容组件自行声明:
use_input+useFocus,需要独占键盘时调use_modal(True)。 close_on_escape=True时 Esc 关闭窗口(其余按键原样放行)。
渲染性能
浮窗开启时框架有两条默认生效的优化,另有一个按需启用的刷新选项:
- 单次浮窗收集:
render_frame的定位阶段把本帧浮窗 fiber 列表写入root._float_frame_windows,合成层直接复用——修复前每帧对整棵组件树做两遍相同的 DFS。 - 区域切片合成:
_merge_window_row只处理窗口覆盖的列区间(左/右段按 run 级严格切片直接追加),不再把整行转列键字典 + 全量重建;120 列终端 + 7 行窗口实测合并耗时约降 60%。 - 空闲帧复用(按需):默认浮窗每帧重建(内容不会冻结;
/loop浮窗即如此)。内容只依赖自身 props 时用idle_static=True,时间驱动且可接受有限帧率时用refresh_interval=N——两者都不再阻止空闲帧复用,后者由会话在间隔到期时强制重建一帧。
内置示例:/pet 宠物浮窗
/pet 用本机制实现一个无边框、透明背景的蓝色大肥鱼宠物(干饭鱼娘,
「爱吃大白饭」的娘化萌版,实现见 src/tui/app/pet.py):
- 规格:
border=False/background=None/width=None(内容自适应右侧 40 列浮窗)/refresh_interval=1/30(动画 30fps,空闲态不阻止帧复用); 舞台固定 16 行,宠物不再全屏随机游走,跳跃 3 行; - 内容按行拆成「非空白段」渲染,空白列不写入画布——只显示实际绘制的 行内容,行宽天然可大小不一,底层消息不会被矩形背景抹掉;
- 宠物的姿态由
time.monotonic()纯函数计算:干饭 / 咀嚼 / 打嗝 / 追饭粒 / 吃撑躺平 / 跳舞 / 漫步 / 嗅 tok / 吃 tok / 开心跑 / 探头 / 伸懒腰 / 讨饭 / 点头,以及上下浮动、眨眼、跳跃、左右摇摆、冲刺掉头、转圈、唱歌、单眼 眨眼、睡觉,共 22 种动作;端着白饭碗、冒热气、掉饭粒; - 台词池 36 条通用台词 + 每个动作的专属台词(干饭、撒娇、沙雕、治愈混合), 每 7 秒冒泡 3 秒;
- 「吃 tok」动作会在浮窗层生成一排
tok小吃,逐个吃掉并留下残影/饭粒; 纯视觉动画,不修改真实 token 统计; - 启动欢迎页等空间不足时自动从舞台底部保留身体、表情与饭碗,隐藏会被 裁掉的气泡;聊天内容变多、空间恢复后自动回到完整 16 行;
- 与
/loop同时打开时,循环浮窗自动让到左侧,宠物保留右侧,两者不互相 遮挡;宠物关闭后循环浮窗恢复右侧; /pet为开关切换(已显示时再按一次收回),/pet off显式收回;不占用 Esc(Esc 保持中断 / 清空输入语义)。
已知限制
- 浮窗覆盖到跨列宽字符(CJK/emoji)时,终端无法只覆盖其某一列——相邻列会被清空(透明窗口未被窗口字符覆盖的边界宽字符也按整字丢弃/留白处理)。
- 嵌套浮窗(窗口内容里再声明
dataFloatWindow)不支持,内层会被忽略。 allow_cover_bottom=True且覆盖输入区时,终端光标仍按输入区定位,会落在窗口内容上——非必要不要打开。- 浮窗只在合成层绘制:不进入输出历史(scrollback 记录的是底层消息内容)。
- 调和 / 布局 / 绘制均为显式栈迭代实现(
_reconcile_tree/_measure_gen+_drive_task/_paint_tree),不受 Python 递归深度限制;实际可承载深度仅受内存限制(Fiber._depth_overflow/MAX_TREE_DEPTH保留为防御性状态,默认不触发)。 - 单帧输入处理预算 8ms、命令应用预算 10ms(
src/tui/ink/session.py):超预算的输入字节/命令留到下一帧继续(顺序不变),避免大段粘贴或历史回放把单帧拉长到阻塞键盘。 - 系统监控(CPU/内存)在后台线程采集(
ink-system-monitor),帧内只读缓存;无 psutil 平台的子进程采样(iostat/powershell/sysctl)不再阻塞渲染线程,首次采集前状态栏显示 0。 - 全屏/底部视图默认每帧重建(保守);
ViewSpec.idle_static=True的视图才允许空闲帧复用。TraceView 含实时耗时,声明refresh_interval=1.0(空闲 1Hz 刷新);若新增视图引入时间驱动渲染,必须显式声明idle_static=False或refresh_interval。 - 帧率默认 60Hz,可用
render(maxFps=...)/TuiConfig(render_interval=...)配置;TuiConfig.idle_reduce_rate=True时静态态按idle_render_interval(默认 10Hz)降频。渲染循环不再 1ms 忙等;空闲无变化帧不重复写光标/终端。
目录结构
├── chat.py # 入口脚本(asyncio.run(main()))
├── pyproject.toml # 项目配置与依赖
├── prompts/ # 系统提示词(8 个文件)
│ ├── prompts_export_main.md # 主 Agent 系统提示词(标准模式:子代理编排范式)
│ ├── prompts_export_main_simple.md # 主 Agent 系统提示词(简单模式:命令式精简规则集)
│ ├── prompts_export_main_empty.md # 主 Agent 系统提示词(空模式:单体完整规则集;已去重并加入正向授权判据与分级交付;「空」指不含子代理编排)
│ ├── prompts_export_map.md # map SubAgent 探底提示词
│ ├── prompts_export_plan.md # plan SubAgent 计划提示词
│ ├── prompts_export_execute.md # execute SubAgent 提示词
│ ├── prompts_export_review.md # review SubAgent 审查提示词
│ ├── prompts_loop_prompt.md # /loop 续跑提词 LLM 的系统提词(每次构建热加载)
├── tests/ # 测试(按被测模块分组)
│ ├── renderer/ # Markdown/ANSI 解析与渲染、流式渲染
│ ├── tui/ # 终端界面(含 ink/ 框架用例)
│ ├── tools/ # 工具与平台后端(bash/window/screenshot/文件/Web)
│ ├── api/ # HTTP 适配器、多模态、流式生命周期
│ ├── core/ # 核心域(Agent/会话/压缩/上下文/沙盒/工具调度)
│ ├── kernel/ # 内核、清单、插件条目、架构守卫
│ ├── integrations/ # 外部集成(MCP / ClawBot / Skills)
│ ├── _paths.py # 与文件层级无关的仓库根定位(新增用例统一使用)
│ └── conftest.py # 全局夹具(事件循环兜底 / 覆盖率模式跳过时间预算用例)
├── ~/.chat/ # 运行时数据目录(用户主目录,首次写入时自动创建;跨项目共用)
│ ├── memory/ # 跨对话记忆系统(索引 + 详情)
│ ├── plan/ # Plan Agent 计划文件
│ └── msg_list/ # 会话消息存储(JSON 格式)
│
├── src/ # 核心源码
│ ├── app.py # 入口 re-export
│ ├── app_init/ # 应用初始化(参数解析、模式选择)
│ ├── app_loop/ # 交互式/单次模式主循环
│ ├── application.py # 应用层编排(Application、AppMode)
│ ├── chat_msgs.py # 对话消息存/取/列/导出
│ ├── checkpoint.py # 任务断点保存与恢复
│ ├── paths.py # 路径常量
│ ├── terminal.py # 终端颜色配置(始终启用颜色)
│ ├── _compat.py # Python 版本兼容(dataclass/aclosing/get_event_loop)
│ │
│ ├── api/ # API 适配层
│ │ ├── client_async.py # httpx 异步 HTTP 客户端
│ │ ├── model_async.py # 模型调用入口 + 重试
│ │ ├── interrupt_async.py # 全局中断信号
│ │ ├── stream/ # 流式输出处理(含推理/工具调用/速度)
│ │ ├── stream_parse.py # 流式工具调用解析
│ │ ├── tokens.py # Token 启发式估算
│ │ ├── stats.py # 会话级 Token 统计
│ │ ├── json_repair.py # JSON 格式自动修复
│ │ ├── protocols.py # LLM 协议定义
│ │ ├── telemetry.py # API 层可观测性
│ │ ├── escape_monitor.py # 键盘输入监听
│ │ ├── events.py # API 事件定义
│ │ ├── _sync_bridge.py / _stats_core.py / _stream_lifecycle.py / _token_speed.py / _tool_parse_utils.py # 内部辅助模块
│ │ ├── multimodal.py # 多模态模型判定(用户消息图片)+ 图片 content blocks 构造
│ │ ├── adapters/ # 多模型适配器(DeepSeek/OpenAI/Anthropic/Ollama)
│ │ └── _adapter_manager.py # 适配器管理
│ │
│ ├── config/ # 配置系统
│ │ ├── loader.py # 配置加载/持久化(~/.chat_config/chatrc.json)
│ │ ├── defaults.py # 默认配置 + Provider 定义
│ │ └── schema.py # 配置校验
│ │
│ ├── core/ # 核心业务逻辑
│ │ ├── agent.py # Agent 对话代理(Pipeline 驱动)
│ │ ├── base_agent.py # Agent 基类(消息管理、沙盒上下文)
│ │ ├── agent_di.py # Agent 依赖注入工厂
│ │ ├── agent_builder.py # Agent 构建器
│ │ ├── session.py # ChatSession 纯领域会话对象(状态机驱动)
│ │ ├── state_machine.py # 会话状态机(INIT→IDLE→RUNNING→COMPLETED/INTERRUPTED)
│ │ ├── subagent.py # SubAgent 子代理(含 _TOOL_EXCLUSION_MAP 工具权限策略)
│ │ ├── pipeline.py # Pipeline 中间件管道(Model-Execute 循环编排)
│ │ ├── compaction/ # dsh 同款上下文压缩(config/region/checkpoint/pruner/summarizer/engine)
│ │ ├── compression.py # 上下文压缩(策略模式,回退链)
│ │ ├── context_manager.py # 上下文管理器 + 消息上限控制
│ │ ├── context_selector.py / context_summarizer.py
│ │ ├── message_queue.py # MessageQueue 异步消息队列
│ │ ├── message_edit.py # 消息编辑功能
│ │ ├── file_change_record.py # 文件变更记录
│ │ ├── sandbox_manager.py # 文件沙盒管理器
│ │ ├── parallel_executor.py # ParallelExecutor 并行 SubAgent 调度
│ │ ├── tool_executor_async.py # AsyncToolExecutor 异步工具执行器
│ │ ├── tool_dag.py # 工具 DAG 调度
│ │ ├── cache.py # 增量统计缓存
│ │ ├── constants.py # 主题常量
│ │ ├── commands/ # 命令系统(base / _ui_adapter / plugins/)
│ │ ├── exceptions.py # 异常定义
│ │ ├── internal/ # 内部实现子模块
│ │ │ ├── agent/ # Agent 内部(spawner / callbacks / capture)
│ │ │ ├── shared/ # 共享工具(sandbox_history / stats_cache)
│ │ │ ├── session/ # 会话内部(persistence / messages)
│ │ │ └── commands/ # 命令内部(_command_core / _config_cmd / _data_cmd / _session_cmd)
│ │ ├── events/ # 核心事件总线 + 事件类型
│ │ ├── middleware/ # Pipeline 中间件(审计/中断/状态机/可观测性/工具适配器)
│ │ ├── ports/ # 六边形架构端口定义(8 个端口)
│ │ └── telemetry/ # 可观测性(指标/追踪/上下文传播)
│ │
│ ├── tui/ # 终端 UI 聊天渲染引擎(替代 chat_ui/)
│ │ ├── _assembly.py / _assembly_steps.py / _base_display.py / _completion.py / _completion_engine.py
│ │ ├── _config.py / _const.py / _consumer.py / _diff_renderer.py / _dispatcher.py / _format.py
│ │ ├── _input.py / _input_io.py / _input_parser.py / _input_buffer.py / _input_dispatcher.py
│ │ ├── _input_layout.py / _input_metrics.py / _input_orchestrator.py / _ink_bridge.py / _lifecycle.py
│ │ ├── _screen.py / _snapshot.py / _stdout_tracker.py / _subagent_panel.py / _subagent_render.py
│ │ ├── _subagent_state.py / _tool_icons.py / _width.py / input.py / _history_disk.py / _system_monitor.py
│ │ ├── app/ # AppModel + apply_cmd + 组件树(input_area/status_bar/toolcard/...)
│ │ ├── consumer/ # ChatUIConsumer 事件消费者 + 渲染入口
│ │ ├── core/ # 核心工具(color/style/singleton/_fx/_theme)
│ │ ├── events/ # UI 事件总线 + DisplayEvent 类型定义
│ │ ├── ink/ # React Ink 风格组件框架(调和器/flexbox/hooks/渲染器)
│ │ ├── pipeline/ # 消息编辑/显示管道
│ │ ├── state/ # 消费/注册表状态管理
│ │ └── subagent/ # SubAgent 面板子域聚合门面
│ │
│ ├── renderer/ # 增量流式 Markdown 渲染引擎
│ │ ├── engine.py # RenderEngine 渲染引擎
│ │ ├── pipeline.py # TokenPipeline 过滤器链
│ │ ├── recursive_parser.py # 递归下降解析器
│ │ ├── types.py # Token/TokenType/RenderContext 类型
│ │ ├── states.py # 渲染状态
│ │ ├── factory.py # 渲染器工厂
│ │ ├── protocols.py # 渲染协议
│ │ ├── output.py # OutputAdapter 输出适配器
│ │ ├── indicator.py # 流式指示器
│ │ ├── ast/ # AST 构建→扁平化→优化→渲染
│ │ ├── handlers/ # 块级元素处理器(code/table/mermaid/math/admonition 等)
│ │ ├── targets/ # 渲染目标抽象(RenderTarget / CompositeRenderTarget)
│ │ │ ├── __init__.py
│ │ │ └── base.py
│ │ │
│ │ ├── pipeline_filters/ # 流式优化过滤器
│ │ ├── math_symbols/ # 数学符号定义
│ │ ├── _rendering/ # 内部渲染辅助
│ │ └── _utils/ # 内部工具函数
│ │
│ ├── tools/ # 工具调用系统(19 个内置工具)
│ │ ├── base.py # Func 基类 + 元数据系统(含 can_use 工具可用性检查 / agent_type)
│ │ ├── file_base.py # FileToolBase 文件操作基类(含 plan agent 路径白名单)
│ │ ├── registry.py # 工具注册表(自动发现 + 调度 + 元数据索引)
│ │ ├── read.py / write.py / edit.py / read_image.py
│ │ ├── grep.py / glob.py / ls.py
│ │ ├── bash.py / cp.py / mv.py / rm.py / mkdir.py / skill_tool.py
│ │ ├── web_search.py / web_fetch.py / user_select.py / subagent.py / subagent_opt.py
│ │ ├── file_ops.py # 文件操作原子工具(原子写入、路径安全校验、沙盒记录)
│ │ ├── _constants.py # 共享常量(排除目录、安全路径、编码等)
│ │ ├── encoding.py # 编码检测工具函数
│ │ ├── utils.py # 工具通用辅助函数
│ │ ├── search_providers.py # DeepSeek 官方原生搜索提供者(web_search 依赖)
│ │ └── page_fetcher.py # 网页内容抓取(web_fetch 依赖)
│ │
│ ├── prompt_builder/ # 系统提示词构建
│ ├── mcp/ # MCP 外部工具接入(stdio / Streamable HTTP / 旧式 SSE)
│ ├── notifications/ # 桌面通知(Termux/Linux/Windows)
│ └── observability/ # 可观测性门面(聚合指标/追踪/遥测日志)
插件内核(一切皆插件)
chat.py 的启动是最薄组合根:解析参数 → 构建内核插件树 → ctx.app.run → 卸载内核。
其余一切——工具、工具元数据、工具运行期常量、事件类型(核心事件类型/显示事件类型/
会话·Agent·能力三事件域)、命名样式、命令、渲染 handler/filter/target、
Agent 类型与中间件、流式处理器、LLM 模型 provider、
通知后端、上下文策略、MCP 传输、工具引擎、事件消费者、UI 视图、Web 提供者、主题、
技能来源、会话投影、全局禁用工具策略、Preset、提示词运行模式/来源/系统提词片段、
ClawBot 远程指令、
CLI 顶层子命令、TUI 键位绑定与特殊键处理器、工具表现(类别/图标/Agent 类型标签)、
语法高亮语言、表现层数据表(Emoji/上下标/HTML 配色/列表符号/轨迹样式/模式文本/
工具显示名/告示块样式/Spinner 帧/配置项说明与选项/轨迹种类顺序与块映射/角色图标/
边框样式表/运行期默认值——计费单价、指标百分位、UI 默认参数、语义色槽位、渐变与
呼吸动效参数、Shell/终端检测表、HTTP 错误提示、Badge 对比色度量、Kitty 键盘协议表、
嵌套列表符号、Diff 样式表、轨迹样式表、模型名称匹配模式表)、
内核 host 组件、补全提供者、状态栏段、运行时数据服务与能力接缝、
运行时不变量检查——都是清单(Profile/Bundle/Patch)中的
独立插件条目,可被 ~/.chat_config/cordis.patch.yml、--patch 或用户 Profile
目录按 id 覆盖配置、禁用或替换。
内核模型(src/kernel/)
| 概念 | 说明 |
|---|---|
Kernel |
无特权内核:服务容器 + Fiber 生命周期 + 依赖驱动加载(settle) |
Context (ctx) |
服务容器与可逆副作用注册点;provide/consume/on/effect/plugin;空间可组合性 extend/isolate/intercept |
Service |
插件向其它插件提供能力的基类(占据稳定的 ctx.<key>) |
Fiber |
插件生命周期状态机(PENDING→LOADING→ACTIVE / FAILED / DISPOSED),支持 restart/disable/enable |
EventBus |
五种分发模式:emit / waterfall / parallel / serial / bail |
Scope |
按 key 划分的作用域注册原语(同一进程多 Agent/会话互不污染) |
ConfigTree |
Profile / Bundle / Patch 三层组装;Overlay 提供 --patch / 用户补丁叠加 |
loader |
目录扫描、模块提取、dsh.plugins entry-points 发现(源码直编,热重载确定性) |
diagnostics |
依赖诊断(dependency_report / why_blocked / service_providers / kernel_stats) |
watch |
插件文件热重载监听(mtime 轮询 → 自动 reload_file) |
运行时管理(ctx.kernel_admin)
| 能力 | 说明 |
|---|---|
| 启用 / 禁用 | await admin.disable(name) / await admin.enable(name)(可逆,撤销全部注册并提供重新启用) |
| 重载 | await admin.reload(name) / await admin.reload_file(path) |
| 热重载监听 | admin.watch_file(path) + await admin.start_watching(interval) |
| 依赖诊断 | admin.plugins() / admin.why_blocked(name) / admin.stats() / admin.diagnose() |
组合根支持 --dump-config 打印最终插件树、--check-invariants 运行时不变量自检;
python chat.py plugin list/add/remove 管理外部插件(~/.chat_config/plugins),
/plugin 界面总览当前内核已加载的插件(运行时 Fiber)。
六边形架构(Ports & Adapters)
核心层通过 8 个端口接口 访问基础设施,实现依赖倒置——核心层不直接依赖 api、tui、chat_msgs 等具体实现模块,基础设施层通过适配器模式实现这些端口。
| 端口 | 文件 | 说明 |
|---|---|---|
ConfigPort |
ports/config.py |
配置管理(读取/写入/默认值) |
AsyncModelPort |
ports/model.py |
异步模型调用(LLM API)+ ModelResult |
PersistencePort |
ports/persistence.py |
会话持久化(JSON 文件存储) |
CheckpointPort |
ports/persistence.py |
任务断点保存与恢复 |
EventPort |
ports/events.py |
事件总线发布/订阅 |
InterruptPort |
ports/interrupt.py |
中断信号检查 |
ObservabilityPort |
ports/observability.py |
可观测性(指标/追踪) |
ModelResult |
ports/model.py |
模型调用结果数据类(input/output tokens / tool_calls) |
设计原则:所有端口均为 Protocol 或抽象基类,核心层仅依赖端口接口,不感知具体实现。测试时可通过 Mock 适配器替换基础设施,实现核心逻辑的独立单元测试。
事件系统
核心事件总线(src/core/events/)
通用事件发布/订阅系统,支持通配符订阅和优先级排序。定义 16 种事件类型:
| 事件常量 | 事件类型字符串 | 说明 |
|---|---|---|
MODEL_CALL_STARTED |
model.call.started |
模型调用开始 |
MODEL_CALL_COMPLETED |
model.call.completed |
模型调用完成 |
MODEL_CALL_FAILED |
model.call.failed |
模型调用失败 |
MODEL_STREAM_CHUNK |
model.stream.chunk |
流式内容块 |
TOOL_CALL_STARTED |
tool.call.started |
工具调用开始 |
TOOL_CALL_COMPLETED |
tool.call.completed |
工具调用完成 |
TOOL_CALL_FAILED |
tool.call.failed |
工具调用失败 |
SESSION_STARTED |
session.started |
会话开始 |
SESSION_COMPLETED |
session.completed |
会话完成 |
SESSION_INTERRUPTED |
session.interrupted |
会话中断 |
SESSION_SAVED |
session.saved |
会话保存 |
CONTEXT_COMPRESSED |
context.compressed |
上下文压缩完成 |
CONTEXT_COMPRESS_FAILED |
context.compress.failed |
上下文压缩失败 |
CONFIG_CHANGED |
config.changed |
配置变更 |
APP_BOOTSTRAP |
app.bootstrap |
应用启动 |
APP_SHUTDOWN |
app.shutdown |
应用关闭 |
特性:通配符订阅(如 model.* 匹配所有模型事件)、优先级排序(EventPriority 枚举,LOWEST→HIGHEST)、不可变事件数据类(frozen dataclass)。
UI 事件总线(src/tui/events/)
显示层事件系统,定义 25 种 DisplayEvent 类型(生命周期/工具调用/Agent 状态/模型阶段/流式内容/附加状态/通用输出/用户交互/上下文压缩),基于 CoreEventBus 底层发布机制实现。其中 CompactionChangedEvent 承载压缩开始/完成/失败状态——TUI 聚合主 Agent 与全部 SubAgent 后在模式行行首显示 compact · N,并在完成/失败时输出通知。DisplayEventBus 对 DisplayEvent 子类提供类型安全包装,与核心事件(字符串类型)并行独立运作,确保终端共享相同的事件语义。
Pipeline 中间件管道
Pipeline 将 Agent 对话循环编排为可插拔中间件链。中间件按注册顺序依次执行,每个钩子可拦截/增强/跳过特定阶段。
中间件列表(5 个)
| 中间件 | 文件 | 功能 |
|---|---|---|
_InterruptCheckMiddleware |
middleware/interrupt.py |
模型调用前检查中断信号 |
_AsyncObservabilityMiddleware |
middleware/observability.py |
指标采集 + 调用链追踪 |
_AuditLogMiddleware |
middleware/audit.py |
审计日志记录 |
StateMachineMiddleware |
middleware/state_machine.py |
状态机自动状态转换 |
_ToolRegistryAdapter |
middleware/adapters.py |
工具注册表端口适配器(继承 ToolRegistryPort) |
生命周期钩子(6 个)
| 钩子 | 触发时机 |
|---|---|
before_model_call |
模型调用之前 |
after_model_call |
模型调用之后 |
before_tool_execution |
工具执行之前 |
after_tool_execution |
工具执行之后 |
on_round_complete |
一轮对话完成 |
on_exception |
异常发生时 |
版本控制
- 分支:
main - 当前版本:
v2.2.0 - 仓库: Git 管理,
.gitignore排除__pycache__/、*.pyc、虚拟环境及运行时数据
能力现状与路线
本仓库的变更历史由 git 提交记录承载(提交信息含动机与验证结论);本节只描述 当前能力与尚未实现的方向,不再逐批罗列已完成的实现细节。
已具备的能力(摘要)
| 领域 | 能力 |
|---|---|
| 渲染 | 增量流式 Markdown(CommonMark / GFM 主体 + Pandoc 扩展,含行内代码属性 / 独立属性块 / 定义列表(块级正文)/ 脚注 / 表格表注 / 自动编号列表(#.)/ 定义标记 ~)、LaTeX 公式终端排版、Mermaid 17 类图 ASCII 渲染(流程图 / 时序 / 类 / 状态 / 甘特 / 饼图 / ER / Git / 思维导图 / 时间线 / 旅程 / 数据包位域 / 块图 / 象限 / 需求 / XY 图表 / 桑基,支持 %% 注释)、HTML 块与行内元素(datalist / hgroup / map / slot / ruby / strike 等,含行内背景色)、Front Matter、代码高亮与行号、TOC、Diff 高亮;自绘 ANSI 渲染路径与共享解析层 |
| TUI | React Ink 风格自研框架(调和器 / flexbox / hooks / 帧差异渲染 / 标准控件库)、默认 60Hz 渲染与输入处理(render(maxFps=...) / TuiConfig 可配置;可选空闲自适应降频)、行级增量与 committed 前缀复用、全屏视图族(轨迹 / 日志 / 配置 / 插件 / 模型 / 文件沙盒 / 变更审查 / MCP / 技能 / 用量 / 搜索 / 键位 / 通知 / 导出 / 命令面板)、模态与底部视图机制、vim 风格导航与搜索、模糊命令面板与工作区状态段、8 套配色主题 |
| Agent | Pipeline 中间件链、上下文自动压缩(dsh 同款)、工具调用 DAG 并行调度(显式引用 / 路径重叠 / user_select 独占 / 类别约束四层依赖 + Kahn 分层)、SubAgent 并发派发(plan / map / review / execute)、会话日志与投影、断点与恢复 |
| 内核 | 无特权插件内核(Fiber 生命周期 / 服务容器 / 五模式事件分发 / 作用域与拦截)、Profile / Bundle / Patch 三层组装、热重载与依赖诊断、运行时不变量自检 |
| 能力接缝 | 六边形端口-适配器(配置 / 模型 / 持久化 / 事件 / 中断 / 可观测性 / 工具注册表)、三段式 seam(ctx.fs / shell / subprocess / terminals / jobs / sandbox,Provider 可整体替换) |
| 工具 | bash / bash_opt(后台任务与 GUI 操作:截图、鼠标键盘输入)、文件读写与检索、Web 搜索与抓取、MCP 外部工具、技能、SubAgent 调度 |
| 工程 | 全量测试 + 覆盖率门槛(pyproject.toml)、ruff(F/E9 阻塞,src 与 tests 零缺陷)/ mypy 基线、CI(3.9 与 3.13 双版本)、pre-commit、依赖锁定与打包元数据守卫、架构分层与无环守卫测试、静态检查卫生守卫(tests/test_lint_hygiene.py,ruff 缺失时回退 pyflakes) |
尚未实现的方向
Agent 并行度
| 改进项 | 现状 | 目标 |
|---|---|---|
| 工具调用并行 | 已实现独立的工具调用 DAG(无依赖的工具并行执行) | 动态扩缩容与优先级队列 |
| SubAgent 并发 | 已支持同轮批量并发派发 | 可复用 Worker 池,减少派发冷启动 |
| 流水线并行 | 各阶段等待完整输出 | 前序 Agent 输出流式送入后续 Agent |
| 资源感知调度 | 固定并发上限 | 按 CPU / 内存 / I/O 负载动态调整 |
| 分布式执行 | 单机 | 派发到远程计算节点,跨会话共享工作池 |
其他
- 渲染层:
src/renderer的解析层与 ANSI 渲染层仍有各自实现的块渲染逻辑,可继续把纯逻辑下沉为共享模块。 - 类型收窄:剩余 mypy 错误集中在动态属性与联合类型分支,需逐一收窄或显式标注。
- 巨型组件:全屏视图已统一复用骨架(
_inspector_pane检查器状态与导航 /_keymap_pane帮助面板 /_modal_view模态框架 /_view_common分隔线与搜索),并由tests/tui/test_view_skeleton_shared.py守卫;各视图剩余的_handle_*_event承载语义各异的按键分发,不再强行抽取。 - 测试目录:
tests/已按被测模块分组(renderer/tui/tools/api/core/kernel/integrations/);顶层保留跨模块/工程守卫用例(路径深度敏感的用例仍留在顶层,其迁移依赖tests/_paths的深度无关定位,见tests/test_paths_helper.py的存量豁免清单)。 - 静态检查:
src/tests现已零 F 组缺陷(未使用导入 / 未定义名 / 未使用局部变量 / 无效全局声明),并由tests/test_lint_hygiene.py在测试套件内守卫(本地优先 ruff、缺失时回退 pyflakes;后者不识别# noqa且更严格,故需要「副作用导入」处统一用importlib.import_module("…")表达,不保留# noqa: F401一类抑制)。
技能系统(Skills)
参照 DeepSeek Harness 的 dsh-skill 设计实现的可复用指令技能系统。技能是一组可复用的任务专用指令(Markdown + YAML frontmatter),模型可在执行任务前按需加载。
存放位置(仅 ./.skills)
技能只存放在项目的 ./.skills 目录(自动定位到 git 根,子目录运行同样生效):
<项目根>/
├── .skills/
│ ├── code-review/
│ │ └── SKILL.md # 目录包技能(可携带相对资源)
│ ├── summarize.md # 扁平技能
│ └── installed/ # GitHub 安装的技能(/skill install)
│ └── owner__repo/
│ └── <技能>/
└── .git/
技能文件格式(与 Claude Skills / DSH 相同):
---
name: code-review # 必填,kebab-case
description: 代码审查指南 # 必填,一句话描述(模型目录用)
whenToUse: 用户要求审查代码时 # 可选,路由提示
disable-model-invocation: false # 可选,禁止模型调用
user-invocable: true # 可选,允许 /name 手势调用
metadata: # 可选,任意附加元数据
author: someone
---
# 技能正文(Markdown 指令)
调用方式
- 模型自动加载(所有 Agent 可用) — 技能目录(名称 + 描述摘要)随系统提示词注入,位置在环境信息之后,构建时只注入一次(不随对话轮次重复注入);主 Agent 与 map/review/plan/execute SubAgent 的系统提示词均会注入,每个 Agent 都能使用技能。模型判断任务匹配后调用
skill工具加载完整指令(返回<skill_content>块)。技能变更后(/skill install/update/remove/refresh)系统提示词自动重建,技能章节随之更新。 - 无条件自动加载(
skills.auto_load) — 配置的技能正文直接注入系统提示词(「已自动加载的技能」小节,<skill_content>块),模型无需调用工具即可遵循。适合高频必用技能,注意正文常驻上下文:
{
"skills": {
"enabled": true,
"auto_load": ["pdf", "docx"],
"catalog_description_max_length": 500
}
}
- 用户
/name手势 — 消息中以词边界输入/code-review即直接加载该技能(仅user-invocable技能),正文以<skill_content>user 消息注入会话。路径(/usr/bin)、分数(5/8)、URL 不会误匹配。 /skill命令 — 管理技能:/skill list(含 installed)//skill info <名>//skill refresh(技能变更后自动重建系统提示词)。
从 GitHub 安装技能
/skill install owner/repo # 默认分支
/skill install owner/repo@main # 指定分支/标签
/skill install https://github.com/a/b/tree/dev
/skill update owner/repo # 更新(沿用原 ref)
/skill remove owner/repo # 卸载(或 owner__repo / 技能名)
/skill list installed # 查看已安装
安装实现:通过 codeload 下载 tarball(httpx 流式,30MB 上限)→ 安全解压(拒绝路径穿越/符号链接/设备文件,60MB 解压上限)→ 识别技能根(skills/ 目录 > 根目录 SKILL.md > 技能集合)→ 校验至少一个合法技能 → 原子替换到 ./.skills/installed/<owner>__<repo>/,并记录 .skill-source.json 元数据(owner/repo/ref/commit/时间)。同名技能项目级(rank 100)优先于已安装(rank 200)。
⚠️ 技能内容按受信任本地内容处理(原样注入),仅从可信仓库安装。
优先级与配置
- 同名技能:项目
.skills(rank 100)> GitHub 安装(rank 200)> 运行时注册(rank 250)。 - 配置(
~/.chat_config/chatrc.json):
{
"skills": {
"enabled": true,
"catalog_description_max_length": 500
}
}
实现结构(src/skills/)
| 模块 | 职责 |
|---|---|
models.py |
数据结构、kebab-case 校验、调用策略(InvocationPolicy) |
frontmatter.py |
YAML frontmatter 解析(零依赖内置解析器,PyYAML 存在时优先) |
discovery.py |
技能根扫描(目录包 / 扁平 Markdown / 单技能根) |
registry.py |
注册表:多根合并、rank 裁决、mtime 缓存、运行时注册 |
render.py |
<skill_content> 规范渲染(工具结果与手势注入同形) |
prompt_section.py |
系统提示词技能章节(环境信息之后注入一次,主 Agent 与 SubAgent 均注入) |
gestures.py |
/name 手势扫描与正文注入 |
github.py |
GitHub 安装/更新/卸载(spec 解析 + tarball 安全解压) |
src/tools/skill_tool.py |
skill 工具(模型加载入口,自动发现注册) |
src/core/commands/plugins/skill_plugin.py |
/skill 命令(变更后重建系统提示词) |
src/prompt_builder/builder.py |
_build_prompt(include_skills=True) 在环境信息后追加技能章节 |
No comments yet. Be the first to write one.