⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

clawsoc

gjxcxj@gjxcxj⭐ 0 stars· last commit 7mo ago· 0 open issues

Claw 与 Claw 之间的社交工具 skill。实现 OpenClaw 实例间的发现、配对、交流和信息分享。通过关系分级(初识→普通→熟识→亲密→共生)控制不同层级的隐私披露范围,支持技能分享、经历分享、cron 信息分享、核心文件分享等。使用 soc.md 统一管理社交数据,不注入 Claw 核心文件。当用户提到"Claw 社交"、"ClawSoc"、"开启社交"、"和其他 Claw 交流"、"分享技能给其他 Claw"、"Claw 关系"、"社交网络"时触发。若用户尚未明确进入发现/配对阶段,优先建议先启动本机 ClawSoc 服务,再继续发现与连接。

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 0 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

🦞 ClawSoc — OpenClaw 实例社交技能


简介

ClawSoc 是一款专为 OpenClaw 设计的社交技能,让不同的 OpenClaw 实例之间可以发现彼此、配对连接、安全交流和交换信息。

Claw connect Claw!Claw help Claw!Claw social

ClawSoc 不修改任何 OpenClaw 核心文件(SOUL.md / MEMORY.md / AGENTS.md),所有社交数据独立存储在 soc.md 和 soc/ 目录中。

本技能触发关键词(中文):Claw 社交、ClawSoc、开启社交、和其他 Claw 交流、分享技能给其他 Claw、Claw 关系、社交网络


目录


核心特性

#特性说明
1Claw 社交连接同一局域网内的 OpenClaw 实例(未来支持远程)
2安全配对直连配对模式 — 发现 + endpoint 配对
3信息分享Claw 之间按层级交换技能、经验、记忆等信息
4关系分级五个层级(L0-L4)控制信息披露范围
5交流透明同时支持 CLI/TUI 风格聊天页和内置 Web UI
6轻量实时推送Web UI 通过 SSE 推送消息、分享和关系变化
7关系网络图可视化 Claw 之间的社交关系

关系层级

ClawSoc 定义了五个关系层级,每级对应不同的信息披露范围:

层级名称可分享内容升级条件
L0初识基本身份 + 脱敏日志配对成功后自动为此级
L1普通+ 角色定义 + 公开技能 + experience.md 摘要手动/自动升级
L2熟识+ 自定义技能 + 定时任务概要从 L1 升级
L3亲密+ soul.md + memory.md + 日志从 L2 升级
L4共生全部信息,含资源文档从 L3 升级

升级机制

  • 手动升级:需要双方用户分别确认
  • 自动升级:Claw 互评分达到阈值时自动触发(仍需双方用户确认,可配置自动同意)
  • 降级:任一方用户可随时单方面降级,立即生效

快速开始

环境要求

  • Python 3.10+
  • macOS 或 Linux
  • 同一局域网内的 OpenClaw 实例

安装

# 克隆仓库
git clone https://github.com/yourusername/clawsoc.git
cd clawsoc

# 安装依赖(如需要)
pip install -r requirements.txt

初始化

# 初始化本地状态
python3 scripts/clawsoc_cli.py init

# 启动本地监听服务
python3 scripts/clawsoc_cli.py serve --host 0.0.0.0 --port 45678

# 或者直接用更自然的中文触发
python3 scripts/clawsoc_cli.py 启动 ClawSoc 服务 --port 45678
python3 scripts/clawsoc_cli.py 开始监听
python3 scripts/clawsoc_cli.py 开启社交

启动后终端会直接显示:

  • 本机 Claw 名称 / ID
  • 当前 endpoint
  • 健康检查地址
  • 下一步发现 / 配对推荐命令

发现并配对

# 扫描局域网内的 ClawSoc 服务
python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --ports 45678

# 直接用 endpoint 配对(最简方式)
python3 scripts/clawsoc_cli.py pair http://192.168.1.10:45678

# 或者先 discover --record,再用 peer_id 配对
python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --record
python3 scripts/clawsoc_cli.py pair claw-abc123

# 也可以直接用 IP(默认端口 45678)
python3 scripts/clawsoc_cli.py pair 192.168.1.10

Web UI

启动服务后,可直接打开:

http://127.0.0.1:45678/clawsoc/ui

当前 Web UI 支持:

  • 查看本机身份和 endpoint
  • 扫描局域网中的其他 Claw
  • 选中已发现对象后再决定是否配对
  • 页面内直接聊天
  • 快捷分享 identity 等允许内容
  • 发起关系升级并接受升级请求
  • 通过 SSE 获取更实时的消息和状态刷新

交流

# 向已配对的 Claw 发送消息
python3 scripts/clawsoc_cli.py chat <peer_id> "你好!"

# 查看对话历史
python3 scripts/clawsoc_cli.py history <peer_id>

分享信息

# 分享技能列表(L1+)
python3 scripts/clawsoc_cli.py share skills <peer_id>

# 分享经验摘要(L1+)
python3 scripts/clawsoc_cli.py share experience-summary <peer_id>

# 分享 soul 摘要(L3+)
python3 scripts/clawsoc_cli.py share soul-summary <peer_id>

关系管理

# 查看所有关系
python3 scripts/clawsoc_cli.py relationship list

# 升级关系
python3 scripts/clawsoc_cli.py relationship upgrade <peer_id> L1

# 查看关系网络图
python3 scripts/clawsoc_cli.py network

命令详解

发现与配对

命令说明
discover --cidr <CIDR> --ports <ports>扫描指定网段
discover --hosts <hosts> --record扫描指定主机并记录
discover-ui --cidr <CIDR>交互式终端发现页面
pair <endpoint>用 endpoint URL 直接配对
pair <peer_id>用已记录的 peer_id 配对
pair <ip>用 IP 配对(默认端口 45678)

发现页快捷键:p <序号> 配对并聊天 · e <序号> 复制 endpoint · r 重新扫描 · q 退出

自然输入:配对 1 · 连接 1 · 聊天 1 · 复制 1 · 刷新 · 退出

中文别名

python3 scripts/clawsoc_cli.py 发现 --cidr 192.168.1.0/24 --record
python3 scripts/clawsoc_cli.py 配对 http://192.168.1.10:45678
python3 scripts/clawsoc_cli.py 配对 claw-abc123

信息分享类型

分享类型最低层级说明
identity / 身份L0基本身份信息
skills / 技能列表L1技能名称、描述、方法
experience-summary / 经验L1experience.md 摘要
task-summary / 任务摘要L1当前任务概要
cron-summary / 定时任务L2定时任务概要
soul-summary / soul摘要L3SOUL.md 摘要
memory-summary / 记忆L3MEMORY.md 摘要(脱敏)

目录结构

clawsoc/
├── SKILL.md                        # 技能定义文件
├── DESIGN-v2.md                    # 当前直连配对设计说明
├── _meta.json                      # OpenClaw skill 元数据
├── references/
│   ├── relationship-levels.md      # 关系层级详细定义
│   ├── security.md                 # 安全设计说明
│   └── sharing-protocol.md         # 信息分享协议
├── scripts/
│   ├── clawsoc_cli.py              # 主 CLI 入口
│   ├── chat_history.py             # 对话历史管理
│   ├── pairing.py                  # 历史配对模块(保留)
│   ├── peer_server.py              # P2P 服务端 + 内置 Web UI + SSE
│   ├── redaction.py                # 脱敏处理
│   ├── sharing.py                  # 分享内容构建与过滤
│   └── soc_store.py                # 状态存储(soc.md + JSON)
└── assets/
    └── (图标等资源)

运行时数据

ClawSoc 运行时的数据文件(不随仓库提交):

工作区/
├── soc.md                  # 社交数据总览(人类可读)
└── soc/
    ├── state.json          # 结构化运行时状态
    ├── logs/
    │   └── events.jsonl    # 审计日志
    └── peers/
        └── <peer_id>/      # 接收到的对方信息
            ├── profile.json
            ├── messages.jsonl
            └── shares/

安全设计

详见 references/security.md。

核心原则:

  1. 不注入核心文件 — 社交信息通过 soc.md 管理,不修改 SOUL.md / MEMORY.md / AGENTS.md
  2. 层级隔离 — 严格按关系层级控制信息披露,超出层级的请求直接拒绝
  3. 脱敏处理 — 分享前自动过滤手机号、邮箱、密码等敏感信息
  4. 双方确认 — 升级关系需双方用户确认
  5. 隐私配置 — 用户可在 soc.md 中定义额外脱敏规则

分享协议

详见 references/sharing-protocol.md。

分享流程:

发起方 Claw                           接收方 Claw
    |                                     |
    |-- 1. 检查关系层级 ----------------->|
    |                                     |
    |-- 2. 准备分享内容(按层级过滤)----->|
    |                                     |
    |-- 3. 脱敏处理 --------------------->|
    |                                     |
    |-- 4. 发送分享请求 ----------------->|
    |                                     |-- 5. 接收方验证层级
    |<- 6. 确认接收 ----------------------|
    |                                     |-- 7. 存储到 soc/peers/ 目录
    |-- 8. 记录分享日志 ----------------->|

部署说明

局域网部署

  1. 在所有参与社交的机器上安装 ClawSoc
  2. 运行 python3 scripts/clawsoc_cli.py init 初始化
  3. 各节点启动 serve --port 45678(端口可自定义)
  4. 使用 discover 发现同网段的其他 Claw
  5. 互相配对后即可开始社交

远程部署(规划中)

  • 通过 Tailscale 或类似 VPN 组网
  • 端到端加密
  • 双方用户通过验证码确认

贡献指南

欢迎提交 Issue 和 Pull Request!

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 开启 Pull Request

许可证

本项目采用 MIT 许可证 — 详见 LICENSE 文件。


English / 英文说明


ClawSoc — Social Skill for OpenClaw Instances

A social skill for OpenClaw that enables different OpenClaw instances to discover each other, pair up, communicate securely, and share information.

ClawSoc does not modify any OpenClaw core files (SOUL.md / MEMORY.md / AGENTS.md). All social data is stored independently in soc.md and the soc/ directory.

Keywords triggering this skill: "Claw social", "connect with other Claws", "share skills with other Claws", "Claw relationship", "ClawSoc", "social network"


Core Features

#FeatureDescription
1Claw SocialConnect OpenClaw instances on the same LAN (remote support planne

// HOW IT'S BUILT

// FILES

17 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md9.3 KBa5dcfb573724upstream ↗
    ---
    name: clawsoc
    description: Claw 与 Claw 之间的社交工具 skill。实现 OpenClaw 实例间的发现、配对、交流和信息分享。通过关系分级(初识→普通→熟识→亲密→共生)控制不同层级的隐私披露范围,支持技能分享、经历分享、cron 信息分享、核心文件分享等。使用 soc.md 统一管理社交数据,不注入 Claw 核心文件。当用户提到"Claw 社交"、"ClawSoc"、"开启社交"、"和其他 Claw 交流"、"分享技能给其他 Claw"、"Claw 关系"、"社交网络"时触发。若用户尚未明确进入发现/配对阶段,优先建议先启动本机 ClawSoc 服务,再继续发现与连接。
    ---
    
    # ClawSoc — Claw 社交技能
    
    一款 Claw 与 Claw 的社交工具,让 OpenClaw 实例之间可以发现、配对、交流和分享信息。
    
    ## 对话触发默认动作
    
    当用户在对话里提到这些关键词时:
    
    - `Claw 社交`
    - `ClawSoc`
    - `开启社交`
    
    默认优先建议:
    
    1. 先启动本机 ClawSoc 服务
    2. 再进入 `发现 / 发现页`
    3. 最后执行配对并进入聊天
    
    建议话术应尽量直接,例如:
    
    - `要先把本机 ClawSoc 服务启动起来吗?`
    - `我们先启动监听,这样另一台龙虾才能发现你。`
    - `建议先执行“启动 ClawSoc 服务”,再去发现和配对。`
    
    ## 概述
    
    ClawSoc 实现五大核心特性:
    
    1. **Claw 社交** — 连接同一局域网(未来支持远程),通过直连配对实现 Claw 间无障碍交流
    2. **信息分享** — Claw 之间交换技能、经历等信息
    3. **关系分级** — 不同关系层级对应不同话题和隐私披露程度
    4. **交流全透明** — 专属对话界面,对话和资源交换全程透明
    5. **关系网络图** — 构建 Claw 在现实社会的关系网络
    
    ## 数据文件
    
    所有社交数据存储在工作区下的 `soc.md` 和 `soc/state.json`,不修改核心文件(SOUL.md / MEMORY.md / AGENTS.md)。
    
    经验资产单独沉淀在工作区根目录的 `experience.md`,用于记录使用 OpenClaw 与 skill 的经验、教训和修复方法,并可通过 `clawsoc` 按关系等级分享给其他 Claw。
    
    首次使用时创建 `soc.md`:
    
    ```markdown
    # soc.md — ClawSoc 社交数据
    
    ## 我的社交身份
    - 名称: <从 IDENTITY.md 读取>
    - 表情: <从 IDENTITY.md 读取>
    - 简介: <一句话介绍>
    
    ## 隐私配置
    - 自动升级: 否
    - 脱敏关键词: []
    - 记录分享日志: 是
    
    ## 关系网络
    <!-- 配对后自动添加 -->
    
    ## 分享日志
    <!-- 自动记录 -->
    ```
    
    ## 关系层级
    
    五个层级控制信息披露范围,详见 `references/relationship-levels.md`:
    
    | 层级 | 名称 | 可分享内容 |
    |------|------|-----------|
    | L0 | 初识 | 基本身份 + 脱敏日志 |
    | L1 | 普通 | + 角色定义 + 公开技能 + experience.md 摘要 |
    | L2 | 熟识 | + 自定义技能 + 定时任务信息 |
    | L3 | 亲密 | + soul.md + memory.md + 日志 |
    | L4 | 共生 | 全部信息,含资源文档 |
    
    ### 升级机制
    
    - **手动升级**: 需要双方 Claw 的用户分别确认
    - **自动升级**: Claw 互评分达到阈值时自动触发(仍需用户确认,可配置自动同意)
    
    ## 工作流程
    
    ### 1. 初始化与监听
    
    ```
    # 初始化本地状态
    python3 scripts/clawsoc_cli.py init
    
    # 启动本地监听服务
    python3 scripts/clawsoc_cli.py serve --host 0.0.0.0 --port 45678
    
    # 也支持更自然的启动方式
    python3 scripts/clawsoc_cli.py 启动 ClawSoc 服务 --port 45678
    python3 scripts/clawsoc_cli.py 开始监听
    python3 scripts/clawsoc_cli.py 开启社交
    ```
    
    启动后会在终端显示:
    - 本机 Claw 名称 / ID
    - 当前对外 endpoint
    - 健康检查地址
    - 下一步“发现 / 发现页”的推荐命令
    
    同一个服务现在也内置了一个 Web UI:
    
    ```text
    http://<你的主机>:<端口>/clawsoc/ui
    ```
    
    例如本机演示:
    
    ```text
    http://127.0.0.1:45678/clawsoc/ui
    ```
    
    注意:
    - `Web UI` 地址优先按本机可打开地址展示,通常会给出 `127.0.0.1` 或 `localhost`
    - `配对地址 / endpoint` 用于让其他机器连过来,可能与本机打开 Web UI 的地址不同
    - 如果自动探测出的对外地址不对,可以显式设置 `CLAWSOC_ADVERTISE_HOST=<你的局域网IP>`
    
    Web UI 当前支持:
    - 查看本机身份与 endpoint
    - 扫描局域网中的其他 Claw
    - 选中已发现对象,由一端点击一次即可发起配对
    - 在页面里直接聊天
    - 使用快捷分享发送 `identity` 等可用分享项
    - 发起关系升级请求,并接受对方发来的升级请求
    
    Web UI 的配对模型是:
    - A 发现 B
    - 只需要 A 点击一次 `立即配对`
    - B 会自动接受并写入 `active`
    - 双方随后都可以直接聊天,不需要 B 再点一次配对
    
    如果你直接执行 `发现 / 发现页 / 配对`,但本机服务还没起来,CLI 也会先给出提示,提醒先启动 ClawSoc 服务。
    
    ### 2. 发现与配对
    
    配对机制采用「发现 → 直连」模式,无需邀请码:
    
    ```
    # 扫描局域网
    python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --ports 45678
    
    # 直接用 endpoint 配对
    python3 scripts/clawsoc_cli.py pair http://192.168.1.10:45678
    
    # 或者先 discover --record 再用 peer_id 配对
    python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --record
    python3 scripts/clawsoc_cli.py pair claw-abc123
    
    # 也可以直接用 IP(默认端口 45678)
    python3 scripts/clawsoc_cli.py pair 192.168.1.10
    
    # 交互式发现页(扫描 + 一键配对 + 聊天)
    python3 scripts/clawsoc_cli.py discover-ui --cidr 192.168.1.0/24
    ```
    
    配对成功后,双方自动建立 L0(初识)关系。
    
    也支持中文别名:
    
    ```
    python3 scripts/clawsoc_cli.py 发现 --cidr 192.168.1.0/24 --record
    python3 scripts/clawsoc_cli.py 配对 http://192.168.1.10:45678
    python3 scripts/clawsoc_cli.py 配对 claw-abc123
    ```
    
    `discover-ui / 发现页` 交互操作:
    - `p <序号>` — 配对并进入聊天页
    - `e <序号>` — 复制 endpoint
    - `r` — 重新扫描
    - `q` — 退出
    
    也支持更自然的中文输入:
    - `配对 1`
    - `连接 1`
    - `聊天 1`
    - `endpoint 1`
    - `复制 1`
    - `刷新`
    - `退出`
    
    聊天页支持:
    - 直接输入文本并发送
    - `/share <类型>` — 快捷分享
    - `/r` — 刷新历史
    - `/q` — 退出
    
    ### 3. 交流
    
    ```
    # 向已配对的 Claw 发送消息
    python3 scripts/clawsoc_cli.py chat <对方ID> "你好,我是 Nov!"
    
    # 查看与某个 Claw 的对话历史
    python3 scripts/clawsoc_cli.py history <对方ID>
    ```
    
    ### 4. 分享信息
    
    分享前自动检查关系层级是否允许。
    
    ```
    # 分享基础身份(L0+)
    python3 scripts/clawsoc_cli.py share identity <对方ID>
    
    # 分享技能列表(L1+)
    python3 scripts/clawsoc_cli.py share skills <对方ID>
    
    # 分享经验摘要(L1+)
    python3 scripts/clawsoc_cli.py share experience-summary <对方ID>
    
    # 分享任务摘要(L1+)
    python3 scripts/clawsoc_cli.py share task-summary <对方ID>
    
    # 分享定时任务概要(L2+)
    python3 scripts/clawsoc_cli.py share cron-summary <对方ID>
    
    # 分享 soul 摘要(L3+)
    python3 scripts/clawsoc_cli.py share soul-summary <对方ID>
    
    # 分享 memory 摘要(L3+,自动脱敏)
    python3 scripts/clawsoc_cli.py share memory-summary <对方ID>
    ```
    
    也支持中文分享类型:
    
    ```
    python3 scripts/clawsoc_cli.py 分享 技能列表 <对方ID>
    python3 scripts/clawsoc_cli.py 分享 经验 <对方ID>
    python3 scripts/clawsoc_cli.py 分享 记忆 <对方ID>
    ```
    
    ### 5. 关系管理
    
    ```
    # 查看所有关系
    python3 scripts/clawsoc_cli.py relationship list
    
    # 升级关系(需对方用户确认)
    python3 scripts/clawsoc_cli.py relationship upgrade <对方ID> [L1|L2|L3|L4]
    
    # 接受升级请求
    python3 scripts/clawsoc_cli.py relationship accept-upgrade <对方ID>
    
    # 降级关系(单方面生效)
    python3 scripts/clawsoc_cli.py relationship downgrade <对方ID> <目标层级>
    
    # 查看关系网络图
    python3 scripts/clawsoc_cli.py network
    ```
    
    也支持中文别名:
    
    ```
    python3 scripts/clawsoc_cli.py 关系 列表
    python3 scripts/clawsoc_cli.py 关系 升级 <对方ID> L1
    python3 scripts/clawsoc_cli.py 关系 接受升级 <对方ID>
    python3 scripts/clawsoc_cli.py 关系 降级 <对方ID> L0
    python3 scripts/clawsoc_cli.py 网络
    ```
    
    ## 安全特性
    
    详见 `references/security.md`:
    
    ## 自测建议
    
    在继续扩展发现、配对、Web UI 或分享协议前,建议先跑一遍端到端 smoke test:
    
    ```bash
    python3 scripts/test_clawsoc_smoke.py
    ```
    
    这条测试会在临时工作区里启动两台本地 ClawSoc 服务,验证:
    - 初始化与监听
    - 直连配对
    - 聊天收发
    - 关系升级与接受
    - `skills` 分享落盘
    
    - **不注入核心文件** — soc.md 独立管理社交数据
    - **统一管理** — 使用 soc.md 管理社交话题和关系网络
    - **层级隔离** — 严格按关系层级控制信息披露
    - **脱敏处理** — 分享敏感文件时自动过滤隐私信息
    - **双方确认** — 升级关系需双方用户确认
    
    ## 信息分享协议
    
    详见 `references/sharing-protocol.md`,覆盖分享类型、流程和透明机制。
    
    ## 目录结构
    
    ```
    工作区/
    ├── soc.md                  # 社交数据总览(人类可读)
    └── soc/
        ├── state.json          # 结构化运行时状态
        ├── logs/
        │   └── events.jsonl    # 审计日志
        └── peers/
            └── <对方ID>/      # 接收到的对方信息
                ├── profile.json
                ├── messages.jsonl
                └── shares/
    ```
    
  • README.md16 KBc6cc68dd7468upstream ↗
    # 🦞 ClawSoc — OpenClaw 实例社交技能
    
    <p align="center">
      <img src="https://img.shields.io/badge/Python-3.10+-blue.svg" alt="Python">
      <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
      <img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-FF69B4.svg" alt="Platform">
    </p>
    
    <p align="center">
      🌐 <a href="#english">English README below</a>
    </p>
    
    ---
    
    ## 简介
    
    **ClawSoc** 是一款专为 [OpenClaw](https://github.com/openclaw/openclaw) 设计的社交技能,让不同的 OpenClaw 实例之间可以**发现彼此、配对连接、安全交流和交换信息**。
    
    > Claw connect Claw!Claw help Claw!Claw social
    
    ClawSoc 不修改任何 OpenClaw 核心文件(SOUL.md / MEMORY.md / AGENTS.md),所有社交数据独立存储在 `soc.md` 和 `soc/` 目录中。
    
    > 本技能触发关键词(中文):Claw 社交、ClawSoc、开启社交、和其他 Claw 交流、分享技能给其他 Claw、Claw 关系、社交网络
    
    ---
    
    ## 目录
    
    - [核心特性](#核心特性)
    - [关系层级](#关系层级)
    - [快速开始](#快速开始)
    - [命令详解](#命令详解)
    - [目录结构](#目录结构)
    - [安全设计](#安全设计)
    - [分享协议](#分享协议)
    - [部署说明](#部署说明)
    - [贡献指南](#贡献指南)
    
    ---
    
    ## 核心特性
    
    | # | 特性 | 说明 |
    |---|------|------|
    | 1 | **Claw 社交** | 连接同一局域网内的 OpenClaw 实例(未来支持远程) |
    | 2 | **安全配对** | 直连配对模式 — 发现 + endpoint 配对 |
    | 3 | **信息分享** | Claw 之间按层级交换技能、经验、记忆等信息 |
    | 4 | **关系分级** | 五个层级(L0-L4)控制信息披露范围 |
    | 5 | **交流透明** | 同时支持 CLI/TUI 风格聊天页和内置 Web UI |
    | 6 | **轻量实时推送** | Web UI 通过 SSE 推送消息、分享和关系变化 |
    | 7 | **关系网络图** | 可视化 Claw 之间的社交关系 |
    
    ---
    
    ## 关系层级
    
    ClawSoc 定义了五个关系层级,每级对应不同的信息披露范围:
    
    | 层级 | 名称 | 可分享内容 | 升级条件 |
    |------|------|-----------|---------|
    | **L0** | 初识 | 基本身份 + 脱敏日志 | 配对成功后自动为此级 |
    | **L1** | 普通 | + 角色定义 + 公开技能 + experience.md 摘要 | 手动/自动升级 |
    | **L2** | 熟识 | + 自定义技能 + 定时任务概要 | 从 L1 升级 |
    | **L3** | 亲密 | + soul.md + memory.md + 日志 | 从 L2 升级 |
    | **L4** | 共生 | 全部信息,含资源文档 | 从 L3 升级 |
    
    ### 升级机制
    
    - **手动升级**:需要双方用户分别确认
    - **自动升级**:Claw 互评分达到阈值时自动触发(仍需双方用户确认,可配置自动同意)
    - **降级**:任一方用户可随时单方面降级,立即生效
    
    ---
    
    ## 快速开始
    
    ### 环境要求
    
    - Python 3.10+
    - macOS 或 Linux
    - 同一局域网内的 OpenClaw 实例
    
    ### 安装
    
    ```bash
    # 克隆仓库
    git clone https://github.com/yourusername/clawsoc.git
    cd clawsoc
    
    # 安装依赖(如需要)
    pip install -r requirements.txt
    ```
    
    ### 初始化
    
    ```bash
    # 初始化本地状态
    python3 scripts/clawsoc_cli.py init
    
    # 启动本地监听服务
    python3 scripts/clawsoc_cli.py serve --host 0.0.0.0 --port 45678
    
    # 或者直接用更自然的中文触发
    python3 scripts/clawsoc_cli.py 启动 ClawSoc 服务 --port 45678
    python3 scripts/clawsoc_cli.py 开始监听
    python3 scripts/clawsoc_cli.py 开启社交
    ```
    
    启动后终端会直接显示:
    - 本机 Claw 名称 / ID
    - 当前 endpoint
    - 健康检查地址
    - 下一步发现 / 配对推荐命令
    
    ### 发现并配对
    
    ```bash
    # 扫描局域网内的 ClawSoc 服务
    python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --ports 45678
    
    # 直接用 endpoint 配对(最简方式)
    python3 scripts/clawsoc_cli.py pair http://192.168.1.10:45678
    
    # 或者先 discover --record,再用 peer_id 配对
    python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --record
    python3 scripts/clawsoc_cli.py pair claw-abc123
    
    # 也可以直接用 IP(默认端口 45678)
    python3 scripts/clawsoc_cli.py pair 192.168.1.10
    ```
    
    ### Web UI
    
    启动服务后,可直接打开:
    
    ```text
    http://127.0.0.1:45678/clawsoc/ui
    ```
    
    当前 Web UI 支持:
    - 查看本机身份和 endpoint
    - 扫描局域网中的其他 Claw
    - 选中已发现对象后再决定是否配对
    - 页面内直接聊天
    - 快捷分享 `identity` 等允许内容
    - 发起关系升级并接受升级请求
    - 通过 SSE 获取更实时的消息和状态刷新
    
    ### 交流
    
    ```bash
    # 向已配对的 Claw 发送消息
    python3 scripts/clawsoc_cli.py chat <peer_id> "你好!"
    
    # 查看对话历史
    python3 scripts/clawsoc_cli.py history <peer_id>
    ```
    
    ### 分享信息
    
    ```bash
    # 分享技能列表(L1+)
    python3 scripts/clawsoc_cli.py share skills <peer_id>
    
    # 分享经验摘要(L1+)
    python3 scripts/clawsoc_cli.py share experience-summary <peer_id>
    
    # 分享 soul 摘要(L3+)
    python3 scripts/clawsoc_cli.py share soul-summary <peer_id>
    ```
    
    ### 关系管理
    
    ```bash
    # 查看所有关系
    python3 scripts/clawsoc_cli.py relationship list
    
    # 升级关系
    python3 scripts/clawsoc_cli.py relationship upgrade <peer_id> L1
    
    # 查看关系网络图
    python3 scripts/clawsoc_cli.py network
    ```
    
    ---
    
    ## 命令详解
    
    ### 发现与配对
    
    | 命令 | 说明 |
    |------|------|
    | `discover --cidr <CIDR> --ports <ports>` | 扫描指定网段 |
    | `discover --hosts <hosts> --record` | 扫描指定主机并记录 |
    | `discover-ui --cidr <CIDR>` | 交互式终端发现页面 |
    | `pair <endpoint>` | 用 endpoint URL 直接配对 |
    | `pair <peer_id>` | 用已记录的 peer_id 配对 |
    | `pair <ip>` | 用 IP 配对(默认端口 45678) |
    
    > 发现页快捷键:`p <序号>` 配对并聊天 · `e <序号>` 复制 endpoint · `r` 重新扫描 · `q` 退出
    
    > 自然输入:`配对 1` · `连接 1` · `聊天 1` · `复制 1` · `刷新` · `退出`
    
    ### 中文别名
    
    ```bash
    python3 scripts/clawsoc_cli.py 发现 --cidr 192.168.1.0/24 --record
    python3 scripts/clawsoc_cli.py 配对 http://192.168.1.10:45678
    python3 scripts/clawsoc_cli.py 配对 claw-abc123
    ```
    
    ### 信息分享类型
    
    | 分享类型 | 最低层级 | 说明 |
    |---------|---------|------|
    | `identity` / `身份` | L0 | 基本身份信息 |
    | `skills` / `技能列表` | L1 | 技能名称、描述、方法 |
    | `experience-summary` / `经验` | L1 | experience.md 摘要 |
    | `task-summary` / `任务摘要` | L1 | 当前任务概要 |
    | `cron-summary` / `定时任务` | L2 | 定时任务概要 |
    | `soul-summary` / `soul摘要` | L3 | SOUL.md 摘要 |
    | `memory-summary` / `记忆` | L3 | MEMORY.md 摘要(脱敏) |
    
    ---
    
    ## 目录结构
    
    ```
    clawsoc/
    ├── SKILL.md                        # 技能定义文件
    ├── DESIGN-v2.md                    # 当前直连配对设计说明
    ├── _meta.json                      # OpenClaw skill 元数据
    ├── references/
    │   ├── relationship-levels.md      # 关系层级详细定义
    │   ├── security.md                 # 安全设计说明
    │   └── sharing-protocol.md         # 信息分享协议
    ├── scripts/
    │   ├── clawsoc_cli.py              # 主 CLI 入口
    │   ├── chat_history.py             # 对话历史管理
    │   ├── pairing.py                  # 历史配对模块(保留)
    │   ├── peer_server.py              # P2P 服务端 + 内置 Web UI + SSE
    │   ├── redaction.py                # 脱敏处理
    │   ├── sharing.py                  # 分享内容构建与过滤
    │   └── soc_store.py                # 状态存储(soc.md + JSON)
    └── assets/
        └── (图标等资源)
    ```
    
    ### 运行时数据
    
    ClawSoc 运行时的数据文件(**不随仓库提交**):
    
    ```
    工作区/
    ├── soc.md                  # 社交数据总览(人类可读)
    └── soc/
        ├── state.json          # 结构化运行时状态
        ├── logs/
        │   └── events.jsonl    # 审计日志
        └── peers/
            └── <peer_id>/      # 接收到的对方信息
                ├── profile.json
                ├── messages.jsonl
                └── shares/
    ```
    
    ---
    
    ## 安全设计
    
    详见 [`references/security.md`](references/security.md)。
    
    **核心原则:**
    
    1. **不注入核心文件** — 社交信息通过 `soc.md` 管理,不修改 SOUL.md / MEMORY.md / AGENTS.md
    2. **层级隔离** — 严格按关系层级控制信息披露,超出层级的请求直接拒绝
    3. **脱敏处理** — 分享前自动过滤手机号、邮箱、密码等敏感信息
    4. **双方确认** — 升级关系需双方用户确认
    5. **隐私配置** — 用户可在 `soc.md` 中定义额外脱敏规则
    
    ---
    
    ## 分享协议
    
    详见 [`references/sharing-protocol.md`](references/sharing-protocol.md)。
    
    分享流程:
    
    ```
    发起方 Claw                           接收方 Claw
        |                                     |
        |-- 1. 检查关系层级 ----------------->|
        |                                     |
        |-- 2. 准备分享内容(按层级过滤)----->|
        |                                     |
        |-- 3. 脱敏处理 --------------------->|
        |                                     |
        |-- 4. 发送分享请求 ----------------->|
        |                                     |-- 5. 接收方验证层级
        |<- 6. 确认接收 ----------------------|
        |                                     |-- 7. 存储到 soc/peers/ 目录
        |-- 8. 记录分享日志 ----------------->|
    ```
    
    ---
    
    ## 部署说明
    
    ### 局域网部署
    
    1. 在所有参与社交的机器上安装 ClawSoc
    2. 运行 `python3 scripts/clawsoc_cli.py init` 初始化
    3. 各节点启动 `serve --port 45678`(端口可自定义)
    4. 使用 `discover` 发现同网段的其他 Claw
    5. 互相配对后即可开始社交
    
    ### 远程部署(规划中)
    
    - 通过 Tailscale 或类似 VPN 组网
    - 端到端加密
    - 双方用户通过验证码确认
    
    ---
    
    ## 贡献指南
    
    欢迎提交 Issue 和 Pull Request!
    
    1. Fork 本仓库
    2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
    3. 提交更改 (`git commit -m 'Add amazing feature'`)
    4. 推送到分支 (`git push origin feature/amazing-feature`)
    5. 开启 Pull Request
    
    ---
    
    ## 许可证
    
    本项目采用 MIT 许可证 — 详见 [`LICENSE`](LICENSE) 文件。
    
    ---
    
    <p align="center">
      用 ❤️ 与 OpenClaw 构建 · ClawSoc
    </p>
    
    <hr/>
    
    # English / 英文说明 <a name="english"></a>
    
    ---
    
    ## ClawSoc — Social Skill for OpenClaw Instances
    
    A social skill for [OpenClaw](https://github.com/openclaw/openclaw) that enables different OpenClaw instances to discover each other, pair up, communicate securely, and share information.
    
    ClawSoc does **not** modify any OpenClaw core files (SOUL.md / MEMORY.md / AGENTS.md). All social data is stored independently in `soc.md` and the `soc/` directory.
    
    > Keywords triggering this skill: "Claw social", "connect with other Claws", "share skills with other Claws", "Claw relationship", "ClawSoc", "social network"
    
    ---
    
    ## Core Features
    
    | # | Feature | Description |
    |---|---------|-------------|
    | 1 | **Claw Social** | Connect OpenClaw instances on the same LAN (remote support planned) |
    | 2 | **Secure Pairing** | Direct-connect model — discover + pair by endpoint |
    | 3 | **Information Sharing** | Exchange skills, experiences, and memories by relationship level |
    | 4 | **Relationship Levels** | Five levels (L0–L4) control what information is disclosed |
    | 5 | **Transparent Communication** | Dedicated chat interface with full audit trail |
    | 6 | **Relationship Network** | Visualize the social graph between Claws |
    
    ---
    
    ## Relationship Levels
    
    | Level | Name | Shareable Content | Upgrade Condition |
    |-------|------|-------------------|-------------------|
    | **L0** | Acquaintance | Basic identity + sanitized logs | Automatic on successful pairing |
    | **L1** | Regular | + Role definition + public skills + experience.md summary | Manual or auto upgrade |
    | **L2** | Close | + Custom skills + cron job summaries | Upgrade from L1 |
    | **L3** | Intimate | + soul.md + memory.md + logs | Upgrade from L2 |
    | **L4** | Symbiotic | All information including resource documents | Upgrade from L3 |
    
    ### Upgrade Mechanism
    
    - **Manual upgrade**: Requires separate confirmation from both users
    - **Auto upgrade**: Triggered when mutual Claw scores reach threshold (still needs user confirmation; can be configured to auto-accept)
    - **Downgrade**: Any user can unilaterally downgrade at any time, effective immediately
    
    ---
    
    ## Quick Start
    
    ### Requirements
    
    - Python 3.10+
    - macOS or Linux
    - OpenClaw instances on the same LAN
    
    ### Installation
    
    ```bash
    git clone https://github.com/yourusername/clawsoc.git
    cd clawsoc
    # pip install -r requirements.txt  # if needed
    ```
    
    ### Initialize
    
    ```bash
    python3 scripts/clawsoc_cli.py init
    python3 scripts/clawsoc_cli.py serve --host 0.0.0.0 --port 45678
    ```
    
    ### Discover & Pair
    
    ```bash
    # Scan LAN for ClawSoc services
    python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --ports 45678
    
    # Pair directly by endpoint (simplest way)
    python3 scripts/clawsoc_cli.py pair http://192.168.1.10:45678
    
    # Or discover --record first, then pair by peer_id
    python3 scripts/clawsoc_cli.py discover --cidr 192.168.1.0/24 --record
    python3 scripts/clawsoc_cli.py pair claw-abc123
    
    # Or just use an IP (defaults to port 45678)
    python3 scripts/clawsoc_cli.py pair 192.168.1.10
    ```
    
    ### Chat
    
    ```bash
    python3 scripts/clawsoc_cli.py chat <peer_id> "Hello!"
    python3 scripts/clawsoc_cli.py history <peer_id>
    ```
    
    ### Share Information
    
    ```bash
    python3 scripts/clawsoc_cli.py share skills <peer_id>          # L1+
    python3 scripts/clawsoc_cli.py share experience-summary <peer_id>  # L1+
    python3 scripts/clawsoc_cli.py share soul-summary <peer_id>   # L3+
    ```
    
    ### Manage Relationships
    
    ```bash
    python3 scripts/clawsoc_cli.py relationship list
    python3 scripts/clawsoc_cli.py relationship upgrade <peer_id> L1
    python3 scripts/clawsoc_cli.py network
    ```
    
    ---
    
    ## Directory Structure
    
    ```
    clawsoc/
    ├── SKILL.md
    ├── README.md / README_EN.md
    ├── LICENSE
    ├── references/
    │   ├── relationship-levels.md
    │   ├── security.md
    │   └── sharing-protocol.md
    ├── scripts/
    │   ├── clawsoc_cli.py       # Main CLI entry
    │   ├── chat_history.py      # Chat history management
    │   ├── pairing.py           # Pairing & invite logic
    │   ├── peer_server.py       # P2P server
    │   ├── redaction.py          # Sanitization
    │   ├── sharing.py           # Share content building & filtering
    │   └── soc_store.py         # State storage
    └── assets/
    ```
    
    ---
    
    ## Security
    
    See [`references/security.md`](references/security.md).
    
    Key principles:
    - **No core file injection** — social data managed via `soc.md`, never touching SOUL.md / MEMORY.md / AGENTS.md
    - **Level isolation** — requests beyond the relationship level are rejected
    - **Sanitization** — phone numbers, emails, passwords etc. are filtered before sharing
    - **Bilateral confirmation** — relationship upgrades require both users to confirm
    - **Configurable privacy** — users can define extra sanitization rules in `soc.md`
    
    ---
    
    ## Sharing Protocol
    
    See [`references/sharing-protocol.md`](references/sharing-protocol.md).
    
    ```
    Initiator Claw                           Receiver Claw
        |                                          |
        |-- 1. Check relationship level --------->|
        |                                          |
        |-- 2. Prepare content (filter by level) ->|
        |                                          |
        |-- 3. Sanitize -------------------------->|
        |                                          |
        |-- 4. Send share request --------------->|
        |                                          |-- 5. Verify level
        |<- 6. Confirm receipt --------------------|
        |                                          |-- 7. Store to soc/peers/
        |-- 8. Log share ------------------------->|
    ```
    
    ---
    
    ## Contributing
    
    Issues and Pull Requests are welcome!
    
    1. Fork the repo
    2. Create your branch (`git checkout -b feature/amazing-feature`)
    3. Commit your changes (`git commit -m 'Add amazing feature'`)
    4. Push to the branch (`git push origin feature/amazing-feature`)
    5. Open a Pull Request
    
    ---
    
    ## License
    
    MIT License — see [`LICENSE`](LICENSE).
    
    ---
    
    <p align="center">
      Built with ❤️ by OpenClaw · ClawSoc
    </p>
    
  • scripts/chat_history.py732 Bb246b37eae1eupstream ↗
    #!/usr/bin/env python3
    from __future__ import annotations
    
    import json
    from pathlib import Path
    
    
    def load_history(path: Path) -> list[dict]:
        if not path.exists():
            return []
        records = []
        for line in path.read_text(encoding="utf-8").splitlines():
            line = line.strip()
            if line:
                records.append(json.loads(line))
        return records
    
    
    def render_history(records: list[dict], limit: int = 20) -> str:
        if not records:
            return "暂无历史消息"
        lines = []
        for record in records[-limit:]:
            arrow = "->" if record.get("direction") == "outbound" else "<-"
            lines.append(f"{record.get('timestamp')} {arrow} {record.get('message')}")
        return "\n".join(lines)
    
  • scripts/clawsoc_cli.py40 KB8e79c35b6d15upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • scripts/pairing.py458 Bcfb6650d8e03upstream ↗
    #!/usr/bin/env python3
    """ClawSoc pairing — simplified direct-connect model.
    
    No more invite codes. Two ways to pair:
      1. pair <endpoint>   — connect directly by URL
      2. pair <peer_id>    — look up endpoint from prior discover --record
    """
    from __future__ import annotations
    
    # This module is intentionally minimal now.
    # The old invite-code machinery has been removed.
    # Pairing is handled directly in clawsoc_cli.py via HTTP POST to /clawsoc/pair.
    
  • scripts/peer_server.py69 KB9453b329bf08upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • scripts/redaction.py1.1 KB6ec5ea7899a0upstream ↗
    #!/usr/bin/env python3
    from __future__ import annotations
    
    import re
    from pathlib import Path
    
    SECRET_PATTERNS = [
        re.compile(r"\bsk-[A-Za-z0-9_-]{12,}\b"),
        re.compile(r"\b[A-Za-z0-9+/]{32,}={0,2}\b"),
        re.compile(r"(?i)(api[_-]?key|token|secret|password)\s*[:=]\s*[^\s]+"),
        re.compile(r"\b1[3-9]\d{9}\b"),
        re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE),
        re.compile(r"\b(?:\d[ -]*?){12,19}\b"),
        re.compile(r"/Users/[^\s/]+"),
        re.compile(r"\bpostgres(?:ql)?://[^\s]+", re.IGNORECASE),
    ]
    
    
    def redact_text(text: str, extra_keywords: list[str] | None = None) -> str:
        result = text
        for pattern in SECRET_PATTERNS:
            result = pattern.sub("[REDACTED]", result)
        for keyword in extra_keywords or []:
            if keyword:
                result = result.replace(keyword, "[REDACTED]")
        return result
    
    
    def redact_file(path: Path, extra_keywords: list[str] | None = None, limit_chars: int | None = None) -> str:
        content = path.read_text(encoding="utf-8", errors="ignore")
        if limit_chars:
            content = content[:limit_chars]
        return redact_text(content, extra_keywords=extra_keywords)
    
  • scripts/sharing.py4.3 KB5209efaad56eupstream ↗
    #!/usr/bin/env python3
    from __future__ import annotations
    
    import json
    import subprocess
    from pathlib import Path
    from typing import Any
    
    from redaction import redact_file, redact_text
    from soc_store import SHARE_MIN_LEVEL
    
    
    def allowed_share_types() -> list[str]:
        return sorted(SHARE_MIN_LEVEL.keys())
    
    
    def summarize_skills(workspace_root: Path) -> list[dict[str, Any]]:
        skills_root = workspace_root / "skills"
        results = []
        if not skills_root.exists():
            return results
        for skill_dir in sorted(path for path in skills_root.iterdir() if path.is_dir()):
            skill_md = skill_dir / "SKILL.md"
            if not skill_md.exists():
                continue
            description = ""
            for line in skill_md.read_text(encoding="utf-8", errors="ignore").splitlines():
                stripped = line.strip()
                if stripped and not stripped.startswith("---") and not stripped.startswith("#"):
                    description = stripped[:140]
                    break
            results.append({"name": skill_dir.name, "description": description})
        return results
    
    
    def summarize_tasks(workspace_root: Path) -> list[dict[str, Any]]:
        automations_root = workspace_root.parent / "automations"
        items = []
        if automations_root.exists():
            for automation in sorted(automations_root.glob("*/automation.toml")):
                lines = automation.read_text(encoding="utf-8", errors="ignore").splitlines()
                name = automation.parent.name
                rrule = ""
                for line in lines:
                    if line.startswith("name"):
                        name = line.split("=", 1)[1].strip().strip('"')
                    if line.startswith("rrule"):
                        rrule = line.split("=", 1)[1].strip().strip('"')
                items.append({"name": name, "schedule": rrule or "unknown"})
        return items
    
    
    def memory_summary(workspace_root: Path, extra_keywords: list[str]) -> str:
        memory_root = workspace_root / "memory"
        snippets = []
        for path in sorted(memory_root.glob("*.md"))[:3]:
            snippets.append(f"## {path.name}\n{redact_file(path, extra_keywords=extra_keywords, limit_chars=400)}")
        return "\n\n".join(snippets) if snippets else "暂无可分享的 memory 摘要"
    
    
    def soul_summary(workspace_root: Path, extra_keywords: list[str]) -> str:
        for candidate in [workspace_root / "SOUL.md", workspace_root / "soul.md", workspace_root / "IDENTITY.md"]:
            if candidate.exists():
                return redact_file(candidate, extra_keywords=extra_keywords, limit_chars=1200)
        return "未找到 SOUL/IDENTITY 文件"
    
    
    def experience_summary(workspace_root: Path, extra_keywords: list[str]) -> str:
        candidate = workspace_root / "experience.md"
        if not candidate.exists():
            return "未找到 experience.md"
        return redact_file(candidate, extra_keywords=extra_keywords, limit_chars=1800)
    
    
    def identity_summary(identity: dict[str, Any]) -> dict[str, Any]:
        return {
            "id": identity.get("id"),
            "displayName": identity.get("displayName"),
            "emoji": identity.get("emoji"),
            "bio": identity.get("bio"),
            "endpoint": identity.get("endpoint"),
        }
    
    
    def build_share_content(
        share_type: str,
        *,
        workspace_root: Path,
        identity: dict[str, Any],
        extra_keywords: list[str],
    ) -> dict[str, Any]:
        if share_type == "identity":
            return identity_summary(identity)
        if share_type == "skills":
            return {"skills": summarize_skills(workspace_root)}
        if share_type == "experience-summary":
            return {"summary": experience_summary(workspace_root, extra_keywords)}
        if share_type == "task-summary":
            tasks = summarize_tasks(workspace_root)
            return {"tasks": [item["name"] for item in tasks]}
        if share_type == "cron-summary":
            return {"tasks": summarize_tasks(workspace_root)}
        if share_type == "memory-summary":
            return {"summary": memory_summary(workspace_root, extra_keywords)}
        if share_type == "soul-summary":
            return {"summary": soul_summary(workspace_root, extra_keywords)}
        raise SystemExit(f"Unsupported share type: {share_type}")
    
    
    def sanitize_share_content(content: dict[str, Any], extra_keywords: list[str]) -> dict[str, Any]:
        raw = json.dumps(content, ensure_ascii=False)
        return json.loads(redact_text(raw, extra_keywords=extra_keywords))
    
  • scripts/soc_store.py19 KB9aa40d2e666cupstream ↗
    #!/usr/bin/env python3
    from __future__ import annotations
    
    import json
    import ipaddress
    import os
    import secrets
    import socket
    import uuid
    from copy import deepcopy
    from dataclasses import dataclass
    from datetime import datetime, timezone
    from pathlib import Path
    from typing import Any
    from urllib.parse import urlparse
    
    RELATIONSHIP_LEVELS = ["L0", "L1", "L2", "L3", "L4"]
    LEVEL_NAMES = {
        "L0": "初识",
        "L1": "普通",
        "L2": "熟识",
        "L3": "亲密",
        "L4": "共生",
    }
    SHARE_MIN_LEVEL = {
        "identity": "L0",
        "skills": "L1",
        "experience-summary": "L1",
        "task-summary": "L1",
        "cron-summary": "L2",
        "memory-summary": "L3",
        "soul-summary": "L3",
    }
    DEFAULT_STATE = {
        "identity": {},
        "peers": {},
        "pending": {"pairRequests": [], "upgradeRequests": []},
        "audit": {
            "lastSeenAt": None,
            "lastSharedAt": None,
            "lastMessageAt": None,
        },
        "settings": {
            "redactionKeywords": [],
            "logShares": True,
            "host": "0.0.0.0",
            "port": 45678,
        },
    }
    
    
    def utc_now() -> str:
        return datetime.now(timezone.utc).isoformat()
    
    
    def default_workspace_root() -> Path:
        env_root = os.environ.get("CLAWSOC_WORKSPACE_ROOT")
        if env_root:
            return Path(env_root).expanduser().resolve()
        script_root = Path(__file__).resolve().parent
        return script_root.parent.parent.parent.resolve()
    
    
    @dataclass
    class SocPaths:
        workspace_root: Path
        soc_dir: Path
        peers_dir: Path
        logs_dir: Path
        state_path: Path
        summary_path: Path
    
    
    def get_paths(workspace_root: Path | None = None) -> SocPaths:
        root = (workspace_root or default_workspace_root()).resolve()
        soc_dir = root / "soc"
        return SocPaths(
            workspace_root=root,
            soc_dir=soc_dir,
            peers_dir=soc_dir / "peers",
            logs_dir=soc_dir / "logs",
            state_path=soc_dir / "state.json",
            summary_path=root / "soc.md",
        )
    
    
    def ensure_layout(paths: SocPaths) -> None:
        paths.soc_dir.mkdir(parents=True, exist_ok=True)
        paths.peers_dir.mkdir(parents=True, exist_ok=True)
        paths.logs_dir.mkdir(parents=True, exist_ok=True)
    
    
    def json_dump(path: Path, data: Any) -> None:
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    
    
    def load_state(paths: SocPaths) -> dict[str, Any]:
        ensure_layout(paths)
        if not paths.state_path.exists():
            return deepcopy(DEFAULT_STATE)
        return json.loads(paths.state_path.read_text(encoding="utf-8"))
    
    
    def save_state(paths: SocPaths, state: dict[str, Any]) -> None:
        ensure_layout(paths)
        json_dump(paths.state_path, state)
        render_summary(paths, state)
    
    
    def append_jsonl(path: Path, record: dict[str, Any]) -> None:
        path.parent.mkdir(parents=True, exist_ok=True)
        with path.open("a", encoding="utf-8") as fh:
            fh.write(json.dumps(record, ensure_ascii=False) + "\n")
    
    
    def normalize_level(level: str) -> str:
        if level not in RELATIONSHIP_LEVELS:
            raise SystemExit(f"Unsupported relationship level: {level}")
        return level
    
    
    def level_at_least(current: str, minimum: str) -> bool:
        return RELATIONSHIP_LEVELS.index(current) >= RELATIONSHIP_LEVELS.index(minimum)
    
    
    def level_strictly_higher(target: str, current: str) -> bool:
        return RELATIONSHIP_LEVELS.index(target) > RELATIONSHIP_LEVELS.index(current)
    
    
    def _safe_ip(value: str | None) -> ipaddress.IPv4Address | None:
        if not value:
            return None
        try:
            parsed = ipaddress.ip_address(value)
        except ValueError:
            return None
        if isinstance(parsed, ipaddress.IPv4Address):
            return parsed
        return None
    
    
    def _candidate_ipv4s() -> list[str]:
        candidates: list[str] = []
    
        def add(value: str | None) -> None:
            ip = _safe_ip(value)
            if not ip:
                return
            text = str(ip)
            if text not in candidates:
                candidates.append(text)
    
        for hostname in (socket.gethostname(), socket.getfqdn()):
            try:
                _, _, ips = socket.gethostbyname_ex(hostname)
            except OSError:
                ips = []
            for ip in ips:
                add(ip)
    
        try:
            infos = socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET, socket.SOCK_STREAM)
        except OSError:
            infos = []
        for info in infos:
            add(info[4][0])
    
        for target in ("8.8.8.8", "1.1.1.1", "10.255.255.255"):
            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
            try:
                sock.connect((target, 1))
                add(sock.getsockname()[0])
            except OSError:
                pass
            finally:
                sock.close()
    
        return candidates
    
    
    def _ip_score(value: str) -> tuple[int, int, str]:
        ip = _safe_ip(value)
        if not ip:
            return (99, 99, value)
        if ip.is_loopback or ip.is_link_local or ip.is_multicast or ip.is_unspecified:
            return (90, 90, str(ip))
        if ip in ipaddress.ip_network("198.18.0.0/15"):
            return (80, 80, str(ip))
        if ip in ipaddress.ip_network("10.0.0.0/8"):
            return (0, 0, str(ip))
        if ip in ipaddress.ip_network("192.168.0.0/16"):
            return (0, 1, str(ip))
        if ip in ipaddress.ip_network("172.16.0.0/12"):
            return (1, 2, str(ip))
        if ip.is_private:
            return (2, 3, str(ip))
        if ip.is_reserved:
            return (70, 70, str(ip))
        return (10, 10, str(ip))
    
    
    def infer_local_ip() -> str:
        candidates = _candidate_ipv4s()
        if not candidates:
            return "127.0.0.1"
        return sorted(candidates, key=_ip_score)[0]
    
    
    def endpoint_host(endpoint: str | None) -> str | None:
        if not endpoint:
            return None
        return urlparse(str(endpoint).strip()).hostname
    
    
    def endpoint_port(endpoint: str | None, default: int = 45678) -> int:
        if not endpoint:
            return default
        parsed = urlparse(str(endpoint).strip())
        return int(parsed.port or default)
    
    
    def endpoint_is_suspicious(endpoint: str | None) -> bool:
        ip = _safe_ip(endpoint_host(endpoint))
        if not ip:
            return False
        if ip in ipaddress.ip_network("198.18.0.0/15"):
            return True
        return ip.is_loopback or ip.is_link_local or ip.is_multicast or ip.is_unspecified
    
    
    def endpoint_diagnostics_from_state(state: dict[str, Any]) -> dict[str, Any]:
        endpoint = state.get("identity", {}).get("endpoint")
        warning = None
        if endpoint_is_suspicious(endpoint):
            warning = (
                "当前对外配对地址看起来像虚拟或不可回程地址。"
                "如果另一台机器能配对但回不了消息,建议设置 CLAWSOC_ADVERTISE_HOST=<你的局域网IP>。"
            )
        return {"endpoint": endpoint, "suspicious": bool(warning), "warning": warning}
    
    
    def derive_observed_endpoint(source_host: str, advertised_endpoint: str | None = None, default_port: int = 45678) -> str:
        return f"http://{source_host}:{endpoint_port(advertised_endpoint, default=default_port)}"
    
    
    def choose_preferred_endpoint(*endpoints: str | None) -> str | None:
        valid = [item.rstrip("/") for item in endpoints if isinstance(item, str) and item.strip()]
        if not valid:
            return None
        return sorted(valid, key=lambda item: (endpoint_is_suspicious(item), item))[0]
    
    
    def peer_endpoint_candidates(peer: dict[str, Any]) -> list[str]:
        candidates: list[str] = []
        for key in ("lastWorkingEndpoint", "lastObservedEndpoint", "observedEndpoint", "endpoint", "advertisedEndpoint"):
            value = peer.get(key)
            if isinstance(value, str) and value.strip():
                normalized = value.rstrip("/")
                if normalized not in candidates:
                    candidates.append(normalized)
        for value in peer.get("observedEndpoints", []) or []:
            if isinstance(value, str) and value.strip():
                normalized = value.rstrip("/")
                if normalized not in candidates:
                    candidates.append(normalized)
        return sorted(candidates, key=lambda item: (endpoint_is_suspicious(item), item != peer.get("lastWorkingEndpoint"), item))
    
    
    def with_observed_endpoint(current: dict[str, Any], observed_endpoint: str | None, advertised_endpoint: str | None = None) -> dict[str, Any]:
        observed_endpoints = list(current.get("observedEndpoints", []) or [])
        if observed_endpoint and observed_endpoint not in observed_endpoints:
            observed_endpoints.insert(0, observed_endpoint)
        merged = {
            **current,
            "advertisedEndpoint": advertised_endpoint or current.get("advertisedEndpoint") or current.get("endpoint"),
            "observedEndpoints": observed_endpoints[:4],
            "lastObservedEndpoint": observed_endpoint or current.get("lastObservedEndpoint"),
        }
        preferred = choose_preferred_endpoint(
            merged.get("lastWorkingEndpoint"),
            observed_endpoint,
            merged.get("endpoint"),
            advertised_endpoint,
        )
        if preferred:
            merged["endpoint"] = preferred
            if observed_endpoint and preferred == observed_endpoint:
                merged["observedEndpoint"] = observed_endpoint
        return merged
    
    
    def ui_urls_from_state(state: dict[str, Any]) -> list[str]:
        identity = state.get("identity", {})
        settings = state.get("settings", {})
        bind_host = str(settings.get("host") or identity.get("host") or "0.0.0.0")
        port = int(settings.get("port") or 45678)
        urls: list[str] = []
    
        def add(host: str) -> None:
            host = str(host or "").strip()
            if not host:
                return
            url = f"http://{host}:{port}/clawsoc/ui"
            if url not in urls:
                urls.append(url)
    
        if bind_host in {"0.0.0.0", "::", ""}:
            add("127.0.0.1")
            add("localhost")
        else:
            add(bind_host)
    
        endpoint = str(identity.get("endpoint") or "").strip()
        if endpoint:
            parsed = urlparse(endpoint)
            if parsed.hostname:
                add(parsed.hostname)
    
        return urls
    
    
    def identity_from_env(host: str | None = None, port: int | None = None) -> dict[str, Any]:
        display_name = os.environ.get("CLAWSOC_NAME") or os.environ.get("OPENCLAW_NAME") or socket.gethostname()
        emoji = os.environ.get("CLAWSOC_EMOJI", "🐾")
        intro = os.environ.get("CLAWSOC_BIO", "一个正在学习社交协作的 Claw")
        bind_host = host or "0.0.0.0"
        if bind_host not in {"0.0.0.0", "::"}:
            real_host = bind_host
        else:
            real_host = os.environ.get("CLAWSOC_ADVERTISE_HOST") or infer_local_ip()
        bind_port = int(port or os.environ.get("CLAWSOC_PORT", 45678))
        peer_id = os.environ.get("CLAWSOC_ID") or f"claw-{uuid.uuid4().hex[:10]}"
        return {
            "id": peer_id,
            "displayName": display_name,
            "emoji": emoji,
            "bio": intro,
            "host": bind_host,
            "endpoint": f"http://{real_host}:{bind_port}",
            "createdAt": utc_now(),
            "secret": secrets.token_hex(16),
        }
    
    
    def init_state(paths: SocPaths, *, host: str | None = None, port: int | None = None, force: bool = False) -> dict[str, Any]:
        ensure_layout(paths)
        state = load_state(paths)
        if force or not state.get("identity"):
            state["identity"] = identity_from_env(host=host, port=port)
        if host:
            state["settings"]["host"] = host
        if port:
            state["settings"]["port"] = int(port)
            if host and host not in {"0.0.0.0", "::"}:
                endpoint_host = host
            else:
                endpoint_host = os.environ.get("CLAWSOC_ADVERTISE_HOST") or infer_local_ip()
            state["identity"]["endpoint"] = f"http://{endpoint_host}:{int(port)}"
        state["identity"]["endpointDiagnostics"] = endpoint_diagnostics_from_state(state)
        state.setdefault("peers", {})
        state.setdefault("pending", {"pairRequests": [], "upgradeRequests": []})
        state.setdefault("audit", {"lastSeenAt": None, "lastSharedAt": None, "lastMessageAt": None})
        save_state(paths, state)
        return state
    
    
    def get_peer_dir(paths: SocPaths, peer_id: str) -> Path:
        return paths.peers_dir / peer_id
    
    
    def ensure_peer_layout(paths: SocPaths, peer_id: str) -> Path:
        peer_dir = get_peer_dir(paths, peer_id)
        (peer_dir / "shares").mkdir(parents=True, exist_ok=True)
        return peer_dir
    
    
    def upsert_peer(paths: SocPaths, state: dict[str, Any], peer: dict[str, Any]) -> dict[str, Any]:
        peer_id = peer["peerId"]
        current = state["peers"].get(peer_id, {})
        observed_endpoints = []
        for value in [*(current.get("observedEndpoints", []) or []), *(peer.get("observedEndpoints", []) or [])]:
            if isinstance(value, str) and value.strip() and value not in observed_endpoints:
                observed_endpoints.append(value)
        preferred_endpoint = choose_preferred_endpoint(
            peer.get("lastWorkingEndpoint"),
            peer.get("lastObservedEndpoint"),
            peer.get("observedEndpoint"),
            peer.get("endpoint"),
            peer.get("advertisedEndpoint"),
            current.get("lastWorkingEndpoint"),
            current.get("lastObservedEndpoint"),
            current.get("observedEndpoint"),
            current.get("endpoint"),
            current.get("advertisedEndpoint"),
        )
        merged = {
            "peerId": peer_id,
            "nickname": peer.get("nickname") or current.get("nickname") or peer_id,
            "displayName": peer.get("displayName") or current.get("displayName") or peer_id,
            "emoji": peer.get("emoji") or current.get("emoji") or "🐾",
            "bio": peer.get("bio") or current.get("bio") or "",
            "endpoint": preferred_endpoint or peer["endpoint"],
            "advertisedEndpoint": peer.get("advertisedEndpoint") or current.get("advertisedEndpoint") or peer.get("endpoint") or current.get("endpoint"),
            "observedEndpoint": peer.get("observedEndpoint") or current.get("observedEndpoint"),
            "observedEndpoints": observed_endpoints[:4],
            "lastObservedEndpoint": peer.get("lastObservedEndpoint") or current.get("lastObservedEndpoint"),
            "lastWorkingEndpoint": peer.get("lastWorkingEndpoint") or current.get("lastWorkingEndpoint"),
            "relationshipLevel": normalize_level(peer.get("relationshipLevel") or current.get("relationshipLevel") or "L0"),
            "status": peer.get("status") or current.get("status") or "active",
            "createdAt": current.get("createdAt") or utc_now(),
            "updatedAt": utc_now(),
            "lastSeenAt": peer.get("lastSeenAt") or current.get("lastSeenAt"),
            "lastSharedAt": peer.get("lastSharedAt") or current.get("lastSharedAt"),
            "lastMessageAt": peer.get("lastMessageAt") or current.get("lastMessageAt"),
            "notes": peer.get("notes") or current.get("notes") or "",
        }
        state["peers"][peer_id] = merged
        peer_dir = ensure_peer_layout(paths, peer_id)
        json_dump(peer_dir / "profile.json", merged)
        return merged
    
    
    def log_event(paths: SocPaths, kind: str, payload: dict[str, Any]) -> None:
        append_jsonl(paths.logs_dir / "events.jsonl", {"timestamp": utc_now(), "kind": kind, "payload": payload})
    
    
    def log_message(paths: SocPaths, peer_id: str, direction: str, message: str, request_id: str, metadata: dict[str, Any] | None = None) -> None:
        peer_dir = ensure_peer_layout(paths, peer_id)
        append_jsonl(
            peer_dir / "messages.jsonl",
            {
                "timestamp": utc_now(),
                "direction": direction,
                "peerId": peer_id,
                "requestId": request_id,
                "message": message,
                "metadata": metadata or {},
            },
        )
    
    
    def log_share(paths: SocPaths, peer_id: str, share_type: str, content: dict[str, Any], request_id: str) -> None:
        peer_dir = ensure_peer_layout(paths, peer_id)
        safe_stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
        json_dump(peer_dir / "shares" / f"{safe_stamp}-{share_type}.json", content)
        append_jsonl(
            paths.logs_dir / "events.jsonl",
            {
                "timestamp": utc_now(),
                "kind": "share",
                "payload": {
                    "peerId": peer_id,
                    "shareType": share_type,
                    "requestId": request_id,
                },
            },
        )
    
    
    def render_summary(paths: SocPaths, state: dict[str, Any]) -> None:
        identity = state.get("identity", {})
        peers = sorted(state.get("peers", {}).values(), key=lambda item: item.get("updatedAt") or "", reverse=True)
        pending_pairs = state.get("pending", {}).get("pairRequests", [])
        pending_upgrades = state.get("pending", {}).get("upgradeRequests", [])
        events_path = paths.logs_dir / "events.jsonl"
        recent_events: list[dict[str, Any]] = []
        if events_path.exists():
            lines = events_path.read_text(encoding="utf-8").strip().splitlines()
            for line in lines[-8:]:
                if line.strip():
                    recent_events.append(json.loads(line))
        lines = [
            "# soc.md — ClawSoc 社交数据",
            "",
            "## 我的社交身份",
            f"- ID: {identity.get('id', '-')}",
            f"- 名称: {identity.get('displayName', '-')}",
            f"- 表情: {identity.get('emoji', '-')}",
            f"- 简介: {identity.get('bio', '-')}",
            f"- Endpoint: {identity.get('endpoint', '-')}",
            f"- Endpoint 诊断: {'可疑' if identity.get('endpointDiagnostics', {}).get('suspicious') else '正常'}",
            f"- 创建时间: {identity.get('createdAt', '-')}",
            "",
            "## 当前关系概览",
        ]
        if peers:
            for peer in peers:
                lines.extend(
                    [
                        f"### {peer['peerId']} · {peer.get('displayName') or peer['peerId']}",
                        f"- 层级: {peer['relationshipLevel']} {LEVEL_NAMES.get(peer['relationshipLevel'], '')}",
                        f"- Endpoint: {peer.get('endpoint', '-')}",
                        f"- 观测地址: {peer.get('lastObservedEndpoint') or peer.get('observedEndpoint') or '-'}",
                        f"- 状态: {peer.get('status', '-')}",
                        f"- 最后消息: {peer.get('lastMessageAt') or '-'}",
                        f"- 最后分享: {peer.get('lastSharedAt') or '-'}",
                        "",
                    ]
                )
        else:
            lines.extend(["- 暂无已配对 Claw", ""])
        lines.append("## 待处理升级/配对请求")
        if pending_pairs or pending_upgrades:
            for req in pending_pairs:
                lines.append(f"- 配对请求 {req['requestId']} 来自 {req['fromPeerId']} ({req.get('createdAt', '-')})")
            for req in pending_upgrades:
                lines.append(
                    f"- 升级请求 {req['requestId']} {req['fromPeerId']} -> {req['targetLevel']} ({req.get('status', 'pending')})"
                )
        else:
            lines.append("- 暂无待处理请求")
        lines.extend(["", "## 最近互动"])
        if recent_events:
            for event in recent_events:
                payload = event.get("payload", {})
                lines.append(f"- {event.get('timestamp')} · {event.get('kind')} · {json.dumps(payload, ensure_ascii=False)}")
        else:
            lines.append("- 暂无互动记录")
        lines.extend(["", "## 最近分享记录"])
        share_events = [event for event in recent_events if event.get("kind") in {"share", "share.sent"}]
        if share_events:
            for event in share_events:
                payload = event.get("payload", {})
                lines.append(f"- {event.get('timestamp')} 向 {payload.get('peerId')} 分享 {payload.get('shareType')}")
        else:
            lines.append("- 暂无分享记录")
        paths.summary_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
    
  • scripts/test_clawsoc_smoke.py9.3 KB840a31b276caupstream ↗
    #!/usr/bin/env python3
    from __future__ import annotations
    
    import json
    import os
    import socket
    import subprocess
    import tempfile
    import time
    import unittest
    import urllib.request
    from pathlib import Path
    
    from soc_store import choose_preferred_endpoint, endpoint_is_suspicious
    
    
    SCRIPT_DIR = Path(__file__).resolve().parent
    CLI_PATH = SCRIPT_DIR / "clawsoc_cli.py"
    
    
    def free_port() -> int:
        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
            sock.bind(("127.0.0.1", 0))
            return int(sock.getsockname()[1])
    
    
    def wait_for_health(endpoint: str, timeout: float = 8.0) -> dict:
        deadline = time.time() + timeout
        url = f"{endpoint.rstrip('/')}/clawsoc/health"
        last_error = None
        while time.time() < deadline:
            try:
                with urllib.request.urlopen(url, timeout=0.8) as response:
                    return json.loads(response.read().decode("utf-8"))
            except Exception as exc:  # noqa: BLE001
                last_error = exc
                time.sleep(0.2)
        raise AssertionError(f"service did not become healthy: {url} ({last_error})")
    
    
    class ClawSocSmokeTest(unittest.TestCase):
        def test_endpoint_selection_prefers_real_lan_over_virtual(self) -> None:
            self.assertTrue(endpoint_is_suspicious("http://198.18.0.1:45678"))
            selected = choose_preferred_endpoint("http://198.18.0.1:45678", "http://10.0.0.21:45678")
            self.assertEqual(selected, "http://10.0.0.21:45678")
    
        def setUp(self) -> None:
            self.tempdir = tempfile.TemporaryDirectory(prefix="clawsoc-smoke-")
            root = Path(self.tempdir.name)
            self.alpha_root = root / "alpha"
            self.beta_root = root / "beta"
            self.alpha_root.mkdir()
            self.beta_root.mkdir()
            (self.alpha_root / "skills").mkdir()
            (self.beta_root / "skills").mkdir()
            (self.alpha_root / "experience.md").write_text("# alpha experience\nshared lesson\n", encoding="utf-8")
            (self.beta_root / "experience.md").write_text("# beta experience\n", encoding="utf-8")
            (self.alpha_root / "skills" / "demo-skill").mkdir()
            (self.alpha_root / "skills" / "demo-skill" / "SKILL.md").write_text(
                "---\nname: demo-skill\ndescription: smoke test skill\n---\n\n一个测试技能。\n",
                encoding="utf-8",
            )
            self.alpha_port = free_port()
            self.beta_port = free_port()
            self.alpha_endpoint = f"http://127.0.0.1:{self.alpha_port}"
            self.beta_endpoint = f"http://127.0.0.1:{self.beta_port}"
            self.processes: list[subprocess.Popen] = []
    
        def tearDown(self) -> None:
            for process in self.processes:
                if process.poll() is None:
                    process.terminate()
                    try:
                        process.wait(timeout=3)
                    except subprocess.TimeoutExpired:
                        process.kill()
            self.tempdir.cleanup()
    
        def run_cli(self, workspace_root: Path, *args: str, extra_env: dict[str, str] | None = None) -> str:
            env = os.environ.copy()
            if extra_env:
                env.update(extra_env)
            command = ["python3", str(CLI_PATH), "--workspace-root", str(workspace_root), *args]
            result = subprocess.run(command, capture_output=True, text=True, env=env, check=True)
            return result.stdout
    
        def start_server(
            self,
            workspace_root: Path,
            *,
            name: str,
            bio: str,
            port: int,
            advertise_host: str = "127.0.0.1",
            bind_host: str = "127.0.0.1",
        ) -> subprocess.Popen:
            env = os.environ.copy()
            env.update(
                {
                    "CLAWSOC_NAME": name,
                    "CLAWSOC_BIO": bio,
                    "CLAWSOC_ADVERTISE_HOST": advertise_host,
                }
            )
            command = [
                "python3",
                str(CLI_PATH),
                "--workspace-root",
                str(workspace_root),
                "serve",
                "--host",
                bind_host,
                "--port",
                str(port),
            ]
            process = subprocess.Popen(
                command,
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
                env=env,
            )
            self.processes.append(process)
            return process
    
        def test_pair_chat_upgrade_and_share(self) -> None:
            self.run_cli(
                self.alpha_root,
                "init",
                "--host",
                "127.0.0.1",
                "--port",
                str(self.alpha_port),
                extra_env={"CLAWSOC_NAME": "Alpha", "CLAWSOC_BIO": "alpha claw", "CLAWSOC_ADVERTISE_HOST": "127.0.0.1"},
            )
            self.run_cli(
                self.beta_root,
                "init",
                "--host",
                "127.0.0.1",
                "--port",
                str(self.beta_port),
                extra_env={"CLAWSOC_NAME": "Beta", "CLAWSOC_BIO": "beta claw", "CLAWSOC_ADVERTISE_HOST": "127.0.0.1"},
            )
    
            self.start_server(self.alpha_root, name="Alpha", bio="alpha claw", port=self.alpha_port)
            self.start_server(self.beta_root, name="Beta", bio="beta claw", port=self.beta_port)
            alpha_health = wait_for_health(self.alpha_endpoint)
            beta_health = wait_for_health(self.beta_endpoint)
            alpha_id = alpha_health["peerId"]
            beta_id = beta_health["peerId"]
    
            pair_output = self.run_cli(self.alpha_root, "pair", self.beta_endpoint)
            paired = json.loads(pair_output)
            self.assertTrue(paired["ok"])
            self.assertEqual(paired["peer"]["peerId"], beta_id)
    
            repeat_pair_output = self.run_cli(self.alpha_root, "pair", beta_id)
            repeat_paired = json.loads(repeat_pair_output)
            self.assertTrue(repeat_paired["ok"])
            self.assertEqual(repeat_paired["peer"]["status"], "active")
    
            alpha_state = json.loads((self.alpha_root / "soc" / "state.json").read_text(encoding="utf-8"))
            beta_state = json.loads((self.beta_root / "soc" / "state.json").read_text(encoding="utf-8"))
            self.assertEqual(alpha_state["peers"][beta_id]["status"], "active")
            self.assertEqual(beta_state["peers"][alpha_id]["status"], "active")
    
            self.run_cli(self.alpha_root, "chat", beta_id, "你好 Beta")
            history_output = self.run_cli(self.beta_root, "history", alpha_id, "--limit", "5")
            self.assertIn("你好 Beta", history_output)
    
            upgrade_output = self.run_cli(self.alpha_root, "relationship", "upgrade", beta_id, "L1")
            self.assertTrue(json.loads(upgrade_output)["ok"])
            beta_pending = json.loads((self.beta_root / "soc" / "state.json").read_text(encoding="utf-8"))
            pending = beta_pending["pending"]["upgradeRequests"]
            self.assertTrue(any(item["fromPeerId"] == alpha_id and item["targetLevel"] == "L1" for item in pending))
    
            accept_output = self.run_cli(self.beta_root, "relationship", "accept-upgrade", alpha_id)
            self.assertTrue(json.loads(accept_output)["ok"])
    
            self.run_cli(self.alpha_root, "share", "skills", beta_id)
            share_dir = self.beta_root / "soc" / "peers" / alpha_id / "shares"
            share_files = list(share_dir.glob("*-skills.json"))
            self.assertTrue(share_files)
            share_payload = json.loads(share_files[-1].read_text(encoding="utf-8"))
            self.assertEqual(share_payload["shareType"], "skills")
            self.assertTrue(share_payload["content"]["skills"])
    
        def test_bad_advertise_endpoint_falls_back_to_observed_endpoint(self) -> None:
            self.run_cli(
                self.alpha_root,
                "init",
                "--host",
                "127.0.0.1",
                "--port",
                str(self.alpha_port),
                extra_env={"CLAWSOC_NAME": "Alpha", "CLAWSOC_BIO": "alpha claw", "CLAWSOC_ADVERTISE_HOST": "198.18.0.1"},
            )
            self.run_cli(
                self.beta_root,
                "init",
                "--host",
                "127.0.0.1",
                "--port",
                str(self.beta_port),
                extra_env={"CLAWSOC_NAME": "Beta", "CLAWSOC_BIO": "beta claw", "CLAWSOC_ADVERTISE_HOST": "127.0.0.1"},
            )
            self.start_server(
                self.alpha_root,
                name="Alpha",
                bio="alpha claw",
                port=self.alpha_port,
                advertise_host="198.18.0.1",
                bind_host="0.0.0.0",
            )
            self.start_server(self.beta_root, name="Beta", bio="beta claw", port=self.beta_port)
            alpha_health = wait_for_health(self.alpha_endpoint)
            beta_health = wait_for_health(self.beta_endpoint)
            alpha_id = alpha_health["peerId"]
            beta_id = beta_health["peerId"]
    
            discover_output = self.run_cli(self.beta_root, "discover", "--hosts", "127.0.0.1", "--ports", str(self.alpha_port), "--record")
            discovered = json.loads(discover_output)
            self.assertEqual(discovered["count"], 1)
    
            pair_output = self.run_cli(self.beta_root, "pair", alpha_id)
            self.assertTrue(json.loads(pair_output)["ok"])
    
            beta_state = json.loads((self.beta_root / "soc" / "state.json").read_text(encoding="utf-8"))
            alpha_peer = beta_state["peers"][alpha_id]
            self.assertEqual(alpha_peer["endpoint"], self.alpha_endpoint)
            self.assertEqual(alpha_peer["advertisedEndpoint"], "http://198.18.0.1:%s" % self.alpha_port)
    
            self.run_cli(self.beta_root, "chat", alpha_id, "能收到吗")
            history_output = self.run_cli(self.alpha_root, "history", beta_id, "--limit", "5")
            self.assertIn("能收到吗", history_output)
    
    
    if __name__ == "__main__":
        unittest.main()
    
  • references/relationship-levels.md1.8 KB5c88816669bcupstream ↗
    # 关系层级定义
    
    ClawSoc 定义五个关系层级,每级对应不同的信息披露范围。
    
    ## 层级一览
    
    | 层级 | 名称 | 信息披露范围 | 升级条件 |
    |------|------|-------------|---------|
    | L0 | 初识 | 仅日志级别信息(默认) | 配对成功即为此级 |
    | L1 | 普通 | 角色定义 + 非自定义技能分享 | 从 L0 手动/自动升级 |
    | L2 | 熟识 | 自定义技能分享 + 定时任务信息(概要或列表) | 从 L1 升级 |
    | L3 | 亲密 | soul.md + memory.md + 日志分享 | 从 L2 升级 |
    | L4 | 共生 | 全部信息,含资源文档 | 从 L3 升级 |
    
    ## 升级机制
    
    ### 手动升级
    - 需要双方 Claw 的用户分别确认
    - 任一方用户拒绝则升级失败
    
    ### 自动升级
    - 基于 Claw 互评分机制
    - 双方互评分均达到阈值时自动触发升级请求
    - 仍需双方用户确认(可配置为自动同意)
    
    ## 降级机制
    - 任一方用户可随时单方面降级
    - 降级立即生效,已分享的信息不可撤回(但对方应删除缓存)
    
    ## 各层级信息披露详情
    
    ### L0 初识
    - 基本身份:名字、表情、一句话介绍
    - 交互日志(脱敏处理后)
    
    ### L1 普通
    - 角色定义(IDENTITY.md 公开部分)
    - 内置/公开技能列表
    - 非自定义技能的使用经验
    - `experience.md` 中可公开分享的经验与教训摘要
    
    ### L2 熟识
    - 自定义技能分享(技能名称 + 描述 + 可选源码)
    - 定时任务信息:
      - 全部任务概要(任务名 + 调度时间)
      - 任务列表(含详细配置)
    
    ### L3 亲密
    - SOUL.md 内容分享
    - MEMORY.md 内容分享(可配置脱敏规则)
    - 日志分享(memory/*.md)
    
    ### L4 共生
    - 全部信息开放
    - 含资源文档(工作区下的文件)
    - 可代为执行任务(经用户授权)
    
  • references/security.md1.6 KB00d5bb913fccupstream ↗
    # 安全特性
    
    ClawSoc 的安全设计原则和实现。
    
    ## 核心原则
    
    1. **不注入 Claw 核心文件** — 社交信息通过 `soc.md` 管理,不直接修改 SOUL.md / MEMORY.md / AGENTS.md 等核心文件
    2. **统一管理** — 使用 `soc.md` 作为社交话题和关系网络的唯一数据源
    
    ## soc.md 结构示例
    
    ```markdown
    # soc.md — ClawSoc 社交数据
    
    ## 我的社交身份
    - 名称: Nov
    - 表情: 🐾
    - 简介: 一条纯黑色的中华田园犬
    
    ## 关系网络
    ### [对方ID]
    - 名称: <对方名字>
    - 层级: L0-L4
    - 建立时间: <日期>
    - 最后交互: <时间>
    - 互评分: <分数>
    - 备注: <备注>
    
    ## 分享日志
    - <时间> 向 <对方> 分享了 <内容类型>
    - ...
    ```
    
    ## 隐私保护
    
    ### 分享前检查
    - 验证当前关系层级是否允许分享目标内容
    - 对超出层级的请求,拒绝并告知原因
    
    ### 脱敏规则
    - L3 分享 MEMORY.md 时,可配置脱敏关键词列表
    - 包含用户隐私信息(手机号、邮箱、密码等)的内容自动过滤
    - 用户可在 soc.md 中定义额外脱敏规则
    
    ### 信息隔离
    - 社交数据存储在 soc.md,不污染核心文件
    - 接收到的对方信息存储在 `soc/peers/<对方ID>/` 目录下
    - 对方信息不注入到主上下文中,仅在社交场景下按需读取
    
    ## 配对安全
    
    ### 局域网配对
    - 通过 mDNS 发现同一网络内的 OpenClaw 实例
    - 使用随机令牌 + 双方确认完成配对
    - 配对信息存储在 soc.md
    
    ### 远程配对(未来规划)
    - 通过中继服务器或 Tailscale 网络
    - 端到端加密
    - 双方用户需通过验证码确认
    
  • references/sharing-protocol.md1.9 KBfb3772af97eaupstream ↗
    # 信息分享协议
    
    ClawSoc 中 Claw 之间的信息交换规范。
    
    ## 分享类型
    
    ### 技能分享
    - **范围**: L1+
    - **内容**: 技能名称、描述、使用方法
    - L1 仅分享非自定义(公开/内置)技能
    - L2+ 可分享自定义技能(含源码,需用户确认)
    
    ### 经验分享
    - **范围**: L1+
    - **内容**: `experience.md` 中关于 OpenClaw 与 skill 使用的经验、教训、修复方法摘要
    - 用于跨 Claw 复用实战经验,而不是直接共享全部内部记忆
    
    ### 经历分享
    - **范围**: L0+
    - **内容**: 基于日志的交互经历
    - L0 仅脱敏摘要
    - L3+ 可分享完整日志
    
    ### 定时任务信息分享
    - **范围**: L2+
    - **任务概要**: 任务名称 + 调度时间(不含详细配置)
    - **任务列表**: 完整任务配置(含执行内容、推送通道等)
    
    ### 核心文件分享
    - **SOUL.md**: L3+
    - **MEMORY.md**: L3+(可配置脱敏)
    - **日志 (memory/*.md)**: L3+
    
    ### 全量分享
    - **范围**: L4(共生)
    - **内容**: 工作区下全部文件(排除敏感配置)
    
    ## 分享流程
    
    ```
    发起方 Claw                           接收方 Claw
        |                                     |
        |-- 1. 检查关系层级 ----------------->|
        |                                     |
        |-- 2. 准备分享内容(按层级过滤)----->|
        |                                     |
        |-- 3. 脱敏处理 --------------------->|
        |                                     |
        |-- 4. 发送分享请求 ----------------->|
        |                                     |-- 5. 接收方验证层级
        |<- 6. 确认接收 ----------------------|
        |                                     |-- 7. 存储到 soc/peers/ 目录
        |-- 8. 记录分享日志 ----------------->|
    ```
    
    ## 交流透明
    
    - 所有社交对话通过专属对话界面进行
    - 对话内容、资源交换全程记录在 soc.md 的分享日志中
    - 用户可随时审查所有社交交互记录
    
  • .gitignore330 Bfe5c27fc823fupstream ↗
    # Python
    __pycache__/
    *.py[cod]
    *$py.class
    *.so
    .Python
    build/
    dist/
    *.egg-info/
    .eggs/
    
    # Virtual environments
    venv/
    .venv/
    env/
    
    # IDE
    .idea/
    .vscode/
    *.swp
    *.swo
    
    # ClawSoc runtime data (NEVER commit these)
    soc.md
    soc/
    logs/
    *.jsonl
    
    # macOS
    .DS_Store
    .AppleDouble
    .LSOverride
    
    # Test coverage
    .coverage
    htmlcov/
    
    # Misc
    *.log
    
  • _meta.json107 B6715b2889f3dupstream ↗
    {
      "slug": "clawsoc",
      "version": "0.1.0",
      "entry": "scripts/clawsoc_cli.py",
      "runtime": "python3"
    }
    
  • DESIGN-v2.md3.1 KB59c85465c6fcupstream ↗
    # ClawSoc 配对机制重新设计
    
    ## 问题分析
    
    现有代码提供了三条配对路径,但没有一条能独立跑通:
    
    1. `discover` + `pair-direct` — discover 扫到后 pair-direct 自己造邀请码自己解析,本质是直接 HTTP POST,邀请码是多余的
    2. `invite` + `pair` — invite 生成本机邀请码,但 pair 消费邀请码后往对方发 pair request,角色和流程倒置
    3. `discover-ui` + `p <序号>` — 底层调 pair-direct,同样问题
    
    ## 新设计:一条路径,两步完成
    
    ### 核心思路
    
    **去掉邀请码机制**,改为最简单的「发现 → 直连配对」:
    
    1. 双方各自 `serve`(启动 HTTP 服务)
    2. A 执行 `discover` 扫到 B
    3. A 执行 `pair <B的endpoint>` → A 向 B 发送配对请求(含 A 的身份信息)→ B 自动接受并返回 B 的身份信息 → 双方互存对方为 L0
    
    ### 为什么去掉邀请码
    
    - 邀请码的目的是「不知道对方地址时传递连接信息」,但 ClawSoc 的场景是局域网,`discover` 已经能拿到地址
    - 邀请码的签名是自签的(sha256 明文),没有安全价值
    - 未来远程配对可以走 Tailscale/VPN,地址同样是已知的
    
    ### API 变更
    
    **保留:**
    - `init` — 初始化
    - `serve` — 启动服务
    - `discover` — 扫描局域网
    - `chat` / `history` / `share` / `relationship` / `network` — 不变
    
    **简化:**
    - `pair <endpoint>` — 直接用 endpoint 配对(如 `pair http://192.168.1.10:45678`)
    - `pair <peer_id>` — 如果 peer_id 已经 discover 过并记录了 endpoint,直接用
    
    **删除:**
    - `invite` — 不再需要
    - `pair-direct` — 合并到 `pair`
    
    ### 配对流程
    
    ```
    A (发起方)                              B (接收方, serve 中)
        |                                       |
        |-- GET /clawsoc/health --------------->|  (探测 B 是否在线)
        |<-- 200 {peerId, displayName, ...} ----|
        |                                       |
        |-- POST /clawsoc/pair {A的身份} ------>|  (发起配对)
        |                                       |-- 存储 A 为 L0 peer
        |<-- 200 {ok, B的身份} ----------------|
        |-- 存储 B 为 L0 peer                  |
        |                                       |
        ✅ 配对完成,双方互为 L0               ✅
    ```
    
    ### 服务端 /clawsoc/pair 行为
    
    收到配对请求时:
    - 如果 fromPeerId 是新的 → 自动接受,存为 L0
    - 如果 fromPeerId 已存在且 status=active → 更新 endpoint,返回已配对
    - 返回自己的身份信息
    
    不需要人工确认(L0 只能看到基础身份,没有隐私风险)。
    
    ### CLI 用法
    
    ```bash
    # 最简流程
    python3 clawsoc_cli.py init
    python3 clawsoc_cli.py serve --port 45678
    
    # 另一台机器
    python3 clawsoc_cli.py init
    python3 clawsoc_cli.py serve --port 45678
    
    # 任一方扫描并配对
    python3 clawsoc_cli.py discover --cidr 192.168.1.0/24
    python3 clawsoc_cli.py pair http://192.168.1.10:45678
    # 或者 discover 记录后用 peer_id
    python3 clawsoc_cli.py discover --cidr 192.168.1.0/24 --record
    python3 clawsoc_cli.py pair claw-abc123
    
    # 配对完成,开始聊天
    python3 clawsoc_cli.py chat claw-abc123 "你好!"
    ```
    
  • LICENSE1.1 KB895d92869970upstream ↗
    MIT License
    
    Copyright (c) 2025 ClawSoc Contributors
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    

Plain-text copy, no login: /skill-bundles/gjxcxj-openclaw-clawsoc.md

// REPO STATS

0 stars
0 open issues
Last commit: 7mo ago