项目初始化(init)
在新项目里一次性搭好任务区、规范载体与技能入口。
bash
toolkit init
toolkit init --dir ../my-tasks-repo # 任务区放项目外(独立仓库管理)
toolkit init --no-hooks # 不写入 package.json 的 prepare 刷新钩子在当前目录初始化任务区,逐项如实报告实际动作(新建 / 更新 / 保持 / 追加 / 跳过):
- 创建
<任务目录>/active/{YYYYMM}/与<任务目录>/archive/目录骨架- 默认目录
.tasks;优先级与task同口径:CLI 参数 > 配置task.dir> 默认.tasks
- 默认目录
- 创建规范载体骨架
<任务目录>/conventions/index.md(v3 三节:端清单 / 索引 / 用法说明)与history.md(语义演进记录)index.md已存在时保持不动;v1 / v2 形态另给升级提示- 存在待迁移的旧单文件
<任务目录>/conventions.md时不建空骨架
- 在已存在的项目级技能目录各生成一份规范入口壳(如
.agents/skills/toolkit-conventions/SKILL.md,目录名与 frontmattername同名)- 壳只作入口、不承载条文;多 agent 混用团队多个候选目录并存时每处各写一份、互不覆盖
- 一个候选目录都不存在时回落
.agents/skills/,不为未安装的 agent 凭空建目录 - 壳已存在时按标记版本分流:标记不旧于当前版本保持不变,落后或无标记就地更新为当前版本(报告为「更新」)
- 另在已存在的
AGENTS.md内幂等追加规范入口指针块;AGENTS.md不存在时不新建,仅在报告中提示规范仍可经全局技能触达
- 向
.gitignore追加忽略片段(含.archive.lock、.toolkitrc.local.json与两份配置备份.toolkitrc.json.bak/.toolkitrc.local.json.bak)- 片段头另附一行出口指引注释:不想改团队
.gitignore者,可把忽略行写进.git/info/exclude - 逐行幂等:「是否已覆盖」用
git check-ignore真实判定,已有该行则跳过;手删单行后重跑只补该行 - 判定涵盖本仓库与上层
.gitignore、.git/info/exclude等全部来源,能识破*.lock、*.local.json等手写通配写法 - 非 git 仓库或 git 不可用时退回等价写法白名单:精确行
/.toolkitrc.local.json的带 / 不带前导/两种写法, 及通配*.local.json、.toolkitrc.*;两份.bak只认精确行或.toolkitrc.*通配 - 白名单外一律追加,宁冗余不误跳
- 片段头另附一行出口指引注释:不想改团队
- 向
.prettierignore幂等追加任务区排除行(<任务目录>/),让格式化器不碰任务区- 原因:任务区表格进入 prettier 范围会被填充出列对齐空白,Markdown 预览不显示、源码可读性变差、token 成本上升
- 触发条件缺一不写:任务区落在仓库内且非仓库根、非本包源仓库、宿主疑似使用 prettier
- prettier 迹象的判据(任一):已存在
.prettierignore、存在 prettier 配置文件、package.json声明 prettier 依赖或含prettier键 - 已有等价排除行(如
/.tasks)保持不动(报告为「保持」);未见 prettier 迹象时跳过,并提示「项目启用 prettier 后重跑toolkit init会自动补上该排除行」 - prettier 的
--ignore-path默认同时读.gitignore与.prettierignore,故新建此文件不影响既有忽略语义
- 向
package.json幂等补一行prepare钩子(值为toolkit skill install --scope project --refresh)- 钩子只刷新已存在的项目面产物,不新增技能;非 TTY / CI 只打印漂移
- 仅当本地依赖含
@fxri/toolkit时写入:dependencies/devDependencies/peerDependencies/optionalDependencies任一 - 写入采用最小文本插入,保留原有排版
- 已有等价钩子(裸
toolkit skill install --refresh亦可)保持不变 - 旧版钩子(
--scope project/ 裸install)原地升级为--refresh;非等价prepare跳过并提示不覆盖 - 未声明本地依赖、
package.json缺失或解析失败均跳过并说明;本包源仓库跳过;--no-hooks关闭写入
- ⚠️ 发布型包误打包检查独立于钩子:
package.json未标private且无files白名单时,报告附提示- 与钩子是否写入无关:
--no-hooks、未声明本地依赖、非等价prepare等情形同样提示 - 原因:
npm无.npmignore时退回.gitignore决定打包面,而项目面技能产物与内置任务区都不在忽略列表、会被打进包 - 涉及产物:技能真源
.agents/skills/、各候选目录下的入口薄壳、归属账.toolkit/,以及内置任务区.tasks/(任务区外置时不计入) - 处置:发布型包请把它们加入
files白名单或.npmignore;init只提示、不代改
- 与钩子是否写入无关:
- 输出后续步骤与文档站链接;检测到尚未安装全局技能时,后续步骤中补一行
toolkit skill install指引(规范触达第一层,不依赖项目内文件;已安装则不重复提示)
⚠️ 入口壳写入项目级技能目录(.agents/skills/、.trae/skills/ 等)属侵入性行为。init 在报告中逐项列出实际写入的路径与动作(存在几个候选目录就各写一份)。
落点被 .gitignore 覆盖时报告给出否定规则提示(不代改 .gitignore)。入口壳可安全删除,重跑 init 会补回;标记落后于当前版本时就地更新为当前版本。
⚠️ 重复执行安全:业务文件已存在一律保持不覆盖、不报错(逐项报告为「保持」);唯一例外是入口壳按标记版本分流——标记不旧于当前版本时保持不变,标记落后或无标记时就地更新为当前版本(报告为「更新」)。
⚠️ 任务区放项目外(独立文档仓库):配置 "task": { "dir": "../my-tasks-repo" } 后,init 与全部 task 子命令都作用于该目录,一次配置永久生效。
.gitignore 片段仍写入当前项目。
相关页面
- 参考:快速开始 · 30 秒上手 · 技能分发
