操作手册
目标读者：任何想用起来的人——完全不熟命令的零基础用户、只用 AI 不想碰命令的用户、想自己手操 CLI 的用户。按「场景 → 该说什么/做什么 → 会发生什么」组织；每节末尾的「更多」指向对应文档。
一、首次使用
目标：装好工具 + skills，跑通一条任务闭环。
| 步骤 | 该做什么 | 会发生什么 |
|---|---|---|
| 1 装 CLI | 团队项目：pnpm add -D @fxri/toolkit（npm 用 npx）；个人多项目：pnpm i -g @fxri/toolkit | 得到 toolkit 命令 |
| 2 装 skills | toolkit skills install（装了 CLI 一键分发，默认软链；npm 用户需先 npm i -g @fxri/toolkit）；--scope project 装进项目仓库（真源落 .agents/skills/、其余候选目录落入口薄壳，队友 clone 即用）；也可用上游安装器 pnpm dlx skills add fxri-net/toolkit --global | AI 侧获得三份岗位说明书，遇到对应场景自动触发 |
| 3 建任务区 | pnpm exec toolkit init | 生成 .tasks/active/{YYYYMM}/、archive/、conventions/index.md + history.md 骨架与 .gitignore 片段，并在项目级技能目录生成规范入口壳；项目本地依赖含 @fxri/toolkit 时写入 prepare 刷新钩子（逐项报告实际动作） |
| 4 配全局规则（可选） | 从 AI 全局规则 复制模板到你的 agent 全局 rules；提交习惯想统一再取提交信息规则 | AI 按你的纪律协作 |
三种安装方式对比、离线/内网装法见新手指南 · 安装。
二、日常开发
目标：方案确认后，任务被记录、跟踪到归档。
触发靠语义，不靠背词：fxri-* 能力是给 AI 的「岗位说明书」，按意图理解触发——你说意思即可（如「今天先到这」代表收尾、「上次做到哪了」代表恢复），不必记固定句式，不同说法都能触发。各能力完整触发描述见对应 SKILL.md 的 description 与「何时使用」节。
AI 模式（推荐，日常零操作）
| 你该说 | 会发生什么 |
|---|---|
| 「把刚才确认的方案落盘为任务」 | AI 按 fxri-plan-to-task 在 .tasks/active/ 建档（先查后写防重复） |
| （方案确认后）「按这个做吧 / 记一下」 | 同上，AI 识别为建档意图自动执行 |
| 任务做完 | AI 置终结态 → 归档 → 任务级规范沉淀 → 回报清单请你确认（提交/推送按你的规则决定） |
| 「现在有哪些没做完的任务」 | AI 跑总览给你 |
手操 CLI
pnpm exec toolkit tasks # 待完成总览
pnpm exec toolkit tasks check # 校验 active 与变更集前缀（建错会告诉你错哪）
pnpm exec toolkit tasks archive --dry-run # 归档预演，先看会归档什么
pnpm exec toolkit tasks archive # 正式归档
pnpm exec toolkit tasks normalize # 检查归档块（可 --fix 修复）
pnpm exec toolkit tasks stats # 完成周期 / 滞留 / 吞吐统计手工建档模板与 frontmatter 字段见完整攻略 · 任务文件规范。
只写 AI 该怎么做
不需要懂任何命令：以上 CLI 动作 AI 都会按 skill 自动执行。你只需要在动手类任务前让 AI 先出方案、确认后再执行。
三、会话边界
目标：换会话不丢上下文；决策与理由沉进仓库。
| 场景 | 你该说 | 会发生什么 |
|---|---|---|
| 会话收尾 | 「今天先到这 / 收个尾 / 把结论记下来」 | AI 全量回放本会话 → 任务清单先给你核对无遗漏 → 逐条落盘归档 → 规范沉淀进 conventions 载体 → 回报 |
| 新会话开始 | 「恢复上下文 / 上次做到哪了」 | AI 读 active 全部 + 近窗归档（≥1 年空洞旧档仅入索引），输出全部任务索引 + 进行中/搁置 + 规范现场 + 建议下一步 |
| 历史时间不准 | 「修正历史任务时间」 | AI 对照 git log/聊天记录取证 → 清单给你逐条确认 → 修正 → normalize --fix 迁移核验 |
时间取证的完整口径（四级时间源）见完整攻略 · 会话沉淀、恢复与历史修正。
四、规范载体迁移
目标：把项目里旧的单文件 .tasks/conventions.md 升到 conventions/ 目录形态（index.md 唯一入口 + common.md / 各端分册按需创建），让规范能按端分类、按需加载；已有目录形态但结构为 v1 的载体升到 v2。
| 场景 | 你该说 | 会发生什么 |
|---|---|---|
| 形态迁移（单文件 → 目录） | 「把项目里的 conventions.md 迁到新形态」 | AI 走三段式：建 conventions/ 并把旧文件整体搬为 index.md（原文不丢）→ 逐条给出「common / 某端」归属建议 → 你逐条确认后拆成索引行 + 分册 |
| 结构升级（v1 → v2） | 「把规范载体升到 v2」 | 载体从 v1（无形态标记、索引表首列为序号 #、演进记录与索引同文件）升到 v2（首行形态标记、索引表首列为稳定 ID C-<n>、演进记录抽独立 history.md）：优先 pnpm exec toolkit conventions upgrade（--dry-run 预演、幂等、先判后写，异常形态拒绝写盘），亦可按链路手工执行 |
| 只修订内容（不换形态） | 「第 3 条规范改成 …」 | AI 在 history.md 追加留痕（只追加、不改旧行）→ 更新 index.md 该行「当前语义」；作废的把「状态」改 已废弃（不删行），条文在分册内的同步改分册 |
- 入口：
pnpm exec toolkit tasks check报旧单文件conventions.md存在、conventions/缺index.md或载体形态异常时按提示处理；pnpm exec toolkit conventions status可查载体形态、索引与入口层现场；新项目toolkit init已预生成index.md与history.md骨架 - 可中断：三段式与 v1 → v2 升级任一步停下都不丢内容——旧文件整体搬为
index.md后，该文件即原文快照，功能上与旧文件等价；未确认归属的条目保持原样留在index.md - 端名：与任务 frontmatter 的
scope取值逐字一致（任务写scope: web+server→ 读web.md+server.md）；端清单在index.md顶部声明，是端的唯一权威，不扫目录 - 迁移期间兼容读：先找
conventions/index.md，不存在再看旧单文件；两者并存时以目录形态为准
原理与细则见完整攻略 · 存量规范载体迁移。
五、数据进出（报表 / 迁移）
目标：任务数据与 Excel/CSV/JSON 互转，方便汇报或从旧系统迁入。
# 导出：按扩展名自动识别格式（.csv 带 BOM，Excel 直开；.xlsx 三 sheet；.json 结构化）
pnpm exec toolkit tasks --view archived --export 归档报表.xlsx
# 导入：先预演核对，再正式导入
pnpm exec toolkit tasks --import 需求清单.csv --dry-run
pnpm exec toolkit tasks --import 需求清单.csv --target active- 表头写常见叫法即可（「任务名/负责人/状态/截止日期」），中英文别名自动识别
- 落盘自动脱敏：手机号、邮箱、密钥等掩码后再写归档
- 列名映射定制、脱敏规则见配置参考
六、发版
目标：变更集 → CHANGELOG → 发布，多语言分组标题不手翻。
pnpm exec toolkit changelog # 创建变更集（等价 changeset，选 patch/minor/major）
pnpm exec toolkit changelog version # 消费变更集：升版本号 + 生成中文 CHANGELOG + 补发布日期
# 人工检查润色条目后：
pnpm exec toolkit changelog --lang en format # 其他语言格式化
# 提交 → 打 vX.Y.Z 标签 → 发布（按项目渠道，如 npm publish）⚠️ 发版不是必经步骤：由你的规则约定是否执行；未归档的 active 任务存在时会提醒先归档。无 changesets 的项目走手工模式。完整链路见完整攻略 · 多语言 CHANGELOG。
七、升级与卸载
目标：CLI + skills + 全局规则对齐到最新；卸载时不留残渣。
升级
# 全局安装（推荐）
pnpm add -g @fxri/toolkit
toolkit skills status # 可选：检查现场（悬空 / 指向其他版本 / 副本漂移 / 缺失 / 同名冲突）与包内技能真源版本
# 人读版健康目标折叠为一行、仅问题项展开；前四类重跑 toolkit skills install 补齐，同名冲突需 toolkit skills install --force 覆盖
# --scope project 查项目面现场（真源 / 入口薄壳 / 缺失 / 漂移）
# 项目内（版本随仓库锁定）
pnpm up @fxri/toolkit升级三步检查：
- CLI 更新（上面命令）
- skills 同步：默认软链锚在 pnpm 稳定入口（升级时由 pnpm 重写该入口，链接不随版本段失效），CLI 升级后技能即新版，无需额外命令；若是副本形式（
--copy安装，或链接创建失败自动降级），需重跑toolkit skills install刷新；项目面（--scope project）技能由prepare钩子在pnpm install（含升级）时自动刷新，无需手动重跑 - 开新会话：旧会话加载的技能内容还是旧版，新会话才读到新版
⚠️ 软链落点是写入穿透形态：在落点目录里编辑技能文件等于编辑真源（真源还随包升级整体换新），要改技能内容请改真源——toolkit skills status 在存在软链落点时于报告末尾也会提示。
装 skills 后无需手动同步全局规则全文——规则细节已收敛进 skills。CLI 检测到新版本时会提示；关闭提示：FX_NO_UPDATE_CHECK=1 或配置 updateCheck.enabled: false。
卸载
toolkit skills remove # 1. 先摘技能产物（只清本包装的，不碰你自己装的技能）
pnpm remove -g @fxri/toolkit # 2. 再卸 CLI⚠️ 顺序别反：skills remove 依赖本工具（CLI + 包内真源）才能定位产物；先卸了 CLI，清技能就没工具可用——重装一次再执行 toolkit skills remove 即可。
⚠️ 软链会悬空：软链形式的技能指向包内目录，CLI 一卸就成悬空链接（agent 读到空目录）。toolkit skills remove 会把悬空链接一并摘除；若已漏摘，手工删除 ~/.agents/skills/ 与各 agent 全局技能目录下的 fxri-* 链接。
八、隐私与安全
- 默认脱敏开启：终端展示、导出文件、归档落盘都会掩码敏感信息；
.tasks/active/源文件保持原样（设计如此） - 不想某类信息被掩码、或要加自定义规则：
.toolkitrc.json的redact段（见配置参考）