@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/documentation-writer/references/readme.md

@@ -0,0 +1,89 @@
+# README
+
+README 是项目的门面，读者多半是第一次来，只想在几分钟内回答三个问题：这是什么，跟我有没有关系，怎么跑起来。写的时候照着这三个问题排优先级，其余内容能链接出去就链接出去。
+
+## 目录
+
+- [先判断是哪种 README](#先判断是哪种-readme)
+- [新建 README](#新建-readme)
+- [更新 README](#更新-readme)
+- [变更映射](#变更映射)
+- [常见问题](#常见问题)
+
+## 先判断是哪种 README
+
+| 类型 | 重点 | 通常不需要 |
+|---|---|---|
+| 应用 / 服务 | 怎么在本地跑起来、依赖哪些服务、有哪些环境变量、端口 | 安装到别的项目里的说明 |
+| 库 / SDK / CLI | 安装、最小可用示例、主要 API 或命令一览、兼容版本 | 部署说明 |
+| monorepo 根目录 | 仓库是什么、子包地图、公共命令、去哪里找每个子包的文档 | 每个子包的细节 |
+| monorepo 子包 | 这个包在整体里的位置、自己的启动与测试命令、和其他包的依赖 | 重复根 README 的通用说明，链接回去即可 |
+
+monorepo 子包的 README 开头写一句它在整个仓库里是干什么的，并链接到根 README；公共的安装步骤不要再抄一遍。
+
+## 新建 README
+
+### 动笔前核实
+
+- 项目名称和一句话定位：从 manifest 的 `name` / `description`、入口代码、已有文档里找。
+- 运行时和版本：`engines`、`.nvmrc`、`.tool-versions`、`go.mod`、`pyproject.toml` 的 `requires-python`、Dockerfile 的 `FROM`。
+- 命令：只写 `package.json` 的 `scripts`、`Makefile`、`justfile`、CI 配置里真实存在的。能跑的最好跑一下安装和启动命令确认；跑不了就不要编造输出。
+- 环境变量：`.env.example` / `.env.template` / `.env.sample`，以及代码里读取环境变量的位置（`process.env.X`、`os.getenv`、`env.X` 的配置模块）。以代码实际读取的为准，模板里有但代码不用的，不写或注明。
+- 端口、依赖服务（数据库、Redis、消息队列）：从配置文件、docker-compose、启动脚本里找。
+
+### 章节结构
+
+按顺序，缺的就不写，不要为了完整留空章节：
+
+1. **标题 + 一两句话**：是什么、给谁用、解决什么问题。不写口号。
+2. **快速开始**：前置条件（带版本）→ 安装 → 配置 → 启动 → 怎么确认跑起来了（打开哪个地址、看到什么输出、调哪个健康检查接口）。每一步是一条可复制的命令。
+3. **用法**：最常见的一两个场景的真实例子。库给代码示例，服务给一个请求示例，CLI 给一条命令和它的输出。
+4. **配置**：环境变量用表格，列「变量 | 必填 | 默认值 | 说明」。默认值从代码里取。
+5. **开发**：测试、lint、类型检查、构建命令；怎么只跑一个测试。
+6. **项目结构**：只在目录不直观时写，每个目录一行说明，只列重要的。
+7. **更多文档**：API 文档、架构文档、用户手册的链接。
+8. **贡献 / 许可证**：仓库里有 `CONTRIBUTING`、`LICENSE` 才写，一两行加链接。
+
+徽章（CI 状态、覆盖率、版本）只在对应服务真实存在时加，不加装饰性徽章。截图只用仓库里已有的图片或用户提供的；没有就不放，不要写一个指向不存在文件的图片链接。
+
+### 例子
+
+不好的开头：
+
+> 🚀 **Invoice Service** 是一款强大的、一站式的发票管理解决方案，致力于为企业赋能，助力财务数字化转型！
+
+好的开头（虚构项目，仅示意写法）：
+
+> Invoice Service 负责开票、作废和红冲，供订单系统和财务后台调用。它从订单服务拉取已支付订单，按税率配置生成发票，再推送到税务平台；本地开发需要 PostgreSQL 15 和一个 Redis。
+
+## 更新 README
+
+1. 通读现有 README，记下它的结构、语气、术语、emoji 与格式习惯。
+2. 找出变化：用户描述的改动、`git diff`、`git log -p --since=<上次更新> -- <相关路径>`。README 本身的最后修改时间可以用 `git log -1 --format=%ad -- README.md` 查，之后的提交都是候选。
+3. 用下面的「变更映射」确定要动哪些章节。
+4. 逐条核对现有 README 里的每条命令、每个环境变量、每个版本号是否还成立，过时的改掉或删掉。
+5. 保持原有风格。原文用 emoji 的继续用，原文用英文标题的继续用英文标题。新增内容和原文读起来要像一个人写的。
+6. 缺失但重要的章节（例如没有环境变量说明）可以补，补之前在交付说明里说明为什么补。
+
+## 变更映射
+
+| 代码里的变化 | README 里要看的地方 |
+|---|---|
+| 新增 / 删除依赖、升级运行时版本 | 前置条件、安装 |
+| `package.json` scripts、`Makefile` 目标变化 | 快速开始、开发 |
+| `.env.example` 或代码读取的环境变量变化 | 配置 |
+| `docker-compose.yml`、依赖服务变化 | 快速开始（要先起哪些服务） |
+| 新增 / 删除路由、命令、公开 API | 用法、功能概述、API 文档链接 |
+| 端口、默认地址变化 | 快速开始里的访问地址 |
+| 目录重组、包拆分或合并 | 项目结构、monorepo 子包地图 |
+| 新功能上线、旧功能下线 | 功能概述、用法；下线的要删掉，不要只加不减 |
+| 许可证、贡献流程变化 | 许可证、贡献 |
+
+同一个改动如果还影响 API 文档或用户手册，一并提醒用户，或者按对应参考文件一起更新。
+
+## 常见问题
+
+- **README 写成了架构文档**：README 里的架构说明控制在一段话加一张简图以内，细节链接到架构文档。
+- **把所有环境变量都列进来**：只列运行需要配置的；内部调试用的开关放到开发文档里。
+- **快速开始跑不通**：最常见的原因是漏了前置服务（数据库没起）、漏了迁移、漏了 `.env` 复制。按一个全新环境的视角从头走一遍步骤。
+- **只加不删**：删掉已经不存在的命令、参数和功能描述，比加新内容更重要。

package/skills/documentation-writer/references/stack-detection.md

@@ -0,0 +1,134 @@
+# 技术栈识别
+
+技术栈不明确时读这份：多种 manifest 并存、文件扩展名陌生、找不到明显的 `package.json` / `go.mod`。
+
+---
+
+## Manifest 文件 → 生态
+
+| 文件 | 生态 | 重点看的字段 |
+|------|-----------|--------------------|
+| `package.json` | Node.js / JavaScript / TypeScript | `dependencies`, `devDependencies`, `scripts`, `main`, `type`, `engines` |
+| `go.mod` | Go | Module path, Go version, `require` block |
+| `requirements.txt` | Python (pip) | Package list with pinned versions |
+| `Pipfile` | Python (pipenv) | `[packages]`, `[dev-packages]`, `[requires]` python version |
+| `pyproject.toml` | Python (poetry / uv / hatch) | `[tool.poetry.dependencies]`, `[project]`, `[build-system]` |
+| `setup.py` / `setup.cfg` | Python (setuptools, legacy) | `install_requires`, `python_requires` |
+| `Cargo.toml` | Rust | `[dependencies]`, `[[bin]]`, `[lib]` |
+| `pom.xml` | Java / Kotlin (Maven) | `<dependencies>`, `<artifactId>`, `<groupId>`, `<java.version>` |
+| `build.gradle` / `build.gradle.kts` | Java / Kotlin (Gradle) | `dependencies {}`, `sourceCompatibility` |
+| `composer.json` | PHP | `require`, `require-dev` |
+| `Gemfile` | Ruby | `gem` declarations, `ruby` version constraint |
+| `mix.exs` | Elixir | `deps/0`, `elixir: "~> X.Y"` |
+| `pubspec.yaml` | Dart / Flutter | `dependencies`, `dev_dependencies`, `environment.sdk` |
+| `*.csproj` | .NET / C# | `<PackageReference>`, `<TargetFramework>` |
+| `*.sln` | .NET solution | References multiple `.csproj` projects |
+| `deno.json` / `deno.jsonc` | Deno (TypeScript runtime) | `imports`, `tasks` |
+| `bun.lockb` | Bun (JavaScript runtime) | Binary lockfile — check `package.json` for deps |
+| `bun.lock` | Bun (JavaScript runtime) | Text lockfile (Bun 1.2+) — check `package.json` for deps |
+
+---
+
+## 运行时版本在哪里
+
+| 语言 | 版本写在哪 |
+|----------|--------------------------|
+| Node.js | `.nvmrc`, `.node-version`, `engines.node` in `package.json`, Docker `FROM node:X` |
+| Python | `.python-version`, `pyproject.toml [requires-python]`, Docker `FROM python:X` |
+| Go | First line of `go.mod` (`go 1.21`) |
+| Java | `<java.version>` in `pom.xml`, `sourceCompatibility` in `build.gradle`, Docker `FROM eclipse-temurin:X` |
+| Ruby | `.ruby-version`, `Gemfile` `ruby 'X.Y.Z'` |
+| Rust | `rust-toolchain.toml`, `rust-toolchain` file |
+| .NET | `<TargetFramework>` in `.csproj` (e.g., `net8.0`) |
+
+---
+
+## 框架识别（Node.js / TypeScript）
+
+| `package.json` 里的依赖 | 框架 |
+|-----------------------------|-----------|
+| `express` | Express.js (minimal HTTP server) |
+| `fastify` | Fastify (high-performance HTTP server) |
+| `next` | Next.js (SSR/SSG React — check for `pages/` or `app/` directory) |
+| `nuxt` | Nuxt.js (SSR/SSG Vue) |
+| `@nestjs/core` | NestJS (opinionated Node.js framework with DI) |
+| `koa` | Koa (middleware-focused, no built-in router) |
+| `@hapi/hapi` | Hapi |
+| `hono` | Hono (lightweight, multi-runtime HTTP framework) |
+| `elysia` | Elysia (Bun-first HTTP framework, TypeBox schemas via `t`) |
+| `@trpc/server` | tRPC (type-safe API without REST/GraphQL schemas) |
+| `routing-controllers` | routing-controllers (decorator-based Express wrapper) |
+| `typeorm` | TypeORM (SQL ORM with decorators) |
+| `prisma` | Prisma (type-safe ORM, check `prisma/schema.prisma`) |
+| `mongoose` | Mongoose (MongoDB ODM) |
+| `sequelize` | Sequelize (SQL ORM) |
+| `drizzle-orm` | Drizzle (lightweight SQL ORM) |
+| `react` without `next` | Vanilla React SPA (check for `react-router-dom`) |
+| `vue` without `nuxt` | Vanilla Vue SPA |
+
+---
+
+## 框架识别（Python）
+
+| 包 | 框架 |
+|---------|-----------|
+| `fastapi` | FastAPI (async REST, auto OpenAPI docs) |
+| `flask` | Flask (minimal WSGI web framework) |
+| `django` | Django (batteries-included, check `settings.py`) |
+| `starlette` | Starlette (ASGI, often used as FastAPI base) |
+| `aiohttp` | aiohttp (async HTTP client and server) |
+| `sqlalchemy` | SQLAlchemy (SQL ORM; check for `alembic` migrations) |
+| `alembic` | Alembic (SQLAlchemy migration tool) |
+| `pydantic` | Pydantic (data validation; core to FastAPI) |
+| `celery` | Celery (distributed task queue) |
+
+---
+
+## Monorepo 识别
+
+按顺序检查这些信号：
+
+1. `pnpm-workspace.yaml` — pnpm workspaces
+2. `lerna.json` — Lerna monorepo
+3. `nx.json` — Nx monorepo (also check `workspace.json`)
+4. `turbo.json` — Turborepo
+5. `rush.json` — Rush (Microsoft monorepo manager)
+6. `moon.yml` — Moon
+7. `package.json` with `"workspaces": [...]` — npm/yarn workspaces
+8. Presence of `packages/`, `apps/`, `libs/`, or `services/` directories with their own `package.json`
+
+确认是 monorepo 后：每个 workspace 的依赖和约定可能**各自独立**。在 `STACK.md` 里分别写每个子包，在 `STRUCTURE.md` 里说明 monorepo 结构。
+
+---
+
+## TypeScript 路径别名
+
+`tsconfig.json` 里有 `paths` 时，非相对路径前缀的导入是别名。写结构前先映射成真实路径。
+
+```json
+// tsconfig.json 示例
+"paths": {
+  "@/*": ["./src/*"],
+  "@components/*": ["./src/components/*"],
+  "@utils/*": ["./src/utils/*"]
+}
+```
+
+`import { foo } from '@/utils/bar'` 实际指向 `src/utils/bar`。文档里写 `src/utils/bar`，不写 `@/utils/bar`。
+
+---
+
+## Docker 基础镜像 → 运行时
+
+没有 manifest 但有 `Dockerfile` 时，`FROM` 行能看出运行时：
+
+| FROM 行 | 运行时 |
+|------------------|---------|
+| `FROM node:X` | Node.js X |
+| `FROM python:X` | Python X |
+| `FROM golang:X` | Go X |
+| `FROM eclipse-temurin:X` | Java X (Eclipse Temurin JDK) |
+| `FROM mcr.microsoft.com/dotnet/aspnet:X` | .NET X |
+| `FROM ruby:X` | Ruby X |
+| `FROM rust:X` | Rust X |
+| 只有 `FROM alpine` | 看 `RUN apk add` 装了什么 |

package/skills/documentation-writer/references/user-manual.md

@@ -0,0 +1,103 @@
+# 用户手册、教程与操作指南
+
+读者是用产品的人，不是写代码的人：业务用户、管理员、运营，或者部署维护系统的运维。他们不关心代码在哪，只关心「我要做 X，该点哪里、填什么、会发生什么」。但手册里的每句话仍然要从代码里核实，因为界面上的按钮名、字段限制、权限规则都写在代码里，凭印象写的手册会和产品对不上。
+
+## 目录
+
+- [先定读者和文档类型](#先定读者和文档类型)
+- [从代码里取事实](#从代码里取事实)
+- [手册结构](#手册结构)
+- [写步骤的规矩](#写步骤的规矩)
+- [截图和图](#截图和图)
+- [运维手册](#运维手册)
+- [自检](#自检)
+
+## 先定读者和文档类型
+
+| 读者 | 典型文档 | 语气 |
+|---|---|---|
+| 第一次用的业务用户 | 快速上手教程 | 一步一个结果，不讲原理 |
+| 日常使用者 | 按任务组织的操作指南 | 直接给步骤 |
+| 管理员 | 配置与权限指南 | 讲清每个设置的影响范围 |
+| 运维 | 部署、升级、备份、故障处理手册 | 命令精确，写清前置条件和回滚方式 |
+
+不同角色看到的界面和能做的事不同。按角色区分章节，或者在每个操作开头写明「需要的角色」。
+
+## 从代码里取事实
+
+| 要写的 | 去哪里找 |
+|---|---|
+| 页面和菜单的名字、入口路径 | 前端路由配置、导航 / 菜单定义、页面组件 |
+| 按钮、字段、提示文字的**原文** | 国际化文件（`locales/`、`i18n/`、`messages/`）；没有 i18n 就看组件里的字面量。界面文字要和产品完全一致，不要意译 |
+| 字段是否必填、长度、格式、取值范围 | 前端表单校验和后端校验 schema，两边不一致时以更严的为准，并告诉用户这个不一致 |
+| 谁能做什么 | 权限 / 角色定义、路由守卫、后端鉴权中间件 |
+| 操作之后会发生什么 | 后端 handler：状态变化、通知、邮件、审批流转 |
+| 状态和流转规则 | 状态枚举、状态机代码 |
+| 报错提示和原因 | 错误码表、i18n 里的错误文案、抛出错误的地方 |
+| 数量限制、配额 | 常量、套餐配置、租户设置 |
+
+写之前可以在交付说明里列出「手册依据的代码位置」，但手册正文里不放文件路径和行号，读者用不上。
+
+## 手册结构
+
+按 Diátaxis 分成几块，各写各的，不要在教程里插长篇解释，也不要在参考表里夹操作步骤：
+
+1. **概述**：这个产品或模块能帮你做什么，适合谁用，一两段话。列出主要功能，每项一句话。
+2. **快速上手（教程）**：带新用户完整走通一件最典型的事，从登录或打开页面开始，到看到结果为止。只走一条路，不讲分支。
+3. **操作指南**：按任务组织，标题用动词开头，写用户要做的事：「提交工时」「审批请假」「导出月度报表」，不用「工时模块介绍」。每个任务独立成节，读者可以直接跳过去看。
+4. **参考**：字段说明表、状态说明表、角色权限表、限制与配额。
+5. **常见问题与故障排查**：从错误提示反推，写「看到 X 提示 → 原因 → 怎么办」。只写代码里真实存在的错误，不编造问题。
+
+小产品可以合并成一篇；功能多的按模块拆成多篇，加一个目录页。
+
+## 写步骤的规矩
+
+- 一步一个动作，用祈使句：「点击「提交」。」不写「用户可以通过点击提交按钮来完成提交操作」。
+- 界面文字用「」括起来（英文文档用 **粗体**），和产品上的文字一字不差。
+- 路径写全：「进入「设置」→「团队成员」」。
+- 关键步骤后写预期结果：「页面顶部出现「已提交，等待审批」。」读者靠它确认自己没走错。
+- 有前置条件的写在最前面：需要的角色、需要先完成的配置。
+- 可能出错的地方就地提醒，一句话说清原因和解决办法，不要全堆到最后。
+- 不写「只需」「轻松」「简单地」，对卡住的读者来说这些词没用，还让人烦。
+- 字段说明写「填什么、格式、限制」，不写「请填写正确的值」。
+
+例子：
+
+> **提交报销单**
+>
+> 需要的角色：员工
+>
+> 1. 在左侧菜单点击「费用报销」，再点击右上角「新建报销」。
+> 2. 选择「费用类型」，填写「金额」。金额最多两位小数，单笔不超过 50,000。
+> 3. 在「附件」里上传发票图片，支持 JPG、PNG、PDF，单个文件不超过 10 MB。
+> 4. 点击「提交审批」。
+>
+> 提交后报销单状态变为「审批中」，不能再修改。需要修改的话，请审批人点击「退回」。
+
+（示例为虚构产品，只示意写法。）
+
+## 截图和图
+
+- 截图不能编造。仓库里已有截图，或者用户提供了，才引用。需要截图但没有的，在对应位置写 `[TODO: 截图 - 「页面名」页面，标出「按钮名」]`，交付时统一告诉用户要补哪些。
+- 能在本地把应用跑起来、并且有浏览器自动化工具时，可以自己截图；截图里不要出现真实的个人信息。
+- 流程类内容（审批流、提交流程）和状态类内容（单据状态流转）适合配图，按 SKILL.md 的「出图」一节处理：审批流、多角色协作流程用 archify 的 `workflow`，状态流转用 `lifecycle`；没有 archify 用 Mermaid。面向业务用户的图，节点名用界面上的叫法，不用代码里的枚举名。
+
+## 运维手册
+
+读者是部署和维护系统的人，要求和用户手册不同：
+
+- 每个操作写清：前置条件、完整命令、预期输出、怎么确认成功、失败了怎么回滚。
+- 命令只写在脚本、CI、部署配置里真实存在的；环境相关的值（主机名、路径）用占位符并说明从哪里取。
+- 按场景组织：首次部署、升级、备份与恢复、扩容、常见故障处理、日志在哪看。
+- 危险操作（删数据、重置、迁移）单独标出来，写清影响范围。
+- 部署拓扑、发布流程适合配图：拓扑用 archify 的 `architecture`，发布步骤用 `workflow`。
+
+## 自检
+
+- [ ] 每个界面文字都和 i18n 文件或组件里的原文一致
+- [ ] 每个操作写了需要的角色
+- [ ] 字段限制和校验代码一致
+- [ ] 教程从头到尾走得通，没有跳步
+- [ ] 常见问题里的每个错误提示在代码里都能找到
+- [ ] 没有编造的截图链接
+- [ ] 正文没有文件路径和行号

package/skills/documentation-writer/references/writing-style.md

@@ -0,0 +1,220 @@
+# 写作风格：去 AI 味
+
+AI 写的技术文档有一股很好认的味道：每节一个模子、形容词堆砌、什么都「强大」「无缝」、结尾必有总结。读者一闻到这个味道，就会怀疑内容也是凑的，哪怕事实都对。
+
+技术文档去 AI 味，方向和散文不一样。散文靠加观点、加个性、加第一人称；技术文档靠**具体、直接、可核对**：用数字代替形容词，用行为代替评价，用读者要做的动作代替空泛的介绍。参考文档不需要个性，需要的是准确和一致。
+
+## 目录
+
+- [1. 结构的模子](#1-结构的模子)
+- [2. 夸大和宣传腔](#2-夸大和宣传腔)
+- [3. AI 高频词](#3-ai-高频词)
+- [4. 句法层面的习惯](#4-句法层面的习惯)
+- [5. 节奏和格式](#5-节奏和格式)
+- [6. 含糊、填充、聊天腔](#6-含糊填充聊天腔)
+- [7. 连接词](#7-连接词)
+- [8. 技术文档特有的毛病](#8-技术文档特有的毛病)
+- [技术文档里合适的「人味」](#技术文档里合适的人味)
+- [该保留的](#该保留的)
+- [改写示例](#改写示例)
+- [快速自检](#快速自检)
+
+## 1. 结构的模子
+
+AI 喜欢套公式。最显眼，先改。
+
+**症状**
+- 每节都是「引入一句 + 三点列表 + 小结一句」
+- 每节结尾都有「总之」「由此可见」「这意味着」
+- 每个列表恰好三条，或者条数都一样
+- 文末固定来一节「总结与展望」「未来规划」「挑战与机遇」
+- 「尽管 X 很强，但也面临挑战……尽管如此，X 仍然……」这种来回绕
+
+**改法**
+- 节的长短跟着内容走。有的节两句话，有的节一整页。
+- 讲完就停，不给每节系蝴蝶结。
+- 列表条数就是真实的条数，四条就四条，一条就别用列表。
+- 删掉总结、展望式结尾。真有后续计划，写具体的：「v2.0 计划移除 `legacyAuth`，见 #123」。
+
+## 2. 夸大和宣传腔
+
+技术文档不是新闻稿。
+
+**中文**：赋能、助力、打造、构建（滥用时）、一站式、全方位、多维度、全链路（非技术含义时）、极致、卓越、领先、业界一流、革命性、颠覆、重塑、引领、里程碑、具有重要意义、至关重要、不可或缺、坚实的基础、保驾护航、为……注入新活力、开启……新篇章
+
+**英文**：stands as / serves as a testament、pivotal、groundbreaking、revolutionize、cutting-edge、world-class、best-in-class、game-changer、state-of-the-art、marks a shift、setting the stage for
+
+**改法**：不是换个近义词，而是删掉，换成事实。删完句子不成立，说明原来就没有内容。
+
+> 改前：本平台致力于为企业打造一站式、全方位的数据治理解决方案，助力企业数字化转型。
+>
+> 改后：本平台从 MySQL、PostgreSQL 和 Kafka 采集元数据，按表和字段记录血缘，字段变更时通知下游负责人。
+
+## 3. AI 高频词
+
+单独出现一次不算问题，扎堆出现就是味道。
+
+### 中文
+
+| AI 常用 | 改成 |
+|---|---|
+| 旨在、致力于 | 直接说做什么：「用于」「负责」，或者删掉 |
+| 扮演着……的角色、发挥着……的作用、起到……作用 | 「是」「负责」「用来」 |
+| 强大的、丰富的、灵活的、高效的 | 删掉，或者给出具体能力、数字 |
+| 无缝集成、无缝衔接 | 说清怎么集成：「通过 Webhook 推送」 |
+| 显著提升、极大地提高、大幅优化 | 给数字：「P99 从 800 ms 降到 120 ms」；没有数字就删 |
+| 深入探讨、全面解析、一文读懂 | 删掉，直接开始讲 |
+| 核心、关键（一段里出现多次） | 留一个真正核心的，其余删 |
+| 生态（非技术含义）、闭环、抓手、底层逻辑、颗粒度、沉淀、打通 | 说具体的东西 |
+| 开箱即用 | 确实零配置可用才写，否则写需要哪些配置 |
+| 高性能、高可用、高扩展 | 有测试数据或部署设计支撑才写，并给出依据 |
+
+### 英文
+
+| AI 常用 | 改成 |
+|---|---|
+| delve into | look at，或者删掉 |
+| leverage、harness、utilize | use |
+| seamless、seamlessly | 说清怎么连 |
+| robust、comprehensive、powerful | 删掉，或给具体能力 |
+| streamline | simplify、cut steps |
+| navigate（比喻） | handle、deal with |
+| landscape、realm、ecosystem（非技术） | 删掉或说具体领域 |
+| myriad、plethora | many |
+| facilitate | help、let |
+| empower | let、allow |
+| tapestry、testament、paradigm shift | 删掉 |
+
+## 4. 句法层面的习惯
+
+**绕开「是」**：「作为……而存在」「扮演着……的角色」「构成了……的基础」扎堆出现，就改回「是」「有」「负责」。英文的 serves as、stands as、functions as、boasts 同理。
+
+**空洞的尾巴**：句子结尾挂一个「从而……」「进而……」「体现了……」「彰显了……」「为……奠定了基础」，英文是 highlighting、underscoring、ensuring、fostering。删掉，或者拆成单独一句并给出依据。
+
+> 改前：该模块采用事件驱动架构，从而实现了各服务之间的解耦，进而提升了系统的可维护性。
+>
+> 改后：订单服务处理完支付后发布 `order.paid` 事件，库存服务和通知服务各自订阅，订单服务不直接调用它们。
+
+**否定式排比**：「不仅……更……」「不是……而是……」「It's not just X, it's Y」。一篇文档用一次足够。
+
+**凑三**：「高效、稳定、易用」「快速、安全、可靠」，第三个往往是凑的。真有三个就写三个，只有两个就写两个。
+
+**同义词轮换**：AI 为了避免重复，会把同一个东西依次叫「租户」「组织」「空间」「团队」。技术文档里这是灾难，读者会以为是四个东西。一个概念一个名字，从头用到尾；和代码里的叫法对应，第一次出现时可以括号注明代码名：租户（`tenant`）。
+
+**假范围**：「从小型团队到大型企业」「从开发到上线」，两端不在一个尺度上。直接列出具体支持的场景。
+
+## 5. 节奏和格式
+
+**句子长度一个样**：每句都是二三十字的中等长句，读起来像节拍器。长短交替，该短就短：「这一步不能省。」
+
+**破折号**：中文的「——」和英文的 em dash（—），AI 用来插入戏剧性的补充说明。一篇文档里几段才出现一次还算正常；每段都有就是味道。改成逗号、句号、括号，或者拆句。检查脚本会报数量，数过再判断，不要凭感觉。
+
+**加粗泛滥**：每段都有几个加粗词，等于没有强调。只在第一次出现的定义术语、真正的警告上加粗。
+
+**加粗小标题列表**：
+
+> 改前：
+> - **高性能：** 系统性能得到了大幅提升。
+> - **易扩展：** 系统扩展性更强。
+> - **安全性：** 安全能力全面增强。
+>
+> 改后：查询接口加了 Redis 缓存，命中时响应从 300 ms 降到 20 ms；新增服务只需在 `services.yaml` 里注册；所有写接口加了 CSRF 校验。
+
+参考文档里「**字段名**：说明」「**术语**：定义」这种格式是正常用法，不算。
+
+**emoji**：新写的文档不给标题和列表加 emoji（✨🚀📝✅）。更新已有文档时，原文用了就沿用。
+
+**英文标题的 Title Case**：有明确风格指南（AP、Chicago）时照指南；没有的话单独出现不算问题，和其他 AI 特征一起出现才算。
+
+## 6. 含糊、填充、聊天腔
+
+**铺垫句**：「值得注意的是」「需要指出的是」「众所周知」「不难发现」「It's worth noting」「It's important to note」。直接说那件事。
+
+**过度对冲**：「在一定程度上」「可能会」「或许」「通常来说」堆在一起。确定的就直接说；不确定的用标记（`[INFERRED]`、`[UNVERIFIED]`），不要用含糊的措辞糊过去。
+
+**模糊出处**：「业界普遍认为」「有观点指出」「Experts say」。给出具体来源，或者删掉。
+
+**填充短语**：「为了实现这一目标」→「为此」；「由于……的原因」→「因为」；「具有……的能力」→「能」；「进行……操作」→ 直接用动词（「进行删除操作」→「删除」）；「in order to」→「to」。
+
+**聊天腔**：「希望对你有帮助！」「如需进一步了解，请随时告诉我」「好问题！」「Let me know if...」。文档里一律删掉。
+
+**开场白**：「在当今数字化时代」「随着……的快速发展」「In today's fast-paced world」。删掉，第一句直接说是什么。
+
+**空泛结尾**：「未来可期」「让我们拭目以待」「综上所述」「总而言之」「The future looks bright」。删掉，文档讲完就停。
+
+## 7. 连接词
+
+AI 反复用同一批连接词：「此外」「另外」「同时」「与此同时」「首先……其次……最后」「总之」，英文是 Moreover、Furthermore、Additionally、In conclusion。
+
+大多数时候不需要连接词，直接开始下一个意思就行，段落分隔本身就是过渡。需要的时候用真实的逻辑关系：「因为」「所以」「但是」。
+
+## 8. 技术文档特有的毛病
+
+- **「只需」「简单地」「轻松」「just」「simply」「easily」**：对卡住的读者毫无帮助，还让人觉得是自己笨。删掉。
+- **用评价代替行为**：「性能很好」「非常安全」「使用方便」。写行为或数字：「单实例 2,000 QPS（见 `bench/README.md`）」。
+- **把 README 写成产品宣传页**：开头一大段愿景，读者翻三屏才看到安装命令。
+- **功能列表只有名词**：「用户管理、权限管理、日志管理」。每项写它具体让用户做什么。
+- **「等」「等等」「etc.」收尾的清单**：参考文档要全，列不全就说明范围（「以下是最常用的 5 个，完整列表见……」）。
+- **被动语态堆积**：「该配置会被系统读取并被用于……」→「系统启动时读取该配置，用来……」。
+
+## 技术文档里合适的「人味」
+
+改散文时去 AI 味常靠加观点、加第一人称、加幽默，这些在参考文档里都不合适。技术文档里真正让人觉得「这是懂行的人写的」的，是这些：
+
+- 写出真实的坑：「第一次运行 `db:migrate` 会失败，因为 Redis 还没起；先跑 `docker compose up -d redis`。」
+- 写出设计取舍：「这里没有用消息队列，因为订单量每天不到一千单，定时任务每分钟扫一次足够。」
+- 教程和 README 可以用「你」直接对读者说话。
+- 该下判断的地方下判断：「生产环境不要开 `DEBUG=1`，它会在响应里带上 SQL。」不写「建议谨慎考虑是否开启」。
+
+## 该保留的
+
+- 技术事实、具体数字、版本号
+- 专有名词、产品名、代码标识符（保持原样，不翻译）
+- 已有文档的结构和风格（更新时）
+- 参考文档里统一的「**术语**：定义」格式
+- 表格里真实就是三行的三条（不是所有三项并列都是凑数）
+- 标准技术术语，哪怕看起来像流行词：「端到端测试」「高可用部署」「生态系统」在技术语境里有确切含义，有依据就可以用
+
+## 改写示例
+
+**README 开头**
+
+> 改前：
+> # 🚀 DataHub
+> 在当今数据驱动的时代，数据治理扮演着至关重要的角色。DataHub 是一款强大的、一站式的数据治理平台，致力于为企业赋能，无缝集成各类数据源，助力企业实现数字化转型。它不仅提供了全面的元数据管理能力，更打造了业界领先的数据血缘追踪功能。
+>
+> 改后：
+> # DataHub
+> DataHub 收集数据库和消息队列的元数据，记录表和字段之间的血缘关系。上游改了字段类型时，它会找出受影响的下游表和报表，通知负责人。目前支持 MySQL、PostgreSQL 和 Kafka。
+
+**架构文档段落**
+
+> 改前：
+> 值得注意的是，系统采用了先进的微服务架构，各服务之间通过消息队列实现了无缝的异步通信，从而显著提升了系统的可扩展性和稳定性。此外，网关层扮演着统一入口的角色，为整个系统提供了坚实的安全保障。
+>
+> 改后：
+> 系统拆成 6 个服务，都挂在 `gateway` 后面。网关负责校验 JWT 并把用户 ID 写进 `X-User-Id` 请求头，下游服务只读这个头，不再自己验 token（`gateway/src/auth.ts:31`）。服务之间的异步通知走 Redis Streams，同步查询直接 HTTP 调用。
+
+**英文 API 说明**
+
+> Before: This powerful endpoint seamlessly enables you to effortlessly retrieve comprehensive user information, leveraging our robust caching layer.
+>
+> After: Returns one user by ID. Responses are cached for 60 seconds; send `Cache-Control: no-cache` to bypass.
+
+## 快速自检
+
+命中 5 条以上，说明需要再改一遍：
+
+- [ ] 第一段没有直接说这是什么、给谁用
+- [ ] 出现 3 个以上第 2、3 节里的词
+- [ ] 有「值得注意的是」一类的铺垫句
+- [ ] 每节结构一样，或者每节都有小结
+- [ ] 结尾有总结、展望
+- [ ] 「不仅……更……」「不是……而是……」出现两次以上
+- [ ] 破折号每段都有
+- [ ] 加粗小标题列表
+- [ ] 标题或列表有装饰性 emoji
+- [ ] 同一个概念用了两个以上的名字
+- [ ] 用形容词评价性能、安全、易用，没有数字或行为
+- [ ] 出现「只需」「轻松」「简单地」
+- [ ] 有聊天腔（「希望对你有帮助」）