227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
# 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 宿主入口定位
|
||
|
||
|---------------------------|------|----------|------|--------------------|
|
||
| `todo add` | 挂 | toolbar（新增按钮） | 不挂 | 定时无意义 |
|
||
| `todo list` | 挂 | row | 不挂 | 定时无意义 |
|
||
| `todo done`（Action `todo-done-row`） | 挂（短 CLI 直调） | row（「完成」按钮） | 不挂 | 定时无意义；batch 批量完成暂未声明 |
|
||
| `todo delete` | 挂 | row（「删除」按钮）) + batch（删除） | 不挂 | 定时无意义 |
|
||
| `todo stats` | 挂 | toolbar（统计） | 不挂 | 定时无意义 |
|
||
| `remind` | 挂 | toolbar | 挂 | 定时扫描到期/待办项并提醒 |
|
||
| `init-db` | 不挂 | 不挂 | 不挂 | 宿主安装/更新时静默调用，不对用户暴露 |
|
||
| `health` | 不挂 | 不挂 | 不挂 | 内部诊断命令 |
|
||
| `version` | 不挂 | 不挂 | 不挂 | 内部诊断命令 |
|
||
| `config-path` | 不挂 | 不挂 | 不挂 | 内部诊断命令 |
|
||
|
||
说明：
|
||
|
||
- 数据管理页面默认展示列：`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 | - | 初版需求文档 |
|
||
| 2026-09-11 | v0.1.1 | - | 入口定位表登记行级 Action `todo-done-row`（todos 表操作列「完成本行」，sync/direct，`$row.$pk` 预填） |
|