项目简介

Commonplace 是一个基于 MCP（Model Context Protocol）的持久化记忆系统，旨在为 AI 代理提供跨会话的上下文记忆能力。该项目使 AI 能够记住用户的偏好、项目的架构决策、技术反馈等重要信息，从而在长时间交互中保持一致性和连续性。

资料来源：README.md:1-10

核心设计原则

记忆文件即真相

Commonplace 采用 Markdown 文件作为记忆的持久化存储介质。每个记忆以 .md 文件形式存储，YAML frontmatter 携带结构化元数据，文件主体承载具体内容。这种设计使得记忆可以被版本控制、人类可读、手动编辑，且不依赖专有格式。

资料来源：CLAUDE.md:15-20

边车文件可重建

.embedding 等边车文件（sidecar）是从 .md 源文件派生的，可以随时从源码重新生成。这确保了数据的安全性——即使边车文件丢失或损坏，也能通过扫描重建索引。

资料来源：CLAUDE.md:20-22

内存类型系统

Commonplace 定义了四种内存类型，构成记忆分类的基础：

资料来源：README.md:45-60

记忆存储架构

双作用域设计

系统支持同时加载两个独立的记忆存储：

graph TD
    A[Commonplace] --> B[用户存储]
    A --> C[项目存储]
    B --> D[COMMONPLACE_USER_DIR<br/>~/.commonplace/memory]
    C --> E[COMMONPLACE_PROJECT_DIR<br/>或 .commonplace/memory]
    
    F[MCP roots/list检测] --> E
    G[当前工作目录] --> E

• 用户存储（User Store）：始终加载，存储跨项目共享的个人规则和反馈
• 项目存储（Project Store）：仅在检测到项目根目录时加载，存储项目特定的上下文

资料来源：README.md:140-165

目录结构

每个记忆存储遵循以下结构：

<store-dir>/
├── <name>.md           # 记忆文件
├── <name>.embedding    # 向量嵌入边车（自动生成）
└── .index/             # 索引缓存（可选）

资料来源：src/store/memory.ts:20-35

记忆文件格式

记忆文件采用标准 Markdown + YAML frontmatter 格式：

概述

Commonplace 是一个本地优先的个人知识管理工具，以 MCP（Model Context Protocol）服务器形式运行。它将笔记存储为带有 YAML 前缀的纯 Markdown 文件，嵌入向量存储在 .embedding 侧边文件中，语义搜索完全离线运行，底层使用 transformers.js + bge-base-en-v1.5 模型实现。

本节介绍 Commonplace 的完整安装流程、系统要求、环境配置以及与 Claude Code 的集成方法。

系统要求

Node.js 环境

Commonplace 要求 Node.js 版本 20 或更高。项目通过 .nvmrc 文件声明了版本要求：

20

同时 package.json 的 engines 字段也做了约束声明。

包管理器

资料来源：CLAUDE.md:30

技术栈

资料来源：CLAUDE.md:24-37

安装流程

步骤一：克隆仓库

git clone https://github.com/rickbassham/commonplace.git
cd commonplace

步骤二：安装依赖

pnpm install

步骤三：构建项目

pnpm build

构建过程会：

• 编译 TypeScript 源码到 ESM 格式
• 输出到 dist/ 目录
• 生成两个可执行入口：commonplace 和 commonplace-mcp

资料来源：CLAUDE.md:48-50

Claude Code 集成配置

添加 MCP 服务器

在 Claude Code 配置中添加以下服务器配置：

{
  "mcpServers": {
    "commonplace": {
      "command": "node",
      "args": ["/path/to/commonplace/dist/bin/commonplace-mcp.js"]
    }
  }
}

完成配置后，重启所有正在运行的 Claude Code 会话，四个记忆工具即可使用：

• memory_save
• memory_list
• memory_delete
• memory_search

资料来源：README.md:48-58

环境变量配置

存储路径配置

功能开关

资料来源：CLAUDE.md:53-57

记忆存储架构

graph TD
    subgraph 用户存储
        USER_DIR["COMMONPLACE_USER_DIR<br/>(~/.commonplace/memory)"]
    end
    
    subgraph 项目存储
        PROJ_DIR["COMMONPLACE_PROJECT_DIR<br/>(按需加载)"]
    end
    
    subgraph 记忆文件
        MD["<name>.md<br/>YAML 前缀 + Markdown 正文"]
        EMB["<name>.embedding<br/>二进制嵌入向量"]
    end
    
    USER_DIR --> MD
    PROJ_DIR --> MD
    MD --> EMB

记忆类型系统

四种记忆类型

资料来源：README.md:60-73

CLI 命令行工具

可执行文件

迁移命令

# 检测已知外部记忆源
commonplace migrate

# 从指定源导入记忆
commonplace migrate --from claude-code

# 预览模式（不写入）
commonplace migrate --from claude-code --dry-run

# 脚本化运行
commonplace migrate --from claude-code --auto

# 为现有记忆目录重建侧边文件
commonplace migrate <dir>
commonplace migrate <dir> --dry-run
commonplace migrate <dir> --prune-dangling

资料来源：README.md:17-23

验证安装

构建验证

make build
make typecheck
make lint

运行测试

make test

审计依赖

make audit

资料来源：CONTRIBUTING.md:24-26

目录结构概览

commonplace/
├── dist/                    # 构建输出
│   ├── index.js            # CLI 入口
│   └── bin/
│       └── commonplace-mcp.js  # MCP 服务器入口
├── src/
│   ├── embedder/           # transformers.js 封装
│   ├── store/              # Markdown + 侧边文件 I/O
│   └── server/             # MCP 服务器处理程序
├── package.json
└── .nvmrc                  # Node.js 版本声明

常见问题

Q: npm 或 yarn 可以使用吗？

不可以。项目仅支持 pnpm 作为包管理器。使用其他包管理器会导致依赖安装失败或构建错误。

Q: Node.js 18 可以使用吗？

不可以。必须使用 Node.js 20 或更高版本。

Q: 记忆文件存储在哪里？

默认情况下，用户级记忆存储在 ~/.commonplace/memory，项目级记忆存储在项目根目录的 .commonplace/memory 下。

Q: 如何重建嵌入向量？

使用 commonplace migrate <dir> 命令可重新扫描目录并重建所有 .embedding 侧边文件。

概述

Commonplace 是一个为 Claude Code 提供持久化记忆功能的 MCP (Model Context Protocol) 工具系统。它通过 markdown 文件存储记忆内容，支持语义搜索和关系图谱管理。资料来源：CLAUDE.md:1

该系统具有以下核心设计原则：

• 单一真相来源 — .md 文件是数据的唯一真实来源，.embedding 等辅助文件可随时从源文件重新生成
• 无覆盖写入 — memory_save 工具拒绝覆盖已有条目，必须先删除再保存
• 双存储架构 — 支持用户级存储和项目级存储分离
• 图关系管理 — 支持在记忆之间建立显式关系边

资料来源：CLAUDE.md:16-19

概述

Commonplace 是一个基于 TypeScript 构建的记忆管理工具，通过 MCP（Model Context Protocol）协议与 Claude Code 等 AI 代理集成。其技术栈围绕本地向量嵌入推理、Markdown 文件存储和 MCP 协议通信三大核心能力展开。

项目采用 Node.js 作为运行时环境，要求 Node >=20，代码以 ESM（ECMAScript Modules）格式输出，不使用 CommonJS。资料来源：CLAUDE.md

核心架构分层

graph TD
    subgraph "表现层"
        CLI[CLI 命令行]
        MCP[MCP 服务器]
    end
    
    subgraph "服务层"
        HANDLERS[MCP Handlers]
        EMBEDDER[嵌入器]
    end
    
    subgraph "存储层"
        MEMORY_STORE[MemoryStore]
        GRAPH[MemoryGraph]
    end
    
    subgraph "文件系统"
        MD[.md 文件]
        EMBEDDING[.embedding 侧文件]
    end
    
    CLI --> HANDLERS
    MCP --> HANDLERS
    HANDLERS --> EMBEDDER
    HANDLERS --> MEMORY_STORE
    MEMORY_STORE --> GRAPH
    MEMORY_STORE --> MD
    MEMORY_STORE --> EMBEDDING

编程语言与工具链

TypeScript

项目使用 TypeScript 进行开发，采用严格模式（strict mode）和 ES2022 编译目标。

资料来源：CLAUDE.md

代码质量工具

项目配置了多个 Make 目标来执行质量检查：

• make typecheck - TypeScript 类型检查
• make lint - ESLint 代码检查
• make test - vitest 测试执行
• make build - 项目构建
• make audit - 安全审计（非阻塞）

资料来源：CONTRIBUTING.md

核心依赖库

向量嵌入推理

src/embedder/ 目录封装了 transformers.js 的调用，提供类型化的 embed(text) -> Float32Array 接口，并隔离模型加载逻辑与业务代码的耦合。

sequenceDiagram
    participant 调用方
    participant Embedder
    participant Transformers
    
    调用方->>Embedder: embed(text)
    Embedder->>Transformers: 加载模型
    Transformers-->>Embedder: 模型就绪
    Embedder->>Transformers: 执行推理
    Transformers-->>Embedder: Float32Array
    Embedder-->>调用方: 返回嵌入向量

资料来源：CLAUDE.md

MCP 协议通信

src/server/ 目录包含 MCP 工具处理器和资源处理器，负责将 MemoryStore 和 Embedder 的能力暴露给外部 MCP 客户端。

项目定义了两个独立的 bin 入口：

• commonplace -> dist/index.js：CLI 命令行界面
• commonplace-mcp -> dist/bin/commonplace-mcp.js：stdio MCP 服务器

资料来源：src/index.ts

文件处理

数据存储架构

存储目录结构

graph LR
    subgraph "用户存储 ~/\.commonplace/memory"
        MD1[name1.md]
        EMB1[name1.embedding]
        MD2[name2.md]
        EMB2[name2.embedding]
    end
    
    subgraph "项目存储 \<project\>/\.commonplace/memory"
        MD3[proj_name1.md]
        EMB3[proj_name1.embedding]
    end

Memory 文件格式

每个记忆以 Markdown 文件形式存储，包含 YAML frontmatter 和正文内容：

概述

Commonplace 的嵌入模型与语义搜索子系统是该应用的核心能力之一。它使 MCP 服务器能够对用户的笔记进行语义相似度搜索，而非简单的关键词匹配。整个系统完全离线运行，不依赖任何云端 API，通过本地向量计算实现语义检索。

核心设计原则：

• 嵌入完全本地化：使用 @huggingface/transformers 库配合 bge-base-en-v1.5 模型
• 边车文件（Sidecar）模式：.embedding 二进制文件与 .md 笔记一一对应，作为派生物可随时重建
• 内容哈希校验：通过 contentSha 确保嵌入与笔记内容的一致性

资料来源：CHANGELOG.md

架构概览

graph TD
    A["📄 Memory (.md)"] --> B["contentSha() 计算哈希"]
    A --> C["序列化内存对象"]
    B --> D["嵌入模型 bge-base-en-v1.5"]
    C --> E[".embedding 边车文件"]
    D --> E
    E --> F["向量数据库"]
    G["语义搜索查询"] --> H["计算查询向量"]
    H --> I["余弦相似度计算"]
    F --> I
    I --> J["Top-K 结果排序"]
    J --> K["返回 MemorySearchMatch"]

内存文件结构与内容哈希

YAML Frontmatter 格式

每篇笔记都是一个 Markdown 文件，前置 YAML 元数据：

概述

Commonplace 系统中的"内存"(Memory)是项目的核心数据单元。每个内存以 Markdown 文件形式持久化存储，配合同名的二进制侧载文件(.embedding)存放嵌入向量。这种设计确保了 Markdown 文件为唯一真相来源，侧载文件可随时从源文件重新生成。

系统通过 contentSha 哈希值实现内容变更检测，确保嵌入向量与源文件保持同步。当检测到内容变化时，系统会自动重新生成嵌入并更新侧载文件。

资料来源：src/store/memory.ts:1-30

内存 Markdown 格式

文件结构

内存文件采用标准 Markdown+YAML frontmatter 格式，文件结构如下：

概述

Commonplace 的搜索功能是一个本地优先的语义搜索系统，基于余弦相似度（Cosine Similarity）算法实现完全离线的向量搜索。系统使用 @huggingface/transformers 库和 bge-base-en-v1.5 模型生成嵌入向量，支持对记忆进行语义匹配检索。

搜索功能的核心设计原则是记忆文件（.md）是唯一真相来源，.embedding 侧边文件是从记忆内容派生的，可以随时删除和重建。

核心架构

搜索流程图

graph TD
    A[用户发起 memory_search] --> B[解析查询参数]
    B --> C[生成查询向量]
    C --> D[遍历所有记忆文件]
    D --> E[加载 .embedding 侧边文件]
    E --> F[计算余弦相似度]
    F --> G[按分数排序取 Top-K]
    G --> H[合并 User/Project 商店结果]
    H --> I[排除已废弃记忆]
    I --> J[丰富关系图数据]
    J --> K[返回搜索结果]

关键组件

嵌入向量生成

嵌入模型

系统使用 bge-base-en-v1.5 模型作为默认嵌入模型，该模型输出 768 维的向量表示。

graph LR
    A[记忆文本] --> B[contentSha 计算]
    B --> C[模型推理]
    C --> D[768维向量]
    D --> E[.embedding 侧边文件]

contentSha 计算

为了检测记忆内容是否发生变化，系统为每个记忆计算 SHA-256 哈希值：

export const contentSha = (memory: Memory): string =>
  createHash('sha256')
    .update(`${memory.type}\n${memory.name}\n${memory.description}\n${memory.body}`, 'utf8')
    .digest('hex');

重要设计决策：哈希值的计算范围仅包括 type、name、description 和 body 四个字段。图字段（relations 和 supersedes）不参与哈希计算，这确保了添加或删除图关系不会导致嵌入向量失效。

资料来源：src/store/memory.ts:47-51

惰性重新嵌入

在保存记忆时，如果 contentSha 与侧边文件中存储的哈希值不匹配，系统会自动触发重新嵌入：

const needsReembed =
  isMissing || stale.embedding.corrupt || stale.embedding.contentShaMismatch;

这确保了搜索结果始终与最新的记忆内容同步。

记忆文件结构

Markdown 格式

记忆以 Markdown 文件形式存储，包含 YAML 前置数据：

概述

图功能与关系管理是 Commonplace 项目中用于管理记忆（Memory）之间语义关联的核心模块。该模块基于 YAML frontmatter 中的 relations 和 supersedes 字段构建内存图，并支持从正文中提取 [[name]] 形式的提及关系。通过这些机制，用户可以构建记忆之间的有向图，实现知识关联、一跳扩展搜索等功能。

该功能主要服务于以下场景：

• 显式声明记忆之间的关系（如"此记忆建立在另一个记忆之上"）
• 自动检测正文中的提及关系
• 悬空边检测与清理
• 图可视化与路径查询

资料来源：src/store/graph.ts:1-20

数据模型

边的类型

图模块定义了六种边类型，分为两类：

授权边类型（Authored Relation Types）

派生边类型（Derived Edge Types）

资料来源：src/store/graph.ts:19-22

export type EdgeType = RelationType | 'supersedes' | 'mentions';

边接口

export interface Edge {
  from: string;    // 源记忆名称
  to: string;      // 目标记忆名称
  type: EdgeType;  // 边类型
}

悬空边接口

当边指向的目标记忆不存在时，该边称为悬空边（Dangling Edge）：

export interface DanglingEdge {
  from: string;
  to: string;
  type: string;  // 类型被放宽为 string，允许扩展
}

资料来源：src/store/graph.ts:24-44

记忆前端matter关系字段

每个记忆的 YAML frontmatter 可包含以下图字段：

概述

存储系统是 Commonplace 项目的核心模块，负责将记忆（Memory）以 Markdown 文件形式持久化到本地磁盘，同时管理向量嵌入（Embedding）sidecar 文件、图关系以及内存索引。该系统采用本地优先（Local-First）架构，所有数据存储在用户本地目录，无需云端依赖，实现了完全的离线语义搜索能力。

存储系统的设计目标包括：

• 文件即存储：每个记忆是一个独立的 .md 文件，YAML frontmatter 存储元数据
• 嵌入派生：.embedding sidecar 文件由 .md 内容派生，可随时重建
• 原子操作：通过 temp file + rename 模式保证写操作的原子性
• 图关系管理：支持记忆之间的多种关系类型（builds-on、related-to 等）
• 作用域隔离：支持 user 和 project 两种存储作用域

资料来源：src/store/memory-store.ts:1-50

架构概览

graph TB
    subgraph "存储层 (Disk)"
        MD[".md 文件<br/>YAML Frontmatter + Body"]
        EMB[".embedding 文件<br/>Binary Sidecar"]
    end
    
    subgraph "内存索引 (In-Memory)"
        IDX["#entries[]<br/>MemoryEntry 数组"]
        GRAPH["#graph<br/>MemoryGraph"]
    end
    
    subgraph "核心模块"
        MS["MemoryStore<br/>主存储类"]
        AW["atomicWrite<br/>原子写入工具"]
        MEM["memory.ts<br/>序列化/反序列化"]
        MENT["mentions.ts<br/>提及提取器"]
    end
    
    MD --> MS
    EMB --> MS
    MS --> IDX
    MS --> GRAPH
    MS --> AW
    MS --> MEM
    MS --> MENT

核心组件

MemoryStore

MemoryStore 是存储系统的主类，负责管理特定目录下的所有记忆文件。它维护两个核心内部状态：

• #entries: MemoryEntry[] — 从磁盘扫描加载的内存索引
• #graph: MemoryGraph | undefined — 可选的内存图结构

资料来源：src/store/memory-store.ts:80-85

#### 关键方法

资料来源：src/store/memory-store.ts:200-450

Atomic Write

atomicWrite 模块提供基于 temp file + rename 的原子写入模式，确保在写入过程中发生崩溃或断电时不会产生部分写入的损坏文件。

sequenceDiagram
    participant Caller
    participant AW as atomicWrite
    participant FS as FileSystem
    
    Caller->>AW: atomicWrite(target, data)
    AW->>AW: 生成随机 tmp 文件名<br/>base.16hexchars.tmp
    AW->>FS: 写入 tmp 文件
    AW->>FS: rename(tmp, target)
    Note over FS: rename(2) 原子操作
    AW->>Caller: 完成

#### 安全特性

• 跨文件系统防护：通过比较源目录和临时文件目录的 dev 设备号，拒绝跨文件系统重命名
• 足够熵值：使用 8 字节（16 十六进制字符）随机数生成临时文件名，避免并发写入冲突
• 同目录原则：临时文件与目标文件位于同一目录，确保 rename 操作在同一文件系统内

资料来源：src/store/atomic-write.ts:1-40

Memory 数据模型

每个记忆由一个 Markdown 文件表示，结构如下：

概述

Commonplace 采用双存储架构，支持用户级别（user）和项目级别（project）两套独立的记忆存储。这种设计允许用户在不同的项目中维护各自的上下文，同时在全局层面保留跨项目的个人规则和偏好。

核心价值：

• 持久化反馈：跨项目积累的纠正和学习经验不会因项目切换而丢失
• 项目隔离：每个项目可以拥有独立的架构笔记和约定规则
• 作用域感知：工具调用可精确指定读写目标存储

资料来源：README.md:1-20

架构设计

双存储模型

graph TD
    subgraph 用户存储 ["用户存储 (User Store)"]
        U[~/.commonplace/memory]
        U1[用户类型记忆]
        U2[反馈类型记忆]
    end
    
    subgraph 项目存储 ["项目存储 (Project Store)"]
        P[.commonplace/memory]
        P1[项目类型记忆]
        P2[引用类型记忆]
    end
    
    subgraph MCP工具 ["MCP 工具层"]
        SAVE[memory_save]
        SEARCH[memory_search]
        LIST[memory_list]
        DELETE[memory_delete]
    end
    
    SAVE -->|scope: user| U
    SAVE -->|scope: project| P
    SEARCH -->|跨存储合并| RESULT[按评分排序结果]
    
    style 用户存储 fill:#e1f5fe
    style 项目存储 fill:#fff3e0

记忆类型与存储映射

资料来源：README.md:60-75

作用域检测优先级

项目存储的检测按照以下优先级顺序进行，从高到低：

graph LR
    A["1. COMMONPLACE_PROJECT_DIR 环境变量"] -->|最高优先级| Z[显式覆盖]
    B["2. MCP roots/list 协议"] -->|次高| P1[项目根目录]
    C["3. 当前工作目录 (cwd)"] -->|兜底| P2[自动检测]
    
    style A fill:#ffcdd2
    style Z fill:#c8e6c9

优先级详情

1. 环境变量 COMMONPLACE_PROJECT_DIR：显式覆盖，最高优先级。路径无需预先存在，Commonplace 会自动创建所需的目录结构。
2. MCP roots/list 协议：通过 MCP 协议发现的项目根目录。
3. 当前工作目录：自动检测，将 <cwd>/.commonplace/memory 作为项目存储路径。

资料来源：README.md:140-155

存储目录结构

用户存储

默认路径：~/.commonplace/memory（可通过 COMMONPLACE_USER_DIR 覆盖）

~/.commonplace/memory/
├── feedback_learned_patterns.md
├── feedback_avoid_shrink_scope.md
├── user_preferences.md
└── .embeddings/
    ├── feedback_learned_patterns.embedding
    └── ...

项目存储

项目存储位置取决于检测优先级：

# 方式1: 环境变量
${COMMONPLACE_PROJECT_DIR}/memory/

# 方式2: 项目根目录
<project-root>/.commonplace/memory/

项目存储只在该项目被 Commonplace 加载时才会被初始化和扫描。

资料来源：CLAUDE.md:1-30

工具接口中的作用域参数

所有四个核心工具都接受可选的 scope 参数：

interface ToolArguments {
  name?: string;
  type?: 'user' | 'feedback' | 'project' | 'reference';
  scope?: 'user' | 'project';  // 作用域参数
  query?: string;
  // ... 其他参数
}

作用域行为

graph TD
    subgraph 读取流程
        R1{scope 参数?}
        R2[合并两存储结果]
        R3[仅用户存储]
        R4[仅项目存储]
        
        R1 -->|省略| R2
        R1 -->|user| R3
        R1 -->|project| R4
    end
    
    subgraph 写入流程
        W1{scope 参数?}
        W2[写入用户存储]
        W3[写入项目存储]
        
        W1 -->|省略/空| W2
        W1 -->|project| W3
    end

资料来源：README.md:80-95

搜索结果合并

当 scope 参数省略时，搜索会跨两个存储执行，并通过向量相似度评分合并结果：

interface MemorySearchMatch {
  name: string;
  type: MemoryType;
  description: string;
  body: string;
  score: number;      // 余弦相似度，保留3位小数
  scope: 'user' | 'project';  // 结果来源标识
}

合并规则：

• 按 score 降序排列
• 每个匹配结果携带 scope 标签，标识其来源存储
• 项目存储的结果可能在某些查询中排名更高

资料来源：src/server/handlers.ts:1-50

迁移命令与作用域

commonplace migrate 命令支持跨作用域的记忆迁移：

# 扫描用户存储（默认）
commonplace migrate

# 扫描指定目录
commonplace migrate ~/.commonplace/memory

# 预演模式（不实际写入）
commonplace migrate ~/.commonplace/memory --dry-run

迁移操作类型

资料来源：src/cli/migrate.ts:1-80

环境变量配置

配置示例

# 使用自定义用户存储位置
export COMMONPLACE_USER_DIR=/data/commonplace/memory

# 指定项目存储位置（优先级最高）
export COMMONPLACE_PROJECT_DIR=/workspace/my-project/.commonplace/memory

资料来源：src/index.ts:1-30

开发指南：记忆存储实践

在开发 Commonplace 项目本身时，应遵循以下规则：

graph TD
    subgraph 记忆保存决策
        D1{记忆范围}
        D2[scope: user] --> U1[跨项目规则、偏好]
        D3[scope: project] --> P1[架构笔记、仓库约定]
        
        D1 -->|跨项目教训| D2
        D1 -->|特定代码库| D3
    end
    
    subgraph 禁止事项
        B1[禁止写入 harness 内置路径]
        B2[禁止删除历史记忆]
    end
    
    P1 --> B1

核心原则：

• 通过 mcp__commonplace__memory_save 保存记忆，选择合适的 type
• 通过 mcp__commonplace__memory_search 和 mcp__commonplace__memory_list 召回记忆
• 禁止向 ~/.claude/projects/<slug>/memory/ 写入（使用 Commonplace 产品自身）
• 禁止删除已有的历史记忆

资料来源：CLAUDE.md:20-45

记忆文件格式与作用域

每条记忆存储为独立的 Markdown 文件，带有 YAML frontmatter：

Pitfall Log / 踩坑日志

项目：rickbassham/commonplace

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1232879661 | https://github.com/rickbassham/commonplace | README/documentation is current enough for a first validation pass.

2. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 建议检查：确认是否有离线 demo、mock 数据或可替代服务。
• 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。
• 证据：packet_text.keyword_scan | github_repo:1232879661 | https://github.com/rickbassham/commonplace | matched external service / cloud / webhook / database keyword

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1232879661 | https://github.com/rickbassham/commonplace | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1232879661 | https://github.com/rickbassham/commonplace | no_demo; severity=medium

5. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1232879661 | https://github.com/rickbassham/commonplace | No sandbox install has been executed yet; downstream must verify before user use.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1232879661 | https://github.com/rickbassham/commonplace | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1232879661 | https://github.com/rickbassham/commonplace | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1232879661 | https://github.com/rickbassham/commonplace | release_recency=unknown