# toolkit

**Repository Path**: fxri/toolkit

## Basic Information

- **Project Name**: toolkit
- **Description**: 专为多人 + AI 跨项目协作打造：任务管理与配套的规范沉淀、规则、技能分发为主，附带多语言 CHANGELOG 与文档站。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="./docs/public/logo.png" width="128" alt="方弦工具集">
</p>

# 方弦工具集

[![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)](./docs/getting-started.md#安装)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./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 是可选加速——推荐都装，体验最完整（[什么关系？](./docs/faq.md#工具和-skills-都得装吗)）
- **不懂 AI 也能用**：任务管理与多语言 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语-先说人话)）

## 🚀 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` 归档并做规范沉淀。
多任务 / 多仓方案先出纯展示计划表，确认后说「开始」即一次建完全部任务档并校验，再按序逐个交付提交。
完整步骤见 [快速开始](./docs/getting-started.md)。

## ✨ 能力矩阵

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

## 📚 文档

| 文档 | 适合谁 |
| --- | --- |
| [快速开始](./docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
| [推荐技能包](./docs/packages.md) | 按场景选择技能源（含 playbook 等外部来源） |
| [操作手册](./docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
| [完整攻略](./docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
| [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
| [API 参考](./docs/api.md) | 作为库引入 Node 项目 |
| [配置参考](./docs/config.md) | 查配置文件字段（全局 / 项目 / 本地三层） |
| [使用统计](./docs/usage/index.md) | 启用后可查技能调用次数、触发词与采集边界 |
| [更新日志](./docs/changelog.md) | 查各版本变更内容 |
| [常见问题](./docs/faq.md) | 遇到问题先来这里找 |
| [全局规则索引](./docs/rules/index.md) | 规则组合器：6 个模块自由勾选、排序与一键复制 |
| [推荐 AI 全局规则](./docs/rules/ai.md) | 想让 AI 助手按本工具的最佳实践协作 |
| [推荐提交信息规则](./docs/rules/commit.md) | 想让 AI 按统一格式写 git 提交信息 |
| [技能使用情况规则](./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](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（任务分解与纯展示计划表、一次建完全部任务档、check、归档 + 任务级规范沉淀为强制终点）
- [fxri-release-changelog](./skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
- [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
- [fxri-plan-review](./skills/fxri-plan-review/SKILL.md)：复核已落档任务拆分，输出新增疏漏、建议与修订计划表，按后续是否落档标记
- [fxri-text-encoding](./skills/fxri-text-encoding/SKILL.md)：文本字节形态基线（文件、管道、命令行、API 请求体，含临时脚本与一次性命令），
  非 ASCII 文本丢失 / 乱码与首行报错的定位与修复

skills 与工具的关系、只在公司项目激活等说明见 [常见问题](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。

## 📦 安装

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

npm / yarn / bun 用户与各方式对比见 [快速开始 · 安装](./docs/getting-started.md#安装)。

## 🔒 隐私脱敏

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

## ⚙️ 环境要求

- Node.js >= 20.19.0（更低版本可安装，changesets 相关子命令不可用，见 [常见问题](./docs/faq.md#node-18-能用吗)）

## 📄 版权信息

作者：唐启云 <tqy@fxri.net>

出品：方弦研究所

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

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

协议：[MIT License](./LICENSE)

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

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