dingMCP/AGENTS.md

Repository Working Rules

Scope and architecture

• This repository implements one lightweight stdio bridge and one unified remote gateway for DingTalk OA and XFT approvals.
• The supported customer architecture uses one gateway OAuth login for both approval sources. Do not reintroduce a local DWS dependency or a second user login without explicit product approval.
• The gateway must derive identity from its verified OAuth token. Never accept caller-supplied userId, employee ID, owner ID, or equivalent identity selectors.
• Approval bodies, expense details, attachments, and upstream schemas must remain real-time and must not be persisted.

Git workflow

• Use Git for every source, documentation, test, deployment, and distribution change.
• Keep main releasable. Develop non-trivial changes on short-lived branches named feat/<topic>, fix/<topic>, docs/<topic>, or chore/<topic>.
• Prefer small, atomic commits using Conventional Commit subjects such as feat:, fix:, docs:, test:, refactor:, and chore:.
• Do not rewrite published history, force-push, or delete remote branches/tags unless the user explicitly requests it.
• Before commit, run npm test, relevant distribution checks, and git diff --check. Update docs when architecture, installation, tools, authentication, or deployment changes.
• Releases should be tagged only from a tested main commit. Do not commit generated dist, release, test bundles, package archives, or npm caches.

Secrets and privacy

• Never commit .secrets, .runtime, .env, the root secret file, OAuth databases, tokens, cookies, credentials, approval data, or machine-specific absolute paths.
• Before the first push and every release, inspect the staged file list and scan it for likely secrets.
• Logs, tests, fixtures, and support references must not expose access tokens, AppSecret, AuthoritySecret, private approval IDs, internal user IDs, or raw upstream payloads.

Testing and safety

• All approval reads and writes in product tests must go through MCP tools; do not bypass MCP to claim end-to-end coverage.
• Automated tests must use mocks unless the user explicitly authorizes a real approval write. Never run real reject or return actions implicitly.
• Preserve the distinction between failed, succeeded, and outcome_uncertain; never automatically retry an uncertain write.
• Keep opaque approval references user-bound, source-bound, expiring, and revalidated against live ownership before every write.

Deployment and distribution

• Use ./deploy/install.sh for gateway installation and updates and ./deploy/uninstall.sh for gateway removal. These are server-operator commands; keep both idempotent and preserve server secrets by default.
• Customer installation and updates must use the signed native client installer. Do not reintroduce global npm installation, Node-version-specific MCP paths, prose-only installation, or direct mutation of host-private configuration.
• Release manifests must be Ed25519 signed. Never commit, publish, or expose the release private key; release verification must fail closed on missing/invalid signatures or artifact hashes.
• Customer installation must remain user-level, lightweight, and free of enterprise credentials. The distributed MCP command is dingtalk-approval-bridge pointing at the HTTPS gateway.
• A complete test release must expose both DingTalk OA and XFT. Treat either source being disabled as a release error.