Nowline

将路线图作为代码。人人皆可使用。
便于人类阅读、专为 AI 打造的路线图。
纯文本 .nowline 文件。受版本控制。可渲染为 SVG、PNG、PDF、HTML、Mermaid、XLSX 和 MS Project XML。

---

什么是 Nowline？

Nowline 是一种以文本为先的 DSL，用于描述产品和工程路线图——既便于人类阅读，也便于机器读取。你只需编写纯文本 .nowline 文件——采用缩进、关键字驱动，且便于查看差异——工具便会将其渲染为时间线、进行验证并组合内容。

examples/minimal.nowline：

nowline v1

roadmap minimal "Starter" start:2026-01-05 scale:2w author:"Jane Doe"

swimlane engineering "Engineering"
  item research "Research"  duration:3w status:done
  item design   "Design"    duration:2w status:in-progress remaining:5d
  item build    "Build"     duration:3w status:planned

渲染结果：

为什么选择 Nowline？

• 文本，而非甘特图。 受版本控制、可比较差异，且可在 PR 中审阅。
• 缩进，而非 XML。 路线图读起来像大纲，因为这符合人们的思维方式。
• 严格到足以发现错误。 提供 30 多条验证规则，以及包含行号和列号的清晰错误消息。
• 可组合。 使用 include 引入其他文件，并明确指定 merge / ignore / isolate 语义。

快速开始

通过你的包管理器安装 CLI：

brew trust lolay/tap                                 # macOS / Linux / WSL (one-time)
brew install lolay/tap/nowline

Debian/Ubuntu 和 Windows 用户可以从 GitHub Releases 获取最新的 .deb 或 .exe。完整的安装方式列表（包括 man nowline 设置）请参阅 packages/cli/README.md。

工具链

采用两层 Node 策略：使用 @nowline/* 包时要求 Node ≥ 22（每个已发布包的 engines.node），进行开发时使用 Node 26（.nvmrc）。CI 会在每个 PR 中测试这两个版本。完整策略和升级流程请参阅工具链与支持的版本。

渲染你的第一个路线图：

nowline examples/minimal.nowline                     # writes ./minimal.svg
nowline --version

或者根据模板创建一个全新的文件：

nowline --init my-project                            # ./my-project.nowline
nowline --init my-project -t teams                   # ./my-project.nowline (teams template)

要为 AI Agent 提供 Nowline 工具，请从此仓库的市场安装插件。在 Claude Code 中：

/plugin install nowline --marketplace lolay/nowline

GitHub Copilot CLI 和 Codex 使用同一个市场；有关这些工具以及添加 MCP 服务的其他方式，请参阅 plugins/nowline/README.md。

对于 VS Code / Cursor / VSCodium 扩展，请在 VS Code Marketplace 或 Open VSX 中搜索 Nowline。

0.x 版本号。 在确定嵌入接口和 IDE 扩展范围期间，nowline 使用 0.x.y 版本号。次要版本之间的公共 API 可能会变化；发布 1.0 后才会全面遵循 SemVer 保证。版本约定请参阅 specs/releasing.md。

要从检出目录运行以进行本地开发（pnpm install && pnpm build），请参阅 CONTRIBUTING.md。

使用 CLI

nowline 无需动词：默认执行渲染。其他操作通过同一命令的标志指定。

渲染（默认）

nowline roadmap.nowline                          # writes ./roadmap.svg
nowline roadmap.nowline -f png                   # writes ./roadmap.png
nowline roadmap.nowline -f pdf                   # writes ./roadmap.pdf
nowline roadmap.nowline -f html                  # writes ./roadmap.html
nowline roadmap.nowline -f mermaid               # writes ./roadmap.md
nowline roadmap.nowline -f xlsx                  # writes ./roadmap.xlsx
nowline roadmap.nowline -f msproj                # writes ./roadmap.xml
nowline roadmap.nowline -o roadmap.pdf           # format inferred from extension
nowline roadmap.nowline -o -                     # SVG to stdout
nowline roadmap.nowline --theme dark --now 2026-03-15
nowline roadmap.nowline --now - --asset-root ./brand --no-links --strict
nowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in
cat roadmap.nowline | nowline -                  # stdin → ./roadmap.svg

渲染流水线依次为 @nowline/core 解析 → @nowline/layout 布局 → @nowline/renderer SVG → 特定格式的导出器。对于相同的输入、主题和 --now，输出的每个字节都保持确定一致。单个 nowline 二进制文件包含所有格式；安装详情请参阅 packages/cli/README.md。

验证（--dry-run）

运行完整流水线（解析 + 验证 + 布局 + 格式化），但不写入文件。成功时退出码为 0，如果产生任何错误，则退出码为 1。

nowline roadmap.nowline --dry-run
nowline roadmap.nowline -n                          # short alias
cat roadmap.nowline | nowline - --dry-run           # read stdin
nowline roadmap.nowline -n --diagnostic-format json # machine-readable output
nowline - -n --format=json < roadmap.nowline        # same, json is the default here

--diagnostic-format text|json 用于选择标准错误输出的格式；使用 --dry-run --format=json 时默认为 json，否则默认为 text。JSON 模式下，只要存在任何诊断信息（包括警告），就会向标准错误输出一个 { "$nowlineDiagnostics": "1", "diagnostics": [...] } 文档，因此仅有警告的源文件会以退出码 0 退出，并输出该文档。没有问题的源文件不会输出任何内容。

转换文本 ↔ JSON

转换只需使用 -f json（反向转换则使用 -f nowline）。输入格式根据扩展名推断；对于不常见的文件名，可使用 --input-format 覆盖。

nowline roadmap.nowline -f json -o roadmap.json    # text → JSON
nowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)
nowline roadmap.nowline -f json -o - | jq '.ast.roadmapDecl.name'

生成的 JSON 顶层包含 "$nowlineSchema": "1"，供下游工具检测架构变更。往返转换不会保留注释——规范打印规则请参阅 packages/cli/README.md。

服务（--serve）

在浏览器中运行可实时重新加载的预览。非常适合编写内容时使用。

nowline roadmap.nowline --serve                    # http://127.0.0.1:4318
nowline roadmap.nowline --serve -p 4400 -t dark --open
nowline roadmap.nowline --serve -o latest.svg      # rewrite latest.svg on each rebuild

每次文件变更后，服务都会重新解析、重新验证、重新布局并重新渲染；已连接的客户端会通过服务器发送事件自动刷新。验证错误会以覆盖层的形式显示在最近一次成功渲染的内容上。

初始化（--init）

在当前工作目录中创建新的 .nowline 文件。位置参数是项目名称，而不是文件路径。系统会自动追加 .nowline。

nowline --init                              # ./roadmap.nowline (default name)
nowline --init my-project                   # ./my-project.nowline
nowline --init my-plan.nowline              # ./my-plan.nowline (literal)
nowline --init my-project --template=teams  # use the teams template

minimal、teams 和 product 分别对应 examples/ 目录下的文件。已有文件会被静默覆盖。

退出码

代码	含义
0	成功
1	验证错误（解析失败、引用无效、任何包含错误，例如缺少被包含文件、跨被包含文件的 wave 规则）
2	用法错误（缺少输入、标志错误、格式不受支持、文件不存在、标准输入为空、--diagnostic-format 无效、拒绝将二进制输出到 TTY）
3	输出错误（无法写入目标位置）

手册

安装任意一种软件包管理器提供的版本（brew install lolay/tap/nowline、npm install -g @nowline/cli 或 GitHub Releases 中的 .deb）后，运行 man nowline 查看 CLI 手册，运行 man 5 nowline 查看完整的 DSL 参考。每个 GitHub Release 也都附带这两个 man 页面作为独立资源——mdoc 源文件请参阅 packages/cli/man/。

语言概览

文件结构

nowline v1                        // 1. version directive (optional, must be first)

include "shared/teams.nowline"    // 2. includes
include "brand.nowline" config:isolate

config                            // 3. config section (optional)
scale
  name: weeks
style enterprise
  bg: blue
  fg: navy

roadmap r "My Roadmap"            // 4. roadmap section

swimlane platform
  item x "Work item" duration:1w status:done

实体

关键字	用途
roadmap	顶层路线图声明。每个文件最多一个。
swimlane	工作的水平泳道。
item	泳道内的一个工作单元。
parallel	子项并发运行的代码块。
group	逻辑分组，组内项目会一起渲染。
anchor	时间线上的命名日期。
milestone	依赖于工作的时间点标记。
wave	横跨所有泳道的屏障：当前 wave 结束前，下一 wave 中的工作不会开始。
footnote	锚定到一个或多个实体的说明。
person、team	所有权引用。
non-working、working	不消耗工作时间的日期（周末、节假日、停工日），以及使这些日期恢复为工作日的例外。配置项可使用 date:、start: / end: 或 every:；名为 weekend 的声明会替代常规周末设置。带标题的定休日会在图表上标注（Thanksgiving · 2d），并纳入 MS Project 和 Mermaid 导出；带标题的工作日会标注其增加的天数（Crunch Saturday · +1d）。
style、symbol、label、size、status、scale、calendar、default	配置项和声明。

属性

item auth "Auth refactor"
  duration: 2w              // duration literal: d, w, m, q, y
  status: in-progress       // builtin or custom from config
  owner: sam                // id reference (person or team)
  wave: build               // barrier the item belongs to (a declared wave)
  after: kickoff            // dependency (single)
  after: [kickoff, approvals] // dependency (list)
  remaining: 30%             // percentage
  labels: [security, p0]     // list of label ids
  link: https://…            // URL (bare, no quotes)

路线图开始日期

roadmap 可以带有可选的 start:YYYY-MM-DD，用于确定时间线基准：

roadmap platform-2026 "Platform 2026" start:2026-01-06

• 如果路线图包含任何 anchor，或任何带有 date: 属性的 milestone，则必须指定 start:。
• 每个此类日期都必须等于或晚于 start:。
• 纯相对路线图（仅使用 duration: 和 after: 构建）无需指定 start:。
• 对于未使用 roadmap:ignore 的 include，父级与任何被包含的路线图必须对 start: 达成一致——要么都不指定，要么都指定相同的值。不一致会导致错误，而不会静默覆盖。

包含

include "teams.nowline"                     // merge everything (default)
include "snippet.nowline"  config:ignore    // skip child config
include "partner.nowline"  roadmap:isolate  // render child as a separate region

• merge — 默认值：合并子内容；发生冲突时以父级定义为准。
• ignore — 丢弃该类型的子内容。
• isolate — 将子路线图保留为独立区域（要求子文件中包含 roadmap）。

Waves 永不合并。在 roadmap:merge 或 roadmap:isolate 下，声明了路线图、泳道或 waves 的被包含文件必须声明与父级相同的 waves，且顺序相同、开始下限相同（NL.E0202）。

完整语法参考请参阅 specs/dsl.md。

示例

这里提供了由浅入深的示例。每次构建 main 时，都会在 review.nowline.dev 渲染这些示例以及 tests/ 中的渲染器测试样例。

• examples/minimal.nowline — 最精简的完整文件。
• examples/capacity.nowline — 泳道和事项的 capacity:，其中值班支持占用团队四分之一的带宽；泳道利用率下划线。
• examples/sizing.nowline — T 恤尺码的 size: 条目，以及通过 capacity: 缩短日历跨度（并行工作）。
• examples/teams.nowline — 人员、团队、锚点、里程碑、脚注。
• examples/product.nowline — 完整配置、样式、标签、并行项、分组、描述。
• examples/long.nowline — 压力测试：八个泳道、约 160 个事项、并行项、分组、锚点、里程碑、脚注、跨领域标签。用于布局和渲染性能测试。
• examples/nested.nowline + examples/nested/ — 父级 Security 泳道，加上五个按团队隔离的路线图包含项（iOS、Android、Web、Platform、Data）。展示 roadmap:isolate。
• examples/waves.nowline — wave 屏障：三个泳道中的三个 waves（Foundations、Build、Launch）、用于分配子项的 group wave:、不属于任何 wave 的后台工作，以及 after: 某个 wave 的里程碑。
• examples/waves-program.nowline + examples/waves-program/ — 多团队 waves：Web 和 API 团队文件重新声明相同的 waves（带有开始下限），因此每个文件都能单独渲染，而项目文件会将它们合并到同一道屏障之后。

编辑器支持

TextMate 语法定义位于 grammars/nowline.tmLanguage.json。它适用于任何支持 TextMate 语法的编辑器（VS Code、Sublime Text、Zed、通过第三方插件支持的 IntelliJ 等）。一流的 LSP 服务和 VS Code 扩展正在 packages/lsp/ 和 packages/vscode-extension/ 中开发。

作为库使用

@nowline/core 是一个基于 Langium 构建的纯 TypeScript 解析器、类型化 AST 和验证器。CLI 在解析之上执行的所有操作本身也都是基于此库构建的。API 和使用示例请参阅 packages/core/README.md。

状态

Nowline 目前处于 v0.x 阶段——已发布到 Homebrew、npm、VS Code Marketplace、Open VSX 和 GitHub Releases。解析器、验证器、布局、渲染器、所有导出格式（SVG、PNG、PDF、HTML、Markdown+Mermaid、XLSX、MS Project XML），以及精简版 CLI（--dry-run、--init、--serve）现已可用。在嵌入接口和 IDE 扩展趋于稳定期间，不同 0.x 次版本之间可能会有破坏性变更；完整的 SemVer 保证将在 1.0 开始生效。按版本发布的路线图位于 specs/milestones.md。

参与贡献

欢迎提交错误报告、功能请求和拉取请求。请先阅读 CONTRIBUTING.md，了解环境设置、构建 / 测试命令以及预期工作流程。提交议题前，请先查看 .github/ISSUE_TEMPLATE/ 下的模板。安全问题请遵循 SECURITY.md。所有参与者均须遵守我们的 CODE_OF_CONDUCT.md。

DSL、渲染器、CLI、IDE 集成和开源里程碑的设计规范均位于 specs/ 下——修改代码前，请先从这里开始，了解 Nowline 的设计。

许可证

Apache 2.0——详见 LICENSE。