TianTianSpeak 文档
文档目录 · 用 AI 制作 tasks

文档/AI 协同

怎么使用 AI 制作 tasks

你只要说清楚「练多久、每天做什么、做到什么程度」，AI 负责把它翻译成任务 JSON。任务的结构比题库更讲规则，所以提示词里要把规则交代清楚，并且一定要校验。

先试试 App 自带的「新建任务」

任务页的「新建任务」表单能做单阶段任务：每天都要完成或整体累计、若干步骤、分数线、字数、同一篇。够用就不必写 JSON。多阶段、指定文章、按年龄段选题库、徽章，才需要导入 JSON。

三步做出一个任务#

  1. 把目标说清楚

    回答四个问题：做几天（连续不要求）？每天做哪几类练习、各几次？分数线或字数线是多少？题库不限，还是限定某个题库？

  2. 复制提示词，发给 AI

    下面的提示词已经带了全部规则。把「我的目标」换成你的。

  3. 校验并导入

    存成 xxx.json，用 task.schema.json 检查；然后到「任务 → 导入任务」。App 的报错会指出哪一步有问题，把它发回给 AI 修改。

提示词：把目标写成任务#

提示词
你是 TianTianSpeak 口语练习 App 的任务制作助手。请把我的练习目标写成一个任务 JSON 文件，只输出 JSON，不要解释，不要 Markdown 代码围栏。

格式规则：
- 根对象：id（英文小写加连字符，字母数字和 ._-，不要以 custom- 开头）、name、description（可用 \n 换行）、order（"sequence" 或 "any"）、badge（可选：{id, name, icon, description}，icon 用 SF Symbol 名）、stages 或 steps（二选一，不能同时写）。
- stages：数组，每个阶段 {id, name, daily, days, steps}。daily:true 表示阶段里所有步骤每天都要达标，累计 days 个达标日（不要求连续）；daily 为 false 时不写 days。
- step：{type, mode, times, minScore, minChars, target}。
  · type 只能是 "readAloud"（朗诵）、"retell"（复述）、"speak"（口述）。
  · mode 可省略（不限模式），可写字符串或字符串数组：
    readAloud: read | recite | typing | dictation（省略时只含 read 和 recite）
    retell: normal | brief | structured | guided
    speak: diary | topic | intro | report | review
  · times 是次数（默认 1；在 daily 阶段里是每天的次数）。
  · minScore 是 0–100 的总分下限；minChars 是转写字数下限（只用于 retell、speak），可写数字，也可按年龄段写对象，键只能是 kindergarten / primary / middle / high / adult。
  · sameArticle:true 表示 times 次必须读同一篇，用了它要在根对象加 "minAppVersion": "0.5.18"。
  · target 可省略（题库不限）。需要限定时才写 {"bank": "题库id"} 或 {"bankSet": "集合名"}；不要编造题库 id。
- 一条练习记录只算给一个步骤，所以「3 篇复述，其中 1 篇极简总结」要拆成 brief×1 和不限模式×1 两个步骤。
- 不要写规则里没有的字段。

我的目标：
（例如：连续 21 个达标日。每天朗读 3 篇，每篇至少 85 分；每天复述 1 篇；每天口述一篇日记，至少 150 字。完成后给一个「21 天达人」徽章。题库不限。）

它应该给你的样子#

上面括号里的目标，对应的任务是：

habit-21.json
{
  "id": "habit-21",
  "name": "21 天口语小习惯",
  "description": "累计 21 个达标日，每天读 3 篇、复述 1 篇、口述 1 篇日记。",
  "order": "sequence",
  "badge": {"id": "habit-21", "name": "21 天达人", "icon": "flame", "description": "坚持 21 天"},
  "stages": [
    {
      "id": "daily", "name": "每日三件事", "daily": true, "days": 21,
      "steps": [
        {"type": "readAloud", "mode": "read", "times": 3, "minScore": 85},
        {"type": "retell", "times": 1},
        {"type": "speak", "mode": "diary", "times": 1, "minChars": 150}
      ]
    }
  ]
}

读懂它只要三点：daily + days 是「累计 21 个达标日」，漏一天不用重来；每个 step 的 times 是每天的次数；没写 target，题库不限。

进阶：按年龄段限定题库和字数#

同一个任务给不同年龄的孩子用，要让 AI 用 bankSets。先把题库 id 告诉它，别让它猜：

提示词（追加）
在上面规则的基础上，增加 bankSets：
"byAge": 幼儿园用 ["hsk-1","hsk-2"]；小学用 ["zh-grade-1","zh-grade-2","zh-grade-3"]；成人用 ["putonghua-50"]。
所有朗诵、复述步骤的 target 写 {"bankSet":"byAge"}。
口述读后感的 minChars：幼儿园 50、小学 100、成人 300。

题库 id 就是题库文件里的 id。自己做的题库先在 题库 里把 id 定好。当前用户的年龄段在集合里没有时，任务不能开始。

让编程 AI 一起校验#

Claude Code、Codex 等能运行命令的 AI，可以把「写 → 校验 → 修」自己跑完：

提示词（编程 AI）
按 https://www.tiantianspeak.com/docs/schemas/task.schema.json 写一个任务，保存为 ./habit-21.json。
目标：（你的目标）
写完用 Python 的 jsonschema（Draft202012Validator）校验，修到没有错误为止；
再列出每个步骤，用一句话告诉我它在要求什么。

最后那句「用一句话说每个步骤」很有用：AI 的复述和你的本意对不上，就说明哪里写错了。

常见错误#

现象原因与做法
导入提示「可能需要升级 App」mode / style / type 写了不存在的值（比如 "retelling"、"reading"）。照上面的取值表改
steps 和 stages 只能写一个二选一
daily 阶段需要 days ≥ 1 或 days 只能和 daily 一起用daily: true 必须配 days；非每日阶段不能写 days
找不到题库集合target.bankSet 的名字在 bankSets 里没定义
任务显示缺题库target.bank 指向的题库本机没有。去题库商店下载，或改成不限题库
字数条件对朗诵没效果minChars 只对复述、口述有意义
任务一导入就「完成」了不会：只统计开始之后的记录。要求太低倒是可能，提高 times 或 minScore
打字、默写没被统计朗诵步骤不写 mode 时不含它们，要明确写 "mode": "typing" 或 "dictation"

规则的完整说明在 tasks 格式。发布给别人用时，建议写上 description 把要求讲清楚，例如每天做什么、分数线是多少。