# Kimi 模型状态追踪工具方案

## 结论

有必要做，但不建议一开始做成“全网爬虫”或自动改写所有项目配置的系统。

最值得做的是一个小型、可审计的 **Kimi model registry + Kimi Code release snapshot/diff 工具**：定期读取官方模型文档、API `/models` 和 Kimi Code 的官方发版/文档来源，保存原始快照，规范化成模型与产品事实表，输出新增、变更、退役、发版和来源冲突报告。

它解决的是“事实变化容易漏掉”这个问题，而不是替人做最终判断。

## 为什么值得做

Kimi 型号的变化会同时影响多个地方：

- 开源项目里的 builtin model map；
- provider preset 和模型选择器；
- context / output token 限制；
- thinking、reasoning、vision、tool calling 能力；
- 退役迁移和默认模型建议；
- 对外 PR、issue 和合作沟通中的事实表述。
- Kimi Code 的 CLI 版本、默认行为、协议变化和迁移要求。

手工搜索很容易出现三种错误：把旧型号当当前型号、把第三方代理的能力当官方 API 能力、把 default 当 hard cap。一个保留历史快照并生成 diff 的工具，价值比单次查询高得多。

## 建议的最小数据模型

每个 `model_id` 保存一条当前记录和来源信息：

```yaml
model_id: kimi-k3
canonical_family: kimi-k3
status: active # active | deprecated | retired | alias | unknown
context_window: 1000000
max_output: 131072
max_output_semantics: default # default | hard_cap | provider_limit | unknown
capabilities:
  vision: true
  reasoning: true
  tool_calling: true
  structured_output: true
  temperature: false
reasoning_options: [low, high, max]
source_records:
  - url: https://platform.kimi.ai/docs/models
    observed_at: 2026-08-25
    source_kind: official_docs
confidence: confirmed
notes: "K3 API default; platform allows a higher maximum."
```

需要把“官方模型 ID”和“代理模型 ID”分开。比如 `moonshotai/kimi-k3`、`accounts/fireworks/models/kimi-k3` 可以关联到同一 family，但不能直接覆盖官方 API 的限制。

## Kimi Code 发版记录

模型状态和 Kimi Code 发版要分成两类记录。模型记录回答“服务端有什么”；发版记录回答“开发者拿到的客户端/代理工具变了什么”。两者可能不同步：CLI 可能先支持新的模型别名，也可能只改安装、认证、工具调用或默认参数。

建议的最小发版记录如下：

```yaml
product: kimi-code
release_id: "@moonshot-ai/kimi-code@X.Y.Z" # 保留官方 raw release/tag id
version: X.Y.Z # 规范化字段，供排序和比较
status: released # released | prerelease | yanked | unknown
published_at: YYYY-MM-DD
source_records:
  - url: https://...
    observed_at: YYYY-MM-DD
    source_kind: official_release
changes:
  - category: model-routing # model-routing | protocol | auth | tools | install | bugfix | docs
    summary: "..."
    impact: potentially_breaking # none | additive | behavior_change | potentially_breaking | breaking | unknown
    affected_models: [kimi-k3]
    migration: "..."
confidence: confirmed
```

发版 diff 至少要提取或人工标注：

- 版本号、发布日期、release/tag/commit；
- raw tag 名称和规范化版本号必须同时保存，不能把 `@moonshot-ai/kimi-code@0.40.1` 丢失为单纯的 `0.40.1`；
- 新增、删除或重命名的模型 ID；
- 默认模型、默认 reasoning/thinking 行为是否变化；
- API endpoint、请求字段、认证方式和配置文件格式是否变化；
- tool calling、MCP、文件/图片输入等能力是否变化；
- 安装渠道、包管理器或二进制分发是否变化；
- 是否有 breaking change、迁移说明、回滚或 yanked release；
- 对外部项目 builtin map、provider preset 或文档的潜在影响。

如果 release note 只有一句话，工具应保留“变更未展开”状态，而不是自行补全技术细节。

## 数据源分层

### 第一层：官方文档

- 官方模型列表；
- Chat Completions / Responses 参数参考；
- 退役和迁移公告；
- 官方 pricing（如果需要成本字段）。

这是发布对外事实时的首选来源。

### 第二层：官方 API `/models`

API 返回可用模型 ID 时，记录原始响应和抓取时间。它适合回答“现在这个 endpoint 能列出什么”，但不能单独证明所有 token limit 或能力字段。

### 第三层：第三方 registry 和代理目录

例如 models.dev、OpenRouter、Fireworks、Cloudflare 等。它们适合发现别名、托管版本和代理差异；发生冲突时应保留冲突，不要静默覆盖官方记录。

### Kimi Code 发版源

发版源应做成可配置 adapter，但现在已经可以确认 Kimi Code 的官方主源：

- 官方代码仓库：<https://github.com/MoonshotAI/kimi-code>
- 官方 Releases/Tags：<https://github.com/MoonshotAI/kimi-code/releases>
- 官方用户文档 changelog：<https://www.kimi.com/code/docs/kimi-code-cli/release-notes/changelog.html>
- 仓库内详细 changelog：<https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/CHANGELOG.md>

截至 2026-09-03，GitHub Releases 页面显示最新 release/tag 为 `@moonshot-ai/kimi-code@0.40.1`，并提供各平台归档和校验文件；官方文档 changelog 同步列出 `0.40.1（2026-09-02）` 和 `0.40.0（2026-09-02）`。因此第一版可以直接以 GitHub Releases 作为版本发现与资产来源，以官方文档 changelog 作为面向用户的变更语义来源，再用仓库 `apps/kimi-code/CHANGELOG.md` 补充详细条目。

其他来源仍可做成可选 adapter，但不能替代上述主源：

- 官方包管理器或二进制发布页；
- 官方公告中明确指向某个版本的更新说明；
- 第三方 registry、代理商目录和社区 changelog（仅用于发现和交叉核对）。

只有上面的官方仓库、Releases/Tags、官方文档和仓库 changelog 才可标记为 `official_release` / `official_changelog`。第三方包镜像、社区 changelog 和用户反馈可以作为发现线索，但不能单独推动当前状态更新。

## 工具输出

第一版只需要三个命令：

```text
kimi-models snapshot       抓取并保存原始响应
kimi-models diff            对比最近两次快照，输出新增/变更/退役/冲突
kimi-models report          生成 Markdown 报告和可复制的模型表
kimi-code releases          抓取 Kimi Code 发版和 changelog 快照
kimi-code diff              输出版本、协议、默认行为和迁移变化
kimi-code report            生成面向外部项目维护者的影响摘要
```

报告应该优先展示“需要人工确认”的变化，例如：

- active → retired；
- context 或 output 改变；
- 官方文档和 `/models` 不一致；
- 同一 slug 在不同代理上的限制不同；
- 新出现但没有官方文档说明的模型。
- Kimi Code 新版本改变默认模型、请求协议或工具行为。
- release note 与实际 tag/package 内容不一致。
- 版本被撤回、标记 prerelease，或连续抓取失败导致状态可能过期。

## 和 repo-signal 的边界

这个工具可以为 repo-signal 提供研究输入，但不能自动把未经审核的结果写入：

- `docs/context/kimi-current-state.md`；
- `data/interactions.yaml`；
- Feishu CRM / Bitable；
- 外部 GitHub PR 或 issue。

推荐流程是：

```text
抓取模型/发版快照 → 生成 diff → 人工确认 → 更新 current-state brief 或 release ledger → 再决定是否改外部项目 PR
```

`kimi-current-state.md` 仍然是人工审核后的模型与产品事实入口；工具生成的原始数据和报告应放在 gitignored 的 runtime 目录，或作为明确标记的研究产物。若发版历史变长，可以另设只追加的 `transcripts/` 或 `docs/` release ledger，避免把完整 changelog 塞进 current-state brief。

## 分阶段实现

### Phase 1：本地、只读、可复现

- 一个小脚本或 Go/Node CLI；
- 官方文档 URL + `/models` endpoint 配置化；
- 保存带时间戳的原始 JSON/HTML；
- 规范化 active/deprecated/retired、context、output、capabilities；
- 生成 Markdown diff。
- 先支持 `MoonshotAI/kimi-code` Releases/Tags 和官方文档 changelog；对未来新增渠道仍输出 `source_unverified`，直到确认其 canonical 身份。

### Phase 2：审查辅助

- 输出适合 PR review 的表格；
- 检测十进制/二进制口径混用；
- 检测 `default` 被写成 `hard cap`；
- 检测过宽 prefix；
- 为每个变更附 source URL、observed date 和 confidence。
- 为 Kimi Code 变更附影响分类：模型、协议、认证、工具、安装、文档或纯 bugfix。
- 生成“哪些外部项目可能需要重审”的候选清单，但不自动开 PR。

### Phase 3：低噪声提醒

- 每日或每周定时运行；
- 只有 active/retired、limit、capability 或官方文档变化才提醒；
- 连续抓取失败只标记 stale，不把模型自动标成 retired；
- 需要人工确认后才更新当前状态文档。

## 不建议一开始做的事

- 不要依赖搜索结果摘要作为事实来源；
- 不要把 models.dev 或某个代理目录当成官方 API 的唯一真相；
- 不要根据 `kimi-*` 前缀自动推断未来型号；
- 不要自动提交外部 PR、评论或迁移用户配置；
- 不要把价格、能力和可用性混成一个无来源的“模型分数”。
- 不要把 Kimi Code 的客户端版本号当成模型版本号；两条时间线要分开保存。
- 不要仅凭 release note 标题推断 breaking change，必须保留原文并标记不确定性。

## 成功标准

这个工具第一版就算成功，只要能让我们在 5 分钟内回答：

1. 当前官方 endpoint 可用哪些 Kimi model IDs？
2. 最近一次变化是什么，何时观察到？
3. context、output 和参数限制分别是什么？
4. 哪些型号已退役，是否仍需保留历史兼容？
5. 哪些结论有官方来源，哪些只是代理或第三方信息？
6. 最近的 Kimi Code 发版改变了什么，是否影响模型配置或外部集成？