aurask/AGENTS.md

# Aurask AGENTS.md

本文件是 `d:\JetBrains\git\aurask` 仓库的项目级实现约束。  
后续所有 Agent 在本仓库修改代码、文档、部署配置时，必须优先遵守本文件，并与 `Aurask_Technical_Operations_Plan.md` 保持一致。

## 1. 当前项目状态

当前仓库是 Aurask 的 **Python 模块化单体 MVP**，根目录按产品边界划分为：

- `api`：后端服务、PostgreSQL、PGVector、Redis、AnythingLLM、Langflow 桥接配置，以及前端到后端请求契约。
- `protal`：用户前端使用面板。目录名按当前需求保留 `protal` 拼写。
- `manager`：管理员前端使用面板。
- `deploy`：k3s 与后续部署配置。

已实现能力：

- 租户、用户与 API Key：`api/aurask/auth.py`
- HTTP 网关：`api/aurask/api.py`
- 套餐与商品目录：`api/aurask/plans.py`
- 订单、订阅与权益发放：`api/aurask/billing.py`
- TBU 额度、预扣、结算与账本：`api/aurask/quota.py`
- USDT-TRC20 支付匹配：`api/aurask/payments.py`
- 模板工作流编排：`api/aurask/orchestrator.py`
- AnythingLLM Workspace / 文档接入适配：`api/aurask/knowledge_base.py`
- PostgreSQL / PGVector / Redis / AnythingLLM / Langflow 桥接：`api/aurask/bridges/`
- 审计事件：`api/aurask/audit.py`
- MVP JSON 持久化：`api/aurask/repository.py`
- CLI：`api/aurask/cli.py`
- 测试：`tests/test_mvp.py`
- k3s 部署规划：`deploy/k3s/README.md`

当前实现可用于本地演示、流程验证和接口联调；生产化目标是迁移到 PostgreSQL、队列、真实 Langflow/AnythingLLM 服务和 k3s 部署。

## 2. 文档优先级

实现时遵循：

1. 用户明确要求
2. 本 `AGENTS.md`
3. `Aurask_Technical_Operations_Plan.md`
4. `README.md`
5. `deploy/k3s/README.md`
6. 其他项目文档

如果代码与方案冲突，优先修正为 Aurask 当前技术方案口径，不要恢复旧模板内容。

## 3. 目录与职责边界

当前目录职责如下：

```text
api/
  README.md               # API 与外部组件桥接说明
  requests/               # 前端到后端请求样例
  aurask/
  __init__.py              # 包入口，导出 CLI main
  __main__.py              # python -m aurask
  app.py                   # 应用装配，不写具体业务规则
  api.py                   # HTTP 网关与路由映射
  bridge_status.py         # 组件桥接状态
  cli.py                   # 命令行入口
  repository.py            # MVP 持久化层
  errors.py                # 统一错误类型
  ids.py                   # ID 与时间工具
  audit.py                 # 审计记录
  auth.py                  # 租户、用户、API Key
  plans.py                 # 套餐、商品、价格口径
  billing.py               # 订单、订阅、权益发放
  quota.py                 # TBU 额度、预扣、结算、账本
  payments.py              # 支付匹配、tx_hash 幂等
  orchestrator.py          # 工作流模板与运行编排
  knowledge_base.py        # Workspace 与文档接入
  bridges/                 # PostgreSQL/PGVector/Redis/AnythingLLM/Langflow 桥接
protal/
  index.html               # 用户面板
manager/
  index.html               # 管理员面板
tests/
  test_mvp.py              # 核心闭环测试
deploy/k3s/
  README.md                # 300 MAU k3s 部署方案
```

新增代码时必须放入对应模块；不要把业务逻辑堆进 `api.py` 或 `cli.py`。

## 4. 架构原则

Aurask 目标架构：

`Web/UI -> Auth + API Gateway -> Billing & Quota -> Workflow Orchestrator -> Langflow / AnythingLLM / LLM Proxy -> PostgreSQL / Redis / Object Storage / Vector DB -> Observability`

必须遵守：

- Aurask 网关是唯一公网入口。
- `Langflow`、`AnythingLLM`、数据库、Redis、向量库不直接暴露给终端用户。
- 所有核心实体和操作必须携带租户上下文。
- 基础用户只能运行审核模板，不开放任意代码执行。
- TBU 必须先预扣再执行，执行后按实际消耗结算。

## 5. 多租户要求

核心字段：

- `tenant_id`
- `user_id`
- `workspace_id`
- `flow_id`
- `plan_id`
- `order_id`

要求：

- 查询、写入、缓存键、对象存储路径、向量检索条件都必须带租户维度。
- 禁止只按 ID 查询却不校验 `tenant_id`。
- 高付费独立空间可独立 Namespace / Pod / 数据库凭证，但领域模型仍保持一致。

## 6. 模块实现规则

### 6.1 `auth.py`

- 负责租户、用户、API Key。
- 不负责套餐、额度或支付。
- API Key 返回时可以展示明文一次；持久化生产化时必须哈希。

### 6.2 `plans.py`

- 维护套餐、商品、价格和权益口径。
- 默认口径必须保持：
  - 免费体验：1 工作流、1 知识库、512MB、7 天
  - 基础套餐：20 USDT/月，3 工作流、3 知识库、1GB、900 TBU
  - 新增栏位：20 USDT/个/月，不赠送 TBU
  - TBU 包：1000、2000、5000 档

### 6.3 `billing.py`

- 负责创建订单、订阅、权益发放。
- 不直接执行支付监听。
- 发放权益必须调用 `QuotaService`，不得绕过额度账本。

### 6.4 `quota.py`

- 负责 `QuotaAccount`、`QuotaLedger`、reservation。
- 工作流执行必须走 `reserve_tbu -> settle_reservation`。
- 失败退款必须区分供应商是否已计费。
- 不允许负数 TBU 或绕过账本直接改余额。

### 6.5 `payments.py`

- 负责 `USDT-TRC20` 支付匹配。
- 必须校验 `tx_hash` 幂等。
- 金额不足、确认数不足、重复转账进入人工处理或报错。
- TRC20 手续费描述必须基于 TRON 资源模型，不要写 BTC 手续费。

### 6.6 `orchestrator.py`

- 只运行审核模板。
- 默认模板不得开启任意 Python 或任意自定义组件。
- 工作流运行必须校验 Workspace 租户归属。
- 运行前必须预扣 TBU。
- 运行后必须写 usage record 和 audit event。

### 6.7 `knowledge_base.py`

- Workspace 必须绑定 `tenant_id`。
- 文档路径必须遵循 `tenant_id/workspace_id/document_id`。
- 上传链路必须预留文件大小、类型、病毒扫描、敏感内容检测钩子。
- AnythingLLM 只能作为内部适配器，不可把管理后台暴露给用户。

### 6.8 `api.py`

- 只做请求解析、鉴权、路由和错误映射。
- 不要在 `api.py` 内写复杂业务规则。
- 新增鉴权接口必须使用 `Authorization: Bearer <api_key>`。

### 6.9 `repository.py`

- 当前是 MVP JSON store。
- 允许为演示补功能，但不要把它描述为生产数据库。
- 生产化时应新增 PostgreSQL repository，而不是把 JSON store 继续扩展成复杂数据库。

### 6.10 `bridges/`

- `config.py` 统一读取环境变量。
- `postgres.py` 只维护 PostgreSQL schema / migration contract，不直接混入业务服务。
- `pgvector.py` 必须强制 `tenant_id`、`workspace_id` 过滤契约。
- `redis_bridge.py` 统一队列、缓存、幂等和限流 key 规则。
- `anythingllm.py` 只封装 AnythingLLM API，不绕过 Aurask Workspace 绑定。
- `langflow.py` 只执行审核模板，不开放任意代码执行。

## 7. Langflow 与 AnythingLLM 约束

### Langflow

- 只作为工作流编排/执行引擎。
- 基础套餐只允许模板模式。
- 禁止向普通用户开放 Langflow 全功能 UI。
- 禁止任意 Python 执行、任意自定义组件、无白名单外部请求。
- 生产环境通过内部 `ClusterIP` 暴露给 `aurask-worker`。

### AnythingLLM

- 只作为 Workspace、文档、RAG、聊天层。
- Workspace 必须与 Aurask `tenant_id` 绑定。
- 普通用户不能进入全局管理后台。
- 文档上传必须先过 Aurask，再转发 AnythingLLM。

## 8. 部署与 k3s 约束

k3s 生产部署规划位于 `deploy/k3s/README.md`。

300 MAU 首版目标：

- `3` 台 k3s server。
- `4` 台 worker。
- `aurask-api` 与 `aurask-worker` 分开部署。
- `langflow-runtime` 与 `anythingllm` 只作为内部服务。
- PostgreSQL 使用 `CloudNativePG + PGVector`。
- Redis 用于缓存、队列、限流。
- Longhorn 或云块存储承载 PVC。
- Prometheus / Grafana / Loki / Alertmanager 做观测。

如果新增 Kubernetes manifests，应放入：

```text
deploy/k3s/base/
deploy/k3s/overlays/staging/
deploy/k3s/overlays/production/
```

## 9. 测试要求

修改核心业务逻辑后至少运行：

```bash
python -m unittest discover -s tests -v
```

若修改 CLI 或启动流程，额外运行：

```bash
uv run aurask demo --reset
```

如果当前环境缺少 `uv`，可使用：

```bash
$env:PYTHONPATH='api'; py -3 -m aurask demo --reset
```

## 10. 文档同步要求

以下变更必须同步文档：

- 新增 API：更新 `README.md`
- 改套餐/价格/TBU：更新 `plans.py`、`README.md`、`Aurask_Technical_Operations_Plan.md`
- 改部署方案：更新 `deploy/k3s/README.md`
- 改目录结构：更新本 `AGENTS.md`
- 改生产化路线：更新 `Aurask_Technical_Operations_Plan.md`

## 11. 禁止事项

默认禁止：

- 继续引入与 Aurask 无关的旧项目说明。
- 绕过 Aurask 网关直连 Langflow / AnythingLLM。
- 绕过 `QuotaService` 直接扣减或发放额度。
- 新增工作流栏位时赠送 TBU。
- 年付现金流重复计入 MRR。
- 在没有隔离设计的前提下开放任意代码执行。
- 日志记录原始密钥、完整 Prompt、完整文档正文。
- 将 JSON store 宣称为生产持久化方案。

## 12. 推荐实现顺序

后续迭代默认按以下顺序推进：

1. 把 `JsonStore` 替换为 PostgreSQL repository。
2. 引入 Redis 队列，把工作流执行移到 `aurask-worker`。
3. 接真实 Langflow Runtime Pool。
4. 接真实 AnythingLLM API。
5. 接 TronGrid / Tronscan 支付监听。
6. 编写 `deploy/k3s/base` manifests。
7. 接入监控、日志、备份和恢复演练。

除非用户明确要求，不要跳过租户、额度、订单和审计边界直接堆功能页面。