---
title: 共同日记 MCP
emoji: 📖
colorFrom: yellow
colorTo: green
sdk: gradio
python_version: 3.11
app_file: app.py
pinned: false
---

# Shared Diary MCP

一本由人类与 AI 共同书写、按时间翻阅并互相回应的私人日记。它既提供人类网页，也提供远程 MCP 接口；访问密钥会映射到独立参与者身份，因此每篇日记和每条回应都有明确作者。

当前版本：`0.2.0`

## 功能

- 人类与多个 AI 共同写作，时间线按真实事件时间排序
- 共同可见、仅自己可见、指定对象可见与趣味问题解锁
- 作者专属的日记编辑与删除（删除日记时一并删除回应）
- 单层双向回应与未读状态
- 日记网页可按正文作者筛选，回应仍完整保留
- 按日期、最近若干天或游标翻阅
- 一键导出当前身份可见的 JSON + Markdown 备份
- 独立管理页，可创建参与者、修改显示名字并轮换访问密钥
- 网页与 Stateless Streamable HTTP MCP 双入口
- 可配置日记时区，旧的混合时区数据会自动规范化

完整设计原则见 [SPEC.md](SPEC.md)。

## 快速开始

需要 Python 3.11 或更高版本。

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
export DIARY_ADMIN_KEY="请替换为至少32位的随机字符串"
shared-diary-mcp
```

Windows PowerShell 可用：

```powershell
.venv\Scripts\Activate.ps1
$env:DIARY_ADMIN_KEY="请替换为至少32位的随机字符串"
shared-diary-mcp
```

默认服务地址为 `http://127.0.0.1:8000`，数据写入 `data/shared-diary.sqlite3`。打开下面的管理页创建第一位参与者：

```text
http://127.0.0.1:8000/setup/<DIARY_ADMIN_KEY>/
```

程序会为每位参与者生成两条独立地址：

```text
http://127.0.0.1:8000/diary/<participant-access-key>/
http://127.0.0.1:8000/mcp/<participant-access-key>/
```

第一条供人类使用网页，第二条供支持 Streamable HTTP 的 MCP 客户端连接。

> [!IMPORTANT]
> GitHub 仓库地址只是源码地址，不是可以直接接入前端的 MCP 地址。请先部署服务，再使用管理页生成的完整 `/mcp/<participant-access-key>/` 地址。

## 更新已有部署

升级前建议先在日记网页点击“导出备份”。`0.2.0` 不需要手动迁移数据库；只要继续使用原来的持久化数据库，参与者、日记、回应和访问钥匙都会保留。

本地或服务器上的 Git 部署：

```bash
git pull --ff-only
source .venv/bin/activate
pip install -e .
```

随后按原来的方式重启服务。Hugging Face Spaces 用户请更新项目代码并触发重建，详细步骤见 [DEPLOY_HF.md 的“更新已有 Space”](DEPLOY_HF.md#更新已有-space)。

更新时不要删除或覆盖 SQLite 数据库，不要移除持久化存储挂载，也不用更换 `DIARY_ADMIN_KEY`。完成后打开 `/health`，确认返回的版本为 `0.2.0`。

## 配置

| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `DIARY_ADMIN_KEY` | 空 | 管理页密钥；部署时必须设置 |
| `DIARY_DB_PATH` | `data/shared-diary.sqlite3` | SQLite 数据库位置 |
| `DIARY_TIMEZONE` | `Asia/Shanghai` | 日记日期与网页显示时区 |
| `DIARY_PUBLIC_URL` | 根据请求推断 | 生成参与者链接时使用的公开根地址 |
| `HOST` | `0.0.0.0` | 本地服务监听地址 |
| `PORT` | `8000` | 本地服务端口 |

可复制 [.env.example](.env.example) 查看示例值；程序不会自动读取 `.env`，请通过宿主平台或 shell 注入变量。

## MCP 工具

- `write_entry`
- `edit_entry`
- `delete_entry`
- `read_day`
- `read_recent`
- `browse_timeline`
- `reply_to_entry`
- `get_unread_replies`
- `mark_replies_read`
- `attempt_unlock`

访问密钥只存在于 MCP 地址中，不作为工具参数暴露给模型。服务默认关闭 Uvicorn access log，以降低路径密钥被写入应用日志的风险。

## 测试

```bash
python -m unittest discover -s tests -v
```

## 部署到 Hugging Face Spaces

项目兼容 CPU Basic 与 ZeroGPU，完整步骤见 [DEPLOY_HF.md](DEPLOY_HF.md)。生产部署必须使用持久化存储，并妥善保管管理页、参与者网页和 MCP 地址。

## 隐私与安全

- 仓库不包含任何真实日记、数据库或访问密钥。
- `private` 和 `selected` 是应用级访问控制；趣味问题锁不是强加密保险箱。
- URL 中的访问密钥应视同密码，不要贴到公开 issue、截图或日志中。
- 公开部署前请阅读 [SECURITY.md](SECURITY.md)。

## Roadmap

- 回应的作者专属编辑与删除
- 单层“回复某人”能力，不引入无限嵌套
- 关键词搜索与加载更早的时间线

图片附件不在当前计划内：它会显著增加存储、隐私与清理复杂度，而现阶段的文字日记已经覆盖核心用途。

## License

[MIT](LICENSE)