# https://github.com/shiwenwen/hope-agent 项目说明书

生成时间：2026-07-20 12:20:41 UTC

## 目录

- [系统概览与三 Crate 架构](#page-1)
- [核心 AI 能力：记忆 / 知识空间 / 设计空间 / Goal-Workflow-Loop](#page-2)
- [工具集成与扩展：模型 Provider / MCP / Hooks / IM 渠道 / 浏览器](#page-3)
- [部署、运行与可靠性：多平台分发 / 沙箱与审批 / 自更新 / 后台保活](#page-4)

<a id='page-1'></a>

## 系统概览与三 Crate 架构

### 相关页面

相关主题：[核心 AI 能力：记忆 / 知识空间 / 设计空间 / Goal-Workflow-Loop](#page-2), [工具集成与扩展：模型 Provider / MCP / Hooks / IM 渠道 / 浏览器](#page-3), [部署、运行与可靠性：多平台分发 / 沙箱与审批 / 自更新 / 后台保活](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/shiwenwen/hope-agent/blob/main/README.md)
- [Cargo.toml](https://github.com/shiwenwen/hope-agent/blob/main/Cargo.toml)
- [docs/architecture/overview.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/overview.md)
- [docs/architecture/backend-separation.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/backend-separation.md)
- [docs/architecture/transport-modes.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/transport-modes.md)
- [crates/ha-core/src/lib.rs](https://github.com/shiwenwen/hope-agent/blob/main/crates/ha-core/src/lib.rs)
- [crates/ha-core/Cargo.toml](https://github.com/shiwenwen/hope-agent/blob/main/crates/ha-core/Cargo.toml)
- [crates/ha-cli/src/main.rs](https://github.com/shiwenwen/hope-agent/blob/main/crates/ha-cli/src/main.rs)
- [crates/ha-app/src/main.rs](https://github.com/shiwenwen/hope-agent/blob/main/crates/ha-app/src/main.rs)
</details>

# 系统概览与三 Crate 架构

Hope Agent 是一个面向个人/团队本地化与云端协作场景的智能体（Agent）平台。它把"对话、知识空间、后台任务、定时任务、视觉桥、设计空间、Chrome 扩展"等能力整合在一个统一的运行时之上，并通过三个互相解耦的 Cargo crate 把核心能力、命令行形态与桌面形态组织在同一个 Workspace 下 资料来源：[README.md:1-40]()。

## 一、设计目标与边界

项目明确把"复杂的工程能力"留给一个核心 crate（`ha-core`），让 CLI 与桌面端这两个上层形态都以"消费者"身份复用它，从而避免在 UI 与 CLI 之间复制业务逻辑 资料来源：[README.md:18-36]()。

这种划分带来三个直接收益：

- **共享同一份业务逻辑**：会话、工具、知识空间、设计空间、后台任务、定时任务等子系统都在 `ha-core` 内统一建模。
- **多形态分发**：CLI（`ha-cli`）面向开发者与服务器场景；桌面 App（`ha-app`）面向终端用户并承载 UI、托盘、IM 与窗口管理。
- **后端可替换**：根据 `docs/architecture/backend-separation.md` 的设计，桌面与 CLI 不绑定某个具体模型后端，可通过 transport 模式切换本地 / 远端 / 浏览器桥 资料来源：[docs/architecture/backend-separation.md:1-40]()。

## 二、Cargo Workspace 结构

仓库根 `Cargo.toml` 通过 `[workspace]` 把三个 crate 组织到一起，使它们可以共享一份锁文件与一致的依赖版本 资料来源：[Cargo.toml:1-30]()。三个 crate 的职责分别为：

| Crate | 形态 | 主要职责 |
| --- | --- | --- |
| `ha-core` | 库（lib） | 会话、工具、知识空间、后台任务、定时任务、设计空间、视觉桥等全部业务子系统的实现 |
| `ha-cli` | 可执行文件（bin） | 提供命令行入口，集成 `ha-core` 并以无界面方式对外提供能力 |
| `ha-app` | 可执行文件（bin） | 提供桌面端 GUI、托盘、系统集成、IM 通道等用户侧体验 |

`ha-core` 的入口在 `crates/ha-core/src/lib.rs`，它把上述子系统以模块形式向外暴露，使得 CLI 与 App 不需要重复实现业务逻辑 资料来源：[crates/ha-core/src/lib.rs:1-30]()。`ha-cli` 与 `ha-app` 都把 `ha-core` 声明为依赖，分别在 `crates/ha-cli/src/main.rs` 与 `crates/ha-app/src/main.rs` 中初始化并启动自己的运行时 资料来源：[crates/ha-cli/src/main.rs:1-20]() 资料来源：[crates/ha-app/src/main.rs:1-20]()。

## 三、运行时与传输模式

三 Crate 之间的边界不是"复制粘贴"，而是通过统一的传输抽象进行协作。`docs/architecture/transport-modes.md` 描述了几种典型的 transport：

- **本地直连**：UI/CLI 直接驱动 `ha-core`，适用于桌面端单机与开发场景。
- **HTTP/WS 服务**：`ha-core` 以服务端形态对外暴露，供独立 CLI 或第三方客户端调用。
- **浏览器桥（Chrome 扩展）**：通过 MV3 扩展把"用户已登录的 Chrome 浏览器"作为外部能力提供者，桌面与 CLI 通过桥调用浏览器 资料来源：[docs/architecture/transport-modes.md:1-60]()。

在 v0.17.0 引入的"视觉桥（Vision Bridge）"就使用了这一传输抽象：当主对话模型不支持视觉时，不是简单地丢弃图片，而是切换到独立配置的视觉模型把图像先转写为文本描述 资料来源：[docs/architecture/overview.md:1-40]()。

## 四、子系统全景与协作关系

在 `ha-core` 内部，多个高阶子系统是互相协作的：

```mermaid
flowchart LR
    UI[ha-app 桌面端] --> Core[ha-core]
    CLI[ha-cli 命令行] --> Core
    Bridge[Chrome 扩展桥] --> Core
    Core --> Session[会话与记忆]
    Core --> KS[知识空间]
    Core --> BG[后台任务]
    Core --> Cron[定时任务]
    Core --> DS[设计空间 v0.20]
    Core --> VB[视觉桥 v0.17]
```

- **会话与记忆**：所有形态的入口，负责把用户消息路由到合适的子系统。
- **知识空间**：v0.16.0 引入"来源 → 笔记"编译工作流，把网页、聊天媒体、本地文档归档为可检索的资料 资料来源：[README.md:60-90]()。
- **后台任务与定时任务**：v0.11.0 / v0.13.0 把后台任务升格为一等公民，并提供时区感知、权限隔离的定时任务能力。
- **设计空间**：v0.20.0 引入的全新子系统，承载"设计 → 产物交付"的闭环。
- **视觉桥**：v0.17.0 的降级与统一策略，让任何主对话模型都能"看见"图像。

这三 Crate 的总体形态可以概括为：**一个核心库、两种分发形态、一套传输抽象、多组协作子系统**，这也是 Hope Agent 能够在 v0.10.x 到 v0.20.1 的迭代中持续叠加新能力而不破坏既有分发链路的关键 资料来源：[docs/architecture/overview.md:20-60]()。

---

<a id='page-2'></a>

## 核心 AI 能力：记忆 / 知识空间 / 设计空间 / Goal-Workflow-Loop

### 相关页面

相关主题：[系统概览与三 Crate 架构](#page-1), [工具集成与扩展：模型 Provider / MCP / Hooks / IM 渠道 / 浏览器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture/memory.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/memory.md)
- [docs/architecture/knowledge-base.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/knowledge-base.md)
- [docs/architecture/design-space.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/design-space.md)
- [docs/architecture/goal.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/goal.md)
- [docs/architecture/workflow.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/workflow.md)
- [docs/architecture/loop.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/loop.md)
- [CHANGELOG.md](https://github.com/shiwenwen/hope-agent/blob/main/CHANGELOG.md)
</details>

# 核心 AI 能力：记忆 / 知识空间 / 设计空间 / Goal-Workflow-Loop

Hope Agent 的核心 AI 能力围绕四条相互衔接的能力主线展开：**记忆（Memory）**、**知识空间（Knowledge Space）**、**设计空间（Design Space）**、以及驱动长程自动化的 **Goal-Workflow-Loop**。它们共同构成 Hope Agent 从「短期对话」走向「长程智能体」的能力底座，分别承担状态沉淀、知识组织、产物设计与目标执行的不同职责。

## 总体架构与协作关系

这四套能力并非彼此独立，而是按时间与抽象层级串联：

- **记忆**负责把对话、工具调用与用户反馈沉淀为可检索的结构化对象；
- **知识空间**在此之上提供「来源 → 笔记」的编译流程，把外部学习材料与记忆中的片段整合为可复用的知识；
- **设计空间**承接知识空间，将多轮意图组织为可交付的产物；
- **Goal-Workflow-Loop** 则把上述能力封装为带目标、带工作流、带循环调度的执行单元。

```mermaid
flowchart LR
    U[用户/触发器] --> G[Goal 目标定义]
    G --> W[Workflow 工作流编排]
    W --> L[Loop 循环调度]
    L --> M[Memory 记忆]
    L --> K[Knowledge Space 知识空间]
    L --> D[Design Space 设计空间]
    M --> W
    K --> D
    D --> O[产物交付]
```

资料来源：[docs/architecture/goal.md:1-30]()、[docs/architecture/workflow.md:1-40]()、[docs/architecture/design-space.md:1-40]()。

## 记忆（Memory）

Hope Agent 在 v0.11.0 把后台任务升格为产品一等公民的同时，引入了**下一代结构化记忆**：不再只是把整段对话压成一个摘要，而是将记忆切分为可寻址、可关联、可被工作流直接消费的对象。记忆层的关键职责包括：

1. **结构化写入**：把会话中的事实、偏好、待办、工具结果分别落到不同记忆槽位；
2. **跨会话检索**：在新的会话或工作流启动时，按目标召回相关记忆片段；
3. **后台任务可见性**：与「后台任务」面板共享同一份生命周期模型，使记忆的写入与读取可在并发场景下保持一致。

资料来源：[docs/architecture/memory.md:1-60]()、[CHANGELOG.md:0.11.0-2026-06-21]()。

## 知识空间（Knowledge Space）

知识空间在 v0.16.0 补齐了完整的 **「来源 → 笔记」编译工作流**：先把网页、聊天媒体、本地文档等学习材料归档为「来源」，再由笔记编译器提炼为结构化笔记，供后续对话、记忆与设计空间引用。其核心特征：

- **来源归档**：原始材料保留可追溯性，避免对模型生成的笔记做无源引用；
- **笔记编译**：将异构来源统一为可检索的知识单元，并打上主题、实体、适用场景标签；
- **跨能力复用**：知识空间同时被记忆层引用（作为长期事实的来源）和被设计空间引用（作为产物素材）。

资料来源：[docs/architecture/knowledge-base.md:1-80]()、[CHANGELOG.md:0.16.0-2026-07-06]()。

## 设计空间（Design Space）

设计空间是 v0.20.0 的主线更新，承载「**设计空间与产物交付闭环**」：把零散的对话、记忆与知识，组织为有结构、有版本、可交付的产物。设计空间的出现，让 Hope Agent 第一次拥有了从「理解意图」到「交付成品」的明确产物层：

- **设计稿与产物清单**：以可编辑对象的形式承载 UI、文案、流程图等设计资产；
- **产物交付闭环**：与工作流串联，使设计稿可被自动验收、修改并回写到知识空间；
- **跨会话版本**：设计对象与记忆、知识一样具备跨会话一致性，避免每次重新生成。

资料来源：[docs/architecture/design-space.md:40-120]()、[CHANGELOG.md:0.20.0-2026-07-19]()。

## Goal-Workflow-Loop：长程执行单元

Goal-Workflow-Loop 是把上述三套能力串成长程自动化的执行框架，对应 v0.11.0 的「后台任务一等公民」与 v0.13.0 的「定时任务全面强化」两条主线：

- **Goal（目标）**：声明期望结果与约束条件，可附带权限、沙箱与可访问的知识空间；
- **Workflow（工作流）**：把目标拆解为有序的工具调用、子目标与分支；
- **Loop（循环）**：在定时、事件或失败重试的驱动下反复执行工作流，并结合记忆与知识空间持续修正。

定时任务在 v0.13.0 起支持独立时区（含夏令时）、独立权限沙箱与可访问的知识空间列表，使 Goal-Workflow-Loop 真正具备「无人值守」能力。

资料来源：[docs/architecture/goal.md:30-90]()、[docs/architecture/workflow.md:40-110]()、[docs/architecture/loop.md:1-70]()、[CHANGELOG.md:0.13.0-2026-06-27]()。

## 小结

记忆沉淀状态、知识空间组织素材、设计空间承载产物、Goal-Workflow-Loop 负责长程执行——这四者构成了 Hope Agent 的核心 AI 能力栈。理解它们各自的边界与协作点，是后续掌握后台任务、视觉桥（v0.17.0）等特性的基础。

资料来源：[docs/architecture/memory.md]()、[docs/architecture/knowledge-base.md]()、[docs/architecture/design-space.md]()、[docs/architecture/goal.md]()、[docs/architecture/workflow.md]()、[docs/architecture/loop.md]()。

---

<a id='page-3'></a>

## 工具集成与扩展：模型 Provider / MCP / Hooks / IM 渠道 / 浏览器

### 相关页面

相关主题：[系统概览与三 Crate 架构](#page-1), [核心 AI 能力：记忆 / 知识空间 / 设计空间 / Goal-Workflow-Loop](#page-2), [部署、运行与可靠性：多平台分发 / 沙箱与审批 / 自更新 / 后台保活](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture/provider-system.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/provider-system.md)
- [docs/architecture/mcp.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/mcp.md)
- [docs/architecture/mcp-server.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/mcp-server.md)
- [docs/architecture/hooks.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/hooks.md)
- [docs/architecture/im-channel.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/im-channel.md)
- [docs/architecture/browser.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/browser.md)
</details>

# 工具集成与扩展：模型 Provider / MCP / Hooks / IM 渠道 / 浏览器

## 定位与整体职责

Hope Agent 的"工具集成与扩展"层负责把外部能力以**可插拔、可降级、可观测**的方式接入主对话循环。它由五个相互正交的子系统组成：

- **Provider 系统**：管理 LLM、视觉、后台/分类等多种模型路由，并支持视觉桥（Vision Bridge）降级。
- **MCP 客户端**：按统一协议拉取外部工具/资源，并暴露给 Agent 调用。
- **MCP Server**：把 Hope Agent 自身的能力（如文件操作、笔记查询）以 MCP 协议对外发布，便于其他 Agent 复用。
- **Hooks**：在会话/工具/模型生命周期的关键节点注入用户脚本，做审计、改写、限流。
- **IM 渠道 & 浏览器后端**：把对话延伸到 Telegram/Slack/飞书/微信/邮件等 IM，以及可选的 Chrome MV3 扩展后端。

## 模型 Provider 系统与视觉桥

Provider 系统把"模型"抽象为带有多角色标签的统一适配层：主对话模型、视觉模型、后台摘要/分类模型、Embeddings 模型各自独立配置，互不耦合。资料来源：[docs/architecture/provider-system.md:1-40]()

当主对话模型不支持图片输入时，v0.17.0 引入的**视觉桥（Vision Bridge）**会用独立配置的视觉模型对用户上传的图片先做一次"翻译"，把图像信息转写为文本/结构化描述后再注入主模型，避免直接丢图。资料来源：[docs/architecture/provider-system.md:42-78]()

后台任务（如定时总结、向量召回）也可指定独立的"后台模型"，通过同一 Provider 接口进行调用与降级，所有错误会被统一归一为可重试/不可重试两类，以便上层做并发治理。资料来源：[docs/architecture/provider-system.md:80-110]()

## MCP 客户端与 MCP Server

### MCP 客户端

Hope Agent 作为 MCP **客户端**，通过 stdio/SSE/HTTP 三种传输与外部 MCP 服务器握手，按 JSON-RPC 风格拉取 `tools/list`、`resources/list`、`prompts/list`，并把工具描述注入到 Agent 的 system prompt / tool schema 中。资料来源：[docs/architecture/mcp.md:1-60]()

工具调用结果按 MCP 标准的 `content` 数组回传，Hope Agent 会把文本、图片、嵌入式资源统一归一化为内部消息片段，再交给对话循环，保证不同来源工具的输出对齐。资料来源：[docs/architecture/mcp.md:62-95]()

### MCP Server

镜像地，Hope Agent 也内置了一个 **MCP Server**，把自身能力（如 `hope.notes.search`、`hope.fs.read`、`hope.scheduler.list` 等）以 MCP 协议对外暴露，让其他兼容 MCP 的 Agent/工具可以反向调用。资料来源：[docs/architecture/mcp-server.md:1-50]()

权限与会话隔离在 Server 端复用主进程的沙箱与凭据，确保外部调用仍受定时任务的权限/沙箱规则约束，不会绕过用户既定的安全策略。资料来源：[docs/architecture/mcp-server.md:52-90]()

## Hooks 生命周期钩子

Hooks 提供一个**轻量、确定顺序**的回调链，覆盖以下生命周期节点：

| 阶段 | 触发时机 | 典型用途 |
|------|----------|----------|
| `before_message` | 用户消息进入会话前 | 改写/补充/PII 脱敏 |
| `before_model_call` | 请求模型前 | 注入额外上下文、限流 |
| `after_model_call` | 模型返回后 | 审计、改写、敏感词拦截 |
| `before_tool_call` | 工具执行前 | 二次鉴权、参数修正 |
| `after_tool_call` | 工具执行后 | 日志、脱敏、告警 |
| `session_end` | 会话结束 | 归档、清理 |

资料来源：[docs/architecture/hooks.md:1-120]()

Hooks 以 JS/Python 脚本形式存放于用户配置目录，按声明顺序串联执行；任一钩子都可以短路返回（short-circuit），中止后续流程并改写最终输出，这给幂等改写和合规拦截留出了统一入口。资料来源：[docs/architecture/hooks.md:122-160]()

## IM 渠道与浏览器后端

### IM 渠道

IM 渠道子系统把同一套"会话 → Agent → 工具"链路复用到外部 IM。每一类渠道（飞书/Telegram/Slack/企业微信/邮件）实现统一的 `ChannelAdapter` 接口，负责：

1. 长连接接收消息并映射为内部 `IncomingMessage`；
2. 把流式输出按渠道限制（Markdown/纯文本/分片长度）格式化；
3. 处理"打字指示"、表情回应、附件下载与回传。资料来源：[docs/architecture/im-channel.md:1-90]()

渠道与"会话/后台任务/定时任务"完全解耦：一个 IM 用户可以被映射到同一会话空间中的多个工作区，跨渠道上下文会按工作区粒度合并，避免不同来源的消息相互污染。资料来源：[docs/architecture/im-channel.md:92-140]()

### 浏览器后端

v0.12.0 起，Hope Agent 提供可选的 **Chrome 扩展浏览器后端**：MV3 扩展与本地原生消息桥通信，驱动用户**已登录的真实 Chrome**，以规避反爬检测并复用既有登录态。资料来源：[docs/architecture/browser.md:1-70]()

浏览器能力以工具形式暴露（导航、点击、表单填写、截图、提取 DOM），并复用 Hooks 的 `before_tool_call` 阶段对敏感站点做统一拦截与白名单控制。资料来源：[docs/architecture/browser.md:72-120]()

## 协作关系一览

```mermaid
flowchart LR
    U[用户 / IM / 浏览器] --> H[Hooks 链]
    H --> A[Agent 主循环]
    A --> P[Provider: 主对话 / 视觉桥 / 后台]
    A --> M[MCP 客户端]
    M --> E[外部 MCP Server]
    A --> S[内置 MCP Server]
    S --> E2[其他 Agent]
```

资料来源：[docs/architecture/provider-system.md:1-40]()、[docs/architecture/mcp.md:1-60]()、[docs/architecture/mcp-server.md:1-50]()、[docs/architecture/hooks.md:1-60]()、[docs/architecture/im-channel.md:1-60]()、[docs/architecture/browser.md:1-60]()

---

<a id='page-4'></a>

## 部署、运行与可靠性：多平台分发 / 沙箱与审批 / 自更新 / 后台保活

### 相关页面

相关主题：[系统概览与三 Crate 架构](#page-1), [工具集成与扩展：模型 Provider / MCP / Hooks / IM 渠道 / 浏览器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/deployment/docker.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/deployment/docker.md)
- [docs/architecture/self-update.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/self-update.md)
- [docs/architecture/permission-system.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/permission-system.md)
- [docs/architecture/sandbox.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/sandbox.md)
- [docs/architecture/reliability.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/reliability.md)
- [docs/architecture/background-jobs.md](https://github.com/shiwenwen/hope-agent/blob/main/docs/architecture/background-jobs.md)
</details>

# 部署、运行与可靠性：多平台分发 / 沙箱与审批 / 自更新 / 后台保活

## 1. 概述与边界

本页聚焦 Hope Agent 在**生产侧**的四条主线：跨平台分发形态、沙箱隔离与人工审批、自更新链路，以及后台任务保活与可靠性工程。它与「对话模型」「知识空间」等业务层模块相对独立，但在所有用户可见功能背后提供**部署、安装、续命与权限边界**的基础设施保障。

四个子系统之间的关系可以用一句话概括：**多平台分发决定 Agent 跑在哪种宿主之上；沙箱与审批决定它在宿主上能做什么；自更新决定它如何从旧版本平滑迁移；后台保活与可靠性决定它在长时间运行中不出事**。资料来源：[docs/architecture/reliability.md:1-12]()

## 2. 多平台分发

Hope Agent 通过双轨制交付产物：**桌面安装包**面向个人用户，**容器镜像**面向自托管与服务器用户。

- 桌面端覆盖 macOS / Windows / Linux（包括 x64 与 arm64），由统一的打包流水线产出。v0.20.1 即是补回 v0.20.0 缺失的 **Linux arm64 安装包**的修复版本；v0.10.3 则集中处理 macOS 唤醒崩溃、Windows 输入法冲突、黑窗等平台特定问题。资料来源：[CHANGELOG.md:0.20.1]() / [CHANGELOG.md:0.10.3]()
- 服务器端通过 `docs/deployment/docker.md` 描述的镜像分发，提供与桌面端一致的能力面，便于在自有基础设施内复用同一份配置。资料来源：[docs/deployment/docker.md:1-40]()

桌面与容器共享同一套核心进程，因此行为差异主要集中在系统集成层（自动更新器、托盘、输入法、权限弹窗），而非业务逻辑层。

## 3. 沙箱与审批

Hope Agent 把"权限"与"沙箱"拆成两个独立维度，再叠加为「审批」：

- **权限系统**（`permission-system`）：以工具为粒度定义能力集合，并在运行时由策略模块判定是否放行。资料来源：[docs/architecture/permission-system.md:1-30]()
- **沙箱**（`sandbox`）：对文件系统、网络、进程等系统资源施加硬性边界，把高风险操作隔离在受限命名空间内。资料来源：[docs/architecture/sandbox.md:1-30]()
- **审批**：当工具调用既未命中"自动放行"也未命中"硬拦截"时，进入人工审批队列，等待用户在 UI 内确认。

v0.13.0 的定时任务改造把这套机制下沉到**每个任务级别**——单个定时任务可独立配置权限与沙箱，并可单独声明可访问的知识空间范围，使长跑后台任务既不失控也不越权。资料来源：[CHANGELOG.md:0.13.0]()

## 4. 自更新

自更新模块（`self-update`）负责把当前进程从旧版本无缝迁移到新版本，关键设计点包括：

- **多通道**：桌面端走系统级更新器（与各平台打包格式绑定），容器端通过镜像 tag 替换。资料来源：[docs/architecture/self-update.md:1-30]()
- **原子性**：避免半新半旧状态残留；更新前后会持久化版本号与迁移标记。资料来源：[docs/architecture/self-update.md:30-60]()
- **回滚**：当新版本启动失败超过阈值时，回退到上一个稳定版本并上报遥测。资料来源：[docs/architecture/self-update.md:60-80]()

## 5. 后台保活与可靠性

后台任务在 v0.11.0 起被升格为"产品一等公民"，由此衍生出一套完整的保活与可靠性栈：

- **统一任务模型**：所有长跑动作（定时任务、轮询、后台索引）使用同一份 Job 描述。资料来源：[docs/architecture/background-jobs.md:1-30]() / [CHANGELOG.md:0.11.0]()
- **并发治理**：在后台任务面板中可视化运行态，避免互相阻塞。资料来源：[docs/architecture/background-jobs.md:30-60]()
- **可靠性工程**：以 `reliability.md` 为纲领，覆盖崩溃自愈、唤醒兼容、跨时区调度（含夏令时自动处理，v0.13.0 引入）等。资料来源：[docs/architecture/reliability.md:12-40]()

## 6. 子系统协作一览

| 子系统 | 主要文档 | 关键产物 / 行为 | 关联版本线索 |
| --- | --- | --- | --- |
| 多平台分发 | `docs/deployment/docker.md` | 安装包、容器镜像、平台修复 | v0.20.1 / v0.10.3 |
| 沙箱与审批 | `sandbox.md`、`permission-system.md` | 工具级权限、隔离命名空间、审批队列 | v0.13.0 |
| 自更新 | `self-update.md` | 多通道、原子迁移、回滚 | 持续演进 |
| 后台保活 | `background-jobs.md`、`reliability.md` | 统一 Job 模型、并发治理、崩溃自愈 | v0.11.0 / v0.13.0 |

资料来源：[docs/deployment/docker.md:1-40]() / [docs/architecture/sandbox.md:1-30]() / [docs/architecture/self-update.md:1-80]() / [docs/architecture/background-jobs.md:1-60]() / [docs/architecture/reliability.md:1-40]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：shiwenwen/hope-agent

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

## 1. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -d --name hope-agent -p 127.0.0.1:8420:8420 -v hope-data:/data ghcr.io/shiwenwen/hope-agent:latest
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -d --name hope-agent -p 127.0.0.1:8420:8420 -v hope-data:/data ghcr.io/shiwenwen/hope-agent:latest`
- 证据：identity.distribution | https://github.com/shiwenwen/hope-agent | docker run -d --name hope-agent -p 127.0.0.1:8420:8420 -v hope-data:/data ghcr.io/shiwenwen/hope-agent:latest

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/shiwenwen/hope-agent | host_targets=claude, mcp_host

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/shiwenwen/hope-agent | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/shiwenwen/hope-agent | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/shiwenwen/hope-agent | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/shiwenwen/hope-agent | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/shiwenwen/hope-agent | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/shiwenwen/hope-agent | release_recency=unknown

<!-- canonical_name: shiwenwen/hope-agent; human_manual_source: deepwiki_human_wiki -->