KOC LOOP

KOC 内容分发与数据回收闭环，运行于 vinext、Cloudflare D1 和 R2。

Prerequisites

• Node.js >=22.13.0

Quick Start

npm install
npm run dev
npm run build

复制 .dev.vars.example 为 .dev.vars 并配置运行时变量。飞书动态导入需要：

• FEISHU_APP_ID
• FEISHU_APP_SECRET

飞书自建应用需开通电子表格读取、知识库节点读取和云文档素材下载权限， 并将应用添加到目标知识库或电子表格的文档应用中。

后台登录首次启动还需要配置：

• SUPER_ADMIN_USERNAME：唯一的超级管理员登录账号
• SUPER_ADMIN_PASSWORD：超级管理员初始密码，至少 8 位
• ADMIN_INTERNAL_TOKEN：自动采集等内部任务使用的服务密钥
• KOC_MCP_API_KEY：Agent 调用 KOC LOOP MCP 使用的独立 Bearer 密钥

系统首次登录时创建唯一的超级管理员。后续管理员和普通用户均由“用户管理”页面创建，普通用户不能访问 KOC 资源库。

This starter does not use wrangler.jsonc.

Included Shape

• edit site code under app/
• .openai/hosting.json declares optional Sites D1 and R2 bindings
• vite.config.ts simulates declared bindings for local development
• db/schema.ts starts intentionally empty
• examples/d1/ contains an optional D1 example surface
• drizzle.config.ts supports local migration generation when needed

后台账号与角色

• 超级管理员：唯一系统管理员，可管理管理员和普通用户。
• 管理员：可访问全部业务模块，可创建和重置普通用户账号。
• 普通用户：可使用工作台、任务、内容分发和数据回收，不可查看或导出 KOC 资源库。

后台不提供注册、找回密码和普通用户个人改密。密码重置统一由管理员在后台完成。

Agent MCP

生产地址：

https://你的-KOC-LOOP-后台域名/api/mcp

MCP 使用独立的 KOC_MCP_API_KEY 鉴权，请通过请求头发送：

Authorization: Bearer <KOC_MCP_API_KEY>

首期只开放 create_distribution_task，用于读取飞书表格并创建分发任务。参数如下：

• feishu_url：飞书 Wiki 或电子表格链接；多工作表时必须带目标 sheet 参数
• task_name：任务名称
• due_date：北京时间截止日期，格式 YYYY-MM-DD
• brand_project：可选，品牌或项目名称；未提供时记录为“未设置项目”

成功后返回任务 ID、笔记数量和 KOC 领取链接。完全相同的任务参数重复调用时，返回已经存在的任务，避免 Agent 重试产生重复任务。

在支持远程 MCP 的 Agent 中添加：

{
  "mcpServers": {
    "koc-loop": {
      "url": "https://你的-KOC-LOOP-后台域名/api/mcp",
      "headers": {
        "Authorization": "Bearer ${KOC_LOOP_MCP_API_KEY}"
      }
    }
  }
}

使用示例：

用这个飞书表格创建发布任务：<飞书链接>。
任务名“8月骑手招募”，截止时间 2026-08-20。
创建后把 KOC 领取链接发给我。

密钥不要写入仓库、对话内容或 URL 查询参数，生产环境通过站点密钥管理配置。

Useful Commands

• npm run dev: start local development
• npm run build: verify the vinext build output
• npm test: build the starter and verify its rendered loading skeleton
• npm run db:generate: generate Drizzle migrations after schema changes

Learn More

• vinext Documentation
• Drizzle D1 Guide