# @agentcms/agentcms 中文文档

规范地址：https://npmcn.com/package/%40agentcms/agentcms/

版本：0\.10\.0
npm 元数据更新时间：2026-09-26T19:17:37.268Z
中文译文更新时间：2026-11-07T04:13:57.549Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentcms/agentcms
原文对照：https://npmcn.com/package/%40agentcms/agentcms/?lang=original
项目主页：https://github.com/agentcms/agentcms#readme
源码仓库：https://github.com/agentcms/agentcms

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：479 kB，109 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：astro ^6\.0\.0 \|\| ^7\.0\.0，@astrojs/cloudflare ^13\.0\.0 \|\| ^14\.0\.0
- 首次发布：2026-02-17T17:01:12.666Z
- 最新版本发布：2026-09-26T19:17:36.873Z
- 近 30 天下载量：2054（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Astro 6/7 + Cloudflare 的AI-代理首个无头CMS

## 安装

```sh
npm install @agentcms/agentcms
```

也可以使用：`pnpm add @agentcms/agentcms`、`yarn add @agentcms/agentcms`、`bun add @agentcms/agentcms`

## README

# 代理CMS系统

**Astro 6和7 + Cloudflare的AI-agent-first 无头 CMS.** 也作为普通工人或Pages中间软件运行,为不是Astro的网站.

Drop-in博客引擎 AI代理为一等内容作者. 存储在Cloudflare KV的帖子,通过Astro的活内容集服务,通过安全的API可写出机器可读技能的发现.

```bash
npm install @agentcms/agentcms
```

## 快速启动

```js
// astro.config.mjs
import agentcms from "@agentcms/agentcms";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  output: "server",
  adapter: cloudflare(),
  integrations: [
    agentcms({
      mode: "auto",      // "auto" = routes included, "headless" = you own pages
      basePath: "/blog",
      postsPerPage: 12,
    }),
  ],
});
```

就是这样。 你会得到:

-   `/blog` 职位指数
-   `/blog/[slug]` - 担任高级管理职位的个人员额
-   `/blog/tag/[tag]` - 标签页
-   `/feed.xml` ——RSS馈送
-   `/sitemap.xml` ——站点地图,有帖子和自有网页
-   `/robots.txt` ——机器人,指向站点地图
-   `/api/agent/*` ——为代理撰写API
-   `/api/posts`, (中文(简体) ), `/api/posts/[slug]`, (中文(简体) ), `/api/tags`, (中文(简体) ), `/api/categories` 公共读取API(JSON,已消毒);其中任何一项服务都是单独提供的(`publicApi: false` 关掉它们)
-   `/.well-known/agent-skill.json` ——人工智能特工技能发现

`/sitemap.xml`, (中文(简体) ), `/robots.txt` 财务报告和审定财务报表 `/feed.xml` 服务于 **两者** 模式 - 见 [SEO 路线](https://npmcn.com/package/%40agentcms/agentcms/#readme-seo-routes)。 。 。 .

## 代理如何发布

```python
import httpx

SITE = "https://your-blog.pages.dev"
API_KEY = "acms_live_..."

# 1. Discover capabilities
skill = httpx.get(f"{SITE}/.well-known/agent-skill.json").json()

# 2. Understand the site
context = httpx.get(f"{SITE}/api/agent/context",
    headers={"Authorization": f"Bearer {API_KEY}"}).json()

# 3. Publish
response = httpx.post(f"{SITE}/api/agent/publish",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "X-Agent-Model": "claude-sonnet-4-5-20250514",
    },
    json={
        "title": "My First AI-Written Post",
        "content": "# Hello World\n\nThis post was written by an AI agent...",
        "tags": ["ai", "demo"],
    })

print(response.json())
# {"success": true, "slug": "my-first-ai-written-post", "url": "..."}
```

### 移动已存在的归档

从另一个中央管理系统调出的员额应保留其原定日期——网址地图和 搜索引擎读取了今天的档案 作为全新的页面。 与一个 **管理员** 键, `publish` 财务报告和审定财务报表 `PUT /api/agent/posts/:slug` 接受 `publishedAt` 财务报告和审定财务报表 `updatedAt` (ISO 8601;无) 未来; `updatedAt` 默认为 `publishedAt`) (中文(简体) ). 其他瞄准镜是403.

日期需要时间和分区 : `2021-03-14T00:00:00Z` 或者说 `2021-03-14T10:00:00+01:00`。仅一个日期 `2021-03-14` (常见于较老的CMS) 出口)或无区 `2021-03-14T10:00:00` 是422 — 附录 `T00:00:00Z`, (中文(简体) ), 或来源自己的平分,在发送前.

```json
{ "title": "…", "content": "…", "slug": "old-slug",
  "publishedAt": "2021-03-04T05:06:07Z", "updatedAt": "2022-01-10T09:00:00Z" }
```

### 语文

一个用几种语言出版的网站在它的配置中列出它们,默认为第一:

```json
{ "name": "My blog", "languages": ["en", "de"] }
```

每个翻译都是自己的职位 `lang` 和共享的 `translationKey`数字 :

```json
{ "title": "Hallo Welt", "content": "…", "lang": "de", "translationKey": "hello-world" }
```

A 类 `lang` 外部 `languages` 是一个422, 和第二个使用同一语言的文章 一个 `translationKey` 是一个409。 没有 `lang` 计为默认值 语言. `GET /api/posts/:slug` 返回时 `translations` (每种语言版本), `/api/posts?lang=de` 过滤器和内置的后页集 `<html lang>` 财务报告和审定财务报表 `hreflang` 候补委员.

### 其他员额领域

-   `metadata`:供您自用的自由式JSON(最大为16KB),例如源代码或a 赞助商。 它被储存并归还,从未交付。 经更新后,将整体替换.
-   `ogImage`, (中文(简体) ), `featuredImage`, (中文(简体) ), `canonicalUrl`:绝对 http(s) URL. 上传 返回绝对值 `url` (加上与网站有关的 `path`),因此可以直接使用.
-   `noindex`: 将帖子置出站点地图并添加 `robots: noindex`。 。 。 .
-   关于最新消息, `null` 清除 `featuredImage`, (中文(简体) ), `ogImage`, (中文(简体) ), `canonicalUrl`, (中文(简体) ), `lang` 财务报告和审定财务报表 `translationKey`。 。 。 .

## 阅读文章

### 现场内容收集(Astro 6.4+/7)

```ts
// src/live.config.ts
import { defineLiveCollection } from "astro:content";
import { agentcmsLoader } from "@agentcms/agentcms/loader";

export const collections = {
  posts: defineLiveCollection({ loader: agentcmsLoader() }),
};
```

```astro
---
import { getLiveEntry } from "astro:content";
const { entry } = await getLiveEntry("posts", Astro.params.slug!);
if (!entry) return new Response("Not found", { status: 404 });
Astro.cache.set(entry); // cache tags + lastModified, when a cache provider is configured
---
<article set:html={entry.rendered?.html} />
```

在没有选项的情况下,加载器会读取该网站自己的KV. `agentcmsLoader({ url: "https://cms.example.com" })` 阅读了另一个AgentCMS 在它的公开API之上, 它的工作从任何Astro主机, 包括一个静态建筑. `getLiveCollection("posts", { lang, tag, category, since, limit, page })` 过滤器.

### 缓存无效

条目和内置页面带有缓存标签 `agentcms:posts` 财务报告和审定财务报表 `agentcms:post:<slug>`。使用 Astro 的路由缓存配置(例如) `cacheCloudflare` 从 `@astrojs/cloudflare/cache`),每份出版物、更新或 通过代理 API 删除这些标记 。 没有供货商,这没什么用.

### 在建设时停车

`GET /api/posts?full=1` 返回每个已转换、已消毒的站点 `contentHtml`。 。 。 . 添加 `since=<ISO date>` 以获取自您上次建设以来更改的帖子 .

## 没有Astro

独立工作者(约束: `AGENTCMS_KV`,以及 `AGENTCMS_R2` 用于上传 :

```ts
// src/index.ts
import { createAgentCMSWorker } from "@agentcms/agentcms/worker";
export default createAgentCMSWorker({ cors: "https://www.example.com" });
```

作为 Cloudflare Pages 中间软件:

```ts
// functions/_middleware.ts
import { agentcmsMiddleware } from "@agentcms/agentcms/cloudflare";
export const onRequest = agentcmsMiddleware();
```

两个都为API特工服务,公共API, `/images/*`,站点地图,机器人.txt和 技术文件。 网约车的交货情况 `waitUntil`,然后在回复发出后完成.

## 无头模式

仅使用 AgentCMS 作为数据层 + API :

```js
agentcms({ mode: "headless" })
```

然后建立自己的页面:

```astro
---
import { BlogList, BlogPost } from "@agentcms/agentcms/components";
import { getAgentCMSPosts } from "@agentcms/agentcms";

const { posts } = await getAgentCMSPosts({ limit: 10, tag: "ai" });
---

<BlogList posts={posts} layout="grid" columns={2} />
```

无头模式给你构建的博客路径. 没错 **没有** 带走 `/sitemap.xml`, (中文(简体) ), `/robots.txt` 或者说 `/feed.xml` - 见下文.

## SEO 路线

`/sitemap.xml`, (中文(简体) ), `/robots.txt` 财务报告和审定财务报表 `/feed.xml` 两种服务 `auto` 财务报告和审定财务报表 `headless` 模式。 在0.9.0之前,它们只注射到 `auto` 模式时 构建日志在每一种模式中宣布它们,所以无头站点没有发送站点映射和 建筑日志上说不同。 3个生产点运行了几个月.

网站地图列出您自己的 **静态** 网页以及CMS的帖子。 写着 由 Astro 解析的路径显示, 因此您添加的一页静态显示而不显示 配置,与 `base` 财务报告和审定财务报表 `trailingSlash` 应用.

无法列出的内容 :

-   **动态路线** (单位:千美元)`/guides/[slug]`) (中文(简体) ). Astro报告模式,永远不要 已生成的 URL, 因此没有设置 `<loc>`。点播者没有 一套固定的 URL; 用于 **已放弃** 那些建筑曾用名警告你们, 因为一个网站图 悄悄地忽略了一个网站的全部内容 比没有更糟糕 网站地图。 如果那是你的形状,你自己写 `src/pages/sitemap.xml.ts` —— 说 你知道怎么统计,我们不知道.
-   个人邮递URL(它们应请求时间来自KV指数), `/404`, (中文(简体) ), `/500`,并页码提供了另一个整合.

没有 `hreflang`/换位支持.

**如果你想拥有其中一条路**只要创造它。 A 类 `src/pages/sitemap.xml.ts` (单位:千美元)`.astro`, (中文(简体) ), `.mdx` 编辑 `sitemap.xml/index.ts` 目录表数也), a `public/robots.txt`,或一个 `redirects` 输入 `astro.config` 使CMS特工站出来走这条路 而不是与之相撞 你,建筑日志说 两者中哪一个服务:

```
  Sitemap: /sitemap.xml
  Robots:  /robots.txt (your own — AgentCMS did not inject one)
  Feed:    /feed.xml
```

探测器只能看见你的回扣 Cloudflare 区域方向调整或手写 `functions/` 其中一条路径的处理器是看不见的,所以日志行 说明AgentCMS注入了什么,不是经过核实的获取.

关掉一个 `sitemap: false`, (中文(简体) ), `robots: false` 或者说 `rss: false`无 然后为那条路而服务,那座建筑就为你们而警告你们 没有可取取的站点地图 是一个搜索引擎必须猜测。 与 `sitemap: false`, (中文(简体) ), `robots.txt` 停止广告a `Sitemap:` 线条而不是 指着404.

## 样式

默认为0-opinion. CSS 自定义属性的主题 :

```css
:root {
  --acms-font-heading: "Inter", sans-serif;
  --acms-color-accent: #8b5cf6;
  --acms-radius: 0;
}
```

或目标数据直接属性 : `[data-acms-post-card] { ... }`

## 设置

```bash
npx @agentcms/agentcms init      # Create KV namespace instructions
npx @agentcms/agentcms keygen    # Generate agent API keys
npx @agentcms/agentcms seed      # Sample posts
npx @agentcms/agentcms migrate   # Bulk-import HTML posts into KV
```

## 许可证

麻省理工学院 - [MC2 风险投资](https://github.com/agentcms)

## 常见问题

### @agentcms/agentcms 是什么？

Astro 6/7 \+ Cloudflare 的AI-代理首个无头CMS

### 如何安装 @agentcms/agentcms？

在项目目录运行 npm install @agentcms/agentcms，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agentcms，可以用 npx agentcms 直接运行。

### @agentcms/agentcms 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentcms/agentcms 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentcms/agentcms 可以商用吗？

@agentcms/agentcms 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentcms/agentcms 的下载量有多少？

根据 npm 官方下载统计，@agentcms/agentcms 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,054 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentcms/agentcms 还在维护吗？

最新版本 0\.10\.0 发布于 2026/09/27（1 个月前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/02/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。