seiso Skill 技能

<h2>技能简介</h2><p>seiso 是一套面向「由 AI 书写、由人与 Agent 共同阅读」的项目文档的 Markdown 约定与 Linter。随着 AI 生成项目文档的速度超过任何人的人工审查速度，代码 Agent 又会把这些文档当作下一次修改的上下文读取，于是过期的版本号、只在三份副本中的一份里更新的字段列表，会同时误导人和机器。seiso 像 rustfmt 统一 Rust 代码格式那样，为仓库中的 Markdown 组织方式定义统一约定，让每个项目把文档映射到「类型」上，而不是各自谈判一套规则。</p><h2>核心能力</h2><ul><li>为每份文档声明唯一类型（如 howto、reference、adr），并只承载该类型应有的内容：操作指南只给步骤，「为什么这样设计」属于 ADR。</li><li>强制「一个事实只有一个家」：其他页面以链接引用，而不是重复叙述，从根源上消除多处不同步。</li><li>约束长生命周期页面不记录比页面本身变化更快的值，例如版本号、部署状态、计数。</li><li>要求指针必须指向具体文件或符号，读者无需再自行搜索。</li><li>成品页面不得向请求者讲话，也不叙述它自己是如何被写出来的。</li><li>工具无法做出的判断必须连同理由写下，没有理由的例外本身即是违规。</li><li>每条诊断都给出问题位置与修复方式，Agent 据此即可自行修复大多数问题；需要人类判断时（如两份页面谁拥有某事实），诊断会点名这一决策。</li><li>稳定规则默认运行，实验规则需加 <code>--preview</code> 显式开启，避免在 CI 中误报。</li></ul><h2>安装配置</h2><ul><li>推荐使用 <code>cargo install seiso</code> 安装 Rust 版本。</li><li>Python 生态可用 <code>uv tool install seiso</code> 或 <code>pipx install seiso</code>。</li><li>Node 生态可用 <code>npm install -g @scarletkc/seiso</code>。</li><li>PyPI 与 npm 包内含 macOS（Apple 芯片与 Intel）、Linux x64/arm64（glibc）、Windows x64 的预编译二进制；Alpine 等 musl 平台需用 cargo 从源码构建。</li></ul><h2>使用步骤</h2><ol><li>在仓库根目录运行 <code>seiso init</code>，生成 <code>seiso.toml</code>，其中包含建议的排除项、类型映射与文档站点条目。</li><li>审阅 <code>seiso.toml</code>，按项目实际情况调整后再依赖结果。</li><li>运行 <code>seiso check</code> 执行全部稳定规则（已通过晋级标准的规则）。</li><li>如需试用实验规则，运行 <code>seiso check --preview</code>，并先本地验证再决定是否纳入 CI。</li><li>用 <code>seiso rule --all</code> 列出全部规则及状态，<code>seiso rule &lt;CODE&gt;</code> 查看单条规则及示例，<code>seiso parse</code> 检查文档模型。</li></ol><h2>适用场景</h2><ul><li>由 AI 大量生成、需要统一规范的长文档仓库。</li><li>需要给代码 Agent 提供可靠上下文的工程团队。</li><li>在 CI 中对项目文档做一致性门禁的团队。</li><li>希望减少同一事实多处维护、反复不同步的维护者。</li></ul><h2>适用人群</h2><p>适合使用 AI 编程助手产出文档的工程团队、开源项目维护者，以及希望把文档规范固化为工具约束的 DevOps / 平台工程人员。</p><h2>工作原理</h2><p>seiso 先定义「文档类型契约」这一核心约定，再以规则检查器逐条核验文档是否符合契约。稳定规则经过评估后默认启用，实验规则以预览方式提供；所有诊断都携带位置与修复建议，使 Agent 能够据输出自行修复。它明确不猜测文字是否像机器写的，也把格式化与拼写交给其他工具。</p><h2>官方链接</h2><p>GitHub：<a href="https://github.com/scarletkc/seiso">https://github.com/scarletkc/seiso</a></p>