Mokhai - Agent Readiness Kit
| 开发者 | mokhaled |
|---|---|
| 更新时间 | 2026年7月13日 16:26 |
| PHP版本: | 7.4 及以上 |
| WordPress版本: | 7.0 |
| 版权: | GPL-2.0-or-later |
| 版权网址: | 版权信息 |
详情介绍:
Mokhai is an open-source WordPress plugin that turns your site into a first-class citizen of the AI-agent web — readable today, actionable next. A single Context Profile (configured once under Tools → Context) is the source of truth for every agent-facing surface — what's exposed, how it's served, and how it's scored.
The core move: Mokhai publishes a Markdown version of every page on your site. When an AI assistant fetches a typical WordPress page it receives 50–100 KB of theme markup — menus, sliders, scripts — with your actual content buried inside. Mokhai gives every public URL a clean Markdown twin (
/about-us.md) that is 4–8 KB of pure content, and pushes those Markdown versions into your /llms.txt index: every entry links straight to the page's .md form and carries a per-page description, so an agent reading your index gets a curated map of your content AND the readable version of each page in one hop. That pipeline — content → Markdown twin → described llms.txt entry — is what the rest of the plugin audits, scores, and advertises.
Mokhai ships seven coherent modules, all driven by one Context Profile:
- Markdown Views — publishes a clean Markdown version of every public URL, with three URL forms (
.mdpath,?format=mdquery,Accept: text/markdowncontent negotiation) and uniform 404 on denial. Per-post cache with content-hash invalidation, Gutenberg sidebar preview, WP-CLI command, REST endpoint for admin tooling. - LLMs Index —
/llms.txtgenerator that publishes a discovery surface for AI agents, where every entry links to the page's Markdown version and carries a description — curated by you or drafted by an optional LLM-powered pass from the post content. Conflict detection againstrobots.txt, plus an editorial entries admin UI for adding non-WordPress URLs. - Context Score — 0–100 readiness audit across seven weighted sub-scores (discoverability, description coverage, schema coverage, exposure safety, integration health, Markdown conversion quality, multi-channel discovery), surfaced in an admin page, Site Health, and
wp mokhai context-score recompute. Includes an optional LLM-generated narrative (with a rule-based fallback) explaining the score and the highest-leverage fixes. - Schema Coordination — detects whether your SEO plugin already emits JSON-LD; if not, optionally emits a native WebSite + Organization + per-content schema set so the schema sub-score is achievable without a third-party SEO plugin. Defers gracefully when an SEO plugin is already covering the surface.
- AI Assistant Preview — an admin pane that shows any post exactly as an AI assistant consumes it: raw HTML, the Markdown View, and the live
/llms.txtline side by side, plus an on-demand "sample AI summary" so you can sanity-check what an agent would say about the page. - Agent Abilities + MCP — exposes core plugin operations (audit run, profile read, exposure toggle,
/llms.txtregenerate, Markdown preview) through the WordPress Abilities API, and surfaces them to MCP clients via the WordPress MCP adapter. Every ability ismanage_options-gated. - Multi-channel discovery — a seventh Context Score sub-score crediting additional agent-discovery surfaces (
ai.txt,/.well-known/declarations, OpenAPI) beyond/llms.txt, so a site running several discovery channels scores higher than one running only one.
屏幕截图:
常见问题:
What is llms.txt and why should I care?
AI assistants like ChatGPT, Claude, and Perplexity increasingly visit websites to answer questions for their users. Most WordPress themes serve them the same heavy HTML built for humans — menus, sliders, widgets — and the actual content gets lost in the noise. llms.txt is a simple convention: a plain-text file at your site's root (like robots.txt, but for content) that tells AI assistants what your site is about and where to find your best pages. Mokhai generates and maintains it for you, alongside clean Markdown versions of your pages that agents can actually read. If AI assistants are answering questions in your topic area, this determines whether your site is the source they cite — or the one they skip.
Does Mokhai require an AI API key?
No. Every deterministic surface (Markdown Views, /llms.txt floor, rule-based Context Score narrative, gap-fill JSON-LD emission) runs fully locally with no external calls. Modules that benefit from an LLM (the Markdown cleanup pass, /llms.txt entry-description drafting, the LLM-narrated Context Score) require the optional WP AI Client to be configured, but each is independently toggleable and not load-bearing for the core agent-readiness contract.
How does Mokhai interact with my SEO plugin?
For JSON-LD: when an SEO plugin (Yoast, Rank Math, AIOSEO, The SEO Framework) is active, Mokhai emits nothing competing — schema is theirs. When no SEO plugin is emitting JSON-LD, you can optionally enable Mokhai's native gap-fill emission from the Context Profile. For noindex: Mokhai auto-detects per-post noindex from Yoast, Rank Math, and AIOSEO and drops the post from agent surfaces. Use the mokhai_post_is_noindexed filter to add support for additional sources.
How is this different from existing /llms.txt plugins?
/llms.txt is one surface among several. Mokhai ships the integrated reading layer (Markdown views), the discovery layer (/llms.txt with editorial entries and LLM-powered descriptions), the audit layer (Context Score across seven sub-scores), and the schema coordination layer as a single coherent unit driven by one Context Profile. Most existing plugins target one of these surfaces in isolation; Mokhai treats them as a coordinated stack.
What's on the roadmap?
v0.5.0 is the public-launch baseline: Markdown Views, /llms.txt, the Context Score, the AI Assistant Preview pane, and the WordPress Abilities API + MCP integration. Looking ahead: agent-activity analytics (see which AI agents visit your site, not just optimize for them), a fuller agent-actionable layer (callable tools via WebMCP / navigator.modelContext), and a richer /.well-known/llms-policy.json policy-declaration surface.
更新日志:
0.6.0 — 2026-07-13
Feature release: markdown that survives hard caching, and discovery that survives AI content extraction. No migration — safe in-place upgrade; all new behaviour is driven by two new Context Profile keys with safe defaults.
New
- Static Markdown mirror — Mokhai can now write each exposed page's Markdown version to a real file under
wp-content/uploads/mokhai/md/, served statically by any host with no PHP involved. This keeps agent-readable content available on sites behind hard full-page caches or static exports, where the request-time.mdroute may never reach PHP. Files follow the full content lifecycle: regenerated on save, moved on slug change, deleted on trash or exposure revoke, with a daily backstop sync and full cleanup on deactivation/uninstall. (#283) - Hard-cache detection — the mirror activates automatically only when a hard page cache is detected, across both layers: caching plugins (WP Rocket, W3TC, WP Super Cache, LiteSpeed, Cache Enabler, and more) and host/CDN caches (Kinsta, Cloudflare, Varnish) via a self-probe of the site's own response headers. Override with the
static_md_modeprofile key (auto/on/off, defaultauto). (#283) - In-content discovery link — an invisible, accessibility-neutral link to the page's Markdown version is added inside the content of exposable singular views. Empirical testing showed AI fetchers (Claude, ChatGPT) strip
<head>alternate links and HTTPLinkheaders before the model sees the page — an in-content link is the only discovery signal that survives, and because it's part of the page HTML it also survives inside cached copies. Disable with thecontent_link_enabledprofile key (default on). (#283)
- wp.org listing copy now leads with the markdown-publishing capability — what the plugin does, stated first. (#282, #284)
mokhai scheme. No new features ship in this release.
- Identifier rename — internal scheme — the PHP namespace (
Mokhai\), WP-CLI root (wp mokhai), REST namespace (mokhai/v1), WordPress Abilities category (mokhai), option/meta/table keys (mokhai_*), and all hook names (mokhai_*) now match the plugin's public name. The previousai-readiness-kit,agentready, andai_readiness_kitidentifiers are gone. - NO automatic migration — option keys, post meta, and the Markdown cache table were all stored under
agentready_*orai_readiness_kit_*names in releases prior to 0.5.0. A pre-0.5.0 install re-initialises its settings on first page-load after upgrade; re-configure the Context Profile under Tools → Context (Exposed CPTs, Exposed statuses, and toggles). The Markdown cache rebuilds on demand from the first request to each.mdURL. - Branding — refreshed Plugin Directory icon and banner assets align with the Mokhai identity established in 0.3.2.
mokhai-agent-readiness-kit). This release is launch housekeeping — no functional change, no migration:
- Refreshed Plugin Directory assets — new banner, icon, and screenshots.
- Polished readme copy for the public listing.
- Repository links consolidated under the
mokhai-agent-readiness-kitname (Plugin URI, package metadata). REST routes, WP-CLI commands, abilities, option keys, and all stored data are unchanged — existing installs upgrade in place with no action required.
mokhai-agent-readiness-kit). wp.org plugin review rejected "Agentable" as colliding with existing third-party projects and required a name and slug that are clearly ours, with a distinctive leading term. "Mokhai" satisfies that. REST, WP-CLI, abilities, option keys, and all stored data are unchanged — existing installs upgrade with no migration. (#259)
Also ships the following changes that landed on main since 0.3.1:
/llms.txtnow warns in the admin when a staticrobots.txtblocks the/llms.txtreference, so the conflict isn't silent. (#245, #250)/llms.txtemits the site header on an otherwise-empty index instead of returning a blank body. (#244, #249)- WooCommerce transactional pages (cart, checkout, account) are now excluded from the
/llms.txtindex. (#243, #248) - Markdown Views falls back to the raw
post_titlewhen a filtered title comes back empty, so titled posts no longer render untitled. (#242, #247) - Markdown URL mapper now guards the root / front-page URL, fixing mapping on the home route. (#241, #246)
agentable). The previous "AgentReady" brand collided with an existing third party (agentready.org), so the plugin is renamed to a distinct, ownable name that also fits the roadmap — sites readable today, actionable next. REST, WP-CLI, abilities, and stored data keys are unchanged, so existing installs upgrade with no migration. Also makes root-served-file detection (llms.txt, ai.txt, .well-known/*) subdirectory-install aware via get_home_path() instead of assuming the install root is the web root. (#230)
0.3.0 — 2026-06-12
Polish release. Refinements surfaced through a full live UX walkthrough of the v0.2.0 admin surfaces — score-narrative correctness, clearer labels, and a more discoverable plugin. Also renamed to "AgentReady – AI Readiness Kit"; REST, WP-CLI, and stored data keys are unchanged. (#224)
Improved
- Multi-channel discovery is reachable at 100 for plugin-only sites — the four plugin-served discovery channels (
/llms.txt,ai.txt,/.well-known/ai-layer,/.well-known/llms-policy.json) now score 100 on their own; OpenAPI is credited as a bonus channel for API-exposing sites rather than capping the score at 80. (#212) - "Content readability" renamed to "Description coverage" across the Context Score page, Site Health, and readme, to match what the sub-score actually measures (curated
/llms.txtdescription coverage). Internal key unchanged. (#211) - Plugin is now findable in wp-admin — the Tools entries read "AI Readiness — Context" / "AI Readiness — Score", and the Plugins list carries a "Settings" link to the Context Profile. (#207)
- Quality floor for auto-descriptions — near-empty posts are skipped (distinct "skipped" status) instead of padded with filler like "Title is available at URL."; threshold filterable via
agentready_description_min_content_chars. (#214)
- Schema-coverage narrative no longer reads "No structured data was detected" beside a 100/100 score when native JSON-LD emission is on; the stale "future release" fix advice is replaced with the reachable Context Profile action. (#208)
- Content-readability fix advice now points to the Descriptions tab "Regenerate stale descriptions" GUI path and stops telling users to enable a setting that is already on. (#209)
- The multi-channel discovery sub-score renders a human label instead of the raw
multi_channel_discoverykey. (#210) - AI Assistant Preview shows an explicit "no content" message for empty posts instead of blank dark panes. (#213)
- Relative-time copy uses proper
_n()plural forms ("1 minute ago" / "5 minutes ago"); excluded posts in the Descriptions table are labelled "excluded" and the intro copy matches. (#215)
- AI Assistant Preview pane — view any post as an AI assistant consumes it (raw HTML / Markdown View / live
/llms.txtline, side by side) with an on-demand synchronous "sample AI summary". No cron; degrades gracefully without an AI provider. (#45) - WordPress Abilities API + MCP — five
manage_options-gated abilities (audit-run, profile-read, profile-set-exposure, llms-txt-regenerate, md-view-preview) exposed via corewp-abilities/v1, and reachable by MCP clients through the WordPress MCP adapter when installed. (#21, #131) - Multi-channel discovery sub-score — Context Score gains a seventh sub-score crediting agent-discovery surfaces beyond
/llms.txt(ai.txt,/.well-known/declarations, OpenAPI), with a filterable sibling-provider registry. Discoverability re-weighted 20 → 10 to fund it; total stays 100. (#22)
- Tools → Context rebuilt as a single Card + TabPanel single-page admin, aligned with the WP AI Client / OpenAI Connector design system, with REST write controllers for the Context Profile and editorial entries. (#142)
- Context Score reason strings are now fully translatable via reason codes, and the sub-score copy across the admin UI and the LLM narrative prompt derives from a single source of truth (
Engine::WEIGHTS). (#137, #139, #140)
- JSON-LD is now emitted without
esc_html()(angle brackets escaped viaJSON_HEX_TAG), so the structured-data payload validates in every standards-compliant validator. (#118) - Stale past-timestamp cron events are cleared before re-scheduling across all four schedulers (
/llms.txtrecompute, Context Score recompute, Markdown cleanup, description generation) — fixes "stuck pending forever" on sites where wp-cron sat stale. (#115, #120, #121) - The Markdown cleanup allowlist now preserves word boundaries at block edges, so headings and paragraphs adjacent to block tags are no longer dropped by the no-hallucination guard. (#135)
- Orphaned shortcodes are stripped from both the deterministic Markdown walker and
/llms.txtentry descriptions via a shared helper. (#145, #147) /llms.txtnow recomposes when a post's description changes, and carries a generator-version staleness signal so out-of-date descriptions are detectable. (#149, #151)package.jsonversion now tracks the plugin version (was drifting at 0.1.0). (#113)
/llms.txt output.
Fixes
/llms.txtregen now fires reliably after Context Profile saves on sites where wp-cron sits stale (e.g. wp-env without traffic, any site where cron failed for a window).Service::schedule_regen()now clears stale past-timestamp events before scheduling a fresh one. (#103)Schema_Emitternow emits per-content JSON-LD for custom CPTs. Built-inpostmaps toArticle;pageand every other CPT (including custom ones likelesson,product,recipe) map toWebPageby default. Adds anagentready_schema_type_for_cptfilter for plugin/theme authors to specialize. Honors'Article'/'WebPage'/null(suppress) in v0.1.1; full custom-@typesupport lands in v0.1.2. (#104)/llms.txtentry links now point at the.mdform when Markdown Views is enabled — AI agents fetch a 4–8 KB Markdown body instead of the 50–100 KB HTML page. Pretty permalinks use the<slug>.mdshape; plain permalinks fall through to?format=md. Idempotent: URLs already in either form are returned unchanged. Whenmarkdown_views_enabledis false, the canonical permalink is preserved. (#105)- HTML entities (
’,&,",—, etc.) no longer leak into the plain-text/llms.txtbody. WordPress'swptexturizefilter HTML-encodes typographic characters; the composer now decodes them at the bottom of the escape pipeline so every text surface (site name, tagline, section label, entry title, description) is clean. (#106)
- Deterministic HTML → Markdown rendering with three URL forms (path
.md, query?format=md,Accept: text/markdown) - Custom cache table with content-hash invalidation and walker-version lazy revalidation
- Gutenberg sidebar panel for in-editor preview
wp ai-readiness-kit md previewWP-CLI command with--format=wrapped,--show-meta,--bypass-exposure- REST endpoint for admin tooling at
/wp-json/ai-readiness-kit/v1/markdown-views/preview - LLM cleanup pass with safety guard (rate-limited, opt-in via Context Profile)
- Admin UI for cleanup approval workflow
/llms.txtgenerator with Context Profile-driven inclusion rules- Conflict detection against
robots.txtwith admin notice - Editorial entries admin UI for curated non-WordPress URLs
- LLM-powered per-entry descriptions (Phase A engine + Phase B admin UI)
- WP-CLI:
wp ai-readiness-kit llms-txt {status,regen,preview}
- Six weighted sub-scores (discoverability 20, content readability 15, schema coverage 10, exposure safety 15, integration health 15, Markdown conversion quality 25) → 0–100 composite
- Admin page at Tools → Context Score with full sub-score breakdown
- Site Health integration with headline score and highest-leverage fix surfacing
- REST endpoint for programmatic access
- LLM-narrated explanation with rule-based fallback
- WP-CLI:
wp ai-readiness-kit context-score recompute
- SEO plugin detection (Yoast, Rank Math, AIOSEO, The SEO Framework)
- Native gap-fill JSON-LD emitter (WebSite + Organization + per-content) gated behind a Context Profile toggle, credited in Context Score's schema sub-score
- Layered CI: PHPCS (WordPress + WordPressVIPMinimum) + Plugin Check + PHPUnit + PHPStan level 5
requires_wp/requires_phpruntime gate with admin-notice degradation- Translation policy documented: managed via wp.org under slug
agentable