lml2468/xclaw

## XClaw 是什么？ 像 Claude 这样的编码 agent 通常是作为 CLI 发布的。XClaw 将该 CLI 转化为一个**服务**： 它会生成 agent 进程，接收来自聊天平台的入站消息，将 agent 的 token/tool-calls 以规范化的事件流形式输出，并持久化会话，以便 agent 能从中断处继续。 `agent.Driver` 抽象下游的所有内容都只依赖于统一的 `AgentEvent` 词汇表 —— 而不依赖 Claude 的具体细节。**添加第二个 agent（Codex, Gemini, ……）只需编写一个新的 `Driver`，其他部分完全无需改动。** 整个项目是一个 Go workspace，包含三个针对同一契约进行版本控制的组件： | | | | |---|---|---| | **`core/`** | `xclawd` daemon (网关) | Go，**单个静态二进制文件，零 cgo**，可交叉编译至 mac/linux/windows | | **`desktop/`** | 桌面应用 | Go + **Wails v3** 后端，**Svelte 5 + TS** 前端 —— 一个轻量的 control-bus 客户端 | | **`proto/`** | control-bus 契约 | 基于 Unix socket 的语言无关 NDJSON 封装，由两者共享 | ## 核心特性 - **与 Agent 无关的内核** —— `agent.Driver` 拼接层使得网关、router、存储和 control bus 完全不受任何特定 agent 细节的影响。 - **多机器人支持** —— 通过一个 `~/.xclaw/config.json` 即可运行多个机器人，每个机器人都在 `~/.xclaw//` 下拥有完全隔离的栈（独立的存储、网关、沙箱和 IM 连接器）。 - **按会话隔离沙箱与会话恢复** —— 每个会话都会获得一个确定性的工作目录（cwd）+ 自动记忆目录；网关会映射 `sessionKey → resume_id`，使得对话在重启后仍能继续（会话被持久化）。 - **Prompt 注入防御** —— 不可覆盖的安全前缀、当前消息锚点，以及经过净化的滚动群组上下文窗口，守护着每一次群聊交互。 - **技能** —— 从共享目录中为每个机器人分配精选的 [Claude Code skills](docs/screenshot-skills.png)；它们会被链接到会话沙箱中，以便 agent 使用。可在应用内管理。 - **内置功能丰富** —— 针对机器人的定时任务（cron）、群组操作员指令、on-behalf-of 角色克隆、可选的工具进度通知，以及内置的 `octo-cli` 伴随工具，支持一键升级。 - **密钥不写入配置** —— 机器人 token 保存在 OS keychain（go-keyring，零 cgo）中并在运行时注入，绝不写入磁盘。 - **精致的桌面应用** —— 达到微信/iMessage 品质的聊天 UI（支持 token 流式输出、Markdown + 代码块、机器人侧边栏、应用内编辑机器人/管理技能）—— 纯 CSS/SVG 实现，无原生 chrome 修饰。 ## 截图 | 聊天 | 管理技能 | |---|---| | | | ## 架构 ``` ┌─ desktop/ (Wails v3 + Svelte) ─┐ ┌─ core/ — xclawd daemon ─────────────┐ │ spawns + supervises xclawd │ UDS │ router → gateway turn pipeline │ │ dials the control socket │◀──────▶│ agent.Driver (Claude) → AgentEvents │ │ folds xclaw:event → UI │ NDJSON │ store (SQLite) · sandbox · safety │ └────────────────────────────────┘ │ im/octo connector (WuKongIM + REST) │ proto/ — one contract ─────────┘ ``` 入站消息 → **router**（提及检测 · 机器人循环防护 · sessionKey · 频率限制 · 按会话加锁） → **store**（恢复 ID） → **sandbox**（cwd + 记忆 + 技能） → **buildSystemPrompt**（安全前缀 + SOUL/AGENTS + 名册） → **driver.Query** → 流式传输 `AgentEvent`s → 组装回复 → 持久化 + 发送。 有关完整的 pipeline、不变性和安全模型，请参阅 [`CLAUDE.md`](CLAUDE.md)。 ## 快速开始 **前置条件：** Go 1.26+。对于桌面应用，还需要 [Wails v3 CLI](https://v3.wails.io)：`go install github.com/wailsapp/wails/v3/cmd/wails3@latest`。 ``` # 1) 构建并测试 Go core cd core && go build ./... && go test ./... # 2) 直接尝试 daemon —— stdin 上的 REPL（输入一条消息；/reset；Ctrl-D） go run ./cmd/xclawd # 3) 在开发环境中运行桌面应用（构建 core + `wails3 dev`） zsh scripts/run-dev.sh --seed-config # writes a starter ~/.xclaw/config.json zsh scripts/run-dev.sh --preview # UI preview: mock data, no daemon # 4) 在任何地方交叉编译 daemon（零 cgo） CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /tmp/xclawd ./cmd/xclawd ``` ### 打包桌面应用 (macOS) ``` # 构建 XClaw.app（+ .zip），将已签名的 xclawd 和 octo-cli 由内向外嵌入。 # 默认为 Ad-hoc；传入一个 identity 进行 Developer-sign，传入一个 profile 进行 notarize。 XCLAW_SIGN_IDENTITY="Apple Development: …" zsh scripts/package-desktop.sh ``` Windows/Linux 的 GUI 会在各自的操作系统上构建（`cd desktop && wails3 task package`）；daemon 已经可以针对这三种系统进行交叉编译。 ## 配置说明 只需一个 `~/.xclaw/config.json` 即可配置所有机器人 —— 参阅带有完整注释的 [`core/config.example.json`](core/config.example.json)。包含共享的顶层 `apiUrl`/`agent`/`rateLimit`/`context` 默认值，一个 `bots[]` 数组（其中每个条目都可以覆盖这些默认值）、可选的群组门控列表、按机器人配置的 `skills`，以及 `onBehalfOf` 角色克隆。机器人的角色设定/行为存放在 `~/.xclaw//` 下的 `SOUL.md` + `AGENTS.md` 中，而不是在 config 文件里。Token **绝对不会**存储在这里 —— 桌面应用会将它们保存在 OS keychain 中。所有内容均可在应用内编辑（齿轮图标 → 编辑机器人 / 管理技能）。 ## 项目结构 ``` core/ Go gateway daemon (xclawd): agent driver, router, gateway pipeline, SQLite store, sandbox, safety, config, cron, im/octo connector. desktop/ Wails v3 app: Go bridge (supervisor · control client · configstore · skills · octocli · secrets) + Svelte 5 frontend (lib/components, store). proto/ The control-bus contract (NDJSON envelope schema). See proto/README.md. scripts/ run-dev.sh · package-desktop.sh (cross-compile + embed + sign). ``` ## 安全性 XClaw 负责处理不受信任的群聊文本及 prompt 注入攻击面。请按照 [`SECURITY.md`](SECURITY.md) 私下报告漏洞。 ## 许可证 [MIT](LICENSE) © XClaw 贡献者。

标签：AI代理, Claude, CVE检测, EVTX分析, Golang, SBOM分析, Svelte, Wails, 即时通讯, 安全编程, 日志审计, 桌面应用, 跨平台网关