Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ npx tsx --test <file> # Run a single test file
- Local PC service: `deploy/install-local.ps1` (Windows Scheduled Task) or `deploy/install-local.sh` (launchd / systemd --user), loopback only
- Private server: `Dockerfile` + `deploy/docker-compose.yml` + `deploy/.env.example`

**Docs layout**: `README.md` is a short landing page modelled on xiaoya-alist: one screenshot, the two install commands (`npx add-mcp ...` for MCP config, `npx skills add ...` for the Skill), five example requests, and links. Keep it under ~60 lines; do not add sections back. Everything else lives behind links: `deploy/README.md` (persistent service, Docker/NAS, client config shapes, env vars, upgrade/uninstall, troubleshooting, security), `docs/web.md` (web version), `docs/tools.md` (tool table). `add-mcp` (third-party) was verified 2026-11-02 to write stdio `env` and HTTP `headers` correctly for Claude Code, Cursor and OpenCode, preserving JSONC comments; it needs an interactive terminal unless `-a <agent> -y` is given.
**Docs layout**: `README.md` is the landing page: what it does, then a two-command install (`npx add-mcp ...` for the MCP config, `npx skills add ...` for the Skill), one short section for the persistent service, upgrade/uninstall, and the web version folded in `<details>`. Keep it short. `deploy/README.md` holds the reference material: script parameters, Docker steps, every client config shape, env vars and troubleshooting. Do not move parameter tables, Docker steps or env var references back into the root README. `add-mcp` (third-party) was verified 2026-11-02 to write stdio `env` and HTTP `headers` correctly for Claude Code, Cursor and OpenCode, preserving JSONC comments; it needs an interactive terminal unless `-a <agent> -y` is given.

**User-specific values in docs**: never write a concrete gateway IP, server IP, token, API key or passcode into anything a user copies (config blocks, commands, prompts to paste into an AI Agent, `.env.example`). Use placeholders such as `http://<网关 IP>`, `<服务器 IP>`, `<访问密码>`, `<登录码>`; a concrete value may appear only in prose as "例如 …". `.env.example` files leave required values empty so a forgotten field fails loudly instead of pointing at someone else's network.

Expand All @@ -82,7 +82,7 @@ Client config shapes differ. `mcpServers` (`command` string + `env`) is the prim

**Client-agnostic docs**: this project targets any MCP host, not one client. Never make a single client the default voice or assume its config schema; a concrete client is fine only as a short labelled example alongside the generic form.

**Tool count**: 32 tools registered in `src/mcp/tools/` (auth 3, device 3, graph 13 + graph draft 6, variable 6, misc 1). Keep the tool table in `docs/tools.md` in sync when adding or removing one.
**Tool count**: 32 tools registered in `src/mcp/tools/` (auth 3, device 3, graph 13 + graph draft 6, variable 6, misc 1). Keep the README tool table in sync when adding or removing one.

**Output size**: tools return compact output by default. `mijia_get_graph` and `mijia_get_device` default to `detail="summary"`; pass `detail="full"` or `node_ids` for full objects. Prefer the compact rule text format (`docs/rule-text-format.md`, parser in `src/core/tools/ruleText.ts`): `mijia_get_graph format="text"` or `focus` to read, `mijia_patch_graph` with `add`/`replace`/`note`/`variables` to edit in one call, `mijia_put_graph_text` for whole-file sync (`scripts/rules.mjs`). Any change to the text format must keep the JSON -> text -> JSON round trip lossless; `nodesToText` falls back to a per-node `+{diff}` or `raw` line rather than dropping data. `mijia_update_graph` (full replace) is kept for compatibility. Card layout lives in `src/core/tools/layout.ts` (`arrangeNodes`: layered layout for new rules, incremental placement that never moves existing cards, collision re-check; `layoutReport` for overlap/edge-through-card/crossing estimates). `graphHash` ignores `cfg.pos` by design; position changes are tracked separately by `layoutHash` / `positionChangedIds` (`src/core/tools/graphHash.ts`), so a position-only patch is saved and guarded by `baseLayoutHash`. Never make `graphHash` include coordinates. Gateway reads go through `src/core/tools/gatewayCache.ts`: device list cached 30 s (forced refresh when a did/name is missing), rule scans cached by `getGraphList` `lastUpdateTime`; call `invalidateGraph` after any write/delete, and use `scanGraphs({fresh:true})` for safety checks such as variable deletion. Independent gateway requests should be issued with `Promise.all`; the gateway handles concurrent requests. Both validators accept a saved rule `id`; `mijia_validate_graph_capabilities` reports problems via `valid=false`, not `isError`.

Expand Down
Loading