zco-claude 0.0.8__py3-none-any.whl

ClaudeSettings/hooks/save_chat_spec.py

@@ -0,0 +1,398 @@
+#!/usr/bin/env python3
+"""
+Claude Code 对话自动保存脚本（增强版）
+保存完整对话 + 工具调用 + 参考资源
+
+Environment Variables:
+- YJ_CLAUDE_CHAT_SAVE_SPEC: Must be "1" to enable this hook
+- YJ_CLAUDE_CHAT_SAVE_DIR: Output directory (default: ${GIT_ROOT}/_.claude_hist)
+"""
+import json
+import os
+import sys
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Set
+
+
+def extract_keywords(text: str, max_keywords: int = 3) -> str:
+    """从文本中提取关键词"""
+    text = re.sub(r'[^\w\s\u4e00-\u9fff]', ' ', text)
+    words = text.split()
+
+    stop_words = {'的', '了', '是', '在', '我', '有', '和', '就', '不', '人', '都', '一', '一个',
+                  'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'is', 'are',
+                  '请', '帮', '我要', '能否', '如何', '什么', '怎么', '吗', '呢'}
+
+    keywords = []
+    for word in words:
+        word = word.strip()
+        if len(word) >= 2 and word not in stop_words:
+            if word not in keywords:
+                keywords.append(word)
+                if len(keywords) >= max_keywords:
+                    break
+
+    if not keywords:
+        return "对话记录"
+
+    return '_'.join(keywords[:max_keywords])
+
+def get_git_root(project_dir: Path=None) -> Path:
+    """获取当前 Git 仓库根目录"""
+    try:
+        # 执行 git rev-parse --show-toplevel 命令
+        if project_dir:
+            result = subprocess.run(
+                ['git', '-C', str(project_dir), 'rev-parse', '--show-toplevel'],
+                capture_output=True, text=True, check=True
+            )
+        else:
+            result = subprocess.run(
+                ['git', 'rev-parse', '--show-toplevel'],
+                capture_output=True, text=True, check=True
+            )
+        return Path(result.stdout.strip())
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return Path.cwd()
+    
+def get_hist_dir(project_dir: Path=None) -> Path:
+    """获取历史记录目录"""
+    hist_dir_name = os.environ.get('YJ_CLAUDE_CHAT_SAVE_DIR', None)
+    git_root = get_git_root(project_dir)
+    if not hist_dir_name:
+        hist_dir = git_root / '_.claude_hist'
+    else:
+        hist_dir = os.path.abspath(os.path.join(str(git_root), hist_dir_name))
+    hist_dir.mkdir(exist_ok=True)
+    return hist_dir
+
+def format_message_content(msg_data: Any) -> str:
+    """格式化消息内容（支持 Claude Code 格式）"""
+    # Claude Code 格式：外层 message 对象包含 role 和 content
+    if isinstance(msg_data, dict) and 'message' in msg_data:
+        msg_data = msg_data.get('message', {})
+
+    # 提取 content
+    content = msg_data.get('content', msg_data) if isinstance(msg_data, dict) else msg_data
+    if not content:
+        return ''
+    if isinstance(content, str):
+        return content
+    elif isinstance(content, list):
+        parts = []
+        for item in content:
+            if isinstance(item, dict):
+                if item.get('type') == 'text':
+                    parts.append(item.get('text', ''))
+                elif item.get('type') == 'tool_use':
+                    tool_name = item.get('name', 'unknown')
+                    parts.append(f"\n[使用工具: {tool_name}]\n")
+            elif isinstance(item, str):
+                parts.append(item)
+        return ''.join(parts)
+    return str(content)
+
+
+def extract_tool_calls(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """提取所有工具调用（支持 Claude Code 格式）"""
+    tool_calls = []
+
+    for msg in messages:
+        # Claude Code 格式：type 在外层
+        msg_type = msg.get('type', '')
+        if msg_type != 'assistant':
+            continue
+
+        # 内层 message 对象
+        inner_msg = msg.get('message', {})
+        content = inner_msg.get('content', [])
+        if not isinstance(content, list):
+            continue
+
+        for item in content:
+            if isinstance(item, dict) and item.get('type') == 'tool_use':
+                tool_calls.append({
+                    'name': item.get('name', 'unknown'),
+                    'input': item.get('input', {}),
+                    'id': item.get('id', '')
+                })
+
+    return tool_calls
+
+
+def extract_tool_results(messages: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """提取工具返回结果（支持 Claude Code 格式）"""
+    tool_results = {}
+
+    for msg in messages:
+        # Claude Code 格式：检查外层 type
+        msg_type = msg.get('type', '')
+        if msg_type != 'user':
+            continue
+
+        # 检查是否有 toolUseResult
+        tool_result = msg.get('toolUseResult')
+        if tool_result and isinstance(tool_result, dict):
+            tool_id = tool_result.get('tool_use_id', '')
+            result_content = tool_result.get('content', '')
+
+            # 解析结果内容
+            if isinstance(result_content, list):
+                text_parts = []
+                for part in result_content:
+                    if isinstance(part, dict) and part.get('type') == 'text':
+                        text_parts.append(part.get('text', ''))
+                result_content = '\n'.join(text_parts)
+
+            tool_results[tool_id] = result_content
+
+        # 也检查内层 message 中的 content
+        inner_msg = msg.get('message', {})
+        content = inner_msg.get('content', [])
+        if not isinstance(content, list):
+            continue
+
+        for item in content:
+            if isinstance(item, dict) and item.get('type') == 'tool_result':
+                tool_id = item.get('tool_use_id', '')
+                result_content = item.get('content', '')
+
+                # 解析结果内容
+                if isinstance(result_content, list):
+                    text_parts = []
+                    for part in result_content:
+                        if isinstance(part, dict) and part.get('type') == 'text':
+                            text_parts.append(part.get('text', ''))
+                    result_content = '\n'.join(text_parts)
+
+                tool_results[tool_id] = result_content
+
+    return tool_results
+
+
+def extract_references(tool_calls: List[Dict], tool_results: Dict) -> Set[str]:
+    """提取参考资源（URLs、文件路径等）"""
+    references = set()
+
+    # 从工具调用中提取
+    for call in tool_calls:
+        tool_name = call.get('name', '')
+        tool_input = call.get('input', {})
+
+        # WebFetch 工具
+        if tool_name == 'WebFetch' or tool_name == 'WebSearch':
+            url = tool_input.get('url', '')
+            if url:
+                references.add(f"🌐 {url}")
+
+        # Read 工具
+        elif tool_name == 'Read':
+            file_path = tool_input.get('file_path', '')
+            if file_path:
+                references.add(f"📄 {file_path}")
+
+        # Task 工具（Agent 调用）
+        elif tool_name == 'Task':
+            agent_type = tool_input.get('subagent_type', '')
+            if agent_type:
+                references.add(f"🤖 Agent: {agent_type}")
+
+    # 从工具结果中提取 URLs
+    for result in tool_results.values():
+        if isinstance(result, str):
+            # 提取 http/https URLs
+            urls = re.findall(r'https?://[^\s<>"{}|\\^`\[\]]+', result)
+            for url in urls:
+                references.add(f"🌐 {url}")
+
+    return references
+
+
+def parse_transcript(transcript_path: str) -> List[Dict[str, Any]]:
+    """解析 Claude Code 的会话文件（JSONL 格式）"""
+    messages = []
+
+    try:
+        with open(transcript_path, 'r', encoding='utf-8') as f:
+            for line in f:
+                try:
+                    msg = json.loads(line.strip())
+                    # 只保留 user 和 assistant 类型的消息
+                    if msg and msg.get('type') in ['user', 'assistant']:
+                        messages.append(msg)
+                except json.JSONDecodeError:
+                    continue
+    except Exception as e:
+        print(f"Error reading transcript: {e}", file=sys.stderr)
+        return []
+
+    return messages
+
+
+def generate_markdown(messages: List[Dict[str, Any]],
+                     tool_calls: List[Dict],
+                     references: Set[str]) -> str:
+    """将消息列表转换为 Markdown 格式（增强版）"""
+    if not messages:
+        return "# 对话记录\n\n无对话内容。\n"
+
+    lines = []
+    lines.append("# Claude Code 对话记录\n")
+    lines.append(f"**时间**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+
+    # 添加参考资源部分
+    if references:
+        lines.append("\n## 📚 参考资源\n")
+        for ref in sorted(references):
+            lines.append(f"- {ref}\n")
+
+    # 添加工具使用统计
+    if tool_calls:
+        lines.append(f"\n**使用工具**: {len(tool_calls)} 次\n")
+        tool_counts = {}
+        for call in tool_calls:
+            name = call.get('name', 'unknown')
+            tool_counts[name] = tool_counts.get(name, 0) + 1
+        for name, count in sorted(tool_counts.items()):
+            lines.append(f"  - {name}: {count} 次\n")
+
+    lines.append("\n---\n")
+
+    # 对话内容
+    for idx, msg in enumerate(messages, 1):
+        msg_type = msg.get('type', 'unknown')
+        text = format_message_content(msg)
+        if text.strip() == '':
+            continue
+
+        if msg_type == 'user':
+            lines.append(f"\n## 👤 用户提问 #{idx}\n")
+            lines.append(f"{text}\n")
+        elif msg_type == 'assistant':
+            lines.append(f"\n## 🤖 Claude 回答 #{idx}\n")
+            lines.append(f"{text}\n")
+
+    lines.append("\n---\n")
+
+    # 附录：详细的工具调用记录
+    if tool_calls:
+        lines.append("\n## 📋 附录：工具调用详情\n")
+        for idx, call in enumerate(tool_calls, 1):
+            lines.append(f"\n### 工具 {idx}: {call.get('name', 'unknown')}\n")
+            lines.append("```json\n")
+            lines.append(json.dumps(call, indent=2, ensure_ascii=False, default=str))
+            lines.append("\n```\n")
+
+    lines.append(f"\n---\n")
+    lines.append(f"*自动生成于 {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}*\n")
+
+    return '\n'.join(lines)
+
+
+def save_resources(references: Set[str], output_dir: Path, base_filename: str):
+    """保存参考资源列表到单独文件"""
+    if not references:
+        return
+
+    resources_file = output_dir / f"{base_filename}_resources.txt"
+
+    try:
+        with open(resources_file, 'w', encoding='utf-8') as f:
+            f.write(f"# 参考资源\n")
+            f.write(f"# 生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+            f.write(f"# 对话文件: {base_filename}.md\n\n")
+
+            for ref in sorted(references):
+                f.write(f"{ref}\n")
+
+        print(f"Resources saved to: {resources_file}", file=sys.stderr)
+    except Exception as e:
+        print(f"Error saving resources: {e}", file=sys.stderr)
+
+
+def save_conversation(transcript_path: str, project_dir: str):
+    """保存对话到 Markdown 文件（增强版）"""
+    try:
+        # 解析会话文件
+        messages = parse_transcript(transcript_path)
+        if not messages:
+            print("No messages to save", file=sys.stderr)
+            return
+
+        # 提取工具调用和结果
+        tool_calls = extract_tool_calls(messages)
+        tool_results = extract_tool_results(messages)
+        references = extract_references(tool_calls, tool_results)
+
+        # 提取第一个用户提问作为关键词来源
+        first_user_msg = ""
+        for msg in messages:
+            if msg.get('type') == 'user':
+                first_user_msg = format_message_content(msg)
+                if first_user_msg:
+                    break
+
+        # 提取关键词
+        keywords = extract_keywords(first_user_msg) if first_user_msg else "spec"
+
+        # 生成文件名: YYmmddHH_{关键词}
+        timestamp = datetime.now().strftime('%y%m%d_%H%M%S')
+        base_filename = f"claude_log_{timestamp}_{keywords}"
+        filename = f"{base_filename}.md"
+
+        # 使用环境变量指定的目录，默认 _.claude_hist
+        hist_dir = get_hist_dir(project_dir)
+
+        # 生成 Markdown 内容
+        markdown_content = generate_markdown(messages, tool_calls, references)
+
+        # 保存主文件
+        output_file = hist_dir / filename
+        with open(output_file, 'w', encoding='utf-8') as f:
+            f.write(markdown_content)
+
+        print(f"Conversation saved to: {output_file}", file=sys.stderr)
+
+        # 保存参考资源列表
+        save_resources(references, hist_dir, base_filename)
+
+    except Exception as e:
+        print(f"Error saving conversation: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc(file=sys.stderr)
+
+
+def main():
+    """主函数"""
+    try:
+        # Check if this hook is enabled via environment variable
+        if os.environ.get('YJ_CLAUDE_CHAT_SAVE_SPEC') != '1':
+            # Silently exit if not enabled
+            sys.exit(0)
+
+        input_data = json.load(sys.stdin)
+        hook_event = input_data.get('hook_event_name', '')
+
+        if hook_event == 'Stop':
+            transcript_path = input_data.get('transcript_path', '')
+            cwd = input_data.get('cwd', '')
+
+            if transcript_path and cwd:
+                save_conversation(transcript_path, cwd)
+            else:
+                print(f"Missing required data: transcript_path={transcript_path}, cwd={cwd}", file=sys.stderr)
+
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"Hook error: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

ClaudeSettings/rules/README.md

@@ -0,0 +1,270 @@
+# 项目开发规范
+
+本目录包含项目的编程标准和开发规范。
+
+## 📚 规范文档
+
+### Go 语言规范
+
+- **[coding-standards.md](go/coding-standards.md)** - Go 项目编程标准
+  - 注释规范（`//` vs `//;` 约定）
+  - 命名规范
+  - 代码组织
+  - 错误处理
+  - 并发编程
+  - 测试规范
+  - 性能优化
+
+## 🛠️ 工具脚本
+
+### Go 项目工具
+
+1. **`check-standards.sh`** - 全面的代码标准检查
+   ```bash
+   # 在项目根目录运行
+   ./.claude/rules/go/check-standards.sh
+   ```
+
+   检查项：
+   - ✅ 代码格式（gofmt）
+   - ✅ Imports 顺序（goimports）
+   - ✅ 测试通过率
+   - ✅ 测试覆盖率（≥ 80%）
+   - ✅ 竞态条件检测
+   - ✅ Linter 检查
+   - ✅ 注释规范统计
+
+2. **`list-comments.sh`** - 列出所有非代码注释
+   ```bash
+   # 在项目根目录运行
+   ./.claude/rules/go/list-comments.sh
+   ```
+
+   显示：
+   - 📋 TODO 列表
+   - 🔧 FIXME 列表
+   - ⚠️ HACK 列表
+   - ⚡ OPTIMIZE 列表
+   - 🗑️ DEPRECATED 列表
+   - 📝 NOTE 列表
+
+## 🚀 快速开始
+
+### 1. 安装必要工具
+
+```bash
+# 安装 golangci-lint
+curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
+
+# 安装 goimports
+go install golang.org/x/tools/cmd/goimports@latest
+```
+
+### 2. 配置项目
+
+在项目根目录创建 `.golangci.yml`：
+
+```yaml
+linters:
+  enable:
+    - gofmt
+    - goimports
+    - govet
+    - errcheck
+    - staticcheck
+    - unused
+    - gosimple
+    - ineffassign
+    - deadcode
+    - typecheck
+    - gocyclo
+    - funlen
+
+linters-settings:
+  gocyclo:
+    min-complexity: 10
+  funlen:
+    lines: 50
+    statements: 40
+```
+
+### 3. 设置 Git Hooks（可选）
+
+创建 `.git/hooks/pre-commit`：
+
+```bash
+#!/bin/bash
+./.claude/rules/go/check-standards.sh
+```
+
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+### 4. 在代码中使用注释约定
+
+```go
+package main
+
+// Add 计算两个整数的和
+// 这是标准的代码注释，使用 //
+func Add(a, b int) int {
+    //; TODO: 添加溢出检查
+    //; NOTE: 这个函数会在 v2.0 中支持浮点数
+    return a + b
+}
+
+//; DEPRECATED: 使用 Add 函数替代
+//; 此函数将在 v2.0 移除
+func AddLegacy(a, b int) int {
+    return a + b
+}
+```
+
+## 📋 注释规范速查
+
+| 前缀 | 用途 | 示例 |
+|------|------|------|
+| `//` | 代码功能注释 | `// CalculateTotal 计算订单总金额` |
+| `//; TODO:` | 待实现功能 | `//; TODO: 添加参数验证` |
+| `//; FIXME:` | 需要修复的问题 | `//; FIXME: Redis 连接超时问题` |
+| `//; HACK:` | 临时解决方案 | `//; HACK: 等待 API v2 升级后移除` |
+| `//; OPTIMIZE:` | 性能优化点 | `//; OPTIMIZE: 可以使用批量查询` |
+| `//; DEPRECATED:` | 已废弃代码 | `//; DEPRECATED: 使用 NewAPI 替代` |
+| `//; NOTE:` | 开发者备注 | `//; NOTE: 这里需要考虑并发安全` |
+| `//; DEBUG:` | 调试信息 | `//; DEBUG: 临时日志，发布前删除` |
+
+## 🎯 质量标准
+
+### 强制要求（MUST）
+
+- ✅ 代码覆盖率 ≥ 80%
+- ✅ 无编译错误和 linter 错误
+- ✅ 所有测试通过
+- ✅ 无竞态条件
+- ✅ 正确使用注释标记（`//` vs `//;`）
+
+### 推荐要求（SHOULD）
+
+- ⭐ 函数长度 ≤ 50 行
+- ⭐ 圈复杂度 ≤ 10
+- ⭐ 参数数量 ≤ 5 个
+- ⭐ 无重复代码
+
+## 📖 使用示例
+
+### 示例 1：检查代码标准
+
+```bash
+# 运行完整检查
+$ ./.claude/rules/go/check-standards.sh
+
+🔍 开始检查 Go 编程标准...
+
+📝 [1/7] 检查代码格式...
+✓ 代码格式正确
+
+📦 [2/7] 检查 imports 顺序...
+✓ Imports 顺序正确
+
+🧪 [3/7] 运行测试...
+✓ 所有测试通过
+
+📊 [4/7] 检查测试覆盖率...
+✓ 测试覆盖率: 87.5% (≥ 80%)
+
+🏃 [5/7] 检查竞态条件...
+✓ 无竞态条件
+
+🔍 [6/7] 运行 linter...
+✓ Linter 检查通过
+
+💬 [7/7] 检查注释规范...
+   - TODO: 3 项
+   - FIXME: 1 项
+   - HACK: 0 项
+   - DEPRECATED: 0 项
+
+================================
+✓ 所有检查通过！
+```
+
+### 示例 2：查看待办事项
+
+```bash
+# 列出所有非代码注释
+$ ./.claude/rules/go/list-comments.sh
+
+💬 Go 项目非代码注释列表
+======================================
+
+📋 TODO 列表:
+./service/user.go:45://; TODO: 添加邮箱验证
+./handler/order.go:78://; TODO: 实现订单取消功能
+
+🔧 FIXME 列表:
+./cache/redis.go:23://; FIXME: Redis 连接偶尔超时
+
+⚠️  HACK 列表:
+   (无)
+
+======================================
+📊 统计信息:
+   TODO:       2 项
+   FIXME:      1 项
+   HACK:       0 项
+```
+
+## 🔧 集成到 IDE
+
+### VS Code
+
+创建 `.vscode/settings.json`：
+
+```json
+{
+  "go.lintTool": "golangci-lint",
+  "go.lintOnSave": "package",
+  "go.formatTool": "gofmt",
+  "editor.formatOnSave": true
+}
+```
+
+### GoLand / IntelliJ IDEA
+
+1. Settings → Tools → File Watchers
+2. 添加 gofmt 和 goimports
+3. Settings → Editor → Inspections → Go
+4. 启用所有推荐的检查项
+
+## 📝 提交代码前检查清单
+
+在提交代码前，确保：
+
+- [ ] 运行 `check-standards.sh` 并全部通过
+- [ ] 使用 `list-comments.sh` 检查是否有未完成的 TODO/FIXME
+- [ ] 所有新增代码都有单元测试
+- [ ] 所有导出的函数都有文档注释（使用 `//`）
+- [ ] 所有 TODO、FIXME 等使用 `//;` 前缀
+- [ ] 代码已通过 code review
+
+## 🤝 贡献规范更新
+
+如果需要更新或改进这些规范：
+
+1. 修改对应的 `.md` 文件
+2. 如有必要，更新检查脚本
+3. 在团队中讨论并达成共识
+4. 提交 PR 并说明修改原因
+
+## 📚 参考资源
+
+- [Effective Go](https://golang.org/doc/effective_go)
+- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
+- [Uber Go Style Guide](https://github.com/uber-go/guide)
+- [Google Go Style Guide](https://google.github.io/styleguide/go/)
+
+---
+
+**维护者**: 开发团队
+**最后更新**: 2026-01-06