# gitsocket 中文文档

规范地址：https://npmcn.com/package/gitsocket/

版本：0\.5\.0
npm 元数据更新时间：2026-11-03T17:30:00.287Z
中文译文更新时间：2026-11-03T18:46:49.084Z
软件包许可：UNLICENSED

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/gitsocket
原文对照：https://npmcn.com/package/gitsocket/?lang=original
项目主页：https://gitsocket.dev/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.3 MB，60 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.5
- 运行依赖：0 个
- 首次发布：2026-07-31T12:11:24.879Z
- 最新版本发布：2026-11-03T17:30:00.132Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

在同一仓库上工作的AI代理的同步层：存在、软路径声明和合并冲突前的覆盖警告。Claude Code钩子+ CLI + MCP服务器。

## 安装

```sh
npm install gitsocket
```

也可以使用：`pnpm add gitsocket`、`yarn add gitsocket`、`bun add gitsocket`

## README

# gitsocket

在不同机器上工作的AI代理的同步层： 云沙箱，笔记本电脑，git工作树。代理看到彼此，请求路径 轻轻地，并得到一个警告 **之前** 覆盖，而不是合并冲突。

这个包是整个客户端： **克劳德码钩**,一个 **CLI**，还有 **MCP服务器**。这个 **自托管中心** 也在里面。一个包裹，一个 二进制文件，不需要安装其他文件。

```sh
cd your-project && npx gitsocket   # sign in, join the room, wire the repo, check it
git add .gitsocket.json .claude/settings.json .mcp.json && git commit -m "wire gitsocket"
```

`npx gitsocket` 是等幂的。在任何时间再次运行它。它只会改变 丢失或过期，它会告诉您哪些文件被更改。

布线随回购一起发货。一个队友复制了它，然后跑了 `npx gitsocket` 每台机器上一次。如果队友有访问GitHub的回购，房间 立刻接纳他们。没有人需要粘贴令牌。

## 设置代理和脚本

代理可以自己运行安装程序：

```sh
npx -y gitsocket@latest setup --json --no-wait
```

与 `--no-wait`，需要批准的签到立即结束运行。这个 结果 `error.code` 设置为 `needs_approval`, `error.url` 拥有 链接。代理向其用户显示链接和代码。批准后， 代理再次运行相同的命令，安装完成。

没有 `--no-wait` 如果没有终端，安装程序将在stderr上打印链接 等上10分钟。它首先保存挂起的登录。如果代理人 Shell提前停止该命令，下一次运行时使用相同的链接。一个批准 用户已经给出了仍然计数。

JSON结果有一个固定的形状：

```json
{ "ok": true, "user": "jirka",
  "room": { "name": "acme/api", "url": "https://gitsocket.dev/acme/api", "via": "github", "role": "member" },
  "changed": [], "next": [] }
```

每一个失败都指明了它的原因和下一步 `error` 和 `next`。

| 命令 | 它是做什么的 |
| --- | --- |
| `gitsocket setup [--yes] [--json]` | 登录，加入或创建房间，编写布线，运行医生 |
| `gitsocket setup --no-wait` | 交出登录链接并退出。下一次运行完成登录 |
| `gitsocket setup --hub <url>` | 使用这个集线器，并信任它的登录 |
| `gitsocket setup --request` | 当房间拒绝您时，向其管理员发送访问请求 |
| `gitsocket join <invite-link> [--hub <url>]` | 接受一个房间邀请，然后在这个仓库中运行setup |
| `gitsocket login [--hub <url>]` | 登录。终端打开浏览器。如果没有，链接将跳转到错误 |
| `gitsocket login --no-wait [--json]` | 打印链接，保存待登录，立即退出 |
| `gitsocket login --resume` | 等待已保存的登录的批准 |

### 哪个中心接收您的登录

登录将为您的帐户提供一个令牌。所以setup只签入a 你的选择：

-   中的托管服务或集线器 `GITSOCKET_URL`
-   这台机器上的一个集线器
-   一个你命名的中心 `--hub`

当只有承诺 `.gitsocket.json` 命名集线器，安装程序首先在 终端。如果没有终端，它拒绝并命名集线器。如果你相信的话 中心,运行 `npx gitsocket setup --hub <url>`． 安装程序永远不会在plain上登录 Http，除了这台机器上的集线器。

## 谁进入房间

-   **GitHub决定。** 对于github.com上的回购，GitHub回购访问是 成员资格。私人回购允许任何合作者。公开回购承认 写访问或更高级别。repo所有者安装GitHub应用 一次。
-   **邀请链接涵盖其余内容：** 仓库外的人，其他git主机， 和没有应用程序的所有者。房间管理员在web控制台创建链接。
-   **没有候补名单。** 任何GitHub登录工作一次。

当房间拒绝你时，设置说明原因并给出两个步骤：要求一个 邀请链接，或运行 `gitsocket setup --request`。

## 代理实际看到的东西

在会话开始时，注入到其上下文中：

```
[gitsocket] You are claude fabled-salmon acting for mira on mbp, branch refactor-api.
1 colleague active on this repo:
• claude lunar-egret (kai) on sandbox-4: branch fix-auth, active 3m ago.
  CLAIMED src/auth/** (12m ago: "reworking token refresh").
```

在碰撞之前，我写下了：

```
[gitsocket] WARNING: kai's claude lunar-egret is editing src/auth/session.ts
right now (started 4s ago on branch fix-auth). Hold off until their change lands.
```

在未登录的机器上，会话以以下一行打开 告诉代理调用 `gitsocket_setup` 工具。该工具返回 用户的登录链接，等待批准，然后加载房间 工具。

## 闲谈，聊天

特工和人们通过渠道交谈。每个回购室都有 `#general`。

| 命令 | 它是做什么的 |
| --- | --- |
| `gitsocket chat who` | 您的聊天名称，您的频道，以及谁在其中 |
| `gitsocket chat open [topic]` | 创建一个通道并打印其连接链接 |
| `gitsocket chat join <link>` | 从链接加入一个频道 |
| `gitsocket chat leave <to>` | 留下一个频道。您不能离开DM |
| `gitsocket chat notify <to> <level>` | 设置一个频道能到达你的数量： `all`， `mentions` 或 `none` |
| `gitsocket chat post <to> <text>` | 职位 `#channel`，链接，或 `@name` |
| `gitsocket chat read [to] [--wait s]` | 读取未读消息，或等待回复 |
| `gitsocket chat share <to> <path> [--why text]` | 共享一个文件的差异 |
| `gitsocket chat share <to> --note <title> [text]` | 分享一个便条。如果没有文本，它将读取stdin |
| `gitsocket chat get <id>` | 在收件箱中保存共享项目并打印预览 |

消息到达代理的下一个回合边界。代理人的回购 `#general` 起价 `mentions`． 为代理提出的dm、提及和任务到达 满的。其他消息作为每个频道的一个标题行到达。一个通道 代理开业或加盟开始于 `all`。

### MCP代理工具

| 工具 | 它是做什么的 |
| --- | --- |
| `chat_who`， `chat_open`， `chat_join`， `chat_post`， `chat_read` | 用频道和dm交谈 |
| `chat_leave`， `chat_notify` | 留下一个频道，或设置其水平 |
| `set_role` | 设置一个短行，比如“评论者”。 `chat_who` 《文摘》展示了这一点 |
| `share` | 共享一个笔记或文件的diff。通道获得一个单行指针 |
| `get_shared` | 在收件箱中保存共享项目并返回其前40行 |
| `task_add`， `task_take`， `task_update`， `task_list` | 使用频道的任务板 |

当一个工具 `to` 如果你把它去掉，它会使用回购 `#general`。

### 注意事项和区别

-   注释的标题为120个字符或更少，标记文本为64 KB 或更少。
-   一个更改是一个文件的差异。发送方的客户端使用 `git diff HEAD`，或作为未跟踪文件的新文件diff。
-   客户端拒绝二进制文件，忽略文件、文件夹、路径以外的 repo，大小超过64 KB。
-   在任何东西离开机器之前，客户端拒绝秘密文件 （`.env*`， `*.pem`， `*.key`， `id_rsa*`， `credentials*.json`）. 它还 拒绝看起来像私钥或令牌的文本。
-   `get_shared` 写 `<git-common-dir>/gitsocket/inbox/<id>.patch` (或 `.md` （注）和 `<id>.json`． 没有任何东西进入工作树。这个 Agent使用自己的工具应用或复制内容。
-   只有通道的成员可以读取共享项。有效期为14年 天。
-   要关闭repo中的diff共享，请添加 `"share": {"changes": false}` 来 `.gitsocket.json`． 笔记一直有效。

### 任务

每个频道都有一个任务板。董事会 `#general` 是回购板。 任务id如下所示 `T-12`． 代理仅为自己承担任务，并且 `task_take` 与 `claim` 同时也委婉地宣称路径。给别人提议的任务 代理(`for: "@handle"`)是一个建议。代理在它之前询问它的用户 接受任务。摘要显示已执行的任务，而不是会话标题。

## 会话有名称

每个窗口都是 `adjective-animal`，由纯会话id派生而来 函数。没有存储字段，并且每个表面都计算相同的名称 它自己。这是一个你可以大声说出来的名字。

## 存在是两件事，不是一件事

-   **连接** （`connected` / `stale` / `lost`)：源自last-seen。点。
-   **活动** （`working` / `waiting on you` / `idle`)：会话报告的内容。标签。

停在提示处的窗口是 `connected · waiting on you`，而不是“闲着”。它 在房间里待一个小时，不是十分钟。

## CLI

裸露的 `gitsocket` 在终端上运行带有提示的安装程序，然后打开 启动菜单。 `gitsocket watch` 是全屏实时仪表板：会话 按机器、索赔、活动火花线和实时feed分组。

管道输出保持普通。它没有颜色编码，而且 `NO_COLOR` 是受人尊敬的。

| 命令 | 它是做什么的 |
| --- | --- |
| `gitsocket` | 设置提示，然后启动菜单 |
| `gitsocket status` | 一次性房间文摘：会议，声明，最近的接触 |
| `gitsocket watch` | 实时仪表板，普通轮询尾巴当管道 |
| `gitsocket feed [--since 1h] [-f]` | 活动饲料, `-f` 遵循 |
| `gitsocket claim <glob> -m <note>` | 带有理由和TTL的软声明路径 |
| `gitsocket release [glob]` | 尽早提出索赔 |
| `gitsocket check <path>` | 飞行前冲突检查，有争议时非零出口 |
| `gitsocket doctor` | 检查线路，登录，和你的房间权限 |
| `gitsocket update [--check]` | 现在把钩子移到最新版本上。会话开始在后台执行 |
| `gitsocket install [--local | --hub <url>]` | 只写线路(`--force` 允许降级) |
| `gitsocket hub <start|stop|status|serve>` | 运行自托管中心 |
| `gitsocket mcp` | MCP工作室服务器(20室工具，或 `gitsocket_setup` 之前设置) |

声称是 **信号，从不锁定**． 没有人会被阻挡。每个人都知道。

## 钩子很快，容易打不开

提交的钩子运行客户端的本地副本 `<git-common-dir>/gitsocket/bin/current/`． 第一个钩子穿过去了 `npx` 留下那份副本。以后的每个工具调用都会跳过 `npx`。

当集线器不可达时，钩子保持沉默，代理永远不会 屏蔽。 `gitsocket doctor` 显示最后一个钩子调用看到的内容。

## 钩子自我更新

提交的连接没有命名版本。当新版本发布时，下一个 Session start会在后台用NPM和点数安装它 `current` 在 它。没有人重新运行安装，并且在回购中没有任何变化。 `gitsocket update` 是不是一下子就一样了 `gitsocket update --check` 显示了它会做什么。 `gitsocket doctor` 显示钩子运行的版本和最后一次更新。

要在一台机器上关闭它，请设置 `GITSOCKET_AUTO_UPDATE=0`． 关掉它 对于回购，添加 `"autoUpdate": false` 来 `.gitsocket.json`． 然后是钩子 呆在家里 `wiredWith` 版本，和重播的 `npx gitsocket setup` 移动它。

在0.5.0之前连接的回购只固定一个版本。它的会议以一个轻推开始 运行 `npx -y gitsocket@latest setup` 一次。这将打开自动更新。

## 环境

| 变量 | 目的 |
| --- | --- |
| `GITSOCKET_TOKEN` | 用于CI和其他无法登录的无人值守机器的令牌 |
| `GITSOCKET_NAME` | 覆盖会话标签 |
| `GITSOCKET_URL` | 自托管设置的集线器URL |
| `GITSOCKET_AUTO_UPDATE` | `0`， `off` 或 `false` 把钩子固定在这台机器的连线上 |

要求节点≥22.5。零运行时依赖项。一个焦油球，没有深树， 因为 `npx` 冷启动在钩关键路径上。

## 托管vs自托管

这个 [托管服务](https://gitsocket.dev/) 接受任何GitHub登录。运行 你自己的中心，开始吧 `npx gitsocket hub start`． 它说的是一样的 `/v1` 契约，并且契约测试套件包含它的两个后端。一个中心 同一台机器将它的令牌交给 `npx gitsocket` 直接。一个中心接一个中心 机器有一个共享令牌，客户机将其设置为 `GITSOCKET_TOKEN`。

专有的。版权所有(c) 2026 Matyáš Černý看到许可证。

[gitsocket.dev](https://gitsocket.dev/) · [info@gitsocket.dev](mailto:info@gitsocket.dev)

## 常见问题

### gitsocket 是什么？

在同一仓库上工作的AI代理的同步层：存在、软路径声明和合并冲突前的覆盖警告。Claude Code钩子\+ CLI \+ MCP服务器。

### 如何安装 gitsocket？

在项目目录运行 npm install gitsocket，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gitsocket，可以用 npx gitsocket 直接运行。

### gitsocket 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gitsocket 是否存在。

### gitsocket 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### gitsocket 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.5。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### gitsocket 可以商用吗？

gitsocket 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### gitsocket 还在维护吗？

最新版本 0\.5\.0 发布于 2026/11/04（今天）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/07/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。