在 OpenHanako 上构建带记忆…

适用于使用 OpenHanako/Electron 桌面平台搭建和运维个人 AI 代理，并为其配置模型、记忆、技能、沙箱、多代理、定时任务和消息桥接。

适用场景

解决思路

1. 从 releases 页面获取 macOS Apple Silicon 版：下载 `.dmg`，挂载后拖入 Applications。
2. macOS 首次启动若被 Gatekeeper 拦截：右键应用 → Open → Open。
3. Windows 从 releases 运行 `.exe` 安装程序；遇到 SmartScreen 警告点击 More info → Run anyway。
4. 从源码构建：`git clone https://github.com/liliMozi/openhanako.git`。
5. 进入目录：`cd openhanako`。
6. 安装依赖：`npm install`。
7. 开发模式：`npm run dev`。
8. 生产构建：`npm run build`。
9. 运行测试：`npm test`。
10. 首次启动向导配置：选择 Language、填写 Your name、选择 Model provider（任何 OpenAI 兼容端点）。
11. 配置三种模型：`chat model`（如 `gpt-4o`、`deepseek-chat`）、`utility model`（如 `gpt-4o-mini`）、`utility large model`（如 `gpt-4o`）。
12. 配置 OpenAI provider：`baseURL` 为 `https://api.openai.com/v1`，`apiKey` 为 `process.env.OPENAI_API_KEY`。
13. 配置 DeepSeek provider：`baseURL` 为 `https://api.deepseek.com/v1`，`apiKey` 为 `process.env.DEEPSEEK_API_KEY`。
14. 配置本地 Ollama provider：`baseURL` 为 `http://localhost:11434/v1`，`apiKey` 为 `ollama`。
15. 配置 Qwen（Alibaba Cloud）provider：`baseURL` 为 `https://dashscope.aliyuncs.com/compatible-mode/v1`，`apiKey` 为 `process.env.DASHSCOPE_API_KEY`。
16. 按项目架构定位代码：`core/` 引擎编排与 Managers；`lib/memory/` 记忆系统；`lib/tools/` 内置工具；`lib/sandbox/` PathGuard 与 OS 隔离；`lib/bridge/` 平台适配；`server/` Fastify 5 HTTP+WebSocket；`hub/` Scheduler、ChannelRouter、EventBus；`desktop/` Electron 38+React 19；`tests/` Vitest；`skills2set/` 内置技能。
17. 通过统一 engine facade 使用 Managers：`AgentManager` 创建/加载/删除代理，`SessionManager` 管理会话，`ModelManager` 路由请求，`PreferencesManager` 管理设置，`SkillManager` 安装/启用/禁用/沙箱技能。
18. 代理配置存放在 `~/.openhanako/agents/<agent-id>/`，包含 `personality.md`、`memory/working.db`、`memory/compiled.md`、`desk/notes/`、`skills/`。
19. 编写人格模板 `personality.md`：定义身份、语气、约束；示例包含 calm/thoughtful、直接、记住过去对话、大任务前澄清、代码加注释、温暖专业、偶尔 dry humor、不用空洞肯定、删除文件前确认、长终端输出先总结。
20. 技能扩展代理能力：技能位于 `skills2set/`（内置）或按代安装。
21. 通过应用内 Skills UI 安装技能；或以代码调用 `skillManager.installFromGitHub({ repo: 'some-user/hanako-skill-weather', agentId: 'agent-abc123', safetyReview: true })`。
22. 技能定义格式：`SKILL.md` 放入 `skills2set`，frontmatter 包含 `name`、`version`、`description`、`tools`、`permissions`，正文写 agent instructions。
23. 编写自定义技能 JavaScript：在 `skills/my-skill/index.js` 导出 default 对象，含 `name`、`version`、`description`、`tools`；工具含 `name`、`description`、`parameters`、`execute`；示例 `fetch_weather` 调用 `https://wttr.in/...`。
24. 使用记忆系统：从 `./lib/memory/index.js` 导入 `MemoryManager`，用 `new MemoryManager({ agentId: 'agent-abc123' })` 创建。
25. 存储记忆事件：`await memory.store({ type: 'conversation', content: 'User prefers dark mode and terse responses', importance: 0.8 })`；`importance` 0.0–1.0，越高衰减越慢。
26. 查询相关记忆：`await memory.query({ query: 'user preferences', limit: 10, minRelevance: 0.5 })`。
27. 手动触发记忆编译：`await memory.compile()`；通常自动运行。
28. 理解记忆层级：工作记忆存 `working.db`（SQLite）快速衰减；编译记忆存 `compiled.md` 由 utility-large model 总结慢衰减；desk notes（Jian）存文件手动/不衰减。
29. 使用内置文件工具：`read_file` 参数 `path`；`write_file` 参数 `path`、`content`。
30. 使用内置终端工具：`run_command` 参数 `command`、`cwd`。
31. 使用内置浏览器/网络工具：`browse` 参数 `url`；`web_search` 参数 `query`。
32. 使用内置屏幕工具：`screenshot`。
33. 使用内置画布工具：`draw` 参数 `instructions`。
34. 使用内置代码执行工具：`execute_js` 参数 `code`。
35. 配置 PathGuard 沙箱访问层级：Tier 0 Denied 系统路径（`/System`、`/usr`、registry hives）；Tier 1 Read-only 代理 desk 外 home 目录文件；Tier 2 Read-write 仅 agent desk 文件夹；Tier 3 Full 用户确认后显式授权路径。
36. 启用 OS 级沙箱：macOS Seatbelt / Linux Bubblewrap 包裹技能进程。
37. 创建多代理：`import { createEngine } from './core/engine.js'`；`const engine = await createEngine();`。
38. 创建第二个代理：`await engine.agentManager.create({ name: 'Researcher', personalityTemplate: 'researcher.md', models: { chat: 'deepseek-chat', utility: 'gpt-4o-mini', utilityLarge: 'gpt-4o' } })`。
39. 代理间委派任务：`await engine.hub.channelRouter.delegate({ fromAgent: 'agent-abc123', toAgent: researchAgent.id, task: 'Find the top 5 papers on mixture-of-experts published in 2025', returnTo: 'agent-abc123' })`；结果自动回传。
40. 配置计划任务：`import { Scheduler } from './hub/scheduler.js'; const scheduler = new Scheduler({ agentId: 'agent-abc123' });`。
41. 创建 cron 任务：`scheduler.cron('daily-briefing', '0 9 * * *', async () => { await agent.run('Summarize my desk notes from yesterday and post to #briefing channel'); });`。
42. 创建 heartbeat：`scheduler.heartbeat('desk-watch', 300_000, async () => { const changed = await agent.desk.checkChanges(); if (changed.length > 0) { await agent.run('New files on desk: ' + changed.join(', ') + ' — summarize and notify me'); } });`。
43. 启动调度器：`scheduler.start();`。
44. 配置多平台 bridge：设置 `bridgeConfig`，含 `telegram`（`enabled`、`token`、`allowedUsers`）、`feishu`（`enabled`、`appId`、`appSecret`）、`qq`（`enabled`）。
45. 将 bridge 绑定到代理：`await engine.agentManager.setBridges('agent-abc123', bridgeConfig);`。
46. 使用 WebSocket 实时聊天流：连接 `ws://localhost:PORT/ws/agent-abc123`，发送 `{ type: 'chat', content: 'Summarize my project folder' }`，监听 `msg.type`：`chunk`、`tool_call`、`tool_result`、`done`。
47. 使用 HTTP 一次性任务：`POST http://localhost:PORT/api/agent/agent-abc123/run`，header `Content-Type: application/json`，body `{ task: 'List all .md files on my desk' }`，读取 JSON 结果。
48. 运行全部测试：`npm test`。
49. 运行指定测试文件：`npx vitest run tests/memory.test.js`。
50. Watch 模式：`npx vitest`。
51. 编写 Vitest 记忆测试：从 `vitest` 导入 `describe, it, expect, beforeEach`，从 `../lib/memory/index.js` 导入 `MemoryManager`，`beforeEach` 中用 `new MemoryManager({ agentId: 'test-agent', inMemory: true })` 并 `await memory.init()`；测试 store/query。
52. 修复 macOS 无法打开：`xattr -dr com.apple.quarantine /Applications/OpenHanako.app`。
53. 排查代理不响应：确认 API key 环境变量已设置且 base URL 可达；打开 DevTools（`Cmd+Option+I` / `Ctrl+Shift+I`）看 Console；确认 model name 与 provider 支持完全一致。
54. 修复记忆编译未触发：`await engine.agentManager.getAgent('agent-abc123').memory.compile({ force: true });`。
55. 技能安装被安全审查阻止：仅对受信任本地技能，调用 `await skillManager.installLocal({ path: './my-skill', agentId: 'agent-abc123', safetyReview: false })`；不要对不可信来源关闭。
56. 修复沙箱权限拒绝：检查 PathGuard tier；在桌面 UI 中 Agent Settings → Sandbox → Grant Path Access；或以程序请求提升到 Tier 3（触发用户确认）。
57. 处理 Windows Defender 对构建 `.exe` 误报：安装程序未签名，在 SmartScreen 点 More info → Run anyway；开发中可在 Windows Security 添加排除项。
58. 参考链接：Releases `https://github.com/liliMozi/openhanako/releases`；Issues `https://github.com/liliMozi/openhanako/issues`；Homepage `https://openhanako.com`；Contributing `https://github.com/liliMozi/openhanako/blob/main/CONTRIBUTING.md`；Security Policy `https://github.com/liliMozi/openhanako/blob/main/SECURITY.md`；License Apache 2.0。

适用边界 · 注意事项

• 不适用于不使用 OpenHanako 桌面代理平台的场景。
• 不适用于无法配置 OpenAI 兼容端点或本地模型服务的环境。
• 不适用于要求完全无沙箱、全盘直接读写且不愿逐项授权路径的场景。