Pituitary

Pituitary

为 AI 原生开发提供一致性治理。

在偏差找上你之前，先把它们揪出来。

它能发现什么 · 快速开始 · Agent · CI · 速查表 · 参考

适用于开发者和团队：人类与 AI 持续产出规格、文档和决策，而这些内容理应保持一致——却在不知不觉中开始互相矛盾。

交互版请在 asciinema 上观看。

单个二进制文件。无需 Docker。无需 API 密钥。只需一个治理 SQLite 文件和一个本地 Stroma 快照。

核心功能以本地运行、命令行优先的方式交付。MCP 服务、CI 接线和由提供商支持的语义运行时，都是围绕同一确定性核心构建的可选封装。

它能发现什么

你早就知道文档会逐渐偏离。你试图用大模型清理流程来解决。大模型说“一切正常”——但它只检查了能放进上下文窗口的内容。其余部分仍在不断腐朽。下一个 PR 又会在那些从未真正修复的问题之上引入新的矛盾。这就像一台跑步机，看似卓有成效，却永远无法收敛。与此同时，代币成本不断累积：错误尝试、方向误导和上下文浪费，都是问题偏差、规格冲突和文档过时直接造成的。

Pituitary 用结构性保障取代这台跑步机：它会为整个语料库建立索引，并在每次运行时检查全部内容。在一个包含 11 份规格和 29 份文档的真实代码库中，它发现了 22 份材料中的 90 处弃用术语违规，以及 7 处语义矛盾。项目方向深受文档偏差、运行时契约矛盾和各处出现的弃用术语困扰——Pituitary 帮助项目摆脱了这些问题。在多个代码库中，它会成为治理汇聚的单一事实来源。

决策重叠。 新规格涵盖了已有规格处理过的内容。

文档过时。 规格发生变化，或代码差异表明文档可能已过时，但引用该规格的 CLAUDE.md、AGENTS.md、运行手册和指南却没有更新。

与规格矛盾的代码。 合并前，将你的差异内容传入：

git diff origin/main...HEAD | pituitary check-compliance --diff-file -

术语偏差。 团队采用了新说法，但旧术语仍留在文档和规格中。

它的演进

Pituitary 最初是一个漂移检测器。随着意图语料库不断增长，它会成为一致性治理层：

时序治理。 针对治理图进行指定时间点的查询。当规范被取代时，历史治理链接会保留，但不会纳入当前查询。对 check-compliance、check-doc-drift 或 analyze-impact 使用 --at DATE。时间戳根据索引构建／更新时间生成。

基于置信度加权的边。 治理链接带有信任等级——提取（在规范中声明）、推断（AST 符号匹配）或模糊。对 check-compliance 和 check-doc-drift 使用 --min-confidence，在精确率和召回率之间权衡。

有意偏离与意外漂移。 当代码与规范矛盾时，Pituitary 会检查是否存在说明原因的注释（// WHY:、// HACK:、决策相关表述）。有意偏离和非预期漂移会采用不同的修复路径。

治理变更日志。 index --update --show-delta 会报告发生的变化：新增／移除的规范、创建／断开的边以及治理态势变化。这是 CI 所需的反馈闭环。

规范族群。 依赖图上的社区检测会发现自然形成的治理簇。族群之间的覆盖缺口是风险最高的未治理区域。

面向 AI 的治理协议。 可选的 MCP 封装会教会你的 AI 助手何时检查治理——修改文件前、提交前、接受规范后、编写文档时——而不只是教它如何检查。

快速开始

pituitary init --path .              # discover, index, report
pituitary new --title "Rate limiting policy" --domain api  # scaffold a draft spec
pituitary check-doc-drift --scope all  # find stale docs
pituitary review-spec --path specs/X   # full review of one spec
pituitary status                       # index health and governance hotspots at a glance

命令参考

所有命令都可通过 --format json 输出 JSON。Agent 可设置 PITUITARY_FORMAT=json，而重定向的标准输出会自动默认为 JSON。review-spec 还支持 --format markdown 和 --format html，用于生成包含完整证据链、便于分享的报告。

当文件选择结果看起来不正确时，请先运行 pituitary explain-file PATH。这是确认哪个源与文件匹配、哪些选择器生效，以及路径为何被拒绝的最快方式，然后再调试漂移或合规性输出。

一个 pituitary.toml 也可以涵盖多个仓库根目录。使用 repo = "..." 将源绑定到具名仓库根目录，Pituitary 会在搜索、漂移、影响、状态和索引输出中保留该仓库身份，让跨仓库结果清晰明确。

pituitary status 现在还会标记治理热点，帮助你快速梳理语料：applies_to 覆盖范围异常广的规范、仅通过推断或不明确链接受到宽松治理的制品，以及当前受多份规范共同治理的制品。

对于术语迁移，你可以继续使用 --term / --canonical-term 执行临时审计，也可以在配置中声明可复用的 [[terminology.policies]] 并直接运行 pituitary check-terminology。结果现在会将当前可处理的违规与可容忍的历史用法分开；支持仅用于术语检查的 exclude_paths，以排除 CHANGELOG.md 等历史容器；并在文本和 JSON 输出中包含替换建议。

analyze-impact、check-doc-drift 和 review-spec 现在会在 JSON 中输出章节级证据链：匹配双方的源引用、classification、link_reason，以及可能的编辑目标或建议要点。这样 Agent 就能解释下一步需要手动进行的编辑，而无需抓取散文内容或自动编辑推测性变更。

对于 Agent 集成，请使用 pituitary schema <command> --format json 检查请求/响应契约；如果 shell 转义容易出错，分析命令应优先使用 --request-file PATH|-。包含原始仓库摘录或证据的结果现在会附带 result.content_trust 元数据，调用方可据此将返回的工作区文本视为不可信输入，而非可执行指令。

所有命令请参阅速查表；配置、运行时和规范详情请参阅完整参考；可复用的多编辑器软件包请参阅 skills/pituitary-cli/README.md；仓库原生的 Agent 指令请参阅 AGENTS.md。

安装

macOS（Homebrew）：

brew install dusk-network/tap/pituitary

Linux / macOS（二进制文件）：从 GitHub Releases 下载，然后：

tar xzf pituitary_*_*.tar.gz
sudo install pituitary /usr/local/bin/

Windows：从 GitHub Releases 下载 pituitary_<version>_windows_amd64.zip，解压 pituitary.exe，并将其所在位置添加到 PATH。

从源代码构建（贡献者）：请参阅 docs/development/prerequisites.md。

防止 Agent 基于过时的决策开展工作

你的 Agent 会编写规范、审查 PR 并提出变更，但它不知道已经做出了哪些决策。Pituitary 会为它提供这些背景信息。治理协议会教它何时检查，而不只是如何检查。

可选 MCP 服务（Claude Code、Cursor、Windsurf 或任何 MCP 客户端）

{
  "mcpServers": {
    "pituitary": {
      "command": "pituitary",
      "args": ["serve", "--config", ".pituitary/pituitary.toml"]
    }
  }
}

你的 Agent 将获得 15 个工具：search_specs、check_overlap、compare_specs、analyze_impact、check_doc_drift、review_spec、get_intent_outline、expand_intent_context、check_compliance、check_terminology、governed_by、compile_preview、fix_preview、status 和 explain_file。如需精简的上下文，请先搜索，再用 get_intent_outline 检查返回的记录，然后使用相同的 snapshot_fingerprint，通过 expand_intent_context 展开选定的 chunk ID。

共享技能（Claude Code、Cowork）

cp -R skills/pituitary-cli ~/.claude/skills/pituitary-cli

Codex CLI 和 Gemini CLI 会自动从 AGENTS.md / GEMINI.md 获取项目策略。如需使用完整的 Pituitary 分析工作流，也请安装技能包：cp -R skills/pituitary-cli ~/.codex/skills/pituitary-cli 或 ~/.gemini/skills/。

编辑器规则（Cursor、Windsurf、Cline）

cp skills/pituitary-cli/platforms/cursor/.cursorrules .cursorrules        # Cursor
cp skills/pituitary-cli/platforms/windsurf/.windsurfrules .windsurfrules  # Windsurf
cp skills/pituitary-cli/platforms/cline/.clinerules .clinerules           # Cline

支持读取 AGENTS.md 的工具（Codex CLI、Gemini CLI 等）

仓库中的 AGENTS.md 是项目策略的权威来源。读取 AGENTS.md 的工具会自动了解 Pituitary。生成的镜像文件（CLAUDE.md、GEMINI.md）仅用于兼容，并非独立的策略来源。

完整的安装指南、请求模板和安全说明，请参阅 skills/pituitary-cli/README.md。

可选 CI 接入

如果你已经在使用 GitHub Actions，可以通过仓库中已提交的 action 封装相同的本地 CLI 工作流，并将 review-spec 输出作为 PR 评论发布：

permissions:
  contents: read
  pull-requests: read
  issues: write

steps:
  - uses: dusk-network/[email protected]
    with:
      fail-on: error
      # Set this when your repo keeps config at the root instead.
      # config-path: pituitary.toml

将规范卫生检查与代码检查工具放在一起运行：

- run: pituitary index --rebuild
- run: git diff origin/main...HEAD | pituitary check-compliance --diff-file -
- run: git diff origin/main...HEAD | pituitary check-doc-drift --diff-file -
- run: pituitary check-doc-drift --scope all

完整的 GitHub Actions 配置示例请参阅 docs/development/ci-recipes.md。

[runtime.embedder]
provider = "openai_compatible"
model = "text-embedding-3-small"
endpoint = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

[runtime.profiles.local-lm-studio]
provider = "openai_compatible"
endpoint = "http://127.0.0.1:1234/v1"
timeout_ms = 30000
max_retries = 1

[runtime.embedder]
profile = "local-lm-studio"
model = "nomic-embed-text-v1.5"

[runtime.analysis]
profile = "local-lm-studio"
model = "your-analysis-model"
timeout_ms = 120000

pituitary status
pituitary status --check-runtime all
pituitary index --rebuild

架构

完整的系统设计请参阅 ARCHITECTURE.md。关键决策：优先采用确定性检索，仅提供工具（不内嵌 Agent），使用一个治理 SQLite 文件和一个不透明的本地 Stroma 快照，并通过原子操作重建。

项目状态

正在积极开发中。核心分析已实现端到端功能：重叠、偏移、影响、合规性、术语、编译、规范新鲜度和评审工作流现已全部提供。治理图包含时效有效性、置信度层级和规范系列分配。Pituitary 用于一致性治理，而非代码检查——它确保项目依据实际决策进行构建，而不是依据常规 LLM 清理工作遗漏的过时决策回声。请参阅 docs/rfcs/0001-spec-centric-compliance-direction.md。

请参阅 ROADMAP.md，了解已交付内容、后续计划以及 Pituitary 的发展方向。

贡献

请参阅 CONTRIBUTING.md。代码库划分了清晰的包边界，因此你无需了解整个系统，也可以为其中一个部分做出贡献。

许可证

MIT