127 lines
6.1 KiB
Markdown
127 lines
6.1 KiB
Markdown
# 待办事项 demo（todo-skill）
|
||
|
||
> 这是匠厂 `skill-template` 的**教学型 demo**，复刻模板的分层与 Action 契约，
|
||
> 自带一份最小 mock 平台库，可以脱离宿主在本机直接跑通。
|
||
> 真实业务技能**不要** vendor `jiangchang_skill_core`（见模板 `SKILL.md`）。
|
||
|
||
## 这个 demo 演示什么
|
||
|
||
- **四层架构** `cli → service → db → util`（与 [../../scripts/](../../scripts) 一致）
|
||
- **CLI 入口**：`scripts/main.py` 子命令分发（argparse + 中文错误）
|
||
- **业务表 + 数据管理元数据**：`todos` 表 + `_jiangchang_tables` / `_jiangchang_columns`
|
||
- **Action 契约**：[assets/actions.json](assets/actions.json) 覆盖 `toolbar`/`row`/`batch`/`cron`/`agent`/`skill-detail` 六个 placement
|
||
- **sync / async 双形态**：CRUD 是 sync（当场返回）；`remind` 是 async（演示 `job_context` / `emit` / `finish` 任务流）
|
||
- **mock 平台库**：`scripts/_mock_platform/jiangchang_skill_core/`，在没有宿主时自动注入 sys.path
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 用独立的数据目录跑（避免污染默认位置）
|
||
# Windows PowerShell
|
||
$env:JIANGCHANG_USER_ID="demo_test"
|
||
$env:JIANGCHANG_DATA_ROOT="$env:TEMP\jc_demo_run"
|
||
|
||
# 1. 初始化数据库（幂等创建 todos 表 + 展示元数据）
|
||
python examples/todo_skill/scripts/main.py init-db
|
||
|
||
# 2. 新增三条待办
|
||
python examples/todo_skill/scripts/main.py todo add "写文档" -p high
|
||
python examples/todo_skill/scripts/main.py todo add "回邮件" -p normal
|
||
python examples/todo_skill/scripts/main.py todo add "买咖啡" -p low
|
||
|
||
# 3. 列出 / 按状态过滤
|
||
python examples/todo_skill/scripts/main.py todo list
|
||
python examples/todo_skill/scripts/main.py todo list -s pending
|
||
|
||
# 4. 批量标记完成（演示逗号分隔 ids，对应 actions.json 的 batch 入口）
|
||
python examples/todo_skill/scripts/main.py todo done 1,2
|
||
|
||
# 5. 统计
|
||
python examples/todo_skill/scripts/main.py todo stats
|
||
|
||
# 6. async 提醒任务（演示 job_context/emit/finish 任务流）
|
||
python examples/todo_skill/scripts/main.py remind -s 2
|
||
|
||
# 7. 删除 / 健康检查 / 版本
|
||
python examples/todo_skill/scripts/main.py todo delete 3
|
||
python examples/todo_skill/scripts/main.py health
|
||
python examples/todo_skill/scripts/main.py version
|
||
python examples/todo_skill/scripts/main.py config-path
|
||
```
|
||
|
||
数据落在 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/todo-skill/todo-skill.db`，
|
||
不设环境变量时回退到 `{系统临时目录}/jiangchang_demo_cache/demo_user/todo-skill/`。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
examples/todo_skill/
|
||
├── README.md # 本文（用户说明）
|
||
├── SKILL.md # 技能入口（Agent / LLM 读，对齐模板 frontmatter）
|
||
├── assets/
|
||
│ └── actions.json # Action 清单（6 placements × sync/async）
|
||
└── scripts/
|
||
├── main.py # CLI 入口；含 mock 平台库回退注入
|
||
├── _mock_platform/ # mock jiangchang_skill_core（仅 demo 独立运行用）
|
||
│ └── jiangchang_skill_core/
|
||
│ ├── __init__.py
|
||
│ ├── runtime_env.py # 数据根 / 用户 ID / apply_cli_local_defaults
|
||
│ ├── config.py # .env 加载与合并
|
||
│ ├── activity.py # job_context / emit / finish
|
||
│ └── diagnostics.py # health 体检
|
||
├── cli/
|
||
│ └── app.py # argparse 子命令分发
|
||
├── service/
|
||
│ ├── task_service.py # 标准命令 + remind async 编排
|
||
│ └── todo_service.py # 待办 CRUD 业务内核（多入口复用）
|
||
├── db/
|
||
│ ├── connection.py # SQLite 连接 + init_db（todos 表 + 元数据）
|
||
│ └── display_metadata.py # _jiangchang_tables/_columns 元数据 DDL
|
||
└── util/
|
||
├── constants.py # SKILL_SLUG / SKILL_VERSION
|
||
├── runtime_paths.py # 数据目录与 DB 路径
|
||
├── argparse_zh.py # 中文 argparse 错误
|
||
├── logging_config.py # stdlib logging 薄封装
|
||
└── config_bootstrap.py # .env.example → 用户 .env 合并
|
||
```
|
||
|
||
## 与真实模板的差异
|
||
|
||
| 维度 | 真实模板 | 本 demo |
|
||
|------|----------|----------|
|
||
| `jiangchang_skill_core` 来源 | 宿主共享 Python runtime（`jiangchang-platform-kit`） | 自带 mock（`scripts/_mock_platform/`） |
|
||
| RPA / 视频录制 | `RpaVideoSession` 完整链路 | 未实现（remind 仅模拟进度，不开浏览器） |
|
||
| 任务中心 UI | 宿主「Run Journal」推送 + 进度面板 | stdout 打印 JSON Lines 模拟 |
|
||
| 鉴权 | `entitlement_service` 调宿主接口 | 完全省略 |
|
||
| HTML 报告 | `render-html` action + `html/*.html` | 未实现（教学范围外） |
|
||
| 日志 | `jiangchang_skill_core.unified_logging` 统一文件日志 | stdlib logging，仅 stdout |
|
||
|
||
## 三大契约在 demo 中的对应
|
||
|
||
### 1. CLI 契约（[scripts/cli/app.py](scripts/cli/app.py)）
|
||
固定子命令：`init-db` / `todo add|list|done|delete|stats` / `remind` / `health` / `version` / `config-path`。
|
||
|
||
### 2. Actions 契约（[assets/actions.json](assets/actions.json)）
|
||
|
||
| action id | executionProfile | placements | 说明 |
|
||
|-----------|------------------|------------|------|
|
||
| `health` / `version` | sync | skill-detail | 标准 |
|
||
| `todo-add` | sync | toolbar, agent, skill-detail | 表单新增 |
|
||
| `todo-list` | sync | skill-detail, agent | 只读查询 |
|
||
| `todo-done` | sync | row, batch, agent | 行级 / 批量，含 `confirmation` |
|
||
| `todo-delete` | sync | row, batch | 行级 / 批量删除 |
|
||
| `todo-stats` | sync | skill-detail, agent | 只读统计 |
|
||
| `remind` | **async** | toolbar, cron, agent, skill-detail | 演示任务中心入口 |
|
||
|
||
### 3. 数据管理元数据（[scripts/db/connection.py](scripts/db/connection.py)）
|
||
- 业务表：`todos`（id/title/status/priority/due_at/created_at/updated_at，字段顺序即列展示顺序）
|
||
- 元数据表：`_jiangchang_tables` + `_jiangchang_columns`
|
||
- `todos` 表 `readonly=1`：增删改通过技能 Action 走，宿主不直写
|
||
|
||
## 冒烟测试
|
||
|
||
```bash
|
||
cd examples/todo_skill
|
||
python -m unittest discover -s tests
|
||
```
|