# git-notes

**Repository Path**: u32-cn/git-notes

## Basic Information

- **Project Name**: git-notes
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Git笔记（git-notes）

开源地址：<https://github.com/u32-cn/git-notes> · 官网地址：<https://git-notes.u32.cn/>

![数据的掌控权必须留在本地](web/assets/help-syc.jpg)

> **"AI 时代，数据的掌控权必须留在本地，不被任何一家 SaaS 供应商绑定。"**

本地 git 仓库架构的微笔记信息流。**两种模式**：

- **仅本机使用**：`git init` 本地仓库，零配置零依赖（只需 git），数据只在 `~/.git-notes/repo`
- **绑定远端**：任意 git 服务器（SSH/HTTPS/本地路径均可，地址自己填），自动 `fetch + rebase/merge + push` 多设备同步

## 应用截图

<img src="docs/screenshots/screenshot-win-main.png" alt="Windows 桌面版" width="100%" />

*Windows 桌面版：信息流 + AI 助手侧栏*

<table>
<tr>
<td width="25%" align="center"><img src="docs/screenshots/screenshot-android-feed.jpg" alt="Android 信息流" /><br><b>信息流</b></td>
<td width="25%" align="center"><img src="docs/screenshots/screenshot-android-ai.jpg" alt="Android AI 助手" /><br><b>AI 助手</b></td>
<td width="25%" align="center"><img src="docs/screenshots/screenshot-android-settings.jpg" alt="Android 设置" /><br><b>同步设置</b></td>
<td width="25%" align="center"><img src="docs/screenshots/screenshot-android-help.jpg" alt="Android 帮助" /><br><b>帮助页</b></td>
</tr>
</table>

*Android（APK 与桌面版同一套界面，多端同步）*

数据格式沿用 `micro/YYYY/MM/YYYYMMDD-HHMMSS.md`（front matter: type/tags/created/images/files）与 `settings/tags.json`，commit 规范 `micro: add|update|delete <摘要>` / `settings: add|remove tag <名>`。支持配图（≤9 张）与**任意附件**（单个 ≤10MB、每帖 ≤9 个，原始文件名保留在 `files:` 字段；附件经 `/media/` 一律以下载形式给出）。

## 特点

**数据留在本地，通过远端 git 库同步，不被任何一家 SaaS 供应商绑定。**

<table>
<tr>
<td width="33%" align="center"><img src="web/assets/help-store-free.jpg" alt="存储自由" /><br><b>存储自由，随时搬家</b><br>远端可自建或放 GitHub / Gitee / 阿里云云效（均免费），换地址即搬家，零锁定</td>
<td width="33%" align="center"><img src="web/assets/help-ai-friendly.jpg" alt="AI 友好" /><br><b>数据在本地，AI 更友好</b><br>内置 AI 助手直接读写本地笔记：检索、批量整理、找回历史版本</td>
<td width="33%" align="center"><img src="web/assets/help-git-history.jpg" alt="git 历史" /><br><b>全量历史，随时追溯</b><br>每步操作都是 git 提交，误删可找回，任何版本可回看</td>
</tr>
</table>

更多介绍见[帮助文档](docs/help.md)。

## 使用

```bash
npm i -g @u32/git-notes   # 从 npm 安装（或源码安装：cd web && npm i -g .）
git-notes                 # 启动并打开 http://127.0.0.1:8644；status / stop / -v / help
```

- 依赖：Node ≥ 18、系统 PATH 有 git（SSH 远端另需 ssh-keygen，Git for Windows 自带）。
- 安卓端：APK（Kotlin + JGit 移植同一套服务与界面，功能与 PC 版一致、可多端同步），见 `android/README.md`。
- 首次打开页面出引导页：**「仅本机使用」**一键开始；或 **「从远端仓库克隆」**（填仓库地址；SSH 地址时程序自动生成专用 ed25519 密钥，把公钥贴到 git 服务器后重试克隆）。
- 设置页「绑定远端」：随时把仅本机模式升级为多设备同步——填地址 → 探测 → 确认。远端为空仓则直接推送本地历史；远端已有笔记则提示合并预览（本地提交叠加到远端历史之上）；也可「解绑」回到仅本机（本地与远端数据都不动）。
- 命令行笔记操作子命令：`list / add / edit / rm / pin / show / search / tags / sync / log / doctor`（`git-notes help` 查看用法），供人或外部 AI 工具读写，写操作提交信息带 `[ai]` 审计标记；远端管理子命令：`key`（输出 SSH 公钥）/ `bind <地址>`（绑定远端并同步）/ `unbind`（解绑回仅本机）；历史与冲突子命令：`restore`（查看/恢复历史版本）/ `changes`（未提交改动清单）/ `remote`（远端状态）/ `diff` / `force-push`（本地为准）/ `reset-to-remote`（远端为准）；初始化子命令：`init --local` / `init <远端地址>`（无浏览器环境用）。

### 外部 AI 工具接入

**主推方式（对外部 AI 工具统一使用这句话）**：

```
请读取git-notes.u32.cn/llms.txt，帮我安装Git笔记和它的技能。
```

AI 工具读取 [llms.txt](https://git-notes.u32.cn/llms.txt) 后会找到技能说明书 [SKILL.md](https://git-notes.u32.cn/skill/SKILL.md)，按其中步骤安装 npm 包 `@u32/git-notes` 并按规则使用 CLI 读写笔记。

其余方式任选：

```bash
# 方式一：GitHub 安装（装成 AI 工具的本地技能）
npx skills add u32-cn/git-notes -g
```

**方式二：直读模式（不装 skill，零拷贝）**：在 AI 工具的 AGENTS.md / 系统提示词里写一行指针，AI 需要时直接读网站上的 SKILL.md 并照做：

```
可用技能 git-notes：先读 https://git-notes.u32.cn/skill/SKILL.md，按其中步骤安装并操作笔记
```

取舍：方式一获得自动发现与渐进加载（装到 `~/.agents/skills/` 等标准目录的是快照，技能更新后重跑安装即更新）；直读模式零拷贝、官网发布即最新，但指针每个工具写一次、该行常驻注入上下文。

## 同步与冲突策略

- 写操作（发布/编辑/删除/改标签）= 先同步拉齐远端 → 本地写文件 → 单个 commit → push（被拒自动整合重试 ≤3 次）。
- 整合策略：**优先 rebase，其次 merge（--allow-unrelated-histories）**；仍冲突则进入「冲突待处理」，页面提供**「强制推送（本地为准）」**（覆盖远端历史，远端本地没有的提交将丢失，按钮有二次确认）；AI 分析处理为后续版本。
- 全库搜索：服务端扫本地仓库全部笔记，词 AND 语义、命中高亮，毫秒级；**支持拼音与首字母**（如 `biji`/`bj` 命中「笔记」，内置 8105 常用字拼音表）。
- 分支：**定死 `main`，不可改**（2026-10-27 起，设置页无分支项）。本地 main ↔ 远端 origin/main；远端没有 main（空仓或只有 master 等旧分支）时绑定/同步会直接把本地 main 推上去建立，远端旧分支与 HEAD 不动；AI 工具 `git_branch` 仅剩列表（无创建/切换）。
- 长笔记（>10 行）信息流自动折叠，可展开/收起；灯箱图片右键菜单支持「复制图片 / 保存图片」。

## 架构与安全

```
web/（前端：index.html + assets/app.css + js/*.js，无构建无 CDN，全局作用域按序加载）
   │ 同源 fetch /api/*（cookie 凭证，服务启动时生成）+ /assets/* /js/* 静态文件
web/server.js（Node ≥18 零 npm 依赖，spawn 系统 git）
   │ 只绑 127.0.0.1:8644
   ▼
本地仓库 ~/.git-notes/repo ──fetch/rebase/push（SSH 专用密钥 ~/.git-notes/keys/）──▶ 任意 git 服务器
```

- 服务只绑 `127.0.0.1`；页面凭证用随机 cookie（SameSite=Lax, HttpOnly）+ Host 校验（防跨站驱动/DNS rebinding）；日志不打印请求头、cookie 与查询串。
- SSH 专用密钥按需自动生成（不复用 `~/.ssh`），首次连接 TOFU（`StrictHostKeyChecking=accept-new`）；私钥 0600。
- 写路径白名单：仅 `micro/` 与 `settings/main.json`，严禁全仓提交；删除以 git 提交落地，历史可找回。

## 验证

无自动化测试框架；改动后用浏览器全功能实测（发布文字/带图/标签/筛选/搜索高亮/编辑/删除/灯箱/设置页/绑定向导/强制推送），390/820/1440 三视口。API 层可用临时 bare 仓 + node fetch 脚本做全场景断言。测试脚本与截图一律不进仓库（见 AGENTS.md）。

## 三端

| 端 | 目录 | 说明 |
|---|---|---|
| PC Web | `web/` | Node ≥18 零 npm 依赖，npm 包 [`@u32/git-notes`](https://www.npmjs.com/package/@u32/git-notes)，`npm i -g @u32/git-notes` 后运行 `git-notes` |
| Android | `android/` | Kotlin + JGit 移植同一套服务与界面，构建见 `android/README.md` |
| Windows 桌面 | `electron/` | Electron 纯单机（零端口零鉴权），`cd electron && npm i && npm run dist` |

三端共享同一套前端（`web/index.html` + `assets/` + `js/`）与数据格式，改 `web/server.js` 路由/git 行为需三端同步。

## 开源地址

- GitHub：<https://github.com/u32-cn/git-notes>
- 官网：<https://git-notes.u32.cn/>

## License

[MIT](LICENSE)