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（推荐执行路径）
# 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（必须执行的命令）
环境准备
cd services/chat-vault
python src/main.py # 首次运行自动安装依赖
依赖文件
功能验证
# 同步一次
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（速查）
# 同步
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
