企业官网建设流程全解析

1. 从一条波浪号说起：HelloAGENTS 的技能路由到底在解决什么问题

第一次翻 HelloAGENTS 的源码目录时，我盯着那个~前缀愣了几秒。做过 CLI 工具的人都知道，命令行里~通常代表用户主目录，但在这里它被赋予了完全不同的语义——它是一个命令路由的触发符。这个设计选择本身就很有意思，因为它意味着 HelloAGENTS 没有走传统的子命令树（比如hello agents skill run xxx），而是用了一个更轻量的前缀标记来区分"普通输入"和"路由指令"。

HelloAGENTS 这个项目，简单说就是一套面向终端环境的智能体编排框架。它的核心卖点有两个：一是内置了14 项开箱即用的技能（Skill），覆盖代码生成、文件操作、命令执行、文本处理等常见场景；二是设计了一套以~为入口的命令路由机制，让用户可以在对话流中直接触发特定技能，而不需要退出当前会话去敲另一条命令。如果你用过 Codex CLI 或者类似终端智能体工具，你会发现这类工具最大的痛点就是"技能调用"和"自然语言对话"之间的边界很模糊——用户说"帮我看看这个文件"，到底算对话还是算技能调用？HelloAGENTS 用~命令路由给出了自己的答案。

这篇文章适合两类人看：一类是正在用 HelloAGENTS 或者准备上手的人，想搞清楚这 14 项技能具体能干什么、~路由怎么用才顺手；另一类是自己在做终端智能体工具的开发者，想参考一下它的技能组织和路由设计思路。我会从整体架构讲到具体技能的实现细节，再讲到~命令路由的匹配逻辑，最后分享一些我在实际使用中踩过的坑和总结出来的技巧。全程尽量说人话，不堆术语，能上代码的地方就上代码。

2. 14 项技能的整体设计与分类逻辑

2.1 为什么是 14 项，而不是 10 项或 20 项

先说说这个数字。14 项技能不是随便定的，我翻了一下项目的技能注册表（skill registry），发现它的分类逻辑其实很清晰：按操作对象和按交互模式两个维度交叉划分。按操作对象分，有文件类、代码类、命令类、文本类；按交互模式分，有一次性执行类、持续会话类、后台任务类。两个维度交叉之后，再去掉一些重叠的、合并一些相似的，最后收敛到 14 这个数字。

这个设计思路的好处是，每项技能的职责边界很清楚，不会出现"这个功能到底该用哪个技能"的困惑。比如文件读取就是文件读取，不会和代码分析混在一起；命令执行就是命令执行，不会和脚本生成混在一起。相比之下，有些工具把"读文件"和"分析代码"塞进同一个技能里，结果就是参数列表长得吓人，用户根本记不住。

从工程角度看，14 项技能对应的是 14 个独立的 skill handler，每个 handler 有自己的输入 schema、输出格式和错误处理逻辑。这种模块化设计让技能可以独立测试、独立替换，也方便后续扩展。我注意到它的 skill 目录结构是这样的：

skills/ file_read/ index.ts schema.json file_write/ index.ts schema.json code_gen/ index.ts schema.json ...

每个技能一个目录，里面放实现和 schema。这种组织方式在 Node.js 生态里很常见，好处是新增技能只需要复制目录改内容，不需要动核心路由代码。

2.2 技能分类的四个象限

我把这 14 项技能按功能分成了四个象限，这样理解起来更直观：

这个分类不是官方文档里写的，是我自己用下来总结的。官方文档只列了技能名称和参数说明，没有做这种象限划分。但我觉得这个视角很有用，因为它能帮你快速判断：当前这个需求应该用哪类技能，以及这类技能有什么共同的注意事项。

比如第一象限的技能都是即时执行的，基本上毫秒级返回，你可以放心在对话流里频繁调用；第二象限的技能需要模型推理，耗时可能几秒到几十秒，最好配合进度提示；第三象限涉及系统调用，权限和安全性要特别注意；第四象限影响会话状态，调用前最好确认一下当前上下文。

2.3 技能注册与发现机制

HelloAGENTS 的技能注册用的是声明式注册 + 运行时发现的混合模式。声明式注册是指每个技能在package.json或者独立的 manifest 文件里声明自己的元信息，包括技能名、描述、参数 schema、权限要求等。运行时发现是指框架启动时会扫描 skills 目录，自动加载所有符合条件的技能。

这种设计的好处是，新增技能不需要修改核心代码，只需要在 skills 目录下新建一个符合规范的目录就行。坏处是，如果技能之间的依赖关系比较复杂，纯靠目录扫描可能会漏掉一些隐式依赖。我实测下来，HelloAGENTS 在这块处理得还算稳妥，它有一个dependency字段用来声明技能间的依赖，加载时会做拓扑排序。

技能发现的优先级是这样的：内置技能 > 用户自定义技能 > 远程技能（如果有的话）。同名技能会按优先级覆盖，所以你可以用自定义技能覆盖内置技能的行为。这个机制在定制化场景下很有用，比如你觉得内置的代码生成技能不符合团队规范，可以写一个自己的版本覆盖掉。

3.~命令路由的匹配逻辑与设计考量

3.1 为什么用~而不是/或!

这是我在读源码时最好奇的一个点。/在大多数 CLI 工具里已经被用作命令前缀了（比如 Slack 的 slash command），!在有些工具里表示"强制执行"或"shell 转义"。HelloAGENTS 选了~，我猜测有几个原因：

第一，~在键盘上位置靠左上角，敲起来顺手，而且和字母键距离适中，不容易误触。第二，~在自然语言里几乎不会出现在句首，所以用它做前缀可以最大程度避免和普通对话混淆。第三，~在数学和逻辑里常表示"近似"或"切换"，语义上和"切换到某个技能"有微妙的契合。

我试过在对话里输入~file_read ./test.txt，也试过直接说"帮我读一下 test.txt"，两种方式都能工作，但~方式的响应更快、更确定。因为~开头的输入会直接进入路由匹配流程，跳过自然语言理解阶段，省掉了一次模型调用。这在批量操作场景下差别很明显——你用~连续调十次文件读取，几乎感觉不到延迟；用自然语言说十次，每次都要等模型解析意图。

3.2 路由匹配的三层结构

~命令路由的匹配逻辑分三层：

第一层是前缀匹配。输入以~开头，就进入路由流程。这一层很简单，就是字符串判断。

第二层是技能名匹配。~后面的第一个 token 会被当作技能名去注册表里查找。这里支持模糊匹配和别名机制。比如~read可以匹配到file_read，~gen可以匹配到code_gen。别名是在技能注册时通过aliases字段声明的。

第三层是参数解析。技能名后面的内容会按照该技能的参数 schema 进行解析。支持位置参数和命名参数两种形式。位置参数就是按顺序传，比如~file_read ./test.txt；命名参数就是--key value形式，比如~file_read --path ./test.txt --encoding utf-8。

这三层结构的好处是职责清晰，每层只做一件事。前缀匹配负责分流，技能名匹配负责定位，参数解析负责传参。我在自己项目里也借鉴了这个设计，确实比把所有逻辑塞在一个大函数里好维护得多。

3.3 路由的优先级与冲突处理

当多个技能都能匹配同一个输入时，HelloAGENTS 的优先级规则是这样的：

1. 精确匹配优先于模糊匹配
2. 内置技能优先于自定义技能
3. 别名匹配优先于前缀匹配

举个例子，假设你有一个内置技能叫file_read，又自定义了一个技能叫file。当你输入~file_read ./test.txt时，精确匹配到file_read，没问题。当你输入~file ./test.txt时，会先尝试精确匹配file，发现自定义技能里有，就用自定义的。如果你输入~f ./test.txt，会先看有没有技能声明了f这个别名，有就用别名的，没有就做前缀匹配，找到第一个以f开头的技能。

这个优先级规则在实际使用中基本不会出问题，但有一个坑要注意：如果你自定义了一个技能，名字和内置技能的别名冲突了，可能会覆盖掉内置技能的别名。我踩过一次这个坑，自定义了一个叫read的技能，结果把内置file_read的read别名覆盖了，导致~read行为变了。后来我把自定义技能改名为my_read才解决。

4. 核心技能实操：从文件操作到命令执行

4.1 文件读取与写入的完整流程

文件读取技能（file_read）是我用得最频繁的一个。它的基本用法很简单：

~file_read ./package.json

但实际用起来，有几个参数值得注意：

~file_read --path ./package.json --encoding utf-8 --max-lines 100 --offset 50

• --encoding指定编码，默认是 utf-8，读 GBK 文件时要显式指定
• --max-lines限制读取行数，大文件时很有用
• --offset从第几行开始读，配合--max-lines可以做分页

我实测下来，读一个 10MB 的日志文件，不加--max-lines会直接把整个文件塞进上下文，token 消耗巨大。加上--max-lines 200之后，只读前 200 行，响应快了很多。这个技巧在处理大文件时特别实用。

文件写入技能（file_write）的用法类似：

~file_write --path ./output.txt --content "Hello World" --mode append

--mode支持overwrite、append、create三种模式。默认是overwrite，这个要特别注意——如果你不小心对一个重要文件用了默认模式，内容会被直接覆盖。我建议在写文件时养成显式指定--mode的习惯，尤其是对已有文件操作时。

注意：文件写入技能默认不会创建父目录。如果目标路径的父目录不存在，会直接报错。需要先手动创建目录，或者用--create-dirs参数（如果版本支持的话）。

4.2 代码生成与解释的配合使用

代码生成技能（code_gen）和代码解释技能（code_explain）是一对好搭档。我通常的用法是：先用code_gen生成一段代码，再用code_explain让它解释这段代码的逻辑，确认没问题后再写入文件。

~code_gen --language python --task "读取 CSV 文件并计算每列平均值" --output ./avg.py

--task参数是自然语言描述，--language指定目标语言，--output可选，指定了就直接写入文件，不指定就返回代码文本。

代码解释技能的用法：

~code_explain --path ./avg.py --detail high

--detail支持low、medium、high三档。low只给一句话概括，high会逐行解释并给出优化建议。我一般用medium，够用又不啰嗦。

这里有个经验：code_gen生成的代码质量和你给的--task描述详细程度强相关。我试过用"写个排序"这种模糊描述，生成的代码很通用但不够贴合需求；改成"写一个对整数数组做降序排序的 Python 函数，要求原地排序，时间复杂度 O(n log n)"之后，生成的代码直接能用。所以别偷懒，任务描述越具体越好。

4.3 命令执行与后台任务管理

命令执行技能（cmd_exec）是权限最敏感的一个。它的基本用法：

~cmd_exec --command "ls -la" --timeout 5000

--timeout指定超时时间，单位毫秒，默认 30000。超过这个时间命令会被强制终止。我建议对不确定耗时的命令显式设置超时，避免卡死。

后台任务技能（task_bg）用来跑长时间运行的命令：

~task_bg --command "python train.py" --name "training-job-1"

启动后会返回一个任务 ID，你可以用~task_status --id <task-id>查询状态，用~task_kill --id <task-id>终止任务。

这里有个坑：后台任务的输出默认不会实时回传，需要手动用~task_log --id <task-id>拉取。如果你跑的是一个需要看实时日志的训练任务，这个设计会有点不方便。我的做法是让训练脚本把日志写到文件里，然后用~file_read配合--offset做增量读取。

4.4 上下文压缩与会话恢复

上下文压缩技能（ctx_compact）是我觉得最被低估的一个技能。当对话轮次多了之后，上下文会越来越长，token 消耗越来越大，响应也越来越慢。ctx_compact可以把历史对话压缩成摘要，保留关键信息，丢弃冗余内容。

~ctx_compact --keep-recent 5 --summary-level medium

--keep-recent指定保留最近几轮对话不压缩，--summary-level控制压缩力度。我一般设--keep-recent 3，这样最近的交互细节还在，更早的内容被压缩成摘要。

会话恢复技能（session_resume）用来恢复之前的会话：

~session_resume --id <session-id>

每个会话有一个唯一 ID，启动时会在日志里打印。如果你忘了 ID，可以用~session_list列出最近的会话。

提示：ctx_compact压缩后的摘要会替换原始对话历史，这个操作不可逆。如果你觉得后续可能还需要查原始对话，建议先用~session_export导出备份。

5. 技能与路由的协同：实际工作流拆解

5.1 一个完整的代码审查工作流

我拿一个实际场景来串一下这些技能和路由的配合。假设你要对一个 Python 项目做代码审查，流程大概是这样的：

第一步，用~file_search找到所有 Python 文件：

~file_search --pattern "*.py" --dir ./src --recursive

第二步，对每个文件用~code_explain做解释和检查：

~code_explain --path ./src/main.py --detail high --check-style

第三步，把发现的问题用~file_write汇总到报告里：

~file_write --path ./review_report.md --content "..." --mode create

第四步，如果发现问题需要自动修复，用~code_gen生成修复建议：

~code_gen --language python --task "修复 main.py 中的未使用变量问题" --context ./src/main.py

这个流程里，~路由的作用是让每一步都能在同一个会话里完成，不需要退出重进。而且因为路由是确定性的，每一步的输入输出都很清晰，方便后续追溯。

5.2 批量文件处理的技巧

批量处理是~路由的强项。比如你要把某个目录下所有.txt文件转成.md：

~file_search --pattern "*.txt" --dir ./docs --recursive --output-list

拿到文件列表后，可以用循环（如果框架支持）或者手动逐个处理：

~file_read --path ./docs/a.txt ~file_write --path ./docs/a.md --content "<转换后的内容>" --mode create

这里有个效率技巧：如果框架支持管道操作，可以把file_search的输出直接传给file_read。我试过用~file_search ... | ~file_read这种写法，在支持管道的版本里能省不少事。不过要注意，管道操作对技能的输出格式有要求，不是所有技能都支持。

5.3 路由嵌套与组合调用

HelloAGENTS 支持一定程度的路由嵌套。比如你可以在一个技能调用里引用另一个技能的输出：

~code_gen --language python --task "处理文件" --input $(~file_read --path ./data.txt)

这种$(...)语法在 shell 里很常见，HelloAGENTS 借鉴了这个设计。不过实测下来，嵌套层数不建议超过两层，太深了可读性很差，而且调试困难。

另一个组合用法是用~路由触发一个技能链。有些版本支持~chain命令，可以预定义一串技能调用，然后一次性执行：

~chain --define "review:file_search -> code_explain -> file_write" ~chain --run review --args "./src"

这个功能我用的不多，因为定义链本身也要花时间，不如直接敲几条~命令来得快。但对于需要反复执行的固定流程，定义成链确实能省事。

6. 常见问题与排查技巧实录

6.1 技能找不到或匹配错误

问题现象：输入~file_read提示 "skill not found"。

排查思路：

1. 先确认技能名拼写是否正确，HelloAGENTS 的技能名是大小写敏感的
2. 用~skill_list列出所有已注册的技能，确认目标技能在列表里
3. 检查 skills 目录下是否有对应的技能目录，以及目录里是否有index.ts和schema.json
4. 如果技能是自定义的，检查package.json里的注册声明是否正确

我遇到过一次是因为技能目录名写成了file-read（连字符），但注册表里写的是file_read（下划线），导致匹配不上。改成一致就好了。

6.2 参数解析失败

问题现象：~file_read ./test.txt报错 "invalid arguments"。

排查思路：

1. 用~help file_read查看该技能的参数 schema
2. 确认位置参数和命名参数没有混用错误
3. 检查参数值里是否有特殊字符需要转义

常见的一个坑是路径里有空格。比如~file_read ./my docs/test.txt，空格会被当作参数分隔符，导致解析出两个参数。正确的写法是加引号：~file_read "./my docs/test.txt"。

6.3 命令执行权限被拒

问题现象：~cmd_exec --command "sudo apt update"报错 "permission denied"。

排查思路：

1. HelloAGENTS 默认不允许执行需要提权的命令，这是安全设计
2. 检查技能配置里的allowedCommands白名单
3. 如果确实需要执行，考虑用--elevated参数（如果版本支持），或者手动在终端执行

我的建议是尽量不要在智能体会话里执行提权命令，因为一旦出错影响面很大。需要提权的操作，手动在终端做更稳妥。

6.4 上下文溢出

问题现象：对话进行到一定轮次后，报错 "context length exceeded"。

排查思路：

1. 用~ctx_status查看当前上下文占用情况
2. 用~ctx_compact压缩历史对话
3. 如果压缩后还是超限，用~session_export导出当前会话，然后开新会话

我一般会在对话进行到 20 轮左右主动做一次ctx_compact，不要等到报错了再处理。主动压缩的体验更好，因为你可以控制压缩的力度和保留的内容。

6.5 技能执行超时

问题现象：~cmd_exec执行一个耗时命令，等了很久没返回。

排查思路：

1. 检查--timeout参数是否设置得太小
2. 用~task_bg改成后台任务执行
3. 检查命令本身是否有交互式输入等待，比如read命令

交互式命令是cmd_exec的一个盲区。如果命令需要用户输入（比如ssh登录后要输密码），cmd_exec会一直等待直到超时。这种场景建议用task_bg配合task_log来处理。

6.6 常见问题速查表

7. 我在实际使用中总结的几条经验

先说一个关于~路由的心得：不要把它当成万能入口。有些操作直接用自然语言说反而更高效，比如"帮我看看这个文件里有什么问题"，模型能自动判断该用哪个技能。~路由的优势在于确定性和速度，适合你已经明确知道要用哪个技能、传什么参数的场景。两者结合用，效率最高。

再说一个关于技能组合的体会：技能之间的数据传递尽量走文件，不要走上下文。比如code_gen生成的代码，如果直接传给file_write，中间会经过上下文，token 消耗大而且容易出错。更好的做法是code_gen直接输出到文件（用--output参数），然后file_write从文件读。这样数据不经过上下文，既省 token 又稳定。

最后分享一个排查路由问题的技巧：用~debug命令查看路由匹配的详细过程。当你输入一个~命令但行为不符合预期时，在命令后面加--debug，框架会打印出前缀匹配、技能名匹配、参数解析的每一步结果。这个功能帮我定位过好几次别名冲突的问题，非常实用。

这个项目后续还可以这样扩展：把常用的技能组合封装成自定义技能，比如"代码审查"可以封装成一个技能，内部依次调用file_search、code_explain、file_write。这样对外只需要一个~code_review命令，用起来更简洁。HelloAGENTS 的技能注册机制支持这种组合技能，只需要在 skill handler 里调用其他技能的 API 就行。