🖥️ TUI 终端手册

纯 Rust 终端 AI 编程助手 · 从安装到精通

1. 安装与启动

1.1 一键脚本（macOS / Linux）

curl -fsSL https://www.youcoder-ai.com/install.sh | sh

默认安装到 /usr/local/bin（需要 sudo）。加 --no-sudo 装到 ~/.local/bin，或用 YOUCODER_INSTALL_DIR 自定义目录。

1.2 Windows (PowerShell)

irm https://www.youcoder-ai.com/install.ps1 | iex

安装到 %LOCALAPPDATA%\youcoder\bin 并自动加入用户 PATH。

1.3 Homebrew（macOS / Linux）

brew install kevin870202zheng/tap/youcoder

1.4 启动

youcoder                # 进入 TUI 交互界面
youcoder resume         # 恢复最近一次会话

💡 提示：首次启动如提示缺少 API Key，可直接输入 /status 查看当前配置状态，参考第 11 节配置 API Key。

2. 快速开始

运行 youcoder 进入界面。
在底部输入栏（提示符 > ）输入你的第一个需求，如 "列出当前目录的文件"，按 Enter 发送。
AI 会调用工具执行并流式返回结果。工具调用需要授权时，按 Enter 批准、Esc 拒绝。
按 Tab 循环切换模式：Plan → Ask → Act → YOLO。
随时按 ? 打开快捷键帮助，输入 /help 查看全部斜杠命令。

界面布局（自上而下）：Header（模式/模型/状态/上下文用量）· 聊天区 · 审批条（工具授权时）· 输入栏 · Footer（模式选择器/错误徽标/消费统计）。

3. 交互模式

模式	说明	适用场景
Plan	只读，先产出计划与设计	复杂任务前先规划
Ask	只读，每次写入需确认	提问、阅读代码
Act	全工具 + 每次调用审批	默认模式，安全可控
YOLO	全自动执行，无审批弹窗	批量操作、可信工作流（Pro）

切换方式：Tab 循环；或输入 /mode act 直接指定。Free 版锁定 YOLO（Footer 显示 🔒Yolo）。

4. 键盘快捷键

4.1 全局

按键	功能
`↑`/`↓`	滚动聊天区（双击跳顶/跳底）
`PgUp`/`PgDn`	滚动 10 行
`Ctrl+F`	聊天记录搜索
`?`	快捷键帮助浮层
`Ctrl+P`	Plan 计划浮层
`Ctrl+R`	错误日志查看器
`Ctrl+B`	文件树侧边栏
`Ctrl+T`	折叠/展开全部 Thinking 块
`Ctrl+A`	折叠/展开全部 Agent 结果
`Ctrl+E`	会话选择器
`Alt+M`	模型选择器
`Ctrl+S`	设置浮层（含 License/登录）
`Ctrl+D`	管理面板（MCP / Agents / Skills）
`Ctrl+G`	Governance 治理模式
`Ctrl+C`	退出应用（空闲时）

4.2 输入栏

按键	功能
`Enter`	发送消息 / 确认
`Tab`	切换模式 / 补全确认
`@`	文件引用选择器（`@file` 展开内容）
`/`	斜杠命令补全（光标在首位）
`Ctrl+Shift+V`	多行粘贴
`Esc`	逐级关闭浮层 / 清空输入 / 取消流式

5. 斜杠命令

命令	功能
`/help [cmd]`	命令帮助（别名 `/？`）
`/mode [plan\|ask\|act\|yolo]`	显示/切换模式
`/status`	模式/模型/scope/license/预算/用量
`/exit` / `/quit`	退出
`/clear`	清空聊天显示
`/model [show\|list\|set <name>]`	模型管理
`/budget [show\|set <usd>]`	会话预算上限
`/compact [show\|set <t>]`	上下文压缩阈值（Pro）
`/session list\|name\|switch\|delete\|rename\|prune`	会话管理
`/agent list\|new\|edit\|rm\|watch\|run`	子代理管理（Pro）
`/skill list\|show\|install\|delete\|run`	技能管理
`/mcp list\|register\|remove\|update\|tools`	MCP 服务器管理（别名 `/tools`）
`/persona list\|activate\|deactivate\|delete`	Persona 管理（Pro）
`/scope [show\|set\|add\|remove\|list\|clear]`	感知范围
`/logs [list\|summary\|prune]`	事件日志
`/license [status\|activate <key>]`	License 查看/激活

输入 / 会弹出自动补全列表；Tab 二次补全子命令（如 /model + Tab → model show）。

6. 内置工具

YouCoder 内置 20+ 工具，涵盖文件、代码搜索、网页、终端、浏览器、记事本与图像识别：

类别	工具
文件操作	`read_file` · `write_file` · `edit_file` · `multi_edit` · `undo_file` · `mkdir` · `mv` · `cp` · `rm`
代码搜索	`glob` · `grep` · `ls`
执行	`exec_shell`（受 `[tools.exec]` 安全策略约束）
网页	`web_fetch` · `web_search`（duckduckgo/bing）· `browser_fetch`
浏览器	`chrome_agent`（CDP 控制浏览器）
其他	`notebook_edit`（Jupyter）· `image_to_text`（OCR）· `checkpoint`（Git 快照）· `create_plan`/`update_task` · `ask_user`
引擎动态	`agent-*` · `run_skill`/`install_skill` · `run_background` · `wait` · 治理工具

工具执行受感知范围（Scope）限制，AI 只能访问 scope 内的目录（/scope 管理）。

7. 技能 Skills

技能是可复用的工作流模板（SKILL.md + frontmatter），存放在项目 .youcoder/skills/ 或用户 ~/.youcoder/skills/。内置技能：探索（广域只读代码库搜索）、研究（网页搜索+代码阅读）、审查（代码审查）。

命令	说明
`/skill list`	列出所有技能
`/skill show <n>`	查看技能详情
`/skill install`	安装自定义技能
`/skill run <n> [输入]`	直接运行技能
`/skill delete <n>`	删除技能

💡 提示：你可以在对话中直接让 AI "用探索技能查看这个仓库"，AI 会自动调用 run_skill。

8. 子代理 Agents

子代理是隔离子智能体，有自己的模型、工具和系统提示词，适合并行处理独立任务。定义文件在 ~/.youcoder/agents/。

命令	说明
`/agent list`	列出代理
`/agent new`	全屏向导创建（名称→描述→系统提示→模型）
`/agent run <n> [输入]`	运行代理（结果可注入主对话）
`/agent watch [id]`	监控代理运行
`/agent edit <n>` / `rm <n>`	编辑 / 删除

9. MCP 服务器

通过 MCP 协议连接外部工具与数据源（数据库、文件系统、Web API），无限扩展能力边界。服务器在 config.toml 的 [mcp_servers] 注册。

# ~/.youcoder/config.toml
[mcp_servers.my-db]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sqlite"]

命令	说明
`/mcp list`	列出已注册服务器
`/mcp register <n> <cmd> [args]`	注册新服务器
`/mcp tools`	查看可用工具
`/mcp remove / update`	删除 / 更新

10. 远程访问（手机）

通过 WebSocket 隧道，用手机浏览器访问你的电脑上的 YouCoder 引擎（需 Pro 登录）：

youcoder tunnel start

输出一个 https://www.youcoder-ai.com/tunnel/<machine-id> 链接，手机打开即用。局域网内也可用 youcoder-server --http 打印二维码扫码访问。

11. 配置

11.1 API Key 三种方式（优先级从高到低）

优先级	方式	说明
1	CLI 参数	`youcoder --provider deepseek --api-key sk-xxx`
2	环境变量	厂商 Key 自动探测：`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` / `GEMINI_API_KEY` / `ZHIPU_API_KEY` / `MINIMAX_API_KEY` / `XIAOMI_API_KEY`
3	配置文件	`~/.youcoder/config.toml`（推荐，持久化）

11.2 配置文件示例

# ~/.youcoder/config.toml
provider = "deepseek"        # 或 anthropic / openai / gemini / zhipu ...
api_key = "sk-your-key"
model = "deepseek-v4-pro"
# base_url = "https://api.deepseek.com"   # 自定义 API 地址
# proxy_url = "http://127.0.0.1:7890"     # HTTP 代理

项目级配置放 .youcoder/config.toml（仅当前项目生效，优先级高于全局）。通用环境变量：YOUCODER_PROVIDER / YOUCODER_API_KEY / YOUCODER_MODEL / YOUCODER_BASE_URL / YOUCODER_PROXY_URL 等。

11.3 执行安全策略

# [tools.exec] 控制 exec_shell 工具
[tools.exec]
security = "relaxed"         # deny / allowlist / relaxed
ask = "on-denied"            # 或 on-every-command
# allowlist = ["git", "ls"]

12. 记忆与上下文

会话持久化：SQLite 自动保存，youcoder resume 恢复最近会话，/session list 管理。
上下文压缩：长对话自动压缩（阈值默认 0.8，保留最近 8 轮），/compact set <t> 调整（Pro）。
预算控制：/budget set 5 设置会话预算上限（美元）。
多设备同步：登录账号后，多台设备的会话与授权状态实时同步。

13. 进阶技巧

@ 文件引用：输入 @src/main.rs 直接引用文件内容，AI 无需先读文件。
多行粘贴：Ctrl+Shift+V 直接粘贴多行代码。
聊天搜索：Ctrl+F 实时搜索历史消息（显示匹配数）。
折叠思考块：Ctrl+T 一键折叠所有 Thinking 块，聚焦结论。
计划浮层：Ctrl+P 查看当前会话的完整计划。
错误日志：Ctrl+R 查看错误日志（Footer 的 [!N] 徽标提示数量）。
Go 治理模式：Ctrl+G 进入双栏治理界面，管理子任务与委派。
Dashboard：Ctrl+D 图形化管理 MCP / Agents / Skills（+ 新建、e 编辑、d 删除）。

14. 故障排查

问题	解决方案
提示 "No API key configured"	检查 `~/.youcoder/config.toml` 位置与字段，或改用环境变量方式
一直连接不上模型	`/status` 查看配置；检查网络/代理；`/model list` 确认模型名
工具执行被拒绝	检查 `[tools.exec]` 策略与感知范围 `/scope`
想查看日志	`~/.youcoder/logs/youcoder.log`（每日轮转）
终端显示异常	退出后重新打开终端；`stty sane` 修复

🖥️ TUI Terminal Manual

A pure-Rust terminal AI coding assistant · from install to mastery

1. Installation & Launch

1.1 One-line script (macOS / Linux)

curl -fsSL https://www.youcoder-ai.com/install.sh | sh

Installs to /usr/local/bin (needs sudo). Add --no-sudo to install to ~/.local/bin, or set YOUCODER_INSTALL_DIR for a custom directory.

1.2 Windows (PowerShell)

irm https://www.youcoder-ai.com/install.ps1 | iex

Installs to %LOCALAPPDATA%\youcoder\bin and adds it to your user PATH.

1.3 Homebrew (macOS / Linux)

brew install kevin870202zheng/tap/youcoder

1.4 Launch

youcoder                # enter the TUI
youcoder resume         # resume the most recent session

💡 Tip: If it reports a missing API key, type /status to inspect your config, then see section 11 to set up your key.

2. Quick Start

Run youcoder.
Type your first request in the input bar (prompt > ), e.g. "list the files in the current directory", press Enter.
The AI calls tools and streams results. To approve a tool call press Enter; to reject press Esc.
Press Tab to cycle modes: Plan → Ask → Act → YOLO.
Press ? any time for the keybinding help, or /help for all slash commands.

Layout (top to bottom): Header (mode/model/status/context usage) · Transcript · Approval bar (when a tool needs approval) · Input bar · Footer (mode selector/error badges/consumption).

3. Interaction Modes

Mode	Description	Best for
Plan	Read-only; produces a plan/design first	Planning before complex tasks
Ask	Read-only; every write needs confirmation	Questions, reading code
Act	All tools + per-call approval	Default mode — safe and controlled
YOLO	Fully autonomous, no approval prompts	Batch ops, trusted workflows (Pro)

Switch with Tab, or /mode act to pick one directly. YOLO is locked on Free (shown as 🔒Yolo in the footer).

4. Keyboard Shortcuts

4.1 Global

Key	Action
`↑`/`↓`	Scroll transcript (double-press jumps top/bottom)
`PgUp`/`PgDn`	Scroll 10 lines
`Ctrl+F`	Search chat history
`?`	Keybinding help overlay
`Ctrl+P`	Plan overlay
`Ctrl+R`	Error log viewer
`Ctrl+B`	File tree sidebar
`Ctrl+T`	Collapse/expand all Thinking blocks
`Ctrl+A`	Collapse/expand all Agent results
`Ctrl+E`	Session switcher
`Alt+M`	Model picker
`Ctrl+S`	Settings overlay (incl. license/login)
`Ctrl+D`	Dashboard (MCP / Agents / Skills)
`Ctrl+G`	Governance mode
`Ctrl+C`	Quit (when idle)

4.2 Input bar

Key	Action
`Enter`	Send / confirm
`Tab`	Cycle mode / confirm completion
`@`	File reference picker (`@file` expands content)
`/`	Slash command completion (cursor at position 0)
`Ctrl+Shift+V`	Paste multi-line text
`Esc`	Close overlays step-by-step / clear input / cancel streaming

5. Slash Commands

Command	Action
`/help [cmd]`	Command help (alias `/？`)
`/mode [plan\|ask\|act\|yolo]`	Show / switch mode
`/status`	Mode/model/scope/license/budget/usage
`/exit` / `/quit`	Quit
`/clear`	Clear the transcript
`/model [show\|list\|set <name>]`	Model management
`/budget [show\|set <usd>]`	Session budget cap
`/compact [show\|set <t>]`	Context compaction threshold (Pro)
`/session list\|name\|switch\|delete\|rename\|prune`	Session management
`/agent list\|new\|edit\|rm\|watch\|run`	Sub-agent management (Pro)
`/skill list\|show\|install\|delete\|run`	Skill management
`/mcp list\|register\|remove\|update\|tools`	MCP server management (alias `/tools`)
`/persona list\|activate\|deactivate\|delete`	Persona management (Pro)
`/scope [show\|set\|add\|remove\|list\|clear]`	Perception scope
`/logs [list\|summary\|prune]`	Event logs
`/license [status\|activate <key>]`	License view/activate

Typing / opens auto-completion; Tab completes sub-commands (e.g. /model + Tab → model show).

6. Built-in Tools

YouCoder ships 20+ tools covering files, code search, web, shell, browser, notebooks and OCR:

Category	Tools
Files	`read_file` · `write_file` · `edit_file` · `multi_edit` · `undo_file` · `mkdir` · `mv` · `cp` · `rm`
Search	`glob` · `grep` · `ls`
Execution	`exec_shell` (governed by `[tools.exec]` policy)
Web	`web_fetch` · `web_search` (duckduckgo/bing) · `browser_fetch`
Browser	`chrome_agent` (CDP-controlled browser)
Other	`notebook_edit` (Jupyter) · `image_to_text` (OCR) · `checkpoint` (Git snapshots) · `create_plan`/`update_task` · `ask_user`
Engine	`agent-*` · `run_skill`/`install_skill` · `run_background` · `wait` · governance tools

Tools are constrained by your perception scope — the AI can only touch directories inside the scope (manage with /scope).

7. Skills

Skills are reusable workflow templates (SKILL.md + frontmatter) stored in .youcoder/skills/ (project) or ~/.youcoder/skills/ (user). Built-ins: Explore (wide read-only codebase search), Research (web + code reading), Review (code review).

Command	Action
`/skill list`	List all skills
`/skill show <n>`	Show skill details
`/skill install`	Install a custom skill
`/skill run <n> [input]`	Run a skill directly
`/skill delete <n>`	Delete a skill

💡 Tip: You can simply ask the AI to "use the explore skill on this repo" — it will call run_skill automatically.

8. Sub-Agents

Sub-agents are isolated AI agents with their own model, tools and system prompt — great for parallel, independent tasks. Definitions live in ~/.youcoder/agents/.

Command	Action
`/agent list`	List agents
`/agent new`	Fullscreen wizard (name → description → prompt → model)
`/agent run <n> [input]`	Run an agent (result can be injected into chat)
`/agent watch [id]`	Watch an agent run
`/agent edit <n>` / `rm <n>`	Edit / delete

9. MCP Servers

Connect external tools and data sources (databases, filesystems, web APIs) via the Model Context Protocol. Servers are registered in [mcp_servers] in your config.

# ~/.youcoder/config.toml
[mcp_servers.my-db]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sqlite"]

Command	Action
`/mcp list`	List registered servers
`/mcp register <n> <cmd> [args]`	Register a server
`/mcp tools`	List available tools
`/mcp remove / update`	Remove / update

10. Remote Access (Mobile)

Expose the YouCoder engine on your machine to a mobile browser over a WebSocket tunnel (requires Pro login):

youcoder tunnel start

It prints a https://www.youcoder-ai.com/tunnel/<machine-id> link — open it on your phone. On a LAN, youcoder-server --http prints a QR code you can scan.

11. Configuration

11.1 API key — three ways (highest priority first)

Priority	Method	Notes
1	CLI args	`youcoder --provider deepseek --api-key sk-xxx`
2	Env vars	Provider auto-detected: `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` / `GEMINI_API_KEY` / `ZHIPU_API_KEY` / `MINIMAX_API_KEY` / `XIAOMI_API_KEY`
3	Config file	`~/.youcoder/config.toml` (recommended, persistent)

11.2 Config file example

# ~/.youcoder/config.toml
provider = "deepseek"        # or anthropic / openai / gemini / zhipu ...
api_key = "sk-your-key"
model = "deepseek-v4-pro"
# base_url = "https://api.deepseek.com"   # custom API base URL
# proxy_url = "http://127.0.0.1:7890"     # HTTP proxy

Project-level config lives in .youcoder/config.toml (overrides global). Generic env vars: YOUCODER_PROVIDER / YOUCODER_API_KEY / YOUCODER_MODEL / YOUCODER_BASE_URL / YOUCODER_PROXY_URL.

11.3 Execution safety policy

# [tools.exec] governs the exec_shell tool
[tools.exec]
security = "relaxed"         # deny / allowlist / relaxed
ask = "on-denied"            # or on-every-command
# allowlist = ["git", "ls"]

12. Memory & Context

Session persistence: auto-saved to SQLite; youcoder resume restores the latest session, /session list manages them.
Context compaction: long chats auto-compact (default threshold 0.8, keeps last 8 rounds); tune with /compact set <t> (Pro).
Budget control: /budget set 5 caps session spend in USD.
Multi-device sync: after login, sessions and approvals sync across your devices in real time.

13. Pro Tips

@ file references: type @src/main.rs to inline a file's content — the AI won't need to read it first.
Multi-line paste: Ctrl+Shift+V pastes code blocks directly.
Chat search: Ctrl+F live-searches history (with match count).
Collapse thinking: Ctrl+T folds all Thinking blocks to focus on conclusions.
Plan overlay: Ctrl+P shows the full plan of the current session.
Error logs: Ctrl+R opens the error viewer (count shown as [!N] in the footer).
Governance mode: Ctrl+G opens the dual-pane governance view for sub-tasks and delegation.
Dashboard: Ctrl+D manages MCP / Agents / Skills graphically (+ create, e edit, d delete).

14. Troubleshooting

Issue	Solution
"No API key configured"	Check the location/fields of `~/.youcoder/config.toml`, or switch to env vars
Can't reach the model	Run `/status`; check network/proxy; verify the model name with `/model list`
Tool execution denied	Check `[tools.exec]` policy and your perception scope (`/scope`)
Need to inspect logs	`~/.youcoder/logs/youcoder.log` (rotated daily)
Terminal rendering glitches	Reopen the terminal; run `stty sane` to fix