openclaw/skills/gsd-openclaw/.planning/phases/02-integration-layer/02-CONTEXT.md

Phase 2: Integration Layer - Context

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

## Phase Boundary

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

## 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 文档）
• 代码块在卡片中的渲染方式
• 卡片的颜色主题和图标选择
• 分页时的断点位置（避免截断代码块或表格）

## Specific Ideas

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

<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 Ideas

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

---

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