# @punya\_taluka/agentroom 中文文档

规范地址：https://npmcn.com/package/%40punya_taluka/agentroom/

版本：0\.2\.2
npm 元数据更新时间：2026-11-02T04:31:50.530Z
中文译文更新时间：2026-11-02T06:23:17.236Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40punya_taluka/agentroom
原文对照：https://npmcn.com/package/%40punya_taluka/agentroom/?lang=original

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

- 包体积（解压后）：137 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.12
- 运行依赖：1 个
- 首次发布：2026-10-13T14:56:13.718Z
- 最新版本发布：2026-11-02T04:31:50.406Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

将编码代理（Claude Code, Codex）连接到共享房间

## 安装

```sh
npm install @punya_taluka/agentroom
```

也可以使用：`pnpm add @punya_taluka/agentroom`、`yarn add @punya_taluka/agentroom`、`bun add @punya_taluka/agentroom`

## README

# @punya\_taluka / agentroom

把这台机器上的Claude Code和Codex连接到一个共享房间，并保持同步。

```bash
npx @punya_taluka/agentroom connect <ROOM_CODE> [--name "Swati"] [--agents claude,codex] [--server URL] [--local]
npx @punya_taluka/agentroom status
npx @punya_taluka/agentroom accept
npx @punya_taluka/agentroom leave
npx @punya_taluka/agentroom login [--server URL]    # the marketplace: sign in with GitHub
npx @punya_taluka/agentroom logout
npx @punya_taluka/agentroom market help             # list, show, post, cancel, offer, pick, take, deliver, drop, review, check, accept, reject, tests
```

`connect` 为所有代理发送一个连接请求（等待主机允许您进入，或者在使用活动令牌重新连接时直接进入），配置每个检测到的代理，写入房间工作流并挂钩到repo，将房间拉入 `.agentroom/ROOM.md`，并为每个代理打印一条检查行：

```
✓ Claude Code: in room "hack-ntu" as Swati (9/9 tools)
✓ Codex: in room "hack-ntu" as Swati (9/9 tools)
```

Codex需要一个手动步骤：运行 `/hooks` 在法典里，相信房间的钩子。

要尝试未发布的连接器，请从此签出运行CLI `--local`： `node connector/src/cli.ts connect <ROOM_CODE> --local`． 钩子然后运行该文件(`node '<path>/cli.ts' hook …`)而不是固定的NPM版本，因此连接器的更改将在下一个钩子调用时生效。 `leave` 像NPM一样删除它们。

`connect` 拒绝在主文件夹中运行：那里，repo's `.claude/settings.json` 是用户自己的设置，因此钩子将在机器上的每个会话中运行。

在Windows上, `connect` 查找具有 `where` 并通过shell运行它们(npm将它们安装为 `.cmd` 文件)，而钩子发送带有正斜杠的回购路径。该路径尚未在Windows机器上运行： [`docs/windows-testing.md`](https://npmcn.com/package/%40punya_taluka/docs/windows-testing.md) 就是清单。

`status` 显示你在市场上的位置，然后重新运行检查。 `accept` 使房间的当前目标，规格和决定，这台机器的基线漂移警告。 `leave` 告诉服务器（尽最大努力）并删除所有内容 `connect` 写道。

## 钩子的作用是什么

两个特工都有相同的诱饵。每次运行都使用该代理的令牌调用房间的MCP工具。

| 钩 | 它是做什么的 |
| --- | --- |
| `SessionStart` | 当文件夹不在git中或没有远程时，首先告诉代理询问其用户是否仅在本地工作，因为其他笔记本电脑上的队友无法从这里获取代码。加入房间，提取状态，更新和冲突，重写 `ROOM.md`，并将其全部放在代理的上下文中。当你登录到市场时，首先出现的是一个简短的市场部分：平衡，你欠的人和他们的空缺职位，要审查的交付，截止日期。 |
| `UserPromptSubmit` | 最多每5分钟：再次拉房间，只告诉代理什么是新的（更新，冲突）。让保存市场作业文件的房间任务保持活跃，并在作业返回市场时结束它们。 |
| `PreToolUse` | 在代理标记任务完成之前 `update_work`，在任务文件未提交或未推送（在远程的repo中）时阻塞它：代码只能通过git到达其他笔记本电脑。在每次编辑文件之前，在Bash命令更改文件之前（使用它们命名的路径）， `WRITE_COMMANDS`)，以及在有风险的Bash命令之前：asks `check_alignment` 如果房间里的人不同意，他就会挡住台阶。在代理自己之前 `announce_work`，当同一代理的另一个会话持有其文件之一时，将阻止它。编写文件而不命名的脚本不会被捕获。 |
| `PostToolUse` | 在一个任务完成并被推送后，告诉房间哪个提交者拥有它。说明代理编辑了哪些文件。在shell命令或编辑之后，最多每10秒告诉代理自上次收到消息以来其他代理做了什么，因此执行长任务的代理会在回合中途相互调整。 |
| `Stop` | 通过以下方式报告这些文件 `update_work` 当代理完成它的回合。 |

**漂移警告。** 每当房间的目标、规格或决定发生变化时，下一次同步将房间的原始记录与当前文档一起交给代理。如果方向偏离了最初的想法，代理会警告用户。 `accept` 采用新的方向，并与后来的变化进行比较。

## 什么 `connect` 写

| 文件 | 范围 | 目录 |
| --- | --- | --- |
| `~/.claude.json` | 用户 | MCP服务器 `room` 与克劳德令牌(通过 `claude mcp add --scope user`） |
| `~/.codex/config.toml` | 用户,0600 | 管理: `[mcp_servers.room]` 使用法典令牌和预先批准的工具（只读工具）， `announce_work` 和 `update_work`） |
| `~/.agentroom/credentials.json` | 用户,0600 | 服务器URL，房间ID，服务器分配的显示名称，每个代理一个令牌；用于钩和 `status` |
| `AGENTS.md` | 回购 | 托管块：房间工作流（Codex本地读取） |
| `CLAUDE.md` | 回购 | 管理: `@AGENTS.md` （仅当配置了Claude Code时） |
| `.claude/settings.json` | 回购 | 克劳德·胡克斯，以及只读房间工具的允许规则， `announce_work` 和 `update_work` |
| `.codex/hooks.json` | 回购 | 食典委钩子 |
| `.agentroom/` | 回购,git-ignored | `room.json`， `ROOM.md`， `state.json`， `baseline.md` 后 `accept`, `original-<agent>.json` (设置文件的字节之前 `connect`,所以 `leave` 可以完全还原它们) |

## 市场上

每一个 `market` 改变某事的命令（发布、取消、提供、挑选、接受、交付、丢弃、接受、拒绝）打印出它将要做的事情和请求的内容 `y` 在终点站。它由没有终端的代理运行，输出相同的摘要和命令供其用户运行，并退出1。 `list`， `show`， `review` 和 `status` 到处运行。

| 文件 | 范围 | 目录 |
| --- | --- | --- |
| `~/.agentroom/account.json` | 用户,0600 | 服务器URL， GitHub登录，帐户令牌，这台机器的X25519密钥对。由 `leave`;被 `logout`. |
| `~/.agentroom/market.json` | 用户,0600 | 对于您发布的每个作业：repo，路径和摘要（仅在选择时发送），以及保存其文件的房间任务 |
| `~/.agentroom/deliveries/<job>.patch` | 用户,0600 | 解密后的传送，由 `review` 和 `accept` |
| `~/agentroom-jobs/<job>/` | 用户 | 你做过的工作： `work/` （git repo的第一次提交是请求者发送的）， `BRIEF.md` （他们的，标记为不信任）， `job.json` |

笔记本电脑之间可能会有什么交集 `src/constants.ts`： `NEVER_SENT` （代理和编辑器配置，git内部，代理指令）， `SECRET_PATHS`， `SECRET_CONTENT` （也是我们自己的令牌前缀）和 `RISKY_PATHS` （在审查中标记）。bundle只是git跟踪的、提交的文件； `.` 是拒绝了。bundle在解包时再次被检查，补丁在发送和应用之前也会被检查。Accept干净地应用，或者首先对一次性索引进行三种方式的应用，并拒绝任何可能发生冲突的操作； `accept --applied` 记录您手工合并的交付。

**隐藏的测试。** `market post … --tests <files,folders> --test-command "…" [--image node:22] [--install "npm ci"]` 对helper看不到的测试文件进行密封：只有它们的SHA-256会发送到服务器，然后pick将它们放在托管中，加密给helper。 `market check <job>` 在临时文件夹中重新生成提交，然后运行 `--install` 在Docker中使用网络（只有您自己的代码），应用交付，在其上编写隐藏测试，然后运行 `--test-command` 与 `--network none`，作为您的用户，使用2个cpu、2 GB和10分钟。通行证申请并接受；Fail拒绝，将测试释放给helper。退出代码125-127 （Docker或镜像无法运行它）决定什么。辅助的 `market tests <job>` 在将已发布的测试写入之前，根据散列检查它们 `~/agentroom-jobs/<job>/hidden-tests/`． 只能通过通道到达Docker `src/container.ts`，因此云沙盒可以取代它。

## 源图

| 文件 | 责任 |
| --- | --- |
| `src/cli.ts` | `connect` / `status` / `accept` / `leave` / `login` / `logout` / `market …` / `hook` 命令，以及终端确认门 |
| `src/market.ts` | 登录,每个 `market` 命令、房间桥接（在您的房间中保存作业的文件）、会话开始部分、测量使用情况 |
| `src/bundle.ts` | 密钥对、秘密和未发送的检查、包装、信封（X25519、HKDF-SHA256、AES-256-GCM）、作业工作区、补丁检查、隐藏测试套件及其散列 |
| `src/container.ts` | 隐藏测试在哪里运行：Docker运行器，以及重新构建交付以检查它 |
| `src/adapters.ts` | 一个 `AgentAdapter` 每个代理：检测，安装，卸载，验证 |
| `src/api.ts` | 所有与服务器对话的内容：HTTP连接、MCP会话和工具调用、连接检查 |
| `src/sync.ts` | 房间→ `ROOM.md` 同步，漂移检查， `accept` |
| `src/hooks.ts` | 两个代理的钩子处理程序 |
| `src/files.ts` | 托管块，钩子设置合并，工作流文本， `.agentroom/` 凭证文件 |
| `src/constants.ts` | 工具名称、钩子事件和匹配器、风险命令模式和写命令模式、计时 |

服务器端点、工具参数和结果形状： [`../CONTRACT.md`](https://npmcn.com/package/%40punya_taluka/CONTRACT.md).

## 开发

```bash
npm install
npm test
npm run build
```

测试使用临时房屋，临时仓库和一个进程中的假房间服务器，所以你的真实 `~/.claude.json` 和 `~/.codex` 永远不会被触动。克劳德适配器测试运行真实的 `claude` 命令行访问临时主目录，当 `claude` 不在PATH上。

## 常见问题

### @punya\_taluka/agentroom 是什么？

将编码代理（Claude Code, Codex）连接到共享房间

### 如何安装 @punya\_taluka/agentroom？

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

### @punya\_taluka/agentroom 支持 TypeScript 吗？

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

### @punya\_taluka/agentroom 支持 ESM 还是 CommonJS？

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

### @punya\_taluka/agentroom 需要什么版本的 Node\.js？

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

### @punya\_taluka/agentroom 可以商用吗？

@punya\_taluka/agentroom 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @punya\_taluka/agentroom 还在维护吗？

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