docs: simplify README + add add-mcpp-index-package skill#51
Merged
Conversation
Sunrisepeak
changed the title
Codifies the full process used for cjson/nlohmann/eigen into a reusable skill under .agents/skills/add-mcpp-index-package/: - SKILL.md — 12-step SOP, the sources-only feature gate (+ mandatory negative test), version-matched local verification, red-flags/common mistakes. - package-types.md — descriptor templates for the four shapes (C-source compat / header-only / C++23 module via generated wrapper / external Form-A module repo), each with real sample paths. - cn-mirror.md — gtc/gitcode mcpp-res mirror closed loop + every known gotcha. - references.md — repo layout, descriptor schema cheat-sheet, validate.yml CI behavior, one-shot local lint, real worked examples (#48 / #50).
Sunrisepeak
force-pushed
the
docs/readme-and-skill
branch
from
46b5ddd to
8a7644f
Compare
Drop the package tables/dependency tree/smoke breakdown/Form-A-B examples from the index README — the browsable site (mcpplibs.github.io/mcpp-index) is the package list, and the how-to detail lives in the add-mcpp-index-package skill. README now = what it is, mcpp add/build usage, the two package categories (native module libs / third-party compat) with a pointer to the skill, and related tools / community.
Sunrisepeak
force-pushed
the
docs/readme-and-skill
branch
from
8a7644f to
71ad4b0
Compare
…llback
- Move the skill's reference files into a human-facing docs/ folder (single
source): package-types.md, cn-mirror.md, repository-and-schema.md (+ index
docs/README.md). SKILL.md now links to ../../../docs/*; the skill dir keeps
just SKILL.md (the agent SOP).
- README: add a "参考示例" table linking typical descriptors by shape
(Form-A module / C-source compat / header-only / module wrapper), a
copy-paste agent prompt that drives the skill end-to-end, and links to docs/.
- skill + docs: document the no-`mcpp-res`-permission fallback — use a
plain-string upstream `url` (lint forbids a {GLOBAL,CN} table whose CN isn't
gitcode/mcpp-res; plain strings are unconstrained). Real precedent:
pkgs/t/tensorvia-cpu.lua.
- skill step 1 now distinguishes the two sources: a third-party upstream lib
vs. the user's own mcpp-based library (Form A, lighter research).
Rewrite all prose across README.md, docs/*, and the add-mcpp-index-package skill into declarative, academic-style Chinese: remove colloquial terms (一把梭 / 踩坑 / 丢给 / 硬凑 / 藏不住 …) and decorative emoji (⚠️ ✅❌📘✓), and reformulate fragments as complete declarative sentences. The red-flag table becomes a "错误做法 / 正确做法" table; section headings are normalized (e.g. "本地 lint 一把梭" → "本地 lint 复现(等价于 CI lint job)", "踩坑" → "注意事项", "CI 兜底" → "CI 保障"). Technical content, commands, code samples, and links are unchanged.
Sunrisepeak
added a commit
that referenced
this pull request
Jun 29, 2026
…git packs (#53) smoke-full-linux failed in 'smoke tests' with hundreds of: cp: cannot create regular file '.../mcpplibs/./.git/objects/pack/pack-*.pack': Permission denied Root cause: the smoke jobs run several scripts under one shared MCPP_HOME. By the time smoke_imgui_module.sh runs, an earlier smoke has already populated $MCPP_HOME/registry/data/mcpplibs/.git with read-only git pack objects (git makes packs mode 0444). smoke_imgui_module.sh then did, with no guard: cp -a "$ROOT/." "$default_index/" which copies the repo's OWN .git (same-named, read-only packs) over the existing read-only packs — and cp cannot overwrite a read-only target -> Permission denied -> the whole job fails (exit 1). Pre-existing since #51; not a mcpp/xlings bug (mcpp shells no such cp; xlings uses std::filesystem::copy). Fix: remove the destination first (rm -rf tolerates read-only files — it needs write on the parent dir, not the file), and seed from the working tree EXCLUDING the repo's .git. The package index only needs pkgs/; the repo's read-only pack objects are both irrelevant and the sole cause of the conflict. Reproduced locally: old path -> 821 'Permission denied'; new path -> 0, pkgs/ present.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
README 精简 + agent skill + 贡献文档(
docs/),供 review。README(精简为入口型,~76 行)
基本介绍 +
mcpp add/build使用示例 + 包生态与贡献 + 相关工具/社区。不再罗列包(完整列表看在线索引站)。贡献区新增:.lua(Form-A 模块库 / C 源 compat / header-only / module wrapper)。docs/的细节文档。docs/(人 / agent 共用的贡献文档)把原先放在 skill 里的参考资料移到仓库
docs/,单一来源、可从 README 直达:docs/package-types.md— 四种库形态描述符模板 + 样例docs/cn-mirror.md—gtc/gitcode CN 镜像闭环docs/repository-and-schema.md— 仓库结构 / schema 速查 / CI / 本地 lintdocs/README.md— 文档索引agent skill
add-mcpp-index-package.agents/skills/add-mcpp-index-package/SKILL.md保留为 agent 用的 12 步 SOP,引用上面的docs/。本轮补充:mcpp-res写权限的回退:用 plain-string 上游url(lint 禁止{GLOBAL,CN}表里 CN 非 gitcode/mcpp-res;纯字符串不受约束)。真实先例pkgs/t/tensorvia-cpu.lua。CI
.agents/**与docs/**不在 PR 触发路径;README 改动触发validate(lint / mirror-cn-reachable / detect),无包改动故 smoke 全 skip。已绿。