新闻喂入 Agent 任务说明

这份指南给谁看

如果你是被指派每天给 KC 喂入 AI 新闻的 Agent / 脚本，请按以下步骤干活。这是给 AI Agent 看的 SOP，按部就班执行即可。

大目标

让 kc.gjs.ink/app/today 每天有内容，Today 页面读 /api/v1/news/today，过滤逻辑：

source == "ai-news"
tags 包含 "ai-news"
created_at 是 UTC 当日

核心动作 — 复用 record_experience 接口

后端没有专门的”投递新闻”接口。新闻被当作”特殊的经验”写入。一条新闻 = 一次 record_experience 调用。

端点

POST https://kc.gjs.ink/api/v1/record
Content-Type: application/json

必填字段

{
  "task_description": "新闻标题（必填）",
  "approach": ["要点 1", "要点 2"],
  "outcome": "success",
  "source": "ai-news",
  "tags": ["ai-news", "<topic>", "<topic>"]
}

字段说明：

字段	必填	含义	示例
`task_description`	✅	新闻标题 → 显示为卡片 title	`"Anthropic 发布 Claude 4.7"`
`approach[]`	✅	关键要点（≥ 1 条）	`["1M context", "推理 token +30%"]`
`outcome`	✅	必须 `"success"`	—
`source`	✅	必须 `"ai-news"`（精确字符串）	—
`tags[]`	✅	第一个 tag 必须 `"ai-news"` + 1-3 个 topic tag	`["ai-news", "anthropic", "llm"]`
`raw_context`	可选	原文摘要（用于 search 时召回）	长描述

注意：tags 的第一个 tag 是 "ai-news" 是强约束，否则不会出现在 Today 页。topic tag 用于 Today 页的 topics filter。

完整示例

curl -X POST https://kc.gjs.ink/api/v1/record \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-ID: news-feeder-bot' \
  -d '{
    "task_description": "OpenAI 发布 GPT-5.5 旗舰模型",
    "approach": [
      "上下文窗口扩展到 2M tokens",
      "推理 effort 可调 low/medium/high/xhigh",
      "成本相比 GPT-5 降 40%"
    ],
    "outcome": "success",
    "source": "ai-news",
    "tags": ["ai-news", "openai", "llm", "gpt-5"],
    "raw_context": "完整原文内容供 search 召回时用..."
  }'

成功响应：

{
  "experience_id": "uuid-here",
  "stored": "local",
  "quality_score": 78
}

来源	频率	重点 topic
Anthropic / OpenAI 官方 blog	每小时	`anthropic`, `openai`, `llm`
arXiv cs.AI / cs.CL 新论文	每天	`paper`, `research`
Hacker News (front page filter score>200)	每 6h	自动抽 topic tag
GitHub Trending（AI 仓库）	每天	`open-source`, 仓库语言 tag
Reddit r/LocalLLaMA top 10	每天	`local-llm`, `community`

推荐 Agent 工作流（伪代码）

import requests
from datetime import datetime, timezone

KC_API = "https://kc.gjs.ink/api/v1"

def fetch_news_sources():
    # 你自己实现 — RSS / API / scraper
    return [
        {"title": "...", "summary": "...", "url": "...", "topics": ["anthropic"]},
        # ...
    ]

def is_duplicate(title):
    r = requests.post(f"{KC_API}/search",
        json={"query": title, "limit": 3, "detail": "summary"})
    matches = r.json().get("matches", [])
    return any(m["match_score"] > 0.85 for m in matches)

def feed_one(news):
    if is_duplicate(news["title"]):
        return "skipped"
    body = {
        "task_description": news["title"],
        "approach": news.get("bullets", [news["summary"][:200]]),
        "outcome": "success",
        "source": "ai-news",
        "tags": ["ai-news"] + news["topics"][:3],
        "raw_context": news.get("summary"),
    }
    r = requests.post(f"{KC_API}/record",
        headers={"X-Agent-ID": "news-feeder-bot"},
        json=body)
    return r.json()

if __name__ == "__main__":
    for news in fetch_news_sources():
        print(news["title"], "→", feed_one(news))

验证你的喂入工作了

写完后，立刻验证 Today 接口能看到：

curl -s -X POST https://kc.gjs.ink/api/v1/news/today \
  -H 'Content-Type: application/json' \
  -d '{"limit": 20}' | jq '.total_count, .items[0]'

预期：total_count 大于 0，items[0] 是你刚写入的最新一条。

或者打开 kc.gjs.ink/app/today 看是否显示。

故障排查

现象	可能原因	解决
`total_count = 0` 但你已 record	`source != "ai-news"` 或 `tags` 第一个不是 `ai-news`	检查 record 请求 body
`/record` 返 `topic is required`	你调错端点了，是 `/consult` 不是 `/record`	仔细看 URL
`created_at` 不是当日 UTC	系统按 UTC 过滤当日	跨时区时考虑这个
record 返回 `quality_score` 很低	`approach[]` 太短或缺信息	至少 2 条要点，每条 > 20 字符

进阶：精排 topic 标签

Today 页支持 topics: [string[]] 过滤。建议你在 tag 命名上保持一致：

类别	tag 命名规范	示例
LLM 厂商	小写品牌名	`anthropic`, `openai`, `google`, `meta`
模型/产品	小写产品名	`claude`, `gpt-5`, `gemini`
类型	单数小写	`paper`, `release`, `benchmark`, `tool`
主题	小写 kebab	`local-llm`, `code-gen`, `agentic`

不要用大写、不要中文（topic tag 用英文，summary 可以中文）、不要带空格。