add-todo-all/development/REQUIREMENTS.md

REQUIREMENTS

0. 技能标识

• 拟定 slug（英文，符合 development/NAMING.md）：add-todo-all
• 中文 name：待办事项
• 中文 description（一句话）：提供待办事项的创建、查看、标记完成、删除、批量操作能力；支持设置截止时间与优先级；数据持久化在本地 SQLite。
• account-manager platform_key（如有）：无（纯本地数据技能，不涉及外部账号登录）
• 命名形态：标准型
• 网页 RPA（如有）— 登录策略： not_needed
  • 本技能不涉及任何网页自动化、浏览器操作或外部系统登录，所有数据存储与操作均在本地 SQLite 中完成。
  • 不调用 account-manager，不使用 profile_dir。

0.1 宿主入口定位

主能力（Action id / CLI）	对话	数据管理	定时	不挂理由（若不挂）
todo add	挂	toolbar（新增按钮）	不挂	定时无意义
todo list	挂	仅展示表	不挂	定时无意义
todo done	挂	row + batch（标记完成）	不挂	定时无意义
todo delete	挂	row + batch（删除）	不挂	定时无意义
todo stats	挂	toolbar（统计）	不挂	定时无意义
remind	挂	toolbar	挂	定时扫描到期/待办项并提醒
init-db	不挂	不挂	不挂	宿主安装/更新时静默调用，不对用户暴露
health	不挂	不挂	不挂	内部诊断命令
version	不挂	不挂	不挂	内部诊断命令
config-path	不挂	不挂	不挂	内部诊断命令

说明：

• todos 表在数据管理中为整表只读（readonly=1），所有增删改必须通过技能 Action（todo add/done/delete）走，宿主不直写业务表。
• 数据管理页面默认展示列：title、status、priority、due_at、created_at；默认按 created_at 倒序。
• status 与 priority 字段在数据管理中以下拉枚举展示（pending=待办/done=完成；high=高/normal=中/low=低）。

0.2 AI + RPA 协作与授权边界

Agent 设计

• 用户会怎样描述本任务：
  • “帮我加一条待办：周五前提交周报，优先级高。”
  • “帮我看看有哪些待办。”
  • “把第 1、3 条标记为完成。”
  • “把第 2 条删掉。”
  • “统计一下待办情况。”
• 支持哪些用户意图；分别映射到哪个 Action：
  • 新增待办 → todo add
  • 查看列表 → todo list
  • 标记完成 → todo done
  • 删除待办 → todo delete
  • 统计概览 → todo stats
  • 到期提醒 → remind（async）
• 每种意图必须提取哪些参数：
  • 新增：title（必填）、priority（可选，默认 normal）、due_at（可选，Unix 秒）
  • 查看列表：status（可选，pending/done）、limit（可选，默认 100）
  • 标记完成：ids（必填，单个或逗号分隔多个）
  • 删除：ids（必填，单个或逗号分隔多个）
  • 提醒：seconds（可选，模拟运行秒数，默认 3）
• 缺少哪些参数时必须追问：
  • 新增时缺少 title 必须追问
  • 标记完成/删除时缺少 ids 必须追问
• 哪些动作必须先展示对象、数量和影响，再取得明确确认：
  • 批量删除（影响多条数据，删除不可恢复）
  • 批量标记完成（可提示将标记的数量）
• Agent 最终如何解释成功、部分成功、失败、等待人工和停止：
  • 成功：返回操作后的待办数据或统计结果
  • 部分成功：批量操作中逐条返回 ok/id/error，告知哪些成功哪些失败及原因
  • 失败：返回 ERROR: 前缀 + 中文原因（如标题为空、编号不存在、已完成不可重复标记）
  • 等待人工：本技能无外部依赖，无需人工介入
  • 停止：async 任务支持 JobStopped 取消

授权与平台边界

• 目标浏览器 / 桌面软件 / 手机 App：无
• 账号、设备、数据和业务权限由谁授权：无需外部授权，数据存于本地 SQLite
• 是否有获得授权的官方 API；若不用，原因是什么：不涉及外部系统
• 目标平台规则、合同或客户约定中的自动化边界：不适用
• 明确禁止的实现路线：不适用（无外部交互）
• 正常界面无法闭环时的上报与停止条件：不适用

RPA 风控设计

不适用。本技能为纯本地数据操作，不涉及任何 RPA、浏览器、桌面或移动端自动化。

0.3 业务行生命周期

不适用。

本技能的 todos 表为用户直接管理的 CRUD 数据，不存在自动处理队列：

• pending → done 的状态变更由用户主动触发（todo done），非技能自动捞起处理。
• 无「进行中」抢占、无失败重试、无跳过逻辑。
• 因此不适用 WORK_ITEM_STATUS.md 的处理队列生命周期。

1. 文档目标

• 本文档用于明确 add-todo-all 的研发范围、交付标准、依赖关系和验收要求。
• 技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。

2. 业务背景

• 当前用户在日常工作中需要管理个人或团队的待办事项，人工记录容易遗漏且难以批量管理。
• 现有流程主要依赖手动记录，存在「不易追踪进度、无法批量操作、缺少到期提醒」等问题。
• 因此需要开发 add-todo-all，用于在本地自动完成待办的创建、查询、状态变更、批量删除与到期提醒，输出结构化 JSON 结果并持久化到本地 SQLite。

3. 开发目标

• 解析并校验待办输入的关键字段（标题非空、优先级合法、状态合法）
• 通过本地 SQLite 完成待办的增删改查
• 输出结构化结果（stdout JSON）
• 写入业务表 todos（含 created_at / updated_at Unix 秒级时间戳）
• 支持失败可诊断（稳定错误信息、ERROR: 前缀）
• 完成 CLI 入口与 health / version / init-db 最小可运行验证
• 实现 async 提醒任务范式（job_context + emit + finish）

4. 功能范围

必须实现

• 支持 python scripts/main.py health（运行时健康检查）
• 支持 python scripts/main.py version（版本信息 JSON）
• 支持 python scripts/main.py init-db（幂等建库与数据管理元数据）
• 支持 python scripts/main.py todo add <title> [-p high|normal|low] [-d <unix秒>]（新增待办）
• 支持 python scripts/main.py todo list [-s pending|done] [-n <limit>]（列出待办，默认 100 条，按创建时间倒序）
• 支持 python scripts/main.py todo done <id>（标记完成，支持逗号分隔批量）
• 支持 python scripts/main.py todo delete <id>（删除，支持逗号分隔批量）
• 支持 python scripts/main.py todo stats（统计总数/待办数/完成数）
• 支持 python scripts/main.py remind [-s <秒>]（async 提醒任务，演示进度推送与终态上报）
• 支持 python scripts/main.py config-path（输出 .env 与模板路径）
• 业务内核统一在 service/todo_service.py，CLI / Action / 数据管理按钮共用同一内核
• 数据管理元数据：todos 表及字段具备中文 display_name，状态/优先级为枚举下拉，整表只读

可后续扩展

• 支持失败自动重试
• 支持多用户/多工作空间隔离
• 支持分类标签
• 支持截止时间到期的真实推送通知（当前 demo 仅统计，不做真实推送）

5. 非功能要求

• 目录结构必须符合当前 skill-template 规范
• 入口必须统一为 scripts/main.py
• 用户市场四 Tab 写在根 README.md / TUTORIAL.md / DEMO.md / CHANGELOG.md；LLM/运行契约写在 SKILL.md；开发规范在 development/
• 输出格式应尽量机读友好；错误前缀统一为 ERROR:
• Windows 环境下需保证 UTF-8 输出兼容
• 必须具备基本日志能力；敏感字段脱敏
• 业务表时间字段统一使用 Unix 秒级整数（created_at / updated_at）
• 数据管理展示顺序由 PRAGMA table_info 的 cid 决定，不依赖 display_order

6. 输入输出要求

输入

• title：待办标题，必填，非空字符串
• priority：优先级，可选，枚举 high / normal / low，默认 normal
• due_at：截止时间，可选，Unix 秒整数，默认 null
• status：列表过滤状态，可选，枚举 pending / done
• limit：列表返回上限，可选，整数，默认 100
• ids：标记完成/删除的待办编号，必填，单个数字或逗号分隔的数字列表
• seconds：提醒任务模拟运行秒数，可选，整数，默认 3
• 环境变量 / .env：本技能无强制环境变量依赖（.env.example 为模板通用项，本技能不使用 RPA 相关配置）

输出

• 成功结果（stdout JSON）：
  • 新增：单条待办对象 {id, title, status, priority, due_at, created_at, updated_at}
  • 列表：{count, items: [Todo...]}
  • 标记完成/删除：{count, items: [{ok, id, ...}]}
  • 统计：{total, pending, done}
• 错误输出：
  • ERROR:TODO_INVALID: <原因>（标题为空、优先级非法等）
  • 批量操作中失败项返回 {ok: false, id, error}
• 数据库记录：表 todos，字段 id, title, status, priority, due_at, created_at, updated_at
• async 提醒任务：通过 emit 推送进度，通过 finish 上报终态

7. 依赖的兄弟技能或外部系统

兄弟技能依赖

• 无（不依赖 account-manager 或其他兄弟技能）

外部系统依赖

• 无（纯本地 SQLite 存储，不访问任何外部 API 或网页）
• Gitea / 匠厂客户端：发布与正式环境验证

Python 包依赖（requirements.txt）

• 本技能无特有 Python 三方包依赖（仅使用 Python 标准库 sqlite3、argparse、asyncio、json 等）
• jiangchang-platform-kit 由宿主共享 runtime 提供，不写入 requirements

8. 不在本次范围内的内容

• 本次不实现分类标签功能
• 本次不实现多用户/多工作空间隔离
• 本次不实现截止时间到期的真实推送通知（remind 仅为 async 范式演示，统计后不做真实推送）
• 本次不实现失败自动重试
• 本次不兼容旧模板历史结构（docs/、optional/、skill_main.py 等）

9. 验收标准

• 代码结构符合模板规范；SKILL.md slug 与 constants.SKILL_SLUG 一致
• health、version、init-db 命令执行正常
• python tests/run_tests.py -v 必跑测试全部通过
• todo add / todo list / todo done / todo delete / todo stats 命令在本地真实跑通
• 业务表 todos 写入和查询符合 references/SCHEMA.md（含 created_at / updated_at Unix 秒级规范）
• init_db() 已写入 _jiangchang_tables / _jiangchang_columns；todos 表及字段具备中文 display_name
• todos 表 readonly=1，字段 editable=0，宿主不直写业务表
• status / priority 字段具备 options_json 枚举下拉
• 字段展示顺序与 PRAGMA table_info(todos) 的 cid 一致；不依赖 display_order
• tests/test_display_metadata.py 通过
• SKILL.md 的 developer_ids 已配置为开发者本人匠厂用户 ID
• 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装
• 安装后按本技能入口定位表与 actions.json 声明完成宿主多入口验收

10. 开发注意事项

• 只修改当前 skill 仓库，不要改动无关兄弟项目
• cli 只做参数解析；核心业务逻辑在 service/todo_service.py
• 单业务内核、多入口：CLI / Action / 数据管理按钮都调用 todo_service 的同一函数，禁止按入口分叉业务行为
• 数据表为只读，所有增删改通过技能 Action 走，宿主不直写
• 发布前完成本地验证、工作流验证和正式环境安装验证（含 developer_ids 与宿主多入口）

11. 变更记录

日期	版本	变更人	变更内容
2026-09-07	v0.1.0	-	初版需求文档