memory-bank-skill 5.0.0

package/skill/memory-bank/README.md

@@ -0,0 +1,108 @@
+# Memory Bank Skill
+
+项目记忆系统 - 自动读取上下文、自动沉淀发现、追踪需求与技术变更。
+
+## 简介
+
+Memory Bank 是一个纯 Markdown 的项目记忆系统。通过结构化文档将 AI 的"记忆"外化，解决 AI 编码助手 session 间失忆的问题。
+
+### 核心能力
+
+- **自动读取**: Session 开始时自动加载项目上下文
+- **自动写入**: 在关键时刻自动沉淀发现和决策
+- **需求追踪**: 管理需求池，记录需求变更历史
+- **技术文档**: 三层技术文档（架构/模块/细节），追踪实现变更
+- **经验沉淀**: 分类管理 bug/性能/集成经验
+
+## 目录结构
+
+```
+memory-bank/
+├── brief.md                 # 项目概述
+├── tech.md                  # 技术栈 + 环境
+├── active.md                # 当前焦点（高频更新）
+├── progress.md              # 进度状态
+├── patterns.md              # 决策 + 约定
+│
+├── requirements/            # 需求池
+│   └── REQ-{ID}-{slug}.md
+│
+├── docs/                    # 技术文档
+│   ├── architecture.md      # L1: 架构层
+│   ├── modules/             # L2: 模块层
+│   └── specs/               # L3: 细节层
+│
+└── learnings/               # 经验沉淀
+    ├── bugs/
+    ├── performance/
+    └── integrations/
+```
+
+## 使用方法
+
+### 初始化
+```
+初始化记忆
+init memory bank
+```
+
+### 更新
+```
+更新记忆
+update memory bank
+```
+
+### 新建需求
+```
+新需求: 用户登录功能
+new req: user login
+```
+
+### 记录经验
+```
+记录经验: bug Safari兼容问题
+log learning: bug safari-compat
+```
+
+### 新建模块文档
+```
+新模块文档: scanner
+new module doc: scanner
+```
+
+### 查看状态
+```
+项目状态
+project status
+```
+
+## 文件说明
+
+| 文件 | 用途 | 更新频率 |
+|------|------|----------|
+| brief.md | 项目是什么 | 低 |
+| tech.md | 技术栈和环境 | 低 |
+| active.md | 当前工作焦点 | 高 |
+| progress.md | 完成状态 | 中 |
+| patterns.md | 技术决策和约定 | 中 |
+| requirements/*.md | 需求文档 | 按需求变更 |
+| docs/*.md | 技术文档 | 按实现变更 |
+| learnings/*/*.md | 经验记录 | 按事件 |
+
+## 设计原则
+
+1. **纯 Markdown**: 无数据库，无外部服务，可 git 管理
+2. **人类可读**: 所有文档可直接阅读和编辑
+3. **简洁优先**: 核心 5 文件 + 3 目录
+4. **追加优先**: patterns 和 learnings 只追加不重写
+5. **变更内聚**: 变更历史放在对应文档内
+
+## 安全提示
+
+⚠️ **不要在 Memory Bank 中存储敏感信息**：
+- API 密钥、Token、密码
+- 数据库连接字符串
+- 私钥或证书
+- 任何凭证信息
+
+Memory Bank 设计为可 git 管理和团队共享，请确保不包含敏感数据。

package/skill/memory-bank/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: memory-bank
+description: 项目记忆系统 - 自动读取上下文、自动沉淀发现、追踪需求与技术变更
+---
+
+# Memory Bank Skill
+
+## 概述
+
+Memory Bank 是一个纯 Markdown 的项目记忆系统。通过结构化文档将"记忆"外化，实现：
+
+- **自动读取**：基于语义理解，智能加载相关上下文
+- **自动写入**：工作中沉淀发现、决策、经验
+- **变更追踪**：需求变更、技术实现变更全程记录
+- **零初始化**：无需手动 init，随项目推进自动创建
+
+---
+
+## 目录结构
+
+```
+memory-bank/
+├── _index.md                # 索引文件（AI 用于智能检索）
+├── brief.md                 # 项目概述（稳定）
+├── tech.md                  # 技术栈 + 环境 + 命令
+├── active.md                # 当前焦点 + 下一步 + 阻塞项（高频更新）
+├── progress.md              # 完成状态
+├── patterns.md              # 技术决策 + 代码约定
+│
+├── requirements/            # 需求池
+│   ├── _index.md
+│   └── REQ-{ID}-{slug}.md
+│
+├── docs/                    # 技术文档
+│   ├── _index.md
+│   ├── architecture.md
+│   ├── modules/
+│   └── specs/
+│
+└── learnings/               # 经验沉淀
+    ├── _index.md
+    ├── bugs/
+    ├── performance/
+    └── integrations/
+```
+
+---
+
+## Bootstrap 流程（零初始化）
+
+**每次用户对话时**：
+
+```
+1. 检测 memory-bank/ 目录是否存在
+   │
+   ├─ 存在 → 读取 _index.md + brief.md + active.md
+   │         继续正常工作
+   │
+   └─ 不存在 → 检测是否有代码库
+              │
+              ├─ 有代码库 → 扫描项目结构（package.json, README 等）
+              │             生成 brief.md + tech.md 草稿
+              │             创建 _index.md
+              │
+              └─ 空目录 → 等用户开始工作后按需创建
+```
+
+**扫描预算**：最多 10 个文件，每个最多 200 行。
+
+---
+
+## 索引系统
+
+### 根索引格式（_index.md）
+
+```markdown
+| path | title | summary | updated | size |
+|------|-------|---------|---------|------|
+| brief.md | Project Brief | 电商后台，核心是订单管理 | 2024-01-20 | 45 |
+| tech.md | Tech Stack | Go + Gin + PostgreSQL | 2024-01-20 | 80 |
+```
+
+### 索引维护
+- 创建/修改文件后自动更新索引
+- 用户可手动编辑 summary 提升检索精度
+- size 字段用于 context 预算控制
+
+---
+
+## 智能检索
+
+### 每轮对话流程
+
+```
+1. 固定加载：brief.md + active.md（如存在）
+
+2. 语义判断：
+   - 读取 _index.md
+   - 基于用户消息选择相关文件
+   - 输出决策：{ files: [...], reason: "..." }
+
+3. 按预算加载选中文件
+```
+
+### 预算限制
+- 每轮最多加载 5 个额外文件
+- 总行数限制 500 行
+- 超出时优先加载小文件、新文件
+
+### 风险提示
+- 如果 learnings/ 下有相关历史经验
+- 主动提醒："注意：历史上有类似问题 → {file}"
+
+---
+
+## 自动写入规则
+
+### 触发时机
+
+| 事件类型 | 触发条件 | 创建/更新 |
+|---------|---------|----------|
+| **New Entity** | 确定新需求/模块/API | requirements/REQ-xxx.md 或 docs/modules/xxx.md |
+| **Decision** | 技术选型确定，用户认可 | patterns.md |
+| **Learning** | Bug 修复/性能优化/集成踩坑 | learnings/{type}/{date}-{slug}.md |
+
+### 不写入的情况
+- 普通代码修改
+- 探索性调研（未形成结论）
+- 临时 debug（未确认根因）
+
+### 写入前确认
+
+```
+[Memory Bank 更新计划]
+- 创建: requirements/REQ-004-refund.md
+- 更新: active.md
+- 更新: _index.md
+
+是否执行？
+```
+
+---
+
+## 区块分离
+
+每个文件分为两个区块：
+
+```markdown
+<!-- MACHINE_BLOCK_START -->
+（AI 自动维护，用户不要改）
+<!-- MACHINE_BLOCK_END -->
+
+<!-- USER_BLOCK_START -->
+（用户自由编辑，AI 不覆盖）
+<!-- USER_BLOCK_END -->
+```
+
+冲突处理：检测到用户修改机器区块时，提示用户选择保留哪个版本。
+
+---
+
+## 命令
+
+| 触发 | 动作 |
+|------|------|
+| `更新记忆` / `update memory bank` | 全面检查并更新所有文件 |
+| `新需求: {标题}` / `new req: {title}` | 创建需求文档 |
+| `新模块文档: {名称}` / `new module doc: {name}` | 创建模块文档 |
+| `记录经验: {类型}` / `log learning: {type}` | 创建经验文档（bug/performance/integration） |
+| `项目状态` / `project status` | 汇总输出当前状态 |
+
+---
+
+## 设计原则
+
+1. **零初始化**：不需要手动 init
+2. **语义检索**：纯 AI 理解，不用关键词匹配
+3. **索引驱动**：通过 _index.md 支撑快速检索
+4. **区块分离**：机器区块自动维护，用户区块自由编辑
+5. **写前确认**：重要写入前输出计划
+6. **预算控制**：每轮加载有上限
+7. **人类可读**：所有文档可直接阅读、编辑、git 管理
+
+---
+
+## 自动提交模式
+
+当用户回复"更新并提交"或"初始化并提交"时，执行以下流程：
+
+### Preflight 检查（必须全部通过）
+
+执行以下检查，任一失败则中止并解释原因：
+
+1. **确认是 git 仓库**：`git rev-parse --is-inside-work-tree`
+2. **确认不在 merge/rebase/cherry-pick 中**：
+   - `git rev-parse --git-path MERGE_HEAD` 返回的文件不存在
+   - `git rev-parse --git-path rebase-merge` 返回的目录不存在
+   - `git rev-parse --git-path rebase-apply` 返回的目录不存在
+   - `git rev-parse --git-path CHERRY_PICK_HEAD` 返回的文件不存在
+3. **确认无冲突文件**：`git diff --name-only --diff-filter=U` 必须为空
+4. **确认有 git 身份**：`git config user.name` 和 `git config user.email` 非空
+5. **确认有变更可提交**：`git status --porcelain` 非空
+
+### 执行流程
+
+1. **输出计划**，包含：
+   - 将要更新的 memory-bank 文件
+   - 将要提交的所有变更（`git status --porcelain`）
+   - **风险检查提醒**：确认没有 `.env`、凭证、大文件会被提交
+   - 如果已有 staged 变更，明确告知"将包含已 staged 的文件"
+
+2. **等待用户确认**
+
+3. **执行更新**：
+   - 写入 memory-bank 文件
+   - 执行 `git add -A`
+   - 执行 `git diff --cached --name-only` 显示将提交的文件
+   - 执行 `git commit -m "chore(memory-bank): update <files>"`
+
+### Commit Message 格式
+
+```
+chore(memory-bank): update active.md
+
+Auto-committed by Memory Bank.
+```
+
+多文件时：
+```
+chore(memory-bank): update memory bank
+
+Files updated:
+- memory-bank/active.md
+- memory-bank/_index.md
+```
+
+### 失败处理
+
+- **Preflight 失败**：不执行任何操作，解释原因和修复方法
+- **Commit 失败**（如 hook 拒绝）：报告错误，memory-bank 文件已写入但未提交，用户手动处理
+
+---
+
+## 安全护栏
+
+### 禁止写入
+- API 密钥、密码、token
+- 客户隐私数据
+- 任何凭证信息
+
+### 防止幻觉
+- AI 只能选择 _index.md 中列出的文件
+- 创建新文件后必须同步更新索引
+
+---
+
+## 每轮行为规范
+
+```
+1. Bootstrap 检查（每次用户对话）
+   └─ 检测 memory-bank/ 是否存在
+
+2. 固定加载
+   └─ 读取 brief.md + active.md
+
+3. 读取索引
+   └─ 读取 _index.md
+
+4. 语义选择文件
+   └─ 基于用户消息选择相关文件
+   └─ 按预算限制加载
+
+5. 处理用户请求
+   └─ 创建 todo 时：
+      - 已有 memory-bank/ → 最后一项必须是"更新 Memory Bank"
+      - 没有 memory-bank/ → 第一项是"初始化 Memory Bank"，最后一项是"更新 Memory Bank"
+   └─ 正常工作
+
+6. 执行"更新 Memory Bank" todo 时
+   └─ 检查触发场景：
+      - 修改了代码/配置文件 → 更新 active.md
+      - 修复了 bug / 踩坑经验 → 创建 learnings/xxx.md
+      - 做了技术决策 → 追加 patterns.md
+      - 新需求确认 → 创建 requirements/REQ-xxx.md
+   └─ 命中任一条件 → 输出 memory_ops 计划
+
+7. 执行写入
+   └─ 用户确认后执行
+```
+
+---
+
+## 读取行为规范
+
+当系统提示 `[Memory Bank]` 通知加载了上下文时，遵循以下规范：
+
+### 1. 显式声明上下文来源
+
+回答问题时，简短说明参考了哪些 Memory Bank 文件：
+
+```
+基于 brief.md 和 active.md，当前项目是...
+```
+
+### 2. 不把 Memory Bank 当真理
+
+Memory Bank 可能过时。如果与代码/配置矛盾：
+- **优先以仓库实际内容为准**
+- 建议更新 Memory Bank（走写入流程）
+
+### 3. 引用驱动的继续阅读
+
+如果 `active.md` 或 `_index.md` 提到：
+- `REQ-xxx` → 读取对应需求文档
+- `patterns.md` → 读取技术决策
+- 某模块文档 → 读取该文档
+
+将这些当作**高优先级读取目标**。
+
+### 4. 陈旧检测
+
+当 `active.md` 的"当前焦点"与用户最新目标明显不一致时：
+- 先澄清："active.md 记录的焦点是 X，你现在想做 Y，是否需要更新？"
+- 或直接建议更新（走写入流程）
+
+### 5. 输出边界
+
+上下文不足时：
+- **先用工具**（grep/read）查找相关文件
+- **禁止**仅凭 Memory Bank 缺失就断言"不存在"或"没有"
+
+---
+
+## 详细参考
+
+- [文件模板](references/templates.md) - 各文件的标准模板
+- [高级规则](references/advanced-rules.md) - 冲突处理、阈值规则、预算控制
+- [结构化输出 Schema](references/schema.md) - JSON 输出格式定义

package/skill/memory-bank/references/advanced-rules.md

@@ -0,0 +1,189 @@
+# Memory Bank 高级规则
+
+> 此文件包含索引规范、冲突处理、阈值规则、预算控制等详细规则。
+
+---
+
+## 索引字段规范
+
+### 字段定义
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `path` | string | 相对于 memory-bank/ 的文件路径（唯一键） |
+| `title` | string | 文件第一个 # 标题 |
+| `summary` | string | 2-4 句话摘要，强调"何时该读它" |
+| `updated` | date | ISO 8601 日期格式：YYYY-MM-DD |
+| `size` | number | 文件行数（用于预算计算） |
+
+### 子索引额外字段
+
+| 字段 | 适用于 | 说明 |
+|------|--------|------|
+| `status` | requirements | Proposed / Accepted / Implementing / Done / Deprecated |
+| `type` | learnings | bug / performance / integration |
+
+### 格式示例
+
+```markdown
+| path | title | summary | updated | size |
+|------|-------|---------|---------|------|
+| brief.md | Project Brief | 电商后台，核心是订单管理，技术约束见 tech.md | 2024-01-20 | 45 |
+```
+
+---
+
+## 索引逃生门（自愈机制）
+
+### 问题场景
+- 索引文件丢失或损坏
+- 新文件未被收录到索引
+- 用户明确要求读取某个路径
+
+### 逃生规则
+
+**场景 1：索引缺失**
+```
+检测到 _index.md 不存在或为空
+→ 扫描 memory-bank/ 下所有 .md 文件
+→ 自动重建索引
+→ 提示用户"索引已重建，请检查"
+```
+
+**场景 2：用户明确指定路径**
+```
+用户说"读取 memory-bank/xxx.md"
+→ 允许读取（即使不在索引中）
+→ 读取后自动添加到 _index.md
+→ 提示用户"已添加到索引"
+```
+
+**场景 3：Bootstrap 时的固定 Allowlist**
+```
+Bootstrap 扫描时允许读取（不依赖索引）：
+- README.md
+- package.json / go.mod / Cargo.toml / pyproject.toml
+- 目录树（前两层）
+```
+
+---
+
+## 机器区块冲突处理
+
+### 冲突检测机制
+
+每个机器区块开头包含元信息：
+```markdown
+<!-- MACHINE_BLOCK_START -->
+<!-- blockVersion: 3 | lastUpdated: 2024-01-22T10:30:00Z -->
+```
+
+**检测流程**：
+1. 读取机器区块的 `blockVersion` 和 `lastUpdated`
+2. 计算当前机器区块内容的 hash
+3. 与上次写入时保存的 hash 对比
+4. 如果 hash 不同 → 检测到用户修改
+
+### 冲突处理策略
+
+**发现冲突时**：
+```
+检测到 active.md 机器区块被手动修改：
+- 上次更新: 2024-01-22T10:30:00Z
+- 当前内容与预期不符
+
+选择处理方式：
+1. 保留你的修改，跳过本次更新
+2. 用 AI 更新覆盖你的修改
+3. 合并：AI 更新追加到你的修改后面
+
+请选择 (1/2/3):
+```
+
+**不产生冲突副本**：避免文件污染，让用户明确选择。
+
+---
+
+## 触发阈值硬规则
+
+### Decision（技术决策）必须满足
+
+写入 patterns.md 的决策必须包含：
+- ✅ **决策内容**：选了什么
+- ✅ **原因**：为什么选它
+- ✅ **取舍**：放弃了什么选项
+- ✅ **适用范围**：什么场景用
+- ❌ **不适用**：什么场景不用（可选）
+
+**格式示例**：
+```markdown
+| 日期 | 决策 | 原因 | 取舍 | 适用范围 |
+|------|------|------|------|----------|
+| 2024-01-22 | 错误处理用 pkg/errors | 支持 wrap + stack trace | 放弃标准 errors | 所有业务逻辑层 |
+```
+
+### Learning（经验教训）必须包含
+
+写入 learnings/ 的经验必须包含：
+- ✅ **症状**：如何发现问题
+- ✅ **根因**：根本原因是什么
+- ✅ **解决方案**：怎么修的
+- ✅ **预防措施**：如何避免再次发生（断言/监控/测试）
+
+**不合格示例**（拒绝写入）：
+```
+问题：支付超时
+解决：改了超时时间
+```
+
+**合格示例**：
+```
+问题：支付超时
+症状：高峰期支付成功率下降到 60%
+根因：默认超时 3s，支付宝网关响应 P99 = 4.2s
+解决：超时改为 10s + 增加重试 2 次
+预防：添加支付耗时监控告警，P99 > 5s 时报警
+```
+
+---
+
+## 预算控制详细规则
+
+### 行数计算方式
+- `size` 字段 = 文件总行数（wc -l）
+- 机器区块和用户区块都计入
+- 空行计入
+
+### 预算分配
+| 类型 | 预算 |
+|------|------|
+| 固定加载（brief + active） | 不限 |
+| 每轮额外加载 | 最多 5 个文件 |
+| 额外加载总行数 | 最多 500 行 |
+
+### 超预算降级策略
+
+当候选文件总 size 超过 500 行时：
+```
+1. 固定加载 brief.md + active.md（不计入预算）
+2. 按相关性排序候选文件
+3. 按 size 从小到大依次加载
+4. 累计 size 达到 500 行时停止
+5. 未加载的文件提示用户："以下文件相关但未加载（预算限制）：..."
+```
+
+### 大文件处理
+- 如果单个文件 > 200 行
+- 只读取前 100 行 + 最后 50 行
+- 中间插入 `[... 省略 {n} 行 ...]`
+
+---
+
+## 扩展点
+
+| 情况 | 动作 |
+|------|------|
+| 需求 > 20 个 | 索引自动分页 或 添加 status 筛选 |
+| learnings > 30 条 | 按 type 分子索引 |
+| 多人协作 | 添加 author 字段到索引 |
+| 大仓库 | bootstrap 扫描增加更多预算限制 |