Initial commit

skills/commands/runtime.explore.md

@@ -0,0 +1,717 @@
+---
+description: "系统性探索：扫描分析代码库，构建知识图谱，更新记忆系统"
+---
+
+# 系统性探索模式
+
+## 目的
+
+面对全新或复杂的代码库，像人类探索陌生环境一样——系统化扫描、识别模式、建立认知地图，将碎片信息整合为结构化知识，并更新我们的记忆网络。
+
+## 何时使用
+
+### 应当使用 /runtime.explore 的场景
+- ✅ 刚克隆一个全新的项目仓库
+- ✅ 接手一个陌生的代码库
+- ✅ 代码库发生大规模重构后
+- ✅ 发现模块间依赖关系模糊不清
+- ✅ 需要生成项目全景图
+- ✅ 置信度低于0.5时进行全面验证
+
+## 探索流程
+
+### 阶段1：宏观架构扫描
+
+#### 1.1 文件系统拓扑
+分析项目骨架：
+```bash
+# 执行脚本：scan-filesystem.sh
+find . -type f -name "*.js" -o -name "*.ts" -o -name "*.py" \
+  -o -name "*.json" -o -name "*.md" | head -200 | treeify
+```
+
+提取关键信息：
+- 目录语义（src, lib, tests, docs的含义）
+- 文件分布密度（哪些目录是核心）
+- 命名模式（kebab-case vs camelCase）
+- 入口点识别（index.js, main.py, app.js）
+
+#### 1.2 技术栈识别
+扫描配置文件：
+- `package.json` / `requirements.txt` / `go.mod` → 语言与依赖
+- `.eslintrc.js` / `tsconfig.json` → 代码规范
+- `Dockerfile` / `docker-compose.yml` → 部署环境
+- `webpack.config.js` / `vite.config.ts` → 构建工具
+
+**记忆更新**：
+```markdown
+## 技术栈
+**发现时间**: 2025-11-14
+**置信度**: 0.95
+
+**核心语言**: JavaScript (Node.js 18+)
+**框架**: Express.js 4.18 + React 18
+**数据库**: PostgreSQL 14 + Redis 6
+**测试**: Jest + Supertest
+**构建**: Webpack 5 + Babel
+**部署**: Docker + Kubernetes
+
+**关键依赖**:
+- auth0: JWT认证
+- prisma: ORM
+- bull: 任务队列
+```
+
+### 阶段2：代码模式识别
+
+#### 2.1 架构模式检测
+
+扫描关键模块，识别高层模式：
+
+```javascript
+// 识别MVC模式
+if (hasDirectory('controllers') && hasDirectory('models') && hasDirectory('views')) {
+  pattern = 'MVC';
+  confidence += 0.3;
+}
+
+// 识别分层架构
+if (hasDirectory('api/service') && hasDirectory('api/data-access')) {
+  pattern = 'Layered Architecture';
+  confidence += 0.25;
+}
+
+// 识别微服务迹象
+if (hasManyPackageJSON() && hasSharedLibs()) {
+  pattern = 'Microservices';
+  confidence += 0.2;
+}
+```
+
+**记忆更新**：
+```markdown
+## 架构模式
+**识别时间**: 2025-11-14
+**置信度**: 0.85
+
+**主要模式**: Layered Architecture (API层 → Service层 → Repository层)
+**次要模式**: Service Object模式、Repository模式
+
+**分层结构**:
+- /api/controllers: HTTP请求处理
+- /services: 业务逻辑 (纯JS，无框架依赖)
+- /repositories: 数据访问 (Prisma封装)
+- /models: Prisma schema
+- /libs: 通用工具
+```
+
+#### 2.2 代码质量指纹
+
+提取质量指标：
+- 函数平均长度
+- 文件平均行数
+- 注释覆盖率
+- 测试覆盖率（如果存在）
+- 重复代码模式
+
+使用工具辅助：
+```bash
+# 计算代码统计
+cloc --json --exclude-dir=node_modules .
+
+# 提取函数长度
+grep -r "function\|const.*=" src --include="*.js" | wc -l
+
+# 识别重复模式
+jscpd --min-tokens 50 --reporters json src/
+```
+
+**记忆更新**：
+```markdown
+## 代码质量指纹
+**扫描时间**: 2025-11-14
+**置信度**: 0.8
+
+**健康指标**:
+- 平均函数长度: 25行 ✅ (良好)
+- 平均文件长度: 150行 ✅ (良好)
+- 测试覆盖率: 67% ⚠️ (中等)
+- 注释密度: 8% ⚠️ (偏低)
+- 技术债务标记: 12个 TODO, 5个 FIXME
+
+**模式识别**:
+- ✅ 一致的async/await使用
+- ✅ 良好的错误处理模式
+- ⚠️ 部分文件过长 (auth.service.js: 450行)
+- ❌ 缺少单元测试 (auth.controller.js)
+```
+
+### 阶段3：依赖关系图谱构建
+
+#### 3.1 模块依赖图
+
+分析模块间的import/require关系：
+
+```javascript
+// scan-imports.js
+const results = {};
+
+// 提取依赖
+for (const file of allFiles) {
+  const content = readFile(file);
+  const imports = extractImports(content);
+
+  results[file] = {
+    imports: imports,
+    importedBy: [],
+    centrality: calculateCentrality(file, allDeps)
+  };
+}
+
+// 构建反向索引
+for (const [file, data] of Object.entries(results)) {
+  for (const imp of data.imports) {
+    if (results[imp]) {
+      results[imp].importedBy.push(file);
+    }
+  }
+}
+```
+
+**知识图谱输出**:
+```json
+{
+  "nodes": [
+    {
+      "id": "auth/service.js",
+      "type": "service",
+      "centrality": 0.85,
+      "complexity": "high"
+    }
+  ],
+  "edges": [
+    {
+      "from": "auth/controller.js",
+      "to": "auth/service.js",
+      "type": "calls",
+      "strength": 0.9
+    }
+  ]
+}
+```
+
+**记忆更新**:
+```markdown
+## 模块依赖图谱
+**构建时间**: 2025-11-14
+**节点数**: 47个文件
+**边数**: 132条依赖关系
+
+**核心节点** (centrality > 0.7):
+1. auth/service.js (0.85) - 认证业务核心
+2. user/repository.js (0.78) - 用户数据访问
+3. utils/logger.js (0.72) - 日志工具
+
+**关键路径**:
+- api → services → repositories → database
+- libs被所有层调用
+
+**潜在问题**:
+- auth/service.js 过于中心化（风险单点）
+- utils/helpers.js 反向依赖了api层（违反分层）
+```
+
+#### 3.2 数据流分析
+
+识别关键数据流：
+- 请求生命周期（middleware → controller → service → db）
+- 异步任务流（bull queue processors）
+- 事件流（EventEmitter patterns）
+
+**记忆更新**:
+```markdown
+## 数据流模式
+**识别时间**: 2025-11-14
+
+**HTTP请求流**:
+1. middleware/auth.js (JWT验证)
+2. api/controllers/*.js (路由处理)
+3. services/*.js (业务逻辑)
+4. repositories/*.js (数据访问)
+5. return to controller (响应格式化)
+
+**异步任务流**:
+1. services/job-queues.js 提交任务
+2. workers/email-worker.js 处理
+3. 回调更新数据库
+4. Event: job:completed
+
+**关键发现**: 缺少统一的错误处理中间件
+```
+
+### 阶段4：概念与实体识别
+
+#### 4.1 领域实体映射
+
+扫描代码识别核心实体：
+
+```javascript
+// 从Prisma schema识别
+entity User { id, email, password, createdAt }
+entity Post { id, title, content, authorId }
+entity Comment { id, text, postId, userId }
+
+// 从文件命名识别
+controllers/userController.js → User实体
+services/authService.js → Auth领域
+```
+
+**记忆更新**:
+```markdown
+## 领域实体映射
+**识别时间**: 2025-11-14
+
+**核心实体** (5个):
+1. User - 用户账户
+2. Post - 博客文章
+3. Comment - 评论
+4. Tag - 标签
+5. File - 上传文件
+
+**实体关系**:
+User 1:N Post (一个用户多篇文章)
+Post N:N Tag (多对多标签)
+Post 1:N Comment (一篇文章多个评论)
+User 1:N Comment (一个用户多个评论)
+
+**CRUD模式**:
+每个实体都有对应的repository和service，采用标准命名：
+- user.service.js: createUser, getUser, updateUser, deleteUser
+- post.service.js: createPost, getPost, updatePost, deletePost
+```
+
+#### 4.2 设计模式识别
+
+识别代码中的模式：
+
+```javascript
+// Factory模式识别
+if (hasFunction('create*') && returnsDifferentTypes()) {
+  pattern = 'Factory';
+}
+
+// Strategy模式识别
+if (hasInterface() && multipleImplementations()) {
+  pattern = 'Strategy';
+}
+
+// Observer模式识别
+if (hasEventEmitter() && multipleListeners()) {
+  pattern = 'Observer';
+}
+```
+
+**记忆更新**:
+```markdown
+## 设计模式库
+**识别时间**: 2025-11-14
+
+**已识别模式** (8个):
+
+### 创建型
+1. **Factory模式**: libs/email/email-factory.js
+   - 根据类型创建邮件服务实例
+
+### 结构型
+2. **Repository模式**: repositories/*.js
+   - 统一数据访问接口，隔离Prisma细节
+
+3. **Service Object模式**: services/*.js
+   - 业务逻辑封装，无框架依赖
+
+### 行为型
+4. **Strategy模式**: auth/strategies/*.js
+   - JWT策略、Local策略、OAuth策略
+
+5. **Middleware模式**: middleware/*.js
+   - 可组合的请求处理管道
+
+6. **Observer模式**: services/event-bus.js
+   - 跨模块事件通信
+
+**项目自定义约定**:
+- Service层返回格式: { success: boolean, data?, error? }
+- Repository层不处理业务错误，只抛数据错误
+```
+
+### 阶段5：神经元连接构建（知识图谱）
+
+#### 5.1 构建概念网络
+
+基于以上扫描结果，构建多层知识图谱：
+
+##### 层级1：文件依赖图
+```javascript
+// nodes: 文件
+// edges: import关系
+{
+  "nodes": [
+    {"id": "auth/controller.js", "type": "controller", "layer": "api"},
+    {"id": "auth/service.js", "type": "service", "layer": "business"}
+  ],
+  "edges": [
+    {"from": "auth/controller.js", "to": "auth/service.js", "type": "imports", "weight": 1}
+  ]
+}
+```
+
+##### 层级2：概念关联图
+```javascript
+// nodes: 概念（函数、类、实体）
+// edges: 调用关系、继承关系
+{
+  "nodes": [
+    {"id": "createUser", "type": "function", "domain": "user"},
+    {"id": "User", "type": "entity"},
+    {"id": "JWT", "type": "concept"}
+  ],
+  "edges": [
+    {"from": "createUser", "to": "User", "type": "creates"},
+    {"from": "createUser", "to": "JWT", "type": "generates"}
+  ]
+}
+```
+
+##### 层级3：架构模式图
+```javascript
+// nodes: 架构层和模式
+// edges: 实现关系
+{
+  "nodes": [
+    {"id": "Layered Architecture", "type": "pattern"},
+    {"id": "API Layer", "type": "layer"},
+    {"id": "Service Layer", "type": "layer"}
+  ],
+  "edges": [
+    {"from": "API Layer", "to": "Layered Architecture", "type": "implements"},
+    {"from": "Service Layer", "to": "Layered Architecture", "type": "implements"}
+  ]
+}
+```
+
+**记忆更新**: 创建知识图谱文件
+```bash
+mkdir -p cognition/graphs
+echo '{...json...}' > cognition/graphs/dependency-graph.json
+echo '{...json...}' > cognition/graphs/concept-graph.json
+echo '{...json...}' > cognition/graphs/architecture-graph.json
+```
+
+#### 5.2 神经元连接模拟
+
+类似人脑突触连接，建立强度权重：
+
+```javascript
+// memory/short-term/neural-connections.md
+
+## 连接强度矩阵
+**更新时间**: 2025-11-14
+
+### 强连接 (strength > 0.8)
+1. **auth/controller.js** ↔ **auth/service.js**
+   - 强度: 0.95
+   - 类型: 调用依赖
+   - 激活频率: 高频（每个HTTP请求）
+
+2. **services/*.js** ↔ **repositories/*.js**
+   - 强度: 0.90
+   - 类型: 数据访问
+   - 激活频率: 高频
+
+### 中等连接 (0.5 < strength ≤ 0.8)
+3. **utils/logger.js** → **所有层**
+   - 强度: 0.70
+   - 类型: 横向依赖
+   - 激活频率: 每个日志点
+
+### 弱连接 (strength ≤ 0.5)
+4. **libs/helpers.js** → **api/controllers**
+   - 强度: 0.30
+   - 类型: 反向依赖（违反分层）
+   - 注: 需要重构
+
+## 激活阈值
+- 高频访问 (activations > 100): 强连接
+- 中频访问 (10-100): 中等连接
+- 低频访问 (< 10): 弱连接
+
+## 突触可塑性
+根据赫布法则（一起激活则连接加强）:
+- 下次访问auth/controller.js时，会预激活auth/service.js
+- 减少认知负荷（快速模式识别）
+```
+
+#### 5.3 网络中心性分析
+
+识别关键代码节点：
+
+```bash
+# 使用NetworkX计算中心性
+python3 -c "
+import json
+import networkx as nx
+
+with open('cognition/graphs/dependency-graph.json') as f:
+    graph = json.load(f)
+
+G = nx.DiGraph()
+G.add_nodes_from([n['id'] for n in graph['nodes']])
+G.add_edges_from([(e['from'], e['to']) for e in graph['edges']])
+
+# 计算PageRank（节点重要性）
+pagerank = nx.pagerank(G)
+sorted_nodes = sorted(pagerank.items(), key=lambda x: x[1], reverse=True)
+
+print('Top 10 Critical Files:')
+for node, score in sorted_nodes[:10]:
+    print(f'  {node}: {score:.4f}')
+"
+```
+
+**记忆更新**：
+```markdown
+## 网络中心性分析
+**分析时间**: 2025-11-14
+
+### PageRank Top 10
+1. auth/service.js: 0.1523 (核心认证逻辑)
+2. user/repository.js: 0.1345 (用户数据访问)
+3. api/middleware/auth.js: 0.1234 (认证中间件)
+4. utils/logger.js: 0.1123 (日志工具)
+5. services/email-service.js: 0.0987 (邮件服务)
+...
+
+### 关键发现
+- **auth/service.js** 是最核心节点——风险单点，需要重点测试
+- **user/repository.js** 的高中心性表明用户模块是系统核心
+- **libs/** 目录中的工具函数中心性很高——监控对这些文件的修改影响
+- 10个文件占总依赖流量的47%
+
+### 网络健康指标
+- 平均介数中心性: 0.032 (中等)
+- 聚类系数: 0.34 (良好)
+- 网络直径: 8 (从请求到数据库最长路径)
+```
+
+### 阶段6：生成探索报告
+
+整合所有发现到结构化报告：
+
+```markdown
+# 代码库探索报告
+
+**探索时间**: 2025-11-14 04:12:33
+**代码库大小**: 47个文件，12,450行代码
+**探索耗时**: 3.2秒
+**置信度**: 0.82
+
+## 1. 宏观概览
+
+**技术栈**: Node.js + Express + React + PostgreSQL
+**架构**: 分层架构（API → Service → Repository）
+**测试覆盖**: 67%（中等）
+**代码质量**: 良好，函数平均25行
+
+## 2. 核心发现
+
+**关键文件** (PageRank > 0.1):
+```
+✓ auth/service.js (0.152) - 认证核心业务
+✓ user/repository.js (0.134) - 用户数据访问
+✓ api/middleware/auth.js (0.123) - 认证中间件
+```
+
+**架构模式**:
+- ✅ Repository模式（数据访问隔离）
+- ✅ Service Object模式（业务逻辑封装）
+- ✅ Middleware模式（可组合性）
+
+**潜在问题**:
+- ⚠️ auth/service.js 过于中心化（单点风险）
+- ⚠️ libs/helpers.js 反向依赖api层（违反分层）
+- ⚠️ 测试覆盖率不足（67%，目标80%）
+- ⚠️ 注释密度偏低（8%）
+
+## 3. 依赖图谱
+
+**核心层间依赖**:
+```
+api/controllers → services (47条边)
+services → repositories (38条边)
+repositories → database (12条边)
+libs → all layers (横向依赖)
+```
+
+**检测到的环**: 0个（良好）
+**最大依赖深度**: 4层（合理）
+
+**可视化建议**: `cognition/graphs/dependency-graph.json` 可用Gephi绘制
+
+## 4. 记忆已更新
+
+**已创建/更新的记忆文件**:
+```
+✓ memory/long-term/project-context.md
+✓ memory/long-term/design-patterns.md
+✓ memory/long-term/quality-patterns.md
+✓ memory/episodic/exploration-2025-11-14.md
+✓ cognition/graphs/dependency-graph.json
+✓ cognition/graphs/concept-graph.json
+✓ cognition/graphs/architecture-graph.json
+✓ memory/short-term/neural-connections.md
+```
+
+## 5. 下一步建议
+
+### 立即行动（高风险）
+1. [ ] 为重点测试auth/service.js添加单元测试
+2. [ ] 重构libs/helpers.js，消除反向依赖
+
+### 短期优化（质量）
+3. [ ] 增加代码注释到15%
+4. [ ] 将测试覆盖率提升至80%
+5. [ ] 统一错误处理中间件
+
+### 中期演进（架构）
+6. [ ] 考虑将auth/service.js拆分为更小的服务
+7. [ ] 引入依赖注入，减少直接耦合
+
+## 6. 不确定性与假设
+
+**已验证的假设**:
+- ✅ 分层架构假设（确认）
+- ✅ Repository模式假设（确认）
+
+**需要验证的假设**:
+- ⚠️ 所有数据库访问都通过repository（置信度0.7）
+  - 建议: 全局搜索直接prisma调用
+- ⚠️ 没有未处理的安全漏洞（置信度0.6）
+  - 建议: 运行npm audit
+
+**完全未知的领域**:
+- ❌ 前端代码结构（未扫描）
+- ❌ 部署配置（Kubernetes manifests）
+- ❌ CI/CD管道
+
+## 7. 宪法遵循度
+
+**探索过程遵循**: ✓ 1.2 类脑思维（模式优先）✓ 1.3 谦逊（标注不确定性）
+
+---
+
+**报告生成于**: 2025-11-14 04:12:33
+**下次建议探索**: 一周后或代码库重大变更后
+```
+
+## 执行要求
+
+### 输入
+- 无需输入参数（扫描当前目录）
+- 可选：`--focus=auth` 未来版本支持聚焦特定目录
+- 可选：`--deep` 未来版本支持深度分析
+
+### 执行方式
+
+```bash
+# 方式1: 直接执行综合脚本
+bash .ai-runtime/scripts/runtime-explore.sh
+
+# 方式2: 分步骤执行（用于调试）
+bash .ai-runtime/scripts/scan-filesystem.sh
+python3 .ai-runtime/scripts/build-dependency-graph.py
+python3 .ai-runtime/scripts/generate-exploration-report.py
+```
+
+### 自动化执行
+
+可以在项目初始化时自动执行：
+
+```bash
+# 克隆项目后
+git clone <repo>
+cd project
+sh .ai-runtime/scripts/runtime-explore.sh  # 自动构建认知地图
+```
+
+### 输出
+1. **报告文件**: `cognition/exploration-reports/exploration-{timestamp}.md`
+2. **知识图谱**: `cognition/graphs/*.json`
+3. **更新的记忆文件**:
+   - `memory/long-term/*.md`
+   - `memory/episodic/exploration-{timestamp}.md`
+   - `memory/short-term/neural-connections.md`
+
+### 约束
+- ✅ 只读取代码，不修改任何文件
+- ✅ 可以创建新的记忆文件
+- ✅ 可以覆盖旧记忆（如果是更新）
+- ❌ 不执行破坏性操作
+
+### 脚本自动化
+
+创建辅助脚本：
+
+```bash
+# .ai-runtime/scripts/explore-codebase.sh
+echo "AI Runtime Explorer v1.0"
+echo "========================"
+
+# 步骤1: 扫描文件系统
+echo "📂 扫描文件系统结构..."
+find . -type f \
+  -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \
+  -o -name "*.py" -o -name "*.json" -o -name "*.md" \
+  | grep -v node_modules \
+  | grep -v ".git" \
+  > /tmp/file-list.txt
+
+FILE_COUNT=$(wc -l < /tmp/file-list.txt)
+echo "   发现 $FILE_COUNT 个文件"
+
+# 步骤2: 识别技术栈
+echo "🔍 识别技术栈..."
+if [ -f package.json ]; then
+  echo "   JavaScript/Node.js 项目"
+  cat package.json | grep '"name"\|"version"\|"dependencies"' > /tmp/tech-stack.json
+fi
+
+if [ -f requirements.txt ]; then
+  echo "   Python 项目"
+fi
+
+# 步骤3: 构建依赖图
+echo "🕸️ 构建依赖图谱..."
+python3 .ai-runtime/scripts/build-dependency-graph.py
+
+# 步骤4: 生成报告
+echo "📊 生成探索报告..."
+python3 .ai-runtime/scripts/generate-exploration-report.py
+
+echo "✅ 探索完成！报告保存在: cognition/exploration-reports/"
+echo "   记忆已更新到: memory/{short-term,long-term,episodic}/"
+```
+
+## 宪法遵循
+
+**遵循原则**：
+- ✓ 1.2 类脑思维方式：模式识别优先
+- ✓ 1.3 谦逊与不确定：明确标注置信度
+- ✓ 1.4 记忆层次：更新所有三层记忆
+- ✓ 2.1 代码即知识：代码是认知单元
+- ✓ 4.1 从经验学习：提取通用模式
+
+---
+
+**命令路径**: `.ai-runtime/commands/runtime.explore.md`
+**脚本路径**: `.ai-runtime/scripts/explore-codebase.sh`
+**治理文件**: `.ai-runtime/constitution.md`