awesome-agentic-ai-zh 风格指南¶
这份指南是这份 catalog 的单一真实来源——术语、entry 结构、license 标注、写作风格、禁用词，全部以这份文件为准。
PR 之前请先读完本文。项目维护者也会用这份指南做 review。
📋 目录¶
- 1. 项目 entry schema
- 2. 推荐星等定义
- 3. 禁用词与替代
- 4. 可保留的英文名词
- 5. License 标注惯例
- 6. Stage 页面模板
- 7. Branch 页面模板
- 8. 写作风格规范
- 9. 链接与引用
1. 项目 entry schema¶
每个 project entry 统一格式如下：
### [Repo Name](https://github.com/owner/repo) ⭐⭐⭐⭐
| 字段 | 内容 |
|---|---|
| 语言 | Python |
| Stars | ★ 12k+ |
| License | MIT |
| 推荐度 | ⭐⭐⭐⭐ |
**教什么**：1-2 句话，这个 project 在这个 stage 教什么具体的东西。
**适合谁**：1 句话，谁应该读这个、为什么。
**备注**：1-3 句个人评价。哪里好、哪里弱、哪里可以跳。（可省略）
**怎么跑**：
```bash
# 最小安装指令、第一次跑该执行什么
### 必填字段（GitHub repo entry）
对“真实 GitHub repo”的 entry：
- `Stars`（★ Xk+ 格式，无千位逗号）
- `License`（SPDX ID 或标注例外，见 5）
- `推荐度`（⭐ × N，见 2）
- `教什么`、`适合谁`
### 必填字段（非 repo entry：article / course / video / protocol / documentation）
某些 entry 不是 GitHub repo 而是文章、视频、官方文件、catalog hub。对此类：
- `推荐度`（必填）
- `教什么`、`适合谁`（必填）
- `形式`（必填，标明是 `文章` / `视频` / `课程` / `精选列表` / `规格文件` 等）
- `Stars` / `License` 可省略（没有 GitHub repo 对应）
范例：`Anthropic — Building Effective Agents` 部落格文章用 `形式 = 文章` + 推荐度，不需要 Stars / License。
### 选填字段
- `语言` — 主要编程语言（Python / TypeScript / 中文 等）
- `最后更新` / `状态` — 已停滞或维护放缓时加注
- `备注`、`怎么跑`
### 标题格式
- Stage 1-4 / 6 用 `### [Repo](url)`
- Stage 5 / 7 / branches 用 `#### [Repo](url)`（已有上层 H3 分类时）
- 标题后可接星等：`### [Repo](url) ⭐⭐⭐⭐⭐` 或副标题：`### [Repo](url) ⭐ 官方`
---
## 2. 推荐星等定义
| 星等 | 含义 | 何时用 |
|---|---|---|
| ⭐⭐⭐⭐⭐ | 必读 / 必做 | 该 stage 不读这个会卡住 |
| ⭐⭐⭐⭐ | 强烈建议 | 深入学该主题的好材料 |
| ⭐⭐⭐ | 扎实范例 | 值得跑一遍、互相对照 |
| ⭐⭐ | 有用参考 | 有兴趣再看 |
| ⭐ | 利基 / 进阶 / C 完整性 | 多数学者可跳 |
**准则**：
- 同一个 repo 出现在不同 stage / branch 时，**星等应一致**（除非有明确 audience-specific 理由，且注明在备注）
- 不要因为“想要看起来推荐”就给高星等。诚实 > 客气
- 商业产品（Cursor、LangSmith 等）也照同一套标准
---
## 3. 禁用词与替代
这份文件以**简体中文（zh-Hans，中国大陆惯例）** 为准。下表列出常见的 zh-TW 用词与替代。
> 📌 **语言代码惯例（BCP 47 / W3C i18n）**：repo 用 `.zh-Hans.md`（不是 `.zh-CN.md`）标记简体中文档。`Hans` / `Hant` 是 [BCP 47 script subtag](https://www.w3.org/International/articles/language-tags/)，跟地区解耦——简体中文不只用在中国大陆（也用在新加坡、马来西亚），用 `Hans` 比 `CN` 更准确。canonical README 的内容是 **zh-Hant-TW**（繁体中文，台湾惯例），但档名保持无 suffix 的 `README.md` 作为 GitHub 默认首页。未来若要分地区可再扩成 `zh-Hans-CN` / `zh-Hant-HK` 等。感谢 [@xfq](https://github.com/xfq)（W3C i18n lead）在 [#9](https://github.com/WenyuChiou/awesome-agentic-ai-zh/issues/9) 指出这个问题。
### 繁简用词替换
| 禁用（zh-TW） | 改用（zh-Hans） |
|---|---|
| 使用者 | 用户 |
| 軟體 | 软件 |
| 資料 | 数据 |
| 專案 | 项目 |
| 腳本 | 脚本 |
| 預設 | 默认 |
| 設定 | 设置 |
| 連結 | 链接 |
| 練習 | 练习 |
| 動手 | 动手 |
| 飛書 | 飞书 |
| 個 | 个 |
| 兩 | 两 |
| “” | "" |
| 整合 | 集成 |
| 系統 | 系统 |
| 點 | 点 |
| 為 | 为 |
| 過 | 过 |
| 還 | 还 |
### Overclaim（夸大）用语禁用
| 禁用 | 改用 |
|---|---|
| 全世界最好的 / 业界最强 | 完整的 / 知名的 / 广泛使用的 |
| production-grade（描述教材时） | 教学导向 / 用来学 production pattern 的教材 |
| 首选 / 唯一选择 | 不错的选项 / 入门选择之一 |
| 最紧迫 / 最重要 | （直接不要修饰） |
| 权威参考（除非真的是官方 spec） | 重要参考实作 / 官方范本 |
| 没问题（法律或 license 判断时） | 使用前先读条款 / 条款还是要自己看过 |
### 中夹英（English-in-Chinese）禁用句型
| 禁用 | 改用 |
|---|---|
| follow 条款 | 遵守条款 |
| ready-made 教材 | 现成可改的教材 |
| NotebookLM-like 工具 | 类 NotebookLM 的工具 / 类似 NotebookLM 的工具 |
| 视觉化 node-based | 视觉化节点式 |
| Anthropic host 的 server | Anthropic 维护的 server |
| coding 流程 | 开发流程 / 程序开发流程 |
---
## 4. 可保留的英文名词
技术写作中**保留英文**比硬翻译读起来更自然的词：
- `LLM`、`API`、`SDK`、`MCP`
- `agent`、`tool use`、`function calling`、`prompt`、`prompt caching`
- `framework`、`library`、`repo`、`commit`、`PR`、`branch`
- `RAG`、`embedding`、`vector DB`、`retrieval`、`chunk`、`token`
- `streaming`、`async`、`batch`、`webhook`
- `marketplace`、`plugin`、`skill`、`hook`
- `project`、`repo` （可保留也可改用“项目”）
- `production`（指“正式环境”时）— 但本 catalog 多数场合刻意避免（见 3）
- `动手练习`、`hello-world` — 保留
**判准**：技术文件圈读者习惯的英文术语就保留，避免“太政治正确的中文化”。
---
## 5. License 标注惯例
### 常见 license 直写
- `MIT`
- `Apache-2.0`
- `BSD-3-Clause`
- `GPL-3.0`
- `LGPL-3.0`
### 需要加注的特殊情况
| 情况 | 写法 |
|---|---|
| 上游无 SPDX | `NOASSERTION（上游未提供 SPDX；使用前请读 LICENSE）` |
| AGPL（传染性） | `AGPL-3.0` + 备注：`AGPL-3.0 license（传染性开源）— 修改后散布的衍生产品需遵守条款。` |
| 自定义非商用 | `NOASSERTION（自定义非商用）` + 备注：`License 是自定义非商用条款，使用前请先读原始条款。` |
| 多元 license（每个 plugin 自己有） | `NOASSERTION（每个 plugin 独立 license，请看各自目录）` |
| Creative Commons | 直写 `CC-BY-4.0`、`CC-BY-NC-SA-4.0` 等 |
**规则**：**永远不要**把 license 解读成法律建议。“研究 / 个人使用没问题”这种句子禁用。改成“使用前先读原始条款”。
---
## 6. Stage 页面模板
> 同一个模板适用于两个位置：
> - `stages/0X-*.md` — 共用基础（0-2）+ Track B（Stage 3-7）
> - `tracks/cli/AX-*.md` — Track A（A1-A3）的 sub-stage，也照同一模板，只是 cross-link 比例较高（多数 entry 引用既有 Stage 5 / 7 / cli-agents-guide）
每个 stage（Stage 0 除外）都应该有：
```markdown
# Stage N — 主题
> [English](./0N-slug.en.md) | **简体中文**
⏱ **时间估算**：N-M 周（约 X-Y 小时）
[1-2 句话描述这个 stage 的核心问题]
## 📌 学习目标
- bullet 1
- bullet 2
...
## 🚪 进入条件（Stage 1+ 才需要）
你应该已经：
- ...
## 📚 必修阅读
1. [链接](url) — 描述
2. ...
## 🛠 动手练习（不是看过就好）
### 练习 N：标题
描述。
[3-5 个动手练习 items]
## 🎯 精选 Projects
### [Project Name](url) ⭐⭐⭐⭐
[entry schema 见 1]
[N 个 entries]
## ✅ 进 Stage N+1 前的自我检查
你能不能：
- [ ] ...
- [ ] ...
如果可以 → 进 Stage N+1。
如果不行 → ...
## 💡 接下来（选填，多在最后一个 stage 用）
Stage 0 例外：可以省略 精选 Projects、进入条件，因为它是 prerequisite gateway。
7. Branch 页面模板¶
# 给 [audience] — 专业分支
> [English](./for-X.en.md) | **简体中文**
> [← 回主路线 README](../README.md) · 从 Stage 7 结尾分支出来
## 使用情境
- bullet 1
- bullet 2
## 精选 Projects
### 子分类 1
#### [Project](url) ⭐⭐⭐⭐
[entry]
### 子分类 2
...
## 必修阅读
1. ...
## 必练流程
- bullet 1
- bullet 2
Branch 的 entry 格式可以比 stage 简洁（不一定要完整 schema 表格），但链接 + 星等 + 1-2 句描述是最低门槛。
8. 写作风格规范¶
句长¶
- 单句不超过 60 字（中文标点计入）
- 太长就断成两句
- 英文 rhythm 强迫塞进中文 = 翻译腔，要避免
标点¶
- 中文用全角：，。：；“”（）
- 句中夹英文时，英文前后可以留空格也可以不留，但全文要一致
- 避免 ASCII 逗号
,在中文句中（会中夹英）
主动 vs 被动¶
- 偏主动句：“Claude 调用工具” ✓
- 避免被动句：“工具被 Claude 调用” ✗
“你” vs “我们”¶
- “你”优先——这是给读者的学习材料
- “我”用于作者发表意见时：“我建议...”
- 避免“我们”（除了合著者实际存在的场合）
连接词¶
- 偏好简单：“但、所以、因为、不过”
- 避免：“然而、因此、由于、之所以”
9. 链接与引用¶
内部链接¶
- Stage 之间：相对路径
[Stage 4](./04-agent-frameworks.zh-Hans.md) - Branch ↔ README：
[← 回主路线](../README.md) - 跨 stage 引用同一 repo：用全名 + 链接，不要只写“之前提过”
外部链接¶
- GitHub repo：
https://github.com/owner/repo✓ 不加 trailing slash - 文章 / 部落格：完整 URL，标题用粗体
- 商业产品（Cursor、Make.com 等）：用官方网址，不是 affiliate
链接文字惯例¶
- Repo entry 标题：
[owner/repo](url)或[Project Name](url) - 句中引用：
[Repo Name](url)或owner/repo（短引用用 inline code） - 链接文字避免“点这里”、“按这个”
相关内部设计文件¶
这份 style-guide 讲“entry 怎么写”。为什么分这 5 个 branch、为什么是 7 个 stage 这类设计理由，见：
branches/DESIGN.md—branch 设计笔记（为什么这样切、entry 该放哪）stages/DESIGN.md—stage 设计笔记（为什么这结构、动手练习 怎么挑）cli-agents-guide.zh-Hans.md—cross-cutting CLI agent 比较指南
修改本指南¶
这份指南本身也欢迎 PR。修改前请先开 Issue 讨论——术语决策影响 100+ 个 entry。
当前 maintainer：@WenyuChiou。