1{
2 "task": "全面的代码库分析",
3 "objective": "对整个代码库进行详尽分析，以识别、优先排序、修复并记录任何技术栈中所有可验证的错误、安全漏洞和关键问题",
4 "analysis_phases": [
5 {
6 "phase": 1,
7 "name": "代码库发现与映射",
8 "steps": [
9 {
10 "step": "1.1",
11 "title": "架构与结构分析",
12 "actions": [
13 "映射完整的目录结构（src/、lib/、tests/、docs/、config/、scripts/、build/、deploy/）",
14 "识别所有正在使用的技术栈和框架",
15 "解析依赖清单（package.json、requirements.txt、go.mod、pom.xml、Gemfile、Cargo.toml、composer.json）",
16 "记录入口点、主要执行路径和模块边界",
17 "分析构建系统（Webpack、Gradle、Maven、Make、CMake）",
18 "审查CI/CD配置（GitHub Actions、GitLab CI、Jenkins、CircleCI）",
19 "检查现有文档（README、CONTRIBUTING、API规范、架构图）"
20 ]
21 },
22 {
23 "step": "1.2",
24 "title": "开发环境清单",
25 "actions": [
26 "识别测试框架（Jest、Mocha、pytest、PHPUnit、Go test、JUnit、RSpec、xUnit）",
27 "审查linter/formatter配置（ESLint、Prettier、Black、Flake8、RuboCop、golangci-lint、Checkstyle）",
28 "扫描内联问题标记（TODO、FIXME、HACK、XXX、BUG、NOTE）",
29 "分析git历史中的问题模式和最近的紧急修复",
30 "提取现有测试覆盖率报告和指标",
31 "识别已使用的代码分析工具（SonarQube、CodeClimate等）"
32 ]
33 }
34 ]
35 },
36 {
37 "phase": 2,
38 "name": "系统性错误发现",
39 "bug_categories": [
40 {
41 "category": "严重",
42 "severity": "P0",
43 "types": [
44 "SQL注入漏洞",
45 "跨站脚本（XSS）缺陷",
46 "跨站请求伪造（CSRF）漏洞",
47 "认证/授权绕过",
48 "远程代码执行（RCE）风险",
49 "数据损坏或永久数据丢失",
50 "系统崩溃、死锁或无限循环",
51 "内存泄漏和资源耗尽",
52 "不安全的加密实现",
53 "硬编码的机密或凭据"
54 ]
55 },
56 {
57 "category": "功能性",
58 "severity": "P1-P2",
59 "types": [
60 "逻辑错误（错误的条件判断、错误的计算、差一错误）",
61 "状态管理问题（竞态条件、过期状态、不当变更）",
62 "错误的API契约或请求/响应映射",
63 "缺失或不足的输入验证",
64 "损坏的业务逻辑或工作流违规",
65 "错误的数据转换或序列化",
66 "类型不匹配或不安全的类型强制转换",
67 "错误的异常处理或错误传播"
68 ]
69 },
70 {
71 "category": "集成",
72 "severity": "P2",
73 "types": [
74 "错误的外部API使用或过时的端点",
75 "数据库查询错误、SQL语法问题或N+1问题",
76 "消息队列处理失败（RabbitMQ、Kafka、SQS）",
77 "文件系统操作错误（权限、路径遍历）",
78 "网络通信问题（超时、重试、连接池）",
79 "缓存不一致或失效问题",
80 "第三方库误用或版本不兼容"
81 ]
82 },
83 {
84 "category": "边缘情况",
85 "severity": "P2-P3",
86 "types": [
87 "空/未定义/nil/None指针解引用",
88 "空数组/列表/集合处理",
89 "零值或负值边缘情况",
90 "边界条件（最大/最小整数、字符串长度限制）",
91 "缺失的错误处理或被吞掉的异常",
92 "超时和重试逻辑失败",
93 "没有适当锁定的并发访问问题",
94 "数值运算中的溢出/下溢"
95 ]
96 },
97 {
98 "category": "代码质量",
99 "severity": "P3-P4",
100 "types": [
101 "使用已弃用的API",
102 "死代码或不可达代码路径",
103 "循环依赖",
104 "性能瓶颈（低效算法、冗余操作）",
105 "缺失或不正确的类型注解",
106 "不一致的错误处理模式",
107 "资源泄漏（文件句柄、数据库连接、网络套接字）",
108 "不当的日志记录（敏感数据暴露、上下文不足）"
109 ]
110 }
111 ],
112 "discovery_methods": [
113 "使用语言特定工具进行静态代码分析",
114 "针对常见反模式和代码坏味道的模式匹配",
115 "依赖漏洞扫描（npm audit、pip-audit、bundle-audit、cargo audit）",
116 "控制流和数据流分析",
117 "死代码检测",
118 "根据最佳实践验证配置",
119 "文档与实现的交叉验证",
120 "以安全为重点的代码审查"
121 ]
122 },
123 {
124 "phase": 3,
125 "name": "错误记录与优先级排序",
126 "bug_report_schema": {
127 "bug_id": "顺序标识符（BUG-001、BUG-002等）",
128 "severity": {
129 "type": "enum",
130 "values": [
131 "严重",
132 "高",
133 "中",
134 "低"
135 ],
136 "description": "错误严重程度"
137 },
138 "category": {
139 "type": "enum",
140 "values": [
141 "安全",
142 "功能性",
143 "性能",
144 "集成",
145 "代码质量"
146 ],
147 "description": "错误分类"
148 },
149 "location": {
150 "files": [
151 "受影响文件路径及行号的数组"
152 ],
153 "component": "模块/服务/功能名称",
154 "function": "具体函数或方法名称"
155 },
156 "description": {
157 "current_behavior": "什么坏了或错了",
158 "expected_behavior": "应该发生什么",
159 "root_cause": "为什么坏的技术解释"
160 },
161 "impact_assessment": {
162 "user_impact": "对最终用户的影响（数据丢失、安全暴露、用户体验下降）",
163 "system_impact": "对系统的影响（性能、稳定性、可扩展性）",
164 "business_impact": "对业务的影响（合规、收入、声誉、法律）"
165 }
166 }
167 }
168 ]
169} },
170 "reproduction": {
171 "steps": [
172 "重现问题的分步说明"
173 ],
174 "test_data": "所需的示例数据或条件",
175 "actual_result": "重现时发生的情况",
176 "expected_result": "应该发生的情况"
177 },
178 "verification": {
179 "code_snippet": "展示缺陷的演示代码",
180 "test_case": "会因此缺陷而失败的测试",
181 "logs_or_metrics": "来自日志或监控的证据"
182 },
183 "dependencies": {
184 "related_bugs": [
185 "相关 BUG-ID 的数组"
186 ],
187 "blocking_issues": [
188 "必须先修复的缺陷数组"
189 ],
190 "blocked_by": [
191 "阻止修复的外部因素"
192 ]
193 },
194 "metadata": {
195 "discovered_date": "ISO 8601 时间戳",
196 "discovered_by": "使用的工具或方法",
197 "cve_id": "如适用，CVE 标识符",
198 "cwe_id": "如适用，CWE 标识符"
199 }
200 },
201 "prioritization_matrix": {
202 "criteria": [
203 {
204 "factor": "severity",
205 "weight": 0.4,
206 "scale": "CRITICAL=100, HIGH=70, MEDIUM=40, LOW=10"
207 },
208 {
209 "factor": "user_impact",
210 "weight": 0.3,
211 "scale": "All users=100, Many=70, Some=40, Few=10"
212 },
213 {
214 "factor": "fix_complexity",
215 "weight": 0.15,
216 "scale": "Simple=100, Medium=60, Complex=20"
217 },
218 {
219 "factor": "regression_risk",
220 "weight": 0.15,
221 "scale": "Low=100, Medium=60, High=20"
222 }
223 ],
224 "formula": "priority_score = Σ(factor_value × weight)"
225 }
226 },
227 {
228 "phase": 4,
229 "name": "修复实现",
230 "fix_workflow": [
231 {
232 "step": 1,
233 "action": "创建隔离的修复分支",
234 "naming": "fix/BUG-{id}-{short-description}"
235 },
236 {
237 "step": 2,
238 "action": "首先编写失败的测试",
239 "rationale": "测试驱动开发确保修复可验证"
240 },
241 {
242 "step": 3,
243 "action": "实现最小、聚焦的修复",
244 "principle": "正确解决问题的最小变更"
245 },
246 {
247 "step": 4,
248 "action": "验证测试现在通过",
249 "validation": "运行特定测试和相关测试套件"
250 },
251 {
252 "step": 5,
253 "action": "运行完整回归测试套件",
254 "validation": "确保没有现有功能被破坏"
255 },
256 {
257 "step": 6,
258 "action": "更新文档",
259 "scope": "API 文档、内联注释、变更日志"
260 }
261 ],
262 "fix_principles": [
263 "MINIMAL_CHANGE: 做出正确修复问题的最小变更",
264 "NO_SCOPE_CREEP: 避免无关的重构或功能添加",
265 "BACKWARDS_COMPATIBLE: 保留现有 API 契约，除非缺陷本身是破坏性的",
266 "FOLLOW_CONVENTIONS: 遵循项目现有的代码风格和模式",
267 "DEFENSIVE_PROGRAMMING: 添加防护措施以防止未来出现类似缺陷",
268 "EXPLICIT_OVER_IMPLICIT: 通过代码结构和注释使意图清晰",
269 "FAIL_FAST: 尽早验证输入并以清晰的错误消息失败"
270 ],
271 "code_review_checklist": [
272 "修复解决根本原因，而不仅仅是症状",
273 "所有边缘情况都得到妥善处理",
274 "错误消息清晰、可操作，且不暴露敏感信息",
275 "性能影响可接受（在 O(n) 足够时没有 O(n²)）",
276 "彻底考虑安全影响",
277 "没有新的编译器警告或 linting 错误",
278 "变更由测试覆盖",
279 "文档已更新且准确",
280 "破坏性变更已明确标记并说明理由",
281 "依赖项是最新的且安全"
282 ]
283 },
284 {
285 "phase": 5,
286 "name": "测试与验证",
287 "test_requirements": {
288 "mandatory_tests_per_fix": [
289 {
290 "type": "unit_test",
291 "description": "针对特定缺陷修复的隔离测试",
292 "coverage": "必须覆盖被破坏的确切代码路径"
293 },
294 {
295 "type": "integration_test",
296 "description": "如果缺陷涉及多个组件则进行测试",
297 "coverage": "通过受影响系统的端到端流程"
298 },
299 {
300 "type": "regression_test",
301 "description": "确保修复不会破坏现有功能",
302 "coverage": "所有相关功能和代码路径"
303 },
304 {
305 "type": "edge_case_tests",
306 "description": "覆盖边界条件和角落情况",
307 "coverage": "空值、空输入、限制、错误条件"
308 }
309 ]
310 },
311 "test_structure_template": {
312 "description": "语言无关的测试结构",
313 "template": [
314 "describe('BUG-{ID}: {description}', () => {",
315 " test('reproduces original bug', () => {",
316 " // 此测试证明缺陷存在",
317 " // 修复前应失败，修复后应通过",
318 " });",
319 "",
320 " test('verifies fix resolves issue', () => {",
321 " // 此测试证明修复后的正确行为",
322 " });",
323 "",
324 " test('handles edge case: {case}', () => {",
325 " // 相关场景的额外覆盖",
326 " });",
327 "});"
328 ]
329 },
330 "validation_steps": [
331 {
332 "step": "运行完整测试套件",
333 "commands": {
334 "javascript": "npm test",
335 "python": "pytest",
336 "go": "go test ./...",
337 "java": "mvn test",
338 "ruby": "bundle exec rspec",
339 "rust": "cargo test",
340 "php": "phpunit"
341 }
342 },
343 {
344 "step": "测量代码覆盖率",
345 "tools": [
346 "Istanbul/NYC",
347 "Coverage.py",
348 "JaCoCo",
349 "SimpleCov",
350 "Tarpaulin"
351 ]
352 },
353 {
354 "step": "运行静态分析",
355 "tools": [
356 "ESLint",
357 "Pylint",
358 "golangci-lint",
359 "SpotBugs",
360 "Clippy"
361 ]
362 },
363 {
364 "step": "性能基准测试",
365 "condition": "如果修复影响热路径或关键操作"
366 },
367 {
368 "step": "安全扫描",
369 "tools": [
370 "Snyk",
371 "OWASP Dependency-Check",
372 "Trivy",
373 "Bandit"
374 ]
375 }
376 ]
377 },
378 {
379 "phase": 6,
380 "name": "文档与报告",
381 "fix_documentation_requirements": [
382 "更新内联代码注释，解释修复内容以及为何必要",
383 "如果行为发生变化，修订 API 文档",
384 "在 CHANGELOG.md 中添加缺陷修复条目",
385 "创建或更新故障排查指南",
386 "记录任何针对延期/未修复问题的变通方案",
387 "如果修复需要用户操作，添加迁移说明"
388 ],
389 "executive_summary_template": {
390 "title": "缺陷修复报告 - {repository_name}",
391 "metadata": {
392 "date": "ISO 8601 日期",
393 "analyzer": "工具/人员名称",
394 "repository": "完整仓库路径",
395 "commit_hash": "Git 提交 SHA",
396 "duration": "分析时长（小时）"
397 },
398 "overview": {
399 "total_bugs_found": "整数",
400 "total_bugs_fixed": "整数",
401 "bugs_deferred": "整数",
402 "test_coverage_before": "百分比",
403 "test_coverage_after": "百分比",
404 "files_analyzed": "整数",
405 "lines_of_code": "整数"
406 },
407 "critical_findings": [
408 "发现的前 3-5 个最关键缺陷及其修复"
409 ],
410 "fix_summary_by_category": {
411 "security": "数量",
412 "functional": "数量",
413 "performance": "数量",
414 "integration": "数量",
415 "code_quality": "数量"
416 },
417 "detailed_fix_table": {
418 "columns": [
419 "BUG-ID",
420 "File",
421 "Line",
422 "Category",
423 "Severity",
424 "Description",
425 "Status",
426 "Test Added"
427 ],
428 "format": "Markdown 表格或 CSV"
429 },
430 "risk_assessment": {
431 "remaining_high_priority": [
432 "未修复的关键问题列表"
433 ],
434 "recommended_next_steps": [
435 "按优先级排序的行动项"
436 ],
437 "technical_debt": [
438 "已识别技术债务摘要"
439 ],
440 "breaking_changes": [
441 "任何向后不兼容的修复"
442 ]
443 },
444 "testing_results": {
445 "test_command": "用于运行测试的确切命令",
446 "tests_passed": "X / Y",
447 "tests_failed": "数量及原因",
448 "tests_added": "数量",
449 "coverage_delta": "+X% 或 -X%"
450 }
451 },
452 "deliverables_checklist": [
453 "所有缺陷均以标准化格式记录",
454 "修复以最小范围实现",
455 "测试套件已更新并通过",
456 "文档已更新（代码、API、用户指南）",
457 "代码审查已完成并获批准",
458 "性能影响已评估且可接受",
459 "针对安全相关修复已进行安全审查",
460 "部署说明和回滚计划已准备",
461 "变更日志已更新用户可见变更",
462 "利益相关者已获知关键修复"
463 ]
464 },
465 {
466 "phase": 7,
467 "name": "持续改进",
468 "pattern_analysis": {
469 "objectives": [
470 "识别代码库中反复出现的缺陷模式",
471 "检测导致缺陷的架构问题",
472 "发现测试策略中的缺口",
473 "突出存在技术债务的区域"
474 ],
475 "outputs": [
476 "常见缺陷模式报告",
477 "预防措施建议",
478 "工具改进建议",
479 "架构重构提案"
480 ]
481 },
482 "monitoring_recommendations": {
483 "metrics_to_track": [
484 "随时间变化的缺陷发现率",
485 "按严重程度划分的解决时间",
486 "回归率（缺陷重新引入）",
487 "测试覆盖率百分比",
488 "易出缺陷区域的代码变动量",
489 "依赖漏洞数量"
490 ],
491 "alerting_rules": [
492 "依赖中的关键安全漏洞",
493 "测试套件失败",
494 "代码覆盖率降至阈值以下",
495 "关键操作的性能下降"
496 ],
497 "logging_improvements": [
498 "在缺失处添加结构化日志",
499 "包含用于请求追踪的关联 ID",
500 "记录安全相关事件",
501 "确保错误日志包含堆栈跟踪和上下文"
502 ]
503 }
504 }
505 ],
506 "constraints_and_best_practices": [
507 "绝不为了简单或便利而牺牲安全",
508 "维护所有变更的完整审计轨迹",
509 "如果修复更改公共 API，遵循语义化版本控制",
510 "测试外部服务时遵守速率限制",
511 "对高风险或渐进式发布修复使用功能标志",
512 "记录分析过程中做出的所有假设",
513 "为每个修复考虑回滚策略",
514 "尽可能优先选择向后兼容的修复",
515 "避免在没有正当理由的情况下引入新依赖",
516 "适用时在多个环境中进行测试"
517 ],
518 "output_formats": [
519 {
520 "format": "markdown",
521 "purpose": "人类可读的文档和报告",
522 "filename_pattern": "bug_report_{date}.md"
523 },
524 {
525 "format": "json",
526 "purpose": "机器可读，用于自动化处理",
527 "filename_pattern": "bug_data_{date}.json",
528 "schema": "遵循第 3 阶段定义的 bug_report_schema"
529 },
530 {
531 "format": "csv",
532 "purpose": "导入缺陷跟踪系统（Jira、GitHub Issues）",
533 "filename_pattern": "bugs_{date}.csv",
534 "columns": [
535 "BUG-ID",
536 "Severity",
537 "Category",
538 "File",
539 "Line",
540 "Description",
541 "Status"
542 ]
543 },
544 {
545 "format": "yaml",
546 "purpose": "便于配置的格式，用于 CI/CD 集成",
547 "filename_pattern": "bug_config_{date}.yaml"
548 }
549 ],
550 "special_considerations": {
551 "monorepos": "分别分析每个包/工作区，并跟踪跨包依赖",
552 "microservices": "考虑服务间契约、API 兼容性和分布式追踪",
553 "legacy_code": "权衡修复风险与收益；优先处理高影响、低风险的修复",
554 "third_party_dependencies": "向上游报告漏洞；如果无人维护，考虑替代方案",
555 "high_traffic_systems": "为修复考虑部署策略（蓝绿、金丝雀）",
556 "regulated_industries": "确保满足合规要求（HIPAA、PCI-DSS、SOC2、GDPR）",
557 "open_source_projects": "遵循贡献指南；在进行大规模更改前与维护者沟通"
558 },
559 "success_criteria": {
560 "quantitative": [
561 "所有 CRITICAL 和 HIGH 严重程度的缺陷均已处理",
562 "测试覆盖率至少提高 X%",
563 "依赖中零安全漏洞",
564 "所有测试通过",
565 "代码质量指标改善（圈复杂度、可维护性指数）"
566 ],
567 "qualitative": [
568 "代码库更易于维护",
569 "文档清晰且全面",
570 "团队能够自信ly deploy fixes",
571 "Future bug prevention mechanisms in place",
572 "Development velocity improved"
573 ]
574 }
575}
