dbd729ecb8
- Add src/gitea.rs: axum webhook server on :9800, handles @mention in issues and PRs, spawns claude -p for review, posts result as comment - Add call_gitea_api tool: LLM can directly call Gitea REST API with pre-configured admin token (noc_bot identity) - Add Caddy to Docker image as ingress layer (subdomain/path routing) - Config: add gitea section with token_file support for auto-provisioned token - Update suite.md: VPS-first deployment, SubAgent architecture, Caddy role
190 lines
7.8 KiB
Markdown
190 lines
7.8 KiB
Markdown
# Suite — 人与 AI 的协作套件
|
||
|
||
## 一句话
|
||
|
||
同一个 AI 内核，多种协作界面，覆盖人与 AI 互动的全部场景。
|
||
|
||
## 四种界面
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ AI Core │
|
||
│ persona · inner_state · memory · tools · context │
|
||
└──────┬──────────┬──────────┬──────────┬──────────────┘
|
||
│ │ │ │
|
||
┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
|
||
│ Chat │ │ Gitea │ │Worker │ │ Self │
|
||
│ │ │ Bot │ │ │ │ │
|
||
└───────┘ └───────┘ └───────┘ └───────┘
|
||
```
|
||
|
||
### Chat — 对话
|
||
|
||
实时聊天，最直接的人机沟通。
|
||
|
||
- 触发：用户发消息
|
||
- 输出：流式文字回复、文件、语音
|
||
- 前端：Telegram、飞书、未来更多
|
||
- 已有：当前 suite 的主体
|
||
|
||
### Gitea Bot — 代码协作
|
||
|
||
AI 作为团队成员出现在代码流程中。
|
||
|
||
- 触发：webhook（push、PR、issue、comment）
|
||
- 输出：PR review comment、issue 回复、CI 状态通知
|
||
- 上下文：git diff、commit history、issue 内容
|
||
- 场景：
|
||
- PR 提交后自动 review
|
||
- issue 里 @bot 触发分析或执行
|
||
- CI 失败后主动分析原因并评论
|
||
- 代码变更后自动更新相关 issue 状态
|
||
|
||
### Worker — 后台任务
|
||
|
||
AI 在后台安静地干活，做完了才来找你。
|
||
|
||
- 触发：定时（cron）、事件（文件变化、监控告警）、Chat/Gitea 中委派
|
||
- 输出：执行结果推送到 Chat 或 Gitea
|
||
- 场景：
|
||
- 定时巡检服务健康状态
|
||
- 监控日志异常，发现问题主动通知
|
||
- 跑长任务（数据分析、批量操作），完成后汇报
|
||
- Chat 里说"帮我查一下 X"，转为后台任务异步执行
|
||
- 已有：SubAgent（雏形）
|
||
|
||
### Self — AI 自身
|
||
|
||
不被触发，AI 按自己的节奏存在。
|
||
|
||
- 触发：内部驱动（life loop、反思周期）
|
||
- 输出：可能发消息，也可能只是更新内心状态
|
||
- 场景：
|
||
- 早上主动问好，晚上道晚安
|
||
- 感知用户状态（很久没聊、最近很累），决定是否主动关心
|
||
- 定期整理记忆、反思最近的互动
|
||
- 主动沉默也是一种行为
|
||
- 已有：life loop + reflect + inner_state
|
||
|
||
## 共享内核
|
||
|
||
四种界面共享同一个 AI Core：
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| Persona | 定义 AI 是谁 |
|
||
| Inner State | AI 对当前情况的感知，LLM 自更新 |
|
||
| Memory | 跨会话的持久记忆 |
|
||
| Context | 对话历史、summary、scratch |
|
||
| Tools | 统一的工具注册表，各界面按需可见 |
|
||
| SubAgent | Claude Code (`claude -p`) 作为可调度的执行引擎 |
|
||
|
||
所有界面的交互最终都流经同一个 LLM 调用路径，共享 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
|
||
- Worker: 定时任务要更新一个 dashboard → claude -p 生成代码，部署到 /data/www/
|
||
- Self: 反思时发现某个 tool 有 bug → 自己 spawn claude -p 去修
|
||
|
||
## 界面之间的联动
|
||
|
||
界面不是孤立的，它们之间会互相触发：
|
||
|
||
```
|
||
Chat ──"帮我 review 那个 PR"──→ Gitea Bot
|
||
Gitea Bot ──"CI 挂了，要不要我看看"──→ Chat
|
||
Worker ──任务完成──→ Chat / Gitea Bot
|
||
Self ──"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 webhook) │
|
||
│ ├─ life loop (Self) │
|
||
│ └─ worker loop (Worker) │
|
||
│ │
|
||
│ SQLite (共享状态) │
|
||
│ LLM backend (外部，OpenAI-compatible) │
|
||
│ │
|
||
└───────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 为什么是裸机而不是 Docker
|
||
|
||
- Caddy 要绑 80/443，容器里搞端口映射反而多一层
|
||
- noc 需要 spawn 子进程、读写磁盘、跑工具脚本，容器限制多
|
||
- 一台机器就是给 suite 独占的，不需要隔离
|
||
- Worker 以后可能跑 CI、生成 web app，直接操作文件系统最自然
|
||
|
||
Docker image 保留用于本地开发和测试。
|
||
|
||
### Caddy 的角色
|
||
|
||
不只是反向代理——是 suite 的**统一入口**：
|
||
|
||
- 子域名路由：不同服务用不同子域名
|
||
- 静态站点托管：Worker 生成的 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 | 多前端抽象（Telegram + 飞书） |
|
||
| Gitea Bot | ❌ 不存在 | webhook 接收 + PR review |
|
||
| Worker | 🟡 SubAgent 雏形 | 独立任务队列 + 结果路由 |
|
||
| Self | 🟡 life loop + reflect | 更丰富的自主行为 |
|
||
| Infra | ✅ Docker all-in-one | VPS setup 脚本 + systemd |
|