mirror of https://18126008609:longquanjian123@gitee.com/feigong123/aurask.git synced 2026-04-19 12:18:24 +00:00

Aaron 66af3b44d9 Add service bridges and frontend panel structure

2026-04-19 16:23:39 +08:00

9.7 KiB

Raw Permalink Blame History

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. 文档优先级

实现时遵循：

用户明确要求
本 AGENTS.md
Aurask_Technical_Operations_Plan.md
README.md
deploy/k3s/README.md
其他项目文档

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

3. 目录与职责边界

当前目录职责如下：

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，应放入：

deploy/k3s/base/
deploy/k3s/overlays/staging/
deploy/k3s/overlays/production/

9. 测试要求

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

python -m unittest discover -s tests -v

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

uv run aurask demo --reset

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

$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. 推荐实现顺序

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

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

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

9.7 KiB Raw Permalink Blame History Unescape Escape