Skip to content

Commit 8c45b83

Browse files
wenermewenerme
committed
Add new documentation files and enhance existing content
- Created new FAQ documents for AI development and CUDA. - Added an "Awesome" section for AI agents and a detailed insight document for LiteLLM. - Introduced new entries in the MCP documentation, including insights and resources. - Expanded the design documentation with new UI components and API details. - Updated various service and workflow notes with additional resources and clarifications. - Enhanced logging and observability documentation with new logging levels and practices. - Added new entries for web technologies, including Tweakpane and PostCSS. - Improved the glossary and ideas sections with new terms and concepts.
1 parent aa9694b commit 8c45b83

File tree

36 files changed

+1287
-92
lines changed

36 files changed

+1287
-92
lines changed

‎notes/ai/dev/agent/agent-awesome.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
tags:
3+
- Awesome
4+
---
5+
6+
# AI Agent Awesome
7+
8+
- https://github.com/a2aproject/A2A
9+
- https://github.com/microsoft/autogen
10+
- https://github.com/DavidZWZ/Awesome-Deep-Research

‎notes/ai/dev/ai-dev-faq.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
tags:
3+
- FAQ
4+
---
5+
6+
# AI Dev FAQ

‎notes/ai/dev/cuda.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
tags:
3+
- FAQ
4+
---
5+
6+
# FAQ
7+
8+
## error during container init: error running prestart hook #0: exit status 1, stdout: , stderr: Auto-detected mode as 'legacy'
9+
10+
- 一般重启能解决
11+
- 如果不能重启，则尝试 unload 然后 reload
12+
13+
```
14+
nvidia-container-cli: initialization error: nvml error: driver/library version mismatch: unknown
15+
```
16+
17+
```bash
18+
nvidia-smi
19+
```
20+
21+
```
22+
Failed to initialize NVML: Driver/library version mismatch
23+
NVML library version: 570.172
24+
```
25+
26+
```bash
27+
# unload old
28+
lsmod | grep nvidia
29+
30+
sudo rmmod nvidia_drm
31+
sudo rmmod nvidia_modeset
32+
sudo rmmod nvidia_uvm
33+
sudo rmmod nvidia
34+
35+
sudo lsof /dev/nvidia*
36+
37+
lsmod | grep nvidia
38+
39+
# reload
40+
nvidia-smi
41+
```

‎notes/ai/dev/litellm/litellm-insight.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
tags:
3+
- Inside
4+
---
5+
6+
# LiteLLM Inside
7+
8+
- 价格信息
9+
- https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
10+
11+
| Header | For |
12+
| ----------------------------------------------- | ------------------------------------------ |
13+
| **Request** | |
14+
| `x-litellm-timeout: <seconds>` | 请求超时设置 |
15+
| `x-litellm-stream-timeout: <seconds>` | 第一个 Chunk 超时 |
16+
| `x-litellm-enable-message-redaction: <boolean>` | 启用消息内容屏蔽 |
17+
| `x-litellm-tags: <tag1,tag2,...>` | 请求标签 |
18+
| `x-litellm-num-retries: <number>` | 请求重试次数 |
19+
| `x-litellm-spend-logs-metadata: <json>` | 请求开销日志元数据 |
20+
| **Request/Anthropic** | |
21+
| `anthropic-version: <str>` | API version |
22+
| `anthropic-beta: <str>` | beta version |
23+
| **Request/OpenAI** | |
24+
| `openai-organization: <str>` | organization id |
25+
| **Request/Bypass** |
26+
| `x-*` | 需要配置 forward_client_headers_to_llm_api |
27+
| **Response/Rate Limit** | |
28+
| `x-ratelimit-remaining-requests: <int>` | 剩余可用请求数 |
29+
| `x-ratelimit-remaining-tokens: <int>` | 剩余可用token数 |
30+
| `x-ratelimit-limit-requests: <int>` | 最大请求数限制 |
31+
| `x-ratelimit-limit-tokens: <int>` | 最大token数限制 |
32+
| `x-ratelimit-reset-requests: <int>` | 请求限制重置时间 |
33+
| `x-ratelimit-reset-tokens: <int>` | token限制重置时间 |
34+
| **Response/Latency** | |
35+
| `x-litellm-response-duration-ms: <float>` | 从请求到响应的总耗时(毫秒) |
36+
| `x-litellm-overhead-duration-ms: <float>` | LiteLLM处理开销时间(毫秒) |
37+
| **Response/Retry&Fallback** | |
38+
| `x-litellm-attempted-retries: <int>` | 实际重试次数 |
39+
| `x-litellm-attempted-fallbacks: <int>` | 实际回退次数 |
40+
| `x-litellm-max-fallbacks: <int>` | 最大回退次数限制 |
41+
| **Response/Cost** | |
42+
| `x-litellm-response-cost: <float>` | API调用费用 |
43+
| `x-litellm-key-spend: <float>` | API密钥总消费 |
44+
| **Response/Bypass** | |
45+
| `llm_provider-*` | 透传LLM提供商的响应头 |
46+
47+
```json title="spend-logs-metadata"
48+
{ "user_id": "12345", "project_id": "proj_abc", "request_type": "chat_completion" }
49+
```
50+
51+
## config.yaml
52+
53+
```yaml
54+
include:
55+
- model_config.yaml
56+
57+
model_list: []
58+
litellm_settings:
59+
num_retries: 3 # retry call 3 times on each model_name (e.g. zephyr-beta)
60+
request_timeout: 10 # raise Timeout error if call takes longer than 10s. Sets litellm.request_timeout
61+
fallbacks: [{"zephyr-beta": ["gpt-4o"]}] # fallback to gpt-4o if call fails num_retries
62+
context_window_fallbacks: [{"zephyr-beta": ["gpt-3.5-turbo-16k"]}, {"gpt-4o": ["gpt-3.5-turbo-16k"]}] # fallback to gpt-3.5-turbo-16k if context window error
63+
allowed_fails: 3 # cooldown model if it fails > 1 call in a minute.
64+
router_settings: # router_settings are optional
65+
routing_strategy: simple-shuffle # Literal["simple-shuffle", "least-busy", "usage-based-routing","latency-based-routing"], default="simple-shuffle"
66+
model_group_alias: {"gpt-4": "gpt-4o"} # all requests with `gpt-4` will be routed to models with `gpt-4o`
67+
num_retries: 2
68+
timeout: 30 # 30 seconds
69+
redis_host: <your redis host> # set this when using multiple litellm proxy deployments, load balancing state stored in redis
70+
redis_password: <your redis password>
71+
redis_port: 1992
72+
general_settings: {}
73+
environment_variables: {}
74+
```
75+
76+
```yaml
77+
model_list:
78+
- model_name: glm-4.5
79+
litellm_params:
80+
model: openai/glm-4.5
81+
litellm_credential_name: zhipu_credential
82+
83+
- model_name: glm-4.5-air
84+
litellm_params:
85+
model: openai/glm-4.5-air
86+
litellm_credential_name: zhipu_credential
87+
88+
- model_name: '*'
89+
litellm_params:
90+
model: openai/glm-4.5-air
91+
litellm_credential_name: zhipu_credential
92+
93+
credential_list:
94+
- credential_name: zhipu_credential
95+
credential_values:
96+
api_base: os.environ/ZHIPU_API_BASE
97+
api_key: os.environ/ZHIPU_API_KEY
98+
credential_info:
99+
description: '智普'
100+
```
101+
102+
**支持通配符**
103+
104+
```yaml
105+
model_list:
106+
- model_name: xai/*
107+
litellm_params:
108+
model: xai/*
109+
api_key: os.environ/XAI_API_KEY
110+
111+
litellm_settings:
112+
check_provider_endpoint: true
113+
```
114+
115+
```yaml
116+
# params for litellm.completion() - https://docs.litellm.ai/docs/completion/input#input---request-body
117+
litellm_params:
118+
model: openai/facebook/opt-125m
119+
api_base: http://0.0.0.0:4000/v1
120+
api_key: none
121+
api_version: "2023-05-15"
122+
rpm: 60 # Optional[int]: When rpm/tpm set - litellm uses weighted pick for load balancing. rpm = Rate limit for this deployment: in requests per minute (rpm).
123+
tpm: 1000 # Optional[int]: tpm = Tokens Per Minute
124+
azure_ad_token: ""
125+
seed: 1234
126+
max_token: 1024
127+
temperature: 0.2
128+
organization: "org-12345"
129+
aws_region_name: "us-west-2"
130+
extra_headers: {"AI-Resource Group": "ishaan-resource"}
131+
model_info:
132+
version: 2
133+
access_groups: ['restricted-models']
134+
supported_environments: ["development", "production", "staging"]
135+
custom_tokenizer:
136+
identifier: deepseek-ai/DeepSeek-V3-Base
137+
revision: main
138+
auth_token: os.environ/HUGGINGFACE_API_KEY
139+
```
140+
141+
- https://docs.litellm.ai/docs/proxy/configs
142+
- https://docs.litellm.ai/docs/proxy/config_settings
143+
144+
## 参考
145+
146+
- https://docs.litellm.ai/docs/proxy/request_headers
147+
- Anthropic
148+
- Beta header
149+
- https://docs.claude.com/en/api/beta-headers
150+
- Features
151+
- https://docs.claude.com/en/docs/build-with-claude/overview

‎notes/ai/dev/mcp/README.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,6 @@ tags:
3737
- eventStore: databaseEventStore
3838
- Local state with message routing - 需要本地维护状态，所有属于同一会话的请求需路由到同一节点。可通过消息队列和发布/订阅系统实现。
3939

40-
# Spec
41-
42-
- https://www.claudemcp.com/specification
43-
4440
## JetBrains
4541

4642
- https://github.com/JetBrains/mcp-jetbrains

‎notes/ai/dev/mcp/mcp-awesome.md‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,17 @@ tags:
4444
- TODOIST_API_KEY
4545
- TODOIST_BASE_URL
4646
- add-projects, update-projects, delete-object
47-
- [Upstash/context7](https://github.com/upstash/context7)
48-
- MIT, JS, TS
49-
- Up-to-date code documentation for LLMs and AI code editors
50-
- `use context7`
51-
- MCP mcp.context7.com/mcp
52-
- Header CONTEXT7_API_KEY
53-
- MCP mcp.context7.com/sse
54-
- API context7.com/api/v1
47+
- search/repo/index/doc
48+
- [oraios/serena](https://github.com/oraios/serena)
49+
- https://ref.tools/
50+
- [Upstash/context7](https://github.com/upstash/context7)
51+
- MIT, JS, TS
52+
- Up-to-date code documentation for LLMs and AI code editors
53+
- `use context7`
54+
- MCP mcp.context7.com/mcp
55+
- Header CONTEXT7_API_KEY
56+
- MCP mcp.context7.com/sse
57+
- API context7.com/api/v1
5558
- Index/Aggregate
5659
- https://modelscope.cn/mcp
5760
- [Dhravya/apple-mcp](https://github.com/Dhravya/apple-mcp)

‎notes/ai/dev/mcp/mcp-insight.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
tags:
3+
- Insight
4+
- Protocol
5+
---
6+
7+
# MCP Insight
8+
9+
```
10+
客户端 服务端
11+
| |
12+
|--- GET /sse ------------>| (建立 SSE 流)
13+
| |
14+
|<--- SSE: endpoint -------| (返回 POST 端点 + sessionId)
15+
| |
16+
|--- POST /messages ------>| (发送消息，带 ?sessionId=)
17+
| |
18+
|<--- 202 Accepted --------| (确认接收)
19+
| |
20+
|<--- SSE: response -------| (通过 SSE 流返回响应)
21+
```
22+
23+
```
24+
客户端 服务端
25+
| |
26+
|--- POST /mcp ----------->| (初始化，包含 initialize 请求)
27+
| |
28+
|<--- SSE Stream --------->| (响应通过 SSE 返回，包含 Mcp-Session-Id header)
29+
| (text/event-stream) |
30+
| |
31+
|--- POST /mcp ----------->| (后续请求，带 Mcp-Session-Id header)
32+
| |
33+
|<--- SSE Stream --------->| (每个 POST 都可能开启新的 SSE 流返回响应)
34+
| |
35+
|--- GET /mcp ------------>| (可选：建立独立 SSE 流接收服务器推送)
36+
|<--- SSE Stream --------->|
37+
| |
38+
|--- DELETE /mcp --------->| (终止会话)
39+
```
40+
41+
- StreamableHTTP - 2025-03-26
42+
- outputSchema
43+
- 适用于 structureContent
44+
- structureContent - 2025-03-26
45+
- 旧版本返回结果为 `Array<{type:''}>`
46+
47+
```json
48+
{
49+
// 工具提示信息
50+
"annotations": {
51+
// 只读提示：工具不会修改环境
52+
"readOnlyHint": false,
53+
// 破坏性提示：是否执行破坏性更新
54+
"destructiveHint": true,
55+
// 幂等性提示：相同参数多次调用是否产生相同效果
56+
"idempotentHint": true,
57+
// 开放世界提示：是否与外部实体交互
58+
"openWorldHint": false
59+
}
60+
}
61+
```
62+
63+
- Client Capabilities
64+
- `roots`：提供文件系统根目录
65+
- `sampling`：支持大模型采样请求
66+
- `experimental`：支持实验性功能
67+
- Server Capabilities
68+
- `prompts`：提供提示模板
69+
- `resources`：提供可读资源
70+
- `tools`：提供可调用工具
71+
- `logging`：结构化日志
72+
- `experimental`：实验性功能支持
73+
- 版本
74+
- 2025-06-18
75+
- 2025-03-26
76+
- StreamableHTTP, outputSchema, structureContent, Mcp-Session-Id
77+
- 2024-11-05
78+
- SSE, seesionId
79+
- 2024-10-07
80+
- Tools、Resources、Prompt、content
81+
- Last-Event-ID
82+
83+
---
84+
85+
- https://www.claudemcp.com/specification

‎notes/ai/dev/mcp/serena.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: serena
3+
---
4+
5+
# serena
6+
7+
- [oraios/serena](https://github.com/oraios/serena)
8+
- MIT, Python
9+
- Serena 是一个强大的**编码代理工具包**，能够将 LLM 转换为功能完整的代理，直接在你的代码库上工作。
10+
- 提供**语义代码检索和编辑工具**，类似于 IDE 的功能，在符号级别提取代码实体并利用关系结构。
11+
- 主要特性：
12+
- 基于语言服务器协议（LSP）的语义代码分析
13+
- 支持多种编程语言：Python、TypeScript/JavaScript、PHP、Go、R、Rust、C/C++、Zig、C#、Ruby、Swift、Kotlin、Java、Clojure、Dart、Bash、Lua、Nix、Elixir、Erlang 等
14+
- 提供 MCP（Model Context Protocol）服务
15+
- 核心工具：
16+
- `find_symbol` - 全局符号搜索
17+
- `find_referencing_symbols` - 查找引用符号
18+
- `insert_after_symbol` / `insert_before_symbol` - 在符号前后插入代码
19+
- `replace_symbol_body` - 替换符号定义
20+
- `get_symbols_overview` - 获取文件符号概览
21+
- 典型用例：
22+
- 增强现有编码代理的性能（如 Claude Code）
23+
- 在大型复杂项目中精确导航和操作代码
24+
- 提供 IDE 级别的代码理解和编辑能力
25+
- 节省 token 使用并提高代码质量

0 commit comments

Comments
 (0)