技能路由器

文档 社区

技能解读

当前原文的自动摘译,尚未人工审校。

适用范围

路由器管理以下各项的运行时建议: 技能代理 MCP 服务器 线束是单独的目录实体。当用户需要时推荐它们

问题

每个加载的助手都需要花费代币、注意力和操作面积。大多数会话需要来自已发布图表的得分最高的小包,但并非每个 ctx 都知道。加载过多:在不相关的指令上浪费上下文,当助手匹配错误的任务时导致失败,

建筑

路由器分为三个部分: 扫描器 - 分析存储库并生成堆栈/任务证据。解析器 - 对图形/wiki 实体进行评分并发出上限清单。 Wiki/graph - 实体、用法、质量和链接的持久目录。

启动流程

阅读附带的图表/wiki 元数据和本地用户覆盖。为活动存储库运行 ctx-scan-repo --repo . --recommend。使用共享推荐引擎解析加载/卸载清单。呈现更改并说明原因并需要确认,除非用户启用了自动模式。

扫描仪

扫描器读取存储库结构和文件以生成堆栈配置文件。检测是基于证据的:每个声明都应映射到文件、依赖项、配置值或导入模式。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
文档
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@stevesolun · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
不需要
兼容的系统
Docker
运行环境要求
Docker
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Skill Router

Scan a repo. Know what the current work needs. Recommend only that. Keep the
wiki and graph as the durable catalog behind the decision.

## Scope

The router manages runtime recommendations for:

- skills
- agents
- MCP servers

Harnesses are separate catalog entities. They are recommended when a user wants
to run ctx with a non-Claude-Code host, local model, or API model. Once attached,
the harness calls the same skills/agents/MCP recommendation engine.

## Problem

Every loaded helper costs tokens, attention, and operational surface area. Most
sessions need a small top-scored bundle from the shipped graph, not every entity
ctx knows about. Loading too much:

- wastes context on irrelevant instructions,
- causes misfires when a helper matches the wrong task,
- slows the agent loop, and
- creates conflicting instructions.

## Architecture

```text
ctx/
|-- src/scan_repo.py                         # Repo scanner -> stack profile
|-- src/ctx/core/resolve/resolve_skills.py   # Profile -> load/unload manifest
|-- src/ctx/core/resolve/recommendations.py  # Shared scoring/ranking engine
|-- src/ctx/adapters/                        # Claude Code hooks + generic tools
|-- src/harness_install.py                   # Custom-model harness install flow
`-- graph/wiki-graph-runtime.tar.gz          # Shipped graph/wiki runtime
```

The router has three halves:

1. **Scanner** - analyzes a repo and produces stack/task evidence.
2. **Resolver** - scores graph/wiki entities and emits a capped manifest.
3. **Wiki/graph** - persistent catalog of entities, usage, quality, and links.

## Startup Flow

1. Read the shipped graph/wiki metadata and local user overrides.
2. Run `ctx-scan-repo --repo . --recommend` for the active repo.
3. Resolve a load/unload manifest with the shared recommendation engine.
4. Present changes with reasons and require confirmation unless the user enabled
   automatic mode.
5. Record usage/quality changes after the user accepts or rejects suggestions.

## Scanner

The scanner reads repo structure and files to produce a stack profile. Detection
is evidence-based: every claim should map to a file, dependency, config value, or
import pattern.

### Detection Categories

- **Languages** - file extensions, shebangs, lock files.
- **Frameworks and libraries** - package manifests, imports, config files.
- **Infrastructure and DevOps** - Docker, CI/CD, IaC, cloud, Kubernetes.
- **Data and storage** - databases, migrations, queues, pipelines.
- **Documentation and content** - MkDocs, Docusaurus, Sphinx, API specs.
- **Testing and quality** - pytest, Jest, Playwright, Ruff, mypy, TypeScript.
- **AI and agent tooling** - MCP configs, LangGraph, CrewAI, prompt dirs, model
  config names.
- **Build and package** - package managers, build tools, monorepos.

### Scanning Rules

1. Start with filenames and config files. Read source only when needed to
   disambiguate.
2. Do not include speculative signals below the configured confidence floor.
3. Skip generated/vendor directories such as `.git`, `node_modules`,
   `__pycache__`, `venv`, and `.venv`.
4. Keep initial scans bounded for large repos.
5. Redact secret values; only record secret/key names as evidence.

## Resolver

The resolver produces a manifest containing the exact helper set to load or
unload.

```json
{
  "generated_at": "ISO-8601",
  "repo_path": "/absolute/path",
  "profile_hash": "sha256 of stack profile",
  "load": [
    {
      "name": "fastapi",
      "type": "skill",
      "reason": "FastAPI detected in pyproject.toml dependencies",
      "score": 0.94
    }
  ],
  "unload": [
    {
      "name": "react",
      "type": "skill",
      "reason": "No active frontend signal in the current repo window"
    }
  ],
  "suggestions": [
    {
      "name": "github",
      "type": "mcp",
      "reason": ".github/workflows exists and the repo uses GitHub Actions",
      "install_command": "ctx-mcp-add ..."
    }
  ],
  "warnings": []
}
```

### Ranking Signals

Candidates can be scored by:

- tag/category/subcategory match
- semantic similarity edge weight
- direct wiki links
- source overlap
- type affinity
- usage score
- quality/security score
- user overrides (`always_load`, `never_load`)
- configured caps and minimum score gates

Recommendations are capped. ctx should not recommend at all costs; below-threshold
candidates should be withheld and the gap should be explained.

## Wiki And Graph Contract

The wiki follows a Karpathy-style durable memory pattern: schema, purpose, index,
log, lint, review items, and entity pages that are machine-readable.

```text
llm-wiki/
|-- SCHEMA.md
|-- index.md
|-- log.md
|-- raw/
|   |-- scans/
|   `-- external-catalogs/
|-- entities/
|   |-- skills/
|   |-- agents/
|   |-- mcp-servers/
|   `-- harnesses/
|-- concepts/
|-- comparisons/
`-- queries/
```

Entity pages use YAML frontmatter with at least:

```yaml
title: Entity Name
type: skill | agent | mcp-server | harness | external-catalog
status: installed | available | deprecated | broken
tags: []
source: local | shipped | github | curated
source_url: ""
path: ""
quality_score: null
usage_score: 0
last_used: null
always_load: false
never_load: false
```

## Entity Sources

Entity sources include shipped skill/MCP/harness sources, GitHub
entity repositories, and local user assets. The public reference page is
[`marketplace-registry.md`](marketplace-registry.md), kept under that filename
for backwards-compatible links.

Source rules:

1. Search the shipped graph/wiki first.
2. Use additional sources only when the local graph is missing or stale.
3. Deduplicate before adding.
4. If an entity exists, emit an update review instead of replacing it.
5. Run security checks before promotion.
6. Rebuild and validate graph/wiki artifacts before shipping.

## Micro-Skill Gate

Every added or updated skill must pass the configured line-count gate before it
is packed into the shipped wiki. The default threshold is 180 lines, read from
ctx config. Skills above the threshold are converted into a short orchestrator
plus staged reference files. Local `.original` backups may be preserved for
traceability, but packaged runtime archives must omit those backups.

## Core Operations

### Full Scan

Triggers: repo open, repo switch, `ctx-scan-repo --repo . --recommend`, or explicit user
request.

1. Read wiki orientation and local overrides.
2. Scan the target repo.
3. Save the scan result.
4. Resolve load/unload recommendations.
5. Present reasons, scores, and install/update commands.
6. Apply only after confirmation unless configured otherwise.
7. Record usage and decisions.

### Incremental Scan

Triggers: changed config files, new dependencies, new MCP config, new tests, new
infrastructure files, or user task change.

If a helper is no longer useful, ctx should suggest unloading it and ask for
confirmation. If the user asks to skip unload prompts, ctx should respect that
preference.

### Manual Override

- "Always load the docker skill" -> set `always_load: true`.
- "Never load the react skill" -> set `never_load: true`.
- "Load the terraform skill for this session" -> temporary load.
- "What is loaded?" -> show current manifest with reasons.

### Discovery

When the user asks what exists for a task:

1. Search graph/wiki entity pages by tags and text.
2. Use `find-skills` and configured sources for remote freshness when needed.
3. Show status, score, source, and risk notes.
4. Suggest install/update commands, not silent installs.
5. Log the query.

## Maintenance Checks

- **Stale installed helpers** - used rarely or not used recently.
- **Ghost helpers** - installed status but missing local path.
- **Orphan local helpers** - present locally but missing entity page.
- **Skill index freshness** - shipped skill snapshot older than policy.
- **Conflicts** - overlapping helpers both marked `always_load`.
- **Usage cold spots** - low usage/quality score candidates for unload review.
- **Wiki lint** - broken links, missing frontmatter, index drift.

## Reporting

After a scan, report only actionable details:

```text
Skill Router Report - repo-name
Scanned: YYYY-MM-DD HH:MM

Loaded:
1. fastapi skill - score 0.94 - pyproject.toml dependency
2. github MCP - score 0.91 - GitHub Actions workflows detected

Unload candidates:
1. react skill - no active frontend signal

Suggestions:
1. openapi-generator skill - OpenAPI spec found

Warnings:
None
```

## Configuration

Router behavior is controlled by ctx config and user overrides. Important knobs:

```yaml
recommendations:
  max_total: 5
  min_score: 0.85
micro_skills:
  max_lines: 180
router:
  auto_scan: true
  auto_apply: false
  ask_before_unload: true
```

## Pitfalls

- Never load all helpers just in case.
- Never replace an existing entity without an update review.
- Never execute external repo scripts while cataloging.
- Never treat conversation history as the source of workflow state.
- Never ship graph/wiki artifacts before validation passes.
- Respect `never_load` and user rejection history.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。