refactor(schedule): 评审落地——schema 去重提级、script 语义澄清、'0' 魔法值移除、brief 帽对齐文档

砖家评审逐条处置(采纳为主,两处按项目现实驳回):
- ①冗余合并:时区/id 规则/每会话一任务各只说一次;但 Required with op=X 的双写
  (description 行 + 参数一句)是 tool-design.md §四 明文规范,保留;
- ②create 副作用提级为独立 'Side effect:' 行,不再夹在句中;
- ③轻补返回语义一行(k=v 块 / 'Error: ...' 可修正重试),不枚举错误场景(现场回显即真语义);
- ④驳回 allOf/if-then:多平台 function-calling 子集不保证支持,严格端点 400、宽容端点忽略,
  收益归零风险为正;§四 紧凑格式就是本环境的答案;
- ⑤script 澄清三点写进描述:提供即「本回合把它写出来」、创建后不可改、缺失脚本由触发回合
  报错现场处理(非静默);
- ⑥'0' 删除(用户拍板:莫名其妙):target()/create 检查/schema 三处同步,omit 即本会话;
- ⑦揪出真 bug:文档说 brief<=40 字符、代码截 80——统一到 40,并注明 CJK 按字计、创建后不可变。

探针 6 项:省略 id 全链路正常、id='0' get/create 均拒、brief 实际截 40、list/get 无回归。
This commit is contained in:
2026-09-29 19:00:54 +08:00
parent 337f79c653
commit 23ede0fe61
3 changed files with 11 additions and 11 deletions
+1 -1
View File
@@ -68,7 +68,7 @@ function createTask(db, sessionId, cronExpr, prompt, brief, script) {
try {
db.prepare(
'INSERT INTO scheduled_tasks (session_id, cron_expr, prompt, brief, script, next_run_at, created_at) VALUES (?,?,?,?,?,?,?)'
).run(sessionId, cronExpr, prompt, String(brief || '').slice(0, 80), String(script || '').replace(/\s+/g, ' ').trim().slice(0, 80), first, Date.now());
).run(sessionId, cronExpr, prompt, String(brief || '').slice(0, 40), String(script || '').replace(/\s+/g, ' ').trim().slice(0, 80), first, Date.now());
} catch (_) {
// 单进程同步 API 下正常到不了这里(上一步已查重),仅作主键约束重复报错的兜底
const ex = db.prepare('SELECT cron_expr FROM scheduled_tasks WHERE session_id = ?').get(sessionId);
+7 -7
View File
@@ -292,7 +292,7 @@
"type": "function",
"function": {
"name": "schedule",
"description": "Manage your scheduled tasks (alarms). Each task lives on exactly one session (at most one per session) and is addressed by its home session id — the same id op=list shows (e.g. 'task-20260929-003'); omit id (or '0') to act on THIS session's task. At each trigger the prompt is delivered to the task's session as a new user message. Schedule times are interpreted in Asia/Shanghai (UTC+8). Call this ONLY when the user explicitly asks for something to run periodically or at a specific time.\n\nop=get Optional id (default: this session).\nop=list No arguments. Every task of the current user across all sessions, each row starting with its id — hand that id to get/update/delete to act on any task directly; never ask the user to switch sessions.\nop=create Always targets THIS session (id is rejected). Requires cron_expr, prompt and brief; optional script. After creating, this session retires into the task's dedicated home (archived; the user's next message starts a fresh session).\nop=update Optional id. Requires at least one of cron_expr, prompt; only given fields change.\nop=delete Optional id. Cancels that task.",
"description": "Manage scheduled tasks (alarms). Call this ONLY when the user explicitly asks for something to run periodically or at a specific time.\n\nModel: each task lives on exactly one session (at most one per session) and is addressed by its task id — the home session id shown by op=list, format 'task-YYYYMMDD-NNN'. Omit id to act on THIS session's task. At each trigger the prompt is delivered to the task's session as a new user message; prior history is archived first. Cron times are Asia/Shanghai (UTC+8). Returns are compact key=value blocks; failures come back as 'Error: ...' and are safe to retry after fixing arguments.\n\nop=get Optional id.\nop=list No arguments. All tasks of the current user across sessions, one block per task starting with its id — pass that id straight to get/update/delete; never ask the user to switch sessions.\nop=create THIS session only; id is rejected. Requires cron_expr, prompt and brief; optional script.\n Side effect: the creating session retires into the task's dedicated home — it gets archived and the user's next message starts a fresh session.\nop=update Optional id. Requires at least one of cron_expr, prompt; other fields unchanged.\nop=delete Optional id. Cancels the task.",
"parameters": {
"type": "object",
"required": [
@@ -308,27 +308,27 @@
"update",
"delete"
],
"description": "Operation to perform. Tasks are addressed by their home session id."
"description": "Operation to perform."
},
"id": {
"type": "string",
"description": "Task handle: the session id the task lives on, exactly as listed by op=list. Omit (or '0') to act on THIS session's task. Allowed with get/update/delete; op=create rejects it (new tasks always live in this session)."
"description": "Task id as shown by op=list (the session the task lives on). Omit for THIS session's task. Not allowed with op=create."
},
"cron_expr": {
"type": "string",
"description": "Standard 5-field cron expression in Asia/Shanghai (UTC+8), e.g. '0 9 * * *' for 09:00 Beijing time every day. The interval between two consecutive runs must be at least 1 hour. Required with op=create; optional with op=update (next run time is recomputed)."
"description": "Standard 5-field cron expression, e.g. '0 9 * * *' for 09:00 daily. Runs must be at least 1 hour apart — denser expressions are rejected (not silently adjusted). Required with op=create; optional with op=update (recomputes next run)."
},
"prompt": {
"type": "string",
"description": "The message to send to this session at each trigger. Write it as a self-contained instruction: previous conversation history is archived before each run, so this prompt is the only input the model will see. The output stays in this session for the user to view; if it must reach the user proactively, state how in the prompt (e.g. via a skill or webhook). Required with op=create; optional with op=update."
"description": "Self-contained instruction delivered as the only input at each trigger (prior history is archived). Output stays in the task's session; if the result must reach the user proactively, say how inside the prompt (e.g. via a skill or webhook). Required with op=create; optional with op=update."
},
"brief": {
"type": "string",
"description": "One short plain-language line (<= 40 chars) saying what this task actually accomplishes, e.g. 'collect and produce a daily news PDF report'. It is written into the assistant's long-term memory diary so the recurring job can be recalled later. Required with op=create."
"description": "One short plain line (<= 40 characters; CJK counts as 1) saying what the task accomplishes, e.g. 'collect and produce a daily news PDF report'. Goes into the assistant's long-term memory diary. Required with op=create; immutable afterwards."
},
"script": {
"type": "string",
"description": "Optional marker for op=create: a script filename (relative to the session working dir) meant to carry this task's routine, so triggers reuse muscle memory instead of redoing everything. Supplying it signals you should distill the workflow into that script (language, invocation and how the prompt wires it are yours to decide). Existence is never validated — not at create, not at trigger."
"description": "Optional for op=create. A script filename (relative to the session working dir) meant to carry this task's routine so triggers reuse muscle memory instead of redoing everything. Supplying it means: distill the workflow into that script NOW (language, invocation and how the prompt references it are yours to decide). Never validated at create or trigger — a missing/broken script surfaces as a runtime error in the trigger turn. Immutable afterwards."
}
}
}
+3 -3
View File
@@ -940,7 +940,7 @@ function toolScheduleTask(ctx, args) {
// 目标会话解析:无 id → 本会话;有 id → 存在 + 同用户,否则报错(不静默降级,防 AI 拿错目标静默误删)。
const target = () => {
const raw = String(args.id == null ? '' : args.id).trim();
if (!raw || raw === '0' || raw === ctx.sessionId) return ctx.sessionId;
if (!raw || raw === ctx.sessionId) return ctx.sessionId;
const s = db.prepare('SELECT user FROM sessions WHERE id = ?').get(raw);
if (!s) throw new Error('id 指向的会话不存在:' + raw + '(op=list 可看各任务所属会话 id)');
if (String(s.user || '') !== curUser()) throw new Error('无权操作其他用户的会话任务');
@@ -956,10 +956,10 @@ function toolScheduleTask(ctx, args) {
}
case 'create': {
const raw = String(args.id == null ? '' : args.id).trim();
if (raw && raw !== '0' && raw !== ctx.sessionId) throw new Error('op=create 只作用于当前会话:新任务住进本会话并于本回合收尾后收口退位成专柜(定时即下班),无需也不能指定其它会话 id');
if (raw && raw !== ctx.sessionId) throw new Error('op=create 只作用于当前会话:新任务住进本会话并于本回合收尾后收口退位成专柜(定时即下班),无需也不能指定其它会话 id');
if (!cronExpr) throw new Error('op=create 缺少必填参数 cron_expr');
if (!prompt) throw new Error('op=create 缺少必填参数 prompt');
const brief = String(args.brief || '').replace(/\s+/g, ' ').trim().slice(0, 80);
const brief = String(args.brief || '').replace(/\s+/g, ' ').trim().slice(0, 40);
// script 纯标记:存在即暗示模型把流程沉淀成脚本(怎么写、用什么跑、prompt 怎么引用由它自定);
// 创建与触发均不校验——缺脚本时 prompt 自身的指示就是回退面。
const script = String(args.script || '').replace(/\s+/g, ' ').trim().slice(0, 80);