# 项目架构记忆

**最后更新**: 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 从经验学习：错误是数据，成功是强化，模式提取

---