待办事项 demo（todo-skill）

这是匠厂 skill-template 的教学型 demo，复刻模板的分层与 Action 契约，自带一份最小 mock 平台库，可以脱离宿主在本机直接跑通。真实业务技能不要 vendor jiangchang_skill_core（见模板 SKILL.md）。

这个 demo 演示什么

四层架构 cli → service → db → util（与 ../../scripts/ 一致）
CLI 入口：scripts/main.py 子命令分发（argparse + 中文错误）
业务表 + 数据管理元数据：todos 表 + _jiangchang_tables / _jiangchang_columns
Action 契约：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

快速开始

# 用独立的数据目录跑（避免污染默认位置）
# 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）

固定子命令：init-db / todo add|list|done|delete|stats / remind / health / version / config-path。

2. Actions 契约（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）

业务表：todos（id/title/status/priority/due_at/created_at/updated_at，字段顺序即列展示顺序）
元数据表：_jiangchang_tables + _jiangchang_columns
todos 表 readonly=1：增删改通过技能 Action 走，宿主不直写

冒烟测试

cd examples/todo_skill
python -m unittest discover -s tests

README.md Unescape Escape