246 lines
6.6 KiB
Markdown
246 lines
6.6 KiB
Markdown
# AGENTS.md
|
||
|
||
AI Agent 操作手册 - Chat Vault Monorepo
|
||
|
||
---
|
||
|
||
## 1. Mission & Scope（目标与边界）
|
||
|
||
### 允许操作
|
||
- 修改 `services/chat-vault/src/` 下的 Python 代码
|
||
- 添加新的解析器到 `services/chat-vault/src/parsers/`
|
||
- 更新文档 (`README.md`, `AGENTS.md`, `docs/`)
|
||
- 修改配置示例 `.env.example`
|
||
|
||
### 禁止操作
|
||
- **禁止修改** `output/` 目录下的任何文件（数据库、日志）
|
||
- **禁止修改** `.env` 文件（包含用户敏感配置）
|
||
- **禁止修改** `libs/external/` 下的外部依赖镜像
|
||
- **禁止删除** 现有解析器，除非明确要求
|
||
|
||
### 敏感区域
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `services/chat-vault/.env` | 用户配置，不得读取或修改 |
|
||
| `services/chat-vault/output/` | 运行时数据，不得修改 |
|
||
| `libs/external/` | 外部镜像，只读 |
|
||
|
||
---
|
||
|
||
## 2. Golden Path（推荐执行路径）
|
||
|
||
```bash
|
||
# 1. 进入服务目录
|
||
cd services/chat-vault
|
||
|
||
# 2. 首次运行（自动创建 venv 并安装依赖）
|
||
python src/main.py
|
||
|
||
# 3. 验证功能
|
||
python src/main.py --stats
|
||
|
||
# 4. 修改代码后测试
|
||
python src/main.py # 同步测试
|
||
python src/main.py --search "test" # 搜索测试
|
||
|
||
# 5. 更新文档（如有变更）
|
||
# 编辑 README.md, AGENTS.md, docs/schema.md
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Must-Run Commands（必须执行的命令）
|
||
|
||
### 环境准备
|
||
```bash
|
||
cd services/chat-vault
|
||
python src/main.py # 首次运行自动安装依赖
|
||
```
|
||
|
||
### 依赖文件
|
||
- `services/chat-vault/requirements.txt`
|
||
```
|
||
python-dotenv>=1.0.0
|
||
watchdog>=3.0.0
|
||
tiktoken>=0.5.0
|
||
```
|
||
|
||
### 功能验证
|
||
```bash
|
||
# 同步一次
|
||
python src/main.py
|
||
|
||
# 查看统计
|
||
python src/main.py --stats
|
||
|
||
# 监控模式
|
||
python src/main.py --watch
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Code Change Rules（修改约束）
|
||
|
||
### 架构原则
|
||
- 解析器必须继承 `parsers/base.py` 的 `SessionData` 数据结构
|
||
- 新增 CLI 支持需在 `parsers/__init__.py` 中导出
|
||
- 配置项通过 `config.py` 的 `CONFIG` 字典访问
|
||
|
||
### 模块边界
|
||
| 模块 | 职责 | 禁止 |
|
||
|------|------|------|
|
||
| `main.py` | CLI 入口、命令分发 | 不含业务逻辑 |
|
||
| `config.py` | 路径检测、配置加载 | 不含 I/O 操作 |
|
||
| `storage.py` | SQLite 读写、Token 计数 | 不含解析逻辑 |
|
||
| `watcher.py` | 文件监控 | 不含存储逻辑 |
|
||
| `parsers/*.py` | 各 CLI 格式解析 | 不含存储逻辑 |
|
||
|
||
### 依赖添加规则
|
||
- 新依赖必须添加到 `requirements.txt`
|
||
- 优先使用标准库
|
||
- 避免引入大型框架
|
||
|
||
### 兼容性要求
|
||
- Python 3.8+ 兼容
|
||
- 跨平台：Linux / macOS / Windows (WSL)
|
||
- WSL 路径格式：`\\wsl.localhost\Ubuntu\...`
|
||
|
||
---
|
||
|
||
## 5. Style & Quality（风格与质量）
|
||
|
||
### 代码风格
|
||
- 文件头：`#!/usr/bin/env python3` + `# -*- coding: utf-8 -*-`
|
||
- 缩进：4 空格
|
||
- 行宽：建议 100 字符
|
||
- 命名：snake_case（函数/变量），PascalCase（类）
|
||
|
||
### 文档要求
|
||
- 每个模块需有 docstring 说明用途
|
||
- 公开函数需有参数/返回值说明
|
||
- 复杂逻辑需有行内注释
|
||
|
||
### 错误处理
|
||
- 解析失败记录到日志，不中断流程
|
||
- 使用 `logger.py` 的 `get_logger()` 记录
|
||
|
||
---
|
||
|
||
## 6. Project Map（项目结构速览）
|
||
|
||
```
|
||
chat-vault/
|
||
├── services/chat-vault/ # 核心服务
|
||
│ ├── src/
|
||
│ │ ├── main.py # 入口：CLI 命令分发
|
||
│ │ ├── config.py # 配置：路径检测、环境变量
|
||
│ │ ├── storage.py # 存储：SQLite + tiktoken
|
||
│ │ ├── watcher.py # 监控：watchdog 封装
|
||
│ │ ├── logger.py # 日志：统一日志配置
|
||
│ │ └── parsers/
|
||
│ │ ├── __init__.py # 导出所有解析器
|
||
│ │ ├── base.py # SessionData 数据结构
|
||
│ │ ├── codex.py # Codex CLI 解析
|
||
│ │ ├── kiro.py # Kiro CLI 解析
|
||
│ │ ├── gemini.py # Gemini CLI 解析
|
||
│ │ └── claude.py # Claude CLI 解析
|
||
│ ├── docs/
|
||
│ │ ├── schema.md # 数据库结构文档
|
||
│ │ ├── roadmap.md # 开发路线图
|
||
│ │ └── AI_PROMPT.md # AI 助手指南
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── .env.example # 配置示例
|
||
│ ├── start.sh # Linux/macOS 启动脚本
|
||
│ └── start.bat # Windows 启动脚本
|
||
├── libs/ # 共享库（预留）
|
||
├── monitoring/ # 监控配置（预留）
|
||
├── scripts/ # 全局脚本
|
||
├── README.md # 项目说明
|
||
└── AGENTS.md # 本文件
|
||
```
|
||
|
||
### 关键入口
|
||
- **CLI 入口**: `services/chat-vault/src/main.py`
|
||
- **配置加载**: `services/chat-vault/src/config.py` → `CONFIG` 字典
|
||
- **数据库**: `services/chat-vault/output/chat_history.db`
|
||
|
||
---
|
||
|
||
## 7. Common Pitfalls（常见问题）
|
||
|
||
| 问题 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| `ModuleNotFoundError` | 未在 venv 中运行 | 运行 `python src/main.py` 自动创建 venv |
|
||
| 路径未检测到 | 默认路径不存在 | 在 `.env` 中配置 `CODEX_PATHS` 等 |
|
||
| WSL 路径失败 | 格式错误 | 使用 `\\wsl.localhost\Ubuntu\...` 格式 |
|
||
| Token 计数为 0 | tiktoken 未安装 | 检查 `requirements.txt` 是否包含 tiktoken |
|
||
| 数据库锁定 | 多进程同时写入 | 确保只有一个实例运行 |
|
||
|
||
---
|
||
|
||
## 8. PR / Commit Rules（提交规则）
|
||
|
||
### Commit Message 格式
|
||
```
|
||
<type>(<scope>): <description>
|
||
|
||
type: feat|fix|docs|refactor|test|chore
|
||
scope: chat-vault|parsers|storage|config|docs
|
||
```
|
||
|
||
示例：
|
||
```
|
||
feat(parsers): add support for new CLI format
|
||
fix(storage): handle empty message array
|
||
docs(readme): update quick start section
|
||
```
|
||
|
||
### 分支策略
|
||
- `main`: 稳定版本
|
||
- `dev`: 开发分支
|
||
- `feature/*`: 功能分支
|
||
|
||
---
|
||
|
||
## 9. Documentation Sync Rule（文档同步规则）
|
||
|
||
### 强制同步
|
||
以下变更必须同步更新文档：
|
||
|
||
| 变更类型 | 需更新文档 |
|
||
|----------|-----------|
|
||
| 新增命令行参数 | README.md, AGENTS.md |
|
||
| 新增解析器 | README.md (功能特性), AGENTS.md (Project Map) |
|
||
| 数据库结构变更 | docs/schema.md |
|
||
| 配置项变更 | README.md (配置说明), .env.example |
|
||
| 目录结构变更 | README.md, AGENTS.md |
|
||
|
||
### 不确定时
|
||
- 使用 `TODO: 需确认 <具体问题>` 标注
|
||
- 不允许猜测或编造
|
||
|
||
---
|
||
|
||
## 10. Quick Reference（速查）
|
||
|
||
```bash
|
||
# 同步
|
||
python src/main.py
|
||
|
||
# 监控
|
||
python src/main.py --watch
|
||
|
||
# 统计
|
||
python src/main.py --stats
|
||
|
||
# 搜索
|
||
python src/main.py --search "关键词"
|
||
|
||
# 导出
|
||
python src/main.py --export json
|
||
python src/main.py --export csv --source codex
|
||
|
||
# 清理
|
||
python src/main.py --prune
|
||
```
|