# 命令行参数

这一页是**电脑上** `waycoder` 命令的全部开关（手机上用不到它们，手机上点按钮就行）。

⚠ **别手抄这张表**：它由 `scripts/make-cli-help.py` 从**参数注册表**生成（`--dump-help`），
改了参数不重跑，这一页就会落后于程序（`--check` 能当场发现）。

约定：`[方括号]` = 可选值，`<尖括号>` = 你要填的占位；一个参数可以写多个同义形式（如 `-m` / `--model`）。

```text
---< 模型 >-----------------------
  -m,  --model [模型ID/子命令]                     模型管理（key 支持有效期：--model key <供应商> <key> [永久|日期]）
        list [供应商]                              列出模型目录（OpenRouter 显示短名）
        name <id>                                  选中大模型
        small <id>                                 选中小模型
        key [set|remove]                           管理 API Key（key 永不自动删除，删除需确认）
        check [connect]                            检查模型能力（think/tools/vision/格式/上下文/key）
        report                                     测试所有 connect 连通性，生成可用/失败报告
        free                                       测试所有 free 模型（zen -free / openrouter :free），列出可用
        restore                                    恢复 /free 切换免费模型之前的模型
        import [alllocal|allonline|all|online <源>|来源]  导入模型（alllocal=本地 / allonline=在线 / all=全部 / online <源>=指定端点）
        add model/provider/key                     添加模型 / 服务商 / Key
        remove <id>                                移除模型或服务商
        clean                                      清理无效服务商/模型 + 合并重复 + 删无效 connect
        test                                       测试连接
        connect <base-url>                         设置 API 地址
        <模型ID>                                   快捷选中模型
  -b,  --base-url <URL>                            API 基础 URL
  -k,  --api-key <密钥>                            API 密钥（自动保存到全局 ~/.waycoder/api_keys.json，按当前服务商）
       --tiny [窗口]                               Tiny 模式（精简提示词 + 小窗口；可指定如 --tiny 8k，缺省自动探测，失败回退 4K）
  -tt, --test-tiny [窗口]                          别名
  -e,  --economy [模式]                            省 Token 模式（--economy [on|auto|off]，缺省 on；auto 按任务复杂度动态调节阈值）

---< 会话 >-----------------------
  -r,  --resume [会话名]                           恢复会话,会话名为空,就是上一次的。
  -c,  --continue [会话名]                         别名
  -s,  --session-list                              列出所有已保存会话
       --sessions                                  别名
       --session <会话ID>                          按会话 id 恢复，等同 --resume <id>
       --resume-session-id <会话ID>                别名
       --session-id <会话ID>                       别名

---< 执行 >-----------------------
  -p,  --prompt <文本>                             一次性提示词（CLI 纯文本输出，跑完退出）。-p1~-p0 投递槽位(进 TUI), -pa 共享前缀, 同槽位可排队
       --print <文本>                              别名
       --output-format <格式>                      输出格式：json|stream-json 等同 --json，text|default 普通输出
       --format <格式>                             别名
  -j,  --json                                      JSON 输出模式（配合 -p 一次性模式，stdout 输出结构化 JSON，供 IDE/脚本解析）
  -pa, --prompt-all <前缀>                         所有槽位任务的共享前缀（自动拼到每个 -pN 前面）

---< 预算 >-----------------------
  -B,  --max-budget-usd <金额>                     费用上限（美元），超支自动停止
       --max-requeue <次数>                        撞轮次上限后自动压缩+续跑次数（0=关闭，默认 3，超长任务可调大）
       --max-turns <次数>                          对话最大轮次上限

---< 权限 >-----------------------
  -y,  --yolo                                      跳过所有权限确认（非交互模式自动开启）
       --dangerously-skip-permissions              别名
       --permission-mode <模式>                    权限模式：default|acceptEdits|plan|bypassPermissions（plan=只读规划，acceptEdits=自动编辑，bypassPermissions=全开）
       --allowed-tools [工具名]                    工具白名单（空格/逗号分隔），等同 WAYCODER_ALLOWED_TOOLS
       --allowedTools [工具名]                     别名
       --disallowed-tools [工具名]                 工具黑名单（空格/逗号分隔），等同 WAYCODER_DISABLED_TOOLS
       --disallowedTools [工具名]                  别名
       --permit <tiny|chat|ack|auto|smart|yolo>    启动权限模式（tiny/chat=纯聊天工作模式）
        tiny                                       聊天：纯聊天工作模式（0 工具 0 提示词）
        ack                                        问答：逐次确认
        auto                                       自动：改必问，只读放行、写操作确认
        smart                                      智能：智能分级确认
        yolo                                       畅通：跳过所有确认
       --mode <build|plan|chat>                    启动工作模式：build=建造（全工具）/plan=计划（只读白名单）/chat=聊天（0 工具 0 提示词）

---< 界面 >-----------------------
       --web [端口]                                浏览器聊天界面（--web [端口]，默认 9527，自动打开浏览器）
       --tui                                       强制 TUI 全屏界面（默认即 TUI）
       --cli                                       强制 CLI 文本界面（非全屏，逐行交互）
       --theme <名字>                              切换颜色主题（ocean/forest/sunset/mono/cyberpunk）
  -q,  --quiet                                     静默模式：抑制横幅等非必要输出
       --no-color                                  禁用 ANSI 颜色输出
  -g,  --gui [文件]                                启动图形界面（独立 Avalonia 进程，可选 --gui [文件] 直接打开编辑器）
       --keypad <脚本文件>                         按键脚本驱动 TUI（KEY/TEXT/DELAY/SNAP/DIALOG）+ 帧截图

---< 系统 >-----------------------
  -i,  --init                                      初始化项目配置（.waycoder/ 目录）
       --system-prompt <文本>                      追加到系统提示词的文本（--append-system-prompt 为别名）
       --append-system-prompt <文本>               别名
  -w,  --watch                                     Watch 模式（监听文件中的 AI! 注释）
       --edit <文件路径>                           直接进入编辑器打开文件（--edit <文件路径>）
       --update                                    检查并自动升级到最新版本（优先 GitHub、回退 Gitee）
  -C,  --config 项 [值]                            命令行配置
        list                                       列出全部设置项
        get <key>                                  读取单项值
        set <key> <value>                          设置并写入 config.json
        <key> [value]                              简写：查值或设置
  -d,  --debug                                     开启调试日志（记录到 logs/ 目录）
       --auto-commit [on|off]                      自动 git 提交开关（on|off，缺省 on）
       --mcp-config <路径>                         指定 MCP 服务器配置文件路径
       --mcp [子命令]                              MCP 服务器管理（无参列出，reload [name] 重连）
        (无参)                                     列出 MCP 服务器状态
        reload [name]                              重连 MCP 服务器
       --reset                                     清空当前会话历史
       --purge                                     清理缓存文件（file-tracker/todos/trajectory）
       --provider [子命令]                         管理服务商数据库（providers.json）
        list                                       列出所有服务商
        add <id> <名称> <base-url>                 添加服务商
        rm <id>                                    移除服务商（同时清除其 Key）
        select <id>                                切换当前服务商（作用于当前大模型 connect）
        key <id> <key>                             保存某服务商的 API key
        test                                       连通性测试
        import [source]                            导入外部模型库
        clean                                      清理无效服务商（探测失败的）
        reconcile [apply]                          把模型归并到同地址的已注册服务商（默认预览；apply/run 才执行，先备份）

---< 批量 >-----------------------
       --batch <JSON>                              批量任务引擎：多仓库并行处理（--batch <JSON文件|内联JSON>，每个任务在独立克隆副本中隔离执行）
       --batch-repo <仓库>                         批量任务：添加一个仓库（可重复，配合 --batch-task 共享任务）
       --batch-task <文本>                         批量任务：所有 --batch-repo 仓库的共享任务
       --batch-keep                                批量任务：保留克隆的工作副本（默认执行后清理）

---< 测试 >-----------------------
  -t,  --test [模块名]                             运行自测（可选指定模块名）

---< 通用 >-----------------------
  -v,  --version                                   显示版本信息
  -h,  --help                                      显示此帮助

---< 其他 >-----------------------
       --connect [connect名/子命令]                连接层管理（connect 注册表 / 命名连接 / 回退链）
        list                                       列出 connect + 命名连接 + 回退链
        add <name> <providerId> <modelId>          新增 connect
        rm <name>                                  删除 connect
        select <id>                                切换大 connect（connect名 | providerId.modelId | providerId/modelId | baseUrl:model | modelId）
        <id>                                       快捷切换（同 select）
        test                                       连通性测试
        import                                     登记当前大/小/回退模型为 connect
        conn add <name> <大> <小>                  新增命名连接（大/小一起切）
        use <name>                                 切换命名连接
        chain <c1> <c2> ...                        设置全局回退链（connect 名）
       --debug-dump                                开启死机现场自动采集（黑匣子 + 定时/冻结 dump 到 logs/freeze_*.txt，排查死机用）
       --kb [子命令]                               编程知识库（mine 提炼经验 / review 间隔重复自测 / weak 薄弱点统计）
        mine [N]                                   从 git 历史提炼经验条目（默认 20）
        diagnose <报错>                            诊断报错（召回知识库 + git 修复史）
        path                                       生成学习路径（欠缺→进阶，接入 /kb review）
        profile [json]                             技能画像（json 导出）
        retro                                      复盘本次会话提炼经验
        review                                     间隔重复自测一条到期经验
        weak                                       欠缺知识清单 + 薄弱点统计
        list                                       列出全部经验条目
       --bench                                     运行性能测评
  -tb, --test-benchmark                            别名
       --perf                                      别名
       --limits                                    运行系统上限报告（扫描所有硬编码上限）
  -tl, --test-limits                               别名
```