@trim21/personal-pi-extensions 0.0.209 → 0.0.211

package/README.md

@@ -11,6 +11,7 @@
 | [opencode-edit](#opencode-edit)               | 替换内置 edit 工具，使用 opencode 的 schema 和匹配引擎 |
 | [bash-default-timeout](#bash-default-timeout) | 为 bash 工具设置默认超时（180 秒）                     |
 | [vision-agent](#vision-agent)                 | 视觉代理：主模型不支持视觉时，spawn 子 agent 识别图片  |
+| [session-name](#session-name)                 | 首个 user prompt 自动生成会话名，模型命名 + 启发式兜底 |
 | [todowrite](#todowrite)                       | opencode 风格的任务列表工具，完整列表替换语义          |
 | [question](#question)                         | opencode 风格的提问工具，阻塞式询问用户选择            |
 | [talk](#talk)                                 | session 间消息传递，SQLite 邮箱 + 双向 ask 时间戳仲裁  |
@@ -172,6 +173,37 @@ pi -e ./src/vision-agent.ts
 
 ---
 
+## session-name
+
+根据会话的第一个 user prompt 自动生成显示名，在 `/resume` 和 `pi -r` 里更易区分会话。
+
+- **双模式命名**：配置了 `sessionName.model` 时调用命名模型（OpenAI 兼容 API，复用 `~/.pi/agent/models.json` 的 provider 配置）把 prompt 概括成短名；未配置模型、provider 不可解析或模型调用失败时退化为启发式（取首行、去 markdown 装饰、截断到 `maxLength`）。
+- **不覆盖已有名字**：`--name`、`/name` 设置过名字的会话不会被改；恢复的已命名会话同样跳过。
+- **恢复无名会话**：resume/fork 恢复且无名字的会话，从历史第一条 user 消息生成名字。
+- **非阻塞**：命名在后台进行，不拖慢首轮回复；中途切换会话也不会把名字写到错误的 session。
+- **无需配置开箱即用**：缺省按启发式命名。
+
+### 配置
+
+```jsonc
+// ~/.pi/agent/settings.json
+{
+  "sessionName": {
+    "provider": "axonhub", // 可选，缺省回退 defaultProvider
+    "model": "deepseek-v4-flash", // 命名模型；不配置则用启发式
+    "maxLength": 30, // 可选，名字最大长度，默认 30
+  },
+}
+```
+
+### 使用
+
+```bash
+pi -e ./src/session-name.ts
+```
+
+---
+
 ## todowrite
 
 opencode 风格的任务列表工具，参数与语义和 opencode 的 [`todowrite`](https://github.com/anomalyco/opencode) 工具一致。取代原 `todo-pendant.ts` 的 widget 输出方式，改用 `details.pendant.markdown` 渲染（与 vision-agent 相同的 pendant 约定）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.209",
+  "version": "0.0.211",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -25,15 +25,15 @@
     "prepare": "husky"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
+    "@earendil-works/pi-agent-core": ">=0.84.1",
+    "@earendil-works/pi-ai": ">=0.84.1",
+    "@earendil-works/pi-coding-agent": ">=0.84.1",
+    "@earendil-works/pi-tui": ">=0.84.1",
+    "typebox": ">=1.3.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.10",
-    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
     "@eslint/js": "10.0.1",
     "@types/node": "^24.13.3",
     "@typescript-eslint/utils": "8.67.0",
@@ -56,6 +56,7 @@
   "pi": {
     "extensions": [
       "src/vision-agent.ts",
+      "src/session-name.ts",
       "src/bwrap/index.ts",
       "src/workspace-guard.ts",
       "src/opencode-edit.ts",

package/src/bwrap/index.ts

@@ -62,11 +62,12 @@ import { access as fsAccess } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import { type BashOperations, createBashTool, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { type TObject, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { type CommandSpec, parseCommand } from "../lib/cli.js";
 import { expandHome } from "../lib/path.js";
 
 const SANDBOX_PROMPT = `
@@ -711,25 +712,80 @@ export default function bwrapExtension(pi: ExtensionAPI) {
     };
   });
 
-  pi.registerCommand("bwrap", {
+  const BWRAP_SPEC = {
+    name: "bwrap",
+    usage: "",
     description: "Show bwrap sandbox configuration",
-    handler: (_args, ctx) => {
-      const r = getResolved(ctx.hasUI);
-      if (!r.bwrapEnabled) {
-        ctx.ui.notify(`bwrap disabled (mode: ${r.mode})`, "info");
-        return Promise.resolve();
-      }
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const BWRAP_ALLOW_ALL_SPEC = {
+    name: "bwrap-allow-all",
+    usage: "",
+    description: "Disable bwrap sandbox, full access",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
 
-      const net = r.network ? "net" : "no-net";
-      const w = r.writablePaths.map((p) => resolvePath(p, localCwd));
-      const t = r.tmpfsPaths.map((p) => resolvePath(p, localCwd));
+  const BWRAP_WORKSPACE_WRITE_SPEC = {
+    name: "bwrap-workspace-write",
+    usage: "",
+    description: "Sandbox on, network off, workspace writable",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
 
-      ctx.ui.notify(
-        `bwrap ${r.mode} ${net} write:[${w.join(", ")}] tmpfs:[${t.join(", ") || "-"}]`,
-        "info",
-      );
+  const BWRAP_ALLOW_NET_SPEC = {
+    name: "bwrap-allow-net",
+    usage: "",
+    description: "Sandbox on, network on, workspace writable",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const BWRAP_READONLY_SPEC = {
+    name: "bwrap-readonly",
+    usage: "",
+    description: "Sandbox on, network off, no writes",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  /** Parse a /bwrap command; on help/error the text is sent to the session, otherwise run() executes. */
+  function runBwrapCommand(
+    spec: CommandSpec<TObject>,
+    args: string,
+    ctx: ExtensionCommandContext,
+    run: (ctx: ExtensionCommandContext) => void | Promise<void>,
+  ): Promise<void> {
+    const parsed = parseCommand(spec, args);
+    if (parsed.kind !== "ok") {
+      pi.sendMessage({ customType: "info", content: parsed.text, display: true });
       return Promise.resolve();
-    },
+    }
+    return Promise.resolve(run(ctx));
+  }
+
+  pi.registerCommand("bwrap", {
+    description: BWRAP_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_SPEC, args, ctx, (c) => {
+        const r = getResolved(c.hasUI);
+        if (!r.bwrapEnabled) {
+          c.ui.notify(`bwrap disabled (mode: ${r.mode})`, "info");
+          return;
+        }
+
+        const net = r.network ? "net" : "no-net";
+        const w = r.writablePaths.map((p) => resolvePath(p, localCwd));
+        const t = r.tmpfsPaths.map((p) => resolvePath(p, localCwd));
+
+        c.ui.notify(
+          `bwrap ${r.mode} ${net} write:[${w.join(", ")}] tmpfs:[${t.join(", ") || "-"}]`,
+          "info",
+        );
+      }),
   });
 
   function switchMode(
@@ -760,22 +816,28 @@ export default function bwrapExtension(pi: ExtensionAPI) {
   }
 
   pi.registerCommand("bwrap-allow-all", {
-    description: "Disable bwrap sandbox, full access",
-    handler: (_args, ctx) => Promise.resolve(switchMode("allow-all", ctx)),
+    description: BWRAP_ALLOW_ALL_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_ALLOW_ALL_SPEC, args, ctx, (c) => switchMode("allow-all", c)),
   });
 
   pi.registerCommand("bwrap-workspace-write", {
-    description: "Sandbox on, network off, workspace writable",
-    handler: (_args, ctx) => Promise.resolve(switchMode("workspace-write", ctx)),
+    description: BWRAP_WORKSPACE_WRITE_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_WORKSPACE_WRITE_SPEC, args, ctx, (c) =>
+        switchMode("workspace-write", c),
+      ),
   });
 
   pi.registerCommand("bwrap-allow-net", {
-    description: "Sandbox on, network on, workspace writable",
-    handler: (_args, ctx) => Promise.resolve(switchMode("allow-net", ctx)),
+    description: BWRAP_ALLOW_NET_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_ALLOW_NET_SPEC, args, ctx, (c) => switchMode("allow-net", c)),
   });
 
   pi.registerCommand("bwrap-readonly", {
-    description: "Sandbox on, network off, no writes",
-    handler: (_args, ctx) => Promise.resolve(switchMode("readonly", ctx)),
+    description: BWRAP_READONLY_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_READONLY_SPEC, args, ctx, (c) => switchMode("readonly", c)),
   });
 }

package/src/lib/cli.ts

@@ -0,0 +1,340 @@
+/**
+ * Declarative command-line parsing for `/command` handlers.
+ *
+ * The shell-like tokenizer from `cli-args.ts` splits the raw argument string;
+ * this module parses the tokens into positional args plus typed flags. Flags
+ * are declared as a typebox object schema: each property is a flag and the
+ * property key is the long name (`--key`). The property schema decides the
+ * flag kind:
+ *
+ *   Type.Boolean()                    boolean flag (`--flag`)
+ *   Type.String()                     string value flag (`--flag value`)
+ *   Type.Number() / Type.Integer()    number value flag (value is coerced)
+ *   Type.Union([Type.Literal(...)])   string enum value flag (validated)
+ *
+ * Supported syntax (common unix CLI conventions):
+ *
+ *   -s            short boolean flag
+ *   -s value      short flag with value (also `-s=value` and `-svalue`)
+ *   -abc          combined short boolean flags
+ *   --long        long boolean flag
+ *   --long=value  long flag with inline value
+ *   --long value  long flag consuming the next token
+ *   --            everything after is a positional
+ *
+ * `Type.Optional(...)` marks a flag optional (no error when absent) and a
+ * `default` fills in a missing value; both flow through typebox's value
+ * pipeline (default → convert → check) so the `ok` result carries
+ * `Static<TFlags>` flags plus `string[]` args.
+ *
+ * `-h`/`--help` is registered automatically unless the schema declares a
+ * `help` property or a short `h` alias; it renders a usage/options text as
+ * the result so handlers can display it in chat instead of writing stdout.
+ */
+
+import type { Static, TObject } from "typebox";
+import { Value } from "typebox/value";
+
+import { shlexSplit } from "./cli-args.js";
+
+/** Per-flag CLI metadata on top of the typebox schema. */
+export interface FlagMeta {
+  /** Optional short alias (single character), e.g. "n" for `-n`. */
+  short?: string;
+  /** Help line for this flag; defaults to the schema `description`. */
+  description?: string;
+  /** Placeholder shown for value flags in help, e.g. "<alias>"; defaults to `<key>`. */
+  valuePlaceholder?: string;
+}
+
+export interface CommandSpec<TFlags extends TObject> {
+  /** Command name used in usage/help, e.g. "talk-group-join". */
+  name: string;
+  /** Usage text after the command name, e.g. "[group name] [options]". */
+  usage: string;
+  /** One-line description shown under the usage line. */
+  description?: string;
+  /** Typebox object schema describing the flags (key = long flag name). */
+  flags: TFlags;
+  /** Per-flag CLI metadata (short alias, help text). */
+  flagMeta?: { [K in keyof Static<TFlags>]?: FlagMeta };
+  /** Positional count constraints. */
+  arity?: { min?: number; max?: number };
+  /** Example lines rendered under the help text. */
+  examples?: string[];
+}
+
+export type CommandResult<TFlags extends TObject> =
+  | { kind: "ok"; flags: Static<TFlags>; args: string[] }
+  | { kind: "help"; text: string }
+  | { kind: "error"; text: string };
+
+/** Runtime view of a flag schema (typebox's `TSchema` is empty at the type level). */
+interface FlagSchema {
+  "~kind"?: string;
+  "~optional"?: boolean;
+  type?: string;
+  default?: unknown;
+  description?: string;
+  anyOf?: { type?: string; const?: unknown }[];
+}
+
+type FlagKind = "boolean" | "string" | "number" | "enum";
+
+interface FlagInfo {
+  key: string;
+  kind: FlagKind;
+  short?: string;
+  required: boolean;
+  placeholder: string;
+  description: string;
+  schema: FlagSchema;
+}
+
+function kindOf(key: string, schema: FlagSchema): FlagKind {
+  switch (schema["~kind"]) {
+    case "Boolean": {
+      return "boolean";
+    }
+    case "String": {
+      return "string";
+    }
+    case "Number":
+    case "Integer": {
+      return "number";
+    }
+    case "Union": {
+      return "enum";
+    }
+    default: {
+      throw new TypeError(
+        `Unsupported flag type for '${key}': ${schema["~kind"] ?? schema.type ?? "unknown"} ` +
+          "(use Type.Boolean/String/Number/Integer or a string literal union)",
+      );
+    }
+  }
+}
+
+/** Allowed values for a string-literal union flag, or undefined for mixed unions. */
+function enumValues(schema: FlagSchema): string[] | undefined {
+  const anyOf = schema.anyOf;
+  if (!anyOf) return undefined;
+  const values = anyOf.map((s) => s.const).filter((c) => typeof c === "string");
+  return values.length === anyOf.length ? values : undefined;
+}
+
+function buildFlagInfos<TFlags extends TObject>(spec: CommandSpec<TFlags>): FlagInfo[] {
+  const meta = spec.flagMeta as Record<string, FlagMeta> | undefined;
+  const infos: FlagInfo[] = [];
+  for (const [key, rawSchema] of Object.entries(spec.flags.properties)) {
+    const schema = rawSchema as unknown as FlagSchema;
+    const m = meta?.[key];
+    infos.push({
+      key,
+      kind: kindOf(key, schema),
+      short: m?.short,
+      required: schema["~optional"] !== true && schema.default === undefined,
+      placeholder: m?.valuePlaceholder ?? `<${key}>`,
+      description: m?.description ?? schema.description ?? "",
+      schema,
+    });
+  }
+  return infos;
+}
+
+/** Is this token a flag-like argument (a negative number is a value)? */
+function looksLikeFlag(token: string): boolean {
+  return token.startsWith("-") && !/^-\d/.test(token);
+}
+
+function errorResult<TFlags extends TObject>(
+  spec: CommandSpec<TFlags>,
+  message: string,
+): CommandResult<TFlags> {
+  return { kind: "error", text: `${message}\nTry '/${spec.name} --help' for usage.` };
+}
+
+function helpResult<TFlags extends TObject>(
+  spec: CommandSpec<TFlags>,
+  flags: FlagInfo[],
+  autoHelp: boolean,
+): CommandResult<TFlags> {
+  const lines = [`Usage: /${spec.name} ${spec.usage}`];
+  if (spec.description) lines.push("", spec.description);
+  const rows = flags.map((f) => ({
+    rawName:
+      (f.short ? `-${f.short}, ` : "") +
+      `--${f.key}` +
+      (f.kind === "boolean" ? "" : ` ${f.placeholder}`),
+    description: f.description,
+  }));
+  if (autoHelp) rows.push({ rawName: "-h, --help", description: "Display this message" });
+  if (rows.length > 0) {
+    lines.push("", "Options:");
+    const width = Math.max(...rows.map((r) => r.rawName.length));
+    for (const r of rows) lines.push(`  ${r.rawName.padEnd(width)}  ${r.description}`);
+  }
+  if (spec.examples?.length) {
+    lines.push("", "Examples:");
+    for (const e of spec.examples) lines.push(`  ${e}`);
+  }
+  return { kind: "help", text: lines.join("\n") };
+}
+
+export function parseCommand<TFlags extends TObject>(
+  spec: CommandSpec<TFlags>,
+  raw: string,
+): CommandResult<TFlags> {
+  const flags = buildFlagInfos(spec);
+  const byLong = new Map(flags.map((f) => [f.key, f]));
+  const byShort = new Map<string, FlagInfo>();
+  for (const f of flags) {
+    if (!f.short) {
+      continue;
+    }
+
+    if (byShort.has(f.short)) {
+      throw new TypeError(`Duplicate short option '-${f.short}' in /${spec.name}`);
+    }
+    byShort.set(f.short, f);
+  }
+  const autoHelp = !byLong.has("help") && !byShort.has("h");
+
+  let tokens: string[];
+  try {
+    tokens = shlexSplit(raw);
+  } catch (error) {
+    return errorResult(spec, error instanceof Error ? error.message : String(error));
+  }
+
+  const rawFlags: Record<string, unknown> = {};
+  const args: string[] = [];
+  let positionalOnly = false;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (positionalOnly) {
+      args.push(token);
+      continue;
+    }
+    if (token === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (token === "-") {
+      args.push(token);
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const body = token.slice(2);
+      const eq = body.indexOf("=");
+      const name = eq === -1 ? body : body.slice(0, eq);
+      if (autoHelp && name === "help") return helpResult(spec, flags, autoHelp);
+      const info = byLong.get(name);
+      if (!info) return errorResult(spec, `Unknown option '--${name}'`);
+      const inline = eq === -1 ? undefined : body.slice(eq + 1);
+      if (inline !== undefined) {
+        rawFlags[info.key] = inline;
+      } else if (info.kind === "boolean") {
+        rawFlags[info.key] = true;
+      } else {
+        const next = tokens[i + 1];
+        if (next !== undefined && !looksLikeFlag(next)) {
+          rawFlags[info.key] = next;
+          i++;
+        } else if (autoHelp && next !== undefined && (next === "--help" || next === "-h")) {
+          return helpResult(spec, flags, autoHelp);
+        } else {
+          return errorResult(spec, `Option '--${name}' requires a value`);
+        }
+      }
+      continue;
+    }
+    if (token.startsWith("-")) {
+      const rest = token.slice(1);
+      for (let j = 0; j < rest.length; j++) {
+        const c = rest[j];
+        if (autoHelp && c === "h") return helpResult(spec, flags, autoHelp);
+        const info = byShort.get(c);
+        if (!info) return errorResult(spec, `Unknown option '-${c}'`);
+        if (info.kind === "boolean") {
+          rawFlags[info.key] = true;
+          continue;
+        }
+        if (rest[j + 1] === "=") {
+          rawFlags[info.key] = rest.slice(j + 2);
+        } else if (j + 1 < rest.length) {
+          rawFlags[info.key] = rest.slice(j + 1);
+        } else {
+          const next = tokens[i + 1];
+          if (next !== undefined && !looksLikeFlag(next)) {
+            rawFlags[info.key] = next;
+            i++;
+          } else if (autoHelp && next !== undefined && (next === "--help" || next === "-h")) {
+            return helpResult(spec, flags, autoHelp);
+          } else {
+            return errorResult(spec, `Option '-${c}' requires a value`);
+          }
+        }
+        break;
+      }
+      continue;
+    }
+    args.push(token);
+  }
+
+  for (const f of flags) {
+    if (f.required && !(f.key in rawFlags)) {
+      return errorResult(spec, `Missing required option '--${f.key}'`);
+    }
+  }
+
+  for (const f of flags) {
+    if (f.kind === "enum" && typeof rawFlags[f.key] === "string") {
+      const values = enumValues(f.schema);
+      if (values && !values.includes(rawFlags[f.key] as string)) {
+        return errorResult(
+          spec,
+          `Invalid value for '--${f.key}': '${String(rawFlags[f.key])}' (expected one of: ${values.join(", ")})`,
+        );
+      }
+    }
+    if (f.kind === "number" && typeof rawFlags[f.key] === "string") {
+      const n = Number(rawFlags[f.key]);
+      if (Number.isNaN(n)) {
+        return errorResult(spec, `Invalid value for '--${f.key}': '${String(rawFlags[f.key])}'`);
+      }
+      rawFlags[f.key] = n;
+    }
+  }
+
+  const { min, max } = spec.arity ?? {};
+  if (max !== undefined && args.length > max) {
+    const extra = args
+      .slice(max)
+      .map((a) => `'${a}'`)
+      .join(", ");
+    return errorResult(spec, `Too many arguments: ${extra} (expected at most ${max})`);
+  }
+  if (min !== undefined && args.length < min) {
+    return errorResult(spec, `Missing required argument: expected ${spec.usage}`);
+  }
+
+  // typebox value pipeline: defaults → coercion → check.
+  let parsed: unknown;
+  try {
+    parsed = Value.Default(spec.flags, rawFlags);
+    parsed = Value.Convert(spec.flags, Value.Clone(parsed));
+    if (!Value.Check(spec.flags, parsed)) {
+      const [first] = [...Value.Errors(spec.flags, parsed)];
+      return errorResult(
+        spec,
+        `Invalid arguments: ${first?.message ?? "value does not match flags"}`,
+      );
+    }
+  } catch {
+    return errorResult(spec, "Invalid arguments");
+  }
+
+  return { kind: "ok", flags: parsed, args };
+}

package/src/opencode-todo.ts

@@ -23,7 +23,8 @@
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 // ── constants ────────────────────────────────────────────────────────────────
@@ -120,7 +121,7 @@ export function serializeTodos(todos: readonly TodoInfo[]): string {
 
 const STATUS_MARK: Record<TodoStatus, string> = {
   pending: " ",
-  in_progress: " ",
+  in_progress: ">",
   completed: "x",
   cancelled: "-",
 };
@@ -180,5 +181,14 @@ export default function todowrite(pi: ExtensionAPI) {
         },
       });
     },
+
+    renderResult(result) {
+      // 用 buildTodoMarkdown 生成任务列表 markdown，经 TUI Markdown 组件渲染。
+      // 折叠时只显示前几项，展开时显示完整列表（与 widget 的 pendant.expanded 语义一致）。
+      const todos = result.details.todos;
+      const display = todos.slice(0, 8);
+      const markdown = buildTodoMarkdown(display);
+      return new Markdown(markdown, 0, 0, getMarkdownTheme());
+    },
   });
 }

package/src/session-name.ts

@@ -0,0 +1,333 @@
+/**
+ * session-name —— 自动会话命名扩展
+ *
+ * 在会话收到第一个 user prompt 时自动生成显示名，方便在 /resume 和 pi -r
+ * 中区分会话：
+ * - 配置了 sessionName.model 时，通过 pi 的模型注册表（ctx.modelRegistry）
+ *   直接调用命名模型把 prompt 概括成短名 —— 复用 pi 的 provider 解析
+ *   （~/.pi/agent/models.json 的 baseUrl/apiKey/env/OAuth）与 AI SDK，
+ *   不手写 HTTP 请求（模型来自 ~/.pi/agent/settings.json 的 sessionName 与
+ *   defaultProvider，与 vision-agent 同一套配置体系）；
+ * - 未配置模型、模型在注册表中找不到或模型调用失败时退化为启发式命名
+ *   （取首行、去 markdown 装饰、截断到 maxLength）。
+ *
+ * 已命名的会话（--name / /name / 恢复的已命名 session）不会被覆盖；
+ * 恢复的无名会话从历史第一条 user 消息生成名字。命名在后台进行，不阻塞
+ * agent 启动；会话切换 / reload 后捕获的 pi 会抛 stale 错误，被 catch
+ * 忽略，名字绝不会写到错误的 session。
+ *
+ * 使用前提：无。未配置 sessionName 时开箱即用（启发式命名）。
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  type Api,
+  type ApiStreamOptions,
+  type AssistantMessage,
+  contentText,
+  type Context,
+  type Model,
+} from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { jsoncToJson } from "./lib/jsonc.js";
+
+// ── constants ────────────────────────────────────────────────────────────────
+
+/** ~/.pi/agent/settings.json：sessionName 配置所在文件 */
+export const SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+/** 会话名最大长度（字符），模型命名与启发式共用 */
+export const DEFAULT_MAX_LENGTH = 30;
+/** 命名请求超时。ctx.signal 在 agent 空闲时为 undefined，不能只依赖它 */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * 命名模型输出上限。命名任务本身简单，但 reasoning 模型（如 deepseek-v4-flash）
+ * 会先输出推理过程再给最终名字：64 太小会在推理阶段被截断导致 content 为空，
+ * 调大到与 vision-agent 的 DEFAULT_MAX_TOKENS 一致，保证推理模型正常出结果。
+ */
+export const NAMER_MAX_TOKENS = 4096;
+
+// ── types ────────────────────────────────────────────────────────────────────
+
+export interface SessionNameConfig {
+  provider?: string;
+  model?: string;
+  maxLength?: number;
+}
+
+/**
+ * 命名所需的模型注册表操作：扩展传 ctx.modelRegistry，测试传 mock。
+ * 结构化类型（duck typing），只声明用到的两个方法。
+ */
+export interface ModelRegistryLike {
+  find(provider: string, modelId: string): Model<Api> | undefined;
+  complete(
+    model: Model<Api>,
+    context: Context,
+    options?: ApiStreamOptions<Api> & { signal?: AbortSignal },
+  ): Promise<AssistantMessage>;
+}
+
+/** 命名所需的 session 操作：扩展传 pi，测试传 mock */
+export interface NamerAPI {
+  getSessionName(): string | undefined;
+  setSessionName(name: string): void;
+}
+
+/** 触发时的 UI / 模型上下文；print / json 模式（hasUI=false）下不通知 */
+export interface SessionNamingContext {
+  hasUI?: boolean;
+  notify?: (message: string) => void;
+  /** 模型注册表（ctx.modelRegistry），用于按 provider/model 解析并调用命名模型 */
+  registry?: ModelRegistryLike;
+  /** 当前 abort signal；agent 空闲时为 undefined */
+  signal?: AbortSignal;
+}
+
+/** 只依赖 type/message.role/content 字段，不绑定 pi 内部类型 */
+export interface UserMessageLike {
+  type: string;
+  message?: { role?: string; content?: unknown } | null;
+}
+
+// ── 配置解析（纯函数，可测试）───────────────────────────────────────────────
+
+/**
+ * 读取 ~/.pi/agent/settings.json 的 sessionName 配置。
+ * provider 缺省时回退到 defaultProvider；文件缺失 / JSON 损坏 / 无 sessionName
+ * 时返回 undefined。支持 jsonc（注释/尾逗号），与 pi 文档的 settings.json
+ * 示例一致。
+ */
+export function loadSessionNameConfig(settingsPath = SETTINGS_PATH): SessionNameConfig | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(settingsPath, "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(jsoncToJson(raw));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    const settings = parsed as Record<string, unknown>;
+    const sn = settings.sessionName;
+    if (!sn || typeof sn !== "object" || Array.isArray(sn)) return undefined;
+    const config = sn as Record<string, unknown>;
+    const provider =
+      typeof config.provider === "string" ? config.provider.trim() || undefined : undefined;
+    const defaultProvider =
+      typeof settings.defaultProvider === "string"
+        ? settings.defaultProvider.trim() || undefined
+        : undefined;
+    const maxLength =
+      typeof config.maxLength === "number" && config.maxLength > 0
+        ? Math.floor(config.maxLength)
+        : undefined;
+    return {
+      provider: provider ?? defaultProvider,
+      model: typeof config.model === "string" ? config.model.trim() || undefined : undefined,
+      maxLength,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+// ── 文本提取与命名生成（纯函数，可测试）────────────────────────────────────
+
+/** 从消息 content（字符串或分片数组）提取文本 */
+function messageText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part: unknown) => {
+      if (typeof part === "string") return part;
+      if (
+        part &&
+        typeof part === "object" &&
+        typeof (part as Record<string, unknown>).text === "string"
+      ) {
+        return (part as Record<string, unknown>).text as string;
+      }
+      return "";
+    })
+    .join("")
+    .trim();
+}
+
+/**
+ * 取要命名的 prompt 文本：新会话（branch 为空）用当前 prompt；
+ * 恢复的会话从历史找第一条 user 消息。找不到可命名文本时返回 undefined。
+ */
+export function extractFirstUserPrompt(
+  branch: readonly UserMessageLike[],
+  currentPrompt: string,
+): string | undefined {
+  const trimmed = currentPrompt.trim();
+  if (branch.length > 0) {
+    for (const entry of branch) {
+      if (entry.type !== "message") continue;
+      const text = messageText(entry.message?.content);
+      if (text) return text;
+    }
+  }
+  return trimmed || undefined;
+}
+
+/** 折叠空白、限制长度；空结果返回 undefined */
+export function sanitizeName(raw: string, maxLength = DEFAULT_MAX_LENGTH): string | undefined {
+  const collapsed = raw.replaceAll(/\s+/g, " ").trim();
+  if (!collapsed) return undefined;
+  if (collapsed.length <= maxLength) return collapsed;
+  return `${collapsed.slice(0, maxLength - 1).trimEnd()}…`;
+}
+
+/**
+ * 启发式命名：取第一个非空行（首行为代码围栏时跳过），去掉常见 markdown
+ * 装饰，截断到 maxLength。适用于未配置命名模型、模型调用失败等场景。
+ */
+export function heuristicName(text: string, maxLength = DEFAULT_MAX_LENGTH): string | undefined {
+  const lines = text
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  const first = lines[0];
+  // "```" / "```ts" 之类的纯代码围栏行不是内容，取下一行
+  const line = first && /^`{1,3}\w*$/.test(first) ? (lines[1] ?? first) : first;
+  if (!line) return undefined;
+  const cleaned = line
+    .replace(/^#{1,6}\s+/, "") // 标题
+    .replace(/^[-*+]\s+/, "") // 无序列表
+    .replace(/^\d+[.)]\s+/, "") // 有序列表
+    .replace(/^>\s?/, "") // 引用
+    .replace(/^`{1,3}/, "") // 行首代码围栏 / 行内代码
+    .replace(/`{1,3}$/, "") // 行尾代码围栏
+    .trim();
+  return sanitizeName(cleaned || line, maxLength);
+}
+
+// ── 命名模型调用 ─────────────────────────────────────────────────────────────
+
+/** 命名模型的 system prompt：只输出一个短名 */
+export function buildNamerPrompt(maxLength: number): string {
+  return [
+    "你是一个会话命名助手。根据用户给出的第一条消息内容，生成一个简洁的会话显示名。",
+    `要求：不超过 ${maxLength} 个字符，概括消息主题；只输出名字本身，不要引号、标点、解释或多余说明。`,
+    "消息是中文时用中文命名，英文时用英文命名，保持原有语言。",
+  ].join("\n");
+}
+
+/** 合并调用方 signal 与本地超时；调用方未传时仍然有超时兜底 */
+function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal {
+  const timeout = AbortSignal.timeout(ms);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+/**
+ * 通过模型注册表调用命名模型，让模型把 prompt 概括成短名。
+ * 走 pi 的 AI SDK（modelRegistry.complete），复用 provider 解析与
+ * thinking/重试/usage 等基础设施，不手写 HTTP 请求。
+ *
+ * 注意：contentText 只取 content 里的 text 块（自动排除 thinking），
+ * 推理模型的思考过程不会被当作会话名。
+ *
+ * @returns 模型返回的原始文本（未清洗，需再经 sanitizeName）
+ */
+export async function callNamer(
+  registry: ModelRegistryLike,
+  model: Model<Api>,
+  text: string,
+  maxLength: number,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await registry.complete(
+    model,
+    {
+      systemPrompt: buildNamerPrompt(maxLength),
+      messages: [{ role: "user", content: text, timestamp: Date.now() }],
+    },
+    { maxTokens: NAMER_MAX_TOKENS, signal: withTimeout(signal, REQUEST_TIMEOUT_MS) },
+  );
+  const output = contentText(result.content).trim();
+  if (!output) {
+    throw new Error("API 未返回内容");
+  }
+  return output;
+}
+
+// ── 命名编排 ─────────────────────────────────────────────────────────────────
+
+/**
+ * 生成会话名：配置了命名模型且能在注册表中解析到模型时优先用模型生成
+ * （失败退化），否则用启发式。模型输出与启发式结果都经过 sanitizeName，
+ * 保证 ≤ maxLength。
+ */
+export async function generateSessionName(
+  text: string,
+  config: SessionNameConfig | undefined,
+  options: {
+    registry?: ModelRegistryLike;
+    signal?: AbortSignal;
+  } = {},
+): Promise<string | undefined> {
+  const maxLength = config?.maxLength ?? DEFAULT_MAX_LENGTH;
+  const model = config?.model;
+  if (model) {
+    const registry = options.registry;
+    const resolved = registry?.find(config.provider ?? "default", model);
+    if (registry && resolved) {
+      const raw = await callNamer(registry, resolved, text, maxLength, options.signal).catch(
+        () => "",
+      );
+      if (raw) {
+        const name = sanitizeName(raw, maxLength);
+        if (name) return name;
+      }
+    }
+  }
+  return heuristicName(text, maxLength);
+}
+
+/**
+ * 完整命名流程：读配置 → 生成名字 → 设置会话名并通知。
+ * 失败（如会话已切换导致 pi stale）由调用方 catch 忽略。
+ */
+export async function nameSession(
+  pi: NamerAPI,
+  text: string,
+  ctx: SessionNamingContext = {},
+): Promise<void> {
+  const config = loadSessionNameConfig();
+  const name = await generateSessionName(text, config, {
+    registry: ctx.registry,
+    signal: ctx.signal,
+  });
+  if (!name) return;
+  pi.setSessionName(name);
+  if (ctx.hasUI && ctx.notify) {
+    ctx.notify(`会话已命名为: ${name}`);
+  }
+}
+
+// ── extension ────────────────────────────────────────────────────────────────
+
+export default function sessionNameExtension(pi: ExtensionAPI) {
+  // 首个 user prompt 到达时自动命名。命名是后台副作用，不阻塞 agent 启动；
+  // 会话切换 / reload 后捕获的 pi 会抛 stale 错误，被 catch 忽略，名字
+  // 绝不会写到错误的 session。
+  pi.on("before_agent_start", (event, ctx) => {
+    if (pi.getSessionName()) return;
+    const text = extractFirstUserPrompt(ctx.sessionManager.getBranch(), event.prompt);
+    if (!text) return;
+    void nameSession(pi, text, {
+      hasUI: ctx.hasUI,
+      notify: (message) => ctx.ui.notify(message, "info"),
+      registry: ctx.modelRegistry,
+      signal: ctx.signal,
+    }).catch(() => {
+      return; // 会话切换 / reload 后 pi 已 stale，名字不会写错 session，忽略即可
+    });
+  });
+}

package/src/talk/index.ts

@@ -16,9 +16,9 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { type TObject, Type } from "typebox";
 
-import { parseArgs } from "../lib/cli-args.js";
+import { type CommandResult, type CommandSpec, parseCommand } from "../lib/cli.js";
 import { resolveHomePath } from "../lib/path.js";
 import { TalkCore } from "./core.js";
 import { formatDelivery } from "./format.js";
@@ -281,92 +281,155 @@ export default function talk(pi: ExtensionAPI) {
 
   // ── /talk commands ────────────────────────────────────────────────────
 
-  pi.registerCommand("talk", {
-    description: "List registered pi agents",
-    async handler() {
-      const text = requireInit() ?? (await core.list());
+  type OkResult<TFlags extends TObject> = Extract<CommandResult<TFlags>, { kind: "ok" }>;
+
+  /** Parse a /talk command; on help/error or init failure the text is sent, otherwise run() produces the listing text. */
+  function handleCommand<TFlags extends TObject>(
+    spec: CommandSpec<TFlags>,
+    args: string,
+    run: (parsed: OkResult<TFlags>) => Promise<string> | string,
+  ): Promise<void> {
+    const parsed = parseCommand(spec, args);
+    if (parsed.kind !== "ok") {
+      pi.sendMessage({ customType: LIST_TYPE, content: parsed.text, display: true });
+      return Promise.resolve();
+    }
+    return (async () => {
+      const initError = requireInit();
+      const text = initError ?? (await run(parsed));
       pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
-  });
+    })();
+  }
 
-  pi.registerCommand("talk-dead", {
+  const TALK_SPEC = {
+    name: "talk",
+    usage: "",
+    description: "List registered pi agents",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_DEAD_SPEC = {
+    name: "talk-dead",
+    usage: "[agentId] [options]",
     description:
       "Mark a talk agent as dead (shown offline, swept soon): no arg = this agent, <agentId> = that agent, --all = every other visible agent",
-    async handler(args) {
-      const initError = requireInit();
-      const trimmed = args.trim();
-      const text =
-        initError ??
-        (trimmed === "--all"
+    flags: Type.Object({
+      all: Type.Optional(Type.Boolean({ description: "Mark every other visible agent dead" })),
+    }),
+    flagMeta: { all: { short: "a" } },
+    arity: { max: 1 },
+  };
+
+  const TALK_GROUP_JOIN_SPEC = {
+    name: "talk-group-join",
+    usage: "[group name] [options]",
+    description:
+      "Join or create a private agent group (members see only each other; an agent in no group sees only itself). No arg = new group with a generated uuid; <name> = join that group, or create it when it does not exist; --name <alias> additionally sets this agent's display name",
+    flags: Type.Object({
+      name: Type.Optional(Type.String({ description: "Set this agent's display name" })),
+    }),
+    flagMeta: { name: { short: "n", valuePlaceholder: "<alias>" } },
+    arity: { max: 1 },
+    examples: ["/talk-group-join frontend", "/talk-group-join --name frontend"],
+  };
+
+  const TALK_GROUP_JOIN_LAST_SPEC = {
+    name: "talk-group-join-last",
+    usage: "",
+    description: "Join the most recently created agent group (no-op when already in it).",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_LEAVE_SPEC = {
+    name: "talk-group-leave",
+    usage: "",
+    description: "Leave the current agent group (an emptied group is deleted).",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_LIST_SPEC = {
+    name: "talk-group-list",
+    usage: "",
+    description: "List all agent groups and their members, newest first.",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_DEL_SPEC = {
+    name: "talk-group-del",
+    usage: "<group name>",
+    description:
+      "Delete an agent group by name; its members become ungrouped (see only themselves).",
+    flags: Type.Object({}),
+    arity: { min: 1, max: 1 },
+  };
+
+  const TALK_GROUP_CLEAR_SPEC = {
+    name: "talk-group-clear",
+    usage: "",
+    description: "Delete every agent group; all agents become ungrouped.",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  pi.registerCommand("talk", {
+    description: TALK_SPEC.description,
+    handler: (args) => handleCommand(TALK_SPEC, args, async () => core.list()),
+  });
+
+  pi.registerCommand("talk-dead", {
+    description: TALK_DEAD_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_DEAD_SPEC, args, async (parsed) => {
+        if (parsed.flags.all && parsed.args.length > 0) {
+          return "--all cannot be combined with an agent id.\nTry '/talk-dead --help' for usage.";
+        }
+        return parsed.flags.all
           ? await core.markAllDead()
-          : trimmed
-            ? await core.markDead(trimmed)
-            : await core.markDead());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+          : parsed.args[0]
+            ? await core.markDead(parsed.args[0])
+            : await core.markDead();
+      }),
   });
 
   pi.registerCommand("talk-group-join", {
-    description:
-      "Join or create a private agent group (members see only each other; an agent in no group sees only itself). No arg = new group with a generated uuid; <name> = join that group, or create it when it does not exist; --name <alias> additionally sets this agent's display name (e.g. --name frontend)",
-    async handler(args) {
-      const initError = requireInit();
-      const parsed = parseArgs(args);
-      const groupName = parsed.positionals[0];
-      const flag = parsed.flags.name;
-      const agentName = typeof flag === "string" && flag.trim() !== "" ? flag.trim() : undefined;
-      if (agentName !== undefined) explicitName = agentName;
-      const text = initError ?? (await core.groupJoin(groupName || undefined, agentName));
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_JOIN_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_JOIN_SPEC, args, async (parsed) => {
+        const agentName = parsed.flags.name?.trim() || undefined;
+        if (agentName !== undefined) explicitName = agentName;
+        return core.groupJoin(parsed.args[0], agentName);
+      }),
   });
 
   pi.registerCommand("talk-group-join-last", {
-    description: "Join the most recently created agent group (no-op when already in it).",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupJoinLast());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_JOIN_LAST_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_JOIN_LAST_SPEC, args, async () => core.groupJoinLast()),
   });
 
   pi.registerCommand("talk-group-leave", {
-    description: "Leave the current agent group (an emptied group is deleted).",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupLeave());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_LEAVE_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_LEAVE_SPEC, args, async () => core.groupLeave()),
   });
 
   pi.registerCommand("talk-group-list", {
-    description: "List all agent groups and their members, newest first.",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupList());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_LIST_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_LIST_SPEC, args, async () => core.groupList()),
   });
 
   pi.registerCommand("talk-group-del", {
-    description:
-      "Delete an agent group by name; its members become ungrouped (see only themselves).",
-    async handler(args) {
-      const initError = requireInit();
-      const name = args.trim();
-      const text =
-        initError ?? (name ? await core.groupDelete(name) : "Usage: /talk-group-del <group name>");
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_DEL_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_DEL_SPEC, args, async (parsed) => core.groupDelete(parsed.args[0])),
   });
 
   pi.registerCommand("talk-group-clear", {
-    description: "Delete every agent group; all agents become ungrouped.",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupClear());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_CLEAR_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_CLEAR_SPEC, args, async () => core.groupClear()),
   });
 
   // ── Delivery card ──────────────────────────────────────────────────────