npm - @seemseam/ccb - Versions diffs - 7.4.2 → 7.5.0 - Mend

@seemseam/ccb 7.4.2 → 7.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,121 +1,70 @@
 <div align="center">
-# CCB - Visible, Controllable Multi-Agent CLI Workspace
+# CCB
+**Designed around agent parity**
+**Visible, controllable multi-agent cooperative TUI workspace**
 <p>
-  <img src="https://img.shields.io/badge/v7-multi--agent--workspace-0B7285?style=for-the-badge" alt="v7 multi-agent workspace">
-  <img src="https://img.shields.io/badge/terminal-tmux-2F9E44?style=for-the-badge" alt="tmux">
-  <img src="https://img.shields.io/badge/providers-Codex%20%7C%20Claude%20%7C%20Gemini%20%7C%20OpenCode%20%7C%20Antigravity-CF1322?style=for-the-badge" alt="providers">
+  <img src="https://img.shields.io/badge/version-7.5.0-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
+  <img src="https://img.shields.io/badge/providers-7%20CLI%20families-0B7285.svg" alt="providers">
 </p>
-[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg)]()
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)]()
-[![Version](https://img.shields.io/badge/version-7.4.2-orange.svg)]()
-[![Release](https://img.shields.io/badge/install-release--first-orange.svg)]()
 **English** | [中文](README_zh.md)
-[Why Multi Agents](#why-multi-agents) · [Comparison](#which-multi-agent-approach-should-you-use) · [v7 UI](#v7-ui-tour) · [Quick Start](#quick-start) · [tmux Basics](#tmux-basics) · [Configure Agents](#configure-your-agent-team) · [Install](#install-and-update)
+[Quick Start](#quick-start) · [v7 UI](#v7-ui-tour) · [Configure Agents](#configure-your-agent-team) · [User Guide](docs/manuals/user-guide/) · [Developer Guide](docs/manuals/developer-guide/)
+<p align="center">
+  <img src="assets/readme_v7/ccb-hero-en.png" alt="CCB v7 visible multi-agent CLI workspace" width="960">
+</p>
 </div>
 ---
-## Why Multi Agents
-A single agent is enough for small tasks. Once work needs planning, parallel edits, review, testing, and handoff, multi agents help separate roles, context, models, and execution. CCB focuses on putting multiple real CLI agents into one visible terminal workspace.
-| Value | Plain meaning |
-| :--- | :--- |
-| Role separation | `main` plans, `worker` implements, `reviewer` checks risk. |
-| Parallel progress | One agent can edit while another reads docs, validates, or reviews. |
-| Model and context layering | Different agents can use different providers, models, APIs, worktrees, and memory. |
-<details>
-<summary><b>Why one agent starts to struggle</b></summary>
-- Mixed roles reduce context focus: one conversation tries to architect, edit, test, and review itself.
-- Complex task execution has a ceiling: long work needs split points, handoffs, checks, and rollback boundaries.
-- Cost pressure is higher: if every step needs the strongest model, even simple sub-tasks become expensive.
-- Tool and skill management becomes harder: a "does everything" agent also accumulates too much authority and instruction load.
-- Serial waiting is inefficient: when one agent is reading logs or running tests, other independent work cannot naturally continue.
-</details>
-## Which Multi-Agent Approach Should You Use?
-Multi-agent systems are not one fixed shape. Use the short table first; expand the details only if you are comparing tradeoffs.
+## Why CCB?
-| Approach | One-line summary | Best fit |
+| See the work | Mix providers | Keep control |
 | :--- | :--- | :--- |
-| [Claude Code native subagents](https://code.claude.com/docs/en/sub-agents) / [agent teams](https://code.claude.com/docs/en/agent-teams) | Native delegation inside Claude Code. | You mostly stay in Claude Code and want more coordination handled by a Claude lead. |
-| [Hive / OpenHive](https://github.com/aden-hive/hive) | Production-oriented multi-agent workflow harness. | You need state, recovery, observability, cost controls, and graph workflows. |
-| CCB | Visible, controllable local CLI-agent workspace with mixed providers. | You want Codex, Claude, Gemini, OpenCode, Antigravity, and other real CLIs in one project terminal. |
-<details>
-<summary><b>Details: model choice, control, context, and complex workflows</b></summary>
-| Question | Claude Code native | Hive / OpenHive | CCB |
-| :--- | :--- | :--- | :--- |
-| Different model vendors? | Can choose Claude models for teammates/subagents; overall path is still Claude Code. | LiteLLM route covers many hosted and local providers. | Choose Codex, Claude, Gemini, OpenCode, Droid, Antigravity, and per-agent model/key/url. |
-| Is the process visible? | In-process or split panes depending on mode. | Runtime observability and dashboard-style control. | Real tmux panes by default; users can click, type, copy, and inspect each CLI. |
-| Is topology controllable? | Natural-language teammate setup, with much coordination handled by the lead. | Goal-generated graph-like topology, harness oriented. | Config explicitly defines agents, windows, panes, worktrees, and sidebar behavior. |
-| Is context manageable? | Subagents/teammates have separate contexts; teams have task and message state. | Role memory, durable state, and recovery are core design points. | Each CLI keeps its provider session; shared project memory and per-agent memory are optional. |
-| Best landing zone | Fast delegation inside Claude Code. | Business automation, long-running workflows, production reliability. | Local development with visible cross-provider CLI agents. |
-CCB also supports complex workflows, but it is not an automatic DAG generator. You design complexity explicitly through `.ccb/ccb.config`, windows, role memory, worktrees, model/API settings, and ask/callback routes.
+| Every agent is a real terminal with layout control. | Run multiple CLIs concurrently from one command. | Stable background communication for multi-line task orchestration. |
-</details>
-## What Is CCB?
-CCB is a project-level agent CLI workspace. It uses tmux to manage multiple real CLI agents and unifies startup, restore, communication, configuration, windows, and runtime state for one project.
+## Supported CLIs
-- **Real CLI sessions, not fake panels**: every agent pane runs the actual provider CLI.
-- **Visible collaboration**: the sidebar shows windows, agents, status, and communication; users can switch panes by mouse.
-- **Mixed providers**: one project can run Codex, Claude, Gemini, OpenCode, Droid, and Antigravity (`agy`) together.
-- **Project config**: `.ccb/ccb.config` defines the team, layout, windows, worktrees, model, key, and url.
-- **Roles**: a new role packaging model that lets specialized agents carrying
-  "heavy weapons" such as independent skills, memory, and tool dependencies
-  instantly land in a target project as hot-loadable, removable agents, while
-  leaving the main environment, user global config, and project runtime state
-  unchanged.
-- **Recoverable runtime**: CCB supervises agent panes and supports attach, restore, and project-scoped cleanup.
-- **Explicit collaboration channel**: agents can delegate through `/ask`, `$ask`, callback, and silence routes.
-## v7 UI Tour
-This screenshot is a real dark terminal session from the `ccb_test2` project. The labels explain the regions; you do not need to memorize every shortcut first.
-<p align="center">
-  <img src="assets/readme_v7/ccb-test2-terminal-annotated-en.png" alt="CCB v7 terminal workspace region guide" width="960">
+<p>
+  <img src="https://img.shields.io/badge/Codex-111111?style=flat-square&logo=openai&logoColor=white" alt="Codex">
+  <img src="https://img.shields.io/badge/Claude-D97757?style=flat-square&logo=anthropic&logoColor=white" alt="Claude">
+  <img src="https://img.shields.io/badge/Gemini-4285F4?style=flat-square&logo=googlegemini&logoColor=white" alt="Gemini">
+  <img src="https://img.shields.io/badge/OpenCode-111111?style=flat-square" alt="OpenCode">
+  <img src="https://img.shields.io/badge/Antigravity-6D5EF6?style=flat-square&logo=google&logoColor=white" alt="Antigravity">
+  <img src="https://img.shields.io/badge/Droid-3DDC84?style=flat-square&logo=android&logoColor=white" alt="Droid">
+  <img src="https://img.shields.io/badge/Kimi-111111?style=flat-square&logo=moonshotai&logoColor=white" alt="Kimi">
 </p>
-| Region | Purpose |
-| :--- | :--- |
-| Sidebar | Shows the current window, agent list, provider labels, selected agent, and status hints. |
-| Comms | Shows ask/callback communication and collaboration status. |
-| Agent pane | Each pane is a real CLI session, such as Codex or Claude. |
-| Current input target | The status bar and pane border show where your input goes. |
-| Status bar | Shows project name, current agent, CCB version, date, and mouse/keyboard hints. |
-| Window grouping | v7 `[windows]` can group agents into main, work, review, research, or other workflow windows. |
+Mix CLIs per agent in `.ccb/ccb.config`. Common provider ids include `codex`, `claude`, `gemini`, `kimi`, `opencode`, `agy`, and `droid`; actual availability depends on the local CLI installation and account access.
-The sidebar implementation uses ideas from [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar). Thanks to that project.
+**New role specification**: package skills, memory, and tool dependencies into self-contained Role Packs, then create hot-loadable and removable specialist agents.
 ## Quick Start
 ### 1. Install or update
-New users can install CCB from npm:
+New installs should use the npm package:
 ```bash
 npm install -g @seemseam/ccb
 ```
-The npm package downloads and verifies the matching GitHub Release package for
-your platform, then exposes `ccb`, `ask`, `autonew`, and `ctx-transfer`.
+After CCB is installed, use CCB's updater:
-You can also install from a release package directly. Download the matching package from [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases), then install it:
+```bash
+ccb update
+```
+<details>
+<summary><b>GitHub release package and source install fallbacks</b></summary>
+If npm is not available in your environment, download the matching package from [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases):
 ```bash
 tar -xzf ccb-*.tar.gz
@@ -123,14 +72,7 @@ cd ccb-*
 ./install.sh install
 ```
-If CCB is already installed:
-```bash
-ccb update
-```
-<details>
-<summary><b>Source install is for development or fallback use</b></summary>
+Source install is for development or temporary fallback use:
 ```bash
 git clone https://github.com/SeemSeam/claude_codex_bridge.git
@@ -138,10 +80,16 @@ cd claude_codex_bridge
 ./install.sh install
 ```
-Source installs link global `ccb` / `ask` back to the checkout. Regular users should prefer a stable release install or update.
+Source installs link global `ccb` / `ask` back to the checkout. Regular users should prefer the npm package.
 </details>
+Out of the box, run `ccb` from your project directory. If startup reports that `.ccb` cannot be created automatically or that the project anchor is missing, create `.ccb` manually:
+```bash
+mkdir -p .ccb
+```
 ### 2. Create project config
 Create `.ccb/ccb.config` in your project root. For v7, it is better to understand config from multi-window topology first: `[windows]` defines tmux windows and agent groups, `agent:provider` defines which CLI each agent uses, and `(worktree)` gives an agent its own git worktree.
@@ -167,7 +115,7 @@ tips_height = "35%"
 comms_limit = 3
 ```
-If you are not sure how to group windows, how many workers you need, which agents should use worktrees, or which agents need separate models or API routes, ask `ccb_self` to design the config with its built-in `ccb-config` skill. Blank projects include `ccb_self`; existing custom configs can add it with `ccb roles add agentroles.ccb_self:codex`.
+If you are not sure how to group windows, how many workers you need, which agents should use worktrees, or which agents need separate models or API routes, ask `ccb_self`. It is CCB's built-in self-agent: it understands CCB commands, config authority, roles, windows, reload behavior, and common recovery paths, and can design the config with its private `ccb-config` skill. Blank projects include `ccb_self`; existing custom configs can add it with `ccb roles add agentroles.ccb_self:codex`.
 Validate the config:
@@ -189,7 +137,92 @@ Type directly in an agent pane, or route work between agents:
 /ask reviewer review the latest parser changes and list blocking issues.
 ```
-## Daily Operation
+Agents can also call `/ask` from workflow orchestration to delegate and hand off work automatically.
+### v7 UI Tour
+| Region | Purpose |
+| :--- | :--- |
+| Sidebar | Shows refresh/close CCB controls, windows and agents, internal communication state, and tips that can be edited in config and hot-reloaded. |
+| Mouse control | Click to switch windows, agents, and panes; refresh, kill, or delete communication entries from the communication area. |
+| Workspace | Every pane is a real CLI. Switch by mouse or tmux shortcuts. |
+| Useful shortcuts | `Ctrl-b h/j/k/l` switches adjacent panes; `Ctrl-b z` zooms or restores the current CLI pane. |
+### Contact
+- Email: `bfly123@126.com`
+- WeChat: `seemseam-com`
+---
+## More Reading
+Start with Quick Start for first use; the sections below cover CCB's design boundaries, comparisons, daily operations, and configuration model.
+### What Is CCB?
+CCB is a project-level agent CLI workspace. It uses tmux to manage multiple real CLI agents and unifies startup, restore, communication, configuration, windows, and runtime state for one project.
+- **Real CLI sessions, not fake panels**: every agent pane runs the actual provider CLI.
+- **Visible collaboration**: the sidebar shows windows, agents, status, and communication; users can switch panes by mouse.
+- **Mixed providers**: one project can run Codex, Claude, Gemini, OpenCode, Droid, Antigravity (`agy`), and Kimi (`kimi`) together.
+- **Project config**: `.ccb/ccb.config` defines the team, layout, windows, worktrees, model, key, and url.
+- **Built-in CCB expert**: blank projects include `ccb_self`, a self-maintenance agent with deep CCB knowledge for usage guidance, config design, diagnostics, recovery, and workflow repair.
+- **Roles**: a new role packaging model that lets specialized agents carrying
+  "heavy weapons" such as independent skills, memory, and tool dependencies
+  instantly land in a target project as hot-loadable, removable agents, while
+  leaving the main environment, user global config, and project runtime state
+  unchanged.
+- **Recoverable runtime**: CCB supervises agent panes and supports attach, restore, and project-scoped cleanup.
+- **Explicit collaboration channel**: agents can delegate through `/ask`, `$ask`, callback, and silence routes.
+### Why Multi Agents
+A single agent is enough for small tasks. Once work needs planning, parallel edits, review, testing, and handoff, multi agents help separate roles, context, models, and execution. CCB focuses on putting multiple real CLI agents into one visible terminal workspace.
+| Value | Plain meaning |
+| :--- | :--- |
+| Role separation | `main` plans, `worker` implements, `reviewer` checks risk. |
+| Parallel progress | One agent can edit while another reads docs, validates, or reviews. |
+| Model and context layering | Different agents can use different providers, models, APIs, worktrees, and memory. |
+<details>
+<summary><b>Why one agent starts to struggle</b></summary>
+- Mixed roles reduce context focus: one conversation tries to architect, edit, test, and review itself.
+- Complex task execution has a ceiling: long work needs split points, handoffs, checks, and rollback boundaries.
+- Cost pressure is higher: if every step needs the strongest model, even simple sub-tasks become expensive.
+- Tool and skill management becomes harder: a "does everything" agent also accumulates too much authority and instruction load.
+- Serial waiting is inefficient: when one agent is reading logs or running tests, other independent work cannot naturally continue.
+</details>
+### Which Multi-Agent Approach Should You Use?
+Multi-agent systems are not one fixed shape. Use the short table first; expand the details only if you are comparing tradeoffs.
+| Approach | One-line summary | Best fit |
+| :--- | :--- | :--- |
+| [Claude Code native subagents](https://code.claude.com/docs/en/sub-agents) / [agent teams](https://code.claude.com/docs/en/agent-teams) | Native delegation inside Claude Code. | You mostly stay in Claude Code and want more coordination handled by a Claude lead. |
+| [Hive / OpenHive](https://github.com/aden-hive/hive) | Production-oriented multi-agent workflow harness. | You need state, recovery, observability, cost controls, and graph workflows. |
+| CCB | Visible, controllable local CLI-agent workspace with mixed providers. | You want Codex, Claude, Gemini, Kimi, OpenCode, Antigravity, and other real CLIs in one project terminal. |
+<details>
+<summary><b>Details: model choice, control, context, and complex workflows</b></summary>
+| Question | Claude Code native | Hive / OpenHive | CCB |
+| :--- | :--- | :--- | :--- |
+| Different model vendors? | Can choose Claude models for teammates/subagents; overall path is still Claude Code. | LiteLLM route covers many hosted and local providers. | Choose Codex, Claude, Gemini, Kimi, OpenCode, Droid, Antigravity, and per-agent model/key/url. |
+| Is the process visible? | In-process or split panes depending on mode. | Runtime observability and dashboard-style control. | Real tmux panes by default; users can click, type, copy, and inspect each CLI. |
+| Is topology controllable? | Natural-language teammate setup, with much coordination handled by the lead. | Goal-generated graph-like topology, harness oriented. | Config explicitly defines agents, windows, panes, worktrees, and sidebar behavior. |
+| Is context manageable? | Subagents/teammates have separate contexts; teams have task and message state. | Role memory, durable state, and recovery are core design points. | Each CLI keeps its provider session; shared project memory and per-agent memory are optional. |
+| Best landing zone | Fast delegation inside Claude Code. | Business automation, long-running workflows, production reliability. | Local development with visible cross-provider CLI agents. |
+CCB also supports complex workflows, but it is not an automatic DAG generator. You design complexity explicitly through `.ccb/ccb.config`, windows, role memory, worktrees, model/API settings, and ask/callback routes.
+</details>
+### Daily Operation
 | Goal | Command |
 | :--- | :--- |
@@ -203,7 +236,7 @@ Type directly in an agent pane, or route work between agents:
 | Preview a config reload plan without changing tmux | `ccb reload --dry-run` |
 | Apply supported config changes without restarting other agents | `ccb reload` |
-## tmux Basics
+### tmux Basics
 CCB can be used mostly with the mouse, but learning a few tmux shortcuts makes daily work much faster. This section lists only common tmux keyboard operations.
@@ -248,7 +281,7 @@ New users should avoid pane/window killing shortcuts at first. To stop a CCB pro
 </details>
-## Configure Your Agent Team
+### Configure Your Agent Team
 CCB resolves config in three layers, from lowest to highest priority:
@@ -276,7 +309,7 @@ After editing `.ccb/ccb.config` in a mounted project, run `ccb reload --dry-run`
 If you want to discuss the configuration before writing it by hand, ask `ccb_self` to describe the target team. Blank projects include this route by default; projects with a user or project config should add `agentroles.ccb_self` if they have overridden the built-in default. Its built-in `ccb-config` skill proposes a complete config first, then writes `.ccb/ccb.config` only after confirmation.
-### Role Packs
+#### Role Packs
 Role Packs define reusable agent roles. A role can carry a stable identity,
 responsibilities, memory, provider-specific skills, tool hooks, and dependency
@@ -301,12 +334,13 @@ bound role locks against the current installed roles; interactive starts ask
 whether to refresh stale project locks in place, and non-interactive starts
 print a warning only.
-`ccb_self` is strongly recommended for CCB projects because it owns CCB config
-maintenance, runtime diagnostics, guarded recovery, and single-agent restart
-assistance without taking over product work. Blank projects include it in the
-built-in default. Existing projects, and projects with user or project config
-that replace the built-in default, should add it explicitly where they want
-that maintenance agent:
+`ccb_self` is strongly recommended for CCB projects because it is the built-in
+CCB expert agent. It carries CCB-specific knowledge about project config,
+command usage, role binding, reload boundaries, runtime diagnostics, guarded
+recovery, workflow repair, and single-agent restart assistance without taking
+over product work. Blank projects include it in the built-in default. Existing
+projects, and projects with user or project config that replace the built-in
+default, should add it explicitly where they want that maintenance agent:
 ```bash
 ccb roles add agentroles.ccb_self:codex
@@ -327,7 +361,7 @@ into that agent's managed provider home.
 <details>
 <summary><b>Config format examples: single window, multi-window, per-agent model/API</b></summary>
-### Single-window compact config
+#### Single-window compact config
 ```text
 cmd; main:codex, worker1:codex(worktree); reviewer:claude
@@ -341,7 +375,7 @@ Meaning:
 - `;` splits left-to-right; `,` stacks top-to-bottom.
 - `(worktree)` means that agent uses an isolated git worktree.
-### Multi-window topology
+#### Multi-window topology
 When you want planning, implementation, review, and research in different tmux windows, use `version = 2` and `[windows]`:
@@ -368,7 +402,7 @@ comms_limit = 3
 Note: `cmd` belongs to compact/hybrid single-window layouts. Do not put `cmd` inside `[windows]`.
-### Managed Neovim tool window
+#### Managed Neovim tool window
 Tool windows are tmux windows managed by CCB, but they are not agents. They do not appear in `ccb ask` targets and do not create provider runtime records.
@@ -389,7 +423,7 @@ If `nvim` is not already on `PATH`, provisioning attempts to download the offici
 The managed profile defaults to ASCII icons so terminals without Nerd Font support do not show unreadable boxes. To opt back into LazyVim glyph icons, launch with `CCB_LAZYVIM_ICON_STYLE=glyph ccb-nvim`.
 Use `ccb tools doctor neovim` to verify the managed profile. A working LazyVim setup reports `neovim_status: ok` and `lazyvim_health_status: ok`; damaged or partially downloaded plugin trees report `degraded` and can be repaired by rerunning `ccb tools install neovim`.
-### Per-agent model, API key, or base URL
+#### Per-agent model, API key, or base URL
 Use compact format when layout is enough. If some agents need separate models or API routes, keep the compact header and add TOML overlays:
@@ -412,10 +446,12 @@ Do not commit real API keys to a public repository. `key` / `url` are agent-loca
 </details>
-## Use ccb_self For CCB Config
+### Use ccb_self For CCB Config
 The full `ccb-config` skill belongs to the `agentroles.ccb_self` role. It is not a globally inherited skill for every agent. CCB installs or refreshes this Role Pack by default, and blank projects include `ccb_self` in the built-in default config. Existing projects, or projects with a user/project config that replaces the built-in default, should bind it where they want the maintenance assistant.
+`ccb_self` is more than a config helper: it is designed as CCB's self-understanding agent. Use it when you need help using CCB, explaining the active layout, choosing an agent topology, migrating `.ccb/ccb.config`, diagnosing project runtime state, or repairing a CCB workflow.
 If you do not want to hand-write `.ccb/ccb.config`, ask `ccb_self` and describe your project goal, parallelism, window grouping, worktree isolation, provider/model/API preferences. `ccb_self` uses its built-in `ccb-config` skill to discuss the shape with you and propose a complete config.
 Example:
@@ -440,7 +476,7 @@ By default, `ccb-config` does not edit `.ccb/ccb_memory.md` or `.ccb/agents/<age
 </details>
-## Agent Collaboration
+### Agent Collaboration
 Normal `ask` is submit-and-return: after handing work to the target agent, the current agent should not poll and wait.
@@ -475,7 +511,7 @@ If agent A is handling a user-originated CCB task and needs agent B's result to
 </details>
-## Editor Workflow
+### Editor Workflow
 <p align="center">
   <img src="assets/nvim.png" alt="Neovim integration with multi-model code review" width="860">
@@ -483,39 +519,35 @@ If agent A is handling a user-originated CCB task and needs agent B's result to
 CCB does not require leaving your editor. A common setup is: editor for code, CCB terminal for multi-agent planning, implementation, review, testing, and handoff.
-## Install And Update
+### Install And Update
-### Requirements
+#### Requirements
+- Node.js and npm for the recommended npm install path
 - Python 3.10+
 - `tmux`
-- At least one agent CLI you plan to use, such as Codex, Claude, Gemini, OpenCode, Droid, or Antigravity
+- At least one agent CLI you plan to use, such as Codex, Claude, Gemini, Kimi, OpenCode, Droid, or Antigravity
 - Linux, macOS, or WSL
-- Node.js 18+ when installing through npm
 Current v7 / newer versions do not claim native Windows support. Native Windows support only applies to the v5 line. If you are on Windows and want current versions, use WSL and keep both `ccb` and agent CLIs inside WSL.
-### npm first
+#### npm first
+For first install, prefer npm:
 ```bash
 npm install -g @seemseam/ccb
 ```
-The npm package is a lightweight installer wrapper around the official GitHub
-Release artifacts. It verifies `SHA256SUMS` before extracting the platform
-package.
-### Release package fallback
-For first install, prefer a package from [GitHub Releases](https://github.com/SeemSeam/claude_codex_bridge/releases). For existing installs:
+For later updates:
 ```bash
 ccb update
 ```
-Source checkout install is for development, fix validation, or temporary fallback when a release package is not available.
+[GitHub Releases](https://github.com/SeemSeam/claude_codex_bridge/releases) remain available for environments where npm is unavailable. Source checkout install is for development, fix validation, or temporary fallback.
-### Uninstall
+#### Uninstall
 ```bash
 ccb uninstall
@@ -525,7 +557,7 @@ ccb reinstall
 ./install.sh uninstall
 ```
-## FAQ
+### FAQ
 <details>
 <summary><b>The expected agents did not appear</b></summary>
@@ -555,11 +587,7 @@ Prefer a release package because it carries or handles the sidebar helper. Sourc
 </details>
-## Community And Credits
-Email: `bfly123@126.com`
-WeChat: `seemseam-com`
+### Community And Credits
 Thanks to the [Linux.do community](https://linux.do) for testing, feedback, and discussion.
@@ -569,7 +597,7 @@ Thanks to [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) fo
   <img src="assets/weixin.jpg" alt="WeChat group" width="300">
 </div>
-## Release Notes
+### Release Notes
 v7 highlights:
@@ -581,6 +609,53 @@ v7 highlights:
 - Hardened tmux, Ghostty, release helper, Codex trust, and provider session restore paths.
 <details open>
+<summary><b>v7.5.0</b> - Native CLI Providers And Homepage Sync</summary>
+- Adds managed native CLI provider support for Kimi plus broader native CLI
+  runtime groundwork, including runtime specs, session bindings, command
+  overrides, and cleanup coverage.
+- Moves Kimi and Antigravity completion detection toward provider-owned
+  session or transcript evidence instead of requiring model-printed `CCB_DONE`.
+- Uses Kimi's current `--auto-approve` flag for CCB auto-permission while
+  recognizing legacy/alias flags such as `--auto`, `--yes`, `-y`, and `--yolo`.
+- Synchronizes the English and Chinese README homepages with refreshed hero
+  assets and the seven public CLI-family positioning.
+</details>
+<details>
+<summary><b>v7.4.4</b> - Claude End-Turn And npm Release Surface</summary>
+- Completes Claude pane-backed asks promptly when a primary assistant response
+  emits `stop_reason=end_turn` with an observed request anchor and non-empty
+  reply, avoiding the previous 900-second timeout path.
+- Treats empty session-boundary terminal events with no prior assistant reply
+  as `incomplete/task_complete_empty_reply` with empty-provider diagnostics.
+- Restores the `@seemseam/ccb` npm release surface with package metadata, CLI
+  runner wrappers, and tag-triggered Trusted Publishing after GitHub release
+  assets are available.
+- Refreshes the v7 README homepage around canonical hero assets, npm-first
+  install, and clearer `ccb_self` guidance.
+</details>
+<details>
+<summary><b>v7.4.3</b> - PR #225 Reliability Follow-Up</summary>
+- Restores the Claude launcher contract: inline `--settings` now reflects the
+  materialized settings overlay without injecting provider env into settings
+  JSON.
+- Fixes Claude WSL Windows-executable environment forwarding so path variables
+  use `/p` translation while `ANTHROPIC_*` API values pass through as raw env
+  names.
+- Hardens Antigravity resume lookup for SQLite `bytes`, `str`, and
+  `memoryview` metadata and falls back to `--continue` if lookup fails.
+- Adds regression tests for the Claude settings contract, WSL API env
+  forwarding, and AGY resume fallback behavior.
+</details>
+<details>
 <summary><b>v7.4.2</b> - Self-Supervision And Empty Reply Guards</summary>
 - Hardens CCB self-supervision with bounded provider-runtime snapshots,

package/README_zh.md CHANGED Viewed

@@ -1,133 +1,78 @@
 <div align="center">
-# CCB - 可见、可控的多 Agent CLI 工作台
+# CCB
+**基于agent平权思想设计**
+**可见、可控的多 Agent 合作TUI工作台**
 <p>
-  <img src="https://img.shields.io/badge/v7-multi--agent--workspace-0B7285?style=for-the-badge" alt="v7 multi-agent workspace">
-  <img src="https://img.shields.io/badge/terminal-tmux-2F9E44?style=for-the-badge" alt="tmux">
-  <img src="https://img.shields.io/badge/providers-Codex%20%7C%20Claude%20%7C%20Gemini%20%7C%20OpenCode%20%7C%20Antigravity-CF1322?style=for-the-badge" alt="providers">
+  <img src="https://img.shields.io/badge/version-7.5.0-orange.svg" alt="version">
+  <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg" alt="platform">
+  <img src="https://img.shields.io/badge/providers-7%20CLI%20families-0B7285.svg" alt="providers">
 </p>
-[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20WSL-lightgrey.svg)]()
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)]()
-[![Version](https://img.shields.io/badge/version-7.4.2-orange.svg)]()
-[![Release](https://img.shields.io/badge/install-release--first-orange.svg)]()
 **中文** | [English](README.md)
-[为什么需要多 agents](#为什么需要多-agents) · [方案对比](#多-agents-方案怎么选) · [v7 界面](#v7-界面速览) · [快速开始](#快速开始) · [tmux 常规操作](#tmux-常规操作) · [配置团队](#配置-agent-团队) · [安装更新](#安装和更新)
+[快速开始](#快速开始) · [v7 界面](#v7-界面速览) · [配置团队](#配置-agent-团队) · [使用文档](docs/manuals/user-guide/) · [开发文档](docs/manuals/developer-guide/)
+<p align="center">
+  <img src="assets/readme_v7/ccb-hero-zh.png" alt="CCB v7 可见多 Agent CLI 工作台" width="960">
+</p>
 </div>
 ---
-## 为什么需要多 agents
+## 为什么用 CCB？
-小任务用单 agent 就够了；一旦任务需要规划、并行实现、审查、测试和交接，多 agents 的价值就变成：把角色、上下文、模型和执行过程拆开管理。CCB 的重点是把多个真实 CLI agent 放进同一个可见终端工作台。
-| 价值 | 直观理解 |
-| :--- | :--- |
-| 角色分离 | `main` 负责任务拆分，`worker` 负责实现，`reviewer` 负责审查。 |
-| 并行推进 | 一个 agent 写代码时，另一个 agent 可以读文档、跑验证或审查风险。 |
-| 模型和上下文分层 | 不同 agent 可以用不同 provider、model、API、worktree 和记忆。 |
-<details>
-<summary><b>展开：单 agent 为什么会吃力？</b></summary>
-- 角色混杂会影响上下文集中度：同一个会话既要做架构，又要写代码，还要自我审查，容易在长任务里丢掉重点。
-- 可执行复杂度有上限：任务越长，越需要拆分、交接、核对和回滚点。
-- 成本压力更高：如果所有步骤都依赖一个最强模型，简单任务也会变贵。
-- 工具和 skill 集中会变难管理：什么都给一个 agent，等于把权限、说明和工具复杂度全部堆在一起。
-- 串行等待效率低：一个 agent 在跑测试、读日志或长时间思考时，其他可并行工作无法自然展开。
-</details>
-## 多 agents 方案怎么选
-多 agents 不是一种固定形态。先用下面这张表判断大方向，细节可以展开看。
-| 方案 | 一句话 | 更适合你如果 |
+| 看得见 | 混合 provider | 项目级控制 |
 | :--- | :--- | :--- |
-| [Claude Code 原生 subagents](https://code.claude.com/docs/en/sub-agents) / [agent teams](https://code.claude.com/docs/en/agent-teams) | Claude Code 内部的原生分工。 | 你主要留在 Claude Code，并接受更多协调由 Claude lead 处理。 |
-| [Hive / OpenHive](https://github.com/aden-hive/hive) | 面向生产工作流的多 agent harness。 | 你要状态、恢复、观测、成本控制和图式工作流。 |
-| CCB | 可见、可控、混合 provider 的本地 CLI agent 工作台。 | 你要把 Codex、Claude、Gemini、OpenCode、Antigravity 等真实 CLI 放到一个项目终端里操作。 |
-<details>
-<summary><b>展开：模型、可控性、上下文和复杂工作流怎么区别？</b></summary>
-| 关键问题 | Claude Code 原生 | Hive / OpenHive | CCB |
-| :--- | :--- | :--- | :--- |
-| 能否使用不同家的模型 | 可给 teammate / subagent 指定 Claude 模型；整体仍在 Claude Code 体系内。 | 通过 LiteLLM 路线支持大量 hosted / local provider。 | 按 agent 选择 Codex、Claude、Gemini、OpenCode、Droid、Antigravity 等，并可设置独立 model / key / url。 |
-| 过程是否可见 | in-process 或 split panes，取决于模式和终端。 | 强调 runtime observability 和控制台视角。 | 默认就是 tmux 可见 pane，用户能直接点击、输入、复制、观察每个 CLI。 |
-| 拓扑是否可控 | 可自然语言指定队友，但运行时协调较多交给 lead。 | 由目标生成图式拓扑，偏 harness。 | 配置文件显式定义 agent、窗口、pane、worktree 和 sidebar。 |
-| 上下文是否可管理 | subagent / teammate 有独立上下文；team 有任务和消息状态。 | 角色记忆、状态持久化、恢复能力是核心卖点。 | 每个 CLI 保留自己的 provider 会话；项目共享记忆和 per-agent 记忆可选。 |
-| 最适合的落点 | Claude Code 内部的快速委派和团队模式。 | 业务流程自动化、长期运行和生产可靠性。 | 本地开发、代码协作、跨 provider CLI agent 可视化工作台。 |
+| 每个 agent 都是真实终端，支持界面排布设计。 | 一个命令同时并发运行多 CLI。 | 稳定后台通信，支持多线并发任务编排。 |
-CCB 也支持复杂工作流，但它不是自动生成 DAG 的 harness；复杂度主要通过 `.ccb/ccb.config`、多 window、角色记忆、worktree、model/API 配置和 ask/callback 路由显式设计。
+## 支持的 CLI
-</details>
-## CCB 是什么
-CCB 是一个项目级 agent CLI 工作台。它用 tmux 管理多个真实 CLI agent，把启动、恢复、通信、配置、窗口和运行态聚合在一个项目里。
-- **真实 CLI，不是模拟面板**：每个 agent pane 都运行对应 provider 的真实 CLI。
-- **可见协作**：sidebar 展示窗口、agent 状态和通信区；用户可以用鼠标直接切 pane。
-- **混合 provider**：一个项目里可以同时跑 Codex、Claude、Gemini、OpenCode、Droid 和 Antigravity（`agy`）。
-- **项目级配置**：`.ccb/ccb.config` 决定团队、布局、窗口、worktree、model、key、url。
-- **Roles**：全新的角色封装概念；它让携带“重武器”（独立 skills、记忆和
-  工具依赖等）的专业角色瞬间“降临”到目标项目中，成为一个可以快速热加载和
-  卸载的独立 agent，同时保持主环境、用户全局配置和项目运行状态不发生改变。
-- **可恢复运行态**：CCB 后台守护 agent pane，支持 attach、恢复和项目级清理。
-- **显式协作通道**：agent 可以通过 `/ask`、`$ask`、callback 和 silence 进行委派与交接。
-## v7 界面速览
-下面截图来自 `ccb_test2` 项目的真实深色终端会话。图片上的标注只解释区域，不代表必须记住所有快捷键。
-<p align="center">
-  <img src="assets/readme_v7/ccb-test2-terminal-annotated.png" alt="CCB v7 终端工作台区域说明" width="960">
+<p>
+  <img src="https://img.shields.io/badge/Codex-111111?style=flat-square&logo=openai&logoColor=white" alt="Codex">
+  <img src="https://img.shields.io/badge/Claude-D97757?style=flat-square&logo=anthropic&logoColor=white" alt="Claude">
+  <img src="https://img.shields.io/badge/Gemini-4285F4?style=flat-square&logo=googlegemini&logoColor=white" alt="Gemini">
+  <img src="https://img.shields.io/badge/OpenCode-111111?style=flat-square" alt="OpenCode">
+  <img src="https://img.shields.io/badge/Antigravity-6D5EF6?style=flat-square&logo=google&logoColor=white" alt="Antigravity">
+  <img src="https://img.shields.io/badge/Droid-3DDC84?style=flat-square&logo=android&logoColor=white" alt="Droid">
+  <img src="https://img.shields.io/badge/Kimi-111111?style=flat-square&logo=moonshotai&logoColor=white" alt="Kimi">
 </p>
-| 区域 | 作用 |
-| :--- | :--- |
-| Sidebar | 显示当前 window、agent 列表、provider 标签、当前选中 agent 和状态提示。 |
-| Comms | 显示 ask/callback 等协作消息和通信状态。 |
-| Agent pane | 每个 pane 是一个真实 CLI 会话，例如 Codex 或 Claude。 |
-| 当前输入目标 | 状态栏和 pane 边框会提示当前输入会发给哪个 agent。 |
-| 状态栏 | 显示项目名、当前 agent、CCB 版本、日期和常用鼠标/键盘提示。 |
-| Window 分组 | v7 可用 `[windows]` 把 agent 按 main、work、review、research 等窗口分组。 |
+可在 `.ccb/ccb.config` 中按 agent 混用不同 CLI。常用 provider id 包括 `codex`、`claude`、`gemini`、`kimi`、`opencode`、`agy`、`droid`；实际可用性取决于本机 CLI 安装和账号权限。
-Sidebar 相关实现使用并借鉴了 [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) 的思路，在此表示感谢。
+**全新角色规范**：可把 skills、记忆和工具依赖封装进自封闭 Role Pack，快速生成可热加载、可卸载的专业 agent。
 ## 快速开始
 ### 1. 安装或更新
-新用户可以先用 npm 安装：
+新安装推荐使用 npm 包：
 ```bash
 npm install -g @seemseam/ccb
 ```
-npm 包会下载并校验与你的平台匹配的 GitHub Release 包，然后提供 `ccb`、`ask`、`autonew` 和 `ctx-transfer`。
-也可以直接使用 release 包。到 [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases) 下载与你的平台匹配的包，解压后安装：
+安装完成后，后续更新直接使用 CCB 自带 updater：
 ```bash
-tar -xzf ccb-*.tar.gz
-cd ccb-*
-./install.sh install
+ccb update
 ```
-如果你已经装过 CCB：
+<details>
+<summary><b>GitHub release 包和源码安装兜底</b></summary>
+如果当前环境不方便使用 npm，可以到 [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases) 下载与你的平台匹配的包，解压后安装：
 ```bash
-ccb update
+tar -xzf ccb-*.tar.gz
+cd ccb-*
+./install.sh install
 ```
-<details>
-<summary><b>源码安装只建议开发或临时兜底使用</b></summary>
+源码安装只建议开发或临时兜底使用：
 ```bash
 git clone https://github.com/SeemSeam/claude_codex_bridge.git
@@ -135,10 +80,17 @@ cd claude_codex_bridge
 ./install.sh install
 ```
-源码安装会让全局 `ccb` / `ask` 链接回当前 checkout。普通用户更建议安装或更新到稳定 release。
+源码安装会让全局 `ccb` / `ask` 链接回当前 checkout。普通用户更建议使用 npm 包。
 </details>
+开箱即用：在项目目录执行 `ccb` 即可使用。
+如果启动时提示无法自动创建 `.ccb` 或找不到项目锚点，需要手动创建 `.ccb` 作为项目锚点：
+```bash
+mkdir -p .ccb
+```
 ### 2. 创建项目配置
 在项目根目录创建 `.ccb/ccb.config`。v7 推荐直接从多 window 拓扑理解配置：`[windows]` 定义窗口和 agent 分组，`agent:provider` 定义每个 agent 使用哪家 CLI，`(worktree)` 表示该 agent 使用独立 git worktree。
@@ -164,7 +116,7 @@ tips_height = "35%"
 comms_limit = 3
 ```
-如果你不确定应该如何分组、要几个 worker、哪些 agent 用 worktree、哪些 agent 需要独立模型或 API，可以让 `ccb_self` 使用它内置的 `ccb-config` 和你讨论并生成配置方案。空白项目默认包含 `ccb_self`；已有自定义配置可用 `ccb roles add agentroles.ccb_self:codex` 添加。
+如果你不确定应该如何分组、要几个 worker、哪些 agent 用 worktree、哪些 agent 需要独立模型或 API，可以直接问当前工作台里的 `ccb_self`。它是 CCB 内置的 self-agent，理解 CCB 命令、配置权威层、roles、windows、reload 边界和常见恢复路径，并能用私有 `ccb-config` skill 和你讨论后生成配置方案。空白项目默认包含 `ccb_self`。
 验证配置：
@@ -186,7 +138,90 @@ ccb
 /ask reviewer review the latest parser changes and list blocking issues.
 ```
-## 日常操作
+也可以在工作编排中让 agent 自动调用 `/ask` 完成委派和交接。
+### v7 界面速览
+| 区域 | 说明 |
+| :--- | :--- |
+| Sidebar | 显示刷新/关闭 CCB 控件、window 和 agent 列表、内部通信状态，以及可在配置文件中修改并热加载的 tips。 |
+| 鼠标操作 | 支持点击切换 window、agent 和 pane，也可在通信区刷新、kill 或删除条目。 |
+| 工作区 | 每个 pane 都是真实 CLI；可以鼠标点击切换，也可以用 tmux 快捷键切换。 |
+| 常用技巧 | `Ctrl-b h/j/k/l` 切换相邻 pane，`Ctrl-b z` 放大或还原当前 CLI pane。 |
+### 联系方式
+- Email: `bfly123@126.com`
+- 微信: `seemseam-com`
+---
+## 更多阅读
+初次使用可以先从快速开始进入；下面内容补充 CCB 的设计边界、方案对比、日常操作和配置方式。
+### CCB 是什么
+CCB 是一个项目级 agent CLI 工作台。它用 tmux 管理多个真实 CLI agent，把启动、恢复、通信、配置、窗口和运行态聚合在一个项目里。
+- **真实 CLI，不是模拟面板**：每个 agent pane 都运行对应 provider 的真实 CLI。
+- **可见协作**：sidebar 展示窗口、agent 状态和通信区；用户可以用鼠标直接切 pane。
+- **混合 provider**：一个项目里可以同时跑 Codex、Claude、Gemini、OpenCode、Droid、Antigravity（`agy`）和 Kimi（`kimi`）。
+- **项目级配置**：`.ccb/ccb.config` 决定团队、布局、窗口、worktree、model、key、url。
+- **内置 CCB 专家**：空白项目默认包含 `ccb_self`，它是具备 CCB 自理解能力的自维护 agent，可帮助使用 CCB、设计配置、诊断运行态、恢复工作流。
+- **Roles**：全新的角色封装概念；它让携带“重武器”（独立 skills、记忆和
+  工具依赖等）的专业角色瞬间“降临”到目标项目中，成为一个可以快速热加载和
+  卸载的独立 agent，同时保持主环境、用户全局配置和项目运行状态不发生改变。
+- **可恢复运行态**：CCB 后台守护 agent pane，支持 attach、恢复和项目级清理。
+- **显式协作通道**：agent 可以通过 `/ask`、`$ask`、callback 和 silence 进行委派与交接。
+### 为什么需要多 agents
+小任务用单 agent 就够了；一旦任务需要规划、并行实现、审查、测试和交接，多 agents 的价值就变成：把角色、上下文、模型和执行过程拆开管理。CCB 的重点是把多个真实 CLI agent 放进同一个可见终端工作台。
+| 价值 | 直观理解 |
+| :--- | :--- |
+| 角色分离 | `main` 负责任务拆分，`worker` 负责实现，`reviewer` 负责审查。 |
+| 并行推进 | 一个 agent 写代码时，另一个 agent 可以读文档、跑验证或审查风险。 |
+| 模型和上下文分层 | 不同 agent 可以用不同 provider、model、API、worktree 和记忆。 |
+<details>
+<summary><b>展开：单 agent 为什么会吃力？</b></summary>
+- 角色混杂会影响上下文集中度：同一个会话既要做架构，又要写代码，还要自我审查，容易在长任务里丢掉重点。
+- 可执行复杂度有上限：任务越长，越需要拆分、交接、核对和回滚点。
+- 成本压力更高：如果所有步骤都依赖一个最强模型，简单任务也会变贵。
+- 工具和 skill 集中会变难管理：什么都给一个 agent，等于把权限、说明和工具复杂度全部堆在一起。
+- 串行等待效率低：一个 agent 在跑测试、读日志或长时间思考时，其他可并行工作无法自然展开。
+</details>
+### 多 agents 方案怎么选
+多 agents 不是一种固定形态。先用下面这张表判断大方向，细节可以展开看。
+| 方案 | 一句话 | 更适合你如果 |
+| :--- | :--- | :--- |
+| [Claude Code 原生 subagents](https://code.claude.com/docs/en/sub-agents) / [agent teams](https://code.claude.com/docs/en/agent-teams) | Claude Code 内部的原生分工。 | 你主要留在 Claude Code，并接受更多协调由 Claude lead 处理。 |
+| [Hive / OpenHive](https://github.com/aden-hive/hive) | 面向生产工作流的多 agent harness。 | 你要状态、恢复、观测、成本控制和图式工作流。 |
+| CCB | 可见、可控、混合 provider 的本地 CLI agent 工作台。 | 你要把 Codex、Claude、Gemini、Kimi、OpenCode、Antigravity 等真实 CLI 放到一个项目终端里操作。 |
+<details>
+<summary><b>展开：模型、可控性、上下文和复杂工作流怎么区别？</b></summary>
+| 关键问题 | Claude Code 原生 | Hive / OpenHive | CCB |
+| :--- | :--- | :--- | :--- |
+| 能否使用不同家的模型 | 可给 teammate / subagent 指定 Claude 模型；整体仍在 Claude Code 体系内。 | 通过 LiteLLM 路线支持大量 hosted / local provider。 | 按 agent 选择 Codex、Claude、Gemini、Kimi、OpenCode、Droid、Antigravity 等，并可设置独立 model / key / url。 |
+| 过程是否可见 | in-process 或 split panes，取决于模式和终端。 | 强调 runtime observability 和控制台视角。 | 默认就是 tmux 可见 pane，用户能直接点击、输入、复制、观察每个 CLI。 |
+| 拓扑是否可控 | 可自然语言指定队友，但运行时协调较多交给 lead。 | 由目标生成图式拓扑，偏 harness。 | 配置文件显式定义 agent、窗口、pane、worktree 和 sidebar。 |
+| 上下文是否可管理 | subagent / teammate 有独立上下文；team 有任务和消息状态。 | 角色记忆、状态持久化、恢复能力是核心卖点。 | 每个 CLI 保留自己的 provider 会话；项目共享记忆和 per-agent 记忆可选。 |
+| 最适合的落点 | Claude Code 内部的快速委派和团队模式。 | 业务流程自动化、长期运行和生产可靠性。 | 本地开发、代码协作、跨 provider CLI agent 可视化工作台。 |
+CCB 也支持复杂工作流，但它不是自动生成 DAG 的 harness；复杂度主要通过 `.ccb/ccb.config`、多 window、角色记忆、worktree、model/API 配置和 ask/callback 路由显式设计。
+</details>
+### 日常操作
 | 目标 | 命令 |
 | :--- | :--- |
@@ -200,7 +235,7 @@ ccb
 | 预览配置热加载计划，不修改 tmux | `ccb reload --dry-run` |
 | 应用支持的配置变更，不重启其他 agent | `ccb reload` |
-## tmux 常规操作
+### tmux 常规操作
 CCB 虽然基本全部可以使用鼠标操作，但是学会 tmux 命令可以显著增加便利性。下面列举了部分常用的键盘操作快捷键。
@@ -242,7 +277,7 @@ CCB 虽然基本全部可以使用鼠标操作，但是学会 tmux 命令可以
 </details>
-## 配置 agent 团队
+### 配置 agent 团队
 CCB 配置有三层，优先级从低到高：
@@ -270,7 +305,7 @@ CCB 配置有三层，优先级从低到高：
 如果你想先讨论配置而不是手写，可以直接让 `ccb_self` 描述目标团队。空白项目默认已经有这个路由；使用用户配置或项目配置覆盖内置默认的项目，如果还没有 `ccb_self`，需要先添加 `agentroles.ccb_self`。它的内置 `ccb-config` skill 会先提出完整方案，确认后再修改 `.ccb/ccb.config`。
-### Role Packs
+#### Role Packs
 Role Pack 用来定义可复用的 agent 角色。一个 role 可以包含稳定身份、职责、
 记忆、provider-specific skills、工具 hooks 和依赖准备逻辑。这样项目配置会更短，
@@ -292,10 +327,11 @@ ccb roles update agentroles.archi
 role；如果锁已经落后，交互式启动会询问是否就地刷新项目锁，非交互启动只打印
 提醒。
-强烈建议 CCB 项目保留 `ccb_self`，因为它负责 CCB 配置维护、运行诊断、受保护
-恢复、工作链修复和单 agent 重启辅助，同时不接管业务任务。空白项目的内置默认配置
-已经包含它；已有项目，或使用用户配置/项目配置替换内置默认的项目，需要该维护
-agent 时应显式把它作为 window leaf 加进去：
+强烈建议 CCB 项目保留 `ccb_self`，因为它是 CCB 内置专家 agent，携带 CCB
+项目配置、命令使用、role 绑定、reload 边界、运行诊断、受保护恢复、工作链修复和
+单 agent 重启辅助等专用知识，同时不接管业务任务。空白项目的内置默认配置已经
+包含它；已有项目，或使用用户配置/项目配置替换内置默认的项目，需要该维护 agent
+时应显式把它作为 window leaf 加进去：
 ```bash
 ccb roles add agentroles.ccb_self:codex
@@ -316,7 +352,7 @@ provider home。
 <details>
 <summary><b>配置格式示例：单窗口、多 window、per-agent 模型/API</b></summary>
-### 单窗口紧凑配置
+#### 单窗口紧凑配置
 ```text
 cmd; main:codex, worker1:codex(worktree); reviewer:claude
@@ -330,7 +366,7 @@ cmd; main:codex, worker1:codex(worktree); reviewer:claude
 - `;` 表示左右分栏，`,` 表示上下堆叠。
 - `(worktree)` 表示该 agent 使用独立 git worktree。
-### 多 window 拓扑
+#### 多 window 拓扑
 当你想把规划、实现、审查、研究分到不同 tmux window 时，使用 `version = 2` 和 `[windows]`：
@@ -357,7 +393,7 @@ comms_limit = 3
 注意：`cmd` 只属于紧凑/混合单窗口布局；`[windows]` 拓扑里不要写 `cmd`。
-### 托管 Neovim 工具 window
+#### 托管 Neovim 工具 window
 工具 window 是 CCB 管理的 tmux window，但不是 agent。它不会出现在 `ccb ask` 目标中，也不会创建 provider runtime 记录。
@@ -378,7 +414,7 @@ label = "neovim"
 托管 profile 默认使用 ASCII 图标，避免没有 Nerd Font 的终端出现方块/乱码。确认终端字体支持 Nerd Font 时，可用 `CCB_LAZYVIM_ICON_STYLE=glyph ccb-nvim` 恢复 LazyVim 图标。
 用 `ccb tools doctor neovim` 验证托管 profile。LazyVim 真正可用时会显示 `neovim_status: ok` 和 `lazyvim_health_status: ok`；插件目录损坏或半下载会显示 `degraded`，重新运行 `ccb tools install neovim` 会尝试修复。
-### 给 agent 单独配置模型、API key 或 base URL
+#### 给 agent 单独配置模型、API key 或 base URL
 如果只需要布局，用紧凑格式即可；如果某些 agent 需要单独模型或 API 路由，在紧凑头后追加 TOML overlay：
@@ -401,10 +437,12 @@ model = "sonnet"
 </details>
-## 使用 ccb_self 配置 CCB
+### 使用 ccb_self 配置 CCB
 完整的 `ccb-config` skill 属于 `agentroles.ccb_self` 角色，不再作为所有 agent 都继承的公共 skill。CCB 默认会安装或刷新这个 Role Pack，空白项目的内置默认配置也会包含 `ccb_self`。已有项目，或使用用户配置/项目配置替换内置默认的项目，需要维护助手时应显式绑定它。
+`ccb_self` 不只是配置助手，它被设计成 CCB 的自理解 agent。使用 CCB 时遇到布局解释、团队拓扑选择、`.ccb/ccb.config` 迁移、运行态诊断、恢复路径或工作流修复问题，都可以先问它。
 如果你不想手写 `.ccb/ccb.config`，可以直接询问 `ccb_self`，再用自然语言描述项目目标、并行程度、窗口分组、worktree 隔离、provider/model/API 偏好。`ccb_self` 会使用它内置的 `ccb-config` 和你讨论后提出完整配置方案。
 示例：
@@ -429,7 +467,7 @@ ccb ask ccb_self "为一个 Python library 设计团队：main 负责任务拆
 </details>
-## Agent 之间如何协作
+### Agent 之间如何协作
 普通 `ask` 是提交即返回：把任务交给目标 agent 后，当前 agent 不应该轮询等待。
@@ -462,7 +500,7 @@ spill 只是兜底，所以只要精确输入或完整输出重要，就应该
 </details>
-## 编辑器工作流
+### 编辑器工作流
 <p align="center">
   <img src="assets/nvim.png" alt="Neovim 集成多模型代码审查" width="860">
@@ -470,37 +508,35 @@ spill 只是兜底，所以只要精确输入或完整输出重要，就应该
 CCB 不要求你离开编辑器。常见方式是：编辑器负责写代码，CCB 终端负责多 agent 规划、实现、审查、测试和交接。
-## 安装和更新
+### 安装和更新
-### 环境要求
+#### 环境要求
+- 推荐 npm 安装路径需要 Node.js 和 npm
 - Python 3.10+
 - `tmux`
-- 至少一个你要使用的 agent CLI，例如 Codex、Claude、Gemini、OpenCode、Droid 或 Antigravity
+- 至少一个你要使用的 agent CLI，例如 Codex、Claude、Gemini、Kimi、OpenCode、Droid 或 Antigravity
 - Linux、macOS 或 WSL
-- 通过 npm 安装时需要 Node.js 18+
 当前 v7 / 新版本不声明原生 Windows 支持。原生 Windows 只支持到 v5 线；如果你在 Windows 上使用新版本，推荐使用 WSL，并让 `ccb` 与 agent CLI 都运行在 WSL 内。
-### npm 优先
+#### npm 优先
+首次安装推荐使用 npm：
 ```bash
 npm install -g @seemseam/ccb
 ```
-npm 包是官方 GitHub Release artifacts 的轻量安装 wrapper，会先校验 `SHA256SUMS`，再解压平台包。
-### Release 包兜底
-首次安装推荐使用 [GitHub Releases](https://github.com/SeemSeam/claude_codex_bridge/releases) 的 release 包；已安装用户推荐：
+后续更新直接使用：
 ```bash
 ccb update
 ```
-源码 checkout 安装只适合开发、验证修复或 release 包暂不可用时临时使用。
+[GitHub Releases](https://github.com/SeemSeam/claude_codex_bridge/releases) 仍作为不方便使用 npm 时的备选路径。源码 checkout 安装只适合开发、验证修复或临时兜底。
-### 卸载
+#### 卸载
 ```bash
 ccb uninstall
@@ -510,7 +546,7 @@ ccb reinstall
 ./install.sh uninstall
 ```
-## 常见问题
+### 常见问题
 <details>
 <summary><b>启动后没有看到预期 agent</b></summary>
@@ -540,11 +576,7 @@ ccb reinstall
 </details>
-## 社区和致谢
-📧 Email: `bfly123@126.com`
-💬 微信: `seemseam-com`
+### 社区和致谢
 感谢 [Linux.do 社区](https://linux.do) 在测试、反馈和讨论中的支持。
@@ -554,7 +586,7 @@ ccb reinstall
   <img src="assets/weixin.jpg" alt="微信群" width="300">
 </div>
-## 新版本记录
+### 新版本记录
 v7 线重点：
@@ -566,6 +598,52 @@ v7 线重点：
 - 加固 tmux、Ghostty、release helper、Codex trust 和 provider 会话恢复路径。
 <details open>
+<summary><b>v7.5.0</b> - 原生 CLI Provider 与首页同步</summary>
+- 新增 Kimi managed native CLI provider 支持，并补齐更通用的 native CLI
+  runtime 基础能力，覆盖 runtime spec、session binding、启动命令覆盖和清理路径。
+- Kimi 和 Antigravity 的完成判定改为读取 provider 自有 session 或
+  transcript 证据，不再要求模型打印 `CCB_DONE`。
+- CCB auto-permission 对 Kimi 默认注入当前版本支持的 `--auto-approve`，
+  同时识别 `--auto`、`--yes`、`-y`、`--yolo` 等旧版或别名标识，避免重复注入。
+- 同步英文和中文 README 首页，刷新 hero assets，并统一为 7 个公开 CLI
+  family 的定位。
+</details>
+<details>
+<summary><b>v7.4.4</b> - Claude end_turn 与 npm 发布面修复</summary>
+- Claude pane-backed ask 在 primary assistant response 带
+  `stop_reason=end_turn`、已看到请求 anchor 且回复非空时，会立即产生
+  `TURN_BOUNDARY(reason=assistant_end_turn)` 并正常完成，不再等到 900 秒
+  reliability timeout。
+- 空的 session-boundary terminal event 如果之前没有 assistant 回复证据，会
+  终止为 `incomplete/task_complete_empty_reply`，并带
+  `empty_provider_reply` 诊断。
+- 恢复 `@seemseam/ccb` npm 发布面：补回 package metadata、CLI runner
+  wrappers，以及等待 GitHub release assets 后再发布 npm 包的 Trusted
+  Publishing workflow。
+- 刷新 v7 README 首页：使用 canonical hero assets，默认 npm-first 安装，并
+  更明确说明 `ccb_self` 是 CCB 内置的使用、配置、诊断和恢复专家。
+</details>
+<details>
+<summary><b>v7.4.3</b> - PR #225 可靠性跟进修复</summary>
+- 恢复 Claude launcher contract：inline `--settings` 只反映 materialized
+  settings overlay，不再把 provider env 注入 settings JSON。
+- 修复 Claude 在 WSL 调 Windows executable 时的环境透传：路径变量使用 `/p`
+  转换，`ANTHROPIC_*` API 值作为 raw env 名透传。
+- 加固 Antigravity resume lookup，兼容 SQLite 返回的 `bytes`、`str` 和
+  `memoryview` metadata，并在查找失败时降级为 `--continue`。
+- 新增 Claude settings contract、WSL API env forwarding 和 AGY resume
+  fallback 的回归测试。
+</details>
+<details>
 <summary><b>v7.4.2</b> - Self-supervision 与空回复防护</summary>
 - 通过有界 provider-runtime snapshot、project-view 活动证据、suspicion

package/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 7.4.2
1	+ 7.5.0

package/package.json CHANGED Viewed

@@ -1,8 +1,8 @@
 {
   "name": "@seemseam/ccb",
-  "version": "7.4.2",
-  "description": "Visible, controllable multi-agent CLI workspace for Codex, Claude, Gemini, OpenCode, and Antigravity.",
-  "license": "MIT",
+  "version": "7.5.0",
+  "description": "Visible, controllable multi-agent CLI workspace for Codex, Claude, Gemini, Kimi, OpenCode, Antigravity, and Droid.",
+  "license": "AGPL-3.0-only",
   "homepage": "https://github.com/SeemSeam/claude_codex_bridge#readme",
   "repository": {
     "type": "git",