skill-extract

宿主：Codex CLI —— 此技能原为 Claude Code 设计，后经调整适用于 Codex。 交叉引用命令使用 Codex 中已安装的技能名称，而非 /octo:* 斜杠命令。 使用当前活跃的 Codex shell 和子 Agent 工具。在当前会话明确提供之前，不要声称某个提供方、模型或宿主子 Agent 可用。 有关宿主工具的等效项，请参阅 skills/blocks/codex-host-adapter.md。

提取技能 - 实现指南

概述

extract 技能为设计系统和产品架构提供全面的逆向工程能力。它能将缺少文档的代码库转化为结构化、可直接用于实现的文档。

功能

设计系统提取

• 令牌提取：从代码或 CSS 中提取颜色、字体排版、间距和阴影
• 组件分析：分析 React/Vue/Svelte 中的属性、变体和使用模式
• 模式检测：检测布局模式、设计规则和无障碍指南
• Storybook 生成：自动生成包含变体和控件的 stories

产品架构提取

• 服务检测：检测微服务边界、模块和领域边界
• API 映射：整理 REST、GraphQL、tRPC、gRPC 端点目录
• 数据建模：提取 ORM 架构（Prisma、TypeORM、Sequelize）
• 功能清单：按路由和领域检测功能
• C4 图：自动生成架构可视化图（Mermaid）

技术实现

令牌提取流程

优先级顺序（置信度由高到低）：

1. 代码定义（95%）：theme.ts、tokens.json、Tailwind 配置
2. CSS 变量（90%）：:root 声明
3. 计算样式（60%）：DOM 分析
4. 推断（40-60%）：颜色聚类、比例检测

颜色聚类算法：

• 使用 CIEDE2000 计算符合感知准确度的颜色距离
• 使用 K-means++ 初始化，确保聚类稳定
• 主色板默认采用 k=8 个聚类
• 使用 ΔE < 2 阈值检测重复项

组件分析

检测策略：

• 对 TypeScript/JavaScript 进行 AST 解析
• 从接口和 PropTypes 中提取属性
• 从联合类型中检测变体
• 跟踪整个代码库中的使用情况

支持的框架：

• React（函数组件、类组件、hooks）
• Vue（SFC、Composition API、Options API）
• Svelte（script/template 分离）

架构检测

服务边界启发式规则：

• 子目录中的 package.json
• 独立部署配置
• 团队所有权边界
• 通信模式分析

API 端点检测：

• 基于装饰器的路由（NestJS、routing-controllers）
• Express/Fastify 路由定义
• GraphQL resolver 类
• tRPC 路由器过程
• Protocol Buffer（.proto）文件

多 AI 编排

启用后，extract 功能会使用多个 AI 提供方来提高准确性：

提供方职责：

• Claude：综合分析、解决冲突、编写文档
• Codex：代码级分析、类型提取、架构分析
• Antigravity：模式识别、替代性解读、UX 洞察

共识机制：

• 阈值：提取质量门槛要求达到已配置的共识阈值（默认为 67%）；如果没有数值投票数据，则仲裁器会从最多 3 个提供方的观点中选出匹配度最高的提案，并记录分歧。
• 在 90_evidence/disagreements.md 中记录分歧
• 为所有输出附加置信度评分

输出结构

octopus-extract/
└── project-name/
    └── timestamp/
        ├── README.md                   # Navigation and summary
        ├── metadata.json               # Extraction parameters
        │
        ├── 00_intent/
        │   ├── answers.json            # User intent responses
        │   ├── intent-contract.md      # Human-readable summary
        │   └── detection-report.md     # Stack auto-detection results
        │
        ├── 10_design/
        │   ├── tokens.json             # W3C Design Tokens format
        │   ├── tokens.css              # CSS custom properties
        │   ├── tokens.md               # Human-readable token docs
        │   ├── components.csv          # Component inventory (tabular)
        │   ├── components.json         # Structured component data
        │   ├── patterns.md             # Layout and design patterns
        │   └── storybook/              # Storybook scaffold (optional)
        │       ├── .storybook/
        │       └── stories/
        │
        ├── 20_product/
        │   ├── product-overview.md     # What, who, key journeys
        │   ├── feature-inventory.md    # Features by domain
        │   ├── architecture.md         # C4 text description
        │   ├── architecture.mmd        # Mermaid C4 diagrams
        │   ├── PRD.md                  # AI-agent executable PRD
        │   ├── user-stories.md         # Gherkin-style scenarios
        │   ├── api-contracts.md        # Endpoint specifications
        │   ├── data-model.md           # Entity relationships
        │   └── implementation-plan.md  # Phased milestones
        │
        └── 90_evidence/
            ├── quality-report.md       # Coverage and confidence metrics
            ├── disagreements.md        # Multi-AI conflicts
            ├── extraction-log.md       # Timestamped progress log
            └── references.json         # File paths per claim

质量门槛

自动验证可确保提取质量：

1. 令牌覆盖率：设计模式下未提取到任何令牌时失败
2. 组件覆盖率：检测到的组件文件少于 50% 时发出警告
3. 架构完整性：产品模式下未检测到任何服务时发出警告
4. 多 AI 共识：关键输出的共识低于已配置阈值（默认为 67%）时失败

使用模式

基本提取

/octo:extract ./my-app

仅提取设计系统

/octo:extract ./my-app --mode design --storybook true

使用多 AI 进行深度分析

/octo:extract ./my-app --depth deep --multi-ai force

URL 提取

/octo:extract https://example.com --mode design --depth quick

与其他技能集成

• /octo:review：审核提取结果的质量
• /octo:deliver：验证提取内容是否完整
• /octo:docs：根据提取结果生成其他文档

错误处理

常见错误代码：

• ERR-001：输入无效（未找到路径/URL）
• ERR-002：网络超时（URL 提取）
• ERR-003：权限被拒绝
• ERR-004：内存不足（使用 --depth quick）
• VAL-001：验证失败（未检测到令牌）
• VAL-004：多 AI 共识度低

性能目标

深度	目标耗时	覆盖率目标
快速	< 2 min	覆盖率 70%，基础分析
标准	2-5 min	覆盖率 85%，全面分析
深度	5-15 min	覆盖率 95%，多 AI 验证

研究来源

此技能参考了以下研究：

• Tokens Studio - 设计令牌自动化
• Superposition - 从网站提取令牌
• W3C Design Tokens - 令牌格式标准
• C4 Model - 架构图绘制
• 现代逆向工程实践（2026）

实施状态

当前版本：1.0.0（骨架）

已实现：

• ✅ 命令结构
• ✅ CLI 参数解析
• ✅ 输出目录设置
• ✅ 元数据生成
• ✅ 多 AI 检测

进行中：

• 🚧 令牌提取流水线
• 🚧 组件分析引擎
• 🚧 架构检测
• 🚧 PRD 生成
• 🚧 质量关卡

计划中：

• ⏳ Storybook 脚手架生成
• ⏳ C4 图生成
• ⏳ URL 提取模式
• ⏳ CSS 推断算法

贡献

请参阅项目文档中的实施计划。

实施阶段：

1. 基础功能与 CLI（第 1 周）
2. 自动检测引擎（第 2 周）
3. 设计提取（第 3-4 周）
4. 产品提取（第 5-6 周）
5. 多 AI 编排（第 7 周）
6. 质量关卡（第 8 周）
7. 测试与文档（第 10 周）

此技能实现了 PRD v2.0（AI-Executable）中指定的设计