charieswei
/
vibe-coding-cn
mirror of https://github.com/tukuaiai/vibe-coding-cn.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
vibe-coding-cn/assets/repo/chat-vault/AGENTS.md

6.6 KiB
Raw Blame History

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 文件（包含用户敏感配置）
  • 禁止修改 repo/ 下的外部依赖镜像
  • 禁止删除 现有解析器，除非明确要求

敏感区域

路径 说明
services/chat-vault/.env 用户配置，不得读取或修改
services/chat-vault/output/ 运行时数据，不得修改
repo/ 外部镜像，只读

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  # 首次运行自动安装依赖

依赖文件

  • services/chat-vault/requirements.txt 
    python-dotenv>=1.0.0
watchdog>=3.0.0
tiktoken>=0.5.0

功能验证

# 同步一次
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