-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | **English**
+[中文](docs/project/README.zh.md) | [日本語](docs/project/README.ja.md) | [한국어](docs/project/README.ko.md) | [Português](docs/project/README.pt-br.md) | [Tiếng Việt](docs/project/README.vi.md) | [Français](docs/project/README.fr.md) | [Italiano](docs/project/README.it.md) | [Bahasa Indonesia](docs/project/README.id.md) | [Malay](docs/project/README.ms.md) | **English**
@@ -112,7 +112,7 @@ _*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is
-> **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!
+> **[Hardware Compatibility List](docs/guides/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!
@@ -164,22 +164,32 @@ Alternatively, download the binary for your platform from the [GitHub Releases](
### Build from source (for development)
+Prerequisites:
+
+- Go 1.25+
+- Node.js 22+ and pnpm 10.33.0+ for Web UI / launcher builds
+
```bash
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
-# Build core binary
+# Install frontend dependencies
+(cd web/frontend && pnpm install --frozen-lockfile)
+
+# Build the core binary for the current platform
make build
-# Build Web UI Launcher (required for WebUI mode)
+# Build the Web UI Launcher (required for WebUI mode)
make build-launcher
-# Build for multiple platforms
+# Build core binaries for all Makefile-managed platforms
make build-all
-# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+# Build for Raspberry Pi Zero 2 W
+# 32-bit: make build-linux-arm
+# 64-bit: make build-linux-arm64
make build-pi-zero
# Build and install
@@ -215,7 +225,7 @@ picoclaw-launcher
-**Getting started:**
+**Getting started:**
Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel -> **3)** Start the Gateway -> **4)** Chat!
For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
+
### 📱 Android
Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw.
@@ -368,8 +379,8 @@ This creates `~/.picoclaw/config.json` and the workspace directory.
```
> See `config/config.example.json` in the repo for a complete configuration template with all available options.
->
-> Please note: config.example.json format is version 0, with sensitive codes in it, and will be auto migrated to version 1+, then, the config.json will only store insensitive data, the sensitive codes will be stored in .security.yml, if you need manually modify the codes, please see `docs/security_configuration.md` for more details.
+>
+> Please note: config.example.json format is version 0, with sensitive codes in it, and will be auto migrated to version 1+, then, the config.json will only store insensitive data, the sensitive codes will be stored in .security.yml, if you need manually modify the codes, please see `docs/security/security_configuration.md` for more details.
**3. Chat**
@@ -448,7 +459,7 @@ PicoClaw supports 30+ LLM providers through the `model_list` configuration. Use
}
```
-For full provider configuration details, see [Providers & Models](docs/providers.md).
+For full provider configuration details, see [Providers & Models](docs/guides/providers.md).
@@ -460,8 +471,8 @@ Talk to your PicoClaw through 18+ messaging platforms:
|---------|-------|----------|------|
| **Telegram** | Easy (bot token) | Long polling | [Guide](docs/channels/telegram/README.md) |
| **Discord** | Easy (bot token + intents) | WebSocket | [Guide](docs/channels/discord/README.md) |
-| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/chat-apps.md#weixin) |
+| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/guides/chat-apps.md#whatsapp) |
+| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/guides/chat-apps.md#weixin) |
| **QQ** | Easy (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.md) |
| **Slack** | Easy (bot + app token) | Socket Mode | [Guide](docs/channels/slack/README.md) |
| **Matrix** | Medium (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.md) |
@@ -470,7 +481,7 @@ Talk to your PicoClaw through 18+ messaging platforms:
| **LINE** | Medium (credentials + webhook) | Webhook | [Guide](docs/channels/line/README.md) |
| **WeCom** | Easy (QR login or manual) | WebSocket | [Guide](docs/channels/wecom/README.md) |
| **VK** | Easy (group token) | Long Poll | [Guide](docs/channels/vk/README.md) |
-| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/chat-apps.md#irc) |
+| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/guides/chat-apps.md#irc) |
| **OneBot** | Medium (WebSocket URL) | OneBot v11 | [Guide](docs/channels/onebot/README.md) |
| **MaixCam** | Easy (enable) | TCP socket | [Guide](docs/channels/maixcam/README.md) |
| **Pico** | Easy (enable) | Native protocol | Built-in |
@@ -478,9 +489,9 @@ Talk to your PicoClaw through 18+ messaging platforms:
> All webhook-based channels share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu uses WebSocket/SDK mode and does not use the shared HTTP server.
-> Log verbosity is controlled by `gateway.log_level` (default: `warn`). Supported values: `debug`, `info`, `warn`, `error`, `fatal`. Can also be set via `PICOCLAW_LOG_LEVEL`. See [Configuration](docs/configuration.md#gateway-log-level) for details.
+> Log verbosity is controlled by `gateway.log_level` (default: `warn`). Supported values: `debug`, `info`, `warn`, `error`, `fatal`. Can also be set via `PICOCLAW_LOG_LEVEL`. See [Configuration](docs/guides/configuration.md#gateway-log-level) for details.
-For detailed channel setup instructions, see [Chat Apps Configuration](docs/chat-apps.md).
+For detailed channel setup instructions, see [Chat Apps Configuration](docs/guides/chat-apps.md).
## 🔧 Tools
@@ -500,7 +511,7 @@ PicoClaw can search the web to provide up-to-date information. Configure in `too
### ⚙️ Other Tools
-PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/tools_configuration.md) for details.
+PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/reference/tools_configuration.md) for details.
## 🎯 Skills
@@ -513,7 +524,7 @@ picoclaw skills search "web scraping"
picoclaw skills install 
Join the Agent Social Network
@@ -590,7 +608,7 @@ PicoClaw supports scheduled reminders and recurring tasks through the `cron` too
* **Recurring tasks**: "Remind me every 2 hours" -> triggers every 2 hours
* **Cron expressions**: "Remind me at 9am daily" -> uses cron expression
-See [docs/cron.md](docs/cron.md) for current schedule types, execution modes, command-job gates, and persistence details.
+See [docs/reference/cron.md](docs/reference/cron.md) for current schedule types, execution modes, command-job gates, and persistence details.
## 📚 Documentation
@@ -598,18 +616,18 @@ For detailed guides beyond this README:
| Topic | Description |
|-------|-------------|
-| [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes |
-| [Chat Apps](docs/chat-apps.md) | All 17+ channel setup guides |
-| [Configuration](docs/configuration.md) | Environment variables, workspace layout, security sandbox |
-| [Scheduled Tasks and Cron Jobs](docs/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
-| [Providers & Models](docs/providers.md) | 30+ LLM providers, model routing, model_list configuration |
-| [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
-| [Hooks](docs/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks |
-| [Steering](docs/steering.md) | Inject messages into a running agent loop between tool calls |
-| [SubTurn](docs/subturn.md) | Subagent coordination, concurrency control, lifecycle |
-| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
-| [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills |
-| [Hardware Compatibility](docs/hardware-compatibility.md) | Tested boards, minimum requirements |
+| [Docker & Quick Start](docs/guides/docker.md) | Docker Compose setup, Launcher/Agent modes |
+| [Chat Apps](docs/guides/chat-apps.md) | All 17+ channel setup guides |
+| [Configuration](docs/guides/configuration.md) | Environment variables, workspace layout, security sandbox |
+| [Scheduled Tasks and Cron Jobs](docs/reference/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
+| [Providers & Models](docs/guides/providers.md) | 30+ LLM providers, model routing, model_list configuration |
+| [Spawn & Async Tasks](docs/guides/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
+| [Hooks](docs/architecture/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks |
+| [Steering](docs/architecture/steering.md) | Inject messages into a running agent loop between tool calls |
+| [SubTurn](docs/architecture/subturn.md) | Subagent coordination, concurrency control, lifecycle |
+| [Troubleshooting](docs/operations/troubleshooting.md) | Common issues and solutions |
+| [Tools Configuration](docs/reference/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills |
+| [Hardware Compatibility](docs/guides/hardware-compatibility.md) | Tested boards, minimum requirements |
## 🤝 Contribute & Roadmap
diff --git a/assets/wechat.png b/assets/wechat.png
index 07a05dd91..d538f40e6 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/membench/eval.go b/cmd/membench/eval.go
new file mode 100644
index 000000000..729c9f97f
--- /dev/null
+++ b/cmd/membench/eval.go
@@ -0,0 +1,412 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "log"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/seahorse"
+)
+
+// EvalResult holds per-sample evaluation results for one mode.
+type EvalResult struct {
+ Mode string `json:"mode"`
+ SampleID string `json:"sampleId"`
+ QAResults []QAResult `json:"qaResults"`
+ Agg AggMetrics `json:"aggregated"`
+}
+
+// QAResult holds metrics for a single QA pair.
+type QAResult struct {
+ Question string `json:"question"`
+ Category int `json:"category"`
+ GoldAnswer string `json:"goldAnswer"`
+ TokenF1 float64 `json:"tokenF1"`
+ HitRate float64 `json:"hitRate"`
+}
+
+// AggMetrics holds aggregated evaluation metrics.
+type AggMetrics struct {
+ OverallF1 float64 `json:"overallF1"`
+ OverallHitRate float64 `json:"overallHitRate"`
+ ByCategory map[int]*CatMetrics `json:"byCategory"`
+ TotalQuestions int `json:"totalQuestions"`
+ ValidF1Count int `json:"validF1Count"`
+}
+
+// CatMetrics holds metrics for a single category.
+type CatMetrics struct {
+ F1 float64 `json:"f1"`
+ HitRate float64 `json:"hitRate"`
+ QuestionCount int `json:"questionCount"`
+ ValidF1Count int `json:"validF1Count"`
+}
+
+// EvalLegacy evaluates using legacy session store (raw history + budget truncation).
+func EvalLegacy(
+ ctx context.Context,
+ samples []LocomoSample,
+ legacy *LegacyStore,
+ budgetTokens int,
+) []EvalResult {
+ results := make([]EvalResult, 0, len(samples))
+ for si := range samples {
+ sample := &samples[si]
+ history := legacy.GetHistory(sample.SampleID)
+
+ // Convert messages to content strings
+ allContent := make([]string, 0, len(history))
+ for _, msg := range history {
+ allContent = append(allContent, msg.Content)
+ }
+
+ qaResults := make([]QAResult, 0, len(sample.QA))
+ for qi := range sample.QA {
+ qa := &sample.QA[qi]
+ // Budget truncate the full history
+ truncated, _ := BudgetTruncate(allContent, budgetTokens)
+ context := StringListToContent(truncated)
+
+ f1 := TokenOverlapF1(context, qa.AnswerString())
+ hitRate := RecallHitRate(qa.Evidence, sample, context)
+
+ qaResults = append(qaResults, QAResult{
+ Question: qa.Question,
+ Category: qa.Category,
+ GoldAnswer: qa.AnswerString(),
+ TokenF1: f1,
+ HitRate: hitRate,
+ })
+ }
+
+ results = append(results, EvalResult{
+ Mode: "legacy",
+ SampleID: sample.SampleID,
+ QAResults: qaResults,
+ Agg: aggregateMetrics(qaResults),
+ })
+ }
+ return results
+}
+
+// EvalSeahorse evaluates using seahorse short memory (per-keyword search + expand).
+func EvalSeahorse(
+ ctx context.Context,
+ samples []LocomoSample,
+ ir *SeahorseIngestResult,
+ budgetTokens int,
+) []EvalResult {
+ store := ir.Engine.GetRetrieval().Store()
+ retrieval := ir.Engine.GetRetrieval()
+
+ results := make([]EvalResult, 0, len(samples))
+ for si := range samples {
+ sample := &samples[si]
+ convID, ok := ir.ConvMap[sample.SampleID]
+ if !ok {
+ log.Printf("WARN: no conversation ID for sample %s", sample.SampleID)
+ continue
+ }
+
+ qaResults := make([]QAResult, 0, len(sample.QA))
+ for qi := range sample.QA {
+ qa := &sample.QA[qi]
+ keywords := ExtractKeywords(qa.Question)
+
+ // Search each keyword individually and union results,
+ // tracking best BM25 rank per message for relevance sorting.
+ bestRank := map[int64]float64{}
+ for _, kw := range keywords {
+ searchResults, err := store.SearchMessages(ctx, seahorse.SearchInput{
+ Pattern: kw,
+ ConversationID: convID,
+ Limit: 20,
+ })
+ if err != nil {
+ log.Printf("WARN: search failed for keyword %q: %v", kw, err)
+ continue
+ }
+ for _, sr := range searchResults {
+ if sr.MessageID > 0 {
+ if prev, ok := bestRank[sr.MessageID]; !ok || sr.Rank < prev {
+ bestRank[sr.MessageID] = sr.Rank
+ }
+ }
+ }
+ }
+ // Sort messageIDs by rank ascending (best/most-negative first).
+ // BudgetTruncate walks from the front, keeping best-ranked messages.
+ // Note: SQLite FTS5 bm25() returns negative values where more
+ // negative = better match.
+ messageIDs := make([]int64, 0, len(bestRank))
+ for id := range bestRank {
+ messageIDs = append(messageIDs, id)
+ }
+ sort.Slice(messageIDs, func(i, j int) bool {
+ return bestRank[messageIDs[i]] < bestRank[messageIDs[j]]
+ })
+
+ // Expand messages to get full content
+ var contentParts []string
+ if len(messageIDs) > 0 {
+ expandResult, err := retrieval.ExpandMessages(ctx, messageIDs)
+ if err != nil {
+ log.Printf("WARN: expand failed for sample %s: %v", sample.SampleID, err)
+ } else {
+ for _, msg := range expandResult.Messages {
+ contentParts = append(contentParts, msg.Content)
+ }
+ }
+ }
+
+ if len(contentParts) == 0 {
+ qaResults = append(qaResults, QAResult{
+ Question: qa.Question,
+ Category: qa.Category,
+ GoldAnswer: qa.AnswerString(),
+ TokenF1: 0.0,
+ HitRate: 0.0,
+ })
+ continue
+ }
+
+ // Budget truncate (drop worst-ranked)
+ truncated, _ := BudgetTruncate(contentParts, budgetTokens)
+ context := StringListToContent(truncated)
+
+ f1 := TokenOverlapF1(context, qa.AnswerString())
+ hitRate := RecallHitRate(qa.Evidence, sample, context)
+
+ qaResults = append(qaResults, QAResult{
+ Question: qa.Question,
+ Category: qa.Category,
+ GoldAnswer: qa.AnswerString(),
+ TokenF1: f1,
+ HitRate: hitRate,
+ })
+ }
+
+ results = append(results, EvalResult{
+ Mode: "seahorse",
+ SampleID: sample.SampleID,
+ QAResults: qaResults,
+ Agg: aggregateMetrics(qaResults),
+ })
+ }
+ return results
+}
+
+// aggregateMetrics computes overall and per-category metrics.
+func aggregateMetrics(qaResults []QAResult) AggMetrics {
+ type catAccum struct {
+ f1Sum float64
+ f1Count int
+ hitRateSum float64
+ hitRateCount int
+ }
+ byCatAcc := map[int]*catAccum{}
+ totalF1 := 0.0
+ totalHitRate := 0.0
+ validF1Count := 0
+ for _, qr := range qaResults {
+ // Skip sentinel -1.0 scores (LLM API/parse failures) from F1 averaging.
+ if qr.TokenF1 >= 0 {
+ totalF1 += qr.TokenF1
+ validF1Count++
+ }
+ totalHitRate += qr.HitRate
+ acc, ok := byCatAcc[qr.Category]
+ if !ok {
+ acc = &catAccum{}
+ byCatAcc[qr.Category] = acc
+ }
+ if qr.TokenF1 >= 0 {
+ acc.f1Sum += qr.TokenF1
+ acc.f1Count++
+ }
+ acc.hitRateSum += qr.HitRate
+ acc.hitRateCount++
+ }
+ nHit := len(qaResults)
+ if nHit == 0 {
+ nHit = 1
+ }
+ byCat := map[int]*CatMetrics{}
+ for cat, acc := range byCatAcc {
+ cm := &CatMetrics{
+ QuestionCount: acc.hitRateCount,
+ ValidF1Count: acc.f1Count,
+ }
+ if acc.f1Count > 0 {
+ cm.F1 = acc.f1Sum / float64(acc.f1Count)
+ }
+ if acc.hitRateCount > 0 {
+ cm.HitRate = acc.hitRateSum / float64(acc.hitRateCount)
+ }
+ byCat[cat] = cm
+ }
+ var overallF1 float64
+ if validF1Count > 0 {
+ overallF1 = totalF1 / float64(validF1Count)
+ }
+ return AggMetrics{
+ OverallF1: overallF1,
+ OverallHitRate: totalHitRate / float64(nHit),
+ ByCategory: byCat,
+ TotalQuestions: len(qaResults),
+ ValidF1Count: validF1Count,
+ }
+}
+
+// SaveResults writes per-sample eval results to JSON files.
+func SaveResults(results []EvalResult, outDir string) error {
+ if err := os.MkdirAll(outDir, 0o755); err != nil {
+ return fmt.Errorf("create output dir: %w", err)
+ }
+ for _, r := range results {
+ path := filepath.Join(outDir, fmt.Sprintf("eval_%s_%s.json", r.Mode, r.SampleID))
+ data, err := json.MarshalIndent(r, "", " ")
+ if err != nil {
+ return fmt.Errorf("marshal result: %w", err)
+ }
+ if err := os.WriteFile(path, data, 0o644); err != nil {
+ return fmt.Errorf("write result: %w", err)
+ }
+ }
+ return nil
+}
+
+// SaveAggregated writes a combined results.json with all modes.
+func SaveAggregated(results []EvalResult, outDir string) error {
+ byMode := map[string][]EvalResult{}
+ for _, r := range results {
+ byMode[r.Mode] = append(byMode[r.Mode], r)
+ }
+
+ aggMap := map[string]AggMetrics{}
+ for mode, modeResults := range byMode {
+ aggMap[mode] = computeModeAgg(modeResults)
+ }
+
+ data, err := json.MarshalIndent(aggMap, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(filepath.Join(outDir, "results.json"), data, 0o644)
+}
+
+// computeModeAgg aggregates results for a single mode using weighted averaging
+// (weighted by question count per sample). All modes must have the same Mode field.
+func computeModeAgg(results []EvalResult) AggMetrics {
+ agg := AggMetrics{ByCategory: map[int]*CatMetrics{}}
+ for _, r := range results {
+ // Backward compat: old eval JSON (token mode) without ValidF1Count → use TotalQuestions.
+ // LLM modes may legitimately have ValidF1Count==0 (all failures).
+ vf1 := r.Agg.ValidF1Count
+ if vf1 == 0 && r.Agg.TotalQuestions > 0 && !strings.HasSuffix(r.Mode, "-llm") {
+ vf1 = r.Agg.TotalQuestions
+ }
+ agg.OverallF1 += r.Agg.OverallF1 * float64(vf1)
+ agg.OverallHitRate += r.Agg.OverallHitRate * float64(r.Agg.TotalQuestions)
+ agg.TotalQuestions += r.Agg.TotalQuestions
+ agg.ValidF1Count += vf1
+ for cat, cm := range r.Agg.ByCategory {
+ existing, ok := agg.ByCategory[cat]
+ if !ok {
+ existing = &CatMetrics{}
+ agg.ByCategory[cat] = existing
+ }
+ cvf1 := cm.ValidF1Count
+ if cvf1 == 0 && cm.QuestionCount > 0 && !strings.HasSuffix(r.Mode, "-llm") {
+ cvf1 = cm.QuestionCount
+ }
+ existing.F1 += cm.F1 * float64(cvf1)
+ existing.HitRate += cm.HitRate * float64(cm.QuestionCount)
+ existing.QuestionCount += cm.QuestionCount
+ existing.ValidF1Count += cvf1
+ }
+ }
+ if agg.ValidF1Count > 0 {
+ agg.OverallF1 /= float64(agg.ValidF1Count)
+ }
+ if agg.TotalQuestions > 0 {
+ agg.OverallHitRate /= float64(agg.TotalQuestions)
+ }
+ for _, cat := range agg.ByCategory {
+ if cat.ValidF1Count > 0 {
+ cat.F1 /= float64(cat.ValidF1Count)
+ }
+ if cat.QuestionCount > 0 {
+ cat.HitRate /= float64(cat.QuestionCount)
+ }
+ }
+ return agg
+}
+
+// printSection prints a single comparison table section.
+func printSection(title string, results []EvalResult) {
+ fmt.Printf("\n--- %s ---\n", title)
+ byMode := map[string][]EvalResult{}
+ for _, r := range results {
+ byMode[r.Mode] = append(byMode[r.Mode], r)
+ }
+
+ modes := map[string]AggMetrics{}
+ for mode, modeResults := range byMode {
+ modes[mode] = computeModeAgg(modeResults)
+ }
+
+ modeKeys := make([]string, 0, len(modes))
+ for k := range modes {
+ modeKeys = append(modeKeys, k)
+ }
+ sort.Strings(modeKeys)
+
+ // Collect all category keys across modes
+ catSet := map[int]bool{}
+ for _, agg := range modes {
+ for cat := range agg.ByCategory {
+ catSet[cat] = true
+ }
+ }
+ cats := make([]int, 0, len(catSet))
+ for cat := range catSet {
+ cats = append(cats, cat)
+ }
+ sort.Ints(cats)
+
+ fmt.Printf("%-10s %-8s %-8s", "Mode", "HitRate", "F1")
+ for _, cat := range cats {
+ fmt.Printf(" %-7s", fmt.Sprintf("C%d", cat))
+ }
+ fmt.Println()
+ fmt.Println(strings.Repeat("-", 10+8+8+7*len(cats)+8))
+
+ for _, mode := range modeKeys {
+ agg := modes[mode]
+ fmt.Printf("%-10s %-8.4f %-8.4f", mode, agg.OverallHitRate, agg.OverallF1)
+ for _, cat := range cats {
+ if cm, ok := agg.ByCategory[cat]; ok {
+ fmt.Printf(" %-7.4f", cm.HitRate)
+ } else {
+ fmt.Printf(" %-7s", "N/A")
+ }
+ }
+ fmt.Println()
+ }
+}
+
+// PrintComparison outputs a human-readable comparison table to stdout.
+func PrintComparison(results []EvalResult, llmResults []EvalResult) {
+ if len(results) > 0 {
+ printSection("No LLM generation", results)
+ }
+ if len(llmResults) > 0 {
+ printSection("With LLM", llmResults)
+ }
+}
diff --git a/cmd/membench/eval_llm.go b/cmd/membench/eval_llm.go
new file mode 100644
index 000000000..ee401d134
--- /dev/null
+++ b/cmd/membench/eval_llm.go
@@ -0,0 +1,346 @@
+package main
+
+import (
+ "context"
+ "fmt"
+ "log"
+ "regexp"
+ "sort"
+ "strconv"
+ "strings"
+ "sync"
+
+ "github.com/sipeed/picoclaw/pkg/seahorse"
+)
+
+const answerSystemPrompt = `You are a helpful assistant. Given conversation context, answer the question concisely and accurately. If the answer is not in the context, say "I don't know". Answer in 1-3 sentences maximum.`
+
+const judgeSystemPrompt = `You are an impartial judge evaluating answer quality.
+Compare the candidate answer against the reference answer.
+Consider semantic equivalence — different wording expressing the same meaning should score high.
+
+Output ONLY a single integer score from 1 to 5:
+1 = completely wrong or irrelevant
+2 = partially related but mostly incorrect
+3 = partially correct, missing key details
+4 = mostly correct with minor omissions
+5 = fully correct, semantically equivalent
+
+Output ONLY the number, nothing else.`
+
+// generateAnswer asks the LLM to answer a question given retrieved context.
+func generateAnswer(ctx context.Context, client *LLMClient, contextText, question string) (string, error) {
+ // Truncate context to avoid exceeding model limits while preserving valid UTF-8.
+ contextRunes := []rune(contextText)
+ if len(contextRunes) > 6000 {
+ contextText = string(contextRunes[:6000]) + "\n... [truncated]"
+ }
+
+ userPrompt := fmt.Sprintf("## Conversation Context\n\n%s\n\n## Question\n\n%s", contextText, question)
+ return client.Complete(ctx, answerSystemPrompt, userPrompt)
+}
+
+// scoreRe matches the first standalone integer 1-5 in the judge response.
+var scoreRe = regexp.MustCompile(`\b([1-5])\b`)
+
+// judgeAnswer asks the LLM to score the candidate answer vs the gold answer.
+// Returns a score from 0.0 to 1.0, or -1.0 on parse failure.
+func judgeAnswer(
+ ctx context.Context,
+ judgeClient *LLMClient,
+ question, goldAnswer, candidateAnswer string,
+) (float64, error) {
+ userPrompt := fmt.Sprintf(
+ "Question: %s\n\nReference Answer: %s\n\nCandidate Answer: %s\n\nScore:",
+ question, goldAnswer, candidateAnswer,
+ )
+
+ response, err := judgeClient.Complete(ctx, judgeSystemPrompt, userPrompt)
+ if err != nil {
+ return -1.0, err
+ }
+
+ response = strings.TrimSpace(response)
+ if m := scoreRe.FindStringSubmatch(response); len(m) == 2 {
+ score, _ := strconv.Atoi(m[1])
+ return float64(score-1) / 4.0, nil // Normalize 1-5 to 0.0-1.0
+ }
+ log.Printf("WARNING: could not parse judge score from: %q, returning -1", response)
+ return -1.0, nil
+}
+
+// qaWork describes one QA evaluation unit.
+type qaWork struct {
+ sampleID string
+ qaIndex int
+ globalIndex int
+ totalQA int
+ qa *LocomoQA
+ contextText string
+ sample *LocomoSample
+}
+
+// qaResult collects one QA evaluation output.
+type qaResultOut struct {
+ index int // position in the flat QA list for ordering
+ result QAResult
+ answer string
+ score float64
+}
+
+// evalQAWorker processes a single QA item: generate answer + judge score.
+func evalQAWorker(
+ ctx context.Context,
+ w qaWork,
+ answerClient, judgeClient *LLMClient,
+ logPrefix string,
+) qaResultOut {
+ llmAnswer, err := generateAnswer(ctx, answerClient, w.contextText, w.qa.Question)
+ if err != nil {
+ log.Printf("WARN: LLM generation failed for sample %s Q%d: %v", w.sampleID, w.qaIndex, err)
+ llmAnswer = ""
+ }
+
+ score := -1.0
+ if llmAnswer != "" {
+ score, err = judgeAnswer(ctx, judgeClient, w.qa.Question, w.qa.AnswerString(), llmAnswer)
+ if err != nil {
+ log.Printf("WARN: LLM judge failed for sample %s Q%d: %v", w.sampleID, w.qaIndex, err)
+ }
+ }
+
+ hitRate := RecallHitRate(w.qa.Evidence, w.sample, w.contextText)
+
+ log.Printf("[%s] sample=%s q=%d/%d score=%.2f answer=%q",
+ logPrefix, w.sampleID, w.globalIndex, w.totalQA, score, truncateStr(llmAnswer, 80))
+
+ return qaResultOut{
+ index: w.globalIndex,
+ result: QAResult{
+ Question: w.qa.Question,
+ Category: w.qa.Category,
+ GoldAnswer: w.qa.AnswerString(),
+ TokenF1: score,
+ HitRate: hitRate,
+ },
+ answer: llmAnswer,
+ score: score,
+ }
+}
+
+// EvalLegacyLLM evaluates legacy store using LLM generation + LLM-as-Judge.
+func EvalLegacyLLM(
+ ctx context.Context,
+ samples []LocomoSample,
+ legacy *LegacyStore,
+ budgetTokens int,
+ answerClient, judgeClient *LLMClient,
+ concurrency int,
+) []EvalResult {
+ if concurrency < 1 {
+ concurrency = 1
+ }
+ totalQA := countTotalQA(samples)
+ results := make([]EvalResult, 0, len(samples))
+
+ for si := range samples {
+ sample := &samples[si]
+ history := legacy.GetHistory(sample.SampleID)
+
+ allContent := make([]string, 0, len(history))
+ for _, msg := range history {
+ allContent = append(allContent, msg.Content)
+ }
+
+ truncated, _ := BudgetTruncate(allContent, budgetTokens)
+ contextText := StringListToContent(truncated)
+
+ qaResults := make([]QAResult, len(sample.QA))
+
+ if concurrency <= 1 {
+ for qi := range sample.QA {
+ out := evalQAWorker(ctx, qaWork{
+ sampleID: sample.SampleID, qaIndex: qi,
+ globalIndex: si*len(sample.QA) + qi + 1, totalQA: totalQA,
+ qa: &sample.QA[qi], contextText: contextText, sample: sample,
+ }, answerClient, judgeClient, "legacy-llm")
+ qaResults[qi] = out.result
+ }
+ } else {
+ sem := make(chan struct{}, concurrency)
+ var wg sync.WaitGroup
+ for qi := range sample.QA {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ sem <- struct{}{}
+ defer func() { <-sem }()
+ out := evalQAWorker(ctx, qaWork{
+ sampleID: sample.SampleID, qaIndex: qi,
+ globalIndex: si*len(sample.QA) + qi + 1, totalQA: totalQA,
+ qa: &sample.QA[qi], contextText: contextText, sample: sample,
+ }, answerClient, judgeClient, "legacy-llm")
+ qaResults[qi] = out.result // safe: each goroutine writes distinct index
+ }()
+ }
+ wg.Wait()
+ }
+
+ results = append(results, EvalResult{
+ Mode: "legacy-llm",
+ SampleID: sample.SampleID,
+ QAResults: qaResults,
+ Agg: aggregateMetrics(qaResults),
+ })
+ }
+ return results
+}
+
+// buildSeahorseContext retrieves context for a seahorse QA item.
+func buildSeahorseContext(
+ ctx context.Context,
+ ir *SeahorseIngestResult,
+ sample *LocomoSample,
+ qa *LocomoQA,
+ budgetTokens int,
+) string {
+ store := ir.Engine.GetRetrieval().Store()
+ retrieval := ir.Engine.GetRetrieval()
+ convID := ir.ConvMap[sample.SampleID]
+
+ keywords := ExtractKeywords(qa.Question)
+ bestRank := map[int64]float64{}
+ for _, kw := range keywords {
+ searchResults, err := store.SearchMessages(ctx, seahorse.SearchInput{
+ Pattern: kw,
+ ConversationID: convID,
+ Limit: 20,
+ })
+ if err != nil {
+ continue
+ }
+ for _, sr := range searchResults {
+ if sr.MessageID > 0 {
+ if prev, ok := bestRank[sr.MessageID]; !ok || sr.Rank < prev {
+ bestRank[sr.MessageID] = sr.Rank
+ }
+ }
+ }
+ }
+
+ messageIDs := make([]int64, 0, len(bestRank))
+ for id := range bestRank {
+ messageIDs = append(messageIDs, id)
+ }
+ sort.Slice(messageIDs, func(i, j int) bool {
+ return bestRank[messageIDs[i]] < bestRank[messageIDs[j]]
+ })
+
+ var contentParts []string
+ if len(messageIDs) > 0 {
+ expandResult, err := retrieval.ExpandMessages(ctx, messageIDs)
+ if err == nil {
+ for _, msg := range expandResult.Messages {
+ contentParts = append(contentParts, msg.Content)
+ }
+ }
+ }
+ if len(contentParts) == 0 {
+ return ""
+ }
+ truncated, _ := BudgetTruncate(contentParts, budgetTokens)
+ return StringListToContent(truncated)
+}
+
+// EvalSeahorseLLM evaluates seahorse retrieval using LLM generation + LLM-as-Judge.
+func EvalSeahorseLLM(
+ ctx context.Context,
+ samples []LocomoSample,
+ ir *SeahorseIngestResult,
+ budgetTokens int,
+ answerClient, judgeClient *LLMClient,
+ concurrency int,
+) []EvalResult {
+ if concurrency < 1 {
+ concurrency = 1
+ }
+ totalQA := countTotalQA(samples)
+ results := make([]EvalResult, 0, len(samples))
+
+ for si := range samples {
+ sample := &samples[si]
+ if _, ok := ir.ConvMap[sample.SampleID]; !ok {
+ log.Printf("WARN: no conversation ID for sample %s", sample.SampleID)
+ continue
+ }
+
+ qaResults := make([]QAResult, len(sample.QA))
+
+ evalOne := func(qi int) {
+ qa := &sample.QA[qi]
+ contextText := buildSeahorseContext(ctx, ir, sample, qa, budgetTokens)
+ if contextText == "" {
+ qaResults[qi] = QAResult{
+ Question: qa.Question,
+ Category: qa.Category,
+ GoldAnswer: qa.AnswerString(),
+ TokenF1: 0.0,
+ HitRate: 0.0,
+ }
+ log.Printf("[seahorse-llm] sample=%s q=%d/%d score=0.00 answer=(no context)",
+ sample.SampleID, si*len(sample.QA)+qi+1, totalQA)
+ return
+ }
+ out := evalQAWorker(ctx, qaWork{
+ sampleID: sample.SampleID, qaIndex: qi,
+ globalIndex: si*len(sample.QA) + qi + 1, totalQA: totalQA,
+ qa: qa, contextText: contextText, sample: sample,
+ }, answerClient, judgeClient, "seahorse-llm")
+ qaResults[qi] = out.result
+ }
+
+ if concurrency <= 1 {
+ for qi := range sample.QA {
+ evalOne(qi)
+ }
+ } else {
+ sem := make(chan struct{}, concurrency)
+ var wg sync.WaitGroup
+ for qi := range sample.QA {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ sem <- struct{}{}
+ defer func() { <-sem }()
+ evalOne(qi)
+ }()
+ }
+ wg.Wait()
+ }
+
+ results = append(results, EvalResult{
+ Mode: "seahorse-llm",
+ SampleID: sample.SampleID,
+ QAResults: qaResults,
+ Agg: aggregateMetrics(qaResults),
+ })
+ }
+ return results
+}
+
+func countTotalQA(samples []LocomoSample) int {
+ n := 0
+ for i := range samples {
+ n += len(samples[i].QA)
+ }
+ return n
+}
+
+func truncateStr(s string, maxLen int) string {
+ s = strings.ReplaceAll(s, "\n", " ")
+ runes := []rune(s)
+ if len(runes) > maxLen {
+ return string(runes[:maxLen]) + "..."
+ }
+ return s
+}
diff --git a/cmd/membench/eval_test.go b/cmd/membench/eval_test.go
new file mode 100644
index 000000000..32dea07c9
--- /dev/null
+++ b/cmd/membench/eval_test.go
@@ -0,0 +1,182 @@
+package main
+
+import (
+ "math"
+ "testing"
+)
+
+func TestComputeModeAggAllCategories(t *testing.T) {
+ results := []EvalResult{
+ {
+ Mode: "test",
+ SampleID: "s1",
+ QAResults: []QAResult{
+ {Category: 1, TokenF1: 0.5, HitRate: 0.8},
+ {Category: 2, TokenF1: 0.3, HitRate: 0.6},
+ {Category: 3, TokenF1: 0.1, HitRate: 0.4},
+ {Category: 4, TokenF1: 0.7, HitRate: 0.9},
+ {Category: 5, TokenF1: 0.2, HitRate: 0.1},
+ },
+ },
+ }
+ for i := range results {
+ results[i].Agg = aggregateMetrics(results[i].QAResults)
+ }
+
+ got := computeModeAgg(results)
+
+ // Should have all 5 categories
+ for cat := 1; cat <= 5; cat++ {
+ cm, ok := got.ByCategory[cat]
+ if !ok {
+ t.Errorf("ByCategory missing category %d", cat)
+ continue
+ }
+ if cm.QuestionCount != 1 {
+ t.Errorf("ByCategory[%d].QuestionCount = %d, want 1", cat, cm.QuestionCount)
+ }
+ }
+
+ // Verify specific F1 values per category
+ wantF1 := map[int]float64{1: 0.5, 2: 0.3, 3: 0.1, 4: 0.7, 5: 0.2}
+ for cat, want := range wantF1 {
+ if cm, ok := got.ByCategory[cat]; ok {
+ if math.Abs(cm.F1-want) > 1e-9 {
+ t.Errorf("ByCategory[%d].F1 = %.4f, want %.4f", cat, cm.F1, want)
+ }
+ }
+ }
+}
+
+func TestComputeModeAgg(t *testing.T) {
+ // Two samples with different question counts:
+ // sample-a: 2 questions, F1 = [0.4, 0.6] → avg 0.5
+ // sample-b: 8 questions, F1 = [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] → avg 0.1
+ //
+ // Unweighted (PrintComparison bug): (0.5 + 0.1) / 2 = 0.3
+ // Weighted (correct): (0.4+0.6 + 0.1*8) / 10 = 1.8 / 10 = 0.18
+ results := []EvalResult{
+ {
+ Mode: "test",
+ SampleID: "sample-a",
+ QAResults: []QAResult{
+ {TokenF1: 0.4, HitRate: 0.5},
+ {TokenF1: 0.6, HitRate: 0.7},
+ },
+ },
+ {
+ Mode: "test",
+ SampleID: "sample-b",
+ QAResults: []QAResult{
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ {TokenF1: 0.1, HitRate: 0.2},
+ },
+ },
+ }
+ // Compute per-sample aggregates
+ for i := range results {
+ results[i].Agg = aggregateMetrics(results[i].QAResults)
+ }
+
+ got := computeModeAgg(results)
+
+ // Weighted: (0.4+0.6+0.1*8) / 10 = 1.8/10 = 0.18
+ wantF1 := 0.18
+ if math.Abs(got.OverallF1-wantF1) > 1e-9 {
+ t.Errorf("OverallF1 = %.6f, want %.6f (weighted average)", got.OverallF1, wantF1)
+ }
+
+ // Weighted: (0.5+0.7+0.2*8) / 10 = 2.8/10 = 0.28
+ wantRecall := 0.28
+ if math.Abs(got.OverallHitRate-wantRecall) > 1e-9 {
+ t.Errorf("OverallHitRate = %.6f, want %.6f (weighted average)", got.OverallHitRate, wantRecall)
+ }
+
+ if got.TotalQuestions != 10 {
+ t.Errorf("TotalQuestions = %d, want 10", got.TotalQuestions)
+ }
+}
+
+func TestAggregateMetricsSentinel(t *testing.T) {
+ qa := []QAResult{
+ {Category: 1, TokenF1: 0.8, HitRate: 0.5},
+ {Category: 1, TokenF1: -1.0, HitRate: 0.3},
+ {Category: 1, TokenF1: 0.4, HitRate: 0.7},
+ }
+ agg := aggregateMetrics(qa)
+
+ if agg.ValidF1Count != 2 {
+ t.Errorf("ValidF1Count = %d, want 2", agg.ValidF1Count)
+ }
+ if agg.TotalQuestions != 3 {
+ t.Errorf("TotalQuestions = %d, want 3", agg.TotalQuestions)
+ }
+ wantF1 := (0.8 + 0.4) / 2.0
+ if math.Abs(agg.OverallF1-wantF1) > 1e-9 {
+ t.Errorf("OverallF1 = %.6f, want %.6f", agg.OverallF1, wantF1)
+ }
+ wantHR := (0.5 + 0.3 + 0.7) / 3.0
+ if math.Abs(agg.OverallHitRate-wantHR) > 1e-9 {
+ t.Errorf("OverallHitRate = %.6f, want %.6f", agg.OverallHitRate, wantHR)
+ }
+}
+
+func TestAggregateMetricsAllSentinel(t *testing.T) {
+ qa := []QAResult{
+ {Category: 1, TokenF1: -1.0, HitRate: 0.5},
+ {Category: 1, TokenF1: -1.0, HitRate: 0.3},
+ }
+ agg := aggregateMetrics(qa)
+
+ if agg.ValidF1Count != 0 {
+ t.Errorf("ValidF1Count = %d, want 0", agg.ValidF1Count)
+ }
+ if agg.OverallF1 != 0 {
+ t.Errorf("OverallF1 = %.6f, want 0", agg.OverallF1)
+ }
+}
+
+func TestComputeModeAggSentinelWeighting(t *testing.T) {
+ results := []EvalResult{
+ {
+ Mode: "test",
+ SampleID: "s1",
+ QAResults: []QAResult{
+ {Category: 1, TokenF1: 0.8, HitRate: 0.5},
+ {Category: 1, TokenF1: -1.0, HitRate: 0.3},
+ },
+ },
+ {
+ Mode: "test",
+ SampleID: "s2",
+ QAResults: []QAResult{
+ {Category: 1, TokenF1: 0.4, HitRate: 0.6},
+ {Category: 1, TokenF1: 0.6, HitRate: 0.8},
+ },
+ },
+ }
+ for i := range results {
+ results[i].Agg = aggregateMetrics(results[i].QAResults)
+ }
+
+ got := computeModeAgg(results)
+
+ // s1: ValidF1Count=1, F1=0.8; s2: ValidF1Count=2, F1=0.5
+ // Weighted: (0.8*1 + 0.5*2) / 3 = 1.8/3 = 0.6
+ wantF1 := 0.6
+ if math.Abs(got.OverallF1-wantF1) > 1e-9 {
+ t.Errorf("OverallF1 = %.6f, want %.6f", got.OverallF1, wantF1)
+ }
+ if got.ValidF1Count != 3 {
+ t.Errorf("ValidF1Count = %d, want 3", got.ValidF1Count)
+ }
+ if got.TotalQuestions != 4 {
+ t.Errorf("TotalQuestions = %d, want 4", got.TotalQuestions)
+ }
+}
diff --git a/cmd/membench/ingest.go b/cmd/membench/ingest.go
new file mode 100644
index 000000000..70d559c2b
--- /dev/null
+++ b/cmd/membench/ingest.go
@@ -0,0 +1,85 @@
+package main
+
+import (
+ "context"
+ "fmt"
+ "log"
+
+ "github.com/sipeed/picoclaw/pkg/seahorse"
+)
+
+// ConvMap stores the mapping from sampleID to seahorse ConversationID.
+type ConvMap map[string]int64
+
+// SeahorseIngestResult holds the results of ingesting into seahorse.
+type SeahorseIngestResult struct {
+ Engine *seahorse.Engine
+ ConvMap ConvMap // sampleID → conversationID
+}
+
+// IngestSeahorse loads all LOCOMO samples into a seahorse Engine.
+// Returns the engine and a mapping from sampleID to conversationID for scoped retrieval.
+func IngestSeahorse(ctx context.Context, samples []LocomoSample, dbPath string) (*SeahorseIngestResult, error) {
+ noopFn := func(ctx context.Context, prompt string, opts seahorse.CompleteOptions) (string, error) {
+ return "", nil
+ }
+
+ engine, err := seahorse.NewEngine(seahorse.Config{
+ DBPath: dbPath,
+ }, noopFn)
+ if err != nil {
+ return nil, fmt.Errorf("create seahorse engine: %w", err)
+ }
+
+ store := engine.GetRetrieval().Store()
+ convMap := make(ConvMap)
+
+ for si := range samples {
+ sample := &samples[si]
+ sessionKey := "locomo-" + sample.SampleID
+
+ // Check if conversation already exists (idempotent)
+ existing, _ := store.GetConversationBySessionKey(ctx, sessionKey)
+ if existing != nil {
+ convMap[sample.SampleID] = existing.ConversationID
+ log.Printf("Skipping existing sample %s: convID=%d", sample.SampleID, existing.ConversationID)
+ continue
+ }
+
+ turns := GetTurns(sample)
+
+ // Convert turns to seahorse messages
+ msgs := make([]seahorse.Message, 0, len(turns))
+ for _, turn := range turns {
+ content := turn.Speaker + ": " + turn.Text
+ msgs = append(msgs, seahorse.Message{
+ Role: "user",
+ Content: content,
+ TokenCount: len(turn.Text) / 4,
+ })
+ }
+
+ // Ingest all turns for this sample
+ _, err := engine.Ingest(ctx, sessionKey, msgs)
+ if err != nil {
+ return nil, fmt.Errorf("ingest sample %s: %w", sample.SampleID, err)
+ }
+
+ // Get the conversation ID for scoped retrieval
+ conv, err := store.GetConversationBySessionKey(ctx, sessionKey)
+ if err != nil {
+ return nil, fmt.Errorf("get conversation for %s: %w", sample.SampleID, err)
+ }
+ if conv == nil {
+ return nil, fmt.Errorf("conversation not found for %s after ingest", sample.SampleID)
+ }
+ convMap[sample.SampleID] = conv.ConversationID
+ log.Printf("Ingested sample %s: %d turns, convID=%d", sample.SampleID, len(turns), conv.ConversationID)
+ }
+
+ log.Printf("Seahorse ingestion complete: %d samples, %d conversations", len(samples), len(convMap))
+ return &SeahorseIngestResult{
+ Engine: engine,
+ ConvMap: convMap,
+ }, nil
+}
diff --git a/cmd/membench/ingest_test.go b/cmd/membench/ingest_test.go
new file mode 100644
index 000000000..e8748deed
--- /dev/null
+++ b/cmd/membench/ingest_test.go
@@ -0,0 +1,79 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "path/filepath"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/seahorse"
+)
+
+func TestIngestSeahorseIdempotent(t *testing.T) {
+ ctx := context.Background()
+ tmpDir := t.TempDir()
+ dbPath := filepath.Join(tmpDir, "test.db")
+
+ // Minimal test data
+ samples := []LocomoSample{
+ {
+ SampleID: "test-1",
+ Conversation: map[string]json.RawMessage{
+ "session_1": json.RawMessage(`[
+ {"speaker":"A","dia_id":"D1:1","text":"hello world this is a test message"},
+ {"speaker":"B","dia_id":"D1:2","text":"another message for testing purposes"}
+ ]`),
+ },
+ },
+ }
+
+ // First ingestion
+ result1, err := IngestSeahorse(ctx, samples, dbPath)
+ if err != nil {
+ t.Fatalf("first ingest failed: %v", err)
+ }
+ convCount1 := len(result1.ConvMap)
+ result1.Engine.Close()
+
+ // Second ingestion on same DB — should reuse existing data
+ result2, err := IngestSeahorse(ctx, samples, dbPath)
+ if err != nil {
+ t.Fatalf("second ingest failed: %v", err)
+ }
+ defer result2.Engine.Close()
+
+ // ConvMap should have same number of entries (no duplicates)
+ if len(result2.ConvMap) != convCount1 {
+ t.Errorf("second ingest convMap has %d entries, want %d (same as first)",
+ len(result2.ConvMap), convCount1)
+ }
+
+ // Verify conversation IDs are the same (reused, not new ones)
+ for id, cid1 := range result1.ConvMap {
+ cid2, ok := result2.ConvMap[id]
+ if !ok {
+ t.Errorf("sample %s missing from second ConvMap", id)
+ continue
+ }
+ if cid2 != cid1 {
+ t.Errorf("sample %s: second ingest got convID %d, want %d (reused)", id, cid2, cid1)
+ }
+ }
+
+ // Verify no duplicate messages by counting
+ store := result2.Engine.GetRetrieval().Store()
+ for _, convID := range result2.ConvMap {
+ msgs, err := store.SearchMessages(ctx, seahorse.SearchInput{
+ Pattern: "test",
+ ConversationID: convID,
+ Limit: 100,
+ })
+ if err != nil {
+ t.Fatalf("search failed: %v", err)
+ }
+ // Should find exactly 1 message containing "test" (the first turn)
+ if len(msgs) > 2 {
+ t.Errorf("found %d messages for 'test' in conv %d, expected ≤2 (no duplicates)", len(msgs), convID)
+ }
+ }
+}
diff --git a/cmd/membench/legacy_store.go b/cmd/membench/legacy_store.go
new file mode 100644
index 000000000..80cbd2704
--- /dev/null
+++ b/cmd/membench/legacy_store.go
@@ -0,0 +1,34 @@
+package main
+
+import (
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/session"
+)
+
+// LegacyStore wraps session.SessionManager for legacy baseline.
+type LegacyStore struct {
+ sm *session.SessionManager
+}
+
+// NewLegacyStore creates a new in-memory session manager.
+func NewLegacyStore() *LegacyStore {
+ return &LegacyStore{
+ sm: session.NewSessionManager(""),
+ }
+}
+
+// IngestSample loads all turns from a LOCOMO sample into the legacy session store.
+func (ls *LegacyStore) IngestSample(sample *LocomoSample) {
+ sessionKey := "locomo-" + sample.SampleID
+ turns := GetTurns(sample)
+ for _, turn := range turns {
+ content := turn.Speaker + ": " + turn.Text
+ ls.sm.AddMessage(sessionKey, "user", content)
+ }
+}
+
+// GetHistory returns all messages for a sample's session.
+func (ls *LegacyStore) GetHistory(sampleID string) []providers.Message {
+ sessionKey := "locomo-" + sampleID
+ return ls.sm.GetHistory(sessionKey)
+}
diff --git a/cmd/membench/llm_client.go b/cmd/membench/llm_client.go
new file mode 100644
index 000000000..6c62424da
--- /dev/null
+++ b/cmd/membench/llm_client.go
@@ -0,0 +1,198 @@
+package main
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "log"
+ "net/http"
+ "strings"
+ "time"
+)
+
+// LLMClient wraps an OpenAI-compatible chat completion endpoint.
+type LLMClient struct {
+ BaseURL string
+ Model string
+ APIKey string
+ NoThinking bool // send chat_template_kwargs to disable thinking (llama.cpp specific)
+ MaxRetries int // max retry attempts for transient errors (0 = no retry)
+ Client *http.Client
+}
+
+// LLMClientOptions configures the LLM client.
+type LLMClientOptions struct {
+ BaseURL string
+ Model string
+ APIKey string
+ Timeout time.Duration
+ NoThinking bool
+ MaxRetries int // max retry attempts (default 3)
+}
+
+// NewLLMClient creates a client for an OpenAI-compatible chat completion API.
+func NewLLMClient(opts LLMClientOptions) *LLMClient {
+ if opts.Timeout == 0 {
+ opts.Timeout = 120 * time.Second
+ }
+ maxRetries := opts.MaxRetries
+ if maxRetries < 0 {
+ maxRetries = 3
+ }
+ return &LLMClient{
+ BaseURL: strings.TrimRight(opts.BaseURL, "/"),
+ Model: opts.Model,
+ APIKey: opts.APIKey,
+ NoThinking: opts.NoThinking,
+ MaxRetries: maxRetries,
+ Client: &http.Client{
+ Timeout: opts.Timeout,
+ },
+ }
+}
+
+type chatRequest struct {
+ Model string `json:"model"`
+ Messages []chatMessage `json:"messages"`
+ Temperature float64 `json:"temperature"`
+ MaxTokens int `json:"max_tokens"`
+ ChatTemplateKwargs map[string]any `json:"chat_template_kwargs,omitempty"` // llama.cpp
+ Think *bool `json:"think,omitempty"` // Ollama
+ Thinking map[string]any `json:"thinking,omitempty"` // GLM (智谱)
+}
+
+type chatMessage struct {
+ Role string `json:"role"`
+ Content string `json:"content"`
+}
+
+type chatResponse struct {
+ Choices []struct {
+ Message struct {
+ Content string `json:"content"`
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ } `json:"message"`
+ } `json:"choices"`
+}
+
+// Complete sends a chat completion request and returns the assistant's reply.
+func (c *LLMClient) Complete(ctx context.Context, systemPrompt, userPrompt string) (string, error) {
+ sysContent := systemPrompt
+ if c.NoThinking && sysContent != "" {
+ // Prepend /no_think tag — works with Ollama /v1 endpoint and
+ // Qwen chat templates where the JSON think field is ignored.
+ sysContent = "/no_think\n" + sysContent
+ }
+ messages := []chatMessage{}
+ if sysContent != "" {
+ messages = append(messages, chatMessage{Role: "system", Content: sysContent})
+ }
+ messages = append(messages, chatMessage{Role: "user", Content: userPrompt})
+
+ body := chatRequest{
+ Model: c.Model,
+ Messages: messages,
+ Temperature: 0.1,
+ MaxTokens: 512,
+ }
+ if c.NoThinking {
+ // llama.cpp: chat_template_kwargs
+ body.ChatTemplateKwargs = map[string]any{
+ "enable_thinking": false,
+ }
+ // Ollama (0.9+): think field
+ thinkFalse := false
+ body.Think = &thinkFalse
+ // GLM (智谱): thinking field
+ body.Thinking = map[string]any{
+ "type": "disabled",
+ }
+ }
+
+ jsonBody, err := json.Marshal(body)
+ if err != nil {
+ return "", fmt.Errorf("marshal request: %w", err)
+ }
+
+ endpoint := strings.TrimRight(c.BaseURL, "/") + "/chat/completions"
+ req, err := http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewReader(jsonBody))
+ if err != nil {
+ return "", fmt.Errorf("create request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ if c.APIKey != "" {
+ req.Header.Set("Authorization", "Bearer "+c.APIKey)
+ }
+
+ var respBody []byte
+ var lastErr error
+ for attempt := 0; attempt <= c.MaxRetries; attempt++ {
+ if attempt > 0 {
+ backoff := time.Duration(1<<(attempt-1)) * time.Second // 1s, 2s, 4s, ...
+ log.Printf("LLM retry %d/%d after %v: %v", attempt, c.MaxRetries, backoff, lastErr)
+ select {
+ case <-ctx.Done():
+ return "", ctx.Err()
+ case <-time.After(backoff):
+ }
+ // Rebuild request (body reader is consumed)
+ req, err = http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewReader(jsonBody))
+ if err != nil {
+ return "", fmt.Errorf("create request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ if c.APIKey != "" {
+ req.Header.Set("Authorization", "Bearer "+c.APIKey)
+ }
+ }
+
+ var resp *http.Response
+ resp, lastErr = c.Client.Do(req)
+ if lastErr != nil {
+ continue // network/timeout error → retry
+ }
+
+ respBody, lastErr = io.ReadAll(resp.Body)
+ resp.Body.Close()
+ if lastErr != nil {
+ continue
+ }
+
+ if resp.StatusCode == 429 || resp.StatusCode >= 500 {
+ lastErr = fmt.Errorf("API error %d: %s", resp.StatusCode, string(respBody))
+ continue // rate limit or server error → retry
+ }
+ if resp.StatusCode != 200 {
+ return "", fmt.Errorf("API error %d: %s", resp.StatusCode, string(respBody))
+ }
+
+ lastErr = nil
+ break
+ }
+ if lastErr != nil {
+ return "", fmt.Errorf("after %d retries: %w", c.MaxRetries, lastErr)
+ }
+
+ var chatResp chatResponse
+ if err := json.Unmarshal(respBody, &chatResp); err != nil {
+ return "", fmt.Errorf("parse response: %w", err)
+ }
+ if len(chatResp.Choices) == 0 {
+ return "", fmt.Errorf("no choices in response")
+ }
+ content := strings.TrimSpace(chatResp.Choices[0].Message.Content)
+ // Strip any residual 
+ 
+
+
+
+
+ 
-SipeedIO-black?style=flat&logo=x&logoColor=white){kind=icon}
- 
+ 
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> **[Liste de compatibilité matérielle](docs/fr/hardware-compatibility.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR !
+> **[Liste de compatibilité matérielle](../guides/hardware-compatibility.fr.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR !
-
+
Recherche Web & Apprentissage
-
+
-
+
-
+
-
+
 |
-  |
-  |
-  |
+  |
+  |
+  |
+  |
+
Pour les environnements minimaux où seul le binaire principal `picoclaw` est disponible (sans Launcher UI), vous pouvez tout configurer via la ligne de commande et un fichier de configuration JSON.
@@ -446,7 +455,7 @@ PicoClaw supporte plus de 30 providers LLM via la configuration `model_list`. Ut
}
```
-Pour les détails complets de configuration des providers, voir [Providers & Models](docs/fr/providers.md).
+Pour les détails complets de configuration des providers, voir [Providers & Models](../guides/providers.fr.md).
@@ -456,28 +465,28 @@ Parlez à votre PicoClaw via plus de 17 plateformes de messagerie :
| Channel | Configuration | Protocole | Docs |
|---------|---------------|-----------|------|
-| **Telegram** | Facile (token bot) | Long polling | [Guide](docs/channels/telegram/README.fr.md) |
-| **Discord** | Facile (token bot + intents) | WebSocket | [Guide](docs/channels/discord/README.fr.md) |
-| **WhatsApp** | Facile (scan QR ou URL bridge) | Natif / Bridge | [Guide](docs/fr/chat-apps.md#whatsapp) |
-| **Weixin** | Facile (scan QR natif) | iLink API | [Guide](docs/fr/chat-apps.md#weixin) |
-| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.fr.md) |
-| **Slack** | Facile (token bot + app) | Socket Mode | [Guide](docs/channels/slack/README.fr.md) |
-| **Matrix** | Moyen (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.fr.md) |
-| **DingTalk** | Moyen (identifiants client) | Stream | [Guide](docs/channels/dingtalk/README.fr.md) |
-| **Feishu / Lark** | Moyen (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.fr.md) |
-| **LINE** | Moyen (identifiants + webhook) | Webhook | [Guide](docs/channels/line/README.fr.md) |
-| **WeCom** | Facile (QR login ou manuel) | WebSocket | [Guide](docs/channels/wecom/README.md) |
-| **IRC** | Moyen (serveur + pseudo) | Protocole IRC | [Guide](docs/fr/chat-apps.md#irc) |
-| **OneBot** | Moyen (URL WebSocket) | OneBot v11 | [Guide](docs/channels/onebot/README.fr.md) |
-| **MaixCam** | Facile (activer) | Socket TCP | [Guide](docs/channels/maixcam/README.fr.md) |
+| **Telegram** | Facile (token bot) | Long polling | [Guide](../channels/telegram/README.fr.md) |
+| **Discord** | Facile (token bot + intents) | WebSocket | [Guide](../channels/discord/README.fr.md) |
+| **WhatsApp** | Facile (scan QR ou URL bridge) | Natif / Bridge | [Guide](../guides/chat-apps.fr.md#whatsapp) |
+| **Weixin** | Facile (scan QR natif) | iLink API | [Guide](../guides/chat-apps.fr.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guide](../channels/qq/README.fr.md) |
+| **Slack** | Facile (token bot + app) | Socket Mode | [Guide](../channels/slack/README.fr.md) |
+| **Matrix** | Moyen (homeserver + token) | Sync API | [Guide](../channels/matrix/README.fr.md) |
+| **DingTalk** | Moyen (identifiants client) | Stream | [Guide](../channels/dingtalk/README.fr.md) |
+| **Feishu / Lark** | Moyen (App ID + Secret) | WebSocket/SDK | [Guide](../channels/feishu/README.fr.md) |
+| **LINE** | Moyen (identifiants + webhook) | Webhook | [Guide](../channels/line/README.fr.md) |
+| **WeCom** | Facile (QR login ou manuel) | WebSocket | [Guide](../channels/wecom/README.fr.md) |
+| **IRC** | Moyen (serveur + pseudo) | Protocole IRC | [Guide](../guides/chat-apps.fr.md#irc) |
+| **OneBot** | Moyen (URL WebSocket) | OneBot v11 | [Guide](../channels/onebot/README.fr.md) |
+| **MaixCam** | Facile (activer) | Socket TCP | [Guide](../channels/maixcam/README.fr.md) |
| **Pico** | Facile (activer) | Protocole natif | Intégré |
| **Pico Client** | Facile (URL WebSocket) | WebSocket | Intégré |
> Tous les channels basés sur webhook partagent un seul serveur HTTP Gateway (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP partagé.
-> La verbosité des logs est contrôlée par `gateway.log_level` (par défaut : `warn`). Valeurs supportées : `debug`, `info`, `warn`, `error`, `fatal`. Peut aussi être défini via `PICOCLAW_LOG_LEVEL`. Voir [Configuration](docs/fr/configuration.md#niveau-de-log-du-gateway) pour plus de détails.
+> La verbosité des logs est contrôlée par `gateway.log_level` (par défaut : `warn`). Valeurs supportées : `debug`, `info`, `warn`, `error`, `fatal`. Peut aussi être défini via `PICOCLAW_LOG_LEVEL`. Voir [Configuration](../guides/configuration.fr.md#niveau-de-log-du-gateway) pour plus de détails.
-Pour les instructions détaillées de configuration des channels, voir [Configuration des applications de chat](docs/fr/chat-apps.md).
+Pour les instructions détaillées de configuration des channels, voir [Configuration des applications de chat](../guides/chat-apps.fr.md).
## 🔧 Outils
@@ -497,7 +506,7 @@ PicoClaw peut effectuer des recherches sur le web pour fournir des informations
### ⚙️ Autres outils
-PicoClaw inclut des outils intégrés pour les opérations sur fichiers, l'exécution de code, la planification et plus encore. Voir [Configuration des outils](docs/fr/tools_configuration.md) pour les détails.
+PicoClaw inclut des outils intégrés pour les opérations sur fichiers, l'exécution de code, la planification et plus encore. Voir [Configuration des outils](../reference/tools_configuration.fr.md) pour les détails.
## 🎯 Skills
@@ -527,7 +536,7 @@ Ajoutez à votre `config.json` :
}
```
-Pour plus de détails, voir [Configuration des outils - Skills](docs/fr/tools_configuration.md#skills-tool).
+Pour plus de détails, voir [Configuration des outils - Skills](../reference/tools_configuration.fr.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -550,9 +559,9 @@ PicoClaw supporte nativement [MCP](https://modelcontextprotocol.io/) — connect
}
```
-Pour la configuration MCP complète (transports stdio, SSE, HTTP, Tool Discovery), voir [Configuration des outils - MCP](docs/fr/tools_configuration.md#mcp-tool).
+Pour la configuration MCP complète (transports stdio, SSE, HTTP, Tool Discovery), voir [Configuration des outils - MCP](../reference/tools_configuration.fr.md#mcp-tool).
-## Rejoignez le réseau social des Agents
+## 
Rejoignez le réseau social des Agents
Connectez PicoClaw au réseau social des Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
@@ -593,23 +602,23 @@ Pour des guides détaillés au-delà de ce README :
| Sujet | Description |
|-------|-------------|
-| [Docker & Démarrage rapide](docs/fr/docker.md) | Configuration Docker Compose, modes Launcher/Agent |
-| [Applications de chat](docs/fr/chat-apps.md) | Guides de configuration pour les 17+ channels |
-| [Configuration](docs/fr/configuration.md) | Variables d'environnement, structure du workspace, sandbox de sécurité |
-| [Providers & Modèles](docs/fr/providers.md) | 30+ providers LLM, routage de modèles, configuration model_list |
-| [Spawn & Tâches asynchrones](docs/fr/spawn-tasks.md) | Tâches rapides, tâches longues avec spawn, orchestration de sous-agents asynchrones |
-| [Hooks](docs/hooks/README.md) | Système de hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
-| [Steering](docs/steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
-| [SubTurn](docs/subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
-| [Dépannage](docs/fr/troubleshooting.md) | Problèmes courants et solutions |
-| [Configuration des outils](docs/fr/tools_configuration.md) | Activation/désactivation par outil, politiques d'exécution, MCP, Skills |
-| [Compatibilité matérielle](docs/fr/hardware-compatibility.md) | Cartes testées, exigences minimales |
+| [Docker & Démarrage rapide](../guides/docker.fr.md) | Configuration Docker Compose, modes Launcher/Agent |
+| [Applications de chat](../guides/chat-apps.fr.md) | Guides de configuration pour les 17+ channels |
+| [Configuration](../guides/configuration.fr.md) | Variables d'environnement, structure du workspace, sandbox de sécurité |
+| [Providers & Modèles](../guides/providers.fr.md) | 30+ providers LLM, routage de modèles, configuration model_list |
+| [Spawn & Tâches asynchrones](../guides/spawn-tasks.fr.md) | Tâches rapides, tâches longues avec spawn, orchestration de sous-agents asynchrones |
+| [Hooks](../architecture/hooks/README.md) | Système de hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
+| [Steering](../architecture/steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
+| [SubTurn](../architecture/subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
+| [Dépannage](../operations/troubleshooting.fr.md) | Problèmes courants et solutions |
+| [Configuration des outils](../reference/tools_configuration.fr.md) | Activation/désactivation par outil, politiques d'exécution, MCP, Skills |
+| [Compatibilité matérielle](../guides/hardware-compatibility.fr.md) | Cartes testées, exigences minimales |
## 🤝 Contribuer & Roadmap
Les PRs sont les bienvenues ! Le code source est intentionnellement petit et lisible.
-Consultez notre [Roadmap communautaire](https://github.com/sipeed/picoclaw/issues/988) et [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives.
+Consultez notre [Roadmap communautaire](https://github.com/sipeed/picoclaw/issues/988) et [CONTRIBUTING.md](../../CONTRIBUTING.md) pour les directives.
Groupe de développeurs en construction, rejoignez-le après votre première PR fusionnée !
@@ -618,8 +627,4 @@ Groupes d'utilisateurs :
Discord : 
-
-
-
-
+
diff --git a/README.id.md b/docs/project/README.id.md
similarity index 81%
rename from README.id.md
rename to docs/project/README.id.md
index d3c556dde..244e6e49a 100644
--- a/README.id.md
+++ b/docs/project/README.id.md
@@ -1,5 +1,5 @@
+
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Malay](README.my.md) | [English](README.md) | **Bahasa Indonesia**
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | **Bahasa Indonesia** | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> **[Daftar Kompatibilitas Hardware](docs/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR!
+> **[Daftar Kompatibilitas Hardware](../guides/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR!
-
+
Pencarian Web & Pembelajaran
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
Untuk lingkungan minimal di mana hanya binary inti `picoclaw` yang tersedia (tanpa Launcher UI), Anda dapat mengonfigurasi semuanya melalui command line dan file konfigurasi JSON.
@@ -442,7 +450,7 @@ PicoClaw mendukung 30+ provider LLM melalui konfigurasi `model_list`. Gunakan fo
}
```
-Untuk detail konfigurasi provider lengkap, lihat [Providers & Models](docs/providers.md).
+Untuk detail konfigurasi provider lengkap, lihat [Providers & Models](../guides/providers.md).
@@ -452,28 +460,28 @@ Bicara dengan PicoClaw Anda melalui 17+ platform pesan:
| Channel | Pengaturan | Protocol | Dokumentasi |
|---------|------------|----------|-------------|
-| **Telegram** | Mudah (bot token) | Long polling | [Panduan](docs/channels/telegram/README.md) |
-| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) |
-| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](docs/chat-apps.md#weixin) |
-| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) |
-| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](docs/channels/slack/README.md) |
-| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) |
-| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) |
-| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](docs/channels/line/README.md) |
-| **WeCom** | Mudah (login QR atau manual) | WebSocket | [Panduan](docs/channels/wecom/README.md) |
-| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](docs/chat-apps.md#irc) |
-| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) |
-| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) |
+| **Telegram** | Mudah (bot token) | Long polling | [Panduan](../channels/telegram/README.md) |
+| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](../channels/discord/README.md) |
+| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](../guides/chat-apps.md#whatsapp) |
+| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](../guides/chat-apps.md#weixin) |
+| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](../channels/qq/README.md) |
+| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](../channels/slack/README.md) |
+| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](../channels/matrix/README.md) |
+| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](../channels/feishu/README.md) |
+| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](../channels/line/README.md) |
+| **WeCom** | Mudah (login QR atau manual) | WebSocket | [Panduan](../channels/wecom/README.md) |
+| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](../guides/chat-apps.md#irc) |
+| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](../channels/onebot/README.md) |
+| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](../channels/maixcam/README.md) |
| **Pico** | Mudah (aktifkan) | Native protocol | Bawaan |
| **Pico Client** | Mudah (WebSocket URL) | WebSocket | Bawaan |
> Semua channel berbasis webhook berbagi satu server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu menggunakan mode WebSocket/SDK dan tidak menggunakan server HTTP bersama.
-> Verbositas log dikontrol oleh `gateway.log_level` (default: `warn`). Nilai yang didukung: `debug`, `info`, `warn`, `error`, `fatal`. Juga dapat diatur melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](docs/configuration.md#gateway-log-level) untuk detail.
+> Verbositas log dikontrol oleh `gateway.log_level` (default: `warn`). Nilai yang didukung: `debug`, `info`, `warn`, `error`, `fatal`. Juga dapat diatur melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](../guides/configuration.md#gateway-log-level) untuk detail.
-Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](docs/chat-apps.md).
+Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](../guides/chat-apps.md).
## 🔧 Tools
@@ -493,7 +501,7 @@ PicoClaw dapat mencari web untuk memberikan informasi terkini. Konfigurasi di `t
### ⚙️ Tools Lainnya
-PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](docs/tools_configuration.md) untuk detail.
+PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](../reference/tools_configuration.md) untuk detail.
## 🎯 Skills
@@ -523,7 +531,7 @@ Tambahkan ke `config.json` Anda:
}
```
-Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](docs/tools_configuration.md#skills-tool).
+Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](../reference/tools_configuration.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -546,9 +554,9 @@ PicoClaw mendukung [MCP](https://modelcontextprotocol.io/) secara native — hub
}
```
-Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](docs/tools_configuration.md#mcp-tool).
+Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](../reference/tools_configuration.md#mcp-tool).
-## Bergabung dengan Jaringan Sosial Agent
+## Bergabung dengan Jaringan Sosial Agent
Hubungkan PicoClaw ke Jaringan Sosial Agent hanya dengan mengirim satu pesan melalui CLI atau Aplikasi Chat terintegrasi mana pun.
@@ -589,23 +597,23 @@ Untuk panduan lengkap di luar README ini:
| Topik | Deskripsi |
|-------|-----------|
-| [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent |
-| [Aplikasi Chat](docs/chat-apps.md) | Semua 17+ panduan pengaturan channel |
-| [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sandbox keamanan |
-| [Providers & Models](docs/providers.md) | 30+ provider LLM, routing model, konfigurasi model_list |
-| [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
-| [Hooks](docs/hooks/README.md) | Sistem hook berbasis event: observer, interceptor, approval hook |
-| [Steering](docs/steering.md) | Menyuntikkan pesan ke dalam loop agent yang sedang berjalan |
-| [SubTurn](docs/subturn.md) | Koordinasi subagent, kontrol konkurensi, siklus hidup |
-| [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya |
-| [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan per-tool, kebijakan exec, MCP, Skills |
-| [Kompatibilitas Hardware](docs/hardware-compatibility.md) | Board yang telah diuji, persyaratan minimum |
+| [Docker & Panduan Cepat](../guides/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent |
+| [Aplikasi Chat](../guides/chat-apps.md) | Semua 17+ panduan pengaturan channel |
+| [Konfigurasi](../guides/configuration.md) | Variabel environment, tata letak workspace, sandbox keamanan |
+| [Providers & Models](../guides/providers.md) | 30+ provider LLM, routing model, konfigurasi model_list |
+| [Spawn & Tugas Async](../guides/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
+| [Hooks](../architecture/hooks/README.md) | Sistem hook berbasis event: observer, interceptor, approval hook |
+| [Steering](../architecture/steering.md) | Menyuntikkan pesan ke dalam loop agent yang sedang berjalan |
+| [SubTurn](../architecture/subturn.md) | Koordinasi subagent, kontrol konkurensi, siklus hidup |
+| [Pemecahan Masalah](../operations/troubleshooting.md) | Masalah umum dan solusinya |
+| [Konfigurasi Tools](../reference/tools_configuration.md) | Aktifkan/nonaktifkan per-tool, kebijakan exec, MCP, Skills |
+| [Kompatibilitas Hardware](../guides/hardware-compatibility.md) | Board yang telah diuji, persyaratan minimum |
## 🤝 Kontribusi & Roadmap
PR sangat diterima! Codebase sengaja dibuat kecil dan mudah dibaca.
-Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan.
+Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](../../CONTRIBUTING.md) untuk panduan.
Grup pengembang sedang dibangun, bergabunglah setelah PR pertama Anda di-merge!
@@ -614,5 +622,4 @@ Grup Pengguna:
Discord:
-
+
diff --git a/README.it.md b/docs/project/README.it.md
similarity index 81%
rename from README.it.md
rename to docs/project/README.it.md
index 6fe6c5e17..eb2f7c95b 100644
--- a/README.it.md
+++ b/docs/project/README.it.md
@@ -1,5 +1,5 @@
+
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> **[Lista di Compatibilità Hardware](docs/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR!
+> **[Lista di Compatibilità Hardware](../guides/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR!
-
+
Ricerca Web & Apprendimento
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
Per ambienti minimali dove è disponibile solo il binario core `picoclaw` (senza Launcher UI), puoi configurare tutto tramite riga di comando e un file di configurazione JSON.
@@ -442,7 +450,7 @@ PicoClaw supporta 30+ provider LLM tramite la configurazione `model_list`. Usa i
}
```
-Per i dettagli completi sulla configurazione dei provider, vedi [Provider & Modelli](docs/providers.md).
+Per i dettagli completi sulla configurazione dei provider, vedi [Provider & Modelli](../guides/providers.md).
@@ -452,28 +460,28 @@ Parla con il tuo PicoClaw attraverso 17+ piattaforme di messaggistica:
| Channel | Configurazione | Protocollo | Docs |
|---------|----------------|------------|------|
-| **Telegram** | Facile (bot token) | Long polling | [Guida](docs/channels/telegram/README.md) |
-| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](docs/channels/discord/README.md) |
-| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](docs/chat-apps.md#weixin) |
-| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](docs/channels/qq/README.md) |
-| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](docs/channels/slack/README.md) |
-| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](docs/channels/matrix/README.md) |
-| **DingTalk** | Medio (credenziali client) | Stream | [Guida](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](docs/channels/feishu/README.md) |
-| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](docs/channels/line/README.md) |
-| **WeCom** | Facile (login QR o manuale) | WebSocket | [Guida](docs/channels/wecom/README.md) |
-| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](docs/chat-apps.md#irc) |
-| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](docs/channels/onebot/README.md) |
-| **MaixCam** | Facile (abilita) | TCP socket | [Guida](docs/channels/maixcam/README.md) |
+| **Telegram** | Facile (bot token) | Long polling | [Guida](../channels/telegram/README.md) |
+| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](../channels/discord/README.md) |
+| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](../guides/chat-apps.md#whatsapp) |
+| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](../guides/chat-apps.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](../channels/qq/README.md) |
+| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](../channels/slack/README.md) |
+| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](../channels/matrix/README.md) |
+| **DingTalk** | Medio (credenziali client) | Stream | [Guida](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](../channels/feishu/README.md) |
+| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](../channels/line/README.md) |
+| **WeCom** | Facile (login QR o manuale) | WebSocket | [Guida](../channels/wecom/README.md) |
+| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](../guides/chat-apps.md#irc) |
+| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](../channels/onebot/README.md) |
+| **MaixCam** | Facile (abilita) | TCP socket | [Guida](../channels/maixcam/README.md) |
| **Pico** | Facile (abilita) | Protocollo nativo | Integrato |
| **Pico Client** | Facile (WebSocket URL) | WebSocket | Integrato |
> Tutti i channel basati su webhook condividono un singolo server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu usa la modalità WebSocket/SDK e non usa il server HTTP condiviso.
-> La verbosità dei log è controllata da `gateway.log_level` (default: `warn`). Valori supportati: `debug`, `info`, `warn`, `error`, `fatal`. Può essere impostato anche tramite `PICOCLAW_LOG_LEVEL`. Vedi [Configurazione](docs/configuration.md#gateway-log-level) per i dettagli.
+> La verbosità dei log è controllata da `gateway.log_level` (default: `warn`). Valori supportati: `debug`, `info`, `warn`, `error`, `fatal`. Può essere impostato anche tramite `PICOCLAW_LOG_LEVEL`. Vedi [Configurazione](../guides/configuration.md#gateway-log-level) per i dettagli.
-Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](docs/chat-apps.md).
+Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](../guides/chat-apps.md).
## 🔧 Strumenti
@@ -493,7 +501,7 @@ PicoClaw può cercare sul web per fornire informazioni aggiornate. Configura in
### ⚙️ Altri Strumenti
-PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](docs/tools_configuration.md) per i dettagli.
+PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](../reference/tools_configuration.md) per i dettagli.
## 🎯 Skill
@@ -523,7 +531,7 @@ Aggiungi al tuo `config.json`:
}
```
-Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](docs/tools_configuration.md#skills-tool).
+Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](../reference/tools_configuration.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -546,9 +554,9 @@ PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connet
}
```
-Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](docs/tools_configuration.md#mcp-tool).
+Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](../reference/tools_configuration.md#mcp-tool).
-## Unisciti al Social Network degli Agent
+## Unisciti al Social Network degli Agent
Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singolo messaggio tramite CLI o qualsiasi app di chat integrata.
@@ -589,23 +597,23 @@ Per guide dettagliate oltre questo README:
| Argomento | Descrizione |
|-----------|-------------|
-| [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
-| [App di Chat](docs/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
-| [Configurazione](docs/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
-| [Provider & Modelli](docs/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
-| [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
-| [Hooks](docs/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |
-| [Steering](docs/steering.md) | Iniettare messaggi in un loop agent in esecuzione |
-| [SubTurn](docs/subturn.md) | Coordinamento subagent, controllo concorrenza, ciclo di vita |
-| [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni |
-| [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec, MCP, Skill |
-| [Compatibilità Hardware](docs/hardware-compatibility.md) | Schede testate, requisiti minimi |
+| [Docker & Avvio Rapido](../guides/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
+| [App di Chat](../guides/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
+| [Configurazione](../guides/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
+| [Provider & Modelli](../guides/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
+| [Spawn & Task Asincroni](../guides/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
+| [Hooks](../architecture/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |
+| [Steering](../architecture/steering.md) | Iniettare messaggi in un loop agent in esecuzione |
+| [SubTurn](../architecture/subturn.md) | Coordinamento subagent, controllo concorrenza, ciclo di vita |
+| [Risoluzione Problemi](../operations/troubleshooting.md) | Problemi comuni e soluzioni |
+| [Configurazione degli Strumenti](../reference/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec, MCP, Skill |
+| [Compatibilità Hardware](../guides/hardware-compatibility.md) | Schede testate, requisiti minimi |
## 🤝 Contribuisci & Roadmap
Le PR sono benvenute! Il codice è volutamente piccolo e leggibile.
-Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida.
+Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](../../CONTRIBUTING.md) per le linee guida.
Gruppo sviluppatori in costruzione, unisciti dopo la tua prima PR accettata!
@@ -614,4 +622,4 @@ Gruppi utenti:
Discord:
+
diff --git a/README.ja.md b/docs/project/README.ja.md
similarity index 82%
rename from README.ja.md
rename to docs/project/README.ja.md
index 793c41fcb..66d06ba5e 100644
--- a/README.ja.md
+++ b/docs/project/README.ja.md
@@ -1,5 +1,5 @@
+
-
+
-[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | **日本語** | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> **[ハードウェア互換性リスト](docs/ja/hardware-compatibility.md)** — テスト済みの全ボード一覧（$5 RISC-V から Raspberry Pi、Android スマートフォンまで）。お使いのボードが未掲載？PR を送ってください！
+> **[ハードウェア互換性リスト](../guides/hardware-compatibility.ja.md)** — テスト済みの全ボード一覧（$5 RISC-V から Raspberry Pi、Android スマートフォンまで）。お使いのボードが未掲載？PR を送ってください！
-
+
Web 検索＆学習
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
`picoclaw` コアバイナリのみが利用可能な最小環境（Launcher UI なし）では、コマンドラインと JSON 設定ファイルですべてを設定できます。
@@ -442,7 +451,7 @@ PicoClaw は `model_list` 設定を通じて 30 以上の LLM Provider をサポ
}
```
-Provider の完全な設定詳細は [Provider とモデル](docs/ja/providers.md) を参照してください。
+Provider の完全な設定詳細は [Provider とモデル](../guides/providers.ja.md) を参照してください。
@@ -452,28 +461,28 @@ Provider の完全な設定詳細は [Provider とモデル](docs/ja/providers.m
| Channel | セットアップ | Protocol | ドキュメント |
|---------|------------|----------|------------|
-| **Telegram** | 簡単（bot トークン） | Long polling | [ガイド](docs/channels/telegram/README.ja.md) |
-| **Discord** | 簡単（bot トークン + intents） | WebSocket | [ガイド](docs/channels/discord/README.ja.md) |
-| **WhatsApp** | 簡単（QR スキャンまたは bridge URL） | Native / Bridge | [ガイド](docs/ja/chat-apps.md#whatsapp) |
-| **微信 (Weixin)** | 簡単（QR スキャン） | iLink API | [ガイド](docs/ja/chat-apps.md#weixin) |
-| **QQ** | 簡単（AppID + AppSecret） | WebSocket | [ガイド](docs/channels/qq/README.ja.md) |
-| **Slack** | 簡単（bot + app トークン） | Socket Mode | [ガイド](docs/channels/slack/README.ja.md) |
-| **Matrix** | 中級（homeserver + トークン） | Sync API | [ガイド](docs/channels/matrix/README.ja.md) |
-| **DingTalk** | 中級（クライアント認証情報） | Stream | [ガイド](docs/channels/dingtalk/README.ja.md) |
-| **Feishu / Lark** | 中級（App ID + Secret） | WebSocket/SDK | [ガイド](docs/channels/feishu/README.ja.md) |
-| **LINE** | 中級（認証情報 + webhook） | Webhook | [ガイド](docs/channels/line/README.ja.md) |
-| **WeCom** | 簡単（QR ログインまたは手動） | WebSocket | [ガイド](docs/channels/wecom/README.md) |
-| **IRC** | 中級（サーバー + nick） | IRC protocol | [ガイド](docs/ja/chat-apps.md#irc) |
-| **OneBot** | 中級（WebSocket URL） | OneBot v11 | [ガイド](docs/channels/onebot/README.ja.md) |
-| **MaixCam** | 簡単（有効化） | TCP socket | [ガイド](docs/channels/maixcam/README.ja.md) |
+| **Telegram** | 簡単（bot トークン） | Long polling | [ガイド](../channels/telegram/README.ja.md) |
+| **Discord** | 簡単（bot トークン + intents） | WebSocket | [ガイド](../channels/discord/README.ja.md) |
+| **WhatsApp** | 簡単（QR スキャンまたは bridge URL） | Native / Bridge | [ガイド](../guides/chat-apps.ja.md#whatsapp) |
+| **微信 (Weixin)** | 簡単（QR スキャン） | iLink API | [ガイド](../guides/chat-apps.ja.md#weixin) |
+| **QQ** | 簡単（AppID + AppSecret） | WebSocket | [ガイド](../channels/qq/README.ja.md) |
+| **Slack** | 簡単（bot + app トークン） | Socket Mode | [ガイド](../channels/slack/README.ja.md) |
+| **Matrix** | 中級（homeserver + トークン） | Sync API | [ガイド](../channels/matrix/README.ja.md) |
+| **DingTalk** | 中級（クライアント認証情報） | Stream | [ガイド](../channels/dingtalk/README.ja.md) |
+| **Feishu / Lark** | 中級（App ID + Secret） | WebSocket/SDK | [ガイド](../channels/feishu/README.ja.md) |
+| **LINE** | 中級（認証情報 + webhook） | Webhook | [ガイド](../channels/line/README.ja.md) |
+| **WeCom** | 簡単（QR ログインまたは手動） | WebSocket | [ガイド](../channels/wecom/README.ja.md) |
+| **IRC** | 中級（サーバー + nick） | IRC protocol | [ガイド](../guides/chat-apps.ja.md#irc) |
+| **OneBot** | 中級（WebSocket URL） | OneBot v11 | [ガイド](../channels/onebot/README.ja.md) |
+| **MaixCam** | 簡単（有効化） | TCP socket | [ガイド](../channels/maixcam/README.ja.md) |
| **Pico** | 簡単（有効化） | Native protocol | 内蔵 |
| **Pico Client** | 簡単（WebSocket URL） | WebSocket | 内蔵 |
> webhook ベースのすべての Channel は単一の Gateway HTTP サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）を共有します。Feishu は WebSocket/SDK モードを使用し、共有 HTTP サーバーを使用しません。
-> ログの詳細度は `gateway.log_level` で制御します（デフォルト：`warn`）。サポートされる値：`debug`、`info`、`warn`、`error`、`fatal`。`PICOCLAW_LOG_LEVEL` 環境変数でも設定可能です。詳細は[設定ガイド](docs/ja/configuration.md#gateway-ログレベル)を参照してください。
+> ログの詳細度は `gateway.log_level` で制御します（デフォルト：`warn`）。サポートされる値：`debug`、`info`、`warn`、`error`、`fatal`。`PICOCLAW_LOG_LEVEL` 環境変数でも設定可能です。詳細は[設定ガイド](../guides/configuration.ja.md#gateway-ログレベル)を参照してください。
-Channel の詳細なセットアップ手順は [チャットアプリ設定](docs/ja/chat-apps.md) を参照してください。
+Channel の詳細なセットアップ手順は [チャットアプリ設定](../guides/chat-apps.ja.md) を参照してください。
## 🔧 ツール
@@ -493,7 +502,7 @@ PicoClaw は最新情報を提供するために Web を検索できます。`to
### ⚙️ その他のツール
-PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](docs/ja/tools_configuration.md) を参照してください。
+PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](../reference/tools_configuration.ja.md) を参照してください。
## 🎯 Skill
@@ -523,7 +532,7 @@ picoclaw skills install エージェントソーシャルネットワークに参加
+## エージェントソーシャルネットワークに参加
CLI または統合チャットアプリからメッセージを 1 つ送るだけで、PicoClaw をエージェントソーシャルネットワークに接続できます。
@@ -589,23 +598,23 @@ PicoClaw は `cron` ツールによるスケジュールリマインダーと定
| トピック | 説明 |
|---------|------|
-| [Docker & クイックスタート](docs/ja/docker.md) | Docker Compose セットアップ、Launcher/Agent モード |
-| [チャットアプリ](docs/ja/chat-apps.md) | 17 以上の Channel セットアップガイド |
-| [設定](docs/ja/configuration.md) | 環境変数、ワークスペース構成、セキュリティサンドボックス |
-| [Provider とモデル](docs/ja/providers.md) | 30 以上の LLM Provider、モデルルーティング、model_list 設定 |
-| [Spawn & 非同期タスク](docs/ja/spawn-tasks.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション |
-| [Hook システム](docs/hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
-| [Steering](docs/steering.md) | 実行中の Agent ループにメッセージを注入 |
-| [SubTurn](docs/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
-| [トラブルシューティング](docs/ja/troubleshooting.md) | よくある問題と解決策 |
-| [ツール設定](docs/ja/tools_configuration.md) | ツールごとの有効/無効、exec ポリシー、MCP、Skill |
-| [ハードウェア互換性](docs/ja/hardware-compatibility.md) | テスト済みボード、最小要件 |
+| [Docker & クイックスタート](../guides/docker.ja.md) | Docker Compose セットアップ、Launcher/Agent モード |
+| [チャットアプリ](../guides/chat-apps.ja.md) | 17 以上の Channel セットアップガイド |
+| [設定](../guides/configuration.ja.md) | 環境変数、ワークスペース構成、セキュリティサンドボックス |
+| [Provider とモデル](../guides/providers.ja.md) | 30 以上の LLM Provider、モデルルーティング、model_list 設定 |
+| [Spawn & 非同期タスク](../guides/spawn-tasks.ja.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション |
+| [Hook システム](../architecture/hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
+| [Steering](../architecture/steering.md) | 実行中の Agent ループにメッセージを注入 |
+| [SubTurn](../architecture/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
+| [トラブルシューティング](../operations/troubleshooting.ja.md) | よくある問題と解決策 |
+| [ツール設定](../reference/tools_configuration.ja.md) | ツールごとの有効/無効、exec ポリシー、MCP、Skill |
+| [ハードウェア互換性](../guides/hardware-compatibility.ja.md) | テスト済みボード、最小要件 |
## 🤝 コントリビュート＆ロードマップ
PR 歓迎！コードベースは意図的に小さく読みやすくしています。
-[コミュニティロードマップ](https://github.com/sipeed/picoclaw/issues/988)と[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
+[コミュニティロードマップ](https://github.com/sipeed/picoclaw/issues/988)と[CONTRIBUTING.md](../../CONTRIBUTING.md)をご覧ください。
開発者グループ構築中、最初の PR がマージされたら参加できます！
@@ -614,4 +623,4 @@ PR 歓迎！コードベースは意図的に小さく読みやすくしてい
Discord:
+
diff --git a/docs/project/README.ko.md b/docs/project/README.ko.md
new file mode 100644
index 000000000..cfc985688
--- /dev/null
+++ b/docs/project/README.ko.md
@@ -0,0 +1,634 @@
+
+
+
+ 
+ 
+
|
+
+ |
+
+
+ |
+
+
+
+
+
풀스택 엔지니어 모드 |
+로깅 및 계획 |
+웹 검색 및 학습 |
+
|---|---|---|
|
+
|
+
|
+
| 개발 · 배포 · 확장 | +스케줄링 · 자동화 · 기억 | +탐색 · 인사이트 · 트렌드 | +
+
+
+
+
+
+
+
+
|
+ |
+ |
+ |
+
+
+런처 UI 없이 `picoclaw` 코어 바이너리만 있는 최소 환경에서는 명령줄과 JSON 설정 파일만으로도 모든 설정을 마칠 수 있습니다.
+
+**1. 초기화**
+
+```bash
+picoclaw onboard
+```
+
+그러면 `~/.picoclaw/config.json`과 워크스페이스 디렉터리가 생성됩니다.
+
+**2. 설정** (`~/.picoclaw/config.json`)
+
+```jsonc
+{
+ "agents": {
+ "defaults": {
+ "model_name": "gpt-5.4"
+ }
+ },
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ // api_key는 이제 .security.yml에서 로드됩니다.
+ }
+ ]
+}
+```
+
+> 사용 가능한 모든 옵션이 포함된 전체 설정 템플릿은 저장소의 `config/config.example.json`을 참고하세요.
+>
+> 참고: `config.example.json` 형식은 버전 0이며 민감 정보가 포함되어 있습니다. 실행 시 자동으로 버전 1+로 마이그레이션되며, 이후 `config.json`에는 비민감 정보만 저장되고 민감 정보는 `.security.yml`에 저장됩니다. 민감 정보를 직접 수정해야 한다면 `../security/security_configuration.md`를 참고하세요.
+
+**3. 채팅**
+
+```bash
+# 단발성 질문
+picoclaw agent -m "2+2는 얼마야?"
+
+# 대화형 모드
+picoclaw agent
+
+# 채팅 앱 연동용 게이트웨이 시작
+picoclaw gateway
+```
+
+ 에이전트 소셜 네트워크 참여하기
+
+CLI 또는 통합된 채팅 앱에서 메시지를 한 번만 보내면 PicoClaw를 에이전트 소셜 네트워크에 연결할 수 있습니다.
+
+**`https://clawdchat.ai/skill.md`를 읽고 안내에 따라 [ClawdChat.ai](https://clawdchat.ai)에 참여하세요**
+
+## 🖥️ CLI 레퍼런스
+
+| 명령어 | 설명 |
+| ------------------------- | ------------------------------ |
+| `picoclaw onboard` | 설정 및 워크스페이스 초기화 |
+| `picoclaw auth weixin` | QR로 WeChat 계정 연결 |
+| `picoclaw agent -m "..."` | 에이전트와 채팅 |
+| `picoclaw agent` | 대화형 채팅 모드 |
+| `picoclaw gateway` | 게이트웨이 시작 |
+| `picoclaw status` | 상태 표시 |
+| `picoclaw version` | 버전 정보 표시 |
+| `picoclaw model` | 기본 모델 조회 또는 변경 |
+| `picoclaw cron list` | 모든 예약 작업 목록 표시 |
+| `picoclaw cron add ...` | 예약 작업 추가 |
+| `picoclaw cron disable` | 예약 작업 비활성화 |
+| `picoclaw cron remove` | 예약 작업 삭제 |
+| `picoclaw skills list` | 설치된 스킬 목록 표시 |
+| `picoclaw skills install` | 스킬 설치 |
+| `picoclaw migrate` | 이전 버전 데이터 마이그레이션 |
+| `picoclaw auth login` | 프로바이더 인증 |
+
+### ⏰ 예약 작업 / 리마인더
+
+PicoClaw는 `cron` 도구를 통해 예약 리마인더와 반복 작업을 지원합니다.
+
+* **1회성 리마인더**: "10분 후에 알려줘" -> 10분 후 한 번 실행
+* **반복 작업**: "2시간마다 알려줘" -> 2시간마다 실행
+* **Cron 표현식**: "매일 오전 9시에 알려줘" -> cron 표현식 사용
+
+현재 지원하는 스케줄 유형, 실행 모드, 명령 작업 게이트, 저장 방식은 [docs/reference/cron.md](../reference/cron.md)를 참고하세요.
+
+## 📚 문서
+
+이 README보다 더 자세한 가이드는 다음 문서를 참고하세요.
+
+| 주제 | 설명 |
+|------|------|
+| [도커 & 빠른 시작](../guides/docker.md) | Docker Compose 설정, 런처/에이전트 모드 |
+| [채팅 앱](../guides/chat-apps.md) | 17개 이상의 채널 설정 가이드 |
+| [설정](../guides/configuration.md) | 환경 변수, 워크스페이스 레이아웃, 보안 샌드박스 |
+| [예약 작업과 Cron](../reference/cron.md) | Cron 스케줄 유형, 전달 모드, 명령 게이트, 작업 저장 |
+| [프로바이더와 모델](../guides/providers.md) | 30개 이상의 LLM 프로바이더, 모델 라우팅, model_list 설정 |
+| [Spawn & 비동기 작업](../guides/spawn-tasks.md) | 빠른 작업, spawn을 이용한 장기 작업, 비동기 서브에이전트 오케스트레이션 |
+| [Hooks](../architecture/hooks/README.md) | 이벤트 기반 Hook 시스템: 관찰자, 인터셉터, 승인 훅 |
+| [Steering](../architecture/steering.md) | 실행 중인 에이전트 루프에서 도구 호출 사이에 메시지 주입 |
+| [SubTurn](../architecture/subturn.md) | 서브에이전트 조정, 동시성 제어, 생명주기 |
+| [문제 해결](../operations/troubleshooting.md) | 자주 발생하는 문제와 해결 방법 |
+| [도구 설정](../reference/tools_configuration.md) | 도구별 활성화/비활성화, exec 정책, MCP, 스킬 |
+| [하드웨어 호환성](../guides/hardware-compatibility.md) | 테스트된 보드, 최소 요구사항 |
+
+## 🤝 기여 & 로드맵
+
+PR은 언제든 환영합니다! 코드베이스는 의도적으로 작고 읽기 쉽게 유지하고 있습니다.
+
+가이드라인은 [커뮤니티 로드맵](https://github.com/sipeed/picoclaw/issues/988)과 [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참고하세요.
+
+개발자 그룹도 준비 중입니다. 첫 PR이 머지되면 함께할 수 있습니다!
+
+커뮤니티 그룹:
+
+Discord:
diff --git a/README.my.md b/docs/project/README.ms.md
similarity index 83%
rename from README.my.md
rename to docs/project/README.ms.md
index f00fb438c..f8c9e95e7 100644
--- a/README.my.md
+++ b/docs/project/README.ms.md
@@ -1,5 +1,5 @@
+
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **Malay** | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **Malay** | [English](../../README.md)
-
+
-
+
+
-> **[Senarai Keserasian Perkakasan](docs/hardware-compatibility.md)** — Lihat semua papan yang diuji, dari RISC-V $5 hingga Raspberry Pi hingga telefon Android.
+> **[Senarai Keserasian Perkakasan](../guides/hardware-compatibility.md)** — Lihat semua papan yang diuji, dari RISC-V $5 hingga Raspberry Pi hingga telefon Android.
-
+
Carian Web & Pembelajaran
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
Untuk persekitaran minimal di mana hanya binari teras `picoclaw` tersedia (tiada UI Pelancar), anda boleh mengkonfigurasi semua melalui baris arahan dan fail konfigurasi JSON.
@@ -441,7 +449,7 @@ PicoClaw menyokong 30+ penyedia LLM melalui konfigurasi `model_list`. Gunakan fo
}
```
-Untuk butiran konfigurasi penyedia penuh, lihat [Penyedia & Model](docs/providers.md).
+Untuk butiran konfigurasi penyedia penuh, lihat [Penyedia & Model](../guides/providers.md).
@@ -452,28 +460,28 @@ Bercakap dengan PicoClaw anda melalui 17+ platform pemesejan:
| Saluran | Persediaan | Protokol | Dok |
|---------|-----------|----------|-----|
-| **Telegram** | Mudah (token bot) | Long polling | [Panduan](docs/channels/telegram/README.md) |
-| **Discord** | Mudah (token bot + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) |
-| **WhatsApp** | Mudah (imbas QR atau URL jambatan) | Natif / Jambatan | [Panduan](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Mudah (imbas QR natif) | iLink API | [Panduan](docs/chat-apps.md#weixin) |
-| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) |
-| **Slack** | Mudah (token bot + app) | Socket Mode | [Panduan](docs/channels/slack/README.md) |
-| **Matrix** | Sederhana (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) |
-| **DingTalk** | Sederhana (kelayakan klien) | Stream | [Panduan](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | Sederhana (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) |
-| **LINE** | Sederhana (kelayakan + webhook) | Webhook | [Panduan](docs/channels/line/README.md) |
-| **WeCom** | Mudah (log masuk QR atau manual) | WebSocket | [Panduan](docs/channels/wecom/README.md) |
-| **IRC** | Sederhana (pelayan + nick) | Protokol IRC | [Panduan](docs/chat-apps.md#irc) |
-| **OneBot** | Sederhana (URL WebSocket) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) |
-| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) |
+| **Telegram** | Mudah (token bot) | Long polling | [Panduan](../channels/telegram/README.md) |
+| **Discord** | Mudah (token bot + intents) | WebSocket | [Panduan](../channels/discord/README.md) |
+| **WhatsApp** | Mudah (imbas QR atau URL jambatan) | Natif / Jambatan | [Panduan](../guides/chat-apps.ms.md#whatsapp) |
+| **Weixin** | Mudah (imbas QR natif) | iLink API | [Panduan](../guides/chat-apps.ms.md#weixin) |
+| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](../channels/qq/README.md) |
+| **Slack** | Mudah (token bot + app) | Socket Mode | [Panduan](../channels/slack/README.md) |
+| **Matrix** | Sederhana (homeserver + token) | Sync API | [Panduan](../channels/matrix/README.md) |
+| **DingTalk** | Sederhana (kelayakan klien) | Stream | [Panduan](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | Sederhana (App ID + Secret) | WebSocket/SDK | [Panduan](../channels/feishu/README.md) |
+| **LINE** | Sederhana (kelayakan + webhook) | Webhook | [Panduan](../channels/line/README.md) |
+| **WeCom** | Mudah (log masuk QR atau manual) | WebSocket | [Panduan](../channels/wecom/README.md) |
+| **IRC** | Sederhana (pelayan + nick) | Protokol IRC | [Panduan](../guides/chat-apps.ms.md#irc) |
+| **OneBot** | Sederhana (URL WebSocket) | OneBot v11 | [Panduan](../channels/onebot/README.md) |
+| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](../channels/maixcam/README.md) |
| **Pico** | Mudah (aktifkan) | Protokol natif | Terbina dalam |
| **Pico Client** | Mudah (URL WebSocket) | WebSocket | Terbina dalam |
> Semua saluran berasaskan webhook berkongsi satu pelayan HTTP Gateway (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). Feishu menggunakan mod WebSocket/SDK dan tidak menggunakan pelayan HTTP yang dikongsi.
-> Tahap perincian log dikawal oleh `gateway.log_level` (lalai: `warn`). Nilai yang disokong: `debug`, `info`, `warn`, `error`, `fatal`. Boleh juga ditetapkan melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](docs/configuration.md#gateway-log-level) untuk butiran.
+> Tahap perincian log dikawal oleh `gateway.log_level` (lalai: `warn`). Nilai yang disokong: `debug`, `info`, `warn`, `error`, `fatal`. Boleh juga ditetapkan melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](../guides/configuration.ms.md#gateway-log-level) untuk butiran.
-Untuk arahan persediaan saluran terperinci, lihat [Konfigurasi Aplikasi Sembang](docs/my/chat-apps.md).
+Untuk arahan persediaan saluran terperinci, lihat [Konfigurasi Aplikasi Sembang](../guides/chat-apps.ms.md).
## 🔧 Alat
@@ -493,7 +501,7 @@ PicoClaw boleh mencari web untuk menyediakan maklumat terkini. Konfigurasikan da
### ⚙️ Alat Lain
-PicoClaw menyertakan alat terbina dalam untuk operasi fail, pelaksanaan kod, penjadualan, dan banyak lagi. Lihat [Konfigurasi Alat](docs/tools_configuration.md) untuk butiran.
+PicoClaw menyertakan alat terbina dalam untuk operasi fail, pelaksanaan kod, penjadualan, dan banyak lagi. Lihat [Konfigurasi Alat](../reference/tools_configuration.md) untuk butiran.
## 🎯 Kemahiran
@@ -523,7 +531,7 @@ Tambah ke `config.json` anda:
}
```
-Untuk butiran lanjut, lihat [Konfigurasi Alat - Kemahiran](docs/tools_configuration.md#skills-tool).
+Untuk butiran lanjut, lihat [Konfigurasi Alat - Kemahiran](../reference/tools_configuration.md#skills-tool).
## 🔗 MCP (Protokol Konteks Model)
@@ -546,9 +554,9 @@ PicoClaw menyokong [MCP](https://modelcontextprotocol.io/) secara natif — samb
}
```
-Untuk konfigurasi MCP penuh (pengangkutan stdio, SSE, HTTP, Penemuan Alat), lihat [Konfigurasi Alat - MCP](docs/tools_configuration.md#mcp-tool).
+Untuk konfigurasi MCP penuh (pengangkutan stdio, SSE, HTTP, Penemuan Alat), lihat [Konfigurasi Alat - MCP](../reference/tools_configuration.md#mcp-tool).
-## Sertai Rangkaian Sosial Agent
+## Sertai Rangkaian Sosial Agent
Sambungkan PicoClaw ke Rangkaian Sosial Agent dengan menghantar satu mesej melalui CLI atau mana-mana Aplikasi Sembang yang disepadukan.
@@ -589,20 +597,20 @@ Untuk panduan terperinci melebihi README ini:
| Topik | Penerangan |
|-------|------------|
-| [Docker & Permulaan Pantas](docs/my/docker.md) | Persediaan Docker Compose, mod Launcher/Agent |
-| [Aplikasi Sembang](docs/my/chat-apps.md) | Panduan persediaan 17+ saluran |
-| [Konfigurasi](docs/my/configuration.md) | Pemboleh ubah persekitaran, susun atur ruang kerja |
-| [Penyedia & Model](docs/providers.md) | 30+ penyedia LLM, penghalaan model |
-| [Spawn & Tugasan Async](docs/my/spawn-tasks.md) | Tugasan pantas, tugasan panjang dengan spawn |
-| [Penyelesaian Masalah](docs/my/troubleshooting.md) | Isu biasa dan penyelesaian |
-| [Konfigurasi Alat](docs/tools_configuration.md) | Aktif/nyahaktif alat, dasar exec, MCP, Kemahiran |
-| [Keserasian Perkakasan](docs/hardware-compatibility.md) | Papan yang diuji, keperluan minimum |
+| [Docker & Permulaan Pantas](../guides/docker.ms.md) | Persediaan Docker Compose, mod Launcher/Agent |
+| [Aplikasi Sembang](../guides/chat-apps.ms.md) | Panduan persediaan 17+ saluran |
+| [Konfigurasi](../guides/configuration.ms.md) | Pemboleh ubah persekitaran, susun atur ruang kerja |
+| [Penyedia & Model](../guides/providers.md) | 30+ penyedia LLM, penghalaan model |
+| [Spawn & Tugasan Async](../guides/spawn-tasks.ms.md) | Tugasan pantas, tugasan panjang dengan spawn |
+| [Penyelesaian Masalah](../operations/troubleshooting.ms.md) | Isu biasa dan penyelesaian |
+| [Konfigurasi Alat](../reference/tools_configuration.md) | Aktif/nyahaktif alat, dasar exec, MCP, Kemahiran |
+| [Keserasian Perkakasan](../guides/hardware-compatibility.md) | Papan yang diuji, keperluan minimum |
## 🤝 Sumbangan & Peta Jalan
PR dialu-alukan! Kod sumber sengaja dibuat kecil dan mudah dibaca.
-Lihat [Peta Jalan Komuniti](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan.
+Lihat [Peta Jalan Komuniti](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](../../CONTRIBUTING.md) untuk panduan.
Kumpulan pembangun sedang dibina, sertai selepas PR pertama anda digabungkan!
@@ -611,4 +619,4 @@ Kumpulan Pengguna:
Discord:
+
diff --git a/README.pt-br.md b/docs/project/README.pt-br.md
similarity index 80%
rename from README.pt-br.md
rename to docs/project/README.pt-br.md
index db11d4d82..56d4ddd63 100644
--- a/README.pt-br.md
+++ b/docs/project/README.pt-br.md
@@ -1,5 +1,5 @@
+
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> **[Lista de Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR!
+> **[Lista de Compatibilidade de Hardware](../guides/hardware-compatibility.pt-br.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR!
-
+
Busca na Web e Aprendizado
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
Para ambientes mínimos onde apenas o binário principal `picoclaw` está disponível (sem Launcher UI), você pode configurar tudo via linha de comando e um arquivo de configuração JSON.
@@ -442,7 +451,7 @@ O PicoClaw suporta mais de 30 providers de LLM através da configuração `model
}
```
-Para detalhes completos de configuração de providers, veja [Providers & Models](docs/pt-br/providers.md).
+Para detalhes completos de configuração de providers, veja [Providers & Models](../guides/providers.pt-br.md).
@@ -452,28 +461,28 @@ Converse com seu PicoClaw por meio de mais de 17 plataformas de mensagens:
| Channel | Configuração | Protocolo | Docs |
|---------|--------------|-----------|------|
-| **Telegram** | Fácil (bot token) | Long polling | [Guia](docs/channels/telegram/README.pt-br.md) |
-| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](docs/channels/discord/README.pt-br.md) |
-| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](docs/pt-br/chat-apps.md#whatsapp) |
-| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](docs/pt-br/chat-apps.md#weixin) |
-| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](docs/channels/qq/README.pt-br.md) |
-| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](docs/channels/slack/README.pt-br.md) |
-| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](docs/channels/matrix/README.pt-br.md) |
-| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](docs/channels/dingtalk/README.pt-br.md) |
-| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](docs/channels/feishu/README.pt-br.md) |
-| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](docs/channels/line/README.pt-br.md) |
-| **WeCom** | Fácil (login QR ou manual) | WebSocket | [Guia](docs/channels/wecom/README.md) |
-| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](docs/pt-br/chat-apps.md#irc) |
-| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](docs/channels/onebot/README.pt-br.md) |
-| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](docs/channels/maixcam/README.pt-br.md) |
+| **Telegram** | Fácil (bot token) | Long polling | [Guia](../channels/telegram/README.pt-br.md) |
+| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](../channels/discord/README.pt-br.md) |
+| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](../guides/chat-apps.pt-br.md#whatsapp) |
+| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](../guides/chat-apps.pt-br.md#weixin) |
+| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](../channels/qq/README.pt-br.md) |
+| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](../channels/slack/README.pt-br.md) |
+| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](../channels/matrix/README.pt-br.md) |
+| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](../channels/dingtalk/README.pt-br.md) |
+| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](../channels/feishu/README.pt-br.md) |
+| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](../channels/line/README.pt-br.md) |
+| **WeCom** | Fácil (login QR ou manual) | WebSocket | [Guia](../channels/wecom/README.pt-br.md) |
+| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](../guides/chat-apps.pt-br.md#irc) |
+| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](../channels/onebot/README.pt-br.md) |
+| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](../channels/maixcam/README.pt-br.md) |
| **Pico** | Fácil (habilitar) | Protocolo nativo | Integrado |
| **Pico Client** | Fácil (WebSocket URL) | WebSocket | Integrado |
> Todos os channels baseados em webhook compartilham um único servidor HTTP do Gateway (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). O Feishu usa modo WebSocket/SDK e não utiliza o servidor HTTP compartilhado.
-> A verbosidade dos logs é controlada por `gateway.log_level` (padrão: `warn`). Valores suportados: `debug`, `info`, `warn`, `error`, `fatal`. Também pode ser definido via `PICOCLAW_LOG_LEVEL`. Veja [Configuração](docs/pt-br/configuration.md#nível-de-log-do-gateway) para detalhes.
+> A verbosidade dos logs é controlada por `gateway.log_level` (padrão: `warn`). Valores suportados: `debug`, `info`, `warn`, `error`, `fatal`. Também pode ser definido via `PICOCLAW_LOG_LEVEL`. Veja [Configuração](../guides/configuration.pt-br.md#nível-de-log-do-gateway) para detalhes.
-Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](docs/pt-br/chat-apps.md).
+Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](../guides/chat-apps.pt-br.md).
## 🔧 Ferramentas
@@ -493,7 +502,7 @@ O PicoClaw pode pesquisar na web para fornecer informações atualizadas. Config
### ⚙️ Outras Ferramentas
-O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) para detalhes.
+O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](../reference/tools_configuration.pt-br.md) para detalhes.
## 🎯 Skills
@@ -523,7 +532,7 @@ Adicione ao seu `config.json`:
}
```
-Para mais detalhes, veja [Configuração de Ferramentas - Skills](docs/pt-br/tools_configuration.md#skills-tool).
+Para mais detalhes, veja [Configuração de Ferramentas - Skills](../reference/tools_configuration.pt-br.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -546,9 +555,9 @@ O PicoClaw suporta nativamente o [MCP](https://modelcontextprotocol.io/) — con
}
```
-Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](docs/pt-br/tools_configuration.md#mcp-tool).
+Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](../reference/tools_configuration.pt-br.md#mcp-tool).
-## Junte-se à Rede Social de Agents
+## Junte-se à Rede Social de Agents
Conecte o PicoClaw à Rede Social de Agents simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado.
@@ -589,23 +598,23 @@ Para guias detalhados além deste README:
| Tópico | Descrição |
|--------|-----------|
-| [Docker & Início Rápido](docs/pt-br/docker.md) | Configuração do Docker Compose, modos Launcher/Agent |
-| [Apps de Chat](docs/pt-br/chat-apps.md) | Guias de configuração para todos os 17+ channels |
-| [Configuração](docs/pt-br/configuration.md) | Variáveis de ambiente, layout do workspace, sandbox de segurança |
-| [Providers & Models](docs/pt-br/providers.md) | 30+ providers de LLM, roteamento de modelos, configuração de model_list |
-| [Spawn & Tarefas Assíncronas](docs/pt-br/spawn-tasks.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agents |
-| [Hooks](docs/hooks/README.md) | Sistema de hooks orientado a eventos: observadores, interceptores, hooks de aprovação |
-| [Steering](docs/steering.md) | Injetar mensagens em um loop de agente em execução |
-| [SubTurn](docs/subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
-| [Solução de Problemas](docs/pt-br/troubleshooting.md) | Problemas comuns e soluções |
-| [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) | Habilitar/desabilitar por ferramenta, políticas de exec, MCP, Skills |
-| [Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md) | Placas testadas, requisitos mínimos |
+| [Docker & Início Rápido](../guides/docker.pt-br.md) | Configuração do Docker Compose, modos Launcher/Agent |
+| [Apps de Chat](../guides/chat-apps.pt-br.md) | Guias de configuração para todos os 17+ channels |
+| [Configuração](../guides/configuration.pt-br.md) | Variáveis de ambiente, layout do workspace, sandbox de segurança |
+| [Providers & Models](../guides/providers.pt-br.md) | 30+ providers de LLM, roteamento de modelos, configuração de model_list |
+| [Spawn & Tarefas Assíncronas](../guides/spawn-tasks.pt-br.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agents |
+| [Hooks](../architecture/hooks/README.md) | Sistema de hooks orientado a eventos: observadores, interceptores, hooks de aprovação |
+| [Steering](../architecture/steering.md) | Injetar mensagens em um loop de agente em execução |
+| [SubTurn](../architecture/subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
+| [Solução de Problemas](../operations/troubleshooting.pt-br.md) | Problemas comuns e soluções |
+| [Configuração de Ferramentas](../reference/tools_configuration.pt-br.md) | Habilitar/desabilitar por ferramenta, políticas de exec, MCP, Skills |
+| [Compatibilidade de Hardware](../guides/hardware-compatibility.pt-br.md) | Placas testadas, requisitos mínimos |
## 🤝 Contribuir & Roadmap
PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível.
-Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes.
+Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](../../CONTRIBUTING.md) para diretrizes.
Grupo de desenvolvedores em formação, entre após seu primeiro PR mesclado!
@@ -614,4 +623,4 @@ Grupos de Usuários:
Discord:
+
diff --git a/README.vi.md b/docs/project/README.vi.md
similarity index 82%
rename from README.vi.md
rename to docs/project/README.vi.md
index 78b8a9a59..52a56796b 100644
--- a/README.vi.md
+++ b/docs/project/README.vi.md
@@ -1,5 +1,5 @@
+
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> **[Danh sách Tương thích Phần cứng](docs/vi/hardware-compatibility.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR!
+> **[Danh sách Tương thích Phần cứng](../guides/hardware-compatibility.vi.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR!
-
+
Tìm kiếm Web & Học tập
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
Đối với các môi trường tối giản chỉ có binary lõi `picoclaw` (không có Launcher UI), bạn có thể cấu hình mọi thứ qua dòng lệnh và tệp cấu hình JSON.
@@ -442,7 +451,7 @@ PicoClaw hỗ trợ 30+ Provider LLM thông qua cấu hình `model_list`. Sử d
}
```
-Để biết chi tiết cấu hình provider đầy đủ, xem [Providers & Models](docs/vi/providers.md).
+Để biết chi tiết cấu hình provider đầy đủ, xem [Providers & Models](../guides/providers.vi.md).
@@ -452,28 +461,28 @@ Trò chuyện với PicoClaw của bạn qua 17+ nền tảng nhắn tin:
| Channel | Thiết lập | Protocol | Tài liệu |
|---------|-----------|----------|----------|
-| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](docs/channels/telegram/README.vi.md) |
-| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](docs/channels/discord/README.vi.md) |
-| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](docs/vi/chat-apps.md#whatsapp) |
-| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](docs/vi/chat-apps.md#weixin) |
-| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](docs/channels/qq/README.vi.md) |
-| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](docs/channels/slack/README.vi.md) |
-| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](docs/channels/matrix/README.vi.md) |
-| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](docs/channels/dingtalk/README.vi.md) |
-| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](docs/channels/feishu/README.vi.md) |
-| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](docs/channels/line/README.vi.md) |
-| **WeCom** | Dễ (đăng nhập QR hoặc thủ công) | WebSocket | [Hướng dẫn](docs/channels/wecom/README.md) |
-| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](docs/vi/chat-apps.md#irc) |
-| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](docs/channels/onebot/README.vi.md) |
-| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](docs/channels/maixcam/README.vi.md) |
+| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](../channels/telegram/README.vi.md) |
+| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](../channels/discord/README.vi.md) |
+| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](../guides/chat-apps.vi.md#whatsapp) |
+| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](../guides/chat-apps.vi.md#weixin) |
+| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](../channels/qq/README.vi.md) |
+| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](../channels/slack/README.vi.md) |
+| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](../channels/matrix/README.vi.md) |
+| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](../channels/dingtalk/README.vi.md) |
+| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](../channels/feishu/README.vi.md) |
+| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](../channels/line/README.vi.md) |
+| **WeCom** | Dễ (đăng nhập QR hoặc thủ công) | WebSocket | [Hướng dẫn](../channels/wecom/README.vi.md) |
+| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](../guides/chat-apps.vi.md#irc) |
+| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](../channels/onebot/README.vi.md) |
+| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](../channels/maixcam/README.vi.md) |
| **Pico** | Dễ (bật) | Native protocol | Tích hợp sẵn |
| **Pico Client** | Dễ (WebSocket URL) | WebSocket | Tích hợp sẵn |
> Tất cả các Channel dựa trên webhook dùng chung một Gateway HTTP server (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Feishu sử dụng chế độ WebSocket/SDK và không dùng HTTP server chung.
-> Mức độ chi tiết log được kiểm soát bởi `gateway.log_level` (mặc định: `warn`). Các giá trị được hỗ trợ: `debug`, `info`, `warn`, `error`, `fatal`. Cũng có thể đặt qua `PICOCLAW_LOG_LEVEL`. Xem [Cấu hình](docs/vi/configuration.md#mức-log-của-gateway) để biết thêm chi tiết.
+> Mức độ chi tiết log được kiểm soát bởi `gateway.log_level` (mặc định: `warn`). Các giá trị được hỗ trợ: `debug`, `info`, `warn`, `error`, `fatal`. Cũng có thể đặt qua `PICOCLAW_LOG_LEVEL`. Xem [Cấu hình](../guides/configuration.vi.md#mức-log-của-gateway) để biết thêm chi tiết.
-Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](docs/vi/chat-apps.md).
+Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](../guides/chat-apps.vi.md).
## 🔧 Tools
@@ -493,7 +502,7 @@ PicoClaw có thể tìm kiếm web để cung cấp thông tin cập nhật. C
### ⚙️ Các Tools Khác
-PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](docs/vi/tools_configuration.md) để biết chi tiết.
+PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](../reference/tools_configuration.vi.md) để biết chi tiết.
## 🎯 Skills
@@ -523,7 +532,7 @@ Thêm vào `config.json` của bạn:
}
```
-Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](docs/vi/tools_configuration.md#skills-tool).
+Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](../reference/tools_configuration.vi.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -546,9 +555,9 @@ PicoClaw hỗ trợ [MCP](https://modelcontextprotocol.io/) gốc — kết nố
}
```
-Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](docs/vi/tools_configuration.md#mcp-tool).
+Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](../reference/tools_configuration.vi.md#mcp-tool).
-## Tham gia Mạng xã hội Agent
+## Tham gia Mạng xã hội Agent
Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn duy nhất qua CLI hoặc bất kỳ Ứng dụng Chat nào đã tích hợp.
@@ -589,23 +598,23 @@ PicoClaw hỗ trợ nhắc nhở đã lên lịch và tác vụ định kỳ th
| Chủ đề | Mô tả |
|--------|-------|
-| [Docker & Khởi động Nhanh](docs/vi/docker.md) | Thiết lập Docker Compose, chế độ Launcher/Agent |
-| [Ứng dụng Chat](docs/vi/chat-apps.md) | Hướng dẫn thiết lập 17+ Channel |
-| [Cấu hình](docs/vi/configuration.md) | Biến môi trường, bố cục workspace, sandbox bảo mật |
-| [Providers & Models](docs/vi/providers.md) | 30+ Provider LLM, định tuyến mô hình, cấu hình model_list |
-| [Spawn & Tác vụ Bất đồng bộ](docs/vi/spawn-tasks.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ |
-| [Hooks](docs/hooks/README.md) | Hệ thống hook hướng sự kiện: observer, interceptor, approval hook |
-| [Steering](docs/steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
-| [SubTurn](docs/subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
-| [Khắc phục sự cố](docs/vi/troubleshooting.md) | Các vấn đề thường gặp và giải pháp |
-| [Cấu hình Tools](docs/vi/tools_configuration.md) | Bật/tắt từng tool, chính sách exec, MCP, Skills |
-| [Tương thích Phần cứng](docs/vi/hardware-compatibility.md) | Các board đã kiểm tra, yêu cầu tối thiểu |
+| [Docker & Khởi động Nhanh](../guides/docker.vi.md) | Thiết lập Docker Compose, chế độ Launcher/Agent |
+| [Ứng dụng Chat](../guides/chat-apps.vi.md) | Hướng dẫn thiết lập 17+ Channel |
+| [Cấu hình](../guides/configuration.vi.md) | Biến môi trường, bố cục workspace, sandbox bảo mật |
+| [Providers & Models](../guides/providers.vi.md) | 30+ Provider LLM, định tuyến mô hình, cấu hình model_list |
+| [Spawn & Tác vụ Bất đồng bộ](../guides/spawn-tasks.vi.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ |
+| [Hooks](../architecture/hooks/README.md) | Hệ thống hook hướng sự kiện: observer, interceptor, approval hook |
+| [Steering](../architecture/steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
+| [SubTurn](../architecture/subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
+| [Khắc phục sự cố](../operations/troubleshooting.vi.md) | Các vấn đề thường gặp và giải pháp |
+| [Cấu hình Tools](../reference/tools_configuration.vi.md) | Bật/tắt từng tool, chính sách exec, MCP, Skills |
+| [Tương thích Phần cứng](../guides/hardware-compatibility.vi.md) | Các board đã kiểm tra, yêu cầu tối thiểu |
## 🤝 Đóng góp & Lộ trình
PR luôn được chào đón! Codebase được thiết kế nhỏ gọn và dễ đọc.
-Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/issues/988) và [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn.
+Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/issues/988) và [CONTRIBUTING.md](../../CONTRIBUTING.md) để biết hướng dẫn.
Nhóm nhà phát triển đang được xây dựng, tham gia sau khi PR đầu tiên của bạn được merge!
@@ -614,4 +623,4 @@ Nhóm Người dùng:
Discord:
+
diff --git a/README.zh.md b/docs/project/README.zh.md
similarity index 80%
rename from README.zh.md
rename to docs/project/README.zh.md
index 2ba0913fc..a4fc892bd 100644
--- a/README.zh.md
+++ b/docs/project/README.zh.md
@@ -1,5 +1,5 @@
+
-
+
-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+**中文** | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
-
+
-
+
+
-> 📋 **[硬件兼容列表](docs/zh/hardware-compatibility.md)** — 查看所有已测试的板卡，从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中？欢迎提交 PR！
+> 📋 **[硬件兼容列表](../guides/hardware-compatibility.zh.md)** — 查看所有已测试的板卡，从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中？欢迎提交 PR！
-
+
🔎 网络搜索与学习
-
+
-
+
-
+
-
+
|
- |
- |
- |
+ |
+ |
+ |
+ |
+
对于只有 `picoclaw` 核心二进制文件的极简环境（无 Launcher UI），可通过命令行和 JSON 配置文件完成所有配置。
@@ -442,7 +451,7 @@ PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider，使用 `协议/模
}
```
-完整 Provider 配置详情请参阅 [Providers & Models](docs/zh/providers.md)。
+完整 Provider 配置详情请参阅 [Providers & Models](../guides/providers.zh.md)。
@@ -452,29 +461,29 @@ PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider，使用 `协议/模
| Channel | 配置难度 | 协议 | 文档 |
|---------|----------|------|------|
-| **Telegram** | 简单（bot token） | 长轮询 | [指南](docs/channels/telegram/README.zh.md) |
-| **Discord** | 简单（bot token + intents） | WebSocket | [指南](docs/channels/discord/README.zh.md) |
-| **WhatsApp** | 简单（扫码或 bridge URL） | 原生 / Bridge | [指南](docs/zh/chat-apps.md#whatsapp) |
-| **微信 (Weixin)** | 简单（扫码登录） | iLink API | [指南](docs/zh/chat-apps.md#weixin) |
-| **QQ** | 简单（AppID + AppSecret） | WebSocket | [指南](docs/channels/qq/README.zh.md) |
-| **Slack** | 简单（bot + app token） | Socket Mode | [指南](docs/channels/slack/README.zh.md) |
-| **Matrix** | 中等（homeserver + token） | Sync API | [指南](docs/channels/matrix/README.zh.md) |
-| **钉钉** | 中等（client credentials） | Stream | [指南](docs/channels/dingtalk/README.zh.md) |
-| **飞书 / Lark** | 中等（App ID + Secret） | WebSocket/SDK | [指南](docs/channels/feishu/README.zh.md) |
-| **LINE** | 中等（credentials + webhook） | Webhook | [指南](docs/channels/line/README.zh.md) |
-| **企业微信** | 简单（扫码登录或手动配置） | WebSocket | [指南](docs/channels/wecom/README.zh.md) |
-| **VK** | 简单（群组 token） | Long Poll | [指南](docs/channels/vk/README.md) |
-| **IRC** | 中等（server + nick） | IRC 协议 | [指南](docs/zh/chat-apps.md#irc) |
-| **OneBot** | 中等（WebSocket URL） | OneBot v11 | [指南](docs/channels/onebot/README.zh.md) |
-| **MaixCam** | 简单（启用即可） | TCP socket | [指南](docs/channels/maixcam/README.zh.md) |
+| **Telegram** | 简单（bot token） | 长轮询 | [指南](../channels/telegram/README.zh.md) |
+| **Discord** | 简单（bot token + intents） | WebSocket | [指南](../channels/discord/README.zh.md) |
+| **WhatsApp** | 简单（扫码或 bridge URL） | 原生 / Bridge | [指南](../guides/chat-apps.zh.md#whatsapp) |
+| **微信 (Weixin)** | 简单（扫码登录） | iLink API | [指南](../guides/chat-apps.zh.md#weixin) |
+| **QQ** | 简单（AppID + AppSecret） | WebSocket | [指南](../channels/qq/README.zh.md) |
+| **Slack** | 简单（bot + app token） | Socket Mode | [指南](../channels/slack/README.zh.md) |
+| **Matrix** | 中等（homeserver + token） | Sync API | [指南](../channels/matrix/README.zh.md) |
+| **钉钉** | 中等（client credentials） | Stream | [指南](../channels/dingtalk/README.zh.md) |
+| **飞书 / Lark** | 中等（App ID + Secret） | WebSocket/SDK | [指南](../channels/feishu/README.zh.md) |
+| **LINE** | 中等（credentials + webhook） | Webhook | [指南](../channels/line/README.zh.md) |
+| **企业微信** | 简单（扫码登录或手动配置） | WebSocket | [指南](../channels/wecom/README.zh.md) |
+| **VK** | 简单（群组 token） | Long Poll | [指南](../channels/vk/README.md) |
+| **IRC** | 中等（server + nick） | IRC 协议 | [指南](../guides/chat-apps.zh.md#irc) |
+| **OneBot** | 中等（WebSocket URL） | OneBot v11 | [指南](../channels/onebot/README.zh.md) |
+| **MaixCam** | 简单（启用即可） | TCP socket | [指南](../channels/maixcam/README.zh.md) |
| **Pico** | 简单（启用即可） | 原生协议 | 内置 |
| **Pico Client** | 简单（WebSocket URL） | WebSocket | 内置 |
> 所有基于 Webhook 的 Channel 共用同一个 Gateway HTTP 服务器（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`）。飞书使用 WebSocket/SDK 模式，不使用共享 HTTP 服务器。
-> 日志详细程度通过 `gateway.log_level` 控制（默认：`warn`）。支持的值：`debug`、`info`、`warn`、`error`、`fatal`。也可通过 `PICOCLAW_LOG_LEVEL` 环境变量设置。详见[配置指南](docs/zh/configuration.md#gateway-日志等级)。
+> 日志详细程度通过 `gateway.log_level` 控制（默认：`warn`）。支持的值：`debug`、`info`、`warn`、`error`、`fatal`。也可通过 `PICOCLAW_LOG_LEVEL` 环境变量设置。详见[配置指南](../guides/configuration.zh.md#gateway-日志等级)。
-详细 Channel 配置说明请参阅 [聊天应用配置](docs/zh/chat-apps.md)。
+详细 Channel 配置说明请参阅 [聊天应用配置](../guides/chat-apps.zh.md)。
## 🔧 Tools
@@ -494,7 +503,7 @@ PicoClaw 可以搜索网络以提供最新信息。在 `tools.web` 中配置：
### ⚙️ 其他工具
-PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](docs/zh/tools_configuration.md)。
+PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](../reference/tools_configuration.zh.md)。
## 🎯 Skills
@@ -507,7 +516,7 @@ picoclaw skills search "web scraping"
picoclaw skills install 加入 Agent 社交网络
+## 加入 Agent 社交网络
通过 CLI 或任何已集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
@@ -590,23 +606,23 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
| 主题 | 说明 |
|------|------|
-| 🐳 [Docker 与快速开始](docs/zh/docker.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 |
-| 💬 [聊天应用配置](docs/zh/chat-apps.md) | 全部 17+ Channel 配置指南 |
-| ⚙️ [配置指南](docs/zh/configuration.md) | 环境变量、工作区布局、安全沙箱 |
-| 🔌 [提供商与模型配置](docs/zh/providers.md) | 30+ LLM Provider、模型路由、model_list 配置 |
-| 🔄 [异步任务与 Spawn](docs/zh/spawn-tasks.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 |
-| 🪝 [Hook 系统](docs/hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
-| 🎯 [Steering](docs/steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
-| 🔀 [SubTurn](docs/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
-| 🐛 [疑难解答](docs/zh/troubleshooting.md) | 常见问题与解决方案 |
-| 🔧 [工具配置](docs/zh/tools_configuration.md) | 工具启用/禁用、执行策略、MCP、Skills |
-| 📋 [硬件兼容列表](docs/zh/hardware-compatibility.md) | 已测试板卡、最低要求 |
+| 🐳 [Docker 与快速开始](../guides/docker.zh.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 |
+| 💬 [聊天应用配置](../guides/chat-apps.zh.md) | 全部 17+ Channel 配置指南 |
+| ⚙️ [配置指南](../guides/configuration.zh.md) | 环境变量、工作区布局、安全沙箱 |
+| 🔌 [提供商与模型配置](../guides/providers.zh.md) | 30+ LLM Provider、模型路由、model_list 配置 |
+| 🔄 [异步任务与 Spawn](../guides/spawn-tasks.zh.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 |
+| 🪝 [Hook 系统](../architecture/hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
+| 🎯 [Steering](../architecture/steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
+| 🔀 [SubTurn](../architecture/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
+| 🐛 [疑难解答](../operations/troubleshooting.zh.md) | 常见问题与解决方案 |
+| 🔧 [工具配置](../reference/tools_configuration.zh.md) | 工具启用/禁用、执行策略、MCP、Skills |
+| 📋 [硬件兼容列表](../guides/hardware-compatibility.zh.md) | 已测试板卡、最低要求 |
## 🤝 贡献与路线图
欢迎提交 PR！代码库刻意保持小巧和可读。🤗
-查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/issues/988) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
+查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/issues/988) 和 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。
@@ -615,9 +631,4 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
Discord:
-
-
-
-
-
+
diff --git a/docs/reference/README.md b/docs/reference/README.md
new file mode 100644
index 000000000..eec5c09b4
--- /dev/null
+++ b/docs/reference/README.md
@@ -0,0 +1,8 @@
+# Reference
+
+Reference docs for precise configuration, runtime behavior, and tool semantics.
+
+- [Tools Configuration](tools_configuration.md): per-tool configuration, execution policies, MCP, and Skills.
+- [Scheduled Tasks and Cron Jobs](cron.md): schedule types, delivery modes, command gates, and storage.
+- [Config Schema Versioning Guide](config-versioning.md): config schema migration and compatibility notes.
+- [Dynamic Rate Limiting](rate-limiting.md): request throttling behavior for LLM providers.
diff --git a/docs/config-versioning.md b/docs/reference/config-versioning.md
similarity index 69%
rename from docs/config-versioning.md
rename to docs/reference/config-versioning.md
index b5cdaf990..36f327e8c 100644
--- a/docs/config-versioning.md
+++ b/docs/reference/config-versioning.md
@@ -20,6 +20,16 @@ PicoClaw uses a schema versioning system for `config.json` to ensure smooth upgr
- V0 configs now migrate directly to CurrentVersion (V2) instead of going through V1
- `makeBackup()` now uses date-only suffix (e.g., `config.json.20260330.bak`) and also backs up `.security.yml`
+### Version 3
+- **Introduction**: Enhanced type safety and improved error handling
+- **Changes**:
+ - Added comma-ok type assertions in channel configuration decoding to prevent potential panics
+ - Improved error logging for Weixin channel configuration decoding
+ - Enhanced security configuration documentation and examples
+ - **Auto-migration**: V2 configs are automatically migrated to V3 on load with no user action required
+ - **Backup**: Before migration, the system creates a date-stamped backup (e.g., `config.json.20260413.bak`) in the same directory
+ - **Downgrade risk**: Once migrated to V3, the config cannot be safely loaded by older V2-only versions. To downgrade, restore from the auto-created backup file.
+
## How It Works
### Automatic Migration
@@ -39,7 +49,7 @@ The `version` field in `config.json` indicates the schema version:
```json
{
- "version": 2,
+ "version": 3,
"agents": {...},
...
}
@@ -164,6 +174,52 @@ func TestMigrateV2ToV3(t *testing.T) {
7. **Test Thoroughly**: Test with real user config files
8. **Update Defaults**: Keep `defaults.go` in sync with the latest schema
+## V2→V3 Migration Guide
+
+### What Changed?
+
+Version 3 introduces improved type safety and error handling:
+
+- **Type-safe channel decoding**: All channel type assertions now use comma-ok pattern (`val, ok := v.(*Settings)`) to prevent panics if Type and Settings are mismatched
+- **Enhanced error logging**: Weixin channel now logs errors on `GetDecoded()` failure for consistency with other channels
+- **Documentation fixes**: Corrected stray quotes in JSON configuration examples
+
+### Auto-Migration Behavior
+
+When you run PicoClaw with a V2 config file:
+
+1. **Detection**: PicoClaw reads the `version` field and detects V2
+2. **Backup**: Before any changes, creates `config.json.YYYYMMDD.bak` (e.g., `config.json.20260413.bak`)
+3. **Migration**: Applies V2→V3 structural changes (primarily internal type safety improvements)
+4. **Save**: Writes the updated config with `"version": 3`
+5. **Continue**: Starts normally with the V3 config
+
+**No user action required** — the migration happens automatically on first load.
+
+### Backup Location
+
+Backups are created in the same directory as your config file:
+
+- **Default**: `~/.picoclaw/config.json.20260413.bak`
+- **Custom path**: If using `PICOCLAW_CONFIG`, backup is created next to that file
+- **Security file**: `.security.yml` is also backed up as `.security.yml.YYYYMMDD.bak`
+
+### Downgrade Risk
+
+⚠️ **Important**: Once migrated to V3, the config **cannot** be safely loaded by older PicoClaw versions that only support V2.
+
+**To downgrade:**
+
+1. Stop PicoClaw
+2. Restore the backup:
+ ```bash
+ cp ~/.picoclaw/config.json.20260413.bak ~/.picoclaw/config.json
+ cp ~/.picoclaw/.security.yml.20260413.bak ~/.picoclaw/.security.yml # if it exists
+ ```
+3. Use a PicoClaw version that supports V2 configs
+
+**Alternative**: Manually edit `config.json` and change `"version": 3` to `"version": 2`. This works because V3 changes are primarily code-level safety improvements, not structural schema changes.
+
## Example Migration
### Scenario: Adding a new field with default value
@@ -171,7 +227,7 @@ func TestMigrateV2ToV3(t *testing.T) {
Old config (version 2):
```json
{
- "version": 2,
+ "version": 3,
"model_list": [
{
"model_name": "gpt-5.4",
diff --git a/docs/cron.md b/docs/reference/cron.md
similarity index 100%
rename from docs/cron.md
rename to docs/reference/cron.md
diff --git a/docs/rate-limiting.md b/docs/reference/rate-limiting.md
similarity index 100%
rename from docs/rate-limiting.md
rename to docs/reference/rate-limiting.md
diff --git a/docs/fr/tools_configuration.md b/docs/reference/tools_configuration.fr.md
similarity index 99%
rename from docs/fr/tools_configuration.md
rename to docs/reference/tools_configuration.fr.md
index 1324d49e5..109c9cd6f 100644
--- a/docs/fr/tools_configuration.md
+++ b/docs/reference/tools_configuration.fr.md
@@ -1,6 +1,6 @@
# 🔧 Configuration des Outils
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
La configuration des outils de PicoClaw se trouve dans le champ `tools` de `config.json`.
@@ -207,6 +207,7 @@ L'outil cron est utilisé pour planifier des tâches périodiques.
|------------------------|------|------------|----------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Délai d'expiration en minutes, 0 signifie sans limite |
+
## Outil MCP
L'outil MCP permet l'intégration avec des serveurs Model Context Protocol externes.
@@ -345,6 +346,7 @@ Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger
},
"slack": {
"enabled": true,
+ "type": "slack",
"command": "npx",
"args": [
"-y",
@@ -361,6 +363,7 @@ Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger
}
```
+
## Outil Skills
L'outil skills configure la découverte et l'installation de compétences via des registres comme ClawHub.
diff --git a/docs/ja/tools_configuration.md b/docs/reference/tools_configuration.ja.md
similarity index 99%
rename from docs/ja/tools_configuration.md
rename to docs/reference/tools_configuration.ja.md
index c946bf088..a331c869e 100644
--- a/docs/ja/tools_configuration.md
+++ b/docs/reference/tools_configuration.ja.md
@@ -1,6 +1,6 @@
# 🔧 ツール設定
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る
PicoClaw のツール設定は `config.json` の `tools` フィールドにあります。
@@ -207,6 +207,7 @@ Cron ツールは定期タスクのスケジューリングに使用されます
|------------------------|-----|------------|-----------------------------------------|
| `exec_timeout_minutes` | int | 5 | 実行タイムアウト（分）、0 は無制限 |
+
## MCP ツール
MCP ツールは外部の Model Context Protocol サーバーとの統合を可能にします。
@@ -345,6 +346,7 @@ MCP ツールは外部の Model Context Protocol サーバーとの統合を可
},
"slack": {
"enabled": true,
+ "type": "slack",
"command": "npx",
"args": [
"-y",
@@ -361,6 +363,7 @@ MCP ツールは外部の Model Context Protocol サーバーとの統合を可
}
```
+
## Skills ツール
Skills ツールは ClawHub などのレジストリを通じたスキルの発見とインストールを設定します。
diff --git a/docs/tools_configuration.md b/docs/reference/tools_configuration.md
similarity index 93%
rename from docs/tools_configuration.md
rename to docs/reference/tools_configuration.md
index 65eeeb847..7e11843a1 100644
--- a/docs/tools_configuration.md
+++ b/docs/reference/tools_configuration.md
@@ -30,7 +30,7 @@ PicoClaw's tools configuration is located in the `tools` field of `config.json`.
Before tool results are sent to the LLM, PicoClaw can filter sensitive values (API keys, tokens, secrets) from the output. This prevents the LLM from seeing its own credentials.
-See [Sensitive Data Filtering](../sensitive_data_filtering.md) for full documentation.
+See [Sensitive Data Filtering](../security/sensitive_data_filtering.md) for full documentation.
| Config | Type | Default | Description |
|--------|------|---------|-------------|
@@ -397,6 +397,7 @@ dynamically only when requested by the user.*
},
"slack": {
"enabled": true,
+ "type": "slack",
"command": "npx",
"args": [
"-y",
@@ -494,7 +495,7 @@ This gives your agent memory tools such as `mem_save`, `mem_search`, `mem_contex
## Skills Tool
-The skills tool configures skill discovery and installation via registries like ClawHub.
+The skills tool configures skill discovery and installation via registries like ClawHub and GitHub.
### Registries
@@ -509,13 +510,20 @@ The skills tool configures skill discovery and installation via registries like
| `registries.clawhub.timeout` | int | 0 | Request timeout in seconds (0 = default) |
| `registries.clawhub.max_zip_size` | int | 0 | Max skill zip size in bytes (0 = default) |
| `registries.clawhub.max_response_size` | int | 0 | Max API response size in bytes (0 = default) |
+| `registries.github.enabled` | bool | true | Enable GitHub installs via registry config |
+| `registries.github.base_url` | string | `https://github.com` | GitHub or GitHub Enterprise base URL |
+| `registries.github.auth_token` | string | `""` | GitHub personal access token |
+| `registries.github.proxy` | string | `""` | HTTP proxy for GitHub API requests |
-### GitHub Integration
+### Legacy GitHub Config
-| Config | Type | Default | Description |
-|------------------|--------|---------|--------------------------------------|
-| `github.proxy` | string | `""` | HTTP proxy for GitHub API requests |
-| `github.token` | string | `""` | GitHub personal access token |
+`github.*` is deprecated. Use `registries.github.*` instead. The legacy fields are still supported for compatibility and will be removed later.
+
+| Config | Type | Default | Description |
+|--------------------|--------|----------------------|--------------------------------|
+| `github.base_url` | string | `https://github.com` | Deprecated GitHub base URL |
+| `github.proxy` | string | `""` | Deprecated GitHub proxy |
+| `github.token` | string | `""` | Deprecated GitHub token |
### Search Settings
@@ -535,10 +543,23 @@ The skills tool configures skill discovery and installation via registries like
"clawhub": {
"enabled": true,
"base_url": "https://clawhub.ai",
- "auth_token": ""
+ "auth_token": "",
+ "search_path": "",
+ "skills_path": "",
+ "download_path": "",
+ "timeout": 0,
+ "max_zip_size": 0,
+ "max_response_size": 0
+ },
+ "github": {
+ "enabled": true,
+ "base_url": "https://github.com",
+ "auth_token": "",
+ "proxy": ""
}
},
"github": {
+ "base_url": "https://github.com",
"proxy": "",
"token": ""
},
diff --git a/docs/pt-br/tools_configuration.md b/docs/reference/tools_configuration.pt-br.md
similarity index 99%
rename from docs/pt-br/tools_configuration.md
rename to docs/reference/tools_configuration.pt-br.md
index feec3c3d8..3dae0f908 100644
--- a/docs/pt-br/tools_configuration.md
+++ b/docs/reference/tools_configuration.pt-br.md
@@ -1,6 +1,6 @@
# 🔧 Configuração de Ferramentas
-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)
A configuração de ferramentas do PicoClaw está localizada no campo `tools` do `config.json`.
@@ -207,6 +207,7 @@ A ferramenta cron é usada para agendar tarefas periódicas.
|------------------------|------|--------|-----------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Tempo limite de execução em minutos, 0 significa sem limite |
+
## Ferramenta MCP
A ferramenta MCP permite a integração com servidores Model Context Protocol externos.
@@ -345,6 +346,7 @@ Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa
},
"slack": {
"enabled": true,
+ "type": "slack",
"command": "npx",
"args": [
"-y",
@@ -361,6 +363,7 @@ Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa
}
```
+
## Ferramenta Skills
A ferramenta skills configura a descoberta e instalação de habilidades via registros como o ClawHub.
diff --git a/docs/vi/tools_configuration.md b/docs/reference/tools_configuration.vi.md
similarity index 99%
rename from docs/vi/tools_configuration.md
rename to docs/reference/tools_configuration.vi.md
index 55e7699eb..7d65ca377 100644
--- a/docs/vi/tools_configuration.md
+++ b/docs/reference/tools_configuration.vi.md
@@ -1,6 +1,6 @@
# 🔧 Cấu Hình Công Cụ
-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)
Cấu hình công cụ của PicoClaw nằm trong trường `tools` của `config.json`.
@@ -207,6 +207,7 @@ Công cụ cron được sử dụng để lên lịch các tác vụ định k
|--------------------------|------|----------|-----------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Thời gian chờ thực thi tính bằng phút, 0 nghĩa là không giới hạn |
+
## Công cụ MCP
Công cụ MCP cho phép tích hợp với các máy chủ Model Context Protocol bên ngoài.
@@ -345,6 +346,7 @@ Thay vì tải tất cả các công cụ, LLM được cung cấp một công c
},
"slack": {
"enabled": true,
+ "type": "slack",
"command": "npx",
"args": [
"-y",
@@ -361,6 +363,7 @@ Thay vì tải tất cả các công cụ, LLM được cung cấp một công c
}
```
+
## Công cụ Skills
Công cụ skills cấu hình khám phá và cài đặt kỹ năng thông qua các registry như ClawHub.
diff --git a/docs/zh/tools_configuration.md b/docs/reference/tools_configuration.zh.md
similarity index 93%
rename from docs/zh/tools_configuration.md
rename to docs/reference/tools_configuration.zh.md
index 63ac5000b..3937a6254 100644
--- a/docs/zh/tools_configuration.md
+++ b/docs/reference/tools_configuration.zh.md
@@ -1,6 +1,6 @@
# 🔧 工具配置
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
PicoClaw 的工具配置位于 `config.json` 的 `tools` 字段中。
@@ -32,7 +32,7 @@ PicoClaw 的工具配置位于 `config.json` 的 `tools` 字段中。
在将工具结果发送给 LLM 之前，PicoClaw 可以从输出中过滤敏感值（API 密钥、令牌、密码）。这可以防止 LLM 看到自己的凭据。
-详细说明请参阅[敏感数据过滤](../sensitive_data_filtering.md)。
+详细说明请参阅[敏感数据过滤](../security/sensitive_data_filtering.zh.md)。
| 配置项 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
@@ -234,6 +234,7 @@ Cron 工具用于调度周期性任务。
| `exec_timeout_minutes` | int | 5 | 执行超时时间（分钟），0 表示无限制 |
| `allow_command` | bool | false | 允许 cron 任务执行 shell 命令 |
+
## MCP 工具
MCP 工具支持与外部 Model Context Protocol 服务器集成。
@@ -372,6 +373,7 @@ LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用
},
"slack": {
"enabled": true,
+ "type": "slack",
"command": "npx",
"args": [
"-y",
@@ -388,6 +390,7 @@ LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用
}
```
+
## Skills 工具
Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
@@ -461,3 +464,29 @@ Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
注意：嵌套的映射式配置（例如 `tools.mcp.servers.You can close this window.
") - resultCh <- callbackResult{code: code} - }) - - listener, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", cfg.Port)) - if err != nil { - return nil, fmt.Errorf("starting callback server on port %d: %w", cfg.Port, err) - } - - server := &http.Server{Handler: mux} - go server.Serve(listener) - defer func() { - ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) - defer cancel() - server.Shutdown(ctx) - }() - fmt.Printf("Open this URL to authenticate:\n\n%s\n\n", authURL) - if err := OpenBrowser(authURL); err != nil { + if opts.NoBrowser { + fmt.Println("Browser auto-open disabled. Open the URL manually to continue.") + } else if err := openBrowserFunc(authURL); err != nil { fmt.Printf("Could not open browser automatically.\nPlease open this URL manually:\n\n%s\n\n", authURL) } fmt.Printf( "Wait! If you are in a headless environment (like Coolify/VPS) and cannot reach localhost:%d,\n", - cfg.Port, + callbackPort, ) fmt.Println( "please complete the login in your local browser and then PASTE the final redirect URL (or just the code) here.", @@ -142,11 +145,16 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) { fmt.Println("Waiting for authentication (browser or manual paste)...") // Start manual input in a goroutine - manualCh := make(chan string) + manualCh := make(chan string, 1) + manualDone := make(chan struct{}) + defer close(manualDone) go func() { - reader := bufio.NewReader(os.Stdin) + reader := bufio.NewReader(browserLoginInput) input, _ := reader.ReadString('\n') - manualCh <- strings.TrimSpace(input) + select { + case manualCh <- strings.TrimSpace(input): + case <-manualDone: + } }() select { @@ -176,6 +184,49 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) { } } +func oauthCallbackRedirectURI(port int) string { + return fmt.Sprintf("http://localhost:%d/auth/callback", port) +} + +func oauthCallbackHandler(state string, resultCh chan<- callbackResult) http.Handler { + mux := http.NewServeMux() + mux.HandleFunc("/auth/callback", func(w http.ResponseWriter, r *http.Request) { + if r.URL.Query().Get("state") != state { + resultCh <- callbackResult{err: fmt.Errorf("state mismatch")} + http.Error(w, "State mismatch", http.StatusBadRequest) + return + } + + code := r.URL.Query().Get("code") + if code == "" { + errMsg := r.URL.Query().Get("error") + resultCh <- callbackResult{err: fmt.Errorf("no code received: %s", errMsg)} + http.Error(w, "No authorization code received", http.StatusBadRequest) + return + } + + w.Header().Set("Content-Type", "text/html") + fmt.Fprint(w, "You can close this window.
") + resultCh <- callbackResult{code: code} + }) + return mux +} + +func listenOAuthCallback(port int) (net.Listener, int, error) { + listener, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port)) + if err != nil { + return nil, 0, err + } + + tcpAddr, ok := listener.Addr().(*net.TCPAddr) + if !ok { + _ = listener.Close() + return nil, 0, fmt.Errorf("unexpected listener address type %T", listener.Addr()) + } + + return listener, tcpAddr.Port, nil +} + type callbackResult struct { code string err error diff --git a/pkg/auth/oauth_test.go b/pkg/auth/oauth_test.go index 230ac7c2a..b318934f9 100644 --- a/pkg/auth/oauth_test.go +++ b/pkg/auth/oauth_test.go @@ -3,6 +3,7 @@ package auth import ( "encoding/base64" "encoding/json" + "net" "net/http" "net/http/httptest" "net/url" @@ -373,3 +374,118 @@ func TestParseDeviceCodeResponseInvalidInterval(t *testing.T) { t.Fatal("expected error for invalid interval") } } + +func TestLoginBrowserWithOptionsNoBrowserDoesNotRequireCallbackPort(t *testing.T) { + server := newMockOAuthTokenServer() + defer server.Close() + reservedListener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatalf("net.Listen() error: %v", err) + } + defer reservedListener.Close() + + reservedPort := reservedListener.Addr().(*net.TCPAddr).Port + origOpenBrowserFunc := openBrowserFunc + origBrowserLoginInput := browserLoginInput + t.Cleanup(func() { + openBrowserFunc = origOpenBrowserFunc + browserLoginInput = origBrowserLoginInput + }) + + var openCalls int + openBrowserFunc = func(string) error { + openCalls++ + return nil + } + browserLoginInput = strings.NewReader("manual-code\n") + + cfg := OAuthProviderConfig{ + Issuer: server.URL, + ClientID: "test-client", + Scopes: "openid", + Port: reservedPort, + } + + cred, err := LoginBrowserWithOptions(cfg, LoginBrowserOptions{NoBrowser: true}) + if err != nil { + t.Fatalf("LoginBrowserWithOptions() error: %v", err) + } + + if openCalls != 0 { + t.Fatalf("openBrowserFunc call count = %d, want 0", openCalls) + } + if cred.AccessToken != "mock-access-token" { + t.Fatalf("AccessToken = %q, want %q", cred.AccessToken, "mock-access-token") + } +} + +func TestLoginBrowserWithOptionsAutoOpensByDefault(t *testing.T) { + server := newMockOAuthTokenServer() + defer server.Close() + + origOpenBrowserFunc := openBrowserFunc + origBrowserLoginInput := browserLoginInput + t.Cleanup(func() { + openBrowserFunc = origOpenBrowserFunc + browserLoginInput = origBrowserLoginInput + }) + + var ( + openCalls int + browserURL string + ) + openBrowserFunc = func(url string) error { + openCalls++ + browserURL = url + return nil + } + browserLoginInput = strings.NewReader("manual-code\n") + + cfg := OAuthProviderConfig{ + Issuer: server.URL, + ClientID: "test-client", + Scopes: "openid", + Port: 0, + } + + _, err := LoginBrowserWithOptions(cfg, LoginBrowserOptions{}) + if err != nil { + t.Fatalf("LoginBrowserWithOptions() error: %v", err) + } + + if openCalls != 1 { + t.Fatalf("openBrowserFunc call count = %d, want 1", openCalls) + } + + parsedBrowserURL, err := url.Parse(browserURL) + if err != nil { + t.Fatalf("url.Parse(browserURL) error: %v", err) + } + + redirectURI, err := url.Parse(parsedBrowserURL.Query().Get("redirect_uri")) + if err != nil { + t.Fatalf("url.Parse(redirectURI) error: %v", err) + } + if redirectURI.Port() == "" { + t.Fatal("redirectURI port is empty") + } + if redirectURI.Port() == "0" { + t.Fatalf("redirectURI port = %q, want dynamically assigned port", redirectURI.Port()) + } +} + +func newMockOAuthTokenServer() *httptest.Server { + return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/oauth/token" { + http.Error(w, "not found", http.StatusNotFound) + return + } + + resp := map[string]any{ + "access_token": "mock-access-token", + "refresh_token": "mock-refresh-token", + "expires_in": 3600, + } + _ = json.NewEncoder(w).Encode(resp) + })) +} diff --git a/pkg/bus/bus.go b/pkg/bus/bus.go index a9c74ef90..9a05d4f95 100644 --- a/pkg/bus/bus.go +++ b/pkg/bus/bus.go @@ -12,6 +12,12 @@ import ( // ErrBusClosed is returned when publishing to a closed MessageBus. var ErrBusClosed = errors.New("message bus closed") +var ( + ErrMissingInboundContext = errors.New("inbound message context is required") + ErrMissingOutboundContext = errors.New("outbound message context is required") + ErrMissingOutboundMediaContext = errors.New("outbound media context is required") +) + const defaultBusBufferSize = 64 // StreamDelegate is implemented by the channel Manager to provide streaming @@ -49,7 +55,7 @@ func NewMessageBus() *MessageBus { inbound: make(chan InboundMessage, defaultBusBufferSize), outbound: make(chan OutboundMessage, defaultBusBufferSize), outboundMedia: make(chan OutboundMediaMessage, defaultBusBufferSize), - audioChunks: make(chan AudioChunk, defaultBusBufferSize*4), // Audio chunks need more buffer + audioChunks: make(chan AudioChunk, defaultBusBufferSize*4), // Audio chunks need more buffer. voiceControls: make(chan VoiceControl, defaultBusBufferSize), done: make(chan struct{}), } @@ -84,6 +90,10 @@ func publish[T any](ctx context.Context, mb *MessageBus, ch chan T, msg T) error } func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) error { + msg = NormalizeInboundMessage(msg) + if msg.Context.isZero() { + return ErrMissingInboundContext + } return publish(ctx, mb, mb.inbound, msg) } @@ -92,6 +102,10 @@ func (mb *MessageBus) InboundChan() <-chan InboundMessage { } func (mb *MessageBus) PublishOutbound(ctx context.Context, msg OutboundMessage) error { + msg = NormalizeOutboundMessage(msg) + if msg.Context.isZero() { + return ErrMissingOutboundContext + } return publish(ctx, mb, mb.outbound, msg) } @@ -100,6 +114,10 @@ func (mb *MessageBus) OutboundChan() <-chan OutboundMessage { } func (mb *MessageBus) PublishOutboundMedia(ctx context.Context, msg OutboundMediaMessage) error { + msg = NormalizeOutboundMediaMessage(msg) + if msg.Context.isZero() { + return ErrMissingOutboundMediaContext + } return publish(ctx, mb, mb.outboundMedia, msg) } diff --git a/pkg/bus/bus_test.go b/pkg/bus/bus_test.go index 9b6324ca6..5145d4759 100644 --- a/pkg/bus/bus_test.go +++ b/pkg/bus/bus_test.go @@ -14,10 +14,13 @@ func TestPublishConsume(t *testing.T) { ctx := context.Background() msg := InboundMessage{ - Channel: "test", - SenderID: "user1", - ChatID: "chat1", - Content: "hello", + Context: InboundContext{ + Channel: "test", + ChatID: "chat1", + ChatType: "direct", + SenderID: "user1", + }, + Content: "hello", } if err := mb.PublishInbound(ctx, msg); err != nil { @@ -34,6 +37,138 @@ func TestPublishConsume(t *testing.T) { if got.Channel != "test" { t.Fatalf("expected channel 'test', got %q", got.Channel) } + if got.Context.Channel != "test" { + t.Fatalf("expected context channel 'test', got %q", got.Context.Channel) + } + if got.Context.ChatID != "chat1" { + t.Fatalf("expected context chat ID 'chat1', got %q", got.Context.ChatID) + } + if got.Context.SenderID != "user1" { + t.Fatalf("expected context sender ID 'user1', got %q", got.Context.SenderID) + } +} + +func TestPublishInbound_NormalizesContext(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := InboundMessage{ + Context: InboundContext{ + Channel: "slack", + Account: "workspace-a", + ChatID: "C456/1712", + ChatType: "group", + TopicID: "1712", + SpaceID: "T001", + SpaceType: "team", + SenderID: "U123", + MessageID: "1712.01", + ReplyToMessageID: "1700.01", + Mentioned: true, + }, + Content: "hello", + } + + if err := mb.PublishInbound(context.Background(), msg); err != nil { + t.Fatalf("PublishInbound failed: %v", err) + } + + got := <-mb.InboundChan() + if got.Context.Channel != "slack" { + t.Fatalf("expected context channel slack, got %q", got.Context.Channel) + } + if got.Context.Account != "workspace-a" { + t.Fatalf("expected context account workspace-a, got %q", got.Context.Account) + } + if got.Context.ChatType != "group" { + t.Fatalf("expected context chat type group, got %q", got.Context.ChatType) + } + if got.Context.TopicID != "1712" { + t.Fatalf("expected topic 1712, got %q", got.Context.TopicID) + } + if got.Context.SpaceType != "team" || got.Context.SpaceID != "T001" { + t.Fatalf("expected team space T001, got %q/%q", got.Context.SpaceType, got.Context.SpaceID) + } + if !got.Context.Mentioned { + t.Fatal("expected mentioned=true in context") + } + if got.Context.ReplyToMessageID != "1700.01" { + t.Fatalf("expected reply_to_message_id 1700.01, got %q", got.Context.ReplyToMessageID) + } +} + +func TestPublishInbound_MirrorsContextIntoConvenienceFields(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := InboundMessage{ + Context: InboundContext{ + Channel: "telegram", + Account: "bot-a", + ChatID: "-1001", + ChatType: "group", + TopicID: "42", + SpaceID: "guild-9", + SpaceType: "guild", + SenderID: "user-1", + MessageID: "777", + Mentioned: true, + ReplyToMessageID: "666", + }, + Content: "hi", + } + + if err := mb.PublishInbound(context.Background(), msg); err != nil { + t.Fatalf("PublishInbound failed: %v", err) + } + + got := <-mb.InboundChan() + if got.Channel != "telegram" { + t.Fatalf("expected legacy channel telegram, got %q", got.Channel) + } + if got.ChatID != "-1001" { + t.Fatalf("expected legacy chat ID -1001, got %q", got.ChatID) + } + if got.SenderID != "user-1" { + t.Fatalf("expected legacy sender ID user-1, got %q", got.SenderID) + } + if got.MessageID != "777" { + t.Fatalf("expected legacy message ID 777, got %q", got.MessageID) + } + if got.Context.Account != "bot-a" || got.Context.SpaceID != "guild-9" || got.Context.TopicID != "42" { + t.Fatalf("unexpected normalized context: %+v", got.Context) + } +} + +func TestPublishInbound_BackfillsContextFromLegacyFields(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := InboundMessage{ + Channel: "pico", + ChatID: "session-1", + SenderID: "user-1", + MessageID: "msg-1", + Content: "hello", + } + + if err := mb.PublishInbound(context.Background(), msg); err != nil { + t.Fatalf("PublishInbound failed: %v", err) + } + + got := <-mb.InboundChan() + if got.Context.Channel != "pico" { + t.Fatalf("expected context channel pico, got %q", got.Context.Channel) + } + if got.Context.ChatID != "session-1" { + t.Fatalf("expected context chat ID session-1, got %q", got.Context.ChatID) + } + if got.Context.SenderID != "user-1" { + t.Fatalf("expected context sender ID user-1, got %q", got.Context.SenderID) + } + if got.Context.MessageID != "msg-1" { + t.Fatalf("expected context message ID msg-1, got %q", got.Context.MessageID) + } } func TestPublishOutboundSubscribe(t *testing.T) { @@ -43,8 +178,10 @@ func TestPublishOutboundSubscribe(t *testing.T) { ctx := context.Background() msg := OutboundMessage{ - Channel: "telegram", - ChatID: "123", + Context: InboundContext{ + Channel: "telegram", + ChatID: "123", + }, Content: "world", } @@ -59,6 +196,222 @@ func TestPublishOutboundSubscribe(t *testing.T) { if got.Content != "world" { t.Fatalf("expected content 'world', got %q", got.Content) } + if got.Context.Channel != "telegram" || got.Context.ChatID != "123" { + t.Fatalf("expected normalized outbound context, got %+v", got.Context) + } +} + +func TestPublishOutbound_MirrorsContextToLegacyFields(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := OutboundMessage{ + Context: InboundContext{ + Channel: "telegram", + ChatID: "chat-42", + ReplyToMessageID: "msg-9", + }, + AgentID: "main", + SessionKey: "sk_v1_123", + Scope: &OutboundScope{ + Version: 1, + AgentID: "main", + Channel: "telegram", + Account: "bot-a", + Dimensions: []string{"chat", "sender"}, + Values: map[string]string{ + "chat": "direct:chat-42", + "sender": "user-1", + }, + }, + Content: "reply", + } + + if err := mb.PublishOutbound(context.Background(), msg); err != nil { + t.Fatalf("PublishOutbound failed: %v", err) + } + + got := <-mb.OutboundChan() + if got.Channel != "telegram" { + t.Fatalf("expected legacy channel telegram, got %q", got.Channel) + } + if got.ChatID != "chat-42" { + t.Fatalf("expected legacy chat ID chat-42, got %q", got.ChatID) + } + if got.ReplyToMessageID != "msg-9" { + t.Fatalf("expected mirrored reply_to_message_id msg-9, got %q", got.ReplyToMessageID) + } + if got.AgentID != "main" || got.SessionKey != "sk_v1_123" { + t.Fatalf("unexpected outbound turn metadata: agent=%q session=%q", got.AgentID, got.SessionKey) + } + if got.Scope == nil || got.Scope.AgentID != "main" || got.Scope.Values["chat"] != "direct:chat-42" { + t.Fatalf("unexpected outbound scope: %+v", got.Scope) + } + if got.Context.Channel != "telegram" || got.Context.ChatID != "chat-42" { + t.Fatalf("unexpected outbound context: %+v", got.Context) + } +} + +func TestPublishOutbound_PreservesExplicitReplyToMessageID(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := OutboundMessage{ + Context: InboundContext{ + Channel: "telegram", + ChatID: "chat-42", + }, + ReplyToMessageID: "msg-9", + Content: "reply", + } + + if err := mb.PublishOutbound(context.Background(), msg); err != nil { + t.Fatalf("PublishOutbound failed: %v", err) + } + + got := <-mb.OutboundChan() + if got.ReplyToMessageID != "msg-9" { + t.Fatalf("expected mirrored reply_to_message_id msg-9, got %q", got.ReplyToMessageID) + } + if got.Context.ReplyToMessageID != "msg-9" { + t.Fatalf("expected context reply_to_message_id msg-9, got %q", got.Context.ReplyToMessageID) + } +} + +func TestPublishOutbound_PreservesExplicitReplyToMessageIDWhenContextReplyIsBlank(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := OutboundMessage{ + Context: InboundContext{ + Channel: "telegram", + ChatID: "chat-42", + ReplyToMessageID: " ", + }, + ReplyToMessageID: "msg-9", + Content: "reply", + } + + if err := mb.PublishOutbound(context.Background(), msg); err != nil { + t.Fatalf("PublishOutbound failed: %v", err) + } + + got := <-mb.OutboundChan() + if got.ReplyToMessageID != "msg-9" { + t.Fatalf("expected mirrored reply_to_message_id msg-9, got %q", got.ReplyToMessageID) + } + if got.Context.ReplyToMessageID != "msg-9" { + t.Fatalf("expected context reply_to_message_id msg-9, got %q", got.Context.ReplyToMessageID) + } +} + +func TestPublishOutboundMedia_MirrorsContextToLegacyFields(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + msg := OutboundMediaMessage{ + Context: InboundContext{ + Channel: "slack", + ChatID: "C001", + }, + AgentID: "support", + SessionKey: "sk_v1_media", + Scope: &OutboundScope{ + Version: 1, + AgentID: "support", + Channel: "slack", + Dimensions: []string{"chat"}, + Values: map[string]string{ + "chat": "channel:c001", + }, + }, + Parts: []MediaPart{{Type: "image", Ref: "media://1"}}, + } + + if err := mb.PublishOutboundMedia(context.Background(), msg); err != nil { + t.Fatalf("PublishOutboundMedia failed: %v", err) + } + + got := <-mb.OutboundMediaChan() + if got.Channel != "slack" { + t.Fatalf("expected legacy channel slack, got %q", got.Channel) + } + if got.ChatID != "C001" { + t.Fatalf("expected legacy chat ID C001, got %q", got.ChatID) + } + if got.AgentID != "support" || got.SessionKey != "sk_v1_media" { + t.Fatalf("unexpected outbound media turn metadata: agent=%q session=%q", got.AgentID, got.SessionKey) + } + if got.Scope == nil || got.Scope.Values["chat"] != "channel:c001" { + t.Fatalf("unexpected outbound media scope: %+v", got.Scope) + } + if got.Context.Channel != "slack" || got.Context.ChatID != "C001" { + t.Fatalf("unexpected outbound media context: %+v", got.Context) + } +} + +func TestPublishAudioChunkSubscribe(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + chunk := AudioChunk{ + SessionID: "voice-1", + SpeakerID: "speaker-1", + ChatID: "chat-1", + Channel: "discord", + Sequence: 7, + Format: "opus", + Data: []byte{0x01, 0x02}, + } + + if err := mb.PublishAudioChunk(context.Background(), chunk); err != nil { + t.Fatalf("PublishAudioChunk failed: %v", err) + } + + got, ok := <-mb.AudioChunksChan() + if !ok { + t.Fatal("AudioChunksChan returned ok=false") + } + if got.SessionID != "voice-1" || got.Sequence != 7 { + t.Fatalf("unexpected audio chunk: %+v", got) + } +} + +func TestPublishVoiceControlSubscribe(t *testing.T) { + mb := NewMessageBus() + defer mb.Close() + + ctrl := VoiceControl{ + SessionID: "voice-1", + ChatID: "chat-1", + Type: "command", + Action: "start", + } + + if err := mb.PublishVoiceControl(context.Background(), ctrl); err != nil { + t.Fatalf("PublishVoiceControl failed: %v", err) + } + + got, ok := <-mb.VoiceControlsChan() + if !ok { + t.Fatal("VoiceControlsChan returned ok=false") + } + if got.Type != "command" || got.Action != "start" { + t.Fatalf("unexpected voice control: %+v", got) + } +} + +func TestNewOutboundContext_NormalizesReplyAddress(t *testing.T) { + ctx := NewOutboundContext(" telegram ", " chat-42 ", " msg-9 ") + if ctx.Channel != "telegram" { + t.Fatalf("expected channel telegram, got %q", ctx.Channel) + } + if ctx.ChatID != "chat-42" { + t.Fatalf("expected chat_id chat-42, got %q", ctx.ChatID) + } + if ctx.ReplyToMessageID != "msg-9" { + t.Fatalf("expected reply_to_message_id msg-9, got %q", ctx.ReplyToMessageID) + } } func TestPublishInbound_ContextCancel(t *testing.T) { @@ -68,7 +421,15 @@ func TestPublishInbound_ContextCancel(t *testing.T) { // Fill the buffer ctx := context.Background() for i := range defaultBusBufferSize { - if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil { + if err := mb.PublishInbound(ctx, InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat-fill", + ChatType: "direct", + SenderID: "user-fill", + }, + Content: "fill", + }); err != nil { t.Fatalf("fill failed at %d: %v", i, err) } } @@ -77,7 +438,15 @@ func TestPublishInbound_ContextCancel(t *testing.T) { cancelCtx, cancel := context.WithCancel(context.Background()) cancel() - err := mb.PublishInbound(cancelCtx, InboundMessage{Content: "overflow"}) + err := mb.PublishInbound(cancelCtx, InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat-overflow", + ChatType: "direct", + SenderID: "user-overflow", + }, + Content: "overflow", + }) if err == nil { t.Fatal("expected error from canceled context, got nil") } @@ -90,7 +459,15 @@ func TestPublishInbound_BusClosed(t *testing.T) { mb := NewMessageBus() mb.Close() - err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"}) + err := mb.PublishInbound(context.Background(), InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat1", + ChatType: "direct", + SenderID: "user1", + }, + Content: "test", + }) if err != ErrBusClosed { t.Fatalf("expected ErrBusClosed, got %v", err) } @@ -100,7 +477,13 @@ func TestPublishOutbound_BusClosed(t *testing.T) { mb := NewMessageBus() mb.Close() - err := mb.PublishOutbound(context.Background(), OutboundMessage{Content: "test"}) + err := mb.PublishOutbound(context.Background(), OutboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat1", + }, + Content: "test", + }) if err != ErrBusClosed { t.Fatalf("expected ErrBusClosed, got %v", err) } @@ -112,14 +495,30 @@ func TestConsumeInbound_ContextCancel(t *testing.T) { defer mb.Close() for i := range defaultBusBufferSize { - if err := mb.PublishInbound(context.Background(), InboundMessage{Content: "fill"}); err != nil { + if err := mb.PublishInbound(context.Background(), InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat-fill", + ChatType: "direct", + SenderID: "user-fill", + }, + Content: "fill", + }); err != nil { t.Fatalf("fill failed at %d: %v", i, err) } } ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) defer cancel() - mb.PublishInbound(ctx, InboundMessage{Content: "ContextCancel"}) + mb.PublishInbound(ctx, InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat-cancel", + ChatType: "direct", + SenderID: "user-cancel", + }, + Content: "ContextCancel", + }) select { case <-ctx.Done(): @@ -213,7 +612,15 @@ func TestPublishInbound_FullBuffer(t *testing.T) { // Fill the buffer for i := range defaultBusBufferSize { - if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil { + if err := mb.PublishInbound(ctx, InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat-fill", + ChatType: "direct", + SenderID: "user-fill", + }, + Content: "fill", + }); err != nil { t.Fatalf("fill failed at %d: %v", i, err) } } @@ -222,7 +629,15 @@ func TestPublishInbound_FullBuffer(t *testing.T) { timeoutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond) defer cancel() - err := mb.PublishInbound(timeoutCtx, InboundMessage{Content: "overflow"}) + err := mb.PublishInbound(timeoutCtx, InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat-overflow", + ChatType: "direct", + SenderID: "user-overflow", + }, + Content: "overflow", + }) if err == nil { t.Fatal("expected error when buffer is full and context times out") } @@ -240,7 +655,15 @@ func TestCloseIdempotent(t *testing.T) { mb.Close() // After close, publish should return ErrBusClosed - err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"}) + err := mb.PublishInbound(context.Background(), InboundMessage{ + Context: InboundContext{ + Channel: "test", + ChatID: "chat1", + ChatType: "direct", + SenderID: "user1", + }, + Content: "test", + }) if err != ErrBusClosed { t.Fatalf("expected ErrBusClosed after multiple closes, got %v", err) } diff --git a/pkg/bus/inbound_context.go b/pkg/bus/inbound_context.go new file mode 100644 index 000000000..d6be80565 --- /dev/null +++ b/pkg/bus/inbound_context.go @@ -0,0 +1,81 @@ +package bus + +import "strings" + +// NormalizeInboundMessage ensures the inbound context is normalized and keeps +// convenience mirrors in sync for runtime consumers. +func NormalizeInboundMessage(msg InboundMessage) InboundMessage { + if msg.Context.Channel == "" { + msg.Context.Channel = msg.Channel + } + if msg.Context.ChatID == "" { + msg.Context.ChatID = msg.ChatID + } + if msg.Context.SenderID == "" { + msg.Context.SenderID = msg.SenderID + } + if msg.Context.MessageID == "" { + msg.Context.MessageID = msg.MessageID + } + msg.Context = normalizeInboundContext(msg.Context) + msg.Channel = msg.Context.Channel + msg.SenderID = msg.Context.SenderID + msg.ChatID = msg.Context.ChatID + if msg.MessageID == "" { + msg.MessageID = msg.Context.MessageID + } + if msg.Context.MessageID == "" { + msg.Context.MessageID = msg.MessageID + } + return msg +} + +func (ctx InboundContext) isZero() bool { + return ctx.Channel == "" && + ctx.Account == "" && + ctx.ChatID == "" && + ctx.ChatType == "" && + ctx.TopicID == "" && + ctx.SpaceID == "" && + ctx.SpaceType == "" && + ctx.SenderID == "" && + ctx.MessageID == "" && + !ctx.Mentioned && + ctx.ReplyToMessageID == "" && + ctx.ReplyToSenderID == "" && + len(ctx.ReplyHandles) == 0 && + len(ctx.Raw) == 0 +} + +func normalizeInboundContext(ctx InboundContext) InboundContext { + ctx.Channel = strings.TrimSpace(ctx.Channel) + ctx.Account = strings.TrimSpace(ctx.Account) + ctx.ChatID = strings.TrimSpace(ctx.ChatID) + ctx.ChatType = normalizeKind(ctx.ChatType) + ctx.TopicID = strings.TrimSpace(ctx.TopicID) + ctx.SpaceID = strings.TrimSpace(ctx.SpaceID) + ctx.SpaceType = normalizeKind(ctx.SpaceType) + ctx.SenderID = strings.TrimSpace(ctx.SenderID) + ctx.MessageID = strings.TrimSpace(ctx.MessageID) + ctx.ReplyToMessageID = strings.TrimSpace(ctx.ReplyToMessageID) + ctx.ReplyToSenderID = strings.TrimSpace(ctx.ReplyToSenderID) + ctx.ReplyHandles = cloneStringMap(ctx.ReplyHandles) + ctx.Raw = cloneStringMap(ctx.Raw) + return ctx +} + +func cloneStringMap(src map[string]string) map[string]string { + if len(src) == 0 { + return nil + } + + dst := make(map[string]string, len(src)) + for k, v := range src { + dst[k] = v + } + return dst +} + +func normalizeKind(kind string) string { + return strings.ToLower(strings.TrimSpace(kind)) +} diff --git a/pkg/bus/outbound_context.go b/pkg/bus/outbound_context.go new file mode 100644 index 000000000..cbbbc99c7 --- /dev/null +++ b/pkg/bus/outbound_context.go @@ -0,0 +1,84 @@ +package bus + +import "strings" + +// NewOutboundContext builds the minimal normalized addressing context required +// to deliver an outbound text message or reply. +func NewOutboundContext(channel, chatID, replyToMessageID string) InboundContext { + return normalizeInboundContext(InboundContext{ + Channel: strings.TrimSpace(channel), + ChatID: strings.TrimSpace(chatID), + ReplyToMessageID: strings.TrimSpace(replyToMessageID), + }) +} + +// NormalizeOutboundMessage ensures Context is normalized and keeps convenience +// mirrors in sync for runtime consumers. +func NormalizeOutboundMessage(msg OutboundMessage) OutboundMessage { + msg.Channel = strings.TrimSpace(msg.Channel) + msg.ChatID = strings.TrimSpace(msg.ChatID) + msg.ReplyToMessageID = strings.TrimSpace(msg.ReplyToMessageID) + if msg.Context.Channel == "" { + msg.Context.Channel = msg.Channel + } + if msg.Context.ChatID == "" { + msg.Context.ChatID = msg.ChatID + } + if msg.Context.ReplyToMessageID == "" { + msg.Context.ReplyToMessageID = msg.ReplyToMessageID + } + msg.Context = normalizeInboundContext(msg.Context) + if msg.Channel == "" { + msg.Channel = msg.Context.Channel + } + if msg.ChatID == "" { + msg.ChatID = msg.Context.ChatID + } + if msg.ReplyToMessageID == "" { + msg.ReplyToMessageID = msg.Context.ReplyToMessageID + } + if msg.Context.ReplyToMessageID == "" { + msg.Context.ReplyToMessageID = msg.ReplyToMessageID + } + msg.Scope = cloneOutboundScope(msg.Scope) + return msg +} + +// NormalizeOutboundMediaMessage ensures media outbound messages also carry a +// normalized context while keeping convenience mirrors in sync. +func NormalizeOutboundMediaMessage(msg OutboundMediaMessage) OutboundMediaMessage { + msg.Channel = strings.TrimSpace(msg.Channel) + msg.ChatID = strings.TrimSpace(msg.ChatID) + if msg.Context.Channel == "" { + msg.Context.Channel = msg.Channel + } + if msg.Context.ChatID == "" { + msg.Context.ChatID = msg.ChatID + } + msg.Context = normalizeInboundContext(msg.Context) + if msg.Channel == "" { + msg.Channel = msg.Context.Channel + } + if msg.ChatID == "" { + msg.ChatID = msg.Context.ChatID + } + msg.Scope = cloneOutboundScope(msg.Scope) + return msg +} + +func cloneOutboundScope(scope *OutboundScope) *OutboundScope { + if scope == nil { + return nil + } + cloned := *scope + if len(scope.Dimensions) > 0 { + cloned.Dimensions = append([]string(nil), scope.Dimensions...) + } + if len(scope.Values) > 0 { + cloned.Values = make(map[string]string, len(scope.Values)) + for key, value := range scope.Values { + cloned.Values[key] = value + } + } + return &cloned +} diff --git a/pkg/bus/types.go b/pkg/bus/types.go index 27cf61b5f..aa06ca173 100644 --- a/pkg/bus/types.go +++ b/pkg/bus/types.go @@ -1,11 +1,5 @@ package bus -// Peer identifies the routing peer for a message (direct, group, channel, etc.) -type Peer struct { - Kind string `json:"kind"` // "direct" | "group" | "channel" | "" - ID string `json:"id"` -} - // SenderInfo provides structured sender identity information. type SenderInfo struct { Platform string `json:"platform,omitempty"` // "telegram", "discord", "slack", ... @@ -15,26 +9,67 @@ type SenderInfo struct { DisplayName string `json:"display_name,omitempty"` // display name } +// InboundContext captures the normalized, platform-agnostic facts about an +// inbound message. This is the source of truth for routing and session +// allocation. +type InboundContext struct { + Channel string `json:"channel"` + Account string `json:"account,omitempty"` + + ChatID string `json:"chat_id"` + ChatType string `json:"chat_type,omitempty"` // direct / group / channel + TopicID string `json:"topic_id,omitempty"` + + SpaceID string `json:"space_id,omitempty"` + SpaceType string `json:"space_type,omitempty"` // guild / team / workspace / tenant + + SenderID string `json:"sender_id"` + MessageID string `json:"message_id,omitempty"` + + Mentioned bool `json:"mentioned,omitempty"` + + ReplyToMessageID string `json:"reply_to_message_id,omitempty"` + ReplyToSenderID string `json:"reply_to_sender_id,omitempty"` + + ReplyHandles map[string]string `json:"reply_handles,omitempty"` + Raw map[string]string `json:"raw,omitempty"` +} + type InboundMessage struct { - Channel string `json:"channel"` - SenderID string `json:"sender_id"` - Sender SenderInfo `json:"sender"` - ChatID string `json:"chat_id"` - Content string `json:"content"` - Media []string `json:"media,omitempty"` - Peer Peer `json:"peer"` // routing peer - MessageID string `json:"message_id,omitempty"` // platform message ID - MediaScope string `json:"media_scope,omitempty"` // media lifecycle scope - SessionKey string `json:"session_key"` - Metadata map[string]string `json:"metadata,omitempty"` + Context InboundContext `json:"context"` + Sender SenderInfo `json:"sender"` + Content string `json:"content"` + Media []string `json:"media,omitempty"` + MediaScope string `json:"media_scope,omitempty"` // media lifecycle scope + SessionKey string `json:"session_key"` + + // Convenience mirrors derived from Context for runtime consumers. + Channel string `json:"channel"` + SenderID string `json:"sender_id"` + ChatID string `json:"chat_id"` + MessageID string `json:"message_id,omitempty"` // platform message ID +} + +// OutboundScope captures the structured session scope associated with an +// outbound turn result without depending on the session package. +type OutboundScope struct { + Version int `json:"version,omitempty"` + AgentID string `json:"agent_id,omitempty"` + Channel string `json:"channel,omitempty"` + Account string `json:"account,omitempty"` + Dimensions []string `json:"dimensions,omitempty"` + Values map[string]string `json:"values,omitempty"` } type OutboundMessage struct { - Channel string `json:"channel"` - ChatID string `json:"chat_id"` - Content string `json:"content"` - ReplyToMessageID string `json:"reply_to_message_id,omitempty"` - Metadata map[string]string `json:"metadata,omitempty"` + Channel string `json:"channel"` + ChatID string `json:"chat_id"` + Context InboundContext `json:"context"` + AgentID string `json:"agent_id,omitempty"` + SessionKey string `json:"session_key,omitempty"` + Scope *OutboundScope `json:"scope,omitempty"` + Content string `json:"content"` + ReplyToMessageID string `json:"reply_to_message_id,omitempty"` } // MediaPart describes a single media attachment to send. @@ -48,9 +83,13 @@ type MediaPart struct { // OutboundMediaMessage carries media attachments from Agent to channels via the bus. type OutboundMediaMessage struct { - Channel string `json:"channel"` - ChatID string `json:"chat_id"` - Parts []MediaPart `json:"parts"` + Channel string `json:"channel"` + ChatID string `json:"chat_id"` + Context InboundContext `json:"context"` + AgentID string `json:"agent_id,omitempty"` + SessionKey string `json:"session_key,omitempty"` + Scope *OutboundScope `json:"scope,omitempty"` + Parts []MediaPart `json:"parts"` } // AudioChunk represents a chunk of streaming voice data. diff --git a/pkg/channels/README.md b/pkg/channels/README.md index c4d12ef59..1cab1a4a6 100644 --- a/pkg/channels/README.md +++ b/pkg/channels/README.md @@ -327,8 +327,13 @@ import ( ) func init() { - channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewTelegramChannel(cfg, b) + channels.RegisterFactory(config.ChannelTelegram, func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { return nil, err } + c, ok := decoded.(*config.TelegramSettings) + if !ok { return nil, channels.ErrSendFailed } + return NewTelegramChannel(bc, c, b) }) } ``` @@ -427,8 +432,13 @@ import ( ) func init() { - channels.RegisterFactory("matrix", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewMatrixChannel(cfg, b) + channels.RegisterFactory(config.ChannelMatrix, func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { return nil, err } + c, ok := decoded.(*config.MatrixSettings) + if !ok { return nil, channels.ErrSendFailed } + return NewMatrixChannel(bc, c, b) }) } ``` @@ -773,41 +783,59 @@ When the Agent finishes processing a message, Manager's `preSend` automatically: ### 3.5 Register Configuration and Gateway Integration -#### Add configuration in `pkg/config/config.go` +#### Add configuration entry + +Channels now use a unified map-based configuration (`map[string]*config.Channel`). +Each channel entry stores common fields (`enabled`, `type`, `allow_from`, etc.) at +the top level, with channel-specific settings in the `settings` sub-key: + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "type": "matrix", + "allow_from": ["@user:example.com"], + "settings": { + "home_server": "https://matrix.org", + "user_id": "@bot:example.com", + "access_token": "enc://..." + } + } + } +} +``` + +Secure fields (tokens, passwords, API keys) go into `.security.yml`: + +```yaml +channels: + matrix: + access_token: "your-matrix-access-token" +``` + +Channel types must be registered in `channelSettingsFactory` in +`pkg/config/config_channel.go`: ```go -type ChannelsConfig struct { +var channelSettingsFactory = map[string]any{ // ... existing channels - Matrix MatrixChannelConfig `json:"matrix"` -} - -type MatrixChannelConfig struct { - Enabled bool `json:"enabled"` - HomeServer string `json:"home_server"` - Token string `json:"token"` - AllowFrom []string `json:"allow_from"` - GroupTrigger GroupTriggerConfig `json:"group_trigger"` - Placeholder PlaceholderConfig `json:"placeholder"` - ReasoningChannelID string `json:"reasoning_channel_id"` + ChannelMatrix: (MatrixSettings{}), } ``` -#### Add entry in Manager.initChannels() +#### No Manager changes needed -```go -// In the initChannels() method of pkg/channels/manager.go -if m.config.Channels.Matrix.Enabled && m.config.Channels.Matrix.Token != "" { - m.initChannel("matrix", "Matrix") -} -``` +The Manager uses `InitChannelList()` to validate types and decode settings, +then looks up factories by `bc.Type`. No per-channel entry needed in Manager — +just register the factory and the config entry. -> **Note**: If your channel has multiple modes (like WhatsApp Bridge vs Native), branch in initChannels based on config: +> **Note**: If your channel has multiple modes (like WhatsApp Bridge vs Native), +> register both types in `channelSettingsFactory` and branch on config: > ```go -> if cfg.UseNative { -> m.initChannel("whatsapp_native", "WhatsApp Native") -> } else { -> m.initChannel("whatsapp", "WhatsApp") -> } +> // In config_channel.go: +> ChannelWhatsApp: (WhatsAppSettings{}), +> ChannelWhatsAppNative: (WhatsAppSettings{}), > ``` #### Add blank import in Gateway @@ -947,10 +975,29 @@ channels.WithReasoningChannelID(id) // Set reasoning chain routing target **File**: `pkg/channels/registry.go` ```go -type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error) +type ChannelFactory func(channelName, channelType string, cfg *config.Config, bus *bus.MessageBus) (Channel, error) -func RegisterFactory(name string, f ChannelFactory) // Called in sub-package init() -func getFactory(name string) (ChannelFactory, bool) // Called internally by Manager +func RegisterFactory(name string, f ChannelFactory) // Called in sub-package init() +func getFactory(name string) (ChannelFactory, bool) // Called internally by Manager +func GetRegisteredFactoryNames() []string // Returns all registered factory names +``` + +For convenience, `RegisterSafeFactory[S any]` provides automatic type-safe settings decoding: + +```go +// Instead of manual GetDecoded() + type assertion: +channels.RegisterFactory(config.ChannelTelegram, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { return nil, err } + c, ok := decoded.(*config.TelegramSettings) + if !ok { return nil, ErrSendFailed } + return NewTelegramChannel(bc, c, b) + }) + +// You can use RegisterSafeFactory (same safety, less boilerplate): +channels.RegisterSafeFactory(config.ChannelTelegram, NewTelegramChannel) ``` The factory registry is protected by `sync.RWMutex` and registrations occur during `init()` phase (completed at process startup). Manager looks up factories by name in `initChannel()` and calls them. diff --git a/pkg/channels/README.zh.md b/pkg/channels/README.zh.md index 3edc5cb6b..c44859c20 100644 --- a/pkg/channels/README.zh.md +++ b/pkg/channels/README.zh.md @@ -327,8 +327,13 @@ import ( ) func init() { - channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewTelegramChannel(cfg, b) + channels.RegisterFactory(config.ChannelTelegram, func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { return nil, err } + c, ok := decoded.(*config.TelegramSettings) + if !ok { return nil, channels.ErrSendFailed } + return NewTelegramChannel(bc, c, b) }) } ``` @@ -427,8 +432,13 @@ import ( ) func init() { - channels.RegisterFactory("matrix", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewMatrixChannel(cfg, b) + channels.RegisterFactory(config.ChannelMatrix, func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { return nil, err } + c, ok := decoded.(*config.MatrixSettings) + if !ok { return nil, channels.ErrSendFailed } + return NewMatrixChannel(bc, c, b) }) } ``` @@ -772,41 +782,58 @@ if c.owner != nil && c.placeholderRecorder != nil { ### 3.5 注册配置和 Gateway 接入 -#### 在 `pkg/config/config.go` 中添加配置 +#### 添加配置入口 + +Channels 现在使用统一的 map 类型配置（`map[string]*config.Channel`）。 +每个 channel 条目将通用字段（`enabled`、`type`、`allow_from` 等）放在顶层， +channel 特定的设置放在 `settings` 子键中： + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "type": "matrix", + "allow_from": ["@user:example.com"], + "settings": { + "home_server": "https://matrix.org", + "user_id": "@bot:example.com", + "access_token": "enc://..." + } + } + } +} +``` + +安全字段（token、密码、API 密钥）放入 `.security.yml`： + +```yaml +channels: + matrix: + access_token: "your-matrix-access-token" +``` + +Channel 类型必须在 `pkg/config/config_channel.go` 的 `channelSettingsFactory` 中注册： ```go -type ChannelsConfig struct { +var channelSettingsFactory = map[string]any{ // ... 现有 channels - Matrix MatrixChannelConfig `json:"matrix"` -} - -type MatrixChannelConfig struct { - Enabled bool `json:"enabled"` - HomeServer string `json:"home_server"` - Token string `json:"token"` - AllowFrom []string `json:"allow_from"` - GroupTrigger GroupTriggerConfig `json:"group_trigger"` - Placeholder PlaceholderConfig `json:"placeholder"` - ReasoningChannelID string `json:"reasoning_channel_id"` + ChannelMatrix: (MatrixSettings{}), } ``` -#### 在 Manager.initChannels() 中添加入口 +#### 无需修改 Manager -```go -// pkg/channels/manager.go 的 initChannels() 方法中 -if m.config.Channels.Matrix.Enabled && m.config.Channels.Matrix.Token != "" { - m.initChannel("matrix", "Matrix") -} -``` +Manager 使用 `InitChannelList()` 来验证类型和解码设置， +然后通过 `bc.Type` 查找工厂。不需要在 Manager 中添加每个 channel 的条目—— +只需注册工厂和配置条目即可。 -> **注意**：如果你的 channel 有多种模式（如 WhatsApp Bridge vs Native），需要在 initChannels 中根据配置分支： +> **注意**：如果你的 channel 有多种模式（如 WhatsApp Bridge vs Native）， +> 在 `channelSettingsFactory` 中注册两种类型，并根据配置分支： > ```go -> if cfg.UseNative { -> m.initChannel("whatsapp_native", "WhatsApp Native") -> } else { -> m.initChannel("whatsapp", "WhatsApp") -> } +> // 在 config_channel.go 中： +> ChannelWhatsApp: (WhatsAppSettings{}), +> ChannelWhatsAppNative: (WhatsAppSettings{}), > ``` #### 在 Gateway 中添加 blank import @@ -946,10 +973,29 @@ channels.WithReasoningChannelID(id) // 设置思维链路由目标 channe **文件**：`pkg/channels/registry.go` ```go -type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error) +type ChannelFactory func(channelName, channelType string, cfg *config.Config, bus *bus.MessageBus) (Channel, error) -func RegisterFactory(name string, f ChannelFactory) // 子包 init() 中调用 -func getFactory(name string) (ChannelFactory, bool) // Manager 内部调用 +func RegisterFactory(name string, f ChannelFactory) // 子包 init() 中调用 +func getFactory(name string) (ChannelFactory, bool) // Manager 内部调用 +func GetRegisteredFactoryNames() []string // 返回所有已注册的工厂名称 +``` + +为方便使用，`RegisterSafeFactory[S any]` 提供自动类型安全的设置解码： + +```go +// 不使用 RegisterSafeFactory（手动 GetDecoded() + 类型断言）： +channels.RegisterFactory(config.ChannelTelegram, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { return nil, err } + c, ok := decoded.(*config.TelegramSettings) + if !ok { return nil, ErrSendFailed } + return NewTelegramChannel(bc, c, b) + }) + +// 使用 RegisterSafeFactory（同等安全，减少样板代码）： +channels.RegisterSafeFactory(config.ChannelTelegram, NewTelegramChannel) ``` 工厂注册表使用 `sync.RWMutex` 保护，在 `init()` 阶段注册（进程启动时完成）。Manager 在 `initChannel()` 中通过名字查找工厂并调用它。 diff --git a/pkg/channels/base.go b/pkg/channels/base.go index bd4ced849..3585fb075 100644 --- a/pkg/channels/base.go +++ b/pkg/channels/base.go @@ -103,6 +103,16 @@ func NewBaseChannel( allowList []string, opts ...BaseChannelOption, ) *BaseChannel { + isEmpty := true + for _, s := range allowList { + if s != "" { + isEmpty = false + break + } + } + if isEmpty { + allowList = []string{} + } bc := &BaseChannel{ config: config, bus: bus, @@ -177,6 +187,12 @@ func (c *BaseChannel) Name() string { return c.name } +// SetName updates the channel name. Used by the manager after channel creation +// to ensure the name matches the config key (which may differ from the type). +func (c *BaseChannel) SetName(name string) { + c.name = name +} + func (c *BaseChannel) ReasoningChannelID() string { return c.reasoningChannelID } @@ -244,12 +260,11 @@ func (c *BaseChannel) IsAllowedSender(sender bus.SenderInfo) bool { return false } -func (c *BaseChannel) HandleMessage( +func (c *BaseChannel) HandleMessageWithContext( ctx context.Context, - peer bus.Peer, - messageID, senderID, chatID, content string, + deliveryChatID, content string, media []string, - metadata map[string]string, + inboundCtx bus.InboundContext, senderOpts ...bus.SenderInfo, ) { // Use SenderInfo-based allow check when available, else fall back to string @@ -257,6 +272,7 @@ func (c *BaseChannel) HandleMessage( if len(senderOpts) > 0 { sender = senderOpts[0] } + senderID := strings.TrimSpace(inboundCtx.SenderID) if sender.CanonicalID != "" || sender.PlatformID != "" { if !c.IsAllowedSender(sender) { return @@ -273,20 +289,28 @@ func (c *BaseChannel) HandleMessage( resolvedSenderID = sender.CanonicalID } - scope := BuildMediaScope(c.name, chatID, messageID) + if resolvedSenderID == "" { + resolvedSenderID = senderID + } + + inboundCtx.Channel = c.name + if inboundCtx.ChatID == "" { + inboundCtx.ChatID = deliveryChatID + } + if inboundCtx.SenderID == "" { + inboundCtx.SenderID = resolvedSenderID + } + + scope := BuildMediaScope(c.name, deliveryChatID, inboundCtx.MessageID) msg := bus.InboundMessage{ - Channel: c.name, - SenderID: resolvedSenderID, + Context: inboundCtx, Sender: sender, - ChatID: chatID, Content: content, Media: media, - Peer: peer, - MessageID: messageID, MediaScope: scope, - Metadata: metadata, } + msg = bus.NormalizeInboundMessage(msg) // Auto-trigger typing indicator, message reaction, and placeholder before publishing. // Each capability is independent — all three may fire for the same message. @@ -297,14 +321,14 @@ func (c *BaseChannel) HandleMessage( if c.owner != nil && c.placeholderRecorder != nil { // Typing if tc, ok := c.owner.(TypingCapable); ok { - if stop, err := tc.StartTyping(ctx, chatID); err == nil { - c.placeholderRecorder.RecordTypingStop(c.name, chatID, stop) + if stop, err := tc.StartTyping(ctx, deliveryChatID); err == nil { + c.placeholderRecorder.RecordTypingStop(c.name, deliveryChatID, stop) } } // Reaction - if rc, ok := c.owner.(ReactionCapable); ok && messageID != "" { - if undo, err := rc.ReactToMessage(ctx, chatID, messageID); err == nil { - c.placeholderRecorder.RecordReactionUndo(c.name, chatID, undo) + if rc, ok := c.owner.(ReactionCapable); ok && msg.MessageID != "" { + if undo, err := rc.ReactToMessage(ctx, deliveryChatID, msg.MessageID); err == nil { + c.placeholderRecorder.RecordReactionUndo(c.name, deliveryChatID, undo) } } // Placeholder — independent pipeline. @@ -313,8 +337,8 @@ func (c *BaseChannel) HandleMessage( // "Thinking…" only once the voice has been processed. if !audioAnnotationRe.MatchString(content) { if pc, ok := c.owner.(PlaceholderCapable); ok { - if phID, err := pc.SendPlaceholder(ctx, chatID); err == nil && phID != "" { - c.placeholderRecorder.RecordPlaceholder(c.name, chatID, phID) + if phID, err := pc.SendPlaceholder(ctx, deliveryChatID); err == nil && phID != "" { + c.placeholderRecorder.RecordPlaceholder(c.name, deliveryChatID, phID) } } } @@ -323,12 +347,24 @@ func (c *BaseChannel) HandleMessage( if err := c.bus.PublishInbound(ctx, msg); err != nil { logger.ErrorCF("channels", "Failed to publish inbound message", map[string]any{ "channel": c.name, - "chat_id": chatID, + "chat_id": deliveryChatID, "error": err.Error(), }) } } +// HandleInboundContext publishes a normalized inbound message using only the +// structured context. +func (c *BaseChannel) HandleInboundContext( + ctx context.Context, + deliveryChatID, content string, + media []string, + inboundCtx bus.InboundContext, + senderOpts ...bus.SenderInfo, +) { + c.HandleMessageWithContext(ctx, deliveryChatID, content, media, inboundCtx, senderOpts...) +} + func (c *BaseChannel) SetRunning(running bool) { c.running.Store(running) } diff --git a/pkg/channels/base_test.go b/pkg/channels/base_test.go index 6132b8bf9..04500f775 100644 --- a/pkg/channels/base_test.go +++ b/pkg/channels/base_test.go @@ -1,6 +1,7 @@ package channels import ( + "context" "testing" "github.com/sipeed/picoclaw/pkg/bus" @@ -263,3 +264,58 @@ func TestIsAllowedSender(t *testing.T) { }) } } + +func TestHandleInboundContext_PublishesNormalizedContext(t *testing.T) { + tests := []struct { + name string + inbound bus.InboundContext + wantChat string + wantSender string + }{ + { + name: "direct uses sender as peer", + inbound: bus.InboundContext{ + Channel: "test", + ChatID: "chat-1", + ChatType: "direct", + SenderID: "user-1", + MessageID: "msg-1", + }, + wantChat: "chat-1", + wantSender: "user-1", + }, + { + name: "group uses chat as peer", + inbound: bus.InboundContext{ + Channel: "test", + ChatID: "group-1", + ChatType: "group", + SenderID: "user-2", + MessageID: "msg-2", + }, + wantChat: "group-1", + wantSender: "user-2", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + msgBus := bus.NewMessageBus() + defer msgBus.Close() + + ch := NewBaseChannel("test", nil, msgBus, nil) + ch.HandleInboundContext(context.Background(), tt.inbound.ChatID, "hello", nil, tt.inbound) + + msg := <-msgBus.InboundChan() + if msg.ChatID != tt.wantChat { + t.Fatalf("ChatID = %q, want %q", msg.ChatID, tt.wantChat) + } + if msg.SenderID != tt.wantSender { + t.Fatalf("SenderID = %q, want %q", msg.SenderID, tt.wantSender) + } + if msg.Context.ChatType != tt.inbound.ChatType { + t.Fatalf("ChatType = %q, want %q", msg.Context.ChatType, tt.inbound.ChatType) + } + }) + } +} diff --git a/pkg/channels/dingtalk/dingtalk.go b/pkg/channels/dingtalk/dingtalk.go index 04ccec8a2..9cd461bc8 100644 --- a/pkg/channels/dingtalk/dingtalk.go +++ b/pkg/channels/dingtalk/dingtalk.go @@ -25,7 +25,7 @@ import ( // It uses WebSocket for receiving messages via stream mode and API for sending type DingTalkChannel struct { *channels.BaseChannel - config config.DingTalkConfig + config *config.DingTalkSettings clientID string clientSecret string streamClient *client.StreamClient @@ -36,7 +36,11 @@ type DingTalkChannel struct { } // NewDingTalkChannel creates a new DingTalk channel instance -func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (*DingTalkChannel, error) { +func NewDingTalkChannel( + bc *config.Channel, + cfg *config.DingTalkSettings, + messageBus *bus.MessageBus, +) (*DingTalkChannel, error) { if cfg.ClientID == "" || cfg.ClientSecret.String() == "" { return nil, fmt.Errorf("dingtalk client_id and client_secret are required") } @@ -44,10 +48,10 @@ func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) ( // Set the logger for the Stream SDK dinglog.SetLogger(logger.NewLogger("dingtalk")) - base := channels.NewBaseChannel("dingtalk", cfg, messageBus, cfg.AllowFrom, + base := channels.NewBaseChannel("dingtalk", cfg, messageBus, bc.AllowFrom, channels.WithMaxMessageLength(20000), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &DingTalkChannel{ @@ -181,16 +185,15 @@ func (c *DingTalkChannel) onChatBotMessageReceived( "session_webhook": data.SessionWebhook, } - var peer bus.Peer + var ( + chatType string + isMentioned bool + ) if data.ConversationType == "1" { - peerID := senderID - if peerID == "" { - peerID = chatID - } - peer = bus.Peer{Kind: "direct", ID: peerID} + chatType = "direct" } else { - peer = bus.Peer{Kind: "group", ID: data.ConversationId} - isMentioned := data.IsInAtList + chatType = "group" + isMentioned = data.IsInAtList if isMentioned { content = stripLeadingAtMentions(content) } @@ -228,8 +231,21 @@ func (c *DingTalkChannel) onChatBotMessageReceived( return nil, nil } - // Handle the message through the base channel - c.HandleMessage(ctx, peer, "", resolvedSenderID, chatID, content, nil, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: "dingtalk", + ChatID: chatID, + ChatType: chatType, + SenderID: resolvedSenderID, + Mentioned: isMentioned, + Raw: metadata, + } + if data.SessionWebhook != "" { + inboundCtx.ReplyHandles = map[string]string{ + "session_webhook": data.SessionWebhook, + } + } + + c.HandleInboundContext(ctx, chatID, content, nil, inboundCtx, sender) // Return nil to indicate we've handled the message asynchronously // The response will be sent through the message bus diff --git a/pkg/channels/dingtalk/dingtalk_test.go b/pkg/channels/dingtalk/dingtalk_test.go index 437616456..6dfc44730 100644 --- a/pkg/channels/dingtalk/dingtalk_test.go +++ b/pkg/channels/dingtalk/dingtalk_test.go @@ -11,7 +11,11 @@ import ( "github.com/sipeed/picoclaw/pkg/config" ) -func newTestDingTalkChannel(t *testing.T, cfg config.DingTalkConfig) (*DingTalkChannel, *bus.MessageBus) { +func newTestDingTalkChannel( + t *testing.T, + cfg config.DingTalkSettings, + bc *config.Channel, +) (*DingTalkChannel, *bus.MessageBus) { t.Helper() if cfg.ClientID == "" { @@ -22,7 +26,10 @@ func newTestDingTalkChannel(t *testing.T, cfg config.DingTalkConfig) (*DingTalkC } msgBus := bus.NewMessageBus() - ch, err := NewDingTalkChannel(cfg, msgBus) + if bc == nil { + bc = &config.Channel{Type: config.ChannelDingTalk, Enabled: true} + } + ch, err := NewDingTalkChannel(bc, &cfg, msgBus) if err != nil { t.Fatalf("new channel: %v", err) } @@ -41,9 +48,12 @@ func mustReceiveInbound(t *testing.T, msgBus *bus.MessageBus) bus.InboundMessage } func TestOnChatBotMessageReceived_GroupMentionOnlyUsesIsInAtListAndStripsMention(t *testing.T) { - ch, msgBus := newTestDingTalkChannel(t, config.DingTalkConfig{ + bc := &config.Channel{ + Type: config.ChannelDingTalk, + Enabled: true, GroupTrigger: config.GroupTriggerConfig{MentionOnly: true}, - }) + } + ch, msgBus := newTestDingTalkChannel(t, config.DingTalkSettings{}, bc) _, err := ch.onChatBotMessageReceived(context.Background(), &chatbot.BotCallbackDataModel{ Text: chatbot.BotCallbackDataTextModel{Content: " @bot /help "}, @@ -65,8 +75,8 @@ func TestOnChatBotMessageReceived_GroupMentionOnlyUsesIsInAtListAndStripsMention if inbound.ChatID != "group-abc" { t.Fatalf("chat_id=%q", inbound.ChatID) } - if inbound.Peer.Kind != "group" || inbound.Peer.ID != "group-abc" { - t.Fatalf("peer=%+v", inbound.Peer) + if inbound.Context.ChatType != "group" { + t.Fatalf("chat_type=%q", inbound.Context.ChatType) } if inbound.Content != "/help" { t.Fatalf("content=%q", inbound.Content) @@ -74,7 +84,7 @@ func TestOnChatBotMessageReceived_GroupMentionOnlyUsesIsInAtListAndStripsMention } func TestOnChatBotMessageReceived_DirectFallbackSenderIDUsesConversationID(t *testing.T) { - ch, msgBus := newTestDingTalkChannel(t, config.DingTalkConfig{}) + ch, msgBus := newTestDingTalkChannel(t, config.DingTalkSettings{}, nil) _, err := ch.onChatBotMessageReceived(context.Background(), &chatbot.BotCallbackDataModel{ Text: chatbot.BotCallbackDataTextModel{Content: "ping"}, @@ -93,12 +103,15 @@ func TestOnChatBotMessageReceived_DirectFallbackSenderIDUsesConversationID(t *te if inbound.ChatID != "conv-direct-42" { t.Fatalf("chat_id=%q", inbound.ChatID) } - if inbound.Peer.Kind != "direct" || inbound.Peer.ID != "openid-user-42" { - t.Fatalf("peer=%+v", inbound.Peer) + if inbound.Context.ChatType != "direct" { + t.Fatalf("chat_type=%q", inbound.Context.ChatType) } - if inbound.SenderID != "dingtalk:openid-user-42" { + if inbound.SenderID != "openid-user-42" { t.Fatalf("sender_id=%q", inbound.SenderID) } + if inbound.Sender.CanonicalID != "dingtalk:openid-user-42" { + t.Fatalf("sender canonical_id=%q", inbound.Sender.CanonicalID) + } if _, ok := ch.sessionWebhooks.Load("conv-direct-42"); !ok { t.Fatal("expected session webhook keyed by conversation_id") diff --git a/pkg/channels/dingtalk/init.go b/pkg/channels/dingtalk/init.go index 5f49bce8c..ab92c75b4 100644 --- a/pkg/channels/dingtalk/init.go +++ b/pkg/channels/dingtalk/init.go @@ -7,7 +7,26 @@ import ( ) func init() { - channels.RegisterFactory("dingtalk", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewDingTalkChannel(cfg.Channels.DingTalk, b) - }) + channels.RegisterFactory( + config.ChannelDingTalk, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.DingTalkSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewDingTalkChannel(bc, c, b) + if err != nil { + return nil, err + } + if channelName != config.ChannelDingTalk { + ch.SetName(channelName) + } + return ch, nil + }, + ) } diff --git a/pkg/channels/discord/discord.go b/pkg/channels/discord/discord.go index 01b1b4053..28f7277d3 100644 --- a/pkg/channels/discord/discord.go +++ b/pkg/channels/discord/discord.go @@ -38,8 +38,9 @@ var ( type DiscordChannel struct { *channels.BaseChannel + bc *config.Channel session *discordgo.Session - config config.DiscordConfig + config *config.DiscordSettings ctx context.Context cancel context.CancelFunc typingMu sync.Mutex @@ -56,7 +57,11 @@ type DiscordChannel struct { ttsPlayID uint64 } -func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) { +func NewDiscordChannel( + bc *config.Channel, + cfg *config.DiscordSettings, + bus *bus.MessageBus, +) (*DiscordChannel, error) { discordgo.Logger = logger.NewLogger("discord"). WithLevels(map[int]logger.LogLevel{ discordgo.LogError: logger.ERROR, @@ -73,14 +78,15 @@ func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordC if err := applyDiscordProxy(session, cfg.Proxy); err != nil { return nil, err } - base := channels.NewBaseChannel("discord", cfg, bus, cfg.AllowFrom, + base := channels.NewBaseChannel("discord", cfg, bus, bc.AllowFrom, channels.WithMaxMessageLength(2000), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &DiscordChannel{ BaseChannel: base, + bc: bc, session: session, config: cfg, ctx: context.Background(), @@ -297,11 +303,11 @@ func (c *DiscordChannel) EditMessage(ctx context.Context, chatID string, message // It sends a placeholder message that will later be edited to the actual // response via EditMessage (channels.MessageEditor). func (c *DiscordChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) { - if !c.config.Placeholder.Enabled { + if !c.bc.Placeholder.Enabled { return "", nil } - text := c.config.Placeholder.GetRandomText() + text := c.bc.Placeholder.GetRandomText() msg, err := c.session.ChannelMessageSend(chatID, text) if err != nil { @@ -402,8 +408,8 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag // In guild (group) channels, apply unified group trigger filtering // DMs (GuildID is empty) always get a response + isMentioned := false if m.GuildID != "" { - isMentioned := false for _, mention := range m.Mentions { if mention.ID == c.botUserID { isMentioned = true @@ -500,14 +506,10 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag }) peerKind := "channel" - peerID := m.ChannelID if m.GuildID == "" { peerKind = "direct" - peerID = senderID } - peer := bus.Peer{Kind: peerKind, ID: peerID} - metadata := map[string]string{ "user_id": senderID, "username": m.Author.Username, @@ -516,8 +518,24 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag "channel_id": m.ChannelID, "is_dm": fmt.Sprintf("%t", m.GuildID == ""), } + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + ChatID: m.ChannelID, + ChatType: peerKind, + SenderID: senderID, + MessageID: m.ID, + Mentioned: isMentioned, + Raw: metadata, + } + if m.GuildID != "" { + inboundCtx.SpaceID = m.GuildID + inboundCtx.SpaceType = "guild" + } + if m.MessageReference != nil { + inboundCtx.ReplyToMessageID = m.MessageReference.MessageID + } - c.HandleMessage(c.ctx, peer, m.ID, senderID, m.ChannelID, content, mediaPaths, metadata, sender) + c.HandleInboundContext(c.ctx, m.ChannelID, content, mediaPaths, inboundCtx, sender) } // startTyping starts a continuous typing indicator loop for the given chatID. diff --git a/pkg/channels/discord/init.go b/pkg/channels/discord/init.go index 8381dc9e9..c8dbe1081 100644 --- a/pkg/channels/discord/init.go +++ b/pkg/channels/discord/init.go @@ -8,11 +8,23 @@ import ( ) func init() { - channels.RegisterFactory("discord", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - ch, err := NewDiscordChannel(cfg.Channels.Discord, b) - if err == nil { - ch.tts = tts.DetectTTS(cfg) - } - return ch, err - }) + channels.RegisterFactory( + config.ChannelDiscord, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.DiscordSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewDiscordChannel(bc, c, b) + if err == nil { + ch.tts = tts.DetectTTS(cfg) + } + return ch, err + }, + ) } diff --git a/pkg/channels/feishu/feishu_32.go b/pkg/channels/feishu/feishu_32.go index f3fe2a6cb..04c7acc15 100644 --- a/pkg/channels/feishu/feishu_32.go +++ b/pkg/channels/feishu/feishu_32.go @@ -19,7 +19,7 @@ type FeishuChannel struct { var errUnsupported = errors.New("feishu channel is not supported on 32-bit architectures") // NewFeishuChannel returns an error on 32-bit architectures where the Feishu SDK is not supported -func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) { +func NewFeishuChannel(bc *config.Channel, cfg *config.FeishuSettings, bus *bus.MessageBus) (*FeishuChannel, error) { return nil, errors.New( "feishu channel is not supported on 32-bit architectures (armv7l, 386, etc.). Please use a 64-bit system or disable feishu in your config", ) diff --git a/pkg/channels/feishu/feishu_64.go b/pkg/channels/feishu/feishu_64.go index b0b231d09..02ee47d69 100644 --- a/pkg/channels/feishu/feishu_64.go +++ b/pkg/channels/feishu/feishu_64.go @@ -14,6 +14,7 @@ import ( "strings" "sync" "sync/atomic" + "time" lark "github.com/larksuite/oapi-sdk-go/v3" larkcore "github.com/larksuite/oapi-sdk-go/v3/core" @@ -37,21 +38,28 @@ const errCodeTenantTokenInvalid = 99991663 type FeishuChannel struct { *channels.BaseChannel - config config.FeishuConfig + bc *config.Channel + config *config.FeishuSettings client *lark.Client wsClient *larkws.Client tokenCache *tokenCache // custom cache that supports invalidation - botOpenID atomic.Value // stores string; populated lazily for @mention detection + botOpenID atomic.Value // stores string; populated lazily for @mention detection + messageCache sync.Map // caches fetched messages (messageID -> *larkim.Message) mu sync.Mutex cancel context.CancelFunc } -func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) { - base := channels.NewBaseChannel("feishu", cfg, bus, cfg.AllowFrom, - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), +type cachedMessage struct { + msg *larkim.Message + expiry time.Time +} + +func NewFeishuChannel(bc *config.Channel, cfg *config.FeishuSettings, bus *bus.MessageBus) (*FeishuChannel, error) { + base := channels.NewBaseChannel("feishu", cfg, bus, bc.AllowFrom, + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) tc := newTokenCache() @@ -61,6 +69,7 @@ func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChan } ch := &FeishuChannel{ BaseChannel: base, + bc: bc, config: cfg, tokenCache: tc, client: lark.NewClient(cfg.AppID, cfg.AppSecret.String(), opts...), @@ -204,14 +213,14 @@ func (c *FeishuChannel) EditMessage(ctx context.Context, chatID, messageID, cont // SendPlaceholder implements channels.PlaceholderCapable. // Sends an interactive card with placeholder text and returns its message ID. func (c *FeishuChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) { - if !c.config.Placeholder.Enabled { + if !c.bc.Placeholder.Enabled { logger.DebugCF("feishu", "Placeholder disabled, skipping", map[string]any{ "chat_id": chatID, }) return "", nil } - text := c.config.Placeholder.GetRandomText() + text := c.bc.Placeholder.GetRandomText() cardContent, err := buildMarkdownCard(text) if err != nil { @@ -439,30 +448,20 @@ func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim. if content == "" { content = "[empty message]" } - - metadata := map[string]string{} - if messageID != "" { - metadata["message_id"] = messageID - } - if messageType != "" { - metadata["message_type"] = messageType - } chatType := stringValue(message.ChatType) - if chatType != "" { - metadata["chat_type"] = chatType - } - if sender != nil && sender.TenantKey != nil { - metadata["tenant_key"] = *sender.TenantKey - } + metadata := buildInboundMetadata(message, sender) - var peer bus.Peer + var ( + inboundChatType string + isMentioned bool + ) if chatType == "p2p" { - peer = bus.Peer{Kind: "direct", ID: senderID} + inboundChatType = "direct" } else { - peer = bus.Peer{Kind: "group", ID: chatID} + inboundChatType = "group" // Check if bot was mentioned - isMentioned := c.isBotMentioned(message) + isMentioned = c.isBotMentioned(message) // Strip mention placeholders from content before group trigger check if len(message.Mentions) > 0 { @@ -477,14 +476,41 @@ func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim. content = cleaned } + if replyTargetID(message) != "" || stringValue(message.ThreadId) != "" { + content, mediaRefs = c.prependReplyContext(ctx, message, chatID, content, mediaRefs) + } + if content == "" { + content = "[empty message]" + } + logger.InfoCF("feishu", "Feishu message received", map[string]any{ "sender_id": senderID, "chat_id": chatID, "message_id": messageID, "preview": utils.Truncate(content, 80), }) + logger.InfoCF("feishu", "Feishu reply linkage", map[string]any{ + "message_id": messageID, + "parent_id": stringValue(message.ParentId), + "root_id": stringValue(message.RootId), + "thread_id": stringValue(message.ThreadId), + }) - c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, mediaRefs, metadata, senderInfo) + inboundCtx := bus.InboundContext{ + Channel: "feishu", + ChatID: chatID, + ChatType: inboundChatType, + SenderID: senderID, + MessageID: messageID, + Mentioned: isMentioned, + Raw: metadata, + } + if sender != nil && sender.TenantKey != nil && *sender.TenantKey != "" { + inboundCtx.SpaceType = "tenant" + inboundCtx.SpaceID = *sender.TenantKey + } + + c.HandleInboundContext(ctx, chatID, content, mediaRefs, inboundCtx, senderInfo) return nil } diff --git a/pkg/channels/feishu/feishu_reply.go b/pkg/channels/feishu/feishu_reply.go new file mode 100644 index 000000000..22dfe3e87 --- /dev/null +++ b/pkg/channels/feishu/feishu_reply.go @@ -0,0 +1,298 @@ +//go:build amd64 || arm64 || riscv64 || mips64 || ppc64 + +package feishu + +import ( + "context" + "fmt" + "strings" + "time" + + larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1" + + "github.com/sipeed/picoclaw/pkg/logger" + "github.com/sipeed/picoclaw/pkg/utils" +) + +const messageCacheTTL = 30 * time.Second + +const ( + maxReplyContextLen = 600 +) + +func (c *FeishuChannel) prependReplyContext( + ctx context.Context, + message *larkim.EventMessage, + chatID string, + content string, + mediaRefs []string, +) (string, []string) { + if message == nil { + return content, mediaRefs + } + + lookupCtx, cancel := context.WithTimeout(ctx, 5*time.Second) + defer cancel() + + targetMessageID := c.resolveReplyTargetMessageID(lookupCtx, message) + if targetMessageID == "" { + logger.DebugCF("feishu", "No reply target resolved; skip reply context", map[string]any{ + "message_id": stringValue(message.MessageId), + "parent_id": stringValue(message.ParentId), + "root_id": stringValue(message.RootId), + "thread_id": stringValue(message.ThreadId), + }) + return content, mediaRefs + } + + repliedMessage, err := c.fetchMessageByID(lookupCtx, targetMessageID) + if err != nil { + logger.DebugCF("feishu", "Failed to fetch replied message context", map[string]any{ + "target_message_id": targetMessageID, + "error": err.Error(), + }) + return content, mediaRefs + } + + messageType := stringValue(repliedMessage.MsgType) + rawContent := "" + if repliedMessage.Body != nil { + rawContent = stringValue(repliedMessage.Body.Content) + } + + var repliedMediaRefs []string + if store := c.GetMediaStore(); store != nil { + repliedMediaRefs = c.downloadInboundMedia(lookupCtx, chatID, targetMessageID, messageType, rawContent, store) + if messageType == larkim.MsgTypeInteractive { + _, externalURLs := extractCardImageKeys(rawContent) + if len(externalURLs) > 0 { + repliedMediaRefs = append(repliedMediaRefs, externalURLs...) + } + } + } + + repliedContent := normalizeRepliedContent(messageType, rawContent, repliedMediaRefs) + if len(repliedMediaRefs) > 0 { + mediaRefs = append(repliedMediaRefs, mediaRefs...) + } + + return formatReplyContext(targetMessageID, repliedContent, content), mediaRefs +} + +func (c *FeishuChannel) resolveReplyTargetMessageID(ctx context.Context, message *larkim.EventMessage) string { + if targetID := replyTargetID(message); targetID != "" { + logger.DebugCF("feishu", "Resolved reply target from event payload", map[string]any{ + "message_id": stringValue(message.MessageId), + "parent_id": stringValue(message.ParentId), + "root_id": stringValue(message.RootId), + "target_id": targetID, + }) + return targetID + } + + currentMessageID := stringValue(message.MessageId) + if currentMessageID == "" { + return "" + } + + if stringValue(message.ThreadId) == "" { + logger.DebugCF("feishu", "No reply target found; message is not in a thread", map[string]any{ + "message_id": stringValue(message.MessageId), + }) + return "" + } + + msg, err := c.fetchMessageByID(ctx, currentMessageID) + if err != nil { + logger.DebugCF("feishu", "Failed to query current message detail for reply info", map[string]any{ + "message_id": currentMessageID, + "error": err.Error(), + }) + return "" + } + + targetID := replyTargetIDFromMessage(msg) + if targetID != "" { + logger.DebugCF("feishu", "Resolved reply target from message detail", map[string]any{ + "message_id": currentMessageID, + "parent_id": stringValue(msg.ParentId), + "root_id": stringValue(msg.RootId), + "target_id": targetID, + }) + } + return targetID +} + +func (c *FeishuChannel) fetchMessageByID(ctx context.Context, messageID string) (*larkim.Message, error) { + if cached, ok := c.messageCache.Load(messageID); ok { + cm := cached.(*cachedMessage) + if time.Now().Before(cm.expiry) { + return cm.msg, nil + } + c.messageCache.Delete(messageID) + } + + req := larkim.NewGetMessageReqBuilder(). + MessageId(messageID). + Build() + + resp, err := c.client.Im.V1.Message.Get(ctx, req) + if err != nil { + return nil, fmt.Errorf("feishu get message: %w", err) + } + if !resp.Success() { + c.invalidateTokenOnAuthError(resp.Code) + return nil, fmt.Errorf("feishu get message api error (code=%d msg=%s)", resp.Code, resp.Msg) + } + if resp.Data == nil || len(resp.Data.Items) == 0 || resp.Data.Items[0] == nil { + return nil, fmt.Errorf("feishu get message: empty response") + } + // Items[0] contains the target message - the Feishu API returns a list + // but we request a single message by ID, so the list always has at most one item. + msg := resp.Data.Items[0] + c.messageCache.Store(messageID, &cachedMessage{msg: msg, expiry: time.Now().Add(messageCacheTTL)}) + return msg, nil +} + +func replyTargetID(message *larkim.EventMessage) string { + if message == nil { + return "" + } + if parentID := stringValue(message.ParentId); parentID != "" { + return parentID + } + return stringValue(message.RootId) +} + +func replyTargetIDFromMessage(message *larkim.Message) string { + if message == nil { + return "" + } + if parentID := stringValue(message.ParentId); parentID != "" { + return parentID + } + return stringValue(message.RootId) +} + +func buildInboundMetadata(message *larkim.EventMessage, sender *larkim.EventSender) map[string]string { + metadata := map[string]string{} + if message == nil { + return metadata + } + + messageID := stringValue(message.MessageId) + if messageID != "" { + metadata["message_id"] = messageID + } + + messageType := stringValue(message.MessageType) + if messageType != "" { + metadata["message_type"] = messageType + } + + chatType := stringValue(message.ChatType) + if chatType != "" { + metadata["chat_type"] = chatType + } + + parentID := stringValue(message.ParentId) + if parentID != "" { + metadata["parent_id"] = parentID + } + + rootID := stringValue(message.RootId) + if rootID != "" { + metadata["root_id"] = rootID + } + + if replyTo := replyTargetID(message); replyTo != "" { + metadata["reply_to_message_id"] = replyTo + } + + threadID := stringValue(message.ThreadId) + if threadID != "" { + metadata["thread_id"] = threadID + } + + if sender != nil && sender.TenantKey != nil && *sender.TenantKey != "" { + metadata["tenant_key"] = *sender.TenantKey + } + + return metadata +} + +func normalizeRepliedContent(messageType, rawContent string, mediaRefs []string) string { + content := extractContent(messageType, rawContent) + + if containsFeishuUpgradePlaceholder(rawContent) || containsFeishuUpgradePlaceholder(content) { + content = "" + } + + content = appendMediaTags(content, messageType, mediaRefs) + if strings.TrimSpace(content) != "" { + return content + } + + switch messageType { + case larkim.MsgTypeImage: + return "[replied image]" + case larkim.MsgTypeFile: + return "[replied file]" + case larkim.MsgTypeAudio: + return "[replied audio]" + case larkim.MsgTypeMedia: + return "[replied video]" + case larkim.MsgTypeInteractive: + return "[replied interactive card]" + default: + return "[replied message content unavailable]" + } +} + +func containsFeishuUpgradePlaceholder(s string) bool { + upgradePrompt := "\u8bf7\u5347\u7ea7\u81f3\u6700\u65b0\u7248\u672c\u5ba2\u6237\u7aef" + upgradePromptEscaped := "\\u8bf7\\u5347\\u7ea7\\u81f3\\u6700\\u65b0\\u7248\\u672c\\u5ba2\\u6237\\u7aef" + return strings.Contains(s, upgradePrompt) || strings.Contains(s, upgradePromptEscaped) +} + +func formatReplyContext(parentID, repliedContent, content string) string { + parentID = strings.TrimSpace(parentID) + repliedContent = strings.TrimSpace(repliedContent) + content = strings.TrimSpace(content) + + if parentID == "" || repliedContent == "" { + return content + } + + repliedContent = utils.Truncate(repliedContent, maxReplyContextLen) + repliedContent = sanitizeReplyContextContent(repliedContent) + content = sanitizeReplyContextContent(content) + header := fmt.Sprintf("[replied_message id=%q]", parentID) + footer := "[/replied_message]" + if content == "" { + return header + "\n" + repliedContent + "\n" + footer + } + if hasLeadingCommandPrefix(content) { + return content + "\n\n" + header + "\n" + repliedContent + "\n" + footer + } + return header + "\n" + repliedContent + "\n" + footer + "\n\n[current_message]\n" + content + "\n[/current_message]" +} + +func hasLeadingCommandPrefix(s string) bool { + tokens := strings.Fields(strings.TrimSpace(s)) + if len(tokens) == 0 { + return false + } + first := tokens[0] + return strings.HasPrefix(first, "/") || strings.HasPrefix(first, "!") +} + +func sanitizeReplyContextContent(s string) string { + tagEscaper := strings.NewReplacer( + "[replied_message", `\[replied_message`, + "[/replied_message]", `\[/replied_message]`, + "[current_message]", `\[current_message]`, + "[/current_message]", `\[/current_message]`, + ) + return tagEscaper.Replace(s) +} diff --git a/pkg/channels/feishu/feishu_reply_test.go b/pkg/channels/feishu/feishu_reply_test.go new file mode 100644 index 000000000..0efe7bc01 --- /dev/null +++ b/pkg/channels/feishu/feishu_reply_test.go @@ -0,0 +1,229 @@ +//go:build amd64 || arm64 || riscv64 || mips64 || ppc64 + +package feishu + +import ( + "strings" + "testing" + + larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1" +) + +func TestBuildInboundMetadata(t *testing.T) { + strPtr := func(s string) *string { return &s } + + t.Run("includes basic and reply fields", func(t *testing.T) { + message := &larkim.EventMessage{ + MessageId: strPtr("om_msg_1"), + MessageType: strPtr("text"), + ChatType: strPtr("group"), + ParentId: strPtr("om_parent_1"), + RootId: strPtr("om_root_1"), + ThreadId: strPtr("omt_thread_1"), + } + sender := &larkim.EventSender{TenantKey: strPtr("tenant_x")} + + got := buildInboundMetadata(message, sender) + + if got["message_id"] != "om_msg_1" { + t.Fatalf("message_id = %q, want %q", got["message_id"], "om_msg_1") + } + if got["message_type"] != "text" { + t.Fatalf("message_type = %q, want %q", got["message_type"], "text") + } + if got["chat_type"] != "group" { + t.Fatalf("chat_type = %q, want %q", got["chat_type"], "group") + } + if got["parent_id"] != "om_parent_1" { + t.Fatalf("parent_id = %q, want %q", got["parent_id"], "om_parent_1") + } + if got["reply_to_message_id"] != "om_parent_1" { + t.Fatalf("reply_to_message_id = %q, want %q", got["reply_to_message_id"], "om_parent_1") + } + if got["root_id"] != "om_root_1" { + t.Fatalf("root_id = %q, want %q", got["root_id"], "om_root_1") + } + if got["thread_id"] != "omt_thread_1" { + t.Fatalf("thread_id = %q, want %q", got["thread_id"], "omt_thread_1") + } + if got["tenant_key"] != "tenant_x" { + t.Fatalf("tenant_key = %q, want %q", got["tenant_key"], "tenant_x") + } + }) + + t.Run("falls back reply_to_message_id to root_id", func(t *testing.T) { + message := &larkim.EventMessage{ + MessageId: strPtr("om_msg_3"), + RootId: strPtr("om_root_3"), + } + + got := buildInboundMetadata(message, nil) + + if got["root_id"] != "om_root_3" { + t.Fatalf("root_id = %q, want %q", got["root_id"], "om_root_3") + } + if got["reply_to_message_id"] != "om_root_3" { + t.Fatalf("reply_to_message_id = %q, want %q", got["reply_to_message_id"], "om_root_3") + } + }) + + t.Run("omits empty values", func(t *testing.T) { + message := &larkim.EventMessage{ + MessageId: strPtr("om_msg_2"), + } + + got := buildInboundMetadata(message, nil) + + if got["message_id"] != "om_msg_2" { + t.Fatalf("message_id = %q, want %q", got["message_id"], "om_msg_2") + } + if _, ok := got["parent_id"]; ok { + t.Fatalf("parent_id should be absent, got %q", got["parent_id"]) + } + if _, ok := got["reply_to_message_id"]; ok { + t.Fatalf("reply_to_message_id should be absent, got %q", got["reply_to_message_id"]) + } + if _, ok := got["tenant_key"]; ok { + t.Fatalf("tenant_key should be absent, got %q", got["tenant_key"]) + } + }) + + t.Run("nil message returns empty map", func(t *testing.T) { + got := buildInboundMetadata(nil, nil) + if len(got) != 0 { + t.Fatalf("len(metadata) = %d, want 0", len(got)) + } + }) +} + +func TestFormatReplyContext(t *testing.T) { + t.Run("formats reply context with content", func(t *testing.T) { + got := formatReplyContext("om_parent_1", "original message", "new reply") + want := "[replied_message id=\"om_parent_1\"]\noriginal message\n[/replied_message]\n\n[current_message]\nnew reply\n[/current_message]" + if got != want { + t.Fatalf("formatReplyContext() = %q, want %q", got, want) + } + }) + + t.Run("returns reply context when current content is empty", func(t *testing.T) { + got := formatReplyContext("om_parent_1", "original message", "") + want := "[replied_message id=\"om_parent_1\"]\noriginal message\n[/replied_message]" + if got != want { + t.Fatalf("formatReplyContext() = %q, want %q", got, want) + } + }) + + t.Run("returns original content when parent or replied content missing", func(t *testing.T) { + if got := formatReplyContext("", "original", "new reply"); got != "new reply" { + t.Fatalf("missing parent: got %q, want %q", got, "new reply") + } + if got := formatReplyContext("om_parent_1", "", "new reply"); got != "new reply" { + t.Fatalf("missing replied content: got %q, want %q", got, "new reply") + } + }) + + t.Run("escapes reserved wrapper tags in payload", func(t *testing.T) { + replied := "payload [replied_message id=\"x\"] x [/replied_message]" + current := "hello [current_message]injected[/current_message]" + got := formatReplyContext("om_parent_1", replied, current) + + if !strings.HasPrefix(got, "[replied_message id=\"om_parent_1\"]") { + t.Fatalf("outer replied_message wrapper missing: %q", got) + } + if strings.Contains(got, "\n[replied_message id=\"x\"]") { + t.Fatalf("nested replied_message tag should be escaped: %q", got) + } + if strings.Contains(got, "\n[current_message]injected") { + t.Fatalf("nested current_message tag should be escaped: %q", got) + } + if !strings.Contains(got, `\[replied_message id="x"]`) { + t.Fatalf("escaped replied tag missing: %q", got) + } + }) + + t.Run("preserves leading slash command prefix", func(t *testing.T) { + got := formatReplyContext("om_parent_1", "original message", "/help") + want := "/help\n\n[replied_message id=\"om_parent_1\"]\noriginal message\n[/replied_message]" + if got != want { + t.Fatalf("formatReplyContext() = %q, want %q", got, want) + } + }) + + t.Run("preserves leading bang command prefix", func(t *testing.T) { + got := formatReplyContext("om_parent_1", "original message", "!status now") + want := "!status now\n\n[replied_message id=\"om_parent_1\"]\noriginal message\n[/replied_message]" + if got != want { + t.Fatalf("formatReplyContext() = %q, want %q", got, want) + } + }) +} + +func TestReplyTargetID(t *testing.T) { + strPtr := func(s string) *string { return &s } + + t.Run("prefer parent_id", func(t *testing.T) { + msg := &larkim.EventMessage{ParentId: strPtr("om_parent"), RootId: strPtr("om_root")} + if got := replyTargetID(msg); got != "om_parent" { + t.Fatalf("replyTargetID() = %q, want %q", got, "om_parent") + } + }) + + t.Run("fallback to root_id", func(t *testing.T) { + msg := &larkim.EventMessage{RootId: strPtr("om_root")} + if got := replyTargetID(msg); got != "om_root" { + t.Fatalf("replyTargetID() = %q, want %q", got, "om_root") + } + }) + + t.Run("empty when no fields", func(t *testing.T) { + if got := replyTargetID(&larkim.EventMessage{}); got != "" { + t.Fatalf("replyTargetID() = %q, want empty", got) + } + }) +} + +func TestNormalizeRepliedContent(t *testing.T) { + t.Run("filters feishu upgrade placeholder for interactive", func(t *testing.T) { + raw := `{"text":"\u8bf7\u5347\u7ea7\u81f3\u6700\u65b0\u7248\u672c\u5ba2\u6237\u7aef\uff0c\u4ee5\u67e5\u770b\u5185\u5bb9"}` + got := normalizeRepliedContent("interactive", raw, nil) + if got != "[replied interactive card]" { + t.Fatalf("normalizeRepliedContent() = %q, want %q", got, "[replied interactive card]") + } + }) + + t.Run("keeps filename and file tag for replied file", func(t *testing.T) { + got := normalizeRepliedContent("file", `{"file_key":"file_xxx","file_name":"doc.pdf"}`, []string{"media://r1"}) + if got != "doc.pdf [file]" { + t.Fatalf("normalizeRepliedContent() = %q, want %q", got, "doc.pdf [file]") + } + }) + + t.Run("falls back when file content missing", func(t *testing.T) { + got := normalizeRepliedContent("file", `{"file_key":"file_xxx"}`, nil) + if got != "[replied file]" { + t.Fatalf("normalizeRepliedContent() = %q, want %q", got, "[replied file]") + } + }) +} + +func TestHasLeadingCommandPrefix(t *testing.T) { + tests := []struct { + name string + input string + want bool + }{ + {name: "slash command", input: "/help", want: true}, + {name: "bang command", input: "!status", want: true}, + {name: "leading spaces slash", input: " /ping arg", want: true}, + {name: "normal text", input: "hello /help", want: false}, + {name: "empty", input: "", want: false}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := hasLeadingCommandPrefix(tt.input); got != tt.want { + t.Fatalf("hasLeadingCommandPrefix(%q) = %v, want %v", tt.input, got, tt.want) + } + }) + } +} diff --git a/pkg/channels/feishu/init.go b/pkg/channels/feishu/init.go index 7e5a62dae..c4982bef1 100644 --- a/pkg/channels/feishu/init.go +++ b/pkg/channels/feishu/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("feishu", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewFeishuChannel(cfg.Channels.Feishu, b) - }) + channels.RegisterFactory( + config.ChannelFeishu, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.FeishuSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewFeishuChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/irc/handler.go b/pkg/channels/irc/handler.go index b92359da4..73df9c43c 100644 --- a/pkg/channels/irc/handler.go +++ b/pkg/channels/irc/handler.go @@ -51,14 +51,11 @@ func (c *IRCChannel) onPrivmsg(conn *ircevent.Connection, e ircmsg.Message) { isDM := !strings.HasPrefix(target, "#") && !strings.HasPrefix(target, "&") var chatID string - var peer bus.Peer if isDM { chatID = nick - peer = bus.Peer{Kind: "direct", ID: nick} } else { chatID = target - peer = bus.Peer{Kind: "group", ID: target} } sender := bus.SenderInfo{ @@ -73,9 +70,11 @@ func (c *IRCChannel) onPrivmsg(conn *ircevent.Connection, e ircmsg.Message) { return } + isMentioned := false + // For channel messages, check group trigger (mention detection) if !isDM { - isMentioned := isBotMentioned(content, currentNick) + isMentioned = isBotMentioned(content, currentNick) if isMentioned { content = stripBotMention(content, currentNick) } @@ -100,7 +99,21 @@ func (c *IRCChannel) onPrivmsg(conn *ircevent.Connection, e ircmsg.Message) { metadata["channel"] = target } - c.HandleMessage(c.ctx, peer, messageID, nick, chatID, content, nil, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: "irc", + ChatID: chatID, + SenderID: nick, + MessageID: messageID, + Mentioned: isMentioned, + Raw: metadata, + } + if isDM { + inboundCtx.ChatType = "direct" + } else { + inboundCtx.ChatType = "group" + } + + c.HandleInboundContext(c.ctx, chatID, content, nil, inboundCtx, sender) } // nickMentionedAt returns the byte index where botNick is mentioned in content diff --git a/pkg/channels/irc/init.go b/pkg/channels/irc/init.go index 221d41b62..3f206cbc7 100644 --- a/pkg/channels/irc/init.go +++ b/pkg/channels/irc/init.go @@ -7,10 +7,29 @@ import ( ) func init() { - channels.RegisterFactory("irc", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - if !cfg.Channels.IRC.Enabled { - return nil, nil - } - return NewIRCChannel(cfg.Channels.IRC, b) - }) + channels.RegisterFactory( + config.ChannelIRC, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + if bc == nil || !bc.Enabled { + return nil, nil + } + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.IRCSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewIRCChannel(bc, c, b) + if err != nil { + return nil, err + } + if channelName != config.ChannelIRC { + ch.SetName(channelName) + } + return ch, nil + }, + ) } diff --git a/pkg/channels/irc/irc.go b/pkg/channels/irc/irc.go index e8a70923f..fa60e9b6d 100644 --- a/pkg/channels/irc/irc.go +++ b/pkg/channels/irc/irc.go @@ -18,14 +18,15 @@ import ( // IRCChannel implements the Channel interface for IRC servers. type IRCChannel struct { *channels.BaseChannel - config config.IRCConfig + bc *config.Channel + config *config.IRCSettings conn *ircevent.Connection ctx context.Context cancel context.CancelFunc } // NewIRCChannel creates a new IRC channel. -func NewIRCChannel(cfg config.IRCConfig, messageBus *bus.MessageBus) (*IRCChannel, error) { +func NewIRCChannel(bc *config.Channel, cfg *config.IRCSettings, messageBus *bus.MessageBus) (*IRCChannel, error) { if cfg.Server == "" { return nil, fmt.Errorf("irc server is required") } @@ -33,14 +34,15 @@ func NewIRCChannel(cfg config.IRCConfig, messageBus *bus.MessageBus) (*IRCChanne return nil, fmt.Errorf("irc nick is required") } - base := channels.NewBaseChannel("irc", cfg, messageBus, cfg.AllowFrom, + base := channels.NewBaseChannel("irc", cfg, messageBus, bc.AllowFrom, channels.WithMaxMessageLength(400), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &IRCChannel{ BaseChannel: base, + bc: bc, config: cfg, }, nil } @@ -166,7 +168,7 @@ func (c *IRCChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]strin func (c *IRCChannel) StartTyping(ctx context.Context, chatID string) (func(), error) { noop := func() {} - if !c.config.Typing.Enabled || !c.IsRunning() || c.conn == nil { + if !c.bc.Typing.Enabled || !c.IsRunning() || c.conn == nil { return noop, nil } diff --git a/pkg/channels/irc/irc_test.go b/pkg/channels/irc/irc_test.go index 168252a4d..e459e71fc 100644 --- a/pkg/channels/irc/irc_test.go +++ b/pkg/channels/irc/irc_test.go @@ -11,28 +11,31 @@ func TestNewIRCChannel(t *testing.T) { msgBus := bus.NewMessageBus() t.Run("missing server", func(t *testing.T) { - cfg := config.IRCConfig{Nick: "bot"} - _, err := NewIRCChannel(cfg, msgBus) + bc := &config.Channel{Type: config.ChannelIRC, Enabled: true} + cfg := &config.IRCSettings{Nick: "bot"} + _, err := NewIRCChannel(bc, cfg, msgBus) if err == nil { t.Error("expected error for missing server, got nil") } }) t.Run("missing nick", func(t *testing.T) { - cfg := config.IRCConfig{Server: "irc.example.com:6667"} - _, err := NewIRCChannel(cfg, msgBus) + bc := &config.Channel{Type: config.ChannelIRC, Enabled: true} + cfg := &config.IRCSettings{Server: "irc.example.com:6667"} + _, err := NewIRCChannel(bc, cfg, msgBus) if err == nil { t.Error("expected error for missing nick, got nil") } }) t.Run("valid config", func(t *testing.T) { - cfg := config.IRCConfig{ + bc := &config.Channel{Type: config.ChannelIRC, Enabled: true} + cfg := &config.IRCSettings{ Server: "irc.example.com:6667", Nick: "testbot", Channels: []string{"#test"}, } - ch, err := NewIRCChannel(cfg, msgBus) + ch, err := NewIRCChannel(bc, cfg, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } diff --git a/pkg/channels/line/init.go b/pkg/channels/line/init.go index 9265575cc..6d829cd40 100644 --- a/pkg/channels/line/init.go +++ b/pkg/channels/line/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("line", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewLINEChannel(cfg.Channels.LINE, b) - }) + channels.RegisterFactory( + config.ChannelLINE, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.LINESettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewLINEChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/line/line.go b/pkg/channels/line/line.go index 230983935..760506a31 100644 --- a/pkg/channels/line/line.go +++ b/pkg/channels/line/line.go @@ -48,7 +48,7 @@ type replyTokenEntry struct { // and REST API for sending messages. type LINEChannel struct { *channels.BaseChannel - config config.LINEConfig + config *config.LINESettings infoClient *http.Client // for bot info lookups (short timeout) apiClient *http.Client // for messaging API calls botUserID string // Bot's user ID @@ -61,15 +61,19 @@ type LINEChannel struct { } // NewLINEChannel creates a new LINE channel instance. -func NewLINEChannel(cfg config.LINEConfig, messageBus *bus.MessageBus) (*LINEChannel, error) { +func NewLINEChannel( + bc *config.Channel, + cfg *config.LINESettings, + messageBus *bus.MessageBus, +) (*LINEChannel, error) { if cfg.ChannelSecret.String() == "" || cfg.ChannelAccessToken.String() == "" { return nil, fmt.Errorf("line channel_secret and channel_access_token are required") } - base := channels.NewBaseChannel("line", cfg, messageBus, cfg.AllowFrom, + base := channels.NewBaseChannel("line", cfg, messageBus, bc.AllowFrom, channels.WithMaxMessageLength(5000), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &LINEChannel{ @@ -350,8 +354,9 @@ func (c *LINEChannel) processEvent(event lineEvent) { } // In group chats, apply unified group trigger filtering + isMentioned := false if isGroup { - isMentioned := c.isBotMentioned(msg) + isMentioned = c.isBotMentioned(msg) respond, cleaned := c.ShouldRespondInGroup(isMentioned, content) if !respond { logger.DebugCF("line", "Ignoring group message by group trigger", map[string]any{ @@ -367,13 +372,6 @@ func (c *LINEChannel) processEvent(event lineEvent) { "source_type": event.Source.Type, } - var peer bus.Peer - if isGroup { - peer = bus.Peer{Kind: "group", ID: chatID} - } else { - peer = bus.Peer{Kind: "direct", ID: senderID} - } - logger.DebugCF("line", "Received message", map[string]any{ "sender_id": senderID, "chat_id": chatID, @@ -392,7 +390,25 @@ func (c *LINEChannel) processEvent(event lineEvent) { return } - c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, mediaPaths, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + ChatID: chatID, + ChatType: map[bool]string{true: "group", false: "direct"}[isGroup], + SenderID: senderID, + MessageID: msg.ID, + Mentioned: isMentioned, + Raw: metadata, + } + if event.ReplyToken != "" { + inboundCtx.ReplyHandles = map[string]string{ + "reply_token": event.ReplyToken, + } + if msg.QuoteToken != "" { + inboundCtx.ReplyHandles["quote_token"] = msg.QuoteToken + } + } + + c.HandleInboundContext(c.ctx, chatID, content, mediaPaths, inboundCtx, sender) } // isBotMentioned checks if the bot is mentioned in the message. diff --git a/pkg/channels/line/line_test.go b/pkg/channels/line/line_test.go index 00770f1c7..c5f4e9be2 100644 --- a/pkg/channels/line/line_test.go +++ b/pkg/channels/line/line_test.go @@ -6,6 +6,8 @@ import ( "net/http/httptest" "strings" "testing" + + "github.com/sipeed/picoclaw/pkg/config" ) func TestWebhookRejectsOversizedBody(t *testing.T) { @@ -66,7 +68,9 @@ func TestWebhookRejectsNonPostMethod(t *testing.T) { } func TestWebhookRejectsInvalidSignature(t *testing.T) { - ch := &LINEChannel{} + ch := &LINEChannel{ + config: &config.LINESettings{}, + } body := `{"events":[]}` req := httptest.NewRequest(http.MethodPost, "/webhook", strings.NewReader(body)) diff --git a/pkg/channels/maixcam/init.go b/pkg/channels/maixcam/init.go index 5a269b22b..f2f7b910b 100644 --- a/pkg/channels/maixcam/init.go +++ b/pkg/channels/maixcam/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("maixcam", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewMaixCamChannel(cfg.Channels.MaixCam, b) - }) + channels.RegisterFactory( + config.ChannelMaixCam, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.MaixCamSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewMaixCamChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/maixcam/maixcam.go b/pkg/channels/maixcam/maixcam.go index bbbf2da56..b81206c59 100644 --- a/pkg/channels/maixcam/maixcam.go +++ b/pkg/channels/maixcam/maixcam.go @@ -17,7 +17,7 @@ import ( type MaixCamChannel struct { *channels.BaseChannel - config config.MaixCamConfig + config *config.MaixCamSettings listener net.Listener ctx context.Context cancel context.CancelFunc @@ -32,13 +32,17 @@ type MaixCamMessage struct { Data map[string]any `json:"data"` } -func NewMaixCamChannel(cfg config.MaixCamConfig, bus *bus.MessageBus) (*MaixCamChannel, error) { +func NewMaixCamChannel( + bc *config.Channel, + cfg *config.MaixCamSettings, + bus *bus.MessageBus, +) (*MaixCamChannel, error) { base := channels.NewBaseChannel( "maixcam", cfg, bus, - cfg.AllowFrom, - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + bc.AllowFrom, + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &MaixCamChannel{ @@ -196,17 +200,15 @@ func (c *MaixCamChannel) handlePersonDetection(msg MaixCamMessage) { return } - c.HandleMessage( - c.ctx, - bus.Peer{Kind: "channel", ID: "default"}, - "", - senderID, - chatID, - content, - []string{}, - metadata, - sender, - ) + inboundCtx := bus.InboundContext{ + Channel: "maixcam", + ChatID: chatID, + ChatType: "channel", + SenderID: senderID, + Raw: metadata, + } + + c.HandleInboundContext(c.ctx, chatID, content, nil, inboundCtx, sender) } func (c *MaixCamChannel) handleStatusUpdate(msg MaixCamMessage) { diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go index 6d9f5eda8..928676cbc 100644 --- a/pkg/channels/manager.go +++ b/pkg/channels/manager.go @@ -11,6 +11,7 @@ import ( "errors" "fmt" "math" + "net" "net/http" "sort" "sync" @@ -86,6 +87,7 @@ type Manager struct { dispatchTask *asyncTask mux *dynamicServeMux httpServer *http.Server + httpListeners []net.Listener mu sync.RWMutex placeholders sync.Map // "channel:chatID" → placeholderID (string) typingStops sync.Map // "channel:chatID" → func() @@ -98,6 +100,22 @@ type asyncTask struct { cancel context.CancelFunc } +func outboundMessageChannel(msg bus.OutboundMessage) string { + return msg.Context.Channel +} + +func outboundMessageChatID(msg bus.OutboundMessage) string { + return msg.ChatID +} + +func outboundMediaChannel(msg bus.OutboundMediaMessage) string { + return msg.Context.Channel +} + +func outboundMediaChatID(msg bus.OutboundMediaMessage) string { + return msg.ChatID +} + // RecordPlaceholder registers a placeholder message for later editing. // Implements PlaceholderRecorder. func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string) { @@ -161,7 +179,8 @@ func (m *Manager) RecordReactionUndo(channel, chatID string, undo func()) { // preSend handles typing stop, reaction undo, and placeholder editing before sending a message. // Returns the delivered message IDs and true when delivery completed before a normal Send. func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMessage, ch Channel) ([]string, bool) { - key := name + ":" + msg.ChatID + chatID := outboundMessageChatID(msg) + key := name + ":" + chatID // 1. Stop typing if v, loaded := m.typingStops.LoadAndDelete(key); loaded { @@ -183,9 +202,9 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess if entry, ok := v.(placeholderEntry); ok && entry.id != "" { // Prefer deleting the placeholder (cleaner UX than editing to same content) if deleter, ok := ch.(MessageDeleter); ok { - deleter.DeleteMessage(ctx, msg.ChatID, entry.id) // best effort + deleter.DeleteMessage(ctx, chatID, entry.id) // best effort } else if editor, ok := ch.(MessageEditor); ok { - editor.EditMessage(ctx, msg.ChatID, entry.id, msg.Content) // fallback + editor.EditMessage(ctx, chatID, entry.id, msg.Content) // fallback } } } @@ -196,7 +215,7 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess if v, loaded := m.placeholders.LoadAndDelete(key); loaded { if entry, ok := v.(placeholderEntry); ok && entry.id != "" { if editor, ok := ch.(MessageEditor); ok { - if err := editor.EditMessage(ctx, msg.ChatID, entry.id, msg.Content); err == nil { + if err := editor.EditMessage(ctx, chatID, entry.id, msg.Content); err == nil { return []string{entry.id}, true } // edit failed → fall through to normal Send @@ -212,7 +231,8 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess // delivery never edits the placeholder because there is no text payload to // replace it with; it only attempts to delete the placeholder when possible. func (m *Manager) preSendMedia(ctx context.Context, name string, msg bus.OutboundMediaMessage, ch Channel) { - key := name + ":" + msg.ChatID + chatID := outboundMediaChatID(msg) + key := name + ":" + chatID // 1. Stop typing if v, loaded := m.typingStops.LoadAndDelete(key); loaded { @@ -235,7 +255,7 @@ func (m *Manager) preSendMedia(ctx context.Context, name string, msg bus.Outboun if v, loaded := m.placeholders.LoadAndDelete(key); loaded { if entry, ok := v.(placeholderEntry); ok && entry.id != "" { if deleter, ok := ch.(MessageDeleter); ok { - deleter.DeleteMessage(ctx, msg.ChatID, entry.id) // best effort + deleter.DeleteMessage(ctx, chatID, entry.id) // best effort } } } @@ -311,22 +331,27 @@ func (s *finalizeHookStreamer) Finalize(ctx context.Context, content string) err return nil } -// initChannel is a helper that looks up a factory by name and creates the channel. -func (m *Manager) initChannel(name, displayName string) { - f, ok := getFactory(name) +// initChannel is a helper that looks up a factory by type name and creates the channel. +// typeName is the channel type used for factory lookup (e.g., "telegram"). +// channelName is the config map key used as the channel's runtime name (e.g., "my_telegram"). +func (m *Manager) initChannel(typeName, channelName string) { + f, ok := getFactory(typeName) if !ok { logger.WarnCF("channels", "Factory not registered", map[string]any{ - "channel": displayName, + "channel": channelName, + "type": typeName, }) return } logger.DebugCF("channels", "Attempting to initialize channel", map[string]any{ - "channel": displayName, + "channel": channelName, + "type": typeName, }) - ch, err := f(m.config, m.bus) + ch, err := f(channelName, typeName, m.config, m.bus) if err != nil { logger.ErrorCF("channels", "Failed to initialize channel", map[string]any{ - "channel": displayName, + "channel": channelName, + "type": typeName, "error": err.Error(), }) } else { @@ -344,90 +369,100 @@ func (m *Manager) initChannel(name, displayName string) { if setter, ok := ch.(interface{ SetOwner(ch Channel) }); ok { setter.SetOwner(ch) } - m.channels[name] = ch + m.channels[channelName] = ch logger.InfoCF("channels", "Channel enabled successfully", map[string]any{ - "channel": displayName, + "channel": channelName, + "type": typeName, }) } } +func (m *Manager) getChannelConfigAndEnabled(channelName string) (*config.Channel, bool) { + bc, ok := m.config.Channels[channelName] + if !ok || bc == nil { + return nil, false + } + if !bc.Enabled { + return bc, false + } + + // Use Type to determine the config struct for validation. + // The map key (channelName) is the config key, which may differ from the type. + channelType := bc.Type + if channelType == "" { + channelType = channelName + } + + // Settings have already been decoded by InitChannelList, so we just need to + // type-assert and check the relevant fields. + decoded, err := bc.GetDecoded() + if err != nil { + return bc, false + } + //nolint:revive + switch settings := decoded.(type) { + case *config.WhatsAppSettings: + if channelType == config.ChannelWhatsApp { + return bc, settings.BridgeURL != "" + } + return bc, channelType == config.ChannelWhatsAppNative && settings.UseNative + case *config.MatrixSettings: + return bc, settings.Homeserver != "" && settings.UserID != "" && settings.AccessToken.String() != "" + case *config.WeComSettings: + return bc, settings.BotID != "" && settings.Secret.String() != "" + case *config.PicoClientSettings: + return bc, settings.URL != "" + case *config.DingTalkSettings: + return bc, settings.ClientID != "" + case *config.SlackSettings: + return bc, settings.BotToken.String() != "" + case *config.WeixinSettings: + return bc, settings.Token.String() != "" + case *config.PicoSettings: + return bc, settings.Token.String() != "" + case *config.IRCSettings: + return bc, settings.Server != "" + case *config.LINESettings: + return bc, settings.ChannelAccessToken.String() != "" + case *config.OneBotSettings: + return bc, settings.WSUrl != "" + case *config.QQSettings: + return bc, settings.AppSecret.String() != "" + case *config.TelegramSettings: + return bc, settings.Token.String() != "" + case *config.FeishuSettings: + return bc, settings.AppSecret.String() != "" + case *config.MaixCamSettings: + return bc, true + case *config.TeamsWebhookSettings: + return bc, true + case *config.DiscordSettings: + return bc, settings.Token.String() != "" + case *config.VKSettings: + return bc, settings.GroupID != 0 && settings.Token.String() != "" + } + + return bc, bc.Enabled +} + +// initChannels initializes all enabled channels based on the configuration. +// It iterates config entries and uses bc.Type to look up the appropriate factory. func (m *Manager) initChannels(channels *config.ChannelsConfig) error { logger.InfoC("channels", "Initializing channel manager") - if channels.Telegram.Enabled && channels.Telegram.Token.String() != "" { - m.initChannel("telegram", "Telegram") - } - - if channels.WhatsApp.Enabled { - waCfg := channels.WhatsApp - if waCfg.UseNative { - m.initChannel("whatsapp_native", "WhatsApp Native") - } else if waCfg.BridgeURL != "" { - m.initChannel("whatsapp", "WhatsApp") + for name, bc := range *channels { + if !bc.Enabled { + continue } - } - - if channels.Feishu.Enabled { - m.initChannel("feishu", "Feishu") - } - - if channels.Discord.Enabled && channels.Discord.Token.String() != "" { - m.initChannel("discord", "Discord") - } - - if channels.MaixCam.Enabled { - m.initChannel("maixcam", "MaixCam") - } - - if channels.QQ.Enabled { - m.initChannel("qq", "QQ") - } - - if channels.DingTalk.Enabled && channels.DingTalk.ClientID != "" { - m.initChannel("dingtalk", "DingTalk") - } - - if channels.Slack.Enabled && channels.Slack.BotToken.String() != "" { - m.initChannel("slack", "Slack") - } - - if channels.Matrix.Enabled && - m.config.Channels.Matrix.Homeserver != "" && - m.config.Channels.Matrix.UserID != "" && - m.config.Channels.Matrix.AccessToken.String() != "" { - m.initChannel("matrix", "Matrix") - } - - if channels.LINE.Enabled && channels.LINE.ChannelAccessToken.String() != "" { - m.initChannel("line", "LINE") - } - - if channels.OneBot.Enabled && channels.OneBot.WSUrl != "" { - m.initChannel("onebot", "OneBot") - } - - if channels.WeCom.Enabled && channels.WeCom.BotID != "" && channels.WeCom.Secret.String() != "" { - m.initChannel("wecom", "WeCom") - } - - if channels.Weixin.Enabled && channels.Weixin.Token.String() != "" { - m.initChannel("weixin", "Weixin") - } - - if channels.Pico.Enabled && channels.Pico.Token.String() != "" { - m.initChannel("pico", "Pico") - } - - if channels.PicoClient.Enabled && channels.PicoClient.URL != "" { - m.initChannel("pico_client", "Pico Client") - } - - if channels.IRC.Enabled && channels.IRC.Server != "" { - m.initChannel("irc", "IRC") - } - - if channels.VK.Enabled && channels.VK.Token.String() != "" && channels.VK.GroupID != 0 { - m.initChannel("vk", "VK") + _, ready := m.getChannelConfigAndEnabled(name) + if !ready { + continue + } + typeName := bc.Type + if typeName == "" { + typeName = name + } + m.initChannel(typeName, name) } logger.InfoCF("channels", "Channel initialization completed", map[string]any{ @@ -441,6 +476,12 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error { // It registers health endpoints from the health server and discovers channels // that implement WebhookHandler and/or HealthChecker to register their handlers. func (m *Manager) SetupHTTPServer(addr string, healthServer *health.Server) { + m.SetupHTTPServerListeners(nil, addr, healthServer) +} + +// SetupHTTPServerListeners creates a shared HTTP server on pre-opened listeners. +// When listeners is empty it falls back to Addr-based ListenAndServe behavior. +func (m *Manager) SetupHTTPServerListeners(listeners []net.Listener, addr string, healthServer *health.Server) { m.mux = newDynamicServeMux() // Register health endpoints @@ -457,6 +498,7 @@ func (m *Manager) SetupHTTPServer(addr string, healthServer *health.Server) { ReadTimeout: 30 * time.Second, WriteTimeout: 30 * time.Second, } + m.httpListeners = append([]net.Listener(nil), listeners...) } // registerHTTPHandlersLocked registers webhook and health-check handlers for @@ -535,7 +577,13 @@ func (m *Manager) StartAll(ctx context.Context) error { continue } // Lazily create worker only after channel starts successfully - w := newChannelWorker(name, channel) + channelType := name + if m.config != nil { + if bc := m.config.Channels.Get(name); bc != nil && bc.Type != "" { + channelType = bc.Type + } + } + w := newChannelWorker(name, channel, channelType) m.workers[name] = w go m.runWorker(dispatchCtx, name, w) go m.runMediaWorker(dispatchCtx, name, w) @@ -580,16 +628,33 @@ func (m *Manager) StartAll(ctx context.Context) error { // Start shared HTTP server if configured if m.httpServer != nil { - go func() { - logger.InfoCF("channels", "Shared HTTP server listening", map[string]any{ - "addr": m.httpServer.Addr, - }) - if err := m.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed { - logger.FatalCF("channels", "Shared HTTP server error", map[string]any{ - "error": err.Error(), - }) + if len(m.httpListeners) > 0 { + for _, listener := range m.httpListeners { + ln := listener + go func() { + logger.InfoCF("channels", "Shared HTTP server listening", map[string]any{ + "addr": ln.Addr().String(), + }) + if err := m.httpServer.Serve(ln); err != nil && err != http.ErrServerClosed { + logger.FatalCF("channels", "Shared HTTP server error", map[string]any{ + "addr": ln.Addr().String(), + "error": err.Error(), + }) + } + }() } - }() + } else { + go func() { + logger.InfoCF("channels", "Shared HTTP server listening", map[string]any{ + "addr": m.httpServer.Addr, + }) + if err := m.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed { + logger.FatalCF("channels", "Shared HTTP server error", map[string]any{ + "error": err.Error(), + }) + } + }() + } } logger.InfoCF("channels", "Channel startup completed", map[string]any{ @@ -616,6 +681,7 @@ func (m *Manager) StopAll(ctx context.Context) error { }) } m.httpServer = nil + m.httpListeners = nil } // Cancel dispatcher @@ -665,10 +731,10 @@ func (m *Manager) StopAll(ctx context.Context) error { } // newChannelWorker creates a channelWorker with a rate limiter configured -// for the given channel name. -func newChannelWorker(name string, ch Channel) *channelWorker { +// for the given channel type. channelType is used for rate limit lookup. +func newChannelWorker(name string, ch Channel, channelType string) *channelWorker { rateVal := float64(defaultRateLimit) - if r, ok := channelRateConfig[name]; ok { + if r, ok := channelRateConfig[channelType]; ok { rateVal = r } burst := int(math.Max(1, math.Ceil(rateVal/2))) @@ -799,7 +865,7 @@ func (m *Manager) sendWithRetry( // All retries exhausted or permanent failure logger.ErrorCF("channels", "Send failed", map[string]any{ "channel": name, - "chat_id": msg.ChatID, + "chat_id": outboundMessageChatID(msg), "error": lastErr.Error(), "retries": maxRetries, }) @@ -861,7 +927,7 @@ func (m *Manager) dispatchOutbound(ctx context.Context) { dispatchLoop( ctx, m, m.bus.OutboundChan(), - func(msg bus.OutboundMessage) string { return msg.Channel }, + func(msg bus.OutboundMessage) string { return outboundMessageChannel(msg) }, func(ctx context.Context, w *channelWorker, msg bus.OutboundMessage) bool { select { case w.queue <- msg: @@ -881,7 +947,7 @@ func (m *Manager) dispatchOutboundMedia(ctx context.Context) { dispatchLoop( ctx, m, m.bus.OutboundMediaChan(), - func(msg bus.OutboundMediaMessage) string { return msg.Channel }, + func(msg bus.OutboundMediaMessage) string { return outboundMediaChannel(msg) }, func(ctx context.Context, w *channelWorker, msg bus.OutboundMediaMessage) bool { select { case w.mediaQueue <- msg: @@ -980,7 +1046,7 @@ func (m *Manager) sendMediaWithRetry( // All retries exhausted or permanent failure logger.ErrorCF("channels", "SendMedia failed", map[string]any{ "channel": name, - "chat_id": msg.ChatID, + "chat_id": outboundMediaChatID(msg), "error": lastErr.Error(), "retries": maxRetries, }) @@ -1124,7 +1190,13 @@ func (m *Manager) Reload(ctx context.Context, cfg *config.Config) error { continue } // Lazily create worker only after channel starts successfully - w := newChannelWorker(name, channel) + channelType := name + if m.config != nil { + if bc := m.config.Channels.Get(name); bc != nil && bc.Type != "" { + channelType = bc.Type + } + } + w := newChannelWorker(name, channel, channelType) m.workers[name] = w go m.runWorker(dispatchCtx, name, w) go m.runMediaWorker(dispatchCtx, name, w) @@ -1173,16 +1245,19 @@ func (m *Manager) UnregisterChannel(name string) { // delivered (or all retries are exhausted), which preserves ordering when // a subsequent operation depends on the message having been sent. func (m *Manager) SendMessage(ctx context.Context, msg bus.OutboundMessage) error { + msg = bus.NormalizeOutboundMessage(msg) + channelName := outboundMessageChannel(msg) + m.mu.RLock() - _, exists := m.channels[msg.Channel] - w, wExists := m.workers[msg.Channel] + _, exists := m.channels[channelName] + w, wExists := m.workers[channelName] m.mu.RUnlock() if !exists { - return fmt.Errorf("channel %s not found", msg.Channel) + return fmt.Errorf("channel %s not found", channelName) } if !wExists || w == nil { - return fmt.Errorf("channel %s has no active worker", msg.Channel) + return fmt.Errorf("channel %s has no active worker", channelName) } maxLen := 0 @@ -1193,10 +1268,10 @@ func (m *Manager) SendMessage(ctx context.Context, msg bus.OutboundMessage) erro for _, chunk := range SplitMessage(msg.Content, maxLen) { chunkMsg := msg chunkMsg.Content = chunk - m.sendWithRetry(ctx, msg.Channel, w, chunkMsg) + m.sendWithRetry(ctx, channelName, w, chunkMsg) } } else { - m.sendWithRetry(ctx, msg.Channel, w, msg) + m.sendWithRetry(ctx, channelName, w, msg) } return nil } @@ -1206,19 +1281,22 @@ func (m *Manager) SendMessage(ctx context.Context, msg bus.OutboundMessage) erro // retries are exhausted), which preserves ordering when later agent behavior // depends on actual media delivery. func (m *Manager) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error { + msg = bus.NormalizeOutboundMediaMessage(msg) + channelName := outboundMediaChannel(msg) + m.mu.RLock() - _, exists := m.channels[msg.Channel] - w, wExists := m.workers[msg.Channel] + _, exists := m.channels[channelName] + w, wExists := m.workers[channelName] m.mu.RUnlock() if !exists { - return fmt.Errorf("channel %s not found", msg.Channel) + return fmt.Errorf("channel %s not found", channelName) } if !wExists || w == nil { - return fmt.Errorf("channel %s has no active worker", msg.Channel) + return fmt.Errorf("channel %s has no active worker", channelName) } - _, err := m.sendMediaWithRetry(ctx, msg.Channel, w, msg) + _, err := m.sendMediaWithRetry(ctx, channelName, w, msg) return err } @@ -1233,10 +1311,10 @@ func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, conten } msg := bus.OutboundMessage{ - Channel: channelName, - ChatID: chatID, + Context: bus.NewOutboundContext(channelName, chatID, ""), Content: content, } + msg = bus.NormalizeOutboundMessage(msg) if wExists && w != nil { select { diff --git a/pkg/channels/manager_channel.go b/pkg/channels/manager_channel.go index b1c8c25e0..1f5978e7d 100644 --- a/pkg/channels/manager_channel.go +++ b/pkg/channels/manager_channel.go @@ -6,7 +6,6 @@ import ( "encoding/json" "github.com/sipeed/picoclaw/pkg/config" - "github.com/sipeed/picoclaw/pkg/logger" ) func toChannelHashes(cfg *config.Config) map[string]string { @@ -21,7 +20,7 @@ func toChannelHashes(cfg *config.Config) map[string]string { if !value["enabled"].(bool) { continue } - hiddenValues(key, value, ch) + hiddenValues(key, value, ch.Get(key)) valueBytes, _ := json.Marshal(value) hash := md5.Sum(valueBytes) result[key] = hex.EncodeToString(hash[:]) @@ -30,38 +29,79 @@ func toChannelHashes(cfg *config.Config) map[string]string { return result } -func hiddenValues(key string, value map[string]any, ch config.ChannelsConfig) { +func hiddenValues(key string, value map[string]any, ch *config.Channel) { + v, err := ch.GetDecoded() + if err != nil { + return + } switch key { case "pico": - value["token"] = ch.Pico.Token.String() + if settings, ok := v.(*config.PicoSettings); ok { + value["token"] = settings.Token.String() + } case "telegram": - value["token"] = ch.Telegram.Token.String() + if settings, ok := v.(*config.TelegramSettings); ok { + value["token"] = settings.Token.String() + } case "discord": - value["token"] = ch.Discord.Token.String() + if settings, ok := v.(*config.DiscordSettings); ok { + value["token"] = settings.Token.String() + } case "slack": - value["bot_token"] = ch.Slack.BotToken.String() - value["app_token"] = ch.Slack.AppToken.String() + if settings, ok := v.(*config.SlackSettings); ok { + value["bot_token"] = settings.BotToken.String() + value["app_token"] = settings.AppToken.String() + } case "matrix": - value["token"] = ch.Matrix.AccessToken.String() + if settings, ok := v.(*config.MatrixSettings); ok { + value["token"] = settings.AccessToken.String() + } case "onebot": - value["token"] = ch.OneBot.AccessToken.String() + if settings, ok := v.(*config.OneBotSettings); ok { + value["token"] = settings.AccessToken.String() + } case "line": - value["token"] = ch.LINE.ChannelAccessToken.String() - value["secret"] = ch.LINE.ChannelSecret.String() + if settings, ok := v.(*config.LINESettings); ok { + value["token"] = settings.ChannelAccessToken.String() + value["secret"] = settings.ChannelSecret.String() + } case "wecom": - value["secret"] = ch.WeCom.Secret.String() + if settings, ok := v.(*config.WeComSettings); ok { + value["secret"] = settings.Secret.String() + } case "dingtalk": - value["secret"] = ch.DingTalk.ClientSecret.String() + if settings, ok := v.(*config.DingTalkSettings); ok { + value["secret"] = settings.ClientSecret.String() + } case "qq": - value["secret"] = ch.QQ.AppSecret.String() + if settings, ok := v.(*config.QQSettings); ok { + value["secret"] = settings.AppSecret.String() + } case "irc": - value["password"] = ch.IRC.Password.String() - value["serv_password"] = ch.IRC.NickServPassword.String() - value["sasl_password"] = ch.IRC.SASLPassword.String() + if settings, ok := v.(*config.IRCSettings); ok { + value["password"] = settings.Password.String() + value["serv_password"] = settings.NickServPassword.String() + value["sasl_password"] = settings.SASLPassword.String() + } case "feishu": - value["app_secret"] = ch.Feishu.AppSecret.String() - value["encrypt_key"] = ch.Feishu.EncryptKey.String() - value["verification_token"] = ch.Feishu.VerificationToken.String() + if settings, ok := v.(*config.FeishuSettings); ok { + value["app_secret"] = settings.AppSecret.String() + value["encrypt_key"] = settings.EncryptKey.String() + value["verification_token"] = settings.VerificationToken.String() + } + case "teams_webhook": + // Expose webhook URLs for hash computation (they contain secrets) + vv := value["webhooks"] + webhooks := make(map[string]string) + if vv != nil { + webhooks = vv.(map[string]string) + } + if settings, ok := v.(*config.TeamsWebhookSettings); ok { + for name, target := range settings.Webhooks { + webhooks[name] = target.WebhookURL.String() + } + } + value["webhooks"] = webhooks } } @@ -85,85 +125,13 @@ func compareChannels(old, news map[string]string) (added, removed []string) { } func toChannelConfig(cfg *config.Config, list []string) (*config.ChannelsConfig, error) { - result := &config.ChannelsConfig{} - ch := cfg.Channels - // should not be error - marshal, _ := json.Marshal(ch) - var channelConfig map[string]map[string]any - _ = json.Unmarshal(marshal, &channelConfig) - temp := make(map[string]map[string]any, 0) - - for key, value := range channelConfig { - found := false - for _, s := range list { - if key == s { - found = true - break - } - } - if !found || !value["enabled"].(bool) { + result := make(config.ChannelsConfig) + for _, name := range list { + bc, ok := cfg.Channels[name] + if !ok || !bc.Enabled { continue } - temp[key] = value - } - - marshal, err := json.Marshal(temp) - if err != nil { - logger.Errorf("marshal error: %v", err) - return nil, err - } - err = json.Unmarshal(marshal, result) - if err != nil { - logger.Errorf("unmarshal error: %v", err) - return nil, err - } - - updateKeys(result, &ch) - - return result, nil -} - -func updateKeys(newcfg, old *config.ChannelsConfig) { - if newcfg.Pico.Enabled { - newcfg.Pico.Token = old.Pico.Token - } - if newcfg.Telegram.Enabled { - newcfg.Telegram.Token = old.Telegram.Token - } - if newcfg.Discord.Enabled { - newcfg.Discord.Token = old.Discord.Token - } - if newcfg.Slack.Enabled { - newcfg.Slack.BotToken = old.Slack.BotToken - newcfg.Slack.AppToken = old.Slack.AppToken - } - if newcfg.Matrix.Enabled { - newcfg.Matrix.AccessToken = old.Matrix.AccessToken - } - if newcfg.OneBot.Enabled { - newcfg.OneBot.AccessToken = old.OneBot.AccessToken - } - if newcfg.LINE.Enabled { - newcfg.LINE.ChannelAccessToken = old.LINE.ChannelAccessToken - newcfg.LINE.ChannelSecret = old.LINE.ChannelSecret - } - if newcfg.WeCom.Enabled { - newcfg.WeCom.Secret = old.WeCom.Secret - } - if newcfg.DingTalk.Enabled { - newcfg.DingTalk.ClientSecret = old.DingTalk.ClientSecret - } - if newcfg.QQ.Enabled { - newcfg.QQ.AppSecret = old.QQ.AppSecret - } - if newcfg.IRC.Enabled { - newcfg.IRC.Password = old.IRC.Password - newcfg.IRC.NickServPassword = old.IRC.NickServPassword - newcfg.IRC.SASLPassword = old.IRC.SASLPassword - } - if newcfg.Feishu.Enabled { - newcfg.Feishu.AppSecret = old.Feishu.AppSecret - newcfg.Feishu.EncryptKey = old.Feishu.EncryptKey - newcfg.Feishu.VerificationToken = old.Feishu.VerificationToken + result[name] = bc } + return &result, nil } diff --git a/pkg/channels/manager_channel_test.go b/pkg/channels/manager_channel_test.go index 3de1e2b3f..b991e58d6 100644 --- a/pkg/channels/manager_channel_test.go +++ b/pkg/channels/manager_channel_test.go @@ -1,6 +1,7 @@ package channels import ( + "encoding/json" "testing" "github.com/stretchr/testify/assert" @@ -15,37 +16,138 @@ func TestToChannelHashes(t *testing.T) { results := toChannelHashes(cfg) assert.Equal(t, 0, len(results)) logger.Debugf("results: %v", results) + + // Add dingtalk channel via map cfg2 := config.DefaultConfig() - cfg2.Channels.DingTalk.Enabled = true + cfg2.Channels["dingtalk"] = &config.Channel{ + Enabled: true, + Type: config.ChannelDingTalk, + Settings: config.RawNode(`{"enabled":true}`), + } results2 := toChannelHashes(cfg2) assert.Equal(t, 1, len(results2)) logger.Debugf("results2: %v", results2) added, removed := compareChannels(results, results2) assert.EqualValues(t, []string{"dingtalk"}, added) assert.EqualValues(t, []string(nil), removed) + + // Add telegram channel cfg3 := config.DefaultConfig() - cfg3.Channels.Telegram.Enabled = true + cfg3.Channels["telegram"] = &config.Channel{ + Enabled: true, + Type: config.ChannelTelegram, + Settings: config.RawNode(`{"enabled":true,"token":"test-token"}`), + } results3 := toChannelHashes(cfg3) assert.Equal(t, 1, len(results3)) logger.Debugf("results3: %v", results3) added, removed = compareChannels(results2, results3) assert.EqualValues(t, []string{"dingtalk"}, removed) assert.EqualValues(t, []string{"telegram"}, added) - cfg3.Channels.Telegram.SetToken("114314") + + // Modify telegram channel — hash should change + cfg3.Channels["telegram"] = &config.Channel{ + Enabled: true, + Type: config.ChannelTelegram, + Settings: config.RawNode(`{"enabled":true,"token":"114314"}`), + } results4 := toChannelHashes(cfg3) assert.Equal(t, 1, len(results4)) logger.Debugf("results4: %v", results4) added, removed = compareChannels(results3, results4) assert.EqualValues(t, []string{"telegram"}, removed) assert.EqualValues(t, []string{"telegram"}, added) + + // toChannelConfig with telegram cc, err := toChannelConfig(cfg3, added) assert.NoError(t, err) - logger.Debugf("cc: %#v", cc.Telegram) - assert.Equal(t, "114314", cc.Telegram.Token.String()) - assert.Equal(t, true, cc.Telegram.Enabled) + bc := cc.Get("telegram") + assert.NotNil(t, bc) + var tc config.TelegramSettings + bc.Decode(&tc) + assert.Equal(t, "114314", tc.Token.String()) + assert.Equal(t, true, bc.Enabled) + + // toChannelConfig with dingtalk (no telegram) cc, err = toChannelConfig(cfg2, added) assert.NoError(t, err) - logger.Debugf("cc: %#v", cc.Telegram) - assert.Equal(t, "", cc.Telegram.Token.String()) - assert.Equal(t, false, cc.Telegram.Enabled) + bc = cc.Get("telegram") + assert.Nil(t, bc) +} + +func TestToChannelHashes_SerializationStability(t *testing.T) { + cfg := config.DefaultConfig() + cfg.Channels["test"] = &config.Channel{ + Enabled: true, + Settings: config.RawNode(`{"enabled":true,"key":"value"}`), + } + h1 := toChannelHashes(cfg) + + // Same config should produce same hash + cfg2 := config.DefaultConfig() + cfg2.Channels["test"] = &config.Channel{ + Enabled: true, + Settings: config.RawNode(`{"enabled":true,"key":"value"}`), + } + h2 := toChannelHashes(cfg2) + assert.Equal(t, h1["test"], h2["test"]) +} + +func TestCompareChannels_NoChanges(t *testing.T) { + cfg := config.DefaultConfig() + cfg.Channels["a"] = &config.Channel{Enabled: true, Settings: config.RawNode(`{}`)} + cfg.Channels["b"] = &config.Channel{Enabled: true, Settings: config.RawNode(`{}`)} + h := toChannelHashes(cfg) + + added, removed := compareChannels(h, h) + assert.EqualValues(t, []string(nil), added) + assert.EqualValues(t, []string(nil), removed) +} + +func TestToChannelConfig_EmptyList(t *testing.T) { + cfg := config.DefaultConfig() + cfg.Channels["test"] = &config.Channel{Enabled: true, Settings: config.RawNode(`{}`)} + + cc, err := toChannelConfig(cfg, []string{}) + assert.NoError(t, err) + assert.Equal(t, 0, len(*cc)) +} + +func TestToChannelHashes_NonEnabledSkipped(t *testing.T) { + cfg := config.DefaultConfig() + cfg.Channels["test"] = &config.Channel{Enabled: false, Settings: config.RawNode(`{"enabled":false}`)} + + h := toChannelHashes(cfg) + assert.Equal(t, 0, len(h)) +} + +func TestToChannelHashes_InvalidJSON(t *testing.T) { + cfg := config.DefaultConfig() + cfg.Channels["test"] = &config.Channel{ + Enabled: true, + Settings: config.RawNode(`invalid-json`), + } + + // Should not panic, just skip the invalid entry + h := toChannelHashes(cfg) + assert.Equal(t, 0, len(h)) +} + +func TestToChannelHashes_RealWorldChannel(t *testing.T) { + cfg := config.DefaultConfig() + + // Simulate a telegram channel config + telegramSettings, _ := json.Marshal(map[string]any{ + "enabled": true, + "token": "123456:ABC-DEF", + }) + cfg.Channels["telegram"] = &config.Channel{ + Enabled: true, + Type: config.ChannelTelegram, + Settings: config.RawNode(telegramSettings), + } + + h := toChannelHashes(cfg) + assert.Equal(t, 1, len(h)) + assert.Contains(t, h, "telegram") } diff --git a/pkg/channels/manager_test.go b/pkg/channels/manager_test.go index 937b32d2c..881993d9c 100644 --- a/pkg/channels/manager_test.go +++ b/pkg/channels/manager_test.go @@ -175,11 +175,11 @@ func TestStartAll_PartialFailure_StartsSuccessfulWorkers(t *testing.T) { pubCtx, pubCancel := context.WithTimeout(context.Background(), 2*time.Second) defer pubCancel() - if err := m.bus.PublishOutbound(pubCtx, bus.OutboundMessage{ + if err := m.bus.PublishOutbound(pubCtx, testOutboundMessage(bus.OutboundMessage{ Channel: "good", ChatID: "chat-1", Content: "hello", - }); err != nil { + })); err != nil { t.Fatalf("PublishOutbound() error = %v", err) } @@ -197,6 +197,20 @@ func TestStartAll_PartialFailure_StartsSuccessfulWorkers(t *testing.T) { } } +func testOutboundMessage(msg bus.OutboundMessage) bus.OutboundMessage { + if msg.Context.Channel == "" && msg.Context.ChatID == "" { + msg.Context = bus.NewOutboundContext(msg.Channel, msg.ChatID, msg.ReplyToMessageID) + } + return bus.NormalizeOutboundMessage(msg) +} + +func testOutboundMediaMessage(msg bus.OutboundMediaMessage) bus.OutboundMediaMessage { + if msg.Context.Channel == "" && msg.Context.ChatID == "" { + msg.Context = bus.NewOutboundContext(msg.Channel, msg.ChatID, "") + } + return bus.NormalizeOutboundMediaMessage(msg) +} + func TestSendWithRetry_Success(t *testing.T) { m := newTestManager() var callCount int @@ -212,7 +226,7 @@ func TestSendWithRetry_Success(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) m.sendWithRetry(ctx, "test", w, msg) @@ -239,7 +253,7 @@ func TestSendWithRetry_TemporaryThenSuccess(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) m.sendWithRetry(ctx, "test", w, msg) @@ -263,7 +277,7 @@ func TestSendWithRetry_PermanentFailure(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) m.sendWithRetry(ctx, "test", w, msg) @@ -287,7 +301,7 @@ func TestSendWithRetry_NotRunning(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) m.sendWithRetry(ctx, "test", w, msg) @@ -314,7 +328,7 @@ func TestSendWithRetry_RateLimitRetry(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) start := time.Now() m.sendWithRetry(ctx, "test", w, msg) @@ -344,7 +358,7 @@ func TestSendWithRetry_MaxRetriesExhausted(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) m.sendWithRetry(ctx, "test", w, msg) @@ -370,11 +384,11 @@ func TestSendMedia_Success(t *testing.T) { m.channels["test"] = ch m.workers["test"] = w - err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{ + err := m.SendMedia(context.Background(), testOutboundMediaMessage(bus.OutboundMediaMessage{ Channel: "test", ChatID: "chat1", Parts: []bus.MediaPart{{Ref: "media://abc"}}, - }) + })) if err != nil { t.Fatalf("SendMedia() error = %v", err) } @@ -397,11 +411,11 @@ func TestSendMedia_PropagatesFailure(t *testing.T) { m.channels["test"] = ch m.workers["test"] = w - err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{ + err := m.SendMedia(context.Background(), testOutboundMediaMessage(bus.OutboundMediaMessage{ Channel: "test", ChatID: "chat1", Parts: []bus.MediaPart{{Ref: "media://abc"}}, - }) + })) if err == nil { t.Fatal("expected SendMedia to return error") } @@ -424,11 +438,11 @@ func TestSendMedia_UnsupportedChannelReturnsError(t *testing.T) { m.channels["test"] = ch m.workers["test"] = w - err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{ + err := m.SendMedia(context.Background(), testOutboundMediaMessage(bus.OutboundMediaMessage{ Channel: "test", ChatID: "chat1", Parts: []bus.MediaPart{{Ref: "media://abc"}}, - }) + })) if err == nil { t.Fatal("expected SendMedia to return error for unsupported channel") } @@ -454,11 +468,11 @@ func TestSendMedia_DeletesPlaceholderBeforeSending(t *testing.T) { m.workers["test"] = w m.RecordPlaceholder("test", "chat1", "placeholder-1") - err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{ + err := m.SendMedia(context.Background(), testOutboundMediaMessage(bus.OutboundMediaMessage{ Channel: "test", ChatID: "chat1", Parts: []bus.MediaPart{{Ref: "media://abc"}}, - }) + })) if err != nil { t.Fatalf("SendMedia() error = %v", err) } @@ -491,7 +505,7 @@ func TestSendWithRetry_UnknownError(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) m.sendWithRetry(ctx, "test", w, msg) @@ -515,7 +529,7 @@ func TestSendWithRetry_ContextCancelled(t *testing.T) { } ctx, cancel := context.WithCancel(context.Background()) - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) // Cancel context after first Send attempt returns ch.sendFn = func(_ context.Context, _ bus.OutboundMessage) error { @@ -561,7 +575,7 @@ func TestWorkerRateLimiter(t *testing.T) { // Enqueue 4 messages for i := range 4 { - w.queue <- bus.OutboundMessage{Channel: "test", ChatID: "1", Content: fmt.Sprintf("msg%d", i)} + w.queue <- testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: fmt.Sprintf("msg%d", i)}) } // Wait enough time for all messages to be sent (4 msgs at 2/s = ~2s, give extra margin) @@ -586,7 +600,7 @@ func TestWorkerRateLimiter(t *testing.T) { func TestNewChannelWorker_DefaultRate(t *testing.T) { ch := &mockChannel{} - w := newChannelWorker("unknown_channel", ch) + w := newChannelWorker("unknown_channel", ch, "unknown_channel") if w.limiter == nil { t.Fatal("expected limiter to be non-nil") @@ -599,10 +613,10 @@ func TestNewChannelWorker_DefaultRate(t *testing.T) { func TestNewChannelWorker_ConfiguredRate(t *testing.T) { ch := &mockChannel{} - for name, expectedRate := range channelRateConfig { - w := newChannelWorker(name, ch) + for channelType, expectedRate := range channelRateConfig { + w := newChannelWorker(channelType, ch, channelType) if w.limiter.Limit() != rate.Limit(expectedRate) { - t.Fatalf("channel %s: expected rate %v, got %v", name, expectedRate, w.limiter.Limit()) + t.Fatalf("channel %s: expected rate %v, got %v", channelType, expectedRate, w.limiter.Limit()) } } } @@ -637,7 +651,7 @@ func TestRunWorker_MessageSplitting(t *testing.T) { go m.runWorker(ctx, "test", w) // Send a message that should be split - w.queue <- bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello world"} + w.queue <- testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello world"}) time.Sleep(100 * time.Millisecond) @@ -678,7 +692,7 @@ func TestSendWithRetry_ExponentialBackoff(t *testing.T) { } ctx := context.Background() - msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}) start := time.Now() m.sendWithRetry(ctx, "test", w, msg) @@ -738,7 +752,7 @@ func TestPreSend_PlaceholderEditSuccess(t *testing.T) { // Register placeholder m.RecordPlaceholder("test", "123", "456") - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) _, edited := m.preSend(context.Background(), "test", msg, ch) if !edited { @@ -768,7 +782,7 @@ func TestPreSend_PlaceholderEditFails_FallsThrough(t *testing.T) { m.RecordPlaceholder("test", "123", "456") - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) _, edited := m.preSend(context.Background(), "test", msg, ch) if edited { @@ -827,7 +841,7 @@ func TestPreSend_TypingStopCalled(t *testing.T) { stopCalled = true }) - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) m.preSend(context.Background(), "test", msg, ch) if !stopCalled { @@ -844,7 +858,7 @@ func TestPreSend_NoRegisteredState(t *testing.T) { }, } - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) _, edited := m.preSend(context.Background(), "test", msg, ch) if edited { @@ -874,7 +888,7 @@ func TestPreSend_TypingAndPlaceholder(t *testing.T) { }) m.RecordPlaceholder("test", "123", "456") - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) _, edited := m.preSend(context.Background(), "test", msg, ch) if !stopCalled { @@ -938,7 +952,7 @@ func TestRecordTypingStop_ReplacesExistingStop(t *testing.T) { t.Fatalf("expected replacement typing stop to stay active until preSend, got %d calls", newStopCalls) } - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) m.preSend(context.Background(), "test", msg, &mockChannel{}) if newStopCalls != 1 { @@ -972,7 +986,7 @@ func TestSendWithRetry_PreSendEditsPlaceholder(t *testing.T) { limiter: rate.NewLimiter(rate.Inf, 1), } - msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}) m.sendWithRetry(context.Background(), "test", w, msg) if sendCalled { @@ -1135,7 +1149,7 @@ func TestPreSendStillWorksWithWrappedTypes(t *testing.T) { }) m.RecordPlaceholder("test", "chat1", "ph_id") - msg := bus.OutboundMessage{Channel: "test", ChatID: "chat1", Content: "response"} + msg := testOutboundMessage(bus.OutboundMessage{Channel: "test", ChatID: "chat1", Content: "response"}) _, edited := m.preSend(context.Background(), "test", msg, ch) if !stopCalled { @@ -1222,7 +1236,7 @@ func TestManager_PlaceholderConsumedByResponse(t *testing.T) { return nil }, } - worker := newChannelWorker("mock", mockCh) + worker := newChannelWorker("mock", mockCh, "mock") mgr.channels["mock"] = mockCh mgr.workers["mock"] = worker @@ -1238,11 +1252,11 @@ func TestManager_PlaceholderConsumedByResponse(t *testing.T) { // Transcription feedback arrives first — it should consume the placeholder // and be delivered via EditMessage, not Send. - msgTranscript := bus.OutboundMessage{ + msgTranscript := testOutboundMessage(bus.OutboundMessage{ Channel: "mock", ChatID: "chat-1", Content: "Transcript: hello", - } + }) mgr.sendWithRetry(ctx, "mock", worker, msgTranscript) if mockCh.editedMessages != 1 { @@ -1258,11 +1272,11 @@ func TestManager_PlaceholderConsumedByResponse(t *testing.T) { } // Final LLM response arrives — no placeholder left, so it goes through Send - msgFinal := bus.OutboundMessage{ + msgFinal := testOutboundMessage(bus.OutboundMessage{ Channel: "mock", ChatID: "chat-1", Content: "Final Answer", - } + }) mgr.sendWithRetry(ctx, "mock", worker, msgFinal) if len(mockCh.sentMessages) != 1 { @@ -1288,12 +1302,12 @@ func TestSendMessage_Synchronous(t *testing.T) { m.channels["test"] = ch m.workers["test"] = w - msg := bus.OutboundMessage{ + msg := testOutboundMessage(bus.OutboundMessage{ Channel: "test", ChatID: "123", Content: "hello world", ReplyToMessageID: "msg-456", - } + }) err := m.SendMessage(context.Background(), msg) if err != nil { @@ -1315,11 +1329,11 @@ func TestSendMessage_Synchronous(t *testing.T) { func TestSendMessage_UnknownChannel(t *testing.T) { m := newTestManager() - msg := bus.OutboundMessage{ + msg := testOutboundMessage(bus.OutboundMessage{ Channel: "nonexistent", ChatID: "123", Content: "hello", - } + }) err := m.SendMessage(context.Background(), msg) if err == nil { @@ -1336,11 +1350,11 @@ func TestSendMessage_NoWorker(t *testing.T) { m.channels["test"] = ch // No worker registered - msg := bus.OutboundMessage{ + msg := testOutboundMessage(bus.OutboundMessage{ Channel: "test", ChatID: "123", Content: "hello", - } + }) err := m.SendMessage(context.Background(), msg) if err == nil { @@ -1369,11 +1383,11 @@ func TestSendMessage_WithRetry(t *testing.T) { m.channels["test"] = ch m.workers["test"] = w - msg := bus.OutboundMessage{ + msg := testOutboundMessage(bus.OutboundMessage{ Channel: "test", ChatID: "123", Content: "retry me", - } + }) err := m.SendMessage(context.Background(), msg) if err != nil { @@ -1385,6 +1399,46 @@ func TestSendMessage_WithRetry(t *testing.T) { } } +func TestSendMessage_ContextOnlyUsesContextAddressing(t *testing.T) { + m := newTestManager() + + var received []bus.OutboundMessage + ch := &mockChannel{ + sendFn: func(_ context.Context, msg bus.OutboundMessage) error { + received = append(received, msg) + return nil + }, + } + + w := &channelWorker{ + ch: ch, + limiter: rate.NewLimiter(rate.Inf, 1), + } + m.channels["test"] = ch + m.workers["test"] = w + + msg := testOutboundMessage(bus.OutboundMessage{ + Context: bus.NewOutboundContext("test", "123", "msg-9"), + Content: "hello", + }) + + if err := m.SendMessage(context.Background(), msg); err != nil { + t.Fatalf("expected no error, got %v", err) + } + if len(received) != 1 { + t.Fatalf("expected 1 message sent, got %d", len(received)) + } + if received[0].Channel != "test" || received[0].ChatID != "123" { + t.Fatalf("expected mirrored legacy address, got %+v", received[0]) + } + if received[0].Context.Channel != "test" || received[0].Context.ChatID != "123" { + t.Fatalf("expected context address to be preserved, got %+v", received[0].Context) + } + if received[0].ReplyToMessageID != "msg-9" { + t.Fatalf("expected reply_to_message_id msg-9, got %q", received[0].ReplyToMessageID) + } +} + func TestSendMessage_WithSplitting(t *testing.T) { m := newTestManager() @@ -1406,11 +1460,11 @@ func TestSendMessage_WithSplitting(t *testing.T) { m.channels["test"] = ch m.workers["test"] = w - msg := bus.OutboundMessage{ + msg := testOutboundMessage(bus.OutboundMessage{ Channel: "test", ChatID: "123", Content: "hello world", - } + }) err := m.SendMessage(context.Background(), msg) if err != nil { @@ -1422,6 +1476,43 @@ func TestSendMessage_WithSplitting(t *testing.T) { } } +func TestSendMedia_ContextOnlyUsesContextAddressing(t *testing.T) { + m := newTestManager() + + var received []bus.OutboundMediaMessage + ch := &mockMediaChannel{ + sendMediaFn: func(_ context.Context, msg bus.OutboundMediaMessage) ([]string, error) { + received = append(received, msg) + return nil, nil + }, + } + + w := &channelWorker{ + ch: ch, + limiter: rate.NewLimiter(rate.Inf, 1), + } + m.channels["test"] = ch + m.workers["test"] = w + + msg := testOutboundMediaMessage(bus.OutboundMediaMessage{ + Context: bus.NewOutboundContext("test", "media-chat", ""), + Parts: []bus.MediaPart{{Type: "image", Ref: "media://1"}}, + }) + + if err := m.SendMedia(context.Background(), msg); err != nil { + t.Fatalf("expected no error, got %v", err) + } + if len(received) != 1 { + t.Fatalf("expected 1 media message sent, got %d", len(received)) + } + if received[0].Channel != "test" || received[0].ChatID != "media-chat" { + t.Fatalf("expected mirrored legacy media address, got %+v", received[0]) + } + if received[0].Context.Channel != "test" || received[0].Context.ChatID != "media-chat" { + t.Fatalf("expected media context address to be preserved, got %+v", received[0].Context) + } +} + func TestSendMessage_PreservesOrdering(t *testing.T) { m := newTestManager() @@ -1441,12 +1532,12 @@ func TestSendMessage_PreservesOrdering(t *testing.T) { m.workers["test"] = w // Send two messages sequentially — they must arrive in order - _ = m.SendMessage(context.Background(), bus.OutboundMessage{ + _ = m.SendMessage(context.Background(), testOutboundMessage(bus.OutboundMessage{ Channel: "test", ChatID: "1", Content: "first", - }) - _ = m.SendMessage(context.Background(), bus.OutboundMessage{ + })) + _ = m.SendMessage(context.Background(), testOutboundMessage(bus.OutboundMessage{ Channel: "test", ChatID: "1", Content: "second", - }) + })) if len(order) != 2 { t.Fatalf("expected 2 messages, got %d", len(order)) diff --git a/pkg/channels/matrix/init.go b/pkg/channels/matrix/init.go index 4d6ad45a7..f645a464b 100644 --- a/pkg/channels/matrix/init.go +++ b/pkg/channels/matrix/init.go @@ -9,12 +9,30 @@ import ( ) func init() { - channels.RegisterFactory("matrix", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - matrixCfg := cfg.Channels.Matrix - cryptoDatabasePath := matrixCfg.CryptoDatabasePath - if cryptoDatabasePath == "" { - cryptoDatabasePath = filepath.Join(cfg.WorkspacePath(), "matrix") - } - return NewMatrixChannel(matrixCfg, b, cryptoDatabasePath) - }) + channels.RegisterFactory( + config.ChannelMatrix, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.MatrixSettings) + if !ok { + return nil, channels.ErrSendFailed + } + cryptoDatabasePath := c.CryptoDatabasePath + if cryptoDatabasePath == "" { + cryptoDatabasePath = filepath.Join(cfg.WorkspacePath(), "matrix") + } + ch, err := NewMatrixChannel(bc, c, b, cryptoDatabasePath) + if err != nil { + return nil, err + } + if channelName != config.ChannelMatrix { + ch.SetName(channelName) + } + return ch, nil + }, + ) } diff --git a/pkg/channels/matrix/matrix.go b/pkg/channels/matrix/matrix.go index 5e975b4f0..40e1b0a36 100644 --- a/pkg/channels/matrix/matrix.go +++ b/pkg/channels/matrix/matrix.go @@ -174,9 +174,10 @@ func (s *typingSession) stop() { // MatrixChannel implements the Channel interface for Matrix. type MatrixChannel struct { *channels.BaseChannel + bc *config.Channel client *mautrix.Client - config config.MatrixConfig + config *config.MatrixSettings syncer *mautrix.DefaultSyncer ctx context.Context @@ -194,7 +195,8 @@ type MatrixChannel struct { } func NewMatrixChannel( - cfg config.MatrixConfig, + bc *config.Channel, + cfg *config.MatrixSettings, messageBus *bus.MessageBus, cryptoDatabasePath string, ) (*MatrixChannel, error) { @@ -228,14 +230,15 @@ func NewMatrixChannel( "matrix", cfg, messageBus, - cfg.AllowFrom, + bc.AllowFrom, channels.WithMaxMessageLength(65536), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &MatrixChannel{ BaseChannel: base, + bc: bc, client: client, config: cfg, syncer: syncer, @@ -570,7 +573,7 @@ func (c *MatrixChannel) StartTyping(ctx context.Context, chatID string) (func(), // SendPlaceholder implements channels.PlaceholderCapable. func (c *MatrixChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) { - if !c.config.Placeholder.Enabled { + if !c.bc.Placeholder.Enabled { return "", nil } @@ -579,7 +582,7 @@ func (c *MatrixChannel) SendPlaceholder(ctx context.Context, chatID string) (str return "", fmt.Errorf("matrix room ID is empty") } - text := c.config.Placeholder.GetRandomText() + text := c.bc.Placeholder.GetRandomText() resp, err := c.client.SendMessageEvent(ctx, roomID, event.EventMessage, &event.MessageEventContent{ MsgType: event.MsgNotice, @@ -720,8 +723,8 @@ func (c *MatrixChannel) handleMessageEvent(ctx context.Context, evt *event.Event logger.DebugCF("matrix", "Ignoring group message by trigger rules", map[string]any{ "room_id": roomID, "is_mentioned": isMentioned, - "mention_only": c.config.GroupTrigger.MentionOnly, - "prefixes": c.config.GroupTrigger.Prefixes, + "mention_only": c.bc.GroupTrigger.MentionOnly, + "prefixes": c.bc.GroupTrigger.Prefixes, }) return } @@ -736,10 +739,8 @@ func (c *MatrixChannel) handleMessageEvent(ctx context.Context, evt *event.Event } peerKind := "direct" - peerID := senderID if isGroup { peerKind = "group" - peerID = roomID } metadata := map[string]string{ @@ -752,17 +753,19 @@ func (c *MatrixChannel) handleMessageEvent(ctx context.Context, evt *event.Event metadata["reply_to_msg_id"] = replyTo.String() } - c.HandleMessage( - c.baseContext(), - bus.Peer{Kind: peerKind, ID: peerID}, - evt.ID.String(), - senderID, - roomID, - content, - mediaPaths, - metadata, - sender, - ) + inboundCtx := bus.InboundContext{ + Channel: "matrix", + ChatID: roomID, + ChatType: peerKind, + SenderID: senderID, + MessageID: evt.ID.String(), + Raw: metadata, + } + if replyTo := msgEvt.GetRelatesTo().GetReplyTo(); replyTo != "" { + inboundCtx.ReplyToMessageID = replyTo.String() + } + + c.HandleInboundContext(c.baseContext(), roomID, content, mediaPaths, inboundCtx, sender) } // decryptEvent decrypts an encrypted event and returns the decrypted message event content. diff --git a/pkg/channels/matrix/matrix_test.go b/pkg/channels/matrix/matrix_test.go index ddcb8d3d9..07f08f32b 100644 --- a/pkg/channels/matrix/matrix_test.go +++ b/pkg/channels/matrix/matrix_test.go @@ -437,9 +437,9 @@ func TestMarkdownToHTML(t *testing.T) { } func TestMessageContent(t *testing.T) { - richtext := &MatrixChannel{config: config.MatrixConfig{MessageFormat: "richtext"}} - plain := &MatrixChannel{config: config.MatrixConfig{MessageFormat: "plain"}} - defaultt := &MatrixChannel{config: config.MatrixConfig{}} + richtext := &MatrixChannel{config: &config.MatrixSettings{MessageFormat: "richtext"}} + plain := &MatrixChannel{config: &config.MatrixSettings{MessageFormat: "plain"}} + defaultt := &MatrixChannel{config: &config.MatrixSettings{}} for _, c := range []*MatrixChannel{richtext, defaultt} { mc := c.messageContent("**hi**") diff --git a/pkg/channels/onebot/init.go b/pkg/channels/onebot/init.go index 84c06dfd6..f6791899c 100644 --- a/pkg/channels/onebot/init.go +++ b/pkg/channels/onebot/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("onebot", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewOneBotChannel(cfg.Channels.OneBot, b) - }) + channels.RegisterFactory( + config.ChannelOneBot, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.OneBotSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewOneBotChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/onebot/onebot.go b/pkg/channels/onebot/onebot.go index 0c59965c1..f0d0a890f 100644 --- a/pkg/channels/onebot/onebot.go +++ b/pkg/channels/onebot/onebot.go @@ -23,7 +23,7 @@ import ( type OneBotChannel struct { *channels.BaseChannel - config config.OneBotConfig + config *config.OneBotSettings conn *websocket.Conn ctx context.Context cancel context.CancelFunc @@ -96,10 +96,14 @@ type oneBotMessageSegment struct { Data map[string]any `json:"data"` } -func NewOneBotChannel(cfg config.OneBotConfig, messageBus *bus.MessageBus) (*OneBotChannel, error) { - base := channels.NewBaseChannel("onebot", cfg, messageBus, cfg.AllowFrom, - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), +func NewOneBotChannel( + bc *config.Channel, + cfg *config.OneBotSettings, + messageBus *bus.MessageBus, +) (*OneBotChannel, error) { + base := channels.NewBaseChannel("onebot", cfg, messageBus, bc.AllowFrom, + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) const dedupSize = 1024 @@ -991,8 +995,8 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) { senderID := strconv.FormatInt(userID, 10) var chatID string - - var peer bus.Peer + var contextChatID string + var contextChatType string metadata := map[string]string{} @@ -1003,12 +1007,14 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) { switch raw.MessageType { case "private": chatID = "private:" + senderID - peer = bus.Peer{Kind: "direct", ID: senderID} + contextChatID = senderID + contextChatType = "direct" case "group": groupIDStr := strconv.FormatInt(groupID, 10) chatID = "group:" + groupIDStr - peer = bus.Peer{Kind: "group", ID: groupIDStr} + contextChatID = groupIDStr + contextChatType = "group" metadata["group_id"] = groupIDStr senderUserID, _ := parseJSONInt64(sender.UserID) @@ -1072,7 +1078,18 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) { return } - c.HandleMessage(c.ctx, peer, messageID, senderID, chatID, content, parsed.Media, metadata, senderInfo) + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + ChatID: contextChatID, + ChatType: contextChatType, + SenderID: senderID, + MessageID: messageID, + Mentioned: isBotMentioned, + ReplyToMessageID: parsed.ReplyTo, + Raw: metadata, + } + + c.HandleInboundContext(c.ctx, chatID, content, parsed.Media, inboundCtx, senderInfo) } func (c *OneBotChannel) isDuplicate(messageID string) bool { diff --git a/pkg/channels/pico/client.go b/pkg/channels/pico/client.go index b4bfd09e5..009900e01 100644 --- a/pkg/channels/pico/client.go +++ b/pkg/channels/pico/client.go @@ -22,7 +22,7 @@ import ( // PicoClientChannel connects to a remote Pico Protocol WebSocket server. type PicoClientChannel struct { *channels.BaseChannel - config config.PicoClientConfig + config *config.PicoClientSettings conn *picoConn mu sync.Mutex ctx context.Context @@ -31,14 +31,15 @@ type PicoClientChannel struct { // NewPicoClientChannel creates a new Pico Protocol client channel. func NewPicoClientChannel( - cfg config.PicoClientConfig, + bc *config.Channel, + cfg *config.PicoClientSettings, messageBus *bus.MessageBus, ) (*PicoClientChannel, error) { if cfg.URL == "" { return nil, fmt.Errorf("pico_client url is required") } - base := channels.NewBaseChannel("pico_client", cfg, messageBus, cfg.AllowFrom) + base := channels.NewBaseChannel("pico_client", cfg, messageBus, bc.AllowFrom) return &PicoClientChannel{ BaseChannel: base, @@ -242,7 +243,11 @@ func (c *PicoClientChannel) handleInbound(pc *picoConn, msg PicoMessage) { } func (c *PicoClientChannel) handleServerMessage(pc *picoConn, msg PicoMessage) { - content, _ := msg.Payload["content"].(string) + if isThoughtPayload(msg.Payload) { + return + } + + content, _ := msg.Payload[PayloadKeyContent].(string) if strings.TrimSpace(content) == "" { return } @@ -254,8 +259,6 @@ func (c *PicoClientChannel) handleServerMessage(pc *picoConn, msg PicoMessage) { chatID := "pico_client:" + sessionID senderID := "pico-remote" - peer := bus.Peer{Kind: "direct", ID: chatID} - sender := bus.SenderInfo{ Platform: "pico_client", PlatformID: senderID, @@ -266,10 +269,19 @@ func (c *PicoClientChannel) handleServerMessage(pc *picoConn, msg PicoMessage) { return } - c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, nil, map[string]string{ - "platform": "pico_client", - "session_id": sessionID, - }, sender) + inboundCtx := bus.InboundContext{ + Channel: "pico_client", + ChatID: chatID, + ChatType: "direct", + SenderID: senderID, + MessageID: msg.ID, + Raw: map[string]string{ + "platform": "pico_client", + "session_id": sessionID, + }, + } + + c.HandleInboundContext(c.ctx, chatID, content, nil, inboundCtx, sender) } // Send sends a message to the remote server. @@ -285,7 +297,7 @@ func (c *PicoClientChannel) Send(ctx context.Context, msg bus.OutboundMessage) ( } outMsg := newMessage(TypeMessageSend, map[string]any{ - "content": msg.Content, + PayloadKeyContent: msg.Content, }) outMsg.SessionID = strings.TrimPrefix(msg.ChatID, "pico_client:") return nil, pc.writeJSON(outMsg) diff --git a/pkg/channels/pico/client_test.go b/pkg/channels/pico/client_test.go index b40606647..5ee028bae 100644 --- a/pkg/channels/pico/client_test.go +++ b/pkg/channels/pico/client_test.go @@ -18,7 +18,8 @@ import ( ) func TestNewPicoClientChannel_MissingURL(t *testing.T) { - _, err := NewPicoClientChannel(config.PicoClientConfig{}, bus.NewMessageBus()) + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + _, err := NewPicoClientChannel(bc, &config.PicoClientSettings{}, bus.NewMessageBus()) if err == nil { t.Fatal("expected error for missing URL") } @@ -28,7 +29,8 @@ func TestNewPicoClientChannel_MissingURL(t *testing.T) { } func TestNewPicoClientChannel_OK(t *testing.T) { - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: "ws://localhost:9999/ws", }, bus.NewMessageBus()) if err != nil { @@ -40,7 +42,8 @@ func TestNewPicoClientChannel_OK(t *testing.T) { } func TestSend_NotRunning(t *testing.T) { - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: "ws://localhost:9999/ws", }, bus.NewMessageBus()) if err != nil { @@ -104,7 +107,8 @@ func TestClientChannel_ConnectAndSend(t *testing.T) { defer srv.Close() mb := bus.NewMessageBus() - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: wsURL(srv.URL), Token: *config.NewSecureString("test-token"), SessionID: "sess-1", @@ -137,7 +141,8 @@ func TestClientChannel_AuthFailure(t *testing.T) { srv := testServer(t, "correct-token") defer srv.Close() - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: wsURL(srv.URL), Token: *config.NewSecureString("wrong-token"), }, bus.NewMessageBus()) @@ -161,7 +166,8 @@ func TestClientChannel_ReceivesServerMessage(t *testing.T) { mb := bus.NewMessageBus() - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: wsURL(srv.URL), SessionID: "sess-echo", ReadTimeout: 10, @@ -203,7 +209,8 @@ func TestClientChannel_StartTyping(t *testing.T) { srv := testServer(t, "") defer srv.Close() - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: wsURL(srv.URL), SessionID: "sess-type", ReadTimeout: 10, @@ -231,7 +238,8 @@ func TestSend_ClosedConnection(t *testing.T) { srv := testServer(t, "") defer srv.Close() - ch, err := NewPicoClientChannel(config.PicoClientConfig{ + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ URL: wsURL(srv.URL), SessionID: "sess-close", ReadTimeout: 10, @@ -279,7 +287,8 @@ func TestParseInlineImageMedia_Valid(t *testing.T) { func TestPicoChannel_HandleMessageSend_AllowsMediaOnly(t *testing.T) { mb := bus.NewMessageBus() - ch, err := NewPicoChannel(config.PicoConfig{ + bc := &config.Channel{Type: "pico", Enabled: true} + ch, err := NewPicoChannel(bc, &config.PicoSettings{ Token: *config.NewSecureString("test-token"), }, mb) if err != nil { @@ -316,3 +325,68 @@ func TestPicoChannel_HandleMessageSend_AllowsMediaOnly(t *testing.T) { t.Fatal("timed out waiting for inbound media message") } } + +func TestIsThoughtPayload(t *testing.T) { + tests := []struct { + name string + payload map[string]any + want bool + }{ + { + name: "explicit thought bool", + payload: map[string]any{PayloadKeyThought: true}, + want: true, + }, + { + name: "thought false", + payload: map[string]any{PayloadKeyThought: false}, + want: false, + }, + { + name: "thought string ignored", + payload: map[string]any{PayloadKeyThought: "true"}, + want: false, + }, + { + name: "default normal", + payload: map[string]any{PayloadKeyContent: "hello"}, + want: false, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := isThoughtPayload(tt.payload); got != tt.want { + t.Fatalf("isThoughtPayload() = %v, want %v", got, tt.want) + } + }) + } +} + +func TestPicoClientChannel_HandleServerMessage_IgnoresThought(t *testing.T) { + mb := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true} + ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{ + URL: "ws://localhost:8080/ws", + }, mb) + if err != nil { + t.Fatalf("NewPicoClientChannel() error = %v", err) + } + + ch.ctx = context.Background() + pc := &picoConn{sessionID: "sess-thought"} + + ch.handleServerMessage(pc, PicoMessage{ + Type: TypeMessageCreate, + Payload: map[string]any{ + PayloadKeyContent: "internal reasoning", + PayloadKeyThought: true, + }, + }) + + select { + case msg := <-mb.InboundChan(): + t.Fatalf("expected no inbound publish for thought payload, got %+v", msg) + case <-time.After(150 * time.Millisecond): + } +} diff --git a/pkg/channels/pico/init.go b/pkg/channels/pico/init.go index 0319279d8..54596fab3 100644 --- a/pkg/channels/pico/init.go +++ b/pkg/channels/pico/init.go @@ -7,10 +7,48 @@ import ( ) func init() { - channels.RegisterFactory("pico", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewPicoChannel(cfg.Channels.Pico, b) - }) - channels.RegisterFactory("pico_client", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewPicoClientChannel(cfg.Channels.PicoClient, b) - }) + channels.RegisterFactory( + config.ChannelPico, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.PicoSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewPicoChannel(bc, c, b) + if err != nil { + return nil, err + } + if channelName != config.ChannelPico { + ch.SetName(channelName) + } + return ch, nil + }, + ) + channels.RegisterFactory( + config.ChannelPicoClient, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.PicoClientSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewPicoClientChannel(bc, c, b) + if err != nil { + return nil, err + } + if channelName != config.ChannelPicoClient { + ch.SetName(channelName) + } + return ch, nil + }, + ) } diff --git a/pkg/channels/pico/pico.go b/pkg/channels/pico/pico.go index e22da1ba1..f998712c8 100644 --- a/pkg/channels/pico/pico.go +++ b/pkg/channels/pico/pico.go @@ -39,6 +39,13 @@ var allowedInlineImageMIMETypes = map[string]struct{}{ "image/bmp": {}, } +func outboundMessageIsThought(msg bus.OutboundMessage) bool { + if len(msg.Context.Raw) == 0 { + return false + } + return strings.EqualFold(strings.TrimSpace(msg.Context.Raw["message_kind"]), MessageKindThought) +} + // writeJSON sends a JSON message to the connection with write locking. func (pc *picoConn) writeJSON(v any) error { if pc.closed.Load() { @@ -63,7 +70,8 @@ func (pc *picoConn) close() { // It serves as the reference implementation for all optional capability interfaces. type PicoChannel struct { *channels.BaseChannel - config config.PicoConfig + bc *config.Channel + config *config.PicoSettings upgrader websocket.Upgrader connections map[string]*picoConn // connID -> *picoConn sessionConnections map[string]map[string]*picoConn // sessionID -> connID -> *picoConn @@ -73,12 +81,16 @@ type PicoChannel struct { } // NewPicoChannel creates a new Pico Protocol channel. -func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoChannel, error) { +func NewPicoChannel( + bc *config.Channel, + cfg *config.PicoSettings, + messageBus *bus.MessageBus, +) (*PicoChannel, error) { if cfg.Token.String() == "" { return nil, fmt.Errorf("pico token is required") } - base := channels.NewBaseChannel("pico", cfg, messageBus, cfg.AllowFrom) + base := channels.NewBaseChannel("pico", cfg, messageBus, bc.AllowFrom) allowOrigins := cfg.AllowOrigins checkOrigin := func(r *http.Request) bool { @@ -96,6 +108,7 @@ func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoCha return &PicoChannel{ BaseChannel: base, + bc: bc, config: cfg, upgrader: websocket.Upgrader{ CheckOrigin: checkOrigin, @@ -247,9 +260,11 @@ func (c *PicoChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]stri if !c.IsRunning() { return nil, channels.ErrNotRunning } + isThought := outboundMessageIsThought(msg) outMsg := newMessage(TypeMessageCreate, map[string]any{ - "content": msg.Content, + PayloadKeyContent: msg.Content, + PayloadKeyThought: isThought, }) return nil, c.broadcastToSession(msg.ChatID, outMsg) @@ -280,16 +295,17 @@ func (c *PicoChannel) StartTyping(ctx context.Context, chatID string) (func(), e // It sends a placeholder message via the Pico Protocol that will later be // edited to the actual response via EditMessage (channels.MessageEditor). func (c *PicoChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) { - if !c.config.Placeholder.Enabled { + if !c.bc.Placeholder.Enabled { return "", nil } - text := c.config.Placeholder.GetRandomText() + text := c.bc.Placeholder.GetRandomText() msgID := uuid.New().String() outMsg := newMessage(TypeMessageCreate, map[string]any{ - "content": text, - "message_id": msgID, + PayloadKeyContent: text, + PayloadKeyThought: false, + "message_id": msgID, }) if err := c.broadcastToSession(chatID, outMsg); err != nil { @@ -562,8 +578,6 @@ func (c *PicoChannel) handleMessageSend(pc *picoConn, msg PicoMessage) { chatID := "pico:" + sessionID senderID := "pico-user" - peer := bus.Peer{Kind: "direct", ID: "pico:" + sessionID} - metadata := map[string]string{ "platform": "pico", "session_id": sessionID, @@ -586,7 +600,16 @@ func (c *PicoChannel) handleMessageSend(pc *picoConn, msg PicoMessage) { return } - c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, media, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: "pico", + ChatID: chatID, + ChatType: "direct", + SenderID: senderID, + MessageID: msg.ID, + Raw: metadata, + } + + c.HandleInboundContext(c.ctx, chatID, content, media, inboundCtx, sender) } // truncate truncates a string to maxLen runes. diff --git a/pkg/channels/pico/pico_test.go b/pkg/channels/pico/pico_test.go index e712767ad..59db705eb 100644 --- a/pkg/channels/pico/pico_test.go +++ b/pkg/channels/pico/pico_test.go @@ -15,9 +15,10 @@ import ( func newTestPicoChannel(t *testing.T) *PicoChannel { t.Helper() - cfg := config.PicoConfig{} + bc := &config.Channel{Type: config.ChannelPico, Enabled: true} + cfg := &config.PicoSettings{} cfg.SetToken("test-token") - ch, err := NewPicoChannel(cfg, bus.NewMessageBus()) + ch, err := NewPicoChannel(bc, cfg, bus.NewMessageBus()) if err != nil { t.Fatalf("NewPicoChannel: %v", err) } diff --git a/pkg/channels/pico/protocol.go b/pkg/channels/pico/protocol.go index 3f8ba8643..051beed1b 100644 --- a/pkg/channels/pico/protocol.go +++ b/pkg/channels/pico/protocol.go @@ -18,7 +18,10 @@ const ( TypeError = "error" TypePong = "pong" - PicoTokenPrefix = "pico-" + PayloadKeyContent = "content" + PayloadKeyThought = "thought" + + MessageKindThought = "thought" ) // PicoMessage is the wire format for all Pico Protocol messages. @@ -39,6 +42,11 @@ func newMessage(msgType string, payload map[string]any) PicoMessage { } } +func isThoughtPayload(payload map[string]any) bool { + thought, _ := payload[PayloadKeyThought].(bool) + return thought +} + func newErrorWithPayload(code, message string, extra map[string]any) PicoMessage { payload := map[string]any{ "code": code, diff --git a/pkg/channels/qq/init.go b/pkg/channels/qq/init.go index 15b955089..55be732fd 100644 --- a/pkg/channels/qq/init.go +++ b/pkg/channels/qq/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("qq", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewQQChannel(cfg.Channels.QQ, b) - }) + channels.RegisterFactory( + config.ChannelQQ, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.QQSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewQQChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/qq/qq.go b/pkg/channels/qq/qq.go index f2b70aec9..71cba5548 100644 --- a/pkg/channels/qq/qq.go +++ b/pkg/channels/qq/qq.go @@ -56,7 +56,8 @@ type qqAPI interface { type QQChannel struct { *channels.BaseChannel - config config.QQConfig + bc *config.Channel + config *config.QQSettings api qqAPI tokenSource oauth2.TokenSource ctx context.Context @@ -82,15 +83,16 @@ type QQChannel struct { stopOnce sync.Once } -func NewQQChannel(cfg config.QQConfig, messageBus *bus.MessageBus) (*QQChannel, error) { - base := channels.NewBaseChannel("qq", cfg, messageBus, cfg.AllowFrom, +func NewQQChannel(bc *config.Channel, cfg *config.QQSettings, messageBus *bus.MessageBus) (*QQChannel, error) { + base := channels.NewBaseChannel("qq", cfg, messageBus, bc.AllowFrom, channels.WithMaxMessageLength(cfg.MaxMessageLength), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &QQChannel{ BaseChannel: base, + bc: bc, config: cfg, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -161,8 +163,8 @@ func (c *QQChannel) Start(ctx context.Context) error { // Pre-register reasoning_channel_id as group chat if configured, // so outbound-only destinations are routed correctly. - if c.config.ReasoningChannelID != "" { - c.chatType.Store(c.config.ReasoningChannelID, "group") + if c.bc.ReasoningChannelID != "" { + c.chatType.Store(c.bc.ReasoningChannelID, "group") } c.SetRunning(true) @@ -588,12 +590,22 @@ func qqFileType(partType string) uint64 { } func (c *QQChannel) maxBase64FileSizeBytes() int64 { + if c.config == nil { + return 0 + } if c.config.MaxBase64FileSizeMiB <= 0 { return 0 } return c.config.MaxBase64FileSizeMiB * bytesPerMiB } +func (c *QQChannel) accountID() string { + if c.config == nil { + return "" + } + return c.config.AppID +} + // handleC2CMessage handles QQ private messages. func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler { return func(event *dto.WSPayload, data *dto.WSC2CMessageData) error { @@ -647,17 +659,17 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler { metadata := map[string]string{ "account_id": senderID, } + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + Account: c.accountID(), + ChatID: senderID, + ChatType: "direct", + SenderID: senderID, + MessageID: data.ID, + Raw: metadata, + } - c.HandleMessage(c.ctx, - bus.Peer{Kind: "direct", ID: senderID}, - data.ID, - senderID, - senderID, - content, - mediaPaths, - metadata, - sender, - ) + c.HandleInboundContext(c.ctx, senderID, content, mediaPaths, inboundCtx, sender) return nil } @@ -725,17 +737,18 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler { "account_id": senderID, "group_id": data.GroupID, } + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + Account: c.accountID(), + ChatID: data.GroupID, + ChatType: "group", + SenderID: senderID, + MessageID: data.ID, + Mentioned: true, + Raw: metadata, + } - c.HandleMessage(c.ctx, - bus.Peer{Kind: "group", ID: data.GroupID}, - data.ID, - senderID, - data.GroupID, - content, - mediaPaths, - metadata, - sender, - ) + c.HandleInboundContext(c.ctx, data.GroupID, content, mediaPaths, inboundCtx, sender) return nil } diff --git a/pkg/channels/qq/qq_test.go b/pkg/channels/qq/qq_test.go index 83a912cd7..2ab03ab54 100644 --- a/pkg/channels/qq/qq_test.go +++ b/pkg/channels/qq/qq_test.go @@ -54,8 +54,8 @@ func TestHandleC2CMessage_IncludesAccountIDMetadata(t *testing.T) { if !ok { t.Fatal("expected inbound message") } - if inbound.Metadata["account_id"] != "7750283E123456" { - t.Fatalf("account_id metadata = %q, want %q", inbound.Metadata["account_id"], "7750283E123456") + if inbound.Context.Raw["account_id"] != "7750283E123456" { + t.Fatalf("account_id raw = %q, want %q", inbound.Context.Raw["account_id"], "7750283E123456") } return } @@ -165,8 +165,8 @@ func TestHandleGroupATMessage_AttachmentOnlyPublishesMedia(t *testing.T) { if !strings.HasPrefix(inbound.Media[0], "media://") { t.Fatalf("inbound.Media[0] = %q, want media:// ref", inbound.Media[0]) } - if inbound.Peer.Kind != "group" || inbound.Peer.ID != "group-1" { - t.Fatalf("inbound.Peer = %+v, want group/group-1", inbound.Peer) + if inbound.Context.ChatType != "group" { + t.Fatalf("inbound.Context.ChatType = %q, want group", inbound.Context.ChatType) } } @@ -198,6 +198,7 @@ func TestSendMedia_UploadsLocalFileAsBase64(t *testing.T) { } ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: api, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -294,6 +295,7 @@ func assertAudioWAVUploadType(t *testing.T, duration time.Duration, wantFileType } ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: api, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -329,6 +331,7 @@ func TestSendMedia_RemoteAudioFallsBackToFileUpload(t *testing.T) { } ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: api, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -374,6 +377,7 @@ func TestSendMedia_LocalAudioWithUnknownDurationFallsBackToFileUpload(t *testing } ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: api, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -409,6 +413,7 @@ func TestSendMedia_UsesRemoteURLUploadForC2C(t *testing.T) { } ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: api, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -481,6 +486,7 @@ func TestSendMedia_LocalFileUploadIncludesStoredFilename(t *testing.T) { } ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: api, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -520,6 +526,7 @@ func TestSendMedia_ReturnsSendFailedWithoutMediaStore(t *testing.T) { messageBus := bus.NewMessageBus() ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), + config: &config.QQSettings{}, api: &fakeQQAPI{}, dedup: make(map[string]time.Time), done: make(chan struct{}), @@ -566,7 +573,7 @@ func TestSendMedia_ReturnsSendFailedWhenLocalFileExceedsBase64MiBLimit(t *testin api := &fakeQQAPI{} ch := &QQChannel{ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil), - config: config.QQConfig{ + config: &config.QQSettings{ MaxBase64FileSizeMiB: 1, }, api: api, diff --git a/pkg/channels/registry.go b/pkg/channels/registry.go index 36a05bf3e..2388d6c54 100644 --- a/pkg/channels/registry.go +++ b/pkg/channels/registry.go @@ -1,6 +1,7 @@ package channels import ( + "fmt" "sync" "github.com/sipeed/picoclaw/pkg/bus" @@ -9,7 +10,9 @@ import ( // ChannelFactory is a constructor function that creates a Channel from config and message bus. // Each channel subpackage registers one or more factories via init(). -type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error) +// channelName is the config map key for this channel instance (may differ from the channel type). +// channelType is the channel type string used to look up the Channel config. +type ChannelFactory func(channelName, channelType string, cfg *config.Config, bus *bus.MessageBus) (Channel, error) var ( factoriesMu sync.RWMutex @@ -23,6 +26,38 @@ func RegisterFactory(name string, f ChannelFactory) { factories[name] = f } +// RegisterSafeFactory is a convenience wrapper that handles GetDecoded() error checking +// and type assertion, reducing boilerplate in channel init() functions. +// +// Usage: +// +// func init() { +// channels.RegisterSafeFactory(config.ChannelTelegram, +// func(bc *config.Channel, c *config.TelegramSettings, b *bus.MessageBus) (channels.Channel, error) { +// return NewTelegramChannel(bc, c, b) +// }) +// } +func RegisterSafeFactory[S any]( + channelType string, + ctor func(bc *config.Channel, settings *S, bus *bus.MessageBus) (Channel, error), +) { + RegisterFactory(channelType, func(channelName, _ string, cfg *config.Config, b *bus.MessageBus) (Channel, error) { + bc := cfg.Channels[channelName] + if bc == nil { + return nil, fmt.Errorf("channel %q: config not found", channelName) + } + decoded, err := bc.GetDecoded() + if err != nil { + return nil, fmt.Errorf("channel %q: failed to decode settings: %w", channelName, err) + } + settings, ok := decoded.(*S) + if !ok { + return nil, fmt.Errorf("channel %q: expected %T settings, got %T", channelName, (*S)(nil), decoded) + } + return ctor(bc, settings, b) + }) +} + // getFactory looks up a channel factory by name. func getFactory(name string) (ChannelFactory, bool) { factoriesMu.RLock() @@ -30,3 +65,14 @@ func getFactory(name string) (ChannelFactory, bool) { f, ok := factories[name] return f, ok } + +// GetRegisteredFactoryNames returns a slice of all registered channel factory names. +func GetRegisteredFactoryNames() []string { + factoriesMu.RLock() + defer factoriesMu.RUnlock() + names := make([]string, 0, len(factories)) + for name := range factories { + names = append(names, name) + } + return names +} diff --git a/pkg/channels/slack/init.go b/pkg/channels/slack/init.go index c131bb291..f1dbf6dd2 100644 --- a/pkg/channels/slack/init.go +++ b/pkg/channels/slack/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("slack", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewSlackChannel(cfg.Channels.Slack, b) - }) + channels.RegisterFactory( + config.ChannelSlack, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.SlackSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewSlackChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/slack/slack.go b/pkg/channels/slack/slack.go index 1e4a4fef5..19e7b737c 100644 --- a/pkg/channels/slack/slack.go +++ b/pkg/channels/slack/slack.go @@ -21,7 +21,7 @@ import ( type SlackChannel struct { *channels.BaseChannel - config config.SlackConfig + config *config.SlackSettings api *slack.Client socketClient *socketmode.Client botUserID string @@ -36,7 +36,11 @@ type slackMessageRef struct { Timestamp string } -func NewSlackChannel(cfg config.SlackConfig, messageBus *bus.MessageBus) (*SlackChannel, error) { +func NewSlackChannel( + bc *config.Channel, + cfg *config.SlackSettings, + messageBus *bus.MessageBus, +) (*SlackChannel, error) { if cfg.BotToken.String() == "" || cfg.AppToken.String() == "" { return nil, fmt.Errorf("slack bot_token and app_token are required") } @@ -48,10 +52,10 @@ func NewSlackChannel(cfg config.SlackConfig, messageBus *bus.MessageBus) (*Slack socketClient := socketmode.New(api) - base := channels.NewBaseChannel("slack", cfg, messageBus, cfg.AllowFrom, + base := channels.NewBaseChannel("slack", cfg, messageBus, bc.AllowFrom, channels.WithMaxMessageLength(40000), - channels.WithGroupTrigger(cfg.GroupTrigger), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &SlackChannel{ @@ -113,7 +117,7 @@ func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]str return nil, channels.ErrNotRunning } - channelID, threadTS := parseSlackChatID(msg.ChatID) + deliveryChatID, channelID, threadTS := resolveSlackOutboundTarget(msg.ChatID, &msg.Context) if channelID == "" { return nil, fmt.Errorf("invalid slack chat ID: %s", msg.ChatID) } @@ -135,7 +139,7 @@ func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]str return nil, fmt.Errorf("slack send: %w", channels.ErrTemporary) } - if ref, ok := c.pendingAcks.LoadAndDelete(msg.ChatID); ok { + if ref, ok := c.pendingAcks.LoadAndDelete(deliveryChatID); ok { msgRef := ref.(slackMessageRef) c.api.AddReaction("white_check_mark", slack.ItemRef{ Channel: msgRef.ChannelID, @@ -157,7 +161,7 @@ func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessa return nil, channels.ErrNotRunning } - channelID, _ := parseSlackChatID(msg.ChatID) + _, channelID, threadTS := resolveSlackMediaOutboundTarget(msg.ChatID, &msg.Context) if channelID == "" { return nil, fmt.Errorf("invalid slack chat ID: %s", msg.ChatID) } @@ -188,10 +192,11 @@ func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessa } _, err = c.api.UploadFileV2Context(ctx, slack.UploadFileV2Parameters{ - Channel: channelID, - File: localPath, - Filename: filename, - Title: title, + Channel: channelID, + ThreadTimestamp: threadTS, + File: localPath, + Filename: filename, + Title: title, }) if err != nil { logger.ErrorCF("slack", "Failed to upload media", map[string]any{ @@ -356,14 +361,10 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) { } peerKind := "channel" - peerID := channelID if strings.HasPrefix(channelID, "D") { peerKind = "direct" - peerID = senderID } - peer := bus.Peer{Kind: peerKind, ID: peerID} - metadata := map[string]string{ "message_ts": messageTS, "channel_id": channelID, @@ -379,7 +380,22 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) { "has_thread": threadTS != "", }) - c.HandleMessage(c.ctx, peer, messageTS, senderID, chatID, content, mediaPaths, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + Account: c.teamID, + ChatID: channelID, + ChatType: peerKind, + SenderID: senderID, + MessageID: messageTS, + SpaceID: c.teamID, + SpaceType: "workspace", + Raw: metadata, + } + if threadTS != "" { + inboundCtx.TopicID = threadTS + } + + c.HandleInboundContext(c.ctx, chatID, content, mediaPaths, inboundCtx, sender) } func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) { @@ -427,14 +443,10 @@ func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) { } mentionPeerKind := "channel" - mentionPeerID := channelID if strings.HasPrefix(channelID, "D") { mentionPeerKind = "direct" - mentionPeerID = senderID } - mentionPeer := bus.Peer{Kind: mentionPeerKind, ID: mentionPeerID} - metadata := map[string]string{ "message_ts": messageTS, "channel_id": channelID, @@ -443,8 +455,21 @@ func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) { "is_mention": "true", "team_id": c.teamID, } + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + Account: c.teamID, + ChatID: channelID, + ChatType: mentionPeerKind, + TopicID: threadTS, + SenderID: senderID, + MessageID: messageTS, + SpaceID: c.teamID, + SpaceType: "workspace", + Mentioned: true, + Raw: metadata, + } - c.HandleMessage(c.ctx, mentionPeer, messageTS, senderID, chatID, content, nil, metadata, mentionSender) + c.HandleInboundContext(c.ctx, chatID, content, nil, inboundCtx, mentionSender) } func (c *SlackChannel) handleSlashCommand(event socketmode.Event) { @@ -491,18 +516,22 @@ func (c *SlackChannel) handleSlashCommand(event socketmode.Event) { "command": cmd.Command, "text": utils.Truncate(content, 50), }) + peerKind := "channel" + if strings.HasPrefix(channelID, "D") { + peerKind = "direct" + } + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + Account: c.teamID, + ChatID: channelID, + ChatType: peerKind, + SenderID: senderID, + SpaceID: c.teamID, + SpaceType: "workspace", + Raw: metadata, + } - c.HandleMessage( - c.ctx, - bus.Peer{Kind: "channel", ID: channelID}, - "", - senderID, - chatID, - content, - nil, - metadata, - cmdSender, - ) + c.HandleInboundContext(c.ctx, chatID, content, nil, inboundCtx, cmdSender) } func (c *SlackChannel) downloadSlackFile(file slack.File) string { @@ -537,3 +566,33 @@ func parseSlackChatID(chatID string) (channelID, threadTS string) { } return channelID, threadTS } + +func resolveSlackOutboundTarget(chatID string, outboundCtx *bus.InboundContext) (string, string, string) { + deliveryChatID := strings.TrimSpace(chatID) + if deliveryChatID == "" && outboundCtx != nil { + deliveryChatID = strings.TrimSpace(outboundCtx.ChatID) + } + channelID, threadTS := parseSlackChatID(deliveryChatID) + if threadTS == "" && outboundCtx != nil { + threadTS = strings.TrimSpace(outboundCtx.TopicID) + if threadTS != "" && channelID != "" { + deliveryChatID = channelID + "/" + threadTS + } + } + return deliveryChatID, channelID, threadTS +} + +func resolveSlackMediaOutboundTarget(chatID string, outboundCtx *bus.InboundContext) (string, string, string) { + deliveryChatID := strings.TrimSpace(chatID) + if deliveryChatID == "" && outboundCtx != nil { + deliveryChatID = strings.TrimSpace(outboundCtx.ChatID) + } + channelID, threadTS := parseSlackChatID(deliveryChatID) + if threadTS == "" && outboundCtx != nil { + threadTS = strings.TrimSpace(outboundCtx.TopicID) + if threadTS != "" && channelID != "" { + deliveryChatID = channelID + "/" + threadTS + } + } + return deliveryChatID, channelID, threadTS +} diff --git a/pkg/channels/slack/slack_test.go b/pkg/channels/slack/slack_test.go index d1980a7c9..a72521d67 100644 --- a/pkg/channels/slack/slack_test.go +++ b/pkg/channels/slack/slack_test.go @@ -53,6 +53,24 @@ func TestParseSlackChatID(t *testing.T) { } } +func TestResolveSlackOutboundTarget_PrefersContextTopicID(t *testing.T) { + deliveryChatID, channelID, threadTS := resolveSlackOutboundTarget("C123456", &bus.InboundContext{ + Channel: "slack", + ChatID: "C123456", + TopicID: "1234567890.123456", + }) + + if deliveryChatID != "C123456/1234567890.123456" { + t.Fatalf("deliveryChatID = %q, want %q", deliveryChatID, "C123456/1234567890.123456") + } + if channelID != "C123456" { + t.Fatalf("channelID = %q, want %q", channelID, "C123456") + } + if threadTS != "1234567890.123456" { + t.Fatalf("threadTS = %q, want %q", threadTS, "1234567890.123456") + } +} + func TestStripBotMention(t *testing.T) { ch := &SlackChannel{botUserID: "U12345BOT"} @@ -100,32 +118,32 @@ func TestStripBotMention(t *testing.T) { func TestNewSlackChannel(t *testing.T) { msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: "slack", Enabled: true} t.Run("missing bot token", func(t *testing.T) { - cfg := config.SlackConfig{} + cfg := &config.SlackSettings{} cfg.AppToken = *config.NewSecureString("xapp-test") - _, err := NewSlackChannel(cfg, msgBus) + _, err := NewSlackChannel(bc, cfg, msgBus) if err == nil { t.Error("expected error for missing bot_token, got nil") } }) t.Run("missing app token", func(t *testing.T) { - cfg := config.SlackConfig{} + cfg := &config.SlackSettings{} cfg.BotToken = *config.NewSecureString("xoxb-test") - _, err := NewSlackChannel(cfg, msgBus) + _, err := NewSlackChannel(bc, cfg, msgBus) if err == nil { t.Error("expected error for missing app_token, got nil") } }) t.Run("valid config", func(t *testing.T) { - cfg := config.SlackConfig{ - AllowFrom: []string{"U123"}, - } + cfg := &config.SlackSettings{} cfg.BotToken = *config.NewSecureString("xoxb-test") cfg.AppToken = *config.NewSecureString("xapp-test") - ch, err := NewSlackChannel(cfg, msgBus) + bc := &config.Channel{Type: "slack", Enabled: true, AllowFrom: []string{"U123"}} + ch, err := NewSlackChannel(bc, cfg, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -142,24 +160,22 @@ func TestSlackChannelIsAllowed(t *testing.T) { msgBus := bus.NewMessageBus() t.Run("empty allowlist allows all", func(t *testing.T) { - cfg := config.SlackConfig{ - AllowFrom: []string{}, - } + bc := &config.Channel{Type: config.ChannelSlack, Enabled: true, AllowFrom: []string{}} + cfg := &config.SlackSettings{} cfg.BotToken = *config.NewSecureString("xoxb-test") cfg.AppToken = *config.NewSecureString("xapp-test") - ch, _ := NewSlackChannel(cfg, msgBus) + ch, _ := NewSlackChannel(bc, cfg, msgBus) if !ch.IsAllowed("U_ANYONE") { t.Error("empty allowlist should allow all users") } }) t.Run("allowlist restricts users", func(t *testing.T) { - cfg := config.SlackConfig{ - AllowFrom: []string{"U_ALLOWED"}, - } + bc := &config.Channel{Type: config.ChannelSlack, Enabled: true, AllowFrom: []string{"U_ALLOWED"}} + cfg := &config.SlackSettings{} cfg.BotToken = *config.NewSecureString("xoxb-test") cfg.AppToken = *config.NewSecureString("xapp-test") - ch, _ := NewSlackChannel(cfg, msgBus) + ch, _ := NewSlackChannel(bc, cfg, msgBus) if !ch.IsAllowed("U_ALLOWED") { t.Error("allowed user should pass allowlist check") } diff --git a/pkg/channels/teams_webhook/init.go b/pkg/channels/teams_webhook/init.go new file mode 100644 index 000000000..6f05b661f --- /dev/null +++ b/pkg/channels/teams_webhook/init.go @@ -0,0 +1,32 @@ +package teamswebhook + +import ( + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/channels" + "github.com/sipeed/picoclaw/pkg/config" +) + +func init() { + channels.RegisterFactory( + config.ChannelTeamsWebHook, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.TeamsWebhookSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewTeamsWebhookChannel(bc, c, b) + if err != nil { + return nil, err + } + if channelName != config.ChannelTeamsWebHook { + ch.SetName(channelName) + } + return ch, nil + }, + ) +} diff --git a/pkg/channels/teams_webhook/teams_webhook.go b/pkg/channels/teams_webhook/teams_webhook.go new file mode 100644 index 000000000..837563453 --- /dev/null +++ b/pkg/channels/teams_webhook/teams_webhook.go @@ -0,0 +1,425 @@ +package teamswebhook + +import ( + "context" + "fmt" + "net/url" + "regexp" + "sort" + "strconv" + "strings" + + goteamsnotify "github.com/atc0005/go-teams-notify/v2" + "github.com/atc0005/go-teams-notify/v2/adaptivecard" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/channels" + "github.com/sipeed/picoclaw/pkg/config" + "github.com/sipeed/picoclaw/pkg/logger" +) + +// statusCodeRe extracts HTTP status codes from error messages like "401 Unauthorized". +var statusCodeRe = regexp.MustCompile(`\b([45]\d{2})\b`) + +// markdownTableRe matches a markdown table block (header + separator + rows). +// It captures the entire table including all rows. +var markdownTableRe = regexp.MustCompile(`(?m)^(\|[^\n]+\|)\n(\|[-:\|\s]+\|)\n((?:\|[^\n]+\|\n?)+)`) + +// teamsMessageSender abstracts the Teams client for testability. +type teamsMessageSender interface { + SendWithContext(ctx context.Context, webhookURL string, message goteamsnotify.TeamsMessage) error +} + +// classifyTeamsError extracts HTTP status code from error message and classifies it. +// The go-teams-notify library returns errors like "error on notification: 401 Unauthorized, ...". +// This allows proper retry behavior: 4xx errors are permanent, 5xx are temporary. +func classifyTeamsError(err error) error { + if err == nil { + return nil + } + errMsg := err.Error() + if matches := statusCodeRe.FindStringSubmatch(errMsg); len(matches) > 1 { + if statusCode, parseErr := strconv.Atoi(matches[1]); parseErr == nil { + return channels.ClassifySendError(statusCode, err) + } + } + // Fallback: treat as temporary network error (retryable) + return channels.ClassifyNetError(err) +} + +// TeamsWebhookChannel is an output-only channel that sends messages +// to Microsoft Teams via Power Automate workflow webhooks. +// Multiple webhook targets can be configured and selected via ChatID. +type TeamsWebhookChannel struct { + *channels.BaseChannel + bc *config.Channel + config *config.TeamsWebhookSettings + client teamsMessageSender +} + +// NewTeamsWebhookChannel creates a new Teams webhook channel. +func NewTeamsWebhookChannel( + bc *config.Channel, + cfg *config.TeamsWebhookSettings, + bus *bus.MessageBus, +) (*TeamsWebhookChannel, error) { + if len(cfg.Webhooks) == 0 { + return nil, fmt.Errorf("teams_webhook: at least one webhook target is required") + } + + // Require "default" webhook target + if _, hasDefault := cfg.Webhooks["default"]; !hasDefault { + return nil, fmt.Errorf("teams_webhook: a 'default' webhook target is required") + } + + // Validate all webhook targets have valid HTTPS URLs + for name, target := range cfg.Webhooks { + webhookURL := target.WebhookURL.String() + if webhookURL == "" { + return nil, fmt.Errorf("teams_webhook: webhook %q has empty webhook_url", name) + } + parsed, err := url.Parse(webhookURL) + if err != nil { + return nil, fmt.Errorf("teams_webhook: webhook %q has invalid URL: %w", name, err) + } + if !strings.EqualFold(parsed.Scheme, "https") { + return nil, fmt.Errorf("teams_webhook: webhook %q must use HTTPS (got %q)", name, parsed.Scheme) + } + } + + base := channels.NewBaseChannel( + "teams_webhook", + cfg, + bus, + []string{ + "*", + }, // Output-only channel; "*" suppresses misleading "allows EVERYONE" audit warning + channels.WithMaxMessageLength(24000), // Power Automate webhook payload limit is 28KB + ) + + client := goteamsnotify.NewTeamsClient() + + return &TeamsWebhookChannel{ + BaseChannel: base, + bc: bc, + config: cfg, + client: client, + }, nil +} + +// Start initializes the channel. For output-only channels, this is a no-op. +func (c *TeamsWebhookChannel) Start(ctx context.Context) error { + targets := make([]string, 0, len(c.config.Webhooks)) + for name := range c.config.Webhooks { + targets = append(targets, name) + } + sort.Strings(targets) + logger.InfoCF("teams_webhook", "Starting Teams webhook channel (output-only)", map[string]any{ + "targets": targets, + }) + c.SetRunning(true) + return nil +} + +// Stop shuts down the channel. +func (c *TeamsWebhookChannel) Stop(ctx context.Context) error { + logger.InfoC("teams_webhook", "Stopping Teams webhook channel") + c.SetRunning(false) + return nil +} + +// Send delivers a message to the specified Teams webhook target. +// The target is selected by msg.ChatID which must match a key in the webhooks map. +func (c *TeamsWebhookChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]string, error) { + if !c.IsRunning() { + return nil, channels.ErrNotRunning + } + + select { + case <-ctx.Done(): + return nil, ctx.Err() + default: + } + + // Look up webhook target by ChatID, fall back to "default" if empty or unknown + targetName := msg.ChatID + if targetName == "" { + targetName = "default" + } + + target, ok := c.config.Webhooks[targetName] + if !ok { + // Log warning and fall back to default target + logger.WarnCF("teams_webhook", "Unknown target, falling back to default", map[string]any{ + "requested": msg.ChatID, + "using": "default", + }) + target = c.config.Webhooks["default"] + } + + // Build an Adaptive Card for rich formatting + card, err := c.buildAdaptiveCard(msg, target) + if err != nil { + return nil, fmt.Errorf("teams_webhook: failed to build card: %w", err) + } + + // Create the message with the card + teamsMsg, err := adaptivecard.NewMessageFromCard(card) + if err != nil { + return nil, fmt.Errorf("teams_webhook: failed to create message: %w", err) + } + + // Send to Teams + if err := c.client.SendWithContext(ctx, target.WebhookURL.String(), teamsMsg); err != nil { + // Log without raw error to avoid leaking webhook URL (embedded in net/http errors) + logger.ErrorCF("teams_webhook", "Failed to send message to Teams webhook", map[string]any{ + "target": msg.ChatID, + }) + // Classify error based on status code extracted from error message. + // The go-teams-notify library includes status in errors like "401 Unauthorized". + // Use ClassifySendError for proper retry behavior (4xx = permanent, 5xx = temporary). + classifiedErr := classifyTeamsError(err) + return nil, fmt.Errorf("teams_webhook: send failed: %w", classifiedErr) + } + + logger.DebugCF("teams_webhook", "Message sent successfully", map[string]any{ + "target": msg.ChatID, + }) + + return nil, nil +} + +// buildAdaptiveCard creates a formatted Adaptive Card from the outbound message. +// It detects markdown tables and converts them to native Adaptive Card Table elements, +// since TextBlocks only support a limited markdown subset (no tables). +func (c *TeamsWebhookChannel) buildAdaptiveCard( + msg bus.OutboundMessage, + target config.TeamsWebhookTarget, +) (adaptivecard.Card, error) { + card := adaptivecard.NewCard() + card.Type = adaptivecard.TypeAdaptiveCard + + // Set full width for Teams rendering + card.MSTeams.Width = "Full" + + // Add title if configured on the target + title := target.Title + if title == "" { + title = "PicoClaw Notification" + } + + titleBlock := adaptivecard.NewTextBlock(title, true) + titleBlock.Size = adaptivecard.SizeLarge + titleBlock.Weight = adaptivecard.WeightBolder + titleBlock.Style = adaptivecard.TextBlockStyleHeading + + if err := card.AddElement(false, titleBlock); err != nil { + return card, err + } + + content := msg.Content + if content == "" { + content = "(empty message)" + } + + // Split content into text segments and tables + // TextBlocks support: bold, italic, bullet/numbered lists, links + // TextBlocks do NOT support: headers, tables, images + segments := splitContentWithTables(content) + + for _, seg := range segments { + if seg.isTable { + // Convert markdown table to Adaptive Card Table element + tableElement, err := parseMarkdownTable(seg.content) + if err != nil { + // Fallback: render as preformatted text if parsing fails + logger.WarnCF("teams_webhook", "Failed to parse markdown table, using fallback", map[string]any{ + "error": err.Error(), + }) + block := adaptivecard.NewTextBlock("```\n"+seg.content+"\n```", true) + block.Wrap = true + if err := card.AddElement(false, block); err != nil { + return card, err + } + continue + } + if err := card.AddElement(false, tableElement); err != nil { + return card, err + } + } else { + // Regular text content + text := strings.TrimSpace(seg.content) + if text == "" { + continue + } + block := adaptivecard.NewTextBlock(text, true) + block.Wrap = true + if err := card.AddElement(false, block); err != nil { + return card, err + } + } + } + + return card, nil +} + +// contentSegment represents either a text block or a table in the message content. +type contentSegment struct { + content string + isTable bool +} + +// splitContentWithTables splits content into alternating text and table segments. +func splitContentWithTables(content string) []contentSegment { + var segments []contentSegment + + matches := markdownTableRe.FindAllStringSubmatchIndex(content, -1) + if len(matches) == 0 { + // No tables found, return entire content as text + return []contentSegment{{content: content, isTable: false}} + } + + lastEnd := 0 + for _, match := range matches { + // Text before this table + if match[0] > lastEnd { + segments = append(segments, contentSegment{ + content: content[lastEnd:match[0]], + isTable: false, + }) + } + // The table itself + segments = append(segments, contentSegment{ + content: content[match[0]:match[1]], + isTable: true, + }) + lastEnd = match[1] + } + + // Text after the last table + if lastEnd < len(content) { + segments = append(segments, contentSegment{ + content: content[lastEnd:], + isTable: false, + }) + } + + return segments +} + +// parseMarkdownTable converts a markdown table string to an Adaptive Card Table element. +func parseMarkdownTable(tableStr string) (adaptivecard.Element, error) { + lines := strings.Split(strings.TrimSpace(tableStr), "\n") + if len(lines) < 2 { + return adaptivecard.Element{}, fmt.Errorf("table must have at least header and separator rows") + } + + // Track header content length per column for width calculation + var headerLengths []int + + // Parse all rows (header + data rows, skip separator) + var allRows [][]adaptivecard.TableCell + for i, line := range lines { + // Skip separator row (contains only |, -, :, and spaces) + if i == 1 && isSeparatorRow(line) { + continue + } + + cells := parseTableRow(line) + if len(cells) == 0 { + continue + } + + var tableCells []adaptivecard.TableCell + for _, cellText := range cells { + trimmedText := strings.TrimSpace(cellText) + + // Use header row (first row) to determine column widths + if i == 0 { + headerLengths = append(headerLengths, len(trimmedText)) + } + + textBlock := adaptivecard.Element{ + Type: adaptivecard.TypeElementTextBlock, + Text: trimmedText, + Wrap: true, + } + cell := adaptivecard.TableCell{ + Type: adaptivecard.TypeTableCell, + Items: []*adaptivecard.Element{&textBlock}, + } + tableCells = append(tableCells, cell) + } + allRows = append(allRows, tableCells) + } + + if len(allRows) == 0 { + return adaptivecard.Element{}, fmt.Errorf("no valid rows found in table") + } + + // Create table with first row as headers + firstRowAsHeaders := true + showGridLines := true + + table, err := adaptivecard.NewTableFromTableCells(allRows, 0, firstRowAsHeaders, showGridLines) + if err != nil { + return adaptivecard.Element{}, fmt.Errorf("failed to create table: %w", err) + } + + // Set column widths based on header content length + table.Columns = calculateColumnWidths(headerLengths) + + return table, nil +} + +// calculateColumnWidths creates TableColumnDefinition entries with widths +// proportional to the max content length of each column. +func calculateColumnWidths(maxLengths []int) []adaptivecard.Column { + if len(maxLengths) == 0 { + return nil + } + + // Use content length as relative weight, with a minimum of 1 + columns := make([]adaptivecard.Column, len(maxLengths)) + for i, length := range maxLengths { + weight := length + if weight < 1 { + weight = 1 + } + columns[i] = adaptivecard.Column{ + Type: "TableColumnDefinition", + Width: weight, + } + } + + return columns +} + +// isSeparatorRow checks if a line is a markdown table separator (e.g., |---|---|). +func isSeparatorRow(line string) bool { + // Remove pipes and spaces, check if only dashes and colons remain + cleaned := strings.ReplaceAll(line, "|", "") + cleaned = strings.ReplaceAll(cleaned, " ", "") + cleaned = strings.ReplaceAll(cleaned, "-", "") + cleaned = strings.ReplaceAll(cleaned, ":", "") + return cleaned == "" +} + +// parseTableRow extracts cell values from a markdown table row. +func parseTableRow(line string) []string { + // Trim leading/trailing pipes and split by | + line = strings.TrimSpace(line) + line = strings.TrimPrefix(line, "|") + line = strings.TrimSuffix(line, "|") + + if line == "" { + return nil + } + + parts := strings.Split(line, "|") + var cells []string + for _, p := range parts { + cells = append(cells, strings.TrimSpace(p)) + } + return cells +} diff --git a/pkg/channels/teams_webhook/teams_webhook_test.go b/pkg/channels/teams_webhook/teams_webhook_test.go new file mode 100644 index 000000000..cc1570038 --- /dev/null +++ b/pkg/channels/teams_webhook/teams_webhook_test.go @@ -0,0 +1,582 @@ +package teamswebhook + +import ( + "context" + "errors" + "testing" + + goteamsnotify "github.com/atc0005/go-teams-notify/v2" + + "github.com/sipeed/picoclaw/pkg/bus" + "github.com/sipeed/picoclaw/pkg/config" +) + +// mockTeamsClient implements teamsMessageSender for testing. +type mockTeamsClient struct { + sendFunc func(ctx context.Context, webhookURL string, message goteamsnotify.TeamsMessage) error +} + +func (m *mockTeamsClient) SendWithContext( + ctx context.Context, + webhookURL string, + message goteamsnotify.TeamsMessage, +) error { + if m.sendFunc != nil { + return m.sendFunc(ctx, webhookURL, message) + } + return nil +} + +func TestNewTeamsWebhookChannel(t *testing.T) { + msgBus := bus.NewMessageBus() + + // Test missing webhooks + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: nil, + } + _, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err == nil { + t.Error("expected error for missing webhooks") + } + + // Test missing "default" webhook + cfg.Webhooks = map[string]config.TeamsWebhookTarget{ + "alerts": { + WebhookURL: *config.NewSecureString("https://example.com/webhook"), + Title: "Alerts", + }, + } + _, err = NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err == nil { + t.Error("expected error for missing 'default' webhook") + } + + // Test empty webhook URL + cfg.Webhooks = map[string]config.TeamsWebhookTarget{ + "default": {Title: "Default"}, + } + _, err = NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err == nil { + t.Error("expected error for empty webhook_url") + } + + // Test HTTP URL (should fail, must be HTTPS) + cfg.Webhooks = map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("http://example.com/webhook"), + Title: "Default", + }, + } + _, err = NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err == nil { + t.Error("expected error for HTTP webhook URL (must be HTTPS)") + } + + // Test valid config with HTTPS (must include "default") + cfg.Webhooks = map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-default"), + Title: "Default", + }, + "alerts": { + WebhookURL: *config.NewSecureString("https://example.com/webhook1"), + Title: "Alerts", + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if ch.Name() != "teams_webhook" { + t.Errorf("expected name 'teams_webhook', got %q", ch.Name()) + } +} + +func TestTeamsWebhookChannel_StartStop(t *testing.T) { + msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook"), + }, + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + ctx := context.Background() + + if ch.IsRunning() { + t.Error("channel should not be running before Start") + } + + if err := ch.Start(ctx); err != nil { + t.Fatalf("Start failed: %v", err) + } + + if !ch.IsRunning() { + t.Error("channel should be running after Start") + } + + if err := ch.Stop(ctx); err != nil { + t.Fatalf("Stop failed: %v", err) + } + + if ch.IsRunning() { + t.Error("channel should not be running after Stop") + } +} + +func TestTeamsWebhookChannel_BuildAdaptiveCard(t *testing.T) { + msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-default"), + Title: "Default", + }, + "alerts": { + WebhookURL: *config.NewSecureString("https://example.com/webhook"), + Title: "Custom Title", + }, + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + target := ch.config.Webhooks["alerts"] + msg := bus.OutboundMessage{ + Content: "Test message content", + ChatID: "alerts", + } + + card, err := ch.buildAdaptiveCard(msg, target) + if err != nil { + t.Fatalf("buildAdaptiveCard failed: %v", err) + } + + if card.Type != "AdaptiveCard" { + t.Errorf("expected card type 'AdaptiveCard', got %q", card.Type) + } +} + +func TestTeamsWebhookChannel_SendNotRunning(t *testing.T) { + msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook"), + }, + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + ctx := context.Background() + msg := bus.OutboundMessage{Content: "test", ChatID: "default"} + + _, err = ch.Send(ctx, msg) + if err == nil { + t.Error("expected error when sending while not running") + } +} + +func TestTeamsWebhookChannel_SendDefaultTargetFallback(t *testing.T) { + tests := []struct { + name string + chatID string + }{ + {"unknown target falls back to default", "unknown"}, + {"empty ChatID uses default", ""}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-default"), + }, + "alerts": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-alerts"), + }, + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + var sentURL string + ch.client = &mockTeamsClient{ + sendFunc: func(ctx context.Context, webhookURL string, message goteamsnotify.TeamsMessage) error { + sentURL = webhookURL + return nil + }, + } + + ctx := context.Background() + _ = ch.Start(ctx) + defer ch.Stop(ctx) + + msg := bus.OutboundMessage{Content: "test", ChatID: tt.chatID} + _, err = ch.Send(ctx, msg) + if err != nil { + t.Fatalf("expected success, got error: %v", err) + } + + if sentURL != "https://example.com/webhook-default" { + t.Errorf("expected default webhook URL, got %q", sentURL) + } + }) + } +} + +func TestTeamsWebhookChannel_SendSuccess(t *testing.T) { + msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-default"), + Title: "Default", + }, + "alerts": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-alerts"), + Title: "Test Alerts", + }, + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // Inject mock client + var sentURL string + ch.client = &mockTeamsClient{ + sendFunc: func(ctx context.Context, webhookURL string, message goteamsnotify.TeamsMessage) error { + sentURL = webhookURL + return nil + }, + } + + ctx := context.Background() + _ = ch.Start(ctx) + defer ch.Stop(ctx) + + msg := bus.OutboundMessage{Content: "Hello Teams!", ChatID: "alerts"} + + _, err = ch.Send(ctx, msg) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if sentURL != "https://example.com/webhook-alerts" { + t.Errorf("expected webhook URL 'https://example.com/webhook-alerts', got %q", sentURL) + } +} + +func TestTeamsWebhookChannel_SendError(t *testing.T) { + msgBus := bus.NewMessageBus() + bc := &config.Channel{Type: config.ChannelTeamsWebHook, Enabled: true} + cfg := config.TeamsWebhookSettings{ + Webhooks: map[string]config.TeamsWebhookTarget{ + "default": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-default"), + }, + "alerts": { + WebhookURL: *config.NewSecureString("https://example.com/webhook-alerts"), + }, + }, + } + ch, err := NewTeamsWebhookChannel(bc, &cfg, msgBus) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + // Inject mock client that returns an error + ch.client = &mockTeamsClient{ + sendFunc: func(ctx context.Context, webhookURL string, message goteamsnotify.TeamsMessage) error { + return errors.New("error on notification: 401 Unauthorized, forbidden") + }, + } + + ctx := context.Background() + _ = ch.Start(ctx) + defer ch.Stop(ctx) + + msg := bus.OutboundMessage{Content: "test", ChatID: "alerts"} + + _, err = ch.Send(ctx, msg) + if err == nil { + t.Error("expected error from failed send") + } +} + +func TestSplitContentWithTables(t *testing.T) { + tests := []struct { + name string + content string + wantSegs int + wantTbl int // number of table segments + }{ + { + name: "no tables", + content: "Just some text\nwith multiple lines", + wantSegs: 1, + wantTbl: 0, + }, + { + name: "single table", + content: `| Col1 | Col2 | +|------|------| +| A | B | +| C | D |`, + wantSegs: 1, + wantTbl: 1, + }, + { + name: "text before table", + content: `Here is some text. + +| Col1 | Col2 | +|------|------| +| A | B |`, + wantSegs: 2, + wantTbl: 1, + }, + { + name: "text before and after table", + content: `Before table. + +| Col1 | Col2 | +|------|------| +| A | B | + +After table.`, + wantSegs: 3, + wantTbl: 1, + }, + { + name: "multiple tables", + content: `First table: + +| A | B | +|---|---| +| 1 | 2 | + +Second table: + +| X | Y | +|---|---| +| 3 | 4 |`, + wantSegs: 4, + wantTbl: 2, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + segs := splitContentWithTables(tt.content) + if len(segs) != tt.wantSegs { + t.Errorf("got %d segments, want %d", len(segs), tt.wantSegs) + } + tableCount := 0 + for _, s := range segs { + if s.isTable { + tableCount++ + } + } + if tableCount != tt.wantTbl { + t.Errorf("got %d tables, want %d", tableCount, tt.wantTbl) + } + }) + } +} + +func TestParseMarkdownTable(t *testing.T) { + tableStr := `| Name | Value | +|------|-------| +| foo | 123 | +| bar | 456 |` + + elem, err := parseMarkdownTable(tableStr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if elem.Type != "Table" { + t.Errorf("expected type 'Table', got %q", elem.Type) + } + + // Should have 3 rows (header + 2 data rows) + if len(elem.Rows) != 3 { + t.Errorf("expected 3 rows, got %d", len(elem.Rows)) + } + + // Should have 2 columns with widths based on content length + if len(elem.Columns) != 2 { + t.Errorf("expected 2 columns, got %d", len(elem.Columns)) + } +} + +func TestParseMarkdownTableColumnWidths(t *testing.T) { + // Column widths are based on HEADER row only: + // Col1: "Description" (11 chars) + // Col2: "X" (1 char) + // Col3: "Amount" (6 chars) + tableStr := `| Description | X | Amount | +|-------------|---|--------| +| Short | Y | 100 | +| Longer text | Z | 50 |` + + elem, err := parseMarkdownTable(tableStr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if len(elem.Columns) != 3 { + t.Fatalf("expected 3 columns, got %d", len(elem.Columns)) + } + + // Verify column widths are based on header content length + w1, ok1 := elem.Columns[0].Width.(int) + w2, ok2 := elem.Columns[1].Width.(int) + w3, ok3 := elem.Columns[2].Width.(int) + + if !ok1 || !ok2 || !ok3 { + t.Fatalf("expected int widths, got types: %T, %T, %T", + elem.Columns[0].Width, elem.Columns[1].Width, elem.Columns[2].Width) + } + + // Header lengths: "Description" = 11, "X" = 1, "Amount" = 6 + if w1 != 11 { + t.Errorf("expected col1 width 11 (from 'Description'), got %d", w1) + } + if w2 != 1 { + t.Errorf("expected col2 width 1 (from 'X'), got %d", w2) + } + if w3 != 6 { + t.Errorf("expected col3 width 6 (from 'Amount'), got %d", w3) + } +} + +func TestCalculateColumnWidths(t *testing.T) { + tests := []struct { + name string + maxLengths []int + wantWidths []int + }{ + { + name: "equal lengths", + maxLengths: []int{10, 10, 10}, + wantWidths: []int{10, 10, 10}, + }, + { + name: "varying lengths", + maxLengths: []int{5, 20, 10}, + wantWidths: []int{5, 20, 10}, + }, + { + name: "zero length gets minimum of 1", + maxLengths: []int{0, 5, 0}, + wantWidths: []int{1, 5, 1}, + }, + { + name: "empty input", + maxLengths: []int{}, + wantWidths: nil, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + cols := calculateColumnWidths(tt.maxLengths) + + if tt.wantWidths == nil { + if cols != nil { + t.Errorf("expected nil, got %v", cols) + } + return + } + + if len(cols) != len(tt.wantWidths) { + t.Fatalf("expected %d columns, got %d", len(tt.wantWidths), len(cols)) + } + + for i, col := range cols { + width, ok := col.Width.(int) + if !ok { + t.Errorf("column %d: expected int width, got %T", i, col.Width) + continue + } + if width != tt.wantWidths[i] { + t.Errorf("column %d: expected width %d, got %d", i, tt.wantWidths[i], width) + } + if col.Type != "TableColumnDefinition" { + t.Errorf("column %d: expected type 'TableColumnDefinition', got %q", i, col.Type) + } + } + }) + } +} + +func TestParseTableRow(t *testing.T) { + tests := []struct { + line string + want []string + }{ + {"| A | B | C |", []string{"A", "B", "C"}}, + {"|A|B|C|", []string{"A", "B", "C"}}, + {"| foo | bar |", []string{"foo", "bar"}}, + {"", nil}, + } + + for _, tt := range tests { + got := parseTableRow(tt.line) + if len(got) != len(tt.want) { + t.Errorf("parseTableRow(%q): got %v, want %v", tt.line, got, tt.want) + continue + } + for i := range got { + if got[i] != tt.want[i] { + t.Errorf("parseTableRow(%q)[%d]: got %q, want %q", tt.line, i, got[i], tt.want[i]) + } + } + } +} + +func TestIsSeparatorRow(t *testing.T) { + tests := []struct { + line string + want bool + }{ + {"|---|---|", true}, + {"| --- | --- |", true}, + {"|:---|---:|", true}, + {"| :---: | :---: |", true}, + {"| A | B |", false}, + {"| foo | bar |", false}, + } + + for _, tt := range tests { + got := isSeparatorRow(tt.line) + if got != tt.want { + t.Errorf("isSeparatorRow(%q): got %v, want %v", tt.line, got, tt.want) + } + } +} diff --git a/pkg/channels/telegram/init.go b/pkg/channels/telegram/init.go index ac87bb805..dc461b324 100644 --- a/pkg/channels/telegram/init.go +++ b/pkg/channels/telegram/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewTelegramChannel(cfg, b) - }) + channels.RegisterFactory( + config.ChannelTelegram, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.TelegramSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewTelegramChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/telegram/telegram.go b/pkg/channels/telegram/telegram.go index 2d59de4dc..2a9cfe4ae 100644 --- a/pkg/channels/telegram/telegram.go +++ b/pkg/channels/telegram/telegram.go @@ -47,18 +47,23 @@ type TelegramChannel struct { *channels.BaseChannel bot *telego.Bot bh *th.BotHandler - config *config.Config + bc *config.Channel chatIDs map[string]int64 ctx context.Context cancel context.CancelFunc + tgCfg *config.TelegramSettings registerFunc func(context.Context, []commands.Definition) error commandRegCancel context.CancelFunc } -func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) { +func NewTelegramChannel( + bc *config.Channel, + telegramCfg *config.TelegramSettings, + bus *bus.MessageBus, +) (*TelegramChannel, error) { + channelName := bc.Name() var opts []telego.BotOption - telegramCfg := cfg.Channels.Telegram if telegramCfg.Proxy != "" { proxyURL, parseErr := url.Parse(telegramCfg.Proxy) @@ -90,20 +95,21 @@ func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChann } base := channels.NewBaseChannel( - "telegram", + channelName, telegramCfg, bus, - telegramCfg.AllowFrom, + bc.AllowFrom, channels.WithMaxMessageLength(4000), - channels.WithGroupTrigger(telegramCfg.GroupTrigger), - channels.WithReasoningChannelID(telegramCfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &TelegramChannel{ BaseChannel: base, bot: bot, - config: cfg, + bc: bc, chatIDs: make(map[string]int64), + tgCfg: telegramCfg, }, nil } @@ -174,9 +180,9 @@ func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([] return nil, channels.ErrNotRunning } - useMarkdownV2 := c.config.Channels.Telegram.UseMarkdownV2 + useMarkdownV2 := c.tgCfg.UseMarkdownV2 - chatID, threadID, err := parseTelegramChatID(msg.ChatID) + chatID, threadID, err := resolveTelegramOutboundTarget(msg.ChatID, &msg.Context) if err != nil { return nil, fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed) } @@ -360,7 +366,7 @@ func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func( // EditMessage implements channels.MessageEditor. func (c *TelegramChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error { - useMarkdownV2 := c.config.Channels.Telegram.UseMarkdownV2 + useMarkdownV2 := c.tgCfg.UseMarkdownV2 cid, _, err := parseTelegramChatID(chatID) if err != nil { return err @@ -435,7 +441,7 @@ func (c *TelegramChannel) DeleteMessage(ctx context.Context, chatID string, mess // It sends a placeholder message (e.g. "Thinking... 💭") that will later be // edited to the actual response via EditMessage (channels.MessageEditor). func (c *TelegramChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) { - phCfg := c.config.Channels.Telegram.Placeholder + phCfg := c.bc.Placeholder if !phCfg.Enabled { return "", nil } @@ -463,7 +469,7 @@ func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMe return nil, channels.ErrNotRunning } - chatID, threadID, err := parseTelegramChatID(msg.ChatID) + chatID, threadID, err := resolveTelegramOutboundTarget(msg.ChatID, &msg.Context) if err != nil { return nil, fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed) } @@ -691,8 +697,9 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes } // In group chats, apply unified group trigger filtering + isMentioned := false if message.Chat.Type != "private" { - isMentioned := c.isBotMentioned(message) + isMentioned = c.isBotMentioned(message) if isMentioned { content = c.stripBotMention(content) } @@ -738,13 +745,9 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes }) peerKind := "direct" - peerID := fmt.Sprintf("%d", user.ID) if message.Chat.Type != "private" { peerKind = "group" - peerID = compositeChatID } - - peer := bus.Peer{Kind: peerKind, ID: peerID} messageID := fmt.Sprintf("%d", message.MessageID) metadata := map[string]string{ @@ -753,24 +756,29 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes "first_name": user.FirstName, "is_group": fmt.Sprintf("%t", message.Chat.Type != "private"), } - if message.ReplyToMessage != nil { - metadata["reply_to_message_id"] = fmt.Sprintf("%d", message.ReplyToMessage.MessageID) - } - // Set parent_peer metadata for per-topic agent binding. + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + ChatID: fmt.Sprintf("%d", chatID), + ChatType: peerKind, + SenderID: platformID, + MessageID: messageID, + Mentioned: isMentioned, + Raw: metadata, + } if message.Chat.IsForum && threadID != 0 { - metadata["parent_peer_kind"] = "topic" - metadata["parent_peer_id"] = fmt.Sprintf("%d", threadID) + inboundCtx.TopicID = fmt.Sprintf("%d", threadID) + } + if message.ReplyToMessage != nil { + inboundCtx.ReplyToMessageID = fmt.Sprintf("%d", message.ReplyToMessage.MessageID) } - c.HandleMessage(c.ctx, - peer, - messageID, - platformID, + c.HandleMessageWithContext( + c.ctx, compositeChatID, content, mediaPaths, - metadata, + inboundCtx, sender, ) return nil @@ -958,6 +966,28 @@ func parseTelegramChatID(chatID string) (int64, int, error) { return cid, tid, nil } +func resolveTelegramOutboundTarget(chatID string, outboundCtx *bus.InboundContext) (int64, int, error) { + targetChatID := strings.TrimSpace(chatID) + if targetChatID == "" && outboundCtx != nil { + targetChatID = strings.TrimSpace(outboundCtx.ChatID) + } + resolvedChatID, resolvedThreadID, err := parseTelegramChatID(targetChatID) + if err != nil { + return 0, 0, err + } + if resolvedThreadID != 0 || outboundCtx == nil { + return resolvedChatID, resolvedThreadID, nil + } + topicID := strings.TrimSpace(outboundCtx.TopicID) + if topicID == "" { + return resolvedChatID, resolvedThreadID, nil + } + if threadID, convErr := strconv.Atoi(topicID); convErr == nil { + return resolvedChatID, threadID, nil + } + return resolvedChatID, resolvedThreadID, nil +} + func logParseFailed(err error, useMarkdownV2 bool) { parsingName := "HTML" if useMarkdownV2 { @@ -1063,7 +1093,7 @@ func (c *TelegramChannel) stripBotMention(content string) string { // BeginStream implements channels.StreamingCapable. func (c *TelegramChannel) BeginStream(ctx context.Context, chatID string) (channels.Streamer, error) { - if !c.config.Channels.Telegram.Streaming.Enabled { + if !c.tgCfg.Streaming.Enabled { return nil, fmt.Errorf("streaming disabled in config") } @@ -1072,7 +1102,7 @@ func (c *TelegramChannel) BeginStream(ctx context.Context, chatID string) (chann return nil, err } - streamCfg := c.config.Channels.Telegram.Streaming + streamCfg := c.tgCfg.Streaming return &telegramStreamer{ bot: c.bot, chatID: cid, diff --git a/pkg/channels/telegram/telegram_test.go b/pkg/channels/telegram/telegram_test.go index 4f7a2600b..3d147b337 100644 --- a/pkg/channels/telegram/telegram_test.go +++ b/pkg/channels/telegram/telegram_test.go @@ -140,7 +140,8 @@ func newTestChannelWithConstructor( BaseChannel: base, bot: bot, chatIDs: make(map[string]int64), - config: config.DefaultConfig(), + bc: &config.Channel{Type: config.ChannelTelegram, Enabled: true}, + tgCfg: &config.TelegramSettings{}, } } @@ -527,6 +528,38 @@ func TestSend_WithForumThreadID(t *testing.T) { assert.Len(t, caller.calls, 1) } +func TestSend_UsesContextTopicIDWhenChatIDDoesNotIncludeThread(t *testing.T) { + caller := &stubCaller{ + callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) { + return successResponse(t), nil + }, + } + ch := newTestChannel(t, caller) + + _, err := ch.Send(context.Background(), bus.OutboundMessage{ + ChatID: "-1001234567890", + Content: "Hello from topic context", + Context: bus.InboundContext{ + Channel: "telegram", + ChatID: "-1001234567890", + TopicID: "42", + }, + }) + + require.NoError(t, err) + require.Len(t, caller.calls, 1) + + var params struct { + ChatID int64 `json:"chat_id"` + MessageThreadID int `json:"message_thread_id"` + Text string `json:"text"` + } + require.NoError(t, json.Unmarshal(caller.calls[0].Data.BodyRaw, ¶ms)) + assert.Equal(t, int64(-1001234567890), params.ChatID) + assert.Equal(t, 42, params.MessageThreadID) + assert.Equal(t, "Hello from topic context", params.Text) +} + func TestHandleMessage_ForumTopic_SetsMetadata(t *testing.T) { messageBus := bus.NewMessageBus() ch := &TelegramChannel{ @@ -556,16 +589,10 @@ func TestHandleMessage_ForumTopic_SetsMetadata(t *testing.T) { inbound, ok := <-messageBus.InboundChan() require.True(t, ok, "expected inbound message") - // Composite chatID should include thread ID - assert.Equal(t, "-1001234567890/42", inbound.ChatID) - - // Peer ID should include thread ID for session key isolation - assert.Equal(t, "group", inbound.Peer.Kind) - assert.Equal(t, "-1001234567890/42", inbound.Peer.ID) - - // Parent peer metadata should be set for agent binding - assert.Equal(t, "topic", inbound.Metadata["parent_peer_kind"]) - assert.Equal(t, "42", inbound.Metadata["parent_peer_id"]) + // ChatID remains the parent chat; TopicID isolates the sub-conversation. + assert.Equal(t, "-1001234567890", inbound.ChatID) + assert.Equal(t, "group", inbound.Context.ChatType) + assert.Equal(t, "42", inbound.Context.TopicID) } func TestHandleMessage_NoForum_NoThreadMetadata(t *testing.T) { @@ -598,13 +625,8 @@ func TestHandleMessage_NoForum_NoThreadMetadata(t *testing.T) { // Plain chatID without thread suffix assert.Equal(t, "-100999", inbound.ChatID) - // Peer ID should be raw chat ID (no thread suffix) - assert.Equal(t, "group", inbound.Peer.Kind) - assert.Equal(t, "-100999", inbound.Peer.ID) - - // No parent peer metadata - assert.Empty(t, inbound.Metadata["parent_peer_kind"]) - assert.Empty(t, inbound.Metadata["parent_peer_id"]) + assert.Equal(t, "group", inbound.Context.ChatType) + assert.Empty(t, inbound.Context.TopicID) } func TestHandleMessage_ReplyThread_NonForum_NoIsolation(t *testing.T) { @@ -641,13 +663,8 @@ func TestHandleMessage_ReplyThread_NonForum_NoIsolation(t *testing.T) { // chatID should NOT include thread suffix for non-forum groups assert.Equal(t, "-100999", inbound.ChatID) - // Peer ID should be raw chat ID (shared session for whole group) - assert.Equal(t, "group", inbound.Peer.Kind) - assert.Equal(t, "-100999", inbound.Peer.ID) - - // No parent peer metadata - assert.Empty(t, inbound.Metadata["parent_peer_kind"]) - assert.Empty(t, inbound.Metadata["parent_peer_id"]) + assert.Equal(t, "group", inbound.Context.ChatType) + assert.Empty(t, inbound.Context.TopicID) } func assertHandleMessageQuotedUserReply( @@ -700,7 +717,7 @@ func assertHandleMessageQuotedUserReply( inbound, ok := <-messageBus.InboundChan() require.True(t, ok) - assert.Equal(t, strconv.Itoa(replyMessageID), inbound.Metadata["reply_to_message_id"]) + assert.Equal(t, strconv.Itoa(replyMessageID), inbound.Context.ReplyToMessageID) assert.Equal(t, expectedContent, inbound.Content) } @@ -786,7 +803,7 @@ func TestHandleMessage_ReplyToOwnBotMessage_UsesAssistantRole(t *testing.T) { inbound, ok := <-messageBus.InboundChan() require.True(t, ok) - assert.Equal(t, "101", inbound.Metadata["reply_to_message_id"]) + assert.Equal(t, "101", inbound.Context.ReplyToMessageID) assert.Equal( t, "[quoted assistant message from afjcjsbx_picoclaw_bot]: Fatto! Ho creato il file notizie_2026_03_28.md\n\nti ricordi questo file?", diff --git a/pkg/channels/vk/init.go b/pkg/channels/vk/init.go index 6a5927a32..deca297d5 100644 --- a/pkg/channels/vk/init.go +++ b/pkg/channels/vk/init.go @@ -7,7 +7,14 @@ import ( ) func init() { - channels.RegisterFactory("vk", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewVKChannel(cfg, b) - }) + channels.RegisterFactory( + config.ChannelVK, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + if bc == nil { + return nil, channels.ErrSendFailed + } + return NewVKChannel(channelName, bc, b) + }, + ) } diff --git a/pkg/channels/vk/vk.go b/pkg/channels/vk/vk.go index 92fbcf4ad..b27431ba0 100644 --- a/pkg/channels/vk/vk.go +++ b/pkg/channels/vk/vk.go @@ -21,41 +21,54 @@ import ( type VKChannel struct { *channels.BaseChannel - vk *api.VK - lp *longpoll.LongPoll - config *config.Config - ctx context.Context - cancel context.CancelFunc + vk *api.VK + lp *longpoll.LongPoll + channelName string + bc *config.Channel + ctx context.Context + cancel context.CancelFunc } -func NewVKChannel(cfg *config.Config, bus *bus.MessageBus) (*VKChannel, error) { - vkCfg := cfg.Channels.VK +func NewVKChannel(channelName string, bc *config.Channel, bus *bus.MessageBus) (*VKChannel, error) { + var vkCfg config.VKSettings + if err := bc.Decode(&vkCfg); err != nil { + return nil, err + } vk := api.NewVK(vkCfg.Token.String()) base := channels.NewBaseChannel( - "vk", - vkCfg, + channelName, + &vkCfg, bus, - vkCfg.AllowFrom, + bc.AllowFrom, channels.WithMaxMessageLength(4000), - channels.WithGroupTrigger(vkCfg.GroupTrigger), - channels.WithReasoningChannelID(vkCfg.ReasoningChannelID), + channels.WithGroupTrigger(bc.GroupTrigger), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &VKChannel{ BaseChannel: base, vk: vk, - config: cfg, + channelName: channelName, + bc: bc, }, nil } +func (c *VKChannel) getVKCfg() *config.VKSettings { + var v config.VKSettings + if err := c.bc.Decode(&v); err != nil { + return nil + } + return &v +} + func (c *VKChannel) Start(ctx context.Context) error { logger.InfoC("vk", "Starting VK bot (Long Poll mode)...") c.ctx, c.cancel = context.WithCancel(ctx) - groupID := c.config.Channels.VK.GroupID + groupID := c.getVKCfg().GroupID if groupID == 0 { c.cancel() return fmt.Errorf("group_id is required for VK bot") @@ -143,7 +156,7 @@ func (c *VKChannel) handleMessage(msg object.MessagesMessage) { return } - groupTrigger := c.config.Channels.VK.GroupTrigger + groupTrigger := c.bc.GroupTrigger isGroupChat := peerID != fromID if isGroupChat { @@ -159,14 +172,11 @@ func (c *VKChannel) handleMessage(msg object.MessagesMessage) { _ = groupTrigger } - peerKind := "direct" - peerIDStr := userID + chatType := "direct" if isGroupChat { - peerKind = "group" - peerIDStr = chatID + chatType = "group" } - peer := bus.Peer{Kind: peerKind, ID: peerIDStr} messageID := strconv.Itoa(msg.ConversationMessageID) metadata := map[string]string{ @@ -174,16 +184,15 @@ func (c *VKChannel) handleMessage(msg object.MessagesMessage) { "is_group": fmt.Sprintf("%t", isGroupChat), } - c.HandleMessage(c.ctx, - peer, - messageID, - userID, - chatID, - text, - nil, - metadata, - sender, - ) + c.HandleInboundContext(c.ctx, chatID, text, nil, bus.InboundContext{ + Channel: "vk", + ChatID: chatID, + ChatType: chatType, + SenderID: userID, + MessageID: messageID, + Mentioned: isGroupChat && c.isMentioned(msg), + Raw: metadata, + }, sender) } func (c *VKChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]string, error) { diff --git a/pkg/channels/vk/vk_test.go b/pkg/channels/vk/vk_test.go index c7e62ab31..9583cbf44 100644 --- a/pkg/channels/vk/vk_test.go +++ b/pkg/channels/vk/vk_test.go @@ -1,6 +1,7 @@ package vk import ( + "encoding/json" "testing" "github.com/sipeed/picoclaw/pkg/bus" @@ -8,19 +9,23 @@ import ( "github.com/sipeed/picoclaw/pkg/config" ) +func makeVKTestBaseChannel(vkCfg config.VKSettings) *config.Channel { + settings, _ := json.Marshal(vkCfg) + return &config.Channel{ + Enabled: true, + Type: config.ChannelVK, + Settings: settings, + } +} + func TestNewVKChannel(t *testing.T) { msgBus := bus.NewMessageBus() t.Run("missing group_id", func(t *testing.T) { - cfg := &config.Config{ - Channels: config.ChannelsConfig{ - VK: config.VKConfig{ - Enabled: true, - Token: *config.NewSecureString("test_token"), - }, - }, - } - ch, err := NewVKChannel(cfg, msgBus) + bc := makeVKTestBaseChannel(config.VKSettings{ + Token: *config.NewSecureString("test_token"), + }) + ch, err := NewVKChannel("vk", bc, msgBus) if err != nil { t.Fatalf("unexpected error during creation: %v", err) } @@ -33,16 +38,11 @@ func TestNewVKChannel(t *testing.T) { }) t.Run("valid config with group_id", func(t *testing.T) { - cfg := &config.Config{ - Channels: config.ChannelsConfig{ - VK: config.VKConfig{ - Enabled: true, - Token: *config.NewSecureString("test_token"), - GroupID: 123456789, - }, - }, - } - ch, err := NewVKChannel(cfg, msgBus) + bc := makeVKTestBaseChannel(config.VKSettings{ + Token: *config.NewSecureString("test_token"), + GroupID: 123456789, + }) + ch, err := NewVKChannel("vk", bc, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -55,17 +55,18 @@ func TestNewVKChannel(t *testing.T) { }) t.Run("with allow_from", func(t *testing.T) { - cfg := &config.Config{ - Channels: config.ChannelsConfig{ - VK: config.VKConfig{ - Enabled: true, - Token: *config.NewSecureString("test_token"), - GroupID: 123456789, - AllowFrom: []string{"123456789"}, - }, - }, + vkCfg := config.VKSettings{ + Token: *config.NewSecureString("test_token"), + GroupID: 123456789, } - ch, err := NewVKChannel(cfg, msgBus) + settings, _ := json.Marshal(vkCfg) + bc := &config.Channel{ + Enabled: true, + Type: "vk", + AllowFrom: []string{"123456789"}, + Settings: settings, + } + ch, err := NewVKChannel("vk", bc, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -78,20 +79,21 @@ func TestNewVKChannel(t *testing.T) { }) t.Run("with group_trigger", func(t *testing.T) { - cfg := &config.Config{ - Channels: config.ChannelsConfig{ - VK: config.VKConfig{ - Enabled: true, - Token: *config.NewSecureString("test_token"), - GroupID: 123456789, - GroupTrigger: config.GroupTriggerConfig{ - MentionOnly: false, - Prefixes: []string{"/bot", "!bot"}, - }, - }, - }, + vkCfg := config.VKSettings{ + Token: *config.NewSecureString("test_token"), + GroupID: 123456789, } - ch, err := NewVKChannel(cfg, msgBus) + settings, _ := json.Marshal(vkCfg) + bc := &config.Channel{ + Enabled: true, + Type: "vk", + GroupTrigger: config.GroupTriggerConfig{ + MentionOnly: false, + Prefixes: []string{"/bot", "!bot"}, + }, + Settings: settings, + } + ch, err := NewVKChannel("vk", bc, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -103,16 +105,11 @@ func TestNewVKChannel(t *testing.T) { func TestVKChannel_MaxMessageLength(t *testing.T) { msgBus := bus.NewMessageBus() - cfg := &config.Config{ - Channels: config.ChannelsConfig{ - VK: config.VKConfig{ - Enabled: true, - Token: *config.NewSecureString("test_token"), - GroupID: 123456789, - }, - }, - } - ch, err := NewVKChannel(cfg, msgBus) + bc := makeVKTestBaseChannel(config.VKSettings{ + Token: *config.NewSecureString("test_token"), + GroupID: 123456789, + }) + ch, err := NewVKChannel("vk", bc, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -236,16 +233,11 @@ func TestVKChannel_ProcessAttachments(t *testing.T) { func TestVKChannel_VoiceCapabilities(t *testing.T) { msgBus := bus.NewMessageBus() - cfg := &config.Config{ - Channels: config.ChannelsConfig{ - VK: config.VKConfig{ - Enabled: true, - Token: *config.NewSecureString("test_token"), - GroupID: 123456789, - }, - }, - } - ch, err := NewVKChannel(cfg, msgBus) + bc := makeVKTestBaseChannel(config.VKSettings{ + Token: *config.NewSecureString("test_token"), + GroupID: 123456789, + }) + ch, err := NewVKChannel("vk", bc, msgBus) if err != nil { t.Fatalf("unexpected error: %v", err) } diff --git a/pkg/channels/wecom/init.go b/pkg/channels/wecom/init.go index 3aad84d42..78e51d18e 100644 --- a/pkg/channels/wecom/init.go +++ b/pkg/channels/wecom/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("wecom", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewChannel(cfg.Channels.WeCom, b) - }) + channels.RegisterFactory( + config.ChannelWeCom, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.WeComSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/wecom/wecom.go b/pkg/channels/wecom/wecom.go index 9689d5171..a0a23feda 100644 --- a/pkg/channels/wecom/wecom.go +++ b/pkg/channels/wecom/wecom.go @@ -34,7 +34,7 @@ const ( type WeComChannel struct { *channels.BaseChannel - config config.WeComConfig + config *config.WeComSettings ctx context.Context cancel context.CancelFunc @@ -108,7 +108,7 @@ func (s *recentMessageSet) Mark(id string) bool { return true } -func NewChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*WeComChannel, error) { +func NewChannel(bc *config.Channel, cfg *config.WeComSettings, messageBus *bus.MessageBus) (*WeComChannel, error) { if cfg.BotID == "" || cfg.Secret.String() == "" { return nil, fmt.Errorf("wecom bot_id and secret are required") } @@ -120,8 +120,8 @@ func NewChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*WeComChann "wecom", cfg, messageBus, - cfg.AllowFrom, - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + bc.AllowFrom, + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) ch := &WeComChannel{ @@ -570,7 +570,6 @@ func (c *WeComChannel) dispatchIncoming(reqID string, msg wecomIncomingMessage) return err } - peer := bus.Peer{Kind: peerKind, ID: actualChatID} metadata := map[string]string{ "channel": "wecom", "req_id": reqID, @@ -583,7 +582,20 @@ func (c *WeComChannel) dispatchIncoming(reqID string, msg wecomIncomingMessage) metadata["quote_text"] = quoteText } - c.HandleMessage(c.ctx, peer, msg.MsgID, senderID, actualChatID, content, mediaRefs, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: c.Name(), + Account: strings.TrimSpace(msg.AIBotID), + ChatID: actualChatID, + ChatType: peerKind, + SenderID: senderID, + MessageID: msg.MsgID, + ReplyHandles: map[string]string{ + "req_id": reqID, + }, + Raw: metadata, + } + + c.HandleInboundContext(c.ctx, actualChatID, content, mediaRefs, inboundCtx, sender) return nil } diff --git a/pkg/channels/wecom/wecom_test.go b/pkg/channels/wecom/wecom_test.go index b3a87e246..85a2f6ef7 100644 --- a/pkg/channels/wecom/wecom_test.go +++ b/pkg/channels/wecom/wecom_test.go @@ -50,11 +50,11 @@ func TestDispatchIncoming_UsesActualChatIDAndStoresReqIDRoute(t *testing.T) { if inbound.MessageID != "msg-1" { t.Fatalf("inbound MessageID = %q, want msg-1", inbound.MessageID) } - if inbound.Peer.ID != "chat-1" { - t.Fatalf("inbound Peer.ID = %q, want chat-1", inbound.Peer.ID) + if inbound.Context.ChatType != "direct" { + t.Fatalf("inbound Context.ChatType = %q, want direct", inbound.Context.ChatType) } - if inbound.Metadata["req_id"] != "req-1" { - t.Fatalf("inbound req_id = %q, want req-1", inbound.Metadata["req_id"]) + if inbound.Context.ReplyHandles["req_id"] != "req-1" { + t.Fatalf("inbound req_id = %q, want req-1", inbound.Context.ReplyHandles["req_id"]) } default: t.Fatal("expected inbound message to be published") @@ -605,9 +605,10 @@ func TestSendMedia_SendsActiveFile(t *testing.T) { func newTestWeComChannel(t *testing.T, messageBus *bus.MessageBus) *WeComChannel { t.Helper() - cfg := config.WeComConfig{BotID: "bot-1"} + cfg := &config.WeComSettings{BotID: "bot-1"} cfg.SetSecret("secret-1") - ch, err := NewChannel(cfg, messageBus) + bc := &config.Channel{Type: config.ChannelWeCom, Enabled: true} + ch, err := NewChannel(bc, cfg, messageBus) if err != nil { t.Fatalf("NewChannel() error = %v", err) } diff --git a/pkg/channels/weixin/state.go b/pkg/channels/weixin/state.go index 8fbdd00dd..0f8257895 100644 --- a/pkg/channels/weixin/state.go +++ b/pkg/channels/weixin/state.go @@ -44,7 +44,7 @@ func picoclawHomeDir() string { return config.GetHome() } -func genWeixinAccountKey(cfg config.WeixinConfig) string { +func genWeixinAccountKey(cfg *config.WeixinSettings) string { token := strings.TrimSpace(cfg.Token.String()) if token == "" { return "default" @@ -53,11 +53,11 @@ func genWeixinAccountKey(cfg config.WeixinConfig) string { return hex.EncodeToString(sum[:8]) } -func buildWeixinSyncBufPath(cfg config.WeixinConfig) string { +func buildWeixinSyncBufPath(cfg *config.WeixinSettings) string { return filepath.Join(picoclawHomeDir(), "channels", "weixin", "sync", genWeixinAccountKey(cfg)+".json") } -func buildWeixinContextTokensPath(cfg config.WeixinConfig) string { +func buildWeixinContextTokensPath(cfg *config.WeixinSettings) string { return filepath.Join(picoclawHomeDir(), "channels", "weixin", "context-tokens", genWeixinAccountKey(cfg)+".json") } diff --git a/pkg/channels/weixin/weixin.go b/pkg/channels/weixin/weixin.go index a0d0c96b5..2897d2422 100644 --- a/pkg/channels/weixin/weixin.go +++ b/pkg/channels/weixin/weixin.go @@ -20,7 +20,7 @@ import ( type WeixinChannel struct { *channels.BaseChannel api *ApiClient - config config.WeixinConfig + config *config.WeixinSettings ctx context.Context cancel context.CancelFunc bus *bus.MessageBus @@ -36,25 +36,48 @@ type WeixinChannel struct { } func init() { - channels.RegisterFactory("weixin", func(cfg *config.Config, bus *bus.MessageBus) (channels.Channel, error) { - return NewWeixinChannel(cfg.Channels.Weixin, bus) - }) + channels.RegisterFactory( + config.ChannelWeixin, + func(channelName, channelType string, cfg *config.Config, bus *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + weixinCfg, ok := decoded.(*config.WeixinSettings) + if !ok { + return nil, channels.ErrSendFailed + } + ch, err := NewWeixinChannel(bc, weixinCfg, bus) + if err != nil { + return nil, err + } + if channelName != config.ChannelWeixin { + ch.SetName(channelName) + } + return ch, nil + }, + ) } // NewWeixinChannel creates a new WeixinChannel from config. -func NewWeixinChannel(cfg config.WeixinConfig, messageBus *bus.MessageBus) (*WeixinChannel, error) { +func NewWeixinChannel( + bc *config.Channel, + cfg *config.WeixinSettings, + messageBus *bus.MessageBus, +) (*WeixinChannel, error) { api, err := NewApiClient(cfg.BaseURL, cfg.Token.String(), cfg.Proxy) if err != nil { return nil, fmt.Errorf("weixin: failed to create API client: %w", err) } base := channels.NewBaseChannel( - "weixin", + bc.Name(), cfg, messageBus, - cfg.AllowFrom, + bc.AllowFrom, channels.WithMaxMessageLength(4000), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &WeixinChannel{ @@ -334,8 +357,6 @@ func (c *WeixinChannel) handleInboundMessage(ctx context.Context, msg WeixinMess return } - peer := bus.Peer{Kind: "direct", ID: fromUserID} - metadata := map[string]string{ "from_user_id": fromUserID, "context_token": msg.ContextToken, @@ -354,7 +375,21 @@ func (c *WeixinChannel) handleInboundMessage(ctx context.Context, msg WeixinMess c.persistContextTokens() } - c.HandleMessage(ctx, peer, messageID, fromUserID, fromUserID, content, mediaRefs, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: "weixin", + ChatID: fromUserID, + ChatType: "direct", + SenderID: fromUserID, + MessageID: messageID, + Raw: metadata, + } + if msg.ContextToken != "" { + inboundCtx.ReplyHandles = map[string]string{ + "context_token": msg.ContextToken, + } + } + + c.HandleInboundContext(ctx, fromUserID, content, mediaRefs, inboundCtx, sender) } // Send implements channels.Channel by sending a text message to the WeChat user. diff --git a/pkg/channels/weixin/weixin_test.go b/pkg/channels/weixin/weixin_test.go index b41b930db..aea2cbb0c 100644 --- a/pkg/channels/weixin/weixin_test.go +++ b/pkg/channels/weixin/weixin_test.go @@ -66,7 +66,7 @@ func TestDownloadAndDecryptCDNBuffer(t *testing.T) { }, nil })}, }, - config: config.WeixinConfig{ + config: &config.WeixinSettings{ CDNBaseURL: "https://cdn.example.com", }, typingCache: make(map[string]typingTicketCacheEntry), @@ -105,7 +105,7 @@ func TestDownloadAndDecryptCDNBufferUsesFullURLWhenProvided(t *testing.T) { return nil, nil })}, }, - config: config.WeixinConfig{ + config: &config.WeixinSettings{ CDNBaseURL: "https://cdn.example.com", }, typingCache: make(map[string]typingTicketCacheEntry), @@ -155,7 +155,7 @@ func TestDownloadAndDecryptCDNBufferFallsBackToConstructedURLWhenFullURLFails(t }, nil })}, }, - config: config.WeixinConfig{ + config: &config.WeixinSettings{ CDNBaseURL: "https://cdn.example.com", }, typingCache: make(map[string]typingTicketCacheEntry), @@ -224,7 +224,7 @@ func TestUploadBufferToCDN(t *testing.T) { }, nil })}, }, - config: config.WeixinConfig{ + config: &config.WeixinSettings{ CDNBaseURL: "https://cdn.example.com", }, typingCache: make(map[string]typingTicketCacheEntry), @@ -259,7 +259,7 @@ func TestBuildWeixinSyncBufPathUsesPicoclawHome(t *testing.T) { home := t.TempDir() t.Setenv(config.EnvHome, home) - wxCfg := config.WeixinConfig{ + wxCfg := &config.WeixinSettings{ BaseURL: "https://ilinkai.weixin.qq.com/", } wxCfg.SetToken("token-123") diff --git a/pkg/channels/whatsapp/init.go b/pkg/channels/whatsapp/init.go index d9c2669c3..a9558d185 100644 --- a/pkg/channels/whatsapp/init.go +++ b/pkg/channels/whatsapp/init.go @@ -7,7 +7,19 @@ import ( ) func init() { - channels.RegisterFactory("whatsapp", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - return NewWhatsAppChannel(cfg.Channels.WhatsApp, b) - }) + channels.RegisterFactory( + config.ChannelWhatsApp, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.WhatsAppSettings) + if !ok { + return nil, channels.ErrSendFailed + } + return NewWhatsAppChannel(bc, c, b) + }, + ) } diff --git a/pkg/channels/whatsapp/whatsapp.go b/pkg/channels/whatsapp/whatsapp.go index 98622fe37..4c338b5f4 100644 --- a/pkg/channels/whatsapp/whatsapp.go +++ b/pkg/channels/whatsapp/whatsapp.go @@ -20,7 +20,7 @@ import ( type WhatsAppChannel struct { *channels.BaseChannel conn *websocket.Conn - config config.WhatsAppConfig + config *config.WhatsAppSettings url string ctx context.Context cancel context.CancelFunc @@ -28,14 +28,18 @@ type WhatsAppChannel struct { connected bool } -func NewWhatsAppChannel(cfg config.WhatsAppConfig, bus *bus.MessageBus) (*WhatsAppChannel, error) { +func NewWhatsAppChannel( + bc *config.Channel, + cfg *config.WhatsAppSettings, + bus *bus.MessageBus, +) (*WhatsAppChannel, error) { base := channels.NewBaseChannel( "whatsapp", cfg, bus, - cfg.AllowFrom, + bc.AllowFrom, channels.WithMaxMessageLength(65536), - channels.WithReasoningChannelID(cfg.ReasoningChannelID), + channels.WithReasoningChannelID(bc.ReasoningChannelID), ) return &WhatsAppChannel{ @@ -223,13 +227,6 @@ func (c *WhatsAppChannel) handleIncomingMessage(msg map[string]any) { metadata["user_name"] = userName } - var peer bus.Peer - if chatID == senderID { - peer = bus.Peer{Kind: "direct", ID: senderID} - } else { - peer = bus.Peer{Kind: "group", ID: chatID} - } - logger.InfoCF("whatsapp", "WhatsApp message received", map[string]any{ "sender": senderID, "preview": utils.Truncate(content, 50), @@ -248,5 +245,18 @@ func (c *WhatsAppChannel) handleIncomingMessage(msg map[string]any) { return } - c.HandleMessage(c.ctx, peer, messageID, senderID, chatID, content, mediaPaths, metadata, sender) + inboundCtx := bus.InboundContext{ + Channel: "whatsapp", + ChatID: chatID, + SenderID: senderID, + MessageID: messageID, + Raw: metadata, + } + if chatID == senderID { + inboundCtx.ChatType = "direct" + } else { + inboundCtx.ChatType = "group" + } + + c.HandleInboundContext(c.ctx, chatID, content, mediaPaths, inboundCtx, sender) } diff --git a/pkg/channels/whatsapp/whatsapp_command_test.go b/pkg/channels/whatsapp/whatsapp_command_test.go index 2d85d74f8..17ba0d2f9 100644 --- a/pkg/channels/whatsapp/whatsapp_command_test.go +++ b/pkg/channels/whatsapp/whatsapp_command_test.go @@ -12,7 +12,7 @@ import ( func TestHandleIncomingMessage_DoesNotConsumeGenericCommandsLocally(t *testing.T) { messageBus := bus.NewMessageBus() ch := &WhatsAppChannel{ - BaseChannel: channels.NewBaseChannel("whatsapp", config.WhatsAppConfig{}, messageBus, nil), + BaseChannel: channels.NewBaseChannel("whatsapp", config.WhatsAppSettings{}, messageBus, nil), ctx: context.Background(), } diff --git a/pkg/channels/whatsapp_native/init.go b/pkg/channels/whatsapp_native/init.go index df13e8539..f1be82ec9 100644 --- a/pkg/channels/whatsapp_native/init.go +++ b/pkg/channels/whatsapp_native/init.go @@ -9,12 +9,27 @@ import ( ) func init() { - channels.RegisterFactory("whatsapp_native", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { - waCfg := cfg.Channels.WhatsApp - storePath := waCfg.SessionStorePath - if storePath == "" { - storePath = filepath.Join(cfg.WorkspacePath(), "whatsapp") - } - return NewWhatsAppNativeChannel(waCfg, b, storePath) - }) + channels.RegisterFactory( + config.ChannelWhatsAppNative, + func(channelName, channelType string, cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) { + bc := cfg.Channels[channelName] + decoded, err := bc.GetDecoded() + if err != nil { + return nil, err + } + c, ok := decoded.(*config.WhatsAppSettings) + if !ok { + return nil, channels.ErrSendFailed + } + storePath := c.SessionStorePath + if storePath == "" { + storePath = filepath.Join(cfg.WorkspacePath(), "whatsapp") + } + ch, err := NewWhatsAppNativeChannel(bc, channelName, c, b, storePath) + if err != nil { + return nil, err + } + return ch, nil + }, + ) } diff --git a/pkg/channels/whatsapp_native/whatsapp_command_test.go b/pkg/channels/whatsapp_native/whatsapp_command_test.go index e51bec392..4d269af66 100644 --- a/pkg/channels/whatsapp_native/whatsapp_command_test.go +++ b/pkg/channels/whatsapp_native/whatsapp_command_test.go @@ -20,7 +20,7 @@ import ( func TestHandleIncoming_DoesNotConsumeGenericCommandsLocally(t *testing.T) { messageBus := bus.NewMessageBus() ch := &WhatsAppNativeChannel{ - BaseChannel: channels.NewBaseChannel("whatsapp_native", config.WhatsAppConfig{}, messageBus, nil), + BaseChannel: channels.NewBaseChannel("whatsapp_native", config.WhatsAppSettings{}, messageBus, nil), runCtx: context.Background(), } diff --git a/pkg/channels/whatsapp_native/whatsapp_native.go b/pkg/channels/whatsapp_native/whatsapp_native.go index d0a74a405..de4ecfd44 100644 --- a/pkg/channels/whatsapp_native/whatsapp_native.go +++ b/pkg/channels/whatsapp_native/whatsapp_native.go @@ -48,7 +48,7 @@ const ( // WhatsAppNativeChannel implements the WhatsApp channel using whatsmeow (in-process, no external bridge). type WhatsAppNativeChannel struct { *channels.BaseChannel - config config.WhatsAppConfig + config *config.WhatsAppSettings storePath string client *whatsmeow.Client container *sqlstore.Container @@ -64,11 +64,13 @@ type WhatsAppNativeChannel struct { // NewWhatsAppNativeChannel creates a WhatsApp channel that uses whatsmeow for connection. // storePath is the directory for the SQLite session store (e.g. workspace/whatsapp). func NewWhatsAppNativeChannel( - cfg config.WhatsAppConfig, + bc *config.Channel, + name string, + cfg *config.WhatsAppSettings, bus *bus.MessageBus, storePath string, ) (channels.Channel, error) { - base := channels.NewBaseChannel("whatsapp_native", cfg, bus, cfg.AllowFrom, channels.WithMaxMessageLength(65536)) + base := channels.NewBaseChannel(name, cfg, bus, bc.AllowFrom, channels.WithMaxMessageLength(65536)) if storePath == "" { storePath = "whatsapp" } @@ -375,7 +377,6 @@ func (c *WhatsAppNativeChannel) handleIncoming(evt *events.Message) { if evt.Info.Chat.Server == types.GroupServer { peerKind = "group" } - peer := bus.Peer{Kind: peerKind, ID: chatID} messageID := evt.Info.ID sender := bus.SenderInfo{ Platform: "whatsapp", @@ -393,7 +394,17 @@ func (c *WhatsAppNativeChannel) handleIncoming(evt *events.Message) { "WhatsApp message received", map[string]any{"sender_id": senderID, "content_preview": utils.Truncate(content, 50)}, ) - c.HandleMessage(c.runCtx, peer, messageID, senderID, chatID, content, mediaPaths, metadata, sender) + + inboundCtx := bus.InboundContext{ + Channel: "whatsapp", + ChatID: chatID, + SenderID: senderID, + MessageID: messageID, + ChatType: peerKind, + Raw: metadata, + } + + c.HandleInboundContext(c.runCtx, chatID, content, mediaPaths, inboundCtx, sender) } func (c *WhatsAppNativeChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]string, error) { diff --git a/pkg/channels/whatsapp_native/whatsapp_native_stub.go b/pkg/channels/whatsapp_native/whatsapp_native_stub.go index 984af23e7..d058d8bba 100644 --- a/pkg/channels/whatsapp_native/whatsapp_native_stub.go +++ b/pkg/channels/whatsapp_native/whatsapp_native_stub.go @@ -13,9 +13,16 @@ import ( // NewWhatsAppNativeChannel returns an error when the binary was not built with -tags whatsapp_native. // Build with: go build -tags whatsapp_native ./cmd/... func NewWhatsAppNativeChannel( - cfg config.WhatsAppConfig, + bc *config.Channel, + name string, + cfg *config.WhatsAppSettings, bus *bus.MessageBus, storePath string, ) (channels.Channel, error) { + _ = bc + _ = name + _ = cfg + _ = bus + _ = storePath return nil, fmt.Errorf("whatsapp native not compiled in; build with -tags whatsapp_native") } diff --git a/pkg/commands/builtin.go b/pkg/commands/builtin.go index 39e76f752..5cf9425cb 100644 --- a/pkg/commands/builtin.go +++ b/pkg/commands/builtin.go @@ -11,6 +11,7 @@ func BuiltinDefinitions() []Definition { showCommand(), listCommand(), useCommand(), + btwCommand(), switchCommand(), checkCommand(), clearCommand(), diff --git a/pkg/commands/builtin_test.go b/pkg/commands/builtin_test.go index 5fd8dd9bc..79e63d9b7 100644 --- a/pkg/commands/builtin_test.go +++ b/pkg/commands/builtin_test.go @@ -188,3 +188,79 @@ func TestBuiltinUseCommand_PassthroughsToAgentLogic(t *testing.T) { t.Fatalf("/use command=%q, want=%q", res.Command, "use") } } + +func TestBuiltinBtwCommand_UsesSideQuestionRuntime(t *testing.T) { + rt := &Runtime{ + AskSideQuestion: func(ctx context.Context, question string) (string, error) { + if question != "what is 2+2?" { + t.Fatalf("question=%q, want %q", question, "what is 2+2?") + } + return "4", nil + }, + } + defs := BuiltinDefinitions() + ex := NewExecutor(NewRegistry(defs), rt) + + var reply string + res := ex.Execute(context.Background(), Request{ + Text: "/btw what is 2+2?", + Reply: func(text string) error { + reply = text + return nil + }, + }) + if res.Outcome != OutcomeHandled { + t.Fatalf("/btw outcome=%v, want=%v", res.Outcome, OutcomeHandled) + } + if reply != "4" { + t.Fatalf("/btw reply=%q, want=%q", reply, "4") + } +} + +func TestBuiltinBtwCommand_MissingQuestion(t *testing.T) { + defs := BuiltinDefinitions() + ex := NewExecutor(NewRegistry(defs), &Runtime{ + AskSideQuestion: func(context.Context, string) (string, error) { + return "", nil + }, + }) + + var reply string + res := ex.Execute(context.Background(), Request{ + Text: "/btw", + Reply: func(text string) error { + reply = text + return nil + }, + }) + if res.Outcome != OutcomeHandled { + t.Fatalf("/btw outcome=%v, want=%v", res.Outcome, OutcomeHandled) + } + if reply != "Usage: /btw