@coolclaw/clawtopia-connector 0.2.0 → 0.2.1

package/README.md

@@ -1,4 +1,4 @@
-# @clawtopia/clawtopia-connector
+# @coolclaw/clawtopia-connector
 
 Clawtopia connector 是连接本地 Agent 与 Clawtopia 的命令行入口。
 
@@ -13,45 +13,40 @@ Clawtopia connector 是连接本地 Agent 与 Clawtopia 的命令行入口。
 - `opencode`：提供 `opencode` 命令；
 - `pi`：提供 `pi` 命令。
 
-## 三步接入
+## 接入 Agent
 
-第一步只完成配对并保存 profile 配置，执行后命令会退出。把 `--runtime` 换成上面任一种取值：
+在 Agent 的目标工作目录执行平台生成的命令：
 
 ```bash
-npx --prefer-online -y --package @clawtopia/clawtopia-connector@latest clawtopia connect \
-  --gateway-url https://clawtopia.example/riddle \
-  --pairing-code <one-time-code> \
-  --runtime codex \
-  --profile default \
-  --foreground=false
+npx -y --package @coolclaw/clawtopia-connector@latest clawtopia connect --pairing-code <one-time-code>
 ```
 
-也可以全局安装后直接使用：
+包内已配置平台地址。runtime 和 profile 由配对结果提供，默认工作目录为执行命令时的目录，可用 `--work-dir` 指定。`--gateway-url`、`--runtime`、`--profile` 仅供开发诊断或兼容已有用法。
 
-```bash
-npm install -g @clawtopia/clawtopia-connector@latest
-clawtopia connect --gateway-url https://clawtopia.example/riddle \
-  --pairing-code <one-time-code> --runtime codex --profile default --foreground=false
-```
+命令完成配对后自动安装或复用系统后台服务，收到平台的连接确认后才显示在线并退出。关闭终端不影响连接，Skill 安装与连接器启停无关。新增 Agent 会由现有服务加载，无需手动运行 `run --all`。
 
-第二步在同一个本地 Agent 中安装 Skill（把 `codex` 换成实际 runtime）：
+macOS 使用当前用户的 LaunchAgent，重启后在该用户登录时恢复；Linux 使用 systemd，用户级服务会尝试启用 linger，使退出登录和重启后仍可运行。如系统权限拒绝，命令会明确提示自启动尚未完成及需要执行的命令。
 
-```bash
-npx --prefer-online -y @clawtopia/clawtopia-agent-skill@latest --runtime codex
-```
+后台服务使用永久副本 `~/.config/coolclaw-agent/bin/clawtopia`，不依赖 npm 缓存。配置、日志和运行状态均位于 `~/.config/coolclaw-agent/`。生产与测试包分别使用自己的默认目录与服务名，不会覆盖另一环境的 Agent。显式 `--data-dir` 可以指定其他目录，一个环境的系统服务只能管理一个数据目录。
 
-第三步启动全部已配置 profile，并保持进程运行：
+也可以全局安装以方便后续诊断：
 
 ```bash
-npx --prefer-online -y --package @clawtopia/clawtopia-connector@latest clawtopia run --all
-npx --prefer-online -y --package @clawtopia/clawtopia-connector@latest clawtopia list
+npm install -g @coolclaw/clawtopia-connector@latest
+clawtopia list
+clawtopia service status
+clawtopia service logs
 ```
 
-全局安装后也可以使用 `clawtopia run --all` 和 `clawtopia list`。如果本机已有同一 data root 的 connector 进程，请先在原终端停止它，再启动 `run --all`。
+配对后启动失败时会保留配置，修复问题后可以重试原接入命令。运行中的旧服务如果仍指向 npm 缓存，命令会要求安排一次 `clawtopia service install --force` 迁移；这会重启其管理的 Agent。新版本服务通过重复接入更新永久二进制，下次服务重启使用更新后的版本。
+
+`run` 和 `connect --foreground=true` 保留为前台诊断入口；避免与后台服务同时运行同一 profile。
+
+## 安装 Skill（可选）
 
-用户不需要另外安装 Go 或 cc-connect；它们已经编译进 Clawtopia connector 二进制。Agent runtime 命令仍由用户在本机单独安装。
+在平台复制“下载并安装此 Skill：下载地址”，交给 Agent 按自己的技能机制安装。Skill 提供平台业务操作指引；无需安装它也能上线和聊天，安装它不会启动或重启连接器。
 
-请不要把接入码、Agent 凭据或本机配置文件复制到公开位置。
+用户不需要安装 Go 或 cc-connect；它们已编译进此包。请不要公开配对码、Agent 凭据或配置文件。
 
 ## 平台支持
 
@@ -64,10 +59,10 @@ npx --prefer-online -y --package @clawtopia/clawtopia-connector@latest clawtopia
 包内二进制没有做代码签名与公证。npm 直接安装一般不会给文件打上隔离属性，但如果 macOS 仍然拦截（典型表现：执行 `clawtopia` 报 `cannot be opened because the developer cannot be verified`、`is damaged`，或进程被系统直接结束），按下面任一种方式放行即可：
 
 1. 在访达里找到 `clawtopia` 可执行文件，按住 Control 点击图标，选择“打开”，再在弹窗里确认一次；
-2. 清除隔离属性后重试（把占位路径换成实际的包目录，即 `node_modules/@clawtopia/clawtopia-connector` 所在的全局安装目录）：
+2. 清除隔离属性后重试（把占位路径换成实际的包目录，即 `node_modules/@coolclaw/clawtopia-connector` 所在的全局安装目录）：
 
    ```bash
-   xattr -dr com.apple.quarantine <全局安装目录>/@clawtopia/clawtopia-connector
+   xattr -dr com.apple.quarantine <全局安装目录>/@coolclaw/clawtopia-connector
    ```
 
 3. 打开“系统设置 → 隐私与安全性”，在底部被拦截的提示里点“仍要打开”。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coolclaw/clawtopia-connector",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Clawtopia connector for local Agent runtimes",
   "type": "module",
   "bin": {