diff --git a/.github/workflows/docs-parity.yml b/.github/workflows/docs-parity.yml new file mode 100644 index 0000000..c09e72e --- /dev/null +++ b/.github/workflows/docs-parity.yml @@ -0,0 +1,17 @@ +name: Docs Parity + +on: + pull_request: + +jobs: + locale-parity: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Check en/zh locale parity + run: node scripts/check-locale-parity.mjs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3f382c4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,155 @@ +# Contributing to the Memoh Docs + +This guide covers how documentation is structured, translated, and checked in this repository. A complete Chinese version follows at the bottom (中文对照). + +## Keep the Two Locales in Lockstep + +- English pages live under `docs/`. +- Chinese pages live under `docs/zh/` with **identical paths**: `docs/guides/memory.md` mirrors to `docs/zh/guides/memory.md`. +- **Every content PR updates both locales.** English is the source of truth; the Chinese mirror lands **in the same PR**, never in a follow-up. + +## Use the Terminology Glossary + +Translate product terms exactly as listed. Where a term has a product UI key, the **bold UI label** in the docs must use the product's own locale string for that key — never a re-translation of the English value. + +| English | 中文 | Product UI key | +|---------|------|----------------| +| Bot | Bot | - | +| bot (prose) | Bot | - | +| workspace | 工作区 | `bots.tabs.container` | +| Platforms tab | 平台 | `bots.tabs.channels` | +| General tab | 通用 | `bots.tabs.general` | +| Desktop tab | 桌面 | `bots.tabs.desktop` | +| Memory tab | 记忆 | `bots.tabs.memory` | +| Schedule tab | 定时任务 | `bots.tabs.schedule` | +| Access Control | 访问控制 | `bots.tabs.access` | +| Providers | 模型服务商 | `sidebar.providers` | +| Add Provider | 添加服务商 | `provider.add` | +| Supermarket | 应用市场 | - | +| skill | 技能 | - | +| channel (concept) | 渠道 | - | +| session | 会话 | - | +| memory (long-term) | 长期记忆 | - | +| Help Center | 帮助中心 | - | + +Rule: bold UI labels must use the product's own locale string, never re-translated by value. If the product string behind a UI key changes, update the docs to match it. + +## Follow the Chinese Typography Rules (中文排版规则) + +Chinese pages follow these rules without exception: + +- Put a space between CJK characters and Latin letters or digits: 「在 Telegram 里发 3 条消息」. +- Use 「」 for quotes, never straight or curly Latin quotes. +- Use full-width punctuation in prose (,。:;?!); half-width only inside code, paths, and URLs. +- Address the reader as 「你」, never 「您」. +- Avoid the em dash ——; restructure the sentence instead. +- No AI-slop phrasing: no 「不只是…更是…」, no 「告别…」, no 「无缝」, no three-part parallel slogans (三连排比). +- Write definite statements. State what the product actually does; never hedge with 「以官网为准」「以实际为准」 or similar. + +## Give Deep-Linkable Headings Explicit Anchors + +FAQ entries and any heading meant to be deep-linked carry an explicit ASCII `{#id}`, **identical in both locales**: + +```md + +## How do I reset a session? {#reset-session} + + +## 怎么重置会话? {#reset-session} +``` + +This keeps links stable across locales and rewordings. + +## Write in the House Copy Style + +- Verb-first headings: "Create a provider", not "Provider creation". +- Exact numbers over vague claims: "256+ voices across 50+ languages", not "many voices". +- Every destructive action notes what it does **not** undo. Example: "Deleting a session removes its message history permanently; it does not delete memories already extracted from it." +- Example prompts end with a safety constraint. Example: "Summarize this thread and draft a reply, and ask me before sending anything." + +## Run the Parity Check Before Opening a PR + +```sh +node scripts/check-locale-parity.mjs +``` + +It must pass. It verifies that every page under `docs/` has its mirror under `docs/zh/` (and vice versa), and that the sidebars in `docs/.vitepress/en.ts` and `docs/.vitepress/zh.ts` link the same set of pages. CI runs the same script on every pull request. + +--- + +# 中文对照 + +本指南说明这个仓库里文档怎么组织、怎么翻译、怎么检查。 + +## 两种语言同步走 + +- 英文页面在 `docs/` 下。 +- 中文页面在 `docs/zh/` 下,**路径完全一致**:`docs/guides/memory.md` 对应 `docs/zh/guides/memory.md`。 +- **每个内容 PR 同时更新两种语言。** 英文是唯一事实来源;中文镜像**在同一个 PR 里**落地,不留到后续 PR。 + +## 按术语表翻译 + +产品术语按下表统一翻译。术语有产品 UI key 时,文档里的**加粗 UI 标签**必须直接使用产品在该语言下的字符串,绝不按英文字面重译。 + +| English | 中文 | Product UI key | +|---------|------|----------------| +| Bot | Bot | - | +| bot (prose) | Bot | - | +| workspace | 工作区 | `bots.tabs.container` | +| Platforms tab | 平台 | `bots.tabs.channels` | +| General tab | 通用 | `bots.tabs.general` | +| Desktop tab | 桌面 | `bots.tabs.desktop` | +| Memory tab | 记忆 | `bots.tabs.memory` | +| Schedule tab | 定时任务 | `bots.tabs.schedule` | +| Access Control | 访问控制 | `bots.tabs.access` | +| Providers | 模型服务商 | `sidebar.providers` | +| Add Provider | 添加服务商 | `provider.add` | +| Supermarket | 应用市场 | - | +| skill | 技能 | - | +| channel (concept) | 渠道 | - | +| session | 会话 | - | +| memory (long-term) | 长期记忆 | - | +| Help Center | 帮助中心 | - | + +规则:加粗的 UI 标签必须用产品自己的语言包字符串,绝不按字面值重译。UI key 背后的产品字符串改了,文档跟着改。 + +## 遵守中文排版规则 + +中文页面一律遵守: + +- 中文与拉丁字母、数字之间加空格:「在 Telegram 里发 3 条消息」。 +- 引号用「」,不用直引号或弯引号。 +- 正文用全角标点(,。:;?!);代码、路径、URL 里用半角。 +- 称呼读者用「你」,不用「您」。 +- 避免破折号 ——,改写句子。 +- 不写 AI 味句式:不用「不只是…更是…」、不用「告别…」、不用「无缝」、不写三连排比。 +- 只写确定的说法。写清产品实际行为,不写「以官网为准」「以实际为准」这类托词。 + +## 给可深链的标题加显式锚点 + +FAQ 条目和所有要被深链的标题带显式 ASCII `{#id}`,**两种语言完全相同**: + +```md + +## How do I reset a session? {#reset-session} + + +## 怎么重置会话? {#reset-session} +``` + +这样链接在换语言、改措辞后依然稳定。 + +## 按文案风格写 + +- 标题动词开头:「创建提供方」,不写「提供方的创建」。 +- 用确切数字,不用含糊说法:「256+ 个声音、50+ 种语言」,不写「很多声音」。 +- 每个破坏性操作都写明它**不会**撤销什么。例:「删除会话会永久移除消息历史;已经从中抽取的记忆不会随之删除。」 +- 示例提示词以安全约束收尾。例:「总结这个帖子并起草回复,发送任何内容前先问我。」 + +## 发 PR 前跑一致性检查 + +```sh +node scripts/check-locale-parity.mjs +``` + +必须通过。它检查 `docs/` 下每个页面在 `docs/zh/` 下都有镜像(反之亦然),并且 `docs/.vitepress/en.ts` 与 `docs/.vitepress/zh.ts` 两份侧栏链接同一组页面。CI 会在每个 pull request 上跑同一个脚本。 diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index e320f9e..6faafe0 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,11 +1,12 @@ import { defineConfig } from 'vitepress' +import llmstxt from 'vitepress-plugin-llms' import { en } from './en' import { zh } from './zh' // https://vitepress.vuejs.org/config/app-configs export default defineConfig({ title: 'Memoh Documentation', - description: 'Multi-member long-memory AI agent platform with desktop and server deploy modes.', + description: 'Documentation for Memoh — bots with their own cloud computer, long-term memory, and your chat channels.', head: [ ['link', { rel: 'icon', href: '/logo.svg' }] @@ -21,7 +22,8 @@ export default defineConfig({ nav: [ { text: 'Guides', link: '/guides/' }, { text: 'Integrations', link: '/integrations/' }, - { text: 'Self-hosted', link: '/self-hosted/' }, + { text: 'Help Center', link: 'https://memoh.ai/help' }, + { text: 'About', link: '/about.md' }, ], }, }, @@ -32,7 +34,8 @@ export default defineConfig({ nav: [ { text: '教程', link: '/zh/guides/' }, { text: '集成', link: '/zh/integrations/' }, - { text: '自托管', link: '/zh/self-hosted/' }, + { text: '帮助中心', link: 'https://memoh.ai/help' }, + { text: '关于', link: '/zh/about.md' }, ], }, } @@ -45,10 +48,6 @@ export default defineConfig({ ...zh, }, - nav: [ - { text: 'References', link: '/guides/' }, - { text: 'About', link: '/about.md' }, - ], logo: { src: '/logo.svg', @@ -82,5 +81,11 @@ export default defineConfig({ } }, - ignoreDeadLinks: true, + ignoreDeadLinks: [/^https?:\/\/localhost/], + + lastUpdated: true, + + vite: { + plugins: [llmstxt()], + }, }) diff --git a/docs/.vitepress/en.ts b/docs/.vitepress/en.ts index 3df6de9..5d5a71d 100644 --- a/docs/.vitepress/en.ts +++ b/docs/.vitepress/en.ts @@ -8,40 +8,28 @@ const references = [ { text: 'Getting Started', items: [ - { text: 'Get Started', link: '/guides/get-started.md' }, + { text: 'Overview', link: '/guides/overview.md' }, { text: 'Quick Start', link: '/guides/quick-start.md' }, + { text: 'Working with Bots', link: '/guides/working-with-bots.md' }, { text: 'Preferences', link: '/guides/preferences.md' }, - { text: 'Bot', link: '/guides/bot.md' }, { text: 'Sessions', link: '/guides/sessions.md' }, { text: 'Files', link: '/guides/files.md' }, { text: 'Slash Commands', link: '/guides/slash-commands.md' }, - { - text: 'Deployment', - collapsed: true, - items: [ - { text: 'Server Deploy', link: '/self-hosted/docker.md' }, - { text: 'Desktop', link: '/self-hosted/desktop.md' }, - { text: 'Workspace Backends', link: '/self-hosted/workspace-backends.md' }, - { text: 'Overview', link: '/self-hosted/' }, - ], - }, + { text: 'Desktop App', link: '/self-hosted/desktop.md' }, { text: 'Channels', collapsed: true, items: [ + { text: 'Overview', link: '/integrations/channels/' }, { text: 'Slack', link: '/integrations/channels/slack.md' }, { text: 'Telegram', link: '/integrations/channels/telegram.md' }, { text: 'Feishu (Lark)', link: '/integrations/channels/feishu.md' }, { text: 'Discord', link: '/integrations/channels/discord.md' }, { text: 'QQ', link: '/integrations/channels/qq.md' }, - { text: 'Matrix', link: '/integrations/channels/matrix.md' }, - { text: 'Misskey', link: '/integrations/channels/misskey.md' }, { text: 'LINE', link: '/integrations/channels/line.md' }, { text: 'DingTalk', link: '/integrations/channels/dingtalk.md' }, { text: 'WeCom (WeWork)', link: '/integrations/channels/wecom.md' }, { text: 'WeChat', link: '/integrations/channels/weixin.md' }, - { text: 'WeChat Official Account', link: '/integrations/channels/wechatoa.md' }, - { text: 'Overview', link: '/integrations/channels/' }, ], }, ], @@ -49,10 +37,11 @@ const references = [ { text: 'Advanced', items: [ + { text: 'Choosing an Extension', link: '/guides/extensions.md' }, { text: 'Agents / ACP', link: '/guides/acp.md' }, + { text: 'Approvals and Trust', link: '/guides/approvals.md' }, { text: 'Access Control', link: '/guides/access.md' }, { text: 'Workspace', link: '/guides/container.md' }, - { text: 'Computers', link: '/guides/computers.md' }, { text: 'Browser / Computer Use', link: '/guides/browser-computer-use.md' }, { text: 'Skills', link: '/guides/skills.md' }, { text: 'Supermarket', link: '/guides/supermarket.md' }, @@ -62,35 +51,13 @@ const references = [ { text: 'Memory', link: '/guides/memory.md' }, { text: 'Compaction', link: '/guides/compaction.md' }, { text: 'Scheduled Tasks', link: '/guides/schedule.md' }, - { text: 'Email', link: '/guides/email.md' }, - { - text: 'Providers', - collapsed: true, - items: [ - { text: 'LLM Providers', link: '/integrations/providers/llm.md' }, - { text: 'Web Search Providers', link: '/integrations/providers/web-search.md' }, - { text: 'Video Providers', link: '/integrations/providers/video.md' }, - { - text: 'Memory Providers', - collapsed: true, - items: [ - { text: 'Built-in', link: '/integrations/providers/memory/builtin.md' }, - { text: 'Mem0', link: '/integrations/providers/memory/mem0.md' }, - { text: 'OpenViking', link: '/integrations/providers/memory/openviking.md' }, - { text: 'Overview', link: '/integrations/providers/memory/' }, - ], - }, - { - text: 'TTS Providers', - collapsed: true, - items: [ - { text: 'Edge TTS', link: '/integrations/providers/tts/edge.md' }, - { text: 'Overview', link: '/integrations/providers/tts/' }, - ], - }, - { text: 'Overview', link: '/integrations/providers/' }, - ], - }, + { text: 'LLM Providers', link: '/integrations/providers/llm.md' }, + { text: 'Web Search Providers', link: '/integrations/providers/web-search.md' }, + { text: 'Video Providers', link: '/integrations/providers/video.md' }, + { text: 'Memory: Built-in', link: '/integrations/providers/memory/builtin.md' }, + { text: 'Memory: Mem0', link: '/integrations/providers/memory/mem0.md' }, + { text: 'Memory: OpenViking', link: '/integrations/providers/memory/openviking.md' }, + { text: 'TTS: Edge', link: '/integrations/providers/tts/edge.md' }, ], }, { diff --git a/docs/.vitepress/theme/components/DocsHome.vue b/docs/.vitepress/theme/components/DocsHome.vue index 4e55785..806c5f8 100644 --- a/docs/.vitepress/theme/components/DocsHome.vue +++ b/docs/.vitepress/theme/components/DocsHome.vue @@ -15,29 +15,29 @@ const copy = computed(() => { tone: 'guide', icon: 'rocket', title: '快速开始', - text: '十分钟部署 Memoh、添加模型、创建第一个机器人并接入聊天平台。', + text: '安装应用、登录、创建第一个 Bot,交给它真实任务,并接入聊天平台。', href: '/zh/guides/quick-start', }, { tone: 'guide', icon: 'book', - title: '入门指南', - text: '部署、添加模型、创建机器人、接入渠道,并掌握日常基础操作。', + title: '进阶教程', + text: '高级能力、自动化与外部提供方——智能体、Hooks、长期记忆等。', href: '/zh/guides/', }, { tone: 'integration', icon: 'plug', - title: '进阶教程', - text: '高级能力、自动化与外部提供方——智能体、Hooks、长期记忆等。', - href: '/zh/guides/', + title: '使用场景', + text: '组合多种功能解决实际问题的即用型示例。', + href: '/zh/guides/use-cases', }, { tone: 'hosted', icon: 'server', - title: '使用场景', - text: '组合多种功能解决实际问题的即用型示例。', - href: '/zh/guides/use-cases', + title: '帮助中心', + text: '订阅、账单与账号问题,以及联系 Memoh 团队的入口。', + href: 'https://memoh.ai/help', }, ], } @@ -49,29 +49,29 @@ const copy = computed(() => { tone: 'guide', icon: 'rocket', title: 'Quick Start', - text: 'Deploy Memoh, add a model, create your first bot, and connect a channel in ten minutes.', + text: 'Install the app, sign in, create your first bot, give it real work, and connect a chat platform.', href: '/guides/quick-start', }, { tone: 'guide', icon: 'book', - title: 'Getting Started', - text: 'Deploy, add a model, create a bot, connect channels, and learn the day-to-day basics.', + title: 'Advanced', + text: 'Capabilities, automation, and external providers — agents, hooks, memory, and more.', href: '/guides/', }, { tone: 'integration', icon: 'plug', - title: 'Advanced', - text: 'Capabilities, automation, and external providers — agents, hooks, memory, and more.', - href: '/guides/', + title: 'Use Cases', + text: 'Ready-to-follow scenarios that combine features to solve real problems.', + href: '/guides/use-cases', }, { tone: 'hosted', icon: 'server', - title: 'Use Cases', - text: 'Ready-to-follow scenarios that combine features to solve real problems.', - href: '/guides/use-cases', + title: 'Help Center', + text: 'Plans, billing, and account questions, plus a direct line to the team.', + href: 'https://memoh.ai/help', }, ], } diff --git a/docs/.vitepress/zh.ts b/docs/.vitepress/zh.ts index a8ef3a5..3ecf4a2 100644 --- a/docs/.vitepress/zh.ts +++ b/docs/.vitepress/zh.ts @@ -8,40 +8,28 @@ const references = [ { text: '快速开始', items: [ - { text: '入门教程', link: '/zh/guides/get-started.md' }, + { text: '概览', link: '/zh/guides/overview.md' }, { text: '快速开始', link: '/zh/guides/quick-start.md' }, + { text: '和 Bot 协作', link: '/zh/guides/working-with-bots.md' }, { text: '用户偏好', link: '/zh/guides/preferences.md' }, - { text: '机器人', link: '/zh/guides/bot.md' }, { text: '会话', link: '/zh/guides/sessions.md' }, { text: '文件', link: '/zh/guides/files.md' }, { text: '斜杠命令', link: '/zh/guides/slash-commands.md' }, - { - text: '部署', - collapsed: true, - items: [ - { text: '服务器部署', link: '/zh/self-hosted/docker.md' }, - { text: 'Desktop 桌面版', link: '/zh/self-hosted/desktop.md' }, - { text: '工作区后端', link: '/zh/self-hosted/workspace-backends.md' }, - { text: '总览', link: '/zh/self-hosted/' }, - ], - }, + { text: '桌面客户端', link: '/zh/self-hosted/desktop.md' }, { text: '渠道', collapsed: true, items: [ + { text: '总览', link: '/zh/integrations/channels/' }, { text: 'Slack', link: '/zh/integrations/channels/slack.md' }, { text: 'Telegram', link: '/zh/integrations/channels/telegram.md' }, { text: '飞书', link: '/zh/integrations/channels/feishu.md' }, { text: 'Discord', link: '/zh/integrations/channels/discord.md' }, { text: 'QQ', link: '/zh/integrations/channels/qq.md' }, - { text: 'Matrix', link: '/zh/integrations/channels/matrix.md' }, - { text: 'Misskey', link: '/zh/integrations/channels/misskey.md' }, { text: 'LINE', link: '/zh/integrations/channels/line.md' }, { text: '钉钉', link: '/zh/integrations/channels/dingtalk.md' }, { text: '企微', link: '/zh/integrations/channels/wecom.md' }, { text: '微信', link: '/zh/integrations/channels/weixin.md' }, - { text: '微信公众号', link: '/zh/integrations/channels/wechatoa.md' }, - { text: '总览', link: '/zh/integrations/channels/' }, ], }, ], @@ -49,10 +37,11 @@ const references = [ { text: '进阶教程', items: [ + { text: '扩展能力怎么选', link: '/zh/guides/extensions.md' }, { text: 'Agents / ACP', link: '/zh/guides/acp.md' }, + { text: '审批与信任', link: '/zh/guides/approvals.md' }, { text: '访问控制', link: '/zh/guides/access.md' }, { text: '工作区', link: '/zh/guides/container.md' }, - { text: '电脑(远程 Runtime)', link: '/zh/guides/computers.md' }, { text: 'Browser / Computer Use', link: '/zh/guides/browser-computer-use.md' }, { text: '技能', link: '/zh/guides/skills.md' }, { text: '应用市场', link: '/zh/guides/supermarket.md' }, @@ -62,35 +51,13 @@ const references = [ { text: '长期记忆', link: '/zh/guides/memory.md' }, { text: '上下文压缩', link: '/zh/guides/compaction.md' }, { text: '定时任务', link: '/zh/guides/schedule.md' }, - { text: '邮件', link: '/zh/guides/email.md' }, - { - text: '提供方', - collapsed: true, - items: [ - { text: '模型服务商', link: '/zh/integrations/providers/llm.md' }, - { text: '搜索提供方', link: '/zh/integrations/providers/web-search.md' }, - { text: '视频提供方', link: '/zh/integrations/providers/video.md' }, - { - text: '记忆提供方', - collapsed: true, - items: [ - { text: '内置', link: '/zh/integrations/providers/memory/builtin.md' }, - { text: 'Mem0', link: '/zh/integrations/providers/memory/mem0.md' }, - { text: 'OpenViking', link: '/zh/integrations/providers/memory/openviking.md' }, - { text: '总览', link: '/zh/integrations/providers/memory/' }, - ], - }, - { - text: 'TTS 提供方', - collapsed: true, - items: [ - { text: 'Edge TTS', link: '/zh/integrations/providers/tts/edge.md' }, - { text: '总览', link: '/zh/integrations/providers/tts/' }, - ], - }, - { text: '总览', link: '/zh/integrations/providers/' }, - ], - }, + { text: '模型服务商', link: '/zh/integrations/providers/llm.md' }, + { text: '搜索提供方', link: '/zh/integrations/providers/web-search.md' }, + { text: '视频提供方', link: '/zh/integrations/providers/video.md' }, + { text: '记忆提供方:内置', link: '/zh/integrations/providers/memory/builtin.md' }, + { text: '记忆提供方:Mem0', link: '/zh/integrations/providers/memory/mem0.md' }, + { text: '记忆提供方:OpenViking', link: '/zh/integrations/providers/memory/openviking.md' }, + { text: 'TTS:Edge', link: '/zh/integrations/providers/tts/edge.md' }, ], }, { diff --git a/docs/about.md b/docs/about.md index 2d53659..a4a16bd 100644 --- a/docs/about.md +++ b/docs/about.md @@ -2,19 +2,19 @@ Memoh v0.13 is the open-source multi-agent platform. It lets you run multiple AI agents on one machine, with each agent getting its own workspace, browser, network, tools, and long-term memory. -Agents can talk through Telegram, Discord, Lark, WeChat, Web UI, Email, and other channels. They can remember context, operate a browser or desktop, call MCP tools, install skills and connectors, run scheduled tasks, and enforce per-bot access rules. +Agents can talk through Telegram, Discord, Slack, Feishu, WeChat, DingTalk, and other channels — and directly in the Memoh app. They can remember context, operate a browser or desktop, call MCP tools, install skills and connectors, run scheduled tasks, and enforce per-bot access rules. -The hosted Memoh SaaS service is coming soon. Join the [SaaS waitlist](https://memoh.ai/waitlist) if you want a managed option instead of operating your own deployment. +Prefer a managed option instead of operating your own deployment? [Memoh Cloud](https://app.memoh.net) runs the same product as a hosted service. ## Distribution Modes ### Desktop -Desktop is the native client for Memoh Cloud or a self-hosted server. It wraps the Web UI in a native window with a system tray and shortcuts, and can register the computer it runs on as a Computer that bots may use. It does not run a local server. +Desktop is the native client for Memoh Cloud or a self-hosted server. It wraps the same client interface in a native window with a system tray and shortcuts, and can register the computer it runs on as a Computer that bots may use. It does not run a local server. ### Server Deploy -Server Deploy is for always-on shared usage. Use it when Memoh should serve multiple users, keep channels online while your computer is offline, or run as a self-hosted service. The Docker Compose stack includes the backend, Web UI, database, memory services, and workspace runtime. +Server Deploy is for always-on shared usage. Use it when Memoh should serve multiple users, keep channels online while your computer is offline, or run as a self-hosted service. The Docker Compose stack includes the backend, web client, database, memory services, and workspace runtime. ## What v0.13 Emphasizes @@ -22,9 +22,9 @@ Server Deploy is for always-on shared usage. Use it when Memoh should serve mult Each bot can use an isolated container workspace with files, commands, MCP hosting, network access, a headed browser, and a graphical desktop. Local and desktop setups can also use trusted local workspaces when host-level access is intentional. -### Web Product +### The Client -The Web UI now covers more of the daily product surface: bot setup, sessions, providers, channels, workspace files, terminal and display panes, Supermarket, hooks, schedules, access control, and user preferences. v0.13 also includes English, Simplified Chinese, and Japanese UI language support. +The client now covers more of the daily product surface: bot setup, sessions, providers, channels, workspace files, terminal and desktop panes, Supermarket, hooks, schedules, access control, and user preferences. v0.13 also includes English, Simplified Chinese, and Japanese UI language support. ### Hooks, Schedules, And Automation @@ -36,9 +36,9 @@ Access control is split between channel-side chat permissions and workspace-side ## Where To Start -- **[Bot Setup](./guides/bot.md)** - create and configure a bot. +- **[Bot Setup](./guides/working-with-bots.md)** - create and configure a bot. - **[Providers And Models](./integrations/providers/llm.md)** - configure model access. - **[Channels](./integrations/channels/index.md)** - choose where bots are reachable. - **[Skills](./guides/skills.md)** and **[Supermarket](./guides/supermarket.md)** - install reusable capabilities. - **[Scheduled Tasks](./guides/schedule.md)** and **[Access Control](./guides/access.md)** - operate recurring work and permissions. -- **[Self-hosted](./self-hosted/index.md)** - deploy and maintain your own Memoh instance. +- **[Help Center](https://memoh.ai/help)** - plans, billing, and account questions, plus a direct line to the team. diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md deleted file mode 100644 index 0a93a82..0000000 --- a/docs/channels/matrix.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/integrations/channels/matrix](/integrations/channels/matrix). diff --git a/docs/channels/misskey.md b/docs/channels/misskey.md deleted file mode 100644 index f0c264c..0000000 --- a/docs/channels/misskey.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/integrations/channels/misskey](/integrations/channels/misskey). diff --git a/docs/channels/wechatoa.md b/docs/channels/wechatoa.md deleted file mode 100644 index 238b928..0000000 --- a/docs/channels/wechatoa.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/integrations/channels/wechatoa](/integrations/channels/wechatoa). diff --git a/docs/getting-started/email.md b/docs/getting-started/email.md deleted file mode 100644 index 8c1772a..0000000 --- a/docs/getting-started/email.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/guides/email](/guides/email). diff --git a/docs/guides/access.md b/docs/guides/access.md index d340c27..0f196df 100644 --- a/docs/guides/access.md +++ b/docs/guides/access.md @@ -2,8 +2,8 @@ Memoh access control has two layers: -- **Channel Members** control identities coming from IM channels such as Telegram, Discord, Feishu, Matrix, QQ, and similar platforms. -- **Workspace Members** control registered Memoh users in the web app and workspace. +- **Channel Members** control identities coming from IM channels such as Telegram, Discord, Feishu, QQ, and similar platforms. +- **Workspace Members** control registered Memoh users in the app and workspace. The old ACL rule model still exists, but it is now the advanced engine behind Channel chat access. Most day-to-day changes should start from the bot's **Access** tab, using **Channel Members** and **Workspace Members**. @@ -14,7 +14,7 @@ The old ACL rule model still exists, but it is now the advanced engine behind Ch | Layer | Identity | Controls | |-------|----------|----------| | **Channel Members** | A channel identity observed from an IM platform | Whether that platform identity can chat with the bot, and whether it can manage the bot from IM commands | -| **Workspace Members** | A registered Memoh user account | Whether that user can use the bot in the web app, read/write files, run workspace commands, or manage bot settings | +| **Workspace Members** | A registered Memoh user account | Whether that user can use the bot in the app, read/write files, run workspace commands, or manage bot settings | These layers can be connected by account binding. A workspace user can bind a channel identity from **Profile -> Connected Accounts** by generating a one-time code and sending `/link ` to a Memoh bot in IM. After binding, Memoh can tell that the IM identity belongs to that workspace user. @@ -56,7 +56,7 @@ Workspace access is for registered Memoh users. It is separate from IM chat acce Channel Members is the IM-side access surface. -Each row represents a **channel identity** — one Telegram user, Discord member, or Matrix user — or a **group** (see below). Members are added from the inline picker in the card header; identity and group candidates appear in the same dropdown, grouped by section. A row can have two independent permissions: +Each row represents a **channel identity** — one Telegram user or Discord member — or a **group** (see below). Members are added from the inline picker in the card header; identity and group candidates appear in the same dropdown, grouped by section. A row can have two independent permissions: | Permission | Meaning | |------------|---------| @@ -130,7 +130,7 @@ Workspace permissions are: Workspace Manage also flows into Channel Members for linked channel identities. If a user with Workspace Manage links a Telegram identity, that Telegram identity inherits Manage on the channel side. -Workspace **Can chat** is not the same as Channel **Chat**. Workspace permissions authorize web app and workspace APIs; Channel Chat authorizes IM inbound messages through the ACL engine. +Workspace **Can chat** is not the same as Channel **Chat**. Workspace permissions authorize app and workspace APIs; Channel Chat authorizes IM inbound messages through the ACL engine. --- @@ -227,7 +227,7 @@ Grant the user **Can manage** in Workspace Members. Ask them to link their Teleg When access is surprising, check these in order: -1. **Which layer is involved?** IM messages use Channel Chat ACL. Web app and workspace APIs use Workspace Members. +1. **Which layer is involved?** IM messages use Channel Chat ACL. App and workspace APIs use Workspace Members. 2. **Is the identity linked?** Connected Accounts determines whether Workspace Manage can inherit into Channel Members. 3. **What is the Channel Access Mode?** Blacklist Mode defaults to allow; Whitelist Mode defaults to deny. 4. **Is Manage inherited or overridden?** The Channel Members info popover shows whether Manage follows Workspace Members or is locally overridden. diff --git a/docs/guides/acp.md b/docs/guides/acp.md index c1a30ef..8d6209a 100644 --- a/docs/guides/acp.md +++ b/docs/guides/acp.md @@ -2,7 +2,7 @@ Memoh can connect a bot to ACP-compatible coding agents. ACP agents are external coding workflows that work from the bot's chat workspace while keeping their sessions separate from normal chat and discuss conversations. -Three agent profiles ship with Memoh: **Codex**, **Claude Code**, and **Hermes**. Treat them as supported setup paths, not as the only possible ACP-compatible agents over time. +Two agent profiles ship with Memoh: **Codex** and **Claude Code**. Treat them as supported setup paths, not as the only possible ACP-compatible agents over time. ACP agents run inside the bot's container workspace, so the bot must use a container-backed workspace backend. @@ -23,7 +23,6 @@ A row shows one of three states: **Needs setup** (enabled but missing credential |-------|---------|-------|--------------| | **Codex** | ✅ | ✅ ChatGPT sign-in with device code | ✅ | | **Claude Code** | ✅ | ✅ paste a token from `claude setup-token` | ✅ | -| **Hermes** | ✅ | — | ✅ | **Self-managed** means Memoh launches the agent against configuration you maintain yourself inside the workspace. @@ -33,23 +32,10 @@ In the Codex settings, click **Use Device Code**. Memoh shows a verification URL > Only enter the code on the displayed OpenAI verification URL — device codes can be used for phishing. -### Hermes - -Hermes is a Python-based agent bundled with the workspace toolkit. Its settings ask for: - -- **Provider** — Gemini (Google AI Studio), OpenRouter, OpenAI API, or a custom endpoint -- **Model** — a preset list per provider, or a custom model ID -- **Base URL** — only shown and required for custom endpoints -- **API Key** — for the selected provider - ---- - ## Adapter Updates The Codex and Claude Code adapters are npm-backed. Memoh resolves the adapter's latest published version once per server run (per bot) and launches that version, so adapter fixes arrive without upgrading Memoh itself. If the lookup or launch fails, Memoh falls back to the adapter version bundled in the workspace image until the next server restart. -Hermes uses a pinned runtime from the workspace toolkit and does not self-update. - --- ## Reasoning Effort @@ -57,7 +43,7 @@ Hermes uses a pinned runtime from the workspace toolkit and does not self-update When the active agent supports it, you can pick a reasoning effort per session from the model picker in the composer: hover **Reasoning** to open the list. - The available options (and their names) are declared by the external agent itself; they can change when you switch models. -- Defaults when you have not chosen one: Codex uses `medium`, Claude Code uses `high`. Hermes does not support reasoning selection. +- Defaults when you have not chosen one: Codex uses `medium`, Claude Code uses `high`. - The choice is per session and independent of the model choice. If a previously chosen effort becomes unavailable, Memoh refreshes the agent's options and asks you to pick again instead of failing silently. @@ -84,13 +70,13 @@ In the bot's interaction settings you can pick a **Default Agent** — Memoh its ## ACP Agent Sessions -ACP work uses the `acp_agent` session type. These sessions are created and managed by the Agents/ACP workflow, not through normal `/new chat` or `/new discuss` routing. In the Web UI, you can filter sessions by `acp_agent` to find coding-agent work separately from everyday conversations. +ACP work uses the `acp_agent` session type. These sessions are created and managed by the Agents/ACP workflow, not through normal `/new chat` or `/new discuss` routing. In the app, you can filter sessions by `acp_agent` to find coding-agent work separately from everyday conversations. --- ## Related Pages -- [Bot Management](./bot.md) +- [Bot Management](./working-with-bots.md) - [Sessions](./sessions.md) - [Files](./files.md) - [Providers And Models](../integrations/providers/llm.md) diff --git a/docs/guides/approvals.md b/docs/guides/approvals.md new file mode 100644 index 0000000..15df3e8 --- /dev/null +++ b/docs/guides/approvals.md @@ -0,0 +1,50 @@ +# Approvals and Trust + +A bot that can write files, run commands, and message people needs a boundary you actually understand. This page explains that boundary from the user's side: what a bot can reach, when it stops to ask, and what approval does and does not cover. The mechanics — member lists, modes, and rules — live in [Access Control](./access.md). + +## What a bot can touch by default + +- **Its own workspace, and nothing else.** Each bot works inside its own isolated container workspace (`/data`). Files and state stay there, and bots cannot see into each other — see [Workspace](./container.md). +- **Only the channels and people you connected.** A bot reaches a platform because you added it on the **Platforms** tab, and answers an identity because access allows it. +- **Only the tier each person was granted.** Workspace access is tiered (chat, read files, write files, execute commands, manage), and a job gets the level it needs, no more. The tiers are defined in [Access Control](./access.md). + +Two member lists feed these grants, both on the bot's **Access** tab: **Channel Members** for identities on IM platforms, and **Workspace Members** for registered Memoh users. + +## When it asks you + +Write and execute tool calls can require human approval, controlled per bot on its **Tool Approval** tab. When a tool is set to require confirmation, the flow is: + +1. The bot proposes the action — the specific tool call, before anything runs. +2. You approve or reject it. +3. Only an approved call executes; a rejected one never runs. + +Approval always happens before the action, so reviewing the request is your moment of control, not damage control. A pending request can also time out rather than wait forever; if you missed one, ask the bot to try the action again. + +::: tip More gates, if you want them +Beyond the Tool Approval settings, a [hook](./hooks.md) matched on an event can itself request human approval — useful for guarding one specific command pattern rather than a whole tool. +::: + +## Keep these behind approval + +These are recommendations, not defaults Memoh enforces; treat them as a sensible starting point: + +- **Messages that leave the workspace** — anything sent to other people or posted publicly. +- **Deleting or overwriting files**, especially ones the bot did not create. +- **Installs and long-running commands** in the workspace. +- **Anything that spends money or touches production.** + +Actions that stay inside the bot's own workspace (drafting, organizing, reading) are the ones worth freeing from approval first. For how this fits a routine's lifecycle, from the first read-only run to widened permissions, see [Working with Bots](./working-with-bots.md). + +## Takeover and credentials + +When a bot working in its visible desktop hits a login wall or a CAPTCHA, you take over the screen and type the password, passkey, or one-time code yourself, then hand control back. The credential goes from your keyboard into the site — you never have to tell it to the bot. + +The browser session stays in that workspace afterwards, so later tasks remain signed in without repeating the takeover. See [Browser / Computer Use](./browser-computer-use.md) and [Quick Start](./quick-start.md#step-5-let-it-use-the-workspace-and-browser). + +## An honest boundary note + +::: warning What approval does not do +An approval gates the proposed action — it does not undo work that already ran, and it cannot retract a message that was already sent. Rejecting a request stops that request; it is not a rollback button. +::: + +That is why the durable habit is the one from [Access Control](./access.md): grant the minimum tier the job needs, review a few runs, and widen afterwards. Trust in a bot is built the same way as trust in a new teammate: incrementally, on evidence. diff --git a/docs/guides/bot.md b/docs/guides/bot.md index 683cffb..6c0d73a 100644 --- a/docs/guides/bot.md +++ b/docs/guides/bot.md @@ -1,150 +1,16 @@ -# Bot Management - -A Bot is an independent AI agent that comes with its own workspace, persistent memory, and configurable personality. Bots can chat via various messaging platforms (Channels) and perform complex tasks using specialized tools. - -## Creating a Bot - -1. Navigate to the **Bots** page from the sidebar. -2. Click the **Create Bot** button. -3. Fill in the basic info: - - **Display Name**: The name users will see in chats. - - **Avatar**: A URL for the bot's profile picture. - - **Timezone**: Optional per-bot timezone. If left empty, the bot inherits the user or system timezone. - - **ACL Preset**: Quick-start access policy such as `allow_all` or `private_only`. -4. Click **Create**. - ---- - -## Bot Detail Page - -Once created, clicking on a bot card takes you to its **Detail Page**, where you can manage its entire lifecycle through specialized tabs. - -### Tab Overview - -| Tab | Description | -|-----|-------------| -| **Overview** | Health checks for workspace runtime, database, channels, and memory. | -| **General** | Core runtime settings: chat/title/image models, memory/search/TTS bindings, timezone, language, reasoning, and danger zone. | -| **Desktop** | Workspace display runtime, headed browser availability, and active display sessions. | -| **Computers** | Remote runtimes (your own machines running the Memoh runtime) that the bot can use for files and commands. | -| **Workspace** | Container-backed workspace lifecycle, snapshots, data export/import. | -| **Network** | Workspace network and overlay provider status/actions. | -| **Memory** | Browse, search, create, edit, and compact memories. | -| **Platforms** | Channel configurations such as Telegram, Discord, Feishu, QQ, Matrix, WeCom, WeChat, Misskey, DingTalk, and Web. | -| **Access** | ACL rules and default access behavior. | -| **Tool Approval** | Human approval settings for tools that require confirmation. | -| **Agents** | ACP-compatible coding agents, such as Codex and Claude Code, that can be enabled for chat workspace use. | -| **Email** | Email bindings and outbox. | -| **Connectors** | Third-party service connections (OAuth or API key) via Connect-It: status, enable/disable, reauthorize, disconnect. | -| **Hooks** | Bot-scoped automation rules stored in `/data/.memoh/hooks.json`. | -| **MCP** | MCP connection management (Stdio, Remote, OAuth). | -| **Compaction** | Session context compaction settings and logs. | -| **Schedule** | Cron-based scheduled tasks and execution logs. | -| **Skills** | Markdown-based skill files that define bot personality and capabilities. | - -Files, Terminal, Display, and Browser workspace tools live in the chat workspace UI. They are not Bot Detail tabs. Use the workspace side of a chat when you need to inspect files, run shell commands, or operate the bot's browser/desktop. - ---- - -## Configuring the Bot's Core Settings - -After creating a bot, the most important step is configuring its runtime settings. These settings are split across a few tabs instead of living in one giant form. - -1. Navigate to your bot's **Detail Page**. -2. Start with the **General** tab for chat/runtime bindings. -3. Use the **Schedule** tab for recurring autonomous tasks. -4. Use the **Compaction** tab for session context compaction behavior. -5. Use the **Access** tab to refine ACL rules after the initial ACL preset. - -If you have not created these resources yet, set them up first: - -- [Providers And Models](../integrations/providers/llm.md) -- [Built-in Memory Provider](../integrations/providers/memory/builtin.md) -- [Search Providers](../integrations/providers/web-search.md) -- [TTS Providers](../integrations/providers/tts/index.md) -- [Agents / ACP](./acp.md) - ---- - -## General Tab Reference - -The **General** tab contains the settings that shape everyday conversation behavior. - -| Field | Description | -|-------|-------------| -| **Chat Model** | The main LLM used for generating chat responses. | -| **Title Model** | Optional model used to generate session titles. | -| **Image Generation Model** | Optional model used by image-generation features. Pick a chat model that supports `image-output`. | -| **Memory Provider** | The memory backend assigned to the bot. The built-in provider can optionally define its own memory and embedding models. | -| **Search Provider** | The search engine used for web browsing capabilities. | -| **TTS Model** | Optional speech model used for text-to-speech output. Speech models come from the TTS Providers flow, not the normal chat provider flow. | -| **Timezone** | Per-bot timezone. If empty, Memoh inherits the user timezone and then falls back to the system timezone. | -| **Language** | The bot's primary communication language. | -| **Reasoning Effort** | Available when the selected chat model exposes `reasoning` compatibility. Options depend on the model (for example `low`, `medium`, `high`). | - -Notes: - -- The **Image Generation Model** is intentionally separate from the normal chat model so you can dedicate an image-capable model only to visual generation tasks. -- The **TTS Model** comes from the [TTS Providers](../integrations/providers/tts/index.md) system and uses `speech` models from the configured speech provider. -- The selected chat model's `context_window` influences session status reporting and [Context Compaction](./compaction.md). - ---- - -## Compaction Tab Reference - -Compaction is now about **session context compaction**, not memory maintenance. - -| Field | Description | -|-------|-------------| -| **Compaction Enabled** | Enable or disable automatic context compaction. | -| **Compaction Threshold** | Estimated token threshold that triggers compaction. | -| **Compaction Ratio** | How aggressively the session context should be reduced. | -| **Compaction Model** | Optional dedicated model used to summarize old session context. | - -The Compaction tab also exposes compaction logs so you can see recent successful, pending, or failed runs. - -For the runtime behavior, see [Context Compaction](./compaction.md). - ---- - -## Access And ACL - -At creation time, the bot starts from an **ACL preset**. After that, use the **Access** tab for fine-grained control. - -Two layers matter: - -- **ACL Preset** gives you a sensible starting policy for a new bot. -- **ACL Default Effect** controls the default result when no rule matches. - -Use the **Access** tab to refine conversation, group, and thread rules after the initial setup. - --- - -## Discuss-Related Advanced Settings - -Most users only need the `chat` and `discuss` behavior described in [Sessions](./sessions.md). - -If you manage bot settings through the API or custom automation, the settings schema also includes `discuss_probe_model_id` for discuss-mode specific setups. Treat it as an advanced setting rather than a required field for normal bot creation. - +layout: false +title: Redirecting --- -## Workspace Files And Terminal - -Workspace files and terminals are available from the chat workspace UI after the bot has an active workspace runtime. From there you can: - -- Browse and edit files in the bot workspace. -- Open terminal sessions inside the workspace runtime. -- Use display/browser tools when the bot workspace has display support enabled. - -For file workflows, see [Files](./files.md). For headed browser and desktop workflows, see [Browser / Computer Use](./browser-computer-use.md). - ---- + -To permanently remove a bot and all its associated data (including workspace files and memory): -1. Navigate to the **General** tab in the Bot Detail page. -2. Scroll to the **Danger Zone** at the bottom. -3. Click **Delete Bot** and confirm the action. + -> **Warning**: This action is irreversible. All persistent data for this bot will be lost. +Redirecting to [/guides/working-with-bots](/guides/working-with-bots). diff --git a/docs/guides/browser-computer-use.md b/docs/guides/browser-computer-use.md index 17cc1c1..e80c42e 100644 --- a/docs/guides/browser-computer-use.md +++ b/docs/guides/browser-computer-use.md @@ -1,6 +1,6 @@ # Browser Use and Computer Use -Memoh can give a bot a visible workspace desktop and a headed browser inside its workspace container. This is different from running a headless Playwright script: the bot can inspect and operate the same graphical browser that you can see in the Web UI display pane. +Memoh can give a bot a visible workspace desktop and a headed browser inside its workspace container. This is different from running a headless Playwright script: the bot can inspect and operate the same graphical browser that you can see in the app's **Desktop** pane. ## Concepts @@ -14,7 +14,7 @@ Prefer Browser Use for web pages. Use Computer Use when the task depends on GUI ## Workspace display and VNC -Workspace display is the desktop environment inside the bot's workspace container. VNC/RFB is the display and input transport behind that desktop, while WebRTC is used by the Web UI display session. +Workspace display is the desktop environment inside the bot's workspace container. VNC/RFB is the display and input transport behind that desktop, while WebRTC is used by the app's desktop session. The main value is not VNC by itself. The important capability is that the workspace can run a headed Chrome/Chromium browser for sites and login flows that do not work well in headless mode. @@ -43,12 +43,10 @@ Both `browser_observe` and `computer_observe` save screenshots to a workspace pa ### Accessibility helper -Computer Use depends on the `a11y-cli` binary installed under `/opt/memoh/toolkit/display/bin/a11y-cli` and the workspace `at-spi2-core` package. The display runtime probe reports `a11y_available` so the Web UI can surface whether the accessibility path is healthy. When AT-SPI is unavailable, `computer_action` still works with raw coordinates and `computer_observe screenshot` remains usable. +Computer Use depends on the `a11y-cli` binary installed under `/opt/memoh/toolkit/display/bin/a11y-cli` and the workspace `at-spi2-core` package. The display runtime probe reports `a11y_available` so the app can surface whether the accessibility path is healthy. When AT-SPI is unavailable, `computer_action` still works with raw coordinates and `computer_observe screenshot` remains usable. These tools are workspace runtime features. They do not automate the Electron desktop app itself. -When a bot has remote [Computers](./computers.md) attached, Browser Use and Computer Use still run in the **Server Workspace** — they do not follow the selected work location. - ## Related - [Bot Workspace Management](./container.md) diff --git a/docs/guides/compaction.md b/docs/guides/compaction.md index bb9d71e..9bcaa94 100644 --- a/docs/guides/compaction.md +++ b/docs/guides/compaction.md @@ -108,7 +108,7 @@ Memoh tracks the current session against the selected chat model's `context_wind You can see this in: -- the Web UI session status panel +- the app's session status panel - the `/status` slash command Context usage is an estimate (roughly four characters per token), so treat the percentages as guidance rather than exact numbers. diff --git a/docs/guides/computers.md b/docs/guides/computers.md deleted file mode 100644 index b9ff746..0000000 --- a/docs/guides/computers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Computers (Remote Runtimes) - -Memoh can connect your own computers to a deployment so bots can work on them: read and write files, and run commands. The Web UI calls these **Computers**; a bot picks between them as **Work locations**. - -The agent itself does not move. Model calls, chat, sessions, and memory all stay on the Memoh server — a connected computer only provides its filesystem and command execution, and appears to the agent as another workspace. - -The connection is outbound from the computer to the server over WebSocket. The computer does not need a public IP or any open ports and can sit behind NAT. - -::: danger Understand what you are sharing -A connected computer exposes the files of the OS user who runs the runtime and executes commands **as that user**. There is no directory sandbox: any file that user can touch, a bot with access can touch. Only bots you explicitly add the computer to can use it, and write/execute actions ask for approval by default — but treat connecting a computer as granting shell access. -::: - ---- - -## Connecting A Computer - -### With The Command Line - -1. Open the **Computers** page in the Web UI settings. -2. Create a runtime key. Keys look like `mrk_...`; any signed-in user can create keys, and each computer belongs to the user who created its key. -3. Run the generated command on the computer you want to connect (Node.js 20+): - -```bash -npx --yes @memohai/runtime --server https://your-memoh-server/api --key mrk_xxxx -``` - -The connection requires `wss://` (TLS). Plain `http` is only accepted for localhost together with `--insecure-localhost`, which the UI adds automatically when applicable. The client reconnects automatically with backoff if the connection drops. - -The server URL and key can also come from the `MEMOH_RUNTIME_SERVER` and `MEMOH_RUNTIME_KEY` environment variables. - -### From The Desktop App - -Memoh Desktop has this built in: enable **This computer**, give it a name, and the app connects its own runtime in-process — no separate terminal needed. The key is stored encrypted with the OS keychain facility, the connection is restored on restart, and the runtime stays bound to the server it was configured for (connecting the desktop app to a different server puts it into an error state instead of silently reattaching). - -### Managing Keys - -- **Revoking** a key disconnects the computer immediately. -- Keys remain readable to their owner so the connection command can be copied again later. That also means they are stored readably server-side — protect the server database accordingly. - ---- - -## Work Locations On A Bot - -Each bot has a set of **Work locations**: - -- **Server Workspace** — the bot's normal container workspace on the server. Always present, cannot be removed. -- Any **computers** you add to the bot. - -Exactly one location is the **default**; new work happens there unless something says otherwise. Adding a computer to a bot requires bot manage permission, and a computer can only be attached to bots owned by the same user who owns the computer. - -A location row shows its status: online, offline, or **Update required** when the computer runs an older `@memohai/runtime` client than the server needs — upgrade the client (`npx` picks up the latest automatically on restart). - -### Choosing A Location Per Request - -- The chat composer has a **computer picker** to route a single message's work to a specific location. -- The agent can target a location per tool call; if the requested location is unavailable, the call fails visibly — it never silently falls back to the server or another computer. -- The agent can list the bot's current locations with the `list_execution_locations` tool. - -### Tool Approval Per Location - -Every location has its own approval policy for **read**, **write**, and **execute**, each set to allow, ask, or deny. For computers the defaults are: read **allow**, write **ask**, execute **ask** — so a bot can look around, but changing files or running commands on your machine asks first. Approvals are pinned to the location they were requested on. - ---- - -## Limitations - -- **Browser Use / Computer Use always run in the Server Workspace**, regardless of the selected location. -- **ACP agent sessions** do not support running on a computer. -- Paths: the runtime works from the OS user's home directory; `~` and `/data` in tool calls are mapped to the home directory for compatibility with container workspace conventions. - ---- - -## Related Pages - -- [Bot Workspace Management](./container.md) -- [Browser / Computer Use](./browser-computer-use.md) -- [Self-hosted Overview](../self-hosted/index.md) diff --git a/docs/guides/connectors.md b/docs/guides/connectors.md index a1a01fb..764eb0a 100644 --- a/docs/guides/connectors.md +++ b/docs/guides/connectors.md @@ -24,7 +24,7 @@ The one-click server deployment provisions a co-hosted Connect-It automatically ## Connect A Service -1. Open **Supermarket** in the Web UI. +1. Open **Supermarket** in the app. 2. Stay on the **Connectors** tab — it is the first tab and the default landing tab when connectors are configured. 3. Choose a connector and click **Connect**. 4. Select the target bot. diff --git a/docs/guides/container.md b/docs/guides/container.md index 1e31398..65befb6 100644 --- a/docs/guides/container.md +++ b/docs/guides/container.md @@ -14,8 +14,6 @@ The workspace acts as the bot's private computer. Within it, the bot can: The workspace toolkit ships both **Node.js** and **Python** runtimes (with `pip` and `uv` on the PATH), so bots can run Python scripts and install packages without preparing an interpreter first. -A bot can also work outside its server workspace on connected machines — see [Computers](./computers.md). - The underlying runtime is selected globally with `[container].backend` in `config.toml`, with trusted local workspace support controlled separately. The official Docker Compose server deploy uses `containerd`; Docker Engine, Apple, and local workspace modes are documented in [Workspace Backends](../self-hosted/workspace-backends.md). ## Workspace tabs @@ -24,7 +22,7 @@ Bot detail pages expose workspace-related settings across several tabs: | Tab | Purpose | |-----|---------| -| **Container** | Container lifecycle, snapshots, data export/import, and CDI device settings. | +| **Workspace** | Container lifecycle, snapshots, data export/import, and CDI device settings. | | **Desktop** | Workspace display runtime, headed browser availability, live display sessions, and session cleanup. | | **Network** | Workspace network and overlay provider status/actions. | | **Tool Approval** | Approval settings for tools that need explicit human permission. | @@ -35,7 +33,7 @@ Some tabs are hidden or limited for trusted local workspaces when the feature on ## Container lifecycle -Manage the container-backed workspace from the **Container** tab. +Manage the container-backed workspace from the **Workspace** tab. - **Create**: Initialize the workspace container if it does not exist. Progress is shown through SSE during image pull and creation. - **Start**: Launch the workspace runtime. @@ -48,11 +46,11 @@ Many workspace features, such as terminal access and container display, require The **Desktop** tab prepares and inspects the graphical workspace runtime. It checks for the desktop toolkit, Xvnc/VNC availability, browser availability, and active display sessions. -When enabled, the workspace can run a headed Chrome/Chromium browser inside the container. The Web UI display pane connects to that desktop session so you and the agent can operate the same visible browser. For the tool model, see [Browser / Computer Use](./browser-computer-use.md). +When enabled, the workspace can run a headed Chrome/Chromium browser inside the container. The app's **Desktop** pane connects to that desktop session so you and the agent can operate the same visible browser. For the tool model, see [Browser / Computer Use](./browser-computer-use.md). ## Container information -The **Container** tab displays runtime data such as: +The **Workspace** tab displays runtime data such as: - container ID and status - image @@ -64,11 +62,11 @@ The **Container** tab displays runtime data such as: Memoh can provide host devices to a bot container through CDI (Container Device Interface). This is an advanced capability for users who want to expose host-managed devices, most commonly GPUs, to the container runtime. -In the Web UI, this capability is placed under **Advanced options** in the **Container** tab. It is optional and only needs to be configured when the bot must access CDI-backed devices from the host. +In the app, this capability is placed under **Advanced options** in the **Workspace** tab. It is optional and only needs to be configured when the bot must access CDI-backed devices from the host. ### Configure CDI Devices -1. Open the bot's **Container** tab. +1. Open the bot's **Workspace** tab. 2. Click **Create** if the container does not exist, or recreate the container if you need to change GPU settings. 3. Expand **Advanced options**. 4. Enable **GPU**. @@ -101,7 +99,7 @@ If Memoh reports an error such as `unresolvable CDI devices`, the configured dev - CDI device settings are applied when the container is created. Updating the setting later requires recreating the container. - Stopping and starting an existing container does not change its attached CDI devices. - The container image still needs the appropriate user-space libraries and tools if you want to run CUDA or ROCm software inside the container. -- After creation, the **Container** tab shows the effective attached CDI devices for verification. +- After creation, the **Workspace** tab shows the effective attached CDI devices for verification. ## Snapshots @@ -109,7 +107,7 @@ Snapshots allow you to capture the current state of the bot's container workspac ## Data Export and Import -The **Container** tab supports exporting and importing workspace data for backup, migration, or sharing purposes. +The **Workspace** tab supports exporting and importing workspace data for backup, migration, or sharing purposes. - **Export Data** packages the workspace filesystem data into a downloadable archive. - **Import Data** extracts an uploaded archive into the workspace filesystem. diff --git a/docs/guides/email.md b/docs/guides/email.md deleted file mode 100644 index 0b30aeb..0000000 --- a/docs/guides/email.md +++ /dev/null @@ -1,67 +0,0 @@ -# Email Providers and Bindings - -Memoh allows your Bot to send and receive emails, providing another powerful channel for communication and task management. - -## Concept: Email as a Bot Channel - -Connecting email to your Bot involves two steps: -1. **Email Provider**: Configure a connection to an email service (like Mailgun or a generic SMTP server). -2. **Email Binding**: Link a specific email address from a provider to a Bot. - ---- - -## Email Provider - -Manage your email service connections from the **Email Provider** page in the sidebar. - -Email providers are **scoped per user**: each user configures and sees only their own email accounts, and bot bindings can only use providers owned by the same user. Different users may reuse the same provider name without conflict. - -::: tip Gmail OAuth -For Gmail providers, the OAuth application credentials (client ID / client secret) are no longer entered in the UI — the deployment operator configures them once in `conf/oauth-clients.toml` on the server. Users only go through the Gmail sign-in flow. -::: - -### Creating a Provider - -1. Navigate to the **Email Provider** page from the sidebar. -2. Click **Add Email Provider**. -3. Choose the provider type: - - **Mailgun**: For high-volume delivery. - - **Generic SMTP**: For traditional email servers. -4. Fill in the required fields (e.g., `domain`, `api_key`, `host`, `port`, `username`, `password`). -5. Click **Create**. - ---- - -## Bot Email Bindings - -Configure your bot's email capabilities from the **Email** tab in the Bot Detail page. - -### Adding a Binding - -1. Click **Add Binding**. -2. Select the **Email Provider** you created. -3. Provide the **Email Address** to be associated with the bot. -4. Set the bot's permissions: - - **Can Read**: If enabled, the bot can check and process incoming emails. - - **Can Write**: If enabled, the bot can compose and send outgoing emails. - - **Can Delete**: If enabled, the bot can manage its own email inbox. -5. Click **Create**. - ---- - -## Outbox and History - -The **Email** tab also provides an **Outbox** showing an audit log of all emails sent by the bot: - -- **To**: The recipient's email address. -- **Subject**: The email's subject line. -- **Status**: Whether the email was sent successfully. -- **Sent At**: The timestamp of the email delivery. - ---- - -## Bot Interaction - -- The bot can use its email permissions to **send reports**, **respond to user inquiries**, or **trigger actions** based on incoming mail. -- Outgoing emails are tracked in the outbox for monitoring and troubleshooting. -- The bot handles email in a structured way, allowing it to "converse" via email just as it does via chat. diff --git a/docs/guides/extensions.md b/docs/guides/extensions.md new file mode 100644 index 0000000..c62a537 --- /dev/null +++ b/docs/guides/extensions.md @@ -0,0 +1,37 @@ +# Choosing an Extension + +Memoh has five ways to extend what a bot can do. They sound alike until you put them side by side — so here they are, side by side. + +| Extension | What it is | Where it lives / how it fires | Best for | +|-----------|------------|-------------------------------|----------| +| [Skills](./skills.md) | `SKILL.md` prompt modules that change how the bot behaves | In the bot workspace under `/data/skills/`, managed on the **Skills** tab; invoked in conversation | Routines and working styles you would otherwise retype every time | +| [Hooks](./hooks.md) | Event rules in `hooks.json` that run commands or tools | In `/data/.memoh/hooks.json`, edited on the **Hooks** tab; fires on lifecycle events such as `PreToolUse` or `TurnEnd` | Checks and side effects at fixed points, with no chat involved | +| [MCP](./mcp.md) | Connections to external MCP tool servers | Configured per bot on the **MCP** tab, as a Stdio or Remote connection; discovered tools are used during conversation | Attaching a tool that already ships an MCP server | +| [Connectors](./connectors.md) | OAuth or API-key bindings to services such as GitHub or Notion | Connected from the Supermarket's **Connectors** tab, managed on the bot's **Connectors** tab; the service's tools appear in conversation | Letting the bot act on your account of a hosted service | +| [Supermarket](./supermarket.md) | Memoh's built-in catalog: one-click install of packaged apps — skills plus their dependencies and connectors | Under **Settings**; what you install lands in the target bot's own tabs | Getting a ready-made capability without assembling the parts | + +However the capability arrives, it converges in the same place: connector and MCP tools appear alongside the bot's workspace tools in conversation, and installed skills show up on the bot's **Skills** tab like hand-written ones. + +## Which should I use? + +- Change how the bot does its work → a [Skill](./skills.md). +- Do something automatically at a fixed event → a [Hook](./hooks.md). +- Attach a tool that has an MCP server → [MCP](./mcp.md). +- Let the bot use your GitHub or Notion account → a [Connector](./connectors.md). +- Install a ready-made package in one click → [Supermarket](./supermarket.md). + +::: tip They combine +These are not competing options. An installed Supermarket app may bring skills and connectors together, and a hook can guard tools that arrived through MCP. Pick by the question above, not one per bot. +::: + +## Where to start + +Each option has a full page with the details this table compresses: + +- [Skills](./skills.md) — writing `SKILL.md`, skill states, and adopting discovered skills. +- [Hooks](./hooks.md) — the event catalog, the config schema, and testing a rule. +- [MCP](./mcp.md) — Stdio and Remote connections, OAuth, and tool discovery. +- [Connectors](./connectors.md) — connection statuses, reauthorization, and tool namespaces. +- [Supermarket](./supermarket.md) — browsing the catalog and installing to a bot. + +If you are unsure, browse the Supermarket first — an installed package shows what a finished setup looks like before you build your own. diff --git a/docs/guides/files.md b/docs/guides/files.md index a727701..a41178e 100644 --- a/docs/guides/files.md +++ b/docs/guides/files.md @@ -25,7 +25,7 @@ The **FileManager** component provides a familiar file-browsing experience with ## Viewing and Editing -The integrated **FileViewer** allows you to interact with the bot's files without leaving the web UI. +The integrated **FileViewer** allows you to interact with the bot's files without leaving the app. ### Text Files diff --git a/docs/guides/get-started.md b/docs/guides/get-started.md index 4968de3..79fd65a 100644 --- a/docs/guides/get-started.md +++ b/docs/guides/get-started.md @@ -1,128 +1,16 @@ -# Get Started +--- +layout: false +title: Redirecting +--- -Memoh gives you bots that can actually do things. Every bot has its own workspace — a real filesystem, an executable terminal, and an optional visible desktop with a browser — plus long-term memory and the chat channels you already use. + -::: tip Looking for installation? -This page assumes you can already open a Memoh instance. If you need to deploy one yourself, read [Quick Start](./quick-start.md) first. -::: + -## Before You Begin - -You need: - -- Access to a Memoh instance and an account that can create bots. -- An API key for at least one model provider (OpenAI, Anthropic, Gemini, DeepSeek, Zhipu, OpenRouter, Ollama, and others). Skip this if an administrator has already configured providers. - -## 1. Sign In - -Open the Memoh Web UI and sign in. - -If this is a fresh instance, change the initial password immediately under **Settings → Account**. - -Interface language, theme, and similar options can be adjusted at any time in [Preferences](./preferences.md). They do not affect the steps below. - -## 2. Add A Model Provider - -A bot cannot think without a model. Skip this step if your administrator has already configured one. - -1. Open **Providers** in the sidebar and click **Add Provider**. -2. Pick a template, paste your API key, and save. -3. Open the provider and **sync** its model list, or add at least one chat model manually. - -For client types, base URLs, and provider-specific notes, see [LLM Providers](../integrations/providers/llm.md). - -## 3. Create Your First Bot - -Go to **Bots → New Bot**, give it a name and display name, then select your chat model on the **General** tab. - -Now write its instructions. This step matters most, and it is where people most often go wrong — usually by being too vague. Describe one job clearly: - -> **Name:** Digest -> -> **Role:** Weekly reading digest -> -> **Instructions:** Collect the articles I send you during the week. Every Friday, produce a digest grouped by theme: one sentence per article with its original link, followed by a "worth re-reading" section. Keep original links unchanged. Never publish anything publicly. - -A bot with one focused job accumulates far more useful context than a bot that does everything. When work genuinely splits into separate roles, create another bot instead of overloading this one — each bot has its own workspace, memory, and configuration. For a walkthrough of every tab, see [Bot](./bot.md). - -Click **Chat** and say hello. A reply confirms the model path works. - -## 4. Give It A Task - -A good first request answers five questions: - -| Element | The question it answers | -|---------|------------------------| -| **Outcome** | What should exist when this is done? | -| **Source** | Which files, sites, or conversations are relevant? | -| **Constraints** | What must it avoid, and what needs your approval? | -| **Format** | How should the answer be delivered? | -| **Checkpoint** | When should it stop and confirm with you? | - -For a result in minutes with no external logins, upload a document and try: - -```text -Summarize this document into five key points. In a separate section, list every -date, decision, and open question, noting which page or section each came from. -Do not modify the original file. -``` - -The bot reads the file inside its own workspace and writes the result back to the conversation. Everything it produces stays in the workspace, where you can browse and edit it under [Files](./files.md). - -## 5. Let It Use The Workspace And Browser - -The workspace is where a bot stops being a chatbot. It has a Linux filesystem, a terminal, and a preinstalled toolchain (Python, Node.js, uv, npm), so it can actually run the work: - -```text -Remove every row with an empty email column from the CSV I just uploaded. -Give me the cleaned file and tell me how many rows you dropped. -``` - -When a task needs a real browser — a site that breaks in headless mode, or a page behind a login — enable the visible desktop on the bot's **Desktop** tab. Once started, the bot drives a headed Chrome and you can watch it work in the display panel. - -When it hits a login wall, take over the screen yourself: type the password, passkey, or one-time code, then hand control back. The browser session stays in that workspace, so later tasks remain signed in. - -::: warning Grant access deliberately -Workspace access is tiered: chat only, read files, write files, execute commands, and manage the container. Grant the level the job needs and no more. See [Access Control](./access.md). -::: - -For details, see [Workspace](./container.md) and [Browser / Computer Use](./browser-computer-use.md). - -## 6. Connect A Chat Channel - -A bot is most useful where you already talk. - -1. Open the bot's **Platforms** tab and click **Add**. -2. Choose a platform — Telegram, Slack, Discord, Feishu, DingTalk, WeCom, QQ, LINE, Matrix, or Misskey — and paste that platform's credentials. -3. Message it from that platform. The first message creates a session; send `/help` to see the available [slash commands](./slash-commands.md). - -From then on you can hand off a task from your phone and collect the result in the same conversation. For per-platform setup, see [Channels](../integrations/channels/index.md). - -## 7. Review, Then Make It Stick - -When something is not right, say so. Phrase corrections as durable rules rather than one-off fixes: - -```text -For all future digests, use this format: grouped by theme, one line per article, -links inline, and a "worth re-reading" section at the end. -``` - -Once a routine is stable, stop retyping it: - -- Save it as a [Skill](./skills.md) so one sentence invokes the whole routine. -- Turn it into a [Scheduled Task](./schedule.md) that runs on cron with no chat at all. -- Use [Memory](./memory.md) to carry your preferences and project context into every future session. - -## Next Steps - -| Goal | Read | -|------|------| -| Configure a bot tab by tab | [Bot](./bot.md) | -| Understand chat, discuss, and routing | [Sessions](./sessions.md) | -| Connect external tools and data | [MCP](./mcp.md), [Connectors](./connectors.md) | -| Install prebuilt capabilities | [Supermarket](./supermarket.md) | -| Attach your own machine as a work location | [Computers](./computers.md) | -| Hook into lifecycle events | [Hooks](./hooks.md) | -| Control who can talk to a bot | [Access Control](./access.md) | \ No newline at end of file +Redirecting to [/guides/quick-start](/guides/quick-start). diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md index 33a6e95..29c1cbe 100644 --- a/docs/guides/hooks.md +++ b/docs/guides/hooks.md @@ -76,12 +76,12 @@ Top-level fields: | Field | Description | |-------|-------------| -| `version` | Required schema version. v0.13.0 supports `1`. | +| `version` | Required schema version. The current version is `1`. | | `enabled` | Enables or disables hooks in this user config. Defaults to `true`. | | `defaults.timeout` | Default action timeout. Accepts Go-style durations such as `10s`, or an integer number of seconds. Defaults to `10s`. | | `defaults.on_error` | Default error behavior: `ignore`, `fail`, or `block`. Defaults to `fail`. | | `defaults.max_output_bytes` | Maximum captured stdout/stderr bytes per command action. Defaults to `65536`. | -| `defaults.trigger_nested_hooks` | Parsed by the schema and defaults to `false`; the Hooks UI does not expose a separate control for it in v0.13.0. | +| `defaults.trigger_nested_hooks` | Parsed by the schema and defaults to `false`; the Hooks UI does not expose a separate control for it yet. | | `env` | Extra environment variables for command actions from the user config. | | `hooks` | Ordered rule list. Matching hooks run by descending `priority`, preserving file order for equal priorities. | @@ -95,7 +95,7 @@ Hook fields: | `enabled` | Enables or disables this hook. Defaults to `true`. | | `priority` | Higher numbers run first. | | `actions` | Actions to run when the hook matches. | -| `conditions` | Present in the schema for future expansion; v0.13.0 matching uses `event`, `enabled`, and `matcher`. | +| `conditions` | Present in the schema for future expansion; matching currently uses `event`, `enabled`, and `matcher`. | The `matcher` target is selected from the hook request in this order: @@ -110,7 +110,7 @@ The `matcher` target is selected from the hook request in this order: ## Action Types -v0.13.0 supports two action types: `command` and `tool`. +Two action types are supported: `command` and `tool`. ### Command Action @@ -171,7 +171,7 @@ If stdout is not JSON, Memoh treats the action as `allow` and stores the raw std A `tool` action calls an available bot tool by name with the configured `input`. Tool results may return `decision`, `reason`, and `append_context` in an object result. -`mcp_tool` is reserved in the codebase but rejected in v0.13.0. +`mcp_tool` is reserved in the codebase but currently rejected. --- @@ -198,7 +198,7 @@ Actions may return one of these decisions: ## Event Catalog -The Hooks tab loads the event catalog from `/bots/{bot_id}/hooks/events`. Events marked as runtime-supported are wired into v0.13.0 execution paths. Catalog-only events are accepted by config parsing and test runs, but are not currently emitted by a live runtime path in v0.13.0. +The Hooks tab loads the event catalog from `/bots/{bot_id}/hooks/events`. Events marked as runtime-supported are wired into the current execution paths. Catalog-only events are accepted by config parsing and test runs, but are not yet emitted by a live runtime path. | Event | Area | Runtime-supported | Notes | |-------|------|-------------------|-------| @@ -232,10 +232,10 @@ The Hooks tab loads the event catalog from `/bots/{bot_id}/hooks/events`. Events | `PostCompact` | Compaction | Yes | Runs after session compaction. | | `SubagentStart` | Subagents | Yes | Runs before a subagent task starts. | | `SubagentStop` | Subagents | Yes | Runs after a subagent task stops. | -| `InboundMessageNormalized` | Messaging | No | Catalog-only in v0.13.0. | -| `BeforeOutboundMessage` | Messaging | No | Catalog-only in v0.13.0. | -| `AfterOutboundMessage` | Messaging | No | Catalog-only in v0.13.0. | -| `ChannelDeliveryFailed` | Messaging | No | Catalog-only in v0.13.0. | +| `InboundMessageNormalized` | Messaging | No | Catalog-only for now. | +| `BeforeOutboundMessage` | Messaging | No | Catalog-only for now. | +| `AfterOutboundMessage` | Messaging | No | Catalog-only for now. | +| `ChannelDeliveryFailed` | Messaging | No | Catalog-only for now. | --- @@ -254,7 +254,7 @@ The test path uses the effective config and runs real actions. Avoid destructive ## Safety Notes -Hooks are powerful. Treat them like code that runs inside the bot workspace. +Hooks execute inside the bot workspace. Treat them like any other code that runs there. - Review every command action before enabling it. - Be careful with `PreToolUse`, `BeforeWorkspaceCommand`, and `BeforeFileWrite`; they can block normal bot work. @@ -267,5 +267,5 @@ Hooks are powerful. Treat them like code that runs inside the bot workspace. ## Related Pages -- [Bot Management](./bot.md) +- [Bot Management](./working-with-bots.md) - [Skills](./skills.md) diff --git a/docs/guides/index.md b/docs/guides/index.md index b66a663..104ecdb 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,39 +1,42 @@ # References -Welcome to the Memoh references. Everything you need to deploy, configure, and operate Memoh lives here, organized into three sections. +Welcome to the Memoh references. Everything you need to set up and use Memoh lives here, organized into three sections. ## Getting Started -Start here if you are new to Memoh. Learn how to deploy, add a model, create your first bot, connect a channel, and handle day-to-day basics. +Start here if you are new to Memoh. Learn how to install the app, create your first bot, connect a channel, and handle day-to-day basics. -- **[Get Started](./get-started.md)**: A guided tutorial — sign in, create a bot, give it real work, and connect a channel. -- **[Quick Start](./quick-start.md)**: Deploy a server, add a model, create your first bot, and connect a channel in ten minutes. +- **[Overview](./overview.md)**: What Memoh is and how the pieces fit together. +- **[Quick Start](./quick-start.md)**: Install the app, sign in, create your first bot, give it real work, and connect a chat platform. +- **[Working with Bots](./working-with-bots.md)**: What to hand off, how to state a request, when to split bots — plus the full tab-by-tab configuration reference. - **[Preferences](./preferences.md)**: Customize language, theme, typography, diagrams, and keyboard shortcuts. -- **[Bot](./bot.md)**: Create a bot and configure its core tabs. - **[Sessions](./sessions.md)**: Understand chat and discuss sessions, routing, and status panels. - **[Files](./files.md)**: Browse and edit files in a bot workspace. - **[Slash Commands](./slash-commands.md)**: Use command shortcuts for daily control. -- **[Deployment](../self-hosted/index.md)**: Choose a hosting option and deploy your own instance. - **[Channels](../integrations/channels/index.md)**: Connect Memoh to Slack, Telegram, Feishu, Discord, and more. ## Advanced Deepen your usage once the basics are in place. These pages cover capabilities, automation, and external providers. +- **[Choosing an Extension](./extensions.md)**: Skills, hooks, MCP, connectors, or Supermarket — which to reach for. - **[Agents / ACP](./acp.md)**: Build multi-agent workflows and interoperate with the Agent Client Protocol. -- **[Access Control](./access.md)**: Configure ACL presets, rule ordering, and scoped access. +- **[Approvals and Trust](./approvals.md)**: What a bot can touch, when it asks you, and what to keep behind approval. +- **[Access Control](./access.md)**: Configure ACL presets, access modes, and scoped rules. - **[Workspace](./container.md)**: Understand workspace behavior from the product UI. -- **[Computers](./computers.md)**: Register machines as remote runtimes. - **[Browser / Computer Use](./browser-computer-use.md)**: Work with headed browsers and visible desktop sessions. - **[Skills](./skills.md)** and **[Supermarket](./supermarket.md)**: Add reusable prompt modules and catalog templates. -- **[Connectors](./connectors.md)**: Connect hosted integrations such as Connect-It. +- **[Connectors](./connectors.md)**: Connect third-party services such as GitHub and Notion. - **[Hooks](./hooks.md)** and **[MCP](./mcp.md)**: Connect tools, automation rules, and external data sources. - **[Memory](./memory.md)**: Manage long-term memory after a provider is configured. - **[Compaction](./compaction.md)**: Reduce active session context size. - **[Scheduled Tasks](./schedule.md)**: Run recurring work on a cron schedule. -- **[Email](./email.md)**: Configure email workflows. -- **[Providers](../integrations/providers/index.md)**: LLM, web search, video, memory, and TTS providers. +- **[LLM Providers](../integrations/providers/llm.md)**: model providers and models; web search, video, memory, and TTS providers sit alongside it in the sidebar. ## Use Cases -- **[Use Cases](./use-cases.md)**: Ready-to-follow scenarios that combine features to solve real problems. \ No newline at end of file +- **[Use Cases](./use-cases.md)**: Ready-to-follow scenarios that combine features to solve real problems. + +## Getting Help + +These pages are the product reference. For plans, credits and billing, account questions, and a direct line to the Memoh team, visit the [Help Center](https://memoh.ai/help). diff --git a/docs/guides/memory.md b/docs/guides/memory.md index 6c6a756..22e5d57 100644 --- a/docs/guides/memory.md +++ b/docs/guides/memory.md @@ -6,7 +6,7 @@ Memoh's structured long-term memory system allows bots to remember information a Before using the **Memory** tab, make sure your bot already has a **Memory Provider** configured. -1. Create a provider from one of the [Memory Providers](../integrations/providers/memory/index.md) (Built-in, Mem0, or OpenViking). +1. Create a provider from one of the [Memory Providers](../integrations/providers/memory/builtin.md) (Built-in, Mem0, or OpenViking). 2. Open your bot's **General** tab. 3. Select the provider in the **Memory Provider** field. 4. Click **Save**. @@ -110,5 +110,5 @@ If you are trying to shorten the currently active conversation history, use **Co - The bot automatically searches and retrieves memories during chat. - The assigned **Memory Provider** controls the memory backend used by the bot. -- Provider-specific settings (such as embedding model or API keys) are configured in the provider itself — see [Memory Providers](../integrations/providers/memory/index.md). +- Provider-specific settings (such as embedding model or API keys) are configured in the provider itself — see [Memory Providers](../integrations/providers/memory/builtin.md). - Memories provide the long-term knowledge that makes each bot unique to its owner. diff --git a/docs/guides/overview.md b/docs/guides/overview.md new file mode 100644 index 0000000..487a942 --- /dev/null +++ b/docs/guides/overview.md @@ -0,0 +1,57 @@ +# Memoh Overview + +Memoh gives every bot its own cloud computer: a workspace with a real filesystem and terminal, a desktop browser you can watch and take over, and long-term memory that carries across sessions. Close your laptop; the bot keeps working. + +You work with a bot by messaging it — in the Memoh app, or on Telegram, Slack, Discord, Feishu, DingTalk, WeCom, WeChat, QQ, and LINE. Every entry point reaches the same bot and the same memory. + +Getting in takes a download and a Memoh Cloud sign-in. Hosted models (DeepSeek, Kimi, GPT, Claude, and more) are ready to use; to run your own keys or model service, see [BYOK](./quick-start.md#bring-your-own-key-byok). + +## What makes Memoh different + +- **A real computer, not a throwaway sandbox.** Files you write and runtimes you install stay in the [workspace](./container.md); what you set up on Monday is still there on Friday. +- **A screen you can see.** The bot drives a real browser on a visible desktop; when it hits a login or CAPTCHA, you [take over the keyboard](./browser-computer-use.md), finish the step, and hand control back. +- **It remembers.** [Long-term memory](./memory.md) works across sessions and channels; a preference you correct once should stick. +- **It runs while you are away.** [Scheduled tasks](./schedule.md) fire on cron and deliver to your connected channels — checking on time, speaking only when something changed. +- **Bring your own coding agent.** Put Claude Code or Codex into the same workspace over [ACP](./acp.md), on your own subscription. + +## One bot per job + +Every bot has its own workspace, memory, channels, and permission boundary; bots cannot see into each other. When work genuinely splits into roles, create another bot instead of overloading one. Who can chat with a bot, read or write its files, and run commands is granted level by level in [Access Control](./access.md) — give the level the job needs and no more. + +## A good first handoff + +Pick something small you already do by hand every week, and state the outcome, sources, and boundaries: + +> Every Friday at 17:00, turn the links and files I sent you this week into a weekly report — grouped by theme, one line each. Save it in the workspace and post the summary to this conversation. Organize only what I sent you; never send anything to anyone else. + +The bot registers the schedule itself and delivers weekly. Start with read-only work, review a few outputs, then widen what it may write and execute — see [Use Cases](./use-cases.md) for ready-made setups. + +## FAQ + +**Does it keep running when my computer is off?** + +Yes. The bot runs in a cloud workspace; schedules fire and channel messages get answered either way. + +**How many bots can I create?** + +That depends on your plan. Each bot is independent — its own workspace, memory, and permissions — and deleting one does not affect the others. + +**Where do my files live?** + +In that bot's isolated container workspace (`/data`), kept across sessions and browsable under [Files](./files.md). + +**Can I use my own models?** + +Yes. Add your own API keys under Providers (see [BYOK](./quick-start.md#bring-your-own-key-byok)); for coding agents, sign in with your own Claude Code or Codex subscription on the bot's **Agent** tab. + +**Where do plan and billing questions go?** + +The [Help Center](https://memoh.ai/help): plans, credits, account questions, and a direct line to the Memoh team. + +## Next steps + +- [Quick Start](./quick-start.md) — from installing the app to a connected chat platform, in about fifteen minutes. +- [Use Cases](./use-cases.md) — ready-to-follow scenarios that combine features to solve real problems. +- [Bot](./working-with-bots.md) — configure a bot tab by tab. +- [Channels](../integrations/channels/index.md) — per-platform setup guides. +- [Help Center](https://memoh.ai/help) — plans, billing, and account questions. diff --git a/docs/guides/preferences.md b/docs/guides/preferences.md index e5cdfd4..cc9c35e 100644 --- a/docs/guides/preferences.md +++ b/docs/guides/preferences.md @@ -1,6 +1,6 @@ # Preferences -Memoh v0.13 includes user-level preferences for the Web UI. These preferences change how the interface looks and how keyboard shortcuts behave for the current browser or desktop app profile. They do not change a bot's personality, model, tools, memory, or access rules. +Memoh v0.13 includes user-level preferences for the client. These preferences change how the interface looks and how keyboard shortcuts behave for the current device profile. They do not change a bot's personality, model, tools, memory, or access rules. Open **Settings**, then use **Appearance** for visual preferences and **Keyboard** for shortcuts. @@ -14,7 +14,7 @@ The **Appearance** page is split into interface, typography, code highlighting, | Setting | What It Does | |---------|--------------| -| **Language** | Sets the Web UI language. v0.13 includes English, Simplified Chinese, and Japanese. If you have not chosen a language yet, Memoh detects English, Chinese, or Japanese from the browser language and falls back to English. | +| **Language** | Sets the interface language. v0.13 includes English, Simplified Chinese, and Japanese. If you have not chosen a language yet, Memoh detects English, Chinese, or Japanese from the browser language and falls back to English. | | **Theme** | Chooses Light, Dark, or System. System follows the operating system or browser color mode. | | **Color Scheme** | Changes the accent palette used by brand elements, status colors, and interface controls. Available schemes are Memoh, Ocean, Forest, Rose, and Amber. | diff --git a/docs/guides/quick-start.md b/docs/guides/quick-start.md index 3ff6b38..cdd13da 100644 --- a/docs/guides/quick-start.md +++ b/docs/guides/quick-start.md @@ -1,91 +1,127 @@ # Quick Start -Get a working Memoh in about ten minutes: deploy the server, sign in, add a model provider, create your first bot, and connect it to a chat channel. - -::: tip Prefer not to self-host? -[Memoh Cloud](https://memoh.ai) runs the same product as a hosted service. Skip to [Step 3](#step-3-add-a-model-provider) once you have signed in. -::: +One complete tutorial from zero: install the app, sign in, create your first bot, give it real work, and reach it from a chat platform. It takes about fifteen minutes. ## Prerequisites -- A Linux server or workstation with **Docker** and **Docker Compose** installed. -- An API key for at least one LLM provider (OpenAI, Anthropic, DeepSeek, Zhipu, ...) or a local Ollama instance. -- Ports **8080** (API) and **8082** (Web UI) reachable from your browser. +- A computer running macOS, Windows, or Linux. +- A [Memoh Cloud](https://app.memoh.net) account — you can create one during sign-in. -## Step 1: Deploy the server +That is all. Memoh Cloud comes with hosted models (DeepSeek, Kimi, GPT, Claude, and more), so you do not need an API key to start. -The one-line installer pulls the images, generates a `config.toml`, and starts everything with Docker Compose: +## Step 1: Install Memoh -```bash -curl -fsSL https://memoh.sh | sh -``` +Download the app for your platform from the [download page](https://memoh.ai/desktop) — macOS (DMG), Windows (installer), or Linux (AppImage/deb/rpm) — and open it. -Users in mainland China can enable the mirror: +## Step 2: Sign in -```bash -curl -fsSL https://memoh.sh | USE_CN_MIRROR=true sh -``` +On the connect screen, choose **Memoh Cloud** and sign in, or create an account. -::: warning Do not run the whole installer with `sudo` -The installer will call `sudo docker` on its own when your user is not in the `docker` group. -::: +## Step 3: Create your first bot + +Go to **Bots → New Bot**, give it a name and display name, then select its chat model on the **General** tab. Hosted models are ready to use. + +Now write its instructions. This step matters most, and it is where people most often go wrong — usually by being too vague. Describe one job clearly: + +> **Name:** Digest +> +> **Role:** Weekly reading digest +> +> **Instructions:** Collect the articles I send you during the week. Every Friday, produce a digest grouped by theme: one sentence per article with its original link, followed by a "worth re-reading" section. Keep original links unchanged. Never publish anything publicly. + +A bot with one focused job accumulates far more useful context than a bot that does everything. When work genuinely splits into separate roles, create another bot instead of overloading this one — each bot has its own workspace, memory, and configuration. For a walkthrough of every tab, see [Bot](./working-with-bots.md). + +Click **Chat** and say hello. A reply confirms the model path works. + +## Bring Your Own Key (BYOK) + +Hosted models aside, you can bring your own models at any time: + +1. Open **Providers** in the sidebar and click **Add Provider**. +2. Pick a template (OpenAI, Anthropic, Gemini, DeepSeek, Zhipu, OpenRouter, Ollama, and others) and paste your API key; for OpenAI-compatible endpoints, add the base URL as well. +3. Open the provider and **sync** its model list, or add at least one chat model manually, then switch to it on the bot's **General** tab. -Prefer to do it by hand? Clone the repository and run: +BYOK usage is billed by your provider at its own rates. The same idea applies to coding agents: on the bot's **Agent** tab, sign in to Claude Code or Codex with your own subscription or API key. Provider-specific fields and notes are in [LLM Providers](../integrations/providers/llm.md). -```bash -git clone https://github.com/felinics/Memoh.git -cd Memoh -cp conf/app.docker.toml config.toml -# edit config.toml (admin password, JWT secret, ...) -docker compose up -d +## Step 4: Give it a task + +A good first request answers five questions: + +| Element | The question it answers | +|---------|------------------------| +| **Outcome** | What should exist when this is done? | +| **Source** | Which files, sites, or conversations are relevant? | +| **Constraints** | What must it avoid, and what needs your approval? | +| **Format** | How should the answer be delivered? | +| **Checkpoint** | When should it stop and confirm with you? | + +For a result in minutes with no external logins, upload a document and try: + +```text +Summarize this document into five key points. In a separate section, list every +date, decision, and open question, noting which page or section each came from. +Do not modify the original file. ``` -When it finishes you should see: +The bot reads the file inside its own workspace and writes the result back to the conversation. Everything it produces stays in the workspace, where you can browse and edit it under [Files](./files.md). + +## Step 5: Let it use the workspace and browser + +The workspace is where a bot does its work. It has a Linux filesystem, a terminal, and a preinstalled toolchain (Python, Node.js, uv, npm), so it can run data cleanups, scripts, and builds directly: ```text -🌐 Web UI: http://localhost:8082 -🔌 API: http://localhost:8080 -🔑 Admin login: admin / +Remove every row with an empty email column from the CSV I just uploaded. +Give me the cleaned file and tell me how many rows you dropped. ``` -Read [Server Deploy](../self-hosted/docker.md) for production hardening, reverse proxies, and upgrades. +When a task needs a real browser — a site that breaks in headless mode, or a page behind a login — enable the visible desktop on the bot's **Desktop** tab. Once started, the bot drives a headed Chrome and you can watch it work in the desktop panel. -## Step 2: Sign in +When it hits a login wall, take over the screen yourself: type the password, passkey, or one-time code, then hand control back. The browser session stays in that workspace, so later tasks remain signed in. -Open `http://:8082` and sign in with the admin account you chose during install (the default in `conf/app.docker.toml` is `admin` / `admin123`). Change the password right away under **Settings → Account**. +::: warning Grant access deliberately +Workspace access is tiered: chat only, read files, write files, execute commands, and manage the container. Grant the level the job needs and no more. See [Access Control](./access.md). +::: -## Step 3: Add a model provider +For details, see [Workspace](./container.md) and [Browser / Computer Use](./browser-computer-use.md). -1. Go to **Providers** in the sidebar and click **Add Provider**. -2. Pick a template (OpenAI, Anthropic, Gemini, DeepSeek, Zhipu, OpenRouter, Ollama, ...) and paste your API key. -3. Open the provider and **sync** or add at least one chat model. +## Step 6: Reach it from a chat platform -Details and client types are in [LLM Providers](../integrations/providers/llm.md). +A bot is most useful where you already talk. -## Step 4: Create your first bot +1. Open the bot's **Platforms** tab and click **Add**. +2. Choose a platform — Telegram, Slack, Discord, Feishu, DingTalk, WeCom, WeChat, QQ, or LINE — and paste that platform's credentials. +3. Message it from that platform. The first message creates a session; send `/help` to see the available [slash commands](./slash-commands.md). -1. Go to **Bots → New Bot**, give it a name and a display name. -2. In the bot's **General** tab choose the chat model you just added. -3. Click the bot's **Chat** button and say hello. If you get a reply, the pipeline works. +From then on you can hand off a task from your phone and collect the result in the same conversation. For per-platform setup, see [Channels](../integrations/channels/index.md). -Each bot has its own workspace, memory, and settings; see [Bot](./bot.md) for every tab. +## Step 7: Review, then make it stick -## Step 5: Connect a channel +When something is not right, say so. Phrase corrections as durable rules rather than one-off fixes: -1. Open the bot's **Channels** tab and click **Add**. -2. Pick a platform (Telegram, Discord, Slack, Feishu, DingTalk, WeCom, QQ, LINE, Matrix, Misskey, ...) and paste the platform credentials. -3. Message the bot from that platform. The first message creates a session; use `/help` to see the available slash commands. +```text +For all future digests, use this format: grouped by theme, one line per article, +links inline, and a "worth re-reading" section at the end. +``` -Per-platform setup guides live under [Channels](../integrations/channels/index.md). +Once a routine is stable, stop retyping it: + +- Save it as a [Skill](./skills.md) so one sentence invokes the whole routine. +- Turn it into a [Scheduled Task](./schedule.md) that runs on cron with no chat at all. +- Use [Memory](./memory.md) to carry your preferences and project context into every future session. ## What's next | Goal | Read | |------|------| -| Let the bot remember users across sessions | [Memory](./memory.md) | +| Configure a bot tab by tab | [Bot](./working-with-bots.md) | +| Understand chat, discuss, and routing | [Sessions](./sessions.md) | | Run scheduled or recurring tasks | [Schedule](./schedule.md) | -| Give the bot files, shell access, and a browser | [Workspace](./container.md), [Computers](./computers.md) | -| Add tools via MCP servers | [MCP](./mcp.md) | -| Teach the bot reusable procedures | [Skills](./skills.md), [Supermarket](./supermarket.md) | +| Connect external tools and data | [MCP](./mcp.md), [Connectors](./connectors.md) | +| Install prebuilt capabilities | [Supermarket](./supermarket.md) | +| Hook into lifecycle events | [Hooks](./hooks.md) | | Control who can talk to the bot | [Access Control](./access.md) | -| Run everything on a Mac with the desktop app | [Desktop](../self-hosted/desktop.md) | \ No newline at end of file +| See what others run | [Use Cases](./use-cases.md) | + +::: tip Need help? +Questions about plans, credits, or your account — or anything this site doesn't cover — are answered in the [Help Center](https://memoh.ai/help), where you can also reach the Memoh team. +::: diff --git a/docs/guides/schedule.md b/docs/guides/schedule.md index 8d805b5..76c0fa8 100644 --- a/docs/guides/schedule.md +++ b/docs/guides/schedule.md @@ -24,7 +24,7 @@ A **Schedule** is a cron-triggered rule bound to a specific bot. When a schedule ## Cron Pattern Reference -The `pattern` field uses standard cron syntax with five fields. It is evaluated in the server's configured timezone. By default, Memoh uses `UTC`, and you can change it with the top-level `timezone` config value. +The `pattern` field uses standard cron syntax with five fields. It is evaluated in the bot's timezone — the **Timezone** field on the bot's **General** tab, which falls back to the server's top-level `timezone` config (`UTC` by default) when unset. ``` ┌───────────── minute (0–59) @@ -65,7 +65,7 @@ Schedules are primarily created in two ways: The bot itself has access to a `schedule` tool. You can ask the bot to create a schedule in natural language: -> "Create a schedule called 'Daily Digest' that runs every day at 8 AM and sends me a summary of my unread emails." +> "Create a schedule called 'Daily Digest' that runs every day at 8 AM and sends me a summary of yesterday's repository activity." The bot will translate this into a cron expression and register the schedule automatically. @@ -80,9 +80,9 @@ POST /api/bots/{bot_id}/schedule ```json { "name": "Daily Digest", - "description": "Summarize unread emails every morning", + "description": "Summarize repository activity every morning", "pattern": "0 8 * * *", - "command": "Summarize my unread emails and send the result to Telegram.", + "command": "Summarize yesterday's repository activity and send the result to Telegram.", "enabled": true, "max_calls": null } diff --git a/docs/guides/sessions.md b/docs/guides/sessions.md index 8d59076..3234d93 100644 --- a/docs/guides/sessions.md +++ b/docs/guides/sessions.md @@ -34,7 +34,7 @@ Only **Chat** and **Discuss** sessions are directly created from normal user con - the conversation behaves like a normal direct assistant exchange - users expect a visible reply when they send a prompt -- this is the default in the Web UI and in direct-message style conversations +- this is the default in the app and in direct-message style conversations **Discuss** means: @@ -61,11 +61,11 @@ ACP Agent sessions are not created through `/new`. They are started from the cha Default routing behavior: -- **Web UI local chat** defaults to `chat` +- **Built-in app chat** defaults to `chat` - **private conversations** default to `chat` - **group conversations on channel adapters** default to `discuss` -`/new discuss` is not supported from the built-in Web UI local channel. Use a real channel adapter such as Telegram, Discord, or Misskey if you want to explicitly create discuss sessions. +`/new discuss` is not supported from the app's built-in chat channel. Use a real channel adapter such as Telegram or Discord if you want to explicitly create discuss sessions. This works across supported channels: @@ -83,9 +83,9 @@ This is especially useful when: - The conversation has become too long and you want a clean start. - You are switching between different tasks. -### In the Web UI +### In the App -The Web UI provides a session sidebar where you can: +The app provides a session sidebar where you can: - Click the **New Session** button to create a fresh chat session. - Switch between existing sessions by clicking on them. @@ -99,7 +99,7 @@ The Web UI provides a session sidebar where you can: ### Viewing Sessions -In the Web UI, the session sidebar lists all sessions for the currently selected bot. Each entry shows: +In the app, the session sidebar lists all sessions for the currently selected bot. Each entry shows: - **Title** — The session name (auto-generated or user-defined). - **Type** — The session type icon. diff --git a/docs/guides/skills.md b/docs/guides/skills.md index c14caf3..17db57e 100644 --- a/docs/guides/skills.md +++ b/docs/guides/skills.md @@ -2,6 +2,10 @@ Skills are reusable prompt modules that extend a bot's behavior, style, and tool-usage guidance. You manage them from the bot's **Skills** tab, and you can either write them yourself or install them from **[Supermarket](./supermarket.md)**. +::: tip Limits +A conversation can request at most 5 skills at once; each skill injects up to 64 KiB, with a 256 KiB total cap. These caps are fixed. +::: + --- ## What A Skill Looks Like diff --git a/docs/guides/slash-commands.md b/docs/guides/slash-commands.md index 6347e60..cb758ab 100644 --- a/docs/guides/slash-commands.md +++ b/docs/guides/slash-commands.md @@ -2,7 +2,7 @@ Memoh bots support **slash commands** that are intercepted before the LLM runs. They are intended for fast inspection and control tasks such as viewing settings, switching providers, checking session status, or creating a fresh session. -Slash commands work in channel adapters and in the built-in Web UI chat. They do not consume model tokens just to parse the command itself. +Slash commands work in channel adapters and in the app's built-in chat. They do not consume model tokens just to parse the command itself. --- @@ -44,7 +44,7 @@ Besides fixed commands, the slash system can activate the bot's [Skills](./skill / [optional prompt] ``` -- In the **Web UI composer**, typing `/` opens a panel with **Quick actions** (`/help`, `/skill list`, `/new`, `/compact`, `/model`) and the bot's skills. Selecting a skill attaches it as a removable chip; you can also type the form above directly. +- In the **app composer**, typing `/` opens a panel with **Quick actions** (`/help`, `/skill list`, `/new`, `/compact`, `/model`) and the bot's skills. Selecting a skill attaches it as a removable chip; you can also type the form above directly. - In **IM channels**, the same `/` form works, and `/skill list` renders the available skills as tappable buttons. - The activated skill's content is injected into the **current turn only** — it does not persist into history, session titles, or memory. @@ -108,7 +108,7 @@ In `/help` output, owner-only actions are marked with `[owner]`. | Command | Description | |---------|-------------| | `/help` | Show slash command help | -| `/new [chat|discuss]` | Create a new session for the current route | +| `/new [chat\|discuss]` | Create a new session for the current route | | `/stop` | Stop the current generation | ### Resource Groups @@ -131,7 +131,7 @@ In `/help` output, owner-only actions are marked with `[owner]`. | `/context` | Show context window usage for the current session | `show` | | `/reasoning` (aliases `/reason`, `/effort`, `/think`) | View or set the reasoning level for this session | `show` | | `/language` | View or set the command UI language (`auto`, `en`, `zh`, `ja`) | `show` | -| `/link ` | Link this channel account to your Memoh user with a code from the Web UI | `consume` | +| `/link ` | Link this channel account to your Memoh user with a code generated in the app | `consume` | --- @@ -149,11 +149,11 @@ Supported forms: Default behavior: -- **Web UI local chat** defaults to `chat` +- **Built-in app chat** defaults to `chat` - **Direct messages** default to `chat` - **Group conversations on channel adapters** default to `discuss` -`/new discuss` is not supported in the built-in Web UI local channel. Use a channel adapter such as Telegram or Discord if you want explicit discuss sessions. +`/new discuss` is not supported in the app's built-in chat channel. Use a channel adapter such as Telegram or Discord if you want explicit discuss sessions. See [Sessions](./sessions.md) for how `chat` and `discuss` differ. diff --git a/docs/guides/supermarket.md b/docs/guides/supermarket.md index 2db196e..241b956 100644 --- a/docs/guides/supermarket.md +++ b/docs/guides/supermarket.md @@ -2,7 +2,7 @@ Supermarket is Memoh's built-in catalog for **connectors** and **skills**. Connectors bind third-party services such as GitHub or Notion to a bot; skills are reusable procedures the agent can load on demand. -The Web UI shows Supermarket under Settings with two tabs: +The app shows Supermarket under **Settings** with two tabs: - **Connectors** - **Skills** @@ -19,7 +19,7 @@ The **Connectors** tab lists services a bot can connect through OAuth or an API ## Install A Skill -1. Open **Supermarket** in the Web UI. +1. Open **Supermarket** in the app. 2. Switch to the **Skills** tab. 3. Choose a skill and click **Install**, or open the skill detail page and click **Install to Bot**. 4. Select the target bot. diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md index e069274..cbbfa32 100644 --- a/docs/guides/use-cases.md +++ b/docs/guides/use-cases.md @@ -2,4 +2,100 @@ Ready-to-follow scenarios that combine multiple Memoh features to solve real problems. -> Coming soon. \ No newline at end of file +A good bot **owns a repeatable outcome**, not a loose category of questions. Each scenario below states what the bot owns, which features it uses, and a starting prompt you can send as-is. Every example starts with read-only work — check the output first, then grant more. + +## Morning Digest + +**Owns:** one message that starts your workday with everything you care about. + +**Uses:** [Scheduled Tasks](./schedule.md) · [Web Search Providers](../integrations/providers/web-search.md) · [Platforms](../integrations/channels/index.md) + +**Start with:** + +> Every weekday at 8am, summarize releases and notable issues from the repositories I follow over the last 24 hours, add today's weather, and send it to me as one digest. Cite a source for every item; if something is uncertain, say so instead of guessing. + +The bot has a `schedule` tool: describe the timing in plain language and it registers the cron entry itself. Cap the first runs with **Max Calls** until the format looks right. + +## Release Watch + +**Owns:** an external change you are waiting for, reported the moment it happens. + +**Uses:** [Scheduled Tasks](./schedule.md) · [Workspace](./container.md) · [Platforms](../integrations/channels/index.md) + +**Start with:** + +> Watch this project's releases page and check every 30 minutes. When a new version ships, write the changes up as Markdown in your workspace and ping me once on Telegram. Organize only — do not run any upgrade or install anything. + +"It's there even when you're not" is schedules plus proactive messages: check on a timer, speak only when something changed. The same pattern watches prices, stock, or document updates. + +## Group On-Call Assistant + +**Owns:** secretary duty in a team group: answers when mentioned and posts a daily recap. + +**Uses:** [Platforms](../integrations/channels/index.md) · [Sessions](./sessions.md) · [Access Control](./access.md) · [Scheduled Tasks](./schedule.md) + +**Start with:** + +> Once you join this group: when someone mentions you, summarize the day's discussion and open items. Every day at 6pm, post a recap organized as decisions / to-dos / open questions. Post only in this group — never message anyone privately. + +Use the "group only" [Access Control](./access.md) preset to fence its territory. In discuss sessions the bot decides for itself whether it has anything worth saying, so it will not flood the channel. + +## A Living Spreadsheet + +**Owns:** one data file that the bot creates, updates on schedule, and reports changes to first. + +**Uses:** [Workspace](./container.md) · [Files](./files.md) · [Scheduled Tasks](./schedule.md) + +**Start with:** + +> Create a competitor pricing sheet (CSV) in your workspace. Check each vendor's site every morning and append any changes to the sheet; message me first if a price drops. Maintain this file only — do not send anything to anyone else. + +The workspace is a real filesystem with a terminal (Python, Node.js, and uv preinstalled), so cleaning CSVs, running scripts, and generating reports all happen in place. Browse the output any time under **Files**. + +## Screen Work Behind Logins + +**Owns:** web tasks that need eyes on a screen: console checks, form flows, OAuth. + +**Uses:** [Browser / Computer Use](./browser-computer-use.md) · [Workspace](./container.md) (visible desktop) + +**Start with:** + +> Open our admin console and verify the configuration against the checklist I give you, saving a screenshot of each item into the workspace. If you hit a login, a CAPTCHA, or anything you are unsure about, stop and wait for me to take over the desktop; continue after I hand it back. Read-only throughout — change no settings. + +The visible desktop works both ways: watch it work in the desktop pane, or take over the keyboard to type a password, then hand control back. The browser session stays in the workspace, so the next task is already signed in. + +## Build and Preview in the Cloud + +**Owns:** a small project built in its own workspace, running where you can see it. + +**Uses:** [Agents / ACP](./acp.md) · [Workspace](./container.md) · [Skills](./skills.md) + +**Start with:** + +> Build a reading-list web page in your workspace: add items, mark them finished, filter by theme. When it works, start the dev server and tell me how to preview it. Commit every change locally with git — do not push to any remote. + +Prefer Claude Code or Codex? Attach your own subscription on the bot's **Agent** tab; it keeps working in the same workspace, on the same files. + +## An Assistant That Remembers + +**Owns:** your preferences and project state, carried across sessions and platforms. + +**Uses:** [Memory](./memory.md) · [Platforms](../integrations/channels/index.md) · [Scheduled Tasks](./schedule.md) + +**Start with:** + +> Remember these preferences: mornings are for deep work, meetings go in the afternoon, and the weekly report is due Friday before end of day. From now on, check memory before scheduling reminders or writing summaries; if a preference is unclear, ask me instead of guessing. + +With a [memory provider](../integrations/providers/memory/builtin.md) configured, "whatever happened with that PR?" is a question it can just answer. When memories pile up, run **Compact** to merge and dedupe. + +--- + +## From Example to Routine + +1. **Start read-only.** Let it read and prepare; review a few outputs before granting writes or execution. +2. **Put constraints in the instructions.** Outcome, sources, constraints, format, checkpoints — spell out all five (see [Quick Start](./quick-start.md)). +3. **Save repeated flows as [Skills](./skills.md).** One sentence should invoke the whole routine. +4. **Add a [Schedule](./schedule.md) only once the flow is stable.** Trial-run with Max Calls first. +5. **Keep writes and external actions behind approval,** even after the routine feels safe. +6. **Fence who can command it with [Access Control](./access.md)** — especially bots that join group chats. +7. **Let [Memory](./memory.md) hold your preferences.** A correction made once should stick. diff --git a/docs/guides/working-with-bots.md b/docs/guides/working-with-bots.md new file mode 100644 index 0000000..1ac825a --- /dev/null +++ b/docs/guides/working-with-bots.md @@ -0,0 +1,217 @@ +# Working with Bots + +[Quick Start](./quick-start.md) gets a bot running; this page is about working with one well — what to delegate, how to phrase it, where rules should live, and when one bot should become two — followed by the configuration reference: creating a bot and every tab on its detail page. + +## What to hand off + +A task is a good fit for a bot when three things hold: + +- **A clear outcome.** You can say what should exist when the work is done — a file, a message, a table. +- **Reachable sources.** The files, sites, or conversations involved are ones the bot can actually get to: uploaded into its workspace, connected as a channel or service, or public. +- **A checkable result.** You can tell at a glance whether the output is right, so reviewing stays cheap. + +When all three hold, start read-only anyway: let the bot read and organize first, review a few outputs, then grant more. Every scenario in [Use Cases](./use-cases.md) begins this way. + +## State the request + +A good request answers five questions — outcome, source, constraints, format, checkpoint. The table is in [Quick Start](./quick-start.md#step-4-give-it-a-task); here is what the difference looks like in practice. + +::: warning Vague +> Keep an eye on tech news and send me anything interesting. +::: + +No source (which sites or repositories?), no delivery time, and "interesting" is a judgment the bot has to make for you. Every digest becomes a coin flip. + +**Instead:** + +::: tip Specific +> Every weekday at 8am, summarize releases and notable issues from the repositories I follow over the last 24 hours, and send them to me as one digest. Cite a source for every item; if something is uncertain, say so instead of guessing. +::: + +::: warning Vague +> Clean up this spreadsheet. +::: + +"Clean" is undefined: which rows count as dirty, may the original file change, and what should come back? The bot has to guess three times before it starts. + +**Instead:** + +::: tip Specific +> Remove every row with an empty email column from the CSV I just uploaded. Give me the cleaned file and tell me how many rows you dropped. Do not modify the original file. +::: + +The pattern in both rewrites: name the sources, bound the actions, and make the result something you can verify in one look. + +## Where rules live + +Two kinds of instruction, two homes: + +- **Permanent rules** belong in the bot's instructions on its detail page — its role, format standards, standing constraints. They apply to every future session. +- **One-off asks** belong in the message — today's file, this week's exception. + +When a correction should stick, promote it: phrase it as a durable rule and move it into the instructions, exactly as [Quick Start](./quick-start.md#step-7-review-then-make-it-stick) step 7 shows. When a whole routine repeats, save it as a [Skill](./skills.md) so one sentence invokes it; preferences the bot should recall on its own belong in [Memory](./memory.md). + +## When to split bots + +One bot, one job. A bot with a single focused job accumulates context that keeps helping it; a do-everything bot dilutes its own instructions and memory. Both [Quick Start](./quick-start.md) and the [Overview](./overview.md) make the same point, so here is only the practical test: when a new request has a different audience, different sources, or needs different permissions than the bot's current job, create a second bot. + +Each bot gets its own workspace, memory, channels, and permission boundary, and bots cannot see into each other. Splitting also keeps permissions honest — the bot that only reads release notes never needs the right to execute commands. + +## Approval habits + +Grant the level a job needs and no more — workspace access is tiered from chat through read, write, execute, and manage; see [Access Control](./access.md). + +In practice: + +1. Start new routines read-only and keep write and execute tool calls behind approval. +2. Review the first few runs before widening anything. +3. Keep actions that leave the workspace — messages to other people, anything external — behind approval even after the routine feels safe. + +This is the same path the [Use Cases](./use-cases.md#from-example-to-routine) checklist walks: approving a few requests costs far less than undoing a wrong write. + +--- + +## Creating a Bot + +1. Navigate to the **Bots** page from the sidebar. +2. Click the **Create Bot** button. +3. Fill in the basic info: + - **Display Name**: The name users will see in chats. + - **Avatar**: A URL for the bot's profile picture. + - **Timezone**: Optional per-bot timezone. If left empty, the bot inherits the user or system timezone. + - **ACL Preset**: Quick-start access policy such as `allow_all` or `private_only`. +4. Click **Create**. + +--- + +## Bot Detail Page + +Once created, clicking on a bot card takes you to its **Detail Page**, where you can manage its entire lifecycle through specialized tabs. + +### Tab Overview + +| Tab | Description | +|-----|-------------| +| **Overview** | Health checks for workspace runtime, database, channels, and memory. | +| **General** | Core runtime settings: chat/title/image models, memory/search/TTS bindings, timezone, language, reasoning, and danger zone. | +| **Desktop** | Workspace display runtime, headed browser availability, and active display sessions. | +| **Workspace** | Container-backed workspace lifecycle, snapshots, data export/import. | +| **Network** | Workspace network and overlay provider status/actions. | +| **Memory** | Browse, search, create, edit, and compact memories. | +| **Platforms** | Channel configurations such as Telegram, Discord, Feishu, QQ, WeCom, WeChat, DingTalk, and Web. | +| **Access** | ACL rules and default access behavior. | +| **Tool Approval** | Human approval settings for tools that require confirmation. | +| **Agents** | ACP-compatible coding agents, such as Codex and Claude Code, that can be enabled for chat workspace use. | +| **Connectors** | Third-party service connections (OAuth or API key) via Connect-It: status, enable/disable, reauthorize, disconnect. | +| **Hooks** | Bot-scoped automation rules stored in `/data/.memoh/hooks.json`. | +| **MCP** | MCP connection management (Stdio, Remote, OAuth). | +| **Compaction** | Session context compaction settings and logs. | +| **Schedule** | Cron-based scheduled tasks and execution logs. | +| **Skills** | Markdown-based skill files that define bot personality and capabilities. | + +Files, Terminal, and the desktop/browser panes are also available inside the chat workspace UI — use the workspace side of a chat when you want to inspect files, run shell commands, or watch the bot's browser and desktop without leaving the conversation. + +--- + +## Configuring the Bot's Core Settings + +After creating a bot, the most important step is configuring its runtime settings. These settings are split across a few tabs instead of living in one giant form. + +1. Navigate to your bot's **Detail Page**. +2. Start with the **General** tab for chat/runtime bindings. +3. Use the **Schedule** tab for recurring autonomous tasks. +4. Use the **Compaction** tab for session context compaction behavior. +5. Use the **Access** tab to refine ACL rules after the initial ACL preset. + +If you have not created these resources yet, set them up first: + +- [Providers And Models](../integrations/providers/llm.md) +- [Built-in Memory Provider](../integrations/providers/memory/builtin.md) +- [Search Providers](../integrations/providers/web-search.md) +- [TTS: Edge](../integrations/providers/tts/edge.md) +- [Agents / ACP](./acp.md) + +--- + +## General Tab Reference + +The **General** tab contains the settings that shape everyday conversation behavior. + +| Field | Description | +|-------|-------------| +| **Chat Model** | The main LLM used for generating chat responses. | +| **Title Model** | Optional model used to generate session titles. | +| **Image Generation Model** | Optional model used by image-generation features. Pick a chat model that supports `image-output`. | +| **Memory Provider** | The memory backend assigned to the bot. The built-in provider can optionally define its own memory and embedding models. | +| **Search Provider** | The search engine used for web browsing capabilities. | +| **TTS Model** | Optional speech model used for text-to-speech output. Speech models come from the TTS Providers flow, not the normal chat provider flow. | +| **Timezone** | Per-bot timezone. If empty, Memoh inherits the user timezone and then falls back to the system timezone. | +| **Language** | The bot's primary communication language. | +| **Reasoning Effort** | Available when the selected chat model exposes `reasoning` compatibility. Options depend on the model (for example `low`, `medium`, `high`). | + +Notes: + +- The **Image Generation Model** is intentionally separate from the normal chat model so you can dedicate an image-capable model only to visual generation tasks. +- The **TTS Model** comes from the [TTS provider](../integrations/providers/tts/edge.md) flow and uses `speech` models from the configured speech provider. +- The selected chat model's `context_window` influences session status reporting and [Context Compaction](./compaction.md). + +--- + +## Compaction Tab Reference + +Compaction is now about **session context compaction**, not memory maintenance. + +| Field | Description | +|-------|-------------| +| **Compaction Enabled** | Enable or disable automatic context compaction. | +| **Compaction Threshold** | Estimated token threshold that triggers compaction. | +| **Compaction Ratio** | How aggressively the session context should be reduced. | +| **Compaction Model** | Optional dedicated model used to summarize old session context. | + +The Compaction tab also exposes compaction logs so you can see recent successful, pending, or failed runs. + +For the runtime behavior, see [Context Compaction](./compaction.md). + +--- + +## Access And ACL + +At creation time, the bot starts from an **ACL preset**. After that, use the **Access** tab for fine-grained control. + +Two layers matter: + +- **ACL Preset** gives you a sensible starting policy for a new bot. +- **ACL Default Effect** controls the default result when no rule matches. + +Use the **Access** tab to refine conversation, group, and thread rules after the initial setup. + +--- + +## Discuss-Related Advanced Settings + +Most users only need the `chat` and `discuss` behavior described in [Sessions](./sessions.md). + +If you manage bot settings through the API or custom automation, the settings schema also includes `discuss_probe_model_id` for discuss-mode specific setups. Treat it as an advanced setting rather than a required field for normal bot creation. + +--- + +## Workspace Files And Terminal + +Workspace files and terminals are available from the chat workspace UI after the bot has an active workspace runtime. From there you can: + +- Browse and edit files in the bot workspace. +- Open terminal sessions inside the workspace runtime. +- Use display/browser tools when the bot workspace has display support enabled. + +For file workflows, see [Files](./files.md). For headed browser and desktop workflows, see [Browser / Computer Use](./browser-computer-use.md). + +--- + +## Deleting a Bot + +To permanently remove a bot and all its associated data (including workspace files and memory): +1. Navigate to the **General** tab in the Bot Detail page. +2. Scroll to the **Danger Zone** at the bottom. +3. Click **Delete Bot** and confirm the action. + +> **Warning**: This action is irreversible. All persistent data for this bot will be lost. diff --git a/docs/index.md b/docs/index.md index e8555f0..e87ea39 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,10 @@ --- title: Memoh Documentation -description: Learn Memoh, connect external systems, or run your own deployment. +description: Learn Memoh, connect external systems, and bring your bots to the platforms you already use. --- # Memoh Documentation -Learn Memoh, connect external systems, or run your own deployment. +Learn Memoh, connect external systems, and bring your bots to the platforms you already use. diff --git a/docs/integrations/channels/dingtalk.md b/docs/integrations/channels/dingtalk.md index 1030598..dbf3ab8 100644 --- a/docs/integrations/channels/dingtalk.md +++ b/docs/integrations/channels/dingtalk.md @@ -1,43 +1,53 @@ # DingTalk Channel Configuration -Memoh supports DingTalk bots for private chats and group chats. The adapter uses DingTalk's stream connection for inbound events and the official APIs for outbound replies and media. +Connect your Memoh bot to DingTalk for private and group chats: inbound events arrive over DingTalk's Stream mode, and replies and media are sent through DingTalk's official APIs. -## Step 1: Create A DingTalk App +::: warning Limits +- Responses are delivered as complete messages; DingTalk output is not streamed token by token. +::: -1. Open the DingTalk developer platform for your organization. -2. Create or choose the app that will act as your bot. -3. Enable the bot / messaging capability for that app. -4. Copy the app credentials: - - **App Key** - - **App Secret** +## Prerequisites -Depending on your DingTalk environment, you may also need to grant message permissions and publish the app before it is available to end users. +- Access to your organization's DingTalk developer platform, with permission to create apps. +- No public callback URL is required: Memoh receives inbound events over a DingTalk Stream connection that it maintains automatically. -## Step 2: Configure Memoh +## Steps -1. Open your bot in the Memoh Web UI. -2. Go to **Platforms**. -3. Click **Add Channel** and choose **DingTalk**. -4. Fill in **App Key** and **App Secret**. -5. Click **Save and Enable**. +### 1. Create a DingTalk app -Memoh maintains the DingTalk stream connection automatically. For the normal setup, you do not need to manually paste a webhook callback URL. +In the DingTalk developer platform for your organization: -## Step 3: Verify Messaging +1. Create or choose the app that will act as the bot. +2. Enable the bot / messaging capability for that app. +3. Copy the **App Key** and **App Secret**. +4. Grant the app message permissions and publish it in your organization so end users can reach it. -After the channel is enabled: +### 2. Add the channel in Memoh -1. Send a private message to the DingTalk bot, or mention it in a supported group chat. -2. Confirm the bot receives the message and can reply. +In Memoh: -## Features Supported +1. Open the bot's **Platforms** tab. +2. Click **Add Channel** and choose **DingTalk**. +3. Fill in **App Key** and **App Secret**. +4. Click **Save and Enable**. -- **Private chats** -- **Group chats** -- **Text and Markdown-style output** -- **Replies** -- **Attachments and media** +Memoh maintains the DingTalk Stream connection automatically — there is no webhook callback URL to paste. -Current behavior note: +## Credentials -- Outbound responses are non-streaming on DingTalk in Memoh. +| Field | Required | Description | +|-------|----------|-------------| +| **App Key** | Yes | The DingTalk app's key, copied from the app's credentials in the DingTalk developer platform. | +| **App Secret** | Yes | The DingTalk app's secret, copied from the same place. | + +## Verify + +Send `/help` to the bot in a private chat, or @mention it in a group chat with `/help`. The bot replies with its command list, which confirms the channel is working. + +## Group chats + +The bot works in DingTalk group chats: @mention it in a supported group to trigger a reply. + +## Disable and rotate credentials + +Disable or remove the channel at any time from the bot's **Platforms** tab. To rotate credentials, update **App Key** / **App Secret** in the same panel and save. diff --git a/docs/integrations/channels/discord.md b/docs/integrations/channels/discord.md index 37bc390..0a6f6d5 100644 --- a/docs/integrations/channels/discord.md +++ b/docs/integrations/channels/discord.md @@ -1,21 +1,29 @@ # Discord Channel Configuration -Connecting your Memoh Bot to Discord allows it to join servers and interact with community members. +Connect your Memoh bot to Discord to join servers and chat with community members in channels and direct messages. -## Step 1: Create a Discord Application +## Prerequisites + +- A Discord account with access to the [Discord Developer Portal](https://discord.com/developers/applications). +- A Discord server you can authorize the bot into. +- A Memoh bot; channels are configured from its **Platforms** tab. + +## Steps + +### 1. In the Discord Developer Portal, create an application and get the bot token 1. Go to the [Discord Developer Portal](https://discord.com/developers/applications). 2. Click **New Application** and give it a name. 3. In the left sidebar, go to **Bot**. 4. Click **Reset Token** to generate a **Bot Token**. Copy this token and store it securely. -## Step 2: Configure Bot Settings +### 2. In the Discord Developer Portal, enable privileged gateway intents -1. Scroll down to the **Privileged Gateway Intents** section. +1. On the **Bot** page, scroll down to the **Privileged Gateway Intents** section. 2. Enable `Message Content Intent`, `Server Members Intent` and `Presence Intent`. 3. Save changes. -## Step 3: Invite the Bot to Your Server +### 3. In the Discord Developer Portal, invite the bot to your server 1. Go to **OAuth2** > **URL Generator**. 2. Select scopes: `bot`, `applications.commands`. @@ -23,17 +31,29 @@ Connecting your Memoh Bot to Discord allows it to join servers and interact with 4. Copy the generated URL and open it in your browser. 5. Select the server you want to add the bot to and authorize it. -> Official Guide: [Discord Developer Portal - Bots](https://discord.com/developers/docs/intro) +> Official guide: [Discord Developer Portal - Bots](https://discord.com/developers/docs/intro) -## Step 4: Configure Memoh +### 4. In Memoh, add the Discord channel -1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +1. Open your bot's detail page and go to the **Platforms** tab. 2. Click **Add Channel** and select **Discord**. -3. Paste your **Bot Token**. +3. Paste the **Bot Token**. 4. Click **Save and Enable**. -## Features Supported +## Credentials + +| Field | Description | +|-------|-------------| +| **Bot Token** | Generated with **Reset Token** on the application's **Bot** page. Store it securely. | + +## Verify + +Send the bot a direct message with `/help`, or @mention it in a channel of a server it has joined. If the bot replies with its command list, the channel is working. + +## Group chats + +Discord servers are supported. After the bot is authorized into a server, @mention it in a channel to talk to it there. + +## Disable and rotate credentials -- **Message Content**: Full access to chat text. -- **Attachments**: Support for images and files. -- **Commands**: Integration with Discord's slash commands (if configured via MCP). +You can disable or remove this channel at any time from the bot's **Platforms** tab. To rotate the token, update the **Bot Token** field and save. diff --git a/docs/integrations/channels/feishu.md b/docs/integrations/channels/feishu.md index 19d21c2..ec70fe2 100644 --- a/docs/integrations/channels/feishu.md +++ b/docs/integrations/channels/feishu.md @@ -1,43 +1,90 @@ # Feishu (Lark) Channel Configuration -Memoh supports integrating with Feishu (Lark) via the Open Platform. This allows your enterprise bots to interact with users in groups or private chats. +Connect your Memoh bot to Feishu (Lark) via the Open Platform, so enterprise bots can interact with users in groups and private chats. -## Step 1: Create a Feishu App +## Prerequisites + +- A [Feishu Open Platform](https://open.feishu.cn/app) account that can create custom apps. +- A Memoh bot; channels are configured from its **Platforms** tab. + +## Steps + +### 1. In the Feishu console, create a custom app 1. Go to the [Feishu Open Platform](https://open.feishu.cn/app) and log in. -2. Click **Create Custom App**. -3. Enter a name and description, then click **Create**. -4. In the left sidebar, go to **App Settings** > **Credentials & Basic Info**. -5. Copy your **App ID** and **App Secret**. +2. Click **Create Custom App**, enter a name and description, then click **Create**. +3. In the left sidebar, go to **App Settings** > **Credentials & Basic Info**. +4. Copy your **App ID** and **App Secret**. -## Step 2: Enable Bot Capability +### 2. In the Feishu console, enable the bot capability -1. In the Feishu Developer Console, go to **Capabilities** > **Bot**. -2. Click **Enable Bot**. +Go to **Capabilities** > **Bot** and click **Enable Bot**. -## Step 3: Configure Permissions +### 3. In the Feishu console, configure permissions 1. Go to **Capabilities** > **Permissions**. 2. Search for and enable the following permissions (at minimum): - - `im:message` (Receive and send messages) - - `im:chat` (Access group chat information) + - `im:message` (receive and send messages) + - `im:chat` (access group chat information) 3. Click **Apply for Permissions** if required by your organization. -## Step 4: Configure Events (Webhook Mode) +### 4. In Memoh, add the Feishu channel (default: long connection) + +1. Go to your bot's **Platforms** tab and add a **Feishu** channel. +2. Keep **Inbound Mode** at its default: `websocket`. +3. Fill in your **App ID** and **App Secret**; if you use international Lark, switch **Region** to `lark`. +4. Click **Save**. Messages arrive over Feishu's **WebSocket long connection** — no public callback URL and no event-subscription setup needed. + +### 5. Optional: switch to webhook mode -1. In Memoh, go to your Bot's **Platforms** tab and add a **Feishu** channel. -2. Choose **Inbound Mode**: `webhook`. -3. Fill in your **App ID** and **App Secret**. -4. Click **Save**. Memoh will generate a **Webhook Callback URL**. -5. Copy this URL. -6. In the Feishu Console, go to **App Settings** > **Event Subscriptions**. -7. Paste the URL into the **Verification URL** field and save. -8. Add events like `Receive Message` (im.message.receive_v1). +Choose this only when your server is publicly reachable and you prefer event callbacks. -> Official Guide: [Feishu Custom Bot Guide](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot) +::: tip +This mode round-trips between Memoh and the Feishu console: Memoh generates a callback URL that you paste back into **Event Subscriptions**, so keep the Feishu console open. +::: -## Step 5: Publish Your App +1. In Memoh, set **Inbound Mode** to `webhook`; besides the **App ID** and **App Secret**, also fill in the **Encrypt Key** and **Verification Token** matching your Event Subscriptions settings in the Feishu console. +2. Click **Save**. Memoh generates a **Webhook Callback URL** — copy it. +3. In the Feishu console, go to **App Settings** > **Event Subscriptions**, paste the URL into the **Verification URL** field, and save. +4. Add events like **Receive Message** (`im.message.receive_v1`). -1. In the Feishu Console, go to **App Release** > **Version Management & Release**. +> Official guide: [Feishu Custom Bot Guide](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot) + +### 6. In the Feishu console, publish your app + +1. Go to **App Release** > **Version Management & Release**. 2. Click **Create a Version**, fill in the details, and submit for approval. -3. Once approved and published, the bot is ready to use. +3. Once approved and published, the bot is ready to use in your tenant. + +## Credentials + +| Field | Description | +|-------|-------------| +| **App ID** | From **App Settings** > **Credentials & Basic Info** in the Feishu console. | +| **App Secret** | From the same **Credentials & Basic Info** page. | +| **Region** | Switch to `lark` if you use international Lark. | +| **Inbound Mode** | `websocket` (default, long connection) or `webhook`. | +| **Encrypt Key** | Webhook mode only; must match your Event Subscriptions settings in the Feishu console. | +| **Verification Token** | Webhook mode only; must match your Event Subscriptions settings in the Feishu console. | + +## Verify + +Open a private chat with the bot in Feishu and send `/help`. If the bot replies with its command list, the channel is working. + +## Group chats + +Feishu group chats are supported. Add the bot to a group and @mention it to talk to it there. + +## Disable and rotate credentials + +You can disable or remove this channel at any time from the bot's **Platforms** tab. To rotate credentials, update the fields (such as **App Secret**) and save. + +## FAQ {#faq} + +### The channel is configured but the bot does not respond {#app-not-published} + +A custom app must be published first: in the Feishu console, go to **App Release** > **Version Management & Release**, create a version, and submit it for approval. Once approved and published, the bot is ready to use in your tenant. + +### Enabling permissions requires an approval {#permission-approval} + +Some organizations require an approval flow for app permissions: click **Apply for Permissions** under **Capabilities** > **Permissions** to submit the request. diff --git a/docs/integrations/channels/index.md b/docs/integrations/channels/index.md index 45ef2f3..3ff0968 100644 --- a/docs/integrations/channels/index.md +++ b/docs/integrations/channels/index.md @@ -1,33 +1,20 @@ # Channels -Channels connect Memoh bots to messaging platforms. Configure them from the bot **Platforms** tab so users can talk to the same bot through Slack, Telegram, Feishu, Discord, WeChat, Email, the web UI, and other surfaces. +Channels connect Memoh bots to messaging platforms. Configure them from the bot **Platforms** tab so users can talk to the same bot through Slack, Telegram, Feishu, Discord, WeChat, and other platforms, as well as directly in the Memoh app. -## Supported Channels +## Supported channels -| Platform | Guide | Notes | -|----------|-------|-------| -| Slack | [Slack Configuration](./slack.md) | Workspace messaging with threads | -| Telegram | [Telegram Configuration](./telegram.md) | Strong attachment and streaming support | -| Feishu (Lark) | [Feishu Configuration](./feishu.md) | Supports webhook-style inbound mode | -| Discord | [Discord Configuration](./discord.md) | Good fit for communities and servers | -| QQ | [QQ Configuration](./qq.md) | Personal DM oriented | -| Matrix | [Matrix Configuration](./matrix.md) | Decentralized homeserver support | -| Misskey | [Misskey Configuration](./misskey.md) | Replies and reactions, no streaming | -| DingTalk | [DingTalk Configuration](./dingtalk.md) | Enterprise private/group chat | -| WeCom (WeWork) | [WeCom Configuration](./wecom.md) | Enterprise workspace integration | -| WeChat | [WeChat Configuration](./weixin.md) | Personal QR login flow | -| WeChat Official Account | [WeChat Official Account Configuration](./wechatoa.md) | Official account webhook flow | -| Email | [Email](../../guides/email.md) | SMTP, Mailgun, Gmail OAuth, and related email provider flows | -| Web | Built-in | Available from the Memoh web interface | +- [Telegram](./telegram.md) +- [Slack](./slack.md) +- [Discord](./discord.md) +- [Feishu (Lark)](./feishu.md) +- [DingTalk](./dingtalk.md) +- [WeCom](./wecom.md) +- [WeChat](./weixin.md) +- [QQ](./qq.md) +- [LINE](./line.md) -## WeChat Options - -Memoh supports two different WeChat-related adapters: - -- **WeChat (`weixin`)** is the personal-account style integration that relies on QR login. -- **WeChat Official Account (`wechatoa`)** is the official-account webhook integration that uses `App ID`, `App Secret`, `Token`, and optional AES settings. - -Choose the one that matches your actual WeChat deployment model. +What each channel supports (Markdown, attachments, streaming, group chats, and so on) is noted in the Limits section of its page. ## General Setup Flow diff --git a/docs/integrations/channels/line.md b/docs/integrations/channels/line.md index da4116b..e29c0fa 100644 --- a/docs/integrations/channels/line.md +++ b/docs/integrations/channels/line.md @@ -1,17 +1,28 @@ # LINE Channel Configuration -Connecting your Memoh Bot to LINE lets it chat with users through a LINE Official Account in one-on-one conversations. +Connect your Memoh bot to a LINE Official Account: users add the linked account as a friend and chat with the bot one-on-one. + +::: warning Limits +- Private chats only. Group and multi-person room messages are ignored — inviting the bot into a LINE group has no effect. +- Output is plain text; Markdown is not rendered. +- Outbound media is limited to PNG/JPEG images. Images must be publicly reachable over HTTPS and within LINE's size limits (10 MB original, 1 MB preview); non-image attachments cannot be sent. +- Inbound audio, video, stickers, and location messages are not processed. Inbound images must be hosted by LINE itself (the normal case for photos sent from the app). +- Responses arrive as complete messages — LINE does not support incremental streaming output — and long replies are split into multiple messages at LINE's 5000-character limit. +- Replies are delivered through the LINE **Push API**, so they count against your LINE plan's push message quota. +::: -## Before You Start +## Prerequisites -LINE delivers messages to Memoh through a **webhook**, so your Memoh deployment must expose a public HTTPS endpoint: +LINE delivers messages to Memoh through a **webhook**, and LINE's servers also fetch outbound images from your deployment, so Memoh must expose a public HTTPS endpoint: - Set `MEMOH_WEBHOOK_PUBLIC_BASE_URL` to your public HTTPS origin (no path, port, or private address), or - Enable the Cloudflare Quick Tunnel profile in the server deploy stack, and Memoh will obtain a public URL automatically. -Outbound images are also fetched by LINE's servers from your deployment, so the same public HTTPS requirement applies to sending pictures. +## Steps + +### 1. Create a LINE Messaging API channel -## Step 1: Create a LINE Messaging API Channel +In the LINE Developers Console: 1. Go to the [LINE Developers Console](https://developers.line.biz/console/). 2. Create a provider (or pick an existing one), then create a **Messaging API** channel. This links the channel to a LINE Official Account. @@ -20,40 +31,49 @@ Outbound images are also fetched by LINE's servers from your deployment, so the > Official Guide: [LINE Messaging API - Getting Started](https://developers.line.biz/en/docs/messaging-api/getting-started/) -## Step 2: Configure Memoh +### 2. Add the channel in Memoh + +In Memoh: -1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +1. Open the bot's **Platforms** tab. 2. Click **Add Channel** and select **LINE**. 3. Paste your **Channel Secret** and **Channel Access Token**. 4. Click **Save** (or **Save and Enable**). The webhook callback URL is generated only after the configuration is saved. -## Step 3: Register the Webhook +### 3. Register the webhook -After saving, the panel shows a read-only **WebHook Callback URL** in the form: +In Memoh, after saving, the panel shows a read-only **WebHook Callback URL** in the form: ```text https:///channels/line/webhook/ ``` -You have two ways to register it: +Register it in one of two ways: - Click **Set in LINE** — Memoh writes the webhook endpoint into your LINE channel directly through the Messaging API. Save any pending changes first, otherwise the button reports an error. - Or click **Copy** and paste the URL into **Messaging API → Webhook URL** in the LINE Developers Console manually. -Then, in the LINE Developers Console, make sure **Use webhook** is enabled for the channel. If the panel warns that no public base URL is available, fix the `MEMOH_WEBHOOK_PUBLIC_BASE_URL` / tunnel setup first. +Then, in the LINE Developers Console, make sure **Use webhook** is enabled for the channel. -## Features Supported +Memoh verifies incoming webhooks against your **Channel Secret** and deduplicates events for 24 hours. -- **One-on-one chat**: Users chat with the bot by adding the linked LINE Official Account as a friend. -- **Inbound messages**: Text, images, and files sent by the user. Images must be hosted by LINE itself (the normal case for photos sent from the app). -- **Outbound messages**: Text, plus PNG/JPEG images. -- **Signature verification**: Incoming webhooks are verified against your Channel Secret; events are deduplicated for 24 hours. +## Credentials -## Limitations +| Field | Required | Description | +|-------|----------|-------------| +| **Channel Secret** | Yes | Copied from **Basic settings** of the Messaging API channel. | +| **Channel Access Token** | Yes | Long-lived token issued in the **Messaging API** tab. | -- **Private chats only.** Group and multi-person room messages are ignored — inviting the bot into a LINE group has no effect. -- **Inbound audio, video, stickers, and location messages are not processed.** -- Outbound images must be publicly reachable over HTTPS and within LINE's size limits (10 MB original, 1 MB preview). Non-image attachments cannot be sent to LINE. -- Replies are delivered through the LINE **Push API**, so they count against your LINE plan's push message quota. -- Responses arrive as complete messages; LINE does not support incremental streaming output. -- Long replies are split into multiple messages at LINE's 5000-character limit. +## Verify + +Add the linked LINE Official Account as a friend, then send `/help` to the bot in the one-on-one chat. The bot replies with its command list, which confirms the channel is working. + +## Disable and rotate credentials + +Disable or remove the channel at any time from the bot's **Platforms** tab. To rotate credentials, update **Channel Secret** / **Channel Access Token** in the same panel and save. + +## FAQ {#faq} + +### The panel warns that no public base URL is available {#no-public-base-url} + +The webhook callback URL cannot be built without a public HTTPS origin. Fix the `MEMOH_WEBHOOK_PUBLIC_BASE_URL` / Cloudflare Quick Tunnel setup described in the prerequisites first. diff --git a/docs/integrations/channels/matrix.md b/docs/integrations/channels/matrix.md deleted file mode 100644 index cff0a14..0000000 --- a/docs/integrations/channels/matrix.md +++ /dev/null @@ -1,65 +0,0 @@ -# Matrix Channel Configuration - -Connecting your Memoh Bot to Matrix allows it to communicate via the decentralized Matrix messaging protocol. Your bot can join rooms, respond to direct messages, and participate in group conversations on any Matrix homeserver. - -## Step 1: Create a Matrix Bot Account - -1. Register a new account on your Matrix homeserver (e.g., via Element or any Matrix client). -2. Note the **User ID** (e.g., `@mybot:matrix.org`). -3. Obtain an **Access Token** for the account. You can do this by: - -- Option A: Using the Matrix Client Login API - -```bash -curl -X POST "https:///_matrix/client/v3/login" \ - -H "Content-Type: application/json" \ - -d '{ - "type": "m.login.password", - "identifier": { - "type": "m.id.user", - "user": "" - }, - "password": "" - }' -``` - -- Option B: Extract from a client - -> **Important**: Keep the access token secret. Anyone with this token can act as your bot account. - -## Step 2: Configure Memoh - -1. Go to your Bot's **Platforms** tab in the Memoh Web UI. -2. Click **Add Channel** and select **Matrix**. -3. Fill in the required fields: - -| Field | Required | Description | -|-------|----------|-------------| -| **Homeserver URL** | Yes | The base URL of your Matrix homeserver (e.g., `https://matrix.org`). | -| **Access Token** | Yes | The bot account's access token. | -| **User ID** | Yes | The bot's Matrix user ID (e.g., `@mybot:matrix.org`). | -| **Sync Timeout** | No | Long-polling timeout in seconds (default: 30). | -| **Auto Join Invites** | No | Automatically join rooms when invited (default: enabled). | - -4. Click **Save and Enable**. - -## Step 3: Invite the Bot - -1. Open your Matrix client (Element, etc.). -2. Invite the bot's user ID to a room, or start a direct message. -3. If **Auto Join Invites** is enabled, the bot will automatically accept and join. - -## Features Supported - -- **Message Content**: Full access to text messages. -- **Rooms**: Join and participate in group rooms. -- **Direct Messages**: Private conversations with individual users. -- **Streaming**: Responses are streamed as they are generated. -- **Markdown**: Support for formatted text. -- **Media/Attachment**: Bots can receive and send files or photos. -- Check [the roadmap](https://github.com/felinics/Memoh/issues/249) for more features of Matrix. - -## Official Resources - -- [Matrix Specification](https://spec.matrix.org/) -- [Element Web Client](https://app.element.io/) diff --git a/docs/integrations/channels/misskey.md b/docs/integrations/channels/misskey.md deleted file mode 100644 index c88ddf7..0000000 --- a/docs/integrations/channels/misskey.md +++ /dev/null @@ -1,49 +0,0 @@ -# Misskey Channel Configuration - -Memoh can connect a bot to a Misskey server so it can read inbound mentions and reply as a Misskey account. This adapter is best for text-first social interactions on self-hosted or public Misskey instances. - -## Step 1: Prepare A Misskey Account And Token - -1. Sign in to the Misskey instance you want to use. -2. Create or choose the account that should represent your bot. -3. Generate an **Access Token** for that account. - -Memoh needs: - -- **Instance URL**: for example `https://misskey.io` -- **Access Token**: a token for the bot account - -The exact token-creation UI varies by Misskey instance. Make sure the token is allowed to read inbound events for the bot account and publish replies. - -## Step 2: Configure Memoh - -1. Open your bot in the Memoh Web UI. -2. Go to **Platforms**. -3. Click **Add Channel** and choose **Misskey**. -4. Enter the **Instance URL**. -5. Paste the **Access Token**. -6. Click **Save and Enable**. - -Memoh uses these credentials to discover the bot identity and start the Misskey connection. - -## Step 3: Start Chatting - -After the channel is enabled, users can interact with the bot on that Misskey instance. - -Misskey in Memoh is generally best suited for: - -- replies to users -- text and Markdown-style output -- reaction-aware social conversations - -## Features Supported - -- **Text** -- **Markdown** -- **Replies** -- **Reactions** - -Current limitations: - -- **No attachments / media upload** -- **No streaming output** diff --git a/docs/integrations/channels/qq.md b/docs/integrations/channels/qq.md index d9f372e..371b6f3 100644 --- a/docs/integrations/channels/qq.md +++ b/docs/integrations/channels/qq.md @@ -1,34 +1,61 @@ # QQ Channel Configuration -Connecting your Memoh Bot to QQ allows it to interact with users through QQ's official Bot platform. +Connect your Memoh bot to QQ through QQ's official bot platform, for private chats, group chats, and thread (话题) conversations. -## Step 1: Create a QQ Bot +::: warning Limits +- Each QQ account can create up to 5 bots. +- Responses are delivered as complete blocks; output is not streamed token by token. +::: + +## Prerequisites + +- A QQ account, used to log in to the [QQ Bot Open Platform](https://q.qq.com/qqbot/openclaw/). + +## Steps + +### 1. Create a QQ bot + +In the QQ Bot Open Platform: 1. Go to the [QQ Bot Open Platform](https://q.qq.com/qqbot/openclaw/) and log in with your QQ account. -2. Click **Create Bot** (创建机器人) - no approval required. Each account can create up to 5 bots. -3. Copy the **AppID** and **AppSecret** displayed on the page. +2. Click **Create Bot** (创建机器人) — no approval is required. +3. Copy the **AppID** and **AppSecret** displayed on the page. **AppSecret** is shown only once — save it securely. + +> Official resources: [QQ Bot Open Platform](https://q.qq.com/) · [QQ Bot Documentation](https://bot.q.qq.com/wiki/) -> **Important**: AppSecret is only shown once. Save it securely - viewing it again will force a reset. +### 2. Add the channel in Memoh -## Step 2: Configure Memoh +In Memoh: -1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +1. Open the bot's **Platforms** tab. 2. Click **Add Channel** and select **QQ**. -3. Paste your **AppID** and **AppSecret**. -4. Configure optional settings: - - **Markdown Support**: Enable Markdown formatting (default: enabled). - - **Enable Input Hint**: Show typing indicators (default: enabled). +3. Paste the **AppID** and **AppSecret**. +4. Adjust the optional settings if needed: **Markdown Support** and **Enable Input Hint** are both enabled by default. 5. Click **Save and Enable**. -## Features Supported +## Credentials + +| Field | Required | Description | +|-------|----------|-------------| +| **AppID** | Yes | The bot's app ID, shown on the QQ Bot Open Platform when the bot is created. | +| **AppSecret** | Yes | The bot's app secret, shown only once at creation. | +| **Markdown Support** | No | Enable Markdown formatting (default: enabled). | +| **Enable Input Hint** | No | Show typing indicators while the bot generates a response (default: enabled). | + +## Verify + +Send `/help` to the bot in a direct message, or @mention it in a group chat with `/help`. The bot replies with its command list, which confirms the channel is working. + +## Group chats + +The bot works in QQ group chats and thread (话题) conversations: @mention it in a group to trigger a reply. + +## Disable and rotate credentials + +Disable or remove the channel at any time from the bot's **Platforms** tab. To rotate credentials, update **AppID** / **AppSecret** in the same panel and save. -- **Message Content**: Full support for text messages. -- **Markdown**: Rich formatting with bold, italic, code blocks, and links. -- **Attachments**: Support for images and files. -- **Typing Indicators**: Visual feedback while generating responses. -- **Target Types**: C2C (direct message), group, and channel. +## FAQ {#faq} -## Official Resources +### I lost the AppSecret {#appsecret-reset} -- [QQ Bot Open Platform](https://q.qq.com/) -- [QQ Bot Documentation](https://bot.q.qq.com/wiki/) +**AppSecret** is shown only once, when the bot is created. Viewing it again on the QQ Bot Open Platform forces a reset; after the reset, update **AppSecret** in Memoh and save. diff --git a/docs/integrations/channels/slack.md b/docs/integrations/channels/slack.md index 2d71cd3..b97d595 100644 --- a/docs/integrations/channels/slack.md +++ b/docs/integrations/channels/slack.md @@ -1,14 +1,24 @@ # Slack Channel Configuration -Connecting your Memoh Bot to Slack allows it to receive direct messages, participate in channels and threads, read attachments, send files, and use streaming replies. +Connect your Memoh bot to Slack to receive direct messages, join channels and threads, read attachments, send files, and reply with streaming. -## Step 1: Create a Slack App +## Prerequisites -1. Go to the Slack API dashboard and create a new app. +- A Slack workspace you can install apps into, and access to the [Slack API dashboard](https://api.slack.com/apps). +- A Memoh bot; channels are configured from its **Platforms** tab. + +## Steps + +### 1. In the Slack console, create an app + +1. Go to the [Slack API dashboard](https://api.slack.com/apps) and create a new app. 2. Choose the workspace where you want to install the bot. -3. Open **Basic Information** and keep this app page open for the next steps. -## Step 2: Enable Socket Mode +::: tip +Keep the app settings page open — steps 2 through 5 all happen there. +::: + +### 2. In the Slack console, enable Socket Mode Memoh's Slack adapter uses Socket Mode, so you need an app-level token in addition to the bot token. @@ -16,9 +26,9 @@ Memoh's Slack adapter uses Socket Mode, so you need an app-level token in additi 2. Create an **App-Level Token** with the `connections:write` scope. 3. Copy the generated token. It starts with `xapp-`. -## Step 3: Configure Bot Token Scopes +### 3. In the Slack console, add bot token scopes -In **OAuth & Permissions**, add the bot token scopes required by the current Slack adapter: +In **OAuth & Permissions**, add the bot token scopes required by the Slack adapter: - `app_mentions:read` - receive bot mentions in channels - `channels:history` - read messages in public channels @@ -30,16 +40,16 @@ In **OAuth & Permissions**, add the bot token scopes required by the current Sla - `files:write` - upload outbound files - `reactions:write` - add and remove reactions -You should also add these recommended scopes if you want Slack conversation names and metadata to show up more completely in Memoh: +Also add these recommended scopes if you want Slack conversation names and metadata to show up more completely in Memoh: - `channels:read` - `groups:read` - `im:read` - `mpim:read` -## Step 4: Subscribe to Bot Events +### 4. In the Slack console, subscribe to bot events -In **Event Subscriptions**, enable bot events and add: +In **Event Subscriptions**, enable bot events and add the inbound event types the Slack adapter handles: - `app_mention` - `message.channels` @@ -47,38 +57,60 @@ In **Event Subscriptions**, enable bot events and add: - `message.im` - `message.mpim` -These are the inbound event types currently handled by the Slack adapter. - -## Step 5: Install the App to Your Workspace +### 5. In the Slack console, install the app to your workspace 1. In **OAuth & Permissions**, click **Install to Workspace**. -2. Review the permission screen. -3. Authorize the app. -4. Copy the **Bot User OAuth Token**. It starts with `xoxb-`. +2. Review the permission screen and authorize the app. +3. Copy the **Bot User OAuth Token**. It starts with `xoxb-`. -Make sure the `xoxb-...` bot token and the `xapp-...` app-level token come from the same Slack app and workspace. +### 6. In Memoh, add the Slack channel -## Step 6: Configure Memoh - -1. Open your Bot detail page in the Memoh Web UI. -2. Go to the **Platforms** tab. -3. Click **Add Channel** and select **Slack**. -4. Fill in: +1. Open your bot's detail page and go to the **Platforms** tab. +2. Click **Add Channel** and select **Slack**. +3. Fill in: - **Bot Token**: your `xoxb-...` token - **App-Level Token**: your `xapp-...` token -5. Click **Save and Enable**. +4. Click **Save and Enable**. + +### 7. In Slack, add the bot to conversations + +After the channel is enabled, the Slack app still needs to be present in the conversations where you want it to work: + +- Direct messages: open a DM with the app and send a message. +- Public channels: invite the bot to the channel. +- Private channels: invite the bot explicitly after installation. + +## Credentials + +| Field | Description | +|-------|-------------| +| **Bot Token** | The **Bot User OAuth Token** (`xoxb-...`) copied after installing the app to the workspace. | +| **App-Level Token** | The Socket Mode token (`xapp-...`) created with the `connections:write` scope. | + +Both tokens must come from the same Slack app and workspace. + +## Verify + +Invite the bot to a channel and @mention it with `/help`, or send `/help` in a DM with the app. If the bot replies with its command list, the channel is working. + +## Group chats + +Slack channels are supported. Invite the bot to a public or private channel, then @mention it to talk to it there. Replies can continue in threads — Slack is the only channel with thread support. + +## Disable and rotate credentials + +You can disable or remove this channel at any time from the bot's **Platforms** tab. To rotate credentials, update the **Bot Token** and **App-Level Token** fields and save. + +## FAQ {#faq} -## Step 7: Add the Bot to Conversations +### Why does Slack need two tokens? {#why-two-tokens} -After the channel is enabled, the Slack app still needs to be present in the conversations where you want it to work. +Memoh's Slack adapter uses Socket Mode: the `xapp-...` app-level token is required in addition to the `xoxb-...` bot token, and both must come from the same Slack app and workspace. -- For direct messages: open a DM with the app and send a message. -- For public channels: invite the bot to the channel. -- For private channels: invite the bot explicitly after installation. +### The bot can send messages but cannot read uploaded images or files {#cannot-read-files} -If the bot can send messages but cannot read uploaded images or files, check that `files:read` is enabled. If it connects but receives no incoming messages, check the bot events and the matching history scopes again. +Check that the `files:read` scope is enabled. -## Features Supported +### The bot connects but receives no incoming messages {#no-incoming-messages} -- **Direct Messages and Channels**: Support for DMs, public channels, private channels, and threads. -- **Attachments**: Read uploaded images and files from Slack, and send files back. +Check the bot events in **Event Subscriptions** and the matching `history` scopes again. diff --git a/docs/integrations/channels/telegram.md b/docs/integrations/channels/telegram.md index 583ecf0..2c8ca19 100644 --- a/docs/integrations/channels/telegram.md +++ b/docs/integrations/channels/telegram.md @@ -1,31 +1,46 @@ # Telegram Channel Configuration -This guide walks you through connecting your Memoh Bot to Telegram. Telegram is one of the most supported platforms in Memoh, featuring streaming responses, Markdown formatting, and attachment support. +Connect your Memoh bot to Telegram — one of the most fully supported channels in Memoh, with streaming responses, Markdown formatting, and attachments. -## Step 1: Create a Telegram Bot +## Prerequisites -You need to create a bot on Telegram to get an API token. +- A Telegram account; you create the bot by talking to **@BotFather**. +- A Memoh bot; channels are configured from its **Platforms** tab. + +## Steps + +### 1. In Telegram, create a bot with @BotFather 1. Open Telegram and search for the official **@BotFather** bot. 2. Send the `/newbot` command. 3. Follow the prompts: - - **Name**: Choose a display name for your bot (e.g., `My Memoh Bot`). - - **Username**: Choose a unique username ending in `bot` (e.g., `my_memoh_bot`). -4. BotFather will provide you with an **API Token** (e.g., `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`). **Keep this token secret.** + - **Name**: a display name for your bot (e.g., `My Memoh Bot`). + - **Username**: a unique username ending in `bot` (e.g., `my_memoh_bot`). +4. BotFather replies with an **API Token** (e.g., `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`). **Keep this token secret.** + +> Official guide: [Telegram Bot Tutorial](https://core.telegram.org/bots/tutorial) + +### 2. In Memoh, add the Telegram channel + +1. Open your bot's detail page and select the **Platforms** tab. +2. Click **Add Channel** and select **Telegram**. +3. Paste the **API Token** into the credentials field. +4. Click **Save and Enable**. + +## Credentials + +| Field | Description | +|-------|-------------| +| **API Token** | The token BotFather issues when you create the bot (e.g., `123456789:ABC...`). Keep it secret. | + +## Verify -> Official Guide: [Telegram Bot Tutorial](https://core.telegram.org/bots/tutorial) +Open a direct chat with your bot in Telegram and send `/help`. If the bot replies with its command list, the channel is working. -## Step 2: Configure Memoh +## Group chats -1. Go to your Bot's **Detail Page** in the Memoh Web UI. -2. Select the **Platforms** tab. -3. Click **Add Channel** and select **Telegram**. -4. Paste your **API Token** into the credentials field. -5. Click **Save and Enable**. +Telegram group chats are supported. Add the bot to a group and @mention it by its username to talk to it there. -## Features Supported +## Disable and rotate credentials -- **Streaming**: Responses appear as the bot "thinks." -- **Markdown**: Support for bold, italic, code blocks, and links. -- **Attachments**: Send images or files to the bot; the bot can also send files back. -- **Replies**: The bot understands context from message replies. +You can disable or remove this channel at any time from the bot's **Platforms** tab. To rotate the token, update the **API Token** field and save. diff --git a/docs/integrations/channels/wechatoa.md b/docs/integrations/channels/wechatoa.md deleted file mode 100644 index 690610d..0000000 --- a/docs/integrations/channels/wechatoa.md +++ /dev/null @@ -1,59 +0,0 @@ -# WeChat Official Account Channel Configuration - -This guide covers the **WeChat Official Account** adapter in Memoh. It is different from the personal **WeChat** QR-login adapter: this one is for official-account webhook integration and is intended for inbound private-message scenarios. - -## Step 1: Prepare Official Account Credentials - -From the WeChat Official Account platform, prepare: - -- **App ID** -- **App Secret** -- **Token** - -You may also need: - -- **Encoding AES Key** if you use encrypted webhook delivery -- an outbound **HTTP Proxy URL** if your deployment must reach WeChat APIs through a proxy - -## Step 2: Add The Channel In Memoh - -1. Open your bot in the Memoh Web UI. -2. Go to **Platforms**. -3. Click **Add Channel** and choose **WeChat Official Account**. -4. Fill in the required fields: - - **App ID** - - **App Secret** - - **Token** -5. Choose the **Encryption Mode**. -6. If you use `safe` or `compat` mode, also provide the **Encoding AES Key**. -7. Save the channel. - -Memoh generates a **Webhook Callback URL** after the channel has been saved. - -## Step 3: Configure The WeChat Platform - -1. Copy the **Webhook Callback URL** from Memoh. -2. Paste it into the WeChat Official Account platform callback configuration. -3. Make sure the WeChat platform and Memoh use the same: - - **Token** - - **Encryption Mode** - - **Encoding AES Key** when encryption is enabled - -WeChat will verify the callback before delivering real messages. - -## Step 4: Enable And Test - -1. Enable the channel in Memoh. -2. Send a test private message from the official account side. -3. Confirm that Memoh receives the message and the bot can reply. - -## Features Supported - -- **Private chats** -- **Replies** -- **Attachments and media** - -Current behavior notes: - -- This adapter is intended for **private-message** conversations, not group-style chats. -- Outbound responses are non-streaming on this channel. diff --git a/docs/integrations/channels/wecom.md b/docs/integrations/channels/wecom.md index d59cef7..ae909b1 100644 --- a/docs/integrations/channels/wecom.md +++ b/docs/integrations/channels/wecom.md @@ -1,40 +1,51 @@ # WeCom (WeWork) Channel Configuration -Connecting your Memoh Bot to WeCom (企业微信) allows it to interact with users within your organization's WeCom workspace. +Connect your Memoh bot to WeCom (企业微信) so it can talk with users in your organization's WeCom workspace, in direct messages and in group chats. -## Step 1: Create a WeCom Bot +## Prerequisites + +- Admin access to the [WeCom Admin Console](https://work.weixin.qq.com/), to create the bot application. + +## Steps + +### 1. Create a WeCom bot + +In the WeCom admin console: 1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/). 2. Navigate to **App Management** > **Custom Apps** or **Bot Management**. 3. Create a new bot application. 4. Note the **Bot ID** and **Secret** credentials. -## Step 2: Configure Memoh +> Official docs: [WeCom Open Platform](https://developer.work.weixin.qq.com/) · [WeCom Bot Documentation](https://developer.work.weixin.qq.com/document/path/91770) + +### 2. Add the channel in Memoh + +In Memoh: -1. Go to your Bot's **Platforms** tab in the Memoh Web UI. +1. Open the bot's **Platforms** tab. 2. Click **Add Channel** and select **WeCom**. -3. Fill in the required fields: +3. Fill in **Bot ID** and **Secret**; set a custom **WebSocket URL** only if you need one. +4. Click **Save and Enable**. + +Once enabled, Memoh connects to WeCom over WebSocket and begins receiving messages. + +## Credentials | Field | Required | Description | |-------|----------|-------------| | **Bot ID** | Yes | The WeCom bot identifier. | | **Secret** | Yes | The bot's authentication credential. | -| **WebSocket URL** | No | Custom WebSocket endpoint (uses default if empty). | - -4. Click **Save and Enable**. +| **WebSocket URL** | No | Custom WebSocket endpoint; the default endpoint is used when empty. | -## Step 3: Start Chatting +## Verify -Once the channel is enabled, the bot will connect to WeCom via WebSocket and begin receiving messages. Users in your WeCom workspace can send messages to the bot directly or in group chats. +Send `/help` to the bot in a direct message, or @mention it in a group chat with `/help`. The bot replies with its command list, which confirms the channel is working. -## Features Supported +## Group chats -- **Message Content**: Full support for text messages. -- **Direct Messages**: Private conversations with individual users. -- **Group Chats**: Participate in group conversations. -- **Streaming**: Responses are streamed in real-time. +The bot also works in WeCom group chats: @mention it in a group to trigger a reply. -## Official Resources +## Disable and rotate credentials -- [WeCom Open Platform](https://developer.work.weixin.qq.com/) -- [WeCom Bot Documentation](https://developer.work.weixin.qq.com/document/path/91770) +Disable or remove the channel at any time from the bot's **Platforms** tab. To rotate credentials, update **Bot ID** / **Secret** in the same panel and save. diff --git a/docs/integrations/channels/weixin.md b/docs/integrations/channels/weixin.md index d429919..875575c 100644 --- a/docs/integrations/channels/weixin.md +++ b/docs/integrations/channels/weixin.md @@ -1,34 +1,52 @@ # WeChat Channel Configuration -Connecting your Memoh Bot to WeChat allows it to interact with users directly via WeChat personal messaging. Setup is simple — just scan a QR code. +Connect your Memoh bot to WeChat personal messaging: setup is a QR-code login, with no manual token or API key entry. -## Step 1: Add WeChat Channel in Memoh +::: warning Limits +- Private chats only. +- Output is plain text; Markdown is not rendered. +- Text messages are split into chunks of at most 4000 characters. +- Responses are delivered as complete messages; output is not streamed. +::: -1. Go to your Bot's **Platforms** tab in the Memoh Web UI. -2. Click **Add Channel** and select **WeChat**. +## Prerequisites -## Step 2: Scan the QR Code +- WeChat on your phone, signed in to the account the bot will use — you approve the login by scanning a QR code. -1. Click **Start QR Login**. Memoh will fetch a QR code from the WeChat platform. +## Steps + +### 1. Add the WeChat channel in Memoh + +In Memoh, open the bot's **Platforms** tab, click **Add Channel**, and select **WeChat**. + +### 2. Scan the QR code + +In Memoh: + +1. Click **Start QR Login**. Memoh fetches a QR code from the WeChat platform. 2. Open WeChat on your phone and scan the displayed QR code. 3. Confirm the login on your phone when prompted. -4. Once confirmed, Memoh automatically saves the credentials — no manual token or API key entry is needed. -The QR code has a limited validity window. If it expires before you scan, click **Start QR Login** again to get a fresh one. +Once confirmed, Memoh saves the credentials automatically and the channel is enabled. + +## Credentials + +QR login stores the session credentials automatically — there are no fields to fill in. One optional setting is available: + +| Field | Required | Description | +|-------|----------|-------------| +| **Enable Typing** | No | Show a typing indicator while the bot generates a response. | + +## Verify -## Step 3: Start Chatting +After the QR login succeeds, the channel is enabled automatically. Send `/help` to the bot in a WeChat private chat; the bot replies with its command list, which confirms the channel is working. -After the QR login succeeds, the channel is automatically enabled. Users can now send messages to the bot directly in WeChat. +## Disable and rotate credentials -## Optional Settings +Disable or remove the channel at any time from the bot's **Platforms** tab. To sign in again, click **Start QR Login** and repeat the QR flow. -| Field | Description | -|-------|-------------| -| **Enable Typing** | Show typing indicators while generating responses. | +## FAQ {#faq} -## Features Supported +### The QR code expired before I scanned it {#qr-expired} -- **Message Content**: Full support for text messages. -- **Direct Messages**: Private conversations with individual users. -- **Attachments**: Support for images and media. -- **Typing Indicators**: Visual feedback while generating responses (when enabled). +The QR code is valid for a limited window. Click **Start QR Login** again to fetch a fresh one. diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 1dbea7c..442a57f 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -4,7 +4,7 @@ Integrations connect Memoh to external systems. Use this section when you want a ## Channels -Channels make bots reachable outside the web app. +Channels make bots reachable outside the Memoh app. - **[Channels Overview](/integrations/channels/)**: Supported platforms and general setup flow. - **[Slack](/integrations/channels/slack)**, **[Telegram](/integrations/channels/telegram)**, **[Feishu](/integrations/channels/feishu)**, **[Discord](/integrations/channels/discord)**, **[WeChat](/integrations/channels/weixin)**, and more. @@ -14,8 +14,8 @@ Channels make bots reachable outside the web app. Providers connect Memoh to external capability backends. - **[LLM Providers](/integrations/providers/llm)**: Configure upstream APIs, client types, and model roles. -- **[Memory Providers](/integrations/providers/memory/)**: Choose built-in memory, Mem0, or OpenViking. -- **[TTS Providers](/integrations/providers/tts/)**: Configure speech synthesis providers and models. +- **[Memory Providers](/integrations/providers/memory/builtin)**: Choose built-in memory, Mem0, or OpenViking. +- **[TTS Providers](/integrations/providers/tts/edge)**: Configure speech synthesis providers and models. - **[Web Search Providers](/integrations/providers/web-search)**: Configure search provider access. ## Product Guides diff --git a/docs/integrations/providers/index.md b/docs/integrations/providers/index.md deleted file mode 100644 index c5bdb1b..0000000 --- a/docs/integrations/providers/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Providers - -Providers connect Memoh to external capability backends. Configure them before assigning models, memory, speech, or search behavior to bots. - -## Provider Types - -- **[LLM Providers](./llm.md)**: Chat, embedding, image, and related model configuration. -- **[Memory Providers](./memory/index.md)**: Long-term memory storage and retrieval backends. -- **[TTS Providers](./tts/index.md)**: Speech synthesis providers and voices. -- **[Web Search Providers](./web-search.md)**: Search providers used by web access tools. - -For product-level usage after provider setup, see **[Bot](../../guides/bot.md)** and **[Memory](../../guides/memory.md)**. diff --git a/docs/integrations/providers/llm.md b/docs/integrations/providers/llm.md index a98e76a..488760d 100644 --- a/docs/integrations/providers/llm.md +++ b/docs/integrations/providers/llm.md @@ -7,7 +7,7 @@ To use Memoh effectively, you usually configure: - optional **speech providers** if you want text-to-speech - optional **transcription providers** if you want speech-to-text -The Web UI manages chat and embedding providers/models from the **Models** page. Speech models are managed from [TTS Providers](./tts/index.md), and transcription models are managed from the Transcription settings page. +Chat and embedding providers/models are managed from the **Models** page in the app. Speech models are managed from [TTS Providers](./tts/edge.md), and transcription models are managed from the Transcription settings page. --- @@ -70,7 +70,7 @@ Memoh currently supports these client types: | `microsoft-speech` | Microsoft speech providers | | `google-transcription` | Google transcription providers | -Speech and transcription client types are for audio workflows, not for chat. Configure speech through [TTS Providers](./tts/index.md) and transcription through the Transcription settings page. Exact model and voice availability depends on the configured provider template and upstream account. +Speech and transcription client types are for audio workflows, not for chat. Configure speech through [TTS Providers](./tts/edge.md) and transcription through the Transcription settings page. Exact model and voice availability depends on the configured provider template and upstream account. --- @@ -151,7 +151,7 @@ Memoh distinguishes four model types: Important distinction: - The **Models** page is primarily where you manage `chat` and `embedding` models. -- `speech` models are exposed through [TTS Providers](./tts/index.md). +- `speech` models are exposed through [TTS Providers](./tts/edge.md). - `transcription` models are exposed through the Transcription settings page. --- @@ -185,7 +185,7 @@ If a model supports reasoning, it may also declare `reasoning_efforts` such as ` `context_window` is important because Memoh uses it to: -- calculate session context usage in the Web UI +- calculate session context usage in the app - power `/status` output - decide when a session is approaching its prompt limit - guide [Context Compaction](../../guides/compaction.md) @@ -216,7 +216,7 @@ Use embedding models with memory providers or any feature that relies on vector ## Speech And Transcription Models -Speech models are managed from [TTS Providers](./tts/index.md), not from the standard chat provider flow. +Speech models are managed from [TTS Providers](./tts/edge.md), not from the standard chat provider flow. Current speech provider categories include: @@ -256,6 +256,6 @@ You do not need to force one model to do everything. ## Next Steps -- To assign chat, image, memory, and TTS settings to a bot, see [Bot Management](../../guides/bot.md). -- To configure speech providers and speech models, see [TTS Providers](./tts/index.md). -- To configure speech-to-text, open the Transcription settings page in the Web UI. +- To assign chat, image, memory, and TTS settings to a bot, see [Bot Management](../../guides/working-with-bots.md). +- To configure speech providers and speech models, see [TTS Providers](./tts/edge.md). +- To configure speech-to-text, open the Transcription settings page in the app. diff --git a/docs/integrations/providers/memory/builtin.md b/docs/integrations/providers/memory/builtin.md index ec39a81..22b786d 100644 --- a/docs/integrations/providers/memory/builtin.md +++ b/docs/integrations/providers/memory/builtin.md @@ -20,7 +20,7 @@ Semantic retrieval is optional and layered on top: | **Graph** (always on) | PostgreSQL memory nodes/edges | None beyond the main database | Structured recall, relations between memories, compaction, rebuild | | **Semantic index** (optional) | `pgvector` database | The `[pgvector]` database from the Compose stack **and** an embedding model selected on the provider | Vector similarity search over memory nodes | -If no embedding model is set, or the `pgvector` database is not configured, the provider still works in graph-only mode; semantic search is simply skipped. +If no embedding model is set, or the `pgvector` database is not configured, the provider still works in graph-only mode; semantic search is skipped. --- diff --git a/docs/integrations/providers/memory/index.md b/docs/integrations/providers/memory/index.md deleted file mode 100644 index b8514ce..0000000 --- a/docs/integrations/providers/memory/index.md +++ /dev/null @@ -1,30 +0,0 @@ -# Memory Providers - -Memoh uses a **Memory Provider** to define how a bot stores, retrieves, and manages long-term memory. A bot can bind one memory provider in its **General** tab, and that provider becomes the backend for memory extraction and memory search. - -## Available Providers - -Memoh supports the following memory providers: - -- [Built-in](./builtin.md): The default memory system included with Memoh. Stores a memory graph in PostgreSQL and optionally adds pgvector-backed semantic search when an embedding model is configured. -- [Mem0](./mem0.md): SaaS memory provider via the Mem0 API. Requires an API key. -- [OpenViking](./openviking.md): Self-hosted or SaaS memory provider with its own API. - ---- - -## Basic Flow - -1. Open the **Memory Providers** page from the sidebar. -2. Create a provider instance using one of the supported provider types. -3. Configure the provider settings. -4. Open a bot's **General** tab and assign that provider in **Memory Provider**. -5. Manage actual memories from the bot's **Memory** tab. - ---- - -## Next Steps - -- [Built-in Memory Provider](./builtin.md) — Default, self-hosted; PostgreSQL graph plus optional pgvector semantic index. -- [Mem0 Memory Provider](./mem0.md) — SaaS via Mem0 API. -- [OpenViking Memory Provider](./openviking.md) — Self-hosted or SaaS. -- [Bot Memory Management](../../../guides/memory.md) — Manage memory entries after the provider is assigned. diff --git a/docs/integrations/providers/tts/index.md b/docs/integrations/providers/tts/index.md deleted file mode 100644 index 6d1c3db..0000000 --- a/docs/integrations/providers/tts/index.md +++ /dev/null @@ -1,46 +0,0 @@ -# TTS Providers - -Memoh supports **Text-to-Speech (TTS)** so bots can synthesize spoken audio from text. The TTS system is organized into three layers: - -- **TTS Provider**: A service type (e.g. Edge TTS). You create named provider instances from the TTS Providers page. -- **TTS Model**: A specific voice/model under a provider (e.g. `edge-read-aloud`). Models have configurable voice, format, speed, and pitch settings. -- **Bot Assignment**: In Bot Settings, select a TTS Model. The bot can then synthesize speech in conversations. - ---- - -## Basic Flow - -1. Navigate to the **TTS Providers** page from the sidebar. -2. Click **Add** and select a provider type (e.g. `edge`). -3. Click **Create** — the provider's default model is auto-imported. -4. Click the model to configure voice, format, speed, and pitch. -5. Test synthesis with the built-in test button. -6. Open a bot's **General** tab and select the TTS Model. -7. Save — the bot can now synthesize speech. - ---- - -## Available Speech Providers - -| Provider | Description | -|----------|-------------| -| [Edge TTS](./edge.md) | Free, uses Microsoft Edge's public read-aloud API. 256+ voices across 50+ languages. No API key required. | -| OpenAI-compatible speech | Uses OpenAI-compatible speech APIs when configured with a matching provider template and credentials. | -| OpenRouter Speech | Uses OpenRouter speech-capable routes when available to the configured account. | -| ElevenLabs Speech | Uses ElevenLabs text-to-speech models and voices. | -| Deepgram Speech | Uses Deepgram text-to-speech models. | -| MiniMax Speech | Uses MiniMax text-to-speech models. | -| Volcengine Speech | Uses Volcengine speech synthesis models. | -| Alibaba Cloud Speech | Uses Alibaba Cloud speech synthesis models. | -| Microsoft Speech | Uses Microsoft speech synthesis models. | - -Exact model, voice, format, and language availability depends on the provider template and upstream account you configure. - -Transcription is managed separately from TTS. Memoh also supports transcription provider categories for OpenAI-compatible, OpenRouter, ElevenLabs, Deepgram, and Google speech-to-text workflows. - ---- - -## Next Steps - -- To set up the no-key Edge option, continue with [Edge TTS](./edge.md). -- To understand how audio provider client types relate to models, see [Providers And Models](../llm.md). diff --git a/docs/integrations/providers/video.md b/docs/integrations/providers/video.md index c625382..ed925d2 100644 --- a/docs/integrations/providers/video.md +++ b/docs/integrations/providers/video.md @@ -5,7 +5,7 @@ Memoh bots can generate videos through the `generate_video` tool. To enable it y 1. A **video provider** with at least one video model, configured under **Settings → Integrations → Video**. 2. A **Video Generation Model** assigned to the bot under **Bot Settings → Multimedia**. -If a bot has no video model assigned, the `generate_video` tool is simply not offered to it. +If a bot has no video model assigned, the `generate_video` tool is not offered to it. --- diff --git a/docs/integrations/providers/web-search.md b/docs/integrations/providers/web-search.md index 672a959..6c0e935 100644 --- a/docs/integrations/providers/web-search.md +++ b/docs/integrations/providers/web-search.md @@ -15,7 +15,7 @@ Configure your search engines from the **Search Provider** page in the sidebar. | Supported Engines | Notes | |-------------------|-------| | **Brave** | Highly recommended for privacy and performance. | -| **Bing** | Powerful global search capability. | +| **Bing** | Microsoft's index; broad global coverage. | | **Google** | Comprehensive web search. | | **Tavily** | Designed specifically for AI-powered research. | | **SearxNG** | Connect to your own self-hosted search aggregator. | diff --git a/docs/memory-providers/index.md b/docs/memory-providers/index.md index 562d298..c676527 100644 --- a/docs/memory-providers/index.md +++ b/docs/memory-providers/index.md @@ -7,10 +7,10 @@ title: Redirecting import { onMounted } from 'vue' onMounted(() => { - window.location.replace('/integrations/providers/memory/') + window.location.replace('/integrations/providers/memory/builtin') }) - + -Redirecting to [/integrations/providers/memory/](/integrations/providers/memory/). +Redirecting to [/integrations/providers/memory/builtin](/integrations/providers/memory/builtin). diff --git a/docs/self-hosted/desktop.md b/docs/self-hosted/desktop.md index b205c28..1008c0d 100644 --- a/docs/self-hosted/desktop.md +++ b/docs/self-hosted/desktop.md @@ -1,6 +1,6 @@ # Desktop -Memoh Desktop is the native client for Memoh Cloud or a self-hosted Memoh server. It packages the same Web UI into an Electron shell with native windows, tray, menus, and keyboard integration, and it can register the computer it runs on as a **Computer** that your bots can use. +Memoh Desktop is the native client for Memoh Cloud or a self-hosted Memoh server. It packages the same client interface into an Electron shell with native windows, tray, menus, and keyboard integration, and it can register the computer it runs on as a **Computer** that your bots can use. Desktop does **not** run its own local server or database. You always connect it to a Memoh server: either [Memoh Cloud](https://memoh.ai) or your own [Server Deploy](./docker.md). @@ -12,7 +12,7 @@ Choose Desktop when you want: - native menus and keyboard shortcuts for the daily Memoh workflow - to let server-side bots use this computer's files, shell, and browser without running a separate runtime process -Use the Web UI directly if you only need occasional access from a browser. +Use the web client directly if you only need occasional access from a browser. ## Install @@ -35,12 +35,12 @@ Switching to a different server clears the local sign-in state, so you will auth Desktop can register the machine it runs on as a **Computer** that server-side bots can work on, without running a separate runtime process. Enable **This computer**, give it a name, and Desktop keeps the connection alive in the background using the embedded Memoh runtime SDK. Credentials are stored with the OS secure storage. -See [Computers](../guides/computers.md) for the permission model, per-bot setup, and what bots can do on a connected computer. +Access is granted per bot, and write/execute actions require approval by default — see [Access Control](../guides/access.md). ## What Desktop manages - the application window, tray icon, reopen and quit behavior -- native menus wired to the same command registry as the Web UI +- native menus wired to the same command registry as the web client - the connection to the selected server and its cached sign-in state - the optional Remote Runtime connection for **This computer** diff --git a/docs/self-hosted/docker.md b/docs/self-hosted/docker.md index 9ca582f..a724fd4 100644 --- a/docs/self-hosted/docker.md +++ b/docs/self-hosted/docker.md @@ -4,7 +4,7 @@ Server Deploy is the self-hosted Memoh stack for always-on, multi-user or multi- This page documents the Docker Compose server deployment. For the native local client, see [Desktop Installation](./desktop.md). -The default Compose stack includes PostgreSQL, a pgvector database for memory embeddings, a one-shot migration job, the main server with an explicit workspace backend and in-process AI agent, the channel worker, and the web UI. PostgreSQL is the only supported database. +The default Compose stack includes PostgreSQL, a pgvector database for memory embeddings, a one-shot migration job, the main server with an explicit workspace backend and in-process AI agent, the channel worker, and the web client. PostgreSQL is the only supported database. The official Compose stack uses the `containerd` workspace backend. The server image starts an embedded containerd and mounts the runtime files needed by bot workspaces. For Docker Engine and Apple backends, see [Workspace backends](./workspace-backends.md). @@ -16,7 +16,7 @@ The Docker Compose stack consists of multiple services. Some are always started, |---------|---------|-------------| | **server** | *(core)* | Main Memoh server with the configured container runtime backend and in-process AI agent | | **channel** | *(core)* | Channel worker (`memoh-channel`) that owns platform connections and webhooks; talks to the server over internal RPC | -| **web** | *(core)* | Web UI (Vue 3) | +| **web** | *(core)* | Web client (Vue 3) | | **postgres** | *(core)* | PostgreSQL database (system of record) | | **pgvector** | *(core)* | PostgreSQL with `pgvector` used for optional memory embeddings; see [Built-in Memory](../integrations/providers/memory/builtin.md) | | **migrate** | *(core, one-shot)* | Runs `memoh-server migrate up` before the server starts | @@ -24,6 +24,24 @@ The Docker Compose stack consists of multiple services. Some are always started, | **connect-it** | `connectors` | Co-hosted [Connect-It](https://github.com/memohai/connect-it) service backing bot [connectors](../guides/connectors.md) (see below) | +### Connect-It Connectors + +The **connect-it** container runs [Connect-It](https://github.com/memohai/connect-it), the service behind bot [connectors](../guides/connectors.md) — it links third-party services such as GitHub and Notion to bots via OAuth or API keys. It shares Memoh's PostgreSQL instance with its data isolated in a separate `connect_it` schema, and manages its own migrations. + +The install script manages Connect-It end to end: + +- **Fresh installs** enable it by default (`MEMOH_CONNECT_IT_MODE=embedded`, Compose profile `connectors`); connectors work out of the box without creating a token in the Connect-It admin console by hand. +- **Upgrades** keep it off unless it was already enabled; to turn it on, rerun the install script with `MEMOH_CONNECT_IT_MODE=embedded`. +- All credentials — admin password, AES key, cookie secret, and the server-to-server API token — are generated once, written to `.env`, and reused across upgrades. Switching modes later does not lose existing connections. + +After install, the Connect-It admin console is at `http://localhost:8421` (user `admin`; the generated password is printed at the end of the install and stored in `.env`). + +Two things to watch: + +- **OAuth callbacks** go through Connect-It's public address, `http://localhost:8421` by default. If Memoh is accessed from other machines, set `MEMOH_CONNECT_IT_PUBLIC_BASE_URL` to an address those machines (and the OAuth providers) can reach. +- **Mainland-China mirrors**: the Connect-It image lives on ghcr.io, which the memoh.cn registry mirror does not cover. If ghcr.io is unreachable, set `MEMOH_CONNECT_IT_MODE=disabled` to skip it. + + ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) @@ -190,7 +208,7 @@ After startup: | Service | URL | |-----------------|------------------------| -| Web UI | http://localhost:8082 | +| Web client | http://localhost:8082 | | API | http://localhost:8080 | | Connect-It admin console *(with the `connectors` profile)* | http://localhost:8421 | diff --git a/docs/self-hosted/index.md b/docs/self-hosted/index.md index 6bc2414..492702c 100644 --- a/docs/self-hosted/index.md +++ b/docs/self-hosted/index.md @@ -1,11 +1,11 @@ # Self-hosted Overview -Memoh runs as a server stack; the Web UI and the Desktop app are clients for it. Pick the server option first, then decide how you want to access it. +Memoh runs as a server stack; the web client and the desktop app are clients for it. Pick the server option first, then decide how you want to access it. | Use case | Choose | Why | |----------|--------|-----| | Try Memoh with nothing to install | [Memoh Cloud](https://memoh.ai) | Hosted service, same product, no server to run. | -| Shared server, remote access, public/private channels, production uptime, multi-user or multi-tenant usage | [Server Deploy](./docker.md) | The Docker Compose stack keeps the backend, Web UI, PostgreSQL (with pgvector for memory), and workspace runtime online. | +| Shared server, remote access, public/private channels, production uptime, multi-user or multi-tenant usage | [Server Deploy](./docker.md) | The Docker Compose stack keeps the backend, web client, PostgreSQL (with pgvector for memory), and workspace runtime online. | | A native app on your own computer, optionally shared with bots as a Computer | [Desktop](./desktop.md) | Native client that connects to Cloud or your server; it does not run a local server. | ## Server Deploy @@ -21,4 +21,3 @@ Use Desktop when you want Memoh to behave like a native app with a tray icon and ## Related - [Workspace Backends](./workspace-backends.md) explains Docker, containerd, Apple, and local workspace runtime choices. -- [Computers](../guides/computers.md) covers sharing your own machines with bots. \ No newline at end of file diff --git a/docs/self-hosted/workspace-backends.md b/docs/self-hosted/workspace-backends.md index 1f2621e..5a634a0 100644 --- a/docs/self-hosted/workspace-backends.md +++ b/docs/self-hosted/workspace-backends.md @@ -86,7 +86,7 @@ This backend is for local macOS testing through socktainer and Apple Containeriz ## Display, Browser Use, and Computer Use -Container workspaces can provide a display runtime: Xvnc/RFB for the workspace desktop, a headed Chrome/Chromium browser with CDP, and WebRTC sessions for the Web UI display pane. +Container workspaces can provide a display runtime: Xvnc/RFB for the workspace desktop, a headed Chrome/Chromium browser with CDP, and WebRTC sessions for the app's Desktop pane. Use this path when a site needs a real graphical browser. Headless Playwright remains available as an ordinary workspace command, but Browser Use and Computer Use target the headed workspace desktop. @@ -108,4 +108,4 @@ Runtime capabilities differ by backend: | `apple` | Basic local runtime | No | No | Limited | | `local` | Host network | No | Host-level only | No container desktop | -Overlay provider settings are configured per bot in the web UI, not in the global TOML file. The global backend still matters because it decides which overlay driver can run. +Overlay provider settings are configured per bot in the app, not in the global TOML file. The global backend still matters because it decides which overlay driver can run. diff --git a/docs/tts-providers/index.md b/docs/tts-providers/index.md index 2446d86..d110f18 100644 --- a/docs/tts-providers/index.md +++ b/docs/tts-providers/index.md @@ -7,10 +7,10 @@ title: Redirecting import { onMounted } from 'vue' onMounted(() => { - window.location.replace('/integrations/providers/tts/') + window.location.replace('/integrations/providers/tts/edge') }) - + -Redirecting to [/integrations/providers/tts/](/integrations/providers/tts/). +Redirecting to [/integrations/providers/tts/edge](/integrations/providers/tts/edge). diff --git a/docs/zh/about.md b/docs/zh/about.md index 78912b5..88624eb 100644 --- a/docs/zh/about.md +++ b/docs/zh/about.md @@ -2,43 +2,43 @@ Memoh v0.13 是开源的多智能体平台。它让你在一台机器上运行多个 AI Agent,并为每个 Agent 提供自己的 workspace、浏览器、网络、工具和长期记忆。 -Agent 可以通过 Telegram、Discord、飞书、微信、Web UI、邮件等渠道对话;也可以记住上下文、操作浏览器或桌面、调用 MCP 工具、安装技能和连接器、执行定时任务,并按机器人配置访问权限。 +Agent 可以通过 Telegram、Discord、Slack、飞书、微信、钉钉等渠道对话,也可以直接在 Memoh 客户端里聊;也可以记住上下文、操作浏览器或桌面、调用 MCP 工具、安装技能和连接器、执行定时任务,并按 Bot 配置访问权限。 -Memoh 托管版 SaaS 即将开放。如果你更想使用托管服务,而不是自己运维部署,可以加入 [SaaS waitlist](https://memoh.ai/waitlist)。 +更想使用托管服务、而不是自己运维部署?[Memoh Cloud](https://app.memoh.net) 提供与开源版一致的托管服务。 ## 分发方式 ### Desktop -Desktop 是 Memoh Cloud 或自托管服务端的原生客户端。它把 Web UI 包进带系统托盘与快捷键的原生窗口,并可把所在电脑注册为机器人可用的 Computer。它不会运行本地服务端。 +Desktop 是 Memoh Cloud 或自托管服务端的原生客户端。它把同一套客户端界面包进带系统托盘与快捷键的原生窗口,并可把所在电脑注册为 Bot 可用的 Computer。它不会运行本地服务端。 ### Server Deploy -Server Deploy 适合长期在线和多人共享。只要 Memoh 需要服务多个用户、在你的个人电脑离线时继续接入渠道,或作为自托管服务运行,就应该用这一形态。Docker Compose stack 包含后端、Web UI、数据库、记忆服务和 workspace runtime。 +Server Deploy 适合长期在线和多人共享。只要 Memoh 需要服务多个用户、在你的个人电脑离线时继续接入渠道,或作为自托管服务运行,就应该用这一形态。Docker Compose stack 包含后端、网页客户端、数据库、记忆服务和 workspace runtime。 ## v0.13 重点 ### Agent Workspaces -每个机器人可以使用隔离容器 workspace,拥有文件、命令、MCP 托管、网络访问、有头浏览器和图形桌面。本地与桌面部署也可以在明确受信任时使用 trusted local workspace。 +每个 Bot 可以使用隔离容器 workspace,拥有文件、命令、MCP 托管、网络访问、有头浏览器和图形桌面。本地与桌面部署也可以在明确受信任时使用 trusted local workspace。 -### Web 产品 +### 客户端 -Web UI 覆盖了更多日常操作:机器人设置、会话、模型服务商、渠道、workspace 文件、终端和显示面板、应用市场、Hooks、定时任务、访问控制和用户偏好。v0.13 也包含英文、简体中文和日文界面支持。 +客户端覆盖了更多日常操作:Bot 设置、会话、模型服务商、渠道、workspace 文件、终端和桌面面板、应用市场、Hooks、定时任务、访问控制和用户偏好。v0.13 也包含英文、简体中文和日文界面支持。 ### Hooks、定时任务与自动化 -Hooks 可以围绕支持的事件运行小型自动化规则,Schedule 则让周期性工作不依赖正在进行的聊天。来自应用市场的技能与连接器无需写代码即可扩展机器人的能力。 +Hooks 可以围绕支持的事件运行小型自动化规则,Schedule 则让周期性工作不依赖正在进行的聊天。来自应用市场的技能与连接器无需写代码即可扩展 Bot 的能力。 ### 访问控制 -访问控制分成渠道侧聊天权限和 workspace 侧用户权限。机器人 owner 可以允许或屏蔽渠道成员,给注册用户授予 workspace 角色,并在需要更精细匹配时继续使用高级 ACL 规则。 +访问控制分成渠道侧聊天权限和 workspace 侧用户权限。Bot owner 可以允许或屏蔽渠道成员,给注册用户授予 workspace 角色,并在需要更精细匹配时继续使用高级 ACL 规则。 ## 从哪开始 -- **[机器人](./guides/bot.md)** - 创建并配置机器人。 +- **[Bot](./guides/working-with-bots.md)** - 创建并配置 Bot。 - **[模型服务商与模型](./integrations/providers/llm.md)** - 配置模型访问。 -- **[渠道](./integrations/channels/index.md)** - 选择机器人出现的位置。 +- **[渠道](./integrations/channels/index.md)** - 选择 Bot 出现的位置。 - **[技能](./guides/skills.md)** 和 **[应用市场](./guides/supermarket.md)** - 安装可复用能力。 - **[定时任务](./guides/schedule.md)** 和 **[访问控制](./guides/access.md)** - 运维周期性工作和权限。 -- **[自托管](./self-hosted/index.md)** - 部署并维护自己的 Memoh 实例。 +- **[帮助中心](https://memoh.ai/help)** - 订阅、账单与账号类问题,以及联系团队的入口。 diff --git a/docs/zh/channels/matrix.md b/docs/zh/channels/matrix.md deleted file mode 100644 index f6c7e35..0000000 --- a/docs/zh/channels/matrix.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/zh/integrations/channels/matrix](/zh/integrations/channels/matrix). diff --git a/docs/zh/channels/misskey.md b/docs/zh/channels/misskey.md deleted file mode 100644 index bc43c5b..0000000 --- a/docs/zh/channels/misskey.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/zh/integrations/channels/misskey](/zh/integrations/channels/misskey). diff --git a/docs/zh/channels/wechatoa.md b/docs/zh/channels/wechatoa.md deleted file mode 100644 index 7f3e33f..0000000 --- a/docs/zh/channels/wechatoa.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/zh/integrations/channels/wechatoa](/zh/integrations/channels/wechatoa). diff --git a/docs/zh/getting-started/email.md b/docs/zh/getting-started/email.md deleted file mode 100644 index 449566b..0000000 --- a/docs/zh/getting-started/email.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: false -title: Redirecting ---- - - - - - -Redirecting to [/zh/guides/email](/zh/guides/email). diff --git a/docs/zh/guides/access.md b/docs/zh/guides/access.md index f28289b..7637c09 100644 --- a/docs/zh/guides/access.md +++ b/docs/zh/guides/access.md @@ -2,8 +2,8 @@ Memoh 的访问控制分成两层: -- **渠道成员**:控制来自 Telegram、Discord、飞书、Matrix、QQ 等 IM 渠道的身份。 -- **工作区成员**:控制 Web App 和工作区里的 Memoh 注册用户。 +- **渠道成员**:控制来自 Telegram、Discord、飞书、QQ 等 IM 渠道的身份。 +- **工作区成员**:控制客户端和工作区里的 Memoh 注册用户。 旧的 ACL 规则模型仍然存在,但现在主要作为渠道聊天权限背后的高级引擎。日常配置应优先从 Bot 的 **Access** 页开始,使用 **渠道成员** 和 **工作区成员** 两个入口。 @@ -14,7 +14,7 @@ Memoh 的访问控制分成两层: | 层级 | 身份 | 控制内容 | |------|------|----------| | **渠道成员** | IM 平台上观测到的渠道身份 | 这个平台身份能否和 Bot 聊天,以及能否通过 IM 命令管理 Bot | -| **工作区成员** | Memoh 注册用户账号 | 这个用户能否在 Web App 使用 Bot、读写文件、执行工作区命令或管理 Bot 设置 | +| **工作区成员** | Memoh 注册用户账号 | 这个用户能否在客户端使用 Bot、读写文件、执行工作区命令或管理 Bot 设置 | 这两层可以通过账号绑定连接起来。工作区用户可在 **Profile -> Connected Accounts** 生成一次性代码,然后在 IM 里向某个 Memoh Bot 发送 `/link `,把发送消息的渠道身份绑定到自己的 Memoh 账号。 @@ -56,7 +56,7 @@ Memoh 的访问控制分成两层: 渠道成员是 IM 侧的访问控制入口。 -每一行代表一个**渠道身份**(一个 Telegram 用户、Discord 成员或 Matrix 用户),或一个**群聊**(见下)。成员从卡片头部的内联选择器添加,个人身份和群聊候选在同一个下拉里分区展示。每一行有两个互相独立的权限: +每一行代表一个**渠道身份**(一个 Telegram 用户或 Discord 成员),或一个**群聊**(见下)。成员从卡片头部的内联选择器添加,个人身份和群聊候选在同一个下拉里分区展示。每一行有两个互相独立的权限: | 权限 | 含义 | |------|------| @@ -130,7 +130,7 @@ Bot 所有者会作为隐式 owner 条目显示,并始终拥有完整权限。 工作区管理权限也会流入渠道成员。若一个拥有工作区管理权限的用户绑定了 Telegram 身份,该 Telegram 身份会在渠道侧继承管理权限。 -工作区的**可对话**不等于渠道的**聊天**。工作区权限授权 Web App 和工作区 API;渠道聊天权限则通过 ACL 引擎授权 IM 入站消息。 +工作区的**可对话**不等于渠道的**聊天**。工作区权限授权客户端与工作区 API;渠道聊天权限则通过 ACL 引擎授权 IM 入站消息。 --- @@ -227,7 +227,7 @@ Bot 所有者会作为隐式 owner 条目显示,并始终拥有完整权限。 访问结果不符合预期时,按顺序检查: -1. **涉及哪一层?** IM 消息走渠道聊天 ACL;Web App 和工作区 API 走工作区成员。 +1. **涉及哪一层?** IM 消息走渠道聊天 ACL;客户端和工作区 API 走工作区成员。 2. **身份是否已绑定?** Connected Accounts 决定工作区管理权限能否继承到渠道成员。 3. **当前渠道访问模式是什么?** 黑名单模式默认允许;白名单模式默认拒绝。 4. **管理权限是继承还是覆盖?** 渠道成员的信息弹窗会显示管理权限是跟随工作区,还是已被本地覆盖。 diff --git a/docs/zh/guides/acp.md b/docs/zh/guides/acp.md index fabf033..13739ad 100644 --- a/docs/zh/guides/acp.md +++ b/docs/zh/guides/acp.md @@ -1,16 +1,16 @@ # Agents / ACP -Memoh 可以把机器人连接到 ACP 兼容的编码智能体。ACP 智能体是外部编码工作流,可以从机器人的聊天 workspace 里工作,同时把自己的会话和普通 chat / discuss 分开。 +Memoh 可以把 Bot 连接到 ACP 兼容的编码智能体。ACP 智能体是外部编码工作流,可以从 Bot 的聊天 workspace 里工作,同时把自己的会话和普通 chat / discuss 分开。 -内置三个 agent profile:**Codex**、**Claude Code**、**Hermes**。它们是当前支持的配置路径,不代表未来只能接这三种。 +内置两个 agent profile:**Codex**、**Claude Code**。它们是当前支持的配置路径,不代表未来只能接这三种。 -ACP 智能体在机器人的容器 workspace 里运行,所以机器人必须使用容器类 workspace backend。 +ACP 智能体在 Bot 的容器 workspace 里运行,所以 Bot 必须使用容器类 workspace backend。 --- ## 设置流程 -1. 打开机器人**详情页** → **Agents** tab。 +1. 打开 Bot**详情页** → **Agents** tab。 2. 每个智能体一行,右侧 Switch 启用,点行进设置。 3. 选 setup 模式,按要求填字段。 4. 保存,然后从聊天 workspace 启动。 @@ -23,7 +23,6 @@ ACP 智能体在机器人的容器 workspace 里运行,所以机器人必须 |--------|---------|-------|--------------| | **Codex** | ✅ | ✅ ChatGPT 登录(设备码) | ✅ | | **Claude Code** | ✅ | ✅ 粘贴 `claude setup-token` 生成的 token | ✅ | -| **Hermes** | ✅ | — | ✅ | **Self-managed** 表示 Memoh 直接用你在 workspace 里自己维护的配置来启动智能体。 @@ -33,23 +32,10 @@ ACP 智能体在机器人的容器 workspace 里运行,所以机器人必须 > 一次性代码只在显示的 OpenAI 验证 URL 上输入——设备码可能被用于钓鱼。 -### Hermes - -Hermes 是随 workspace toolkit 一起分发的 Python 智能体。设置字段: - -- **Provider**——Gemini(Google AI Studio)、OpenRouter、OpenAI API、或自定义端点 -- **Model**——每个 provider 有预设列表,也可填自定义模型 ID -- **Base URL**——仅自定义端点时显示且必填 -- **API Key**——对应所选 provider - ---- - ## Adapter 自动升级 Codex 和 Claude Code 的 adapter 是 npm 包。Memoh 每次服务进程启动后(按 bot)解析一次 npm 上的最新版本并启动它,adapter 的修复不需要升级 Memoh 就能拿到。解析或启动失败时回退到 workspace 镜像里内置的版本,直到下次服务重启。 -Hermes 用 toolkit 里 pin 死的运行时,不自动升级。 - --- ## Reasoning Effort @@ -57,7 +43,7 @@ Hermes 用 toolkit 里 pin 死的运行时,不自动升级。 智能体支持时,可以在 composer 的模型选择器里悬停 **Reasoning** 按会话选择推理力度。 - 可选项(以及它们的名字)由外部智能体自己声明,换模型时可能变化。 -- 未选择时的默认值:Codex 是 `medium`,Claude Code 是 `high`;Hermes 不支持。 +- 未选择时的默认值:Codex 是 `medium`,Claude Code 是 `high`。 - 选择按会话独立,和模型选择互不影响。 之前选的力度失效时,Memoh 会刷新智能体的选项并让你重选,而不是悄悄失败。 @@ -78,19 +64,19 @@ ACP 智能体会话支持消息附件: ## 默认 Agent -机器人的交互设置里有 **默认 Agent** 下拉框——可以选 Memoh 本体,或任一已启用且配置完成的 ACP 智能体。只影响之后新建的一对一会话,已有会话和群聊 Discuss 不受影响。 +Bot 的交互设置里有 **默认 Agent** 下拉框——可以选 Memoh 本体,或任一已启用且配置完成的 ACP 智能体。只影响之后新建的一对一会话,已有会话和群聊 Discuss 不受影响。 --- ## ACP Agent 会话 -ACP 工作使用 `acp_agent` 会话类型,由 Agents/ACP 工作流创建和管理,不走普通 `/new chat` / `/new discuss` 路由。网页端可以按 `acp_agent` 过滤,把编码工作和日常对话分开看。 +ACP 工作使用 `acp_agent` 会话类型,由 Agents/ACP 工作流创建和管理,不走普通 `/new chat` / `/new discuss` 路由。客户端里可以按 `acp_agent` 过滤,把编码工作和日常对话分开看。 --- ## 相关页面 -- [机器人](./bot.md) +- [Bot](./working-with-bots.md) - [会话](./sessions.md) - [文件](./files.md) - [模型服务商与模型](../integrations/providers/llm.md) diff --git a/docs/zh/guides/approvals.md b/docs/zh/guides/approvals.md new file mode 100644 index 0000000..e31adff --- /dev/null +++ b/docs/zh/guides/approvals.md @@ -0,0 +1,50 @@ +# 审批与信任 + +一个能写文件、能执行命令、能给人发消息的 Bot,需要一条你真正理解的边界。这一页从使用者的角度讲清这条边界:Bot 够得着什么、什么时候会停下来问、审批管得住什么又管不住什么。具体机制——成员列表、模式、规则——在 [访问控制](./access.md)。 + +## Bot 默认能碰什么 + +- **自己的工作区,仅此而已。** 每个 Bot 在自己隔离的容器工作区(`/data`)里干活。文件和状态都留在里面,Bot 之间互相看不见——见 [工作区](./container.md)。 +- **只有你接入的渠道和授权的人。** Bot 能出现在某个平台,是因为你在 **平台** 标签页添加了它;能回应某个身份,是因为访问控制放行了。 +- **每个人只有被授予的那一级。** 工作区权限分五级:聊天、读文件、写文件、执行命令、管理;任务需要哪级给哪级,不多给。级别定义见 [访问控制](./access.md)。 + +这些授权来自 Bot **Access** 标签页上的两份成员列表:**渠道成员** 管 IM 平台上的身份,**工作区成员** 管 Memoh 注册用户。 + +## 什么时候会来问你 + +写入和执行类工具调用可以要求人工批准,按 Bot 在 **Tool Approval** 标签页里配置。一个工具被设为需要确认时,流程是: + +1. Bot 提出这个动作——具体到某一次工具调用,此时什么都还没执行。 +2. 你批准或拒绝。 +3. 只有批准的调用才会执行;被拒绝的永远不会跑。 + +审批永远发生在动作之前,所以审一眼请求就是控制权本身,而不是事后补救。等待中的请求也可能超时,不会无限等下去;错过了就让 Bot 把这个动作再试一次。 + +::: tip 想加更多关卡也可以 +在 Tool Approval 设置之外,命中某个事件的 [Hook](./hooks.md) 也能主动发起人工审批——适合只看住某一类命令,而不是拦下整个工具。 +::: + +## 建议留在审批后面的动作 + +以下是建议,不是 Memoh 强制的默认值;当作一份稳妥的起步清单: + +- **会离开工作区的消息**——发给其他人或公开发布的任何内容。 +- **删除或覆盖文件**,尤其是不是 Bot 自己建的那些。 +- **在工作区里执行安装和长时间运行的命令。** +- **任何花钱或触碰生产环境的动作。** + +留在 Bot 自己工作区之内的动作(起草、整理、阅读)最先值得放出审批。这份建议怎么嵌进一个流程的生命周期,从第一次只读运行到逐步放宽,见 [和 Bot 协作](./working-with-bots.md)。 + +## 桌面接管与凭据 + +Bot 在可视化桌面里干活时撞上登录墙或验证码,就由你接管屏幕,亲手输入密码、通行密钥或一次性验证码,然后把控制权交还。凭据从你的键盘直接进网站——你从头到尾不需要把它告诉 Bot。 + +之后浏览器会话留在该工作区里,后续任务保持登录状态,不用再接管一次。见 [浏览器 / 电脑操作](./browser-computer-use.md) 与 [快速开始](./quick-start.md#第-5-步-让它用上工作区和浏览器)。 + +## 一条诚实的边界说明 + +::: warning 审批管不住的部分 +审批拦的是「提议中的动作」——它不能撤销已经执行的工作,也收不回已经发出去的消息。拒绝一个请求只是拦下这一个请求,它不是回滚按钮。 +::: + +所以真正持久的习惯还是 [访问控制](./access.md) 里那条:按任务给最低级别,检查几次运行,再逐步放宽。对 Bot 的信任和对新同事的信任是同一种东西:靠证据一点点建立。 diff --git a/docs/zh/guides/bot.md b/docs/zh/guides/bot.md index dea7f0d..a38758c 100644 --- a/docs/zh/guides/bot.md +++ b/docs/zh/guides/bot.md @@ -1,123 +1,16 @@ -# 机器人 - -机器人是 Memoh 里**独立**的智能体:自带 workspace、长期记忆、可配性格,并能通过各 **渠道** 对话、用工具做事。 - -## 创建 - -1. 侧栏进入 **Bots**。 -2. 点 **Create Bot**。 -3. 基本信息: - - **Display Name**:对外的名字 - - **Avatar**:头像 URL - - **Timezone**:可空;不填则继承用户或系统时区 - - **ACL Preset**:如 `allow_all` 只给自己用、`private_only` 等快捷策略 -4. 创建。 - ---- - -## 详情页 - -点卡片进 **详情**,各 tab 管不同事: - -| Tab | 内容 | -|-----|------| -| **Overview** | workspace runtime、库、渠道、记忆等健康检查 | -| **General** | 主模型/标题/生图、记忆/搜索/TTS 绑定、时区、语言、推理、危险区 | -| **Desktop** | Workspace display runtime、有头浏览器、实时 display session | -| **电脑** | 远程运行时(运行 Memoh runtime 的自有机器),机器人可在其上读写文件、执行命令 | -| **Workspace** | 容器型 workspace 起停、快照、导入导出 | -| **Network** | Workspace 网络与 overlay provider 状态/动作 | -| **Memory** | 浏览、搜、建、改、压记忆 | -| **Platforms** | 各消息渠道(Telegram、Discord、飞书等) | -| **Access** | ACL 与默认通过/拒绝 | -| **Tool Approval** | 需要人类确认的工具审批设置 | -| **Agents** | 可为聊天 workspace 启用的 ACP 兼容编码智能体,如 Codex、Claude Code | -| **Email** | 邮箱绑定、发件箱 | -| **Connectors** | 经 Connect-It 连接的第三方服务(OAuth 或 API Key):状态、启停、重新授权、断开 | -| **Hooks** | 保存在 `/data/.memoh/hooks.json` 的机器人自动化规则 | -| **MCP** | 连接(Stdio/Remote/OAuth) | -| **Compaction** | 会话压缩设置与记录 | -| **Schedule** | cron 与日志 | -| **Skills** | 技能 Markdown | - -Files、Terminal、Display、Browser 这些 workspace 工具在聊天 workspace UI 里,不是机器人详情页 tab。要看文件、跑 shell、操作浏览器或桌面,请进入对应聊天里的 workspace 区域。 - ---- - -## 核心先配什么 - -1. 打开机器人 **General**,先管模型与各类绑定。 -2. **Schedule** 管周期性自主任务。 -3. **Compaction** 管会话写不长时的压缩。 -4. **Access** 在 ACL 预设之后细调。 - -若这些资源还没有,先建好: - -- [模型服务商与模型](../integrations/providers/llm.md) -- [内置记忆提供方](../integrations/providers/memory/builtin.md)(如用) -- [搜索提供方](../integrations/providers/web-search.md) -- [TTS 提供方](../integrations/providers/tts/index.md) -- [Agents / ACP](./acp.md) - ---- - -## General 字段 - -| 字段 | 说明 | -|------|------| -| **Chat Model** | 主对话模型 | -| **Title Model** | 可选,生成会话标题 | -| **Image Generation Model** | 可选,需带 `image-output` 的聊天模型 | -| **Memory Provider** | 长期记忆后端;内置类型还可自带记忆/向量模型 | -| **Search Provider** | 联网搜索用哪家 | -| **TTS Model** | 来自 TTS 提供方流程,不在普通 chat 模型服务商里选 | -| **Timezone** | 不填则用户时区再落到系统 | -| **Language** | 机器人主用语 | -| **Reasoning Effort** | 当前 chat 模型有 `reasoning` 时可用;可选值随模型而定(如 `low` / `medium` / `high`) | - -注意: - -- **生图模型** 故意与主聊天模型分开,好单独换「更擅长出图」的。 -- **TTS** 在 [TTS 提供方](../integrations/providers/tts/index.md) 里用所配置语音提供方的 `speech` 模型。 -- 所选聊天模型的 `context_window` 会影响会话状态展示和 [会话压缩](./compaction.md)。 - ---- - -## Compaction 相关(此处指「会话」) - -这里说的是 **当前会话** 的上下文压短,不是改记忆条目的那种。 - -| 字段 | 说明 | -|------|------| -| **Compaction Enabled** | 是否自动在会话里压摘要 | -| **Compaction Threshold** | 触发的估算 token 阈值 | -| **Compaction Ratio** | 压多狠 | -| **Compaction Model** | 可选,专门做摘要的模型 | - -细节见 [会话上下文压缩](./compaction.md)。 - --- - -## 访问与 ACL - -创建时先给一个 **ACL 预设**,之后在 **Access** 里微调。**预设** 给一版默认策略,**Default Effect** 管「没命中规则时」放行还是挡。 - -[会话](./sessions.md) 与 Discuss 的默认行为在那一页。若你用 API/自动化,配置里还可能有 `discuss_probe_model_id` 等进阶项,日常创建不必先动。 - +layout: false +title: Redirecting --- -## Workspace 文件与终端 + -## 删除 + -**General** 最下 **Danger Zone** -> **Delete Bot**,会删掉该机器人相关数据(含 workspace 文件与记忆等),**不可恢复**。 +Redirecting to [/zh/guides/working-with-bots](/zh/guides/working-with-bots). diff --git a/docs/zh/guides/browser-computer-use.md b/docs/zh/guides/browser-computer-use.md index a7fd3a9..c80b829 100644 --- a/docs/zh/guides/browser-computer-use.md +++ b/docs/zh/guides/browser-computer-use.md @@ -1,6 +1,6 @@ # Browser Use 与 Computer Use -Memoh 可以在机器人 workspace 容器里启动一个可见桌面和有头浏览器。这和跑 headless Playwright 脚本不是一条路径:机器人操作的是网页端 Display pane 里也能看到的那套图形浏览器。 +Memoh 可以在 Bot workspace 容器里启动一个可见桌面和有头浏览器。这和跑 headless Playwright 脚本不是一条路径:Bot 操作的是客户端 **桌面** 面板里也能看到的那套图形浏览器。 ## 概念区别 @@ -14,16 +14,16 @@ Memoh 可以在机器人 workspace 容器里启动一个可见桌面和有头浏 ## Workspace display 与 VNC -Workspace display 是机器人 workspace 容器里的桌面环境。VNC/RFB 是这套桌面的显示和输入传输基础;网页端的 Display 会话使用 WebRTC 承载画面。 +Workspace display 是 Bot workspace 容器里的桌面环境。VNC/RFB 是这套桌面的显示和输入传输基础;客户端的桌面会话使用 WebRTC 承载画面。 重点不是“有 VNC”本身,而是 workspace 能跑有头 Chrome/Chromium。很多登录、验证码、复杂前端状态或只支持真实图形会话的网站,headless 模式不一定可靠。 -## 准备机器人桌面 +## 准备 Bot 桌面 -1. 打开机器人详情页。 +1. 打开 Bot 详情页。 2. 进入 **Desktop** tab。 3. 准备或启用 workspace display runtime。 -4. 从机器人设置页或聊天 workspace 打开 display session。 +4. 从 Bot 设置页或聊天 workspace 打开 display session。 Display runtime 会安装或使用桌面、VNC server、浏览器和字体等组件。具体可用性取决于 workspace backend 和镜像。 @@ -43,12 +43,10 @@ workspace desktop 启用后,agent 可以使用浏览器和电脑操作工具 ### 无障碍辅助二进制 -Computer Use 依赖容器内 `/opt/memoh/toolkit/display/bin/a11y-cli` 以及 workspace 的 `at-spi2-core` 包。Display runtime probe 会返回 `a11y_available`,便于 Web UI 显示无障碍路径是否健康。AT-SPI 不可用时,`computer_action` 仍可用坐标驱动,`computer_observe screenshot` 仍然可用。 +Computer Use 依赖容器内 `/opt/memoh/toolkit/display/bin/a11y-cli` 以及 workspace 的 `at-spi2-core` 包。Display runtime probe 会返回 `a11y_available`,便于客户端显示无障碍路径是否健康。AT-SPI 不可用时,`computer_action` 仍可用坐标驱动,`computer_observe screenshot` 仍然可用。 这些是 workspace runtime 能力,不是用来自动化 Electron 桌面 App 本身的。 -机器人连接了远程[电脑](./computers.md)时,Browser Use / Computer Use 也仍然在**服务器工作区**里跑,不跟随所选使用位置。 - ## 相关页面 - [容器与 Workspace](./container.md) diff --git a/docs/zh/guides/compaction.md b/docs/zh/guides/compaction.md index c2b15f0..b27c4cb 100644 --- a/docs/zh/guides/compaction.md +++ b/docs/zh/guides/compaction.md @@ -8,7 +8,7 @@ ## 现在默认就开着,零配置 -新建的机器人自动压缩**默认启用**,阈值、比例、摘要模型一个都不用配——Memoh 全按聊天模型的 `context_window` 比例来: +新建的 Bot 自动压缩**默认启用**,阈值、比例、摘要模型一个都不用配——Memoh 全按聊天模型的 `context_window` 比例来: - 会话可压缩历史超过窗口约 **50%**:本轮结束后**后台**压。 - 后台没追上、涨过约 **75%**:下一轮发送前**同步**压。 @@ -16,7 +16,7 @@ 唯一的真前提:聊天模型必须在模型设置里声明 `context_window`。没有它,自动策略没有预算基准,**永远不会触发**。见 [模型服务商与模型](../integrations/providers/llm.md)。 -默认值变更之前建的机器人保留原有设置、按原语义跑(见下面的 legacy 模式)。 +默认值变更之前建的 Bot 保留原有设置、按原语义跑(见下面的 legacy 模式)。 --- @@ -26,7 +26,7 @@ | 字段 | 说明 | |------|------| -| **Compaction Enabled** | 默认开。关掉即禁用本机器人的自动压缩。 | +| **Compaction Enabled** | 默认开。关掉即禁用本 Bot 的自动压缩。 | | **Compaction Threshold** | 输入 token 阈值。`0`(默认)= 上面的自动比例策略;**大于 0** 切到 legacy 绝对阈值模式。 | | **Compaction Ratio** | 压多狠。只在 legacy 模式下生效——阈值为 `0` 时这个字段直接隐藏。 | | **Compaction Model** | 可选的专用摘要模型。默认继承聊天模型;设过 override 也可以清回 **Use chat model (default)**。 | @@ -35,7 +35,7 @@ 启用的 chat 模型基本都行,唯一限制:provider 必须尊重输出 token 上限。**OpenAI Codex 系模型当不了摘要模型**——下拉框里直接筛掉了。 -要注意的场景:机器人主聊天模型本身就是 Codex 时,自动压缩因为没有可继承的合法模型会**静默不跑**。这种情况显式配一个 Compaction Model。 +要注意的场景:Bot 主聊天模型本身就是 Codex 时,自动压缩因为没有可继承的合法模型会**静默不跑**。这种情况显式配一个 Compaction Model。 --- @@ -82,7 +82,7 @@ ## 记录 -机器人详情 **Compaction** tab 可看各次:成功/失败、摘要或预览、涉多少条消息、起止时间、若有的模型与用量。用来确认**自动**有没有在跑、失败原因等。 +Bot 详情 **Compaction** tab 可看各次:成功/失败、摘要或预览、涉多少条消息、起止时间、若有的模型与用量。用来确认**自动**有没有在跑、失败原因等。 ### 常见失败原因 diff --git a/docs/zh/guides/computers.md b/docs/zh/guides/computers.md deleted file mode 100644 index 40716a7..0000000 --- a/docs/zh/guides/computers.md +++ /dev/null @@ -1,77 +0,0 @@ -# 电脑(远程 Runtime) - -可以把你自己的电脑接进 Memoh 部署,让机器人在上面干活:读写文件、跑命令。Web UI 里这叫**电脑**(Computers);机器人这边以**使用位置**(Work locations)的形式在它们之间选。 - -Agent 本体不挪窝。模型调用、聊天、会话、记忆全在 Memoh server 上——接进来的电脑只提供文件系统和命令执行,在 agent 眼里就是又一个 workspace。 - -连接方向是电脑**主动连 server** 的 WebSocket。电脑不需要公网 IP、不需要开端口,在 NAT 后面也行。 - -::: danger 想清楚你在共享什么 -接入的电脑暴露的是跑 runtime 的那个系统用户能访问的文件,命令也**以该用户身份**执行。没有目录沙箱:那个用户碰得到的,有权限的机器人就碰得到。只有你明确添加了这台电脑的机器人才能用它,写/执行默认也要审批——但心态上要按"给了个 shell"来对待。 -::: - ---- - -## 接入一台电脑 - -### 命令行方式 - -1. 打开 Web UI 设置里的 **电脑** 页。 -2. 创建一个 runtime key(形如 `mrk_...`;任何登录用户都能建,电脑归创建 key 的用户所有)。 -3. 在要接入的电脑上跑页面生成的命令(Node.js 20+): - -```bash -npx --yes @memohai/runtime --server https://your-memoh-server/api --key mrk_xxxx -``` - -连接强制 `wss://`(TLS);纯 `http` 只允许 localhost 且要加 `--insecure-localhost`(适用时 UI 会自动带上)。断线自动指数退避重连。 - -server 地址和 key 也可以用环境变量 `MEMOH_RUNTIME_SERVER` / `MEMOH_RUNTIME_KEY` 给。 - -### 桌面版方式 - -Memoh Desktop 内置了这个能力:打开**这台电脑**开关、起个名字,App 进程内直接连——不用另开终端。key 用系统钥匙串加密存储,重启自动恢复连接,并且绑定配置时的 server(桌面版换连别的 server 时它会进错误状态,不会悄悄挂到新 server 上)。 - -### key 管理 - -- **吊销** key 会立刻断开对应电脑。 -- key 对所有者保持可见,方便日后再复制连接命令——也就是说 server 侧是可读存储的,server 数据库要按敏感数据保护。 - ---- - -## 机器人的使用位置 - -每个机器人有一组**使用位置**(Work locations): - -- **服务器工作区**——机器人在 server 上的常规容器 workspace。恒定存在,删不掉。 -- 你加给这个机器人的若干**电脑**。 - -其中恰好一个是**默认位置**,没特别指定时活都在那干。给机器人加电脑需要 bot 管理权限,且电脑只能挂到**同一个用户**拥有的机器人上。 - -位置行会显示状态:在线、离线、或 **Update required**(电脑上的 `@memohai/runtime` 客户端比 server 要求的旧——重启 `npx` 会自动拿最新版)。 - -### 按请求选位置 - -- 聊天输入框有**电脑选择器**,单条消息的活可以指定到某个位置。 -- Agent 每次工具调用也可以指定位置;指定的位置不可用时**明着报错**,绝不静默回落到 server 或别的电脑。 -- Agent 可以用 `list_execution_locations` 工具列出当前机器人的位置。 - -### 按位置的工具审批 - -每个位置有自己独立的审批策略:**读 / 写 / 执行**各自设 allow / ask / deny。电脑的默认值:读 **allow**、写 **ask**、执行 **ask**——机器人可以随便看,但要改你机器上的文件或跑命令得先问。审批请求钉在发起时的那个位置上。 - ---- - -## 限制 - -- **Browser Use / Computer Use 永远在服务器工作区里跑**,不跟随所选位置。 -- **ACP agent 会话**不支持指定电脑。 -- 路径:runtime 以系统用户的 home 目录为工作根;工具调用里的 `~` 和 `/data` 会映射到 home,兼容容器 workspace 的路径习惯。 - ---- - -## 相关页面 - -- [Workspace](./container.md) -- [Browser / Computer Use](./browser-computer-use.md) -- [自托管总览](../self-hosted/index.md) diff --git a/docs/zh/guides/connectors.md b/docs/zh/guides/connectors.md index 45ae03f..ea64a16 100644 --- a/docs/zh/guides/connectors.md +++ b/docs/zh/guides/connectors.md @@ -24,7 +24,7 @@ api_token = "" # 服务端之间的可信 token ## 连接一个服务 -1. 在 Web UI 中打开 **应用市场**。 +1. 在客户端打开 **应用市场**。 2. 停在 **Connectors** tab——配置了连接器时它排在第一个,也是默认落地的 tab。 3. 选一个连接器,点 **Connect**。 4. 选择目标 Bot。 diff --git a/docs/zh/guides/container.md b/docs/zh/guides/container.md index c7bac18..f6b875b 100644 --- a/docs/zh/guides/container.md +++ b/docs/zh/guides/container.md @@ -1,10 +1,10 @@ # 工作区(Workspace)与容器 -每个机器人都在一个 workspace 里工作。Server Deploy 里通常是隔离容器、Pod 或类似 VM 的 runtime;在受信任的 Desktop/local 场景里,也可以是宿主机上的本地目录。workspace 提供文件系统、命令执行环境、MCP runtime,以及可选的图形桌面。 +每个 Bot 都在一个 workspace 里工作。Server Deploy 里通常是隔离容器、Pod 或类似 VM 的 runtime;在受信任的 Desktop/local 场景里,也可以是宿主机上的本地目录。workspace 提供文件系统、命令执行环境、MCP runtime,以及可选的图形桌面。 ## 是什么 -可以把 workspace 想成机器人私用的一台小电脑。它能: +可以把 workspace 想成 Bot 私用的一台小电脑。它能: - 存文件、改文件 - 在镜像允许时装包 @@ -12,30 +12,28 @@ - 跨会话保留状态 - 可选地运行桌面显示和有头浏览器 -workspace toolkit 自带 **Node.js** 和 **Python** 两套运行时(`pip`、`uv` 都在 PATH 上),机器人跑 Python 脚本、装包不用先折腾解释器。 - -机器人还可以在 server workspace 之外、你接入的机器上干活——见 [电脑(远程 Runtime)](./computers.md)。 +workspace toolkit 自带 **Node.js** 和 **Python** 两套运行时(`pip`、`uv` 都在 PATH 上),Bot 跑 Python 脚本、装包不用先折腾解释器。 底层容器 runtime 由 `config.toml` 的 `[container].backend` 决定,trusted local workspace 另行控制。官方 Docker Compose Server Deploy 使用 `containerd`;Docker Engine、Apple 和 local workspace 的差异见 [Workspace backend](../self-hosted/workspace-backends.md)。 ## Workspace 相关 tab -机器人详情页里有几组和 workspace 相关的 tab: +Bot 详情页里有几组和 workspace 相关的 tab: | Tab | 内容 | |-----|------| -| **Container** | 容器生命周期、快照、导入导出、CDI 设备。 | +| **工作区** | 容器生命周期、快照、导入导出、CDI 设备。 | | **Desktop** | Workspace display runtime、有头浏览器可用性、实时 display session、关闭会话。 | | **Network** | Workspace 网络与 overlay provider 状态/动作。 | | **Tool Approval** | 需要人类确认的工具审批设置。 | -| **Files** | 浏览和编辑机器人 workspace 文件系统。 | +| **Files** | 浏览和编辑 Bot workspace 文件系统。 | | **Terminal** | 在当前 workspace runtime 里打开交互 shell。 | -如果机器人使用 trusted local workspace,一些只适用于容器 runtime 的 tab 或按钮可能会隐藏或不可用。 +如果 Bot 使用 trusted local workspace,一些只适用于容器 runtime 的 tab 或按钮可能会隐藏或不可用。 ## 容器生命周期 -在 **Container** tab 管容器型 workspace: +在 **工作区** tab 管容器型 workspace: - **Create**:没有就按镜像建;拉镜像、建实例时会有 SSE 进度。 - **Start**:启动 workspace runtime。 @@ -48,11 +46,11 @@ workspace toolkit 自带 **Node.js** 和 **Python** 两套运行时(`pip`、`u **Desktop** tab 用来准备和检查图形 workspace runtime。它会检查 desktop toolkit、Xvnc/VNC、浏览器和当前 display session。 -启用后,workspace 可以在容器里跑有头 Chrome/Chromium。网页端 Display pane 会连接到同一个桌面会话,你和 agent 看到、操作的是同一个可见浏览器。工具层面的区别见 [Browser / Computer Use](./browser-computer-use.md)。 +启用后,workspace 可以在容器里跑有头 Chrome/Chromium。客户端的 **桌面** 面板会连接到同一个桌面会话,你和 agent 看到、操作的是同一个可见浏览器。工具层面的区别见 [Browser / Computer Use](./browser-computer-use.md)。 ## 运行时信息 -**Container** tab 会显示: +**工作区** tab 会显示: - container id 与状态 - 镜像 @@ -62,11 +60,11 @@ workspace toolkit 自带 **Node.js** 和 **Python** 两套运行时(`pip`、`u ## 进阶:CDI 设备 -要把宿主机通过 **CDI**(常见是 GPU)透进容器,在 **Container** -> **Advanced** 里配。一般只有确实要在里面跑 CUDA/ROCm 等才要动。 +要把宿主机通过 **CDI**(常见是 GPU)透进容器,在 **工作区** -> **Advanced** 里配。一般只有确实要在里面跑 CUDA/ROCm 等才要动。 ### 配法 -1. 打开 **Container**。 +1. 打开 **工作区**。 2. 没有容器先 **Create**;要改 GPU 类设置往往要**重建**容器。 3. 展开 **Advanced**。 4. 开 **GPU**,在 **CDI devices** 里写设备名。 @@ -97,7 +95,7 @@ workspace toolkit 自带 **Node.js** 和 **Python** 两套运行时(`pip`、`u - CDI 在**创建**时生效,改配置后常要**重建**容器;只停再起**不会**换已挂设备。 - 镜像里仍要装对的用户态库和工具,才能真正跑 CUDA/ROCm 软件。 -- 建好后 **Container** tab 会显示当前挂上的设备,便于核对。 +- 建好后 **工作区** tab 会显示当前挂上的设备,便于核对。 ## 快照 @@ -105,7 +103,7 @@ workspace toolkit 自带 **Node.js** 和 **Python** 两套运行时(`pip`、`u ## 导入导出 -**Container** tab 支持导入导出 workspace 数据: +**工作区** tab 支持导入导出 workspace 数据: - **Export Data**:把 workspace 文件系统数据打成包下载。 - **Import Data**:从本地上传归档并解进 workspace 文件系统。 diff --git a/docs/zh/guides/email.md b/docs/zh/guides/email.md deleted file mode 100644 index 387e802..0000000 --- a/docs/zh/guides/email.md +++ /dev/null @@ -1,55 +0,0 @@ -# 邮件 - -让机器人**收/发**邮件,分两步:**邮服提供方** + 机器人上的 **Email 绑定**。 - -## 在做什么 - -1. 先配能连上的 **Email Provider**(如 Mailgun、泛用 SMTP 等)。 -2. 再在某个机器人上,把某邮箱**绑定**过去,并设读/写/删权限。 - ---- - -## 邮服 - -侧栏 **Email Provider**。 - -邮服提供方**按用户隔离**:每人配自己的、只看得见自己的,机器人绑定也只能用机器人所属用户自己的提供方。不同用户可以重名,互不冲突。 - -::: tip Gmail OAuth -Gmail 类提供方的 OAuth 应用凭据(client ID / client secret)不再在界面里填——由部署方在 server 的 `conf/oauth-clients.toml` 里配一次。用户只走 Gmail 登录授权流程。 -::: - -### 新建 - -1. **Add Email Provider** -2. 类型如 **Mailgun**(量大)、**泛用 SMTP**(传统邮件服务器) -3. 按表单填 `domain`/`api_key` 或 `host`/`port` 等 -4. 创建 - ---- - -## 机器人上的绑定 - -机器人 **Email** tab。 - -### 添加 - -1. **Add Binding** -2. 选已建的 **Email Provider** -3. 填要绑的 **Email Address** -4. 勾权限: - - **Can Read** 收信、处理入站 - - **Can Write** 发信 - - **Can Delete** 管邮箱里删除等(视实现) -5. 创建 - -### 发件箱 - -**Outbox** 会记发出的邮件:收信人、主题、状态、时间,便于对账、排错。 - ---- - -## 和机器人 - -- 有权限时可用邮件发报告、回邮、或按新邮件做事。 -- 和聊天一样,是另一条渠道,但仍是结构化、可审的。 diff --git a/docs/zh/guides/extensions.md b/docs/zh/guides/extensions.md new file mode 100644 index 0000000..680a14c --- /dev/null +++ b/docs/zh/guides/extensions.md @@ -0,0 +1,37 @@ +# 扩展能力怎么选 + +Memoh 有五种给 Bot 加能力的方式。单看名字很容易混,摆在一起就清楚了——所以直接摆在一起。 + +| 扩展方式 | 它是什么 | 放在哪 / 怎么触发 | 适合什么 | +|----------|----------|-------------------|----------| +| [技能](./skills.md) | 改变 Bot 做事方式的 `SKILL.md` 提示模块 | 在 Bot 工作区的 `/data/skills/` 下,从 **Skills** 标签页管理;在对话中唤起 | 那些本来每次都要重打一遍的流程和工作习惯 | +| [Hooks](./hooks.md) | 写在 `hooks.json` 里、可以运行命令或工具的事件规则 | 在 `/data/.memoh/hooks.json`,从 **Hooks** 标签页编辑;在 `PreToolUse`、`TurnEnd` 这类生命周期事件上触发 | 固定节点上的检查和附带动作,全程不经过聊天 | +| [MCP](./mcp.md) | 到外部 MCP 工具服务器的连接 | 按 Bot 在 **MCP** 标签页配置,Stdio 或 Remote 连接;发现的工具在对话中使用 | 接入一个本身就带 MCP server 的工具 | +| [连接器](./connectors.md) | 到 GitHub、Notion 这类服务的 OAuth 或 API Key 绑定 | 从应用市场的 **Connectors** 标签页连接,在 Bot 的 **Connectors** 标签页管理;服务的工具出现在对话里 | 让 Bot 用你在某个托管服务上的账号做事 | +| [应用市场](./supermarket.md) | Memoh 内置目录:一键安装打包好的应用——技能连同它的依赖和连接器 | 在 **设置** 下;装好的内容落进目标 Bot 自己的各个标签页 | 直接拿到现成能力,不用自己拼零件 | + +不管能力从哪条路进来,最后都汇到同一个地方:连接器和 MCP 的工具在对话里与工作区工具并列出现,装好的技能出现在 Bot 的 **Skills** 标签页里,和手写的没有两样。 + +## 该用哪个? + +- 想改 Bot 的做事方式 → [技能](./skills.md)。 +- 想在某个事件点自动做事 → [Hooks](./hooks.md)。 +- 想接一个有 MCP server 的工具 → [MCP](./mcp.md)。 +- 想让 Bot 用你的 GitHub/Notion 账号 → [连接器](./connectors.md)。 +- 想一键装现成的一套 → [应用市场](./supermarket.md)。 + +::: tip 它们可以叠着用 +这五种不是互斥选项。应用市场装的一个应用可能同时带来技能和连接器,Hook 也可以看住经 MCP 接进来的工具。按上面的问题选,而不是每个 Bot 只挑一种。 +::: + +## 从哪开始 + +每种方式都有完整的一页,展开这张表压缩掉的细节: + +- [技能](./skills.md)——`SKILL.md` 的写法、技能状态、收编发现的技能。 +- [Hooks](./hooks.md)——事件目录、配置结构、怎么测试一条规则。 +- [MCP](./mcp.md)——Stdio 与 Remote 连接、OAuth、工具发现。 +- [连接器](./connectors.md)——连接状态、重新授权、工具命名空间。 +- [应用市场](./supermarket.md)——浏览目录、安装到 Bot。 + +拿不定主意就先逛应用市场——装一个现成的包,先看看成品长什么样,再动手搭自己的。 diff --git a/docs/zh/guides/files.md b/docs/zh/guides/files.md index 5f96ae0..5ce4fad 100644 --- a/docs/zh/guides/files.md +++ b/docs/zh/guides/files.md @@ -1,6 +1,6 @@ # 文件 -每个机器人都有自己的 **workspace 文件系统**。服务端部署里通常在容器型 workspace 内;受信任的桌面/本地模式下也可能是本地 workspace 目录。在 **Files** tab 里可以直接管理。 +每个 Bot 都有自己的 **workspace 文件系统**。服务端部署里通常在容器型 workspace 内;受信任的桌面/本地模式下也可能是本地 workspace 目录。在 **Files** tab 里可以直接管理。 --- @@ -11,7 +11,7 @@ ### 浏览 - 面包屑上下级 -- **Refresh** 看机器人刚写的文件 +- **Refresh** 看 Bot 刚写的文件 - **New Folder** 建目录 ### 文件 @@ -31,6 +31,6 @@ --- -## 和机器人 +## 和 Bot -机器人自己也能用技能、MCP 等改这些文件;**Files** 是你**肉眼查看、手改** workspace 的入口。 +Bot 自己也能用技能、MCP 等改这些文件;**Files** 是你**肉眼查看、手改** workspace 的入口。 diff --git a/docs/zh/guides/get-started.md b/docs/zh/guides/get-started.md index f7a4f33..fccee1d 100644 --- a/docs/zh/guides/get-started.md +++ b/docs/zh/guides/get-started.md @@ -1,127 +1,16 @@ -# 入门教程 +--- +layout: false +title: Redirecting +--- -Memoh 给你的机器人是真能干活的:每个机器人都有自己的工作区——完整的文件系统、可执行的终端、以及可选的带浏览器的可视化桌面——外加长期记忆和你本来就在用的聊天渠道。 + -::: tip 想找安装方法? -本页假定你已经能打开一个 Memoh 实例。如果你需要自己部署,请先看 [快速开始](./quick-start.md)。 -::: + -## 开始之前 - -你需要: - -- 一个可访问的 Memoh 实例,以及能创建机器人的账号。 -- 至少一个模型提供方的 API Key(OpenAI、Anthropic、Gemini、DeepSeek、智谱、OpenRouter、Ollama 等)。如果管理员已经配好了,跳过即可。 - -## 1. 登录 - -打开 Memoh Web UI 并登录。 - -如果这是一个全新实例,请立刻在 **Settings → Account** 修改初始密码。 - -界面语言、主题等选项随时可以在 [偏好设置](./preferences.md) 里调整,不影响下面的步骤。 - -## 2. 添加模型提供方 - -没有模型,机器人就无法思考。如果管理员已经配置过,跳过这一步。 - -1. 在侧边栏打开 **Providers**,点击 **Add Provider**。 -2. 选择模板,填入 API Key,保存。 -3. 打开该提供方并**同步**模型列表,或手动添加至少一个对话模型。 - -各家的客户端类型、Base URL 和注意事项见 [LLM 提供方](../integrations/providers/llm.md)。 - -## 3. 创建第一个机器人 - -进入 **Bots → New Bot**,填写名称和显示名,然后在 **General** 标签页选择对话模型。 - -接下来写它的指令。这一步最关键,也最容易出错——通常是写得太笼统。把一件事说清楚: - -> **名称:** Digest -> -> **角色:** 每周阅读摘要 -> -> **指令:** 收集我这一周发给你的文章。每周五整理成一份摘要,按主题分组:每篇一句话概括并附原始链接,最后加一节"值得再读"。原始链接保持不变。任何内容都不要公开发布。 - -职责单一的机器人能积累的有效上下文,远多于什么都干的机器人。当工作确实分成不同角色时,请新建一个机器人,而不是把这个越堆越重——每个机器人都有独立的工作区、记忆和配置。逐个标签页的说明见 [机器人](./bot.md)。 - -点击 **Chat** 打个招呼。收到回复就说明模型链路是通的。 - -## 4. 交给它第一个任务 - -一个好的首次请求会回答五个问题: - -| 要素 | 它回答的问题 | -|------|------------| -| **结果** | 做完之后应该存在什么? | -| **来源** | 涉及哪些文件、网站或对话? | -| **约束** | 什么不能碰,什么需要你批准? | -| **形式** | 结果以什么形式交付? | -| **确认点** | 什么时候该停下来跟你确认? | - -想在几分钟内看到结果、又不需要任何外部登录,可以上传一份文档试试: - -```text -把这份文档总结成五个要点。另起一节,列出其中所有的日期、决定和待解决问题, -并标注每条来自哪一页或哪一节。不要修改原文件。 -``` - -机器人会在自己的工作区里读取文件,并把结果写回对话。它产出的一切都留在工作区,你可以在 [文件](./files.md) 里浏览和编辑。 - -## 5. 让它用上工作区和浏览器 - -工作区是机器人不再只是聊天机器人的地方。它有 Linux 文件系统、终端和预装工具链(Python、Node.js、uv、npm),能真正把活干完: - -```text -把我刚上传的 CSV 里 email 列为空的行全部删掉。 -给我清洗后的文件,并告诉我删了多少行。 -``` - -当任务需要真实浏览器时——比如无头模式下会出错的站点,或需要登录才能访问的页面——在机器人的 **Desktop** 标签页启用可视化桌面。启动后,机器人会驱动一个有头 Chrome,你可以在 display 面板里看着它操作。 - -遇到登录墙时,你可以自己接管屏幕:输入密码、通行密钥或一次性验证码,然后把控制权交还给它。浏览器会话保留在该工作区中,后续任务依然是登录状态。 - -::: warning 按需授权 -工作区权限是分级的:仅聊天、读文件、写文件、执行命令、管理容器。任务需要哪一级就给哪一级,不要多给。参见 [访问控制](./access.md)。 -::: - -详见 [工作区](./container.md) 与 [浏览器 / 电脑操作](./browser-computer-use.md)。 - -## 6. 接入聊天渠道 - -机器人在你本来就聊天的地方最有用。 - -1. 打开机器人的 **Platforms** 标签页,点击 **Add**。 -2. 选择平台——Telegram、Slack、Discord、飞书、钉钉、企业微信、QQ、LINE、Matrix 或 Misskey——并填入该平台的凭据。 -3. 从该平台给它发消息。第一条消息会创建会话;发送 `/help` 可以看到可用的 [斜杠命令](./slash-commands.md)。 - -从此你可以在手机上派活,然后在同一个对话里收结果。各平台的具体配置见 [渠道](../integrations/channels/index.md)。 - -## 7. 复盘,然后固化下来 - -有问题就直接说。把纠正写成长期规则,而不是一次性修补: - -```text -以后所有的摘要都用这个格式:按主题分组,每篇一行,链接放在行内, -最后加一节"值得再读"。 -``` - -当一套流程稳定下来后,就别再重复输入了: - -- 存成 [技能](./skills.md),以后一句话唤起整套流程。 -- 变成 [定时任务](./schedule.md),按 cron 自动运行,完全不需要聊天。 -- 用 [长期记忆](./memory.md) 把你的偏好和项目上下文带进之后的每一次会话。 - -## 下一步 - -| 目标 | 阅读 | -|------|------| -| 逐个标签页配置机器人 | [机器人](./bot.md) | -| 理解聊天、讨论与消息路由 | [会话](./sessions.md) | -| 接入外部工具和数据 | [MCP](./mcp.md)、[连接器](./connectors.md) | -| 安装现成的能力 | [应用市场](./supermarket.md) | -| 把自己的机器接为工作地点 | [电脑](./computers.md) | -| 在生命周期节点挂自己的逻辑 | [钩子](./hooks.md) | -| 控制谁能跟机器人说话 | [访问控制](./access.md) | \ No newline at end of file +Redirecting to [/zh/guides/quick-start](/zh/guides/quick-start). diff --git a/docs/zh/guides/hooks.md b/docs/zh/guides/hooks.md index 2e776cd..067c444 100644 --- a/docs/zh/guides/hooks.md +++ b/docs/zh/guides/hooks.md @@ -1,18 +1,18 @@ # Bot Hooks -Bot Hooks 可以让机器人在工具调用、对话 turn、记忆、workspace 活动、审批、压缩和 subagent 等流程前后运行小型自动化规则。每个机器人都有自己的配置文件: +Bot Hooks 可以让 Bot 在工具调用、对话 turn、记忆、workspace 活动、审批、压缩和 subagent 等流程前后运行小型自动化规则。每个 Bot 都有自己的配置文件: ```text /data/.memoh/hooks.json ``` -打开机器人 **详情页**,进入 **Hooks** tab,就可以从 UI 编辑这个文件。 +打开 Bot **详情页**,进入 **Hooks** tab,就可以从 UI 编辑这个文件。 --- ## Hooks Tab -Hooks tab 是机器人 hook 配置的 JSON 编辑器。它可以: +Hooks tab 是 Bot hook 配置的 JSON 编辑器。它可以: - 显示 `/data/.memoh/hooks.json` 是否存在 - 显示用户配置是否启用 @@ -76,12 +76,12 @@ Hooks tab 是机器人 hook 配置的 JSON 编辑器。它可以: | 字段 | 说明 | |------|------| -| `version` | 必填的 schema 版本。v0.13.0 支持 `1`。 | +| `version` | 必填的 schema 版本。当前版本为 `1`。 | | `enabled` | 启用或停用这个用户配置文件里的 hooks。默认 `true`。 | | `defaults.timeout` | 默认 action 超时时间。支持 `10s` 这类 Go duration,也支持整数秒。默认 `10s`。 | | `defaults.on_error` | 默认错误处理:`ignore`、`fail` 或 `block`。默认 `fail`。 | | `defaults.max_output_bytes` | 每个 command action 捕获 stdout/stderr 的最大字节数。默认 `65536`。 | -| `defaults.trigger_nested_hooks` | schema 会解析这个字段,默认 `false`;v0.13.0 的 Hooks UI 没有单独控件。 | +| `defaults.trigger_nested_hooks` | schema 会解析这个字段,默认 `false`;Hooks UI 目前没有单独控件。 | | `env` | 用户配置里的 command action 会使用的额外环境变量。 | | `hooks` | 规则列表。命中后按 `priority` 从高到低运行,同优先级保持文件顺序。 | @@ -95,7 +95,7 @@ Hook 字段: | `enabled` | 启用或停用这个 hook。默认 `true`。 | | `priority` | 数字越大越先运行。 | | `actions` | hook 命中后要运行的 action。 | -| `conditions` | schema 中保留给未来扩展;v0.13.0 匹配时使用 `event`、`enabled` 和 `matcher`。 | +| `conditions` | schema 中保留给未来扩展;目前匹配时使用 `event`、`enabled` 和 `matcher`。 | `matcher` 的目标文本按下面顺序从 hook 请求里选择: @@ -110,7 +110,7 @@ Hook 字段: ## Action 类型 -v0.13.0 支持两类 action:`command` 和 `tool`。 +目前支持两类 action:`command` 和 `tool`。 ### Command Action @@ -124,7 +124,7 @@ v0.13.0 支持两类 action:`command` 和 `tool`。 } ``` -`command` action 会在机器人 workspace 容器内运行。hook 请求会作为 JSON 通过 stdin 传入,末尾带换行。 +`command` action 会在 Bot workspace 容器内运行。hook 请求会作为 JSON 通过 stdin 传入,末尾带换行。 工作目录解析顺序: @@ -169,9 +169,9 @@ v0.13.0 支持两类 action:`command` 和 `tool`。 } ``` -`tool` action 会按名称调用一个可用的机器人工具,并传入配置里的 `input`。如果工具结果是对象,可以返回 `decision`、`reason` 和 `append_context`。 +`tool` action 会按名称调用一个可用的 Bot 工具,并传入配置里的 `input`。如果工具结果是对象,可以返回 `decision`、`reason` 和 `append_context`。 -`mcp_tool` 在代码里是保留类型,但 v0.13.0 会拒绝它。 +`mcp_tool` 在代码里是保留类型,但目前会被拒绝。 --- @@ -198,7 +198,7 @@ action 可以返回这些 decision: ## 事件目录 -Hooks tab 会从 `/bots/{bot_id}/hooks/events` 加载事件目录。标记为 runtime-supported 的事件已经接入 v0.13.0 执行路径。catalog-only 事件可以通过配置解析和测试接口,但 v0.13.0 没有实际的运行时路径会发出这些事件。 +Hooks tab 会从 `/bots/{bot_id}/hooks/events` 加载事件目录。标记为 runtime-supported 的事件已经接入当前执行路径。catalog-only 事件可以通过配置解析和测试接口,但目前没有实际的运行时路径会发出这些事件。 | Event | 区域 | 已接入运行时 | 说明 | |-------|------|--------------|------| @@ -232,10 +232,10 @@ Hooks tab 会从 `/bots/{bot_id}/hooks/events` 加载事件目录。标记为 ru | `PostCompact` | 压缩 | 是 | 会话压缩后运行。 | | `SubagentStart` | Subagent | 是 | subagent 任务开始前运行。 | | `SubagentStop` | Subagent | 是 | subagent 任务结束后运行。 | -| `InboundMessageNormalized` | 消息 | 否 | v0.13.0 中仅存在于事件目录。 | -| `BeforeOutboundMessage` | 消息 | 否 | v0.13.0 中仅存在于事件目录。 | -| `AfterOutboundMessage` | 消息 | 否 | v0.13.0 中仅存在于事件目录。 | -| `ChannelDeliveryFailed` | 消息 | 否 | v0.13.0 中仅存在于事件目录。 | +| `InboundMessageNormalized` | 消息 | 否 | 目前仅存在于事件目录。 | +| `BeforeOutboundMessage` | 消息 | 否 | 目前仅存在于事件目录。 | +| `AfterOutboundMessage` | 消息 | 否 | 目前仅存在于事件目录。 | +| `ChannelDeliveryFailed` | 消息 | 否 | 目前仅存在于事件目录。 | --- @@ -254,10 +254,10 @@ Hooks tab 会从 `/bots/{bot_id}/hooks/events` 加载事件目录。标记为 ru ## 安全注意事项 -Hooks 很强大。请把它们当成会在机器人 workspace 里运行的代码来对待。 +Hooks 会在 Bot workspace 里实际执行。请把它们当成跑在那里的代码来对待。 - 启用前审查每个 command action。 -- 小心使用 `PreToolUse`、`BeforeWorkspaceCommand` 和 `BeforeFileWrite`;它们可能阻断机器人的正常工作。 +- 小心使用 `PreToolUse`、`BeforeWorkspaceCommand` 和 `BeforeFileWrite`;它们可能阻断 Bot 的正常工作。 - 保持较短 timeout,并明确设置 `on_error`。 - 不要把长期有效的 secrets 直接写进 `hooks.json`。 - 对高风险 hooks 使用尽量窄的 `matcher`。 @@ -267,5 +267,5 @@ Hooks 很强大。请把它们当成会在机器人 workspace 里运行的代码 ## 相关页面 -- [机器人](./bot.md) +- [Bot](./working-with-bots.md) - [技能](./skills.md) diff --git a/docs/zh/guides/index.md b/docs/zh/guides/index.md index cf5db2f..906d23f 100644 --- a/docs/zh/guides/index.md +++ b/docs/zh/guides/index.md @@ -1,39 +1,42 @@ # 参考文档 -欢迎查阅 Memoh 参考文档。部署、配置和运维 Memoh 所需的一切都在这里,按三大板块组织。 +欢迎查阅 Memoh 参考文档。安装、配置和使用 Memoh 所需的一切都在这里,按三大板块组织。 ## 新手入门 -刚接触 Memoh?从这里开始。学习如何部署、添加模型、创建第一个机器人、接入渠道,并处理日常基础操作。 +刚接触 Memoh?从这里开始。学习如何安装应用、创建第一个 Bot、接入渠道,并处理日常基础操作。 -- **[入门教程](./get-started.md)**:手把手教程——登录、创建机器人、交给它真实任务、接入渠道。 -- **[快速开始](./quick-start.md)**:十分钟内部署服务端、添加模型、创建第一个机器人并接入渠道。 +- **[概览](./overview.md)**:Memoh 是什么,各个部件如何搭在一起。 +- **[快速开始](./quick-start.md)**:安装应用、登录、创建第一个 Bot、交给它真实任务,并接入聊天平台。 +- **[和 Bot 协作](./working-with-bots.md)**:什么任务适合交给 Bot、请求怎么说、什么时候拆多个 Bot——外加逐 tab 的配置参考。 - **[用户偏好](./preferences.md)**:配置界面语言、主题、字体、图表和快捷键。 -- **[机器人](./bot.md)**:创建机器人并配置核心标签页。 - **[会话](./sessions.md)**:理解 chat、discuss、路由和状态区。 -- **[文件](./files.md)**:浏览和编辑机器人 workspace 文件。 +- **[文件](./files.md)**:浏览和编辑 Bot workspace 文件。 - **[斜杠命令](./slash-commands.md)**:用命令快捷完成日常控制。 -- **[部署](../self-hosted/index.md)**:选择托管方式并部署自己的实例。 - **[渠道](../integrations/channels/index.md)**:把 Memoh 接入 Slack、Telegram、飞书、Discord 等平台。 ## 进阶教程 基础就绪后深入使用。这些页面涵盖高级能力、自动化与外部提供方。 +- **[扩展能力怎么选](./extensions.md)**:技能、Hooks、MCP、连接器、应用市场,该用哪个。 - **[Agents / ACP](./acp.md)**:构建多智能体工作流,并接入 Agent Client Protocol。 -- **[访问控制](./access.md)**:配置 ACL 预设、规则顺序和来源限定。 +- **[审批与信任](./approvals.md)**:Bot 能碰什么、什么时候会问你、哪些动作留在审批后面。 +- **[访问控制](./access.md)**:配置 ACL 预设、访问模式和来源限定。 - **[Workspace](./container.md)**:从产品界面理解 workspace 行为。 -- **[电脑(远程 Runtime)](./computers.md)**:把机器注册为远程运行时。 - **[Browser / Computer Use](./browser-computer-use.md)**:使用有头浏览器和可见桌面会话。 - **[技能](./skills.md)** 和 **[应用市场](./supermarket.md)**:添加可复用提示模块和模板。 -- **[连接器](./connectors.md)**:接入 Connect-It 等托管集成。 +- **[连接器](./connectors.md)**:接入 GitHub、Notion 等第三方服务。 - **[Hooks](./hooks.md)** 和 **[MCP](./mcp.md)**:连接工具、自动化规则和外部数据源。 - **[长期记忆](./memory.md)**:配置好记忆提供方后管理长期记忆。 - **[上下文压缩](./compaction.md)**:缩小当前会话上下文占用。 - **[定时任务](./schedule.md)**:按 cron 计划运行周期性工作。 -- **[邮件](./email.md)**:配置邮件相关工作流。 -- **[提供方](../integrations/providers/index.md)**:模型、搜索、视频、记忆与 TTS 提供方。 +- **[模型服务商](../integrations/providers/llm.md)**:模型提供方与模型;搜索、视频、记忆与 TTS 提供方在侧边栏同级可见。 ## 使用场景 -- **[使用场景](./use-cases.md)**:组合多种功能解决实际问题的即用型示例。 \ No newline at end of file +- **[使用场景](./use-cases.md)**:组合多种功能解决实际问题的即用型示例。 + +## 获取帮助 + +本站是产品参考文档。订阅计划、credits 计费、账号类问题,以及联系 Memoh 团队的方式,请访问 [帮助中心](https://memoh.ai/help)。 diff --git a/docs/zh/guides/mcp.md b/docs/zh/guides/mcp.md index e26a29d..782ee96 100644 --- a/docs/zh/guides/mcp.md +++ b/docs/zh/guides/mcp.md @@ -1,10 +1,10 @@ # MCP 连接 -Memoh 支持 **Model Context Protocol (MCP)**,让机器人接外部工具与上下文服务。每个机器人可以有自己的一组 MCP 连接。 +Memoh 支持 **Model Context Protocol (MCP)**,让 Bot 接外部工具与上下文服务。每个 Bot 可以有自己的一组 MCP 连接。 ## 在做什么 -MCP 把「外部数据、外部工具」用相对统一的方式接进来。你在机器人 **MCP** tab 里手配,或从 [应用市场](./supermarket.md) 装模板再进编辑器改。 +MCP 把「外部数据、外部工具」用相对统一的方式接进来。你在 Bot **MCP** tab 里手配,或从 [应用市场](./supermarket.md) 装模板再进编辑器改。 --- @@ -12,7 +12,7 @@ MCP 把「外部数据、外部工具」用相对统一的方式接进来。你 ### 1. Stdio(本机进程) -在机器人**容器里**起本地命令,用标准输入输出通信。 +在 Bot**容器里**起本地命令,用标准输入输出通信。 | 字段 | 说明 | |------|------| @@ -63,6 +63,6 @@ MCP 把「外部数据、外部工具」用相对统一的方式接进来。你 --- -## 和机器人怎么配合 +## 和 Bot 怎么配合 连上后,对话里模型会按说明选用这些工具;发现到的工具会进推理流程。具体工具名、参数以服端为准。 diff --git a/docs/zh/guides/memory.md b/docs/zh/guides/memory.md index 77bb70c..a47b37d 100644 --- a/docs/zh/guides/memory.md +++ b/docs/zh/guides/memory.md @@ -1,11 +1,11 @@ # 长期记忆 -Memoh 的结构化长期记忆让机器人在**多路会话**里也能用上以前留下的事实。用 **Memory** tab 前,先给机器人配好 **Memory Provider**。 +Memoh 的结构化长期记忆让 Bot 在**多路会话**里也能用上以前留下的事实。用 **Memory** tab 前,先给 Bot 配好 **Memory Provider**。 ## 先决条件 -1. 在 [记忆提供方](../integrations/providers/memory/index.md) 里建一个(内置、Mem0、OpenViking 等)。 -2. 打开机器人 **General**。 +1. 在 [记忆提供方](../integrations/providers/memory/builtin.md) 里建一个(内置、Mem0、OpenViking 等)。 +2. 打开 Bot **General**。 3. **Memory Provider** 里选中。 4. 保存。 @@ -38,7 +38,12 @@ Memoh 的结构化长期记忆让机器人在**多路会话**里也能用上以 ## 记忆压缩(注意:不是会话压缩) -积累多了可以在 **Memory** tab 对**存储侧**做 **Compact**:合并重复、去陈旧、压噪声。有 **Ratio**、**Decay Days** 等参数。 +积累多了可以在 **Memory** tab 对**存储侧**做 **Compact**:合并重复、去陈旧、压噪声。 + +参数: + +- **Ratio**:压缩比,如 `0.8`、`0.5`、`0.3`;值越低,压得越激进。 +- **Decay Days**:可选,把压缩范围限定在超过这个天数的旧记忆上,新记忆不动。 这和 [会话上下文压缩](./compaction.md) 不同:后者是**单路会话**里把 prompt 压短,不改库里长期记忆条目的存法与合并结果。 @@ -52,7 +57,7 @@ Memoh 的结构化长期记忆让机器人在**多路会话**里也能用上以 ## 状态 -**Memory** tab 会显示当前该机器人的记忆后端的 **Connected / Error**,排障时先看一眼。 +**Memory** tab 会显示当前该 Bot 的记忆后端的 **Connected / Error**,排障时先看一眼。 --- @@ -74,8 +79,8 @@ Memoh 的结构化长期记忆让机器人在**多路会话**里也能用上以 --- -## 和机器人的关系 +## 和 Bot 的关系 - 聊的时候会按配置去搜记忆。 -- 具体用哪种后端、embedding 等,在**提供方**上配,见 [记忆提供方](../integrations/providers/memory/index.md)。 -- 长期记忆是机器人「个性与事实」里很大一块来源。 +- 具体用哪种后端、embedding 等,在**提供方**上配,见 [记忆提供方](../integrations/providers/memory/builtin.md)。 +- 长期记忆是 Bot「个性与事实」里很大一块来源。 diff --git a/docs/zh/guides/overview.md b/docs/zh/guides/overview.md new file mode 100644 index 0000000..cb4b2bc --- /dev/null +++ b/docs/zh/guides/overview.md @@ -0,0 +1,57 @@ +# Memoh 概览 + +Memoh 给每个 Bot 一台自己的云电脑:带真实文件系统和终端的工作区、可以看见和接管的桌面浏览器,以及跨会话的长期记忆。你的笔记本合上之后,它照常工作。 + +和 Bot 协作的方式就是给它发消息。在 Memoh 应用里聊,或者把它接到 Telegram、Slack、Discord、飞书、钉钉、企业微信、微信、QQ、LINE。无论从哪个入口进来,都是同一个 Bot 和同一份记忆。 + +上手只需要下载应用并登录 Memoh Cloud。托管模型(DeepSeek、Kimi、GPT、Claude 等)开箱即用;想换自己的 API Key 或模型服务,见 [BYOK](./quick-start.md#使用自己的模型-byok)。 + +## Memoh 有什么不同 + +- **一台真实的电脑,不是一次性沙盒。** 写过的文件、装过的运行时都留在 [工作区](./container.md) 里,周一建的东西周五还能接着用。 +- **一块你能看见的屏幕。** Bot 在可视化桌面里操作真实浏览器;遇到登录或验证码,你[接管键鼠](./browser-computer-use.md)处理完再交还给它。 +- **记得住。** [长期记忆](./memory.md) 跨会话、跨渠道生效,纠正过一次的偏好不用再说第二遍。 +- **你不在它也在跑。** [定时任务](./schedule.md) 按 cron 触发,结果发到你接入的渠道;到点检查、有变化才说话。 +- **自带你的编码智能体。** 通过 [ACP](./acp.md) 把 Claude Code、Codex 装进同一个工作区,用你自己的订阅。 + +## 一个 Bot 负责一件事 + +每个 Bot 都有独立的工作区、记忆、渠道和权限边界,互不可见。工作确实分成不同角色时,就多建一个 Bot,而不是把一个越堆越重。谁能和 Bot 聊天、谁能读写它的文件、谁能执行命令,都在 [访问控制](./access.md) 里按级别授予——需要哪级给哪级。 + +## 第一个任务怎么交 + +挑一件你每周都在手动做的小事,说清楚结果、来源和边界: + +> 每周五 17:00,把我这一周发给你的链接和文件整理成一份周报,按主题分组、每条一句话,存进工作区并把摘要发到这个对话。只整理我发给你的内容,不要外发给任何人。 + +Bot 会自己登记定时任务并按周交付。先从只读的活儿开始,检查过几次产出,再逐步放开写入和执行——更多现成搭配见 [使用场景](./use-cases.md)。 + +## 常见问题 + +**我关掉电脑,它还会跑吗?** + +会。Bot 运行在云端工作区里,定时任务照常触发,渠道消息照常回复。 + +**可以建几个 Bot?** + +取决于订阅计划。每个 Bot 都是独立的:自己的工作区、记忆和权限,删除一个不影响其他。 + +**我的文件放在哪?** + +在该 Bot 的隔离容器工作区里(`/data`),跨会话保留,可在 [文件](./files.md) 里随时查看和编辑。 + +**能用自己的模型吗?** + +能。在模型服务商里加自己的 API Key(见 [BYOK](./quick-start.md#使用自己的模型-byok)),编码智能体则在 Bot 的 **Agent** 标签页登录你自己的 Claude Code / Codex 订阅。 + +**订阅和计费的问题去哪问?** + +[帮助中心](https://memoh.ai/help):套餐、credits、账号问题,以及联系 Memoh 团队的入口。 + +## 下一步 + +- [快速开始](./quick-start.md)——从装应用到接入聊天平台,十五分钟。 +- [使用场景](./use-cases.md)——组合多种功能解决实际问题的即用示例。 +- [Bot](./working-with-bots.md)——逐个标签页配置一个 Bot。 +- [渠道](../integrations/channels/index.md)——各聊天平台的接入方法。 +- [帮助中心](https://memoh.ai/help)——订阅、账单与账号问题。 diff --git a/docs/zh/guides/preferences.md b/docs/zh/guides/preferences.md index a7e0858..4d6c1d8 100644 --- a/docs/zh/guides/preferences.md +++ b/docs/zh/guides/preferences.md @@ -1,6 +1,6 @@ # 偏好设置 -Memoh v0.13 提供 Web UI 级别的用户偏好设置。它们会改变当前浏览器或桌面应用配置档里的界面观感和快捷键行为,不会改变机器人的人格、模型、工具、记忆或访问规则。 +Memoh v0.13 提供客户端级别的用户偏好设置。它们会改变当前设备配置档里的界面观感和快捷键行为,不会改变 Bot 的人格、模型、工具、记忆或访问规则。 打开 **Settings**,在 **Appearance** 调整视觉偏好,在 **Keyboard** 调整快捷键。 @@ -14,11 +14,11 @@ Memoh v0.13 提供 Web UI 级别的用户偏好设置。它们会改变当前浏 | 设置 | 作用 | |------|------| -| **Language** | 设置 Web UI 语言。v0.13 包含 English、简体中文和日本語。如果还没有手动选择,Memoh 会根据浏览器语言识别英文、中文或日文,并在无法识别时回退到英文。 | +| **Language** | 设置界面语言。v0.13 包含 English、简体中文和日本語。如果还没有手动选择,Memoh 会根据浏览器语言识别英文、中文或日文,并在无法识别时回退到英文。 | | **Theme** | 选择 Light、Dark 或 System。System 会跟随操作系统或浏览器的颜色模式。 | | **Color Scheme** | 更换品牌元素、状态颜色和界面控件使用的强调色方案。可选 Memoh、Ocean、Forest、Rose、Amber。 | -这里的语言只影响 Memoh 界面。机器人回复时使用什么语言,仍在机器人设置里配置。 +这里的语言只影响 Memoh 界面。Bot 回复时使用什么语言,仍在 Bot 设置里配置。 ### 字体与字号 @@ -95,6 +95,6 @@ macOS 上显示为 `Cmd`,Windows 和 Linux 上显示为 `Ctrl`。 ## 实用说明 -- 外观和快捷键是个人 UI 偏好,不会影响其他用户或机器人。 +- 外观和快捷键是个人 UI 偏好,不会影响其他用户或 Bot。 - 偏好保存在当前设备/浏览器配置档里,换浏览器或换机器后可能需要重新设置。 - 如果试字体或快捷键后界面不合预期,可以回到同一页面重置对应字段或快捷键。 diff --git a/docs/zh/guides/quick-start.md b/docs/zh/guides/quick-start.md index 1a4c081..437a428 100644 --- a/docs/zh/guides/quick-start.md +++ b/docs/zh/guides/quick-start.md @@ -1,91 +1,126 @@ # 快速开始 -大约十分钟即可跑通 Memoh:部署服务端、登录、添加模型服务商、创建第一个机器人,并把它接到一个聊天平台。 - -::: tip 不想自托管? -[Memoh Cloud](https://memoh.ai) 提供与开源版一致的托管服务。登录后可直接跳到 [第 3 步](#第-3-步添加模型服务商)。 -::: +一份从零开始的完整教程:安装应用、登录、创建第一个 Bot、交给它真实工作,并在聊天平台上找到它。大约需要十五分钟。 ## 前置条件 -- 一台安装了 **Docker** 与 **Docker Compose** 的 Linux 服务器或工作站。 -- 至少一个模型服务商的 API Key(OpenAI、Anthropic、DeepSeek、智谱……),或本地 Ollama。 -- 浏览器可以访问服务器的 **8080**(API)与 **8082**(Web UI)端口。 +- 一台 macOS、Windows 或 Linux 电脑。 +- 一个 [Memoh Cloud](https://app.memoh.net) 账号——登录时可以直接注册。 -## 第 1 步:部署服务端 +就这些。Memoh Cloud 内置了托管模型(DeepSeek、Kimi、GPT、Claude 等),上手不需要任何 API Key。 -一行安装脚本会拉取镜像、生成 `config.toml`,并用 Docker Compose 启动全部组件: +## 第 1 步:安装 Memoh -```bash -curl -fsSL https://memoh.sh | sh -``` +从 [下载页](https://memoh.ai/desktop) 下载对应平台的安装包——macOS(DMG)、Windows(安装程序)或 Linux(AppImage/deb/rpm)——然后打开它。 -中国大陆用户可启用镜像加速: +## 第 2 步:登录 -```bash -curl -fsSL https://memoh.sh | USE_CN_MIRROR=true sh -``` +在连接页选择 **Memoh Cloud** 并登录,没有账号就先注册一个。 -::: warning 不要用 `sudo` 运行整个安装脚本 -当前用户不在 `docker` 组时,脚本会自行调用 `sudo docker`。 -::: +## 第 3 步:创建第一个 Bot + +进入 **Bot → 新建 Bot**,填写名称与显示名,然后在 **通用** 标签页选择对话模型。托管模型开箱即用。 + +接下来写它的指令。这一步最关键,也最容易出错——通常是写得太笼统。把一件事说清楚: + +> **名称:** Digest +> +> **角色:** 每周阅读摘要 +> +> **指令:** 收集我这一周发给你的文章。每周五整理成一份摘要,按主题分组:每篇一句话概括并附原始链接,最后加一节"值得再读"。原始链接保持不变。任何内容都不要公开发布。 + +职责单一的 Bot 能积累的有效上下文,远多于什么都干的 Bot。当工作确实分成不同角色时,请新建一个 Bot,而不是把这个越堆越重——每个 Bot 都有独立的工作区、记忆和配置。逐个标签页的说明见 [Bot](./working-with-bots.md)。 + +点击 **聊天** 打个招呼。收到回复就说明模型链路是通的。 + +## 使用自己的模型(BYOK) + +托管模型之外,你随时可以自带模型(Bring Your Own Key): + +1. 在侧边栏打开 **模型服务商**,点击 **添加服务商**。 +2. 选择模板(OpenAI、Anthropic、Gemini、DeepSeek、智谱、OpenRouter、Ollama 等),填入你的 API Key;OpenAI 兼容端点再补上对应的 Base URL。 +3. 打开该服务商并**同步**模型列表,或手动添加至少一个对话模型,然后在 Bot 的 **通用** 标签页切换过去。 -想手动部署?克隆仓库后执行: +BYOK 的模型用量按你所选服务商的价格计费。编码智能体同理:在 Bot 的 **Agent** 标签页,用你自己的订阅或 API Key 登录 Claude Code、Codex。各家的字段与注意事项见 [模型服务商](../integrations/providers/llm.md)。 -```bash -git clone https://github.com/felinics/Memoh.git -cd Memoh -cp conf/app.docker.toml config.toml -# 编辑 config.toml(管理员密码、JWT 密钥等) -docker compose up -d +## 第 4 步:交给它第一个任务 + +一个好的首次请求会回答五个问题: + +| 要素 | 它回答的问题 | +|------|------------| +| **结果** | 做完之后应该存在什么? | +| **来源** | 涉及哪些文件、网站或对话? | +| **约束** | 什么不能碰,什么需要你批准? | +| **形式** | 结果以什么形式交付? | +| **确认点** | 什么时候该停下来跟你确认? | + +想在几分钟内看到结果、又不需要任何外部登录,可以上传一份文档试试: + +```text +把这份文档总结成五个要点。另起一节,列出其中所有的日期、决定和待解决问题, +并标注每条来自哪一页或哪一节。不要修改原文件。 ``` -完成后会看到类似输出: +Bot 会在自己的工作区里读取文件,并把结果写回对话。它产出的一切都留在工作区,你可以在 [文件](./files.md) 里浏览和编辑。 + +## 第 5 步:让它用上工作区和浏览器 + +工作区是 Bot 干活的地方。它有 Linux 文件系统、终端和预装工具链(Python、Node.js、uv、npm),数据清洗、脚本、构建都能直接跑: ```text -🌐 Web UI: http://localhost:8082 -🔌 API: http://localhost:8080 -🔑 Admin login: admin / <你的密码> +把我刚上传的 CSV 里 email 列为空的行全部删掉。 +给我清洗后的文件,并告诉我删了多少行。 ``` -生产环境加固、反向代理与升级方式见 [服务端部署](../self-hosted/docker.md)。 +当任务需要真实浏览器时——比如无头模式下会出错的站点,或需要登录才能访问的页面——在 Bot 的 **桌面** 标签页启用可视化桌面。启动后,Bot 会驱动一个有头 Chrome,你可以在桌面面板里看着它操作。 + +遇到登录墙时,你可以自己接管屏幕:输入密码、通行密钥或一次性验证码,然后把控制权交还给它。浏览器会话保留在该工作区中,后续任务依然是登录状态。 -## 第 2 步:登录 +::: warning 按需授权 +工作区权限是分级的:仅聊天、读文件、写文件、执行命令、管理容器。任务需要哪一级就给哪一级,不要多给。参见 [访问控制](./access.md)。 +::: -打开 `http://<你的服务器>:8082`,使用安装时设置的管理员账号登录(`conf/app.docker.toml` 中的默认值为 `admin` / `admin123`)。登录后请立即在 **设置 → 账户** 中修改密码。 +详见 [工作区](./container.md) 与 [浏览器 / 电脑操作](./browser-computer-use.md)。 -## 第 3 步:添加模型服务商 +## 第 6 步:在聊天平台上找到它 -1. 在侧边栏进入 **模型服务商**,点击 **添加模型服务商**。 -2. 选择模板(OpenAI、Anthropic、Gemini、DeepSeek、智谱、OpenRouter、Ollama……)并填入 API Key。 -3. 进入该模型服务商,**同步** 或手动添加至少一个对话模型。 +Bot 在你本来就聊天的地方最有用。 -更多细节与客户端类型见 [模型服务商](../integrations/providers/llm.md)。 +1. 打开 Bot 的 **平台** 标签页,点击 **添加**。 +2. 选择平台——Telegram、Slack、Discord、飞书、钉钉、企业微信、微信、QQ 或 LINE——并填入该平台的凭据。 +3. 从该平台给它发消息。第一条消息会创建会话;发送 `/help` 可以看到可用的 [斜杠命令](./slash-commands.md)。 -## 第 4 步:创建第一个机器人 +从此你可以在手机上派活,然后在同一个对话里收结果。各平台的具体配置见 [渠道](../integrations/channels/index.md)。 -1. 进入 **机器人 → 新建机器人**,填写名称与显示名。 -2. 在机器人的 **通用** 标签页中选择刚添加的对话模型。 -3. 点击机器人的 **聊天** 按钮打个招呼。收到回复即说明链路已打通。 +## 第 7 步:复盘,然后固化下来 -每个机器人都有独立的工作区、记忆与设置,各标签页说明见 [机器人](./bot.md)。 +有问题就直接说。把纠正写成长期规则,而不是一次性修补: -## 第 5 步:接入聊天平台 +```text +以后所有的摘要都用这个格式:按主题分组,每篇一行,链接放在行内, +最后加一节"值得再读"。 +``` -1. 打开机器人的 **渠道** 标签页,点击 **添加**。 -2. 选择平台(Telegram、Discord、Slack、飞书、钉钉、企业微信、QQ、LINE、Matrix、Misskey……)并填写平台凭据。 -3. 在该平台上给机器人发消息。第一条消息会创建会话;输入 `/help` 查看可用的斜杠命令。 +当一套流程稳定下来后,就别再重复输入了: -各平台的详细配置见 [渠道](../integrations/channels/index.md)。 +- 存成 [技能](./skills.md),以后一句话唤起整套流程。 +- 变成 [定时任务](./schedule.md),按 cron 自动运行,完全不需要聊天。 +- 用 [长期记忆](./memory.md) 把你的偏好和项目上下文带进之后的每一次会话。 ## 下一步 | 目标 | 阅读 | |------|------| -| 让机器人跨会话记住用户 | [记忆](./memory.md) | +| 逐个标签页配置 Bot | [Bot](./working-with-bots.md) | +| 理解聊天、讨论与消息路由 | [会话](./sessions.md) | | 运行定时或周期任务 | [定时任务](./schedule.md) | -| 赋予机器人文件、Shell 与浏览器能力 | [Workspace](./container.md)、[电脑](./computers.md) | -| 通过 MCP 服务器添加工具 | [MCP](./mcp.md) | -| 教会机器人可复用的流程 | [Skills](./skills.md)、[应用市场](./supermarket.md) | -| 控制谁可以和机器人对话 | [访问控制](./access.md) | -| 在 Mac 上用桌面版运行 | [Desktop](../self-hosted/desktop.md) | \ No newline at end of file +| 接入外部工具和数据 | [MCP](./mcp.md)、[连接器](./connectors.md) | +| 安装现成的能力 | [应用市场](./supermarket.md) | +| 在生命周期节点挂自己的逻辑 | [钩子](./hooks.md) | +| 控制谁能跟 Bot 说话 | [访问控制](./access.md) | +| 看看别人怎么用 | [使用场景](./use-cases.md) | + +::: tip 需要帮助? +订阅、credits 或账号相关的问题,以及本文档没有覆盖的疑问,都可以在 [帮助中心](https://memoh.ai/help) 找到答案,也可以从那里联系 Memoh 团队。 +::: diff --git a/docs/zh/guides/schedule.md b/docs/zh/guides/schedule.md index b1a61fd..86b3db2 100644 --- a/docs/zh/guides/schedule.md +++ b/docs/zh/guides/schedule.md @@ -1,10 +1,10 @@ # 定时任务 -用 **cron 表达式** 在固定时间让机器人干一件事:发报告、查外网、维护、或任何能交给智能体+工具完成的活。 +用 **cron 表达式** 在固定时间让 Bot 干一件事:发报告、查外网、维护、或任何能交给智能体+工具完成的活。 ## 是什么 -**Schedule** 绑在某个机器人上。到点就把一条自然语言 **command** 交给智能体,由它用工具、技能去执行,结果可发到已接好的渠道。 +**Schedule** 绑在某个 Bot 上。到点就把一条自然语言 **command** 交给智能体,由它用工具、技能去执行,结果可发到已接好的渠道。 --- @@ -24,7 +24,7 @@ ## Cron(五段) -在服务器时区下算;Memoh 默认使用 **UTC**,可用顶层 `timezone` 改。五段为:分、时、日、月、周。 +按 Bot 的时区求值——即 Bot **通用** 标签页的 **Timezone** 字段;未设置时回退到服务器顶层 `timezone` 配置(默认 **UTC**)。五段为:分、时、日、月、周。 ``` ┌ 分 0–59 @@ -47,15 +47,15 @@ ## 看列表 -机器人 **Schedule** tab:名、pattern、是否启用、执行次数等;**Refresh** 重载。 +Bot **Schedule** tab:名、pattern、是否启用、执行次数等;**Refresh** 重载。 --- ## 创建 -### 让机器人自己建 +### 让 Bot 自己建 -机器人有 `schedule` 工具。你可以说人话,例如让每天 8:00 汇总未读邮件,它会去拼 cron 并登记。 +Bot 有 `schedule` 工具。你可以说人话,例如让每个工作日 8:00 汇总仓库动态,它会去拼 cron 并登记。 ### 调 API @@ -64,9 +64,9 @@ ```json { "name": "Daily Digest", - "description": "Summarize unread emails every morning", + "description": "Summarize repository activity every morning", "pattern": "0 8 * * *", - "command": "Summarize my unread emails and send the result to Telegram.", + "command": "Summarize yesterday's repository activity and send the result to Telegram.", "enabled": true, "max_calls": null } diff --git a/docs/zh/guides/sessions.md b/docs/zh/guides/sessions.md index ab45237..36659b5 100644 --- a/docs/zh/guides/sessions.md +++ b/docs/zh/guides/sessions.md @@ -1,14 +1,14 @@ # 会话 -**会话**是用户与机器人之间的一路独立对话。每路有自己的上下文与历史,换话题或任务时常开新会话。 +**会话**是用户与 Bot 之间的一路独立对话。每路有自己的上下文与历史,换话题或任务时常开新会话。 --- ## 为什么要隔离 -你和机器人聊的内容都落在当前会话里;**新开会话**会换一块上下文,老记录还在,只是不再参与当前这一路的推理。 +你和 Bot 聊的内容都落在当前会话里;**新开会话**会换一块上下文,老记录还在,只是不再参与当前这一路的推理。 -会话按**机器人**分;每个机器人各自一摞会话,互不掺。 +会话按**Bot**分;每个 Bot 各自一摞会话,互不掺。 --- @@ -19,7 +19,7 @@ Memoh 用五类会话区分不同活动: | 类型 | 说明 | |------|------| | **Chat** | 最常见的用户发起对话,默认就它。 | -| **Discuss** | 偏「旁观」:机器人默认可以不吱声,把模型输出当内心戏,只有用发送类动作时才算对渠道真说话。 | +| **Discuss** | 偏「旁观」:Bot 默认可以不吱声,把模型输出当内心戏,只有用发送类动作时才算对渠道真说话。 | | **Schedule** | cron 触发。 | | **Subagent** | 子智能体被委派时。 | | **ACP Agent** | 从聊天 workspace 使用已启用 ACP 兼容编码智能体时生成。 | @@ -36,12 +36,12 @@ Memoh 用五类会话区分不同活动: **Discuss**: -- 常出现在群里:机器人**看着**大家聊 +- 常出现在群里:Bot**看着**大家聊 - 直接文本多算内部独白 - 真发到渠道要显式 `send` 之类动作 - **保持沉默是正常选项** -有 Discuss,机器人才更像「要不要接话我自己决定」的群成员,而不是每句都回的客服。 +有 Discuss,Bot 才更像「要不要接话我自己决定」的群成员,而不是每句都回的客服。 --- @@ -53,15 +53,25 @@ Memoh 用五类会话区分不同活动: - `/new chat`:强制普通 chat - `/new discuss`:强制 discuss -ACP Agent 会话不通过 `/new` 创建。要先在机器人详情的 **Agents** tab 启用 ACP 兼容智能体,再从聊天 workspace 启动。 +ACP Agent 会话不通过 `/new` 创建。要先在 Bot 详情的 **Agents** tab 启用 ACP 兼容智能体,再从聊天 workspace 启动。 **网页本地渠道** 默认 `chat`;**私聊** 多 `chat`;**外接群聊** 多 `discuss`。 -**内置网页本地** 不支持 `/new discuss`,要 discuss 请用 Telegram、Discord、Misskey 等真实渠道。 +**内置网页本地** 不支持 `/new discuss`,要 discuss 请用 Telegram、Discord 等真实渠道。 -在渠道里发这些命令会:建新会话、后续消息都进这路、旧会话保留但不再当「当前」。 +### 在外部渠道里 -**网页** 里也可用侧栏 **New Session**、切换、搜索、按类型筛(`chat`、`discuss`、`schedule`、`subagent`、`acp_agent`)、重命名、删除等。 +在 Telegram、Discord、飞书等外部渠道里,把 `/new`、`/new chat` 或 `/new discuss` 当消息发给 Bot,它会:建新会话、后续消息都进这路、旧会话保留但不再当「当前」。 + +这些时候特别有用: + +- 想换话题,不想让 Bot 再引用旧上下文。 +- 这一路聊得太长,想干净重开。 +- 在不同任务之间切换。 + +### 在客户端里 + +**客户端** 里也可用侧栏 **New Session**、切换、搜索、按类型筛(`chat`、`discuss`、`schedule`、`subagent`、`acp_agent`)、重命名、删除等。 --- @@ -69,7 +79,7 @@ ACP Agent 会话不通过 `/new` 创建。要先在机器人详情的 **Agents** ### 列表 -当前机器人的会话在侧栏;每项可见标题、类型图标、最近活跃时间。日常你关心的 **Chat / Discuss** 会混在同一列表,都是「人能看到的那类线程」。 +当前 Bot 的会话在侧栏;每项可见标题、类型图标、最近活跃时间。日常你关心的 **Chat / Discuss** 会混在同一列表,都是「人能看到的那类线程」。 ### 重命名 @@ -91,6 +101,6 @@ ACP Agent 会话不通过 `/new` 创建。要先在机器人详情的 **Agents** - **Discuss** 给「群里多看少说」用。 - **Schedule** 到点也会生成会话,可看 cron 命令跑的结果。 -- **Subagent** 各自会话,跟委派任务对齐。子智能体几乎能用主机器人的全套工具——workspace、浏览器、记忆、MCP 都在——但不能直接给用户发消息、不能向用户提问、不能再套子智能体。委派时机器人可以给每个子智能体单独挑聊天模型,也可以选择把当前会话上下文 fork 给它。会话信息面板能看到当前活跃的子智能体。 +- **Subagent** 各自会话,跟委派任务对齐。子智能体几乎能用主 Bot 的全套工具——workspace、浏览器、记忆、MCP 都在——但不能直接给用户发消息、不能向用户提问、不能再套子智能体。委派时 Bot 可以给每个子智能体单独挑聊天模型,也可以选择把当前会话上下文 fork 给它。会话信息面板能看到当前活跃的子智能体。 - **ACP Agent** 记录从聊天 workspace 启动的编码智能体工作。 -- **长期记忆**在机器人整级共享,从哪一路抽出来,别路也能检索到(在你配置允许的前提下)。 +- **长期记忆**在 Bot 整级共享,从哪一路抽出来,别路也能检索到(在你配置允许的前提下)。 diff --git a/docs/zh/guides/skills.md b/docs/zh/guides/skills.md index d55dc1f..f6fbd8a 100644 --- a/docs/zh/guides/skills.md +++ b/docs/zh/guides/skills.md @@ -1,6 +1,10 @@ # 技能 -**技能**是可复用的提示模块,用来改机器人的语气、行为方式、工具使用习惯。在机器人的 **Skills** tab 里管;可手写,也可从 [应用市场](./supermarket.md) 装。 +**技能**是可复用的提示模块,用来改 Bot 的语气、行为方式、工具使用习惯。在 Bot 的 **Skills** tab 里管;可手写,也可从 [应用市场](./supermarket.md) 装。 + +::: tip 限制 +一次会话最多同时请求 5 个技能;单个技能注入上限 64 KiB,合计上限 256 KiB。这些上限不可配置。 +::: --- @@ -95,7 +99,7 @@ Memoh 按顺序扫这些根: ## 运行时 -只有 **effective** 会进当前机器人提示。 +只有 **effective** 会进当前 Bot 提示。 - `shadowed` 能看、不进提示 - `disabled` 当不存在 diff --git a/docs/zh/guides/slash-commands.md b/docs/zh/guides/slash-commands.md index ab14a9d..a1e54c9 100644 --- a/docs/zh/guides/slash-commands.md +++ b/docs/zh/guides/slash-commands.md @@ -36,22 +36,22 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 ## 技能激活与快捷操作 -固定命令之外,斜杠还能按需激活机器人的[技能](./skills.md): +固定命令之外,斜杠还能按需激活 Bot 的[技能](./skills.md): ```text /<技能名> [可选的提示词] ``` -- **网页 composer** 里输入 `/` 会弹面板:**快捷操作**(`/help`、`/skill list`、`/new`、`/compact`、`/model`)加上机器人的技能列表。选中的技能变成可移除的 chip,也可以直接打上面那种形式。 +- **网页 composer** 里输入 `/` 会弹面板:**快捷操作**(`/help`、`/skill list`、`/new`、`/compact`、`/model`)加上 Bot 的技能列表。选中的技能变成可移除的 chip,也可以直接打上面那种形式。 - **IM 渠道**里同样支持 `/<技能名>`;`/skill list` 会渲染成可点的按钮。 - 激活的技能内容**只注入当前这一轮**——不进历史、不进会话标题、不进记忆。 -技能名每次发送都在**服务端**按机器人当前生效的技能目录解析。长得像命令/技能但都对不上的斜杠输入会明确报错,不会漏给模型;只是开头带 `/` 的普通文本(路径、URL)照常当聊天。 +技能名每次发送都在**服务端**按 Bot 当前生效的技能目录解析。长得像命令/技能但都对不上的斜杠输入会明确报错,不会漏给模型;只是开头带 `/` 的普通文本(路径、URL)照常当聊天。 两个限制: - 技能激活消息不能带附件(固定命令带附件照常执行)。 -- 群聊里没有指向机器人的斜杠消息会被静默忽略。 +- 群聊里没有指向 Bot 的斜杠消息会被静默忽略。 ## 内建帮助 @@ -73,7 +73,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 ## 解析规则 -- 群里可 **@机器人 前缀**,如 `@BotName /help`。 +- 群里可 **@Bot 前缀**,如 `@BotName /help`。 - **Telegram** 可带 bot 后缀,如 `/help@MemohBot`。 - 引号包一整个参数,例如: @@ -87,7 +87,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 ## 权限 -只读类:能跟机器人聊的人一般就能用。 +只读类:能跟 Bot 聊的人一般就能用。 `set`、`create`、`update`、`delete`、`enable`、`disable` 等写操作多要 **owner**。 `/help` 里 owner 专属会标 `[owner]`。 @@ -110,7 +110,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 |----|------|----------| | `/schedule` | 定时任务 | 无 | | `/mcp` | 看 MCP 连接 | 无 | -| `/settings` | 机器人设置 | `get` | +| `/settings` | Bot 设置 | `get` | | `/model` | 聊天模型 | 无 | | `/memory` | 记忆提供方 | 无 | | `/search` | 搜索提供方 | 无 | @@ -124,7 +124,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 | `/context` | 当前会话的上下文窗口占用 | `show` | | `/reasoning`(别名 `/reason`、`/effort`、`/think`) | 查看或设置本会话的推理档位 | `show` | | `/language` | 查看或设置命令界面语言(`auto`、`en`、`zh`、`ja`) | `show` | -| `/link ` | 用 Web UI 里生成的码,把当前渠道账号绑定到 Memoh 用户 | `consume` | +| `/link ` | 用客户端里生成的码,把当前渠道账号绑定到 Memoh 用户 | `consume` | --- @@ -159,7 +159,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 | 动作 | 用法 | |------|------| | `show` | `/status` 或 `/status show`,当前路由 | -| `latest` | 若当前路由没有活跃会话,要看**该机器人最新**会话时用 | +| `latest` | 若当前路由没有活跃会话,要看**该 Bot 最新**会话时用 | ### `/access` @@ -181,7 +181,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 ### `/email` -当前机器人邮服、绑定、发件箱。 +当前 Bot 邮服、绑定、发件箱。 | 动作 | 用法 | |------|------| @@ -283,7 +283,7 @@ Memoh 支持 **斜杠命令**,在进 LLM 之前截获。用来快速看状态 |------|------| | `list` | `/skill` 或 `/skill list` | -要按轮激活技能,用 `/<技能名> [提示词]`,见上面「技能激活与快捷操作」。 +要按轮激活技能,用 `/ [提示词]`,见上面的 [技能激活与快捷操作](#技能激活与快捷操作)。 ### `/fs` diff --git a/docs/zh/guides/supermarket.md b/docs/zh/guides/supermarket.md index e689702..6409793 100644 --- a/docs/zh/guides/supermarket.md +++ b/docs/zh/guides/supermarket.md @@ -2,7 +2,7 @@ 应用市场是 Memoh 内置的**连接器**和 **Skills** 目录。连接器把第三方服务(GitHub、Notion 这类)绑到 Bot 上;Skills 是 Agent 可按需加载的可复用流程。 -Web UI 会在 Settings 下显示应用市场,提供两个 tab: +客户端在 **设置** 下提供应用市场,分两个标签页: - **Connectors** - **Skills** @@ -19,7 +19,7 @@ Web UI 会在 Settings 下显示应用市场,提供两个 tab: ## 安装 Skill -1. 在 Web UI 中打开 **应用市场**。 +1. 在客户端打开 **应用市场**。 2. 切到 **Skills** tab。 3. 选择一个 Skill 并点击 **Install**,或进入 Skill 详情页点击 **Install to Bot**。 4. 选择目标 Bot。 diff --git a/docs/zh/guides/use-cases.md b/docs/zh/guides/use-cases.md index 6cd2526..7f3e114 100644 --- a/docs/zh/guides/use-cases.md +++ b/docs/zh/guides/use-cases.md @@ -2,4 +2,100 @@ 组合多种 Memoh 功能解决实际问题的即用型示例。 -> 敬请期待。 \ No newline at end of file +好的 Bot 分工,是**负责一个可重复的结果**,而不是"大概管一类问题"。下面每个场景都给出:Bot 负责什么、用到哪些功能、以及一句可以直接发给它的起手指令。所有示例都从只读工作开始——先看它做得对不对,再逐步放权。 + +## 晨间简报 + +**它负责:** 每个工作日开始前,把你关心的信息汇成一条消息。 + +**用到:** [定时任务](./schedule.md) · [搜索提供方](../integrations/providers/web-search.md) · [平台](../integrations/channels/index.md) + +**从这句开始:** + +> 每个工作日早上 8 点,汇总我关注的这几个仓库过去 24 小时的 release 和重要 issue,加上今天的天气,整理成一条简报发给我。每条信息注明来源,不确定的内容直接说不确定,不要编造。 + +Bot 自带 `schedule` 工具,你用自然语言说清楚时间,它会自己登记 cron。先用 **Max Calls** 限制试跑几次,确认格式满意再放开。 + +## 发版盯守 + +**它负责:** 盯住一个你在等的外部变化,发生时第一时间主动找你。 + +**用到:** [定时任务](./schedule.md) · [工作区](./container.md) · [平台](../integrations/channels/index.md) + +**从这句开始:** + +> 盯着这个项目的发布页,每 30 分钟检查一次。出了新版本就把变更内容整理成 Markdown 存进工作区,并在 Telegram 上提醒我一句。只做整理,不要执行任何升级或安装。 + +"你不在的时候它也在"是定时任务加主动消息的组合:到点检查、有变化才说话。同类玩法还有盯价格、盯库存、盯文档更新。 + +## 群聊值班助理 + +**它负责:** 在团队群里当值班秘书:被 @ 时答疑,每天固定时间发纪要。 + +**用到:** [平台](../integrations/channels/index.md) · [会话](./sessions.md) · [访问控制](./access.md) · [定时任务](./schedule.md) + +**从这句开始:** + +> 接入这个群之后:有人 @ 你就总结当天讨论要点和待办;每天 18 点主动发一份当日纪要,按"结论 / 待办 / 未决"三段整理。纪要只发在群里,不要私聊任何人。 + +用 [访问控制](./access.md) 的"仅群聊"预设限定它的活动范围。讨论(discuss)会话里 Bot 会自己判断该不该说话,不会刷屏。 + +## 数据表格的日常维护 + +**它负责:** 一份活的数据文件:建表、定期更新、有异动先报告。 + +**用到:** [工作区](./container.md) · [文件](./files.md) · [定时任务](./schedule.md) + +**从这句开始:** + +> 在工作区建一个竞品价格表(CSV)。每天早上检查一次各家官网价格,把变化追加写进表格;有降价先发消息告诉我。只维护这份文件,不要对外发送任何内容给别人。 + +工作区是真实的文件系统加终端(预装 Python、Node.js、uv),清洗 CSV、跑脚本、生成报表都在里面完成,产出物随时可以在 **文件** 里查看。 + +## 带登录墙的网页任务 + +**它负责:** 需要"看着屏幕"的网页操作:后台核对、表单流程、OAuth 授权。 + +**用到:** [Browser / Computer Use](./browser-computer-use.md) · [工作区](./container.md)(可视化桌面) + +**从这句开始:** + +> 打开我们的后台控制台,按我给你的清单逐项核对配置,每一项截图存进工作区。遇到登录、验证码或任何拿不准的画面就停下来等我接管桌面,我处理完你再继续。全程只读,不要修改任何设置。 + +可视化桌面是双向的:你能在桌面面板里看着它操作,也能随时接管键鼠输密码,再把控制权交回去。浏览器会话保留在工作区里,下次任务免登录。 + +## 云端写码与预览 + +**它负责:** 在自己的工作区里写一个小项目,跑起来给你看。 + +**用到:** [Agents / ACP](./acp.md) · [工作区](./container.md) · [技能](./skills.md) + +**从这句开始:** + +> 在工作区里做一个阅读清单网页:能添加、标记读完、按主题筛选。做好后把开发服务跑起来,给我预览方式。所有改动用 git 提交在本地,不要推送到任何远端。 + +习惯用 Claude Code 或 Codex?在 Bot 的 **Agent** 标签页接入你自己的订阅,它会在同一个工作区、同一批文件上继续干活。 + +## 记得住事的个人助理 + +**它负责:** 跨会话、跨平台地记住你的偏好和项目进展,接着上次继续。 + +**用到:** [长期记忆](./memory.md) · [平台](../integrations/channels/index.md) · [定时任务](./schedule.md) + +**从这句开始:** + +> 记住这些偏好:上午留给深度工作,会议尽量约下午;周报每周五下班前要成稿。以后帮我安排提醒和整理摘要时,先查记忆再动手;偏好拿不准就问我,不要猜。 + +配好 [记忆提供方](../integrations/providers/memory/builtin.md) 后,"上次那个 PR 后来怎么样了"这类问题它能直接接住。记忆攒多了用 **Compact** 做一次合并去重。 + +--- + +## 从示例到日常使用 + +1. **从只读开始。** 先让它"读并整理",人工检查几次产出,再谈写入和执行。 +2. **把约束写进指令。** 结果、来源、约束、形式、确认点——五件事说清楚(见 [快速开始](./quick-start.md))。 +3. **重复的流程存成 [技能](./skills.md)。** 一句话唤起整套动作,不用每次重打。 +4. **稳定后再上 [定时任务](./schedule.md)。** 先用 Max Calls 试跑,确认无误再放开。 +5. **写入和执行留在审批后面。** 即使流程已经很熟,对外动作也值得多看一眼。 +6. **用 [访问控制](./access.md) 限定谁能使唤它。** 尤其是接入群聊的 Bot。 +7. **让 [记忆](./memory.md) 沉淀偏好。** 纠正过的事不该再错第二次。 diff --git a/docs/zh/guides/working-with-bots.md b/docs/zh/guides/working-with-bots.md new file mode 100644 index 0000000..810d178 --- /dev/null +++ b/docs/zh/guides/working-with-bots.md @@ -0,0 +1,190 @@ +# 和 Bot 协作 + +[快速开始](./quick-start.md) 解决的是把 Bot 跑起来;这一页讲的是怎么用好它——什么任务适合交出去、请求怎么说、规则放在哪、什么时候该拆成两个 Bot——后半部分是配置参考:创建 Bot 和详情页每个 tab 的字段。 + +## 什么样的任务适合交给 Bot + +同时满足三个条件的任务,交给 Bot 最合适: + +- **结果清楚。** 你说得出做完之后应该存在什么——一份文件、一条消息、一张表。 +- **来源够得着。** 涉及的文件、网站或对话是它真能访问到的:已上传进工作区、已接入的渠道或服务、或者是公开内容。 +- **产出好检查。** 你一眼能看出结果对不对,复查的成本才低。 + +三条都满足,也还是从只读开始:先让它读和整理,检查几次产出,再逐步放权。[使用场景](./use-cases.md) 里的每个示例都是这么起步的。 + +## 把请求说清楚 + +一个好的请求会回答五个问题——结果、来源、约束、形式、确认点。那张表在 [快速开始](./quick-start.md#第-4-步-交给它第一个任务);这里看两组实际对比。 + +::: warning 含糊 +> 帮我盯着科技新闻,有意思的发给我。 +::: + +没有来源(哪些网站、哪些仓库?),没有送达时间,「有意思」还是一个替你做的主观判断。每期简报都在碰运气。 + +**改成:** + +::: tip 具体 +> 每个工作日早上 8 点,汇总我关注的这几个仓库过去 24 小时的 release 和重要 issue,整理成一条简报发给我。每条信息注明来源,不确定的内容直接说不确定,不要编造。 +::: + +::: warning 含糊 +> 把这个表格清理一下。 +::: + +「清理」没有定义:哪些行算脏数据、原文件能不能动、最后要交回什么?Bot 动手之前得连猜三次。 + +**改成:** + +::: tip 具体 +> 把我刚上传的 CSV 里 email 列为空的行全部删掉。给我清洗后的文件,并告诉我删了多少行。不要修改原文件。 +::: + +两处改写的共同点:点名来源、限定动作、让结果一眼可验。 + +## 长期规则放哪 + +两类指令,两个去处: + +- **长期规则** 写进 Bot 详情页的指令里——角色、格式标准、常设约束。之后每一次会话都生效。 +- **一次性要求** 写在消息里——今天这份文件、这周的例外。 + +一条纠正值得长期生效时,就把它升级:改写成持久规则,挪进指令,做法见 [快速开始](./quick-start.md#第-7-步-复盘-然后固化下来) 第 7 步。整套流程反复出现时,存成 [技能](./skills.md),一句话就能唤起;希望 Bot 自己记得的偏好,交给 [长期记忆](./memory.md)。 + +## 什么时候拆成多个 Bot + +一个 Bot 负责一件事。职责单一的 Bot 积累的上下文会持续帮到它;什么都干的 Bot 会稀释自己的指令和记忆。[快速开始](./quick-start.md) 和 [概览](./overview.md) 都讲过这一点,这里只补一个实用判断:新需求的受众不同、来源不同,或者需要的权限不同,就该新建第二个 Bot。 + +每个 Bot 都有独立的工作区、记忆、渠道和权限边界,互相看不见对方。拆开也让权限更诚实——只读 release 动态的那个 Bot,永远不需要执行命令的权利。 + +## 审批习惯 + +任务需要哪一级就给哪一级——工作区权限从聊天、读文件、写文件、执行命令到管理逐级授予,见 [访问控制](./access.md)。 + +实际操作: + +1. 新流程从只读开始,写入和执行类工具调用留在审批后面。 +2. 检查过前几次运行,再考虑放宽。 +3. 会离开工作区的动作——给别人发消息、任何对外操作——即使流程已经很熟,也继续留在审批后面。 + +这和 [使用场景](./use-cases.md#从示例到日常使用) 的检查清单是同一条路:多批几次请求,远比撤销一次写错便宜。 + +--- + +## 创建 + +1. 侧栏进入 **Bots**。 +2. 点 **Create Bot**。 +3. 基本信息: + - **Display Name**:对外的名字 + - **Avatar**:头像 URL + - **Timezone**:可空;不填则继承用户或系统时区 + - **ACL Preset**:如 `allow_all`(默认放行)、`private_only`(仅私聊)等快捷策略 +4. 创建。 + +--- + +## 详情页 + +点卡片进 **详情**,各 tab 管不同事: + +| Tab | 内容 | +|-----|------| +| **Overview** | workspace runtime、库、渠道、记忆等健康检查 | +| **General** | 主模型/标题/生图、记忆/搜索/TTS 绑定、时区、语言、推理、危险区 | +| **Desktop** | Workspace display runtime、有头浏览器、实时 display session | +| **Workspace** | 容器型 workspace 起停、快照、导入导出 | +| **Network** | Workspace 网络与 overlay provider 状态/动作 | +| **Memory** | 浏览、搜、建、改、压记忆 | +| **Platforms** | 各消息渠道(Telegram、Discord、飞书等) | +| **Access** | ACL 与默认通过/拒绝 | +| **Tool Approval** | 需要人类确认的工具审批设置 | +| **Agents** | 可为聊天 workspace 启用的 ACP 兼容编码智能体,如 Codex、Claude Code | +| **Connectors** | 经 Connect-It 连接的第三方服务(OAuth 或 API Key):状态、启停、重新授权、断开 | +| **Hooks** | 保存在 `/data/.memoh/hooks.json` 的 Bot 自动化规则 | +| **MCP** | 连接(Stdio/Remote/OAuth) | +| **Compaction** | 会话压缩设置与记录 | +| **Schedule** | cron 与日志 | +| **Skills** | 技能 Markdown | + +Files、Terminal 以及桌面 / 浏览器面板在聊天的 workspace 区域里同样可用——想不离开对话就查看文件、跑 shell、盯着 Bot 的浏览器和桌面时,用聊天里的 workspace 侧栏。 + +--- + +## 核心先配什么 + +1. 打开 Bot **General**,先管模型与各类绑定。 +2. **Schedule** 管周期性自主任务。 +3. **Compaction** 管会话写不长时的压缩。 +4. **Access** 在 ACL 预设之后细调。 + +若这些资源还没有,先建好: + +- [模型服务商与模型](../integrations/providers/llm.md) +- [内置记忆提供方](../integrations/providers/memory/builtin.md)(如用) +- [搜索提供方](../integrations/providers/web-search.md) +- [TTS:Edge](../integrations/providers/tts/edge.md) +- [Agents / ACP](./acp.md) + +--- + +## General 字段 + +| 字段 | 说明 | +|------|------| +| **Chat Model** | 主对话模型 | +| **Title Model** | 可选,生成会话标题 | +| **Image Generation Model** | 可选,需带 `image-output` 的聊天模型 | +| **Memory Provider** | 长期记忆后端;内置类型还可自带记忆/向量模型 | +| **Search Provider** | 联网搜索用哪家 | +| **TTS Model** | 来自 TTS 提供方流程,不在普通 chat 模型服务商里选 | +| **Timezone** | 不填则用户时区再落到系统 | +| **Language** | Bot 主用语 | +| **Reasoning Effort** | 当前 chat 模型有 `reasoning` 时可用;可选值随模型而定(如 `low` / `medium` / `high`) | + +注意: + +- **生图模型** 故意与主聊天模型分开,好单独换「更擅长出图」的。 +- **TTS** 用 [TTS 提供方](../integrations/providers/tts/edge.md) 所配置语音提供方的 `speech` 模型。 +- 所选聊天模型的 `context_window` 会影响会话状态展示和 [会话压缩](./compaction.md)。 + +--- + +## Compaction 相关(此处指「会话」) + +这里说的是 **当前会话** 的上下文压短,不是改记忆条目的那种。 + +| 字段 | 说明 | +|------|------| +| **Compaction Enabled** | 是否自动在会话里压摘要 | +| **Compaction Threshold** | 触发的估算 token 阈值 | +| **Compaction Ratio** | 压多狠 | +| **Compaction Model** | 可选,专门做摘要的模型 | + +细节见 [会话上下文压缩](./compaction.md)。 + +--- + +## 访问与 ACL + +创建时先给一个 **ACL 预设**,之后在 **Access** 里微调。**预设** 给一版默认策略,**Default Effect** 管「没命中规则时」放行还是挡。 + +[会话](./sessions.md) 与 Discuss 的默认行为在那一页。若你用 API/自动化,配置里还可能有 `discuss_probe_model_id` 等进阶项,日常创建不必先动。 + +--- + +## Workspace 文件与终端 + +Workspace 文件和终端在聊天 workspace UI 里使用;前提是该 Bot 有可用的 workspace runtime。这里可以: + +- 浏览、编辑 workspace 文件 +- 打开 workspace 内的终端会话 +- 在开启 display 后使用浏览器/桌面相关工具 + +文件流程见 [文件](./files.md),有头浏览器和桌面操作见 [Browser / Computer Use](./browser-computer-use.md)。 + +--- + +## 删除 + +**General** 最下 **Danger Zone** -> **Delete Bot**,会删掉该 Bot 相关数据(含 workspace 文件与记忆等),**不可恢复**。 diff --git a/docs/zh/index.md b/docs/zh/index.md index 366f091..c2715b7 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -1,10 +1,10 @@ --- title: Memoh 文档 -description: 学习 Memoh、连接外部系统,或部署你自己的实例。 +description: 学习 Memoh、连接外部系统,把 Bot 带进你常用的聊天平台。 --- # Memoh 文档 -学习 Memoh、连接外部系统,或部署你自己的实例。 +学习 Memoh、连接外部系统,把 Bot 带进你常用的聊天平台。 diff --git a/docs/zh/integrations/channels/dingtalk.md b/docs/zh/integrations/channels/dingtalk.md index a1a4adc..32d085c 100644 --- a/docs/zh/integrations/channels/dingtalk.md +++ b/docs/zh/integrations/channels/dingtalk.md @@ -1,30 +1,53 @@ # 钉钉 -企业内私聊、群聊;入站多走钉钉 **Stream**,出站走官方 API,媒体按平台能力来。 +把 Memoh Bot 接入钉钉,支持企业内私聊与群聊:入站消息经由钉钉 Stream 模式送达,回复与媒体走钉钉官方 API。 -## 1. 建钉钉应用 +::: warning 使用限制 +- 回复按完整消息送达,不做逐 token 流式输出。 +::: -1. 进组织对应的钉钉开放平台/开发者后台。 -2. 建或选用一个应用,打开 **机器人/消息** 等能力(以钉钉当前流程为准)。 -3. 拿到 **App Key**、**App Secret**,并按需在组织内 **发布/授权** 给使用的人。 +## 前提条件 -## 2. 在 Memoh 里填 +- 能进入组织对应的钉钉开放平台,并有创建应用的权限。 +- 不需要公网回调地址:Memoh 自动维护与钉钉的 Stream 长连接来接收消息。 -1. 机器人 **Platforms** → **Add Channel** → **DingTalk**。 -2. 填 **App Key**、**App Secret**。 -3. **Save and Enable**。 +## 步骤 -Memoh 会维护与钉钉的 **stream 长连接**。常规部署**不用**你再去配一层 webhook 回调地址(与飞书、微信公众号那种 webhook 模式不同)。 +### 1. 在钉钉开放平台创建应用 -## 3. 验证 +在组织对应的钉钉开放平台: -私聊给机器人发一句,或在支持的群里 @ 它,看能否收、能否回。 +1. 创建或选用一个应用作为 Bot。 +2. 为该应用开启 Bot/消息能力。 +3. 复制 **App Key** 和 **App Secret**。 +4. 为应用授予消息权限,并在组织内发布,让使用者能够访问。 -## 支持的能力 +### 2. 在 Memoh 里添加渠道 -- 私聊、群聊 -- 文本、类 Markdown -- 回复 -- 附件/媒体 +在 Memoh: -**说明**:在 Memoh 里,钉钉侧出站回复多为**非流式**(整段出)。 +1. 打开 Bot 的 **平台** 标签页。 +2. 点 **Add Channel**,选择 **DingTalk**。 +3. 填入 **App Key** 和 **App Secret**。 +4. 点 **Save and Enable**。 + +Memoh 会自动维护钉钉 Stream 长连接,不需要粘贴 webhook 回调地址。 + +## 凭据 + +| 字段 | 必填 | 说明 | +|------|------|------| +| **App Key** | 是 | 钉钉应用的 Key,在钉钉开放平台的应用凭据处复制。 | +| **App Secret** | 是 | 钉钉应用的 Secret,与 App Key 在同一处复制。 | + +## 验证 + +私聊给 Bot 发送 `/help`,或在群聊中 @Bot 并发送 `/help`。Bot 回复命令列表,说明渠道已接通。 + +## 群聊 + +Bot 支持钉钉群聊:在支持的群里 @Bot 即可触发回复。 + +## 停用与更换凭据 + +随时可在 Bot 的 **平台** 标签页停用或移除该渠道。更换凭据时,在同一面板更新 **App Key** / **App Secret** 并保存即可。 diff --git a/docs/zh/integrations/channels/discord.md b/docs/zh/integrations/channels/discord.md index fb77347..e83df07 100644 --- a/docs/zh/integrations/channels/discord.md +++ b/docs/zh/integrations/channels/discord.md @@ -1,40 +1,59 @@ # Discord -接上 Discord 后,机器人可进服务器、在频道和私聊里说话。 +把 Memoh Bot 接到 Discord,进服务器,在频道和私聊里与社群成员对话。 -## 1. 建 Discord 应用 +## 前提条件 -1. 打开 [Discord Developer Portal](https://discord.com/developers/applications)。 -2. **New Application**,起名。 -3. 左侧 **Bot** → **Reset Token** 得到 **Bot Token**,保管好。 +- 一个能登录 [Discord Developer Portal](https://discord.com/developers/applications) 的 Discord 账号。 +- 一个可以授权 Bot 加入的服务器。 +- 一个 Memoh Bot;渠道在它的 **平台** 标签页里配置。 + +## 步骤 -## 2. 开特权意图 +### 1. 在 Discord Developer Portal 创建应用并拿 Bot Token -在 **Privileged Gateway Intents** 里打开: +1. 打开 [Discord Developer Portal](https://discord.com/developers/applications)。 +2. 点 **New Application**,起名。 +3. 左侧进入 **Bot**。 +4. 点 **Reset Token** 生成 **Bot Token**,复制并妥善保管。 -- `Message Content Intent` -- `Server Members Intent` -- `Presence Intent` +### 2. 在 Discord Developer Portal 开启特权意图 -保存。 +1. 在 **Bot** 页向下找到 **Privileged Gateway Intents**。 +2. 开启 `Message Content Intent`、`Server Members Intent` 和 `Presence Intent`。 +3. 保存。 -## 3. 把机器人拉进服务器 +### 3. 在 Discord Developer Portal 生成邀请链接,把 Bot 拉进服务器 -1. **OAuth2** → **URL Generator**。 +1. 进入 **OAuth2** > **URL Generator**。 2. 勾选 scope:`bot`、`applications.commands`。 -3. 权限里至少:发消息、读历史、嵌链接、发附件等按需要勾。 -4. 用生成 URL 在浏览器里打开,选服务器并授权。 +3. 勾选权限:`Send Messages`、`Read Message History`、`Embed Links`、`Attach Files`。 +4. 复制生成的 URL,在浏览器里打开。 +5. 选择要加入的服务器并授权。 + +> 官方说明:[Discord Developer Portal - Bots](https://discord.com/developers/docs/intro) + +### 4. 在 Memoh 添加 Discord 渠道 + +1. 打开 Bot 详情页,进入 **平台** 标签页。 +2. 点 **Add Channel**,选 **Discord**。 +3. 贴上 **Bot Token**。 +4. 点 **Save and Enable**。 + +## 凭据 + +| 字段 | 说明 | +|------|------| +| **Bot Token** | 在应用的 **Bot** 页用 **Reset Token** 生成,妥善保管。 | + +## 验证 -> 文档入口:[Discord Developer Portal - Bots](https://discord.com/developers/docs/intro) +私聊 Bot 发送 `/help`,或在 Bot 已加入的服务器频道里 @它。Bot 回复命令列表即说明渠道已生效。 -## 4. 在 Memoh 里填 +## 群聊 -1. 机器人 **Platforms** → **Add Channel** → **Discord**。 -2. 贴 **Bot Token**。 -3. **Save and Enable**。 +Discord 服务器即群聊场景。Bot 授权进入服务器后,在频道里 @它即可对话。 -## 支持的能力 +## 停用与更换凭据 -- 读**完整消息正文**。 -- **附件**:图片、文件。 -- 若用 MCP 等可扩展 slash;具体以你 Memoh 版本与配置为准。 +在 Bot 的 **平台** 标签页可以随时停用或移除该渠道。更换 token 时,更新 **Bot Token** 字段并保存即可。 diff --git a/docs/zh/integrations/channels/feishu.md b/docs/zh/integrations/channels/feishu.md index 5c26599..76305d2 100644 --- a/docs/zh/integrations/channels/feishu.md +++ b/docs/zh/integrations/channels/feishu.md @@ -1,37 +1,90 @@ # 飞书(Lark) -通过飞书开放平台接入,让企业机器人在群聊/私聊里与用户交互。 +通过飞书开放平台接入,让企业 Bot 在群聊和私聊里与用户交互。 -## 1. 建飞书应用 +## 前提条件 + +- 一个能登录 [飞书开放平台](https://open.feishu.cn/app)、可创建企业自建应用的账号。 +- 一个 Memoh Bot;渠道在它的 **平台** 标签页里配置。 + +## 步骤 + +### 1. 在飞书开放平台创建自建应用 1. 打开 [飞书开放平台](https://open.feishu.cn/app) 并登录。 -2. **创建企业自建应用**,填名与简介。 -3. 左侧 **应用能力** 或 **凭证与基础信息** 里取 **App ID**、**App Secret**。 +2. 点 **创建企业自建应用**,填名称与简介后创建。 +3. 左侧进入 **凭证与基础信息**。 +4. 复制 **App ID** 和 **App Secret**。 + +### 2. 在飞书开放平台启用 Bot 能力 + +进入 **应用能力** → **Bot**,点启用。 + +### 3. 在飞书开放平台开权限 + +1. 进入 **应用能力** → **权限管理**。 +2. 至少开启: + - `im:message`(收发消息) + - `im:chat`(群信息等) +3. 组织有要求时,点 **申请权限** 提交。 + +### 4. 在 Memoh 添加飞书渠道(默认:长连接) + +1. 打开 Bot 的 **平台** 标签页,添加 **飞书** 渠道。 +2. **入站方式** 保持默认的 `websocket`。 +3. 填 **App ID**、**App Secret**;使用国际版 Lark 时把 **区域** 切到 `lark`。 +4. 点 **Save**。消息经飞书 **WebSocket 长连接** 送达,无需公网回调地址,也不用配置事件订阅。 + +### 5. 可选:改用 Webhook 入站 + +服务端可被公网访问、且更希望走事件回调时,再选这种方式。 + +::: tip +这一步会在 Memoh 和飞书后台之间往返:Memoh 生成回调 URL 后要贴回 **事件订阅** 页,先别关飞书后台。 +::: + +1. 在 Memoh 把 **入站方式** 改为 `webhook`;除 **App ID**、**App Secret** 外,再填入与飞书后台事件订阅一致的 **Encrypt Key** 和 **Verification Token**。 +2. 点 **Save**,页面会生成 **Webhook 回调 URL**,复制它。 +3. 回到飞书后台,进入 **应用配置** → **事件订阅**,把 URL 填到 **请求地址** 并保存。 +4. 添加 **接收消息**(`im.message.receive_v1`)等事件。 + +> 官方说明:[飞书自定义机器人](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot) + +### 6. 在飞书开放平台发布应用 + +1. 进入 **应用发布** → **版本管理与发布**。 +2. 点 **创建版本**,填写信息并提交审批。 +3. 审批通过并发布后,Bot 才能在租户里正常使用。 + +## 凭据 + +| 字段 | 说明 | +|------|------| +| **App ID** | 在飞书开放平台 **凭证与基础信息** 页获取。 | +| **App Secret** | 与 App ID 同页获取。 | +| **区域** | 使用国际版 Lark 时切到 `lark`。 | +| **入站方式** | `websocket`(默认,长连接)或 `webhook`。 | +| **Encrypt Key** | 仅 webhook 模式需要,须与飞书后台事件订阅设置一致。 | +| **Verification Token** | 仅 webhook 模式需要,须与飞书后台事件订阅设置一致。 | -## 2. 开机器人能力 +## 验证 -控制台 **应用能力** → **机器人** → 启用。 +在飞书里私聊 Bot,发送 `/help`。Bot 回复命令列表即说明渠道已生效。 -## 3. 开权限 +## 群聊 -**应用能力** → **权限管理**,至少可开(按组织要求可能需审批): +飞书支持群聊。把 Bot 加进群后,@它即可在群里对话。 -- `im:message`(收发消息) -- `im:chat`(群信息等) +## 停用与更换凭据 -需时点 **申请权限**。 +在 Bot 的 **平台** 标签页可以随时停用或移除该渠道。更换凭据时,更新对应字段(如 **App Secret**)并保存即可。 -## 4. 事件:Webhook 入站 +## 常见问题 {#faq} -1. Memoh 里该机器人 **Platforms** → 加 **飞书**,**入站方式** 选 `webhook`。 -2. 填 **App ID**、**App Secret**。 -3. **Save**,页面上会出现 **Webhook 回调 URL**,复制。 -4. 飞书后台 **应用配置** → **事件订阅**。 -5. 把上面 URL 填到 **请求地址** 等对应栏位并保存。 -6. 订阅如 **接收消息**(`im.message.receive_v1` 等,以当前控制台为准)。 +### 渠道配好了,Bot 却没反应 {#app-not-published} -> 官方: [飞书自定义机器人](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot) +自建应用要先发布:在飞书开放平台 **应用发布** → **版本管理与发布** 里创建版本并提交审批,审批通过并发布后 Bot 才能在租户里正常使用。 -## 5. 发布 +### 权限要走审批 {#permission-approval} -**应用发布** → **版本管理与发布**,建版本、走审批/发布。通过后机器人才能在租户里正常用。 +部分组织对应用权限有审批流程:在 **应用能力** → **权限管理** 里点 **申请权限** 提交即可。 diff --git a/docs/zh/integrations/channels/index.md b/docs/zh/integrations/channels/index.md index 0bfdb08..db5a9c7 100644 --- a/docs/zh/integrations/channels/index.md +++ b/docs/zh/integrations/channels/index.md @@ -1,39 +1,26 @@ # 渠道 -渠道把 Memoh 机器人接到消息平台。你可以在机器人 **Platforms** tab 里配置,让同一个机器人通过 Slack、Telegram、飞书、Discord、微信、邮件、网页端等入口被访问。 +渠道把 Memoh Bot 接到消息平台。你可以在 Bot **平台** 标签页里配置,让同一个 Bot 通过 Slack、Telegram、飞书、Discord、微信等平台被访问,也可以直接在 Memoh 客户端里聊。 ## 支持的渠道 -| 平台 | 指南 | 备注 | -|------|------|------| -| Slack | [Slack](./slack.md) | Workspace 消息、thread | -| Telegram | [Telegram](./telegram.md) | 附件、流式较好 | -| 飞书 | [飞书](./feishu.md) | 可走 webhook 入站 | -| Discord | [Discord](./discord.md) | 社群、服务器 | -| QQ | [QQ](./qq.md) | 偏个人 DM | -| Matrix | [Matrix](./matrix.md) | 自建 homeserver | -| Misskey | [Misskey](./misskey.md) | 回复、反应;无流式 | -| 钉钉 | [钉钉](./dingtalk.md) | 企业私聊/群 | -| 企微 | [企微](./wecom.md) | 企业微信工作区 | -| 微信 | [微信](./weixin.md) | 个人扫码登录 | -| 微信公众号 | [微信公众号](./wechatoa.md) | 公众号 webhook | -| 邮件 | [邮件](../../guides/email.md) | SMTP、Mailgun、Gmail OAuth 等邮件流程 | -| Web | 内置 | Memoh 网页端自带 | +- [Telegram](./telegram.md) +- [Slack](./slack.md) +- [Discord](./discord.md) +- [飞书](./feishu.md) +- [钉钉](./dingtalk.md) +- [企业微信](./wecom.md) +- [微信](./weixin.md) +- [QQ](./qq.md) +- [LINE](./line.md) -## 微信选项 - -Memoh 支持两种微信相关适配: - -- **微信(`weixin`)**:个人号扫码登录。 -- **微信公众号(`wechatoa`)**:公众号 webhook,需要 `App ID`、`App Secret`、`Token`,可选 AES 设置。 - -按实际部署模式选择,不要混用。 +各渠道支持的消息能力(Markdown、附件、流式输出、群聊等)见对应页面的「使用限制」说明。 ## 通用配置流程 -1. 在目标平台注册应用或机器人。 +1. 在目标平台注册应用或 Bot。 2. 获取 API token、App ID、app secret、access token 等凭据。 -3. 在 Memoh 的机器人 **Platforms** tab 里添加渠道。 +3. 在 Memoh 的 Bot **平台** 标签页里添加渠道。 4. 保存并启用渠道。 -不同平台的最后一步可能不同:有的要把 webhook 回调 URL 粘到平台控制台,有的要手机扫码,有的需要由 Memoh 持续维护 stream 或 WebSocket 连接。 +不同平台的最后一步可能不同:有的要把 webhook 回调 URL 粘到平台控制台,有的要手机扫码,有的由 Memoh 持续维护 stream 或 WebSocket 连接。 diff --git a/docs/zh/integrations/channels/line.md b/docs/zh/integrations/channels/line.md index 53b3f8d..0e331b1 100644 --- a/docs/zh/integrations/channels/line.md +++ b/docs/zh/integrations/channels/line.md @@ -1,56 +1,79 @@ # LINE -接上 LINE 后,用户加机器人绑定的 LINE 官方账号为好友,即可 1 对 1 聊天。 +把 Memoh Bot 接入 LINE 官方账号:用户加该账号为好友,即可与 Bot 1 对 1 聊天。 -## 先决条件:公网 HTTPS +::: warning 使用限制 +- 仅支持私聊。群和多人聊天室的消息会被忽略,把 Bot 拉进 LINE 群没有用。 +- 仅输出纯文本,不渲染 Markdown。 +- 出站媒体仅限 PNG/JPEG 图片。图片必须公网 HTTPS 可访问,且符合 LINE 体积限制(原图 10 MB、预览图 1 MB);图片之外的附件发不出去。 +- 入站的语音、视频、贴图、位置不处理。入站图片必须由 LINE 托管(在 App 里直接发照片就是这种)。 +- 无流式输出,回复整条送达;超长回复按 LINE 的 5000 字符上限拆成多条。 +- 回复走 LINE **Push API**,计入 LINE 套餐的推送条数配额。 +::: -LINE 用 **webhook** 推消息进来,出站图片也是 LINE 服务器来你这边抓,所以部署必须有公网 HTTPS 入口,二选一: +## 前提条件 -- 设 `MEMOH_WEBHOOK_PUBLIC_BASE_URL` 为公网 HTTPS origin(不能带路径、端口、内网地址); -- 或在 server deploy 里启用 Cloudflare Quick Tunnel profile,Memoh 会自动拿到公网地址。 +LINE 用 **webhook** 推消息进来,出站图片也由 LINE 服务器来抓取,所以 Memoh 部署必须有公网 HTTPS 入口,二选一: -## 1. 建 Messaging API channel +- 设 `MEMOH_WEBHOOK_PUBLIC_BASE_URL` 为公网 HTTPS origin(不能带路径、端口、内网地址); +- 或在 server deploy 里启用 Cloudflare Quick Tunnel profile,Memoh 会自动拿到公网地址。 + +## 步骤 + +### 1. 在 LINE Developers Console 创建 Messaging API channel + +在 LINE Developers Console: 1. 打开 [LINE Developers Console](https://developers.line.biz/console/)。 -2. 建(或选)一个 provider,在下面创建 **Messaging API** channel,它会关联一个 LINE 官方账号。 -3. **Basic settings** 里复制 **Channel secret**。 -4. **Messaging API** tab 里签发并复制 **Channel access token**(长效)。 +2. 建(或选)一个 provider,在下面创建 **Messaging API** channel,它会关联一个 LINE 官方账号。 +3. 在 **Basic settings** 里复制 **Channel secret**。 +4. 在 **Messaging API** tab 里签发并复制 **Channel access token**(长效)。 -> 官方文档:[Messaging API - Getting Started](https://developers.line.biz/en/docs/messaging-api/getting-started/) +> 官方文档:[Messaging API - Getting Started](https://developers.line.biz/en/docs/messaging-api/getting-started/) -## 2. 在 Memoh 里填 +### 2. 在 Memoh 里添加渠道 -1. 机器人 **Platforms** → **Add Channel** → **LINE**。 -2. 贴 **Channel Secret** 和 **Channel Access Token**。 -3. **Save**(或 **Save and Enable**)。回调 URL 要保存之后才会生成。 +在 Memoh: -## 3. 注册 webhook +1. 打开 Bot 的 **平台** 标签页。 +2. 点 **Add Channel**,选择 **LINE**。 +3. 贴入 **Channel Secret** 和 **Channel Access Token**。 +4. 点 **Save**(或 **Save and Enable**)。回调 URL 要保存之后才会生成。 -保存后面板会显示只读的 **WebHook Callback URL**,格式: +### 3. 注册 webhook + +在 Memoh,保存后面板会显示只读的 **WebHook Callback URL**,格式: ```text https://<公网 base>/channels/line/webhook/ ``` -两种注册方式: +两种注册方式: + +- 点 **Set in LINE**——Memoh 直接通过 Messaging API 把地址写进 LINE channel。有未保存的改动会先报错,保存了再点。 +- 或点 **Copy**,到 LINE Developers Console 的 **Messaging API → Webhook URL** 手动粘贴。 + +最后在 LINE Developers Console 里确认该 channel 的 **Use webhook** 已打开。 + +Memoh 会用 **Channel Secret** 校验入站 webhook 的签名,事件在 24 小时内去重。 + +## 凭据 + +| 字段 | 必填 | 说明 | +|------|------|------| +| **Channel Secret** | 是 | 在 Messaging API channel 的 **Basic settings** 里复制。 | +| **Channel Access Token** | 是 | 在 **Messaging API** tab 里签发的长效 token。 | + +## 验证 -- 点 **Set in LINE**——Memoh 直接通过 Messaging API 把地址写进你的 LINE channel。有未保存的改动会先报错,保存了再点。 -- 或点 **Copy**,去 LINE Developers Console 的 **Messaging API → Webhook URL** 手动粘贴。 +用 LINE 加该官方账号为好友,在 1 对 1 聊天中给 Bot 发送 `/help`。Bot 回复命令列表,说明渠道已接通。 -最后确认 LINE 控制台里 **Use webhook** 是打开的。面板若提示拿不到公网 base URL,先回去解决第一步的公网 HTTPS。 +## 停用与更换凭据 -## 支持的能力 +随时可在 Bot 的 **平台** 标签页停用或移除该渠道。更换凭据时,在同一面板更新 **Channel Secret** / **Channel Access Token** 并保存即可。 -- **1 对 1 私聊**:用户加官方账号好友即可开聊。 -- **入站**:文本、图片、文件(图片需是 LINE 自己托管的,App 里直接发照片就是这种)。 -- **出站**:文本 + PNG/JPEG 图片。 -- webhook 带签名校验(用 Channel Secret 验),事件 24 小时内去重。 +## 常见问题 {#faq} -## 限制 +### 面板提示拿不到公网 base URL {#no-public-base-url} -- **只支持私聊**。群和多人聊天室的消息会被忽略,把机器人拉进 LINE 群没有用。 -- 入站的**语音、视频、贴图、位置**不处理。 -- 出站图片必须公网 HTTPS 可访问,且符合 LINE 体积限制(原图 10 MB、预览图 1 MB);图片之外的附件发不出去。 -- 回复走 LINE **Push API**,计入你 LINE 套餐的推送条数配额。 -- 不支持流式输出,回复整条整条到。 -- 超长回复按 LINE 的 5000 字符上限拆成多条。 +没有公网 HTTPS origin 就生成不了 webhook 回调 URL。先按前提条件把 `MEMOH_WEBHOOK_PUBLIC_BASE_URL` 或 Cloudflare Quick Tunnel 配好。 diff --git a/docs/zh/integrations/channels/matrix.md b/docs/zh/integrations/channels/matrix.md deleted file mode 100644 index 7cc5595..0000000 --- a/docs/zh/integrations/channels/matrix.md +++ /dev/null @@ -1,57 +0,0 @@ -# Matrix - -接到任意 Matrix homeserver,机器人在房间、私聊里收发消息。 - -## 1. 建机器人 Matrix 账号 - -1. 在目标 homeserver 上注册账号(Element 等客户端即可)。 -2. 记下 **User ID**,如 `@mybot:matrix.org`。 -3. 准备该账号的 **Access Token**: - -- 一种做法:用登录 API,例如: - -```bash -curl -X POST "https:///_matrix/client/v3/login" \ - -H "Content-Type: application/json" \ - -d '{ - "type": "m.login.password", - "identifier": { - "type": "m.id.user", - "user": "" - }, - "password": "" - }' -``` - -- 或从客户端里导出/查看 token(以客户端安全提示为准)。 - -> **注意**:谁拿到 token 谁就能以该账号操作,当密码保管。 - -## 2. 在 Memoh 里填 - -1. **Platforms** → **Add Channel** → **Matrix**。 -2. 填表: - -| 字段 | 必填 | 说明 | -|------|------|------| -| **Homeserver URL** | 是 | 如 `https://matrix.org` | -| **Access Token** | 是 | 机器人账号 token | -| **User ID** | 是 | 如 `@mybot:matrix.org` | -| **Sync Timeout** | 否 | 长轮询秒数,默认如 30 | -| **Auto Join Invites** | 否 | 被邀请是否自动进房,默认多开 | - -3. **Save and Enable**。 - -## 3. 拉机器人进房 - -在 Element 等里邀请该 User ID,或私聊。若开了 **Auto Join Invites**,邀请会自动接受。 - -## 支持的能力 - -- 房间、私聊、流式、Markdown、媒体/附件等(以当前 Memoh 版本为准)。 -- 更多路线可见 [相关 issue/路线图](https://github.com/felinics/Memoh/issues/249)。 - -## 参考 - -- [Matrix 规范](https://spec.matrix.org/) -- [Element Web](https://app.element.io/) diff --git a/docs/zh/integrations/channels/misskey.md b/docs/zh/integrations/channels/misskey.md deleted file mode 100644 index 1f8f9a6..0000000 --- a/docs/zh/integrations/channels/misskey.md +++ /dev/null @@ -1,35 +0,0 @@ -# Misskey - -把 Memoh 接到某台 Misskey 实例,以 Misskey 账号收 mention、发回复。适合偏文字、社交向的玩法。 - -## 1. 账号和 Token - -1. 登录目标 Misskey 实例。 -2. 用(或专门建)一个代表机器人的账号。 -3. 给该账号生成 **Access Token**(各实例「设置 → API」等位置名称可能略有不同)。 - -需要交给 Memoh 的主要是: - -- **Instance URL**,如 `https://misskey.io` -- **Access Token** - -Token 要允许:读入站、发回复等(以你实例上的权限勾选项为准)。 - -## 2. 在 Memoh 里填 - -1. 机器人 **Platforms** → **Add Channel** → **Misskey**。 -2. 填 **Instance URL**、**Access Token**。 -3. **Save and Enable**。 - -## 3. 用起来 - -启用后,用户可在该实例上 at/互动。Misskey 在 Memoh 里更偏:回复、文字与类 Markdown、带反应的会话。 - -## 支持的能力 - -- 文本、**Markdown**、**回复**、**反应**。 - -**当前限制**(以版本为准): - -- 无附件/媒体上传类能力 -- 无流式逐字输出 diff --git a/docs/zh/integrations/channels/qq.md b/docs/zh/integrations/channels/qq.md index 032600d..900eec0 100644 --- a/docs/zh/integrations/channels/qq.md +++ b/docs/zh/integrations/channels/qq.md @@ -1,31 +1,61 @@ # QQ -走 QQ 开放平台的官方机器人,可和用户在 QQ 里互动。 +通过 QQ 开放平台的官方 Bot 接入 Memoh,支持私聊、群聊与话题(thread)会话。 -## 1. 建 QQ 机器人 +::: warning 使用限制 +- 每个 QQ 账号最多创建 5 个 Bot。 +- 回复按完整消息块送达,不做逐 token 流式输出。 +::: -1. 打开 [QQ 机器人开放平台](https://q.qq.com/qqbot/openclaw/),用 QQ 登录。 -2. **创建机器人**,一般无需审批;每号最多约 5 个。 -3. 记下 **AppID**、**AppSecret**。 +## 前提条件 -> **注意**:AppSecret 往往只显示一次,存好。再看一次常会被迫重置。 +- 一个 QQ 账号,用于登录 [QQ Bot 开放平台](https://q.qq.com/qqbot/openclaw/)。 -## 2. 在 Memoh 里填 +## 步骤 -1. 机器人 **Platforms** → **Add Channel** → **QQ**。 -2. 填 **AppID**、**AppSecret**。 -3. 可选: - - **Markdown Support**:开 Markdown(默认多开)。 - - **Enable Input Hint**:是否显示「正在输入」类提示(默认多开)。 -4. **Save and Enable**。 +### 1. 在 QQ 开放平台创建 Bot -## 支持的能力 +在 QQ Bot 开放平台: -- 文本、**Markdown**、**附件**。 -- **正在输入**类提示(可关)。 -- 场景:C2C 私聊、群、频道等(以平台与版本为准)。 +1. 打开 [QQ Bot 开放平台](https://q.qq.com/qqbot/openclaw/),用 QQ 账号登录。 +2. 点 **创建机器人**(Create Bot),无需审批。 +3. 复制页面上显示的 **AppID** 和 **AppSecret**。**AppSecret** 只显示一次,务必存好。 -## 参考 +> 官方资料:[QQ Bot 开放平台](https://q.qq.com/) · [QQ Bot 文档](https://bot.q.qq.com/wiki/) -- [QQ 机器人开放平台](https://q.qq.com/) -- [QQ 机器人文档](https://bot.q.qq.com/wiki/) +### 2. 在 Memoh 里添加渠道 + +在 Memoh: + +1. 打开 Bot 的 **平台** 标签页。 +2. 点 **Add Channel**,选择 **QQ**。 +3. 粘贴 **AppID** 和 **AppSecret**。 +4. 按需调整可选设置:**Markdown Support** 与 **Enable Input Hint** 默认均已开启。 +5. 点 **Save and Enable**。 + +## 凭据 + +| 字段 | 必填 | 说明 | +|------|------|------| +| **AppID** | 是 | Bot 的 App ID,创建 Bot 时在 QQ 开放平台页面上显示。 | +| **AppSecret** | 是 | Bot 的 App Secret,只在创建时显示一次。 | +| **Markdown Support** | 否 | 启用 Markdown 格式(默认开启)。 | +| **Enable Input Hint** | 否 | 生成回复时显示「正在输入」提示(默认开启)。 | + +## 验证 + +私聊给 Bot 发送 `/help`,或在群聊中 @Bot 并发送 `/help`。Bot 回复命令列表,说明渠道已接通。 + +## 群聊 + +Bot 支持 QQ 群聊与话题(thread)会话:在群里 @Bot 即可触发回复。 + +## 停用与更换凭据 + +随时可在 Bot 的 **平台** 标签页停用或移除该渠道。更换凭据时,在同一面板更新 **AppID** / **AppSecret** 并保存即可。 + +## 常见问题 {#faq} + +### AppSecret 找不到了 {#appsecret-reset} + +**AppSecret** 只在创建 Bot 时显示一次。在 QQ 开放平台再次查看会强制重置;重置后,在 Memoh 里更新 **AppSecret** 并保存。 diff --git a/docs/zh/integrations/channels/slack.md b/docs/zh/integrations/channels/slack.md index 4d29e3b..0abacc5 100644 --- a/docs/zh/integrations/channels/slack.md +++ b/docs/zh/integrations/channels/slack.md @@ -1,64 +1,116 @@ # Slack -在 Slack 里收 DM、进频道、跟 thread、读附件、发文件、流式回复。Memoh 的 Slack 适配用 **Socket Mode**。 +把 Memoh Bot 接到 Slack:收 DM、进频道、跟 thread、读附件、发文件、流式回复。 -## 1. 建 Slack App +## 前提条件 -1. 打开 [Slack API 控制台](https://api.slack.com/apps),**Create New App**。 -2. 选要装的工作区。 -3. 在 **Basic Information** 等页保留窗口,下面要填。 +- 一个可以安装 app 的 Slack workspace,并能访问 [Slack API 控制台](https://api.slack.com/apps)。 +- 一个 Memoh Bot;渠道在它的 **平台** 标签页里配置。 -## 2. 开 Socket Mode +## 步骤 -1. 在 **Settings** → 找到 **Socket Mode** 并开启。 -2. 建 **App-Level Token**,Scope 勾 `connections:write`。 -3. 复制以 `xapp-` 开头的 **App-Level Token**。 +### 1. 在 Slack API 控制台创建 app -## 3. Bot 权限(OAuth Scopes) +1. 打开 [Slack API 控制台](https://api.slack.com/apps),点 **Create New App**。 +2. 选择要安装 Bot 的 workspace。 -在 **OAuth & Permissions** → **Bot Token Scopes** 至少加当前适配会用的,例如: +::: tip +保持 app 设置页开着,第 2 到 5 步都在这里完成。 +::: -- `app_mentions:read`:频道里 @ -- `channels:history` / `groups:history` / `im:history` / `mpim:history`:读各场景消息 -- `chat:write`:在频道/线程/DM 里发 -- `files:read` / `files:write`:收、发文件 -- `reactions:write`:添加/移除反应 +### 2. 在 Slack API 控制台开启 Socket Mode -建议再加(名字、元数据更齐): +Memoh 的 Slack 适配走 Socket Mode,所以除 Bot token 外还需要一个 app-level token。 -- `channels:read` / `groups:read` / `im:read` / `mpim:read` +1. 在 **Basic Information** 里开启 **Socket Mode**。 +2. 创建 **App-Level Token**,scope 勾 `connections:write`。 +3. 复制生成的 token,以 `xapp-` 开头。 -## 4. 订事件 +### 3. 在 Slack API 控制台加 Bot Token Scopes -**Event Subscriptions** 打开,**Subscribe to bot events** 里加,例如: +在 **OAuth & Permissions** 里加上 Slack 适配需要的 scope: + +- `app_mentions:read`:接收频道里对 Bot 的 @ +- `channels:history`:读公开频道消息 +- `groups:history`:读私有频道消息 +- `im:history`:读 DM +- `mpim:history`:读多人 DM +- `chat:write`:发送回复和 thread 消息 +- `files:read`:读上传的文件和图片 +- `files:write`:发出文件 +- `reactions:write`:添加/移除 reaction + +想让会话名称、元数据在 Memoh 里显示得更全,建议再加: + +- `channels:read` +- `groups:read` +- `im:read` +- `mpim:read` + +### 4. 在 Slack API 控制台订阅事件 + +在 **Event Subscriptions** 里开启 bot events,加上 Slack 适配处理的入站事件: - `app_mention` -- `message.channels` / `message.groups` / `message.im` / `message.mpim` +- `message.channels` +- `message.groups` +- `message.im` +- `message.mpim` + +### 5. 在 Slack API 控制台把 app 装进 workspace + +1. 在 **OAuth & Permissions** 点 **Install to Workspace**。 +2. 确认权限页并授权。 +3. 复制 **Bot User OAuth Token**,以 `xoxb-` 开头。 + +### 6. 在 Memoh 添加 Slack 渠道 + +1. 打开 Bot 详情页,进入 **平台** 标签页。 +2. 点 **Add Channel**,选 **Slack**。 +3. 填写: + - **Bot Token**:`xoxb-` 开头的 token + - **App-Level Token**:`xapp-` 开头的 token +4. 点 **Save and Enable**。 + +### 7. 在 Slack 把 Bot 加进对话 + +渠道启用后,还要让这个 Slack app 出现在你想用它的对话里: + +- DM:和该 app 开对话并发一条消息。 +- 公开频道:把 Bot 邀请进频道。 +- 私有频道:装好后显式邀请进频道。 + +## 凭据 + +| 字段 | 说明 | +|------|------| +| **Bot Token** | 装进 workspace 后复制的 **Bot User OAuth Token**(`xoxb-` 开头)。 | +| **App-Level Token** | 为 Socket Mode 创建、带 `connections:write` scope 的 token(`xapp-` 开头)。 | + +两个 token 必须来自同一个 Slack app、同一个 workspace。 + +## 验证 + +把 Bot 邀请进一个频道并 @它发送 `/help`,或在 DM 里发 `/help`。Bot 回复命令列表即说明渠道已生效。 -以你装的 Memoh 版本在文档/发行说明里写的为准;上面是常见集合。 +## 群聊 -## 5. 装到工作区 +Slack 频道即群聊场景。把 Bot 邀请进公开或私有频道,@它即可对话;回复可以在 thread 里继续,Slack 也是唯一支持 thread 的渠道。 -1. **OAuth & Permissions** → **Install to Workspace**。 -2. 授权后复制 **Bot User OAuth Token**(`xoxb-` 开头)。 +## 停用与更换凭据 -**同一个 Slack App 里** 的 `xoxb-` 与 `xapp-` 要配对使用。 +在 Bot 的 **平台** 标签页可以随时停用或移除该渠道。更换凭据时,更新 **Bot Token** 与 **App-Level Token** 字段并保存即可。 -## 6. 在 Memoh 里填 +## 常见问题 {#faq} -1. 机器人 **Platforms** → **Add Channel** → **Slack**。 -2. 填 **Bot Token**(`xoxb-`)、**App-Level Token**(`xapp-`)。 -3. **Save and Enable**。 +### 为什么要填两个 token? {#why-two-tokens} -## 7. 把 app 加进对话 +Memoh 的 Slack 适配走 Socket Mode:除 `xoxb-` 开头的 Bot token 外,还需要 `xapp-` 开头的 app-level token,且两者必须来自同一个 Slack app 和 workspace。 -- DM:在 Slack 里和该 app 开对话并发一条。 -- 公开频道:把 app **邀请**进频道。 -- 私有频道:装好后**显式邀请**进频道。 +### Bot 能发消息,但读不到上传的图片或文件 {#cannot-read-files} -能发不能收图/文件,多半缺 `files:read`;能连上但收不到任何入站消息,查 **Event** 和 **history** 类 scope 是否配对。 +检查 `files:read` scope 是否已开启。 -## 支持的能力 +### 连上了,但收不到任何入站消息 {#no-incoming-messages} -- DM、公开/私有频道、**thread** -- 读/发附件与图片 +重新核对 **Event Subscriptions** 里的 bot events,以及配套的 `history` 类 scope。 diff --git a/docs/zh/integrations/channels/telegram.md b/docs/zh/integrations/channels/telegram.md index 1ede426..5868502 100644 --- a/docs/zh/integrations/channels/telegram.md +++ b/docs/zh/integrations/channels/telegram.md @@ -1,30 +1,46 @@ # Telegram -把 Memoh 机器人接到 Telegram。Memoh 对 TG 支持较全:流式、Markdown、附件等。 +把 Memoh Bot 接到 Telegram。Memoh 对 Telegram 的支持较全:流式、Markdown、附件等。 -## 1. 在 Telegram 建 Bot +## 前提条件 -先要有一个 **API Token**。 +- 一个 Telegram 账号,用于和 **@BotFather** 对话建 Bot。 +- 一个 Memoh Bot;渠道在它的 **平台** 标签页里配置。 -1. 在 Telegram 里搜官方 **@BotFather**。 -2. 发 `/newbot`。 -3. 按提示填: +## 步骤 + +### 1. 在 Telegram 用 @BotFather 创建 Bot + +1. 在 Telegram 里搜索官方 **@BotFather**。 +2. 发送 `/newbot`。 +3. 按提示填写: - **Name**:展示名,如 `My Memoh Bot`。 - **Username**:全局唯一、以 `bot` 结尾,如 `my_memoh_bot`。 -4. BotFather 会给 **API Token**(形如 `123456789:ABC...`)。**不要泄露。** +4. BotFather 会回复 **API Token**(形如 `123456789:ABC...`)。**不要泄露。** > 官方说明:[Telegram Bot Tutorial](https://core.telegram.org/bots/tutorial) -## 2. 在 Memoh 里填 +### 2. 在 Memoh 添加 Telegram 渠道 + +1. 打开 Bot 详情页,进入 **平台** 标签页。 +2. 点 **Add Channel**,选 **Telegram**。 +3. 把 **API Token** 填进凭据字段。 +4. 点 **Save and Enable**。 + +## 凭据 + +| 字段 | 说明 | +|------|------| +| **API Token** | 创建 Bot 时 BotFather 发给你的 token(形如 `123456789:ABC...`),不要泄露。 | + +## 验证 + +在 Telegram 里私聊 Bot,发送 `/help`。Bot 回复命令列表即说明渠道已生效。 + +## 群聊 -1. 网页里打开机器人 **详情** → **Platforms**。 -2. **Add Channel** → 选 **Telegram**。 -3. 把 **API Token** 填进凭据。 -4. **Save and Enable**。 +Telegram 支持群聊。把 Bot 拉进群后,@它的用户名即可在群里对话。 -## 支持的能力 +## 停用与更换凭据 -- **流式**:边生成边出字。 -- **Markdown**:粗体、斜体、代码块、链接等。 -- **附件**:收图/文件,机器人也可发文件。 -- **回复链**:机器人能理解回复消息中的上下文。 +在 Bot 的 **平台** 标签页可以随时停用或移除该渠道。更换 token 时,更新 **API Token** 字段并保存即可。 diff --git a/docs/zh/integrations/channels/wechatoa.md b/docs/zh/integrations/channels/wechatoa.md deleted file mode 100644 index c888644..0000000 --- a/docs/zh/integrations/channels/wechatoa.md +++ /dev/null @@ -1,43 +0,0 @@ -# 微信公众号 - -与 **个人微信扫码** 那套不同:这是 **服务号/公众号的 webhook 接入**,适合平台把消息**推**到你部署的 URL,多用在私聊入站场景。 - -## 1. 准备平台侧信息 - -在微信公众号平台准备至少: - -- **App ID** -- **App Secret** -- **Token** - -若开加密传输,还要 **Encoding AES Key**;出网要绕代理时可能有 **代理 URL** 等,按你部署来。 - -## 2. 在 Memoh 里加渠道 - -1. 机器人 **Platforms** → **Add Channel** → **WeChat Official Account**(名称以界面为准)。 -2. 填 **App ID**、**App Secret**、**Token**。 -3. 选 **加解密方式**(与微信后台一致)。 -4. 若用 `safe` / `compat` 等要密钥的模式,再填 **Encoding AES Key**。 -5. 先**保存**渠道。保存后 Memoh 会生成 **URL(服务器配置)** 用的回调地址,复制到微信平台。 - -## 3. 在微信平台填回调 - -1. 把 Memoh 的 **Webhook 回调 URL** 粘到公众号后台「服务器配置」的 URL。 -2. **Token**、**加解密方式**、**EncodingAESKey** 两边必须**完全一致**。 -3. 微信会先做一次**验证**,通过后才真正推消息。 - -## 4. 启用与试发 - -1. Memoh 里打开该渠道。 -2. 用测试号或正式号走一条**私聊**入站,看 Memoh 是否收到、机器人能否回。 - -## 支持的能力 - -- 私聊场景 -- 回复 -- 附件/媒体 - -**注意**(以当前适配为准): - -- 不是群聊那种产品形态 -- 出站多 **非流式** diff --git a/docs/zh/integrations/channels/wecom.md b/docs/zh/integrations/channels/wecom.md index 64dfe18..f2ba098 100644 --- a/docs/zh/integrations/channels/wecom.md +++ b/docs/zh/integrations/channels/wecom.md @@ -1,37 +1,51 @@ -# 企业微信(WeCom / WeWork) +# 企业微信(WeCom / WeWork) -在企微工作区内收发消息,常走管理后台里自建/机器人应用。 +把 Memoh Bot 接入企业微信,在组织的企微工作区内与用户私聊或在群聊中协作。 -## 1. 建企微侧凭据 +## 前提条件 -1. 登录 [企微管理后台](https://work.weixin.qq.com/) 或开发文档里指引的入口。 -2. 在 **应用管理** 等位置创建 **自建应用** 或 **机器人**(以你组织实际菜单为准)。 -3. 记下 **AgentId / Bot ID** 与 **Secret** 等(字段名以 Memoh 表单与企微当前文档为准)。 +- 拥有 [企微管理后台](https://work.weixin.qq.com/) 的管理权限,用于创建 Bot 应用。 -## 2. 在 Memoh 里填 +## 步骤 -1. 机器人 **Platforms** → **Add Channel** → **WeCom**。 -2. 按表单填,常见包括: +### 1. 在企微管理后台创建 Bot + +在企微管理后台: + +1. 登录 [企微管理后台](https://work.weixin.qq.com/)。 +2. 进入 **应用管理** 下的 **自建应用** 或 **Bot 管理**。 +3. 创建一个新的 Bot 应用。 +4. 记下 **Bot ID** 和 **Secret** 凭据。 + +> 官方文档:[企微开放平台](https://developer.work.weixin.qq.com/) · [企微 Bot 文档](https://developer.work.weixin.qq.com/document/path/91770) + +### 2. 在 Memoh 里添加渠道 + +在 Memoh: + +1. 打开 Bot 的 **平台** 标签页。 +2. 点 **Add Channel**,选择 **WeCom**。 +3. 填入 **Bot ID** 和 **Secret**;仅在需要时填自定义 **WebSocket URL**。 +4. 点 **Save and Enable**。 + +启用后,Memoh 通过 WebSocket 连接企微并开始接收消息。 + +## 凭据 | 字段 | 必填 | 说明 | |------|------|------| -| **Bot ID** | 是 | 企微里该机器人的标识 | -| **Secret** | 是 | 鉴权用 | -| **WebSocket URL** | 否 | 不填多用默认端点 | - -3. **Save and Enable**。 +| **Bot ID** | 是 | 企微里该 Bot 的标识。 | +| **Secret** | 是 | Bot 的鉴权凭据。 | +| **WebSocket URL** | 否 | 自定义 WebSocket 端点;留空时使用默认端点。 | -## 3. 使用 +## 验证 -连上后,工作区内用户可私聊或拉群与机器人说话,行为以你企微与 Memoh 当前版本为准。 +私聊给 Bot 发送 `/help`,或在群聊中 @Bot 并发送 `/help`。Bot 回复命令列表,说明渠道已接通。 -## 支持的能力 +## 群聊 -- 文本 -- 私聊、群聊 -- **流式**回复(在 Memoh 里多为实时出字,以实际为准) +Bot 也能在企微群聊中使用:在群里 @Bot 即可触发回复。 -## 参考 +## 停用与更换凭据 -- [企微开放能力](https://developer.work.weixin.qq.com/) -- [企微「智能机器人」等文档以官网为准](https://developer.work.weixin.qq.com/document/path/91770) +随时可在 Bot 的 **平台** 标签页停用或移除该渠道。更换凭据时,在同一面板更新 **Bot ID** / **Secret** 并保存即可。 diff --git a/docs/zh/integrations/channels/weixin.md b/docs/zh/integrations/channels/weixin.md index 291e3f6..75ddb84 100644 --- a/docs/zh/integrations/channels/weixin.md +++ b/docs/zh/integrations/channels/weixin.md @@ -1,32 +1,52 @@ -# 微信(个人号) +# 微信(个人号) -个人微信发消息、收附件。Memoh 侧是 **扫二维码** 登录,不手填长串 token。 +把 Memoh Bot 接入个人微信:扫二维码即可登录,不用手填 token 或 API key。 -## 1. 在 Memoh 里加渠道 +::: warning 使用限制 +- 仅支持私聊。 +- 仅输出纯文本,不渲染 Markdown。 +- 文本消息按每段最多 4000 字符拆分发送。 +- 回复按完整消息送达,无流式输出。 +::: -1. 机器人 **Platforms** → **Add Channel** → **WeChat**。 +## 前提条件 -## 2. 扫码 +- 手机上装有微信,并登录 Bot 要使用的账号——登录靠手机扫码确认。 -1. 点 **Start QR Login**,Memoh 会拉取二维码。 -2. 手机微信扫页面上的码。 -3. 手机上点确认。 -4. 成功后会话凭据由 Memoh 存好,一般**不用**你复制 API key。 +## 步骤 -码有过期时间;过期了再点 **Start QR Login** 重刷。 +### 1. 在 Memoh 里添加微信渠道 -## 3. 使用 +在 Memoh,打开 Bot 的 **平台** 标签页,点 **Add Channel**,选择 **WeChat**。 -登录成功后渠道一般会自动启用。用户即可在微信里跟机器人私聊。 +### 2. 扫码登录 -## 可选 +在 Memoh: -| 字段 | 说明 | -|------|------| -| **Enable Typing** | 生成中是否显示「正在输入」类状态 | +1. 点 **Start QR Login**,Memoh 会从微信平台拉取二维码。 +2. 用手机微信扫页面上显示的二维码。 +3. 在手机上确认登录。 -## 支持的能力 +确认后,Memoh 自动保存凭据,渠道随即启用。 -- 私聊文本 -- 图片、媒体等附件 -- 可选「正在输入」提示 +## 凭据 + +扫码登录后,会话凭据由 Memoh 自动保存,没有需要手填的字段。可选设置一项: + +| 字段 | 必填 | 说明 | +|------|------|------| +| **Enable Typing** | 否 | 生成回复时显示「正在输入」状态。 | + +## 验证 + +二维码登录成功后,渠道自动启用。在微信里私聊给 Bot 发送 `/help`,Bot 回复命令列表,说明渠道已接通。 + +## 停用与更换凭据 + +随时可在 Bot 的 **平台** 标签页停用或移除该渠道。需要重新登录时,再次点 **Start QR Login** 走一遍扫码流程即可。 + +## 常见问题 {#faq} + +### 还没扫,二维码就过期了 {#qr-expired} + +二维码有有效期。再点一次 **Start QR Login**,获取新的二维码。 diff --git a/docs/zh/integrations/index.md b/docs/zh/integrations/index.md index f39a6ae..26d6a90 100644 --- a/docs/zh/integrations/index.md +++ b/docs/zh/integrations/index.md @@ -1,10 +1,10 @@ # 集成 -集成用于把 Memoh 接到外部系统。需要让机器人出现在消息平台里,或需要配置模型、记忆、语音、搜索等上游能力时,从这里开始。 +集成用于把 Memoh 接到外部系统。需要让 Bot 出现在消息平台里,或需要配置模型、记忆、语音、搜索等上游能力时,从这里开始。 ## 渠道 -渠道让机器人可以在网页端之外被访问。 +渠道让 Bot 在 Memoh 客户端之外也能被访问。 - **[渠道总览](/zh/integrations/channels/)**:支持的平台和通用配置流程。 - **[Slack](/zh/integrations/channels/slack)**、**[Telegram](/zh/integrations/channels/telegram)**、**[飞书](/zh/integrations/channels/feishu)**、**[Discord](/zh/integrations/channels/discord)**、**[微信](/zh/integrations/channels/weixin)** 等。 @@ -14,10 +14,10 @@ 提供方把 Memoh 接到外部能力后端。 - **[LLM 提供方](/zh/integrations/providers/llm)**:配置上游 API、client type 和模型角色。 -- **[记忆提供方](/zh/integrations/providers/memory/)**:选择内置记忆、Mem0 或 OpenViking。 -- **[TTS 提供方](/zh/integrations/providers/tts/)**:配置语音合成提供方和模型。 +- **[记忆提供方](/zh/integrations/providers/memory/builtin)**:选择内置记忆、Mem0 或 OpenViking。 +- **[TTS 提供方](/zh/integrations/providers/tts/edge)**:配置语音合成提供方和模型。 - **[搜索提供方](/zh/integrations/providers/web-search)**:配置搜索提供方接入。 ## 产品教程 -集成配置完成后,到 **[教程](/zh/guides/)** 查看机器人、会话、记忆操作、工具和日常工作流。 +集成配置完成后,到 **[教程](/zh/guides/)** 查看 Bot、会话、记忆操作、工具和日常工作流。 diff --git a/docs/zh/integrations/providers/index.md b/docs/zh/integrations/providers/index.md deleted file mode 100644 index 8b4ebdb..0000000 --- a/docs/zh/integrations/providers/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# 提供方 - -提供方把 Memoh 接到外部能力后端。先配置提供方,再把模型、记忆、语音或搜索能力分配给机器人。 - -## 提供方类型 - -- **[模型服务商](./llm.md)**:聊天、embedding、生图等模型配置。 -- **[记忆提供方](./memory/index.md)**:长期记忆的存储和检索后端。 -- **[TTS 提供方](./tts/index.md)**:语音合成提供方和音色。 -- **[搜索提供方](./web-search.md)**:网页访问工具使用的搜索提供方。 - -配置完成后,产品侧使用方式见 **[机器人](../../guides/bot.md)** 和 **[长期记忆](../../guides/memory.md)**。 diff --git a/docs/zh/integrations/providers/llm.md b/docs/zh/integrations/providers/llm.md index 93f60b2..1b90804 100644 --- a/docs/zh/integrations/providers/llm.md +++ b/docs/zh/integrations/providers/llm.md @@ -4,7 +4,7 @@ - 一个或多个 **模型服务商**(怎么连上游 API) - 其下的 **模型** -- 若要朗读,再配 **语音合成**(见 [TTS](./tts/index.md)) +- 若要朗读,再配 **语音合成**(见 [TTS 提供方](./tts/edge.md)) - 若要把语音转文字,再配 **语音转写** 聊天与 embedding 在 **Models** 页管理;语音合成模型在 TTS 流程里单走,语音转写模型在 Transcription 设置页管理。 @@ -68,7 +68,7 @@ | `microsoft-speech` | Microsoft 语音合成 | | `google-transcription` | Google 语音转写 | -语音合成与语音转写类型不能当主聊天用。语音合成走 [TTS 提供方](./tts/index.md),语音转写走 Transcription 设置页。具体模型、音色和语言取决于 provider 模板与上游账号。 +语音合成与语音转写类型不能当主聊天用。语音合成走 [TTS 提供方](./tts/edge.md),语音转写走 Transcription 设置页。具体模型、音色和语言取决于 provider 模板与上游账号。 --- @@ -114,11 +114,19 @@ Copilot 凭据以前按用户存,现在和 Codex 一样是模型服务商级 ## 导入模型 -建完模型服务商后可以导入或手加模型。常见:选中模型服务商 → **Import Models**(若上游有目录)→ 勾要保存的。已知上游 id 时也可手填。 +建完模型服务商后,可以在它下面导入或手动添加模型。 + +典型流程: + +1. 选中模型服务商。 +2. 若它能给出模型目录,点 **Import Models**。 +3. 勾选要存进 Memoh 的模型。 + +已知上游模型 ID 时,也可以手动添加。 ### 模型启用开关 -模型服务商详情页里每个模型一行,各带**启用开关**。禁用的模型仍留在这页方便再开,但会从所有模型选择器(机器人设置、聊天、embedding 等)里消失。 +模型服务商详情页里每个模型一行,各带**启用开关**。禁用的模型仍留在这页方便再开,但会从所有模型选择器(Bot 设置、聊天、embedding 等)里消失。 默认值看模型怎么来的: @@ -136,7 +144,7 @@ Copilot 凭据以前按用户存,现在和 Codex 一样是模型服务商级 | `speech` | 朗读,挂在 TTS | | `transcription` | 语音转文字,挂在 Transcription | -**Models** 页主要管 chat / embedding;speech 在 [TTS](./tts/index.md),transcription 在 Transcription 设置页。 +**Models** 页主要管 chat / embedding;speech 在 [TTS 提供方](./tts/edge.md),transcription 在 Transcription 设置页。 --- @@ -174,19 +182,27 @@ Memoh 用来: ### 文生图模型 -机器人上可单挂 **Image Generation Model**,须是带 `image-output` 的 chat 模型。需要时与默认聊天模型分开。 +Bot 上可单挂 **Image Generation Model**,须是带 `image-output` 的 chat 模型。需要时与默认聊天模型分开。 --- ## Embedding 模型 -给语义索引用。必填如 **Dimensions**(向量维数,如 1536)。和记忆或其它向量检索能力绑在一起用。 +Embedding 模型用于语义索引与检索。 + +必填字段: + +| 字段 | 说明 | +|------|------| +| **Dimensions** | embedding 输出的向量维数,如 `1536`。 | + +配合记忆提供方,或任何依赖向量检索的能力使用。 --- ## 语音合成与转写模型 -语音合成在 [TTS 提供方](./tts/index.md) 配,不跟普通 chat 模型服务商混流。当前语音合成类别包括: +语音合成在 [TTS 提供方](./tts/edge.md) 配,不跟普通 chat 模型服务商混流。当前语音合成类别包括: - Edge:`edge-speech` - OpenAI 兼容:`openai-speech` @@ -212,7 +228,7 @@ Memoh 用来: ## 怎么记省事 -对多数机器人,可以分几条线想: +对多数 Bot,可以分几条线想: - **Chat**:日常说人话 - **Embedding**:记忆 @@ -224,6 +240,6 @@ Memoh 用来: ## 接下来 -- 给机器人绑聊天、生图、记忆、朗读等:[机器人](../../guides/bot.md) -- 配语音提供方与语音模型:[TTS 提供方](./tts/index.md) -- 配语音转文字:打开 Web UI 的 Transcription 设置页 +- 给 Bot 绑聊天、生图、记忆、朗读等:[Bot](../../guides/working-with-bots.md) +- 配语音提供方与语音模型:[TTS 提供方](./tts/edge.md) +- 配语音转文字:打开客户端的 Transcription 设置页 diff --git a/docs/zh/integrations/providers/memory/builtin.md b/docs/zh/integrations/providers/memory/builtin.md index 4e53445..7197c72 100644 --- a/docs/zh/integrations/providers/memory/builtin.md +++ b/docs/zh/integrations/providers/memory/builtin.md @@ -11,7 +11,7 @@ ## 工作方式 -内置提供方运行在 **graph** 模式:记忆节点与边存放在 PostgreSQL 中作为唯一真源,并派生出一份 Markdown 视图(机器人工作区里的 `memory/` bundle 和 `MEMORY.md`)供 Agent 读写。 +内置提供方运行在 **graph** 模式:记忆节点与边存放在 PostgreSQL 中作为唯一真源,并派生出一份 Markdown 视图(Bot 工作区里的 `memory/` bundle 和 `MEMORY.md`)供 Agent 读写。 语义检索是可选的加层: @@ -68,9 +68,9 @@ sslmode = "disable" --- -## 绑到机器人 +## 绑到 Bot -1. **Bots** → 机器人 +1. **Bots** → Bot 2. **General** → **Memory Provider** 3. 保存 @@ -80,7 +80,7 @@ sslmode = "disable" ## 配好之后 -在机器人的 **Memory** tab 里管理具体记忆: +在 Bot 的 **Memory** tab 里管理具体记忆: - 手动新建 - 从对话抽取 diff --git a/docs/zh/integrations/providers/memory/index.md b/docs/zh/integrations/providers/memory/index.md deleted file mode 100644 index 6be9d6e..0000000 --- a/docs/zh/integrations/providers/memory/index.md +++ /dev/null @@ -1,28 +0,0 @@ -# 记忆提供方 - -**Memory Provider** 决定机器人**怎么存、怎么取、怎么管**长期记忆。在机器人 **General** 里绑一个,即成为抽取与检索记忆的后端。 - -## 有哪些 - -- [内置](./builtin.md):默认自带:记忆图存 PostgreSQL,配了 embedding 模型后可加 pgvector 语义检索,全可自建。 -- [Mem0](./mem0.md):走 Mem0 云 API,要密钥。 -- [OpenViking](./openviking.md):自建或 SaaS,自有 API。 - ---- - -## 一般步骤 - -1. 侧栏 **Memory Providers**。 -2. 选类型,建一个实例。 -3. 配好参数。 -4. 机器人 **General** → **Memory Provider** 选中。 -5. 在 **Memory** tab 里管具体条目。 - ---- - -## 接下来 - -- [内置](./builtin.md) -- [Mem0](./mem0.md) -- [OpenViking](./openviking.md) -- 条目级操作:[长期记忆](../../../guides/memory.md) diff --git a/docs/zh/integrations/providers/memory/mem0.md b/docs/zh/integrations/providers/memory/mem0.md index 98ecd53..6325c99 100644 --- a/docs/zh/integrations/providers/memory/mem0.md +++ b/docs/zh/integrations/providers/memory/mem0.md @@ -1,6 +1,6 @@ # Mem0 记忆 -把机器人接到 [Mem0](https://mem0.ai) 云端,由对方管存储、索引、检索,本机不搭那套库。 +把 Bot 接到 [Mem0](https://mem0.ai) 云端,由对方管存储、索引、检索,本机不搭那套库。 --- @@ -23,9 +23,9 @@ --- -## 绑到机器人 +## 绑到 Bot -1. **Bots** → 机器人 → **General** +1. **Bots** → Bot → **General** 2. **Memory Provider** 选 Mem0 3. 保存 diff --git a/docs/zh/integrations/providers/memory/openviking.md b/docs/zh/integrations/providers/memory/openviking.md index e7d2d3a..7e231e8 100644 --- a/docs/zh/integrations/providers/memory/openviking.md +++ b/docs/zh/integrations/providers/memory/openviking.md @@ -21,9 +21,9 @@ --- -## 绑到机器人 +## 绑到 Bot -1. **Bots** → 机器人 → **General** +1. **Bots** → Bot → **General** 2. **Memory Provider** 选 OpenViking 3. 保存 diff --git a/docs/zh/integrations/providers/tts/edge.md b/docs/zh/integrations/providers/tts/edge.md index 6a612ce..460376a 100644 --- a/docs/zh/integrations/providers/tts/edge.md +++ b/docs/zh/integrations/providers/tts/edge.md @@ -1,6 +1,6 @@ # Edge TTS -用 Edge 对外公开的朗读接口做合成:免费、无 API key,语言/声音很多。 +用 Edge 对外公开的朗读接口做合成:免费、无 API key,提供 256+ 个声音,覆盖 50+ 种语言。 --- @@ -10,7 +10,7 @@ 2. 类型选 `edge`。 3. **Create**。 -通常会自带默认模型 `edge-read-aloud`。 +创建提供方时会自动导入默认模型 `edge-read-aloud`。 --- @@ -20,16 +20,16 @@ | 字段 | 说明 | |------|------| -| **Voice** | 语言 + 声线 id,默认如 `en-US-EmmaMultilingualNeural` | -| **Format** | 如 `audio-24khz-48kbitrate-mono-mp3`、webm 等 | -| **Speed** | 如 `0.5`、`1.0`、`2.0` | -| **Pitch** | -100 ~ +100,默认 0 | +| **Voice** | 语言 + 声线 id,默认 `en-US-EmmaMultilingualNeural`;共 256+ 个声音、50+ 种语言可选 | +| **Format** | 输出格式:`audio-24khz-48kbitrate-mono-mp3`(默认)、`audio-24khz-96kbitrate-mono-mp3`、`webm-24khz-16bit-mono-opus` | +| **Speed** | 语速:`0.5`、`1.0`(默认)、`2.0`、`3.0` | +| **Pitch** | 音高:`-100` ~ `+100`,默认 `0` | --- -## 绑到机器人 +## 绑到 Bot -1. 机器人 **General** → **TTS Model** +1. Bot **General** → **TTS Model** 2. 选配好的 Edge 模型 3. 保存 @@ -37,4 +37,4 @@ ## 试听 -模型页上一般有试合成按钮,绑给机器人前可先听效果。 +模型配置页有内置的试合成按钮,绑给 Bot 前先听一遍所选声音、格式、语速、音高的效果。 diff --git a/docs/zh/integrations/providers/tts/index.md b/docs/zh/integrations/providers/tts/index.md deleted file mode 100644 index 60448a9..0000000 --- a/docs/zh/integrations/providers/tts/index.md +++ /dev/null @@ -1,45 +0,0 @@ -# 语音(TTS) - -Memoh 支持把字变成声音。可以分三层想: - -- **TTS Provider**:一种服务类型(如 Edge TTS),在 TTS 页建**具名实例**。 -- **TTS Model**:某实例下的具体声音/模型,可配音色、格式、变速、音高。 -- **机器人绑定**:在机器人 **General** 里选 TTS Model,之后对话里可朗读。 - ---- - -## 一般步骤 - -1. 侧栏 **TTS Providers**。 -2. **Add**,选类型(如 `edge`)。 -3. **Create**(常会自动导入默认模型)。 -4. 点进模型,调音色、格式等。 -5. 用页面试听。 -6. 机器人 **General** 里选这个 TTS Model 并保存。 - ---- - -## 可用语音合成提供方 - -| 提供方 | 说明 | -|--------|------| -| [Edge TTS](./edge.md) | 走 Edge 公开朗读接口,无 key,多语音 | -| OpenAI 兼容语音合成 | 使用 OpenAI 兼容的语音合成 API,需要匹配 provider 模板和凭据。 | -| OpenRouter Speech | 使用 OpenRouter 可用的语音合成路线,具体取决于账号能力。 | -| ElevenLabs Speech | 使用 ElevenLabs 语音合成模型和音色。 | -| Deepgram Speech | 使用 Deepgram 语音合成模型。 | -| MiniMax Speech | 使用 MiniMax 语音合成模型。 | -| 火山引擎语音合成 | 使用火山引擎语音合成模型。 | -| 阿里云语音合成 | 使用阿里云语音合成模型。 | -| Microsoft Speech | 使用 Microsoft 语音合成模型。 | - -具体模型、音色、格式和语言取决于你配置的 provider 模板与上游账号。 - -语音转写与 TTS 分开管理。Memoh 也支持 OpenAI 兼容、OpenRouter、ElevenLabs、Deepgram、Google 等语音转写 provider 类别。 - ---- - -## 接下来 - -- 配无 key 的 Edge 选项:[Edge TTS](./edge.md) -- 了解音频 provider client type 与模型关系:[模型服务商与模型](../llm.md) diff --git a/docs/zh/integrations/providers/video.md b/docs/zh/integrations/providers/video.md index 7befe2a..79a58f4 100644 --- a/docs/zh/integrations/providers/video.md +++ b/docs/zh/integrations/providers/video.md @@ -1,11 +1,11 @@ # 视频生成提供方 -机器人靠 `generate_video` 工具生成视频。要用上它,两步缺一不可: +Bot 靠 `generate_video` 工具生成视频。要用上它,两步缺一不可: 1. 在 **设置 → 集成 → Video** 里配好**视频提供方**和至少一个视频模型; -2. 在 **机器人设置 → 多媒体** 里给机器人选一个**视频生成模型**。 +2. 在 **Bot 设置 → 多媒体** 里给 Bot 选一个**视频生成模型**。 -没选视频模型的机器人根本不会拿到 `generate_video` 这个工具。 +没选视频模型的 Bot 根本不会拿到 `generate_video` 这个工具。 --- @@ -35,18 +35,18 @@ OpenRouter 支持 **Import Models** 在线拉模型列表;ModelArk 和火山 2. 从模板列表里加一个提供方(OpenRouter / ModelArk / 火山引擎)。 3. 填 API Key,非默认接入点才需要改 Base URL,保存。 4. 看 **Video Models** 区:列表空的话从提供方导入或手动加一个。 -5. 去机器人 **设置 → 多媒体**,选上**视频生成模型**。 +5. 去 Bot **设置 → 多媒体**,选上**视频生成模型**。 --- -## 机器人怎么用 +## Bot 怎么用 -直接跟机器人说"给我生成一个 xx 的视频"就行。背后发生的事: +直接跟 Bot 说"给我生成一个 xx 的视频"就行。背后发生的事: -- `generate_video` 是**后台任务**,立刻返回 task ID;生成通常要几分钟,机器人自己用后台任务工具盯进度。 +- `generate_video` 是**后台任务**,立刻返回 task ID;生成通常要几分钟,Bot 自己用后台任务工具盯进度。 - 参数除了 `prompt`,还有可选的 `duration_seconds`、`resolution`(`720p`/`1080p`)、`aspect_ratio`(`16:9`、`9:16`、`1:1`)、提供方专属的 `size`、`generate_audio`。 -- 成片下载到机器人 workspace 的 `/data/generated-videos/.mp4`(也可能是 `.webm`/`.mov`,看提供方输出)。 -- 视频**不会自动发出去**——机器人以消息附件形式交付,你也可以去 workspace 的 **Files** tab 拿。 +- 成片下载到 Bot workspace 的 `/data/generated-videos/.mp4`(也可能是 `.webm`/`.mov`,看提供方输出)。 +- 视频**不会自动发出去**——Bot 以消息附件形式交付,你也可以去 workspace 的 **Files** tab 拿。 生成完成时如果 workspace 不可达,任务照样算完成,会带 warning 和提供方的输出 URL,只是没存盘。 diff --git a/docs/zh/integrations/providers/web-search.md b/docs/zh/integrations/providers/web-search.md index 1be10d5..013afcf 100644 --- a/docs/zh/integrations/providers/web-search.md +++ b/docs/zh/integrations/providers/web-search.md @@ -1,16 +1,16 @@ # 搜索提供方 -给机器人接 **Search Provider** 后,它能在对话里**实时**查网,用搜索引擎 API 当工具。 +给 Bot 接 **Search Provider** 后,它能在对话里**实时**查网,用搜索引擎 API 当工具。 ## 在做什么 -每个 Search Provider 是某一家的搜索 API(如 Brave、Google)。配好并绑到机器人后,需要新鲜事实时由模型去调。 +每个 Search Provider 是某一家的搜索 API(如 Brave、Google)。配好并绑到 Bot 后,需要新鲜事实时由模型去调。 --- ## 支持哪些 -侧栏 **Search Provider** 里建。常见能力包括(以你装的版本为准): +在侧栏 **Search Provider** 页配置搜索引擎。支持的引擎: | 引擎 | 说明 | |------|------| @@ -34,15 +34,15 @@ --- -## 绑到机器人 +## 绑到 Bot -1. **Bots** → 机器人 +1. **Bots** → Bot 2. **General** 3. **Search Provider** 下拉选中 4. 保存 --- -## 机器人怎么用 +## Bot 怎么用 需要**较新、较贴问题**的公开信息时,会走搜索,再把结果融进回答;可多结果综合。具体策略由模型和工具设计决定。 diff --git a/docs/zh/memory-providers/index.md b/docs/zh/memory-providers/index.md index f5bad3f..d5e28ad 100644 --- a/docs/zh/memory-providers/index.md +++ b/docs/zh/memory-providers/index.md @@ -7,10 +7,10 @@ title: Redirecting import { onMounted } from 'vue' onMounted(() => { - window.location.replace('/zh/integrations/providers/memory/') + window.location.replace('/zh/integrations/providers/memory/builtin') }) - + -Redirecting to [/zh/integrations/providers/memory/](/zh/integrations/providers/memory/). +Redirecting to [/zh/integrations/providers/memory/builtin](/zh/integrations/providers/memory/builtin). diff --git a/docs/zh/self-hosted/desktop.md b/docs/zh/self-hosted/desktop.md index ff5cd0c..fc9f1e8 100644 --- a/docs/zh/self-hosted/desktop.md +++ b/docs/zh/self-hosted/desktop.md @@ -1,6 +1,6 @@ # Desktop -Memoh Desktop 是面向 Memoh Cloud 或自托管 Memoh 服务端的原生客户端。它把同一套 Web UI 打包进 Electron 外壳,提供原生窗口、托盘、菜单与快捷键,并且可以把所在的这台电脑注册为机器人可用的 **Computer**。 +Memoh Desktop 是面向 Memoh Cloud 或自托管 Memoh 服务端的原生客户端。它把同一套客户端界面打包进 Electron 外壳,提供原生窗口、托盘、菜单与快捷键,并且可以把所在的这台电脑注册为 Bot 可用的 **Computer**。 Desktop **不会**自己运行本地服务端或数据库。你始终需要把它连到一个 Memoh 服务端:[Memoh Cloud](https://memoh.ai) 或你自己的 [Server Deploy](./docker.md)。 @@ -10,9 +10,9 @@ Desktop **不会**自己运行本地服务端或数据库。你始终需要把 - 想要原生 App 窗口与系统托盘,而不是浏览器标签页 - 想用原生菜单与快捷键处理日常的 Memoh 工作流 -- 想让服务端的机器人使用这台电脑的文件、Shell 与浏览器,又不想单独跑一个 runtime 进程 +- 想让服务端的 Bot 使用这台电脑的文件、Shell 与浏览器,又不想单独跑一个 runtime 进程 -如果只是偶尔从浏览器访问,直接用 Web UI 即可。 +如果只是偶尔从浏览器访问,直接用网页客户端即可。 ## 安装 @@ -31,17 +31,17 @@ Desktop **不会**自己运行本地服务端或数据库。你始终需要把 切换到另一个服务端会清除本地登录状态,需要重新登录。 -## 把这台电脑共享给机器人 +## 把这台电脑共享给 Bot -Desktop 可以把它所在的机器注册成服务端机器人可用的 **Computer**,不用另跑 runtime 进程:打开 **这台电脑** 开关,起个名字,Desktop 会通过内嵌的 Memoh runtime SDK 在后台维持连接。凭据使用操作系统的安全存储保存。 +Desktop 可以把它所在的机器注册成服务端 Bot 可用的 **Computer**,不用另跑 runtime 进程:打开 **这台电脑** 开关,起个名字,Desktop 会通过内嵌的 Memoh runtime SDK 在后台维持连接。凭据使用操作系统的安全存储保存。 -权限模型、按机器人授权以及机器人在电脑上能做什么,见 [电脑](../guides/computers.md)。 +按 Bot 授权,写入与执行默认需要审批——详见 [访问控制](../guides/access.md)。 ## Desktop 负责什么 - 应用窗口、托盘图标、重新打开与退出行为 -- 与 Web UI 共用命令注册表的原生菜单 +- 与网页客户端共用命令注册表的原生菜单 - 到所选服务端的连接及其缓存的登录状态 - **这台电脑** 对应的可选 Remote Runtime 连接 -其它一切(机器人、会话、记忆、工作区、渠道)都在你连接的服务端上。工作区运行时在服务端配置,见 [Workspace Backends](./workspace-backends.md)。 \ No newline at end of file +其它一切(Bot、会话、记忆、工作区、渠道)都在你连接的服务端上。工作区运行时在服务端配置,见 [Workspace Backends](./workspace-backends.md)。 \ No newline at end of file diff --git a/docs/zh/self-hosted/docker.md b/docs/zh/self-hosted/docker.md index ed94548..e822a90 100644 --- a/docs/zh/self-hosted/docker.md +++ b/docs/zh/self-hosted/docker.md @@ -1,12 +1,12 @@ # 服务器部署(Server Deploy) -Server Deploy 是 Memoh 的自托管服务端部署形态,适合长期在线、多人、多租户、远程访问,或需要机器人在桌面离线时继续服务外部渠道的场景。 +Server Deploy 是 Memoh 的自托管服务端部署形态,适合长期在线、多人、多租户、远程访问,或需要 Bot 在桌面离线时继续服务外部渠道的场景。 本页说明 Docker Compose 版 Server Deploy。要安装本地原生客户端,请看 [Desktop 桌面版](./desktop.md)。 默认编排里包含 PostgreSQL、用于记忆向量的 pgvector 库、一次性迁移任务、主服务(显式配置 workspace backend,智能体也在同一进程)、渠道 worker 和网页前端。数据库仅支持 PostgreSQL。 -官方 Compose 栈使用 `containerd` workspace backend。server 镜像会启动内置 containerd,并挂好机器人 workspace 需要的 runtime 文件。Docker Engine 和 Apple 后端见 [Workspace backend](./workspace-backends.md)。 +官方 Compose 栈使用 `containerd` workspace backend。server 镜像会启动内置 containerd,并挂好 Bot workspace 需要的 runtime 文件。Docker Engine 和 Apple 后端见 [Workspace backend](./workspace-backends.md)。 ## 服务结构 @@ -16,7 +16,7 @@ Compose 里有多组服务。有的默认就起,有的通过 `--profile` 打 |------|---------|------| | **server** | *(核心)* | 主服务,使用配置中的容器运行时后端,智能体同进程 | | **channel** | *(核心)* | 渠道 worker(`memoh-channel`),持有各平台连接与 webhook,通过内部 RPC 与主服务通信 | -| **web** | *(核心)* | 网页端(Vue 3) | +| **web** | *(核心)* | 网页客户端(Vue 3) | | **postgres** | *(核心)* | PostgreSQL(主数据) | | **pgvector** | *(核心)* | 带 `pgvector` 的 PostgreSQL,供可选的记忆向量使用;见 [内置记忆](../integrations/providers/memory/builtin.md) | | **migrate** | *(核心,一次性)* | 在主服务启动前执行 `memoh-server migrate up` | diff --git a/docs/zh/self-hosted/index.md b/docs/zh/self-hosted/index.md index 5a93e15..e22f53a 100644 --- a/docs/zh/self-hosted/index.md +++ b/docs/zh/self-hosted/index.md @@ -1,24 +1,23 @@ # 自托管总览 -Memoh 以服务端形态运行,Web UI 和 Desktop 桌面版都是它的客户端。先选好服务端方案,再决定怎样访问它。 +Memoh 以服务端形态运行,网页客户端和 Desktop 桌面版都是它的客户端。先选好服务端方案,再决定怎样访问它。 | 场景 | 选择 | 原因 | |------|------|------| | 什么都不想装,先试试 | [Memoh Cloud](https://memoh.ai) | 托管服务,功能一致,无需运维服务器。 | -| 共享服务器、远程访问、生产长期在线、对接 Telegram/Discord/飞书/微信/邮件等渠道、多用户或多租户 | [Server Deploy](./docker.md) | Docker Compose 栈会持续运行后端、网页端、PostgreSQL(含 pgvector 记忆存储)和 workspace runtime。 | -| 想在自己电脑上用原生 App,或把这台电脑作为 Computer 共享给机器人 | [Desktop 桌面版](./desktop.md) | 连接 Cloud 或自托管服务端的原生客户端;不会在本地运行服务端。 | +| 共享服务器、远程访问、生产长期在线、对接 Telegram/Discord/飞书/微信/邮件等渠道、多用户或多租户 | [Server Deploy](./docker.md) | Docker Compose 栈会持续运行后端、网页客户端、PostgreSQL(含 pgvector 记忆存储)和 workspace runtime。 | +| 想在自己电脑上用原生 App,或把这台电脑作为 Computer 共享给 Bot | [Desktop 桌面版](./desktop.md) | 连接 Cloud 或自托管服务端的原生客户端;不会在本地运行服务端。 | ## Server Deploy -Server Deploy 适合多人、远程、长期在线或多租户场景。机器人需要持续接入 Telegram、Discord、飞书、微信、公众号、邮件等外部渠道时,也应该用这一形态。 +Server Deploy 适合多人、远程、长期在线或多租户场景。Bot 需要持续接入 Telegram、Discord、飞书、微信、公众号、邮件等外部渠道时,也应该用这一形态。 最快的路径见 [快速开始](../guides/quick-start.md),完整参考见 [Server Deploy](./docker.md)。 ## Desktop 桌面版 -Desktop 适合想要托盘图标与快捷键的原生体验,或者想让服务端机器人使用你电脑上的文件、Shell 和浏览器的场景。Desktop 始终连接一个服务端(Cloud 或自托管),详见 [Desktop](./desktop.md)。 +Desktop 适合想要托盘图标与快捷键的原生体验,或者想让服务端 Bot 使用你电脑上的文件、Shell 和浏览器的场景。Desktop 始终连接一个服务端(Cloud 或自托管),详见 [Desktop](./desktop.md)。 ## 相关页面 - [Workspace backend](./workspace-backends.md) 解释 Docker、containerd、Apple 和本地 workspace 的差异。 -- [电脑](../guides/computers.md) 介绍如何把自己的机器共享给机器人。 \ No newline at end of file diff --git a/docs/zh/self-hosted/workspace-backends.md b/docs/zh/self-hosted/workspace-backends.md index 2f99d43..3473b6c 100644 --- a/docs/zh/self-hosted/workspace-backends.md +++ b/docs/zh/self-hosted/workspace-backends.md @@ -1,6 +1,6 @@ # 工作区后端(Workspace backend) -每个 Memoh 机器人都在一个 workspace 里工作。workspace 可以是隔离容器,也可以是在 Desktop/local 场景下明确受信任的本机目录。Backend 决定 workspace 跑在哪里,以及隔离、网络、快照和 display 能力是否可用。 +每个 Memoh Bot 都在一个 workspace 里工作。workspace 可以是隔离容器,也可以是在 Desktop/local 场景下明确受信任的本机目录。Backend 决定 workspace 跑在哪里,以及隔离、网络、快照和 display 能力是否可用。 ## 容器后端 @@ -17,7 +17,7 @@ backend = "containerd" # containerd、docker 或 apple | `docker` | Memoh 直接跑在宿主机,宿主机有 Docker Engine | 走宿主机 Docker API。`container.runtime_dir` 这类 bind mount 源路径必须在 Docker 宿主机上真实存在。 | | `apple` | macOS 本地测试 | 通过 socktainer 和 Apple Containerization。provider sidecar 不支持。 | -一键 Docker Compose Server Deploy 固定使用 `containerd`。这是有意的:server 镜像会启动内置 containerd,并挂好机器人 workspace 需要的 runtime 文件。`docker`、`apple` 更适合你能控制宿主机 runtime 路径的手动部署。 +一键 Docker Compose Server Deploy 固定使用 `containerd`。这是有意的:server 镜像会启动内置 containerd,并挂好 Bot workspace 需要的 runtime 文件。`docker`、`apple` 更适合你能控制宿主机 runtime 路径的手动部署。 ## Trusted local workspace @@ -30,7 +30,7 @@ enabled = true Trusted local workspace 直接用 server 进程权限在宿主机上运行。它适合个人桌面工作流和本地开发,但**没有容器隔离**。不要在不受信任的 server 部署里打开 local workspace。 -当机器人使用 local workspace 时,依赖容器桌面或容器 display session 的界面能力可能会隐藏或不可用。 +当 Bot 使用 local workspace 时,依赖容器桌面或容器 display session 的界面能力可能会隐藏或不可用。 ## containerd @@ -86,7 +86,7 @@ Apple backend 用于通过 socktainer 和 Apple Containerization 做 macOS 本 ## Display、Browser Use 与 Computer Use -容器 workspace 可以提供 display runtime:Xvnc/RFB 作为 workspace 桌面显示与输入基础,有头 Chrome/Chromium 提供 CDP,网页端 Display pane 通过 WebRTC 打开会话。 +容器 workspace 可以提供 display runtime:Xvnc/RFB 作为 workspace 桌面显示与输入基础,有头 Chrome/Chromium 提供 CDP,客户端的 **桌面** 面板通过 WebRTC 打开会话。 当网站需要真实图形浏览器时,用这条路径。Headless Playwright 仍然可以作为普通 workspace 命令运行,但 Browser Use 和 Computer Use 面向的是有头 workspace 桌面。 @@ -94,10 +94,10 @@ Local workspace 不提供同样的容器桌面隔离。工具层面的区别见 ## 网络和 overlay -机器人网络有两层: +Bot 网络有两层: - runtime network:把 workspace 接到基础容器或 Pod 网络。 -- overlay provider:如 Tailscale、NetBird,可给单个机器人附加私有网络。 +- overlay provider:如 Tailscale、NetBird,可给单个 Bot 附加私有网络。 不同后端能力不同: @@ -108,4 +108,4 @@ Local workspace 不提供同样的容器桌面隔离。工具层面的区别见 | `apple` | 基础本地 runtime | 不支持 | 不支持 | 有限 | | `local` | 宿主机网络 | 不支持 | 宿主机级别 | 无容器桌面 | -Overlay provider 在机器人界面里配置,不在全局 TOML 里配。全局 backend 仍然重要,因为它决定能跑哪类 overlay driver。 +Overlay provider 在 Bot 界面里配置,不在全局 TOML 里配。全局 backend 仍然重要,因为它决定能跑哪类 overlay driver。 diff --git a/docs/zh/tts-providers/index.md b/docs/zh/tts-providers/index.md index 170a155..fedcd9c 100644 --- a/docs/zh/tts-providers/index.md +++ b/docs/zh/tts-providers/index.md @@ -7,10 +7,10 @@ title: Redirecting import { onMounted } from 'vue' onMounted(() => { - window.location.replace('/zh/integrations/providers/tts/') + window.location.replace('/zh/integrations/providers/tts/edge') }) - + -Redirecting to [/zh/integrations/providers/tts/](/zh/integrations/providers/tts/). +Redirecting to [/zh/integrations/providers/tts/edge](/zh/integrations/providers/tts/edge). diff --git a/package.json b/package.json index ba985da..6f19bad 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ }, "devDependencies": { "vitepress": "^1.6.0", + "vitepress-plugin-llms": "^1.14.0", "vue": "^3.5.0" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ef7c738..f391992 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,12 +11,19 @@ importers: vitepress: specifier: ^1.6.0 version: 1.6.4(@algolia/client-search@5.53.0)(postcss@8.5.15)(search-insights@2.17.3) + vitepress-plugin-llms: + specifier: ^1.14.0 + version: 1.14.0 vue: specifier: ^3.5.0 version: 3.5.35 packages: + '@11ty/gray-matter@2.1.0': + resolution: {integrity: sha512-fNdBOb3MgDz/1UCIoeY4wDuGbp+/3s5y6UrsyfMabECbh/CVycj7Er33JXqSxRwxrRKXcGE1Jipuq/1mODInsQ==} + engines: {node: '>=11'} + '@algolia/abtesting@1.19.0': resolution: {integrity: sha512-Lhnez3hhXHk25lfxLAMxvkP4fmN3+1RgADhD2ssMDBYuAsDVReeyP+3SGRx+ntq8ijMrLqUyfvO72TB6jsTteQ==} engines: {node: '>= 14.0.0'} @@ -314,79 +321,66 @@ packages: resolution: {integrity: sha512-DxH0P3wxm+Yzs/p3zrk9dw1rURu8p0Nv5+MRK/L7OtnLNg5rLZraSBFZ8iUXOd9f2BlhJyEpIZUH/emjq4UJ4g==} cpu: [arm] os: [linux] - libc: [glibc] '@rollup/rollup-linux-arm-musleabihf@4.61.0': resolution: {integrity: sha512-T6ZvMNe84kAz6TBWHC7hGAoEtzP1LWYw/AqayGWEF6uISt3Abk/st06LqRD9THd7Xz3NxzurUpzAuEAUbZf+nw==} cpu: [arm] os: [linux] - libc: [musl] '@rollup/rollup-linux-arm64-gnu@4.61.0': resolution: {integrity: sha512-q/4hzvQkDs8b4jIBab1pnLiiM0ayTZsN2amBFPDzuyZxjEd4wDwx0UJFYM3cOZzSf5Kw8fnWSprJzIBMkcR44Q==} cpu: [arm64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-arm64-musl@4.61.0': resolution: {integrity: sha512-vvYWX3akdEAY6km+9wAqFDnk6pQsbJKVnj7xawcvs/+fdlYBGp+U+Qq/lLfpIxYIZvZLHMAKD9HLdacSx/r3dw==} cpu: [arm64] os: [linux] - libc: [musl] '@rollup/rollup-linux-loong64-gnu@4.61.0': resolution: {integrity: sha512-DePa5cqOxDP/Zp0VOXpeWaGew5iIv5DXp9NYbzkX5PFQyWVX9184WCTh3hvr/7lhXo8ZVlbFLkz8+o/q1dU6gA==} cpu: [loong64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-loong64-musl@4.61.0': resolution: {integrity: sha512-LV8aWMB8UChglMCEzs7RkN0GsH29RJaLLqwm9fCIjlqwxQTiWAqNcc7wjBkH31hV0PU/yVxGYvrYsgfea2qw6g==} cpu: [loong64] os: [linux] - libc: [musl] '@rollup/rollup-linux-ppc64-gnu@4.61.0': resolution: {integrity: sha512-QoNSnwQtaeNu5grdBbsL0tt1uyl5EnS8DA8Mr3nluMXbhdQNyhN+G4tBax7VCdxLKj8YJ0/4OO9Ho84jMnJtKA==} cpu: [ppc64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-ppc64-musl@4.61.0': resolution: {integrity: sha512-/zZp5MKapIIApE8trN8qLGNSiRN9TUoaUZ1cmVu4XnVdd5LQLOXTtyi+vtfUbNnT3iyjzpPqYeKXmvJ+gJGYWw==} cpu: [ppc64] os: [linux] - libc: [musl] '@rollup/rollup-linux-riscv64-gnu@4.61.0': resolution: {integrity: sha512-RbrzcD3aJ1k3UbtMRRBNwojdVVyXjuVAFTfn/xPa6EEl6GE9Sm/akPgFTb9aAC9pMKGJ6CtWxaGrqWcabH+ySg==} cpu: [riscv64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-riscv64-musl@4.61.0': resolution: {integrity: sha512-ZF+onDsBso8PJf1XaG9lB+O9RnBpKGnY6OrzC4CSHrtC1jb6jWLTKK4bRqdoCXHd22gyr2hiYmEAm8Wns/BOCw==} cpu: [riscv64] os: [linux] - libc: [musl] '@rollup/rollup-linux-s390x-gnu@4.61.0': resolution: {integrity: sha512-Atk0aSIk5Zx2Wuh9dgRQgLP0Koc8hOeYpbWryMXyk8G8/HmPkwPPkMqIIDhrXHHYqfUzSJA/I7IWSBv8xSmRBA==} cpu: [s390x] os: [linux] - libc: [glibc] '@rollup/rollup-linux-x64-gnu@4.61.0': resolution: {integrity: sha512-0uMOcf3eZ5K+K4cYHkdxShFMPlPXCOdfDFEFn9dNYAEEd2cVvmOfH7zFgRVoDgmtQ1m9k5q7qfrHzyMAubKYUA==} cpu: [x64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-x64-musl@4.61.0': resolution: {integrity: sha512-mvFtE4A/t/7hRJ7X8Ozmu8FsIkAUat2nzl12pgU337BRmq87AQUJztwHz2Zv5/tjo9/C95E66CK03SI/ToEDJw==} cpu: [x64] os: [linux] - libc: [musl] '@rollup/rollup-openbsd-x64@4.61.0': resolution: {integrity: sha512-z9b9+aTxvt8n2rNltMPvyaUfB8NJ+CVyOrGK/MdIKHx7B+lXmZpm/XbRsU7Rpf3fRqJ2uS6mBJiJveCtq8LHDg==} @@ -442,6 +436,9 @@ packages: '@shikijs/vscode-textmate@10.0.2': resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} + '@types/debug@4.1.13': + resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==} + '@types/estree@1.0.9': resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==} @@ -460,6 +457,9 @@ packages: '@types/mdurl@2.0.0': resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==} + '@types/ms@2.1.0': + resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==} + '@types/unist@3.0.3': resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} @@ -568,9 +568,31 @@ packages: resolution: {integrity: sha512-OGW1q6b91CRSSeiOnM8LxuR5NYJ2esvw66jUZ4IIvdv+ItNkx3pwLuyR+jaCdbGee4ov5WgUnyPryyh11xvByQ==} engines: {node: '>= 14.0.0'} + ansi-regex@5.0.1: + resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==} + engines: {node: '>=8'} + + ansi-styles@4.3.0: + resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==} + engines: {node: '>=8'} + + argparse@2.0.1: + resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} + + bail@2.0.2: + resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==} + + balanced-match@4.0.4: + resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==} + engines: {node: 18 || 20 || >=22} + birpc@2.9.0: resolution: {integrity: sha512-KrayHS5pBi69Xi9JmvoqrIgYGDkD6mcSe/i6YKi3w5kekCLzrX4+nawcXqrj2tIp50Kw/mT/s3p+GVK0A0sKxw==} + brace-expansion@5.0.12: + resolution: {integrity: sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==} + engines: {node: 20 || >=22} + ccount@2.0.1: resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==} @@ -580,6 +602,20 @@ packages: character-entities-legacy@3.0.0: resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==} + character-entities@2.0.2: + resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==} + + cliui@8.0.1: + resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==} + engines: {node: '>=12'} + + color-convert@2.0.1: + resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==} + engines: {node: '>=7.0.0'} + + color-name@1.1.4: + resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==} + comma-separated-tokens@2.0.3: resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==} @@ -590,6 +626,18 @@ packages: csstype@3.2.3: resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} + debug@4.4.3: + resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} + engines: {node: '>=6.0'} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + + decode-named-character-reference@1.3.0: + resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==} + dequal@2.0.3: resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==} engines: {node: '>=6'} @@ -600,6 +648,13 @@ packages: emoji-regex-xs@1.0.0: resolution: {integrity: sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==} + emoji-regex@8.0.0: + resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==} + + entities@4.5.0: + resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} + engines: {node: '>=0.12'} + entities@7.0.1: resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==} engines: {node: '>=0.12'} @@ -609,17 +664,43 @@ packages: engines: {node: '>=12'} hasBin: true + escalade@3.2.0: + resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} + engines: {node: '>=6'} + + escape-string-regexp@5.0.0: + resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==} + engines: {node: '>=12'} + estree-walker@2.0.2: resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==} + extend-shallow@2.0.1: + resolution: {integrity: sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==} + engines: {node: '>=0.10.0'} + + extend@3.0.2: + resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==} + + fault@2.0.1: + resolution: {integrity: sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==} + focus-trap@7.8.0: resolution: {integrity: sha512-/yNdlIkpWbM0ptxno3ONTuf+2g318kh2ez3KSeZN5dZ8YC6AAmgeWz+GasYYiBJPFaYcSAPeu4GfhUaChzIJXA==} + format@0.2.2: + resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==} + engines: {node: '>=0.4.x'} + fsevents@2.3.3: resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} os: [darwin] + get-caller-file@2.0.5: + resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==} + engines: {node: 6.* || 8.* || >= 10.*} + hast-util-to-html@9.0.5: resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==} @@ -632,40 +713,154 @@ packages: html-void-elements@3.0.0: resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} + is-extendable@0.1.1: + resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==} + engines: {node: '>=0.10.0'} + + is-fullwidth-code-point@3.0.0: + resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==} + engines: {node: '>=8'} + + is-plain-obj@4.1.0: + resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==} + engines: {node: '>=12'} + is-what@5.5.0: resolution: {integrity: sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==} engines: {node: '>=18'} + js-yaml@4.3.2: + resolution: {integrity: sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==} + hasBin: true + + kind-of@6.0.3: + resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==} + engines: {node: '>=0.10.0'} + + linkify-it@5.0.2: + resolution: {integrity: sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==} + + longest-streak@3.1.0: + resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==} + magic-string@0.30.21: resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==} mark.js@8.11.1: resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} + markdown-it@14.3.2: + resolution: {integrity: sha512-sHHjZ5fJKlgrG4qns2YwVcdNep35h5fERrfkD2YNsb9UFk0UIHarbiTaHKVMlPuWAoiilyK8Fv/jAm11slsY7Q==} + hasBin: true + + markdown-title@1.0.2: + resolution: {integrity: sha512-MqIQVVkz+uGEHi3TsHx/czcxxCbRIL7sv5K5DnYw/tI+apY54IbPefV/cmgxp6LoJSEx/TqcHdLs/298afG5QQ==} + engines: {node: '>=6'} + + mdast-util-from-markdown@2.0.3: + resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==} + + mdast-util-frontmatter@2.0.1: + resolution: {integrity: sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==} + + mdast-util-phrasing@4.1.0: + resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==} + mdast-util-to-hast@13.2.1: resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==} + mdast-util-to-markdown@2.1.2: + resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==} + + mdast-util-to-string@4.0.0: + resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==} + + mdurl@2.1.0: + resolution: {integrity: sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==} + + micromark-core-commonmark@2.0.3: + resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==} + + micromark-extension-frontmatter@2.0.0: + resolution: {integrity: sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==} + + micromark-factory-destination@2.0.1: + resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==} + + micromark-factory-label@2.0.1: + resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==} + + micromark-factory-space@2.0.1: + resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==} + + micromark-factory-title@2.0.1: + resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==} + + micromark-factory-whitespace@2.0.1: + resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==} + micromark-util-character@2.1.1: resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==} + micromark-util-chunked@2.0.1: + resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==} + + micromark-util-classify-character@2.0.1: + resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==} + + micromark-util-combine-extensions@2.0.1: + resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==} + + micromark-util-decode-numeric-character-reference@2.0.2: + resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==} + + micromark-util-decode-string@2.0.1: + resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==} + micromark-util-encode@2.0.1: resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==} + micromark-util-html-tag-name@2.0.1: + resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==} + + micromark-util-normalize-identifier@2.0.1: + resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==} + + micromark-util-resolve-all@2.0.1: + resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==} + micromark-util-sanitize-uri@2.0.1: resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==} + micromark-util-subtokenize@2.1.0: + resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==} + micromark-util-symbol@2.0.1: resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==} micromark-util-types@2.0.2: resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==} + micromark@4.0.2: + resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==} + + millify@6.1.0: + resolution: {integrity: sha512-H/E3J6t+DQs/F2YgfDhxUVZz/dF8JXPPKTLHL/yHCcLZLtCXJDUaqvhJXQwqOVBvbyNn4T0WjLpIHd7PAw7fBA==} + hasBin: true + + minimatch@10.2.6: + resolution: {integrity: sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==} + engines: {node: 18 || 20 || >=22} + minisearch@7.2.0: resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==} mitt@3.0.1: resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==} + ms@2.1.3: + resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} + nanoid@3.3.12: resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==} engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} @@ -674,6 +869,9 @@ packages: oniguruma-to-es@3.1.1: resolution: {integrity: sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ==} + path-to-regexp@6.3.0: + resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==} + perfect-debounce@1.0.0: resolution: {integrity: sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA==} @@ -687,9 +885,17 @@ packages: preact@10.29.2: resolution: {integrity: sha512-7tNmwg/7mzzAoB/8kSg6Hl37JraAZw3Z3A0JSY7VXlZwo82Xn0G7wKbNNs2qoF4ZEEsQGTwDAroNdqKs1ofJxQ==} + pretty-bytes@7.1.3: + resolution: {integrity: sha512-U2KZ675nqba6XSBppSjU2pRgc9Ffx9+uUtd/RTWYmOawVkZuUbBYuwdtFZQmLv+yMgQ2TQxWWuOpyNje67J9tg==} + engines: {node: '>=20'} + property-information@7.2.0: resolution: {integrity: sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==} + punycode.js@2.3.1: + resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} + engines: {node: '>=6'} + regex-recursion@6.0.2: resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==} @@ -699,6 +905,22 @@ packages: regex@6.1.0: resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==} + remark-frontmatter@5.0.0: + resolution: {integrity: sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==} + + remark-parse@11.0.0: + resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==} + + remark-stringify@11.0.0: + resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==} + + remark@15.0.1: + resolution: {integrity: sha512-Eht5w30ruCXgFmxVUSlNWQ9iiimq07URKeFS3hNc8cUWy1llX4KDWfyEDZRycMc+znsN9Ux5/tJ/BFdgdOwA3A==} + + require-directory@2.1.1: + resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==} + engines: {node: '>=0.10.0'} + rfdc@1.4.1: resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==} @@ -710,6 +932,10 @@ packages: search-insights@2.17.3: resolution: {integrity: sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ==} + section-matter@1.0.0: + resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==} + engines: {node: '>=4'} + shiki@2.5.0: resolution: {integrity: sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ==} @@ -724,9 +950,17 @@ packages: resolution: {integrity: sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==} engines: {node: '>=0.10.0'} + string-width@4.2.3: + resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==} + engines: {node: '>=8'} + stringify-entities@4.0.4: resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==} + strip-ansi@6.0.1: + resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==} + engines: {node: '>=8'} + superjson@2.2.6: resolution: {integrity: sha512-H+ue8Zo4vJmV2nRjpx86P35lzwDT3nItnIsocgumgr0hHMQ+ZGq5vrERg9kJBo5AWGmxZDhzDo+WVIJqkB0cGA==} engines: {node: '>=16'} @@ -734,15 +968,30 @@ packages: tabbable@6.4.0: resolution: {integrity: sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg==} + tokenx@1.6.0: + resolution: {integrity: sha512-CKTjk345ajvBAUp5xUI9a5KKN0zU0lBueVHQbCskH1Hp6WkUKsPW2qGCYNs0pxNyfzxfo+IIjdt2W4sMbw/qBw==} + trim-lines@3.0.1: resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==} + trough@2.2.0: + resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==} + + uc.micro@2.1.0: + resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} + + unified@11.0.5: + resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==} + unist-util-is@6.0.1: resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==} unist-util-position@5.0.0: resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==} + unist-util-remove@4.0.0: + resolution: {integrity: sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg==} + unist-util-stringify-position@4.0.0: resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==} @@ -789,6 +1038,10 @@ packages: terser: optional: true + vitepress-plugin-llms@1.14.0: + resolution: {integrity: sha512-Qb42p9pYoRlMRbv+Yvh3reS4GInyr+ToU3G1tEC1Euz+gyBNywXkZIQPV/AoltizaakAeuI89Bkhkd7Y0jaM/w==} + engines: {node: '>=18'} + vitepress@1.6.4: resolution: {integrity: sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg==} hasBin: true @@ -809,11 +1062,32 @@ packages: typescript: optional: true + wrap-ansi@7.0.0: + resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==} + engines: {node: '>=10'} + + y18n@5.0.8: + resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==} + engines: {node: '>=10'} + + yargs-parser@21.1.1: + resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==} + engines: {node: '>=12'} + + yargs@17.7.3: + resolution: {integrity: sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==} + engines: {node: '>=12'} + zwitch@2.0.4: resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==} snapshots: + '@11ty/gray-matter@2.1.0': + dependencies: + js-yaml: 4.3.2 + section-matter: 1.0.0 + '@algolia/abtesting@1.19.0': dependencies: '@algolia/client-common': 5.53.0 @@ -1155,6 +1429,10 @@ snapshots: '@shikijs/vscode-textmate@10.0.2': {} + '@types/debug@4.1.13': + dependencies: + '@types/ms': 2.1.0 + '@types/estree@1.0.9': {} '@types/hast@3.0.4': @@ -1174,6 +1452,8 @@ snapshots: '@types/mdurl@2.0.0': {} + '@types/ms@2.1.0': {} + '@types/unist@3.0.3': {} '@types/web-bluetooth@0.0.21': {} @@ -1301,14 +1581,44 @@ snapshots: '@algolia/requester-fetch': 5.53.0 '@algolia/requester-node-http': 5.53.0 + ansi-regex@5.0.1: {} + + ansi-styles@4.3.0: + dependencies: + color-convert: 2.0.1 + + argparse@2.0.1: {} + + bail@2.0.2: {} + + balanced-match@4.0.4: {} + birpc@2.9.0: {} + brace-expansion@5.0.12: + dependencies: + balanced-match: 4.0.4 + ccount@2.0.1: {} character-entities-html4@2.1.0: {} character-entities-legacy@3.0.0: {} + character-entities@2.0.2: {} + + cliui@8.0.1: + dependencies: + string-width: 4.2.3 + strip-ansi: 6.0.1 + wrap-ansi: 7.0.0 + + color-convert@2.0.1: + dependencies: + color-name: 1.1.4 + + color-name@1.1.4: {} + comma-separated-tokens@2.0.3: {} copy-anything@4.0.5: @@ -1317,6 +1627,14 @@ snapshots: csstype@3.2.3: {} + debug@4.4.3: + dependencies: + ms: 2.1.3 + + decode-named-character-reference@1.3.0: + dependencies: + character-entities: 2.0.2 + dequal@2.0.3: {} devlop@1.1.0: @@ -1325,6 +1643,10 @@ snapshots: emoji-regex-xs@1.0.0: {} + emoji-regex@8.0.0: {} + + entities@4.5.0: {} + entities@7.0.1: {} esbuild@0.21.5: @@ -1353,15 +1675,33 @@ snapshots: '@esbuild/win32-ia32': 0.21.5 '@esbuild/win32-x64': 0.21.5 + escalade@3.2.0: {} + + escape-string-regexp@5.0.0: {} + estree-walker@2.0.2: {} + extend-shallow@2.0.1: + dependencies: + is-extendable: 0.1.1 + + extend@3.0.2: {} + + fault@2.0.1: + dependencies: + format: 0.2.2 + focus-trap@7.8.0: dependencies: tabbable: 6.4.0 + format@0.2.2: {} + fsevents@2.3.3: optional: true + get-caller-file@2.0.5: {} + hast-util-to-html@9.0.5: dependencies: '@types/hast': 3.0.4 @@ -1384,14 +1724,76 @@ snapshots: html-void-elements@3.0.0: {} + is-extendable@0.1.1: {} + + is-fullwidth-code-point@3.0.0: {} + + is-plain-obj@4.1.0: {} + is-what@5.5.0: {} + js-yaml@4.3.2: + dependencies: + argparse: 2.0.1 + + kind-of@6.0.3: {} + + linkify-it@5.0.2: + dependencies: + uc.micro: 2.1.0 + + longest-streak@3.1.0: {} + magic-string@0.30.21: dependencies: '@jridgewell/sourcemap-codec': 1.5.5 mark.js@8.11.1: {} + markdown-it@14.3.2: + dependencies: + argparse: 2.0.1 + entities: 4.5.0 + linkify-it: 5.0.2 + mdurl: 2.1.0 + punycode.js: 2.3.1 + uc.micro: 2.1.0 + + markdown-title@1.0.2: {} + + mdast-util-from-markdown@2.0.3: + dependencies: + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + decode-named-character-reference: 1.3.0 + devlop: 1.1.0 + mdast-util-to-string: 4.0.0 + micromark: 4.0.2 + micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-decode-string: 2.0.1 + micromark-util-normalize-identifier: 2.0.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + unist-util-stringify-position: 4.0.0 + transitivePeerDependencies: + - supports-color + + mdast-util-frontmatter@2.0.1: + dependencies: + '@types/mdast': 4.0.4 + devlop: 1.1.0 + escape-string-regexp: 5.0.0 + mdast-util-from-markdown: 2.0.3 + mdast-util-to-markdown: 2.1.2 + micromark-extension-frontmatter: 2.0.0 + transitivePeerDependencies: + - supports-color + + mdast-util-phrasing@4.1.0: + dependencies: + '@types/mdast': 4.0.4 + unist-util-is: 6.0.1 + mdast-util-to-hast@13.2.1: dependencies: '@types/hast': 3.0.4 @@ -1404,27 +1806,178 @@ snapshots: unist-util-visit: 5.1.0 vfile: 6.0.3 + mdast-util-to-markdown@2.1.2: + dependencies: + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + longest-streak: 3.1.0 + mdast-util-phrasing: 4.1.0 + mdast-util-to-string: 4.0.0 + micromark-util-classify-character: 2.0.1 + micromark-util-decode-string: 2.0.1 + unist-util-visit: 5.1.0 + zwitch: 2.0.4 + + mdast-util-to-string@4.0.0: + dependencies: + '@types/mdast': 4.0.4 + + mdurl@2.1.0: {} + + micromark-core-commonmark@2.0.3: + dependencies: + decode-named-character-reference: 1.3.0 + devlop: 1.1.0 + micromark-factory-destination: 2.0.1 + micromark-factory-label: 2.0.1 + micromark-factory-space: 2.0.1 + micromark-factory-title: 2.0.1 + micromark-factory-whitespace: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-chunked: 2.0.1 + micromark-util-classify-character: 2.0.1 + micromark-util-html-tag-name: 2.0.1 + micromark-util-normalize-identifier: 2.0.1 + micromark-util-resolve-all: 2.0.1 + micromark-util-subtokenize: 2.1.0 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-extension-frontmatter@2.0.0: + dependencies: + fault: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-factory-destination@2.0.1: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-factory-label@2.0.1: + dependencies: + devlop: 1.1.0 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-factory-space@2.0.1: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-types: 2.0.2 + + micromark-factory-title@2.0.1: + dependencies: + micromark-factory-space: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-factory-whitespace@2.0.1: + dependencies: + micromark-factory-space: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + micromark-util-character@2.1.1: dependencies: micromark-util-symbol: 2.0.1 micromark-util-types: 2.0.2 + micromark-util-chunked@2.0.1: + dependencies: + micromark-util-symbol: 2.0.1 + + micromark-util-classify-character@2.0.1: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-util-combine-extensions@2.0.1: + dependencies: + micromark-util-chunked: 2.0.1 + micromark-util-types: 2.0.2 + + micromark-util-decode-numeric-character-reference@2.0.2: + dependencies: + micromark-util-symbol: 2.0.1 + + micromark-util-decode-string@2.0.1: + dependencies: + decode-named-character-reference: 1.3.0 + micromark-util-character: 2.1.1 + micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-symbol: 2.0.1 + micromark-util-encode@2.0.1: {} + micromark-util-html-tag-name@2.0.1: {} + + micromark-util-normalize-identifier@2.0.1: + dependencies: + micromark-util-symbol: 2.0.1 + + micromark-util-resolve-all@2.0.1: + dependencies: + micromark-util-types: 2.0.2 + micromark-util-sanitize-uri@2.0.1: dependencies: micromark-util-character: 2.1.1 micromark-util-encode: 2.0.1 micromark-util-symbol: 2.0.1 + micromark-util-subtokenize@2.1.0: + dependencies: + devlop: 1.1.0 + micromark-util-chunked: 2.0.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + micromark-util-symbol@2.0.1: {} micromark-util-types@2.0.2: {} + micromark@4.0.2: + dependencies: + '@types/debug': 4.1.13 + debug: 4.4.3 + decode-named-character-reference: 1.3.0 + devlop: 1.1.0 + micromark-core-commonmark: 2.0.3 + micromark-factory-space: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-chunked: 2.0.1 + micromark-util-combine-extensions: 2.0.1 + micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-encode: 2.0.1 + micromark-util-normalize-identifier: 2.0.1 + micromark-util-resolve-all: 2.0.1 + micromark-util-sanitize-uri: 2.0.1 + micromark-util-subtokenize: 2.1.0 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + transitivePeerDependencies: + - supports-color + + millify@6.1.0: + dependencies: + yargs: 17.7.3 + + minimatch@10.2.6: + dependencies: + brace-expansion: 5.0.12 + minisearch@7.2.0: {} mitt@3.0.1: {} + ms@2.1.3: {} + nanoid@3.3.12: {} oniguruma-to-es@3.1.1: @@ -1433,6 +1986,8 @@ snapshots: regex: 6.1.0 regex-recursion: 6.0.2 + path-to-regexp@6.3.0: {} + perfect-debounce@1.0.0: {} picocolors@1.1.1: {} @@ -1445,8 +2000,12 @@ snapshots: preact@10.29.2: {} + pretty-bytes@7.1.3: {} + property-information@7.2.0: {} + punycode.js@2.3.1: {} + regex-recursion@6.0.2: dependencies: regex-utilities: 2.3.0 @@ -1457,6 +2016,41 @@ snapshots: dependencies: regex-utilities: 2.3.0 + remark-frontmatter@5.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-frontmatter: 2.0.1 + micromark-extension-frontmatter: 2.0.0 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + + remark-parse@11.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-from-markdown: 2.0.3 + micromark-util-types: 2.0.2 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + + remark-stringify@11.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-to-markdown: 2.1.2 + unified: 11.0.5 + + remark@15.0.1: + dependencies: + '@types/mdast': 4.0.4 + remark-parse: 11.0.0 + remark-stringify: 11.0.0 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + + require-directory@2.1.1: {} + rfdc@1.4.1: {} rollup@4.61.0: @@ -1492,6 +2086,11 @@ snapshots: search-insights@2.17.3: {} + section-matter@1.0.0: + dependencies: + extend-shallow: 2.0.1 + kind-of: 6.0.3 + shiki@2.5.0: dependencies: '@shikijs/core': 2.5.0 @@ -1509,19 +2108,45 @@ snapshots: speakingurl@14.0.1: {} + string-width@4.2.3: + dependencies: + emoji-regex: 8.0.0 + is-fullwidth-code-point: 3.0.0 + strip-ansi: 6.0.1 + stringify-entities@4.0.4: dependencies: character-entities-html4: 2.1.0 character-entities-legacy: 3.0.0 + strip-ansi@6.0.1: + dependencies: + ansi-regex: 5.0.1 + superjson@2.2.6: dependencies: copy-anything: 4.0.5 tabbable@6.4.0: {} + tokenx@1.6.0: {} + trim-lines@3.0.1: {} + trough@2.2.0: {} + + uc.micro@2.1.0: {} + + unified@11.0.5: + dependencies: + '@types/unist': 3.0.3 + bail: 2.0.2 + devlop: 1.1.0 + extend: 3.0.2 + is-plain-obj: 4.1.0 + trough: 2.2.0 + vfile: 6.0.3 + unist-util-is@6.0.1: dependencies: '@types/unist': 3.0.3 @@ -1530,6 +2155,12 @@ snapshots: dependencies: '@types/unist': 3.0.3 + unist-util-remove@4.0.0: + dependencies: + '@types/unist': 3.0.3 + unist-util-is: 6.0.1 + unist-util-visit-parents: 6.0.2 + unist-util-stringify-position@4.0.0: dependencies: '@types/unist': 3.0.3 @@ -1563,6 +2194,25 @@ snapshots: optionalDependencies: fsevents: 2.3.3 + vitepress-plugin-llms@1.14.0: + dependencies: + '@11ty/gray-matter': 2.1.0 + markdown-it: 14.3.2 + markdown-title: 1.0.2 + mdast-util-from-markdown: 2.0.3 + millify: 6.1.0 + minimatch: 10.2.6 + path-to-regexp: 6.3.0 + picocolors: 1.1.1 + pretty-bytes: 7.1.3 + remark: 15.0.1 + remark-frontmatter: 5.0.0 + tokenx: 1.6.0 + unist-util-remove: 4.0.0 + unist-util-visit: 5.1.0 + transitivePeerDependencies: + - supports-color + vitepress@1.6.4(@algolia/client-search@5.53.0)(postcss@8.5.15)(search-insights@2.17.3): dependencies: '@docsearch/css': 3.8.2 @@ -1620,4 +2270,24 @@ snapshots: '@vue/server-renderer': 3.5.35(vue@3.5.35) '@vue/shared': 3.5.35 + wrap-ansi@7.0.0: + dependencies: + ansi-styles: 4.3.0 + string-width: 4.2.3 + strip-ansi: 6.0.1 + + y18n@5.0.8: {} + + yargs-parser@21.1.1: {} + + yargs@17.7.3: + dependencies: + cliui: 8.0.1 + escalade: 3.2.0 + get-caller-file: 2.0.5 + require-directory: 2.1.1 + string-width: 4.2.3 + y18n: 5.0.8 + yargs-parser: 21.1.1 + zwitch@2.0.4: {} diff --git a/scripts/check-locale-parity.mjs b/scripts/check-locale-parity.mjs new file mode 100644 index 0000000..f2c0748 --- /dev/null +++ b/scripts/check-locale-parity.mjs @@ -0,0 +1,146 @@ +#!/usr/bin/env node +/** + * check-locale-parity.mjs — en/zh docs parity checker. Dependency-free. + * + * Checks two things: + * 1. Page tree — every *.md under docs/ (excluding docs/zh, docs/public, + * docs/.vitepress) has a mirror at docs/zh/, and vice versa. + * 2. Sidebars — docs/.vitepress/en.ts and zh.ts link the same multiset of + * paths once the /zh prefix is stripped from the zh side. + * + * Exits 1 on any mismatch, 0 otherwise. + * Run from anywhere: paths are resolved relative to this script. + */ + +import { readdirSync, readFileSync, existsSync } from 'node:fs' +import { dirname, join, relative, sep } from 'node:path' +import { fileURLToPath } from 'node:url' + +const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..') +const docsDir = join(repoRoot, 'docs') +const zhDir = join(docsDir, 'zh') + +const EN_EXCLUDED_TOP_DIRS = new Set(['zh', 'public', '.vitepress']) + +/** Recursively collect *.md paths under `dir`, POSIX-relative to `base`. */ +function listMarkdown(dir, base, isExcluded) { + const out = [] + for (const entry of readdirSync(dir, { withFileTypes: true })) { + const full = join(dir, entry.name) + const rel = relative(base, full).split(sep).join('/') + if (isExcluded && isExcluded(rel)) continue + if (entry.isDirectory()) { + out.push(...listMarkdown(full, base, isExcluded)) + } else if (entry.isFile() && entry.name.endsWith('.md')) { + out.push(rel) + } + } + return out.sort() +} + +/** Extract every `link: '...'` value from a VitePress locale config, in order. */ +function extractSidebarLinks(source) { + const links = [] + const re = /\blink:\s*(['"`])([^'"`]*)\1/g + let m + while ((m = re.exec(source)) !== null) links.push(m[2]) + return links +} + +/** Strip a leading /zh locale prefix: /zh/guides/x.md -> /guides/x.md */ +function stripZhPrefix(link) { + return link.replace(/^\/zh(?=\/|$)/, '') || '/' +} + +/** Array -> Map of value -> occurrence count. */ +function toMultiset(items) { + const counts = new Map() + for (const item of items) counts.set(item, (counts.get(item) ?? 0) + 1) + return counts +} + +let failures = 0 + +function reportGroup(title, lines) { + if (lines.length === 0) return + failures += lines.length + console.log(` ${title}:`) + for (const line of lines) console.log(` - ${line}`) +} + +// --------------------------------------------------------------------------- +// 1. Page tree parity +// --------------------------------------------------------------------------- + +console.log('Locale parity check: docs/ (en) <-> docs/zh/ (zh)') +console.log('') +console.log('[1/2] Markdown page tree') + +const enPages = listMarkdown(docsDir, docsDir, (rel) => EN_EXCLUDED_TOP_DIRS.has(rel)) +const zhPages = existsSync(zhDir) ? listMarkdown(zhDir, zhDir) : [] +const enSet = new Set(enPages) +const zhSet = new Set(zhPages) + +console.log(` en pages: ${enPages.length} zh pages: ${zhPages.length}`) + +reportGroup( + 'Missing zh mirror (en page exists, zh twin does not)', + enPages.filter((p) => !zhSet.has(p)).map((p) => `docs/${p} -> expected docs/zh/${p}`), +) +reportGroup( + 'Missing en source (zh page exists, en twin does not)', + zhPages.filter((p) => !enSet.has(p)).map((p) => `docs/zh/${p} -> expected docs/${p}`), +) +if (enPages.every((p) => zhSet.has(p)) && zhPages.every((p) => enSet.has(p))) { + console.log(' OK: every page is mirrored in both locales.') +} + +// --------------------------------------------------------------------------- +// 2. Sidebar link parity +// --------------------------------------------------------------------------- + +console.log('') +console.log('[2/2] Sidebar links: docs/.vitepress/en.ts <-> docs/.vitepress/zh.ts') + +const enConfigPath = join(docsDir, '.vitepress', 'en.ts') +const zhConfigPath = join(docsDir, '.vitepress', 'zh.ts') + +const missingConfigs = [enConfigPath, zhConfigPath].filter((p) => !existsSync(p)) +if (missingConfigs.length > 0) { + for (const p of missingConfigs) console.log(` ERROR: config not found: ${relative(repoRoot, p)}`) + failures += missingConfigs.length +} else { + const enLinks = extractSidebarLinks(readFileSync(enConfigPath, 'utf8')) + const zhLinks = extractSidebarLinks(readFileSync(zhConfigPath, 'utf8')).map(stripZhPrefix) + + console.log(` en links: ${enLinks.length} zh links: ${zhLinks.length}`) + + const enCounts = toMultiset(enLinks) + const zhCounts = toMultiset(zhLinks) + const allLinks = [...new Set([...enCounts.keys(), ...zhCounts.keys()])].sort() + + const onlyEn = [] + const onlyZh = [] + for (const link of allLinks) { + const inEn = enCounts.get(link) ?? 0 + const inZh = zhCounts.get(link) ?? 0 + if (inEn > inZh) onlyEn.push(inZh === 0 ? link : `${link} (${inEn}x in en.ts, ${inZh}x in zh.ts)`) + if (inZh > inEn) onlyZh.push(inEn === 0 ? link : `${link} (${inZh}x in zh.ts, ${inEn}x in en.ts)`) + } + + reportGroup('Linked in en.ts but not in zh.ts (zh path shown without /zh prefix)', onlyEn) + reportGroup('Linked in zh.ts but not in en.ts (shown without /zh prefix)', onlyZh) + if (onlyEn.length === 0 && onlyZh.length === 0) { + console.log(' OK: both sidebars link the same set of pages.') + } +} + +// --------------------------------------------------------------------------- + +console.log('') +if (failures > 0) { + console.log(`FAIL: ${failures} parity mismatch${failures === 1 ? '' : 'es'}. en is the source of truth; every content PR must update both locales.`) + process.exit(1) +} +console.log('PASS: en and zh locales are in parity.') +process.exit(0)