# 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`** |
