AskaEth
5b8c7a3ef3
主人 2026-10-07 口径补充：原先把这条红线读成「任何组件都不许开端口」过宽了。 - AGENTS.md §9：红线加限定语（只约束 Cyrene 框架自身）；qq-obv11 那条已登记 例外升格为一般规则的实例；新增插件开端口的四条护栏（显式配置 / 默认绑 127.0.0.1 / 日志与审计 / 不得绕过身份判定）—— 护栏由主代理拟，待主人逐条确认 - Docs/api-client.md v0.88：澄清「插件监听端口不在契约范围内」；零破坏性变更， 无新端点 / 无新帧 / 无字段形状变化，路由计数不变（14 + 25 + 40 = 79） - README.md：用户侧表述同步 DevDocs 侧同步（不进 git）：design/13 §0、design/09 §5、design/08 §4、恢复提示词红线节。
284 lines
23 KiB
Markdown
284 lines
23 KiB
Markdown
# Cyrene v2 — 昔涟
|
||
|
||
> 自托管的「人格化通用智能体运行时」。一个 Go 单二进制，默认以「全能小女友」的人格陪伴你；在聊天/开发/家庭/工作等模式间无感切换；如 OpenClaw 般接入聊天平台（**KOOK / 微信 iLink 已接通**，QQ OneBot v11 链路已打通但暂不连，Telegram 待凭据）；各人格独立记忆与情绪、共享同一套能力。
|
||
|
||
**状态**：M0–M12 里程碑主干已落地，现处于「后 M12 增量切片」阶段。每一项能力以本文的三档清单（已实现 / 需凭据·部分 / 未实现）为准，**不作整体完成宣称**；真实缺口见「已知缺口与路线图」。 ｜ **分支**：`dev` ｜ 设计文档见 `DevDocs/00-overview.md`
|
||
|
||
---
|
||
|
||
## 当前能力（按真实状态分三档，不虚标）
|
||
|
||
> 状态以**代码 + 真机实测**为准。标注「需凭据」的项依赖外部凭据 / endpoint 才能达到完整形态；「未实现」一律如实写出，不当「已修」。
|
||
|
||
### ✅ 已实现
|
||
|
||
- **单二进制、进程内协作** — **框架**的所有服务同进程打包、**框架**仅网关一个对外端口（默认 `:8080`）；框架模块间走进程内接口 + 事件总线，**零跨进程 IPC**。🔴 **2026-10-07 口径补充：该红线只约束框架自身，不约束扩展插件** —— `plugins/` 下的渠道适配器与工具、MCP server、以及插件自己拉起的本地伴随服务**可以开自己的监听端口、可以有自己的进程形态**（原「`qq-obv11` 反连 server 模式」那条例外随之升格为一般规则的实例）。插件端口仍须：**由配置显式给出**、**默认绑 `127.0.0.1`**、**登记日志与审计**、**不得绕过身份判定**
|
||
- **人格化陪伴** — 多人格（`configs/personas/*.yaml`）/ 情绪状态机 / 好感度；**人格 = 身份**（不限制能力）、per-persona 记忆隔离、能力全局共享
|
||
- **通用 Agent 运行时** — 多供应商 LLM（per-role 路由 + 降级：主 → 备 → 本地，本地级默认关）、工具调用（**8 轮上限**）、流式输出、子代理编排（生命周期 / 结果合并 / 并行上限 / 超时 / 防失控）、会话持久化 + 主·次级会话、上下文压缩（预算按模型窗口推导）
|
||
- **记忆系统** — **三类作用域隔离**（用户习惯全局共享 / 角色日常他角色只读 / 项目人人读写 + 项目索引分层）、相关性 + 最近度检索、衰减、溯源、RAG；**LLM 异步提取**（每轮落定后后台提取，手工提取兜底）；**定期记忆整理**（低峰后台任务，只产候选建议、绝不自动改写）；**入库前审查**（D3：新记忆落库前先判定 merge / modify / create / skip，软合并可 `revert` 回滚）
|
||
- **durable execution / checkpoint** — 每步落盘快照，**崩溃后可从最新 checkpoint 续跑**（`loadCheckpoint` → `Step+1`；仅「崩溃遗留的在途 run」允许恢复，已落定退出一律重开）
|
||
- **IM 渠道插件（内置 5 个，随二进制分发）** — **KOOK** ✅、**微信 iLink** ✅（扫码绑定 + 绑定确认时**自动把主人登记进 owner 白名单**，热生效）、**QQ OneBot v11**（正/反 WS × HTTP，四端组合齐；判主 / 收发 / 语音转写均**真机验证过**，但主人 2026-10-05 因风控决定**暂不连**，代码保留）、**Telegram**（长轮询 / webhook，需 Bot token）、**通用 Webhook**（入站，已挂网关）
|
||
- **多渠道主会话同步** — 主人私聊（Web / KOOK / 微信 / QQ）汇聚到主会话，Web 端免刷新镜像；群聊 / 陌生人走独立隔离会话，不写记忆、不入主会话上下文
|
||
- **后台思考与主动推送** — 自主思考心跳 + 事件触发（安全域 / 急性事件可穿透安静时段）+ 静默时段降频（`THINK_QUIET_INTERVAL_SEC`）+ 主动推送限频；**自排思考 `request_think`**（她可在一次思考里给自己排下一轮，有窗口次数上限）
|
||
- **技能（Skill）** — 目录式 YAML（`configs/skills/<id>/skill.yaml`，内含示例 `daily-brief`）；**渐进披露**（清单只给 description，命中才展开正文）+ **工具面收缩**（`allowed-tools` 是能力上限，只收不放）；**`Runner.Run` 多步执行可用**（步骤拓扑 / 环检测 / 并行上限 / guardrail 强制点）
|
||
- **插件声明的管理页面** — `GET /api/v1/admin/panels`（按角色过滤的接入点快照）+ `POST /api/v1/admin/plugins/{id}/actions/{action}`（**真执行**已登记动作，写动作走 owner/admin + 审计）；插件生命周期变化推 WS 帧 `panels_changed`
|
||
- **网络搜索** — 原生 **6 家 provider**（SearXNG 本机兜底 / 智谱 / 阿里 IQS / 博查 / 火山·豆包 / 百度千帆）+ 降级链 + **配置面板热重载**（改配置即生效、无需重启；会让 web-search 无可用后端的改动会被回滚并报 `409`）
|
||
- **文件 / 文档进对话** — 上传 → 抽取正文 sidecar → 按预算注入上下文；**含 PDF 摄取**；引用计数 + 保留期 GC（仍被引用的文件绝不删）
|
||
- **语音** — 云端 **STT / TTS 真实接通**（阿里云百炼 DashScope：`qwen-audio-3.0-asr-flash` / `cosyvoice-v3-flash`），含**声音复刻**入口；IM 入站语音自动转写；**语音落库 + 回放**（消息 DTO `voice` + `GET /api/v1/media/{name}`，支持 Range）；不可播格式（QQ AMR）**转码成 wav** 后再落副本
|
||
- **浏览器工具** — 自研**出站 CDP**（不发 `Runtime.enable`，减少被识别面）；**有头 Chrome + 持久化 profile**（过风控口径）；动作 `open` / `screenshot` / `info`（owner-only）；**截图落盘后自动进本轮上下文**；插件声明页（B4）已落地
|
||
- **MCP 客户端** — 接入官方 MCP SDK（Go）；stdio 子进程 / SSE / Streamable HTTP；工具**自动发现并注册**进能力面
|
||
- **实时全链路流程图（含时间轴）** — `graph_update` 实时帧 + 落盘 `flow_graphs` 多轮历史 + `GET /api/v1/admin/flow/graph`（最近一轮 / 指定 `turnId` / `lanes[]`）+ `GET /api/v1/admin/flow/timeline`（按时间正序的多轮时间轴，支持 `limit` / `before` 分页 + 保留期信号）；**真并行每路各发自己的帧**（不再互相覆盖）；Flow 页提供「最近一轮 / 时间轴」两种视图
|
||
- **超级详尽后台管理面板**（`/admin`，路径可配）— **18 个静态模块**（仪表盘 / 人格 / 会话 / 记忆 / 知识库 / 插件 / 渠道 / 渠道事件 / IoT / LLM / 自动化 / Agent 监控 / 全链路流程 / 后台思考 / 通知 / 可观测性 / 用户与权限 / 系统设置）+ **插件声明的动态页**，统一 RBAC（`owner` > `admin` > `viewer`）+ 审计
|
||
- **系统设置（4 个可写操作）** — 吊销全部 API key / 轮换 JWT / 备份 / 恢复（owner-only + 审计 + 前端确认弹窗）
|
||
- **语境感知 UI** — 用户端是**一个共享页面**：单页消息流，每条消息带自己的 mode，气泡按 mode 渲染（`chat` / `code` / `home` / `work` / `docs` / `voice` / `vision` / `agents` / `settings` 共 9 种）；统一 **Miuix 设计语言** + PWA
|
||
- **多端契约** — 用户侧 REST `/api/v1` + 实时 WS `/ws/chat` + 管理 `/api/v1/admin/*`，**版本化契约 v0.81**（权威文档 `Docs/api-client.md`）
|
||
- **多平台部署** — Linux / Windows / macOS / ARM / Termux；**SQLite 默认**（纯 Go、单二进制）；PG + pgvector **可选增强**（配置后真走语义 / 向量路径）
|
||
|
||
### ⚠️ 部分实现 / 需凭据
|
||
|
||
- **视觉** — 分层路由（主模型 → 工具化视觉 / OCR）与**真推理入口已落地**；真实视觉 / OCR 模型服务**需配 `LLM_VISION_MODEL`（或 `LLM_OCR_MODEL`）及凭据**。无凭据时降级为主模型直接看图 / 视觉·OCR 工具文本描述
|
||
- **语音的真实双向通话（Web 端）** — 上行链路与 STT/TTS 已通；`voice` 模式的「实时通话」交互仍未接（前端标注 deferred）。`edge-tts` / `espeak` 仍是**未实现占位**（无凭据时走降级链到 `silent`）
|
||
- **声音复刻** — 代码路径已实现，但仍**需主人提供公网可访问的参考音频 URL** 方能真建自定义音色
|
||
- **网络搜索的 5 家云端 provider** — 除本机 SearXNG 兜底外，智谱 / 阿里 IQS / 博查 / 火山 / 百度千帆**均需自配 API key，且尚未真机实测**（无凭据）；中文查询在本机兜底上的效果有限
|
||
- **RAG 语义 / 向量检索** — 默认走内置 n-gram / FTS 向量（dim=256，离线可用）；配置 `EMBEDDING_API_URL` + PG/pgvector 后走**真语义**路径
|
||
- **微信 iLink 绑定依赖微信侧资格** — 扫码协议已对齐官方并打通；仍需微信账号侧具备 iLink bot 绑定资格（账号环境依赖）
|
||
- **QQ OneBot v11** — 代码链路与真机验证都成立，但按主人决定**当前不连**（风控原因）；接回只需配置并在面板启用
|
||
- **主动推送的设备兜底（Getui）** — 自建推送服务的 webhook 出口已实现（`PUSH_EXPORTER_*`）；个推（Getui）**SDK 未接入**，仅预留字段
|
||
|
||
### ❌ 未实现（当前不提供）
|
||
|
||
- **`Runner.Run` 多步工作流未接进 loop** — 技能进入 loop 的目前只有「清单 / 命中展开正文 / 工具面收缩」；多步工作流执行器（`Runner.Run` / `Runner.RunSkill`）本身可用且有单测，但**模型还不能在对话里直接触发一套多步技能**
|
||
- **浏览器 MCP 委派未落地** — `browser` 工具只提供 `open` / `screenshot` / `info`；`click` / `type` / `wait` / `extract` 仅在工具描述里指路，实际需经 MCP 浏览器服务补齐（未接）
|
||
- **搜索降级档 B5 未做**、浏览器容器 docker 配方（CJK 字体）**未落盘**、浏览器会话**未挂进程关闭链**
|
||
- **系统设置**：编辑环境变量 / 重启服务 / 检查更新 — 后端未实现，不提供
|
||
- **自排思考 C2 的写路径（面板可调）** — 自排的**成本可见面（读侧：`?trigger=` 筛选）已落地**；把后台思考调优参数做成**面板可保存**（`SaveBackgroundTuning` + admin 端点）的部分仍在做
|
||
- **全链路 P2 剩余** — token / 耗时统计、移动端优化（并行路 / 泳道 / 节点实时日志本身已落地）
|
||
- **群聊类能力** — 冷避、@ 窗口期、戳一戳回应等**全部依赖有群聊的平台**；因 QQ 暂不连、微信 iLink 只支持绑定微信号私聊，当前暂无活体群聊对象（队列保留，不删）
|
||
- **IM 路由主动消息的行 id 回填（design/19 §6.10-2）** — 需扩 `SendProactive` 返回值并改全部 mock，本期不做
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 0. 前置
|
||
- **Go 1.26**、**Node 22**（前端构建用）、**Docker**（可选：PG + pgvector；不用 PG 可仅用 SQLite）。
|
||
|
||
### 1. 构建
|
||
|
||
```bash
|
||
# 前端（必做一次：go:embed 需要 dist；构建脚本会同步到 internal/webui/dist）
|
||
cd frontend/web && npm ci && npm run build && cd ../..
|
||
|
||
# 后端二进制（Windows）
|
||
scripts\ctrl.bat build
|
||
# Linux / macOS（无 build 子命令，直接 go build）
|
||
go build -ldflags="-s -w" -trimpath -o cyrene ./cmd/cyrene/
|
||
```
|
||
|
||
> `scripts\ctrl.bat build` 是 Windows 上的权威构建（带 `-ldflags="-s -w" -trimpath`），产物写到仓库根 `cyrene.exe`。
|
||
> **换二进制**：先 `build` 到位，再**一次** `restart`（不留空窗）。
|
||
> **纯前端改动不需要重启后端**：运行时**优先读磁盘 `frontend/web/dist`**（存在即覆盖内嵌 dist），刷新浏览器即可。
|
||
|
||
### 2. 启停（本地服务控制）
|
||
|
||
```bash
|
||
# Windows
|
||
scripts\ctrl.bat start # 启动（无参 = start；已在跑则跳过）
|
||
scripts\ctrl.bat stop # 停止（先优雅、后强杀）
|
||
scripts\ctrl.bat restart # 停止 + 启动
|
||
scripts\ctrl.bat status # 端口 + PID + /api/v1/health
|
||
scripts\ctrl.bat build # 只构建二进制
|
||
|
||
# Linux / macOS（等价，无 build）
|
||
bash scripts/ctrl.sh start|stop|restart|status
|
||
```
|
||
|
||
> 端口取 `.env` 的 `PORT`，缺省回落 `10080`。日志 `%USERPROFILE%\cy.log`（每次启动前把上一份归档为 `cy.log.<时间戳>.bak`，保留最近 20 份），PID 文件 `%USERPROFILE%\.cyrene.pid`。
|
||
> 启动默认**分离进程**（`Start-Process -WindowStyle Hidden`）：从 Git Bash 调 `restart` 时请把输出重定向到文件（`> /tmp/cy-restart.log 2>&1 < /dev/null`），否则 bash 会等管道 EOF 而「不返回」；**判定成功要看「新 PID + health ok + 启动日志」，不是看命令退没退出**。
|
||
|
||
### 3. 配置 `.env`（复制 `.env.example`）
|
||
|
||
```bash
|
||
# 认证（JWT_SECRET 必填 ≥32，过短启动即 panic）
|
||
JWT_SECRET=<≥32 字符随机串>
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=<你的密码>
|
||
|
||
# LLM（LLM_PROVIDER 显式声明协议：openai / anthropic，默认 openai）
|
||
LLM_PROVIDER=anthropic
|
||
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
|
||
ANTHROPIC_API_KEY=<key>
|
||
ANTHROPIC_MODEL=deepseek-flash
|
||
# 或 OpenAI 兼容：LLM_PROVIDER=openai + LLM_BASE_URL / LLM_API_KEY / LLM_MODEL
|
||
|
||
# 数据库（可选增强：PG + pgvector 向量检索；不配则用 SQLite）
|
||
DB_PG_URL=postgres://cyrene:cyrene_pass@localhost:5432/cyrene_ai?sslmode=disable
|
||
|
||
# 记忆嵌入（真语义；EMBEDDING_API_URL 必须是【完整 /v1/embeddings 端点】，不是 base）
|
||
EMBEDDING_API_URL=http://localhost:11434/v1/embeddings
|
||
EMBEDDING_MODEL=Qwen3-Embedding-0.6B
|
||
```
|
||
|
||
### 4. 可选依赖
|
||
|
||
```bash
|
||
# PG + pgvector（可选增强：向量索引走这里）
|
||
docker compose -f docker-compose.dev.yml up -d pg
|
||
|
||
# 本地 embedding（可选：真语义；llama.cpp + Qwen3 GGUF，CPU/GPU）
|
||
scripts\embed.bat start|stop|status # Linux / macOS：见 embed.bat 内注释自行起 llama-server
|
||
|
||
# 本机 SearXNG 兜底搜索（可选；配置见 scripts/searxng/settings.yml）
|
||
```
|
||
|
||
> `scripts/dev-up.sh` 是 Linux / macOS 上的**一键全流程**（PG → llama.cpp embedding → 前端 build → cyrene），约定 llama.cpp 放 `~/apps/llama.cpp/`、GGUF 放 `~/.models/`、二进制 `~/apps/cyrene/cyrene`；已运行的服务自动跳过。
|
||
|
||
### 5. 访问
|
||
|
||
- 用户端 SPA：`http://localhost:8080`（按 `.env` 的 `PORT`）
|
||
- 管理面板：`http://localhost:8080/<ADMIN_PATH>`（`ADMIN_PATH` 默认 `admin`；REST/admin API 仍是 `/api/v1/admin/*`，安全靠 JWT + 角色门）
|
||
|
||
### 6. 服务端口 / 路径速查
|
||
|
||
| 服务 | 地址 / 路径 | 说明 |
|
||
|------|------------|------|
|
||
| Cyrene 网关 | `http://localhost:8080`（`.env:PORT`） | SPA + REST/WS + 面板 |
|
||
| PG + pgvector | `localhost:5432`（docker `cyrene-pg`） | 可选；向量索引在 `cyrene_ai` |
|
||
| llama.cpp embedding | `http://localhost:11434/v1/embeddings` | 可选；Qwen3 |
|
||
|
||
---
|
||
|
||
## 配置
|
||
|
||
### `.env` 已冻结（最小化可跑，不加 / 不改 / 不删）
|
||
|
||
`.env` 只保证「**最小化功能可跑**」的引导面，**不是配置面**。主人 2026-10-06 定红线：
|
||
|
||
- **基础键已经定好，以后不准改**：不加、不改、不删；模板 `.env.example` 与 `.env` 同进退。
|
||
- **新配置一律不进 `.env`**：调优 / 门槛 / 上限 / 开关类参数走 **`$DATA_DIR/config/**`**（管理面板可改、热重载）+ 代码内默认值。
|
||
- 既有基础键与既有 `env:` tag **保持现状**（不迁移、不改默认值、不删键）。
|
||
|
||
> 想要调优项请走面板（如「LLM 模型」页写 `models.json`、「渠道管理」页写 `channels.json`、插件配置写 `$DATA_DIR/config/plugins/<plugin-id>.json`），或直接改 `$DATA_DIR/config/**` 下的文件。
|
||
> 口径全文见 `DevDocs/design/13 §2.1`；`AGENTS.md §10` 亦载明。
|
||
|
||
### 数据目录 `DATA_DIR`
|
||
|
||
默认 `./data`；显式写 `platform`（保留字哨兵）则走平台标准数据目录（Windows `%APPDATA%\Cyrene`、macOS `~/Library/Application Support/Cyrene`、Linux `~/.local/share/cyrene`）。
|
||
|
||
---
|
||
|
||
## Embedding 模型推荐
|
||
|
||
> 用于长记忆 / 知识库的**语义向量检索**（默认不配 = 内置 n-gram 向量，dim=256，离线但质量一般）。
|
||
> 配了 `EMBEDDING_API_URL` / `EMBEDDING_MODEL` 后走**真语义**。维度 = 模型 dim，与向量索引一致；**切换模型会改维度，需清空旧向量数据**。
|
||
|
||
| 模型 | dim | 大小 | 推理内存 | 质量 | 建议 |
|
||
|------|-----|------|---------|------|------|
|
||
| **Qwen3-Embedding-0.6B** | 1024 | Q8_0 **639MB** / f16 1.2GB | ~0.7–1GB | ★★★★★（多语言、2025 新、MTEB 榜前列） | ⭐ **首选**（ModelScope 国内可下 + GGUF） |
|
||
| **bge-m3** | 1024 | ~2.2GB(fp16) / ~1.2GB(Q4) | ~2–3GB | ★★★★★（跨语言标杆） | 内存 / GPU 充裕时可用 |
|
||
| **bge-small-zh-v1.5** | 512 | ~30–100MB | ~几十MB | ★★★★ | 极轻量备选 |
|
||
| nomic-embed-text | 768 | ~270MB | ~400–600MB | ★★★☆ | 可 |
|
||
| mxbai-embed-large | 768 | ~350–670MB | ~0.8–1GB | ★★★★ | 可 |
|
||
|
||
> **首选说明**：**Qwen3-Embedding-0.6B**（阿里通义开源，覆盖 100+ 语言）——**有 GGUF**、**ModelScope（魔搭）国内直连可下**（HuggingFace 在国内已不可访问）；`Q8_0` 仅 **639MB**，内存紧张（如 ~3GB 可用、无独立显存的 UMA GPU）也能跑，质量≈f16。
|
||
>
|
||
> **llama.cpp 能替代 Ollama 吗？** 能，且更省内存。`llama-server`（服务模式）暴露 **OpenAI 兼容 `/v1/embeddings`**：
|
||
> ```bash
|
||
> ./llama-server -m Qwen3-Embedding-0.6B-Q8_0.gguf --embeddings -ngl 99 --host 127.0.0.1 --port 11434
|
||
> # 然后 EMBEDDING_API_URL=http://localhost:11434/v1/embeddings 照用（dim=1024；切换前清一次向量表）
|
||
> ```
|
||
> - **Ollama**：模型管理方便（`pull`）、开箱即用，但常驻偏重。
|
||
> - **llama.cpp**：单文件更轻、可离线自制 GGUF；但模型要自己下 / 转（无 registry）。**只认 GGUF**，`model.safetensors` 不能直接喂。
|
||
|
||
### 注意事项
|
||
|
||
- **勿用 `/tmp` 放二进制 / 模型**（tmpfs 在内存里）；一律 `~/apps/`、`~/.models/`。
|
||
- `EMBEDDING_API_URL` **必须是完整 `/v1/embeddings`**（不是 base），否则 404。
|
||
- **切换 embedding 模型会改维度**（Qwen3=1024，n-gram=256）→ 换模型前清一次向量表：`docker exec cyrene-pg psql -U cyrene -d cyrene_ai -c "TRUNCATE vec_items;"`。
|
||
- LLM 用 anthropic 协议时填 `ANTHROPIC_*`；用 openai 兼容时填 `LLM_*`。`LLM_PROVIDER` 二选一。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
Cyrene_v2/
|
||
├── cmd/cyrene/ # 唯一入口（wire_*.go 组合根：把各子系统接线 + go:embed 前端）
|
||
├── internal/ # 进程内模块（不对外）
|
||
│ ├── config/ # .env 加载 + $DATA_DIR/config/** 可变源（面板一等来源）
|
||
│ ├── logger/ platform/ db/ bus/ errors/ auth/ user/ # 地基
|
||
│ ├── runtime/ # 核心运行时：model / agent / loop / tool / guardrail / trace /
|
||
│ │ # persist(checkpoint) / memory / embedding / multimodal /
|
||
│ │ # orchestration / exec / task / flowgraph / documents / voice / capacity
|
||
│ ├── persona/ capability/ channel/ iot/ urgency/ contract/
|
||
│ ├── services/ # gateway(REST/WS/admin) / automations / backthink / approvalreview / channelbridge
|
||
│ └── webui/ # 内嵌前端 dist（go:embed）
|
||
├── plugins/ # 一等插件：tools(basic/io/browser) + channels(kook/qq_obv11/telegram/webhook/weixin_ilink)
|
||
├── pkg/plugins/sdk/ # 插件 SDK（第三方接入）
|
||
├── configs/ # 配置模板：personas/ + users/（主人档案）+ skills/（示例技能）
|
||
├── frontend/web/ # React SPA（单页消息流 + mode 渲染器）+ 管理面板（Miuix）；构建产物 dist/ 供磁盘热覆盖
|
||
├── Docs/ # 用户文档（进 git）：api-client.md（客户端 API 契约）+ archive/
|
||
├── DevDocs/ # 开发文档（**不进 git**，本地锚点：设计 / 时间线 / 工作小结 / 审计）
|
||
├── data/ # 运行时数据（DATA_DIR；SQLite / uploads / 面板写入的 *.json）
|
||
├── scripts/ # ctrl.bat / ctrl.sh / embed.bat / dev-up.sh / searxng/
|
||
└── services/ # 预留（外部服务扩展位）
|
||
```
|
||
|
||
> `Docs/`（大写 D）**进 git**；`DevDocs/` **被 gitignore，不进 git**。`*.exe`、`dist/`、`data/`、`.env` 等亦不入库（见 `.gitignore`）。
|
||
|
||
---
|
||
|
||
## 已知缺口与路线图
|
||
|
||
> **不美化**：以下是**当前真做不了 / 没做完**的事。
|
||
|
||
**核心运行时**
|
||
1. 🔴 **`Runner.Run` 多步工作流未接进 loop** — 技能的多步执行器可用且有单测，但**模型还不能在对话里触发一整套多步技能**（现只到「清单 / 命中展开正文 / 工具面收缩」）。
|
||
2. **自排思考 C2 的写路径未做** — 自排的成本可见读侧（`?trigger=` 筛选）已落地，面板可保存的后台思考调优（`SaveBackgroundTuning` + admin 端点）在做。
|
||
3. **全链路 P2 剩余** — token / 耗时统计、移动端优化。
|
||
|
||
**浏览器**
|
||
4. 🔴 **MCP 委派未落地** — `click` / `type` / `wait` / `extract` 尚未接通（只在工具描述里指路）。
|
||
5. **搜索降级档 B5 未做**；容器 docker 配方（CJK 字体）未落盘；浏览器会话未挂进程关闭链。
|
||
|
||
**渠道**
|
||
6. **QQ OneBot v11 暂不连**（主人 2026-10-05 因风控决定）；**Telegram 需 Bot token**。群聊类能力（冷避 / @ 窗口 / 戳一戳）因此暂无活体平台可验。
|
||
7. **搜索 5 家云端 provider 未真机实测**（无 key）；微信 iLink 依赖微信侧绑定资格；声音复刻需公网参考音频 URL。
|
||
8. **视觉 / OCR 真模型需凭据**；`edge-tts` / `espeak` 仍是占位。
|
||
|
||
**治理 / 其他**
|
||
9. **系统设置**：编辑环境变量 / 重启服务 / 检查更新 — 后端未实现。
|
||
10. **Getui（个推）兜底未接入**（SDK 未接）；待主人自建推送服务。
|
||
11. **部分真机端到端未验**（如实登记）：时间轴真机面板联调、搜索 provider 热重载真机端到端、AMR 落副本生产端到端、`graph_update` 真并行真机端到端、`design/19 §6.8` 的 Q1–Q4。
|
||
12. **Android 客户端**另会话推进（跨仓协同事项见 `DevDocs`，不入本仓库）。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| 后端 | Go 1.26（单二进制运行时）、进程内事件总线（API 刻意对齐 NATS，便于日后换出进程 transport）、`slog`（日志带 `source` 来源标注） |
|
||
| 前端 | React 19、TypeScript、Vite 6、Tailwind 4、Zustand 5、PWA（Miuix 设计语言） |
|
||
| 数据库 | **SQLite 默认**（纯 Go、单二进制）；PG + pgvector 可选增强（配置后真生效） |
|
||
| 多模态 | vision（分层路由：主 / 视觉 / OCR；真模型需凭据，无凭据降级主模型）、voice（DashScope STT/TTS 真实接通 + 降级链；无凭据降级 `silent`） |
|
||
| LLM | 多供应商（OpenAI 兼容 / Anthropic / 本地 / 网关）、per-role 路由 + 降级（主 → 备 → 本地） |
|
||
| 插件 / 协议 | 进程内插件 SDK（`pkg/plugins/sdk`）、官方 MCP SDK（stdio / SSE / Streamable HTTP） |
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
| 文档 | 位置 | 说明 |
|
||
|------|------|------|
|
||
| 架构总览 / 重构蓝图 | `DevDocs/00-overview.md` | 产品定位、架构、渠道插件、后台面板、阶段计划（**本地，不进 git**） |
|
||
| 开发约束 | `DevDocs/02-development-constraints.md` | 编码规范 + 性能要求（**本地**） |
|
||
| **客户端 API** | `Docs/api-client.md` | 跨平台客户端 API 契约（REST / WS / admin，版本化，当前 **v0.81**） |
|
||
| 开发铁律 | `AGENTS.md` | 每会话自动注入；含全球红线（单二进制 / 身份识别 / 前端 Miuix 等） |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Apache-2.0 © 2026 Aska
|