OneSelf

One self. One context. Every AI.

开源个人上下文管理：建立一份关于你的上下文，让每个 AI 都了解你，在隐私与效率之间取得平衡。

快速开始 · 架构 · Agent 入口 · 文档 · English

https://github.com/user-attachments/assets/98c48652-0ec5-476c-a6b6-bd5dde7151a5

💡 这是什么

不必每次都从自我介绍开始。

换了一个 AI，你还是你。你的经历、知识、作品和偏好，不应该跟着某个平台走。

OneSelf 把这些资料放回你自己手里。

开源、自托管，一份个人资料，多种 AI 共用。每一次读取、修改和公开，都由你授权。

你的资料，你做主。AI 来了解你，而不是你反复适应 AI。

✨ 特性

Agent-first：Agent 负责读取、整理和维护；你划定边界——给谁、给多少、何时收回。

🗂️ 管理

• 一份上下文，汇集所有资料：经历、笔记、证件摘要写成页面，照片和 PDF 作为原件上传并挂到页面上；事实、时间线、标签和页面链接可检索。
• 改动可追溯、可回退：增量编辑带版本校验；每页保留最近 50 个版本，删除后 30 天内可恢复。

🔐 隐私

• 默认私有，公开由你决定：按目录分读、写、改可见性；没有权限时，私有页和不存在的页看起来一样。公开主页改版需你批准才上线。
• 每次授权你批准，随时可收回：API Key 或 OAuth 设备码都要在批准页确认；密钥与授权可单独作废。Agent 不能给自己发密钥，也不能替你批准。
• 数据留在你的机器上：Node.js + PostgreSQL + RustFS，Docker Compose 部署；Agent 只走接口。

⚡ 效率

• 自助接入：读 /.well-known/pcp 和 Skill oneself 即可；HTTP（OpenAPI）与 MCP 同一张操作表。
• AI 帮你维护：Agent 可整理原件成页面、记住或忘掉事实、补时间线与标签；下次任何 AI 读到的都是最新的你。

🚀 快速开始

🐳 方式一：CLI 安装

需要 Docker 与 Docker Compose v2。

macOS / Linux

curl -fsSL https://github.com/ptonlix/OneSelf/releases/latest/download/oneself.sh | sh

Windows（PowerShell）

powershell -c "irm https://github.com/ptonlix/OneSelf/releases/latest/download/oneself.ps1 | iex"

安装器会按提示选对外源和入口，并拉起服务。装好后：

1. 打开打印的 PUBLIC_ORIGIN（首页）
2. 把这条命令交给正在对话的 Agent（<agent> 换成对应 Agent 名）：

npx skills add https://你的站点 -a <agent> -s oneself -y

1. Agent 没有凭据时会申请设备码。到 /admin 登录后，在 /admin/device 批准。
2. API Key 只给脚本或长期密钥，不是第一次对话的接入方式。

安装选项

• 目录：默认 $HOME/.local/share/oneself（Windows 为 %LOCALAPPDATA%\oneself），不进源码树
• 换目录：ONESELF_DIR=/path 或 sh -s -- --dir /path（Compose 项目名仍是 oneself，共用同一组卷）
• 非交互：ONESELF_YES=1
• 入口：默认本机/局域网，也可选 Cloudflare / Caddy / Tailscale，见 部署
• 变量：见 配置

运维

• 命令：bin/oneself update | doctor | backup | restore
• backup / restore 在安装目录用 compose.yaml 完成，不需要检出仓库或 scripts/transfer-cli.ts
• update 有新版本就升级并重启，没有就重新拉取当前镜像。doctor 只检查
• update 可改 .oneself-release 和 ONESELF_IMAGE，但更换 CLI 二进制仍需重跑 Release 安装命令。
• 口令保留。旧 Release 的安装命令不会降级；确要换旧版设 ONESELF_REF=v1.2.3

实现

• 安装与运维只有一套实现：CLI 二进制 apps/cli
• oneself.sh / oneself.ps1 是薄启动脚本（deploy/oneself-bootstrap.sh、deploy/oneself-bootstrap.ps1），只下载、校验本平台二进制后转交
• Alpine/musl 用 oneself-linux-*-musl

💻 方式二：本地开发

需要 Node.js >=24、pnpm 12.9.1（Corepack）、Docker。

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
docker compose -f compose.dev.yaml up -d

在仓库根新建 .env（这些口令只给本机；本地不要设 PUBLIC_ORIGIN，应用用 http://127.0.0.1:3000）：

DATABASE_URL=postgres://oneself:[email protected]:5432/oneself
OBJECT_STORAGE_ENDPOINT=http://127.0.0.1:9000
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_BUCKET=oneself
OBJECT_STORAGE_ACCESS_KEY=oneself
OBJECT_STORAGE_SECRET_KEY=oneselfsecret
OWNER_LOGIN=owner
OWNER_PASSWORD=<自己设一个初始口令>

pnpm dev

打开 http://127.0.0.1:3000 与 http://127.0.0.1:3000/admin。compose.dev.yaml 只起 PostgreSQL 和 RustFS（绑定 127.0.0.1）。更多命令见 开发。

🔧 配置

完整变量和注释见 .env.example。.env 已被 Git 忽略，不要提交真实口令。

🧱 架构

• 一个进程：PCP、MCP、OAuth、管理端和已发布站点都由同一个 Hono 应用提供。
• 规则不在路由里：HTTP / MCP 只做认证与返回；用例在 apps/server/src/app，业务规则在 packages/domain。
• 原文与投影分离：页面原文与原件以对象存储为准；PostgreSQL 中的正文、标签、链接、事实和时间线是投影。

Mermaid 版系统总览、代码边界、数据表和关键流程见 docs/ARCHITECTURE.md。

🤖 Agent 入口

接入二选一：API Key（Authorization: ApiKey <key> 或 X-Api-Key），或 OAuth 2.1 设备码访问令牌（Authorization: Bearer <token>）。都要所属人批准。路径以 packages/operations/src/registry.ts 为准。

🧩 上下文怎么组织

一份上下文由页面和原件组成，按目录（source）分组，例如 profile、career、health：

• 页面：由 (source, slug) 标识；type、title、visibility 等写在 frontmatter 里。需要有效期或置信度的陈述放进 ## Facts，经历放进 ## Timeline。
• 原件：JPEG、PNG、WebP、GIF、PDF（单个最大 20 MiB）用 file_upload 上传，在页面的 files 里引用；挂接页公开时原件才可匿名访问。

---
type: profile
title: 工程师
name: 张三
visibility: public
tags: [public-profile]
files: []
---

# 张三

做个人工具和开发者产品。

## Facts

- id: fact_01
  entity: 张三
  statement: 现居上海
  confidence: 0.9
  valid_until: 2027-01-01

## Timeline

- 2024-06-01 | 加入某公司 | 做后端

完整规则见 skills/oneself/references/context.md。

📁 项目结构

OneSelf/
├── apps/
│   ├── server/            # 唯一的 Node 进程：pcp/、mcp/、oauth/、owner/、site-files/
│   └── admin/             # 管理端（Vite + React）
├── packages/
│   ├── domain/            # 纯业务规则
│   ├── operations/        # 操作注册表
│   ├── ports/ / adapters/ # 对象存储、时钟、解析的接口与实现
│   ├── db/                # Drizzle 与 SQL 迁移
│   ├── public-client/     # 匿名公开 PCP 客户端
│   └── public-page/       # 内置公开页源码
├── skills/oneself/        # 产品 Skill
├── tests/                 # 冒烟与 Skill 验收
├── deploy/                # 安装脚本与 Caddyfile
├── docs/                  # PRD 与架构
├── compose.yaml           # 生产：应用 + PostgreSQL + RustFS + 入口
├── compose.dev.yaml       # 本地依赖：PostgreSQL + RustFS
└── Dockerfile

🧪 开发

pnpm check            # Prettier、ESLint、tsc、Vitest、dependency-cruiser、Knip
pnpm test             # 单元与进程内接口测试（不需要 Compose）
pnpm test:smoke       # 闭环冒烟：复用已启动的 compose.dev.yaml
pnpm boundaries       # 包依赖方向
pnpm db:migrate       # 只迁移，不启动应用
pnpm data:export --out oneself-export --stopped
pnpm data:import --from oneself-export.tar.gz --stopped
pnpm dev              # 构建管理端和内置公开页，再启动应用

导出/导入与冒烟的细节（--via compose、独立 smoke 库与桶等）见脚本帮助或 docs/ARCHITECTURE.md。pnpm check 是合并前门禁。行为以 docs/PRD.md 为准。

🚢 部署

compose.yaml 含应用、PostgreSQL 18 和 RustFS，三者都不直接映射宿主机端口。访问入口由 .env 的 COMPOSE_PROFILES 选择，四种互斥（安装时四选一），换入口不换应用镜像：

• PUBLIC_ORIGIN 须与所选入口的对外地址一致。
• 走 Cloudflare 时不要缓存 /pcp、/oauth、/.well-known、/admin、/skills、/media、/_preview。
• 不用安装器：cp .env.example .env 填好变量后 docker compose pull && docker compose up -d。
• Agent 接入：npx skills add https://站点 -a <agent> -s oneself -y。

📚 文档

• 产品需求（PRD）
• 技术架构
• Skill：oneself
• 运行中的实例：/.well-known/pcp、/openapi.json、/skills/oneself/SKILL.md
• 安装 Skill：npx skills add https://站点 -a <agent> -s oneself -y

🤝 贡献

欢迎 Issue 和 Pull Request。请先读 CONTRIBUTING.md。安全问题走 SECURITY.md，不要把密钥、口令或导出包贴进 Issue。一起协作的约定见 CODE_OF_CONDUCT.md。

1. 从当前 main 拉分支。
2. 改动与 docs/PRD.md 范围一致；操作名、权限或错误码有变时，先改文档和 packages/operations。
3. 提交前运行 pnpm check。
4. 发起 PR，说明行为变化和验证方式。