# Suite — 人与 AI 的协作套件

## 一句话

同一个 AI 内核，多种协作界面，覆盖人与 AI 互动的全部场景。

## 三种界面

```
┌─────────────────────────────────────────────┐
│                  AI Core                     │
│  persona · inner_state · memory · tools      │
└──────┬──────────┬──────────┬────────────────┘
       │          │          │
   ┌───▼───┐ ┌───▼───┐ ┌───▼─────┐
   │ Chat  │ │ Gitea │ │  Life   │
   │       │ │  Bot  │ │  Loop   │
   └───────┘ └───────┘ └─────────┘
```

### Chat — 对话

实时聊天，最直接的人机沟通。

- 触发：用户发消息
- 输出：流式文字回复、文件、语音
- 前端：Telegram、飞书、未来更多
- 已有：Telegram 前端、Output trait 抽象（新前端只需实现 trait）

### Gitea Bot — 代码协作

AI 作为团队成员出现在代码流程中。

- 触发：webhook（push、PR、issue、comment）
- 输出：PR review comment、issue 回复、CI 状态通知
- 上下文：git diff、commit history、issue 内容
- 场景：
  - PR 提交后自动 review
  - issue 里 @bot 触发分析或执行
  - CI 失败后主动分析原因并评论
  - 代码变更后自动更新相关 issue 状态
- 已有：webhook server (axum)、GiteaClient API、GiteaOutput（实现 Output trait）、issue comment

### Life Loop — AI 的自主节奏

不依赖外部触发，AI 按自己的节奏存在和工作。既是内在生命（反思、感知、主动关心），也是后台执行引擎（定时任务、异步委派）。

- 触发：timer（定时/cron）、内部驱动（反思周期）、Chat/Gitea 中委派
- 输出：可能发消息、更新内心状态、执行结果推送到 Chat 或 Gitea
- 场景：
  - 早上主动问好，晚上道晚安
  - 感知用户状态（很久没聊、最近很累），决定是否主动关心
  - 定期整理记忆、反思最近的互动
  - 定时巡检服务健康状态、监控日志异常
  - Chat 里说"帮我查一下 X"，转为后台 timer 异步执行
  - 主动沉默也是一种行为
- 已有：life loop + reflect + inner_state + life_log + timer 系统

## 共享内核

三种界面共享同一个 AI Core：

| 组件 | 说明 |
|------|------|
| Persona | 定义 AI 是谁 |
| Inner State | AI 对当前情况的感知，LLM 自更新 |
| Memory | 跨会话的持久记忆（slot 0-99） |
| Context | 对话历史、summary、scratch |
| Tools | 统一的工具注册表，各界面按需可见 |
| Output | 输出抽象层（TelegramOutput、GiteaOutput、BufferOutput） |
| SubAgent | Claude Code (`claude -p`) 作为可调度的执行引擎 |

所有界面的交互最终都流经同一个 LLM 调用路径（`run_openai_with_tools`），共享 persona 和 inner_state——无论 AI 是在回复聊天、review 代码还是自言自语，它都是同一个"人"。

### SubAgent — Claude Code 作为执行引擎

Suite 的 AI Core 通过 OpenAI-compatible API 做对话和决策，但**复杂任务的执行交给 Claude Code**。这是当下 agent 生态的主流模式：一个轻量的调度层 + 重量级的 coding agent 做实际工作。

```
AI Core (决策层)
  │
  ├─ 简单任务：直接用 tools（bash、文件操作、API 调用）
  │
  └─ 复杂任务：spawn claude -p（subagent）
       ├─ 代码编写、重构、debug
       ├─ 多文件修改、跨项目操作
       ├─ 调研、分析、生成报告
       └─ 结果异步回传给 AI Core
```

**noc 是调度层和人格层，Claude Code 是执行层。** noc 不重复造 coding agent 的轮子，直接站在巨人肩膀上。

这意味着 suite 的 VPS 上需要安装 Claude Code CLI。noc 不需要自己实现 coding agent 的能力——它负责理解意图、管理上下文、协调界面，把"脏活"交给 Claude Code。

场景举例：
- Chat: "帮我写个脚本分析日志" → spawn claude -p，完成后把结果发回聊天
- Gitea Bot: PR 来了 → claude -p review 代码，结果写成 comment
- Life Loop: 定时任务要更新 dashboard → claude -p 生成代码，部署到 /data/www/
- Life Loop: 反思时发现某个 tool 有 bug → 自己 spawn claude -p 去修

## 界面之间的联动

界面不是孤立的，它们之间会互相触发：

```
Chat ──"帮我 review 那个 PR"──→ Gitea Bot
Gitea Bot ──"CI 挂了，要不要我看看"──→ Chat
Life Loop ──任务完成──→ Chat / Gitea Bot
Life Loop ──"Fam 今天还没动过代码"──→ Chat（主动关心）
```

## 部署架构

Suite 跑在一台专属 VPS / EC2 上——一台小机器（2C4G 足够），完整拥有整个环境：

```
┌─ VPS (suite 专属) ───────────────────────────┐
│                                               │
│  Caddy (ingress)                              │
│    ├─ git.example.com  → Gitea :3000          │
│    ├─ app1.example.com → /data/www/app1       │
│    └─ ...按需扩展                              │
│                                               │
│  Gitea (self-hosted, AI 专属)                  │
│    ├─ noc 持有 admin token，完全控制            │
│    ├─ webhook → noc http server               │
│    └─ noc 通过 REST API 读写一切               │
│                                               │
│  noc (Rust binary)                            │
│    ├─ telegram loop    (Chat)                 │
│    ├─ axum http server (Gitea Bot)            │
│    └─ life loop        (Life Loop)            │
│                                               │
│  SQLite (共享状态)                              │
│  LLM backend (外部，OpenAI-compatible)         │
│                                               │
└───────────────────────────────────────────────┘
```

### 为什么是裸机而不是 Docker

- Caddy 要绑 80/443，容器里搞端口映射反而多一层
- noc 需要 spawn 子进程、读写磁盘、跑工具脚本，容器限制多
- 一台机器就是给 suite 独占的，不需要隔离
- Life Loop 以后可能跑 CI、生成 web app，直接操作文件系统最自然

Docker image 保留用于本地开发和测试。

### Caddy 的角色

不只是反向代理——是 suite 的**统一入口**：

- 子域名路由：不同服务用不同子域名
- 静态站点托管：Life Loop 生成的 web app 放到 `/data/www/<name>/`，加一条路由即可对外
- 自动 HTTPS：Let's Encrypt 证书自动申请和续期
- 未来 noc 自己的 HTTP API 也从这里暴露

### Gitea 的角色

noc 的"专属地盘"——admin token 意味着 noc 可以：
- 创建/删除 repo 和 branch
- 读写任意 PR、issue、comment
- 管理 webhook、CI、用户
- 不用操心权限，想干嘛干嘛

### 部署方式

- 主线：`deploy/setup.sh` 在 VPS 上一键安装 Caddy + Gitea + noc，systemd 管理
- 开发：`make docker` 构建 all-in-one image，本地测试用

## 现状 → 目标

| 界面 | 现状 | 下一步 |
|------|------|--------|
| Chat | ✅ Telegram, streaming, tools, Output trait 已抽象 | 更多前端（飞书等）只需实现 Output |
| Gitea Bot | 🟡 webhook server + API client + issue comment | PR review、CI 失败分析 |
| Life Loop | 🟡 timer + reflect + inner_state + life_log | 更丰富的自主行为、异步任务委派 |
| Infra | ✅ Docker all-in-one (Caddy + Gitea + noc) | VPS setup 脚本 + systemd |