# youxiawen

**Repository Path**: c031001/youxiawen

## Basic Information

- **Project Name**: youxiawen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-11
- **Last Updated**: 2026-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# youxiawen

youxiawen 是一个可自部署的个人 Agent，由 **macOS 桌宠**和**独立服务端**组成。你可以和桌宠对话，也可以让服务端在定时触发、发现匹配邮件或收到外部推送后，判断是否值得主动处理。Mac 关机时，只要服务端在线，自动任务仍能运行。

## 能做什么

- **桌面会话**：和 Agent 对话、发送文件和图片、接收报告等回复附件，在同一个会话里接续上下文。
- **内置事件源与外部推送**：在桌宠中配置定时任务和 IMAP 邮箱，或让 CI、备份脚本等外部系统通过 API 上报事件。
- **机会检测**：自动事件先判断、再决定是否执行，也可安排稍后复查。判断和复查记录可以单独查看。
- **自选模型与工具**：支持 OpenAI Chat Completions 兼容模型、MCP 服务和自定义 Skills。

## 快速开始

### 1. 启动服务端

**Docker Compose**：首次部署时，在项目根目录将 `.env.example` 复制为 `.env`，用 `openssl rand -hex 32` 生成并填写 `YXW_TOKEN`。仅供本机使用时，将 `YXW_BIND_HOST` 设为 `127.0.0.1`。

```bash
chmod 600 .env
docker compose up -d --build
```

**不用 Docker**：在 macOS 或 Linux 上安装 Node.js 22.19+，然后在项目根目录执行：

```bash
cd server
npm ci
test -f .env || cp .env.example .env
chmod 600 .env
# 首次运行前，在 server/.env 填写 YXW_TOKEN
npm run build
npm start
```

### 2. 打开 macOS 桌宠

需要 macOS 14+ 和 Swift 命令行工具。在项目根目录执行：

```bash
./scripts/build-macos.sh
open output/youxiawen.app
```

1. 在 **设置 → 连接** 填写服务端地址和相同的令牌。本机默认地址为 `http://127.0.0.1:8787`；远程连接使用 HTTPS。
2. 在 **设置 → Agent → 模型** 添加模型，打开会话发送一条测试消息。
3. 在 **设置 → 内置事件源** 添加定时任务或邮箱，或按下文接入外部推送。

## 两类事件源

两类事件源按**谁配置和管理规则**区分，不按事件在客户端还是服务端产生，也不按是否经过 HTTP 接口区分。

| 类型 | 在哪里配置 | 怎么用 |
| --- | --- | --- |
| **内置事件源** | 桌宠的 **设置 → 内置事件源** | 目前支持定时和邮箱，这两种的配置保存在服务端。点击「添加事件源」：定时任务填写触发时间和任务指令，由服务端到点触发；邮箱填写 IMAP 连接信息和可选的过滤条件，由服务端检查邮件。 |
| **外部推送** | CI 工作流、NAS 备份脚本等外部系统 | 由外部系统在事情发生时调用 `POST /api/events`。不需要在桌宠里添加事件源。不能自定义请求头和 JSON 的平台，需要先把原生 Webhook 转换成此接口接受的格式。 |

例如，本机文件变化如果由桌宠监听并上报，仍属于内置事件源；如果由独立脚本监听并上报，则属于外部推送。目前桌宠尚未内置本机文件监听。

两类自动事件都经过机会检测。打开会话窗口的 **机会检测**，可查看 Agent 的判断和复查记录。手动聊天不经过这一步。

定时支持固定间隔、每天、每周、每月和仅一次。也可以在会话里说「每周一、三、五北京时间 9 点检查待办」，再到 **设置 → 内置事件源 → 待确认变更** 查看或编辑草稿。只有点击「确认并保存」才会修改正式配置。

### 用 `curl` 发送一条外部事件

先在当前终端设置 `YXW_TOKEN` 为服务端配置的令牌。默认请求本机 `8787` 端口；如果服务端使用其他端口或部署在远程，请设置 `YXW_SERVER_URL` 为实际地址，远程连接使用 HTTPS。

```bash
curl -i "${YXW_SERVER_URL:-http://127.0.0.1:8787}/api/events" \
  -H "Authorization: Bearer ${YXW_TOKEN:?请先设置 YXW_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "id": "$(uuidgen)",
  "source": "nas-backup",
  "type": "backup.completed",
  "occurredAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "payload": {"job": "daily-backup", "message": "每日备份已完成"}
}
EOF
```

外部推送请使用稳定的 `source`（不要用保留值 `manual`），并在重试同一事件时复用原来的 `id`。`202` 表示已接收，不代表 Agent 已执行；重复提交同一 `id` 返回 `200`。当前接口使用服务端管理令牌，请仅在可信脚本或中转服务中使用，不要把令牌写进 URL 或公开仓库。

## 详细文档

- [部署与使用说明](docs/usage.md)：Docker、数据持久化、桌宠设置、事件源和附件。
- [开发与 API](docs/development.md)：`npm run dev`、测试、实现细节和 HTTP 接口。

## 使用提示

模型供应商可能收到会话内容和匹配的邮件片段。不要上传不希望分享的敏感内容。Agent 可以在服务端运行命令，请保护访问令牌，只启用可信的 Skills 和 MCP 服务。

桌宠使用「蓝色大肥鱼」非商用同人素材（CC BY-NC-SA 4.0），与 DeepSeek 官方无关。详见[素材来源和许可](macos/Sources/Youxiawen/Resources/BlueFatFish-Attribution.txt)。