大活
This commit is contained in:
64
.cursor/changelog/changelog-full.md
Normal file
64
.cursor/changelog/changelog-full.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# Dev Changelog — Full
|
||||
|
||||
完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
|
||||
|
||||
## 记录
|
||||
|
||||
### [CL-20260411-1500] 2026-04-11 15:00 — 完成美术 Agent 产品决策和技术选型
|
||||
- **tags**: art-agent, 产品决策, 技术选型, 规划
|
||||
- **affected_files**:
|
||||
- docs/art-agent/DECISIONS.md
|
||||
- docs/art-agent/TECH-STACK.md
|
||||
- **what**: 通过 5 轮结构化讨论确定了美术 Agent 工具的产品决策（产品形态、交互模型、AI 架构、风格管理、资源 Pipeline），并完成全部 8 个维度的技术选型
|
||||
- **why**: 项目从零开始，需要先把产品方向和技术基准定下来再动手写代码
|
||||
- **decisions**:
|
||||
- 产品形态选 Chat-first Web App（排除纯 Bot 和桌面应用）
|
||||
- 前端 Next.js / 后端 Python FastAPI / 自建 Agent Loop（不用 LangChain）
|
||||
- 数据库 PostgreSQL / 图像生成 Replicate / 部署 Vercel + Railway
|
||||
- 对象存储 MVP 先用本地文件系统
|
||||
- **notes**: 技术选型中图像生成 API、部署方案、异步任务三项用户未明确选定，采用了推荐方案
|
||||
|
||||
### [CL-20260411-1600] 2026-04-11 16:00 — 搭建美术 Agent MVP 全部前后端代码
|
||||
- **tags**: art-agent, MVP, 前端, 后端, FastAPI, Next.js, Agent Loop
|
||||
- **affected_files**:
|
||||
- art-agent/README.md
|
||||
- art-agent/backend/requirements.txt
|
||||
- art-agent/backend/.env.example
|
||||
- art-agent/backend/app/main.py
|
||||
- art-agent/backend/app/api/chat.py
|
||||
- art-agent/backend/app/agent/loop.py
|
||||
- art-agent/backend/app/agent/tools.py
|
||||
- art-agent/backend/app/services/image_gen.py
|
||||
- art-agent/frontend/package.json
|
||||
- art-agent/frontend/src/app/page.tsx
|
||||
- art-agent/frontend/src/app/layout.tsx
|
||||
- art-agent/frontend/src/app/globals.css
|
||||
- art-agent/frontend/src/components/chat/chat-messages.tsx
|
||||
- art-agent/frontend/src/components/chat/chat-input.tsx
|
||||
- art-agent/frontend/src/components/chat/image-grid.tsx
|
||||
- art-agent/frontend/src/lib/api.ts
|
||||
- docs/art-agent/MVP-PLAN.md
|
||||
- **what**: 从零创建了完整的 MVP 前后端代码，包括 FastAPI 后端（Agent Loop + Replicate 图像生成 + SSE 流式推送）和 Next.js 前端（Chat UI + 参考图上传 + 图片下载），后端已验证可正常启动
|
||||
- **why**: 以最小流程跑通端到端闭环（对话 → 生图 → 迭代 → 保存），快速暴露集成问题
|
||||
- **decisions**:
|
||||
- MVP 范围刻意砍掉：数据库/持久化、Skill/Rules 机制、风格库、用户认证、云端部署
|
||||
- Agent Loop 硬编码 system prompt，不走 Skill 扩展（最简化）
|
||||
- 图像模型选 flux-schnell（快速版），优先验证流程通畅
|
||||
- OpenAI 客户端延迟初始化，避免无 Key 时模块加载失败
|
||||
- **notes**:
|
||||
- 前端使用 Tailwind CSS v4 + PostCSS 配置方式（非 tailwind.config.ts）
|
||||
- 参考图在 MVP 阶段仅通过 GPT vision 理解风格后融入 prompt，未直接传给图像模型做 img2img
|
||||
|
||||
### [CL-20260411-1630] 2026-04-11 16:30 — 完成开发环境搭建和依赖安装
|
||||
- **tags**: art-agent, 环境搭建, Node.js, Python
|
||||
- **affected_files**:
|
||||
- art-agent/backend/venv/
|
||||
- art-agent/frontend/node_modules/
|
||||
- **what**: 通过 winget 安装 Node.js v24.14.1，创建 Python 虚拟环境并安装后端依赖（9 个包），安装前端 npm 依赖（46 个包），后端启动验证通过
|
||||
- **why**: 代码写好后需要实际运行环境来验证
|
||||
- **decisions**:
|
||||
- Node.js 用 winget 安装 LTS 版本
|
||||
- Python 虚拟环境放在 backend/venv/ 下
|
||||
- **notes**:
|
||||
- 遇到 3 个环境问题已解决：OpenAI 延迟初始化、PowerShell 不支持 &&、脚本执行策略限制
|
||||
- 端到端完整测试待用户配置 API Key 后进行
|
||||
7
.cursor/changelog/changelog-headlines.md
Normal file
7
.cursor/changelog/changelog-headlines.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Dev Changelog — Headlines
|
||||
|
||||
最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
|
||||
|
||||
- [CL-20260411-1630] 安装 Node.js v24.14.1 + Python venv + 前后端依赖，后端启动验证通过
|
||||
- [CL-20260411-1600] 从零创建美术 Agent MVP 全部前后端代码（FastAPI + Next.js + Agent Loop + SSE）
|
||||
- [CL-20260411-1500] 完成美术 Agent 产品决策（5 个核心问题）和技术选型（8 个维度）两份文档
|
||||
19
.cursor/changelog/changelog-recent.md
Normal file
19
.cursor/changelog/changelog-recent.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Dev Changelog — Recent
|
||||
|
||||
最近 ~10 次改动的摘要记录，按时间倒序排列。
|
||||
当 Agent 检测到当前任务与近期改动相关时自动读取。
|
||||
|
||||
### [CL-20260411-1630] 2026-04-11 — 完成开发环境搭建和依赖安装
|
||||
- **tags**: art-agent, 环境搭建, Node.js, Python
|
||||
- **affected_files**: art-agent/backend/venv/, art-agent/frontend/node_modules/
|
||||
- **summary**: 安装 Node.js v24.14.1（winget）、创建 Python venv 并安装后端依赖、安装前端 npm 依赖。后端启动验证通过。遇到并解决了 OpenAI 延迟初始化、PowerShell && 不支持、脚本执行策略限制等问题。
|
||||
|
||||
### [CL-20260411-1600] 2026-04-11 — 搭建美术 Agent MVP 全部前后端代码
|
||||
- **tags**: art-agent, MVP, 前端, 后端, FastAPI, Next.js, Agent Loop
|
||||
- **affected_files**: art-agent/backend/app/*, , art-agent/frontend/src/*, docs/art-agent/MVP-PLAN.md
|
||||
- **summary**: 从零创建完整 MVP：后端 FastAPI（Agent Loop + Replicate 图像生成 + SSE）+ 前端 Next.js（Chat UI + 参考图上传 + 图片下载 + 暗色主题）。范围刻意最小化：无数据库、无 Skill 机制、无用户认证。Agent Loop 硬编码 system prompt，使用 GPT-4o-mini + flux-schnell。
|
||||
|
||||
### [CL-20260411-1500] 2026-04-11 — 完成美术 Agent 产品决策和技术选型
|
||||
- **tags**: art-agent, 产品决策, 技术选型, 规划
|
||||
- **affected_files**: docs/art-agent/DECISIONS.md, docs/art-agent/TECH-STACK.md
|
||||
- **summary**: 5 轮结构化讨论确定产品决策（Chat-first Web App、对话驱动交互、三层风格定义等）。8 维度技术选型：Next.js / FastAPI / 自建 Agent Loop / PostgreSQL / Replicate / Vercel+Railway。DECISIONS.md 和 TECH-STACK.md 两份文档产出。
|
||||
26
.cursor/profile/project-profile-log.md
Normal file
26
.cursor/profile/project-profile-log.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Project Profile Log
|
||||
|
||||
详细记录每次项目画像更新的完整上下文，按时间正序追加。
|
||||
|
||||
## 记录
|
||||
|
||||
### 2026-04-11 — 初始化项目画像
|
||||
- **分类**: 项目定位
|
||||
- **精简版**: 面向游戏美术团队的 AI Agent 工具，通过对话驱动产出美术资源
|
||||
- **原始上下文**: "我希望做一个agent工具方便我们团队的美术更简易便捷地主要通过对话的形式去产出美术资源"
|
||||
- **来源对话**: 初始化会话
|
||||
- **操作**: 新增
|
||||
|
||||
### 2026-04-11 — 初始化项目画像
|
||||
- **分类**: 设计约定
|
||||
- **精简版**: 目标用户是美术人员，交互设计需优先考虑非技术用户的友好度
|
||||
- **原始上下文**: "方便我们团队的美术更简易便捷地"
|
||||
- **来源对话**: 初始化会话
|
||||
- **操作**: 新增
|
||||
|
||||
### 2026-04-11 — 初始化项目画像
|
||||
- **分类**: 产品方向
|
||||
- **精简版**: 当前阶段：平面资源、UI 类资源、交互设计、美术风格；远期：场景、3D 资源
|
||||
- **原始上下文**: "目前可能主要考虑产出平面资源和UI类资源、交互、美术风格等，以后也考虑要产出场景甚至3D资源"
|
||||
- **来源对话**: 初始化会话
|
||||
- **操作**: 新增
|
||||
13
.cursor/profile/project-profile.md
Normal file
13
.cursor/profile/project-profile.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# Project Profile
|
||||
|
||||
## 项目定位
|
||||
- 面向游戏美术团队的 AI Agent 工具，通过对话驱动产出美术资源
|
||||
|
||||
## 技术栈与架构
|
||||
|
||||
## 设计约定
|
||||
- 目标用户是美术人员，交互设计需优先考虑非技术用户的友好度
|
||||
|
||||
## 产品方向
|
||||
- 当前阶段：平面资源、UI 类资源、交互设计、美术风格
|
||||
- 远期规划：场景资源、3D 资源生成
|
||||
48
.cursor/rules/common/changelog-recall.mdc
Normal file
48
.cursor/rules/common/changelog-recall.mdc
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
description: 每次会话开始时注入开发日志概要（L3），并在检测到任务与近期改动相关时自动读取中期记录（L2）
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
## 开发日志上下文注入
|
||||
|
||||
每次会话处理用户第一个任务前，执行以下操作：
|
||||
|
||||
1. 读取 `.cursor/changelog/changelog-headlines.md`（不存在则跳过）
|
||||
2. 如文件存在且有实质内容（不仅是模板头部），将全部条目作为背景知识注入上下文
|
||||
3. 这些信息帮助 Agent 快速建立位置感：项目进展到什么阶段、最近的工作重心在哪个模块
|
||||
4. 在后续回复中自然参考，不显式提及"根据开发日志"
|
||||
|
||||
## L2 自动触发
|
||||
|
||||
Agent 开始处理一个新任务时，判断是否需要读取近期详细记录：
|
||||
|
||||
1. 从当前任务中提取涉及的文件路径和语义关键词
|
||||
2. 与 L3 概要中的内容做快速比对——如果近期有相关模块/文件的改动记录
|
||||
3. 命中时，读取 `.cursor/changelog/changelog-recent.md`，将相关条目纳入上下文
|
||||
4. 匹配策略：
|
||||
- 硬匹配：当前任务涉及的文件出现在 L2 条目的 `affected_files` 中
|
||||
- 软匹配：当前任务的语义关键词与条目的 `tags` 有交集
|
||||
- 任一命中即触发读取
|
||||
|
||||
### 注意
|
||||
|
||||
- L3 注入是低成本操作（~50 句话），每次会话都执行
|
||||
- L2 读取按需触发，只在检测到关联时才读取
|
||||
- 开发日志是事实性记录，直接使用即可，不像画像那样需要"自然融入"的措辞考量
|
||||
- 记录的写入和管理由 `dev-changelog` Skill 负责，本 Rule 只负责读取和注入
|
||||
|
||||
## 逐级上溯
|
||||
|
||||
当 L3 中某条记录的一句话描述**语义模糊**（无法判断具体范围或与当前任务的关系），
|
||||
按以下步骤精准上溯，**禁止全文读取 L1**：
|
||||
|
||||
1. 提取该条目的锚点 ID（`CL-xxx`）
|
||||
2. 用 Grep 在 `changelog-recent.md`（L2）中搜索该 ID → 找到则读取该条目
|
||||
3. 如 L2 中未找到或仍有歧义 → 用 Grep 在 `changelog-full.md`（L1）中搜索该 ID，
|
||||
获取行号后用 Read 工具读取该行号 ±20 行范围
|
||||
4. 一次上溯通常只涉及 1-3 条记录，不批量上溯
|
||||
|
||||
## 被动写入提醒
|
||||
|
||||
Agent 在完成涉及代码/配置文件实质性改动的任务后，应读取 `dev-changelog` Skill
|
||||
并执行其"操作 A：记录写入"流程，静默追加三层记录。
|
||||
@@ -7,10 +7,16 @@ alwaysApply: true
|
||||
|
||||
每次会话处理用户第一个任务前，执行以下操作：
|
||||
|
||||
1. 读取 `~/.cursor/profile/user-profile.md`（不存在则跳过）
|
||||
2. 读取 `.cursor/profile/project-profile.md`（不存在则跳过）
|
||||
3. 如文件存在且有实质内容（非空模板），将其内容作为背景知识纳入考量
|
||||
4. 在后续回复中，Agent 应自然地参考画像信息，无需显式引用
|
||||
1. 读取 `~/.cursor/profile/user-profile.md`（不存在记为 user_missing）
|
||||
2. 读取 `.cursor/profile/project-profile.md`（不存在记为 project_missing）
|
||||
3. **冷启动检测**：如果 user_missing 或 project_missing 为真，在回复开头简要提醒：
|
||||
> 画像系统尚未初始化（缺少：user-profile / project-profile）。
|
||||
> 如需启用画像功能，请说"初始化画像"，我会引导你完成。
|
||||
- 每次会话最多提醒一次，不重复打扰
|
||||
- 如用户回应"初始化画像"，读取 `profile-memory` Skill 并按其模板创建文件，
|
||||
然后引导用户填写基本信息
|
||||
4. 如文件存在且有实质内容（非空模板），将其内容作为背景知识纳入考量
|
||||
5. 在后续回复中，Agent 应自然地参考画像信息，无需显式引用
|
||||
|
||||
### 注意
|
||||
|
||||
@@ -18,6 +24,16 @@ alwaysApply: true
|
||||
- 不要在回复中提及"根据你的画像"之类的措辞，自然融入即可
|
||||
- 画像的记录和管理由 `profile-memory` Skill 负责，本 Rule 只负责读取和注入
|
||||
|
||||
### 逐级上溯
|
||||
|
||||
当精简版 Profile 中某条记录**语义模糊**（无法判断偏好的具体适用场景），
|
||||
按以下步骤精准查找详细 Log，**禁止全文读取 Log 文件**：
|
||||
|
||||
1. 提取该条目的锚点 ID（HTML 注释中的 `PF-xxx`）
|
||||
2. 用 Grep 在对应的 Log 文件中搜索该 ID，获取行号
|
||||
3. 用 Read 工具读取该行号 ±15 行范围，获取原始上下文和来源信息
|
||||
4. 一次上溯通常只涉及 1-2 条记录，不批量上溯
|
||||
|
||||
## 被动检测提醒
|
||||
|
||||
Agent 在整个对话过程中应保持对画像信号的被动感知。
|
||||
|
||||
249
.cursor/skills/dev-changelog/SKILL.md
Normal file
249
.cursor/skills/dev-changelog/SKILL.md
Normal file
@@ -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 过程中发现的必要检查项。
|
||||
|
||||
### 已知必要检查
|
||||
|
||||
（暂无）
|
||||
@@ -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 概要每次会话自动注入上下文
|
||||
|
||||
@@ -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 的那一行内容
|
||||
- **原始上下文**: 用户原话或对话中的关键语句
|
||||
|
||||
Reference in New Issue
Block a user