# https://github.com/AlmanacCode/codealmanac 项目说明书

生成时间：2026-07-21 18:08:55 UTC

## 目录

- [概述、安装与日常读取命令](#page-overview)
- [系统架构、核心概念与生命周期操作](#page-architecture)
- [Provider 与 Harness 集成（含 OpenCode 支持议题）](#page-harness)
- [作业生命周期、launchd 自动化与本地状态](#page-jobs-automation)

<a id='page-overview'></a>

## 概述、安装与日常读取命令

### 相关页面

相关主题：[系统架构、核心概念与生命周期操作](#page-architecture), [作业生命周期、launchd 自动化与本地状态](#page-jobs-automation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/AlmanacCode/codealmanac/blob/main/README.md)
- [pyproject.toml](https://github.com/AlmanacCode/codealmanac/blob/main/pyproject.toml)
- [src/codealmanac/app.py](https://github.com/AlmanacCode/codealmanac/blob/main/src/codealmanac/app.py)
- [src/codealmanac/cli/main.py](https://github.com/AlmanacCode/codealmanac/blob/main/src/codealmanac/cli/main.py)
- [src/codealmanac/cli/dispatch/setup.py](https://github.com/AlmanacCode/codealmanac/blob/main/src/codealmanac/cli/dispatch/setup.py)
- [src/codealmanac/manual/getting-started.md](https://github.com/AlmanacCode/codealmanac/blob/main/src/codealmanac/manual/getting-started.md)
</details>

# 概述、安装与日常读取命令

## 1. 项目概述与适用场景

CodeAlmanac 是一个面向代码仓库的"年鉴式"知识管理工具，它把构建、索引、检索与日常读取整合在同一个 CLI 之下，目标是让开发者不必离开终端即可完成对仓库历史、符号与文档的查询。资料来源：[README.md:1-40]()

核心能力由 `app.py` 承载应用入口与生命周期调度；命令行界面则由 `cli/main.py` 统一分发，再交由 `cli/dispatch/` 下的子模块（例如 `setup.py`）处理具体动作。资料来源：[src/codealmanac/app.py:1-30]() 资料来源：[src/codealmanac/cli/main.py:1-25]()

| 模块 | 角色 | 关键动作 |
|------|------|----------|
| `app.py` | 应用上下文 | 初始化、加载配置、调度生命周期阶段 |
| `cli/main.py` | CLI 入口 | 解析参数、路由子命令 |
| `cli/dispatch/setup.py` | 子命令实现 | 安装、初始化本地缓存、注册读取器 |

当前版本 0.4.4 在 Yoke 之上挂接了 Codex 与 Claude 两个执行后端，社区正在讨论引入 OpenCode 作为一等公民客户端（详见 #41），并关注是否能与 Claude Mac App、Xcode、Android Studio 等编辑器协同（#40）。资料来源：[README.md:60-90]()

## 2. 安装与环境准备

### 2.1 通过 `pyproject.toml` 直接安装

项目使用 Python 打包元数据声明依赖与入口点。开发模式安装命令如下：

```bash
git clone https://github.com/AlmanacCode/codealmanac.git
cd codealmanac
pip install -e .
```

`pyproject.toml` 中定义了 `codealmanac` 控制台入口，指向 `cli/main.py` 中的 `main()` 函数，从而保证 `codealmanac <subcommand>` 在任意目录下都可调用。资料来源：[pyproject.toml:1-40]()

### 2.2 初次引导（`setup` 子命令）

首次使用需要执行初始化，将本地索引目录、Yoke 配置与默认 harness（默认 Codex 或 Claude）写入 `~/.codealmanac/`。资料来源：[src/codealmanac/cli/dispatch/setup.py:1-45]()

```bash
codealmanac setup --harness codex
codealmanac setup --harness claude
```

`setup` 子命令会：

1. 创建本地缓存与日志目录；
2. 校验所选 harness 的认证信息；
3. 写入默认的 `config.toml`，供后续 `ingest`、`garden`、`read` 等命令读取。资料来源：[src/codealmanac/cli/dispatch/setup.py:20-60]()

### 2.3 入门手册

`manual/getting-started.md` 提供了一步一步的演练流程，覆盖最小可运行示例与首个查询命令，建议新用户完整跟读。资料来源：[src/codealmanac/manual/getting-started.md:1-30]()

## 3. 日常读取命令

完成 `setup` 后，最常用的就是"读取"类子命令。它们不会修改仓库内容，只在索引之上做查询：

- `codealmanac read <path>`：读取指定文件或符号的注释化摘要。
- `codealmanac search <query>`：跨仓库执行模糊搜索，返回符号、提交与文档三路命中。
- `codealmanac timeline <symbol>`：展示符号的演变时间线，串联起提交与文档变更。
- `codealmanac explain <ref>`：调用当前 harness（Codex / Claude）生成解释段落。

这些命令由 `cli/main.py` 统一路由，并依赖 `app.py` 构建的应用上下文来读取已索引的数据。资料来源：[src/codealmanac/cli/main.py:30-80]() 资料来源：[src/codealmanac/app.py:40-90]()

下面以"读取 + 搜索"为例展示一个最小工作流：

```mermaid
flowchart LR
    A[setup] --> B[ingest]
    B --> C[index 落盘]
    C --> D[read / search]
    D --> E[harness 解释]
```

## 4. 兼容性、扩展与社区关注点

- **多编辑器协作**：社区在 #40 询问是否支持 Claude Mac App、Xcode 与 Android Studio；这些场景主要取决于 harness 客户端是否能输出结构化文本，并由 `app.py` 的解析层吸收。资料来源：[src/codealmanac/app.py:50-110]()
- **OpenCode 一等公民**：#9 与 #41 提议把 OpenCode 接入 CodeAlmanac 的执行链，让 `build / ingest / garden` 可在 OpenCode 的鉴权与模型路由下运行；接入点预期落在 `cli/dispatch/` 的 harness 注册表中。资料来源：[src/codealmanac/cli/dispatch/setup.py:30-70]()

若你日常主要使用 OpenCode，建议先关注 #41 的进展，并在跟踪版本时留意 `v0.4.4` 之后的 Changelog，以确认 harness 注册表是否扩展。资料来源：[README.md:100-130]()

---

<a id='page-architecture'></a>

## 系统架构、核心概念与生命周期操作

### 相关页面

相关主题：[概述、安装与日常读取命令](#page-overview), [Provider 与 Harness 集成（含 OpenCode 支持议题）](#page-harness), [作业生命周期、launchd 自动化与本地状态](#page-jobs-automation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [almanac/architecture/composition-root.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/composition-root.md)
- [almanac/architecture/service-boundaries.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/service-boundaries.md)
- [almanac/architecture/lifecycle/workflows.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/lifecycle/workflows.md)
- [almanac/architecture/lifecycle/operation-runner.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/lifecycle/operation-runner.md)
- [almanac/architecture/lifecycle/mutation-safety.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/lifecycle/mutation-safety.md)
- [almanac/architecture/lifecycle/run-queue-and-sync.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/lifecycle/run-queue-and-sync.md)
</details>

# 系统架构、核心概念与生命周期操作

## 概述与项目定位

CodeAlmanac 是一个面向代码仓库的结构化"年鉴"系统：通过对源码进行构建、摄取（ingest）与整理（garden）三类生命周期操作，把分散的代码事实汇聚成可查询、可演进的知识资产。当前版本为 **0.4.4**，所有生命周期任务均通过统一的可插拔"harness 客户端"调度，目前内置支持 Codex 与 Claude（经由 Yoke 中间层）。社区中关于"将 OpenCode 作为一等 harness 客户端"的诉求（[#41](https://github.com/AlmanacCode/codealmanac/issues/41)、[#9](https://github.com/AlmanacCode/codealmanac/issues/9)）正是围绕这一调度层展开。

资料来源：[almanac/architecture/composition-root.md:1-40]()

## 核心组成与服务边界

系统的入口由 composition root 装配，它在启动期把配置、harness、存储与生命周期队列注入到运行容器中。服务边界文档明确了各模块的职责切割：

- **Harness 抽象层**：封装外部编码代理（Codex/Claude）的调用协议，对外暴露统一的 `run` 接口；
- **生命周期引擎**：负责把 `build`、`ingest`、`garden` 三类操作分解为可执行步骤；
- **持久化层**：保存运行队列、运行结果与变更快照；
- **同步网关**：将本地队列与外部触发源（如 Git 事件）同步。

资料来源：[almanac/architecture/service-boundaries.md:1-60]()、[almanac/architecture/composition-root.md:41-90]()

## 生命周期工作流

三类生命周期操作共享同一调度骨架，但语义不同：

| 操作 | 目标 | 典型产物 |
|------|------|----------|
| `build` | 解析仓库结构、生成索引骨架 | 索引清单、构件图 |
| `ingest` | 摄取代码事实与文档片段 | 事实条目、引用图谱 |
| `garden` | 整理、修剪与版本对齐 | 修订建议、归档产物 |

工作流文档规定每个操作必须经过 **入队 → 预检 → 调度 → 执行 → 落盘** 五阶段，并由 mutation-safety 策略确保任意阶段失败都不会污染既有数据。

资料来源：[almanac/architecture/lifecycle/workflows.md:1-80]()、[almanac/architecture/lifecycle/mutation-safety.md:1-50]()

## 操作运行器与队列同步

`operation-runner` 是执行节点的核心：它从运行队列中取任务，调用对应 harness 客户端完成动作，再把结构化结果回写。`run-queue-and-sync` 描述了队列的本地持久化、租约续期、以及与外部事件源的回压同步机制，保证在 harness 不可用或网络抖动时任务不会丢失。

```mermaid
flowchart LR
    A[触发源] --> B[Run Queue]
    B --> C[Operation Runner]
    C --> D{Harness 客户端}
    D -->|Codex| E[Yoke]
    D -->|Claude| E
    D -.未来.-> F[OpenCode]
    C --> G[落盘与快照]
    G --> H[知识库]
```

资料来源：[almanac/architecture/lifecycle/operation-runner.md:1-70]()、[almanac/architecture/lifecycle/run-queue-and-sync.md:1-90]()

## 变更安全与扩展点

mutation-safety 文档为所有写操作引入"先快照、再执行、再校验"的三段式约束，失败时按队列条目回滚而非整库回滚。harness 抽象层预留了 `register(client)` 扩展点，这正是社区希望引入 **OpenCode** 作为一等客户端的接入位置（参见 #41）。同样的扩展机制也允许接入 Claude Mac、Xcode、Android Studio 等本地代理（社区 #40 中提出的兼容问题）。

资料来源：[almanac/architecture/lifecycle/mutation-safety.md:51-110]()、[almanac/architecture/composition-root.md:91-130]()

---

<a id='page-harness'></a>

## Provider 与 Harness 集成（含 OpenCode 支持议题）

### 相关页面

相关主题：[系统架构、核心概念与生命周期操作](#page-architecture), [作业生命周期、launchd 自动化与本地状态](#page-jobs-automation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [almanac/architecture/agent-runs/harness-contract.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/agent-runs/harness-contract.md)
- [almanac/architecture/agent-runs/provider-adapters.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/agent-runs/provider-adapters.md)
- [almanac/reference/harness-event-shape.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/reference/harness-event-shape.md)
- [almanac/guides/add-a-harness-provider-adapter.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/guides/add-a-harness-provider-adapter.md)
- [src/codealmanac/integrations/harnesses/yoke/adapter.py](https://github.com/AlmanacCode/codealmanac/blob/main/src/codealmanac/integrations/harnesses/yoke/adapter.py)
- [src/codealmanac/services/harnesses/service.py](https://github.com/AlmanacCode/codealmanac/blob/main/src/codealmanac/services/harnesses/service.py)
</details>

# Provider 与 Harness 集成（含 OpenCode 支持议题）

本页说明 CodeAlmanac 如何通过**契约（Contract）+ 适配器（Adapter）** 的方式把外部 AI 编程代理（如 Codex、Claude、OpenCode）接入生命周期操作（build / ingest / garden），并解释为何社区提出的 OpenCode 一等公民支持是一个独立的工程议题。

## 1. 集成目标与作用域

CodeAlmanac 的生命周期操作需要由一个外部“代理执行体”来驱动：构造代码库快照（build）、摄取内容（ingest）、整理知识库（garden）。该执行体在项目中被统称为 **Harness**。CodeAlmanac 不绑定到某一个 CLI，而是定义一套统一的调用契约，再为不同工具（Codex、Claude Code、未来的 OpenCode）编写 Provider Adapter。

- 契约定义在 `almanac/architecture/agent-runs/harness-contract.md` 中，是所有适配器必须遵守的输入、输出、事件协议。
- 服务层入口位于 `src/codealmanac/services/harnesses/service.py`，负责把上层任务请求分派到对应 Provider。
- 适配器层目前主要由 `src/codealmanac/integrations/harnesses/yoke/adapter.py` 实现，统一封装 Codex 与 Claude Code。

资料来源：[almanac/architecture/agent-runs/harness-contract.md:1-40]()，[src/codealmanac/services/harnesses/service.py:1-60]()

## 2. 架构分层：Contract → Adapter → Provider

集成被分为三层，确保新增 Provider 时只改动 Adapter，不影响业务调用方。

| 层 | 文件 | 职责 |
|---|---|---|
| 契约层 | `harness-contract.md` | 描述请求 schema、事件流、终止条件 |
| 服务层 | `services/harnesses/service.py` | 解析任务、选择 Provider、汇聚事件 |
| 适配器层 | `integrations/harnesses/*/adapter.py` | 将契约翻译为具体 CLI 调用 |

`almanac/architecture/agent-runs/provider-adapters.md` 进一步说明：每个 Provider 必须实现 `start / send_event / cancel / collect_artifacts` 等最小接口，并把外部 CLI 的原始流式输出规范化为 [harness-event-shape.md](almanac/reference/harness-event-shape.md) 中定义的标准事件（如 `run.started`、`message.delta`、`run.finished`）。

```mermaid
flowchart LR
    A[Lifecycle Job] --> B[HarnessService]
    B --> C{Provider Router}
    C -->|codex| D[Yoke Adapter]
    C -->|claude| D
    C -.->|opencode(规划中)| E[OpenCode Adapter]
    D --> F[Standard Event Stream]
    E --> F
    F --> G[Job Result Store]
```

资料来源：[almanac/architecture/agent-runs/provider-adapters.md:1-80]()，[almanac/reference/harness-event-shape.md:1-50]()

## 3. 事件契约与 Yoke 适配器实现要点

事件契约是 Provider 之间互操作的核心。`harness-event-shape.md` 规定所有 Harness 必须产出**确定字段**的事件 JSON：`run_id`、`seq`、`type`、`payload`、`timestamp`，并保证 `seq` 单调递增，以便上层做重放与断点续传。

Yoke 适配器（`src/codealmanac/integrations/harnesses/yoke/adapter.py`）当前承担 Codex 与 Claude Code 两类 Provider 的转换工作：

1. 在 `start()` 中根据 `provider_kind` 选择具体 CLI 参数模板（Codex 使用 `--prompt-file`，Claude Code 使用 `-p`）。
2. 通过子进程管道读取 stdout，逐行解析为 Yoke 内部事件，再映射到 CodeAlmanac 标准事件。
3. 在 `collect_artifacts()` 中根据 `run.finished` 携带的 `artifacts_ref` 下载 diff、log 与 transcript。

由于 Yoke 把两个 Provider 收敛到一个文件，新增 Provider 时可以参考 `almanac/guides/add-a-harness-provider-adapter.md` 中的步骤独立编写 Adapter，避免改动 Yoke 主路径。

资料来源：[src/codealmanac/integrations/harnesses/yoke/adapter.py:1-120]()，[almanac/reference/harness-event-shape.md:20-90]()，[almanac/guides/add-a-harness-provider-adapter.md:1-60]()

## 4. OpenCode 支持议题（社区诉求）

社区 Issue #9 与 #41 明确请求把 **OpenCode** 作为一等公民 Harness 接入：

- Issue #9（9 条评论）指出 OpenCode（<https://opencode.ai/>）已是流行的开源编程代理，应当被支持。
- Issue #41 进一步指出：现有用户已在 OpenCode 中维护自己的安装、鉴权与模型路由，却无法将其作为 CodeAlmanac 生命周期任务的后端执行体。

从架构上看，这正契合“Contract + Adapter”模式的设计目标：只需新增一个 `integrations/harnesses/opencode/adapter.py`，在 `services/harnesses/service.py` 的 Provider Router 中注册 `opencode` 分支，即可复用事件契约和上层业务。Issue #40 询问的 “Claude Mac app / Xcode / Android Studio” 本质上也属于同一类 Provider 适配议题，应通过新增 Adapter、而非修改 Contract 来解决。

资料来源：[issue #9 Support OpenCode]()，[issue #41 Add OpenCode as a first-class CodeAlmanac harness client]()，[issue #40 Does it work with Claude Mac app, Xcode and android studio?]()

## 5. 小结

- CodeAlmanac 通过 `harness-contract.md` + `provider-adapters.md` 的分层设计，把 Provider 实现细节隔离在 Adapter 层。
- `harness-event-shape.md` 提供的统一事件格式，是多 Provider 互操作和未来扩展的基础。
- Yoke 适配器只是当前实现，新增 OpenCode（或 Claude Mac app、Xcode、Android Studio 等）时应遵循 `add-a-harness-provider-adapter.md` 的指南独立编写 Adapter，避免在契约层引入 Provider 特定逻辑。

---

<a id='page-jobs-automation'></a>

## 作业生命周期、launchd 自动化与本地状态

### 相关页面

相关主题：[概述、安装与日常读取命令](#page-overview), [系统架构、核心概念与生命周期操作](#page-architecture), [Provider 与 Harness 集成（含 OpenCode 支持议题）](#page-harness)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [almanac/reference/local-state-layout.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/reference/local-state-layout.md)
- [almanac/reference/runs/run-states-and-events.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/reference/runs/run-states-and-events.md)
- [almanac/reference/config-keys.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/reference/config-keys.md)
- [almanac/architecture/telemetry.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/telemetry.md)
- [almanac/architecture/setup/automation-and-update.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/setup/automation-and-update.md)
- [almanac/architecture/repositories/local-state.md](https://github.com/AlmanacCode/codealmanac/blob/main/almanac/architecture/repositories/local-state.md)
</details>

# 作业生命周期、launchd 自动化与本地状态

## 概述

CodeAlmanac 把每一次 `build` / `ingest` / `garden` 编排视为一次"作业（run）"，并将作业的元数据、状态转换、日志和产物全部落地到本地状态目录中。运行时由 Codex 与 Claude 这两类 harness（通过 Yoke 中转）负责实际的模型调用与命令执行，而 macOS 上的 launchd 则承担后台拉起、定期巡检以及自我更新的职责。资料来源：[almanac/architecture/repositories/local-state.md:1-60]()、资料来源：[almanac/architecture/setup/automation-and-update.md:1-40]()

整个体系可以拆成三个相互耦合的子系统：

- **作业生命周期**：定义一次 run 从排队、运行到归档的全部状态。
- **launchd 自动化**：负责常驻守护、定时触发与升级。
- **本地状态存储**：所有上述行为落盘的目录与文件结构。

## 作业生命周期与状态事件

一次作业的状态机由 `runs/` 子目录中的状态文件驱动，最小状态集合为 `queued` → `running` → `succeeded | failed | cancelled`，外加一个用于归档的 `archived` 终态。状态之间的迁移由 harness 回调写入对应事件文件（`event.json`），并由本地仓储层原子地重命名 `state.json` 以保证并发安全。资料来源：[almanac/reference/runs/run-states-and-events.md:1-80]()

| 阶段 | 触发者 | 关键产物 |
| --- | --- | --- |
| `queued` | CLI / launchd 计划任务 | `runs/<id>/state.json`、`events/queued.json` |
| `running` | harness | `events/started.json`、实时日志流 |
| 终态 | harness / 守护进程 | `events/{succeeded,failed,cancelled}.json`、最终 `result.json` |
| `archived` | 回收任务 | 压缩包移入 `archive/` 子树 |

事件流同时会被遥测层采样，用于在 CLI 与未来的 Web UI 中呈现进度。资料来源：[almanac/architecture/telemetry.md:1-50]()

## launchd 自动化与后台更新

在 macOS 上，CodeAlmanac 通过 `~/Library/LaunchAgents` 下的 `com.codealmanac.agent.plist` 注册两类作业：

1. **守护保活（KeepAlive）**：若 `codealmanac daemon` 异常退出，launchd 会重新拉起它，负责监视正在 `running` 的 run。
2. **定时调度（StartCalendarInterval）**：周期性地执行 `codealmanac garden` 以整理陈旧 run、并触发 `codealmanac update --self` 完成版本自更新。

```mermaid
flowchart LR
  A[launchd] -- StartCalendarInterval --> B[codealmanac garden]
  A -- KeepAlive --> C[codealmanac daemon]
  C -- 事件回调 --> D[runs/<id>/state.json]
  B -- 清理 --> E[archive/]
  F[codealmanac update --self] -- 新版本 --> A
```

Linux / 无 launchd 环境下，README 建议改用 systemd `--user` 单元或 `cron` 等价配置；行为语义保持一致。资料来源：[almanac/architecture/setup/automation-and-update.md:40-120]()

## 本地状态布局与配置键

默认根目录遵循 XDG 风格：`$XDG_STATE_HOME/codealmanac`（macOS 下回退到 `~/.local/state/codealmanac`）。其下关键子树如下：

- `runs/`：每个 run 一个目录，包含 `state.json`、`events/`、`logs/`、`result.json`。
- `repos/`：克隆下来的本地代码仓库与索引缓存。
- `archive/`：已归档 run 的压缩包，便于跨机器搬运。
- `logs/daemon.log`：守护进程与 launchd 触发的合并日志。

资料来源：[almanac/reference/local-state-layout.md:1-90]()

常用配置键位于 `config.toml`，与生命周期直接相关的包括：

- `state_root`：覆盖默认本地状态路径。
- `keep_runs`：保留多少个最近 run 在非归档区。
- `harness`：默认 `codex` / `claude` 之一，决定 launchd 触发时调用哪个后端。
- `self_update_channel`：与 launchd 定时任务联动，控制是否在每次 garden 时拉取新版本。

资料来源：[almanac/reference/config-keys.md:1-70]()

## 与社区关注的关联

当前 Codex 与 Claude 之外，OpenCode 作为新兴开源编码代理被频繁请求作为一等公民接入（参见 issue #9 与 #41）。由于生命周期和本地状态均以 harness 无关的方式建模，新增 OpenCode 后端只需实现与现有 harness 相同的 `queued → running → 终态` 契约，并在 `config.toml` 的 `harness` 枚举中追加即可，无需改动 launchd 与状态目录布局。资料来源：[almanac/architecture/repositories/local-state.md:60-110]()

> 简而言之：作业是状态文件，launchd 是驱动器，本地状态目录是唯一真相来源；三者解耦使得后续接入新的 harness（包括 OpenCode）几乎只是注册一个新实现。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：almanaccode/codealmanac

摘要：发现 16 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows support (Currently errors with No module named 'termios').。

## 1. 安装坑 · 来源证据：Windows support (Currently errors with No module named 'termios').

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows support (Currently errors with No module named 'termios').
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/24 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：bug: docs/concepts.md lists build as a public command but codealmanac build is rejected

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: docs/concepts.md lists build as a public command but codealmanac build is rejected
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/35 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安全/权限坑 · 来源证据：Not Detecting Codex CLI

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Not Detecting Codex CLI
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：bug: dev dependency httpx2 is unused - looks like a typo for httpx

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: dev dependency httpx2 is unused - looks like a typo for httpx
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/33 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：bug: setup --yes crashes on Linux because scheduled automation is macOS/launchd-only

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: setup --yes crashes on Linux because scheduled automation is macOS/launchd-only
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/31 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：bug: two updates can run at the same time and corrupt things

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: two updates can run at the same time and corrupt things
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/26 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://news.ycombinator.com/item?id=48995181 | host_targets=claude_code, claude

## 8. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48995181 | README/documentation is current enough for a first validation pass.

## 9. 运行坑 · 来源证据：bug: getting error launchctl bootout failed

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: getting error launchctl bootout failed
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/30 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48995181 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48995181 | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48995181 | no_demo; severity=medium

## 13. 安全/权限坑 · 来源证据：Add OpenCode as a first-class CodeAlmanac harness client

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add OpenCode as a first-class CodeAlmanac harness client
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/41 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 安全/权限坑 · 来源证据：bug: worker spawn OSError crashes CLI with raw traceback after run is durably committed to the queue

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: worker spawn OSError crashes CLI with raw traceback after run is durably committed to the queue
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/AlmanacCode/codealmanac/issues/38 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 15. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48995181 | issue_or_pr_quality=unknown

## 16. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48995181 | release_recency=unknown

<!-- canonical_name: almanaccode/codealmanac; human_manual_source: deepwiki_human_wiki -->