memory-bank-skill 5.3.0 → 5.3.2

package/README.md

@@ -41,9 +41,9 @@ bunx memory-bank-skill doctor
 | 操作 | 目标路径 |
 |------|----------|
 | 复制 Skill 文件 | `~/.config/opencode/skill/memory-bank/` |
-| 复制 Plugin 文件 | `~/.config/opencode/plugin/memory-bank.ts` |
-| 配置 opencode.json | 添加 `permission.skill` 和插件注册 |
-| 安装依赖 | `~/.config/opencode/node_modules/` |
+| 配置 opencode.json | 添加 `permission.skill=allow`，注册插件包 `memory-bank-skill` |
+| 写入 manifest | `~/.config/opencode/skill/memory-bank/.manifest.json` |
+| 依赖安装 | 不自动执行；如需手动运行 `cd ~/.config/opencode && bun install` |
 
 ---
 
@@ -55,7 +55,7 @@ bunx memory-bank-skill doctor
 |------|---------|
 | **已有代码库** | 扫描 package.json/README 等，自动生成 brief.md + tech.md |
 | **新项目** | 不创建任何文件，等你开始工作后按需创建 |
-| **已有 Memory Bank** | 直接读取 brief.md + active.md，恢复上下文 |
+| **已有 Memory Bank** | 直接读取 brief.md + active.md + _index.md，恢复上下文 |
 
 ---
 
@@ -75,12 +75,17 @@ memory-bank/
 │
 ├── docs/                    # 技术文档
 │   ├── architecture.md
-│   └── modules/
+│   ├── design-*.md
+│   ├── modules/
+│   └── specs/
 │
-└── learnings/               # 经验沉淀
-    ├── bugs/
-    ├── performance/
-    └── integrations/
+├── learnings/               # 经验沉淀
+│   ├── bugs/
+│   ├── performance/
+│   └── integrations/
+│
+└── archive/                 # 归档文件（按月）
+    └── active_YYYY-MM.md
 ```
 
 ---
@@ -96,17 +101,21 @@ Memory Bank 包含一个 OpenCode 插件，提供两个核心功能：
 - 文件缓存 + mtime 检测，只有变更才重新读取
 - 12,000 字符上限，超出自动截断
 
-### 2. 自动提醒更新
+### 2. 自动提醒更新（当前禁用）
 
 AI 尝试停止时，检测是否需要更新 Memory Bank：
 - 检测文件修改（代码/配置/文档）
 - 检测用户消息关键词（新需求、bug、决策等）
 - 提醒初始化或更新
 
+> 注意：自动提醒链路当前在插件中整体暂时禁用（`evaluateAndFireReminder()` 未被调用），以下描述为历史行为。
+
+当前提醒禁用时，以下逃逸阀不会生效。
+
 **逃逸阀**：
 - 回复"无需更新"或"已检查" → 本次会话不再提醒
 - 回复"跳过初始化" → 本次会话不再提醒初始化
-- 环境变量 `MEMORY_BANK_DISABLED=1` → 完全禁用
+- 环境变量 `MEMORY_BANK_DISABLED=1|true` → 禁用提醒链路（上下文注入仍然生效）
 
 ---
 
@@ -169,11 +178,11 @@ service=memory-bank Plugin initialized (unified) {"projectRoot":"..."}
 | Skill 主文件 | `~/.config/opencode/skill/memory-bank/SKILL.md` |
 | 文件模板 | `~/.config/opencode/skill/memory-bank/references/templates.md` |
 | 高级规则 | `~/.config/opencode/skill/memory-bank/references/advanced-rules.md` |
-| 插件 | `~/.config/opencode/plugin/memory-bank.ts` |
+| 插件 | `opencode.json` 的 `plugin` 数组（`memory-bank-skill`） |
 
 ---
 
 ## 版本
 
-- **版本**: 5.2.0
+- **版本**: 5.3.2
 - **主要更新**: 增加 Design 设计文档支持，方案讨论确定时自动创建/更新 docs/design-*.md

package/dist/cli.js

@@ -7,7 +7,7 @@ import { homedir } from "os";
 import { join, dirname } from "path";
 import { createHash } from "crypto";
 import { fileURLToPath } from "url";
-var VERSION = "5.3.0";
+var VERSION = "5.3.2";
 var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-bank-skill",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "description": "Memory Bank - 项目记忆系统，让 AI 助手在每次对话中都能快速理解项目上下文",
   "type": "module",
   "main": "dist/plugin.js",

package/skill/memory-bank/README.md

@@ -14,10 +14,14 @@ Memory Bank 是一个纯 Markdown 的项目记忆系统。通过结构化文档
 - **技术文档**: 三层技术文档（架构/模块/细节），追踪实现变更
 - **经验沉淀**: 分类管理 bug/性能/集成经验
 
+> 注意：插件提醒链路当前暂时禁用，自动写入依赖 AI 按规则执行。
+> 环境变量 `MEMORY_BANK_DISABLED=1|true` 用于禁用提醒链路（提醒恢复前无效）。
+
 ## 目录结构
 
 ```
 memory-bank/
+├── _index.md                # 索引文件
 ├── brief.md                 # 项目概述
 ├── tech.md                  # 技术栈 + 环境
 ├── active.md                # 当前焦点（高频更新）
@@ -29,18 +33,23 @@ memory-bank/
 │
 ├── docs/                    # 技术文档
 │   ├── architecture.md      # L1: 架构层
+│   ├── design-*.md           # 方案设计文档
 │   ├── modules/             # L2: 模块层
 │   └── specs/               # L3: 细节层
 │
-└── learnings/               # 经验沉淀
-    ├── bugs/
-    ├── performance/
-    └── integrations/
+├── learnings/               # 经验沉淀
+│   ├── bugs/
+│   ├── performance/
+│   └── integrations/
+│
+└── archive/                 # 归档文件（按月）
+    └── active_YYYY-MM.md
 ```
 
 ## 使用方法
 
-### 初始化
+### 初始化（可选）
+默认无需初始化，仅在需要手动创建时使用。
 ```
 初始化记忆
 init memory bank
@@ -80,22 +89,26 @@ project status
 
 | 文件 | 用途 | 更新频率 |
 |------|------|----------|
+| _index.md | 索引与检索提示 | 中 |
 | brief.md | 项目是什么 | 低 |
 | tech.md | 技术栈和环境 | 低 |
 | active.md | 当前工作焦点 | 高 |
 | progress.md | 完成状态 | 中 |
 | patterns.md | 技术决策和约定 | 中 |
 | requirements/*.md | 需求文档 | 按需求变更 |
+| docs/design-*.md | 设计文档 | 按设计变更 |
 | docs/*.md | 技术文档 | 按实现变更 |
 | learnings/*/*.md | 经验记录 | 按事件 |
+| archive/*.md | 归档记录 | 按需 |
 
 ## 设计原则
 
 1. **纯 Markdown**: 无数据库，无外部服务，可 git 管理
 2. **人类可读**: 所有文档可直接阅读和编辑
-3. **简洁优先**: 核心 5 文件 + 3 目录
+3. **简洁优先**: 核心 6 文件 + 4 目录
 4. **追加优先**: patterns 和 learnings 只追加不重写
-5. **变更内聚**: 变更历史放在对应文档内
+5. **区块分离**: MACHINE_BLOCK 与 USER_BLOCK 分离维护
+6. **变更内聚**: 变更历史放在对应文档内
 
 ## 安全提示
 

package/skill/memory-bank/SKILL.md

@@ -28,22 +28,28 @@ memory-bank/
 ├── patterns.md              # 技术决策 + 代码约定
 │
 ├── requirements/            # 需求池
-│   ├── _index.md
 │   └── REQ-{ID}-{slug}.md
 │
 ├── docs/                    # 技术文档
-│   ├── _index.md
 │   ├── architecture.md
+│   ├── design-*.md
 │   ├── modules/
 │   └── specs/
 │
-└── learnings/               # 经验沉淀
-    ├── _index.md
-    ├── bugs/
-    ├── performance/
-    └── integrations/
+├── learnings/               # 经验沉淀
+│   ├── bugs/
+│   ├── performance/
+│   └── integrations/
+│
+└── archive/                 # 归档文件（按月）
+    └── active_YYYY-MM.md
 ```
 
+可选子索引（规模变大时启用）：
+- `requirements/_index.md`
+- `docs/_index.md`
+- `learnings/_index.md`
+
 ---
 
 ## Bootstrap 流程（零初始化）
@@ -92,11 +98,10 @@ memory-bank/
 ### 每轮对话流程
 
 ```
-1. 固定加载：brief.md + active.md（如存在）
+1. 固定加载：brief.md + active.md + _index.md（如存在）
 
 2. 语义判断：
-   - 读取 _index.md
-   - 基于用户消息选择相关文件
+   - 基于 _index.md 选择相关文件
    - 输出决策：{ files: [...], reason: "..." }
 
 3. 按预算加载选中文件
@@ -123,12 +128,31 @@ memory-bank/
 | **Design** | 新设计 / 重新设计 / 设计变更 | docs/design-{slug}.md（已存在则更新） |
 | **Decision** | 技术选型确定，用户认可 | patterns.md |
 | **Learning** | Bug 修复/性能优化/集成踩坑 | learnings/{type}/{date}-{slug}.md |
+| **Archive** | active.md 超过 120 行或已完成条目超过 20 条 | archive/active_YYYY-MM.md |
+
+### 归档判定
+
+- 已完成条目 = `active.md` 中“已完成（待归档）”区块内的 `- [x]` 数量
+- 若该区块缺失，可回退为统计 `active.md` 中所有 `- [x]` 项
 
 ### 不写入的情况
 - 普通代码修改
 - 探索性调研（未形成结论）
 - 临时 debug（未确认根因）
 
+### patterns vs 设计文档判定
+
+用下面的判定避免混淆：
+
+- **patterns.md**：全局/长期的技术决策或约定（"以后都这样做"、"统一选择 X"）
+- **docs/design-*.md**：某个功能/模块/重构的具体实现方案（"这个功能怎么搭"）
+
+快速判断：
+
+- 问题是"该功能如何实现" → 写设计文档
+- 问题是"我们以后统一怎么做/用什么" → 追加 patterns
+- 两者都涉及 → 先写设计文档，再把最终技术决策沉淀到 patterns
+
 ### 写入前确认
 
 ```
@@ -250,7 +274,8 @@ Files updated:
 - 任何凭证信息
 
 ### 防止幻觉
-- AI 只能选择 _index.md 中列出的文件
+- 默认只读取 _index.md 中列出的文件
+- 用户明确指定路径时允许读取，并补充到索引
 - 创建新文件后必须同步更新索引
 
 ---
@@ -262,16 +287,13 @@ Files updated:
    └─ 检测 memory-bank/ 是否存在
 
 2. 固定加载
-   └─ 读取 brief.md + active.md
-
-3. 读取索引
-   └─ 读取 _index.md
+   └─ 读取 brief.md + active.md + _index.md
 
-4. 语义选择文件
-   └─ 基于用户消息选择相关文件
+3. 语义选择文件
+   └─ 基于 _index.md 选择相关文件
    └─ 按预算限制加载
 
-5. 处理用户请求
+4. 处理用户请求
    └─ **文档驱动开发原则**：
       - 方案讨论确定后 → 先写 memory-bank/docs/design-xxx.md，再写代码
       - 设计文档是契约，代码要符合文档
@@ -282,7 +304,7 @@ Files updated:
       - 没有 memory-bank/ → 第一项是"初始化 Memory Bank"，最后一项是"更新 Memory Bank"
    └─ 正常工作
 
-6. 执行"更新 Memory Bank" todo 时
+5. 执行"更新 Memory Bank" todo 时
    └─ 检查触发场景：
       - 方案讨论确定 / 设计变更 → 检查 docs/design-*.md 是否已存在
         - 存在 → 更新该文档
@@ -290,10 +312,11 @@ Files updated:
       - 修改了代码/配置文件 → 更新 active.md
       - 修复了 bug / 踩坑经验 → 创建 learnings/xxx.md
       - 做了技术决策 → 追加 patterns.md
-      - 新需求确认 → 创建 requirements/REQ-xxx.md
+   - 新需求确认 → 创建 requirements/REQ-xxx.md
+   - active.md 超出归档阈值 → 归档到 archive/active_YYYY-MM.md 并清理 active.md
    └─ 命中任一条件 → 输出 memory_ops 计划
 
-7. 执行写入
+6. 执行写入
    └─ 用户确认后执行
 ```
 
@@ -301,7 +324,7 @@ Files updated:
 
 ## 读取行为规范
 
-当系统提示 `[Memory Bank]` 通知加载了上下文时，遵循以下规范：
+当 system prompt 注入 Memory Bank Bootstrap（当前无 `[Memory Bank]` 头部通知）时，遵循以下规范：
 
 ### 1. 显式声明上下文来源
 

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

@@ -46,6 +46,7 @@
 ```
 检测到 _index.md 不存在或为空
 → 扫描 memory-bank/ 下所有 .md 文件
+→ 默认忽略 _index.md 自身（不写入索引表）
 → 自动重建索引
 → 提示用户"索引已重建，请检查"
 ```
@@ -72,14 +73,14 @@ Bootstrap 扫描时允许读取（不依赖索引）：
 
 ### 冲突检测机制
 
-每个机器区块开头包含元信息：
+机器区块可选包含元信息（建议）：
 ```markdown
 <!-- MACHINE_BLOCK_START -->
 <!-- blockVersion: 3 | lastUpdated: 2024-01-22T10:30:00Z -->
 ```
 
 **检测流程**：
-1. 读取机器区块的 `blockVersion` 和 `lastUpdated`
+1. 若存在元信息，读取机器区块的 `blockVersion` 和 `lastUpdated`
 2. 计算当前机器区块内容的 hash
 3. 与上次写入时保存的 hash 对比
 4. 如果 hash 不同 → 检测到用户修改
@@ -147,17 +148,32 @@ Bootstrap 扫描时允许读取（不依赖索引）：
 
 ---
 
+## 归档阈值规则
+
+当 `active.md` 满足以下任一条件时，触发归档：
+
+- 行数超过 120 行
+- 已完成条目超过 20 条（`active.md` 中 `- [x]` 数量，优先统计“已完成（待归档）”区块）
+
+归档行为：
+
+- 移入 `archive/active_YYYY-MM.md`
+- `active.md` 仅保留当前焦点、下一步、阻塞项、最近 30 天变更
+
+---
+
 ## 预算控制详细规则
 
 ### 行数计算方式
 - `size` 字段 = 文件总行数（wc -l）
+- 若文件缺少结尾换行，`wc -l` 可能不计入最后一行（建议保留结尾换行）
 - 机器区块和用户区块都计入
 - 空行计入
 
 ### 预算分配
 | 类型 | 预算 |
 |------|------|
-| 固定加载（brief + active） | 不限 |
+| 固定加载（brief + active + _index） | 不限 |
 | 每轮额外加载 | 最多 5 个文件 |
 | 额外加载总行数 | 最多 500 行 |
 
@@ -165,7 +181,7 @@ Bootstrap 扫描时允许读取（不依赖索引）：
 
 当候选文件总 size 超过 500 行时：
 ```
-1. 固定加载 brief.md + active.md（不计入预算）
+1. 固定加载 brief.md + active.md + _index.md（不计入预算）
 2. 按相关性排序候选文件
 3. 按 size 从小到大依次加载
 4. 累计 size 达到 500 行时停止

package/skill/memory-bank/references/templates.md

@@ -7,7 +7,7 @@
 ## _index.md（根索引）
 
 ```markdown
-# Memory Bank Index
+# Memory Bank 索引
 
 > 自动维护，可手工编辑 summary 以提升检索精度
 
@@ -94,8 +94,11 @@
 {正在做什么}
 
 ## 下一步
-1. {next 1}
-2. {next 2}
+- [ ] {next 1}
+- [ ] {next 2}
+
+## 已完成（待归档）
+- [x] {done item}
 
 ## 阻塞项
 - {blocker，无则写「无」}
@@ -141,6 +144,30 @@
 
 ---
 
+## archive/active_YYYY-MM.md
+
+```markdown
+# Active Archive - {YYYY-MM}
+
+<!-- MACHINE_BLOCK_START -->
+> 归档于: {YYYY-MM-DD}
+
+## 已完成条目
+- {item}
+
+## 最近变更（历史）
+| 日期 | 变更 |
+|------|------|
+<!-- MACHINE_BLOCK_END -->
+
+<!-- USER_BLOCK_START -->
+## 备注
+{用户自由编辑区}
+<!-- USER_BLOCK_END -->
+```
+
+---
+
 ## patterns.md
 
 ```markdown
@@ -193,6 +220,177 @@
 
 ---
 
+以下 docs 模板与 `templates/docs/` 保持一致，更新时需同步。
+
+## docs/architecture.md
+
+```markdown
+# Architecture
+
+> 更新于: {YYYY-MM-DD}
+
+## 系统概览
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Layer 1   │────▶│   Layer 2   │────▶│   Layer 3   │
+│    {名称}   │     │    {名称}   │     │    {名称}   │
+└─────────────┘     └─────────────┘     └─────────────┘
+```
+
+## 模块划分
+| 模块 | 职责 | 文档 |
+|------|------|------|
+| {module1} | {职责描述} | [modules/{module1}.md](modules/{module1}.md) |
+| {module2} | {职责描述} | [modules/{module2}.md](modules/{module2}.md) |
+
+## 关键流程
+
+### {流程 1 名称}
+```
+{步骤 1} → {步骤 2} → {步骤 3} → {步骤 4}
+```
+
+### {流程 2 名称}
+{流程描述}
+
+## 变更记录
+| 日期 | 变更 | 原因 | 影响 |
+|------|------|------|------|
+| {YYYY-MM-DD} | {变更内容} | {为什么改} | {影响范围} |
+```
+
+---
+
+## docs/modules/{module}.md
+
+```markdown
+# {Module} 模块
+
+> 更新于: {YYYY-MM-DD}
+
+## 职责
+{模块负责什么，1-2 句话}
+
+## 目录结构
+```
+src/{path}/
+├── components/      # {说明}
+├── hooks/           # {说明}
+├── services/        # {说明}
+└── types.ts         # {说明}
+```
+
+## 核心流程
+```
+{输入} → {处理1} → {处理2} → {输出}
+```
+
+## 对外接口
+| 接口 | 说明 | 详见 |
+|------|------|------|
+| {接口名} | {说明} | [specs/{spec}.md](../specs/{spec}.md) |
+
+## 依赖关系
+- **依赖**: {本模块依赖的其他模块}
+- **被依赖**: {依赖本模块的其他模块}
+
+## 变更记录
+| 日期 | 变更 | 原因 |
+|------|------|------|
+| {YYYY-MM-DD} | {变更内容} | {为什么改} |
+```
+
+---
+
+## docs/specs/{spec}.md
+
+```markdown
+# {Spec Name}
+
+> 更新于: {YYYY-MM-DD}
+
+## 接口定义
+
+### {接口 1}
+```typescript
+// 输入
+interface {Name}Input {
+  field1: string
+  field2: number
+}
+
+// 输出
+interface {Name}Output {
+  success: boolean
+  data: {Type}
+}
+```
+
+## 数据模型
+```typescript
+interface {Model} {
+  id: string
+  field1: string
+  field2: number
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+## 业务规则
+- {规则 1}
+- {规则 2}
+- {规则 3}
+
+## 边界情况
+| 情况 | 处理方式 |
+|------|----------|
+| {情况 1} | {处理} |
+| {情况 2} | {处理} |
+
+## 变更记录
+| 日期 | 版本 | 变更 | 原因 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | - |
+```
+
+---
+
+## docs/design-{slug}.md
+
+```markdown
+# 设计文档: {标题}
+
+## 状态
+{提案 | 已确认 | 实现中 | 已完成}
+
+## 背景
+{问题背景与动机}
+
+## 目标
+- {目标 1}
+- {目标 2}
+
+## 方案
+
+### 方案概述
+{总体思路}
+
+### 关键改动
+- {改动 1}
+- {改动 2}
+
+## 风险与兜底
+- {风险 1} → {兜底方案}
+
+## 变更记录
+| 日期 | 变更 | 原因 |
+|------|------|------|
+| {YYYY-MM-DD} | 创建 | - |
+```
+
+---
+
 ## learnings/{type}/{date}-{slug}.md
 
 ```markdown

package/templates/active.md

@@ -1,14 +1,18 @@
 # Active Context
 
+<!-- MACHINE_BLOCK_START -->
 > 更新于: {YYYY-MM-DD HH:mm}
 
 ## 当前焦点
 {正在做什么，1-2 句话描述当前最重要的工作}
 
 ## 下一步
-1. {下一步 1}
-2. {下一步 2}
-3. {下一步 3}
+- [ ] {下一步 1}
+- [ ] {下一步 2}
+- [ ] {下一步 3}
+
+## 已完成（待归档）
+- [x] {已完成事项}
 
 ## 阻塞项
 - {阻塞项描述，无则写「无」}
@@ -17,4 +21,9 @@
 | 日期 | 变更 |
 |------|------|
 | {YYYY-MM-DD} | {变更内容} |
-| {YYYY-MM-DD} | {变更内容} |
+<!-- MACHINE_BLOCK_END -->
+
+<!-- USER_BLOCK_START -->
+## 用户笔记
+{用户自由编辑区}
+<!-- USER_BLOCK_END -->

package/templates/docs/design-template.md

@@ -0,0 +1,28 @@
+# 设计文档: {标题}
+
+## 状态
+{提案 | 已确认 | 实现中 | 已完成}
+
+## 背景
+{问题背景与动机}
+
+## 目标
+- {目标 1}
+- {目标 2}
+
+## 方案
+
+### 方案概述
+{总体思路}
+
+### 关键改动
+- {改动 1}
+- {改动 2}
+
+## 风险与兜底
+- {风险 1} → {兜底方案}
+
+## 变更记录
+| 日期 | 变更 | 原因 |
+|------|------|------|
+| {YYYY-MM-DD} | 创建 | - |