NAC_Blockchain/memory/USAGE_GUIDE.md

# NAC记忆系统使用指南

## 快速开始

### 1. 查询记忆

```bash
# 进入记忆系统目录
cd /home/ubuntu/nac-workspace/memory

# 查询CBPP相关知识
python3 tools/query.py --keyword CBPP

# 查询所有问题
python3 tools/query.py --type problem

# 查询所有决策
python3 tools/query.py --type decision

# 查询术语映射
python3 tools/query.py --term Contract

# 列出所有记录
python3 tools/query.py --list
```

### 2. 添加新记录

```bash
# 添加文档记录
python3 tools/add.py document \
  --title "文档标题" \
  --path "/path/to/doc.pdf" \
  --summary "文档摘要" \
  --concepts "概念1,概念2,概念3"

# 添加问题记录
python3 tools/add.py problem \
  --title "问题标题" \
  --description "问题详细描述" \
  --solution "解决方案"

# 添加决策记录
python3 tools/add.py decision \
  --title "决策标题" \
  --decision "决策内容" \
  --rationale "决策理由"
```

### 3. 导出报告

```bash
# 导出完整报告
python3 tools/export.py --output NAC_Memory_Report.md

# 导出特定类型
python3 tools/export.py --type document --output documents.md
python3 tools/export.py --type problem --output problems.md
```

## 工作流程

### 每次开始新任务前

1. **查询相关文档**
   ```bash
   python3 tools/query.py --keyword "任务关键词"
   ```

2. **查询相关问题历史**
   ```bash
   python3 tools/query.py --type problem --keyword "相关问题"
   ```

3. **查询相关设计决策**
   ```bash
   python3 tools/query.py --type decision --keyword "相关决策"
   ```

4. **查询术语映射**
   ```bash
   python3 tools/query.py --term "术语"
   ```

### 每次阅读新文档后

1. **立即记录文档核心思想**
   ```bash
   python3 tools/add.py document \
     --title "文档标题" \
     --path "/path/to/doc" \
     --summary "核心思想摘要" \
     --concepts "核心概念列表"
   ```

2. **手动编辑JSON文件补充详细信息**
   - 打开生成的JSON文件
   - 补充核心概念的详细定义
   - 添加关键特性列表
   - 建立与其他文档的关联

### 每次遇到问题时

1. **先查询问题库**
   ```bash
   python3 tools/query.py --type problem --keyword "问题关键词"
   ```

2. **如果找到类似问题，直接使用解决方案**

3. **如果是新问题，解决后立即记录**
   ```bash
   python3 tools/add.py problem \
     --title "问题标题" \
     --description "问题描述" \
     --solution "解决方案"
   ```

4. **手动编辑JSON文件补充**
   - 根本原因分析
   - 预防措施
   - 经验教训

### 每次做重要决策时

1. **记录决策**
   ```bash
   python3 tools/add.py decision \
     --title "决策标题" \
     --decision "决策内容" \
     --rationale "决策理由"
   ```

2. **手动编辑JSON文件补充**
   - 决策背景和上下文
   - 替代方案及其优缺点
   - 影响范围和风险
   - 实施计划

### 定期维护

**每周一次**：
```bash
# 1. 导出完整报告
python3 tools/export.py --output weekly_report_$(date +%Y%m%d).md

# 2. 审查新增记录
ls -lt documents/*.json | head -10
ls -lt problems/*.json | head -10
ls -lt decisions/*.json | head -10

# 3. 更新关联关系
# 手动编辑JSON文件，添加related_docs, related_principles等

# 4. 备份记忆系统
cd /home/ubuntu/nac-workspace
tar -czf memory_backup_$(date +%Y%m%d).tar.gz memory/
```

## 记录规范

### 文档记录

**必填字段**：
- `title`: 文档标题
- `path`: 文档路径
- `summary`: 核心思想摘要（1-2句话）

**建议补充**：
- `core_concepts`: 核心概念列表（每个概念包含定义和重要性）
- `key_features`: 关键特性列表
- `related_docs`: 相关文档ID列表
- `tags`: 标签列表

**示例**：
```json
{
  "doc_id": "CBPP_WhitePaper_v1",
  "title": "CBPP技术白皮书",
  "summary": "CBPP通过'参与即共识'实现规则验证而非节点协商",
  "core_concepts": [
    {
      "concept": "参与即共识",
      "definition": "节点遵守规则的行为本身就是共识",
      "importance": "critical"
    }
  ]
}
```

### 问题记录

**必填字段**：
- `title`: 问题标题
- `description`: 问题详细描述
- `solution`: 解决方案

**建议补充**：
- `root_cause`: 根本原因分析（primary, secondary, underlying）
- `prevention`: 预防措施（rules, checklist）
- `lessons_learned`: 经验教训列表
- `related_docs`: 相关文档ID列表

**示例**：
```json
{
  "problem_id": "P001",
  "title": "误认为CBPP需要投票",
  "root_cause": {
    "primary": "未深入理解CBPP的'参与即共识'哲学",
    "secondary": "混淆了治理投票和共识机制"
  },
  "prevention": {
    "rules": ["实现前必须阅读相关白皮书"]
  }
}
```

### 决策记录

**必填字段**：
- `title`: 决策标题
- `decision`: 决策内容
- `rationale`: 决策理由

**建议补充**：
- `context`: 决策背景和问题
- `alternatives`: 替代方案及其优缺点
- `impact`: 影响范围和风险
- `related_files`: 受影响的文件列表

**示例**：
```json
{
  "decision_id": "D001",
  "title": "OpCode命名统一为UPPER_CASE",
  "decision": {
    "statement": "所有OpCode使用UPPER_CASE命名",
    "rules": ["单词间用下划线分隔"]
  },
  "rationale": ["符合区块链行业标准"]
}
```

## 最佳实践

### 1. 实时记录
- ✅ 阅读文档后立即记录
- ✅ 解决问题后立即记录
- ✅ 做决策时立即记录
- ❌ 不要等到任务结束才记录

### 2. 详细描述
- ✅ 记录要详细，包含上下文
- ✅ 说明原因和理由
- ✅ 提供示例和代码
- ❌ 不要只记录结论

### 3. 建立关联
- ✅ 记录之间建立关联（related_docs, related_principles）
- ✅ 问题关联到文档和原则
- ✅ 决策关联到受影响的文件
- ❌ 不要孤立地记录

### 4. 定期维护
- ✅ 每周审查新增记录
- ✅ 更新关联关系
- ✅ 导出备份
- ❌ 不要让记录过时

### 5. 查询优先
- ✅ 遇到问题先查询记忆系统
- ✅ 开始新任务前查询相关知识
- ✅ 使用术语前查询映射表
- ❌ 不要重复犯同样的错误

## 常见问题

### Q: 如何快速查找某个概念？
```bash
python3 tools/query.py --keyword "概念名称"
```

### Q: 如何查看所有未解决的问题？
```bash
python3 tools/query.py --type problem --status open
```

### Q: 如何查看某个术语的正确用法？
```bash
python3 tools/query.py --term "术语"
```

### Q: 如何导出给团队成员看的报告？
```bash
python3 tools/export.py --output team_report.md
```

### Q: 记录太多了，如何快速找到关键信息？
- 使用`--keyword`精确搜索
- 使用`--type`过滤记录类型
- 使用`--status`过滤状态
- 查看索引文件（index.json）

## 记忆系统文件结构

```
memory/
├── README.md                          # 简介
├── USAGE_GUIDE.md                     # 使用指南（本文件）
├── documents/                         # 文档知识库
│   ├── index.json                     # 文档索引
│   └── *.json                         # 文档记录
├── problems/                          # 问题解决方案库
│   ├── index.json                     # 问题索引
│   └── *.json                         # 问题记录
├── decisions/                         # 设计决策日志
│   ├── index.json                     # 决策索引
│   └── *.json                         # 决策记录
├── principles/                        # NAC核心原则库
│   ├── index.json                     # 原则索引
│   ├── consensus.json                 # 共识原则
│   ├── terminology.json               # 术语映射
│   └── architecture.json              # 架构原则
└── tools/                             # 管理工具
    ├── query.py                       # 查询工具
    ├── add.py                         # 添加工具
    └── export.py                      # 导出工具
```

## 技术支持

如有问题，请查看：
- `README.md` - 系统简介
- `../docs/NAC_Memory_System_Design.md` - 详细设计文档
- `../docs/NAC_Memory_Report_*.md` - 导出的报告

---

*记忆系统是避免重复错误、保持知识连续性的关键工具，请坚持使用！*