CONTEXTCORE / LOCAL WORKBENCH GUIDE

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

Senrelay（续境）由 macOS 本机后台服务与桌面/浏览器工作台组成，集成了多宿主配置管理与本机配置同步、伴生自动记忆沉淀（附 💡 回执），以及跨 Agent 对话接力。

核心能力速览

1. 多宿主配置管理：常驻顶栏秒切目标宿主（支持 Claude Code、Codex、Cursor、Antigravity、OMP、OpenCode 六大主力宿主及扩展宿主），支持「一键接入续境」、一键切换模型服务商及 MCP / Skills / 系统提示词，每次写入自动留存回滚快照，遇到外部手动修改冲突时弹窗核对差异；文件写入与宿主进程实际加载分别独立核验。

2. 伴生自动记忆沉淀：日常对话中由伴生 MCP 与 Skills 采集偏好、架构决定、约束、进度与踩坑经验（保留原话出处并给出简短 💡 回执），并在工作台支持 📌 核心规则置顶、AGENTS.md 规则手册生成与多格式资料导入。

3. 跨 Agent 对话接力：打开任意新 Agent 输入 /contextcore 或说「接力 / 接着做 / relay」，自动列出近期对话记录候选（含序号、来源 Agent、所属项目、标题与摘要）——仅选序号先加载上下文并汇报摘要待命，附带具体任务指令则直接续做。

1. 下载包与运行环境 Download & Requirements

可通过 Homebrew Cask 一键安装，或前往 GitHub Releases（v1.0.0-beta.1）下载发布附件。Senrelay-macOS.zip 面向 Apple Silicon（arm64）、macOS 14.0 及以上，免费开源（MIT 协议），仅打包 Senrelay.app 本体，内含独立 Python 后台与前端工作台资源，无需单独安装 Python 或 Node（各 AI 宿主自身的运行环境仍需具备）。

# 推荐方式：通过 Homebrew Cask 安装桌面应用
brew install --cask qingsongcui/tap/senrelay

安装包当前采用 ad-hoc 签名，暂未执行 Apple 公证。手动下载核对 SHA256SUMS 并解压后，按以下两步首次启动指引打开（无需全局关闭 Gatekeeper）：

将 Senrelay.app 移入 /Applications；
在终端执行 xattr -cr /Applications/Senrelay.app 清理隔离属性（或在「系统设置 → 隐私与安全性 → 仍要打开」中放行；源码仓库亦提供 app/macos/install-macos.sh 供终端执行）。

包名甄别提示：请切勿执行 pip install contextcore——PyPI 上的同名包为无关第三方项目；源码开发请仅在克隆本仓库后执行下方 pip install -e 'app/backend[test]'。

数据默认保存在 ~/Library/Application Support/ContextCore。关闭窗口（如 Cmd+W）不会停止后台常驻服务；需要停服务时请在设置页或 CLI 执行明确停止操作。支持通过 contextcore backup 生成整库 SQLite 在线备份；卸载 App 不会删除项目历史与记忆。

从源码开发

在启动本机源码服务前，请确认本地 macOS 环境满足以下依赖版本：

操作系统：macOS 14.0 及以上（Apple Silicon，支持系统钥匙串独立凭据托管与 LaunchAgent 守护）。
Python：Python 3.12 推荐（最低 3.11，需 SQLite blobopen 支持）。
Node.js：Node 22 LTS 或 Node 24 LTS（支持引擎 ^22.22.2 || ^24.15.0 || >=26）。

2. 安装依赖 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

3. 启动工作台 Running

提供两种启动方式：集成运行模式（适合日常主力使用）与前后端热重载模式（适合界面开发调试）。

模式 A：集成部署（后端直接托管前端工作台）

# 步骤 1：构建前端包（输出至 app/frontend/dist-staging）
npm --prefix app/frontend run build

# 步骤 2：启动本机服务（监听 127.0.0.1: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（若已配置 macOS 常驻服务则可直接访问 http://127.0.0.1:8420）。

模式 B：前后端独立调试（Vite 开发热重载）

# 终端 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，自动代理至 18420）
npm --prefix app/frontend run dev:isolated

启动后在浏览器打开：http://localhost:15173

4. 三大核心工作流实战 Core Workflows

① 多宿主配置切换与同步

进入「Agent 管理」，在常驻顶栏选定目标宿主（Claude Code、Codex、Cursor、Antigravity、OMP、OpenCode 等），点击「一键接入续境」完成接入。可一键填入供应商预设模板并测速验证，一键切换模型、MCP 工具、Skills 与使用规则（自动留存快照，冲突时弹窗核对差异），并支持同步与导入本机已有配置。

② 伴生自动记忆沉淀

在已绑定伴生 MCP 与 Skills 的 Agent 中正常对话工作。当讨论产生架构决定、个人偏好、边界约束、阶段进展或踩坑教训时，伴生组件会采集带来源引用的结构化记忆并附上简短 💡 回执；分歧项进入「待确认」处理。

③ 跨 Agent 对话接力

在新 Agent 输入 /contextcore 或说「接力 / 接着做」列出近期对话候选：只选序号先加载上下文汇报摘要并等待下一句指令，附带具体任务指令则直接续做。

5. 本机数据与安全边界 Data & Security

本机优先存储与钥匙串隔离

会话索引、项目记忆与配置快照全部保存在你的 Mac 本机目录（目录权限 0700，数据库文件 0600），支持通过设置页或 contextcore backup 创建整库 SQLite 在线备份；API Key 独立保存在 macOS 系统钥匙串中，配置导出包默认排除已托管的密钥凭据。

独立授权、多模路由与配置守护

读取会话历史、修改宿主配置文件、下载可选本地语义模型三类权限彼此独立，绝不捆绑。单个宿主可按需切换直连、本机代理转发（含优先级备用链）或模型聚合；每次宿主配置文件更改均自动留存快照以便回滚，遇到外部手动修改会阻止覆盖并弹窗提示核对差异。