Awam To-Do

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install awam-todo
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 awam-todo。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Awam To-Do 是一款适用于 Openclaw Skills 的个人任务管理技能，可将对话请求转换为结构化任务，并通过 Python 3 命令行工具进行管理。它会将截止日期、优先级、备注、标签、工作区、链接和相关文档记录在按日期分类的 Markdown 文件中，并维护一个用于任务列表和摘要的 JSON 索引。
它的保护机制有助于确保任务数据可靠：重复或相似任务需要确认；未完成的依赖项和子任务可能会阻止状态变更；推断出的标签仅为建议，不会自动决定。还可使用本地网页界面浏览和编辑任务。数据保存在本地文件中；此技能不提供远程同步或团队协作功能。

应用场景

根据自然语言请求记录任务，包括截止日期、重要程度、工作区、备注、文档或链接。
按状态、日期、紧急程度、标签或逾期状态查看任务，并选择推进逾期任务或重新安排时间。
通过依赖关系链接跟踪前置事项，并将较大的任务组织为父任务和子任务。
在遵循确认保护机制的前提下，开始、完成、重新打开、推迟或归档任务。
使用本地网页看板搜索、筛选、创建和更新任务。
将现有任务数据移动到其他存储目录，或配置用于打开任务工作区的编辑器。

工作原理

使用 init 初始化环境。此技能会检测平台和路径惯例、记录配置，并尝试检测受支持的编辑器。
用户提出任务请求时，代理会提取任务文本和明确提供的字段，例如截止日期、重要程度、状态、工作区、标签、依赖项或父任务。
创建任务前，脚本会检查已存储的任务，查找完全匹配或相似的任务。如果找到匹配项，它会返回确认提示，而不会悄悄创建重复任务。
代理会向用户展示任何需要做出的选择。建议的标签也会提交用户确认，未经确认不会写入。
Python CLI 会验证任务 ID 和关系，将任务写入相应的按日期分类的 Markdown 文件，并重建 JSON 索引。
更改状态时，脚本会检查依赖项和子任务规则。如果前置事项尚未完成，或父任务仍有未完成的子任务，脚本会阻止更改，并要求代理在执行任何强制操作前征求确认。
代理可通过 CLI 列出、查看、编辑、推迟、重新打开或归档任务。也可使用本地网页界面查看和编辑任务，并通过补丁工作流保存更改。
在相关读取或写入操作时，索引会刷新，符合条件的已完成每日文件也可能会合并到每月归档中。

配置指南

Awam To-Do 需要 Python 3。请从技能目录运行脚本；SKILL.md 未指定软件包安装命令。首次使用时，请初始化环境。将示例路径替换为技能的实际位置。
python /path/to/awam-todo/scripts/todo.py init
python /path/to/awam-todo/scripts/todo.py env
python /path/to/awam-todo/scripts/todo.py list
在 Windows 上，请使用相应的 Windows 路径，并通过 python 调用脚本。若要配置存储位置，请设置 storage_dir。如果旧目录中包含数据，请明确选择迁移数据还是将其保留在原处；迁移会先复制并验证数据，然后再移除旧文件。
python /path/to/awam-todo/scripts/todo.py env --set storage_dir="/path/to/awam-todo-data" --migrate
若要配置 work 命令使用的编辑器，请设置其可执行文件路径或命令名称。必须正确配置有效的编辑器；此技能不会猜测路径，也不会悄悄回退到系统默认编辑器。
python /path/to/awam-todo/scripts/todo.py env --set editor.path=code
python /path/to/awam-todo/scripts/todo.py env --set editor.label="VS Code"
使用以下命令启动可选的本地网页界面：
python /path/to/awam-todo/web/server.py
服务器默认使用端口 8796 并打开浏览器。使用 --port 9000 选择其他端口，或使用 --no-browser 禁止启动浏览器。默认情况下，界面在本地的 http://127.0.0.1:8796/ 提供服务。

数据架构

任务数据默认存储在 Git 版本控制之外的本地位置。实际使用的存储目录可通过 env.json 配置。
文件或位置 用途
storage/YYYY-MM-DD.md 每日 Markdown 任务记录，按任务块整理，包含 ID、状态、日期和可选元数据。
storage/archive/YYYY-MM.md 每月归档，包含从每日文件中汇总的符合条件的已完成任务。
index.json 重建的 JSON 索引，包含架构版本、摘要计数、每周总数、任务分组、归档元数据和任务级字段。
env.json 本地环境设置，包括路径样式、存储目录、编辑器配置和可配置的默认值。
每日存储文件包含 schema: N 标头；技能中说明的当前架构版本为 2。索引包含 schema_version。migrate 默认会预览存储更新，而 migrate --apply 会应用更新。每月归档会保留来源文件和原始日期信息，并计入归档元数据，而不纳入日常任务分组。每周统计采用周一至周日的统计周期。缺失数据会表示为 null 或不可用的估算值，不会捏造为零。

高级特性

精确和模糊重复检测可防止自动创建重复任务；用户可以确认更新、要求新建任务或取消。
依赖关系和父子关系验证会阻止开始或完成受阻任务，除非用户确认强制操作。关系检查也会防止无效引用和循环依赖。
子任务可以拥有自己的任务属性，也可以嵌套；未完成的子任务会阻止其父任务正常完成。
自然语言截止日期解析支持常见的相对日期和时间。对于逾期任务，会提供两种明确的处理方式：推进任务，或推迟／清除其截止日期。
标签建议依据现有任务历史和关键词规则生成，但在用户批准前仅供查看，不会写入。
每日 Markdown 存储、可重建的 JSON 索引、识别架构的迁移以及自动每月归档，共同支持持久可靠的本地任务管理。
可通过 CLI 管理可配置的工作区存储和编辑器设置；存储迁移会先验证复制的数据，再删除旧文件。
本地网页看板支持筛选、搜索、任务 CRUD、状态转换、重复项和关系冲突确认、自适应布局以及内嵌 SVG 图标。
网页编辑使用待处理补丁队列、修订版本检查和合并处理，以减少与并发 CLI 更改发生冲突的情况。更改可手动保存、自动保存，或在页面关闭时保存。
此技能有意避免编造缺失的估算值或日期，也不包含远程同步、团队协作、日历管理或项目排期功能。

name: awam-todo version: 0.4.0 description: >- 输入与管理 Awam 的 To-Do：在会话中解析用户自然语言里的待办内容、重要性、备注、工作空间目录、 相关文档、链接与时间，调用脚本追加到按日期划分的存储文件，并自动维护索引（todo / in_progress / urgent / done / 归档文件）。新增时会检测相同/近似任务：相同默认更新已有状态（需用户确认）， 近似需用户确认后更新或强制新建。支持待办依赖链：可为任务标记前置依赖，推进到「进行中/结束」 时若前置依赖未结束，脚本硬性拦截（exit 3）并交由 AI 向用户确认后决定是否强制推进。 支持子任务：子任务归属于一个主任务（--parent），属性与其他任务一致；把存在未完成子任务 的主任务标记为「结束」会被硬性拦截，交由 AI 确认。支持预案：每条待办可填「最容易拦住我的 障碍」与「如果它出现，我就……」，卡片与列表直接展示。支持逾期双出口：逾期任务给出天数， 并提供「立即推进」与「调整计划（postpone 改截止日）」两个出口；被置顶的任务（逾期/停滞/今天 到期）一律带置顶理由。支持存储格式版本（文件头 schema: N、migrate 迁移）与月度归档 （进入新月自动把上月已全部完成的日文件合并进 storage/archive/YYYY-MM.md）。所有按周统计一律以 周一为起点；数据不足时一律显示「暂无推算」，不编造数字。AI 创建待办时若未给标签，脚本会推测 标签但只作为建议值展示（suggest-tags 可只读预取），确认后才写入，不代用户决定分类。 支持两条可配置能力：存储目录（env --set storage_dir，旧目录有数据时必须显式选 --migrate 搬迁或 --no-migrate 留原处，搬迁先复制、校验一致才删旧）与「用编辑器打开」的编辑器 （env --set editor.path，init 自动探测，未配置/失效时报错并停用入口，不猜路径）。 当用户说“记一下/加个待办/帮我记/安排XX/提醒我X日做XX”或显式 调用 /awam-todo 时使用；也用于列出、完成、标记进行中、重新打开、归档待办、设置依赖、管理子任务。 awam-todo（输入与管理 To-Do）

个人待办管理技能。所有数据落在本技能目录下的 storage/（不纳入 Git 管理），索引在 index.json（不纳入 Git 管理），本机环境信息在 env.json（不纳入 Git 管理， 由 init 自动生成）。核心命令见 scripts/todo.py（Python 3）。

何时用
用户意图 执行
首次使用 / 换机器后初始化环境 init（识别工作环境、探测编辑器并保存，统一工作空间）
查看 / 修改环境配置（路径风格等） env（可 --set、--reformat-workspaces）
换存储位置 / 迁移已有的待办数据 env --set storage_dir= + --migrate（见「两条可配置能力」）
换「用编辑器打开」用的编辑器 env --set editor.path=（见「两条可配置能力」）
新增一条待办 解析 → add（含重复检测，见下）
检查是否重复 check --text "..."（只读）
只读推测标签（只建议、不写入） suggest-tags --text "..."（JSON 输出）
查看待办 list（可按状态/日期筛选）
完成一条待办 done （前置依赖未结束需确认）
标记进行中 / 重新打开 start （前置依赖未结束需确认） / reopen
继续工作（标记进行中并用配置的编辑器打开工作区） work （别名 continue，前置依赖未结束需确认）
逾期了：改期 / 取消截止 postpone "下周一"（别名 reschedule / replan；--clear 取消截止）
设置 / 查看任务依赖 dep [--add/--remove/--set/--clear]
列出某主任务下的子任务 children （别名 sub）
新增子任务（归属主任务） add --parent ...
解除子任务归属 deparent
强制归档某天文件 archive YYYY-MM-DD
月度归档（上月已完成的记录） archive-month [--month YYYY-MM] [--all] [--dry-run]
旧版本存储迁移到当前 schema migrate（默认预览） / migrate --apply
查看索引（紧急/今日/逾期/进行中/开放/已完成） index
查看单条、某天文件或某月归档 `show 停滞（琥珀）> 今天到期（蓝）。凡置顶必带理由 （索引里是 pin / pin_reason），不得静默重排。
逾期必须给两个出口（这是硬要求）：
立即推进 → start / done
调整计划 → postpone "下周一"（重设截止）或 postpone --clear（取消截止）

python ...\todo.py postpone T-20261002-001 "下周一 10:00" # 改期
python ...\todo.py postpone T-20261002-001 --clear # 取消截止
python ...\todo.py list --state overdue # 只看逾期（带天数与出口提示）
python ...\todo.py list --state today # 只看今天要处理（逾期/停滞/今天到期）

时间解析不了时 postpone 直接报错并保持原值——不猜日期。

不推算原则（重要）

缺失输入时派生指标一律返回 None，渲染成 — 或 暂无推算：

指标 有数据 无数据
逾期天数 逾期 N 天 不出现该字段
距截止 N 天 —
停滞天数 N 天 —
预计完成日 需要「进展记录」样本 ≥ 3 条才推算 暂无推算（缺少进展记录）

当前版本没有进展记录层，所以预计完成日恒为「暂无推算」。这是有意为之——记录层的设计见 优化建议.md 第 7/8 条。绝不允许为了"看起来完整"而输出假数字。

周口径（写死，不要临时改）

任何按周统计一律 周一 00:00 至周日 23:59（WEEK_START_ISO = 1）。索引的 week 段给出 start / end / created / done。以后做周报环比必须同口径对比。

存储格式版本与迁移
每个存储文件头部写 schema: N（当前 SCHEMA_VERSION = 2），index.json 顶层写 schema_version。
没有 schema 行的旧文件视为 v1；migrate 默认只预览，--apply 才重写（读出来按当前格式写回， 补齐 schema 头与新字段默认值，无损）。
新增字段时：同步改 _parse_block / _write_block / _task_view / build_index，并提升 SCHEMA_VERSION，否则网页端看不到新字段。
月度归档

进入新月份后，把上月及更早、且全部任务已结束的日文件合并进 storage/archive/YYYY-MM.md， 原日文件删除；仍有未完成任务的日文件保持不动。归档文件带 月份: / 来源文件: 头， 每条任务带 原日期: 行，可用 show YYYY-MM 查看。归档文件不参与日常索引，只在 index.json 的 monthly_archives / summary.archived_tasks 里计数。

自动触发点在 build_index() 里（每个进程只跑一次，读命令也可能触发，属预期行为）； 手动触发用 archive-month，--dry-run 先看计划。

可覆盖的默认值（只是预填，不锁死）

env.json 的 defaults 段控制新增待办的默认 状态 / 重要性 / 紧急：

python ...\todo.py env --set defaults.status=待开始
python ...\todo.py env --set defaults.importance=重要

网页新建表单用同一份值预填，用户随时可改。默认值是建议值，不是约束。

数据与状态
存储：storage/YYYY-MM-DD.md，每个文件含头部 归档: true/false、schema: N 与若干任务块 （## T-YYYYMMDD-NNN + 状态/重要/紧急/内容/父任务/备注/障碍/对策/工作空间/文档/链接/标签/依赖/来源/截止/创建/更新 行）。 依赖: T-A; T-B 记录该任务的前置依赖（任务 ID）；父任务: T-X 记录该子任务归属的主任务； 标签: 工作; 学习 记录该任务的分类标签（用 ; 分隔）。 来源 from：可选对象 {type, url}，记录待办来源（如某次 AI Agent 对话链接）。由 --from-type / --from-url 写入；获取不到对话链接时留空（不落盘、不入索引）。 ID：T-YYYYMMDD-NNN，按当天递增，脚本自动生成。
状态：维护 [ ] · 进行中 [~] · 结束 [x] · 待开始 [ ] · 其他 [ ]；新增待办默认「进行中」，不再出现 open。
重要：重要 / 不重要（默认「不重要」）。
紧急：紧急 / 不紧急（默认「不紧急」）；截止在 24 小时内/已过期仍自动视为紧急。
归档不变量：某文件全部任务 done → 自动把该文件标 归档: true 并记入索引 archived_files；重新打开某任务 → 若不再全部完成，自动取消归档。
索引 index.json（脚本每次变更后自动重建）
{ "schema_version": 2,
"generated": "...",
"summary": {"todo":n, "in_progress":n, "urgent":n, "done":n, "total":n,
"archived_files":n, "files":n, "today":n, "overdue":n,
"week_created":n, "week_done":n, "monthly_archives":n, "archived_tasks":n},
"week": {"start":"YYYY-MM-DD", "end":"YYYY-MM-DD", "created":n, "done":n},
"urgent": [...], "today": [...], "overdue": [...],
"in_progress": [...], "todo": [...], "done": [...],
"archived_files": ["YYYY-MM-DD", ...],
"monthly_archives": [{"month":"YYYY-MM","files":[...],"file_count":n,"tasks":n}] }

索引条目含 depends_on（前置依赖 ID 列表）、blocked（是否存在未结束前置依赖）、parent（父任务 ID）、 tags（标签列表）、blocker / counter（预案），以及派生指标 overdue_days / due_in_days / stall_days / projected_finish / pin / pin_reason （无数据一律为 null，展示时渲染「—」/「暂无推算」）。

排序规则：向用户展示进度（list / index）时，若用户未特别说明，默认按 “置顶（逾期 > 停滞 > 今天到期）→ 紧急 → 重要性（重要>不重要）→ 有截止 → 创建时间”排列（脚本内实现）。

向用户汇报时优先用 index 的 summary 与这几个桶给一句话概览：先看 today（今天要处理）与 overdue（逾期），再看 in_progress；提到逾期时必须同时给出两个出口（推进 / 改期）。

前端实现约束（长期有效）

改 web/index.html 时必须遵守：

零外部库、零 CDN、零外链字体/图片——所有 CSS/JS/图标内联，断网可用。
图标用内联 SVG（文件内 P 图标表 + ic(name, cls) 助手），禁止 emoji。
数据不足时显示「—」/「暂无推算」，不补 0、不编日期。
破坏性操作（删除）二次确认；置顶/排序变化必须能解释原因。
悬浮/浮层定位：纵向锚定到触发元素，横向才跟随鼠标。浮层不能整体跟随鼠标，否则鼠标永远追不上、 选不中；且多卡片场景下必须取「当前 hover 的那个」浮层，不能用 document.querySelector() 取文档第一个。 浮层与触发元素之间必须用透明桥接带补上间隙，避免鼠标穿过时 :hover 断开、浮层消失。
改动后跑自测：python scripts/selftest.py（CLI 场景，临时目录，不碰真实数据） 与 node scripts/smoke-web.js（前端渲染冒烟，最小 DOM 桩）。
非目标
不做笔记、日历或项目排期；只管理待办本身。
不做多人协作 / 同步 / 远程服务。
from 的来源链接只能由 Agent 在会话上下文中取得（如当前 AI 对话链接）；取不到就留空， 脚本不会自行编造。
网页前端展示（web）

当用户要求「用网页展示待办 / 打开看板 / web 查看 / 网页操作待办」时，启动本地网页前端：

python "...\awam-todo\web\server.py" # 默认端口 8796，启动后自动打开浏览器
python "...\awam-todo\web\server.py" --port 9000 # 指定端口
python "...\awam-todo\web\server.py" --no-browser # 只启动不打开浏览器

服务常驻后台，浏览器访问 http://127.0.0.1:8796/。
网页支持：列表展示与统计、按状态/标签筛选、关键词搜索、增删改查、状态流转（开始/完成/重开/待开始）、 重复检测确认（相同/近似）、依赖链与子任务冲突确认（可强制推进）。
视图：全部 / 今日 / 进行中 / 待开始 / 已结束 / 紧急 / 逾期。 「今日」= 逾期 + 停滞 + 今天到期，每条都带置顶理由，顶部有一句口径说明。 「今日」是视图而不是入口——默认落在「全部」。
预案：新增/编辑可填「障碍」「对策」（; 无需分隔，单行文本）；卡片直接展示；搜索也会匹配预案内容。
逾期双出口：逾期卡片上直接给「立即推进」与「调整计划」两个按钮；「调整计划」弹出输入框， 支持自然语言时间（明天 / 下周一 / 3天后），也可一键清除截止。
三档响应式：手机（