@pennixrv/trellis 0.7.0-beta.46 → 0.7.0-beta.47

package/dist/templates/markdown/spec/guides/code-reuse-thinking-guide.md.txt

@@ -1,23 +1,23 @@
-# Code Reuse Thinking Guide
+# 代码复用思考指南（Code Reuse Thinking Guide）
 
-> **Purpose**: Stop and think before creating new code - does it already exist?
+> **目的（Purpose）**：创建新代码前先停下来思考：它是否已经存在？
 
 ---
 
-## The Problem
+## 问题（The Problem）
 
-**Duplicated code is the #1 source of inconsistency bugs.**
+**重复代码是不一致错误的首要来源。**
 
-When you copy-paste or rewrite existing logic:
-- Bug fixes don't propagate
-- Behavior diverges over time
-- Codebase becomes harder to understand
+复制粘贴或重写已有逻辑会导致：
+- 错误修复无法传播
+- 行为随时间逐渐分化
+- 代码库更难理解
 
 ---
 
-## Before Writing New Code
+## 编写新代码前（Before Writing New Code）
 
-### Step 1: Search First
+### 第一步：先搜索（Step 1: Search First）
 
 ```bash
 # Search for similar function names
@@ -27,50 +27,49 @@ grep -r "functionName" .
 grep -r "keyword" .
 ```
 
-### Step 2: Ask These Questions
+### 第二步：回答这些问题（Step 2: Ask These Questions）
 
-| Question | If Yes... |
+| 问题（Question） | 如果是……（If Yes...） |
 |----------|-----------|
-| Does a similar function exist? | Use or extend it |
-| Is this pattern used elsewhere? | Follow the existing pattern |
-| Could this be a shared utility? | Create it in the right place |
-| Am I copying code from another file? | **STOP** - extract to shared |
+| 是否存在相似函数？ | 使用或扩展它 |
+| 其他地方是否使用了这种模式？ | 遵循已有模式 |
+| 它是否可以成为共享工具？ | 在正确位置创建它 |
+| 是否正在复制其他文件中的代码？ | **停止**：提取为共享逻辑 |
 
 ---
 
-## Common Duplication Patterns
+## 常见重复模式（Common Duplication Patterns）
 
-### Pattern 1: Copy-Paste Functions
+### 模式一：复制粘贴函数（Pattern 1: Copy-Paste Functions）
 
-**Bad**: Copying a validation function to another file
+**不佳**：将校验函数复制到另一个文件。
 
-**Good**: Extract to shared utilities, import where needed
+**较好**：提取为共享工具，在需要的位置导入。
 
-### Pattern 2: Similar Components
+### 模式二：相似组件（Pattern 2: Similar Components）
 
-**Bad**: Creating a new component that's 80% similar to existing
+**不佳**：创建一个与现有组件有 80% 相似度的新组件。
 
-**Good**: Extend existing component with props/variants
+**较好**：通过 props/变体扩展现有组件。
 
-### Pattern 3: Repeated Constants
+### 模式三：重复常量（Pattern 3: Repeated Constants）
 
-**Bad**: Defining the same constant in multiple files
+**不佳**：在多个文件中定义同一个常量。
 
-**Good**: Single source of truth, import everywhere
+**较好**：保留唯一事实来源，在各处导入。
 
-### Pattern 4: Repeated Payload Field Extraction
+### 模式四：重复提取载荷字段（Pattern 4: Repeated Payload Field Extraction）
 
-**Bad**: Multiple consumers cast the same JSON/event fields locally:
+**错误示例（Bad）**：多个消费者各自在本地转换同一组 JSON/事件字段：
 
 ```typescript
 const description = (ev as { description?: string }).description;
 const context = (ev as { context?: ContextEntry[] }).context;
 ```
 
-This is duplicated contract logic even when the code is only two lines. Each
-consumer now has its own definition of what a valid payload means.
+即使只有两行代码，这也是重复的合同逻辑。此时每个消费者都有一份自己对“有效载荷”的定义。
 
-**Good**: Put the decoder, type guard, or projection next to the data owner:
+**较好**：将解码器、类型守卫或投影放在数据 owner 旁边：
 
 ```typescript
 if (isThreadEvent(ev)) {
@@ -78,37 +77,35 @@ if (isThreadEvent(ev)) {
 }
 ```
 
-**Rule**: If the same untyped payload field is read in 2+ places, create a
-shared type guard / normalizer / projection before adding a third reader.
+**规则**：如果同一个无类型载荷字段在两个或更多位置被读取，在增加第三个读取者前创建共享类型守卫、规范化器或投影。
 
 ---
 
-## When to Abstract
+## 何时抽象（When to Abstract）
 
-**Abstract when**:
-- Same code appears 3+ times
-- Logic is complex enough to have bugs
-- Multiple people might need this
+**在以下情况进行抽象**：
+- 相同代码出现三次或更多
+- 逻辑复杂到足以产生错误
+- 多个人可能需要使用它
 
-**Don't abstract when**:
-- Only used once
-- Trivial one-liner
-- Abstraction would be more complex than duplication
+**在以下情况不要抽象**：
+- 只使用一次
+- 只是简单的一行代码
+- 抽象后的复杂度高于重复代码
 
 ---
 
-## After Batch Modifications
+## 批量修改后（After Batch Modifications）
 
-When you've made similar changes to multiple files:
+对多个文件进行相似修改后：
 
-1. **Review**: Did you catch all instances?
-2. **Search**: Run grep to find any missed
-3. **Consider**: Should this be abstracted?
+1. **复核**：是否覆盖了所有实例？
+2. **搜索**：运行 grep 查找遗漏
+3. **考虑**：是否应该进行抽象？
 
-### Reducers Should Use Exhaustive Structure
+### Reducer 应使用穷举结构（Reducers Should Use Exhaustive Structure）
 
-When state is derived from action-like values (`action`, `kind`, `status`,
-`phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
+当状态由类似 action 的值（`action`、`kind`、`status`、`phase`）派生时，优先使用一个 `switch` 的 reducer，而不是分散的 `if/else` 更新。
 
 ```typescript
 // BAD - action-specific state transitions are hard to audit
@@ -127,30 +124,28 @@ switch (event.action) {
 }
 ```
 
-This matters when the event log is the source of truth. A reducer is the
-documented replay model; display code and commands should not duplicate pieces
-of that replay model.
+当事件日志是事实来源时，这一点尤其重要。Reducer 是有文档记录的重放模型；展示代码和命令不应重复该重放模型的局部逻辑。
 
 ---
 
-## Checklist Before Commit
+## 提交前清单（Checklist Before Commit）
 
-- [ ] Searched for existing similar code
-- [ ] No copy-pasted logic that should be shared
-- [ ] No repeated untyped payload field extraction outside a shared decoder
-- [ ] Constants defined in one place
-- [ ] Similar patterns follow same structure
-- [ ] Reducer/action transitions live in one reducer or command dispatcher
+- [ ] 已搜索现有相似代码
+- [ ] 没有应当共享却被复制粘贴的逻辑
+- [ ] 共享解码器之外没有重复提取无类型载荷字段
+- [ ] 常量只在一个位置定义
+- [ ] 相似模式遵循相同结构
+- [ ] Reducer/action 转换集中在一个 reducer 或命令分发器中
 
 ---
 
-## Gotcha: Python if/elif/else Exhaustive Check
+## 注意：Python 的 if/elif/else 穷举检查（Gotcha: Python if/elif/else Exhaustive Check）
 
-**Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., `Platform`), existing if/elif/else chains silently fall through to `else` with wrong defaults.
+**问题**：Python 的 if/elif/else 链没有编译期穷举检查。向 `Literal` 类型（例如 `Platform`）增加新值时，已有 if/elif/else 链可能静默落入 `else`，使用错误的默认值。
 
-**Symptom**: New platform works partially — some methods return Claude defaults instead of platform-specific values. No error is raised.
+**表现**：新平台只能部分工作，一些方法返回 Claude 默认值而不是平台专属值，并且不会抛出错误。
 
-**Example** (`cli_adapter.py`):
+**示例**（`cli_adapter.py`）：
 ```python
 # BAD: "gemini" falls through to else, returns "claude"
 @property
@@ -171,53 +166,53 @@ def cli_name(self) -> str:
         return "claude"
 ```
 
-**Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.
+**预防**：向 Python `Literal` 类型增加新值时，搜索所有基于该类型分支的 if/elif/else 链，并增加显式分支。不要假定 `else` 对新值仍然正确。
 
 ---
 
-## Gotcha: Asymmetric Mechanisms Producing Same Output
+## 注意：产生相同输出的非对称机制（Gotcha: Asymmetric Mechanisms Producing Same Output）
 
-**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
+**问题**：当两个不同机制必须产生相同文件集合时（例如 init 的递归目录复制与 update 的手动 `files.set()`），结构变化（重命名、移动、增加子目录）只会通过自动机制传播，手动机制会静默漂移。
 
-**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
+**表现**：init 完全正常，但 update 将文件创建到错误路径，或完全遗漏文件。
 
-**Prevention**:
-- **Best**: Eliminate the asymmetry — have the manual path call the automatic one (e.g., `collectTemplateFiles()` calls `getAllScripts()` instead of maintaining its own list)
-- **If asymmetry is unavoidable**: Add a regression test that compares outputs from both mechanisms
-- When migrating directory structures, search for ALL code paths that reference the old structure
+**预防**：
+- **最佳做法**：消除非对称性，让手动路径调用自动路径（例如让 `collectTemplateFiles()` 调用 `getAllScripts()`，而不是维护自己的列表）。
+- **如果无法避免非对称性**：增加回归测试，比较两种机制的输出。
+- 迁移目录结构时，搜索所有引用旧结构的代码路径。
 
-**Real example**: `trellis update` had a manual `files.set()` list for 11 scripts that `getAllScripts()` already tracked. Fix: replaced the manual list with a `for..of getAllScripts()` loop. See `update.ts` refactor in v0.4.0-beta.3.
+**真实示例**：`trellis update` 曾为 11 个脚本维护手动 `files.set()` 列表，而 `getAllScripts()` 已经跟踪这些脚本。修复方式是用 `for..of getAllScripts()` 循环替换手动列表。参见 v0.4.0-beta.3 的 `update.ts` 重构。
 
 ---
 
-## Template File Registration (Trellis-specific)
+## 模板文件登记（Trellis-specific）
 
-When adding new files to `src/templates/trellis/scripts/`:
+向 `src/templates/trellis/scripts/` 增加文件时：
 
-**Single registration point**: `src/templates/trellis/index.ts`
+**唯一登记点**：`src/templates/trellis/index.ts`
 
-1. Add `export const xxxScript = readTemplate("scripts/path/file.py");`
-2. Add to `getAllScripts()` Map
+1. 增加 `export const xxxScript = readTemplate("scripts/path/file.py");`
+2. 加入 `getAllScripts()` Map。
 
-That's it. `commands/update.ts` uses `getAllScripts()` directly — no manual sync needed.
+完成这两步即可。`commands/update.ts` 直接使用 `getAllScripts()`，不需要手动同步列表。
 
-**Why this matters**: Without registration in `getAllScripts()`, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
+**原因**：如果没有在 `getAllScripts()` 中登记，`trellis update` 就不会把文件同步到用户项目，错误修复和新功能也无法传播。
 
-**History**: Before v0.4.0-beta.3, `update.ts` had its own hand-maintained file list that frequently fell out of sync with `getAllScripts()`. This caused 11 Python files to be silently skipped during `trellis update`. The fix was to eliminate the duplicate list and use `getAllScripts()` as the single source of truth.
+**历史**：在 v0.4.0-beta.3 之前，`update.ts` 有一份自己维护的文件列表，经常与 `getAllScripts()` 不同步，导致 `trellis update` 静默跳过 11 个 Python 文件。修复方式是删除重复列表，并将 `getAllScripts()` 作为唯一事实来源。
 
-### Quick Checklist for New Scripts
+### 新增脚本快速清单（Quick Checklist for New Scripts）
 
 ```bash
 # After adding a new .py file, verify it's in getAllScripts():
 grep -l "newFileName" src/templates/trellis/index.ts  # Should match
 ```
 
-### Template Sync Convention
+### 模板同步约定（Template Sync Convention）
 
-`.trellis/scripts/` (dogfooded) and `packages/cli/src/templates/trellis/scripts/` (template) must stay identical. After editing `.trellis/scripts/`, always sync:
+`.trellis/scripts/`（自用代码）与 `packages/cli/src/templates/trellis/scripts/`（模板）必须保持一致。编辑 `.trellis/scripts/` 后始终同步：
 
 ```bash
 rsync -av --delete --exclude='__pycache__' .trellis/scripts/ packages/cli/src/templates/trellis/scripts/
 ```
 
-**Gotcha**: Running rsync with wrong source/destination paths can create nested garbage directories (e.g., `.trellis/scripts/packages/cli/...`). Always double-check paths before running.
+**注意**：使用错误的 rsync 源路径或目标路径可能创建嵌套的垃圾目录（例如 `.trellis/scripts/packages/cli/...`）。运行前始终复核路径。