基于AI编辑器的本地化生产力系统：jw-agenda智能体技能深度解析

1. 项目概述一个为AI编辑器而生的本地化生产力系统如果你和我一样日常重度依赖 Cursor 或 Claude 这类 AI 驱动的编辑器那你肯定也经历过这种场景脑子里有一堆待办事项项目规划散落在各个角落想用 AI 助手帮你整理却发现它对你的工作流一无所知最后还得自己手动在 Markdown 文件、日历应用和任务管理工具之间来回切换。这种割裂感正是我开发jw-skills这个项目最初的动机。这不是一个传统的待办清单 App而是一套深度嵌入你开发环境的Agent Skills智能体技能集合核心是jw-agenda——一个让你能用自然语言与 AI 对话就能完成从月度规划到每日执行、再到复盘总结的完整闭环系统。简单来说jw-agenda让你在写代码、写文档的同一个地方用最自然的方式管理你的所有事务。你不再需要离开编辑器去打开另一个应用只需要像跟同事聊天一样对你的 AI 助手说“帮我生成这周的计划”或者“我刚完成了 API 接口的调试”剩下的规划、记录、同步工作系统会自动帮你完成。所有数据都以纯文本 Markdown 格式存储在本地没有云服务没有数据同步的烦恼你拥有完全的控制权和隐私。这套系统特别适合开发者、内容创作者以及任何追求高效、专注且希望将工作流深度集成到工具链中的专业人士。2. jw-agenda 核心设计哲学与架构解析2.1 为什么是“技能”而非“应用”在深入细节之前理解jw-skills的定位至关重要。它被设计为一系列Agent Skills而非一个独立应用。这背后的核心哲学是“赋能而非替代”。我们不希望创造一个需要你改变习惯去适应的新工具而是将能力注入到你已经习惯的 AI 协作环境如 Cursor、Claude Desktop中。2.1.1 与 AI 助手的原生集成在 Cursor 中你可以通过Cmd/Ctrl K唤起 AI 指令面板直接输入自然语言指令。jw-agenda的技能被设计为能理解这些指令并触发相应的自动化流程。例如当你输入“生成今天的计划”背后的jw-agenda-daily-todo技能会被激活。它会自动扫描你工作区中jw-agenda-data/目录下的周计划文件提取出分配给今天的任务并结合昨天未完成的事项生成一份结构清晰的今日待办列表并直接插入或更新到当天的日志文件中。整个过程无需你指定文件路径或记忆任何命令语法。2.1.2 基于文件的松散耦合架构整个系统的状态完全由一组 Markdown 文件定义。这种设计带来了几个关键优势可移植性与控制权你的所有计划、日志就是一堆.md文件。你可以用任何文本编辑器查看用 Git 进行版本管理轻松地在不同机器间同步。工具链友好你可以用grep、awk或自己写的脚本去分析这些文件也可以用任何支持 Markdown 的静态站点生成器如 Hugo、Jekyll生成可视化的报告页面。故障容忍度高即使某个技能暂时失效你的核心数据Markdown 文件完好无损你可以手动编辑系统恢复后能继续读取。2.2 数据流与五大技能的协同逻辑jw-agenda由五个独立的技能组成它们通过共享的文件系统进行“对话”形成一个从宏观到微观再从执行反馈到宏观复盘的数据流闭环。2.2.1 自上而下的规划流Plan月度计划 (monthly/YYYY-MM-plan.md)这是规划的起点。你在这里定义本月的主要目标或重点领域如“完成项目 Alpha 的 Beta 版开发”、“学习 Rust 并发编程”。文件结构自由但通常包含几个主要板块。周度计划 (weekly/YYYY-[week]-plan.md)jw-agenda-weekly-plan技能的核心工作。你只需对 AI 说“生成本周计划”它会读取月度计划并结合上周的复盘结果特别是“结转事项”帮你将宏观目标分解为具体到每一天的可执行任务。它会自动生成一个新的周计划文件。每日待办 (daily/YYYY-MM-DD.md)jw-agenda-daily-todo技能负责此环节。每天早晨指令“生成今日计划”会触发它读取周计划中分配给今天的任务并检查前一天的日志将未完成的“进行中”任务自动带入今天形成当天的任务清单。2.2.2 自下而上的执行与复盘流Do-Check-Act每日执行与记录 (daily/YYYY-MM-DD.md)在当天文件中你直接勾选完成的任务或通过自然语言向 AI 汇报进展如“我完成了用户登录模块的单元测试”。jw-agenda-daily-log技能可以结构化这些零散的汇报将其整理为日志条目。周度复盘 (weekly/YYYY-[week]-review.md)这是jw-agenda-weekly-review技能的舞台。周末时一句“生成周度复盘”它会自动聚合本周所有每日日志文件分析任务完成率、时间花费分布如果日志中有时间记录并智能识别出哪些是已完成、哪些需要结转至下周、哪些应被取消。输出一份详细的复盘报告。计划同步与一致性检查jw-agenda-planning-sync技能扮演“审计员”角色。它可以检查日计划、周计划、月计划之间是否存在描述不一致或状态不同步的问题例如周计划中说“开始写设计文档”但日计划中连续几天都没有相关任务并在你确认后进行同步更新确保整个系统数据一致。注意这五个技能是模块化的。你可以只安装“每日待办”和“每日日志”实现轻量级的任务跟踪。当你需要更系统的规划时再引入周计划和复盘技能。这种渐进式采用策略降低了上手门槛。3. 从零开始部署与深度配置指南3.1 环境准备与技能安装虽然项目介绍中提到了 Python 3.9但作为终端用户你几乎不需要直接接触 Python 环境因为技能包是预编译的。重点在于正确放置它们。3.1.1 定位你的 Cursor Skills 目录这是最关键的一步。Cursor 的技能存放目录因操作系统而异macOS:~/.cursor/skills/Windows:C:\Users\[你的用户名]\.cursor\skills\或通过%USERPROFILE%\.cursor\skills\访问。Linux:~/.cursor/skills/如果目录不存在你需要手动创建它。一个快速验证的方法是打开 Cursor进入设置Settings搜索 “skills”通常会有相关路径提示。3.1.2 获取并安装技能包不建议直接克隆整个 Git 仓库除非你打算参与开发。对于使用者最方便的是从项目的 GitHub Releases 页面下载预打包的 ZIP 文件。前往 Releases 页面找到最新的版本例如v0.1.2。你会看到五个独立的 ZIP 文件分别对应五个技能jw-agenda-daily-log.zip,jw-agenda-daily-todo.zip等。将所有这些 ZIP 文件下载到本地。逐个解压到上一步找到的~/.cursor/skills/目录下。解压后该目录下应该会出现五个对应的文件夹如jw-agenda-daily-todo。实操心得在 macOS 或 Linux 上你可以使用终端快速操作。假设下载的 ZIP 文件在~/Downloads目录下cd ~/.cursor/skills/ for skill in ~/Downloads/jw-agenda-*.zip; do unzip $skill; done安装完成后重启 Cursor至关重要以便它重新扫描并加载新技能。3.1.3 初始化你的数据仓库技能本身不包含你的数据。你需要一个独立的位置来存放所有 Markdown 计划文件。建议在你的工作区Workspace根目录或你的个人文档目录下创建。# 在你的项目工作区根目录执行 mkdir -p jw-agenda-data/{monthly,weekly,daily,tasks}这个结构是技能默认寻找数据的路径。tasks目录目前可能未被使用是为未来功能预留的。3.2 创建你的第一个计划周期系统运转需要初始数据输入即一个月度计划。进入jw-agenda-data/monthly/目录。创建一个以年月-plan.md格式命名的文件例如2025-04-plan.md。用你喜欢的任何方式编辑这个文件。一个简单有效的模板如下# 2025年4月月度计划 ## 核心目标 1. 发布项目X的v1.2版本包含A、B特性。 2. 完成技术博客系列《系统设计入门》的前三篇。 3. 建立规律的晨间运动习惯每周≥3次。 ## 关键项目 * **项目X v1.2**完成API性能优化、编写用户文档、进行集成测试。 * **博客写作**确定大纲、完成初稿、配图与发布。 ## 学习与成长 * 深入理解Docker网络模型。 * 阅读《领域驱动设计》前五章。不需要严格的格式用自然语言描述你的目标和想法即可。AI 技能会解析这些内容。3.3 与 AI 助手进行首次交互打开一个集成了jw-skills的 Cursor 工作区确保该工作区包含或能访问到你的jw-agenda-data目录。生成周计划按下Cmd/Ctrl K输入“基于我的月度计划生成本周的计划”。AI 助手会调用jw-agenda-weekly-plan技能读取你的月度计划并在jw-agenda-data/weekly/下生成一个类似2025-w15-plan.md的文件将目标分解到周一至周日。生成日计划第二天输入“生成我今天要做的任务”。jw-agenda-daily-todo技能会读取周计划中对应日期的任务在jw-agenda-data/daily/下创建或更新当天的文件如2025-04-07.md并列出待办项。记录进度在当天工作中你可以在 AI 聊天框里说“我刚修复了用户登录模块的那个边界条件 Bug花了大概 1.5 小时。”jw-agenda-daily-log技能会将这些信息结构化追加到当天的日志文件中。灵活调整如果会议超时你可以说“把‘编写项目周报’这个任务移到明天下午。” 技能会理解你的意图并更新相关计划文件。避坑指南初次使用时AI 助手可能无法立即识别技能。请确保技能已正确安装在~/.cursor/skills/目录。Cursor 已完全重启。你的指令足够清晰自然例如使用“生成”、“总结”、“记录”、“移动”等动词开头。如果技能未被触发可以尝试在指令中明确提及技能名称如“使用 jw-agenda 生成本周计划”。4. 核心技能深度剖析与高级用法4.1 jw-agenda-daily-todo你的智能每日规划师这个技能远不止是简单列出任务。它内置了智能的上下文感知和任务调度逻辑。4.1.1 自动结转与优先级管理当你运行“生成今日计划”时它执行以下操作读取周计划找到当前周的计划文件提取出标记为今天日期的所有任务。检查昨日遗留读取前一天的日志文件寻找所有状态不是“已完成”的任务例如标记为“进行中”或未勾选的任务。智能合并将昨日遗留任务自动添加到今日清单的顶部或特定区域可配置确保连续性工作不被遗忘。处理临时任务你可以随时通过“把‘预约牙医’加到今天任务里”这样的指令添加临时任务技能会将其合理插入列表。4.1.2 任务重调度与依赖解析这是它的高级功能。你可以说“我需要先完成数据库设计才能开始写 API请帮我安排一下。” 技能会尝试理解任务间的依赖关系并在安排时考虑顺序。更常见的重调度指令是“我今天做不完‘性能测试’了把它移到周五。” 技能会从今天的文件中移除该任务。在周计划文件中找到“周五”部分添加该任务。更新任务的状态或添加备注。4.2 jw-agenda-daily-log从碎片汇报到结构化记录很多人有记日志的习惯但难以坚持因为整理费时。这个技能旨在解决这个问题。4.2.1 自然语言解析你不需要遵循固定模板。你可以输入“下午花了 2 小时和团队评审了 PR #123提出了几个关于错误处理的问题。”“早上阅读了关于 React Server Components 的文档有收获但还有些疑惑。”“搞定终于解决了那个跨域认证的诡异问题原因是缓存头设置不对。”技能会解析这些句子提取关键元素活动评审 PR、阅读文档、调试问题。主题/对象PR #123、React Server Components、跨域认证。时间花费2小时如果提及。成果与状态提出了问题、有收获有疑惑、已解决。情感与备注“诡异”、“终于搞定”这些都会被保留让日志更有温度。4.2.2 自动结构化输出解析后它会将条目以统一格式追加到当日日志文件中例如## 工作日志 - **[14:00-16:00] PR 评审**评审了 PR #123针对错误处理逻辑提出了三点优化建议。 - **[10:00-11:00] 学习**阅读 React Server Components 官方文档理解了核心概念但对数据获取模式仍有疑问。 - **[调试]** 解决了 API 跨域认证失败问题根本原因为响应头 Cache-Control 配置不当。这样你得到了一个既包含原始思考过程又便于后期检索和分析的结构化日志。4.3 jw-agenda-weekly-review数据驱动的复盘引擎周复盘是个人成长加速器但手动整理一周数据极其繁琐。这个技能自动化了 80% 的整理工作。4.3.1 自动化数据聚合运行“生成周度复盘”后它会扫描daily/目录下本周的所有文件。提取每一个任务条目、日志条目、时间记录如果存在。按项目、领域或标签取决于你日志中的关键词对活动进行分类。计算核心指标计划完成率本周计划任务中标记为完成的数量 / 计划任务总数* 100%。时间分布在各项目或活动类型上的总时间投入。任务流转分析多少任务从上周结转而来多少被完成多少需要继续结转4.3.2 生成洞察与建议基于聚合的数据它会生成一份包含以下部分的复盘报告整体概览核心数据仪表盘。成果展示按项目列出完成的主要工作。时间分析可视化通过文本表格时间花费帮你发现“时间黑洞”。结转事项清晰列出未完成且仍需继续的任务这是输入到下周计划的关键。困难与反思从你的日志中提取带有“困难”、“挑战”、“阻塞”等关键词的条目集中呈现。下周优化建议基于本周数据给出诸如“某项目时间投入不足”、“会议时间占比过高可考虑优化”等中性建议。个人经验坚持使用周复盘技能几个月后我最大的收获不是效率数字的提升而是对自己工作模式和节奏的清晰认知。我能明确看到在哪些类型的任务上容易低估时间哪些时段我的创造性工作效率最高这帮助我进行了更合理的日程安排。4.4 自定义与扩展让系统更贴合你jw-skills的本地 Markdown 基础使其天生易于扩展。4.4.1 定制你的文件模板如果你不喜欢默认生成的计划或日志格式你可以修改技能的模板。每个技能包内通常有一个template.md或类似文件。例如你可以在每日待办模板中加入固定的“健康检查”项目“喝 8 杯水”、“起身活动”这样每天生成的计划都会包含它们。4.4.2 通过脚本扩展分析能力由于所有数据都是 Markdown你可以用简单的 Shell 或 Python 脚本进行深度分析。例如我写了一个小脚本每月初运行统计上个月在所有日志中提到的“学习”相关条目并生成一个学习主题云图。#!/bin/bash # 简单示例统计过去30天日志中的高频技术名词 grep -r -h 学习\|阅读\|了解 ./jw-agenda-data/daily/ --include*.md | tr \n | grep -E (Docker|React|Rust|API|K8s) | sort | uniq -c | sort -nr | head -104.4.3 与其他工具集成你可以将jw-agenda-data/daily/目录软链接到 Obsidian、Logseq 等知识管理软件的仓库中这样你的计划和日志就能无缝融入你的第二大脑。同样你也可以配置一个 Git Hook在每次更新日志后自动提交实现版本化的人生记录。5. 常见问题排查与实战技巧5.1 安装与初始化问题问题1在 Cursor 中输入指令AI 没有反应似乎没有识别技能。检查清单路径确认绝对确保技能文件夹如jw-agenda-daily-todo被直接解压到了~/.cursor/skills/目录下而不是嵌套在另一层文件夹里。重启生效安装或移动技能文件后必须完全关闭并重启 Cursor。仅仅重载窗口有时不够。技能目录权限确保当前用户对~/.cursor/skills/目录有读写权限。指令清晰度尝试更具体、动词开头的指令如“请使用 jw-agenda 技能为我生成今天的任务列表”。问题2技能执行时报错提示找不到文件或路径错误。原因分析技能默认在当前工作区Workspace的根目录下寻找jw-agenda-data文件夹。如果你的数据目录在其他地方或者你在一个子文件夹中执行指令就会出错。解决方案方案A推荐始终在 Cursor 中打开包含jw-agenda-data目录的那个项目文件夹作为工作区。方案B在技能包内查找配置文件可能是config.json或skill.json尝试修改其中定义的数据目录路径。但这需要一定的技术能力。5.2 数据与同步问题问题3周计划生成时没有正确继承上周的结转事项。排查步骤检查上周的复盘文件 (weekly/YYYY-[week]-review.md) 是否成功生成并且其中“结转至下周”部分是否有明确列出的任务。检查本周计划生成指令执行时AI 是否正确地引用了上周的复盘文件。有时需要明确说明“参考上周的复盘生成本周计划”。查看生成的周计划文件内容看结转任务是否被添加到了合适的日期下。问题4手动修改了 Markdown 文件后技能似乎读不到最新内容。原因与解决技能在运行时可能会缓存文件状态或依赖于 AI 模型对文件内容的“快照”。如果手动修改后立即运行技能AI 可能还在基于旧上下文工作。技巧手动保存文件后可以在 Cursor 中执行一个无关的操作比如切换一下标签页或者更可靠的方法是在给 AI 的指令中明确提示“请注意我刚更新了周计划文件请基于最新内容操作。”5.3 使用习惯与优化问题5感觉每天都要输入指令有点麻烦。自动化技巧你可以利用 Cursor 的自定义指令Custom Commands功能。创建一个名为“Plan My Day”的自定义指令其内容就是“生成我今天要做的任务”。然后为其绑定一个快捷键如CmdShiftP。这样一个快捷键就能触发整个流程。结合习惯将“生成今日计划”作为早晨启动工作的第一个仪式将“记录一下今天的工作”作为下班前的最后一个动作形成习惯闭环。问题6生成的计划太过机械不够灵活应对突发情况。正确心态jw-agenda是为你服务的助手不是你必须严格遵守的监工。它的价值在于帮你梳理和记录而不是限制你。灵活操作随时调整用自然语言让 AI 帮你移动、删除或添加任务。接受不完美如果某天计划完全被打乱直接在日志里记录原因和实际情况。复盘时分析这些“干扰源”是偶然还是常态从而优化未来的计划弹性。聚焦核心系统帮你管理的是“你想做”和“你需要做”的事情对于纯粹的突发紧急事件正常处理即可事后在日志中补记一笔。问题7如何备份和迁移我的所有计划数据备份整个jw-agenda-data目录就是一个完整的备份。你可以用任何云盘同步工具如 Dropbox, iCloud Drive, 或国内的各种网盘同步这个文件夹或者定期用 Git 提交到私人仓库。迁移在新电脑上安装好 Cursor 和jw-skills后只需将备份的jw-agenda-data目录放到新工作区的对应位置一切就能无缝衔接。这正是本地 Markdown 文件架构的最大优势。