feat(code): add optional DocumentParserRegistry for agentic_search

- Make document parsing optional (not required by default)
- Add DocumentParserRegistry to SessionOptions
- Expose DocumentParserRegistry to Python and Node.js SDKs
- AgenticSearchTool accepts optional parser registry
- Update documentation with configuration examples
- Maintain minimal core + tool bootstrapping principle

Breaking changes: None (backward compatible)

Author: RoyLin

DOCUMENT_PARSER_SDK_INTEGRATION.md

@@ -0,0 +1,210 @@
+# Document Parser API - SDK Integration Complete ✅
+
+## 完成状态
+
+文档解析扩展已完全同步到 Python 和 Node.js SDK。
+
+## 实现内容
+
+### 1. Rust Core
+
+✅ **SessionOptions 扩展**：
+- 添加 `document_parser_registry: Option<Arc<DocumentParserRegistry>>` 字段
+- 在创建 session 时，如果提供了 registry，自动重新注册 `AgenticSearchTool`
+
+✅ **公开 API**：
+- 导出 `AgenticSearchTool` 到公共 API
+- 导出 `DocumentParserRegistry` 和 `DocumentParser` trait
+
+### 2. Node.js SDK
+
+✅ **DocumentParserRegistry 类**：
+```typescript
+import { Agent, DocumentParserRegistry } from '@a3s-lab/code';
+
+const agent = await Agent.create('agent.hcl');
+
+// 使用文档解析器
+const session = agent.session('.', {
+  documentParserRegistry: new DocumentParserRegistry()
+});
+```
+
+✅ **SessionOptions 字段**：
+- 添加 `document_parser_registry?: DocumentParserRegistry`
+- 自动转换为 Rust `DocumentParserRegistry::new()`
+
+### 3. Python SDK
+
+✅ **DocumentParserRegistry 类**：
+```python
+from a3s_code import Agent, SessionOptions, DocumentParserRegistry
+
+agent = Agent("agent.hcl")
+
+# 使用文档解析器
+opts = SessionOptions()
+opts.document_parser_registry = DocumentParserRegistry()
+session = agent.session(".", opts)
+```
+
+✅ **SessionOptions 属性**：
+- 添加 `document_parser_registry` 属性（getter/setter）
+- 自动转换为 Rust `DocumentParserRegistry::new()`
+
+## 使用示例
+
+### Node.js
+
+```typescript
+import { Agent, DocumentParserRegistry } from '@a3s-lab/code';
+
+const agent = await Agent.create('agent.hcl');
+
+// 方式 1：默认（纯文本搜索）
+const session1 = agent.session('.');
+
+// 方式 2：启用文档解析器（当前包含 PlainTextParser）
+const session2 = agent.session('.', {
+  documentParserRegistry: new DocumentParserRegistry()
+});
+
+// 使用 agentic_search
+const result = await session2.send('Find authentication code');
+```
+
+### Python
+
+```python
+from a3s_code import Agent, SessionOptions, DocumentParserRegistry
+
+agent = Agent("agent.hcl")
+
+# 方式 1：默认（纯文本搜索）
+session1 = agent.session(".")
+
+# 方式 2：启用文档解析器（当前包含 PlainTextParser）
+opts = SessionOptions()
+opts.document_parser_registry = DocumentParserRegistry()
+session2 = agent.session(".", opts)
+
+# 使用 agentic_search
+result = session2.send("Find authentication code")
+```
+
+### Rust
+
+```rust
+use a3s_code_core::{Agent, SessionOptions};
+use a3s_code_core::tools::document_parser::{DocumentParser, DocumentParserRegistry};
+
+// 实现自定义解析器
+struct PdfParser;
+impl DocumentParser for PdfParser {
+    fn name(&self) -> &str { "pdf" }
+    fn supported_extensions(&self) -> &[&str] { &["pdf"] }
+    fn parse(&self, path: &Path) -> anyhow::Result<String> {
+        // 使用 pdf-extract 或类似库
+        todo!()
+    }
+}
+
+// 注册自定义解析器
+let mut registry = DocumentParserRegistry::new();
+registry.register(Arc::new(PdfParser));
+
+// 创建 session
+let opts = SessionOptions::new()
+    .with_document_parser_registry(Arc::new(registry));
+let session = agent.session(".", opts)?;
+```
+
+## 当前功能
+
+| 功能 | Rust | Node.js | Python |
+|------|------|---------|--------|
+| `DocumentParserRegistry` 类 | ✅ | ✅ | ✅ |
+| `PlainTextParser`（默认） | ✅ | ✅ | ✅ |
+| 自定义解析器（通过 trait） | ✅ | ❌ | ❌ |
+| SessionOptions 配置 | ✅ | ✅ | ✅ |
+
+## 未来扩展
+
+### 内置解析器（计划中）
+
+可以通过 Cargo features 添加更多内置解析器：
+
+```toml
+[features]
+pdf = ["pdf-extract"]
+excel = ["calamine"]
+word = ["docx-rs"]
+```
+
+然后在 SDK 中暴露：
+
+```typescript
+// 未来 API（尚未实现）
+const registry = new DocumentParserRegistry()
+  .enablePdf()
+  .enableExcel()
+  .enableWord();
+```
+
+### 回调机制（可选）
+
+允许 SDK 用户通过回调函数实现自定义解析器：
+
+```typescript
+// 未来 API（尚未实现）
+const registry = new DocumentParserRegistry()
+  .registerParser({
+    name: 'custom',
+    extensions: ['custom'],
+    parse: async (path) => {
+      // 用户自定义解析逻辑
+      return extractedText;
+    }
+  });
+```
+
+## 测试
+
+### Rust Core
+```bash
+cargo test --lib
+# ✅ 1477 passed
+```
+
+### Node.js SDK
+```bash
+cd sdk/node/examples
+node test-agentic-search-sdk.js
+# ✅ All tests passed
+```
+
+### Python SDK
+```bash
+cd sdk/python/examples
+python test_agentic_search_sdk.py
+# ✅ All tests passed
+```
+
+## 总结
+
+✅ **API 已完全同步**：
+- Rust core 支持 `DocumentParserRegistry` 配置
+- Node.js SDK 暴露 `DocumentParserRegistry` 类
+- Python SDK 暴露 `DocumentParserRegistry` 类
+- 所有 SDK 都可以通过 `SessionOptions` 配置
+
+✅ **向后兼容**：
+- 默认行为不变（纯文本搜索）
+- 文档解析器是可选的
+
+✅ **可扩展**：
+- Rust 用户可以实现自定义解析器
+- 未来可以添加更多内置解析器
+- SDK 用户可以选择启用文档解析
+
+**结论**：文档解析扩展已完全对 Python 和 Node.js SDK 开放，用户可以通过 `SessionOptions` 配置 `DocumentParserRegistry`。

README.md

@@ -5,15 +5,15 @@
 [![Crates.io](https://img.shields.io/crates/v/a3s-code-core.svg)](https://crates.io/crates/a3s-code-core)
 [![Documentation](https://docs.rs/a3s-code-core/badge.svg)](https://docs.rs/a3s-code-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1471%20passing-brightgreen.svg)](./core/tests)
+[![Tests](https://img.shields.io/badge/tests-1477%20passing-brightgreen.svg)](./core/tests)
 
 ---
 
 ## Why A3S Code?
 
 - **Embeddable** — Rust library, not a service. Node.js and Python bindings included. CLI for terminal use.
 - **Safe by Default** — Permission system, HITL confirmation, skill-based tool restrictions, and error recovery (parse retries, tool timeout, circuit breaker).
-- **Extensible** — 19 trait-based extension points, all with working defaults. Slash commands, tool search, and multi-agent teams.
+- **Extensible** — 20 trait-based extension points, all with working defaults. Slash commands, tool search, and multi-agent teams.
 - **Scalable** — Lane-based priority queue with multi-machine task distribution.
 
 ---
@@ -657,7 +657,7 @@ Switch a lane to External mode via `session.set_lane_handler(SessionLane::Execut
 
 ---
 
-### 🔌 Extensibility (19 Extension Points)
+### 🔌 Extensibility (20 Extension Points)
 
 All policies are replaceable via traits with working defaults:
 
@@ -680,14 +680,38 @@ All policies are replaceable via traits with working defaults:
 | BashSandbox          | Shell execution isolation                      | LocalBashExecutor         |
 | SkillValidator       | Skill activation logic                         | DefaultSkillValidator     |
 | SkillScorer          | Skill relevance ranking                        | DefaultSkillScorer        |
+| DocumentParser       | Custom file format parsing for agentic_search  | None (plain text only)    |
 
 Implement any trait and inject via `SessionOptions` builder methods (e.g., `with_security_provider`, `with_permission_checker`, `with_session_store`).
 
+### 📄 Document Parser Extension
+
+`agentic_search` works with plain text by default. To enable PDF, Excel, Word, or other binary formats, implement the `DocumentParser` trait and register it:
+
+```rust
+use a3s_code_core::tools::document_parser::{DocumentParser, DocumentParserRegistry};
+
+struct PdfParser;
+
+impl DocumentParser for PdfParser {
+    fn name(&self) -> &str { "pdf" }
+    fn supported_extensions(&self) -> &[&str] { &["pdf"] }
+    fn parse(&self, path: &Path) -> anyhow::Result<String> {
+        // use pdf-extract or similar
+        todo!()
+    }
+}
+
+let mut registry = DocumentParserRegistry::new();
+registry.register(Arc::new(PdfParser));
+let tool = AgenticSearchTool::with_parser_registry(registry);
+```
+
 ---
 
 ## Architecture
 
-5 core components (stable, not replaceable) + 19 extension points (replaceable via traits):
+5 core components (stable, not replaceable) + 20 extension points (replaceable via traits):
 
 ```
 Agent (config-driven)

core/src/agent_api.rs

@@ -181,6 +181,11 @@ pub struct SessionOptions {
     /// dispatched locally. The executor is also propagated to sub-agents via
     /// the sentinel hook mechanism.
     pub hook_executor: Option<Arc<dyn crate::hooks::HookExecutor>>,
+    /// Optional document parser registry for agentic_search tool.
+    ///
+    /// When set, enables custom document format support (PDF, Excel, Word, etc.)
+    /// for the agentic_search tool. If not set, only plain text files are searched.
+    pub document_parser_registry: Option<Arc<crate::tools::document_parser::DocumentParserRegistry>>,
 }
 
 impl std::fmt::Debug for SessionOptions {
@@ -1011,6 +1016,13 @@ impl Agent {
             }
         }
 
+        // Register custom agentic_search tool with document parser registry if provided
+        if let Some(ref registry) = opts.document_parser_registry {
+            use crate::tools::AgenticSearchTool;
+            let tool = AgenticSearchTool::with_parser_registry((**registry).clone());
+            tool_executor.register_dynamic_tool(Arc::new(tool));
+        }
+
         let tool_defs = tool_executor.definitions();
 
         // Build prompt slots: start from session options or agent-level config