# @cianfrani/devlog 中文文档

规范地址：https://npmcn.com/package/%40cianfrani/devlog/

版本：2\.2\.0
npm 元数据更新时间：2026-10-31T18:31:32.937Z
中文译文更新时间：2026-10-31T19:02:30.031Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cianfrani/devlog
原文对照：https://npmcn.com/package/%40cianfrani/devlog/?lang=original
项目主页：https://github.com/markacianfrani/devlog#readme
源码仓库：https://github.com/markacianfrani/devlog

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2026-04-30T12:13:09.520Z
- 最新版本发布：2026-10-31T18:31:32.584Z
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

存档AI助手对话（Claude Code, opencode, pi）

## 安装

```sh
npm install @cianfrani/devlog
```

也可以使用：`pnpm add @cianfrani/devlog`、`yarn add @cianfrani/devlog`、`bun add @cianfrani/devlog`

## README

# Devlog

Devlog将你所有的编码记录复制到第三方位置，这样你就可以在默认保留期删除它们后访问它们。

支持 **克劳德代码**， **Opencode**, **π**.

## 安装

```bash
npm install -g @cianfrani/devlog
devlog init
```

`devlog init` 询问在哪里存储存档文件(默认： `~/devlog`)以及为哪些代理配置MCP服务器。

## 命令

```bash
devlog                  # copy sessions, then index them for search
devlog archive          # only copy sessions to your archive
devlog index            # only index archived sessions into SQLite
devlog mcp              # start the MCP server (stdio)
devlog init             # first-time setup
```

每个阶段都跳过自上次运行以来没有改变的会话。使用 `archive` 或者 `index` 当你只需要一个阶段。

### 选项

```
--verbose    show per-project and per-session details
--debug      extra noisy diagnostics
--rebuild    with devlog or index, wipe the database and re-index everything
```

## MCP服务器

在运行 `devlog init`，您可以从编码代理内部搜索会话历史记录。

**工具:** `search`， `list_sessions`， `get_session`， `schema`， `query`

如果不想使用MCP，可以编写一个描述sqlite或会话存储位置的技能。

```
search past sessions for "auth middleware"
list sessions for project "quoting-ui"
get session <session_id>
```

原始SQL也可以工作：

```sql
SELECT project, COUNT(*) as n FROM sessions GROUP BY project ORDER BY n DESC
```

## 它是如何工作的

**存档** 读取每个代理的本地会话数据并将其写入 `~/devlog/` 作为规范化的json。Claude Code和pi将会话存储为文件，因此devlog直接复制这些文件。Opencode现在将会话存储在SQLite数据库中，因此devlog提取并转换它们。

**指数** 使用全文搜索（FTS5，波特词干）将存档的JSONL解析为SQLite数据库。在将内容写入SQLite之前，devlog会尽最大努力清理常见的凭据模式，并对敏感的环境变量值进行精确匹配 `OPENAI_API_KEY` 和 `GITHUB_TOKEN`． MCP服务器从该数据库读取数据。

### 适用修订的地方

修订运行 **只有** 写入SQLite索引的内容，这是编码代理通过MCP服务器查询的表面。已归档的json文件 `~/devlog/` 是 **复制byte-for-byte** 从源会话文件-他们永远不会重写或清除。这是故意的：

-   该存档是代理实际看到的内容的忠实备份。重写它将使它不可能对源进行修改或恢复原始上下文。
-   索引是可查询的表面。清除是为了防止秘密泄露到搜索结果或MCP响应中。

如果您需要归档文件本身保持干净，请将其清除到带外（例如，擦除会话文件），然后 `devlog index --rebuild`）. 洗涤器故意设置得很窄：它有助于避免不经意地暴露秘密，但事实确实如此 **不** 一个完整的个人信息/隐私杀菌剂。

### 会话消息

| 代理 | 来源 | 格式 |
| --- | --- | --- |
| 克劳德代码 | `~/.claude/projects/` | JSONL |
| opencode | `~/.local/share/opencode/opencode.db` | SQLite |
| π | `~/.pi/agent/sessions/` | JSONL |

### PI扩展记录

PI写入通用扩展记录(`custom` 和 `custom_message`)以及会话信息。Devlog只从它们的公共信封中对它们进行索引——它从不解释任何第三方扩展的私有有效负载模式。一个 `custom` 条目的 `data` 序列化为不透明的JSON在 `<pi:custom>` 块，因此嵌套的值保持可搜索，但会逐字显示，而不是重新格式化。原始归档的json文件永远不会通过索引重写；跨索引版本的升级会在下一次更新时重新构建本地SQLite缓存 `devlog index`，使先前被删除的扩展状态再次可搜索。

## 文件布局

遵循 [XDG基础目录](https://specifications.freedesktop.org/basedir-spec/latest/) 规范:

| 什么 | 路径 | XDG目录 |
| --- | --- | --- |
| 配置 | `~/.config/devlog/config.json` | `XDG_CONFIG_HOME` |
| 存档 | `~/devlog/` (可配置) | user-chosen |
| 索引数据库 | `~/.local/state/devlog/index.db` (可配置) | `XDG_STATE_HOME` |

从存档重新生成索引 `devlog index --rebuild`.

### 配置

`~/.config/devlog/config.json` (由 `devlog init`):

```json
{
  "archiveDir": "/Users/you/devlog",
  "dbPath": "/Users/you/devlog/index.db",
  "excludeProjects": ["fidelio", "scratch"]
}
```

| 关键 | 默认的 | 它是做什么的 |
| --- | --- | --- |
| `archiveDir` | `~/.config/devlog` | 原始json会话副本写入的地方。 |
| `dbPath` | `~/.local/state/devlog/index.db` | SQLite索引所在的位置。两个 `devlog index` 和 `devlog mcp` 读这个键。 |
| `excludeProjects` | `[]` | 模糊的、不区分大小写的子字符串匹配项目段/路径。不需要全段塞。 |

`excludeProjects` 例子:

-   `"fidelio"` 匹配 `-Users-you-src-tries-2026-02-17-fidelio`
-   `"scratch"` 匹配 `/Users/you/Code/scratchpad`

## 要求

-   [包子](https://bun.sh/) —CLI运行在Bun运行时。

## 贡献

从结帐处工作： `bun install && bun run build:cli`，然后调用 `./dist/cli.js` 直接。

## 常见问题

### @cianfrani/devlog 是什么？

存档AI助手对话（Claude Code, opencode, pi）

### 如何安装 @cianfrani/devlog？

在项目目录运行 npm install @cianfrani/devlog，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 devlog，可以用 npx devlog 直接运行。

### @cianfrani/devlog 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cianfrani\_\_devlog 是否存在。

### @cianfrani/devlog 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cianfrani/devlog 可以商用吗？

@cianfrani/devlog 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cianfrani/devlog 还在维护吗？

最新版本 2\.2\.0 发布于 2026/11/01（2 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/04/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。