docs(zh-CN): sync Chinese docs with latest upstream changes (#304)

* docs(zh-CN): sync Chinese docs with latest upstream changes

* update

---------

Co-authored-by: neo <neo.dowithless@gmail.com>

docs/zh-CN/rules/README.md

@@ -17,7 +17,8 @@ rules/
 │   └── security.md
 ├── typescript/      # TypeScript/JavaScript specific
 ├── python/          # Python specific
-└── golang/          # Go specific
+├── golang/          # Go specific
+└── swift/           # Swift specific
 ```
 
 * **common/** 包含通用原则 —— 没有语言特定的代码示例。
@@ -32,6 +33,7 @@ rules/
 ./install.sh typescript
 ./install.sh python
 ./install.sh golang
+./install.sh swift
 
 # Install multiple languages at once
 ./install.sh typescript python
@@ -51,6 +53,7 @@ cp -r rules/common ~/.claude/rules/common
 cp -r rules/typescript ~/.claude/rules/typescript
 cp -r rules/python ~/.claude/rules/python
 cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/swift ~/.claude/rules/swift
 
 # Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
 ```
@@ -78,3 +81,22 @@ cp -r rules/golang ~/.claude/rules/golang
    > 此文件通过 <语言> 特定内容扩展了 [common/xxx.md](../common/xxx.md)。
    ```
 4. 如果现有技能可用，则引用它们，或者在 `skills/` 下创建新的技能。
+
+## 规则优先级
+
+当语言特定规则与通用规则冲突时，**语言特定规则优先**（具体规则覆盖通用规则）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。
+
+* `rules/common/` 定义了适用于所有项目的通用默认值。
+* `rules/golang/`、`rules/python/`、`rules/typescript/` 等在语言习惯用法不同的地方会覆盖这些默认值。
+
+### 示例
+
+`common/coding-style.md` 建议将不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点：
+
+> 符合 Go 语言习惯的做法是使用指针接收器进行结构体修改——关于通用原则请参阅 [common/coding-style.md](../../../common/coding-style.md)，但此处更推荐符合 Go 语言习惯的修改方式。
+
+### 带有覆盖说明的通用规则
+
+`rules/common/` 中可能被语言特定文件覆盖的规则会标记为：
+
+> **语言说明**：对于此模式不符合语言习惯的语言，此规则可能会被语言特定规则覆盖。

docs/zh-CN/rules/common/development-workflow.md

@@ -0,0 +1,29 @@
+# 开发工作流程
+
+> 本文档在 [common/git-workflow.md](git-workflow.md) 的基础上进行了扩展，涵盖了在 git 操作之前发生的完整功能开发过程。
+
+功能实现工作流程描述了开发管道：规划、测试驱动开发、代码审查，然后提交到 git。
+
+## 功能实现工作流程
+
+1. **先行规划**
+   * 使用 **planner** 代理创建实现计划
+   * 识别依赖项和风险
+   * 分解为多个阶段
+
+2. **测试驱动开发方法**
+   * 使用 **tdd-guide** 代理
+   * 先编写测试（红）
+   * 实现代码以通过测试（绿）
+   * 重构（改进）
+   * 验证 80% 以上的覆盖率
+
+3. **代码审查**
+   * 编写代码后立即使用 **code-reviewer** 代理
+   * 解决 CRITICAL 和 HIGH 级别的问题
+   * 尽可能修复 MEDIUM 级别的问题
+
+4. **提交与推送**
+   * 详细的提交信息
+   * 遵循约定式提交格式
+   * 有关提交信息格式和 PR 流程，请参阅 [git-workflow.md](git-workflow.md)

docs/zh-CN/rules/common/git-workflow.md

@@ -22,25 +22,5 @@
 4. 包含带有 TODO 的测试计划
 5. 如果是新分支，使用 `-u` 标志推送
 
-## 功能实现工作流程
-
-1. **先做计划**
-   * 使用 **planner** 代理创建实施计划
-   * 识别依赖项和风险
-   * 分解为多个阶段
-
-2. **TDD 方法**
-   * 使用 **tdd-guide** 代理
-   * 先写测试（RED）
-   * 实现代码以通过测试（GREEN）
-   * 重构（IMPROVE）
-   * 验证 80%+ 的覆盖率
-
-3. **代码审查**
-   * 编写代码后立即使用 **code-reviewer** 代理
-   * 解决 CRITICAL 和 HIGH 级别的问题
-   * 尽可能修复 MEDIUM 级别的问题
-
-4. **提交与推送**
-   * 详细的提交信息
-   * 遵循约定式提交格式
+> 有关 git 操作之前的完整开发流程（规划、TDD、代码审查），
+> 请参阅 [development-workflow.md](development-workflow.md)。

docs/zh-CN/rules/common/performance.md

@@ -8,7 +8,7 @@
 * 结对编程和代码生成
 * 多智能体系统中的工作智能体
 
-**Sonnet 4.5** (最佳编码模型):
+**Sonnet 4.6** (最佳编码模型):
 
 * 主要的开发工作
 * 编排多智能体工作流

docs/zh-CN/rules/golang/coding-style.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+
 # Go 编码风格
 
 > 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上，扩展了 Go 语言的特定内容。

docs/zh-CN/rules/golang/hooks.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+
 # Go 钩子
 
 > 本文件通过 Go 特定内容扩展了 [common/hooks.md](../common/hooks.md)。

docs/zh-CN/rules/golang/patterns.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+
 # Go 模式
 
 > 本文档在 [common/patterns.md](../common/patterns.md) 的基础上扩展了 Go 语言特定的内容。

docs/zh-CN/rules/golang/security.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+
 # Go 安全
 
 > 此文件基于 [common/security.md](../common/security.md) 扩展了 Go 特定内容。

docs/zh-CN/rules/golang/testing.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+
 # Go 测试
 
 > 本文档在 [common/testing.md](../common/testing.md) 的基础上扩展了 Go 特定的内容。

docs/zh-CN/rules/python/coding-style.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+
 # Python 编码风格
 
 > 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上扩展了 Python 特定的内容。

docs/zh-CN/rules/python/hooks.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+
 # Python 钩子
 
 > 本文档扩展了 [common/hooks.md](../common/hooks.md) 中关于 Python 的特定内容。

docs/zh-CN/rules/python/patterns.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+
 # Python 模式
 
 > 本文档扩展了 [common/patterns.md](../common/patterns.md)，补充了 Python 特定的内容。

docs/zh-CN/rules/python/security.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+
 # Python 安全
 
 > 本文档基于 [通用安全指南](../common/security.md) 扩展，补充了 Python 相关的内容。

docs/zh-CN/rules/python/testing.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+
 # Python 测试
 
 > 本文件在 [通用/测试.md](../common/testing.md) 的基础上扩展了 Python 特定的内容。

docs/zh-CN/rules/swift/coding-style.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+
+# Swift 编码风格
+
+> 本文件在 [common/coding-style.md](../common/coding-style.md) 的基础上扩展了 Swift 相关的内容。
+
+## 格式化
+
+* **SwiftFormat** 用于自动格式化，**SwiftLint** 用于风格检查
+* `swift-format` 已作为替代方案捆绑在 Xcode 16+ 中
+
+## 不变性
+
+* 优先使用 `let` 而非 `var` — 将所有内容定义为 `let`，仅在编译器要求时才改为 `var`
+* 默认使用具有值语义的 `struct`；仅在需要标识或引用语义时才使用 `class`
+
+## 命名
+
+遵循 [Apple API 设计指南](https://www.swift.org/documentation/api-design-guidelines/)：
+
+* 在使用时保持清晰 — 省略不必要的词语
+* 根据方法和属性的作用而非类型来命名
+* 对于常量，使用 `static let` 而非全局常量
+
+## 错误处理
+
+使用类型化 throws (Swift 6+) 和模式匹配：
+
+```swift
+func load(id: String) throws(LoadError) -> Item {
+    guard let data = try? read(from: path) else {
+        throw .fileNotFound(id)
+    }
+    return try decode(data)
+}
+```
+
+## 并发
+
+启用 Swift 6 严格并发检查。优先使用：
+
+* `Sendable` 值类型用于跨越隔离边界的数据
+* Actors 用于共享可变状态
+* 结构化并发 (`async let`, `TaskGroup`) 而非非结构化的 `Task {}`

docs/zh-CN/rules/swift/hooks.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+
+# Swift 钩子
+
+> 此文件扩展了 [common/hooks.md](../common/hooks.md) 的内容，添加了 Swift 特定内容。
+
+## PostToolUse 钩子
+
+在 `~/.claude/settings.json` 中配置：
+
+* **SwiftFormat**: 在编辑后自动格式化 `.swift` 文件
+* **SwiftLint**: 在编辑 `.swift` 文件后运行代码检查
+* **swift build**: 在编辑后对修改的包进行类型检查
+
+## 警告
+
+标记 `print()` 语句 — 在生产代码中请改用 `os.Logger` 或结构化日志记录。

docs/zh-CN/rules/swift/patterns.md

@@ -0,0 +1,67 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+
+# Swift 模式
+
+> 此文件使用 Swift 特定内容扩展了 [common/patterns.md](../common/patterns.md)。
+
+## 面向协议的设计
+
+定义小型、专注的协议。使用协议扩展来提供共享的默认实现：
+
+```swift
+protocol Repository: Sendable {
+    associatedtype Item: Identifiable & Sendable
+    func find(by id: Item.ID) async throws -> Item?
+    func save(_ item: Item) async throws
+}
+```
+
+## 值类型
+
+* 使用结构体（struct）作为数据传输对象和模型
+* 使用带有关联值的枚举（enum）来建模不同的状态：
+
+```swift
+enum LoadState<T: Sendable>: Sendable {
+    case idle
+    case loading
+    case loaded(T)
+    case failed(Error)
+}
+```
+
+## Actor 模式
+
+使用 actor 来处理共享可变状态，而不是锁或调度队列：
+
+```swift
+actor Cache<Key: Hashable & Sendable, Value: Sendable> {
+    private var storage: [Key: Value] = [:]
+
+    func get(_ key: Key) -> Value? { storage[key] }
+    func set(_ key: Key, value: Value) { storage[key] = value }
+}
+```
+
+## 依赖注入
+
+使用默认参数注入协议 —— 生产环境使用默认值，测试时注入模拟对象：
+
+```swift
+struct UserService {
+    private let repository: any UserRepository
+
+    init(repository: any UserRepository = DefaultUserRepository()) {
+        self.repository = repository
+    }
+}
+```
+
+## 参考
+
+查看技能：`swift-actor-persistence` 以了解基于 actor 的持久化模式。
+查看技能：`swift-protocol-di-testing` 以了解基于协议的依赖注入和测试。

docs/zh-CN/rules/swift/security.md

@@ -0,0 +1,34 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+
+# Swift 安全
+
+> 此文件扩展了 [common/security.md](../common/security.md)，并包含 Swift 特定的内容。
+
+## 密钥管理
+
+* 使用 **Keychain Services** 处理敏感数据（令牌、密码、密钥）—— 切勿使用 `UserDefaults`
+* 使用环境变量或 `.xcconfig` 文件来管理构建时的密钥
+* 切勿在源代码中硬编码密钥 —— 反编译工具可以轻易提取它们
+
+```swift
+let apiKey = ProcessInfo.processInfo.environment["API_KEY"]
+guard let apiKey, !apiKey.isEmpty else {
+    fatalError("API_KEY not configured")
+}
+```
+
+## 传输安全
+
+* 默认强制执行 App Transport Security (ATS) —— 不要禁用它
+* 对关键端点使用证书锁定
+* 验证所有服务器证书
+
+## 输入验证
+
+* 在显示之前清理所有用户输入，以防止注入攻击
+* 使用带验证的 `URL(string:)`，而不是强制解包
+* 在处理来自外部源（API、深度链接、剪贴板）的数据之前，先进行验证

docs/zh-CN/rules/swift/testing.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+---
+
+# Swift 测试
+
+> 本文档在 [common/testing.md](../common/testing.md) 的基础上扩展了 Swift 特定的内容。
+
+## 框架
+
+对于新测试，使用 **Swift Testing** (`import Testing`)。使用 `@Test` 和 `#expect`：
+
+```swift
+@Test("User creation validates email")
+func userCreationValidatesEmail() throws {
+    #expect(throws: ValidationError.invalidEmail) {
+        try User(email: "not-an-email")
+    }
+}
+```
+
+## 测试隔离
+
+每个测试都会获得一个全新的实例 —— 在 `init` 中设置，在 `deinit` 中拆卸。测试之间没有共享的可变状态。
+
+## 参数化测试
+
+```swift
+@Test("Validates formats", arguments: ["json", "xml", "csv"])
+func validatesFormat(format: String) throws {
+    let parser = try Parser(format: format)
+    #expect(parser.isValid)
+}
+```
+
+## 覆盖率
+
+```bash
+swift test --enable-code-coverage
+```
+
+## 参考
+
+关于基于协议的依赖注入和 Swift Testing 的模拟模式，请参阅技能：`swift-protocol-di-testing`。

docs/zh-CN/rules/typescript/coding-style.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
 # TypeScript/JavaScript 编码风格
 
 > 本文件基于 [common/coding-style.md](../common/coding-style.md) 扩展，包含 TypeScript/JavaScript 特定内容。

docs/zh-CN/rules/typescript/hooks.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
 # TypeScript/JavaScript 钩子
 
 > 此文件扩展了 [common/hooks.md](../common/hooks.md)，并添加了 TypeScript/JavaScript 特有的内容。

docs/zh-CN/rules/typescript/patterns.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
 # TypeScript/JavaScript 模式
 
 > 此文件在 [common/patterns.md](../common/patterns.md) 的基础上扩展了 TypeScript/JavaScript 特定的内容。

docs/zh-CN/rules/typescript/security.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
 # TypeScript/JavaScript 安全
 
 > 本文档扩展了 [common/security.md](../common/security.md)，包含了 TypeScript/JavaScript 特定的内容。

docs/zh-CN/rules/typescript/testing.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
 # TypeScript/JavaScript 测试
 
 > 本文档基于 [common/testing.md](../common/testing.md) 扩展，补充了 TypeScript/JavaScript 特定的内容。