# @phren/cli 中文文档

规范地址：https://npmcn.com/package/%40phren/cli/

版本：0\.3\.69
npm 元数据更新时间：2026-11-02T03:41:59.441Z
中文译文更新时间：2026-11-02T04:23:16.773Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：15.8 MB，997 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：9 个
- 首次发布：2026-03-14T04:09:23.174Z
- 最新版本发布：2026-11-02T03:41:58.977Z
- 已发布版本数：189（近 12 个月 189 个）

## 中文简介

AI代理的知识层- CLI， MCP服务器和数据层

## 安装

```sh
npm install @phren/cli
```

也可以使用：`pnpm add @phren/cli`、`yarn add @phren/cli`、`bun add @phren/cli`

## README

# phren MCP服务器

MCP服务器，索引你的个人电话，并通过全文搜索将其暴露给人工智能代理。

在启动时，它遍历你的phren目录，读取所有 `.md` 文件，并在内存中构建SQLite FTS5索引。

默认情况下，定期远程检查是关闭的。使他们能够 `phren config pull-interval 60` 在运行时每分钟检查一次共享的Git存储库，在使用相同存储库的MCP客户端之间进行协调。更改的refs仅作为干净的快进提取和应用；脏存储或发散存储被延迟。拉出的更改刷新索引和现有的托管技能/指令镜像。将此机器配置为 `phren config pull-interval 600` （十分钟）或者 `phren config pull-interval off`． 禁用项目本地存储和手动预设的定期检查；现有的生命周期钩子是单独配置的。

公共界面：78个MCP实现工具，跨越17个目录模块（搜索、任务、发现、笔记、内存、数据、图形、会话、操作/审查、技能、钩子、配置、提取）。

值得注意的已交付功能：

-   寻找生命周期工具： `supersede_finding`， `retract_finding`， `resolve_contradiction`， `get_contradictions`
-   找到出处: `add_finding.source` （`human|agent|hook|extract|consolidation|unknown`）
-   轻量级每日笔记：CRUD in `<project>/notes/YYYY-MM-DD.md`，显式搜索，无需自动提示注入即可提升发现
-   跨会话连续性：任务检查点+ `session_history`
-   从注入的上下文结果中寻找影响评分
-   技能注册表行为：范围优先，别名冲突处理，可见性门控，生成 `skill-manifest.json`
-   生命周期惩罚：取代0.25倍，撤回0.1倍，反驳0.4倍的检索置信度
-   从FTS索引中删除不活跃的发现（被取代/撤回的发现不能出现在检索中）
-   自动标记：没有类型标记的结果在写入时从内容中推断出来
-   会话上下文差异： `session_start` 报告上次会议以来的新发现
-   抗衰减性：确认的发现在重复使用时衰减速度降低3倍

## 安装

```bash
npx @phren/cli init
```

这设置了phren无需 `sudo` 或者全局安装。在Windows上，使用 `npm install -g @phren/cli` 如果 `npx` 不是可用的。

或者手动添加到Claude Code：

```bash
claude mcp add phren -- phren ~/.phren
```

## 环境变量

| 变量 | 默认的 | 描述 |
| --- | --- | --- |
| `PHREN_PATH` | `~/.phren` | phren实例的路径 |
| `PHREN_PROFILE` | _(没有)_ | 活动配置文件名称。未设置时，phren使用 `machines.yaml` 可用时，否则退回到无作用域视图 |
| `PHREN_PULL_INTERVAL_SECONDS` | `0` (关闭) | 覆盖机器本地拉取间隔。从30秒到86400秒，或者 `0`/`off` 关闭MCP周期性检查。 |
| `PHREN_ACTOR` | OS用户/ env | 治理/审计RBAC检查中使用的参与者标识 |

## 工具

看到 [文档/ api-reference.md](https://npmcn.com/package/%40phren/docs/api-reference.md) 获取完整的API参考。

## 集成模型

-   Claude：完整的本地生命周期钩子(`SessionStart`， `UserPromptSubmit`， `Stop`， `PostToolUse`) + MCP
-   Copilot CLI / Cursor / Codex: MCP +生成的钩子配置+会话包装器二进制文件

## 治理和安全重点

-   RBAC使用 `.config/access-control.json` 和 `.runtime/access-control.local.json`
-   Web UI只绑定环回，使用每次运行的验证令牌，对突变强制CSRF，并设置CSP标头
-   遥测技术仅供选择使用(`phren config telemetry on`)，并储存在本地 `.runtime/telemetry.json`

### search\_knowledge

全文搜索所有带同义词扩展的索引标记文件。

```
query: string              - FTS5 query (supports AND, OR, NOT, "phrase matching")
limit?: number             - Max results, 1-20, default 5
type?: string              - Filter: "claude", "findings", "reference", "summary", "task", "skill"
project?: string           - Filter to a specific project
tag?: string               - Filter findings by type tag: decision, pitfall, pattern, tradeoff, architecture, bug
since?: string             - Filter findings by date: "7d", "30d", "YYYY-MM", "YYYY-MM-DD"
status?: string            - Filter by lifecycle status: active, superseded, contradicted, stale, invalid_citation, retracted
include_history?: boolean  - Include superseded/retracted findings (default false)
synthesize?: boolean       - Generate a synthesis paragraph from top results using an LLM
```

### get\_project\_summary

返回项目的摘要。md内容，到其AGENTS的路径。Md，以及索引文件列表。

```
name: string      - Project name (e.g. "my-app", "backend")
```

### list\_projects

列出活动配置文件中的所有项目，并提供简要说明以及存在哪些文档。

没有参数。

## 它是如何工作的

1.  读取 `PHREN_PATH` (或默认为 `~/.phren`）
2.  解析来自的活动概要文件 `PHREN_PROFILE`，或from `machines.yaml` 当env变量未设置时
3.  如果还没有活动的概要文件可以解析，则退回到顶级项目目录的未限定范围视图
4.  遍历每个项目目录，读取 `.md` 文件，按文件名对它们进行分类
5.  用波特词干构建内存中的SQLite FTS5索引
6.  使用MCP协议通过工作室提供工具

文件类型由文件名和目录派生： `AGENTS.md` - - - - - - >“克劳德。” `summary.md` - - - - - - >“总结”, `FINDINGS.md` - - - - - - >“发现”, `tasks.md` ->“任务”，文件下 `notes/` ->“笔记”，文件下 `reference/` ->“引用”，文件下 `skills/` - - - - - - >“技巧”。

## 开发

```bash
cd ~/phren
npm install
npm run build    # Compile TypeScript
npm run dev      # Run with tsx (hot reload)
npm test         # Run all tests
```

## 常见问题

### @phren/cli 是什么？

AI代理的知识层- CLI， MCP服务器和数据层

### 如何安装 @phren/cli？

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

### @phren/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @phren/cli 支持 ESM 还是 CommonJS？

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

### @phren/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @phren/cli 可以商用吗？

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

### @phren/cli 还在维护吗？

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