ydc-agent 1.0.0

package/README.md

@@ -0,0 +1,217 @@
+# ydc-agent
+
+[![npm version](https://img.shields.io/npm/v/ydc-agent.svg)](https://www.npmjs.com/package/ydc-agent)
+[![npm downloads](https://img.shields.io/npm/dm/ydc-agent.svg)](https://www.npmjs.com/package/ydc-agent)
+
+MCP server for You.com AI agents with OpenAI-compatible API.
+
+> 📖 Other languages: 繁體中文 | 简体中文 | 日本語 (see README_ZH_TW.md, README_ZH_CN.md, README_JA.md)
+
+## MCP Configuration
+
+### Claude Desktop / Cursor / Windsurf
+
+Add to your MCP config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
+**Cursor/Windsurf**: `.cursor/mcp.json` or `.windsurf/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "ydc-agent": {
+      "command": "npx",
+      "args": ["-y", "ydc-agent"],
+      "env": {
+        "YDC_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### With Multiple API Keys
+
+```json
+{
+  "mcpServers": {
+    "ydc-agent": {
+      "command": "npx",
+      "args": ["-y", "ydc-agent"],
+      "env": {
+        "YDC_API_KEYS": "key1,key2,key3",
+        "YDC_KEY_MODE": "round-robin"
+      }
+    }
+  }
+}
+```
+
+Key modes: `round-robin` (default), `sequential`, `random`
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `you_search` | Web and news search |
+| `you_express` | Fast AI answers |
+| `you_advanced` | Complex reasoning with compute/research tools |
+| `you_agent` | Custom AI agent with intelligent prompt enhancement |
+| `you_chat` | OpenAI-compatible chat with conversation history |
+| `you_conversation_list` | List active conversations |
+| `you_conversation_get` | Get conversation history |
+| `you_conversation_delete` | Delete conversation |
+| `you_key_status` | API key usage statistics |
+| `openai_server_control` | Start/stop OpenAI-compatible HTTP server |
+
+### Built-in AI Guidance
+
+Tool descriptions include guidance for AI callers:
+
+| Tool | Built-in Feature |
+|------|------------------|
+| `you_search` | Guides AI to use `call_count=5+` for diverse results |
+| `you_express` | Guides AI to use `call_count=5+` for diverse opinions |
+| `you_advanced` | **AI Capability Rule**: If caller is GPT-3.5+, results are reference material only - use `call_count=5+` for multiple perspectives |
+| `you_agent` | **Failure Tracking**: Auto-tracks failures, suggests switching to `you_advanced` after threshold (default: 3 failures) |
+
+## AI Calling Decision Guide
+
+### ⚠️ For GPT-3.5+ Level AI
+
+If you are GPT-3.5 or above (GPT-4, Claude 3.5, etc.):
+- `you_advanced` results are **reference material**, not authoritative answers
+- Use `call_count=5+` to gather multiple perspectives, then integrate with your own judgment
+- Avoid `call_count=1` for single answers (wastes multi-perspective capability)
+
+### Quick Reference
+
+| Use Case | Tool | Parameters |
+|----------|------|------------|
+| Diverse viewpoints | `you_advanced` | `call_count=5-10, summary=true, show_results=true` |
+| Quick opinions | `you_express` | `call_count=10-20, show_results=true` |
+| Deep research | `you_advanced` | `agent_type="advanced-4.5-research", call_count=1` |
+| Web search | `you_search` | `call_count=5-20, show_results=true` |
+
+### ⚠️ Common Mistakes
+
+| Wrong | Correct |
+|-------|---------|
+| `call_count=1` for single answer | `call_count=5+` for diverse perspectives |
+| Treat results as authoritative | Treat as reference, integrate yourself |
+| `call_count=10` with `you_advanced` | Use `you_express` or `call_count=3-5` |
+
+## Models / Agent Types
+
+| Model | Description |
+|-------|-------------|
+| `express` | Fast responses |
+| `research` | Deep analysis |
+| `advanced-3.0-high` | Compute tools (default) |
+| `advanced-4.5-high-research` | Full tools (compute + research) |
+| `<custom-agent-id>` | Any custom You.com agent ID |
+
+### Custom Agent ID
+
+You can use any custom You.com agent ID as the model name:
+
+```bash
+curl -X POST http://localhost:3002/v1/chat/completions \
+  -H "Authorization: Bearer token" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"your-custom-agent-uuid","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## OpenAI-Compatible Server
+
+Start via npx:
+
+```bash
+# Start with single API key
+npx ydc-agent --openai --api-key YOUR_API_KEY
+
+# Start with multiple API keys (round-robin)
+npx ydc-agent --openai --api-keys KEY1,KEY2,KEY3
+
+# With custom port and key mode
+npx ydc-agent --openai --api-keys KEY1,KEY2 --port 3003 --key-mode random
+
+# With access token authentication
+npx ydc-agent --openai --api-key YOUR_API_KEY --access-token SECRET
+
+# With custom agents (name:id format)
+npx ydc-agent --openai --api-key YOUR_API_KEY --agent mybot:uuid-here --agent another:uuid2
+```
+
+Or via MCP tool `openai_server_control`.
+
+### Endpoints
+
+- `POST /v1/chat/completions` - Chat completions
+- `GET /v1/models` - List models
+- `GET /health` - Health check
+
+### Usage
+
+```bash
+curl -X POST http://localhost:3002/v1/chat/completions \
+  -H "Authorization: Bearer token" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"express","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `YDC_API_KEY` | You.com API key | required |
+| `YDC_API_KEYS` | Multiple keys (comma-separated) | - |
+| `YDC_KEY_MODE` | round-robin / sequential / random | round-robin |
+| `YDC_OPENAI_PORT` | HTTP server port | 3002 |
+| `YDC_CONVERSATION_STORE` | sqlite / memory | sqlite |
+| `YDC_OPENAI_ACCESS_TOKENS` | Allowed tokens (comma-separated) | - |
+| `YDC_CUSTOM_AGENTS` | Custom agents (name:id,name2:id2) | - |
+| `YDC_AGENT_FAILURE_THRESHOLD` | you_agent failure threshold before disable | 3 |
+
+## PM2 Deployment
+
+For production deployment with PM2:
+
+```bash
+# Using ecosystem config
+pm2 start ecosystem.config.cjs
+
+# Or direct command (Windows)
+pm2 start "cmd /c npx ydc-agent --openai --api-key YOUR_KEY" --name ydc
+```
+
+## Cloudflare Worker Deployment
+
+Deploy as a serverless Cloudflare Worker with D1 database for conversation storage.
+
+### Quick Deploy
+
+[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linuxdo-ref/ydc-agent&authed=true)
+
+### Manual Deploy
+
+1. Create D1 database in Cloudflare Dashboard
+2. Create Worker and paste `cloudflare/worker.js`
+3. Add environment variables: `YDC_API_KEYS`, `ACCESS_TOKEN` (optional)
+4. Bind D1 database as `YDC_DB`
+5. Visit `/setup` to initialize database
+
+### Worker Features
+
+- OpenAI & Anthropic API compatible
+- D1 database for conversation history
+- Multi API key support (random selection)
+- Custom agents via `CUSTOM_AGENTS` env var
+- Setup page at `/setup` for configuration
+
+See [cloudflare/README.md](cloudflare/README.md) for detailed instructions.
+
+## License
+
+MIT

package/README_JA.md

@@ -0,0 +1,189 @@
+# ydc-agent
+
+[![npm version](https://img.shields.io/npm/v/ydc-agent.svg)](https://www.npmjs.com/package/ydc-agent)
+[![npm downloads](https://img.shields.io/npm/dm/ydc-agent.svg)](https://www.npmjs.com/package/ydc-agent)
+
+You.com AI エージェント用 MCP サーバー、OpenAI 互換 API 対応。
+
+## MCP 設定
+
+### Claude Desktop / Cursor / Windsurf
+
+MCP 設定ファイルに追加：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
+**Cursor/Windsurf**: `.cursor/mcp.json` または `.windsurf/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "ydc-agent": {
+      "command": "npx",
+      "args": ["-y", "ydc-agent"],
+      "env": {
+        "YDC_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### 複数 API Key 設定
+
+```json
+{
+  "mcpServers": {
+    "ydc-agent": {
+      "command": "npx",
+      "args": ["-y", "ydc-agent"],
+      "env": {
+        "YDC_API_KEYS": "key1,key2,key3",
+        "YDC_KEY_MODE": "round-robin"
+      }
+    }
+  }
+}
+```
+
+Key モード：`round-robin`（デフォルト）、`sequential`、`random`
+
+## 利用可能な MCP ツール
+
+| ツール | 説明 |
+|--------|------|
+| `you_search` | ウェブ・ニュース検索 |
+| `you_express` | 高速 AI 回答 |
+| `you_advanced` | 複雑な推論（計算/リサーチツール付き） |
+| `you_agent` | カスタム AI エージェント（インテリジェントプロンプト強化） |
+| `you_chat` | OpenAI 互換チャット（会話履歴付き） |
+| `you_conversation_list` | 会話一覧 |
+| `you_conversation_get` | 会話履歴取得 |
+| `you_conversation_delete` | 会話削除 |
+| `you_key_status` | API Key 使用統計 |
+| `openai_server_control` | OpenAI 互換 HTTP サーバーの起動/停止 |
+
+### 組み込み AI ガイダンス
+
+ツール説明には AI 呼び出し元へのガイダンスが含まれています：
+
+| ツール | 組み込み機能 |
+|--------|--------------|
+| `you_search` | AI に `call_count=5+` で多様な検索結果を取得するよう誘導 |
+| `you_express` | AI に `call_count=5+` で多様な意見を取得するよう誘導 |
+| `you_advanced` | **AI 能力ルール**：呼び出し元が GPT-3.5+ の場合、結果は参考資料のみ - `call_count=5+` で多様な視点を収集すべき |
+| `you_agent` | **失敗追跡**：失敗回数を自動追跡、閾値（デフォルト 3 回）超過後に `you_advanced` への切り替えを提案 |
+
+## モデル / Agent タイプ
+
+| モデル | 説明 |
+|--------|------|
+| `express` | 高速レスポンス |
+| `research` | 深い分析 |
+| `advanced-3.0-high` | 計算ツール（デフォルト） |
+| `advanced-4.5-high-research` | フルツール（計算 + リサーチ） |
+| `<custom-agent-id>` | 任意のカスタム You.com agent ID |
+
+### カスタム Agent ID
+
+任意の You.com カスタム agent ID をモデル名として使用可能：
+
+```bash
+curl -X POST http://localhost:3002/v1/chat/completions \
+  -H "Authorization: Bearer token" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"your-custom-agent-uuid","messages":[{"role":"user","content":"こんにちは"}]}'
+```
+
+## OpenAI 互換サーバー
+
+npx で起動：
+
+```bash
+# 単一 API key
+npx ydc-agent --openai --api-key YOUR_API_KEY
+
+# 複数 API keys（ローテーション）
+npx ydc-agent --openai --api-keys KEY1,KEY2,KEY3
+
+# カスタムポートと key モード
+npx ydc-agent --openai --api-keys KEY1,KEY2 --port 3003 --key-mode random
+
+# アクセストークン認証付き
+npx ydc-agent --openai --api-key YOUR_API_KEY --access-token SECRET
+
+# カスタム agents 付き（name:id 形式）
+npx ydc-agent --openai --api-key YOUR_API_KEY --agent mybot:uuid-here --agent another:uuid2
+```
+
+または MCP ツール `openai_server_control` 経由。
+
+### API エンドポイント
+
+- `POST /v1/chat/completions` - チャット完了
+- `GET /v1/models` - モデル一覧
+- `GET /health` - ヘルスチェック
+
+### 使用例
+
+```bash
+curl -X POST http://localhost:3002/v1/chat/completions \
+  -H "Authorization: Bearer token" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"express","messages":[{"role":"user","content":"こんにちは"}]}'
+```
+
+## 環境変数
+
+| 変数 | 説明 | デフォルト |
+|------|------|------------|
+| `YDC_API_KEY` | You.com API キー | 必須 |
+| `YDC_API_KEYS` | 複数キー（カンマ区切り） | - |
+| `YDC_KEY_MODE` | round-robin / sequential / random | round-robin |
+| `YDC_OPENAI_PORT` | HTTP サーバーポート | 3002 |
+| `YDC_CONVERSATION_STORE` | sqlite / memory | sqlite |
+| `YDC_OPENAI_ACCESS_TOKENS` | 許可トークン（カンマ区切り） | - |
+| `YDC_CUSTOM_AGENTS` | カスタム agents（name:id,name2:id2） | - |
+| `YDC_AGENT_FAILURE_THRESHOLD` | you_agent 失敗閾値（無効化まで） | 3 |
+
+## PM2 デプロイ
+
+PM2 を使用した本番環境デプロイ：
+
+```bash
+# ecosystem 設定を使用
+pm2 start ecosystem.config.cjs
+
+# または直接コマンド（Windows）
+pm2 start "cmd /c npx ydc-agent --openai --api-key YOUR_KEY" --name ydc
+```
+
+## Cloudflare Worker デプロイ
+
+サーバーレス Cloudflare Worker としてデプロイ、D1 データベースで会話履歴を保存。
+
+### クイックデプロイ
+
+[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linuxdo-ref/ydc-agent&authed=true)
+
+### 手動デプロイ
+
+1. Cloudflare Dashboard で D1 データベースを作成
+2. Worker を作成し `cloudflare/worker.js` を貼り付け
+3. 環境変数を追加：`YDC_API_KEYS`、`ACCESS_TOKEN`（オプション）
+4. D1 データベースを `YDC_DB` としてバインド
+5. `/setup` にアクセスしてデータベースを初期化
+
+### Worker 機能
+
+- OpenAI と Anthropic API 互換
+- D1 データベースで会話履歴を保存
+- 複数 API Key 対応（ランダム選択）
+- カスタム agents（`CUSTOM_AGENTS` 環境変数経由）
+- 設定ページ `/setup` で構成
+
+詳細は [cloudflare/README.md](cloudflare/README.md) を参照。
+
+## ライセンス
+
+MIT

package/README_ZH_CN.md

@@ -0,0 +1,189 @@
+# ydc-agent
+
+[![npm version](https://img.shields.io/npm/v/ydc-agent.svg)](https://www.npmjs.com/package/ydc-agent)
+[![npm downloads](https://img.shields.io/npm/dm/ydc-agent.svg)](https://www.npmjs.com/package/ydc-agent)
+
+You.com AI 代理的 MCP 服务器，支持 OpenAI 兼容 API。
+
+## MCP 配置
+
+### Claude Desktop / Cursor / Windsurf
+
+添加到 MCP 配置文件：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
+**Cursor/Windsurf**: `.cursor/mcp.json` 或 `.windsurf/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "ydc-agent": {
+      "command": "npx",
+      "args": ["-y", "ydc-agent"],
+      "env": {
+        "YDC_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### 多 API Key 配置
+
+```json
+{
+  "mcpServers": {
+    "ydc-agent": {
+      "command": "npx",
+      "args": ["-y", "ydc-agent"],
+      "env": {
+        "YDC_API_KEYS": "key1,key2,key3",
+        "YDC_KEY_MODE": "round-robin"
+      }
+    }
+  }
+}
+```
+
+Key 模式：`round-robin`（默认）、`sequential`、`random`
+
+## 可用 MCP 工具
+
+| 工具 | 说明 |
+|------|------|
+| `you_search` | 网页与新闻搜索 |
+| `you_express` | 快速 AI 回答 |
+| `you_advanced` | 复杂推理（含计算/研究工具） |
+| `you_agent` | 自定义 AI 代理（智能提示增强） |
+| `you_chat` | OpenAI 兼容聊天（含对话历史） |
+| `you_conversation_list` | 列出对话 |
+| `you_conversation_get` | 获取对话历史 |
+| `you_conversation_delete` | 删除对话 |
+| `you_key_status` | API Key 使用统计 |
+| `openai_server_control` | 启动/停止 OpenAI 兼容 HTTP 服务器 |
+
+### 内置 AI 引导功能
+
+工具描述中包含对 AI 调用方的引导：
+
+| 工具 | 内置功能 |
+|------|----------|
+| `you_search` | 引导 AI 使用 `call_count=5+` 获取多元搜索结果 |
+| `you_express` | 引导 AI 使用 `call_count=5+` 获取多元意见 |
+| `you_advanced` | **AI 能力规则**：如果调用方是 GPT-3.5+，结果仅作为参考资料 - 应使用 `call_count=5+` 收集多元观点 |
+| `you_agent` | **累错追踪**：自动追踪失败次数，超过阈值（默认 3 次）后建议切换到 `you_advanced` |
+
+## 模型 / Agent 类型
+
+| 模型 | 说明 |
+|------|------|
+| `express` | 快速响应 |
+| `research` | 深度分析 |
+| `advanced-3.0-high` | 计算工具（默认） |
+| `advanced-4.5-high-research` | 完整工具（计算 + 研究） |
+| `<custom-agent-id>` | 任意自定义 You.com agent ID |
+
+### 自定义 Agent ID
+
+可使用任意 You.com 自定义 agent ID 作为 model 名称：
+
+```bash
+curl -X POST http://localhost:3002/v1/chat/completions \
+  -H "Authorization: Bearer token" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"your-custom-agent-uuid","messages":[{"role":"user","content":"你好"}]}'
+```
+
+## OpenAI 兼容服务器
+
+通过 npx 启动：
+
+```bash
+# 单个 API key
+npx ydc-agent --openai --api-key YOUR_API_KEY
+
+# 多个 API keys（轮换）
+npx ydc-agent --openai --api-keys KEY1,KEY2,KEY3
+
+# 自定义 port 和 key 模式
+npx ydc-agent --openai --api-keys KEY1,KEY2 --port 3003 --key-mode random
+
+# 带 access token 验证
+npx ydc-agent --openai --api-key YOUR_API_KEY --access-token SECRET
+
+# 带自定义 agents（name:id 格式）
+npx ydc-agent --openai --api-key YOUR_API_KEY --agent mybot:uuid-here --agent another:uuid2
+```
+
+或通过 MCP 工具 `openai_server_control`。
+
+### API 端点
+
+- `POST /v1/chat/completions` - 聊天完成
+- `GET /v1/models` - 列出模型
+- `GET /health` - 健康检查
+
+### 使用示例
+
+```bash
+curl -X POST http://localhost:3002/v1/chat/completions \
+  -H "Authorization: Bearer token" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"express","messages":[{"role":"user","content":"你好"}]}'
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `YDC_API_KEY` | You.com API 密钥 | 必填 |
+| `YDC_API_KEYS` | 多个密钥（逗号分隔） | - |
+| `YDC_KEY_MODE` | round-robin / sequential / random | round-robin |
+| `YDC_OPENAI_PORT` | HTTP 服务器端口 | 3002 |
+| `YDC_CONVERSATION_STORE` | sqlite / memory | sqlite |
+| `YDC_OPENAI_ACCESS_TOKENS` | 允许的 token（逗号分隔） | - |
+| `YDC_CUSTOM_AGENTS` | 自定义 agents（name:id,name2:id2） | - |
+| `YDC_AGENT_FAILURE_THRESHOLD` | you_agent 失败阈值（超过后停用） | 3 |
+
+## PM2 部署
+
+使用 PM2 进行生产环境部署：
+
+```bash
+# 使用 ecosystem 配置
+pm2 start ecosystem.config.cjs
+
+# 或直接命令（Windows）
+pm2 start "cmd /c npx ydc-agent --openai --api-key YOUR_KEY" --name ydc
+```
+
+## Cloudflare Worker 部署
+
+部署为无服务器 Cloudflare Worker，使用 D1 数据库存储对话历史。
+
+### 快速部署
+
+[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linuxdo-ref/ydc-agent&authed=true)
+
+### 手动部署
+
+1. 在 Cloudflare Dashboard 创建 D1 数据库
+2. 创建 Worker 并粘贴 `cloudflare/worker.js`
+3. 添加环境变量：`YDC_API_KEYS`、`ACCESS_TOKEN`（可选）
+4. 绑定 D1 数据库为 `YDC_DB`
+5. 访问 `/setup` 初始化数据库
+
+### Worker 功能
+
+- OpenAI 与 Anthropic API 兼容
+- D1 数据库存储对话历史
+- 多 API Key 支持（随机选择）
+- 自定义 agents（通过 `CUSTOM_AGENTS` 环境变量）
+- 设置页面 `/setup` 进行配置
+
+详细说明请参阅 [cloudflare/README.md](cloudflare/README.md)。
+
+## 许可证
+
+MIT