Metadata-Version: 2.4
Name: prompt-collector
Version: 0.1.0
Summary: A CLI tool for collecting and forwarding Prompt events to API
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# Prompt Collector

一个 CLI 工具，用于收集 Prompt 和 AI 响应，并推送到远程 API 服务。

## 功能特点

- 支持发送 `prompt` 和 `result` 两种类型的事件
- 从环境变量读取配置，支持静默失败
- 从 stdin 或命令行参数读取内容
- 内容自动截断（最大 10000 字符）
- 错误日志写入 `/tmp/prompt_collector_error.log`

## 安装

```bash
# 安装依赖
pip install -e ".[dev]"

# 或使用生产依赖
pip install -e .
```

## 配置

通过环境变量配置：

```bash
export PROMPT_COLLECTOR_API_URL="https://your-api.com"  # API 基础 URL（必需）
export PROMPT_COLLECTOR_USERNAME="your-username"         # 用户名（必需）
export PROMPT_COLLECTOR_API_KEY="your-api-key"          # API Key（可选）
export PROMPT_COLLECTOR_TIMEOUT="5"                     # 超时时间，默认 5 秒（可选）
```

## 使用方法

### 基本用法

```bash
# 发送 Prompt（从 stdin 读取）
echo '{"session_id": "sess_abc123", "content": "Hello AI"}' | prompt-collector --type prompt

# 发送 Result（从 stdin 读取）
echo '{"session_id": "sess_abc123", "content": "AI response"}' | prompt-collector --type result

# 发送原始文本
printf "Hello AI" | prompt-collector --type prompt --session-id "sess_abc123"

# 使用命令行参数
prompt-collector --type prompt --session-id "sess_abc123" --content "Hello AI"
```

### 与 Claude Code 集成

Claude Code 支持通过 hooks 在特定事件触发时执行自定义命令。

#### 配置步骤

1. 在项目根目录或用户主目录创建 `.claude/settings.json`：

```bash
# 项目级配置（推荐）
mkdir -p .claude
touch .claude/settings.json

# 或全局配置
mkdir -p ~/.claude
touch ~/.claude/settings.json
```

2. 添加 hooks 配置：

```json
{
  "hooks": {
    "UserPromptSubmit": "echo '{\"session_id\": \"$CLAUDE_SESSION_ID\", \"content\": \"$CLAUDE_LAST_MESSAGE\"}' | prompt-collector --type prompt",
    "Stop": "echo '{\"session_id\": \"$CLAUDE_SESSION_ID\", \"content\": \"$CLAUDE_LAST_MESSAGE\"}' | prompt-collector --type result"
  }
}
```

#### 可用的 Claude Code 环境变量

| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `CLAUDE_SESSION_ID` | 当前会话唯一标识 | `abc123-def456` |
| `CLAUDE_LAST_MESSAGE` | 最后一条消息内容 | `"Hello AI"` |
| `CLAUDE_PROJECT_DIR` | 当前项目目录 | `/home/user/myproject` |

#### 可用的 Hooks 类型

| Hook 名称 | 触发时机 |
|-----------|----------|
| `UserPromptSubmit` | 用户提交消息时 |
| `Stop` | 会话结束或 AI 响应完成时 |

#### 完整配置示例

```json
{
  "hooks": {
    "UserPromptSubmit": "echo '{\"session_id\": \"$CLAUDE_SESSION_ID\", \"content\": \"$CLAUDE_LAST_MESSAGE\"}' | prompt-collector --type prompt",
    "Stop": "echo '{\"session_id\": \"$CLAUDE_SESSION_ID\", \"content\": \"$CLAUDE_LAST_MESSAGE\"}' | prompt-collector --type result"
  }
}
```

#### 验证配置

配置完成后，启动 Claude Code 并输入任意消息，检查数据是否被正确收集：

```bash
# 查看错误日志
tail -f /tmp/prompt_collector_error.log

# 测试配置是否正确加载
python -c "from prompt_collector.config import get_api_base_url; print(get_api_base_url())"
```

## CLI 参数

```
usage: prompt-collector [-h] --type {prompt,result} [--session-id SESSION_ID] [--content CONTENT]

options:
  -h, --help            show this help message and exit
  --type {prompt,result}
                        Type of event to send: 'prompt' for user input, 'result' for AI response
  --session-id SESSION_ID
                        Session identifier (can also be read from stdin JSON)
  --content CONTENT     Content to send (can also be read from stdin)
```

## API 接口

工具会向 `POST {API_URL}/api/sessions` 发送请求：

**Request:**
```json
{
  "username": "your-username",
  "session_id": "session-identifier",
  "prompt": "user prompt content (仅当 type=prompt)",
  "result": "ai response content (仅当 type=result)"
}
```

## 测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_parser.py

# 带覆盖率报告
pytest --cov=prompt_collector
```

## 错误排查

查看错误日志：
```bash
tail -f /tmp/prompt_collector_error.log
```

启用调试日志（取消 `main.py` 中 `debug_log()` 函数的注释）。

## 项目结构

```
prompt-collector/
├── pyproject.toml              # 项目配置
├── README.md                   # 项目说明
├── src/
│   └── prompt_collector/
│       ├── __init__.py
│       ├── __main__.py         # 模块入口
│       ├── config.py           # 环境变量配置
│       ├── parser.py           # 输入解析
│       ├── formatter.py        # 消息格式化
│       ├── sender.py           # HTTP 发送
│       └── main.py             # CLI 和主流程
└── tests/                      # 测试目录
```
