# AgentTeam WeChat Mini Program

Native WeChat Mini Program client for AgentTeam. The miniapp is the mobile entry point
for a selected AgentTeam workspace: it shows the Inbox / directory tabs, opens unified
conversation views, manages channel/thread members, and can be paired from Web by
scanning a workspace QR code.

## Current Capabilities

- **Root miniapp shell** — `pages/inbox/index` is the landing page and owns the
  workspace header, server/workspace switcher, and the Inbox / Channel / Agent
  directory tabs.
- **Inbox and directories** — Inbox rows, pinned conversations, channel directory,
  agent teams, private agents, and workspace members are loaded through
  `utils/api.ts` and formatted by `runtime/format.ts`.
- **Unified conversations** — `pages/conversation/chat` handles channel, DM, and
  thread scopes with message list, composer, mentions, attachments, optimistic
  sending, reply-thread summaries, realtime refresh, tasks, activity, members,
  collaborators, and notification sheets.
- **Conversation panels** — `components/start-chat-panel` lets users start a
  channel / team / agent / DM conversation from the Inbox shell; channel member
  and collaborator panels live under `pages/conversation/*-sheet.ts`.
- **Channel members** — `pages/channel-members/index` provides a standalone
  channel member list and DM entry point.
- **Workspace QR onboarding** — Web's **Add to Mini App** dialog generates a QR
  payload with the API base URL, a single-use pairing code, and workspace id. The
  miniapp exchanges it for a device-bound revocable session through
  `utils/workspace-link-session.ts` and stores the selected server/workspace
  through `utils/storage.ts`.
- **Mobile session security** — signing out a server revokes its server-side
  session family before deleting local credentials. Account settings in Web or
  Desktop list paired mobile devices and can revoke any of them remotely.
- **Localization** — user-facing copy is centralized in
  `utils/i18n/{zh-CN,en,ja}.ts`; WXML should bind localized `text.*` data instead
  of hard-coding display strings.

## Tech Stack

- **TypeScript** via WeChat's official `useCompilerPlugins: ['typescript']`
- **Native mini program** (WXML / WXSS / `wx.*` API)
- Erased TypeScript types from `@agentteam/shared` (`../shared`); shared value
  helpers used at runtime are generated into checked-in local modules
- `bun test` wiring/unit tests for miniapp runtime and component structure

## Project Structure

```text
miniapp/
├── app.{ts,json,wxss}         # App shell and registered pages
├── components/                # Message, composer, switcher, sheet, and start-chat UI
├── pages/
│   ├── inbox/                 # Root page: Inbox + directory tabs + workspace switcher
│   ├── conversation/          # Unified channel / DM / thread chat page and panels
│   └── channel-members/       # Standalone channel member directory
├── runtime/                   # Pure formatting, cache, realtime, activity helpers
├── utils/                     # API, storage, realtime, i18n, mention, pending-message helpers
├── project.config.json        # WeChat Dev Tools config
├── tsconfig.json              # TypeScript config
└── package.json               # @agentteam/shared dependency + dev tooling
```

## Setup

1. Open **WeChat Dev Tools** (微信开发者工具).
2. Import this directory (`miniapp/`) as a Mini Program project.
3. Set your AppID in `project.config.json` (or use test mode).
4. Install deps: `cd miniapp && bun install` (or `npm install`).

The project uses `packNpmManually=false` and does not load `@agentteam/shared`
values from `miniprogram_npm`. Package imports are type-only and erased by
TypeScript. Shared reply-thread, conversation-list, and Task conversation
action helpers run from checked-in local artifacts under `utils/` and
`runtime/`.

If DevTools reports that a registered `.wxml` file is missing immediately after
switching branches or updating many files, verify that the file exists, then
restart DevTools so it rebuilds its project file index. The hot-reload index can
otherwise retain the partial order in which `app.json` and newly added page
files appeared.

## Add a workspace from Web

Open the Web user avatar menu and choose **Add to Mini App** / **添加到微信小程序**.
Scan the QR code from the miniapp workspace switcher via **添加服务器 → 扫码添加工作区**;
the QR payload carries the Web base URL, a short-lived single-use pairing code,
and the current workspace id. After exchange, the miniapp stores the revocable
server session and switches to that workspace. Use the trash/sign-out action in
the switcher to revoke and remove that server login.

## Development Checks

```bash
cd miniapp
bun install
bun run check:shared-realtime
bun test
bun run typecheck
```

Edit shared MiniApp runtime behavior only in its canonical module under
`../shared/src/`, then regenerate and verify:

```bash
bun run generate:shared-realtime
bun run check:shared-realtime
```

Direct edits to `utils/shared-realtime.ts`, `runtime/shared-conversations.ts`,
or `runtime/shared-task-conversation-actions.ts` are overwritten by generation
and rejected by the drift check. Runtime imports from `@agentteam/shared` are also
rejected because WeChat does not package that module; only erased type imports
are allowed.

For targeted conversation-panel/i18n work:

```bash
bun test pages/conversation/chat.realtime.test.ts pages/conversation/notification-sheet.test.ts utils/i18n.test.ts
```