hmbown--codewhale/web/AGENT.md

Community Assistant Agent

The community assistant is a set of Cloudflare Cron Triggers that call deepseek-v4-flash to draft triage comments, PR reviews, stale-issue nudges, duplicate suggestions, and weekly digests. It never posts to GitHub directly. Every output is a draft staged in Workers KV for maintainer review.

Architecture

Cloudflare Cron Triggers
  └─ worker.ts scheduled() handler
       ├─ */30 min  → triage (new issues) + pr-review (new PRs)
       ├─ daily     → stale (30d inactive) + dupes (embed-similarity scan)
       ├─ weekly    → digest (Mon 09:00 UTC)
       └─ 6h       → curate (Today's Dispatch — pre-existing)

Drafts stored in Workers KV:
  draft:triage:<issue-number>
  draft:pr-review:<pr-number>
  draft:stale:<issue-number>
  draft:dupes:<issue-number>
  draft:digest:<year>-W<week>

Usage logged to:
  usage:<YYYY-MM-DD>

Cron schedule

Expression	Frequency	Tasks
0 */6 * * *	Every 6 hours	Today's Dispatch (curate)
*/30 * * * *	Every 30 min	Issue triage + PR review
0 0 * * *	Daily 00:00 UTC	Stale issue nudges + duplicate detection
0 9 * * 1	Monday 09:00 UTC	Weekly digest

Voice constraints

All drafts follow these rules:

• Calm, factual, never breathless.
• Never uses first person plural ("we"/"我们") — the maintainer is one person.
• Never commits to timing, prioritisation, or merge intent.
• Never apologises on the maintainer's behalf.
• Cites specific files / line numbers / linked issues when discussing code.
• Ends with: "— drafted by community assistant, pending maintainer review"
• Chinese drafts end with: "— 由社区助理草拟，待维护者审阅"
• Chinese output is rewritten in zh-CN, not machine-translated.

Cost guardrails

• Each cron invocation caps at ~30k input tokens and ~2k output tokens.
• Issue/PR bodies are truncated to 1000–4000 chars before sending to the model.
• Deduplication: hasFreshDraft checks if a draft already exists that's newer than the item's updated_at. Skips if so.
• Token usage is logged to usage:<YYYY-MM-DD> KV keys (retained 90 days).
• If DEEPSEEK_API_KEY is missing or the API errors, the cron returns 200 with { skipped: true, reason } — never crashes, never retry-loops.

Maintainer review surface

Access at /admin?token=<MAINTAINER_TOKEN>.

• Lists all pending drafts with source link, draft body, and three actions:
  • Post as comment — calls GitHub REST API using MAINTAINER_GITHUB_PAT
  • Edit & post — opens a textarea for editing before posting
  • Discard — removes the draft from KV
• The auth token is set via MAINTAINER_TOKEN env var. Access sets an mt cookie for the session.
• Nothing posts to GitHub without an explicit maintainer click.

Environment variables

Variable	Required	Purpose
DEEPSEEK_API_KEY	Yes	DeepSeek API key for the community agent
GITHUB_TOKEN	Optional	Fine-grained PAT for GitHub API (raises rate limit)
CRON_SECRET	Optional	Shared secret for manual cron invocation
MAINTAINER_TOKEN	Optional	Auth token for /admin panel
MAINTAINER_GITHUB_PAT	Optional	GitHub PAT with issues:write scope for posting comments

Initial deployment

One-time setup before the first npm run deploy:

1. Create the KV namespaces:

   npx wrangler kv namespace create CURATED_KV
   npx wrangler kv namespace create NEXT_INC_CACHE_KV
   

   Copy the returned id values and paste them into the matching wrangler.jsonc bindings, replacing each "REPLACE_WITH_KV_ID".

2. Set secrets:

   npx wrangler secret put DEEPSEEK_API_KEY
   npx wrangler secret put MAINTAINER_TOKEN
   npx wrangler secret put MAINTAINER_GITHUB_PAT
   npx wrangler secret put CRON_SECRET
   

3. (Optional) Raise GitHub rate limit:

   npx wrangler secret put GITHUB_TOKEN
   

4. Verify:

   npm run predeploy   # checks KV ID is set
   npm run deploy      # builds + deploys
   

Kill switch

To disable the community agent entirely:

1. Remove all cron triggers from wrangler.jsonc except the original 0 */6 * * * (curate).
2. Redeploy: npm run deploy.

The curate cron (Today's Dispatch) continues working independently. Individual tasks remain callable manually for testing through /api/cron?task=triage, /api/cron?task=pr-review, etc.

To disable a specific cron task, remove its cron expression from wrangler.jsonc and redeploy.

Bilingual output

Every draft contains both bodyEn (English) and bodyZh (Chinese zh-CN). The admin panel shows the version matching the current locale. The zh version is rewritten natively by the model, not translated from English.