@deepstorm/cli 0.1.0

package/dist/mcp-skills/deepflow-mcp-feishu-wiki-read/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: deepflow-mcp-feishu-wiki-read
+description: Use when you need to search and read Feishu wiki documents — search PRDs, read document content, extract requirement context. References knowledge_base domain in the capability mapping.
+---
+
+# 飞书知识库读取操作指南
+
+本指南说明如何通过飞书知识库 MCP 搜索和读取文档内容。使用前请确保 `.env` 中已配置 `DEEPFLOW_FEISHU_TOKEN`。
+
+> **领域能力：** `knowledge_base` — 知识管理
+> **服务标识：** `feishu-wiki`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_FEISHU_TOKEN=your_token`
+- Token 从飞书开放平台 > 应用凭证获取
+
+---
+
+## 常用操作
+
+### 搜索文档
+
+按关键词搜索飞书知识库文档，返回匹配的文档列表和摘要。
+
+**示例场景：**
+- 搜索 PRD 文档：搜索与当前 Issue 相关的需求文档
+- 搜索技术方案：搜索关于特定功能的讨论文档
+
+### 读取文档内容
+
+获取指定文档的完整内容，支持 Markdown 格式输出。
+
+**使用方式：**
+- 从 Issue 描述中提取的文档链接
+- 使用搜索结果的文档 ID
+
+### 提取 PRD 上下文
+
+读取到的文档内容中提取以下信息：
+
+1. **需求背景和目标** — 为什么做、解决什么问题
+2. **功能范围定义** — 做什么，不做什么
+3. **验收标准** — 如何验证
+4. **关键决策记录** — 重要的技术/产品决策及理由
+
+---
+
+## 降级处理
+
+`knowledge_base.available === false` 时：
+1. 告知用户未检测到知识库服务
+2. 询问用户是否手动提供 PRD 内容
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| Token 错误 | Token 未配置或无效 | 检查 `.env` 中 `DEEPFLOW_FEISHU_TOKEN` |
+| 文档不存在 | 链接错误或已被删除 | 确认文档链接正确 |
+| 无权限 | Token 无权访问该文档 | 确认机器人已被加入目标知识库 |

package/dist/mcp-skills/deepflow-mcp-feishu-wiki-write/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: deepflow-mcp-feishu-wiki-write
+description: Use when you need to create or update Feishu wiki documents — push PRD, update document content. References knowledge_base domain in the capability mapping.
+---
+
+# 飞书知识库写入操作指南
+
+本指南说明如何通过飞书知识库 MCP 创建和更新文档。使用前请确保 `.env` 中已配置 `DEEPFLOW_FEISHU_TOKEN`。
+
+> **领域能力：** `knowledge_base` — 知识管理
+> **服务标识：** `feishu-wiki`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_FEISHU_TOKEN=your_token`
+- Token 从飞书开放平台 > 应用凭证获取
+
+---
+
+## 常用操作
+
+### 创建文档
+
+在指定知识库或目录下创建新文档，需提供：
+- 标题
+- 正文（Markdown 格式）
+- 目标知识库或目录
+
+**典型场景：** 将 PRD 推送到知识库，方便团队查阅。
+
+### 更新文档
+
+修改已有文档的内容。
+
+---
+
+## 多 Provider 选择
+
+| 场景 | 处理方式 |
+|------|---------|
+| 唯一 provider | 自动推送，无需用户选择 |
+| 多个 provider | 展示可用列表，用户选择后持久化 |
+
+---
+
+## 降级处理
+
+`knowledge_base.available === false` 时：
+1. 跳过知识库写入操作
+2. 在 checklist 中记录为 skipped
+3. 告知用户未检测到知识库服务，跳过 PRD 推送
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| Token 错误 | Token 未配置或无效 | 检查 `.env` |
+| 文档不存在 | 链接错误或已被删除 | 确认目标文档存在 |
+| 无权限 | Token 无权操作该文档 | 确认机器人权限 |

package/dist/mcp-skills/deepflow-mcp-figma-read/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: deepflow-mcp-figma-read
+description: Use when you need to read Figma design data — get file info, read node tree, get components and styles, export images. References design_tools domain in the capability mapping.
+---
+
+# Figma 设计稿读取操作指南
+
+本指南说明如何通过 Figma MCP 读取设计稿数据。使用前请确保 `.env` 中已配置 `DEEPFLOW_FIGMA_TOKEN`。
+
+> **领域能力：** `design_tools` — 设计工具
+> **服务标识：** `figma`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_FIGMA_TOKEN=your_token`
+- Token 从 Figma > Settings > Personal Access Tokens 生成
+
+---
+
+## 运行时能力确认
+
+操作前先确认 Figma MCP 是否可用：
+
+```
+检查 `.claude/settings.json` → `deepflow.mcpCapabilities` 中 design_tools.available === true
+```
+
+---
+
+## 设计链接识别
+
+### 从 Issue Design 字段获取（推荐）
+
+从 Issue MCP 返回的数据中查找设计相关字段（如 Jira 的 `customfield_10032`），提取其中的 URL。
+
+从 URL 中提取：
+
+| 参数 | 说明 |
+|------|------|
+| `fileKey` | 文件标识，从 URL path 获取 |
+| `nodeId` | 节点标识，从 URL query（`node-id` 参数）获取 |
+
+### 从 Issue 描述回退
+
+Design 字段不存在或为空时，回退到 Issue 描述中正则匹配设计工具链接。
+
+---
+
+## 常用操作
+
+### 文件操作
+
+| 操作 | 说明 |
+|------|------|
+| 获取文件信息 | 获取元数据：名称、版本、最后修改时间 |
+| 读取文件内容 | 获取完整节点树结构 |
+| 获取节点 | 获取指定节点的详细信息和样式属性 |
+| 获取图片 | 导出节点为 PNG/JPEG/SVG |
+| 获取文件版本 | 文件历史版本列表 |
+
+### 组件和样式
+
+| 操作 | 说明 |
+|------|------|
+| 获取本地组件 | 文件中所有本地组件及其属性 |
+| 获取团队组件 | 团队组件库中的组件 |
+| 获取样式 | TextStyle、ColorStyle、EffectStyle |
+
+---
+
+## 设计数据分析
+
+设计数据获取后，可派遣子代理进行分析：
+
+1. 保存原始 JSON 到 `openspec/changes/{change}/design-data/raw-{slug}.json`
+2. 如有图片资源则下载到 `openspec/changes/{change}/design-assets/`
+3. 子代理输出结构化摘要：布局结构、关键 UI 元素、交互流程、响应式信息
+
+---
+
+## 降级处理
+
+`design_tools.available === false` 时：
+1. 告知用户未检测到设计工具服务
+2. 跳过设计稿获取
+3. 不影响其他工作流
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `Invalid token` | Token 无效或过期 | 在 Figma 设置中重新生成 |
+| `File not found` | 链接错误或无访问权限 | 确认 URL 正确，检查分享权限 |
+| `Node not found` | Node ID 错误 | 确认节点 ID 存在于当前文件版本 |

package/dist/mcp-skills/deepflow-mcp-github-read/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: deepflow-mcp-github-read
+description: Use when you need to read GitHub data — browse repository files, list branches, search code, view Issues and Pull Requests. References code-hosting domain in the capability mapping.
+---
+
+# GitHub 读取操作指南
+
+本指南说明如何通过 GitHub MCP 读取仓库数据。使用前请确保 `.env` 中已配置 `DEEPFLOW_GITHUB_TOKEN`。
+
+> **领域能力：** `code-hosting` — 代码托管
+> **服务标识：** `github`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_GITHUB_TOKEN=your_token`
+- Token 从 https://github.com/settings/tokens 生成，至少需要 `repo` 和 `read:org` 权限
+- 需要本地 Docker 环境
+
+---
+
+## 常用操作
+
+### 仓库浏览
+
+| 操作 | 说明 |
+|------|------|
+| 查看仓库详情 | 元信息：描述、语言、Star 数、License |
+| 查看文件内容 | 指定路径的文件内容 |
+| 列出分支 | 仓库所有分支列表 |
+
+### 代码搜索
+
+| 操作 | 说明 |
+|------|------|
+| 搜索代码 | 在仓库范围内搜索代码片段 |
+| 搜索 Issue/PR | 按关键词、状态、作者搜索 |
+
+### Issue 和 PR 查看
+
+| 操作 | 说明 |
+|------|------|
+| 获取 PR 详情 | 描述、变更文件列表、评论、检查状态 |
+| 获取 Issue 详情 | Issue 描述和全部评论 |
+| 列出 Issue/PR | 按状态、标签、Assignee 筛选 |
+
+---
+
+## 降级处理
+
+`code-hosting.available === false` 时，降级为使用 `gh` CLI 命令替代。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `Resource not accessible` | Token 权限不足 | 检查 Token 的 scope |
+| `Not Found` | 仓库不存在或无权限 | 确认仓库名和权限 |
+| Docker 错误 | Docker 未启动 | 确认 Docker 正在运行 |

package/dist/mcp-skills/deepflow-mcp-github-write/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: deepflow-mcp-github-write
+description: Use when you need to write to GitHub — create/update Issues, create Pull Requests, submit comments, create/update files. References code-hosting domain in the capability mapping.
+---
+
+# GitHub 写入操作指南
+
+本指南说明如何通过 GitHub MCP 创建和修改仓库内容。使用前请确保 `.env` 中已配置 `DEEPFLOW_GITHUB_TOKEN`。
+
+> **领域能力：** `code-hosting` — 代码托管
+> **服务标识：** `github`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_GITHUB_TOKEN=your_token`
+- Token 从 https://github.com/settings/tokens 生成，至少需要 `repo` 权限
+
+---
+
+## 常用操作
+
+### Issue 管理
+
+| 操作 | 说明 |
+|------|------|
+| 创建 Issue | 附带标题、描述、标签、Assignee |
+| 更新 Issue | 修改标题、描述、标签、状态 |
+| 关闭/重新打开 | 管理 Issue 生命周期 |
+| 添加评论 | 在 Issue 上回复 |
+
+### Pull Request
+
+| 操作 | 说明 |
+|------|------|
+| 创建 PR | 指定源/目标分支、标题、描述，支持 Draft PR |
+| 更新 PR 描述 | 修改 PR 描述 |
+| 合并 PR | merge/squash/rebase |
+| 添加 Review Comment | 在 PR 上提交 Review 评论 |
+
+### 文件操作
+
+| 操作 | 说明 |
+|------|------|
+| 创建文件 | 在指定路径创建新文件 |
+| 更新文件 | 修改已有文件内容 |
+
+---
+
+## 降级处理
+
+`code-hosting.available === false` 时，降级为使用 `gh` CLI 命令替代。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `Resource not accessible` | Token 权限不足 | 检查 Token 的 scope 配置 |
+| `Not Found` | 仓库不存在或无权限 | 确认仓库名和权限 |
+| `Conflict` | 合并冲突/分支已存在 | 先解决冲突或检查分支状态 |

package/dist/mcp-skills/deepflow-mcp-jira-read/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: deepflow-mcp-jira-read
+description: Use when you need to read Jira Issue data — get issue details, search issues, extract custom fields. References issue_tracker domain in the capability mapping.
+---
+
+# Jira Issue 读取操作指南
+
+本指南说明如何通过 Jira MCP 读取 Issue 数据。使用前请确保 `.env` 中已配置 `DEEPFLOW_JIRA_TOKEN`。
+
+> **领域能力：** `issue_tracker` — 项目管理
+> **服务标识：** `jira`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_JIRA_TOKEN=your_token`
+- Token 从 https://id.atlassian.com/manage/api-tokens 生成
+
+---
+
+## 运行时能力确认
+
+操作前先确认 Jira MCP 是否可用：
+
+```
+检查 `.claude/settings.json` → `deepflow.mcpCapabilities` 中 issue_tracker.available === true（providers 包含 jira）
+```
+
+---
+
+## 常用操作
+
+### 解析 Issue 标识
+
+| 输入格式 | 示例 | 提取方式 |
+|---------|------|---------|
+| 完整 URL | `https://<instance>.atlassian.net/browse/LC-1234` | 从 URL path 提取 `LC-1234` |
+| 完整编号 | `LC-1234` | 直接使用 |
+| 纯数字 | `1234` | 需结合项目前缀 |
+
+### 获取 Issue 详情
+
+调用 Jira MCP 的获取 Issue 工具，传入解析后的 Issue Key。
+
+**提取的元数据结构：**
+
+```json
+{
+  "key": "LC-1234",
+  "title": "Issue 摘要",
+  "url": "https://<instance>.atlassian.net/browse/LC-1234",
+  "type": "Story",
+  "status": "In Progress",
+  "description": "Issue 描述正文"
+}
+```
+
+### 提取自定义字段
+
+从返回数据中查找设计工具关联字段（如 `customfield_10032`），提取其中的 Figma/Figma 链接。
+
+---
+
+## 降级处理
+
+`issue_tracker.available === false` 时：
+
+1. 告知用户未检测到 Issue 跟踪服务
+2. 请求用户手动粘贴 Issue 摘要和描述
+3. 从用户提供的信息提取所需元数据
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `Authentication failed` | Token 无效 | 检查 `.env` 中 `DEEPFLOW_JIRA_TOKEN` |
+| `Issue not found` | Key 错误或无权限 | 确认 Key 正确，检查项目访问权限 |

package/dist/mcp-skills/deepflow-mcp-jira-write/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: deepflow-mcp-jira-write
+description: Use when you need to create, update, transition, or comment on Jira Issues. References issue_tracker domain in the capability mapping.
+---
+
+# Jira Issue 写入操作指南
+
+本指南说明如何通过 Jira MCP 创建和修改 Issue。使用前请确保 `.env` 中已配置 `DEEPFLOW_JIRA_TOKEN`。
+
+> **领域能力：** `issue_tracker` — 项目管理
+> **服务标识：** `jira`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPFLOW_JIRA_TOKEN=your_token`
+- Token 从 https://id.atlassian.com/manage/api-tokens 生成
+
+---
+
+## 常用操作
+
+### 创建 Issue
+
+调用 Jira MCP 的创建 Issue 工具，需提供：
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| 项目 Key | 项目标识 | `PROJ` |
+| Issue 类型 | Story/Task/Bug/Sub-task | `Task` |
+| 摘要（Summary） | 标题 | `用户登录功能优化` |
+| 描述（Description） | Markdown 正文 | 详细描述 |
+| 父任务（可选） | Sub-task 的父级 | `PROJ-123` |
+
+### 更新 Issue 字段
+
+调用 Jira MCP 的更新 Issue 工具，可更新：摘要、描述、优先级、经办人、标签。
+
+### 状态流转（Transition）
+
+1. **先查询**：调用 Jira MCP 获取可用的 transitions 列表
+2. **再流转**：选择目标 transition 执行
+
+常见流转路径：`To Do → In Progress → In Review → Done`
+
+### 添加评论
+
+调用 Jira MCP 的添加评论工具，支持 Markdown 格式。
+
+---
+
+## 多 Provider 选择
+
+当 `issue_tracker.available === true` 且有多个 provider 时，展示可用列表供用户选择。
+
+---
+
+## 降级处理
+
+`issue_tracker.available === false` 时：
+1. 跳过 Issue 创建/更新操作
+2. 在 checklist 中记录为 skipped
+3. 提示用户手动在 Jira 中操作
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `Authentication failed` | Token 无效 | 检查 `.env` |
+| `Transition not allowed` | 该状态流转在当前工作流中不允许 | 先查询可用的 transitions 列表 |
+| `Field not on screen` | Jira 项目配置限制 | 确认字段在 project workflow 中可见 |

package/dist/mcp-skills/deepflow-mcp-playwright-read/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: deepflow-mcp-playwright-read
+description: Use when you need to perform browser automation — navigate pages, click elements, fill forms, extract content, take screenshots. References e2e-testing domain in the capability mapping.
+---
+
+# Playwright MCP 浏览器操作指南
+
+本指南说明如何通过 Playwright MCP 操作浏览器执行 E2E 测试步骤。使用前请确保 DeepFlow 安装时已选择 Playwright MCP 服务，连接地址已硬编码在 `.mcp.json` 中（默认 `http://localhost:54321/sse`）。
+
+> **领域能力：** `browser-automation` — 端到端测试
+> **服务标识：** `playwright`
+
+---
+
+## 环境要求
+
+- Playwright MCP 连接地址已硬编码在 `.mcp.json` 的 `deepflow-playwright` 服务中（默认 `http://localhost:54321/sse`）
+- 确保 Playwright MCP 进程已在本地运行（默认端口 54321）
+
+---
+
+## 运行时能力确认
+
+操作前先确认 Playwright MCP 是否可用：
+
+```
+检查 `.claude/settings.json` → `deepflow.mcpCapabilities` 中 browser-automation.available === true（providers 包含 playwright）
+```
+
+---
+
+## 常用操作
+
+### 页面导航
+
+```text
+使用 Playwright MCP 的 navigate 工具，传入目标 URL
+```
+
+### 元素交互
+
+| 操作 | 工具 | 参数 |
+|------|------|------|
+| 点击 | click | selector（CSS 选择器） |
+| 填写 | fill | selector + value |
+| 选择 | selectOption | selector + value |
+| 悬停 | hover | selector |
+
+### 内容提取
+
+```text
+使用 evaluate 或 textContent 工具，通过选择器提取页面文本内容
+```
+
+### 截图
+
+```text
+使用 screenshot 工具，可指定全页截图或视口截图
+```
+
+---
+
+## 降级处理
+
+`browser-automation.available === false` 时：
+
+1. 告知用户未检测到浏览器自动化服务
+2. 提示用户运行 `deepflow setup` 并选择 Playwright MCP
+3. 或手动配置 `.mcp.json` 中的 `deepflow-playwright` 服务
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| `Connection refused` | Playwright MCP 未启动 | 检查 `.mcp.json` 中 `deepflow-playwright` 的 `url` 配置，启动 Playwright MCP 服务 |
+| `Element not found` | 选择器不匹配 | 使用浏览器 DevTools 检查正确选择器 |
+| `Timeout` | 页面加载慢 | 增加等待时间或使用 waitForSelector |

package/dist/mcp-skills/deepstorm-mcp-feishu-wiki-read/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: deepstorm-mcp-feishu-wiki-read
+description: Use when you need to search and read Feishu wiki documents — search PRDs, read document content, extract requirement context. References knowledge_base domain in the capability mapping.
+---
+
+# 飞书知识库读取操作指南
+
+本指南说明如何通过飞书知识库 MCP 搜索和读取文档内容。使用前请确保 `.env` 中已配置 `DEEPSTORM_FEISHU_TOKEN`。
+
+> **领域能力：** `knowledge_base` — 知识管理
+> **服务标识：** `feishu-wiki`
+
+---
+
+## 环境要求
+
+- `.env` 文件须包含 `DEEPSTORM_FEISHU_TOKEN=your_token`
+- Token 从飞书开放平台 > 应用凭证获取
+
+---
+
+## 常用操作
+
+### 搜索文档
+
+按关键词搜索飞书知识库文档，返回匹配的文档列表和摘要。
+
+**示例场景：**
+- 搜索 PRD 文档：搜索与当前 Issue 相关的需求文档
+- 搜索技术方案：搜索关于特定功能的讨论文档
+
+### 读取文档内容
+
+获取指定文档的完整内容，支持 Markdown 格式输出。
+
+**使用方式：**
+- 从 Issue 描述中提取的文档链接
+- 使用搜索结果的文档 ID
+
+### 提取 PRD 上下文
+
+读取到的文档内容中提取以下信息：
+
+1. **需求背景和目标** — 为什么做、解决什么问题
+2. **功能范围定义** — 做什么，不做什么
+3. **验收标准** — 如何验证
+4. **关键决策记录** — 重要的技术/产品决策及理由
+
+---
+
+## 降级处理
+
+`knowledge_base.available === false` 时：
+1. 告知用户未检测到知识库服务
+2. 询问用户是否手动提供 PRD 内容
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 处理 |
+|------|------|------|
+| Token 错误 | Token 未配置或无效 | 检查 `.env` 中 `DEEPSTORM_FEISHU_TOKEN` |
+| 文档不存在 | 链接错误或已被删除 | 确认文档链接正确 |
+| 无权限 | Token 无权访问该文档 | 确认机器人已被加入目标知识库 |