gudong-xiexia-cli

CLI tool that lets AI agents read and write your Xiexia (写下) diary from S3/WebDAV. No MCP, no server, just a command.

📚 本 CLI 的 src/entry/types.ts 是写下日记 JSON 格式的 TS 镜像，协议权威源在 ../RiJian/shared/src/commonMain/kotlin/name/gudong/xiexia/sync/EntryJson.kt。

Why

写下（Xiexia） 是一款本地优先、一天一页的私人日记 App，通过 S3 或 WebDAV 同步。这个 CLI 让 AI coding agent（ZCode / Codex / Claude / Cursor 等）用普通 shell 命令直接读写你的日记——无 MCP 协议、无服务端、App 零改动（agent 写入云端，App 下次同步自然拉到）。

架构与 gudong-inbox-cli 同构（Skill + CLI + 云端直连），按日记语义定制。

Quick Start

# 安装
npm install -g gudong-xiexia-cli

# 配置（WebDAV 示例，与 App「同步设置」用同一账号）
gudong-xiexia config init \
  --cloud-type webdav \
  --url https://dav.jianguoyun.com/dav \
  --username [email protected] \
  --password app-password \
  --root-dir Xiexia \
  --timezone Asia/Shanghai

# 验证
gudong-xiexia config test

# 用
gudong-xiexia today
gudong-xiexia search --query "加班"
gudong-xiexia append --content "今天去了海边，风很大。"

Commands

| Command | Description | |---------|-------------| | today | Today's page (all entries, chronological) | | day --date 2026-09-04 | One day's page | | list | Days with entries (summaries, --since/--until/--limit) | | read --id <id> | Full text of one entry | | search --query "kw" | Full-text search | | stats [--month 2026-09] | Total / streaks / monthly counts | | append --content "..." [--date] | Append an entry (default today) | | update --id <id> --text "..." | Rewrite one entry's text | | delete --id <id> --confirm | Soft-delete (tombstone, App trash semantics) | | config init/show/test | Credential management (secrets masked in show) |

所有命令成功输出 JSON 到 stdout，失败 stderr + exit 1，写入冲突 exit 2。

同步协议（与 App 的契约）

• 云端布局：{rootDir}/entries/{id}.json（默认 rootDir Xiexia），一条日记一个 JSON
• 写入纪律：改写前重读远端做冲突检测；updatedAt = now、revision = 远端 revision + 1
• 删除 = 写 removed: true 墓碑（正文保留，App 回收站可恢复），附件文件不动
• 新条目 id：entry-<毫秒时间戳>-<uuid前8位>（对齐 App 的 DiaryIds）
• calendarDate（yyyy-MM-dd）= occurredAt 在 timezone 下的折算，默认 Asia/Shanghai

Config

~/.gudong-xiexia/config.json（chmod 600，config init 生成）。环境变量回退：CLOUD_TYPE、S3_ENDPOINT、WEBDAV_URL 等。磁盘增量缓存在 ~/.gudong-xiexia/cache.json（按 etag/lastModified 增量刷新，删掉即全量重建）。

Skill for AI Agents

skills/gudong-xiexia/SKILL.md 随包分发，复制到 agent 的 skill 目录（如 ~/.zcode/skills/、~/.codex/skills/）即生效。Skill 内含读写安全铁律：读取免确认，写入必须两阶段确认；追加优先不改写；日记隐私不外传。

How it works

AI agent (ZCode / Codex / Claude / Cursor)
        ↓ exec_command
  gudong-xiexia (standalone CLI process)
        ↓ S3 API / WebDAV PROPFIND-GET-PUT
  your cloud storage  ←→  写下 App（Android / iOS / macOS，同一协议）

Development

npm test        # vitest（协议解析 / 冲突 / 软删 / 缓存）
npm run build
npm run dev     # tsx 直跑

WebDAV 往返可配合 RiJian 仓库的 scripts/webdav-test-server.py 本地服务器实测。

License

MIT