opencode-session-spawn 2.0.1 → 2.1.1

package/README.md

@@ -8,59 +8,66 @@ opencode 插件：**会话生成原语**。只做一件事——**创建一个
 
 | 入口 | 用法 | 谁触发 |
 |------|------|--------|
-| 工具 `spawn_session` | `spawn_session({ prompt, title? })` | **模型自主调用**（打通无人值守） |
-| 命令 | `@spawn <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
+| 工具 `spawn_session` | `spawn_session({ prompt, title?, agent?, directory? })` | **模型自主调用**（打通无人值守） |
+| 命令 | `@spawn [--agent <名称>] [--title <标题>] <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
 
 参数 / 行为：
 
 - `prompt`（必填）：注入新会话的起始语句。可内含读取文件、复述要点、执行下一步等引导。
 - `title`（可选）：新会话标题。缺省取 `prompt` 首行（清洗非法字符、截断 60）。
-- 内部调用：`client.session.create({ body: { title } })` → `client.session.promptAsync({ path: { id }, body: { parts: [{ type: "text", text: prompt }] } })`。
+- `agent`（可选，工具参数）：新会话以某 agent/模式启动（如 `leader`）。仅在传了非空白值时透传，交服务端校验。
+- `directory`（可选，工具参数）：新会话绑定的项目目录（如 `D:\dev\bbcare`）。仅在传了非空白值时透传，交服务端校验。
+- 命令 flag 说明：`--agent` / `--title` 值均为**单个 token**（不处理引号/空格）；仅解析命令后**前导** flag，起始语句内部再出现的 `--xxx` 原样保留；flag 缺值或起始语句为空 → warning toast 且不建会话。`--title` 优先于起始语句首行。
+- 内部调用：`client.session.create({ body: { title }, query: { directory } })` → `client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text: prompt }] } })`；`agent` / `directory` 未传时不出现对应键。
 - 优先 `promptAsync`（异步 fire-and-forget，**不阻塞父会话**）；缺失则回退同步 `prompt`。
 - create 失败 → 不建会话；create 成功但注入失败 → **保留已建会话**并提示 id，不产生重复会话。
 
-## 安装（部署到桌面版）
+## 安装
 
-桌面版从用户配置目录加载活插件：
+在全局或项目 `opencode.json(c)` 的 `plugin` 数组注册包名，重启桌面版生效（opencode 自动拉取最新发布并装入包缓存）：
 
-```bash
-cp index.js package.json "$HOME/.config/opencode/plugins/session-relay/"
+```jsonc
+{
+  "plugin": ["opencode-session-spawn"]
+}
 ```
 
-在全局 `opencode.jsonc` 的 `plugin` 数组注册 `./plugins/session-relay`，重启桌面版生效。
+本地开发也可注册本地目录（opencode 按路径加载）：把 `index.js` + `package.json` 复制到自选目录，在 `plugin` 中写该目录相对路径（如 `./plugins/session-spawn`）。
 
 ## 编排示例
 
-模型在长任务中决定交接，直接调用工具：
+模型在长任务中决定交接，直接调用工具（可选 `agent` / `directory`）：
 
 ```
 spawn_session({
   prompt: `你是本任务的接手会话。先读取交接文书：
 E:\\proj\\handoff\\migration-3.md
 通读后复述要点（已完成/未完成/下一步第 1 件事），确认后继续执行。`,
-  title: "[迁移] 第 3 棒"
+  title: "[迁移] 第 3 棒",
+  agent: "leader",
+  directory: "D:\\dev\\bbcare"
 })
 ```
 
-或人工在会话里发：
+或人工在会话里发（前导 flag 可省略、顺序不限）：
 
 ```
-@spawn 读取 handoff/migration-3.md 后继续迁移任务
+@spawn --agent leader --title "[P1-10] sprint" 读取 handoff/migration-3.md 后继续迁移任务
 ```
 
 ## 开发与测试
 
 ```bash
 npm install          # 安装 devDependency @opencode-ai/plugin（唯一依赖，仅测试用）
-node test/test.mjs   # 12 用例 / 39 断言
+node test/test.mjs   # 23 用例 / 62 断言
 ```
 
-- `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（如生产活实例）。生产版从 `.config/opencode/node_modules` 解析 `@opencode-ai/plugin`。
+- `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（tarball 解包版 / 包缓存活实例）。`RELAY_MAIN` 目标须能向上解析到 `@opencode-ai/plugin`（解包放项目内即可）。
 - 以尾部 `==== 结果: N 通过, 0 失败 ====` 为准。
 
 ## 发布
 
-`index.js` + `package.json` 成对同步生产 → `RELAY_MAIN=<生产路径> node test/test.mjs` 回归全绿 → 重启桌面版实测 → commit → push → `npm publish`（不打 git tag；发布前 `npm whoami` 确认登录态，凭据不入库）。详见 `AGENTS.md`。
+bump 版本号（`package.json` 与 `index.js` 头注释同步）→ `node test/test.mjs` 全绿 → `npm pack` 解包核对哈希 + `RELAY_MAIN` 回归全绿 → commit → push → `npm publish`（不打 git tag；先 `npm whoami` 确认登录态，凭据不入库）→ 重启桌面版实测 `@spawn` / `spawn_session`；实测不过修复补丁重发。详见 `AGENTS.md`。
 
 ## 历史
 

package/index.js

@@ -1,11 +1,12 @@
 import { tool } from "@opencode-ai/plugin/tool";
 
 /**
- * session-spawn —— 会话生成原语（v2.0.0，2026-09-12 卍解简化定稿）
+ * session-spawn —— 会话生成原语（v2.1.1，2026-09-12 起支持 agent/directory）
  *
  * 只做一件事：创建一个新的顶层会话，并把起始语句注入为该会话首条消息。
- *   create: client.session.create({ body: { title } })
- *   inject: client.session.promptAsync({ path: { id }, body: { parts: [{ type: "text", text }] } })
+ *   create: client.session.create({ body: { title }, query: { directory } })
+ *   inject: client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text }] } })
+ *   （agent / directory 均可选，仅在显式传入且非空白时透传；不做校验，交服务端）
  *
  * 设计约束（用户定稿）：
  *   - 插件只负责「建会话 + 注入语句」，不落文书、不读文书、不追踪链、无状态文件。
@@ -36,6 +37,42 @@ function userText(parts) {
     .join(" ");
 }
 
+// 可选参数透传判定：空串 / 纯空白视为未传（返回 undefined）。
+function nonEmpty(v) {
+  return typeof v === "string" && v.trim() !== "" ? v : undefined;
+}
+
+const SPAWN_USAGE = "用法：@spawn [--agent <名称>] [--title <标题>] <起始语句>";
+
+// 解析人工命令：@spawn / @relay spawn，支持前导 --agent / --title。
+// 返回 null（非 spawn 命令）或 { prompt, agent, title } / { error, flag?, agent?, title? }。
+// 规则：仅解析命令后前导的 flag；值均为单个空白分隔 token；剩余内容原样作为起始语句。
+function parseSpawnCommand(text) {
+  const m = /^\s*@(?:relay\s+)?spawn\b([\s\S]*)$/i.exec(String(text || ""));
+  if (!m) return null;
+
+  let rest = m[1];
+  let agent;
+  let title;
+  while (true) {
+    const fm = /^\s*(--agent|--title)(?=\s|$)/.exec(rest);
+    if (!fm) break;
+    rest = rest.slice(fm[0].length);
+    const vm = /^\s+(\S+)/.exec(rest);
+    const value = vm && vm[1];
+    if (!value || value.startsWith("--")) {
+      return { error: "missing-value", flag: fm[1], agent, title };
+    }
+    rest = rest.slice(vm[0].length);
+    if (fm[1] === "--agent") agent = value;
+    else title = value;
+  }
+
+  const prompt = rest.trim();
+  if (!prompt) return { error: "empty-prompt", agent, title };
+  return { prompt, agent, title };
+}
+
 export const SessionSpawn = async (ctx) => {
   const { client } = ctx;
 
@@ -50,34 +87,42 @@ export const SessionSpawn = async (ctx) => {
   };
 
   // 核心：建新会话 + 注入起始语句。
-  // 返回 { id, title, injected, error? }；create 失败则抛出（未建会话）。
-  async function spawn(prompt, title) {
+  // opts.agent / opts.directory 可选；仅在非空白时透传（不做校验，交服务端）。
+  // 返回 { id, title, injected, agent?, directory?, error? }；create 失败则抛出（未建会话）。
+  async function spawn(prompt, title, opts = {}) {
     const text = typeof prompt === "string" ? prompt : "";
     if (!text.trim()) throw new Error("起始语句为空");
     if (!client || !client.session || typeof client.session.create !== "function") {
       throw new Error("client.session.create 不可用");
     }
     const t = (title && String(title).trim()) || defaultTitle(text);
+    const agent = nonEmpty(opts.agent);
+    const directory = nonEmpty(opts.directory);
 
-    const created = await client.session.create({ body: { title: t } });
+    const createReq = { body: { title: t } };
+    if (directory !== undefined) createReq.query = { directory };
+    const created = await client.session.create(createReq);
     const id = created && (created.data?.id || created.id);
     if (!id) throw new Error("create 未返回会话 id");
 
     const body = { parts: [{ type: "text", text }] };
+    if (agent !== undefined) body.agent = agent;
     const injectFn =
       typeof client.session.promptAsync === "function"
         ? client.session.promptAsync.bind(client.session)
         : typeof client.session.prompt === "function"
           ? client.session.prompt.bind(client.session)
           : null;
-    if (!injectFn) return { id, title: t, injected: false, error: "client.session.promptAsync/prompt 均不可用" };
+    if (!injectFn) {
+      return { id, title: t, injected: false, agent, directory, error: "client.session.promptAsync/prompt 均不可用" };
+    }
 
     try {
       await injectFn({ path: { id }, body });
-      return { id, title: t, injected: true };
+      return { id, title: t, injected: true, agent, directory };
     } catch (e) {
       console.error(`[session-spawn] 注入失败（会话 ${id} 已建保留）: ${e.message}`);
-      return { id, title: t, injected: false, error: e.message };
+      return { id, title: t, injected: false, agent, directory, error: e.message };
     }
   }
 
@@ -86,14 +131,16 @@ export const SessionSpawn = async (ctx) => {
     tool: {
       spawn_session: tool({
         description:
-          "创建一个新的顶层会话并向其注入起始语句，用于无人值守长任务编排：当前会话模型在需要时自行决定把工作交给一个新会话继续。新会话会立即开始执行该起始语句。若需让其读取某份交接文书，请把文书路径与读取要求写进 prompt。",
+          "创建一个新的顶层会话并向其注入起始语句，用于无人值守长任务编排：当前会话模型在需要时自行决定把工作交给一个新会话继续。新会话会立即开始执行该起始语句。若需让其读取某份交接文书，请把文书路径与读取要求写进 prompt。agent 可指定新会话以某 agent/模式启动（如 leader）；directory 可绑定项目目录。",
         args: {
           prompt: tool.schema.string().describe("注入新会话的起始语句（可内含读取交接文书路径等引导）"),
           title: tool.schema.string().optional().describe("新会话标题；缺省取起始语句首行"),
+          agent: tool.schema.string().optional().describe("新会话以某 agent/模式启动（如 leader）；缺省由服务端默认"),
+          directory: tool.schema.string().optional().describe("新会话绑定的项目目录（绝对路径，如 D:\\dev\\bbcare）；缺省由服务端默认"),
         },
         async execute(args) {
           try {
-            const r = await spawn(args.prompt, args.title);
+            const r = await spawn(args.prompt, args.title, { agent: args.agent, directory: args.directory });
             if (!r.injected) {
               return `会话「${r.title}」(id=${r.id}) 已创建，但起始语句注入失败：${r.error}。请手动打开该会话补发指令。`;
             }
@@ -105,19 +152,22 @@ export const SessionSpawn = async (ctx) => {
       }),
     },
 
-    // 人工命令：@spawn <起始语句>（兼容 @relay spawn）。
+    // 人工命令：@spawn [--agent <名称>] [--title <标题>] <起始语句>（兼容 @relay spawn）。
     "chat.message": async ({ sessionID }, { parts }) => {
       try {
         const text = userText(parts);
-        const m = /^\s*@(?:relay\s+)?spawn\b([\s\S]*)$/i.exec(text);
-        if (!m) return;
-        const prompt = m[1].trim();
-        if (!prompt) {
-          await notify("spawn", "用法：@spawn <起始语句>", "warning");
+        const parsed = parseSpawnCommand(text);
+        if (!parsed) return;
+        if (parsed.error === "missing-value") {
+          await notify("spawn", `${parsed.flag} 缺少值。${SPAWN_USAGE}`, "warning");
+          return;
+        }
+        if (parsed.error === "empty-prompt") {
+          await notify("spawn", SPAWN_USAGE, "warning");
           return;
         }
         try {
-          const r = await spawn(prompt);
+          const r = await spawn(parsed.prompt, parsed.title, { agent: parsed.agent });
           if (!r.injected) {
             await notify("spawn", `会话「${r.title}」(id=${r.id}) 已创建，但注入失败：${r.error}`, "warning");
           } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-spawn",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "type": "module",
   "description": "opencode 会话生成原语：创建新顶层会话并注入起始语句，用于无人值守长任务编排（工具 spawn_session + 命令 @spawn）。",
   "main": "index.js",