121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# KOC LOOP
|
||
|
||
KOC 内容分发与数据回收闭环，运行于 vinext、Cloudflare D1 和 R2。
|
||
|
||
## Prerequisites
|
||
|
||
- Node.js `>=22.13.0`
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
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
|
||
|
||
生产地址：
|
||
|
||
```text
|
||
https://你的-KOC-LOOP-后台域名/api/mcp
|
||
```
|
||
|
||
MCP 使用独立的 `KOC_MCP_API_KEY` 鉴权，请通过请求头发送：
|
||
|
||
```text
|
||
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 重试产生重复任务。
|
||
|
||
同时开放以下运营工具：
|
||
|
||
- 任务：`task_list`、`task_get`
|
||
- 数据回收：`recovery_list`、`recovery_export`
|
||
- 数据采集：`collection_plan_set`、`collection_run_due`、`collection_collect_now`、`collection_retry_failed`
|
||
- KOC 资源：`resource_search`、`resource_get`、`resource_backfill_profile`、`resource_export`
|
||
|
||
`recovery_export` 和 `resource_export` 返回 15 分钟有效的安全下载链接。链接不包含 MCP 密钥；任务数据导出会继续把笔记原图、发布截图和创作者截图直接嵌入 Excel。
|
||
|
||
在支持远程 MCP 的 Agent 中添加：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"koc-loop": {
|
||
"url": "https://你的-KOC-LOOP-后台域名/api/mcp",
|
||
"headers": {
|
||
"Authorization": "Bearer ${KOC_LOOP_MCP_API_KEY}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
使用示例：
|
||
|
||
```text
|
||
用这个飞书表格创建发布任务：<飞书链接>。
|
||
任务名“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](https://github.com/cloudflare/vinext)
|
||
- [Drizzle D1 Guide](https://orm.drizzle.team/docs/get-started/d1-new)
|