hxx 使用手册

hxx 是安装后的全局命令。在 npm registry 上本工具为 作用域包 @huangxiaoxu/hxx（无作用域的 hxx 已被他人占用）；全局安装：npm install -g @huangxiaoxu/hxx，不全局：npx @huangxiaoxu/hxx。在当前工作目录作为代码仓库根目录，串联 规划（Planner）→ 执行（Worker），支持本地工具调用与 MCP。底层对接 智谱 GLM 的 Anthropic 兼容 HTTP API。完整行为约定见仓库内 REQUIREMENTS.md。

1. 安装 hxx

1.1 全局安装（推荐，用法类似安装 Claude Code 后输入 claude）

需要先安装 Node.js ≥ 20。

npm install -g @huangxiaoxu/hxx

安装完成后，在终端可直接执行：

hxx --help

确认能打印帮助即表示 PATH 中已有全局命令（Windows 下若找不到命令，请检查 npm 全局 bin 目录是否已加入 PATH）。

1.2 不全局安装（临时使用）

在你的项目根目录执行：

npx @huangxiaoxu/hxx --help

注意：npx 按 registry 包名 @huangxiaoxu/hxx 安装/运行；不会单独注册全局命令 hxx，除非你先 npm install -g @huangxiaoxu/hxx。若要单次 REPL，可：

cd /path/to/your/repo
npx @huangxiaoxu/hxx

1.3 从本仓库源码开发调试

git clone <本仓库地址>
cd <克隆下来的仓库目录>
npm install
npm run build
npm link          # 可选：注册全局命令 hxx
hxx --help

日常不改构建产物时也可用：

npm start

2. 配置文件：~/.hxx/ + 项目根（类似 Claude Code）

应用参数只从 JSON 文件读取，不读 Shell 环境变量，也不读 .env。

2.1 两层合并（用户目录 + 当前项目）

1. 用户级（全局缺省）：在用户主目录下创建文件夹 .hxx（路径：~/.hxx/，Windows：%USERPROFILE%\.hxx\），放入 hxx.config.json。适合放 anthropicAuthToken、默认模型、常用 glm* 开关等，所有项目共用。
2. 项目级（覆盖）：在运行 hxx 时的当前目录（一般是仓库根）再放入一份 hxx.config.json。其中出现的字段会覆盖用户级同名字段；未写的字段继续用用户级的值。
3. 模板见 hxx.config.example.json；字段含义见 REQUIREMENTS.md §4 与源码 src/appConfig.ts（HxxConfigFile）。

启动时执行 refreshAppConfig()：先读 ~/.hxx/hxx.config.json，再叠加上 ./hxx.config.json。

2.2 API Key（多层兜底）

合并后的 anthropicAuthToken 若仍为空，按顺序尝试：

1. 项目根下的 .glm-api-key（第一行有效密钥，用法见 glm-api-key.example）；
2. ~/.hxx/.glm-api-key（同上）。

不要把含密钥的文件提交到 Git；仓库默认 hxx.config.json、.glm-api-key 已在 .gitignore 中（可按团队规范调整）。

2.3 安全提示

• 不要把真实 Key 写进 README、Issue、公开 gist。
• 若密钥曾误提交到 Git，请在智谱控制台轮换密钥，并从历史中移除敏感文件。

2.4 关于 .env

历史版本曾支持 .env / 环境变量；当前版本已移除。根目录 .env.example 仅作迁移说明。

3. 配置 MCP（Model Context Protocol）

MCP 用于接入外部工具服务（与内置的 read_file、grep 等并列，名称格式为 mcp_<服务器名>_<工具名>）。

除 --help 外，每次启动会在工作区下确保存在 ./.hxx/skills/ 与 ./.hxx/mcp.json。全新仓库在尚无 .hxx/mcp.json、且根目录也无历史 mcp.json 可复制时，会写入出厂默认 MCP：已附带 Chrome DevTools MCP（npx -y chrome-devtools-mcp@latest；需 Node 与 Chrome）。若你仍在使用工作区根的 ./mcp.json 且尚无 .hxx/mcp.json，首次启动会把它 复制 到 .hxx/mcp.json。此后每次启动：若 mcp.json 里没有 chrome-devtools 这一条，会自动 补上（与「出厂默认」一致）；若你已手动删掉且不想要该行为，在 hxx.config.json 设 glmOmitDefaultChromeDevtoolsMcp: true。

3.1 配置文件位置

• 默认：工作区根下的 .hxx/mcp.json
• 自定义路径：在 hxx.config.json 中设置 glmMcpConfig（相对路径相对于工作区根）。

禁用 MCP：在 hxx.config.json 设置 glmDisableMcp: true（或 "1"）。

3.2 格式概要

根对象须包含 mcpServers，每一项为一个 MCP 服务：

| transport（或与 type 二选一） | 含义 | |----------------------------------|------| | stdio | 本地进程：需提供 command，可选 args、env | | sse 或 http | 远程 URL：需提供 url，可选 headers |

完整约定见 REQUIREMENTS.md 中的 §10a MCP 支持。

3.3 示例

可参考仓库内 mcp.example.json，复制为 .hxx/mcp.json（或首次运行 hxx 生成空壳后粘贴内容）并按需修改：

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:\\\\your\\\\allowed\\\\root"],
      "env": {}
    },
    "remote-example": {
      "transport": "sse",
      "url": "http://localhost:3001/sse",
      "headers": {}
    }
  }
}

注意：

• 不要把含真实 API Key 的 URL（例如 query 里的 Authorization=）提交到公开仓库；默认 .gitignore 已忽略 mcp.json 与 .hxx/mcp.json，但仍需防范手动拷贝泄露。
• 智谱等提供的 MCP Broker：文档若要求 transport: "sse" 且 URL 中带鉴权，请在本地私有配置中填写。

启动成功后，stderr 会出现类似 [mcp] N server(s) connected… 的日志。

3.4 Chrome DevTools MCP：用「日常已在用的」Chrome，而不是干净自动化窗口

默认会再启动一份带「正受到自动测试软件的控制」提示的 Chrome（独立配置目录）。若要 MCP 接到你平时已经打开的那个 Chrome（同一套登录、书签、扩展）：

1. Chrome 版本需 ≥ M144（见 chrome-devtools-mcp README）。
2. 在已运行的 Chrome 里打开 chrome://inspect/#remote-debugging，按页面说明开启远程调试（会涉及本机上的允许/拒绝）。
3. 在 .hxx/mcp.json 里给 chrome-devtools 加上参数 --autoConnect，例如：

"chrome-devtools": {
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]
}

4. 先保持 Chrome 已打开，再启动 hxx；首次连接时 Chrome 可能弹出是否允许调试的对话框，需点允许。

多用户配置时，文档说明会连到 Chrome 认定的默认配置；扩展类工具有额外限制以 上游说明 为准。

另一种是 --browser-url=http://127.0.0.1:9222 搭配用调试端口启动的另一个 Chrome 进程——官方指出为安全常需单独 --user-data-dir，一般不等同于日常主配置，需要「完全同一窗口」时优先用 --autoConnect。

4. 使用 hxx

4.1 工作目录（非常重要）

与 Claude Code 类似：请先 cd 到你的项目根目录再运行 hxx。

进程启动时会把当时的目录 固定为工作区根（path.resolve(process.cwd()) 一次）；REPL 启动时 stderr 会打印一行 Workspace: …。之后即使运行环境改了 process.cwd()，配置与工具默认仍指向该根目录。

该根目录决定：

• 自动维护 ./.hxx/skills/ 与 ./.hxx/mcp.json（见上文 MCP 一节）
• 读取 ./hxx.config.json（与用户目录 ~/.hxx/hxx.config.json 合并）
• 读取 ./.glm-api-key（密钥兜底之一）
• 默认 MCP 配置：./.hxx/mcp.json（或由合并后配置里的 glmMcpConfig 指定路径）
• Worker 工具（读写文件、终端命令等）的工作区根路径
• .hxx/skills、.glm-agent/skills、.glm-agent/workflows 等项目级配置

4.2 交互 REPL（默认）

cd /path/to/your/repo
hxx

• 普通一行输入：交给 Planner 作为新 mission。
• 以 ! 开头的行：记入备注，合并进下一次规划的上下文。
• 输入 /exit（仅此一条命令，不区分大小写）退出；/quit、quit、exit 等一律视为普通任务目标。

4.3 单次目标（非交互）

hxx --goal "用一句话概括 src 目录职责"

可选 --parallel：并行跑 Worker（默认串行且带 Planner 逐步评审时行为不同，详见 REQUIREMENTS.md）。

4.4 按 JSON 任务表执行

hxx tasks.json

任务文件格式可参考 tasks.example.json。

4.5 浏览器里看任务队列

默认在本机项目根启动 hxx（交互 REPL、--goal、tasks.json、--workflow）并在 MCP / Skills 初始化完成后，会自动在 127.0.0.1 监听任务面板（stderr 打印 [task-ui] http://127.0.0.1:…/）。默认端口 18765（hxx.config.json → glmTaskUiPort；命令行 --port 优先）。页面轮询 ./.hxx/task-ui-state.json，可看到 queued / running / ok / error。

• 不需要为面板单独起进程；若不想自动监听，设 glmTaskUiAutostart: false，需要时再执行 hxx task-ui（仅 HTTP，不调模型）。
• 不想写状态文件时设 glmDisableTaskUi: true。
• 若已有一个 hxx 在跑且占用了端口，第二个进程会提示端口占用，继续用第一次提示的地址打开即可。

本地静态站预览（由 Worker 决定）： Planner/Worker 可使用工具 dev_static_http 在 127.0.0.1 启停只读 HTTP 服务；是否启动、根目录（document_root，相对工作区根）、端口 均在对话中由模型选择，默认端口见 glmDevHttpDefaultPort（hxx.config.json，默认 8766）。与上方「任务面板」不是同一个服务。

4.6 前端 / 站点收尾自检

对用户可见的网页（静态站、SPA、服务端模板等），Planner 会尽量在任务表 末尾安排一条自检：按项目的 README / package.json 脚本起 dev 或预览，并结合 Chrome DevTools MCP（新项目 .hxx/mcp.json 出厂默认已注册，成功连接后可用 mcp_chrome-devtools_*；若你已删掉该项或 MCP 拉起失败则退化为脚本/mcp_web_fetch 等）。REQUIREMENTS.md §7.2 有完整约定。--parallel 批量模式不会在任务之间跑逐步评审，队列为空后也不会再走 §8 的评审收尾；请务必在初次拆任务时就写上验证步骤。其它路径下不能用配置关闭逐步评审。

4.7 Workflow

hxx --list-workflows
hxx --workflow <名称> --input key=value

REPL 内：/workflow …、/workflows 列出。

4.8 帮助

hxx --help

4.9 Windows：npm 吃掉参数时

不要用 npm start -- --goal "..." 这类易被 npm 截断的方式；请直接使用：

hxx --goal "你的目标"

或未全局安装时：

npx @huangxiaoxu/hxx --goal "你的目标"

5. 开源与发布（维护者）

• 协议：MIT，见 LICENSE。
• Registry：发布到 https://registry.npmjs.org/。若本机默认是镜像（如 npmmirror），请 npm login / npm publish 时加上 --registry https://registry.npmjs.org/，否则会报未登录或无法发包。
• 发布前：在 package.json 中提升 version（或使用 npm version patch / minor / major），然后执行 npm publish --registry https://registry.npmjs.org/（prepublishOnly 会自动 npm run build）。作用域包已在 package.json 中配置 publishConfig.access: "public"；若未配置，首次发包须加 --access public。

更多细节（流式输出、Planner 上下文压缩、工具列表与安全策略等）见 REQUIREMENTS.md。