📖 CLI 使用手册
终端原生 AI 编程助手 — 完整操作指南
1. 快速开始
下载对应平台的二进制文件后，打开终端运行：
# macOS / Linux chmod +x ./youcoder-macos-arm64 ./youcoder-macos-arm64 # Windows (PowerShell) .\youcoder-windows-x64.exe
📦 macOS 注意：下载的是
.dmg 磁盘映像，需先 hdiutil attach 挂载 → 复制二进制 → xattr -d com.apple.quarantine 解除隔离。详见 配置指南 → macOS 问题。
首次启动会提示配置 API Key。设置好之后即可进入 TUI（终端界面）。
2. 界面概览
YouCoder 启动后，终端界面分为以下几个区域：
| 区域 | 说明 |
|---|---|
| 顶部标题栏 | 显示交互模式、引擎状态（Idle / Streaming / Thinking）、上下文使用进度条 |
| 对话区 | 用户输入和 AI 回复的历史记录，支持滚动浏览 |
| 输入栏 | 底部输入框，在此输入提示词和命令 |
| 底部状态栏 | 错误 / 警告数量指示器 |
3. 交互模式
YouCoder 提供四种交互模式，控制 AI 的自主程度。按 Tab 循环切换：
| 模式 | 说明 | 可执行操作 |
|---|---|---|
| Plan | 只读模式。AI 作为架构师，分析代码库、生成计划 | 读文件、搜索代码、生成计划。不能写文件或执行命令 |
| Ask | 问答模式。自由阅读，写入需逐个确认 | 读文件（自动）、写文件（需批准）、执行命令（需批准） |
| Act | 执行模式。全部工具可用，每步操作需确认 | 全部 17 个工具可用，每个调用需按 Enter 批准 |
| YOLO | 全自动模式。无确认提示，AI 完全自主 | 全部工具自动执行，适合批量操作和可信工作流 |
💡 建议：日常使用推荐 Act 模式——既有 AI 的自主性，又保留每步操作的确认权。
4. 键盘快捷键
4.1 基础操作
| 按键 | 功能 |
|---|---|
| Enter | 提交输入 / 批准工具调用 / 折叠消息 |
| Escape | 清除输入 / 取消 AI 回复 / 拒绝工具调用 / 关闭叠加层 |
| Tab | 循环切换交互模式 |
| ? | 打开快捷键帮助 |
| Ctrl+C / Ctrl+D | 退出程序 |
4.2 导航
| 按键 | 功能 |
|---|---|
| ↑ / ↓ | 滚动对话记录（双击 ↑ 跳到顶部，双击 ↓ 跳到底部） |
| PageUp / PageDown | 滚动 10 行 |
| ← / → | 在输入框中移动光标 |
| Home / End | 光标跳转到输入框开头 / 末尾 |
| Backspace / Delete | 删除光标前 / 后的字符 |
4.3 功能快捷键
| 按键 | 功能 |
|---|---|
| Ctrl+T | 折叠 / 展开所有 AI 推理过程（Thinking 块） |
| Ctrl+E | 折叠 / 展开所有已提交的工具调用结果 |
| Ctrl+A | 折叠 / 展开所有后台智能体运行结果 |
| Ctrl+F | 切换对话搜索模式 |
| Ctrl+B | 切换左侧文件树侧边栏 |
| Ctrl+P | 切换全屏计划叠加层 |
| Ctrl+R | 切换错误日志查看器 |
📖 按 ? 可随时查看全部快捷键列表。
5. 内置工具
YouCoder 提供 17 个内置工具，分为三类：
5.1 读取类 Read
| 工具 | 功能 |
|---|---|
read_file | 读取文件内容（支持行号和 offset / limit） |
glob | 按通配符查找文件 |
grep | 搜索文件内容（支持上下文行） |
ls | 列出目录内容 |
web_fetch | 获取网页内容并转为 Markdown |
web_search | 搜索引擎查询 |
search_and_fetch | 搜索并获取搜索结果内容 |
browser_fetch | 完整浏览器渲染获取（支持 JS 动态页面） |
chrome_agent | 交互式 Chrome 浏览器控制（点击、输入、截图等） |
5.2 写入类 Write
| 工具 | 功能 |
|---|---|
write_file | 写入文件（不存在则创建） |
edit_file | 替换文件中的指定段落（需精确匹配） |
multi_edit | 原子性地对同一文件执行多次编辑 |
read_edit | 读取文件并应用编辑（Edit / MultiEdit 备选方案） |
notebook_edit | 编辑 Jupyter Notebook（.ipynb）单元格 |
create_plan | 创建结构化任务计划 |
update_task | 更新计划中的任务状态 |
5.3 执行类 Execute
| 工具 | 功能 |
|---|---|
exec_shell | 执行 Shell 命令（支持超时设置） |
读取类工具可并发执行，写入类工具按顺序执行（带路径限制），执行类工具在沙箱中顺序执行。
6. 斜杠命令
在输入框中输入以下命令，按 Enter 执行：
6.1 会话管理
| 命令 | 功能 |
|---|---|
/session list | 列出所有会话（ID、标题、更新时间、消息数） |
/session name <标题> | 为当前会话命名 |
/session switch <ID或标题> | 切换到指定会话 |
/session delete <ID> | 删除指定会话 |
/session rename <ID> <标题> | 重命名会话 |
6.2 感知范围
| 命令 | 功能 |
|---|---|
/scope | 查看当前 AI 可操作的目录范围 |
/scope <路径> | 修改感知范围 |
6.3 子智能体管理
| 命令 | 功能 |
|---|---|
/agent list | 列出所有已注册的子智能体 |
/agent new | 启动交互式智能体创建向导（5 步） |
/agent rm <名称> | 删除一个智能体 |
/agent edit <名称> | 编辑智能体定义 |
/agent <名称> <输入> | 运行一个智能体（支持后台运行） |
6.4 文件树操作（Ctrl+B 打开）
| 按键 | 功能 |
|---|---|
| ↑ / ↓ | 在文件列表中移动 |
| Enter / → | 展开目录 |
| ← | 折叠目录 / 返回上级 |
| Escape | 关闭文件树 |
7. @ 引用上下文
在输入框中输入 @ 可以快速引用项目中的文件或目录，AI 会自动读取并将其作为上下文：
@file src/main.rs— 读取文件内容并嵌入 Markdown 代码块@dir src/— 递归列出目录结构（最多 3 层，排除隐藏文件和 target）
输入 @ 后会弹出自动补全列表，用 ↑ / ↓ 选择，Enter 或 Tab 确认。
8. 子智能体系统
YouCoder 支持定义专门的子智能体（Sub-Agent），每个智能体拥有独立的系统提示词、工具集和模型。
智能体定义存储在 TOML 文件中：
# ~/.config/youcoder/agents/reviewer.toml
name = "reviewer"
description = "代码审查专家，专注于发现潜在缺陷和安全问题"
system_prompt = """
你是一位资深的代码审查专家。审查代码时重点关注：
1. 潜在的安全漏洞
2. 性能问题
3. 代码可维护性
4. 不符合最佳实践的模式
对每个问题给出严重等级（Critical / Major / Minor）和修复建议。
"""
model = "claude-sonnet-4-20250514"
tools = ["read_file", "grep", "glob", "ls"]
运行方式：/agent reviewer "请审查 src/auth.rs 中的代码"
💡 提示：使用
/agent new 可启动交互式创建向导，5 步完成子智能体创建。
9. MCP（Model Context Protocol）
YouCoder 支持 MCP 协议，可连接外部工具和数据源。在配置文件中添加：
# config.toml
[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
[[mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
每个 MCP 服务器是一个 stdio JSON-RPC 2.0 进程，启动时自动注册到工具列表。
10. 会话持久化
所有对话自动保存到数据库，下次启动时可以恢复：
# 恢复最近一次会话 ./youcoder-macos-arm64 resume # 或在 TUI 中切换会话 /session list /session switch <ID>
会话数据库位置：~/.local/share/youcoder/sessions.db（Linux / macOS）
11. CLI 参数参考
| 参数 | 环境变量 | 说明 |
|---|---|---|
--provider | YOUCODER_PROVIDER | 供应商（anthropic / openai / deepseek / auto） |
--api-key | YOUCODER_API_KEY | API Key |
--model | YOUCODER_MODEL | 模型名 |
--base-url | YOUCODER_BASE_URL | 自定义 API 地址 |
--max-tokens | YOUCODER_MAX_TOKENS | 最大 Token（默认 8192） |
--search-provider | YOUCODER_SEARCH_PROVIDER | 搜索供应商 |
--proxy-url | YOUCODER_PROXY_URL | HTTP 代理 |
resume | — | 恢复最近会话 |
12. 常见工作流
日常编码
# 启动（Act 模式默认） ./youcoder-macos-arm64 # 示例：让 AI 实现一个功能 "请为这个项目添加一个命令行参数 --verbose，用于控制日志输出级别" # AI 会：读取代码 → 理解结构 → 编写代码 → 等待你确认每步操作
代码审查
# 切换到 Plan 模式（只读安全） # 按 Tab 切换到 Plan，然后输入： "请审查 src/api/handlers.rs 的安全性和代码质量" # AI 会读取文件、分析问题，输出审查报告
快速原型
# 切换到 YOLO 模式全速开发 # 按 Tab 切换到 YOLO，然后输入： "请创建一个 Python Flask Web 应用，包含用户注册和登录功能" # AI 会自动创建文件、安装依赖、编写代码
调试问题
# 让 AI 分析错误日志 "应用启动时报错 'connection refused'，请检查代码并修复" # AI 会搜索相关代码，定位问题，提出修复方案
13. 提示与技巧
- 感知范围：默认 AI 可以读写当前目录及子目录的所有文件。使用
/scope <路径>限制 AI 的操作范围。 - 并行智能体：使用
/agent <名称> <输入>可以在后台运行子智能体，不影响主对话。 - 上下文管理：顶部进度条显示上下文窗口使用率，超过 80% 会自动压缩。可用
/session switch切换到新会话。 - 错误日志：按 Ctrl+R 可以查看运行时错误和警告，帮助排查问题。
- 搜索对话：长对话中按 Ctrl+F 可以搜索关键词，快速定位之前的内容。
14. 故障排查
| 问题 | 解决方案 |
|---|---|
| 启动后提示 "No API key configured" | 参考配置指南设置 API Key |
| macOS 提示应用未验证 | xattr -d com.apple.quarantine ./youcoder-* |
| AI 没有响应 | 检查网络连接和 API Key 是否有效 |
| 文件写入被拒绝 | 确认当前模式允许写入（Plan 模式不能写文件） |
| 想终止正在生成的回复 | 按 Escape |
| 界面显示异常 | 尝试调整终端窗口大小或重启程序 |
15. 从源码构建
# 需要 Rust 工具链
git clone https://github.com/Kevin870202Zheng/Roosevelt-s-YouCoder.git
cd Roosevelt-s-YouCoder
cargo build --release -p youcoder-cli
./target/release/youcoder