# Artifact Hub

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

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

## 快速开始

```bash
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 即可连接。

## 全局安装

在仓库根目录执行：

```bash
npm link
```

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

## 中心化 Agent 知识库

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

```text
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 指令：

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

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

```bash
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：

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

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

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

## 知识产物格式

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

```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` 可以迁移到新的知识库目录：

```bash
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：

```bash
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。

## 测试

```bash
npm test
npm run build
```

## 许可证

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

## 常用命令

```bash
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>
```