CONTEXTCORE / LOCAL WORKBENCH GUIDE

本地运行与核心工作流指南

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 或「接力」,先通过短简介认出会话,再分页读完完整原文并在上下文中直接压缩(仅选序号先待命,附带任务则继续执行,详见工程保障说明)。

01 · DOWNLOAD & REQUIREMENTS

下载安装与运行环境

下载 macOS Beta.4。可在发布页查看更新与验收记录。软件面向 Apple Silicon(arm64)、macOS 14.0 及以上,免费开源($0,MIT 协议),安装包已内置 Python 后台与前端工作台,无需单独安装运行环境。

Public Beta 当前采用 ad-hoc 签名,尚未完成 Apple 公证。按 SHA256SUMS 核对并解压安装包后,按以下步骤完成首次启动:

  1. 将 Senrelay.app 移入 /Applications 目录。
  2. 在终端执行 xattr -cr /Applications/Senrelay.app 清理隔离属性(或在系统设置「隐私与安全性」中点击仍要打开;仓库内亦附有 app/macos/install-macos.sh)。

包名说明:PyPI 上名为 contextcore 的包为无关第三方项目,请勿执行 pip install contextcore。需要从源码运行时,请克隆仓库后按下一节安装开发依赖。

用户数据默认存放在 ~/Library/Application Support/ContextCore。关闭窗口(Cmd+W)不会停止后台常驻服务;卸载应用也不会删除已保存的项目历史、记忆或钥匙串凭据,可通过 contextcore backup 随时导出整库在线备份。

首次打开后,怎么确认能用?

  1. 先确认工作台能打开:若应用已打开但宿主里找不到 contextcore,先在同一台 Mac 的浏览器访问 http://127.0.0.1:8420,区分本机服务未启动和宿主尚未接入。
  2. 只选一个宿主试接入:在「Agent 管理」中选你正在用的 Claude Code 或 Codex,核对 contextcore 是否指向本机的 /mcp/。如果宿主仍看不到工具,打开对应宿主的配置路径核对,别先覆盖其他宿主的配置。
  3. 用一条测试会话验收:在接收方输入 /contextcore,核对来源项目和时间。先只回复序号,让它汇报并待命,确认选对会话后再交代下一步。

源码开发要求

  • 操作系统:macOS 14.0 及以上(Apple Silicon)
  • Python:推荐 Python 3.12(最低 3.11,需 SQLite blobopen 支持)
  • Node.js:Node 22 LTS 或 Node 24 LTS
02 · INSTALLATION

安装源码依赖

请在仓库根目录下依次执行以下命令:

# 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
03 · RUNNING

启动工作台

日常使用推荐模式 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。

04 · WORKFLOWS

三大核心工作流

多宿主配置切换与同步

在「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 分页读完完整原文并原地压缩;仅选序号先汇报待命,附带任务才直接续做。

05 · SECURITY BOUNDARIES

本机数据与安全边界

本机存储与钥匙串隔离

会话索引、工作任务与项目记忆均保留在 Mac 本地目录(目录权限 0700,SQLite 文件 0600),支持 contextcore backup 在线备份;API Key 独立保存在系统钥匙串中,配置导出默认剔除密钥。

独立授权与预算保护

读取会话、修改宿主配置、下载本地模型三项权限彼此独立,启动或导入配置绝不静默改写已安装宿主 Skill;受保护规则超出预算时显式阻断而非截断,外部手改配置文件时弹窗核对差异。

06 · FACT SHEET & AUTHOR

版本事实、限制与作者说明

适用边界与定价(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 按原样提供。

07 · TROUBLESHOOTING

常见问题排查

首次打开 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]'。