@deepseek-ai/dsh-tool-schedule 0.2.2-alpha.2 → 0.2.2-alpha.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.i18n.yaml +50 -32
- package/README.md +47 -20
- package/README.zh.md +47 -20
- package/lib/index.js +477 -445
- package/lib/types/index.d.ts +9 -8
- package/package.json +21 -16
package/README.i18n.yaml
CHANGED
|
@@ -3,68 +3,86 @@
|
|
|
3
3
|
# After editing either side, bring the other along and re-record with:
|
|
4
4
|
# pnpm run verify-translation-pairing --write packages/schedule/tool-schedule/README.md
|
|
5
5
|
/:
|
|
6
|
-
en:
|
|
7
|
-
zh:
|
|
6
|
+
en: d77b6ecc8e63e0f2
|
|
7
|
+
zh: 19ff500139aec118
|
|
8
8
|
/deepseek-ai-dsh-tool-schedule:
|
|
9
9
|
en: eb91320d8594cfca
|
|
10
10
|
zh: 7a900a2029baafa5
|
|
11
11
|
/deepseek-ai-dsh-tool-schedule/summary:
|
|
12
|
-
en:
|
|
13
|
-
zh:
|
|
12
|
+
en: c7480ff7361e0c8f
|
|
13
|
+
zh: 4b6833658ca71cb8
|
|
14
14
|
/deepseek-ai-dsh-tool-schedule/table-of-contents:
|
|
15
15
|
en: d152484eb41ac6b4
|
|
16
16
|
zh: 09388d293f9be9cb
|
|
17
17
|
/deepseek-ai-dsh-tool-schedule/use-this-package:
|
|
18
|
-
en:
|
|
19
|
-
zh:
|
|
18
|
+
en: d54bb40aa19d48e9
|
|
19
|
+
zh: 5ff029a30b4ee2c4
|
|
20
20
|
/deepseek-ai-dsh-tool-schedule/use-this-package/when-to-choose-it:
|
|
21
|
-
en:
|
|
22
|
-
zh:
|
|
21
|
+
en: 398e453a30e458b1
|
|
22
|
+
zh: 049514128eee6bda
|
|
23
|
+
/deepseek-ai-dsh-tool-schedule/use-this-package/user-authorization:
|
|
24
|
+
en: bf63fe71777703fe
|
|
25
|
+
zh: 3935ef0931f9b50f
|
|
23
26
|
/deepseek-ai-dsh-tool-schedule/use-this-package/the-four-tools:
|
|
24
|
-
en:
|
|
25
|
-
zh:
|
|
27
|
+
en: 7b192d94290c0e38
|
|
28
|
+
zh: fdb6963131cb1cab
|
|
26
29
|
/deepseek-ai-dsh-tool-schedule/use-this-package/minimal-configuration:
|
|
27
|
-
en:
|
|
28
|
-
zh:
|
|
30
|
+
en: 4da5d0e7bff6f5b3
|
|
31
|
+
zh: 093699c732eacf72
|
|
29
32
|
/deepseek-ai-dsh-tool-schedule/understand-the-implementation:
|
|
30
|
-
en:
|
|
31
|
-
zh:
|
|
33
|
+
en: b3bbc30caad60d2a
|
|
34
|
+
zh: a0c2fa3e8e085759
|
|
32
35
|
/deepseek-ai-dsh-tool-schedule/understand-the-implementation/source-map:
|
|
33
|
-
en:
|
|
34
|
-
zh:
|
|
36
|
+
en: 9d899dc328be7e20
|
|
37
|
+
zh: f0c353326e644395
|
|
35
38
|
/deepseek-ai-dsh-tool-schedule/further-exploration:
|
|
36
|
-
en:
|
|
37
|
-
zh:
|
|
39
|
+
en: d41b7d0d315a7086
|
|
40
|
+
zh: f69c26b34721ffde
|
|
38
41
|
/deepseek-ai-dsh-tool-schedule/model-experience:
|
|
39
42
|
en: 215e7ba838619b7b
|
|
40
43
|
zh: a311da3843709f90
|
|
44
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt:
|
|
45
|
+
en: eb7c154ebdf40bd7
|
|
46
|
+
zh: 40f739f10eb4c89e
|
|
47
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/what-the-model-sees:
|
|
48
|
+
en: bf567fba90b70e70
|
|
49
|
+
zh: 9b2e01bd756c9b20
|
|
50
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/what-the-model-sees/task-authorization:
|
|
51
|
+
en: 286eac8fa217213b
|
|
52
|
+
zh: 805ac84224bc2140
|
|
53
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/token-effect:
|
|
54
|
+
en: f943e9c303ec4c7b
|
|
55
|
+
zh: f44cb084c17b6d2b
|
|
56
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/shared-system-prompt/kv-cache-effect:
|
|
57
|
+
en: 8ecdb4f045cb35e5
|
|
58
|
+
zh: 46cd350ee096511d
|
|
41
59
|
/deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas:
|
|
42
60
|
en: 3039bc5e7a796b21
|
|
43
61
|
zh: 6b7a9eaf69c9ea53
|
|
44
62
|
/deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas/what-the-model-sees:
|
|
45
|
-
en:
|
|
46
|
-
zh:
|
|
63
|
+
en: c78c5a1ae65173ea
|
|
64
|
+
zh: 04533f81725efa04
|
|
47
65
|
/deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas/token-effect:
|
|
48
66
|
en: 70fb9094859d0804
|
|
49
67
|
zh: 30726b045484713c
|
|
50
68
|
/deepseek-ai-dsh-tool-schedule/model-experience/tool-schemas/kv-cache-effect:
|
|
51
69
|
en: 332231fb9f1b8146
|
|
52
70
|
zh: eace0b2e789d1c0f
|
|
53
|
-
/deepseek-ai-dsh-tool-schedule/model-experience/
|
|
54
|
-
en:
|
|
55
|
-
zh:
|
|
56
|
-
/deepseek-ai-dsh-tool-schedule/model-experience/
|
|
57
|
-
en:
|
|
58
|
-
zh:
|
|
59
|
-
/deepseek-ai-dsh-tool-schedule/model-experience/
|
|
60
|
-
en:
|
|
61
|
-
zh:
|
|
62
|
-
/deepseek-ai-dsh-tool-schedule/model-experience/
|
|
71
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/task-results:
|
|
72
|
+
en: c47b2272c94ac202
|
|
73
|
+
zh: 6a5bcfde187b3007
|
|
74
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/task-results/what-the-model-sees:
|
|
75
|
+
en: 18459cc1f3009e83
|
|
76
|
+
zh: 00a9e870dae49f58
|
|
77
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/task-results/token-effect:
|
|
78
|
+
en: 681160f74fec9bec
|
|
79
|
+
zh: c4cec94e94c56aa8
|
|
80
|
+
/deepseek-ai-dsh-tool-schedule/model-experience/task-results/kv-cache-effect:
|
|
63
81
|
en: 2fbf2175168e8244
|
|
64
82
|
zh: 9c4c1964ae59e661
|
|
65
83
|
/deepseek-ai-dsh-tool-schedule/known-limitations-and-deferred-work:
|
|
66
|
-
en:
|
|
67
|
-
zh:
|
|
84
|
+
en: a160cb125b7c20a1
|
|
85
|
+
zh: 708113b410d87d46
|
|
68
86
|
/deepseek-ai-dsh-tool-schedule/known-limitations-and-deferred-work/dev-note:
|
|
69
87
|
en: e67f633dc6fe7773
|
|
70
88
|
zh: b2ee0fbaa165910d
|
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "Preset-scoped
|
|
2
|
+
description: "Preset-scoped scheduled task tools (schedule_create, schedule_list, schedule_view, schedule_edit) over the Host ctx.schedule service, for deployments choosing which agents may manage scheduled tasks."
|
|
3
3
|
kind: "package-reference"
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
|
|
|
9
9
|
|
|
10
10
|
## Summary
|
|
11
11
|
|
|
12
|
-
Use `dsh-tool-schedule` to let an agent create, list,
|
|
12
|
+
Use `dsh-tool-schedule` to let an agent create, list, view, update, and delete Host scheduled tasks through `schedule_create`, `schedule_list`, `schedule_view`, and `schedule_edit`. A scheduled task delivers its instruction to a target Session at each occurrence of its recurrence rule. The package registers the four tools in the preset or Agent scope that mounts it; `minimal` keeps none. Tasks belong to the Host: the tools read and change any task by id, and only the delivery target names a Session. The Host `@deepseek-ai/dsh-schedule` service owns storage, scheduling, and delivery. Failures return one structured error code.
|
|
13
13
|
|
|
14
14
|
## Table of Contents
|
|
15
15
|
|
|
@@ -25,18 +25,24 @@ Use `dsh-tool-schedule` to let an agent create, list, edit, and delete durable H
|
|
|
25
25
|
<a id="use-this-package"></a>
|
|
26
26
|
## Use this package
|
|
27
27
|
|
|
28
|
-
Add the row below to a preset's plugin list when that preset's agents should manage
|
|
28
|
+
Add the row below to a preset's plugin list when that preset's agents should manage scheduled tasks. The shipped Web `standard`, `cordis`, and `ptc` presets mount it; `minimal` does not.
|
|
29
29
|
|
|
30
30
|
### When to choose it
|
|
31
31
|
|
|
32
|
-
Choose it for any preset whose agents need to schedule future work
|
|
32
|
+
Choose it for any preset whose agents need to schedule future work, and load `@deepseek-ai/dsh-schedule` in the same process: this package is only the model-facing consumer of that service. A preset that should stay capability-poor — `minimal` is the shipped example — omits the row, and its agents see no Schedule tool at all.
|
|
33
|
+
|
|
34
|
+
### User authorization
|
|
35
|
+
|
|
36
|
+
One shared `tool:schedule` system-prompt section requires explicit user authorization to create or modify tasks. Prior explicit authorization for the running scheduled task remains valid, such as pausing that task after a monitored PR merges.
|
|
33
37
|
|
|
34
38
|
### The four tools
|
|
35
39
|
|
|
36
|
-
- `schedule_create(prompt,
|
|
37
|
-
- `schedule_list()` — List every
|
|
38
|
-
- `
|
|
39
|
-
- `
|
|
40
|
+
- `schedule_create(title, prompt, rrule, target)` — Create one task; all four inputs are required. `title` has at most 120 characters and names the action and object in the user's language; keep timing, status, and ids in their fields. `prompt` is the instruction delivered at each occurrence, and `rrule` is one `DTSTART` line and one `RRULE` line in the [RFC 5545 subset of Schedule](../../../docs/subsystems/schedule.md#rrule-input). Returns the task with its generated id.
|
|
41
|
+
- `schedule_list(active?, limit?, offset?)` — List one page of every Host task, including tasks that other Sessions created. Active tasks come first by next occurrence, and paused and ended tasks follow, newest first. `active: true` keeps only active tasks and `active: false` only paused and ended tasks; `limit` is 1 through 500 and defaults to 100.
|
|
42
|
+
- `schedule_view(id)` — Read one task by id. An unknown id returns `{ id, code: 'schedule_not_found' }`.
|
|
43
|
+
- `schedule_edit(id, action, ...)` — An `update` changes at least one of `title`, `prompt`, `rrule`, `target`, and `active`; `active: false` pauses the task and `active: true` resumes it. Resume needs a future occurrence; supply a new `rrule` if the old rule is exhausted. With `expectedUpdatedAt`, an update or delete of a task that changed after that read returns `schedule_conflict` and changes nothing. A `delete` accepts no patch field and removes the task with its saved deliveries.
|
|
44
|
+
|
|
45
|
+
`target` selects the Session that receives each delivery: `this_session` delivers to the calling Session, `new_once` creates one Session at the first delivery and reuses it, and `new` creates a Session for every delivery. Omit it on edit to preserve the destination and settings. Supplying it replaces the destination; `new_once` reserves a different Session, and either creating target captures the editor's working directory and composed preset.
|
|
40
46
|
|
|
41
47
|
### Minimal configuration
|
|
42
48
|
|
|
@@ -44,7 +50,7 @@ Choose it for any preset whose agents need to schedule future work in their own
|
|
|
44
50
|
- name: '@deepseek-ai/dsh-tool-schedule'
|
|
45
51
|
```
|
|
46
52
|
|
|
47
|
-
The package declares no `Config` fields. It injects `ctx.tools` and registers the four tools once the scope resolves the Host `ctx.schedule` service, so a composition that keeps that service off mounts no
|
|
53
|
+
The package declares no `Config` fields. It injects `ctx.tools` and `ctx.systemPrompt` and registers the four tools and their shared guidance once the scope resolves the Host `ctx.schedule` service, so a composition that keeps that service off mounts no Schedule tool. Each call acts for the Agent that dispatched it.
|
|
48
54
|
|
|
49
55
|
-----
|
|
50
56
|
|
|
@@ -54,13 +60,13 @@ The package declares no `Config` fields. It injects `ctx.tools` and registers th
|
|
|
54
60
|
<details>
|
|
55
61
|
<summary>Implementation internals — click to expand</summary>
|
|
56
62
|
|
|
57
|
-
The plugin registers four `defineTool` definitions
|
|
63
|
+
The plugin registers four `defineTool` definitions and one `tool:schedule` system-prompt section in the scope that resolves `ctx.schedule`, so a preset mount decides visibility and Cordis effect ownership disposes them with the mount. The section is empty when neither `schedule_create` nor `schedule_edit` is visible through `ctx.tools.get()` in the requesting scope, including delegated scopes whose preset filters those tools. This lookup works for both Native and PTC presentation. Execution reads `exec.agent` for the acting Session. The delegation-depth guard runs first and the argument checks of `schedule_edit` run next, both before the service call. A `ScheduleInputError` keeps its code when the output schema of the tool declares that code, and every other failure becomes `internal_error`, so storage details never reach the model. Model content is the canonical JSON of the returned value, and the Host service owns persistence, scheduling, Session restoration, and delivery.
|
|
58
64
|
|
|
59
65
|
### Source map
|
|
60
66
|
|
|
61
67
|
| File | Role |
|
|
62
68
|
|---|---|
|
|
63
|
-
| [`src/index.ts`](src/index.ts) | Plugin entry: the four
|
|
69
|
+
| [`src/index.ts`](src/index.ts) | Plugin entry: the four tools, their shared guidance, output schemas, target resolution, and render/present helpers |
|
|
64
70
|
|
|
65
71
|
</details>
|
|
66
72
|
|
|
@@ -73,18 +79,38 @@ The plugin registers four `defineTool` definitions through the context that load
|
|
|
73
79
|
- [Schedule group map](../README.md) — the sibling packages in this group.
|
|
74
80
|
- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-schedule) — the exact four schemas the model receives.
|
|
75
81
|
- [Schedule subsystem](../../../docs/subsystems/schedule.md) — the `ctx.schedule` Cordis surface and stored types.
|
|
76
|
-
- [Schedule user guide](../../../docs/user/guide/schedule.md) — the user-facing
|
|
82
|
+
- [Schedule user guide](../../../docs/user/guide/schedule.md) — the user-facing scheduled task workflow.
|
|
77
83
|
|
|
78
84
|
-----
|
|
79
85
|
|
|
80
86
|
<a id="model-experience"></a>
|
|
81
87
|
## Model Experience
|
|
82
88
|
|
|
89
|
+
### Shared system prompt
|
|
90
|
+
|
|
91
|
+
#### What the model sees
|
|
92
|
+
|
|
93
|
+
One `tool:schedule` section when `schedule_create` or `schedule_edit` is visible in the calling Agent's scope. Tool descriptions retain their operation-specific guidance without repeating this policy. A `complete: true` system-prompt override replaces ordinary sections, including this one.
|
|
94
|
+
|
|
95
|
+
##### Task authorization
|
|
96
|
+
|
|
97
|
+
```markdown
|
|
98
|
+
Only create or modify scheduled tasks at the user's explicit request; prior explicit user authorization for the running scheduled task remains valid.
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
#### Token effect
|
|
102
|
+
|
|
103
|
+
One fixed sentence per assembled prompt in Native and PTC mode. Scopes that hide both mutation tools pay no cost for this section.
|
|
104
|
+
|
|
105
|
+
#### KV Cache effect
|
|
106
|
+
|
|
107
|
+
Prefix-stable while the section text and mutation-tool visibility are unchanged. Mounting, disposal, or filtering may invalidate reuse from this section.
|
|
108
|
+
|
|
83
109
|
### Tool schemas
|
|
84
110
|
|
|
85
111
|
#### What the model sees
|
|
86
112
|
|
|
87
|
-
The generated [`schedule_create`, `schedule_list`, `
|
|
113
|
+
The generated [`schedule_create`, `schedule_list`, `schedule_view`, and `schedule_edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-schedule) whenever this package is visible in the calling Agent's scope. The catalog shows the default configuration; the `target` description of `schedule_create` adds the configured spacing of `new` deliveries when it exceeds one minute.
|
|
88
114
|
|
|
89
115
|
#### Token effect
|
|
90
116
|
|
|
@@ -94,15 +120,15 @@ A fixed schema cost on every request from an Agent whose preset mounts the packa
|
|
|
94
120
|
|
|
95
121
|
Prefix-stable while tool definitions and visibility are unchanged. Mounting, disposal, or a scope change may invalidate reuse from the first changed schema token.
|
|
96
122
|
|
|
97
|
-
###
|
|
123
|
+
### Task results
|
|
98
124
|
|
|
99
125
|
#### What the model sees
|
|
100
126
|
|
|
101
|
-
One
|
|
127
|
+
One canonical JSON text block per call. `schedule_create` returns the task; `schedule_list` returns `{ items, shown, total, limit, offset }`; `schedule_view` returns the task or `{ id, code: 'schedule_not_found' }`; and `schedule_edit` returns the updated task, `{ id, deleted: true }`, `{ id, code: 'schedule_not_found' }`, or `{ id, code: 'schedule_conflict' }`. Task results discriminate all seven timing kinds with `kind` and retain their authoritative timing fields. They include `id`, `title`, `prompt`, `scheduledAt`, `scheduledAtLocal`, `target`, `status`, optional `updatedAt` for revision comparison, and optional `lastDelivery` with `scheduledAt`, `deliveredAt`, and `targetSessionId`. The model input continues to expose RRULE; a rejected call returns `{ code, message }` with a declared output code.
|
|
102
128
|
|
|
103
129
|
#### Token effect
|
|
104
130
|
|
|
105
|
-
Results remain in the calling Session's history until compaction and repeat the
|
|
131
|
+
Results remain in the calling Session's history until compaction and repeat the task summary; a `schedule_list` page costs its full rendered length, at most `limit` tasks, on every later request.
|
|
106
132
|
|
|
107
133
|
#### KV Cache effect
|
|
108
134
|
|
|
@@ -114,10 +140,11 @@ Append-only; newly visible content follows the reusable request prefix and does
|
|
|
114
140
|
|
|
115
141
|
- **No tools without the Host service** — a composition that mounts this package without `ctx.schedule` leaves the plugin pending, so none of the four tools register.
|
|
116
142
|
- **Every call needs a calling Agent** — a call dispatched without one returns `internal_error` rather than guessing a Session.
|
|
117
|
-
- **
|
|
118
|
-
- **
|
|
119
|
-
- **
|
|
120
|
-
- **
|
|
143
|
+
- **Every tool reaches every Host task** — `schedule_list` returns tasks that other Sessions created, and `schedule_view` and `schedule_edit` read, change, and delete any task by id. The authorization sentence guides model behavior; the Host does not validate user intent or add ownership checks per Session. A preset whose agents must not manage Host tasks omits the row.
|
|
144
|
+
- **Deletion does not retract a queued message** — a message that the Host already delivered stays in the target Session inbox after a `schedule_edit` delete.
|
|
145
|
+
- **Task timing belongs to the Host** — the tools expose no clock source, delivery retry, or execution result; those limits are the service's.
|
|
146
|
+
- **Every tool refuses a delegated caller** — each of the four tools reads the calling Agent's delegation depth before it calls the service and returns `{ code: 'subagent_session', message: 'A delegated subagent cannot use scheduled tasks.' }` when that depth is above zero. The guard lives in this package and reads `delegationDepthOf` from `@deepseek-ai/dsh-subagent`, the same accounting the delegation cap enforces, so it holds under any preset that mounts the tools.
|
|
147
|
+
- **A delegated child still sees the four tools** — a child joins its parent's preset, so its requests carry the four schemas and their token cost; the refusal above, not schema omission, keeps the child from managing tasks.
|
|
121
148
|
|
|
122
149
|
<a id="dev-note"></a>
|
|
123
150
|
### Dev Note
|
package/README.zh.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "
|
|
2
|
+
description: "预设作用域的定时任务工具（schedule_create、schedule_list、schedule_view、schedule_edit），基于宿主 ctx.schedule 服务，供选择哪些 agent 可以管理定时任务的部署使用。"
|
|
3
3
|
kind: "package-reference"
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -9,7 +9,7 @@ kind: "package-reference"
|
|
|
9
9
|
|
|
10
10
|
## 概述
|
|
11
11
|
|
|
12
|
-
使用 `dsh-tool-schedule`，可通过 `schedule_create`、`schedule_list`、`
|
|
12
|
+
使用 `dsh-tool-schedule`，可通过 `schedule_create`、`schedule_list`、`schedule_view` 与 `schedule_edit` 让 agent（智能体）创建、列出、查看、更新和删除宿主定时任务。定时任务在其重复规则的每个发生时点把指令投递到一个目标 Session。本包把四个工具注册进挂载它的 preset 或 Agent 作用域；`minimal` 不获得。任务属于宿主：这些工具按 id 读取和改变任意任务，只有投递目标指定 Session。存储、调度与投递由宿主 `@deepseek-ai/dsh-schedule` 服务负责。失败时返回一个结构化错误码。
|
|
13
13
|
|
|
14
14
|
## 目录
|
|
15
15
|
|
|
@@ -25,18 +25,24 @@ kind: "package-reference"
|
|
|
25
25
|
<a id="use-this-package"></a>
|
|
26
26
|
## 使用本包
|
|
27
27
|
|
|
28
|
-
当某个 preset 的 agent
|
|
28
|
+
当某个 preset 的 agent 需要管理定时任务时，把下面这一行加入该 preset 的插件列表。随产品发布的 Web `standard`、`cordis` 与 `ptc` preset 会挂载它；`minimal` 不会。
|
|
29
29
|
|
|
30
30
|
### 何时选用
|
|
31
31
|
|
|
32
|
-
当 preset 的 agent
|
|
32
|
+
当 preset 的 agent 需要安排未来工作时选用它，并在同一进程内加载 `@deepseek-ai/dsh-schedule`：本包只是该服务面向模型的消费方。需要保持能力精简的 preset——随产品发布的例子是 `minimal`——会省略该行，其 agent 完全看不到 Schedule 工具。
|
|
33
|
+
|
|
34
|
+
### 用户授权
|
|
35
|
+
|
|
36
|
+
共享的 `tool:schedule` system prompt 段落要求创建或修改任务时获得用户明确授权。用户此前为当前运行的定时任务明确授予的授权继续有效，例如在监控的 PR 合并后暂停该任务。
|
|
33
37
|
|
|
34
38
|
### 四个工具
|
|
35
39
|
|
|
36
|
-
- `schedule_create(prompt,
|
|
37
|
-
- `schedule_list()` ——
|
|
38
|
-
- `
|
|
39
|
-
- `
|
|
40
|
+
- `schedule_create(title, prompt, rrule, target)` —— 创建一个任务，四项输入均为必填。`title` 不超过 120 个字符，使用用户的语言命名动作与对象；时间、状态和 id 保留在各自字段中。`prompt` 是每个发生时点投递的指令，`rrule` 是 [Schedule 所支持的 RFC 5545 子集](../../../docs/subsystems/schedule.zh.md#rrule-input)中的一行 `DTSTART` 与一行 `RRULE`。返回任务及其生成的 id。
|
|
41
|
+
- `schedule_list(active?, limit?, offset?)` —— 列出宿主全部任务中的一页，包括其他 Session 创建的任务。活动任务按下一个发生时点排在前面，暂停与已结束的任务随后，按最新时间在前。`active: true` 只保留活动任务，`active: false` 只保留暂停与已结束的任务；`limit` 取 1 到 500，默认 100。
|
|
42
|
+
- `schedule_view(id)` —— 按 id 读取一个任务。未知 id 返回 `{ id, code: 'schedule_not_found' }`。
|
|
43
|
+
- `schedule_edit(id, action, ...)` —— `update` 至少改变 `title`、`prompt`、`rrule`、`target` 与 `active` 中的一项；`active: false` 暂停任务，`active: true` 恢复任务。恢复需要未来发生时点；旧规则耗尽时须提供新的 `rrule`。带有 `expectedUpdatedAt` 时，如果任务在那次读取之后发生过改变，更新或删除返回 `schedule_conflict` 且不做任何改变。`delete` 不接受任何补丁字段，并移除任务及其已保存的投递。
|
|
44
|
+
|
|
45
|
+
`target` 选择接收每次投递的 Session：`this_session` 投递到调用方 Session，`new_once` 在首次投递时创建一个 Session 并在之后复用它，`new` 为每次投递创建一个 Session。编辑时省略该字段可保留目的地与设置。提供该字段会替换目的地；`new_once` 预留另一个 Session，两种新建目标都会保存编辑者的工作目录与组合后的 preset。
|
|
40
46
|
|
|
41
47
|
### 最小配置
|
|
42
48
|
|
|
@@ -44,7 +50,7 @@ kind: "package-reference"
|
|
|
44
50
|
- name: '@deepseek-ai/dsh-tool-schedule'
|
|
45
51
|
```
|
|
46
52
|
|
|
47
|
-
本包不声明任何 `Config` 字段。它注入 `ctx.tools`，并在作用域解析到宿主 `ctx.schedule`
|
|
53
|
+
本包不声明任何 `Config` 字段。它注入 `ctx.tools` 和 `ctx.systemPrompt`，并在作用域解析到宿主 `ctx.schedule` 服务后注册这四个工具及其共享指导，因此保持该服务关闭的组合不会挂载任何 Schedule 工具。每次调用都代表派发该调用的 Agent 执行。
|
|
48
54
|
|
|
49
55
|
-----
|
|
50
56
|
|
|
@@ -54,13 +60,13 @@ kind: "package-reference"
|
|
|
54
60
|
<details>
|
|
55
61
|
<summary>实现内部细节——点击展开</summary>
|
|
56
62
|
|
|
57
|
-
|
|
63
|
+
插件在解析到 `ctx.schedule` 的作用域内注册四个 `defineTool` 定义与一个 `tool:schedule` system prompt 段落，因此由 preset 挂载决定可见性，并由 Cordis effect 的所有权随挂载一并释放。当请求作用域中的 `ctx.tools.get()` 既看不到 `schedule_create` 也看不到 `schedule_edit` 时，该段落为空；preset 过滤了这些工具的委派作用域也包括在内。此查询同时适用于 Native 与 PTC 呈现方式。执行时读取 `exec.agent` 作为执行操作的 Session。委派深度守卫先运行，`schedule_edit` 的参数校验随后运行，二者都在服务调用之前完成。当工具的输出 schema 声明了某个 `ScheduleInputError` 的错误码时，该错误保留其错误码；其他任何失败都变为 `internal_error`，因此存储细节不会到达模型。模型内容为返回值的规范 JSON，而持久化、调度、Session 恢复与投递都由宿主服务负责。
|
|
58
64
|
|
|
59
65
|
### 源码映射
|
|
60
66
|
|
|
61
67
|
| 文件 | 作用 |
|
|
62
68
|
|---|---|
|
|
63
|
-
| [`src/index.ts`](src/index.ts) |
|
|
69
|
+
| [`src/index.ts`](src/index.ts) | 插件入口：四个工具、共享指导、输出 schema、目标解析，以及 render/present 辅助函数 |
|
|
64
70
|
|
|
65
71
|
</details>
|
|
66
72
|
|
|
@@ -73,18 +79,38 @@ kind: "package-reference"
|
|
|
73
79
|
- [Schedule 分组映射](../README.zh.md) —— 本组内的同级包。
|
|
74
80
|
- [生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-schedule) —— 模型接收的确切四个 schema。
|
|
75
81
|
- [Schedule 子系统](../../../docs/subsystems/schedule.zh.md) —— `ctx.schedule` 的 Cordis 接线区域与存储类型。
|
|
76
|
-
- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md) ——
|
|
82
|
+
- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md) —— 面向用户的定时任务工作流。
|
|
77
83
|
|
|
78
84
|
-----
|
|
79
85
|
|
|
80
86
|
<a id="model-experience"></a>
|
|
81
87
|
## 模型体验
|
|
82
88
|
|
|
89
|
+
### 共享 system prompt
|
|
90
|
+
|
|
91
|
+
#### What the model sees
|
|
92
|
+
|
|
93
|
+
当 `schedule_create` 或 `schedule_edit` 在调用方 Agent 的作用域内可见时，模型收到一个 `tool:schedule` 段落。工具说明保留各自的操作指导，不再重复这条规则。`complete: true` 的 system prompt 覆盖会替换普通段落，本段落也包括在内。
|
|
94
|
+
|
|
95
|
+
##### 任务授权
|
|
96
|
+
|
|
97
|
+
```markdown
|
|
98
|
+
Only create or modify scheduled tasks at the user's explicit request; prior explicit user authorization for the running scheduled task remains valid.
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
#### Token effect
|
|
102
|
+
|
|
103
|
+
Native 和 PTC 模式下，每次组装 prompt 只加入一句固定文本。同时隐藏两个修改工具的作用域不承担本段落的开销。
|
|
104
|
+
|
|
105
|
+
#### KV Cache effect
|
|
106
|
+
|
|
107
|
+
段落文本与修改工具可见性不变时，前缀保持稳定。挂载、释放或过滤都可能使从该段落开始的复用失效。
|
|
108
|
+
|
|
83
109
|
### 工具 schema
|
|
84
110
|
|
|
85
111
|
#### What the model sees
|
|
86
112
|
|
|
87
|
-
只要本包在调用方 Agent 的作用域内可见，模型就会收到生成的 [`schedule_create`、`schedule_list`、`
|
|
113
|
+
只要本包在调用方 Agent 的作用域内可见，模型就会收到生成的 [`schedule_create`、`schedule_list`、`schedule_view` 与 `schedule_edit` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-schedule)。目录展示默认配置；当 `new` 投递的配置间隔超过一分钟时，`schedule_create` 的 `target` 描述会加上该间隔。
|
|
88
114
|
|
|
89
115
|
#### Token effect
|
|
90
116
|
|
|
@@ -94,15 +120,15 @@ kind: "package-reference"
|
|
|
94
120
|
|
|
95
121
|
只要工具定义与可见性不变，前缀保持稳定。挂载、释放或作用域变化都可能使从首个变化 schema token 起的复用失效。
|
|
96
122
|
|
|
97
|
-
###
|
|
123
|
+
### 任务结果
|
|
98
124
|
|
|
99
125
|
#### What the model sees
|
|
100
126
|
|
|
101
|
-
|
|
127
|
+
每次调用返回一个规范 JSON 文本块。`schedule_create` 返回任务；`schedule_list` 返回 `{ items, shown, total, limit, offset }`；`schedule_view` 返回任务或 `{ id, code: 'schedule_not_found' }`；`schedule_edit` 返回更新的任务、`{ id, deleted: true }`、`{ id, code: 'schedule_not_found' }` 或 `{ id, code: 'schedule_conflict' }`。任务结果用 `kind` 区分七种时间类型，并保留权威时间字段。结果包含 `id`、`title`、`prompt`、`scheduledAt`、`scheduledAtLocal`、`target`、`status`，可选的 `updatedAt` 用于版本比较；可选的 `lastDelivery` 包含 `scheduledAt`、`deliveredAt` 与 `targetSessionId`。模型输入继续暴露 RRULE；拒绝调用返回带已声明输出错误码的 `{ code, message }`。
|
|
102
128
|
|
|
103
129
|
#### Token effect
|
|
104
130
|
|
|
105
|
-
结果会留在调用方 Session
|
|
131
|
+
结果会留在调用方 Session 的历史中直到压缩，并重复任务摘要；一页 `schedule_list` 结果最多包含 `limit` 个任务，在之后每次请求中都付出其全部渲染长度。
|
|
106
132
|
|
|
107
133
|
#### KV Cache effect
|
|
108
134
|
|
|
@@ -114,10 +140,11 @@ kind: "package-reference"
|
|
|
114
140
|
|
|
115
141
|
- **没有宿主服务就没有工具** —— 在缺少 `ctx.schedule` 的组合中挂载本包会让插件保持挂起，四个工具都不会注册。
|
|
116
142
|
- **每次调用都需要调用方 Agent** —— 未携带 Agent 的派发返回 `internal_error`，而不会猜测某个 Session。
|
|
117
|
-
-
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
-
|
|
143
|
+
- **每个工具都能触及宿主的全部任务** —— `schedule_list` 返回其他 Session 创建的任务，`schedule_view` 与 `schedule_edit` 按 id 读取、改变和删除任意任务。授权说明约束模型行为；宿主不校验用户意图，也不增加按 Session 的归属检查。不应管理宿主任务的 agent 所用 preset 应省略这一行。
|
|
144
|
+
- **删除不会撤回已排队的消息** —— 宿主已经投递的消息在 `schedule_edit` 删除之后仍留在目标 Session 收件箱中。
|
|
145
|
+
- **任务时间由宿主负责** —— 这些工具不提供时钟来源、投递重试或执行结果；这些限制属于该服务。
|
|
146
|
+
- **每个工具都拒绝被委派的调用方** —— 四个工具都会在调用服务之前读取调用方 Agent 的委派深度，当该深度大于零时返回 `{ code: 'subagent_session', message: 'A delegated subagent cannot use scheduled tasks.' }`。该守卫位于本包内，读取来自 `@deepseek-ai/dsh-subagent` 的 `delegationDepthOf`，即委派封顶本身执行的同一份记账，因此在任何挂载这些工具的 preset 下都成立。
|
|
147
|
+
- **被委派的子 agent 仍能看到这四个工具** —— 子 agent 加入父方的 preset，因此其请求携带这四个 schema 及其 token 成本；阻止它管理任务的是上述拒绝，而不是省略 schema。
|
|
121
148
|
|
|
122
149
|
<a id="dev-note"></a>
|
|
123
150
|
### 开发备注
|