# clarify-kit 中文文档

规范地址：https://npmcn.com/package/clarify-kit/

版本：0\.2\.0
npm 元数据更新时间：2026-11-03T07:49:59.928Z
中文译文更新时间：2026-11-03T07:59:12.819Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/clarify-kit
原文对照：https://npmcn.com/package/clarify-kit/?lang=original
项目主页：https://github.com/carlos-space/clarify-kit#readme
源码仓库：https://github.com/carlos-space/clarify-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：111 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：fact-kit ^0\.12\.1，oxc-parser ^0\.155\.0
- 首次发布：2026-10-30T18:34:02.241Z
- 最新版本发布：2026-11-03T07:49:59.584Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

将讨论转化为解决问题的文件：建立文件，并对照所引用的事实进行检查。

## 安装

```sh
npm install clarify-kit
```

也可以使用：`pnpm add clarify-kit`、`yarn add clarify-kit`、`bun add clarify-kit`

## README

# clarify-kit

把討論整理成能定案的文件。文件用 TypeScript 寫成 `*.doc.ts`，`clarify-kit build` 把它們編譯成帶 `formatVersion` 的 `index.json`，`clarify-kit check` 檢查文件是否合格。

## 文件源碼

`index.ts` 所在的目錄是一個 entry。它預設匯出 entry 層欄位 `describes`（涵蓋哪個產品的哪個版本）與 `publish`（發布到哪裡）。同目錄與子目錄的 `*.doc.ts` 依相對路徑排序收進這個 entry，每個檔預設匯出一份文件。子目錄有另一個 `index.ts` 時，底下的檔案歸那個 entry。

```ts
// docs/main/index.ts
import { defineDocs } from 'clarify-kit'

export default defineDocs({
  describes: { 'my-product': '1.2.0' },
  publish: { target: 'npm', name: 'my-product-docs' },
})
```

```ts
// docs/main/use-x.doc.ts
import { decision, section, text } from 'clarify-kit'

export default decision({
  id: 'use-x',
  title: '採用 X',
  status: 'proposed',
  appliesFrom: 'next',
  sections: [section('context', '背景', [text('為什麼要採用 X。')])],
})
```

`.doc.ts` 用 Node 內建的型別剝除執行，所以只能用可剝除的 TypeScript 語法，相對匯入要寫 `.ts` 副檔名。專案目錄的 `package.json` 要設 `"type": "module"`，否則 Node 會對每個檔案印出模組類型警告。

## 設定檔

`clarify-kit.config.json` 放在專案目錄。沒有設定檔時，工作目錄就是專案目錄，所有設定用預設值。

| 設定 | 意思 | 預設 |
| :-- | :-- | :-- |
| `docsDir` | 文件源碼目錄，相對於設定檔 | `docs` |
| `modules` | 要先載入的模組套件名稱，模組在載入時登記範本與渲染函式 | `[]` |
| `repoRoot` | 倉庫根目錄，相對於設定檔 | 含 `.git` 的最近上層 |
| `factSources` | 文件會引用 fact 的 facts 套件，寫成 `<套件>/<entry>`，例如 `my-product-facts/my-product` | `[]` |

## 指令

| 指令 | 做什麼 | 結束碼 |
| :-- | :-- | :-- |
| `clarify-kit build [--config <file>]` | 把每個 entry 編譯成專案目錄下的 `dist/<entry>/index.json`。有檔案載入失敗時不寫任何檔案 | 0 成功，1 載入失敗，2 讀不到輸入 |
| `clarify-kit check [--config <file>] [--json]` | 檢查文件並回報問題，每筆問題有穩定的 `code`、`message` 與 `location` | 0 沒有問題，1 有問題，2 讀不到輸入 |
| `clarify-kit pin --version <v> [--config <file>]` | 把 `docsDir` 底下 `*.doc.ts` 裡文件、段落與區塊的 `since: 'next'` 換成 `<v>`。帶 `pending` 的不動，功能落地時先拿掉 `pending`，下一次 pin 才釘版號 | 0 成功，2 沒給 `--version`、版號不是 semver 或讀不到輸入 |
| `clarify-kit render [--out <dir>] [--version <v>] [--include <label>...] [--config <file>]` | 把文件渲染成 Markdown，每份文件一個檔 `<out>/<entry>/<文件 id>.md`。預設寫到 `os.tmpdir()` 底下的新目錄，`--out` 在 git 工作樹或 `.git/` 內時拒絕（先解析符號連結再比對 git 根目錄），找不到 git 時也拒絕 `--out`。fact 渲染區塊呼叫模組用 `registerRenderer` 登記的函式，收到 `{ version, include, document, section }` | 0 成功，1 `--out` 在 git 工作樹或 `.git/` 內、或無法確認位置，2 讀不到輸入、`--out` 的符號連結無法解析、找不到渲染函式或 fact |

## 讀取與影響分析

-   `readDocs('<套件>/<entry>', { version, include, root })` 讀已安裝的 `-docs` 套件。沒給 `version` 或給 `head` 時讀 head，`next` 看得到。給版號時只看 `since` 不晚於它的內容。帶 `pending` 的內容只在讀 head 且 `include` 含該標籤時看得到。`formatVersion` 的 major 不是 1，或 `docs` 結構不對時丟 `DocReadError`。
-   `registerDocImpactExtractor()` 向 fact-kit 的 `impactOf` 註冊抽取器，讓影響分析找得到引用某個 fact 的 `*.doc.ts`。認得 `factBlock()` 與 `scenario()` 的 `facts` 裡的 id 字串、從 facts 來源匯入的 fact 物件，以及 `text()` 裡的 `fact:<id>`。算出來的 id 認不得。匯入套件時不會自動註冊。

### check 的錯誤碼

| 錯誤碼 | 意思 |
| :-- | :-- |
| `missing-required-section` | 文件缺範本的必要段落 |
| `unknown-fact-reference` | 區塊引用的 fact 在 `factSources` 的 facts 套件裡找不到 |
| `supersedes-unknown` | `supersedes` 指向的 decision 不在同一個 entry |
| `scenario-without-fact` | requirement 的驗收情境沒有引用 fact |
| `outside-entry` | `*.doc.ts` 不在任何 entry 底下 |
| `load-error` | 檔案載入失敗，或預設匯出不是文件 |
| `duplicate-document-id` | 同一個 entry 內有兩份文件的 `id` 相同 |

check 用 fact-kit 的 `loadInstalledIndex` 與 `selectFacts` 讀 `factSources` 的 facts 套件，所以 fact-kit 1.x 與 2.0 格式的 index 都讀得懂。pending 的 fact 也算存在。

### 採納後內文不改

decision 採納後內文不改，record 寫完不改。clarify-kit 不比對內文，也沒有採納指令，所以這兩條規則由 PR 審查把關：審查者看到已採納 decision 或寫完的 record 的內文被改動時，要求作者改開新的 decision（用 `supersedes` 取代舊的）或新的 record。狀態、版本欄位、`since`、`pending` 與 `supersedes` 不算內文，發版釘版號、功能落地時拿掉 `pending` 標籤、把 decision 改成已取代都可以直接改。

## 文件套件慣例

build 出的 `index.json` 要裝進一個發版單元，名稱是 `<product>-docs`。它的 `package.json` 照下面設，文件就會預設發布。

```json
{
  "name": "<product>-docs",
  "exports": {
    "./<entry>/index.json": "./dist/<entry>/index.json"
  },
  "files": ["dist"]
}
```

-   `name` 用 `<product>-docs`，`<product>` 是文件涵蓋的產品。
-   不設 `"private"`，不設就預設發布。設成 `true` 會讓這個套件不發布。
-   `exports` 一個 entry 對應一行，讀取端靠 `<套件>/<entry>/index.json` 找到它。
-   `files` 只列 `dist`。
-   `describes` 記文件涵蓋的產品版號，這個套件本身是一個發版單元，版號跟著自己的發版流程走。

## 常见问题

### clarify-kit 是什么？

将讨论转化为解决问题的文件：建立文件，并对照所引用的事实进行检查。

### 如何安装 clarify-kit？

在项目目录运行 npm install clarify-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：fact-kit（^0\.12\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 clarify-kit，可以用 npx clarify-kit 直接运行。

### clarify-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### clarify-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### clarify-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### clarify-kit 可以商用吗？

clarify-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### clarify-kit 还在维护吗？

最新版本 0\.2\.0 发布于 2026/11/03（今天）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。