用途
absolute-init 是 absolute 命令集的唯一配置写入命令,用于一次性完成初始化。它先检测项目真实约定,再询问用户希望 absolute 如何行为,最后把结果写入 JSON 配置,供其余十个命令在每次运行时读取。这样其他命令不必每次从零重新检测技术栈,也能自动遵循用户偏好(输出风格、门控、TDD 严格度),无需反复告知。
主要能力
- 自动检测技术栈:依据 references/work.md 中的 Codebase Convention Detection 表检测包管理器、语言/运行时、测试运行器、linter/formatter、构建、CI 和可用脚本,并解析为项目自身的脚本形式(如 npm test、make lint),使缓存命令与 CI 一致。读取实际的 package.json scripts / Makefile targets 填充 test、lint、typecheck、format、build;用 git symbolic-ref --short refs/remotes/origin/HEAD 检测默认分支(回退 main)。无法确定的内容会留空并询问或省略。
- 检测格式化与 UI 约定:conventions.format 来自 package.json 的 format/fmt 脚本、Makefile format 目标、ruff format 或 gofmt。conventions.ui 来自 package.json 依赖,检测 framework(react/vue/svelte/none)、styling(tailwindcss → tailwind;css-modules;styled-components;否则 vanilla)、iconLibrary(lucide-react、@heroicons/、@phosphor-icons/、react-icons 等)、componentLib(shadcn 标记 / @mui/material → mui / @chakra-ui → chakra / none)以及 tokensPath(若存在 tokens/theme CSS 或 TS 文件)。无 UI 依赖则整块省略。
- 检测文档栈:conventions.docs 依据 absolute-docs 的 Stack Detection 标记文件表(source.config.ts/fumadocs、docusaurus.config.*、Starlight、mkdocs.yml、.vitepress/、Mintlify,否则 markdown)确定 stack 与 dir。无文档则省略。
- 解析已有配置:询问前先检查已有配置(按优先级),若找到则打印当前值的紧凑摘要,询问是更新(默认)还是重新开始,并把已有值作为访谈默认值,用户一键即可保留。
- 偏好访谈:使用 AskUserQuestion 逐条提问,一次一题,等待回答后再继续。问题包括:输出风格(normal 推荐 / terse)、自主级别(gate-all 推荐 / auto-low-risk)、TDD 严格度(strict 推荐 / pragmatic)、spec/文档输出目录(自由文本,默认 docs/plans)、使用的命令族(多选:build 推荐,含 work、spec、ui、simplify、docs;health 推荐,含 upgrade、audit、prune、debt、deflake),以及确认检测到的约定(以代码块展示,可回复修正或回车接受)。已有配置已回答的问题会跳过,除非用户要求重新配置。
- 写入配置:在仓库根目录写入 .absolute.config.json(美化打印、2 空格缩进),这是提交的团队共享文件。随后询问是否也持久化到全局文件 ~/.absolute/config.json,其中 defaults.preferences 是跨项目偏好默认值,projects["<absolute repo path>"] 是机器本地的按项目覆盖项。合并进已有全局文件,绝不丢弃无关键。写入后打印文件路径并提醒用户提交 .absolute.config.json(命令自身从不提交)。
配置结构
项目文件 .absolute.config.json 包含 version、conventions(packageManager、languages、test、lint、typecheck、format、build、ci、defaultBranch,以及可选的 ui 与 docs 块)和 preferences(outputStyle、autonomy、tdd、specDir、boardTracking、families、health.protectedPaths、health.deflakeRuns)。conventions.ui 与 conventions.docs 在未检测到时整块省略,保持文件精简。
全局文件 ~/.absolute/config.json 包含 version、defaults.preferences 和 projects 映射。
字段含义:conventions.* 为字符串,是每个命令运行所依据的缓存技术栈/脚本;conventions.format 是格式化脚本,simplify/debt 直接使用而不重新检测;conventions.ui 缓存框架/样式/图标库/组件库/tokensPath,ui 据此采用而不假设 Tailwind 或猜测图标库;conventions.docs 缓存文档栈与目录,docs 跳过标记文件重检测;preferences.outputStyle 控制命令响应详细度;preferences.autonomy 决定 health 命令是否自动应用安全波次;preferences.tdd 控制 work 的测试先行严格度;preferences.specDir 指定 spec/work 写设计文档的位置;preferences.boardTracking 决定 work 的 .absolute-work/board.md 是否提交,一次设定而非每次 intake 询问;preferences.families 裁剪无参数菜单;preferences.health.protectedPaths 是 prune 永不删除的 glob;preferences.health.deflakeRuns 是 deflake 建立 flakiness 的默认重复运行次数。
使用方式
在仓库中首次使用 absolute 时运行;约定变化(新包管理器、新测试/lint 脚本、分支重命名)后重跑以刷新;想全局改变 absolute 行为(输出风格、自主性)时也可运行。命令以 ⚙️ emoji 开始首次响应。
配置优先级(命令读取方式):任何命令开始时按最高优先覆盖解析有效配置:./.absolute.config.json(项目,已提交)→ ~/.absolute/config.json 的 projects["<cwd 绝对路径>"] → ~/.absolute/config.json 的 defaults。conventions 与 preferences 分别浅合并;嵌套的 conventions.ui、conventions.docs 和 preferences.health 块再深一层合并,避免部分覆盖丢失同级键。若都不存在则无配置,命令会软推荐 init 并使用即时检测。
适用场景
首次在仓库使用 absolute,为每个命令提供缓存约定与偏好;约定变化后刷新;跨项目统一调整行为。其他命令没有 init 也能正常运行,会回退到即时检测并输出一行建议运行 init;init 只是让它们更快、更贴合。
限制与注意事项
- 非破坏性:已有配置会展示并逐项确认合并,绝不盲目覆盖;从不提交。
- 提交策略本身不可配置——absolute 从不提交。
- 全局文件 ~/.absolute/config.json 是机器本地,只有 .absolute.config.json 会被提交。
- 缓存错误的命令会污染后续所有命令——需验证每个检测到的脚本确实可运行。
- 过时的约定(分支重命名或包管理器更换)会静默误导命令,技术栈变化后应重跑 init。
- init 不是门控,命令无需它也能继续;它是优化而非前置条件。
配套命令
/absolute work 是缓存约定与 tdd/autonomy/boardTracking 偏好的主要消费者;/absolute spec 读取约定与 specDir;/absolute ui 读取 conventions.ui;/absolute simplify 读取缓存的 test/lint/format/typecheck 用于自动验证;/absolute docs 读取 conventions.docs;/absolute-upgrade|audit|prune|debt|deflake 健康族读取约定用于 DETECT、autonomy 用于门控,以及 preferences.health.*(prune 的 protectedPaths、deflake 的 deflakeRuns)。约定或偏好变化时可随时重跑 /absolute init。