大活

.cursor/skills/dev-changelog/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: dev-changelog
+description: >-
+  三层开发进程记录系统。在 Agent 完成代码改动后自动记录，提供从一句话概要到完整日志的
+  多级上下文，帮助 Agent 在跨会话场景下保持对项目开发进展的感知。
+  当用户提到"开发日志"、"changelog"、"最近改了什么"、"回顾改动"等时触发。
+---
+
+# Dev Changelog
+
+三层开发进程记录系统，解决 Agent 跨会话的上下文断裂问题。
+
+## 三层架构
+
+| 层级 | 文件 | 信息密度 | 条目数量 | 注入方式 |
+|------|------|---------|---------|---------|
+| L1 完整版 | `changelog-full.md` | 高（5-15 行/条） | 无上限，只追加 | 用户手动唤醒 |
+| L2 中期版 | `changelog-recent.md` | 中（3-5 行/条） | 滚动窗口 ~10 条 | 检测到关联时自动读取 |
+| L3 概要版 | `changelog-headlines.md` | 低（1 行/条） | 滚动窗口 ~50 条 | 每次会话自动注入 |
+
+所有数据文件存放在 `.cursor/changelog/` 目录下。
+
+## 锚点 ID 机制
+
+每条记录在写入时生成一个**锚点 ID**，格式为 `CL-YYYYMMDD-HHMM`（如 `CL-20260412-1430`）。
+同一分钟内有多条时追加字母后缀（`CL-20260412-1430a`、`CL-20260412-1430b`）。
+
+锚点 ID 在三层文件中保持一致，用于跨层精准定位：
+- L3 一句话条目以 `[CL-xxx]` 开头
+- L2 摘要条目的 H3 标题包含 `[CL-xxx]`
+- L1 完整条目的 H3 标题包含 `[CL-xxx]`
+
+这使得从 L3 → L2 → L1 的逐级查找可以通过 Grep 精准定位，无需全文读取。
+
+## 逐级上溯机制
+
+当 Agent 在使用 L3 概要作为上下文时，如果某条记录的一句话描述**语义模糊**
+（如无法判断改动的具体范围、与当前任务的关系不明确），执行以下逐级查找：
+
+```
+1. 从 L3 条目中提取锚点 ID（如 CL-20260412-1430）
+2. 在 changelog-recent.md（L2）中 Grep 该 ID
+   - 找到 → 读取该条目的 3-5 行摘要，通常足以消除歧义
+   - 未找到（已滚出 L2 窗口）→ 进入步骤 3
+3. 在 changelog-full.md（L1）中 Grep 该 ID
+   - 找到 → 用 Read 工具读取该 ID 所在行号 ±20 行范围（精准读取，不读全文）
+   - 未找到 → 放弃上溯，该条目上下文不可用
+```
+
+### 上溯原则
+
+- **按需触发**：只有在 L3 信息不足以支撑当前任务判断时才上溯，不预防性地批量读取
+- **精准读取**：对 L1 的访问必须通过 Grep 定位行号 + Read 局部读取，禁止全文读取
+- **最小化**：一次上溯通常只涉及 1-3 条记录，不批量上溯
+
+## 操作 A：记录写入（核心流程）
+
+### 触发条件
+
+Agent 完成了一个涉及**代码或配置文件实质性改动**的任务后，自动触发。
+
+以下情况**不触发**：
+- 纯对话讨论、方案设计、问题解答（无文件改动）
+- 只读操作（查看文件、搜索代码）
+- 只改动了 `.cursor/` 目录下的基础设施文件（如画像、延期方案、changelog 自身）
+
+### 写入流程
+
+```
+1. 生成锚点 ID：CL-YYYYMMDD-HHMM（检查是否与已有 ID 冲突，冲突则追加字母后缀）
+
+2. 从刚完成的任务中提取以下信息：
+   - 做了什么（what）：一句话概括
+   - 为什么这样做（why）：动机和背景
+   - 改了哪里（where）：受影响的文件/模块列表
+   - 关键决策（decisions）：如果有方案选择，记录选了什么、放弃了什么
+   - 注意事项（notes）：后续可能受影响的地方、已知限制等
+
+3. 生成三层内容（共享同一个锚点 ID）：
+   - L1 完整条目（包含以上全部信息）
+   - L2 摘要条目（what + why + where，3-5 行）
+   - L3 一句话（what，不超过 80 字）
+
+4. 写入三个文件（按以下顺序）：
+   a. 读取 changelog-full.md，在 "## 记录" 下方追加 L1 条目
+   b. 读取 changelog-recent.md，在顶部插入 L2 条目，如超过 10 条则移除最旧的
+   c. 读取 changelog-headlines.md，在顶部插入 L3 条目，如超过 50 条则移除最旧的
+
+5. 在回复末尾附一行提示："[已记录到开发日志]"
+```
+
+### 静默写入原则
+
+- **不需要用户确认**——Agent 自己做的改动，对"做了什么"的认知是一手的
+- 用户如果觉得记录不准确，可通过操作 D 修改或删除
+- 回滚操作也要记录（"回退了 XX 改动"），真实反映开发过程
+
+## 操作 B：L2 自动触发读取
+
+### 触发条件
+
+由 `changelog-recall.mdc` Rule 调度。当 Agent 开始处理一个新任务时，判断该任务是否
+与近期改动相关。
+
+### 匹配策略（文件 + 标签双匹配）
+
+```
+1. 从当前任务中提取：
+   - 涉及的文件路径
+   - 语义关键词（模块名、功能领域等）
+
+2. 读取 changelog-recent.md，逐条检查：
+   - 硬匹配：当前任务涉及的文件出现在条目的 affected_files 中
+   - 软匹配：当前任务的语义关键词与条目的 tags 有交集
+
+3. 任一匹配命中 → 将匹配到的 L2 条目作为上下文纳入考量
+4. 在回复中自然融入，不显式提及"根据开发日志"
+```
+
+## 操作 C：L1 手动检索
+
+### 触发条件
+
+用户主动要求回顾完整改动记录时触发。典型话语：
+- "回顾一下最近的改动"
+- "XX 模块之前改过什么"
+- "查看开发日志"
+- "changelog"
+
+### 流程
+
+```
+1. 读取 changelog-full.md
+2. 根据用户需求过滤：
+   - 按时间范围
+   - 按模块/文件
+   - 按 tags
+3. 展示匹配的条目摘要表，用户可以进一步查看某条的完整内容
+```
+
+## 操作 D：记录管理
+
+用户可以对已有记录进行管理：
+
+| 操作 | 说明 |
+|------|------|
+| 删除 | 从三层文件中同步移除对应条目 |
+| 修改 | 修改某条记录的描述（三层同步更新） |
+| 清理 | 手动触发 L1 的归档（如按月分文件，暂不实现，作为演进方向） |
+
+## 条目格式
+
+### L1 完整条目
+
+```markdown
+### [CL-20260412-1430] YYYY-MM-DD HH:MM — 一句话标题
+- **tags**: tag1, tag2, tag3
+- **affected_files**:
+  - path/to/file1
+  - path/to/file2
+- **what**: 做了什么的简要描述
+- **why**: 动机和背景
+- **decisions**: 选择了 A 方案（放弃了 B 因为 xxx）
+- **notes**: 后续注意事项
+- **source_chat**: [对话简述](chat-uuid)
+```
+
+### L2 摘要条目
+
+```markdown
+### [CL-20260412-1430] YYYY-MM-DD — 一句话标题
+- **tags**: tag1, tag2, tag3
+- **affected_files**: file1, file2
+- **summary**: 做了什么 + 为什么（3-5 行）
+```
+
+### L3 一句话条目
+
+```markdown
+- [CL-20260412-1430] 一句话描述改动内容（不超过 80 字）
+```
+
+## 滚动窗口维护
+
+### L2 窗口（~10 条）
+
+```
+写入新条目后，检查总条目数：
+- <= 10 条：不做处理
+- > 10 条：移除文件底部（最旧的）条目，直到恰好 10 条
+```
+
+### L3 窗口（~50 条）
+
+```
+写入新条目后，检查总行数（排除文件头部的标题和说明）：
+- <= 50 条：不做处理
+- > 50 条：移除文件底部（最旧的）条目，直到恰好 50 条
+```
+
+被移除的条目不需要额外归档——L1 完整版保留了所有历史。
+
+## 数据文件模板
+
+首次写入时，如对应文件不存在，按以下模板创建。
+
+### changelog-full.md
+
+```markdown
+# Dev Changelog — Full
+
+完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
+
+## 记录
+```
+
+### changelog-recent.md
+
+```markdown
+# Dev Changelog — Recent
+
+最近 ~10 次改动的摘要记录，按时间倒序排列。
+当 Agent 检测到当前任务与近期改动相关时自动读取。
+```
+
+### changelog-headlines.md
+
+```markdown
+# Dev Changelog — Headlines
+
+最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
+```
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `changelog-recall` Rule | 下游消费者 | 每次会话注入 L3，自动触发 L2 读取 |
+| `deferred-decisions` Skill | 互补 | deferred 记"没做什么"，changelog 记"做了什么" |
+| `profile-memory` Skill | 结构对称 | profile 是"是什么"，changelog 是"做了什么" |
+| `epee-orchestrator` | 注册 | 在 registry.md 中注册本 Skill |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+（暂无）

.cursor/skills/epee-orchestrator/registry.md

@@ -32,3 +32,11 @@
 - **输出**: ~/.cursor/profile/user-profile.md、.cursor/profile/project-profile.md 及对应 log 文件
 - **路径**: .cursor/skills/profile-memory/SKILL.md
 - **备注**: 被动检测由 profile-recall Rule 触发；精简 Profile 每次会话自动注入上下文
+
+### dev-changelog
+- **类型**: 基础设施
+- **能力**: 三层开发进程记录系统，Agent 完成代码改动后自动记录，提供一句话概要到完整日志的多级上下文
+- **触发场景**: "开发日志"、"changelog"、"最近改了什么"、"回顾改动"、"查看开发记录"、代码改动后自动写入
+- **输出**: .cursor/changelog/ 下的 changelog-full.md、changelog-recent.md、changelog-headlines.md
+- **路径**: .cursor/skills/dev-changelog/SKILL.md
+- **备注**: 写入由 changelog-recall Rule 的被动写入提醒触发；L3 概要每次会话自动注入上下文

.cursor/skills/profile-memory/SKILL.md

@@ -22,6 +22,35 @@ description: >-
 精简版 Profile 是 Agent 每次会话的上下文输入，必须极度精简。
 详细 Log 保留完整上下文，供用户主动查阅和溯源。
 
+## 锚点 ID 机制
+
+每条画像记录在写入时生成一个**锚点 ID**，格式为 `PF-YYYYMMDD-NN`（如 `PF-20260412-01`），
+其中 NN 为当天的序号。
+
+锚点 ID 在精简版和 Log 中保持一致：
+- 精简版条目格式：`- 条目内容 <!-- PF-20260412-01 -->`（HTML 注释，不影响可读性）
+- Log 条目的 H3 标题：`### [PF-20260412-01] YYYY-MM-DD — 简短标题`
+
+这使得从精简版到 Log 的查找可以通过 Grep 精准定位，无需全文读取 Log。
+
+## 逐级上溯机制
+
+当 Agent 在使用精简版 Profile 作为上下文时，如果某条记录**语义模糊**
+（如无法判断偏好的具体适用场景、与当前任务的关系不明确），执行以下查找：
+
+```
+1. 从精简版条目中提取锚点 ID（HTML 注释中的 PF-xxx）
+2. 在对应的 Log 文件中 Grep 该 ID
+   - 找到 → 用 Read 工具读取该 ID 所在行号 ±15 行范围（精准读取，不读全文）
+   - Log 中包含原始上下文、来源对话等完整信息，通常足以消除歧义
+```
+
+### 上溯原则
+
+- **按需触发**：只有在精简版信息不足以支撑当前判断时才上溯
+- **精准读取**：通过 Grep 定位行号 + Read 局部读取，禁止全文读取 Log
+- **最小化**：一次上溯通常只涉及 1-2 条记录
+
 ## 硬上限
 
 - user-profile.md：不超过 **50 行**
@@ -93,16 +122,17 @@ description: >-
 
 ```
 1. 读取对应的精简 Profile 和详细 Log（不存在则用模板创建）
-2. 按变更类型执行：
-   - 新增：在对应分类下追加条目
-   - 演进：替换对应旧条目为新措辞
-   - 转向：替换对应旧条目为新措辞（用户已在确认流程中审核）
-3. 写入精简 Profile
-4. 追加详细 Log，其中：
+2. 为每条新记录生成锚点 ID：PF-YYYYMMDD-NN（检查 Log 中已有 ID 避免冲突）
+3. 按变更类型执行：
+   - 新增：在对应分类下追加条目，带锚点 ID 注释
+   - 演进：替换对应旧条目为新措辞，沿用旧条目的锚点 ID（或生成新 ID，视变化程度而定）
+   - 转向：替换对应旧条目为新措辞，生成新锚点 ID（用户已在确认流程中审核）
+4. 写入精简 Profile（条目格式：`- 内容 <!-- PF-xxx -->`）
+5. 追加详细 Log（标题格式：`### [PF-xxx] YYYY-MM-DD — 简短标题`），其中：
    - 新增条目：操作记为"新增"
    - 演进条目：操作记为"更新（旧值 → 新值）"
    - 转向条目：操作记为"转向（旧值 → 新值）"，便于溯源重大变化
-5. 检查精简 Profile 是否超过硬上限，超过则提醒用户精简
+6. 检查精简 Profile 是否超过硬上限，超过则提醒用户精简
 ```
 
 ## 操作 B：用户主动管理
@@ -205,7 +235,7 @@ description: >-
 每次写入 Log 时，追加以下格式的条目：
 
 ```markdown
-### YYYY-MM-DD — 简短标题
+### [PF-20260412-01] YYYY-MM-DD — 简短标题
 - **分类**: 对应的精简 Profile 分类名
 - **精简版**: 写入精简 Profile 的那一行内容
 - **原始上下文**: 用户原话或对话中的关键语句