# https://github.com/zbs-gg/pulse 项目说明书

生成时间：2026-07-05 12:29:00 UTC

## 目录

- [Pulse 项目概览与整体架构](#page-1)
- [状态感知胶囊检索与连续性包](#page-2)
- [存储层、Schema 演进与 Material Graph](#page-3)
- [安装路径、兼容性矩阵与运维（doctor/demo/wipe/MCP）](#page-4)

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

## Pulse 项目概览与整体架构

### 相关页面

相关主题：[状态感知胶囊检索与连续性包](#page-2), [存储层、Schema 演进与 Material Graph](#page-3), [安装路径、兼容性矩阵与运维（doctor/demo/wipe/MCP）](#page-4)

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

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

- [README.md](https://github.com/zbs-gg/pulse/blob/main/README.md)
- [AGENTS.md](https://github.com/zbs-gg/pulse/blob/main/AGENTS.md)
- [llms.txt](https://github.com/zbs-gg/pulse/blob/main/llms.txt)
- [pulse-app/cmd/pulse/main.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/cmd/pulse/main.go)
- [pulse-app/internal/server/server.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/server/server.go)
- [CHANGELOG.md](https://github.com/zbs-gg/pulse/blob/main/CHANGELOG.md)
</details>

# Pulse 项目概览与整体架构

## 一、项目定位与目标
Pulse 是一个面向 AI Agent 的**本地优先（local-first）、状态感知（state-aware）的记忆引擎**。它不直接产出对话文本或调用工具，而是为上层 Agent 提供可持久化、可分类、可检索的"长期记忆"层，使 Agent 在多轮、多会话乃至跨进程场景中保持上下文一致。项目的设计前提是：记忆数据归属于用户本地，状态可被显式标注，从而让 Agent 在推理时既能"记得"也能"知道现在应该想起什么"。

资料来源：[README.md:1-40]()

## 二、整体架构分层
Pulse 使用 Go 语言实现，模块边界围绕"入口—服务端—检索—存储"四层组织：

- **入口层**：`pulse-app/cmd/pulse/main.go` 负责解析命令行参数、加载配置、装配依赖并启动服务进程。
- **服务端**：`pulse-app/internal/server/server.go` 暴露对外 API（如 `pulse_remember`、`pulse_recall`），是所有读写请求的统一入口。
- **检索层**：把已记住的 capsule 投影到一张**检索图（retrieval graph）**，并通过独立的 state 通道在检索阶段过滤与排序。
- **存储层**：本地优先的持久化层，将索引与正文分离存储，便于检索图复用与一致性维护。

```mermaid
flowchart LR
  Client[Agent / CLI] -->|pulse_remember / pulse_recall| Server[pulse-app/internal/server/server.go]
  Server --> Engine[Memory Engine]
  Engine --> Graph[Retrieval Graph]
  Engine --> Store[(Local Store)]
  Graph -->|state-aware ranking| Server
  Server --> Client
```

资料来源：[pulse-app/cmd/pulse/main.go:1-60]()，[pulse-app/internal/server/server.go:1-80]()，[llms.txt:1-30]()

## 三、状态感知检索机制
v0.6.7 引入的 **state-aware capsule retrieval** 是当前架构的标志性能力，其核心思想是把"状态"从元数据提升为独立的检索维度：

- **胶囊化（capsule）**：每条记忆以 capsule 形式存在，并被显式投影到检索图，成为可寻址的节点而非纯文本片段。
- **state 通道**：当 capsule 携带 `state:<flag>` 标签，且调用方传入 `user_state.context_flags[flag]` 为真时，该胶囊所在分区在排序时被整体抬升，从而凌驾于"普通"记忆之上。
- **同分区 tie-break**：被抬升的分区内部以词法顺序（lexical tie-break）二次排序，避免引入额外语义开销。
- **无 flag 兜底**：若没有任何 state flag 激活，则回退到主题连贯性（thematic coherence）+ `state:calm` 等默认偏好，保证结果稳定可复现。
- 官方公布的评测显示 15/15 命中率，表明在带状态的查询路径上，state 通道不会被普通记忆淹没。

资料来源：[CHANGELOG.md:1-50]()

## 四、安全护栏与版本演进
项目把"安全护栏"作为一等公民，与功能演进并行推进：

- **Unicode-aware 标签**：v0.6.5 修复了非 ASCII 标签（如西里尔字母）首次写入需重试的问题，消除了 `pulse_remember` 路径上多秒级别的隐式延迟。
- **三组守卫**：secret / path / transcript 三个方向的负向烟雾测试持续拒绝 **15 种危险负载**，覆盖凭据泄露、路径穿越、对话回灌等典型攻击面。
- **可审计变更**：所有能力边界与回归修复都通过 `CHANGELOG.md` 显式记录，方便 Agent 作者判断升级风险。

资料来源：[CHANGELOG.md:1-80]()，[AGENTS.md:1-40]()

## 五、协作与扩展边界
- `AGENTS.md` 规定了 AI Agent 协作流程：新增能力需同步更新变更说明与用例，确保记忆语义对所有调用方保持一致。
- `llms.txt` 为 LLM 消费方提供精简接入说明，使 Pulse 可以作为更大 Agent 栈中的一块"记忆后端"被嵌入。
- 后续演进方向集中于：在保持本地优先与状态可解释性的前提下，进一步提升检索图在跨进程、跨设备场景下的一致性表现。

资料来源：[AGENTS.md:1-50]()，[llms.txt:1-40]()

---

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

## 状态感知胶囊检索与连续性包

### 相关页面

相关主题：[Pulse 项目概览与整体架构](#page-1), [存储层、Schema 演进与 Material Graph](#page-3)

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

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

- [pulse-app/internal/retrieve/graph_retrieve.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/graph_retrieve.go)
- [pulse-app/internal/retrieve/state.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/state.go)
- [pulse-app/internal/retrieve/state_tag_boost.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/state_tag_boost.go)
- [pulse-app/internal/retrieve/v3boosts.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/v3boosts.go)
- [pulse-app/internal/retrieve/emotion_role.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/emotion_role.go)
- [pulse-app/internal/store/memory_capsule.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/memory_capsule.go)
</details>

# 状态感知胶囊检索与连续性包

## 概述

`Pulse` 是一个面向 AI 代理的本地优先（local-first）、具备状态感知的记忆引擎。其核心子系统之一 **状态感知胶囊检索（State-aware Capsule Retrieval）** 随 v0.6.7 引入，负责在检索阶段决定"哪条记忆胜出"。该子系统通过将记忆胶囊（memory capsule）投影到检索图（retrieval graph）并维护一条独立的 **状态通道（state channel）**，使得当用户进入特定情境（如 `calm`、`alert`）时，带有 `state:<flag>` 标签的记忆会优先召回。资料来源：[v0.6.7 发布说明](https://github.com/zbs-gg/pulse/releases/tag/v0.6.7)。

围绕该通道的还有 **连续性包（continuity pack）**：一组配套的提升器（booster）文件，覆盖情绪角色（emotion role）、v3 提升逻辑和状态标签提升，使检索不仅"找得到"，还能"找得连贯"。资料来源：[pulse-app/internal/retrieve/state.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/state.go)。

## 状态通道与标签提升机制

状态通道以 `user_state.context_flags` 为入口，由 `state.go` 读取当前生效的上下文标志，并将其传递给 `graph_retrieve.go` 的排序管线。记忆胶囊若被打上 `state:<flag>` 标签，便会进入"状态分区"，位于普通记忆之上；当对应 `context_flags[flag]` 未激活时，这些项目回落到常规排序路径。资料来源：[pulse-app/internal/retrieve/state.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/state.go)、[pulse-app/internal/retrieve/graph_retrieve.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/graph_retrieve.go)。

具体打分动作发生在 `state_tag_boost.go`：模块按当前 flag 对候选胶囊计算提升值，保证同分区内部仍以词典序（lexical tie-break）作为最终决定。当 `context_flags` 全部为空时，系统回退到 `state:calm` + 主题一致性兜底策略，保证始终有一条可解释的胜出路径。资料来源：[pulse-app/internal/retrieve/state_tag_boost.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/state_tag_boost.go)。

## 胶囊数据结构与图投影

胶囊由 `memory_capsule.go` 定义，是检索图中的最小节点。每个胶囊持有内容、标签集与时间戳；标签集中允许出现 `state:<flag>`，该前缀在写入路径已被验证通过 Unicode 字符（v0.6.5 修复非 ASCII 标签首次校验失败的问题）。资料来源：[pulse-app/internal/store/memory_capsule.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/memory_capsule.go)、[v0.6.5 发布说明](https://github.com/zbs-gg/pulse/releases/tag/v0.6.5)。

`graph_retrieve.go` 在构建检索图时将这些胶囊节点连同其标签一并注入，状态通道读取 `state:<flag>` 标签后，在排序阶段建立状态分区。下列简图描述一次典型召回的数据流：

```mermaid
flowchart LR
  A[memory_capsule.go<br/>胶囊节点] --> B[graph_retrieve.go<br/>检索图投影]
  C[state.go<br/>读取 context_flags] --> D[state_tag_boost.go<br/>标签提升]
  B --> E{状态 flag 激活?}
  D --> E
  E -- 是 --> F[状态分区优先<br/>词典序兜底]
  E -- 否 --> G[常规排序<br/>calm + 主题一致性]
```

## 连续性包：v3 提升与情绪角色

连续性包由 `v3boosts.go` 与 `emotion_role.go` 共同构成，承担"找得连贯"的职责。`v3boosts.go` 在 v3 评分模型上叠加主题、时间、近因性等连续性信号；`emotion_role.go` 进一步将情绪角色（如安抚、提醒）映射为加权因子，使状态通道胜出的胶囊在情绪一致性上更稳定。资料来源：[pulse-app/internal/retrieve/v3boosts.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/v3boosts.go)、[pulse-app/internal/retrieve/emotion_role.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/retrieve/emotion_role.go)。

社区证据显示，状态感知胶囊检索在实测中达到 15/15 通过率，说明状态分区与连续性包协同稳定，且保留了原有 secret/path/transcript 守卫（v0.6.5 引入负向烟雾测试拒绝 15 类危险载荷）。资料来源：[v0.6.7 发布说明](https://github.com/zbs-gg/pulse/releases/tag/v0.6.7)、[v0.6.5 发布说明](https://github.com/zbs-gg/pulse/releases/tag/v0.6.5)。

## 总结

状态感知胶囊检索与连续性包是 Pulse 的核心召回管线，由 `state.go`、`state_tag_boost.go`、`graph_retrieve.go` 共同实现状态分区，再由 `v3boosts.go`、`emotion_role.go` 保障召回在主题与情绪层面的连续性。该设计让记忆召回既对 `context_flags` 敏感，又在无 flag 时拥有 `state:calm` 兜底，是 v0.6.7 的关键能力。资料来源：[v0.6.7 发布说明](https://github.com/zbs-gg/pulse/releases/tag/v0.6.7)。

---

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

## 存储层、Schema 演进与 Material Graph

### 相关页面

相关主题：[状态感知胶囊检索与连续性包](#page-2)

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

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

- [pulse-app/internal/store/schema.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/schema.go)
- [pulse-app/internal/store/store.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/store.go)
- [pulse-app/internal/store/material_graph.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/material_graph.go)
- [pulse-app/internal/store/memory_capsule.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/memory_capsule.go)
- [pulse-app/internal/store/assertions.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/assertions.go)
- [pulse-app/internal/store/claim_resolver.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/store/claim_resolver.go)
</details>

# 存储层、Schema 演进与 Material Graph

Pulse 的存储子系统是整个本地优先（local-first）、状态感知（state-aware）记忆引擎的物理底盘。`pulse-app/internal/store` 目录下聚合了所有持久化原语——负责把"被记住"的事实、断言、上下文状态、标签与对应的检索图谱落到磁盘上，并在版本升级时平滑演进 schema。本页聚焦于三个紧密耦合的概念：**存储层总体职责**、**Schema 演进机制**、以及**Material Graph（物化检索图）**。

## 存储层总体职责与分层

存储层对外屏蔽底层 KV/嵌入式数据库的实现细节，对内向上层服务（如 `pulse_remember`、capsule 检索通路）提供原子写入、状态查询、图谱构建三类能力。`store.go` 充当门面（facade），把不同子模块聚合起来：

- **Memory Capsule 落盘**：`memory_capsule.go` 将每条被记住的记忆压缩为 capsule 结构，写入时同步投影到检索图谱中。
- **Material Graph 投影**：`material_graph.go` 维护一张"已落盘即入图"的图结构，使记忆条目在写入瞬间即可被检索通路访问，避免异步索引带来的"写入可见性窗口"问题。
- **Schema 版本门控**：`schema.go` 在 `Store.Open` 路径上检查并按需执行迁移，保证旧版本数据在升级后仍可读取。

```mermaid
flowchart LR
  A[pulse_remember / 写入路径] --> B[store.go<br/>门面]
  B --> C[memory_capsule.go<br/>条目序列化]
  B --> D[material_graph.go<br/>检索图谱]
  B --> E[schema.go<br/>迁移与版本]
  B --> F[claim_resolver.go<br/>冲突/Claim 解析]
  B --> G[assertions.go<br/>不变式断言]
  D --> H[(本地持久化层)]
  E --> H
  C --> H
```

资料来源：[pulse-app/internal/store/store.go:1-120]()、[pulse-app/internal/store/memory_capsule.go:1-80]()。

## Schema 演进与断言门控

随着 Pulse 从 0.6.5 → 0.6.7 的演进，schema 必须容纳 Unicode 标签、`state:<flag>` 通道等新增字段。`schema.go` 内部通过版本号 + 迁移函数列表的方式实现轻量演进：每次 `Open` 时读取持久化层的 schema version，与代码内置版本对比，按差集顺序执行迁移步骤。

要点：

1. **版本比对与幂等迁移**：迁移函数被设计为幂等，重复执行不会引入重复记录。`
资料来源：[pulse-app/internal/store/schema.go:30-95]()`。
2. **Unicode-aware 标签校验**：`schema.go` 在 tag 字段上接受非 ASCII 字符（包含西里尔字母），这正是 v0.6.5 修复"沉默重试"问题的落点——校验逻辑放在 schema 解析早期，避免写入路径重新跑一遍序列化。
`
资料来源：[pulse-app/internal/store/schema.go:97-140]()`。
3. **断言护栏**：`assertions.go` 在迁移前后注入不变式断言（例如"所有 capsule 必须带有唯一 ID"、"标签集合非空则必须 UTF-8 合法"），失败则中止启动。
`
资料来源：[pulse-app/internal/store/assertions.go:1-60]()`。

社区反馈显示，Unicode 校验回归在 0.6.5 之前曾带来多秒延迟，因此 schema 层现在通过 `validate_once` 风格设计避免重复校验。

## Material Graph：写入即投影的检索图谱

`material_graph.go` 实现了"material（物化）"语义：胶囊一经写入即被投影到图谱中，使得 `pulse_recall` 任何时刻查询都能看到最新集合，无需等待后台索引器。

- **节点（Node）**：每条 capsule 是一个节点，边由标签共现、状态字段共享构造。
- **状态通道（state:<flag>）**：v0.6.7 起，凡带 `state:<flag>` 标签的节点在活跃标志下被提升到单独分区，词法分数仅在分区内作为 tie-break。
`
资料来源：[pulse-app/internal/store/material_graph.go:50-130]()`。
- **主题一致性回退**：当 `user_state.context_flags` 中没有激活标志时，节点回到主题（thematic）通道，依靠向量/词的连贯度排序。
`
资料来源：[pulse-app/internal/store/material_graph.go:132-180]()`。

## Claim 解析与一致性收尾

`claim_resolver.go` 处理多源声称同一事实时的冲突解决，是 Material Graph 写入流程的最后一步。常见的输入包括：被记忆值与既有 capsule 之间的字段级差异、并发写入留下的 tombstone、以及状态字段切换带来的隐含上下文变更。Claim resolver 在解析后通知 material graph 更新边权重，并返回给上层 `pulse_remember` 一个明确的响应报文。

`
资料来源：[pulse-app/internal/store/claim_resolver.go:1-110]()`、`[pulse-app/internal/store/store.go:120-180]()`。

综上所述，存储层把 schema 演进、断言护栏、物化图与 claim 解析四件工作耦合在同一事务边界内落地，使得 Pulse 在保持 local-first 简洁性的同时，仍能支持 Unicode 标签、状态分通道等增量能力——这是 0.6.5 与 0.6.7 两个发布版本共同验证的设计主线。

---

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

## 安装路径、兼容性矩阵与运维（doctor/demo/wipe/MCP）

### 相关页面

相关主题：[Pulse 项目概览与整体架构](#page-1), [状态感知胶囊检索与连续性包](#page-2)

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

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

- [README.md](https://github.com/zbs-gg/pulse/blob/main/README.md)
- [docs/INSTALL_WITH_AGENT.md](https://github.com/zbs-gg/pulse/blob/main/docs/INSTALL_WITH_AGENT.md)
- [docs/SECURITY_INSTALL_CHECKLIST.md](https://github.com/zbs-gg/pulse/blob/main/docs/SECURITY_INSTALL_CHECKLIST.md)
- [pulse-app/cli/src/cli.js](https://github.com/zbs-gg/pulse/blob/main/pulse-app/cli/src/cli.js)
- [pulse-app/internal/erase/erase.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/erase/erase.go)
- [pulse-app/internal/health/fixture.go](https://github.com/zbs-gg/pulse/blob/main/pulse-app/internal/health/fixture.go)
</details>

# 安装路径、兼容性矩阵与运维（doctor/demo/wipe/MCP）

## 概述

Pulse 是一个面向 AI 代理的、本地优先（local-first）、状态感知的记忆引擎。当前发布线为 v0.6.7（状态感知胶囊检索）。本页聚焦安装、平台兼容与四类运维入口——`doctor` 健康自检、`demo` 演示种子、`wipe` 数据擦除与 `MCP` 协议接入——以便用户在选型、部署与排障时建立一致的预期。CLI 由 `pulse-app/cli/src/cli.js` 暴露，底层 Go 服务在 `pulse-app/internal/` 下承载擦除与健康逻辑。资料来源：[README.md]()

## 安装路径

Pulse 提供三种互不互斥的安装形态，可按使用场景单独或组合部署。

- **本地 CLI 独立安装**：直接通过 CLI 二进制使用 `pulse_remember` 等命令，适合本地原型与脚本化场景。CLI 入口与命令路由位于 `pulse-app/cli/src/cli.js`。资料来源：[pulse-app/cli/src/cli.js]()
- **Agent 嵌入安装**：作为 AI 代理的依赖或工具集集成，遵循 `docs/INSTALL_WITH_AGENT.md` 中描述的代理侧接入步骤。资料来源：[docs/INSTALL_WITH_AGENT.md]()
- **带安全检查的安装**：在上述任一路径之外，需按 `docs/SECURITY_INSTALL_CHECKLIST.md` 完成秘密/路径/转录三类安全守卫（secret/path/transcript guards）的核对；v0.6.5 的负向烟雾测试覆盖了 15 种危险载荷并应全部被拒。资料来源：[docs/SECURITY_INSTALL_CHECKLIST.md]()

## 兼容性矩阵

下表汇总了 Pulse 当前文档与代码可验证的兼容性边界，仅列出可由仓库文件直接支持的项；空白格表示该组合未在仓库中明示。

| 维度 | 支持范围 | 备注 |
| --- | --- | --- |
| 运行时 | 本地优先（local-first） | 数据落在用户本地，无需远程服务 资料来源：[README.md]() |
| 记忆标记 | Unicode 感知 | v0.6.5 起非 ASCII（如 Cyrillic）标签首次校验即通过 资料来源：[README.md]() |
| 检索通道 | 状态通道 + 词法通道 | v0.6.7 的 `state:<flag>` 项在 `user_state.context_flags[flag]` 激活时优先 资料来源：[README.md]() |
| 安全守卫 | 秘密 / 路径 / 转录 | 负向烟雾测试 15/15 拒绝 资料来源：[docs/SECURITY_INSTALL_CHECKLIST.md]() |

## 运维命令（doctor/demo/wipe/MCP）

### doctor — 健康自检

`doctor` 由 `pulse-app/internal/health/fixture.go` 提供健康探针实现，供 CLI 调用以校验本地环境与依赖就绪状态。建议在首次安装、升级后或排障前运行。资料来源：[pulse-app/internal/health/fixture.go]()

### demo — 演示种子

`demo` 命令用于在隔离环境中注入演示胶囊，使用户在不污染生产记忆的前提下观察状态感知检索行为；其与 v0.6.7 引入的 `state:<flag>` 分区机制配合，可演示 `state:calm` 等典型场景。资料来源：[README.md]()

### wipe — 数据擦除

`wipe` 通过 `pulse-app/internal/erase/erase.go` 实现本地记忆胶囊与状态上下文的不可逆清理；由于 Pulse 为本地优先设计，擦除操作无需远端协调即可完成，但应与 `docs/SECURITY_INSTALL_CHECKLIST.md` 一并审计以避免残留。资料来源：[pulse-app/internal/erase/erase.go]() 资料来源：[docs/SECURITY_INSTALL_CHECKLIST.md]()

### MCP — 模型上下文协议接入

`MCP` 命令将 Pulse 的记忆能力以模型上下文协议的形式暴露给上游代理，使代理在调用 `pulse_remember` 等操作时复用统一的安全守卫与状态通道。该入口在 CLI 中由 `pulse-app/cli/src/cli.js` 注册。资料来源：[pulse-app/cli/src/cli.js]()

### 运维流程

```mermaid
flowchart LR
  A[安装] --> B[doctor 自检]
  B --> C{通过?}
  C -- 否 --> X[按 SECURITY_INSTALL_CHECKLIST 修复]
  C -- 是 --> D[demo 验证]
  D --> E[投入运行 / MCP 接入]
  E --> F[wipe 数据擦除]
```

## 常见排障要点

- 若 `pulse_remember` 在非 ASCII 标签上出现多秒级延迟，请确认版本不低于 v0.6.5；旧版本的重试逻辑是已知根因之一。资料来源：[README.md]()
- 检索结果未按预期偏置到 `state:<flag>` 分组时，应检查 `user_state.context_flags` 是否正确激活对应 flag。资料来源：[README.md]()
- 任何危险载荷（秘密/路径/转录）若被 `doctor` 或守卫放行，应立即视为安全回归并对照 15 项负向烟雾测试复测。资料来源：[docs/SECURITY_INSTALL_CHECKLIST.md]()

---

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

---

## Doramagic 踩坑日志

项目：zbs-gg/pulse

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/zbs-gg/pulse | no_demo; severity=medium

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

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

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

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

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

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

<!-- canonical_name: zbs-gg/pulse; human_manual_source: deepwiki_human_wiki -->