# AGENTS.md - 项目上下文定义

## 项目概述
- **项目名称**: MyAI-Note
- **技术栈**: Next.js 14 + TypeScript + Tailwind CSS
- **代码风格**: Airbnb ESLint Config + Prettier
- **仓库**: GitHub Enterprise (https://github.company.com/ai-team/my-ai-note)

## 核心约束
- **不修改**: legacy/ 目录下的代码（历史遗留，维护成本高）
- **强制测试**: 所有 PR 必须包含对应的测试用例
- **Code Review**: 必须至少 1 人 approve 才能合并

## 编码规范
- **命名**: camelCase（变量/函数），PascalCase（组件/类型），SCREAMING_SNAKE_CASE（常量）
- **组件**: 函数式组件 + Hooks，禁止 class 组件
- **状态管理**: 局部 useState，跨组件用 Zustand
- **API 调用**: 统一使用 useSWR

## 重要上下文
- **后端 API**: https://api.internal.company.com/v1
- **认证**: Bearer Token，每次请求需携带
- **当前开发重点**: 用户收藏功能重构

## 个人偏好
- **解释优于直接修改**: 先分析再动手
- **小步提交**: 每个 commit 专注一件事
- **详细 commit message**: 说明 why 而非 what

## 常见陷阱
- **API 频率限制**: 外部 API 每日 1000 次，注意缓存
- **敏感信息**: 永远不要在代码中硬编码 API Key

[明确指令] + [具体信息] + [记忆触发词]

请记住以下配置：
- 我的 GitHub Personal Access Token 是 ghp_xxxxxxxxxxxx
- 这个项目使用 pnpm 作为包管理器
- API 文档在 https://docs.company.com

（以后涉及到包管理或 GitHub 操作时请使用这些配置）

记住我的 GitHub token

// 方式 1：直接请求
帮我分析这个 React 性能瓶颈，找出原因并给出优化方案，然后将分析过程保存为一个技能 "React 性能分析"。

// 方式 2：引导创建
我需要经常做数据库迁移，能否创建一个 "DB Migration" 技能，包含：
1. 检查当前 schema
2. 生成 migration 文件模板
3. 执行���验证
4. 回滚预案

// 方式 3：场景驱动
（直接开始复杂任务，Hermes 会自动识别并创建技能）

# 查看最近 30 天的认知摘要
/hermes insights --days 30

# 输出示例：
# === 认知摘要 ===
# 
# 项目理解：
#   - MyAI-Note: Next.js 14 + TS 项目，熟悉 pages/app router
#   - 技术栈：Tailwind, Zustand, SWR
#   - 常用操作：git commit, npm test, deploy
# 
# 技能积累：
#   - React 性能优化 ✓
#   - API 错误处理模式 ✓
#   - 测试用例生成模板 ✓
# 
# 协作风格：
#   - 喜欢先分析再修改
#   -偏好小步提交
#   - 重视测试覆盖

# 清理 90 天前的记忆
/hermes memory cleanup --older-than 90d

# 手动删除特定记忆
/hermes memory delete "过时的 API 地址"

# 查看记忆统计
/hermes memory stats

# hermes-gateway.yaml - 安全配置
security:
  # 启用白名单模式
  whitelist_mode: true
  
  # 各平台白名单
  allowed_users:
    # Telegram 用户 ID（不是用户名！）
    telegram:
      - "123456789"      # 主账号
      - "987654321"      # 开发伙伴
    # Discord Snowflake ID
    discord:
      - "111222333444555666"
      - "777888999000111222"
    # Slack User ID  
    slack:
      - "U1234567890"
      - "U0987654321"
    # 自定义平台
    custom:
      - "user_internal_001"
      
  # 群组白名单（可选）
  allowed_groups:
    telegram:
      - "-1001234567890"  # 负号开头是群组 ID
    discord:
      - "guild_id_123456"
      
  # 未授权处理
  on_unauthorized:
    # 回复消息（留空则不回复）
    reply: "抱歉，我没有权限响应你的消息。如需访问请配置白名单。"
    # 记录日志
    log: true
    # 通知管理员
    notify_admin: true
    # 通知方式
    notify_via: "telegram"
    admin_ids: ["123456789"]

security:
  # 需要审批的命令模式
  approval_required:
    # 文件删除
    - pattern: "^rm\\s"
      description: "删除文件"
    # 仓库操作
    - pattern: "^git\\s+push"
      description: "推送到远程"
    # 系统命令
    - pattern: "^sudo\\s"
      description: "系统管理员操作"
    # 环境修改
    - pattern: "^hermes\\s+config\\s+set"
      description: "修改配置"
      
  # 审批超时（秒）
  approval_timeout: 300
  
  # 审批消息模板
  approval_message: |
    ⚠️ 安全确认
    
    将要执行：{{command}}
    
    请回复 "确认" 或 "取消"

execution:
  # 执行后端选择
  backend: "docker"  # docker | native | none
  
  docker:
    # 基础镜像
    image: "hermes-executor:latest"
    
    # 只读根文件系统
    read_only_root: true
    
    # 丢弃所有能力
    cap_drop:
      - ALL
      
    # 允许的能力
    cap_add:
      - NET_BIND_SERVICE
      
    # 内存限制
    memory: "512m"
    
    # CPU 限制
    cpus: "0.5"
    
    # 网络��离
    network_mode: "none"  # none | bridge | host
    
    # 卷只读挂载
    volumes:
      - source: "/data/projects"
        target: "/projects"
        readonly: false
      - source: "/data/secrets"
        target: "/secrets"
        readonly: true

用户：帮我用这个 key 查一下天气
Hermes：好的，我用你的 API_KEY=sk-xxx 查询...

# 方式 1：配置文件
# ~/.hermes/config.yaml
api_keys:
  weather: "${WEATHER_API_KEY}"
  
# 方式 2：环境变量
$ export WEATHER_API_KEY="sk-xxx"
$ hermes config set weather_api_key "env:WEATHER_API_KEY"

# 方式 3：密钥管理服务
$ hermes config set api_keys.weather "vault:secret/weather"

总 Token = 输入 Token + 输出 Token

输入 Token = 对话历史 + 上下文文件 + 检索记忆
输出 Token = AI 生成内容 + 工具输出

# 压缩当前上下文
/compress
# 效果：减少 ~40-60% Token

# ❌ 过于详细
## 详细技术文档
这里记录了项目的所有技术细节...
（500+ 行，太长！）

# ✅ 精简版
## 技术栈
- Next.js 14 + TypeScript
- 风格：Airbnb
（50 行以内刚好）

# 每周清理一次
/hermes memory cleanup --older-than 90d

# 或手动指定
/hermes memory delete "临时测试数据"

# ~/.hermes/config.yaml
models:
  default: "hermes-2-pro"
  
  # 小模型映射
  fast:
    simple_qa: "hermes-2-mini"
    code_review: "claude-3-haiku"
    file_list: "hermes-2-mini"

# 查看已启用工具
/hermes tools

# 禁用不需要的工具
/hermes tools disable browser
/hermes tools disable database

# ❌ 冗长
请帮我详细分析一下这个代码文件的结构，包括所有的函数、类、变量定义，然后给出优化建议。

# ✅ 简洁
分析这个文件，给出优化建议。

# ❌ 宽泛搜索
搜索"React"  -> 返回 50+ 相关记忆

# ✅ 精确搜索
搜索"React useEffect cleanup"  -> 返回 3-5 条精准记忆

日常任务（80% 场景）：
  Hermes-2 Pro + Claude-3 Haiku
  月成本：$5-15

复杂任务（15% 场景）：
  GPT-4 + Claude-3.5 Opus  
  月成本：$30-50

研究任务（5% 场景）：
  自定义模型 + vLLM
  成本：取决于硬件

# 配置缓存
cache:
  enabled: true
  # 缓存类型
  backend: "redis"
  # TTL 设置
  default_ttl: 3600
  # 基于模型
  model_overrides:
    hermes-2-pro: 1800
    hermes-2-mini: 300

# 并发配置
concurrency:
  # 最大并发会话
  max_sessions: 10
  # 每会话最大并发工具调用
  max_tool_calls: 5
  # 队列大小
  queue_size: 100

## 环境信息
- Hermes 版本：2.1.0
- 操作系统：Ubuntu 22.04
- 模型：Claude-3.5 Sonnet

## 问题描述
[清晰描述问题]

## 重现步骤
1. 执行 xxx
2. 出现 xxx 错误

## 已尝试
- 尝试了 xxx，没用

# 方式 1：命令行
hermes skill publish --name "my-skill" --public true

# 方式 2：Web 界面
# 1. 访问 agentskills.io
# 2. 连接 GitHub 账号
# 3. 发布技能仓库

## Bug 报告格式

### 问题描述
[简洁描述问题]

### 重现步骤
1. [步骤 1]
2. [步骤 2]

### 预期行为
[描述期望]

### 实际行为
[描述实际]

### 环境
- 版本：2.1.0
- 平台：macOS
- 模型：默认

# 查看配置
hermes config show

# 设置值
hermes config set model.provider "openai"
hermes config set model.name "gpt-4"

# 删除值
hermes config unset api_key

# 导入配置
hermes config import config.yaml

传统 AI 助手：
  你 → 对话 → AI → 回答 → 结束（下次从头开始）
  
Hermes Agent：
  你 → 对话 → AI → 回答 + 学习 → 记忆 → 下次继续（越来越懂你）