docs(knowledge): update command reference documentation and tests

- Revised command reference files to clarify schema versioning and CLI version querying.
- Updated tests to ensure that temporary channel versions do not alter committed references.
- Enhanced documentation to prevent manual edits and improve consistency across references.

Author: clark-fc

docs/agents/skill-change.md

@@ -63,6 +63,7 @@ bailian-gen      bailian-finetune  bailian-managed-agent   bailian-web-search
 - [ ] 跑 `pnpm run sync:skill-assets`（或 commit 走 pre-commit），提交生成的 `reference/` 与 version 同步结果
 - [ ] 高风险命令生成的 reference 必须包含 `Risk` / `Risk message` 和简短 Agent safety 提示；带 `--yes` 的示例必须标注只能在确认后执行，不要手改生成物
 - [ ] `bailian-knowledge/reference` 由 `generate-knowledge-reference.ts` 通过 runtime 的 `buildCommandSchema` 生成，与 `--introspect` 共用数据源；分别读取 bl / kscli 的真实入口 map，不用字符串替换推导产品路径。统一生成入口负责归属迁移与旧文件清理。改动后运行 `tools/generate-reference.test.ts`、`tools/generate-knowledge-reference.test.ts` 和 `tools/knowledge-reference-renderer.test.ts`。
+- [ ] 纳入 Git 的 reference 不写入包版本号：channel 发布会在生成前临时 bump 为带时间戳的 beta 版本，否则每次发布都会触发生成物差异。可保留 schema 协议版本，实际 CLI 版本通过 `--version` / `--introspect` 查询。
 - [ ] 默认模型若写在领域路由表（如 `bailian-gen`）：与命令 default / [model-add-remove.md](model-add-remove.md) 一并核对
 
 ## 完成后自查

skills/bailian-knowledge/reference/knowledge.md

@@ -1,7 +1,8 @@
 # bl command reference
 
 > Generated from the same schema as `--introspect`. Do not edit by hand.
-> Version: 2.0.1; schema: 1.
+> Schema version: 1.
+> Query the installed CLI version with `bl --version`.
 
 Cross-flag constraints are validated at execution and are not exported by this schema.
 

skills/bailian-knowledge/reference/kscli.md

@@ -1,7 +1,8 @@
 # kscli command reference
 
 > Generated from the same schema as `--introspect`. Do not edit by hand.
-> Version: 2.0.1; schema: 1.
+> Schema version: 1.
+> Query the installed CLI version with `kscli --version`.
 
 Cross-flag constraints are validated at execution and are not exported by this schema.
 

tools/knowledge-reference-renderer.test.ts

@@ -82,6 +82,17 @@ test("rendering is deterministic and does not mutate schema", () => {
   expect(renderKnowledgeReference(input)).toBe(renderKnowledgeReference(input));
   expect(input).toEqual(snapshot);
 });
+test("temporary channel versions do not change committed references", () => {
+  for (const bin of ["bl", "kscli"]) {
+    const stable = schema(bin, bin === "bl" ? "knowledge init" : "init");
+    const channel = { ...stable, version: "0.0.0-beta-abcdef0-202610120930" };
+    for (const locale of ["en-US", "zh-CN"] as const) {
+      expect(renderKnowledgeReference(channel, locale)).toBe(
+        renderKnowledgeReference(stable, locale),
+      );
+    }
+  }
+});
 test("index links both actual product references", () => {
   const output = renderKnowledgeReferenceIndex();
   expect(output).toContain("(knowledge.md)");

tools/knowledge-reference-renderer.ts

@@ -35,7 +35,12 @@ export function renderKnowledgeReference(schema: CommandSchema, locale: Locale =
       "> Generated from the same schema as `--introspect`. Do not edit by hand.",
       "> 与 `--introspect` 使用同一份 schema 自动生成，请勿手动修改。",
     ),
-    `> ${pick("Version", "版本")}: ${schema.version}; schema: ${schema.schema_version}.`,
+    // Channel releases temporarily bump package versions before checking these tracked assets.
+    `> ${pick("Schema version", "Schema 版本")}: ${schema.schema_version}.`,
+    pick(
+      `> Query the installed CLI version with \`${schema.bin} --version\`.`,
+      `> 使用 \`${schema.bin} --version\` 查询已安装的 CLI 版本。`,
+    ),
     "",
     pick(
       "Cross-flag constraints are validated at execution and are not exported by this schema.",