@colin4k1024/tsp 2.4.0

package/skills/agent-dev-workshop/references/phase2-architecture.md

@@ -0,0 +1,146 @@
+# Phase 2: 架构设计（Architecture）引导细则
+
+## 入口条件
+
+- Phase 1 的 `agent-spec.md` 已确认
+- 已知 Agent 类型和框架选型
+
+## 活动流程
+
+### Step 1: 加载架构模式
+
+读取 `agent-patterns-catalog` Skill 中对应 Agent 类型的 reference 文件：
+
+| Agent 类型 | Reference 文件 |
+|-----------|---------------|
+| ReAct | `agent-patterns-catalog/references/react-agent.md` |
+| Multi-Agent Conversation | `agent-patterns-catalog/references/multi-agent-conversation.md` |
+| Multi-Agent Workflow | `agent-patterns-catalog/references/multi-agent-workflow.md` |
+| RAG Agent | `agent-patterns-catalog/references/rag-agent.md` |
+| Tool-Use Agent | `agent-patterns-catalog/references/tool-use-agent.md` |
+| Autonomous Agent | `agent-patterns-catalog/references/autonomous-agent.md` |
+
+混合类型时读多个文件，组合架构。
+
+### Step 2: 组件拓扑设计
+
+根据 spec 确认所需组件：
+
+| 组件 | 何时需要 | 职责 |
+|------|---------|------|
+| Agent Core | 始终 | 主控循环、决策 |
+| LLM Client | 始终 | 调用大模型 |
+| Tool Registry | 有工具时 | 工具注册与分发 |
+| Memory Store | 需要上下文时 | 对话历史 / 实体记忆 |
+| Vector Store | RAG 场景 | 向量检索 |
+| Document Loader | RAG 场景 | 文档解析 |
+| Orchestrator | Multi-Agent | 编排与路由 |
+| State Manager | Workflow | 状态机 / DAG 执行 |
+| Human-in-Loop | 需要审批时 | 人工确认节点 |
+
+### Step 3: 生成 Mermaid 架构图
+
+**单 Agent 模板**:
+```mermaid
+graph TD
+    User[用户] --> Agent[Agent Core]
+    Agent --> LLM[LLM Client]
+    Agent --> Tools[Tool Registry]
+    Tools --> T1[Tool 1]
+    Tools --> T2[Tool 2]
+    Agent --> Memory[Memory Store]
+```
+
+**Multi-Agent 模板**:
+```mermaid
+graph TD
+    User[用户] --> Orchestrator
+    Orchestrator --> Agent1[Agent: Role 1]
+    Orchestrator --> Agent2[Agent: Role 2]
+    Orchestrator --> Agent3[Agent: Role 3]
+    Agent1 --> LLM
+    Agent2 --> LLM
+    Agent3 --> LLM
+    Agent1 --> SharedMemory[Shared Memory]
+    Agent2 --> SharedMemory
+```
+
+**RAG Agent 模板**:
+```mermaid
+graph TD
+    User[用户] --> Agent[Agent Core]
+    Agent --> Retriever[Retrieval Pipeline]
+    Retriever --> VectorStore[(Vector Store)]
+    Retriever --> Reranker[Reranker]
+    Agent --> LLM[LLM Client]
+    Agent --> Memory[Memory Store]
+    DocLoader[Document Loader] --> Chunker --> Embedder --> VectorStore
+```
+
+根据实际需求调整模板，确保图中每个节点都对应 agent-spec 中的需求。
+
+### Step 4: 数据流描述
+
+对每条核心路径，描述数据如何流转：
+
+```
+1. 用户输入 → Agent Core
+2. Agent Core 决定调用 Tool A → 传入参数 {param}
+3. Tool A 返回结果 → Agent Core
+4. Agent Core 组合结果 → 调用 LLM 生成 Response
+5. Response → 存入 Memory → 返回用户
+```
+
+### Step 5: 设计决策记录
+
+每个关键设计决策需要结构化记录：
+
+| 决策 | 选项 A | 选项 B | 选择 | 理由 |
+|------|--------|--------|------|------|
+| 通信模式 | 同步 | 异步消息 | 同步 | 简单场景，无需消息队列 |
+| Memory 类型 | Buffer | Entity | Buffer | 对话短，无实体提取需求 |
+
+### Step 6: Multi-Agent 角色定义（如适用）
+
+| 角色名 | 职责 | 可用工具 | 特殊约束 |
+|--------|------|----------|----------|
+| Planner | 任务分解 | 无 | 只输出 JSON plan |
+| Executor | 执行子任务 | 全部 | 需要用户审批危险操作 |
+| Reviewer | 检查结果 | 无 | 必须给出评分 |
+
+## agent-architecture.md 输出模板
+
+```markdown
+# Agent Architecture
+
+## 架构模式
+
+- 模式名称: {pattern_name}
+- 基础描述: {description}
+
+## 组件拓扑
+
+{mermaid_diagram}
+
+## 组件职责
+
+| 组件 | 职责 | 技术选型 |
+|------|------|----------|
+| {component} | {responsibility} | {technology} |
+
+## 核心数据流
+
+{data_flow_description}
+
+## Multi-Agent 角色定义
+
+{role_table}（如适用）
+
+## 设计决策
+
+{decision_table}
+```
+
+## 确认点
+
+展示 agent-architecture.md 的完整内容（包括 Mermaid 图），请用户确认或提出调整意见。如有调整，修改后再次确认。

package/skills/agent-dev-workshop/references/phase3-tools.md

@@ -0,0 +1,174 @@
+# Phase 3: 工具与能力定义（Tools & Capabilities）引导细则
+
+## 入口条件
+
+- Phase 2 的 `agent-architecture.md` 已确认
+- 已知组件拓扑和 Agent 角色
+
+## 工具定义流程
+
+### Step 1: 工具清单推导
+
+从 agent-spec.md 和 agent-architecture.md 中提取所有需要的工具：
+
+1. 分析 Agent 核心能力 → 每个能力拆分为 1-N 个工具
+2. 分析外部依赖 → 每个依赖封装为 1 个工具
+3. Multi-Agent 场景 → 按角色列出各自的工具
+
+示例推导：
+| 核心能力 | 推导出的工具 |
+|---------|------------|
+| "能搜索网页" | `web_search(query: str) → results: list` |
+| "能读写数据库" | `db_query(sql: str)`, `db_write(table, data)` |
+| "能发送邮件" | `send_email(to, subject, body)` |
+
+### Step 2: 逐工具交互确认
+
+对每个工具，展示以下结构并让用户确认：
+
+```yaml
+- name: web_search
+  description: "搜索网页并返回摘要结果"
+  parameters:
+    - name: query
+      type: string
+      required: true
+      description: "搜索关键词"
+    - name: max_results
+      type: integer
+      required: false
+      default: 5
+      description: "最大返回结果数"
+  returns:
+    type: array
+    items:
+      title: string
+      url: string
+      snippet: string
+  implementation:
+    strategy: api_call          # api_call / db_query / file_op / custom_logic / external_service
+    endpoint: "https://api.example.com/search"
+    auth: api_key
+  error_handling:
+    timeout: 10s
+    retry: 2
+    fallback: "返回空结果列表"
+```
+
+**交互规则**:
+- 每次展示 1 个工具定义，等用户说"确认"或给出修改意见
+- 用户可以随时添加额外的工具
+- 用户可以合并或拆分工具
+
+### Step 3: Memory 策略定义
+
+根据 Agent 类型展示 Memory 选项：
+
+| Memory 类型 | 适用场景 | 配置项 |
+|------------|---------|--------|
+| `conversation_buffer` | 短对话，直接保留全部 | `max_messages: 50` |
+| `conversation_window` | 中等对话，滑动窗口 | `window_size: 20` |
+| `conversation_summary` | 长对话，自动摘要 | `summary_model: gpt-4o-mini` |
+| `entity_memory` | 需要跟踪实体状态 | `entity_types: [user, task]` |
+| `vector_memory` | 大规模历史上下文召回 | `embedding_model, top_k` |
+
+推荐组合：
+- 简单对话 Agent → `conversation_buffer`
+- 客服 Agent → `conversation_window` + `entity_memory`
+- 知识问答 → `conversation_buffer` + `vector_memory`
+
+### Step 4: RAG Pipeline 定义（如适用）
+
+如果 Agent 包含 RAG 能力，逐步配置：
+
+**4a. 数据源**:
+```yaml
+data_sources:
+  - type: file           # file / api / database / url
+    path: "./docs/"
+    formats: [pdf, md, txt]
+  - type: api
+    endpoint: "https://..."
+    auth: bearer_token
+```
+
+**4b. 文档处理**:
+```yaml
+processing:
+  chunking:
+    strategy: recursive    # recursive / character / token / semantic
+    chunk_size: 1000
+    chunk_overlap: 200
+    separators: ["\n\n", "\n", " "]
+  metadata:
+    extract: [title, source, date]
+```
+
+**4c. Embedding**:
+```yaml
+embedding:
+  model: text-embedding-3-small   # text-embedding-3-small / text-embedding-ada-002 / bge-large-zh
+  dimensions: 1536
+  batch_size: 100
+```
+
+**4d. 向量存储**:
+```yaml
+vector_store:
+  backend: chroma          # faiss / chroma / milvus / weaviate / qdrant / pgvector
+  collection: "{agent_name}_knowledge"
+  distance_metric: cosine
+```
+
+**4e. 检索策略**:
+```yaml
+retrieval:
+  strategy: hybrid         # similarity / mmr / hybrid
+  top_k: 5
+  score_threshold: 0.7
+  reranker:                # 可选
+    model: bge-reranker-large
+    top_n: 3
+```
+
+## agent-tools.md 输出模板
+
+```markdown
+# Agent Tools & Capabilities
+
+## 工具清单
+
+| # | 名称 | 描述 | 输入 | 输出 | 实现策略 |
+|---|------|------|------|------|----------|
+| 1 | {name} | {desc} | {input} | {output} | {strategy} |
+
+## 工具详细定义
+
+### Tool 1: {name}
+
+\`\`\`yaml
+{complete_tool_definition}
+\`\`\`
+
+## Memory 配置
+
+| 配置项 | 值 |
+|--------|-----|
+| 类型 | {type} |
+| 存储后端 | {backend} |
+| 窗口大小 | {window} |
+
+## RAG Pipeline（如适用）
+
+{rag_pipeline_config}
+
+## 外部依赖清单
+
+| 依赖 | 类型 | 用途 | 认证方式 |
+|------|------|------|----------|
+| {dep} | {type} | {purpose} | {auth} |
+```
+
+## 确认点
+
+全部工具定义逐个确认后，展示完整 agent-tools.md，再次整体确认。

package/skills/agent-dev-workshop/references/phase4-prompts.md

@@ -0,0 +1,269 @@
+# Phase 4: Prompt 与编排设计（Prompt & Orchestration）引导细则
+
+## 入口条件
+
+- Phase 3 的 `agent-tools.md` 已确认
+- 已知全部工具、Memory 和 RAG 配置
+
+## System Prompt 设计
+
+### Step 1: 角色与人格
+
+根据 agent-spec 中的描述构建 System Prompt 的角色部分：
+
+```
+你是 {agent_name}，一个 {agent_description}。
+
+## 你的核心职责
+{responsibilities_from_spec}
+
+## 你的行为准则
+- {rule_1}
+- {rule_2}
+```
+
+**引导问题**:
+- Agent 应该用什么语气？（专业 / 友好 / 简洁 / 详尽）
+- Agent 是否需要拒绝某些类型的请求？
+- Agent 是否需要在特定条件下升级给人类？
+
+### Step 2: 工具使用指令
+
+自动根据 agent-tools.md 生成工具使用部分：
+
+```
+## 可用工具
+
+你可以使用以下工具来完成任务：
+
+### {tool_name}
+- 描述: {tool_description}
+- 何时使用: {when_to_use}
+- 输入: {input_schema}
+- 注意: {caveats}
+```
+
+**每个工具需要确认**:
+- "何时使用"的触发条件
+- 工具调用频率限制（如果有）
+- 工具之间的优先级
+
+### Step 3: 输出格式
+
+```
+## 输出要求
+
+- 回复语言: {language}
+- 格式: {format}（纯文本 / Markdown / JSON / 结构化）
+- 引用来源: {citation_style}（如 RAG Agent）
+- 不确定时: {uncertainty_handling}
+```
+
+### Step 4: Few-shot Examples（可选）
+
+```
+## 示例
+
+### 示例 1: {scenario}
+用户: {user_input}
+思考: {thinking_process}
+行动: {tool_calls}
+回复: {response}
+```
+
+是否需要 few-shot examples 取决于：
+- 输出格式是否非标准
+- 工具调用逻辑是否复杂
+- 用户是否提供了样例对话
+
+## 编排逻辑设计
+
+### 单 Agent 编排
+
+```yaml
+orchestration:
+  type: single_agent
+  execution:
+    max_iterations: 10
+    timeout: 120s
+    termination:
+      - condition: "agent 返回 FINAL_ANSWER"
+      - condition: "达到 max_iterations"
+        action: "返回当前最佳结果 + 说明未完成"
+  error_handling:
+    tool_error: "报告错误，尝试替代方案"
+    llm_error: "重试 2 次，然后返回友好错误信息"
+    timeout: "返回已完成的部分结果"
+```
+
+### Multi-Agent Conversation 编排
+
+```yaml
+orchestration:
+  type: multi_agent_conversation
+  agents:
+    - role: {role_1}
+      prompt: "{system_prompt_1}"
+      tools: [{tool_list}]
+    - role: {role_2}
+      prompt: "{system_prompt_2}"
+      tools: [{tool_list}]
+  routing:
+    strategy: llm_based      # round_robin / llm_based / rule_based / function_based
+    router_prompt: "根据当前对话状态，选择下一个应该发言的角色..."
+    max_rounds: 20
+  termination:
+    - condition: "所有角色达成一致"
+    - condition: "达到 max_rounds"
+  shared_state:
+    type: conversation_history
+    visible_to: all
+```
+
+### Multi-Agent Workflow 编排
+
+```yaml
+orchestration:
+  type: multi_agent_workflow
+  stages:
+    - name: "research"
+      agent: researcher
+      input: "{user_query}"
+      output: "research_results"
+    - name: "analyze"
+      agent: analyst
+      input: "{research_results}"
+      output: "analysis"
+      parallel: false
+    - name: "review"
+      agent: reviewer
+      input: "{analysis}"
+      output: "review_result"
+      gate:                    # 可选：门控
+        condition: "review_result.score >= 7"
+        on_fail: "回到 analyze 阶段"
+    - name: "synthesize"
+      agent: synthesizer
+      input: ["{research_results}", "{analysis}", "{review_result}"]
+      output: "final_result"
+  error_handling:
+    stage_timeout: 60s
+    stage_retry: 1
+    pipeline_timeout: 300s
+```
+
+### Autonomous Agent 编排
+
+```yaml
+orchestration:
+  type: autonomous
+  plan_phase:
+    prompt: "将以下任务分解为子任务列表..."
+    output_format: json_plan
+    max_subtasks: 10
+  execute_phase:
+    per_subtask_timeout: 60s
+    parallel_execution: false    # 是否并行执行子任务
+  reflect_phase:
+    prompt: "评估以下执行结果是否满足目标..."
+    replan_threshold: "score < 0.7"
+    max_replans: 3
+  human_in_loop:
+    enabled: false
+    trigger: "风险操作或 confidence < 0.5 时"
+```
+
+## Mermaid 流程图
+
+为编排逻辑生成 Mermaid 流程图：
+
+**Conversation 模式**:
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant O as Orchestrator
+    participant A1 as Agent: Role 1
+    participant A2 as Agent: Role 2
+    U->>O: 输入
+    O->>A1: 分派
+    A1->>O: 回复
+    O->>A2: 分派
+    A2->>O: 回复
+    O->>U: 最终结果
+```
+
+**Workflow 模式**:
+```mermaid
+graph LR
+    Input --> Stage1[Research]
+    Stage1 --> Stage2[Analyze]
+    Stage2 --> Gate{Score >= 7?}
+    Gate -->|Yes| Stage3[Synthesize]
+    Gate -->|No| Stage2
+    Stage3 --> Output
+```
+
+## 输出文件
+
+### agent-prompts.md
+
+```markdown
+# Agent Prompts
+
+## System Prompt
+
+\`\`\`
+{complete_system_prompt}
+\`\`\`
+
+## Few-shot Examples
+
+{examples_if_any}
+
+## Multi-Agent Prompts（如适用）
+
+### Role: {role_name}
+\`\`\`
+{role_system_prompt}
+\`\`\`
+```
+
+### agent-orchestration.md
+
+```markdown
+# Agent Orchestration
+
+## 编排模式
+
+- 类型: {orchestration_type}
+- 最大循环次数: {max_iterations}
+- 超时时间: {timeout}
+
+## 编排逻辑
+
+{orchestration_config_yaml}
+
+## 流程图
+
+{mermaid_diagram}
+
+## 路由策略（如适用）
+
+{routing_config}
+
+## 错误处理
+
+| 错误类型 | 处理策略 |
+|---------|---------|
+| 工具调用失败 | {strategy} |
+| LLM 调用失败 | {strategy} |
+| 超时 | {strategy} |
+
+## 终止条件
+
+{termination_conditions}
+```
+
+## 确认点
+
+分别展示 agent-prompts.md 和 agent-orchestration.md，逐个确认。Prompt 文本需要特别仔细的审批。