让 agent 在长期对话里自然沉淀用户的生活轨迹，并在需要时生成可筛选、可截图的时间轴报表。
当前先开放 CLI，MCP 能力正在开发中。
重要前提：agent 上下文里必须带有明确对话时间戳，否则写入的时间数据会不准。如果你手头还没有满足这个前提的 agent，可以直接使用我的赛博老板项目：cyberboss。
它适合这样的场景：
- agent 在和用户的持续聊天中，会掌握用户的生活作息和身体状况，这些信息会不断累积，但没有一个结构化的出口
- 用户希望这些片段被稳定记录成生活轨迹时间轴，而不是散落在长对话里
- 当用户想看某一天、某一周、某个月，或某个分类、某个明细时，可以立刻从 agent 那里获取对应的报表截图
桌面主视图示例：
移动端视图示例：
| 时间轴 | 分析 | 事件 |
|---|---|---|
 |
 |
 |
局部筛选示例：
需要编码类别的分析局部截图时，可描述为“截 2026-04 的月视图分析区，筛到工作 > 编码”：
agent 发送截图给用户的示例：
其他局部截图和排列组合示例可在 examples/ 查看：
timeline-dashboard-timeline-view.pngtimeline-dashboard-analytics-view.pngtimeline-dashboard-events-view.pngscreenshot-combos/timeline-dashboard-main-view-zh.pngscreenshot-combos/timeline-dashboard-mobile-timeline-view.pngscreenshot-combos/timeline-dashboard-mobile-analytics-view.pngscreenshot-combos/timeline-dashboard-mobile-events-view.pngscreenshot-combos/week-main-default.pngscreenshot-combos/week-analytics-default.pngscreenshot-combos/month-2026-04-work-coding-analytics.pngscreenshot-combos/week-rest-sleep-events.pngscreenshot-combos/day-2026-04-05-timeline.pngscreenshot-combos/month-2026-04-analytics.png
- 让 agent 在对话中持续写入时间轴，需要时再截图给用户
- 自己在本地长期挂一个 dashboard，随时打开查看，不依赖 agent 临时截图
如果你不想每次都依赖 agent 触发截图，而是希望自己在本地随时打开 dashboard 看当前数据，最直接的方式是长期运行下面两个命令中的一个：
timeline-for-agent dev
timeline-for-agent serve区别是：
timeline-for-agent dev适合开发和频繁改数据，会监听源码和数据文件，自动重建并热刷新timeline-for-agent serve适合稳定查看，直接把已经构建好的静态页面挂起来，不做监听
常见用法：
timeline-for-agent build
timeline-for-agent serve --port 4317如果你长期只想“查看”而不是“边改边看”，优先用 serve。如果你会一边改数据一边观察效果，优先用 dev。
环境前提：
- Node.js
>=22 - 已执行
npm install - 如果需要截图，本机需要可用的 Chromium / Chrome / Edge，或可被
playwright-core发现的浏览器
最快启动方式：
npm install
npm run timeline-dev默认会启动在 http://127.0.0.1:4317。
如果不想走 npm scripts，也可以直接用：
node ./bin/timeline-for-agent.js dev默认状态目录在 ~/.timeline-for-agent/timeline/，主要文件包括：
timeline-state.json单一权威状态快照timeline-taxonomy.json分类、子类和 eventNodetimeline-facts.json真实时间轴事件数据site/build产出的静态页面shots/screenshot默认输出目录
时区配置：
timeline-state.json、timeline-taxonomy.json、timeline-facts.json都会带timezone- dashboard 的日/周/月分桶、趋势统计、tooltip 时间、移动端时间轴定位，都应以这个
timezone为准 - 如果你部署在东八区外，或希望按其他时区解释同一份事件数据，优先检查并修改
timeline-state.json里的timezone - 如果你还在使用拆分文件模式，也需要保证
timeline-taxonomy.json和timeline-facts.json里的timezone一致
CLI 会优先读取这两个 .env 位置：
- 当前工作目录下的
.env ~/.timeline-for-agent/.env
常用环境变量：
TIMELINE_FOR_AGENT_LOCALETIMELINE_FOR_AGENT_STATE_DIRTIMELINE_FOR_AGENT_DIRTIMELINE_FOR_AGENT_PORTTIMELINE_FOR_AGENT_CHROME_PATHTIMELINE_FOR_AGENT_TAXONOMY_FILETIMELINE_FOR_AGENT_FACTS_FILETIMELINE_FOR_AGENT_SITE_DIR
语言切换方式：
TIMELINE_FOR_AGENT_LOCALE=zh-CN npm run timeline-serve
TIMELINE_FOR_AGENT_LOCALE=en npm run timeline-serve同样也适用于：
TIMELINE_FOR_AGENT_LOCALE=zh-CN npm run timeline-dev
TIMELINE_FOR_AGENT_LOCALE=en npm run timeline-build
TIMELINE_FOR_AGENT_LOCALE=zh-CN npm run timeline-screenshot -- --selector main- 如果真实
facts非空，dashboard 会直接使用真实数据 - 如果真实
facts为空，会按语言回退到 demo 数据- 英文： demo-facts.json
- 中文： demo-facts.zh-CN.json
dev模式下修改真实数据文件会自动重建；demo 场景下修改examples/demo-facts.json也会自动重建
- 当前分类来自
timeline-taxonomy.json - 如果没有自定义 taxonomy，会先使用项目内置的默认 taxonomy
- agent 在写入时也可以顺带新增
eventNode，这些新增项会进入 taxonomy，并留下 proposal 记录
- 如果只是想让 agent 以后复用已有分类，可以先让它执行
timeline-for-agent categories - 如果是新增或调整 eventNode，可以让 agent 按现有流程写入，它会留下 proposal，之后再检查
timeline-for-agent proposals - 如果你想手动改分类体系，直接修改
timeline-taxonomy.json即可；改完后重新执行dev或build
timeline-for-agent build构建静态 dashboard 到site/timeline-for-agent serve [--port 4317]启动静态页面服务timeline-for-agent dev [--port 4317]监听源码和数据并热刷新timeline-for-agent screenshot先构建，再临时起本地服务并截图
timeline-for-agent screenshot默认截整页- 如果只截局部，优先使用受控 selector，而不是临时编 CSS
- 如果要在截图前切换日/周/月、时间范围、分类或明细，优先用结构化参数，不要让模型自己编 Playwright 步骤
当前内置区域：
main主视图整页timeline时间轴区域analytics类别分布、子类明细和趋势三块分析区events事件明细区
推荐的自然语言描述：
- “截主视图” / “截整页”
- “截时间轴” / “只截 timeline”
- “截类别明细趋势” / “截分析区”
- “截事件” / “只截事件列表”
- “截 2026-04-05 的日视图时间轴”
- “截 2026-04 的月视图分析区”
- “截工作 > 编码的分析区”
- “截工作 > 编码的事件列表”
timeline-for-agent help
timeline-for-agent categories
timeline-for-agent proposals
timeline-for-agent read --help
timeline-for-agent write --help
timeline-for-agent read --date 2026-04-06
timeline-for-agent write --date 2026-04-06 --stdin
timeline-for-agent build
timeline-for-agent serve
timeline-for-agent dev
timeline-for-agent screenshot --help
timeline-for-agent screenshot如果仓库还没全局安装，也可以把上面的命令替换成：
node ./bin/timeline-for-agent.js <命令>- 优先调用现有 CLI，不要先读源码理解用法
- 只有在命令报错、用户明确要求改实现、或需要新增能力时，才进入读源码路径
- 不推荐直接读取或修改原始 JSON 文件
- 如果不确定该复用哪个 category / subcategory / eventNode，先执行
timeline-for-agent categories - 如果是补充新内容，且上下文已经足够、目标日期明确、写入位置也明确，可以直接执行
timeline-for-agent write - 如果是修改、删除、覆盖或替换已有内容，先执行
timeline-for-agent read --date YYYY-MM-DD read只返回目标日期的受控事件数据，不返回完整 facts 或 taxonomy- 确认要改的事件后，再执行
timeline-for-agent write - 如果要排查新增了哪些 eventNode 提案，执行
timeline-for-agent proposals
- 所有
events都必须落在对应date当天内，不能跨天 - 每条事件都必须带
startAt和endAt - 每条事件都必须满足以下两种之一：
- 提供
eventNodeId - 提供
subcategoryId，并且最好同时提供categoryId
- 提供
- 如果缺少可用的分类信息，写入会直接报错，不会再静默过滤
- 睡眠如果跨过
00:00，需要拆成两段写： 一段是当天凌晨的睡眠，一段是当天夜间入睡后的睡眠 - 不要写一条从当天晚上直接跨到第二天早上的事件
screenshot会先执行一次build，再临时起服务后截图- 默认输出到
~/.timeline-for-agent/timeline/shots/ - 如果浏览器路径无法自动发现，可显式设置
TIMELINE_FOR_AGENT_CHROME_PATH - 只要用户想看某个分类或明细的时间分布，优先使用
--selector analytics - 只有明确要看事件卡片列表时，才使用
--selector events
示例：
timeline-for-agent screenshot --selector main
timeline-for-agent screenshot --selector timeline
timeline-for-agent screenshot --selector analytics
timeline-for-agent screenshot --selector events
timeline-for-agent screenshot --range day --date 2026-04-05 --selector timeline
timeline-for-agent screenshot --range month --month 2026-04 --selector analytics
timeline-for-agent screenshot --range week --category 工作 --detail 编码 --selector analytics
timeline-for-agent screenshot --range week --category 工作 --detail 编码 --selector events- 共享 agent 约束见 agent-instructions.md
- 未来 MCP 的 tool description 模板见 mcp-tool-descriptions.md
本项目主要面向个人本地部署场景设计。由于时间轴数据往往包含高度私密的生活信息、作息信息和长期行为轨迹，我不希望它被闭源包装成 SaaS 后再反向剥夺用户对数据和代码的知情权。
因此，本项目采用 AGPL-3.0-only 协议发布。任何基于本项目进行修改、扩展并通过网络向用户提供服务的行为，都必须按照 AGPL 的要求向对应用户提供完整的对应源代码。
商业使用并非天然被禁止，但前提是必须完整遵守 AGPL。对于任何形式的闭源封装、闭源云端化或只提供服务不提供源代码的做法，本项目都明确不欢迎。