absolute-init

“设置 / 初始化 / 配置 absolute”。 首次回复请以 ⚙️ 表情符号开头。

Absolute 初始化

一次性设置。检测项目的实际约定，询问几个关于你希望 absolute 如何运行的问题，然后将答案写入 JSON 配置文件，其他十个命令每次运行时都会读取该文件。结果：命令不再从头检测你的技术栈，并会遵循你的偏好（输出风格、门控、TDD 严格程度），无需每次都告知。

这是唯一会写入配置的命令。它不会造成破坏：如果配置已存在，会先显示并更新，绝不会盲目覆盖。它从不提交更改。

---

适用场景

• 首次在仓库中使用 absolute——为每个命令提供缓存的约定和你的偏好。
• 约定发生变化（更换包管理器、新增测试／lint 脚本、重命名分支）——重新运行以刷新。
• 想在多个项目中全局更改 absolute 的行为（输出风格、自主程度）。

其他命令即使不运行 init 也能正常工作——它们会改为即时检测，并输出一行提示建议运行 init。init 只是让它们更快、更贴合项目。

---

核心原则

1. 先检查代码库，再提问。 先检测所有可检测的信息。只询问仓库无法告知的内容（偏好、模糊选项）。
2. 少量提问，不要盘问。 最多约 4-6 个问题，一次问一个。这是设置流程，不是设计评审。
3. 不造成破坏。 配置已存在 → 显示、确认每项更改并合并，不要覆盖。
4. 绝不自动提交。 写入项目文件，然后告知用户提交。（提交策略本身不可配置——absolute 从不提交。）
5. 分为两个层级，以项目配置为准。 项目配置由团队共享且具有权威性；全局配置是你的个人默认值和逐项目覆盖项。

---

步骤 1 — 检测

使用 references/work.md 中的 代码库约定检测 表自动检测技术栈（包管理器、语言／运行时、测试运行器、lint／格式化工具、构建、CI、可用脚本）。将每项解析为项目的自有脚本形式（npm test、make lint），使缓存的命令与 CI 一致，而不是使用原始工具。

读取实际的 package.json scripts／Makefile 目标，以填充 test、lint、typecheck、format、build。使用 git symbolic-ref --short refs/remotes/origin/HEAD 检测默认分支（回退到 main）。任何无法确信的内容 → 留空并询问，或省略。

此外，根据依赖项和标记文件检测以下内容（如果未检测到任何内容，则省略整个区块）：

• 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 + dir（source.config.ts／fumadocs、docusaurus.config.*、Starlight、mkdocs.yml、.vitepress/、Mintlify，否则为 markdown）。如果没有文档，则省略。

步骤 2 — 解析现有配置

在提问之前，先检查是否存在配置（见下方优先级）。如果存在，打印当前值的简要摘要，并询问是要更新（默认）还是重新开始。将现有值视为访谈的默认值，让用户只需按一次键即可保留。

步骤 3 — 访谈

每个偏好问题都使用 AskUserQuestion。将选项作为带描述的结构化选项呈现；在推荐/默认选项的标签前标注 "(Recommended)"。一次只问一个问题——等待用户回答后再继续。

问题（如果现有配置已给出答案，则跳过；除非用户要求重新配置）：

Q1 — 输出风格

question: "Output style?"
header: "Output style"
options:
  - label: "normal (Recommended)"
    description: "Full prose, explanations — good for onboarding or unfamiliar codebases"
  - label: "terse"
    description: "Compressed, minimal prose — matches caveman mode"

Q2 — 自主性

question: "Autonomy level?"
header: "Autonomy"
options:
  - label: "gate-all (Recommended)"
    description: "Confirm before every change/wave — full control"
  - label: "auto-low-risk"
    description: "Auto-apply obviously-safe health waves, gate risky ones"

Q3 — TDD 严格程度

question: "TDD strictness?"
header: "TDD"
options:
  - label: "strict (Recommended)"
    description: "Test-first, red→green — failing test must exist before any code"
  - label: "pragmatic"
    description: "Tests required but not strictly written first"

Q4 — 规格 / 文档输出目录 以自由文本提问："Where should spec/work write design docs? (default: docs/plans)"。接受空白输入以保留默认值。

Q5 — 相关类别

question: "Which command families do you use?"
header: "Families"
multiSelect: true
options:
  - label: "build (Recommended)"
    description: "work, spec, ui, simplify, docs"
  - label: "health (Recommended)"
    description: "upgrade, audit, prune, debt, deflake"

Q6 — 确认检测到的约定 以代码块显示检测到的 conventions 块，并询问："Are these correct? Reply with any corrections or press enter to accept."。接受空白输入以继续。

步骤 4 — 写入

在仓库根目录写入 .absolute.config.json（美化格式，2 个空格缩进）。这是已提交、团队共享的文件。然后询问是否也要将配置持久化到全局文件 ~/.absolute/config.json：

• defaults.preferences — 跨项目的偏好默认值。
• projects["<absolute repo path>"] — 项目级覆盖项（仅本机使用，不提交）。

合并到任何现有全局文件中；绝不删除无关键。写入后，打印文件路径，并提醒用户提交 .absolute.config.json（你不会提交）。

---

配置架构

两个文件共用 conventions + preferences；全局文件会将它们包装起来。

.absolute.config.json（项目级，已提交）：

{
  "version": 1,
  "conventions": {
    "packageManager": "npm",
    "languages": ["typescript"],
    "test": "npm test",
    "lint": "npm run lint",
    "typecheck": "npm run typecheck",
    "format": "npm run format",
    "build": "npm run build",
    "ci": ".github/workflows/ci.yml",
    "defaultBranch": "main",
    "ui": {
      "framework": "react",
      "styling": "tailwind",
      "iconLibrary": "lucide-react",
      "componentLib": "shadcn",
      "tokensPath": "src/styles/tokens.css"
    },
    "docs": {
      "stack": "fumadocs",
      "dir": "docs"
    }
  },
  "preferences": {
    "outputStyle": "normal",
    "autonomy": "gate-all",
    "tdd": "strict",
    "specDir": "docs/plans",
    "boardTracking": "gitignored",
    "families": ["build", "health"],
    "health": {
      "protectedPaths": ["dist/**", "vendor/**", "**/*.generated.*"],
      "deflakeRuns": 20
    }
  }
}

如果未检测到任何内容（没有 UI 依赖、没有文档技术栈），则完全省略 conventions.ui 和 conventions.docs 块，以保持文件精简。

~/.absolute/config.json（用户级 / 全局）：

{
  "version": 1,
  "defaults": {
    "preferences": {
      "outputStyle": "normal",
      "autonomy": "gate-all",
      "tdd": "strict",
      "specDir": "docs/plans",
      "families": ["build", "health"]
    }
  },
  "projects": {
    "/Users/you/dev/your-repo": {
      "conventions": { "packageManager": "pnpm", "test": "pnpm test" },
      "preferences": { "outputStyle": "terse" }
    }
  }
}

字段含义：

字段	值	效果
conventions.*	字符串	缓存技术栈 / 脚本，每个命令都会使用它们，而不是重新检测。
conventions.format	字符串	格式化脚本——simplify/debt 会运行该脚本，而不是重新检测。
conventions.ui	对象	缓存 framework/styling/iconLibrary/componentLib/tokensPath——ui 会采用这些值，而不是默认使用 Tailwind / 猜测图标库。
conventions.docs	对象	缓存文档 stack + dir——docs 会跳过标记文件的重新检测。
preferences.outputStyle	normal | terse	命令响应的详细程度。
preferences.autonomy	gate-all | auto-low-risk	健康检查命令是否自动应用安全波次。
preferences.tdd	strict | pragmatic	work 的测试优先严格程度。
preferences.specDir	路径	spec/work 编写设计文档的位置。
preferences.boardTracking	gitignored | git-tracked	work 的 .absolute-work/board.md 是否提交——设置一次后，每次任务接收时都不再询问。
preferences.families	["build","health"] 子集	将无参数菜单精简为你使用的类别。
preferences.health.protectedPaths	glob[]	prune 会遵守的永不删除 glob（生成代码 / 引入的代码）。
preferences.health.deflakeRuns	int	deflake 用于确认测试不稳定性的默认重复运行次数 N。

---

优先级（命令如何读取配置）

每条命令开始时，按以下优先级叠加配置并解析有效配置，优先级最高者胜出：

1. ./.absolute.config.json（项目级，已提交）
2. ~/.absolute/config.json → projects["<cwd absolute path>"]
3. ~/.absolute/config.json → defaults

分别对 conventions 和 preferences 做浅合并；对嵌套的 conventions.ui、 conventions.docs 和 preferences.health 块再向下合并一层，避免部分覆盖导致同级键被丢弃。如果均不存在，则表示没有配置——命令会温和地建议使用 init，并采用即时检测。

---

注意事项

1. 覆盖手动调整过的配置。 始终先执行 RESOLVE；应合并，而非覆盖。
2. 缓存错误的命令。 与 CI 不匹配的缓存 test/lint 命令会影响之后的每条命令——请验证每个检测到的脚本是否确实能运行。
3. 提交全局文件。 ~/.absolute/config.json 是本机文件；只有 .absolute.config.json 会被提交。
4. 约定过时。 重命名分支或更换包管理器会导致命令被错误路由，且不会发出提示——技术栈变更后请重新运行 init。
5. 把 init 当作门槛。 事实并非如此。即使未运行 init，命令也会继续执行；init 是优化手段，而非前置条件。

---

配套命令

• /absolute work — 主要使用缓存约定以及 tdd/autonomy/boardTracking 偏好设置。
• /absolute spec — 读取 conventions + specDir，而不是重新检测。
• /absolute ui — 读取 conventions.ui（框架、样式、图标库、tokens 路径）。
• /absolute simplify — 读取缓存的 test/lint/format/typecheck，用于自动验证。
• /absolute docs — 读取 conventions.docs（技术栈、目录），跳过标记重新检测。
• /absolute-upgrade|audit|prune|debt|deflake — 健康检查命令组读取 conventions 进行 DETECT，读取 autonomy 用于门控，并读取 preferences.health.*（prune 的 protectedPaths、deflake 的 deflakeRuns）。
• 每当约定或偏好设置发生变化时，请重新运行 /absolute init。