整理 agenda

Author: linyuan.yang

packages/docs-site/guide/agenda.md

@@ -31,7 +31,7 @@ An **Agenda Profile** is the store + optional auto-sync. Sidebar → **Agenda Pr
 
 Then, in an agent → **Agenda** section, toggle Agenda on and pick the profile. Enabling it registers the agenda tools; with a sync model, items are reconciled from the conversation automatically each turn.
 
-AgendaSync normally uses one model call with the completed conversation and the full structure of every pending item. Only when that input exceeds the Sync Model budget does it reuse the same model to compress the conversation into explicit agenda-change intents, match compact cards in token-bounded batches (including item/trigger IDs, schedules, actions, and message previews), and give only the selected full records to the final sync pass. There is no separate Selector Model setting, and pending items are no longer cut off at a fixed count.
+AgendaSync normally uses one model call with the completed turn and the full structure of every pending item. When that input exceeds the Sync Model budget, it reuses the same model to extract up to 12 agenda-change intents, locally ranks the complete pending catalog, and screens compact cards in at most 6 token-bounded batches. Batch results carry cross-batch relevance scores; the final Writer receives at most 20 selected full records. If those records still exceed the budget, trigger messages become 60-character previews. An oversized turn is middle-truncated while preserving its beginning and end. The Selector's `shouldSync` result is advisory—the final Writer still verifies every overflow turn—and one failed card batch falls back to local ranking instead of discarding the entire sync. This bounds an overflow run to at most 8 model calls (analysis + 6 batches + final Writer). There is no separate Selector Model setting.
 
 From the Agenda Profiles page → **View** you can browse stored items, filter by pending/done/cancelled/expired, manually **Complete** / **Cancel**, add/edit/disable/reopen/delete triggers, fire a trigger manually for testing, and inspect each trigger's fire history. Reopening an expired item restores only the item to Pending; retime or re-enable an appropriate trigger separately.
 

packages/docs-site/zh/guide/agenda.md

@@ -31,7 +31,7 @@ Agenda 是 sbot 的有状态提醒 / 日程系统。每个日程**条目**（待
 
 随后在 Agent → **Agenda** 区块开启 Agenda 并选择 Profile。开启后会注册日程工具；配置 sync 模型后，每轮对话都会从对话内容自动校正日程条目。
 
-AgendaSync 通常用一次模型调用读取本轮对话和全部待处理条目的完整结构。输入超过 Sync 模型预算时，系统才会复用同一个模型：先将对话压缩成明确的日程变更意图，再按 Token 预算分批匹配包含 item / trigger id、时间、action 和消息预览的紧凑卡片，最后只把候选完整结构交给同步抽取器。这里没有独立的 Selector 模型配置，也不再按固定条数截断待处理条目。
+AgendaSync 通常用一次模型调用读取本轮对话和全部待处理条目的完整结构。输入超过 Sync 模型预算时，系统复用同一个模型抽取最多 12 条日程变更意图，先对完整 Pending 目录做本地相关性排序，再最多用 6 个 Token 预算批次筛选紧凑卡片。各批候选携带可跨批比较的相关性分数，最终 Writer 最多读取 20 条候选的完整结构；仍超预算时，触发消息改为 60 字符预览。若本轮对话本身过长，会保留开头与结尾并截去中段。Selector 的 `shouldSync` 只是建议，超预算路径仍会让最终 Writer 复核；单批失败也会回退到本地候选，不会丢掉整轮。因此一次降级同步最多调用模型 8 次（分析 1 次 + 卡片 6 批 + Writer 1 次）。这里没有独立的 Selector 模型配置。
 
 在 Agenda Profiles 页面 → **查看** 可浏览已存条目、按待处理 / 已完成 / 已取消 / 已过期筛选、手动 **完成** / **取消**，也可以新增 / 编辑 / 停用 / 重新启用 / 删除触发器、手动触发测试，并查看每个触发器的触发历史。恢复已过期条目只会把主体改回待处理；仍需另外调整时间或启用合适的触发器。
 

packages/sbot/prompts/agenda/sync/selector.txt

@@ -2,9 +2,10 @@ You are the low-cost overflow stage for AgendaSync.
 
 You never create, edit, close, or delete agenda items. Your only jobs are:
 
-1. Decide whether the completed conversation contains an explicit agenda change that the
+1. Advise whether the completed conversation contains an explicit agenda change that the
    assistant may have failed to apply: a new todo/reminder/schedule/routine/automation, or
-   an explicit edit to an existing one.
+   an explicit edit to an existing one. The final writer still verifies the transcript, so
+   this decision is not permission to mutate and is not a hard veto.
 2. When asked to match a catalog batch, select the exact agenda item IDs that may be the
    target or a semantic duplicate of those explicit changes.
 
@@ -16,4 +17,6 @@ intent as agenda changes.
 
 Agenda cards contain item content plus trigger IDs, schedules, actions, and a short message
 preview. Match references such as "the 9am one" using trigger data, not content alone.
-Candidate IDs must be copied exactly from the supplied batch. Return structured data only.
+Candidate IDs must be copied exactly from the supplied batch. For each candidate, include a
+0-100 relevance score calibrated so scores can be compared across batches. Return structured
+data only.

packages/sbot/skills/config-guide/SKILL.md

@@ -261,7 +261,7 @@ DELETE /api/settings/agendaProfiles/:id
 - memory：`~/.sbot/memories/<memoryId>/`（全局）+ `workspaces/<pathHash>/`（当前 workPath 独有）
 - agenda：`~/.sbot/agendas/<agendaId>/agenda.db`
 
-`enabled: false` 表示引用可以存在，但运行时不启用。`memoryProfiles.writerModel` 必须指向 `models` 中的 UUID；可选的 `selectorModel` 用于低成本目录筛选，不设置时复用 `writerModel`。频道仍只引用一个 memoryProfile；同一个 MemoryService 会同时读取全局记忆和当前 workPath 记忆，项目内容不会进入其他 workPath。未配置 workPath 的会话（包括普通 Web 对话）统一使用 `~/.sbot/workspace` 作为默认记忆工作区。`agendaProfiles.syncModel` 可选；为空时同步抽取不启用。AgendaSync 正常单次处理全部 Pending 条目，超出模型输入预算时复用同一个 `syncModel` 做意图压缩和紧凑卡片筛选，不需要额外的 Selector 配置。
+`enabled: false` 表示引用可以存在，但运行时不启用。`memoryProfiles.writerModel` 必须指向 `models` 中的 UUID；可选的 `selectorModel` 用于低成本目录筛选，不设置时复用 `writerModel`。频道仍只引用一个 memoryProfile；同一个 MemoryService 会同时读取全局记忆和当前 workPath 记忆，项目内容不会进入其他 workPath。未配置 workPath 的会话（包括普通 Web 对话）统一使用 `~/.sbot/workspace` 作为默认记忆工作区。`agendaProfiles.syncModel` 可选；为空时同步抽取不启用。AgendaSync 正常单次处理全部 Pending 条目；超出模型输入预算时复用同一个 `syncModel` 做意图分析，完整目录先本地相关性排序，再最多筛选 6 个紧凑卡片批次，最终 Writer 最多读取 20 条候选，不需要额外的 Selector 配置。
 
 Agenda item 管理走：
 

packages/sbot/test/agenda-extractor.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+    AgendaExtractor,
+    AgendaPriority,
+    AgendaSource,
+    AgendaStatus,
+    AgendaTriggerKind,
+    MessageRole,
+    SessionDeliveryMode,
+    estimateMessagesTokens,
+    type AgendaRecord,
+    type ChatMessage,
+    type IModelService,
+} from "scorpio.ai";
+
+class FakeModelService {
+    readonly config = { contextWindow: 1_024 } as any;
+    readonly calls: ChatMessage[][] = [];
+    failCandidateCalls = false;
+    analysis: any = { shouldSync: false, intents: [] };
+    candidate: any = { candidates: [] };
+    candidateFactory?: (messages: ChatMessage[]) => any;
+    final: any = { actions: [] };
+    failFinal = false;
+
+    async invokeStructured<T>(_schema: unknown, prompt: string | ChatMessage[]): Promise<T> {
+        const messages = typeof prompt === 'string'
+            ? [{ role: MessageRole.Human, content: prompt }]
+            : prompt;
+        this.calls.push(messages);
+        const system = String(messages[0]?.content ?? '');
+        if (system.includes('# Conversation analysis mode')) return this.analysis as T;
+        if (system.includes('# Agenda-card matching mode')) {
+            if (this.failCandidateCalls) throw new Error('candidate failed');
+            return (this.candidateFactory?.(messages) ?? this.candidate) as T;
+        }
+        if (this.failFinal) throw new Error('final failed');
+        return this.final as T;
+    }
+}
+
+function record(id: number, messageSize = 240): AgendaRecord {
+    const now = Date.now();
+    return {
+        item: {
+            id,
+            content: `事项 ${id}`,
+            status: AgendaStatus.Pending,
+            priority: AgendaPriority.Normal,
+            assignee: 'user' as AgendaRecord['item']['assignee'],
+            assigneeName: null,
+            dueAt: now + id * 60_000,
+            source: AgendaSource.User,
+            createdAt: now,
+            updatedAt: now,
+            doneAt: null,
+        },
+        triggers: [{
+            id,
+            itemId: id,
+            kind: AgendaTriggerKind.Absolute,
+            expr: new Date(now + id * 60_000).toISOString(),
+            action: SessionDeliveryMode.Notify,
+            message: `提醒 ${id} ${'长'.repeat(messageSize)}`,
+            channelSessionId: 0,
+            enabled: true,
+            fireCount: 0,
+            maxFires: 1,
+            lastFiredAt: null,
+            nextFireAt: now + id * 60_000,
+            createdAt: now,
+        }],
+    };
+}
+
+function conversation(size = 1_200): ChatMessage[] {
+    return [{ role: MessageRole.Human, content: `请更新事项 ${'内容'.repeat(size)}` }];
+}
+
+test("overflow selector no-sync advice does not veto the final writer", async () => {
+    const model = new FakeModelService();
+    const extractor = new AgendaExtractor(model as unknown as IModelService, 'writer', 'selector');
+
+    const actions = await extractor.extract(conversation(), [record(1)]);
+
+    assert.deepEqual(actions, []);
+    assert.equal(model.calls.length, 2);
+    assert.match(String(model.calls[0][0].content), /Conversation analysis mode/);
+    assert.match(String(model.calls[1][0].content), /Oversized-catalog candidate contract/);
+    assert.ok(model.calls.every(call => estimateMessagesTokens(call) <= 512));
+});
+
+test("overflow candidate scan has a hard six-batch model-call cap", async () => {
+    const model = new FakeModelService();
+    model.analysis = { shouldSync: true, intents: ['修改事项 40 的提醒时间'] };
+    const extractor = new AgendaExtractor(model as unknown as IModelService, 'writer', 'selector');
+
+    await extractor.extract(conversation(), Array.from({ length: 40 }, (_, index) => record(index + 1)));
+
+    const candidateCalls = model.calls.filter(call => String(call[0]?.content ?? '').includes('# Agenda-card matching mode'));
+    assert.equal(candidateCalls.length, 6);
+    assert.equal(model.calls.length, 8); // analysis + six batches + final writer
+});
+
+test("one failed candidate batch falls back locally and still reaches the writer", async () => {
+    const model = new FakeModelService();
+    model.analysis = { shouldSync: true, intents: ['修改事项 1'] };
+    model.failCandidateCalls = true;
+    const extractor = new AgendaExtractor(model as unknown as IModelService, 'writer', 'selector');
+
+    const actions = await extractor.extract(conversation(), [record(1)]);
+
+    assert.deepEqual(actions, []);
+    assert.equal(model.calls.length, 3);
+});
+
+test("candidate relevance scores are merged globally instead of keeping batch order", async () => {
+    const model = new FakeModelService();
+    model.config.contextWindow = 4_096;
+    model.analysis = { shouldSync: true, intents: ['修改事项'] };
+    model.candidateFactory = messages => {
+        const human = String(messages[1]?.content ?? '');
+        const ids = [...human.matchAll(/<agenda id="(\d+)"/g)].map(match => Number(match[1]));
+        return { candidates: ids.map(id => ({ id, relevance: id })) };
+    };
+    const extractor = new AgendaExtractor(model as unknown as IModelService, 'writer', 'selector');
+
+    await extractor.extract(conversation(), Array.from({ length: 8 }, (_, index) => record(index + 1)));
+
+    const finalHuman = String(model.calls.at(-1)?.[1]?.content ?? '');
+    const finalIds = [...finalHuman.matchAll(/<agenda id="(\d+)"/g)].map(match => Number(match[1]));
+    assert.ok(finalIds.length > 1);
+    assert.deepEqual(finalIds, [...finalIds].sort((a, b) => b - a));
+});
+
+test("a final writer failure propagates so the pending job can be marked failed", async () => {
+    const model = new FakeModelService();
+    model.failFinal = true;
+    const extractor = new AgendaExtractor(model as unknown as IModelService, 'writer', 'selector');
+
+    await assert.rejects(() => extractor.extract(conversation(), [record(1)]), /final failed/);
+});