关于 deep-research
deep-research 是一款 Claude 技能,可研究主题、学术论文和网页,并生成结构化 JSON 报告及 HTML 页面。它使用 Actionbook 浏览器自动化进行搜索和页面分析。
主要功能
- 01主题与论文研究
- 02arXiv 高级搜索
- 03多来源网页分析
- 04生成 JSON 报告
- 05渲染 HTML 报告
适用场景
- 01研究一篇学术论文
- 02跨来源探索某个主题
- 03创建双语研究报告
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ actionbook/ actionbook --skill deep-research安装后在 Claude Code 中输入/deep-research确认已加载。
详细介绍
深度研究
分析任意主题、领域或论文,并使用 Actionbook 浏览器自动化和 json-ui 渲染生成精美的 HTML 报告。
用法
/deep-research:analyze <topic>
/deep-research:analyze <topic> --lang zh
/deep-research:analyze <topic> --output ./reports/my-report.json
或者直接告诉 Claude:“帮我深度研究 XXX 并生成报告” / “研究 XXX 并生成报告”
参数
| 参数 | 必填 | 默认值 | 描述 |
|---|---|---|---|
topic | 是 | - | 要研究的主题(任意文本) |
--lang | 否 | both | 语言:en、zh 或 both(双语) |
--output | 否 | ./output/<topic-slug>.json | JSON 报告的输出路径 |
主题检测
| 模式 | 类型 | 策略 |
|---|---|---|
arxiv:XXXX.XXXXX | 论文 | arXiv 高级搜索(步骤 2b)+ ar5iv 深度阅读 |
doi:10.XXX/... | 论文 | 解析 DOI,然后通过 arXiv 高级搜索查找相关研究 |
| 学术关键词(paper、research、model、algorithm) | 学术主题 | arXiv 高级搜索(步骤 2b)+ 使用 Google 搜索非学术来源 |
| URL | 特定页面 | 获取并分析该页面 |
| 普通文本 | 主题研究 | Google 搜索;如相关,再使用 arXiv 高级搜索 |
架构
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
│ Claude │────▶│ Actionbook │────▶│ Web Pages │────▶│ Extract │
│ Code │ │ Browser CLI │ │ (multiple) │ │ Content │
└──────────┘ └──────────────┘ └──────────────┘ └─────┬────┘
│ │
│ ┌──────────────┐ ┌──────────────┐ │
├─────────▶│ Actionbook │ │ arXiv Adv. │ │
│ │ search/get │────▶│ Search Form │──────────▶│
│ │ (selectors) │ │ (40+ fields) │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ Actionbook indexes arXiv form selectors, │
│ enabling field-specific, filtered academic │
│ searches that WebFetch/WebSearch CANNOT do. │
│ │
┌──────────┐ ┌──────────────┐ ┌──────────────┐ │
│ Open in │◀────│ json-ui │◀────│ Write JSON │◀──────────┘
│ Browser │ │ render │ │ Report │ Synthesize
└──────────┘ └──────────────┘ └──────────────┘
为什么使用 Actionbook,而不是 WebFetch/WebSearch?
| 能力 | Actionbook | WebFetch/WebSearch |
|---|---|---|
| 操作复杂的网页表单(下拉菜单、复选框、日期选择器) | 是 — 使用已索引的选择器 | 否 |
| arXiv:分别按作者、标题、摘要搜索 | 是 — #terms-0-field 选择器 | 否 — 仅支持关键词 |
| arXiv:按主题筛选(CS、Physics、Math,……) | 是 — 类别复选框 | 否 |
| arXiv:按日期范围或指定年份筛选 | 是 — 日期输入框 | 否 |
| 使用经过验证的选择器读取页面(无需猜测) | 是 — actionbook get | 否 — 解析原始 HTML |
| 与任何已索引网站的 UI 交互 | 是 — 点击、输入、选择 | 否 — 只读 |
这正是 Actionbook 对研究的核心价值:它将网页表单转变为结构化、可编程的界面,供 AI Agent 使用。
必须使用 Actionbook CLI
浏览网页时始终使用 actionbook browser 命令。切勿使用 WebFetch 或 WebSearch。
actionbook browser open <url> # Navigate to page
actionbook browser snapshot # Get accessibility tree
actionbook browser text [selector] # Extract text content
actionbook browser screenshot [path] # Capture visual
actionbook browser click <selector> # Click element
actionbook browser close # Close browser (ALWAYS do this at end)
完整工作流
第 1 步:制定搜索策略
根据主题,从不同角度生成 5–8 条搜索查询:
- 核心定义 / 概述
- 最新进展 / 新闻
- 技术细节 / 实现方式
- 比较 / 替代方案
- 专家观点 / 分析
- 用例 / 应用
搜索顺序 — 始终先查询 Actionbook API,再进行搜索:
| 步骤 | 操作 | 原因 |
|---|---|---|
| 第 2 步(第一步) | 查询 Actionbook API | 在浏览之前,获取 arXiv 高级搜索表单、ar5iv 论文和其他已知网站的已验证选择器。这是后续所有步骤的基础。 |
| 第 3 步(第二步) | arXiv 高级搜索 | 使用第 2 步获取的 Actionbook 选择器执行多字段筛选式学术搜索。即使是非学术主题,通常也能找到相关论文。 |
| 第 4 步(第三步) | Google / Bing 搜索 | 补充博客、新闻、代码、讨论和非学术来源。 |
重要: 始终先查询 Actionbook API(第 2 步)获取选择器,然后在 arXiv 高级搜索(第 3 步)中使用它们。这正是 Actionbook 驱动的研究与 WebFetch/WebSearch 有本质区别之处——Agent 在打开浏览器之前,就知道每个表单字段的确切选择器。
第 2 步:查询 Actionbook API 获取选择器(务必先执行)
在浏览任何 URL 之前,先查询 Actionbook 已索引的选择器。 这样可以获取经过验证的 CSS/XPath 选择器,无需猜测。
# Search for indexed actions by domain
actionbook search "<keywords>" -d "<domain>"
# Get detailed selectors for a specific page
actionbook get "<domain>:/<path>:<area>"
适用于研究的预索引网站:
| 网站 | area_id | 关键选择器 |
|---|---|---|
| arXiv 高级搜索 | arxiv.org:/search/advanced:default | 40+ 个选择器:字段选择框、词条输入框、类别复选框(CS/Physics/Math/...)、日期范围筛选器、交叉列表控制项——在第 3 步中使用 |
| ar5iv 论文 | ar5iv.labs.arxiv.org:/html/{paper_id}:default | h1.ltx_title_document(标题)、div.ltx_authors(作者)、div.ltx_abstract(摘要)、section.ltx_section(章节) |
| Google Scholar | scholar.google.com:/:default | #gs_hdr_tsi(搜索输入框)、#gs_hdr_tsb(搜索按钮) |
| arXiv 首页 | arxiv.org:/:default | 可搜索 240 多万篇文章的全局搜索 |
对于计划访问的任何 URL,运行 actionbook search "<keywords>" -d "<domain>" 检查该网站是否已被索引。有可用的索引选择器时请使用;对于未索引的网站,则使用 actionbook browser snapshot。
示例:搜索前获取 arXiv 高级搜索选择器:
# Query Actionbook for arXiv form selectors
actionbook get "arxiv.org:/search/advanced:default"
# Returns 40+ selectors: #terms-0-field, #terms-0-term, #classification-computer_science, etc.
第 3 步:arXiv 高级搜索(使用 Actionbook 选择器)
关键差异化优势: WebFetch/WebSearch 只能执行简单的关键词搜索。Actionbook 已索引整个 arXiv 高级搜索表单,包含 40 多个经过验证的选择器(在第 2 步中查询),支持多字段、多条件的学术搜索——就像人类研究人员使用该表单一样。
使用从第 2 步获取的选择器,Agent 可以:
| 功能 | Actionbook 选择器 | WebFetch/WebSearch |
|---|---|---|
| 按特定字段搜索(标题、作者、摘要) | #terms-0-field 选择框 → 选择字段 | 无法实现 |
| 使用布尔逻辑添加多个搜索词 | button "Add another term +" | 无法实现 |
| 按主题筛选(CS、Physics、Math 等) | #classification-computer_science 复选框 | 无法实现 |
| 按日期范围筛选 | #date-filter_by-3 单选按钮 + #date-from_date / #date-to_date | 无法实现 |
| 按特定年份筛选 | #date-filter_by-2 单选按钮 + #date-year 输入框 | 无法实现 |
| 纳入/排除交叉列表论文 | #classification-include_cross_list-0/1 单选按钮 | 无法实现 |
| 控制结果显示 | #size 选择框、#abstracts-0/1 单选按钮 | 无法实现 |
示例:搜索特定作者近期发表的 CS 论文:
# Open arXiv Advanced Search
actionbook browser open "https://arxiv.org/search/advanced"
# 1. Set search field to "Author" and type author name
actionbook browser click "#terms-0-field"
actionbook browser click "option[value='author']"
actionbook browser type "#terms-0-term" "Yann LeCun"
# 2. Filter to Computer Science only
actionbook browser click "#classification-computer_science"
# 3. Restrict to past 12 months
actionbook browser click "#date-filter_by-1"
# 4. Show abstracts in results
actionbook browser click "#abstracts-0"
# 5. Submit search
actionbook browser click "button:has-text('Search'):nth(2)"
# 6. Extract results
actionbook browser text "#main-container"
示例:在指定日期范围内按标题关键词搜索:
actionbook browser open "https://arxiv.org/search/advanced"
# Search in "Title" field
actionbook browser click "#terms-0-field"
actionbook browser click "option[value='title']"
actionbook browser type "#terms-0-term" "large language model agent"
# Date range: 2025-01 to 2026-02
actionbook browser click "#date-filter_by-3"
actionbook browser type "#date-from_date" "2025-01-01"
actionbook browser type "#date-to_date" "2026-02-09"
# Submit and extract
actionbook browser click "button:has-text('Search'):nth(2)"
actionbook browser text "#main-container"
第 4 步:补充 Google / Bing 搜索
在 arXiv 搜索之后,使用 Google/Bing 查找非学术来源(博客、新闻、文档、代码、讨论):
# Search via Google
actionbook browser open "https://www.google.com/search?q=<encoded_query>"
actionbook browser text "#search"
# Or search via Bing
actionbook browser open "https://www.bing.com/search?q=<encoded_query>"
actionbook browser text "#b_results"
解析搜索结果,提取 URL 和摘要片段。收集最相关的 5-10 个 URL。对于每个发现的 URL,在访问之前按照第 2 步的方法查询 Actionbook API,检查该网站是否已被索引。
第 5 步:深入阅读来源
对于每个相关 URL,先查询 Actionbook API(与第 2 步相同),检查该网站是否已被索引,然后使用经过验证的选择器:
actionbook browser open "<url>"
actionbook browser text # Full page text (fallback)
actionbook browser text "<selector>" # Use Actionbook selector if indexed
对于 arXiv 论文,按以下顺序尝试不同来源(较新的论文在 ar5iv 上往往无法访问):
# 1. Try ar5iv first (best structured selectors from Actionbook)
actionbook browser open "https://ar5iv.org/html/<arxiv_id>"
actionbook browser text "h1.ltx_title_document" # Title
actionbook browser text "div.ltx_authors" # Authors
actionbook browser text "div.ltx_abstract" # Abstract
# NOTE: section.ltx_section often fails on newer papers — use "article" as fallback
# 2. If ar5iv content is truncated (<5KB), fall back to arxiv abstract + other sources
actionbook browser open "https://arxiv.org/abs/<arxiv_id>"
actionbook browser text "main"
# 3. Supplement with HuggingFace model cards and GitHub READMEs for full details
actionbook browser open "https://huggingface.co/papers/<arxiv_id>"
actionbook browser text "main"
重要经验: 不要只依赖 ar5iv。务必交叉参考 3-4 个来源,以确保内容完整。
对于 Google Scholar(已由 Actionbook 索引):
actionbook browser open "https://scholar.google.com"
# Type into search: use selector #gs_hdr_tsi
actionbook browser click "#gs_hdr_tsi"
# ... type query, click #gs_hdr_tsb to search
对于未索引的网站,使用 snapshot 探索页面结构:
actionbook browser open "<url>"
actionbook browser snapshot # Get accessibility tree to find selectors
actionbook browser text "<discovered_selector>"
第 6 步:综合整理发现
将收集到的信息整理成一份条理清晰的报告:
- 概览 / 执行摘要
- 关键发现
- 详细分析
- 支持数据 / 证据
- 影响 / 重要性
- 来源
第 7 步:生成 json-ui JSON 报告
使用 Write 工具,按照 @actionbookdev/json-ui schema 编写 JSON 文件。
输出路径: ./output/<topic-slug>.json(或用户指定的 --output 路径)
第 8 步:渲染 HTML
关键:放弃前必须尝试所有备用方法。不要在首次失败后就停止。
重要:JSON_FILE 和 HTML_FILE 始终使用绝对路径。 当 git rev-parse 返回绝对仓库根目录时,相对路径会失效。
逐一尝试每种方法,直到其中一种成功:
# Method 1: npx (recommended — works anywhere if npm is available)
npx @actionbookdev/json-ui render /absolute/path/to/report.json -o /absolute/path/to/report.html
# Method 2: Global install (if user ran: npm install -g @actionbookdev/json-ui)
json-ui render /absolute/path/to/report.json -o /absolute/path/to/report.html
# Method 3: Monorepo local path (fallback if inside actionbook project)
node "$(git rev-parse --show-toplevel)/packages/json-ui/dist/cli.js" render /absolute/path/to/report.json -o /absolute/path/to/report.html
绝不要默默放弃。 如果所有方法都失败,请告知用户:
- JSON 报告已保存至
<path> - 如需安装渲染器,请运行:
npm install -g @actionbookdev/json-ui
第 9 步:在浏览器中打开
# macOS
open <report.html>
# Linux
xdg-open <report.html>
第 10 步:关闭浏览器
完成后始终关闭浏览器:
actionbook browser close
json-ui 报告模板
重要:始终包含 BrandHeader 和 BrandFooter。
{
"type": "Report",
"props": { "theme": "auto" },
"children": [
{
"type": "BrandHeader",
"props": {
"badge": { "en": "Deep Research Report", "zh": "深度研究报告" },
"poweredBy": "Actionbook"
}
},
{
"type": "Section",
"props": { "title": { "en": "Overview", "zh": "概述" }, "icon": "paper" },
"children": [
{
"type": "Prose",
"props": {
"content": { "en": "English overview...", "zh": "中文概述..." }
}
}
]
},
{
"type": "Section",
"props": { "title": { "en": "Key Findings", "zh": "核心发现" }, "icon": "star" },
"children": [
{
"type": "ContributionList",
"props": {
"items": [
{
"badge": { "en": "Finding", "zh": "发现" },
"title": { "en": "...", "zh": "..." },
"description": { "en": "...", "zh": "..." }
}
]
}
}
]
},
{
"type": "Section",
"props": { "title": { "en": "Detailed Analysis", "zh": "详细分析" }, "icon": "bulb" },
"children": [
{
"type": "Prose",
"props": { "content": { "en": "...", "zh": "..." } }
}
]
},
{
"type": "Section",
"props": { "title": { "en": "Key Metrics", "zh": "关键指标" }, "icon": "chart" },
"children": [
{
"type": "MetricsGrid",
"props": { "metrics": [], "cols": 3 }
}
]
},
{
"type": "Section",
"props": { "title": { "en": "Sources", "zh": "信息来源" }, "icon": "link" },
"children": [
{
"type": "LinkGroup",
"props": { "links": [] }
}
]
},
{
"type": "BrandFooter",
"props": {
"timestamp": "YYYY-MM-DDTHH:MM:SSZ",
"attribution": "Powered by Actionbook",
"disclaimer": {
"en": "This report was generated by AI using web sources. Verify critical information independently.",
"zh": "本报告由 AI 基于网络来源生成,请独立验证关键信息。"
}
}
}
]
}
论文报告模板(适用于 arXiv 论文)
分析学术论文时,请使用更丰富的模板,其中包括:
PaperHeader(标题、arxivId、日期、类别)AuthorList(作者及其所属机构)Abstract(含关键词高亮)ContributionList(主要贡献)MethodOverview(分步介绍方法)ResultsTable(实验结果)Formula(关键公式,LaTeX)Figure(来自 ar5iv 的论文图片)
可用的 json-ui 组件
| 组件 | 用途 | 关键属性 |
|---|---|---|
BrandHeader | 报告页眉 | badge、poweredBy |
PaperHeader | 论文元数据 | title、arxivId、date、categories |
AuthorList | 作者 | authors: [{name, affiliation}]、maxVisible |
Section | 主要章节 | title、icon(paper/star/bulb/chart/code/link/info/warning) |
Prose | 富文本 | content(支持 粗体、斜体、代码、列表) |
Abstract | 摘要文本 | text、highlights: ["keyword"] |
ContributionList | 编号列出的研究发现 | items: [{badge, title, description}] |
MethodOverview | 分步介绍 | steps: [{step, title, description}] |
MetricsGrid | 关键统计数据 | metrics: [{label, value, trend, suffix}]、cols |
ResultsTable | 数据表格 | columns、rows、highlights: [{row, col}] |
Table | 通用表格 | columns: [{key, label}]、rows、striped、compact |
Callout | 信息/提示/警告 | type(info/tip/warning/important/note)、title、content |
Highlight | 引用块 | type(quote/important/warning/code)、text、source |
KeyPoint | 关键发现卡片 | icon、title、description、variant |
CodeBlock | 代码片段 | code、language、title、showLineNumbers |
Formula | LaTeX 公式 | latex、block、label |
Figure | 图片 | images: [{src, alt, width}]、label、caption |
Image | 单张图片 | src、alt、caption、width |
DefinitionList | 术语/定义 | items: [{term, definition}] |
LinkGroup | 来源链接 | links: [{href, label, icon}] |
Grid | 网格布局 | cols、子项 |
Card | 卡片容器 | padding(sm/md/lg)、shadow |
TagList | 标签 | tags: [{label, color, href}] |
BrandFooter | 页脚 | timestamp、attribution、disclaimer |
json-ui 已知问题
| 问题 | 现象 | 修复方法 |
|---|---|---|
MetricsGrid.suffix 使用 i18n 对象 | text.replace is not a function | suffix 必须是纯字符串,不能是 { "en": ..., "zh": ... } |
MetricsGrid.value 使用数字 | 渲染错误 | value 必须是字符串(例如,"58.5",而不是 58.5) |
缺少 BrandHeader/BrandFooter | 报告显示异常 | 始终包含两者 |
Table 行值使用 i18n 对象 | 单元格中显示 [object Object] | 行单元格的值必须是纯字符串。列的 label 支持 i18n,但行数据不支持。请使用 "Runtimes / 运行时",而不是 { "en": "Runtimes", "zh": "运行时" } |
| Prose 内容过长 | 渲染内容被截断 | 拆分为多个 Prose 块或使用子章节 |
i18n 支持
除上文注明的情况外,所有文本字段均支持双语输出:
{ "en": "English text", "zh": "中文文本" }
对于 --lang en,使用纯文本字符串。对于 --lang zh,使用纯中文字符串。对于 --lang both(默认值),使用 i18n 对象。
例外:
MetricsGrid属性value和suffix必须始终使用纯文本字符串。Table行单元格的值必须使用纯文本字符串(列label支持 i18n,但行数据不支持)。双语内容请使用"English / 中文"格式。
学术论文支持
arXiv 论文
ar5iv.org HTML(阅读时优先使用,但对于发布未满 3 个月的论文,内容往往不完整):
| 元素 | 选择器(经 Actionbook 验证) | 可靠性 | 回退方案 |
|---|---|---|---|
| 标题 | h1.ltx_title_document | 高 | div.ltx_abstract 中包含标题上下文 |
| 作者 | div.ltx_authors | 高 | — |
| 摘要 | div.ltx_abstract | 高 | — |
| 全文 | article | 中 | 分节选择器失效时使用 |
| 章节 | section.ltx_section | 新论文中可靠性低 | 使用 article 获取全部内容 |
| 章节标题 | h2.ltx_title_section | 新论文中可靠性低 | 从 article 文本中解析 |
| 图 | figure.ltx_figure | 中 | — |
| 表格 | table.ltx_tabular | 中 | — |
| 参考文献 | .ltx_bibliography | 中 | — |
注意: 对于最近约 3 个月内提交的论文,ar5iv 通常无法完整呈现内容。请务必检查 actionbook browser text 2>&1 | wc -c——如果结果小于 5 KB,说明页面未能完整呈现。请改用其他来源。
arXiv API(通过 actionbook browser 获取元数据):
actionbook browser open "http://export.arxiv.org/api/query?id_list={arxiv_id}"
actionbook browser text
论文来源优先级建议
根据测试结果,为了最大限度地覆盖内容,请按以下优先级使用来源:
| 优先级 | 来源 | 可获取内容 | 可靠性 |
|---|---|---|---|
| 1 | arxiv.org/abs/<id> | 摘要、元数据、提交历史 | 很高 |
| 2 | huggingface.co/papers/<id> | 摘要、社区评论、相关模型/数据集 | 很高 |
| 3 | GitHub 仓库(来自搜索结果) | 包含方法细节的 README、模型库、代码 | 高 |
| 4 | HuggingFace 模型卡片 | 训练方案、基准测试结果、快速入门 | 高 |
| 5 | ar5iv.org/html/<id> | 带结构化选择器的论文全文 HTML | 中(新论文可能无法正常呈现) |
| 6 | Google Scholar / Semantic Scholar | 引用、相关工作 | 中 |
关键见解: 不要依赖单一来源。即使 ar5iv 失效,结合 arxiv 摘要、HuggingFace 和 GitHub,通常也能获取所需信息的 90% 以上。
其他学术来源
使用 actionbook browser 访问并提取以下来源的内容:
- Google Scholar(
scholar.google.com)——已由 Actionbook 编入索引,使用#gs_hdr_tsi进行搜索 - Semantic Scholar(
semanticscholar.org) - Papers With Code(
paperswithcode.com) - 会议论文集网站
Error Handling
| Error | Action |
|---|---|
| Browser fails to open | Run actionbook browser status, retry |
| Page load timeout (30s) | Skip source, try next. Common on papers.cool, slow academic sites |
| ar5iv content truncated (<5KB) | Paper too new for ar5iv. Fall back to arxiv abstract + HuggingFace + GitHub |
section.ltx_section not found | ar5iv rendering incomplete. Use actionbook browser text "article" or "main" instead |
| Actionbook selector not found | Use actionbook browser snapshot to discover actual page structure |
actionbook search returns no results | Site not indexed. Use actionbook browser snapshot to find selectors manually |
json-ui render crash (text.replace) | Check MetricsGrid suffix/value — must be plain strings, not i18n objects |
npx @actionbookdev/json-ui fails | Run npm install -g @actionbookdev/json-ui and retry with json-ui render. If still fails, try monorepo local path |
| No search results | Broaden search terms, try different angles |
| Render failed | Save JSON, tell user path, and suggest: npm install -g @actionbookdev/json-ui |
IMPORTANT: Always run actionbook browser close before finishing, even on errors.
Quality Guidelines
- Breadth: Research from at least 3-5 diverse sources
- Depth: Read full articles, not just snippets
- Accuracy: Cross-reference facts across sources
- Structure: Use appropriate json-ui components for each content type
- Attribution: Always include source links in the report
- Freshness: Prefer recent sources when relevance is equal
Chinese Content Quality Guidelines (中文内容质量规范)
CRITICAL: Chinese text must be written as native Chinese, NOT translated from English.
The zh field is not a translation — it is an independent Chinese version of the content. Write it as if authoring a Chinese tech article from scratch.
Common Problems to Avoid
| Problem | Bad Example | Good Example |
|---|---|---|
| 被动语态过多 | "Wasm 已被广泛采用" | "Wasm 已经大规模落地" |
| 英语语序直译 | "广泛但常常不可见地被采用" | "已经深入渗透到各类产品中,只是用户浑然不觉" |
| 生硬术语拼接 | "语言无关的异步通信" | "不绑定特定编程语言的异步通信机制" |
| 直译英文短语 | "关键缺失部分" | "最后一块拼图" |
| "地道"当形容词 | "地道绑定" | "符合各语言习惯的绑定" |
| 逗号长句(一逗到底) | "A,B,C,D,E。" | 拆成 2-3 个短句 |
| 引用原文硬翻 | "「许多用户并未意识到它正在被使用」" | 用中文重新表述引用的核心意思,必要时保留原文人名 |
Writing Rules
- 先写中文,再对照英文查漏:不要从英文逐句翻译。先理解内容本质,用中文重新组织表达。
- 主动语态优先:中文天然偏好主动句。"X 被 Y 采用" → "Y 采纳了 X" 或 "Y 已在用 X"。
- 短句 > 长句:中文读者偏好短句。超过 40 字的句子应拆分。
- 术语处理原则:
- 有公认中文译名的术语用中文:服务器 → 服务器、容器 → 容器、沙箱 → 沙箱
- 无公认译名的术语保留英文:Component Model、WASI、SIMD、Cold Start
- 首次出现时中英对照:「组件模型(Component Model)」,之后可只用中文
- 不要硬造中文译名(如"非干扰分析",应写"Noninterference 分析"或解释性表述)
- 数据和事实保持一致:中英文的数字、日期、引用来源必须完全一致。
- 语气自然:可以用"说白了"、"换句话说"、"简单来说"等口语化连接词,避免全篇书面腔。
- 标点规范:用中文标点(,。;:「」)而非英文标点。引号优先用「」。
Table & Short Text Rules (表格与短文本规则)
Table 行中的 "English / 中文" 格式是中文质量的重灾区。短文本更容易暴露机翻痕迹。
规则:中文部分必须是独立的中文表述,不是英文的逐词翻译。
| Bad | Why Bad | Good |
|---|---|---|
| "应用级错误处理" | 太生硬,像翻译腔 | "应用层统一报错" |
| "高性能 Web 框架" | 可以,但太平淡 | "主打性能的 Web 框架" |
| "序列化框架" | 可以接受 | "序列化框架" ✓ |
| "嵌入式异步执行器" | 太绕 | "嵌入式异步运行器" |
| "凸块分配器" | 硬造译名,没人这么说 | "Bump 分配器(arena 风格)" |
| "安全内存擦除" | 太书面 | "安全清零内存" |
| "多生产者多消费者通道" | 太长 | "MPMC 通道" |
| "类 React UI 框架" | OK | "类 React 的 UI 框架" ✓ |
表格中文短文本的核心原则:
- 保留英文术语:Bump allocator、MPMC、ECS 这些没有公认中文译名的概念,直接保留英文。别硬翻。
- 口语化 > 书面化:短文本读者扫一眼就过,要像说话一样自然。"主打性能" 比 "性能优化的" 好。
- 别逐词翻译:先理解英文描述的意思,然后用中文重新说一遍。"Full-featured datetime" → "功能齐全的时间日期库",不是 "全功能日期时间"。
- 可以省略冗余修饰:英文 "A generic serialization/deserialization framework" → 中文只需 "序列化框架"。
- 数量控制在 10 字以内:表格中文描述尽量控制在 10 个汉字以内,简短精准。
Bilingual Tone Reference
| English Tone | Chinese Equivalent | Example |
|---|---|---|
| "X has reached a critical milestone" | 不要直译"关键里程碑" | "X 迎来了重要转折点" 或 "X 进入成熟期" |
| "This is the key missing piece" | 不要直译"关键缺失部分" | "这是最后一块拼图" 或 "补上了最关键的短板" |
| "excels at cold starts" | 不要直译"在冷启动方面表现卓越" | "冷启动速度远超同类方案" |
| "security scrutiny intensifies" | 不要直译"安全审查加强" | "安全领域的关注度持续升温" |
| "emerging as a standard" | 不要直译"正成为标准" | "逐渐确立了标准地位" 或 "大有一统江湖之势" |
| "widespread but invisible adoption" | 不要直译"广泛但不可见的采用" | "已经悄然渗透到各类产品中" |