pplx-sdk-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pplx-sdk Development Meta-Skill

pplx-sdk开发元技能

This meta-skill orchestrates all project-specific and community skills for pplx-sdk development. Activate this skill for any development task — it coordinates the right sub-skills automatically.

这个元技能可编排所有针对pplx-sdk开发的项目专属技能与社区技能。任何开发任务都可激活该技能——它会自动协调合适的子技能。

When to use

使用场景

Use this skill for any development task on the pplx-sdk project: implementing features, fixing bugs, reviewing code, writing tests, or scaffolding new modules.

当你在pplx-sdk项目中进行任何开发任务时都可使用该技能：功能实现、Bug修复、代码审查、编写测试或搭建新模块脚手架。

Subagent Architecture

子代理架构

Each skill delegates to a specialist subagent via

context: fork

. Subagents run in isolated context windows with restricted tool access.

┌───────────────────────────────────────────────────────┐
│                  orchestrator                         │
│  (meta-orchestrator, delegates subtasks)              │
├───────────────────────────────────────────────────────┤
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ code-reviewer │  │ test-runner   │                  │
│  │ (read-only)   │  │ (run & fix)   │                  │
│  │ view,grep,    │  │ bash,view,    │                  │
│  │ glob,bash     │  │ edit,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ scaffolder    │  │ sse-expert    │                  │
│  │ (create new)  │  │ (streaming)   │                  │
│  │ view,edit,    │  │ view,edit,    │                  │
│  │ bash,grep     │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ reverse-     │  │ architect     │                  │
│  │  engineer    │  │ (diagrams &   │                  │
│  │ (API disc.)  │  │  design)      │                  │
│  │ view,edit,   │  │ view,edit,    │                  │
│  │ bash,grep    │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ spa-expert   │  │ codegraph     │                  │
│  │ (SPA RE,     │  │ (AST, deps,   │                  │
│  │  CDP, ext.)  │  │  knowledge)   │                  │
│  │ view,edit,   │  │ view,edit,    │                  │
│  │ bash,grep    │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
└───────────────────────────────────────────────────────┘

每个技能都会通过

context: fork

委托给专业的子代理。子代理在独立的上下文窗口中运行，工具访问权限受限。

┌───────────────────────────────────────────────────────┐
│                  orchestrator                         │
│  (meta-orchestrator, delegates subtasks)              │
├───────────────────────────────────────────────────────┤
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ code-reviewer │  │ test-runner   │                  │
│  │ (read-only)   │  │ (run & fix)   │                  │
│  │ view,grep,    │  │ bash,view,    │                  │
│  │ glob,bash     │  │ edit,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ scaffolder    │  │ sse-expert    │                  │
│  │ (create new)  │  │ (streaming)   │                  │
│  │ view,edit,    │  │ view,edit,    │                  │
│  │ bash,grep     │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ reverse-     │  │ architect     │                  │
│  │  engineer    │  │ (diagrams &   │                  │
│  │ (API disc.)  │  │  design)      │                  │
│  │ view,edit,   │  │ view,edit,    │                  │
│  │ bash,grep    │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
│  ┌──────────────┐  ┌──────────────┐                  │
│  │ spa-expert   │  │ codegraph     │                  │
│  │ (SPA RE,     │  │ (AST, deps,   │                  │
│  │  CDP, ext.)  │  │  knowledge)   │                  │
│  │ view,edit,   │  │ view,edit,    │                  │
│  │ bash,grep    │  │ bash,grep     │                  │
│  └──────────────┘  └──────────────┘                  │
│                                                       │
└───────────────────────────────────────────────────────┘

Subagent Definitions (

.claude/agents/

)

子代理定义（

.claude/agents/

）

Subagent	Role	Tools	Isolation
`orchestrator`	Decomposes tasks, coordinates others	view, bash, grep, glob	fork
`code-reviewer`	Read-only architecture review	view, grep, glob, bash	fork
`test-runner`	Run tests, diagnose, fix failures	bash, view, edit, grep, glob	fork
`scaffolder`	Create new modules and files	view, edit, bash, grep, glob	fork
`sse-expert`	SSE streaming implementation	view, edit, bash, grep, glob	fork
`reverse-engineer`	API discovery, traffic analysis	view, edit, bash, grep, glob	fork
`architect`	Architecture diagrams, design validation	view, edit, bash, grep, glob	fork
`spa-expert`	SPA RE: React/Vite/Workbox/CDP, extensions	view, edit, bash, grep, glob	fork
`codegraph`	AST parsing (Python + JS/TS), dep graphs, knowledge graphs	view, edit, bash, grep, glob	fork

子代理	角色	工具	隔离方式
`orchestrator`	分解任务，协调其他代理	view, bash, grep, glob	fork
`code-reviewer`	只读架构审查	view, grep, glob, bash	fork
`test-runner`	运行测试、诊断并修复失败用例	bash, view, edit, grep, glob	fork
`scaffolder`	创建新模块和文件	view, edit, bash, grep, glob	fork
`sse-expert`	SSE流实现	view, edit, bash, grep, glob	fork
`reverse-engineer`	API发现、流量分析	view, edit, bash, grep, glob	fork
`architect`	架构图绘制、设计验证	view, edit, bash, grep, glob	fork
`spa-expert`	SPA逆向工程：React/Vite/Workbox/CDP、扩展	view, edit, bash, grep, glob	fork
`codegraph`	AST解析（Python + JS/TS）、依赖图、知识图谱	view, edit, bash, grep, glob	fork

Skill Dependencies

技能依赖

This meta-skill composes the following skills. Apply them in the order shown based on the task type.

该元技能由以下技能组合而成。可根据任务类型按所示顺序应用它们。

Project-Specific Skills (repo root)

项目专属技能（仓库根目录）

Skill	Path	Subagent	Purpose
`code-review`	`code-review/SKILL.md`	`code-reviewer`	Architecture compliance and conventions
`test-fix`	`test-fix/SKILL.md`	`test-runner`	Diagnose and fix failing tests
`scaffold-module`	`scaffold-module/SKILL.md`	`scaffolder`	Create new modules per layered architecture
`sse-streaming`	`sse-streaming/SKILL.md`	`sse-expert`	SSE protocol and streaming patterns
`reverse-engineer`	`reverse-engineer/SKILL.md`	`reverse-engineer`	API discovery from browser traffic
`architecture`	`architecture/SKILL.md`	`architect`	System diagrams and design visualization
`spa-reverse-engineer`	`spa-reverse-engineer/SKILL.md`	`spa-expert`	React/Vite/Workbox/CDP webapp RE
`code-analysis`	`code-analysis/SKILL.md`	`codegraph`	AST parsing (Python + JS/TS), dependency graphs, knowledge graphs

技能	路径	子代理	用途
`code-review`	`code-review/SKILL.md`	`code-reviewer`	架构合规性与规范检查
`test-fix`	`test-fix/SKILL.md`	`test-runner`	诊断并修复失败的测试
`scaffold-module`	`scaffold-module/SKILL.md`	`scaffolder`	按分层架构创建新模块
`sse-streaming`	`sse-streaming/SKILL.md`	`sse-expert`	SSE协议与流处理模式
`reverse-engineer`	`reverse-engineer/SKILL.md`	`reverse-engineer`	从浏览器流量中发现API
`architecture`	`architecture/SKILL.md`	`architect`	系统图与设计可视化
`spa-reverse-engineer`	`spa-reverse-engineer/SKILL.md`	`spa-expert`	React/Vite/Workbox/CDP网页应用逆向工程
`code-analysis`	`code-analysis/SKILL.md`	`codegraph`	AST解析（Python + JS/TS）、依赖图、知识图谱

Community Skills (installed via

npx skills

)

社区技能（通过

npx skills

安装）

Skill	Source	Purpose
`python-testing-patterns`	`wshobson/agents`	pytest patterns, fixtures, mocking
`python-type-safety`	`wshobson/agents`	Type annotations, mypy strict mode
`python-error-handling`	`wshobson/agents`	Exception hierarchies, error patterns
`python-design-patterns`	`wshobson/agents`	Protocol pattern, DI, factory
`api-design-principles`	`wshobson/agents`	REST API design, endpoint conventions
`async-python-patterns`	`wshobson/agents`	async/await, concurrency patterns
`skill-creator`	`anthropics/skills`	Guide for creating new skills
`mcp-builder`	`anthropics/skills`	Build MCP servers for tool integration
`webapp-testing`	`anthropics/skills`	Test web apps with Playwright
`ast-grep`	`ast-grep/agent-skill`	Structural code search via AST patterns
`knowledge-graph-builder`	`daffy0208/ai-dev-standards`	Knowledge graph design and entity relationships
`steering`	`nahisaho/codegraphmcpserver`	CodeGraph MCP orchestration and traceability

技能	来源	用途
`python-testing-patterns`	`wshobson/agents`	pytest模式、夹具、模拟
`python-type-safety`	`wshobson/agents`	类型注解、mypy严格模式
`python-error-handling`	`wshobson/agents`	异常层级、错误模式
`python-design-patterns`	`wshobson/agents`	协议模式、依赖注入、工厂模式
`api-design-principles`	`wshobson/agents`	REST API设计、端点规范
`async-python-patterns`	`wshobson/agents`	async/await、并发模式
`skill-creator`	`anthropics/skills`	创建新技能的指南
`mcp-builder`	`anthropics/skills`	构建用于工具集成的MCP服务器
`webapp-testing`	`anthropics/skills`	用Playwright测试网页应用
`ast-grep`	`ast-grep/agent-skill`	通过AST模式进行结构化代码搜索
`knowledge-graph-builder`	`daffy0208/ai-dev-standards`	知识图谱设计与实体关系
`steering`	`nahisaho/codegraphmcpserver`	CodeGraph MCP编排与可追溯性

Workflow: New Feature

工作流：新功能开发

[plan] → [explore] → [research] → [implement] → [test] → [review] → [done]

Plan —
```
orchestrator
```
decomposes the task, identifies target layer
Explore —
```
code-reviewer
```
(read-only fork) analyzes existing code and dependencies
Research —
```
reverse-engineer
```
or
```
sse-expert
```
(fork) studies API behavior, reads docs, gathers context needed before implementation
Scaffold —
```
scaffolder
```
(fork) creates files from templates
Implement —
```
sse-expert
```
or
```
scaffolder
```
(fork) writes the code
Test —
```
test-runner
```
(fork) runs pytest, fixes failures
Review —
```
code-reviewer
```
(fork) validates architecture compliance

Verify —

ruff check --fix . && ruff format . && mypy pplx_sdk/ && pytest -v

[plan] → [explore] → [research] → [implement] → [test] → [review] → [done]

规划 —
```
orchestrator
```
分解任务，确定目标层级
探索 —
```
code-reviewer
```
（只读fork）分析现有代码与依赖
调研 —
```
reverse-engineer
```
或
```
sse-expert
```
（fork）研究API行为、阅读文档，收集实现前所需的上下文信息
搭建脚手架 —
```
scaffolder
```
（fork）从模板创建文件
实现 —
```
sse-expert
```
或
```
scaffolder
```
（fork）编写代码
测试 —
```
test-runner
```
（fork）运行pytest，修复失败用例
审查 —
```
code-reviewer
```
（fork）验证架构合规性

验证 — 执行

ruff check --fix . && ruff format . && mypy pplx_sdk/ && pytest -v

Workflow: Bug Fix

工作流：Bug修复

Reproduce —
```
test-runner
```
(fork) runs failing test with
```
-v
```
Research —
```
code-reviewer
```
(fork) traces the code path, reads related modules and tests
Diagnose —
```
test-runner
```
reads traceback, identifies root cause
Fix —
```
test-runner
```
edits source/test, applies
```
python-error-handling
```
patterns
Verify —
```
test-runner
```
runs full suite

复现 —
```
test-runner
```
（fork）通过
```
-v
```
参数运行失败的测试
调研 —
```
code-reviewer
```
（fork）追踪代码路径，阅读相关模块与测试
诊断 —
```
test-runner
```
读取回溯信息，确定根本原因
修复 —
```
test-runner
```
编辑源码/测试，应用
```
python-error-handling
```
模式
验证 —
```
test-runner
```
运行完整测试套件

Workflow: SSE/Streaming Work

工作流：SSE/流处理工作

Research —
```
sse-expert
```
(fork) reviews SSE protocol spec, existing transport code, and API response patterns
Implement —
```
sse-expert
```
writes streaming code, applies
```
async-python-patterns
```
Test —
```
test-runner
```
(fork) runs tests with mock SSE responses
Review —
```
code-reviewer
```
(fork) validates transport layer compliance

调研 —
```
sse-expert
```
（fork）审查SSE协议规范、现有传输代码与API响应模式
实现 —
```
sse-expert
```
编写流处理代码，应用
```
async-python-patterns
```
测试 —
```
test-runner
```
（fork）使用模拟SSE响应运行测试
审查 —
```
code-reviewer
```
（fork）验证传输层合规性

Workflow: API Discovery (Reverse Engineering)

工作流：API发现（逆向工程）

[capture] → [research] → [document] → [scaffold] → [test] → [review]

Capture —
```
reverse-engineer
```
(fork) analyzes cURL/traffic from perplexity.ai DevTools
Research —
```
reverse-engineer
```
studies request/response patterns, tests variations, maps edge cases and auth flows
Document —
```
reverse-engineer
```
writes endpoint documentation with field types and examples
Scaffold —
```
scaffolder
```
(fork) creates Pydantic models and service methods from schema
Implement —
```
sse-expert
```
or
```
scaffolder
```
implements transport and domain code
Test —
```
test-runner
```
(fork) validates with mock responses matching discovered schemas
Review —
```
code-reviewer
```
(fork) ensures architecture compliance

[capture] → [research] → [document] → [scaffold] → [test] → [review]

捕获 —
```
reverse-engineer
```
（fork）分析来自perplexity.ai开发者工具的cURL/流量
调研 —
```
reverse-engineer
```
研究请求/响应模式，测试变体，梳理边缘情况与认证流程
文档 —
```
reverse-engineer
```
编写包含字段类型与示例的端点文档
搭建脚手架 —
```
scaffolder
```
（fork）从Schema创建Pydantic模型与服务方法
实现 —
```
sse-expert
```
或
```
scaffolder
```
实现传输层与领域代码
测试 —
```
test-runner
```
（fork）使用与发现的Schema匹配的模拟响应进行验证
审查 —
```
code-reviewer
```
（fork）确保架构合规性

Workflow: API Endpoint

工作流：API端点开发

Research —
```
code-reviewer
```
(fork) studies existing endpoints and
```
api-design-principles
```
patterns
Design —
```
code-reviewer
```
reviews proposed schema against REST conventions
Implement —
```
scaffolder
```
(fork) creates FastAPI endpoint
Test —
```
test-runner
```
(fork) validates with pytest-httpx mocks

调研 —
```
code-reviewer
```
（fork）研究现有端点与
```
api-design-principles
```
模式
设计 —
```
code-reviewer
```
对照REST规范审查提议的Schema
实现 —
```
scaffolder
```
（fork）创建FastAPI端点
测试 —
```
test-runner
```
（fork）使用pytest-httpx模拟进行验证

Workflow: Architecture Design & Visualization

工作流：架构设计与可视化

[analyze] → [research] → [diagram] → [validate] → [document]

Analyze —
```
architect
```
(fork) reads existing code, maps imports and layer dependencies
Research —
```
architect
```
studies the components involved and their relationships
Diagram —
```
architect
```
produces Mermaid diagrams (layer map, sequence, class hierarchy, state machine)
Validate —
```
architect
```
checks for circular deps, upward imports, protocol conformance
Document —
```
architect
```
embeds diagrams in README, docs, or PR descriptions

[analyze] → [research] → [diagram] → [validate] → [document]

分析 —
```
architect
```
（fork）读取现有代码，映射导入关系与层级依赖
调研 —
```
architect
```
研究涉及的组件及其关系
绘图 —
```
architect
```
生成Mermaid图（层级图、序列图、类层次图、状态机图）
验证 —
```
architect
```
检查循环依赖、向上导入、协议合规性
文档 —
```
architect
```
将图嵌入README、文档或PR描述中

Workflow: SPA Reverse Engineering

工作流：SPA逆向工程

[detect] → [research] → [intercept] → [extract] → [code-graph] → [document] → [implement]

Detect —
```
spa-expert
```
(fork) identifies the SPA stack (React version, bundler, state management, service workers)
Research —
```
spa-expert
```
studies the SPA internals, React component tree, and network patterns
Intercept —
```
spa-expert
```
captures network traffic via CDP, Chrome extension, or DevTools
Extract —
```
spa-expert
```
extracts React state shapes, API schemas, and Workbox cache strategies
Code Graph —
```
codegraph
```
(fork) analyzes SPA source code: component tree, import graph, hook chains, TypeScript types; cross-references with
```
spa-expert
```
runtime findings
Document —
```
reverse-engineer
```
+
```
spa-expert
```
map runtime + static discoveries to SDK architecture
Implement —
```
scaffolder
```
creates models and services;
```
spa-expert
```
builds tools/extensions

[detect] → [research] → [intercept] → [extract] → [code-graph] → [document] → [implement]

检测 —
```
spa-expert
```
（fork）识别SPA技术栈（React版本、打包工具、状态管理、Service Worker）
调研 —
```
spa-expert
```
研究SPA内部机制、React组件树与网络模式
拦截 —
```
spa-expert
```
通过CDP、Chrome扩展或开发者工具捕获网络流量
提取 —
```
spa-expert
```
提取React状态结构、API Schema与Workbox缓存策略
代码图谱 —
```
codegraph
```
（fork）分析SPA源码：组件树、导入图、钩子链、TypeScript类型；与
```
spa-expert
```
的运行时发现进行交叉引用
文档 —
```
reverse-engineer
```
+
```
spa-expert
```
将运行时与静态发现映射到SDK架构
实现 —
```
scaffolder
```
创建模型与服务；
```
spa-expert
```
构建工具/扩展

Workflow: Code Analysis & Knowledge Graph

工作流：代码分析与知识图谱

[parse] → [graph] → [analyze] → [report] → [act]

Parse —
```
codegraph
```
(fork) parses source AST: Python via
```
ast
```
module, JavaScript/TypeScript via grep-based import parsing
Graph —
```
codegraph
```
builds dependency graph (module-to-module imports) and knowledge graph (Python: IMPORTS, INHERITS, IMPLEMENTS, CALLS, RAISES; SPA: RENDERS, USES_HOOK, CALLS_API, PROVIDES, CONSUMES)
Analyze —
```
codegraph
```
detects patterns: circular deps, layer violations, dead code, complexity hotspots (Python); barrel file cycles, prop drilling, orphan routes (SPA)
Report —
```
codegraph
```
produces structured insights report with Mermaid diagrams and actionable findings
Act — Delegate findings:
```
architect
```
updates diagrams,
```
code-reviewer
```
reviews violations,
```
scaffolder
```
fixes gaps,
```
spa-expert
```
cross-references runtime analysis

[parse] → [graph] → [analyze] → [report] → [act]

解析 —
```
codegraph
```
（fork）解析源码AST：Python通过
```
ast
```
模块，JavaScript/TypeScript通过基于grep的导入解析
图谱构建 —
```
codegraph
```
构建依赖图（模块间导入）与知识图谱（Python：导入、继承、实现、调用、抛出；SPA：渲染、使用钩子、调用API、提供、消费）
分析 —
```
codegraph
```
检测模式：循环依赖、层级违规、死代码、复杂度热点（Python）；桶文件循环、属性透传、孤立路由（SPA）
报告 —
```
codegraph
```
生成包含Mermaid图与可执行发现结果的结构化洞察报告
行动 — 委托发现结果：
```
architect
```
更新图，
```
code-reviewer
```
审查违规，
```
scaffolder
```
修复缺口，
```
spa-expert
```
交叉引用运行时分析

Project Quick Reference

项目快速参考

bash

undefined

bash

undefined

Install dependencies

安装依赖

pip install -e ".[dev]"

Install/update community skills

安装/更新社区技能

npx skills add wshobson/agents --skill python-testing-patterns --skill python-type-safety --skill python-error-handling --skill python-design-patterns --skill api-design-principles --skill async-python-patterns --agent github-copilot -y npx skills add anthropics/skills --skill skill-creator --skill mcp-builder --skill webapp-testing --agent github-copilot -y npx skills add ast-grep/agent-skill --skill ast-grep --agent github-copilot -y npx skills add "daffy0208/ai-dev-standards@knowledge-graph-builder" --agent github-copilot -y npx skills add nahisaho/codegraphmcpserver --skill steering --agent github-copilot -y

Lint, format, type-check, test

代码检查、格式化、类型检查、测试

ruff check --fix . && ruff format . mypy pplx_sdk/ --ignore-missing-imports pytest tests/ -v --cov=pplx_sdk

Manage skills

技能管理

npx skills list # Show installed skills npx skills check # Check for updates npx skills update # Update all skills

undefined

npx skills list # 显示已安装技能 npx skills check # 检查更新 npx skills update # 更新所有技能

undefined

Architecture Invariants

架构不变式

These rules must never be violated regardless of which sub-skill is active:

Layer dependencies:

core/ → shared/ → transport/ → domain/ → client.py

(never reverse)

Exception hierarchy: All errors extend
```
PerplexitySDKError
```
Type annotations: 100% coverage,
```
from __future__ import annotations
```
Google docstrings: On all public APIs
Protocol pattern: Use
```
typing.Protocol
```
, never ABC

无论哪个子技能处于激活状态，以下规则绝对不能被违反：

层级依赖：

core/ → shared/ → transport/ → domain/ → client.py

（绝对不能反向）

异常层级：所有错误都继承自
```
PerplexitySDKError
```
类型注解：100%覆盖，使用
```
from __future__ import annotations
```
Google风格文档字符串：所有公共API都必须包含
协议模式：使用
```
typing.Protocol
```
，绝对不能使用ABC