Skip to content

Commit b322443

Browse files
ZengLiangYiZengLiangYi
committed
docs: refresh site and PKM metadata
1 parent 8561ce7 commit b322443

30 files changed

Lines changed: 515 additions & 354 deletions

‎README.md‎

Lines changed: 61 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,20 @@
44

55
# ChatCrystal
66

7-
**Turn your AI conversations into searchable knowledge**
7+
**Local-first AI PKM for coding conversations**
88

99
[![GitHub release](https://img.shields.io/github/v/release/ZengLiangYi/ChatCrystal?style=flat-square)](https://github.com/ZengLiangYi/ChatCrystal/releases)
1010
[![npm](https://img.shields.io/npm/v/chatcrystal?style=flat-square)](https://www.npmjs.com/package/chatcrystal)
1111
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)
1212
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
1313
[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey?style=flat-square)](#)
14-
[![Website](https://img.shields.io/badge/website-ChatCrystal-5A5FD6?style=flat-square)](https://zengliangyi.github.io/ChatCrystal/)
14+
[![Website](https://img.shields.io/badge/website-ChatCrystal-B8584B?style=flat-square)](https://zengliangyi.github.io/ChatCrystal/)
1515

16-
English | [简体中文](README.zh-CN.md)
16+
[Website](https://zengliangyi.github.io/ChatCrystal/) ·
17+
[Download Desktop](https://github.com/ZengLiangYi/ChatCrystal/releases) ·
18+
[npm](https://www.npmjs.com/package/chatcrystal) ·
19+
[Docs](docs/USER_GUIDE.md) ·
20+
[简体中文](README.zh-CN.md)
1721

1822
</div>
1923

@@ -25,9 +29,9 @@ English | [简体中文](README.zh-CN.md)
2529

2630
<br>
2731

28-
ChatCrystal collects conversations from AI coding tools, distills them into structured notes with LLMs, and builds a local searchable knowledge base from your real problem-solving history.
32+
ChatCrystal is a local-first AI PKM app for developers who solve real problems with Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot.
2933

30-
Supported sources: Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot.
34+
It turns scattered AI coding conversations into structured notes, semantic search, a tag knowledge graph, Markdown exports, and MCP memory your agents can reuse. If this fits your workflow, a star helps more builders find a private, local-first way to keep their AI work memory.
3135

3236
## Quick Start
3337

@@ -47,51 +51,7 @@ Then open http://localhost:3721 in your browser.
4751

4852
### Docker Cloud
4953

50-
The default Compose deployment runs only the ChatCrystal service. It stores data in the `chatcrystal-data` volume mounted at `/data` inside the container.
51-
52-
```bash
53-
git clone https://github.com/ZengLiangYi/ChatCrystal.git
54-
cd ChatCrystal
55-
docker compose up -d
56-
```
57-
58-
The default `docker-compose.yml` pulls `ghcr.io/zengliangyi/chatcrystal:latest` from GitHub Container Registry. Set `CHATCRYSTAL_IMAGE_TAG` to pin a published version. To build from source instead, run `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`.
59-
60-
To update an existing Docker deployment, run `docker compose pull && docker compose up -d`. Maintainers only: after the first GHCR publish, make the `ghcr.io/zengliangyi/chatcrystal` package public in GitHub Packages; the release workflow verifies anonymous pull access before passing.
61-
62-
Compose binds ChatCrystal to `0.0.0.0:3721` by default so other devices can reach the cloud core through the host IP. Set `CHATCRYSTAL_HOST_PORT` to change the host port, or set `BIND_ADDRESS=127.0.0.1` when a local-only reverse proxy fronts it. For public cloud access, an HTTPS reverse proxy is recommended for safer token transport.
63-
64-
On Windows Docker Desktop, a published port may still need extra host networking configuration before it is reachable through the host LAN IP. For cloud-mode testing, verify `http://<host-ip>:<host-port>/api/health` from the client device first; if it cannot connect, configure Windows port forwarding/firewall rules or deploy the cloud core on a real remote host.
65-
66-
On first start without `CHATCRYSTAL_API_TOKEN`, open the Web UI and enter the setup code printed in container logs or stored at `/data/setup-code`, then choose one shared API token for your devices.
67-
68-
To rotate or reset the Docker cloud token:
69-
70-
```bash
71-
# If you still know the current token, rotate it online.
72-
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
73-
crystal connect https://chatcrystal.example.com --token "new-long-token-at-least-16-chars"
74-
75-
# If you forgot the token and did not set CHATCRYSTAL_API_TOKEN, reset stored auth in the container.
76-
docker compose exec chatcrystal crystal token reset --yes
77-
docker compose logs chatcrystal --tail=80
78-
docker compose exec chatcrystal cat /data/setup-code
79-
```
80-
81-
If your deployment sets `CHATCRYSTAL_API_TOKEN`, that environment variable is the active token source. Change it in your `.env` or Compose environment and recreate the container with `docker compose up -d --force-recreate`.
82-
83-
To use an existing Ollama or external API, configure provider URLs in the Web UI or environment. In Docker, `localhost` means inside the container; use `CHATCRYSTAL_DOCKER_LLM_BASE_URL` and `CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL` for Compose-time provider URL overrides. Docker Desktop can reach host Ollama at `http://host.docker.internal:11434`, or you can use a remote HTTPS/OpenAI-compatible API.
84-
85-
### Import from a Device into the Cloud Instance
86-
87-
Install or run the CLI on the device that has Claude Code, Cursor, Codex CLI, Trae, or GitHub Copilot history:
88-
89-
```bash
90-
crystal connect https://chatcrystal.example.com --token "your-long-token"
91-
crystal import --yes
92-
```
93-
94-
The CLI scans local histories, parses them locally, and uploads normalized conversations to the cloud. The cloud never scans your local filesystem. Imported conversations are not summarized automatically; use the Web UI or `crystal summarize --all` when you are ready. HTTPS is recommended for cloud access, but HTTP works when that is the deployment you choose.
54+
Prefer self-hosting ChatCrystal for multiple devices? See [Docker Cloud Deployment](#docker-cloud-deployment) after the product overview.
9555

9656
## What It Does
9757

@@ -174,8 +134,57 @@ Development server ports:
174134

175135
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for architecture, testing, build, and release details.
176136

177-
## Wechat
178-
Wechat: Yizel1
137+
## Docker Cloud Deployment
138+
139+
The default Compose deployment runs only the ChatCrystal service. It stores data in the `chatcrystal-data` volume mounted at `/data` inside the container.
140+
141+
```bash
142+
git clone https://github.com/ZengLiangYi/ChatCrystal.git
143+
cd ChatCrystal
144+
docker compose up -d
145+
```
146+
147+
The default `docker-compose.yml` pulls `ghcr.io/zengliangyi/chatcrystal:latest` from GitHub Container Registry. Set `CHATCRYSTAL_IMAGE_TAG` to pin a published version. To build from source instead, run `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`.
148+
149+
To update an existing Docker deployment, run `docker compose pull && docker compose up -d`. Maintainers only: after the first GHCR publish, make the `ghcr.io/zengliangyi/chatcrystal` package public in GitHub Packages; the release workflow verifies anonymous pull access before passing.
150+
151+
Compose binds ChatCrystal to `0.0.0.0:3721` by default so other devices can reach the cloud core through the host IP. Set `CHATCRYSTAL_HOST_PORT` to change the host port, or set `BIND_ADDRESS=127.0.0.1` when a local-only reverse proxy fronts it. For public cloud access, an HTTPS reverse proxy is recommended for safer token transport.
152+
153+
On Windows Docker Desktop, a published port may still need extra host networking configuration before it is reachable through the host LAN IP. For cloud-mode testing, verify `http://<host-ip>:<host-port>/api/health` from the client device first; if it cannot connect, configure Windows port forwarding/firewall rules or deploy the cloud core on a real remote host.
154+
155+
On first start without `CHATCRYSTAL_API_TOKEN`, open the Web UI and enter the setup code printed in container logs or stored at `/data/setup-code`, then choose one shared API token for your devices.
156+
157+
To rotate or reset the Docker cloud token:
158+
159+
```bash
160+
# If you still know the current token, rotate it online.
161+
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
162+
crystal connect https://chatcrystal.example.com --token "new-long-token-at-least-16-chars"
163+
164+
# If you forgot the token and did not set CHATCRYSTAL_API_TOKEN, reset stored auth in the container.
165+
docker compose exec chatcrystal crystal token reset --yes
166+
docker compose logs chatcrystal --tail=80
167+
docker compose exec chatcrystal cat /data/setup-code
168+
```
169+
170+
If your deployment sets `CHATCRYSTAL_API_TOKEN`, that environment variable is the active token source. Change it in your `.env` or Compose environment and recreate the container with `docker compose up -d --force-recreate`.
171+
172+
To use an existing Ollama or external API, configure provider URLs in the Web UI or environment. In Docker, `localhost` means inside the container; use `CHATCRYSTAL_DOCKER_LLM_BASE_URL` and `CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL` for Compose-time provider URL overrides. Docker Desktop can reach host Ollama at `http://host.docker.internal:11434`, or you can use a remote HTTPS/OpenAI-compatible API.
173+
174+
### Import from a Device into the Cloud Instance
175+
176+
Install or run the CLI on the device that has Claude Code, Cursor, Codex CLI, Trae, or GitHub Copilot history:
177+
178+
```bash
179+
crystal connect https://chatcrystal.example.com --token "your-long-token"
180+
crystal import --yes
181+
```
182+
183+
The CLI scans local histories, parses them locally, and uploads normalized conversations to the cloud. The cloud never scans your local filesystem. Imported conversations are not summarized automatically; use the Web UI or `crystal summarize --all` when you are ready. HTTPS is recommended for cloud access, but HTTP works when that is the deployment you choose.
184+
185+
## Contact Us
186+
187+
<img src="docs/wechat.png" alt="WeChat QR code" width="220" />
179188

180189
## License
181190

‎README.zh-CN.md‎

Lines changed: 61 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,20 @@
44

55
# ChatCrystal
66

7-
**从 AI 对话中提炼可搜索的知识库**
7+
**面向 AI 编程对话的本地优先 PKM**
88

99
[![GitHub release](https://img.shields.io/github/v/release/ZengLiangYi/ChatCrystal?style=flat-square)](https://github.com/ZengLiangYi/ChatCrystal/releases)
1010
[![npm](https://img.shields.io/npm/v/chatcrystal?style=flat-square)](https://www.npmjs.com/package/chatcrystal)
1111
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)
1212
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
1313
[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey?style=flat-square)](#)
14-
[![Website](https://img.shields.io/badge/website-ChatCrystal-5A5FD6?style=flat-square)](https://zengliangyi.github.io/ChatCrystal/zh/)
14+
[![Website](https://img.shields.io/badge/website-ChatCrystal-B8584B?style=flat-square)](https://zengliangyi.github.io/ChatCrystal/zh/)
1515

16-
[English](README.md) | 简体中文
16+
[官网](https://zengliangyi.github.io/ChatCrystal/zh/) ·
17+
[下载桌面版](https://github.com/ZengLiangYi/ChatCrystal/releases) ·
18+
[npm](https://www.npmjs.com/package/chatcrystal) ·
19+
[文档](docs/USER_GUIDE.zh-CN.md) ·
20+
[English](README.md)
1721

1822
</div>
1923

@@ -25,9 +29,9 @@
2529

2630
<br>
2731

28-
ChatCrystal 会采集 AI 编程工具中的本地对话，用 LLM 提炼为结构化笔记，并基于真实问题解决过程建立一个可搜索的本地知识库。
32+
ChatCrystal 是一个本地优先的 AI PKM / 个人知识管理工具，面向每天使用 Claude Code、Cursor、Codex CLI、Trae、GitHub Copilot 解决问题的开发者。
2933

30-
支持的数据源：Claude Code、Cursor、Codex CLI、Trae、GitHub Copilot。
34+
它会把散落在 AI 编程工具里的对话沉淀为结构化笔记、语义搜索、标签知识图谱、Markdown 备份和可供 Agent 复用的 MCP 记忆。如果它也解决了你的工作流痛点，Star 可以帮助更多开发者发现这种私有、本地优先的 AI 工作记忆方式。
3135

3236
## 快速开始
3337

@@ -47,51 +51,7 @@ crystal import
4751

4852
### Docker 云端部署
4953

50-
默认 Compose 只运行 ChatCrystal 一个服务。数据保存在 `chatcrystal-data` volume 中，并挂载到容器内 `/data`。
51-
52-
```bash
53-
git clone https://github.com/ZengLiangYi/ChatCrystal.git
54-
cd ChatCrystal
55-
docker compose up -d
56-
```
57-
58-
默认 `docker-compose.yml` 会从 GitHub Container Registry 拉取 `ghcr.io/zengliangyi/chatcrystal:latest`。如果要固定已发布版本，设置 `CHATCRYSTAL_IMAGE_TAG`。如果要从源码本地构建，使用 `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`。
59-
60-
如果要更新已有 Docker 部署，运行 `docker compose pull && docker compose up -d`。维护者注意：GHCR 首次发布后，需要在 GitHub Packages 中将 `ghcr.io/zengliangyi/chatcrystal` 设为 Public；发布 workflow 会验证匿名拉取权限，未公开时不会通过。
61-
62-
Compose 默认绑定到宿主机 `0.0.0.0:3721`，这样局域网设备可以通过宿主机 IP 访问云端核心。如需调整宿主机端口，设置 `CHATCRYSTAL_HOST_PORT`；如果只想让本机反向代理访问，可设置 `BIND_ADDRESS=127.0.0.1`。如果要公网访问，请在前面放一个 HTTPS 反向代理，并让 CLI / 浏览器连接 HTTPS 地址。不要让 bearer token 走明文 HTTP。
63-
64-
在 Windows Docker Desktop 上，published port 可能仍需要额外宿主机网络配置，才能通过宿主机局域网 IP 访问。云端模式测试时，请先在客户端设备上验证 `http://<host-ip>:<host-port>/api/health` 是否能连通；如果不能连通，需要配置 Windows 端口转发/防火墙规则，或把云端核心部署到真正的远程主机。
65-
66-
首次启动且没有设置 `CHATCRYSTAL_API_TOKEN` 时，打开 Web UI，输入容器日志或 `/data/setup-code` 中的 setup code，然后设置一个供所有设备共享的 API token。
67-
68-
Docker 云端 token 的轮换和重置方式如下：
69-
70-
```bash
71-
# 如果还知道当前 token，可以在线轮换。
72-
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
73-
crystal connect https://chatcrystal.example.com --token "new-long-token-at-least-16-chars"
74-
75-
# 如果忘记 token，且没有设置 CHATCRYSTAL_API_TOKEN，可以在容器内重置 stored auth。
76-
docker compose exec chatcrystal crystal token reset --yes
77-
docker compose logs chatcrystal --tail=80
78-
docker compose exec chatcrystal cat /data/setup-code
79-
```
80-
81-
如果部署时设置了 `CHATCRYSTAL_API_TOKEN`，实际生效的 token 来自环境变量，而不是 `/data/auth.json`。这时需要修改 `.env` 或 Compose 环境变量，然后用 `docker compose up -d --force-recreate` 重建容器。
82-
83-
如果使用已有 Ollama 或外部 API，可在 Web UI 或环境变量中配置 provider URL。在 Docker 中，`localhost` 指向容器内部；Compose 场景请用 `CHATCRYSTAL_DOCKER_LLM_BASE_URL` 和 `CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL` 覆盖 provider URL。Docker Desktop 上访问宿主机 Ollama 可用 `http://host.docker.internal:11434`，也可以使用远程 HTTPS / OpenAI-compatible API。
84-
85-
### 从本机设备导入到云端实例
86-
87-
在保存 Claude Code、Cursor、Codex CLI、Trae 或 GitHub Copilot 历史记录的设备上安装或运行 CLI：
88-
89-
```bash
90-
crystal connect https://chatcrystal.example.com --token "your-long-token"
91-
crystal import --yes
92-
```
93-
94-
CLI 会在本机扫描并解析历史记录，然后把标准化后的对话上传到云端。云端不会扫描你的本机文件系统。导入的对话不会自动生成摘要；准备好后再通过 Web UI 或 `crystal summarize --all` 批量生成。默认情况下，CLI 会拒绝把 ChatCrystal API token 发送到非本机 `http://` 地址；云端访问请使用 HTTPS。
54+
想把 ChatCrystal 自托管给多台设备使用？完整说明见后文的 [Docker 云端部署](#docker-云端部署-1)。
9555

9656
## 它能做什么
9757

@@ -174,8 +134,57 @@ npm run dev
174134

175135
架构、测试、构建和发布说明见[开发者指南](docs/DEVELOPMENT.zh-CN.md)。
176136

177-
## 欢迎提问
178-
微信号: Yizel1
137+
## Docker 云端部署
138+
139+
默认 Compose 只运行 ChatCrystal 一个服务。数据保存在 `chatcrystal-data` volume 中，并挂载到容器内 `/data`。
140+
141+
```bash
142+
git clone https://github.com/ZengLiangYi/ChatCrystal.git
143+
cd ChatCrystal
144+
docker compose up -d
145+
```
146+
147+
默认 `docker-compose.yml` 会从 GitHub Container Registry 拉取 `ghcr.io/zengliangyi/chatcrystal:latest`。如果要固定已发布版本，设置 `CHATCRYSTAL_IMAGE_TAG`。如果要从源码本地构建，使用 `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build`。
148+
149+
如果要更新已有 Docker 部署，运行 `docker compose pull && docker compose up -d`。维护者注意：GHCR 首次发布后，需要在 GitHub Packages 中将 `ghcr.io/zengliangyi/chatcrystal` 设为 Public；发布 workflow 会验证匿名拉取权限，未公开时不会通过。
150+
151+
Compose 默认绑定到宿主机 `0.0.0.0:3721`，这样局域网设备可以通过宿主机 IP 访问云端核心。如需调整宿主机端口，设置 `CHATCRYSTAL_HOST_PORT`；如果只想让本机反向代理访问，可设置 `BIND_ADDRESS=127.0.0.1`。如果要公网访问，请在前面放一个 HTTPS 反向代理，并让 CLI / 浏览器连接 HTTPS 地址。不要让 bearer token 走明文 HTTP。
152+
153+
在 Windows Docker Desktop 上，published port 可能仍需要额外宿主机网络配置，才能通过宿主机局域网 IP 访问。云端模式测试时，请先在客户端设备上验证 `http://<host-ip>:<host-port>/api/health` 是否能连通；如果不能连通，需要配置 Windows 端口转发/防火墙规则，或把云端核心部署到真正的远程主机。
154+
155+
首次启动且没有设置 `CHATCRYSTAL_API_TOKEN` 时，打开 Web UI，输入容器日志或 `/data/setup-code` 中的 setup code，然后设置一个供所有设备共享的 API token。
156+
157+
Docker 云端 token 的轮换和重置方式如下：
158+
159+
```bash
160+
# 如果还知道当前 token，可以在线轮换。
161+
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
162+
crystal connect https://chatcrystal.example.com --token "new-long-token-at-least-16-chars"
163+
164+
# 如果忘记 token，且没有设置 CHATCRYSTAL_API_TOKEN，可以在容器内重置 stored auth。
165+
docker compose exec chatcrystal crystal token reset --yes
166+
docker compose logs chatcrystal --tail=80
167+
docker compose exec chatcrystal cat /data/setup-code
168+
```
169+
170+
如果部署时设置了 `CHATCRYSTAL_API_TOKEN`，实际生效的 token 来自环境变量，而不是 `/data/auth.json`。这时需要修改 `.env` 或 Compose 环境变量，然后用 `docker compose up -d --force-recreate` 重建容器。
171+
172+
如果使用已有 Ollama 或外部 API，可在 Web UI 或环境变量中配置 provider URL。在 Docker 中，`localhost` 指向容器内部；Compose 场景请用 `CHATCRYSTAL_DOCKER_LLM_BASE_URL` 和 `CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL` 覆盖 provider URL。Docker Desktop 上访问宿主机 Ollama 可用 `http://host.docker.internal:11434`，也可以使用远程 HTTPS / OpenAI-compatible API。
173+
174+
### 从本机设备导入到云端实例
175+
176+
在保存 Claude Code、Cursor、Codex CLI、Trae 或 GitHub Copilot 历史记录的设备上安装或运行 CLI：
177+
178+
```bash
179+
crystal connect https://chatcrystal.example.com --token "your-long-token"
180+
crystal import --yes
181+
```
182+
183+
CLI 会在本机扫描并解析历史记录，然后把标准化后的对话上传到云端。云端不会扫描你的本机文件系统。导入的对话不会自动生成摘要；准备好后再通过 Web UI 或 `crystal summarize --all` 批量生成。默认情况下，CLI 会拒绝把 ChatCrystal API token 发送到非本机 `http://` 地址；云端访问请使用 HTTPS。
184+
185+
## 联系我
186+
187+
<img src="docs/wechat.png" alt="微信二维码" width="220" />
179188

180189
## License
181190

‎docs/screenshots/zh-CN/dashboard.png‎

209 KB
Loading

‎docs/wechat.png‎

252 KB
Loading

0 commit comments

Comments
 (0)