seiso

About

现在项目里的 Markdown 文档越来越多是 AI 写的，写的速度远远快过人审的速度。更麻烦的是，Claude Code、Codex 这类 coding agent 在下一次改代码时，又会把这些文档当成上下文读回去。文档里一个过时的版本号，或者一份字段列表在三处副本里只改了一处，人会被误导，agent 也会照着错的继续改。而且 AI 写文档，翻来覆去犯的就是那几种错。 seiso 是一套项目文档的 Markdown 约定，加上按这套约定做检查的 linter，用 Rust 写的。思路类似 rustfmt 统一了 Rust 的代码格式，各个项目共用同一套规则，不用每家自己重新商量。项目要做的主要是把自己的文档对应到类型上，seiso init 会给出一份初始配置。 约定的核心是这几条。 每篇文档声明一种类型，比如 howto、reference、adr，只写这种类型该写的内容。操作指南只给步骤，为什么这样设计放进 ADR。 每个事实只有一个归属页面，其他页面链接过去，不再复述一遍。 长期存在的页面不记录比页面本身变得更快的值，比如版本号、部署状态和数量。 成稿不对提需求的人说话，也不交代自己是怎么写出来的。 工具判断不了的例外要写明理由，没写理由的例外本身就算违规。 下面是对一篇中文部署文档的实际检查结果： text $ seiso check --preview docs/deploy.md:7:7: VOX001 This phrase refers to the requester of an earlier conversation. | 7 | 好的，下面是按你的要求更新后的部署指南。 | = suggestion: State the document's instructions or facts directly for its readers. docs/deploy.md:9:12: STL001 This sentence pairs a current-state marker with a value that can change. | 9 | 当前生产环境运行的是 2.3.1 版本。 | = suggestion: Link to the source that owns the value, or state a lasting requirement with its constraint. docs/deploy.md:14:5: LNK001 Local link target "config.md" does not exist in the workspace. | 14 | 配置项见配置说明。 | = suggestion: Update the path or restore the target; paths resolve from this document's directory, or from the workspace root when they start with /, and seiso does not add .md or index.md. Found 3 diagnostics. 每条诊断都会给出位置和修改建议，agent 只看 seiso 的输出就能修掉大部分问题。遇到需要人来判断的情况，比如两个页面到底哪个拥有某个事实，诊断会直接点出要做的决定。seiso 不去猜一段话像不像机器写的，格式和拼写也留给其他工具。 我对误报比较保守。新规则一律先进 preview，要在固定版本的真实仓库语料上攒够至少 100 条逐条人工复核的留出集诊断，精度达到 95% 以上，才会升级成默认启用的稳定规则。所以现在默认只跑文档类型声明、本地链接目标和抑制注释这几条稳定规则，上面例子里的对话残留和当前状态值检查还在 preview，要加 --preview 才会开启。宁可漏报，也不给没有依据的诊断。 它可以接进 Claude Code 的 PostToolUse hook。agent 每次用 Write 或 Edit 改完一个 Markdown 文件，seiso 就检查这个文件，发现问题时用退出码 2 把诊断直接反馈给 Claude，让它当场修掉。另外也支持 pre-commit 和 CI。中文、英文和日文文档都能检查。 sh 三种安装方式任选一种 cargo install seiso uv tool install seiso # 或 pipx install seiso npm install -g @scarletkc/seiso 在仓库根目录 seiso init seiso check PyPI 和 npm 包自带主流平台的预编译二进制，不需要装 Rust 工具链。MIT 协议。

Discovery history

1. 阮一峰周刊·用户投稿

   Sep 28, 2026 · 1 observations