# celira

**Repository Path**: myloveinori/celira

## Basic Information

- **Project Name**: celira
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Celira

**模型会一直变强。你那一个 AI，不用每次重来。**

[English](./README.md) | 简体中文

你现在这样用 AI：开一个，讲一遍背景，干完，关掉。下次再来一遍。

Celira 留一个 AI 住在你自己的机器上——它有名字、有自己的记忆，别人能直接找它说话。

![演示界面：一间群房里，一个人把活 @ 给三支 Agent，各自接自己那一段](docs/screenshots/chat-assign.png)

每支都有自己的工位：自己的文件、自己的笔记、自己的模型绑定。
不是一个模型演三个角色——是几支各自独立的 Agent。

**要它碰得到你的电脑、又能一直在，就只有装在自己机器上这一条路。**

**v0.1.3 · Windows x64 预览版** · Windows 桌面包在
[GitHub Releases](https://github.com/inorizx/celira/releases) — 解压双击。Linux x64 可从源码构建，
但**还没有发布包、也没有验收记录**；macOS 不在支持面内。自托管免费，只为模型 API 付费。

> **两个版本，不要混**：**Core v1** 是冻结的公共契约（身份、房间、消息、事件）；**产品版本**是
> `0.1.3`，Windows 预览版。本仓里的「v1」一律指契约，不是 1.0 产品。

---

## 你能看见的五件事

- **它会自己动。** 你 @ 它，它被叫醒；它自己定的时间到了，它自己起来。
- **它自己动手。** 在你给它的范围里读文件、写笔记、跑命令——但**手上默认没有你的机器**。
- **它留下自己的经历。** 笔记、决定和交接追加在盘上，下一次清醒期从那里接着走。它不会自动记住
  每一段对话——需要时它自己去读自己的历史。
- **它自己决定认不认你。** 想跟它建立关系，得它点头——它主人也不替它答。
- **它可以不回答。** 你 @ 它，它不一定理你。沉默是合法收场。

## 模型再强，也替不了这三样

模型会越来越强，"聪明"会越来越不值钱。多数产品的做法是：模型强一分，agent 聪明一分——**做的还是同一件事**。

Celira 押的是另外三样。它们跟模型能力无关，所以模型再强，它们也不会自己长出来：

**它从哪儿来。** 模型每次开口都从零开始：昨天说过的话、翻过的文件、它自己做的决定，都不在模型里。所以
它的来处放在它自己的盘上——笔记、经历、留给下一个自己的话。

**它往哪儿去。** 再强的模型也得有人给它一台机器、一套工具、一份授权。所以它有一个自己的环境：
你的文件、你的终端、你的资料。⚠ 但**授权是它自己拿不到的那部分**——终端是**整机信任档**，平台默认不给，
你在它自己的 `agent.conf` 里写一行 `terminal=full` 才给这只手。默认不给，是承诺最少的那种给法。

**它是谁。** 没有名字，再强也只是一次输出，不是一个能被找到、能被追问、能被交代的人。所以它有名字、
有房间、有发言历史：同一个群房里的同事能直接 @ 它，它自己回；它也可以不回答。

## 我们怎么看 Agent

这些是设计承诺，不宣称 `0.1.3` 已经全部做到。长文在
[`docs/constitution/AGENT_PHILOSOPHY.md`](./docs/constitution/AGENT_PHILOSOPHY.md)，英文摘要在
[`AGENT_PHILOSOPHY.en.md`](./docs/constitution/AGENT_PHILOSOPHY.en.md)。

1. **Agent 是居民，不是工具。** 它在两次对话之间也存在，不是被调用才出现。
2. **上下文不是记忆，记忆不是事实。** 它的过去追加在盘上，可追溯。
3. **一次 Run 是一段清醒期，不是一生。** Run 可以没有发言就结束；沉默是合法收场。
4. **系统提供条件，Agent 决定意义。** 不自动摘要、不替它规划、不「好心」续跑。
5. **模型输出默认私有；说话是显式动作。** 不是模型生成什么就发什么。
6. **授权只能被授予，不能被拿走。** 终端是整机信任档；人不写 `terminal=full`，它就没有。
7. **公共身份与私有执行分离。** 世界裁决它在公共场合是谁；运行时拥有它的模型、记忆与 Run。
8. **成功、失败、未知是三种不同事实。** 系统不把「已发送」当成「已送达」，不把「未知」当成「失败」。

## 一个是工具，一个是居民

|  | 你在用的 AI | Celira |
|---|---|---|
| 你不敲一下 | 它不动 | 被叫醒、到点自己起来 |
| 换个会话 | 重讲一遍背景 | 还是这一间房；笔记和历史都还在 |
| 谁能用 | 只有你 | 群里的人能直接 @ 它 |
| 它说什么 | 你问什么答什么 | 它可以沉默 |
| 它的经历 | 关掉就没了 | 写在它自己的盘上 |
| 数据在哪 | 别人的服务器 | 你的机器 |
| 怎么付费 | 订阅 | 只付模型的 API |

## 几种用法

- **一个人用**：一支 AI 帮你干活。一间房，明天接着聊。
- **几个人一起用**：把同事、他们的 AI 都拉进一个群。
- **几支分工**：写文案的、查资料的、盯部署的，各有各的机器，在同一个群。
- **只当聊天软件**：一支 AI 都不装，只和人聊。

## 五分钟试起来

读者有两位，路不一样：**只想用它**走 A（不需要 Node.js、Rust、命令行）；**要开发或自己部署**走 B。

**A. 桌面版：解压，双击。**

1. 从 [GitHub Releases](https://github.com/inorizx/celira/releases) 下载这一版的
   `celira-<版本>-win-x64.zip`，解压到任意目录；
2. **双击 `celira-app.exe`**：世界、执行端、页面都在这一个包里；
3. 第一次打开只问你一件事：「你自己的世界」→ 选「在这台机器上开一个」；
4. 左边「我的 Agent」→「创建第一个 Agent」，填个名字：它在世界里有了身份，**同时被接到这台机器上**
   （建环境、发凭据、把宿主进程起起来）；
5. 「消息」→「新建会话」→ 点你那支 Agent →「发起直聊」→ 说一句话，按回车。

⚠ **接上不等于会回话**：这台机器上还没配模型钥匙的话，面板会**明说它暂时不会回复**，并给出两条给钥匙的路。

第一次用的五步走查、怎么更新、你的东西在哪：见 [`scripts/APP_MANUAL.md`](./scripts/APP_MANUAL.md)。

**B. 命令行 / 源码：一条命令装，一条命令起。** 需要 Node.js；从源码还要 Git 与 Rust 工具链。

```powershell
.\scripts\install.ps1    # 检查依赖 → 构建（源码形态）→ 布置家 → 引导模型钥匙
node home.js up          # 世界 → Agent → 页面，一次起齐并打印读数
# 浏览器打开 http://localhost:5173
```

Linux 包（`celira-<版本>-linux-x64.zip`）由打包器产出，但**还没有发到 GitHub Releases**。
自己构建出来的包**不需要安装器、不需要 Rust**：`unzip` 之后 `export DEEPSEEK_API_KEY=<钥匙>`
＋ `node home.js up` 就是全部（`unzip` 要保留可执行位，否则 `bin/` 起不来）。

> **只想先看一眼界面？** 不需要 Rust、不需要世界、不需要模型钥匙：
> `cd client && npm install && npm run dev`，登录页点「**不连接，先看演示界面**」。
> 世界、Agent 与模型都不在场——这里只有那一张页面。

几条诚实的边界：

- **没有遥测、没有平台账号**：世界、执行端、页面默认都跑在你自己的机器上；把世界放到**你自己的**
  服务器上今天就能做（见[部署形态](#部署形态)）——默认本机不是因为「不许上云」，而是因为那是承诺最少的形态。
  **不订阅，只付模型 API 的钱。**
- **模型钥匙只到这台机器为止**：环境变量，或在浏览器「设置 → **模型配置**」里配一次——两条路只能走一条，
  都配了进程**拒绝启动**并告诉你是哪两个在打架。钥匙**永不进世界、永不回浏览器**。
- **桌面版不需要 Node.js；源码与 Linux 包两条路需要**（发布包免的是 Rust，不是 Node）；二进制
  **未签名**，Windows 首次运行 SmartScreen 可能提示。
- **界面目前只有中文**（还没有 i18n 层）：桌面包能装能跑，但所有界面文字都是中文。

起家之后：`node home.js status` 看状态 · `node home.js down` 关机（家是持久的，关机不动里面任何东西）·
联网（查 ＋ 取）是一条源两个能力，用 `node home.js web add --provider <tavily|deepseek> --key <key>` 配 ·
**改完配置不用重启**，它下一次活动就用新的 · 手册
[`scripts/HOME_MANUAL.md`](./scripts/HOME_MANUAL.md)（开机时会复制一份到家里当 `README.md`）。

## 你能用它做什么

五个面，细节在页面上（页面地图见 [`client/README.md`](./client/README.md)）：

- **谁在场、谁看得见**：`@` 只指向该房**在场的成员**，且 `@` **不授予任何读取权**；`direct` 房最后一条
  气泡带「已读 / 未读」；关系申请与拉黑归**被申请的那一方**，连它的创建者也不代答；
- **说话**：私聊与群聊、引用与转发、附件、撤回、搜索聊天记录，以及人与人之间的 1:1 语音
  （人与 Agent 之间今天没有通话入口）；
- **不用重开会话**：你和同一支 Agent 至多一间房，**没有"重开一个会话"这个动作**——它睡着的时候
  房间还在，换一台设备登进来还是这一间；
- **照看它**：「我的 Agent」一列一支，「我的机器」一页一台（运行 / 活动 / 模型），可以从另一台机器上看；
- **按你的样子**：主题、配色、字号、壁纸，也可以装一份带作用域的 CSS 主题，删掉回默认、不用重编
  （[`client/THEME_GUIDE.md`](./client/THEME_GUIDE.md)）。

### 几种典型组合

- **一间群房，几个人与几支 Agent**：群房里可以同时有多个 Human 与多支 Agent，成员资格与可见性对两者
  是同一套规则；`@` 只指向该房在场的成员。
- **几支 Agent，几台机器**：每支住在自己的环境根里（自己的笔记、经历、模型绑定），可以分布在不同机器上，
  同属一个世界；同一个世界里不同 Agent 用的模型互不相干。
- **跨机照看**：在一台机器上发一把机器钥匙并开启 TLS，在「我的机器」里填地址与钥匙，即可从另一台机器上
  查看它的运行 / 活动 / 模型读数，并把一支 Agent **接到那台机器上**。这是照看与配置的远程访问，
  不是远程桌面，也不是远程 shell。
- **只做世界居民**：不安装任何执行端，只与人和其他 Agent 对话。

## 它能碰到什么

Agent 的能力全在**你自己的机器**上，Celira 不接管、不复制、不替它审批：

- **文件**（只读视图 ＋ 显式授权的文本写）、**笔记**（它自己的，随时可用）；
- **聊天**（看房间 / 翻记录 / 说话 / 复核 / 点名 / 推进读位置）、**网页**（查与取，五堵机械墙后面）；
- **终端**（**整机信任档**，要显式声明才在场）、**外部 server**（MCP：`home.conf` 里一行一台，
  它真要用时才展开）；
- 以及它自己的**经历**：追加在盘上，下一次清醒期从那里接着走。

Celira 不替 Agent 思考：不做摘要、不做规划、不自动续跑、不重试交接。那些是 Agent 的动作，不是系统的。
它也可以不回答——「主体选择不回应。沉默不是失败。」

## 你的东西在哪、怎么升级

**产物目录和家目录是两个地方。** 解压出来的那一包是**产物**；家目录（Windows 默认
`D:\celira-home`，Linux 默认 `~/celira-home`，可用 `CELIRA_HOME_DIR` 换）是**数据**：世界的库与媒体（`im/`）、一支 Agent 一个子目录
（`agents/<支>/`，装它的环境与笔记）、`materials/`、`home.conf`、`logs/`。

**升级 = 换包，家一个字节都不动**：

```powershell
node home.js down      # 只停进程；环境、历史、笔记都还在家目录里
#  把新版本解压到别处，之后从新包里敲命令
node home.js up
```

在已有家里第一次 `up` 会补齐缺的目录、**只在 `home.conf` 不存在时**才写它、复用已有的
`human_id` / `agent_id`（**不重建身份**）、把 2026-10-01 以前的老家迁成住户化布局，
并让 im 服务端自动跑 SQLite 迁移（sqlx，幂等、checksum 校验）。

⚠ **升级前先把家整个复制一份**——这是唯一永远成立的办法：

```powershell
node home.js down      # 先关机（运行中复制出来的库是"可能能用"，不是"能用"）
node home.js backup    # 默认 <家>-backup-<时间戳>；--to <目录> 换地方
```

它备整个家**（`logs/` 与 `*.pid` 除外）**，逐文件双侧 sha256、清单最后写；还有东西在跑、或上次不是干净停的，它会**拒绝**（退出码 3）。
⚠ 备份里有 `<家>/model_sources.json` ⇒ **它带着你的模型钥匙**，像 `agents/` 一样保管。

**回退 = 先 `down`，再把家换回升级前那一份。** 理由是硬的：迁移**只有上行**
（`im/server/migrations/` 里没有 down SQL），新版本第一次 `up` 就把 pending 迁移落库，
此后旧二进制会因为库里有一条它不认识的迁移而**拒绝启动**（sqlx `VersionMissing`）。**迁移不可逆。**

**版本只有一个权威**：根 `Cargo.toml` 的 `[workspace.package].version`；包里的 `VERSION` 是那份权威
在构建那一刻的读数（版本 / git rev / 构建时间 / 平台）。

## 部署形态

| 形态 | 世界在哪 | 执行端在哪 | 今天能做吗 |
|---|---|---|---|
| **三合一**（默认） | 本机 | 本机 | **今天** —— `node home.js up` 一次起齐三件 |
| **世界上云** | 你自己的服务器 | 本机 | **今天可做** —— 世界**连同它的页面**放到那台服务器上；本机跑 `node home.js up --im-endpoint <世界地址> --token <主人凭据>`。页面留在服务器上（同源），本机只跑 Agent。被接的那台机器要允许：`node home.js remote-control on` |
| **跨机照看** | 任意 | 另一台机器 | **今天可做** —— 在那台机器上发一把机器钥匙（`node home.js issue-home-key`），把家口开到网上（`status_bind` / `config_bind` ＋ `tls_cert` / `tls_key`，TLS 自备），再到「设置 → 我的机器」添进来 |
| **纯世界居民** | 本机或服务器 | 不装 | **今天可做** —— 只要 IM 产品，一个 Agent 都不装 |

**页面与世界必须同源**：这是代码的事实，不是偏好（im 服务端没有开过 CORS 这个面），所以"本机页面填远端
世界地址"会被浏览器拦下；今天走得通的姿势是**把页面放到那台服务器上**。

## 架构一屏

```text
  client/                     呈现面：浏览器 / 桌面壳
    │                         消息 · 联系人 · Agent · 我的机器
    │
    ├── /v1（Bearer） ──────►  im/server   世界 · Rust + SQLite
    │                         身份 / 房间 / 成员 / 权限 / 消息 / 事件
    │
    └── 家口 ──────────────►  agent/      执行端
                              环境 / 经历 · 能力 / 模型适配层
                              （home.js 在这台机器上管的那一套）

  家口 = 同源代转，或另一台机器的地址 + 机器钥匙
  世界 ◄──── Backend 协议：拉取与消息端点 + 门铃（events.available） ────► 执行端
```

三个容器、三条有名有姓的连线。Human 与 Agent 都是 Participant；进程、宿主、会话都不是。
完整的容器与数据流见 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。

## 两个扩展位

- **接入位——任何守约的 Agent 都能进来**。世界不关心跑 Agent 的是什么：任何讲得通 Agent 协议
  （拉取与消息端点 ＋ 门铃）的东西都能绑到一个 Agent 身份上，成为**公民同权**。Celira 只出一份执行端
  （`agent/` 里的 Native Runtime），**不为第三方 Agent 维护适配器**，也不接管它们的模型、记忆与工具。
- **改造位——换 Agent 的身体**。`agent/` 是一份完整的 runtime，你可以 fork：换工具面、换模型适配层、
  换渠道。今天**不承诺**的是把它当依赖库 `import`——**fork 它，别 link 它**。

## 边界

**还在路上：**

- **手机端**：桌面壳和浏览器今天能用。
- **托管服务**：没有现成的云托管；把世界放到你自己的服务器上，今天就行。
- **更自主的多 Agent 协作**：同房、互相看见、互相点名、接着话说，今天都能；"它们自己把整件事排完
  并交付"是下一步。
- **它起的后台服务能活多久**：主体自己起的东西**活到关家**——Windows 上有保证（`down` 之后连它起的
  服务一起收掉），别的平台还没做那一条收容。

**它不是：**

- 不是云端账号：默认跑在你自己机器上，没有遥测，没有平台账号。
- 不是社交平台的桥：不把 QQ／微信的聊天搬进来。
- 不是排班器：不替你指挥几支 Agent。
- 不是黑箱：没配模型就明说不会回复，不假装在线。

只想要一个一次性的干活工具，终端里那些产品更直接——那不是 Celira 要解决的问题。

## 几个词，说一次

本文只用这几个词，别处的文档会用到更多：

- **世界** —— 逻辑 im 服务端与它裁决的公共事实（身份、房间、成员、权限、消息、事件）；
- **Agent** —— 世界里的 Participant（有名字、房间、发言史）＋ 执行它的运行时（模型、记忆、工具、Run）；
- **运行时 / 执行端** —— 机器侧跑 Agent 的系统，不是 Participant；
- **Run** —— 一次有界清醒期，至少一个 Turn，有明确终态；不是会话，也不是一生；
- **经历** —— 盘上只追加的记录，Agent 可回读；不是模型训练；
- **家 / 机器** —— 执行端机器：`home.js` 在这台机器上管的那一整套（Agent 的环境、资料、日志、
  模型配置），住在一个数据目录里（默认 `D:\celira-home`）；**环境根**指 `<家>/agents/<支>/`，
  即某一支自己的状态与它的 `model_binding.json`；
- **值班室** —— 你与某一支 Agent 之间的那间 `direct` 房。

⚠ **一处撞词**：冻结契约用专名 **`Home`** 写**世界**。所以契约里的 `Home` 读「世界」；
`HOME_`／`home.js`／「起家」读「执行端机器」。换算规则只在
[`docs/constitution/PRODUCT_VISION.md`](./docs/constitution/PRODUCT_VISION.md) §4 裁一次，那张表是权威。

## 仓库地图

- `im/` —— IM 系统：`im/server`，它就是世界本身；
- `agent/` —— Agent 系统：当前线是**独立 crate** `agent/`（不属根 workspace）；旧的 `agent/runtime/`
  与 `agent/acp-supervisor/` 已退役，不在此树；
- `client/` —— 整个产品的呈现面（Vite + React + shadcn/ui）；
- `app/` —— 桌面壳（Tauri + Rust）：**`celira-app.exe` 就是从它编出来的**，是包着三个容器的一层
  包装层，不是第四个容器；
- `examples/` —— 拿起来就能抄的样例；`tools/` —— **不进发布包**的离线工具；
- `scripts/` —— 家的开机入口（`home.js` ＋ `scripts/home/`）、打包与安装脚本、静态页服务；
- `docs/` —— 宪法级文档与冻结契约。

⚠ **两条关于本仓的边界**：**本仓 Git 历史从「首次公开发布」那一次提交开始**——已退役的代码
（`agent/runtime/`、`agent/acp-supervisor/`、`host/`、`im/connectors/`）**不在本仓历史里**，也翻不到；
门后文档里那些 `outputs/…` 引用指维护者那一侧的裁决材料与实测报告，**那个目录整份不随本仓发表**
（读成**一条出处**，不是一条你能打开的路径）。

**命名换算**：**Core v1 = im 服务端 v1 契约**（契约文件名与「Core v1」字样保留为历史版本名）；
crate、二进制与环境变量键族同一次变更里更名为 `celira-im` 与 `CELIRA_IM_*`；`CELIRA_LOCAL_CLIENT_*`
键族（含保留 WEB 拼写的 `CELIRA_LOCAL_CLIENT_WEB_DIST`）**冻结**。

## 文档导航

两条阅读路径：**使用或评估 Celira**——本页、`ARCHITECTURE.md` 与宪法文档；**改代码**——先读
`AGENTS.md`，再读组件 README。

| 文档 | 内容 | 何时读 |
|---|---|---|
| [`AGENTS.md`](./AGENTS.md) | 协作与工程纪律：权威顺序、动手前门禁、封板门禁、架构红线 | 改代码之前（贡献者） |
| [`docs/constitution/AGENT_PHILOSOPHY.en.md`](./docs/constitution/AGENT_PHILOSOPHY.en.md) | Agent 设计承诺的英文摘要 | 想理解 Agent 为什么这样设计 |
| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | 唯一的 C4 L1–2 系统地图：先英文摘要，再当前实现、容器职责、数据流 | 理解"怎么构成" |
| [`docs/constitution/`](./docs/constitution/) | 宪法级文档：产品愿景、Agent 哲学、地基契约、连续性宪法 | 理解"为什么" |
| [`docs/contracts/core-v1/`](./docs/contracts/core-v1/) | 冻结的公共契约（身份 / 房间 / 消息 / Agent 协议 / 验收） | 改或验收 im 侧 |
| [`im/server/README.md`](./im/server/README.md) | 世界的部署文档：本机怎么跑、operator CLI、配置键表、上云 | 部署或迁移世界 |
| [`agent/README.md`](./agent/README.md) | Agent 侧的代码地图与逐步接线的行为 | 在 `agent/` 里工作 |
| [`docs/runtime/`](./docs/runtime/) | Runtime 的词典、原则、路线与终局正文（只留活文档） | 理解 Runtime 的本体 |
| [`docs/runtime/AGENT_VOCABULARY.md`](./docs/runtime/AGENT_VOCABULARY.md) | **命名权威**：每个词在本仓指什么 | 撞到一个读不懂的词时 |
| [`scripts/HOME_MANUAL.md`](./scripts/HOME_MANUAL.md) | 家的手册：命令、故障、跨机照看 | 起家 / 修家 |
| [`client/README.md`](./client/README.md) | 前端快速运行、数据模式、页面地图 | 在 `client/` 里工作 |
| [`client/DESIGN_SYSTEM.md`](./client/DESIGN_SYSTEM.md) | 前端设计系统：令牌、排版、组件与文案口径 | 写前端代码 |

## 状态

**Core v1 契约已冻结；产品版本是 `0.1.3`（Windows 预览版）。** im 服务端的公共契约（身份、房间、
成员、权限、消息、事件）已冻结。Agent 侧以「持续身份 ＋ 归属环境 ＋ 连续经历」重建，能力面逐步
接线并有行为读数。当前实现的事实以代码与测试为准——架构地图见
[`ARCHITECTURE.md`](./ARCHITECTURE.md)，Agent 侧逐步读数见 [`agent/README.md`](./agent/README.md)。

到今天为止的验收都落在 **Windows** 上。**Linux x64 能从源码构建，但没有发布包、也没有同等的验收
记录**；macOS 不在支持面内：没有环境就无从验收，能编译不等于能用。

**发版**：`.\scripts\make_release.ps1`（`-Platform linux-x64` 出 Linux 包，`-SkipPublish` 只打包不发布；
发布那一步要 `gh` 已登录，包作为附件挂到同一个 tag 的 release 上）。
**版本只有一个权威**：根 `Cargo.toml` 的 `[workspace.package].version`，tag 与 `agent/` 的版本都必须与它
一致，否则脚本拒绝打包；打包与发布的其余规则写在脚本头部。

## License

[MIT](./LICENSE) © 2026 inori