agentsclimarketplace
Sign in

Spectra

Skill connor-git-yaml/cc-plugin-market/skills/spectra

Use this skill when the user asks to: - Generate a spec/specification from existing code - Document or analyze a module's architecture - Reverse engineer what a piece of code does - Create .spec.md documentation for a file, directory, or module - Understand the intent, interfaces, and business logic of existing code Supports single files (e.g., src/auth/login.ts), directories (e.g., src/auth/), or entire modules.From its SKILL.md

Install
npx -y skills add connor-git-yaml/cc-plugin-market --skill spectra

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 15 stars15 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

8.7 KB, as published. Nobody here has run it

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Purpose

通过 AST 静态分析 + LLM 混合三阶段流水线，将源代码逆向工程为结构化的 9 段式中文 Spec 文档。TypeScript/JavaScript 项目享有 AST 增强的精确分析，接口定义 100% 来自 AST 提取。

Execution Flow

1. Parse Target

Interpret $ARGUMENTS to determine the analysis target:

  • Single file: e.g., src/auth/login.ts
  • Directory: e.g., src/auth/ — analyze all TS/JS source files recursively
  • --deep flag: Include function bodies in LLM context for deeper analysis
  • No argument: Ask user to specify a target path

If the target doesn't exist, ERROR with suggestions based on project structure.

2. Run Pipeline

Execute the analysis pipeline using the globally installed spectra CLI:

spectra generate $TARGET_PATH --deep

如果需要自定义输出目录：

spectra generate $TARGET_PATH --deep --output-dir specs

Pipeline stages:

  1. 预处理: 扫描 TS/JS 文件 → ts-morph AST 分析 → CodeSkeleton 提取 → 敏感信息脱敏
  2. 上下文组装: 骨架 + 依赖 spec + 代码片段 → ≤100k token 预算的 LLM prompt
  3. 生成增强: Claude API 生成 9 段式中文 Spec → 解析验证 → Handlebars 渲染 → 写入 specs/*.spec.md

3. Handle Results

If pipeline succeeds, report:

Spec 生成完成: specs/<name>.spec.md

分析摘要:
- 文件数: N
- 总行数: N LOC
- 导出 API: N 个
- Token 消耗: N
- 置信度: high|medium|low
- 警告: <warnings list>

后续步骤:
- 审查生成的 Spec 文档
- 使用 /spectra-batch 批量生成全项目 Spec
- 使用 /spectra-diff 检测 Spec 漂移

If pipeline fails, fall back to manual analysis following the sections below.

4. Fallback: Manual Analysis

If the CLI pipeline is unavailable, perform manual analysis:

  1. Scan & inventory all source files in scope
  2. Read and analyze each file's exports, imports, types, and logic
  3. Generate spec following the 9-section structure defined below
  4. Write to specs/<target-name>.spec.md

5. 9-Section Spec Structure

Each generated spec must contain these 9 sections in Chinese:

  1. 意图 — 模块目的和存在理由
  2. 接口定义 — 所有导出 API（签名必须精确，不可捏造）
  3. 业务逻辑 — 核心算法、决策树、工作流
  4. 数据结构 — 类型定义、接口、Schema
  5. 约束条件 — 性能、安全、平台约束
  6. 边界条件 — 错误处理、边界条件、降级策略
  7. 技术债务 — TODO/FIXME、缺失测试、硬编码值
  8. 测试覆盖 — 已测试行为、覆盖缺口
  9. 依赖关系 — 内部/外部依赖

Constitution Rules (不可违反)

  1. AST 精确性优先: 接口定义 100% 来自 AST/代码，绝不由 LLM 捏造
  2. 混合分析流水线: 强制三阶段（预处理 → 上下文组装 → 生成增强）
  3. 诚实标注不确定性: 推断内容用 [推断: 理由]，模糊代码用 [不明确: 理由]
  4. 只读安全性: 仅向 specs/ 写入输出，绝不修改源代码
  5. 纯 Node.js 生态: 所有依赖限于 npm 包
  6. 双语文档: 中文散文 + 英文代码标识符

语言规范

所有 spec 文档的正文内容必须使用中文撰写。 具体规则：

  • 用中文：所有描述、说明、分析、总结、表格内容
  • 保留英文：代码标识符、文件路径、类型签名、代码块内容
  • 章节标题：使用中文，例如 ## 1. 意图、## 2. 接口定义
  • Frontmatter：保留英文（YAML 键名）

架构问答工具（MCP）

panoramic-query — 架构分析 + 自然语言问答

panoramic-query MCP 工具支持四种 operation：

operation说明必填参数
cross-package跨包依赖分析（monorepo 项目）projectRoot
architecture-ir架构信息模型（IR）提取projectRoot
overview架构概览文档生成projectRoot
natural-language自然语言问答（FR-009）projectRoot + question

natural-language operation（F5 新增）

通过自然语言问题查询项目架构，支持 5 类典型问题：调用关系、调用路径、设计决策映射、技术债、流程归属。

参数：

  • operation（必填）："natural-language"
  • projectRoot（必填）：项目根目录绝对路径
  • question（必填）：问题文本（operation=natural-language 时必填；空字符串会被拒绝）

返回：JSON 格式的 QnAAnswer 结构：

  • answer（string）：LLM 生成的回答文本
  • citations（Citation[]）：溯源引用列表（100% 覆盖率，每条含三字段）
    • specPath：引用来源的 spec 文件路径（repo-relative）
    • lineRange：{ startLine, endLine }（1-based，含边界）
    • excerpt：原文摘要（≤ 200 字符）
    • nodeId（可选）：对应 graph 节点 ID
    • similarity（可选）：余弦相似度得分（RAG 精排路径）
  • tokenUsage：{ input, output, overBudget }（overBudget=true 时已超 $0.05 硬限额，但不阻断调用）
  • durationMs：问答耗时（毫秒）
  • fallbackMode（可选）：'rag-only' | 'bfs-only' | 'graph-insufficient'（降级模式）

前置条件：需先运行 spectra batch 生成 specs/_meta/graph.json。

典型调用：

{
  "operation": "natural-language",
  "projectRoot": "/absolute/path/to/project",
  "question": "什么模块调用了认证逻辑？"
}

图查询工具（MCP）

单模块生成完成后，若项目已跑过 spectra batch，则 specs/_meta/graph.json 会提供 6 个 MCP 图查询工具供 AI 助手调用：

  • graph_query：按关键词查询相关模块和子图（{ question: "认证模块", depth: 2 }）
  • graph_node：查询指定节点的详情和邻居（{ id: "src/auth/login.ts" }）；v2.0 起返回额外的 semanticEdges 字段（见下）
  • graph_path：查找两个节点间的最短路径（{ source, target }）
  • graph_community：列出某社区的节点（{ communityId: "c-0" }）
  • graph_god_nodes：识别度数最高的枢纽节点（{ limit: 10 }）
  • graph_hyperedges：查询超边（Hyperedges），表达 3+ 节点共同参与的架构流程或概念群（见下）

使用场景：通过 /spectra 生成单模块 spec 后，想追问"这个模块被谁调用了"、"从 A 到 B 的依赖路径是什么"、"项目里哪个模块最核心"等结构性问题，即可使用这些工具。

graph_hyperedges

查询 graph.json 中的超边（Hyperedges），表达 3+ 节点共同参与的架构流程或概念群。需要先运行 spectra batch --hyperedges 生成含超边的图谱。

参数（均可选）：

  • label（string）：按 hyperedge label 模糊匹配（子串，大小写不敏感）
  • node_id（string）：按节点 ID 精确匹配（返回 nodes 数组中含此 ID 的 hyperedge）
  • limit（number）：返回数量上限（默认返回全部匹配的超边）

返回：hyperedge 列表，每条含 id / label / nodes / rationale / confidence，以及 total（匹配总数）和 filtered（是否使用了过滤参数）

典型调用：

{ "label": "Ingestion Pipeline" }
{ "node_id": "src/auth/login.ts" }
{}

使用场景：

  • 查询 "Full Ingestion Pipeline" 等命名流程涉及的所有函数/模块
  • 反向溯源某个函数属于哪些架构流程（通过 node_id 过滤）
  • 了解项目中有哪些跨模块的复杂协作关系

graph_node v2.0 新增：semanticEdges 字段

v2.0 起，graph_node 响应额外返回 semanticEdges 数组，列出与当前节点关联的所有语义边（references / conceptually_related_to / rationale_for）。

每条语义边包含：

  • type：边类型（references / conceptually_related_to / rationale_for）
  • direction：相对当前节点的方向（outgoing / incoming）
  • peer：对端节点 ID
  • evidenceText：证据文本（可选）
  • evidenceSource：证据来源（格式 "path:startLine-endLine"，可选）
  • confidence：置信度（EXTRACTED / INFERRED / AMBIGUOUS）

节点无关联语义边时，semanticEdges 返回空数组（不报错）。

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.