# @fxri/toolkit 中文文档

规范地址：https://npmcn.com/package/%40fxri/toolkit/

版本：1\.16\.15
npm 元数据更新时间：2026-11-14T01:26:01.935Z
中文译文更新时间：2026-11-15T19:36:44.939Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fxri/toolkit
原文对照：https://npmcn.com/package/%40fxri/toolkit/?lang=original
项目主页：https://fxri-net.github.io/toolkit/
源码仓库：https://github.com/fxri-net/toolkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，46 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：4 个
- 首次发布：2026-09-02T15:13:16.680Z
- 最新版本发布：2026-11-14T01:26:01.700Z
- 近 30 天下载量：7739（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 98 个）

## 中文简介

专为多人 + AI 跨项目协作打造：任务管理与配套的规范沉淀、规则、技能分发为主，附带多语言 CHANGELOG 与文档站。

## 安装

```sh
npm install @fxri/toolkit
```

也可以使用：`pnpm add @fxri/toolkit`、`yarn add @fxri/toolkit`、`bun add @fxri/toolkit`

## README

![方弦工具集](https://npmcn.com/package/%40fxri/toolkit/docs/public/logo.png)

# 方弦工具集

[![CI](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@fxri/toolkit)](https://www.npmjs.com/package/@fxri/toolkit) [![Node](https://img.shields.io/badge/node-%E2%89%A520.19-brightgreen)](https://npmcn.com/package/%40fxri/toolkit/docs/getting-started.md#%E5%AE%89%E8%A3%85) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://npmcn.com/package/%40fxri/toolkit/LICENSE) [![文档站](https://img.shields.io/badge/docs-fxri--net.github.io%2Ftoolkit-blueviolet)](https://fxri-net.github.io/toolkit/)

> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/toolkit)（与 GitHub 同源同步，仓库/文档/issues/skills 全渠道可用）。 问题反馈走 [GitHub Issues](https://github.com/fxri-net/toolkit/issues)， 或 [Gitee Issues](https://gitee.com/fxri/toolkit/issues)。

专为**多人 + AI 跨项目协作**打造：任务管理与配套的规范沉淀、规则、技能分发为主，附带多语言 CHANGELOG 与文档站。

AI 参与开发后，方案与决策散落在对话记录里，会话一关什么都不剩；任务记录零散，谁在做、做到哪，无从查起； 发版 CHANGELOG 还要人肉维护多语言。本工具把这条链路沉淀为**仓库内可检索、可校验、可归档的文件**——人离开会话，记忆留在仓库里。

除任务主线外，CLI 还提供规范载体（conventions）、技能分发（skills）、规则组合（rules）、文档站校验（docs）与使用统计（usage）。

-   **零依赖 AI 技能包（skills）**：方案落盘、会话收尾、发版 CHANGELOG 等工作流沉淀为 Agent Skills，不绑定任何 AI 工具；skills 可以独立工作， CLI 是可选加速——推荐都装，体验最完整（[什么关系？](https://npmcn.com/package/%40fxri/toolkit/docs/faq.md#%E5%B7%A5%E5%85%B7%E5%92%8C-skills-%E9%83%BD%E5%BE%97%E8%A3%85%E5%90%97)）
-   **不懂 AI 也能用**：任务管理与多语言 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](https://npmcn.com/package/%40fxri/toolkit/docs/getting-started.md#%E5%87%A0%E4%B8%AA%E6%9C%AF%E8%AF%AD-%E5%85%88%E8%AF%B4%E4%BA%BA%E8%AF%9D)）

## 🚀 30 秒上手

```bash
# 1. 项目内安装（推荐，团队共享版本）
pnpm add -D @fxri/toolkit

# 2. 初始化任务区（生成 .tasks/ 骨架、conventions/ 规范载体与技能入口壳；含本地依赖时写入 prepare 刷新钩子）
pnpm exec toolkit init

# 3. 查看任务总览
pnpm exec toolkit tasks
```

之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。 多任务 / 多仓方案先出纯展示计划表，确认后说「开始」即一次建完全部任务档并校验，再按序逐个交付提交。 完整步骤见 [快速开始](https://npmcn.com/package/%40fxri/toolkit/docs/getting-started.md)。

## ✨ 能力矩阵

| 能力 | 适用场景 | 文档 |
| --- | --- | --- |
| 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli.md) · [任务文件规范](https://npmcn.com/package/%40fxri/toolkit/docs/guide.md#%E4%BB%BB%E5%8A%A1%E6%96%87%E4%BB%B6%E8%A7%84%E8%8C%83) |
| 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli/changelog.md) |
| 协作规范载体（conventions） | 把任务里提炼的规范收进 `.tasks/conventions/`，成为可检索、可校验的项目规范源；支持结构升级、表格形态归一与只读体检 | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli.md) · [完整攻略](https://npmcn.com/package/%40fxri/toolkit/docs/guide.md#conventions-%E8%A7%84%E8%8C%83%E6%B2%89%E6%B7%80%E5%9C%B0) |
| AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活；装了可一键分发技能（`--scope project` 随仓库入库、队友 clone 即用） | [完整攻略](https://npmcn.com/package/%40fxri/toolkit/docs/guide.md#ai-%E6%8A%80%E8%83%BD%E5%8C%85-skills) · [常见问题](https://npmcn.com/package/%40fxri/toolkit/docs/faq.md#%E5%B7%A5%E5%85%B7%E5%92%8C-skills-%E9%83%BD%E5%BE%97%E8%A3%85%E5%90%97) |
| 全局规则（rules） | 按模块组合、排序与复制 AI 全局规则（含提交信息、技能使用情况等模块），预设与缓存随包分发 | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli/rules.md) |
| 技能使用统计（usage） | 统计技能调用次数、触发词与结果；默认关闭、不联网、数据只留本机 | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli/usage.md) · [使用统计](https://npmcn.com/package/%40fxri/toolkit/docs/usage/index.md) |
| 文档站工具（docs） | 校验主题一致性、导航结构与构建产物，规则随包分发、跨仓样式漂移可发现 | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli/docs-theme.md) · [docs 校验](https://npmcn.com/package/%40fxri/toolkit/docs/cli/docs-check.md) |
| 隐私脱敏 | 落盘前自动掩码邮箱、手机号、密钥等 | [配置参考](https://npmcn.com/package/%40fxri/toolkit/docs/config.md) |
| 配置文件 | 三层（全局 / 项目 / 本地）定制脱敏、告警、导入列映射、语言表；`toolkit config status` 只读查看生效情况与来源 | [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli/config.md) · [配置参考](https://npmcn.com/package/%40fxri/toolkit/docs/config.md) |
| Node API | 把上述能力嵌进脚本或平台 | [API 参考](https://npmcn.com/package/%40fxri/toolkit/docs/api.md) |

## 📚 文档

| 文档 | 适合谁 |
| --- | --- |
| [快速开始](https://npmcn.com/package/%40fxri/toolkit/docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
| [推荐技能包](https://npmcn.com/package/%40fxri/toolkit/docs/packages.md) | 按场景选择技能源（含 playbook 等外部来源） |
| [操作手册](https://npmcn.com/package/%40fxri/toolkit/docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
| [完整攻略](https://npmcn.com/package/%40fxri/toolkit/docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
| [CLI 参考](https://npmcn.com/package/%40fxri/toolkit/docs/cli.md) | 查命令、参数、默认值、退出码 |
| [API 参考](https://npmcn.com/package/%40fxri/toolkit/docs/api.md) | 作为库引入 Node 项目 |
| [配置参考](https://npmcn.com/package/%40fxri/toolkit/docs/config.md) | 查配置文件字段（全局 / 项目 / 本地三层） |
| [使用统计](https://npmcn.com/package/%40fxri/toolkit/docs/usage/index.md) | 启用后可查技能调用次数、触发词与采集边界 |
| [更新日志](https://npmcn.com/package/%40fxri/toolkit/docs/changelog.md) | 查各版本变更内容 |
| [常见问题](https://npmcn.com/package/%40fxri/toolkit/docs/faq.md) | 遇到问题先来这里找 |
| [全局规则索引](https://npmcn.com/package/%40fxri/toolkit/docs/rules/index.md) | 规则组合器：6 个模块自由勾选、排序与一键复制 |
| [推荐 AI 全局规则](https://npmcn.com/package/%40fxri/toolkit/docs/rules/ai.md) | 想让 AI 助手按本工具的最佳实践协作 |
| [推荐提交信息规则](https://npmcn.com/package/%40fxri/toolkit/docs/rules/commit.md) | 想让 AI 按统一格式写 git 提交信息 |
| [技能使用情况规则](https://npmcn.com/package/%40fxri/toolkit/docs/rules/usage.md) | 启用本机使用统计后，约束 AI 不重复补记、不外传数据 |
| [完整文档站](https://fxri-net.github.io/toolkit/) | 在线阅读体验 |

## 🧩 AI 技能包（skills）

```bash
pnpm add -g @fxri/toolkit && toolkit skills install   # 装了 CLI 一键分发（npm 用户：npm i -g @fxri/toolkit）
toolkit skills install --scope project                # 项目面分发：真源与入口薄壳随仓库入库、队友 clone 即用
pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器（npm 用户：npx skills add fxri-net/toolkit）
```

技能随包分发（真源为包内 `skills/`），与 CLI 同一发布批次（技能内容版本独立编号）。

-   **默认形态**：`toolkit skills install` 默认软链，链接创建失败自动降级副本；`toolkit skills status` 查现场，`toolkit skills uninstall` 卸载
    
-   **交互两步**：先按 `metadata.tier` 选技能，再选目标（`canonical` 主目标 + 已检测 agent；项目面为候选薄壳目录）
    
    -   `core`：`fxri-plan-to-task`、`fxri-session-recap`、`fxri-plan-review`，`skills` 模式必装、`package` 模式可选
    -   `optional`：`fxri-release-changelog`、`fxri-text-encoding`
-   **跳过交互**：`--skills` / `--all` / `--no-optional` / `--agent` / `--all-agents` / `--yes` 首次按模式默认（`skills` 装 `core`、`package` 零装）与全部可用目标，`--no-save-agents` 只影响本次
    
-   **模式**：`--mode package` 切纯包管理器模式（core 也可不装、允许零选），`--no-skills` 仅本次零装 选择集分别写入 `~/.toolkitrc.json` 的 `skillsInstall` 与项目层 `.toolkitrc.json` 的 `projectSkills`
    
-   **外部来源**：`--from <path|url>` 临时纳入（副本、只写本次），加 `--save [name]` 登记为永久来源（默认软链）；`toolkit skills sources` 查看 / 注销来源
    
-   **作用域**：`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳， 随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐
    
-   [fxri-plan-to-task](https://npmcn.com/package/%40fxri/toolkit/skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（任务分解与纯展示计划表、一次建完全部任务档、check、归档 + 任务级规范沉淀为强制终点）
    
-   [fxri-release-changelog](https://npmcn.com/package/%40fxri/toolkit/skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
    
-   [fxri-session-recap](https://npmcn.com/package/%40fxri/toolkit/skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
    
-   [fxri-plan-review](https://npmcn.com/package/%40fxri/toolkit/skills/fxri-plan-review/SKILL.md)：复核已落档任务拆分，输出新增疏漏、建议与修订计划表，按后续是否落档标记
    
-   [fxri-text-encoding](https://npmcn.com/package/%40fxri/toolkit/skills/fxri-text-encoding/SKILL.md)：文本字节形态基线（文件、管道、命令行、API 请求体，含临时脚本与一次性命令）， 非 ASCII 文本丢失 / 乱码与首行报错的定位与修复
    

skills 与工具的关系、只在公司项目激活等说明见 [常见问题](https://npmcn.com/package/%40fxri/toolkit/docs/faq.md) 与 [完整攻略](https://npmcn.com/package/%40fxri/toolkit/docs/guide.md#ai-%E6%8A%80%E8%83%BD%E5%8C%85-skills)。

## 📦 安装

```bash
pnpm add -D @fxri/toolkit        # 项目 devDependency（团队项目推荐，版本随仓库锁定）
pnpm i -g @fxri/toolkit          # 全局（个人多项目推荐；pnpm 不受 nvm 切版本影响）
pnpm dlx @fxri/toolkit tasks     # 不安装临时执行
```

npm / yarn / bun 用户与各方式对比见 [快速开始 · 安装](https://npmcn.com/package/%40fxri/toolkit/docs/getting-started.md#%E5%AE%89%E8%A3%85)。

## 🔒 隐私脱敏

落盘记录默认脱敏敏感信息：内置邮箱、手机号、身份证、IPv4、内网 URL、JWT、AWS / GitHub / OpenAI / Slack 密钥等 13 类规则， 支持自定义规则与禁用。开关三档（CLI 参数 > 环境变量 > 配置文件），详见 [配置参考](https://npmcn.com/package/%40fxri/toolkit/docs/config.md)。

## ⚙️ 环境要求

-   Node.js >= 20.19.0（更低版本可安装，changesets 相关子命令不可用，见 [常见问题](https://npmcn.com/package/%40fxri/toolkit/docs/faq.md#node-18-%E8%83%BD%E7%94%A8%E5%90%97)）

## 📄 版权信息

作者：唐启云 [tqy@fxri.net](mailto:tqy@fxri.net)

出品：方弦研究所

版权：Copyright © 2026 唐启云. All rights reserved.

网站：[方弦研究信息网](https://fxri.net:444/)

协议：[MIT License](https://npmcn.com/package/%40fxri/toolkit/LICENSE)

商标："方弦®"为第42类注册商标（注册号89648411），本开源许可不授予商标使用权，详见 [TRADEMARK.md](https://npmcn.com/package/%40fxri/toolkit/TRADEMARK.md)

> 方弦研究所为唐启云个人项目品牌与出品方，非独立法人实体；本软件著作权归唐启云所有。

## 常见问题

### @fxri/toolkit 是什么？

专为多人 \+ AI 跨项目协作打造：任务管理与配套的规范沉淀、规则、技能分发为主，附带多语言 CHANGELOG 与文档站。

### 如何安装 @fxri/toolkit？

在项目目录运行 npm install @fxri/toolkit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 toolkit，可以用 npx toolkit 直接运行。

### @fxri/toolkit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fxri/toolkit 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fxri/toolkit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fxri/toolkit 可以商用吗？

@fxri/toolkit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fxri/toolkit 的下载量有多少？

根据 npm 官方下载统计，@fxri/toolkit 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,739 次，日均约 258 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fxri/toolkit 还在维护吗？

最新版本 1\.16\.15 发布于 2026/11/14（1 天前）；至今共发布 98 个版本，其中过去 12 个月发布了 98 个；首次发布于 2026/09/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。