@jahanxu/trellis 0.4.1

package/dist/templates/trellis/paths.README.md

@@ -0,0 +1,277 @@
+# 三角色协作路径配置说明
+
+> 框架层与业务层分离，支持不同项目自定义目录结构
+
+---
+
+## 设计理念
+
+**问题**：`deliverables/` 及其子目录是业务层概念，不应该在框架层硬编码。
+
+**解决**：通过 `.trellis/paths.yaml` 配置文件，将路径定义从框架层抽离到项目配置层。
+
+**优点**：
+- ✅ 框架通用性更强，可适配不同项目
+- ✅ 一处配置，处处生效
+- ✅ 向后兼容（配置文件不存在时使用默认值）
+
+---
+
+## 配置文件
+
+### 位置
+
+`.trellis/paths.yaml`
+
+### 默认配置
+
+如果此文件不存在，使用以下默认值：
+
+```yaml
+deliverables_base: "deliverables"
+
+role_outputs:
+  pm:
+    dir: "requirements"
+  designer:
+    dir: "prototypes"
+  frontend:
+    dir: "production/features"
+
+pools:
+  pm: "requirements"
+  designer: "prototypes"
+  frontend: "implementations"
+```
+
+### 自定义示例
+
+#### 示例1：修改基础目录名
+
+```yaml
+# 将 deliverables/ 改为 outputs/
+deliverables_base: "outputs"
+
+role_outputs:
+  pm:
+    dir: "requirements"
+  designer:
+    dir: "prototypes"
+  frontend:
+    dir: "production/features"
+```
+
+**结果**：
+- PM 产出 → `outputs/requirements/`
+- Designer 产出 → `outputs/prototypes/`
+- Frontend 产出 → `outputs/production/features/`
+
+#### 示例2：完全自定义
+
+```yaml
+deliverables_base: "artifacts"
+
+role_outputs:
+  pm:
+    dir: "specs"
+  designer:
+    dir: "designs"
+  frontend:
+    dir: "code"
+```
+
+**结果**：
+- PM 产出 → `artifacts/specs/`
+- Designer 产出 → `artifacts/designs/`
+- Frontend 产出 → `artifacts/code/`
+
+#### 示例3：多级目录
+
+```yaml
+deliverables_base: "dist"
+
+role_outputs:
+  pm:
+    dir: "docs/requirements"
+  designer:
+    dir: "docs/designs"
+  frontend:
+    dir: "src/features"
+```
+
+**结果**：
+- PM 产出 → `dist/docs/requirements/`
+- Designer 产出 → `dist/docs/designs/`
+- Frontend 产出 → `dist/src/features/`
+
+---
+
+## 使用方式
+
+### 在 Python 脚本中使用
+
+```python
+from common.project_paths import get_output_dir_for_task, get_repo_root
+
+repo_root = get_repo_root()
+role = "pm"
+task_id = "user-login"
+
+# 获取产出目录
+output_dir = get_output_dir_for_task(repo_root, role, task_id)
+# 结果：deliverables/requirements/user-login（默认配置）
+# 或：outputs/specs/user-login（自定义配置）
+```
+
+### 在命令行中使用
+
+```bash
+# 查看当前配置
+python3 .trellis/scripts/common/project_paths.py
+
+# 输出：
+# === Loaded Configuration ===
+# Deliverables base: deliverables
+#
+# Role output directories:
+#   pm: deliverables/requirements
+#   designer: deliverables/prototypes
+#   frontend: deliverables/production/features
+```
+
+### 在 AI 命令中使用
+
+AI 读取配置并自动使用正确的路径：
+
+```bash
+# AI 执行 /trellis:handoff 时会：
+1. 读取 .trellis/paths.yaml（如果存在）
+2. 获取当前角色的产出目录配置
+3. 创建产出目录并复制文件
+```
+
+---
+
+## API 参考
+
+### `load_paths_config(repo_root: Path) -> Dict`
+
+加载路径配置，如果配置文件不存在则返回默认配置。
+
+### `get_deliverables_base(repo_root: Path) -> str`
+
+获取产出物基础目录名（如 `deliverables`）。
+
+### `get_role_output_dir(repo_root: Path, role: str) -> str`
+
+获取指定角色的产出目录路径。
+
+**参数**：
+- `role`: `pm`、`designer` 或 `frontend`
+
+**返回**：
+- 完整路径，如 `deliverables/requirements`
+
+### `get_output_dir_for_task(repo_root: Path, role: str, task_id: str) -> str`
+
+获取指定任务的完整产出目录路径。
+
+**返回**：
+- 完整路径，如 `deliverables/requirements/user-login`
+
+### `get_pool_name(role: str) -> str`
+
+获取指定角色的任务池名称。
+
+**返回**：
+- 池名称，如 `requirements`、`prototypes`、`implementations`
+
+---
+
+## 依赖
+
+### 可选依赖：PyYAML
+
+```bash
+pip install pyyaml
+```
+
+如果未安装 PyYAML：
+- ⚠️ 会打印警告信息
+- ✅ 仍然可以正常工作（使用默认配置）
+
+---
+
+## 迁移指南
+
+### 从硬编码路径迁移
+
+**之前**：路径硬编码在文档中
+
+```markdown
+| `pm` | `deliverables/requirements/{task-id}/` |
+```
+
+**现在**：使用配置化路径
+
+```python
+from project_paths import get_output_dir_for_task
+output_dir = get_output_dir_for_task(repo_root, "pm", task_id)
+```
+
+### 为现有项目添加自定义配置
+
+1. 创建 `.trellis/paths.yaml`
+2. 定义你的目录结构
+3. 无需修改任何代码，AI 会自动读取新配置
+
+---
+
+## 注意事项
+
+1. **池子状态文件名不建议修改**
+   - `.trellis/pool/requirements.json`
+   - `.trellis/pool/prototypes.json`
+   - `.trellis/pool/implementations.json`
+   - 这些是框架层的内部文件
+
+2. **产出目录可以任意定制**
+   - `deliverables/` 及其子目录
+   - 这些是业务层的目录
+
+3. **配置文件是可选的**
+   - 不存在时使用默认值
+   - 向后兼容
+
+---
+
+## 常见问题
+
+### Q: 修改配置后需要重启吗？
+A: 不需要。每次执行命令时都会重新读取配置。
+
+### Q: 可以为不同角色使用完全不同的基础目录吗？
+A: 可以，通过多级路径实现：
+```yaml
+role_outputs:
+  pm:
+    dir: "../docs/specs"  # 相对路径
+  designer:
+    dir: "ui/designs"
+  frontend:
+    dir: "src/features"
+```
+
+### Q: 其他项目如何快速采用？
+A:
+1. 复制 `.trellis/` 整个目录到新项目
+2. 修改 `.trellis/paths.yaml` 适配新项目的目录结构
+3. 立即可用，无需修改任何代码
+
+---
+
+## 相关文档
+
+- [三角色协作工作流](../workflow.md)
+- [Handoff 命令说明](../../.claude/commands/trellis/handoff.md)
+- [项目路径工具源码](../scripts/common/project_paths.py)

package/dist/templates/trellis/paths.yaml

@@ -0,0 +1,41 @@
+# Trellis 三角色协作路径配置
+#
+# 此文件定义项目特定的目录结构，不同项目可以自定义。
+# 如果此文件不存在，将使用默认值。
+
+# 产出物基础目录
+deliverables_base: "deliverables"
+
+# 角色产出目录映射
+role_outputs:
+  pm:
+    # PM 角色的产出目录（相对于 deliverables_base）
+    dir: "requirements"
+    # 完整路径（自动计算：deliverables_base + dir）
+    # full_path: "deliverables/requirements"
+
+  designer:
+    # Designer 角色的产出目录
+    dir: "prototypes"
+    # full_path: "deliverables/prototypes"
+
+  frontend:
+    # Frontend 角色的产出目录
+    dir: "production/features"
+    # full_path: "deliverables/production/features"
+
+# 任务池配置（池子状态文件名，通常不需要修改）
+pools:
+  pm: "requirements"
+  designer: "prototypes"
+  frontend: "implementations"
+
+# 示例：其他项目可能的配置
+# deliverables_base: "outputs"
+# role_outputs:
+#   pm:
+#     dir: "specs"
+#   designer:
+#     dir: "designs"
+#   frontend:
+#     dir: "code"

package/dist/templates/trellis/pool/implementations.json

@@ -0,0 +1,5 @@
+{
+  "available": [],
+  "consumed": [],
+  "last_updated": null
+}

package/dist/templates/trellis/pool/prototypes.json

@@ -0,0 +1,5 @@
+{
+  "available": [],
+  "consumed": [],
+  "last_updated": null
+}

package/dist/templates/trellis/pool/requirements.json

@@ -0,0 +1,5 @@
+{
+  "available": [],
+  "consumed": [],
+  "last_updated": null
+}

package/dist/templates/trellis/scripts/__init__.py

@@ -0,0 +1,5 @@
+"""
+Trellis Python Scripts
+
+This module provides Python implementations of Trellis workflow scripts.
+"""