chore(.features): sync feature memory (auto) (#55)

Generated by sparticle-toolkit feature-memory-sync

Co-authored-by: Denya0529 <217564326+Denya0529@users.noreply.github.com>

.features/skill/MEMORY.md

@@ -1,6 +1,7 @@
 # Skill 功能
 
 > 负责范围：技能包管理服务 - 核心实现
+> 最后更新：2026-06-07
 > 最后更新：2026-06-02
 > 最后更新：2026-05-26
 > 最后更新：2026-05-23
@@ -33,6 +34,9 @@ MCP UI 类 skill 已按 MCP Apps 模式改造：工具返回数据，静态 HTML
 
 ## 最近重要事项
 
+- [2026-06-07](changelog/2026-Q2.md): 新增 `table-query` skill——`skills/developing/table-query/`，SQLite 表查询三步式工作流（search-tables → get-schemas → run-sql），run-sql 接收 JSON plan via stdin heredoc 避免 shell 转义；`category: Data & Retrieval`（`bb74aee`）
+- [2026-06-05](changelog/2026-Q2.md): 新增 `mineru` skill——`skills/developing/mineru/`，PDF/Office/图片转 Markdown，自动路由免 token 的 Agent API 与需 token 的 Standard API，附 15 个目标 sink（notion/feishu/slack/...）；`category: Document Processing`（`b618cb1`）
+- [2026-06-05](changelog/2026-Q2.md): `rag-retrieve` 系列空 query 由 JSON-RPC error 改为 success-with-error-text——5 个 server 变体（autoload/onprem、autoload/support、developing/rag-retrieve-no-citation、onprem/rag-retrieve-only、support/rag-retrieve-only）统一改用 `create_success_response` 携带 `"Error: missing required parameter 'query'..."` 文案，让 agent 在 tool output 里看到错误并自纠错重试（`ecf332a`）
 - [2026-06-02](changelog/2026-Q2.md): 修复 deepagents 落盘 backend grep 扫描全盘问题——`create_custom_cli_agent` 中 `large_results_backend` / `conversation_history_backend` 的 `FilesystemBackend` 由 `virtual_mode=False` 改为 `True`，避免 `CompositeBackend` 剥前缀后把 `"/"` 转发给 grep 时扫到真实根目录，单次 grep 从 45–152s 回到毫秒级（`6bccd89`）
 - [2026-05-29](changelog/2026-Q2.md): 新增 `ToolMetricsMiddleware`——通过 `wrap_tool_call` / `awrap_tool_call` 对每次 tool 调用计时并 emit `catalog_agent.tool_call` 结构化指标（成功/失败/取消三态、含 `tool_name`/`trace_id`/`bot_id`/`duration_ms`/`error_type`）；插在 `init_agent` 中间件链的 `EmptyResponseRetryMiddleware` 之后、`ToolUseCleanupMiddleware` 之前（`9f0ae25`）
 - [2026-05-26](changelog/2026-Q2.md): skill 引入 `category` 字段——`routes/skill_manager.py` 在 `SkillItem` / `SkillValidationResult` 增加 `category`，从 `plugin.json` 与 `SKILL.md` frontmatter 解析，official skill 默认 `"other"`、user skill 默认 `"custom"`；并通过 batch 给 common/developing/onprem/support 路径下大量 skill 元数据补 `category`，`data-dashboard` / `mcp-ui` 归类 `Interactive UI`（`203dcf4`, `3ada55a`, `9658588`）
@@ -91,6 +95,7 @@ MCP UI 类 skill 已按 MCP Apps 模式改造：工具返回数据，静态 HTML
 - ⚠️ **Daytona shell_env 是文件注入而非 process env**：`init_agent` 通过 `cat > $REMOTE_BASH_ENV_PATH` 写入 `export VAR=...` 行，沙箱内必须由 shell（bash）的 `BASH_ENV` 加载才能生效；非 daytona 模式或不走 bash 启动的脚本拿不到这些变量。扩展注入项需直接改 `init_agent` 里的 `_shell_env` 字典。
 - ⚠️ **`CompositeBackend` 路由下的落盘 backend 必须 `virtual_mode=True`**：`create_custom_cli_agent` 中 `large_results_backend` / `conversation_history_backend` 都用独立 `tempfile.mkdtemp()` 做根目录，但 `CompositeBackend` 在路由时会剥掉前缀、可能把 `"/"` 转发给 grep；`virtual_mode=False` 会把 `"/"` 解析为真实根目录并扫到 `/usr`、`/var`、其他会话的 tmp 目录（单次 45–152s）。`virtual_mode=True` 才会把所有路径锚定到 `root_dir` 并过滤越界结果。后续新增"只服务本次会话"的落盘 backend 一律走 `virtual_mode=True`，真实 workspace backend 仍保持 `False`。
 - ⚠️ **`ToolMetricsMiddleware` 必须在重试中间件之后、其他工具中间件之前**：`init_agent` 中顺序约定为 `EmptyResponseRetryMiddleware → ToolMetricsMiddleware → ToolUseCleanupMiddleware → ...`，这样统计到的 `duration_ms` 才包含全部后续 tool 处理开销并自然覆盖重试边界。指标 emit 自身的异常被吞掉只打 logger.exception，所以指标缺失不会触发 agent 报错，必须在指标后端做独立告警。
+- ⚠️ **`rag-retrieve` 系列空 query 返回 success 而非 JSON-RPC error**：5 个 server 变体（autoload/onprem、autoload/support、developing/rag-retrieve-no-citation、onprem/rag-retrieve-only、support/rag-retrieve-only）从 2026-06-05 起，缺 `query` 参数时返回 `create_success_response` 携带 `content[].text` 前缀 `"Error: missing required parameter 'query'..."`，故意让 LLM agent 在 tool output 里看到错误并自纠错重试。下游/中间层不能再用 JSON-RPC `error.code == -32602` 判断缺参，需要从 text 内容解析；新 MCP server 设计错误路径时也应区分"需要 agent 自纠错的语义错误（走 success-with-error-text）"与"不可恢复错误（走 error response）"。
 
 ## Skill 目录结构
 

.features/skill/changelog/2026-Q2.md

@@ -4,6 +4,92 @@
 
 ---
 
+## 2026-06-07: 新增 `table-query` skill（SQLite 表查询）
+
+**类型**：新功能
+
+**背景**：bot 上传的 Excel/CSV 表格此前只能走 `rag_retrieve` 语义检索回答问题，对"价格/数量/库存/排名/聚合"这类**结构化**问题精度差、答非所问。需要一条"快速、不走 LLM 的 SQL 查询路径"。
+
+**改动**：
+- 新增 `skills/developing/table-query/`：
+  - `SKILL.md`：定义 search-tables → get-schemas → run-sql 三步工作流；明确"backend 不做 LLM 推理，由 agent 自己写 SQLite SQL"；`category: Data & Retrieval`。
+  - `scripts/table_query.py`：CLI 入口 + run-sql plan 执行器（plan 通过 stdin heredoc 传递，无需 shell 转义）。
+  - `skill.yaml`：元数据。
+  - `verify_table_query.sh`：自检脚本。
+- 工作流要求：search-tables **每问最多 1 次**，run-sql 出错重试 ≤ 2 次，且不回退到 search-tables；search-tables 无果时降级到 `rag_retrieve`。
+
+**根因**：N/A（新功能）
+
+**影响**：
+- agent 可直接对上传表数据做 SUM/AVG/COUNT 等结构化查询，并通过 `__src` 列 + `file_ref_table` 输出行级 citation。
+- 同时引入 plan-on-stdin 的调用约定（`<<'PLAN' ... PLAN`），后续类似 SQL/JSON 入参的 skill 可参考此模式以避免 argv 转义问题。
+
+**相关文件**：
+- `skills/developing/table-query/SKILL.md`
+- `skills/developing/table-query/scripts/table_query.py`
+- `skills/developing/table-query/skill.yaml`
+- `skills/developing/table-query/verify_table_query.sh`
+
+**Commit/PR**：`bb74aee`
+
+---
+
+## 2026-06-05: 新增 `mineru` skill（PDF/Office/图片 → Markdown 解析）
+
+**类型**：新功能
+
+**背景**：缺少统一的"文档转 Markdown"管道，PDF/Word/PPT/Excel/图片需要走不同工具，且 OCR / 公式 / 表格识别能力不一致。
+
+**改动**：
+- 新增 `skills/developing/mineru/`（约 4700 行，30 文件）：
+  - `SKILL.md` + `references/`（api_reference / comparison / integrations）。
+  - `scripts/mineru.py`：核心 CLI，自动路由 Agent API（无 token）与 Standard API（需 `MINERU_TOKEN`，支持大文件/批量/DOCX/HTML/LaTeX 导出）。
+  - `scripts/mineru_mcp.py`：MCP server 包装。
+  - `scripts/sinks/`：airtable / coda / confluence / dingtalk / feishu / linear / local / notion / onenote / roam / siyuan / slack / ticktick / wecom / wps / yuque 等多目标写出。
+  - `scripts/chunking.py` / `splitter.py` / `local_engine.py`：分块、切分、本地引擎。
+- `category: Document Processing`，标准依赖（仅标准库）。
+
+**根因**：N/A（新功能）
+
+**影响**：
+- 提供"零 token 起步、有 token 升级"的渐进式解析路径，降低部署门槛。
+- 多 sink 设计可作为后续"采集 → 结构化 → 多目的地分发"类 skill 的参考骨架。
+
+**相关文件**：
+- `skills/developing/mineru/SKILL.md`
+- `skills/developing/mineru/scripts/mineru.py`
+- `skills/developing/mineru/scripts/mineru_mcp.py`
+- `skills/developing/mineru/scripts/sinks/*.py`（15 个目标）
+
+**Commit/PR**：`b618cb1`
+
+---
+
+## 2026-06-05: `rag-retrieve` 系列空 query 改返回 success 文案（替代 JSON-RPC error）
+
+**类型**：行为变更（兼容性）
+
+**背景**：`rag_retrieve` / `table_rag_retrieve` 工具在缺少 `query` 参数时返回 JSON-RPC `-32602` error。MCP/agent 链路上 error 容易被上层吞掉，agent 看不到"为什么失败"，无法自我修复。
+
+**改动**：把 5 个 rag-retrieve server 变体的"missing query"分支由 `create_error_response(-32602, ...)` 改为 `create_success_response(...)` 携带 `content[].text = "Error: missing required parameter 'query'. Please call this tool again with a non-empty 'query' argument describing what you want to retrieve."`：
+- `skills/autoload/onprem/rag-retrieve/rag_retrieve_server.py`
+- `skills/autoload/support/rag-retrieve/rag_retrieve_server.py`
+- `skills/developing/rag-retrieve-no-citation/rag_retrieve_server.py`
+- `skills/onprem/rag-retrieve-only/rag_retrieve_server.py`
+- `skills/support/rag-retrieve-only/rag_retrieve_server.py`
+
+**根因**：MCP 协议层的 error 在多数 agent 框架下不会作为"tool 返回结果"传给 LLM，从而无法触发重试；改成 success-with-error-text 让 agent 把错误文本当 tool output 读到，并在下一轮自然带上 query 重试。
+
+**影响**：
+- 客户端**不能再依赖 JSON-RPC error code = -32602 判定缺参**，必须从 `content[].text` 前缀 `"Error:"` 解析；任何在 success 路径上做强校验/落盘的中间层需要兼容这种"假成功"形态。
+- 新 MCP server 出错路径如果是"需要 agent 自纠错"的语义错误，应走同样的 success-with-error-text 模式；底层崩溃 / 不可恢复错误仍走 error response。
+
+**相关文件**：见上。
+
+**Commit/PR**：`ecf332a`
+
+---
+
 ## 2026-06-02: 修复 deepagents 落盘 backend grep 扫描全盘问题（virtual_mode=True）
 
 **类型**：Bug 修复