Metadata-Version: 2.4
Name: performance-optimization-workbench
Version: 0.1.0
Summary: 面向证据驱动性能优化的确定性 CLI 和可复用 Agent/Skills。
Author-email: bsh00699 <dianshijuhaoka@163.com>
Maintainer-email: bsh00699 <dianshijuhaoka@163.com>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.18
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# 性能优化工作台（Performance Optimization Workbench）

面向团队的中文性能优化工作台。它把“需求定义 → 代码分析 → 基线埋点 → 手工采样 → 瓶颈定位 → 方案设计与实施 → P50/P90 验证 → 提效报告”固化为由 Agent、Skills、数据契约、模板和确定性 CLI 组成的可复用工程。

> **当前状态：** Alpha。仓库已经提供完整工作流、数据契约、核心 Skills、模板、合成示例，以及首版确定性校验/统计/对比 CLI。运行时适配器和 CI 自动化会逐步补充。

## 为什么需要这个项目

性能优化通常重复执行以下步骤：

1. 描述问题、指标、目标和验收门禁。
2. 梳理代码路径并添加基线性能埋点。
3. 在受控条件下完成基线采样。
4. 标准化并分析日志，基于证据定位性能瓶颈。
5. 设计并实施优化方案。
6. 在相同条件下采集优化后批次。
7. 对比 P50/P90 和护栏指标。
8. 生成采样、分析、设计和提效报告。

本工作台把这套流程变成共享的、以产物为中心的工作流：总控 Agent 管理状态和审批，Skills 执行边界清晰的任务，确定性工具负责计算，项目适配器负责运行时差异。

## 架构

```text
用户需求 / GitHub Issue
          |
          v
性能优化总控 Agent
          |
          +-- Skills：规范、仓库映射、埋点、采样手册
          +-- Skills：日志标准化、瓶颈分析、方案设计
          +-- Skills：优化实施、回归验证、报告生成
          +-- 契约：experiment、run、event、analysis、comparison
          +-- 适配器：项目、运行时、日志、分析器、GitHub
          |
          v
不可变的性能实验产物包
```

工作台坚持证据优先：不得静默修改目标、删除异常运行、把并行阶段相加为串行耗时，或把不可比数据包装成优化结论。

## 工作流状态

```text
INTAKE -> SPEC_READY -> REPO_MAPPED -> INSTRUMENTATION_READY
       -> BASELINE_COLLECTED -> BOTTLENECK_IDENTIFIED
       -> DESIGN_READY -> IMPLEMENTED -> OPTIMIZED_COLLECTED
       -> VERIFIED -> REPORTED
```

当证据不足或门禁失败时，可以进入 `WAITING_FOR_USER`、`INVALID_DATA`、`INCOMPARABLE`、`REGRESSION_FOUND` 或 `BLOCKED`。状态由产物和校验门禁推导，而不仅由聊天记录决定。

## 核心 Skills

| Skill | 责任 |
| --- | --- |
| `perf-spec` | 定义可度量目标、场景、目标值、采样规则和护栏。 |
| `perf-repo-mapping` | 梳理入口、调用路径、进程边界、输入输出、缓存和候选瓶颈。 |
| `perf-instrumentation` | 设计低开销计时、跟踪、元数据和基线日志补丁。 |
| `perf-runbook` | 生成可复现的手工或 CI 采样步骤和采集清单。 |
| `perf-log-normalization` | 将原始日志和跟踪转换为标准事件及运行记录。 |
| `perf-bottleneck-analysis` | 对性能瓶颈排序并形成有证据支撑的优化假设。 |
| `perf-optimization-design` | 生成包含风险、发布、回滚和验证的可实施设计。 |
| `perf-optimization-implementation` | 应用已批准变更，执行测试/构建并记录构建结果。 |
| `perf-regression-verification` | 检查可比性、计算 P50/P90 并执行验收门禁。 |
| `perf-reporting` | 从结构化产物生成四份可追溯的性能文档。 |

每个 Skill 都有独立的 `SKILL.md`，可以单独调用；完整生命周期建议从总控 Agent 开始。Skill 名称和技术标识的语言边界见 [`docs/中文术语与技术标识.md`](docs/中文术语与技术标识.md)。

## 仓库结构

```text
agents/                 总控 Agent 说明
skills/                 可复用 Codex Skills
contracts/              版本化 JSON 数据契约
templates/              采样手册和报告模板
examples/               合成且可公开的实验示例
adapters/               项目、运行时、日志、分析器和 GitHub 适配器
cli/                    确定性校验、统计和对比工具
policies/               测量完整性、隐私和审批规则
docs/                   中文术语和协作约定
.github/                Issue、拉取请求和 CI 集成入口
```

## 性能实验产物包

建议在接入项目中按以下结构保存实验：

```text
.perf/experiments/<experiment-id>/
├─ spec.yaml
├─ acceptance.yaml
├─ environment.json
├─ scenarios.yaml
├─ instrumentation/
├─ baseline/
│  ├─ raw-logs/
│  ├─ events.jsonl
│  └─ runs.jsonl
├─ optimized/
│  ├─ raw-logs/
│  ├─ events.jsonl
│  └─ runs.jsonl
├─ analysis/
├─ optimization/
├─ comparison.json
├─ manifest.json
└─ reports/
```

开始对比后，基线和优化后的原始产物应保持不可变。`manifest.json` 记录版本和哈希，便于后续审计报告。

## 数据契约

当前契约包括：

- [`experiment.schema.json`](contracts/experiment.schema.json)：目标、指标、场景、控制项和护栏。
- [`run.schema.json`](contracts/run.schema.json)：单次运行及其环境/构建元数据。
- [`event.schema.json`](contracts/event.schema.json)：标准跟踪/跨度事件数据。
- [`analysis.schema.json`](contracts/analysis.schema.json)：阶段统计、瓶颈、假设和限制。
- [`statistics.schema.json`](contracts/statistics.schema.json)：确定性的场景级和总体统计。
- [`comparison.schema.json`](contracts/comparison.schema.json)：基线/优化后指标、验收状态和置信度。

建议使用 `user_visible_ready`、`functional_ready`、`cache_ready` 和 `request_total` 等语义事件名；项目专用名称放在适配器别名映射中。

## 快速开始

1. 将 [`templates/experiment-spec.yaml`](templates/experiment-spec.yaml) 复制到项目实验目录。
2. 填写主指标、语义端点、场景矩阵、目标和护栏。
3. 调用 `$perf-spec` 评审规范。
4. 使用 `$perf-repo-mapping` 和 `$perf-instrumentation` 生成带证据链接的代码地图和可评审补丁。
5. 使用 `$perf-runbook` 采集基线，并保留原始日志和失败运行。
6. 标准化批次、分析瓶颈、审批方案并实施变更。
7. 使用相同场景和环境控制采集优化后批次。
8. 执行回归验证并生成四份报告。

完整的合成端到端示例位于 [`examples/application-open`](examples/application-open/)。

## 确定性 CLI

在隔离环境安装本地包：

```bash
python -m pip install -e .
```

校验运行批次：

```bash
perf-validate --contract run \
  --input examples/application-open/baseline/runs.jsonl
```

计算 P50/P90。默认使用版本化的 `linear_interpolation_v1` 算法：

```bash
perf-stats \
  --input examples/application-open/baseline/runs.jsonl \
  --metric user_visible_ready_ms \
  --min-valid-samples 3 \
  --preferred-valid-samples 3 \
  --output baseline-stats.json
```

将两份统计产物按照实验定义进行对比：

```bash
perf-compare \
  --baseline baseline-stats.json \
  --optimized optimized-stats.json \
  --experiment examples/application-open/experiment.json \
  --require-pass \
  --output comparison.json
```

不安装也可以使用 `python -m cli.perf_validate`、`python -m cli.perf_stats` 和 `python -m cli.perf_compare`。在 `perf-validate` 中使用 `--output-format json` 可获得适合 CI 的结构化错误。

运行确定性测试：

```bash
python -m unittest discover -s tests -v
```

在 Windows 中文系统上校验 Skill 时，请显式启用 UTF-8，避免 Python 按本地代码页读取中文 `SKILL.md`：

```bash
python -X utf8 C:/Users/<用户>/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/perf-spec
```

其余 Skill 目录按相同方式逐个校验。

## 测量完整性默认规则

- 使用单调时钟计算持续时长，并在两组数据中固定百分位数算法。
- 每个场景优先采集至少 30 个有效样本；较小的探索批次标记为低置信度。
- 分开报告冷/热状态、缓存命中/未命中和排除用户交互等待的指标。
- 报告 P50、P90、样本数、无效运行、失败、崩溃、内存、CPU 和限制。
- 对比相同的端点语义、构建类型、数据快照、机器、运行时和场景矩阵。
- 永不删除原始证据，也不静默丢弃离群值。
- 没有源码或跟踪链接及可检验假设时，不声称因果关系。

## GitHub 集成方向

仓库通过适配器对接 GitHub Issue、拉取请求、Actions、产物和外部 Agent/Skill。外部能力必须固定到发布版本或提交，经过许可证和安全审查，并标准化为本仓库契约。

## 公共仓库安全

示例必须是合成或已脱敏数据。不得提交内部日志、源码、凭据、用户标识、机器标识或私有包路径。项目专用数据应保存在接入项目中，而不是公共工作台。

## 路线图

- 在确定性 CLI 中加入事件标准化、置信区间和实验清单哈希。
- 增加 TypeScript/Electron、Node.js、Python、JVM 和 OpenTelemetry 适配器。
- 增加 GitHub Issue 模板、PR 评论、Actions 产物采集和性能门禁。
- 为冷启动、热缓存、文件 I/O、网络请求、渲染和并发增加经过前向验证的示例。
- 发布供外部 GitHub Agent 和 Skill 使用的版本化能力注册表。

## 贡献

保持 Skill 小而聚焦；详细变体放入一层 `references/`，算术和校验使用确定性脚本，为解析器变更补充合成夹具，并保持契约版本兼容。每条新增优化规则都应声明证据要求和失败行为。

项目采用 MIT License，完整文本见 [`LICENSE`](LICENSE)。
