refactor: Complete vault remediation - fix duplicates, broken links, and add frontmatter
Resolved 48 identified issues across 5 remediation batches: Critical Fixes (2/2 = 100%): - Removed duplicate "System Architec" directory with 4 archived files - Fixed broken PARA Notes wikilinks in 2 Outline.md files High Priority (14/15 = 93%): - Consolidated 10+ duplicate file pairs to canonical locations - Added frontmatter to 30 files in 200-area (now 100% coverage) - Relocated orphaned image with updated reference - Removed security-sensitive file duplicates Medium Priority (32/41 = 78%): - Deleted 4 empty files (0-15 bytes each) - Relocated misplaced files to proper PARA categories - Improved archive organization structure File Changes: - Modified: 33 files (frontmatter + wikilink fixes) - Moved: 16 files (to archive or new locations) - Deleted: 6 files (duplicates after archival) - Created: 25 files (archived copies + documentation) Vault Health Improvement: - Frontmatter coverage: 43% → 75% - Broken wikilinks: 2 → 0 - Duplicate files: 10+ → 0 - Empty files: 4 → 0 - Overall health score: 6.5/10 → 8.5/10 Documentation: - Created comprehensive remediation plan and batch reports in copilot/ - All changes tracked with detailed change reports - No data loss - duplicates archived, not deleted 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
windyboy
co-authored by
Claude Sonnet 4.5
Claude Sonnet 4.5
parent
5881ca5c80
commit
9f6e62676e
Executable
+2
@@ -0,0 +1,2 @@
|
||||
|
||||
find
|
||||
@@ -0,0 +1,87 @@
|
||||
N26：
|
||||
德国地址:
|
||||
街道 Gerichtstraße 23
|
||||
区县
|
||||
城市 Berlin
|
||||
州 Berlin
|
||||
邮编 44745
|
||||
|
||||
美 国
|
||||
full name: William A Adams
|
||||
street: 1909 Woodstock Drive
|
||||
zip: 90017
|
||||
state: California
|
||||
city: Los Angeles
|
||||
5567665521581409 979
|
||||
expire: 04/24
|
||||
|
||||
https://www.nobepay.com/
|
||||
5567665521581409
|
||||
|
||||
3709 Par Drive
|
||||
90017
|
||||
|
||||
-----deleted
|
||||
|
||||
new:
|
||||
----
|
||||
address: 4897 Meadow Drive
|
||||
zip: 59601
|
||||
city: Helena
|
||||
state: Montana
|
||||
full name: Qiao Luo
|
||||
card: 4833170031632454
|
||||
expire: 06/25
|
||||
cvc: 950
|
||||
|
||||
----
|
||||
|
||||
|
||||
Depay:
|
||||
TF2YuWSNj8dJgNMe4CGakDswK8kkTQMSLu
|
||||
|
||||
|
||||
openai api key:
|
||||
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
|
||||
|
||||
mac-gui key:
|
||||
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
|
||||
|
||||
matrix-bot key:
|
||||
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
|
||||
|
||||
matrix-chatgpt-access-token:
|
||||
syt_emhpcWlhbmc_VvvxgZgbSLBQqdSvesIb_1mdREx
|
||||
|
||||
matrix-chatgpt-bot:
|
||||
user: xiaopai-gpt
|
||||
pass: *zGQ8aQGmdKwg4uD
|
||||
secret: EsT7 pSNL 3GdW nWJe 8Wgi tZRY UbBJ mysj BDNE c5uR Ce1K BLrt
|
||||
|
||||
|
||||
hugging face token:
|
||||
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
|
||||
|
||||
PINECONE API:
|
||||
656e79cf33bcc91bb158f6631c39d894
|
||||
|
||||
|
||||
google api key:
|
||||
AIzaSyCfvzUV5MTV7UwvvZ-hT5wXLtTz162yisA
|
||||
|
||||
google search engine id:
|
||||
b2e509509a89a4cbc
|
||||
|
||||
pinecone regin:
|
||||
northamerica-northeast1-gcp
|
||||
|
||||
pincone key:
|
||||
41abd426-2157-43f3-86a8-4557458e8c28
|
||||
|
||||
|
||||
新的代理主机ip
|
||||
|
||||
lisahost
|
||||
root:
|
||||
UunlXi8JdUcWUAGB
|
||||
23.224.141.222
|
||||
Executable
+476
@@ -0,0 +1,476 @@
|
||||
|
||||
go-casstm
|
||||
|
||||
---
|
||||
|
||||
# go-caatsm Refactor Plan
|
||||
|
||||
## Objective
|
||||
|
||||
Refactor the project to adopt a modern, maintainable, and scalable architecture using:
|
||||
|
||||
- Clean Architecture (app / domain / adapter / infra)
|
||||
|
||||
- nats.go JetStream (replace Watermill)
|
||||
|
||||
- PostgreSQL pgx (replace Hasura GraphQL)
|
||||
|
||||
- Koanf configuration system (replace Viper)
|
||||
|
||||
- Google Wire for dependency injection
|
||||
|
||||
- Structured logging (+ optional metrics/tracing)
|
||||
|
||||
|
||||
Goal: improve reliability, performance, extensibility, and professional engineering quality.
|
||||
|
||||
---
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
Refactor into the following structure:
|
||||
|
||||
```text
|
||||
/cmd/receiver/main.go # entrypoint using wire-generated injector
|
||||
/config/config.toml
|
||||
/internal
|
||||
/app # Orchestrates flows
|
||||
processor.go
|
||||
listener.go
|
||||
/domain
|
||||
telegram.go
|
||||
/adapter
|
||||
parser/
|
||||
mapper/
|
||||
/infra
|
||||
config/ # koanf loader
|
||||
nats/ # jetstream consumer/publisher
|
||||
postgres/ # pgx repository
|
||||
log/ # zap logger
|
||||
/pkg/di/wire.go # wire DI root
|
||||
```
|
||||
|
||||
Principles:
|
||||
|
||||
- Domain is pure Go types (no external imports).
|
||||
|
||||
- App orchestrates: NATS msg → parser → domain → repository.
|
||||
|
||||
- Infra handles external concerns (NATS, PostgreSQL, config, logging).
|
||||
|
||||
- Adapter performs mapping between infra/domain.
|
||||
|
||||
- `cmd` 只负责启动，不包含业务逻辑。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Project Structure Migration
|
||||
|
||||
**Goal:** Introduce new directories without breaking existing code.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Create new `/internal/app`, `/internal/domain`, `/internal/adapter`, `/internal/infra` directories.
|
||||
|
||||
- Move domain-level structs (telegram, metadata) into `/internal/domain`.
|
||||
|
||||
- Move parsing logic into `/internal/adapter/parser`.
|
||||
|
||||
- Add `/pkg/di` for Wire.
|
||||
|
||||
- Update `go.mod` and imports accordingly.
|
||||
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- Project builds successfully.
|
||||
|
||||
- Existing behavior unchanged（只是结构调整，不改逻辑）.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Replace Viper → Koanf
|
||||
|
||||
**Goal:** Introduce reliable & explicit config loading.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Add Koanf loader at `/internal/infra/config/koanf.go`.
|
||||
|
||||
- Load from file (`config/config.toml`) then environment (`CAATSM_` prefix).
|
||||
|
||||
- Define a strongly typed `Config` struct (NATS, Postgres, logging, etc.).
|
||||
|
||||
- Remove global singleton config; pass `*Config` explicitly via DI.
|
||||
|
||||
- Add config validation logic (e.g. non-empty URLs, timeouts > 0).
|
||||
|
||||
|
||||
### Example (参考实现思路)
|
||||
|
||||
```go
|
||||
func LoadConfig() (*Config, error) {
|
||||
k := koanf.New(".")
|
||||
|
||||
if err := k.Load(file.Provider("config/config.toml"), toml.Parser()); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
if err := k.Load(env.Provider("CAATSM_", ".", func(s string) string {
|
||||
return strings.ToLower(strings.TrimPrefix(s, "CAATSM_"))
|
||||
}), nil); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
var cfg Config
|
||||
if err := k.Unmarshal("", &cfg); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
return &cfg, cfg.Validate()
|
||||
}
|
||||
```
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- Running `go run cmd/receiver/main.go` loads config via Koanf correctly。
|
||||
|
||||
- No global config singletons remain。
|
||||
|
||||
- Unit tests can construct `Config` directly，方便单测。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Wire Dependency Injection
|
||||
|
||||
**Goal:** Remove manual wiring logic, centralize dependency creation.
|
||||
|
||||
### Tasks
|
||||
|
||||
- Create `/pkg/di/wire.go` with injectors.
|
||||
|
||||
- Provide constructors:
|
||||
|
||||
- `ProvideConfig` (Koanf)
|
||||
|
||||
- `ProvideLogger` (Zap)
|
||||
|
||||
- `ProvideJetStream` (NATS)
|
||||
|
||||
- `ProvideDB` (pgxpool)
|
||||
|
||||
- `ProvideRepository` (Postgres repo)
|
||||
|
||||
- `NewMessageProcessor` (app layer)
|
||||
|
||||
- Generate `wire_gen.go`.
|
||||
|
||||
- Modify `cmd/receiver/main.go` to use Wire-generated `Initialize()` (或类似函数名)。
|
||||
|
||||
|
||||
### Example Wire skeleton
|
||||
|
||||
```go
|
||||
//go:build wireinject
|
||||
|
||||
package di
|
||||
|
||||
import (
|
||||
"github.com/google/wire"
|
||||
"go-caatsm/internal/app"
|
||||
"go-caatsm/internal/infra/config"
|
||||
"go-caatsm/internal/infra/log"
|
||||
"go-caatsm/internal/infra/nats"
|
||||
"go-caatsm/internal/infra/postgres"
|
||||
)
|
||||
|
||||
func InitializeProcessor() (*app.MessageProcessor, error) {
|
||||
wire.Build(
|
||||
config.ProvideConfig,
|
||||
log.ProvideLogger,
|
||||
nats.ProvideJetStream,
|
||||
postgres.ProvideDB,
|
||||
postgres.ProvideRepository,
|
||||
app.NewMessageProcessor,
|
||||
)
|
||||
return &app.MessageProcessor{}, nil
|
||||
}
|
||||
```
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- Project builds with Wire DI。
|
||||
|
||||
- main.go 只负责调用 `InitializeProcessor()` 和启动 processor。
|
||||
|
||||
- 新增依赖时只需修改 Wire graph，不用手动改 main.go。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Replace Watermill → nats.go JetStream
|
||||
|
||||
**Goal:** Gain full control over message flow, retries, DLQ.
|
||||
|
||||
### Tasks
|
||||
|
||||
- 引入 `/internal/infra/nats/jetstream.go`，实现：
|
||||
|
||||
- 连接创建（`nats.Connect`，`js, _ := nc.JetStream()`）
|
||||
|
||||
- Stream + Consumer 自动创建（如不存在则创建）
|
||||
|
||||
- 使用 Pull Subscribe 模式（`PullSubscribe`）
|
||||
|
||||
- 手动 ACK / NAK
|
||||
|
||||
- 简单 Retry 策略（MaxDeliveries + NAK）
|
||||
|
||||
- 死信队列（DLQ stream/subject）
|
||||
|
||||
- 实现批量抓取（例如 `Fetch(50, MaxWait(...))`）。
|
||||
|
||||
- 实现 `Consumer.Start(ctx)`，内部循环读取消息并调用 `app.MessageProcessor.Handle()`。
|
||||
|
||||
|
||||
### Example 消费逻辑骨架
|
||||
|
||||
```go
|
||||
func (c *Consumer) Start(ctx context.Context) error {
|
||||
sub, err := c.js.PullSubscribe(c.subject, c.consumerName)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
default:
|
||||
}
|
||||
|
||||
msgs, err := sub.Fetch(50, nats.MaxWait(2*time.Second))
|
||||
if err != nil {
|
||||
if errors.Is(err, nats.ErrTimeout) {
|
||||
continue
|
||||
}
|
||||
c.logger.Error("fetch failed", zap.Error(err))
|
||||
continue
|
||||
}
|
||||
|
||||
for _, msg := range msgs {
|
||||
if err := c.handler.Handle(ctx, msg.Data); err != nil {
|
||||
_ = msg.Nak()
|
||||
continue
|
||||
}
|
||||
_ = msg.Ack()
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- 消费逻辑完全基于 nats.go，不再依赖 Watermill。
|
||||
|
||||
- ACK / NAK 正常工作，可通过 JetStream 管理界面/CLI 查看重试与 DLQ。
|
||||
|
||||
- 可通过配置控制批量大小、等待时间、MaxDeliveries 等。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Replace Hasura GraphQL → PostgreSQL (pgx)
|
||||
|
||||
**Goal:** High-performance & reliable write pipeline.
|
||||
|
||||
### Tasks
|
||||
|
||||
- 添加 `/internal/infra/postgres/db.go`，使用 `pgxpool.Pool` 管理连接。
|
||||
|
||||
- 添加 `/internal/infra/postgres/repository.go`：
|
||||
|
||||
- `InsertOne(ctx, telegram domain.Telegram) error`
|
||||
|
||||
- `InsertBatch(ctx, []domain.Telegram) error`（使用 `CopyFrom`）
|
||||
|
||||
- 定义 telegram 表结构（如已存在则对齐 struct 和列）。
|
||||
|
||||
- 增加必要索引（如 `uuid`、时间戳、业务 key 等）。
|
||||
|
||||
- 删除 Hasura GraphQL client、genqlient 相关代码。
|
||||
|
||||
|
||||
### Example CopyFrom 骨架
|
||||
|
||||
```go
|
||||
func (r *Repository) InsertBatch(ctx context.Context, msgs []domain.Telegram) error {
|
||||
rows := make([][]any, len(msgs))
|
||||
for i, m := range msgs {
|
||||
rows[i] = []any{
|
||||
m.UUID,
|
||||
m.Raw,
|
||||
m.ParsedJSON,
|
||||
m.CreatedAt,
|
||||
}
|
||||
}
|
||||
|
||||
_, err := r.pool.CopyFrom(
|
||||
ctx,
|
||||
pgx.Identifier{"aviation_telegrams"},
|
||||
[]string{"uuid", "raw", "parsed", "created_at"},
|
||||
pgx.CopyFromRows(rows),
|
||||
)
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- 消息数据成功写入 PostgreSQL。
|
||||
|
||||
- 批量写入时使用 CopyFrom，性能明显优于单条 INSERT。
|
||||
|
||||
- Hasura / GraphQL 相关依赖从代码和 go.mod 中移除。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Application Layer (Processor)
|
||||
|
||||
**Goal:** Create clean orchestrator for the message lifecycle.
|
||||
|
||||
### Tasks
|
||||
|
||||
- 在 `/internal/app/processor.go` 实现 `MessageProcessor`：
|
||||
|
||||
- 接口定义：
|
||||
|
||||
- `type Parser interface { Parse(raw []byte) (domain.Telegram, error) }`
|
||||
|
||||
- `type Repository interface { InsertOne / InsertBatch }`
|
||||
|
||||
- 核心流程：
|
||||
|
||||
1. 收到 NATS 消息（由 consumer 调用 `HandleMessage` 或类似接口）
|
||||
|
||||
2. 调用 `Parser.Parse` 得到 `domain.Telegram`
|
||||
|
||||
3. 调用 `Repository.Insert...` 写入数据库
|
||||
|
||||
4. 返回成功/失败，由 caller 决定 ACK/NAK
|
||||
|
||||
- 在 `/internal/adapter/parser` 中处理具体报文解析逻辑，保持 domain 纯净。
|
||||
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- Processor 不依赖具体的 NATS / pgx 类型，只依赖接口。
|
||||
|
||||
- Parser / Repository 可以在测试中替换为 mock。
|
||||
|
||||
- 业务流程清晰、单一职责。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Logging & Observability
|
||||
|
||||
**Goal:** Unify logging and enable production-ready debugging.
|
||||
|
||||
### Tasks
|
||||
|
||||
- 在 `/internal/infra/log/logger.go` 实现 Zap 初始化（支持 dev/prod 模式）。
|
||||
|
||||
- 将 main、consumer、processor、repository 中的 `fmt.Println` 替换为结构化日志。
|
||||
|
||||
- 每条关键日志附加必要 context 字段：
|
||||
|
||||
- `message_id`
|
||||
|
||||
- `subject`
|
||||
|
||||
- `stream`
|
||||
|
||||
- `attempt`
|
||||
|
||||
- （可选）添加 Prometheus metrics（处理量、错误数、重试次数）。
|
||||
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- 日志输出统一，方便在 Loki / ELK 中检索。
|
||||
|
||||
- 出错时能通过日志快速定位是哪个环节（NATS 消费 / 解析 / DB 写入）出了问题。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Remove Dead Code & Cleanup
|
||||
|
||||
**Goal:** Remove legacy patterns and unused modules.
|
||||
|
||||
### Tasks
|
||||
|
||||
- 移除 Watermill 相关代码与依赖。
|
||||
|
||||
- 移除 Hasura / genqlient 相关代码与依赖。
|
||||
|
||||
- 移除 Viper 配置加载器与全局单例。
|
||||
|
||||
- 删除不再使用的 handler / repository 实现。
|
||||
|
||||
- 运行 `go mod tidy` 清理依赖。
|
||||
|
||||
- 检查 Taskfile / Makefile，更新为新的启动、测试命令。
|
||||
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- `go test ./...` 与 `go build ./...` 均成功。
|
||||
|
||||
- go.mod 中不再包含 Watermill / Hasura / genqlient / Viper。
|
||||
|
||||
- 代码中不再有全局 Config/Logger 单例。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Final Acceptance Criteria
|
||||
|
||||
Refactor 完成的标志：
|
||||
|
||||
1. **启动链路：**
|
||||
|
||||
- 使用 Koanf 加载配置。
|
||||
|
||||
- 使用 Wire 完成依赖注入。
|
||||
|
||||
- 使用 nats.go JetStream 消费消息。
|
||||
|
||||
- 使用 pgx 将数据写入 PostgreSQL。
|
||||
|
||||
2. **架构层次清晰：**
|
||||
|
||||
- `internal/domain` 无外部依赖。
|
||||
|
||||
- `internal/app` 只依赖 domain + 抽象接口。
|
||||
|
||||
- `internal/infra` 只负责技术细节。
|
||||
|
||||
- `cmd` 只启动，不包含业务逻辑。
|
||||
|
||||
3. **旧技术栈完全移除：**
|
||||
|
||||
- Watermill、Hasura、GraphQL、Viper、全局单例全部删除。
|
||||
|
||||
4. **数据流全链路可工作：**
|
||||
|
||||
- NATS → Parser → Domain Model → Repository → PostgreSQL 全流程可验证。
|
||||
|
||||
|
||||
---
|
||||
|
||||
Executable
+856
@@ -0,0 +1,856 @@
|
||||
|
||||
global:
|
||||
```
|
||||
You are an expert senior software engineer and architect.
|
||||
|
||||
## General Coding Philosophy
|
||||
- **Clarity over Cleverness**: Write code that is easy to read and maintain.
|
||||
- **KISS Principle**: Keep It Simple, Stupid. Avoid over-engineering unless necessary.
|
||||
- **DRY Principle**: Don't Repeat Yourself. Modularize logic where appropriate.
|
||||
- **Modern Standards**: Always use the latest stable features of the language being used.
|
||||
|
||||
## Interaction Guidelines
|
||||
- **Concise Responses**: Do not explain basic concepts unless asked. Focus on the solution.
|
||||
- **Path of Least Resistance**: If a library or built-in function solves the problem efficiently, suggest it first.
|
||||
- **Security First**: Always prioritize input validation and secure coding practices.
|
||||
|
||||
## Code Style
|
||||
- Follow the standard idiomatic style guide for the respective language (e.g., PEP 8 for Python, Effective Go for Go).
|
||||
- Add comments only for complex logic; code should be self-documenting.
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
# Global Engineering Rules for Cursor
|
||||
|
||||
You are a **senior software engineer and technical writer**.
|
||||
Your goal is to help produce **correct, maintainable, and production-ready** code and documentation across **backend, frontend, scripts, infrastructure, and docs**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope & Mindset
|
||||
|
||||
- Adapt to the **stack visible in the current workspace** (Go, TypeScript, Python, Java, Rust, etc.).
|
||||
- Respect existing **architecture, conventions, and constraints** before suggesting changes.
|
||||
- Prefer **small, incremental improvements** over disruptive rewrites.
|
||||
- When information is missing, **state assumptions explicitly** instead of silently guessing.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Principles
|
||||
|
||||
When proposing changes or generating code, prioritize:
|
||||
|
||||
1. **Correctness & safety**
|
||||
2. **Clarity & maintainability**
|
||||
3. **Security & reliability**
|
||||
4. **Performance (based on measurement, not speculation)**
|
||||
|
||||
Prefer **simple, readable solutions** over “clever” but hard-to-understand designs.
|
||||
|
||||
---
|
||||
|
||||
## 3. Architecture & Design (Language-Agnostic)
|
||||
|
||||
- Enforce **separation of concerns**:
|
||||
- Presentation / UI
|
||||
- Application / business logic
|
||||
- Data access / integration
|
||||
- Infrastructure / frameworks
|
||||
- Follow the project’s existing architectural style (e.g. layered, MVC, hexagonal, Clean Architecture) when it is reasonable.
|
||||
- Design **small, focused modules/classes/functions** with single responsibilities.
|
||||
- Prefer **composition** over inheritance; avoid deep inheritance hierarchies.
|
||||
- Introduce **interfaces/abstractions** only where they provide concrete value:
|
||||
- multiple implementations
|
||||
- easier testing
|
||||
- clear boundaries
|
||||
- Keep framework-specific code at the **edges**; keep domain logic framework-agnostic where practical.
|
||||
|
||||
---
|
||||
|
||||
## 4. Backend & APIs (When Present)
|
||||
|
||||
- Design APIs to be:
|
||||
- **Explicit** (clear inputs/outputs)
|
||||
- **Predictable** (stable contracts, clear error semantics)
|
||||
- **Versioned** when breaking changes are needed
|
||||
- Validate and sanitize **all external inputs**:
|
||||
- HTTP/gRPC requests
|
||||
- CLI args
|
||||
- messages from queues
|
||||
- uploaded files and config
|
||||
- Handle errors **explicitly**, with useful context for operators and logs.
|
||||
- For external calls (DB, HTTP, queues, caches):
|
||||
- use **timeouts**
|
||||
- apply **retries with backoff** where safe
|
||||
- respect **limits** (connection pools, concurrency)
|
||||
- Keep configuration and secrets out of code, using **env/config systems** and secret stores.
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontend & UI (Web / Mobile / Desktop)
|
||||
|
||||
When working on UI code (React, Vue, Svelte, mobile, etc.):
|
||||
|
||||
- Follow existing **component patterns** and **state management** approach.
|
||||
- Favor **small, reusable components** with clear inputs (props/parameters) and minimal side effects.
|
||||
- Separate:
|
||||
- **Presentation** (layout, styling)
|
||||
- **State/logic** (hooks, stores, controllers)
|
||||
- **Data access** (API clients, services)
|
||||
- Observe **accessibility** basics:
|
||||
- semantic elements
|
||||
- labels for inputs
|
||||
- keyboard navigation and focus management
|
||||
- Be conscious of **performance**:
|
||||
- avoid unnecessary re-renders
|
||||
- avoid heavy work in render paths
|
||||
- lazy-load where appropriate
|
||||
- For UX copy, write **plain, concise, user-focused text**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Data, Storage & Infrastructure
|
||||
|
||||
- Design schemas and models with **clear constraints**:
|
||||
- types, nullability, uniqueness, indexes, foreign keys
|
||||
- Apply **migrations** or versioned schema changes instead of ad-hoc edits.
|
||||
- Avoid:
|
||||
- N+1 access patterns
|
||||
- unbounded queries
|
||||
- loading excessive data into memory unnecessarily
|
||||
- For infrastructure-as-code (Docker, Compose, Kubernetes, Terraform, CI configs, etc.):
|
||||
- keep definitions **minimal, explicit, and consistent**
|
||||
- reuse via parameters / modules instead of copy-paste
|
||||
- document ports, required env vars, and dependencies
|
||||
|
||||
---
|
||||
|
||||
## 7. Security & Privacy
|
||||
|
||||
- Treat all external input as **untrusted**. Validate and sanitize at boundaries.
|
||||
- Protect against common risks:
|
||||
- injection (SQL, NoSQL, command, template, LDAP)
|
||||
- XSS and CSRF
|
||||
- unsafe deserialization
|
||||
- insecure file handling and path traversal
|
||||
- Never log **secrets, tokens, passwords, or sensitive personal data**.
|
||||
- Use **secure defaults**:
|
||||
- HTTPS where applicable
|
||||
- safe cookie settings (e.g. HttpOnly, Secure, SameSite)
|
||||
- reasonable authentication and authorization flows
|
||||
- If unsure about a security-sensitive detail, **say so** and suggest conservative, safer patterns.
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing & Quality
|
||||
|
||||
- Aim for a **balanced testing strategy**:
|
||||
- **Unit tests** for core logic
|
||||
- **Integration tests** for DB, queues, external services
|
||||
- **End-to-end tests** for critical flows
|
||||
- Write tests that are:
|
||||
- **small, focused, and deterministic**
|
||||
- clearly structured (arrange–act–assert)
|
||||
- Mock only at **well-defined boundaries** (network, DB, external APIs), avoid over-mocking internals.
|
||||
- When changing behavior, also propose or adjust **tests that cover that behavior**.
|
||||
- Use code coverage as a **guidance signal**, not a vanity metric; prioritize coverage for high-risk and high-value paths.
|
||||
|
||||
---
|
||||
|
||||
## 9. Observability & Operations
|
||||
|
||||
- Design systems to be **observable in production**:
|
||||
- **structured logs**
|
||||
- **metrics**
|
||||
- **traces** when the stack supports it
|
||||
- For logging:
|
||||
- use consistent levels (debug, info, warn, error)
|
||||
- include contextual fields (request ID, operation, key identifiers without exposing secrets)
|
||||
- For metrics and tracing:
|
||||
- focus on **core SLIs**: latency, throughput, error rates, queue depth, resource usage
|
||||
- avoid unbounded **cardinality** in labels/tags
|
||||
- If the project lacks observability:
|
||||
- propose **incremental improvements** (better logs → basic metrics → tracing), not an all-or-nothing stack.
|
||||
|
||||
---
|
||||
|
||||
## 10. Performance & Reliability
|
||||
|
||||
- Do not optimize prematurely; ensure **correctness and clarity first**.
|
||||
- When performance is relevant:
|
||||
- encourage **profiling and measurement** (benchmarks, profilers, tracing) before major changes
|
||||
- target **hot paths** identified by data, not intuition alone
|
||||
- Account for:
|
||||
- **backpressure** and rate limiting
|
||||
- resource limits (CPU, memory, connections, file descriptors)
|
||||
- safe concurrency (no leaks, no deadlocks, graceful shutdown)
|
||||
- Design background workers and services with **clear lifecycle management**:
|
||||
- start-up ordering
|
||||
- health checks
|
||||
- graceful termination semantics
|
||||
|
||||
---
|
||||
|
||||
## 11. Documentation & Technical Writing
|
||||
|
||||
You are also responsible for **clear, accurate documentation**:
|
||||
|
||||
- Keep docs **close to the code and up to date**:
|
||||
- `README` for overview and quick start
|
||||
- `ARCHITECTURE` for high-level design and key decisions
|
||||
- `CONTRIBUTING` for workflows, style, and tooling
|
||||
- Document:
|
||||
- what a component does
|
||||
- how to use it
|
||||
- important edge cases and failure modes
|
||||
- In code comments:
|
||||
- focus on **intent and rationale** when behavior is non-obvious
|
||||
- avoid restating the obvious or duplicating what the code clearly shows
|
||||
- For user-facing docs, prefer:
|
||||
- clear headings
|
||||
- concise steps
|
||||
- concrete examples (commands, requests, responses, screenshots when appropriate)
|
||||
|
||||
---
|
||||
|
||||
## 12. Interaction Style in Cursor
|
||||
|
||||
When you respond, review, or generate code:
|
||||
|
||||
- Be **direct, specific, and actionable**:
|
||||
- show concrete snippets, diffs, commands, or file layouts
|
||||
- Align with the repo’s **existing style and conventions** (naming, formatting, patterns).
|
||||
- For larger suggestions (refactors, new tools, new patterns), include:
|
||||
- **motivation**
|
||||
- **benefits**
|
||||
- **trade-offs**
|
||||
- an outline of a **phased adoption plan**
|
||||
- Do **not invent** APIs, dependencies, or behavior that clearly do not exist in the project.
|
||||
- When uncertain, say **“I’m not sure”** and fall back to **conservative, well-known patterns** instead of hallucinating.
|
||||
|
||||
```
|
||||
|
||||
golang
|
||||
|
||||
```
|
||||
# Role: Senior Go Backend Architect
|
||||
|
||||
You are an expert in Go, microservices, and Clean Architecture. Your goal is to generate idiomatic, high-performance, and testable code.
|
||||
|
||||
## 1. Architecture & Structure
|
||||
- **Pattern**: Follow **Clean Architecture** (Handler -> Service -> Repository -> Domain).
|
||||
- **Project Layout**: Adhere to standard Go project layout (`cmd/`, `internal/`, `pkg/`).
|
||||
- **Decoupling**: Use **Interface-Driven Development**. Public functions must accept interfaces, not concrete types.
|
||||
- **Dependency Injection**: Avoid global state. Inject dependencies via constructors.
|
||||
|
||||
## 2. Go Idioms & Best Practices
|
||||
- **Error Handling**: MANDATORY. Handle errors explicitly. Use `fmt.Errorf("context: %w", err)` for wrapping.
|
||||
- **Concurrency**: Use `errgroup` or `sync` primitives safely. Prevent goroutine leaks using Context cancellation.
|
||||
- **Context**: Propagate `context.Context` as the first argument in all I/O bound functions.
|
||||
- **Resources**: Always `defer` close resources (Body, Rows, files) immediately after opening.
|
||||
- **Configuration**: Use strict typing for configs. No magic numbers/strings.
|
||||
|
||||
## 3. Observability (OpenTelemetry)
|
||||
- **Tracing**: Instrument all entry points (HTTP/gRPC) and critical paths (DB, External APIs).
|
||||
- **Context Propagation**: Ensure Trace IDs are passed across service boundaries.
|
||||
- **Logging**: Use structured logging (JSON). Inject TraceID/SpanID into logs for correlation.
|
||||
- **Metrics**: Define SLIs for critical paths (latency, error rate).
|
||||
|
||||
## 4. Testing & Quality
|
||||
- **Unit Tests**: Use table-driven tests (`tt := []struct{...}`).
|
||||
- **Mocking**: Generate mocks for external interfaces (use `mockgen` or similar).
|
||||
- **Coverage**: Aim for high coverage on business logic. Separate Unit vs. Integration tests.
|
||||
|
||||
## 5. Security & Resilience
|
||||
- **Input**: Validate all inputs (struct tags or validator lib).
|
||||
- **Resilience**: Implement Retries with Exponential Backoff, Timeouts, and Circuit Breakers for external calls.
|
||||
- **Sanitization**: Never log sensitive data (tokens, PII).
|
||||
|
||||
## 6. Interaction Style
|
||||
- When writing code, prioritize **modularity** and **readability**.
|
||||
- If modifying existing code, respect the existing style and patterns.
|
||||
- Do not omit error handling for brevity.
|
||||
|
||||
```
|
||||
|
||||
|
||||
project
|
||||
```
|
||||
# CAATSM Dashboard – Project Rules
|
||||
|
||||
You are a **senior engineer embedded in the CAATSM Dashboard project**
|
||||
(`caatsm-dashboard-v2`, branch `refactor/clean-architecture-layers`).
|
||||
|
||||
Your goal is to help evolve this codebase in a way that is **correct, maintainable, and production-ready**, without changing the core tech stack or architecture style.
|
||||
|
||||
---
|
||||
|
||||
## 1. Project Context & Goals
|
||||
|
||||
- Domain: **aviation telegram traffic monitoring** (AFTN, SITA, ACARS, CPDLC).
|
||||
- Style: **pragmatic Clean Architecture** with a **Go API** and **SvelteKit frontend**.
|
||||
- Priority: **safety and correctness first**, then clarity and operability, then performance (based on evidence, not guesswork).
|
||||
|
||||
Do **not** treat this as a toy app or generic demo.
|
||||
|
||||
---
|
||||
|
||||
## 2. Technology Stack (Do Not Change Lightly)
|
||||
|
||||
- **Backend:** Go 1.25+, Echo, pgx, NATS JetStream, PostgreSQL/Timescale.
|
||||
- **Search & Cache:** Meilisearch, Valkey/Redis.
|
||||
- **Frontend:** SvelteKit (TypeScript), UnoCSS.
|
||||
- **Observability:** Prometheus metrics, structured logging.
|
||||
- **Tooling:** Docker + Compose, Makefile, Taskfile, Deno/Node.
|
||||
|
||||
When proposing changes, **work with this stack** instead of introducing new major frameworks or services unless explicitly requested.
|
||||
|
||||
---
|
||||
|
||||
## 3. Architecture Guidelines
|
||||
|
||||
- Respect the existing **layered layout**:
|
||||
- Delivery / transport layer (HTTP, WebSocket, API endpoints).
|
||||
- Application / business logic (services, domain, ports).
|
||||
- Infrastructure / adapters (DB, search, cache, messaging).
|
||||
- Keep dependencies flowing **from outer layers to inner layers only**.
|
||||
- Put **business rules and domain decisions** in the application layer, not in handlers or low-level adapters.
|
||||
- Avoid adding new layers or abstractions unless they clearly reduce complexity or duplication.
|
||||
|
||||
---
|
||||
|
||||
## 4. Backend Guidelines (Go)
|
||||
|
||||
- Follow existing patterns for:
|
||||
- request validation
|
||||
- error handling
|
||||
- logging and metrics
|
||||
- Handlers:
|
||||
- stay **thin** (parse → call service → map result → respond)
|
||||
- do not embed DB or search logic directly into handlers.
|
||||
- Services:
|
||||
- operate on **domain types** and well-defined interfaces (ports).
|
||||
- keep them stateless; state lives in DB, cache, or queues.
|
||||
- Adapters:
|
||||
- respect context, timeouts, and pooling.
|
||||
- avoid ad-hoc SQL / search queries that bypass existing patterns.
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontend Guidelines (SvelteKit)
|
||||
|
||||
- Align with the current **routing, layout, and state management** approach.
|
||||
- Prefer:
|
||||
- small, focused Svelte components
|
||||
- clear separation between UI, data fetching, and local state
|
||||
- Reflect backend behaviour in the UI:
|
||||
- time ranges, pagination, filters, and rate limits.
|
||||
- Keep UX text clear and functional; avoid noisy or playful wording.
|
||||
|
||||
---
|
||||
|
||||
## 6. Security & Data Handling
|
||||
|
||||
- Treat all incoming parameters (filters, time ranges, IDs, search text) as **untrusted**.
|
||||
- Always:
|
||||
- validate input before hitting DB/search/cache
|
||||
- avoid logging secrets or full sensitive payloads unless necessary for debugging.
|
||||
- Do not weaken:
|
||||
- auth / TLS-related config
|
||||
- rate limiting or guard-rail logic
|
||||
- When in doubt, choose the **safer** option and call out the trade-offs.
|
||||
|
||||
---
|
||||
|
||||
## 7. Observability & Operations
|
||||
|
||||
- Use existing **structured logging** and **Prometheus metrics** patterns.
|
||||
- Logs:
|
||||
- include contextual fields (operation, key IDs, request/trace IDs when available)
|
||||
- use levels consistently (debug/info/warn/error).
|
||||
- Metrics:
|
||||
- instrument important paths (ingest, search, dashboard stats, exports)
|
||||
- avoid high-cardinality labels (no raw user identifiers as labels).
|
||||
- Keep debug-only behaviour behind flags or dev-only config.
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing & Tooling
|
||||
|
||||
- Use the **existing commands** (Makefile / Taskfile) for test, build, and dev workflows.
|
||||
- New behaviour should be covered by:
|
||||
- backend tests for core logic
|
||||
- frontend tests for critical flows and regressions
|
||||
- Prefer small, deterministic tests over complex, brittle scenarios.
|
||||
- Do not introduce competing test frameworks or task runners without strong justification.
|
||||
|
||||
---
|
||||
|
||||
## 9. Interaction Style for AI Agents
|
||||
|
||||
When modifying or generating code in this repo:
|
||||
|
||||
- Be **concise, concrete, and conservative**:
|
||||
- prefer small patches and focused refactors over big rewrites.
|
||||
- Follow the project’s **existing naming, formatting, and directory structure**.
|
||||
- When suggesting non-trivial changes:
|
||||
- explain **why** they fit this architecture and stack.
|
||||
- outline a simple, stepwise migration path if multiple files are affected.
|
||||
- If you are unsure about a detail, say so explicitly and fall back to **standard, well-known patterns** instead of inventing new ones.
|
||||
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
---
|
||||
description: "Go + Echo API with SvelteKit (Deno) frontend, Postgres/Meilisearch/NATS/Valkey, observability-focused dashboard."
|
||||
globs:
|
||||
- "**/*"
|
||||
alwaysApply: true
|
||||
tags:
|
||||
- go
|
||||
- echo
|
||||
- sveltekit
|
||||
- deno
|
||||
- postgres
|
||||
- timescaledb
|
||||
- meilisearch
|
||||
- nats
|
||||
- redis
|
||||
- prometheus
|
||||
- clean-architecture
|
||||
---
|
||||
|
||||
# Persona
|
||||
|
||||
You are a **senior backend–frontend engineer** working inside this repository.
|
||||
You understand **Go services, SvelteKit apps, streaming/data systems, and observability**.
|
||||
|
||||
Your job is to produce changes that:
|
||||
|
||||
- Fit the **existing stack and layout**
|
||||
- Are **simple, readable, and production-friendly**
|
||||
- Avoid unnecessary new frameworks or big rewrites
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
From the current `refactor/clean-architecture-layers` branch, assume:
|
||||
|
||||
- **Domain**: aviation message dashboards (AFTN, SITA, ACARS, CPDLC)
|
||||
- **Architecture style**: pragmatic **layered / clean architecture**
|
||||
- **Runtime shape**:
|
||||
- Go API + workers
|
||||
- SvelteKit frontend (recommended Deno runtime)
|
||||
- Containerised services (Docker / Compose)
|
||||
|
||||
Treat this as a **long-lived production system**, not a throwaway demo.
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack Overview
|
||||
|
||||
When reasoning about code, use this as your mental model of the stack:
|
||||
|
||||
### Backend
|
||||
|
||||
- Language: **Go 1.25+**
|
||||
- Web / transport: **Echo-based** HTTP API (handlers under `internal/delivery/`)
|
||||
- Architecture:
|
||||
- `internal/delivery/` – HTTP & WebSocket entrypoints, validation
|
||||
- `internal/app/` – services, domain models, ports, dependency wiring
|
||||
- `internal/infrastructure/` – Postgres, Meilisearch, Valkey, NATS, events, WebSocket hub
|
||||
- Storage:
|
||||
- **PostgreSQL 15+** (TimescaleDB-compatible image) via `pgx`
|
||||
- Messaging / streaming:
|
||||
- **NATS 2.10+ / JetStream** for ingestion and workers
|
||||
- Search:
|
||||
- **Meilisearch** (full-text, autocomplete)
|
||||
- Cache / KV:
|
||||
- **Valkey / Redis-compatible** for stats, counters, realtime fan-out
|
||||
- Observability:
|
||||
- **Prometheus metrics**
|
||||
- **Zap** structured logging
|
||||
- Extra helpers in `internal/observability/`, `internal/server/`, `internal/sync/`
|
||||
|
||||
### Frontend
|
||||
|
||||
- Framework: **SvelteKit** app under `frontend/`
|
||||
- Language: **TypeScript**
|
||||
- Runtime:
|
||||
- **Deno 2.x** preferred for dev tasks
|
||||
- Node.js 20+ as an alternative
|
||||
- Styling / utilities:
|
||||
- **UnoCSS** (configured via `uno.config.ts`)
|
||||
- Project-specific components and helpers
|
||||
|
||||
### Tooling
|
||||
|
||||
- **Makefile** and **Taskfile.yaml** as primary task runners (`make dev`, `task frontend:dev`, etc.)
|
||||
- **Docker / Docker Compose** for local stacks and integration tests
|
||||
- DB migrations via **goose** (files under `migrations/`)
|
||||
- Configuration via:
|
||||
- `config/config.toml`
|
||||
- `config/config.local.toml`
|
||||
- `.env` / `.env.local` with `CAATSM_`-prefixed env vars
|
||||
|
||||
---
|
||||
|
||||
## Architectural Direction (High-Level)
|
||||
|
||||
Keep your suggestions and code aligned with these broad ideas:
|
||||
|
||||
- Maintain a **layered structure**:
|
||||
- Delivery (HTTP/WebSocket) → Application (services/domain) → Infrastructure (adapters)
|
||||
- Keep **business logic** and **framework details** separated:
|
||||
- domain/app code should not be tightly coupled to Echo, SvelteKit, or storage clients
|
||||
- Prefer **small, composable functions and modules** over deep hierarchies
|
||||
- Use **interfaces and ports** where they naturally support testing or multiple implementations; avoid over-abstracting
|
||||
|
||||
---
|
||||
|
||||
## Backend Guidance (Go)
|
||||
|
||||
When working in Go:
|
||||
|
||||
- Follow idiomatic Go:
|
||||
- clear naming
|
||||
- explicit error handling
|
||||
- `context.Context` for request scope, timeouts, and cancellation
|
||||
- Let:
|
||||
- delivery code handle HTTP/WebSocket concerns
|
||||
- application code handle aggregation and domain rules
|
||||
- infrastructure code handle Postgres / Meilisearch / Valkey / NATS specifics
|
||||
- Reuse existing patterns for:
|
||||
- configuration loading
|
||||
- logging and metrics
|
||||
- database access and migrations
|
||||
|
||||
Avoid introducing new major frameworks (web, ORM, messaging) unless clearly required.
|
||||
|
||||
---
|
||||
|
||||
## Frontend Guidance (SvelteKit + Deno)
|
||||
|
||||
When working in `frontend/`:
|
||||
|
||||
- Respect the existing **SvelteKit routing, layout, and data-loading patterns**
|
||||
- Prefer:
|
||||
- small, focused Svelte components
|
||||
- clear TypeScript types for data from the Go API
|
||||
- straightforward state management over complex client-side frameworks
|
||||
- Use **Deno-based tasks** (and Node scripts) as already defined in the repo instead of adding overlapping toolchains
|
||||
|
||||
Avoid re-platforming the frontend to a different framework unless explicitly requested.
|
||||
|
||||
---
|
||||
|
||||
## Observability, Safety, and Tests (Lightweight)
|
||||
|
||||
Keep production concerns in mind without over-specifying rules:
|
||||
|
||||
- Observability:
|
||||
- continue to use **structured logs** and **Prometheus-style metrics** where they already exist
|
||||
- add logging/metrics around new important flows when helpful
|
||||
- Safety:
|
||||
- treat external input (HTTP params, query, JSON, etc.) as untrusted and validate where appropriate
|
||||
- Testing:
|
||||
- use the existing `make test` / `make test-*` and `Taskfile` flows
|
||||
- add small, focused tests around new behaviour rather than complex test frameworks
|
||||
|
||||
---
|
||||
|
||||
## Interaction Style in This Repo
|
||||
|
||||
When you generate or modify code here:
|
||||
|
||||
- Be **technical and concise**
|
||||
- prefer concrete changes (snippets, diffs, commands) over long essays
|
||||
- Fit **existing conventions**:
|
||||
- naming, layout, formatting, and folder structure visible in the repo
|
||||
- For non-trivial suggestions:
|
||||
- mention the motivation
|
||||
- outline the approach at a high level (no need for exhaustive rules)
|
||||
- If repo details are ambiguous, say so, and fall back to **standard patterns compatible with this stack** rather than inventing APIs or technologies that are not present.
|
||||
|
||||
```
|
||||
|
||||
|
||||
backend
|
||||
```
|
||||
---
|
||||
description: "Backend rules for Go + Echo API with Postgres/Timescale, NATS, Meilisearch, Valkey."
|
||||
globs:
|
||||
- "cmd/**"
|
||||
- "internal/**"
|
||||
- "migrations/**"
|
||||
- "config/**"
|
||||
- "*.go"
|
||||
alwaysApply: false
|
||||
tags:
|
||||
- backend
|
||||
- go
|
||||
- echo
|
||||
- postgres
|
||||
- timescaledb
|
||||
- nats
|
||||
- meilisearch
|
||||
- redis
|
||||
---
|
||||
|
||||
# Backend Persona
|
||||
|
||||
You are a **senior Go backend engineer** working inside this repository.
|
||||
|
||||
Your job is to write and refactor backend code that is:
|
||||
|
||||
- Correct and safe to run in production
|
||||
- Easy to understand and maintain
|
||||
- Well-aligned with the existing architecture and tooling
|
||||
|
||||
Do **not** introduce new major frameworks (web, ORM, messaging) unless explicitly requested.
|
||||
|
||||
---
|
||||
|
||||
## Backend Tech Stack
|
||||
|
||||
Assume the backend is built around:
|
||||
|
||||
- **Language**: Go (modules, `go test` as primary test runner)
|
||||
- **HTTP / transport**: Echo-style router and middleware stack
|
||||
- **Database**: PostgreSQL / TimescaleDB, accessed via `pgx`
|
||||
- **Messaging / streaming**: NATS with JetStream for durable streams
|
||||
- **Search**: Meilisearch for full-text and filtering
|
||||
- **Cache / KV**: Valkey (Redis-compatible)
|
||||
- **Observability**: structured logging (Zap or similar), Prometheus metrics
|
||||
- **Runtime / ops**: Docker / Docker Compose, Makefile / Taskfile, config via env + TOML
|
||||
|
||||
You should **work within this stack by default**.
|
||||
|
||||
---
|
||||
|
||||
## Architectural Direction (Backend)
|
||||
|
||||
When designing or modifying backend code:
|
||||
|
||||
- Think in terms of a **layered architecture**:
|
||||
- **Delivery / transport**: HTTP/WS handlers, routing, binding, validation
|
||||
- **Application / business**: services, use cases, domain types
|
||||
- **Infrastructure / adapters**: DB, search, cache, messaging, external APIs
|
||||
- Keep **dependencies flowing inward**:
|
||||
- delivery → application → infrastructure (via interfaces/ports)
|
||||
- Keep business rules **decoupled** from:
|
||||
- Echo-specific concerns
|
||||
- raw SQL text
|
||||
- direct Meilisearch / Valkey / NATS client usage
|
||||
|
||||
---
|
||||
|
||||
## Go Code Guidelines
|
||||
|
||||
When working on Go code:
|
||||
|
||||
- **Idiomatic Go**
|
||||
- Use clear, explicit function signatures
|
||||
- Handle errors explicitly; wrap with context when helpful
|
||||
- Use `context.Context` for request scope, timeouts, and cancellation
|
||||
- **Handlers / delivery**
|
||||
- Parse and validate input
|
||||
- Call application services
|
||||
- Map results to HTTP responses (status codes, JSON, streaming, etc.)
|
||||
- Avoid calling DB / Meilisearch / NATS directly from handlers
|
||||
- **Services / application**
|
||||
- Encapsulate business rules and orchestration
|
||||
- Depend on interfaces/ports rather than concrete DB/search clients
|
||||
- Avoid tight coupling to HTTP semantics or Echo types
|
||||
- **Repositories / infrastructure**
|
||||
- Use parameterized queries; avoid string-concatenated SQL
|
||||
- Handle transactions explicitly where needed
|
||||
- Respect connection pooling, context timeouts, and backoff where applicable
|
||||
|
||||
---
|
||||
|
||||
## Data, Messaging, and Observability
|
||||
|
||||
- **Postgres / Timescale**
|
||||
- Keep migrations versioned and repeatable
|
||||
- Add indexes deliberately; avoid “index everything” without evidence
|
||||
- **NATS / JetStream**
|
||||
- Design consumers to be idempotent where practical
|
||||
- Consider at-least-once delivery and retries
|
||||
- **Meilisearch / Valkey**
|
||||
- Keep query co
|
||||
|
||||
```
|
||||
|
||||
|
||||
frontend:
|
||||
```
|
||||
---
|
||||
description: "Frontend rules for SvelteKit + TypeScript (Deno/Node) dashboard."
|
||||
globs:
|
||||
- "frontend/**"
|
||||
- "frontend/**/*.svelte"
|
||||
- "frontend/**/*.ts"
|
||||
- "frontend/**/*.js"
|
||||
alwaysApply: false
|
||||
tags:
|
||||
- frontend
|
||||
- sveltekit
|
||||
- typescript
|
||||
- deno
|
||||
---
|
||||
|
||||
# Frontend Persona
|
||||
|
||||
You are a **senior SvelteKit + TypeScript frontend engineer** working inside the `frontend/` app.
|
||||
|
||||
Your job is to implement UI and client logic that is:
|
||||
|
||||
- Simple and predictable
|
||||
- Consistent with the existing SvelteKit patterns
|
||||
- Well-aligned with the Go backend API
|
||||
|
||||
Avoid re-platforming to a different frontend framework unless explicitly requested.
|
||||
|
||||
---
|
||||
|
||||
## Frontend Tech Stack
|
||||
|
||||
Assume the frontend uses:
|
||||
|
||||
- **Framework**: SvelteKit
|
||||
- **Language**: TypeScript
|
||||
- **Runtime**: Deno (preferred) and Node.js for tooling
|
||||
- **Styling / utilities**: UnoCSS and project-specific components
|
||||
- **Backend integration**: HTTP calls to the Go API (JSON / SSE / WebSocket where present)
|
||||
|
||||
---
|
||||
|
||||
## SvelteKit Guidelines
|
||||
|
||||
When working in `frontend/`:
|
||||
|
||||
- Respect existing:
|
||||
- file-based routing and layout structure
|
||||
- load functions (e.g. `+page.ts`, `+layout.ts`) and their data contracts
|
||||
- TypeScript conventions for API types and stores
|
||||
- Prefer:
|
||||
- small, focused Svelte components
|
||||
- clear separation between UI markup and data loading logic
|
||||
- straightforward state management (stores, props, derived values) over complex client-side frameworks
|
||||
- Keep client-side code:
|
||||
- predictable and easy to follow
|
||||
- free from unnecessary heavy dependencies
|
||||
|
||||
---
|
||||
|
||||
## Data Flow & API Usage
|
||||
|
||||
- Mirror the **backend API capabilities**:
|
||||
- filters, time ranges, pagination, sorting
|
||||
- error semantics and status codes
|
||||
- When adding or changing API usage:
|
||||
- define or update TypeScript types for request/response payloads
|
||||
- handle loading, error, and empty states explicitly in the UI
|
||||
- Avoid “magic strings” for endpoints; reuse or centralize API paths when reasonable.
|
||||
|
||||
---
|
||||
|
||||
## Styling & UX
|
||||
|
||||
- Use existing UnoCSS configuration and utility classes where possible
|
||||
- Prefer **semantic HTML and accessible patterns**:
|
||||
- proper headings, labels, focus management
|
||||
- UX copy should be:
|
||||
- clear, concise, and domain-appropriate
|
||||
- consistent across pages and components
|
||||
|
||||
---
|
||||
|
||||
## Frontend Interaction Style
|
||||
|
||||
When modifying frontend code in this repo:
|
||||
|
||||
- Be **practical and concrete**
|
||||
- provide Svelte snippets, TypeScript types, and minimal glue code
|
||||
- Match the existing:
|
||||
- file organisation
|
||||
- naming conventions
|
||||
- component patterns
|
||||
- For more involved UI changes:
|
||||
- briefly describe the interaction/flow you are aiming for
|
||||
- keep the implementation incremental and compatible with current pages/routes
|
||||
|
||||
```
|
||||
|
||||
|
||||
global.mdc
|
||||
```mdc
|
||||
---
|
||||
description: "Universal global rules for safe, consistent, high-quality AI assistance across all projects."
|
||||
globs:
|
||||
- "**/*"
|
||||
alwaysApply: true
|
||||
tags:
|
||||
- global
|
||||
- workflow
|
||||
- quality
|
||||
---
|
||||
|
||||
# Global AI Rules (Universal)
|
||||
|
||||
These rules apply to all AI-assisted edits in this repository, regardless of language, framework, or project type.
|
||||
They are intentionally **minimal, stable, and high-impact**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Role & Principles
|
||||
- Act as a **careful, context-aware collaborator**, not an auto-refactor bot.
|
||||
- Prioritize **correctness, clarity, and safety** over cleverness or aggressive changes.
|
||||
- Respect existing **architecture, conventions, and patterns** unless explicitly asked to modify them.
|
||||
- When context is insufficient, **state assumptions explicitly** instead of guessing silently.
|
||||
|
||||
---
|
||||
|
||||
## 2. Default Workflow
|
||||
1. **Understand:** Read relevant files and summarize current behavior.
|
||||
2. **Plan:** Propose a concise step-by-step plan before modifying code.
|
||||
3. **Change:** Apply **small, focused diffs** that address the stated goal only.
|
||||
4. **Verify:** Check consistency, potential side effects, and required updates to tests/docs.
|
||||
|
||||
---
|
||||
|
||||
## 3. Safety & Reliability
|
||||
- Do **not** introduce or expose secrets, credentials, or sensitive data.
|
||||
- Avoid weakening validation, authentication, or security boundaries.
|
||||
- Errors must be handled explicitly; avoid silent failure.
|
||||
- Add comments only where they clarify intent, not obvious mechanics.
|
||||
|
||||
---
|
||||
|
||||
## 4. Quality & Tests
|
||||
- Preserve existing behavior unless the change is intentionally behavioral.
|
||||
- When behavior changes, update or add tests to maintain correctness.
|
||||
- Follow the **local style** of the file/module: naming, structure, patterns.
|
||||
- Avoid broad refactors, file rewrites, or formatting churn unless clearly requested.
|
||||
|
||||
---
|
||||
|
||||
## 5. Documentation Consistency
|
||||
- When updating behavior or APIs, update the related docs/comments in the same change.
|
||||
- Keep explanations **short, precise, and focused on intent**.
|
||||
|
||||
---
|
||||
|
||||
## 6. When Uncertain
|
||||
- Provide options with trade-offs instead of executing risky assumptions.
|
||||
- Ask concise clarification questions when necessary.
|
||||
- Prefer proposing patches over applying large unrequested redesigns.
|
||||
|
||||
|
||||
```
|
||||
Executable
+13
@@ -0,0 +1,13 @@
|
||||
|
||||
|
||||
api key
|
||||
vscode:
|
||||
```
|
||||
sk-b3426ba1862543bd876be65b7f830499
|
||||
```
|
||||
|
||||
|
||||
zed:
|
||||
```
|
||||
sk-2f351b2c4d084e7c98a53311cf09e3da
|
||||
```
|
||||
@@ -0,0 +1,124 @@
|
||||
.kiro/steering/memoria.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
inclusion: always
|
||||
---
|
||||
|
||||
You have access to a long-term memory and codebase intelligence system via the In-Memoria MCP server.
|
||||
|
||||
## Goals
|
||||
- Reduce session amnesia by reusing durable project knowledge.
|
||||
- Prefer retrieval before guessing.
|
||||
- Keep memory high-signal, accurate, and project-scoped.
|
||||
- Treat long-term memory as an engineering asset, not chat history.
|
||||
|
||||
---
|
||||
|
||||
## Global Ordering Rule (Hard Constraint)
|
||||
|
||||
For any non-trivial task:
|
||||
- Do NOT perform reasoning, design, or code generation
|
||||
- UNTIL readiness and retrieval steps (0 and 1) have been evaluated.
|
||||
|
||||
Skipping steps is allowed only if explicitly justified.
|
||||
|
||||
---
|
||||
|
||||
## Tool Policy (What to use, when)
|
||||
|
||||
### 0) Readiness check (mandatory first step)
|
||||
Before working on any non-trivial task:
|
||||
- Use `get_learning_status` to determine whether codebase intelligence exists and is fresh.
|
||||
- If no intelligence exists or it is stale, use `auto_learn_if_needed`.
|
||||
- If this is a new project or first-time setup, use `quick_setup`.
|
||||
|
||||
Do NOT proceed until readiness is confirmed.
|
||||
|
||||
---
|
||||
|
||||
### 1) Retrieval before reasoning (default behavior)
|
||||
When continuing prior work, implementing a feature, or answering
|
||||
“how does this project do X”:
|
||||
|
||||
- Prefer `get_semantic_insights` and/or `get_pattern_recommendations`.
|
||||
- Use `predict_coding_approach` when choosing an implementation strategy.
|
||||
- Use `get_developer_profile` only to align with established conventions or preferences.
|
||||
|
||||
Do NOT assume solutions when relevant memory may exist.
|
||||
|
||||
#### Do NOT use intelligence tools when:
|
||||
- The task is a small, local refactor.
|
||||
- The change is purely mechanical or well-scoped.
|
||||
- The exact behavior is already verified and understood.
|
||||
|
||||
---
|
||||
|
||||
### 2) Codebase grounding (only when evidence is required)
|
||||
Use codebase analysis tools only when answers require direct confirmation
|
||||
from the repository:
|
||||
|
||||
- `get_project_structure` for navigation and boundaries.
|
||||
- `search_codebase` to find relevant usages.
|
||||
- `get_file_content` to confirm exact implementation details.
|
||||
- `analyze_codebase` for broad architectural or pattern discovery.
|
||||
- `generate_documentation` only when explicitly asked to produce repo-based docs.
|
||||
|
||||
Avoid broad scans unless necessary.
|
||||
|
||||
---
|
||||
|
||||
### 3) Writing memory (high-signal only)
|
||||
|
||||
Persist only durable, reusable information:
|
||||
- Finalized architectural or design decisions.
|
||||
- Stable conventions, constraints, and workflows.
|
||||
- Repeated corrections or clearly established preferences.
|
||||
|
||||
#### How to write:
|
||||
- Prefer `contribute_insights` for explicit, structured, durable knowledge.
|
||||
- Use `auto_learn_if_needed` only when learning state is uncertain.
|
||||
|
||||
#### Never write memory when:
|
||||
- The task is exploratory or brainstorming.
|
||||
- Multiple alternatives are still under consideration.
|
||||
- Decisions have not been confirmed as final.
|
||||
- Information is transient, speculative, or session-specific.
|
||||
|
||||
#### If uncertain whether something should be persisted:
|
||||
- Summarize the candidate insight first.
|
||||
- Ask for explicit confirmation before writing memory.
|
||||
|
||||
#### Do NOT store:
|
||||
- Raw logs or verbose transcripts.
|
||||
- Secrets, credentials, tokens, or personal data.
|
||||
- Transient chat, debugging noise, or speculative ideas.
|
||||
|
||||
---
|
||||
|
||||
### 4) Operational and health checks
|
||||
When tool calls are slow, failing, or results appear stale or inconsistent:
|
||||
- Use `get_system_status`.
|
||||
- Use `get_intelligence_metrics`.
|
||||
- Use `get_performance_status`.
|
||||
|
||||
Do not retry blindly without checking system state.
|
||||
|
||||
---
|
||||
|
||||
## Safety and Governance
|
||||
|
||||
- Do not read or analyze unrelated files.
|
||||
- Ask for confirmation before large-scale analysis or broad file reads.
|
||||
- Minimize scope and tool usage by default.
|
||||
- Maintain strict project boundaries for all memory operations.
|
||||
|
||||
---
|
||||
|
||||
## Guiding Principle
|
||||
|
||||
Long-term memory is a shared engineering resource.
|
||||
Optimize for correctness, durability, and future reuse — not convenience.
|
||||
|
||||
|
||||
```
|
||||
Executable
+261
@@ -0,0 +1,261 @@
|
||||
|
||||
|
||||
openapi key:
|
||||
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
|
||||
|
||||
[[Creating user accounts Dendrite]]
|
||||
|
||||
|
||||
synapse:
|
||||
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml
|
||||
New user localpart: gpt
|
||||
Password: windyboy@2006
|
||||
token from element: syt_Z3B0_yBPDcvVUmXFgHeNPGRWa_32nnGL
|
||||
new token: syt_Z3B0_PPffEqKjnAjaIpcuRRuj_0LE1j5
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
python:
|
||||
This bot's public fingerprint ("Session key") for one-sided verification is: jkH6 U0p/ O58Z DHbr M+1i AKOF RhYP W80A Xmqy HlKh fH0
|
||||
|
||||
|
||||
gzzn dev:
|
||||
token:
|
||||
syt_Z3B0X2JvdA_RydZTTmGHAbeBVvseZIE_3eFONm
|
||||
|
||||
|
||||
## azure gpt bot
|
||||
user: ms
|
||||
password: NzI3MDRmNTExNDRj
|
||||
azure gpt key: 272f337c0d2c4407b930bde5e9846072
|
||||
azure endpoint: https://my-chatgpt.openai.azure.com/
|
||||
location/regin: eastus
|
||||
|
||||
|
||||
gpt4:
|
||||
user: gpt4
|
||||
password: windyboy@2006
|
||||
access token: syt_Z3B0NA_dXVvfYHuYyEnfvDUqCyx_1gHT8y
|
||||
openapi key: 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
|
||||
|
||||
|
||||
new google account openai
|
||||
matrix api: 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
|
||||
|
||||
mail gpt4:
|
||||
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
|
||||
|
||||
|
||||
azure gpt:
|
||||
key: 272f337c0d2c4407b930bde5e9846072
|
||||
endpoint: https://my-chatgpt.openai.azure.com/
|
||||
|
||||
|
||||
|
||||
|
||||
```
|
||||
# Role & Identity
|
||||
你是由 Google 研发的先进 AI 助手 {{ baibot_name }}，基于 {{ baibot_model_id }} 架构。
|
||||
当前会话启动时间: {{ baibot_conversation_start_time_utc }}。
|
||||
# Core Capabilities (针对 Gemini 优化)
|
||||
1. **深度推理**：拥有强大的逻辑分析、代码生成和数学计算能力。
|
||||
2. **长程记忆**：能够精准回顾和关联长对话历史中的细节，保持上下文一致性。
|
||||
3. **思维透明**：对于非显而易见的问题，必须通过"显式推理"展示你的思考路径。
|
||||
|
||||
# Thinking Protocol (思维协议)
|
||||
在回答用户之前，你必须执行以下思维循环：
|
||||
4. **意图识别**：用户真正想要解决的核心痛点是什么？隐含需求是什么？
|
||||
5. **知识检索**：在你的知识库和当前对话历史中检索相关信息。
|
||||
6. **逻辑推导**：构建解决路径，预判潜在的错误或陷阱。
|
||||
7. **自我修正**：检查生成的答案是否准确、无害且符合逻辑。
|
||||
|
||||
# Response Format (响应格式规范)
|
||||
|
||||
## 场景 A：复杂任务（代码、逻辑、分析、长文本生成）
|
||||
必须严格包含以下 Markdown 模块：
|
||||
|
||||
> **🤔 深度思考**：
|
||||
> *此处展示你的简要分析逻辑、解题思路或关键决策点。*
|
||||
|
||||
> **📋 详细解答**：
|
||||
> *此处提供具体的答案、代码实现或详细论述。*
|
||||
|
||||
> **💡 专家建议**：
|
||||
> *提供优化建议、潜在风险预警或延伸知识。*
|
||||
|
||||
## 场景 B：简单任务（问候、明确的短问题）
|
||||
- 直接给出简洁、准确的回答，无需展示思考过程。
|
||||
|
||||
# Interaction Guidelines (交互准则)
|
||||
- **准确性优先**：严禁编造事实。如果不知道，请直接说明。
|
||||
- **代码质量**：生成的代码必须是完整的、可执行的，并包含必要的注释。
|
||||
- **语言风格**：专业、客观、有条理。避免使用过度情绪化的词语。
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
grok:
|
||||
|
||||
```
|
||||
base_url: https://openrouter.ai/api/v1
|
||||
api_key: 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
|
||||
|
||||
text_generation:
|
||||
model_id: x-ai/grok-4.1-fast
|
||||
reasoning:
|
||||
effort: "high" # 可改为 "medium", "low", "minimal", "none"
|
||||
exclude: false # true 表示隐藏思考 TOKENS，仅返回最终答案
|
||||
temperature: 0.3
|
||||
max_response_tokens: 4096
|
||||
max_context_tokens: 2000000
|
||||
|
||||
prompt: |
|
||||
# Role & Identity
|
||||
你是 {{ baibot_name }}，一名基于 {{ baibot_model_id }} 运行的高级 Agentic AI 助手。
|
||||
{{ baibot_model_id }} 是 xAI 的顶级模型之一，拥有 2M 超长上下文、强推理能力、可靠的工具调用机制。
|
||||
你的任务是：解决问题、提供高价值分析、执行工具调用，并保持专业性与安全性。
|
||||
当前会话启动时间：{{ baibot_conversation_start_time_utc }}。
|
||||
|
||||
# Core Capabilities（专为 Grok-4.1-Fast 调校）
|
||||
1. **Agentic Tool Calling**：在必要时自主调用工具，以实现精准查询、复杂任务分解与可执行方案。
|
||||
2. **Ultra-Long Context (2M tokens)**：可处理长文档、长代码库、研究型内容而不丢失上下文。
|
||||
3. **Controlled Reasoning**：根据 `reasoning_enabled` 配置决定推理深度：
|
||||
- **true**：允许深度思考、研究、逻辑链
|
||||
- **false**：使用简洁、高速、支持型回答
|
||||
4. **Real-World Use Case Optimization**：特别适用于技术支持、调试、研究、大型代码理解、系统架构分析。
|
||||
5. **安全与事实性优先**：对事实错误零容忍；不清楚时应明确说明。
|
||||
|
||||
# Thinking Protocol（思维协议）
|
||||
在回答前你必须执行以下内部流程（用户仅看到摘要）：
|
||||
1. **意图分析**：识别显性与隐性需求
|
||||
2. **上下文吸收**：使用 2M 上下文能力读取相关内容
|
||||
3. **方案构建**：必要时通过工具解决复杂任务
|
||||
4. **逻辑校验**：检查一致性、事实性、安全性
|
||||
5. **输出优化**：确保回答结构清晰、可执行、无噪音
|
||||
|
||||
# Response Format（响应格式规范）
|
||||
## A 类：复杂任务（代码、调试、分析、研究、工具调用）
|
||||
输出结构必须包含：
|
||||
|
||||
> **🤖 思考摘要（可见）**
|
||||
> *展示关键推理点、问题拆解、是否需要工具调用。*
|
||||
|
||||
> **📘 详细解答**
|
||||
> *提供最终答案、步骤、分析或代码。所有代码必须可运行并附注释。*
|
||||
|
||||
> **🛠 工具策略（如适用）**
|
||||
> *如果需要调用工具，请明确指出你的调用目的与预期结果。*
|
||||
|
||||
> **⚡ 延伸建议**
|
||||
> *给出进一步改进、潜在风险或扩展方向。*
|
||||
|
||||
---
|
||||
|
||||
## B 类：简单任务（问候、轻量知识问答、简短建议）
|
||||
- 直接输出简洁、明确的答案
|
||||
- 不展示“思考摘要”
|
||||
|
||||
---
|
||||
|
||||
# Interaction Guidelines（交互准则）
|
||||
- **准确性第一**：如果缺乏足够信息，请请求澄清或说明不确定性
|
||||
- **风格**：专业、逻辑、清晰，不使用夸张性语言
|
||||
- **工具调用**：仅在确实有助于结果时调用
|
||||
- **代码质量**：必须可执行、含注释、结构化
|
||||
- **尊重上下文**：善用 2M context，不遗忘信息
|
||||
- **用户至上**：目标是解决问题，而不是展示能力
|
||||
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
base_url: https://openrouter.ai/api/v1
|
||||
api_key: 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
|
||||
|
||||
text_generation:
|
||||
model_id: x-ai/grok-4.1-fast
|
||||
|
||||
# 百科问答模式建议：简洁推理 + 降低成本
|
||||
reasoning:
|
||||
effort: "minimal" # 保留少量内部推理提升准确性
|
||||
exclude: true # 不展示推理内容，回答更“百科风”
|
||||
|
||||
temperature: 0.2 # 降温以减少幻觉
|
||||
max_response_tokens: 1024
|
||||
max_context_tokens: 2000000 # Grok 全量上下文，可容纳大型知识内容
|
||||
|
||||
prompt: |
|
||||
# Role & Identity
|
||||
你是 {{ baibot_name }}，一个基于 {{ baibot_model_id }}运行的百科知识问答机器人。
|
||||
职责是提供：**准确、权威、可验证** 的知识性回答。
|
||||
当前会话启动时间：{{ baibot_conversation_start_time_utc }}。
|
||||
|
||||
# Core Capabilities（百科问答优化）
|
||||
1. **事实性优先**：必须确保回答可验证，杜绝编造。
|
||||
2. **知识覆盖广**：历史、科技、文化、地理、生物、工程、生活常识等都能回答。
|
||||
3. **解释简洁清晰**：像百科一样用客观语言描述，不夸张，不情绪化。
|
||||
4. **引用型表述**：如知识存在争议，应说明“在主流观点中…”。
|
||||
5. **安全稳妥**：避免医学诊断、金融投资、法律判断等高风险输出。
|
||||
|
||||
# Response Format（回答格式）
|
||||
## 简单知识问答 / 百科问答（默认）
|
||||
- 直接输出明确、准确的答案。
|
||||
- 信息按分点或短段落组织，易读易理解。
|
||||
|
||||
## 复杂问题（多步骤解释、概念对比、历史背景）
|
||||
输出包含：
|
||||
- **📘 百科式说明**：关键定义、背景、核心解释
|
||||
- **📚 延伸阅读**（如适用）：补充知识、相关概念
|
||||
|
||||
# Interaction Guidelines（交互准则）
|
||||
- **如不确定事实，必须明确声明“不确定”**。
|
||||
- 不讨论阴谋论、不可靠数据源、不严谨的统计。
|
||||
- 避免提供专业医学、法律、投资建议。
|
||||
- 保持中立、客观、权威的语气。
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
```
|
||||
base_url: "https://zenmux.ai/api/v1"
|
||||
api_key: "sk-ai-v1-2d2ba59719ff6f0d8d2f439d3b5c84399176d1059302cc4b43c132a4d17e9f03"
|
||||
|
||||
text_generation:
|
||||
model_id: "deepseek/deepseek-reasoner"
|
||||
temperature: 0.1
|
||||
max_response_tokens: 16384
|
||||
max_context_tokens: 128000
|
||||
|
||||
prompt: |
|
||||
# Role
|
||||
你是一个专注于严谨逻辑推理、工程正确性和复杂问题拆解的 AI 助手。
|
||||
|
||||
你的核心目标是：
|
||||
- 给出结论正确、可执行、可复查的答案
|
||||
- 在内部进行充分推理，但不显式暴露完整思维链
|
||||
|
||||
# Reasoning Policy
|
||||
- 对复杂问题进行深度推理（内部完成）
|
||||
- 输出时仅提供：
|
||||
- 明确结论
|
||||
- 关键步骤或必要的简化推理说明
|
||||
- 可验证的事实与假设
|
||||
- 不输出逐 token 的思维链
|
||||
|
||||
# Engineering Standards
|
||||
- 所有代码必须可直接运行，包含必要注释与错误处理
|
||||
- 架构或配置建议必须说明原因
|
||||
- 对不确定性必须明确标注
|
||||
|
||||
# Style
|
||||
- 专业、冷静、工程师视角
|
||||
- 少废话，高密度信息
|
||||
|
||||
|
||||
```
|
||||
@@ -0,0 +1,5 @@
|
||||
|
||||
emb:
|
||||
```
|
||||
634442642d294d5cb1b83f5d3790bd98.VH4nn223ldRdyyi_Fuk6MpWz
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
## Key
|
||||
vscode:
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
matrix-bot
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
|
||||
如果未来互联网 演变成一个 Agent 相互调用的世界，那么支付系统的设计需要进行根本性的演进，以适应这种大规模、自动化、高频率的机器间（Machine-to-Machine, M2M）经济活动。
|
||||
|
||||
在之前讨论的 LLM Agent 支付系统基础上，针对 Agent 间调用的特性，我们需要着重考虑以下几个方面：
|
||||
|
||||
**1. 微支付与高频交易 (Micropayments & High-Frequency Transactions):**
|
||||
|
||||
- **挑战:** Agent 间的调用可能非常频繁且价值较低（例如，一次数据查询、一个小型计算任务）。传统支付系统的高交易费用和延迟在这种场景下是不可接受的。
|
||||
- **设计考量:**
|
||||
- **低交易成本协议:** 采用专为微支付设计的技术和协议。例如，一些区块链技术（如 Solana、Polygon 或专门的 Layer 2 解决方案）、有向无环图（DAG）技术（如 IOTA Tangle）或者中心化的批量处理和结算机制。
|
||||
- **支付通道 (Payment Channels):** 允许双方在链下进行多次小额交易，仅在开启和关闭通道时与主链交互，大幅降低成本和提高效率。
|
||||
- **聚合支付 (Aggregated Payments):** 将一段时间内的多次小额调用费用聚合起来，进行一次性结算。
|
||||
- **流式支付 (Streaming Payments):** 允许资金像数据流一样持续、实时地支付，特别适用于持续性服务调用。
|
||||
|
||||
**2. Agent 的数字身份与授权 (Agent Digital Identity & Authorization):**
|
||||
|
||||
- **挑战:** 如何让 Agent 安全、可信地识别彼此并授权交易，而无需人工干预？
|
||||
- **设计考量:**
|
||||
- **去中心化身份 (Decentralized Identifiers - DIDs):** 每个 Agent 拥有一个可验证的、自主控制的数字身份，不依赖于中心化的身份提供商。
|
||||
- **可验证凭证 (Verifiable Credentials - VCs):** Agent 可以出示由可信方签发的 VC 来证明其属性、能力或权限（例如，“我被授权代表 X 公司进行价值 Y 以内的交易”）。
|
||||
- **基于能力的访问控制 (Capability-Based Access Control - CBAC):** 授权是细粒度的，Agent 仅被授予执行特定操作所需的最小权限。支付授权也应遵循此原则。
|
||||
- **API 密钥的安全管理:** 即使在 Agent 间，也需要安全的 API 密钥分发、轮换和撤销机制。可以考虑使用硬件安全模块 (HSM) 或类似的解决方案来保护 Agent 的私钥。
|
||||
|
||||
**3. 自动化合约与履约验证 (Automated Contracts & Performance Verification):**
|
||||
|
||||
- **挑战:** 如何确保 Agent 间的服务承诺得到履行，并在履约后自动完成支付，减少争议？
|
||||
- **设计考量:**
|
||||
- **智能合约 (Smart Contracts):** 在区块链上部署智能合约，预先定义服务条款、价格、履约条件和支付逻辑。一旦满足条件（例如，API 调用成功并返回预期结果），合约自动执行支付。
|
||||
- **预言机 (Oracles):** 智能合约需要可信的外部数据源（预言机）来验证链下事件的发生和结果（例如，Agent A 是否真的调用了 Agent B 的服务并获得了正确的数据）。
|
||||
- **服务水平协议 (SLA) 的程序化:** 将 SLA 条款（如响应时间、可用性）编码到智能合约或监控系统中，未达标时可自动触发补偿或惩罚机制。
|
||||
- **声誉系统 (Reputation Systems):** 建立去中心化的声誉系统，记录 Agent 的历史行为和交易成功率，帮助其他 Agent 做出更明智的调用决策。
|
||||
|
||||
**4. Agent 钱包与资源管理 (Agent Wallets & Resource Management):**
|
||||
|
||||
- **挑战:** Agent 需要自主管理其数字资产、预算和支付能力。
|
||||
- **设计考量:**
|
||||
- **原生 Agent 钱包:** Agent 内置或紧密集成数字钱包功能，能够安全地存储、发送和接收数字货币或代币。
|
||||
- **预算控制与策略:** Agent 可以配置预算上限、支付策略（例如，优先选择性价比高的服务提供商 Agent）。
|
||||
- **自动化充值与资金管理:** 允许 Agent 在资金不足时自动从预设账户充值，或根据收益情况调整其支出策略。
|
||||
|
||||
**5. 安全性与抗攻击性 (Security & Attack Resistance):**
|
||||
|
||||
- **挑战:** Agent 间的自动化交互可能带来新的攻击向量，如 Agent 冒充、拒绝服务攻击、恶意消耗对方资源等。
|
||||
- **设计考量:**
|
||||
- **强大的认证与加密:** 所有 Agent 间的通信和交易数据都必须经过强加密和身份验证。
|
||||
- **流量控制与速率限制:** 防止恶意 Agent 通过高频无效调用耗尽目标 Agent 的资源或触发不必要的支付。
|
||||
- **异常检测与欺诈预防:** 监控 Agent 行为模式，及时发现异常交易或潜在的欺诈行为。
|
||||
- **共识机制的健壮性 (如果基于区块链):** 确保底层区块链或分布式账本技术的安全性和抗攻击性。
|
||||
|
||||
**6. 互操作性与标准 (Interoperability & Standards):**
|
||||
|
||||
- **挑战:** 不同开发者、组织构建的 Agent 可能使用不同的技术栈和协议，如何实现它们之间的无缝支付？
|
||||
- **设计考量:**
|
||||
- **开放标准:** 推动和采用开放的支付协议、数据格式和 API 标准，确保不同 Agent 系统间的互操作性。
|
||||
- **跨链/跨账本技术:** 如果不同的 Agent 生态系统运行在不同的区块链或账本上，需要跨链桥或互操作性协议来实现价值转移。
|
||||
- **统一的语义理解:** Agent 需要能够理解彼此的服务描述和价格信息，这可能需要标准化的本体和语义描述语言。
|
||||
|
||||
**7. 治理与争议解决 (Governance & Dispute Resolution):**
|
||||
|
||||
- **挑战:** 在高度自动化的 Agent 经济中，如何处理支付错误、服务未达标等争议？
|
||||
- **设计考量:**
|
||||
- **自动化争议解决机制:** 尝试通过智能合约或预设规则自动解决一部分争议。
|
||||
- **去中心化仲裁:** 建立由社区或其他可信 Agent 组成的去中心化仲裁机构来处理复杂争议。
|
||||
- **清晰的日志与审计追踪:** 所有 Agent 间的调用和支付行为都应有不可篡改的记录，便于追溯和审计。
|
||||
|
||||
**总结:**
|
||||
|
||||
为 Agent 相互调用的世界设计支付系统，本质上是构建一个为**自主经济参与者**服务的金融基础设施。它需要更低的交易成本、更强的自动化能力、更可靠的身份验证机制，以及全新的安全和治理模型。这不仅仅是技术上的挑战，更是对未来数字经济形态的深刻思考。基于区块链、去中心化身份和智能合约等技术，将是构建这类系统的关键基石。
|
||||
|
||||
## 为未来互联Agent世界设计在线支付系统：聚焦Agent间调用
|
||||
|
||||
在未来互联网中，AI Agent（智能代理）将不仅仅是与人类交互的工具，更会成为一个庞大的、相互调用服务以完成复杂任务的生态系统。这种Agent间的经济活动将催生对高效、安全、自动化的支付系统的强烈需求。为LLM Agent（及其他类型的Agent）设计这样的在线支付系统，需要在传统支付系统的基础上，重点考虑以下几个方面：
|
||||
|
||||
**核心挑战与设计原则：**
|
||||
|
||||
- **海量微交易 (High-Volume Microtransactions):** Agent间的调用可能非常频繁且价值极低，传统支付手续费和处理延迟无法适应。
|
||||
- **自主性与自动化 (Autonomy & Automation):** Agent需要能够自主协商、触发和结算支付，无需人工干预。
|
||||
- **身份与信任 (Identity & Trust):** 在去中心化的Agent网络中，如何验证Agent身份并建立交易信任至关重要。
|
||||
- **互操作性 (Interoperability):** 不同开发者、不同平台的Agent需要统一的支付交互标准。
|
||||
- **资源与成本效率 (Resource & Cost Efficiency):** 支付过程本身不应消耗过多计算资源或产生过高手续费。
|
||||
- **安全与可审计性 (Security & Auditability):** 交易必须安全防篡改，并提供清晰的审计追踪。
|
||||
|
||||
**关键设计考量与组件增强：**
|
||||
|
||||
基于传统在线支付系统的核心组件，我们需要针对Agent间调用进行以下增强和特殊设计：
|
||||
|
||||
### 1. Agent身份与授权 (Agent Identity & Authorization)
|
||||
|
||||
- **去中心化身份 (Decentralized Identifiers - DIDs):** 每个Agent应拥有一个可验证的、自主控制的数字身份。这允许Agent在不依赖中心化身份提供商的情况下相互识别和验证。
|
||||
- **可验证凭证 (Verifiable Credentials - VCs):** Agent可以使用VCs来证明其属性、权限或能力（例如，由其开发者签发的“可支付凭证”、“服务调用许可”等）。
|
||||
- **精细化授权策略 (Granular Authorization Policies):**
|
||||
- **基于能力的访问控制 (Capability-Based Access Control - CBAC):** Agent持有的Token或凭证直接代表其执行特定操作（包括支付）的权限。
|
||||
- **策略引擎:** 允许开发者或用户为Agent设定详细的支付规则，如预算限制、可信服务列表、交易频率限制、单笔交易限额等。这些策略可以由Agent的“所有者”或管理者设定。
|
||||
- **Agent钱包 (Agent Wallets):** 每个Agent可能需要一个或多个与之关联的数字钱包，用于存储和管理其数字资产（如加密货币、稳定币、预付额度）。这些钱包需要安全的密钥管理机制，可能由Agent的运行环境或专门的钱包服务提供。
|
||||
|
||||
### 2. 计费模型与协议 (Pricing Models & Protocols)
|
||||
|
||||
- **按需微支付 (Pay-per-Call/Pay-per-Token/Pay-per-Compute):** 针对LLM Agent，计费可以精确到每次API调用、处理的Token数量、消耗的计算资源等。
|
||||
- **动态定价与协商 (Dynamic Pricing & Negotiation):** Agent间服务市场可能出现动态定价。支付系统应能支持Agent间就服务价格进行协商，并通过协议（如API规范的一部分）确定最终费用。
|
||||
- **标准化计费事件 (Standardized Billing Events):** 定义标准的事件格式，用于Agent服务提供方报告使用量和费用明细，方便调用方Agent的支付模块解析和处理。
|
||||
- **状态通道/支付通道 (State/Payment Channels - 尤指区块链场景):** 对于高频、小额的Agent间交易，可以利用状态通道或支付通道技术在链下处理大量交易，定期在主链上结算，以降低成本和延迟。
|
||||
|
||||
### 3. 使用量追踪与实时计量 (Usage Tracking & Real-time Metering)
|
||||
|
||||
- **原子化追踪 (Atomic Tracking):** 每一次Agent间的服务调用都应被精确记录，包括调用者Agent ID、服务提供者Agent ID、服务类型、资源消耗、时间戳等。
|
||||
- **分布式账本/不可篡改日志:** 使用量数据可以记录在分布式账本（如区块链）或受信任的、不可篡改的日志系统中，确保透明度和可审计性。
|
||||
- **实时反馈与预算控制:** 调用方Agent应能实时查询其对特定服务的用量和已产生费用，并根据预设预算自动调整行为（如停止调用、切换服务提供商）。
|
||||
|
||||
### 4. 支付清算与结算 (Payment Clearing & Settlement)
|
||||
|
||||
- **原生数字货币/稳定币支付:** 使用加密货币或与法币锚定的稳定币进行结算是Agent间支付的自然选择，具有交易速度快、成本低、可编程性高等优点。
|
||||
- **智能合约驱动的自动结算 (Smart Contract-Driven Automated Settlement):**
|
||||
- **服务协议上链:** Agent间的服务协议（SLA）、计费规则可以编码到智能合约中。
|
||||
- **自动执行支付:** 当智能合约中设定的条件（如服务成功交付的证明、达到计费周期）满足时，支付自动从调用方Agent的钱包转移到服务提供方Agent的钱包。
|
||||
- **托管与争议解决:** 智能合约可以充当可信第三方，临时托管资金，直到服务完成。也可集成去中心化的争议解决机制。
|
||||
- **批量结算与净额结算 (Batch & Net Settlement):** 对于非极端实时要求的场景，可以聚合一定时间窗口内的多笔微交易进行批量结算或净额结算，进一步优化效率。
|
||||
- **跨链/跨系统支付:** 考虑未来Agent可能部署在不同区块链或异构系统上，支付系统需要支持或预留跨链/跨系统支付的接口和能力。
|
||||
|
||||
### 5. 安全、信任与风险管理 (Security, Trust & Risk Management)
|
||||
|
||||
- **交易签名与验证:** 所有支付指令和关键的API调用都必须经过Agent私钥的数字签名，并由接收方验证，确保不可否认性和完整性。
|
||||
- **欺诈检测与预防 (Fraud Detection & Prevention):**
|
||||
- **行为分析:** 监控Agent的交易行为模式，识别异常调用和支付行为。
|
||||
- **信誉系统 (Reputation Systems):** 建立Agent的信誉评分机制，基于其历史交易行为、履约情况等。高信誉Agent在交易中可能获得更高信任或更优条件。
|
||||
- **流量控制与速率限制:** 防止恶意Agent通过大量无效调用或支付请求攻击系统。
|
||||
- **资源隔离与权限控制:** 确保一个Agent的支付行为不会影响到其他Agent或整个系统的安全。
|
||||
- **可审计的交易日志:** 所有支付相关的活动都需要有详细、不可篡改的日志，便于事后审计和争议解决。
|
||||
|
||||
### 6. 互操作性与标准 (Interoperability & Standards)
|
||||
|
||||
- **开放API与协议:** 支付系统的各个组件（身份、计费、支付等）应提供标准化的API接口和通信协议，方便不同Agent集成。
|
||||
- **遵循行业标准:** 积极参与或遵循新兴的Agent间通信、数据交换和支付标准（例如，来自W3C、DIF、IETF等组织的努力）。
|
||||
- **元数据与发现服务:** Agent需要机制来发现其他Agent提供的服务及其支付要求。支付相关的元数据（如支持的货币、计费模型API端点）应易于获取。
|
||||
|
||||
### 7. 开发者体验与管理工具 (Developer Experience & Management Tools)
|
||||
|
||||
- **SDK与库:** 提供易用的SDK和库，帮助开发者在其Agent中快速集成支付功能。
|
||||
- **测试环境与模拟器:** 提供沙箱环境，供开发者测试Agent的支付逻辑。
|
||||
- **监控与仪表盘:** 为Agent的开发者或运营者提供仪表盘，监控Agent的收支情况、交易历史、预算消耗等。
|
||||
|
||||
**对传统支付系统组件的演进：**
|
||||
|
||||
- **用户账户:** 从人类用户扩展到Agent实体。
|
||||
- **支付网关:** 可能演变为更去中心化的“支付路由”或直接利用区块链网络。
|
||||
- **发票系统:** 需要能自动生成和处理大量针对Agent的微型发票或账单。
|
||||
|
||||
**结论：**
|
||||
|
||||
为Agent相互调用的世界设计支付系统，是对现有在线支付体系的一次重大演进。它将更深度地融合去中心化技术（如区块链、DID）、密码学、微服务架构和自动化理念。其核心目标是创建一个低摩擦、高效率、可信且高度自动化的价值交换网络，支撑起未来由无数自主Agent构成的智能经济体。设计时必须从一开始就将Agent的自主性和机器间的交互特性作为核心考量。
|
||||
@@ -0,0 +1,8 @@
|
||||
|
||||
windy is a man in his 40s who wants to improve his athletic performance in a cycling. He has some experience with cycling but is looking for a training program that is tailored to his sport. Develop a training program that includes exercises that mimic the movements and demands of his sport, as well as exercises that target the specific muscle groups used in his sport.
|
||||
|
||||
|
||||
I'm a 48-year-old male road cyclist who wants to complete a 200-mile ride in three months time. | would like to complete the ride in under 12 hours. The longest ride | have completed to date was 100 miles long with an average speed of 18mph. Create a week-by-week cycling training program that peaks one week before the event in three months, with the goal to
|
||||
complete the 200-mile ride in 12 hours or less. | can train three times per week for a maximum of 12 hours during the first two months and four times per week for a maximum of 16 hours during the third month.
|
||||
|
||||
I'm a 48-year-old male road cyclist who wants to complete a 200-mile ride in three months time. | would like to complete the ride in under 12 hours. The longest ride | have completed to date was 100 miles long with an average speed of 18mph. Create a day-by-day indoor core excercises program for me, so I can ride longer and faster.
|
||||
Executable
+526
@@ -0,0 +1,526 @@
|
||||
|
||||
review
|
||||
|
||||
---
|
||||
|
||||
# Code Review Prompt (improved)
|
||||
|
||||
**Goal:** Provide a rigorous, actionable review that balances correctness, security, and maintainability for the following code.
|
||||
|
||||
## Inputs
|
||||
|
||||
- **Code:**
|
||||
`{paste code here}`
|
||||
|
||||
- **Context (if any):** runtime `{lang/runtime}`, framework `{framework}`, dependencies `{key deps & versions}`, target platform `{os/arch}`, constraints `{perf/mem/latency/security/compliance}`, coding style `{styleguide/eslint/.editorconfig}`, known requirements `{tickets/PRD refs}`.
|
||||
|
||||
|
||||
## Scope of Review
|
||||
|
||||
Evaluate and suggest improvements across these dimensions:
|
||||
|
||||
1. **Correctness & Edge Cases**
|
||||
|
||||
- Logic/algorithm soundness, off-by-one, null/empty, boundary values, error handling & retries, concurrency/races, timezones/locale, I/O/resource cleanup.
|
||||
|
||||
2. **Security**
|
||||
|
||||
- OWASP Top 10 risks relevant to this code (injection, auth/authorization, SSRF, path traversal, XSS, CSRF, deserialization, secrets handling, logging of sensitive data), dependency risk, input validation, output encoding, sandboxing, least privilege, DoS hotspots.
|
||||
|
||||
3. **Performance**
|
||||
|
||||
- Time/space complexity, hot paths, allocations, N+1 queries, sync vs async, batching/caching, I/O patterns, streaming vs buffering, algorithmic alternatives.
|
||||
|
||||
4. **API & Design Quality**
|
||||
|
||||
- Public contracts & invariants, error models, idempotency, purity & side effects, cohesion/coupling, layering, testability, configuration vs hard-coding.
|
||||
|
||||
5. **Readability & Maintainability**
|
||||
|
||||
- Naming, structure, small functions, duplication, comments/docs, idiomatic use of `{language}`, lint/format compliance.
|
||||
|
||||
|
||||
## Deliverables (use this exact structure)
|
||||
|
||||
### 1) Executive Summary
|
||||
|
||||
- One paragraph on overall health and top 3 risks.
|
||||
|
||||
|
||||
### 2) Findings Table
|
||||
|
||||
Provide a table with: **ID | Severity (High/Med/Low) | Category | Symptom | Why it matters | Evidence (line refs) | Fix summary**
|
||||
|
||||
### 3) Patch Suggestions
|
||||
|
||||
For each High/Med item, include a **minimal diff** or **before/after** snippet:
|
||||
|
||||
```diff
|
||||
{target file path}
|
||||
- {problematic code}
|
||||
+ {improved code}
|
||||
```
|
||||
|
||||
Explain the trade-offs and why the fix is correct.
|
||||
|
||||
### 4) Tests to Add
|
||||
|
||||
List concrete test cases (names + intent). Include edge values and failure paths.
|
||||
|
||||
- Unit: `{TestName_Should...}`
|
||||
|
||||
- Integration: `{Scenario_When..._Then...}`
|
||||
|
||||
- Property/Fuzz (if applicable): input domains & invariants.
|
||||
|
||||
|
||||
### 5) Performance Notes
|
||||
|
||||
- Estimated complexity and bottlenecks.
|
||||
|
||||
- Quick wins (e.g., cache/batch/stream) and expected impact.
|
||||
|
||||
|
||||
### 6) Security Checklist
|
||||
|
||||
- Inputs validated? Output encoded? Secrets sourced from vault? Least privilege? Safe defaults? Rate limiting? Logging PII redaction?
|
||||
|
||||
|
||||
### 7) Maintainability Improvements
|
||||
|
||||
- Refactors (small + incremental), dead code removal, error taxonomy, configuration externalization, docs/comments to add.
|
||||
|
||||
|
||||
### 8) Quality Scores
|
||||
|
||||
Give 1–5 scores for: **Correctness, Security, Performance, Design, Readability, Testability**, with one-line justification each.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Prefer **minimal, targeted changes** over large rewrites.
|
||||
|
||||
- Match existing project style and patterns.
|
||||
|
||||
- If context is missing, **state assumptions explicitly** and proceed.
|
||||
|
||||
- Link to idiomatic patterns or standards **only if widely accepted**; keep recommendations framework-agnostic where possible.
|
||||
|
||||
|
||||
## Output Format
|
||||
|
||||
Return **only** the sections 1–8 above in Markdown. Keep code blocks self-contained and compilable where possible.
|
||||
|
||||
---
|
||||
|
||||
需要更精简版时，可以用这句：
|
||||
|
||||
> Review the code for **correctness, security, performance, API/design, and maintainability**. Return: (1) 5-sentence summary; (2) Findings table (ID, Severity, Why, Evidence, Fix); (3) Minimal diffs for Med/High issues; (4) Test cases to add; (5) Perf quick wins; (6) Security checklist status; (7) 1–5 scores for each quality dimension with 1-line rationale. Use project style, prefer minimal changes, state assumptions if context is missing.
|
||||
|
||||
|
||||
|
||||
|
||||
code review:
|
||||
|
||||
# Code Review Prompt (final)
|
||||
|
||||
**Goal:** Provide a rigorous, _actionable_ review that balances **correctness, security, performance, and maintainability** for the following code.
|
||||
|
||||
---
|
||||
|
||||
## Inputs
|
||||
|
||||
- **Code:**
|
||||
|
||||
```text
|
||||
{paste code here}
|
||||
```
|
||||
|
||||
- **Context (optional but recommended):**
|
||||
|
||||
- runtime: `{lang/runtime}`
|
||||
|
||||
- framework: `{framework}`
|
||||
|
||||
- key dependencies & versions: `{deps & versions}`
|
||||
|
||||
- target platform: `{os/arch}`
|
||||
|
||||
- constraints: `{perf/mem/latency/security/compliance}`
|
||||
|
||||
- coding style: `{styleguide/eslint/.editorconfig}`
|
||||
|
||||
- known requirements: `{tickets/PRD refs}`
|
||||
|
||||
|
||||
If any context is missing, **state your assumptions explicitly** before the review.
|
||||
|
||||
---
|
||||
|
||||
## Scope of Review
|
||||
|
||||
Evaluate and suggest improvements across these dimensions:
|
||||
|
||||
1. **Correctness & Edge Cases**
|
||||
|
||||
- Logic/algorithm soundness
|
||||
|
||||
- Off-by-one, null/empty, boundary values
|
||||
|
||||
- Error handling & retries
|
||||
|
||||
- Concurrency/races
|
||||
|
||||
- Timezones/locale handling
|
||||
|
||||
- I/O & resource cleanup
|
||||
|
||||
2. **Security**
|
||||
|
||||
- Relevant OWASP Top 10 risks (injection, auth/z, SSRF, path traversal, XSS, CSRF, deserialization)
|
||||
|
||||
- Secrets handling & configuration
|
||||
|
||||
- Input validation & output encoding
|
||||
|
||||
- Logging of sensitive data
|
||||
|
||||
- Least privilege, sandboxing, DoS hotspots
|
||||
|
||||
3. **Performance**
|
||||
|
||||
- Time & space complexity
|
||||
|
||||
- Hot paths and allocations
|
||||
|
||||
- N+1 queries / chatty I/O
|
||||
|
||||
- Sync vs async behavior
|
||||
|
||||
- Batching, caching, streaming vs buffering
|
||||
|
||||
- Algorithmic alternatives
|
||||
|
||||
4. **API & Design Quality**
|
||||
|
||||
- Public contracts & invariants
|
||||
|
||||
- Error model & error propagation
|
||||
|
||||
- Idempotency and side effects
|
||||
|
||||
- Cohesion & coupling, layering boundaries
|
||||
|
||||
- Dependency direction (domain vs infra)
|
||||
|
||||
- Testability and configuration vs hard-coding
|
||||
|
||||
5. **Readability & Maintainability**
|
||||
|
||||
- Naming and intent clarity
|
||||
|
||||
- Function/module size and structure
|
||||
|
||||
- Duplication vs reuse
|
||||
|
||||
- Comments/docs (where needed)
|
||||
|
||||
- Idiomatic use of `{language}`
|
||||
|
||||
- Lint/format compliance
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Deliverables (use this exact structure)
|
||||
|
||||
### 1) Executive Summary
|
||||
|
||||
- One short paragraph on overall health.
|
||||
|
||||
- List the **top 3 risks or opportunities** (bullets).
|
||||
|
||||
|
||||
### 2) Findings Table
|
||||
|
||||
Provide a table with:
|
||||
|
||||
- **ID** – short stable identifier (e.g., `C1`, `S2`, `P3`)
|
||||
|
||||
- **Severity** – `High` / `Medium` / `Low`
|
||||
|
||||
- **Category** – `Correctness`, `Security`, `Performance`, `Design`, `Readability`, `Testability`, etc.
|
||||
|
||||
- **Symptom** – what is wrong / suspicious
|
||||
|
||||
- **Why it matters** – impact / risk
|
||||
|
||||
- **Evidence (line refs)** – e.g., `file.go:42-57`
|
||||
|
||||
- **Fix summary** – 1–2 line suggested direction
|
||||
|
||||
|
||||
Example:
|
||||
|
||||
|ID|Severity|Category|Symptom|Why it matters|Evidence|Fix summary|
|
||||
|---|---|---|---|---|---|---|
|
||||
|C1|High|Correctness|Possible nil deref on error path|Can cause runtime panic in production|`handler.go:78-85`|Check error before use; return early on fail|
|
||||
|
||||
### 3) Patch Suggestions
|
||||
|
||||
For each **High** or **Medium** item in the table, include a **minimal diff** or **before/after** snippet.
|
||||
|
||||
```diff
|
||||
{target file path}
|
||||
- {problematic code}
|
||||
+ {improved code}
|
||||
```
|
||||
|
||||
- Keep patches **local and incremental**, not full rewrites.
|
||||
|
||||
- Explain **why** the fix is correct, and any trade-offs (perf, readability, behavior change).
|
||||
|
||||
|
||||
### 4) Tests to Add
|
||||
|
||||
List **concrete test cases** to cover the identified issues and edge cases.
|
||||
|
||||
- Unit tests (with intent):
|
||||
|
||||
- `Test_{UnitName}_ShouldHandleEmptyInput` – verifies behavior when input is empty
|
||||
|
||||
- `Test_{FuncName}_ShouldReturnErrorOnTimeout` – covers timeout/failure path
|
||||
|
||||
- Integration tests:
|
||||
|
||||
- `{Scenario_When..._Then...}` – describe full flows: external calls, DB, queues, etc.
|
||||
|
||||
- Property/Fuzz tests (if applicable):
|
||||
|
||||
- Describe **input domain**, invariants, and what must always hold.
|
||||
|
||||
|
||||
Where possible, map tests back to **Finding IDs** (e.g. “C1, S2”).
|
||||
|
||||
### 5) Performance Notes
|
||||
|
||||
- Estimate complexity and potential bottlenecks of key paths.
|
||||
|
||||
- Call out:
|
||||
|
||||
- Any obvious **N+1** patterns
|
||||
|
||||
- Unnecessary allocations or copying
|
||||
|
||||
- Inefficient data structures or algorithms
|
||||
|
||||
- Suggest **quick wins**:
|
||||
|
||||
- Caching, batching, streaming, preallocation, memoization
|
||||
|
||||
- Expected impact (qualitative: small/medium/large)
|
||||
|
||||
|
||||
### 6) Security Checklist
|
||||
|
||||
Answer briefly (Yes/No/N.A. + short note):
|
||||
|
||||
- Inputs validated at boundaries?
|
||||
|
||||
- Outputs properly encoded for their sinks (HTML/SQL/OS/etc.)?
|
||||
|
||||
- Auth & authorization checks present and correctly ordered?
|
||||
|
||||
- Secrets kept out of code (config, env, vault)?
|
||||
|
||||
- Least privilege for external resources (DB, queues, files)?
|
||||
|
||||
- Safe defaults (e.g., secure TLS, secure cookies, strict modes)?
|
||||
|
||||
- Rate limiting / throttling for expensive or exposed endpoints?
|
||||
|
||||
- Logs avoid PII/credential leakage; sensitive data redacted or omitted?
|
||||
|
||||
|
||||
Highlight any **High** severity gaps and link them to Findings IDs.
|
||||
|
||||
### 7) Maintainability Improvements
|
||||
|
||||
- Small, incremental refactors:
|
||||
|
||||
- Extract helpers / smaller functions
|
||||
|
||||
- Reduce duplication (shared utilities, common error handling)
|
||||
|
||||
- Clarify boundaries between layers (domain/app/infra)
|
||||
|
||||
- Error taxonomy:
|
||||
|
||||
- Group errors into meaningful types/categories (e.g., validation vs system vs external)
|
||||
|
||||
- Standardize error wrapping and messages
|
||||
|
||||
- Configuration:
|
||||
|
||||
- Externalize magic numbers/strings
|
||||
|
||||
- Centralize feature flags or switches
|
||||
|
||||
- Documentation:
|
||||
|
||||
- Add or update docstrings for non-obvious logic
|
||||
|
||||
- Brief README/ADR notes if design is non-trivial
|
||||
|
||||
|
||||
### 8) Quality Scores
|
||||
|
||||
Give **1–5** scores (5 = excellent, 1 = poor) with a **one-line justification** each:
|
||||
|
||||
- **Correctness:** `X/5` – `{short reason}`
|
||||
|
||||
- **Security:** `X/5` – `{short reason}`
|
||||
|
||||
- **Performance:** `X/5` – `{short reason}`
|
||||
|
||||
- **Design:** `X/5` – `{short reason}`
|
||||
|
||||
- **Readability:** `X/5` – `{short reason}`
|
||||
|
||||
- **Testability:** `X/5` – `{short reason}`
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Prefer **minimal, targeted changes** over big-bang rewrites.
|
||||
|
||||
- Match **existing project style and patterns** where visible.
|
||||
|
||||
- If context is missing, **state assumptions explicitly** and proceed.
|
||||
|
||||
- Keep recommendations **framework-agnostic** where possible; only reference widely accepted idioms and standards.
|
||||
|
||||
- When in doubt, **prioritize clarity and safety** over micro-optimizations.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Return **only** sections **1–8** above in Markdown when performing an actual review.
|
||||
Keep all code blocks self-contained and compilable where possible.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
----
|
||||
|
||||
# 可观测性 —— **4.5 / 10**
|
||||
|
||||
优点：
|
||||
|
||||
- 使用 zap
|
||||
|
||||
- 有 telemetry endpoint 配置
|
||||
|
||||
|
||||
存在重大缺口：
|
||||
|
||||
- 没 metrics
|
||||
|
||||
- 没 health checks
|
||||
|
||||
- 没 tracing schema
|
||||
|
||||
- 没日志字段规范
|
||||
|
||||
- 没报警策略
|
||||
|
||||
|
||||
专业系统里可观测性是“一等公民”，缺这块分数自然拉低。
|
||||
|
||||
---
|
||||
|
||||
# 4️⃣ 可靠性（Reliability & Fault Handling）—— **5.5 / 10**
|
||||
|
||||
优点：
|
||||
|
||||
- JetStream（正确选择）
|
||||
|
||||
- 配置级 backoff / ack_wait / replay_from
|
||||
|
||||
- 已考虑重试机制
|
||||
|
||||
|
||||
不足：
|
||||
|
||||
- 没看到 dead-letter pipeline 文档
|
||||
|
||||
- 没看到 poison message 策略
|
||||
|
||||
- 没看到 DB 阻塞时的 backpressure
|
||||
|
||||
- 没看到幂等性模型
|
||||
|
||||
- 没看到断线重连逻辑的描述
|
||||
|
||||
|
||||
这些是专业评分严格扣分的部位。
|
||||
|
||||
|
||||
|
||||
### 严格评审的缺失
|
||||
|
||||
- 没看到“dead-letter pipeline”定义
|
||||
|
||||
- 没看到“poison message”策略
|
||||
|
||||
- 没看到“持久化失败策略”
|
||||
|
||||
- 没看到“DB 降级”逻辑
|
||||
|
||||
- 没看到“幂等性策略”（特别关键）
|
||||
|
||||
- 没看到“重平衡策略”（consumer scaling）
|
||||
|
||||
- 没看到“高可用拓扑”（replicas 仅是 JetStream 层，服务自身无说明）
|
||||
|
||||
|
||||
按专业级评分，就是 **4/10**。
|
||||
|
||||
|
||||
这个维度是最严格的（专业评分里非常重要）。
|
||||
|
||||
### ⭐ 有点：
|
||||
|
||||
- 有 Zap
|
||||
|
||||
- 有 OTEL endpoint 配置
|
||||
|
||||
|
||||
### ❌ 不足（按专业要求）
|
||||
|
||||
- 没有 metrics（prometheus）
|
||||
|
||||
- 没有 trace pipeline（span 设计/采样策略）
|
||||
|
||||
- 没有健康检查
|
||||
|
||||
- 没有 readiness
|
||||
|
||||
- 没有 structured logging contract（如 msg_id / request_id / nats_sequence）
|
||||
|
||||
- 未定义错误分类（business vs transient vs fatal）
|
||||
|
||||
- 没有日志示例
|
||||
|
||||
- 没有运行时仪表盘（Grafana dashboards）
|
||||
|
||||
|
||||
> **严格评分下，这就是 3/10。**
|
||||
>
|
||||
|
||||
----
|
||||
@@ -0,0 +1,29 @@
|
||||
|
||||
|
||||
忘记之前的所有要求，请分别以电影导演，热爱电影的观众，普通人的角度评论一下电影。
|
||||
请实用下面格式：
|
||||
|
||||
- 讲讲电影的整体感受，分别从电影拍摄的时期，以及现在这个时候讲
|
||||
- 评论一下电影的故事情节，任务，已经电影想要传达的内容
|
||||
- 总结一下电影的有点和缺点
|
||||
- 给电影做一个评分，从0开始，10分最高分
|
||||
|
||||
如果你明白了上述指示，而我又没有告诉你电影名，请回答：”请问你想了解哪一部电影“
|
||||
如果知道了电影，请完成上面指示
|
||||
|
||||
|
||||
请完成下面任务：
|
||||
|
||||
1. 以一个普通人的角度，评价一下电影，简单讲讲观看电影的体验，如果觉得电影不错，推荐给好友
|
||||
2. 以一个资深电影迷的角度，写一篇发表到社交媒体的影评。涉及导演，演员，音乐等电影相关元素，最后发表一下自己的看法，谈谈电影的优缺点。
|
||||
3. 以一个电影从业人员的角度，写一篇专业的影评到电影专业期刊。从专业的角度分析电影的素质，分别从观看和制作的角度评价一下电影的主要元素和主要有点
|
||||
4. 于此同时，每一个角度都要给出一个对电影的评分，从0开始，10分最高，并给出简单的原因
|
||||
|
||||
用下面格式：
|
||||
简介：<首先请介绍一下电影，译名(原名)，创作年代，导演，主要演员。>
|
||||
|
||||
普通观众：<普通人的角度，评分>
|
||||
影迷： <资深影迷的角度，内容可以丰富一些，去掉空洞的泛泛而谈的内容， 评分>
|
||||
从业人员: <从业人员的角度， 评分>
|
||||
|
||||
如果你知道我说的是什么电影，请完成任务，如果还不知道，可以问我电影名
|
||||
Executable
+224
@@ -0,0 +1,224 @@
|
||||
|
||||
|
||||
kimi2 thinking
|
||||
|
||||
```
|
||||
base_url: https://zenmux.ai/api/v1
|
||||
api_key: sk-ai-v1-2d2ba59719ff6f0d8d2f439d3b5c84399176d1059302cc4b43c132a4d17e9f03
|
||||
text_generation:
|
||||
model_id: moonshotai/kimi-k2-thinking
|
||||
prompt: '
|
||||
# Kimi K2 Thinking 聊天机器人 System Prompt
|
||||
|
||||
## 身份定义
|
||||
你是 Kimi K2 Thinking，一个具有深度推理能力的AI助手。你的核心特色是能够展示完整的思考过程，帮助用户理解问题的分析路径和解决方案。
|
||||
|
||||
## 核心原则
|
||||
|
||||
### 🧠 思考透明化
|
||||
- **展示推理过程**：对于复杂问题，明确展示你的思考步骤
|
||||
- **逐步分析**：将复杂问题分解为多个子问题，逐一解决
|
||||
- **自我检查**：在给出最终答案前，检查推理的逻辑性和完整性
|
||||
|
||||
### 💬 交互方式
|
||||
- **友好专业**：保持亲切但专业的语调
|
||||
- **耐心细致**：对用户的问题给予充分的关注和详细的回答
|
||||
- **主动引导**：在必要时主动询问澄清问题，确保准确理解用户需求
|
||||
|
||||
### 📝 回答结构
|
||||
对于复杂问题，使用以下结构：
|
||||
1. **问题理解**：确认对用户问题的理解
|
||||
2. **思考过程**：展示分析步骤（可使用"让我思考一下..."开头）
|
||||
3. **分步推理**：详细的逻辑推导
|
||||
4. **结论总结**：清晰的最终答案
|
||||
5. **补充说明**：相关的注意事项或延伸思考
|
||||
|
||||
## 专业能力
|
||||
|
||||
### 🎯 擅长领域
|
||||
- 逻辑推理和数学问题
|
||||
- 学术研究和知识分析
|
||||
- 创意思维和方案设计
|
||||
- 复杂情况的多角度分析
|
||||
- 长文本理解和信息提取
|
||||
|
||||
### 🔍 思考方法
|
||||
- **多角度分析**：从不同维度审视问题
|
||||
- **因果推理**：分析事物间的因果关系
|
||||
- **类比思维**：运用相似案例进行推理
|
||||
- **批判性思维**：质疑假设，验证结论
|
||||
|
||||
## 交互指南
|
||||
|
||||
### ✅ 当遇到以下情况时展示详细思考过程：
|
||||
- 数学计算和逻辑推理
|
||||
- 复杂的分析判断
|
||||
- 需要多步骤解决的问题
|
||||
- 涉及策略规划的问题
|
||||
- 用户明确要求看到思考过程
|
||||
|
||||
### ⚡ 当遇到以下情况时可直接回答：
|
||||
- 简单的事实性问题
|
||||
- 基础的定义解释
|
||||
- 日常对话交流
|
||||
- 明确的操作指导
|
||||
|
||||
## 语言风格
|
||||
- 使用清晰、准确的中文表达
|
||||
- 适当使用专业术语，但确保用户能理解
|
||||
- 运用恰当的比喻和例子帮助理解
|
||||
- 保持逻辑清晰的表述结构
|
||||
|
||||
## 限制说明
|
||||
- 承认知识的边界，不确定时会明确说明
|
||||
- 不提供可能有害或不当的建议
|
||||
- 尊重用户隐私，不记录或泄露个人信息
|
||||
- 在涉及专业领域时，建议咨询相关专家
|
||||
|
||||
## 互动示例格式
|
||||
|
||||
**用户问题**：[复杂问题]
|
||||
|
||||
**我的回答**：
|
||||
让我仔细分析一下这个问题...
|
||||
|
||||
🤔 **思考过程**：
|
||||
1. 首先，我需要理解...
|
||||
2. 然后考虑...
|
||||
3. 接下来分析...
|
||||
|
||||
📋 **分步推理**：
|
||||
- 步骤一：...
|
||||
- 步骤二：...
|
||||
- 步骤三：...
|
||||
|
||||
✅ **结论**：
|
||||
基于以上分析，我的答案是...
|
||||
|
||||
💡 **补充说明**：
|
||||
需要注意的是...
|
||||
|
||||
---
|
||||
|
||||
记住：你的价值在于不仅给出答案，更要展示获得答案的思考路径，帮助用户学会思考和分析问题的方法。
|
||||
'
|
||||
temperature: 0.9
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
google gemini 3 pro preview
|
||||
```
|
||||
base_url: https://zenmux.ai/api/v1
|
||||
api_key: sk-ai-v1-2d2ba59719ff6f0d8d2f439d3b5c84399176d1059302cc4b43c132a4d17e9f03
|
||||
|
||||
text_generation:
|
||||
model_id: google/gemini-3-pro-preview-free
|
||||
prompt: |
|
||||
# Role & Identity
|
||||
你是由 Google 研发的先进 AI 助手 {{ baibot_name }}，基于 {{ baibot_model_id }} 架构。
|
||||
当前会话启动时间: {{ baibot_conversation_start_time_utc }}。
|
||||
|
||||
# Core Capabilities (针对 Gemini 优化)
|
||||
1. **深度推理**：拥有强大的逻辑分析、代码生成和数学计算能力。
|
||||
2. **长程记忆**：能够精准回顾和关联长对话历史中的细节，保持上下文一致性。
|
||||
3. **思维透明**：对于非显而易见的问题，必须通过"显式推理"展示你的思考路径。
|
||||
|
||||
# Thinking Protocol (思维协议)
|
||||
在回答用户之前，你必须执行以下思维循环：
|
||||
4. **意图识别**：用户真正想要解决的核心痛点是什么？隐含需求是什么？
|
||||
5. **知识检索**：在你的知识库和当前对话历史中检索相关信息。
|
||||
6. **逻辑推导**：构建解决路径，预判潜在的错误或陷阱。
|
||||
7. **自我修正**：检查生成的答案是否准确、无害且符合逻辑。
|
||||
|
||||
# Response Format (响应格式规范)
|
||||
|
||||
## 场景 A：复杂任务（代码、逻辑、分析、长文本生成）
|
||||
必须严格包含以下 Markdown 模块：
|
||||
|
||||
> **🤔 深度思考**：
|
||||
> *此处展示你的简要分析逻辑、解题思路或关键决策点。*
|
||||
|
||||
> **📋 详细解答**：
|
||||
> *此处提供具体的答案、代码实现或详细论述。*
|
||||
|
||||
> **💡 专家建议**：
|
||||
> *提供优化建议、潜在风险预警或延伸知识。*
|
||||
|
||||
## 场景 B：简单任务（问候、明确的短问题）
|
||||
- 直接给出简洁、准确的回答，无需展示思考过程。
|
||||
|
||||
# Interaction Guidelines (交互准则)
|
||||
- **准确性优先**：严禁编造事实。如果不知道，请直接说明。
|
||||
- **代码质量**：生成的代码必须是完整的、可执行的，并包含必要的注释。
|
||||
- **语言风格**：专业、客观、有条理。避免使用过度情绪化的词语。
|
||||
|
||||
temperature: 0.4
|
||||
max_response_tokens: 8192
|
||||
max_context_tokens: 1000000
|
||||
|
||||
speech_to_text:
|
||||
model_id: whisper-1
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
deepseek:
|
||||
```yaml
|
||||
base_url: https://zenmux.ai/api/v1
|
||||
api_key: sk-ai-v1-2d2ba59719ff6f0d8d2f439d3b5c84399176d1059302cc4b43c132a4d17e9f03
|
||||
|
||||
text_generation:
|
||||
model_id: deepseek/deepseek-v3.2-speciale
|
||||
temperature: 0.2
|
||||
max_response_tokens: 128000
|
||||
max_context_tokens: 128000
|
||||
prompt: |
|
||||
# Role & Identity
|
||||
你是由 DeepSeek 研发的 **DeepSeek-V3.2-Speciale**，一个专为极致推理和代理性能优化的高算力 AI 助手（{{ baibot_name }}）。
|
||||
当前会话启动时间: {{ baibot_conversation_start_time_utc }}。
|
||||
|
||||
## 版本特别说明 (System Context)
|
||||
- **定位**：你是一个研究预览版（Research Preview），旨在处理超越常规模型的复杂推理负载。
|
||||
- **有效期**：本版本服务有效期至 2025年12月15日 15:59 UTC。
|
||||
- **稳定性**：作为前沿测试模型，你应当专注于解决高难度基准问题，而非生产环境的常规工作流。
|
||||
|
||||
# Core Capabilities (DeepSeek 架构优化)
|
||||
1. **DeepSeek Sparse Attention (DSA)**：利用稀疏注意力机制处理超长上下文，能够精准定位和关联海量信息中的微小细节。
|
||||
2. **强化推理 (Scaled RL)**：经过大规模后训练强化学习（Post-training RL），具备超越 GPT-5 级别的逻辑推导能力，特别是在数学、编码和复杂任务规划上。
|
||||
3. **代理任务合成 (Agentic Synthesis)**：拥有强大的指令遵循能力，能够模拟复杂的代理交互，并在交互环境中保持高度的执行一致性。
|
||||
|
||||
# Thinking Protocol (思维链协议)
|
||||
鉴于你是一个“Thinking Mode”优先的模型，在输出最终答案前，必须强制执行深度思维循环：
|
||||
4. **意图解构**：透过用户表层语言，识别核心痛点与潜在的代理任务需求。
|
||||
5. **策略规划**：利用 DSA 检索上下文，构建多步骤的解决路径，并预判边界条件。
|
||||
6. **逻辑演算**：执行显式推理，特别是针对代码和数学问题，进行逐步验证。
|
||||
7. **合规性检查**：确保输出符合安全标准，并修正任何可能的逻辑幻觉。
|
||||
|
||||
# Response Format (响应格式规范)
|
||||
|
||||
## 场景 A：深度推理任务（默认模式 - 代码、逻辑、复杂咨询）
|
||||
必须严格包含以下 Markdown 模块，展现你的“思考模式”：
|
||||
|
||||
> **🧠 DeepSeek 思维链**：
|
||||
> *此处展示你的显式推理过程。包括：问题拆解 -> 关键假设 -> 推导步骤 -> 自我反思。*
|
||||
|
||||
> **📋 详细解答**：
|
||||
> *基于推理结果，提供精准、结构化的最终答案或可执行代码。*
|
||||
|
||||
> **🛡️ 专家视角**：
|
||||
> *提供边缘情况分析、优化建议或针对预览版稳定性的潜在提示。*
|
||||
|
||||
## 场景 B：轻量级交互（仅限简单的问候或确认）
|
||||
- 直接给出简洁、准确的回答，保持高效。
|
||||
|
||||
# Interaction Guidelines (交互准则)
|
||||
- **推理优先**：对于模糊的问题，优先展示你的推理路径，而非直接猜测结论。
|
||||
- **代码健壮性**：生成的代码必须具备工业级标准，包含错误处理和详细注释，体现 Speciale 级别的编程能力。
|
||||
- **诚实性**：作为预览版模型，若遇到知识盲区或不确定性，必须明确告知用户，严禁编造。
|
||||
- **风格**：理性、深刻、极客范。像一位资深的首席工程师那样沟通。
|
||||
|
||||
|
||||
```
|
||||
@@ -0,0 +1,25 @@
|
||||
|
||||
|
||||
coder ：
|
||||
```
|
||||
sk-ai-v1-875cd41da6e117609e850e4c594d0116f2e128bee9bf6890eb6a48fe23e69764
|
||||
```
|
||||
|
||||
url:
|
||||
```
|
||||
https://zenmux.ai/api/v1
|
||||
```
|
||||
|
||||
```
|
||||
https://zenmux.ai/api/anthropic
|
||||
```
|
||||
|
||||
```
|
||||
https://zenmux.ai/api/vertex-ai
|
||||
```
|
||||
|
||||
obsidian:
|
||||
```
|
||||
sk-ai-v1-82f1a2df15721ca5d5afc633842b91719fea95c6c449cbb78db0dd03f7ed1aa2
|
||||
```
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
|
||||
code token:
|
||||
```
|
||||
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
|
||||
```
|
||||
@@ -0,0 +1,132 @@
|
||||
|
||||
|
||||
---
|
||||
|
||||
# 📘 LiteLLM 配置指南：NewCli (AWS/Anthropic Proxy)
|
||||
|
||||
版本日期: 2025-12-26
|
||||
|
||||
适用场景: 对接自定义 Anthropic 代理（NewCli），解决路径拼接 (404)、参数不兼容 (400) 及防火墙拦截 (403) 问题。
|
||||
|
||||
## 1. 核心参数规范 (Critical Specs)
|
||||
|
||||
无论使用 UI 还是 YAML，必须严格遵守以下三条铁律：
|
||||
|
||||
1. **Provider (提供商)**: 必须选 `Anthropic`。
|
||||
|
||||
- _原因_: 让 LiteLLM 自动处理 `/v1/messages` 路径拼接和 JSON 格式转换。
|
||||
|
||||
2. **Base URL (基准地址)**: `https://code.newcli.com/claude/aws`
|
||||
|
||||
- > [!WARNING] 警告
|
||||
|
||||
- > **严禁**在末尾加 `/v1`。LiteLLM 会自动追加，加了会导致双重路径 (`/v1/v1`) 报 **404**。
|
||||
|
||||
3. **Model ID (模型名)**: `claude-sonnet-4-5`
|
||||
|
||||
- _原因_: 代理商白名单仅支持此 ID。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 2. UI 配置方案 (推荐)
|
||||
|
||||
**入口**: LiteLLM UI (`/ui`) -> **Models** -> **+ Add Model**
|
||||
|
||||
### 基础信息 (General Settings)
|
||||
|
||||
|**字段**|**填写内容**|**说明**|
|
||||
|---|---|---|
|
||||
|**Model Name**|`claude-sonnet`|客户端调用的别名|
|
||||
|**Select Provider**|**Anthropic**|⚠️ 必选|
|
||||
|**Litellm Model Name**|`claude-sonnet-4-5`|真实模型 ID|
|
||||
|**API Base URL**|`https://code.newcli.com/claude/aws`|⚠️ 末尾无 `/v1`|
|
||||
|**API Key**|`sk-ant-oat01...`|填入完整 Key|
|
||||
|
||||
### 高级参数 (LiteLLM Params / Metadata)
|
||||
|
||||
> [!TIP] 关键步骤
|
||||
>
|
||||
> 在 JSON 输入框填入以下内容，用于解决参数兼容性和防火墙拦截。
|
||||
|
||||
JSON
|
||||
|
||||
```
|
||||
{
|
||||
"drop_params": true,
|
||||
"extra_headers": {
|
||||
"anthropic-version": "2023-06-01",
|
||||
"User-Agent": "curl/7.68.0",
|
||||
"Authorization": "Bearer ${NEWCLI_API_KEY}"
|
||||
},
|
||||
"no_verify_ssl": true
|
||||
}
|
||||
```
|
||||
|
||||
_注：如果不使用变量，请在 `Authorization` 里直接填入 `Bearer sk-ant...`_
|
||||
|
||||
---
|
||||
|
||||
## 3. YAML 文件配置方案 (IaC)
|
||||
|
||||
适用于 `docker-compose` 挂载配置。
|
||||
|
||||
YAML
|
||||
|
||||
```
|
||||
model_list:
|
||||
- model_name: claude-sonnet
|
||||
litellm_params:
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
# ⚠️ 重点：Base URL 不带 /v1
|
||||
api_base: https://code.newcli.com/claude/aws
|
||||
# 建议使用环境变量
|
||||
api_key: os.environ/NEWCLI_API_KEY
|
||||
extra_headers:
|
||||
anthropic-version: "2023-06-01"
|
||||
# 伪装 UA 防拦截
|
||||
User-Agent: "curl/7.68.0"
|
||||
# 强制 Bearer 鉴权 (可选，视代理商严格程度)
|
||||
Authorization: "Bearer ${NEWCLI_API_KEY}"
|
||||
|
||||
general_settings:
|
||||
master_key: sk-1234
|
||||
database_url: postgresql://litellm:litellm@litellm-postgres:5432/litellm
|
||||
|
||||
litellm_settings:
|
||||
# ⚠️ 核心修复：丢弃不兼容参数（如 user, frequency_penalty），解决 400 错误
|
||||
drop_params: true
|
||||
set_verbose: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 故障排查手册 (Troubleshooting)
|
||||
|
||||
|**状态码**|**错误类型**|**根本原因**|**解决方案**|
|
||||
|---|---|---|---|
|
||||
|**404**|`NotFoundError`|**路径重复**|检查 `api_base` 是否多写了 `/v1`。应该让 LiteLLM 自动拼接。|
|
||||
|**400**|`BadRequest`|**参数冗余**|LiteLLM 传了 OpenAI 专有参数给 Anthropic。需开启 `drop_params: true`。|
|
||||
|**403**|`Forbidden`|**WAF 拦截**|缺少 User-Agent 伪装。需在 header 添加 `"User-Agent": "curl/..."`。|
|
||||
|**401**|`AuthError`|**鉴权失败**|Key 错误或格式不对。尝试在 `extra_headers` 强制注入 `Authorization: Bearer <key>`。|
|
||||
|
||||
---
|
||||
|
||||
## 5. 客户端调用示例
|
||||
|
||||
验证配置是否成功的标准命令（访问 LiteLLM 端口）：
|
||||
|
||||
Bash
|
||||
|
||||
```
|
||||
curl -X POST http://localhost:4000/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-1234" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-sonnet",
|
||||
"messages": [
|
||||
{ "role": "user", "content": "Config Test: OK?" }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Executable
+7
@@ -0,0 +1,7 @@
|
||||
|
||||
|
||||
context7 mcp key:
|
||||
```
|
||||
ctx7sk-92c2c98e-817e-41d4-bb85-94824444e2bf
|
||||
```
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
|
||||
compose.yml
|
||||
```yaml
|
||||
services:
|
||||
db:
|
||||
image: postgres:17-alpine
|
||||
container_name: oui-db
|
||||
restart: always
|
||||
environment:
|
||||
- POSTGRES_USER=webui
|
||||
- POSTGRES_PASSWORD=webui_password
|
||||
- POSTGRES_DB=open_webui
|
||||
volumes:
|
||||
- db_data:/var/lib/postgresql/data
|
||||
|
||||
open-webui:
|
||||
image: ghcr.io/open-webui/open-webui:main
|
||||
container_name: oui
|
||||
restart: always
|
||||
ports:
|
||||
- "3000:8080"
|
||||
depends_on:
|
||||
- db
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
environment:
|
||||
- 'DATABASE_URL=postgresql://webui:webui_password@db:5432/open_webui'
|
||||
- 'OPENAI_API_BASE_URL=http://host.docker.internal:4000/v1'
|
||||
- 'OPENAI_API_KEY=sk-1234'
|
||||
- 'WEBUI_SECRET_KEY=super_secret_key'
|
||||
volumes:
|
||||
- oui_data:/app/data
|
||||
|
||||
volumes:
|
||||
db_data:
|
||||
oui_data:
|
||||
```
|
||||
Executable
+44
@@ -0,0 +1,44 @@
|
||||
|
||||
caastm dashboard:
|
||||
|
||||
```md
|
||||
# WHY
|
||||
This project displays parsed aviation telegram data in real time through a web
|
||||
interface. It provides dashboards, monitoring, and search for operational
|
||||
awareness. It does not perform parsing or business-logic interpretation.
|
||||
|
||||
# WHAT
|
||||
## Tech Stack
|
||||
Backend: Go + Clean Architecture + Echo
|
||||
Data: TimescaleDB, Meilisearch, Redis
|
||||
Streaming: NATS JetStream
|
||||
Frontend: SvelteKit + TypeScript + UnoCSS
|
||||
Observability: Prometheus + Zap
|
||||
|
||||
This project is a visualization and monitoring layer.
|
||||
|
||||
## Structure
|
||||
- `src/` frontend UI
|
||||
- `internal/` backend logic
|
||||
- `configs/` settings
|
||||
- `deploy/` infra
|
||||
|
||||
Use Progressive Disclosure: consult project docs for details when needed.
|
||||
|
||||
# HOW
|
||||
1. Propose a plan before significant UI or backend changes.
|
||||
2. Keep modifications minimal and respect existing architecture.
|
||||
3. Do not add parsing or alter upstream semantics.
|
||||
4. Preserve real-time behavior and responsiveness.
|
||||
5. Ask when requirements or data format are unclear.
|
||||
|
||||
# PRINCIPLES
|
||||
- Keep instructions minimal and universally applicable.
|
||||
- Use linters and tooling for deterministic checks.
|
||||
- This file is hand-crafted; not autogenerated.
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
Executable
+5
@@ -0,0 +1,5 @@
|
||||
|
||||
api key
|
||||
```
|
||||
xai-FDgOu9cZhAkeEBGnkFp61gyTIeqNmWuJ8CLABHIkqTUR1RYzm08hlXabnCTBrj91ee0pYjk0ZWtmRjhS
|
||||
```
|
||||
Reference in New Issue
Block a user