Stack

外观

快速开始 ​

选择一种安装方式，按本页步骤生成第一个SVG。在终端或coding agent中工作时使用CLI；无需安装即可体验的方式是打开Playground，并使用下方的浏览器示例。

安装CLI ​

Stack CLI 0.5.4支持arm64 / x86_64的macOS和glibc Linux。预编译文件需要macOS 13或glibc 2.31及以上；不支持Windows和Alpine/musl。请选择一种安装方式，避免多个二进制文件在PATH中冲突。准确的支持范围以分发契约为准。

Homebrew ​

在Apple Silicon macOS或受支持的Linux上使用已安装的Homebrew。主机还必须满足Homebrew自身的Tier 1要求。

text
brew install stack-sh/tap/stack

Cargo ​

需要Rust 1.85及以上和本地链接器：macOS使用Xcode Command Line Tools，Linux使用C编译器和链接器。将Cargo的bin目录加入PATH。包名为stack-diagram-cli，安装后的命令为stack。

text
cargo install stack-diagram-cli --version 0.5.4 --locked

Aqua ​

在Git仓库的根目录（包含.git的目录）中，将以下内容保存为aqua.yaml。新项目请先运行git init：

yaml
checksum:
  enabled: true
  require_checksum: true
  supported_envs:
    - all
registries:
  - name: stack-sh
    type: github_content
    repo_owner: stack-sh
    repo_name: cli
    ref: 42702cda91a4156901b9a601bd143c43dcf05766
    path: aqua/registry.yaml
packages:
  - name: stack-sh/cli@v0.5.4
    registry: stack-sh

将以下限定范围的策略保存为aqua-policy.yaml，审阅后允许该策略并安装：

yaml
registries:
  - name: stack-sh
    type: github_content
    repo_owner: stack-sh
    repo_name: cli
    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
    path: aqua/registry.yaml
packages:
  - name: stack-sh/cli
    registry: stack-sh
    version: semver(">= 0.3.0")
text
aqua policy allow
aqua update-checksum
aqua install

提交aqua.yaml、aqua-policy.yaml和生成的aqua-checksums.json。确保Aqua的bin目录在PATH中。注册表固定到不可变revision，请勿改成main。

直接下载 ​

在受支持的主机上安装并登录GitHub CLI，然后在POSIX shell中执行。此流程下载到新的临时目录，验证校验和与确切标签的发布者身份后才解压，并拒绝替换已有的~/.local/bin/stack。macOS文件使用ad-hoc签名，未经公证。任何验证失败时都应停止。

text
(
  set -eu
  version=0.5.4
  case "$(uname -s)/$(uname -m)" in
    Darwin/arm64) target=aarch64-apple-darwin ;;
    Darwin/x86_64) target=x86_64-apple-darwin ;;
    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
    *) echo "Unsupported platform" >&2; exit 1 ;;
  esac
  archive="stack-v${version}-${target}.tar.gz"
  download_dir=$(mktemp -d)
  cd "$download_dir"
  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum --check archive-checksum.txt
  else
    shasum -a 256 --check archive-checksum.txt
  fi
  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
  tar -xzf "$archive"
  mkdir -p "$HOME/.local/bin"
  test ! -e "$HOME/.local/bin/stack"
  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
)
export PATH="$HOME/.local/bin:$PATH"

生成第一个SVG ​

在新的空工作目录中执行。使用Aqua时，请将该目录放在包含aqua.yaml的Git仓库内：

sh
$ stack --version
$ stack init
$ stack check diagram.stack
$ stack render diagram.stack -o diagram.svg

预期结果：显示stack 0.5.4、生成diagram.stack、检查无错误，并生成非空的diagram.svg。用浏览器打开SVG或将其加入README。stack init会保护已有文件，请使用新目录而非覆盖原有工作。

修改diagram.stack描述自己的系统，再次运行check和render。需要格式化时执行：

sh
$ stack fmt diagram.stack
$ stack fmt --check diagram.stack

检查安装并配置shell集成 ​

在项目或coding agent工作流中持续使用Stack之前，请先运行两个只读命令检查安装状态：

text
$ stack doctor
$ stack config path

stack doctor会报告CLI版本、选中的配置路径、配置状态、实际icon store路径和已安装的已知provider pack。默认配置或icon store不存在属于正常状态；显式配置的路径无效或不可读时，命令会提供修复建议并以状态码2退出。stack config path只显示将使用的config.yaml路径，不会创建或读取该文件。

Homebrew会自动安装与binary匹配的补全和manual文件。使用直接下载、Aqua或Cargo时，可以为自己的shell生成相同且确定的文件：

text
$ stack completions bash
$ stack completions zsh
$ stack completions fish
$ stack manpage

这些命令只写入标准输出，不会修改shell启动文件。请按照shell集成指南，将输出保存到用户拥有的补全或manual目录。也可以无需安装，直接阅读offline manual：

text
$ stack manpage > stack.1
$ man ./stack.1

编写第一份文档 ​

在浏览器中试用时，打开Playground，将编辑器内容替换为下面的示例。CLI用户可以将相同源文件保存为diagram.stack，然后再次执行上面的检查与渲染命令：

stack
stack 1.0

diagram "Checkout" {
  theme default

  node shopper "Shopper" {
    kind actor
  }

  group application "Application" {
    node web "Web app" {
      kind client
      detail "React"
    }

    node api "Checkout API" {
      kind service
      detail "Rust"
    }

    layout {
      direction right
      order [web, api]
    }
  }

  node orders "Orders" {
    kind database
    detail "PostgreSQL"
  }

  edge shopper -> web "HTTPS" {
    kind request
  }

  edge web -> api "JSON" {
    kind request
  }

  edge api -> orders "SQL" {
    kind data
  }

  layout {
    direction right
    order [shopper, application, orders]
  }
}

渲染并查看 ​

选择 Run，或按 Command/Ctrl + Enter。预览区会显示独立 SVG。选择预览可放大查看，需要保存时使用 Download SVG。

源文件由四部分组成：

  1. stack 1.0 声明语言版本。
  2. diagram 提供一个标题并包含完整架构。
  3. node 和 group 声明组件与边界。
  4. edge 记录关系，layout 提供受约束的布局意图。

检查与格式化 ​

Check 在不替换 SVG 的情况下运行完整验证与布局流程。Format 保留行注释和语义，将语法有效的源文件改写成规范的两空格格式。

发现问题时，诊断会显示严重级别、稳定代码、位置、源码片段、候选值，以及可用的修复帮助。选择诊断会聚焦对应源码范围。

接下来阅读 ​

更新或卸载 ​

Stack不会自行更新。请使用安装该二进制文件的工具进行管理。卸载二进制文件不会删除配置和已导入的图标包。

安装方式更新卸载
Homebrewbrew upgrade stack-sh/tap/stackbrew uninstall stack-sh/tap/stack
Cargo用所需版本重新运行上面的Cargo安装命令。cargo uninstall stack-diagram-cli
Aquaaqua update, aqua update-checksum, aqua install保留此配置时运行aqua rm -m pl stack-sh,stack-sh/cli，然后从aqua.yaml移除stack-sh/cli。其他项目需要此包时可能会重新安装。
直接下载验证新release后，仅替换直接安装的二进制文件。仅删除自己直接安装的二进制文件（~/.local/bin/stack）。

更新恢复与artifact验证方法见安全更新和供应链验证。