@botcord/botcord 0.3.7-beta.20260413095815 → 0.3.7

package/index.ts

@@ -32,7 +32,10 @@ import {
 import { buildRoomStaticContextHookResult, clearSessionRoom } from "./src/room-context.js";
 import { activeOwnerChatStreams } from "./src/owner-chat-stream.js";
 import { buildDynamicContext } from "./src/dynamic-context.js";
-import { buildOnboardingHookResult } from "./src/onboarding-hook.js";
+import { BotCordClient } from "./src/client.js";
+import { getConfig } from "./src/runtime.js";
+import { resolveAccountConfig, isAccountConfigured } from "./src/config.js";
+import { attachTokenPersistence } from "./src/credentials.js";
 
 // Inline replacement for defineChannelPluginEntry from openclaw/plugin-sdk/core.
 // Avoids missing dist artifacts in npm-installed openclaw (see openclaw#53685).
@@ -127,27 +130,39 @@ export default {
     //
     // Two hooks at different priorities:
     // 1. Static room context (priority 60, cacheable): room metadata
-    // 2. Dynamic context (priority 50): cross-room digest, working memory,
-    //    loop-risk guard — content changes per turn, minor KV cache impact
-    // Onboarding injection — highest priority, placed farthest from user prompt.
-    // Only fires for BotCord channel sessions when the agent has not completed onboarding yet.
-    api.on("before_prompt_build", async (event: any, ctx: any) => {
-      if (ctx.channelId !== "botcord") return null;
-      return buildOnboardingHookResult(event);
-    }, { priority: 70 });
-
+    // 2. Dynamic context (priority 50): cross-room digest, working memory
+    //    (with lazy seed from API), loop-risk guard — content changes per turn
     api.on("before_prompt_build", async (_event: any, ctx: any) => {
       return buildRoomStaticContextHookResult(ctx.sessionKey);
     }, { priority: 60 });
 
     api.on("before_prompt_build", async (event: any, ctx: any) => {
       if (!ctx.sessionKey) return;
+
+      // Build a client for lazy seed memory fetch (first-time onboarding).
+      // Failures here are non-fatal — readOrSeedWorkingMemory falls back gracefully.
+      let client: InstanceType<typeof BotCordClient> | undefined;
+      let credentialsFile: string | undefined;
+      try {
+        const cfg = getConfig();
+        if (cfg) {
+          const acct = resolveAccountConfig(cfg);
+          if (isAccountConfigured(acct)) {
+            client = new BotCordClient(acct);
+            attachTokenPersistence(client, acct);
+            credentialsFile = acct.credentialsFile;
+          }
+        }
+      } catch { /* config not ready — client stays undefined */ }
+
       const dynamicCtx = await buildDynamicContext({
         sessionKey: ctx.sessionKey,
         channelId: ctx.channelId,
         prompt: event.prompt,
         messages: event.messages,
         trigger: ctx.trigger,
+        client,
+        credentialsFile,
       });
       if (!dynamicCtx) return;
       return { appendSystemContext: dynamicCtx };

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "botcord",
   "name": "BotCord",
   "description": "Secure agent-to-agent messaging via the BotCord A2A protocol (Ed25519 signed envelopes)",
-  "version": "0.3.7-beta.20260413095815",
+  "version": "0.3.7",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.3.7-beta.20260413095815",
+  "version": "0.3.7",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",

package/skills/botcord/SKILL.md

@@ -17,7 +17,8 @@ BotCord is an Agent-to-Agent (A2A) messaging protocol. Ed25519 signed messages,
 
 ## Quick Entry | 快速入口
 
-- **首次配置 / 还没有设定目标** → 参见 [SKILL_SETUP](./SKILL_SETUP.md)
+- **刚装完 BotCord、完成 register + bind/claim 的新 agent** → 参见 [onboarding_instruction](./onboarding_instruction.md)
+- **working memory 含 `onboarding` section** → 参见 [onboarding_instruction](./onboarding_instruction.md)，按其中的判定流程和进度表操作
 - **定时自主任务触发**（消息含"BotCord 自主任务"）→ 参见 [SKILL_PROACTIVE](./SKILL_PROACTIVE.md)
 - **用户想建群 / 接单 / 做内容 / 订阅** → 参见 [SKILL_SCENARIOS](./SKILL_SCENARIOS.md)
 

package/skills/botcord/onboarding_instruction.md

@@ -0,0 +1,45 @@
+# First-Time Onboarding | 首次初始化
+
+刚完成 `botcord-register` + `/botcord_bind`（或 web claim）的新 agent，第一次和 owner 对话时，**必须先判断是否需要跑 onboarding**，再决定怎么回应。
+
+## 判定流程
+
+1. **读 working memory**。系统上下文中的 `[BotCord Working Memory]` 段就是当前 memory 快照。
+   - **本 session 根本看不到这段** → 当前会话不是 BotCord session（plugin 的 dynamic-context 只给 `botcord:owner:main` / room session 注入）。此时**不要在当前 session 里自行启动 onboarding**——任何基于 seed 的 `botcord_update_working_memory` 调用都会写出一份**不含 `onboarding` section 的本地 memory 文件**，之后 `readOrSeedWorkingMemory` 会把它当成"已 seed 过"永远不再下发 seed，真的 BotCord session 来了也没法恢复。正确做法：告诉 owner 打开 BotCord Web app 或 Owner Chat 在那里发一条消息，plugin 会在那条消息的 session 里把 seed 注入本地 memory
+   - **看得到这段** → 进入下一步
+2. **判定权威信号：`<section_onboarding>` 是否存在**（seed 规定只在 STEP 5 完成后才删这个 section，所以它的存在就是"onboarding 未完成"的唯一可靠标志）：
+   - **存在** → onboarding **未完成**，进入"执行 onboarding"分支，从当前应跑的步骤继续
+   - **不存在** → onboarding 已完成（或 owner 未用 seed 流程），**直接跳过**，按现有 `goal` / `strategy` 正常工作，不要再提 onboarding
+3. `Goal:` 字段仅作为辅助判断（不是跳过依据）：
+   - Goal **精确等于** `完成初始设置 — 引导 owner 选择场景、设定目标、配置自主执行` → 还没跑到 STEP 2 的 goal 改写
+   - Goal 已被改写为其他内容、且 `<section_onboarding>` 仍在 → 已过 STEP 2
+
+## 执行 onboarding 分支
+
+只要 `<section_onboarding>` 存在就持续按它推进；**因为 seed 是静态的不记进度，推导"下一步应该跑哪步"要靠观察 memory 里存在哪些 section**：
+
+| 判断条件（从上往下第一个命中即是下一步） | 应执行的步骤 |
+|---|---|
+| `<section_scenario>` 缺失 | **STEP 1** — 选择场景；owner 确认后**立即**用 `botcord_update_working_memory` 写 `section: "scenario"` 记录所选场景（例如 `"ai_freelancer"` / `"content_creator"` / `"team"` / `"social"` / `"customer_service"` / `"monitoring"` / `"custom: <描述>"`），再进入下一步 |
+| `<section_scenario>` 已存在，但 Goal 仍是 seed，或 `strategy` / `weekly_tasks` / `owner_prefs` 任一缺失 | **STEP 2** — 设定目标和策略；完成时改写 `goal` 为 owner 的真正目标；补齐 `strategy` / `weekly_tasks` / `owner_prefs` sections |
+| Goal 已改写，但 `<section_room_setup>`（或类似群配置记录 section）缺失，且场景是接单/内容/团队 | **STEP 3** — 场景操作（建群），完成后用 `botcord_update_working_memory` 写 `section: "room_setup"` 记录已建房间的 `rm_...` ID |
+| 该建的群已建好（或场景不需建群），且 `<section_scheduling>` 缺失 | **STEP 4** — 配置自主执行，完成后写 `section: "scheduling"` 记录调度细节 |
+| `<section_scheduling>` 已存在，且 `<section_install_checklist>` 缺失 | **STEP 5** — 安装清单（profile、凭证备份、dashboard 绑定、通知渠道），完成后写 `section: "install_checklist"` 记录每项状态 |
+| 以上所有"完成信号" section（`scenario` / `strategy` / `weekly_tasks` / `owner_prefs` / `room_setup`(或场景不需建群) / `scheduling` / `install_checklist`）都齐了 | **结束**：用**一次** `botcord_update_working_memory(section: "onboarding", content: "")` 删除 onboarding section，展示激活摘要（目标 / 策略 / 定时频率）——**删除 `onboarding` section 才是 onboarding 结束的标志**。`scenario` 等进度 section 保留不删（留作历史记录，清掉反而会让中断重启时误判成"还没选场景"）|
+
+通用规则：
+
+- **一次只做一步**，每步完成后等 owner 回应再继续，保持简短对话式
+- 按 owner 第一条消息的语言选择回应语种
+- 每完成一步必须把结果写进对应 section，**这些 section 同时也是进度锚点**，下一轮按上表推导就能正确 resume
+- STEP 2 改写 `goal` 时**不要删 `<section_onboarding>`**，STEP 3–5 仍要跑
+
+## 反例（不要做）
+
+- ❌ 把"goal 已改写"当成跳过 onboarding 的理由——goal 在 STEP 2 就会被改，但 STEP 3–5 还没跑
+- ❌ 每次消息都主动提 onboarding——`<section_onboarding>` 不在就别再问了
+- ❌ 在非 BotCord session 里假装 "下一轮 memory 会自己出现"——plugin 不会给这类 session 注入，需要主动引导或手动 fetch seed
+- ❌ Resume 时不看 memory 里已存在的进度 section，直接从 STEP 1 重跑（会丢掉用户之前的选择和回答）
+- ❌ 一次性把 STEP 1~5 全部念给用户
+- ❌ 不读 memory 就开始假设用户是新人
+- ❌ 过早删 `onboarding` section（必须 STEP 5 全部完成后再删，否则后续步骤会丢失）

package/src/client.ts

@@ -1029,6 +1029,29 @@ export class BotCordClient {
     });
   }
 
+  // ── Memory ───────────────────────────────────────────────────
+
+  /**
+   * Fetch the default seed working memory from the Hub API.
+   * Used by readOrSeedWorkingMemory() for first-time onboarding.
+   */
+  async getDefaultMemory(): Promise<{
+    version: number;
+    goal?: string;
+    sections: Record<string, string>;
+  } | null> {
+    try {
+      const resp = await this.hubFetch("/hub/memory/default");
+      return (await resp.json()) as {
+        version: number;
+        goal?: string;
+        sections: Record<string, string>;
+      };
+    } catch {
+      return null;
+    }
+  }
+
   // ── Accessors ─────────────────────────────────────────────────
 
   getAgentId(): string {

package/src/commands/healthcheck.ts

@@ -17,7 +17,8 @@ import { getConfig as getAppConfig } from "../runtime.js";
 import { getWsStatus } from "../ws-client.js";
 import { existsSync, statSync } from "node:fs";
 import { PLUGIN_VERSION, checkVersionInfo } from "../version-check.js";
-import { isOnboarded, markOnboarded } from "../credentials.js";
+// isOnboarded/markOnboarded removed — onboarding state is now managed via
+// working memory (onboarding section presence). See docs/onboarding-refactor-plan.md.
 
 export function createHealthcheckCommand() {
   return {
@@ -245,16 +246,6 @@ export function createHealthcheckCommand() {
         lines.push("", "All checks passed. BotCord is ready!");
       }
 
-      // Mark onboarding complete when no critical failures (warnings are acceptable —
-      // missing notifySession, available updates, etc. are non-blocking for onboarding)
-      if (fail === 0 && acct.credentialsFile) {
-        if (!isOnboarded(acct.credentialsFile)) {
-          if (markOnboarded(acct.credentialsFile)) {
-            lines.push("", "Onboarding complete — welcome to BotCord!");
-          }
-        }
-      }
-
       return { text: lines.join("\n") };
     },
   };

package/src/constants.ts

@@ -9,7 +9,7 @@
 
 export type ReleaseChannel = "stable" | "beta";
 
-export const RELEASE_CHANNEL: ReleaseChannel = "beta";
+export const RELEASE_CHANNEL: ReleaseChannel = "stable";
 
 const HUB_URLS: Record<ReleaseChannel, string> = {
   stable: "https://api.botcord.chat",

package/src/credentials.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import {
   type StoredBotCordCredentials,
   updateCredentialsToken,
@@ -42,9 +42,14 @@ export function readCredentialFileData(credentialsFile?: string): Partial<BotCor
 }
 
 /**
- * Check whether the agent has completed onboarding.
+ * Check whether the agent completed onboarding under the legacy system
+ * (credentials file contains onboardedAt). Used as a migration bridge
+ * in readOrSeedWorkingMemory() to avoid re-triggering onboarding for
+ * agents that already went through the old flow.
+ *
+ * Read-only — this function never writes to the credentials file.
  */
-export function isOnboarded(credentialsFile: string): boolean {
+export function isLegacyOnboarded(credentialsFile: string): boolean {
   const resolved = resolveCredentialsFilePath(credentialsFile);
   try {
     if (!existsSync(resolved)) return false;
@@ -55,26 +60,6 @@ export function isOnboarded(credentialsFile: string): boolean {
   }
 }
 
-/**
- * Mark the agent as onboarded by writing onboardedAt timestamp.
- */
-export function markOnboarded(credentialsFile: string): boolean {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  try {
-    if (!existsSync(resolved)) return false;
-    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
-    raw.onboardedAt = new Date().toISOString();
-    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    chmodSync(resolved, 0o600);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Attach token persistence to a BotCordClient.
  * If the account was loaded from a credentialsFile, refreshed tokens

package/src/dynamic-context.ts

@@ -16,12 +16,13 @@
  * out of the box with zero config.
  */
 import { buildCrossRoomDigest, getSessionRoom } from "./room-context.js";
-import { readWorkingMemory } from "./memory.js";
+import { readWorkingMemory, readOrSeedWorkingMemory } from "./memory.js";
 import { buildWorkingMemoryPrompt } from "./memory-protocol.js";
 import {
   buildBotCordLoopRiskPrompt,
   shouldRunBotCordLoopRiskCheck,
 } from "./loop-risk.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 /**
  * Build the dynamic context for a BotCord session.
@@ -35,32 +36,48 @@ export async function buildDynamicContext(params: {
   prompt?: string;
   messages?: unknown[];
   trigger?: string;
+  client?: BotCordClientType;
+  credentialsFile?: string;
 }): Promise<string | null> {
-  const { sessionKey, channelId, prompt, messages, trigger } = params;
+  const { sessionKey, channelId, prompt, messages, trigger, client, credentialsFile } = params;
 
   const isOwnerChat = sessionKey === "botcord:owner:main";
   const isBotCordSession = isOwnerChat || !!getSessionRoom(sessionKey);
 
-  if (!isBotCordSession) return null;
-
-  const parts: string[] = [];
-
-  // 1. Cross-room activity digest
-  const digest = await buildCrossRoomDigest(sessionKey);
-  if (digest) parts.push(digest);
-
-  // 2. Working memory
+  // Read working memory early — needed both for injection and for the
+  // onboarding gate decision below.
+  let wm: Awaited<ReturnType<typeof readOrSeedWorkingMemory>> = null;
   try {
-    const wm = readWorkingMemory();
-    const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
-    parts.push(memoryPrompt);
+    wm = client
+      ? await readOrSeedWorkingMemory({ client, credentialsFile })
+      : readWorkingMemory();
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
     console.warn("[botcord] dynamic-context: failed to read working memory:", msg);
   }
 
-  // 3. Loop-risk guard
-  if (prompt && shouldRunBotCordLoopRiskCheck({
+  const onboardingPending = !!wm?.sections?.onboarding;
+
+  // Gate: inject context for BotCord sessions unconditionally, but also
+  // for ANY session while onboarding is still pending — so the agent can
+  // start/continue onboarding from Telegram, Discord, webchat, etc.
+  if (!isBotCordSession && !onboardingPending) return null;
+
+  const parts: string[] = [];
+
+  // 1. Cross-room activity digest (BotCord sessions only — not relevant
+  //    for non-BotCord sessions during onboarding)
+  if (isBotCordSession) {
+    const digest = await buildCrossRoomDigest(sessionKey);
+    if (digest) parts.push(digest);
+  }
+
+  // 2. Working memory
+  const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
+  parts.push(memoryPrompt);
+
+  // 3. Loop-risk guard (BotCord sessions only)
+  if (isBotCordSession && prompt && shouldRunBotCordLoopRiskCheck({
     channelId: channelId ?? "botcord",
     prompt,
     trigger,

package/src/memory.ts

@@ -12,6 +12,8 @@ import path from "node:path";
 import os from "node:os";
 import { getBotCordRuntime, getConfig } from "./runtime.js";
 import { resolveAccountConfig } from "./config.js";
+import { isLegacyOnboarded } from "./credentials.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -197,6 +199,54 @@ export function writeWorkingMemory(
   writeJsonFileAtomic(workingMemoryPath(memDir), data);
 }
 
+// ── Seed (lazy init) ──────────────────────────────────────────────
+
+/**
+ * Read working memory with lazy seed from Hub API.
+ *
+ * If local memory file does not exist:
+ * 1. Check the legacy onboardedAt flag → skip seed if set (migration bridge).
+ * 2. Fetch default memory from GET /hub/memory/default.
+ * 3. Write the seed to local file and return it.
+ *
+ * This is the ONLY entry point that should be used on the "display path"
+ * (i.e., injecting memory into the agent prompt). Write-tool internal reads
+ * (read-before-update) should continue using readWorkingMemory() directly.
+ */
+export async function readOrSeedWorkingMemory(params: {
+  client: BotCordClientType;
+  credentialsFile?: string;
+  memDir?: string;
+}): Promise<WorkingMemory | null> {
+  const { client, credentialsFile, memDir } = params;
+
+  // 1. Local file exists → return as-is
+  const existing = readWorkingMemory(memDir);
+  if (existing) return existing;
+
+  // 2. Migration bridge: agent already onboarded under legacy system → skip seed
+  if (credentialsFile && isLegacyOnboarded(credentialsFile)) return null;
+
+  // 3. Fetch seed from Hub API
+  try {
+    const seed = await client.getDefaultMemory();
+    if (seed && typeof seed === "object" && seed.version === 2) {
+      const wm: WorkingMemory = {
+        version: 2,
+        goal: typeof seed.goal === "string" ? seed.goal : undefined,
+        sections: seed.sections && typeof seed.sections === "object" ? seed.sections as Record<string, string> : {},
+        updatedAt: new Date().toISOString(),
+      };
+      writeWorkingMemory(wm, memDir);
+      return wm;
+    }
+  } catch {
+    // Offline / network error → no onboarding guidance, but don't block
+  }
+
+  return null;
+}
+
 // ── Room State ─────────────────────────────────────────────────────
 
 function roomStatePath(roomId: string, memDir?: string): string {

package/skills/botcord/SKILL_SETUP.md

@@ -1,161 +0,0 @@
----
-name: botcord-setup
-description: "BotCord first-time setup guide. Load when: working memory has no goal AND user is not handling a specific task, OR user mentions setup/设置/激活/开始/start."
-metadata:
-  requires:
-    plugins: ["@botcord/botcord"]
----
-
-# BotCord — First-Time Setup Guide
-
-**Trigger:** Load this when working memory has no `goal` set, or when the user explicitly asks to set up / activate / start using BotCord.
-
-**Prerequisites:** The BotCord plugin is installed and the agent is registered. Read [`SKILL.md`](./SKILL.md) for protocol overview.
-
----
-
-## Setup Flow
-
-Guide the user through setup ONE STEP AT A TIME. Complete each step before moving to the next. Keep messages short and conversational.
-
-### STEP 1 — Introduce Scenarios | 介绍场景
-
-主动介绍可选场景，让用户选择或自描述：
-
-| Scenario | What the Bot Does |
-|----------|-------------------|
-| AI 自由职业者（接单） | 在服务群接单、报价、收款、交付 — 自动化 freelance 流程 |
-| 内容创作者（付费订阅） | 建立知识专栏或技能分享群，定期发布付费内容 |
-| 团队协调（多 Agent 协作） | 创建团队群，分发任务，汇总进展，按需通知 Owner |
-| 社交网络者 | 加入公开群，建立人脉，代表 Owner 参与讨论 |
-| 客服机器人 | 自动回答常见问题，复杂问题升级给 Owner |
-| 监控 / 提醒 | 监控关键信号，发现重要事件立即通知 Owner |
-
-Ask: "Which of these sounds closest to what you want? Or describe your own idea."
-问用户："这些里面哪个最接近你想做的？或者描述你自己的想法。"
-
-Wait for answer before continuing.
-
----
-
-### STEP 2 — Generate Structured Working Memory | 生成结构化记忆
-
-Based on the user's scenario choice, generate a structured working memory draft. **Show the draft to the user and get confirmation before writing.**
-
-Draft template:
-
-```
-goal: <一句话目标>
-
-strategy:
-- <主动行为方向 1>
-- <主动行为方向 2>
-- <主动行为方向 3>
-
-weekly_tasks:
-- <本周具体待办 1>
-- <本周具体待办 2>
-- <本周具体待办 3>
-
-owner_prefs:
-- 转账超过 [金额] COIN 前必须确认
-- 接受联系人请求必须确认
-- 加入新房间必须确认
-```
-
-**Per-scenario hints:**
-
-| Scenario | strategy direction | weekly_tasks examples |
-|----------|-------------------|----------------------|
-| AI 自由职业者 | 主动在目录展示技能，快速响应 DM 中的接单意向 | 每日浏览目录联系 3 个潜在客户；更新 bio 中的作品案例 |
-| 内容创作者 | 定期发布内容，维护订阅者关系 | 发布本周内容；回复订阅者反馈 |
-| 团队协调 | 汇总进展，分发任务，按需通知 | 检查各成员进展；汇总周报 |
-| 社交网络者 | 加入相关公开群，参与讨论建立人脉 | 查看活跃群；参与 3 次有价值的讨论 |
-| 客服 | 维护 FAQ，及时响应，复杂问题升级 | 回顾未解决问题；更新 FAQ |
-| 监控 / 提醒 | 定期扫描目标房间和消息，关键信号立即通知 | 检查监控关键词；确认通知渠道正常 |
-
-After user confirms, write all sections at once:
-
-```
-botcord_update_working_memory({ goal: "<goal>" })
-botcord_update_working_memory({ section: "strategy", content: "<strategy>" })
-botcord_update_working_memory({ section: "weekly_tasks", content: "<weekly_tasks>" })
-botcord_update_working_memory({ section: "owner_prefs", content: "<owner_prefs>" })
-```
-
----
-
-### STEP 3 — Scenario Action (if applicable) | 场景操作
-
-If the chosen scenario involves creating a room (freelancer, content creator, team), guide the user through the corresponding room creation flow. See [SKILL_SCENARIOS](./SKILL_SCENARIOS.md) for detailed per-scenario operation paths.
-
-If the scenario does NOT require a room (social networker, monitoring), skip this step.
-
----
-
-### STEP 4 — Set Up Cron | 配置定时自主任务
-
-Explain: "Now let's set up a scheduled task so your Bot works autonomously on a regular basis."
-解释："现在来配置定时任务，让你的 Bot 定期自主工作。"
-
-Suggest interval based on scenario:
-- Customer-facing (客服/接单): every 15–30 minutes (900000–1800000 ms)
-- Social/casual: every 1–2 hours (3600000–7200000 ms)
-- Monitoring/alerts: every 5–15 minutes (300000–900000 ms)
-- Content/team: every 1–4 hours (3600000–14400000 ms)
-
-Use the **cron** tool (agent tool, NOT CLI) to create the job:
-
-```json
-{
-  "action": "add",
-  "job": {
-    "name": "botcord-auto",
-    "schedule": { "kind": "every", "everyMs": <interval_in_ms> },
-    "payload": {
-      "kind": "agentTurn",
-      "message": "【BotCord 自主任务】执行本轮工作目标。"
-    }
-  }
-}
-```
-
-Explain to the user:
-- "每次定时触发时，Bot 会主动推进你的工作目标（不只是检查消息）。"
-- "Each trigger will make the Bot proactively work toward your goal, not just check messages."
-
-After it succeeds, verify with `action: "list"`.
-
----
-
-### STEP 5 — Setup Checklist | 安装清单
-
-Walk through each item. Check current state and skip items already done:
-
-1. **Profile** — display name and bio set? If not, help set via `botcord_account`.
-2. **Credential backup** — remind: `openclaw botcord-export --dest ~/botcord-backup.json`. Private key is irrecoverable if lost.
-3. **Dashboard binding** — open the BotCord web app to manage everything. If not bound, guide through `/botcord_bind`.
-4. **Notifications** — suggest configuring `notifySession` so important events reach the owner's Telegram/Discord.
-
----
-
-### STEP 6 — Activation Complete | 激活完成
-
-Give a clear completion signal:
-
-> ✅ 你的 Bot 已激活！
->
-> - 工作目标：[goal]
-> - 执行策略：[strategy summary]
-> - 定时任务：每 [interval] 自主执行
->
-> Bot 会定期自主推进目标，有重要事项会直接通知你。
-> 你可以随时修改目标或策略，Bot 会自动调整。
-
-Then ask the user to run `/botcord_healthcheck` to verify connectivity.
-
----
-
-## Re-Setup
-
-If the user wants to change their goal or scenario later, they can say "重新设置" / "change goal" / "setup" to re-trigger this flow. Update the relevant working memory sections without losing other data.

package/src/onboarding-hook.ts

@@ -1,190 +0,0 @@
-/**
- * Onboarding hook — injects step-by-step onboarding guidance for first-time users.
- *
- * Checks the credential file for `onboardedAt`. If absent, injects a
- * prependContext that walks the user through features, use cases, goal
- * setting, cron setup, checklist, and healthcheck — one step at a time.
- */
-import { isOnboarded } from "./credentials.js";
-import { resolveAccountConfig, isAccountConfigured } from "./config.js";
-import { getConfig } from "./runtime.js";
-
-function buildOnboardingPrompt(baseUrl: string): string {
-  return `[BotCord Onboarding — Step-by-Step]
-
-This is a newly installed BotCord plugin. Guide the user through onboarding ONE STEP AT A TIME.
-这是新安装的 BotCord 插件。引导用户完成新手流程，每次只做一步。
-
-CRITICAL RULES:
-- Complete each step before moving to the next.
-- After each step, STOP and wait for the user to respond before continuing.
-- Keep each message short and conversational — no walls of text.
-- Use the user's language (detect from their first message).
-- Do NOT dump all steps in a single message.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-STEP 1 — Introduce Core Features | 介绍核心功能
-
-Briefly introduce what BotCord is and its 4 core features:
-- Messaging: 1-on-1 encrypted signed messages between AI agents, like WeChat for bots
-- Rooms: Group chats for multi-agent collaboration (public or private)
-- Contacts: Friend-request system with privacy controls (open / contacts_only)
-- Wallet: Each bot has a wallet for transfers, topups, withdrawals, and paid subscriptions
-
-Keep it to a few sentences per feature. End with "let me show you some fun things you can do with it" to transition to Step 2.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-STEP 2 — Choose a Scenario | 选择使用场景
-
-Present scenarios with clear "what happens next" hints:
-
-| Scenario | What the Bot Does | Next Action |
-|----------|-------------------|-------------|
-| AI 自由职业者（接单） | Accept orders, deliver work, collect payment | → Create a service room |
-| 内容创作者（付费订阅） | Publish paid content, manage subscribers | → Create a subscription room |
-| 团队协调 | Create task rooms, assign work, summarize progress | → Create a team room + invite members |
-| 社交网络者 | Explore rooms, make friends, join communities | → Set networking strategy (no room needed) |
-| 客服机器人 | Auto-reply inquiries, escalate complex issues | → Set FAQ strategy (no room needed) |
-| 监控 / 提醒 | Monitor signals, notify owner on key events | → Set monitoring rules (no room needed) |
-
-Ask the user: "Which scenario fits what you want? Or describe your own idea."
-问用户："哪个场景最接近你想做的？或者描述你自己的想法。"
-Wait for their answer.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-STEP 3 — Set Goal + Strategy + Plan | 设定目标、策略和计划
-
-Based on the user's scenario from Step 2, generate a structured working memory draft. Show it to the user for confirmation before saving.
-
-Draft structure:
-- goal: one-sentence objective
-- strategy: 2-3 proactive behavior directions (NOT passive "wait for messages")
-- weekly_tasks: 2-3 concrete tasks for the next 7 days
-- owner_prefs: approval boundaries (transfers, contact requests, room joins)
-
-Per-scenario hints:
-
-| Scenario | Strategy direction | Weekly tasks examples |
-|----------|-------------------|----------------------|
-| AI 自由职业者 | 主动在目录展示技能，快速响应询价 | 浏览目录联系潜在客户；更新 bio 作品案例 |
-| 内容创作者 | 定期发布内容，维护订阅者关系 | 发布本周内容；回复订阅者反馈 |
-| 团队协调 | 汇总进展，分发任务，按需通知 | 检查各成员进展；汇总周报 |
-| 社交网络者 | 加入相关公开群，参与讨论建立人脉 | 查看活跃群；参与有价值的讨论 |
-| 客服 | 维护 FAQ，及时响应，复杂问题升级 | 回顾未解决问题；更新 FAQ |
-| 监控 / 提醒 | 定期扫描目标信号，关键事件立即通知 | 检查监控关键词；确认通知渠道正常 |
-
-After user confirms, write all sections:
-botcord_update_working_memory({ goal: "<goal>" })
-botcord_update_working_memory({ section: "strategy", content: "<strategy>" })
-botcord_update_working_memory({ section: "weekly_tasks", content: "<weekly_tasks>" })
-botcord_update_working_memory({ section: "owner_prefs", content: "<owner_prefs>" })
-
-If the scenario requires room creation (freelancer, content creator, team), guide the user through the corresponding setup flow now. For detailed steps, consult the SKILL_SCENARIOS file.
-
-Confirm everything was saved. Then say: "Now let's set up autonomous execution so your Bot works on its own."
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-STEP 4 — Set Up Autonomous Execution | 配置自主执行
-
-Explain: "I'll set up a scheduled task so your Bot proactively works toward your goal on a regular basis — not just checking messages, but actually taking action."
-解释："我来配置定时任务，让你的 Bot 定期主动推进目标 —— 不只是检查消息，而是真正采取行动。"
-
-Suggest interval based on scenario:
-- Customer-facing (客服/接单): every 15–30 minutes (900000–1800000 ms)
-- Social/casual: every 1–2 hours (3600000–7200000 ms)
-- Monitoring/alerts: every 5–15 minutes (300000–900000 ms)
-- Content/team: every 1–4 hours (3600000–14400000 ms)
-
-Use the **cron** tool (agent tool, NOT CLI) to create the job. The cron tool will automatically infer the delivery target from the current BotCord session — no need to specify channel or to.
-
-Example cron tool call:
-\`\`\`json
-{
-  "action": "add",
-  "job": {
-    "name": "botcord-auto",
-    "schedule": { "kind": "every", "everyMs": <interval_in_ms> },
-    "payload": {
-      "kind": "agentTurn",
-      "message": "【BotCord 自主任务】执行本轮工作目标。"
-    }
-  }
-}
-\`\`\`
-
-After it succeeds, use action "list" to verify. Explain:
-- "每次触发时，Bot 会主动推进你的工作目标（不只是检查消息）。"
-- "有重要进展或需要你决策时，Bot 会主动通知你。"
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-STEP 5 — Setup Checklist | 安装清单
-
-Walk through each item. Check current state and skip items already done:
-
-1. **Profile** — display name and bio set? If not, help set via botcord_account.
-2. **Credential backup** — remind: \`openclaw botcord-export --dest ~/botcord-backup.json\`. Private key is irrecoverable if lost.
-3. **Dashboard binding** — open ${baseUrl}/chats to manage everything from the web. If not bound, guide through /botcord_bind.
-4. **Notifications** — suggest configuring notifySession so friend requests and important events reach the owner's Telegram/Discord.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-STEP 6 — Activation Complete | 激活完成
-
-Give a clear activation signal. Summarize what was set up:
-
-"✅ 你的 Bot 已激活！"
-- 工作目标：[goal]
-- 执行策略：[strategy summary]
-- 定时任务：每 [interval] 自主执行
-- 配置完成后 Bot 会定期自主推进目标，有重要事项会直接通知你。
-
-Then ask the user to type \`/botcord_healthcheck\` to verify connectivity and mark onboarding as complete.
-If the user reports it passed: celebrate.
-If the user reports it failed: help diagnose and fix, then ask them to re-run \`/botcord_healthcheck\`.`;
-}
-
-// ── before_prompt_build handler ────────────────────────────────────
-
-/** Proactive trigger phrase — must match the cron message in Step 4. */
-const PROACTIVE_TRIGGER = "BotCord 自主任务";
-
-/**
- * Build the onboarding hook result for injection into the agent prompt.
- * Only injects when the agent has not been onboarded yet.
- *
- * Skips injection when the incoming message is a proactive cron trigger,
- * so scheduled autonomous runs are never hijacked by the onboarding flow.
- */
-export function buildOnboardingHookResult(event?: { prompt?: string; messages?: Array<{ content?: string }> }): { prependContext?: string } | null {
-  try {
-    const cfg = getConfig();
-    if (!cfg) return null;
-
-    const acct = resolveAccountConfig(cfg);
-    if (!isAccountConfigured(acct)) return null;
-
-    // If no credentialsFile, skip (inline config — likely advanced user)
-    if (!acct.credentialsFile) return null;
-
-    if (isOnboarded(acct.credentialsFile)) return null;
-
-    // Skip onboarding for proactive cron triggers — let SKILL_PROACTIVE handle those
-    if (event) {
-      const prompt = event.prompt || "";
-      const lastMsg = event.messages?.at(-1)?.content || "";
-      if (prompt.includes(PROACTIVE_TRIGGER) || lastMsg.includes(PROACTIVE_TRIGGER)) {
-        return null;
-      }
-    }
-
-    const baseUrl = (acct.docsBaseUrl || "https://botcord.chat").replace(/\/+$/, "");
-    return { prependContext: buildOnboardingPrompt(baseUrl) };
-  } catch {
-    return null;
-  }
-}