Skip to content

常见问题 ​

目标读者:遇到疑问来查答案的用户(含不熟悉 AI 生态的)。按主题分组,先答结论再给细节。

解决什么问题 ​

快速开始讲最短路径、完整攻略讲全流程,但真实使用中的疑问是碎片化的。本篇按「问题 → 答案」直给。同一事实只在真源页维护一次:本篇只给结论与该问题特有的差异,细节指回真源。没找到答案可去提问:

安装与环境 ​

工具和 skills 都得装吗? ​

不是都得装。skills 独立可用,工具是可选加速:只装 skills 时 AI 照着技能里的规范纯手工跑通建档、校验、归档全流程(零依赖,纯 Markdown); 只装工具时人可以用 CLI,但 AI 侧没有规范指引;两者都装时 AI 自动校验、自动归档,体验最完整(推荐)。 一句话:skills 教 AI 怎么做,CLI 帮人(和 AI)做得快。 安装顺序见快速开始 · 安装:全局装 CLI → toolkit skill install → toolkit rule compose。

个人用,全局装还是每个项目里装? ​

个人多项目默认双全局,一次配置所有项目直接可用:全局装 CLI + toolkit skill install, 再按需 toolkit rule compose 组合自己的全局规则(三步命令见快速开始 · 安装)。 升级一条命令:pnpm add -g @fxri/toolkit。 软链模式下技能随包自动更新;副本形式需重跑 toolkit skill install;skills 升级后开新会话,见「升级后要注意什么」。

诚实代价:全局装的版本不随项目锁定,团队里会出现「各装各的」版本漂移。 所以团队项目推荐工具走项目 devDependency、技能装进项目(--scope project),也可用上游安装器项目级安装并把 skills-lock.json 提交进仓库锁版本。 只想在公司项目生效见下文「只在公司项目激活」。

我只想当技能包管理器,不想装自带技能? ​

用 toolkit skill install --mode package 切换到纯包管理器模式:core 也不再强制,可以一个都不选。 之后按 --source <name|path> --skills <names> 只装外部来源技能。 只想本次零装、不改长期模式时用 --no-skills,它与 --skills / --all / --no-optional / --mode 互斥。

项目内装的技能放在哪、队友 clone 后要重装吗? ​

项目面分发(toolkit skill install --scope project;--scope 缺省时项目内装的 CLI 会自动走此面)只保留一份唯一真源:<仓库根>/.agents/skills/。 其余已存在的候选目录各放每个技能一个 SKILL.md 薄壳,description 从真源派生、正文指明真源路径与版本标记,不重复承载内容。 某个候选目录不存在就不凭空创建,候选目录清单见 配置参考 · 作用域与安装面。真源、薄壳与归属账(<仓库根>/.toolkit/state.json)都要入库。 队友 clone 后不必逐台手动重装:prepare 刷新钩子在 pnpm install 时自动刷新已有产物(仅当本地依赖含 @fxri/toolkit),也可手动重跑 install。 现场用 toolkit skill status --scope project 查,清理用 toolkit skill uninstall --scope project --all(只摘本包登记的产物)。

⚠️ 发布型包要把这些产物加入 files 白名单或 .npmignore,否则 npm 无 .npmignore 时可能被打进包。 toolkit init 会提示但不代改,完整说明见完整攻略 · Git 纳管范围。

用 nvm 切了 Node 版本,全局装的 toolkit 不见了? ​

全局包绑定在安装时的 Node 版本上,切版本后各版本的 node_modules 相互独立。这是 nvm 类工具的机制,不是本工具的问题。 处置三种:新版本下重新安装(pnpm add -g @fxri/toolkit 或 npm add -g @fxri/toolkit); 改用 pnpm 全局安装(pnpm 全局目录独立于 Node 版本);团队项目改用项目 devDependency 方式,不受切版本影响(见快速开始 · 安装)。

Node 18 能用吗? ​

能。运行时下限为 Node.js >= 18.17.0,全部命令(含交互式选择与 release 透传子命令)在该版本上可用。 Node 18 已于 2025-04 EOL,只保证可运行、不再有安全补丁,条件允许时建议升级到 Node 20.19+。 低于 18.17.0 时 CLI 会输出中文提示并以非 0 退出,不静默降级。 CLI 只使用该基线已稳定的 API,高版本才有的内置不会进入运行路径。 Node 19 / 21 / 23 等非 LTS 版本只保证命令可运行,不纳入测试套件回归;开发测试以 20 / 22 / 24 LTS 为基线。

内网或离线环境怎么装? ​

先判断你的网络卡在哪一档:

  • 只卡 GitHub(npm registry 可达,最常见):CLI 照常用 pnpm add -g @fxri/toolkit 装;skills 随包分发、不走 GitHub,直接一键分发:

    bash
    toolkit skill install   # npm 用户先 npm add -g @fxri/toolkit

    若仍想用上游安装器,也可把已装 CLI 包目录当本地源:

    • pnpm:pnpm dlx skills add "$(pnpm root -g)/@fxri/toolkit" --global
    • npm:npx skills add "$(npm root -g)/@fxri/toolkit" --global
  • registry 也不可达(完全离线):换一台能联网的机器执行 pnpm pack @fxri/toolkit(npm 用户 npm pack)。 把打出的 tgz 拷进内网后 pnpm add -g <tgz 路径> 离线装 CLI,再 toolkit skill install——技能随包分发,全程不碰 GitHub。

  • GitHub 有代理或镜像:pnpm dlx skills add fxri-net/toolkit --global 直连即可,与正常安装无异。

国内网络优先走哪条渠道? ​

Gitee 镜像 与 GitHub 同源同步,国内访问最省心:

  • 源码浏览 / 克隆:https://gitee.com/fxri/toolkit
  • skills 安装:装了 CLI(走 npm registry)后直接 toolkit skill install,技能随包分发、不碰 GitHub。
  • 上游安装器:只认 GitHub 源与本地路径。GitHub 不稳时先 clone 镜像、再对本地目录安装:
    bash
    git clone https://gitee.com/fxri/toolkit fxri-toolkit
    pnpm dlx skills add fxri-toolkit --global    # npm 用户把 pnpm dlx 换成 npx
  • CLI 本体与 npm 源提速:CLI 走 npm registry,与镜像无关;提速可 pnpm config set registry https://registry.npmmirror.com (npm 用户把 pnpm config 换成 npm config)

之前用 npx skills 装过,改用内置命令提示同名冲突怎么办? ​

上游安装器把技能落成 ~/.agents/skills/ 下的实体副本,且不在本包状态文件 ~/.agents/.toolkit-skills.json 的登记内。 内置命令因此把它判为「同名非本包产物」并报成「同名冲突」。一条命令接管:

bash
toolkit skill install --force   # 把各目标下的同名旧副本重建为软链(无权限建链时降级为副本)

--force 只解除「同名非本包产物」的跳过判定,按默认形态重建这些未登记的目录;本包自己以 --copy 装出、且已在状态文件登记的副本不受影响。

⚠️ 迁移后两条路径不要混用:再跑 pnpm dlx skills update -g(npm 用户 npx skills update -g)会把该目录重写回实体副本,冲突复发。 迁移后 skills-lock.json 不再被任何一方维护,可删除,避免与内置命令的真实状态不一致。

卸载工具时 skills 怎么办? ​

先清技能、再卸工具:toolkit skill uninstall --all → pnpm remove -g @fxri/toolkit。 ⚠️ 顺序别反:skill uninstall 要靠 CLI 与包内真源定位产物,CLI 卸了就没工具可用(重装一次再清即可)。 软链会随 CLI 卸载悬空,remove 会一并摘除,漏摘时手工删 ~/.agents/skills/ 与各 agent 全局技能目录下的 fxri-* 链接。 项目面产物用 remove --scope project 单独清(实体副本不随 CLI 卸载悬空)。完整步骤见操作手册 · 升级与卸载。

技能与规则 ​

skills 是什么?和插件、脚本有什么区别? ​

skills 是给 AI 编程助手看的「岗位说明书」:一份 Markdown 文件,写清楚某类工作(比如方案落盘、发版)的流程和规范。agent 遇到对应任务时自动读取并照着执行。 与插件/脚本的区别:它不是可执行代码,没有安装依赖、没有版本运行环境问题,任何兼容 Agent Skills 标准的 AI 工具(Trae、Claude Code、Cursor、Codex 等)都能直接读。 缺点也来自这里:它依赖 AI 去执行,所以配套 CLI 做自动校验兜底。

skills 需要额外的仓库参考文件吗? ​

不需要。技能是自包含的:SKILL.md 主干 + 规范细节(references/)+ 模板资产(assets/)都在技能目录内,装好即完整,AI 拿到就能按规范执行。 唯一例外:只装 skills、未装 CLI,且项目里没有仓库根 SPEC.md 时,建档格式需按任务文件规范参照。 装齐 CLI 或放一份 SPEC.md 即可消除。

我不用 AI,这个工具对我有用吗? ​

有用。任务管理(建档、校验、归档、导出报表)和 CHANGELOG 格式化都是纯 CLI 能力,不涉及 AI; 规范载体体检、规则组合、文档站校验与使用统计同样不依赖 AI,skills 部分不装即可。

配好全局规则后,我就完全不用管了?AI 能全程自主吗? ​

日常可以做到零操作:建档、校验、归档与规范沉淀全部由 AI 按全局规则自主完成,你只说自然语言。AI 完成后会回报清单请你确认——这是防写错仓库文件的安全设计,不是操作负担。 三个时刻仍需你出手:首次安装(AI 规则明确不自行全局安装)、升级后开新会话、工具不可用时手动保存兜底方案。详见快速开始 · AI 用户。

我说了"开始",AI 却反问或没动? ​

开工只认明确的开工词,且要范围明确、方案已定稿;「可以 / 定稿 / 落档」这类回应不会让它动手。说得像开工但没命中时,AI 会反问一句; 回「嗯 / 行吧」这类含糊答复仍不会开工,需要给到开工词或明确说「就按你说的做」。判定口径见操作手册。

AI 沉淀会话时,记什么不记什么? ​

只沉淀工作产出:功能改动、结论、以及对话中产生的决策及其理由(「为什么选方案 B 不选 A」——决策散落在对话里,会话一关就丢)。与产出无关的闲聊不记录;你明确要求记录的内容 AI 照记。

技能次数正常,但触发词 / 参数 / 结果是空的? ​

这是规则通道的预期表现:规则只上报技能名与次数,触发词、参数、结果与耗时靠工具反查会话记录补齐。读不到记录时字段留空,计数不受影响。 常见原因有三种:该 Agent 的会话正文不落可读文件(Trae)、会话格式尚未适配(dsh 为 v4 事件流)、或会话记录已过期被清理。 补救两种:toolkit usage log --skill <名称> --session <id> --prompt "…" --args "…" --outcome success 手工补录; 或改用 Hook 通道(toolkit usage config channel hook)。两种方式只对之后的事件生效。完整说明见 Agent 接入 · 拿不到明细时的补救。

⚠️ 升级 Node 或安装 zstd 不会让 dsh 明细出现——它的会话格式尚未适配。

只在公司项目激活,个人项目不被插入怎么做? ​

全局装 skills 后,可以先用 toolkit scope 设置生效范围(只在我选的目录 / 除了我选的目录),再在公司项目根的 AGENTS.md / 项目 rules 中显式引用 fxri 技能并提交;个人项目不放引用文件即可。 需要按技能维度收口时,用 toolkit scope skills allow/deny 或 toolkit scope policy add 写策略规则(条件 + 技能维度)。 介于两者之间可用内容闸门(toolkit skill install --gate):技能壳仍全局可见,正文按作用域由 toolkit scope guard 下发。 需要绝对隔离(技能物理不在场)时用 toolkit skill mount <父目录> 批量做项目面安装。 兼容 agent 仍可能按 description 匹配自动触发,若需要稳定启用(而非碰运气触发),个人项目同样建议显式声明。 模板见完整攻略 · 项目级激活模板,判定与范围配置见作用域配置。

想让技能正文只在激活项目加载,怎么做? ​

默认全局技能是全文安装,description 命中即整篇进入上下文。矩阵策略限制的技能会自动改为入口壳; 也可用 skillDelivery 规则或 toolkit skill install --gate 显式指定: 技能只保留 name / description 与一句「先运行 toolkit scope guard <技能名>」,正文由 guard 按当前目录判定—— 激活时输出正文,未激活以未激活退出码结束(stdout 为空,见退出码)。 --embed 可把本次安装回退全文;旧键 skillInstall.gate 与技能声明 metadata.gate: false 仍读时兼容。 契约见 技能分发 与 作用域 · 内容闸门。

⚠️ 入口壳只降低正文被读取的概率,不是物理隔离;需要绝对干净用 toolkit skill mount 或 toolkit skill install --scope project。

任务与流程 ​

.tasks/ 要提交到 git 吗?哪些文件该提交? ​

.tasks/ 整体(active + archive)必须入库——任务记录是团队共享的工作记忆。 .toolkitrc.json 建议提交,.toolkitrc.local.json 应忽略(toolkit init 自动写忽略行,存量项目重跑 init 幂等补写)。 .archive.lock 为运行时锁、默认忽略。完整纳管表见完整攻略 · Git 纳管范围。

我一个人用,还有必要提交任务记录吗? ​

建议提交。除多人协作外,任务记录还是跨会话的上下文载体:AI 的新会话读不到旧会话的对话内容,但能读仓库里的任务文件——这正是「新会话恢复上下文」能力的基石(见下文「AI 换了个会话就不记得之前聊的了」)。

AI 换了个会话就不记得之前聊的了,怎么办? ​

这是所有 agent 的共性约束:新会话读不到其他会话的内部上下文。解法是把记忆沉淀进仓库文件(.tasks/)。会话结束前说「今天先到这 / 收个尾」,AI 全量回放本会话、清单经你核对后落盘归档并做规范沉淀。 新会话开头说「恢复上下文 / 上次做到哪了」,AI 读 active 全部与近窗归档接上现场。完整流程见完整攻略 · 会话沉淀、恢复与历史修正。

为什么 AI 建的档 check 不过? ​

常见原因三种:文件放错层级(必须在 active/{YYYYMM}/ 下,漏掉月份目录会软告警且不被读取)、created 与文件名日期前缀不一致、终结态缺 completed。 跑 pnpm exec toolkit task check,按输出逐条修即可。建档交给 AI 时说「按 fxri-plan-task 技能建档」可从源头避免。

归档提示「本次无可归档任务」? ​

任务文件的 frontmatter 里 status 仍是 待办/进行中/阻塞/搁置(这四类都不归档),或终结态但缺 completed 完成时间(会明确提示跳过)。先打开任务文件确认 frontmatter 状态。

归档后发现敏感信息没脱敏? ​

脱敏只作用于终端展示、导出文件与归档落盘。.tasks/active/ 源文件按原样保存(设计如此,不改动原始正文)。 若某类信息未被掩码,可能未命中内置规则:团队规则加到 .toolkitrc.json;个人规则加到 .toolkitrc.local.json (仅本人可见、默认不入库),见配置参考 · 隐私脱敏。

除了开发,产品经理、项目经理这类非开发角色能用吗? ​

能用。任务管理部分对所有角色开放。产品经理把需求清单整理成 Excel/CSV(列名用「任务名/负责人/截止日期」等常见叫法即可), 让 AI 执行导入(toolkit task import 需求.xlsx)转成规范任务文件,内置中文列名映射、非标准列可用配置自定义。 项目经理按负责人/状态过滤总览、导出 XLSX 汇报;测试、运维同样适用。发版部分面向有发版需求的软件项目。角色速查表与边界说明见快速开始 · 谁适合用。

任务做完必须马上归档吗?能不能攒一批? ​

工具不强制,但强烈建议随完成随归档:若提交代码,先归档与沉淀、后提交,归档文件与代码变更落同一 git 提交是本工作流的核心纪律。 滞留 active 的任务会丢失「完成时间→提交」的对应关系,攒批归档则把这个缺口拉大。团队可在 CI 或 code review 中检查。

多人同一天归档,pull 时归档文件冲突了怎么办? ​

归档文件按完成日期聚合成单一文件(archive/{YYYYMM}/{YYYYMMDD}.md)。多人同天归档、各自先提交后拉取时,git 会在同一文件上留下冲突标记。 不用手工逐块合并:跑 toolkit task normalize --fix 即可。工具取冲突两侧的任务块并集、按标题去重、按完成时间降序重排, 丢弃 diff3 的 ||||||| base 段与全部标记行,得到无标记的规范归档文件(normalize 只读检查与 task check 也会先把这类文件报出来)。 若由 AI 代为推送与拉取,可让其冲突后直接执行该命令收敛。

项目里已有历史的 .tasks/conventions.md,怎么升级到新形态? ​

说一句「把项目里的 conventions.md 迁到新形态」即可,AI 按三段式执行且中途停下也不丢内容。 旧文件整体搬为 index.md 后即原文快照,步骤与可中断说明见操作手册 · 规范载体迁移。

载体已经是 conventions/ 目录了,还要升级什么? ​

目录形态另有结构版本:最新为 v3 三分区(常驻 index.md、按需分册、归档面 history.md / retired.md,索引表首列为稳定 ID C-<n>); v2 有标记与稳定 ID 但无归档面,v1 连标记都没有。 升级说一句「把规范载体升到 v3」,或跑 toolkit convention upgrade:--dry-run 预演、幂等、异常形态拒绝写盘,v1 / v2 链式升级。 各版本差异见完整攻略 · 存量规范载体迁移。

载体表格里为什么有大量空格?怎么去掉? ​

那是宿主格式化器(prettier)对 GFM 表格做列对齐填充的结果,预览不显示、纯文本阅读时干扰。 两种处置:toolkit init 在检测到 prettier 时幂等托管 .prettierignore 把任务区排除; 已存在的填充用 toolkit convention format 归一回紧凑形态(幂等、跳过 fenced code block)。详见完整攻略 · 表格形态。

toolkit init 生成的「规范入口壳」是什么?必须留着吗? ​

它是在已存在的项目级技能目录(如 .agents/skills/toolkit-conventions/SKILL.md)生成的只作入口、不承载条文的小技能壳。 多个候选目录并存时每处各写一份,一个都不存在则回落 .agents/skills/;壳让 AI 在项目里能按需发现 .tasks/conventions/ 载体,正文指回 index.md。 它属侵入性写入,init 会逐项报告实际动作。落点被 .gitignore 覆盖时报告会提示(不代改 .gitignore),因为那样壳不会随 git 分发。 不需要可直接删除,重跑 init 会补回;壳标记落后于当前 toolkit 时,重跑 init 会就地更新为当前版本。

⚠️ 若只是某条旧规范过时(不换形态),走内容修订而非迁移:语义变更先在 history.md 留痕、再更新索引行;作废则迁入 retired.md 并删分册条文。 口径见完整攻略 · conventions/,场景说法见操作手册 · 规范载体迁移。

发版与升级 ​

升级后要注意什么? ​

技能默认自动跟随 CLI 升级(软链锚在 pnpm 稳定入口)。 用了 --copy 或建链失败降级为副本的需重跑 toolkit skill install,项目面由 prepare 钩子自动刷新;三种情形都要开新会话才读到新技能。 升级命令与三步检查见操作手册 · 升级,Node 版本兼容见完整攻略 · 升级与版本兼容。

任务做完必须提交、发版、推送吗? ​

都不必须。任务工作流的强制约束到沉淀为止:任务置终结态(已完成/已放弃 + completed)并归档,再做任务级规范沉淀,归档 + 沉淀即流程终点。提交、发版、推送由你的规则约定,也可在当次指令里直接授权。 ⚠️ 唯一保留的顺序约束:若提交代码,必须先归档与沉淀、再跑项目验收命令、后提交(验收须晚于归档)。 归档文件、规范变更与代码变更落在同一 git 提交,完整口径见完整攻略 · 方案落盘工作流。

提交信息有格式要求吗? ​

本工具不强制 commit 格式;需要统一时可用 toolkit rule 的 commit 模块取模板(提交信息规则),采纳与否仍由团队规则决定。

fork 本仓库怎么部署文档站? ​

文档站固定部署 GitHub Pages,fork 后调整 VITEPRESS_BASE 即可自动构建发布,详见完整攻略 · 文档站部署。

相关页面 ​

MIT 开源协议