8.2 KiB

Raw Permalink Blame History

NAC记忆系统使用指南

快速开始

1. 查询记忆

# 进入记忆系统目录
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. 添加新记录

# 添加文档记录
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. 导出报告

# 导出完整报告
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

工作流程

每次开始新任务前

查询相关文档

python3 tools/query.py --keyword "任务关键词"

查询相关问题历史

python3 tools/query.py --type problem --keyword "相关问题"

查询相关设计决策

python3 tools/query.py --type decision --keyword "相关决策"

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

每次阅读新文档后

立即记录文档核心思想

python3 tools/add.py document \
  --title "文档标题" \
  --path "/path/to/doc" \
  --summary "核心思想摘要" \
  --concepts "核心概念列表"

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

每次遇到问题时

先查询问题库

python3 tools/query.py --type problem --keyword "问题关键词"

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

如果是新问题，解决后立即记录

python3 tools/add.py problem \
  --title "问题标题" \
  --description "问题描述" \
  --solution "解决方案"

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

每次做重要决策时

记录决策

python3 tools/add.py decision \
  --title "决策标题" \
  --decision "决策内容" \
  --rationale "决策理由"

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

定期维护

每周一次：

# 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: 标签列表

示例：

{
  "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列表

示例：

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

决策记录

必填字段：

title: 决策标题
decision: 决策内容
rationale: 决策理由

建议补充：

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

示例：

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

最佳实践

1. 实时记录

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

2. 详细描述

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

3. 建立关联

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

4. 定期维护

✅ 每周审查新增记录
✅ 更新关联关系
✅ 导出备份
❌ 不要让记录过时

5. 查询优先

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

常见问题

Q: 如何快速查找某个概念？

python3 tools/query.py --keyword "概念名称"

Q: 如何查看所有未解决的问题？

python3 tools/query.py --type problem --status open

Q: 如何查看某个术语的正确用法？

python3 tools/query.py --term "术语"

Q: 如何导出给团队成员看的报告？

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 - 导出的报告

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

8.2 KiB Raw Permalink Blame History Unescape Escape

NAC记忆系统使用指南

快速开始

1. 查询记忆

2. 添加新记录

3. 导出报告

工作流程

每次开始新任务前

每次阅读新文档后

每次遇到问题时

每次做重要决策时

定期维护

记录规范

文档记录

问题记录

决策记录

最佳实践

1. 实时记录

2. 详细描述

3. 建立关联

4. 定期维护

5. 查询优先

常见问题

Q: 如何快速查找某个概念？

Q: 如何查看所有未解决的问题？

Q: 如何查看某个术语的正确用法？

Q: 如何导出给团队成员看的报告？

Q: 记录太多了，如何快速找到关键信息？

记忆系统文件结构

技术支持

8.2 KiB

Raw Permalink Blame History