@adonis0123/weekly-report 1.0.10 → 1.0.12

package/README.md

@@ -61,7 +61,7 @@ project-backend
 - [@adonis0123/commit](https://www.npmjs.com/package/@adonis0123/commit) - 提交信息生成
 - [@adonis0123/staged-changes-review](https://www.npmjs.com/package/@adonis0123/staged-changes-review) - 代码审查
 - [@adonis0123/create-skill](https://www.npmjs.com/package/@adonis0123/create-skill) - 创建新技能包
-
+- [@adonis0123/code-doc-generator](https://www.npmjs.com/package/@adonis0123/code-doc-generator) - 代码文档生成
 ## License
 
 MIT

package/SKILL.md

@@ -40,7 +40,58 @@ metadata:
    - 自定义周报（输入周一日期）
    - 自定义时间段（输入起始日期，截止到今天）
 
-   **重要**：选择时必须显示具体的日期范围，让用户确认是否正确
+   **重要**：
+   - 所有日期计算必须使用 **中国时区 (UTC+8 / Asia/Shanghai)**，而不是系统默认时区
+   - 选择时必须显示具体的日期范围，让用户确认是否正确
+
+   **自定义日期输入规范（必须严格遵守）**：
+
+   ⚠️ **严禁使用 AskUserQuestion 工具收集日期输入** ⚠️
+
+   **问题原因**：AskUserQuestion 工具会将数字键识别为选项快捷键，导致用户输入 "2026-01-06" 时，按下 "2" 会被当作选择了选项 2，而不是日期的一部分。
+
+   **使用场景区分**：
+   | 场景 | 工具 | 用户操作 |
+   |------|------|----------|
+   | 选项选择（本周/上周/自定义等） | AskUserQuestion | 按数字快捷键或点击选项 |
+   | 自由文本输入（日期、补充说明等） | 不使用任何工具，直接输出文本 | 输入内容后按 **Enter** 发送 |
+
+   **正确流程**：
+   1. 用 AskUserQuestion 显示时间范围选项（本周/上周/前半年/自定义周报/自定义时间段）
+   2. 如果用户选择了"自定义周报"或"自定义时间段"：
+      - **立即停止，不要调用任何工具**
+      - 直接输出纯文本提示，例如："请输入周报的周一日期（格式：YYYY-MM-DD，如 2026-01-06）："
+      - 等待用户在对话框中输入日期并按 Enter 发送
+
+   **正确的交互示例**：
+   ```
+   第一步（使用 AskUserQuestion 工具选择选项）:
+   [AskUserQuestion 工具显示选项]
+   请选择时间范围：
+   1. 本周 (2026-01-13 ~ 2026-01-19)
+   2. 上周 (2026-01-06 ~ 2026-01-12)
+   3. 前半年 (2025-07-19 ~ 2026-01-19)
+   4. 自定义周报
+   5. 自定义时间段
+
+   用户选择: 4
+
+   第二步（直接输出文本，不调用任何工具，等待用户回复）:
+   Claude 直接输出文本: "请输入周报的周一日期（格式：YYYY-MM-DD，如 2026-01-06）："
+
+   用户直接在对话框中输入: 2026-01-06
+   [用户按 Enter 发送消息]
+   ```
+
+   **错误示例（严禁）**：
+   ```
+   # 错误：使用 AskUserQuestion 工具要求用户输入日期
+   # 原因：用户按数字键会触发选项选择，无法正常输入日期
+   AskUserQuestion({
+     question: "请输入日期",
+     options: [...]  // 这种方式无法让用户自由输入日期！
+   })
+   ```
 
 2. **选择仓库**（如已配置多仓库）
    - 显示已配置的仓库列表
@@ -61,16 +112,17 @@ metadata:
 
 ## Git 提交读取（重要）
 
-为避免“只读取当前分支而漏掉其它分支（例如 `credits-lite*`）”的问题，读取提交时必须使用 `--all`（覆盖本地分支 + 远端跟踪分支），并确保截止时间包含结束日当天：
+为避免"只读取当前分支而漏掉其它分支（例如 `credits-lite*`）"的问题，读取提交时必须使用 `--all`（覆盖本地分支 + 远端跟踪分支），并确保截止时间包含结束日当天：
 
 ```bash
 # 关键点：
 # - 用 --all 覆盖所有本地 refs（包含 remotes/origin/*）
-# - --until 用 “结束日 23:59:59” 避免漏掉结束日当天提交
+# - --until 用 "结束日 23:59:59" 避免漏掉结束日当天提交
 # - --author 建议用 name + email 联合匹配，避免不同身份写法漏掉本人提交
+# - 必须使用中国时区 (UTC+8)
 
 AUTHOR_PATTERN="(your-name|your@email.com)"  # 或仅用你的 name/email
-git log --all \
+TZ='Asia/Shanghai' git log --all \
   --author="$AUTHOR_PATTERN" \
   --since="$START_DATE 00:00:00" \
   --until="$END_DATE 23:59:59" \
@@ -78,6 +130,26 @@ git log --all \
   --date=short
 ```
 
+### 日期计算（中国时区）
+
+计算"本周"、"上周"等日期时，必须基于中国时区 (UTC+8)：
+
+```bash
+# 获取中国时区的当前日期
+TODAY=$(TZ='Asia/Shanghai' date +%Y-%m-%d)
+
+# 获取中国时区的星期几（1=周一, 7=周日）
+DAY_OF_WEEK=$(TZ='Asia/Shanghai' date +%u)
+
+# 计算本周一（中国时区）
+THIS_MONDAY=$(TZ='Asia/Shanghai' date -v-$((DAY_OF_WEEK-1))d +%Y-%m-%d)
+
+# 计算本周日（中国时区）
+THIS_SUNDAY=$(TZ='Asia/Shanghai' date -v+$((7-DAY_OF_WEEK))d +%Y-%m-%d)
+```
+
+**注意**：所有显示给用户的日期都必须是中国时区的日期。
+
 如果 `git branch -a` 看不到目标远端分支（说明本地没有对应的远端跟踪引用），需要先 `git fetch --all --prune`（在用户同意且网络可用时执行），否则无法读取到“本地不存在的分支”的提交。
 
 ## 输出格式
@@ -118,14 +190,21 @@ git log --all \
 # 周报 (2026-01-06 ~ 2026-01-12)
 
 project-frontend
-  - 构建工具升级改造
-  - 核心功能开发流程跟进
-    - 方案合理性优化
-  - 脚本国际化优化
+  - [新功能] 用户登录系统开发，支持多种登录方式
+    - 接口对接和联调
+    - 表单验证优化
+    - 记住登录状态功能
+  - [修复] 认证流程问题排查修复
+    - 定位 token 过期问题
+    - 优化重试机制
+  - [优化] 构建工具升级
+  - [文档] 国际化文档更新
 
 project-backend
-  - 自定义类型化消息渲染
-  - 断线重连流程梳理
+  - [新功能] 自定义类型化消息渲染，支持多种格式
+    - 富文本渲染
+    - 图片消息支持
+  - [优化] 断线重连流程
 
 其他
   - 新版国际化方案讨论
@@ -162,6 +241,41 @@ project-backend
 - **按项目分组**：相同项目的工作归类
 - **层级清晰**：用缩进表示从属关系
 
+### 类型标签
+
+根据提交类型自动添加标签：
+
+| 类型 | 标签 | 说明 |
+|------|------|------|
+| feat | [新功能] | 新增功能 |
+| fix | [修复] | 问题修复 |
+| refactor | [优化] | 代码重构 |
+| perf | [性能] | 性能优化 |
+| docs | [文档] | 文档更新 |
+| test | [测试] | 测试相关 |
+| build | [构建] | 构建相关 |
+
+### 重点与难点体现
+
+自动识别工作的重点和难点，通过内容详略体现（而非显式标记）：
+
+- **重点工作**（feat/perf 类型 + 多次迭代）：摘要更详细，保留更多子条目
+- **难点工作**（fix 类型 + 多次尝试修复）：保留完整的排查过程细节
+- **普通工作**：简洁摘要，精简细节
+
+**示例**：
+```markdown
+project-frontend
+  - [新功能] 用户登录系统开发，支持多种登录方式
+    - 接口对接和联调
+    - 表单验证优化
+    - 记住登录状态功能
+  - [修复] 认证流程问题排查修复
+    - 定位 token 过期问题
+    - 优化重试机制
+  - [优化] 构建工具升级
+```
+
 ### 过滤规则
 
 以下提交不会单独列出：

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@adonis0123/weekly-report",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Claude Code Skill - 自动读取 Git 提交记录生成周报，支持多仓库汇总和智能过滤",
   "scripts": {
     "postinstall": "node install-skill.js",
     "preuninstall": "node uninstall-skill.js",
-    "test": "node install-skill.js && echo 'Installation test completed.'"
+    "test": "python3 -m pytest tests/ -v --tb=short",
+    "test:install": "node install-skill.js && echo 'Installation test completed.'"
   },
   "files": [
     "SKILL.md",

package/src/git_analyzer.py

@@ -10,6 +10,22 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 
+# 提交类型配置
+COMMIT_TYPE_CONFIG = {
+    "feat": {"label": "[新功能]", "priority": 1, "is_highlight": True, "is_challenge": False},
+    "fix": {"label": "[修复]", "priority": 2, "is_highlight": False, "is_challenge": True},
+    "refactor": {"label": "[优化]", "priority": 3, "is_highlight": False, "is_challenge": False},
+    "perf": {"label": "[性能]", "priority": 3, "is_highlight": True, "is_challenge": False},
+    "style": {"label": "[样式]", "priority": 6, "is_highlight": False, "is_challenge": False},
+    "docs": {"label": "[文档]", "priority": 5, "is_highlight": False, "is_challenge": False},
+    "test": {"label": "[测试]", "priority": 4, "is_highlight": False, "is_challenge": False},
+    "chore": {"label": "[杂项]", "priority": 6, "is_highlight": False, "is_challenge": False},
+    "build": {"label": "[构建]", "priority": 4, "is_highlight": False, "is_challenge": False},
+    "ci": {"label": "[CI]", "priority": 5, "is_highlight": False, "is_challenge": False},
+    "other": {"label": "", "priority": 7, "is_highlight": False, "is_challenge": False},
+}
+
+
 # 琐碎提交的关键词
 TRIVIAL_PATTERNS = [
     r"^fix\s*typo",
@@ -155,6 +171,10 @@ def get_commits(
                     "date": parts[3],
                     "type": parsed["type"],
                     "is_trivial": parsed["is_trivial"],
+                    "is_highlight": parsed["is_highlight"],
+                    "is_challenge": parsed["is_challenge"],
+                    "label": parsed["label"],
+                    "priority": parsed["priority"],
                     "project": get_repo_name(repo_path),
                 })
 
@@ -192,13 +212,25 @@ def parse_commit_message(message: str) -> Dict[str, Any]:
         message: 提交信息
 
     Returns:
-        解析后的提交信息字典
+        解析后的提交信息字典，包含：
+        - type: 提交类型
+        - scope: 作用域
+        - description: 描述
+        - is_trivial: 是否为琐碎提交
+        - is_highlight: 是否为重点（feat/perf 类型）
+        - is_challenge: 是否为难点（fix 类型）
+        - label: 类型标签（如 [新功能]）
+        - priority: 优先级（用于排序）
     """
     result = {
         "type": "other",
         "scope": None,
         "description": message,
         "is_trivial": False,
+        "is_highlight": False,
+        "is_challenge": False,
+        "label": "",
+        "priority": 7,
     }
 
     # 检查是否为琐碎提交
@@ -213,11 +245,20 @@ def parse_commit_message(message: str) -> Dict[str, Any]:
     match = re.match(conventional_pattern, message)
 
     if match:
-        result["type"] = match.group(1).lower()
+        commit_type = match.group(1).lower()
+        result["type"] = commit_type
         result["scope"] = match.group(2)
         result["description"] = match.group(3)
     else:
         result["description"] = message
+        commit_type = "other"
+
+    # 从配置中获取类型属性
+    type_config = COMMIT_TYPE_CONFIG.get(commit_type, COMMIT_TYPE_CONFIG["other"])
+    result["is_highlight"] = type_config["is_highlight"]
+    result["is_challenge"] = type_config["is_challenge"]
+    result["label"] = type_config["label"]
+    result["priority"] = type_config["priority"]
 
     return result
 

package/src/report_generator.py

@@ -6,7 +6,7 @@
 import re
 from typing import Any, Dict, List, Optional
 
-from src.git_analyzer import group_commits_by_project
+from src.git_analyzer import group_commits_by_project, COMMIT_TYPE_CONFIG
 
 
 def generate_report(
@@ -75,8 +75,9 @@ def merge_related_commits(
     """合并相关提交
 
     合并规则：
-    - 同一功能的多次迭代合并为一条
-    - 问题排查和解决归为一条
+    1. 先按 commit 类型分组（feat/fix/docs 分开）
+    2. 再按关键词合并相似提交
+    3. 按类型优先级排序输出
 
     Args:
         commits: 提交记录列表
@@ -89,48 +90,61 @@ def merge_related_commits(
     if len(commits) <= 1:
         single = commits[0].copy()
         single.setdefault("details", [])
+        single.setdefault("commit_count", 1)
         return [single]
 
-    # 按关键词分组
-    groups: Dict[str, List[Dict[str, Any]]] = {}
-
+    # 第一步：按类型分组
+    type_groups: Dict[str, List[Dict[str, Any]]] = {}
     for commit in commits:
-        # 提取关键词
-        keywords = extract_keywords(commit["message"])
-        key = frozenset(keywords) if keywords else commit["message"]
-
-        # 转换为字符串 key
-        str_key = str(sorted(keywords)) if keywords else commit["message"]
-
-        if str_key not in groups:
-            groups[str_key] = []
-        groups[str_key].append(commit)
+        commit_type = commit.get("type", "other")
+        if commit_type not in type_groups:
+            type_groups[commit_type] = []
+        type_groups[commit_type].append(commit)
 
-    # 合并同组提交（保留主条目 + 子条目细节，避免信息丢失）
+    # 第二步：在每个类型组内按关键词合并
     merged: List[Dict[str, Any]] = []
-    for group_commits in groups.values():
-        main_commit = group_commits[0].copy()
-        for c in group_commits:
-            if c.get("type") == "feat":
-                main_commit = c.copy()
-                break
-
-        details = []
-        for c in group_commits:
-            details.append(clean_commit_message(c.get("message", "")))
-
-        # 去重并保持顺序
-        seen = set()
-        uniq_details = []
-        for d in details:
-            key = d.strip()
-            if not key or key in seen:
-                continue
-            seen.add(key)
-            uniq_details.append(d.strip())
 
-        main_commit["details"] = uniq_details if len(uniq_details) > 1 else []
-        merged.append(main_commit)
+    for commit_type, type_commits in type_groups.items():
+        # 按关键词分组
+        keyword_groups: Dict[str, List[Dict[str, Any]]] = {}
+
+        for commit in type_commits:
+            keywords = extract_keywords(commit["message"])
+            str_key = str(sorted(keywords)) if keywords else commit["message"]
+
+            if str_key not in keyword_groups:
+                keyword_groups[str_key] = []
+            keyword_groups[str_key].append(commit)
+
+        # 合并同组提交
+        for group_commits in keyword_groups.values():
+            main_commit = group_commits[0].copy()
+            # 优先选择 feat 类型作为主条目
+            for c in group_commits:
+                if c.get("type") == "feat":
+                    main_commit = c.copy()
+                    break
+
+            details = []
+            for c in group_commits:
+                details.append(clean_commit_message(c.get("message", "")))
+
+            # 去重并保持顺序
+            seen = set()
+            uniq_details = []
+            for d in details:
+                key = d.strip()
+                if not key or key in seen:
+                    continue
+                seen.add(key)
+                uniq_details.append(d.strip())
+
+            main_commit["details"] = uniq_details if len(uniq_details) > 1 else []
+            main_commit["commit_count"] = len(group_commits)
+            merged.append(main_commit)
+
+    # 第三步：按优先级排序（优先级数字越小越靠前）
+    merged.sort(key=lambda x: (x.get("priority", 7), x.get("message", "")))
 
     return merged
 
@@ -165,12 +179,51 @@ def clean_commit_message(message: str) -> str:
     return re.sub(r"^(\w+)(\([^)]+\))?\s*:\s*", "", message).strip()
 
 
+def analyze_work_significance(commit: Dict[str, Any]) -> Dict[str, bool]:
+    """分析工作的重点和难点
+
+    判断规则：
+    - 重点：feat 类型 + 多次迭代（>=2次提交）或显式标记 is_highlight
+    - 难点：fix 类型 + 多次尝试（>=2次提交）或显式标记 is_challenge
+
+    Args:
+        commit: 提交记录（合并后的，含 commit_count）
+
+    Returns:
+        包含 is_highlight 和 is_challenge 的字典
+    """
+    commit_count = commit.get("commit_count", 1)
+    commit_type = commit.get("type", "other")
+
+    # 判断是否为重点
+    is_highlight = commit.get("is_highlight", False)
+    if commit_type == "feat" and commit_count >= 2:
+        is_highlight = True
+    if commit_type == "perf":
+        is_highlight = True
+
+    # 判断是否为难点
+    is_challenge = commit.get("is_challenge", False)
+    if commit_type == "fix" and commit_count >= 2:
+        is_challenge = True
+
+    return {
+        "is_highlight": is_highlight,
+        "is_challenge": is_challenge,
+    }
+
+
 def format_project_section(
     project: str,
     commits: List[Dict[str, Any]],
 ) -> str:
     """格式化项目部分
 
+    重点/难点通过以下方式体现（而非显式标记）：
+    - 重点工作：摘要字数更长（max_length=40），保留更多细节
+    - 难点工作：保留更多子条目细节
+    - 普通工作：简洁摘要（max_length=25）
+
     Args:
         project: 项目名称
         commits: 提交记录列表
@@ -181,11 +234,39 @@ def format_project_section(
     lines = [project]
 
     for commit in commits:
-        summary = summarize_commit(commit["message"])
+        # 获取类型标签
+        label = commit.get("label", "")
+
+        # 分析重点/难点
+        significance = analyze_work_significance(commit)
+
+        # 根据重要程度调整摘要长度
+        if significance["is_highlight"]:
+            # 重点工作：更长的摘要
+            max_len = 40
+        elif significance["is_challenge"]:
+            # 难点工作：适中的摘要
+            max_len = 35
+        else:
+            # 普通工作：简洁摘要
+            max_len = 25
+
+        # 生成摘要（含类型标签）
+        summary = summarize_commit(commit["message"], max_length=max_len, label=label)
+
         lines.append(f"  - {summary}")
+
+        # 添加子条目细节
+        # 重点/难点保留更多细节，普通工作限制细节数量
         details = commit.get("details") or []
-        for detail in details:
-            lines.append(f"    - {detail}")
+        if significance["is_highlight"] or significance["is_challenge"]:
+            # 重点/难点：保留所有细节（最多5条）
+            for detail in details[:5]:
+                lines.append(f"    - {detail}")
+        else:
+            # 普通工作：最多保留2条细节
+            for detail in details[:2]:
+                lines.append(f"    - {detail}")
 
     return "\n".join(lines)
 
@@ -207,21 +288,60 @@ def format_other_section(supplements: List[str]) -> str:
     return "\n".join(lines)
 
 
-def summarize_commit(message: str, max_length: int = 20) -> str:
-    """生成提交摘要
+def summarize_commit(
+    message: str,
+    max_length: int = 30,
+    label: str = "",
+) -> str:
+    """生成提交摘要（智能截断）
+
+    在自然断点处截断，避免割裂语义：
+    - 优先在标点符号处截断
+    - 其次在空格处截断
+    - 最后才硬截断
 
     Args:
         message: 提交信息
-        max_length: 最大长度
+        max_length: 最大长度（不含标签）
+        label: 类型标签（如 [新功能]）
 
     Returns:
-        摘要文本
+        带标签的摘要文本
     """
     cleaned = clean_commit_message(message)
 
-    # 截断过长的文本
+    # 截断过长的文本（智能截断）
     if len(cleaned) > max_length:
-        cleaned = cleaned[:max_length - 3] + "..."
+        # 在最大长度范围内寻找自然断点
+        truncated = cleaned[:max_length]
+
+        # 1. 优先在中文标点处截断
+        for punct in ["。", "，", "、", "；", "：", "！", "？"]:
+            idx = truncated.rfind(punct)
+            if idx > max_length // 2:  # 至少保留一半内容
+                truncated = truncated[:idx + 1]
+                break
+        else:
+            # 2. 尝试在英文标点处截断
+            for punct in [".", ",", ";", ":", "!", "?"]:
+                idx = truncated.rfind(punct)
+                if idx > max_length // 2:
+                    truncated = truncated[:idx + 1]
+                    break
+            else:
+                # 3. 尝试在空格处截断
+                idx = truncated.rfind(" ")
+                if idx > max_length // 2:
+                    truncated = truncated[:idx]
+                else:
+                    # 4. 硬截断并添加省略号
+                    truncated = truncated[:max_length - 3] + "..."
+
+        cleaned = truncated
+
+    # 添加类型标签
+    if label:
+        return f"{label} {cleaned.strip()}"
 
     return cleaned.strip()