@colin4k1024/tsp 2.4.0

package/skills/agent-dev-workshop/references/phase5-codegen.md

@@ -0,0 +1,182 @@
+# Phase 5: 代码生成（Code Generation）引导细则
+
+## 入口条件
+
+- Phase 4 的 `agent-prompts.md` 和 `agent-orchestration.md` 已确认
+- 已知目标框架和所有设计文档
+
+## 前置检查
+
+### 加载框架适配器
+
+1. 读取 `adk-framework-adapters` 中目标框架的 reference 文件
+2. 检查 `verified_date` 字段：
+   - 距今 ≤ 90 天：正常使用
+   - 距今 > 90 天：提醒用户「框架 {name} 的适配器最后验证于 {date}，API 可能已变化。建议在生成后仔细检查 import 路径和 API 名称」
+3. 从 reference 文件中加载：项目模板结构、依赖配置、惯用模式、示例代码片段
+
+## 项目结构生成
+
+### 通用结构（框架无关）
+
+```
+{agent_name}/
+├── README.md
+├── .env.example
+├── .gitignore
+├── {dependency_file}               # pyproject.toml / go.mod / package.json
+├── src/
+│   ├── __init__.py                 # Python only
+│   ├── agent.{ext}                 # Agent 核心入口
+│   ├── config.{ext}                # 配置加载
+│   ├── tools/
+│   │   ├── __init__.{ext}
+│   │   ├── {tool_1}.{ext}
+│   │   └── {tool_2}.{ext}
+│   ├── prompts/
+│   │   ├── system.txt              # System Prompt 文本
+│   │   └── templates/              # 其他 Prompt 模板
+│   ├── memory/
+│   │   └── store.{ext}            # Memory 实现
+│   └── orchestrator/               # Multi-Agent 时
+│       ├── __init__.{ext}
+│       ├── router.{ext}
+│       └── workflow.{ext}
+├── tests/
+│   ├── test_agent.{ext}
+│   ├── test_tools.{ext}
+│   └── conftest.{ext}             # Python pytest fixture / Go testmain
+├── configs/
+│   └── default.yaml                # 默认运行配置
+├── data/                           # RAG Agent 的知识库目录
+│   └── .gitkeep
+└── scripts/
+    ├── run.sh                      # 启动脚本
+    ├── ingest.sh                   # RAG 数据导入脚本（如适用）
+    └── test.sh                     # 测试脚本
+```
+
+### 文件扩展名映射
+
+| 框架 | 语言 | ext | 依赖文件 |
+|------|------|-----|----------|
+| LangChain | Python | py | pyproject.toml |
+| LangChain.js | TypeScript | ts | package.json |
+| EINO | Go | go | go.mod |
+| AutoGen | Python | py | pyproject.toml |
+| AgentScope | Python | py | pyproject.toml |
+| CrewAI | Python | py | pyproject.toml |
+
+## 代码生成规则
+
+### 通用规则
+
+1. **所有敏感配置通过环境变量**：API Key、数据库连接串、Token 等一律从 `.env` 读取，不硬编码
+2. **`.env.example` 标注所有必需变量**：标注变量名、用途、格式要求
+3. **类型标注**：Python 使用 type hints，Go 天然类型安全，TypeScript 使用严格类型
+4. **错误处理**：每个工具调用都有 try-catch 和有意义的错误消息
+5. **日志**：使用框架原生日志机制，关键节点有 INFO 级日志
+6. **配置分层**：`.env` → `configs/default.yaml` → 代码默认值
+
+### 框架特定规则
+
+框架特定的代码模式、import 路径、初始化方式见对应的 `adk-framework-adapters/references/{framework}.md`。
+
+### 代码生成顺序
+
+1. 依赖文件（`pyproject.toml` / `go.mod` / `package.json`）
+2. 配置文件（`.env.example`、`configs/default.yaml`）
+3. 工具实现（`src/tools/*.{ext}`）— 最独立的部分
+4. Memory 实现（`src/memory/store.{ext}`）
+5. Prompt 文件（`src/prompts/system.txt`）
+6. Agent 核心（`src/agent.{ext}`）— 串联工具 + memory + prompt
+7. 编排逻辑（`src/orchestrator/`）— Multi-Agent 时
+8. 入口脚本（`scripts/run.sh`）
+9. 测试文件（`tests/`）
+10. README.md
+
+### 逐文件确认规则
+
+对以下核心文件，生成后必须单独展示并等待用户确认：
+- `src/agent.{ext}`（Agent 核心）
+- `src/orchestrator/*.{ext}`（编排逻辑，如有）
+- 每个工具的实现（`src/tools/*.{ext}`）
+
+辅助文件（配置、脚本、.gitignore）可以批量展示确认。
+
+## README.md 模板
+
+```markdown
+# {Agent Name}
+
+{Agent Description}
+
+## 架构
+
+{从 agent-architecture.md 复制 Mermaid 图}
+
+## 快速开始
+
+### 前置条件
+
+- {language} {version}
+- {其他依赖}
+
+### 安装
+
+\`\`\`bash
+{install_command}
+\`\`\`
+
+### 配置
+
+复制环境变量模板并填写：
+
+\`\`\`bash
+cp .env.example .env
+# 编辑 .env 填写 API Key 等配置
+\`\`\`
+
+### 运行
+
+\`\`\`bash
+{run_command}
+\`\`\`
+
+### 测试
+
+\`\`\`bash
+{test_command}
+\`\`\`
+
+## 工具列表
+
+| 工具 | 描述 |
+|------|------|
+| {tool_name} | {tool_desc} |
+
+## 项目结构
+
+\`\`\`
+{tree_output}
+\`\`\`
+
+## License
+
+MIT
+```
+
+## --import 模式特殊处理
+
+Phase 5 在 import 模式下的行为：
+1. 对比原框架 vs 目标框架的关键差异，生成 `migration-diff.md`
+2. 原 Agent 的每个工具在新框架中必须有等效实现
+3. 原 Prompt 保持不变（除非框架要求调整格式）
+4. 生成后展示 `migration-diff.md` 供用户确认
+
+## 确认点
+
+1. 先展示完整项目结构树
+2. 逐个展示核心代码文件
+3. 批量展示辅助文件
+4. 用户整体确认后进入 Phase 6

package/skills/agent-dev-workshop/references/phase6-verification.md

@@ -0,0 +1,160 @@
+# Phase 6: 验证与迭代（Verification & Iteration）引导细则
+
+## 入口条件
+
+- Phase 5 的完整项目代码已生成并确认
+- 项目文件已写入磁盘
+
+## 验证步骤
+
+### Step 1: 依赖安装
+
+根据框架执行依赖安装：
+
+| 框架 | 安装命令 |
+|------|---------|
+| LangChain (Python) | `cd {project_dir} && pip install -e .` 或 `pip install -r requirements.txt` |
+| LangChain.js | `cd {project_dir} && npm install` |
+| EINO (Go) | `cd {project_dir} && go mod tidy` |
+| AutoGen | `cd {project_dir} && pip install -e .` |
+| AgentScope | `cd {project_dir} && pip install -e .` |
+| CrewAI | `cd {project_dir} && pip install -e .` |
+
+**失败处理**：
+- 依赖冲突 → 检查版本兼容性并调整
+- 缺少系统依赖 → 提示用户安装（如 `libpq-dev`）
+- 网络问题 → 建议使用镜像源
+
+### Step 2: 语法与类型检查
+
+| 语言 | 检查命令 |
+|------|---------|
+| Python | `python -m py_compile src/agent.py` + `mypy src/ --ignore-missing-imports`（如有 mypy） |
+| TypeScript | `npx tsc --noEmit` |
+| Go | `go build ./...` + `go vet ./...` |
+
+### Step 3: 单元测试
+
+执行生成的测试文件：
+
+| 语言 | 测试命令 |
+|------|---------|
+| Python | `cd {project_dir} && python -m pytest tests/ -v` |
+| TypeScript | `cd {project_dir} && npm test` |
+| Go | `cd {project_dir} && go test ./... -v` |
+
+**预期**：基础测试（工具函数、配置加载）应该在不需要真实 API Key 的情况下通过。
+
+### Step 4: Smoke Test
+
+模拟一轮 Agent 交互验证端到端可用性。
+
+**前提**：用户需要先配置 `.env`（至少 LLM API Key）。
+
+**Smoke Test 方式**：
+
+```python
+# Python 示例
+from src.agent import create_agent
+
+agent = create_agent()
+response = agent.run("你好，请帮我...")
+print(response)
+```
+
+```go
+// Go 示例
+agent := createAgent()
+response, err := agent.Run(context.Background(), "你好，请帮我...")
+fmt.Println(response)
+```
+
+**无 API Key 时的降级策略**：
+- 提供 mock LLM 配置选项，返回固定响应
+- 至少验证：Agent 初始化成功、工具注册成功、Prompt 加载成功
+
+### Step 5: 失败定位与修复
+
+如验证失败，按以下流程处理：
+
+```
+失败 → 读取错误信息
+     → 分析根因（import 错误 / 类型错误 / 配置缺失 / API 变更）
+     → 修复代码
+     → 重跑验证
+     → 最多 3 轮自动修复
+     → 仍失败则暂停，向用户说明问题并寻求指引
+```
+
+如果错误复杂，可调用 `systematic-debugging` skill 进行系统化调试。
+
+## --import 模式的额外验证
+
+导入模式下需要额外验证行为一致性：
+
+1. **工具等效性**：逐个工具验证输入/输出与原实现一致
+2. **Prompt 保真度**：对比原 System Prompt 和新框架中的 Prompt 是否语义一致
+3. **编排一致性**：模拟相同输入，验证 Agent 行为路径是否匹配
+4. 生成 `migration-validation.md` 记录验证结果
+
+## 验证报告模板
+
+```markdown
+# Agent Verification Report
+
+## 基本信息
+
+| 项目 | 值 |
+|------|-----|
+| Agent 名称 | {name} |
+| 框架 | {framework} |
+| 验证时间 | {timestamp} |
+
+## 验证结果
+
+| 步骤 | 状态 | 说明 |
+|------|------|------|
+| 依赖安装 | ✅/❌ | {detail} |
+| 语法检查 | ✅/❌ | {detail} |
+| 类型检查 | ✅/❌ | {detail} |
+| 单元测试 | ✅/❌ | {passed}/{total} 通过 |
+| Smoke Test | ✅/❌/⏭️ | {detail} |
+
+## 问题与修复
+
+| # | 问题 | 根因 | 修复方案 | 状态 |
+|---|------|------|----------|------|
+| 1 | {issue} | {root_cause} | {fix} | ✅/⏳ |
+
+## 用户操作指引
+
+### 运行你的 Agent
+
+\`\`\`bash
+{step_by_step_instructions}
+\`\`\`
+
+### 下一步建议
+
+1. 配置 `.env` 文件
+2. 运行 Smoke Test 验证端到端
+3. 根据实际使用调整 Prompt
+4. 添加更多测试用例
+```
+
+## 迭代循环
+
+验证通过后：
+1. 展示验证报告给用户
+2. 告知用户如何运行和测试
+3. 用户测试后如有反馈 → 回到对应 Phase 调整：
+   - Prompt 调整 → Phase 4 → 重新生成 prompt 文件
+   - 工具调整 → Phase 3 → 更新工具 + 重新生成
+   - 架构调整 → Phase 2 → 较大改动
+4. 每次迭代只影响变更点及其下游
+
+## 完成条件
+
+- 验证报告全部 ✅（Smoke Test 可以跳过但需说明）
+- 用户确认 Agent 可用
+- 更新 tracking.md Phase 6 为 ✅

package/skills/agent-dev-workshop/references/shared.md

@@ -0,0 +1,123 @@
+# 共享引用：框架映射与通用常量
+
+## 框架-语言映射表
+
+| 框架 | 语言 | 包管理器 | 依赖文件 | 测试框架 | 最低版本要求 |
+|------|------|---------|----------|----------|-------------|
+| LangChain | Python | pip/uv | pyproject.toml | pytest | Python 3.9+ |
+| LangGraph | Python | pip/uv | pyproject.toml | pytest | Python 3.9+ |
+| LangChain.js | TypeScript | npm/pnpm | package.json | vitest/jest | Node 18+ |
+| EINO | Go | go modules | go.mod | go test | Go 1.21+ |
+| AutoGen | Python | pip/uv | pyproject.toml | pytest | Python 3.9+ |
+| AgentScope | Python | pip/uv | pyproject.toml | pytest | Python 3.9+ |
+| CrewAI | Python | pip/uv | pyproject.toml | pytest | Python 3.9+ |
+
+## Agent 类型 → 架构模式映射
+
+| Agent 类型 | 默认架构模式 | 典型组件 |
+|-----------|-------------|---------|
+| ReAct | 单 Agent + Tool Loop | Agent Core, LLM, Tool Registry |
+| Multi-Agent Conversation | 多 Agent + Router | Orchestrator, N×Agent, Shared Memory |
+| Multi-Agent Workflow | DAG / Pipeline | Orchestrator, N×Agent, State Manager |
+| RAG Agent | Retrieve → Generate | Agent, Retriever, Vector Store, LLM |
+| Tool-Use Agent | Tool Chain | Agent Core, LLM, Tool Registry |
+| Autonomous Agent | Plan → Execute → Reflect | Planner, Executor, Reflector, Memory |
+
+## LLM Provider 配置模板
+
+```yaml
+# OpenAI
+provider: openai
+model: gpt-4o
+api_key: ${OPENAI_API_KEY}
+base_url: https://api.openai.com/v1              # 可选自定义
+
+# Azure OpenAI
+provider: azure_openai
+model: gpt-4o
+api_key: ${AZURE_OPENAI_API_KEY}
+azure_endpoint: ${AZURE_OPENAI_ENDPOINT}
+api_version: "2024-10-21"
+
+# Anthropic
+provider: anthropic
+model: claude-sonnet-4-20250514
+api_key: ${ANTHROPIC_API_KEY}
+
+# 通义千问
+provider: dashscope
+model: qwen-max
+api_key: ${DASHSCOPE_API_KEY}
+
+# DeepSeek
+provider: deepseek
+model: deepseek-chat
+api_key: ${DEEPSEEK_API_KEY}
+base_url: https://api.deepseek.com
+
+# 本地模型 (Ollama)
+provider: ollama
+model: llama3.1:8b
+base_url: http://localhost:11434
+```
+
+## 向量存储选型指南
+
+| 向量存储 | 适用规模 | 部署方式 | 特点 |
+|---------|---------|---------|------|
+| FAISS | 小/中 | 内嵌（无服务器） | 快速原型，无持久化 |
+| Chroma | 小/中 | 内嵌或独立服务 | 简单易用，适合入门 |
+| Milvus | 中/大 | 需独立部署 | 分布式，生产级别 |
+| Weaviate | 中/大 | 需独立部署 | GraphQL API，多模态 |
+| Qdrant | 中/大 | 需独立部署 | Rust 实现，高性能 |
+| pgvector | 小/中 | PostgreSQL 扩展 | 复用已有 PG 实例 |
+
+## .gitignore 模板
+
+```gitignore
+# Environment
+.env
+.env.local
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Go
+/vendor/
+
+# Node
+node_modules/
+dist/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Data
+data/*.pdf
+data/*.db
+*.faiss
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+## 状态符号约定
+
+| 符号 | 含义 |
+|------|------|
+| ✅ | 已完成并确认 |
+| ⏳ | 进行中 |
+| 🔲 | 未开始 |
+| ❌ | 失败 |
+| ⏭️ | 已跳过 |
+| ⚠️ | 需关注 |

package/skills/agent-eval/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: agent-eval
+description: Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics
+origin: ECC
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Agent Eval Skill
+
+A lightweight CLI tool for comparing coding agents head-to-head on reproducible tasks. Every "which coding agent is best?" comparison runs on vibes — this tool systematizes it.
+
+## When to Activate
+
+- Comparing coding agents (Claude Code, Aider, Codex, etc.) on your own codebase
+- Measuring agent performance before adopting a new tool or model
+- Running regression checks when an agent updates its model or tooling
+- Producing data-backed agent selection decisions for a team
+
+## Installation
+
+> **Note:** Install agent-eval from its repository after reviewing the source.
+
+## Core Concepts
+
+### YAML Task Definitions
+
+Define tasks declaratively. Each task specifies what to do, which files to touch, and how to judge success:
+
+```yaml
+name: add-retry-logic
+description: Add exponential backoff retry to the HTTP client
+repo: ./my-project
+files:
+  - src/http_client.py
+prompt: |
+  Add retry logic with exponential backoff to all HTTP requests.
+  Max 3 retries. Initial delay 1s, max delay 30s.
+judge:
+  - type: pytest
+    command: pytest tests/test_http_client.py -v
+  - type: grep
+    pattern: "exponential_backoff|retry"
+    files: src/http_client.py
+commit: "abc1234"  # pin to specific commit for reproducibility
+```
+
+### Git Worktree Isolation
+
+Each agent run gets its own git worktree — no Docker required. This provides reproducibility isolation so agents cannot interfere with each other or corrupt the base repo.
+
+### Metrics Collected
+
+| Metric | What It Measures |
+|--------|-----------------|
+| Pass rate | Did the agent produce code that passes the judge? |
+| Cost | API spend per task (when available) |
+| Time | Wall-clock seconds to completion |
+| Consistency | Pass rate across repeated runs (e.g., 3/3 = 100%) |
+
+## Workflow
+
+### 1. Define Tasks
+
+Create a `tasks/` directory with YAML files, one per task:
+
+```bash
+mkdir tasks
+# Write task definitions (see template above)
+```
+
+### 2. Run Agents
+
+Execute agents against your tasks:
+
+```bash
+agent-eval run --task tasks/add-retry-logic.yaml --agent claude-code --agent aider --runs 3
+```
+
+Each run:
+1. Creates a fresh git worktree from the specified commit
+2. Hands the prompt to the agent
+3. Runs the judge criteria
+4. Records pass/fail, cost, and time
+
+### 3. Compare Results
+
+Generate a comparison report:
+
+```bash
+agent-eval report --format table
+```
+
+```
+Task: add-retry-logic (3 runs each)
+┌──────────────┬───────────┬────────┬────────┬─────────────┐
+│ Agent        │ Pass Rate │ Cost   │ Time   │ Consistency │
+├──────────────┼───────────┼────────┼────────┼─────────────┤
+│ claude-code  │ 3/3       │ $0.12  │ 45s    │ 100%        │
+│ aider        │ 2/3       │ $0.08  │ 38s    │  67%        │
+└──────────────┴───────────┴────────┴────────┴─────────────┘
+```
+
+## Judge Types
+
+### Code-Based (deterministic)
+
+```yaml
+judge:
+  - type: pytest
+    command: pytest tests/ -v
+  - type: command
+    command: npm run build
+```
+
+### Pattern-Based
+
+```yaml
+judge:
+  - type: grep
+    pattern: "class.*Retry"
+    files: src/**/*.py
+```
+
+### Model-Based (LLM-as-judge)
+
+```yaml
+judge:
+  - type: llm
+    prompt: |
+      Does this implementation correctly handle exponential backoff?
+      Check for: max retries, increasing delays, jitter.
+```
+
+## Best Practices
+
+- **Start with 3-5 tasks** that represent your real workload, not toy examples
+- **Run at least 3 trials** per agent to capture variance — agents are non-deterministic
+- **Pin the commit** in your task YAML so results are reproducible across days/weeks
+- **Include at least one deterministic judge** (tests, build) per task — LLM judges add noise
+- **Track cost alongside pass rate** — a 95% agent at 10x the cost may not be the right choice
+- **Version your task definitions** — they are test fixtures, treat them as code
+
+## Links
+
+- Repository: [github.com/joaquinhuigomez/agent-eval](https://github.com/joaquinhuigomez/agent-eval)

package/skills/agent-harness-construction/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: agent-harness-construction
+description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
+origin: ECC
+---
+
+# Agent Harness Construction
+
+Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.
+
+## Core Model
+
+Agent output quality is constrained by:
+1. Action space quality
+2. Observation quality
+3. Recovery quality
+4. Context budget quality
+
+## Action Space Design
+
+1. Use stable, explicit tool names.
+2. Keep inputs schema-first and narrow.
+3. Return deterministic output shapes.
+4. Avoid catch-all tools unless isolation is impossible.
+
+## Granularity Rules
+
+- Use micro-tools for high-risk operations (deploy, migration, permissions).
+- Use medium tools for common edit/read/search loops.
+- Use macro-tools only when round-trip overhead is the dominant cost.
+
+## Observation Design
+
+Every tool response should include:
+- `status`: success|warning|error
+- `summary`: one-line result
+- `next_actions`: actionable follow-ups
+- `artifacts`: file paths / IDs
+
+## Error Recovery Contract
+
+For every error path, include:
+- root cause hint
+- safe retry instruction
+- explicit stop condition
+
+## Context Budgeting
+
+1. Keep system prompt minimal and invariant.
+2. Move large guidance into skills loaded on demand.
+3. Prefer references to files over inlining long documents.
+4. Compact at phase boundaries, not arbitrary token thresholds.
+
+## Architecture Pattern Guidance
+
+- ReAct: best for exploratory tasks with uncertain path.
+- Function-calling: best for structured deterministic flows.
+- Hybrid (recommended): ReAct planning + typed tool execution.
+
+## Benchmarking
+
+Track:
+- completion rate
+- retries per task
+- pass@1 and pass@3
+- cost per successful task
+
+## Anti-Patterns
+
+- Too many tools with overlapping semantics.
+- Opaque tool output with no recovery hints.
+- Error-only output without next steps.
+- Context overloading with irrelevant references.