seiso：面向 AI 与人类共同阅读的 Markdown 文档规范与 linter

scarletkc/seiso

seiso，一个面向项目文档的 Markdown 规范与检查工具（linter），文档由 AI 撰写，供人类与智能体（agent）共同阅读。

AI 撰写项目文档的速度，远快于任何人的审阅速度。编码智能体（coding agent）又会把这些文档读回来，作为下一次修改的上下文。无论是人还是智能体，都会把页面内容当作事实照单全收。所以一个过时的版本号，或者一份只在三处副本之一被更新的字段列表，就会同时误导他们所有人。AI 也反复犯同样那几个错误。

seiso 为仓库中的 Markdown 定义一套统一的规范，就像 rustfmt 为 Rust 代码统一了格式一样。各项目共用这套规则，不必各自协商；每个项目主要把文档映射到相应的种类（kind），seiso init 会给出一个起点建议。

规范（The convention）。每份文档声明一个种类（kind），例如 howto、reference 或 adr，只承载该种类对应的内容。how-to 给步骤；设计为何如此，应当写在 ADR 里。

每条事实只有一个归属地。其他页面通过链接指向它，而不是把它复述一遍。

长期存在的页面不记录那些比页面本身变化更频繁的值，例如版本号、部署状态、计数等。

指针（pointer）指向一个文件或符号（symbol），让读者不必再去搜索句子所承诺的内容。

成稿页面不会针对当初提出需求的那个人来写，也不会叙述它是如何被写出来的。

工具无法作出的判断，应当写下来并附上理由。没有理由的例外，本身就是一种违反。

seiso 的规则会依据这套规范来检查文档。稳定的规则默认运行，其余规则是可选启用的预览（preview）。每条诊断信息都会指出问题所在以及修复方法，因此智能体单凭 seiso 的输出就能修复大部分发现。当修复需要作出判断（例如两个页面中哪一个应当归属某条事实）时，诊断信息会标明这一决定。seiso 不会去猜测一段文字是否像机器写的，格式与拼写也留给其他工具处理。规范定义了每种 kind 的契约，以及一条诊断所依据的证据。

安装

cargo install seiso
uv tool install seiso  # 或者：pipx install seiso
npm install -g @scarletkc/seiso

PyPI 与 npm 包内附带适用于多平台的预编译二进制，包括 Apple silicon 与 Intel 架构的 macOS、采用 glibc 或 musl（例如 Alpine）的 Linux x64 与 arm64，以及 Windows x64 与 arm64。在其他平台上，请使用 cargo；PyPI 包也可以工作，但会从源码编译，因此需要 Rust 工具链（toolchain）。在源码检出目录中，可运行 cargo run -- <command>。

快速上手

在仓库根目录下：

seiso init
seiso check

seiso init 会在仓库根目录写入一个 seiso.toml，包含建议的排除项、kind 映射以及文档站点条目。请先审阅，再依赖其结果。

seiso check 仅运行那些已达到晋升（promotion）标准的稳定规则。

其余规则处于预览（preview）阶段，是实验性的，可能报告误报（false positive），并且只能在加上 --preview 时才会运行。在依赖它们之前请先在本地试用，并把它们挡在 CI 的质量门禁之外。

seiso rule --all 列出所有规则及其状态，seiso rule <CODE> 以示例解释某条规则，seiso parse 在不运行规则的情况下检视文档模型。

文档

- 文档检查：配置、规则选择与输出格式
- 集成：Claude Code hooks、pre-commit 与 CI
- 开发：构建、测试与验证命令
- 架构：命令执行
- 路线图：拟议特性与里程碑证据
- 文档索引：指南、参考与评估记录
- 贡献：issue、分支、提交与拉取请求

许可证

seiso 以 MIT 许可证授权。