Refactor agent configurations and context gathering processes across multiple workflow tools

- Removed agent references in context-gather and test-context-gather commands for clarity. - Updated test-task-generate to streamline agent configuration references. - Enhanced action-planning-agent documentation by removing redundant examples. - Adjusted execute command to eliminate direct agent path references. - Improved context-gather documentation to clarify agent autonomy and project.json integration. - Revised test-context-gather to focus on agent delegation and coverage analysis. - Cleaned up test-task-generate to focus on task generation rules without direct agent references. - Implemented automatic agent assignment based on exploration file names in deep analysis phase. - Expanded project exploration phase to include intelligent angle selection based on software type. - Enhanced output schemas and success criteria for exploration tasks to ensure clarity and completeness.
2026-02-13 02:41:50 +08:00 · 2025-12-26 16:20:46 +08:00
parent a5ba7c0f6c
commit c8a914aeca
15 changed files with 751 additions and 106 deletions
--- a/.claude/skills/copyright-docs/phases/01.5-project-exploration.md
+++ b/.claude/skills/copyright-docs/phases/01.5-project-exploration.md
@@ -0,0 +1,150 @@
+# Phase 1.5: Project Exploration
+
+基于元数据，启动并行探索 Agent 收集代码信息。
+
+## Execution
+
+### Step 1: Intelligent Angle Selection
+
+```javascript
+// 根据软件类型选择探索角度
+const ANGLE_PRESETS = {
+  'CLI': ['architecture', 'commands', 'algorithms', 'exceptions'],
+  'API': ['architecture', 'endpoints', 'data-structures', 'interfaces'],
+  'SDK': ['architecture', 'interfaces', 'data-structures', 'algorithms'],
+  'DataProcessing': ['architecture', 'algorithms', 'data-structures', 'dataflow'],
+  'Automation': ['architecture', 'algorithms', 'exceptions', 'dataflow']
+};
+
+// 从 metadata.category 映射到预设
+function getCategoryKey(category) {
+  if (category.includes('CLI') || category.includes('命令行')) return 'CLI';
+  if (category.includes('API') || category.includes('后端')) return 'API';
+  if (category.includes('SDK') || category.includes('库')) return 'SDK';
+  if (category.includes('数据处理')) return 'DataProcessing';
+  if (category.includes('自动化')) return 'Automation';
+  return 'API'; // default
+}
+
+const categoryKey = getCategoryKey(metadata.category);
+const selectedAngles = ANGLE_PRESETS[categoryKey];
+
+console.log(`
+## Exploration Plan
+
+Software: ${metadata.software_name}
+Category: ${metadata.category} → ${categoryKey}
+Selected Angles: ${selectedAngles.join(', ')}
+
+Launching ${selectedAngles.length} parallel explorations...
+`);
+```
+
+### Step 2: Launch Parallel Agents (Direct Output)
+
+**⚠️ CRITICAL**: Agents write output files directly.
+
+```javascript
+const explorationTasks = selectedAngles.map((angle, index) =>
+  Task({
+    subagent_type: "cli-explore-agent",
+    run_in_background: false,
+    description: `Explore: ${angle}`,
+    prompt: `
+## Exploration Objective
+为 CPCC 软著申请文档执行 **${angle}** 探索。
+
+## Assigned Context
+- **Exploration Angle**: ${angle}
+- **Software Name**: ${metadata.software_name}
+- **Scope Path**: ${metadata.scope_path}
+- **Category**: ${metadata.category}
+- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
+- **Output File**: ${sessionFolder}/exploration-${angle}.json
+
+## MANDATORY FIRST STEPS
+1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
+2. Run: rg -l "{relevant_keyword}" --type ts (locate relevant files)
+3. Analyze from ${angle} perspective
+
+## Exploration Strategy (${angle} focus)
+
+**Step 1: Structural Scan**
+- 识别与 ${angle} 相关的模块和文件
+- 分析导入/导出关系
+
+**Step 2: Pattern Recognition**
+- ${angle} 相关的设计模式
+- 代码组织方式
+
+**Step 3: Write Output**
+- 输出 JSON 到指定路径
+
+## Expected Output Schema
+
+**File**: ${sessionFolder}/exploration-${angle}.json
+
+\`\`\`json
+{
+  "angle": "${angle}",
+  "findings": {
+    "structure": [
+      { "component": "...", "type": "module|layer|service", "path": "...", "description": "..." }
+    ],
+    "patterns": [
+      { "name": "...", "usage": "...", "files": ["path1", "path2"] }
+    ],
+    "key_files": [
+      { "path": "src/file.ts", "relevance": 0.85, "rationale": "Core ${angle} logic" }
+    ]
+  },
+  "insights": [
+    { "observation": "...", "cpcc_section": "2|3|4|5|6|7", "recommendation": "..." }
+  ],
+  "_metadata": {
+    "exploration_angle": "${angle}",
+    "exploration_index": ${index + 1},
+    "software_name": "${metadata.software_name}",
+    "timestamp": "ISO8601"
+  }
+}
+\`\`\`
+
+## Success Criteria
+- [ ] get_modules_by_depth 执行完成
+- [ ] 至少识别 3 个相关文件
+- [ ] patterns 包含具体代码示例
+- [ ] insights 关联到 CPCC 章节 (2-7)
+- [ ] JSON 输出到指定路径
+- [ ] Return: 2-3 句话总结 ${angle} 发现
+`
+  })
+);
+
+// Execute all exploration tasks in parallel
+```
+
+## Output
+
+Session folder structure after exploration:
+
+```
+${sessionFolder}/
+├── exploration-architecture.json
+├── exploration-{angle2}.json
+├── exploration-{angle3}.json
+└── exploration-{angle4}.json
+```
+
+## Downstream Usage (Phase 2 Analysis Input)
+
+Phase 2 agents read exploration files as context:
+
+```javascript
+// Discover exploration files by known angle pattern
+const explorationData = {};
+selectedAngles.forEach(angle => {
+  const filePath = `${sessionFolder}/exploration-${angle}.json`;
+  explorationData[angle] = JSON.parse(Read(filePath));
+});
+```
--- a/.claude/skills/copyright-docs/phases/02-deep-analysis.md
+++ b/.claude/skills/copyright-docs/phases/02-deep-analysis.md
@@ -5,15 +5,161 @@
 > **模板参考**: [../templates/agent-base.md](../templates/agent-base.md)
 > **规范参考**: [../specs/cpcc-requirements.md](../specs/cpcc-requirements.md)

-## Agent 执行前置条件
+## Exploration → Agent 自动分配

-**每个 Agent 必须首先读取以下规范文件**：
+根据 Phase 1.5 生成的 exploration 文件名自动分配对应的 analysis agent。
+
+### 映射规则

 ```javascript
-// Agent 启动时的第一步操作
-const specs = {
-  cpcc: Read(`${skillRoot}/specs/cpcc-requirements.md`)
+// Exploration 角度 → Agent 映射（基于文件名识别，不读取内容）
+const EXPLORATION_TO_AGENT = {
+  'architecture': 'architecture',
+  'commands': 'functions',      // CLI 命令 → 功能模块
+  'endpoints': 'interfaces',    // API 端点 → 接口设计
+  'algorithms': 'algorithms',
+  'data-structures': 'data_structures',
+  'dataflow': 'data_structures', // 数据流 → 数据结构
+  'interfaces': 'interfaces',
+  'exceptions': 'exceptions'
 };
+
+// 从文件名提取角度
+function extractAngle(filename) {
+  // exploration-architecture.json → architecture
+  const match = filename.match(/exploration-(.+)\.json$/);
+  return match ? match[1] : null;
+}
+
+// 分配 agent
+function assignAgent(explorationFile) {
+  const angle = extractAngle(path.basename(explorationFile));
+  return EXPLORATION_TO_AGENT[angle] || null;
+}
+
+// Agent 配置（用于 buildAgentPrompt）
+const AGENT_CONFIGS = {
+  architecture: {
+    role: '系统架构师，专注于分层设计和模块依赖',
+    section: '2',
+    output: 'section-2-architecture.md',
+    focus: '分层结构、模块依赖、数据流向'
+  },
+  functions: {
+    role: '功能分析师，专注于功能点识别和交互',
+    section: '3',
+    output: 'section-3-functions.md',
+    focus: '功能点枚举、模块分组、入口文件、功能交互'
+  },
+  algorithms: {
+    role: '算法工程师，专注于核心逻辑和复杂度分析',
+    section: '4',
+    output: 'section-4-algorithms.md',
+    focus: '核心算法、流程步骤、复杂度、输入输出'
+  },
+  data_structures: {
+    role: '数据建模师，专注于实体关系和类型定义',
+    section: '5',
+    output: 'section-5-data-structures.md',
+    focus: '实体定义、属性类型、关系映射、枚举'
+  },
+  interfaces: {
+    role: 'API设计师，专注于接口契约和协议',
+    section: '6',
+    output: 'section-6-interfaces.md',
+    focus: 'API端点、参数校验、响应格式、时序'
+  },
+  exceptions: {
+    role: '可靠性工程师，专注于异常处理和恢复策略',
+    section: '7',
+    output: 'section-7-exceptions.md',
+    focus: '异常类型、错误码、处理模式、恢复策略'
+  }
+};
+```
+
+### 自动发现与分配流程
+
+```javascript
+// 1. 发现所有 exploration 文件（仅看文件名）
+const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`)
+  .split('\n')
+  .filter(f => f.trim());
+
+// 2. 按文件名自动分配 agent
+const agentAssignments = explorationFiles.map(file => {
+  const angle = extractAngle(path.basename(file));
+  const agentName = EXPLORATION_TO_AGENT[angle];
+  return {
+    exploration_file: file,
+    angle: angle,
+    agent: agentName,
+    output_file: AGENT_CONFIGS[agentName]?.output
+  };
+}).filter(a => a.agent);
+
+// 3. 补充未被 exploration 覆盖的必需 agent（分配相关 exploration）
+const coveredAgents = new Set(agentAssignments.map(a => a.agent));
+const requiredAgents = ['architecture', 'functions', 'algorithms', 'data_structures', 'interfaces', 'exceptions'];
+const missingAgents = requiredAgents.filter(a => !coveredAgents.has(a));
+
+// 相关性映射：为缺失 agent 分配最相关的 exploration
+const RELATED_EXPLORATIONS = {
+  architecture: ['architecture', 'dataflow', 'interfaces'],
+  functions: ['commands', 'endpoints', 'architecture'],
+  algorithms: ['algorithms', 'dataflow', 'architecture'],
+  data_structures: ['data-structures', 'dataflow', 'architecture'],
+  interfaces: ['interfaces', 'endpoints', 'architecture'],
+  exceptions: ['exceptions', 'algorithms', 'architecture']
+};
+
+function findRelatedExploration(agent, availableFiles) {
+  const preferences = RELATED_EXPLORATIONS[agent] || ['architecture'];
+  for (const pref of preferences) {
+    const match = availableFiles.find(f => f.includes(`exploration-${pref}.json`));
+    if (match) return { file: match, angle: pref, isRelated: true };
+  }
+  // 最后兜底：任意 exploration 都比没有强
+  return availableFiles.length > 0
+    ? { file: availableFiles[0], angle: extractAngle(path.basename(availableFiles[0])), isRelated: true }
+    : { file: null, angle: null, isRelated: false };
+}
+
+missingAgents.forEach(agent => {
+  const related = findRelatedExploration(agent, explorationFiles);
+  agentAssignments.push({
+    exploration_file: related.file,
+    angle: related.angle,
+    agent: agent,
+    output_file: AGENT_CONFIGS[agent].output,
+    is_related: related.isRelated  // 标记为相关而非直接匹配
+  });
+});
+
+console.log(`
+## Agent Auto-Assignment
+
+Found ${explorationFiles.length} exploration files:
+${agentAssignments.map(a => {
+  if (!a.exploration_file) return `- ${a.agent} agent (no exploration)`;
+  if (a.is_related) return `- ${a.agent} agent ← ${a.angle} (related)`;
+  return `- ${a.agent} agent ← ${a.angle} (direct)`;
+}).join('\n')}
+`);
+```
+
+---
+
+## Agent 执行前置条件
+
+**每个 Agent 接收 exploration 文件路径，自行读取内容**：
+
+```javascript
+// Agent prompt 中包含文件路径
+// Agent 启动后的操作顺序：
+// 1. Read exploration 文件（如有）
+// 2. Read CPCC 规范文件
+// 3. 执行分析任务
 ```

 规范文件路径（相对于 skill 根目录）：
@@ -47,26 +193,90 @@ const specs = {
 ## 执行流程

 ```javascript
-// 1. 准备目录
+// 1. 发现 exploration 文件并自动分配 agent
+const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`)
+  .split('\n')
+  .filter(f => f.trim());
+
+const agentAssignments = explorationFiles.map(file => {
+  const angle = extractAngle(path.basename(file));
+  const agentName = EXPLORATION_TO_AGENT[angle];
+  return { exploration_file: file, angle, agent: agentName };
+}).filter(a => a.agent);
+
+// 补充必需 agent
+const coveredAgents = new Set(agentAssignments.map(a => a.agent));
+const requiredAgents = ['architecture', 'functions', 'algorithms', 'data_structures', 'interfaces', 'exceptions'];
+requiredAgents.filter(a => !coveredAgents.has(a)).forEach(agent => {
+  agentAssignments.push({ exploration_file: null, angle: null, agent });
+});
+
+// 2. 准备目录
 Bash(`mkdir -p ${outputDir}/sections`);

-// 2. 并行启动 6 个 Agent
-const results = await Promise.all([
-  launchAgent('architecture', metadata, outputDir),
-  launchAgent('functions', metadata, outputDir),
-  launchAgent('algorithms', metadata, outputDir),
-  launchAgent('data_structures', metadata, outputDir),
-  launchAgent('interfaces', metadata, outputDir),
-  launchAgent('exceptions', metadata, outputDir)
-]);
+// 3. 并行启动所有 Agent（传递 exploration 文件路径）
+const results = await Promise.all(
+  agentAssignments.map(assignment =>
+    Task({
+      subagent_type: "cli-explore-agent",
+      run_in_background: false,
+      description: `Analyze: ${assignment.agent}`,
+      prompt: buildAgentPrompt(assignment, metadata, outputDir)
+    })
+  )
+);

-// 3. 收集返回信息
+// 4. 收集返回信息
 const summaries = results.map(r => JSON.parse(r));

-// 4. 传递给 Phase 2.5
+// 5. 传递给 Phase 2.5
 return { summaries, cross_notes: summaries.flatMap(s => s.cross_module_notes) };
 ```

+### Agent Prompt 构建
+
+```javascript
+function buildAgentPrompt(assignment, metadata, outputDir) {
+  const config = AGENT_CONFIGS[assignment.agent];
+  let contextSection = '';
+
+  if (assignment.exploration_file) {
+    const matchType = assignment.is_related ? '相关' : '直接匹配';
+    contextSection = `[CONTEXT]
+**Exploration 文件**: ${assignment.exploration_file}
+**匹配类型**: ${matchType}
+首先读取此文件获取 ${assignment.angle} 探索结果作为分析上下文。
+${assignment.is_related ? `注意：这是相关探索结果（非直接匹配），请提取与 ${config.focus} 相关的信息。` : ''}
+`;
+  }
+
+  return `
+${contextSection}
+[SPEC]
+读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+
+[ROLE] ${config.role}
+
+[TASK]
+分析 ${metadata.scope_path}，生成 Section ${config.section}。
+输出: ${outputDir}/sections/${config.output}
+
+[CPCC_SPEC]
+- 内容基于代码分析，无臆测
+- 图表编号: 图${config.section}-1, 图${config.section}-2...
+- 每个子章节 ≥100字
+- 包含文件路径引用
+
+[FOCUS]
+${config.focus}
+
+[RETURN JSON]
+{"status":"completed","output_file":"${config.output}","summary":"<50字>","cross_module_notes":[],"stats":{}}
+`;
+}
+```
+
 ---

 ## Agent 提示词