chore: sync before memory update
This commit is contained in:
SkyJourney
@@ -0,0 +1,217 @@
|
||||
---
|
||||
name: memory-lint
|
||||
description: 检查本地记忆文件的健康状况。AUTO-FIX类问题直接修改本地文件，NEED-HUMAN类问题写入lint_report.md。以本地.claude/memory/为唯一权威，不推送远程。可独立执行，也作为/memory-sync流程的一部分。调用命令: /memory-lint
|
||||
---
|
||||
|
||||
# memory-lint
|
||||
|
||||
健康检查 `.claude/memory/`：AUTO-FIX 直修，NEED-HUMAN 写入 `lint_report.md`。**本地权威，不推送远程**。会话目录 = `$PROJECT_DIR`。
|
||||
|
||||
目录不存在 → 输出 `⚠ 未找到 .claude/memory/，建议先执行 /memory-sync` 并终止。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — 读取状态
|
||||
|
||||
```bash
|
||||
cat "$PROJECT_DIR/.claude/memory/MEMORY.md"
|
||||
ls "$PROJECT_DIR/.claude/memory/"*.md
|
||||
```
|
||||
|
||||
提取 `$INDEX_FILES`（索引中的 `[filename.md]`）/ `$DISK_FILES`（磁盘文件）/ `$ANCHOR_COMMIT` / `$LAST_SYNCED`。
|
||||
|
||||
---
|
||||
|
||||
## Phase 1-2 — 孤儿与幽灵检测
|
||||
|
||||
| Phase | 定义 | 级别 | AUTO-FIX |
|
||||
|-------|------|------|---------|
|
||||
| 1 孤儿 | 索引有 → 磁盘无 | ERROR | 从 MEMORY.md 删该条目 |
|
||||
| 2 幽灵 | 磁盘有 → 索引无（排除 MEMORY.md / lint_report.md） | WARN | 补入索引（类型推断见下） |
|
||||
|
||||
幽灵类型推断：`user_*` → user / `project_*` 或 `decisions.md` → project / `feedback*` → feedback / `reference*` → reference / `synthesis_*` → synthesis / 其他默认 project。
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — 交叉引用完整性
|
||||
|
||||
### 3A 存在性检测 + 引用计数构建
|
||||
|
||||
扫描所有 `[[filename.md#section]]`，构建：
|
||||
- **引用表** `源文件#源章节 → 目标文件#目标章节`
|
||||
- **`$REF_COUNT`**：文件级被引用计数（按源文件去重，不含自引用）→ Phase 7 写入 MEMORY.md「引用」列
|
||||
- **`$ITEM_REF_COUNT`**：`decisions.md` / `feedback*.md` 中每个 `## 条目`的被引用计数（按源文件去重）→ Phase 8 写入 lint_report.md，供 `/memory-update` 反向触发消费
|
||||
|
||||
| 情况 | 级别 | 动作 |
|
||||
|------|------|-----|
|
||||
| 目标文件不存在 | ERROR | NEED-HUMAN |
|
||||
| 章节缺失 + 高相似度匹配（疑似重命名） | WARN | AUTO-FIX 更新引用 |
|
||||
| 章节缺失 + 无相似项 | WARN | NEED-HUMAN |
|
||||
|
||||
### 3B 对称性检测（双链闭环）
|
||||
|
||||
复用 3A 引用表，对每条 `A#α → B#β` 检查 B 的 `## β` 是否含任意 `[[A` 引用（不要求精确章节）。
|
||||
|
||||
- 级别：WARN
|
||||
- AUTO-FIX：B 的目标章节末尾追加 `**See Also：** [[A#α]]`
|
||||
- 边界：`lint_report.md` 不参与；B 整文件无对 A 任何引用 → AUTO-FIX；B 有引用但不在目标章节 → 仅 WARN 不自动修改
|
||||
|
||||
---
|
||||
|
||||
## Phase 4-6 — NEED-HUMAN 检测族
|
||||
|
||||
三类全部为 NEED-HUMAN，写入 lint_report.md 时**必须附带 3 问 yes/no checklist + 决策矩阵**（Phase 8 模板）。
|
||||
|
||||
### Phase 4 内容矛盾
|
||||
|
||||
| 维度 | 检查 |
|
||||
|------|------|
|
||||
| decisions vs feedback | 决策与规范逻辑冲突 |
|
||||
| decisions vs 架构文件 | 与 pom.xml / package.json / requirements.txt 实际依赖不一致 |
|
||||
| 多 feedback 文件 | feedback.md 与 feedback_{topic}.md 重复或矛盾 |
|
||||
| synthesis vs decisions | synthesis 结论与决策抵触 |
|
||||
|
||||
```bash
|
||||
cat "$PROJECT_DIR/pom.xml" || cat "$PROJECT_DIR/package.json" || cat "$PROJECT_DIR/requirements.txt"
|
||||
```
|
||||
|
||||
### Phase 5 过期检测
|
||||
|
||||
阈值：WARN ≥30 天 / ERROR ≥90 天（可由 MEMORY.md 头部 `<!-- lint-stale-warn: N -->` 覆盖）。
|
||||
|
||||
```bash
|
||||
git -C "$PROJECT_DIR" log --oneline --since="$last_updated" -- .
|
||||
```
|
||||
|
||||
### Phase 6 可推断内容污染
|
||||
|
||||
污染特征：大量文件路径、git 流水账、方法签名/SQL、可从依赖文件直读的版本号列表。
|
||||
|
||||
**边界（关键）**：架构层级（"认证模块在 auth/，提供 JWT + OAuth2 双协议"）**保留**；具体类名/方法/路径列表（`AuthFilter.java`）**删除**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — 执行 AUTO-FIX
|
||||
|
||||
按顺序修改本地文件：
|
||||
1. MEMORY.md 移除孤儿（Phase 1）
|
||||
2. MEMORY.md 补入幽灵（Phase 2）
|
||||
3. 更新断链引用（Phase 3A 重命名匹配）
|
||||
4. 追加反向链接（Phase 3B）
|
||||
5. **刷新 MEMORY.md 索引「引用」列**（基于 `$REF_COUNT`）：
|
||||
- 表格统一 5 列：`| 文件 | 描述 | 类型 | 引用 | Commit |`
|
||||
- 「引用」值 ≥3 加 `*`（如 `5*`）、<3 显示数字（如 `2`、`0`）
|
||||
- **按引用次数倒序排列**（同次数按类型序：user → project → feedback → reference → synthesis → lint）
|
||||
- 旧版 `## 核心枢纽节点` 段落自动删除（已合并到主表）
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — 生成 lint_report.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: 记忆健康检查报告
|
||||
description: memory-lint 最新一次执行的检查结果与待处理项
|
||||
type: lint
|
||||
last_updated: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# 记忆健康检查报告
|
||||
|
||||
> _执行时间: YYYY-MM-DD | Base commit: `HASH` | Last synced: DATE_
|
||||
|
||||
## 健康概览
|
||||
|
||||
| 检查项 | AUTO-FIX | NEED-HUMAN |
|
||||
|--------|---------|-----------|
|
||||
| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | N / N / N / N | — / — / N / N |
|
||||
| 4 矛盾 / 5 过期 / 6 污染 | — | N / N / N |
|
||||
|
||||
**AUTO-FIX 已执行 N 项 | NEED-HUMAN 待处理 N 项**
|
||||
|
||||
---
|
||||
|
||||
## AUTO-FIX 已执行清单
|
||||
|
||||
- [x] 移除孤儿：`synthesis_xxx.md`
|
||||
- [x] 补入幽灵：`feedback_api.md`（feedback）
|
||||
- [x] 更新断链：`[[feedback.md#API 认证规范]]` → `[[feedback.md#API 鉴权约束]]`
|
||||
- [x] MEMORY.md「引用」列已刷新（22 文件，倒序）
|
||||
|
||||
---
|
||||
|
||||
## 条目级高频引用 Top（供 /memory-update 消费）
|
||||
|
||||
跨 ≥3 个不同源文件被引用的 decisions/feedback 条目。无候选时保留标题 + "无候选"。
|
||||
|
||||
| 条目 | 跨文件次数 | 建议 |
|
||||
|------|----------|------|
|
||||
| `architecture_decisions.md#动态API normalizeParams 类型转型` | 4 | 升级为 synthesis_arch_dynamic_api.md |
|
||||
| `feedback_code_quality.md#JWT 密钥安全` | 3 | 升级为 synthesis_security_jwt.md |
|
||||
|
||||
---
|
||||
|
||||
## NEED-HUMAN 待处理清单
|
||||
|
||||
每项附 3 问 yes/no checklist + 决策矩阵，避免模糊判断。
|
||||
|
||||
### [ERROR] 引用断链 — 目标文件不存在
|
||||
|
||||
- **位置**：`decisions.md → ## 数据库选型` → `[[synthesis_arch_xxx.md]]`
|
||||
- **Checklist**：
|
||||
- Q1：内容是否真实归档过？
|
||||
- Q2：git history 能否找到删除/重命名证据？
|
||||
- Q3：该引用是「锦上添花」还是「核心支撑」？
|
||||
- **矩阵**：Q1+Q2 = 是 → 恢复文件；Q1 是 + Q2 否 → 重新归档；Q1 否 → 删引用；Q3 核心 → 必须二选一不允许保留断链
|
||||
|
||||
### [WARN] 内容矛盾 — 跨文件表述冲突
|
||||
|
||||
- **A**：`decisions.md → ## 数据库选型` PostgreSQL（last_updated: 2026-04-22）
|
||||
- **B**：`project_overview.md → ## 技术栈` MySQL 8.0（last_updated: 2026-02-10）
|
||||
- **Checklist**：
|
||||
- Q1：当前代码/配置（pom.xml / docker-compose）实际指向？
|
||||
- Q2：另一方是「计划未实施」还是「过时记录」？
|
||||
- Q3：近 30 天 git log 有迁移提交？
|
||||
- **矩阵**：Q1 答案 = 当前权威；Q2 过时 → 直接更新另一方；Q2 计划 → 末尾标 `**Status:** planned, target HASH`；Q3 有迁移 → 用迁移时间反推
|
||||
|
||||
### [WARN] 过期记忆 — last_updated 超阈值
|
||||
|
||||
- **文件**：`project_progress.md`（last_updated: 2026-01-15，过期 86 天）
|
||||
- **Checklist**：
|
||||
- Q1：覆盖领域近 90 天有里程碑变更？
|
||||
- Q2：现有内容是否仍可指导决策？
|
||||
- Q3：是否有继任 synthesis_* 已分担其职责？
|
||||
- **矩阵**：Q1 是 + Q2 否 → 触发 `/memory-update`；Q2 是（仅日期老）→ 仅刷新 `last_updated`；Q3 是 → 归档/删除，索引指向继任者
|
||||
|
||||
### [WARN] 可推断内容污染 — 疑似从代码可 grep 的明细
|
||||
|
||||
- **文件**：`project_overview.md` 第 N 行（疑似具体类/路径列表）
|
||||
- **Checklist**：
|
||||
- Q1：能否通过 grep / find / git log 直接还原？
|
||||
- Q2：删除后剩余内容是否仍清晰描述「为什么/约束/边界」？
|
||||
- Q3：是否承载 git history 抓不到的语义？（如「曾选 A 后改 B 因 X」）
|
||||
- **矩阵**：Q1+Q2 = 是 + Q3 否 → 安全删除；Q3 是 → 改写为决策格式迁到 decisions.md（保留 Why）；Q2 否 → 保留架构层级描述但删具体路径
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — 输出摘要
|
||||
|
||||
被 `/memory-sync` 调用：
|
||||
```
|
||||
🔍 memory-lint：AUTO-FIX N 项，NEED-HUMAN N 项（详见 lint_report.md）
|
||||
```
|
||||
|
||||
独立调用：扩展输出已修复 / 待处理清单 + 报告路径；全通过则 `✅ 记忆体系健康，已更新执行时间`。
|
||||
|
||||
每次执行必须更新 lint_report.md（即使全通过也刷新执行时间）。
|
||||
|
||||
---
|
||||
|
||||
## 执行约束
|
||||
|
||||
1. **AUTO-FIX 边界严格** — 只修结构性错误（孤儿、幽灵、断链、双链），不改业务内容
|
||||
2. **NEED-HUMAN 完整记录** — 每项含 checklist + 决策矩阵
|
||||
3. **矛盾检测宁缺勿滥** — 措辞不一致 ≠ 矛盾，宁漏报不误报
|
||||
4. **污染检测边界**（重申）— 架构层级保留 / 具体类名路径删除
|
||||
5. **被调用静默返回** — `/memory-sync` 内 Phase 9 不输出收尾
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: memory-sync
|
||||
description: 项目记忆体系完整同步。Git检查→远程补充本地→增量更新记忆文件→lint收敛→CLAUDE.md注入→本地权威推送远程。以本地.claude/memory/为唯一权威基准。调用命令: /memory-sync
|
||||
---
|
||||
|
||||
# memory-sync
|
||||
|
||||
记忆体系完整同步周期。**本地 `.claude/memory/` 是唯一权威**，远程为镜像。会话目录 = `$PROJECT_DIR`。
|
||||
|
||||
```
|
||||
Phase 0-4 前置（git + 锚点 + 远程→本地补充 + 多机检测 + diff）
|
||||
Phase 5 /memory-update（本地写入）
|
||||
Phase 6 /memory-lint（收敛）
|
||||
Phase 7-9 CLAUDE.md 维护与记忆引导区块注入
|
||||
Phase 10 本地 → 远程权威推送
|
||||
Phase 11 完成报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Git 检查
|
||||
|
||||
```bash
|
||||
git -C "$PROJECT_DIR" status --short
|
||||
```
|
||||
|
||||
- 有未提交变更 → 展示文件、询问 commit message（默认 `chore: sync before memory update`）→ `git add .claude/memory/ && git commit -m "<msg>"` → 记新 hash
|
||||
- 干净 → `git rev-parse --short HEAD` → `$HEAD_HASH`
|
||||
- 非 git 仓库 → 跳过 Phase 0，commit 字段填 `N/A`
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — 远程路径
|
||||
|
||||
```
|
||||
$REMOTE_MEMORY = ~/.claude/projects/{PROJECT_KEY}/memory/
|
||||
PROJECT_KEY = $PROJECT_DIR 中所有 `:` `\` `/` 替换为 `-`
|
||||
例：C:\Users\skyji\work\api → C--Users-skyji-work-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — 本地目录初始化
|
||||
|
||||
```bash
|
||||
ls "$PROJECT_DIR/.claude/memory/" 2>/dev/null
|
||||
```
|
||||
|
||||
- 不存在 → `mkdir -p` 后跳到 Phase 3（全量从远程拉，跳过差量）
|
||||
- 存在 → 提取 `MEMORY.md` 头部 `Base commit: \`HASH\`` → `$ANCHOR_COMMIT`（无则空 = 全量）
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — 远程 → 本地（只补不覆）
|
||||
|
||||
```bash
|
||||
for f in ~/.claude/projects/{PROJECT_KEY}/memory/*.md; do
|
||||
fn=$(basename "$f"); local="$PROJECT_DIR/.claude/memory/$fn"
|
||||
[ ! -f "$local" ] && cp -p "$f" "$local"
|
||||
done
|
||||
```
|
||||
|
||||
### 多机不同步检测
|
||||
|
||||
两边都存在的文件，对比 mtime：
|
||||
|
||||
```bash
|
||||
for f in ~/.claude/projects/{PROJECT_KEY}/memory/*.md; do
|
||||
local="$PROJECT_DIR/.claude/memory/$(basename "$f")"
|
||||
[ ! -f "$local" ] && continue
|
||||
rm=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f")
|
||||
lm=$(stat -c %Y "$local" 2>/dev/null || stat -f %m "$local")
|
||||
diff_days=$(( (rm - lm) / 86400 ))
|
||||
[ $diff_days -ge 7 ] && echo "⚠ $(basename "$f") 远程比本地新 $diff_days 天"
|
||||
done
|
||||
```
|
||||
|
||||
≥1 个警告 → 提示 `检测到 N 个文件远程比本地新 ≥7 天，可能多机不同步。继续？(y/n)`。
|
||||
- `n` → 终止整个 sync 流程
|
||||
- `y` → 继续（Phase 10 仍按本地权威覆盖远程）
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — diff 范围
|
||||
|
||||
```bash
|
||||
[ -n "$ANCHOR_COMMIT" ] && git diff --name-only $ANCHOR_COMMIT..HEAD # → $CHANGED_FILES
|
||||
```
|
||||
|
||||
空锚点 → `$CHANGED_FILES = 全量`。
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — 执行 /memory-update
|
||||
|
||||
按 git diff 增量更新记忆文件 + MEMORY.md 索引。**完成立即继续 Phase 6，不暂停不收尾**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — 执行 /memory-lint
|
||||
|
||||
全量健康检查：AUTO-FIX 直修，NEED-HUMAN 写 `lint_report.md`。**完成立即继续 Phase 7，不暂停不收尾**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — CLAUDE.md 新建（若不存在）
|
||||
|
||||
执行 `/init` → 文件顶部加 `<!-- Last updated: YYYY-MM-DD | Commit: HASH -->` → 跳到 Phase 9。**简体中文，仅命令/代码保留原文**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — CLAUDE.md 增量更新（若已存在）
|
||||
|
||||
1. 提取顶部 `<!-- Last updated: ... | Commit: HASH -->` 的 HASH → `$CLAUDE_MD_COMMIT`
|
||||
2. `git diff $CLAUDE_MD_COMMIT..HEAD -- .`
|
||||
3. 按 diff 内容针对性修改章节（技术栈/模块/命令变化等），不重写全文
|
||||
4. 更新顶部元数据日期与 commit
|
||||
|
||||
**简体中文，仅命令/代码保留原文**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — 记忆引导区块注入
|
||||
|
||||
读 `MEMORY.md` 索引，按以下骨架生成区块（动态填充清单）；CLAUDE.md 已含 `## 记忆体系（会话启动必读）` → 整块替换，否则追加末尾。
|
||||
|
||||
```markdown
|
||||
## 记忆体系（会话启动必读）
|
||||
|
||||
> 每次新会话或长会话压缩后，必须先读 `MEMORY.md` 索引再按需加载文件。代码与记忆冲突 → 以代码为准并更新记忆。
|
||||
|
||||
### 读取流程
|
||||
1. `cat .claude/memory/MEMORY.md` 获取清单
|
||||
2. **必读**（type=`project`/`feedback`）：decisions.md / feedback.md / project_progress.md（按 MEMORY.md 实际动态生成）
|
||||
3. **按需**（type=`user`/`reference`/`synthesis`/`lint`）：架构讨论时读 project_overview.md / 个性化时读 user_profile.md / 外部集成读 reference.md / 特定主题读 feedback_{topic}.md / 技术决策读 synthesis_*.md
|
||||
|
||||
### 记忆目录骨架
|
||||
.claude/memory/
|
||||
├── MEMORY.md / decisions.md / feedback*.md / project_*.md / reference.md
|
||||
├── user_profile.md
|
||||
├── synthesis_*.md（按需）
|
||||
└── lint_report.md（按需）
|
||||
```
|
||||
|
||||
**动态调整**：从 MEMORY.md 表格筛 `project`/`feedback` → 必读；`user`/`reference`/`synthesis`/`lint` → 按需。区块清单必须与索引严格一致。
|
||||
|
||||
---
|
||||
|
||||
## Phase 10 — 本地 → 远程推送（权威覆盖）
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.claude/projects/{PROJECT_KEY}/memory/
|
||||
cp -pf "$PROJECT_DIR/.claude/memory/"*.md ~/.claude/projects/{PROJECT_KEY}/memory/
|
||||
```
|
||||
|
||||
统一推送 update + lint 的全部本地结果。
|
||||
|
||||
---
|
||||
|
||||
## Phase 11 — 完成报告
|
||||
|
||||
```
|
||||
✓ memory-sync 完成
|
||||
|
||||
📋 CLAUDE.md [已更新 / 已新建 / 无变更]
|
||||
📖 记忆引导区块 [已注入 / 已刷新 / 无变更]
|
||||
|
||||
🧠 memory-update：N 个文件已更新（commit HASH）
|
||||
🔍 memory-lint：AUTO-FIX N 项 / NEED-HUMAN N 项（详见 lint_report.md）
|
||||
|
||||
🌟 核心枢纽节点（被引用 ≥3 次的 Top3，源：MEMORY.md「引用」列）：
|
||||
- architecture_decisions.md (5*)
|
||||
- dev_workflow.md (4*)
|
||||
|
||||
📊 高频引用条目候选 synthesis 升级（源：lint_report.md「条目级高频引用 Top」；本段是聚合）：
|
||||
- architecture_decisions.md#动态API normalizeParams 类型转型 (跨 4 文件)
|
||||
|
||||
📤 已同步 N 个文件到远程
|
||||
🔗 Base commit: HASH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 执行约束
|
||||
|
||||
1. **Phase 0 最先** — 有未提交代码不允许跳过
|
||||
2. **方向严格区分** — Phase 3 只补充 / Phase 10 才覆盖
|
||||
3. **顺序固定** — Phase 5（update）→ Phase 6（lint）；lint 在 update 写入完毕后检查
|
||||
4. **统一推送** — update + lint 修改全部本地完成后由 Phase 10 一次推
|
||||
5. **记忆引导区块强制存在** — 每次 sync 后 CLAUDE.md 必须含最新区块，文件清单与 MEMORY.md 严格一致
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
name: memory-update
|
||||
description: 根据git diff增量范围，更新本地记忆文件和MEMORY.md索引。以本地.claude/memory/为唯一权威，不推送远程。可独立执行，也作为/memory-sync流程的一部分。调用命令: /memory-update
|
||||
---
|
||||
|
||||
# memory-update
|
||||
|
||||
按 git diff 增量更新本地 `.claude/memory/`。**本地权威，仅操作本地文件**。会话目录 = `$PROJECT_DIR`；目录不存在则 `mkdir -p`。
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — 读取增量锚点
|
||||
|
||||
```bash
|
||||
# MEMORY.md 头部 _Last synced: DATE | Base commit: `HASH`_ → $ANCHOR_COMMIT（无则空=全量）
|
||||
git -C "$PROJECT_DIR" rev-parse --short HEAD # → $HEAD_HASH（非 git 仓库填 N/A）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — 计算变更范围
|
||||
|
||||
```bash
|
||||
[ -n "$ANCHOR_COMMIT" ] && git diff --name-only $ANCHOR_COMMIT..HEAD # → $CHANGED_FILES
|
||||
```
|
||||
|
||||
空锚点 → 全量审查。
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — 更新记忆文件
|
||||
|
||||
### 维度路由（$CHANGED_FILES → 目标文件）
|
||||
|
||||
| 变更内容 | 写入到 |
|
||||
|---------|-------|
|
||||
| 业务代码（`*.java/py/ts/vue`） | `project_overview.md` `decisions.md` |
|
||||
| 依赖文件（pom.xml / requirements.txt / package.json） | `project_overview.md` |
|
||||
| 进度信号（功能完成、Issue 关闭） | `project_progress.md` |
|
||||
| 协作反馈（用户纠正、规范变更） | `feedback.md` 或 `feedback_{topic}.md` |
|
||||
| 外部 URL | `reference.md` |
|
||||
| 用户偏好/风格 | `user_profile.md` |
|
||||
|
||||
### 文件职责边界
|
||||
|
||||
| 文件 | 类型 | 写 | 不写 |
|
||||
|------|------|---|------|
|
||||
| `user_profile.md` | user | 角色、背景、偏好 | 任务进度 |
|
||||
| `project_overview.md` | project | 技术栈、架构、目录、约定 | 可推断细节 |
|
||||
| `project_progress.md` | project | 阶段、待办、里程碑 | git 历史 |
|
||||
| `decisions.md` | project | Why 格式决策 | 实现细节 |
|
||||
| `feedback*.md` | feedback | 协作规范（含 Why + How to apply） | 一次性修复 |
|
||||
| `reference.md` | reference | 外部 URL/用途 | 本地路径 |
|
||||
| `synthesis_*.md` | synthesis | 高价值分析归档 | 对话逐字记录 |
|
||||
|
||||
### 统一 frontmatter
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: 文件标题
|
||||
description: 一句话描述（影响未来加载判断）
|
||||
type: user | project | feedback | reference | synthesis
|
||||
last_updated: YYYY-MM-DD
|
||||
commit: HASH
|
||||
---
|
||||
```
|
||||
|
||||
### 条目格式（decisions / feedback 通用骨架）
|
||||
|
||||
```markdown
|
||||
## 标题
|
||||
|
||||
**结论**（feedback 改为规范描述）：xxx
|
||||
**Why：** 背景、约束、历史教训
|
||||
**How to apply：** 何时适用、边界
|
||||
**See Also：** [[file.md#标题]]
|
||||
```
|
||||
|
||||
`synthesis_*.md` 是完整文件而非条目，含 4 段：`## 背景` / `## 分析过程`（提炼，非逐字记录）/ `## 结论`（含 Why + How to apply）/ `## See Also`。
|
||||
|
||||
### 交叉引用（双向）
|
||||
|
||||
新增 decisions / feedback 条目时：
|
||||
1. 扫描其他记忆文件标题
|
||||
2. 主题相关 → 新条目末尾追加 `[[file.md#标题]]`
|
||||
3. **反向也补**：被引用的旧条目末尾补充对新条目的引用
|
||||
|
||||
### synthesis 双触发模式
|
||||
|
||||
**A. 会话内主动**：会话出现技术选型对比 / Bug 根因 / 架构演进 / 性能安全分析时，主动提议归档为 `synthesis_{type}_{topic}.md`。
|
||||
|
||||
**B. 反向引用触发**：
|
||||
1. 读 `lint_report.md`「条目级高频引用 Top」段（≥3 跨文件 = 候选）
|
||||
2. 检查候选是否已有对应 `synthesis_*`（前缀匹配 + 标题语义）
|
||||
3. 未升级候选 → 提议：
|
||||
```
|
||||
📊 高频引用候选升级 synthesis：
|
||||
[条目]（被 N 文件引用）→ 建议归档为 synthesis_xxx.md
|
||||
是否归档？(y/n/skip-all)
|
||||
```
|
||||
4. `y` → 创建文件 + 在原条目末尾加 `**Synthesized:** [[xxx.md]]`
|
||||
5. `n` → 原条目末尾加 `<!-- synthesis-decline: YYYY-MM-DD -->`，30 天免打扰
|
||||
6. `skip-all` → 本次不再提议
|
||||
|
||||
### 写入要点
|
||||
|
||||
- 仅更新有变化维度，不重写无关文件
|
||||
- frontmatter 的 `last_updated` 改今日，`commit` 改 `$HEAD_HASH`
|
||||
- 追加为主，不删已有内容（除非过时/冲突）
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — 更新 MEMORY.md 索引
|
||||
|
||||
```markdown
|
||||
# Memory Index
|
||||
> _Last synced: YYYY-MM-DD | Base commit: `HASH`_
|
||||
|
||||
| 文件 | 描述 | 类型 | 引用 | Commit |
|
||||
|------|------|------|------|--------|
|
||||
```
|
||||
|
||||
更新规则：
|
||||
- 改过的文件 → 同步「Commit」列
|
||||
- 头部 `Last synced` / `Base commit` 改为今日 / `$HEAD_HASH`
|
||||
- 新增文件 → 「引用」列占位 `0`（实际值由 `/memory-lint` Phase 7 刷新）
|
||||
- 「引用」列语义：≥3 加 `*`（如 `5*`）、<3 显示数字
|
||||
- 表格排序由 lint 重排，本 Phase 不强制
|
||||
|
||||
被 `/memory-sync` 调用 → 不输出收尾；独立调用 → 输出完整摘要。
|
||||
|
||||
---
|
||||
|
||||
## 执行约束
|
||||
|
||||
1. **最小化更新** — 不写无变化维度
|
||||
2. **不记录可推断内容** — 实现细节、文件路径、git 历史不入库
|
||||
3. **feedback 拆分** — 同主题 >5 条规则 → 拆出 `feedback_{topic}.md`
|
||||
4. **See Also 双向同步** — 新增时扫关联并双向补
|
||||
5. **synthesis 双触发** — 会话主动 + lint Top 反向；`**Synthesized:**` 标记不可覆盖；`<!-- synthesis-decline -->` 标记 30 天免打扰
|
||||
6. **被调用静默返回** — `/memory-sync` 内执行不输出收尾
|
||||
Reference in New Issue
Block a user