Develop wechat ai miniprograms

Develop WeChat Mini Programs

Deliver a working mini-program, not only source files. Keep the ordinary mini-program, AI Skill, cloud backend, factual data, and release configuration consistent and test them as separate layers before an end-to-end test.

Not every project uses every layer. Skip the AI Skill and CloudBase sections when the project has no skills/ directory or no backend; the project baseline, layered validation, privacy scan, and release stages apply to any mini-program.

Start with current facts

1. Inspect the existing project before planning. Read project.config.json, app.json, page-meta.json, skills/*/SKILL.md, skills/*/mcp.json, cloud configuration, and release artifacts.
2. Confirm the subject type, AppID, selected service category, certification state, cloud environment, DevTools version, and intended release stage.
3. Verify changing platform rules, prices, product capabilities, review requirements, and official APIs against current primary WeChat or Tencent sources. Do not rely on remembered pricing.
4. Separate factual claims into:
   • stable local facts from source code or CLI output;
   • current external facts verified from official sources;
   • inferences that must be labeled as such.

Route work to the right tool

Use the narrowest reliable interface:

Work	Preferred interface
Search, edit, validate, inspect JSON, run tests	Shell plus apply_patch
DevTools CLI preview, upload, CloudBase status	WeChat DevTools CLI
Native WeChat DevTools UI, AI compile panel, QR/login panel	computer-use:computer-use through node_repl
Official documentation and ordinary web pages	Web browsing or chrome:control-chrome
WeChat public-platform backend when Chrome automation works	chrome:control-chrome
QR scans, phone confirmations, CAPTCHA, blocked admin UI	User handoff

Read references/tool-routing.md before any GUI work. Never use Computer Use for Chrome when the Chrome skill is available. If the WeChat admin backend resists automation, stop clicking blindly and give the user exact copy/paste or click instructions.

Follow the delivery workflow

1. Define the first useful scenario

Choose one bounded, decision-oriented scenario. Prefer requests with explicit inputs and structured outputs, such as finding, comparing, calculating, checking availability, or assessing risk. Avoid an unfocused directory of content.

Define:

• user utterances that should invoke the Skill;
• utterances that should not invoke it;
• required filters and identifiers;
• which facts are static, sourced, predicted, or live;
• safety boundaries and fallback behavior.

2. Build the ordinary mini-program

Implement a useful non-AI path first: home/list, filtering, detail, source attribution, loading, empty, and failure states. Keep a user-visible path to the same entities returned by the AI Skill.

Use subpackages when they clarify boundaries. Include the skills directory in the uploaded code package. Keep generated validation artifacts out of the package with packOptions.ignore and watch ignores.

3. Build the AI Skill contract

Create one Skill directory per coherent capability:

skills/<skill>/
├── SKILL.md
├── mcp.json
├── index.js
├── apis/
├── components/
├── data/ or adapters/
└── utils/

Register each atomic API with wx.modelContext.registerAPI. Make API names, mcp.json, index.js, and implementation filenames agree exactly.

Design atomic APIs around model decisions:

1. Search or list candidates.
2. Fetch detail using an ID returned by search.
3. Compare two or three known IDs only when the user asks.

Return both a short model-facing message and structuredContent. Use stable IDs; never ask the model to invent identifiers from names. Put explicit routing rules, negative scope, relative-date conversion, and safety constraints in the Skill instructions and API descriptions.

Read references/ai-skill-sop.md when creating or changing a Skill contract.

4. Add current data through a backend

Treat the mini-program code as the frontend. Use CloudBase or another compliant backend for secrets, third-party requests, dynamic data, and server-side normalization.

For CloudBase:

1. Create or select an environment.
2. Write the environment ID to every runtime config that actually uses it.
3. Initialize wx.cloud once.
4. Deploy the cloud function and install dependencies in the cloud.
5. Verify function status and timeout with the CLI or console.
6. Call it from both the ordinary page path and the AI Skill adapter.
7. Return an explicit unavailable state when the upstream service fails or a date is outside the supported window. Never fabricate fresh data.

Use a server-side proxy when a third-party domain cannot satisfy WeChat request-domain requirements. Do not expose AppSecret or third-party credentials in the mini-program package.

Read references/build-and-cloud-sop.md for the complete implementation sequence.

5. Validate in layers

Do not jump directly to natural-language chat.

1. Run syntax and local tests.
2. Run scripts/preflight.mjs <project> from this Skill repository. It checks any mini-program; add --strict-privacy before a release build and --require-skills when the project is supposed to declare an AI Skill. Resolve every error, judge every warning, and manually verify every info finding.
3. Run the current official or project-provided Skill validator.
4. Execute every atomic API directly with representative valid, empty, invalid-ID, and out-of-window inputs.
5. Inspect atomic UI components for overflow and truncation.
6. Compile the ordinary mini-program and test the page path.
7. Switch DevTools to AI compile mode and send a natural-language prompt.
8. Confirm every proposed API call and inspect parameters, structured output, final answer, and mini-program handoff.

Record exact evidence: validator counts, build stage, API inputs, returned IDs, upstream data timestamps, cloud function status, package size, and upload version.

6. Release in distinct stages

Treat these as different states:

local source -> preview -> uploaded development version -> experience version
-> submitted for review -> approved -> published

Uploading a development version is not public release. Do not claim the mini-program is online until the backend shows a published version.

Before upload:

• check certification, filing, category, privacy declaration, and current subject restrictions;
• scan for privacy-sensitive APIs and ensure every call is intentional;
• remove convenience-only privacy APIs when a plain UI alternative is sufficient;
• verify the cloud function is deployed independently of the frontend upload;
• increment the version and write a precise description.

After upload, have the user configure or scan the experience version when backend automation is unavailable. Run a phone regression before review. Read references/release-sop.md.

Diagnose by layer

When a test fails, identify the first broken boundary:

1. DevTools account and compile mode.
2. AI model routing.
3. Atomic API registration and schema.
4. API implementation.
5. Cloud function invocation.
6. Upstream data provider.
7. Atomic component rendering.
8. Page handoff.
9. Admin review configuration.

Do not rewrite working Skill logic because the DevTools account is logged out. Do not change cloud code because only the admin backend is blocking a button. Read references/troubleshooting.md for observed symptoms and proven checks.

Preserve operating evidence

Keep machine-readable results outside the upload package. A practical artifact folder contains:

• validator report;
• direct API execution results;
• component render snapshots;
• end-to-end test notes;
• upload result and package sizes;
• a short release report listing passed checks, limitations, and next stage.

Never store QR codes, access tokens, AppSecret, personal identity materials, or cloud credentials in the repository.