Skip to content

操作手册 ​

目标读者:任何想用起来的人——完全不熟命令的零基础用户、只用 AI 不想碰命令的用户、想自己手操 CLI 的用户。按「场景 → 该说什么/做什么 → 会发生什么」组织;每节末尾的「更多」指向对应文档。

本篇只讲怎么用:每个场景说什么、做什么、会发生什么;机制原理、边界与细节取舍见完整攻略。

一、首次使用 ​

目标:装好工具 + skills,跑通一条任务闭环。命令细节与三种安装方式对比见快速开始 · 安装。

步骤该做什么
1 装 CLI个人多项目 pnpm add -g @fxri/toolkit(默认,配合全局技能与全局规则);团队项目 pnpm add -D @fxri/toolkit(版本随仓库锁定)
2 装 skillstoolkit skill install;项目面用 --scope project(技能随仓库入库、队友 clone 即用)
3 配全局规则(推荐)toolkit rule compose 交互式选择后粘贴到所用 Agent 的全局规则入口;也可从 AI 全局规则 复制模板,提交习惯另取提交信息规则
4 建任务区对 AI 说「初始化任务区」(AI 执行 toolkit init 并完成建档;也可自己运行 toolkit init)

初始化做了什么、30 秒最短路径见快速开始 · 30 秒上手。

二、日常开发 ​

目标:方案确认后,任务被记录、跟踪到归档。

落档与收尾按语义,开工按关键词:建档、收尾、恢复这类动作按意图理解触发——说意思即可(如「今天先到这」代表收尾、「上次做到哪了」代表恢复), 不必记固定句式;开工是例外,只认明确的开工词(开始 / 开工 / 动手 / 执行 / 落地 / 按计划做 / 照这个做), 且要范围明确、方案已定稿——「可以 / 定稿 / 落档 / 继续评估」都不会让 AI 开始改代码; 说得像开工但没命中这些词时,AI 会反问一句,既不静默也不自行开工。 各能力完整触发描述见对应 SKILL.md 的 description 与「何时使用」节。

你该说会发生什么
「把刚才确认的方案落盘为任务」AI 按 fxri-plan-task 在 .tasks/active/ 建档(先查后写防重复)
(方案定稿后)「开始 / 开工 / 按计划做」AI 识别为开工授权:先一次建完全部任务档并校验,再动手
(方案定稿后)「记一下 / 先落档 / 方案可以」仅建档或停在定稿态,不视为开工;之后说「开工」只补缺档、不重复建档
开工后被打断,再说「继续」恢复执行:先回显恢复哪项,再复核现场(改动、任务档锚点),然后接着做
「继续评估 / 再看看」仍是讨论态,不写文件
方案涉及多个任务或多个仓库AI 先出一张纯展示计划表(仓库 + 任务 + 前置,跨仓同表),再一次建完各任务档,按表顺序逐个交付、逐个提交
任务做完AI 置终结态 → 归档 → 任务级规范沉淀 → 回报清单请你确认
「现在有哪些没做完的任务」AI 跑总览给你

想自己手操命令时,归档、校验、归一、统计、导入导出等命令见 任务管理;手工建档模板与 frontmatter 字段见完整攻略 · 任务文件规范。 只写 AI 该怎么做:不需要懂命令,以上动作 AI 都会按 skill 自动执行,你只需在动手类任务前让 AI 先出方案、确认后再执行。

三、会话边界 ​

目标:换会话不丢上下文;决策与理由沉进仓库。

场景你该说会发生什么
会话收尾「今天先到这 / 收个尾 / 把结论记下来」AI 全量回放本会话 → 任务清单先给你核对无遗漏 → 逐条落盘归档 → 规范沉淀进 conventions 载体 → 回报
新会话开始「恢复上下文 / 上次做到哪了」AI 读 active 全部 + 近窗归档(≥1 年空洞旧档仅入索引),输出全部任务索引 + 进行中/阻塞 + 搁置项(一行计数,超 90 天的另给数量,点名才展开)+ 规范现场 + 建议下一步
有任务暂时不做「这个先放着 / 以后再说」AI 置 搁置 并在正文首个二级标题处写 ## 搁置 四行(搁置原因 / 重启条件 / 进度锚点 / 搁置日期);它不进计划表、不占「建议的下一步」,盘点用 toolkit task --status 搁置(每行附「搁置 N 天」,超 90 天标 ⚠️)
历史时间不准「修正历史任务时间」AI 对照 git log/聊天记录取证 → 清单给你逐条确认 → 修正 → normalize --fix 迁移核验

⚠️ 跨仓库会话:一次会话涉及多个仓库时,各仓的改动在各自仓库里建档归档(任务档是仓库自述,只记本仓的改动与动机),不把另一仓的工作痕迹合并进本仓记录。

时间取证的完整口径(四级时间源)见完整攻略 · 会话沉淀、恢复与历史修正。

四、规范载体迁移 ​

目标:把项目里旧的单文件 .tasks/conventions.md 升到 conventions/ 目录形态(index.md 唯一入口 + common.md / 各端分册按需创建), 让规范能按端分类、按需加载;已有目录形态但结构为旧版的载体升到 v3 三分区。

场景你该说会发生什么
形态迁移(单文件 → 目录)「把项目里的 conventions.md 迁到新形态」AI 走三段式:建 conventions/ 并把旧文件整体搬为 index.md(原文不丢)→ 逐条给出「common / 某端」归属建议 → 你逐条确认后拆成索引行 + 分册
结构升级(v1 / v2 → v3)「把规范载体升到 v3」载体升到 v3(三分区:常驻索引 / 按需分册 / 归档留痕;首行形态标记、索引表首列为稳定 ID C-<n>、索引表删「状态」「确立来源任务」两列、history.md 表头首格同为稳定 ID ID):优先 pnpm exec toolkit convention upgrade(--dry-run 预演、幂等、先判后写,异常形态拒绝写盘),亦可按链路手工执行
只修订内容(不换形态)「第 3 条规范改成 …」语义变更:AI 在 history.md 追加留痕(只追加、不改旧行)→ 更新 index.md 该行「当前语义」;规则作废走「迁出 + 三层清理」——索引行从 index.md 删除并迁入 retired.md(冻结退休时语义、记后继与条文去向),同时物理删除分册内该条小节、同步删改外部单一事实源
  • 入口:toolkit task check 报旧单文件存在 / 缺 index.md / 形态异常时按提示处理;toolkit convention status 查载体现场; 新项目 toolkit init 已预生成骨架
  • 端名与读法:端名与任务 scope 逐字一致(web+server → web.md + server.md),端清单以 index.md 顶部声明为唯一权威;迁移期间新旧兼容读, 两者并存以目录形态为准;表格被格式化器填充出空隙时用 toolkit convention format 归一

三分区、读写分层与表格形态的机制见完整攻略 · conventions/,命令契约见 规范载体。

五、数据进出(报表 / 迁移) ​

目标:任务数据与 Excel/CSV/JSON 互转,方便汇报或从旧系统迁入。

bash
# 导出:按扩展名自动识别格式(.csv 带 BOM,Excel 直开;.xlsx 三 sheet;.json 结构化)
pnpm exec toolkit task export 归档报表.xlsx --view archived

# 导入:先预演核对,再正式导入
pnpm exec toolkit task import 需求清单.csv --dry-run
pnpm exec toolkit task import 需求清单.csv --target active
  • 表头写常见叫法即可(「任务名/负责人/状态/截止日期」),中英文别名自动识别
  • 落盘自动脱敏:手机号、邮箱、密钥等掩码后再写归档
  • 列名映射定制、脱敏规则见配置参考

六、发版 ​

目标:变更集 → CHANGELOG → 发布,多语言分组标题不手翻。

bash
pnpm exec toolkit release changeset add   # 创建变更集(等价 changeset,选 patch/minor/major)
pnpm exec toolkit release audit # 可选:列出同对象净变更候选,先人工合并
pnpm exec toolkit release bump            # 消费变更集:升版本号 + 中文 CHANGELOG + 发布日期
pnpm exec toolkit release mirror          # 同步文档站更新日志镜像(bump 后也会自动同步)
# 提交 → 打 vX.Y.Z 标签 → 发布(按项目渠道,如 npm publish)

⚠️ 发版不是必经步骤:默认由你的规则约定是否执行,当次指令已含授权则直接执行;未归档的 active 任务存在时会提醒先归档。 完整链路见完整攻略 · 多语言 CHANGELOG,参数见 发版与更新日志。

七、升级与卸载 ​

目标:CLI + skills + 全局规则对齐到最新;卸载时不留残渣。

升级 ​

bash
pnpm add -g @fxri/toolkit   # 全局安装(推荐)
pnpm up @fxri/toolkit       # 项目内(版本随仓库锁定)
toolkit skill status       # 查 CLI 版本提示与技能现场

升级三步检查:

  1. CLI 更新
  2. skills 同步:软链形式随 CLI 自动更新;副本形式(--copy 或建链失败降级)需重跑 toolkit skill install;项目面由 prepare 钩子自动刷新
  3. 开新会话:旧会话加载的仍是旧版技能

⚠️ 软链落点是写入穿透形态:编辑落点文件等于编辑真源,要改技能内容请改真源(toolkit skill status 报告末尾也会提示)。

⚠️ 历史落点残留:Codex / Pi 的全局落点已改为 canonical(~/.agents/skills/),升级前分发到 ~/.codex/skills/、 ~/.pi/agent/skills/ 的产物不再随本包更新;若状态文件仍有登记且目录仍在,status 会单列提示, 用 toolkit skill uninstall --all 清理后再 toolkit skill install 恢复(只提示、不自动删除)。

规则细节已收敛进 skills,装完无需手动同步全局规则全文。CLI 检测到新版本会提示;关闭提示:FX_TOOLKIT_NO_UPDATE_CHECK=1 或配置 updateCheck.enabled: false。 版本兼容(Node 版本要求)见完整攻略 · 升级与版本兼容。

卸载 ​

bash
toolkit skill uninstall --all      # 1. 先摘技能产物(只清本包装的,不碰你自己装的技能)
pnpm remove -g @fxri/toolkit     # 2. 再卸 CLI

⚠️ 顺序别反:skill uninstall --all 依赖本工具(CLI + 包内真源)才能定位产物;先卸了 CLI,清技能就没工具可用——重装一次再执行即可。

⚠️ 软链会悬空:软链形式的技能指向包内目录,CLI 一卸就成悬空链接(agent 读到空目录)。toolkit skill uninstall --all 会把悬空链接一并摘除;若已漏摘, 手工删除 ~/.agents/skills/ 与各 agent 全局技能目录下的 fxri-* 链接。

八、隐私与安全 ​

  • 默认脱敏开启:终端展示、导出文件、归档落盘都会掩码敏感信息;.tasks/active/ 源文件保持原样(设计如此)
  • 不想某类信息被掩码、或要加自定义规则:.toolkitrc.json 的 redact 段(见配置参考 · 隐私脱敏)

相关页面 ​

MIT 开源协议