Skip to content

AGENTS.md

Latest commit

 

History

History
198 lines (148 loc) · 11.2 KB

AGENTS.md

File metadata and controls

198 lines (148 loc) · 11.2 KB

Chaterm Project AGENTS.md

This document is intended for "AI coding agents/Agent tools" (such as the built-in Agent in this repository, various automated PR bots, and IDE-based intelligent coding assistants). The goal is to help agents quickly and correctly complete changes without disturbing human collaborators, while maintaining unified repository style, maintainability, and verifiability.

— If you are a human contributor, you can also refer to this document's workflow and acceptance checklist.

Project Overview

  • Tech Stack: Electron + Vite + Vue 3 + TypeScript
  • Build & Run: electron-vite, electron-builder
  • Code Structure:
    • src/main: Electron main process logic (windows, updates, SSH, storage, etc.)
    • src/preload: Preload scripts (secure bridge)
    • src/renderer: Frontend rendering layer (Vue, Pinia, Router, i18n)
    • src/main/agent: In-project AI Agent capabilities (LLM Provider, context, tools, etc.)
    • src/main/storage/db: Local DB (better-sqlite3), migrations and services

Code Structure Quick Reference

  • Main process entry: src/main/index.ts
  • Renderer entry: src/renderer/src/main.ts
  • Preload declarations: src/preload/index.ts, src/preload/index.d.ts
  • Routing & State:
    • Router src/renderer/src/router/index.ts
    • Store src/renderer/src/store/*.ts
  • Agent capabilities: src/main/agent/* (providers, core, integrations, utils, shared, etc.)
  • DB services: src/main/storage/db/* (connections, tables, migrations, services)
  • Build config: electron.vite.config.ts (aliases, proxy, sourcemap, component auto-import, etc.)

Behavioral Rules

Rule 1 — Think Before Coding

State assumptions explicitly. If uncertain, ask rather than guess. Push back when a simpler approach exists. Stop when confused — name what's unclear.

Rule 2 — Simplicity First

Minimum code that solves the problem. No speculative features. No abstractions for single-use code. If a senior engineer would call it overcomplicated, simplify.

Rule 3 — Surgical Changes

Touch only what you must. Don't "improve" adjacent code, comments, or formatting. Don't refactor what isn't broken. Match existing style.

Rule 7 — Surface Conflicts, Don't Average Them

If two existing patterns contradict, pick one (more recent / more tested), explain why, and flag the other for cleanup. Don't blend conflicting patterns.

Rule 8 — Read Before You Write

Before adding code in a file, read its exports, the immediate caller, and any obvious shared utilities. "Looks orthogonal to me" is dangerous — if unsure why code is structured a certain way, ask.

Rule 12 — Fail Loud

"Completed" is wrong if anything was skipped silently. "Tests pass" is wrong if any were skipped. Default to surfacing uncertainty, not hiding it.

Basic Principles (Required Reading for Agents)

  • Small and Precise: Only modify files directly related to requirements, avoid "incidental" refactoring of unrelated code.
  • Maintain Style: Follow ESLint + Prettier and existing naming, directory, and import alias conventions.
  • Type First: Complete TypeScript types, use any cautiously; define types for new APIs/IPC.
  • Include Tests: Core logic that is added or modified should have Vitest unit tests; end-to-end flows can add Playwright test cases.
  • Don't Break Contracts: Respect existing IPC, Store, and service interfaces; new capabilities should use an "optional extension" approach.
  • Sync Documentation: User-visible behavior changes or new capabilities should update README.md/README_zh.md or related comments.

Change Scope Options (When Adding Features)

  • Related-Only (Default/Mandatory):

    • Ignore existing issues unrelated to current functionality (code smells, historical naming, style inconsistencies, readability, etc.), do not modify them arbitrarily.
    • Only modify code and configuration directly related to "new features" or "issues explicitly to be fixed now".
    • If important issues are found (security/stability/build blockers), record them in the PR's "Known issues/Follow-ups" section, open an Issue if necessary; do not handle them in this change.
    • Lint/formatting auto-fixes are limited to files involved in this change, avoid cascading changes.

  • Broadened-Refactor (Requires Maintainer Approval):

    • Only use after explicit maintainer approval; allows cascading refactoring or batch fixes of unrelated issues.
    • PR title must include prefix [refactor-approved], description must list impact scope, migration/rollback plan, and verification method.

Submission Process (Command Quick Reference)

  • Install Dependencies:
    • node scripts/patch-package-lock.js
    • npm install
  • Development & Debugging: npm run dev
  • Code Checks:
    • Format npm run format
    • Lint fix npm run lint
    • Type check npm run typecheck
  • Testing:
    • Unit tests npm test
    • E2E npm run test:e2e / npm run test:e2e:headed
  • Build:
    • General npm run build
    • Platform packages npm run build:win|build:mac|build:linux

Pre-submission Checklist:

  • Pass lint, format, typecheck, test.
  • No unrelated diffs or large-scale formatting introduced.
  • Minimal change scope with clear commit messages.
  • If UI text or new features are involved, i18n and documentation are synced.
  • This change follows Related-Only mode; if unrelated changes are included, approval has been obtained and marked with [refactor-approved].
  • Unrelated issues found but not handled are recorded in PR's "Known issues/Follow-ups" (or a separate Issue).

Electron-Specific Constraints

  • Main Process (src/main):
    • Do not block the event loop (long-running tasks should be async or use child processes/threads).
    • Communicate with renderer via IPC; keep channel names unique, payloads serializable, and type-safe.
  • Preload (src/preload):
    • Only expose minimal APIs, use contextBridge; do not directly expose Node capabilities to the renderer.
  • Renderer (src/renderer):
    • Use Composition API, Pinia for state management; route guards go in router/guards.ts.
    • New views follow views/components and router/routes.ts conventions.

Agent Subsystem Change Guidelines (src/main/agent)

  • Provider Extensions:
    • Place in src/main/agent/api/providers/*, and complete registration in providers/types.ts and api/index.ts.
    • Network interactions should uniformly use api/retry.ts, api/transform/* wrappers to maintain consistent logging and error formats.
  • Tools/Integrations:
    • Place in integrations/* or services/*; follow existing naming and directory conventions.
    • New storage should reuse core/storage/* interfaces, or derive shared types in shared/*.
  • Rules & Prompts:
    • System prompts are located in core/prompts/* and shared/*; reuse or extend existing modules before adding new ones.
  • Testing:
    • Place in adjacent __tests__ directory or *.test.ts; assert external contract behavior rather than internal details.

Database & Migrations (better-sqlite3)

  • Code Location: src/main/storage/db/*
  • Adding/Modifying Tables:
    • Through new migration files (see examples in migrations/*), idempotent and replayable.
    • Service layer in *.service.ts; type definitions in types.ts.
  • Do not hardcode paths or access DB across layers; use the service layer uniformly.

i18n & UI Guidelines

  • Text Content:
    • Chinese src/renderer/src/locales/lang/zh-CN.ts
    • English src/renderer/src/locales/lang/en-US.ts
  • Components: src/renderer/src/views/components/*, use less/css for styles and avoid global pollution.
  • New Routes: Update src/renderer/src/router/routes.ts, route guards in router/guards.ts.

Security & Keys

  • Do not commit any keys, tokens, private domains, or account information.
  • Environment Variables: Renderer only exposes variables with RENDERER_ prefix (see electron.vite.config.ts).
  • External Requests: If proxy or Provider switching is needed, reuse existing Provider/Proxy mechanisms (api/providers/*, api/providers/proxy.ts).

Log Sanitization Rules

All log output is processed by the sanitizer (src/main/services/logging/sanitizer.ts), but developers must still follow these rules to avoid sensitive data leakage:

  • Prohibited in logger calls:

    • Logging entire objects that may contain credentials: connection configs, API configurations, asset objects, keychain objects, user payloads, MCP settings
    • String interpolation with sensitive values: hostnames, IPs, API keys, passwords, MAC addresses, usernames, proxy URLs, internal service URLs
    • JSON.stringify() on objects containing credential fields
    • Passing raw Error objects from API clients (Axios/OpenAI SDK) without sanitization — the error's config/request properties may contain tokens

  • Required patterns:

    • Use structured logging with only safe metadata: logger.info('description', { event: 'name', id: obj.id, count: N })
    • Use boolean flags for credentials: hasApiKey: !!apiKey, hasPassword: !!password, hasPrivateKey: !!privateKey
    • For connection events, log only: event name, port, protocol type, connection ID — never host/username/password
    • For API validation, log only: provider name, model ID — never the API key or full configuration object

  • Sanitizer capabilities (automatic, defense-in-depth):

    • Key-name matching: substring match on 16+ sensitive field names (password, apikey, secret, token, etc.)
    • Value pattern detection: PEM keys, JWT, AWS AKIA, Anthropic/OpenAI API keys, URL credentials
    • PII partial masking: phone numbers, emails, credit cards, ID cards, IPv4, IPv6, MAC addresses
    • Inline credential labels: apikey: xxx, token: xxx, password: xxx in error messages
    • Host/hostname partial masking for debuggability
    • Error object message/stack sanitization

Dependencies & Build

  • Build aliases are in electron.vite.config.ts:
    • Main process: @shared, @core, @services, @integrations, @utils, @api
    • Renderer: @renderer, @views, @router, @store, @utils, @api, @config, @
  • If adding third-party libraries:
    • Evaluate package size and main/renderer process compatibility.
    • Keep externalizeDepsPlugin and packaging externalization strategy consistent, update configuration if necessary.

Typical Workflow (Operation Template for Agents)

  1. Read requirements → Create minimal change plan (including impact scope, rollback strategy).
  2. Precisely locate directories and modules → Minimal scope changes.
  3. Local quick verification: npm run lint && npm run typecheck && npm test.
  4. If UI or cross-process communication is involved, perform manual/automated integration: npm run dev and npm run test:e2e.
  5. Update documentation/comments and i18n.
  6. Output change description and follow-up suggestions (such as potential risks, technical debt, TODOs).

Prohibited Actions

  • Large-scale formatting, reordering imports, meaningless renaming.
  • Modifying unrelated configuration or scripts (e.g., release processes) to "make it work".
  • Bypassing types or disabling ESLint rules to "temporarily pass".
  • Committing code containing sensitive information or environment-specific paths.

If further clarification is needed or uncertain scenarios are encountered, please briefly document your assumptions and trade-offs in the PR/change description to help human reviewers understand and make decisions.