本地运行与核心工作流指南
Senrelay(续境)是面向 macOS 14.0+(Apple Silicon)的本机后台服务与桌面工作台,基于 MIT 协议免费开源($0,无需注册),提供多宿主配置管理、伴生自动记忆沉淀与跨 Agent 全文对话接力。
多宿主配置管理在常驻顶栏切换 Claude Code、Codex、Cursor、Antigravity、OMP、OpenCode 与扩展宿主(详见支持矩阵),以 contextcore 接入 /mcp/ 服务并同步服务商、MCP、Skills 与提示词。每次写入自动留存快照,外部手改时弹出差异确认。
双层自动记忆与工作台对话中伴生维护工作任务(working_tasks)与带版本的长期记忆,保留原话出处并支持核心规则置顶、AGENTS.md 导出与多格式资料导入。
跨 Agent 全文接力在新 Agent 输入 /contextcore 或「接力」,先通过短简介认出会话,再分页读完完整原文并在上下文中直接压缩(仅选序号先待命,附带任务则继续执行,详见工程保障说明)。
下载安装与运行环境
下载 macOS Beta.4。可在发布页查看更新与验收记录。软件面向 Apple Silicon(arm64)、macOS 14.0 及以上,免费开源($0,MIT 协议),安装包已内置 Python 后台与前端工作台,无需单独安装运行环境。
Public Beta 当前采用 ad-hoc 签名,尚未完成 Apple 公证。按 SHA256SUMS 核对并解压安装包后,按以下步骤完成首次启动:
- 将
Senrelay.app移入/Applications目录。 - 在终端执行
xattr -cr /Applications/Senrelay.app清理隔离属性(或在系统设置「隐私与安全性」中点击仍要打开;仓库内亦附有app/macos/install-macos.sh)。
包名说明:PyPI 上名为 contextcore 的包为无关第三方项目,请勿执行 pip install contextcore。需要从源码运行时,请克隆仓库后按下一节安装开发依赖。
用户数据默认存放在 ~/Library/Application Support/ContextCore。关闭窗口(Cmd+W)不会停止后台常驻服务;卸载应用也不会删除已保存的项目历史、记忆或钥匙串凭据,可通过 contextcore backup 随时导出整库在线备份。
首次打开后,怎么确认能用?
- 先确认工作台能打开:若应用已打开但宿主里找不到
contextcore,先在同一台 Mac 的浏览器访问http://127.0.0.1:8420,区分本机服务未启动和宿主尚未接入。 - 只选一个宿主试接入:在「Agent 管理」中选你正在用的 Claude Code 或 Codex,核对
contextcore是否指向本机的/mcp/。如果宿主仍看不到工具,打开对应宿主的配置路径核对,别先覆盖其他宿主的配置。 - 用一条测试会话验收:在接收方输入
/contextcore,核对来源项目和时间。先只回复序号,让它汇报并待命,确认选对会话后再交代下一步。
源码开发要求
- 操作系统:macOS 14.0 及以上(Apple Silicon)
- Python:推荐 Python 3.12(最低 3.11,需 SQLite
blobopen支持) - Node.js:Node 22 LTS 或 Node 24 LTS
安装源码依赖
请在仓库根目录下依次执行以下命令:
# 1. 创建后端虚拟环境并安装开发包(自动注册 contextcore CLI)
python3.12 -m venv app/backend/.venv
app/backend/.venv/bin/python -m pip install -e 'app/backend[test]'
# 2. 安装前端依赖
npm --prefix app/frontend ci --ignore-scripts
启动工作台
日常使用推荐模式 A;界面开发调试可使用模式 B 的 Vite 热重载模式。
模式 A:集成运行(后端直接托管构建产物)
# 构建前端静态包(输出至 app/frontend/dist-staging)
npm --prefix app/frontend run build
# 启动本机服务(源码调试端口 18420,常驻应用端口为 8420)
app/backend/.venv/bin/contextcore serve --host 127.0.0.1 --port 18420 --data-dir "$HOME/.contextcore/dev-data" --frontend-dir app/frontend/dist-staging
启动后在浏览器访问 http://127.0.0.1:18420(桌面常驻版访问 http://127.0.0.1:8420)。
模式 B:前后端分离调试(热重载)
# 终端 1:启动后端 API 与 MCP 服务
app/backend/.venv/bin/contextcore serve --host 127.0.0.1 --port 18420 --data-dir "$HOME/.contextcore/dev-data" --no-static
# 终端 2:启动前端 Vite 开发服务器(端口 15173)
npm --prefix app/frontend run dev:isolated
启动后在浏览器访问 http://localhost:15173。
三大核心工作流
多宿主配置切换与同步
在「Agent 管理」顶栏切换 Claude Code、Codex、Cursor、Antigravity、OMP 或 OpenCode 后点击「一键接入续境」,即可按 contextcore 键名接入 http://127.0.0.1:8420/mcp/ 并配齐历史路径与伴生组件;支持服务商预设、端点测速、MCP/Skills 同步及写前快照。
双层记忆与版本治理
在接入 Agent 中正常对话,伴生组件一边跟踪工作任务(working_tasks),一边沉淀带原话出处的长期记忆并留痕更新;教训晋升须核验原对话来源,存在分歧则转入「待确认」。
跨 Agent 全文对话接力
在新 Agent 输入 /contextcore 或说「接力」,先通过短简介认出会话,随后由工具 read_conversation_messages 分页读完完整原文并原地压缩;仅选序号先汇报待命,附带任务才直接续做。
本机数据与安全边界
本机存储与钥匙串隔离
会话索引、工作任务与项目记忆均保留在 Mac 本地目录(目录权限 0700,SQLite 文件 0600),支持 contextcore backup 在线备份;API Key 独立保存在系统钥匙串中,配置导出默认剔除密钥。
独立授权与预算保护
读取会话、修改宿主配置、下载本地模型三项权限彼此独立,启动或导入配置绝不静默改写已安装宿主 Skill;受保护规则超出预算时显式阻断而非截断,外部手改配置文件时弹窗核对差异。
版本事实、限制与作者说明
适用边界与定价(2026-11-15 核对)
定价为 $0(MIT 开源协议,免注册),当前版本 v1.0.0-beta.4。不适用场景:不支持 Windows、Linux 或 Intel Mac;纯单机回环运行(127.0.0.1:8420),无云同步;九类扩展宿主仅管理配置文件(详见首页核对表与5 种方案对比)。
作者与许可协议
Senrelay(仓库 qingsongcui/ContextCore)由独立开发者 Qingsong Cui(George O'Nair)(GitHub @qingsongcui · X @George_ONair)维护,零云端遥测,基于 MIT License 按原样提供。
常见问题排查
首次打开 Senrelay.app 提示“已损坏”或无法验证开发者怎么办?
Public Beta(v1.0.0-beta.4)目前使用 ad-hoc 签名,尚未加入 Apple 公证。将应用移入 /Applications 后执行一次 xattr -cr /Applications/Senrelay.app 即可正常启动,或在系统设置「隐私与安全性」中点击仍要打开。
如何在宿主配置文件确认 MCP 服务名称与端口?
桌面常驻应用默认监听 http://127.0.0.1:8420,源码调试默认使用 18420。各宿主 MCP 配置中的服务键名为 contextcore(指向 /mcp/),伴生接力指令为 /contextcore;不要手动填写 senrelay-mcp。
误执行了 pip install contextcore 怎么处理?
PyPI 上的 contextcore 属于无关第三方项目,并非本仓库后端。请卸载该包后,改用官方 ZIP安装桌面版,或在仓库根目录执行 app/backend/.venv/bin/python -m pip install -e 'app/backend[test]'。