Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (77 loc) · 7.81 KB

AGENTS.md

File metadata and controls

96 lines (77 loc) · 7.81 KB
Raw

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)
  • 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, ~1060 lines). 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.8") 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).
docs/                 ← Supplementary docs.
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.
  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).