From 5fad1996643684e56c8ef90e4aa9da59a178d607 Mon Sep 17 00:00:00 2001 From: bj456736 <161294296+bj456736@users.noreply.github.com> Date: Tue, 18 Aug 2026 11:03:58 +0800 Subject: [PATCH 1/2] docs(agents): require plain user-facing wording in gen-changesets skill --- .agents/skills/gen-changesets/SKILL.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.agents/skills/gen-changesets/SKILL.md b/.agents/skills/gen-changesets/SKILL.md index ad64295f894..aceccfc59c6 100644 --- a/.agents/skills/gen-changesets/SKILL.md +++ b/.agents/skills/gen-changesets/SKILL.md @@ -1,6 +1,6 @@ --- name: gen-changesets -description: Use when generating changesets in the kimi-code repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and English changelog wording. +description: Use when generating changesets in the kimi-code repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and user-facing English changelog wording. --- # Generate Changesets @@ -13,7 +13,7 @@ All other `@moonshot-ai/*` packages are treated as internal packages, including `@moonshot-ai/pi-tui` is a special internal package: it is a private fork (`private: true`) that is never published, but it keeps its own changelog through changesets. It is an exception to Core Rule 4 — see the dedicated section below. -Only the CLI changelog gets a curated, user-facing presentation (the docs-site changelog sync). The SDK and other internal package changelogs are raw changesets output kept for version history — nobody curates them, so write those entries honestly and technically; their wording does not need to suit end users. +Only the CLI changelog gets a curated, user-facing presentation (the docs-site changelog sync). The SDK and other internal package changelogs are raw changesets output kept for version history — nobody curates them later, so what you write is exactly what people read. Keep those entries honest and technical in vocabulary, but still short and readable: summarize the capability change — what callers can now do, what behavior changed — in one or two sentences, naming at most the entry points a caller must know. Never enumerate methods, parameters, or fields like an API reference; that detail belongs in docs and code, not in a changelog. ## Core Rules @@ -37,6 +37,7 @@ Only the CLI changelog gets a curated, user-facing presentation (the docs-site c 4. If an ignored internal package change enters the CLI bundle, put `@moonshot-ai/kimi-code` in frontmatter instead of mixing the ignored package into the same changeset. 5. Create a short kebab-case file under `.changeset/`. 6. Split unrelated changes into separate changesets; keep one logical change in one file. +7. Re-read the finished entry as a user with no codebase knowledge: can you tell what changed, whether it affects you, and how to try it? If not, rewrite. For user-facing changes, have the human author proofread the entry before merge — AI-drafted changelog wording is a starting point, not a pass. Before a release, review the accumulated `.changeset/` entries against Core Rule 6 and prune non-user-facing ones; the release PR regenerates from `.changeset/` on `main`, so deleting a changeset removes its changelog entry without affecting the shipped code. @@ -73,6 +74,8 @@ If you believe a change qualifies as major, stop first, explain why, and ask the - Changelog entries **must be written in English**. - **Keep the whole entry concise.** Aim for one short sentence that states what was done; at most a short sentence plus a one-line usage hint. Do not write a paragraph, do not pile on technical detail, and do not enumerate every sub-change. +- **Write for a reader who does not know the codebase.** State the user-visible outcome in plain language, one outcome per entry. Do not cram several effects into one sentence with semicolons and slash lists — if a change has several distinct user-visible effects, split it into separate changesets, or keep only the one that matters most to users. +- **Say who can actually use it.** If the change is experimental, flag-gated, or limited to one engine (legacy / v2), one platform, or one surface (TUI / `kimi web` / VSCode), the entry must say so in plain words (e.g. `experimental`, `on the legacy engine only`, `behind the --foo flag`). A reader must be able to tell whether the feature is available to them and how mature it is. - **For new user-facing features, append a brief usage hint** so users know how to try it. Keep it to a single short line — a command name, a subcommand, a flag, or a one-line "how to use". Do not explain design rationale or list edge cases. Skip the hint for bug fixes, internal changes, and refactors. - Slash command: `Add the /foo slash command to list active sessions. Run /foo to see them.` - CLI subcommand: `Add the kimi web subcommand to open the web UI. Run kimi web to launch it.` @@ -204,3 +207,7 @@ Fix the transcript jumping to the top when scrolling up through history during s - The CLI wording mentions internal package names, class names, or PR numbers. - The entry includes real internal identifiers instead of neutral placeholders. - A change that only touches `@moonshot-ai/pi-tui` lists `@moonshot-ai/kimi-code` instead of `@moonshot-ai/pi-tui`, or mixes both packages in one frontmatter. +- The entry reads like an API reference — it enumerates method, parameter, or field names instead of summarizing the capability change. This applies to SDK and other internal entries too: technical vocabulary is fine, enumeration is not. +- An experimental, flag-gated, engine-gated, platform-gated, or surface-specific change is presented without saying who can use it or how mature it is. +- One sentence stuffing several user-visible effects together with semicolons or slash lists — split it into separate changesets. +- User-facing wording was committed without anyone re-reading it from a user's perspective. From 1f3a17674122b51465f54a515bc0149a19c2ee86 Mon Sep 17 00:00:00 2001 From: bj456736 <161294296+bj456736@users.noreply.github.com> Date: Tue, 18 Aug 2026 11:03:59 +0800 Subject: [PATCH 2/2] chore(changesets): rewrite v1-mcp-management-plane entry in plain language --- .changeset/v1-mcp-management-plane.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/v1-mcp-management-plane.md b/.changeset/v1-mcp-management-plane.md index ef24a78bc21..705101887c8 100644 --- a/.changeset/v1-mcp-management-plane.md +++ b/.changeset/v1-mcp-management-plane.md @@ -4,6 +4,6 @@ "kimi-code": patch --- -On the legacy engine, plugin MCP server changes (install / enable / disable / remove / reload) now apply to open sessions immediately, and an MCP server OAuth sign-in or credential reset automatically refreshes the affected sessions instead of leaving them stuck until a manual reconnect; a connection that fails mid-session for auth reasons is now reported as needing sign-in rather than as a generic failure. +On the legacy engine, MCP server changes (install / enable / disable / remove / reload) now apply to open sessions immediately — no manual reconnect needed. Signing in to an MCP server with OAuth or resetting its credential now automatically refreshes the affected sessions, and a connection that fails mid-session for auth reasons is reported as needing sign-in instead of a generic failure. -`@moonshot-ai/kimi-code-sdk`: the MCP management surface is now backed by a unified, source-tagged registry — `listMcpServers` also covers plugin-declared servers (read-only, with their effective config) and returns `source` / `origin` / `mutable` markers; new `getMcpServer` for a single effective config; `testMcpServerConfig` probes an unsaved inline config; sessions can connect a server at runtime via `addMcpServer` with an optional persist flag; `reconnectMcpServer` accepts an optional replacement config and otherwise re-resolves the current config instead of reusing a stale snapshot; `listMcpServerAuthStatuses` accepts `cwd` / `verify` (online probe) and distinguishes dead grants via the new `oauth-expired` state; stored OAuth grants now record their absolute expiry and are refreshed proactively and single-flight per credential. Session status entries and read-only management entries redact secret-bearing stdio `env` / remote `headers` values to key lists, and concurrent logins for the same credential join a single browser flow. A new app-level inspection, `inspectAppMcpServers`, reports every server's effective config and real (probe-verified) authorization state — including plugin servers and runtime-name collisions — and the OAuth flow RPCs have locator-addressed variants (`authenticateAppMcpServer` / `resetAppMcpServerAuth`) so plugin servers can be signed in and reset directly. +`@moonshot-ai/kimi-code-sdk`: MCP servers are now managed through a unified registry that also covers plugin-declared servers. SDK callers can list, inspect, probe, add, reconnect, and authenticate MCP servers at runtime — including plugin servers — with effective config and probe-verified authorization state. Stored OAuth grants now record expiry and refresh proactively, concurrent logins for the same credential share one browser flow, and secret-bearing `env` / `headers` values are redacted to key lists in status responses.