AlmanacCode/codealmanac 来源：https://github.com/AlmanacCode/codealmanac

CodeAlmanac

你的代码库的活百科，由 AI 编程智能体维护。

CodeAlmanac 为 AI 智能体提供纯代码无法承载的上下文：系统为何如此设计、之前出过什么问题、哪些不变量至关重要、工作流如何跨越文件和服务的边界。

百科以纯 Markdown 形式存放在仓库中，本地索引，并像其他代码变更一样通过 Git 审查。

当前支持： macOS + Codex 或 Claude Code。需要 Python 3.12+。

快速开始

uv tool install codealmanac@latest
codealmanac setup

配置选项见设置。CodeAlmanac 设置完成后：

cd your-repo
codealmanac init                # 创建百科（如果没有）
codealmanac search "getting started"  # 显示匹配的百科页面
codealmanac show getting-started       # 在终端中打开一个页面
codealmanac serve                # 在本地网页浏览器中查看百科

设置

为你使用的本地工具安装全局智能体指令：

# 交互式设置
codealmanac setup

# 快速安装，使用推荐默认值；使用 Codex 作为 AI 运行器
codealmanac setup --yes

# 快速安装，使用 Claude 作为 AI 运行器
codealmanac setup --yes --runner claude

设置过程会为所选工具安装智能体指令，以及三个本地 macOS launchd 任务。这些任务和所有百科工作都在本地运行。

这些计划在后台本地运行。使用 codealmanac automation status 查看已安装的任务。

最后一步设置会询问是否允许匿名遥测，建议选择“是”，以便我们了解哪些命令正常工作以及 CLI 在何处崩溃。它会在随机安装 UUID 下发送受控的命令及生命周期结果，以及经过清理的未处理崩溃信息。它从不发送代码、路径、参数、查询、提示、转录、仓库/运行 ID、本地变量或凭据；GeoIP 处于禁用状态。可以在设置中选择“否”，传递 setup --no-telemetry，将 telemetry.enabled 设置为 false，或随时使用 DO_NOT_TRACK=1。如果没有未来登录，UUID 配置文件中不含姓名或电子邮件。

如果你没有 Codex 或更喜欢 Claude，请使用 --runner claude。--target 仅选择要安装哪个全局智能体指令文件，而不选择 AI 运行器：

codealmanac setup --yes --target codex
codealmanac setup --yes --target claude

在设置期间自定义自动工作：

# 更改自动扫描最近 AI 对话的频率
codealmanac setup --yes --sync-every 5h

# 不安装自动转录同步
codealmanac setup --yes --sync-off

# 不安装自动百科清理
codealmanac setup --yes --garden-off

# 不安装自动 CodeAlmanac 更新
codealmanac setup --yes --no-auto-update

若要卸载 CodeAlmanac 拥有的本地工件：

codealmanac uninstall --yes

日常读取

AI 智能体和人类使用相同的本地读取命令：

codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
codealmanac validate

使用 --wiki <路径> 读取另一个注册的本地百科。默认情况下，命令针对当前目录（当它是注册仓库根目录时）进行精确操作。

更新

百科生命周期命令通过公开的 Yoke SDK（https://github.com/AlmanacCode/Yoke）运行三种明确的智能体之一：构建（build）、引入（ingest） 或 整理（garden）。现有的打包提示文件包含完整的任务指令，并引导智能体编辑 almanac/ 下的百科。

生命周期智能体是受信任的本地编码智能体。它们具有 CodeAlmanac 历来提供的同样广泛且非交互的文件系统权限，因此 almanac/ 边界是一个指令和提交策略，而非操作系统沙箱。仅在你接受该信任模型的仓库中运行生命周期命令，并在禁用自动提交时检查生成的 Git 差异。

codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude
codealmanac garden --using codex

ingest 将选定的本地材料整合到百科中。输入可以包括文件、目录、Git 差异、提交范围、GitHub PR 或 issue、URL 以及本地智能体转录。garden 改进现有的百科图谱：过时页面、链接、主题、薄弱引线、重复页面和无依据的断言。无操作也是有效的。如果材料没有增加持久的百科知识，运行框架应保持百科不变。

init、ingest 和 garden 会创建排队的运行并启动本地工作线程。若要直观地跟踪它们，可运行 codealmanac serve 并在侧边栏中选择任务 (Jobs)。若要在终端中查看，请使用 codealmanac jobs attach <id>。

同步与自动化

CodeAlmanac 可以使注册的百科保持最新，无需你记住维护命令。

同步 (Sync) 扫描本地 Codex 和 Claude 转录存储，查找自上次成功同步以来活跃的对话。与注册仓库关联的对话将作为普通引入任务排入队列。同步可能认为某次对话不包含持久的知识，从而保持百科不变。

整理 (Garden) 定期为每个注册的百科排队一个维护任务。它会改进过时的页面、薄弱的链接、主题、重复的知识和图谱结构。

更新 (Update) 保持本地安装的 CodeAlmanac CLI 为最新。当更新不安全时会跳过计划更新，例如生命周期工作正在进行时。

自动化通过本地 macOS launchd 任务实现，而非托管服务或云同步。日志存储在 ~/.codealmanac/logs/ 下。

# 查看已安装的计划
codealmanac automation status

# 更改计划
codealmanac config set automation.sync.every 5h
codealmanac config set automation.garden.every 24h
codealmanac config set automation.update.every 24h

# 禁用或重新启用计划
codealmanac config set automation.sync.enabled false
codealmanac config set automation.sync.enabled true

config set 会更新用户的 TOML 并使 launchd 立即匹配。如果你直接编辑了 TOML，之后需要运行 codealmanac config apply。

自动化会产生单独的后台运行。可以使用 codealmanac jobs 单独检查这些运行。

任务 (Jobs)

生命周期运行记录在 ~/.codealmanac/ 下。使用以下命令检查和管控它们：

# 列出最近的任务及其 ID、类型、状态和已用时间
codealmanac jobs

# 显示一个任务的状态、摘要、页面更改、时间戳和错误详情
codealmanac jobs show <id>

# 打印到目前为止记录的事件，包括进度、工具活动和错误
codealmanac jobs logs <id>

# 实时跟踪新事件，直到任务完成、失败或标记为已取消
codealmanac jobs attach <id>

# 阻止排队的任务启动，或停止正在运行的任务及其智能体
codealmanac jobs cancel <id>

show 是任务的摘要；logs 是其事件历史的快照；attach 持续观察并在事件到达时打印它们。所有这些命令都读取相同的持久本地任务记录，因此在启动任务的终端关闭后它们仍能正常工作。在从脚本中消费其输出时添加 --json。

运行器 (Providers)

CodeAlmanac 使用 almanac-yoke 作为单一运行器边界。Codex 通过 app-server 运行；Claude 使用 Yoke 的默认 Claude 表面（目前基于 Python Agent SDK）。会重用现有的 Codex 或 Claude Code OAuth 会话，API 凭据可以通过 Yoke 在嵌入 SDK 时提供。

构建、引入和整理被打包为 Yoke 智能体集合，位于 src/codealmanac/agents/ 下。每个智能体使用 Yoke 的原生文件夹约定：agent.yaml 描述工具和权限，而 instructions.md 包含持久的智能体指令。一次生命周期运行仅将其类型化的运行时上下文作为任务提示传递。可选地，当产品需要时，可以向智能体添加 Yoke 的 skills/、subagents/ 和 workflows/ 文件夹；原生 Claude 或 Codex 执行仍然决定如何使用它们。

codex login
claude auth login
codealmanac doctor

读取命令不需要运行器凭据。需要写入能力的生命周期命令需要选定的运行框架可用且已验证。

Init 创建的内容

使用默认根目录时：

your-repo/
├── almanac/
│   ├── README.md
│   ├── topics.yaml
│   ├── architecture/
│   │   ├── README.md
│   │   └── indexer.md
│   ├── decisions/
│   │   └── local-first.md
│   └── guides/
│       └── setup.md
├── src/
└── ...

Markdown 页面直接位于 almanac/ 下有意义的文件夹中。topics.yaml 跨文件夹组织页面。README.md 文件作为其文件夹路由的着陆页。

对于自动检测，当仓库中存在 almanac/topics.yaml 和 almanac/README.md 时，该仓库被视为 CodeAlmanac 百科。

运行时状态

派生的本地状态位于 ~/.codealmanac/ 下：

~/.codealmanac/codealmanac.db
~/.codealmanac/repos/<hash>/index.db

本地数据库记录仓库、运行、运行事件、工作线程锁和同步状态。每个仓库的运行时文件包含派生的索引。它们不属于已提交的 almanac/ 树。

配置

用户配置文件位于：

~/.codealmanac/config.toml

支持的默认值为：

auto_commit = true

[harness]
default = "codex"
model = "gpt-5.5"

[automation.sync]
enabled = true
every = "5h"

[automation.garden]
enabled = true
every = "24h"

[automation.update]
enabled = true
every = "24h"

CLI 标志仍然优先于配置。对于常规更改，使用 codealmanac config set <key> <value>。它会立即将自动化更改应用到 launchd。直接文件编辑也支持，但之后必须执行：

codealmanac config apply

auto_commit 意味着生命周期提示可能会告知选定的智能体使用常规 Git 命令进行百科源更改。CodeAlmanac 不会在内部暂存文件、拆分差异或提交。

codealmanac setup --no-auto-commit
codealmanac config set auto_commit false
codealmanac config set auto_commit true

本地查看器

codealmanac serve

查看器是只读的。它根据本地百科数据渲染页面、搜索、主题、反向链接和文件引用导航。serve 在服务器就绪后会在默认浏览器中打开它；对于无头或脚本化使用，请使用 codealmanac serve --no-open。默认情况下，查看器可以在可用的已注册本地百科之间切换。使用 codealmanac serve --wiki <路径> 将其限制为一个百科。

从 npm CLI 迁移

旧版 codealmanac npm 包已退役。PyPI 是唯一支持的发行方式。如果你曾使用过 npm CLI，你的机器上可能仍然保留着旧版全局安装以及它设置的回调和智能体指令。在从 PyPI 安装之前，请移除这些。

移除旧版全局包以及它安装的任何 CodeAlmanac 回调或智能体指令部分，然后安装并设置 Python CLI：

npm uninstall -g codealmanac
uv tool install codealmanac@latest
codealmanac setup --yes
codealmanac doctor

同时移除旧的 bun、pnpm 或 yarn 安装以及 PATH 中任何残留的旧版二进制文件。保留仓库本地的 almanac/ 树不变；它们是已提交的百科内容，不属于 CLI 安装的一部分。

故障排除

harness codex failed with status failed: Error: spawn ... codex ENOENT

此机器上的 Codex CLI 损坏或缺失：@openai/codex 包已安装，但其原生二进制文件已丢失（通常是由于安装中断或在 nvm/volta/fnm 下切换 Node 版本导致）。使用以下命令验证：

codex --version

如果同样出现 spawn ... ENOENT 错误，请重新安装 Codex CLI：

npm install -g @openai/codex
codex --version        # 确认二进制文件可运行
codex login status     # 确认你仍处于登录状态

重新安装不会使你退出登录：codex 将其登录信息保存在 ~/.codex 中，位于 npm 包之外。

或者将 CodeAlmanac 切换到 Claude 运行器：

codealmanac config set harness.default claude

harness claude failed 错误同理：检查 claude --version，如果损坏则重新安装 Claude Code CLI，或切换默认运行器。codealmanac doctor 会报告运行器的可用性。

当前约定

本次重写目前仅限本地。

• 公开命令：codealmanac
• 短别名：ca
• 仓库百科根目录：仅 almanac/
• 替代仓库百科根目录：无
• 用户状态根目录：~/.codealmanac/
• 运行时：Python 3.12+
• 存储：本地 Markdown 加上 ~/.codealmanac/ 下的派生状态
• 无托管登录/连接/上传命令
• 无公开 SDK 或 MCP 包
• 不支持旧版兼容别名，除已支持的 ca 简写外
• 无其他百科根目录
• 可选的匿名使用和经过清理的崩溃遥测；可通过 codealmanac config set telemetry.enabled false 或设置时的 --no-telemetry 禁用
• 无百科、源代码、提示、转录、路径或命令参数的上传路径
• 无第二个规范的官方产品名称

这是 Python/PyPI 产品的表面。托管集成可以稍后围绕同一个仓库拥有的百科工件添加，但它不属于此发布表面的一部分。