@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/diag/skills/init/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: init
+description: |
+  初始化 Diag 插件 - 创建 ~/.claude-diag/ 配置目录 + 服务清单模板 + 依赖检查
+---
+
+# /diag:init - 初始化 Diag 插件
+
+首次使用 Diag 插件时执行，完成以下事项：
+
+1. **依赖检查**：`python3`、`jq`、`ssh`、`yq` 或 `pyyaml`
+2. **创建目录**：`~/.claude-diag/{config,audit}/`（700 权限）
+3. **生成配置模板**：`~/.claude-diag/config/services.yaml`（600 权限）
+4. **引导配置**：让用户将真实服务登记到 `services.yaml`
+5. **配置校验**：确保必填字段齐全
+6. **（可选）空跑测试**：SSH `echo ok` 验证 Hook 链路
+
+---
+
+## 执行流程
+
+### 1. 运行初始化脚本
+
+调用 `init-diag.sh`，该脚本会：
+- 检查 `python3 / jq / ssh / yq(或 pyyaml)` 是否可用，缺失则终止
+- 创建 `~/.claude-diag/config/` 和 `~/.claude-diag/audit/`
+- 若 `services.yaml` 不存在，则从模板拷贝（已存在时不覆盖）
+- 打印目录结构和下一步指引
+
+### 2. 创建项目 Runbook 目录
+
+在当前项目的 `docs/runbooks/` 创建事故处理文档骨架，仅当文件不存在时创建：
+
+| 文件 | 用途 |
+|------|------|
+| `db-slow-query.md` | 数据库慢查询处理 |
+| `oom.md` | 内存溢出处理 |
+| `5xx-spike.md` | 接口报错飙升处理 |
+| `deployment-rollback.md` | 部署回滚流程 |
+
+每个文件使用统一的 5 节骨架，节内容留空，在 `/diag:diagnose` 诊断完事故后由 AI 协作补写：
+
+```markdown
+# <事故类型>
+
+> <一行用途说明>
+
+## 什么时候用
+
+<!-- 触发条件和典型症状 -->
+
+## 必备输入
+
+<!-- 开始诊断前需要收集的信息（日志、监控指标、错误码等） -->
+
+## 触发方式
+
+<!-- /diag:diagnose 命令模板 + 需要提供的上下文 -->
+
+## 优质输出标准
+
+<!-- 定位到根因、给出可执行的修复步骤 -->
+
+## 常见失败模式
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+```
+
+若不在 git 仓库目录下运行（`git rev-parse --is-inside-work-tree` 失败），跳过此步骤。
+
+### 3. 引导用户编辑服务清单
+
+脚本结束后向用户展示：
+
+```
+✅ 已创建配置模板：~/.claude-diag/config/services.yaml
+
+请现在告诉我你的服务信息，我帮你填写（或你自己编辑后回复"已填写"）：
+
+- 服务名（如 order-api）：
+- 主机（对应 ~/.ssh/config 里的 Host 名 或 user@ip）：
+- 日志路径（可以多条）：
+- 语言栈（可选，java/node/python/go/ruby/php）：
+```
+
+**用户配合方式**：
+- **方式 A（对话录入）**：用户说"服务名 order-api，主机 prod-web-01，日志 /var/log/app/order.log"，AI 用 `Edit` 工具改 `~/.claude-diag/config/services.yaml`
+- **方式 B（自行编辑）**：用户说"我自己编辑"，AI 等待用户说"已填写"后继续校验
+
+### 4. 校验配置
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/services-config.sh" validate
+```
+
+- 通过 → 展示服务数量
+- 失败 → 展示具体错误（缺字段 / 重名 / language_hint 非法），让用户修复后重试
+
+### 5. （可选）Hook 空跑测试
+
+询问用户是否跑一次空测试：
+
+```
+是否执行一次空测试？（SSH <host> 'echo ok' 验证 Hook 链路是否生效）  [Y/n]
+```
+
+若同意：
+1. 从 `services.yaml` 取第一个服务的 host
+2. 执行 `ssh <host> 'echo ok'`（应被 Hook 放行，因 echo 在白名单）
+3. 展示退出码和 `~/.claude-diag/audit/` 下的 JSONL 条目，证明链路通
+
+**注意**：本期不强制执行空测试，用户拒绝即跳过。
+
+### 6. 输出总结
+
+```
+✅ Diag 插件初始化完成
+
+配置：~/.claude-diag/config/services.yaml（2 个服务）
+审计：~/.claude-diag/audit/
+Runbook：docs/runbooks/（4 个骨架文件，诊断完事故后补写内容）
+
+下一步：
+- /diag:diagnose <报错描述>   开始诊断
+- /diag:audit                 查审计日志
+```
+
+---
+
+## 边界
+
+- 只在 **primary** 仓库意义上执行（插件无 primary/readonly 区分，但应在用户本机执行，不要在 CI/CD 环境）
+- `~/.claude-diag/` 不纳入任何仓库；多机协作时，每台机器独立 init
+
+## 故障排查
+
+| 问题 | 诊断 |
+|---|---|
+| `yq/pyyaml 都没装` | 选一：`brew install yq` 或 `pip3 install pyyaml` |
+| `services.yaml 已存在` | 脚本不覆盖，可手动 `rm ~/.claude-diag/config/services.yaml` 后重 init |
+| `Hook 不生效` | 重启 Claude Code 让插件加载；检查 `.claude/settings.local.json` 的 `enabledPlugins.diag@devflow: true` |

package/plugins/diag/skills/stack-analyzer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: stack-analyzer
+description: |
+  生产报错堆栈识别助手。仅在执行 /diag:diagnose 命令期间触发。
+  根据日志片段识别多语言栈的异常格式（Java / Node / Python / Go / Ruby / PHP 等），
+  抽取异常类型、错误消息、堆栈帧（文件/行号/方法），为下一步本地代码关联提供结构化输入。
+---
+
+# 生产报错堆栈识别助手
+
+## 触发条件
+
+仅在执行 `/diag:diagnose` 命令并获取到日志片段后触发。
+
+## 输入
+
+- `log_snippet`：SSH 拉回的日志文本（tail + grep 后）
+- `language_hint`（可选）：服务配置里的语言提示，值为 `java / node / python / go / ruby / php` 之一
+
+## 输出（结构化）
+
+```yaml
+error_type: "java.lang.NullPointerException"      # 异常类 / 错误类型
+message: "Cannot invoke ... because coupon is null"   # 核心消息
+frames:
+  - file: "OrderService.java"
+    line: 142
+    method: "com.example.order.OrderService.submit"
+    qualified: "com.example.order.OrderService"
+  - file: "OrderController.java"
+    line: 87
+    method: "com.example.order.OrderController.create"
+    qualified: "com.example.order.OrderController"
+evidence: "2026-04-20 02:31:05 [http-nio-8080-exec-3] ERROR ..."   # 原始行截取，便于对照
+```
+
+无法识别时输出：
+
+```yaml
+error_type: "unknown"
+message: "<摘要>"
+frames: []
+note: "未识别堆栈格式，原始片段见 evidence"
+evidence: "<原始日志截取>"
+```
+
+## 识别策略（按 language_hint 优先）
+
+### Java (Spring / Tomcat 等)
+
+格式特征：
+```
+java.lang.NullPointerException: Cannot invoke ...
+    at com.example.Foo.bar(Foo.java:42) ~[app.jar:?]
+    at com.example.Baz.qux(Baz.java:87) ~[app.jar:?]
+Caused by: ...
+```
+
+抽取规则：
+- 异常行：正则 `^\w+(?:\.\w+)*(?:Exception|Error)(?::.*)?$`
+- 帧行：`at <qualified>.<method>\(<file>:<line>\)`
+- 保留 `Caused by` 链
+
+### Node.js (V8 trace)
+
+格式特征：
+```
+TypeError: Cannot read property 'foo' of undefined
+    at OrderService.submit (/app/src/services/order.js:142:15)
+    at /app/src/routes/order.js:87:23
+    at processTicksAndRejections (node:internal/process/task_queues:96:5)
+```
+
+抽取规则：
+- 首行：`<ErrorType>: <message>`
+- 帧：`at (?:<method> )?\((?<file>.+):(?<line>\d+):(?<col>\d+)\)` 或 `at (?<file>.+):(?<line>\d+):(?<col>\d+)`
+- 内置模块（`node:internal/`）标注为"运行时内部"
+
+### Python
+
+格式特征：
+```
+Traceback (most recent call last):
+  File "/app/order/service.py", line 142, in submit
+    return self._calculate(coupon.discount)
+AttributeError: 'NoneType' object has no attribute 'discount'
+```
+
+抽取规则：
+- 帧：`File "<file>", line <line>, in <method>`
+- 末行：`<ErrorType>: <message>`
+
+### Go
+
+格式特征：
+```
+panic: runtime error: invalid memory address or nil pointer dereference
+[signal SIGSEGV: segmentation violation]
+
+goroutine 42 [running]:
+main.(*OrderService).Submit(0xc0001f0000, 0x0)
+        /app/order/service.go:142 +0x2a
+main.orderHandler(...)
+        /app/order/handler.go:87
+```
+
+抽取规则：
+- panic 首行 → error_type + message
+- 帧：下一行是 `<file>:<line>`，上一行是 `<pkg>.<method>`
+
+### Ruby
+
+格式特征：
+```
+NoMethodError (undefined method `discount' for nil:NilClass):
+  app/services/order_service.rb:142:in `submit'
+  app/controllers/orders_controller.rb:87:in `create'
+```
+
+抽取规则：
+- 首行：`<ErrorType> (<message>)`
+- 帧：`<file>:<line>:in '<method>'`
+
+### PHP
+
+格式特征：
+```
+PHP Fatal error:  Uncaught TypeError: ... in /app/OrderService.php:142
+Stack trace:
+#0 /app/OrderController.php(87): OrderService->submit()
+#1 {main}
+```
+
+抽取规则：
+- 首行：`TypeError: <message>`
+- 帧：`#<n> <file>(<line>): <class>-><method>\(\)`
+
+### 未知 / 混合
+
+若 `language_hint` 为空且首行不匹配上述特征：
+- 尝试全部模式，取命中数最多的
+- 仍无命中 → 输出 `error_type: "unknown"`，把日志中 `ERROR`/`Exception` 附近 20 行作为 evidence 返回
+
+## 使用建议
+
+- **不要构造堆栈**：识别不出就说"未识别"，不要猜测或编造帧。
+- **保留原文**：`evidence` 字段必须是原始日志片段，便于人工核对。
+- **优先 language_hint**：命中后不再尝试其他语言，减少误识别。
+- **只抽取第一个异常链**：日志片段中可能有多个异常，只取最早/最完整的那个。
+- **裁剪噪声**：框架内部帧（如 `org.springframework.web.*`、`node:internal/*`）放到 frames 末尾或标注，避免喧宾夺主。

package/plugins/pm/skills/ask/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ask
+description: |
+  自由提问 - 基于项目数据回答任何项目相关问题
+---
+
+# 自由提问
+
+> **Audience:** Product Manager
+
+基于项目的 PRD、需求文档、Git 记录等数据，回答任何项目相关问题。
+
+## 命令格式
+
+```
+/pm:ask <问题>
+```
+
+**示例：**
+- `/pm:ask 还有几个需求没完成？`
+- `/pm:ask 上周谁的提交最多？`
+- `/pm:ask 哪个模块的需求最多？`
+- `/pm:ask 最近一个版本包含了哪些功能？`
+- `/pm:ask 项目的技术栈是什么？`
+- `/pm:ask 帮我写一段给客户的进展邮件`
+
+---
+
+## 执行流程
+
+### 1. 分析问题意图
+
+根据问题关键词判断需要哪些数据：
+
+```python
+question = args.question
+
+# 关键词 → 数据源映射
+if matches(question, ["需求", "进度", "完成", "待办", "状态"]):
+    data["reqs"] = collect_requirements()
+
+if matches(question, ["提交", "代码", "贡献", "git", "变更"]):
+    data["git"] = collect_git_stats()
+
+if matches(question, ["模块", "功能", "架构"]):
+    data["modules"] = collect_modules()
+
+if matches(question, ["PRD", "产品", "愿景", "规划", "技术栈"]):
+    data["prd"] = collect_prd()
+
+if matches(question, ["版本", "发布", "tag", "里程碑"]):
+    data["tags"] = git_tags()
+
+# 无法判断时，采集全部数据
+if not data:
+    data = collect_all()
+```
+
+### 2. AI 基于数据回答
+
+**回答原则：**
+- 必须基于实际项目数据，不编造
+- 给出具体数字和引用
+- 如果数据不足以回答，明确说明缺少什么
+- 区分事实和推测
+
+### 3. 输出格式
+
+自由格式，根据问题类型调整：
+- 数量类问题 → 简短数字回答 + 详细列表
+- 分析类问题 → 结构化分析
+- 生成类问题 → 直接生成内容
+- 对比类问题 → 表格对比
+
+```
+
+/pm:ask
+
+
+Q: <用户问题>
+
+A: <基于项目数据的回答>
+
+
+```
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/pm/skills/brief/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: brief
+description: |
+  项目简介 - 生成面向新人或客户的项目概述
+---
+
+# 项目简介
+
+> **Audience:** Product Manager
+
+生成项目概述文档，适合给新成员、客户或外部合作方了解项目全貌。
+
+## 命令格式
+
+```
+/pm:brief [--lang=zh|en] [--audience=新人|客户|外部] [--save]
+```
+
+**参数说明：**
+- `--lang`：可选，语言，默认 zh（中文）
+- `--audience`：可选，受众，影响语言风格和侧重点，默认「新人」
+- `--save`：可选，直接保存不询问
+
+---
+
+## 执行流程
+
+### 1. 采集数据
+
+```python
+prd = collect_prd()        # 产品愿景、功能规划
+reqs = collect_requirements()
+modules = collect_modules()
+git = collect_git_stats()   # 代码规模
+```
+
+### 2. 按受众生成
+
+| 受众 | 侧重点 |
+|------|--------|
+| 新人 | 技术栈、项目结构、模块职责、如何上手 |
+| 客户 | 产品愿景、核心功能、交付进度、技术保障 |
+| 外部 | 项目概况、规模、成熟度 |
+
+### 3. 输出格式
+
+```
+
+项目简介
+
+
+## 项目概述
+
+（从 PRD 愿景提取，或 AI 根据项目数据总结）
+
+## 核心功能
+
+（从模块文档和已完成需求推导）
+
+| 模块 | 核心功能 | 状态 |
+|------|---------|------|
+| 用户模块 | 注册、登录、积分、等级 | 运行中 |
+| 订单模块 | 下单、支付、退款、导出 | 开发中 |
+
+## 技术架构
+
+（从 CLAUDE.md 和 PRD 技术选型提取）
+
+## 项目规模
+
+| 指标 | 数值 |
+|------|------|
+| 代码行数 | ~XX,XXX |
+| 源文件数 | XX |
+| 需求总数 | XX（已完成 XX） |
+| 版本数量 | XX |
+| 团队规模 | XX 人 |
+
+## 当前进展
+
+（从活跃需求推导当前重点工作）
+
+
+*由 /pm:brief 自动生成 · YYYY-MM-DD*
+```
+
+### 4. 提供保存选项
+
+```python
+offer_save(content, "docs/reports/brief.md")
+```
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/pm/skills/export/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: export
+description: |
+  导出内容 - 将 pm 生成的内容保存到 docs/reports/
+---
+
+# 导出内容
+
+> **Audience:** Product Manager
+
+将最近一次 pm 命令生成的内容保存到 `docs/reports/` 目录。
+也可以直接指定要执行的命令并保存结果。
+
+## 命令格式
+
+```
+/pm:export [命令名] [--format=md] [--path=自定义路径]
+```
+
+**参数说明：**
+- `命令名`：可选，指定要执行并导出的命令（如 `weekly`、`stats`）
+- `--format`：可选，输出格式，默认 md
+- `--path`：可选，自定义保存路径
+
+**示例：**
+- `/pm:export weekly` — 生成周报并直接保存
+- `/pm:export stats --from=2026-03-01` — 生成统计并保存
+- `/pm:export --path=给客户的报告.md` — 保存到自定义路径
+
+---
+
+## 执行流程
+
+### 1. 确定内容来源
+
+```python
+if args.command:
+    # 执行指定命令获取内容
+    content = execute_pm_command(args.command, args)
+else:
+    # 提示用户指定命令
+    print("请指定要导出的命令：")
+    print("  /pm:export weekly")
+    print("  /pm:export stats")
+    print("  /pm:export progress")
+    exit()
+```
+
+### 2. 确定保存路径
+
+```python
+if args.path:
+    save_path = args.path
+else:
+    # 按命令类型自动生成路径
+    paths = {
+        "weekly": f"docs/reports/weekly/{to_date}.md",
+        "monthly": f"docs/reports/monthly/{month}.md",
+        "milestone": f"docs/reports/milestone/{version}.md",
+        "stats": f"docs/reports/stats/{today}.md",
+        "progress": f"docs/reports/progress/{today}.md",
+        "risk": f"docs/reports/risk/{today}.md",
+        "plan": f"docs/reports/plans/{topic_slug}.md",
+        "brief": "docs/reports/brief.md",
+    }
+    save_path = paths.get(args.command, f"docs/reports/custom/{today}.md")
+```
+
+### 3. 保存文件
+
+```python
+mkdir_p(dirname(save_path))
+write_file(save_path, content)
+print(f"已保存到 {save_path}")
+```
+
+### 4. 输出确认
+
+```
+导出成功
+
+文件路径：docs/reports/weekly/2026-03-26.md
+内容类型：周报
+生成日期：2026-03-26
+
+**后续操作：**
+- git add docs/reports/  提交到版本控制
+- /pm:help              查看其他命令
+```
+
+## 用户输入
+
+$ARGUMENTS