@downcity/plugins 1.0.253 → 1.0.280

package/src/task/PROMPT.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/task/PROMPT.ts.txt
-const TEXT_MODULE_CONTENT = "# Task Plugin\n\nYou can use the `task` plugin to manage task definitions, execution, scheduling, and status control.\n\n## Task Model\n\nEach task is defined in `./.downcity/task/<title>/task.md` and contains:\n- frontmatter for structured fields\n- body for the task instructions\n\nCore frontmatter fields:\n- `title`: unique task identifier\n- `description`: task description\n- `when`: trigger condition, supporting `@manual`, cron, or `time:<ISO8601-with-timezone>`\n- `session_id`: task execution session\n- `status`: `enabled|paused|disabled`\n- `kind`: `agent|script`, defaulting to `agent`\n\nEach execution creates a run directory:\n- `./.downcity/task/<title>/<timestamp>/`\n\nCommon artifacts:\n- `input.md`\n- `output.md`: final output body for this run\n- `result.md`: execution summary\n- `run.json`\n- `run-progress.json`\n- `dialogue.md` / `dialogue.json`: multi-turn agent dialogue\n- `error.md`: failure details\n\n## Execution Kinds\n\n1. `kind=agent`\n- Sends the task body to an agent for execution.\n- Completes in a single turn by default. Simulated multi-turn review is enabled only when frontmatter explicitly sets `review: true`.\n- Suitable for research, analysis, and report generation.\n\n2. `kind=script`\n- Treats the body as a shell script.\n- The body must be non-empty and executable as a script.\n\n## Available Actions\n\n- `list`\n- `create`\n- `run`\n- `delete`\n- `update`\n- `status`\n- `enable`\n- `disable`\n\n## Action Examples\n\n- `plugin_call({ plugin: \"task\", action: \"list\", payload: { status } })`\n- `plugin_call({ plugin: \"task\", action: \"create\", payload: { title, description, session_id, when, kind, status } })`\n- `plugin_call({ plugin: \"task\", action: \"run\", payload: { title, reason } })`\n- `plugin_call({ plugin: \"task\", action: \"update\", payload: { title, description, when, status, session_id } })`\n- `plugin_call({ plugin: \"task\", action: \"delete\", payload: { title } })`\n\n## Key Constraints\n\n- `title` is unique. `create` deduplicates only by exact `title`.\n- After `when=time:...` triggers, the task is automatically set to `paused` and falls back to `when=@manual`.\n- `run` is accepted asynchronously. It returns `accepted=true`, `message`, and `executionId` immediately. Treat this as \"the task has entered background execution; the result will be sent automatically through the chat plugin runtime, and the current flow does not need to block.\"\n- If `run` returns `accepted=true`:\n  - Do not manually forward task output to the user again.\n  - Do not actively poll the run directory, `run-progress.json`, or `output.md`.\n  - Inspect the run directory only when the user explicitly asks to debug, view artifacts, or confirm execution details.\n- Agent tasks only need to produce valid output by default. They should send to an external channel only when the task body explicitly requires it.\n\n## Designing The Task Body\n\n### Recommended Agent Task Structure\n\nThe body should include at least these headings:\n\n```md\n# Task Goal\n\n- What final result this task must deliver.\n\n# Background And Input\n\n- Data sources, scope, constraints, and reference materials.\n\n# Execution Steps\n\n1. What to do first.\n2. What to do next.\n3. Where key intermediate artifacts should be written.\n\n# Output Requirements\n\n- What format the final result must use.\n- Whether a table, JSON, or Markdown is required.\n- What content must not be included.\n\n# Trigger And Status Recommendation\n\n- Why this task is suitable for `@manual`, cron, or `time:...`.\n- Whether it should currently be `paused` or `enabled`.\n\n# Notes\n\n- Risks, boundaries, and things not to do.\n```\n\n### Agent Task Body Writing Constraints\n\n- The task body must read like a delivery contract, so another executor can run it directly without relying on the current chat context.\n- `# Task Goal` must clearly state the final deliverable. Do not write vague goals such as \"take a look\", \"research this\", or \"handle this\".\n- `# Background And Input` must specify sources, scope, objects, time range, and constraints. Do not assume the executor can see the original chat context.\n- `# Execution Steps` should describe the task workflow, not task-management actions. Do not write \"first check whether a task with the same name exists\", \"then create a task\", or \"then trigger the task\".\n- `# Output Requirements` must clearly specify the final artifact's format, structure, tone, length, and excluded content.\n- Explicitly state that the final assistant message will be written directly to `output.md` and sent to the user. Therefore, the final answer must be exactly the deliverable content.\n- Content-generation tasks such as daily reports, reminders, morning briefings, summaries, and reports must explicitly require \"the final output is the deliverable body itself\". Do not let the executor output process notes.\n- If the task result should be sent to the user, the body should require \"output send-ready message content\" instead of asking the executor to explain what it has sent.\n- Unless truly needed, do not ask the executor to repeat the task title, session_id, execution time, status, or other metadata in the body.\n- Constraints in the body must be executable and checkable. Avoid weak phrases such as \"appropriately\", \"as much as possible\", or \"depending on the situation\".\n- Do not put task creation, task update, task status lookup, or same-title existence checks into the body. Those belong to the task plugin, not to the task deliverable.\n\n### Forbidden Agent Task Body Patterns\n\n- Do not write the body in chat-reply style, for example:\n  - \"I will help you...\"\n  - \"First, let me...\"\n  - \"I will check first...\"\n  - \"I see there is already a task with the same name...\"\n- Do not write the body as task-management instructions, for example:\n  - \"If the task exists, update it; otherwise create it.\"\n  - \"First list, then run.\"\n  - \"Tell the user that the task has started when done.\"\n- Do not write the body as a status-report template, for example:\n  - \"Task status summary\"\n  - \"Sent / completed / updated\"\n  - \"Current task configuration\"\n- Do not describe only actions without describing the deliverable, for example:\n  - \"Go collect some materials.\"\n  - \"Generate some content and see.\"\n  - \"Report back after finishing.\"\n- Do not use references that depend on the current context, for example:\n  - \"Do what was said above.\"\n  - \"Continue the previous one.\"\n  - \"Send this out.\"\n\n### How To Judge Whether The Body Is Good\n\n- If you can copy the task body alone to another agent and it can still understand the goal, input, steps, and deliverable, the body is valid.\n- If deleting the output section leaves only \"go do something\" style instructions, the body is invalid.\n- If the body looks more like instructions for creating or updating a task than instructions for executing the task, the layering is wrong and the body must be rewritten.\n- If the body naturally encourages the executor to output process notes instead of the final artifact, the `# Output Requirements` section is not strong enough and must add explicit prohibitions.\n\n### Recommended Script Task Structure\n\n- The body must be a pure shell script. Do not mix in explanatory natural language.\n- Start with comments that describe the script's purpose, input dependencies, and failure conditions when possible.\n- Keep output stable so it can be sent directly as the final result.\n- If files need to be generated, write them to the run directory or to an explicit project path.\n\n### Output Design Principles\n\n- When a task completes, the system automatically sends the final result body back to the chat bound to `session_id` through the chat plugin runtime's `send`.\n- The current implementation uses the simplest rule: the final assistant message is treated directly as the final result body and written to `output.md`.\n- Therefore, the \"Output Requirements\" section must be written for the final user, not only for developers.\n- For user-facing agent tasks, the body should require \"the final assistant message directly outputs the deliverable itself\". Do not let the executor explain how it created, checked, updated, triggered, or sent the task.\n- For content-generation tasks such as daily reports, reminders, morning briefings, and summaries, the final output should be exactly that content. It should not include process language such as \"I will handle this\", \"task sent\", or \"task status summary\".\n- By default, do not ask the executor to call chat plugin send actions again. The system handles final-result delivery.\n- Explicitly require chat plugin actions only for cross-conversation sending, additional CCs, multi-channel notifications, or similar cases.\n\n### Choosing `when` And `status`\n\n- A task is created as `status=enabled` by default. Set `paused` explicitly only when it is still a draft, likely to fail, or needs human confirmation.\n- For verified stable tasks that need automatic execution, use cron with `status=enabled`.\n- For a clear one-time execution, use `time:<ISO time with timezone>`. After execution, the system automatically falls back to `@manual` and `paused`.\n- If the user only wants to save it for later, do not enable scheduling directly.\n\n## Body Templates\n\n### Agent Template\n\n```md\n# Task Goal\n\n- Produce a final result that can be sent directly to the user.\n\n# Background And Input\n\n- Add context, files, links, scope, and assumptions here.\n\n# Execution Steps\n\n1. Understand the task goal and completion criteria.\n2. Collect necessary information and execute the task.\n3. Write key intermediate artifacts to the run directory.\n4. Output the final result body.\n\n# Output Requirements\n\n- The final assistant message is the final result. Do not include long logs.\n- The final assistant message must output the deliverable itself. Do not output task-management process, sending process, or status reports.\n- Do not use meta language such as \"I will help you...\", \"First, let me...\", or \"sent\".\n- By default, do not call the chat plugin send action again.\n\n# Trigger And Status Recommendation\n\n- Enable by default after creation. If this is only a draft or waiting for human confirmation, set it to `paused`.\n\n# Notes\n\n- Call chat plugin send actions only when cross-conversation or additional notifications are explicitly needed.\n```\n\n### Script Template\n\n```bash\n# Task goal: state in one sentence what the script should do\n# Input dependencies: list environment variables, files, and command dependencies\n# Failure conditions: list cases that should exit 1\n\nset -euo pipefail\n\n# 1. Prepare input\n\n# 2. Execute main logic\n\n# 3. Output final result. This output will be sent directly to the user.\n```\n\n## Recommendations\n\n- Run `list` before `create` or `update`.\n- Keep simple content-generation tasks single-turn by default. Set `review: true` only when you truly need \"draft, review, revise\".\n- Keep script task bodies as pure scripts, without redundant natural-language explanation.\n- If the user only wants to save something for later, create it as `paused`; otherwise keep the default enabled state.\n- The task body must describe what the final result should look like, not only say \"go do this and see\".\n- For content-generation tasks, explicitly require \"the final assistant message can only be the finished content body\" so the executor does not mistake process notes for the final result.\n";
+const TEXT_MODULE_CONTENT = "# Task Plugin\n\nYou can use the `task` plugin to manage task definitions, execution, scheduling, and status control.\n\n## Task Model\n\nEach task is defined in the current Agent private runtime directory private `task/<title>/task.md` and contains:\n- frontmatter for structured fields\n- body for the task instructions\n\nCore frontmatter fields:\n- `title`: unique task identifier\n- `description`: task description\n- `when`: trigger condition, supporting `@manual`, cron, or `time:<ISO8601-with-timezone>`\n- `session_id`: task execution session\n- `status`: `enabled|paused|disabled`\n- `kind`: `agent|script`, defaulting to `agent`\n\nEach execution creates a private run record managed by Downcity under the current Agent private runtime directory.\n\nCommon artifacts:\n- `input.md`\n- `output.md`: final output body for this run\n- `result.md`: execution summary\n- `run.json`\n- `run-progress.json`\n- `dialogue.md` / `dialogue.json`: multi-turn agent dialogue\n- `error.md`: failure details\n\n## Execution Kinds\n\n1. `kind=agent`\n- Sends the task body to an agent for execution.\n- Completes in a single turn by default. Simulated multi-turn review is enabled only when frontmatter explicitly sets `review: true`.\n- Suitable for research, analysis, and report generation.\n\n2. `kind=script`\n- Treats the body as a shell script.\n- The body must be non-empty and executable as a script.\n\n## Available Actions\n\n- `list`\n- `create`\n- `run`\n- `delete`\n- `update`\n- `status`\n- `enable`\n- `disable`\n\n## Action Examples\n\n- `plugin_call({ plugin: \"task\", action: \"list\", payload: { status } })`\n- `plugin_call({ plugin: \"task\", action: \"create\", payload: { title, description, session_id, when, kind, status } })`\n- `plugin_call({ plugin: \"task\", action: \"run\", payload: { title, reason } })`\n- `plugin_call({ plugin: \"task\", action: \"update\", payload: { title, description, when, status, session_id } })`\n- `plugin_call({ plugin: \"task\", action: \"delete\", payload: { title } })`\n\n## Key Constraints\n\n- `title` is unique. `create` deduplicates only by exact `title`.\n- After `when=time:...` triggers, the task is automatically set to `paused` and falls back to `when=@manual`.\n- `run` is accepted asynchronously. It returns `accepted=true`, `message`, and `executionId` immediately. Treat this as \"the task has entered background execution; the result will be sent automatically through the chat plugin runtime, and the current flow does not need to block.\"\n- If `run` returns `accepted=true`:\n  - Do not manually forward task output to the user again.\n  - Do not actively poll the run directory, `run-progress.json`, or `output.md`.\n  - Inspect run details through the task/control API only when the user explicitly asks to debug, view artifacts, or confirm execution details.\n- Agent tasks only need to produce valid output by default. They should send to an external channel only when the task body explicitly requires it.\n\n## Designing The Task Body\n\n### Recommended Agent Task Structure\n\nThe body should include at least these headings:\n\n```md\n# Task Goal\n\n- What final result this task must deliver.\n\n# Background And Input\n\n- Data sources, scope, constraints, and reference materials.\n\n# Execution Steps\n\n1. What to do first.\n2. What to do next.\n3. Where key intermediate artifacts should be written.\n\n# Output Requirements\n\n- What format the final result must use.\n- Whether a table, JSON, or Markdown is required.\n- What content must not be included.\n\n# Trigger And Status Recommendation\n\n- Why this task is suitable for `@manual`, cron, or `time:...`.\n- Whether it should currently be `paused` or `enabled`.\n\n# Notes\n\n- Risks, boundaries, and things not to do.\n```\n\n### Agent Task Body Writing Constraints\n\n- The task body must read like a delivery contract, so another executor can run it directly without relying on the current chat context.\n- `# Task Goal` must clearly state the final deliverable. Do not write vague goals such as \"take a look\", \"research this\", or \"handle this\".\n- `# Background And Input` must specify sources, scope, objects, time range, and constraints. Do not assume the executor can see the original chat context.\n- `# Execution Steps` should describe the task workflow, not task-management actions. Do not write \"first check whether a task with the same name exists\", \"then create a task\", or \"then trigger the task\".\n- `# Output Requirements` must clearly specify the final artifact's format, structure, tone, length, and excluded content.\n- Explicitly state that the final assistant message will be written directly to `output.md` and sent to the user. Therefore, the final answer must be exactly the deliverable content.\n- Content-generation tasks such as daily reports, reminders, morning briefings, summaries, and reports must explicitly require \"the final output is the deliverable body itself\". Do not let the executor output process notes.\n- If the task result should be sent to the user, the body should require \"output send-ready message content\" instead of asking the executor to explain what it has sent.\n- Unless truly needed, do not ask the executor to repeat the task title, session_id, execution time, status, or other metadata in the body.\n- Constraints in the body must be executable and checkable. Avoid weak phrases such as \"appropriately\", \"as much as possible\", or \"depending on the situation\".\n- Do not put task creation, task update, task status lookup, or same-title existence checks into the body. Those belong to the task plugin, not to the task deliverable.\n\n### Forbidden Agent Task Body Patterns\n\n- Do not write the body in chat-reply style, for example:\n  - \"I will help you...\"\n  - \"First, let me...\"\n  - \"I will check first...\"\n  - \"I see there is already a task with the same name...\"\n- Do not write the body as task-management instructions, for example:\n  - \"If the task exists, update it; otherwise create it.\"\n  - \"First list, then run.\"\n  - \"Tell the user that the task has started when done.\"\n- Do not write the body as a status-report template, for example:\n  - \"Task status summary\"\n  - \"Sent / completed / updated\"\n  - \"Current task configuration\"\n- Do not describe only actions without describing the deliverable, for example:\n  - \"Go collect some materials.\"\n  - \"Generate some content and see.\"\n  - \"Report back after finishing.\"\n- Do not use references that depend on the current context, for example:\n  - \"Do what was said above.\"\n  - \"Continue the previous one.\"\n  - \"Send this out.\"\n\n### How To Judge Whether The Body Is Good\n\n- If you can copy the task body alone to another agent and it can still understand the goal, input, steps, and deliverable, the body is valid.\n- If deleting the output section leaves only \"go do something\" style instructions, the body is invalid.\n- If the body looks more like instructions for creating or updating a task than instructions for executing the task, the layering is wrong and the body must be rewritten.\n- If the body naturally encourages the executor to output process notes instead of the final artifact, the `# Output Requirements` section is not strong enough and must add explicit prohibitions.\n\n### Recommended Script Task Structure\n\n- The body must be a pure shell script. Do not mix in explanatory natural language.\n- Start with comments that describe the script's purpose, input dependencies, and failure conditions when possible.\n- Keep output stable so it can be sent directly as the final result.\n- If files need to be delivered to the user, write them to an explicit project path.\n\n### Output Design Principles\n\n- When a task completes, the system automatically sends the final result body back to the chat bound to `session_id` through the chat plugin runtime's `send`.\n- The current implementation uses the simplest rule: the final assistant message is treated directly as the final result body and written to `output.md`.\n- Therefore, the \"Output Requirements\" section must be written for the final user, not only for developers.\n- For user-facing agent tasks, the body should require \"the final assistant message directly outputs the deliverable itself\". Do not let the executor explain how it created, checked, updated, triggered, or sent the task.\n- For content-generation tasks such as daily reports, reminders, morning briefings, and summaries, the final output should be exactly that content. It should not include process language such as \"I will handle this\", \"task sent\", or \"task status summary\".\n- By default, do not ask the executor to call chat plugin send actions again. The system handles final-result delivery.\n- Explicitly require chat plugin actions only for cross-conversation sending, additional CCs, multi-channel notifications, or similar cases.\n\n### Choosing `when` And `status`\n\n- A task is created as `status=enabled` by default. Set `paused` explicitly only when it is still a draft, likely to fail, or needs human confirmation.\n- For verified stable tasks that need automatic execution, use cron with `status=enabled`.\n- For a clear one-time execution, use `time:<ISO time with timezone>`. After execution, the system automatically falls back to `@manual` and `paused`.\n- If the user only wants to save it for later, do not enable scheduling directly.\n\n## Body Templates\n\n### Agent Template\n\n```md\n# Task Goal\n\n- Produce a final result that can be sent directly to the user.\n\n# Background And Input\n\n- Add context, files, links, scope, and assumptions here.\n\n# Execution Steps\n\n1. Understand the task goal and completion criteria.\n2. Collect necessary information and execute the task.\n3. Write user-visible artifacts to an explicit project path when needed.\n4. Output the final result body.\n\n# Output Requirements\n\n- The final assistant message is the final result. Do not include long logs.\n- The final assistant message must output the deliverable itself. Do not output task-management process, sending process, or status reports.\n- Do not use meta language such as \"I will help you...\", \"First, let me...\", or \"sent\".\n- By default, do not call the chat plugin send action again.\n\n# Trigger And Status Recommendation\n\n- Enable by default after creation. If this is only a draft or waiting for human confirmation, set it to `paused`.\n\n# Notes\n\n- Call chat plugin send actions only when cross-conversation or additional notifications are explicitly needed.\n```\n\n### Script Template\n\n```bash\n# Task goal: state in one sentence what the script should do\n# Input dependencies: list environment variables, files, and command dependencies\n# Failure conditions: list cases that should exit 1\n\nset -euo pipefail\n\n# 1. Prepare input\n\n# 2. Execute main logic\n\n# 3. Output final result. This output will be sent directly to the user.\n```\n\n## Recommendations\n\n- Run `list` before `create` or `update`.\n- Keep simple content-generation tasks single-turn by default. Set `review: true` only when you truly need \"draft, review, revise\".\n- Keep script task bodies as pure scripts, without redundant natural-language explanation.\n- If the user only wants to save something for later, create it as `paused`; otherwise keep the default enabled state.\n- The task body must describe what the final result should look like, not only say \"go do this and see\".\n- For content-generation tasks, explicitly require \"the final assistant message can only be the finished content body\" so the executor does not mistake process notes for the final result.\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/task/PROMPT.ts.txt

@@ -4,7 +4,7 @@ You can use the `task` plugin to manage task definitions, execution, scheduling,
 
 ## Task Model
 
-Each task is defined in `./.downcity/task/<title>/task.md` and contains:
+Each task is defined in the current Agent private runtime directory private `task/<title>/task.md` and contains:
 - frontmatter for structured fields
 - body for the task instructions
 
@@ -16,8 +16,7 @@ Core frontmatter fields:
 - `status`: `enabled|paused|disabled`
 - `kind`: `agent|script`, defaulting to `agent`
 
-Each execution creates a run directory:
-- `./.downcity/task/<title>/<timestamp>/`
+Each execution creates a private run record managed by Downcity under the current Agent private runtime directory.
 
 Common artifacts:
 - `input.md`
@@ -66,7 +65,7 @@ Common artifacts:
 - If `run` returns `accepted=true`:
   - Do not manually forward task output to the user again.
   - Do not actively poll the run directory, `run-progress.json`, or `output.md`.
-  - Inspect the run directory only when the user explicitly asks to debug, view artifacts, or confirm execution details.
+  - Inspect run details through the task/control API only when the user explicitly asks to debug, view artifacts, or confirm execution details.
 - Agent tasks only need to produce valid output by default. They should send to an external channel only when the task body explicitly requires it.
 
 ## Designing The Task Body
@@ -156,7 +155,7 @@ The body should include at least these headings:
 - The body must be a pure shell script. Do not mix in explanatory natural language.
 - Start with comments that describe the script's purpose, input dependencies, and failure conditions when possible.
 - Keep output stable so it can be sent directly as the final result.
-- If files need to be generated, write them to the run directory or to an explicit project path.
+- If files need to be delivered to the user, write them to an explicit project path.
 
 ### Output Design Principles
 
@@ -192,7 +191,7 @@ The body should include at least these headings:
 
 1. Understand the task goal and completion criteria.
 2. Collect necessary information and execute the task.
-3. Write key intermediate artifacts to the run directory.
+3. Write user-visible artifacts to an explicit project path when needed.
 4. Output the final result body.
 
 # Output Requirements

package/src/task/Scheduler.ts

@@ -36,7 +36,7 @@ export async function registerTaskCronJobs(params: {
 }): Promise<{ tasksFound: number; jobsScheduled: number }> {
   const context = params.context;
   const logger = context.logger;
-  const tasks = await listTasks(context.workspace_path);
+  const tasks = await listTasks(context.data_path);
   const runtimeTimezone = params.timezone;
 
   let jobsScheduled = 0;
@@ -49,7 +49,7 @@ export async function registerTaskCronJobs(params: {
     try {
       const task = await readTask({
         taskId: item.taskId,
-        project_root: context.workspace_path,
+        data_path: context.data_path,
       });
       latestWhen = task.frontmatter.when;
     } catch {}
@@ -78,7 +78,7 @@ export async function registerTaskCronJobs(params: {
               // 关键点（中文）：触发瞬间复查最新 task.md，避免 status/when 变更后仍沿用旧注册状态。
               const latest = await readTask({
                 taskId,
-                project_root: context.workspace_path,
+                data_path: context.data_path,
               });
               if (String(latest.frontmatter.status).toLowerCase() !== "enabled") {
                 return;
@@ -91,7 +91,7 @@ export async function registerTaskCronJobs(params: {
               const result = await runTaskNow({
                 context,
                 taskId,
-                project_root: context.workspace_path,
+                data_path: context.data_path,
                 trigger: { type: "cron" },
               });
 
@@ -166,7 +166,7 @@ export async function registerTaskCronJobs(params: {
           try {
             const latest = await readTask({
               taskId,
-              project_root: context.workspace_path,
+              data_path: context.data_path,
             });
             if (String(latest.frontmatter.status).toLowerCase() !== "enabled") return;
             const latestPlannedMs = resolveTaskWhenOneShotMs(latest.frontmatter.when);
@@ -177,7 +177,7 @@ export async function registerTaskCronJobs(params: {
             const result = await runTaskNow({
               context,
               taskId,
-              project_root: context.workspace_path,
+              data_path: context.data_path,
               trigger: { type: "time" },
             });
 
@@ -206,10 +206,10 @@ export async function registerTaskCronJobs(params: {
               try {
                 const latest = await readTask({
                   taskId,
-                  project_root: context.workspace_path,
+                  data_path: context.data_path,
                 });
                 await writeTask({
-                  project_root: context.workspace_path,
+                  data_path: context.data_path,
                   taskId,
                   overwrite: true,
                   frontmatter: {

package/src/task/TaskPlugin.ts

@@ -8,6 +8,7 @@
  */
 
 import { BasePlugin, create_action } from "@downcity/agent";
+import type { AgentPluginContext } from "@downcity/agent";
 import type { PluginActions } from "@downcity/agent";
 import type { PluginContext } from "@downcity/agent";
 import type {
@@ -25,6 +26,7 @@ import {
 } from "@/task/runtime/TaskActionExecution.js";
 import { TASK_PLUGIN_PROMPT } from "@/task/runtime/TaskPluginSystem.js";
 import { resolve_runtime_timezone } from "@downcity/agent";
+import type { TaskWorkspaceRuntime } from "@/task/types/TaskWorkspaceRuntime.js";
 
 const TASK_LOG_PREFIX = "[TASK]";
 
@@ -44,7 +46,10 @@ export class TaskPlugin extends BasePlugin {
   /**
    * task plugin 的 system 文本提供器。
    */
-  readonly system = (): string => TASK_PLUGIN_PROMPT;
+  readonly system = async (context: PluginContext): Promise<string> => {
+    await this.start_cron_runtime(context);
+    return TASK_PLUGIN_PROMPT;
+  };
 
   /**
    * task plugin 的 action 定义表。
@@ -63,16 +68,10 @@ export class TaskPlugin extends BasePlugin {
    * - 这是 per-plugin-instance 的长期运行态。
    * - 不再复用 module-global 单例。
    */
-  public cronEngine: TaskCronTriggerEngine | null = null;
+  private readonly runtimes_by_workspace = new Map<string, TaskWorkspaceRuntime>();
 
-  /**
-   * 当前实例持有的运行中 task 锁。
-   *
-   * 关键点（中文）
-   * - scheduler reload 会替换 cron engine。
-   * - 锁必须挂在 plugin 实例上，避免 reload 后同一 task 被新旧调度器并发触发。
-   */
-  private readonly runningTaskIds = new Set<string>();
+  /** 各 Workspace 当前唯一的 cron 启动流程。 */
+  private readonly starts_by_workspace = new Map<string, Promise<TaskCronRegisterResult | null>>();
 
   constructor(options?: TaskPluginOptions) {
     super();
@@ -86,7 +85,7 @@ export class TaskPlugin extends BasePlugin {
       reload: create_action({
         description: "Reload the task scheduler from persisted tasks.",
         execute: async ({ context }) => {
-          const result = await this.restartCronRuntime(context);
+          const result = await this.restart_cron_runtime(context);
           context.logger.info(
             formatTaskLogMessage(
               `Task cron trigger reloaded (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
@@ -105,19 +104,13 @@ export class TaskPlugin extends BasePlugin {
     };
 
     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"));
+      start: async (_context: AgentPluginContext) => {},
+      stop: async (_context: AgentPluginContext) => {
+        await Promise.allSettled([...this.starts_by_workspace.values()]);
+        await Promise.all([...this.runtimes_by_workspace.keys()].map(async (workspace_id) => {
+          await this.stop_cron_runtime(workspace_id);
+        }));
+        this.starts_by_workspace.clear();
       },
     };
   }
@@ -125,42 +118,58 @@ export class TaskPlugin extends BasePlugin {
   /**
    * 启动当前实例的 cron runtime。
    */
-  async startCronRuntime(
+  async start_cron_runtime(
     context: PluginContext,
   ): Promise<TaskCronRegisterResult | null> {
-    if (this.cronEngine) return null;
-
-    const engine = new TaskCronTriggerEngine();
-    const registerResult = await registerTaskCronJobs({
-      context,
-      engine,
-      timezone: this.resolveTimezone(),
-      runningTaskIds: this.runningTaskIds,
-    });
-    await engine.start();
-    this.cronEngine = engine;
-    return registerResult;
+    if (this.runtimes_by_workspace.has(context.workspace_id)) return null;
+    const started = this.starts_by_workspace.get(context.workspace_id);
+    if (started) return await started;
+
+    const start_promise = (async () => {
+      const engine = new TaskCronTriggerEngine();
+      const running_task_ids = new Set<string>();
+      const register_result = await registerTaskCronJobs({
+        context,
+        engine,
+        timezone: this.resolveTimezone(),
+        runningTaskIds: running_task_ids,
+      });
+      await engine.start();
+      this.runtimes_by_workspace.set(context.workspace_id, {
+        cron_engine: engine,
+        running_task_ids,
+      });
+      return register_result;
+    })();
+    this.starts_by_workspace.set(context.workspace_id, start_promise);
+    try {
+      return await start_promise;
+    } finally {
+      if (this.starts_by_workspace.get(context.workspace_id) === start_promise) {
+        this.starts_by_workspace.delete(context.workspace_id);
+      }
+    }
   }
 
   /**
    * 停止当前实例的 cron runtime。
    */
-  async stopCronRuntime(): Promise<boolean> {
-    if (!this.cronEngine) return false;
-    const previous = this.cronEngine;
-    this.cronEngine = null;
-    await previous.stop();
+  async stop_cron_runtime(workspace_id: string): Promise<boolean> {
+    const runtime = this.runtimes_by_workspace.get(workspace_id);
+    if (!runtime) return false;
+    this.runtimes_by_workspace.delete(workspace_id);
+    await runtime.cron_engine.stop();
     return true;
   }
 
   /**
    * 重启当前实例的 cron runtime。
    */
-  async restartCronRuntime(
+  async restart_cron_runtime(
     context: PluginContext,
   ): Promise<TaskCronRegisterResult> {
-    await this.stopCronRuntime();
-    const started = await this.startCronRuntime(context);
+    await this.stop_cron_runtime(context.workspace_id);
+    const started = await this.start_cron_runtime(context);
     return (
       started || {
         tasksFound: 0,
@@ -181,7 +190,7 @@ export class TaskPlugin extends BasePlugin {
       context: params.context,
       action: params.action,
       title: params.title,
-      reloadScheduler: async (context) => this.restartCronRuntime(context),
+      reloadScheduler: async (context) => this.restart_cron_runtime(context),
     });
   }
 

package/src/task/runtime/Model.ts

@@ -142,16 +142,6 @@ export function normalizeTaskWhen(
   return { ok: true, value: canonical };
 }
 
-/**
- * 兼容旧调用名：返回 cron 表达式或 `@manual`。
- */
-export function normalizeTaskCronExpression(raw: string): string | null {
-  const when = normalizeTaskWhen(raw);
-  if (!when.ok) return null;
-  if (isTaskWhenOneShot(when.value)) return null;
-  return normalizeCronExpression(when.value);
-}
-
 export function isTaskWhenManual(input: string): boolean {
   const when = String(input || "").trim().toLowerCase();
   return when === "@manual";
@@ -213,9 +203,9 @@ export function parseTaskMarkdown(params: {
   taskId: string;
   markdown: string;
   taskMdPath: string;
-  project_root: string;
+  data_path: string;
 }): { ok: true; task: ShipTaskDefinitionV1 } | { ok: false; error: string } {
-  const { taskId, markdown, taskMdPath, project_root } = params;
+  const { taskId, markdown, taskMdPath, data_path } = params;
   const text = String(markdown ?? "");
   const { frontMatterYaml, body } = parseFrontMatter(text);
 
@@ -293,7 +283,7 @@ export function parseTaskMarkdown(params: {
   };
 
   const relTaskMdPath = path
-    .relative(project_root, taskMdPath)
+    .relative(data_path, taskMdPath)
     .split(path.sep)
     .join("/");
 

package/src/task/runtime/Paths.ts

@@ -2,9 +2,9 @@
  * Task System paths and identifiers.
  *
  * 约定（中文）
- * - task root: `./.downcity/task/`
- * - definition: `./.downcity/task/<taskId>/task.md`
- * - run dir: `./.downcity/task/<taskId>/<timestamp>/`
+ * - task root: `<Agent data>/task/`
+ * - definition: `<Agent data>/task/<taskId>/task.md`
+ * - run dir: `<Agent data>/task/<taskId>/<timestamp>/`
  *
  * 同时定义“task run session_id”格式，用于把 Agent 的 session 映射到 run 目录：
  * - `task-run:<taskId>:<timestamp>`
@@ -59,16 +59,16 @@ export function normalizeTaskId(input: string): string {
   return id;
 }
 
-export function getTaskRootDir(project_root: string): string {
-  return path.join(String(project_root || "").trim(), ".downcity", "task");
+export function getTaskRootDir(data_path: string): string {
+  return path.join(String(data_path || "").trim(), "task");
 }
 
-export function getTaskDir(project_root: string, taskId: string): string {
-  return path.join(getTaskRootDir(project_root), normalizeTaskId(taskId));
+export function getTaskDir(data_path: string, taskId: string): string {
+  return path.join(getTaskRootDir(data_path), normalizeTaskId(taskId));
 }
 
-export function getTaskMdPath(project_root: string, taskId: string): string {
-  return path.join(getTaskDir(project_root, taskId), "task.md");
+export function getTaskMdPath(data_path: string, taskId: string): string {
+  return path.join(getTaskDir(data_path, taskId), "task.md");
 }
 
 export function formatTaskRunTimestamp(date: Date = new Date()): string {
@@ -85,13 +85,13 @@ export function formatTaskRunTimestamp(date: Date = new Date()): string {
 }
 
 export function getTaskRunDir(
-  project_root: string,
+  data_path: string,
   taskId: string,
   timestamp: string,
 ): string {
   const ts = String(timestamp || "").trim();
   if (!ts) throw new Error("timestamp is required");
-  return path.join(getTaskDir(project_root, taskId), ts);
+  return path.join(getTaskDir(data_path, taskId), ts);
 }
 
 export function createTaskRunSessionId(taskId: string, timestamp: string): string {

package/src/task/runtime/Runner.ts

@@ -79,7 +79,7 @@ export async function runTaskNow(params: {
   taskId: string;
   trigger: ShipTaskRunTriggerV1;
   executionId?: string;
-  project_root?: string;
+  data_path?: string;
   /** 发起该任务的 Session step 已提交生效的 env 快照。 */
   workspace_env?: Readonly<Record<string, string>>;
   /** 发起该任务的 Session step 已提交生效的 instruction 快照。 */
@@ -102,19 +102,19 @@ export async function runTaskNow(params: {
   runDirRel: string;
 }> {
   const context = params.context;
-  const root = String(params.project_root || context.workspace_path || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || context.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
 
   const startedAt = Date.now();
   const timestamp = formatTaskRunTimestamp(new Date(startedAt));
   const executionId = String(params.executionId || `${params.taskId}:${timestamp}`).trim();
 
-  const task = await readTask({ taskId: params.taskId, project_root: root });
+  const task = await readTask({ taskId: params.taskId, data_path: root });
   const runDirAbs = getTaskRunDir(root, task.taskId, timestamp);
   const { runDirRel } = await ensureRunDir({
     taskId: task.taskId,
     timestamp,
-    project_root: root,
+    data_path: root,
   });
   const filePaths = createTaskRunFilePaths(runDirAbs);
 
@@ -170,7 +170,6 @@ export async function runTaskNow(params: {
   if (taskKind === "script") {
     const scriptResult = await runScriptTaskBranch({
       context,
-      runDirAbs,
       session_id: task.frontmatter.session_id,
       scriptBody: task.body,
       runProgress,

package/src/task/runtime/Store.ts

@@ -2,9 +2,9 @@
  * Task storage (disk-backed).
  *
  * 关键点（中文）
- * - Task 的“唯一来源”是 `./.downcity/task/<taskId>/task.md`
+ * - Task 的“唯一来源”是 Agent 私有目录中的 `task/<taskId>/task.md`
  * - list/read/write 都只围绕 markdown 文件与目录结构，不引入数据库
- * - 运行产物目录：`./.downcity/task/<taskId>/<timestamp>/...`
+ * - 运行产物目录：Agent 私有目录中的 `task/<taskId>/<timestamp>/...`
  */
 
 import fs from "fs-extra";
@@ -52,11 +52,11 @@ function isDirectoryNameTimestamp(name: string): boolean {
  * 列出全部任务。
  *
  * 算法（中文）
- * - 遍历 `.downcity/task/*` 目录并解析每个 `task.md`。
+ * - 遍历 Agent 的 `task/*` 目录并解析每个 `task.md`。
  * - 通过子目录时间戳推断 `lastRunTimestamp`。
  */
-export async function listTasks(project_root: string): Promise<TaskListItem[]> {
-  const root = String(project_root || "").trim();
+export async function listTasks(data_path: string): Promise<TaskListItem[]> {
+  const root = String(data_path || "").trim();
   if (!root) return [];
 
   const dir = getTaskRootDir(root);
@@ -88,7 +88,7 @@ export async function listTasks(project_root: string): Promise<TaskListItem[]> {
       taskId,
       markdown: raw,
       taskMdPath,
-      project_root: root,
+      data_path: root,
     });
     if (!parsed.ok) continue;
 
@@ -136,11 +136,11 @@ export async function listTasks(project_root: string): Promise<TaskListItem[]> {
  * - 若磁盘中存在同 title 多定义，会拒绝并提示冲突。
  */
 export async function resolveTaskIdByTitle(params: {
-  project_root: string;
+  data_path: string;
   title: string;
 }): Promise<string> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const title = String(params.title || "").trim();
   if (!title) throw new Error("title is required");
 
@@ -156,9 +156,9 @@ export async function resolveTaskIdByTitle(params: {
 /**
  * 读取单个任务定义。
  */
-export async function readTask(params: { taskId: string; project_root: string }): Promise<ShipTaskDefinitionV1> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+export async function readTask(params: { taskId: string; data_path: string }): Promise<ShipTaskDefinitionV1> {
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
 
   const taskMdPath = getTaskMdPath(root, taskId);
@@ -167,7 +167,7 @@ export async function readTask(params: { taskId: string; project_root: string })
     taskId,
     markdown: raw,
     taskMdPath,
-    project_root: root,
+    data_path: root,
   });
   if (!parsed.ok) throw new Error(parsed.error);
   return parsed.task;
@@ -178,10 +178,10 @@ export async function readTask(params: { taskId: string; project_root: string })
  */
 export async function deleteTask(params: {
   taskId: string;
-  project_root: string;
+  data_path: string;
 }): Promise<{ taskId: string; taskDirPath: string }> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
 
   const taskMdPath = getTaskMdPath(root, taskId);
@@ -208,11 +208,11 @@ export async function writeTask(params: {
   taskId: string;
   frontmatter: ShipTaskFrontmatterV1;
   body: string;
-  project_root: string;
+  data_path: string;
   overwrite?: boolean;
 }): Promise<{ taskId: string; taskMdPath: string }> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
 
   const dir = getTaskDir(root, taskId);
@@ -239,10 +239,10 @@ export async function writeTask(params: {
 export async function ensureRunDir(params: {
   taskId: string;
   timestamp: string;
-  project_root: string;
+  data_path: string;
 }): Promise<{ runDir: string; runDirRel: string }> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
   const runDir = getTaskRunDir(root, taskId, params.timestamp);
   await fs.ensureDir(runDir);

package/src/task/runtime/TaskActionExecution.ts

@@ -114,7 +114,7 @@ export async function executeTaskListAction(params: {
   return {
     success: true,
     data: await listTaskDefinitions({
-      project_root: params.context.workspace_path,
+      data_path: params.context.data_path,
       ...(params.payload.status ? { status: params.payload.status } : {}),
     }),
   };
@@ -130,7 +130,7 @@ export async function executeTaskCreateAction(params: {
 }) {
   const payload = params.payload;
   const result = await createTaskDefinition({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {
@@ -163,7 +163,7 @@ export async function executeTaskRunAction(params: {
 }) {
   const result = await runTaskDefinition({
     context: params.context,
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: params.payload,
     execution_context: params.execution_context,
   });
@@ -189,7 +189,7 @@ export async function executeTaskDeleteAction(params: {
 }) {
   const payload = params.payload;
   const result = await deleteTaskDefinition({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {
@@ -222,7 +222,7 @@ export async function executeTaskUpdateAction(params: {
 }) {
   const payload = params.payload;
   const result = await updateTaskDefinition({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {
@@ -255,7 +255,7 @@ export async function executeTaskStatusAction(params: {
 }) {
   const payload = params.payload;
   const result = await setTaskStatus({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {

package/src/task/runtime/TaskPluginActionRegistry.ts

@@ -222,7 +222,7 @@ export function createTaskPluginActions(params: {
         return executeTaskRunAction({
           context: actionParams.context,
           payload: actionParams.input as TaskRunRequest,
-          execution_context: actionParams.execution_context,
+          execution_context: actionParams.execution.snapshot,
         });
       },
     }),