aicd 0.0.9__tar.gz

aicd-0.0.9/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: aicd
+Version: 0.0.9
+Summary: CLI AI Agent for code and documentation
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.9.0
+Requires-Dist: textual>=0.47.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.40.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: pymupdf>=1.24.0
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: python-pptx>=0.6.23
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: mammoth>=1.8.0
+Requires-Dist: markdownify>=0.13.0
+Requires-Dist: playwright>=1.45.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: fastapi>=0.115.0; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == "dev"
+Provides-Extra: db
+Requires-Dist: asyncpg>=0.29.0; extra == "db"
+Requires-Dist: aiomysql>=0.2.0; extra == "db"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115.0; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == "api"
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
+Provides-Extra: opencv
+Requires-Dist: opencv-python-headless>=4.8.0; extra == "opencv"
+Provides-Extra: pdf
+Requires-Dist: docx2pdf>=0.1.8; extra == "pdf"

aicd-0.0.9/README.md

@@ -0,0 +1,97 @@
+# aicd
+
+命令行 AI Agent：聊天驱动文件、进程、HTTP、任务与子 Agent。Windows 优先，预留 Linux。
+
+本工具借助大模型，在对话中完成**由代码生成文档**与**由文档生成代码**的闭环，并对项目中的文档与源码做**深入分析与理解**，便于梳理设计、落地实现与持续维护。
+
+## 环境
+
+```powershell
+cd <本仓库根目录>
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+# 可选：Agent 访问 PostgreSQL / MySQL（db_inspect / db_query）
+pip install -e ".[db]"
+# 可选：只读聊天历史 HTTP API（aicd serve）
+pip install -e ".[api]"
+# 可选：PDF 整页 OCR（doc_extract use_ocr）
+pip install -e ".[ocr]"
+# 可选：浏览器自动化
+playwright install chromium
+```
+
+## 配置（config.yaml）
+
+- **`llm`**：`apiKey` / `baseUrl` / `modelId`；可选 **`visionModel`**（多模态专用，缺省沿用主模型）；**`timeoutSec`**；**`maxRetries`**（单次请求失败后额外重试次数，0–20，默认 3）；**`retryBaseDelaySec`**（退避基数秒，默认 1.0）；采样字段 `temperature`、`topP` 等。
+- **`agent`**：**`maxToolRounds`** / **`subAgentMaxToolRounds`** 各 **1–500**（超出会截断）；**`contextBudgetTokens`**、**`chatHistoryMaxMessages`**（启动时从 SQLite 恢复尾部消息再按 token 预算裁剪）。
+- **`paths`**：`full_disk`、`allowed_roots` 等（见代码内默认值）。
+
+环境变量 **`AICD_HOME`**：应用数据目录。未设置且未使用 `--home` 时，使用 **`%USERPROFILE%\.aicd`**（Windows）。其下 **`logs/`** 每次 `aicd tui` 会新建时间戳日志；LLM 重试会写入会话日志。
+
+## 命令行
+
+| 命令 | 说明 |
+|------|------|
+| `aicd init [--home DIR]` | 初始化 HOME、`config.yaml`、SQLite |
+| `aicd tui [--home DIR] [--work DIR]` | TUI；**`--work`** 启动后立刻将 AI 工作区设为该目录（等同 `/work`） |
+| `aicd serve [--home DIR] [--host] [--port] [--api-key]` | 只读聊天 API（需 **`pip install -e ".[api]"`**）；鉴权见下文 |
+| `aicd version` | 打印版本 |
+
+TUI 斜杠：**`/work`**、**`/doc`**、**`/agent`**、**`/llm`**（含 `maxRetries`、`retryBaseDelaySec`）、**`/task`**、**`/exit`**。
+
+## Agent 能力与工具（摘要）
+
+- **工作区**：主会话须用工具 **`ai_workspace_set`** 切换项目目录（**`run_command cd` 无效**）；TUI 用 **`/work`**。
+- **多模态**：**`vision_analyze_image`** — 将本地图片送视觉模型解析图表/图中文字；默认 **`save_report`** 把结果写入 **AI tmp**（`ai_output_dir/tmp`），便于后续 **`fs_read_file`**。发送前会对大图做长边与体积压缩（默认长边 ≤1920、编码目标 ≤1MiB 等，见 `llm.image_file_to_data_url`）。
+- **文档**：**`doc_extract`**（PDF/DOCX/PPTX 等）；**`document_outline`** — 对 `.md`/`.html`/`.txt` 提取标题树、**行号**与 **UTF-8 字节偏移**，默认写入 **`tmp/outlines/<stem>.json`**，便于大文档分块阅读。
+- **超大上下文策略**：系统提示中的 **LARGE_CONTEXT** 约定：先检索/目录再 **`fs_read_file` offset/limit**、在 **`ai_tmp`** 写清单与 **`session_focus.md`**（稳定事实 vs 工作假设）、大输出落盘、必要时 **`task_ai`** / **`chat_save_summary`** / **`chat_history_*`**。
+- **聊天持久化**：消息与摘要存 SQLite；**`aicd serve`** 提供只读 HTTP 拉取（与 TUI 共用同一库）。
+- **主 / 子任务闭环**：复杂工作优先 **`task_ai`**。主会话可在旧子任务仍 **`running`** 时继续发话；若新意图属于同一子任务，主 AI 应 **`task_message_send`**（**`kind`**: **`directive`**，**`body`**: `{"text":"..."}`，主会话可省略 **`from_task_id`**，库内记为 **`main-<session_id>`**）。子 Agent 在每段 LLM 工具循环结束后**自动拉取收件箱**；有未读则合并为新的 **user** 轮次并继续，**无新消息则任务结束**。累计 LLM 轮次有上限（约 `max(subAgentMaxToolRounds*6, 300)`），防无限循环。相关工具：**`task_list`** / **`task_result`**（**timeline**）、**`task_thread_stats`**。
+
+## 只读聊天 HTTP API（`aicd serve`）
+
+需安装 **`aicd[api]`**。默认监听 **`127.0.0.1:8765`**（可用 `--host` / `--port` 修改）。
+
+- **`GET /health`** → `{"ok": true}`
+- **`GET /v1/sessions/{session_id}/messages?limit=&offset=`** — 分页消息（`limit` 1–2000）
+- **`GET /v1/sessions/{session_id}/summaries?limit=`** — 会话摘要列表
+
+若启动时传入 **`--api-key`** 或环境变量 **`AICD_API_KEY`**，则请求须带 **`X-API-Key`** 或 **`Authorization: Bearer <token>`**。
+
+## 离线可视化（导出 HTML）
+
+包内自带 `src/aicd/res/`：**Chart.js**、**Mermaid**、**vis-network**（含 CSS）。升级或重装依赖可执行：
+
+```powershell
+python scripts/download_viz_res.py
+```
+
+Agent 工具：`viz_export_html`、`viz_data_chart`、`viz_copy_resources`、`viz_list_bundled_assets`；导出前可用 **`viz_spec_validate`**。
+
+## 分析函数库（kit）
+
+`src/aicd/kit/` 提供 JSON 友好的纯函数，并由聚合工具暴露：`data_stats`、`data_text`、`data_time`、`script_template`（骨架 + `script_run`）。实现与路由见 `src/aicd/agent/handlers/`。
+
+## Cursor 技能（`.cursor/skills/`）
+
+仓库内包含若干 **SKILL.md**（工作区、输出目录、聊天历史、大仓库索引 **aicd-code-index**、Draw.io、可视化校验、Analytics、DB 等），便于在 Cursor 中改代码时对齐行为。
+
+## 版本号
+
+- 当前版本见 `src/aicd/version.py` 中的 **`VERSION`**（`pyproject.toml` 动态读取）。
+- **每次合入/发布前**在仓库根目录执行：`python scripts/bump_version.py`。
+- **上传 PyPI 前**先构建再自检：`python scripts/package.py --clean`，然后 `python scripts/release_precheck.py`（可加 `--strict` 做更严的 apiKey 字面量检查）；通过后再 `python -m twine upload dist\aicd-*`。
+
+## 代码结构（速查）
+
+| 路径 | 作用 |
+|------|------|
+| `src/aicd/app.py` | Typer 入口：`tui` / `init` / `serve` / `version` |
+| `src/aicd/runtime.py` | `build_runtime`、工作区/输出目录、`set_vision_llm` / `attach_session_log` |
+| `src/aicd/agent/loop.py` | 主对话与子 Agent 工具循环 |
+| `src/aicd/agent/llm.py` | OpenAI 兼容客户端、**重试**、**vision 图片编码** |
+| `src/aicd/agent/prompts.py` | 系统提示（含 **LARGE_CONTEXT**） |
+| `src/aicd/api_serve.py` | FastAPI 只读聊天 API |
+| `src/aicd/tools/document_outline.py` | 文档标题索引 |
+| `src/aicd/config.py` | **`MAX_AGENT_TOOL_ROUNDS`**、**`LLMConfig`** |

aicd-0.0.9/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aicd"
+dynamic = ["version"]
+description = "CLI AI Agent for code and documentation"
+requires-python = ">=3.10"
+dependencies = [
+  "typer>=0.9.0",
+  "textual>=0.47.0",
+  "rich>=13.0.0",
+  "httpx>=0.27.0",
+  "openai>=1.40.0",
+  "pyyaml>=6.0.1",
+  "aiosqlite>=0.19.0",
+  "pymupdf>=1.24.0",
+  "python-docx>=1.1.0",
+  "openpyxl>=3.1.0",
+  "python-pptx>=0.6.23",
+  "Pillow>=10.0.0",
+  "numpy>=1.24.0",
+  "mammoth>=1.8.0",
+  "markdownify>=0.13.0",
+  "playwright>=1.45.0",
+  "cryptography>=42.0.0",
+]
+
+[project.scripts]
+aicd = "aicd.app:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2.0", "fastapi>=0.115.0", "uvicorn[standard]>=0.32.0"]
+db = ["asyncpg>=0.29.0", "aiomysql>=0.2.0"]
+api = ["fastapi>=0.115.0", "uvicorn[standard]>=0.32.0"]
+ocr = ["pytesseract>=0.3.10"]
+opencv = ["opencv-python-headless>=4.8.0"]
+pdf = ["docx2pdf>=0.1.8"]
+
+[tool.setuptools.dynamic]
+version = { attr = "aicd.version.VERSION" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aicd = ["res/*.js", "res/*.css", "res/*.txt"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

aicd-0.0.9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aicd-0.0.9/src/aicd/__init__.py

@@ -0,0 +1,3 @@
+"""Aicd: CLI AI agent for code and documentation."""
+
+from aicd.version import VERSION as __version__

aicd-0.0.9/src/aicd/__main__.py

@@ -0,0 +1,8 @@
+from aicd.cli_encoding import configure_cli_utf8
+
+configure_cli_utf8()
+
+from aicd.app import main
+
+if __name__ == "__main__":
+    main()

aicd-0.0.9/src/aicd/agent/__init__.py

@@ -0,0 +1,3 @@
+from aicd.agent.loop import AgentLoop
+
+__all__ = ["AgentLoop"]

aicd-0.0.9/src/aicd/agent/chat_context.py

@@ -0,0 +1,203 @@
+"""按消息条数与粗算 token 预算裁剪历史，用于启动时恢复上下文。"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from aicd.agent.chat_serialize import estimate_message_tokens
+from aicd.db.store import ChatMessageRow
+
+
+def _tool_call_ids_from_assistant(msg: dict[str, Any]) -> list[str]:
+    tcs = msg.get("tool_calls") or []
+    if not isinstance(tcs, list):
+        return []
+    ids: list[str] = []
+    for tc in tcs:
+        if not isinstance(tc, dict):
+            continue
+        tid = tc.get("id")
+        if tid:
+            ids.append(str(tid))
+    return ids
+
+
+def openai_message_list_valid(msgs: list[dict[str, Any]]) -> bool:
+    """
+    检查消息序列是否满足 OpenAI 兼容 API 约定：
+    无首部孤立 ``tool``；每条带 ``tool_calls`` 的 ``assistant`` 后须紧跟对应数量的 ``tool``，
+    且 ``tool_call_id`` 与 ``tool_calls[].id`` 一致（多重集）。
+    """
+    if not msgs:
+        return True
+    if msgs[0].get("role") == "tool":
+        return False
+    i = 0
+    while i < len(msgs):
+        role = msgs[i].get("role")
+        if role == "tool":
+            return False
+        if role == "system":
+            i += 1
+            continue
+        if role == "user":
+            i += 1
+            continue
+        if role == "assistant":
+            ids = _tool_call_ids_from_assistant(msgs[i])
+            if not ids:
+                i += 1
+                continue
+            need = len(ids)
+            want = sorted(ids)
+            got: list[str] = []
+            for k in range(need):
+                j = i + 1 + k
+                if j >= len(msgs):
+                    return False
+                tm = msgs[j]
+                if tm.get("role") != "tool":
+                    return False
+                got.append(str(tm.get("tool_call_id") or ""))
+            if sorted(got) != want:
+                return False
+            i += 1 + need
+            continue
+        return False
+    return True
+
+
+def repair_openai_chat_messages(messages: list[dict[str, Any]]) -> None:
+    """
+    原地修复：去掉首部孤立 ``tool``；去掉不完整 tool 轮次（含仅跟了部分 ``tool`` 的 ``assistant``）；
+    去掉尾部仍含 ``tool_calls`` 且无对应 ``tool`` 的 ``assistant``。
+    """
+    changed = True
+    while changed and messages:
+        changed = False
+        while messages and messages[0].get("role") == "tool":
+            messages.pop(0)
+            changed = True
+        i = 0
+        while i < len(messages):
+            m = messages[i]
+            if m.get("role") != "assistant":
+                i += 1
+                continue
+            ids = _tool_call_ids_from_assistant(m)
+            if not ids:
+                i += 1
+                continue
+            need = len(ids)
+            j = i + 1
+            tool_roles = 0
+            while j < len(messages) and tool_roles < need:
+                if messages[j].get("role") != "tool":
+                    break
+                tool_roles += 1
+                j += 1
+            if tool_roles < need:
+                del messages[i:j]
+                changed = True
+                continue
+            got = [str(messages[i + 1 + k].get("tool_call_id") or "") for k in range(need)]
+            if sorted(got) != sorted(ids):
+                del messages[i:j]
+                changed = True
+                continue
+            i = j
+        while messages:
+            last = messages[-1]
+            if last.get("role") == "assistant" and _tool_call_ids_from_assistant(last):
+                messages.pop()
+                changed = True
+                continue
+            break
+
+
+def longest_valid_openai_suffix(
+    body: list[dict[str, Any]], max_len: int
+) -> list[dict[str, Any]]:
+    """
+    取 ``body`` 的尾部子列表，长度不超过 ``max_len``，且对 API 合法；优先更长、更近的尾部。
+    """
+    n = len(body)
+    if n == 0:
+        return []
+    cap = min(max_len, n)
+    for length in range(cap, 0, -1):
+        candidate = body[-length:]
+        if openai_message_list_valid(candidate):
+            return list(candidate)
+    for j in range(n - 1, -1, -1):
+        one = [body[j]]
+        if openai_message_list_valid(one):
+            return one
+    return []
+
+
+def chat_row_to_openai_message(row: ChatMessageRow) -> dict[str, Any] | None:
+    if row.role == "tool":
+        return {
+            "role": "tool",
+            "tool_call_id": row.tool_call_id or "",
+            "content": row.content or "",
+        }
+    if row.role == "assistant":
+        msg: dict[str, Any] = {"role": "assistant", "content": row.content or ""}
+        if row.tool_calls_json:
+            try:
+                tc = json.loads(row.tool_calls_json)
+                if isinstance(tc, list):
+                    msg["tool_calls"] = tc
+            except json.JSONDecodeError:
+                pass
+        return msg
+    if row.role in ("user", "system"):
+        return {"role": row.role, "content": row.content or ""}
+    return {"role": row.role, "content": row.content or ""}
+
+
+def rows_to_messages(rows: list[ChatMessageRow]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for r in rows:
+        m = chat_row_to_openai_message(r)
+        if m:
+            out.append(m)
+    return out
+
+
+def trim_messages_to_token_budget(
+    messages: list[dict[str, Any]], max_tokens: int
+) -> list[dict[str, Any]]:
+    """从头部丢弃消息直至估算 token 不超过 ``max_tokens``（至少保留最后一条）。"""
+    if not messages:
+        return messages
+    m = list(messages)
+    while len(m) > 1:
+        total = sum(estimate_message_tokens(x) for x in m)
+        if total <= max_tokens:
+            break
+        m.pop(0)
+    repair_openai_chat_messages(m)
+    return m
+
+
+def build_hydrated_messages(
+    *,
+    rows: list[ChatMessageRow],
+    truncated_by_count: bool,
+    latest_summary: str | None,
+    context_budget_tokens: int,
+) -> list[dict[str, Any]]:
+    msgs = rows_to_messages(rows)
+    if truncated_by_count and latest_summary:
+        msgs.insert(
+            0,
+            {
+                "role": "user",
+                "content": "[历史摘记 — 更早轮次未载入上下文]\n" + latest_summary.strip(),
+            },
+        )
+    return trim_messages_to_token_budget(msgs, context_budget_tokens)

aicd-0.0.9/src/aicd/agent/chat_serialize.py

@@ -0,0 +1,62 @@
+"""OpenAI 消息与数据库存储之间的序列化。"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+# 多模态计费/上下文粗估：业界常见按每张图约 2k–8k token（分辨率与模型有关）
+VISION_IMAGE_TOKENS_MIN = 2000
+VISION_IMAGE_TOKENS_MAX = 8000
+VISION_IMAGE_TOKENS_ESTIMATE = (VISION_IMAGE_TOKENS_MIN + VISION_IMAGE_TOKENS_MAX) // 2
+
+
+def tool_calls_to_jsonable(tool_calls: Any) -> list[dict[str, Any]]:
+    if not tool_calls:
+        return []
+    out: list[dict[str, Any]] = []
+    for tc in tool_calls:
+        fn = getattr(tc, "function", None)
+        name = getattr(fn, "name", "") if fn else ""
+        args = getattr(fn, "arguments", None) if fn else None
+        out.append(
+            {
+                "id": getattr(tc, "id", "") or "",
+                "type": getattr(tc, "type", None) or "function",
+                "function": {
+                    "name": name,
+                    "arguments": args if isinstance(args, str) else (args or "{}"),
+                },
+            }
+        )
+    return out
+
+
+def estimate_message_tokens(msg: dict[str, Any]) -> int:
+    """
+    粗估 token：纯文本约 4 字符/token；含 ``tool_calls`` JSON。
+    若 ``content`` 为 OpenAI 多模态列表（``text`` + ``image_url``），
+    每张图按 ``VISION_IMAGE_TOKENS_ESTIMATE``（2k–8k 的中值）加计，便于与 ``context_budget_tokens`` 对齐。
+    """
+    raw_c = msg.get("content")
+    if isinstance(raw_c, list):
+        text_chars = 0
+        image_n = 0
+        for part in raw_c:
+            if not isinstance(part, dict):
+                continue
+            if part.get("type") == "text":
+                text_chars += len(str(part.get("text") or ""))
+            elif part.get("type") == "image_url":
+                image_n += 1
+        text_tok = (text_chars // 4 + 1) if text_chars else 0
+        vision_tok = image_n * VISION_IMAGE_TOKENS_ESTIMATE
+        tc = msg.get("tool_calls")
+        extra = len(json.dumps(tc, ensure_ascii=False)) // 4 + 1 if tc else 0
+        return max(1, text_tok + vision_tok + extra)
+
+    n = len(str(raw_c or ""))
+    tc = msg.get("tool_calls")
+    if tc:
+        n += len(json.dumps(tc, ensure_ascii=False))
+    return max(1, n // 4 + 1)

aicd-0.0.9/src/aicd/agent/handlers/__init__.py

@@ -0,0 +1,5 @@
+"""Tool handler functions keyed by OpenAI tool name."""
+
+from aicd.agent.handlers.registry import tool_handlers
+
+__all__ = ["tool_handlers"]

aicd-0.0.9/src/aicd/agent/handlers/agent_settings.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from aicd.config import save_config
+from aicd.config_settings import apply_nested_settings_patch, format_settings_summary
+
+if TYPE_CHECKING:
+    from aicd.agent.tool_router import ToolRouter
+
+
+def _agent_settings_update(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    patch = args.get("patch")
+    if patch is None:
+        return {
+            "ok": True,
+            "message": "no patch; current summary",
+            "summary": format_settings_summary(router._cfg),
+        }
+    if not isinstance(patch, dict):
+        return {"ok": False, "error": "patch must be an object with optional llm / agent keys"}
+    ok, msg = apply_nested_settings_patch(router._cfg, patch)
+    if not ok:
+        return {"ok": False, "error": msg}
+    if bool(args.get("persist", True)):
+        save_config(router._layout["config"], router._cfg)
+    return {
+        "ok": True,
+        "message": msg,
+        "summary": format_settings_summary(router._cfg),
+        "persisted": bool(args.get("persist", True)),
+    }
+
+
+HANDLERS: dict[str, Any] = {
+    "agent_settings_update": _agent_settings_update,
+}

aicd-0.0.9/src/aicd/agent/handlers/ai_viz.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import aicd.tools.viz_assets as viz_assets
+from aicd.kit import chart_spec
+
+if TYPE_CHECKING:
+    from aicd.agent.tool_router import ToolRouter
+
+
+def _ai_output_info(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "workspace": str(router._cwd),
+        "ai_output_dir": str(router._ai_output),
+        "ai_tmp_dir": str(router._ai_tmp),
+        "note": "Write scratch/intermediate analysis under ai_tmp_dir; clean up when done. "
+        "Durable artifacts go under ai_output_dir (not inside tmp unless explicitly temporary).",
+    }
+
+
+def _ai_ensure_layout(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    router._ai_output.mkdir(parents=True, exist_ok=True)
+    router._ai_tmp.mkdir(parents=True, exist_ok=True)
+    return {
+        "ok": True,
+        "ai_output_dir": str(router._ai_output),
+        "ai_tmp_dir": str(router._ai_tmp),
+        "created": True,
+    }
+
+
+def _ai_workspace_set(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    fn = router._ai_workspace_setter
+    if fn is None:
+        return {
+            "ok": False,
+            "error": "ai_workspace_set is only available in the main chat session; use TUI /work <path>.",
+        }
+    raw = args.get("path")
+    if raw is None or (isinstance(raw, str) and not str(raw).strip()):
+        ok, msg = fn(None)
+    else:
+        ok, msg = fn(str(raw).strip())
+    if not ok:
+        return {"ok": False, "error": msg}
+    return {
+        "ok": True,
+        "workspace": msg,
+        "note": "fs_* relative paths and default run_command cwd use this directory.",
+    }
+
+
+def _viz_list_bundled_assets(
+    router: ToolRouter, args: dict[str, Any]
+) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "bundled_dir": str(viz_assets.bundled_res_dir()),
+        "files": viz_assets.list_bundled_viz_files(),
+    }
+
+
+def _viz_copy_resources(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    dest = router._resolve_path(args["target_directory"])
+    if not dest.is_dir():
+        return {"ok": False, "error": "target_directory must be an existing directory"}
+    return viz_assets.copy_viz_resources(dest)
+
+
+def _viz_export_html(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    out = router._resolve_path(args["html_path"])
+    out.parent.mkdir(parents=True, exist_ok=True)
+    title = str(args.get("title") or "Analysis")
+    raw_body = args.get("body_html")
+    body = (raw_body if raw_body is not None else "").strip()
+    if not body:
+        body = viz_assets.demo_body_snippet()
+        boot = True
+    else:
+        body = str(raw_body)
+        boot = bool(args.get("include_demo_chart_vis_bootstrap", False))
+    html = viz_assets.build_viz_html_document(
+        title,
+        body,
+        extra_head=str(args.get("extra_head") or ""),
+        extra_scripts=str(args.get("extra_scripts") or ""),
+        include_default_chart_vis_init=boot,
+    )
+    html = viz_assets.reorder_body_scripts_before_vis_usage(html)
+    out.write_text(html, encoding="utf-8")
+    copied: dict[str, Any] = {"skipped": True}
+    if bool(args.get("copy_resources", True)):
+        copied = viz_assets.copy_viz_resources(out.parent)
+    return {
+        "ok": True,
+        "html_path": str(out),
+        "copy_resources": copied,
+    }
+
+
+def _viz_data_chart(router: ToolRouter, args: dict[str, Any]) -> dict[str, Any]:
+    out = router._resolve_path(args["html_path"])
+    out.parent.mkdir(parents=True, exist_ok=True)
+    title = str(args.get("title") or "Chart")
+    chart_type = str(args.get("chart_type") or "bar")
+    labels = list(args.get("labels") or [])
+    values = list(args.get("values") or [])
+    dataset_label = str(args.get("dataset_label") or "")
+    html = chart_spec.build_html_with_chart(
+        title,
+        chart_type,
+        labels,
+        values,
+        dataset_label=dataset_label or "Series",
+    )
+    out.write_text(html, encoding="utf-8")
+    copied: dict[str, Any] = {"skipped": True}
+    if bool(args.get("copy_resources", True)):
+        copied = viz_assets.copy_viz_resources(out.parent)
+    return {
+        "ok": True,
+        "html_path": str(out),
+        "copy_resources": copied,
+        "ascii_preview": chart_spec.mermaid_bar_from_counts(
+            [str(x) for x in labels],
+            [int(round(float(v))) for v in values],
+        )
+        if len(labels) == len(values)
+        else "",
+    }
+
+
+HANDLERS: dict[str, Any] = {
+    "ai_output_info": _ai_output_info,
+    "ai_ensure_layout": _ai_ensure_layout,
+    "ai_workspace_set": _ai_workspace_set,
+    "viz_list_bundled_assets": _viz_list_bundled_assets,
+    "viz_copy_resources": _viz_copy_resources,
+    "viz_export_html": _viz_export_html,
+    "viz_data_chart": _viz_data_chart,
+}