@downcity/agent 1.1.35 → 1.1.51

package/src/plugin/builtins/task/PROMPT.ts.txt

@@ -1,237 +0,0 @@
-# Task Plugin
-
-你可以通过 `task` plugin 管理任务定义、执行、调度与状态控制。
-
-## 任务模型
-
-每个任务定义在 `./.downcity/task/<title>/task.md`，包含：
-- frontmatter（结构化字段）
-- body（任务正文）
-
-frontmatter 核心字段：
-- `title`：任务唯一标识（唯一）
-- `description`：任务描述
-- `when`：触发条件，支持：`@manual` / cron / `time:<ISO8601-with-timezone>`
-- `sessionId`：任务执行会话
-- `status`：`enabled|paused|disabled`
-- `kind`：`agent|script`（默认 `agent`）
-
-执行时会产生 run 目录：
-- `./.downcity/task/<title>/<timestamp>/`
-
-常见产物：
-- `input.md`
-- `output.md`（本次任务的最终输出正文）
-- `result.md`（执行摘要）
-- `run.json`
-- `run-progress.json`
-- `dialogue.md` / `dialogue.json`（agent 多轮）
-- `error.md`（失败时）
-
-## 执行类型（kind）
-
-1. `kind=agent`
-- 将正文交给 agent 执行
-- 默认单轮完成；仅当 frontmatter 显式设置 `review: true` 时启用模拟用户多轮复核
-- 适合研究、分析、报告生成
-
-2. `kind=script`
-- 将正文当作 shell 脚本执行
-- 正文不能为空，必须是可执行脚本
-
-## 可用 action
-
-- `list`
-- `create`
-- `run`
-- `delete`
-- `update`
-- `status`
-- `enable`
-- `disable`
-
-## CLI 示例
-
-- `city task list [--status enabled|paused|disabled]`
-- `city task create --title '...' --description '...' --session-id <sessionId> [--when '@manual'] [--kind agent|script] [--status ...|--activate]`
-- `city task run <title> [--reason '...']`
-- `city task update <title> [--title ...] [--description ...] [--when ...] [--status ...|--activate] [--session-id ...]`
-- `city task delete <title>`
-
-## 关键约束
-
-- `title` 唯一；create 去重仅按 `title` 精确匹配。
-- `when=time:...` 触发后会自动置为 `paused`，并回退为 `when=@manual`。
-- `run` 为异步受理：立即返回 `accepted=true`、`message`、`executionId`；调用方应把它视为“任务已进入后台执行，结果会自动通过 chat plugin runtime 发送，当前流程无需阻塞等待”。
-- 如果 `run` 返回 `accepted=true`：
-  - 不要手动把 task 产出再转发给用户。
-  - 不要主动读取 run 目录、`run-progress.json`、`output.md` 做轮询。
-  - 只有当用户明确要求排查、查看产物或确认执行细节时，才进入 run 目录检查。
-- agent 任务默认只要求产生有效输出；仅当任务正文明确要求外发时，才应发送到外部 channel。
-
-## 如何设计 task 正文
-
-### agent task 推荐结构
-
-建议正文至少包含这些标题：
-
-```md
-# 任务目标
-
-- 这次任务要交付什么最终结果
-
-# 背景与输入
-
-- 数据来源、范围、约束、参考材料
-
-# 执行步骤
-
-1. 先做什么
-2. 再做什么
-3. 关键中间产物落在哪里
-
-# 输出要求
-
-- 最终结果用什么格式返回
-- 是否需要表格 / JSON / Markdown
-- 不要包含什么内容
-
-# 触发与状态建议
-
-- 这个任务为什么适合 `@manual` / cron / `time:...`
-- 当前应该是 `paused` 还是 `enabled`
-
-# 注意事项
-
-- 风险、边界、不要做什么
-```
-
-### agent task 正文编写约束
-
-- task 正文必须像一份“交付合同”，让另一个执行器拿到后可以直接执行，不依赖当前聊天语境补全含义。
-- `# 任务目标` 必须写清楚最终要交付什么，不要只写“看一下”“研究一下”“处理一下”这类模糊目标。
-- `# 背景与输入` 必须写清来源、范围、对象、时间、限制条件；不要假设执行器还能看到原始聊天上下文。
-- `# 执行步骤` 应描述任务流程，不应描述 task 管理动作；不要写“先检查有没有同名任务”“再创建任务”“然后触发任务”。
-- `# 输出要求` 必须清楚声明最终成品的格式、结构、语气、长度，以及“不要输出什么”。
-- 要明确写出：**最后一条 assistant 返回会被直接写入 `output.md` 并发送给用户**；因此最终回答必须直接等于成品内容。
-- 内容生成类任务（如日报、提醒、晨读、摘要、报告）必须明确要求“最终输出直接是成品正文”，不要让执行器输出过程说明。
-- 如果任务要把结果发给用户，正文应要求“输出可直接发送的正文内容”，而不是要求执行器解释自己已经发送了什么。
-- 除非确有需要，不要在正文中要求执行器复述 task title、sessionId、执行时间、状态等元信息。
-- 正文中的约束要可执行、可判断，尽量避免“适当”“尽量”“看情况”这类弱约束词。
-- 不要把创建 task、更新 task、查看 task 状态、确认 task 是否存在等管理动作写进正文；这些属于 task plugin 的职责，不属于 task 正文交付物。
-
-### agent task 正文禁止写法
-
-- 不要把正文写成聊天回复口吻，例如：
-  - “我来为你……”
-  - “首先让我……”
-  - “我先检查一下……”
-  - “我看到已经有一个同名任务……”
-- 不要把正文写成任务管理说明，例如：
-  - “如果任务已存在则更新，否则创建”
-  - “先 list 再 run”
-  - “完成后告诉用户任务已启动”
-- 不要把正文写成状态汇报模板，例如：
-  - “任务状态总结”
-  - “已发送 / 已完成 / 已更新”
-  - “当前任务配置如下”
-- 不要只描述动作，不描述成品，例如：
-  - “去搜集一些资料”
-  - “生成一个内容看看”
-  - “做完后反馈结果”
-- 不要把正文写成依赖当前上下文的指代，例如：
-  - “按上面说的做”
-  - “继续刚才那个”
-  - “把这个发出去”
-
-### 如何判断正文写得对不对
-
-- 如果把 task 正文单独复制出来给另一个 agent，它仍然能理解任务目标、输入、步骤和交付物，说明正文合格。
-- 如果最终输出章节删掉后，正文只剩“去做一下”式描述，说明正文不合格。
-- 如果正文更像“创建/更新任务的操作说明”，而不是“任务执行说明”，说明分层错了，必须重写。
-- 如果正文天然会诱导执行器输出过程汇报，而不是最终成品，说明 `# 输出要求` 写得不够强，必须补充禁止项。
-
-### script task 推荐结构
-
-- 正文必须是纯 shell 脚本，不要混入解释性自然语言。
-- 开头尽量写注释说明脚本目的、输入依赖、失败条件。
-- 输出保持稳定，便于直接作为最终结果发送给用户。
-- 如需生成文件，写到 run 目录或明确的项目路径。
-
-### 输出设计原则
-
-- task 完成后，系统会自动把**最终结果正文**通过 chat plugin runtime 的 `send` 发回 `sessionId` 绑定的 chat。
-- 当前实现采用最简规则：**最后一条 assistant 返回**会被直接视为最终结果正文，并写入 `output.md`。
-- 因此正文里的“输出要求”要面向最终用户阅读，不要只写给开发者看。
-- 对于面向用户的 agent task，正文应要求“最后一条 assistant 返回直接输出最终交付物本身”，不要让执行器在最后回答里输出自己如何创建、检查、更新、触发或发送任务。
-- 如果任务是内容生成类（例如日报、提醒、晨读、摘要），最后输出应直接是那段内容本身，不要附带“我来为你处理”“任务已发送”“任务状态总结”等过程汇报。
-- 默认不要在正文里再次要求执行器调用 `city chat send`。
-- 只有在“跨会话发送”“额外抄送”“多渠道通知”这类场景下，才显式要求 `city chat send`。
-
-### `when` / `status` 怎么选
-
-- task 创建默认就是 `status=enabled`；如果还在试任务、容易失败、需要人工确认，再显式切到 `paused`。
-- 已经验证稳定、需要自动运行：直接使用 cron + `status=enabled`。
-- 明确只执行一次：使用 `time:<带时区 ISO 时间>`；执行后系统会自动回退到 `@manual` + `paused`。
-- 如果用户只是“先存起来以后再跑”，不要直接启用调度。
-
-## 正文模板
-
-### agent 模板
-
-```md
-# 任务目标
-
-- 产出一份可直接发给用户的最终结果。
-
-# 背景与输入
-
-- 在这里补充上下文、文件、链接、范围和假设。
-
-# 执行步骤
-
-1. 理解任务目标与完成标准。
-2. 收集必要信息并执行任务。
-3. 把关键中间产物写入 run 目录。
-4. 输出最终结果正文。
-
-# 输出要求
-
-- 最后一条 assistant 返回直接作为最终结果，不要附带冗长日志。
-- 最后一条 assistant 返回直接输出交付物本身，不要输出任务管理过程、发送过程或状态汇报。
-- 不要使用“我来为你…… / 首先让我…… / 已发送……”这类元话术。
-- 默认不要再次调用 `city chat send`。
-
-# 触发与状态建议
-
-- 默认创建后立即启用；如果只是先保存草稿或等待人工确认，再改成 `paused`。
-
-# 注意事项
-
-- 仅在明确需要跨会话或额外通知时，才调用 `city chat send`。
-```
-
-### script 模板
-
-```bash
-# 任务目标：一句话说明脚本要做什么
-# 输入依赖：列出环境变量、文件、命令依赖
-# 失败条件：列出应该 exit 1 的情况
-
-set -euo pipefail
-
-# 1. 准备输入
-
-# 2. 执行主逻辑
-
-# 3. 输出最终结果（这段输出会被直接发送给用户）
-```
-
-## 建议
-
-- 先 `list`，再 `create`/`update`。
-- 简单内容生成任务优先保持默认单轮；只有确实需要“先生成、再复核、再修订”时再设置 `review: true`。
-- script 任务正文保持纯脚本，不要混入冗余自然语言。
-- 如果用户只是先存起来以后再跑，创建后显式设成 `paused`；否则保持默认启用。
-- task 正文要写“最终结果长什么样”，不要只写“去做一下看看”。
-- 对内容生成任务，要明确写“最后一条 assistant 返回只能是成品正文”，避免执行器把过程说明误当成最终结果。

package/src/plugin/builtins/task/Scheduler.ts

@@ -1,245 +0,0 @@
-/**
- * Task 调度注册（集成层）。
- *
- * 关键点（中文）
- * - task 语义（status/when/串行保护）放在 task plugin runtime。
- * - cron 调度执行器由宿主注入，task runtime 不依赖具体实现。
- */
-
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import {
-  isTaskWhenManual,
-  resolveTaskWhenCronExpression,
-  resolveTaskWhenOneShotMs,
-} from "./runtime/Model.js";
-import { listTasks, readTask, writeTask } from "./runtime/Store.js";
-import { runTaskNow } from "./runtime/Runner.js";
-import { TaskCronEngine } from "./types/Cron.js";
-import { resolveRuntimeTimezone } from "@/utils/Time.js";
-
-const TASK_LOG_PREFIX = "[TASK]";
-
-function formatTaskLogMessage(message: string): string {
-  return `${TASK_LOG_PREFIX} ${message}`;
-}
-
-export async function registerTaskCronJobs(params: {
-  context: AgentContext;
-  engine: TaskCronEngine;
-}): Promise<{ tasksFound: number; jobsScheduled: number }> {
-  const context = params.context;
-  const logger = context.logger;
-  const tasks = await listTasks(context.rootPath);
-  const runtimeTimezone = resolveRuntimeTimezone();
-
-  const runningByTaskId = new Set<string>();
-  let jobsScheduled = 0;
-
-  for (const item of tasks) {
-    if (String(item.status).toLowerCase() !== "enabled") continue;
-
-    const expr = resolveTaskWhenCronExpression(item.when);
-    let latestWhen = item.when;
-    try {
-      const task = await readTask({
-        taskId: item.taskId,
-        projectRoot: context.rootPath,
-      });
-      latestWhen = task.frontmatter.when;
-    } catch {}
-
-    if (expr && !isTaskWhenManual(item.when)) {
-      try {
-        params.engine.register({
-          id: `task:${item.taskId}`,
-          expression: expr,
-          timezone: runtimeTimezone,
-          execute: async () => {
-            const taskId = String(item.taskId || "").trim();
-            if (!taskId) return;
-
-            // 关键点（中文）：同一 taskId 串行；重叠触发时跳过，避免并发执行污染 run 目录。
-            if (runningByTaskId.has(taskId)) {
-              void logger.log("warn", formatTaskLogMessage("Task skipped (already running)"), {
-                taskId,
-                via: "cron",
-              });
-              return;
-            }
-
-            runningByTaskId.add(taskId);
-            try {
-              // 关键点（中文）：触发瞬间复查最新 task.md，避免 status/when 变更后仍沿用旧注册状态。
-              const latest = await readTask({
-                taskId,
-                projectRoot: context.rootPath,
-              });
-              if (String(latest.frontmatter.status).toLowerCase() !== "enabled") {
-                return;
-              }
-              const latestExpr = resolveTaskWhenCronExpression(latest.frontmatter.when);
-              if (!latestExpr || isTaskWhenManual(latest.frontmatter.when)) {
-                return;
-              }
-
-              const result = await runTaskNow({
-                context,
-                taskId,
-                projectRoot: context.rootPath,
-                trigger: { type: "cron" },
-              });
-
-              void logger.log("info", formatTaskLogMessage("Task run finished"), {
-                taskId,
-                via: "cron",
-                status: result.status,
-                executionStatus: result.executionStatus,
-                resultStatus: result.resultStatus,
-                ...(result.resultErrors.length > 0
-                  ? { resultErrors: result.resultErrors }
-                  : {}),
-                dialogueRounds: result.dialogueRounds,
-                userSimulatorSatisfied: result.userSimulatorSatisfied,
-                timestamp: result.timestamp,
-                runDir: result.runDirRel,
-              });
-            } catch (error) {
-              void logger.log("error", formatTaskLogMessage("Task run failed (scheduler)"), {
-                taskId,
-                via: "cron",
-                error: String(error),
-              });
-            } finally {
-              runningByTaskId.delete(taskId);
-            }
-          },
-        });
-
-        jobsScheduled += 1;
-      } catch {
-        void logger.log("warn", formatTaskLogMessage("Invalid task cron; skipped"), {
-          taskId: item.taskId,
-          when: item.when,
-        });
-      }
-    }
-
-    const plannedTimeMs = resolveTaskWhenOneShotMs(latestWhen);
-    if (String(latestWhen || "").trim() && String(latestWhen || "").toLowerCase().startsWith("time:") && plannedTimeMs === null) {
-      void logger.log("warn", formatTaskLogMessage("Invalid task one-shot time; skipped"), {
-        taskId: item.taskId,
-        when: latestWhen,
-      });
-      continue;
-    }
-    if (plannedTimeMs === null) continue;
-
-    try {
-      params.engine.register({
-        id: `task-time:${item.taskId}`,
-        expression: "* * * * *",
-        timezone: runtimeTimezone,
-        execute: async () => {
-          const taskId = String(item.taskId || "").trim();
-          if (!taskId) return;
-
-          // 到点前不执行；进程重启后若已过点，将在下一分钟补执行一次。
-          if (Date.now() < plannedTimeMs) return;
-
-          // 关键点（中文）：同一 taskId 串行；重叠触发时跳过，避免并发执行污染 run 目录。
-          if (runningByTaskId.has(taskId)) {
-            void logger.log("warn", formatTaskLogMessage("Task skipped (already running)"), {
-              taskId,
-              via: "time",
-            });
-            return;
-          }
-
-          let shouldDeactivateOneShot = false;
-          runningByTaskId.add(taskId);
-          try {
-            const latest = await readTask({
-              taskId,
-              projectRoot: context.rootPath,
-            });
-            if (String(latest.frontmatter.status).toLowerCase() !== "enabled") return;
-            const latestPlannedMs = resolveTaskWhenOneShotMs(latest.frontmatter.when);
-            if (latestPlannedMs === null) return;
-            if (Date.now() < latestPlannedMs) return;
-
-            shouldDeactivateOneShot = true;
-            const result = await runTaskNow({
-              context,
-              taskId,
-              projectRoot: context.rootPath,
-              trigger: { type: "time" },
-            });
-
-            void logger.log("info", formatTaskLogMessage("Task run finished"), {
-              taskId,
-              via: "time",
-              status: result.status,
-              executionStatus: result.executionStatus,
-              resultStatus: result.resultStatus,
-              ...(result.resultErrors.length > 0
-                ? { resultErrors: result.resultErrors }
-                : {}),
-              dialogueRounds: result.dialogueRounds,
-              userSimulatorSatisfied: result.userSimulatorSatisfied,
-              timestamp: result.timestamp,
-              runDir: result.runDirRel,
-            });
-          } catch (error) {
-            void logger.log("error", formatTaskLogMessage("Task run failed (scheduler)"), {
-              taskId,
-              via: "time",
-              error: String(error),
-            });
-          } finally {
-            if (shouldDeactivateOneShot) {
-              try {
-                const latest = await readTask({
-                  taskId,
-                  projectRoot: context.rootPath,
-                });
-                await writeTask({
-                  projectRoot: context.rootPath,
-                  taskId,
-                  overwrite: true,
-                  frontmatter: {
-                    ...latest.frontmatter,
-                    when: "@manual",
-                    status: "paused",
-                  },
-                  body: latest.body,
-                });
-                void logger.log("info", formatTaskLogMessage("One-shot task deactivated after execution"), {
-                  taskId,
-                  status: "paused",
-                });
-              } catch (e) {
-                void logger.log("warn", formatTaskLogMessage("Failed to deactivate one-shot task"), {
-                  taskId,
-                  error: String(e),
-                });
-              }
-            }
-            runningByTaskId.delete(taskId);
-          }
-        },
-      });
-
-      jobsScheduled += 1;
-    } catch {
-      void logger.log("warn", formatTaskLogMessage("Invalid task one-shot trigger; skipped"), {
-        taskId: item.taskId,
-        when: latestWhen,
-      });
-    }
-  }
-
-  return {
-    tasksFound: tasks.length,
-    jobsScheduled,
-  };
-}

package/src/plugin/builtins/task/TaskPlugin.ts

@@ -1,167 +0,0 @@
-/**
- * TaskPlugin：task plugin 的类实例实现。
- *
- * 关键点（中文）
- * - task 的长期运行态（cron engine）归属于 TaskPlugin 实例。
- * - task 的 prompt、action input、action execution 都已拆到独立模块。
- * - 当前文件只保留实例骨架与 lifecycle，不再依赖旧的模块级单例。
- */
-
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
-import { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type { PluginActions } from "@/plugin/types/Plugin.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type {
-  TaskCronRegisterResult,
-  TaskSchedulerReloadResult,
-} from "@/plugin/builtins/task/types/TaskPluginTypes.js";
-import { TaskCronTriggerEngine } from "@/plugin/builtins/task/runtime/CronTrigger.js";
-import { registerTaskCronJobs } from "@/plugin/builtins/task/Scheduler.js";
-import {
-  createTaskPluginActions,
-} from "@/plugin/builtins/task/runtime/TaskPluginActions.js";
-import {
-  reloadTaskSchedulerAfterMutation,
-} from "@/plugin/builtins/task/runtime/TaskActionExecution.js";
-import { TASK_PLUGIN_PROMPT } from "@/plugin/builtins/task/runtime/TaskPluginSystem.js";
-
-const TASK_LOG_PREFIX = "[TASK]";
-
-function formatTaskLogMessage(message: string): string {
-  return `${TASK_LOG_PREFIX} ${message}`;
-}
-
-/**
- * task plugin 类实现。
- */
-export class TaskPlugin extends BasePlugin {
-  /**
-   * 当前 plugin 名称。
-   */
-  readonly name = "task";
-
-  /**
-   * task plugin 的 system 文本提供器。
-   */
-  readonly system = (): string => TASK_PLUGIN_PROMPT;
-
-  /**
-   * task plugin 的 action 定义表。
-   */
-  readonly actions: PluginActions;
-
-  /**
-   * 当前实例持有的 cron engine。
-   *
-   * 关键点（中文）
-   * - 这是 per-plugin-instance 的长期运行态。
-   * - 不再复用 module-global 单例。
-   */
-  public cronEngine: TaskCronTriggerEngine | null = null;
-
-  constructor(agent: AgentRuntime | null) {
-    super(agent);
-
-    this.actions = createTaskPluginActions({
-      reloadSchedulerAfterMutation: async (params) =>
-        this.reloadSchedulerAfterMutation(params),
-    });
-
-    this.lifecycle = {
-      start: async (context) => {
-        const result = await this.startCronRuntime(context);
-        if (!result) return;
-        context.logger.info(
-          formatTaskLogMessage(
-            `Task cron trigger started (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
-          ),
-        );
-      },
-      stop: async (context) => {
-        const stopped = await this.stopCronRuntime();
-        if (!stopped) return;
-        context.logger.info(formatTaskLogMessage("Task cron trigger stopped"));
-      },
-      command: async ({ context, command }) => {
-        if (command !== "reschedule" && command !== "reload") {
-          return {
-            success: false,
-            message: `Unknown task command: ${command}`,
-          };
-        }
-
-        const result = await this.restartCronRuntime(context);
-        context.logger.info(
-          formatTaskLogMessage(
-            `Task cron trigger reloaded (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
-          ),
-        );
-        return {
-          success: true,
-          message: "task scheduler reloaded",
-        };
-      },
-    };
-  }
-
-  /**
-   * 启动当前实例的 cron runtime。
-   */
-  async startCronRuntime(
-    context: AgentContext,
-  ): Promise<TaskCronRegisterResult | null> {
-    if (this.cronEngine) return null;
-
-    const engine = new TaskCronTriggerEngine();
-    const registerResult = await registerTaskCronJobs({
-      context,
-      engine,
-    });
-    await engine.start();
-    this.cronEngine = engine;
-    return registerResult;
-  }
-
-  /**
-   * 停止当前实例的 cron runtime。
-   */
-  async stopCronRuntime(): Promise<boolean> {
-    if (!this.cronEngine) return false;
-    const previous = this.cronEngine;
-    this.cronEngine = null;
-    await previous.stop();
-    return true;
-  }
-
-  /**
-   * 重启当前实例的 cron runtime。
-   */
-  async restartCronRuntime(
-    context: AgentContext,
-  ): Promise<TaskCronRegisterResult> {
-    await this.stopCronRuntime();
-    const started = await this.startCronRuntime(context);
-    return (
-      started || {
-        tasksFound: 0,
-        jobsScheduled: 0,
-      }
-    );
-  }
-
-  /**
-   * 任务定义变更后重载 scheduler。
-   */
-  private async reloadSchedulerAfterMutation(params: {
-    context: AgentContext;
-    action: "create" | "update" | "delete" | "status";
-    title: string;
-  }): Promise<TaskSchedulerReloadResult> {
-    return await reloadTaskSchedulerAfterMutation({
-      context: params.context,
-      action: params.action,
-      title: params.title,
-      reloadScheduler: async (context) => this.restartCronRuntime(context),
-    });
-  }
-}