一、设计目标与边界

项目明确把"复杂的工程能力"留给一个核心 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 的职责分别为：

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 内部，多个高阶子系统是互相协作的：

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。

总体架构与协作关系

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

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

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。

定位与整体职责

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 提供一个轻量、确定顺序的回调链，覆盖以下生命周期节点：

资料来源：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

协作关系一览

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

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: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

Pitfall Log / 踩坑日志

项目：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