chrona：实践指南

工作中遇到相关需求时，chrona值得先读说明，因为它主要用于YAML 项目文件中的精美甘特图幻灯片，定义计划，选择演示文稿，渲染 SVG 或 PNG，时间表是计算出来的，而不是绘制出来的。在文档与演示交付场景里，常见问题是内容结构和版式在转换后容易走样，这正是评估时需要盯住的地方。我的评估方法是拿一份结构复杂的真实文档完成转换，然后检查标题层级、表格图片、字体版式和可编辑性是否与文档一致。整体来看，它适合经常交付正式文档或演示稿的团队拿来做对照测试，最终决定仍应回到真实结果和维护状态。

克罗纳

chrona 是一种 Git 友好的语法，用于临时项目数据、调度和 可视化。 它的真实来源是语义、结构化数据；渲染器是 消费者，从来不是编辑拥有的权威。

该存储库包含实时的、版本化的 chrona 规范和参考 已接受的交付里程碑的实施。核心v0.1保持稳定 仅限日期的调度配置文件；后继者 DateTime、容量、协作和 演示功能是选择加入版本化配置文件，而不是更改 仅日期含义。

^{Manifest-declared 来自 examples/aster-ssd 的物化证据。 编辑项目，重新运行物化器，就出现这个SVG follows.}

今天可以用什么

• 确定性日期 / CalendarPeriod / WorkPeriod 算术；
• 项目 JSON-Schema 验证加上核心 v0.1 语义验证；
• 基于端点的依赖性下限和仅限日期的计划跨度放置；
• 规范 Core v0.1 夹具的可执行一致性检查；
• 确定性 Plan/Actual 审查 SVGs 与 YAML- 受控图例、组详细信息、 来源标记的观察结果和里程碑摘要；
• 经过测试的代理技能，与 chrona skill copy 一起安装，教授 AI 编码 代理此工作流程，以及 MCP 服务器（chrona mcp，可选 chrona[mcp] 额外；只读，除非使用 --allow-write 启动） 没有 shell 的主机（请参阅 使用来自 AI 编码代理 的 chrona）。

快速启动

python -m pip install -e '.[dev,render]'
pytest
chrona validate path/to/project.yaml
chrona schedule path/to/project.yaml
python -m chrona validate path/to/project.yaml

草稿渲染默认为内容大小的 1600xauto 视口。使用 当您需要有限的最小分配时，显式 --viewport WIDTHxHEIGHT 。 auto 请求仅是草案；不可变的渲染上下文保持有限 environment.viewport.blockSize.

在 Windows 上，python -m chrona 相当于安装的 chrona 命令 并避免依赖于虚拟环境的 Scripts 目录 PATH。贡献者应保留存储库的.gitattributes；它别针 LF 身份绑定 YAML、JSON、SVG 和架构资源的签出字节。

validate 和 schedule 还接受不可变的本地快照而不是 原始草稿路径：

chrona schedule \
  --snapshot-reference project-reference.yaml \
  --snapshot-root .chrona/snapshots \
  --store-identity local-workspace

chrona render-review 仅消耗不可变的渲染上下文 v0.8 引用。主题， 布局、视图、可选的 detail/summary 输入、视口和字体规格由此关闭 布局或场景构建之前的上下文。

chrona schedule 是非循环 Date-only 的参考实现 子集。它报告不受支持的周期的诊断，而不是治疗所有周期 循环作为语义错误。

chrona render 是第一个派生的表示切片：它投影 将放置解析为确定性 SVG 时间线。 SVG坐标不是 项目数据，绝不会用于安排或验证项目。

尝试包含的仅计划控制器示例。 render刻意要求 每个演示文稿都明确输入；省略 --actual 因为此视图声明 它是可选的：

chrona render examples/controller-z/project.yaml \
  --view examples/controller-z/views/plan-only.yaml \
  --theme examples/controller-z/themes/executive-light.yaml \
  --scheme examples/controller-z/schemes/executive-light.yaml \
  --layout examples/controller-z/layouts/executive-review.yaml \
  --output controller-z-plan.svg

对于具有固定和预定跨度的更广泛的半导体启动示例，工作日 例外、端点依赖性、并行资格认证工作、门、实体、 注释和观察，添加执行视图和实际集：

chrona render examples/controller-z/project.yaml \
  --view examples/controller-z/views/executive.yaml \
  --theme examples/controller-z/themes/executive-light.yaml \
  --scheme examples/controller-z/schemes/executive-light.yaml \
  --layout examples/controller-z/layouts/executive-review.yaml \
  --actual examples/controller-z/actual.yaml \
  --output controller-z.svg

演示幻灯片

Plan/Actual 审查表面是从具体化的 v0.8 上下文渲染的：

chrona render-review \
  --context-reference context-reference.yaml \
  --snapshot-root .chrona/snapshots \
  --store-identity local-workspace \
  --output executive.svg

可重复使用的创作文件位于 views/、themes/、layouts/ 和可选目录下 profiles/。不同的主题会改变具体的视觉标记；不同的布局变化 组合而不改变选定的事实。

对于一副牌组，为每个视图生成一个 v0.8 上下文，同时绑定相同的不可变项目， 实际、主题和布局资源。 examples/aster-ssd/manifest.yaml 列出复用； contexts/01-overview.yaml 显示一个生成的绑定。通过渲染每个上下文 相同的 chrona render-review 命令，因此调度和演示事实不会发生变化。

examples/aster-ssd 是工作示例：24 个对象， 跨两个工作日历的 28 个依赖项计划，投影到四个 1600x900 中 幻灯片加上高大的主视图。删除 --no-raster 也可以编写 PNG 预览； 该路径还需要带有 sharp 的节点。

本地创作

简洁的计划

简洁的计划 (plan.chrona) 是起草时间表的最快方法：每个任务、门或组一行， 依赖关系作为子句就行了。 chrona validate、schedule 和 render 直接接受，并且 一旦计划最终确定，chrona compile 就会编写项目 YAML（YAML 是此后的来源）。的 一页卡 具有完整的语法。

project my-plan "My plan"
design "Design" task 2026-10-01..2026-10-15
build "Build" task 3w after design
release "Release" gate 2026-11-20 after build

chrona render plan.chrona --output plan.svg

便携式图标

从显式本地 Iconify 集合创建一个目录，然后传递该目录 目录明确地绘制草稿。目录在渲染之前被标准化； chrona 从不读取原始 SVG 或在渲染时联系注册表。 导入器将确定性 JSON（YAML 子集）写入请求的 .yaml 路径，因此在快速加载大型目录时它仍然有效 YAML。

chrona icon-catalog import icons.json --license-spdx MIT --notice-file NOTICE \
  --output icons.yaml
chrona render project.yaml --view view.yaml --theme theme.yaml --scheme scheme.yaml \
  --layout layout.yaml --icon-catalog icons.yaml \
  --visual-profile chrona-output/visual/v0.7-svg --output review.svg

声明性主题资源源可以提供许可的字形和 图案；其 SPDX 标识符和完整的通知在目录中旅行。

chrona icon-catalog import --theme-assets assets.yaml --output assets-catalog.yaml

在视图中，将目录条目附加到现有目标。 decorative: false 需要目录替代并保留现有文本作为等效文本 含义：

visuals:
  - target: {kind: title}
    ref: chrona:risk
    side: leading
    decorative: false

请参阅 规范 64 和 控制器 Z 的图标 上下文 完全固定的具体化示例。

创建一个小型可编辑项目并使用捆绑的渲染其第一个草稿 默认演示预设：

chrona init my-chrona-project
chrona render my-chrona-project/project.yaml --actual my-chrona-project/actual.yaml \
  --viewport 1600xauto --output my-chrona-project/plan.svg

由此产生的 SVG 是供审查的草案，而不是不可变的物化器证据。 生成的三个源文件可供您编辑。 使用 --preset PATH 来 选择显式演示预设，或显式 View/Theme/Color 方案/ 覆盖其成员的布局路径。

完整的可复制 HALCYON 语料库仍然明确可用：

chrona init my-halcyon-example --example halcyon-1
chrona materialize my-halcyon-example/manifest.yaml \
  --slide mission-brief --output my-halcyon-example/out

init 拒绝非空目标。 HALCYON 示例保持其不可变 .chrona/store 下的商店关闭；使用配置的 Store 的命令 更喜欢显式的 --store-config，否则会发现 .chrona/store.yaml 从当前项目目录向上走。没有主目录或 使用广泛的文件系统后备。

init --example 将 integrity: optional 写入该 Store 配置，并带有注释 说出原因：示例上下文在设计上未固定内部引用 （ADR-0030）。简单的 chrona init 和其他所有 Store 都保留内容身份 required。 第一个项目 显示使用 render-review --store-config 渲染此 Store 的示例上下文。

物化验证声明的生成证据。如果经过审查的来源 更改故意更改该工件，重新运行相同的 chrona materialize 使用 --write 命令刷新它；如果没有明确的标志，则不匹配 被拒绝了。

规格

当前规范集维护在 docs/specification/ 中。 公共模式位于 schemas/ 中，可执行兼容性装置位于 conformance/。 Git 历史记录和版本化清单更早地保存 候选人。从以下开始：

1. docs/specification/00-vision.md
2. docs/specification/03-temporal-model.md
3. docs/specification/04-scheduling-model.md
4. docs/specification/05-project-format.md
5. docs/specification/17-implementation-delivery-profile.md

核心v0.1稳定。通过诊断记录实施发现， ADRs，以及实施更改之前设计优先的修复。