Skip to content

docs: add Simplified Chinese translation #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bitwalt merged 1 commit into from
Aug 13, 2026
Merged

docs: add Simplified Chinese translation #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 174 additions & 0 deletions TRANSLATION-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
# Translation Guide — Simplified Chinese (`cn`)

Canonical rules and glossary for the Chinese localization of the KaleidoSwap docs.
Read this before translating or updating any file under `mintlify-docs/cn/`.

## Layout

- English (default language) stays at the repo root: `mintlify-docs/<section>/<page>.mdx`.
- Simplified Chinese mirrors that tree one-to-one under `mintlify-docs/cn/`:
`mintlify-docs/whats-kaleidoswap/introduction.mdx` → `mintlify-docs/cn/whats-kaleidoswap/introduction.mdx`
- `docs.json` declares both under `navigation.languages` (`en` first, then `cn`).
Adding or removing a page means updating **both** language trees.
- `mintlify-docs/snippets/` is shared. Chinese pages import the same snippet with the
same absolute path (`/snippets/versions.mdx`) — do not duplicate it.
- `mintlify-docs/openapi.json` is shared and not translated.

## Tooling

Run both after any change to the `cn/` tree:

```bash
python scripts/check-cn-parity.py # structure, links, anchors, coverage
python scripts/pin-cn-anchors.py # add --apply to write
```

`check-cn-parity.py` compares every translated page against its English source
(heading count, code fences, components, table rows, images, links), confirms each
page in the `cn` navigation exists, and verifies every internal link is `/cn`-prefixed
and resolves. It exits with `PROBLEMS FOUND` if anything is off.

## What to translate

Translate:

- Prose, headings, list items, table cells.
- Frontmatter **values** for `title`, `sidebarTitle`, `description`.
For `description`, target **60–80 CJK characters**, not the 150–160 used for
English. CJK glyphs are roughly double-width, so 60–80 of them occupy the same
space in a search result as a 150–160 character English description. Do not pad
a description to hit a count.
- User-facing component props: `title=`, `label=`, `header=`, `<Tooltip>` text,
`<Accordion title=>`, `<Card title=>`, `<Step title=>`, `<Tab title=>`.
- Image `alt` text (the square-bracket part of `![alt](path)`).
- Comments inside code blocks (`// ...`, `# ...`).

Leave in English / untouched:

- Product and brand names: KaleidoSwap, KaleidoMind, KaleidoAgent, Thunderstack.
- Protocol and standard names: Bitcoin, Lightning, RGB, Taproot Assets, LSPS1, NWC,
HTLC, PSBT, UTXO, MCP, QVAC.
- All code: identifiers, string literals, JSON keys, API field names, CLI commands
and flags, env vars, file paths, package names, URLs, version numbers.
- Code-fence language tags and their tab titles (```` ```typescript TypeScript ````).
- Component and prop **names**, and icon/layout values (`icon="wallet"`, `cols={2}`,
`horizontal`, `openapi=`).
- Image paths (`/assets/images/...`) — only the alt text changes.
- Network names: mainnet is 主网 and testnet is 测试网, but `signet` and `regtest`
stay lowercase in English.

## Links

- Rewrite every internal absolute link to the `cn` tree:
`[SDK](/sdk/introduction)` → `[SDK](/cn/sdk/introduction)`
- External links (`https://…`) are unchanged, including their `#fragments`.
- **Anchor fragments on internal links:** leave the English fragment verbatim
(e.g. `/cn/sdk/websocket#events`), including same-page anchors (`](#some-heading)`).
Do not translate fragments and do not guess another page's headings.

### How anchors survive translation

Mintlify derives a heading's anchor from its text, so translating a heading would
break every link pointing at it. Instead, any heading that is the target of a link
carries an explicit id with the **English** slug, using Mintlify's `{#custom-id}`
syntax:

```mdx
## 客户端配置 {#client-configuration}
```

The link stays `](/cn/ai-tools/mcp-servers#client-configuration)` and keeps working
no matter how the heading text is later reworded. Consequences:

- Never reorder or drop headings in a translated page — `scripts/pin-cn-anchors.py`
maps English to Chinese headings by position.
- After adding or changing any cross-page anchor link, re-run that script; it pins
the ids it needs and reports anything it cannot resolve.
- Headings with no inbound links need no id. Mintlify generates both the id and its
own table-of-contents link, so those stay self-consistent.
- A fragment containing `&` is normalised (`installation-&-configuration` becomes
`installation-and-configuration`) and the `cn` links are repointed to match.
Mintlify keeps `&` when it generates a slug from heading text, but its handling of
`&` inside an explicit `{#id}` is undocumented; since both sides live in the `cn`
tree, the script picks an id that cannot be ambiguous. The English pages are
untouched and keep their original `&` anchors.

## Style

Audience is Chinese-speaking Bitcoin developers and traders. Aim for the register of
good native technical documentation, not literal translation.

- Simplified Chinese (简体), mainland conventions.
- Full-width punctuation for Chinese sentences: `，。：；！？、（）「」`.
Keep half-width punctuation inside code and inside English phrases.
- Put a half-width space between CJK and adjacent Latin text or numerals:
`使用 KaleidoSwap 桌面应用`, `需要 2 个通道`.
- Prefer verb-first, concise imperative sentences in instructions (`点击「创建钱包」`).
- Do not pad. If the English is one sentence, the Chinese is one sentence.
- Keep Markdown structure identical: same heading levels, same list nesting,
same number of table rows, same component tree. Only text changes.
- UI labels that appear in the app's English interface: translate, then keep the
English in parentheses on first use in a page — `点击「解锁钱包」(Unlock Wallet)`.

## Positioning

Do **not** frame KaleidoSwap as an RGB-first product. It is a multi-protocol Bitcoin
DEX; RGB is one of the supported Bitcoin layers. Use 多协议 / 比特币分层 framing.
This applies especially to `title` and `description` frontmatter.

## Glossary

| English | 简体中文 | Note |
|---|---|---|
| atomic swap | 原子交换 | |
| swap (noun/verb) | 交换 | consistent with 原子交换; never 兑换 |
| swap protocol | 交换协议 | |
| trading pair | 交易对 | |
| quote | 报价 | |
| request for quote (RFQ) | 询价 | |
| order | 订单 | |
| Lightning Network | 闪电网络 | |
| Lightning channel | 闪电通道 | `channel` alone → 通道 |
| open a channel | 开通通道 | |
| channel capacity | 通道容量 | |
| inbound / outbound liquidity | 入向流动性 / 出向流动性 | |
| liquidity | 流动性 | |
| LSP (Lightning Service Provider) | 闪电服务提供商（LSP） | |
| market maker | 做市商 | |
| maker / taker | 做市方 / 接单方 | |
| node | 节点 | |
| peer | 对等节点 | |
| non-custodial | 非托管 | |
| custodial | 托管 | |
| trustless | 无需信任 | |
| self-custody / sovereign | 自主保管 / 自主掌控 | |
| wallet | 钱包 | |
| mnemonic / recovery phrase | 助记词 | |
| seed | 种子 | |
| unlock the wallet | 解锁钱包 | |
| on-chain / off-chain | 链上 / 链下 | |
| Bitcoin | 比特币 | |
| BTC | BTC | never translate the ticker |
| sats / satoshis | 聪 | |
| Bitcoin Layers | 比特币分层协议 | |
| Layer 2 | 二层 | |
| RGB assets | RGB 资产 | |
| asset ID | 资产 ID | |
| mainnet / testnet | 主网 / 测试网 | |
| deposit | 存入 | noun 存入操作 / 充值 in UI context |
| withdrawal | 提取 | |
| balance | 余额 | |
| payment | 支付 | |
| invoice | 发票 | Lightning invoice → 闪电发票 |
| fee | 费用 | routing fee → 路由费 |
| backup | 备份 | |
| restore | 恢复 | |
| desktop app | 桌面应用 | |
| browser extension | 浏览器扩展 | |
| DApp | DApp | |
| open source | 开源 | |
| whitelist | 白名单 | |
| rate limit | 速率限制 | |
| endpoint | 接口端点 | |
| webhook | Webhook | |
| SDK / CLI / API / REST | keep in English | |
91 changes: 91 additions & 0 deletions mintlify-docs/cn/ai-tools/additional-resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
title: "AI 工具：更多资源"
sidebarTitle: "更多资源"
description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP 与闪电付费 API 的协议规范，以及可用的支持渠道。"
---

## 源码仓库

每一种 AI 接入方式都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下开源。

<CardGroup cols={2}>
<Card title="kaleido-agent" icon="robot" href="https://github.com/kaleidoswap/kaleido-agent">
自主代理本体、它的仪表盘与状态 API，以及每个循环加载的 `skills/` 目录。
</Card>
<Card title="kaleido-mind" icon="brain" href="https://github.com/kaleidoswap/kaleido-mind">
本地端引擎：分层漏斗、recipe 引擎、工具契约、记忆与检索，以及评测框架。
</Card>
<Card title="kaleido-mcp" icon="server" href="https://github.com/kaleidoswap/kaleido-mcp">
把所有领域组合到一条连接背后的统一网关。已发布到 npm。
</Card>
<Card title="Rate" icon="mobile" href="https://github.com/kaleidoswap/Rate">
以语音控制承载 KaleidoMind 的 React Native 移动钱包。
</Card>
</CardGroup>

### 单域 MCP 服务器

| 仓库 | 工具前缀 | 领域 |
|-----------|-------------|--------|
| [wdk-wallet-mcp](https://github.com/kaleidoswap/wdk-wallet-mcp) | `wdk_*` | RGB Lightning Node 钱包、通道、原子交换接单方 |
| [wdk-wallet-spark-mcp](https://github.com/kaleidoswap/wdk-wallet-spark-mcp) | `spark_*` | Spark 钱包、闪电网络、代币转账、BTC 桥接 |
| [wdk-wallet-liquid-mcp](https://github.com/kaleidoswap/wdk-wallet-liquid-mcp) | `liquid_*` | Liquid 钱包、L-BTC 与资产余额、保密发送 |
| [kaleidoswap-mcp](https://github.com/kaleidoswap/kaleidoswap-mcp) _（已归档）_ | `kaleidoswap_*` | 已被 kaleido-mcp 中的 `kaleidoswap_*` 工具取代 |
| [l402-gateway-mcp](https://github.com/kaleidoswap/l402-gateway-mcp) _（已归档）_ | `mpp_*`、`l402_*` | 已被 kaleido-mcp 中的 `mpp_*` / `l402_*` 工具取代 |

## 协议规范

<CardGroup cols={2}>
<Card title="Model Context Protocol" icon="plug" href="https://modelcontextprotocol.io">
每个 KaleidoSwap MCP 服务器都实现的工具协议。
</Card>
<Card title="RGB 协议" icon="gem" href="https://docs.rgb.info">
RGB 工具背后的客户端验证与资产接口。
</Card>
<Card title="RGB Lightning Node" icon="bolt" href="https://github.com/RGB-Tools/rgb-lightning-node">
`wdk_*` 工具所驱动的节点，附带它自己的 OpenAPI 参考。
</Card>
<Card title="QVAC SDK" icon="microchip" href="https://www.npmjs.com/package/@qvac/sdk">
KaleidoMind 用于 LLM、向量嵌入、语音转文字和文字转语音的本地端推理运行时。
</Card>
</CardGroup>

## KaleidoSwap 参考文档

先读这几篇，代理工具会好理解得多，因为那些工具只是它们之上的一层薄封装。

<CardGroup cols={2}>
<Card title="交换协议" icon="arrows-rotate" href="/cn/api-reference/swap-protocol">
原子 HTLC 流程如何结算，也就是交换工具所编排的那套流程。
</Card>
<Card title="RGB LSPS1 API" icon="code" href="/cn/api-reference/rgb-lsps1-apis">
`kaleidoswap_lsp_*` 背后的通道下单接口端点。
</Card>
<Card title="CLI" icon="terminal" href="/cn/cli/introduction">
KaleidoAgent 调用的那个可执行文件，也是节点生命周期工具的来源。
</Card>
<Card title="SDK" icon="code" href="/cn/sdk/introduction">
直接从 TypeScript 或 Python 调用交换基础设施，跳过代理这一层。
</Card>
</CardGroup>

## 产品与社区

<CardGroup cols={2}>
<Card title="AI 工具产品页" icon="sparkles" href="https://kaleidoswap.com/products/ai-tools">
产品概览，以及每个 skill 的可阅读与可下载版本。
</Card>
<Card title="Telegram" icon="telegram" href="https://t.me/kaleidoswap">
社区支持与讨论。
</Card>
<Card title="GitHub" icon="github" href="https://github.com/kaleidoswap">
Issue、Pull Request 和完整源码。
</Card>
<Card title="邮件支持" icon="envelope" href="mailto:support@kaleidoswap.com">
紧急问题的直接支持渠道。
</Card>
</CardGroup>

<Note>
反馈某个 AI 接入方式的问题时，请附上失败的工具名称、你所在的网络，以及移除了种子和所有 API 密钥的配置。请先查看[故障排查](/cn/ai-tools/troubleshooting)。
</Note>
115 changes: 115 additions & 0 deletions mintlify-docs/cn/ai-tools/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
title: "AI 工具常见问题"
sidebarTitle: "常见问题"
description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种子处理、模型选择、网络、成本，以及不同接入方式各自适合什么场景。"
---

## 常见问题

<AccordionGroup>
<Accordion title="这些 AI 工具是托管的吗？">
**不是。** 密钥始终留在本地 WDK 钱包和你所指向的 RGB Lightning Node 中。交易以闪电网络上的原子 HTLC 交换结算，因此做市商只是交易的对手方，从不持有你的资金。

引入 AI 改变的不是托管方式，而是*由谁发起花费*。这正是确认机制和风险上限存在的意义。
</Accordion>

<Accordion title="语言模型会看到我的助记词吗？">
助记词以环境变量（`WDK_SEED`）的形式传给服务器进程，或从 `agent.config.json` 中读取。签名发生在该进程内部。模型只是调用工具并接收结果，因此种子不会成为提示词或工具输出的一部分。

但这并不等于种子是安全的。任何能读取配置文件或进程环境的东西都能拿到你的助记词，所以主网种子绝不该出现在你会提交或分享的文件里。
</Accordion>

<Accordion title="我该用哪种接入方式？">
| 如果你想 | 使用 |
|----------------|-----|
| 给已有的 MCP 客户端加上比特币工具 | [MCP 服务器](/cn/ai-tools/mcp-servers) |
| 无人值守地管理一个投资组合 | [KaleidoAgent](/cn/ai-tools/kaleido-agent) |
| 在本地端通过聊天或语音操作钱包 | [KaleidoMind](/cn/ai-tools/kaleido-mind) |
| 不改代码就调整代理行为 | [Skills](/cn/ai-tools/skills) |
</Accordion>

<Accordion title="我需要运行一个节点吗？">
取决于你调用哪些工具。

- 行情数据（`l402_*`）和 Spark 钱包（`spark_*`）**不需要节点**，后者只需要一份种子。
- RGB Lightning Node 工具（`wdk_*`）和原子交换**需要节点**，因为 HTLC 的接单方一侧跑在你的节点上。

[KaleidoCLI](/cn/cli/getting-started) 可以为你部署一个基于 Docker 的节点，`kaleido-mcp` 也提供了 `kaleido_node_*` 工具来替你驱动这套生命周期。
</Accordion>

<Accordion title="这些工具用的是哪个模型？">
因接入方式而异：

- **KaleidoAgent** 用托管模型推理，Claude 或 OpenAI，通过 `AGENT_PROVIDER` 选择。
- **KaleidoMind** 通过 QVAC SDK 让模型**在设备上**运行，可以在本地，也可以在你显式配对过的桌面端。它的分层漏斗设计意味着大多数请求根本不会到达模型。
- **MCP 服务器** 与模型无关。调用工具的就是你的 MCP 宿主所运行的那个模型。
</Accordion>

<Accordion title="我可以在主网上运行吗？">
这些工具能够访问主网，但请把它当作最后一步而不是第一步。先用一次性种子在 regtest 或 signet 上起步，在 KaleidoAgent 上保持 `dry_run` 开启，直到 dry-run 的决策看起来都正确，然后再切换网络。

另外要注意，不同接入方式的成熟度并不相同：KaleidoAgent 和 MCP 服务器会直接动用真实资金，而 LLM 调错一个工具是真实存在的失败模式。
</Accordion>

<Accordion title="运行起来要花多少钱？">
三条相互独立的成本线：

- 托管模型的 **LLM token**。KaleidoAgent 会在 `GET /status` 中报告每轮运行的 token 开销。
- KaleidoMind **没有推理成本**，因为模型跑在你自己的硬件上。
- 每种情况下都有 **比特币费用**：闪电网络上的路由费、通道开通或关闭时的链上费用，以及交换中做市商的价差。
</Accordion>

<Accordion title="怎样阻止代理花钱？">
有几种相互独立的控制手段，而且值得同时用上多个：

| 控制项 | 效果 |
|---------|--------|
| `dry_run` | 只模拟决策，不真正执行 |
| `max_swap_usd` | 限制单笔交易的上限 |
| `stop_loss_btc_sats` | 低于某个 BTC 阈值时停止所有交易 |
| `min_btc_reserve_sats` | 为节点与 Spark 合计保留一个下限 |
| `max_concurrent_orders` | 限制同时挂出的订单数量 |

在 KaleidoMind 上，等价机制是结构性的而非配置出来的：会动用资金的工具被标记为 `requiresConfirmation`，并暂停等待宿主的确认面板。
</Accordion>

<Accordion title="代理能在没有 API 密钥的情况下为 API 付费吗？">
可以，这正是 Machine Payments Protocol 工具覆盖的场景。代理探测一个受门控的 URL，收到带闪电发票的 HTTP 402 挑战，支付它，然后提交凭据以拿到数据和一张收据。无需注册，也无需 API 密钥。完整流程见 [MCP 服务器页面](/cn/ai-tools/mcp-servers#paid-api-access)。
</Accordion>

<Accordion title="skill 和 MCP 服务器有什么区别？">
**MCP 服务器**提供工具：针对钱包、DEX 或节点的类型化、可调用操作。

**skill** 是一份 `SKILL.md` 操作手册，限定模型*可以调用其中哪些*工具，并承载执行计划。改动 skill 就能改变行为，无需触碰运行时代码。一个是能力，另一个是策略加计划。
</Accordion>

<Accordion title="这些都是开源的吗？">
是的。所有仓库都公开在 [github.com/kaleidoswap](https://github.com/kaleidoswap) 下：MCP 服务器、KaleidoAgent、KaleidoMind，以及 skill 本身。直达链接见[更多资源](/cn/ai-tools/additional-resources)。
</Accordion>

<Accordion title="这些工具能配合桌面应用或浏览器扩展使用吗？">
桌面应用直接把 KaleidoMind 作为应用内聊天来承载，其工具以 stdio 边车方式接入 `kaleido-mcp`，可在**「设置 > 能力」**(Settings > Capabilities) 中切换。浏览器扩展自带一个内置的对话式代理来执行钱包操作。独立的 MCP 服务器则面向 Claude Desktop 或你自己的客户端这类外部宿主。
</Accordion>
</AccordionGroup>

## 获取帮助

如果遇到的是报错而不是疑问，请查看[故障排查](/cn/ai-tools/troubleshooting)。其他情况请通过下面任一渠道反馈问题，并附上：

1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本）
2. 你所在的网络（regtest、signet 或主网）
3. 失败的工具名称和报错文本
4. 宿主与运行时版本（MCP 客户端、Node.js）
5. 你的配置，并移除其中的种子和所有密钥

<CardGroup cols={3}>
<Card title="Telegram 社区" icon="telegram" href="https://t.me/kaleidoswap">
向社区提问。
</Card>
<Card title="GitHub Issues" icon="github" href="https://github.com/kaleidoswap">
在相关仓库提交缺陷报告。
</Card>
<Card title="邮件支持" icon="envelope" href="mailto:support@kaleidoswap.com">
紧急问题的直接支持渠道。
</Card>
</CardGroup>
Loading
Loading