Weekly Planner

An Obsidian weekly planner: a seven-column drag-and-drop board with six color themes, a bilingual (English / 中文) interface, habit tracking, time statistics, and optional Markdown archiving.

English quick start — copy manifest.json, main.js and styles.css into <your vault>/.obsidian/plugins/weekly-planner/, restart Obsidian, then enable Weekly Planner under Settings → Community plugins. Open the board by clicking the calendar icon in the left ribbon or by running Open board from the command palette (Ctrl+P) — it does not open by itself on startup. Drag task cards between the seven day columns, switch palettes, tick off habits, and optionally archive the week to Markdown. No network access, no telemetry; everything stays inside your vault. MIT licensed.

一个 Obsidian 周计划工作台：七列拖拽看板、配色主题切换、中英双语界面、习惯打卡、时长统计与每日小结。界面与交互参考小红书同款「用 AI 做周计划」工作台。

功能

• 周视图看板：周一至周日七列，任务卡可在列间拖拽调整日期
• 任务卡：分类配色、计划/实际小时数、完成勾选、分类下拉切换
• 统计：任务总数、已完成数、计划总时长、实际总时长
• 分类时长汇总：按分类汇总本周计划/实际时长
• 每日图表（Daily Chart）：当日各分类计划 vs 实际时长条形对比
• 每日记录：每天一段自由文本小结
• 侧栏管理：迷你日历（可翻月，高亮当前周期）、本周优先级、本周任务清单、习惯打卡（七天勾选）、任务分类管理
• 6 套配色主题：马卡龙、莫兰迪、莫奈花园、孟菲斯、洛可可、敦煌 —— 整页联动换肤
• 中英界面切换：一键切换，随数据持久化
• 多周期：可建新周期、归档历史周、下拉切回查看
• JSON 导入导出：备份与迁移
• 可选 Markdown 归档：把当前周计划导出成 .md 文件写入库内指定目录（见下）

安装

方式一：手动安装

1. 下载或克隆本仓库

2. 将 manifest.json、main.js、styles.css 三个文件放入：

   <你的库>/.obsidian/plugins/weekly-planner/
   

3. 重启 Obsidian

4. 设置 → 第三方插件 → 已安装插件 → 启用 Weekly Planner

方式二：从源码构建

本插件为纯 JavaScript 实现，无需编译，main.js 即最终产物。

使用

• 点击左侧边栏的日历图标，或使用命令面板（Ctrl+P）搜索 Open board 打开视图
• 另有命令 Open board in right sidebar，直接把看板开在右侧栏
• 注意：插件启动时不会自动打开视图。需要手动打开一次，之后 Obsidian 会记住这个标签页
• 视图可像普通标签页一样停靠、分屏

设置

设置 → 第三方插件 → Weekly Planner 右侧齿轮图标：

归档目录、备份目录若不存在，插件会自动创建。

数据存储

• 插件自身数据保存在 <vault>/.obsidian/plugins/weekly-planner/data.json
• 自动备份副本写入库内独立目录（默认 _weekly-planner-backup），刻意放在插件目录之外 —— 见下节
• Markdown 归档文件按设置写入库内指定目录，可被 Obsidian 直接检索、链接、纳入每日笔记体系

自动备份

为什么必须放在插件目录之外：Obsidian 把「已启用插件列表」缓存在内存里。若在 Obsidian 运行期间从外部写入 community-plugins.json（脚本安装、手工编辑等），它下一次保存就会用内存状态覆盖这个文件、把新条目摘掉，随后把那个插件目录当孤儿目录删除 —— data.json 连同里面所有任务一起消失，重新加载时只剩默认配色和英文界面。

data.json 待在插件目录里，救不了自己。所以副本写到库内另一处：

<vault>/_weekly-planner-backup/wp-2026-09-18_175644354.json

行为细节：

• 自动触发：任何改动（加/删任务、写笔记、勾选、切周…）都会走一次保存，保存后延迟 3 秒写副本；两份副本之间至少间隔「备份间隔」（默认 5 分钟），所以连续打字只产生一份
• 内容没变就不写：比对内容指纹，不变则跳过，不产生垃圾文件
• 文件名绝不复用：wp- + 毫秒级时间戳；同一毫秒内再写会追加 _2、_3，一份副本都不会被另一份顶掉
• 自动清理：只保留最新 N 份（默认 30），更旧的删除
• 空数据不占位：刚装好、还没有任何任务的默认数据不会生成副本
• 可恢复：设置面板可列出最近 20 份并一键恢复；恢复前会先把当前状态备份一份，选错了用同样方式退回

排序按文件 mtime（不是文件名）—— 因为被清理掉的旧文件名会被新副本重新使用，纯按名字排序会把「复用名」误判成最旧。

备份目录务必放在 .obsidian 之外，否则会和插件目录一起被回滚清掉。

真的被回滚掉之后怎么恢复

插件目录被删时 data.json 一起没了，test/install.py 会按下面的顺序补回来（只有在缺失时才写，已存在则绝不覆盖）：

1. 最新的一份库内副本 —— 从 _weekly-planner-backup 里按 mtime 取最新且含 periods 的 wp-*.json，把完整看板恢复回来
2. 种子文件 data.seed.json —— 库里从来没有过副本时（新机器）的兜底，只有空结构与偏好，没有任务

顺序不能反：先取种子会「恢复成功」但得到一个空看板，而旁边就躺着一份完整副本。 test/recover_test.py 用一次性假库把这三条路径（最新副本 / 无副本走种子 / 已有数据不动）都测了一遍。

开发

git clone <repo-url>
cd obsidian-weekly-planner

修改 main.js 后，在库中重新加载插件即可（设置 → 第三方插件 → 关闭再开启，或使用 Hot Reload）。

离线自检（不需要打开 Obsidian）

test/ 目录下的脚本可在纯命令行下验证插件，改完代码先跑一遍再切回 Obsidian：

# 1. 运行期自检：桩化 obsidian 模块 + 迷你 DOM，跑 onload / onOpen /
#    设置页 / 归档写入 / 自动备份（写入位置·去重·轮转·恢复）全链路。
#    可传目标目录以直接测试「已部署的那份」
node test/smoke.mjs
node test/smoke.mjs "E:\My obsidian Vault\.obsidian\plugins\weekly-planner"

# 2. 生成样式预览页（真样式 + 真模板 + 样例数据），浏览器直接打开看版式
python test/preview.py
#    -> test/out/preview-wide.html / preview-narrow.html

# 3. 布局探针：在多个宽度下量真实几何，报告每行几列 / 是否被压到换行下限以下；
#    同时模拟一次编辑以验证 save() 链路（含备份钩子）不抛错
#    （排「显示不全 / 格子太小」先跑这个）
python test/probe.py
python test/probe.py 1400 1085 1000 900      # 也可指定宽度

# 4. 分行可达性：确认换行后的第二行能滚到，且 7 列名字齐全
python test/rows.py 1085 1000                # 宽 高

# 5. 出图看版式（宽 高）
python test/shot.py 1085 1000                # -> test/out/wrap-1085.png

# 5b. 分类胶囊行高度：专测「结构性行被 flex 压扁」（探针里也含这条断言）
python test/pillsbug.py
python test/negctl_pills.py                  # 反向对照：证明断言真的会报错

# 6. 从源 HTML 重新生成 styles.css（改设计后保持样式同步）
python test/regen_css.py ../weekly-planner.html styles.css

# 6b. 看用户截图（无 Pillow 也能用）：尺寸 / 色彩结构 / 扫描线
python test/imgsize.py  shot.png
python test/pngmap.py   shot.png
python test/scanline.py
python test/zoomcrops.py                     # 放大渲染，便于复核

# 7. 安装到某个库（会先检查 Obsidian 是否在运行，在跑就拒绝）
python test/install.py "E:\My obsidian Vault"

# 8. 装后校验：逐文件 md5 比对源 ↔ 库
python test/verify_deploy.py "E:\My obsidian Vault"

# 9. data.json 恢复顺序测试（用一次性假库，不动真实库）
python test/recover_test.py

文件结构

weekly-planner/
├── manifest.json     插件元信息
├── main.js           插件主程序（纯 JS，免编译）
├── styles.css        样式（全部作用域收敛在 .wp-app 容器内）
├── versions.json     插件版本 ↔ 最低 Obsidian 版本映射
├── LICENSE           MIT 许可证
├── README.md
├── RELEASE.md        发布到社区插件目录的操作手册
├── data.seed.json    部署兜底种子（仅 test/install.py 使用，非插件运行文件）
└── test/
    ├── smoke.mjs         运行期自检（桩化 obsidian + 迷你 DOM）
    ├── preview.py        生成样式预览页，便于截图比对
    ├── probe.py          布局探针：量每行几列、是否被压到换行下限以下
    ├── rows.py           换行可达性：第二行能否滚到
    ├── hprobe.py         单列高度探针：量每列 top/h/bodyH，查"列被拉高/空白过大"
    ├── shot.py           无头浏览器出图（加 --hide-scrollbars）
    ├── sb.py             同上但保留滚动条，用来确认滚动条真的渲染出来了
    ├── procs.py          Obsidian 进程检测（Python 解析，替代 grep -c）
    ├── state.py          库状态快照（条目数 / 目录清单 / 目标插件明细）
    ├── verify_deploy.py  源 ↔ 库逐文件 md5 比对
    ├── regen_css.py      从源 HTML 重生成 styles.css
    ├── hotcss.py         只替换 CSS 的轻量更新（已被证伪不能绕过回滚，见「注意事项」）
    ├── px.py             截图像素采样：核对渲染出来的背景/配色是否真的对
    ├── pillsbug.py       复现/守住「分类胶囊行被 flex 压扁」（分类行高度断言）
    ├── negctl_pills.py   反向对照：把 .pills 改回可压缩，确认探针真的报错
    ├── negctl_cmdid.py   反向对照：注入违规命令 ID，确认合规断言真的报错
    ├── package.py        构建发布包（dist/ 仓库文件集 + 运行文件 zip）并校验
    ├── recover_test.py   data.json 恢复顺序端到端测试（假库：最新副本/种子/已有数据）
    ├── imgsize.py        只读 PNG 头拿宽高（无需 Pillow，判断截图是整窗还是裁剪）
    ├── pngmap.py         纯标准库解码 PNG，打印粗粒度色彩结构图
    ├── scanline.py       逐行扫描线游程：精确判别「几列/是否被裁剪」
    ├── zoomcrops.py      把用户截图放大渲染，便于人眼/模型复核
    └── install.py        写入目标库并启用（含进程检测 + data.json 恢复/种子兜底）

响应式行为

原版是照着宽屏桌面窗口设计的（七列各 252px，合计约 1836px）。在 Obsidian 的窗格里这个宽度并不存在。插件不再把七列硬挤成一行（那样每格只剩 ~115px，完全没法看），而是按可用宽度自动换行：一行能放下几列就放几列，剩下的折到下一行。

每列有一个可读宽度下限 --dayfloor（默认 240px），低于它就换行，绝不压缩。

（实测值取自 test/probe.py：1055px 视口 → perRow=[4,3] minW=251px；730px → [2,2,2,1] minW=347px。任何宽度下 hScroll=no。）

换行后整体高度会超过窗格，因此主区改为纵向滚动，第二行可滚到（不会像早先那样被裁掉）。 任何宽度下都不出现横向滚动——换行才是保证可读性的手段。

周次跳转

工具栏的 ‹ [周次下拉] › 用来直接翻到某一周，不必先在「新建周期」里手动建。

• 下拉列出以本周为基准的前后各 8 周（共 17 项），每项显示相对说法与日期区间， 例如「本周 (2026-09-14 ~ 2026-09-20)」。
• 选中一个尚不存在的周会即时创建空周期并切过去；已存在且有任务的周在标签尾部带 ● 标记， 方便区分空白周。
• ‹ / › 按钮按周前后翻动，效果等同于在下拉里选相邻项。
• 相对说法随界面语言切换（中文「本周 / 上一周 / 3 周前」，英文 This week / Last week / 3 weeks ago）。

滚动条

主区是唯一滚动容器（.days 自身不滚动，避免出现嵌套滚动条——内层滚动条短、先抢走滚轮事件， 还会掩盖「下面还有一行」这个事实）。滚动条常驻可见：

• scrollbar-gutter: stable 预留轨道，内容不会因滚动条出现/消失而左右跳动
• 显式设置轨道与滑块样式，不依赖「悬停才浮现」的浮层滚动条
• 日期列高度封顶在 220–360px，一行不会高到把第二行顶出可视区

已知行为

• 日期列高度区间为 220–360px：过矮则内容挤成一条，过高则第二行要滚很久

布局不变量（改 CSS 前请先读）

主区 .main 是唯一滚动容器，内部的结构性行永远不许被压缩：

最容易踩的坑：给某个行加 overflow-x:auto 会让它的自动最小尺寸变成 0， 于是它成为唯一能被压缩的 flex 成员，独自吃掉全部溢出。 .pills（分类胶囊）就中过这一枪 —— 4 张统计卡完好，胶囊行被压成 2px 的彩色细条。 test/probe.py 现在会断言 pills: CRUSHED，test/negctl_pills.py 用来确认这条断言不是瞎的。

注意事项

• 样式全部约束在 .wp-app 作用域内，不会污染 Obsidian 原生界面
• isDesktopOnly: false，桌面端与移动端均可使用（拖拽在移动端需长按）

安装 / 更新时的两个坑

1. 安装前请先完全退出 Obsidian。 Obsidian 运行期间会把 community-plugins.json 缓存在内存里；此时从外部写入插件文件与启用列表，会在 Obsidian 下一次保存配置时 被整体覆盖 —— 表现为「明明装了，重启后插件却不见了」。test/install.py 会先检测 进程并拒绝执行。
2. styles.css 请用 test/regen_css.py 从源 HTML 生成，不要手工改。 手工改容易漏掉 CSS 变量或误伤高度规则。特别注意源文件的 html,body{height:100%} 在插件里只能作用于容器本身，若扩散到所有后代元素，卡片会被拉伸到整屏高。

作者

YanXu

许可

MIT © 2026 YanXu

社区插件规范符合性

本插件已按 Obsidian 开发者政策 与 插件提交要求 自查：

• 不访问网络：代码中没有 fetch / XMLHttpRequest / sendBeacon，也不加载任何远程资源
• 不含遥测：不上报任何使用数据
• 无第三方依赖：整个 main.js 里唯一的 require 就是 require("obsidian")
• 不自我更新：不安装、不升级自身及其依赖
• 无广告：界面内不含任何广告位
• 代码未混淆：main.js 是可直接阅读的源码，未压缩、未加密
• 命令 ID 不含插件 ID：open / open-sidebar / backup-now（Obsidian 会自动补上 weekly-planner: 前缀）
• isDesktopOnly: false：只使用 Web API，桌面端与移动端通用