write-tui
Use when writing or modifying the kimi-code terminal UI in apps/kimi-code/src/tui — components, dialogs/selectors, slash commands, themes, streaming render, or the KimiTUI controllers. Covers the architecture, where new features go, test placement, the theme system mechanics, and the dialog interaction/visual spec (DESIGN.md).
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8.2k
- Forks
- 1.4k
01 前言 Front Matter
- name
- write-tui
- description
- Use when writing or modifying the kimi-code terminal UI in apps/kimi-code/src/tui — components, dialogs/selectors, slash commands, themes, streaming render, or the KimiTUI controllers. Covers the architecture, where new features go, test placement, the theme system mechanics, and the dialog interaction/visual spec (DESIGN.md).
02 资源文件 1
- 参考文档DESIGN.md12.1 KB
03 SKILL.md 正文
Write TUI (apps/kimi-code)
The terminal UI lives in apps/kimi-code/src/tui. Before writing TUI code, read apps/kimi-code/AGENTS.md for the always-on map, module boundaries, and hard constraints (printable-key decoding, no chalk named colors, etc.). This skill is the how-to: architecture orientation, feature routing, test placement, theme mechanics, and the dialog spec.
For any list dialog, selector, input box, or status/toggle list, the interaction and visual rules are normative — see DESIGN.md in this folder and follow its self-check list before submitting.
Architecture
KimiTUI is a coordinator that wires state, layout, session, and dialogs together and delegates heavy logic to controllers.
src/tui/kimi-tui.ts— theKimiTUIcoordinator. Holdsstate, owns startup/shutdown order, layout/editor wiring, user-input entry, sending/queueing, session lifecycle, and the slash-command handler dispatch. It should not accumulate event-routing or rendering logic — those live in controllers.src/tui/tui-state.ts—TUIState,createTUIState,createInitialAppState. The single global UI state shape. Before adding a new global field, decide whether it truly belongs here vs. local component state.src/tui/controllers/— the independently-testable responsibilities. Each controller owns one slice:session-event-handler.ts— routes SDK session events (handleEventdispatch + the per-eventhandleXxx). Concrete event handling goes here, not inKimiTUI.streaming-ui.ts— streaming render: assistant delta, thinking, tool call / result, compaction, subagent, background agent, transcript aggregation.session-replay.ts— resume/replay orchestration; drives replay records through the same live render hooks. Stateless replay parsing/limiting/projection helpers belong insrc/tui/utils/message-replay.ts.tasks-browser.ts— the tasks browser controller.editor-keyboard.ts— editor keyboard handling, exit shortcuts, external editor, clipboard image.auth-flow.ts— login/auth orchestration (refreshConfigAfterLogin, etc.).
src/tui/commands/— slash-command declaration, parsing, ordering, and dynamic skill-command generation. Parsing and types only; execution is dispatched fromKimiTUI's slash-command handler section, and complex execution sinks intoutilsor focused components.src/tui/components/— pi-tui components by UI type:chrome/(footer, todo, welcome, loader, device code),dialogs/(selectors, approval/question panels, settings popups that replace the editor),editor/(input box + mention provider),media/(image, diff, code highlight),markdown/(the app's Markdown wrapper and mermaid art),messages/(transcript blocks + tool-renderers),panes/(activity, queue).src/tui/reverse-rpc/— adapts SDK approval/question callbacks into UI panel data and the user's choice back into an SDK response.src/tui/theme/— themes, color tokens, style helpers, pi-tui markdown theme, terminal-background detection. The single source of truth for color.src/tui/utils/— TUI-only utilities (needTUIStateor a component). App-wide, UI-independent helpers go insrc/utils/.
When a controller or KimiTUI section keeps growing, split pure functions, state projections, and presentation components into the matching directory rather than expanding the file.
Where new features go
The feature type decides the landing spot:
- CLI arguments →
src/cli/commands.ts/src/cli/options.ts, passed into the TUI viasrc/cli/run-shell.ts. The CLI never operates on the session directly. - CLI subcommands →
src/cli/sub/, non-interactive only; reach core via@moonshot-ai/kimi-code-sdk. - Slash commands → declare/parse/type under
src/tui/commands/; add the execution entry inKimiTUI's slash-command handler section; sink complex logic intoutilsor a focused component. - Skill-derived commands → hook into
buildSkillSlashCommands/ the skill command map; do not hard-code a single skill. - Transcript message types → define the shape in
src/tui/types.ts, add/extend acomponents/messages/component, register the renderer in the transcript builder. - Tool-result display → extend
components/messages/tool-renderers/registry.tsand the renderer; do not stack branches insideToolCallComponent. - Popup / selector →
components/dialogs/, mounted viamountEditorReplacement; follow DESIGN.md. If triggered by an SDK callback, check whetherreverse-rpc/needs an adapter/controller/handler. - SDK event handling → add the dispatch in
session-event-handler.ts'shandleEvent, then the matchinghandleXxx. - Streaming render →
controllers/streaming-ui.ts. - Session start / resume behavior → the session-management section of
KimiTUI; replay behavior →controllers/session-replay.ts, reusing live render paths. - Status bar / activity / queue →
chrome/footer,panes/activity,panes/queue, and the matchingupdateXxx. - Configuration option → read/write + schema in
src/tui/config.ts, then the settings UI; persist throughsaveTuiConfig(a component never writes the config file itself). - Constants → shared CLI/TUI non-copy constants in
src/constant/; TUI-only non-copy constants insrc/tui/constant/. Component-local copy, option labels, help text, dialog titles/footers stay next to their component — do not centralize copy into a global module. - General capability → no TUI-state dependency →
src/utils/; depends on TUI state or a component →src/tui/utils/.
Test placement
- Component behavior tests sit next to the component's existing tests (
test/tui/components/...). - Command parsing tests →
test/tui/commands/. - reverse-rpc tests →
test/tui/reverse-rpc/. - Pure utility tests → next to the corresponding utils tests.
- Do not create a generic
some-feature.test.tsjust to land a small feature; extend the nearest existing test file.
Theme system mechanics
Themes are managed centrally under src/tui/theme/:
colors.ts— semantic tokens:ColorPalette,darkColors,lightColors.styles.ts— common chalk helpers built on top ofColorPalette.pi-tui-theme.ts— the markdown/pi-tui theme config.terminal-background.ts— terminal background detection used by auto resolution.bundle.ts— packscolors,styles,markdownThemeinto aKimiTUIThemeBundle.index.ts/detect.ts— theme type and auto/dark/light resolution.
Keep the color-token set in sync.
ColorPaletteincolors.tsis the source of truth for color tokens. When you add, rename, or remove one, update its mirrors in the same change: the custom-theme JSON schema (apps/kimi-code/src/tui/theme/theme-schema.json), the token tables in the custom-theme docs (docs/en/customization/themes.mdanddocs/zh/customization/themes.md), and the token table in thecustom-themebuilt-in skill (packages/agent-core-v2/src/features/skill/catalog/builtin/custom-theme.md).
Apply / switch flow:
- UI entry:
ThemeSelectorComponent→handleThemeCommand→applyThemeChoice. - The real apply step is
KimiTUI.applyTheme: it updatesstate.theme,state.appState.theme, and notifies components to refresh their palette. - Persist the choice through
saveTuiConfig— a component must not write the config file itself.
The hard color rules (no chalk named colors, contrast ratios, no module-top-level cached styled functions, add a
ColorPalettetoken before inventing a color) are normative and guard-enforced — they live inapps/kimi-code/AGENTS.md. This skill only covers the mechanics.
Before you submit
- Run lint / format / test on the files you changed.
- For any dialog/selector/input/toggle list, walk the self-check list at the end of DESIGN.md.
- Keep
printableChar()for printable-key comparisons (CI guard) andchalk.hex(colors.<token>)for color (CI guard).
04 同仓库更多 Skills
golden-skill
Golden fixture skill
tools
暂无简介
review
Analyze the available skill set and recommend candidate groups that could be consolidated into sub-skill bundles. Read-only — proposes a plan, does not move files.
consolidate
Apply an approved sub-skill grouping by moving user-specified skills into a parent bundle, with timestamped backups of every modified directory.
sub-skill
Discover and reorganize the skill inventory into hierarchical sub-skill bundles. Use when the user asks to review, group, or consolidate skills into a parent bundle.
write-pr
在 kimi-code 仓库里创建或更新 PR 时使用:如何写出让 reviewer 只读描述就能从逻辑和架构上理解改动的 PR 描述,包括核心思路与结构图、"行为变化与受影响人群"表、可视化大纲,以及 UI/UX 变化的截图和录屏。