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

package/dist/templates/markdown/spec/frontend/index.md.txt

@@ -1,39 +1,39 @@
-# Frontend Development Guidelines
+# 前端开发指南（Frontend Development Guidelines）
 
-> Best practices for frontend development in this project.
+> 本项目的前端开发最佳实践。
 
 ---
 
-## Overview
+## 概览（Overview）
 
-This directory contains guidelines for frontend development. Fill in each file with your project's specific conventions.
+本目录包含前端开发指南。请在各文件中填写项目的具体约定。
 
 ---
 
-## Guidelines Index
+## 指南索引（Guidelines Index）
 
-| Guide | Description | Status |
+| 指南（Guide） | 说明（Description） | 状态（Status） |
 |-------|-------------|--------|
-| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
-| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
-| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
-| [State Management](./state-management.md) | Local state, global state, server state | To fill |
-| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
-| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
+| [目录结构（Directory Structure）](./directory-structure.md) | 模块组织和文件布局 | 待填写 |
+| [组件指南（Component Guidelines）](./component-guidelines.md) | 组件模式、props 和组合 | 待填写 |
+| [Hook 指南（Hook Guidelines）](./hook-guidelines.md) | 自定义 Hook 和数据获取模式 | 待填写 |
+| [状态管理（State Management）](./state-management.md) | 本地状态、全局状态和服务端状态 | 待填写 |
+| [质量指南（Quality Guidelines）](./quality-guidelines.md) | 代码标准和禁止模式 | 待填写 |
+| [类型安全（Type Safety）](./type-safety.md) | 类型模式和校验 | 待填写 |
 
 ---
 
-## How to Fill These Guidelines
+## 如何填写这些指南（How to Fill These Guidelines）
 
-For each guideline file:
+对于每个指南文件：
 
-1. Document your project's **actual conventions** (not ideals)
-2. Include **code examples** from your codebase
-3. List **forbidden patterns** and why
-4. Add **common mistakes** your team has made
+1. 记录项目的**实际约定**，而不是理想状态
+2. 包含代码库中的**代码示例**
+3. 列出**禁止模式**及其原因
+4. 补充团队曾经出现过的**常见错误**
 
-The goal is to help AI assistants and new team members understand how YOUR project works.
+目标是帮助 AI 助手和新团队成员理解项目的实际工作方式。
 
 ---
 
-**Language**: All documentation should be written in **English**.
+**语言（Language）**：所有文档默认使用**简体中文**。

package/dist/templates/markdown/spec/frontend/quality-guidelines.md.txt

@@ -1,51 +1,51 @@
-# Quality Guidelines
+# 质量指南（Quality Guidelines）
 
-> Code quality standards for frontend development.
+> 前端开发的代码质量标准。
 
 ---
 
-## Overview
+## 概览（Overview）
 
 <!--
-Document your project's quality standards here.
+在此记录项目的质量标准。
 
-Questions to answer:
-- What patterns are forbidden?
-- What linting rules do you enforce?
-- What are your testing requirements?
-- What code review standards apply?
+需要回答的问题：
+- 禁止哪些模式？
+- 执行哪些 lint 规则？
+- 有哪些测试要求？
+- 适用哪些代码审查标准？
 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Forbidden Patterns
+## 禁止模式（Forbidden Patterns）
 
-<!-- Patterns that should never be used and why -->
+<!-- 永远不应使用的模式及其原因 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Required Patterns
+## 必须遵守的模式（Required Patterns）
 
-<!-- Patterns that must always be used -->
+<!-- 必须始终使用的模式 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Testing Requirements
+## 测试要求（Testing Requirements）
 
-<!-- What level of testing is expected -->
+<!-- 期望达到的测试层级 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Code Review Checklist
+## 代码审查清单（Code Review Checklist）
 
-<!-- What reviewers should check -->
+<!-- 审查者应检查的内容 -->
 
-(To be filled by the team)
+（待团队填写）

package/dist/templates/markdown/spec/frontend/state-management.md.txt

@@ -1,51 +1,51 @@
-# State Management
+# 状态管理（State Management）
 
-> How state is managed in this project.
+> 本项目如何管理状态。
 
 ---
 
-## Overview
+## 概览（Overview）
 
 <!--
-Document your project's state management conventions here.
+在此记录项目的状态管理约定。
 
-Questions to answer:
-- What state management solution do you use?
-- How is local vs global state decided?
-- How do you handle server state?
-- What are the patterns for derived state?
+需要回答的问题：
+- 使用什么状态管理方案？
+- 如何决定使用本地状态还是全局状态？
+- 如何处理服务端状态？
+- 派生状态遵循哪些模式？
 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## State Categories
+## 状态分类（State Categories）
 
-<!-- Local state, global state, server state, URL state -->
+<!-- 本地状态、全局状态、服务端状态、URL 状态 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## When to Use Global State
+## 何时使用全局状态（When to Use Global State）
 
-<!-- Criteria for promoting state to global -->
+<!-- 将状态提升为全局状态的条件 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Server State
+## 服务端状态（Server State）
 
-<!-- How server data is cached and synchronized -->
+<!-- 如何缓存和同步服务端数据 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Common Mistakes
+## 常见错误（Common Mistakes）
 
-<!-- State management mistakes your team has made -->
+<!-- 团队曾经出现过的状态管理错误 -->
 
-(To be filled by the team)
+（待团队填写）

package/dist/templates/markdown/spec/frontend/type-safety.md.txt

@@ -1,51 +1,51 @@
-# Type Safety
+# 类型安全（Type Safety）
 
-> Type safety patterns in this project.
+> 本项目的类型安全模式。
 
 ---
 
-## Overview
+## 概览（Overview）
 
 <!--
-Document your project's type safety conventions here.
+在此记录项目的类型安全约定。
 
-Questions to answer:
-- What type system do you use?
-- How are types organized?
-- What validation library do you use?
-- How do you handle type inference?
+需要回答的问题：
+- 使用什么类型系统？
+- 如何组织类型？
+- 使用什么校验库？
+- 如何处理类型推断？
 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Type Organization
+## 类型组织（Type Organization）
 
-<!-- Where types are defined, shared types vs local types -->
+<!-- 类型定义位置，共享类型与局部类型的区别 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Validation
+## 校验（Validation）
 
-<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
+<!-- 运行时校验模式（Zod、Yup、io-ts 等） -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Common Patterns
+## 常见模式（Common Patterns）
 
-<!-- Type utilities, generics, type guards -->
+<!-- 类型工具、泛型和类型守卫 -->
 
-(To be filled by the team)
+（待团队填写）
 
 ---
 
-## Forbidden Patterns
+## 禁止模式（Forbidden Patterns）
 
-<!-- any, type assertions, etc. -->
+<!-- any、类型断言等 -->
 
-(To be filled by the team)
+（待团队填写）

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/...`）。运行前始终复核路径。