# 外部项目文档接入规范

HDF MCP 集中维护多个项目的后台操作说明。外部项目负责按本规范生成和核对文档，通过 HTTP API 上传；管理员也可以在后台页面编辑。上传后 MCP 即时使用新内容。所有接口免登录，不要求 Token，不调用外部项目的业务接口。

默认服务地址：`http://服务器地址:8505`。后台页面 `/`，MCP `/mcp`，健康检查 `/health`，本文 `/api/integration-guide`。

## 1. 生成规则

每个项目生成一个独立目录：

```text
my-project-docs/
  project.json
  create-exam.md
  review-course.md
```

`project.json` 示例：

```json
{
  "id": "online-edu",
  "name": "在线教育后台",
  "description": "课程、考试相关后台操作说明",
  "aliases": ["在线教育", "教育后台"],
  "operations": [
    {"id": "create-exam", "title": "新增在线考试", "summary": "准备、关键字段与提交检查"},
    {"id": "review-course", "title": "审核课程", "summary": "审核入口与结果核对"}
  ]
}
```

- 项目 ID、操作 ID：长度 1–80，只允许小写英文字母、数字、`-`、`_`；不可包含斜杠、点号或上级路径。同一项目内操作 ID 唯一；不同项目可以使用相同操作 ID。
- 文件名必须为 `<operationId>.md`，UTF-8 编码，直接放在 `project.json` 旁边。后台按“项目 → Markdown 文件”展示目录；当前不支持任意多级子目录或附件上传。
- 项目名称必填，最多 128 字符；说明最多 2000 字符；别名最多 20 个，每个最多 128 字符。
- 文档标题必填，最多 200 字符；摘要最多 2000 字符；正文不能为空，最多 100000 个 UTF-16 字符。每次 HTTP 请求体上限 2 MiB。
- 一份文档描述一项操作，包含适用项目、适用版本、审核状态、最后核对日期、前置条件、页面入口、操作步骤、字段说明、常见问题和依据。未确认的页面或业务规则明确标记待确认。
- 文档只写操作知识。原后台需要的权限在前置条件中说明；MCP 不取得后台账号，也不执行后台业务操作。
- 仓库的 `templates/example-project/` 提供可复制的模板。模板不自动进入正式知识库。

可交给外部项目的生成要求：

> 请依据本项目真实代码、页面和产品说明，生成符合 HDF MCP 规范的 project.json 及各操作的 Markdown 文件。项目和操作 ID 使用稳定的小写标识；一项操作一份文档，正文包含审核状态与来源。不要猜测不存在的功能，未确认项明确标记。完成业务核对后调用文档接收接口上传。

## 2. HTTP 接口

请求和响应使用 UTF-8 JSON。无需 Authorization 请求头。ID 在服务端校验，客户端不能指定服务器文件路径。

| 方法 | 路径 | 用途 |
|---|---|---|
| GET | `/api/projects` | 列出项目、别名及操作目录 |
| POST | `/api/projects` | 新增项目，请求含 `id/name/description/aliases`；重复 ID 返回 409 |
| GET | `/api/projects/{projectId}` | 获取单个项目与目录 |
| PUT | `/api/projects/{projectId}` | 新增或更新项目信息；保留现有文档 |
| DELETE | `/api/projects/{projectId}` | 删除整个项目及其文档目录 |
| GET | `/api/projects/{projectId}/documents` | 列出该项目的文档信息 |
| GET | `/api/projects/{projectId}/documents/{operationId}` | 获取文档，含 `projectId/id/title/summary/content` |
| PUT | `/api/projects/{projectId}/documents/{operationId}` | 上传或覆盖一份文档，JSON 中的 `content` 为 Markdown 正文 |
| DELETE | `/api/projects/{projectId}/documents/{operationId}` | 删除一份文档 |

先登记项目，再上传文档。项目 PUT 请求体不含 `operations`；每份操作文档通过独立的文档 PUT 接口登记。文档 PUT 会同时更新目录元数据和 Markdown 文件。PUT 可重复调用；没有出现在本次上传中的旧文档会保留，要删除时显式调用 DELETE。

创建 / 更新项目示例：

```http
PUT /api/projects/online-edu
Content-Type: application/json

{"name":"在线教育后台","description":"课程和考试操作说明","aliases":["教育后台"]}
```

上传一份文档示例：

```http
PUT /api/projects/online-edu/documents/create-exam
Content-Type: application/json

{"title":"新增在线考试","summary":"创建前准备和步骤","content":"# 新增在线考试\n\n审核状态：草稿\n\n## 前置条件\n..."}
```

成功：GET/PUT 返回 200，POST 返回 201，DELETE 返回 204。常见错误：400 参数不合法、404 项目或文档不存在、409 项目 ID 冲突、413 请求体过大。错误通常为 Problem Details JSON，`title` 说明原因。

## 3. 使用上传脚本

Windows PowerShell 5.1 或 PowerShell 7：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/import-docs.ps1 `
  -SourceDirectory D:/my-project-docs `
  -BaseUrl http://服务器地址:8505
```

脚本会先校验本地清单和全部 Markdown，再更新项目、逐份上传文档。上传不是跨文档事务，网络失败时已成功的文档会保留，修复后可以重跑。两个维护者同时保存同一文档时，以最后成功保存的内容为准。

也可以由外部项目的 CI 或业务程序直接调用以上 PUT 接口。MCP 不扫描其他项目的源码，不自动抓取 Swagger，也不自动生成业务说明。

## 4. 后台与 MCP 的关系

后台打开 `/`：可以新增、编辑、删除项目，查看项目文件目录，新建 / 编辑 / 导入 `.md` / 删除文档。导入文件后需点击保存。Markdown 以源码编辑，不执行其中的 HTML 或脚本。

MCP 只暴露四个读取工具：`list_projects`、`list_admin_operations`、`search_admin_help`、`get_operation_guide`。写入接口成功返回后，新请求会立即读取更新后的内容。MCP 工具本身不能增删文档。

## 5. 存储与运行约定

内容默认存放于服务目录的 `content`，可通过 `Content__Root` 指定；Docker 使用名为 `hdf-mcp-content` 的持久卷。数据结构为 `catalog.json` 和 `<projectId>/<operationId>.md`。删除后的文件移入同一卷的 `.trash`，不会再被 MCP 检索；当前没有回收站页面，恢复时可取出 Markdown 重新上传。

服务适用于单实例部署。进程内串行写入、目录原子替换及内存快照使并发读取不会看到写到一半的文档；不支持多个实例共同写同一目录。运行时请通过 API 或后台修改；手工改卷内文件后需要重启服务。重新发布保留已有数据卷，镜像内示例只在首次创建数据卷时用于初始化。发布前应备份持久卷；不要使用 `docker compose down -v`，它会移除文档数据卷。

MCP、管理 API 和后台页面均按要求免登录。能够访问服务的人都能管理文档；部署时请将 8505 的可达范围设为实际需要使用该服务的网络。
