omo-slim-plan 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.1
+
+- Interactive Telegram first-run setup: only a bot token is required; `chat_id` is captured after you message the bot (`getUpdates`), shown for confirmation, then saved
+- New CLI flag: `npx omo-slim-plan --setup-telegram`
+- `--telegram-token` without `--telegram-chat-id` now auto-enters interactive setup after install
+- Event `test` bypasses webhook event filters so the setup test notification can always verify config
+- New helper module `plugin/planflow-telegram.mjs` (getMe / getUpdates / confirm / save / test send)
+
+## 0.1.0
+
+- Initial public release: plan-first workflow for OpenCode + oh-my-opencode-slim
+- Commands: `/plan`, `/start-work`, `/plan-review`
+- Skill `plan-workflow` (`.plans/` contract, human gates, checkbox progress)
+- Plugin `planflow` + notify CLI + extensible providers (`telegram` / `generic` / `command`)
+- npx installer (zero runtime deps)

package/README.md

@@ -52,36 +52,36 @@ What the installer does:
 
 `OPencode_CONFIG` overrides the config root. `--config <path>` sets it too (directory, or a `planflow.json` path). Existing targets are backed up to `*.bak-<timestamp>` before overwrite. After install: **restart OpenCode**.
 
-## Configure Telegram
+## Configure Telegram (first run)
 
-1. Talk to [@BotFather](https://t.me/BotFather) on Telegram → `/newbot` → copy the **bot token**.
-2. Add the bot to your target chat, then get the **chat id** (e.g. via `https://api.telegram.org/bot<TOKEN>/getUpdates`, or send a message and inspect the response).
-3. Fill in `~/.config/opencode/planflow.json`:
+You only need a **bot token** first. `chat_id` is captured interactively — no manual lookup.
 
-```json
-{
-  "version": 1,
-  "plansDir": ".plans",
-  "webhook": {
-    "provider": "telegram",
-    "telegram": {
-      "botToken": "123456:ABC-your-token",
-      "chatId": "-1001234567890"
-    },
-    "generic": { "url": "", "headers": {} },
-    "command": { "cmd": "" },
-    "events": {
-      "plan-ready": true,
-      "awaiting-review": true,
-      "task-done": false,
-      "awaiting-acceptance": true
-    },
-    "titlePrefix": "[omo-slim-plan]"
-  }
-}
+1. Talk to [@BotFather](https://t.me/BotFather) → `/newbot` → copy the **bot token**.
+2. Install / run setup (chat_id optional on the command line):
+
+```bash
+npx omo-slim-plan --telegram-token "123456:ABC-your-token"
+# re-run anytime
+npx omo-slim-plan --setup-telegram
 ```
 
-Or pass flags at install time:
+3. The installer calls Telegram `getMe`, prints your bot username, and asks you to **message the bot** (any text, e.g. `/start`).
+4. It polls `getUpdates` and shows the captured message:
+
+```text
+捕获到消息:
+  chat_id   : 123456789
+  chat_type : private
+  from      : lofibass (@lofibass)
+  text      : hi
+```
+
+5. Confirm `[Y/n]` → `chat_id` is saved to `~/.config/opencode/planflow.json` (`provider=telegram`).
+6. A test message (`Telegram 配置成功`) is sent to verify the path.
+
+If provider is `telegram` but `chatId` is empty, notifications report `telegram_not_configured` until setup completes — re-run `--setup-telegram`.
+
+Manual config still works: set `webhook.telegram.botToken` + `chatId` in `planflow.json`, or pass both flags:
 
 ```bash
 node bin/install.js --telegram-token "123456:ABC..." --telegram-chat-id "-1001234567890"
@@ -95,6 +95,7 @@ node bin/install.js --telegram-token "123456:ABC..." --telegram-chat-id "-100123
 | `awaiting-review` | on | `/plan-review` starts (oracle review) |
 | `task-done` | off | each todo completed during `/start-work` |
 | `awaiting-acceptance` | on | all Todos + Final checks done |
+| `test` | n/a | setup test notification (always allowed) |
 
 Set any event to `false` to silence it. **A missing/unconfigured provider never blocks the workflow** — notify failures are logged and work continues.
 

package/bin/install.js

@@ -4,7 +4,11 @@
 // Usage:
 //   node bin/install.js [--dry-run] [--force] [--uninstall]
 //                       [--webhook <url>] [--telegram-token <t>] [--telegram-chat-id <id>]
-//                       [--config <path>]
+//                       [--setup-telegram] [--config <path>]
+//
+// Telegram first-run: pass --telegram-token (or --setup-telegram). After files
+// are installed, the installer can capture chat_id interactively (message the
+// bot → getUpdates → confirm) so users never need to look up chat_id manually.
 //
 // Defaults:
 //   Config root : $OPencode_CONFIG  ||  ~/.config/opencode
@@ -25,12 +29,17 @@ import {
 } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 const COMMAND_FILES = ["plan.md", "start-work.md", "plan-review.md"];
-const PLUGIN_FILES = ["planflow.js", "planflow-notify.mjs", "planflow-providers.mjs"];
+const PLUGIN_FILES = [
+  "planflow.js",
+  "planflow-notify.mjs",
+  "planflow-providers.mjs",
+  "planflow-telegram.mjs",
+];
 const DEFAULT_PLANFLOW = {
   version: 1,
   plansDir: ".plans",
@@ -77,6 +86,7 @@ function parseArgs(argv) {
     webhook: "",
     telegramToken: "",
     telegramChatId: "",
+    setupTelegram: false,
     config: "",
     help: false,
   };
@@ -110,6 +120,10 @@ function parseArgs(argv) {
       args.uninstall = true;
       continue;
     }
+    if (a === "--setup-telegram") {
+      args.setupTelegram = true;
+      continue;
+    }
     if (a.startsWith("--") && a.includes("=")) {
       const eq = a.indexOf("=");
       const key = a.slice(0, eq);
@@ -148,7 +162,8 @@ function usage() {
       "  --uninstall               Remove installed files; unregister plugin; keep planflow.json unless --force",
       "  --webhook <url>           generic webhook provider (sets provider=generic, generic.url=<url>)",
       "  --telegram-token <t>      Telegram bot token (sets provider=telegram)",
-      "  --telegram-chat-id <id>   Telegram chat id",
+      "  --telegram-chat-id <id>   Telegram chat id (optional; omit to capture interactively)",
+      "  --setup-telegram          Interactive Telegram setup: message the bot, confirm chat_id",
       "  --config <path>           OpenCode config root (dir) or planflow.json path",
       "  -h, --help                Show help",
       "",
@@ -339,12 +354,20 @@ function removeIfExists(target, dryRun, roots, label) {
   return { removed: true };
 }
 
-function printNextSteps(p) {
+function readPlanflowJsonSafe(planflowPath) {
+  try {
+    return JSON.parse(readFileSync(planflowPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function printNextSteps(p, setupState) {
   log("");
   log(bold("Next steps:"));
   log("  1. Restart OpenCode so it loads the planflow plugin.");
   log(`  2. Configure Telegram (or generic/command) in ${p.planflowPath}`);
-  log('     - telegram: fill webhook.telegram.botToken + webhook.telegram.chatId');
+  log("     - telegram: npx omo-slim-plan --setup-telegram   (message the bot; chat_id is captured)");
   log("     - generic:  set webhook.provider=generic + webhook.generic.url");
   log("     - command:  set webhook.provider=command + webhook.command.cmd");
   log("  3. In a project, run /plan — AI writes .plans/<slug>.md, then you choose:");
@@ -352,12 +375,68 @@ function printNextSteps(p) {
   log("");
   log(`  Commands installed: ${p.commandDir}/plan.md, start-work.md, plan-review.md`);
   log(`  Skill installed:    ${p.skillDest}`);
-  log(`  Plugin installed:   ${p.pluginDir}/planflow.js (+ planflow-notify.mjs, planflow-providers.mjs)`);
+  log(`  Plugin installed:   ${p.pluginDir}/planflow.js (+ planflow-notify.mjs, planflow-providers.mjs, planflow-telegram.mjs)`);
   log(`  Notify CLI:         ${p.pluginDir}/planflow-notify.mjs`);
   log(`  Plans convention:   .plans/ per project (see templates/plans/README.md; commit plans, not boulder)`);
+  if (setupState) {
+    if (setupState.saved) {
+      log("");
+      log(green(`  Telegram chat_id saved: ${setupState.chatId}`));
+    } else if (setupState.needed) {
+      log("");
+      warn("  Telegram chat_id is empty — run setup to capture it:");
+      log("    npx omo-slim-plan --setup-telegram");
+      log("    # or: node bin/install.js --setup-telegram");
+    }
+  }
 }
 
-function runInstall(args, p) {
+/**
+ * Decide whether interactive Telegram setup should run after install.
+ * Returns { needed, reason }.
+ */
+function evaluateTelegramSetup(args, cfg) {
+  if (args.uninstall) return { needed: false, reason: "skipped" };
+  if (args.setupTelegram) return { needed: true, reason: "flag" };
+  if (args.telegramChatId) return { needed: false, reason: "chat_id_already_set" };
+  const tg = cfg?.webhook?.telegram || {};
+  const provider = cfg?.webhook?.provider || "telegram";
+  const hasToken = Boolean(String(args.telegramToken || tg.botToken || "").trim());
+  const hasChat = Boolean(String(tg.chatId || "").trim());
+  if (provider === "telegram" && hasToken && !hasChat) {
+    return { needed: true, reason: "token_without_chat_id" };
+  }
+  return { needed: false, reason: hasChat ? "chat_id_already_set" : "telegram_not_requested" };
+}
+
+function shouldRunTelegramSetup(args, p, cfg) {
+  if (args.dryRun) return { needed: false, reason: "dry_run" };
+  return evaluateTelegramSetup(args, cfg);
+}
+
+async function runInteractiveTelegramSetup(args, p, plan) {
+  const { runTelegramSetup } = await import(
+    pathToFileURL(path.join(PKG_ROOT, "plugin", "planflow-telegram.mjs")).href
+  );
+  const cfg = readPlanflowJsonSafe(p.planflowPath) || {};
+  const token = String(args.telegramToken || cfg?.webhook?.telegram?.botToken || "").trim();
+  log("");
+  log(bold("Telegram setup:"));
+  if (!process.stdin.isTTY && !token) {
+    warn("stdin is not a TTY and no --telegram-token was provided — skipping interactive setup");
+    log("  re-run: npx omo-slim-plan --setup-telegram --telegram-token <token>");
+    return { needed: true, saved: false, chatId: null, tested: false };
+  }
+  const result = await runTelegramSetup({
+    token,
+    planflowPath: p.planflowPath,
+    log,
+    warn,
+  });
+  return { needed: true, saved: Boolean(result?.saved), chatId: result?.chatId ?? null, tested: Boolean(result?.tested) };
+}
+
+async function runInstall(args, p) {
   log(bold("omo-slim-plan installer"));
   log(cyan("Resolving paths..."));
   log(`  config root : ${p.configRoot}`);
@@ -474,7 +553,16 @@ function runInstall(args, p) {
   }
 
   if (args.dryRun) {
+    const dryCfg = readPlanflowJsonSafe(p.planflowPath) || buildPlanflowConfig(args, null);
+    const setupPreview = evaluateTelegramSetup(args, dryCfg);
     log("");
+    log(cyan("Telegram setup:"));
+    if (setupPreview.needed) {
+      log(`  [dry-run] would run interactive setup (${setupPreview.reason}) — message the bot, confirm chat_id`);
+      log(`  (interactive prompts require a TTY; not executed in dry-run)`);
+    } else {
+      log(`  skipped (${setupPreview.reason})`);
+    }
     log(green("Dry-run complete — nothing was written."));
     return 0;
   }
@@ -483,7 +571,26 @@ function runInstall(args, p) {
     log(green("Uninstall complete. Restart OpenCode to drop the plugin."));
     return 0;
   }
-  printNextSteps(p);
+
+  // --- 10: optional interactive Telegram first-run setup ---
+  const cfgNow = readPlanflowJsonSafe(p.planflowPath) || {};
+  const setupPlan = shouldRunTelegramSetup(args, p, cfgNow);
+  let setupState = null;
+  if (setupPlan.needed) {
+    log(cyan("Telegram setup:"));
+    log(`  reason: ${setupPlan.reason}`);
+    setupState = await runInteractiveTelegramSetup(args, p, setupPlan);
+  } else {
+    log(cyan("Telegram setup:"));
+    log(`  skipped (${setupPlan.reason})`);
+    const tg = cfgNow?.webhook?.telegram || {};
+    const provider = cfgNow?.webhook?.provider || "telegram";
+    if (provider === "telegram" && !String(tg.chatId || "").trim()) {
+      setupState = { needed: true, saved: false, chatId: null, tested: false };
+    }
+  }
+
+  printNextSteps(p, setupState);
   return 0;
 }
 
@@ -546,8 +653,14 @@ function main() {
   }
   try {
     const p = resolvePaths(args);
-    const code = runInstall(args, p);
-    process.exit(code);
+    runInstall(args, p)
+      .then((code) => {
+        process.exit(code);
+      })
+      .catch((e) => {
+        err(e?.message || String(e));
+        process.exit(1);
+      });
   } catch (e) {
     err(e?.message || String(e));
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omo-slim-plan",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight plan-first workflow for OpenCode + oh-my-opencode-slim: plan → human gate → start-work → acceptance",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
   "type": "module",
   "license": "MIT",
   "bin": { "omo-slim-plan": "bin/install.js" },
-  "files": ["bin", "templates", "plugin", "LICENSE", "README.md"],
+  "files": ["bin", "templates", "plugin", "LICENSE", "README.md", "CHANGELOG.md"],
   "engines": { "node": ">=18" },
   "keywords": ["opencode", "oh-my-opencode-slim", "plan", "workflow", "omo-slim"]
 }

package/plugin/planflow-notify.mjs

@@ -17,7 +17,8 @@ Usage:
   node planflow-notify.mjs --event <event> --plan <path> [options]
 
 Options:
-  --event <event>       plan-ready | awaiting-review | task-done | awaiting-acceptance | custom
+  --event <event>       plan-ready | awaiting-review | task-done | awaiting-acceptance | test | custom
+                          (note: --event test bypasses webhook.event filters — used by Telegram first-run setup)
   --plan <path>         plan file path (e.g. .plans/foo.md)
   --title <text>        optional notification title
   --message <text>      optional notification message
@@ -126,6 +127,7 @@ async function main() {
     return 0;
   }
 
+  // event "test" (Telegram setup) bypasses webhook.event filters in providers.send
   const result = await send(cfg, payload);
   const reason = result?.reason || "";
   const notConfigured = !result?.ok && /_not_configured$/.test(reason);

package/plugin/planflow-providers.mjs

@@ -283,7 +283,9 @@ export async function send(config, { event, plan, title, message, remaining, ses
     const p = payloadFor(cfg, { event, plan, title, message, remaining, session });
 
     const events = hook.events || {};
-    if (events[p.event] === false) {
+    // event "test" (Telegram first-run setup) always bypasses webhook.event filters —
+    // it must never be skipped so sendTestNotification() can verify the saved config.
+    if (p.event !== "test" && events[p.event] === false) {
       return { ok: true, skipped: true, provider: providerName };
     }
     if (!provider) {

package/plugin/planflow-telegram.mjs

@@ -0,0 +1,409 @@
+// omo-slim-plan — Telegram first-run setup helpers (zero deps, Node 18+ builtins only)
+// Used by bin/install.js for interactive chat_id capture. Never logs the full bot token.
+//
+// Exports:
+//   getMe(token) / getUpdates(token, offset) / sendMessage(token, chatId, text)
+//   waitForMessage(token, { timeoutMs, pollIntervalMs, onStatus })
+//   pickLatestMessage(resultArray)          — pure, testable
+//   maskToken(token)                        — safe display form
+//   promptConfirm(question) / promptLine(question) — readline/promises
+//   saveChatIdToConfig(planflowPath, token, chatId)
+//   runTelegramSetup({ token, planflowPath, log, warn }) — full interactive flow
+
+import { createInterface } from "node:readline/promises";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+
+const API_TIMEOUT_MS = 10_000;
+const DEFAULT_WAIT_MS = 120_000;
+const DEFAULT_POLL_MS = 2_000;
+
+function apiBase(token) {
+  return `https://api.telegram.org/bot${token}`;
+}
+
+/** Safe display form — never the full token. */
+export function maskToken(token) {
+  const t = String(token || "");
+  if (!t) return "(empty)";
+  if (t.length <= 8) return "***";
+  return `${t.slice(0, 6)}…${t.slice(-2)} (${t.length} chars)`;
+}
+
+/** Strip any accidental token leakage from error text. */
+function redact(text, token) {
+  if (!text || !token) return text;
+  return String(text).split(token).join("<redacted>");
+}
+
+function describeTelegramError(json, token) {
+  const desc = json?.description || "";
+  const code = json?.error_code;
+  const d = desc.toLowerCase();
+  let hint = "";
+  if (d.includes("unauthorized") || d.includes("not found") || d.includes("invalid")) {
+    hint = "invalid bot token — re-copy it from @BotFather (/token)";
+  } else if (d.includes("bot was blocked")) {
+    hint = "bot was blocked by the user — unblock the bot in Telegram";
+  } else if (d.includes("chat not found")) {
+    hint = "chat not found — message the bot first, then retry";
+  } else if (d.includes("bot can't initiate") || d.includes("bot can not initiate")) {
+    hint = "bot cannot start the chat — open the bot and send /start";
+  }
+  const safe = redact(desc, token);
+  return `telegram error ${code ?? ""}: ${safe}${hint ? ` (${hint})` : ""}`.replace(/\s+$/, "");
+}
+
+/**
+ * Pure: pick the latest update entry that carries a chat.
+ * Accepts the raw `result` array from getUpdates (message / channel_post / edited_*).
+ */
+export function pickLatestMessage(resultArray) {
+  if (!Array.isArray(resultArray) || resultArray.length === 0) return null;
+  let best = null;
+  let bestId = -Infinity;
+  for (const item of resultArray) {
+    if (!item || typeof item !== "object") continue;
+    const candidates = [item.message, item.channel_post, item.edited_message, item.edited_channel_post];
+    for (const m of candidates) {
+      if (!m || typeof m !== "object" || !m.chat) continue;
+      const uid = Number.isFinite(item.update_id) ? item.update_id : 0;
+      if (uid >= bestId) {
+        bestId = uid;
+        best = m;
+      }
+    }
+  }
+  return best;
+}
+
+async function telegramGet(token, method, params) {
+  const url = new URL(`${apiBase(token)}/${method}`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
+  }
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), API_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { method: "GET", signal: ctrl.signal });
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+      /* non-JSON */
+    }
+    if (!json) return { ok: false, error: `HTTP ${res.status} (non-JSON response)`, token };
+    if (json.ok === false) {
+      return {
+        ok: false,
+        error: describeTelegramError(json, token),
+        error_code: json.error_code,
+        description: redact(json.description, token),
+        token,
+      };
+    }
+    return { ok: true, data: json.result, raw: json };
+  } catch (e) {
+    const aborted = e?.name === "AbortError" || e?.name === "TimeoutError";
+    return { ok: false, error: aborted ? "timeout" : e?.message || String(e), token };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function getMe(token) {
+  return telegramGet(token, "getMe");
+}
+
+export async function getUpdates(token, offset) {
+  const params = { timeout: 0 };
+  if (offset !== undefined && offset !== null && offset !== "") {
+    params.offset = String(offset);
+  }
+  return telegramGet(token, "getUpdates", params);
+}
+
+export async function sendMessage(token, chatId, text) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), API_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${apiBase(token)}/sendMessage`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ chat_id: chatId, text }),
+      signal: ctrl.signal,
+    });
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+      /* non-JSON */
+    }
+    if (json && json.ok === false) return { ok: false, error: describeTelegramError(json, token) };
+    if (!json) return { ok: false, error: `HTTP ${res.status}` };
+    return { ok: true, data: json.result };
+  } catch (e) {
+    return {
+      ok: false,
+      error: e?.name === "AbortError" || e?.name === "TimeoutError" ? "timeout" : e?.message || String(e),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Poll getUpdates until a message with a chat arrives.
+ * onStatus({ elapsedMs, timeoutMs }) is called each poll (installer prints progress).
+ * Supports Ctrl+C cleanly via process SIGINT handler set by runTelegramSetup.
+ */
+export async function waitForMessage(token, { timeoutMs = DEFAULT_WAIT_MS, pollIntervalMs = DEFAULT_POLL_MS, onStatus } = {}) {
+  const started = Date.now();
+  let offset; // undefined → read backlog first, then advance past seen updates
+  let lastStatusLog = 0;
+  const isTTY = Boolean(process.stdout.isTTY);
+
+  while (true) {
+    const elapsed = Date.now() - started;
+    const remaining = timeoutMs - elapsed;
+    if (remaining <= 0) {
+      return { ok: false, reason: "timeout", elapsedMs: elapsed };
+    }
+
+    if (typeof onStatus === "function") {
+      try {
+        onStatus({ elapsedMs: elapsed, timeoutMs });
+      } catch {
+        /* ignore */
+      }
+    } else if (isTTY) {
+      process.stdout.write(`\r  polling getUpdates… ${Math.round(elapsed / 1000)}s / ${Math.round(timeoutMs / 1000)}s   `);
+    } else if (elapsed - lastStatusLog >= 10_000) {
+      lastStatusLog = elapsed;
+      process.stdout.write(`polling getUpdates… ${Math.round(elapsed / 1000)}s / ${Math.round(timeoutMs / 1000)}s\n`);
+    }
+
+    const res = await getUpdates(token, offset);
+    if (!res.ok) {
+      const errText = String(res.error || "");
+      const hard = /unauthorized|not found|bot can't|invalid/i.test(errText);
+      if (hard) {
+        return { ok: false, reason: "api_error", error: errText, elapsedMs: Date.now() - started };
+      }
+      // transient network error → retry until timeout
+    } else if (Array.isArray(res.data) && res.data.length > 0) {
+      const msg = pickLatestMessage(res.data);
+      const last = res.data[res.data.length - 1];
+      if (last && Number.isFinite(last.update_id)) offset = last.update_id + 1;
+      if (msg) {
+        return { ok: true, message: msg, offset };
+      }
+      // updates without a chat (e.g. inline queries) — already advanced offset
+    }
+
+    await sleep(Math.max(200, Math.min(pollIntervalMs, remaining)));
+  }
+}
+
+export function promptConfirm(question) {
+  return promptLine(question);
+}
+
+export function promptLine(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return rl
+    .question(question)
+    .then((ans) => {
+      rl.close();
+      return ans;
+    })
+    .catch((e) => {
+      rl.close();
+      throw e;
+    });
+}
+
+function formatCaptured(msg) {
+  const chat = msg?.chat || {};
+  const from = msg?.from || {};
+  const name = from.first_name
+    ? [from.first_name, from.last_name].filter(Boolean).join(" ")
+    : "";
+  const handle = from.username ? ` (@${from.username})` : "";
+  const text = msg?.text ?? msg?.caption ?? "";
+  return [
+    "捕获到消息:",
+    `  chat_id   : ${chat.id ?? "(none)"}`,
+    `  chat_type : ${chat.type ?? "(unknown)"}`,
+    `  from      : ${name || "(unknown)"}${handle}`,
+    `  text      : ${text === "" ? "(empty)" : text}`,
+  ].join("\n");
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Persist botToken + chatId into planflow.json (creates shape if missing). */
+export function saveChatIdToConfig(planflowPath, token, chatId) {
+  const cfg = readJsonSafe(planflowPath) || {};
+  if (!cfg.webhook || typeof cfg.webhook !== "object") cfg.webhook = {};
+  if (!cfg.webhook.telegram || typeof cfg.webhook.telegram !== "object") cfg.webhook.telegram = {};
+  if (token) cfg.webhook.telegram.botToken = token;
+  cfg.webhook.telegram.chatId = String(chatId);
+  cfg.webhook.provider = "telegram";
+  if (cfg.version === undefined) cfg.version = 1;
+  if (cfg.plansDir === undefined) cfg.plansDir = ".plans";
+  mkdirSync(path.dirname(planflowPath), { recursive: true });
+  writeFileSync(planflowPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+  return cfg;
+}
+
+/**
+ * Send a test notification through the normal provider path (event "test").
+ * Lives here so installer and notify CLI share one implementation; providers.mjs
+ * special-cases event==="test" to bypass event filters.
+ */
+export async function sendTestNotification(planflowPath, { log = console.log, warn = console.warn } = {}) {
+  try {
+    // This module sits next to planflow-providers.mjs after install and in the package.
+    const providers = await import("./planflow-providers.mjs");
+    const cfg = providers.loadConfig(planflowPath, process.cwd());
+    const result = await providers.send(cfg, {
+      event: "test",
+      plan: "setup",
+      title: "omo-slim-plan",
+      message: "Telegram 配置成功",
+    });
+    if (result?.ok) {
+      log("Test notification sent ✓ — check your Telegram.");
+      return { ok: true, result };
+    }
+    if (result?.skipped) {
+      warn("test event was skipped (unexpected) — check webhook.events in planflow.json");
+      return { ok: false, result };
+    }
+    warn(`test notification failed: ${result?.reason || result?.error || "unknown"}`);
+    return { ok: false, result };
+  } catch (e) {
+    warn(`test notification error: ${e?.message || e}`);
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+
+/**
+ * Full interactive Telegram first-run setup.
+ * Returns { saved, chatId, token, tested }.
+ */
+export async function runTelegramSetup({
+  token,
+  planflowPath,
+  log = console.log,
+  warn = console.warn,
+} = {}) {
+  log("");
+  log("=== Telegram first-run setup ===");
+
+  // Ctrl+C → clean exit, no stack trace
+  const onSigint = () => {
+    process.stdout.write("\n");
+    log("Cancelled. Re-run setup anytime: npx omo-slim-plan --setup-telegram");
+    process.exit(130);
+  };
+  process.on("SIGINT", onSigint);
+
+  try {
+    // 1. Token: flag/config value, or prompt
+    let tok = String(token || "").trim();
+    if (!tok) {
+      const ans = (await promptLine("Bot token from @BotFather (stored only in planflow.json): ")).trim();
+      tok = ans;
+    }
+    if (!tok) {
+      log("No token provided — skipping Telegram setup.");
+      log("Re-run: npx omo-slim-plan --setup-telegram   (or pass --telegram-token)");
+      return { saved: false, chatId: null, token: null, tested: false };
+    }
+    log(`  token: ${maskToken(tok)}`);
+
+    // 2. getMe → bot identity + open hint
+    const me = await getMe(tok);
+    if (!me.ok) {
+      log(`getMe failed: ${me.error}`);
+      log("Check the token (@BotFather → /token) and that the bot is not blocked.");
+      return { saved: false, chatId: null, token: tok, tested: false };
+    }
+    const username = me.data?.username ? `@${me.data.username}` : "(no username)";
+    log(`  bot: ${username}${me.data?.first_name ? ` (${me.data.first_name})` : ""}`);
+    log("");
+    log("Please message this bot in Telegram now (any text, e.g. /start or hi).");
+    log("Waiting for your message… (timeout 120s, Ctrl+C to cancel)");
+
+    // 3. Poll getUpdates with status
+    const waitRes = await waitForMessage(tok, {
+      timeoutMs: DEFAULT_WAIT_MS,
+      pollIntervalMs: DEFAULT_POLL_MS,
+      onStatus: ({ elapsedMs }) => {
+        const total = Math.round(DEFAULT_WAIT_MS / 1000);
+        const cur = Math.round(elapsedMs / 1000);
+        if (process.stdout.isTTY) {
+          process.stdout.write(`\r  polling getUpdates… ${cur}s / ${total}s   `);
+        } else if (elapsedMs % 10_000 < DEFAULT_POLL_MS) {
+          process.stdout.write(`polling getUpdates… ${cur}s / ${total}s\n`);
+        }
+      },
+    });
+    if (process.stdout.isTTY) process.stdout.write("\n");
+
+    if (!waitRes.ok) {
+      if (waitRes.reason === "timeout") {
+        log("Timed out waiting for a message. Make sure you actually messaged the bot, then retry:");
+        log("  npx omo-slim-plan --setup-telegram");
+      } else {
+        log(`getUpdates failed: ${waitRes.error}`);
+      }
+      return { saved: false, chatId: null, token: tok, tested: false };
+    }
+
+    const msg = waitRes.message;
+    const chatId = msg?.chat?.id;
+
+    // 4. Confirm capture
+    log("");
+    log(formatCaptured(msg));
+    log("");
+    const ans = (await promptConfirm("是否将此 chat_id 保存到 planflow.json? [Y/n] "))
+      .trim()
+      .toLowerCase();
+    if (ans === "n" || ans === "no") {
+      log("Discarded — chatId left empty. Re-run setup when ready.");
+      return { saved: false, chatId: null, token: tok, tested: false };
+    }
+
+    // 5. Save + optionally acknowledge updates with offset
+    saveChatIdToConfig(planflowPath, tok, String(chatId));
+    log(`Saved chatId ${chatId} → ${planflowPath}`);
+    if (waitRes.offset !== undefined && waitRes.offset !== null) {
+      // Best-effort acknowledge so the captured message is not re-offered later
+      try {
+        await getUpdates(tok, waitRes.offset);
+      } catch {
+        /* ignore */
+      }
+    }
+
+    // 6. Test notification through providers (event "test" bypasses filters)
+    const test = await sendTestNotification(planflowPath, { log, warn });
+    return { saved: true, chatId: String(chatId), token: tok, tested: Boolean(test?.ok) };
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}

package/templates/command/plan.md

@@ -43,6 +43,8 @@ description: Explore the request and write a decision-complete plan to .plans/<s
 
    - 若 notify 脚本不在该路径，用实际安装路径（`<configRoot>/plugin/planflow-notify.mjs`）。
    - 若未安装 omo-slim-plan 或未配置 webhook：跳过通知，继续第 7 步。
+   - 若 provider=telegram 且 chatId 为空：提示用户运行 `npx omo-slim-plan --setup-telegram`（首次只需 bot token，chat_id 交互捕获）。
+   - 若 provider=telegram 且 chatId 为空：提示用户运行 `npx omo-slim-plan --setup-telegram`（首次只需 bot token，chat_id 交互捕获）。
 
 7. **停在人工门禁**：用 question 工具向人类提供选项（一次只问这一题）：
    - `start-work <slug>` — 按计划开始执行

package/templates/skills/plan-workflow/SKILL.md

@@ -104,6 +104,8 @@ node ~/.config/opencode/plugin/planflow-notify.mjs \
 
 - **notify 失败或 provider 未配置：继续工作流，绝不阻塞**。
 - 也可直接编辑 `~/.config/opencode/planflow.json` 配置 Telegram / generic webhook / command provider。
+- Telegram 首次配置：只需 bot token；chat_id 由用户给 bot 发消息后交互捕获——提示运行 `npx omo-slim-plan --setup-telegram`。chatId 为空时通知会报 `telegram_not_configured`。
+- Telegram 首次配置：只需 bot token；chat_id 由用户给 bot 发消息后交互捕获——提示运行 `npx omo-slim-plan --setup-telegram`。chatId 为空时通知会报 `telegram_not_configured`。
 
 ## Delegation（委派）