周时间轴

中文 | English

按 docs/周时间轴工具需求文档.md 实现的时间安排编辑工具。它是一个本机网页服务加页面，结构与其他使用 web-kit 的工具（clash-review、port-monitor）相同：双击 TIMELINE.bat，服务在后台启动并打开浏览器。

四级安排

抽象级	在哪一页	默认内容
唯一模板（1 个）	模板页	——
周模板（周日至周六 7 个）	模板页	跟随唯一模板
具体日子，即某一天的计划（从起始日到下周末）	计划日程页	跟随同一星期的周模板
实际记录，即某一天实际的安排（同样的范围）	实际日程页	跟随同一天的计划

• 计划日程与实际日程：两页列出同样的日子，一天一行。计划日程页用来做计划；实际日程页用来记录那一天实际是怎么过的。一天的实际记录在改动之前等于那一天的计划，只需要改与计划不同的地方。工具不比较计划与实际，也不做统计。
• 跟随：上级怎么变，它就怎么变，包括已经过去的日子。行头是一个虚线空心、灰字的“跟随”标签，后面写着它跟随谁（“唯一模板”“周二模板”“计划”）。
• 已编辑：第一次改动一个跟随的周模板、日子或实际记录时，工具先把上级的内容复制给它，再做改动。从此它有自己的内容，不再随上级变化。行头是一个紫色实心的“已编辑”标签。
• 重置：行头菜单里的“重置为模板”（实际记录是“重置为计划”）可以让它恢复跟随。
• 日程页的参照行：顶部固定一行只读的唯一模板参照行。选中某一天的格或区间后，唯一模板下方才出现第二个参照行，取消选区后消失：计划日程页显示那一天所属星期的周模板（例如选中 9月29日 周二，就显示“周二模板”）；实际日程页在同一个位置显示那一天的计划（“9月29日 周二 计划”）。三层的底色一层比一层暗，行头左侧的竖条一深一浅（最下面一层没有），行名逐层缩进。两种参照行都可以隐藏。
• 今天：两个日程页里，当天的那一行有一圈墨色描边，行名后面有“今天”标签。日期取自系统时间，过了零点自动移到新的一天。打开日程页或点“回到本周”时，当天的行滚动到编辑区的垂直中央。
• 加载范围：两个日程页都显示到“今天所在周的下一周”的最后一天。一周从周几开始，在“文档设置”中选，默认周日。
• 笔记：计划文件最后的 ## 笔记 一节，放“每天最多工作 9 小时”这类工具不检查的计划判断。页面上没有笔记框，要改就打开“文本视图”改最后一节。

快速上手

0. 下载：到 Releases 下载 weekline-版本号-win64.zip，解压到任意位置。压缩包自带 Python，不用另外安装。
1. 启动：双击 TIMELINE.bat。服务在后台运行，不留窗口，并用默认浏览器打开页面。再双击一次只会再打开一个页面。
2. 计划文件：工具只编辑一个 md 文件，每次修改后 1 秒内自动写入，不需要“保存”。顶栏写着文件名和保存状态；单击文件名可以在资源管理器中显示它。第一次启动时按示例新建。
3. 切换页面：顶栏的“模板”“计划日程”“实际日程”按钮，或在编辑区按 Alt+1、Alt+2、Alt+3。
4. 选格：单击一个空格，或按住鼠标拖动选出一块（可以跨多行）。按住 Ctrl 单击行头，可以把该行加入或移出选区。再单击选区里的格，或单击编辑区外面的地方，取消选区。
5. 建区间：按 E 建外部固定安排（会弹出文字框，输入“上课”后按 Enter）；按 S 建自主安排；按 D 建日常事务（吃饭、洗漱这类，也会弹出文字框）。
6. 改区间：单击区间选中它，然后：
   • ← → 平移，Shift+←→ 调结束时刻，Ctrl+←→ 调开始时刻，Alt+↑↓ 移到相邻行；
   • F 切换浮动，Enter 或双击改文字，Delete 删除；
   • 也可以拖动已选中区间的左右边缘来调整时刻。
7. 导入、导出：“导入”读入一个 md 文件替换当前内容（可以撤销），修订前的旧格式也能读；“导出”下载一份 标题.md。
8. 文档设置：修改显示范围、一周起始日、起始日。
9. 显示设置：顶栏右侧的滑杆按钮打开 web-kit 的显示设置：四套配色（出厂为象牙）、英文字体、英文粗细、灰字亮度；旁边的太阳按钮在同一对深浅之间切换（象牙↔暖炭，青瓷↔深青）。“设为默认”存到工具的数据目录，不写入计划文件。
10. 菜单与帮助：右键任意位置可以打开菜单，菜单列出当前可用的全部操作。在编辑区按 ? 可以查看全部快捷键和图例。

图例：

• 外部固定安排：蓝色实心块，文字加圆角圈注；
• 自主安排：沙色描边块（底色很淡）；
• 日常事务：浅绿色半透明块，没有边框，能透过它看到格线；
• 时刻事件：蜂蜜黄半透明竖线加标签；起床、就寝的竖线更粗，线外铺暗色；
• 浮动：虚线（实心块则在内侧加一圈虚线）；没有文字时显示“浮动”；
• 选中的区间：粗外框；选中的格：框线变粗、变成铜色，除起点那一格（锚点）外都有淡底；
• 状态标签：“已编辑”紫色实心，“跟随”虚线空心、灰字；
• 今天：整行一圈墨色描边，加“今天”标签。

转成灰度后，这些样式仍可区分（实心块与描边块、实线与虚线、实心标签与空心标签）。

计划文件与保存

• 位置：默认是设置目录里的 plan.md。设置目录平常是 %APPDATA%\weekline\；想放到别处（例如同步盘），把 settings.example.json 复制成设置目录里的 settings.json，填 plan_file。
• 自动保存：写入是原子的（先写临时文件再替换）。服务停了时，顶栏显示“保存失败”，修改留在页面里，每 5 秒重试；重新双击 TIMELINE.bat 后自动写入。
• 在别处修改：可以用文本编辑器直接改计划文件。切回页面时，工具自动载入新内容（可以撤销）；如果页面里也有还没写入的修改，顶栏会让你选“载入文件的版本”或“用本页的内容覆盖文件”。
• 文件有错误：页面不会载入，也不会改写它，而是在文本视图中列出错误；改好后点“应用”才写回。
• 备份：每天第一次写入前，把原文件复制到数据目录的 backup/，保留最近 30 份。
• 停止服务：没有窗口可关。关掉页面 30 分钟后服务自动退出；要立即停止，运行 pythonw weekline.py --stop。
• 日志：数据目录（平常是 %LOCALAPPDATA%\weekline\）里的 web.log。

文本视图

点顶栏的“文本视图”，右侧会显示当前安排对应的 md 文本，图形编辑时它会实时更新。

• 文本里只写出已编辑的周模板、日子和实际记录；没写出来的，就是跟随的。
• 一天的计划写作 ## 2026-09-29 周二 一节，那一天的实际记录写作 ## 2026-09-29 周二 实际 一节，紧跟在计划后面。旧版本的工具不认识“实际”一节，读不了含有它的文件。
• 直接修改文本后，编辑区会暂时变为只读，直到点“应用”或“放弃修改”。
• 有错误时会列出全部错误及行号，点击一条错误会跳到对应的行。
• 浮动写作 ~ 加文字，~ 后面的字就是横条上显示的文字：18:30-20:30 ~读书 显示“读书”，18:30-20:30 ~[上课] 是浮动的外部固定安排；只写 ~ 或 ~浮动 显示“浮动”。全角 ～ 也认。因此区间文字里不能有 ~。
• 修订前的写法 18:30-20:30 读书 ~浮动 也能读，写回时改为 ~读书。
• 时刻事件：只写一个时刻加文字，如 10:00 吃药，编辑区里画成一条蜂蜜黄半透明竖线加标签。它只能在文本视图或计划文件里写、改、删，编辑区里点不中它（点下去落在下面的格子上）。
• 起床、就寝：写成时刻事件 07:00 起床、23:00 睡觉（也可以写“就寝”），竖线更粗，起床前、就寝后的时段铺暗色，一眼看出清醒的时间段。每节至多各一个。它们单独继承，不跟区间走：写在唯一模板里，所有周模板和日子都会显示，包括已经编辑过的；哪一节自己写了起床（或睡觉），就用自己的，另一个照旧沿用上级。
• 日常事务写作圆括号：12:00-13:00 (吃饭)，浮动的写作 ~(吃饭)；全角 （） 也认。因此自主安排的文字不能整段用括号括起来。

目录结构

路径	说明
TIMELINE.bat	启动脚本：用 web-kit\find-python.ps1 找 Python（环境变量 TOOL_PYTHON、工具目录里的 python\、注册表、py 启动器、常见目录、PATH），再用 pythonw 在后台启动服务。
weekline.py	服务：送出页面，读写计划文件。只用 Python 标准库。
web/	页面：index.html、app.css、纯函数核心 core.js（数据模型、继承、规则、编辑操作、日期、md 解析与序列化，NFR-9）和界面层 app/。没有构建步骤，改了刷新页面即可。
web-kit/	web-kit 的副本：配色、显示设置、本机显示参数、心跳、服务外壳、tooldirs、pack.py。不要修改，来历见 vendor.json；更新方法见 web-kit 的 README“副本与比对”。
docs/	需求文档。改动的顺序：先改需求文档，再改 README，最后改代码。
tests/ + run-tests.sh	./run-tests.sh：用无头 Edge 跑纯函数层的测试，再用 Python 跑服务的计划文件读写测试。
settings.example.json	可选设置的样例。

界面层 web/app/ 各文件由 index.html 按下表顺序加载。

• 所有文件共享一个命名空间对象 WeekApp，每个文件把自己的函数挂到它上面。
• 文件开头可以直接取用排在前面的文件提供的函数；调用排在后面的文件的函数时，写作 A.xxx()。
• 新增文件要在 index.html 里加一行 <script>；服务会自动送出 web/ 下的新文件。

文件	内容
base.js	常量、示例文本、界面元素、状态对象、通用工具（提示信息、只读检查、复制到剪贴板、当前日期）
state.js	撤销历史（含步骤合并）、选区
page.js	页面模型：当前页有哪些行（层级标题、分组标题、参照行、可编辑行）、可编辑行的顺序；切换页面；把当天的行滚动到中央
render.js	顶栏（含保存状态与提示条）、编辑区、状态栏（含浏览器缩放提示）的渲染；键盘操作后的自动滚动
textview.js	文本视图：行号、错误列表、应用、放弃修改
edit.js	编辑操作：写入、移动、复制粘贴、行操作、文字编辑
input.js	键盘与鼠标
menus.js	上下文菜单、行菜单、对话框（文档设置、快捷键）
files.js	计划文件：读入、自动保存与重试、外部修改与冲突、导入、导出
main.js	事件绑定、web-kit 初始化与启动

开发：在工具目录放一个名为 portable 的空文件（已在 .gitignore 里），计划文件就在工具目录、数据在 var/，与已安装的那份分开。

发布新版本：提交并推送改动后，打一个带说明的版本标签并推送，例如 git tag -a v1.0.1 -m "修正……"，再 git push origin v1.0.1。GitHub 收到 v 开头的标签后，按 .github/workflows/release.yml 自动打包（git 跟踪的文件加免安装版 Python，由 web-kit/pack.py 完成），并新建一个 Release，附上 zip，发布说明就是标签的说明。进度在仓库的 Actions 页查看。

对需求的解释与补充（需求 1.4 节要求的说明）

需求中的“应当”条款全部实现，没有偏离。以下几处是需求没有写明、实现时自行做了决定的地方：

• 行操作的键盘入口：上下文菜单（Shift+F10 或菜单键）中包含锚点所在行的“重置为模板 / 清空此行 / 选中整行”。行头的“⋯”按钮菜单里另有“加入/移出格选区”。
• 撤销步骤的合并：为使 AC-9 成立（AC-2、AC-3、AC-4 各算一步），以下情况合并为一个撤销步骤：
  • 按 E 创建区间后紧接着的文字输入；
  • 对同一选区连续进行的同类移动（例如连按两次 Shift+←）；
  • 标题中的连续输入，在停止 1 秒或失去焦点前合并为一步（FR-6.22）。
• 首尾空格：标题和区间文字的首尾空格会被去掉，否则写成 md 再读回时会变，违反 FR-7.8。
• 自动保存的节奏：修改后 300 毫秒写入，这段时间内的多次修改合并为一次；写入失败每 5 秒重试。
• 计划文件有错误时：“放弃修改”恢复为文件原文，编辑区仍为只读；已有内容的页面还可以选“用本页的内容覆盖文件”。
• 锚点（需求术语表、FR-5.17）：格选区里没有淡底的那一格就是锚点，即拖选时按下鼠标的那一格。它记住选区从哪一头选起：
  • 从左往右拖出 12:00–14:00 后按 Shift+←，右端缩回，变为 12:00–13:30；从右往左拖出同样的选区再按 Shift+←，左端伸出，变为 11:30–14:00。Shift+单击同理，锚点那头不动；
  • ← → ↑ ↓ 从锚点出发移到相邻的格；Space 选中锚点所在的区间；上下文菜单里的行操作针对锚点所在的行；
  • 粘贴不看锚点，从选区的左上格开始。
  • 2026-09-26 评估过是否去掉：主要用法“拖一下，按 E/S/D”用不到它，但去掉后 Shift+方向键只能单向加长、想缩短得另配按键，所以保留。
• 横条上的时长：文字优先。完整的文字加时长放得下才显示时长，放不下就整个藏起时长（不显示半截），文字一行放不下就折成两行，两行还放不下才截断；悬停总能看到完整内容（FR-5.15）。
• 实际日程页的范围与参照行（需求 Q-8、Q-9）：实际日程页与计划日程页列出同样的日子，包括还没到的日子（它们跟随计划）；顶部保留唯一模板参照行，只把周模板参照行的位置换成当日计划。
• 行头宽度：由 172 像素加宽到 220 像素，使“10月12日 周一”加“今天”标签能完整显示（FR-5.26）。
• 外部修改的检查时机：窗口重新获得焦点或页面重新可见时。页面一直在前台时，别处的修改要等下一次写入（被拒绝后进入二选一）或切换窗口时才发现。

浏览器与系统

• Windows 10 / 11。服务向 Windows 读显示器参数（NFR-11），启动脚本是 .bat。
• Chrome、Edge、Firefox：功能完整。文件读写都由服务完成，不依赖浏览器的文件接口。