Feat/cost web

.gitignore

@@ -15,3 +15,5 @@
 # Dependency directories (remove the comment below to include it)
 vendor
 .env
+.vscode/
+.local/

README.md

@@ -11,16 +11,16 @@ Inspired by [uber-go/dig](https://github.com/uber-go/dig), with support for adva
 
 ## ✨ Features
 
-| Feature | Description |
-|---------|-------------|
-| 🔄 **Cycle Detection** | Auto-detect dependency cycles |
-| 📦 **Multiple Injection** | Support func, struct, map, list |
-| 🏷️ **Namespace** | Dependency isolation via map key |
-| 🎯 **Multi-Output** | Struct can provide multiple dependencies |
-| 🪆 **Nested Support** | Support nested struct injection |
-| 🔧 **Non-Invasive** | Zero intrusion to original objects |
-| 🛡️ **Safe API** | `TryProvide`/`TryInject` won't panic |
-| 🌐 **Visualization** | HTTP module for dependency graph |
+| Feature                  | Description                              |
+| ------------------------ | ---------------------------------------- |
+| 🔄 **Cycle Detection**    | Auto-detect dependency cycles            |
+| 📦 **Multiple Injection** | Support func, struct, map, list          |
+| 🏷️ **Namespace**          | Dependency isolation via map key         |
+| 🎯 **Multi-Output**       | Struct can provide multiple dependencies |
+| 🪆 **Nested Support**     | Support nested struct injection          |
+| 🔧 **Non-Invasive**       | Zero intrusion to original objects       |
+| 🛡️ **Safe API**           | `TryProvide`/`TryInject` won't panic     |
+| 🌐 **Visualization**      | HTTP module for dependency graph         |
 
 ## 📦 Installation
 
@@ -115,6 +115,98 @@ err := dix.TryInject(di, func(svc *Service) {
 })
 ```
 
+### Startup Timeout / Slow Provider Warning
+
+Control long-running providers during startup:
+
+- Default provider timeout: `15s`
+- Disable provider timeout explicitly: `dix.WithProviderTimeout(0)`
+- Default slow provider warning threshold: `2s`
+- Disable slow provider warning: `dix.WithSlowProviderThreshold(0)`
+
+```go
+di := dix.New(
+    // Default `ProviderTimeout` is `15s`
+    // Use `dix.WithProviderTimeout(0)` to disable provider timeout
+    // Default `SlowProviderThreshold` is `2s`
+    // Use `dix.WithSlowProviderThreshold(0)` to disable slow-provider warnings
+    dix.WithProviderTimeout(2*time.Second),        // override default (default: 15s, 0 = disabled)
+    dix.WithSlowProviderThreshold(300*time.Millisecond), // override default (default: 2s, 0 = disabled)
+)
+```
+
+### DI Trace Logging (Optional)
+
+Enable step-by-step dependency resolution/injection/provider execution logs:
+
+- Env var: `DIX_TRACE_DI`
+- Default: disabled
+- Enable values: `1`, `true`, `on`, `yes`, `enable`, `trace`, `debug`
+
+```bash
+export DIX_TRACE_DI=true
+```
+
+When enabled, dix prints `di_trace ...` events with structured key-values (provider, input/output types, query kind, parent chain, timeout, etc.).
+
+> Note: if `DIX_LLM_DIAG_MODE=machine`, human-readable text logs are suppressed by design, including `di_trace` lines.
+
+### Diagnostic File Collection (Optional)
+
+You can collect detailed diagnostics into a searchable JSONL file:
+
+- Env var: `DIX_DIAG_FILE`
+- Example: `export DIX_DIAG_FILE=.local/dix-diag.jsonl`
+
+Behavior rules:
+
+- If `DIX_DIAG_FILE` is **not configured**, dix keeps the original behavior (no diagnostic file output).
+- If `DIX_DIAG_FILE` is configured, dix appends diagnostic records to file (`trace` / `error` / `llm`).
+- Console verbosity still follows existing controls (`DIX_TRACE_DI`, `DIX_LLM_DIAG_MODE`).
+
+Tip:
+
+- Keep console output concise for users.
+- Keep detailed records in file for search/LLM/offline troubleshooting.
+
+### In-Memory Trace Query (`dixtrace`, Optional)
+
+Starting from this version, dix also emits unified trace events into an in-memory trace store (`dixtrace`), which can be queried via HTTP API (`/api/trace`).
+
+- Default: enabled (in-memory ring buffer)
+- Optional file sink env var: `DIX_TRACE_FILE`
+- Example: `export DIX_TRACE_FILE=.local/dix-trace.jsonl`
+
+`/api/trace` is optimized for online troubleshooting (filter by `operation/status/event/component/provider/output_type`).
+If you need long-term persistence, combine it with `DIX_TRACE_FILE`.
+
+Quick event dictionary:
+
+| Event                                          | Meaning                                                                    |
+| ---------------------------------------------- | -------------------------------------------------------------------------- |
+| `di_trace inject.start`                        | Begin an injection request (`component`, `param_type`)                     |
+| `di_trace inject.route`                        | Injection route selected (`function` or `struct`)                          |
+| `di_trace provide.start`                       | Begin a provider registration request (`component`)                        |
+| `di_trace provide.signature`                   | Provider function signature analyzed (`input_count`, `output_count`)       |
+| `di_trace provide.register.output.done`        | Provider output type registered successfully                               |
+| `di_trace provide.register.failed`             | Provider registration failed (`reason` or `error`)                         |
+| `di_trace resolve.value.search_provider.start` | Start searching providers for a dependency type                            |
+| `di_trace resolve.value.found`                 | Dependency value resolved successfully                                     |
+| `di_trace resolve.value.not_found`             | Dependency resolution failed (`reason` included)                           |
+| `di_trace provider.execute.dispatch`           | Provider selected for execution (`provider`, `output_type`, `input_types`) |
+| `di_trace provider.input.resolve.start`        | Resolve one provider input type                                            |
+| `di_trace provider.input.resolve.found`        | Provider input resolved                                                    |
+| `di_trace provider.input.resolve.failed`       | Provider input resolution failed                                           |
+| `di_trace provider.call.start`                 | Start executing provider (`timeout`)                                       |
+| `di_trace provider.call.done`                  | Provider execution completed                                               |
+| `di_trace provider.call.failed`                | Provider execution failed (`timed_out`, `error`)                           |
+| `di_trace provider.call.return_error`          | Provider returned non-nil `error`                                          |
+| `di_trace inject.func.resolve_input.start`     | Resolve function injection argument                                        |
+| `di_trace inject.func.resolve_input.failed`    | Function argument resolution failed                                        |
+| `di_trace inject.struct.field.resolve.start`   | Resolve one struct field injection                                         |
+| `di_trace inject.struct.field.resolve.done`    | Struct field injected successfully                                         |
+| `di_trace inject.struct.field.resolve.failed`  | Struct field injection failed                                              |
+
 ## 🎯 Injection Patterns
 
 ### Struct Injection
@@ -242,29 +334,29 @@ task build
 
 ## 📚 Examples
 
-| Example | Description |
-|---------|-------------|
-| [struct-in](./example/struct-in/) | Struct input injection |
-| [struct-out](./example/struct-out/) | Struct multi-output |
-| [func](./example/func/) | Function injection |
-| [map](./example/map/) | Map/namespace injection |
-| [map-nil](./example/map-nil/) | Map with nil handling |
-| [list](./example/list/) | List injection |
-| [list-nil](./example/list-nil/) | List with nil handling |
-| [lazy](./example/lazy/) | Lazy injection |
-| [cycle](./example/cycle/) | Cycle detection example |
-| [handler](./example/handler/) | Handler pattern |
-| [inject_method](./example/inject_method/) | Method injection |
-| [test-return-error](./example/test-return-error/) | Error handling |
-| [http](./example/http/) | HTTP visualization |
+| Example                                           | Description             |
+| ------------------------------------------------- | ----------------------- |
+| [struct-in](./example/struct-in/)                 | Struct input injection  |
+| [struct-out](./example/struct-out/)               | Struct multi-output     |
+| [func](./example/func/)                           | Function injection      |
+| [map](./example/map/)                             | Map/namespace injection |
+| [map-nil](./example/map-nil/)                     | Map with nil handling   |
+| [list](./example/list/)                           | List injection          |
+| [list-nil](./example/list-nil/)                   | List with nil handling  |
+| [lazy](./example/lazy/)                           | Lazy injection          |
+| [cycle](./example/cycle/)                         | Cycle detection example |
+| [handler](./example/handler/)                     | Handler pattern         |
+| [inject_method](./example/inject_method/)         | Method injection        |
+| [test-return-error](./example/test-return-error/) | Error handling          |
+| [http](./example/http/)                           | HTTP visualization      |
 
 ## 📖 Documentation
 
-| Document | Description |
-|----------|-------------|
-| [Design Document](./docs/design.md) | Architecture and detailed design |
-| [Audit Report](./docs/audit.md) | Project audit, evaluation and comparison |
-| [dixhttp README](./dixhttp/README.md) | HTTP visualization module documentation |
+| Document                              | Description                              |
+| ------------------------------------- | ---------------------------------------- |
+| [Design Document](./docs/design.md)   | Architecture and detailed design         |
+| [Audit Report](./docs/audit.md)       | Project audit, evaluation and comparison |
+| [dixhttp README](./dixhttp/README.md) | HTTP visualization module documentation  |
 
 ## 📄 License
 

README_zh.md

@@ -11,16 +11,16 @@
 
 ## ✨ 功能特性
 
-| 特性 | 说明 |
-|------|------|
-| 🔄 **循环检测** | 自动检测依赖循环，避免死循环 |
-| 📦 **多种注入** | 支持 func、struct、map、list 作为注入参数 |
-| 🏷️ **命名空间** | 通过 map key 实现依赖隔离 |
-| 🎯 **多输出** | struct 可对外提供多组依赖对象 |
-| 🪆 **嵌套支持** | 支持 struct 依赖嵌套 |
-| 🔧 **无侵入** | 对原对象零侵入 |
+| 特性           | 说明                                              |
+| -------------- | ------------------------------------------------- |
+| 🔄 **循环检测** | 自动检测依赖循环，避免死循环                      |
+| 📦 **多种注入** | 支持 func、struct、map、list 作为注入参数         |
+| 🏷️ **命名空间** | 通过 map key 实现依赖隔离                         |
+| 🎯 **多输出**   | struct 可对外提供多组依赖对象                     |
+| 🪆 **嵌套支持** | 支持 struct 依赖嵌套                              |
+| 🔧 **无侵入**   | 对原对象零侵入                                    |
 | 🛡️ **安全 API** | 提供 `TryProvide`/`TryInject` 不 panic 的安全版本 |
-| 🌐 **可视化** | HTTP 模块图形化展示依赖关系 |
+| 🌐 **可视化**   | HTTP 模块图形化展示依赖关系                       |
 
 ## 📦 安装
 
@@ -115,6 +115,98 @@ err := dix.TryInject(di, func(svc *Service) {
 })
 ```
 
+### 启动超时 / 慢 Provider 告警
+
+可在启动阶段限制 provider 执行时间，并对慢调用输出告警：
+
+- 默认 `ProviderTimeout` 为 `15s`
+- 可用 `dix.WithProviderTimeout(0)` 显式关闭 provider 超时
+- 默认 `SlowProviderThreshold` 为 `2s`
+- 可用 `dix.WithSlowProviderThreshold(0)` 显式关闭慢 provider 告警
+
+```go
+di := dix.New(
+    // 默认 `ProviderTimeout` 为 `15s`
+    // 使用 `dix.WithProviderTimeout(0)` 可关闭 provider 超时
+    // 默认 `SlowProviderThreshold` 为 `2s`
+    // 使用 `dix.WithSlowProviderThreshold(0)` 可关闭慢 provider 告警
+    dix.WithProviderTimeout(2*time.Second),               // 覆盖默认值（default: 15s, 0 = 不限制）
+    dix.WithSlowProviderThreshold(300*time.Millisecond),  // 覆盖默认值（default: 2s, 0 = 关闭）
+)
+```
+
+### DI 追踪日志（可选）
+
+可开启“依赖查询 / 注入 / Provider 执行”的全过程日志：
+
+- 环境变量：`DIX_TRACE_DI`
+- 默认：关闭
+- 开启取值：`1`、`true`、`on`、`yes`、`enable`、`trace`、`debug`
+
+```bash
+export DIX_TRACE_DI=true
+```
+
+开启后会输出 `di_trace ...` 事件，包含结构化键值（如 provider、输入输出类型、查询类型、父链路、超时等）。
+
+> 注意：若设置 `DIX_LLM_DIAG_MODE=machine`，会按设计抑制人类文本日志，`di_trace` 也会被抑制。
+
+### 诊断文件采集（可选）
+
+你可以把更完整的诊断信息写入可检索的 JSONL 文件：
+
+- 环境变量：`DIX_DIAG_FILE`
+- 示例：`export DIX_DIAG_FILE=.local/dix-diag.jsonl`
+
+行为规则：
+
+- 如果 **未配置** `DIX_DIAG_FILE`，dix 保持原有方案（不输出诊断文件）。
+- 如果配置了 `DIX_DIAG_FILE`，dix 会追加写入诊断记录（`trace` / `error` / `llm`）。
+- 终端可见日志仍由现有开关控制（`DIX_TRACE_DI`、`DIX_LLM_DIAG_MODE`）。
+
+建议：
+
+- 终端给用户看“少而准”。
+- 文件给排障/LLM看“全而细”。
+
+### 内存 Trace 查询（`dixtrace`，可选）
+
+从这个版本开始，dix 会把统一 trace 事件写入内存 trace 存储（`dixtrace`），可通过 HTTP API（`/api/trace`）在线查询。
+
+- 默认：开启（内存环形缓冲）
+- 可选文件落盘环境变量：`DIX_TRACE_FILE`
+- 示例：`export DIX_TRACE_FILE=.local/dix-trace.jsonl`
+
+`/api/trace` 适合在线排障（按 `operation/status/event/component/provider/output_type` 等过滤）。
+如需长期持久化，请同时配置 `DIX_TRACE_FILE`。
+
+事件速查：
+
+| 事件                                           | 含义                                                                    |
+| ---------------------------------------------- | ----------------------------------------------------------------------- |
+| `di_trace inject.start`                        | 开始一次注入请求（`component`、`param_type`）                           |
+| `di_trace inject.route`                        | 注入路径已确定（`function` 或 `struct`）                                |
+| `di_trace provide.start`                       | 开始一次 provider 注册请求（`component`）                               |
+| `di_trace provide.signature`                   | provider 函数签名分析完成（`input_count`、`output_count`）              |
+| `di_trace provide.register.output.done`        | provider 输出类型注册成功                                               |
+| `di_trace provide.register.failed`             | provider 注册失败（含 `reason` 或 `error`）                             |
+| `di_trace resolve.value.search_provider.start` | 开始为某个依赖类型查找 provider                                         |
+| `di_trace resolve.value.found`                 | 依赖值查找成功                                                          |
+| `di_trace resolve.value.not_found`             | 依赖值查找失败（含 `reason`）                                           |
+| `di_trace provider.execute.dispatch`           | 选择并派发 provider 执行（含 `provider`、`output_type`、`input_types`） |
+| `di_trace provider.input.resolve.start`        | 开始解析 provider 的某个输入                                            |
+| `di_trace provider.input.resolve.found`        | provider 输入解析成功                                                   |
+| `di_trace provider.input.resolve.failed`       | provider 输入解析失败                                                   |
+| `di_trace provider.call.start`                 | 开始执行 provider（含 `timeout`）                                       |
+| `di_trace provider.call.done`                  | provider 执行完成                                                       |
+| `di_trace provider.call.failed`                | provider 执行失败（含 `timed_out`、`error`）                            |
+| `di_trace provider.call.return_error`          | provider 返回了非 nil `error`                                           |
+| `di_trace inject.func.resolve_input.start`     | 开始解析函数注入参数                                                    |
+| `di_trace inject.func.resolve_input.failed`    | 函数注入参数解析失败                                                    |
+| `di_trace inject.struct.field.resolve.start`   | 开始解析结构体字段注入                                                  |
+| `di_trace inject.struct.field.resolve.done`    | 结构体字段注入成功                                                      |
+| `di_trace inject.struct.field.resolve.failed`  | 结构体字段注入失败                                                      |
+
 ## 🎯 注入模式
 
 ### 结构体注入
@@ -242,29 +334,29 @@ task build
 
 ## 📚 示例
 
-| 示例 | 说明 |
-|------|------|
-| [struct-in](./example/struct-in/) | 结构体输入注入 |
-| [struct-out](./example/struct-out/) | 结构体多输出 |
-| [func](./example/func/) | 函数注入 |
-| [map](./example/map/) | Map/命名空间注入 |
-| [map-nil](./example/map-nil/) | Map 空值处理 |
-| [list](./example/list/) | List 注入 |
-| [list-nil](./example/list-nil/) | List 空值处理 |
-| [lazy](./example/lazy/) | 延迟注入 |
-| [cycle](./example/cycle/) | 循环检测示例 |
-| [handler](./example/handler/) | Handler 模式 |
-| [inject_method](./example/inject_method/) | 方法注入 |
-| [test-return-error](./example/test-return-error/) | 错误处理 |
-| [http](./example/http/) | HTTP 可视化 |
+| 示例                                              | 说明             |
+| ------------------------------------------------- | ---------------- |
+| [struct-in](./example/struct-in/)                 | 结构体输入注入   |
+| [struct-out](./example/struct-out/)               | 结构体多输出     |
+| [func](./example/func/)                           | 函数注入         |
+| [map](./example/map/)                             | Map/命名空间注入 |
+| [map-nil](./example/map-nil/)                     | Map 空值处理     |
+| [list](./example/list/)                           | List 注入        |
+| [list-nil](./example/list-nil/)                   | List 空值处理    |
+| [lazy](./example/lazy/)                           | 延迟注入         |
+| [cycle](./example/cycle/)                         | 循环检测示例     |
+| [handler](./example/handler/)                     | Handler 模式     |
+| [inject_method](./example/inject_method/)         | 方法注入         |
+| [test-return-error](./example/test-return-error/) | 错误处理         |
+| [http](./example/http/)                           | HTTP 可视化      |
 
 ## 📖 文档
 
-| 文档 | 说明 |
-|------|------|
-| [设计文档](./docs/design_zh.md) | 架构和详细设计 |
-| [审计报告](./docs/audit_zh.md) | 项目审计、评价和对比 |
-| [dixhttp 文档](./dixhttp/README_zh.md) | HTTP 可视化模块文档 |
+| 文档                                   | 说明                 |
+| -------------------------------------- | -------------------- |
+| [设计文档](./docs/design_zh.md)        | 架构和详细设计       |
+| [审计报告](./docs/audit_zh.md)         | 项目审计、评价和对比 |
+| [dixhttp 文档](./dixhttp/README_zh.md) | HTTP 可视化模块文档  |
 
 ## 📄 License