@downcity/plugins 1.0.52 → 1.0.56

package/src/skill/runtime/Paths.ts

@@ -2,16 +2,16 @@
  * Skills roots resolution.
  *
  * 关键点（中文）
- * - roots 分三类：项目内（project）、用户目录（home），以及配置外部路径（config）
- * - allowExternalPaths 只控制“配置外部路径（config）”是否可扫描；home 默认始终可扫描
+ * - roots 分三类：项目内（project）、用户目录（home），以及构造参数路径（custom）
+ * - SkillPlugin constructor 是唯一配置入口，不再读取 downcity.json 的 skill 私有配置
  * - 兼容 `<any>/skills` 这种布局：如果 root basename 不是 `skills` 且其子目录 `skills/` 存在，则优先扫描 `<root>/skills`
  */
 
 import fs from "fs-extra";
 import path from "node:path";
-import type { DowncityConfig } from "@downcity/agent/internal/config/Config.js";
-import { readSkillPluginConfig } from "../Config.js";
+import { resolveSkillPluginOptions } from "../Config.js";
 import type { SkillRoot } from "@/skill/types/SkillRoot.js";
+import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 import { expandHome, uniqStrings } from "./Utils.js";
 
 function normalizeSkillRootCandidate(candidate: string): string {
@@ -38,13 +38,17 @@ function resolveSkillRootPath(projectRoot: string, raw: string): string {
 
 export function getClaudeSkillSearchRoots(
   projectRoot: string,
-  config: DowncityConfig,
+  options?: SkillPluginOptions | null,
 ): SkillRoot[] {
-  const skillPluginConfig = readSkillPluginConfig(config);
-  const configured = skillPluginConfig.paths.map((x) => String(x));
+  const skillPluginOptions = resolveSkillPluginOptions(options);
+  const configured = skillPluginOptions.paths.map((x) => String(x));
 
-  const defaultsProject: string[] = [];
-  const defaultsHome = ["~/.agents/skills"];
+  const defaultsProject = skillPluginOptions.use.includes("project")
+    ? [".agents/skills"]
+    : [];
+  const defaultsHome = skillPluginOptions.use.includes("home")
+    ? ["~/.agents/skills"]
+    : [];
 
   const rawConfigured = uniqStrings(configured);
   const rawProject = uniqStrings(defaultsProject);
@@ -65,32 +69,17 @@ export function getClaudeSkillSearchRoots(
     });
   }
 
-  // 2) configured roots：如果在项目内，按 project 处理；否则按 config（受 allowExternalPaths 影响）
+  // 2) constructor paths：用户显式传入的路径，统一视为 custom 来源
   for (const raw of rawConfigured) {
     const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
-    const rel = path.relative(projectRoot, resolved);
-    const inside =
-      rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-
-    if (inside) {
-      roots.push({
-        source: "project",
-        raw,
-        resolved,
-        display: raw,
-        priority: 12,
-        trustedWhenExternalDisabled: true,
-      });
-    } else {
-      roots.push({
-        source: "config",
-        raw,
-        resolved,
-        display: raw,
-        priority: 40,
-        trustedWhenExternalDisabled: false,
-      });
-    }
+    roots.push({
+      source: "custom",
+      raw,
+      resolved,
+      display: raw,
+      priority: 12,
+      trustedWhenExternalDisabled: true,
+    });
   }
 
   // 3) home root（用户目录）
@@ -120,9 +109,9 @@ export function getClaudeSkillSearchRoots(
 // Back-compat（内部仅用于 prompt 展示）：保留旧 API 形状，避免外部 import 立刻断裂。
 export function getClaudeSkillSearchPaths(
   projectRoot: string,
-  config: DowncityConfig,
+  options?: SkillPluginOptions | null,
 ): { raw: string[]; resolved: string[] } {
-  const roots = getClaudeSkillSearchRoots(projectRoot, config);
+  const roots = getClaudeSkillSearchRoots(projectRoot, options);
   return {
     raw: roots.map((r) => r.display),
     resolved: roots.map((r) => r.resolved),

package/src/skill/runtime/Prompt.ts

@@ -7,10 +7,9 @@
  * - 仅做字符串渲染，不做文件 IO。
  */
 
-import type { DowncityConfig } from "@downcity/agent/internal/config/Config.js";
-import { readSkillPluginConfig } from "../Config.js";
 import { getClaudeSkillSearchRoots } from "./Paths.js";
 import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
 /**
  * 渲染 skills 系统提示片段。
@@ -21,11 +20,10 @@ import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
  */
 export function renderClaudeSkillsPromptSection(
   projectRoot: string,
-  config: DowncityConfig,
+  options: SkillPluginOptions | null | undefined,
   skills: ClaudeSkill[],
 ): string {
-  const roots = getClaudeSkillSearchRoots(projectRoot, config);
-  const allowExternal = readSkillPluginConfig(config).allowExternalPaths;
+  const roots = getClaudeSkillSearchRoots(projectRoot, options);
 
   const skillsSection =
     skills.length > 0
@@ -41,11 +39,7 @@ export function renderClaudeSkillsPromptSection(
     roots.length > 0
       ? roots
           .map((root) => {
-            const externalNote =
-              root.source === "config" && !allowExternal
-                ? " (disabled: allowExternalPaths=false)"
-                : "";
-            return `- [${root.source}] ${root.display}${externalNote}`;
+            return `- [${root.source}] ${root.display}`;
           })
           .join("\n")
       : "- (none)";

package/src/skill/runtime/SystemProvider.ts

@@ -8,14 +8,14 @@
  */
 
 import { getSessionRunContext } from "@downcity/agent/internal/executor/SessionRunScope.js";
-import type { DowncityConfig } from "@downcity/agent/internal/types/config/DowncityConfig.js";
 import { discoverClaudeSkillsSync } from "./Discovery.js";
 import { renderClaudeSkillsPromptSection } from "./Prompt.js";
 import { setSessionAvailableSkills } from "./Store.js";
+import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
 type SkillSystemRuntime = {
   rootPath: string;
-  config: DowncityConfig;
+  options?: SkillPluginOptions | null;
 };
 
 function getCurrentSessionId(): string {
@@ -37,7 +37,7 @@ export async function buildSkillsSystemText(
   const sessionId = getCurrentSessionId();
   const discoveredSkills = discoverClaudeSkillsSync(
     runtime.rootPath,
-    runtime.config,
+    runtime.options,
   );
 
   if (sessionId) {
@@ -46,7 +46,7 @@ export async function buildSkillsSystemText(
 
   return renderClaudeSkillsPromptSection(
     runtime.rootPath,
-    runtime.config,
+    runtime.options,
     discoveredSkills,
   ).trim();
 }

package/src/skill/types/SkillPlugin.ts

@@ -3,9 +3,13 @@
  *
  * 关键点（中文）
  * - skill 已迁到 plugin 体系，因此把对外 action 名称与 payload 类型统一放到 `types/`。
- * - 该文件只描述插件动作协议，不承载发现、安装或 system 组装逻辑。
+ * - constructor options 是 skill plugin 的唯一行为配置入口。
+ * - 该文件只描述插件协议，不承载发现、安装或 system 组装逻辑。
  */
 
+import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillRootSource } from "@/skill/types/SkillRoot.js";
+
 /**
  * skill plugin action 名称常量。
  */
@@ -71,37 +75,60 @@ export type SkillPluginLookupPayload = {
 };
 
 /**
- * skill plugin 配置。
+ * skill 忽略规则。
  */
-export interface SkillPluginConfig {
+export type SkillPluginIgnoreRule =
+  | string
+  | RegExp
+  | ((skill: ClaudeSkill) => boolean);
+
+/**
+ * SkillPlugin 构造参数。
+ */
+export interface SkillPluginOptions {
+  /**
+   * 启用的内置 skill 来源。
+   *
+   * 说明（中文）
+   * - `project` 表示扫描当前项目的 `.agents/skills`。
+   * - `home` 表示扫描用户目录的 `~/.agents/skills`。
+   * - 默认只启用 `project`，避免 agent 隐式读取全局 skill。
+   */
+  use?: Array<Extract<SkillRootSource, "project" | "home">>;
   /**
    * 额外的 skill 扫描根目录。
    *
    * 说明（中文）
    * - 相对路径基于项目根目录解析。
-   * - 典型值：`.agents/skills`、`.my/skills`。
+   * - 绝对路径与 `~` 路径会按原样解析为自定义来源。
+   * - 典型值：`.agents/shared-skills`、`~/team/skills`。
    */
   paths?: string[];
   /**
-   * 是否允许扫描项目根目录之外的外部路径。
+   * 忽略指定 skills。
    *
    * 说明（中文）
-   * - 仅影响 `paths` 中落在项目外部的目录。
-   * - 用户目录 `~/.agents/skills` 不受此字段限制。
+   * - 字符串会同时匹配 skill `id` 与 `name`。
+   * - `RegExp` 可用于批量过滤。
+   * - 函数返回 `true` 表示忽略该 skill。
    */
-  allowExternalPaths?: boolean;
+  ignore?: SkillPluginIgnoreRule[];
 }
 
 /**
- * 归一化后的 skill plugin 配置。
+ * 归一化后的 SkillPlugin 构造参数。
  */
-export interface ResolvedSkillPluginConfig {
+export interface ResolvedSkillPluginOptions {
+  /**
+   * 最终启用的内置 skill 来源。
+   */
+  use: Array<Extract<SkillRootSource, "project" | "home">>;
   /**
    * 最终生效的额外 skill 扫描根目录。
    */
   paths: string[];
   /**
-   * 最终生效的外部路径扫描开关。
+   * 最终生效的 skill 忽略规则。
    */
-  allowExternalPaths: boolean;
+  ignore: SkillPluginIgnoreRule[];
 }

package/src/skill/types/SkillRoot.ts

@@ -9,7 +9,7 @@
 /**
  * skill 根目录来源类型。
  */
-export type SkillRootSource = "project" | "home" | "config";
+export type SkillRootSource = "project" | "home" | "custom";
 
 /**
  * skill 扫描根目录。

package/src/task/Action.ts

@@ -75,7 +75,7 @@ function buildDefaultTaskBody(): string {
     "",
     "- 最终输出直接写结果本身，不要包多余寒暄，不要粘贴冗长日志。",
     "- 需要结构时，优先使用短标题、要点列表、表格或 JSON 等稳定格式。",
-    "- 默认不要在正文里重复调用 `town chat send`；系统会自动发送最终结果。",
+    "- 默认不要在正文里重复调用 chat plugin 的发送 action；系统会自动发送最终结果。",
     "",
     "# 触发与状态建议",
     "",
@@ -87,7 +87,7 @@ function buildDefaultTaskBody(): string {
     "",
     "- 当前是独立 task 上下文，不要假设仍处在原始聊天回合里。",
     "- 尽量使用可审计的方式：关键中间产物写入 `./.downcity/task/<title>/<timestamp>/` 下的 markdown 文件。",
-    "- 如果任务明确要求跨会话、跨平台或发送额外通知，再显式调用 `town chat send`。",
+    "- 如果任务明确要求跨会话、跨平台或发送额外通知，再显式调用 chat plugin 的发送 action。",
     "",
   ].join("\n");
 }

package/src/task/PROMPT.ts

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

package/src/task/PROMPT.ts.txt

@@ -50,13 +50,13 @@ frontmatter 核心字段：
 - `enable`
 - `disable`
 
-## CLI 示例
+## Action 调用示例
 
-- `town task list [--status enabled|paused|disabled]`
-- `town task create --title '...' --description '...' --session-id <sessionId> [--when '@manual'] [--kind agent|script] [--status ...|--activate]`
-- `town task run <title> [--reason '...']`
-- `town task update <title> [--title ...] [--description ...] [--when ...] [--status ...|--activate] [--session-id ...]`
-- `town task delete <title>`
+- `plugin_call({ plugin: "task", action: "list", payload: { status } })`
+- `plugin_call({ plugin: "task", action: "create", payload: { title, description, sessionId, when, kind, status } })`
+- `plugin_call({ plugin: "task", action: "run", payload: { title, reason } })`
+- `plugin_call({ plugin: "task", action: "update", payload: { title, description, when, status, sessionId } })`
+- `plugin_call({ plugin: "task", action: "delete", payload: { title } })`
 
 ## 关键约束
 
@@ -165,8 +165,8 @@ frontmatter 核心字段：
 - 因此正文里的“输出要求”要面向最终用户阅读，不要只写给开发者看。
 - 对于面向用户的 agent task，正文应要求“最后一条 assistant 返回直接输出最终交付物本身”，不要让执行器在最后回答里输出自己如何创建、检查、更新、触发或发送任务。
 - 如果任务是内容生成类（例如日报、提醒、晨读、摘要），最后输出应直接是那段内容本身，不要附带“我来为你处理”“任务已发送”“任务状态总结”等过程汇报。
-- 默认不要在正文里再次要求执行器调用 `town chat send`。
-- 只有在“跨会话发送”“额外抄送”“多渠道通知”这类场景下，才显式要求 `town chat send`。
+- 默认不要在正文里再次要求执行器发送 chat 消息；系统会处理最终结果回传。
+- 只有在“跨会话发送”“额外抄送”“多渠道通知”这类场景下，才显式要求执行器调用 chat plugin action。
 
 ### `when` / `status` 怎么选
 
@@ -200,7 +200,7 @@ frontmatter 核心字段：
 - 最后一条 assistant 返回直接作为最终结果，不要附带冗长日志。
 - 最后一条 assistant 返回直接输出交付物本身，不要输出任务管理过程、发送过程或状态汇报。
 - 不要使用“我来为你…… / 首先让我…… / 已发送……”这类元话术。
-- 默认不要再次调用 `town chat send`。
+- 默认不要再次调用 chat plugin 的发送 action。
 
 # 触发与状态建议
 
@@ -208,7 +208,7 @@ frontmatter 核心字段：
 
 # 注意事项
 
-- 仅在明确需要跨会话或额外通知时，才调用 `town chat send`。
+- 仅在明确需要跨会话或额外通知时，才调用 chat plugin 的发送 action。
 ```
 
 ### script 模板

package/src/task/TaskPlugin.ts

@@ -7,7 +7,6 @@
  * - 当前文件只保留实例骨架与 lifecycle，不再依赖旧的模块级单例。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
@@ -59,8 +58,8 @@ export class TaskPlugin extends BasePlugin {
    */
   public cronEngine: TaskCronTriggerEngine | null = null;
 
-  constructor(agent: AgentRuntime | null) {
-    super(agent);
+  constructor() {
+    super();
 
     this.actions = createTaskPluginActions({
       reloadSchedulerAfterMutation: async (params) =>

package/src/tts/Plugin.ts

@@ -6,7 +6,6 @@
  * - Console 只通过 setup / action 与插件交互，保持极简统一。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type {
@@ -493,13 +492,13 @@ function createTtsPluginDefinition(plugin: Plugin): Plugin {
       "# TTS Plugin",
       "The agent can call the tts plugin to synthesize speech audio from plain text.",
       "Typical usage flow:",
-      "1. Check availability with `town tts status` when you need to confirm whether the plugin and model are ready.",
-      "2. Generate audio with `town tts synthesize <text>`.",
-      "3. Optionally override synthesis parameters with `--voice`, `--language`, `--format`, `--speed`, and `--output`.",
+      "1. Check availability with the `status` action when you need to confirm whether the plugin and model are ready.",
+      "2. Generate audio with the `synthesize` action.",
+      "3. Optionally override synthesis parameters in the action payload: `voice`, `language`, `format`, `speed`, and `output`.",
       "Use the `tts.synthesize` action when the user asks to generate spoken audio or a reusable audio file tag.",
       "A successful synthesis returns a local output path and a reusable `<file type=\"audio\">...</file>` tag for downstream sending.",
       "If the Python runner prints non-fatal stderr, the command still succeeds and returns that stderr summary as extra context.",
-      "Example: `town tts synthesize \"你好，欢迎来到 Downcity\" --format wav`",
+      "Example: `plugin_call({ plugin: \"tts\", action: \"synthesize\", payload: { text: \"你好，欢迎来到 Downcity\", format: \"wav\" } })`",
     ].join("\n");
   },
   };
@@ -511,8 +510,8 @@ function createTtsPluginDefinition(plugin: Plugin): Plugin {
 export class TtsPlugin extends BasePlugin {
   readonly name = "tts";
 
-  constructor(agent: AgentRuntime | null = null) {
-    super(agent);
+  constructor() {
+    super();
     Object.assign(this, createTtsPluginDefinition(this));
   }
 }

package/src/web/PROMPT.agent-browser.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/web/PROMPT.agent-browser.ts.txt
-const TEXT_MODULE_CONTENT = "# Web Plugin / agent-browser\n\n当前 provider 是 `agent-browser`。\n\n你应直接使用 `agent-browser` 项目的浏览器自动化方法，而不是在本项目里自己实现浏览器交互。\n\n工作原则：\n\n- 浏览器交互、打开页面、点击、填写、截图、滚动等操作优先交给 `agent-browser`\n- 严格遵循 `agent-browser` 的基本工作流：\n  1. `open`\n  2. `snapshot -i`\n  3. 使用元素引用交互\n  4. 页面变化后重新 snapshot\n- 如果 `agent-browser` 命令不可用，应先报告依赖缺失\n\n你在处理需要浏览器操作的任务时，应以外部 `agent-browser` 项目为准。\n";
+const TEXT_MODULE_CONTENT = "# Web Plugin / agent-browser\n\n当前 provider 是 `agent-browser`。\n\n你应直接使用 `agent-browser` 项目的浏览器自动化方法，而不是在本项目里自己实现浏览器交互。\n\n工作原则：\n\n- 浏览器交互、打开页面、点击、填写、截图、滚动等操作优先交给 `agent-browser`\n- 严格遵循 `agent-browser` 的基本工作流：\n  1. `open`\n  2. `snapshot -i`\n  3. 使用元素引用交互\n  4. 页面变化后重新 snapshot\n- 如果 `agent-browser` provider 不可用，应先报告依赖缺失\n\n你在处理需要浏览器操作的任务时，应以外部 `agent-browser` 项目为准。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/web/PROMPT.agent-browser.ts.txt

@@ -12,6 +12,6 @@
   2. `snapshot -i`
   3. 使用元素引用交互
   4. 页面变化后重新 snapshot
-- 如果 `agent-browser` 命令不可用，应先报告依赖缺失
+- 如果 `agent-browser` provider 不可用，应先报告依赖缺失
 
 你在处理需要浏览器操作的任务时，应以外部 `agent-browser` 项目为准。

package/src/web/Plugin.ts

@@ -5,7 +5,6 @@
  * - `web` plugin 不再自实现联网与浏览器能力，只负责 provider 选择、状态检查与提示词注入。
  * - 真正的联网逻辑直接交给外部实现：`web-access` 或 `agent-browser`。
  */
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
@@ -499,7 +498,7 @@ function createWebPluginDefinition(plugin: Plugin): Plugin {
     return [
       `Current web provider: ${config.provider}`,
       config.provider === "agent-browser"
-        ? `Use external CLI command: ${config.browserCommand}`
+        ? `Use the configured agent-browser provider: ${config.browserCommand}`
         : "Use the installed external web-access skill/project.",
       "",
       WEB_PLUGIN_PROMPT,
@@ -516,8 +515,8 @@ function createWebPluginDefinition(plugin: Plugin): Plugin {
 export class WebPlugin extends BasePlugin {
   readonly name = "web";
 
-  constructor(agent: AgentRuntime | null = null) {
-    super(agent);
+  constructor() {
+    super();
     Object.assign(this, createWebPluginDefinition(this));
   }
 }

package/src/workboard/Plugin.ts

@@ -6,7 +6,6 @@
  * - 当前同时通过 plugin action 与 HTTP 注入提供快照，供 Town RPC 与 Town HTTP gateway 复用。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
@@ -111,8 +110,8 @@ function createWorkboardPluginDefinition(plugin: Plugin): Plugin {
 export class WorkboardPlugin extends BasePlugin {
   readonly name = "workboard";
 
-  constructor(agent: AgentRuntime | null = null) {
-    super(agent);
+  constructor() {
+    super();
     Object.assign(this, createWorkboardPluginDefinition(this));
   }
 }