Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
import json
import os
from pathlib import Path
import shlex
import subprocess
import sys

Expand Down
4 changes: 2 additions & 2 deletions apps/workbench/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# AGENTS.md

在远程主机上跑 coding agent,用手机或电脑浏览器操作。
要做的事看 `docs/TODO.md`,架构看 `docs/PLAN.md`,设计图在 `docs/design/`。
安装和连接 LoopX Core 见 `docs/install-agent.md`。

## 开始前

先跑 `scripts/init.sh --check`:装依赖(缺时)、构建,再起一个用假 agent 的临时 hub 跑一轮冒烟测试。不过就先修好,再做新的事。要在浏览器里看改动,去掉 `--check`,它会打印地址、token 和 PID,一直运行到 Ctrl-C 或按这个 PID 停止,退出时清理临时目录。

## 三条原则

1. **简单,不干扰 agent。** 不改 agent 的目录、配置和会话。不做 IDE:没有补全、调试、多面板那一套。终端例外,是给人的运维工具(见 `TODO.md` 第 10 节),不碰 agent 的会话。文件默认只读:能浏览这台机器的目录(线程目录、项目目录、家目录,见第 11 节),回复里明确引用的单个文件也照旧能开。需要人写字的地方可以有纯文本编辑,像写字一样干净好看,不像代码编辑器;现在只有写作模式的正文(见 `docs/writing-design.md`)。
1. **简单,不干扰 agent。** 不改 agent 的目录、配置和会话。不做 IDE:没有补全、调试、多面板那一套。终端例外,是给人的运维工具,不碰 agent 的会话。文件默认只读:能浏览线程目录、项目目录和家目录,回复里明确引用的单个文件也照旧能开。需要人写字的地方可以有纯文本编辑,像写字一样干净好看,不像代码编辑器;现在只有写作模式的正文。
2. **界面要好看。** 标准是 Codex,目标是超过它。丑就是 bug。
3. **先参考再动手。** 新功能和改交互前,先看两三个同类开源项目怎么解这个问题(如 Codex、Claude Code、Chatwoot、LibreChat、Open WebUI),对比分析、择优借鉴,再开始写;参考结论一句话写进回复,让取舍有据可查。

Expand Down
66 changes: 10 additions & 56 deletions apps/workbench/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,35 +19,13 @@ LooChat 是一个开源的 agent 工作台。用简单的界面管理 TRAE、zco

LooChat 不动 agent 本身的目录、配置和会话,装好即用。LooChat 是自创品牌名,呼应随时叫上 AI 伙伴的感觉;图标采用一只举着大小双钳的蓝色小螃蟹,配浅蓝背景,保持简单、亲切的形象。

## 界面预览

| 桌面 · 亮色 | 桌面 · 深色 |
|---|---|
| ![桌面亮色](docs/screenshots/desktop-light.png) | ![桌面深色](docs/screenshots/desktop-dark.png) |

| 手机 · 亮色 | 手机 · 深色 |
|---|---|
| ![手机亮色](docs/screenshots/phone-light.png) | ![手机深色](docs/screenshots/phone-dark.png) |
## 使用方式

实时语音:开启后输入框换成一个会随声音起伏的球,你说的话以浅蓝气泡记进线程;后台任务和待批准事项一行可见;结束后逐句对话折成一行,下面留一份文字总结。

![实时语音(亮色):连接中、对话中、静音、结束后的总结](docs/screenshots/voice-light.png)

![实时语音(深色)](docs/screenshots/voice-dark.png)

用量与诊断:多 agent 的 token 用量、TPM 走势和费用估算。

![用量与诊断](docs/screenshots/usage-light.png)

写作模式:在加号菜单里一点就开。你口述观点,agent 用你的原话记成初稿、标出【待补】、追问具体场景,再按二稿、三稿、配图、润色一稿一稿往下走。正文是 `writing/` 下的 Markdown,按文章排版,画出 Mermaid 图、显示配图;读和写是同一张纸,可以直接改(键盘或语音输入法都行),agent 同时改过时不会覆盖你的版本。在正文里选中一句,一点「删」「待补」「为什么」「改成…」就成了给 agent 的注释。说「复盘」,agent 把你反复改的地方提炼成写作习惯,记进 `~/.loochat/notes/writing.md` 等你确认,之后每篇都照着写。设计见 [写作流程设计](docs/writing-design.md)。

![写作模式(亮色):加号菜单、选阶段、正文、选中一句加注释](docs/screenshots/writing-light.png)

![写作模式(深色)](docs/screenshots/writing-dark.png)

![写作模式(桌面):对话上方是阶段条,右边是正文](docs/screenshots/writing-desktop-light.png)

> 状态:可用,正在迭代。产品方向见 [愿景与设计思路](docs/VISION.md),现有架构见 [PLAN](docs/PLAN.md),进度见 [TODO](docs/TODO.md),扩展方案见 [扩展设计](docs/extensions-design.md)。
写作模式:在加号菜单里一点就开。你口述观点,agent 用你的原话记成初稿、标出【待补】、追问具体场景,再按二稿、三稿、配图、润色一稿一稿往下走。正文是 `writing/` 下的 Markdown,按文章排版,画出 Mermaid 图、显示配图;读和写是同一张纸,可以直接改(键盘或语音输入法都行),agent 同时改过时不会覆盖你的版本。在正文里选中一句,一点「删」「待补」「为什么」「改成…」就成了给 agent 的注释。说「复盘」,agent 把你反复改的地方提炼成写作习惯,记进 `~/.loochat/notes/writing.md` 等你确认,之后每篇都照着写。

## 已支持

Expand All @@ -61,18 +39,18 @@ LooChat 不动 agent 本身的目录、配置和会话,装好即用。LooChat
| zcode | `zcode app-server` 精简接入 | 有 | 按原生模型能力 | 暂无 |
| DeepSeek Harness | `dsh --profile acp`(ACP) | 有(仅允许一次/拒绝) | 有(按当前模型路由) | 暂无 |

各家 agent CLI 需要先在主机上装好并完成登录或鉴权。没装的 agent 在界面里显示为不可用;各家的能力和接入边界见 [架构说明](docs/PLAN.md)。
各家 agent CLI 需要先在主机上装好并完成登录或鉴权。没装的 agent 在界面里显示为不可用。

## 插件与参与

在「配置 → 扩展」按需安装:

- **线程看板**:按进行中、等你、待验收、已完成排列线程;agent 每轮结束报告进度,完成由你勾选。
- **Memory 记忆看板**:只读浏览 Codex 已有的记忆文档,不生成或同步记忆。
- **实时语音**(试验中,真人听说仍在验收):用这台机器上已登录的 Codex 原生语音,不需要另配 API Key;会消耗现有额度,具体计费归属尚未核实。在任意支持协作的线程里都能开,任务可以交给当前线程的 agent(Claude Code、pi 等)去做。浏览器开麦需要 HTTPS 或 localhost,见 [语音设计](docs/voice-design.md)。
- **实时语音**(试验中,真人听说仍在验收):用这台机器上已登录的 Codex 原生语音,不需要另配 API Key;会消耗现有额度,具体计费归属尚未核实。在任意支持协作的线程里都能开,任务可以交给当前线程的 agent(Claude Code、pi 等)去做。浏览器开麦需要 HTTPS 或 localhost。
- **LoopX**:需先安装并配置 LoopX,关联目标和线程后,在会话与看板中查看目标、待办和待决定事项。当前不提供自动推进。

skills 和 MCP 属于 agent 资源,通过各自的管理页操作,与 LooChat 插件分开。想接入工具、贡献一个工作视图,或者反馈使用中的问题,可以从 [参与和插件指南](docs/contributing-extensions.md) 开始。独立数据源可放在自己的仓库;当前还没有自动收录的插件市场。
skills 和 MCP 属于 agent 资源,通过各自的管理页操作,与 LooChat 插件分开。想接入工具、贡献一个工作视图,或者反馈使用中的问题,可以在 LoopX 仓库提交 issue。独立数据源可放在自己的仓库;当前还没有自动收录的插件市场。

## 快速开始

Expand All @@ -99,8 +77,6 @@ curl -fsSL "https://raw.githubusercontent.com/loopx-project/loopx/$ref/apps/work

**Core 单独安装。** 上述稀疏检出不包含 Python Core,安装器不会启动或升级 Core。普通 agent 会话可独立使用;Goal 功能需要运行中的 Core,以及对应注册表的 LoopX CLI。安装器会检查 Core 的 `/healthz`,不可达时打印地址和配置提示。在生成的 `.env` 中配置 `LOOCHAT_LOOPX_CORE_URL`(默认 `http://127.0.0.1:8792`);源码 Core 还需设置 `LOOCHAT_LOOPX_CMD`、`LOOCHAT_LOOPX_CWD`,具体见 [安装与 Core 连接](docs/install-agent.md#连接-loopx-core)。

以上 `main` 安装链接在本次变更合入 `main` 后生效;合入前请使用包含本安装器的提交 SHA。

**让 agent 帮你装**:把这句话发给这台机器上的 Claude Code、Codex 等:

```text
Expand All @@ -116,7 +92,7 @@ curl -fsSL "https://raw.githubusercontent.com/loopx-project/loopx/$ref/apps/work
```bash
cd apps/workbench # 从 LoopX 仓库根目录进入
npm install
npm run setup # 生成仓库根目录的 .env 和随机 LOOCHAT_TOKEN,并打印出来
npm run setup # 生成 apps/workbench 下的 .env 和随机 LOOCHAT_TOKEN,并打印出来
npm run build
LOOCHAT_ENV_FILE=../../.env npm start -w @loopx/loochat # 默认监听 127.0.0.1:8787
```
Expand All @@ -128,28 +104,7 @@ LOOCHAT_ENV_FILE=../../.env npm run dev:daemon # 后端
npm run dev:web # Vite,http://127.0.0.1:5173,/api 代理到后端
```

daemon 在 `packages/daemon` 目录里运行,所以用 `LOOCHAT_ENV_FILE` 指向根目录的 `.env`。没有设置 `LOOCHAT_ENV_FILE` 时,读取的是当前目录下的 `.env`。

## 产品官网与引导体验

官网:[maxliux5.github.io/loochat](https://maxliux5.github.io/loochat/)。

仓库包含独立的中文产品官网,展示「简单管理更多国内外 agent、按需安装插件、一起参与建设」的方向。官网展示自动交接、agent 协作、看板与记忆等可操作例子:体验账号接力、取消倒计时或原会话换模型,派发任务、查看成员与返回结果,勾选看板验收,以及搜索记忆、阅读原文;同时保留任务、审批和方案体验,介绍可安装的 LoopX 工作数据源,并提供插件贡献与需求反馈入口。技能和 MCP 通过各自的资源页管理;BotMux 提醒与通用任务控制仍在规划,具体状态见 [扩展设计](docs/extensions-design.md)。

```bash
npm run dev:site # 开发官网,默认端口 5174
npm run build:site # 输出 packages/site/dist
npm run preview:site # 预览构建后的静态站点
npm run test:site # 构建并运行官网浏览器测试
```

`packages/site/dist` 可以单独部署到静态托管服务,支持网站根目录和子目录。首页是 `index.html`,独立体验入口是 `demo/index.html`;托管服务需要支持目录首页。开发与本地预览默认只监听本机。

GitHub Pages 通过 `.github/workflows/pages.yml` 发布:推送到 `main` 后,自动安装依赖、检查并构建官网,再上传 `packages/site/dist`;也可在 Actions 中手动运行「Deploy website」。首次启用需在仓库 Settings → Pages 选择 GitHub Actions 作为发布来源。Pages 仅托管官网和本地模拟体验,运行 agent 的 hub 仍部署在自己的主机上。

体验区进入可视范围或点击场景后才加载,手机保留内嵌交互并提供「全屏体验」。官网使用自己的轻量图标和静态资源目录,不复制 hub 的应用清单。安装区包含启动后打开工作台、输入 token 及远程访问说明。

引导体验仅在浏览器内回放预置事件,不需要 daemon,不读取已保存的 hub token,不发送 `/api/` 请求,也不运行真实 agent。回复、命令结果和文件改动都是示例;切换任务可浏览不同流程,重新体验会清空本轮演示。普通 hub 的入口、登录和原有只读示例保持不变。官网独立构建,不由 `scripts/restart.sh` 部署。
daemon 在 `packages/daemon` 目录里运行,所以用 `LOOCHAT_ENV_FILE` 指向 `apps/workbench/.env`。没有设置 `LOOCHAT_ENV_FILE` 时,读取的是当前目录下的 `.env`。

## 远程访问

Expand All @@ -176,7 +131,7 @@ GitHub Pages 通过 `.github/workflows/pages.yml` 发布:推送到 `main` 后

私有 socket 由本机用户文件权限保护。hub token 能操作登记的节点;节点令牌只能领取自己的 relay 任务。移除机器会撤销令牌,不删除节点线程和文件。

`scripts/update-hosts.sh [机器ID] [--check]` 可经 relay 更新在线节点。节点需要 systemd 用户服务与仓库克隆(默认优先使用 `install.sh` 的 `~/.local/share/loochat`,否则回退 `~/code/loochat`;hosts.json 的 `repo` 可设为仓库根或 `apps/workbench` 子目录)。更新任务独立于节点服务运行,构建快照、等待空闲后切换、失败回滚;hub 在重连后读取结果。`--check` 会 fetch 并快进克隆,但不构建或切换服务。真实 systemd 更新与跨网络部署仍待验收,机制和限制见 [多机管理设计](docs/multi-host-design.md)。
`scripts/update-hosts.sh [机器ID] [--check]` 可经 relay 更新在线节点。节点需要 systemd 用户服务与仓库克隆(默认优先使用 `install.sh` 的 `~/.local/share/loochat`,否则回退 `~/code/loochat`;hosts.json 的 `repo` 可设为仓库根或 `apps/workbench` 子目录)。更新任务独立于节点服务运行,构建快照、等待空闲后切换、失败回滚;hub 在重连后读取结果。`--check` 会 fetch 并报告候选版本,保留当前检出、构建和服务。真实 systemd 更新与跨网络部署仍待验收。

## 开机自启

Expand Down Expand Up @@ -206,7 +161,7 @@ scripts/migrate-name.sh # 构建,等线程空闲后切换,服务
## 发布前检查

```bash
npm run check:publish
node scripts/check-publish.mjs
```

扫描会被发布的文件,查找你的用户名、主机名、家目录路径、内网 IP、长密钥、邮箱地址。公司名、项目名这类私人词放在仓库外的 `~/.config/loochat/publish-denylist`(每行一个),也会一起检查。
Expand All @@ -216,14 +171,13 @@ npm run check:publish
```
packages/daemon 网关:HTTP/SSE API、鉴权、SQLite 存储、各 agent 的适配器
packages/web 界面:React + Vite,手机与桌面共用一套组件
docs/ 计划与界面说明
docs/ 安装与 Core 连接指南
```

## 开发

```bash
scripts/init.sh # 装依赖、构建,起一个用假 agent 的临时 hub 并跑一轮冒烟测试;加 --check 跑完即停
scripts/demo.sh # 起一个浏览器可打开的体验 hub:假 agent,绑定所有网卡,打印地址和 token;用 stop 子命令停止并清理
npm test # daemon 与 web 的全部单元测试和 API 测试
npm run typecheck
npm run test:e2e # 统一构建一次,再运行浏览器 E2E(最多并行 2 个测试文件)
Expand Down
2 changes: 1 addition & 1 deletion apps/workbench/docs/install-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## 预览、安装与版本

默认安装当前 `main`;要复现某个版本,将下面的 `main` 替换为完整提交 SHA 或 tag。脚本和源码使用同一个 ref。下面的 `main` 链接在本变更合入后才生效。
默认安装当前 `main`;要复现某个版本,将下面的 `main` 替换为完整提交 SHA 或 tag。脚本和源码使用同一个 ref。先用 `--dry-run` 检查安装目录与版本。

```bash
ref=main
Expand Down
35 changes: 18 additions & 17 deletions apps/workbench/install.sh
Original file line number Diff line number Diff line change
@@ -1,20 +1,4 @@
#!/usr/bin/env bash
# Installs LooChat on this machine, or updates it when it is there already:
#
# curl -fsSL https://raw.githubusercontent.com/loopx-project/loopx/main/apps/workbench/install.sh | bash
# curl -fsSL .../install.sh | bash -s -- --dry-run only print what it would do
#
# It clones the code to ~/.local/share/loochat, builds it, writes ~/.config/loochat/.env (a random
# token; data under ~/.local/state/loochat; your home as the working directory), runs it as a
# systemd user service and prints the address and token. Run again to update: the .env, the
# token and the data stay. Agents (Claude Code, Codex, ...) are installed and signed in apart.
#
# --dry-run print the steps, change nothing
# --no-service do not install the service; print how to start it by hand
# --uninstall stop and remove the service and the code; the .env and the data stay
#
# LOOCHAT_REPO (git URL or path), LOOCHAT_REF (branch, tag or commit; default main) and
# LOOCHAT_HOME (checkout directory) override the defaults. Core is installed separately.
set -euo pipefail

REPO_URL="${LOOCHAT_REPO:-https://github.com/loopx-project/loopx.git}"
Expand All @@ -25,13 +9,30 @@ ENV_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/loochat/.env"
DATA_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/loochat/data"
NAME=loochat

usage() {
cat <<'USAGE'
Install or update LooChat from the LoopX repository.

Usage: bash install.sh [--dry-run] [--no-service] [--uninstall]
... | bash -s -- [options]

--dry-run Print the steps without writing files or starting services.
--no-service Build the application and print the foreground start command.
--uninstall Remove the service and checkout, keeping configuration and data.
-h, --help Show this help.

LOOCHAT_REPO, LOOCHAT_REF (default: main), and LOOCHAT_HOME override
the source, revision and checkout directory. Install LoopX Core separately.
USAGE
}

DRY=0 SERVICE=1 UNINSTALL=0
for arg in "$@"; do
case "$arg" in
--dry-run) DRY=1 ;;
--no-service) SERVICE=0 ;;
--uninstall) UNINSTALL=1 ;;
-h | --help) sed -n '2,17p' "$0" 2>/dev/null | sed 's/^# \{0,1\}//'; exit 0 ;;
-h | --help) usage; exit 0 ;;
*) echo "Unknown option: $arg (see --help)" >&2; exit 2 ;;
esac
done
Expand Down
8 changes: 8 additions & 0 deletions apps/workbench/packages/e2e/test/install.spec.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,14 @@ test('setup preserves current and historical tokens without appending a second c
}
});

test('help works when the installer is supplied on stdin', () => {
const installer = readFileSync(join(repo, 'install.sh'), 'utf8');
const result = spawnSync('bash', ['-s', '--', '--help'], { input: installer, encoding: 'utf8' });
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /--dry-run/);
assert.match(result.stdout, /--no-service/);
});

test('a dry run changes nothing', (t) => {
const { run, read, home } = fixture(t);
const r = run('--dry-run');
Expand Down
Loading
Loading