内容
# 液体流动
用于同步和**热加载** Liquid 模板的工具，适用于 **Comarch 电子商店**。您可以在本地编辑模板文件，液体流动会立即将更改发送到商店，检测与管理面板的冲突，并可选地通过 Git 对文件夹进行版本控制。
有两种版本，具有相同的核心：
- **桌面应用程序** (macOS / Windows / Linux) — 从图标启动，图形界面，菜单栏图标（托盘），后台同步。
- **CLI** — `liquidflow` 命令启动交互式终端界面，具有自己的提示和斜杠命令调色板。
## 功能
- **热加载** — 监视本地模板文件夹；每个文件保存都会立即发送到商店（SOAP `Liquid_FileSet` / `Liquid_FileAdd`）。
- **冲突检测** — 如果有人在管理面板中更改文件，液体流动会检测到并允许**下载**最新版本或**覆盖**商店版本（单个或批量）。
- **版本控制和备份（Git）** — 模板文件夹作为 Git 仓库：每次同步自动提交，历史记录，任意版本恢复，可选推送到 GitHub。
## 结构（monorepo）
```
packages/
core/ @liquidflow/core — 共同逻辑（独立于 UI）：
soap.js SOAP 客户端 iSklep24Service.asmx (+ 会话)
syncEngine.js 文件监视器，热加载，冲突
store.js 配置，元数据，路径
git.js 版本控制 / 备份 / 推送
controller.js 状态编排（事件发射器）
log.js, xml.js, translations.js
apps/
desktop/ @liquidflow/desktop — Electron（窗口，托盘，IPC）+ 渲染
React + Vite + Tailwind + shadcn/ui
cli/ @liquidflow/cli — 交互式 CLI `liquidflow`（Ink/React）
```
两个应用程序都是在同一个 `Controller` 上构建的 `Controller` 来自`@liquidflow/core`。
## 要求
- [Node.js](https://nodejs.org) 20+
- [Git](https://git-scm.com) — 可选，仅用于版本控制/备份
## 安装
```bash
npm install # 安装所有工作区（一次）
```
## 桌面应用程序
```bash
npm run dev # 开发模式（Vite + Electron，热加载 UI）
npm run build # 当前系统的软件包
npm run build:mac # .dmg + .zip（macOS）
npm run build:win # .exe 安装程序（Windows）
npm run build:linux # .AppImage（Linux）
```
结果输出到 `apps/desktop/release/`。这是一个具有图标（Dock / 任务栏）和托盘图标的成熟应用程序。
**如何使用：** 添加商店（名称，URL `https://…` 或 `http://localhost:port`，Web 负责人密码 — 登录名始终为 `webmaster`）→ 选择模板 → 文件将本地下载并启动实时同步。选项卡：**文件**（冲突），**日志**（事件），**Git / 备份**（版本控制）。
## CLI（`liquidflow`）
```bash
npm run cli # 从存储库运行
# 或在构建/链接软件包后：
npm link --workspace @liquidflow/cli && liquidflow
```
启动交互式界面：顶部状态栏（商店，模板，冲突，Git），实时日志面板和提示。输入 `/` 以打开 **命令调色板**，支持自动补全。
**导航：** `/` 调色板 · `↑`/`↓` 选择 · `Enter` 确认 · `Tab` 自动补全 · `Esc` 返回 · `/exit` 退出（故意忽略 Ctrl+C 以避免终止同步会话）。
**斜杠命令：**
| 命令 | 操作 |
|---|---|
| `/connect` | 连接到商店；添加 / 切换 / 断开 / 删除（商店列表 + 操作） |
| `/templates` | 选择模板 |
| `/conflicts` | 冲突和操作 — 下载 / 发送 / 删除，单个或批量 |
| `/git` | 版本控制和备份（自动提交，推送，历史记录，恢复，远程） |
| `/open` | 打开本地模板文件夹 |
| `/settings` | 设置：日志换行，语言 |
| `/clear` | 清空日志面板 |
| `/exit` (`/quit`) | 退出 |
## MCP 服务器（@liquidflow/mcp）
液体流动提供 MCP（模型上下文协议）服务器，允许 AI 代理（例如 Claude Code，Claude Desktop）通过 MCP 协议以编程方式控制同步，冲突，日志和 Git 检查点。
### 如何启动
服务器在标准输入/输出流上运行：
```bash
# 直接从 monorepo 启动
node apps/mcp/bin/liquidflow-mcp.js
# 或链接软件包后：
npm link --workspace @liquidflow/mcp && liquidflow-mcp
```
### MCP 主机配置
示例配置条目，添加到您的 MCP 客户端配置文件中（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"liquidflow": {
"command": "node",
"args": ["/绝对路径/到/repo/apps/mcp/bin/liquidflow-mcp.js"]
}
}
}
```
### 安全性和限制
- **MCP 没有密码**：`connect_shop` 工具仅支持使用预先保存的已记住密码（SavePassword）的商店连接。添加新商店或验证新会话必须通过 CLI 或桌面应用程序完成。
- **标准输入/输出纯度**：服务器仅通过标准输出通信。技术日志和错误通过 MCP 错误机制或发送到标准错误流。
## 文件位置
跨平台应用程序数据目录：
- **macOS**：`~/Library/Application Support/LiquidFlow/`
- **Windows**： `%APPDATA%\LiquidFlow\`
- **Linux**： `~/.config/liquid-flow/` （或 `$XDG_CONFIG_HOME`）
结构：`Shops/<商店名称>/files/<模板 ID>/<模式>/…` — 这是您编辑模板文件的位置。`meta/` 存储冲突检测的时间戳，（启用后）`.git/` 存储版本历史记录。
> 桌面版和 CLI 共享相同的数据目录和配置。
## Git — 模板版本控制（`/git`）
Git 仓库位于 `files/<模板 ID>/0/` 文件夹中。液体流动维护 **双分支模型**：
- `liquidflow/wip` — 工作分支。监视器检测到的每个文件更改都会在此分支上自动提交；**不会**自动推送。
- `main` — 清洁分支。仅包含 `/git checkpoint` 操作的提交；从此分支推送。
### 典型流程
```
/git → 启用 Git # 初始化存储库 + 设置 liquidflow/wip
# 编辑文件 → 自动提交到 wip
/git → 检查点 # 合并 wip→main，重置 wip 到 main
/git → 推送 # git push origin main
```
### 其他 `/git` 操作
| 操作 | 描述 |
|---|---|
| **历史记录 / 恢复** | 显示 `main` 分支的提交列表；选择恢复文件，通过 `git checkout` 并在 `wip` 上提交恢复 |
| **设置远程仓库** | 将远程仓库 URL 保存到配置中 |
| **拉取** | 从远程仓库拉取（仅当 `wip` == `main` 时允许，即没有未推送的提交） |
| **克隆** | 将远程仓库克隆到 `0/` 文件夹；为 `0` 模式播种元数据，从商店获取 `2` 模式文件 |
| **自动提交** | 切换 — 当禁用时，监视器不会提交（文件仍会同步到商店） |
| **自动推送** | 切换 — 启用后，在每次检查点后自动推送 |
`liquidflow/wip` 分支始终从 `main` 分支的起点创建（而非当前 HEAD），确保即使 HEAD 在其他位置，基础也保持干净。所有修改 Git 索引（`.git/index`）的操作都按顺序排列在会话队列中，以消除对 `.git/index.lock` 的竞争。
## Git / GitHub — 身份验证
推送使用系统的 Git 配置：SSH 密钥（`git@github.com:…`）或 HTTPS URL 中的凭证管理器/令牌。液体流动不存储 GitHub 凭证。
## 协议
SOAP `iSklep24Service.asmx`，命名空间 `http://www.icomarch24.pl/iSklep24`，身份验证 `SignIn` + 会话 cookie，操作 `Liquid_Get / FilesGet / FilesMetaGet / FileSet / FileAdd / FileDelete / FileRename / FileIsValid / Unlock`。限制：名称 ≤ 64 个字符，文件 ≤ 519168 字节，文本文件验证。
