Artifact Hub

Artifact Hub 是一个面向团队的 Agent 知识库和 MCP Server。它用 Git 保存可复用知识产物，向 IDE 和 Agent 暴露 MCP 工具，并提供 Dashboard 来查看知识、评审任务和使用度。

它可以继续作为旧版 skill registry 使用，也可以作为中心化的 AI 知识库，沉淀 Agent 每次会话里产生的 skill、spec、plan、review 和 adr。

快速开始

npm install
npm run build
node packages/server/src/cli.js start --port 3721 --root .

服务启动后会打印访问 Token，并暴露：

• Dashboard: http://localhost:3721

• REST API: /api/*

• MCP HTTP endpoint: /mcp

在 Dashboard 中输入启动时打印的 Token 即可连接。

Related MCP server: jt-mcp-server

全局安装

在仓库根目录执行：

npm link

之后本机可以直接使用 artifact-hub 命令，也可以在其他项目中通过 npx artifact-hub 调用。

中心化 Agent 知识库

团队可以把 Artifact Hub 作为一个中心化 MCP Server 部署。Git 中的 knowledge/** 是事实源：

knowledge/
  skill/<id>.md
  spec/<id>.md
  plan/<id>.md
  review/<id>.md
  adr/<id>.md

支持的知识产物类型：

• skill: 可复用操作技能、工程规范、工具使用方法。

• spec: 产品、接口、流程、数据模型等规格说明。

• plan: 可复用执行计划、迁移计划、实施步骤。

• review: 代码评审、方案评审、风险评审沉淀。

• adr: 架构决策记录，包括决策状态和被替代决策。

Agent 推荐工作流：

1. 首次接入时调用 get_agent_instructions 获取团队知识库使用规则。

2. 开始较大任务时调用 session_start 记录会话。

3. 产出可复用内容前调用 search_artifacts，避免重复造知识。

4. 命中相关知识后调用 get_artifact 加载完整内容。

5. 产生新的可复用 skill、spec、plan、review 或 adr 后，调用 create_artifact 或 update_artifact 保存。

6. 结束任务前调用 session_end，让系统记录本次会话沉淀了哪些产物。

如何让 Agent 主动使用

artifact-hub install 会把 MCP 配置和 Agent 指令写入项目支持的 IDE/Agent 配置位置，例如：

• Claude Code: CLAUDE.md

• Codex / 通用 Agent: AGENTS.md

• Cursor: .cursor/rules/knowledge-hub.mdc

这些指令会要求 Agent 在开始可复用工作前先检索知识库，在产出可复用内容后保存知识产物。MCP Server 也提供 get_agent_instructions 工具，供支持动态工具调用的 Agent 在运行时再次拉取规则。

使用度会记录到 .artifact-hub/usage.json，Dashboard 的“使用度”页面可以看到 Agent 的 session、search 和 write 统计，用于观察团队是否真的在复用知识库。

安装到 IDE

一键写入 MCP 配置和 Agent 指令：

artifact-hub install --server http://localhost:3721 --token <token>

也可以只生成某个 IDE 的 MCP 配置：

node packages/server/src/cli.js init-ide --ide cursor --server http://localhost:3721 --token <token>
node packages/server/src/cli.js init-ide --ide claude --server http://localhost:3721 --token <token>

Cursor 会写入 .cursor/mcp.json，Claude Code 会写入 .mcp.json。配置会指向 MCP HTTP endpoint：

{
  "mcpServers": {
    "team-artifact-hub": {
      "url": "http://localhost:3721/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

如果 IDE 只支持 stdio bridge，可以生成代理配置：

node packages/server/src/cli.js init-ide --transport stdio --ide cursor --server http://localhost:3721 --token <token>

知识产物格式

每个知识产物都是带 frontmatter 的 Markdown 文件：

---
id: api-contract
type: spec
title: API Contract
status: active
version: 1.0.0
author: agent
owner: platform
description: REST API contract rules.
tags:
  - api
  - backend
aliases:
  - rest contract
related_artifacts:
  - adr/http-style
applicable_projects:
  - billing-service
source_conversation_id: session-1
review_policy: reviewer
risk: medium
created_at: 2026-08-20T00:00:00.000Z
updated_at: 2026-08-20T00:00:00.000Z
---

# API Contract

Use resource-oriented URLs and stable response envelopes.

通用字段包括：

• id, type, title, status, version

• author, owner, description

• tags, aliases, related_artifacts

• applicable_projects, source_conversation_id

• review_policy, risk, created_at, updated_at

skill 额外支持 triggers 和 eval_cases；adr 额外支持 decision_status 和 supersedes。

MCP 工具

通用知识库工具：

• get_agent_instructions: 获取 Agent 必须遵守的知识库使用规则。

• session_start: 记录 Agent 会话开始。

• session_end: 记录 Agent 会话结束和本次沉淀。

• search_artifacts: 按类型、项目、标签、别名、状态和关键词检索知识产物。

• get_artifact: 读取完整知识产物。

• get_related_artifacts: 获取关联知识产物推荐。

• create_artifact: 新建知识产物。

• update_artifact: 更新知识产物。

• archive_artifact: 归档知识产物。

• delete_artifact: 删除知识产物。

• get_artifact_history: 查看 Git 历史。

• get_artifact_diff: 查看版本差异。

• rollback_artifact: 回滚到指定 Git ref。

• validate_artifact: 运行规则型 Reviewer 检查。

• propose_artifact_change: 提交知识产物变更评审。

• list_review_tasks: 查看评审任务。

• review_artifact: 记录批准、拒绝或升级。

• evaluate_artifact: 对 skill 类型运行 eval cases。

• get_git_status: 查看知识库 Git 状态。

兼容旧 skill API 的工具仍然保留：

• search_skills

• get_skill

• create_skill

• update_skill

• propose_skill_update

• evaluate_skill

• save_artifact

Dashboard

Dashboard 现在以知识库为主入口：

• “知识库”页面：检索和查看 skill/spec/plan/review/adr。

• “评审”页面：查看 pending review task，并执行批准或拒绝。

• “使用度”页面：查看 Agent 的会话、检索和写入统计。

• “设置”页面：查看 MCP 配置，切换严格审批或开放写入。

迁移

旧版 skills/*.md 可以迁移到新的知识库目录：

artifact-hub migrate --root .

命令会把旧技能写入 knowledge/skill/*.md，保留原始内容，并在 frontmatter 中标记迁移信息。

治理

服务默认是严格模式：

• 高风险或需要评审的 artifact 写入会进入 .artifact-hub/reviews/。

• Maintainer 可以在 Dashboard 的“评审”页面批准或拒绝。

• 设置保存在 <root>/.artifact-hub/settings.json。

切换到开放模式后，新增和修改会直接写入 Git-backed knowledge store。

开发

分别启动 API Server 和 Vite Dev Server：

node packages/server/src/cli.js start --port 3721 --root .
npm run dev

Vite 运行在 http://localhost:5173，并把 /api 代理到后端。

架构

• packages/core: artifact frontmatter、索引、Git service、store、review、session usage、eval。

• packages/mcp-server: JSON-RPC MCP router、HTTP gateway、stdio proxy。

• packages/server: REST API、SSE、静态 Dashboard、CLI。

• packages/web: React + Vite Dashboard。

测试

npm test
npm run build

许可证

本项目使用 MIT License，详见 LICENSE。

常用命令

node packages/server/src/cli.js start --port 3721 --root .
artifact-hub install --server http://localhost:3721 --token <token>
artifact-hub migrate --root .
node packages/server/src/cli.js mcp-proxy --server http://localhost:3721 --token <token>