# cindy-official-plugins **Repository Path**: ToolStorage/cindy-official-plugins ## Basic Information - **Project Name**: cindy-official-plugins - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-28 - **Last Updated**: 2026-08-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Cindy Official Plugins

English · 简体中文

🌐 International | Mainland China · ⬇️ Download | 下载

This is the source for every official plugin (Ghost) in the [Cindy](https://github.com/makecindy/cindy) plugin marketplace. - **Using Cindy?** You don't need this repository — open **Plugins** in the Cindy client and install any generally available plugin below with one click (rows marked "targeted rollout" are still being staged and not yet installable for everyone). - **Want to build a plugin?** This repository accepts external contributions. Once your PR merges to `main`, the package is submitted automatically to the CN and Global review queues. It becomes visible in a region only after that region approves it. Start at [Submit your plugin](#submit-your-plugin). ## Plugins | | Plugin | Directory | Description | | --- | --- | --- | --- | |

| Web Search | [`cindy-web-search`](./cindy-web-search) | Public web search (Cindy AI by default; optional user-provided Brave / Tavily key) | |

| World Bank Open Data | [`world-bank-open-data`](./world-bank-open-data) | Public country, economic, social, and development indicators with no API key; staged rollout | |

| Gmail | [`google-gmail`](./google-gmail) | Search, read, and organize Gmail, create drafts, and send messages; host-managed OAuth | |

| iCloud Mail | [`icloud-mail`](./icloud-mail) | Cindy stores the app-specific password securely; manage iCloud Mail via IMAP/SMTP on demand | |

| QQ Mail | [`qq-mail`](./qq-mail) | Cindy stores the authorization code securely; search, read, organize, and send via IMAP/SMTP on demand | |

| Yahoo Mail | [`yahoo-mail`](./yahoo-mail) | Cindy stores the app password securely; manage and send Yahoo Mail via IMAP/SMTP on demand | |

| iOS Simulator | [`ios-simulator`](./ios-simulator) | Host-owned embedded workflow; Host-authorized fallback hands off the exact task and device to a named external workflow; staged rollout | |

| X Manager | [`x-manager`](./x-manager) | Search X (Twitter) and post to it — xAI x_search with Grok-subscription / API-key fallback, posting via the official X API v2; currently in a targeted rollout | Missing a plugin you want? [Propose it](#submit-your-plugin) — or build it yourself and submit it here. ## Submit your plugin The full path from idea to marketplace: 1. **Idea** — check the table above for overlap first. Official plugins avoid duplicating each other's scenarios; same-provider product families (Gmail / Drive / Calendar) and same-protocol different providers (163 / iCloud / QQ mail) are fine, but a second generic web search is not. 2. **Align** — open a [new plugin proposal](https://github.com/makecindy/cindy-official-plugins/issues/new?template=new_plugin_proposal.yml) describing the scenario, boundaries, and required capabilities (network hosts, credentials, Node runtime). Wait for a maintainer ack before writing code — it keeps you from building something that overlaps or won't be accepted. 3. **Build** — in a Cindy conversation, say "help me build a plugin" to get the complete authoring manual (`ghost_forge_guide`: every `ghost.json` field, slots, the `cindy.send` pipe API, packaging). Scaffold with `ghost_forge_scaffold` or copy the layout of any plugin here. Import the directory or a packaged `.cindy` into a dev environment to verify. 4. **Open a PR** — title `feat(): …`; bump `ghost.json.version`; add the `provisioning.json` entry; complete four-language locales (`zh-CN` / `en` / `ja` / `ko`); sign off every commit (`git commit -s`, [DCO](./DCO)). Details in [`CONTRIBUTING.md`](./CONTRIBUTING.md). 5. **Review** — CI validates each manifest and the Server/Desktop delivery limits within this repository, checks localization / provisioning, and dry-runs the exact package; automated review enforces the full ruleset in [`.greptile/rules.md`](./.greptile/rules.md); a maintainer reviews against the same [review standards](#review-standards). Walk through the self-check list below before requesting review. 6. **Submit and approve** — after merge to `main`, the CN and Global workflows submit the real package through Plugin Platform. Each region reviews its own pending release; only an approved release becomes available to compatible clients. Rejection leaves the previous approved release in service. ## Review standards Every official plugin is installed by real users who carry its security and experience risk, so review is strict by design. Four hard principles: 1. **Pure sandbox by default, capabilities declared explicitly.** Regular plugins run in Cindy's isolated sandbox and may only use the network allowlist and host channels declared in `ghost.json`. Official plugins that genuinely need the Node Runtime must explicitly declare the `node` slot, a fixed entry point, and a minimal child-process boundary. 2. **Clear secret ownership.** Ordinary API tokens are stored through the host's write-only `/secrets` channel. When a Node plugin needs plaintext credentials, use `node.secretBindings` to restrict them to specific Worker methods, injected transiently by the host — never passing through the browser `main.js`, Agent parameters, or logs. If an official third-party runtime manages account credentials itself (e.g. TapTap Maker), the plugin only hands credentials to the runtime; it does not copy them into Cindy KV/Secret or keep plaintext in logs or page state. 3. **Tool descriptions are contracts.** Each tool's `description` in `ghost.json` is the usage manual the Agent reads; it must accurately describe behavioral boundaries (what it does, what it doesn't, what it returns, and any side effects). 4. **Error messages speak human.** User-facing errors must be actionable (e.g. 401 → tell the user where to fill in the token), not raw HTTP status codes. ### Self-check before requesting review - [ ] `ghost.json` declares only the network hosts and host channels actually used; no `node` slot unless genuinely required - [ ] Node plugins: explicit `node` slot, fixed entry, minimal child-process boundary; `node/worker.cjs` is an esbuild artifact rebuilt from `src/` - [ ] No plaintext credentials anywhere: tokens go through the write-only `/secrets` channel or `node.secretBindings`; never through `main.js`, Agent parameters, logs, KV, or page state - [ ] Tools with irreversible external side effects (send / post / delete) distinguish "definitely not executed / definitely executed / unknown" in every failure path, and never suggest a blind retry on "unknown" - [ ] Every tool `description` matches actual behavior — capabilities, limits, return values, side effects - [ ] User-facing errors are actionable; no raw status codes or stack traces - [ ] Four-language locales complete; `node --test .tests/localization.test.mjs` passes - [ ] If `minCindyVersion` is added or raised, the packaged `.cindy` was installed on that exact Cindy version and the result is recorded in the PR; lowering or removing it requires maintainer review - [ ] `ghost.json.version` bumped; `provisioning.json` entry present with an audience decision stated in the PR - [ ] No credentials, real user data, `node_modules`, or unrelated generated files in the diff; fixtures use placeholder domains (`example.test`) - [ ] Bundled dependency changes reflected in `THIRD-PARTY-LICENSES.txt` - [ ] Every commit signed off (`git commit -s`) The complete machine-and-human review contract lives in [`.greptile/rules.md`](./.greptile/rules.md) — automated review enforces it on every PR, and maintainers apply the same standards. ## Repository layout Each subdirectory is the complete source of one plugin ("consciousness pack"): ``` cindy-github/ ├── ghost.json # Identity card: plugin id, description, tool declarations, network & secret declarations ├── main.js # Entry point: plugin logic running in the sandbox ├── settings.html # (optional) Settings page, e.g. for pasting an API token ├── settings.js └── assets/ # (optional) Static assets such as icons cindy-art/ ├── ghost.json ├── main.js └── panel.* # (optional) Custom panel UI ``` `provisioning.json` at the repository root declares, per plugin, which audience receives it as a built-in. Every plugin directory has a corresponding entry, so adding a plugin means adding a row there too. The `.tests/` directory holds plugin behavior tests; `*.test.mjs` files run on Node's built-in test runner (`node --test .tests/.test.mjs`) and back both the PR verification workflow and the publish gates. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the verification workflow. Official plugins are wired into host-driven `zh-CN / en / ja / ko` locale resources; see [`docs/localization.md`](./docs/localization.md) for language selection and the English-fallback contract. The shared resources cover the catalog layer; self-rendered settings pages are being migrated independently to the same host-driven locale contract, while runtime error copy is still primarily Chinese-only. ## Automated submission and review In one sentence: **merging to `main` submits automatically to both regions; public availability still requires Plugin Platform approval in each region.** Two workflows publish, and both only from `main`: - [`publish-cindy-plugins.yml`](./.github/workflows/publish-cindy-plugins.yml) — `Publish Cindy Plugins (CN)` - [`publish-cindy-plugins-global.yml`](./.github/workflows/publish-cindy-plugins-global.yml) — `Publish Cindy Plugins (Global)` Both are active and use the same submission flow: - A regular push to `main` submits only the plugin directories changed in that push. A push that touches no plugin directory submits nothing. - Manually running a workflow from the Actions page submits all current plugins in full — for initial setup after a repository migration or an explicit re-submission. - Each workflow uses GitHub Actions OIDC (audience `cindy-plugin`) to call its protected Plugin Platform endpoint. Platform creates a pending release and notifies reviewers; it does not bypass review by calling Plugin Server directly. - The two regions package, submit, review, and report independently. Failure or rejection in one region does not affect the other. There is no development publishing workflow. After approval, compatible clients receive that release; clients below its `minCindyVersion` continue to receive the newest older compatible release, when one exists. When changing plugin content you must bump `ghost.json.version` in the same change. The new `major.minor.patch` SemVer must be greater than the version on `main`; otherwise CI blocks the pull request before Server submission. ## Local development The complete plugin-authoring contract (all `ghost.json` fields, slots, the `cindy.send` pipe API, packaging flow) is defined by the manual returned by the `ghost_forge_guide` tool built into the Cindy client — just say "help me build a plugin" in a Cindy conversation to get it on the spot. Typical flow: 1. Scaffold with the client's `ghost_forge_scaffold`, or copy the layout of any plugin in this repository. 2. In a dev environment, import the plugin directory or a `.cindy` package directly for verification. 3. When done, package it with `ghost_forge_pack` into a `.cindy` and install it to verify. `taptap-maker/vendor/taptap-maker/` ships the official `@taptap/maker@0.0.32` with the plugin. When upgrading, replace the published npm package content wholesale and bump the plugin version accordingly — do not edit the generated `dist/maker.js` by hand. ## Community Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a PR — it covers the PR title convention, the mandatory `ghost.json` version bump, the localization check, how to rebuild the bundled Node Workers, and the [DCO](./DCO) sign-off required on every commit (`git commit -s`). Participation is governed by [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md). For usage questions and what to include in an issue, see [`SUPPORT.md`](./SUPPORT.md). Please do not disclose security vulnerabilities in public issues — see [SECURITY.md](./SECURITY.md) for the reporting channel. ## License The code in this repository is open-sourced under the [Apache License 2.0](./LICENSE). Copyright 2026 心动网络股份有限公司 (X.D. Network Inc.) — see [`NOTICE`](./NOTICE). Third-party open-source components contained in bundled artifacts are attributed in the corresponding plugin directories: - `qq-mail/THIRD-PARTY-LICENSES.txt` — full license texts of the dependencies embedded in `node/worker.cjs` - `163-mail/THIRD-PARTY-LICENSES.txt` — same, for the 163 Mail plugin - `icloud-mail/THIRD-PARTY-LICENSES.txt` — same, for the iCloud Mail plugin - `yahoo-mail/THIRD-PARTY-LICENSES.txt` — same, for the Yahoo Mail plugin - `taptap-maker/vendor/taptap-maker/LICENSE` — vendored `@taptap/maker` (MIT) Apache-2.0 grants no trademark rights. These plugins are unofficial integrations with the services they connect to; third-party names and logos belong to their owners — see [`TRADEMARKS.md`](./TRADEMARKS.md).