katra

katra

一份提交到版本库的富组件开发日志，在开发过程中随手记录——适用于独立开发者或与编码 Agent 协作的开发者，也是让规范驱动的 Agent 式开发得以实现的记忆载体。日志以 Markdown 条目形式呈现，嵌入交互式组件，并自动附上所描述工作的提交和差异统计信息；它以实时、自动重新加载的页面形式提供。

它旨在让一种工作流变得可靠：随着工作推进记录历程——记录原因、走过的弯路、截图和动画——绝不因跳过“发布”步骤而丢失草稿。

同一存储也能让 Agent 在不同会话间保持高效：设计以已提交规范的形式保存，任务指向这些规范，而新会话启动时可以直接读取规范，而不是从一段早已不存在的对话中重新推导意图。下文的Agent 工作流介绍了这个循环。

katra init --install-hook        # store + portable Git auto-stamp
katra new "Reworked the swing"   # start a draft (a markdown file)
katra capture shot.png           # drop a screenshot into it
katra compare before.png after.png
katra serve                      # live page on the LAN, reloads as you write
git commit -m "…"                # the draft is stamped with this commit

核心理念

**没有提交哈希的条目就是草稿。**这就是完整的状态机。

创建条目后，它便会立即出现在进行中面板中。没有临时文件，没有单独文档，也没有“发布”开关。为条目加上哈希和差异统计信息，也就是盖上提交戳，这时它就会进入日志。

其他一切都由此而来。不会有任何内容被遗忘在你忘记发布的缓冲区里，因为根本没有缓冲区。日志会按照你实际工作的顺序记录所有内容，包括最终没能奏效的部分，而压缩后的历史记录总会遗漏这半段历程。

查看器

katra serve 会将存储内容呈现为实时页面——无需构建，也无需在写作期间重新生成静态 站点。中央的主线按照事情发生的顺序记录日志：未来的史诗任务、此刻正在进行的条目，然后是 过去。右侧栏会展示平铺文件列表中被埋没的内容——仍然承载关键内容的决策，以及一段工作贯穿了哪些标签。

更多截图

打开的条目——这项工作在草稿阶段中途发布，其中包含一个前后对比滑块，用来比较两个图标标记 方案；该滑块通过 katra compare 拖入：

按状态分组的看板——specced 是 todo 和 doing 之间的独立一列，供已经确定设计、但尚无人着手实现的任务使用：

项目中心，一页展示这台机器上所有已注册项目——这是维护者自己的项目中心，包含 14 个项目和 25 个正在进行的事项，没有任何内容需要 在其他地方重复录入：

问题

你熬过了艰难的一周。提交记录写着 fix streaming、wip、actually fix streaming。六个月后，你需要知道为什么生成预算采用最近优先，而答案不在差异中——它当时在你的脑海里，也在一张你已经找不到的 截图里。

常见的解决办法都有同一个问题：它们都是一份额外工作。

• CHANGELOG.md 记录的是发布了什么，而不是你学到了什么；而且它是在发布时根据你正试图解释的差异编写的。
• Wiki 或 Notion 页面不在代码库中，因此会立即与代码脱节，而且别人克隆代码库时也看不到它。
• 博客文章是在事后凭记忆写成的——恰恰在这时，你需要的细节已经消失了。
• Conventional commits 能以机器可读的方式记录做了什么，却没有空间记录为什么、图片或你舍弃的其他方案。

它们共同的问题在于，都是工作完成后的一个步骤；工作一旦拖长，任何事后步骤都会被跳过——而那恰恰是日志最有价值的时候。

katra 的设想是，日志必须是工作时的副产物，而不是工作结束后才进行的任务。因此，草稿会在你开始时创建，随着工作推进逐步积累截图和推理过程，而你本来就要进行的提交会负责发布它。

Agent 工作流

这是 katra 的核心，也是它的形态与静态站点生成器相比显得古怪的原因：它旨在避免两样东西在不同 Agent 会话之间丢失——Agent 应依据构建的设计，以及构建实际进展的记录。

在最后才记录日志的 Agent，写下的只是对差异的总结——而差异本身已经告诉你这件事。真正丢失的是最终状态之前的一切：失败的方案、改变计划的测量结果、Bug 的截图。因此，katra 将日志记录融入工作流程。通用约定是 Katra 工作流中的 CLI 操作序列：声明 epic/task，在适用时附加并阅读已提交的规格说明，在实施前开启草稿，过程中记录决策和证据，然后盖章并关闭。无论使用 Codex、Claude Code、MCP 还是普通 shell，都适用。

katra init --install-hook

这会创建 Katra，并安装与框架无关的 Git post-commit 自动盖章钩子。Claude Code 用户还可以运行 katra setup，安装其技能和七个会话钩子。启用这个可选适配器后：

1. SessionStart 会报告当前草稿、尚未解决的记忆，或需要协调的进行中改动。
2. PostToolUse 会记录 Agent 编辑的每个文件。
3. Stop 会阻止本轮结束，前提是本轮编写的代码发生了变化，却没有说明这些代码的用途。
4. PreToolUse 会阻止提交暂存代码时使用 git commit，但没有协调回执。
5. 你的提交会触发 post-commit hook，为草稿盖章。

门禁是大家最关注的部分，因此有必要准确说明它何时触发。只有当本轮编写的代码仍存在于工作树中、位于 katra 目录之外，且没有人说明其用途时，门禁才会阻止操作。对话轮次不会被阻止。编辑后又还原，最终没有留下改动，也不会被阻止。别人预先留下的未提交改动不属于你的工作，也不会触发阻止。同一份未变化的工作不会导致同一轮被阻止两次。

要满足要求，<task> 是 katra task list 返回的 slug（也可以用 katra task new 创建一个）：

katra reconcile --advance <task>   # this moves a task forward
katra reconcile --close   <task>   # this finishes one
katra reconcile --no-task --reason "…"
katra reconcile status             # what does the gate want right now?

如果你正在试用 katra，请使用 katra setup --no-gate。 这样既能获得提醒和自动盖章，又不会阻止提交；之后可以重新运行 katra setup 来启用门禁。在每个仓库中安装阻止操作的钩子，会实实在在地改变提交时的体验，因此应该由你有意识地选择是否启用。

此外还有一个 MCP 服务（katra-mcp），供更愿意调用工具而不是通过 shell 执行命令的客户端使用。它的 15 个工具涵盖条目、任务、任务规格、epic、决策和文章。详情请参阅：Katra 工作流和 Agent。

首个版本发布后，官方 MCP Registry 将能够通过一个精简的 OCI 包发现同一个 stdio 服务端。该镜像只包含 katra-mcp 和 git；之所以提供它，是因为 Registry 需要可安装的包，而不是因为容器是使用 Katra 的更好方式。Registry 客户端仍须向它提供仓库工作树。若要直接使用，请安装上文的原生二进制文件。

由规范驱动，而非从规范推导

当前源码功能： 已安装的 v0.1.0 CLI 尚不支持 task spec、task new --spec 或列表筛选帮助中的 specced 值。 在下一个版本发布之前，此阶段请使用 make all 构建当前源码； 发布检查清单现在会针对打包后的二进制文件验证这三项功能。

任务可以带有 spec:——指向 katra 中某个节点的 slug（决策、文章或条目），也可以是相对于仓库根目录的路径，解析方式与 [[wikilink]] 相同。katra task spec <slug> <ref> 会将其关联到任务，并将任务从 todo（或空状态）移至一个新状态 specced：设计已经完成并提交，但还没有人开始实现。

katra task new "Cache swap"                           # todo, slug: cache-swap
katra decide "Cache invalidation: TTL, not events"   # write the design
katra task spec cache-swap cache-invalidation-ttl-not-events   # by node slug
katra task start cache-swap                          # -> doing, implement from it

这样做能提高实现效率，而且效果会在多个会话间累积：刚开始工作的 Agent——新的上下文窗口、不同的一天——可以阅读规范，而不必从一段已经不存在的对话中重新推导意图。katra task list --status specced 就是工作清单。规范并非必需；todo → doing 仍然合法，而且大多数任务不值得专门写规范。对于值得先写下设计的任务，specced 只是一个介于“我们应该做这件事”和“有人正在做这件事”之间的状态；而你在实现过程中写下的条目，则构成记录的另一半：规范中的设想与实际发生的情况，包括走不通的路。

可选的 Claude Code 记忆导入

Claude Code 会为每个项目保留原生记忆。katra 可以将其导入私有日志，这样日志就能记录完整过程，无需任何人重新输入。默认只接收 metadata.type: project 的记忆，不接收 user（关于你是谁）或 feedback（你喜欢怎样的协作方式），因为两者都不应进入已提交的日志。任何匹配机密信息检测器或你在 sensitiveTerms 中列出的词语的内容，都会被隔离，而不会提供给你。

日志本身位于 katra/.state/memory-ledger.json，并且刻意保持为本地文件且被 git 忽略——原始 Agent 记忆是未经审核的、关于你和你的机器的文本，默认绝不应进入共享分支；只有你选择据此撰写的文字才会进入。因此，“审核”意味着在产生这些内容的机器上处理 katra memory scan | status | resolve | ignore 队列：克隆仓库的队友会得到你的条目，而不是你的日志。

替代方案

采用之前请先阅读。多种工具都能完成其中一部分，其中一些可能更适合你的需求。

工具	在以下情况下改用它
Keep a Changelog + release-please	你需要面向用户的发布记录，说明发布了什么。这与记录原因的工作文档不同，大多数项目两者都应该有。
adr-tools / Log4brains	你只想记录架构决策。ADR 的格式更精简、规范；katra 的 decide 是有意设计得更轻量的类似工具。
Obsidian、Logseq、wiki	笔记是个人的，涉及多个项目，放在代码仓库中并非重点。katra 面向单个代码仓库，并且有意将内容提交到仓库中。
Hugo、Jekyll、Astro	你要写公开博客。它们有主题、订阅源、分类体系和受众；katra 都没有，也不打算提供。
Notion、Linear、Jira	你需要负责人、权限和共享的团队工作流。katra 的任务是为了从条目中链接过去，而不是用来管理团队。
git log 和良好的提交信息	老实说，这种情况相当常见。如果你的提交已经包含推理过程，而且你从不需要配图，那就不需要这个工具。

这些工具都做不到、而本工具存在的目的，是让日志留在代码仓库中，在工作进行时记录而不是事后补写，内嵌截图和交互式组件，并由你本来就会创建的提交发布。如果你不需要这四点中的全部，那么上述工具之一会更适合你，而且已经历经多年实践检验。

安装

macOS、Linux 和 Windows 的 amd64 与 arm64 架构均提供二进制文件。

go install

这是主要安装渠道，也是首个版本发布前唯一可用的安装方式（参见下文的 Homebrew 和下载二进制文件）。如果你已经安装 Go 1.25 或更高版本，这是合适的方式：

go install github.com/craigjmidwinter/katra/cmd/katra@latest
go install github.com/craigjmidwinter/katra/cmd/katra-mcp@latest

两者都要安装。katra-mcp 并非可有可无的额外工具——技能和所有 MCP 客户端配置都假定它与 katra 一同位于你的 PATH 中。

通过 go install 构建的版本会报告你安装的版本—— go install …@v0.1.0 会报告 v0.1.0，从工作树安装则会报告包含提交信息的伪版本。发布二进制文件和 make build 则会附带链接时戳，还会标记工作树是否有未提交的更改。

从源代码构建

git clone https://github.com/craigjmidwinter/katra
cd katra
make install        # both binaries into GOBIN, version stamped

make build 会将文件写入 ./bin/，而不是代码仓库根目录，因为 katra 会用自身记录自身；./katra 正是其自身日志所在的目录。

如果你想检查发布包会包含什么，make snapshot 可以在本地构建完整的发布归档（需要 goreleaser）。

Homebrew

目前尚未发布任何版本，因此此 tap 在 v0.1.0 发布之前没有可安装的内容——RELEASING.md 介绍了如何发布首个版本；发布之后，以下说明才会生效：

brew install craigjmidwinter/tap/katra

此命令会添加 craigjmidwinter/homebrew-tap 并安装预构建的二进制文件。brew upgrade katra 会跟进新版本。

下载二进制文件

与 Homebrew 一样，只有发布工作流触发后才会生成这些归档，因此 v0.1.0 之前还没有。每个 release 发布后，都会提供适用于 macOS、Linux 和 Windows 的归档，覆盖 amd64 和 arm64 架构；每个归档都包含 katra 和 katra-mcp 这两个文件，以及 checksums.txt 和对应的签名。

在 macOS 或 Linux 上（bash/zsh）：

# Latest release, without the leading v. Set this by hand to pin a version.
VERSION=$(curl -fsSL https://api.github.com/repos/craigjmidwinter/katra/releases/latest \
  | sed -n 's/.*"tag_name": *"v\{0,1\}\([^"]*\)".*/\1/p')

OS=$(uname -s | tr '[:upper:]' '[:lower:]')     # darwin | linux
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/katra_${VERSION}_${OS}_${ARCH}.tar.gz"
tar xzf "katra_${VERSION}_${OS}_${ARCH}.tar.gz" katra katra-mcp
sudo install -m 0755 katra katra-mcp /usr/local/bin/

在 Windows 上（PowerShell），下载适用于机器架构的 zip 文件，并将两个 .exe 文件解压到 PATH 中的某个目录：

$release = Invoke-RestMethod https://api.github.com/repos/craigjmidwinter/katra/releases/latest
$version = $release.tag_name.TrimStart('v')
$arch = if ([Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() -eq 'Arm64') { 'arm64' } else { 'amd64' }
$archive = "katra_${version}_windows_${arch}.zip"

Invoke-WebRequest "https://github.com/craigjmidwinter/katra/releases/download/v${version}/${archive}" -OutFile $archive
Expand-Archive $archive -DestinationPath katra-bin

在 macOS 上，你自行下载的二进制文件会被 Gatekeeper 隔离。运行 xattr -d com.apple.quarantine /usr/local/bin/katra 将其解除隔离；也可以使用上面的 Homebrew 安装方式，它会自动处理。

验证下载的文件

curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/checksums.txt"

# Linux
sha256sum --check --ignore-missing checksums.txt
# macOS
shasum -a 256 --check --ignore-missing checksums.txt

在 Windows 上，Get-FileHash $archive -Algorithm SHA256 会输出归档文件的哈希值；在解压前，将其与 checksums.txt 中对应的一行进行比较。

然后验证 checksums.txt 上的签名。发布版本使用 cosign 进行无密钥签名——无需获取公钥，也无需有人保管私钥。签名证书颁发给发布工作流自身的 GitHub OIDC 身份，并记录在公开的 Rekor 透明日志中，因此你检查的是“这是由此仓库中的 release.yml 从某个标签构建的”：

curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/checksums.txt.sig"
curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/checksums.txt.pem"

cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  --certificate-identity-regexp '^https://github\.com/craigjmidwinter/katra/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

升级

重新运行上面的 go install ...@latest 命令会就地替换二进制文件——已验证：第二次运行会重新链接两者，与第一次相同。发布版本推出后，brew upgrade katra 会为 Homebrew 渠道执行同样的操作。

卸载

katra setup 会创建五项内容；每项都有各自的移除方式。

1. Git post-commit 钩子。 katra hook uninstall。
2. hub launchd Agent，如果你运行过 katra hub install。katra hub uninstall 会撤销安装——运行 launchctl unload 并删除 plist。
3. Claude Code 技能。 rm -rf .claude/skills/katra/（其中只有一个 文件：SKILL.md）。
4. .claude/settings.json 中的 hooks 块。 移除 SessionStart、 UserPromptSubmit、PostToolUse、Stop、PreCompact、SessionEnd 键下的 katra agent-hook 条目；如果你安装了提交门控，也要移除 PreToolUse 下的条目——然后删除其中任何已空的键。katra setup 只会在这些键下添加条目；其中的其他内容都属于你。
5. ~/.config/katra/registry.yml 中的注册表条目。 没有专门的注销命令，上述操作也都不会移除它——只要 katra/config.yml 存在，该条目就会保留。这通常正是你想要的，因为卸载自动化并不等于放弃日志。如果你删除了 katra/，下次 katra hub list 或 katra hub serve 读取注册表时，该条目就会自动清理——包括已在运行的 hub 守护进程。

上述操作都不会触及 katra/ 本身——katra/ 目录是你的数据，会原样保留。

快速入门

在 Git 仓库中操作，约需五分钟。

1. 设置时不将仓库绑定到某个编码框架。

   katra init --install-hook
   

   ✓ katra created at katra
     entries/   — one markdown file per post
     media/     — images, gifs, video, html embeds
     config.yml — title, accent, hook behaviour
     registered with the global katra registry (…)
   ✓ post-commit hook installed at .git/hooks/post-commit
   

   创建 katra/、欢迎草稿、可移植的 Git 自动打标钩子，以及 hub 注册项。Claude Code 用户可以再运行 katra setup --no-gate 添加会话提醒，或运行 katra setup 同时启用提醒和提交门控。

2. 添加内容到欢迎草稿，然后放入一张截图。

   katra append --entry hello-katra "The first reason this project needs a chronicle."
   

   ✓ appended to hello-katra
   

   可选；等你有内容可展示时，建议实际操作一次：在你的机器上截取任意图像（如果你没有截图，macOS 上可用 screencapture -x shot.png 截取）。

   katra capture ~/Desktop/swing.png --entry hello-katra --caption "first visible proof"   # swap in your own path
   

   ✓ imported media/swing.png
   ✓ added to hello-katra
   

3. 启动服务。

   katra serve
   

     local:   http://localhost:8080/
     network: http://192.168.1.23:8080/   (one line per LAN interface)
     watching katra — open tabs reload on change. Ctrl-C to stop.
   

   保持运行；随着你编写内容，打开的标签页会自动重新加载。

4. 照常提交。

   git commit -m "Reworked the swing arc"
   

   post-commit 钩子会用该提交的哈希和 diffstat 为草稿打标。没有钩子时：运行 katra stamp（HEAD），或运行 katra stamp --hash a1b2c3,d4e5f6，为包含多个提交的章节打标。

5. 确认已记录。

   katra list
   

   2026-08-20 16:06:54  Reworked the swing arc   [12acf46]  (+261 −0)
   

   一条带标记的记录，关联到你刚刚完成的提交——这是本快速入门以之收尾的、保证可见的成功结果。

要发布静态副本：

katra build --out ./site

一个自包含目录——包含 index.html、data.json 和媒体文件——不会发出外部请求。可托管在任意位置，也可直接从 U 盘打开。

富组件

组件是语言名称用于标识组件的围栏代码块。源内容保持 可读且便于比较差异；页面会显示对应的小部件。

```compare
before: media/bunker_before.png
after:  media/bunker_after.png
caption: Bunker reshape
```

```gallery
- src: media/a.png
  cap: tier one
- src: media/b.png
  cap: tier two
```

```video
src: media/horde.mp4
loop: true
```

```embed
src: media/frame-times.html
height: 480
caption: Frame time vs district count
```

```note
A callout. **Markdown** works inside it.
```

```warning
Same, with a warning style.
```

普通的 ![caption](media/x.png) 图片会自动获得灯箱效果。

未注册的语言会渲染为普通代码块。 这是该格式的 兼容性规则，并非回退机制：针对较新 katra 编写的条目在较旧版本中 仍可渲染，只是效果没那么美观。

我们特意不提供图表组件。你可以编写自包含的 HTML 图形并将其捕获 — katra capture 可识别 .html 并生成 embed 块 — 因此你可以使用任意图表，而非受限于一组固定类型。 examples/media/frame-times.html 是一个完整示例， examples/entry.md 则在单个条目中展示了所有组件（CI 会在每次推送时渲染它，因此内容不会过时）。

添加组件只需在 internal/core/render.go 中编写一个 ComponentFunc —— 这就是全部扩展接口。完整参考： docs/components.md。

磁盘布局

katra 写入的文件就是它的公共 API。 它们是你 代码库中的 Markdown 文件，无需使用该工具也能阅读，并且会长久留存。

katra/
  config.yml        title, accent, hook behaviour, memory settings
  entries/          one .md per post
  tasks/  epics/  decisions/  articles/
  media/            images, gifs, video, html embeds
  .state/           machine state — ledger, receipts (gitignored)

---
title: Reworked the swing arc
date: "2026-08-03"
tags: [physics, gameplay]
hash: 5ddc0f5          # or  hashes: [a, b]  for a chapter of commits
stat: {f: 12, a: 340, d: 50}
summary: tuned the magnus model      # optional, for the index
featured: true                       # optional → "Deep Dives" zone
cover: media/hero.png                # optional banner image
---

Markdown body. Write the *why*, not a paraphrased diff.

当且仅当一个目录包含 config.yml 时，它才是 katra。约定的 名称是 katra/；devlog/ 是重命名前使用的名称，仍会被发现，因此 旧代码库无需迁移也能继续使用。

使用方可以依赖以下兼容性规则：未知的 frontmatter 键会被 忽略，未知的围栏会降级为代码块，未指定 type 时默认为 entry。完整规范：docs/format.md。

命令

命令	功能
katra setup [--no-gate]	添加 Claude Code 技能/钩子，以及可移植的 Git 自动标记和 Hub 注册。可重复执行。
katra init [--title T] [--install-hook]	搭建与 Harness 无关的 Katra，可选择启用 Git 自动标记
katra new "Title" [--tags a,b] [--featured]	新建草稿条目
katra append [text] [--entry slug] [--file -]	向草稿追加 Markdown
katra capture <file> [--caption C]	将媒体导入当前草稿
katra compare <before> <after>	添加前后对比滑块
katra stamp [--hash H…] [--closes task]	使用提交和差异统计标记草稿
katra list [--drafts] [--json]	列出条目
katra serve [--port N]	在局域网上提供实时自动重载页面
katra build [--out dir] [--all]	构建静态网站
katra hook install | uninstall	管理自动标记 Git 钩子
katra doctor	查找失效媒体、解析错误、没有视觉内容的条目和过时的史诗
katra task | epic | decide | article	节点模型
katra task spec <slug> <ref>	将任务指向已提交的规格（todo/空 → specced）
katra reconcile …	声明当前工作的目标
katra memory scan | status	Claude Code 记忆摄取
katra hub serve | list | scan | install	管理所有已注册的 katra

完整参考：docs/cli.md。

Git 集成

katra stamp 会读取 git 来解析哈希并计算差异统计 （--numstat）。可选的提交后钩子可彻底消除“忘记标记” 这一问题：

katra hook install

每次提交后，它都会用该提交标记当前草稿，同时跳过自身的 簿记提交以及仅修改 katra 的提交。默认情况下，标记会作为工作树变更保留，供你提交；在 config.yml 中设置 autoCommit: true，可让钩子自行提交标记。

该钩子遵循 core.hooksPath。在 husky 下，它会安装到受 Git 跟踪的 .husky/post-commit，而不是 husky 每次 npm install 都会重写的生成目录 .husky/_/ — 并且其 shim 会在追加到其中的内容运行前退出。

中心面板

katra 是按仓库划分的，这适合记录日志，却不适合回答“我一直在做什么？”

katra hub serve          # http://localhost:4200 — every registered katra
katra hub install        # run it at login (macOS launchd)

一个项目索引、一个跨项目看板和路线图、一份合并后的时间顺序日志，以及每个项目在 /p/<id>/ 下各自的查看器。注册表位于 ~/.config/katra/registry.yml，读取时会顺带清理，因此你删除的项目会自动消失，无需额外清理。

katra build --all 会生成与静态目录相同的内容。没有托管服务、账号或同步功能。docs/hub.md；contrib/ 中有 launchd 代理和 systemd 单元。

贡献

欢迎提交 PR——CONTRIBUTING.md 介绍了环境配置、测试和 lint 命令，以及修改应遵循的不变量。RELEASING.md 介绍了实际发布流程，供准备发布的人参考。

状态与范围

尚未达到 1.0 版，由一个人编写，用于自己的项目。关于实际使用情况，与其说“经过实战检验”这种容易说出口、也容易核实的话，不如直接看具体数字：11 个仓库、237 条记录、持续使用四个多月。 使用并非每天都有，而是时多时少——有一个使用密集的月份（7 月的 31 天里有 24 天写了记录），此前则有三个使用稀疏的月份。

还没有其他人使用过它，所以你遇到的每个粗糙之处，很可能都还没人遇到过。

有两点支持它，一点不支持它，都可以核实：

• 磁盘上的格式是稳定部分。它采用 Markdown，并且严格遵循上述兼容性规则。
• 这个工具用来构建自身，因此此仓库中的 katra/ 是真实的输出样例，而不是演示内容。
• 事实证明，要在这么多仓库中持续保持配置有效，确实是个问题。 8 月的一次审查发现了 40 个未盖时间戳的草稿、三个从未写过记录的项目，以及 11 个项目中有 9 个的 Agent 钩子损坏或缺失。大多数问题都出在 katra 身上——钩子安装程序写入了 husky 会重新生成的目录，而中心面板在启动时会对注册表做快照——这两处问题现在都已修复。但实话实说，自动化在失败时的提示不够明显，值得运行 katra doctor。

命令名称和标志仍可能变动。

明确不在范围内

• 托管服务。 你的日志是仓库中的 Markdown。无需登录，也无需迁移离开；增加后端就会牺牲这些优点，换取便利。
• 通用容器安装。 katra 会操作你的工作树、Git 历史和钩子。将整个工具容器化意味着必须挂载这三者，到头来还不如本地安装。发布工作流确实会构建一个精简的 katra-mcp OCI 封装，仅供官方 MCP Registry 建立索引；它并非上述安装方式的替代方案。
• 主题系统。 查看器只有一种设计，accent 是唯一可调整的选项。如果必须自定义样式，你可以自行修改静态构建目录。
• 订阅源、评论和分析。 这是供仓库内成员使用的日志。
• 差异摘要。 katra 不会根据差异替你撰写记录。差异正是它无法告诉你的内容，而自动生成的记录恰恰会变成这款工具要避免的复述。

已知限制

• Hub 的 launchd 代理仅支持 macOS，作为一等安装方式。 contrib/systemd/ 支持 Linux，但没有适用于它的 katra hub install。

• katra serve 和 katra hub serve 会绑定所有网络接口，因此局域网中的头戴设备或手机都能访问它。没有身份验证。请勿在不信任的网络上运行。

• 更改 slug 会破坏指向该条目的 [[wikilinks]]。 文件路径就是身份标识；katra doctor 会报告因此产生的失效链接，但不会替你重写它们。

• 媒体文件会提交到仓库。 充满 gif 的日志，就是一个充满 gif 的仓库。Git LFS 可以使用，而 katra 对此一无所知，也不在意。

• stat 差异统计会计算整个提交，包括与该条目无关的文件；对于章节，则是跨提交的总和。它只能让你了解大致规模，并非精确统计。

• katra build 只会覆盖它生成的内容。 每次构建都会重写 index.html、app.js、styles.css 和 data.json；你在旁边添加的文件则会保留。这种组合正是陷阱所在。如果生成器会清空整个目录，你自然会小心使用；但它会保留你添加的文件，让人很容易合理地以为它也会保留你做的其他修改——然后丢弃那些必须写在生成文件内部的修改。

  因此，手动写入该页面的任何内容——分析代码片段、社交标签、网站图标链接——都会在下次构建时悄然消失，而页面仍然能完美呈现，只是它们原本提供的功能已经停止。请将此类插入内容放在构建之后运行的步骤中。通过检查全新构建加上你的步骤是否能重现已提交的文件来验证：页面看起来正常，只能证明它曾经生效，不能证明它现在仍然有效。

• 构建后的网站只有一个 URL，因此各条目没有独立 URL。 查看器通过片段（#/node/<slug>）进行路由，而浏览器不会将片段发送给服务器。发布 katra 到重要场合前，有两点后果值得了解：

  • 所有条目共用一张社交卡片。 指向任何条目的链接展开后显示的都是网站，而不是该条目，因为抓取工具没有可获取的条目专属 URL。给唯一存在的页面设置标签也无法改变这一点。
  • 分析数据按每次访问统计一次页面浏览，而不是按阅读的条目统计。 在条目之间切换只是片段变化，不会触发导航。读者读完 20 个条目只会计为一次页面浏览，因此，按条目统计的阅读量并非不准确，而是根本不存在。

  这是一项限制，而非两项；两部分都无法单独修复：它们都需要每个条目拥有一个 URL。向构建后的页面注入 head 标签无法解决任何一部分——它无法改变服务器从未路由到的卡片，也无法触发从未发生的导航。

  服务器可见的条目专属页面已列入计划；这些页面上线后，所有已发布的 #/node/<slug> 链接仍会继续有效。在此之前，katra 是一种可以发布并链接到的编年记录，而不是一种可以链接到、预览或统计其中各条目的编年记录。

文档

可通过 https://midwinter.io/katra/ 浏览，也可在此仓库中查看：

• docs/quickstart.md — 从安装到创建第一条盖章记录。
• docs/workflow.md — 完整的、与运行框架无关的从规范到盖章工作流。
• docs/components.md — 所有组件、各组件接受的确切键，以及图表和示意图的制作方法。
• docs/cli.md — 所有命令和标志。
• docs/configuration.md — 每个 config.yml 键、其默认值和对应的故障模式。
• docs/format.md — 磁盘上的格式约定。编写用于读取 katra 的工具前，请先阅读。
• docs/agents.md — CLI、十五个 MCP 工具，以及可选的 Claude 技能、钩子、提交门禁和记忆导入。
• docs/hub.md — 注册表和跨项目视图。
• docs/architecture.md — 各个接口，以及应将更改放在哪里。
• CONTRIBUTING.md — 构建、测试，以及代码库所遵循的约定。

可运行示例：examples/entry.md（一条记录包含所有组件，由 CI 渲染）、examples/config/（最简配置和带完整注释的配置），以及 examples/media/frame-times.html（自包含图表）。

致谢

字标采用 Fraunces 字体，由 Undercase Type（Phaedra Charles 和 Flavia Zimbardi）设计，依据 SIL Open Font License 1.1 使用。品牌素材、调色板及其测得的对比度均见 branding/BRAND.md。

许可证

MIT。详见 LICENSE。