前置要求

• Python 3.12+——使用 python --version 检查
• conda（推荐）或 venv
• Git——从源码安装时需要
• Node.js 20+（可选）——源码运行需要预编译 WebUI JSX

选项 A：预构建包（推荐，开箱即用）

从 GitHub Releases 下载适用于你平台的安装包，下载后直接打开即可使用。无需安装 Python、Node.js 或任何依赖。

• macOS——.dmg 安装包（Apple Silicon / Intel）
• Windows——ARM64 和 x64 安装程序分别提供
• Linux——.AppImage

首次启动会运行引导向导，配置 API 密钥和人格。之后就可以开始使用了。

选项 B：从源码安装

如果希望自行构建或修改源码，按以下步骤操作。

Linux / macOS

# 1. 创建虚拟环境
conda create -n cyrene python=3.12 -y
conda activate cyrene

# 2. 安装 Cyrene（推荐使用 uv）
uv sync
# 或使用 pip：
# pip install -e .

# 3. 预编译 WebUI JSX（仅源码运行需要）
cd src/webui && npm install && node build-jsx.mjs && cd ../..

# 4. 启动
python -m cyrene --workbench

Windows（从源码）

Windows 需要额外步骤，因为 uvloop（内置 SimpleXNG 使用）是 Unix-only 的。

步骤 1：创建环境

conda create -n cyrene python=3.12 -y
conda activate cyrene

步骤 2：安装依赖

pip install aiosqlite apscheduler croniter fastapi httpx jinja2 python-dotenv python-telegram-bot requests sniffio uvicorn "mcp>=1.27.0"
pip install winloop  # uvloop 的 Windows 替代
pip install simplexng --no-deps
pip install babel brotli clideps flask flask-babel httpx-socks isodate lxml markdown-it-py msgspec platformdirs pyyaml rich setproctitle typer-slim valkey whitenoise
pip install -e . --no-build-isolation

中国用户：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

步骤 3：Windows 兼容性补丁

SimpleXNG 的 vendored 代码需要以下手工修补：

补丁 1：uvloop → winloop
编辑 Lib/site-packages/simplexng/_vendor/searx/network/client.py：

# 替换：
import uvloop
uvloop.install()
# 为：
import sys
if sys.platform == 'win32':
    import winloop as uvloop
else:
    import uvloop
uvloop.install()

补丁 2：fork → spawn
编辑 Lib/site-packages/simplexng/_vendor/searx/plugins/calculator.py：

# 替换：
mp_fork = multiprocessing.get_context("fork")
# 为：
import sys
mp_fork = multiprocessing.get_context("fork" if sys.platform != "win32" else "spawn")

补丁 3：创建 pwd 存根
创建 Lib/site-packages/pwd.py：

"""pwd stub for Windows — SearXNG compatibility."""
import os
def getpwuid(uid):
    name = os.environ.get("USERNAME", "unknown")
    return type("pw", (), {"pw_name": name, "pw_uid": uid})()

补丁 4：启用 JSON API
编辑 Lib/site-packages/simplexng/settings/settings_template.yml，在 search.formats 中添加 json。

步骤 4：启动

python -m cyrene --workbench

验证安装

conda activate cyrene
cd /path/to/Cyrene
python -m cyrene --workbench

打开 http://localhost:4242。首次启动将显示引导向导，指导你：

1. 配置 API 密钥（DeepSeek/Claude/GPT 等）
2. 设置代理名称和人格
3. 选择默认模型

不用 Web 服务器的测试方式：

python -m cyrene.local_cli

可选扩展

故障排除

相关文档

• Workbench UI 使用指南
• 配置参考——环境变量和设置

Prerequisites

• Python 3.12+ — check with python --version
• conda (recommended) or venv
• Git — for source installation
• Node.js 20+ (optional) — for JSX precompilation from source

Option A: Pre-built Package (Recommended)

Download from GitHub Releases — open and use immediately. No Python, Node.js, or any dependencies required.

• macOS — .dmg (Apple Silicon / Intel)
• Windows — ARM64 and x64 installers
• Linux — .AppImage

First launch runs the onboarding wizard for API key and personality setup.

Option B: From Source

Linux / macOS

conda create -n cyrene python=3.12 -y
conda activate cyrene
pip install -e .
cd src/webui && npm install && node build-jsx.mjs && cd ../..

Verify Installation

python -m cyrene --workbench

Open http://localhost:4242. The first launch will run the onboarding wizard.

To test without the web server:

python -m cyrene.local_cli

配置架构

Cyrene 使用 Fernet 加密的 JSON 配置存储（data/config.enc）。这意味着：

• API 密钥等敏感信息在磁盘上加密
• 你不需要创建或维护 .env 文件
• 首次运行的引导向导会写入所有必需值
• Web UI 设置页面可以在运行时更新配置

.env.example 仅为向后兼容保留，新安装应使用加密仓库方式。

环境变量

以下变量在启动时读取。多数字段可通过 Web UI 在运行时编辑，无需重启。

LLM

Agent 行为

调度与管家

搜索

知识库 / 嵌入（可选）

浏览器

渠道（可选）

运行时设置

通过 Web UI 设置页面可以在不重启的情况下修改大部分设置：

模型定价参考

Cyrene 跟踪 token 用量并为已知模型估算成本。如果供应商价格变动，请在设置 UI 中更新。

Config Architecture

Cyrene uses a Fernet-encrypted JSON config store (data/config.enc). API keys are encrypted on disk. The first-run wizard writes required values, and the Web UI Settings page can update them at runtime.

Environment Variables

The following variables are read at startup. Most can be edited at runtime through the Web UI.

LLM

Agent Settings

Runtime Settings

Most settings can be modified at runtime through the Web UI Settings page without restarting:

• API Keys — update OPENAI_API_KEY, OPENAI_BASE_URL, etc.
• Models — add or remove model configurations
• Tools — enable or disable specific tools
• MCP Servers — add, remove, and restart MCP connections
• SOUL.md — edit the personality document directly

启动

Release 桌面应用

从 Releases 页面 下载安装包后，直接打开应用即可。首次启动会运行引导向导，配置 API 密钥和人格。Workbench UI 是默认界面，启动后自动加载。

源码运行

python -m cyrene --workbench

打开 http://localhost:4242。首次运行也会启动引导向导。

--workbench 标志可以省略——python -m cyrene 等价于 python -m cyrene --workbench。

页面一览

意图分流（Intent Dispatch）

聊天输入不是简单地全部交给 LLM。系统会自动分类意图：

• 回答模式——直接交给 LLM 回答，不会触发工具调用或不必要的规划
• 指令模式——需要调用工具执行的命令（如搜索、文件操作），交给代理执行
• 任务模式——需要多步操作的复杂请求，生成执行计划逐步执行
• 收尾——你说"任务完成"或"可以验收"时，代理汇总成果，状态标记为 review

你始终可以自由对话，不会无条件生成计划。

逐步执行

当代理进入任务模式时：

1. Agent 规划需要执行的步骤
2. 你决定步骤的执行顺序（不必按计划顺序）
3. 每步执行时你可以在聊天中实时看到进度
4. 你可以随时发送消息引导、调整或中止当前步
5. 任务完成时，Agent 汇总成果，产物（文件、报告等）可在线查看或下载

项目隔离

Workbench 的核心设计理念是项目隔离。每个项目拥有：

• 独立的 workspacePath 限定工作区
• 独立的知识库（文档和嵌入向量）
• 独立的记忆空间
• 独立的聊天历史和会话

这意味着你可以在"工作"项目中讨论代码，在"个人"项目中讨论生活，两者互不干扰。

相关文档

• Legacy Agent UI——经典聊天界面
• CLI 使用——命令行和交互式终端

Launching

Release Desktop App

Download from GitHub Releases and open the app directly. First launch runs the onboarding wizard. Workbench UI is the default interface.

From Source

python -m cyrene --workbench

Open http://localhost:4242. The --workbench flag can be omitted.

Intent Dispatch

Chat input is automatically classified into intents:

• Answer mode — direct LLM reply, no tool calls
• Command mode — tool execution (search, file operations)
• Task mode — multi-step plan with step-by-step execution
• Finalize — when you say "done", agent summarizes results

Project Isolation

Each project has its own workspace path, knowledge base, memory space, and chat history — completely isolated.

启动

Release 桌面应用

从 Releases 页面 下载安装包后，直接打开应用。如果你偏好经典界面，需要在应用内设置中切换，或在启动时使用 --agent 模式启动。

源码运行

python -m cyrene --agent

打开 http://localhost:4242。

页面功能详解

聊天

• 主面板——Markdown 渲染的消息区域，发送消息，实时查看流式响应
• 引导（Guidance）——当代理正在执行多轮操作时，你可以向它发送引导指令，影响当前轮次的行为
• 浏览器面板——当代理使用浏览器时自动显示实时画面

Agent Flow

SVG 画布可视化代理执行的每一个步骤：LLM 调用、工具执行、子代理通信、消息路由。每个节点可点击查看详情。

会话管理

• 列表——浏览、搜索历史会话，查看消息数和 token 用量
• 详情——查看完整消息记录、每个子代理的运行轨迹

记忆面板

• SOUL.md——浏览和在线编辑人格文档
• 短期记忆——查看压缩后的短期记忆条目，每条带情感权重标签（正面/负面/中性）
• 上下文——监控上下文窗口使用量

状态与调试

• 指标——子代理数、会话数、记忆条目数、任务数
• 工作者——主代理和每个子代理的运行状态
• 服务健康——LLM 端点可用性、SOUL.md 状态、MCP 服务器连接状态
• Context Debugger——检查最近 LLM 调用的完整上下文溯源元数据（_ctx）

与传统聊天的区别

相比 Workbench UI，Legacy UI 更适合：

• 需要全面监控代理内部运行状态的场景
• 深入调试工具调用和 LLM 行为
• 不需要项目隔离的简单使用场景

Launching

Release Desktop App

Download from GitHub Releases. To use Legacy UI, launch with --agent mode or switch in-app settings.

From Source

python -m cyrene --agent

Open http://localhost:4242.

Interface

• Chat — Markdown-rendered messages, live streaming, browser panel
• Agent Flow — SVG canvas visualizing every step of execution
• Sessions — browse, search, and inspect session history
• Memory — SOUL.md, short-term memory with valence, context usage
• Context Debugger — inspect provenance metadata for LLM calls

cyrene 命令（HTTP 客户端）

cyrene 命令是一个瘦 HTTP 客户端，与运行在 http://localhost:4242 的守护进程通信。使用 --json 获取机器可读输出。

# 后台启动守护进程
cyrene start

# 查看状态
cyrene status

# 发送消息
cyrene do "搜索今天的科技新闻" --session run_live

# 停止守护进程
cyrene stop

交互式本地 CLI

不需要启动 Web 服务器，直接运行代理的交互模式。适合快速测试和无头环境：

python -m cyrene.local_cli

可用命令：

聊天的斜杠命令

Workbench UI、Legacy UI 和交互式 CLI 都支持的斜杠命令：

完成的工作流示例

# 1. 启动守护进程
cyrene start

# 2. 创建一个会话并发送消息
cyrene do "分析当前目录的项目架构" --session analysis

# 3. 查看代理的推理轮次
cyrene flow --session analysis

# 4. 查看特定轮次的详细信息
cyrene flow --session analysis --round round_1

# 5. 获取系统状态
cyrene status

# 6. 完成后停止守护进程
cyrene stop

cyrene Command (HTTP Client)

The cyrene command communicates with the daemon at http://localhost:4242.

cyrene start
cyrene status
cyrene do "search today news" --session daily
cyrene stop

Interactive Local CLI

python -m cyrene.local_cli

Slash commands: /h, /mcp, /clear, /deep-reflect [focus], quit.

双阶段决策循环

这是 Cyrene 最核心的设计决策。传统的 AI Agent 在每次交互中都加载完整工具集，这在简单对话时造成不必要的开销（更大的系统提示 = 更多 token）。

Cyrene 的做法是将交互分为两个阶段：

阶段 1（快速通道）

每次用户交互都从阶段 1 开始。此阶段 LLM 可以在 use_tools、ask_user 和 quit 三个工具中选择：

• 如果用户只是在聊天或问简单问题，代理选择 quit 直接回复——仅一次 LLM 调用
• 如果用户请求涉及工具操作，代理选择 use_tools 进入阶段 2
• 如果代理需要向用户提问（如确认意图），选择 ask_user——也是一种纯聊天交互

这意味着简单的对话保持轻量和快速，而真正的工作仍然可以获得完整工具集的支持。出于提示缓存优化，完整的工具集定义实际上在阶段 1 就已经传递给 LLM，但只有上述三个工具可在阶段 1 调用。

阶段 2（完整工具集）

此阶段加载完整的工具集，包括：

代理在多轮之间保持状态，直到调用 quit 结束交互。最大轮次由 MAX_TOOL_ROUNDS 控制（默认 15）。

项目结构

src/
├── cyrene/                           # 核心引擎
│   ├── agent/                        # 双阶段循环、会话、轮次
│   │   ├── agent.py                  # 主代理编排
│   │   ├── coordinator.py            # 阶段路由、上下文组装
│   │   ├── session.py                # 会话持久化
│   │   ├── round.py                  # 工具轮次生命周期
│   │   ├── prompts.py                # 系统提示和阶段提示
│   │   └── deep_reflection.py        # 深度反思
│   ├── tool_impl/                    # 每个原生工具一个文件
│   ├── code_tools/                   # 代码索引、分析、Git
│   ├── knowledge/                    # 文档摄取、嵌入、检索
│   ├── channels/                     # Telegram、WeChat Bot
│   ├── modules/                      # 深度研究等管道
│   ├── registry_tools.py             # 中心工具注册表
│   ├── mcp_manager.py                # MCP 服务器生命周期
│   ├── search.py                     # 搜索管道
│   ├── searxng_manager.py            # SimpleXNG 进程管理
│   ├── scheduler.py                  # 心跳、cron、抽奖、管家
│   ├── soul.py                       # SOUL.md 读写
│   ├── short_term.py                 # 短期记忆压缩
│   ├── memory.py                     # 记忆上下文组装
│   ├── shells.py                     # 持久 Shell 会话
│   ├── browser.py                    # 持久浏览器
│   ├── cc_bridge.py / cc_terminal.py # Claude Code 集成
│   ├── behavior_learning.py          # 行为模式学习
│   ├── skills_registry.py            # 技能存储
│   ├── context_trace.py              # 上下文溯源标记
│   └── context_debug.py              # 调试日志查看器
├── webui/                            # FastAPI 后端 + SPA
│   ├── server.py                     # FastAPI 应用工厂
│   ├── routes.py                     # REST API + SSE
│   ├── routes_knowledge.py           # 知识库 API
│   ├── routes_workbench.py           # Workbench API
│   └── static/app/                   # JSX 前端组件
├── workbench-webui/                  # Workbench 前端资源
├── tests/                            # 测试套件
├── data/                             # 运行时数据、调试日志
├── workspace/                        # SOUL.md、模式、会话
└── store/                            # SQLite 数据库

安全模型

• 网络层——Web UI 只绑定 127.0.0.1，不暴露到网络。Electron 桌面构建在 OS 钥匙串中存储随机令牌，每次请求验证。
• 工作区守卫——文件读写和 Shell 操作有工作区范围守卫。在 Workbench 中，代理工作区被限定到项目的 workspacePath。
• 权限升降级——跨越工作区的读写操作需要权限提升请求。

Two-Phase Decision Loop

Each interaction starts in Phase 1 with only use_tools, ask_user, and quit available. Pure chat costs one LLM call. Tool-requiring requests escalate to Phase 2 with the full toolset.

Security

• Network — Web UI binds to 127.0.0.1 only. Electron adds keyring-based auth.
• Workspace guard — file/shell operations are scoped to the workspace.
• Permission elevation — cross-workspace ops require user approval.

三层架构

Cyrene 的记忆分为三个层级，随着时间从短期向长期流动：

记忆流动过程

1. 每轮对话保存在上下文窗口中。超过 MAX_HISTORY_MESSAGES 条时，最早的条目被裁剪——但不会丢失，因为后台压缩器会处理。
2. 后台压缩器定期将上下文窗口中的旧对话压缩为摘要，存入短期记忆。每条短期记忆包括：
• 情感权重（Valence）——正面/中性/负面评分
• 提及次数——同一主题被提到的频率
• 条目类型——事实 / 模式 / 偏好 / 情感
3. 自动保留规则——高频条目（≥3 次提及）和极端情感条目自动保留，不会被压缩器淘汰
4. 管家代理按 STEWARD_INTERVAL（默认 30 分钟）运行，审查短期记忆和最近对话，通过 APPEND/ERASE/MERGE 命令更新 SOUL.md

记忆退休（Memory Retirement）

过时或被取代的短期记忆可以退休（retire）。退休意味着：

• 该记忆停止被注入到上下文窗口中
• 它不再被回忆或引用
• 但文件本身不被破坏性删除

这比直接删除更安全——如果后续发现需要这个信息，仍然可以恢复。退休机制也避免了"已删除的记忆被重新学习"的问题。

SOUL.md 人格系统

workspace/SOUL.md 是 Cyrene 的长期记忆载体，也是一个可自进化的人格文档。其结构如下：

## SELF:IDENTITY
- I am Cyrene, a personal AI companion.
- My purpose is to be a friend and companion.

## SELF:BELIEFS


## RELATIONSHIP:USER
- Trust level: neutral
- Communication style: casual, direct

## MEMORY:HIGH_IMPACT


## PATTERN:USER


## TEMPORARY

管家代理的工作方式：

• 运行时，AI 模型审查最近的对话记录
• 判断哪些信息值得写入 SOUL.md
• 使用结构化命令更新：APPEND 添加、ERASE 删除、MERGE 合并
• TEMPORARY 部分的条目 24 小时后自动过期

SOUL.md 在每次交互时注入到系统提示中。由于启用了提示缓存，未变化的内容不会重新注入，缓存命中率高。

Workbench 记忆集成

Workbench UI 中的记忆页面按 workspace 隔离：

• 文件名为 wb_memory_<workspace>.json，不同项目的记忆互不干扰
• 对话自动沉淀到记忆
• Agent 可以通过 save_project_memory 工具主动写入记忆
• 反思（reflection）结果也落地到记忆库

Three-Layer Architecture

Memory Flow

1. Conversations stay in context window, auto-trimmed at the limit
2. Background compressor creates summaries with valence, mention count, type
3. High-frequency (>=3 mentions) and extreme-valence entries auto-preserve
4. Steward agent reviews and updates SOUL.md via APPEND/ERASE/MERGE

Outdated memories can be retired — stopped from injection without destructive deletion.

知识库

文档（PDF、文本、图片、代码）放入工作区后，会被哈希、分块、嵌入，并存储在工作区特定的 SQLite 数据库（store/kb_<workspace>.db）中。代理可以通过 SearchKnowledge 工具搜索语料库。

支持的类型

• 文本文件（.md、.txt、.py 等）
• PDF 文档
• 图片（通过视觉模型描述）

摄取流程

1. 提取文本——PDF 用 pypdf，图片用视觉模型，文本用 UTF-8
2. 过滤——跳过二进制文件和大于 10 MB 的文件
3. 分块和存储——存入 store/kb_<workspace>.db
4. 嵌入——如果配置了嵌入端点，生成向量嵌入

实体系统

结构化项目实体可以通过工具跟踪和查询：

• track_entity——创建实体
• query_entities——搜索实体
• update_entity——更新实体
• delete_entity——删除实体

实体存储在主 SQLite 数据库中，可限定到 Workbench 项目范围。

Knowledge Base

Documents (PDF, text, images, code) in the workspace are hashed, chunked, embedded, and stored in a workspace-specific SQLite database (store/kb_<workspace>.db). The agent can search via SearchKnowledge.

Supported Types

• Text files (.md, .txt, .py, etc.)
• PDF documents
• Images (described via vision model)

Ingestion Pipeline

1. Extract text (pypdf for PDF, vision for images, UTF-8 for text)
2. Filter — skip binaries >10 MB
3. Chunk and store in store/kb_<workspace>.db
4. Embed — vector index if embedding endpoint is configured

Entity System

Structured project entities can be tracked via tools:

• track_entity — create an entity
• query_entities — search entities
• update_entity — update an entity
• delete_entity — delete an entity

概述

子代理是主代理动态生成的独立代理实例。每个子代理：

• 拥有完整的工具访问权限（除了一小部分主代理专属黑名单如调度器）
• 通过基于文件的收件箱（inbox）系统与兄弟代理通信
• 拥有独立的思考过程和工具调用链
• 超时后自动终止

子代理特别适合：同时搜索多个来源、并行分析多个文件、执行可分解的子任务。

生命周期

1. running——子代理启动，开始执行任务
2. waiting——等待兄弟代理的结果或收件箱消息
3. resumed——收到消息后继续执行
4. done / timeout——正常完成或超时终止

主代理收集所有子代理的结果，综合为最终回复。

通信机制

子代理之间的通信使用文件基收件箱（inbox）系统：

• 每个子代理有一个专属收件箱目录
• 代理通过 send_agent_message 工具向兄弟的收件箱写入消息
• 收件箱中的消息在下一次思考循环中被读取和处理

典型使用场景

• 并行研究——同时搜索多个来源，合并结果
• 多文件分析——并行读取多个代码文件，分别分析后汇总
• 分解任务——"搜索资料"和"分析数据"两个子代理并行执行
• 竞争实验——多个子代理用不同方法解决问题，主代理取最优

注意事项

Sub-agents are independently spawned agents with full tool access (except a small main-agent blocklist). Communication uses a file-based inbox system.

Lifecycle

running → waiting → resumed → done / timeout

1. running — sub-agent starts executing
2. waiting — waiting for sibling results or inbox messages
3. resumed — continues after receiving a message
4. done / timeout — completed or timed out

特性

当代理使用浏览器工具时，聊天 UI 实时显示页面的画面——你能看到代理看到了什么和正在做什么。遇到登录墙时，代理可以把浏览器的控制权交给你。

• 持续浏览器上下文——懒惰启动，跨所有浏览器操作重用。配置文件在磁盘上持久化（<DATA_DIR>/browser_profile），cookies/登录状态跨运行保留。
• 实时画面——CDP screencast 通过 /ws/browser WebSocket 持续推送 JPEG 帧。
• 登录接管——代理遇到登录墙时请求接管 → 真实浏览器窗口打开 → 你登录 → 代理在已验证会话中继续。

设置

浏览器工具无需额外依赖的基本功能：browser_navigate 在没有 Playwright 时会降级为纯文本 HTTP 获取。

完整功能（浏览器自动化、实时画面、登录接管）：

pip install -e ".[browser]"
playwright install chromium

工作流程

因为配置文件是持久化的，对于大多数网站，接管只需要在首次登录时出现一次。

配置

浏览器配置通过加密配置仓库设置（环境变量键名在括号中）：

工具列表

• Persistent context — browser profile on disk, cookies survive restarts
• Live screencast — CDP JPEG frames via WebSocket
• Login takeover — agent hits login wall → real window opens → you log in → agent resumes authenticated

Setup

pip install -e ".[browser]"
playwright install chromium

概述

MCP（Model Context Protocol）是一个开放协议，允许 AI 应用通过标准化接口连接外部工具和服务。Cyrene 支持两种 MCP 传输方式：

• stdio——启动一个子进程，通过标准输入/输出通信。适用于本地工具和脚本。
• SSE（Server-Sent Events）——通过 HTTP 连接远程 MCP 服务器。适用于远程工具和 API。

添加 MCP 服务器

Stdio 服务器

# 文件系统工具（通过 npm）
cyrene mcp add filesystem stdio npx -y @modelcontextprotocol/server-filesystem /path/to/workspace

# 自定义 Python MCP 服务器
cyrene mcp add marp-deck stdio python /path/to/mcp_server.py

SSE 服务器

cyrene mcp add my-api sse http://localhost:3000/mcp

管理命令

示例输出

$ cyrene mcp list
Name              Transport    Status         Tools    Endpoint
filesystem        stdio        connected      3        npx -y @modelcontextprotocol/server-filesystem .
marp-deck         stdio        connected      4        python mcp_server.py

运行时管理

MCP 服务器也可以通过 Web UI（设置 → MCP 服务器）管理。添加、删除、启用/禁用 MCP 服务器无需重启 Cyrene 进程——MCP 工具会自动出现在内置工具旁边。

Supports stdio (subprocess) and SSE (HTTP) transports. Connected MCP servers expose tools alongside built-in ones.

cyrene mcp add filesystem stdio npx -y @modelcontextprotocol/server-filesystem /path
cyrene mcp add my-api sse http://localhost:3000/mcp

任务类型

通过 schedule_task 工具创建三种类型的任务：

调度机制

调度器的工作方式：

• 通过 schedule_task 工具创建任务（也可以在 Web UI 调度页面管理）
• 心跳按 HEARTBEAT_INTERVAL 秒（默认 300 = 5 分钟）运行，检查到期任务
• 任务持久化在 SQLite 中，带有完整执行历史
• 可以使用 list_tasks、pause_task、resume_task、cancel_task 工具管理

抽奖系统（Proactive Lottery）

抽奖系统是 Cyrene 的一个独特功能——它让代理可以在没有用户输入时主动发起行动：

• 每个心跳周期，代理有一定概率"中奖"
• 未中奖时，LOTTERY_DELTA（默认 0.15）加到累积概率上
• 概率上限为 LOTTERY_MAX（默认 0.85）
• 中奖后概率重置
• 只在 DAYTIME_START 到 DAYTIME_END 之间触发（避免半夜打扰）

这个机制让 Cyrene 能够"主动"关心你，而不是只能被动响应你的提问。

管家代理（Steward）

管家代理不是用户可调度的任务，而是一个特殊的内置代理，按 STEWARD_INTERVAL（默认 30 分钟）运行：

• 回顾最近的对话历史
• 判断需要更新 SOUL.md 的哪些内容
• 使用 APPEND/ERASE/MERGE 命令修改 SOUL.md
• 清理过期的 TEMPORARY 条目（24 小时过期）

• Cron — schedule by cron expression
• Interval — repeat at fixed intervals
• One-shot — execute once at a specified time

Lottery System

Each heartbeat cycle, the agent has a chance to "win" and send proactive messages. Probability accumulates until it hits the cap or wins, then resets.

SimpleXNG 内置搜索

Cyrene 使用 SimpleXNG——一个基于 SearXNG 的零配置封装。它不需要 Docker，不需要外部搜索 API 密钥，开箱即用。

• 自动配置——管理器自动生成 data/simplexng_settings.yml
• 自动启动——端口 8888 上的搜索实例在 Cyrene 启动时自动运行
• 代理发现——自动处理 proxy 配置

如果需要使用外部 SearXNG 实例：

# 在设置或 .env 中
SEARXNG_URL=https://your-searxng-instance.com
SEARXNG_AUTO_START=0

深度研究（Deep Research）

深度研究是一个多轮管道，适合需要深入调研的复杂问题：

1. 规划——将主问题分解为子问题
2. 搜索——并行搜索多个来源，获取结果
3. 阅读——获取和分析搜索到的源内容
4. 迭代——多轮循环，深入挖掘
5. 综合——将所有发现综合为一张"白板"
6. 导出——输出结构化 PDF 报告

状态：稳定。适合市场调研、技术调研、论文阅读等场景。

Cyrene uses SimpleXNG (based on SearXNG) — zero-config, auto-starts on port 8888. No Docker required.

概述

Quick Chat 是 Cyrene 的全局快捷对话功能。无论你在做什么，按下 Ctrl/Cmd+Shift+Space 即可呼出一个浮动聊天窗口，与 Cyrene 对话。

功能

• 全局快捷键——Ctrl/Cmd+Shift+Space 从任意界面呼出浮动窗口
• 截图粘贴——呼出时自动截取当前活跃窗口，作为图片发送给代理
• 独立窗口复用——关闭后固定到系统托盘，下次唤醒复用同一窗口
• 完整对话体验——与主聊天页共享运行管理器：工具调用轨迹、生成附件、实时思考卡片
• 后台继续——关窗后 Agent 仍在后台运行，结果持久化到服务端
• 系统托盘常驻——应用关闭到托盘，后台持续运行，随时唤醒

使用方式

启动 Cyrene 后：

1. 按下 Ctrl/Cmd+Shift+Space 呼出浮动窗口
2. 输入问题或指令，或直接粘贴截图
3. 随时按快捷键再次呼出继续对话
4. 关闭窗口时自动回到系统托盘，不会中断正在进行的任务

Overview

Quick Chat is Cyrene's global shortcut chat feature. Press Ctrl/Cmd+Shift+Space from anywhere to open a floating chat window and talk to Cyrene.

Features

• Global shortcut — Ctrl/Cmd+Shift+Space from any application
• Screenshot paste — captures the active window on invocation
• Independent window — closes to system tray, reuses the same window next time
• Full chat experience — shared run manager with tool call traces, artifacts, real-time thinking cards
• Background execution — agent continues after closing the window
• System tray — app lives in the tray, always ready

Usage

1. Press Ctrl/Cmd+Shift+Space to open the floating window
2. Type your question or paste a screenshot
3. Press the shortcut again to resume anytime
4. Close to system tray — running tasks are not interrupted

调试

详细模式

记录每个 LLM 调用的完整上下文（提示词、工具定义、响应、耗时）和上下文溯源：

python -m cyrene.local_cli --verbose
python -m cyrene --workbench --verbose

调试日志

详细模式下，事件写入带时间戳的 JSONL 文件：

data/debug_20260617_133426.jsonl

每行是一个 JSON 对象，包含：

{"type": "llm_call", "caller": "main_agent", "phase": "phase1",
 "messages": [...], "response": {...}, "duration_ms": 423.0}

{"type": "tool_call", "caller": "subagent_poet", "tool": "send_agent_message",
 "args": {...}, "result": "Message sent.", "duration_ms": 150.2}

Context Debugger

每条 LLM 调用都带有 _ctx 元数据，标记每个上下文块的来源（系统提示、SOUL.md、短期记忆、历史消息、工具结果等）。调试方式：

# 通过 API
curl http://localhost:4242/api/context-debug/events?limit=10
curl http://localhost:4242/api/context-debug/events/evt_3b22f9a5c0cb

# 通过 CLI
cyrene flow --session run_live --round round_xxx --id evt_3b22f9a5c0cb

Web UI 调试

• 状态页面——显示实时调试日志、系统指标、工作线程状态、服务健康
• Agent Flow 页面——SVG 流程图可视化每一次 LLM 调用和工具执行

测试

# 安装开发测试依赖
uv pip install -e ".[dev]"

# 运行所有测试
uv run pytest -q

# 运行特定测试文件
python -m pytest tests/test_context_trace.py -v

# 带日志输出
uv run pytest -v --tb=long

项目约定

• Python 3.12+——类型提示、模式匹配等最新特性
• Ruff——代码检查（行长 180）
• 类型提示——所有函数签名必须标注类型
• Async/await——全程异步（asyncio）
• 模块模式——每个模块单一职责：
  • 函数调用用于直接导入
  • 事件总线（debug.publish_event）用于实时 UI 更新
  • 文件收件箱（inbox.py）用于子代理通信
  • SQLite 用于结构化持久化

添加新工具

如果你想为 Cyrene 添加新的原生工具：

1. 在 cyrene/tool_impl/ 下创建新模块（如 my_tool.py）
2. 模块导出 TOOL_DEF（工具定义字典）和 handler（async 处理函数）
3. 在 cyrene/registry_tools.py 的 _NATIVE_TOOL_MODULES 中注册模块
4. 可选：在 src/webui/static/app/settings.jsx 中添加 UI 入口

MCP 协议工具不需要修改 Cyrene 代码——通过 cyrene mcp add 或 Web UI 直接连接即可。

CI / 发布

目前没有 CI 持续集成测试任务。标记发布前请在本地运行 uv run pytest -q。

Debugging

Verbose Mode

Logs every LLM call (full prompt, tools, response, duration) and context trace to data/debug_*.jsonl:

python -m cyrene.local_cli --verbose
python -m cyrene --workbench --verbose

Debug Logs

In verbose mode, events are written to timestamped JSONL files. Each line is a JSON object:

{"type": "llm_call", "caller": "main_agent", "phase": "phase1",
 "messages": [...], "response": {...}, "duration_ms": 423.0}

{"type": "tool_call", "caller": "subagent_poet", "tool": "send_agent_message",
 "args": {...}, "result": "Message sent.", "duration_ms": 150.2}

Context Debugger

Every LLM call is tagged with _ctx provenance metadata showing where each context block came from (system prompt, SOUL.md, short-term memory, history, tool results). View via the Web UI Context Debugger page or API:

curl http://localhost:4242/api/context-debug/events?limit=10
curl http://localhost:4242/api/context-debug/events/evt_3b22f9a5c0cb

Via CLI:

cyrene flow --session run_live --round round_xxx --id evt_3b22f9a5c0cb

Testing

uv pip install -e ".[dev]"
uv run pytest -q
python -m pytest tests/test_context_trace.py -v

Project Conventions

• Python 3.12+ with type hints on all function signatures
• Ruff for linting (line length: 180)
• Async/await throughout (asyncio)
• Single responsibility per module. Cross-module communication via function calls, event bus, file-based inbox, and SQLite.

Adding New Tools

1. Create a module under cyrene/tool_impl/ (e.g., my_tool.py)
2. Export TOOL_DEF (dict) and handler (async callable)
3. Register in cyrene/registry_tools.py::_NATIVE_TOOL_MODULES
4. Optionally add a UI entry in src/webui/static/app/settings.jsx

For MCP servers, use cyrene mcp add or the Web UI — no code changes needed.

CI / Release

No CI test runner currently. Run uv run pytest -q locally before tagging a release.

cyrene 命令参考

cyrene 命令是一个 HTTP 客户端，与 http://localhost:4242 的守护进程通信。使用 --json 获取机器可读输出。

进程管理

会话管理

代理轮次检查

记忆

MCP 管理

系统

Telegram Bot

在 Web UI 设置或加密配置中配置以下值：

TELEGRAM_BOT_TOKEN=你的_bot_token
OWNER_ID=你的_telegram_user_id

然后运行：

python -m cyrene

Telegram Bot 支持与 Web UI 完全相同的双阶段循环、子代理和工具集。你可以从 Telegram 执行搜索、文件操作、生成子代理等所有操作。

WeChat Bot

在加密配置中设置 WECHAT_BOT_TOKEN 和 WECHAT_OWNER_ID。启动 Cyrene Web UI 后，WeChat 集成自动运行。状态显示在 Web UI 设置页面。

完整工作流示例

# 1. 后台启动守护进程
cyrene start

# 2. 检查系统状态
cyrene status

# 3. 发送消息到实时会话
cyrene do "帮我搜索今天的 AI 新闻" --session daily

# 4. 查看代理执行了哪些轮次
cyrene flow --session daily

# 5. 查看特定轮次的工具调用详情
cyrene flow --session daily --round round_1

# 6. 查看系统指标
cyrene status

# 7. 完成工作后停止守护进程
cyrene stop

cyrene Commands

The cyrene command communicates with the daemon at http://localhost:4242. Use --json for machine-readable output.

Process Management

Session Management

Agent Round Inspection

Memory

MCP Management

System

Telegram Bot

Set TELEGRAM_BOT_TOKEN and OWNER_ID in the Web UI or encrypted config store, then run python -m cyrene. The Telegram bot supports the same two-phase loop, sub-agents, and tools as the Web UI.

WeChat Bot

Set WECHAT_BOT_TOKEN and WECHAT_OWNER_ID in the config store. Status is shown on the Web UI Settings page.

Full Workflow Example

# 1. Start daemon in background
cyrene start

# 2. Check system status
cyrene status

# 3. Send message to a live session
cyrene do "search today's AI news" --session daily

# 4. View agent execution rounds
cyrene flow --session daily

# 5. Inspect a specific round's tool calls
cyrene flow --session daily --round round_1

# 6. View system metrics
cyrene status

# 7. Stop daemon when done
cyrene stop