Skip to content

CLI 参考 ​

目标读者:需要查命令、参数、默认值、退出码的用户。命令与参数口径取自 toolkit --help 与各子命令 --help(两者冲突时以 --help 为准)。

本篇是命令总览与全局约定;每个域的完整参数、边界行为与示例见对应分页。

命令总览 ​

命令用途常用子命令分页
toolkit status整体状态:只读聚合任务区 / 技能现场 / 配置层 / 文档站 / 版本与弃用项—整体状态
toolkit init初始化任务区:目录骨架、规范载体、技能入口壳、忽略片段—项目初始化
toolkit task任务管理:总览、建档、更新、归档、校验、归一、统计、导入导出add / update / archive / check / normalize / stats / export / import任务管理
toolkit convention规范载体:结构升级、表格与索引单元格归一、只读体检upgrade / status / format规范载体
toolkit release多语言 CHANGELOG 与发版(封装 changesets,默认 status)status / bump / changelog / mirror / publish / audit / changeset发版与更新日志
toolkit skillAI 技能分发:安装、分发计划、状态、卸载、来源与版本install / plan / status / uninstall / source / bump / lint技能分发
toolkit usage技能使用情况:开关、统计、导出与诊断(默认关闭)show / data / config / setup / record技能使用情况
toolkit rule全局规则:列出模块、组合输出、锚点校验与缓存管理list / compose / reset / check全局规则
toolkit scope作用域:按项目 / 目录判定技能与规则是否生效(默认全域生效)status / list / policy / skills / wizard / guard(list 组含 add / exclude / remove / default / reset,详见 scope 页)作用域
toolkit config配置唯一写入口(键清单 + 分层写入)与只读体检list / get / set / unset / status配置体检
toolkit docs文档站全量校验(默认)、主题写入与分项校验check / theme / nav / dist文档站主题 · 文档站校验
toolkit help显示帮助——

按场景找命令 ​

你在做什么用什么
新项目接入toolkit init → toolkit skill install → toolkit config status
整体自查toolkit status 一次看全貌(--check 有 error 时退出 1;--format json 供脚本)
日常任务toolkit task 看板 → toolkit task check 校验 → toolkit task archive 归档
新会话恢复toolkit status(或 toolkit task --view all + toolkit convention status)
发版toolkit release bump → pnpm verify → 打标签发布
技能升级 / 换装toolkit skill status → toolkit skill install(外部来源见 skill source)
看分发形态会怎么落toolkit skill plan(只读预览;install --dry-run 同义)
看技能用了多少次toolkit usage show stats(--by session / --by trigger / --limit)
复制全局规则toolkit rule compose(按需 --preset / --module,--copy 直接进剪贴板)
规范沉淀toolkit convention status → toolkit convention upgrade / format
排查配置toolkit config status(不打印配置值)→ toolkit config get <key> --explain(看来源层与覆盖链)
改配置toolkit config set <key> <value>(--layer 选层;非交互加 --yes),删除用 config unset
文档站主题漂移toolkit docs theme check
文档站导航或产物不合规toolkit docs nav check / toolkit docs dist check

裸命令入口 ​

域裸命令(TTY)非 TTY显式向导入口机器可读
toolkit task打印任务总览(默认视图)同左,退出 0无list / stats --format json、export
toolkit skill打印本域帮助同左,退出 0无(mount 等子命令参数化)多数子命令 --format json(mount 等除外)
toolkit rule打印本域帮助同左,退出 0无list / compose --format json
toolkit config打印本域帮助同左,退出 0无list / get / status --format json
toolkit convention打印本域帮助同左,退出 0无status / format / upgrade --format json
toolkit docs默认全量校验(theme / nav / dist)同左无nav / dist --format json
toolkit scope状态优先向导输出状态摘要与子命令提示,退出 0scope wizard(需要交互但无终端时按无交互退出码结束,见退出码)status / list --format json
toolkit usage交互向导输出 show 摘要与子命令提示,退出 0usage setup wizard(需要交互但无终端时按无交互退出码结束,见退出码)show / show stats / data doctor 等 --format json
toolkit release默认 status 只读概览同左,退出 0无status / changeset list 等 --format json

规则:查询型域给默认视图,配置 / 分发型域给帮助,向导型域给摘要 + wizard 入口提示; 查询 / 分发型裸命令在非 TTY 退出 0;校验型裸命令(toolkit docs)按校验结论退出,存在 error 时为 1; 显式 wizard 子命令需要交互时退出 2。

术语表 ​

术语含义出现位置
层配置文件层级:global 全局 / project 项目 / local 本地--layer(scope 写命令;source notify 的 --layer 是它的别名)
面技能安装面:全局面 global / 项目面 projectskill install --scope、skill status / uninstall
名单作用域白名单(include)与黑名单(exclude)scope 菜单与写命令、scope list
策略作用域规则条目:条件 + 技能维度 + allow / deny;按层与具体度取唯一命中scope policy、scope status --skills
档案可复用的技能名单,供策略 skills.profiles 引用scope skills profile、skillProfiles 配置段
预演--dry-run:只打印将执行的动作,不写文件 / 剪贴板 / 缓存全部写命令
确认写前展示预览并交互确认;--yes 跳过确认usage / skill / config 写命令;scope 写命令在非 TTY 带显式参数直接执行
来源技能来源:内置 toolkit 源与 --source 外部来源skill、skill source
目标技能安装目标:agent 全局目录 / 项目薄壳目录skill install、skill status
范围按上下文区分:作用域命中范围(scope)或技能统计范围(usage)scope / usage config scope

全局约定 ​

调用方式:下文示例统一用 toolkit <command> 直调(已全局安装)或 pnpm exec toolkit <command>(项目 devDependency,npm 用户 npx toolkit)。

不安装临时执行用 pnpm dlx @fxri/toolkit <command>。

顶层命令支持的开关(-h 全局与子命令均可用):

参数说明
-h, --help显示帮助(全局或子命令)
-v, --version显示版本号
--no-color关闭终端颜色输出(优先于 NO_COLOR / FORCE_COLOR,可写在任意位置)
--cwd <path>在指定目录执行命令(等价先切换工作目录;非法路径按 1 退出,不回落当前目录)

--redact / --warn 为域级开关:仅 task 与 release 两个域支持。

init / skill / convention / config / docs / usage / rule 域不提供,清单见各域的选项表。

批量参数:目标集合是命令主语时省略参数即全部(如 skill source refresh)。

否则须显式 --all(如 usage data purge --all、skill install --all、skill bump --all)。

开关为双向三档,优先级从高到低:CLI 参数 > 环境变量 > 配置文件 > 默认开启。

对应环境变量:FX_TOOLKIT_REDACT、FX_TOOLKIT_CHECK_WARN(认 0/1、true/false、on/off、yes/no);配置项见配置参考。

本工具自身的环境变量只认 FX_TOOLKIT_ 前缀。旧名(如 FX_REDACT、TOOLKIT_USAGE_DIR)不再读取: 命中时只在 stderr 提示一次,取值按新名或默认值处理。

另有独立环境变量 FX_TOOLKIT_NO_UPDATE_CHECK:设为真值时关闭升级检查提示。

升级检查自 1.7.0 引入;变量名随前缀统一为 FX_TOOLKIT_,行为详见配置参考 · 升级检查。

升级提示收口:命令成功(退出码 0)时,按 updateCheck.notify(默认 always)在输出结尾给出一句话提示;TTY 下走 stderr,非 TTY 走 stdout。

已尝试修复(执行过 skill install)的同一版本不再重复提示。哪些子命令不输出、版本比较口径、关闭方式见配置参考 · 升级检查。

输出约定 ​

颜色仅在交互终端启用:输出被重定向到文件或管道、TERM=dumb、 旧版 Windows 控制台(无 Windows Terminal / VS Code 终端标记)时自动关闭。 NO_COLOR 非空或 --no-color 可关闭,FORCE_COLOR 非 0 可强制开启。

成功结论(✔)绿色、告警(⚠️)黄色、失败(✖)红色、次要说明与操作指引(·)暗色, [预演] 标记青色,路径与命令名等强调文本青色。关闭颜色时符号保留、文案不变。

机器可读输出不着色:--format json、--out 写入文件、scope guard 技能正文等数据通道恒为纯文本。

报告类 --format json 统一为信封 { schemaVersion, command, ok, data, issues }:command 为实际命令路径, ok 为报告结论(check 类按是否存在 error,只有告警时仍为 true),data 承载域载荷, issues 汇总问题(level / scope / message)。数据流输出不套信封:usage data export、task export <path> 与 release changeset 透传保持原格式;业务错误仍写 stderr 并保留原退出码,不在 stdout 输出半截 JSON。

文本表格、报告数据行与规则正文同样不着色,便于复制与日志比对;交互菜单由组件库自行渲染,不在本约定内。

交互约定 ​

交互提示统一走同一套基座(rule / scope / usage / skill 已接入,其余域按同一口径演进):

  • 有上级步骤时按 ESC 返回上一级;顶层按 ESC 或 Ctrl+C 取消整个命令(取消退出码见退出码)。
  • 写操作先展示预览再确认;--yes 跳过确认,--dry-run 只预览、不写文件 / 剪贴板 / 缓存。
  • 非法取值统一在 stderr 报错并以 1 退出;--format 只接受 json,不再回落文本。

退出码 ​

退出码的数值、含义与场景以退出码与解析错误为单一真源,本页不再重复。

软告警(warn 级)不影响退出码。解析错误的提示格式与 release 透传差异见退出码与解析错误。

诊断类命令语义:

  • status / usage show 只汇总现状,退出码恒 0;toolkit status --check 例外——存在 error 级问题时退出 1
  • usage data doctor 输出问题与修复建议,退出码恒 0
  • check(task check、docs theme check、docs nav check、docs dist check)发现问题时退出 1,可直接作为门禁步骤

相关页面 ​

MIT 开源协议