From 2d76433be04cd59dfe5964a166a92acf33f23c8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=89=E6=BE=9C?= Date: Mon, 3 Aug 2026 12:27:26 +0800 Subject: [PATCH] docs(schema): group reviewed inputs beside command registry Co-authored-by: Cursor --- AGENTS.md | 29 ++++++++++++++++++++----- docs/schema/schema-command-registry.md | 4 ++++ internal/cli/param_concepts.go | 3 ++- internal/cli/schema_command_registry.go | 3 ++- 4 files changed, 32 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f5a4a689..994c4ff5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,7 +38,10 @@ snapshot. It is the single reviewed source of stable canonical identity, primary paths, aliases, and navigation. Edit it only when reviewed exposure, identity, primary path, or aliases change; parameter, Skill, and metadata-only changes must not rewrite it mechanically. Rationale and day-to-day management -rules: `docs/schema/schema-command-registry.md`. +rules: `docs/schema/schema-command-registry.md`. It sits beside other +**reviewed inputs** under `internal/cli` (see Agent Schema contract) — same +organizational family, separate authority; do not merge with +`param_concepts.json` or promote any of them into Catalog declaration. ## Command framework declaration @@ -114,6 +117,23 @@ The Schema data flow is one way: └─ CI may dump Catalog via cmd_schema_catalog for jq gates / determinism ``` +**Reviewed inputs / 评审输入** (organizational family under `internal/cli`; +parallel peers, not one merged authority). These are assembly inputs only — +never Catalog declaration authority, never leaf `Contract` / `ProductDecl` +substitutes. Keep them side-by-side; do **not** fold one into another: + +| Input | Path | Owns | +|---|---|---| +| Command registry | `schema_command_registry/` (`registry.json` + `products/*.json`) | stable identity, primary CLI path, aliases, navigation | +| Param concepts | `param_concepts.json` (+ `.schema.json`) | argv synonym / concept dictionary (reduced to `param_aliases_generated.go`) | +| Exclusions | `schema_command_exclusions.go` | exact reviewed CLI paths excluded from Schema (non-empty reason) | +| Bindings audit | `schema_parameter_bindings.json` | `mapping_exclusions` / removals audit only (active bindings empty) | +| MCP pin | `schema_mcp_metadata.json` | pinned MCP tool-metadata baseline | + +Leaf declare (`Contract` / `ParamDecl` / `Safety` / `ProductDecl`) and the live +Cobra tree remain separate from this table: declare owns semantics; Cobra owns +executability and flags. + After binding there is no second identity source and no identity precedence winner. The binder must reject a missing/non-runnable Cobra path, an alias collision, and any native identity annotation that disagrees with the effective @@ -134,10 +154,9 @@ records, or use a previous Catalog JSON as a source. - CI tool: `cmd_schema_catalog` dumps an assembled Catalog for jq/determinism; it is **not** a `//go:generate` or committed delivery step. - `gen.go` only generates `param_aliases_generated.go`. -- Inputs: authored source groups (registry + ProductDecl/ContractFinal + MCP - metadata + parameter mapping audit (`schema_parameter_bindings.json`: - mapping_exclusions / removals; active bindings empty) + reviewed parameter - concepts + cobra tree). `schema_hints/` / `schema_agent_metadata/` must not +- Inputs: **reviewed inputs** (registry / param_concepts / exclusions / + bindings audit / MCP pin — see table above) + ProductDecl/ContractFinal + + live Cobra tree. `schema_hints/` / `schema_agent_metadata/` must not reappear. - Gates: `make generate-schema` (param aliases + assembly determinism), `check-generated-drift.sh`, `check-schema-catalog.sh`. diff --git a/docs/schema/schema-command-registry.md b/docs/schema/schema-command-registry.md index 72f0d869..4651d60d 100644 --- a/docs/schema/schema-command-registry.md +++ b/docs/schema/schema-command-registry.md @@ -18,6 +18,10 @@ Safety / Selection / 参数语义 → 写在叶上 Contract（`ContractDecl` / `ProductDecl`），不进 registry。 +同属 `internal/cli` 的 **评审输入**（`param_concepts.json`、exclusions、bindings +audit、MCP pin）与本目录并列、职责分开——不要合并进 registry，也不要把它们抬成 +Catalog 声明权威。总表见 `AGENTS.md`「Reviewed inputs / 评审输入」。 + ## 为什么不能删 **Cobra 不够当身份源。** Cobra 只保证「现在能不能跑、有哪些 flag」。它不负责稳定的 diff --git a/internal/cli/param_concepts.go b/internal/cli/param_concepts.go index c16ef113..cb040eeb 100644 --- a/internal/cli/param_concepts.go +++ b/internal/cli/param_concepts.go @@ -21,7 +21,8 @@ const paramConceptsSchemaRef = "./param_concepts.schema.json" // the sole source of equivalent flag spellings ("concepts") plus per-command // overrides. Build-time generators reduce these concepts against each command's // real Cobra flags; generated alias tables are downstream views and must never -// be read back here. +// be read back here. It is a reviewed input peer of schema_command_registry/ +// (argv synonyms vs identity) — keep them side-by-side; do not merge authorities. //go:embed param_concepts.json var embeddedParamConceptsJSON []byte diff --git a/internal/cli/schema_command_registry.go b/internal/cli/schema_command_registry.go index 2a349a6a..602550d8 100644 --- a/internal/cli/schema_command_registry.go +++ b/internal/cli/schema_command_registry.go @@ -25,7 +25,8 @@ const commandRegistrySchemaRef = "./schema_command_registry.schema.json" // schema_command_registry/ (registry.json + products/*.json) is the reviewed, // typed command registry and the sole source of stable command identity and // navigation. Catalog and generated metadata are downstream views and must -// never be read back here. +// never be read back here. Peer reviewed inputs (param_concepts, exclusions, +// bindings audit, MCP pin) stay separate — see AGENTS.md "Reviewed inputs". //go:embed schema_command_registry/registry.json var embeddedSchemaCommandRegistryEnvelopeJSON []byte