AGENTS.md · git:20260914.639f617 · 2026-09-14 · sha256 4489179add9253e2
AGENTS.md git:20260914.639f617A
Immutable. This exact content is served forever at /api/v1/blob/4489179add9253e2.
# AGENTS.md — majia-guanyuan
This file is read by:
- **OpenAI Codex** as project-level instructions (when cwd is inside this repo)
- **Hermes / gbrain** as a resolver file (alternative to `RESOLVER.md`)
- Other AGENTS.md-aware tools (e.g., **Cursor**, **Aider**)
## What this repo is
A Claude Code Skill for **Guandata BI (观远 BI)** — a tool-agnostic agent skill packaged so it works with **Claude Code**, **OpenClaw**, **Hermes/gbrain**, **Codex**, and any other agent that recognizes `SKILL.md` frontmatter.
**V3.0.0 重定位 — 「马甲实战版」**: after the official Guandata BI skill family went public on 2026-06-03 (`@guandata/guanskill`: guancli / guanvis / guanetl / guanwf / guands / guanmetric + per-skill AI skills; guanadmin / guanexport left the public family on 2026-06-04; guanmetric joined 2026-07-08, current family = 6), this skill was refactored ground-up from a self-built full-stack + fallback into a **battle-tested gain-layer on top of the official family**. The self-built HTTP client `scripts/guandata.py` (2789 lines) was retired and ~1600 lines of dead code removed. **Standard query / card / ETL / dataset CRUD all route to the official family**; this skill keeps only what the official DSL/commands can't reach.
Current structure — a router layer plus the hard-bone Parts:
- **🧭 Router layer** — standard query/card/ETL/dataset CRUD routed to the official family (`guancli` / `guanvis` / `guanetl` / `guanwf` / `guands` / `guanmetric`)
- **Part B** — ETL governance, write, delete (incl. SmartETL full-chain rewrite methodology and ExecPlan workflow)
- **Part C** — Custom chart HTML/CSS/JS injection & debugging on existing pages
- **Part C-12** — HTML application-style dashboard generation (descriptor patch linking selector → custom-chart dataView)
- **Store mobile scorecard** — franchise-owner phone scorecard (20 views, detectV, desensitized offline sample)
- **Part D** — V7 Page/Card publish pipeline (draft/release state-machine bypass + node-level silent traps + mobile phoneLayout ZIP-inject)
- **Part E** — SuperApp open-app development pipeline (reverse-engineering)
- **AI-native ADS design methodology** — philosophy-layer doc (governance vs rebuild judgment)
- **Restaurant-chain BI formula playbook** — 60+ SQL / RFM / Comp / DWD wide-table patterns
## Required reading order for any task
Before performing any work in this repo, always:
1. Read `SKILL.md` (the main doc, router and relevant Part sections). The `## 🧭 Part 选择` table at the top tells you which Part (router layer / B / C / C-12 / D / E / ADS / restaurant formulas) covers the user's request.
2. Read only the relevant Part section in detail. Don't load the whole SKILL.md unnecessarily — each Part points to its own `references/` playbook for the full tables.
3. Authentication is via `guancli auth login` (the whole official family shares one profile). This skill no longer reads `config.json` — credentials live in the guancli profile, not in this repo.
## Tool-specific entry points
| Tool | Install path | Entry |
|---|---|---|
| Claude Code | `~/.claude/skills/majia-guanyuan/` | `SKILL.md` |
| OpenClaw | `~/.openclaw/skills/majia-guanyuan/` or `<workspace>/skills/majia-guanyuan/` | `SKILL.md` |
| Codex | `~/.codex/skills/majia-guanyuan/` or `<repo>/.codex/skills/majia-guanyuan/` | `SKILL.md` (this `AGENTS.md` provides project-level instructions) |
| Hermes / gbrain | `<workspace>/skills/majia-guanyuan/` | `SKILL.md` (this `AGENTS.md` serves as the resolver pointer) |
| Other agents | Anywhere; see `manifest.json` and `SKILL.md` frontmatter | `SKILL.md` |
The `SKILL.md` frontmatter (`name: majia-guanyuan`, `description: ...`, `metadata.version: "3.1.12"`) is the universal handshake every agent should parse.
## Hard rules (do not violate)
- **Authentication is via `guancli auth login`** — the official family shares one profile; this skill no longer reads `config.json`. Do not commit any `config.json` (still in `.gitignore` defensively). `config.example.json` is kept as a legacy schema reference only.
- **Do not re-route standard work to self-built code** — standard query / card / ETL / dataset CRUD all go to the official family (`guancli` / `guanvis` / `guanetl` / `guanwf` / `guands` / `guanmetric`). This skill keeps only what the official DSL/commands can't reach (governance judgment, engine-level error playbooks, state-machine bypass, reverse-engineering, business formulas). The self-built `scripts/guandata.py` was retired in v3.0.0 (recover from git tag `v2.1.14` if ever needed).
- **Do not edit contributor originals in `references/`** — `etl-rewrite-original.md` + `custom-chart-playbook.md` (CTO Zhang Jin), `execplan-spec.md` + `agents-rule.md` (OpenAI Codex) are verbatim. Cite, don't edit. (The 马甲-distilled references are maintained docs and may be updated. `restaurant-bi-formulas/` moved to the standalone repo majia-huiyuan on 2026-07-12 — only a pointer README remains here.)
- **Do not strip version frontmatter** in `SKILL.md`. Bump `metadata.version` and update the version log section per the changelog convention when making changes.
- **Do not add tool-specific code paths** (e.g., `if claude_code: ...`) inside scripts or SKILL.md. The skill is tool-agnostic on purpose.
## Repo layout (one-liner per file)
SKILL.md ← Main agent doc (router layer + key rules; progressive disclosure).
AGENTS.md ← This file (Codex/Hermes/Cursor entry).
README.md ← Human-facing 中文 README.
README.en.md ← Human-facing English README.
CHANGELOG.md ← Full version history.
ATTRIBUTIONS.md ← Credits to contributors.
SECURITY.md ← Security policy.
LICENSE ← MIT.
llms.txt ← llms.txt index.
manifest.json ← Tool-agnostic metadata (name/version/compatibility/entry).
package.json ← npm package descriptor (scoped @supermajia).
config.example.json ← Legacy credential schema (auth now via `guancli auth login`).
.gitignore
.npmignore ← Defense-in-depth alongside package.json `files` whitelist.
bin/
install.js ← npm CLI: install/list/uninstall to 4 agent tools.
scripts/
inject_phone_layout.py ← Part D mobile phoneLayout ZIP-inject helper (stdlib only).
templates/ ← html-dashboard template pack (Part C-12).
examples/store-mobile-scorecard/ ← Offline desensitized mobile scorecard sample (V3.1.12).
docs/ ← Supplementary docs.
references/official-cli-compatibility.md ← Current official versions and migration boundaries.
references/ ← Progressive-disclosure playbooks (13 .md files + restaurant-bi-formulas/ pointer):
part-b-errors.md ← Part B 10-category error fixes detailed.
part-b-payload.md ← ETL payload schema deep-dive.
part-b-sdk.md ← v2→v3 bulk refactoring SDK.
part-b17-fullchain-rewrite.md ← Full B-17 SmartETL full-chain rewrite methodology.
part-c-payload-json.md ← C-3 payload_json troubleshooting.
part-c-html-dashboard.md ← Part C-12 HTML application-style dashboard methodology.
part-c-store-mobile-scorecard.md ← Franchise-owner mobile scorecard playbook (V3.1.12).
v7-page-card-publish-pipeline.md ← Part D v7 publish pipeline (16 sections).
part-e-superapp-pipeline.md ← Part E SuperApp open-app development pipeline.
ai-native-ads-design.md ← AI-native ADS design methodology (philosophy layer).
restaurant-bi-formulas/ ← POINTER ONLY — playbook moved to github.com/maojiebc/majia-huiyuan (公式库/).
execplan-spec.md ← OpenAI Codex ExecPlan full spec (contributor original).
agents-rule.md ← OpenAI Codex minimal scheduling rule (contributor original).
etl-rewrite-original.md ← CTO Zhang Jin SmartETL rewrite (contributor original).
custom-chart-playbook.md ← CTO Zhang Jin custom chart playbook (contributor original).
## Verification
After modifying anything, run a sanity check that no real credentials leak:
git ls-files | grep -E "config\.json$|\.cache/|columns_cache/"
The output must be empty (the only `config*` file tracked is `config.example.json`).