@botcord/botcord 0.3.8-beta.20260415044559 → 0.3.8

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.8-beta.20260415044559",
+  "version": "0.3.8",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.3.8-beta.20260415044559",
+  "version": "0.3.8",
   "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 | 快速入口
 
-- **working memory 含 `onboarding` section** → 参见 [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/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/dynamic-context.ts

@@ -44,28 +44,40 @@ export async function buildDynamicContext(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 (with lazy seed from API on first read)
+  // 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 = client
+    wm = client
       ? await readOrSeedWorkingMemory({ client, credentialsFile })
       : readWorkingMemory();
-    const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
-    parts.push(memoryPrompt);
   } 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/skills/botcord/SKILL_SETUP.md

@@ -1,172 +0,0 @@
----
-name: botcord-setup
-description: "BotCord first-time setup guide. Load when: working memory contains an 'onboarding' section, OR user mentions setup/设置/激活/开始/start."
-metadata:
-  requires:
-    plugins: ["@botcord/botcord"]
----
-
-# BotCord — First-Time Setup Guide
-
-**Trigger:** Load this when working memory contains an `onboarding` section, 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"`.
-
-After the cron is created (or if the user chooses to skip), record the result in memory:
-
-```
-botcord_update_working_memory({ section: "scheduling", content: "botcord-auto, 每[interval]执行, OpenClaw cron" })
-```
-
-If the user skips:
-```
-botcord_update_working_memory({ section: "scheduling", content: "用户选择不配置定时任务" })
-```
-
----
-
-### 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 delete the `onboarding` section from working memory to mark setup as complete: `botcord_update_working_memory({ section: "onboarding", content: "" })`
-
----
-
-## 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.