openclacky 1.5.22 → 1.5.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +104 -0
  3. data/docs/secretary-prototype.md +286 -0
  4. data/lib/clacky/agent/cost_tracker.rb +55 -36
  5. data/lib/clacky/agent/hook_manager.rb +4 -1
  6. data/lib/clacky/agent/llm_caller.rb +46 -12
  7. data/lib/clacky/agent/memory_injector.rb +209 -0
  8. data/lib/clacky/agent/memory_updater.rb +16 -0
  9. data/lib/clacky/agent/session_serializer.rb +15 -11
  10. data/lib/clacky/agent/skill_manager.rb +30 -8
  11. data/lib/clacky/agent.rb +124 -17
  12. data/lib/clacky/agent_config.rb +7 -3
  13. data/lib/clacky/agent_profile.rb +33 -6
  14. data/lib/clacky/anthropic_stream_aggregator.rb +11 -1
  15. data/lib/clacky/bedrock_stream_aggregator.rb +11 -1
  16. data/lib/clacky/billing/platform_billing.rb +7 -0
  17. data/lib/clacky/cli.rb +4 -3
  18. data/lib/clacky/client.rb +30 -25
  19. data/lib/clacky/default_extensions/advisor/README.md +25 -0
  20. data/lib/clacky/default_extensions/advisor/README.zh.md +25 -0
  21. data/lib/clacky/default_extensions/advisor/ext.yml +1 -1
  22. data/lib/clacky/default_extensions/advisor/icon.svg +14 -0
  23. data/lib/clacky/default_extensions/advisor/panels/advisor/view.js +7 -1
  24. data/lib/clacky/default_extensions/coding/ext.yml +0 -1
  25. data/lib/clacky/default_extensions/computer-use/README.md +48 -0
  26. data/lib/clacky/default_extensions/computer-use/README.zh.md +48 -0
  27. data/lib/clacky/default_extensions/computer-use/ext.yml +1 -1
  28. data/lib/clacky/default_extensions/computer-use/icon.svg +16 -0
  29. data/lib/clacky/default_extensions/ext-studio/ext.yml +0 -1
  30. data/lib/clacky/default_extensions/general/ext.yml +0 -1
  31. data/lib/clacky/default_extensions/git/README.md +41 -0
  32. data/lib/clacky/default_extensions/git/README.zh.md +41 -0
  33. data/lib/clacky/default_extensions/git/ext.yml +1 -1
  34. data/lib/clacky/default_extensions/git/icon.svg +15 -0
  35. data/lib/clacky/default_extensions/git/panels/git/view.js +106 -27
  36. data/lib/clacky/default_extensions/meeting/README.md +46 -0
  37. data/lib/clacky/default_extensions/meeting/README.zh.md +47 -0
  38. data/lib/clacky/default_extensions/meeting/ext.yml +1 -1
  39. data/lib/clacky/default_extensions/meeting/icon.svg +13 -0
  40. data/lib/clacky/default_extensions/preview/README.md +29 -0
  41. data/lib/clacky/default_extensions/preview/README.zh.md +29 -0
  42. data/lib/clacky/default_extensions/preview/ext.yml +1 -1
  43. data/lib/clacky/default_extensions/preview/icon.svg +13 -0
  44. data/lib/clacky/default_extensions/secretary/README.md +69 -0
  45. data/lib/clacky/default_extensions/secretary/README.zh.md +69 -0
  46. data/lib/clacky/default_extensions/secretary/agents/secretary.md +41 -0
  47. data/lib/clacky/default_extensions/secretary/agents/worker.md +35 -0
  48. data/lib/clacky/default_extensions/secretary/api/handler.rb +8 -0
  49. data/lib/clacky/default_extensions/secretary/ext.yml +42 -0
  50. data/lib/clacky/default_extensions/secretary/icon.svg +17 -0
  51. data/lib/clacky/default_extensions/secretary/panels/work/view.js +344 -0
  52. data/lib/clacky/default_extensions/secretary/tools/delegate_work.rb +37 -0
  53. data/lib/clacky/default_extensions/secretary/tools/manage_work.rb +22 -0
  54. data/lib/clacky/default_extensions/secretary/tools/yield_work.rb +35 -0
  55. data/lib/clacky/default_extensions/time_machine/README.md +32 -0
  56. data/lib/clacky/default_extensions/time_machine/README.zh.md +32 -0
  57. data/lib/clacky/default_extensions/time_machine/ext.yml +1 -1
  58. data/lib/clacky/default_extensions/time_machine/icon.svg +14 -0
  59. data/lib/clacky/default_skills/channel-manager/SKILL.md +103 -13
  60. data/lib/clacky/default_skills/channel-manager/dingtalk_setup.rb +4 -2
  61. data/lib/clacky/default_skills/channel-manager/discord_setup.rb +9 -2
  62. data/lib/clacky/default_skills/channel-manager/weixin_setup.rb +10 -1
  63. data/lib/clacky/default_skills/cron-task-creator/SKILL.md +183 -206
  64. data/lib/clacky/default_skills/cron-task-creator/evals/evals.json +45 -0
  65. data/lib/clacky/default_skills/media-gen/SKILL.md +31 -14
  66. data/lib/clacky/default_skills/onboard/SKILL.md +5 -7
  67. data/lib/clacky/default_skills/persist-memory/SKILL.md +15 -1
  68. data/lib/clacky/extension/api_extension.rb +23 -2
  69. data/lib/clacky/extension/loader.rb +2 -0
  70. data/lib/clacky/extension/verifier.rb +2 -2
  71. data/lib/clacky/json_ui_controller.rb +14 -1
  72. data/lib/clacky/locales/en.rb +14 -0
  73. data/lib/clacky/locales/i18n.rb +25 -3
  74. data/lib/clacky/locales/zh.rb +14 -0
  75. data/lib/clacky/message_history.rb +15 -2
  76. data/lib/clacky/openai_responses_stream_aggregator.rb +11 -1
  77. data/lib/clacky/openai_stream_aggregator.rb +11 -1
  78. data/lib/clacky/prompts/base.md +1 -1
  79. data/lib/clacky/providers.rb +32 -17
  80. data/lib/clacky/server/backup_manager.rb +98 -2
  81. data/lib/clacky/server/browser_manager.rb +10 -5
  82. data/lib/clacky/server/channel/adapters/base.rb +18 -0
  83. data/lib/clacky/server/channel/adapters/feishu/message_parser.rb +1 -0
  84. data/lib/clacky/server/channel/adapters/telegram/adapter.rb +1 -0
  85. data/lib/clacky/server/channel/channel_config.rb +185 -48
  86. data/lib/clacky/server/channel/channel_manager.rb +247 -110
  87. data/lib/clacky/server/git_panel.rb +2 -1
  88. data/lib/clacky/server/http_server.rb +517 -175
  89. data/lib/clacky/server/preview.rb +26 -5
  90. data/lib/clacky/server/scheduler.rb +166 -85
  91. data/lib/clacky/server/web_ui_controller.rb +12 -0
  92. data/lib/clacky/session_manager.rb +4 -1
  93. data/lib/clacky/skill.rb +1 -1
  94. data/lib/clacky/tools/base.rb +7 -1
  95. data/lib/clacky/ui_interface.rb +5 -0
  96. data/lib/clacky/utils/file_processor.rb +23 -11
  97. data/lib/clacky/utils/model_pricing.rb +19 -0
  98. data/lib/clacky/version.rb +1 -1
  99. data/lib/clacky/web/app.css +621 -52
  100. data/lib/clacky/web/app.js +103 -9
  101. data/lib/clacky/web/components/code-editor.js +73 -4
  102. data/lib/clacky/web/components/custom-select.js +7 -18
  103. data/lib/clacky/web/components/hint-tip.js +172 -0
  104. data/lib/clacky/web/components/model-picker.js +1 -1
  105. data/lib/clacky/web/components/notify.js +37 -10
  106. data/lib/clacky/web/components/onboard.js +1 -1
  107. data/lib/clacky/web/components/sidebar.js +70 -0
  108. data/lib/clacky/web/features/backup/store.js +64 -27
  109. data/lib/clacky/web/features/backup/view.js +42 -11
  110. data/lib/clacky/web/features/channels/store.js +19 -4
  111. data/lib/clacky/web/features/channels/view.js +94 -33
  112. data/lib/clacky/web/features/extensions/view.js +15 -8
  113. data/lib/clacky/web/features/new-session/view.js +33 -22
  114. data/lib/clacky/web/features/profile/view.js +4 -4
  115. data/lib/clacky/web/features/tasks/store.js +5 -3
  116. data/lib/clacky/web/features/tasks/view.js +99 -26
  117. data/lib/clacky/web/features/trash/view.js +4 -4
  118. data/lib/clacky/web/features/workspace/view.js +193 -57
  119. data/lib/clacky/web/i18n.js +189 -17
  120. data/lib/clacky/web/index.html +165 -53
  121. data/lib/clacky/web/projects.js +15 -2
  122. data/lib/clacky/web/sessions.js +316 -86
  123. data/lib/clacky/web/settings.js +304 -75
  124. data/lib/clacky/web/utils.js +261 -0
  125. data/lib/clacky/web/ws-dispatcher.js +24 -3
  126. data/lib/clacky/web/ws.js +16 -4
  127. data/lib/clacky/work/service.rb +544 -0
  128. data/lib/clacky/work/store.rb +57 -0
  129. data/lib/clacky.rb +1 -0
  130. metadata +35 -1
@@ -0,0 +1,35 @@
1
+ # frozen_string_literal: true
2
+ module Clacky
3
+ module Tools
4
+ class YieldWork < Base
5
+ self.tool_name = "yield_work"
6
+ self.tool_description = "End this execution: complete with evidence, request a user decision, or wait. Channel matching requires genuine channel/chat/sent-message IDs; otherwise accept a relayed reply in the panel."
7
+ self.tool_parameters = {
8
+ type: "object", properties: {
9
+ reason: { type: "string", enum: %w[waiting_event needs_input completed], description: "needs_input asks the main agent for help or a decision; waiting_event awaits an external reply or timed checkpoint" },
10
+ summary: { type: "string", description: "Result with evidence, concrete question, or what you are waiting for" },
11
+ display_summary: { type: "string", description: "User-facing progress in one short sentence (max 100 characters): result, question or what is awaited. No internal IDs, channel metadata or execution narration." },
12
+ check_at: { type: "string", description: "Optional future ISO8601 timestamp including timezone" },
13
+ channel: { type: "string" }, conversation_id: { type: "string" }, reply_to: { type: "string" }
14
+ }, required: %w[reason summary]
15
+ }
16
+ def format_call(args)
17
+ concise = (args[:display_summary] || args["display_summary"]).to_s.strip
18
+ return concise if !concise.empty? && concise.length <= 100
19
+ "yield_work(#{args[:reason] || args['reason']})"
20
+ end
21
+
22
+ # Both live rendering and history replay use the host's tool UI contract.
23
+ def ui_result(result)
24
+ return nil unless result[:work_yielded] && !result[:message].to_s.empty?
25
+ { type: "markdown", content: result[:message] }
26
+ end
27
+
28
+ def execute(reason:, summary:, display_summary: nil, check_at: nil, channel: nil, conversation_id: nil, reply_to: nil, **)
29
+ raise "Yield requires a delegated server work session" unless agent&.work_service
30
+ agent.work_service.yield_work(agent, reason: reason, summary: summary, display_summary: display_summary, check_at: check_at,
31
+ channel: channel, conversation_id: conversation_id, reply_to: reply_to)
32
+ end
33
+ end
34
+ end
35
+ end
@@ -0,0 +1,32 @@
1
+ # Time Machine
2
+
3
+ Every time the AI finishes a step, your workspace is snapshotted automatically. Broke something? Jump back to any earlier step.
4
+
5
+ ## Opening it
6
+
7
+ Switch to the **History** tab in the session's side panel to see a timeline of tasks.
8
+
9
+ - The step marked **Current** is the version your workspace is on right now.
10
+ - Each step shows how many files changed and when it finished.
11
+
12
+ ## Seeing what a step changed
13
+
14
+ 1. Click a step on the timeline to expand it and see its main changed files.
15
+ 2. Click **View details** for a two-pane view: file list on the left, line-by-line diff on the right.
16
+ 3. Tags next to each file show the kind of change: **Added / Created / Modified / Deleted**.
17
+ 4. Click **Back** to return to the timeline.
18
+
19
+ ## Going back to an earlier step
20
+
21
+ 1. Expand the target step and click **Go back here**.
22
+ 2. The panel first lists the files that will be affected so you can check them.
23
+ 3. Click **Confirm** and the workspace files are restored to how they were at that step.
24
+
25
+ > ⚠️ Going back overwrites the current changes in those files. Review the list before confirming.
26
+
27
+ If you keep working after going back, the new work grows as a **Branch** — the original history is kept and you can still switch back to it.
28
+
29
+ ## Tips
30
+
31
+ - Snapshots are automatic: no manual saving, and no Git required.
32
+ - To review changes from a Git perspective — by commit or branch — use the **Git** extension.
@@ -0,0 +1,32 @@
1
+ # 时光机
2
+
3
+ AI 每完成一步任务,都会自动给工作区存一个档。改坏了?随时回到之前任意一步。
4
+
5
+ ## 怎么打开
6
+
7
+ 在会话右侧面板切换到 **「时光机」** 标签页,会看到一条按时间排列的任务时间轴。
8
+
9
+ - 标有 **「当前」** 的是工作区现在所处的版本。
10
+ - 每一步显示改动了几个文件以及完成时间。
11
+
12
+ ## 查看某一步改了什么
13
+
14
+ 1. 点击时间轴上的某一步,展开卡片,可以看到主要改动的文件。
15
+ 2. 点击 **「查看详情」**,进入双栏视图:左边是文件列表,右边是逐行差异。
16
+ 3. 文件旁的标签说明改动类型:**新增 / 新建 / 修改 / 删除**。
17
+ 4. 点击 **「返回」** 回到时间轴。
18
+
19
+ ## 回到之前的某一步
20
+
21
+ 1. 展开目标步骤,点击 **「回到这里」**。
22
+ 2. 面板会先列出将受影响的文件,供你确认。
23
+ 3. 点击 **「确认回到这里」**,工作区文件会恢复到那一步完成时的状态。
24
+
25
+ > ⚠️ 回到某一步会覆盖当前工作区中对应文件的修改,请先确认列出的文件。
26
+
27
+ 回到过去的某一步后继续让 AI 工作,会从那里长出新的 **「分支」**,原来的记录不会丢失,之后仍可以切换回去。
28
+
29
+ ## 小贴士
30
+
31
+ - 存档是自动的,不需要手动保存,也不依赖 Git。
32
+ - 想以 Git 的视角审阅改动、按提交或分支对比,可以使用「Git 管理」扩展。
@@ -5,8 +5,8 @@ display_name_zh: 时光机
5
5
  description: Vertical timeline of session tasks with per-task diff and one-click restore
6
6
  description_zh: 会话任务时间轴,支持按任务查看差异并一键还原
7
7
  version: "0.1.0"
8
+ icon: icon.svg
8
9
  author: OpenClacky
9
- homepage: https://www.openclacky.com
10
10
  license: MIT
11
11
  contributes:
12
12
  panels:
@@ -0,0 +1,14 @@
1
+ <svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <defs>
3
+ <linearGradient id="timemachine-bg" x1="18" y1="0" x2="18" y2="36" gradientUnits="userSpaceOnUse">
4
+ <stop stop-color="#14B8A6"/>
5
+ <stop offset="1" stop-color="#0D9488"/>
6
+ </linearGradient>
7
+ </defs>
8
+ <rect width="36" height="36" fill="url(#timemachine-bg)"/>
9
+ <g transform="translate(8 8) scale(0.8333)" stroke="#fff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
10
+ <path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/>
11
+ <path d="M3 3v5h5"/>
12
+ <path d="M12 7v5l4 2"/>
13
+ </g>
14
+ </svg>
@@ -6,7 +6,7 @@ description: |
6
6
  Configure IM platform channels (Feishu, WeCom, Weixin, Discord, Telegram, DingTalk, QQ) for openclacky.
7
7
  Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
8
8
  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "setup discord", "setup telegram", "setup dingtalk", "setup qq",
9
- "channel config", "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
9
+ "bind this session to a channel", "channel config", "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
10
10
  "send message to weixin", "send message to feishu", "send message to wecom", "send message to discord", "send message to telegram", "send message to dingtalk", "send message to qq".
11
11
  Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor, send.
12
12
  argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor | send <platform> <message>"
@@ -34,12 +34,60 @@ Configure IM platform channels for openclacky.
34
34
  | `channel status` | status |
35
35
  | `channel enable feishu/wecom/weixin/discord/telegram/dingtalk/qq` | enable |
36
36
  | `channel disable feishu/wecom/weixin/discord/telegram/dingtalk/qq` | disable |
37
+ | `channel remove`, `channel delete` | remove |
37
38
  | `channel reconfigure` | reconfigure |
38
39
  | `channel doctor` | doctor |
39
40
  | `send <message> to weixin/feishu/wecom/discord/telegram/dingtalk/qq` | send |
40
41
 
41
42
  ---
42
43
 
44
+ ## Keep the current conversation when connecting a channel
45
+
46
+ When the user asks to connect a channel from this conversation, include
47
+ `"bind_session_id": "<actual CLACKY_SESSION_ID>"` in the same
48
+ `POST /api/channels/<platform>` request that saves the credentials. Read the
49
+ actual ID from the terminal environment; never invent it. For an already
50
+ configured channel, POST just `bind_session_id` and the selected `instance_id`.
51
+ The first message received by that instance binds its chat to this conversation
52
+ and runs here, retaining the role and history. No `/bind` command or new session
53
+ is needed. Other chats keep their existing routing.
54
+
55
+ The Weixin, Discord and DingTalk scripts below pass `CLACKY_SESSION_ID` when
56
+ saving credentials. This only applies to setup/binding, not status, enable,
57
+ disable or credential-only maintenance. When explicitly configuring an account
58
+ without binding this conversation, omit `bind_session_id` and run scripts with
59
+ `CLACKY_SESSION_ID` unset. Outside a session, omit the field.
60
+
61
+ ---
62
+
63
+ ## Multiple instances per platform
64
+
65
+ Every platform can be connected more than once (for example a personal and a work
66
+ Feishu app, or two WeChat accounts). Each instance carries:
67
+
68
+ - `id` — stable routing identifier. The first instance is always `default`.
69
+ - `name` — display name shown in the Web UI (e.g. "Company Feishu").
70
+
71
+ Rules:
72
+
73
+ 1. Before adding an instance, ask the user for a display name (`ask_user`).
74
+ 2. Derive `instance_id` from that name as a short ASCII slug (`work`, `personal`,
75
+ `team-2`). It must match `[A-Za-z0-9][A-Za-z0-9_-]{0,39}` and must not collide
76
+ with an existing id from `GET /api/channels` → `channels[].instances[].id`.
77
+ 3. Pass BOTH fields in the same `POST /api/channels/<platform>` body that saves
78
+ the credentials:
79
+ ```json
80
+ {"instance_id":"work","name":"Company Feishu","app_id":"...","app_secret":"..."}
81
+ ```
82
+ 4. Never omit `instance_id` when adding: without it the server updates the
83
+ **default** instance and overwrites its credentials.
84
+ 5. When reconfiguring an existing instance, keep its `instance_id`; never create
85
+ a new one for the same bot.
86
+ 6. All setup flows below work unchanged for the first instance; add the two
87
+ fields above only when the user asked for an additional instance.
88
+
89
+ ---
90
+
43
91
  ## `status`
44
92
 
45
93
  Call the server API:
@@ -61,6 +109,10 @@ Response shape (example):
61
109
 
62
110
  Display the result:
63
111
 
112
+ When a platform has multiple instances, `channels[].instances` lists each one
113
+ with `id`, `name`, `enabled`, `running` and `has_config`. Report one row per
114
+ instance, e.g. `feishu (default)` and `feishu (work)`.
115
+
64
116
  ```
65
117
  Channel Status
66
118
  ─────────────────────────────────────────────────────
@@ -131,7 +183,7 @@ Parse both values.
131
183
  ```bash
132
184
  curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
133
185
  -H "Content-Type: application/json" \
134
- -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
186
+ -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn","bind_session_id":"<actual CLACKY_SESSION_ID>"}'
135
187
  ```
136
188
 
137
189
  **CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml`
@@ -147,7 +199,7 @@ en: "✅ Feishu channel configured! You can now chat with the assistant via Feis
147
199
 
148
200
  #### Step 3 — Optional: install Feishu CLI
149
201
 
150
- Reach here after the channel is configured (Step 2 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
202
+ Reach here after the channel is configured (Step 2 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`; it is now a **list** of instances — use the entry whose `id` matches the instance you just configured, otherwise the first entry) for the install commands below.
151
203
 
152
204
  Call `ask_user`:
153
205
 
@@ -211,7 +263,7 @@ When the session ends with `exit_code: 0`, tell the user:
211
263
  ```bash
212
264
  curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/wecom \
213
265
  -H "Content-Type: application/json" \
214
- -d '{"bot_id":"<BOT_ID>","secret":"<SECRET>"}'
266
+ -d '{"bot_id":"<BOT_ID>","secret":"<SECRET>","bind_session_id":"<actual CLACKY_SESSION_ID>"}'
215
267
  ```
216
268
 
217
269
  On success: "✅ WeCom channel configured. WeCom client → Contacts → Smart Bot to find it."
@@ -222,6 +274,8 @@ On success: "✅ WeCom channel configured. WeCom client → Contacts → Smart B
222
274
 
223
275
  Weixin uses a QR code login — no app_id/app_secret needed. The token from the QR scan is saved directly in `channels.yml`.
224
276
 
277
+ For a second or later WeChat account, ask the user for a display name first, derive an `instance_id`, and pass both to the save step: `weixin_setup.rb --qrcode-id "$QRCODE_ID" --instance-id "personal" --name "Personal WeChat"`. Without `--instance-id` the token overwrites the `default` instance.
278
+
225
279
  #### Step 1 — Fetch QR code
226
280
 
227
281
  Run the script in `--fetch-qr` mode to get the QR URL without blocking:
@@ -271,6 +325,8 @@ As soon as the QR page has been presented to the user — whether you opened it
271
325
  ruby "SKILL_DIR/weixin_setup.rb" --qrcode-id "$QRCODE_ID"
272
326
  ```
273
327
 
328
+ For an additional account, append `--instance-id "<id>" --name "<display name>"` so the new token does not overwrite the existing WeChat instance.
329
+
274
330
  Where `$QRCODE_ID` is the `qrcode_id` from Step 2's JSON output.
275
331
 
276
332
  Run this command with `timeout: 60`. If it doesn't succeed, **retry up to 3 times with the same `$QRCODE_ID`** — the QR code stays valid for 5 minutes. Only stop retrying if:
@@ -370,7 +426,7 @@ Call the server API. It calls `getMe` against the Bot API to validate the token
370
426
  ```bash
371
427
  curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/telegram \
372
428
  -H "Content-Type: application/json" \
373
- -d '{"bot_token":"<TOKEN>","base_url":"<BASE_URL_OR_OMIT>"}'
429
+ -d '{"bot_token":"<TOKEN>","base_url":"<BASE_URL_OR_OMIT>","bind_session_id":"<actual CLACKY_SESSION_ID>"}'
374
430
  ```
375
431
 
376
432
  - `200 { "ok": true }` — token validated and saved. The adapter starts long-polling immediately.
@@ -423,7 +479,7 @@ The server persists the credentials and immediately opens the gateway WebSocket:
423
479
  ```bash
424
480
  curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/qq \
425
481
  -H "Content-Type: application/json" \
426
- -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","sandbox":<TRUE_OR_FALSE>}'
482
+ -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","sandbox":<TRUE_OR_FALSE>,"bind_session_id":"<actual CLACKY_SESSION_ID>"}'
427
483
  ```
428
484
 
429
485
  - `200` — credentials saved; the QQ gateway session starts.
@@ -455,22 +511,55 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/
455
511
 
456
512
  If the platform has no credentials (404 or error), redirect to `setup`.
457
513
 
514
+ When the platform has multiple instances, add `"instance_id":"<id>"` to the body
515
+ to enable just that instance.
516
+
458
517
  Say: "✅ `<platform>` channel enabled."
459
518
 
460
519
  ---
461
520
 
462
521
  ## `disable`
463
522
 
464
- Call the server API to disable the platform:
523
+ Call the server API to turn the platform off without touching its credentials:
465
524
 
466
525
  ```bash
467
- curl -s -X DELETE http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>
526
+ curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/enabled \
527
+ -H "Content-Type: application/json" \
528
+ -d '{"enabled": false}'
529
+ ```
530
+
531
+ This disables the first instance. To disable one specific instance, add its id:
532
+
533
+ ```bash
534
+ curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/enabled \
535
+ -H "Content-Type: application/json" \
536
+ -d '{"enabled": false, "instance_id": "<instance_id>"}'
468
537
  ```
469
538
 
539
+ To disable every instance, read `GET /api/channels` and send the PATCH above for
540
+ each instance id. Never use `DELETE` to turn a bot off — it removes the credentials.
541
+
470
542
  Say: "❌ `<platform>` channel disabled."
471
543
 
472
544
  ---
473
545
 
546
+ ## `remove`
547
+
548
+ Delete one instance and its credentials for good. Always confirm the target with
549
+ the user first, then call:
550
+
551
+ ```bash
552
+ curl -s -X DELETE http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/instances/<instance_id>
553
+ ```
554
+
555
+ The bot stops immediately and the entry is removed from `channels.yml`. Deleting the
556
+ last instance removes the platform entirely. If the user only wants to pause it,
557
+ use `disable` instead.
558
+
559
+ Say: "🗑️ `<platform>` instance `<name>` removed."
560
+
561
+ ---
562
+
474
563
  ### DingTalk setup
475
564
 
476
565
  #### Step 1 — Get QR code
@@ -512,7 +601,7 @@ ruby "SKILL_DIR/dingtalk_setup.rb" --poll "<device_code>"
512
601
  Check each item, report ✅ / ❌ with remediation:
513
602
 
514
603
  1. **Config file** — does `~/.clacky/channels.yml` exist and is it readable?
515
- 2. **Required keys** — for each enabled platform:
604
+ 2. **Required keys** — for each enabled platform instance (every `channels.<platform>` entry is a list of instances):
516
605
  - Feishu: `app_id`, `app_secret` present and non-empty
517
606
  - WeCom: `bot_id`, `secret` present and non-empty
518
607
  - Weixin: `token` present and non-empty in `channels.yml`
@@ -523,8 +612,8 @@ Check each item, report ✅ / ❌ with remediation:
523
612
  4. **Weixin token** (if enabled) — call `GET /api/channels` and check `has_token: true` for the weixin entry.
524
613
  5. **Telegram credentials** (if enabled) — call `getMe` against the Bot API:
525
614
  ```bash
526
- BOT_TOKEN=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["bot_token"] rescue "")')
527
- BASE_URL=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["base_url"] || "https://api.telegram.org" rescue "https://api.telegram.org")')
615
+ BOT_TOKEN=$(ruby -ryaml -e 'c=YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"] rescue nil; c=[c] if c.is_a?(Hash); i=(c||[]).first; puts(i ? i["bot_token"].to_s : "")')
616
+ BASE_URL=$(ruby -ryaml -e 'c=YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"] rescue nil; c=[c] if c.is_a?(Hash); i=(c||[]).first; puts(i && i["base_url"] ? i["base_url"] : "https://api.telegram.org")')
528
617
  curl -s "$BASE_URL/bot$BOT_TOKEN/getMe" | grep -q '"ok":true' && echo "✅ Telegram OK" || echo "❌ Telegram credentials rejected by getMe"
529
618
  ```
530
619
  6. **WeCom credentials** (if enabled) — search today's log:
@@ -567,6 +656,7 @@ Proactively send a message to a user via an IM channel adapter.
567
656
  Extract two things from the user's instruction:
568
657
  - **platform** — one of `weixin`, `feishu`, `wecom`, `discord`, `telegram`, `dingtalk`, `qq`
569
658
  - **message** — the text content to send
659
+ - **instance** (optional) — when the platform has multiple instances, ask which `name`/`id` to use and pass `instance_id` in both API calls below
570
660
 
571
661
  If the platform cannot be inferred, ask the user to clarify.
572
662
 
@@ -577,7 +667,7 @@ If the user specified a `user_id`, use it directly.
577
667
  Otherwise, list known users first:
578
668
 
579
669
  ```bash
580
- curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/users
670
+ curl -s "http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/users?instance_id=<instance_id>"
581
671
  ```
582
672
 
583
673
  - If the list is **empty**: tell the user "No known users for `<platform>`. The target user must send at least one message to the bot before proactive messaging is possible." Stop here.
@@ -589,7 +679,7 @@ curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platfor
589
679
  ```bash
590
680
  curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/send \
591
681
  -H "Content-Type: application/json" \
592
- -d '{"message": "<message>", "user_id": "<user_id>"}'
682
+ -d '{"message": "<message>", "user_id": "<user_id>", "instance_id": "<instance_id>"}'
593
683
  ```
594
684
 
595
685
  **Response handling:**
@@ -134,8 +134,10 @@ def mode_poll(device_code, expires_in: POLL_TIMEOUT, interval: POLL_INTERVAL)
134
134
  step "Phase 4 — Saving credentials to clacky server..."
135
135
 
136
136
  begin
137
- res = server_post("/api/channels/dingtalk",
138
- { client_id: client_id, client_secret: client_secret, enabled: true })
137
+ fields = { client_id: client_id, client_secret: client_secret, enabled: true }
138
+ session_id = ENV["CLACKY_SESSION_ID"].to_s.strip
139
+ fields[:bind_session_id] = session_id unless session_id.empty?
140
+ res = server_post("/api/channels/dingtalk", fields)
139
141
  if res.code.to_i == 200
140
142
  ok "Credentials saved, DingTalk Stream adapter starting..."
141
143
  else
@@ -86,12 +86,19 @@ def saved_bot_token
86
86
  yml_path = File.expand_path("~/.clacky/channels.yml")
87
87
  return nil unless File.exist?(yml_path)
88
88
  data = YAML.safe_load(File.read(yml_path), permitted_classes: [Symbol], aliases: true) rescue nil
89
- data&.dig("channels", "discord", "bot_token") || data&.dig(:channels, :discord, :bot_token)
89
+ channels = data.is_a?(Hash) ? (data["channels"] || data[:channels]) : nil
90
+ entries = channels.is_a?(Hash) ? (channels["discord"] || channels[:discord]) : nil
91
+ entries = [entries] if entries.is_a?(Hash)
92
+ first = Array(entries).find { |inst| inst.is_a?(Hash) }
93
+ first && (first["bot_token"] || first[:bot_token])
90
94
  end
91
95
 
92
96
  def save_to_server(bot_token:)
93
97
  uri = URI("#{CLACKY_SERVER_URL}/api/channels/discord")
94
- body = JSON.generate({ bot_token: bot_token })
98
+ fields = { bot_token: bot_token }
99
+ session_id = ENV["CLACKY_SESSION_ID"].to_s.strip
100
+ fields[:bind_session_id] = session_id unless session_id.empty?
101
+ body = JSON.generate(fields)
95
102
 
96
103
  http = Net::HTTP.new(uri.host, uri.port)
97
104
  http.read_timeout = 30
@@ -44,6 +44,10 @@ end
44
44
  FETCH_QR_MODE = ARGV.include?("--fetch-qr")
45
45
  QRCODE_ID_IDX = ARGV.index("--qrcode-id")
46
46
  GIVEN_QRCODE_ID = QRCODE_ID_IDX ? ARGV[QRCODE_ID_IDX + 1] : nil
47
+ INSTANCE_ID_IDX = ARGV.index("--instance-id")
48
+ GIVEN_INSTANCE_ID = INSTANCE_ID_IDX ? ARGV[INSTANCE_ID_IDX + 1].to_s.strip : ""
49
+ NAME_IDX = ARGV.index("--name")
50
+ GIVEN_NAME = NAME_IDX ? ARGV[NAME_IDX + 1].to_s.strip : ""
47
51
 
48
52
  # ---------------------------------------------------------------------------
49
53
  # Logging (suppress in --fetch-qr mode so stdout is clean JSON)
@@ -145,7 +149,12 @@ end
145
149
 
146
150
  def save_to_server(token:, base_url:)
147
151
  uri = URI("#{CLACKY_SERVER_URL}/api/channels/weixin")
148
- body = JSON.generate({ token: token, base_url: base_url })
152
+ body = { token: token, base_url: base_url }
153
+ session_id = ENV["CLACKY_SESSION_ID"].to_s.strip
154
+ body[:bind_session_id] = session_id unless session_id.empty?
155
+ body[:instance_id] = GIVEN_INSTANCE_ID unless GIVEN_INSTANCE_ID.empty?
156
+ body[:name] = GIVEN_NAME unless GIVEN_NAME.empty?
157
+ body = JSON.generate(body)
149
158
 
150
159
  http = Net::HTTP.new(uri.host, uri.port)
151
160
  http.read_timeout = 15