跳转至

快速上手

本页依次介绍如何安装 CLI、搭建项目脚手架、编写第一个节点，以及在已有代码库上引入本工具。

安装

SpexCode 运行在 Node 22 上。安装 CLI，它提供 spex 命令：

npm install -g spexcode

spex init

在一个已有的 git 仓库内运行 init。它需要一个 git 工作树，且不会替你创建 —— 如果当前目录不是仓库，它会停下来，并在写入任何内容之前提示你先执行 git init。

spex init

init 是追加式的，绝不会覆盖已有文件。它会搭建三样东西：

  • 一个带根节点的初始 .spec/ 树；
  • git 钩子（一个 pre-commit 检查和一个提交信息戳），复制到仓库的钩子目录中；
  • 仓库根目录下的一个 spexcode.json。其 lint.governedRoots 默认指向 src —— 请把它设为你项目的源码目录，否则 spex lint 会报告它没有治理任何内容。

你的第一个 spec 节点

一个节点就是 .spec/ 下包含 spec.md 的目录。目录名即节点 id；把一个目录嵌套在另一个目录里，它就成了子节点。

为一段你想治理的代码创建一个节点：

mkdir -p .spec/project/auth

然后编写 .spec/project/auth/spec.md：

---
title: auth
desc: How a session token is issued and checked.
code:
  - src/auth/session.ts
  - src/auth/verify.ts
---
# auth

Tokens are issued on login and expire after 24 hours. Verification
rejects an expired or malformed token before any handler runs.
Refresh is explicit; there is no silent renewal.

正文陈述的是当前意图，而不是变更日志 —— 意图变化时你就地重写它，版本历史由 git 提供。code: 列表就是 linter 检查的那条边。

运行 linter

spex lint

有两项检查属于错误并会阻断：code: 列表里的每个路径都必须存在，且正文不得携带 ## vN 变更日志标题。其余都是建议性的警告 —— 覆盖度（一个被跟踪的源码文件没有任何节点认领）、drift(漂移)（一个受治理的文件在其 spec 上一个版本之后发生了改动），以及若干体量和归属信号。覆盖度和 drift 保持为警告，这样一个只部分引入本工具的仓库在错误层面仍能通过。

每一个与项目相关的取值 —— 受治理的根目录、文件扩展名、预算、上限 —— 都从 spexcode.json 的 lint 键下读取，因此你是按自己的布局来调优它，而不是去 fork 这个工具。

在已有代码库上引入

你不需要重构任何东西。为想要治理的部分添加节点，每个节点带一个指向已有文件的 code: 列表，并把 覆盖度 警告当作你的待办清单：每一条都指出一个尚无节点认领的、被跟踪的源码文件。逐条处理下去，直到整个图完整为止。

由于 git 钩子是每个 clone 各自安装、且可被绕过的，请把它们当作快速的本地反馈，而让 CI 成为真正的关卡：在每次 push 和 pull request 上运行 spex lint，并把完整的 git 历史提供给 CI，因为版本时间线和 drift 都是从中派生出来的。

如果你的布局与默认不同 —— main 在仓库根目录、worktree 位于 .worktrees/ 下、node/<id> 分支 —— 请在 spexcode.json 里描述你的结构，而不是去改动仓库本身。显式设置的 mainBranch 会被采用；否则会从主检出中探测源头分支，探测不到则回退到 main。