---
name: profile-memory
description: >-
  渐进式用户/项目画像系统。两条触发路径：
  （1）被动检测（主路径）——由 AGENTS.md checklist 前置项 A 触发短路扫描，
  命中偏好/项目决策触发词时执行操作 A（总结 + 用户确认 + 写入）。
  （2）显式管理——当用户提到"画像"、"profile"、"查看画像"、"我的偏好"、"项目信息"等时
  执行操作 B（浏览、修改、删除已有条目）。
---

# Profile Memory

渐进式画像系统，被动收集并持久化用户个人特质与项目信息。

## 存储结构

| 文件 | 位置 | 用途 | 注入上下文 |
|------|------|------|-----------|
| user-profile.md | `.opencode/data/profile/` | 个人画像精简版 | 是（每次会话） |
| user-profile-log.md | `.opencode/data/profile/` | 个人画像详细日志 | 否 |
| project-profile.md | `.opencode/data/profile/` | 项目画像精简版 | 是（每次会话） |
| project-profile-log.md | `.opencode/data/profile/` | 项目画像详细日志 | 否 |

精简版 Profile 是 Agent 每次会话的上下文输入，必须极度精简。
详细 Log 保留完整上下文，供用户主动查阅和溯源。

## 锚点 ID 机制

每条画像记录在写入时生成一个**锚点 ID**，格式为 `PR-YYYYMMDD-NN`（如 `PR-20260412-01`），
其中 NN 为当天的序号。

锚点 ID 在精简版和 Log 中保持一致：
- 精简版条目格式：`- 条目内容 <!-- PR-20260412-01 -->`（HTML 注释，不影响可读性）
- Log 条目的 H3 标题：`### [PR-20260412-01] YYYY-MM-DD — 简短标题`

这使得从精简版到 Log 的查找可以通过 Grep 精准定位，无需全文读取 Log。

## 逐级上溯机制

当 Agent 在使用精简版 Profile 作为上下文时，如果某条记录**语义模糊**
（如无法判断偏好的具体适用场景、与当前任务的关系不明确），执行以下查找：

```
1. 从精简版条目中提取锚点 ID（HTML 注释中的 PR-xxx）
2. 在对应的 Log 文件中 Grep 该 ID
   - 找到 → 用 Read 工具读取该 ID 所在行号 ±15 行范围（精准读取，不读全文）
   - Log 中包含原始上下文、来源对话等完整信息，通常足以消除歧义
```

### 上溯原则

- **按需触发**：只有在精简版信息不足以支撑当前判断时才上溯
- **精准读取**：通过 Grep 定位行号 + Read 局部读取，禁止全文读取 Log
- **最小化**：一次上溯通常只涉及 1-2 条记录

## 硬上限

- user-profile.md：不超过 **50 行**
- project-profile.md：不超过 **30 行**
- 每条信息一行，`- ` 开头，措辞客观中立

## 操作 A：被动检测 + 对话结束前确认

### 检测范围

在正常对话中被动检测以下信号（**不主动询问**）：

**个人特质**：
- 审美/设计偏好（"太花哨了"、"我喜欢 minimal"）
- 技术偏好（"以后都用 X"、"我不喜欢 class 写法"）
- 做事风格（"先讨论再动手"、"不要自作主张"）
- 沟通偏好（"给我简短的回答"、"多解释一下原理"）
- 产品理解/思维方式

**项目信息**：
- 项目定位和目标（"这个项目是做 X 的"）
- 技术栈与架构决策
- 设计约定和规范
- 产品方向和目标用户

### 检测原则

- **保守而非激进**：宁可漏记也不误记
- 只记录**持久性**的偏好/特质，忽略一次性的临时需求
- 区分"个人"和"项目"两个维度，分别写入对应 Profile 文件

### 变更分类

检测到的新信息与已有条目的关系分为三类，处理方式不同：

| 类型 | 定义 | 示例 | 提示强度 |
|------|------|------|---------|
| **新增** | 全新维度，无已有条目 | 首次提到审美偏好 | 常规 |
| **演进** | 已有条目的深化、细化或自然发展 | "偏好 React" → "偏好 React + Next.js 全栈" | 常规，展示前后对比 |
| **转向** | 与已有条目方向性矛盾或根本性变化 | "偏好 React" → "想转 Vue"；项目方向从 B2C 转 B2B | **加强提醒**，展示前后对比 |

### 确认流程

```
1. 在对话过程中将检测到的信息在内部缓存，分类为"个人"或"项目"
2. 对每条缓存信息，与已有 Profile 比对，标记变更类型（新增/演进/转向）
3. 当用户的主线任务完成后，统一提出，格式如下：

   "本次对话中我注意到以下可记录的画像信息："

   **个人画像：**
   - [新增][分类] 条目内容
   - [演进][分类] 旧：xxx → 新：yyy
   - [转向][分类] 旧：xxx → 新：yyy ⚠️

   **项目画像：**
   - （同上格式）

   转向类条目额外标注 ⚠️ 并附一句说明：
   "⚠️ 以下条目与已有记录存在方向性变化，请特别关注："

   "是否记录？你可以全部确认、逐条修改或跳过。"

4. 用户确认后执行写入流程
5. 如本次对话未检测到任何画像信息，则不触发此流程
```

### 写入流程

```
1. 根据分类读取对应的精简 Profile 和详细 Log（不存在则用模板创建）
2. 为每条新记录生成锚点 ID：PR-YYYYMMDD-NN（检查 Log 中已有 ID 避免冲突）
3. 按变更类型执行：
   - 新增：在对应分类下追加条目，带锚点 ID 注释
   - 演进：替换对应旧条目为新措辞，沿用旧条目的锚点 ID（或生成新 ID，视变化程度而定）
   - 转向：替换对应旧条目为新措辞，生成新锚点 ID（用户已在确认流程中审核）
4. 写入精简 Profile（条目格式：`- 内容 <!-- PR-xxx -->`）
5. 追加详细 Log（标题格式：`### [PR-xxx] YYYY-MM-DD — 简短标题`），其中：
   - 新增条目：操作记为"新增"
   - 演进条目：操作记为"更新（旧值 → 新值）"
   - 转向条目：操作记为"转向（旧值 → 新值）"，便于溯源重大变化
6. 检查精简 Profile 是否超过硬上限，超过则提醒用户精简
```

## 操作 B：用户主动管理

当用户说"查看我的画像"、"profile"、"查看项目画像"、"我的偏好"等：

```
1. 读取对应的精简 Profile，展示给用户
2. 如用户要看详细版或溯源，读取对应 Log 展示
3. 用户可要求：
   - 删除某条记录（同步删除精简版条目，Log 中标记为已删除）
   - 修改某条记录的措辞
   - 合并/重组分类
   - 新增分类
```

## 操作 C：变更比对与冲突处理

### 比对逻辑

```
对每条新检测到的信息，在同分类下的已有条目中查找语义相近项：
1. 无相近条目 → 标记为"新增"
2. 有相近条目且方向一致（深化/细化/补充） → 标记为"演进"
3. 有相近条目且方向矛盾（替代/转向/否定） → 标记为"转向"
```

### 前后对比格式

演进和转向类条目在确认流程中必须展示前后对比：

```
- [演进][技术偏好] 旧：偏好 React → 新：偏好 React + Next.js 全栈开发
- [转向][产品方向] 旧：面向 C 端个人用户 → 新：转向 B 端企业客户 ⚠️
```

### 用户选择

对每条演进/转向条目，用户可以：
- **确认更新**：用新条目替换旧条目
- **保留两者**：旧条目不动，新条目作为补充追加（适用于不同细分维度）
- **放弃**：不记录本条

## 数据文件模板

首次使用时，如对应文件不存在，按以下模板创建。

### user-profile.md

```markdown
# User Profile

## 审美与设计

## 技术偏好

## 做事风格

## 沟通偏好

## 产品理解
```

### user-profile-log.md

```markdown
# User Profile Log

详细记录每次画像更新的完整上下文，按时间正序追加。

## 记录
```

### project-profile.md

```markdown
# Project Profile

## 项目定位

## 技术栈与架构

## 设计约定

## 产品方向
```

### project-profile-log.md

```markdown
# Project Profile Log

详细记录每次项目画像更新的完整上下文，按时间正序追加。

## 记录
```

### Log 条目格式

每次写入 Log 时，追加以下格式的条目：

```markdown
### [PR-20260412-01] YYYY-MM-DD — 简短标题
- **分类**: 对应的精简 Profile 分类名
- **精简版**: 写入精简 Profile 的那一行内容
- **原始上下文**: 用户原话或对话中的关键语句
- **来源对话**: [对话简述](chat-uuid)
- **操作**: 新增 / 演进（旧值 → 新值）/ 转向（旧值 → 新值）/ 删除
```

## 分类扩展

预设的分类列表可以扩展。当检测到的信息不属于任何现有分类时：

```
1. 在确认流程中标注"建议新增分类: [分类名]"
2. 用户确认后在精简 Profile 中新增该分类的 H2 标题
3. 注意硬上限，新增分类会占用行数
```

## 与其他系统的协作

| 系统 | 关系 | 说明 |
|------|------|------|
| AGENTS.md | 下游消费者 | 每次会话读取精简 Profile 并注入上下文 |
| `epee-orchestrator` Skill | 注册 | 在 registry.md 中注册本 Skill |

## 自迭代日志

本节记录使用本 Skill 过程中发现的必要检查项。

### 已知必要检查

（暂无）