RFC - Multi-Market Skills Marketplace for CoPaw

[futuremeng]

背景

• CoPaw 已支持从单个 Hub/URL 导入技能，但缺少“可管理的市场列表”能力。
• 路线图已明确技能生态方向，且近期 skills 相关改动活跃，具备推进窗口。
• 社区需要将技能来源从“单链接导入”升级为“多市场聚合发现 + 按条目安装”。

目标

• 支持多个技能市场，每个市场是一个 git 仓库。
• 支持用户在控制台新增、编辑、启停、排序市场。
• 支持市场聚合展示、失败隔离、按条目安装。
• 保持现有 URL 导入路径可用，不破坏已有行为。
• 市场配置持久化到 ~/.copaw/config.json（随工作目录机制一致）。

非目标

• 首版不引入签名校验、信誉评分或复杂审核系统。
• 首版不改动技能执行沙箱模型。
• 首版不改变安装后的运行权限边界。

设计概览

• 配置层：在根配置新增 skills_market 节点，管理 markets/cache/install。
• 后端层：新增 markets 配置读写、marketplace 聚合、marketplace install、市场预校验接口。
• 前端层：Skills 页面增加“已安装/市场”双视图与市场管理入口。
• 索引层：市场仓库默认使用 index.json，支持 schema_version=1。
• 聚合层：以 market_id + skill_id 作为复合主键，规避同名冲突。

兼容性

• 缺失 skills_market 时按空市场处理。
• 保留直接 URL 导入功能，作为回退路径。
• 未知字段透传，便于后续扩展。

迁移策略

• 不做一次性迁移脚本。
• 采用惰性默认值：读取时补齐，显式保存时回写。
• 通过现有 load_config/save_config 管道统一写入。

风险与缓解

• GitHub/API 限流：引入缓存 TTL + 手动 refresh。
• 远程市场不稳定：返回 market_errors，单市场失败不阻断整体。
• 索引格式不规范：条目级跳过并记录错误详情。
• 同名技能冲突：采用复合主键并在安装时进行冲突检测。

回滚策略

• 配置层：将 skills_market.markets 置空即可关闭市场聚合。
• 功能层：前端隐藏市场入口后仍可使用原有 URL 导入。
• 代码层：PR 按后端/前端拆分，可独立回滚。

交付与 PR 拆分

• PR-1（upstream）：配置模型、后端接口、聚合与缓存、测试。
• PR-2（upstream）：控制台市场视图、市场管理、i18n、回归测试。
• Local-only PR：默认市场 futuremeng/editor-skills（不进入 upstream）。

验收标准

• 可在控制台管理多个市场并持久化。
• marketplace 返回聚合条目与市场级错误。
• 可按 market_id + skill_id 安装并启用技能。
• 旧 URL 导入场景回归通过。
• 异常市场、超时、限流不影响整体可用性。

讨论点

• 索引协议是否仅支持 index.json，还是保留目录扫描兜底。
• 并发写配置是否首版即引入版本锁（建议二期）。

Hi maintainers and community,

We propose adding a Multi-Market Skills Marketplace to CoPaw. Today, importing skills from a single URL works well, but discoverability and market-level management are still limited.

This RFC proposes:

• Support multiple skill markets, where each market is a git repository.
• Allow users to add, edit, enable/disable, and reorder markets in the console.
• Add marketplace aggregation APIs that return installable items with market-level failure isolation.
• Install by market_id + skill_id to avoid cross-market name collisions.
• Keep current direct URL import fully available for backward compatibility.

Config persistence:

• Persist under ~/.copaw/config.json, aligned with existing working-directory rules.

Out of scope for v1:

• Signature verification, reputation scoring, or complex review workflows.
• Runtime sandbox model changes.

Planned delivery split:

• PR-1: backend config model + APIs + aggregation cache + tests.
• PR-2: console marketplace UI + market management + i18n + regression tests.
• Local-only: default market futuremeng/editor-skills stays in local branch and is not part of upstream defaults.

Feedback requested:

• Should we enforce index.json-only, or keep directory-scan fallback?
• Should config write version-locking be introduced in v1 or deferred to v2?
• Do we want a unified naming convention for API error codes and frontend messages?

If this direction is accepted, we will submit PRs in small, independently reviewable and revertible slices.

中文补充：
大家好，我们提议为 CoPaw 增加“多市场技能市场”能力。当前单 URL 导入可用，但在技能发现和市场级管理上还有提升空间。

RFC 主要内容：

• 支持多个技能市场，每个市场是一个 git 仓库。
• 控制台支持市场的新增、编辑、启停、排序。
• 新增聚合接口，返回可安装条目并支持市场级失败隔离。
• 通过 market_id + skill_id 安装，避免跨市场同名冲突。
• 保留现有 URL 导入路径，确保向后兼容。

配置落盘位置：

• ~/.copaw/config.json（遵循现有工作目录机制）。

首版不包含：

• 签名校验、信誉评分、复杂审核流。
• 运行时沙箱模型升级。

交付拆分：

• PR-1：后端配置模型 + API + 聚合缓存 + 测试。
• PR-2：控制台市场视图 + 市场管理 + i18n + 回归。
• Local-only：futuremeng/editor-skills 默认市场仅保留在本地分支，不进入 upstream。

欢迎重点反馈：

• 索引协议是仅 index.json，还是保留目录扫描兜底。
• 配置并发写版本锁是否应首版引入。
• 错误码与前端提示是否统一命名规范。

Upstream Reviewer Checklist (Bilingual)

• Scope boundary / 范围边界
  • Only generic multi-market capability is included.
  • No upstream default for futuremeng/editor-skills.
  • 仅包含通用多市场能力。
  • 不包含 futuremeng/editor-skills 的 upstream 默认配置。
• Config and compatibility / 配置与兼容
  • Config persists to ~/.copaw/config.json.
  • Missing skills_market behaves as empty markets with direct URL import still working.
  • Unknown fields do not break parsing.
  • 配置落盘到 ~/.copaw/config.json。
  • 缺失 skills_market 时行为等价空市场，且 URL 导入可用。
  • 未知字段不应导致解析失败。
• API contract / API 契约
  • /skills/markets read-write loop works.
  • /skills/marketplace returns both items and market_errors.
  • /skills/marketplace/install returns expected statuses for conflict/missing/remote failure.
  • /skills/markets 读写闭环可用。
  • /skills/marketplace 同时返回 items 与 market_errors。
  • /skills/marketplace/install 在冲突/缺失/远程失败场景返回可预期状态码。
• Isolation and stability / 失败隔离与稳定性
  • One failed market does not block others.
  • Cache-hit and refresh behaviors are verifiable.
  • Rate-limit failures are actionable and readable.
  • 单市场失败不影响其他市场。
  • 缓存命中与 refresh 行为可验证。
  • 限流错误可读且可定位。
• Frontend usability / 前端可用性
  • Skills page can manage market list (CRUD + enable/disable + reorder).
  • Marketplace items are installable with clear status feedback.
  • Legacy URL import path passes regression.
  • Skills 页面可管理市场列表（增删改 + 启停 + 排序）。
  • 市场条目可安装并有清晰状态回显。
  • 旧 URL 导入路径回归通过。
• Testing and rollback / 测试与回滚
  • Backend tests cover config, aggregation, and failure isolation.
  • Frontend tests cover market management and install flow.
  • PRs are independently revertible without breaking baseline skills behavior.
  • 后端测试覆盖配置、聚合、失败隔离。
  • 前端测试覆盖市场管理与安装流程。
  • PR 可独立回滚且不影响基础技能能力。

Relevant files

• roadmap.zh.md — 上游路线图依据（技能生态/安全）。
• skills.zh.md — 当前 skills hub/导入来源文档与用户行为预期。
• skills_hub.py — 现有 hub 查询/安装与 GitHub 拉取能力复用点。
• skills.py — 新增市场 API 与安装入口的首要改动点。
• config.py — 新增 skills markets 配置模型。
• utils.py — 配置读写与默认值处理复用。
• config.py — 若市场管理并入通用配置路由，此处新增读写接口。
• skill.ts — 市场列表、聚合、安装 API 客户端。
• skill.ts — MarketSpec/MarketplaceItem 类型扩展。
• index.tsx — 双视图 UI 与导入逻辑去硬编码。
• useSkills.ts — 数据加载、安装、状态刷新流程。
• zh.json — 新增市场管理与错误提示文案（并同步 en/ja/ru）。

Verification

1. 后端单测：市场配置读写、市场索引解析、多市场聚合、失败隔离、缓存命中/失效。
2. 接口联调：/skills/markets、/skills/marketplace、安装接口在空市场/失效市场/混合市场场景都返回可预期结构。
3. 前端验证：

• 新增市场后可立即看到市场技能列表。
• 多市场同名技能展示/安装规则一致且可解释。
• 旧的“直接 URL 导入”路径保持可用（回归）。

4. 安全回归：恶意 URL、非法协议、不可达仓库、超时、限流场景均不会导致控制台崩溃或后端阻塞。
5. 本地分支验证：默认 futuremeng/editor-skills 仅在 local 分支生效，upstream 分支无该默认项。