Compass

本地优先的个人 AI 助理：长期主对话、Side chat、人生目标与价值观，以及按电脑工作目录组织的项目对话。内核使用相邻的 atomix-core；重构方向见 开发方案。

当前是可构建的开发版本，完整产品仍在实现中。页面已接入本地数据，不包含伪装成真实模型输出的演示回复。

启动

需要 Node.js 22.13 或以上，并保留以下源码目录关系：

代码开源/
  atomix-core/    # 需要已经构建出 dist
  semaclaw/      # 功能迁移参考
  atomix-cli/    # Harness / 插件参考
  Compass/

在 Compass 目录执行：

npm install
npm run build
npm start

访问 http://127.0.0.1:18789。开发前端可另运行 npm run dev:web。启动脚本使用 Node 的 tsx loader，不依赖 tsx CLI 的 IPC 监听。

首次进入设置填写模型接口、模型名和密钥。保存配置不意味着联网验证成功，真实调用在发送消息时发生。无需鉴权的本地兼容接口可填写 local 作为密钥占位。

项目通过文件夹绝对路径绑定本机目录。创建项目后点击“开始一个任务”，对话会在该目录使用“专注工作”Harness。它不是云端项目看板；现有文件保持原位。

当前能力

• Chats：固定主线、独立对话、带来源上下文的 Side chat、显式带回结论、流式回复、停止执行。
• Projects：真实目录绑定、服务端文件夹选择器、目录内文本预览、项目对话与目录范围继承；目录丢失时标记并提供重新定位，不会默默切到别的目录。
• Goals / Ideas：价值观、目标、里程碑、回顾时间、灵感转目标。
• Feeds：目标回顾、免打扰和暂停、重复调度去重。
• Gallery：独立成果页、Markdown / 隔离 HTML 预览、版本与导出；静态 LaunchUI 文件可进入 Gallery；HTML 成果可由用户显式声明“允许页面脚本”，在 allow-scripts 的隔离 iframe 中运行且无网络。
• Wiki：笔记编辑与历史版本。尚未迁移 SemaClaw 的 Git、反链和搜索。
• 界面配色：设置页「界面配色」只定三个基色（底色 / 主题色 / 字体色），其余颜色由 style.css 的 color-mix 推导；五个一键预设（远山海岸 / 黛黛山川 / 草莓奶油 / 麦田黄昏 / 薄荷汽水）加调色盘自定义，自己调过的颜色单独存成「我的配色」一格，保存在 config.json 的 appearance，执行中也可改。
• Workflows：SemaClaw YAML/frontmatter 导入、依赖推断、DAG 混合执行、目录占用控制、取消/超时、固定运行快照、结果进入 Gallery；定时运行（每天固定时间或固定间隔）在创建计划时固定一份快照，到期自动开始，重启只补偿一次，目录占用时跳过并记录。
• Harness：与 atomix-cli 同款的可配置设计——每个 harness 是 .compass/harness/<id>/ 下的 harness.yaml + rules.md + SOUL.md，完整快照声明工具（白/黑名单、defer、pin）、Skills / Agents / MCP 取舍、提示词段 replace / disable / insert、记忆与人设三态、模型槽位、thinking、温度，以及 compass: 宿主块（权限模式、时限、团队并发、插件、轻量记忆范围）。设置页提供表单与 YAML 两种编辑、目录导入、三文件导出、按项目预览生效配置与来源、相对 base 的差异；每次执行保存配置与解析结果快照。见 Harness 说明。
• 全局配置：.compass/config.json（与 ~/.atomix/config.json 同款）控制 MEMORY.md / SOUL.md 供给层开关与 base 默认值；损坏时拒绝合并写入。
• 长期记忆文件：个人级 MEMORY.md 与项目级 projects/<项目>/MEMORY.md 由内核在新会话与压缩后注入，主助理可维护；SOUL.md 为人设。记忆页可直接查看与编辑这些文件。
• 多供应商模型配置：沿用 atomix-cli 的供应商预设，支持多个已保存模型、独立主/快速默认选择、协议与地址编辑；更换供应商/端点不会自动沿用旧密钥。
• 长期对话摘要：复用 Atomix 上下文压缩，展示整理状态、摘要历史和上下文长度；聊天原文保留，摘要与明确记录的记忆分开。
• 轻量记忆：个人/项目范围、搜索、修改、置顶和停用；按当前话题在固定长度内选择，使用本机文本匹配，无额外模型或向量数据库。
• 主动回顾：按目标进度生成提醒，支持每日额度、至少一小时的间隔、免打扰、稍后提醒和暂停目标；可带入长期主线继续讨论。
• 知识沉淀：Gallery 指定版本存入 Wiki，保留成果和对话来源；支持标题/正文搜索、项目筛选、笔记关联与反向引用、历史版本恢复和带入新对话。
• 对话表单：接入 Atomix FormUI，支持文字、数值、选项、日期和可编辑表格；填写、跳过和结果回看都在对话内完成。
• 团队协作：直接在对话中提出任务，由 Atomix AgentTeam 安排成员与依赖；工具栏查看真实进度，结果回到主助理、Gallery 和 Feeds。见 团队协作说明。
• 插件：本地目录或 git / 本机来源（marketplace.json 清单，与 atomix-cli / SemaClaw 同构）安装副本、内容摘要校验、独立启停/卸载、来源同步与版本更新；贡献点含规则、Skills、Agent 目录、工作流、harness、hooks、记忆提供者模块、stdio MCP。见 插件说明。
• 网页搜索：每次对话自带 web_search / fetch_url（内置 MCP 服务，只读自动放行）；多引擎自动回退，默认顺序按地区预设、不需要 Key，中国大陆用百度 / 360 直连，其他亚洲地区 Brave / DuckDuckGo 优先，可选 SearXNG 与 Tavily / Brave / Serper Key。见 搜索说明。
• SemaClaw 数据导入：只读扫描 ~/.semaclaw 的 wiki 与 workflows，dry-run 报告、附加式导入、可回退（已修改的记录保留）。

尚未完成：自动阶段摘要（当前复用内核压缩摘要）；桌面壳的安装包分发（当前需自备 Electron）。团队调度直接复用 Atomix；扩展成员通过插件 Agents 提供，不要求重建 SemaClaw 的持久 worker 机制。

数据与运行

默认存储在项目根目录 .compass/；可通过 COMPASS_DATA_DIR 指定其他目录，通过 PORT 修改端口。

• compass.sqlite：个人档案、业务数据、对话、事件、模型设置、每次执行的配置快照。
• config.json：供给层开关与 base 默认值（atomix-cli 同款）。
• harness/<id>/：harness 定义文件（harness.yaml、rules.md、可选 SOUL.md），用户资产，可手改与互相拷贝。
• MEMORY.md、SOUL.md、projects/<项目>/MEMORY.md：长期记忆与人设文件。
• atomix/：Compass 独立内核历史、配置与日志。
• workspace/：主对话的默认工作空间；项目对话使用自己绑定的本机目录。

密钥存于本机配置，API 快照和导出不包含模型密钥。数据目录使用当前用户权限，当前没有额外的静态加密。删除轻量记忆不会删除原始对话及内核历史；完整遗忘与上下文清理仍需补齐。

服务仅绑定回环地址。读取文件的预览接口检查路径和符号链接边界；Agent 工具通过内核权限机制执行，工作目录与权限机制不等同于操作系统沙箱。

关闭页面后，本机服务仍运行才能继续任务和提醒；退出服务后不会在云端运行。重启时未完成执行标记为中断，不自动重放可能有副作用的操作。

HTML 成果默认为静态隔离预览，脚本和网络禁用；用户按成果显式开启“允许页面脚本”后才在隔离 iframe 内运行脚本，仍无网络。

桌面壳与原生目录选择器

ELECTRON=/path/to/Electron npm run desktop            # 用任意一份 Electron 可执行文件打开桌面窗口
ELECTRON=/path/to/Electron npm run desktop -- --smoke # 无人值守验证后退出

Electron 不作为基础依赖（体积大、需要 registry）；apps/desktop/main.cjs 拉起同一份本机服务并通过 preload 暴露 window.compassDesktop.pickFolder，网页检测到它时“连接文件夹 / 重新定位”改用系统原生目录对话框，否则使用服务端文件夹浏览。

真实浏览器与真实模型验收

PLAYWRIGHT_MODULE=/path/to/node_modules/playwright npm run e2e:browser   # 本机 Chrome：桌面 / 窄窗口 / 减少动画三种条件走一遍页面，截图并检查控制台错误、横向滚动、键盘焦点
COMPASS_LIVE_PROFILE='deepseek-chat[custom-openai]' npm run test:live    # 读取 ~/.atomix/model.conf 的 profile，向真实服务商发起少量请求：对话回复、读取本机文件、维护 MEMORY.md、脚本→Agent 工作流进 Gallery

两者都依赖本机已有的 Chrome / Playwright / 模型密钥，不随安装提供；未设置时 test:live 跳过而不是伪报通过。

打包与干净环境验证

npm run package                                   # release/compass-<版本>/ 与 .tgz：源码 + 构建好的前端 + 生产依赖真实副本
npm run verify:release -- release/compass-0.1.0.tgz   # 解压到临时目录、全新数据目录启动、检查接口与页面后退出

发行版只需 Node.js 22.13+，node start.mjs 启动，不访问 npm registry；体积约 200 MB（包含内核依赖的完整副本）。

发布到 npm（包名 compasss）

npm login --registry https://registry.npmjs.org/   # 首次
npm run pack:npm                                   # 只打包到 release/npm/，本地验证用
npm run pack:npm -- --publish                      # 打包并发布到 npmjs.com

用户侧 npm i -g compasss 后直接运行 compasss（默认端口 18789、数据目录 ~/.compass，可用 --port / --data-dir 或 PORT / COMPASS_DATA_DIR 覆盖）。服务端与 atomix-core 预编译为单个 JS，运行期不需要 tsx。首次发布、发新版本与验证步骤见 docs/publishing.md。

验证

npm test
npm run build

测试覆盖 harness 解析 / 解析器 / 库 / config.json 语义与真实内核中的工具白名单、提示词段、SOUL.md / MEMORY.md 注入、温度、模型回落、三态记忆，以及目录隔离、分支范围、持久化、重启中断、提醒去重、Wiki 版本，以及工作流依赖校验、目录执行、脚本输入隔离、失败传播、进程取消、运行恢复和真实 Atomix 内核的流式事件、Read 工具、历史恢复、script → agent 混合链路，以及并行会话中的插件 Skills/Agents/规则和真实 stdio MCP 进程隔离。团队测试覆盖实际 Atomix AgentTeam 调用、依赖结果传递、成员进度、主助理汇总、Gallery/Feeds 和重启中断。集成测试仅替换远程模型传输，因此不证明真实模型服务可用。

本次开发环境不能解析 npm registry，也禁止本地端口监听。构建与测试使用相邻项目已安装依赖的本地符号链接；新环境安装和浏览器视觉验收尚未通过，不应视为已交付稳定版本。

来源

产品与宿主重构参考 SemaClaw 的 AgentPool、桥接、Workflow、Wiki、调度设计，Harness/扩展边界参考 Atomix CLI。当前 atomix-core 通过本地包依赖接入，其许可证以该项目自带 LICENSE 为准。已迁移的工作流模板、类型与定义校验保留 SemaClaw MIT 归属，见 packages/workflow/LICENSE.semaclaw。

本机工作流

从 Projects 的目录详情点击“在这个目录运行工作流”，或使用左侧工作流入口。新建时提供可直接执行的文件夹速览示例。保存先做 DAG 校验，再填写输入、选择目录，预览固定快照后运行。

• 支持内联 YAML 或 Markdown frontmatter，保留 steps、dependsOn、inputs、guidance、observe。
• persona 当前映射到 Harness ID（companion/focus/research/workflow）；自定义成员通过 Atomix Agents/插件扩展；旧 persona 导入为独立迁移工作。
• 模板 {{input.name}}、{{steps.id.result}} 用于 Agent prompt/guidance；脚本通过 WF_INPUT_NAME、WF_STEP_ID_RESULT 读取数据，不做 shell 字符串插值。
• scriptFile 相对于选定项目目录，准备时读取并固化到运行快照。外部脚本中的依赖需显式写 dependsOn。
• 不采纳 YAML 中的 workspace 覆盖，运行目录由用户选择的项目决定；未选项目时使用 Compass 专属工作流目录。
• Agent 步骤独立会话，可从运行详情打开步骤对话处理权限。工作流不会塞进长期主线历史。
• 同一个目录的工作流不能并发运行；工作流运行时该目录的普通项目任务暂不接受新输入。
• 当前脚本执行器面向 macOS/Linux，使用 /bin/sh；这不是操作系统沙箱。执行前的预览展示实际脚本与目录。
• 运行期间改定义不会改变已准备的快照；服务重启会标记中断，不自动重放。

模型供应商与参考限额表来自 atomix-cli，保留 MIT 归属于 packages/models/LICENSE.atomix-cli；预设可修改，不代表服务商当前账户一定开放相应模型。

成果追溯：新建成果的每个修订记录手动编辑、来源消息、Agent/团队执行或工作流步骤。项目详情集中展示该目录的成果，Gallery 可返回来源对话。仅切换 HTML 交互权限不新增内容版本。

模型连接测试：编辑模型时点击“测试连接”，使用当前表单和同一配置保留的密钥调用 Atomix 连接检查；不保存、不切换默认模型。测试会向所选服务商发送一条简短请求。

灵感与目标：Ideas 可直接带到长期主线探索，也可转成保留来源的目标；重复操作不会重复创建目标。Goals 的“一起推进”会准备包含当前状态与步骤的对话草稿，不自动启动模型或改变目标状态。