Cindy Official Plugins

English · 简体中文

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

This is the source for every official plugin (Ghost) in the
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.

Plugins

Missing a plugin you want? Propose it — 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
   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(<directory>): …; 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). Details in 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; a maintainer reviews against
   the same 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 — 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/<file>.test.mjs) and back both
the PR verification workflow and the publish gates. See
CONTRIBUTING.md for the verification workflow.

Official plugins are wired into host-driven zh-CN / en / ja / ko locale
resources; see 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 —
  Publish Cindy Plugins (CN)
• 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/[email protected]
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 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 sign-off required on every commit (git commit -s).

Participation is governed by
CODE_OF_CONDUCT.md. For usage questions and what
to include in an issue, see SUPPORT.md.

Please do not disclose security vulnerabilities in public issues — see
SECURITY.md for the reporting channel.

License

The code in this repository is open-sourced under the
Apache License 2.0.

Copyright 2026 心动网络股份有限公司 (X.D. Network Inc.) — see
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.