命令行 CLI

除了桌面客户端，仓库里还有一个命令行工具 triecode，用的是同一套智能体引擎。适合脚本、CI、远程服务器和习惯终端的人。

⚠️ 目前 CLI 还没有发布到 npm，需要从仓库构建：

corepack pnpm --filter @triecode/cli build
node packages/cli/dist/index.js --help

运行时要求 Node ≥ 24（用到了 node:sqlite）。

先配置模型 Key

export TRIECODE_API_KEY=sk-xxx        # Windows PowerShell: $env:TRIECODE_API_KEY="sk-xxx"

也可以每次用 --api-key 传。默认接入点是 DeepSeek 的 OpenAI 兼容接口：

参数	默认值	说明
--provider	openai	claude 走 Anthropic 原生协议，其它值按 OpenAI 兼容处理
--base-url	https://api.deepseek.com/v1	换成其它兼容服务时改这里
--model	deepseek-v4-flash	模型名以服务商为准

单次执行：triecode run

triecode run "把 main.c 编译并烧录到 uno"
triecode run "跑一遍测试并修复失败用例" --format json

参数	作用
--yes	自动模式：常规写操作直接执行，危险命令与受保护路径仍会确认
--ask	默认档：非只读操作逐个问 y/N
--reject	只侦察：任何非只读操作一律拒绝
--format json	输出 NDJSON（每行一个 JSON 事件），方便脚本消费
--cwd <dir>	指定工作目录（不改变进程自身目录）
--proxy <url>	HTTP 代理；也可以设 HTTPS_PROXY / HTTP_PROXY

结构化输出请使用 --format json。子命令（如 triecode run）暂不支持 --help，查看帮助请执行 triecode --help。

NDJSON 事件

{"version":1,"seq":1,"type":"session.status","status":"start"}
{"version":1,"seq":2,"type":"message.delta","content":"先看一下项目结构"}
{"version":1,"seq":3,"type":"tool.step","name":"read_file","status":"completed","args":{...},"result":"..."}
{"version":1,"seq":9,"type":"message.done","content":"..."}

tool.step 带 failed: true 表示这一步确实失败（编译失败、插件返回失败、操作被拒绝都会如实标记）。

交互模式

triecode          # 终端里：全屏 TUI
triecode repl     # 显式 REPL（管道输入时降级为逐行）

• TUI：全屏界面，包含欢迎卡、Markdown 渲染、可折叠的思考块、工具卡、权限弹窗与状态行。
  • Ctrl+C 中断（500ms 内再按一次强制退出）、Ctrl+T 折叠思考、Ctrl+E 展开工具
  • ↑ / ↓ 历史、PageUp/PageDown 滚动、Esc 清空输入
  • 斜杠命令：/clear、/help、/status、/exit
• REPL：提示符 triecode>，支持 /clear、/exit；任务运行中输入的内容会排队。

硬件命令

triecode compile uno D:\proj --port COM3
triecode flash uno COM3 D:\proj
triecode monitor COM3 115200

命令	位置参数顺序	说明
compile	板卡 / FQBN → 项目路径	串口只认 --port，不占位置参数
flash	板卡 → 串口 → 项目路径	也可以全用 --board / --port / --project
monitor	串口 → 波特率	流式输出，Ctrl+C 结束

工具链会自动识别：有 sdkconfig 判 ESP-IDF，有 .ino 判 Arduino，CMakeLists.txt 里含 STM32Cube 判 STM32。找不到时可显式指定：

export TRIECODE_ARDUINO_CLI=/path/to/arduino-cli
export IDF_PATH=/path/to/esp-idf
export STM32_PROGRAMMER=/path/to/STM32_Programmer_CLI

环境自检：triecode doctor

TrieCode CLI 环境自检（win32 10.0.26300 / node v24.14.0）
──────────────────────────────────────────
  [✓] API key (TRIECODE_API_KEY) — sk-abc...
  [✓] 工具链 — arduino-cli ✓ | esp-idf ✗ | stm32 ✓
  [✓] git — git version 2.53.0.windows.1
  [✓] 代理 — 直连（未设置 HTTPS_PROXY / HTTP_PROXY）
──────────────────────────────────────────

缺项时会打印「引导」，例如没有 Key：

  [✗] API key (TRIECODE_API_KEY) — 未配置——triecode run 需 --api-key 或环境变量
引导：
  · 配置模型 key：export TRIECODE_API_KEY=xxx（或 triecode run --api-key xxx）
  · 国内网络：triecode run ... --proxy http://127.0.0.1:7890

任一项失败时退出码为 1，并给出下一步建议。

退出码

码	含义
0	正常完成
1	出现工具失败（编译失败、命令返回错误等），或 run 抛异常
2	用法错误（未知命令、缺任务描述、缺 API Key）
4	非交互环境下遇到需要确认的操作（无人可答 → 直接取消）
130	被 Ctrl+C 中断

CI 中最常见的是 4：表示某一步需要人工确认，把权限策略改为 --yes 或调整任务描述即可。

与桌面端的差异

CLI 和桌面共用引擎、模型层、权限内核与失败判据，但有几点不同，使用前需要知道：

• 不读桌面配置：%APPDATA%\TrieCode\config.json 里的 Key、代理、模型都不会自动生效，CLI 只认参数和环境变量；
• 没有会话续接：每次 run 都是新会话，没有 --resume；
• 工具集是独立的一份（读文件、写文件、编辑、列目录、查找、终端、git 状态），桌面端的插件技能、MCP、记忆等不经过 CLI；
• 插件只用于 compile / flash 两步，triecode plugin list 可以查看哪些插件声明了对应能力。

常见问题

Q：triecode 命令找不到？ 还没有发布到 npm。构建后直接用 node packages/cli/dist/index.js；想在任意目录调用 triecode，可在 packages/cli 下执行 npm link（或 pnpm link --global）。

Q：triecode run --help 报「缺少任务描述」？ 已知限制：子命令中只有硬件命令支持 --help。查看帮助请用 triecode --help。

Q：task list 一直是空的？ 任务注册表目前是进程内内存，不落盘。它用于单次执行中的后台任务查询，不会显示桌面端「定时任务」里的内容。