Versions and Changelog

A Context knowledge workspace has its own version: package.json.version, a SemVer. Each completed delivery records one new version with a short changelog, and the package, the website and LLM Docs all carry it. Intermediate batches and worker results never get their own version.

flowchart LR
  rv["Review approved"] --> cl["Close"]
  cl --> pk["Package and template<br/>decisions"]
  pk --> tr["Site translation"]
  tr --> ver["Record version<br/>and changelog"]
  ver --> b["Final build"]

Which number changes

Change in the delivery	Increment
Added modules or material that expands coverage	Minor
Corrections, updates to existing modules, navigation, persistent status	Patch
Anything you explicitly call a major version	Major — only on your instruction

The first version is 0.1.0 unless the knowledge workspace already has a higher one or you specify another. Temporary progress under .tmp/ never changes the version.

How it is recorded

The Agent runs context version inspect to see the formal changes — article bodies, assets, structure, navigation and templates — then writes the entry and submits it with context version record:

expected_digest: "<digest returned by inspect>"
version: 0.2.0
title: Add module recovery guidance
changes:
  - Document recovery conditions and the supported retry flow.
triggers:
  - kind: module
    description: Additional module material requested in this iteration.

Trigger kinds are initial, note, sessions, mr, module, document, navigation, repair, dist, translation and other. The optional actor defaults to the local Git user.name; the Agent never guesses an identity. Each entry stays within 1500 visible characters, compressed by merging related changes rather than truncated or split. Entries never contain credentials, raw transcripts, local absolute paths or private account IDs.

The CLI updates package.json, changelog.yaml and the generated CHANGELOG.md together. version inspect --base <commit-or-tag> compares against a specific Git point; by default it uses the current version's v<version> tag, or HEAD.

Retries and republishing

A failed build reuses the recorded version; retrying does not bump it. If formal content has to change after a failed build, an unpublished version can be amended. Once content has been published, any further change needs a higher version. A local build alone does not seal a version, and recording one never commits, tags, uploads or deploys anything.

Where readers see it

The website has a history page, changelog.html: cards newest first, the latest three expanded and older ones collapsed. The History button beside the theme switch and the footer's update time link to it. Knowledge packages and LLM Docs carry the same version and changelog.

Going back to an earlier version

Ask the Agent to restore a version — "restore the knowledge as of last Friday" or "go back to the previous version". It resolves that to a concrete commit and path scope, abandons unfinished task state, restores only the agreed knowledge workspace paths with Git, and restores the sources pinned by that version. It never resets the whole repository, and existing build output is stale until rebuilt. Nothing is committed or pushed automatically.

版本与 Changelog

Context 知识工作区有自己的版本：package.json.version，采用 SemVer。每次完成交付都会记录一个新版本和一段简短的 Changelog，知识包、网站和 LLM Docs 都会带上这个版本。中间批次和 worker 结果永远不会单独获得版本。

flowchart LR
  rv["审核通过"] --> cl["Close"]
  cl --> pk["知识包与模板<br/>决策"]
  pk --> tr["站点翻译"]
  tr --> ver["记录版本<br/>和 Changelog"]
  ver --> b["最终构建"]

哪一位数字会变化

交付中的变化	递增
新增模块或扩大覆盖范围的材料	Minor
修正、对现有模块的更新、导航、持久状态	Patch
你明确称为主版本的任何变化	Major，仅在你指示时

除非知识工作区已有更高的版本或你另行指定，第一个版本是 0.1.0。.tmp/ 下的临时进度永远不会改变版本。

如何记录

Agent 先运行 context version inspect 查看正式变更，包括文章正文、资源、结构、导航和模板，然后撰写条目，并通过 context version record 提交：

expected_digest: "<digest returned by inspect>"
version: 0.2.0
title: Add module recovery guidance
changes:
  - Document recovery conditions and the supported retry flow.
triggers:
  - kind: module
    description: Additional module material requested in this iteration.

触发类型包括 initial、note、sessions、mr、module、document、navigation、repair、dist、translation 和 other。可选的 actor 默认取本地 Git 的 user.name；Agent 从不猜测身份。每个条目不超过 1500 个可见字符，超出时通过合并相关变更来压缩，而不是截断或拆分。条目中绝不包含凭据、原始对话记录、本地绝对路径或私有账号 ID。

CLI 会同时更新 package.json、changelog.yaml 和生成的 CHANGELOG.md。version inspect --base <commit-or-tag> 与指定的 Git 节点进行比较；默认使用当前版本的 v<version> 标签，或 HEAD。

重试与重新发布

构建失败时会复用已记录的版本，重试不会递增版本。如果构建失败后必须修改正式内容，可以修订尚未发布的版本。内容一旦发布，后续任何改动都需要更高的版本。仅在本地构建并不会封定版本，而记录版本也从不会提交、打标签、上传或部署任何内容。

读者在哪里查看

网站有一个历史页面 changelog.html：卡片按从新到旧排列，最新的三张展开，较早的折叠。主题切换旁的 History 按钮和页脚的更新时间都链接到该页面。知识包和 LLM Docs 带有相同的版本和 Changelog。

回到较早的版本

让 Agent 恢复某个版本，例如*“把知识恢复到上周五的状态”或“回到上一个版本”*。它会把请求解析为具体的提交和路径范围，放弃未完成的任务状态，用 Git 只恢复约定的知识工作区路径，并恢复该版本固定的来源。它从不重置整个仓库，现有的构建产物在重新构建之前都是过时的。不会自动提交或推送任何内容。