docs(design): detail module contracts and sync interface map

docs/design/modules/README.md

@@ -1,9 +1,9 @@
 # Modules Design Index
 
-> Status: updated (2026-01-31).
+> Status: updated (2026-02-25).
 >
 > This directory holds per-module design documents aligned with `dare_framework/`.
-> TODO markers indicate gaps or ambiguity that need module owners to confirm.
+> Each module README now contains explicit: **Public Contract / Core Fields / Runtime Flow**.
 
 ## Modules
 - agent: `docs/design/modules/agent/README.md`
@@ -25,7 +25,10 @@
 - skill: `docs/design/modules/skill/README.md` (assessment: `docs/design/modules/skill/Assessment.md`)
 - mcp: `docs/design/modules/mcp/README.md` (assessment: `docs/design/modules/mcp/Assessment.md`)
 - embedding: `docs/design/modules/embedding/README.md`
-- transport (design-only): `docs/design/modules/transport/transport_mvp.md` (see also `docs/design/modules/transport/Transport_Domain_Design.md`)
+- transport: `docs/design/modules/transport/README.md`
+  - supplemental: `docs/design/modules/transport/transport_mvp.md`
+  - supplemental: `docs/design/modules/transport/Transport_Domain_Design.md`
+  - supplemental: `docs/design/modules/transport/InteractionStreaming.md`
 
 ## Related Docs
 - interface map: `docs/design/Interfaces.md`

docs/design/modules/agent/README.md

@@ -27,3 +27,35 @@
 - `examples/06-dare-coding-agent-mcp/README.md`
 
 说明：DareAgent 当前语义为 five-layer only，不承担 simple/react 自动降级。
+
+## 4. 对外接口（Public Contract）
+
+- 统一入口：`IAgent.__call__(task, transport=None)`
+- 编排入口：`IAgentOrchestration.execute(task, transport)`
+- 结果契约：统一输出 `RunResult`（含 `output_text`）
+
+详细签名与约束见：
+- `SimpleChatAgent_Detailed.md`（最小调用链）
+- `ReactAgent_Detailed.md`（ReAct 工具循环）
+- `DareAgent_Detailed.md`（five-layer 编排）
+
+## 5. 核心字段（Core Fields）
+
+- 统一任务输入：`Task`（`description/task_id/milestones/metadata`）
+- 统一运行输出：`RunResult`（`success/output/output_text/errors/metadata`）
+- Five-layer 状态（DareAgent）：
+  - `SessionState`: `task_id/run_id/current_milestone_idx/milestone_states`
+  - `MilestoneState`: `attempts/attempted_plans/reflections/evidence_collected`
+
+## 6. 关键流程（Runtime Flow）
+
+```mermaid
+flowchart TB
+  A["task input"] --> B{"agent kind"}
+  B -- SimpleChat --> C["single model call"]
+  B -- React --> D["model <-> tool loop"]
+  B -- Dare --> E["session -> milestone -> plan -> execute -> tool -> verify"]
+  C --> F["RunResult"]
+  D --> F
+  E --> F
+```

docs/design/modules/config/README.md

@@ -1,50 +1,97 @@
 # Module: config
 
-> Status: aligned to `dare_framework/config` (2026-01-31).
+> Status: detailed design aligned to `dare_framework/config` (2026-02-25).
 
 ## 1. 定位与职责
 
-- 提供全局配置模型与加载策略。
-- 支持多层配置合并（user + workspace）。
-- 为 Manager/Builder 提供组件启用/禁用与参数解析。
-
-## 2. 关键概念与数据结构
-
-- `Config`：统一配置入口（llm/tools/components/workspace_dir/user_dir/skill_mode/skill_paths/initial_skill_path）。
-- `LLMConfig` / `ProxyConfig`：模型连接与代理配置。
-- `ComponentConfig`：组件级 enable/disable 配置。
-
-## 3. 关键接口与实现
-
-- Kernel：`IConfigProvider`（`dare_framework/config/kernel.py`）
-- 默认实现：`FileConfigProvider`（`dare_framework/config/file_config_provider.py`）
-
-## 4. 配置层级与合并规则
-
-- 默认配置文件：`.dare/config.json`
-- 合并顺序：**user 层 → workspace 层**（workspace 覆盖 user）
-- 自动写入空配置文件（当文件不存在时）。
-
-## 5. 与其他模块的交互
-
-- **Model**：`Config.llm` 决定默认 adapter/endpoint/api_key。
-- **Tool**：`Config.tools` 提供 tool-specific config；`components` 控制启用/禁用。
-- **Builder/Manager**：按组件类型过滤/选择组件。
-- **Skill**：`skill_mode` 控制 skill 模式；`skill_paths` 提供技能目录集合；`initial_skill_path` 用于 agent 模式挂载单一 skill。
-
-## 6. 约束与限制
-
-- 仅支持 JSON 配置文件。
-- `allow_tools` / `allow_mcps` 未在 ToolManager 中强制执行（TODO）。
-
-## 7. TODO / 未决问题
-
-- TODO: 增加环境变量或多格式配置支持（YAML/TOML）。
-- TODO: enforce allowlists（allow_tools/allow_mcps）。
-- TODO: 配置热更新与订阅机制。
-
-## 8. Design Clarifications (2026-02-03)
-
-- Doc gap: component-level config schema is not defined; `component_config()` returns `Any`.
-- Impl gap: tighten config typing (at least `dict[str, Any]`) for component configs.
-- Surface: `FileConfigProvider` is exposed as a default implementation in the config facade.
+- 提供全局配置读取、分层合并与类型化访问。
+- 为 Builder / Manager 提供统一的组件启停、实例参数与目录路径。
+- 承担 observability / hooks / model / tool / mcp / skill 的统一入口配置。
+
+## 2. 依赖与边界
+
+- 核心依赖：`dare_framework/config/types.py`（配置模型）、`dare_framework/config/kernel.py`（稳定接口）。
+- 默认实现：`FileConfigProvider`（JSON 文件，workspace 覆盖 user）。
+- 边界约束：
+  - config 只负责“配置值解析与快照”，不负责运行时热更新通知。
+  - `allow_tools` / `allow_mcps` 当前只落在配置模型，尚未在 Tool/MCP 执行链强制。
+
+## 3. 对外接口（Public Contract）
+
+- `IConfigProvider.current() -> Config`
+  - 返回当前配置快照。
+- `IConfigProvider.reload() -> Config`
+  - 重新加载并返回新快照。
+- `build_config_provider(workspace_dir, user_dir) -> IConfigProvider`
+  - 创建默认 `FileConfigProvider`。
+- `Config` 实例方法（跨模块常用）
+  - `component_settings(component_type) -> ComponentConfig`
+  - `is_component_enabled(component) -> bool`
+  - `component_config(component) -> Any | None`
+  - `filter_enabled(components) -> list[IComponent]`
+
+## 4. 关键字段（Core Fields）
+
+### 4.1 顶层 `Config`
+
+- `llm: LLMConfig`
+- `mcp: dict[str, dict[str, Any]]`
+- `mcp_paths: list[str]`
+- `skill_paths: list[str]`
+- `tools: dict[str, dict[str, Any]]`
+- `allow_tools: list[str]`
+- `allow_mcps: list[str]`
+- `components: dict[str, ComponentConfig]`
+- `hooks: HooksConfig`
+- `knowledge: dict[str, Any]`
+- `long_term_memory: dict[str, Any]`
+- `workspace_dir: str`
+- `user_dir: str`
+- `prompt_store_path_pattern: str`
+- `default_prompt_id: str | None`
+- `observability: ObservabilityConfig`
+
+### 4.2 子结构
+
+- `LLMConfig`
+  - `adapter`, `endpoint`, `api_key`, `model`, `proxy`, `extra`
+- `ProxyConfig`
+  - `http`, `https`, `no_proxy`, `use_system_proxy`, `disabled`
+- `ComponentConfig`
+  - `disabled`, `entries`
+- `HooksConfig`
+  - `version`, `defaults`, `entries`, `priority_for(...)`
+- `ObservabilityConfig`
+  - `enabled`, `traces_enabled`, `metrics_enabled`, `exporter`, `sampling_ratio`, `redaction`, ...
+
+## 5. 关键流程（Runtime Flow）
+
+```mermaid
+flowchart TD
+  A["FileConfigProvider.reload"] --> B["Load user .dare/config.json"]
+  B --> C["Load workspace .dare/config.json"]
+  C --> D["Deep merge user -> workspace"]
+  D --> E["Config.from_dict"]
+  E --> F["Typed Config snapshot"]
+  F --> G["Builder / Manager consume"]
+```
+
+## 6. 与其他模块的交互
+
+- **Model**：读取 `Config.llm` 初始化 adapter 与 endpoint。
+- **Tool**：读取 `tools/components/allow_tools` 决定工具装配与筛选。
+- **MCP**：读取 `mcp` / `mcp_paths` 构建 client。
+- **Skill**：读取 `skill_paths` 驱动 skill 加载。
+- **Hook/Observability**：读取 `hooks` 与 `observability`。
+
+## 7. 约束与限制
+
+- 当前只支持 JSON 配置文件。
+- `reload()` 是显式触发，不带订阅/广播语义。
+- 组件配置值仍有 `Any`，需要逐步收敛类型。
+
+## 8. TODO / 未决问题
+
+- TODO: 支持 YAML/TOML 或环境变量分层。
+- TODO: 打通 `allow_tools` / `allow_mcps` 的强制执行。
+- TODO: 增加配置热更新与变更事件语义。

docs/design/modules/context/README.md

@@ -279,3 +279,34 @@ flowchart TD
 - TODO: 给 LTM/Knowledge 定义统一去重 key 与冲突消解规则。
 - TODO: 明确知识写入权限、审计与成本计量策略。
 - TODO: 增加“召回质量 + 压缩损失”评估指标并接入观测。
+
+## 14. 对外接口汇总（Public Contract Snapshot）
+
+- `IRetrievalContext.get(query="", **kwargs) -> list[Message]`
+- `IContext`
+  - `stm_add(message)`, `stm_get()`, `stm_clear()`
+  - `budget_use(resource, amount)`, `budget_check()`, `budget_remaining(resource)`
+  - `list_tools() -> list[CapabilityDescriptor]`
+  - `assemble() -> AssembledContext`
+  - `compress(**options) -> None`
+  - `set_tool_gateway(tool_gateway)`
+
+## 15. 核心字段汇总（Core Fields Snapshot）
+
+- `Message`: `role`, `content`, `name`, `metadata`
+- `Budget`: `max_tokens/max_cost/max_time_seconds/max_tool_calls` + `used_*`
+- `AssembledContext`: `messages`, `sys_prompt`, `tools`, `metadata`
+- 推荐 metadata 最小审计字段：
+  - `context_id`
+  - `retrieval.query/ltm_count/knowledge_count`
+  - `compression.trigger/strategies_applied/before_token_estimate/after_token_estimate`
+
+## 16. 关键流程汇总（Flow Snapshot）
+
+```mermaid
+flowchart TD
+  A["Agent before model call"] --> B["Context budget_check"]
+  B --> C["Context compress (optional)"]
+  C --> D["Context assemble"]
+  D --> E["AssembledContext -> ModelInput"]
+```

docs/design/modules/embedding/README.md

@@ -1,43 +1,63 @@
 # Module: embedding
 
-> Status: aligned to `dare_framework/embedding` (2026-01-31). TODO indicates gaps vs desired architecture.
+> Status: detailed design aligned to `dare_framework/embedding` (2026-02-25).
 
 ## 1. 定位与职责
 
-- 提供文本向量化能力接口（embedding adapter）。
-- 供知识检索 / RAG / 语义匹配等模块使用。
+- 提供统一向量化接口，支撑 knowledge / memory 的向量检索路径。
+- 隔离第三方 embedding SDK，向上层暴露稳定 `IEmbeddingAdapter` 协议。
 
-## 2. 关键概念与数据结构
+## 2. 依赖与边界
 
-- `EmbeddingResult`：向量 + metadata。
-- `EmbeddingOptions`：embedding 参数（model/metadata）。
-- `IEmbeddingAdapter`：embedding 适配器接口。
+- 核心协议：`dare_framework/embedding/interfaces.py`
+- 数据类型：`dare_framework/embedding/types.py`
+- 默认实现：`OpenAIEmbeddingAdapter`（`langchain-openai`）
+- 边界约束：
+  - embedding 只负责“文本->向量”，不负责检索排序与召回融合。
+  - 适配器层不管理知识库存储生命周期。
 
-## 3. 当前实现
+## 3. 对外接口（Public Contract）
 
-- `OpenAIEmbeddingAdapter`（LangChain OpenAIEmbeddings）。
+- `IEmbeddingAdapter.embed(text, options=None) -> EmbeddingResult`
+- `IEmbeddingAdapter.embed_batch(texts, options=None) -> list[EmbeddingResult]`
 
-## 4. 与其他模块的交互
+默认实现补充：
+- `OpenAIEmbeddingAdapter(model, api_key, endpoint, http_client_options)`
+- 支持 OpenAI 兼容 endpoint。
 
-- **Knowledge**：知识检索可调用 embedding 生成向量（当前未接入）。
-- **Config**：embedding 尚未纳入 Config 管理（TODO）。
+## 4. 关键字段（Core Fields）
 
-## 5. 约束与限制
+- `EmbeddingOptions`
+  - `model: str | None`
+  - `metadata: dict[str, Any]`
+- `EmbeddingResult`
+  - `vector: list[float]`
+  - `metadata: dict[str, Any]`（可含 model/usage）
 
-- 依赖 `langchain-openai`，未提供 fallback。
-- 无 Manager / Factory 统一选择逻辑（TODO）。
+## 5. 关键流程（Runtime Flow）
 
-## 6. 扩展点
+```mermaid
+flowchart TD
+  A["Knowledge / Memory request embedding"] --> B["IEmbeddingAdapter.embed(_batch)"]
+  B --> C["Adapter ensure client"]
+  C --> D["OpenAI-compatible embedding API"]
+  D --> E["EmbeddingResult(vector, metadata)"]
+  E --> F["Vector store consume"]
+```
 
-- 实现新的 embedding adapter（本地模型/第三方 API）。
-- 增加 Manager/Factory 统一管理。
+## 6. 与其他模块的交互
 
-## 7. TODO / 未决问题
+- **Knowledge**：vector knowledge 写入/检索依赖 embedding。
+- **Memory**：vector LTM 构建依赖 embedding。
+- **Config**：目前 embedding 独立于 config domain，后续需统一。
 
-- TODO: 接入 Knowledge/RAG pipeline。
-- TODO: 统一配置与 adapter 选择策略。
+## 7. 约束与限制
 
-## 8. Design Clarifications (2026-02-03)
+- 依赖可选第三方包 `langchain-openai`。
+- 当前未定义 adapter manager / provider 统一选择逻辑。
 
-- Doc/Impl gap: embedding domain lacks a `kernel.py` despite kernel conventions elsewhere.
-- Type cleanup: reduce `Any` usage in adapter client construction.
+## 8. TODO / 未决问题
+
+- TODO: 增加 embedding domain 的 kernel 层统一入口（与其他域一致）。
+- TODO: 收敛 adapter client 构造中的 `Any`。
+- TODO: 增加本地 embedding 模型支持与 fallback 策略。