# @charonova/agenthq 中文文档

规范地址：https://npmcn.com/package/%40charonova/agenthq/

版本：0\.3\.0
npm 元数据更新时间：2026-10-31T17:15:22.702Z
中文译文更新时间：2026-10-31T18:40:16.575Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40charonova/agenthq
原文对照：https://npmcn.com/package/%40charonova/agenthq/?lang=original
项目主页：https://charonova.github.io/agenthq/
源码仓库：https://github.com/charonova/agenthq

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

- 包体积（解压后）：970 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-31T14:32:34.047Z
- 最新版本发布：2026-10-31T17:15:22.540Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

为你的《Claude Code》和《Codex》设置一个像素级的办公室：每个会话都是一个办公室，主代理是它的经理，每个子代理都是一张桌子。

## 安装

```sh
npm install @charonova/agenthq
```

也可以使用：`pnpm add @charonova/agenthq`、`yarn add @charonova/agenthq`、`bun add @charonova/agenthq`

## README

# 🏢AgentHQ

**为你的《Claude Code》和《Codex》会议准备一个像素化的办公室。**

[网站](https://charonova.github.io/agenthq/) · [它是如何工作的](https://npmcn.com/package/%40charonova/agenthq/#readme-how-it-works) · [开发](https://npmcn.com/package/%40charonova/agenthq/#readme-develop)

![AgentHQ: the building of live sessions, then one office: teammates walk from the couch to their desks, to the bookshelf, to the lab, and into the manager's glass office to report](https://raw.githubusercontent.com/charonova/agenthq/main/docs/media/office.gif)

* * *

每个现场会议都是一个办公室。它的主要代理人是经理，每个队友都有一张桌子，他们开始的助手作为实习生坐在他们旁边。工作代理人在他们的办公桌上打字，在书架上阅读，在实验室里做测试，走过去互相交谈；闲散的人喝杯咖啡，然后在沙发上小睡一会儿。

> 早（0.2），移动快。适用于macOS， Linux和Windows。

## 运行它

你需要 [node . js](https://nodejs.org/) 20岁或以上。一个命令:

```bash
npx @charonova/agenthq          # opens the office at http://localhost:4747
npx @charonova/agenthq --list   # or print it in the terminal
```

或者安装： `npm install -g @charonova/agenthq`,然后 `agenthq`.

<table><tbody><tr><td><img alt="The building: three live sessions as offices on one map, with a list of offices on the right" src="https://raw.githubusercontent.com/charonova/agenthq/main/docs/media/building.png" loading="lazy" decoding="async" referrerpolicy="no-referrer"></td><td><img alt="Inside an office: the manager in a glass office, staff at desks, the bookshelf, lab and couch, and a selected agent's details" src="https://raw.githubusercontent.com/charonova/agenthq/main/docs/media/office.png" loading="lazy" decoding="async" referrerpolicy="no-referrer"></td></tr><tr><td align="center"><sub><b>建筑</b> ·每个现场会话，在一张地图上</sub></td><td align="center"><sub><b>一个办公室</b> ·点击任何人的任务、工具、模型和上下文</sub></td></tr><tr><td colspan="2"><img alt="An agent's conversation open over its office: the prompt, a Markdown reply, a command with its output, and a teammate's message" src="https://raw.githubusercontent.com/charonova/agenthq/main/docs/media/conversation.png" loading="lazy" decoding="async" referrerpolicy="no-referrer"></td></tr><tr><td align="center" colspan="2"><sub><b>一次谈话</b> ·任何人的完整聊天，实时，每个工具调用及其输出</sub></td></tr></tbody></table>

这些图片来自于制作过程(`pnpm media`）; AgentHQ展示了你自己。

-   **建筑**：每个现场会议都是一张地图上的办公室。拖动可移动，滚动可缩放，点击办公室可进入内部。
-   **在办公室里**经理坐在玻璃办公室里，员工坐在各自团队颜色的办公桌前，实习生站在启动他们的人旁边。泡沫说明每个人在做什么；点击任何人的任务、工具、模型、上下文和最后的话。
-   **他们去了哪里**：写代码→他们的桌子·阅读→书架·命令→服务器机架·测试→实验室·网络→窗口·计划→白板·给队友发消息→那个队友的桌子·等你→举手·空闲→咖啡，然后是沙发。他们围着家具走。
-   **它会告诉你什么时候有人需要你**一个桌面通知和一个报时，当一个代理开始等待你（🔔在头部）；点击它跳到那里。选项卡标题显示有多少人正在等待 **✋需要你** 计数器依次进入每个计数器。也可以在会话结束时使用。
-   **每个代理的时间轴**：它最新的工具调用，随着时间的推移，在它的细节下。
-   **💬整个对话**：打开任何人的对话，经理，队友或助手，Claude Code或Codex：您的提示，它的回复，每个工具调用及其输入和输出，队友之间的消息。当你向上滚动时，它会实时加载旧消息（即使是在几gb的会话中），并且你可以搜索它。
-   **✋来自AgentHQ的回答** （Claude Code，选择加入）：允许提示和问题显示在代理的对话中。允许一次，从Claude Code自己的“总是允许”选项中选择一个，拒绝并注明要做什么，或者选择问题的答案（或者输入你自己的）。终端还显示提示，也能回答；谁先回答，谁就赢。在🔔下面打开它：它增加了一个 `PermissionRequest` 钩, `~/.claude/settings.json` （首先保存文件的副本，保留其他钩子），并且在AgentHQ关闭时它什么也不做。把它关掉，它就消失了。
-   **直接去治疗**：双击任意对象(或 **去xxx** 在他们的详细信息中)，它的窗口出现：在Terminal或iTerm2中的确切选项卡，项目的窗口在VS Code，光标或Windsurf，或它运行的应用程序（macOS）。在其他地方，或者当它不能，恢复会话的命令为您复制。
-   **食典委太**每个Codex线程都是一个办公室，其子代理（如监护人）作为工作人员，在Codex应用程序中命名。
-   **日日夜夜** 遵循你的生物钟。

## 它是如何工作的

AgentHQ只 **读取** Claude Code写的东西 `~/.claude`，并且没有任何内容离开您的计算机（该页面仅在127.0.0.1上提供）。唯一的例外是从AgentHQ进行应答，当您打开它时：然后它将钩子添加到 `~/.claude/settings.json`，并保存自己的文件 `~/.agenthq` （钩子，运行服务器的地址，每次启动都有一个新的秘密，以及你回答的日志，只有名字和选择）。

| 办公室 | 从 |
| --- | --- |
| 办公室 | 会议在 `~/.claude/projects/*/*.jsonl` 在过去30分钟内活跃 |
| 经理 | 会议记录 |
| 工作人员 | 队友: `<session>/subagents/agent-*.jsonl` 谁的 `.meta.json` 说 `spawnDepth: 0` （名称、颜色、型号） |
| 实习生 | 他们开始了： `spawnDepth` 1 +, `parentAgentId` |
| 每个人做什么 | 记录的最后几行：它调用的工具，以及多久以前 |
| 会话运行的位置 | `~/.claude/sessions/<pid>.json` （哪个进程运行哪个会话），然后是该进程上面的应用程序 |
| 食典委 | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` （子代理的线程命名它的父线程），从 `~/.codex/session_index.jsonl` |

只读取每个文本的末尾，所以几gb的会话保持快速；当您滚动时，每次读取一页（192 KB）的对话。设置: `AGENTHQ_JUMP=copy` 使“go to session”只复制resume命令； `AGENTHQ_CLAUDE_HOME` 读取另一个文件夹； `AGENTHQ_IGNORE=frag1,frag2` 忽略文件夹中包含这些会话的会话（默认情况下忽略claude-mem的后台会话）。

## 开发

一个pnpm工作区：

| 包 | 什么 |
| --- | --- |
| `packages/core` | 读者：实时会话→办公室（Node，无依赖） |
| `packages/cli` | `@charonova/agenthq`：命令、本地服务器（server - sent Events）和构建的web应用 |
| `apps/web` | 办公室：Vite + React + PixiJS（摄像头的pixi-viewport）， Zustand代表状态 |
| `e2e` | 剧作家测试虚构的剧本 `~/.claude` |

```bash
pnpm install
pnpm dev          # server + Vite with hot reload: http://localhost:5173
pnpm check        # lint, format, types, unit tests
pnpm build        # web app, then the CLI with it inside
pnpm e2e          # end-to-end tests (after a build), with screenshots in test-results/
pnpm start        # build, then open the office
pnpm media        # the README's screenshots and GIF, from made-up sessions
```

CI在Linux、macOS和Windows上运行检查，并在Linux上运行端到端测试。

## 许可证

麻省理工学院

## 常见问题

### @charonova/agenthq 是什么？

为你的《Claude Code》和《Codex》设置一个像素级的办公室：每个会话都是一个办公室，主代理是它的经理，每个子代理都是一张桌子。

### 如何安装 @charonova/agenthq？

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

### @charonova/agenthq 支持 TypeScript 吗？

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

### @charonova/agenthq 支持 ESM 还是 CommonJS？

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

### @charonova/agenthq 需要什么版本的 Node\.js？

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

### @charonova/agenthq 可以商用吗？

@charonova/agenthq 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @charonova/agenthq 还在维护吗？

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