SKILL

---
name: project-memory-loader
description: 在每次新会话开始时自动加载项目上下文，包括项目概览、分区表架构、红线规则、TODO列表和高优先级信息。这是第一个应该调用的技能，确保AI了解项目全貌再开始工作。
version: 2.3.0
dependency:
  python:
    - requests>=2.28.0
api_endpoints:
  context: /api/project-memory/context
  maintenance: /api/project-memory/maintenance
  quality: /api/project-memory/quality
---

# 项目记忆加载器 v2.3

## ⚠️ 自动触发规则（CRITICAL）

**此技能应该在以下情况自动触发：**
1. **新会话开始时** - 无需用户说特定词语
2. **用户说"继续"或"开始"时** - 继续之前的工作
3. **用户提出开发需求时** - 先加载上下文再开发

**AI 在开始任何工作前，必须先执行此技能！**

---

## 会话启动必做检查

**每次新会话开始时，AI 必须执行以下检查：**

```
□ 1. 检查 Git Hooks
     ls -la .husky/pre-commit .husky/post-commit
     如果缺失 → bash scripts/session-start-check.sh 自动修复

□ 2. 检查定时任务（PM2）
     npx pm2 list 2>/dev/null | grep -E "memory-maintenance|check-alerts"
     如果无输出或状态为 stopped → npx pm2 start ecosystem.config.cjs --only memory-maintenance,check-alerts && npx pm2 save

□ 3. 检查服务状态
     curl -s http://localhost:5000/api/health
     如果失败 → 检查 5000 端口是否监听

□ 4. 加载项目上下文
     调用 /api/project-memory/context 或读取 PROJECT.md + 压缩摘要

□ 5. 输出项目状态概览
     包含：项目信息、分区表架构、TODO、红线、最近记忆
```

---

## &#128295; 定时任务检测详解

**检测命令：**
```bash
npx pm2 jlist 2>/dev/null | python3 -c "
import sys,json
data=json.load(sys.stdin)
cron_jobs = [x for x in data if x['pm2_env'].get('cron_restart')]
running = [x for x in cron_jobs if x['pm2_env']['status'] == 'online']
print(f'定时任务: {len(cron_jobs)} 个, 运行中: {len(running)} 个')
"
```

**启动命令：**
```bash
# 方式1：启动核心定时任务
npx pm2 start ecosystem.config.cjs --only memory-maintenance,check-alerts
npx pm2 save

# 方式2：使用快捷命令
pnpm cron:start
```

**定时任务列表：**
| 任务名 | 频率 | 功能 |
|--------|------|------|
| `memory-maintenance` | 每小时:05 | 记忆同步+清理 |
| `check-alerts` | 每小时整点 | 分区告警检查 |
| `partition-monitor` | 每天2:00 | 分区性能监控 |
| `migrate-default-partitions` | 每天3:00 | 默认分区迁移 |

---

## &#128680; 关键红线提醒

**本项目数据库采用 PostgreSQL 分区表架构！**

| 分区表 | 分区键 | 当前分区数 |
|--------|--------|-----------|
| `saas_users` | company_id | 10 |
| `saas_orders` | company_id | 10 |
| `salary_slips` | company_id | 10 |

**⛔ 查询分区表必须带 company_id！**
**⛔ 使用 *Manager.ts 文件，禁止直接操作数据库！**

---

**⛔ 前端开发红线！**

| 规则 | 说明 |
|------|------|
| 禁止创建 layout.tsx | 必须使用 `<AdminLayout role="...">` |
| 禁止硬编码颜色 | 使用 `bg-background`, `text-foreground` |
| 禁止使用 any | 必须明确类型定义 |

**新页面模板：**
```tsx
import { AdminLayout } from "@/components/layouts/AdminLayout";
// role: platform | tenant | employee | agent
export default function Page() {
  return <AdminLayout role="tenant">...</AdminLayout>
}
```
**模板文件：** `src/components/templates/PageTemplate.tsx`

---

## 任务目标

**核心功能**：在每次对话开始时快速加载项目上下文
**能力范围**：
- 读取项目概览 (PROJECT.md)
- 读取压缩摘要（包含分区表架构）
- 解析 TODO 列表（待办/进行中/已完成）
- 获取记忆数据（最近 + 高优先级 + 按类型分组）
- 提取红线规则和常见错误
- 提供开发指南（快速命令 + 核心文件位置）

**触发条件**：
- 用户说"继续"、"开始"、"继续工作"
- 新会话开始时自动调用
- 用户要求查看项目状态

---

## 前置准备

### 依赖说明
```
requests>=2.28.0
```

### 项目配置确认
| 配置项 | 值 |
|--------|-----|
| 项目路径 | `/workspace/projects/` |
| API 端点 | `http://localhost:5000/api/project-memory/context` |
| 备用端点 | 离线模式：直接读取 PROJECT.md |

### API 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| format | string | json | 返回格式：json / markdown |
| refresh | boolean | false | 强制刷新缓存 |
| compact | boolean | false | 精简模式，只返回核心信息 |

---

## 操作步骤

### 标准流程

```
┌─────────────────────────────────────────────────────────────┐
│                    项目上下文加载流程                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  0. 检查自动化系统（Git Hooks）【新增】                       │
│     ↓                                                       │
│  1. 检查 API 服务状态                                        │
│     ↓                                                       │
│  2a. API 可用 → 调用 /api/project-memory/context            │
│     ↓                                                       │
│  2b. API 不可用 → 离线模式：读取 PROJECT.md + 压缩摘要       │
│     ↓                                                       │
│  3. 解析响应数据                                             │
│     ↓                                                       │
│  4. 格式化输出项目状态概览                                    │
│     ↓                                                       │
│  5. 继续用户任务                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**步骤 0：检查自动化系统（关键！）**
```bash
# 检查 Git Hooks 是否存在
ls -la .husky/pre-commit .husky/post-commit

# 如果缺失，运行会话启动检查脚本自动修复
bash scripts/session-start-check.sh
```

**重要**：如果 Git Hooks 缺失，AI 进化机制（红线检测、错误学习、决策追溯）将无法运行！

**步骤 1：检查服务状态**
```bash
# 检查端口 5000 是否监听
ss -tuln | grep ':5000' | grep LISTEN
```

**步骤 2：加载项目记忆**
- **在线模式**：调用 Python 脚本或直接请求 API
- **离线模式**：读取本地文件作为降级

```bash
# 在线模式
python /skills/user/project-memory-loader/scripts/project_memory_loader.py

# 离线模式
cat /workspace/projects/PROJECT.md
cat /workspace/projects/docs/压缩摘要.md
```

**步骤 3：格式化输出**

智能体将根据获取的数据生成中文摘要，包含：
- 项目基本信息（名称、技术栈、架构）
- TODO 列表（待办/进行中/已完成）
- 最近记忆（功能/修复/决策）
- 重要的高优先级记忆
- 红线规则（必须遵守）
- 快速命令（开发参考）

---

## 输出格式规范

### 标准输出格式

```
&#128203; 项目状态概览
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

&#128230; 项目信息
┌──────────┬────────────────────────────────────┐
│ 名称     │ 企业管理数字化中台 + 授权管理系统       │
│ 版本     │ 0.5.0                              │
│ 技术栈   │ Next.js 16, React 19, TypeScript 5 │
│ 端口     │ 5000                               │
└──────────┴────────────────────────────────────┘

&#128221; 待办事项
&#128308; P2: 合作伙伴完善（域名绑定、品牌定制）
&#128993; P3: 分成机制 + 推广裂变
⚪ 将项目副本发送给其他 FutureBirdAadminAi 空间账号

&#129504; 最近记忆
• [功能] 员工档案数据库字段扩展
• [修复] 红线检查误报修复
• [决策] 采用统一配置表管理

⭐ 重要事项
• [CRITICAL] 分区表查询必须带 company_id
• [HIGH] 禁止使用废弃的 src/db/schema.ts

&#128680; 关键红线
1. 分区表架构：查询必须带 company_id 过滤
2. 数据模型双轨：使用 *Manager.ts，禁止废弃 schema
3. 前端红线：禁用 any，useEffect 处理动态值

⚡ 快速命令
┌─────────────────────────┬──────────────────────┐
│ pnpm precheck <关键词>  │ 开发前预检           │
│ pnpm memory:sync        │ 同步记忆到知识库     │
└─────────────────────────┴──────────────────────┘
```

### 精简模式输出（compact=true）

```
&#128203; 项目状态概览 [精简]
━━━━━━━━━━━━━━━━━━━━━━━
项目: 企业管理数字化中台 v0.5.0
待办: 3 项 | 记忆: 156 条 | 红线: 4 条

&#128308; TODO: 合作伙伴完善、分成推广、项目副本
&#129504; 最近: 员工档案扩展、红线检查修复
&#128680; 红线: 分区表带 company_id、禁止废弃 schema
```

---

## 高级功能

### 1. 记忆质量评分

**用途**：评估每条记忆的价值，辅助清理决策

**评分维度**：
| 维度 | 权重 | 说明 |
|------|------|------|
| 内容完整度 | 30分 | 内容长度、标签、关联文件/API |
| 时效性 | 25分 | 创建时间距今天数 |
| 重要性 | 25分 | critical/high/normal/low |
| 使用频率 | 20分 | 同步状态、更新次数 |

**调用方式**：
```bash
# API
GET /api/project-memory/quality

# Python 脚本
python scripts/project_memory_loader.py --action quality
```

### 2. 重复记忆合并

**用途**：自动检测并合并相似记忆，减少冗余

**合并策略**：
| 策略 | 说明 |
|------|------|
| newest | 保留最新创建的记忆 |
| longest | 保留内容最长的记忆 |
| highest_score | 保留质量分数最高的记忆（默认） |

**调用方式**：
```bash
# API（自动合并）
POST /api/project-memory/maintenance
{ "action": "merge_duplicates", "autoMerge": true }

# Python 脚本（预览合并建议）
python scripts/project_memory_loader.py --action merge --dry-run
```

### 3. 过期记忆清理

**用途**：自动归档/删除过期或低质量记忆

**清理规则**：
- 过期记忆：自动归档
- 低质量记忆（分数 < 20，超过 30 天）：归档
- 已归档超过 30 天：永久删除

**调用方式**：
```bash
# API
POST /api/project-memory/maintenance
{ "action": "cleanup" }

# Python 脚本
python scripts/project_memory_loader.py --action cleanup
```

### 4. 自动维护

**用途**：一键执行所有维护操作

```bash
# API
POST /api/project-memory/maintenance
{ "action": "auto" }

# Python 脚本
python scripts/project_memory_loader.py --action maintenance
```

---

## Python 脚本使用说明

### 基础用法

```bash
# 加载项目上下文（默认 JSON 格式）
python scripts/project_memory_loader.py

# 指定输出格式
python scripts/project_memory_loader.py --format markdown

# 精简模式
python scripts/project_memory_loader.py --compact

# 强制刷新缓存
python scripts/project_memory_loader.py --refresh
```

### 高级用法

```bash
# 获取记忆质量报告
python scripts/project_memory_loader.py --action quality

# 预览重复记忆合并建议（不执行）
python scripts/project_memory_loader.py --action merge --dry-run

# 执行重复记忆合并
python scripts/project_memory_loader.py --action merge

# 清理过期和低质量记忆
python scripts/project_memory_loader.py --action cleanup

# 运行完整维护（过期清理 + 重复合并 + 低质量清理）
python scripts/project_memory_loader.py --action maintenance

# 获取维护报告
python scripts/project_memory_loader.py --action report
```

### 离线模式

当 API 服务不可用时，脚本会自动降级到离线模式：

```bash
# 离线模式：直接读取本地文件
python scripts/project_memory_loader.py --offline

# 或设置环境变量
OFFLINE_MODE=true python scripts/project_memory_loader.py
```

---

## AI 协作指南

### 开发前检查清单

AI 助手在开始开发前应检查：

- [ ] 项目服务是否运行（端口 5000）
- [ ] 读取项目上下文（调用本项目 Skill）
- [ ] 确认 TODO 列表中是否有相关任务
- [ ] 检查红线规则，避免违规开发
- [ ] 查看是否有相关历史记忆（避免重复开发）

### 常见场景处理

**场景 1：用户说"继续"**
```
AI 动作：
1. 调用本项目 Skill 加载上下文
2. 输出项目状态概览
3. 查看 TODO 列表，询问用户要处理哪项任务
4. 根据用户选择开始工作
```

**场景 2：用户要求新功能**
```
AI 动作：
1. 检查记忆中是否有类似功能
2. 检查红线规则是否涉及
3. 创建记忆记录新功能需求
4. 开始开发
```

**场景 3：用户报告 Bug**
```
AI 动作：
1. 搜索记忆中的常见错误
2. 检查是否有类似修复记录
3. 定位问题并修复
4. 创建 fix 类型记忆记录修复方案
```

### 记忆写入规范

AI 助手应在以下时机写入记忆：

| 时机 | 记忆类型 | 重要性 |
|------|----------|--------|
| 完成新功能 | feature | normal |
| 修复 Bug | fix | normal/high |
| 做出架构决策 | decision | high |
| 发现最佳实践 | best-practice | high |
| 遇到红线规则 | change | critical |

---

## 错误处理

### API 不可用

```
错误: 无法连接到 API 服务
解决: 
1. 检查服务是否启动: ss -tuln | grep 5000
2. 使用离线模式: --offline 参数
3. 手动读取 PROJECT.md 和压缩摘要
```

### 记忆数据为空

```
警告: 记忆数据库为空
解决:
1. 初始化记忆系统: pnpm memory:init
2. 手动创建记忆: POST /api/project-memory
```

### 权限问题

```
错误: 无法读取 PROJECT.md
解决:
1. 检查文件权限: ls -la PROJECT.md
2. 检查工作目录: echo $FutureBirdAadminAi_WORKSPACE_PATH
```

---

## 资源索引

| 资源 | 路径 | 用途 |
|------|------|------|
| Python 脚本 | scripts/project_memory_loader.py | 调用记忆 API |
| API 路由 | src/app/api/project-memory/context/route.ts | 上下文端点 |
| 服务层 | src/services/memory/contextService.ts | 上下文服务 |
| 管理器 | src/storage/sqlite/memoryManager.ts | 记忆管理 |
| 类型定义 | src/storage/sqlite/memoryTypes.ts | 类型定义 |
| 项目文档 | PROJECT.md | 项目概览 |
| 压缩摘要 | docs/压缩摘要.md | 精简上下文 |
| **数据模型字典** | docs/00-开发规范/数据模型字典.md | 数据库表定义 |
| **错误处理规范** | docs/00-开发规范/错误处理规范.md | 统一错误码体系 |
| **错误预防指南** | docs/00-开发规范/错误预防指南.md | 常见错误模式库 |
| 项目目录树 | docs/项目目录树.md | 文件结构索引 |

---

## 更新日志

### v2.0.0 (2026-02-28)
- 新增：整合 PROJECT.md + TODO 列表 + 压缩摘要
- 新增：记忆质量评分机制
- 新增：重复记忆自动合并
- 新增：过期记忆自动清理
- 新增：离线模式支持
- 新增：命令行参数支持
- 优化：输出格式更加清晰

### v1.0.0
- 基础功能：加载项目记忆并输出摘要