npm package: @protoethik-ai/ode-code
Description: TyloAI terminal-based coding assistant with direct workspace editing
Author: Protoeic AI
Latest version: 1.1.0

# Ode Code 中文快速指南（Key、计费、数据库）

本文说明新版 Ode Code 的工作流、计费规则，以及需要在 **现有 Supabase 实例**（`https://oozxrnrxrapiylcsobgi.supabase.co`）创建的表结构。最新链路（无登录流程）如下：

1. 在浏览器打开 `platform.tyloai.com`（即仓库根目录 `index.html`），点击 “Generate new key” 生成 **ode-code 专用 API Key**（记录写入 Supabase）。
2. 复制生成的 `sk-` Key，粘贴到终端运行的 `ode code` / `tyloai`。
3. CLI 每次请求前自动校验 Supabase 配额，展示 “Working” 进展、计时器、剩余额度。
4. 免费额度用完后，如在仪表盘勾选 “Use balance after 50 free calls”，则按 $0.10/次从余额扣费，否则直接报错停止。

## 计费逻辑（与 CLI/前端同步）
- **每日免费 50 次**：字段 `free_quota=50`、`free_used_today` 记录当日使用量，跨天自动归零
- **付费开关**：`bill_after_free=true` 且 `balance_cents>=10` 时，超出免费额度的调用按 `call_cost_cents=10`（$0.10）扣减，并累计到 `paid_used_today` / `paid_spend_cents`
- **实时展示**：`index.html` 的「ode-code Usage」卡片和 CLI `:status` 都读取上述字段，展示免费剩余、今日总调用、已扣费用、余额
- **上游调用**：若 `ode_api_keys` 中不存在映射，CLI 会直接使用终端 `api_key` 调 Tylo 接口（默认基址 `https://api-for-tyloai.tyloai.com/v1`）

## Supabase 表（必需）

```sql
create table if not exists public.ode_terminal_keys (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null,
  email text not null,
  display_name text,
  api_key text not null,
  free_quota integer not null default 50,
  free_used_today integer not null default 0,
  paid_used_today integer not null default 0,
  paid_spend_cents integer not null default 0,
  balance_cents integer not null default 0,
  bill_after_free boolean not null default false,
  usage_date date,
  call_cost_cents integer not null default 10,
  session_code text,
  status text not null default 'active',
  inserted_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

create unique index if not exists ode_terminal_keys_api_key_idx on public.ode_terminal_keys(api_key);
create unique index if not exists ode_terminal_keys_user_idx on public.ode_terminal_keys(user_id);
```

> 若需要自动更新时间戳，可复用：
> ```sql
> create or replace function public.touch_updated_at()
> returns trigger as $$
> begin new.updated_at = now(); return new; end; $$ language plpgsql;
> drop trigger if exists set_updated_at on public.ode_terminal_keys;
> create trigger set_updated_at before update on public.ode_terminal_keys
> for each row execute function public.touch_updated_at();
> ```

### 可选：上游密钥映射
如需将终端 key 映射到另一组 TyloAI Provider Key，可建表：
```sql
create table if not exists public.ode_api_keys (
  id uuid primary key default gen_random_uuid(),
  terminal_api_key text not null unique,
  provider_api_key text not null,
  status text not null default 'active',
  rotated_at timestamptz,
  expires_at timestamptz,
  inserted_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);
create unique index if not exists ode_api_keys_terminal_idx on public.ode_api_keys(terminal_api_key);
```
CLI 查询顺序：若找不到 `provider_api_key`，直接用终端 `api_key` 调用。

### RLS 建议（匿名即可）
```sql
alter table public.ode_terminal_keys enable row level security;
create policy "ode-terminal-upsert" on public.ode_terminal_keys for insert to anon with check (true);
create policy "ode-terminal-update" on public.ode_terminal_keys for update to anon using (true) with check (true);

alter table public.ode_api_keys enable row level security;
create policy "ode-api-read" on public.ode_api_keys for select to anon using (status = 'active');
```
前端与 CLI 均会带上 `api_key=eq.<key>` 过滤条件，仅读写当前登录行。

## 前端/CLI 对应关系
- `index.html`（根目录、platform.tyloai.com）：唯一入口，直接生成/加载 ode-code Key，写 Supabase `ode_terminal_keys`，可开关付费续用。
- CLI（`lib/cli.js`）：用户直接粘贴 `sk-` Key；每次请求前通过 Supabase 校验额度，“Working” 行内置转圈 + 跑马灯 + 计时器，错误时红色提示。

## 环境变量（如需自定义）
```bash
export ODE_SUPABASE_URL="https://oozxrnrxrapiylcsobgi.supabase.co"
export ODE_SUPABASE_ANON_KEY="<your-anon-key>"
export ODE_SUPABASE_TABLE="ode_terminal_keys"
export ODE_SUPABASE_API_TABLE="ode_api_keys"
export TYLOAI_API_BASE_URL="https://api-for-tyloai.tyloai.com/v1"
```

完成以上配置后即可在 Supabase 中看到调用计数、扣费和余额，前端与 CLI 会实时读取并提示用量。