Feat/iteration1 w1 foundation

[clark-fc]

概述

修复知识库两个命令层问题，补齐 Knowledge Studio CLI 命令手册，并完成 1.17.1 发版准备。

变更内容

命令行为

• knowledge create 新增 --description 并设为必填 — 对齐服务端对知识库描述的必填校验。CLI 在发出请求前本地校验 1–500 字符长度，超限/缺失直接报 USAGE(2)，不再让请求打到服务端才被拒。

• 修复 knowledge service update 的误报警告 — 走 --policy 等标量参数更新草稿配置时，CLI 会「读取完整草稿 → 合并 → 回写」。草稿中服务端返回的 9 个字段（user_system_prompt、anti_leak_prompt、refusal_prompt、credibility_prompt、session_file_parse_mode，以及 enable_thinking / enable_temperature / enable_credibility / enable_max_completion_tokens）此前不在 KNOWN_CONFIG_KEYS 白名单里，导致每次更新都刷出一串 unknown agent_config field passed through 警告。

  这些字段始终被正确回写（{ ...currentConfig, ...scalarConfig } 对象展开保留全部字段），修的是噪音不是数据。本 PR 将其加入白名单并在 RagAgentConfig 中补类型。

帮助文案

• 数据集合、服务的 --description 说明改为陈述用途（在列表中区分同类项；服务描述供 agent 判断该调用哪个服务），不再只写「必填」。
• knowledge retrieve --rerank-model 补充前置条件说明：目标知识库须已配置重排序模型，否则任何取值都会被拒绝。
• service list --scene 去掉冗余的「服务端必填」措辞（required: true 未变，行为零变化）。

测试

• kb create 新增 4 条 e2e 断言：help 展示 --description、缺参报 USAGE(2)、501 字符报 USAGE(2)、dry-run body 携带 description。
• 新增 verified-models.ts，集中收敛经线上验证的模型取值，并记录两个契约坑：
  • agent_model 白名单仅 qwen3.6-plus / qwen3.7-plus，其余（含 qwen3-max、deepseek-v3）返回 401 agent model not allowed
  • rerank[].model_name 服务端只按 -hybrid 后缀分支，模型前缀被忽略，实际打分模型取索引自身的 rerankModelName
• service update --model 断言改为自适应：先读回草稿当前模型，再挑一个不同的已验证模型写入，确保断言证明「值真的变了」而非把默认值原样回写；白名单缩到只剩当前模型时跳过该断言而不是断言空操作。
• 刻意不把模型白名单下沉到命令层做本地校验 —— 模型目录随服务端上下架变动，CLI 硬编码会挡住合法模型直到用户升级。

文档

• 新增 docs/kscli/ 8 篇命令手册（约 2900 行），覆盖 kb / doc / chunk / collection-category / file / service / search-chat 及总览指南。已逐条核对：packages/kscli/src/commands.ts 中 37 条命令路径全部有文档覆盖，0 缺失。
• 同步更新 docs/knowledge/ 中受 --description 影响的示例，及 kscli README。

发版准备

• 五包版本统一升至 1.17.1（core / runtime / commands / cli / kscli）。
• CHANGELOG.md + CHANGELOG.zh.md 新增 1.17.1 条目，中英一一对应，分类用 Keep a Changelog 规范段名。
• 6 个 SKILL.md 的 metadata.version 同步到 1.17.1，skills/bailian-cli/reference/knowledge.md 重新生成。

影响与升级说明

调用方需要改：bl knowledge create / kscli kb create 现在必须传 --description，否则退出码 2。

# 旧
bl knowledge create --name demo --doc-id file-xxx

# 新
bl knowledge create --name demo --description '产品文档' --doc-id file-xxx