Skip to content
BranchesTags

Repository files navigation

ReportCraft

ReportCraft 是一个本地优先的 HTML 文档工作台，适合写周报、方案、技术笔记和 AI 辅助内容。它的书写体验尽量接近 Markdown / 飞书文档，同时底层使用 HTML，方便插入 SVG 流程图、Mermaid、表格、图片和自包含的小部件。

当前版本面向单人本地使用。

English version is available below: English

中文

核心特性

  • React + Vite + Tiptap 构建的轻量文档编辑器。
  • 像 Markdown 一样写正文，底层保存为 HTML。
  • 支持导入 Markdown、导入 HTML、导出 HTML、导出 PDF。
  • 支持打开本地工作区目录，递归扫描 .report.json 文档。
  • AI 生成内容以可拖动小部件插入，支持 SVG、HTML、Mermaid、表格和图片。
  • HTML 导入时，普通标题/正文/列表/图片保留为正文内容，内联 SVG 和 Mermaid 会自动转成小部件。
  • 图片小部件支持局部重绘入口。
  • AI Provider 和模型列表通过 .env 配置，真实 URL 和 API Key 不暴露到前端。
  • 小部件提示词模板保存在 .reportcraft/widgets/templates。
  • 内置 GitHub Pages 构建工作流。

快速开始

npm install
cp .env.example .env
npm run dev

打开：

http://127.0.0.1:5173

也可以指定本地端口：

npm run dev -- --host 127.0.0.1 --port 4173

常用命令

npm run dev      # 启动本地开发服务
npm run build    # 类型检查并构建生产包
npm test         # 运行 Vitest 测试
npm run preview  # 预览生产构建

AI Provider 配置

复制 .env.example 为 .env，然后填写本地网关或模型服务配置。

一个 provider 表示一套 URL + API Key，可以挂多个模型：

VITE_PROVIDER_1_ID=qwen-gateway
VITE_PROVIDER_1_NAME=Qwen Gateway
VITE_PROVIDER_1_MODELS=qwen3.6-plus,kimi-k2.6-ali,claude-opus-4-6-v1,gpt-image-2,doubao-seedream-5-0-lite
PROVIDER_1_BASE_URL=https://example.com/llm/your-consumer-id
PROVIDER_1_API_KEY=replace-me

如果是 DeepSeek 或其他 OpenAI-compatible 服务，通常只需要 URL、API Key、provider 名称和模型列表：

VITE_PROVIDER_2_ID=deepseek
VITE_PROVIDER_2_NAME=DeepSeek
VITE_PROVIDER_2_MODELS=deepseek-chat,deepseek-reasoner
PROVIDER_2_BASE_URL=https://api.deepseek.com
PROVIDER_2_API_KEY=replace-me

注意：

  • VITE_PROVIDER_N_* 会暴露给浏览器，只放 provider 名称、ID 和模型列表。
  • PROVIDER_N_BASE_URL 和 PROVIDER_N_API_KEY 不要加 VITE_ 前缀，它们只给本地 dev-server 代理使用。
  • 修改 .env 后需要重启 dev server。

工作区和存储

ReportCraft 可以打开一个本地目录作为工作区，并递归扫描其中的 .report.json 文件。这个能力依赖浏览器 File System Access API，推荐使用 Chrome 或 Edge。

文档保存为 JSON，核心字段是 HTML 内容和小部件数据。这样重新打开文档时，不需要重新调用 AI，也能恢复已插入的图、表、图片和 HTML 小部件。

导入和导出

  • 导入 Markdown：把 Markdown 转成编辑器 HTML。
  • 导入 HTML：读取本地 .html / .htm / .txt 文件，提取 body，清洗不安全标签和属性，再导入编辑器。
  • HTML 导入规则：正文内容作为正文保留；内联 SVG、Mermaid 代码块、旧版 artifact frame 会转成小部件。
  • 导出 HTML：导出静态 HTML 文件。
  • 导出 PDF：通过浏览器打印流程导出 PDF。

小部件模板

小部件提示词模板放在：

.reportcraft/widgets/templates

每个模板包含：

widget.json
source-prompt.md

当前模板包括：

  • bar-chart
  • bento-card
  • dynamic-island-toc
  • moving-border
  • project-showcase
  • team-section-block
  • testimonial-v2

模板索引在 src/lib/widget-templates.ts。这些模板用于约束 AI 生成自包含的 HTML / CSS / SVG，方便插入文档并稳定导出。

安全说明

  • .env 已被 Git 忽略，不应该提交真实密钥。
  • API 请求通过本地 Vite dev-server 代理，避免把 provider key 放到浏览器可见变量中。
  • 当前项目定位是单人本地使用，不是多人在线协作系统。

开发检查

提交前建议运行：

npm test
npm run build

部署

仓库包含 GitHub Pages 工作流：.github/workflows/deploy.yml。在 GitHub Pages 设置中选择 GitHub Actions，然后推送到 main 即可触发构建。

示例

示例文档：examples/weekly-report.report.json

English

ReportCraft is a local-first HTML document workspace for weekly reports, plans, technical notes, and AI-assisted writing. It keeps the editing experience close to Markdown and Feishu Docs, while using HTML underneath so diagrams, tables, images, SVG, Mermaid, and self-contained widgets can be inserted naturally.

The current version is designed for single-user local workflows.

Features

  • Lightweight document editor built with React, Vite, and Tiptap.
  • Markdown-like writing experience with HTML as the storage format.
  • Markdown import, HTML import, static HTML export, and PDF export.
  • Local workspace directory support for recursively scanning .report.json documents.
  • Draggable artifact widgets for AI-generated SVG, HTML, Mermaid, table, and image content.
  • HTML import keeps regular headings, paragraphs, lists, and images inline, while imported SVG and Mermaid blocks become widgets.
  • Image widgets expose an inpainting entry point.
  • AI providers and model lists are configured through .env.
  • Widget prompt templates live under .reportcraft/widgets/templates.
  • GitHub Pages build workflow included.

Quick Start

npm install
cp .env.example .env
npm run dev

Open:

http://127.0.0.1:5173

You can also run Vite on a specific local port:

npm run dev -- --host 127.0.0.1 --port 4173

Scripts

npm run dev      # start local dev server
npm run build    # type-check and build production assets
npm test         # run Vitest test suite
npm run preview  # preview production build

AI Provider Configuration

Copy .env.example to .env, then fill in your local gateway or model provider values.

One provider represents one URL + API key pair and can expose multiple models:

VITE_PROVIDER_1_ID=qwen-gateway
VITE_PROVIDER_1_NAME=Qwen Gateway
VITE_PROVIDER_1_MODELS=qwen3.6-plus,kimi-k2.6-ali,claude-opus-4-6-v1,gpt-image-2,doubao-seedream-5-0-lite
PROVIDER_1_BASE_URL=https://example.com/llm/your-consumer-id
PROVIDER_1_API_KEY=replace-me

For DeepSeek or other OpenAI-compatible providers, URL + API key + provider name + model list is usually enough:

VITE_PROVIDER_2_ID=deepseek
VITE_PROVIDER_2_NAME=DeepSeek
VITE_PROVIDER_2_MODELS=deepseek-chat,deepseek-reasoner
PROVIDER_2_BASE_URL=https://api.deepseek.com
PROVIDER_2_API_KEY=replace-me

Notes:

  • VITE_PROVIDER_N_* values are browser-visible, so only put provider IDs, display names, and model IDs there.
  • PROVIDER_N_BASE_URL and PROVIDER_N_API_KEY must not use the VITE_ prefix. They are used by the local dev-server proxy.
  • Restart the dev server after changing .env.

Workspace And Storage

ReportCraft can open a local directory as a workspace and recursively scan .report.json files. This relies on the browser File System Access API, so Chrome or Edge is recommended.

Documents are saved as JSON with HTML content and widget data. Reopening a document restores generated diagrams, tables, images, and HTML widgets without calling AI again.

Import And Export

  • 导入 Markdown: Convert Markdown into editor HTML.
  • 导入 HTML: Read local .html, .htm, or .txt files, extract the body, sanitize unsafe tags and attributes, then import the result.
  • HTML import rule: regular document content stays inline; inline SVG, Mermaid code blocks, and legacy artifact frames are converted into widgets.
  • 导出 HTML: Export a static HTML file.
  • 导出 PDF: Export through the browser print flow.

Widget Templates

Widget prompt templates live in:

.reportcraft/widgets/templates

Each template contains:

widget.json
source-prompt.md

Current templates:

  • bar-chart
  • bento-card
  • dynamic-island-toc
  • moving-border
  • project-showcase
  • team-section-block
  • testimonial-v2

The lightweight template index is stored in src/lib/widget-templates.ts. Templates guide AI output toward self-contained HTML, CSS, and SVG that can be inserted into documents and exported reliably.

Security Notes

  • .env is ignored by Git and should never contain committed real keys.
  • API requests are proxied through the local Vite dev server so provider keys do not need to be placed in browser-visible variables.
  • The current app is intended for local single-user workflows, not hosted multi-user collaboration.

Development Checks

Before publishing changes:

npm test
npm run build

Deployment

The repository includes a GitHub Pages workflow at .github/workflows/deploy.yml. Configure GitHub Pages to use GitHub Actions, then push to main.

Example

Example document: examples/weekly-report.report.json

About

汇报专用，原生html- md文档，直接修改你的html

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages