mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
Add Chinese documentation for custom skills development and reference guide
- Created a new document for custom skills development (`custom.md`) detailing the structure, creation, implementation, and best practices for developing custom CCW skills. - Added an index document (`index.md`) summarizing all built-in skills, their categories, and usage examples. - Introduced a reference guide (`reference.md`) providing a quick reference for all 33 built-in CCW skills, including triggers and purposes.
This commit is contained in:
catlog22
245
docs/skills/templates/architecture-doc.md
Normal file
245
docs/skills/templates/architecture-doc.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# Architecture Doc Template
|
||||
|
||||
> 用途: 架构文档模板，用于 spec-generator Phase 4 输出
|
||||
|
||||
## 模板
|
||||
|
||||
### _index.md 模板
|
||||
|
||||
```markdown
|
||||
# Architecture - Index
|
||||
|
||||
> **Product**: {Product Name}
|
||||
> **Generated**: {YYYY-MM-DD}
|
||||
> **Session**: {session-id}
|
||||
|
||||
## Overview
|
||||
|
||||
架构概述（2-3 段）
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
1. **Principle 1**: Description
|
||||
2. **Principle 2**: Description
|
||||
3. **Principle 3**: Description
|
||||
|
||||
## System Architecture
|
||||
|
||||
### High-Level Architecture
|
||||
|
||||
```plaintext
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Frontend │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Web UI │ │ Mobile │ │ API │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Backend Layer │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Gateway │ │ Services │ │ Events │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Data Layer │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ | Database │ │ Cache │ │ Storage │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
| Component | Responsibility | Technology |
|
||||
|-----------|----------------|------------|
|
||||
| Component 1 | 描述 | 技术栈 |
|
||||
| Component 2 | 描述 | 技术栈 |
|
||||
| Component 3 | 描述 | 技术栈 |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Frontend
|
||||
|
||||
| Layer | Technology | Rationale |
|
||||
|-------|-----------|-----------|
|
||||
| Framework | {framework} | 选择理由 |
|
||||
| State | {state lib} | 选择理由 |
|
||||
| UI | {ui lib} | 选择理由 |
|
||||
|
||||
### Backend
|
||||
|
||||
| Layer | Technology | Rationale |
|
||||
|-------|-----------|-----------|
|
||||
| Runtime | {runtime} | 选择理由 |
|
||||
| Framework | {framework} | 选择理由 |
|
||||
| Database | {database} | 选择理由 |
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
详见各 ADR 文档：
|
||||
- [ADR-001-{title}](./ADR-001-{slug}.md)
|
||||
- [ADR-002-{title}](./ADR-002-{slug}.md)
|
||||
|
||||
## Requirements Traceability
|
||||
|
||||
| Requirement | ADR | Component |
|
||||
|-------------|-----|-----------|
|
||||
| REQ-001 | ADR-001 | Service A |
|
||||
| REQ-002 | ADR-002 | Service B |
|
||||
|
||||
## Change Log
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | YYYY-MM-DD | Initial version |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ADR-*.md 模板
|
||||
|
||||
```markdown
|
||||
# ADR-{NNN}: {Decision Title}
|
||||
|
||||
> **Status**: {Accepted|Deprecated|Superseded}
|
||||
> **Date**: {YYYY-MM-DD}
|
||||
> **Decision Type**: {Technical|Process|Architecture}
|
||||
|
||||
## Context
|
||||
|
||||
描述背景和问题：
|
||||
- 当前状况
|
||||
- 需要解决的问题
|
||||
- 约束条件
|
||||
|
||||
## Decision
|
||||
|
||||
**决策内容**: 一句话概括
|
||||
|
||||
详细说明决策内容
|
||||
|
||||
### Options Considered
|
||||
|
||||
| Option | Pros | Cons | Selected |
|
||||
|--------|------|------|----------|
|
||||
| Option 1 | 优点 | 缺点 | No |
|
||||
| Option 2 | 优点 | 缺点 | **Yes** |
|
||||
| Option 3 | 优点 | 缺点 | No |
|
||||
|
||||
### Rationale
|
||||
|
||||
选择此方案的原因：
|
||||
1. Reason 1
|
||||
2. Reason 2
|
||||
3. Reason 3
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Benefit 1
|
||||
- Benefit 2
|
||||
|
||||
### Negative
|
||||
|
||||
- Risk 1
|
||||
- Risk 2
|
||||
|
||||
### Mitigation
|
||||
|
||||
如何缓解负面影响
|
||||
|
||||
## Related Requirements
|
||||
|
||||
| Requirement | Relation |
|
||||
|-------------|----------|
|
||||
| REQ-001 | Enables |
|
||||
| NFR-PERF-001 | Addresses |
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
1. Alternative 1: Description - Rejected because...
|
||||
2. Alternative 2: Description - Rejected because...
|
||||
|
||||
## References
|
||||
|
||||
- [Related Doc](path)
|
||||
- [External Reference](url)
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: spec-generator Phase 4
|
||||
2. **输入**: Phase 3 Requirements (PRD)
|
||||
3. **输出**: architecture/ 目录，包含 _index.md 和所有 ADR 文件
|
||||
4. **验证**: 确保追溯链接有效
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例 - ADR-001.md
|
||||
|
||||
```markdown
|
||||
# ADR-001: Use Operational Transformation for Real-Time Sync
|
||||
|
||||
> **Status**: Accepted
|
||||
> **Date**: 2026-03-01
|
||||
> **Decision Type**: Technical
|
||||
|
||||
## Context
|
||||
|
||||
实时协作平台需要支持多用户同时编辑同一文档。
|
||||
- 简单的"最后写入胜出"策略会导致数据丢失
|
||||
- 需要自动解决编辑冲突
|
||||
- 网络延迟和离线编辑需要支持
|
||||
|
||||
## Decision
|
||||
|
||||
**决策内容**: 使用 Operational Transformation (OT) 算法实现实时同步
|
||||
|
||||
OT 通过转换操作序列来解决冲突，确保最终一致性。
|
||||
|
||||
### Options Considered
|
||||
|
||||
| Option | Pros | Cons | Selected |
|
||||
|--------|------|------|----------|
|
||||
| Last Write Wins | 简单 | 数据丢失 | No |
|
||||
| OT (Yjs) | 成熟方案 | 复杂度高 | **Yes** |
|
||||
| CRDT | 理论优雅 | 性能开销 | No |
|
||||
|
||||
### Rationale
|
||||
|
||||
1. **成熟度**: Yjs 是成熟的 OT 实现，被广泛应用
|
||||
2. **性能**: OT 比 CRDT 性能更好，适合文档编辑场景
|
||||
3. **社区**: 活跃的社区支持和丰富的集成
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 自动解决冲突，无需用户干预
|
||||
- 支持离线编辑，重连后自动同步
|
||||
- 低延迟，良好的用户体验
|
||||
|
||||
### Negative
|
||||
|
||||
- 实现复杂，学习曲线陡峭
|
||||
- 需要维护操作历史，内存开销
|
||||
|
||||
### Mitigation
|
||||
|
||||
- 使用成熟的 Yjs 库，降低实现复杂度
|
||||
- 实现历史压缩策略，控制内存使用
|
||||
|
||||
## Related Requirements
|
||||
|
||||
| Requirement | Relation |
|
||||
|-------------|----------|
|
||||
| REQ-001 | Enables |
|
||||
| NFR-PERF-001 | Addresses |
|
||||
```
|
||||
260
docs/skills/templates/autonomous-action.md
Normal file
260
docs/skills/templates/autonomous-action.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# Autonomous Action Template
|
||||
|
||||
> 用途: 自主行动模板，用于 Autonomous 类型 Skill 的具体行动
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# Action: {Action Name}
|
||||
|
||||
> **Skill**: {Skill Name}
|
||||
> **Action Type**: {Analysis|Execution|Verification}
|
||||
> **Estimated Duration**: {X minutes}
|
||||
|
||||
## Description
|
||||
|
||||
详细描述这个行动的目的和功能
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
| Condition | Description | Check Method |
|
||||
|-----------|-------------|--------------|
|
||||
| condition1 | 描述 | 如何检查 |
|
||||
| condition2 | 描述 | 如何检查 |
|
||||
|
||||
## Input Parameters
|
||||
|
||||
| Parameter | Type | Required | Description | Default |
|
||||
|-----------|------|----------|-------------|---------|
|
||||
| param1 | string | Yes | 参数描述 | - |
|
||||
| param2 | number | No | 参数描述 | 42 |
|
||||
| param3 | array | No | 参数描述 | [] |
|
||||
|
||||
## Output
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| result1 | string | 结果描述 |
|
||||
| result2 | object | 结果描述 |
|
||||
| success | boolean | 行动是否成功 |
|
||||
|
||||
## Execution Logic
|
||||
|
||||
### Step 1: {Step Name}
|
||||
|
||||
**Description**: 步骤描述
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
// 示例代码
|
||||
const step1Result = await doSomething(input);
|
||||
if (!step1Result) {
|
||||
throw new Error('Step 1 failed');
|
||||
}
|
||||
```
|
||||
|
||||
**Validation**: 如何验证步骤成功
|
||||
|
||||
### Step 2: {Step Name}
|
||||
|
||||
**Description**: 步骤描述
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
// 示例代码
|
||||
const step2Result = await process(step1Result);
|
||||
```
|
||||
|
||||
**Validation**: 如何验证步骤成功
|
||||
|
||||
### Step 3: {Step Name}
|
||||
|
||||
...
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Handling | Retry |
|
||||
|-------|-------|----------|-------|
|
||||
| ErrorType1 | 原因描述 | 处理方式 | Yes/No |
|
||||
| ErrorType2 | 原因描述 | 处理方式 | Yes/No |
|
||||
|
||||
**Error Recovery Logic**:
|
||||
```typescript
|
||||
try {
|
||||
return await execute();
|
||||
} catch (error) {
|
||||
if (error instanceof RecoverableError) {
|
||||
return await recover(error);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
```
|
||||
|
||||
## Side Effects
|
||||
|
||||
| Effect | Description | Mitigation |
|
||||
|--------|-------------|------------|
|
||||
| Side effect 1 | 描述 | 缓解措施 |
|
||||
| Side effect 2 | 描述 | 缓解措施 |
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Type | Version | Description |
|
||||
|------------|------|---------|-------------|
|
||||
| dep1 | internal | - | 内部依赖描述 |
|
||||
| dep2 | external | ^1.0.0 | 外部依赖描述 |
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Cases
|
||||
|
||||
| Case | Input | Expected Output |
|
||||
|------|-------|-----------------|
|
||||
| Normal case | `{param: "value"}` | `{result: "expected"}` |
|
||||
| Edge case | `{param: null}` | `{result: "default"}` |
|
||||
| Error case | `{param: "invalid"}` | Throws Error |
|
||||
|
||||
### Test Implementation
|
||||
|
||||
```typescript
|
||||
describe('ActionName', () => {
|
||||
it('should handle normal case', async () => {
|
||||
const result = await actionName({ param: 'value' });
|
||||
expect(result).toEqual({ result: 'expected' });
|
||||
});
|
||||
|
||||
it('should handle edge case', async () => {
|
||||
const result = await actionName({ param: null });
|
||||
expect(result).toEqual({ result: 'default' });
|
||||
});
|
||||
|
||||
it('should throw on invalid input', async () => {
|
||||
await expect(actionName({ param: 'invalid' }))
|
||||
.rejects.toThrow(Error);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
| Metric | Type | Unit |
|
||||
|--------|------|------|
|
||||
| duration | histogram | milliseconds |
|
||||
| success_rate | gauge | percentage |
|
||||
| error_count | counter | count |
|
||||
|
||||
## Example Usage
|
||||
|
||||
```typescript
|
||||
// 基本使用
|
||||
const result = await actionName({
|
||||
param1: 'value1',
|
||||
param2: 100
|
||||
});
|
||||
|
||||
console.log(result);
|
||||
|
||||
// 带重试
|
||||
const result = await actionName.withRetry({
|
||||
param1: 'value1'
|
||||
}, { maxRetries: 3 });
|
||||
|
||||
// 带回调
|
||||
await actionName.withCallback({
|
||||
param1: 'value1'
|
||||
}, {
|
||||
onProgress: (progress) => console.log(progress),
|
||||
onComplete: (result) => console.log('Done', result)
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: skill-generator Phase 3 (Autonomous 模式)
|
||||
2. **输入**: Phase 2 skill-config.json
|
||||
3. **输出**: actions/{action-name}.md
|
||||
4. **命名**: 使用动词-名词格式 (如 collect-context.md)
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
# Action: quick-scan
|
||||
|
||||
> **Skill**: review-code
|
||||
> **Action Type**: Analysis
|
||||
> **Estimated Duration**: 5 minutes
|
||||
|
||||
## Description
|
||||
|
||||
快速扫描目标代码，识别高风险区域，为深度审查提供焦点
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
| Condition | Description | Check Method |
|
||||
|-----------|-------------|--------------|
|
||||
| context_collected | 上下文收集完成 | state.context != null |
|
||||
| target_exists | 目标路径有效 | file exists check |
|
||||
|
||||
## Input Parameters
|
||||
|
||||
| Parameter | Type | Required | Description | Default |
|
||||
|-----------|------|----------|-------------|---------|
|
||||
| files | array | Yes | 要扫描的文件列表 | - |
|
||||
| dimensions | array | No | 要检查的维度 | ["all"] |
|
||||
| risk_threshold | number | No | 风险阈值 | 0.5 |
|
||||
|
||||
## Output
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| risk_areas | array | 高风险区域列表 |
|
||||
| scan_summary | object | 扫描摘要 |
|
||||
| recommendations | array | 建议的审查重点 |
|
||||
|
||||
## Execution Logic
|
||||
|
||||
### Step 1: 按文件类型分组
|
||||
|
||||
```typescript
|
||||
const groups = groupBy(files, f => f.extension);
|
||||
// ts/tsx -> TypeScript review rules
|
||||
// py -> Python review rules
|
||||
```
|
||||
|
||||
### Step 2: 应用快速检查规则
|
||||
|
||||
```typescript
|
||||
const risks = [];
|
||||
for (const file of files) {
|
||||
const fileRisks = applyQuickChecks(file);
|
||||
risks.push(...fileRisks);
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: 聚合和排序
|
||||
|
||||
```typescript
|
||||
const aggregated = aggregateByLocation(risks);
|
||||
const sorted = sortBySeverity(aggregated);
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Handling | Retry |
|
||||
|-------|-------|----------|-------|
|
||||
| FileAccessError | 文件无法读取 | 跳过文件，记录警告 | No |
|
||||
| ParseError | 代码解析失败 | 标记为需要人工审查 | No |
|
||||
|
||||
## Testing
|
||||
|
||||
| Case | Input | Expected Output |
|
||||
|------|-------|-----------------|
|
||||
| Normal | 10 files | risk_areas non-empty |
|
||||
| Empty | 0 files | risk_areas empty |
|
||||
| ParseError | Invalid code | Area marked for manual review |
|
||||
```
|
||||
311
docs/skills/templates/autonomous-orchestrator.md
Normal file
311
docs/skills/templates/autonomous-orchestrator.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Autonomous Orchestrator Template
|
||||
|
||||
> 用途: 自主编排器模板，用于 Autonomous 类型 Skill
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# Orchestrator
|
||||
|
||||
> **Skill**: {Skill Name}
|
||||
> **Type**: Autonomous (State-Driven)
|
||||
> **Version**: 1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
本编排器使用状态驱动的决策引擎，根据当前状态自动选择下一步行动。
|
||||
|
||||
## State Machine
|
||||
|
||||
### State Definition
|
||||
|
||||
| State | Description | Entry Condition | Exit Actions |
|
||||
|-------|-------------|-----------------|--------------|
|
||||
| `initialized` | 初始状态，等待目标 | Skill 启动 | 转到 `collecting_context` |
|
||||
| `collecting_context` | 收集上下文信息 | 进入状态 | 收集完成后转到 `analyzing` |
|
||||
| `analyzing` | 分析目标内容 | 上下文就绪 | 分析完成后转到 `planning` 或 `executing` |
|
||||
| `planning` | 制定执行计划 | 需要复杂规划 | 计划完成后转到 `executing` |
|
||||
| `executing` | 执行具体行动 | 计划就绪 | 执行完成后转到 `verifying` |
|
||||
| `verifying` | 验证执行结果 | 执行完成 | 验证通过转到 `completed`，否则转到 `analyzing` |
|
||||
| `completed` | 任务完成 | 所有目标达成 | 结束 |
|
||||
| `error` | 错误状态 | 发生错误 | 根据错误类型恢复或终止 |
|
||||
|
||||
### State Transitions
|
||||
|
||||
```plaintext
|
||||
┌─────────────────┐
|
||||
│ initialized │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│collecting_context│
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ analyzing │◄─────────┐
|
||||
└────────┬────────┘ │
|
||||
│ │
|
||||
┌────────┴────────┐ │
|
||||
│ │ │
|
||||
▼ ▼ │
|
||||
┌──────────┐ ┌──────────┐ │
|
||||
│ planning │ │executing │────┘
|
||||
└────┬─────┘ └────┬─────┘
|
||||
│ │
|
||||
│ ┌────────┴────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────────────────────┐
|
||||
│ verifying │
|
||||
└───────────┬──────────────────┘
|
||||
│
|
||||
┌─────────┴─────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────┐ ┌──────────┐
|
||||
│completed │ │ error │
|
||||
└──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
## Action Registry
|
||||
|
||||
### Available Actions
|
||||
|
||||
| Action | From States | To States | Description |
|
||||
|--------|------------|-----------|-------------|
|
||||
| `collect_context` | `initialized`, `error` | `analyzing` | 收集必要的上下文信息 |
|
||||
| `analyze_target` | `collecting_context` | `planning` or `executing` | 分析目标，决定需要规划还是直接执行 |
|
||||
| `create_plan` | `analyzing` | `executing` | 创建详细执行计划 |
|
||||
| `execute_action` | `planning`, `analyzing` | `verifying` | 执行具体行动 |
|
||||
| `verify_result` | `executing` | `completed` or `analyzing` | 验证执行结果 |
|
||||
| `handle_error` | Any | `error` or `analyzing` | 处理错误情况 |
|
||||
| `complete` | `verifying` | `completed` | 标记任务完成 |
|
||||
|
||||
## Routing Logic
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```typescript
|
||||
// 伪代码：状态路由决策
|
||||
function route(currentState: State, context: Context): Action {
|
||||
switch (currentState) {
|
||||
case 'initialized':
|
||||
return Action.COLLECT_CONTEXT;
|
||||
|
||||
case 'collecting_context':
|
||||
if (context.hasEnoughData()) {
|
||||
return Action.ANALYZE_TARGET;
|
||||
}
|
||||
return Action.COLLECT_CONTEXT; // 继续收集
|
||||
|
||||
case 'analyzing':
|
||||
if (context.needsPlanning()) {
|
||||
return Action.CREATE_PLAN;
|
||||
}
|
||||
return Action.EXECUTE_ACTION;
|
||||
|
||||
case 'planning':
|
||||
return Action.EXECUTE_ACTION;
|
||||
|
||||
case 'executing':
|
||||
return Action.VERIFY_RESULT;
|
||||
|
||||
case 'verifying':
|
||||
if (context.isResultValid()) {
|
||||
return Action.COMPLETE;
|
||||
}
|
||||
return Action.ANALYZE_TARGET; // 重新分析
|
||||
|
||||
case 'error':
|
||||
if (context.isRecoverable()) {
|
||||
return Action.ANALYZE_TARGET;
|
||||
}
|
||||
throw new UnrecoverableError(context.error);
|
||||
|
||||
default:
|
||||
throw new UnknownStateError(currentState);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Condition Evaluation
|
||||
|
||||
| Condition | Evaluation | Result |
|
||||
|-----------|------------|--------|
|
||||
| `hasEnoughData()` | context.files.length > 0 | Boolean |
|
||||
| `needsPlanning()` | context.complexity > threshold | Boolean |
|
||||
| `isResultValid()` | validation.checks passed | Boolean |
|
||||
| `isRecoverable()` | error.type in recoverableErrors | Boolean |
|
||||
|
||||
## State Persistence
|
||||
|
||||
### State File Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"state": "analyzing",
|
||||
"history": [
|
||||
{ "state": "initialized", "timestamp": "2026-03-01T10:00:00Z" },
|
||||
{ "state": "collecting_context", "timestamp": "2026-03-01T10:00:05Z" },
|
||||
{ "state": "analyzing", "timestamp": "2026-03-01T10:00:15Z" }
|
||||
],
|
||||
"context": {
|
||||
"target": "...",
|
||||
"files": [],
|
||||
"findings": []
|
||||
},
|
||||
"metrics": {
|
||||
"actionsExecuted": 3,
|
||||
"errors": 0,
|
||||
"startTime": "2026-03-01T10:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Save/Restore
|
||||
|
||||
- **Save**: 每次状态转换后保存
|
||||
- **Restore**: Skill 重启时从文件恢复
|
||||
- **Reset**: 新任务开始时重置状态
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Classification
|
||||
|
||||
| Error Type | Severity | Recovery |
|
||||
|------------|----------|----------|
|
||||
| `ContextError` | Medium | 重新收集上下文 |
|
||||
| `ValidationError` | High | 重新分析并调整 |
|
||||
| `ExecutionError` | High | 尝试替代行动 |
|
||||
| `FatalError` | Critical | 终止并报告 |
|
||||
|
||||
### Error Recovery Strategies
|
||||
|
||||
```typescript
|
||||
function handleError(error: Error, state: State): RecoveryAction {
|
||||
if (error instanceof ContextError) {
|
||||
return RecoveryAction.RETRY_WITH_ALTERNATIVE_SOURCE;
|
||||
}
|
||||
if (error instanceof ValidationError) {
|
||||
return RecoveryAction.ADJUST_AND_RETRY;
|
||||
}
|
||||
if (error instanceof ExecutionError) {
|
||||
return RecoveryAction.TRY_ALTERNATIVE_ACTION;
|
||||
}
|
||||
return RecoveryAction.ABORT;
|
||||
}
|
||||
```
|
||||
|
||||
## Metrics and Observability
|
||||
|
||||
### Tracked Metrics
|
||||
|
||||
| Metric | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `state_transitions` | Counter | 状态转换次数 |
|
||||
| `action_duration` | Histogram | 每个行动的执行时间 |
|
||||
| `error_count` | Counter | 错误发生次数 |
|
||||
| `completion_rate` | Gauge | 任务完成率 |
|
||||
|
||||
### Logging
|
||||
|
||||
```typescript
|
||||
// 每次状态转换记录日志
|
||||
log.info('State transition', {
|
||||
from: oldState,
|
||||
to: newState,
|
||||
action: executedAction,
|
||||
timestamp: now()
|
||||
});
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Scenarios
|
||||
|
||||
1. **Happy Path**: 正常流程从初始化到完成
|
||||
2. **Error Recovery**: 错误发生后正确恢复
|
||||
3. **State Persistence**: 状态正确保存和恢复
|
||||
4. **Edge Cases**: 边界条件处理
|
||||
|
||||
### Test Example
|
||||
|
||||
```typescript
|
||||
describe('Orchestrator', () => {
|
||||
it('should complete happy path', async () => {
|
||||
const orchestrator = new Orchestrator();
|
||||
await orchestrator.run({ target: 'test' });
|
||||
expect(orchestrator.state).toBe('completed');
|
||||
});
|
||||
|
||||
it('should recover from errors', async () => {
|
||||
const orchestrator = new Orchestrator();
|
||||
// 模拟错误后恢复
|
||||
await expect(orchestrator.run()).toEventuallyComplete();
|
||||
});
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: skill-generator Phase 3 (Autonomous 模式)
|
||||
2. **输入**: Phase 2 skill-config.json
|
||||
3. **输出**: phases/_orchestrator.md
|
||||
4. **验证**: 确保状态转换逻辑完整
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
# Orchestrator
|
||||
|
||||
> **Skill**: review-code
|
||||
> **Type**: Autonomous (State-Driven)
|
||||
> **Version**: 1.0.0
|
||||
|
||||
## State Transitions
|
||||
|
||||
```plaintext
|
||||
initialized → collecting_context → analyzing
|
||||
↓
|
||||
┌───────┴────────┐
|
||||
↓ ↓
|
||||
quick_scan deep_review
|
||||
↓ ↓
|
||||
└───────┬────────┘
|
||||
↓
|
||||
generating_report
|
||||
↓
|
||||
completed
|
||||
```
|
||||
|
||||
## Action Registry
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `collect_context` | 收集目标文件信息 |
|
||||
| `quick_scan` | 快速扫描识别高风险区域 |
|
||||
| `deep_review` | 按 6 维度深度审查 |
|
||||
| `generate_report` | 生成审查报告 |
|
||||
|
||||
## Routing Logic
|
||||
|
||||
```typescript
|
||||
function route(state, context) {
|
||||
if (state === 'initialized') return 'collect_context';
|
||||
if (state === 'collecting_context') return 'quick_scan';
|
||||
if (state === 'analyzing') {
|
||||
if (context.hasHighRiskAreas()) return 'deep_review';
|
||||
return 'generate_report';
|
||||
}
|
||||
if (state === 'deep_review') return 'generate_report';
|
||||
return 'complete';
|
||||
}
|
||||
```
|
||||
```
|
||||
311
docs/skills/templates/epics-template.md
Normal file
311
docs/skills/templates/epics-template.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Epics Template
|
||||
|
||||
> 用途: Epic 和 Story 文档模板，用于 spec-generator Phase 5 输出
|
||||
|
||||
## 模板
|
||||
|
||||
### _index.md 模板
|
||||
|
||||
```markdown
|
||||
# Epics - Index
|
||||
|
||||
> **Product**: {Product Name}
|
||||
> **Generated**: {YYYY-MM-DD}
|
||||
> **Session**: {session-id}
|
||||
|
||||
## Overview
|
||||
|
||||
Epic 概述（2-3 段）
|
||||
|
||||
## Epic Summary
|
||||
|
||||
| Epic | Title | Stories | Status | Priority |
|
||||
|------|-------|---------|--------|----------|
|
||||
| EPIC-001 | Epic 标题 | N stories | {Draft|Ready|In Progress} | {P0|P1|P2} |
|
||||
| EPIC-002 | Epic 标题 | N stories | {Draft|Ready|In Progress} | {P0|P1|P2} |
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
```plaintext
|
||||
EPIC-001 (Foundation)
|
||||
│
|
||||
├── EPIC-002 (Feature A)
|
||||
│ │
|
||||
│ └── EPIC-004 (Enhancement)
|
||||
│
|
||||
└── EPIC-003 (Feature B)
|
||||
```
|
||||
|
||||
## MVP Scope
|
||||
|
||||
以下 Epic 属于 MVP:
|
||||
- [ ] EPIC-001: {Epic title}
|
||||
- [ ] EPIC-002: {Epic title}
|
||||
- [ ] EPIC-003: {Epic title}
|
||||
|
||||
**Estimated MVP Duration**: {X weeks}
|
||||
|
||||
## Requirements Traceability
|
||||
|
||||
| Requirement | Epic(s) | Story Count |
|
||||
|-------------|---------|-------------|
|
||||
| REQ-001 | EPIC-001 | 3 |
|
||||
| REQ-002 | EPIC-001, EPIC-002 | 5 |
|
||||
|
||||
## Architecture Traceability
|
||||
|
||||
| ADR | Epic(s) | Component |
|
||||
|-----|---------|-----------|
|
||||
| ADR-001 | EPIC-001 | Service A |
|
||||
| ADR-002 | EPIC-002 | Service B |
|
||||
|
||||
## Epics
|
||||
|
||||
详见各 Epic 文档：
|
||||
- [EPIC-001-{title}](./EPIC-001-{slug}.md)
|
||||
- [EPIC-002-{title}](./EPIC-002-{slug}.md)
|
||||
|
||||
## Change Log
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | YYYY-MM-DD | Initial version |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### EPIC-*.md 模板
|
||||
|
||||
```markdown
|
||||
# EPIC-{NNN}: {Epic Title}
|
||||
|
||||
> **Priority**: {P0|P1|P2|P3}
|
||||
> **Status**: {Draft|Ready|In Progress|Done}
|
||||
> **MVP**: {Yes|No}
|
||||
> **Created**: {YYYY-MM-DD}
|
||||
|
||||
## Description
|
||||
|
||||
详细描述 Epic 的目标和范围
|
||||
|
||||
## Business Value
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| 业务价值1 | 描述 |
|
||||
| 业务价值2 | 描述 |
|
||||
|
||||
## Related Requirements
|
||||
|
||||
| Requirement | Relation |
|
||||
|-------------|----------|
|
||||
| REQ-001 | Addresses |
|
||||
| REQ-002 | Partially Addresses |
|
||||
|
||||
## Stories
|
||||
|
||||
| Story | Title | Points | Status |
|
||||
|-------|-------|--------|--------|
|
||||
| STORY-001 | Story 标题 | {points} | {Todo|In Progress|Done} |
|
||||
| STORY-002 | Story 标题 | {points} | {Todo|In Progress|Done} |
|
||||
|
||||
### STORY-001: {Story Title}
|
||||
|
||||
**As a** {user type},
|
||||
**I want** {action},
|
||||
**So that** {benefit}.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
- [ ] Criterion 3
|
||||
|
||||
**Technical Notes**:
|
||||
- Notes for developers
|
||||
- API endpoints, data models, etc.
|
||||
|
||||
**Dependencies**:
|
||||
- STORY-002 (must complete first)
|
||||
- External dependency description
|
||||
|
||||
---
|
||||
|
||||
### STORY-002: {Story Title}
|
||||
|
||||
... (same structure)
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Depends On | Type | Epic |
|
||||
|------------|------|------|
|
||||
| EPIC-XXX | Finish-to-Start | {epic title} |
|
||||
| External API | External | {description} |
|
||||
|
||||
## Estimate
|
||||
|
||||
| Category | Estimate |
|
||||
|----------|----------|
|
||||
| Development | {X days} |
|
||||
| Testing | {X days} |
|
||||
| Documentation | {X days} |
|
||||
| **Total** | **{X days}** |
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All stories completed and tested
|
||||
- [ ] Code reviewed
|
||||
- [ ] Documentation updated
|
||||
- [ ] Acceptance criteria met
|
||||
- [ ] No known bugs
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|------------|
|
||||
| Risk 1 | High/Low | 缓解措施 |
|
||||
| Risk 2 | High/Low | 缓解措施 |
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: spec-generator Phase 5
|
||||
2. **输入**: Phase 4 Architecture
|
||||
3. **输出**: epics/ 目录，包含 _index.md 和所有 Epic 文件
|
||||
4. **验证**: 确保追溯链接有效
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例 - _index.md
|
||||
|
||||
```markdown
|
||||
# Epics - Index
|
||||
|
||||
> **Product**: Real-Time Collaboration Platform
|
||||
> **Generated**: 2026-03-01
|
||||
> **Session**: SPEC-rtc-platform-2026-03-01
|
||||
|
||||
## Overview
|
||||
|
||||
本文档定义实时协作平台的 Epic 和 Story 分解。
|
||||
|
||||
## Epic Summary
|
||||
|
||||
| Epic | Title | Stories | Status | Priority |
|
||||
|------|-------|---------|--------|----------|
|
||||
| EPIC-001 | Core Sync Engine | 4 | Ready | P0 |
|
||||
| EPIC-002 | User Interface | 3 | Ready | P1 |
|
||||
| EPIC-003 | Conflict Resolution | 2 | Draft | P0 |
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
```plaintext
|
||||
EPIC-001 (Core Sync Engine)
|
||||
│
|
||||
├── EPIC-002 (User Interface)
|
||||
│
|
||||
└── EPIC-003 (Conflict Resolution)
|
||||
```
|
||||
|
||||
## MVP Scope
|
||||
|
||||
以下 Epic 属于 MVP:
|
||||
- [ ] EPIC-001: Core Sync Engine
|
||||
- [ ] EPIC-002: User Interface
|
||||
|
||||
**Estimated MVP Duration**: 6 weeks
|
||||
```
|
||||
|
||||
### 简化示例 - EPIC-001.md
|
||||
|
||||
```markdown
|
||||
# EPIC-001: Core Sync Engine
|
||||
|
||||
> **Priority**: P0
|
||||
> **Status**: Ready
|
||||
> **MVP**: Yes
|
||||
> **Created**: 2026-03-01
|
||||
|
||||
## Description
|
||||
|
||||
实现基于 OT 算法的实时文档同步引擎，支持多用户并发编辑。
|
||||
|
||||
## Business Value
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| 无缝协作 | 用户可同时编辑而无需担心冲突 |
|
||||
| 数据安全 | 自动保存，防止数据丢失 |
|
||||
|
||||
## Related Requirements
|
||||
|
||||
| Requirement | Relation |
|
||||
|-------------|----------|
|
||||
| REQ-001 | Addresses |
|
||||
| NFR-PERF-001 | Must satisfy |
|
||||
|
||||
## Stories
|
||||
|
||||
| Story | Title | Points | Status |
|
||||
|-------|-------|--------|--------|
|
||||
| STORY-001 | WebSocket Connection | 5 | Todo |
|
||||
| STORY-002 | Operation Transformer | 8 | Todo |
|
||||
| STORY-003 | State Persistence | 3 | Todo |
|
||||
| STORY-004 | Conflict Resolution | 5 | Todo |
|
||||
|
||||
### STORY-001: WebSocket Connection
|
||||
|
||||
**As a** system,
|
||||
**I want** to establish WebSocket connections,
|
||||
**So that** clients can receive real-time updates.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Server accepts WebSocket connections
|
||||
- [ ] Connection authentication implemented
|
||||
- [ ] Reconnection logic handles network issues
|
||||
|
||||
**Technical Notes**:
|
||||
- Use ws library for Node.js
|
||||
- Implement JWT-based authentication
|
||||
- Store active connections in memory
|
||||
|
||||
**Dependencies**:
|
||||
- None
|
||||
|
||||
---
|
||||
|
||||
### STORY-002: Operation Transformer
|
||||
|
||||
**As a** system,
|
||||
**I want** to transform concurrent operations,
|
||||
**So that** conflicts are automatically resolved.
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] OT transform function implemented
|
||||
- [ ] Handles insert and delete operations
|
||||
- [ ] Maintains document consistency
|
||||
|
||||
**Technical Notes**:
|
||||
- Use Yjs library for OT implementation
|
||||
- Implement transform() function per OT spec
|
||||
|
||||
**Dependencies**:
|
||||
- STORY-001 must complete first
|
||||
|
||||
## Estimate
|
||||
|
||||
| Category | Estimate |
|
||||
|----------|----------|
|
||||
| Development | 10 days |
|
||||
| Testing | 5 days |
|
||||
| Documentation | 2 days |
|
||||
| **Total** | **17 days** |
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All stories completed and tested
|
||||
- [ ] Unit tests coverage > 80%
|
||||
- [ ] API documentation complete
|
||||
- [ ] Performance benchmarks meet NFR-PERF-001
|
||||
```
|
||||
295
docs/skills/templates/issue-template.md
Normal file
295
docs/skills/templates/issue-template.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# Issue Template
|
||||
|
||||
> 用途: Issue 记录模板，用于代码审查和问题追踪
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
### [{Severity}] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Category**: {Correctness|Readability|Performance|Security|Testing|Architecture}
|
||||
**Dimension**: {Dimension Name}
|
||||
|
||||
#### Issue Description
|
||||
|
||||
{Detailed description of the issue, 1-3 sentences}
|
||||
|
||||
#### Current Code
|
||||
|
||||
```typescript
|
||||
// {file-path}:{line}
|
||||
{current code snippet}
|
||||
```
|
||||
|
||||
#### Severity
|
||||
|
||||
{Critical|High|Medium|Low|Info} - {为什么是这个严重性的理由}
|
||||
|
||||
#### Recommendation
|
||||
|
||||
```typescript
|
||||
// Suggested fix
|
||||
{fixed code snippet}
|
||||
```
|
||||
|
||||
**Explanation**: {解释为什么这样修复}
|
||||
|
||||
#### Impact
|
||||
|
||||
- **Breaks**: {什么功能会受影响}
|
||||
- **Risk**: {风险等级}
|
||||
- **Users Affected**: {受影响的用户范围}
|
||||
|
||||
#### Effort
|
||||
|
||||
- **Complexity**: {Low|Medium|High}
|
||||
- **Estimated Time**: {X hours/days}
|
||||
- **Files to Change**: {N files}
|
||||
|
||||
#### Related
|
||||
|
||||
- **Requirement**: {REQ-XXX} (if applicable)
|
||||
- **ADR**: {ADR-XXX} (if applicable)
|
||||
- **Similar Issues**: {link to similar issues}
|
||||
|
||||
---
|
||||
|
||||
**Tags**: {tag1}, {tag2}, {tag3}
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: 任何问题记录场景
|
||||
2. **输入**: 问题发现时的上下文
|
||||
3. **输出**: 结构化 issue 记录
|
||||
4. **位置**: 可在审查报告、Issue 追踪系统等使用
|
||||
|
||||
---
|
||||
|
||||
## 变体
|
||||
|
||||
### 简化变体 (用于快速记录)
|
||||
|
||||
```markdown
|
||||
### [{Severity}] {Title}
|
||||
|
||||
**Location**: `{file}:{line}`
|
||||
**Category**: {category}
|
||||
|
||||
{Brief description}
|
||||
|
||||
**Fix**:
|
||||
```typescript
|
||||
// Before
|
||||
{code}
|
||||
|
||||
// After
|
||||
{fix}
|
||||
```
|
||||
```
|
||||
|
||||
### 安全 Issue 变体
|
||||
|
||||
```markdown
|
||||
### [{Severity}] Security: {Title}
|
||||
|
||||
**Location**: `{file}:{line}`
|
||||
**CVSS**: {score}
|
||||
**CWE**: {CWE-ID}
|
||||
|
||||
**Vulnerability**: {漏洞描述}
|
||||
|
||||
**Exploit Scenario**: {攻击场景}
|
||||
|
||||
**Mitigation**:
|
||||
```typescript
|
||||
{修复代码}
|
||||
```
|
||||
|
||||
**References**:
|
||||
- {OWASP link}
|
||||
- {CVE link}
|
||||
```
|
||||
|
||||
### 性能 Issue 变体
|
||||
|
||||
```markdown
|
||||
### [{Severity}] Performance: {Title}
|
||||
|
||||
**Location**: `{file}:{line}`
|
||||
**Complexity**: {O(n) / O(n²) / etc.}
|
||||
|
||||
**Current Performance**: {当前性能指标}
|
||||
**Target Performance**: {目标性能指标}
|
||||
|
||||
**Bottleneck**: {瓶颈描述}
|
||||
|
||||
**Optimization**:
|
||||
```typescript
|
||||
{优化代码}
|
||||
```
|
||||
|
||||
**Expected Improvement**: {预期改进}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 完整示例
|
||||
|
||||
```markdown
|
||||
### [C] SQL Injection Vulnerability
|
||||
|
||||
**Location**: `src/auth/login.ts:45`
|
||||
**Category**: Security
|
||||
**Dimension**: Security
|
||||
|
||||
#### Issue Description
|
||||
|
||||
User input is directly concatenated into SQL query without sanitization,
|
||||
allowing attackers to inject arbitrary SQL commands.
|
||||
|
||||
#### Current Code
|
||||
|
||||
```typescript
|
||||
// src/auth/login.ts:45
|
||||
const userId = req.params.id;
|
||||
const query = `SELECT * FROM users WHERE id='${userId}'`;
|
||||
const result = await db.query(query);
|
||||
```
|
||||
|
||||
#### Severity
|
||||
|
||||
Critical - Allows unauthorized data access and potential data breach
|
||||
|
||||
#### Recommendation
|
||||
|
||||
```typescript
|
||||
// Use parameterized query
|
||||
const userId = req.params.id;
|
||||
const query = 'SELECT * FROM users WHERE id = ?';
|
||||
const result = await db.query(query, [userId]);
|
||||
```
|
||||
|
||||
**Explanation**: Parameterized queries prevent SQL injection by separating
|
||||
SQL logic from data. The database driver properly escapes the parameter.
|
||||
|
||||
#### Impact
|
||||
|
||||
- **Breaks**: User authentication, data integrity
|
||||
- **Risk**: Data breach, unauthorized access
|
||||
- **Users Affected**: All users
|
||||
|
||||
#### Effort
|
||||
|
||||
- **Complexity**: Low
|
||||
- **Estimated Time**: 1 hour
|
||||
- **Files to Change**: 3 files (all query locations)
|
||||
|
||||
#### Related
|
||||
|
||||
- **Requirement**: NFR-SEC-001
|
||||
- **ADR**: ADR-002 (Security Standards)
|
||||
- **Similar Issues**: None in this codebase
|
||||
|
||||
---
|
||||
|
||||
**Tags**: security, sql-injection, critical, authentication
|
||||
```
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
### [M] Long Function
|
||||
|
||||
**Location**: `src/utils/data.ts:123`
|
||||
**Category**: Readability
|
||||
|
||||
Function `processUserData` is 120 lines long, handles too many responsibilities.
|
||||
|
||||
**Fix**:
|
||||
```typescript
|
||||
// Before: One big function
|
||||
function processUserData(user) {
|
||||
// 120 lines...
|
||||
}
|
||||
|
||||
// After: Split into smaller functions
|
||||
function processUserData(user) {
|
||||
validateUser(user);
|
||||
enrichUserData(user);
|
||||
saveUser(user);
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### 安全 Issue 示例
|
||||
|
||||
```markdown
|
||||
### [C] Hardcoded API Key
|
||||
|
||||
**Location**: `src/config/api.ts:10`
|
||||
**CVSS**: 7.5 (High)
|
||||
**CWE**: 798
|
||||
|
||||
**Vulnerability**: API key is hardcoded in source code and will be exposed
|
||||
in version control.
|
||||
|
||||
**Exploit Scenario**: Anyone with repository access can extract the API key
|
||||
and make unauthorized API calls.
|
||||
|
||||
**Mitigation**:
|
||||
```typescript
|
||||
// Before
|
||||
const API_KEY = 'sk-1234567890abcdef';
|
||||
|
||||
// After
|
||||
const API_KEY = process.env.API_KEY || throw new Error('API_KEY required');
|
||||
```
|
||||
|
||||
**References**:
|
||||
- OWASP: https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_cryptographic_key
|
||||
- CWE-798: https://cwe.mitre.org/data/definitions/798.html
|
||||
```
|
||||
|
||||
### 性能 Issue 示例
|
||||
|
||||
```markdown
|
||||
### [H] Nested Loop Performance
|
||||
|
||||
**Location**: `src/processing/analyzer.ts:67`
|
||||
**Complexity**: O(n²)
|
||||
|
||||
**Current Performance**: Processing 10k items takes ~5 seconds
|
||||
**Target Performance**: Should be < 1 second
|
||||
|
||||
**Bottleneck**: Nested loop comparing every item with every other item.
|
||||
|
||||
**Optimization**:
|
||||
```typescript
|
||||
// Before: O(n²)
|
||||
for (let i = 0; i < items.length; i++) {
|
||||
for (let j = i + 1; j < items.length; j++) {
|
||||
if (compare(items[i], items[j])) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// After: O(n) using Map
|
||||
const map = new Map();
|
||||
for (const item of items) {
|
||||
const key = item.category;
|
||||
if (!map.has(key)) {
|
||||
map.set(key, []);
|
||||
}
|
||||
map.get(key).push(item);
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Improvement**: ~100x faster for large datasets
|
||||
```
|
||||
```
|
||||
160
docs/skills/templates/product-brief.md
Normal file
160
docs/skills/templates/product-brief.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Product Brief Template
|
||||
|
||||
> 用途: 产品简介文档模板，用于 spec-generator Phase 2 输出
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# {Product Name} - Product Brief
|
||||
|
||||
> **Generated**: {YYYY-MM-DD}
|
||||
> **Source**: spec-generator Phase 2
|
||||
> **Session**: {session-id}
|
||||
|
||||
## One-Liner
|
||||
|
||||
**简短描述** — 详细说明
|
||||
|
||||
## Problem Statement
|
||||
|
||||
### Pain Points
|
||||
|
||||
| Pain Point | Current State | Impact | Solution |
|
||||
|------------|---------------|--------|----------|
|
||||
| Pain Point 1 | 当前问题描述 | 影响程度 | 解决方案概述 |
|
||||
| Pain Point 2 | 当前问题描述 | 影响程度 | 解决方案概述 |
|
||||
| Pain Point 3 | 当前问题描述 | 影响程度 | 解决方案概述 |
|
||||
|
||||
## Target Audience
|
||||
|
||||
### Primary Users
|
||||
|
||||
| User Type | Description | Key Needs |
|
||||
|-----------|-------------|-----------|
|
||||
| 用户类型1 | 描述 | 核心需求 |
|
||||
| 用户类型2 | 描述 | 核心需求 |
|
||||
|
||||
### Secondary Users
|
||||
|
||||
| User Type | Description | Key Needs |
|
||||
|-----------|-------------|-----------|
|
||||
| 用户类型 | 描述 | 核心需求 |
|
||||
|
||||
## Solution Overview
|
||||
|
||||
### Core Value Proposition
|
||||
|
||||
一句话描述核心价值主张
|
||||
|
||||
### Key Features
|
||||
|
||||
| Feature | Description | Priority |
|
||||
|---------|-------------|----------|
|
||||
| Feature 1 | 功能描述 | Must/Should/Could |
|
||||
| Feature 2 | 功能描述 | Must/Should/Could |
|
||||
| Feature 3 | 功能描述 | Must/Should/Could |
|
||||
|
||||
## MoSCoW Analysis
|
||||
|
||||
| Category | Features | Rationale |
|
||||
|----------|----------|-----------|
|
||||
| **Must Have** | Feature 1, Feature 2 | 核心功能，必须实现 |
|
||||
| **Should Have** | Feature 3, Feature 4 | 重要功能，尽快实现 |
|
||||
| **Could Have** | Feature 5 | 有价值的功能，时间允许时实现 |
|
||||
| **Won't Have** | Feature 6 | 明确不实现的功能 |
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Target | Measurement Method |
|
||||
|--------|--------|-------------------|
|
||||
| 指标1 | 目标值 | 测量方法 |
|
||||
| 指标2 | 目标值 | 测量方法 |
|
||||
| 指标3 | 目标值 | 测量方法 |
|
||||
|
||||
## Feasibility Assessment
|
||||
|
||||
### Technical Feasibility
|
||||
|
||||
- **技术栈**: {技术栈选择}
|
||||
- **复杂度**: {高/中/低}
|
||||
- **风险**: {主要技术风险}
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
| Resource | Estimate | Notes |
|
||||
|----------|----------|-------|
|
||||
| 开发时间 | {estimate} | |
|
||||
| 测试时间 | {estimate} | |
|
||||
| 其他资源 | {estimate} | |
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. [ ] Review and approve Product Brief
|
||||
2. [ ] Proceed to Requirements (PRD) phase
|
||||
3. [ ] Conduct technical feasibility study
|
||||
|
||||
## References
|
||||
|
||||
- [Discovery Context](../discovery-context.json)
|
||||
- [Session Config](../spec-config.json)
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: spec-generator Phase 2
|
||||
2. **输入**: Phase 1 Discovery 结果 + 多 CLI 分析结果
|
||||
3. **输出**: product-brief.md
|
||||
4. **验证**: 确保所有必需字段填充完整
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
# Real-Time Collaboration Platform - Product Brief
|
||||
|
||||
> **Generated**: 2026-03-01
|
||||
> **Session**: SPEC-rtc-platform-2026-03-01
|
||||
|
||||
## One-Liner
|
||||
|
||||
**实时协作平台** — 让团队成员能够同时编辑文档并进行实时沟通
|
||||
|
||||
## Problem Statement
|
||||
|
||||
### Pain Points
|
||||
|
||||
| Pain Point | Current State | Impact | Solution |
|
||||
|------------|---------------|--------|----------|
|
||||
| 版本冲突 | 多人编辑同一文件时产生冲突 | 降低效率 | OT 算法自动合并 |
|
||||
| 沟通割裂 | 编辑和沟通在不同工具间切换 | 上下文丢失 | 内嵌即时通讯 |
|
||||
| 状态不明 | 不知道谁在编辑什么 | 协作混乱 | 实时光标显示 |
|
||||
|
||||
## Target Audience
|
||||
|
||||
### Primary Users
|
||||
|
||||
| User Type | Description | Key Needs |
|
||||
|-----------|-------------|-----------|
|
||||
| 内容团队 | 需要协作编辑文档的团队 | 实时同步、冲突解决 |
|
||||
| 开发团队 | 需要协作编写代码的团队 | 代码合并、审查 |
|
||||
|
||||
## MoSCoW Analysis
|
||||
|
||||
| Category | Features | Rationale |
|
||||
|----------|----------|-----------|
|
||||
| **Must Have** | 实时编辑、冲突解决、用户在线状态 | 核心功能 |
|
||||
| **Should Have** | 评论系统、版本历史、权限管理 | 重要功能 |
|
||||
| **Could Have** | AI 辅助编辑、模板系统 | 增值功能 |
|
||||
| **Won't Have** | 视频通话（使用现有工具） | 非核心 |
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Target | Measurement Method |
|
||||
|--------|--------|-------------------|
|
||||
| 冲突自动解决率 | >95% | 系统日志统计 |
|
||||
| 实时延迟 | <200ms | 性能监控 |
|
||||
| 用户活跃度 | 日活 >1000 | 分析平台 |
|
||||
```
|
||||
262
docs/skills/templates/requirements-prd.md
Normal file
262
docs/skills/templates/requirements-prd.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Requirements PRD Template
|
||||
|
||||
> 用途: 产品需求文档模板，用于 spec-generator Phase 3 输出
|
||||
|
||||
## 模板
|
||||
|
||||
### _index.md 模板
|
||||
|
||||
```markdown
|
||||
# Requirements (PRD) - Index
|
||||
|
||||
> **Product**: {Product Name}
|
||||
> **Generated**: {YYYY-MM-DD}
|
||||
> **Session**: {session-id}
|
||||
|
||||
## Overview
|
||||
|
||||
产品需求概述（2-3 段）
|
||||
|
||||
## Requirements Summary
|
||||
|
||||
| Category | Count | Status |
|
||||
|----------|-------|--------|
|
||||
| Functional Requirements | {N} | |
|
||||
| Non-Functional Requirements | {N} | |
|
||||
|
||||
## MoSCoW Summary
|
||||
|
||||
| Category | Count | Items |
|
||||
|----------|-------|-------|
|
||||
| Must | {N} | REQ-001, REQ-002, ... |
|
||||
| Should | {N} | REQ-003, REQ-004, ... |
|
||||
| Could | {N} | REQ-005, ... |
|
||||
|
||||
## Requirements Traceability
|
||||
|
||||
### From Product Brief
|
||||
|
||||
| Brief Feature | Requirement(s) |
|
||||
|---------------|----------------|
|
||||
| Feature 1 | REQ-001, REQ-002 |
|
||||
| Feature 2 | REQ-003 |
|
||||
|
||||
### To Architecture
|
||||
|
||||
| Requirement | ADR |
|
||||
|-------------|-----|
|
||||
| REQ-001 | ADR-001 |
|
||||
| REQ-002 | ADR-002 |
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
详见各需求文档：
|
||||
- [REQ-001-{title}](./REQ-001-{slug}.md)
|
||||
- [REQ-002-{title}](./REQ-002-{slug}.md)
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
详见各 NFR 文档：
|
||||
- [NFR-PERF-001](./NFR-PERF-001.md)
|
||||
- [NFR-SEC-001](./NFR-SEC-001.md)
|
||||
|
||||
## Change Log
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | YYYY-MM-DD | Initial version |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### REQ-*.md 模板
|
||||
|
||||
```markdown
|
||||
# REQ-{NNN}: {Requirement Title}
|
||||
|
||||
> **Type**: Functional Requirement
|
||||
> **Priority**: {Must|Should|Could}
|
||||
> **Status**: {Draft|Approved|Implemented}
|
||||
> **Created**: {YYYY-MM-DD}
|
||||
|
||||
## Description
|
||||
|
||||
详细描述需求内容
|
||||
|
||||
## User Story
|
||||
|
||||
**As a** {user type},
|
||||
**I want** {action/feature},
|
||||
**So that** {benefit/value}.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
- [ ] Criterion 3
|
||||
|
||||
## Functional Specifications
|
||||
|
||||
### Input
|
||||
|
||||
| Input | Type | Description | Validation |
|
||||
|-------|------|-------------|------------|
|
||||
| input1 | type | 描述 | 验证规则 |
|
||||
|
||||
### Output
|
||||
|
||||
| Output | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| output1 | type | 描述 |
|
||||
|
||||
### Business Rules
|
||||
|
||||
1. Rule 1
|
||||
2. Rule 2
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Type | Status |
|
||||
|------------|------|--------|
|
||||
| REQ-XXX | Functional | |
|
||||
| NFR-XXX | Non-Functional | |
|
||||
|
||||
## References
|
||||
|
||||
- [Product Brief](../product-brief.md) - Related Feature
|
||||
- [ADR-XXX](../architecture/ADR-XXX.md) - Technical Decision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### NFR-*.md 模板
|
||||
|
||||
```markdown
|
||||
# NFR-{TYPE}-{NNN}: {Non-Functional Requirement Title}
|
||||
|
||||
> **Type**: {Performance|Security|Scalability|Reliability|Usability}
|
||||
> **Priority**: {Must|Should|Could}
|
||||
> **Status**: {Draft|Approved}
|
||||
> **Created**: {YYYY-MM-DD}
|
||||
|
||||
## Description
|
||||
|
||||
详细描述非功能需求
|
||||
|
||||
## Metrics
|
||||
|
||||
| Metric | Target | Measurement Method |
|
||||
|--------|--------|-------------------|
|
||||
| metric1 | value | 测量方法 |
|
||||
| metric2 | value | 测量方法 |
|
||||
|
||||
## Specifications
|
||||
|
||||
### {Type} Requirements
|
||||
|
||||
1. Requirement 1
|
||||
2. Requirement 2
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- Test 1: Description
|
||||
- Test 2: Description
|
||||
|
||||
## Related Requirements
|
||||
|
||||
| Requirement | Relation |
|
||||
|-------------|----------|
|
||||
| REQ-001 | Impacts |
|
||||
| REQ-002 | Enables |
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: spec-generator Phase 3
|
||||
2. **输入**: Phase 2 Product Brief
|
||||
3. **输出**: requirements/ 目录，包含 _index.md 和所有需求文件
|
||||
4. **验证**: 确保追溯链接有效
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例 - _index.md
|
||||
|
||||
```markdown
|
||||
# Requirements (PRD) - Index
|
||||
|
||||
> **Product**: Real-Time Collaboration Platform
|
||||
> **Generated**: 2026-03-01
|
||||
> **Session**: SPEC-rtc-platform-2026-03-01
|
||||
|
||||
## Overview
|
||||
|
||||
本文档包含实时协作平台的完整需求规格说明。
|
||||
|
||||
## Requirements Summary
|
||||
|
||||
| Category | Count | Status |
|
||||
|----------|-------|--------|
|
||||
| Functional Requirements | 8 | Draft |
|
||||
| Non-Functional Requirements | 3 | Draft |
|
||||
|
||||
## MoSCoW Summary
|
||||
|
||||
| Category | Count | Items |
|
||||
|----------|-------|-------|
|
||||
| Must | 4 | REQ-001, REQ-002, REQ-003, REQ-004 |
|
||||
| Should | 3 | REQ-005, REQ-006, REQ-007 |
|
||||
| Could | 1 | REQ-008 |
|
||||
```
|
||||
|
||||
### 简化示例 - REQ-001.md
|
||||
|
||||
```markdown
|
||||
# REQ-001: Real-Time Document Sync
|
||||
|
||||
> **Type**: Functional Requirement
|
||||
> **Priority**: Must
|
||||
> **Status**: Draft
|
||||
> **Created**: 2026-03-01
|
||||
|
||||
## Description
|
||||
|
||||
用户编辑文档时，更改应实时同步到所有协作者
|
||||
|
||||
## User Story
|
||||
|
||||
**As a** content editor,
|
||||
**I want** to see others' changes in real-time,
|
||||
**So that** we can collaborate without conflicts.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Changes sync within 200ms
|
||||
- [ ] Multiple users can edit simultaneously
|
||||
- [ ] Conflicts are auto-resolved using OT algorithm
|
||||
- [ ] User cursors are visible to others
|
||||
|
||||
## Functional Specifications
|
||||
|
||||
### Input
|
||||
|
||||
| Input | Type | Description | Validation |
|
||||
|-------|------|-------------|------------|
|
||||
| document_id | string | Document identifier | Required, valid UUID |
|
||||
| operations | array | OT operations | Required, non-empty |
|
||||
|
||||
### Output
|
||||
|
||||
| Output | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| status | string | "synced" or "conflict" |
|
||||
| merged_ops | array | Merged operations |
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Type | Status |
|
||||
|------------|------|--------|
|
||||
| NFR-PERF-001 | Performance | |
|
||||
| ADR-001 | OT Algorithm Choice | |
|
||||
```
|
||||
382
docs/skills/templates/review-report.md
Normal file
382
docs/skills/templates/review-report.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# Review Report Template
|
||||
|
||||
> 用途: 代码审查报告模板，用于 review-code 输出
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# Code Review Report
|
||||
|
||||
> **Target**: {target-path}
|
||||
> **Generated**: {YYYY-MM-DD HH:MM}
|
||||
> **Reviewer**: {skill-name}
|
||||
> **Session**: {session-id}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| **Overall Score** | {X/100} |
|
||||
| Files Reviewed | {N} |
|
||||
| Total Issues | {N} |
|
||||
| Critical | {N} |
|
||||
| High | {N} |
|
||||
| Medium | {N} |
|
||||
| Low | {N} |
|
||||
|
||||
### Quality Grade
|
||||
|
||||
{A/B/C/D}
|
||||
|
||||
**Rationale**: 简要说明评分理由
|
||||
|
||||
---
|
||||
|
||||
## Dimensions Summary
|
||||
|
||||
| Dimension | Score | Issues | Top Issues |
|
||||
|-----------|-------|--------|------------|
|
||||
| Correctness | {X/10} | {N} | [C] Issue 1, [H] Issue 2 |
|
||||
| Readability | {X/10} | {N} | [M] Issue 3 |
|
||||
| Performance | {X/10} | {N} | [H] Issue 4 |
|
||||
| Security | {X/10} | {N} | [C] Issue 5 |
|
||||
| Testing | {X/10} | {N} | [L] Issue 6 |
|
||||
| Architecture | {X/10} | {N} | [M] Issue 7 |
|
||||
|
||||
---
|
||||
|
||||
## Risk Areas Identified
|
||||
|
||||
| Area | Risk Level | Files | Issues |
|
||||
|------|------------|-------|--------|
|
||||
| {area1} | {High/Medium/Low} | {file list} | {N} issues |
|
||||
| {area2} | {High/Medium/Low} | {file list} | {N} issues |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### Correctness: {X/10}
|
||||
|
||||
**Summary**: 简要总结正确性方面的发现
|
||||
|
||||
#### [C] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述（1-2 句话）
|
||||
|
||||
**Severity**: Critical - 必须修复
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Before (problematic)
|
||||
const code = "problematic code";
|
||||
|
||||
// After (fixed)
|
||||
const code = "fixed code";
|
||||
```
|
||||
|
||||
**Reference**: [specs/review-dimensions.md](specs/review-dimensions.md) - Correctness section
|
||||
|
||||
---
|
||||
|
||||
#### [H] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述
|
||||
|
||||
**Severity**: High - 应该修复
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Fix suggestion
|
||||
const fixedCode = "fixed code";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Readability: {X/10}
|
||||
|
||||
**Summary**: 简要总结可读性方面的发现
|
||||
|
||||
#### [M] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述
|
||||
|
||||
**Severity**: Medium - 建议改进
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Suggestion
|
||||
const betterCode = "more readable code";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Performance: {X/10}
|
||||
|
||||
**Summary**: 简要总结性能方面的发现
|
||||
|
||||
#### [H] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述
|
||||
|
||||
**Severity**: High - 影响性能
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Optimization
|
||||
const optimizedCode = "optimized code";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Security: {X/10}
|
||||
|
||||
**Summary**: 简要总结安全方面的发现
|
||||
|
||||
#### [C] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述
|
||||
|
||||
**Severity**: Critical - 安全风险
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Security fix
|
||||
const secureCode = "secure code";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Testing: {X/10}
|
||||
|
||||
**Summary**: 简要总结测试方面的发现
|
||||
|
||||
#### [L] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述
|
||||
|
||||
**Severity**: Low - 建议添加测试
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Test example
|
||||
describe('Function', () => {
|
||||
it('should handle edge case', () => {
|
||||
// test code
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Architecture: {X/10}
|
||||
|
||||
**Summary**: 简要总结架构方面的发现
|
||||
|
||||
#### [M] {Issue Title}
|
||||
|
||||
**Location**: `{file-path}:{line}`
|
||||
|
||||
**Issue**: 问题描述
|
||||
|
||||
**Severity**: Medium - 架构改进建议
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Architecture suggestion
|
||||
// Consider using {pattern} instead
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Priority Actions (Do First)
|
||||
|
||||
1. **[Critical] Fix security vulnerability in {file}:{line}**
|
||||
- Action: 修复 SQL 注入风险
|
||||
- Estimate: 1 hour
|
||||
|
||||
2. **[Critical] Handle null pointer in {file}:{line}**
|
||||
- Action: 添加空检查
|
||||
- Estimate: 30 minutes
|
||||
|
||||
### High Priority (Do Soon)
|
||||
|
||||
3. **[High] Optimize performance bottleneck in {file}:{line}**
|
||||
- Action: 重构算法
|
||||
- Estimate: 2 hours
|
||||
|
||||
### Medium Priority (Do When Possible)
|
||||
|
||||
4. **[Medium] Improve code readability in {file}:{line}**
|
||||
- Action: 重构函数
|
||||
- Estimate: 1 hour
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Files Reviewed
|
||||
|
||||
| File | Lines | Issues | Score |
|
||||
|------|-------|--------|-------|
|
||||
| {file1} | {N} | {N} | {X/10} |
|
||||
| {file2} | {N} | {N} | {X/10} |
|
||||
| {file3} | {N} | {N} | {X/10} |
|
||||
|
||||
### Issue Distribution
|
||||
|
||||
```
|
||||
Critical: ████ 4
|
||||
High: ████████ 8
|
||||
Medium: ████████████ 12
|
||||
Low: ██████ 6
|
||||
```
|
||||
|
||||
### Review Metadata
|
||||
|
||||
| Key | Value |
|
||||
|-----|-------|
|
||||
| Review Duration | {X minutes} |
|
||||
| Review Method | {Quick Scan + Deep Review} |
|
||||
| Dimensions Covered | {All / Specific} |
|
||||
| Review Configuration | {config details} |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review this report**: 确认所有问题理解正确
|
||||
2. **Fix Critical issues**: 优先修复高风险问题
|
||||
3. **Run review-cycle**: 使用 `/review-cycle` 自动修复和验证
|
||||
4. **Re-review**: 修复后重新审查确认
|
||||
|
||||
---
|
||||
|
||||
**Generated by**: {skill-name} v{version}
|
||||
**Review Standards**: [specs/review-dimensions.md](specs/review-dimensions.md)
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: review-code Phase 4
|
||||
2. **输入**: Phase 3 的 findings 数据
|
||||
3. **输出**: review-report.md
|
||||
4. **格式**: Markdown，支持 GitHub/GitLab 渲染
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
# Code Review Report
|
||||
|
||||
> **Target**: src/auth/**
|
||||
> **Generated**: 2026-03-01 10:30
|
||||
> **Reviewer**: review-code
|
||||
|
||||
## Executive Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| **Overall Score** | 65/100 |
|
||||
| Files Reviewed | 5 |
|
||||
| Total Issues | 15 |
|
||||
| Critical | 2 |
|
||||
| High | 4 |
|
||||
| Medium | 6 |
|
||||
| Low | 3 |
|
||||
|
||||
### Quality Grade
|
||||
|
||||
**C - Needs Improvement**
|
||||
|
||||
存在 2 个严重安全问题需要立即修复
|
||||
|
||||
---
|
||||
|
||||
## Dimensions Summary
|
||||
|
||||
| Dimension | Score | Issues |
|
||||
|-----------|-------|--------|
|
||||
| Correctness | 6/10 | 3 |
|
||||
| Readability | 7/10 | 2 |
|
||||
| Performance | 7/10 | 2 |
|
||||
| Security | 4/10 | 4 |
|
||||
| Testing | 5/10 | 2 |
|
||||
| Architecture | 6/10 | 2 |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### Security: 4/10
|
||||
|
||||
#### [C] SQL Injection Risk
|
||||
|
||||
**Location**: `src/auth/login.ts:45`
|
||||
|
||||
**Issue**: 用户输入直接拼接 SQL，可被注入攻击
|
||||
|
||||
**Severity**: Critical - 必须修复
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Before (vulnerable)
|
||||
const query = `SELECT * FROM users WHERE id='${userId}'`;
|
||||
|
||||
// After (safe)
|
||||
const query = 'SELECT * FROM users WHERE id = ?';
|
||||
await db.query(query, [userId]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Correctness: 6/10
|
||||
|
||||
#### [H] Null Pointer Risk
|
||||
|
||||
**Location**: `src/auth/user.ts:23`
|
||||
|
||||
**Issue**: user 对象可能为 null
|
||||
|
||||
**Severity**: High - 可能导致崩溃
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Add null check
|
||||
if (user?.profile) {
|
||||
return user.profile.name;
|
||||
}
|
||||
return 'Anonymous';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Priority Actions
|
||||
|
||||
1. **[Critical] Fix SQL injection in login.ts:45**
|
||||
- Use parameterized queries
|
||||
- Estimate: 1 hour
|
||||
|
||||
2. **[Critical] Add null check in user.ts:23**
|
||||
- Add optional chaining
|
||||
- Estimate: 15 minutes
|
||||
```
|
||||
218
docs/skills/templates/sequential-phase.md
Normal file
218
docs/skills/templates/sequential-phase.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# Sequential Phase Template
|
||||
|
||||
> 用途: 顺序执行阶段的模板，用于 Sequential 类型 Skill
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# Phase {N}: {Phase Name}
|
||||
|
||||
> **Skill**: {Skill Name}
|
||||
> **Phase Number**: {N}
|
||||
> **Execution Mode**: Sequential
|
||||
> **Estimated Duration**: {X minutes}
|
||||
|
||||
## Objective
|
||||
|
||||
本阶段的目标描述（1-2 句话）
|
||||
|
||||
## Prerequisites
|
||||
|
||||
在执行本阶段之前，必须满足以下条件：
|
||||
|
||||
- [ ] Prerequisite 1
|
||||
- [ ] Prerequisite 2
|
||||
- [ ] Prerequisite 3
|
||||
|
||||
## Input Data
|
||||
|
||||
| Data | Source | Format | Required |
|
||||
|------|--------|--------|----------|
|
||||
| data1 | {source} | {format} | Yes |
|
||||
| data2 | {source} | {format} | Yes |
|
||||
| data3 | {source} | {format} | No |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: {Step Name}
|
||||
|
||||
**Description**: 详细描述步骤内容
|
||||
|
||||
**Action**: 具体要执行的操作
|
||||
|
||||
**Validation**: 如何验证步骤完成
|
||||
|
||||
**Output**: 产出什么数据或文件
|
||||
|
||||
### Step 2: {Step Name}
|
||||
|
||||
**Description**: 详细描述步骤内容
|
||||
|
||||
**Action**: 具体要执行的操作
|
||||
|
||||
**Validation**: 如何验证步骤完成
|
||||
|
||||
**Output**: 产出什么数据或文件
|
||||
|
||||
### Step 3: {Step Name}
|
||||
|
||||
...
|
||||
|
||||
## Output
|
||||
|
||||
本阶段将产生以下输出：
|
||||
|
||||
| Output | Format | Location | Description |
|
||||
|--------|--------|----------|-------------|
|
||||
| output1 | {format} | {path} | 描述 |
|
||||
| output2 | {format} | {path} | 描述 |
|
||||
|
||||
## Quality Checks
|
||||
|
||||
执行完成后，检查以下项目：
|
||||
|
||||
- [ ] 所有步骤已执行
|
||||
- [ ] 输出文件已创建
|
||||
- [ ] 输出格式正确
|
||||
- [ ] 数据完整性验证
|
||||
- [ ] 无错误或警告
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Error 1 | 原因描述 | 解决方案 |
|
||||
| Error 2 | 原因描述 | 解决方案 |
|
||||
|
||||
## Next Phase
|
||||
|
||||
完成本阶段后，进入 **Phase {N+1}: {Next Phase Name}**
|
||||
|
||||
**传递数据**:
|
||||
- data1 → Next phase input 1
|
||||
- data2 → Next phase input 2
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
本阶段被视为完成，当：
|
||||
|
||||
1. 所有执行步骤已完成
|
||||
2. 所有质量检查已通过
|
||||
3. 输出文件已生成并验证
|
||||
4. 无未处理的错误
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: skill-generator Phase 3 (Sequential 模式)
|
||||
2. **输入**: Phase 2 生成的目录结构
|
||||
3. **输出**: phases/NN-{phase-name}.md
|
||||
4. **命名**: 使用数字前缀排序 (01-, 02-, 03-)
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
# Phase 1: Context Collection
|
||||
|
||||
> **Skill**: review-code
|
||||
> **Phase Number**: 1
|
||||
> **Execution Mode**: Sequential
|
||||
> **Estimated Duration**: 5 minutes
|
||||
|
||||
## Objective
|
||||
|
||||
收集目标代码的上下文信息，识别技术栈和代码结构
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [ ] Phase 0: 规范学习已完成
|
||||
- [ ] 目标路径已提供
|
||||
- [ ] specs/ 文档已阅读
|
||||
|
||||
## Input Data
|
||||
|
||||
| Data | Source | Format | Required |
|
||||
|------|--------|--------|----------|
|
||||
| target_path | User input | string | Yes |
|
||||
| review_dimensions | specs/review-dimensions.md | list | Yes |
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: 扫描目标目录
|
||||
|
||||
**Description**: 使用 Glob 或 ACE 搜索工具扫描目标路径
|
||||
|
||||
**Action**:
|
||||
```bash
|
||||
# 扫描所有源文件
|
||||
Glob(pattern="{target}/**/*.ts")
|
||||
Glob(pattern="{target}/**/*.tsx")
|
||||
```
|
||||
|
||||
**Validation**: 至少找到 1 个文件
|
||||
|
||||
**Output**: file_list.json
|
||||
|
||||
### Step 2: 识别技术栈
|
||||
|
||||
**Description**: 分析配置文件和依赖，识别技术栈
|
||||
|
||||
**Action**:
|
||||
- 读取 package.json
|
||||
- 读取 tsconfig.json
|
||||
- 分析导入语句
|
||||
|
||||
**Validation**: 识别出主要语言和框架
|
||||
|
||||
**Output**: tech_stack.json
|
||||
|
||||
### Step 3: 构建代码模型
|
||||
|
||||
**Description**: 构建代码的依赖关系图
|
||||
|
||||
**Action**: 使用 ACE 工具分析代码关系
|
||||
|
||||
**Validation**: 依赖图构建完成
|
||||
|
||||
**Output**: code_model.json
|
||||
|
||||
## Output
|
||||
|
||||
| Output | Format | Location | Description |
|
||||
|--------|--------|----------|-------------|
|
||||
| file_list | JSON | state/context/files.json | 所有扫描到的文件 |
|
||||
| tech_stack | JSON | state/context/tech-stack.json | 技术栈信息 |
|
||||
| code_model | JSON | state/context/code-model.json | 代码关系图 |
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] 文件列表非空
|
||||
- [ ] 技术栈识别准确
|
||||
- [ ] 代码模型无循环依赖警告
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| No files found | 路径错误或路径为空 | 提示用户检查路径 |
|
||||
| Unknown tech | 无法识别技术栈 | 使用默认配置 |
|
||||
|
||||
## Next Phase
|
||||
|
||||
完成本阶段后，进入 **Phase 2: Quick Scan**
|
||||
|
||||
**传递数据**:
|
||||
- file_list → Quick Scan 输入
|
||||
- tech_stack → Quick Scan 输入
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
1. 所有文件已扫描
|
||||
2. 技术栈已识别
|
||||
3. 代码模型已构建
|
||||
4. state/context/ 目录已创建
|
||||
```
|
||||
274
docs/skills/templates/skill-md.md
Normal file
274
docs/skills/templates/skill-md.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# SKILL.md Template
|
||||
|
||||
> 用途: Skill 入口文档模板 (SKILL.md)，用于 skill-generator
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# {Skill Name}
|
||||
|
||||
> **Type**: {Sequential|Autonomous}
|
||||
> **Version**: {1.0.0}
|
||||
> **Status**: {Stable|Experimental}
|
||||
> **Category**: {Team|Workflow|Standalone|Specialized}
|
||||
|
||||
## One-Liner
|
||||
|
||||
**简短描述** — 详细说明
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | {Skill Name} Solution |
|
||||
|------------|---------------|----------------------|
|
||||
| Pain Point 1 | 当前问题描述 | 解决方案描述 |
|
||||
| Pain Point 2 | 当前问题描述 | 解决方案描述 |
|
||||
| Pain Point 3 | 当前问题描述 | 解决方案描述 |
|
||||
|
||||
## Skills List / 功能列表
|
||||
|
||||
| Skill / Phase | Function | Trigger |
|
||||
|---------------|----------|---------|
|
||||
| {sub-skill-1} | 功能描述 | 触发命令 |
|
||||
| {sub-skill-2} | 功能描述 | 触发命令 |
|
||||
|
||||
## Skills Details / 详细说明
|
||||
|
||||
### {Sub-Skill Name}
|
||||
|
||||
**One-Liner**: 一句话描述
|
||||
|
||||
**Trigger**:
|
||||
```shell
|
||||
/trigger-command <args>
|
||||
/trigger-command --flag <value>
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
|
||||
**Architecture Overview**:
|
||||
```plaintext
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ {Skill Name} Architecture │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Phase 1 │ -> │ Phase 2 │ -> │ Phase 3 │ │
|
||||
│ │ {Desc} │ │ {Desc} │ │ {Desc} │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**⚠️ Mandatory Prerequisites**:
|
||||
|
||||
> **Do not skip**: Before executing any operations, you **must** completely read the following documents.
|
||||
|
||||
**Specification Documents** (required):
|
||||
| Document | Purpose | Priority |
|
||||
|----------|---------|----------|
|
||||
| [specs/{doc-name}.md](specs/{doc-name}.md) | Description | **P0 - Highest** |
|
||||
|
||||
**Template Files** (read before generation):
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [templates/{template}.md](templates/{template}.md) | Template description |
|
||||
|
||||
**Execution Flow**:
|
||||
```plaintext
|
||||
Phase 1: {Phase Name}
|
||||
-> Action 1: Description
|
||||
-> Action 2: Description
|
||||
-> Output: {output description}
|
||||
|
||||
Phase 2: {Phase Name}
|
||||
-> Action 1: Description
|
||||
-> Action 2: Description
|
||||
-> Output: {output description}
|
||||
|
||||
Phase 3: {Phase Name}
|
||||
-> Action 1: Description
|
||||
-> Output: {output description}
|
||||
```
|
||||
|
||||
**Output Structure**:
|
||||
```plaintext
|
||||
{output-directory}/
|
||||
├── file1.md # Description
|
||||
├── file2.md # Description
|
||||
└── subdirectory/ # Description
|
||||
├── file3.md
|
||||
└── file4.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### {Another Sub-Skill}
|
||||
|
||||
**One-Liner**: 一句话描述
|
||||
|
||||
**Trigger**:
|
||||
```shell
|
||||
/trigger-command <args>
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
**Use Cases**:
|
||||
- Use case 1
|
||||
- Use case 2
|
||||
|
||||
## Related Commands
|
||||
|
||||
- [Related Command 1](../commands/claude/{command}.md)
|
||||
- [Related Command 2](../commands/claude/{command}.md)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Practice 1**: Description
|
||||
2. **Practice 2**: Description
|
||||
3. **Practice 3**: Description
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Example 1: Description
|
||||
/trigger-command <args>
|
||||
|
||||
# Example 2: Description
|
||||
/trigger-command --flag <args>
|
||||
|
||||
# Example 3: Description
|
||||
/trigger-command sub-command <args>
|
||||
```
|
||||
|
||||
## Output Example
|
||||
|
||||
```
|
||||
### Example Output Title
|
||||
|
||||
**Location**: `file/path:line`
|
||||
|
||||
**Issue**: Description of the finding
|
||||
|
||||
**Severity**: {Critical|High|Medium|Low}
|
||||
|
||||
**Recommendation**:
|
||||
```typescript
|
||||
// Before (problematic)
|
||||
const code = "problematic code";
|
||||
|
||||
// After (fixed)
|
||||
const code = "fixed code";
|
||||
```
|
||||
|
||||
**Reference**: [specs/reference.md](specs/reference.md) - Section name
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Problem 1 | Solution 1 |
|
||||
| Problem 2 | Solution 2 |
|
||||
| Problem 3 | Solution 3 |
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | YYYY-MM-DD | Initial release |
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **触发**: skill-generator Phase 2
|
||||
2. **输入**: Phase 1 skill-config.json
|
||||
3. **输出**: SKILL.md
|
||||
4. **验证**: 确保所有链接有效，所有章节完整
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 简化示例
|
||||
|
||||
```markdown
|
||||
# Review Code
|
||||
|
||||
> **Type**: Autonomous
|
||||
> **Version**: 1.0.0
|
||||
> **Status**: Stable
|
||||
> **Category**: Specialized
|
||||
|
||||
## One-Liner
|
||||
|
||||
**多维度代码审查** — 通过 6 个维度自动分析代码质量并提供修复建议
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Review Code Solution |
|
||||
|------------|---------------|----------------------|
|
||||
| 审查维度不全 | 手动审查容易遗漏 | 6 维度自动审查 |
|
||||
| 问题分类混乱 | 难以区分严重性 | 结构化问题分类 |
|
||||
| 修复建议模糊 | 缺乏具体方案 | 可执行的修复建议 |
|
||||
|
||||
## Skills List
|
||||
|
||||
| Skill | Function | Trigger |
|
||||
|-------|----------|---------|
|
||||
| review-code | 6 维度代码审查 | `/review-code <target>` |
|
||||
| review-cycle | 审查和修复循环 | `/review-cycle <target>` |
|
||||
|
||||
## Skills Details
|
||||
|
||||
### review-code
|
||||
|
||||
**One-Liner**: 6 维度代码审查
|
||||
|
||||
**Trigger**:
|
||||
```shell
|
||||
/review-code src/**
|
||||
/review-code --dimensions=sec,perf src/
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- 6 维度审查：正确性、可读性、性能、安全、测试、架构
|
||||
- 快速扫描识别高风险区域
|
||||
- 深度审查聚焦关键问题
|
||||
- 结构化报告分级输出
|
||||
|
||||
**Execution Flow**:
|
||||
```plaintext
|
||||
Phase 0: Specification Study (Mandatory)
|
||||
-> Read specs/review-dimensions.md
|
||||
-> Read specs/issue-classification.md
|
||||
|
||||
Phase 1: Collect Context
|
||||
-> Scan target files
|
||||
-> Identify tech stack
|
||||
-> Output: state.context
|
||||
|
||||
Phase 2: Quick Scan
|
||||
-> Identify high-risk areas
|
||||
-> Output: state.risk_areas
|
||||
|
||||
Phase 3: Deep Review (per dimension)
|
||||
-> Analyze each dimension
|
||||
-> Record findings
|
||||
-> Output: state.findings[]
|
||||
|
||||
Phase 4: Generate Report
|
||||
-> Aggregate findings
|
||||
-> Generate review-report.md
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **完整阅读规范**: 执行前必须阅读 specs/ 文档
|
||||
2. **快速扫描先行**: 先识别高风险，再深度审查
|
||||
3. **结构化报告**: 使用生成的报告作为修复指南
|
||||
```
|
||||
Reference in New Issue
Block a user