103 lines
8.1 KiB
Markdown
103 lines
8.1 KiB
Markdown
---
|
||
name: 待办事项
|
||
description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
|
||
version: 1.0.98
|
||
author: 深圳匠厂科技有限公司
|
||
metadata:
|
||
openclaw:
|
||
slug: add-todo-all
|
||
platform_kit_min_version: "1.2.11"
|
||
emoji: "📦"
|
||
category: "通用"
|
||
developer_ids:
|
||
- 78997 # 占位，请换成你的匠厂用户 ID
|
||
allowed-tools:
|
||
- bash
|
||
---
|
||
# 待办事项 （add-todo-all）
|
||
|
||
提供待办事项的创建、查看、修改、标记完成、删除、批量操作能力；支持设置截止时间、优先级、分类标签；可生成待办清单文本输出；不持久化跨会话存储，会话结束数据丢失。
|
||
|
||
## Agent 读取顺序
|
||
|
||
回答普通用户“是什么、能做什么、怎么开始”时，优先读取面向用户的 `README.md`；第一次操作步骤读 `TUTORIAL.md`。Agent 编排再按需读取 `references/CLI.md`、`references/ACTIONS.md` 和 `references/SCHEMA.md`，开发与浏览器账号细节见 `development/ACCOUNT_MANAGER.md`。
|
||
|
||
市场四个材料分别是：`README.md` → `readme_md`、`TUTORIAL.md` → `tutorial_md`、`DEMO.md` → `demo_md` / `demo_video_url`、`CHANGELOG.md` → `changelog`。
|
||
|
||
### 架构铁律（先读）
|
||
|
||
- **宿主产品入口平级**：对话任务 / 数据管理 / 定时任务是同一技能能力的不同触发场景，**同等重要**；挂哪些由本技能 UX 定义（入口定位表），详见 `development/PRODUCT_SURFACES.md`。以后宿主若增加新入口，仍是「新触发场景 + 同一内核」。
|
||
- **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
|
||
- **数据管理**：既是 **UI 执行面**（点按钮走与对话相同的闭环），也是数据与过程可见；不是「只读库」。
|
||
- **`placements`**：只决定 Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail）。其中 `row` 表示**行级入口**（宿主可呈现为操作列、行右键、行内「⋯」等；技能配什么就显示什么，无独立菜单 DSL）。数据管理技能按钮顺序见 `actions` **数组相对顺序**（详见 `references/ACTIONS.md`），无独立 sortOrder。
|
||
- **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
|
||
- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。
|
||
- **`policy`（可选）**：需要按用户/角色控制数据管理按钮或行列时，在 `actions.json` 顶层启用 Data Policy，由技能 `policy` CLI 输出 Snapshot；**未启用 = 与今日一致（L0）**。详见 `references/POLICY.md`。用户/角色数据源（飞书/库/API）属技能内部，宿主不托管。
|
||
- **`cellPresentation`（可选）**：需要数据管理「某格特殊标色/强调」时启用；技能按当前数据写入呈现（语义 tone），宿主映射主题样式；**未启用 = P0 无标色**。用途不限（超时、预警、驳回等）。详见 `references/CELL_PRESENTATION.md`。
|
||
- **业务行生命周期（有处理队列时）**：对某一行做生成/触达/私信等处理时，默认只操作「可操作」角色状态；开始抢占「进行中」；结束回写成功或失败（失败带原因）；重做靠人工改回可操作。状态名由本技能自定。详见 `references/WORK_ITEM_STATUS.md`。
|
||
- **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；文件型特殊报告才另做 `export-*`（落 `output/`）；**HTML 整页报告**写 `html/` 并用固定 Action id `render-html`（见 `references/ACTIONS.md`）。
|
||
- **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
|
||
|
||
### 如何触发（能力类型）
|
||
|
||
| 你要做什么 | Agent 怎么做 | 进任务中心？ |
|
||
|------------|--------------|--------------|
|
||
| 短查询 / 只读 / 秒级（`health` / `version` / `stats` / `list` / `get` 等） | OpenClaw bash/exec + **共享 Python** 跑 CLI（见下方「共享 Python」） | 否（CLI 当场结束） |
|
||
| 已在 `actions.json` 声明且 `executionProfile: "sync"` 的能力 | 可用 `run_skill_action`，或同等效果的短 CLI（同一内核） | 否 |
|
||
| 长耗时 / RPA / 浏览器 / 需要进度或取消；或 `executionProfile: "async"` | **必须** `run_skill_action`（先 `list_skill_actions` / `get_skill_action`） | **是**（仅因为该 Action 是 async） |
|
||
| 用户只问用法 / 能做什么 | 读根目录 `README.md`；逐步操作再读 `TUTORIAL.md`；**不要**为答用法去列目录或默认打开 `references/` | — |
|
||
|
||
### 用户意图路由表
|
||
|
||
复制为业务技能后，**必须**用本技能真实意图改写下表（保留三列结构）。格子写清：短 CLI 子命令，或 `run_skill_action` → **具体 action id**（及主要 `input`）。勿留模板占位语上线。
|
||
|
||
| 用户意图 | 准备 vs 执行 | 路由 |
|
||
|------------------------|--------------|--------------|
|
||
| （例）查询 / 统计 / 列表 | 短 CLI：`<your-read-commands>` | 否 |
|
||
| （例）写入 / 导入 / 改本地状态 | 短 CLI：`<your-prep-commands>` | 否 |
|
||
| （例）长副作用 / RPA / 需进度 | `run_skill_action` → `<your-async-action-id>`，`input.…` | 是（因该 Action 为 async） |
|
||
|
||
有长任务 / RPA 时：上表至少一行指向真实的 async action id，且该 id 须出现在 `assets/actions.json`；细节分流见 `references/CLI.md`。
|
||
|
||
|
||
|
||
## CLI 契约
|
||
|
||
必须使用宿主共享 Python runtime：
|
||
|
||
```bash
|
||
python {baseDir}/scripts/main.py <command> …
|
||
```
|
||
|
||
禁止使用 `uv run python`，也禁止向临时环境自行安装依赖。短 CLI 白名单为 `health`、`stats`、`version`、`config-path`、`init-db`、 和 `run` 是 Action 强制黑名单，必须通过 `run_skill_action` 执行。
|
||
|
||
## 面向用户问答（LLM 规则）
|
||
|
||
- 本文（`SKILL.md`）是 LLM / OpenClaw 平台读取的技能入口，**不是**用户市场说明。
|
||
- 根目录市场材料面向普通用户（见下方「文档分工」），**不是** Agent 调用契约。
|
||
|
||
当用户询问以下问题时，**必须优先读取**根目录 `README.md`（能力说明）与 `TUTORIAL.md`（逐步用法），并用用户能理解的业务语言回答：
|
||
|
||
- 这个技能是做什么的
|
||
- 这个技能怎么用
|
||
- 适合什么场景
|
||
- 使用前要准备什么
|
||
- 执行后会得到什么
|
||
- 能不能帮我完成某个业务任务
|
||
|
||
**回答「怎么用 / 能做什么」时的要求：**
|
||
|
||
1. 「能做什么 / 场景 / FAQ」以 `README.md` 为主；「第一次怎么用完」以 `TUTORIAL.md` 为主。
|
||
2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
|
||
3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录，或默认打开 `references/`、`development/`；仅当用户明确问命令、参数、集成或排错时再读 `references/`。
|
||
4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节，除非用户明确询问技术实现。
|
||
|
||
**文档读取边界：**
|
||
|
||
- **不要**把 `SKILL.md`、`references/`、`development/` 中的技术细节直接作为用户回答。
|
||
- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/`；`development/` 主要给开发者 / 编码助手，对话 Agent **不必**默认打开。
|
||
- 若市场材料与 `SKILL.md` / `references` 表述冲突：对用户展示以 `README.md` / `TUTORIAL.md` 为准；对执行契约以 `SKILL.md` / `references` 为准。
|
||
- 用户未问技术实现时，**不要**讨论 slug 命名规则；开发者问命名或 slug 时，读取 `development/NAMING.md`。
|
||
|
||
|