mirror of
https://github.com/multica-ai/multica.git
synced 2026-08-12 19:06:06 +02:00
32740d0ee3
* fix(landing): align ZH copy with conventions and update tool list to 11 - Replace "Agent" with "智能体" in ZH marketing copy (lines 1-275) per conventions.zh.mdx — landing was the only surface still using "Agent" while UI, docs, and locales already use "智能体". Changelog-section technical names (Agent SDK / Agent runtime / Cursor Agent) preserved. - Replace the 4-tool list (Claude Code / Codex / OpenClaw / OpenCode) with the actual 11 supported tools across hero card, how-it-works step, and FAQ — this matches daemon-runtimes.mdx and the file's own changelog entries that already record the rollout of Cursor, Copilot, Gemini, Hermes, Kimi, Kiro CLI, and Pi. - Drop the "plug in and go" line; replace with an honest sentence about multica setup walking through OAuth + daemon start. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(i18n): correct daemon/runtime drift across modals, onboarding, docs - modals/zh-Hans: 4 places used "daemon" untranslated; conventions.zh.mdx rules Daemon -> 守护进程. Aligned. - onboarding/zh-Hans: line "把任务交给它们" was the only spot using "任务" for the task entity; rest of the file already uses lowercase "task" per conventions. Aligned. - onboarding (en + zh-Hans) runtime_aside.what_suffix: said runtime IS a background process. daemon-runtimes.mdx defines runtime = daemon × one AI coding tool (one machine + N tools = N runtimes). Replaced with the correct definition so new users form the right mental model on first contact. - onboarding (en + zh-Hans) step_platform headline+lede: said "Connect a runtime" but the next options are "install desktop / CLI / cloud waitlist" — those install a runtime source, not connect to one. Reworded. - onboarding/zh-Hans: 4 places used "AI 编码工具"; docs use "AI 编程工具" consistently. Unified on the docs term. - daemon-runtimes (en + zh): added cross-link to /desktop-app for users deciding between desktop daemon and CLI daemon. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(onboarding): localize starter-content (Getting Started project) The Getting Started project + welcome issue + 10 sub-issues that land in the workspace at the end of onboarding were hardcoded English. Chinese users finished a Chinese onboarding flow and arrived to an all-English workspace; the welcome issue's prompt to the agent was also English, so the agent's first reply tended to be English regardless of what templates the user picked. This commit adds Chinese parity, fixes the runtime definition error that was the source of similar drift in onboarding.json, and removes a few hardcoded UI specifics that would silently rot. Architecture: - Long-form markdown (~600 lines per language) lives in TS sibling files: starter-content-content-en.ts and starter-content-content-zh.ts. JSON locales were considered, but multi-paragraph markdown becomes unreadable single-line escape soup in JSON; keeping it in TS lets reviewers see the rendered shape and catch markdown regressions in code review. - starter-content-templates.ts is now a thin orchestrator: imports both content files, exports buildImportPayload({ ..., locale }), picks the right one at runtime. - StarterContentPrompt resolves locale from i18n.language (with a small startsWith("zh") helper so "zh-Hans-CN" or future variants still hit the ZH content). Content fixes (apply to both EN and ZH): - "A runtime is a small background process" was wrong (runtime = daemon × one AI coding tool, per docs). Replaced with the correct definition so the welcome agent doesn't seed an incorrect mental model. - Removed hardcoded "tabs at the top: 6 tabs" / "(third row)" / "6 templates" lists — those rot the moment product UI changes. Replaced with descriptions that don't depend on exact counts/positions. Conventions adherence (ZH): - agent → 智能体, daemon → 守护进程, runtime → 运行时, workspace → 工作区 - task / issue / skill stay lowercase English (per conventions.zh.mdx) - Product UI labels (Properties, Assignee, Status, Activity, Live card, Inbox, Members, Settings, Runtimes, Configure, Repositories, Instructions, Tasks, Skills, Autopilot, etc.) stay English so the doc text matches what the user sees on screen. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(conventions): formalize mixed-rule for task / issue / skill in CN The prior rule said issue/skill/task always render as lowercase English in Chinese text. That worked for UI strings but never matched what the sister docs actually do — tasks.zh.mdx is built around "执行任务", issues.zh.mdx titles "Issue 与 project", skills.zh.mdx titles "Skills". Three docs, three patterns, all sensible in their own context, none matching the old rule. Conventions also explicitly cited the docs as the voice standard, so the rule was internally inconsistent. This commit promotes the de facto pattern to a written rule: - UI strings, state names, code references → lowercase English ("排队中的 task", "创建子 issue", "为智能体注入 skill") - Doc titles / section headings → Title-case English OR Chinese term ("Issue 与 project", "Skills", "执行任务") - Doc prose where the entity is the running subject → Chinese term, with English in parentheses on first mention ("**执行任务**（task）是智能体每一次工作的单位") - API / DB fields → always task / issue / skill (`task_id`, etc.) Provides the term mapping (task ↔ 执行任务) explicitly so future translation PRs don't have to rediscover it. No code or other doc changes — tasks.zh.mdx already follows this pattern; this commit just formalizes it. Other ZH locale strings remain lowercase per the UI rule (which the locale audit + PR #2139 verified). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: add Projects page (en + zh) and Autopilot failure visibility note The audit found that 'projects' was the most prominently missing docs page — it appears as a sidebar nav item in onboarding's workspace preview, but users clicking through to docs found nothing on the topic. The other locale-but-no-doc pages (my-issues, labels, settings) are listed as follow-ups; this PR ships the highest-impact one. Also adds a missing piece in tasks.{mdx,zh.mdx}: the Autopilot no-auto-retry callout explained the *why* but never the *how do I notice* — added a sentence pointing users at Inbox + the issue status revert + the Autopilot page's run history. projects.mdx covers: - What a project is (container for related issues) - Fields: name, icon, description, lead, status, priority, progress - Project-issue many-to-one relationship + how progress is computed - Pinning to sidebar (personal preference) - Resources section (GitHub repos passed to daemon) - Delete behavior (issues unlinked, not deleted) - Lead can be a member or an agent Both pages registered in meta.json / meta.zh.json under "Workspace & team" group, between issues and comments. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(pr-template): add drift-prevention checkboxes for runtime/CN copy Two failure modes the docs+onboarding audit found, both caused by adding-a-thing without remembering all the places that thing surfaces: 1. New runtime / coding tool / UI tab gets recorded in changelog but not in landing FAQ ("Multica supports 4 tools" while changelog shows the 11th was added) or starter-content tutorial ("6 tabs at the top: Instructions / Skills / Tasks / Environment / Custom Args / Settings" stays frozen the moment a tab is added or renamed). 2. Chinese copy added without checking the canonical glossary — "Agent" survived in landing/zh.ts long after product UI standardized on "智能体" because nobody routed landing through the conventions review. Adding two checklist items to the PR template so authors see the specific paths to update at PR-creation time, before the drift ships. This is the final batch (5 / 5) from the audit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
112 lines
6.1 KiB
Plaintext
112 lines
6.1 KiB
Plaintext
---
|
||
title: 守护进程与运行时
|
||
description: 智能体不在 Multica 服务器上运行——它们跑在你自己的机器上。
|
||
---
|
||
|
||
import { Callout } from "fumadocs-ui/components/callout";
|
||
import { Mermaid } from "@/components/mermaid";
|
||
|
||
在 Multica 里，[智能体](/agents) **不**在我们的服务器上运行——它们跑在你自己的机器上，由一个叫**守护进程**（daemon）的小程序调用本地安装的 [AI 编程工具](/providers)。Multica 服务器只做协调：存 [issue](/issues)、排 [任务](/tasks)、派发给正确的**运行时**（runtime = 守护进程 × 一款 AI 编程工具）。
|
||
|
||
这个结构带来 Multica 和 Linear / Jira 最大的差别：**你的 API 密钥、工具链、代码目录都留在本地**，Multica 服务器一个都看不到。"我的智能体不工作"类问题几乎都是本地问题——守护进程没启动、某款 AI 工具没装、密钥过期——请先从本地查起；定位指引见 [故障排查](/troubleshooting)。
|
||
|
||
## 启动守护进程
|
||
|
||
守护进程是 Multica CLI 的一部分。装好 [Multica CLI](/cli) 后，在自己机器上跑：
|
||
|
||
```bash
|
||
multica daemon start
|
||
```
|
||
|
||
启动后它会做四件事：
|
||
|
||
1. 读取你登录时保存的凭证
|
||
2. 探测本机 `PATH` 上已安装的 AI 编程工具（内置支持 11 款：[Claude Code](/providers#claude-code)、[Codex](/providers#codex)、[Cursor](/providers#cursor)、[Copilot](/providers#copilot)、[Gemini](/providers#gemini)、[Hermes](/providers#hermes)、[Kimi](/providers#kimi)、[Kiro CLI](/providers#kiro-cli)、[OpenCode](/providers#opencode)、[OpenClaw](/providers#openclaw)、[Pi](/providers#pi)）
|
||
3. 向服务器注册自己，以及每款检测到的工具对应的运行时
|
||
4. 持续**每 3 秒轮询一次**是否有任务要领，**每 15 秒发一次心跳**
|
||
|
||
常用命令：
|
||
|
||
| 命令 | 作用 |
|
||
|---|---|
|
||
| `multica daemon start` | 启动（默认后台，加 `--foreground` 前台运行）|
|
||
| `multica daemon stop` | 停止 |
|
||
| `multica daemon restart` | 重启 |
|
||
| `multica daemon status` | 查看状态 |
|
||
| `multica daemon logs` | 查看日志（加 `-f` 跟随）|
|
||
|
||
完整 CLI 参考见 [CLI 命令速查](/cli)。
|
||
|
||
**桌面应用自带守护进程。**用 [桌面应用](/desktop-app) 就不必手动 `multica daemon start`——它启动时会自动拉起守护进程。哪种方式更适合你的工作流，详见 [桌面应用](/desktop-app) 页面。
|
||
|
||
## 为什么一台机器会有多个运行时
|
||
|
||
运行时不是一个服务器，也不是一个容器——它是「**守护进程 × 一款 AI 编程工具**」的组合。举例：你在一台 MacBook 上启动守护进程，本机装了 Claude Code 和 Codex；你是两个工作区的成员。那么 Multica 会注册 4 个运行时：
|
||
|
||
<Mermaid chart={`
|
||
graph TD
|
||
D["你的守护进程<br/>MacBook"]
|
||
D --> R1["运行时<br/>工作区 A × Claude Code"]
|
||
D --> R2["运行时<br/>工作区 A × Codex"]
|
||
D --> R3["运行时<br/>工作区 B × Claude Code"]
|
||
D --> R4["运行时<br/>工作区 B × Codex"]
|
||
`} />
|
||
|
||
关键的点：
|
||
|
||
- **一个守护进程可以对应多个运行时**——装了多款工具、加入了多个工作区，每个组合就各一个
|
||
- **同一个守护进程在同一个工作区同一款工具上只会有一条运行时**——重启守护进程不会产生重复记录
|
||
- Multica 界面的 **Runtimes** 页面列的就是这些行
|
||
|
||
<Callout type="info">
|
||
**云端运行时即将开放**，目前处于等待名单阶段。上线后，你无需在本地运行守护进程，即可在 Multica Cloud 上直接执行智能体任务。在 [下载页面](https://multica.ai/download) 登记邮箱以获取通知。
|
||
</Callout>
|
||
|
||
## 运行时什么时候被判定为离线
|
||
|
||
Multica 用心跳判断运行时是否在线。三个关键数字：
|
||
|
||
| 事件 | 阈值 |
|
||
|---|---|
|
||
| 守护进程心跳频率 | 每 **15 秒** |
|
||
| 标记为失联 | 超过 **45 秒** 没心跳（漏了 3 次）|
|
||
| 自动删除 | 失联且无关联智能体超过 **7 天** |
|
||
|
||
失联不是永久的——守护进程只要再次发出心跳就立刻回到在线，运行时记录也会保留。重启守护进程不会丢运行时。
|
||
|
||
<Callout type="warning">
|
||
**失联的运行时上正在跑的执行任务会被标记为失败**（失败原因 `runtime_offline`）。对可重试的来源（issue、chat），Multica 会自动重新排队；Autopilots 触发的任务不自动重试。详见 [执行任务 → 哪些失败会自动重试](/tasks#哪些失败会自动重试哪些不会)。
|
||
</Callout>
|
||
|
||
## 一次能并发跑多少任务
|
||
|
||
Multica 对并发有两层限额：
|
||
|
||
- **守护进程层**：默认 **20 个执行任务并发**（环境变量 `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` 可调）
|
||
- **智能体层**：每个智能体默认 **6 个执行任务并发**（智能体配置里改）
|
||
|
||
两层中更紧的那层生效。如果你的守护进程已经在跑 20 个任务，即使某个智能体还有余量，新的任务也要等。
|
||
|
||
如果你看到执行任务卡在 `queued` 状态不 `dispatched`，通常就是这两层里某一层打满了。
|
||
|
||
## 守护进程崩溃后，没跑完的任务会怎样
|
||
|
||
守护进程崩溃或被强行结束时，它领走的执行任务会停在 `dispatched` 或 `running` 状态。下次启动时，守护进程会告诉服务器：「这些任务不是我的了，请标记失败。」服务器把它们改成 `failed`，失败原因 `runtime_recovery`——对可重试的来源，任务自动重新排队。
|
||
|
||
即使这一步因网络问题没完成，还有**每 30 秒**一次的服务器端扫描作为后备：超过 45 秒没心跳的运行时会被统一标记为失联，上面的任务也一并回收。
|
||
|
||
## Agent 不工作怎么排查
|
||
|
||
遇到「我的智能体不工作」类问题，先过一遍这三步：
|
||
|
||
1. 跑 `multica daemon status`，确认守护进程在运行且在线
|
||
2. 跑 `multica daemon logs -f`，看是否有错误
|
||
3. 去 Multica 界面的 **Runtimes** 页面，确认你的运行时显示「在线」
|
||
|
||
更多场景见 [Troubleshooting](/troubleshooting)。
|
||
|
||
## 下一步
|
||
|
||
- [执行任务](/tasks) —— 守护进程领到任务后，它的完整生命周期
|
||
- [Providers Matrix](/providers) —— 11 款 AI 编程工具的能力差异对照
|