# acp-py

Python Agent SDK - 基于 WebSocket 的智能体通信库

## 安装

```bash
pip install acp-py
```

## 快速开始

### 启动 Agent

```bash
# 直接启动（使用默认配置）
acp-py

# 指定 Agent 名称
acp-py -n my_agent

# 启用调试模式
acp-py --debug

# 指定目标 Agent（可直接发送消息）
acp-py -t target_agent.aid.pub
```

### 交互命令

启动后可以使用以下命令：

| 命令 | 说明 |
|------|------|
| `/target <aid>` | 设置目标 Agent |
| `/session` | 显示当前会话信息 |
| `/aid` | 显示本机 AID |
| `/help` | 显示帮助 |
| `/quit` | 退出 |
| 其他输入 | 发送消息给目标 |

## CLI 参数

```bash
acp-py [选项]

选项:
  -d, --data <path>    数据目录 (默认: ./acp-data)
  -p, --password <pwd> 种子密码
  -n, --name <name>    Agent 名称
  -t, --target <aid>   目标 Agent AID
  --ap <address>       AP 地址 (默认: aid.pub)
  --debug              启用调试模式
```

## 调度器环境变量

以下环境变量用于调整消息调度器的默认并发参数（可选）：

- `AGENTCP_SCHED_CORE_WORKERS`：核心线程数（常驻）
- `AGENTCP_SCHED_MAX_WORKERS`：最大线程数（高峰扩展）
- `AGENTCP_SCHED_MAX_TASKS_PER_WORKER`：每线程最大并发异步任务数

## 自定义 Agent 开发

```python
from agentcp import AgentCP

# 创建 AgentCP 实例
acp = AgentCP("./data", seed_password="your_password", debug=True)

# 创建 Agent
aid = acp.create_aid(ap="aid.pub", agent_name="my_agent")
print(f"Agent AID: {aid.id}")

# 注册消息处理器
async def handle_message(data):
    print(f"收到消息: {data}")

aid.add_message_handler(handle_message)

# 上线
aid.online()

# 发送消息
session_id = aid.create_session("my_session", "测试会话")
aid.invite_member(session_id, "target_agent.aid.pub")
aid.send_message(session_id, ["target_agent.aid.pub"], "Hello!")

# 保持运行
acp.serve_forever()
```

## 系统要求

- Python >= 3.8

## 平台支持

- macOS
- Linux
- Windows

## 更新日志 (v1.0.3)

### 安全修复

- 修复 Guest 证书申请日志泄露私钥问题，日志脱敏仅记录 guest_aid 和 entrypoint (`ca_client.py`)
- 修复 `client.py` 异常处理不一致：统一 401 重试逻辑顺序，安全解析非 JSON 响应体，get/post 方法行为对称
- 替换全部 DEBUG print 语句为 log 框架调用，消除生产环境信息泄露风险 (`agentcp.py`, `session_manager.py`)

### Bug 修复

- 修复 `message_serialize.py` 中 InviteCodeExpire 双写导致序列化/反序列化字段错位的数据损坏 bug
- 修复 `session_manager.py` 中 `eject_member` 使用 `self.agent_id` 而非参数 `eject_aid` 的逻辑错误
- 修复 `session_manager.py` 中 `check_stream_url_exists` 的 `return False` 死代码
- 修复版本号不一致：`__init__.py` 从 0.1.96 更新为 1.0.3，与 `pyproject.toml` 对齐

### 性能与稳定性

- SQLite 线程安全重构：启用 WAL 模式，使用 `threading.local()` 为每线程维护独立连接，解决并发 `database is locked` 问题 (`db_manager.py`)
- 消息调度器优化：核心/最大线程数改为基于 CPU 动态计算，支持环境变量覆盖 (`improved_scheduler.py`)
- 文件传输添加超时保护：`timeout=(10, 600)`，防止网络异常时无限挂起 (`file_client.py`)
- 消息队列溢出时记录 warning 日志，便于排查消息丢失 (`message_client.py`)

### 代码清理

- 删除未使用的 `connection_manager.py`（完整但从未被导入的死代码）
- 移除错误的 `from ntpath import exists` 导入 (`agentcp.py`)
- 修正拼写：`db_mananger` → `db_manager`（文件名 + 3 处 import + 构造函数参数）
- 修正拼写：`on_message_recive` → `on_message_receive`（回调参数名）
- 移除 `get_friend_agent_list` 未使用的 `aid` 参数 (`db_manager.py`, `agentcp.py`)

## License

MIT
