# Phase 2: Integration Layer - Context

**Gathered:** 2026-03-11
**Status:** Ready for planning

<domain>
## Phase Boundary

创建 OpenClaw 技能定义（SKILL.md）、频道自适应响应格式化和提示模板，使 OpenClaw 能够加载和调用技能。这是 gsd-openclaw 技能的"门面"层，定义了如何触发技能以及如何向用户呈现输出。

</domain>

<decisions>
## Implementation Decisions

### SKILL.md 触发器设计
- **触发模式**: 仅 `/gsd:*` 命令，不支持自然语言触发
- **命令匹配**: 通配符 `/gsd:*` 模式，由 orchestrator.py 验证命令有效性
- **技能描述**: 详细描述，包含功能说明和示例命令
- **项目上下文**: 显式切换项目模式（`/gsd:use <project>` 设置当前项目）

### 频道格式化策略
- **支持频道**: 仅飞书（Phase 2）
- **消息格式**: 飞书卡片消息（Card Message）
- **交互元素**:
  - 交互按钮（用于审批确认、操作触发）
  - 下拉选择器（用于项目选择等）
  - 链接按钮（跳转到 OpenClaw 控制面板）

### 卡片布局规范
- **三区结构**:
  - 标题区：命令名 + 状态图标（成功/失败/进行中）
  - 内容区：GSD 输出内容
  - 操作区：相关按钮（确认/取消/查看详情等）

### 长消息处理
- **处理方式**: 分页发送（超出限制时自动分割）
- **分页呈现**: 消息编号 `[1/N]` 标记在消息末尾

### 错误消息格式化
- **格式**: 错误卡片（红色警示样式）
- **内容**: 错误标题 + 详情 + 建议操作
- **项目不存在时**: 错误卡片 + 「创建新项目」按钮 + 「查看我的项目」按钮

### GSD 审批流程集成
- **审批方式**: 飞书按钮交互
- **流程**: GSD 请求确认时，发送带「确认」/「取消」按钮的卡片，用户点击即完成审批

### Prompt 模板设计
- **模板类型**:
  - `context_recovery.md`: 上下文恢复（会话中断后恢复）
  - `command_mapping.md`: 命令映射（用户输入解析）
  - `error_recovery.md`: 错误处理（生成用户友好的错误消息）
- **模板格式**: Markdown 模板，变量用 `{{variable}}` 标记

### Claude's Discretion
- 单条消息的精确字符限制（根据飞书 API 文档）
- 代码块在卡片中的渲染方式
- 卡片的颜色主题和图标选择
- 分页时的断点位置（避免截断代码块或表格）

</decisions>

<specifics>
## Specific Ideas

- 卡片设计参考飞书官方的机器人消息样式
- 错误卡片使用红色主题，成功卡片使用绿色主题
- 按钮文案保持简洁（2-4 个中文字符）

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- **Phase 1 state_manager.py**: 可用于获取用户的项目列表（显示在「查看我的项目」时）
- **Phase 1 tmux_session.py**: 提供会话状态（可用于判断当前项目上下文）
- **Phase 1 cli.py**: 命令解析模式可参考

### Established Patterns
- **状态持久化**: JSON 格式，原子写入
- **错误处理**: 中文错误消息 + 异常类
- **命名规范**: gsd- 前缀统一

### Integration Points
- 本 phase 产出的 `response_formatter.py` 将被 Phase 3 的 `orchestrator.py` 调用
- `SKILL.md` 定义了 OpenClaw 加载技能的入口
- `prompts/` 目录的模板将被 Phase 3/4 的命令处理逻辑使用

</code_context>

<deferred>
## Deferred Ideas

- 微信频道支持（Phase 3 或后续）
- Telegram/Discord 频道支持（Phase 3 或后续）
- 多语言支持（中文/英文切换）
- 卡片主题自定义

</deferred>

---

*Phase: 02-integration-layer*
*Context gathered: 2026-03-11*