ChatCode CLI terminal interface
简体中文 | English
ChatCode CLI TUI
一个美观且实用的 Claude Code 风格 TUI 插件：ChatCode CLI 风格首屏、深灰终端界面、实时工作状态行、思考流式展开、双击 Esc 时间回溯、上下文进度条 + TPS 仪表。
零核心改动，纯插件挂载。安装插件即可启用，卸载后不会留下核心补丁。
献给钟爱tui的各位极客们~
A beautiful, practical Claude Code-style TUI plugin: a ChatCode CLI-style startup screen, charcoal terminal surfaces, a real-time status line, streaming thought expansion, double-Esc time rewind, context progress bar, and TPS gauge.
Zero core changes, pure plugin mounting. Install to enable; uninstall leaves no core patches.
For all TUI-loving geeks~
🎉 官方收录
本插件被 DeepSeek Harness 官方公众号 推文收录，也被 dshfind 插件目录与 GitHub Trending 收录，同时登上了Github Treding日榜第七
核心能力
-
版本更新日志：升级后首次启动展示后台配置的当前版本 Markdown 内容；即使跳过多个版本，也只展示当前版本的一条日志，关闭后同版本不再提示。
-
终端交互：低资源占用，长会话稳定可靠；多种主题切换，样式美观，输入框下方默认显示 ChatCode 平台账号全端今日总 Token 消耗（与 chatcode-cli 同源同逻辑，完整标签为「今日总Toekn消耗 ${token}」）与当前上下文占用，/tokens 的当前上下文百分比与该看板同源，并实时显示工作状态、TPS、缓存命中率等
推理等级、输入/输出 token 与 Git/会话信息；终端卡多行命令可经 /settings 折叠为首行 + 计数提示（Ctrl+O 或点击卡片展开）；全屏模式下悬停在截断的工具卡标题、用户消息或会话标题上约 600ms，浮层显示完整内容。
-
上下文检查：/context 在独立只读页面中按系统提示词、工作区指令、运行时上下文、技能和工具分组展示；←/→ 切换分组，方向键或翻页键滚动，Esc/q 返回会话，不向聊天记录追加报告行。
-
底栏设置：/settings 中的底栏选项即时生效，极简模式也遵循勾选状态；“显示模型”展示当前模型名称。底栏和设置面板不提供花费估算。
-
模型配置：/model 打开后直接平铺全部可用模型，主行显示真实模型名称，供应商作为次级信息；产品目录不展示原生 deepseek-official 模型。模型切换沿用当前会话 ID 和完整历史，不创建同名副本；CLI 与 Web 共用 ~/.chatcode-cli/model.json，任一端保存后由另一端在重启时读取。/model-config 与 Web 原生模型页共用 <CHATCODE_CLI_HOME>/cordis.patch.yml 中的 llm-pi-ai.providers 配置，可新增、编辑、真实测试和删除自定义模型；密钥通过凭据服务保存到同目录的 .credentials.yaml，配置只保存 apiKeyEnv 引用，不再读取 settings.json.customModels，同时显示 CodingPlan 内置模型和只读元景模型；仅在配置服务支持切换时显示“元景”开关，新版目录型服务直接展示已启用模型。保存后本端立即生效，另一端在文件监听稳定后更新；重新打开模型列表可查看变化，无需重启。当前项行尾标记 [当前]。同供应商下的模型共用协议、地址和密钥；删除模型保留可能被其他配置引用的凭据。旧 JSON 配置不自动迁移，请通过模型配置界面重新录入。
-
本地开发启动：在本仓库中执行 pnpm cco 会回落到 PATH 中的全局 cco，不会加载当前 worktree。使用 pnpm dev:copy-config 复制 settings.json / settings.yaml / 凭据到隔离的开发目录，再执行 pnpm dev 构建、安装并启动当前 worktree。
-
功能全面：/resume 按工作目录分类浏览、搜索与预览历史会话（左键恢复、右键弹出操作菜单；可固定常用会话——「已固定」分组置顶显示，行内 ★ 或 Ctrl+P 切换，持久化到 ~/.chatcode-cli/tui；也可搜索 /tag 写入的本地标签），另有 /agentview 会话总览（CC 同款 agent view：空输入 ← 一键后台化，后台会话派发/预览/回复/停止一站式管理）、/clear（新会话）、/clean（清视图）、/compact、/export、/btw，以及 /copy [N]（复制最近回复或代码块）、/diff（查看暂存/未暂存/未跟踪改动）、/memory（编辑 Harness 发现的用户级与工作区 AGENTS.md；macOS 未配置编辑器时使用系统 nano）、/files（列出真正加载进模型上下文的指令文件）、/version（查看当前运行版本）、/statusline（直达底栏设置）、（本月本地 Git 作者 churn 占比，不推断 AI 采纳率）、/（复用 ）、（复用并增强 ）、（直达快捷键设置）、（复用 DSH 与 sandbox preset）、（兼容 、），以及 （读取官方全日志统计投影）、（会话标签）、（通过官方 Agent Presets 名册管理用户预设），以及 、、、、、 六个由当前 Harness agent 执行的受约束工作流（兼容 、、）；模型热切换，原生subagent，会话fork，自动更新，输入框 vim 编辑模式、鼠标选区编辑（拖选高亮、Shift+click 扩展、双击选词、Ctrl+C 复制选区）与全屏草稿编辑（ 或输入行 按钮：行号 + 当前行高亮、Enter 换行、Ctrl+Enter 发送、滚轮滚动、点击/拖选，长草稿独占整屏； 可关）；可在vs code中，已上架 VS Code Marketplace。
当前模型与模型配置分别同步：进程启动时读取一次 model.json 并生成本端缓存，之后新建或恢复会话都采用该缓存；另一端改变选择后必须重启进程，刷新 Web 页面不会采用新选择。切换模型等待跨进程写锁与原子保存完成才确认成功，失败保留原模型；重选当前模型仍保存。成功显示绿色“已切换至「模型名称」”，开始界面同步更新名称，但不清屏或滚到顶部。
macOS 下使用 sudo / su 导致终端标识缺失时，TUI 跳过可能漏出 p 的终端状态探测；已识别的兼容终端保留自动恢复能力。
界面预览
快速开始
前置条件：安装 Node.js。ChatCode CLI TUI 使用 ChatCode 提供的模型；DeepSeek 模型和 Provider 标识按原协议保留。
安装命令：
npm install -g @chatcode/chatcode-cli
启动命令：
# 默认启动 TUI
chatcode-cli
# 简写；cco 不带参数只启动 TUI
cco
# 在 TUI 内输入 /web，或从终端直接启动 Web
cco web
TUI 首页会持续显示 Web 启动提示。/web 等同于 /web on：首次启动 Web，服务就绪后打开带认证 token 的链接；已有同一用户目录下的 Web 实例时，验证实例并获取它当前有效的链接，复用原进程打开浏览器。每次执行都会在 CLI 中保留用法和完整访问 URL。/web off 关闭该 Web 服务并等待端口释放，CLI 保持运行；命令补全提供 on|off 中文说明。链接包含访问权限，请勿分享。此功能需要主启动器 3.0.4-rc.2 或更高版本。
首次由当前 TUI 启动的 Web 仍由它管理，退出 TUI 时一并停止。复用在另一个终端通过 cco web 启动的独立实例不会改变其归属，退出 TUI 不会停止它；显式 /web off 会关闭同一用户目录登记的实例。cco web / pnpm cco web 使用相同的复用机制，终端也支持 cco web on|off。现有英文界面可继续通过 /lang en 使用，中文界面的全部内置命令描述已补齐。
首页“版本”与 /version 的 ChatCode CLI 行读取主启动器包版本，与 cco --version 和 Web 构建版本保持一致；/version 另行显示 TUI 插件版本，供插件更新与诊断使用。
设置页、启动及错误提示统一显示 chatcode-cli；内部 dsh-tui 插件 ID、设置 namespace 与旧数据兼容保持不变。首页“AI代码生成占比”显示平台当月统计：加载时显示“加载中”，无提交数据时显示“暂无数据”，查询失败显示“暂不可用”并每 30 秒重试，成功后每 10 分钟刷新；不会把失败或无数据伪装成 0%。
新会话默认使用执行 cco 时的当前目录，不会自动提升到父级 Git 仓库根目录；首页、会话上下文和 @ 文件补全使用同一个目录。显式 workspace/cwd 配置仍可指定其他目录；恢复旧会话会沿用该会话记录的目录。详见工作目录配置。
cco -r 或 chatcode-cli -r 直接继续当前工作目录最近使用的对话；--resume、-c 和 --continue 支持相同行为。空会话、子代理运行及其他目录的会话不会被选中；当前目录没有历史对话时会提示。使用 cco -r <会话ID> 或 --resume=<会话ID> 可指定恢复目标。兼容启动器 dsh-tui/dst 也支持这些参数。
/resume 与 Web 共用会话目录，支持尚未迁移的旧版历史日志。升级后会自动重建历史列表缓存并保留本地分支备注；无法完整读取的会话不会被判为空会话或加入空会话清理。列表默认按当前工作目录筛选，可切换目录查看其他项目的历史。Web 创建并登记的工作区目录会单独显示，含空目录；即使位于当前目录之下，也不会并入当前工作区。共享工作区服务可用时，会话归属、固定及归档状态与 Web 共用；未归属会话单列，归档项默认不显示。/resume 的移除操作会归档而非删除日志，可在 Web 端恢复；未挂载共享工作区服务的独立 TUI 仍沿用本地固定及删除逻辑。
如果你想手动安装，可以使用仓库根目录的 install.sh：
sh install.sh
# 插件维护场景：
chatcode-cli plugin --profile dsh-tui add @chatcode/cco-tui
新用户提示：若 chatcode-cli plugin 安装时报 ERR_PNPM_IGNORED_BUILDS（pnpm ≥11 默认阻止带安装脚本的依赖，如 @google/genai、protobufjs——这些脚本运行时不需要，忽略即可），在 profile 的 pnpm-workspace.yaml 里加入：
allowBuilds:
'@google/genai': false
protobufjs: false
TUI 内 /update 与兼容启动器的 dsh-tui update 会自动写入这份配置，无需手工处理。
更面向零基础的安装流程、profile 叠加机制、源码构建与常见问题见安装与快速开始。
插件扩展与开发指南
想为 ChatCode CLI TUI 做插件/扩展？欢迎加入生态！
接缝稳定性参考
按当前实现成熟度给出的非正式分级，帮助插件作者评估投入；正式状态与兼容性协定以
准入与开发指南为准：
| 分级 | 接缝 |
|---|
| 稳定候选（形态冻结；如有破坏性变更，先在次版本弃用告警再移除） | 六 设置区块 · 八 全屏场景 · 十 托管对话框 · 十一 状态行 · 十二 键盘快捷键 · 十三 条目渲染器 |
| 实验性（仍可能随 dsh-std / 准入规范演进调整） | 九 决策事件 · toast 通知（ctx.tuiToast，新增） |
| 跟随上游（稳定性由 cordis / dsh 官方机制决定） | 一 会话事件 · 二 官方 prompt 槽位 · 三 技能打包 · 四 主题 · 五 system prompt 段 · 七 profile 组合 |
另：@chatcode/cco-tui/test-utils（headless 准入/挂载测试助手）与
@chatcode/cco-tui/api（纯类型入口）为实验性公开面。
文档索引
| 主题 | 内容 |
|---|
| 安装与快速开始 | 前置条件、安装、启动、profile 生命周期、源码开发 |
| 配置参考 | Cordis 覆盖、配置字段、Agent preset、MCP、环境变量 |
| 主题系统 | 内置主题、自动检测、静态 JSON 与 npm 插件主题、校验规则 |
| 交互与命令 | 快捷键、鼠标、问卷、slash command 与会话工作流 |
| 架构与限制 | 运行链路、渲染与持久化设计、安全边界、已知限制 |
| VS Code 使用指南 | 在 VS Code 集成终端运行 dsh-tui；companion 扩展 dsh-tui-vscode 提供与 Claude Code 官方扩展几乎一致的体验（已上架 Marketplace） |
| 贡献与开发约定 | 贡献流程、仓库地图、构建产物、验证矩阵与修改规则 |
| 插件准入与开发指南 | 接口与兼容性协定 / 插件准入规范 / 插件接缝 / 契约 / 验证清单（已并入 dsh-ecosystem-spec） |
完整的中英文索引见 docs/README.md。
社区
微信群二维码约 7 天过期一次，如遇失效请走 QQ 群（572549239），或开个 issue 提醒我们更新。
权限与安全边界
CLI 和 Web 使用相同的工作区账本。会话必须登记在该工作区的 sessionIds 中，且会话头部目录与工作区规范路径一致；缺少登记、主动移出工作区或工作区登记被删除时显示“未分组”，不再显示“未记录目录”或“未归属会话”。打开 /resume 会刷新账本，选择器打开期间也接收另一进程的工作区变化；共享 JSON 后端在后台每 1.5 秒检查一次。TUI 配置的自定义模型在 Web 模型页可编辑，在模型选择器统一归类为“自定义模型”；provider ID 保持不变。
自定义模型字段统一为：models[].id 是模型 ID，models[].name 是模型显示名称，提供商的 displayName 是提供商名称。“自定义”只作为分类标签。在 /model-config 的添加表单中先选择“模型提供商”：选择 Web 或 TUI 已配置的提供商可追加模型；选择“新增提供商”可从目录选择 deepseek 等 ID，或填写稳定的自定义 ID，不再生成随机提供商 ID。已有提供商 ID 不允许重复创建，同一提供商内的模型 ID 不允许重复添加；应编辑已有配置。追加模型保留提供商的地址、协议、密钥和其他模型。目录提供商未配置模型列表或列表为空时显示继承的模型；删除最后一个模型会移除该提供商配置，但保留凭据，避免重新继承默认模型。Web 单模型卡片显示模型名称或 ID，多模型卡片显示提供商名称及旗下模型名称。旧随机路由继续可用，不自动迁移或合并；显示名称变化不改变 provider ID 或凭据引用。
模型配置中的 Esc 逐级返回：“新增提供商”返回“模型提供商”选择页，“模型提供商”选择页返回添加模型表单，表单返回模型配置列表；仅在模型配置列表按 Esc 才退出到聊天界面。返回时保留表单内容，不保存未完成的配置。
新增提供商时，目录选择和手动输入使用相同的 ID 校验（忽略输入前后空格，统一为小写）。若 ID 已存在，当前页显示“已有提供商使用了这个 ID”，不会返回模型表单或写入配置；可重新选择/填写其他 ID，或按 Esc 返回选择已有提供商。
重复提供商 ID、重复模型 ID、字段格式错误、保存失败和连接测试失败均在当前页以主题错误色（红色）加粗显示，普通说明不会变色。模型 ID 输入后立即检查同一提供商的已配置及继承模型，重复时停留在字段页；先填模型后选提供商，也会立即检查。编辑现有模型保留其自身 ID、不同提供商使用相同模型 ID 均允许；保存时再复核以防并发新增。测试成功使用绿色反馈，操作提示使用警告色。
选择目录提供商后，API 协议、Base URL、API Key 等字段仍可编辑；协议与地址从运行宿主安装的目录自动填入，已有配置优先。目录没有统一默认值时保持原生继承，不猜测协议。仅追加模型不会覆盖已有提供商连接配置；显式修改连接字段会影响该提供商的其他模型。连接测试结果保留在当前表单或模型操作页，并记录到本地聊天区。已保存且连接字段未修改的目录模型走宿主真实路由测试；未保存的地址、协议或密钥修改使用草稿测试，不会自动保存。无法直接测试的原生协议需先保存，再从模型列表测试，页面会明确提示。
Windows 安全警告： Windows profile 默认使用 danger-full-access，且 approval 默认是 never。这会授予工具不受限制的访问权限；在敏感凭证或不可信仓库环境中启动前，务必先检查并收紧 profile 配置。
ChatCode CLI TUI 不实现独立沙箱，而是使用当前 Profile 的文件、Shell、sandbox 与 approval 策略。/sandbox 是本地兼容入口，裸命令复用权限预设选择器，/sandbox status 复用策略说明，其余参数原样转发给 /permission；没有可执行契约的旧式 exclusion 语法不会被伪造。权限预设来自受保护的 DSH permissionPresets registry ABI：服务缺失时使用 legacy 三项兼容名册；服务已挂载但为空、损坏或不一致时标记为 unavailable，TUI fail closed，不伪造名册。在包含敏感凭证或不可信仓库的环境中启动前，请先检查 Profile 配置。
详见权限边界与已知限制。
友情链接
朋友们开发的社区、相关项目与周边工具
Stars
Star History
License
MIT
ChatCode 统一登录
未登录时，每次启动都会发起新的登录请求、重新打开默认浏览器并打印登录链接；上次遗留的 pending 不会让启动只停留在等待状态。不小心关掉登录网页后，重新执行 cco 即可恢复，无需删除凭据文件；已有账号验证通过时仍直接进入 CLI。
/plugins 打开两级插件市场，Enter 选择插件后分别安装到项目级或用户级，已安装的范围可以卸载；Tab 切换已安装列表，Esc 返回，r 刷新。切换市场及刷新目录时隐藏原列表并阻止选择，成功后显示对应市场的插件；失败可按 r 重试。通过 config 插件与 Web 共用本机安装记录。两个安装范围中的插件命令都直接使用原名（例如 /code-review），不加插件或哈希前缀；同名时项目级优先，卸载后恢复用户级命令。契约诊断使用 /plugins diagnostics 或 /plugins check <清单路径>。配置、官方市场目录和加载能力见 插件市场说明。
登录验证通过后，即使模型目录为空也能进入 CLI、查看 /resume 历史和修改设置；状态显示“未配置模型”。发送消息前需用 /model 选择模型或通过 /provider 配置提供方，选好后无需重启；不会自动使用旧的 DeepSeek 默认模型。
当前项目从主库执行 pnpm cco 启动 TUI；可在 TUI 输入 /web，或执行 pnpm cco web 启动 Web。主库源码包装器会自动叠加 dsh-llm-chatcode-config，无需向 cli Profile 重复安装。启动时先使用 Host 内置的 CVP_CHATCODE_API_TOKEN 检查 ChatCode 全局启用状态，CHATCODE_CVP_CONFIG_TOKEN 可覆盖默认凭证；失败时可选择“重新检测”或“退出”，通过后才验证共享账号并创建 Agent/Session。/login 校验共享账号；/logout 清除本机共享凭据并退出当前 TUI 进程，下一次启动会重新进入登录流程。Web 和 TUI 使用同一 CHATCODE_CLI_HOME 与凭据存储；旧 DSH_HOME 仅作为兼容输入。账号登录不会替换各模型的 API key，也不注销其他提供方。详见相邻配置插件仓库的 使用手册。
今日 Token 与 AI 代码占比统计也通过宿主 chatcodeAuth 服务鉴权，使用 dsh-llm-chatcode-config 管理的 $CHATCODE_CLI_HOME/.credentials.yaml，不再读取旧 .credentials.json。进程级 OAuth token 由同一服务统一处理；未登录或查询失败且尚无成功结果时，今日 Token 显示占位符。
/settings、/statusline 和 /keybindings 兼容新旧 Harness 设置服务；显示偏好实时生效并由宿主持久化，不重建当前会话。全屏模式仍在重启后生效。
快捷键设置会显示冲突的组合和占用它的动作；例如 Ctrl+T 默认用于轨迹场景，待办折叠默认使用 Ctrl+Q。打开文本字段、或未修改内容就按 Enter，不会触发校验或写入。按 Esc 会取消当前字段的未保存编辑，不影响同组其他有效草稿；重置下拉选项会清除用户覆盖并恢复宿主默认值。
全屏模式按变化行重绘，清除系统终端及 JetBrains 内置终端中的流式输出残影，保持未变化的输入框稳定，并保留兼容终端的硬件滚动优化；状态图标输出后校正光标列，兼容旧终端的字符宽度表。
