AI 编程工作流层hellowind777/helloagents

HelloAGENTS

面向 AI 编程 CLI 的工作流层：技能、项目知识、交付检查、更安全的配置写入，以及可恢复执行。

Version
npm
Node
Skills
License
PRs Welcome
LINUX DO

[!IMPORTANT]
在找 v2.x？旧的 Python 版本现在位于 helloagents-archive。v3 版本是基于 Node.js、Markdown 规则、技能和小型运行时脚本的完全重写。

🏅 本项目由 LINUX DO 社区链接与认可。

目录

- HelloAGENTS 的作用
- 核心特性
- 快速开始
- CLI 管理
- 聊天中的命令
- 项目知识库
- 工作流与交付
- 配置
- 各 CLI 的集成方式
- 验证
- 常见问题
- 故障排查
- 许可证

HelloAGENTS 的作用

AI 编程 CLI 可以快速推进，但它们也可能止步于建议、跳过检查、丢失项目上下文、在任务变难时推卸责任，或在工作真正完成之前就报告完成。

HelloAGENTS 在 Claude Code、Gemini CLI、Grok Build、Cursor 和 Codex CLI 之上添加了一个工作流层。它将智能体锚定为一个有能力的执行者，阻止推卸责任的模式，帮助智能体选择正确的路径、使用针对特定任务的质量技能、维护项目知识库，并在交付前验证工作。

没有 HelloAGENTS

使用 HelloAGENTS

| 问题 | 没有 HelloAGENTS | 有 HelloAGENTS |
|---------|---------------------|------------------|
| 过早停止 | 以建议结束 | 继续进入构建、验证和收尾 |
| 转移责任 | 拒绝困难任务，建议其他工具 | 穷尽替代路径，坚持完成任务 |
| 质量不一致 | 取决于每个提示词 | 14 项质量技能按任务类型激活 |
| 上下文分散 | 计划存在于聊天历史中 | 项目知识和计划文件保留在磁盘上 |
| 完成定义模糊 | 自然语言说“完成” | 交付检查使用状态、证据和验证 |
| 配置写入有风险 | CLI 文件可能漂移 | 安装、更新、清理和诊断流程检查受管文件 |

核心功能

1) 14 项内置工作流技能

HelloAGENTS 内置 14 项技能。它们仅在当前阶段需要时加载，因此简单任务保持轻量，而复杂工作则获得更严格的检查。

| 技能 | 重点 |
|-------|-------|
| hello-ui | UI 规划、设计契约、实现映射、视觉验证 |
| hello-api | API 设计、验证、错误格式、兼容性 |
| hello-security | 认证、密钥、权限、注入风险 |
| hello-test | TDD、覆盖率、边界情况、测试结构 |
| qa-review | 统一质量审查、验证命令、阻塞性修复、交付证据、收尾 |
| helloagents | 命令路由、工作流阶段规则、项目知识和状态协调 |
| hello-errors | 错误处理、日志、重试和恢复行为 |
| hello-perf | 性能、缓存、查询和渲染风险 |
| hello-data | 数据库、迁移、事务、索引 |
| hello-arch | 架构、边界、代码规模、可维护性 |
| hello-debug | 缺陷诊断和卡住时的升级处理 |
| hello-subagent | 子代理委派和结果集成 |
| hello-write | 文档、报告和书面交付物 |
| hello-reflect | 可复用的经验教训和知识更新 |

所有 UI 工作首先遵循共享的 UI 质量基线。
在宿主全局模式、已初始化项目或显式 UI 工作流中，hello-ui 在该基线之上增加更深层的设计契约执行、设计系统映射和视觉验证。
当需要视觉证据时，HelloAGENTS 将其记录在当前会话的 artifacts/visual.json 中。

2) 适用于不同工作风格的命令

命令在 AI CLI 聊天中以 ~ 前缀运行。命令技能会被直接读取；除非工作流需要，否则不会加载无关技能。

| 命令 | 用途 |
|---------|---------|
| ~ask | 交互式澄清：通过问答明确目标、方向、范围和约束；不写入文件 |
| ~auto | 选择主路径并持续执行，直到交付或遇到真正的阻塞 |
| ~plan | 需求、方案设计、任务分解和计划包 |
| ~build | 根据当前请求或现有计划进行实现 |
| ~prd | 通过引导式逐维度探索生成现代产品需求文档 |
| ~loop | 长时间运行的入口；在 Codex 中它更偏好 /goal -> ~auto -> ~qa |
| ~init | 初始化项目工作流并同步项目知识 |
| ~test | 为目标模块或最近的变更编写测试 |
| ~qa | 运行统一质量循环：审查、验证命令、修复和收尾 |
| ~commit | 生成约定式提交信息并同步知识 |
| ~clean | 归档已完成的计划并清理临时运行时文件 |
| ~help | 显示命令和当前设置 |

兼容性别名：

- ~do → ~build
- ~design → ~plan
- ~review → ~qa
- ~idea → ~ask（已弃用）

使用 ~ask 来澄清需求、比较方案、权衡价值和界定范围——纯对话，不创建文件。

3) 项目知识库

HelloAGENTS 可以在 .helloagents/ 下创建并维护项目知识库。

知识库帮助后续轮次理解仓库，而无需重新发现相同的事实。它可以存储：

| 文件或目录 | 用途 |
|-------------------|---------|
| context.md | 项目概览、技术栈、架构、模块索引 |
| guidelines.md | 从仓库中推断出的非显而易见的编码约定 |
| verify.yaml | 验证命令，例如 lint、test、build |
| CHANGELOG.md | 项目级变更历史 |
| DESIGN.md | 当项目有 UI 工作时的稳定 UI 设计契约 |
| modules/.md | 模块特定的笔记和经验教训 |
| plans// | 活动计划包 |
| archive/ | 已归档的计划包 |

~init 初始化项目工作流：它写入项目级完整载体标记，准备项目状态，并创建或更新知识库。

4) 结构化计划包

复杂工作可以存储为计划包，而不是聊天中的单一段落。

对于 ~plan，HelloAGENTS 使用：

- requirements.md
- plan.md
- tasks.md
- contract.json

对于 ~prd，HelloAGENTS 还会创建 PRD 文件，例如：

- prd/00-overview.md
- prd/01-user-stories.md
- prd/02-functional.md
- prd/03-ui-design.md
- prd/04-technical.md
- prd/05-nonfunctional.md
- prd/06-i18n-l10n.md
- prd/07-accessibility.md
- prd/08-content.md
- prd/09-testing.md
- prd/10-deployment.md
- prd/11-legal-privacy.md
- prd/12-timeline.md

contract.json 被工作流用于决定 qaMode、qaFocus、可选的顾问检查以及可选的可视化验证。

tasks.md 还包含一个 Codex /goal 入口。对于长时间运行的 Codex 工作，请使用该准备好的入口，而不是给 /goal 一个原始产品文档。默认链是 /goal -> ~auto -> ~qa：Codex 保持长时间运行的延续，~auto 执行 AFK 工作，而 ~qa 仍然是收尾前的最终质量门。

5) 状态与恢复

长任务需要一个小型恢复快照，但一个共享状态文件对于并发工作来说不够安全。
HelloAGENTS 现在从 state_path 解析当前状态文件：

- 当存在稳定或可复用的会话 id 时：.helloagents/sessions///STATE.md
- 在可复用会话 id 可用之前：.helloagents/sessions//default/STATE.md

是当前 Git 分支，对于 detached HEAD 是 detached-，对于非 Git 项目是 workspace。 是当前项目本地会话令牌。.helloagents/sessions/active.json 只保留最新的活动 workspace/session 映射以及别名桥接，因此同一个 CLI 会话会保持在同一个目录中，并且 /resume 可以复用它。

对于项目本地会话，HelloAGENTS 首先使用稳定的宿主标识符，例如 sessionId、conversationId、threadId 或 HELLOAGENTS_NOTIFY_SESSION_ID。如果宿主只暴露窗口或终端 id，例如 WT_SESSION、TERM_SESSION_ID 或 WINDOWID，HelloAGENTS 仅将其用作轻量级别名桥接，并优先复用已映射的会话，而不是扩散出重复目录。如果会话在稳定宿主标识符可用之前启动，HelloAGENTS 可以从 default 开始，并在同一个 CLI 会话稍后暴露稳定标识符后继续复用同一个活动目录，而不是分裂成第二个会话目录。

STATE.md 记录当前工作流停止的位置。它不是每次对话的通用记忆文件。Codex /goal 不会替代 state_path、turn-state 或本地证据文件；它只处理 Codex 侧的长时运行延续。

6) 验证与交付证据

HelloAGENTS 不会把“测试通过”和“任务完成”视为同一件事。交付还可能要求计划覆盖、任务清单状态、审查证据、顾问证据和视觉证据。

运行时状态现在有意保持很小：

- .helloagents/sessions///STATE.md
- .helloagents/sessions///runtime.json
- .helloagents/sessions/active.json
- .helloagents/sessions///artifacts/qa-review.json
- .helloagents/sessions///artifacts/advisor.json
- .helloagents/sessions///artifacts/visual.json
- .helloagents/sessions///artifacts/closeout.json
- 可选的 .helloagents/sessions///events.jsonl
- ~/.codex/.helloagents/notify-state.json 仅用于 Codex 原生 closeout 去重

STATE.md 只保留人类可读的恢复快照。runtime.json 仅面向机器，并保留最小运行时状态。artifacts/.json 仅限于结构化回执。events.jsonl 仍然是可选的跟踪输出，并且默认关闭。
项目本地 STATE.md 现在更惰性地物化。

标准运行时证据和瞬态运行时状态现在会在 72 小时后过期。长时运行的 Codex goal 流程在工作流明确需要时，仍保留其 720 小时上限。
交付门禁、守卫和 QA 门禁消息使用面向行动的措辞，例如处理路径、收尾操作和视觉验证操作，因此被阻塞的流程会显示下一步该做什么，而不会把可执行步骤变成可选建议。最终收尾还强制使用单个 HelloAGENTS 包装器，因此一次回复不会发出重复的收尾标头。
该包装器现在仅保留用于直接面向最终用户的交付。中间报告、委托任务结果和子代理回复保持自然形式，并且子代理停止钩子会拒绝带包装的收尾回复。

7) 更安全的安装、更新、清理和诊断

CLI 显式管理宿主文件：

- install 仅写入选定的目标，除非使用 --all
- update 刷新选定的目标或所有目标
- cleanup 移除受管理的注入和链接
- uninstall 在移除包之前执行限定范围的清理
- doctor 报告载体、链接、钩子、配置项、插件根目录、缓存副本、版本以及真实的 Claude/Gemini 全局安装产物中的漂移；对于 Codex，它还会在可用时显示原生 codex doctor 输出
- Codex 受管理的 notify = ["helloagents-js", "codex-notify"] 保持可移植，并且 doctor、cleanup 和 uninstall 也会识别 Codex App / Computer Use 使用的带包装的 --previous-notify 链
- 每个宿主的模式跟踪仅在宿主设置成功后写入，并且原生全局清理失败时会将宿主保持跟踪为 global，而不是静默地在上面叠加备用模式
- 直接执行 switch-branch 会在其内部 npm install/sync 步骤之前清除陈旧的 HELLOAGENTS 生命周期环境变量，并且当未提供显式宿主参数时，包的 preuninstall 会回退到 --all，因此陈旧的 shell 环境不会缩小分支切换或卸载清理的范围
- Windows 的 .cmd / .bat 生命周期调用现在通过显式命令包装器运行，因此宿主安装、分支切换和 doctor 流程不会发出 Node DEP0190 shell 弃用警告
- Claude Code、Gemini CLI、Grok Build、Cursor 和 Codex CLI 的配置写入、更新、清理、卸载、模式切换和分支切换被覆盖为一条经过测试的生命周期链，而不是各自尽力而为的独立路径

快速开始

1) 安装包

npm install -g --allow-scripts=helloagents helloagents

如果你的 PATH 中已经存在另一个名为 helloagents 的可执行文件，请使用稳定的受管理入口别名：

helloagents-js

默认情况下，postinstall 会安装包命令、初始化 ~/.helloagents/helloagents.json，并将运行时文件同步到 ~/.helloagents/helloagents。除非你设置 HELLOAGENTS=target[:mode]，例如 HELLOAGENTS=codex:global，否则不会部署任何宿主 CLI。

对于 npm 11 及更高版本，在直接安装或升级包的命令中保留 --allow-scripts=helloagents，以便 npm 可以在没有审批警告的情况下运行受管理的 postinstall。如果你仍在使用 npm 10 或更早版本，可以省略该标志。

2) 部署到 CLI
对选定的项目使用待机模式并显式激活：

helloagents install codex --standby
helloagents install --all --standby

当你希望在所有地方都应用完整规则时，使用全局模式：

helloagents --global
helloagents install --all --global

重新安装、刷新或切换模式后，请重启目标 AI CLI 或打开新会话；已在运行的会话不会自动重新加载注入的规则。

3) 在你的 AI CLI 中验证

输入：

~help

你应该会看到可用的聊天命令和当前设置。

4) 创建项目知识

初始化项目工作流：

~init

CLI 管理

Shell 命令

helloagents --standby
helloagents --global
helloagents install codex --standby
helloagents install --all --global
helloagents update codex
helloagents cleanup claude --global
helloagents uninstall gemini
helloagents switch-branch beta
helloagents switch-branch beta claude --global
helloagents doctor
helloagents doctor codex --json
helloagents codex goals status
helloagents codex goals enable

支持的目标：

- claude
- gemini
- grok
- cursor
- codex
- --all

如果你省略 --standby 或 --global，HelloAGENTS 会先复用该 CLI 已跟踪/检测到的模式，然后回退到 standby。

npm 和一次性脚本入口

当你不想在包更新期间依赖 helloagents 二进制文件可用时，可以使用这些入口。在 HELLOAGENTS=target[:mode] 中，target 可以是 all、claude、gemini、grok、cursor 或 codex；mode 可以是 standby 或 global。对于安装，省略 mode 会被视为 standby。对于更新、清理、卸载和分支切换，省略的 mode 会原样转发，以便 HelloAGENTS 可以先复用该 CLI 已跟踪或检测到的模式。如果你不提供 HELLOAGENTS，一次性安装脚本现在的行为就像普通的包安装：它们只安装或更新包，不会自动部署任何宿主 CLI。对于自定义 tarball 或包规范，请设置 HELLOAGENTS_PACKAGE，而不是 HELLOAGENTS_BRANCH。要确保刷新已安装的包，请在包命令之后优先使用 npm explore -g helloagents -- npm run sync-hosts -- ...。一次性 shell 和 PowerShell 包装脚本会自动检测 npm 11+，并且仅在该标志受支持的地方追加 --allow-scripts=helloagents。
宿主配置使用稳定的 helloagents-js 入口点和运行时根目录 ~/.helloagents/helloagents，因此 Node 全局包路径可以变化，而不会破坏受管理的钩子或 Codex notify。Codex 钩子使用独立的 ~/.codex/hooks.json，而不是向 config.toml 添加大型钩子块，并且 Codex 全局插件根目录及插件缓存现在都链接回同一个稳定的运行时根目录。Claude Code 全局安装使用 ~/.helloagents/host-projections/claude-marketplace 下的专用本地市场投影，Gemini 全局扩展打包使用 ~/.helloagents/host-projections/gemini，Grok Build 全局安装使用物化市场投影 ~/.helloagents/host-projections/helloagents-grok-marketplace，而 Cursor 全局安装使用精选的本地插件投影 ~/.helloagents/host-projections/cursor-local-plugin/helloagents，外加位于 ~/.cursor/plugins/local/helloagents 的真实复制安装目录，因此特定于宿主的打包与共享运行时根目录保持隔离，而不依赖仅符号链接的插件加载。

npm 命令

macOS / Linux：

Install to Codex in standby mode
HELLOAGENTS=codex npm install -g --allow-scripts=helloagents helloagents

Install to Codex in global mode
HELLOAGENTS=codex:global npm install -g --allow-scripts=helloagents helloagents

Update the package, then refresh Claude in standby mode
npm install -g --allow-scripts=helloagents helloagents@latest
npm explore -g helloagents -- npm run sync-hosts -- claude --standby

Switch to the beta branch, then refresh all CLIs in standby mode
npm install -g --allow-scripts=helloagents https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
npm explore -g helloagents -- npm run sync-hosts -- --all --standby

Clean Gemini integration before package uninstall
npm explore -g helloagents -- npm run uninstall -- gemini --standby
npm uninstall -g helloagents

Windows PowerShell：

Install to Codex in standby mode
$env:HELLOAGENTS="codex"; npm install -g --allow-scripts=helloagents helloagents

Install to Codex in global mode
$env:HELLOAGENTS="codex:global"; npm install -g --allow-scripts=helloagents helloagents

Update the package, then refresh Claude in standby mode
npm install -g --allow-scripts=helloagents helloagents@latest
npm explore -g helloagents -- npm run sync-hosts -- claude --standby

Switch to the beta branch, then refresh all CLIs in standby mode
npm install -g --allow-scripts=helloagents https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
npm explore -g helloagents -- npm run sync-hosts -- --all --standby

Clean Gemini integration before package uninstall
npm explore -g helloagents -- npm run uninstall -- gemini --standby
npm uninstall -g helloagents

安装包后，你也可以直接调用其 npm 脚本：

npm explore -g helloagents -- npm run deploy:global
npm explore -g helloagents -- npm run sync-hosts -- --all --standby
npm explore -g helloagents -- npm run cleanup-hosts -- codex --standby
npm explore -g helloagents -- npm run uninstall -- --all

全新安装仍可直接使用 HELLOAGENTS=target[:mode]。对于更新、分支切换，或对已安装包进行任何强制主机重新同步，上述显式的 npm run sync-hosts 步骤是确定性的路径。

一次性脚本

macOS / Linux：
bash
Install
HELLOAGENTS=codex curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Update
HELLOAGENTS=claude:standby HELLOAGENTS_ACTION=update curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Switch branch
HELLOAGENTS=all:global HELLOAGENTS_ACTION=switch-branch HELLOAGENTS_BRANCH=beta curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Cleanup host integration without uninstalling the package
HELLOAGENTS=codex:standby HELLOAGENTS_ACTION=cleanup curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Uninstall
HELLOAGENTS=gemini HELLOAGENTS_ACTION=uninstall curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/main/install.sh | sh

Windows PowerShell：
powershell
Install
$env:HELLOAGENTS="codex"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Update
$env:HELLOAGENTS="claude:standby"; $env:HELLOAGENTS_ACTION="update"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Switch branch
$env:HELLOAGENTS="all:global"; $env:HELLOAGENTS_ACTION="switch-branch"; $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Cleanup host integration without uninstalling the package
$env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

Uninstall
$env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex

shell 和 PowerShell 包装脚本现在会解析一次 HELLOAGENTS，在未指定目标时保持纯包安装/更新行为，在更新、分支切换和卸载前清除生命周期环境变量，然后运行一条显式的同步或清理路径。

分支切换

switch-branch 会先安装所请求的 npm/GitHub ref，然后通过 npm 脚本同步主机 CLI，因此它在更新期间不依赖 helloagents 可执行文件：
bash
helloagents switch-branch beta
helloagents switch-branch beta claude --global
helloagents branch beta --all --standby

直接使用 helloagents switch-branch ... 命令时，也会在其内部的 npm install 和主机同步步骤之前清除过期的 HELLOAGENTS 生命周期环境变量。
当你只想更改包而不立即同步宿主 CLI 时，请使用普通的 npm 命令：

npm install -g --allow-scripts=helloagents https://github.com/hellowind777/helloagents/archive/refs/heads/beta.tar.gz
npm install -g --allow-scripts=helloagents helloagents@latest
npm explore -g helloagents -- npm run uninstall -- --all
npm uninstall -g helloagents

待机模式文件

| CLI | 写入或更新的文件 | 清理行为 |
|-----|--------------------------|------------------|
| Claude Code | ~/.claude/CLAUDE.md、~/.claude/settings.json、~/.claude/helloagents -> ~/.helloagents/helloagents | 移除受管理的标记块、HelloAGENTS 钩子/权限以及符号链接 |
| Cursor | ~/.cursor/hooks.json、~/.cursor/helloagents -> ~/.helloagents/helloagents | 移除受管理的 Cursor 钩子以及运行时符号链接 |
| Gemini CLI | ~/.gemini/GEMINI.md、~/.gemini/settings.json、~/.gemini/helloagents -> ~/.helloagents/helloagents | 移除受管理的标记块、HelloAGENTS 钩子以及符号链接 |
| Grok Build | ~/.grok/AGENTS.md、~/.grok/hooks/helloagents.json、~/.grok/helloagents -> ~/.helloagents/helloagents | 移除受管理的标记块、受管理的 Grok 钩子文件以及符号链接 |
| Codex CLI | ~/.codex/AGENTS.md、~/.codex/config.toml、~/.codex/hooks.json、~/.codex/helloagents -> ~/.helloagents/helloagents、受管理的备份 | 移除受管理的标记块、受管理的配置键、受管理的钩子、符号链接以及最新的受管理备份 |

全局模式文件

| CLI | 安装方式 | 涉及的文件 |
|-----|----------------|----------------|
| Claude Code | 原生插件安装 | ~/.helloagents/host-projections/claude-marketplace、由宿主管理的 Claude Code 插件元数据/缓存 |
| Cursor | 原生本地插件安装 | ~/.helloagents/host-projections/cursor-local-plugin/helloagents，具体化为 ~/.cursor/plugins/local/helloagents |
| Gemini CLI | 原生扩展安装 | ~/.helloagents/host-projections/gemini、~/.gemini/extensions/helloagents |
| Grok Build | 原生市场 + 插件安装 | ~/.helloagents/host-projections/helloagents-grok-marketplace、~/.grok/config.toml、~/.grok/installed-plugins/registry.json、由宿主管理的 Grok 插件缓存 |
| Codex CLI | 原生本地插件链 | ~/.agents/plugins/marketplace.json、~/plugins/helloagents/ -> ~/.helloagents/helloagents、~/.codex/plugins/cache/local-plugins/helloagents/local/ -> ~/.helloagents/helloagents、~/.codex/config.toml、~/.codex/hooks.json、~/.codex/helloagents -> ~/.helloagents/helloagents |
在全局模式下，HelloAGENTS 现在会自动尝试宿主原生的安装命令。Claude Code 使用本地市场投影，Gemini 使用本地扩展投影，Grok Build 使用物化的本地市场投影，Cursor 在 ~/.cursor/plugins/local/helloagents 下刷新一个真实的本地插件副本，而 Codex 则保持链接回同一个稳定的运行时根目录，因此安装、更新、分支切换、模式切换、清理和卸载都会针对同一个一致的运行时副本进行刷新。如果宿主命令不可用，请手动运行相同的命令：

/plugin marketplace add "~/.helloagents/host-projections/claude-marketplace"
/plugin install helloagents@helloagents
gemini extensions link "~/.helloagents/host-projections/gemini"
grok plugin marketplace add "~/.helloagents/host-projections/helloagents-grok-marketplace"
grok plugin install "~/.helloagents/host-projections/helloagents-grok-marketplace/plugins/helloagents" --trust

对于 Cursor，请将 ~/.helloagents/host-projections/cursor-local-plugin/helloagents 的内容复制到 ~/.cursor/plugins/local/helloagents。在 Windows 上，不要依赖指向 ~/.cursor 外部的符号链接或目录联接。

对于 Claude Code，CLI 还会尝试等效的 claude plugin marketplace add ... 和 claude plugin install ... 命令。市场名为 helloagents，插件名也是 helloagents，因此安装目标是 helloagents@helloagents。全局安装后请重启宿主 CLI。

当你将 Claude 或 Gemini 切回待机模式时，HelloAGENTS 会先移除原生插件或扩展。如果清理失败，宿主会保持被跟踪为 global，而不是在待机模式之上静默叠加。

Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。

聊天中的命令

典型流程

| 目标 | 使用 |
|------|-----|
| 澄清需求、比较方案、确定范围与价值 | ~ask "should this become a full platform or just a thin wedge?" |
| 让 HelloAGENTS 选择路径并继续 | ~auto "add JWT login" |
| 在实现前审查计划 | ~plan "refactor payment module" |
| 根据清晰的请求或活动计划进行实现 | ~build "finish task 2 in the plan" |
| 构建完整的产品需求文档 | ~prd "modern dashboard for operations team" |
| 通过 /goal -> ~auto -> ~qa 运行一个长时间的 Codex 任务 | ~loop "finish the auth refactor" |
| 初始化或刷新项目工作流 | ~init |
| 验证当前工作 | ~qa |
| 生成提交信息并同步知识 | ~commit |

项目初始化与宿主全局部署

在待机模式下，未初始化的项目会获得更轻量的规则和显式的 ~command 入口点。在 ~init 写入项目级  标记后，项目即被视为已初始化。

在全局模式下，HelloAGENTS 默认在宿主级别应用完整规则。

项目知识库
本地模式

默认情况下，项目知识存放在项目内：

.helloagents/

该目录是本地知识、计划、状态和运行时目录。

仓库共享模式

当 project_store_mode = "repo-shared" 时：

- 本地 .helloagents/ 保留项目本地状态和运行时文件
- 稳定的知识和计划文件移动到 ~/.helloagents/projects//
- 同一 git 仓库的多个工作树可以共享相同的稳定知识

运行时状态和证据仍保留在工作项目本地：

- state_path
- .helloagents/sessions/active.json
- .helloagents/sessions///runtime.json
- .helloagents/sessions///artifacts/*.json

项目本地存储之外的临时会话

对于没有本地输出的只读工作，如果当前目录及其父目录都不包含项目本地的 .helloagents/ 目录，HelloAGENTS 会将短期运行时状态保存在用户级目录下：

~/.helloagents/runtime//

这里只存储短期的 STATE.md、runtime.json 和 artifacts/。可选的 events.jsonl 跟踪文件仅在启用跟踪模式时写入。它不是项目知识。过期的临时会话会通过 TTL 清理移除。

一旦任务创建或修改本地文件，或以其他方式在当前项目中留下本地输出，HelloAGENTS 会自动创建项目本地的 .helloagents/sessions///STATE.md，而不是将该任务仅保留在用户级临时运行时中。

知识创建规则

| 命令或设置 | 行为 |
|--------------------|----------|
| ~init | 初始化项目工作流并同步知识库 |
| kb_create_mode = 0 | 禁用自动知识更新 |
| kb_create_mode = 1 | 仅在知识库已存在时自动同步知识 |
| kb_create_mode = 2 | 对于编码任务，当知识库已存在或项目已初始化时，自动创建或同步知识库 |

工作流与交付

工作流阶段

HelloAGENTS 使用以下阶段模型进行结构化工作：

路由与分级 → 目标澄清 → 规划 → 实现 → 质量循环 → 收尾与归档

| 阶段 | 目的 |
|-------|---------|
| 路由与分级 | 决定任务应通过 ~ask、~plan、~build、~qa、~prd 还是自动流程执行 |
| 目标澄清 | 澄清目标、约束和成功标准 |
| 规划 | 准备计划文件并选择所需技能 |
| 实现 | 实现并运行本地检查 |
| 质量循环 | 审查、运行命令并检查契约和证据 |
| 收尾与归档 | 更新状态、知识和收尾证据 |

HelloAGENTS 还在 bootstrap.md / bootstrap-lite.md 中保留了一个始终启用的核心规则层。
该层将智能体锚定为可信环境中的有能力执行者，阻止将责任转嫁给用户或其他工具，强制在宣布受阻前穷尽替代路径，纠正提案偏见，区分真实外部约束与内部惯性，并保持用户可见措辞使用同一种语言，除非代码标识符、命令、路径、配置键或必要的专有名词必须保持不变。

交付层级

| 层级 | 典型用途 |
|------|-------------|
| T0 | 只读分析、想法探索、比较 |
| T1 | 低风险聚焦修复或显式验证 |
| T2 | 多文件功能、新项目、结构化计划 |
| T3 | 高风险或不可逆工作，如认证、支付、数据库、发布、生产操作 |

UI 工作流

UI 工作遵循以下优先级：

1. 当前 plan.md 或 PRD 中的 UI 决策
2. .helloagents/DESIGN.md
3. 任何已加载的 hello-ui 实现和验证规则；所有 UI 工作仍必须满足共享的 UI 质量基线

对于较重的 UI 工作，contract.json 可以要求：

- ui.styleAdvisor.required
- ui.visualValidation.required

这些要求通过当前会话的 artifacts/advisor.json 和 artifacts/visual.json 关闭。

验证来源

验证命令按以下顺序检测：

1. 逻辑路径 .helloagents/verify.yaml
2. 包管理器脚本，如 package.json
3. 自动检测

当 project_store_mode = "repo-shared" 时，逻辑路径 .helloagents/verify.yaml 从共享项目存储中解析。

配置

配置文件：

~/.helloagents/helloagents.json

默认结构：

{
"output_language": "",
"output_format": true,
"notify_level": 0,
"ralph_loop_enabled": true,
"guard_enabled": true,
"kb_create_mode": 1,
"project_store_mode": "local",
"auto_commit_enabled": true,
"commit_attribution": "",
"install_mode": "standby",
"host_install_modes": {}
}

| 键 | 默认值 | 含义 |
|-----|---------|---------|
| output_language | "" | 除非已设置，否则跟随用户语言 |
| output_format | true | 主智能体直接面向最终用户的收尾输出使用 HelloAGENTS 布局；中间、委托和子智能体输出保持自然 |
| notify_level | 0 | 0 关闭，1 桌面，2 声音，3 两者 |
| ralph_loop_enabled | true | 对显式 ~qa / ~loop 或必需的收尾门运行 QA 停止门 |
| guard_enabled | true | 阻止危险命令 |
| kb_create_mode | 1 | 0 关闭，1 自动同步现有 KB，2 为编码任务自动创建或同步 KB |
| project_store_mode | "local" | local 或 repo-shared |
| auto_commit_enabled | true | 当验证通过且工作树发生变化时，在收尾时自动创建本地提交；false 仅跳过自动提交 |
| commit_attribution | "" | 追加到提交消息的可选文本 |
| install_mode | "standby" | 当前默认安装模式 |
| host_install_modes | {} | 按 CLI 管理的模式映射，例如 { "codex": "standby" }；仅在主机设置成功后记录，并在回退到 install_mode 之前使用 |

auto_commit_enabled 仅在配置文件首次创建时初始化为 true。后续安装和更新只会填充缺失的键，不会覆盖你已有的值。

每个 CLI 如何集成

Claude Code

- standby 写入 ~/.claude/CLAUDE.md
- standby 使用受管理的 hooks 和权限更新 ~/.claude/settings.json
- standby 创建 ~/.claude/helloagents -> ~/.helloagents/helloagents
- global 模式使用 Claude Code 的插件系统
- 从 global 切换回 standby 时，会先移除原生插件；如果该清理失败，HelloAGENTS 会将 Claude 继续跟踪为 global

Gemini CLI

- standby 写入 ~/.gemini/GEMINI.md
- standby 使用受管理的 hooks 更新 ~/.gemini/settings.json
- standby 创建 ~/.gemini/helloagents -> ~/.helloagents/helloagents
- global 模式使用 Gemini 的扩展系统
- 从 global 切换回 standby 时，会先移除原生扩展；如果该清理失败，HelloAGENTS 会将 Gemini 继续跟踪为 global

Grok Build

- standby 写入 ~/.grok/AGENTS.md
- standby 在 ~/.grok/hooks/helloagents.json 写入一个受管理的全局 hooks 文件
- standby 创建 ~/.grok/helloagents -> ~/.helloagents/helloagents
- global 模式使用 Grok Build 的原生市场以及插件安装路径
- global 打包内容物化在 ~/.helloagents/host-projections/helloagents-grok-marketplace 下
- 从 global 切换回 standby 时，会先移除原生插件和市场源；如果该清理失败，HelloAGENTS 会将 Grok 继续跟踪为 global

Cursor

- standby 更新 ~/.cursor/hooks.json
- standby 创建 ~/.cursor/helloagents -> ~/.helloagents/helloagents
- global 模式使用 Cursor 的原生本地插件路径
- global 打包内容物化在 ~/.helloagents/host-projections/cursor-local-plugin/helloagents 下
- 安装的本地插件会被复制到 ~/.cursor/plugins/local/helloagents，因此 Cursor 不依赖外部符号链接目标
- 从 global 切换回 standby 时，会先移除本地插件副本；如果该清理失败，HelloAGENTS 会跳过 standby 注入

Codex CLI

Codex 默认由规则文件驱动。

- standby 写入 ~/.codex/AGENTS.md
- standby 写入一个可移植的受管理 model_instructions_file = "~/.codex/AGENTS.md"
- standby 写入一个受管理且可移植的 notify = ["helloagents-js", "codex-notify"] 命令用于收尾通知，因此重新安装、更新或迁移到另一台机器时无需重写绝对路径
- standby 将静默 Codex hooks 写入 ~/.codex/hooks.json
- Codex SessionStart 保持静默，并在运行时读取当前的 ~/.helloagents/helloagents.json，而不是将配置快照烘焙进 config.toml，因此首轮和压缩后的设置始终保持最新
- 安装和更新还会同步 ~/.codex/config.toml 中由 HelloAGENTS 管理的 Codex hook 信任状态，因此 Codex 0.129.0+ 不会对受管理的 hook 重复提示
- 该 hook 信任状态是基于当前绝对路径 ~/.codex/hooks.json 生成的机器本地元数据；与 model_instructions_file = "~/.codex/AGENTS.md" 不同，它不是可移植配置，应在每台机器上重新生成
- standby 会创建 ~/.codex/helloagents -> ~/.helloagents/helloagents
- global 模式会安装原生本地插件链，但通过将插件根目录、插件缓存和 ~/.codex/helloagents 链接回 ~/.helloagents/helloagents，将其保留为唯一受管理的运行时来源
- doctor、cleanup 和 uninstall 也会识别包装后的 notify 链，例如 --previous-notify ["helloagents-js", "codex-notify"]，因此 Codex App / Computer Use 包装器不会导致误报漂移或破坏 notify 恢复
- 对于 Codex 应用/插件发现，global 是原生路径；standby 仍是用于显式项目工作的更轻量默认值
- cleanup 仅移除由 HelloAGENTS 管理的 hook 信任条目，同时保持用户拥有的 hook 状态不变
- Codex hook 仅同步运行时状态并强制执行 Stop 门禁；它们不会注入 HelloAGENTS 规则或通过 hook 输出路由文本
- Codex closeout 会对 Stop hook 和原生 codex-notify 去重，因此一轮不会通知两次，并且当受管理的 Stop hook 处于活动状态时，无客户端的委托子完成事件会保持静默
- /goal 保持为 Codex 原生功能。当需要长时间运行的计划执行时，使用 helloagents codex goals enable 显式启用它
- 当前 OpenAI 文档仍将 /goal 标记为实验性，Codex 应用支持仍为预览版。因此 HelloAGENTS 将 /goal 视为可选的 Codex 原生加速器，而不是必需的运行时依赖
- 目标感知命令会从 tasks.md、contract.json 和 state_path 恢复；它们不会自动创建目标，也不会在 HelloAGENTS 验证和 closeout 之前将其标记为完成

验证

运行所有测试：

npm test

当前测试套件覆盖：

- 安装、更新、清理、卸载、分支切换和模式切换
- 针对直接 switch-branch 和包 preuninstall 的过期生命周期环境变量保护
- Windows .cmd / .bat 生命周期分发，且不会产生 Node DEP0190 警告
- 一次性 shell 和 PowerShell 生命周期分发，以及针对安装、更新、清理、卸载和分支切换的包装器环境变量清理和模式路由规则
- Claude、Gemini、Grok、Cursor 和 Codex 主机集成行为，包括从 global 到 standby 的清理以及失败的原生清理跟踪
- Codex 受管理的 model_instructions_file、notify、hooks.json、hook 信任状态、本地插件、marketplace 和缓存行为
- Codex 清理和规范受管理 notify 恢复规则，包括包装后的 --previous-notify 链
- Codex /goal 功能开关、长时间运行路由上下文和目标感知命令契约
- helloagents doctor
- 项目存储与 repo-shared 行为
- 工作区会话作用域的 state_path、运行时信号与证据
- 运行时注入、路由、守卫、验证、视觉证据、交付门禁、收尾去重、子代理包装与通知抑制，以及原生安装失败后的成功模式跟踪
- 跨 Claude Code、Gemini CLI、Grok Build、Cursor 和 Codex CLI 的端到端主机配置写入、更新、清理、卸载、模式切换和分支切换流程
- README 与技能契约对齐

常见问题

docs/ 的作用是什么？

docs/ 是面向用户和 AI 代理的参考资料。它可能滞后于实现；运行时行为由源代码、规则模板、技能、模板和测试定义。

这是一个 CLI 工具还是一个提示框架？

两者都是。

- cli.mjs 处理安装、更新、清理、诊断和主机配置
- 规则模板定义加载的工作流规则
- skills/ 定义特定任务的行为
- scripts/ 提供用于路由、守卫、通知、验证、状态和证据的运行时辅助工具

我应该使用 ~init 还是 --global？

当你想初始化某个项目工作流并同步项目知识时，在仓库内使用 ~init。

当你想在受支持的 CLI 之间进行主机级部署时，使用 helloagents --global。

standby 和 global 有什么区别？

standby 更轻量且更明确。它将规则部署到选定的 CLI，同时让每个仓库保持未初始化状态，直到你运行 ~init。

global 在主机级别广泛应用完整规则。Claude、Gemini 和 Grok 使用原生插件、扩展或市场安装。Cursor 和 Codex 使用原生本地插件路径；Cursor 具体会在 ~/.cursor/plugins/local/helloagents 下物化一个真实的插件副本。
如果你主要想要 Codex 应用/插件的可发现性，请使用 global。如果你主要想要更轻量、更明确的项目工作流，请保持 standby。

Codex 钩子会显示注入的内容吗？

不会通过钩子注入任何 HelloAGENTS 规则或路由文本。HelloAGENTS Codex 钩子只写入运行时状态并强制执行 Stop 门禁；成功的钩子保持静默，而被阻止或失败的钩子会显示必要的原因。

我可以关闭通知或守卫检查吗？

可以。

- 将 notify_level 设置为 0 以禁用通知
- 将 guard_enabled 设置为 false 以禁用命令守卫

npm uninstall -g helloagents 会移除项目知识吗？

不会。在移除包之前运行 npm explore -g helloagents -- npm run uninstall -- --all，以便 HelloAGENTS 可以复用每个 CLI 已跟踪或检测到的模式，并清理主机集成以及稳定的运行时副本。项目 .helloagents/ 文件和 ~/.helloagents/helloagents.json 会被有意保留，除非你自己移除它们。

故障排除

~help 无法识别

检查：

npm list -g helloagents
helloagents doctor

然后重启目标 CLI。

某个 CLI 看起来已安装但行为过时

运行：

helloagents doctor
helloagents update codex
helloagents --standby
helloagents --global

使用与您安装模式和目标 CLI 匹配的命令。

本地分支切换后 Codex 仍使用旧文件

刷新 Codex：

helloagents update codex

对于全局模式，您也可以运行：

helloagents --global

通知不工作

首先检查 notify_level。

- Windows：PowerShell 必须能够显示桌面通知或播放声音
- macOS：afplay 应可用
- Linux：安装 aplay、paplay 或 notify-send

Guard 阻止了您想要运行的命令

检查该命令。Guard 会阻止已知的破坏性操作，并对有风险的写入发出警告。如果您仍想禁用它：

{ "guard_enabled": false }

许可证

代码根据 Apache-2.0 许可。文档根据 CC BY 4.0 许可。

贡献

- Bug 报告：提交 issue
- 功能请求：提交 issue
- 欢迎提交 Pull Request

如果这个项目对您有帮助，star 就是最好的支持。

感谢 codexzh.com / ccodezh.com 对本项目的支持。