1. 项目概述：一个本地化的智能体命令行伙伴

如果你和我一样，每天都在终端里敲敲打打，处理着各种开发任务，那你肯定幻想过能有一个“数字副驾”——它不仅能理解你的自然语言指令，帮你写代码、查文档、分析日志，还能记住我们之前的对话上下文，甚至在你离开电脑时，还能默默帮你处理一些后台通知。今天要聊的 Hooman ，就是这样一个让我眼前一亮的工具。它不是一个运行在云端、需要你反复粘贴 API Key 的网页应用，而是一个完全跑在你本地机器上的、由 Bun 驱动、用 TypeScript 写的 AI 智能体命令行工具。

简单来说，Hooman 把你的终端变成了一个能与大型语言模型（LLM）深度交互的工作站。它基于 Strands Agents SDK 构建，这意味着它天生就具备了构建复杂、可执行任务的智能体（Agent）的能力。而 Ink 库则为它赋予了漂亮的交互式终端界面，让你不用离开熟悉的命令行环境，就能享受近乎图形化的配置和聊天体验。它的核心价值在于“本地化”和“集成化”：你的对话历史、配置、乃至智能体学到的“技能”（Skills），都安静地躺在 ~/.hooman 目录下，完全由你掌控；同时，它通过支持 MCP（Model Context Protocol） 协议，可以无缝连接各种外部工具和服务（比如本地文件系统、数据库），极大地扩展了智能体的能力边界。

无论你是想快速执行一个一次性命令（ hooman exec "总结当前 Git 仓库的改动" ），还是开启一段持续的、有记忆的对话（ hooman chat ），抑或是想搭建一个能自动响应系统事件的后台守护进程（ hooman daemon ），Hooman 都提供了相应的入口。它支持从 Ollama 这类本地模型运行时，到 OpenAI、Anthropic、Google 等主流云服务在内的多种 LLM 提供商，让你可以根据自己的需求（隐私、成本、性能）灵活选择。接下来，我就结合自己深度使用和折腾的经验，带你从里到外拆解这个项目，分享如何把它调教成你得力的终端助手。

2. 核心架构与设计哲学解析

2.1 为什么选择 Bun + TypeScript + Strands SDK 这个技术栈？

初次接触 Hooman 的代码库，你可能会好奇它的技术选型。这背后其实是一套非常务实且现代化的组合拳。

首先， Bun 不仅仅是一个 JavaScript 运行时，它更是一个集打包、测试、包管理于一身的工具链。对于 Hooman 这样一个 CLI 工具来说，Bun 的启动速度远超 Node.js，这对于需要快速响应用户指令的交互式应用至关重要。此外，Bun 内置了对 .env 文件、TypeScript 和 JSX 的原生支持，这让开发过程变得极其顺畅，无需复杂的转译配置。从用户体验角度看，最终用户安装后，也能享受到更快的命令执行速度。

其次， TypeScript 是构建此类复杂 CLI 应用的“安全带”。智能体涉及大量的异步操作、工具调用、配置管理和状态维护，没有严格的类型系统，很容易在回调地狱和动态类型中迷失。TypeScript 不仅能提前捕获大量潜在错误，其清晰的接口定义（比如 LLMConfig 、 MCPServer ）也极大地提升了代码的可读性和可维护性，这对于开源项目吸引贡献者非常重要。

最核心的，是 Strands Agents SDK 。在自行构建智能体时，我们需要处理很多底层细节：工具的定义与调用、对话历史的管理、LLM 响应的解析、思维链（Chain-of-Thought）的实现等。Strands SDK 将这些能力抽象成了一套高阶 API。Hooman 直接利用它来创建智能体实例、管理会话状态、处理工具执行流。这意味着开发者可以更专注于 Hooman 特有的功能逻辑（如 CLI 交互、配置管理、MCP 集成），而不是重新发明轮子。这种“站在巨人肩膀上”的做法，保证了项目在智能体核心逻辑上的稳定性和先进性。

2.2 Ink 驱动的 TUI：在终端里获得图形化体验

传统的 CLI 工具配置，往往需要用户手动编辑 JSON 或 YAML 文件，对新手不够友好。Hooman 通过 Ink 库实现了终端用户界面（TUI），带来了革命性的配置体验。运行 hooman configure 后，你会进入一个全屏的、支持键盘导航的交互界面。

这个界面巧妙地管理了四块核心配置：

1. 应用配置 ：直接修改 config.json ，比如切换 LLM 提供商和模型。
2. 指令编辑 ：调用你的默认编辑器（ $VISUAL 或 $EDITOR ）来修改 instructions.md 。这个文件的内容会作为系统提示词（System Prompt）的一部分，用来塑造智能体的行为和性格。
3. MCP 服务器管理 ：以表单形式添加、编辑或删除 MCP 服务器，支持 stdio 、 streamable-http 、 sse 三种连接方式，并可以设置环境变量和工作目录。
4. 技能管理 ：可以搜索公共技能目录、安装新技能、刷新或移除已安装技能。所有操作都有确认步骤，防止误操作。

这种设计极大地降低了使用门槛。用户无需记忆复杂的 JSON 结构或文件路径，在一个界面内就能完成所有设置。Ink 通过 React 组件模型来构建 TUI，使得 Hooman 的界面代码结构清晰，易于扩展。例如，未来要增加一个“主题切换”功能，只需要添加一个新的 React 组件到配置流中即可。

2.3 模块化工具箱与权限控制思想

Hooman 一个非常精妙的设计是它的 工具包（Toolkit）分级系统 。这不是一个简单的“开/关”开关，而是一个根据使用场景和信任级别划分的权限模型。通过 --toolkit lite|full|max 参数，你可以动态调整智能体在当前会话中可用的工具集。

• lite （轻量级） ：这是最安全、最基础的级别。智能体只能使用时间、网络请求（fetch）、长期记忆（如果启用）以及你通过配置流程安装的“技能”和 MCP 服务器提供的工具。它无法直接访问你的文件系统或执行 Shell 命令。适合处理一些信息查询、总结等不涉及本地数据操作的任务。
• full （完整版） ：在 lite 的基础上，增加了文件系统操作、Shell 命令执行以及“思考”（thinking）工具。这意味着智能体可以读写文件、运行系统命令、进行复杂的推理规划。 这是大多数开发任务所需的级别 ，但使用时需要保持警惕。
• max （最大化） ：在 full 的基础上，进一步授予了技能管理和 MCP 配置管理的工具。这意味着智能体可以自行安装、更新或移除技能，甚至修改 MCP 服务器连接。 这个级别权限极高，应仅在完全受控的环境或深度调试时使用。

这个设计体现了“最小权限原则”。在 hooman daemon （守护进程）模式下，工具调用是 自动批准 的，因此为守护进程选择一个恰当的 toolkit 级别（通常是 lite ）就显得尤为重要，可以避免后台任务执行危险操作。而在交互式的 chat 或 exec 模式下，Hooman 默认会 请求用户批准 每一次工具调用（除非在 config.json 的 tools.allowed 列表中预先放行），这给了用户最终的控制权。

3. 从零开始：安装、配置与初体验

3.1 环境准备与快速启动

Hooman 的核心依赖是 Bun 。如果你还没有安装，可以去官网根据你的操作系统获取安装脚本。通常一行命令就能搞定。确保你的 Bun 版本在 1.0.0 以上。

最快体验 Hooman 的方式是使用 npx 或 bunx ，这不需要你先克隆仓库或全局安装。

# 使用 npm/npx
npx hoomanjs configure
npx hoomanjs chat

# 使用 Bun
bunx hoomanjs configure
bunx hoomanjs chat

第一次运行 configure 命令时，它会引导你完成初始化设置，主要就是选择 LLM 提供商和模型。完成之后，就可以直接开始 chat 了。如果你想更深入地参与开发，或者希望拥有一个全局可用的 hooman 命令，可以克隆项目并本地链接。

# 克隆项目
git clone https://github.com/vaibhavpandeyvpz/hooman.git
cd hooman

# 安装依赖
bun install

# 在开发模式下运行（查看帮助）
bun run src/cli.ts --help
# 或使用开发别名
bun run dev -- --help

# 将 CLI 链接到全局（方便测试）
bun link
# 之后就可以直接使用 `hooman` 命令了
hooman --help

实操心得 ：对于长期使用，我推荐使用 bun link 的方式。这样你既可以使用全局的 hooman 命令，又能在项目目录下直接修改源码，修改会即时生效，非常适合调试和添加自定义功能。

3.2 核心配置详解：打造你的专属智能体

所有的配置都存储在 ~/.hooman 目录下。理解这几个核心文件，你就掌握了 Hooman 的命脉。

1. config.json ：大脑与行为设定 这是最重要的配置文件，由 hooman configure 界面管理。我们拆开看一个典型的 Ollama 配置：

{
  "name": "MyAssistant", // 智能体名字，会用在对话中
  "llm": {
    "provider": "ollama", // 核心：选择 LLM 服务
    "model": "qwen2.5:7b", // 模型名称，Ollama 需提前 pull
    "params": {} // 可传递模型特定参数，如 temperature, top_p
  },
  "tools": {
    "allowed": [] // 预批准的工具列表。为空则每次调用都需手动确认
  },
  "ltm": { // 长期记忆 (Long-Term Memory)
    "enabled": false, // 是否启用
    "chroma": { // 使用 Chroma 向量数据库存储记忆
      "url": "http://127.0.0.1:8000",
      "collection": { "memory": "memory" }
    }
  },
  "compaction": { // 对话压缩设置
    "ratio": 0.75, // 当 token 数超过上限的75%时触发压缩
    "keep": 5 // 压缩后保留最近几条消息
  }
}

• llm.provider ：这是关键选择。对于追求隐私和零成本的开发者， Ollama 是首选。你需要先在本地运行 ollama pull <model-name> 拉取模型。对于需要最强能力的场景，可以配置 OpenAI 或 Anthropic 的 API。
• tools.allowed ：这是一个安全特性。如果你完全信任某个工具（比如一个只读的 fetch 工具），可以把它加到这里，这样调用时就不会弹出确认提示，交互会更流畅。
• ltm （长期记忆） ：这是一个高级功能。启用后，Hooman 会将对话中的重要信息存入向量数据库（如 Chroma）。当你在未来的对话中提到相关概念时，智能体可以“回忆”起来。这需要你额外运行一个向量数据库服务。
• compaction （压缩） ：LLM 有上下文窗口限制。当对话历史太长时，Hooman 会自动将早期的、不重要的消息总结成一条精简记录，以节省 Token，同时保留核心上下文。 ratio 和 keep 参数让你可以微调这个行为。

2. instructions.md ：人格与角色设定 这个文件是你的智能体的“宪法”。在这里，你可以定义它的身份、职责、说话风格和行事准则。例如：

# 系统指令

你是一个资深的软件开发助手，名叫“码匠”。你的语气专业、简洁且乐于助人。

## 核心原则
1.  安全第一：未经用户明确确认，绝不执行任何可能修改或删除文件的命令。
2.  代码质量：提供的代码应简洁、高效，并附上必要的注释。
3.  解释清晰：在给出解决方案时，同时解释其背后的原理。

## 技能偏好
- 优先使用 `fetch` 工具查询在线文档。
- 在分析代码时，可以建议重构，但需说明理由。

这个文件的内容会被插入到每次发给 LLM 的系统提示词最前面，因此它对智能体的行为有最直接的影响。你可以把它当成一个不断打磨的“提示词工程”实验场。

3. mcp.json ：能力扩展接口 这是 Hooman 与其他世界连接的桥梁。MCP 服务器可以赋予智能体新的工具。例如，配置一个本地文件系统服务器后，智能体就能读写你指定目录下的文件了。

{
  "mcpServers": {
    "myFiles": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Projects"],
      "env": {},
      "cwd": "/tmp"
    }
  }
}

4. skills/ 目录：即插即用的功能模块 技能（Skills）是比 MCP 工具更上层的、封装好的功能包。它们可以通过 hooman configure 界面从公共目录搜索和安装。安装后，其提供的工具会自动对智能体可用。这是社区共享和复用智能体能力的绝佳方式。

3.3 首次对话与基础命令实战

配置完成后，让我们开始第一次对话。最直接的方式是使用 chat 命令进入交互模式。

hooman chat

你会看到一个干净的提示符 > 。尝试问它：“帮我用 Python 写一个简单的 HTTP 服务器。” 智能体会开始思考，并可能请求调用工具（比如搜索网络或写文件）。在交互模式下，每次工具调用前都会向你请求确认（ [y/N] ），你按 y 批准， n 拒绝。

对于一次性任务， exec 命令更高效：

hooman exec "列出当前目录下所有扩展名为 .js 的文件，并按大小排序"

exec 会创建一个临时会话，执行完命令后立即结束，不会保存历史。

如果你想在后台处理一些自动化任务，比如监控一个日志文件的变化并自动摘要，就需要用到 daemon 。但 daemon 通常需要配合 MCP 服务器的通知频道使用，我们稍后详解。

注意事项 ：初次使用 chat 或 exec 时，如果选择了云服务提供商（如 OpenAI），请确保已在 config.json 的 params 中正确配置了 apiKey ，或者设置了对应的环境变量（如 OPENAI_API_KEY ）。如果使用 Ollama，请确保模型已下载且 ollama serve 正在运行。常见的连接错误通常源于此。

4. 核心功能深度剖析与实战

4.1 会话管理与状态持久化机制

Hooman 的 chat 和 daemon 命令的核心是 有状态的会话 。每个会话都有一个唯一的 ID，默认是随机生成的，但你可以通过 --session <session-id> 参数来指定或恢复一个特定的会话。

会话数据存储 ：所有会话数据都保存在 ~/.hooman/sessions/<session-id>/ 目录下。这里不仅保存了完整的对话消息历史，还包括了会话的元数据（如使用的工具包级别、关联的 MCP 服务器列表等）。这意味着你可以随时中断一个长时间的对话，几天后通过相同的 session-id 恢复，智能体会完全记得之前的上下文。

会话恢复实战 ：

# 开始一个新的聊天会话，并命名为“project-alpha”
hooman chat --session project-alpha
# ...进行一些关于项目架构的讨论...

# 退出后，在另一个终端或改天，恢复这个会话
hooman chat --session project-alpha
# 此时你可以直接问：“我们昨天讨论的数据库选型是什么？” 智能体会记得。

这个特性对于处理复杂的、需要多轮交互的任务（如代码重构规划、故障排查）极其有用。它打破了传统聊天机器人“健忘”的局限。

ACP 会话 ：当通过 hooman acp 命令以 Agent Client Protocol 模式运行时，会话会被单独存储在 ~/.hooman/acp-sessions/ 下。ACP 是一种标准协议，允许其他客户端程序（如编辑器插件、IDE）通过标准输入输出与 Hooman 交互。这种模式下的会话管理更侧重于与外部程序的集成。

4.2 MCP 集成：从本地工具到云端服务的桥梁

MCP 是 Hooman 能力扩展的基石。它允许你将任何可以通过标准输入输出、HTTP 或 SSE 通信的服务，变成智能体可以调用的工具。

4.2.1 配置一个实用的 MCP 服务器

让我们以最常用的 文件系统 MCP 服务器 为例，看看如何配置和用它来提升效率。

1. 安装服务器 ：首先，你需要一个实现了 MCP 协议的文件系统服务器。一个流行的选择是 @modelcontextprotocol/server-filesystem 。

   npm install -g @modelcontextprotocol/server-filesystem
   # 或直接通过 npx 调用，如配置示例所示
   

2. 通过 UI 配置 ：运行 hooman configure ，进入 “MCP Servers” 部分，添加一个新服务器。

   • Name : local_fs (自定义名称)
   • Type : 选择 stdio
   • Command : npx
   • Args : -y @modelcontextprotocol/server-filesystem /path/to/your/safe/directory

     重要安全提示 ：这里的路径参数定义了服务器可访问的根目录。 切勿设置为 / 或你的家目录 ！应该指定一个专门用于与 AI 共享的工作目录，例如 ~/Code/ai_sandbox 。这是最重要的安全实践。

   • Env 和 Cwd : 可按需设置环境变量和工作目录。

3. 使用 ：配置完成后，在新的 chat 会话中，智能体就会自动拥有这个文件系统服务器提供的工具（如 read_file , write_file , list_directory ）。你可以让它帮你读取日志、创建配置文件模板，或者分析项目结构。

4.2.2 守护进程与通知频道

hooman daemon 模式是自动化工作流的利器。它让 Hooman 变身为一个后台服务，监听特定 MCP 服务器发布的“通知频道”（Notification Channels）。

工作原理 ：

1. MCP 服务器可以在初始化时声明它支持发布通知到某些频道（例如 hoomanjs/channel 或 alerts/system ）。
2. 你启动守护进程，并订阅感兴趣的频道： hooman daemon --channel hoomanjs/channel 。
3. 当 MCP 服务器有事件发生（如：文件变动、定时任务触发、收到邮件）时，它会向订阅了该频道的客户端（即 Hooman 守护进程）发送一个通知。
4. Hooman 守护进程收到通知后，会将通知内容（ params.content ）作为新的用户提示，注入到其维护的持久化会话中，并让智能体处理。 关键点：在守护进程模式下，所有工具调用都是自动批准的（auto-approves） ，因此必须确保其工具包级别（ --toolkit ）和所连接的 MCP 服务器是绝对安全的。

一个想象的应用场景 ：你可以配置一个监控服务器日志的 MCP 服务。当它检测到错误日志时，就向 errors/logs 频道发布通知。Hooman 守护进程订阅了这个频道，收到通知后，自动分析错误信息，尝试查找解决方案，甚至执行一些预定义的修复命令（比如重启某个服务），并将处理结果记录到文件或发送给你。

4.3 技能系统：社区智慧的即插即用

技能（Skills）是 Hooman 生态中更高级的抽象。如果说 MCP 服务器提供了原始的“工具”（如读文件、执行命令），那么技能就是利用这些工具组合而成的、解决特定问题的“剧本”或“工作流”。

技能目录与安装 ：通过 hooman configure 界面，你可以浏览一个公共的技能目录。假设你发现一个名为 “git-helper” 的技能，它可能封装了一系列与 Git 仓库交互的复杂操作，比如“自动分析提交历史并生成变更报告”、“智能创建符合规范的分支”等。点击安装后，这个技能及其依赖的工具就会被下载到 ~/.hooman/skills/ 目录下。

技能的生命周期 ：安装后，技能提供的工具会在智能体构建时被加载。技能的元数据（如描述、作者、版本）和其自定义的指令（可能会修改系统提示词）都会生效。你可以通过配置界面“刷新”技能来更新，或“移除”它来禁用。

开发自己的技能 ：这是 Hooman 最激动人心的部分。你可以将自己的常用操作模式打包成一个技能。一个技能通常包含：

• package.json ：定义元数据和依赖。
• 一个主入口文件：导出工具定义和可选的初始化逻辑。
• 可选的 instructions.md ：描述该技能的特有行为。

例如，你可以为你常用的内部 API 测试流程创建一个技能，该技能提供 run_api_smoke_test 工具，内部会调用 fetch 工具访问多个端点并校验响应。这样，团队其他成员安装此技能后，就能用自然语言让智能体执行整套测试流程。

5. 高级配置、问题排查与性能调优

5.1 多 LLM 提供商配置实战与选型建议

Hooman 支持众多 LLM 提供商，配置的关键在于 config.json 中的 params 字段。这里针对几个主要提供商给出详细配置示例和选型建议。

Ollama（本地首选） ：

{
  "provider": "ollama",
  "model": "llama3.2:3b", // 推荐较小模型，响应快
  "params": {
    "temperature": 0.8, // 增加创造性
    "num_predict": 1024, // 限制生成长度
    "seed": 42 // 固定随机种子，使结果可复现
  }
}

• 优势 ：完全离线，零成本，数据隐私性最高。
• 劣势 ：能力取决于本地硬件和所选模型，复杂任务上可能不如顶级云模型。
• 选型建议 ：对于日常编码辅助、文本处理，7B-13B 参数的模型（如 llama3.2:3b , qwen2.5:7b , gemma2:9b ）在消费级 GPU 或强 CPU 上已有不错表现。确保运行 ollama pull <model> 提前拉取。

OpenAI / Anthropic（云端最强） ：

// OpenAI
{
  "provider": "openai",
  "model": "gpt-4o-mini", // 性价比高
  "params": {
    "apiKey": "sk-...", // 可从环境变量 OPENAI_API_KEY 读取
    "temperature": 0.7,
    "maxTokens": 2000
  }
}
// Anthropic
{
  "provider": "anthropic",
  "model": "claude-3-haiku-20240307", // 速度快，成本低
  "params": {
    "apiKey": "sk-ant-...",
    "temperature": 0.2 // Claude 对温度更敏感，较低值输出更稳定
  }
}

• 优势 ：目前综合能力最强的模型，适合处理最复杂的逻辑、创意和分析任务。
• 劣势 ：产生 API 费用，有网络延迟，数据需发送到第三方。
• 选型建议 ：将关键、复杂的任务（如架构设计、算法优化）路由到云模型。可以利用 Hooman 的会话持久化，先在本地模型（Ollama）上进行草稿对话，最后阶段切换到云模型进行润色和升华。

Groq / Moonshot（云端性价比之选） ：

// Groq (基于 LPU，推理速度极快)
{
  "provider": "groq",
  "model": "llama-3.1-8b-instant",
  "params": {
    "apiKey": "gsk_...", // 或环境变量 GROQ_API_KEY
    "temperature": 0.7
  }
}
// Moonshot (国内可用，长上下文出色)
{
  "provider": "moonshot",
  "model": "kimi-k2.5",
  "params": {
    "apiKey": "sk-...", // 或环境变量 MOONSHOT_API_KEY
    "maxTokens": 8192 // 充分利用其长上下文优势
  }
}

• 优势 ：Groq 的推理速度是革命性的，几乎无感知延迟；Moonshot 在国内访问顺畅，且上下文窗口巨大。
• 劣势 ：模型本身的能力可能略逊于 OpenAI/Anthropic 的顶级模型。
• 选型建议 ：Groq 非常适合需要快速、流式交互的场景（如实时对话辅助）。Moonshot 适合需要处理超长文档（如代码库分析、长报告总结）的任务。

5.2 长期记忆与对话压缩实战

长期记忆和对话压缩是处理长上下文对话的两个互补功能。

启用长期记忆 ：

1. 你需要先运行一个向量数据库服务。以 Chroma （一个轻量级开源向量数据库）为例：

   # 使用 Docker 运行 Chroma
   docker run -d -p 8000:8000 chromadb/chroma
   

2. 在 hooman configure 中，将 ltm.enabled 设为 true ，并填写 Chroma 的连接信息（默认 http://127.0.0.1:8000 ）。
3. 重启你的 Hooman 会话。

启用后，智能体在对话中会将你认为重要的信息（通常由 LLM 决定）进行嵌入（Embedding）并存储到向量库中。在后续对话中，当你提到相关概念时，它会自动进行向量相似度搜索，将“记忆”中的相关内容作为上下文插入到当前提示中。这相当于给了智能体一个“外部大脑”。

配置对话压缩 ：即使有长期记忆，当前会话的窗口也是有限的。 compaction 设置用于自动精简历史消息。

• "ratio": 0.75 ：当当前对话的 Token 数达到模型上下文窗口上限的 75% 时，触发压缩。
• "keep": 5 ：压缩时，保留最新的 5 条消息（通常是最近的几轮问答），将之前的所有旧消息总结成一条简短的背景信息。

例如，你进行了长达 50 轮的代码评审对话。当 Token 快满时，Hooman 可能会将前 45 轮对话总结为：“用户与助手讨论了项目 X 的模块 A、B 的设计，并确定了使用 Y 框架。用户提出了关于 Z 接口的性能疑虑。” 然后将这条总结和最新的 5 轮对话一起发送给 LLM。这样既保留了核心上下文，又节省了大量 Token。

实操心得 ：长期记忆功能目前还比较基础，其效果严重依赖于嵌入模型的质量和记忆的检索策略。对于高度结构化信息的记忆（如 API 密钥、项目特定规则），更好的做法是将这些信息直接写入 instructions.md 。对话压缩则非常实用，尤其是在使用按 Token 计费的云模型时，能有效控制成本。

5.3 常见问题排查与调试技巧

即使配置正确，在实际使用中也可能遇到各种问题。下面是一个快速排查指南。

问题现象	可能原因	排查步骤与解决方案
运行命令后无反应或立即退出	1. Bun 未正确安装或版本过低。 2. 项目依赖未安装。	1. 运行 bun --version 确认版本 ≥1.0.0。 2. 在项目目录下运行 bun install --frozen-lockfile 重新安装依赖。
Error: Failed to create agent / LLM 连接错误	1. Ollama 服务未运行。 2. API Key 错误或未设置。 3. 网络问题（针对云服务）。 4. 模型名称错误。	1. 对于 Ollama，运行 ollama serve 并确保模型已拉取 ( ollama list )。 2. 检查 config.json 的 params.apiKey 或对应的环境变量。 3. 尝试 curl 测试提供商 API 端点。 4. 核对提供商文档中的正确模型名称。
工具调用失败（权限错误、命令未找到）	1. MCP 服务器命令路径错误。 2. 工具执行的环境（cwd）不正确。 3. 系统缺少相关命令行工具。	1. 在 mcp.json 中检查 command 和 args ，确保可以在 Shell 中直接运行。 2. 检查 cwd 配置，确保是有效目录且有权限。 3. 确保工具依赖的命令（如 git , python3 ）已在系统 PATH 中。
chat 交互中工具调用无确认提示	config.json 中的 tools.allowed 列表包含了该工具。	这是预期行为。如果你希望恢复确认，可以从 allowed 列表中移除该工具。
智能体行为与 instructions.md 不符	1. instructions.md 格式错误或未被读取。 2. 会话缓存了旧的系统提示。	1. 检查 ~/.hooman/instructions.md 文件是否存在且为合法 Markdown。 2. 尝试启动一个 新的会话 （不使用 --session 或使用新的 ID），因为系统提示通常在会话初始化时加载。
daemon 进程不处理通知	1. 订阅的频道名称与 MCP 服务器发布的不匹配。 2. MCP 服务器未正确声明频道能力。 3. Daemon 会话工具调用被挂起等待批准。	1. 仔细核对频道名称，大小写敏感。 2. 检查 MCP 服务器的实现，确保其在 initialize 响应中正确声明了 capabilities 。 3. 记住： daemon 模式应使用 --toolkit lite 并确保其工具都是安全且自动批准的。
性能缓慢（特别是首次响应）	1. 本地模型（Ollama）首次加载。 2. 启用了长期记忆，向量检索慢。 3. 提示词过长，包含太多上下文。	1. 对于 Ollama，首次使用某模型需要加载，后续会快很多。 2. 考虑禁用 LTM，或优化 Chroma 性能（如使用本地持久化模式）。 3. 调整 compaction 设置，让压缩更早触发。检查 instructions.md 是否过于冗长。

高级调试技巧 ：

• 查看详细日志 ：在运行命令时设置 DEBUG=* 环境变量，可以输出 Strands SDK 和 Hooman 内部的详细日志，对定位复杂问题非常有帮助。

  DEBUG=* hooman chat
  

• 检查会话文件 ：如果某个特定会话出现问题，可以直接查看其存储文件 ~/.hooman/sessions/<session-id>/ 下的内容，了解保存的历史和状态。
• 简化复现 ：当遇到问题时，尝试用最简配置复现：换一个简单的模型（如 Ollama 的 tinyllama ），禁用所有 MCP 服务器和技能，使用全新的会话。这有助于判断问题是出在核心逻辑还是某个扩展组件上。

通过理解这些核心机制、掌握配置细节并善用排查技巧，你就能将 Hooman 从一个新奇玩具，逐步打磨成融入你日常工作流、真正提升效率的智能终端伙伴。它的可扩展性意味着，随着更多 MCP 服务器和社区技能的出现，它的能力边界还将不断拓宽。