Skip to content

docs(readme): unify bilingual open-source README and README_CN layout #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mcocdaa merged 1 commit into from
Oct 17, 2026
Merged

docs(readme): unify bilingual open-source README and README_CN layout #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
114 changes: 71 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,106 @@
<div align="center">

# MeetFlow

> 轻量级多人共享会议档案、结构化行动项追踪与团队知识沉淀系统。
**Collaborative meeting workspace with live agenda timing, structured outcome extraction, and headless AI note ingestion.**

[![Family: *Flow](https://img.shields.io/badge/family-*Flow-8A2BE2.svg)](https://github.com/mcocdaa)
[![Family: *Flow](https://img.shields.io/badge/Family-*Flow-8A2BE2?style=flat-square)](https://github.com/mcocdaa)
[![CI](https://github.com/mcocdaa/MeetFlow/actions/workflows/ci.yml/badge.svg)](https://github.com/mcocdaa/MeetFlow/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/mcocdaa/MeetFlow?display_name=tag&sort=semver)](https://github.com/mcocdaa/MeetFlow/releases)
[![Container image](https://img.shields.io/badge/image-ghcr.io%2Fmcocdaa%2Fmeetflow-0b6a58)](https://github.com/mcocdaa/MeetFlow/pkgs/container/meetflow)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](compose.yaml)
[![Release](https://img.shields.io/github/v/release/mcocdaa/MeetFlow?display_name=tag&sort=semver&style=flat-square)](https://github.com/mcocdaa/MeetFlow/releases)
[![GHCR Image](https://img.shields.io/badge/GHCR-ghcr.io%2Fmcocdaa%2Fmeetflow-0b6a58?style=flat-square&logo=docker)](https://github.com/mcocdaa/MeetFlow/pkgs/container/meetflow)
[![Python 3.12](https://img.shields.io/badge/Python-3.12-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Docker Ready](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white)](compose.yaml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)

<p align="center">
<img src="docs/assets/demo_meetflow.gif" alt="MeetFlow Live Demo" width="820">
</p>
[**English**](README.md) · [**简体中文**](README_CN.md)

MeetFlow 是一个轻量级多人共享会议档案工具。一次会议可以保存 Markdown 原始记录、关键结论、结构化行动项、后续补充、图片与小文件。所有成员使用同一个共享工作区；管理员负责账号审批和插件配置。
<img src="docs/assets/demo_meetflow.gif" alt="MeetFlow Demo" width="840">

## 快速启动
</div>

MeetFlow 的公开镜像是 `ghcr.io/mcocdaa/meetflow`，支持 `linux/amd64` 和 `linux/arm64`，服务器拉取不需要 `docker login ghcr.io`。
---

在服务器的空部署目录中复制配置模板并编辑：
## ✨ Highlights

```bash
cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(48))" # 生成 APP_SECRET_KEY
vim .env
```
- **Live Agenda Workbench & Focus Mode**: Run structured meetings (`Planned → In Progress → Completed`) with per-agenda countdown timers, actual duration tracking, optimistic concurrency protection (`expected_version`), and read-only completion snapshots.
- **Inline Structured Outcome Extraction**: Write `@决策:` (Decision), `@行动:` (Action Item), and `@开放问题:` (Open Question) directly inside agenda Markdown notes to automatically reconcile cross-meeting trackers while preserving manual items.
- **Headless AI Note Ingestion API**: Push meeting transcripts or LLM summaries in a single atomic call via `POST /api/v1/meetings/{id}/ingest` authenticated with Personal Access Tokens (`X-API-Key: mf_...`) or `Authorization: Bearer mf_...`.
- **Recurring Series & Calendar Subscriptions**: Schedule daily, weekly, monthly, or yearly recurring meeting series with IANA timezone support, ad-hoc session support, and subscribable `.ics` calendar feeds.
- **Role-Based Project Governance & Webhooks**: Fine-grained project roles (`lead`, `member`, `stakeholder`), meeting-level guest invitations, and outbound webhook notifications for Feishu, WeCom, DingTalk, and generic HTTP endpoints.
- **Hardened Single-Container Deployment**: Ships as a multi-arch (`linux/amd64`, `linux/arm64`) read-only container (`ghcr.io/mcocdaa/meetflow`) backed by FastAPI, Vue 3 + Naive UI, SQLite WAL, and built-in background workers.

---

至少替换 `.env` 中的三项：`ADMIN_PASSWORD`（至少 12 位的强密码）、`APP_SECRET_KEY`（上一步生成并长期保存的随机值）和 `TRUSTED_ORIGINS`（你的 HTTPS 域名）。`.env` 包含密钥，不要提交到 Git。
## 🚀 Quick Start

然后从这个部署目录启动：
### Option 1: Pre-built Container Image (Recommended)

Copy `.env.example`, set a strong `ADMIN_PASSWORD` (12+ chars), `APP_SECRET_KEY`, and `TRUSTED_ORIGINS`, then launch on `127.0.0.1:8000`:

```bash
cp .env.example .env && chmod 600 .env
# Edit .env: set ADMIN_PASSWORD, APP_SECRET_KEY (python3 -c "import secrets; print(secrets.token_urlsafe(48))"), TRUSTED_ORIGINS
docker run -d --name meetflow --init --read-only --tmpfs /tmp:size=64m \
--security-opt no-new-privileges:true --restart unless-stopped \
-p 127.0.0.1:8000:8000 \
-v "$PWD/data:/app/data" \
--env-file .env \
-p 127.0.0.1:8000:8000 -v "$PWD/data:/app/data" --env-file .env \
ghcr.io/mcocdaa/meetflow:latest
```

`$PWD/data` 是当前部署目录中的 `./data/`，保存数据库、附件和备份；容器内固定映射为 `/app/data`，第一次运行时 Docker 会创建该目录。`APP_SECRET_KEY` 必须与 `./data/` 一起长期保存：更换它会使现有登录会话失效，也会导致已经加密保存的插件密钥无法解密。
Or start from source with Docker Compose:

生产容器默认只监听宿主机 `127.0.0.1:8000`。对外提供服务前，请按[运维指南](docs/operations.md)配置 HTTPS 反向代理；`APP_ENV=production` 会拒绝不安全的 Cookie 或 HTTP 可信来源配置。更新回滚、备份恢复和生产插件挂载也见运维指南。
```bash
MEETFLOW_IMAGE=ghcr.io/mcocdaa/meetflow:latest docker compose up -d
curl http://127.0.0.1:8000/api/health
```

## 首次登录与账号
### Option 2: Local Development

首次启动会使用 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 创建管理员。后续启动不会用新的环境变量密码覆盖已有账号。
Requires **Python 3.12+** and **Node.js 22+**:

- `ALLOW_REGISTRATION=true`：用户可以申请账号，管理员批准后才能登录。
- `ALLOW_REGISTRATION=false`：关闭自助申请，由管理员创建固定体验账号。
```bash
python -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
npm --prefix frontend ci
./scripts/start.sh local
```

管理员可以批准、拒绝或禁用账号，也可以重置成员密码。登录后，所有成员都在同一个共享工作区中维护会议、结论、行动项和附件。
- **Backend API & OpenAPI**: `http://127.0.0.1:8000` (`/api/health`)
- **Frontend Dev Server**: `http://localhost:5173`

## 会议系列与纪要
---

项目可以创建独立的会议系列，并设置每天、每周、每月或每年的本地开始时间、时区和默认时长。每个系列也可以临时添加会议；临时会议仍归属于该系列，但不会替代下一次固定周期会议。固定周期实例到期时会创建为“待开始”；开始新周期实例时，同一系列上一个尚未结束的固定实例会自动结束。
## 🤖 AI Note Ingestion API

会议操作只有“待开始 → 会议进行中 → 已结束”三个状态。结束会议时，未完成议题会统一记为已跳过；每个议题记录预计时长（新增默认为 5 分钟）及实际耗时。
Generate a Personal Access Token (`mf_...`) in **Personal Center → API Keys** (or via `POST /api/v1/auth/tokens`) and ingest structured Markdown notes plus outcome tags in one atomic request:

会议纪要和议题记录均需要显式保存。议题记录中可使用 `@决策:`、`@行动:`、`@开放问题:` 生成随记录同步的产出；在下方手动添加的产出不受记录修改影响。会议结束后，完成档案会只读展示已保存纪要、会议总实际时长、每条议题记录及其耗时、状态和产出。
```bash
curl -X POST "http://127.0.0.1:8000/api/v1/meetings/<MEETING_ID>/ingest" \
-H "X-API-Key: mf_your_personal_access_token" \
-H "Content-Type: application/json" \
-d '{
"agenda_title": "Architecture & Release Sync",
"auto_complete_agenda": true,
"notes_markdown": "### Key Takeaways\n- @决策: Adopt single-container SQLite deployment for v1.0\n- @行动: Finalize reverse-proxy TLS checklist @admin\n- @开放问题: Should webhook retries support custom backoff?"
}'
```

## 检查服务
MeetFlow automatically creates or updates the target agenda item, extracts `@决策:` / `@行动:` / `@开放问题:` records into the project's global trackers, and records an audit event.

---

## 🛠️ Verification & Tests

```bash
docker ps --filter name=meetflow
curl http://127.0.0.1:8000/api/health
.venv/bin/python -m pytest -q
npm --prefix frontend test
npm --prefix frontend run build
```

健康接口返回 `{"status":"ok"}` 后，再通过配置好的 HTTPS 域名访问 MeetFlow。
---

## 进一步文档
## 📚 Documentation & License

- [运维指南](docs/operations.md)：HTTPS、临时覆盖配置、更新回滚、备份恢复与生产插件挂载。
- [发布指南](docs/release.md)：GitHub Actions、GHCR 镜像和版本标签，供仓库维护者使用。
- [开发与维护文档](docs/README.md)：架构、本地开发、测试与 agent 工作入口。
- **[Operations Guide](docs/operations.md)**: HTTPS reverse proxy, `.env` security boundaries, upgrades, rollbacks, backups, and plugin mounts.
- **[Release Guide](docs/release.md)**: GitHub Actions CI/CD, multi-arch GHCR image publishing, and semantic version tagging.
- **[Developer & Agent Guide](docs/README.md)**: Architecture index, database migrations ([docs/development.md](docs/development.md)), and plugin contracts ([backend/app/plugins/README.md](backend/app/plugins/README.md)).
- **License**: Released under the [MIT License](LICENSE).
106 changes: 106 additions & 0 deletions README_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
<div align="center">

# MeetFlow

**支持议题计时、结构化结论提取（@决策/@行动/@开放问题）与 AI 纪要原子导入的团队会议工作台。**

[![Family: *Flow](https://img.shields.io/badge/Family-*Flow-8A2BE2?style=flat-square)](https://github.com/mcocdaa)
[![CI](https://github.com/mcocdaa/MeetFlow/actions/workflows/ci.yml/badge.svg)](https://github.com/mcocdaa/MeetFlow/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/mcocdaa/MeetFlow?display_name=tag&sort=semver&style=flat-square)](https://github.com/mcocdaa/MeetFlow/releases)
[![GHCR Image](https://img.shields.io/badge/GHCR-ghcr.io%2Fmcocdaa%2Fmeetflow-0b6a58?style=flat-square&logo=docker)](https://github.com/mcocdaa/MeetFlow/pkgs/container/meetflow)
[![Python 3.12](https://img.shields.io/badge/Python-3.12-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Docker Ready](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white)](compose.yaml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)

[**English**](README.md) · [**简体中文**](README_CN.md)

<img src="docs/assets/demo_meetflow.gif" alt="MeetFlow Demo" width="840">

</div>

---

## ✨ 核心特性

- **实时议题工作台与专注模式**：围绕“待开始 → 会议进行中 → 已结束”生命周期推进议题，内置单议题倒计时、实际耗时统计、乐观锁并发保护（`expected_version`）与会后只读档案快照。
- **行内结构化结论自动提取**：在议题 Markdown 记录中直接书写 `@决策:`、`@行动:`、`@开放问题:`，保存时自动同步至跨会议追踪视图，同时保留手动添加的独立产出。
- **AI 纪要原子导入接口（Headless Ingestion）**：支持通过个人访问令牌（`X-API-Key: mf_...` 或 `Authorization: Bearer mf_...`）调用 `POST /api/v1/meetings/{id}/ingest`，一键写入议题纪要并自动提取结构化结论与行动项。
- **周期会议系列与日历订阅**：支持按天、周、月、年配置带 IANA 时区的固定周期会议系列及临时加会，提供标准 iCalendar（`.ics`）订阅源。
- **项目级权限治理与群机器人通知**：内置项目角色（负责人 `lead`、成员 `member`、干系人 `stakeholder`）与单场会议嘉宾邀请边界，支持飞书、企业微信、钉钉及通用 Webhook 纪要推送。
- **加固单容器生产部署**：公开多架构镜像（`ghcr.io/mcocdaa/meetflow`，支持 `linux/amd64` 与 `linux/arm64`），基于 FastAPI + Vue 3 + SQLite 构建，默认支持只读根文件系统与非特权运行。

---

## 🚀 快速开始

### 方式一：公开容器镜像部署（推荐）

在部署目录复制 `.env.example`，配置至少 12 位的 `ADMIN_PASSWORD`、长期保存的 `APP_SECRET_KEY` 以及 `TRUSTED_ORIGINS`（HTTPS 域名），并在 `127.0.0.1:8000` 启动：

```bash
cp .env.example .env && chmod 600 .env
# 编辑 .env：设置 ADMIN_PASSWORD、APP_SECRET_KEY（可用 python3 -c "import secrets; print(secrets.token_urlsafe(48))" 生成）与 TRUSTED_ORIGINS
docker run -d --name meetflow --init --read-only --tmpfs /tmp:size=64m \
--security-opt no-new-privileges:true --restart unless-stopped \
-p 127.0.0.1:8000:8000 -v "$PWD/data:/app/data" --env-file .env \
ghcr.io/mcocdaa/meetflow:latest
```

也可以使用 Docker Compose 快速启动并检查健康状态：

```bash
MEETFLOW_IMAGE=ghcr.io/mcocdaa/meetflow:latest docker compose up -d
curl http://127.0.0.1:8000/api/health
```

### 方式二：本地源码开发

需要 **Python 3.12+** 与 **Node.js 22+**：

```bash
python -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
npm --prefix frontend ci
./scripts/start.sh local
```

- **后端服务与健康检查**：`http://127.0.0.1:8000`（`/api/health`）
- **前端开发服务器**：`http://localhost:5173`

---

## 🤖 AI 纪要导入接口

在「个人中心 → API 密钥」生成个人访问令牌（`mf_...`，或调用 `POST /api/v1/auth/tokens`），即可通过单次请求将外部语音转写或大模型总结原子化写入指定会议：

```bash
curl -X POST "http://127.0.0.1:8000/api/v1/meetings/<MEETING_ID>/ingest" \
-H "X-API-Key: mf_your_personal_access_token" \
-H "Content-Type: application/json" \
-d '{
"agenda_title": "架构评审与发布同步",
"auto_complete_agenda": true,
"notes_markdown": "### 讨论结论\n- @决策: v1.0 采用单容器 SQLite 持久化部署架构\n- @行动: 完善反向代理 HTTPS 与备份巡检清单 @admin\n- @开放问题: Webhook 失败重试是否需要自定义退避策略？"
}'
```

接口会自动匹配或新建对应议题、解析同步 `@决策:` / `@行动:` / `@开放问题:` 产出，并记录活动审计日志。

---

## 🛠️ 测试与构建验证

```bash
.venv/bin/python -m pytest -q
npm --prefix frontend test
npm --prefix frontend run build
```

---

## 📚 进一步文档与许可证

- **[运维指南](docs/operations.md)**：HTTPS 反向代理、`.env` 密钥边界、版本升级回滚、数据备份恢复与生产插件挂载。
- **[发布指南](docs/release.md)**：GitHub Actions、GHCR 多架构镜像发布与版本标签规范。
- **[开发与维护文档](docs/README.md)**：系统架构索引、本地开发与数据库迁移（[docs/development.md](docs/development.md)）、插件契约（[backend/app/plugins/README.md](backend/app/plugins/README.md)）。
- **开源许可**：本项目基于 [MIT License](LICENSE) 开源。
Loading