Skip to content

Commit e8bd87e

Browse files
breeze0305breeze0305
committed
Publish UFriend desktop application and user documentation
0 parents  commit e8bd87e

161 files changed

Lines changed: 27427 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
* text=auto
2+
*.js text eol=lf
3+
*.cjs text eol=lf
4+
*.json text eol=lf
5+
*.css text eol=lf
6+
*.html text eol=lf
7+
*.md text eol=lf
8+
*.cs text eol=lf
9+
*.ps1 text eol=crlf
10+
*.cmd text eol=crlf
11+
*.bat text eol=crlf
12+
*.png binary
13+
*.jpg binary
14+
*.jpeg binary
15+
*.ico binary
16+
*.pdf binary
17+
*.docx binary
18+
# Keep the upstream FFmpeg notices byte-for-byte for the pinned SHA-256 checks.
19+
scripts/runtime/ffmpeg/COPYING.GPLv3.txt -text
20+
scripts/runtime/ffmpeg/UPSTREAM-README.txt -text -whitespace

‎.github/workflows/ci.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
windows:
14+
runs-on: windows-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: actions/setup-node@v4
18+
with:
19+
node-version: '24'
20+
cache: npm
21+
- run: npm ci
22+
- run: npm run build:native
23+
- run: npm run check
24+
- run: npm test
25+
# Media integration tests skip when the pinned FFmpeg tools are absent.

‎.gitignore‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Dependencies, build outputs and caches
2+
node_modules/
3+
/dist/
4+
/build/
5+
/coverage/
6+
/.nyc_output/
7+
/.cache/
8+
/.npm/
9+
*.tsbuildinfo
10+
*.log
11+
npm-debug.log*
12+
yarn-debug.log*
13+
yarn-error.log*
14+
15+
# Local test output, research and publishing bundles
16+
/.test-data/
17+
/.test-results/
18+
/.research/
19+
/local/*
20+
21+
# Independent service repositories
22+
/PC-LLM-API/
23+
/PC-OCR-API/
24+
/PC-Whisper-API/
25+
26+
# Local-only planning, competition and historical validation documents
27+
/docs/competition/
28+
/docs/product/
29+
/docs/development/*
30+
!/docs/development/FFMPEG_RUNTIME.md
31+
32+
# Keep only the artwork required by the icon build
33+
/design/logo-options/*
34+
!/design/logo-options/ufriend-logo-b-leaf-companion.png
35+
36+
# Local application data, mail and database exports
37+
/workspace/
38+
/user-data/
39+
credentials.bin
40+
credentials.bin.*
41+
state.json
42+
state.backup.json
43+
state.corrupt-*.json
44+
*.eml
45+
*.mbox
46+
*.pst
47+
*.ost
48+
*.db
49+
*.db-*
50+
*.sqlite
51+
*.sqlite-*
52+
*.sqlite3
53+
*.sqlite3-*
54+
55+
# Imported recordings, exported videos and transcripts
56+
*.mp3
57+
*.wav
58+
*.m4a
59+
*.aac
60+
*.flac
61+
*.ogg
62+
*.wma
63+
*.mp4
64+
*.webm
65+
*.mov
66+
*.avi
67+
*.mkv
68+
*.srt
69+
*.vtt
70+
71+
# Environment and credentials
72+
*.env
73+
.env
74+
.env.*
75+
!.env.example
76+
!.env.template
77+
*.local.json
78+
credentials.json
79+
credentials-*.json
80+
credentials_*.json
81+
client_secret*.json
82+
client-secret*.json
83+
google-oauth*.json
84+
google_oauth*.json
85+
oauth-client*.json
86+
oauth_client*.json
87+
service-account*.json
88+
service_account*.json
89+
serviceAccount*.json
90+
*-service-account*.json
91+
*_service_account*.json
92+
*-sa-key.json
93+
application_default_credentials.json
94+
token.json
95+
tokens.json
96+
token-*.json
97+
token_*.json
98+
access_token*.json
99+
access-token*.json
100+
refresh_token*.json
101+
refresh-token*.json
102+
*.pem
103+
*.key
104+
*.p12
105+
*.pfx
106+
107+
# This source file must remain an empty OAuth template
108+
!/app/config/google-oauth.json
109+
110+
# Downloaded runtimes and model weights; keep app/models and scripts/runtime
111+
/.runtime/
112+
/.runtimes/
113+
/.downloads/
114+
/downloads/
115+
/models/
116+
*.gguf
117+
*.safetensors
118+
*.onnx
119+
*.pt
120+
*.pth
121+
*.ckpt
122+
*.hef
123+
*.tflite
124+
125+
# Compiled binaries and downloaded archives
126+
*.exe
127+
*.dll
128+
*.pdb
129+
*.msi
130+
*.msix
131+
*.zip
132+
*.7z
133+
*.rar
134+
*.tar
135+
*.tar.gz
136+
*.tgz
137+
138+
# Local editor and agent configuration
139+
/.vscode/
140+
/.idea/
141+
/.vs/
142+
/.codex/
143+
/.agents/
144+
AGENTS.md
145+
AGENTS.local.md
146+
CLAUDE.md
147+
CLAUDE.local.md
148+
*.code-workspace
149+
*.swp
150+
*.swo
151+
*~
152+
153+
# Python environments used by local tooling
154+
.venv/
155+
venv/
156+
__pycache__/
157+
*.py[cod]
158+
.pytest_cache/
159+
.mypy_cache/
160+
.ruff_cache/
161+
162+
# OS-generated files
163+
Thumbs.db
164+
Desktop.ini
165+
.DS_Store

‎CONTRIBUTING.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Contributing to UFriend
2+
3+
Use [GitHub Issues](https://github.com/breeze0305/UFriend/issues) for reproducible bugs and feature requests. For vulnerabilities, follow [SECURITY.md](SECURITY.md).
4+
5+
## Report a problem
6+
7+
Include the UFriend version, Windows version, local or cloud processing source, steps to reproduce, expected behavior, and the actual result. Prefer a small synthetic EML, image, or recording over personal data. Review screenshots and logs before sharing them; remove account details, API keys, OAuth files, message content, and private paths.
8+
9+
## Propose a change
10+
11+
Discuss larger changes in an issue before implementing them. Keep changes focused, explain the resulting behavior, and update the relevant documentation. Contributions to the project's own code are provided under the [MIT License](LICENSE); retain the licenses and attribution of any third-party material you add.
12+
13+
1. Follow the [Windows setup guide](docs/guides/INSTALL_BUILD.md). Use `npm ci` to preserve the locked dependency versions.
14+
2. Use an isolated workspace through `UFRIEND_DATA_DIR`; do not develop against your only copy of personal workspace data.
15+
3. Run `npm run check` and tests appropriate to the change. Run `npm test` before submitting, and report any skipped media checks. UI or native changes may also require the smoke tests described in the guide.
16+
4. Describe the problem, behavior change, validation, and remaining limitations in the pull request. Include English and Traditional Chinese UI changes where applicable.
17+
18+
Do not include credentials, OAuth downloads, personal mail, recordings, model weights, dependency folders, release packages, or test output. Keep `app/config/google-oauth.json` as the empty template. The PC model services are separate projects; their changes belong in their own repositories.
19+
20+
Build and packaging details, including FFmpeg prerequisites, are in the [installation guide](docs/guides/INSTALL_BUILD.md). A successful package build is not a substitute for workflow tests.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 breeze0305
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
<p align="center">
2+
<img src="app/assets/ufriend.png" alt="UFriend logo" width="88" height="88">
3+
</p>
4+
5+
# UFriend
6+
7+
**A Windows workspace for email, recordings, image text, and everyday writing.**
8+
9+
UFriend keeps your workspace on your computer and connects to separately configured local or cloud AI services. Review the original material alongside the result, edit it, and decide how to use it. The interface supports English and Traditional Chinese, with light, dark, and system themes.
10+
11+
**Current version: 0.1.38 · Windows x64 · Electron 44**
12+
13+
[Releases](https://github.com/breeze0305/UFriend/releases) · [Documentation](docs/README.md) · [使用手冊（繁體中文）](docs/guides/APP_README.md) · [Report an issue](https://github.com/breeze0305/UFriend/issues)
14+
15+
## Features
16+
17+
| Workflow | Available functionality |
18+
| --- | --- |
19+
| Email | Import EML files or connect Gmail; read HTML mail, manage attachments and drafts, send mail, summarize and classify messages, and schedule daily organization. |
20+
| Recordings | Import audio or video, choose a transcription language, queue or schedule jobs, jump to timestamps, and edit or export TXT and SRT transcripts. |
21+
| Captioned video | Burn timed subtitles into a new MP4 with progress and cancellation, keeping the source video. Requires the optional FFmpeg runtime. |
22+
| Image text | Import an image or read a clipboard image, run OCR, compare the source with editable text, and copy the result. Automatic clipboard capture is opt-in. |
23+
| Writing | Stream chat responses, keep separate conversations, translate text, and polish writing by purpose and tone. Optional profile context and task prompts are configurable. |
24+
| Workspace | Local persistence and recovery backups, data cleanup, diagnostics, and system tray operation. |
25+
26+
AI results need review. Mail summaries currently use Traditional Chinese, independently of the interface language. Meeting tools provide transcription and subtitles; speaker diarization and automatic meeting summaries are not implemented.
27+
28+
## Run the Windows release
29+
30+
1. Open [GitHub Releases](https://github.com/breeze0305/UFriend/releases) and download the Windows x64 release ZIP. GitHub's **Source code** archives are not runnable desktop packages.
31+
2. Extract the **entire ZIP** into a normal folder. Keep the adjacent DLLs, `resources`, `locales`, and license files with the executable.
32+
3. If another version is running, quit it from the system tray menu, then launch `UFriend.exe` from the extracted folder.
33+
4. For English, open **設定 → 一般 → 軟體介面語言**, choose **English**, and save.
34+
35+
The desktop package does not require Node.js. AI models and services are installed separately.
36+
37+
**Optional media runtime:** the public ZIP does not include the FFmpeg executable. For captioned-video export or cloud speech transcription, run `Install media runtime.cmd` in the extracted application folder. The installer downloads the pinned build from Gyan's official site and verifies its hashes. It needs 7-Zip; an already extracted package can instead be supplied through the PowerShell installer's `-From` option. See the [runtime guide](docs/development/FFMPEG_RUNTIME.md) for exact commands and paths. Local Whisper uses its own independently installed runtime.
38+
39+
Workspace data is separate from the application folder. Use the data-location control in **Settings → General** to find it. Fully quit UFriend before backing up the workspace or replacing application files.
40+
41+
## Configure AI and Gmail
42+
43+
### Local AI
44+
45+
The desktop repository contains HTTP adapters, **not model weights or model-service source code**. The following services are independent projects and are currently available by contacting the maintainer. Cloning this repository or installing a desktop release does not install them.
46+
47+
| Service | Default endpoint | Current implementation |
48+
| --- | --- | --- |
49+
| PC LLM API | `http://127.0.0.1:8765` | Qwen2.5-1.5B-Instruct Q4_K_M with llama.cpp CUDA |
50+
| PC OCR API | `http://127.0.0.1:8767` | PP-OCRv5 mobile detection and recognition on CPU |
51+
| PC Whisper API | `http://127.0.0.1:8768` | Multilingual Whisper Small with PyTorch CUDA; Base is optional |
52+
53+
Install and start each required service using its own README. In the local model settings, select PC API, save the endpoints, and test the connections. Only loopback endpoints are supported for these services. UFriend does not install, start, or stop them. See the [PC model guide](docs/guides/PC_MODELS.md) for requirements.
54+
55+
### Cloud AI
56+
57+
Configure your own compatible API endpoint, key, and text, vision, or speech model in the cloud settings. Text and OCR use the OpenAI-compatible Chat Completions format; speech requires Audio Transcriptions with segment timestamps. Compatibility varies by provider and model.
58+
59+
Text, OCR, and speech have separate defaults, and you can select a source for each task. A failed task does not automatically switch to another source. See [model sources and data flows](docs/guides/MODEL_SOURCES.md).
60+
61+
### Gmail
62+
63+
Bring your own **Google Desktop OAuth client configuration**. Enable Gmail API in your Google Cloud project, configure its consent screen and permitted users, then import the downloaded Desktop client JSON in **Settings → Email accounts → Advanced settings**. Follow the [Gmail setup guide](docs/guides/GMAIL_SETUP_GUIDE.md), then authorize your account in the system browser.
64+
65+
The repository and public release contain an empty OAuth template; no shared client or Gmail credentials are supplied. EML import and local drafts can be used without a Gmail connection. Connected mail currently supports Gmail only.
66+
67+
## Build from source
68+
69+
Use Windows x64 with Node.js 24.x, npm, Windows PowerShell 5.1, and the .NET Framework 4.x C# compiler. Electron is installed through the lockfile. The desktop itself does not require Python or CUDA; separate model services have their own requirements.
70+
71+
```powershell
72+
git clone https://github.com/breeze0305/UFriend.git
73+
cd UFriend
74+
npm ci
75+
npm run build:native
76+
```
77+
78+
Prepare the pinned FFmpeg runtime and the `UFRIEND_TEST_FFMPEG` test path as described in the [installation guide](docs/guides/INSTALL_BUILD.md) and [FFmpeg runtime guide](docs/development/FFMPEG_RUNTIME.md). Then run:
79+
80+
```powershell
81+
npm run check
82+
npm test
83+
npm start
84+
```
85+
86+
After quitting the app, create a Windows portable package without an embedded FFmpeg executable:
87+
88+
```powershell
89+
npm run package -- --without-ffmpeg
90+
```
91+
92+
For a local package using the prepared FFmpeg runtime, use `npm run package`. The output is written to `dist/UFriend-<version>/`, or a timestamped directory if that version already exists. Packaging does not run the full test suite for you. See the installation guide for isolated development data, UI smoke tests, media prerequisites, and packaging details.
93+
94+
## Architecture and data
95+
96+
```mermaid
97+
flowchart LR
98+
UI[Electron renderer] --> Main[Main process and task control]
99+
Main --> Data[Local workspace and encrypted credentials]
100+
Main --> Gmail[Gmail API]
101+
Main --> Local[Independent local LLM / OCR / speech services]
102+
Main --> Cloud[Configured cloud API]
103+
Main --> FFmpeg[Local FFmpeg process]
104+
```
105+
106+
- Mail, files, settings, and completed work are stored locally. Ordinary workspace files are not encrypted by UFriend. Credentials use Electron `safeStorage`, backed by the Windows user account.
107+
- Gmail operations connect to Google. External email images connect to their source websites. Local inference does not make every feature offline.
108+
- Cloud tasks send the necessary input to the configured endpoint. Chat includes the current conversation history; enabled profile context is included only in the applicable text tasks. Provider retention and charges depend on the provider.
109+
- Model output does not independently send mail, delete messages, create calendar events, or execute programs.
110+
111+
UGen300 integration is not implemented or verified on hardware. Device-pool timing simulations in the interface do not perform model inference. Outlook, Yahoo, and calendar integrations are also outside the current supported scope.
112+
113+
## Documentation and project files
114+
115+
- [User and developer documentation](docs/README.md)
116+
- [Model adapter contracts](app/models/README.md)
117+
- [Windows clipboard component](app/native/README.md)
118+
- [Contributing](CONTRIBUTING.md) and [security reporting](SECURITY.md)
119+
120+
`app/` contains the desktop application, `scripts/` the build and verification tools, and `tests/` the automated tests. Dependencies, release output, credentials, personal data, and model runtimes are excluded from source control.
121+
122+
## License and third-party components
123+
124+
UFriend is licensed under the [MIT License](LICENSE).
125+
126+
Third-party components retain their respective licenses. These include Electron, Lucide, DOMPurify, MailParser, Nodemailer, and OpenCC. The separately installed FFmpeg build has its own license; UFriend's MIT license does not replace it. See [third-party notices](THIRD_PARTY_NOTICES.md), the [FFmpeg runtime and source information](docs/development/FFMPEG_RUNTIME.md) and [Google asset attribution](app/assets/GOOGLE-BRANDING.md).

0 commit comments

Comments
 (0)