Write clearly. Review deeply.

---

HelpSoft là gì

Công cụ ghi chú cá nhân chạy trên trình duyệt, dựng từ SiYuan v3.8.1 (afa823b) và giữ nguyên nhân Go lẫn trình soạn thảo Protyle. Bản fork này dùng riêng cho một người, đặt tại helpsoft.pandev00.com.

Ca sử dụng chính là vòng rà soát tài liệu: Claude đẩy bản thảo sang qua MCP → người dùng đọc và ghi chú thích trên điện thoại → Claude lấy chú thích về và sửa.

Chi tiết bản fork khác bản gốc chỗ nào: FORK.md.

Thương hiệu

Bộ nhận diện riêng — HelpSoft Brand Kit B ("Living Archive"), nằm ở customizations/helpsoft-brand-kit-b/.

Màu	Mã	Dùng cho
Ink	#151A1F	chữ, biểu tượng trên nền sáng
Paper	#F5F1E8	nền sáng, biểu tượng đảo trên nền tối
Review teal	#32B8B6	nét nhấn của biểu tượng, trạng thái rà soát
Highlight amber	#E7B55C	nhấn phụ
Muted	#536168	chữ phụ

• SVG là bản gốc. PNG/WebP chỉ sinh ra cho những chỗ bắt buộc dùng ảnh raster.
• Chỗ nào dùng tệp nào: 05-guidelines/integration-map.txt. Token màu: brand-tokens.css · brand-tokens.json.
• Đã thay vào ứng dụng: biểu tượng desktop, biểu tượng PWA + maskable, favicon (.ico nhiều kích cỡ), logo màn hình khởi động, hình chờ. Nhật ký: plans/journals/2026-08-21-integrate-helpsoft-brand-kit-b.md.
• Wordmark dùng phông hệ thống (Arial/Helvetica) nên không phải nhúng hay mua phông. Điều kiện dùng: usage-rights.txt.

Định danh tương thích của bản gốc (org.b3log.siyuan, giao thức siyuan://, web+siyuan) giữ nguyên — đổi là hỏng dữ liệu và liên kết cũ.

Khác gì bản gốc

Nhân + trình soạn thảo	Giữ nguyên. Đây là lý do chọn SiYuan
Giao diện	Chủ đề mặc định Asri; tab MCP Server đứng đầu Settings; bỏ tab Account & Sync; tắt popup chào mừng
Thêm	docker-compose.yml · .env.example · deploy/ (nginx, sao lưu, runbook) · run-local.sh
Đã xoá	Đóng gói desktop/Windows, ảnh bìa, phông, sổ tay kèm sẵn, CI của upstream, pandoc — kho từ 285 MB xuống 52 MB
Nền tảng nhắm tới	Ubuntu x86_64 24.04 (Docker trên VPS) và macOS arm64 (máy phát triển)

Chạy trên máy

cd app    && pnpm install && pnpm run build
cd kernel && CGO_ENABLED=1 go build -tags "fts5 sqlcipher" -o kernel-local .

./run-local.sh          # bật — http://127.0.0.1:6807/
./run-local.sh status
./run-local.sh stop

Cổng 6807 và thư mục dữ liệu ~/SiYuanFork cố ý khác SiYuan bản desktop (cổng 6806). Hai nhân không được dùng chung thư mục dữ liệu — hai chỉ mục cùng ghi một chỗ sẽ hỏng dữ liệu. Đổi bằng biến SIYUAN_FORK_PORT / SIYUAN_FORK_WORKSPACE.

Đưa lên VPS

Docker Compose; nginx của VPS đứng ngoài làm reverse proxy.

git clone https://github.com/sagozen/helpsoft.git /opt/helpsoft
cd /opt/helpsoft
cp .env.example .env && nano .env      # PUID, PGID, TZ, HELPSOFT_WORKSPACE, SIYUAN_ACCESS_AUTH_CODE
docker compose up -d --build

Không cần cài Go hay Node lên VPS — dựng hết trong container.

Ba điều dễ vấp nhất:

1. Đặt mật khẩu khoá màn hình trước khi mở tên miền. Nhân từ chối truy cập từ xa khi chưa có mật khẩu, nên lần đầu phải vào qua đường hầm SSH.
2. nginx phải cấu hình tay ba thứ: nâng cấp WebSocket cho /ws, client_max_body_size (mặc định 1 MB — dán ảnh là dính 413), tắt bộ đệm cho /mcp. Mẫu: deploy/nginx-helpsoft.conf.
3. Không đặt biến SIYUAN_ACCESS_AUTH_CODE_BYPASS — nó bỏ qua toàn bộ kiểm tra mật khẩu.

Container publish ra 127.0.0.1:6806, không phải 0.0.0.0: ảnh đặt RUN_IN_CONTAINER=true nên nhân bind 0.0.0.0 bên trong container, ràng địa chỉ trong docker-compose.yml là lớp chặn duy nhất giữ dịch vụ khỏi lộ ra Internet.

Runbook đầy đủ: deploy/deploy-vps.md · Sao lưu: deploy/backup-runbook.md.

MCP

Nhân phục vụ MCP tại POST|GET /mcp, yêu cầu xác thực và vai quản trị. Bật và lấy thông tin kết nối trong Settings → MCP Server (tab đầu tiên, hoặc bấm nút MCP trên thanh trên cùng).

Bộ công cụ phủ đọc, sửa, tìm kiếm, truy vấn SQL, lịch sử và liên kết ngược. Chưa có công cụ chú thích — đang làm, xem docs/_product/roadmap.md.

Dòng lệnh

Nhân cũng là CLI (HelpSoft-Kernel), đọc thẳng dữ liệu workspace, không cần server đang chạy. Trên máy phát triển gọi bằng ./kernel/kernel-local:

./kernel/kernel-local notebook list -w ~/SiYuanFork
./kernel/kernel-local search "từ khoá" -w ~/SiYuanFork -f json
./kernel/kernel-local search "cụm từ" --asset --ext pdf -w ~/SiYuanFork
./kernel/kernel-local export md --id <block-id> -w ~/SiYuanFork

Nhóm	Lệnh
Sổ tay & tài liệu	notebook, document, dailynote
Nội dung	block, attr, outline
Siêu dữ liệu	tag, bookmark, template
Truy vấn	search, sql
Tham chiếu	ref
Xuất / nhập	export, import, inbox
Dữ liệu	repo, history, sync
Tệp	asset, file
Cơ sở dữ liệu	database
Máy chủ	serve
Workspace & hệ thống	workspace, system

--help để xem cây lệnh đầy đủ. -f json cho đầu ra hợp với script (mặc định -f table). Phần lớn lệnh có sửa dữ liệu đều nhận --dry-run.

Tài liệu

FORK.md	Fork khác bản gốc chỗ nào, đã xoá gì, hệ quả cần biết
deploy/	Runbook triển khai VPS, nginx, sao lưu lên R2
docs/_product/	PRD và roadmap của bản fork
docs/_upstream/	Tài liệu gốc SiYuan: API, định dạng .sy, workspace, sổ tay mã hoá

Hạn chế đã biết

• Xuất Word chưa chạy — cả trên Docker lẫn trên máy, vì hai lý do khác nhau (xem FORK.md). Cách vòng: xuất Markdown rồi pandoc x.md -o x.docx.
• Kéo-thả tệp vào ghi chú là thứ bản gốc chỉ làm cho Electron nên bản trình duyệt chưa có.
• Không có ứng dụng desktop/di động, không có đồng bộ đám mây, không có tài khoản.

Giấy phép & ghi công

• HelpSoft kế thừa AGPL-3.0 của SiYuan. Nghĩa vụ công bố mã nguồn kích hoạt khi người khác dùng dịch vụ qua mạng.
• Engine markdown Lute theo MulanPSL-2.0.
• Chủ đề Asri theo giấy phép của chính nó.
• Bộ nhận diện HelpSoft làm riêng cho dự án này; SiYuan và các nhãn hiệu của B3log không thuộc bộ nhận diện đó.

Cảm ơn SiYuan và những người đóng góp cho nó — toàn bộ phần lõi của HelpSoft là công của họ.