From c3770ed04b583bab196d19cacfb63784a2fedd40 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sat, 21 Nov 2026 13:04:45 +0900 Subject: [PATCH 1/5] docs: add AGENTS.md, contributing and development skills, issue forms and a concise README - AGENTS.md states the repository's rules in their shortest form and links to the full statements: where a fact lives, who owns what (mcpp, backend, plugins, mcppls), the triage before a change (whose problem, core or plugin, fix or workaround), versions, build and test, code and the change workflow. - .agents/skills/mcpp-ide-contributing: triage, issues, branches, commits, pull requests and the rules an AI agent follows besides. - .agents/skills/mcpp-ide-development: the environment, the tests of each component, common changes (protocol, spec/, strings, fixtures, pins), diagnosing and the release procedure. - .github/ISSUE_TEMPLATE: bug, feature and task forms; blank issues are disabled, and questions, problems of mcpp and of mcppls are sent where they belong. A pull-request template. - README.md and README.zh-CN.md: badges, the architecture in one diagram, one table of the editors and one of installs, prompts for agents, and links. What they no longer state is in docs/versions.md (series and tags, the project's mcpp, the test features by mcpp). - .github/components.tsv: the issue and pull-request forms are documentation, so a change of them runs the documentation checks only (test_changes.sh holds the case). --- .agents/skills/mcpp-ide-contributing/SKILL.md | 73 +++++++ .agents/skills/mcpp-ide-development/SKILL.md | 77 +++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 64 ++++++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/feature_request.yml | 34 +++ .github/ISSUE_TEMPLATE/task.yml | 22 ++ .github/components.tsv | 3 + .github/pull_request_template.md | 26 +++ .github/scripts/test_changes.sh | 2 + AGENTS.md | 100 +++++++++ README.md | 204 +++++++----------- README.zh-CN.md | 174 +++++++-------- docs/README.md | 1 + docs/versions.md | 42 ++++ 14 files changed, 606 insertions(+), 227 deletions(-) create mode 100644 .agents/skills/mcpp-ide-contributing/SKILL.md create mode 100644 .agents/skills/mcpp-ide-development/SKILL.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/task.yml create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 docs/versions.md diff --git a/.agents/skills/mcpp-ide-contributing/SKILL.md b/.agents/skills/mcpp-ide-contributing/SKILL.md new file mode 100644 index 0000000..3617688 --- /dev/null +++ b/.agents/skills/mcpp-ide-contributing/SKILL.md @@ -0,0 +1,73 @@ +--- +name: mcpp-ide-contributing +description: Use when contributing to mcpp-ide -- reporting a bug, proposing a feature, opening an issue or a pull request, or making any change as a person or an AI agent. Covers triage (core or plugin, fix or workaround), issue and pull-request conventions, commits, review and merge. +--- + +# Contributing to mcpp-ide + +Read [AGENTS.md](../../../AGENTS.md) first: who owns what, and the rules every change follows. The +flow is **issue → branch → pull request → CI → review → squash merge**. Nothing is pushed to `main` +directly, whatever its size, and that includes a version bump or a change to documentation. + +## 1. Triage before anything else + +Answer the three questions of AGENTS.md §3 and write the answers into the issue: + +| Question | How to decide | Outcome | +|---|---|---| +| Whose problem? | reproduce without the editor: `mcpp-ide self-check --json`, `mcpp-ide serve`, the mock mcpp | mcpp, mcppls or an editor's upstream: report it there and link it here | +| Core or plugin? | would another editor need the same change? | yes → backend (`src/`, `spec/`, `protocol/`); no → `mide-plugins/` | +| Fix or workaround? | does the cause lie in this repository? | no → no workaround by default; an exception states its cause, the upstream issue, why it cannot wait and when it is removed | + +## 2. Issues + +Open one with a template (`.github/ISSUE_TEMPLATE/`): **Bug report**, **Feature request** or +**Task**. A blank issue is not offered, and a question goes to the +[forum](https://forum.d2learn.org/category/20). + +- Title: `(): `, for example `fix(clion): the test tree loses a case's + location after a rebuild`. The type is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, + `ci`, `chore`. The component is `backend`, `vscode`, `clion`, `nvim`, `docs` or `ci`. +- A bug carries the output of `mcpp-ide self-check --json` (backend, mcpp, mcppls, xlings, trust), + the editor and its version, the steps, the expected and actual behaviour, and the triage answers. + The IDE report (**mcpp: Export IDE Report**) is attached when the backend is involved. +- A feature states the motivation, which party it belongs to, the protocol or `spec/` change it + needs, and what each editor shows. A change larger than one pull request gets a design record in + `.agents/docs/` (`YYYY-MM-DD-.md`, opening with its status) before any code. + +## 3. Branches and commits + +- Branch from the latest `main`: `/`, for example `fix/clion-case-location`. A + release is made on `release/X.Y.Z` (see [mcpp-ide-development](../mcpp-ide-development/SKILL.md)). +- A commit is English and declarative, `(): ` or `X.Y.Z: ` for + a release, with no emoji. Its body says why, citing the issue, the design record or mcpp's spec + clause where there is one. + +## 4. Pull requests + +- One pull request does one thing and links the issue it closes (`Closes #N`). The title follows + the commit form, since it becomes the subject of the squash merge. +- The body follows `.github/pull_request_template.md`: summary, triage, the criteria (the test that + fails before and passes after, and where it ran), compatibility and the checklist. +- A change of behaviour updates, in the same pull request: `protocol/protocol.schema.json`, the docs + it touches (README.md and README.zh-CN.md together), `spec/i18n` in both languages, and + CHANGELOG.md under its series. +- The required check is `ci`. It runs the components the change reaches (`.github/components.tsv`), + so a backend change runs every plugin. A red job is fixed, never retried until green. +- The merge is a squash with an explicit subject and body; GitHub's composed message is not used. + +## 5. AI agents + +An agent contributes under the same rules, plus these: + +- **Read before writing:** AGENTS.md, the docs it links for the area, and the neighbouring code. Do + the triage before editing, and say in the pull request which party the problem belongs to. +- **Ask before outward actions:** creating an issue, a pull request, a comment, a tag or a release + needs the person's confirmation. Never push to `main`, force-push a shared branch, merge, tag or + publish unless explicitly asked. +- **Report what ran:** each criterion says whether it ran locally, on which system, or was left to + CI. A test that did not run is not described as passing. +- **Stay in scope:** no drive-by refactors, no new dependency and no workaround for another party's + problem without the person's decision. +- **No attribution trailers:** commits and pull requests carry no `Co-Authored-By` lines or + generated-by footers. The person who submits a change is responsible for it. diff --git a/.agents/skills/mcpp-ide-development/SKILL.md b/.agents/skills/mcpp-ide-development/SKILL.md new file mode 100644 index 0000000..e2e87aa --- /dev/null +++ b/.agents/skills/mcpp-ide-development/SKILL.md @@ -0,0 +1,77 @@ +--- +name: mcpp-ide-development +description: Use when setting up a development environment for mcpp-ide, building or testing the backend or an editor plugin, changing the protocol, spec/, fixtures or strings, bumping a pinned tool, or preparing a release (a series vX.Y.0 or a plugin patch). +--- + +# Developing mcpp-ide + +## 1. Environment + +The pins live in [.github/versions.env](../../../.github/versions.env), which CI reads. A local +setup uses the same versions: + +| Tool | Version | For | Install | +|---|---|---|---| +| xlings | `XLINGS_VERSION` | mcpp, toolchains, gradle | [xlings](https://github.com/d2learn/xlings) | +| mcpp | `.xlings.json` (= `MCPP_VERSION`) | the backend; its toolchain comes from `mcpp.toml` | `xlings install` in the repository | +| Node.js | 22 | the VS Code extension, the web UI tests | any Node 22 | +| VS Code | `VSCODE_VERSION` (the oldest supported) | the extension's e2e tests | fetched by `@vscode/test-electron` | +| Gradle and its JDK | xlings's | the CLion plugin | `xlings install gradle` | +| Neovim | 0.10+ | the Neovim plugin | system package | + +Check the environment with `mcpp build && mcpp run mcpp-ide -- self-check`. + +## 2. Build and test, per component + +Run what a change reaches ([.github/components.tsv](../../../.github/components.tsv)). A backend +change reaches every plugin, because each plugin is tested over the backend. + +| Component | Paths | Commands | +|---|---|---| +| backend | `src/`, `protocol/`, `spec/`, `webui/`, `tests/`, `testsupport/`, `mcpp.toml` | `mcpp build`, `mcpp test`, `mcpp run mcpp-ide-dev -- check-sources`, `mcpp run mcpp-ide-dev -- check-i18n` | +| vscode | `mide-plugins/vscode/` | `npm ci && npm test`; `npm run test:parity`, `npm run test:webui`, `npm run test:e2e`; `npm run package` | +| clion | `mide-plugins/clion/` | `gradle test buildPlugin verifyPlugin` | +| nvim | `mide-plugins/nvim/` | `nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua` | +| CI | `.github/` | `bash .github/scripts/test_changes.sh`, `bash .github/scripts/release-plan.sh` | + +## 3. Common changes + +- **A protocol method or notification:** change `protocol/protocol.schema.json` together with the + backend and every plugin that uses it. The backend's tests check its answers against the schema. +- **A setting, command or editor string:** edit `spec/` (`settings.json`, `commands.json`, + `i18n/*.json`), then run `mcpp run mcpp-ide-dev -- gen vscode` and commit what it rewrites in + `mide-plugins/vscode`. CLion's declarations are generated at build time. Neovim reads the table at + run time. A command that an editor does not offer states why (`omitted`). +- **A runtime string:** pass it through `t(...)` and add its Chinese entry to + `spec/i18n/runtime.zh-cn.json`; `check-i18n` enforces this. +- **What mcpp reports:** run `mcpp run mcpp-ide-dev -- capture` against a real mcpp and review the + diff in `protocol/fixtures`. Update `protocol/mcpp-contract.schema.json` if the contract grew. + The mock mcpp and every plugin's tests replay these fixtures. +- **A feature of a newer mcpp or mcppls:** enable it from what mcpp states (`features`). An earlier + release is described by a table frozen at that release, not by comparing versions. +- **A pinned tool:** change `.github/versions.env`, `.xlings.json` and `mcpp = ">=..."` in + `mcpp.toml` together, and only to versions that are already released and indexed. + +## 4. Diagnosing + +- `mcpp-ide self-check --json` reports the backend, mcpp and its contract, mcppls, xlings and trust. +- The IDE report (**mcpp: Export IDE Report**, `:Mcpp exportReport`) collects the projects' mcpp, + mcppls's status, the settings in effect, recent jobs and the backend's log. +- `mcpp.backend.logLevel` controls how much the backend writes to the editor's log. + +## 5. Release + +The rules are in AGENTS.md §4 and [release-plan.sh](../../../.github/scripts/release-plan.sh). + +1. Decide the kind. Any backend path changed since `vX.Y.0` means a series release `vX.Y+1.0` (or + `vX+1.0.0`). Otherwise it is a plugin patch, `-vX.Y.Z+1`. +2. On `release/`, bump the version statements (all six for a series, only the plugin's + own for a patch) and add the CHANGELOG.md section under its series, listing each component's + version. Then run `bash .github/scripts/release-plan.sh `. +3. Open a pull request titled `X.Y.Z: ` and merge it after `ci` passes. +4. Tag the merge commit and push the tag. `release.yml` runs CI, publishes the GitHub release with + `SHA256SUMS`, then submits the same VSIX to Open VSX and the same ZIP to JetBrains Marketplace. + The Visual Studio Marketplace upload is manual. The secrets are `OPENVSX_TOKEN` and + `JETBRAINS_TOKEN`; Marketplace availability follows JetBrains review. +5. Watch the run until every job passes, then check that the release assets install + (`mcpp-ide self-check` on a project). diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..24ab8e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,64 @@ +name: Bug report +description: mcpp-ide or one of its editor plugins behaves wrongly +title: "fix(): " +labels: [bug] +body: + - type: markdown + attributes: + value: | + Triage first ([AGENTS.md §3](https://github.com/mcpp-community/mcpp-ide/blob/main/AGENTS.md)): + reproduce without the editor where you can, and report problems of mcpp or mcppls in their own repositories. + - type: dropdown + id: component + attributes: + label: Component + options: [backend, vscode, clion, nvim, packaging / install, docs] + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: The smallest project and the actions that show the problem. + placeholder: | + 1. mcpp new demo && cd demo + 2. ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected and actual behaviour + validations: + required: true + - type: textarea + id: selfcheck + attributes: + label: mcpp-ide self-check --json + description: The backend, mcpp and its contract, mcppls, xlings and trust. + render: json + validations: + required: true + - type: input + id: editor + attributes: + label: Editor and OS + placeholder: VS Code 1.95 / CLion 2026.1 / Neovim 0.11 on Ubuntu 24.04 x86_64 + validations: + required: true + - type: dropdown + id: party + attributes: + label: Whose problem is it? + description: Where does it still reproduce once the editor is taken away? + options: + - The backend (every editor shows it) + - One editor plugin only + - Not sure yet + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs or IDE report + description: "mcpp: Export IDE Report (Neovim :Mcpp exportReport), or the backend's log." diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f9d6354 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Question or discussion + url: https://forum.d2learn.org/category/20 + about: Usage questions and ideas go to the community forum. + - name: A problem of mcpp itself + url: https://github.com/mcpp-community/mcpp/issues/new/choose + about: Wrong output from mcpp (builds, tests, the machine contract) is reported to mcpp. + - name: A C++ language feature (mcppls) + url: https://github.com/Sunrisepeak/mcpp-language-server/issues + about: Completion, navigation and diagnostics of C++ files come from mcppls. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..e16e59e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,34 @@ +name: Feature request +description: A new capability or a change of behaviour +title: "feat(): " +labels: [enhancement] +body: + - type: textarea + id: motivation + attributes: + label: Motivation + description: The problem it solves, and for whom. + validations: + required: true + - type: dropdown + id: party + attributes: + label: Where does it belong? + description: A decision every editor shares belongs to the backend; plugins only map it onto their UI. + options: + - Backend (protocol / spec), shown by every editor + - One editor plugin's presentation + - Needs mcpp or mcppls to state something new first + validations: + required: true + - type: textarea + id: design + attributes: + label: Design + description: The protocol or spec/ change, what each editor shows, and the mcpp feature it relies on. A change larger than one pull request starts with a record in .agents/docs/. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..3c28a2f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,22 @@ +name: Task +description: Maintenance, refactoring, CI, documentation or a release +labels: [task] +body: + - type: dropdown + id: type + attributes: + label: Type + options: [refactor, perf, test, docs, ci, chore, release] + validations: + required: true + - type: textarea + id: what + attributes: + label: What and why + validations: + required: true + - type: textarea + id: done + attributes: + label: Done when + description: The criteria that close this task. diff --git a/.github/components.tsv b/.github/components.tsv index 18d1e99..54d5476 100644 --- a/.github/components.tsv +++ b/.github/components.tsv @@ -25,5 +25,8 @@ docs docs/* docs agents/* docs *.md docs LICENSE +# The forms of issues and pull requests are read by people too, although they live under .github/. +docs .github/ISSUE_TEMPLATE/* +docs .github/pull_request_template.md # The workflows, the scripts and the pins every job runs with. all .github/* diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6bd7edd --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## Summary + + + +## Triage + + + +## Criteria + + + +## Compatibility + + + +## Checklist + +- [ ] One thing; the title is `(): ` (or `X.Y.Z: `). +- [ ] The protocol schema, docs (README in both languages), `spec/i18n` and CHANGELOG.md follow the behaviour. +- [ ] `spec/` is edited, not its output; `mcpp-ide-dev gen vscode` leaves no diff. +- [ ] No commit carries an attribution trailer (`git log origin/main..HEAD -i --grep=Co-Authored-By` is empty). diff --git a/.github/scripts/test_changes.sh b/.github/scripts/test_changes.sh index 6213e91..ebd3707 100755 --- a/.github/scripts/test_changes.sh +++ b/.github/scripts/test_changes.sh @@ -26,6 +26,8 @@ check "its README is the plugin's" pull_request vscode=true docs=false backend=f check "documentation alone" pull_request docs=true backend=false vscode=false -- docs/x.md README.md check "the backend reaches every plugin" pull_request backend=true vscode=true clion=true nvim=true -- src/main.cpp check "spec/ is the backend's" pull_request backend=true vscode=true -- spec/test-frameworks.json +check "the issue and pull-request forms are documentation" pull_request docs=true backend=false full=false -- .github/ISSUE_TEMPLATE/bug_report.yml .github/pull_request_template.md +check "a skill is documentation" pull_request docs=true backend=false full=false -- .agents/skills/mcpp-ide-development/SKILL.md AGENTS.md check "a workflow reaches everything" pull_request full=true backend=true -- .github/workflows/ci.yml check "a path of no component reaches everything" pull_request full=true -- newdir/x check "a push reaches everything" push full=true backend=true -- docs/x.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8561ce6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,100 @@ +# AGENTS.md + +mcpp-ide is the IDE layer of [mcpp](https://github.com/mcpp-community/mcpp): one backend (`mcpp-ide serve`, +C++23 modules) and the editor plugins that host it (`mide-plugins/`: VS Code, CLion, Neovim). This file +gives the rules in their shortest form and links to the full statement, which holds where they differ. + +## 1. Where a fact lives + +| Path | States | +|---|---| +| [docs/architecture.md](docs/architecture.md) | the layers, the adapters, a request end to end, distribution | +| [docs/versions.md](docs/versions.md) | series and tags, the project's mcpp and what each of its features adds | +| [protocol/](protocol) | the backend's protocol, the part of mcpp's contract it reads, mcpp's real output (`fixtures/`) | +| [spec/](spec) | settings, commands, strings: the source of every editor's declarations | +| [.agents/docs/](.agents/docs) | design records, `YYYY-MM-DD-.md`, each opening with its status | +| [.agents/skills/](.agents/skills) | procedures: [contributing](.agents/skills/mcpp-ide-contributing/SKILL.md) (issues, pull requests, agents), [development](.agents/skills/mcpp-ide-development/SKILL.md) (environment, tests, release) | +| [agents/](agents/README.md) | for agents that *use* mcpp-ide: the [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) | +| `mide-plugins//README.md` | one plugin: installing it, its settings, what it maps onto | +| [CHANGELOG.md](CHANGELOG.md) | by series; release.yml publishes it as the release notes | + +## 2. Who owns what + +| Party | Owns | Never | +|---|---|---| +| mcpp | the machine contract: events, result records, launches, JSON queries, `features` | an IDE concept | +| backend (`src/`) | every decision: projects, jobs and lanes, view models, cleanup plans, settings, the command table, strings, the rules of mcpp.toml and build.mcpp | a manifest's meaning, resolving dependencies | +| plugins (`mide-plugins/`) | the protocol mapped onto the editor's native UI, the backend process, workspace trust | any decision | +| mcppls | every language feature of C++ files | | + +- **One answer everywhere.** What two editors would both decide is the backend's. A decision made + in a plugin is a defect, even a correct one. +- **Only mcpp's contract.** A fact mcpp does not state is requested from mcpp (an issue there). It is + never derived by parsing mcpp's files or its human-readable output. +- **Capabilities, not versions.** A feature is enabled by what the project's mcpp (or mcppls) states. + An older release is described by a table frozen at that release. Versions are never compared. +- **Native in each editor.** A plugin uses its editor's own components. VS Code's pages stay + byte-identical to mcpp-vscode 0.9.0 (`test/parity`). +- **Doing less is never silent.** A missing capability is reported with the party responsible and + the remedy (`capabilities/explain`, `self-check`). + +## 3. Before a change: triage + +1. **Whose problem is it?** Reproduce it without the editor: `mcpp-ide self-check --json`, the + protocol over `mcpp-ide serve`, the mock mcpp. Wrong output from mcpp goes to mcpp, a C++ language + feature to mcppls, an editor API to that editor's upstream. Report it there with the reproduction. +2. **Backend or plugin?** If another editor would need the same change, it belongs to the backend. + A plugin changes only for how an answer is shown or for its host's API. +3. **Fix or workaround?** Fix the cause in the party that owns it. A problem that is not this + project's gets no workaround by default. A workaround that must ship anyway (a blocked release, + an upstream fix that will not arrive in time) states in the code and in the pull request: the + cause, the upstream issue, why it cannot wait, and when it will be removed; it stays narrow. + +## 4. Versions ([release-plan.sh](.github/scripts/release-plan.sh)) + +- A version is `X.Y.Z`. The series `X.Y` is shared by the backend and every plugin; `Z` is one + plugin's own patch. The backend is always `X.Y.0`: every package carries it, so a change to any + backend path ([components.tsv](.github/components.tsv)) begins a new series. +- Six statements: `mcpp.toml`, `src/server.cppm` (`kVersion`, `kSeries`), `vscode/package.json`, + `clion/gradle.properties` (`pluginVersion`), `nvim/lua/mcpp/session.lua` (`M.version`). A series + changes all of them in one commit, a patch only its plugin's; CI checks that they agree. +- Tags: `vX.Y.0` releases every component. `vscode-vX.Y.Z`, `clion-vX.Y.Z` and `nvim-vX.Y.Z` release + one plugin's patch, and are refused if the backend changed after `vX.Y.0`. +- Pins name only released versions: [versions.env](.github/versions.env) (CI), `.xlings.json`, `mcpp = ">=..."`. + +## 5. Build and test + +```bash +mcpp build && mcpp test # backend (mtest: unit, e2e, cts, bench) +mcpp run mcpp-ide-dev -- check-sources && mcpp run mcpp-ide-dev -- check-i18n +(cd mide-plugins/vscode && npm ci && npm test) # extension, parity gates included +(cd mide-plugins/clion && gradle buildPlugin verifyPlugin) # CLion plugin +nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim plugin +``` + +- Edit `spec/`, never what is generated from it. `mcpp-ide-dev gen vscode` rewrites the extension's + manifest, bundles and registry, and CI expects no diff afterwards. +- A change in what mcpp reports begins with `mcpp-ide-dev capture` and the diff in `protocol/fixtures`, + which the mock mcpp replays; CI runs the components a change reaches (`components.tsv`). + +## 6. Code + +- Backend: C++23 modules and `import std;`, with no header, no `#include` and no `#if`. The system is + reached only through `mcpplibs.os` (`os::host()`, never `os::is_`, which an ok image answers + false). `check-sources` enforces all of this. +- CLion: public IntelliJ API only (the verifier reports internal use). VS Code: the oldest + `engines.vscode` (`VSCODE_VERSION`). Neovim: 0.10 and later, over `vim.lsp`. +- User-facing strings belong to the backend (`spec/i18n`), and English and Chinese change together. +- Follow the neighbouring code and change only what the task needs. A comment says why, not what. + +## 7. Change workflow + +- Follow the [contributing skill](.agents/skills/mcpp-ide-contributing/SKILL.md): an issue from a + template, a branch `/` from `main`, a pull request, passing `ci`, review, a squash + merge. Nothing is pushed directly to `main`; an agent asks before any outward action. +- Commits and pull requests are English and declarative, `(): ` or + `X.Y.Z: `, with no attribution trailer. Documentation follows mcpp's + [docs style](https://github.com/mcpp-community/mcpp/blob/main/.agents/skills/mcpp-docs-style/SKILL.md), + and README.md and README.zh-CN.md stay in step. +- One pull request does one thing. A change in behaviour updates the protocol schema, the affected + docs and CHANGELOG.md in the same pull request; a decision worth keeping goes to `.agents/docs/`. diff --git a/README.md b/README.md index 1fe0ef8..776b280 100644 --- a/README.md +++ b/README.md @@ -1,153 +1,103 @@ -# mcpp-ide - the IDE layer of mcpp +
-> One backend for every editor of [mcpp](https://github.com/mcpp-community/mcpp) projects: VS Code -> (mcpp-vscode), CLion (mcpp-clion) and Neovim (mcpp-nvim) build, run, test, debug and pack alike +# mcpp-ide + +**One backend for every editor of [mcpp](https://github.com/mcpp-community/mcpp) projects** + +VS Code · CLion · Neovim build, run, test, debug and pack alike + +[![Release](https://img.shields.io/github/v/release/mcpp-community/mcpp-ide)](https://github.com/mcpp-community/mcpp-ide/releases) +[![CI](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml) +[![VS Code](https://img.shields.io/badge/VS_Code-mcpp--vscode-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) +[![Open VSX](https://img.shields.io/open-vsx/v/mcpp-community/mcpp-vscode?label=Open%20VSX)](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) +[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/io.github.mcpp-community.mcpp-clion) +[![C++23](https://img.shields.io/badge/C%2B%2B-23_modules-blue.svg)](https://en.cppreference.com/w/cpp/23) +[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) **English** | [简体中文](README.zh-CN.md) -[Documentation](docs/README.md) · [Protocol](protocol/protocol.schema.json) · [Settings](spec/settings.json) · -[For agents](agents/README.md) · [Releases](https://github.com/mcpp-community/mcpp-ide/releases) +[Documentation](docs/README.md) · [Architecture](docs/architecture.md) · [Protocol](protocol/protocol.schema.json) · +[For agents](agents/README.md) · [Contributing](AGENTS.md) · [Releases](https://github.com/mcpp-community/mcpp-ide/releases) -An editor integration of a build tool decides a great deal: which command a build runs, what a -test result means, how dangerous a cleanup is, which target a project builds for. Written once per -editor, those decisions drift apart, and a person who moves from one editor to another meets a -different tool. +
-mcpp-ide makes them once. Its backend, `mcpp-ide serve`, is a C++ program that reads only mcpp's -machine contract (event streams, result records, launch descriptors, JSON queries) and answers the -editors as an LSP server (JSON-RPC, protocol 2). The VS Code extension's views and pages are -mcpp-vscode 0.9.0's; the CLion plugin shows the same information in CLion's own trees, lists and -settings form (a graph in JCEF), and the Neovim plugin maps the answers onto buffers, floating -windows and the quickfix list. The editor plugins are `mide-plugins/` of this repository. Language -features of C++ files come from [mcppls](https://github.com/Sunrisepeak/mcpp-language-server); -those of mcpp.toml and build.mcpp come from the backend ([docs/rules.md](docs/rules.md)). +An editor integration of a build tool makes many decisions: which command a build runs, what a test +result means, how dangerous a cleanup is. If each editor makes them separately, the editors drift +apart. mcpp-ide makes them once. Its backend, `mcpp-ide serve`, reads only mcpp's machine contract +and answers every editor as an LSP server. Each plugin then shows those answers in its editor's own UI. -## Features +``` +mcpp ──contract──▶ mcpp-ide serve ──LSP / JSON-RPC──▶ mcpp-vscode · mcpp-clion · mcpp-nvim · agents + (every decision) (native UI, no decisions) +mcppls ──────────────────────────────────────────────▶ C++ language features in every editor +``` -| | VS Code (mcpp-vscode) | CLion (mcpp-clion) | Neovim (mcpp-nvim) | +## Highlights + +- **One answer everywhere**: what a build runs, how a test is reported and what a cleanup costs are decided by the backend +- **Only mcpp's contract**: no manifest parsing and no dependency resolution of its own +- **Tests as mcpp states them**: programs, cases, live results, diffs, metrics and Test Insights +- **Jobs in order**: one build at a time per project, a newer build replaces a waiting one, and cancelling ends cleanly +- **Safe cleanups**: each plan has a danger level, a preview and the confirmation that level requires + +## Editors + +| | VS Code | CLion | Neovim | |---|---|---|---| -| Build, run, test | Tasks in a pseudoterminal showing mcpp's output | "mcpp" run configurations, PTY console, ▶ beside `main` | `:Mcpp build`, `test`: jobs streamed into a buffer; `:Mcpp run` in a terminal buffer | -| Test tree, re-run one test | Testing view: program, file, case; `@kind:bench` and a case's tags filter it | IDE test runner: a suite per program and per file | `:Mcpp test `: `mcpp://tests`, signs, the quickfix list | -| Test results | Live per case; a failure with both sides opens VS Code's diff; a case's line ends with its duration and metrics | Live per case; a comparison failure opens the IDE's diff; metrics in the case's output | Live per case; both sides in the buffer and the quickfix list; duration and metrics as virtual text | -| Test insights (the runs mcpp keeps) | "mcpp: Show Test Insights", a webview | The mcpp tool window's Test Insights tab (JCEF) | `:Mcpp test.insights`, a floating window | -| Debug | CodeLLDB, C/C++ (gdb, lldb), lldb-dap | CLion's GDB or LLDB | nvim-dap (codelldb, lldb-dap, cppdbg, gdb) | -| Diagnostics | Problems, from mcpp's located diagnostics | Console links to the reported location | `vim.diagnostic`, `:Mcpp problems` in the quickfix list | -| mcpp.toml, build.mcpp | Completion, hover, jumps and the rules' diagnostics from the backend (language client); Problems from mcpp | The same, through CLion's completion, documentation, annotations and go-to | The same, through `vim.lsp`; mcpp's problems in `vim.diagnostic` | -| Libraries, a package's page, graphs, cache, settings | mcpp-vscode's views and pages | Native trees and lists, a settings form from the registry, the graphs in JCEF | Text in floating windows, `vim.ui.select`; settings in `setup()` | -| Targets (target sets among them), pack | Quick picks | Popups | `vim.ui.select` | -| Language features | mcppls (installed with the extension) | mcppls CLion plugin (a dependency) | mcppls-nvim (`xlings install mcppls-nvim`) | - -CLion's **Settings | Tools | mcpp** validates finite numbers and their allowed ranges before -saving the form. Invalid input displays an error and leaves every stored value unchanged. -Entering a setting's default removes its stored override. - -Graph queries report build-database errors instead of showing an empty graph. After correcting -the reported problem, reopen the graph to retry. - -**Tests.** The editors show tests as `mcpp test` states them ([docs/architecture.md](docs/architecture.md), -"A test run, end to end"). A program of several files (`[test] programs = "directory"`) has its files as -children, each the part of the program a run gives a process. A case of the mtest test protocol carries its -kind, tags and the bounds on its metrics. Test Insights reads the runs mcpp keeps in `target/mtest`: the last -run, its failures and since when, each metric against its bound, the slowest and the flaky cases, and the -schedule with its critical path. What an editor shows follows the project's mcpp: - -| The project's mcpp | Adds | +| Build, run, test | tasks, Testing view | run configurations, test runner, ▶ beside `main` | `:Mcpp`, buffers, quickfix | +| Debug | CodeLLDB, C/C++, lldb-dap | CLion's GDB / LLDB | nvim-dap | +| mcpp.toml, build.mcpp | completion, hover, jumps, diagnostics | the same | the same, over `vim.lsp` | +| Libraries, graphs, cache, settings | views and pages | native trees, forms, JCEF graphs | floating windows, `vim.ui.select` | +| C++ language features | mcppls (extension pack) | mcppls CLion plugin | mcppls-nvim | +| Details | [mcpp-vscode](mide-plugins/vscode/README.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | + +## Install + +| Editor | Install | |---|---| -| any | programs and their results | -| 2026.11.8.1 (`test-protocol`) | cases, their places and results, both sides of a failure | -| 2026.11.9.1 | the files of a program of several files; Test Insights over the kept runs | -| `test-parts`, `test-case-stream`, `test-metrics` ([mcpp#917](https://github.com/mcpp-community/mcpp/issues/917)) | the parts as mcpp states them, results as each case ends, metrics and their trends | +| VS Code 1.91+ | Marketplace or Open VSX: `mcpp-community.mcpp-vscode`, or `code --install-extension mcpp-vscode-.vsix` | +| CLion 2026.1+ | JetBrains Marketplace: `mcpp-clion`, which depends on the mcppls CLion plugin; or install the ZIP from disk | +| Neovim 0.10+ | `xlings install mcpp-ide-nvim` (with the backend; it sets itself up at start) and `xlings install mcppls-nvim` | +| Agents, other clients | `xlings install mcpp-ide`, then `mcpp-ide serve`; or `okrun mcpp-ide-.okb serve` | -A view that needs a feature the project's mcpp does not state is left out. The self-check -(`capabilities/explain`) says which mcpp states it. +The VS Code and CLion packages carry the backend for Linux x64/arm64, macOS arm64 and Windows x64 +([distribution](docs/architecture.md#distribution)). Run `mcpp-ide self-check` in a project to verify an +install. Versions and compatibility with mcpp are described in [docs/versions.md](docs/versions.md). -- **One answer everywhere** -- what a build runs, how a test is reported, what a cleanup costs: the backend's -- **Only mcpp's contract** -- no manifest parsing, no dependency resolution of its own -- **Jobs in order** -- one at a time per project, a newer build replaces a waiting one, cancelling ends cleanly -- **Platforms visible** -- each target with the platform that configures it and where every value came from -- **Safe cleanups** -- a plan with a danger level, a preview and the confirmation that level requires +## With an agent -## Install +A good prompt names **the repository**, **the document to read first**, **the task** and **the check +that ends it**. The documents below are written for agents, so the prompt can stay short. -### From an agent +| Goal | Prompt | +|---|---| +| Install | `Read agents/README.md of https://github.com/mcpp-community/mcpp-ide, install mcpp-ide for my editor from the latest release, and verify it with mcpp-ide self-check on my project.` | +| Understand | `Read AGENTS.md and docs/architecture.md of mcpp-ide, then explain how a build travels from my editor through the backend to mcpp, and which layer owns .` | +| Contribute | `Read AGENTS.md and .agents/skills/mcpp-ide-contributing of mcpp-ide. Triage : core or plugin, fix or workaround. Then propose the change and the tests that prove it, and wait for my go-ahead before opening a pull request.` | -``` -Read agents/README.md of https://github.com/mcpp-community/mcpp-ide, then install mcpp-ide for -the editor I use (VS Code, CLion or Neovim) from its latest release, and check it with -`mcpp-ide self-check` on my mcpp project. -``` +- Using mcpp-ide from an agent: [agents/README.md](agents/README.md) and the [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) +- Working on mcpp-ide: [AGENTS.md](AGENTS.md), the [contributing](.agents/skills/mcpp-ide-contributing/SKILL.md) and [development](.agents/skills/mcpp-ide-development/SKILL.md) skills -### From a release - -| Editor | Asset | Install | -|---|---|---| -| VS Code | the Marketplace (`mcpp-community.mcpp-vscode`), or `mcpp-vscode-.vsix` | search *mcpp*, or `code --install-extension mcpp-vscode-.vsix` | -| VS Code-compatible editors | Open VSX, or the `.vsix` | install the `.vsix` from the extensions view | -| CLion 2026.1+ | JetBrains Marketplace (`mcpp-clion`), or `mcpp-clion-.zip` | Settings → Plugins → Install Plugin from Disk; the mcppls CLion plugin (its package for this system carries the server) first | -| Neovim 0.10+ | `mide-plugins/nvim` of the release's source tree | `xlings install mcpp-ide-nvim` (the backend with it, set up at start); or the directory on the runtimepath and `require('mcpp').setup()` ([its README](mide-plugins/nvim/README.md)) | -| Agents, other clients | `mcpp-ide--openkal-bundle-all.tar.gz` (both images; okrun for Linux x64/arm64, macOS arm64, Windows x64), `mcpp-ide-.okb` with okrun, or `xlings install mcpp-ide` | run `bin/mcpp-ide serve` (`bin\mcpp-ide.exe` on Windows), or `okrun mcpp-ide-.okb serve` | - -Each editor package serves every system: it carries the backend as one ok-image bundle -(`backend/mcpp-ide.okb`, the x86_64 and aarch64 images on openkal-platform 0.24) and okrun for -Linux x64/arm64, macOS arm64 and Windows x64. The Neovim plugin carries none: it starts the -`mcpp-ide` command xlings installs (okrun on the same bundle). -VS Code and CLion check for the local build tool only when a user starts an action that needs it. - -**Versions.** A version is `X.Y.Z`. `X.Y`, the series, is shared by the backend and every plugin: a -plugin works with any backend of its series and refuses another, naming both versions and the -install that matches. The VS Code and CLion packages carry the backend, so a change of the backend is a -change of every package: it begins a series, every component at `X.Y.0`, tagged `vX.Y.0`, and the backend -is always its series' `X.Y.0`. `Z` is an editor plugin's own patch, tagged `vscode-`, `clion-` or -`nvim-vX.Y.Z`, which publishes that plugin alone over its series' backend: VS Code 1.3.2 and CLion 1.3.1 -both carry backend 1.3.0. A plugin's patch is refused when a path of the backend has changed since its -series' tag. A pull request runs the jobs of -the components it changes ([`.github/components.tsv`](.github/components.tsv)): a change of the backend runs -everything, a change of one plugin runs that plugin's jobs over the backend main built from the same inputs, -a change of the documentation its checks; `.github/` and any path the table does not name run everything. -The one required check is `ci`. -If `mcpp` is absent, they show one notification linking to the -[mcpp repository](https://github.com/mcpp-community/mcpp). - -### From source +## Development ```bash -mcpp build # the backend, the mock mcpp, mcpp-ide-dev -mcpp test # the backend's tests (mtest: tests/unit, e2e, cts, bench) -cd mide-plugins/vscode && npm ci && npm test # the extension's tests, the parity gates against 0.9.0 among them -npm run test:webui # the graph and tests pages in Chromium, over the backend -npm run package # dist/mcpp-vscode-.vsix -cd ../clion && gradle buildPlugin verifyPlugin # build/distributions/mcpp-clion-.zip -cd ../.. && nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # the Neovim plugin's tests +mcpp build && mcpp test # the backend, its mocks and mcpp-ide-dev +(cd mide-plugins/vscode && npm ci && npm test) # VS Code, the parity gates included +(cd mide-plugins/clion && gradle buildPlugin verifyPlugin) # CLion (xlings install gradle) +nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim ``` -`xlings install gradle` brings Gradle and its JDK. - -## Documentation - -- [docs/architecture.md](docs/architecture.md) -- the three layers and their boundaries -- [protocol/protocol.schema.json](protocol/protocol.schema.json) -- the backend's methods and notifications -- [protocol/mcpp-contract.schema.json](protocol/mcpp-contract.schema.json) -- the part of mcpp's contract it reads -- [spec/](spec) -- settings, commands, translations: the source of the editors' declarations and command tables -- [mide-plugins/vscode/README.md](mide-plugins/vscode/README.md), - [mide-plugins/clion/README.md](mide-plugins/clion/README.md), - [mide-plugins/nvim/README.md](mide-plugins/nvim/README.md) +The environment, the tests for each component, common changes and the release procedure are in the +[development skill](.agents/skills/mcpp-ide-development/SKILL.md). ## Contributing -The backend is C++23 with modules, built by mcpp; the repository's tools are a program of it -(`mcpp-ide-dev`: fixture capture, the editors' declarations, the translation check). Generated -files are not committed. A change to what mcpp reports starts with `mcpp-ide-dev capture` and the -diff in `protocol/fixtures`. - -A release runs the repository CI, publishes the checked archives of what its -tag names (`.github/scripts/release-plan.sh`) and `SHA256SUMS` on GitHub, then -independently submits the same VSIX to Open VSX and the same CLion ZIP to -JetBrains Marketplace when the release carries them. The JetBrains job checks the -archive digest, plugin XML ID and version before upload and retains a receipt; -Marketplace availability follows JetBrains review. `OPENVSX_TOKEN` and -`JETBRAINS_TOKEN` are repository secrets. The Visual Studio Marketplace upload -remains manual. +Every change starts with an issue ([templates](https://github.com/mcpp-community/mcpp-ide/issues/new/choose)) +and goes through a pull request. The rules are in [AGENTS.md](AGENTS.md): who owns what, how to +triage (core or plugin, fix or workaround), versions and code. The procedure for people and agents +is in the [contributing skill](.agents/skills/mcpp-ide-contributing/SKILL.md). Questions go to the +[forum](https://forum.d2learn.org/category/20). ## License -Apache-2.0 +[Apache-2.0](LICENSE) diff --git a/README.zh-CN.md b/README.zh-CN.md index cfbd485..0c0850e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,126 +1,100 @@ -# mcpp-ide - mcpp 的 IDE 层 +
-> 所有编辑器共用一个后端来对待 [mcpp](https://github.com/mcpp-community/mcpp) 工程:VS Code(mcpp-vscode)、 -> CLion(mcpp-clion)与 Neovim(mcpp-nvim)的构建、运行、测试、调试、打包行为一致 +# mcpp-ide + +**所有编辑器共用一个后端来对待 [mcpp](https://github.com/mcpp-community/mcpp) 工程** + +VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为一致 + +[![Release](https://img.shields.io/github/v/release/mcpp-community/mcpp-ide)](https://github.com/mcpp-community/mcpp-ide/releases) +[![CI](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml) +[![VS Code](https://img.shields.io/badge/VS_Code-mcpp--vscode-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) +[![Open VSX](https://img.shields.io/open-vsx/v/mcpp-community/mcpp-vscode?label=Open%20VSX)](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) +[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/io.github.mcpp-community.mcpp-clion) +[![C++23](https://img.shields.io/badge/C%2B%2B-23_modules-blue.svg)](https://en.cppreference.com/w/cpp/23) +[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) [English](README.md) | **简体中文** -[文档](docs/README.md) · [协议](protocol/protocol.schema.json) · [设置](spec/settings.json) · -[面向 Agent](agents/README.md) · [发布](https://github.com/mcpp-community/mcpp-ide/releases) +[文档](docs/README.md) · [架构](docs/architecture.md) · [协议](protocol/protocol.schema.json) · +[面向 Agent](agents/README.md) · [贡献](AGENTS.md) · [发布](https://github.com/mcpp-community/mcpp-ide/releases) -构建工具的编辑器集成要做许多决定:构建运行哪条命令、测试结果是什么含义、一次清理有多危险、工程为哪个目标构建。 -每个编辑器各写一遍,这些决定就会分歧;从一个编辑器换到另一个,用户遇到的就是另一个工具。 +
-mcpp-ide 只做一次。它的后端 `mcpp-ide serve` 是一个 C++ 程序,只读取 mcpp 的机器契约(事件流、结果记录、启动描述、 -JSON 查询),以 LSP 服务器(JSON-RPC,协议 2)回答编辑器。VS Code 扩展的视图与页面即 mcpp-vscode 0.9.0 的视图与页面; -CLion 插件以 CLion 自己的树、列表与设置表单显示同样的信息(图在 JCEF 中);Neovim 插件把这些回答映射到缓冲区、浮动窗口与 -quickfix 列表。各编辑器插件位于本仓库的 `mide-plugins/`。C++ 文件的语言功能来自 -[mcppls](https://github.com/Sunrisepeak/mcpp-language-server);mcpp.toml 与 build.mcpp 的语言功能来自后端 -([docs/rules.md](docs/rules.md))。 +构建工具的编辑器集成要做许多决定:构建运行哪条命令、测试结果是什么含义、一次清理有多危险。每个编辑器各写一遍, +这些决定就会分歧。mcpp-ide 只做一次:后端 `mcpp-ide serve` 只读取 mcpp 的机器契约,以 LSP 服务器回答所有编辑器, +各插件再用编辑器自己的界面呈现这些回答。 -## 功能 +``` +mcpp ──契约──▶ mcpp-ide serve ──LSP / JSON-RPC──▶ mcpp-vscode · mcpp-clion · mcpp-nvim · agents + (所有决定) (原生界面,不做决定) +mcppls ───────────────────────────────────────────▶ 各编辑器中 C++ 文件的语言功能 +``` -| | VS Code(mcpp-vscode) | CLion(mcpp-clion) | Neovim(mcpp-nvim) | +## 特性 + +- **处处同一答案**:构建运行什么、测试如何报告、清理的代价,都由后端决定 +- **只读 mcpp 的契约**:不自行解析清单,不自行解析依赖 +- **测试即 mcpp 所述**:程序、用例、实时结果、差异对比、指标与 Test Insights +- **任务有序**:每个工程同一时间一个构建,新构建替换等待中的构建,取消会正常结束 +- **安全清理**:每个计划都带危险等级与预览,并按该等级要求确认 + +## 编辑器 + +| | VS Code | CLion | Neovim | |---|---|---|---| -| 构建、运行、测试 | 伪终端中的任务,显示 mcpp 自身的输出 | "mcpp" 运行配置、PTY 控制台、`main` 旁的 ▶ | `:Mcpp build`、`test`:任务输出流入缓冲区;`:Mcpp run` 在终端缓冲区中运行 | -| 测试树、单个测试重跑 | 测试视图:程序、文件、用例;`@kind:bench` 与用例的标签可筛选 | IDE 测试运行器:每个程序、每个文件一个套件 | `:Mcpp test `:`mcpp://tests`、标记、quickfix 列表 | -| 测试结果 | 逐用例实时显示;陈述两侧的失败可打开 VS Code 的差异视图;用例所在行末显示耗时与指标 | 逐用例实时显示;比较型失败可打开 IDE 的差异视图;指标在用例输出中 | 逐用例实时显示;两侧写入缓冲区与 quickfix 列表;耗时与指标以虚拟文本显示 | -| 测试洞察(mcpp 保留的运行) | "mcpp: Show Test Insights",一个 webview | mcpp 工具窗口的 Test Insights 页(JCEF) | `:Mcpp test.insights`,浮动窗口 | -| 调试 | CodeLLDB、C/C++(gdb、lldb)、lldb-dap | CLion 的 GDB 或 LLDB | nvim-dap(codelldb、lldb-dap、cppdbg、gdb) | -| 诊断 | 问题面板,来自 mcpp 带位置的诊断 | 控制台链接到报告的位置 | `vim.diagnostic`,`:Mcpp problems` 填入 quickfix 列表 | -| mcpp.toml、build.mcpp | 补全、悬停、跳转与规则诊断来自后端(语言客户端);问题来自 mcpp | 同上,经 CLion 的补全、文档、标注与跳转 | 同上,经 `vim.lsp`;mcpp 的问题在 `vim.diagnostic` | -| 库、包页面、依赖图、缓存、设置 | mcpp-vscode 的视图与页面 | 原生的树与列表、由设置注册表生成的设置表单、JCEF 中的图 | 浮动窗口中的文本、`vim.ui.select`;设置在 `setup()` 中 | -| 目标(含目标集合)、打包 | 快速选择 | 弹出列表 | `vim.ui.select` | -| 语言功能 | mcppls(随扩展一并安装) | mcppls CLion 插件(依赖) | mcppls-nvim(`xlings install mcppls-nvim`) | - -CLion 的 **Settings | Tools | mcpp** 在保存表单前检查数值是否有限、是否处于允许范围内。 -无效输入会显示错误,并保持所有已存储的值不变。输入某项设置的默认值会移除其存储覆盖。 - -图查询失败时显示构建数据库错误。修正所报告的问题后,重新打开图即可重试。 - -**测试。** 编辑器按 `mcpp test` 的陈述显示测试([docs/architecture.md](docs/architecture.md), -"A test run, end to end")。多文件程序(`[test] programs = "directory"`)以其文件为子项,每个文件是一次运行中 -单独成进程的那一部分。mtest 测试协议的用例带有其类别、标签与指标上下限。测试洞察读取 mcpp 保存在 -`target/mtest` 的运行:最近一次运行、其失败及起始时间、各指标与上下限、最慢与不稳定的用例、调度与关键路径。 -编辑器所显示的内容取决于工程的 mcpp: - -| 工程的 mcpp | 增加 | +| 构建、运行、测试 | 任务、测试视图 | 运行配置、测试运行器、`main` 旁的 ▶ | `:Mcpp`、缓冲区、quickfix | +| 调试 | CodeLLDB、C/C++、lldb-dap | CLion 的 GDB / LLDB | nvim-dap | +| mcpp.toml、build.mcpp | 补全、悬停、跳转、诊断 | 同上 | 同上,经 `vim.lsp` | +| 库、依赖图、缓存、设置 | 视图与页面 | 原生树、表单、JCEF 中的图 | 浮动窗口、`vim.ui.select` | +| C++ 语言功能 | mcppls(扩展包) | mcppls CLion 插件 | mcppls-nvim | +| 详情 | [mcpp-vscode](mide-plugins/vscode/README.zh-CN.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | + +## 安装 + +| 编辑器 | 安装 | |---|---| -| 任意版本 | 程序及其结果 | -| 2026.11.8.1(`test-protocol`) | 用例、其位置与结果、失败的两侧 | -| 2026.11.9.1 | 多文件程序的文件;基于已保留运行的测试洞察 | -| `test-parts`、`test-case-stream`、`test-metrics`([mcpp#917](https://github.com/mcpp-community/mcpp/issues/917)) | 由 mcpp 陈述的部分、逐用例结束时的结果、指标及其趋势 | +| VS Code 1.91+ | Marketplace 或 Open VSX:`mcpp-community.mcpp-vscode`,或 `code --install-extension mcpp-vscode-.vsix` | +| CLion 2026.1+ | JetBrains Marketplace:`mcpp-clion`,依赖 mcppls CLion 插件;或从磁盘安装 ZIP | +| Neovim 0.10+ | `xlings install mcpp-ide-nvim`(连同后端,启动时自动 setup)与 `xlings install mcppls-nvim` | +| Agent、其他客户端 | `xlings install mcpp-ide`,然后运行 `mcpp-ide serve`;或 `okrun mcpp-ide-.okb serve` | -工程的 mcpp 未声明某视图所需的能力时,该视图不显示;自检(`capabilities/explain`)说明哪个版本的 mcpp 声明了它。 +VS Code 与 CLion 的包自带后端,覆盖 Linux x64/arm64、macOS arm64 与 Windows x64 +([分发方式](docs/architecture.md#distribution))。在工程中运行 `mcpp-ide self-check` 即可验证安装。 +版本与 mcpp 的兼容性见 [docs/versions.md](docs/versions.md)。 -- **处处同一答案**——构建运行什么、测试如何报告、清理的代价:都由后端决定 -- **只读 mcpp 的契约**——不自行解析清单,不自行解析依赖 -- **任务有序**——每个工程同一时间一个任务,新构建替换等待中的构建,取消会正常结束 -- **平台可见**——每个目标连同配置它的平台,以及每个值的来源 -- **安全清理**——带危险等级与预览的计划,按该等级要求确认 +## 使用 Agent -## 安装 +一条好的提示词写清四件事:**仓库**、**先读哪份文档**、**要做的任务**,以及**以什么检查作为结束**。 +下面这些文档都是为 Agent 写的,所以提示词本身可以很短。 -### 让 Agent 安装 +| 目的 | 提示词 | +|---|---| +| 安装 | `阅读 https://github.com/mcpp-community/mcpp-ide 的 agents/README.md,为我的编辑器从最新发布安装 mcpp-ide,并在我的工程上用 mcpp-ide self-check 验证。` | +| 了解项目 | `阅读 mcpp-ide 的 AGENTS.md 与 docs/architecture.md,说明一次构建如何从编辑器经后端到达 mcpp,以及 <功能> 属于哪一层。` | +| 参与贡献 | `阅读 mcpp-ide 的 AGENTS.md 与 .agents/skills/mcpp-ide-contributing,对 做分诊(core 还是插件,修复还是 workaround),提出改动方案及能证明它的测试;开 PR 前先等我确认。` | -``` -阅读 https://github.com/mcpp-community/mcpp-ide 的 agents/README.md,为我使用的编辑器(VS Code、CLion 或 Neovim) -从最新发布安装 mcpp-ide,并在我的 mcpp 工程上用 `mcpp-ide self-check` 检查。 -``` +- 从 Agent 使用 mcpp-ide:[agents/README.md](agents/README.md) 与 [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) +- 开发 mcpp-ide:[AGENTS.md](AGENTS.md),以及[贡献](.agents/skills/mcpp-ide-contributing/SKILL.md)与[开发](.agents/skills/mcpp-ide-development/SKILL.md) skill -### 从 release 安装 - -| 编辑器 | 资产 | 安装 | -|---|---|---| -| VS Code | Marketplace(`mcpp-community.mcpp-vscode`),或 `mcpp-vscode-.vsix` | 搜索 *mcpp*,或 `code --install-extension mcpp-vscode-.vsix` | -| 兼容 VS Code 的编辑器 | Open VSX,或 `.vsix` | 在扩展视图中安装 `.vsix` | -| CLion 2026.1+ | JetBrains Marketplace(`mcpp-clion`),或 `mcpp-clion-.zip` | Settings → Plugins → Install Plugin from Disk;先安装 mcppls CLion 插件(本系统的包自带服务端) | -| Neovim 0.10+ | release 源码树中的 `mide-plugins/nvim` | `xlings install mcpp-ide-nvim` 与 `xlings install mcpp-ide`,再 `require('mcpp').setup()`;或把该目录加入 runtimepath([其 README](mide-plugins/nvim/README.md)) | -| Agent、其他客户端 | `mcpp-ide--openkal-bundle-all.tar.gz`(两个架构的映像;Linux x64/arm64、macOS arm64、Windows x64 的 okrun),携带 okrun 的 `mcpp-ide-.okb`,或 `xlings install mcpp-ide` | 运行 `bin/mcpp-ide serve`(Windows 上为 `bin\mcpp-ide.exe`),或 `okrun mcpp-ide-.okb serve` | - -每个编辑器包都服务全部系统:后端以一个 ok 映像包(`backend/mcpp-ide.okb`,openkal-platform 0.24 上的 -x86_64 与 aarch64 映像)加上 Linux x64/arm64、macOS arm64、Windows x64 的 okrun 携带。Neovim 插件不携带后端: -它启动 xlings 安装的 `mcpp-ide` 命令(由 okrun 运行同一个映像包)。 -VS Code 和 CLion 仅在用户主动执行依赖本地构建工具的操作时检查 `mcpp`;未安装时只提示一次,并提供 -[mcpp 开源仓库](https://github.com/mcpp-community/mcpp)链接。 - -**版本。** 版本为 `X.Y.Z`。`X.Y` 是系列,由后端与全部插件共享:插件与同系列的任何后端配合,遇到其他系列时拒绝, -并写出双方的版本与对应的安装方法。VS Code 与 CLion 的包内含后端,因此后端的改动即是全部包的改动:它开启一个新系列, -全部组件为 `X.Y.0`,标签为 `vX.Y.0`;后端始终是所属系列的 `X.Y.0`。`Z` 是编辑器插件自己的补丁,标签为 `vscode-`、 -`clion-` 或 `nvim-vX.Y.Z`,只发布该插件,所带的后端仍是本系列的那一份:VS Code 1.3.2 与 CLion 1.3.1 都带后端 1.3.0。 -自本系列的标签以来后端的任何路径有改动时,插件补丁被拒绝。 -拉取请求只运行它所改动的组件的作业([`.github/components.tsv`](.github/components.tsv)):后端的改动运行全部作业; -一个插件的改动只运行该插件的作业,所用的后端是 main 以相同输入构建的那一份;文档的改动只运行文档的检查;`.github/` -与表中没有列出的路径运行全部作业。唯一必需的检查是 `ci`。 - -### 从源码构建 +## 开发 ```bash -mcpp build # 后端、mock mcpp、mcpp-ide-dev -mcpp test # 后端测试(mtest:tests/unit、e2e、cts、bench) -cd mide-plugins/vscode && npm ci && npm test # 扩展的测试,含对 0.9.0 的一致性门 -npm run test:webui # 图页面与测试页面在 Chromium 中、经后端运行 -npm run package # dist/mcpp-vscode-.vsix -cd ../clion && gradle buildPlugin verifyPlugin # build/distributions/mcpp-clion-.zip -cd ../.. && nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim 插件的测试 +mcpp build && mcpp test # 后端、mock 与 mcpp-ide-dev +(cd mide-plugins/vscode && npm ci && npm test) # VS Code,含 parity 门禁 +(cd mide-plugins/clion && gradle buildPlugin verifyPlugin) # CLion(xlings install gradle) +nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua # Neovim ``` -`xlings install gradle` 会一并带来 Gradle 及其 JDK。 - -## 文档 - -- [docs/architecture.md](docs/architecture.md)——三层及其边界 -- [protocol/protocol.schema.json](protocol/protocol.schema.json)——后端的方法与通知 -- [protocol/mcpp-contract.schema.json](protocol/mcpp-contract.schema.json)——后端读取的 mcpp 契约部分 -- [spec/](spec)——设置、命令、翻译:各编辑器声明与命令表的唯一来源 -- [mide-plugins/vscode/README.md](mide-plugins/vscode/README.md)、[mide-plugins/clion/README.md](mide-plugins/clion/README.md)、 - [mide-plugins/nvim/README.md](mide-plugins/nvim/README.md) +环境、各组件的测试、常见改动与发布流程见[开发 skill](.agents/skills/mcpp-ide-development/SKILL.md)。 ## 参与贡献 -后端是用 mcpp 构建的 C++23 模块程序;仓库的工具是它的一个程序(`mcpp-ide-dev`:抓取 fixture、生成编辑器声明、 -检查翻译)。生成物不提交。mcpp 的输出有变化时,从 `mcpp-ide-dev capture` 与 `protocol/fixtures` 的差异开始。 +每个改动都从 issue 开始([模板](https://github.com/mcpp-community/mcpp-ide/issues/new/choose)),并通过 PR 合入。 +规则见 [AGENTS.md](AGENTS.md):谁负责什么、如何分诊(core 还是插件,修复还是 workaround)、版本与代码规范。 +面向人与 Agent 的完整流程见[贡献 skill](.agents/skills/mcpp-ide-contributing/SKILL.md)。问题与讨论请到 +[论坛](https://forum.d2learn.org/category/20)。 ## 许可证 -Apache-2.0 +[Apache-2.0](LICENSE) diff --git a/docs/README.md b/docs/README.md index a692e64..44099fd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,7 @@ # mcpp-ide documentation - [architecture.md](architecture.md) -- the three layers, what each holds, and how a request travels +- [versions.md](versions.md) -- series and tags, the project's mcpp and what each of its features adds - [rules.md](rules.md) -- mcpp.toml and build.mcpp: completion, hover, jumps and diagnostics over LSP - [../protocol/protocol.schema.json](../protocol/protocol.schema.json) -- the backend's protocol - [../agents/README.md](../agents/README.md) -- driving the backend from an agent diff --git a/docs/versions.md b/docs/versions.md new file mode 100644 index 0000000..2f99b90 --- /dev/null +++ b/docs/versions.md @@ -0,0 +1,42 @@ +# Versions and compatibility + +## Series + +A version is `X.Y.Z`. The series `X.Y` is shared by the backend and every plugin. A plugin works +with any backend of its series and refuses one from another series, naming both versions and the +install that matches. + +The VS Code and CLion packages carry the backend, so a change to the backend changes every package. +It therefore begins a new series: every component moves to `X.Y.0`, tagged `vX.Y.0`, and the +backend is always its series' `X.Y.0`. `Z` is an editor plugin's own patch, tagged +`vscode-vX.Y.Z`, `clion-vX.Y.Z` or `nvim-vX.Y.Z`. Such a tag publishes that plugin alone over its +series' backend; VS Code 1.3.2 and CLion 1.3.1, for example, both carry backend 1.3.0. A plugin +patch is refused when any backend path has changed since its series' tag +([release-plan.sh](../.github/scripts/release-plan.sh)). + +## The project's mcpp + +Each project is described by the mcpp that builds it: the one its `.xlings.json` pins, or +`mcpp.path`. A feature is enabled by what that mcpp states (`features`). An earlier release is +described by a table frozen at that release, never by comparing versions. A view that needs a +feature the project's mcpp does not state is left out, and the self-check (`capabilities/explain`) +names the mcpp that states it. If `mcpp` is absent, VS Code and CLion show one notification linking +to the [mcpp repository](https://github.com/mcpp-community/mcpp); they look for mcpp only when an +action needs it. + +## Tests + +The editors show tests as `mcpp test` states them ([architecture.md](architecture.md), "A test +run, end to end"). A program made of several files (`[test] programs = "directory"`) lists its +files as children, each file being the part of the program that a run gives a process. A case of +the mtest protocol carries its kind, its tags and the bounds on its metrics. Test Insights reads +the runs mcpp keeps in `target/mtest`: the last run, its failures and when they began, each metric +against its bound, the slowest and the flaky cases, and the schedule with its critical path. + +| The project's mcpp | Adds | +|---|---| +| any | programs and their results | +| 2026.11.8.1 (`test-protocol`) | cases, their places and results, both sides of a failure | +| 2026.11.9.1 | the files of a multi-file program; Test Insights over the kept runs | +| `test-parts`, `test-case-stream`, `test-metrics` ([mcpp#917](https://github.com/mcpp-community/mcpp/issues/917)) | the parts as mcpp states them, results as each case ends, metrics and their trends | +| `test-launch-records` (2026.11.10.1) | cases run through a framework's test session | From 35b1c278d58b1fa89667ca75c575ee5f161cdfc4 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sat, 21 Nov 2026 13:09:05 +0900 Subject: [PATCH 2/5] docs: diagrams in mermaid with one palette, and copyable prompts for agents - README.md and README.zh-CN.md draw the layers as a mermaid flowchart in place of the text drawing: mcpp's contract into the backend, the backend into the plugins and agents, mcppls into every editor. - agents/README.md draws a session as a sequence diagram. - docs/architecture.md gains three: a build end to end, a test run end to end (a test session or mcpp test), and the order in which a plugin finds the backend. - Every diagram shares one palette that reads on light and dark backgrounds: indigo for mcpp and the backend, teal for the editors, amber for mcppls and notes, slate for lines and labels. - The agent prompts are code blocks, each copyable, with the documents they rely on beside them. --- README.md | 56 +++++++++++++++++++++++++++++++---------- README.zh-CN.md | 55 +++++++++++++++++++++++++++++++---------- agents/README.md | 21 ++++++++++------ docs/architecture.md | 59 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 776b280..8212735 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,27 @@ result means, how dangerous a cleanup is. If each editor makes them separately, apart. mcpp-ide makes them once. Its backend, `mcpp-ide serve`, reads only mcpp's machine contract and answers every editor as an LSP server. Each plugin then shows those answers in its editor's own UI. -``` -mcpp ──contract──▶ mcpp-ide serve ──LSP / JSON-RPC──▶ mcpp-vscode · mcpp-clion · mcpp-nvim · agents - (every decision) (native UI, no decisions) -mcppls ──────────────────────────────────────────────▶ C++ language features in every editor +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#94a3b8", "edgeLabelBackground": "#f8fafc", "clusterBkg": "#f0fdfa", "clusterBorder": "#99f6e4", "titleColor": "#0f766e"}}}%% +flowchart LR + mcpp("mcpp
machine contract"):::mcpp + serve("mcpp-ide serve
every decision"):::core + mcppls("mcppls
C++ language features"):::ls + subgraph clients ["native UI · no decisions"] + direction LR + vscode("mcpp-vscode"):::ide + clion("mcpp-clion"):::ide + nvim("mcpp-nvim"):::ide + agent("agents"):::agent + end + mcpp -- "events · records · queries" --> serve + serve -- "LSP / JSON-RPC" --> clients + mcppls -. "C++ files" .-> clients + classDef mcpp fill:#e0e7ff,stroke:#818cf8,color:#312e81 + classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff + classDef ide fill:#ccfbf1,stroke:#2dd4bf,color:#134e4a + classDef agent fill:#f1f5f9,stroke:#cbd5e1,color:#334155 + classDef ls fill:#fef3c7,stroke:#fbbf24,color:#78350f ``` ## Highlights @@ -66,17 +83,30 @@ install. Versions and compatibility with mcpp are described in [docs/versions.md ## With an agent -A good prompt names **the repository**, **the document to read first**, **the task** and **the check -that ends it**. The documents below are written for agents, so the prompt can stay short. +A prompt names **the repository**, **the document to read first**, **the task** and **the check that +ends it**. The documents are written for agents, so the prompt stays short. Copy one and fill in `<...>`. -| Goal | Prompt | -|---|---| -| Install | `Read agents/README.md of https://github.com/mcpp-community/mcpp-ide, install mcpp-ide for my editor from the latest release, and verify it with mcpp-ide self-check on my project.` | -| Understand | `Read AGENTS.md and docs/architecture.md of mcpp-ide, then explain how a build travels from my editor through the backend to mcpp, and which layer owns .` | -| Contribute | `Read AGENTS.md and .agents/skills/mcpp-ide-contributing of mcpp-ide. Triage : core or plugin, fix or workaround. Then propose the change and the tests that prove it, and wait for my go-ahead before opening a pull request.` | +**Install** · [agents/README.md](agents/README.md), the [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) + +```text +Read agents/README.md of https://github.com/mcpp-community/mcpp-ide, install mcpp-ide for +from the latest release, and verify it with `mcpp-ide self-check` on my project. +``` + +**Understand** · [AGENTS.md](AGENTS.md), [docs/architecture.md](docs/architecture.md) -- Using mcpp-ide from an agent: [agents/README.md](agents/README.md) and the [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) -- Working on mcpp-ide: [AGENTS.md](AGENTS.md), the [contributing](.agents/skills/mcpp-ide-contributing/SKILL.md) and [development](.agents/skills/mcpp-ide-development/SKILL.md) skills +```text +Read AGENTS.md and docs/architecture.md of https://github.com/mcpp-community/mcpp-ide, then explain +how a build travels from the editor through the backend to mcpp, and which layer owns . +``` + +**Contribute** · the [contributing](.agents/skills/mcpp-ide-contributing/SKILL.md) and [development](.agents/skills/mcpp-ide-development/SKILL.md) skills + +```text +Read AGENTS.md and .agents/skills/mcpp-ide-contributing of https://github.com/mcpp-community/mcpp-ide. +Triage : core or plugin, fix or workaround. Propose the change and the tests that prove it, +and wait for my go-ahead before opening a pull request. +``` ## Development diff --git a/README.zh-CN.md b/README.zh-CN.md index 0c0850e..5e032de 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -25,10 +25,27 @@ VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为 这些决定就会分歧。mcpp-ide 只做一次:后端 `mcpp-ide serve` 只读取 mcpp 的机器契约,以 LSP 服务器回答所有编辑器, 各插件再用编辑器自己的界面呈现这些回答。 -``` -mcpp ──契约──▶ mcpp-ide serve ──LSP / JSON-RPC──▶ mcpp-vscode · mcpp-clion · mcpp-nvim · agents - (所有决定) (原生界面,不做决定) -mcppls ───────────────────────────────────────────▶ 各编辑器中 C++ 文件的语言功能 +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#94a3b8", "edgeLabelBackground": "#f8fafc", "clusterBkg": "#f0fdfa", "clusterBorder": "#99f6e4", "titleColor": "#0f766e"}}}%% +flowchart LR + mcpp("mcpp
机器契约"):::mcpp + serve("mcpp-ide serve
所有决定"):::core + mcppls("mcppls
C++ 语言功能"):::ls + subgraph clients ["原生界面 · 不做决定"] + direction LR + vscode("mcpp-vscode"):::ide + clion("mcpp-clion"):::ide + nvim("mcpp-nvim"):::ide + agent("agents"):::agent + end + mcpp -- "事件 · 记录 · 查询" --> serve + serve -- "LSP / JSON-RPC" --> clients + mcppls -. "C++ 文件" .-> clients + classDef mcpp fill:#e0e7ff,stroke:#818cf8,color:#312e81 + classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff + classDef ide fill:#ccfbf1,stroke:#2dd4bf,color:#134e4a + classDef agent fill:#f1f5f9,stroke:#cbd5e1,color:#334155 + classDef ls fill:#fef3c7,stroke:#fbbf24,color:#78350f ``` ## 特性 @@ -65,17 +82,29 @@ VS Code 与 CLion 的包自带后端,覆盖 Linux x64/arm64、macOS arm64 与 ## 使用 Agent -一条好的提示词写清四件事:**仓库**、**先读哪份文档**、**要做的任务**,以及**以什么检查作为结束**。 -下面这些文档都是为 Agent 写的,所以提示词本身可以很短。 +一条提示词写清四件事:**仓库**、**先读哪份文档**、**要做的任务**、**以什么检查结束**。文档本身面向 Agent 编写, +所以提示词可以很短。复制一条,填入 `<...>` 即可。 -| 目的 | 提示词 | -|---|---| -| 安装 | `阅读 https://github.com/mcpp-community/mcpp-ide 的 agents/README.md,为我的编辑器从最新发布安装 mcpp-ide,并在我的工程上用 mcpp-ide self-check 验证。` | -| 了解项目 | `阅读 mcpp-ide 的 AGENTS.md 与 docs/architecture.md,说明一次构建如何从编辑器经后端到达 mcpp,以及 <功能> 属于哪一层。` | -| 参与贡献 | `阅读 mcpp-ide 的 AGENTS.md 与 .agents/skills/mcpp-ide-contributing,对 做分诊(core 还是插件,修复还是 workaround),提出改动方案及能证明它的测试;开 PR 前先等我确认。` | +**安装** · [agents/README.md](agents/README.md)、[mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) + +```text +阅读 https://github.com/mcpp-community/mcpp-ide 的 agents/README.md,为 <我的编辑器> 从最新发布安装 +mcpp-ide,并在我的工程上用 `mcpp-ide self-check` 验证。 +``` + +**了解项目** · [AGENTS.md](AGENTS.md)、[docs/architecture.md](docs/architecture.md) -- 从 Agent 使用 mcpp-ide:[agents/README.md](agents/README.md) 与 [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) -- 开发 mcpp-ide:[AGENTS.md](AGENTS.md),以及[贡献](.agents/skills/mcpp-ide-contributing/SKILL.md)与[开发](.agents/skills/mcpp-ide-development/SKILL.md) skill +```text +阅读 https://github.com/mcpp-community/mcpp-ide 的 AGENTS.md 与 docs/architecture.md,说明一次构建如何 +从编辑器经后端到达 mcpp,以及 <功能> 属于哪一层。 +``` + +**参与贡献** · [贡献](.agents/skills/mcpp-ide-contributing/SKILL.md)与[开发](.agents/skills/mcpp-ide-development/SKILL.md) skill + +```text +阅读 https://github.com/mcpp-community/mcpp-ide 的 AGENTS.md 与 .agents/skills/mcpp-ide-contributing, +对 做分诊(core 还是插件,修复还是 workaround),提出改动方案及能证明它的测试;开 PR 前先等我确认。 +``` ## 开发 diff --git a/agents/README.md b/agents/README.md index db130ee..8911ed9 100644 --- a/agents/README.md +++ b/agents/README.md @@ -22,13 +22,20 @@ and its contract, mcppls, xlings, trust. ## A session -``` -→ initialize {"editor": "cli", "workspaceFolders": ["/path/to/project"]} -← result {"projects": [...], "mcpp": {...}, "languageService": {...}, "checks": [...]} -→ test/list {"root": "/path/to/project"} -→ job/start {"kind": "test", "root": "/path/to/project", "color": false} -← job/started, job/output, job/plan, test/result ..., test/summary, job/finished -→ shutdown, then the notification exit +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#e0e7ff", "actorBorder": "#818cf8", "actorTextColor": "#312e81", "actorLineColor": "#cbd5e1", "signalColor": "#64748b", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fef3c7", "noteBorderColor": "#fbbf24", "noteTextColor": "#78350f", "activationBkgColor": "#ccfbf1", "activationBorderColor": "#2dd4bf", "labelBoxBkgColor": "#e0e7ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#312e81", "loopTextColor": "#64748b"}}}%% +sequenceDiagram + participant A as Agent + participant B as mcpp-ide serve + A->>B: initialize {editor: "cli", workspaceFolders: [dir]} + B-->>A: projects, mcpp, languageService, checks + A->>B: test/list {root} + B-->>A: programs, their files and parts + A->>B: job/start {kind: "test", root, color: false} + B-->>A: job/started, job/output, job/plan + B-->>A: test/result ..., test/summary + B-->>A: job/finished + A->>B: shutdown, then the notification exit ``` Each message is framed as in LSP: `Content-Length: \r\n\r\n`. diff --git a/docs/architecture.md b/docs/architecture.md index c7a9e30..45ecf12 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -62,6 +62,26 @@ mcppls what a compiler answers better. ## A build, end to end +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#e0e7ff", "actorBorder": "#818cf8", "actorTextColor": "#312e81", "actorLineColor": "#cbd5e1", "signalColor": "#64748b", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fef3c7", "noteBorderColor": "#fbbf24", "noteTextColor": "#78350f", "activationBkgColor": "#ccfbf1", "activationBorderColor": "#2dd4bf", "labelBoxBkgColor": "#e0e7ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#312e81", "loopTextColor": "#64748b"}}}%% +sequenceDiagram + autonumber + participant E as Editor plugin + participant B as mcpp-ide serve + participant M as mcpp + participant L as mcppls + E->>B: job/start {kind: "build", root} + Note over B: queued on the project's lane + B->>M: mcpp build --message-format json + M-->>B: narration and events + B-->>E: job/output, job/plan, job/progress, job/diagnostic, job/artifact + M-->>B: the closing envelope + B-->>E: job/finished + Note over M: writes the result record + B-->>E: result/changed (the watcher) + Note over L: reads the same record, refreshes +``` + 1. The user runs Build. The adapter sends `mcpp-ide/job/start {kind: "build", root}`. 2. The backend queues it on the project's lane and runs `mcpp build --message-format json` with `MCPP_CLIENT`, colour for a terminal, and `MCPP_DENY_EFFECTS` in an untrusted workspace. @@ -80,6 +100,35 @@ builds and runs the programs and states their cases and results; a framework is program is written with, and the backend knows none by name. What a framework offers beyond the base, it states of itself (`mcpp test --guide`, B6). +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#e0e7ff", "actorBorder": "#818cf8", "actorTextColor": "#312e81", "actorLineColor": "#cbd5e1", "signalColor": "#64748b", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fef3c7", "noteBorderColor": "#fbbf24", "noteTextColor": "#78350f", "activationBkgColor": "#ccfbf1", "activationBorderColor": "#2dd4bf", "labelBoxBkgColor": "#e0e7ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#312e81", "loopTextColor": "#64748b"}}}%% +sequenceDiagram + autonumber + participant E as Editor plugin + participant B as mcpp-ide serve + participant M as mcpp + participant S as test session + E->>B: test/list + B->>M: mcpp test --list + B-->>E: programs, files, parts + E->>B: test/cases + B->>M: mcpp test --cases + B-->>E: the cases, kept until the project changes + alt a framework states a session and mcpp gives launches + E->>B: test/runCases + B->>S: started once per project (JSON-RPC) + S-->>B: build, cases, end + B-->>E: test/caseEvent ..., job/finished + else otherwise + E->>B: job/start {kind: "test"} + B->>M: mcpp test --message-format json + M-->>B: records + B-->>E: test/result, test/caseEvent ..., job/finished + end + E->>B: test/insights + B-->>E: the runs mcpp keeps (target/mtest) +``` + 1. `test/list` runs `mcpp test --list` and answers each program with its files, its `main` and its parts. A protocol program of several files (`[test] programs = "directory"`) runs as one process per file, `/`. mcpp states the parts with `test-parts`; before it, the backend derives them as @@ -128,6 +177,16 @@ editor package carries that bundle and the runner that starts it on each system: | `backend/mcpp-ide.okb` | the x86_64 and aarch64 images | | | `backend/okrun/-/okrun[.exe]` | okrun for `linux-x86_64`, `linux-aarch64`, `macos-aarch64`, `windows-x86_64`, from the universal self-contained package (`--mode self-contained --systems all`: each okrun built over the platform's hosted arrangement); one command packs both, `mcpp pack mcpp-ide --target openkal --mode self-contained --systems all --pkg-format tar,okb`, and the package's `runs_on.self` names the systems it runs on | `okrun mcpp-ide.okb serve`: the okrun carried for this system, else okrun on PATH | +```mermaid +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#94a3b8", "edgeLabelBackground": "#f8fafc", "clusterBkg": "#f0fdfa", "clusterBorder": "#99f6e4", "titleColor": "#0f766e"}}}%% +flowchart LR + cfg("1 · mcpp.ide.backendPath"):::core + pkg("2 · the package's .okb
run by okrun"):::core + inst("3 · mcpp-ide
from xlings or PATH"):::core + cfg -- unset --> pkg -- not carried --> inst + classDef core fill:#e0e7ff,stroke:#818cf8,color:#312e81 +``` + Before it, a configured `mcpp.ide.backendPath` (a program or an `.okb`) is used; after it, an installed `mcpp-ide` (xlings, whose command runs okrun on its bundle) or one on PATH. The Neovim plugin carries no package of the backend: it starts setup()'s `backend`, else `mcpp-ide` on PATH, From 47de690ca11ebb4a5b2ac1aee69bb40c3f4d717f Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sat, 21 Nov 2026 13:18:50 +0900 Subject: [PATCH 3/5] docs: one prompt for agents, one editors table with its marketplaces, straight diagrams - The README's agent section is one prompt: read AGENTS.md, then only what the task needs (install, understand, report an issue after triage, change the code); with no clear task, the agent says what mcpp-ide is and asks which direction, suggesting a first step for each, and it asks before any outward action. - Editors and installs are one table, linking the Visual Studio Marketplace, Open VSX and the JetBrains Marketplace (plugin 35632), and mcppls's extension and CLion plugin (35609). The JetBrains badge links the plugin's page by its numeric id; its XML id gave 404. mcppls is a dependency of the VS Code extension, not an extension pack. - The layers are one row with straight arrows: mcpp's contract into the backend, LSP both ways between the backend and the clients and between the clients and mcppls. - Every diagram shares one palette: slate for what lies outside, indigo for the backend and the clients, amber for mcppls and notes; flowcharts draw linear edges. --- README.md | 92 ++++++++++++++++---------------------------- README.zh-CN.md | 89 +++++++++++++++--------------------------- agents/README.md | 2 +- docs/architecture.md | 15 +++++--- 4 files changed, 76 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index 8212735..ee80e66 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ VS Code · CLion · Neovim build, run, test, debug and pack alike [![CI](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml) [![VS Code](https://img.shields.io/badge/VS_Code-mcpp--vscode-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) [![Open VSX](https://img.shields.io/open-vsx/v/mcpp-community/mcpp-vscode?label=Open%20VSX)](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) -[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/io.github.mcpp-community.mcpp-clion) +[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/35632-mcpp) [![C++23](https://img.shields.io/badge/C%2B%2B-23_modules-blue.svg)](https://en.cppreference.com/w/cpp/23) [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) @@ -27,26 +27,18 @@ apart. mcpp-ide makes them once. Its backend, `mcpp-ide serve`, reads only mcpp' and answers every editor as an LSP server. Each plugin then shows those answers in its editor's own UI. ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#94a3b8", "edgeLabelBackground": "#f8fafc", "clusterBkg": "#f0fdfa", "clusterBorder": "#99f6e4", "titleColor": "#0f766e"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "linear", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% flowchart LR - mcpp("mcpp
machine contract"):::mcpp + mcpp("mcpp
machine contract"):::ext serve("mcpp-ide serve
every decision"):::core + clients("VS Code · CLion
Neovim · agents

native UI, no decisions"):::ide mcppls("mcppls
C++ language features"):::ls - subgraph clients ["native UI · no decisions"] - direction LR - vscode("mcpp-vscode"):::ide - clion("mcpp-clion"):::ide - nvim("mcpp-nvim"):::ide - agent("agents"):::agent - end - mcpp -- "events · records · queries" --> serve - serve -- "LSP / JSON-RPC" --> clients - mcppls -. "C++ files" .-> clients - classDef mcpp fill:#e0e7ff,stroke:#818cf8,color:#312e81 + mcpp -- contract --> serve <-- LSP --> clients <-. LSP .-> mcppls + classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff - classDef ide fill:#ccfbf1,stroke:#2dd4bf,color:#134e4a - classDef agent fill:#f1f5f9,stroke:#cbd5e1,color:#334155 - classDef ls fill:#fef3c7,stroke:#fbbf24,color:#78350f + classDef ide fill:#eef2ff,stroke:#818cf8,color:#3730a3 + classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e + linkStyle 2 stroke:#f59e0b ``` ## Highlights @@ -59,53 +51,37 @@ flowchart LR ## Editors -| | VS Code | CLion | Neovim | +| | VS Code 1.91+ | CLion 2026.1+ | Neovim 0.10+ | |---|---|---|---| -| Build, run, test | tasks, Testing view | run configurations, test runner, ▶ beside `main` | `:Mcpp`, buffers, quickfix | -| Debug | CodeLLDB, C/C++, lldb-dap | CLion's GDB / LLDB | nvim-dap | -| mcpp.toml, build.mcpp | completion, hover, jumps, diagnostics | the same | the same, over `vim.lsp` | -| Libraries, graphs, cache, settings | views and pages | native trees, forms, JCEF graphs | floating windows, `vim.ui.select` | -| C++ language features | mcppls (extension pack) | mcppls CLion plugin | mcppls-nvim | -| Details | [mcpp-vscode](mide-plugins/vscode/README.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | - -## Install - -| Editor | Install | -|---|---| -| VS Code 1.91+ | Marketplace or Open VSX: `mcpp-community.mcpp-vscode`, or `code --install-extension mcpp-vscode-.vsix` | -| CLion 2026.1+ | JetBrains Marketplace: `mcpp-clion`, which depends on the mcppls CLion plugin; or install the ZIP from disk | -| Neovim 0.10+ | `xlings install mcpp-ide-nvim` (with the backend; it sets itself up at start) and `xlings install mcppls-nvim` | -| Agents, other clients | `xlings install mcpp-ide`, then `mcpp-ide serve`; or `okrun mcpp-ide-.okb serve` | - -The VS Code and CLion packages carry the backend for Linux x64/arm64, macOS arm64 and Windows x64 -([distribution](docs/architecture.md#distribution)). Run `mcpp-ide self-check` in a project to verify an -install. Versions and compatibility with mcpp are described in [docs/versions.md](docs/versions.md). +| **Install** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) · [Open VSX](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/35632-mcpp) | `xlings install mcpp-ide-nvim` | +| **Build · run · test** | tasks, Testing view | run configurations, test runner | `:Mcpp`, quickfix | +| **Debug** | CodeLLDB · C/C++ · lldb-dap | GDB · LLDB | nvim-dap | +| **Views** | libraries, graphs, cache, settings | native trees, forms, JCEF graphs | floating windows | +| **C++ (mcppls)** | [installed with it](https://marketplace.visualstudio.com/items?itemName=sunrisepeak.mcpp-language-server) | [mcppls plugin](https://plugins.jetbrains.com/plugin/35609) | `xlings install mcppls-nvim` | +| **Guide** | [mcpp-vscode](mide-plugins/vscode/README.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | + +mcpp.toml and build.mcpp get completion, hover, jumps and diagnostics in every editor. The VS Code and +CLion packages carry the backend for Linux x64/arm64, macOS arm64 and Windows x64; offline, install the +`.vsix` or `.zip` from [Releases](https://github.com/mcpp-community/mcpp-ide/releases). Agents and other clients use `xlings install mcpp-ide`, then +`mcpp-ide serve`. Verify any install with `mcpp-ide self-check`; versions: [docs/versions.md](docs/versions.md). ## With an agent -A prompt names **the repository**, **the document to read first**, **the task** and **the check that -ends it**. The documents are written for agents, so the prompt stays short. Copy one and fill in `<...>`. - -**Install** · [agents/README.md](agents/README.md), the [mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) - -```text -Read agents/README.md of https://github.com/mcpp-community/mcpp-ide, install mcpp-ide for -from the latest release, and verify it with `mcpp-ide self-check` on my project. -``` - -**Understand** · [AGENTS.md](AGENTS.md), [docs/architecture.md](docs/architecture.md) - -```text -Read AGENTS.md and docs/architecture.md of https://github.com/mcpp-community/mcpp-ide, then explain -how a build travels from the editor through the backend to mcpp, and which layer owns . -``` - -**Contribute** · the [contributing](.agents/skills/mcpp-ide-contributing/SKILL.md) and [development](.agents/skills/mcpp-ide-development/SKILL.md) skills +Paste this into any coding agent. It reads only what your task needs, and asks you first when the +task is not clear. ```text -Read AGENTS.md and .agents/skills/mcpp-ide-contributing of https://github.com/mcpp-community/mcpp-ide. -Triage : core or plugin, fix or workaround. Propose the change and the tests that prove it, -and wait for my go-ahead before opening a pull request. +Work with mcpp-ide (https://github.com/mcpp-community/mcpp-ide), the IDE layer of mcpp. +Read AGENTS.md first, then only what my task needs: +- install or use it: agents/README.md, verified with `mcpp-ide self-check` on my project +- understand it: docs/architecture.md, saying which layer owns what +- report a bug or propose a feature: .agents/skills/mcpp-ide-contributing, triage first + (mcpp, mcppls, backend or one plugin; fix or workaround), then draft the issue from its template +- change the code: that skill and .agents/skills/mcpp-ide-development, with tests that prove it +My task: +If it is empty or unclear, tell me in three lines what mcpp-ide is, then ask which of the above +I want, with one suggested first step for each. Ask me before opening an issue or a pull request, +pushing, or tagging. ``` ## Development diff --git a/README.zh-CN.md b/README.zh-CN.md index 5e032de..564408b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -10,7 +10,7 @@ VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为 [![CI](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpp-community/mcpp-ide/actions/workflows/ci.yml) [![VS Code](https://img.shields.io/badge/VS_Code-mcpp--vscode-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) [![Open VSX](https://img.shields.io/open-vsx/v/mcpp-community/mcpp-vscode?label=Open%20VSX)](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) -[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/io.github.mcpp-community.mcpp-clion) +[![JetBrains](https://img.shields.io/jetbrains/plugin/v/io.github.mcpp-community.mcpp-clion?label=CLion)](https://plugins.jetbrains.com/plugin/35632-mcpp) [![C++23](https://img.shields.io/badge/C%2B%2B-23_modules-blue.svg)](https://en.cppreference.com/w/cpp/23) [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) @@ -26,26 +26,18 @@ VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为 各插件再用编辑器自己的界面呈现这些回答。 ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#94a3b8", "edgeLabelBackground": "#f8fafc", "clusterBkg": "#f0fdfa", "clusterBorder": "#99f6e4", "titleColor": "#0f766e"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "linear", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% flowchart LR - mcpp("mcpp
机器契约"):::mcpp + mcpp("mcpp
机器契约"):::ext serve("mcpp-ide serve
所有决定"):::core + clients("VS Code · CLion
Neovim · agents

原生界面,不做决定"):::ide mcppls("mcppls
C++ 语言功能"):::ls - subgraph clients ["原生界面 · 不做决定"] - direction LR - vscode("mcpp-vscode"):::ide - clion("mcpp-clion"):::ide - nvim("mcpp-nvim"):::ide - agent("agents"):::agent - end - mcpp -- "事件 · 记录 · 查询" --> serve - serve -- "LSP / JSON-RPC" --> clients - mcppls -. "C++ 文件" .-> clients - classDef mcpp fill:#e0e7ff,stroke:#818cf8,color:#312e81 + mcpp -- 契约 --> serve <-- LSP --> clients <-. LSP .-> mcppls + classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff - classDef ide fill:#ccfbf1,stroke:#2dd4bf,color:#134e4a - classDef agent fill:#f1f5f9,stroke:#cbd5e1,color:#334155 - classDef ls fill:#fef3c7,stroke:#fbbf24,color:#78350f + classDef ide fill:#eef2ff,stroke:#818cf8,color:#3730a3 + classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e + linkStyle 2 stroke:#f59e0b ``` ## 特性 @@ -58,52 +50,35 @@ flowchart LR ## 编辑器 -| | VS Code | CLion | Neovim | +| | VS Code 1.91+ | CLion 2026.1+ | Neovim 0.10+ | |---|---|---|---| -| 构建、运行、测试 | 任务、测试视图 | 运行配置、测试运行器、`main` 旁的 ▶ | `:Mcpp`、缓冲区、quickfix | -| 调试 | CodeLLDB、C/C++、lldb-dap | CLion 的 GDB / LLDB | nvim-dap | -| mcpp.toml、build.mcpp | 补全、悬停、跳转、诊断 | 同上 | 同上,经 `vim.lsp` | -| 库、依赖图、缓存、设置 | 视图与页面 | 原生树、表单、JCEF 中的图 | 浮动窗口、`vim.ui.select` | -| C++ 语言功能 | mcppls(扩展包) | mcppls CLion 插件 | mcppls-nvim | -| 详情 | [mcpp-vscode](mide-plugins/vscode/README.zh-CN.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | - -## 安装 - -| 编辑器 | 安装 | -|---|---| -| VS Code 1.91+ | Marketplace 或 Open VSX:`mcpp-community.mcpp-vscode`,或 `code --install-extension mcpp-vscode-.vsix` | -| CLion 2026.1+ | JetBrains Marketplace:`mcpp-clion`,依赖 mcppls CLion 插件;或从磁盘安装 ZIP | -| Neovim 0.10+ | `xlings install mcpp-ide-nvim`(连同后端,启动时自动 setup)与 `xlings install mcppls-nvim` | -| Agent、其他客户端 | `xlings install mcpp-ide`,然后运行 `mcpp-ide serve`;或 `okrun mcpp-ide-.okb serve` | - -VS Code 与 CLion 的包自带后端,覆盖 Linux x64/arm64、macOS arm64 与 Windows x64 -([分发方式](docs/architecture.md#distribution))。在工程中运行 `mcpp-ide self-check` 即可验证安装。 -版本与 mcpp 的兼容性见 [docs/versions.md](docs/versions.md)。 +| **安装** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=mcpp-community.mcpp-vscode) · [Open VSX](https://open-vsx.org/extension/mcpp-community/mcpp-vscode) | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/35632-mcpp) | `xlings install mcpp-ide-nvim` | +| **构建 · 运行 · 测试** | 任务、测试视图 | 运行配置、测试运行器 | `:Mcpp`、quickfix | +| **调试** | CodeLLDB · C/C++ · lldb-dap | GDB · LLDB | nvim-dap | +| **视图** | 库、依赖图、缓存、设置 | 原生树、表单、JCEF 图 | 浮动窗口 | +| **C++(mcppls)** | [随扩展安装](https://marketplace.visualstudio.com/items?itemName=sunrisepeak.mcpp-language-server) | [mcppls 插件](https://plugins.jetbrains.com/plugin/35609) | `xlings install mcppls-nvim` | +| **指南** | [mcpp-vscode](mide-plugins/vscode/README.zh-CN.md) | [mcpp-clion](mide-plugins/clion/README.md) | [mcpp-nvim](mide-plugins/nvim/README.md) | + +mcpp.toml 与 build.mcpp 在所有编辑器中都有补全、悬停、跳转与诊断。VS Code 与 CLion 的包自带后端,覆盖 +Linux x64/arm64、macOS arm64 与 Windows x64;离线时从[发布页](https://github.com/mcpp-community/mcpp-ide/releases)安装 `.vsix` 或 `.zip`。Agent 与其他 +客户端使用 `xlings install mcpp-ide`,然后运行 `mcpp-ide serve`。安装后用 `mcpp-ide self-check` 验证;版本见 +[docs/versions.md](docs/versions.md)。 ## 使用 Agent -一条提示词写清四件事:**仓库**、**先读哪份文档**、**要做的任务**、**以什么检查结束**。文档本身面向 Agent 编写, -所以提示词可以很短。复制一条,填入 `<...>` 即可。 - -**安装** · [agents/README.md](agents/README.md)、[mcpp-ide skill](agents/skills/mcpp-ide/SKILL.md) - -```text -阅读 https://github.com/mcpp-community/mcpp-ide 的 agents/README.md,为 <我的编辑器> 从最新发布安装 -mcpp-ide,并在我的工程上用 `mcpp-ide self-check` 验证。 -``` - -**了解项目** · [AGENTS.md](AGENTS.md)、[docs/architecture.md](docs/architecture.md) - -```text -阅读 https://github.com/mcpp-community/mcpp-ide 的 AGENTS.md 与 docs/architecture.md,说明一次构建如何 -从编辑器经后端到达 mcpp,以及 <功能> 属于哪一层。 -``` - -**参与贡献** · [贡献](.agents/skills/mcpp-ide-contributing/SKILL.md)与[开发](.agents/skills/mcpp-ide-development/SKILL.md) skill +把下面这段粘贴给任意编程 Agent。它只读任务需要的文档;任务不明确时,会先询问你。 ```text -阅读 https://github.com/mcpp-community/mcpp-ide 的 AGENTS.md 与 .agents/skills/mcpp-ide-contributing, -对 做分诊(core 还是插件,修复还是 workaround),提出改动方案及能证明它的测试;开 PR 前先等我确认。 +协助我处理 mcpp-ide(https://github.com/mcpp-community/mcpp-ide),即 mcpp 的 IDE 层。 +先读 AGENTS.md,再只读我的任务需要的文档: +- 安装或使用:agents/README.md,并在我的工程上用 `mcpp-ide self-check` 验证 +- 了解项目:docs/architecture.md,说明各层分别负责什么 +- 报告问题或提出功能:.agents/skills/mcpp-ide-contributing,先分诊(mcpp、mcppls、后端还是某个插件; + 修复还是 workaround),再按模板起草 issue +- 修改代码:上述 skill 与 .agents/skills/mcpp-ide-development,并给出能证明改动的测试 +我的任务:<在此描述,或留空> +若留空或不明确,先用三行说明 mcpp-ide 是什么,再问我想做上面哪一项,并为每项给出建议的第一步。 +开 issue、PR,推送或打 tag 之前先征得我的同意。 ``` ## 开发 diff --git a/agents/README.md b/agents/README.md index 8911ed9..d2a462e 100644 --- a/agents/README.md +++ b/agents/README.md @@ -23,7 +23,7 @@ and its contract, mcppls, xlings, trust. ## A session ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#e0e7ff", "actorBorder": "#818cf8", "actorTextColor": "#312e81", "actorLineColor": "#cbd5e1", "signalColor": "#64748b", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fef3c7", "noteBorderColor": "#fbbf24", "noteTextColor": "#78350f", "activationBkgColor": "#ccfbf1", "activationBorderColor": "#2dd4bf", "labelBoxBkgColor": "#e0e7ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#312e81", "loopTextColor": "#64748b"}}}%% +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#eef2ff", "actorBorder": "#818cf8", "actorTextColor": "#3730a3", "actorLineColor": "#c7d2fe", "signalColor": "#818cf8", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fffbeb", "noteBorderColor": "#f59e0b", "noteTextColor": "#92400e", "labelBoxBkgColor": "#eef2ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#3730a3", "loopTextColor": "#64748b"}}}%% sequenceDiagram participant A as Agent participant B as mcpp-ide serve diff --git a/docs/architecture.md b/docs/architecture.md index 45ecf12..b48e3d3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -63,7 +63,7 @@ mcppls what a compiler answers better. ## A build, end to end ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#e0e7ff", "actorBorder": "#818cf8", "actorTextColor": "#312e81", "actorLineColor": "#cbd5e1", "signalColor": "#64748b", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fef3c7", "noteBorderColor": "#fbbf24", "noteTextColor": "#78350f", "activationBkgColor": "#ccfbf1", "activationBorderColor": "#2dd4bf", "labelBoxBkgColor": "#e0e7ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#312e81", "loopTextColor": "#64748b"}}}%% +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#eef2ff", "actorBorder": "#818cf8", "actorTextColor": "#3730a3", "actorLineColor": "#c7d2fe", "signalColor": "#818cf8", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fffbeb", "noteBorderColor": "#f59e0b", "noteTextColor": "#92400e", "labelBoxBkgColor": "#eef2ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#3730a3", "loopTextColor": "#64748b"}}}%% sequenceDiagram autonumber participant E as Editor plugin @@ -101,7 +101,7 @@ program is written with, and the backend knows none by name. What a framework of it states of itself (`mcpp test --guide`, B6). ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#e0e7ff", "actorBorder": "#818cf8", "actorTextColor": "#312e81", "actorLineColor": "#cbd5e1", "signalColor": "#64748b", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fef3c7", "noteBorderColor": "#fbbf24", "noteTextColor": "#78350f", "activationBkgColor": "#ccfbf1", "activationBorderColor": "#2dd4bf", "labelBoxBkgColor": "#e0e7ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#312e81", "loopTextColor": "#64748b"}}}%% +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#eef2ff", "actorBorder": "#818cf8", "actorTextColor": "#3730a3", "actorLineColor": "#c7d2fe", "signalColor": "#818cf8", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fffbeb", "noteBorderColor": "#f59e0b", "noteTextColor": "#92400e", "labelBoxBkgColor": "#eef2ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#3730a3", "loopTextColor": "#64748b"}}}%% sequenceDiagram autonumber participant E as Editor plugin @@ -178,13 +178,16 @@ editor package carries that bundle and the runner that starts it on each system: | `backend/okrun/-/okrun[.exe]` | okrun for `linux-x86_64`, `linux-aarch64`, `macos-aarch64`, `windows-x86_64`, from the universal self-contained package (`--mode self-contained --systems all`: each okrun built over the platform's hosted arrangement); one command packs both, `mcpp pack mcpp-ide --target openkal --mode self-contained --systems all --pkg-format tar,okb`, and the package's `runs_on.self` names the systems it runs on | `okrun mcpp-ide.okb serve`: the okrun carried for this system, else okrun on PATH | ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#94a3b8", "edgeLabelBackground": "#f8fafc", "clusterBkg": "#f0fdfa", "clusterBorder": "#99f6e4", "titleColor": "#0f766e"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "linear", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% flowchart LR - cfg("1 · mcpp.ide.backendPath"):::core + cfg("1 · mcpp.ide.backendPath"):::ext pkg("2 · the package's .okb
run by okrun"):::core - inst("3 · mcpp-ide
from xlings or PATH"):::core + inst("3 · mcpp-ide
from xlings or PATH"):::ide cfg -- unset --> pkg -- not carried --> inst - classDef core fill:#e0e7ff,stroke:#818cf8,color:#312e81 + classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 + classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff + classDef ide fill:#eef2ff,stroke:#818cf8,color:#3730a3 + classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e ``` Before it, a configured `mcpp.ide.backendPath` (a program or an `.okb`) is used; after it, an From 277ae81cb7a5b47bbff6e8a3f38fa268b63d5fa5 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sat, 21 Nov 2026 13:23:51 +0900 Subject: [PATCH 4/5] docs: the architecture as layers, each editor its own client - The README's diagram is layered: the clients on top, each editor (VS Code, CLion, Neovim) and agents a node of its own with its own connection; the backend, mcpp-ide serve, as the layer every decision lives in, with its parts (projects, jobs, view models, the rules of mcpp.toml); mcpp at the bottom, which the backend runs and whose contract it reads; mcppls beside it, whose status the backend asks and which reads mcpp's result record. - Colour carries ownership: indigo for mcpp-ide, amber for mcppls, slate for mcpp. Flowcharts draw curves again. --- README.md | 30 ++++++++++++++++++++---------- README.zh-CN.md | 30 ++++++++++++++++++++---------- docs/architecture.md | 2 +- 3 files changed, 41 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index ee80e66..f629a8b 100644 --- a/README.md +++ b/README.md @@ -27,18 +27,28 @@ apart. mcpp-ide makes them once. Its backend, `mcpp-ide serve`, reads only mcpp' and answers every editor as an LSP server. Each plugin then shows those answers in its editor's own UI. ```mermaid -%%{init: {"theme": "base", "flowchart": {"curve": "linear", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% -flowchart LR - mcpp("mcpp
machine contract"):::ext - serve("mcpp-ide serve
every decision"):::core - clients("VS Code · CLion
Neovim · agents

native UI, no decisions"):::ide - mcppls("mcppls
C++ language features"):::ls - mcpp -- contract --> serve <-- LSP --> clients <-. LSP .-> mcppls +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 22, "rankSpacing": 60, "padding": 10}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#6366f1", "edgeLabelBackground": "#ffffff"}}}%% +flowchart TB + vscode("VS Code
mcpp-vscode"):::ide + clion("CLion
mcpp-clion"):::ide + nvim("Neovim
mcpp-nvim"):::ide + agent("Agents
mcpp-ide skill"):::ide + subgraph backend ["mcpp-ide serve · LSP server · every decision"] + direction LR + projects("projects"):::part ~~~ jobs("jobs"):::part ~~~ views("view models"):::part ~~~ rules("mcpp.toml rules"):::part + end + mcppls("mcppls
C++ language server"):::ls + mcpp("mcpp
build · test · pack"):::ext + vscode & clion & nvim & agent ==> backend + backend -. "status" .-> mcppls + backend == "runs · reads its contract" ==> mcpp + mcppls -. "result record" .-> mcpp + classDef ide fill:#ffffff,stroke:#818cf8,color:#3730a3 + classDef part fill:#eef2ff,stroke:#c7d2fe,color:#312e81 classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 - classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff - classDef ide fill:#eef2ff,stroke:#818cf8,color:#3730a3 classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e - linkStyle 2 stroke:#f59e0b + style backend fill:#4f46e5,stroke:#4338ca,color:#ffffff + linkStyle 7,9 stroke:#f59e0b ``` ## Highlights diff --git a/README.zh-CN.md b/README.zh-CN.md index 564408b..d285bc3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -26,18 +26,28 @@ VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为 各插件再用编辑器自己的界面呈现这些回答。 ```mermaid -%%{init: {"theme": "base", "flowchart": {"curve": "linear", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% -flowchart LR - mcpp("mcpp
机器契约"):::ext - serve("mcpp-ide serve
所有决定"):::core - clients("VS Code · CLion
Neovim · agents

原生界面,不做决定"):::ide - mcppls("mcppls
C++ 语言功能"):::ls - mcpp -- 契约 --> serve <-- LSP --> clients <-. LSP .-> mcppls +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 22, "rankSpacing": 60, "padding": 10}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#6366f1", "edgeLabelBackground": "#ffffff"}}}%% +flowchart TB + vscode("VS Code
mcpp-vscode"):::ide + clion("CLion
mcpp-clion"):::ide + nvim("Neovim
mcpp-nvim"):::ide + agent("Agents
mcpp-ide skill"):::ide + subgraph backend ["mcpp-ide serve · LSP 服务器 · 所有决定"] + direction LR + projects("工程"):::part ~~~ jobs("任务"):::part ~~~ views("视图模型"):::part ~~~ rules("mcpp.toml 规则"):::part + end + mcppls("mcppls
C++ 语言服务器"):::ls + mcpp("mcpp
构建 · 测试 · 打包"):::ext + vscode & clion & nvim & agent ==> backend + backend -. "状态" .-> mcppls + backend == "运行 · 读取契约" ==> mcpp + mcppls -. "结果记录" .-> mcpp + classDef ide fill:#ffffff,stroke:#818cf8,color:#3730a3 + classDef part fill:#eef2ff,stroke:#c7d2fe,color:#312e81 classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 - classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff - classDef ide fill:#eef2ff,stroke:#818cf8,color:#3730a3 classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e - linkStyle 2 stroke:#f59e0b + style backend fill:#4f46e5,stroke:#4338ca,color:#ffffff + linkStyle 7,9 stroke:#f59e0b ``` ## 特性 diff --git a/docs/architecture.md b/docs/architecture.md index b48e3d3..bd580b8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -178,7 +178,7 @@ editor package carries that bundle and the runner that starts it on each system: | `backend/okrun/-/okrun[.exe]` | okrun for `linux-x86_64`, `linux-aarch64`, `macos-aarch64`, `windows-x86_64`, from the universal self-contained package (`--mode self-contained --systems all`: each okrun built over the platform's hosted arrangement); one command packs both, `mcpp pack mcpp-ide --target openkal --mode self-contained --systems all --pkg-format tar,okb`, and the package's `runs_on.self` names the systems it runs on | `okrun mcpp-ide.okb serve`: the okrun carried for this system, else okrun on PATH | ```mermaid -%%{init: {"theme": "base", "flowchart": {"curve": "linear", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% flowchart LR cfg("1 · mcpp.ide.backendPath"):::ext pkg("2 · the package's .okb
run by okrun"):::core From 7c411fbf3a7a8d47c44ffa8cac70ec9cc77042e0 Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sat, 21 Nov 2026 13:28:39 +0900 Subject: [PATCH 5/5] docs: a simpler architecture diagram in GitHub's palette - The README's diagram keeps its layers and drops what repeats: each client (VS Code, CLion, Neovim, agents) an arrow of its own into mcpp-ide serve, which runs mcpp under its contract and asks mcppls its status; the backend's parts and the repeated LSP labels are left to the text. - Every diagram takes GitHub's Primer colours: blue for mcpp-ide (the backend solid), purple for mcppls, grey for mcpp; the sequence diagrams' actors, messages and notes follow them. --- README.md | 35 +++++++++++++++-------------------- README.zh-CN.md | 35 +++++++++++++++-------------------- agents/README.md | 2 +- docs/architecture.md | 18 +++++++++--------- 4 files changed, 40 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index f629a8b..2103706 100644 --- a/README.md +++ b/README.md @@ -27,28 +27,23 @@ apart. mcpp-ide makes them once. Its backend, `mcpp-ide serve`, reads only mcpp' and answers every editor as an LSP server. Each plugin then shows those answers in its editor's own UI. ```mermaid -%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 22, "rankSpacing": 60, "padding": 10}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#6366f1", "edgeLabelBackground": "#ffffff"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 26, "rankSpacing": 56, "padding": 14}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#54aeff", "edgeLabelBackground": "#ffffff"}}}%% flowchart TB - vscode("VS Code
mcpp-vscode"):::ide - clion("CLion
mcpp-clion"):::ide - nvim("Neovim
mcpp-nvim"):::ide - agent("Agents
mcpp-ide skill"):::ide - subgraph backend ["mcpp-ide serve · LSP server · every decision"] - direction LR - projects("projects"):::part ~~~ jobs("jobs"):::part ~~~ views("view models"):::part ~~~ rules("mcpp.toml rules"):::part - end + vscode("VS Code
mcpp-vscode"):::client + clion("CLion
mcpp-clion"):::client + nvim("Neovim
mcpp-nvim"):::client + agent("Agents
mcpp-ide skill"):::client + serve("mcpp-ide serve
LSP · every decision"):::core mcppls("mcppls
C++ language server"):::ls - mcpp("mcpp
build · test · pack"):::ext - vscode & clion & nvim & agent ==> backend - backend -. "status" .-> mcppls - backend == "runs · reads its contract" ==> mcpp - mcppls -. "result record" .-> mcpp - classDef ide fill:#ffffff,stroke:#818cf8,color:#3730a3 - classDef part fill:#eef2ff,stroke:#c7d2fe,color:#312e81 - classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 - classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e - style backend fill:#4f46e5,stroke:#4338ca,color:#ffffff - linkStyle 7,9 stroke:#f59e0b + mcpp("mcpp
build · test · pack"):::tool + vscode & clion & nvim & agent --> serve + serve -- contract --> mcpp + serve -. status .-> mcppls + classDef client fill:#ffffff,stroke:#54aeff,color:#0550ae + classDef core fill:#0969da,stroke:#0550ae,color:#ffffff + classDef ls fill:#fbefff,stroke:#c297ff,color:#6639ba + classDef tool fill:#f6f8fa,stroke:#8c959f,color:#24292f + linkStyle 5 stroke:#c297ff ``` ## Highlights diff --git a/README.zh-CN.md b/README.zh-CN.md index d285bc3..7dc8e46 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -26,28 +26,23 @@ VS Code · CLion · Neovim 的构建、运行、测试、调试、打包行为 各插件再用编辑器自己的界面呈现这些回答。 ```mermaid -%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 22, "rankSpacing": 60, "padding": 10}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#6366f1", "edgeLabelBackground": "#ffffff"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 26, "rankSpacing": 56, "padding": 14}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#54aeff", "edgeLabelBackground": "#ffffff"}}}%% flowchart TB - vscode("VS Code
mcpp-vscode"):::ide - clion("CLion
mcpp-clion"):::ide - nvim("Neovim
mcpp-nvim"):::ide - agent("Agents
mcpp-ide skill"):::ide - subgraph backend ["mcpp-ide serve · LSP 服务器 · 所有决定"] - direction LR - projects("工程"):::part ~~~ jobs("任务"):::part ~~~ views("视图模型"):::part ~~~ rules("mcpp.toml 规则"):::part - end + vscode("VS Code
mcpp-vscode"):::client + clion("CLion
mcpp-clion"):::client + nvim("Neovim
mcpp-nvim"):::client + agent("Agents
mcpp-ide skill"):::client + serve("mcpp-ide serve
LSP · 所有决定"):::core mcppls("mcppls
C++ 语言服务器"):::ls - mcpp("mcpp
构建 · 测试 · 打包"):::ext - vscode & clion & nvim & agent ==> backend - backend -. "状态" .-> mcppls - backend == "运行 · 读取契约" ==> mcpp - mcppls -. "结果记录" .-> mcpp - classDef ide fill:#ffffff,stroke:#818cf8,color:#3730a3 - classDef part fill:#eef2ff,stroke:#c7d2fe,color:#312e81 - classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 - classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e - style backend fill:#4f46e5,stroke:#4338ca,color:#ffffff - linkStyle 7,9 stroke:#f59e0b + mcpp("mcpp
构建 · 测试 · 打包"):::tool + vscode & clion & nvim & agent --> serve + serve -- 契约 --> mcpp + serve -. 状态 .-> mcppls + classDef client fill:#ffffff,stroke:#54aeff,color:#0550ae + classDef core fill:#0969da,stroke:#0550ae,color:#ffffff + classDef ls fill:#fbefff,stroke:#c297ff,color:#6639ba + classDef tool fill:#f6f8fa,stroke:#8c959f,color:#24292f + linkStyle 5 stroke:#c297ff ``` ## 特性 diff --git a/agents/README.md b/agents/README.md index d2a462e..5e0af04 100644 --- a/agents/README.md +++ b/agents/README.md @@ -23,7 +23,7 @@ and its contract, mcppls, xlings, trust. ## A session ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#eef2ff", "actorBorder": "#818cf8", "actorTextColor": "#3730a3", "actorLineColor": "#c7d2fe", "signalColor": "#818cf8", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fffbeb", "noteBorderColor": "#f59e0b", "noteTextColor": "#92400e", "labelBoxBkgColor": "#eef2ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#3730a3", "loopTextColor": "#64748b"}}}%% +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#ddf4ff", "actorBorder": "#54aeff", "actorTextColor": "#0550ae", "actorLineColor": "#b6e3ff", "signalColor": "#54aeff", "signalTextColor": "#57606a", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fbefff", "noteBorderColor": "#c297ff", "noteTextColor": "#6639ba", "labelBoxBkgColor": "#ddf4ff", "labelBoxBorderColor": "#54aeff", "labelTextColor": "#0550ae", "loopTextColor": "#57606a"}}}%% sequenceDiagram participant A as Agent participant B as mcpp-ide serve diff --git a/docs/architecture.md b/docs/architecture.md index bd580b8..e8b3046 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -63,7 +63,7 @@ mcppls what a compiler answers better. ## A build, end to end ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#eef2ff", "actorBorder": "#818cf8", "actorTextColor": "#3730a3", "actorLineColor": "#c7d2fe", "signalColor": "#818cf8", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fffbeb", "noteBorderColor": "#f59e0b", "noteTextColor": "#92400e", "labelBoxBkgColor": "#eef2ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#3730a3", "loopTextColor": "#64748b"}}}%% +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#ddf4ff", "actorBorder": "#54aeff", "actorTextColor": "#0550ae", "actorLineColor": "#b6e3ff", "signalColor": "#54aeff", "signalTextColor": "#57606a", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fbefff", "noteBorderColor": "#c297ff", "noteTextColor": "#6639ba", "labelBoxBkgColor": "#ddf4ff", "labelBoxBorderColor": "#54aeff", "labelTextColor": "#0550ae", "loopTextColor": "#57606a"}}}%% sequenceDiagram autonumber participant E as Editor plugin @@ -101,7 +101,7 @@ program is written with, and the backend knows none by name. What a framework of it states of itself (`mcpp test --guide`, B6). ```mermaid -%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#eef2ff", "actorBorder": "#818cf8", "actorTextColor": "#3730a3", "actorLineColor": "#c7d2fe", "signalColor": "#818cf8", "signalTextColor": "#64748b", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fffbeb", "noteBorderColor": "#f59e0b", "noteTextColor": "#92400e", "labelBoxBkgColor": "#eef2ff", "labelBoxBorderColor": "#818cf8", "labelTextColor": "#3730a3", "loopTextColor": "#64748b"}}}%% +%%{init: {"theme": "base", "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "actorBkg": "#ddf4ff", "actorBorder": "#54aeff", "actorTextColor": "#0550ae", "actorLineColor": "#b6e3ff", "signalColor": "#54aeff", "signalTextColor": "#57606a", "sequenceNumberColor": "#ffffff", "noteBkgColor": "#fbefff", "noteBorderColor": "#c297ff", "noteTextColor": "#6639ba", "labelBoxBkgColor": "#ddf4ff", "labelBoxBorderColor": "#54aeff", "labelTextColor": "#0550ae", "loopTextColor": "#57606a"}}}%% sequenceDiagram autonumber participant E as Editor plugin @@ -178,16 +178,16 @@ editor package carries that bundle and the runner that starts it on each system: | `backend/okrun/-/okrun[.exe]` | okrun for `linux-x86_64`, `linux-aarch64`, `macos-aarch64`, `windows-x86_64`, from the universal self-contained package (`--mode self-contained --systems all`: each okrun built over the platform's hosted arrangement); one command packs both, `mcpp pack mcpp-ide --target openkal --mode self-contained --systems all --pkg-format tar,okb`, and the package's `runs_on.self` names the systems it runs on | `okrun mcpp-ide.okb serve`: the okrun carried for this system, else okrun on PATH | ```mermaid -%%{init: {"theme": "base", "flowchart": {"curve": "basis", "rankSpacing": 70}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#818cf8", "edgeLabelBackground": "#ffffff"}}}%% +%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 26, "rankSpacing": 56, "padding": 14}, "themeVariables": {"fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif", "fontSize": "14px", "lineColor": "#54aeff", "edgeLabelBackground": "#ffffff"}}}%% flowchart LR - cfg("1 · mcpp.ide.backendPath"):::ext + cfg("1 · mcpp.ide.backendPath"):::tool pkg("2 · the package's .okb
run by okrun"):::core - inst("3 · mcpp-ide
from xlings or PATH"):::ide + inst("3 · mcpp-ide
from xlings or PATH"):::client cfg -- unset --> pkg -- not carried --> inst - classDef ext fill:#f8fafc,stroke:#94a3b8,color:#334155 - classDef core fill:#4f46e5,stroke:#4338ca,color:#ffffff - classDef ide fill:#eef2ff,stroke:#818cf8,color:#3730a3 - classDef ls fill:#fffbeb,stroke:#f59e0b,color:#92400e + classDef client fill:#ffffff,stroke:#54aeff,color:#0550ae + classDef core fill:#0969da,stroke:#0550ae,color:#ffffff + classDef ls fill:#fbefff,stroke:#c297ff,color:#6639ba + classDef tool fill:#f6f8fa,stroke:#8c959f,color:#24292f ``` Before it, a configured `mcpp.ide.backendPath` (a program or an `.okb`) is used; after it, an