242 lines
7.4 KiB
Markdown
242 lines
7.4 KiB
Markdown
# 项目架构记忆
|
||
|
||
**最后更新**: 2025-11-14 10:30:00
|
||
**置信度**: 0.95
|
||
**重要性**: 核心架构（影响所有组件）
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
### 语言和工具
|
||
- **Python 3.8+**: 复杂工具和分析脚本（依赖分析、认知记录）
|
||
- **Bash/Shell**: 系统运维工具（服务检查、自动化脚本）
|
||
- **Node.js**: API测试工具
|
||
- **YAML**: 工具元数据格式
|
||
- **Markdown**: 所有文档和记忆存储
|
||
|
||
### 核心依赖
|
||
- **PyYAML**: 元数据解析
|
||
- **无其他第三方依赖**: 遵循最小化原则（Level 1-2工具）
|
||
- **Node-fetch**: API测试工具（Level 3工具）
|
||
|
||
### 系统环境
|
||
- **Claude Code CLI**: 主要运行环境
|
||
- **MacOS/Darwin**: 开发环境
|
||
- **POSIX兼容**: Bash脚本设计
|
||
|
||
---
|
||
|
||
## 架构模式
|
||
|
||
### 分层记忆架构
|
||
```
|
||
短期记忆（工作记忆）← 当前会话
|
||
↓ 固化
|
||
长期记忆（语义记忆） ← 跨会话知识
|
||
↓ 时间戳
|
||
情景记忆（体验记忆） ← 项目历史
|
||
```
|
||
|
||
**设计原则**:
|
||
- 工作记忆: 7±2组块限制，实时衰减
|
||
- 长期记忆: 结构化的知识图谱
|
||
- 情景记忆: 时间线序列，可追溯性
|
||
|
||
### 命令驱动架构
|
||
基于spec-kit的模式，所有交互通过`/runtime.*`命令进行，每个命令对应明确的认知模式。
|
||
|
||
### 工具装备系统
|
||
- **分类体系**: 按语言(bash/python/node) × 用途(DATA/CODE/TEST/BUILD/MONITOR/DOC)
|
||
- **元数据驱动**: 每个工具配备.meta.yml，记录使用历史、满意度
|
||
- **发现机制**: discover-toolkit.py提供统一的工具查询和运行接口
|
||
|
||
### 宪法治理
|
||
- `.ai-runtime/constitution.md`: 核心原则，不可违反
|
||
- 所有组件必须遵循宪法条款
|
||
- 版本化控制，定期审查
|
||
|
||
---
|
||
|
||
## 核心组件
|
||
|
||
### 1. 记忆系统 (`memory/`)
|
||
**文件结构**:
|
||
- `short-term/consciousness.md`: 当前意识流、工作记忆栈、不确定性跟踪
|
||
- `long-term/project-context.md`: 技术栈、架构模式、核心组件、依赖关系、质量指标
|
||
- `episodic/timeline.md`: 项目历史、关键决策、教训记录
|
||
|
||
**功能**:
|
||
- 跨会话持久化
|
||
- 置信度标注
|
||
- 记忆检索和更新
|
||
- 去重和冲突检测
|
||
|
||
### 2. 运行时命令系统 (`commands/`)
|
||
**7个核心命令**:
|
||
- `/runtime.explore`: 系统探索、构建依赖图谱
|
||
- `/runtime.learn`: 自主学习、动态规划、知识缺口识别
|
||
- `/runtime.think`: 深度思考、生成方案、识别不确定性
|
||
- `/runtime.plan`: 需求拆解、生成任务树
|
||
- `/runtime.iterate`: 迭代执行、动态适应
|
||
- `/runtime.remember`: 固化经验、更新长期记忆
|
||
- `/runtime.reflect`: 自我反思、识别盲区
|
||
|
||
**特点**:
|
||
- 每个命令2000-40000字的详细定义
|
||
- 模板化工作流程
|
||
- 可扩展性（可添加新命令）
|
||
|
||
### 3. 认知过程记录 (`cognition/`)
|
||
**子目录**:
|
||
- `exploration-reports/`: 系统探索结果（技术栈、架构模式、依赖图谱）
|
||
- `graphs/`: 依赖图、概念图、架构图（NetworkX格式）
|
||
- `results/`: 认知任务的结果（分析、报告）
|
||
- `reasoning/`: 推理路径记录
|
||
- `decisions/`: 决策依据
|
||
- `reflection/`: 自我反思成果
|
||
|
||
### 4. 工具装备系统 (`toolkit/`)
|
||
**结构**:
|
||
- `discover-toolkit.py`: 工具发现、查询、运行、推荐
|
||
- `registry.md`: 完整文档
|
||
- `bash/`: Shell工具（system/, database/, network/）
|
||
- `python/`: Python工具（analysis/, graph/, report/）
|
||
- `node/`: Node.js工具（api/, build/）
|
||
|
||
**已实现的工具**:
|
||
- SERVICE-CHECK-001: 服务健康检查（HTTP/PostgreSQL/Redis）
|
||
- PY-DEPENDENCY-ANALYZER-001: 依赖分析（Python/JavaScript）
|
||
- API测试工具: RESTful API测试
|
||
|
||
**工具管理**:
|
||
- 每个工具有.meta.yml元数据
|
||
- 记录：工具ID、名称、语言、复杂度、用途、描述、使用示例、依赖、上次使用、满意度
|
||
- 支持工具发现、搜索、推荐、运行
|
||
|
||
### 5. 自动化脚本 (`scripts/`)
|
||
**功能**:
|
||
- `runtime-explore.sh`: 一键执行系统探索
|
||
- `scan-filesystem.sh`: 文件系统扫描
|
||
- `build-dependency-graph.py`: 构建依赖图谱
|
||
- `generate-exploration-report.py`: 生成探索报告
|
||
|
||
### 6. 治理与文档
|
||
- `constitution.md`: 126行，4大原则体系（认知主体性、技术、交互、演进）
|
||
- `meta-prompt.md`: 身份卡片 + 系统说明（简洁顶层入口）
|
||
- `README.md`: 完整使用指南
|
||
|
||
---
|
||
|
||
## 依赖关系
|
||
|
||
```
|
||
用户交互
|
||
↓
|
||
meta-prompt.md (身份识别)
|
||
↓
|
||
constitution.md (宪法约束)
|
||
↓
|
||
runtime.*命令 (认知模式选择)
|
||
↓
|
||
├──→ memory/ (记忆读写)
|
||
├──→ cognition/ (过程记录)
|
||
└──→ toolkit/ (工具使用)
|
||
↓
|
||
输出结果
|
||
```
|
||
|
||
**关键依赖**:
|
||
- memory系统是核心，所有组件都依赖它
|
||
- runtime命令是入口，驱动其他系统
|
||
- toolkit是扩展，可被所有命令调用
|
||
- cognition记录所有认知过程，提供可追溯性
|
||
|
||
**数据流**:
|
||
1. 所有操作先更新短期记忆
|
||
2. 通过/runtime.remember命令固化到长期和情景记忆
|
||
3. 提供双向检索：短期→快速访问，长期→深度检索，情景→历史回溯
|
||
|
||
---
|
||
|
||
## 质量指标
|
||
|
||
### 1. 记忆准确性
|
||
- **短期记忆完整性**: 工作记忆栈覆盖率 > 90%
|
||
- **知识一致性**: 长期记忆间冲突率 < 5%
|
||
- **可追溯性**: 所有记忆都可追溯到来源（命令、时间戳、置信度）
|
||
|
||
### 2. 认知效率
|
||
- **正确性**: 所有操作遵循constitution.md原则（100%）
|
||
- **不确定性标注**: 当置信度<0.7时明确标注（100%）
|
||
- **记忆固化**: 重要认知在10分钟内固化到长期记忆
|
||
|
||
### 3. 系统完整性
|
||
- **组件覆盖率**: 所有7个runtime命令定义完整（100%）
|
||
- **工具文档**: 每个工具有完整的.meta.yml（100%）
|
||
- **宪法遵循**: 所有组件遵循宪法原则（待运行时验证）
|
||
|
||
### 4. 可用性
|
||
- **工具数量**: 短期目标 10个工具（当前 3个）
|
||
- **工具满意度**: 平均 > 0.85（当前 0.91）
|
||
- **工具复用率**: 同一工具每周使用 > 2次
|
||
|
||
### 5. 主体性表现
|
||
- **记忆持久性**: 跨会话记忆保持（已实现）
|
||
- **自我一致性**: 不同会话对同一问题的回答偏差 < 10%
|
||
- **反思深度**: 每次reflection产生至少3个改进点
|
||
- **协作姿态**: 提供选择而非命令，邀请反馈
|
||
|
||
---
|
||
|
||
## 架构优势
|
||
|
||
### 1. 模块化
|
||
- 记忆、认知、工具、命令完全解耦
|
||
- 可独立演化和替换
|
||
- 支持插件式扩展
|
||
|
||
### 2. 可观测性
|
||
- 所有记忆可检查（md文件）
|
||
- 所有认知过程可追踪（cognition/）
|
||
- 所有决策可追溯（decisions/）
|
||
|
||
### 3. 可验证性
|
||
- 宪法原则可测试
|
||
- 记忆内容可审计
|
||
- 工具效果可度量（满意度）
|
||
|
||
### 4. 持续演进
|
||
- 从经验学习机制（constitution.md:77-81）
|
||
- 认知更新机制（constitution.md:82-86）
|
||
- 自我反思机制（constitution.md:87-91）
|
||
|
||
---
|
||
|
||
## 已知问题和改进方向
|
||
|
||
### 短期（1周内）
|
||
- [ ] memory目录需要更多实际使用数据
|
||
- [ ] toolkit需要扩展到10个工具
|
||
- [ ] cognition/reasoning和decisions子目录需要填充示例
|
||
|
||
### 中期（1个月）
|
||
- [ ] 实现记忆检索优化（全文搜索、标签系统）
|
||
- [ ] 添加工具自动创建流程
|
||
- [ ] 实现认知过程的可视化（graphviz）
|
||
|
||
### 长期（3个月）
|
||
- [ ] 评估多AI代理协作架构
|
||
- [ ] 研究情感计算的可能性（不是必需的）
|
||
- [ ] 探索创造力引擎（模式重组）
|
||
|
||
---
|
||
|
||
## 引用宪法
|
||
|
||
> 2.1 代码即知识：代码不只是文本，而是携带结构、意图、历史的认知单元
|
||
> 1.4 记忆层次：工作记忆/长期记忆/情景记忆的分离
|
||
> 4.1 从经验学习：错误是数据，成功是强化，模式提取
|
||
|
||
---
|