pond-agent

Pond 群聊 AI Agent。登录后自动监听群消息，被 @ 时调用 AI 生成回复。

安装

方式 1：npm 全局安装（推荐）

npm install -g pond-agent
pond-agent run

首次运行自动完成 Python 环境初始化，然后引导你登录并选择 Agent。

需要 Node >= 18 和 Python >= 3.10。

方式 2：预编译二进制（无需 Python）

从 GitHub Releases 下载对应平台的二进制，直接运行：

chmod +x pond-agent-macos-arm64
./pond-agent-macos-arm64 run

方式 3：从源码安装

git clone <repo-url> && cd pond-group-agent
npm install
npm start

使用

pond-agent run     # 启动
pond-agent --help  # 帮助

REPL 终端命令

启动后进入交互终端：

pond (代码助手 (a1b2c3d4)) >

| 命令 | 说明 | |------|------| | /login | 重新登录（仅未登录状态可用） | | /logout | 退出登录，清除认证信息，程序保持运行 | | /exit | 退出程序 | | /help | 显示帮助 |

首次配置

首次运行若无配置，会引导你：

=======================================================
  Pond Agent — 首次配置
=======================================================

  配置方式:
    [1] 用户名密码登录，选择已有 Agent
    [2] 粘贴 Provision URL

  请选择 (1/2，默认 1):

选择 1 后输入 Pond 服务地址、用户名、密码，然后从列表中选择一个已创建的 Agent。

配置

配置文件 pond-agent.config.json（自动生成）：

{
  "pond": {
    "baseUrl": "https://your-pond-server.com/api",
    "token": "用户 JWT（REST API / WebSocket 用）",
    "agentToken": "Agent Token（LLM 代理用）",
    "agentId": "agent-xxx",
    "userId": "user-xxx"
  },
  "llm": {
    "temperature": 0.3,
    "maxTokens": 4000,
    "systemPrompt": "你是群聊中的助手。"
  }
}

注意：模型名称、API Key、baseUrl 等在聊天端每个 Agent 独立配置，不在本地文件。

环境变量（可选）

所有配置项都可通过 .env 覆盖：

# Pond
POND_BASE_URL=http://localhost:8080/api
POND_TOKEN=eyJ...

# LLM（可选覆盖）
LLM_SYSTEM_PROMPT=你是群聊中的助手。

触发规则

Agent 监听群消息，触发任一条件即回复：

1. 消息 mentions 包含 Agent 的 userId
2. 消息文本包含配置的 mentionNames

发布

一键发布

# 预览（不实际发布）
npm run release 0.3.21 -- --dry

# 正式发布：同步版本号 + 编译二进制 + npm publish
npm run release 0.3.21

自动完成：

1. 同步版本号到 package.json + pyproject.toml
2. 编译当前平台二进制 → dist/pond-agent-<平台>-<架构>
3. npm publish

单独构建二进制

npm run build:binary
# 输出: dist/pond-agent-<平台>-<架构>

构建环境要求：

• macOS：Xcode Command Line Tools
• Linux：sudo apt install libpython3.12-dev
• 所有平台：Python 3.10+、Node 18+

GitHub Actions 自动发布

推送 v* 标签自动触发（配置位于 .github/workflows/release.yml）：

1. Build — 5 个平台并行编译二进制
2. npm publish — 推送 npm 包
3. GitHub Release — 附带所有平台二进制

使用方式：

git tag v0.3.21
git push origin v0.3.21

首次配置：添加 NPM_TOKEN

在 npmjs.com → Access Tokens → Generate New Token：

• 类型选 "Automation"（CI/CD 专用，跳过 2FA）
• 生成后在 GitHub 仓库 Settings → Secrets → Actions 添加 NPM_TOKEN

文件结构

pond-group-agent/
├── package.json           # npm 包配置
├── pyproject.toml         # Python 包配置
├── pond-agent.config.json # 配置文件（自动生成）
├── .env                   # 环境变量（可选）
├── bin/
│   ├── pond-group-agent.js  # CLI 入口（JS 壳 → Python）
│   ├── install.js           # npm postinstall
│   └── build-binary.js      # PyInstaller 二进制构建
├── pond_agent/
│   ├── cli.py             # CLI 入口 (init/validate/run)
│   ├── config.py          # 配置管理 + 登录流程
│   ├── agent.py           # 主循环 + REPL
│   ├── agent_core.py      # Deep Agent (LangChain + Deep Agents)
│   ├── pond_client.py     # Pond REST + WebSocket 客户端
│   ├── executor.py        # PTY Claude Code 执行器
│   ├── server.py          # Hook HTTP 服务器
│   ├── hooks.py           # Claude Code hooks 管理
│   └── tools/             # LangChain 工具
└── README.md

注意事项

1. Python 版本：依赖要求 Python >= 3.10（langchain、deepagents 等）
2. 模型配置：Agent 的模型名、API Key 等在聊天端每个 Agent 独立配置，本地只配 temperature/maxTokens/systemPrompt
3. Token 过期：检测到 401 会自动清除认证，引导重新登录
4. 发布前：确保 package.json 和 pyproject.toml 版本号一致