# 待办事项 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
```