haoyuan 0.0.0-stage → 1.0.0

package/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+## Project commands
+
+- Backend tests: `cd api && python -m pytest -q`
+- Backend run: `cd api && python main.py` (base port 8030, env `HAOYUAN_PORT`; auto +1 when busy, actual port written to `api/data/runtime.json`)
+- Frontend dev: `cd web && npm run dev` (base port 8130, env `HAOYUAN_WEB_PORT`; auto +1 when busy, proxies `/api`, `/docs` and `/ws` to `HAOYUAN_API_PORT` or `runtime.json` `api_port`)
+- Frontend build: `cd web && npm run build`
+- Production: build the frontend, then run the API; the API serves `web/dist` at `/`.
+- Plugin center (separate repo `../hao-yuan-plugin-center`): `cd ../hao-yuan-plugin-center && python main.py` (base port 8180, env `PLUGIN_CENTER_PORT`). The API connects to it via `HAOYUAN_PLUGIN_CENTER_URL` (default `http://127.0.0.1:8180`).
+- `desktop.exe` (source `desktop/desktop.cs`, build `desktop\build.bat`): can override base ports via `api_port_config` / `web_port_config` in `api/data/runtime.json` and restart services.
+
+## Architecture invariants
+
+- `core/` is the kernel. It must not import from `plugins/`.
+- Business capabilities belong in `plugins/<name>/` and register through `register(ctx)`.
+- Plugins may add routers, tools, agents, skills and middlewares through `PluginContext` (`add_router`, `add_middleware`, `on`). Toggle hooks receive `(name, enabled)`.
+- Tool handlers receive `(ctx: ToolContext, args: dict)` and must respect `ctx.workspace`.
+- Every state-changing tool that touches the filesystem or executes commands must be `confirm=True` and high risk.
+- Events are append-only in SQLite and broadcast over WebSocket. Do not log secrets into event payloads.
+- The API envelope is `{ code, data, message }`; `code` is 200 on success.
+- Frontend state lives in `web/src/stores/app.js`; API calls go through `web/src/api/client.js`.
+
+## Verification discipline
+
+- After backend changes: run `python -m pytest -q` in `api/`.
+- After frontend changes: run `npm run build` in `web/`.
+- For UI changes, take Playwright screenshots at 1440x900 and 430x900 with the local Chrome executable, and verify there are no console errors or 404 resources.
+- Never claim live-model verification without a configured API key; use mock-mode tests and state that limitation explicitly.

package/README.md

@@ -1,3 +1,585 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 豪源 · HaoYuan
+
+> 个人指挥 AI 实现多个 AI 员工异步并行工作的 AI 工作室。  
+> 一个内核，一组可安装插件，一套可验证的长程任务闭环。
+
+豪源以 **agent-harness** 为后端参考底座重写，保留并强化了 AI 助理的编程专长，同时用插件化架构重新组织了会话、工具、Agent、路由、技能、监督与编排。前端完全重写，目标是把「AI 协作」从聊天窗口升级为可指挥、可观察、可干预的工作台。
+
+![Workbench](docs/screenshots/workbench-dark.png)
+
+---
+
+## 1. 核心特性
+
+### 1.1 真正可用的编码闭环
+
+| 能力 | 实现 |
+|---|---|
+| 仓库感知 | `project_scan`、`repo_map`、符号索引、`search_symbol` |
+| 精准读取 | `read_file`、`read_range`、行号定位 |
+| 最小编辑 | `apply_patch`（unified diff / SEARCH-REPLACE）、`edit_file`、`multi_edit` |
+| 文件操作 | `write_file`、`glob`、`grep`、`list_dir`、`delete_path`、`move_path` |
+| 命令验证 | `run_shell`（UTF-8、超时、结构化错误摘要）、`git` 封装 |
+| 验证门禁 | 代码写完后强制要求跑测试/lint/build，避免「只改不验」 |
+| 测试修复环 | pytest 失败结构化解析 → 定位行 → 最小修复 → 失败指纹升级策略 |
+| 子代理 | `task` 在独立上下文侦察，只回填结论，避免污染主上下文 |
+| 上下文治理 | 工具结果老化、结构化摘要、轮内压缩、硬预算裁剪 |
+| 上下文预装 | 需求感知 `repo_map` 排序 + 复杂题相关源码 `context_pack`（最多约 30KB），减少重复整读 |
+| 长程任务 | 步数预算、自动续跑、检查点、幂等副作用登记（写操作不重复施加） |
+| 人机协同 | 高风险写操作/命令弹出 diff 预览，批准或拒绝后才执行 |
+
+会话意图分层：寒暄、闲聊与通用问答直接回答，不扫描工作区、不触发工具或写入；只有编码、改文件、跑命令等明确任务才进入编码闭环。
+
+### 1.2 多会话异步并行
+
+- 一个会话 = 一个后台 `asyncio.Task`，切窗、关页、断线都不会停止任务。
+- 全局并发闸 + FIFO 排队；等待人工审批时自动让出并发槽。
+- 会话状态机：`idle → queued → running ⇄ waiting_input → done / error`。
+- 工作台顶部会话标签栏：新建或打开会话自动生成标签，点击即可横向切换，`×` 仅关闭视图不删除会话，刷新后保留。
+- 新会话的首条消息会由模型按当前界面语言生成短标题；旧会话若仍是默认标题，则按首条消息自动显示摘要。
+- 每个会话拥有独立地址 `/#/s/<session-id>`，可直接复制、刷新、分享或直接在地址栏切换。
+- 刷新页面后从 SQLite 恢复消息、事件、计划、审批与产物。
+- 前端实时事件主通道使用 SSE（断线重连、游标续传、无需 WebSocket 也能流式输出）；WebSocket 端点保留用于兼容；REST 支持事件回放。
+
+### 1.3 AI 总管与多智能体编排
+
+- **Supervisor**：跨会话健康巡检、卡死告警、自动中断、控制台对话与调度动作。
+- **Orchestrator**：目标 → 任务 DAG → 每个员工独立 git worktree → 并行执行 → 合并验收。
+- 员工会话共享契约文件与共享黑板，失败不阻塞同层其它任务。
+
+### 1.4 技能库（Skills）
+
+- Markdown + front-matter，声明 `name / title / description / kinds / triggers`。
+- 按任务类型与关键词自动匹配；技能多了自动切 BM25 排序。
+- 内置：核心方法论、仓库工程闭环、Debug 闭环、网页交付、方案写作、视频分镜。
+- 支持在 UI 中新建、编辑、删除技能，保存即生效。
+
+### 1.5 方案 / 分镜文档
+
+- `make_plan`：生成独立 HTML 方案/计划书，含 KPI、章节、表格、风险、里程碑。
+- `make_storyboard`：生成视频分镜脚本（镜头、时长、画面、口播）。
+- 产物登记到 `api/data/artifacts/`，工作台右侧可直接预览/下载。
+
+### 1.6 插件化架构
+
+豪源不是「一个巨大的单体」，而是：
+
+```
+Kernel（会话 / 事件 / 工具注册 / 策略 / 模型网关 / 审批）
+        │
+        ├── coding      编码 Agent + 工程工具 + 技能
+        ├── plans       方案工具 + Planner Agent
+        ├── video       分镜工具 + Video Agent
+        ├── supervisor  巡检 + 控制台路由
+        ├── orchestrator 任务 DAG + worktree + 合并
+        └── embodied    具身 Agent Harness（默认关闭，可安装启用）
+```
+
+插件可以贡献：工具、Agent、HTTP 路由、技能目录、事件订阅、生命周期钩子、前端导航/命令元数据。单个插件加载失败不会拖垮内核。
+
+![Plugins](docs/screenshots/plugins.png)
+
+### 1.7 三语言、浅色默认与可收起侧栏
+
+- 默认 **浅色（白色）主题**，可在设置页或侧栏底部切换为深色。
+- 默认 **简体中文**，可在 **简体中文 / 繁體中文 / English** 之间切换。
+- 语言入口放在三个显眼位置：工作台顶栏、侧栏底部（所有页面可用）、设置页「外观」。
+- 选择持久化到 `localStorage`，刷新和重启后保持；同时更新 `document.lang` 与页面标题。
+- 侧栏可收起为 76px 图标栏；收起后顶部保留明确的「展开侧栏」按钮，会话列表自动隐藏，恢复后完整还原。
+- 右侧洞察面板默认收起，给对话区留出更多空间；点击右上角按钮打开，用户选择会持久化。
+- 内置技能标题、描述，插件标题、描述，状态、按钮、提示、审批、计划、用量、编排等 UI 文案均已完成三语言覆盖。
+
+---
+
+## 2. 快速开始
+
+### 匿名使用统计（透明声明）
+
+豪源内置一个**完全匿名**的使用统计心跳，用于统计在线设备数与版本分布：
+
+- **上报内容**：本地随机生成的 `install_id`（UUID）、客户端版本号、操作系统类型（如 `Windows 11`）。不含用户名、邮箱、文件内容、工作区路径、对话内容等任何个人数据。
+- **上报频率**：启动后及运行期间每 5 分钟一次（仅一次轻量 POST 请求）。
+- **完全可关闭**：启动前设置环境变量 `HAOYUAN_TELEMETRY=0` 即永久关闭，所有功能不受影响。
+- **隐私保障**：服务端只记录 IP 的单向哈希，不存明文 IP；数据保留 90 天。
+- **完整声明**：见插件中心隐私接口 `GET {插件中心地址}/api/plugin-center/privacy`，或源码 `api/core/telemetry.py`（约 100 行，可自行审计）。
+
+### 环境要求
+
+- Python 3.10+
+- Node.js 18+
+- Windows / Linux / macOS
+
+### Windows 一键启动
+
+```bat
+start.bat
+```
+
+脚本会自动：停止 8030 上的旧进程 → 创建 `api/env1` → 安装 Python 依赖 → 安装前端依赖 → 每次重新构建前端 → 启动 API，并自动打开产品网页。这样不会因为旧进程或旧静态资源导致流式事件异常。
+
+**端口自动顺延**：后端默认 `8030`、前端默认 `8130`；启动时若端口被占用会自动 +1（8031、8032…）直到绑定成功。实际端口写入 `api/data/runtime.json`，启动脚本会读取后直接打开正确地址。也可用环境变量 `HAOYUAN_PORT` / `HAOYUAN_WEB_PORT`（前端）、`HAOYUAN_API_PORT`（前端代理目标）显式指定基准端口。
+
+停止：
+
+```bat
+stop.bat
+```
+
+### 桌面控制台（desktop.exe）
+
+双击根目录的 `desktop.exe` 打开图形化控制台（约 20 KB，仅依赖 Windows 自带的 .NET Framework 4.x）：
+
+- **全部启动 / 全部关闭**：一键管理后端与前端开发服务，启动后自动打开产品网页
+- **启动 / 停止后端**（默认 8030）、**启动 / 停止前端**（默认 8130）
+- **端口设置**：可直接修改后端 / 前端端口，点击「应用端口并重启」保存配置并自动重启两个服务；端口被占用时服务仍会自动 +1 顺延
+- **打开产品网页**：自动打开后端实际端口（`api/data/runtime.json`），仅前端运行时回退前端端口
+- **构建前端**、**打开项目目录**、每秒刷新的服务状态与实时运行日志
+
+关闭控制台窗口不会停止服务，如需停止请点击「全部关闭」或对应的停止按钮。源码位于 `desktop/`，修改后运行 `desktop\build.bat` 可重新编译。
+
+### Linux / macOS
+
+```bash
+bash start.sh
+bash stop.sh
+```
+
+### 手动启动
+
+```bash
+# 后端
+cd api
+python -m venv env1
+env1\Scripts\activate           # Linux: source env1/bin/activate
+pip install -r requirements.txt
+python main.py                  # http://127.0.0.1:8030，被占用时自动 +1
+
+# 前端开发模式（热更新，可选）
+cd web
+npm install
+npm run dev                     # http://localhost:8130，被占用时自动 +1；/api 与 /ws 代理到后端实际端口
+```
+
+生产模式由后端直接托管 `web/dist`，只需要访问后端实际端口。端口可通过环境变量覆盖：`HAOYUAN_PORT`（后端，默认 8030）、`HAOYUAN_WEB_PORT`（前端，默认 8130）、`HAOYUAN_API_PORT`（前端代理目标，默认读取 `api/data/runtime.json`）。
+
+### 配置模型
+
+```bash
+copy api\configs\secrets_example.py api\configs\secrets_local.py
+```
+
+编辑 `api/configs/secrets_local.py`：
+
+```python
+DEEPSEEK_API_KEY = "sk-..."
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+DEEPSEEK_MODEL = "deepseek-flash"
+
+# 可选：智谱
+ZHIPU_API_KEY = ""
+
+# 可选：小米 MiMo（公平评测使用的模型）
+MIMO_API_KEY = "tp-..."
+MIMO_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1"
+MIMO_MODEL = "mimo-v2.6-flash"
+```
+
+也可以使用环境变量（优先级高于文件）：
+
+```powershell
+$env:DEEPSEEK_API_KEY="sk-..."
+```
+
+**未配置任何 Key 时自动使用本地 `mock` 模型**，完整跑通会话、工具调用、审批、事件与前端。
+
+---
+
+## 3. 界面
+
+| 工作台（浅色，默认） | 工作台（英文） |
+|---|---|
+| ![](docs/screenshots/workbench-light.png) | ![](docs/screenshots/workbench-en.png) |
+
+| 工作台（繁體中文） | 工作台（深色） |
+|---|---|
+| ![](docs/screenshots/workbench-tw.png) | ![](docs/screenshots/workbench-dark.png) |
+
+| 总管控制台 | 技能库 |
+|---|---|
+| ![](docs/screenshots/console.png) | ![](docs/screenshots/skills.png) |
+
+| 设置与语言入口 | 侧栏收起后的展开按钮 |
+|---|---|
+| ![](docs/screenshots/settings.png) | ![](docs/screenshots/collapsed.png) |
+
+移动端右侧洞察面板：  
+![](docs/screenshots/mobile-panel.png)
+
+主要交互：
+
+- 顶部会话标签：点击切换对话框，`×` 关闭标签（不影响会话数据）
+- 新建任务不再提供预设问题，直接在输入框描述即可；会话标题会自动摘要
+- 地址栏路由：`/#/s/<session-id>` 对应具体会话，可直接复制、刷新或在新窗口打开
+- `Ctrl / Cmd + K`：命令面板（导航、会话、动作）
+- `Ctrl / Cmd + N`：新建任务
+- `Ctrl / Cmd + B`：折叠 / 展开侧栏
+- `Enter`：发送；`Shift + Enter`：换行（`Ctrl / Cmd + Enter` 同样发送）
+- 审批卡片：`A` 批准、`R` 拒绝
+- 语言切换：工作台右上角、任意页面侧栏底部、设置页「外观」
+- 会话运行中继续输入：作为「追加指令」合并进当前执行，不打断任务
+- 右侧面板默认收起；点击右上角按钮展开，包含概览 / 计划 / 文件 / 变更 / 产物，支持拖拽调整宽度
+- 文件与 diff 使用大尺寸预览弹层，避免窄栏阅读代码
+
+---
+
+## 4. 架构
+
+```text
+hao-yuan/
+├── api/
+│   ├── main.py                    FastAPI 入口（扩展路由 + 插件路由 + 静态前端）
+│   ├── configs/                   配置、模型注册、密钥
+│   ├── core/
+│   │   ├── contracts.py           Tool / Agent / Policy / ToolContext
+│   │   ├── storage.py             SQLite (WAL) 存储层
+│   │   ├── events.py              事件总线（广播 + 批量落库 + 回放）
+│   │   ├── gateway.py             模型网关（流式 + 降级 + fallback）
+│   │   ├── context.py             上下文压缩 / 老化 / 硬预算
+│   │   ├── runtime.py             Agent 主循环
+│   │   ├── session_manager.py     并发闸 / 排队 / 审批 / 续跑
+│   │   ├── policy.py              权限门禁
+│   │   ├── tools.py               工具注册与执行
+│   │   ├── agents.py              Agent 注册
+│   │   └── plugin.py              插件发现 / 依赖 / 生命周期
+│   ├── harness/                   沙箱 / 技能 / 符号索引 / 修复环 / 监督 / 编排 / 具身
+│   ├── tools/                     builtin / dev / plan
+│   ├── adapters/providers/        deepseek / mimo / mock
+│   ├── plugins/                   coding / plans / video / supervisor / orchestrator / embodied
+│   ├── extensions/                系统 / 会话 / 技能 / 设置 / 文件 / 用量 / 插件 / 审批 / 实时事件（SSE / WebSocket）
+│   ├── skills/                    核心技能
+│   ├── tests/                     28 个后端测试
+│   └── data/                      运行时数据（gitignore）
+├── web/                           Vue 3 + Vite
+├── docs/screenshots/              界面截图
+├── start.bat / stop.bat
+├── start.sh / stop.sh
+├── dev.bat
+├── desktop.exe                    图形化桌面控制台（启停服务 / 打开网页）
+└── desktop/                       desktop.exe 源码与构建脚本
+```
+
+### 数据与边界
+
+- 数据库：`api/data/haoyuan.db`（WAL）
+- 产物：`api/data/artifacts/<session_id>/`
+- 运行时端口：`api/data/runtime.json`（后端写 `api_port`、前端写 `web_port`、桌面控制台写 `api_port_config` / `web_port_config`）
+- 所有文件工具都受会话工作区白名单约束，拒绝 `../` 与绝对路径越界。
+- 高风险工具（写文件、patch、删除、移动、shell、git、机器人运动）必须经审批。
+- `run_shell` 对灾难性命令做硬阻断（如 `rm -rf /`、磁盘格式化、关机）。
+- 产物 HTML 通过带沙箱 CSP 的接口预览，避免模型生成页面读取本地凭据。
+- 密钥只从环境变量或 `secrets_local.py` 读取，不入库、不返回明文。
+- 真实 Key 存放在 `api/configs/secrets_local.py`，已被 `.gitignore` 忽略；`git add --dry-run` 验证不会进入仓库。
+
+---
+
+## 5. 插件开发
+
+在 `api/plugins/` 下新建目录：
+
+```
+api/plugins/my-plugin/
+├── plugin.json
+├── plugin.py
+├── routes.py        # 可选
+└── skills/          # 可选
+    └── my-skill.md
+```
+
+`plugin.json`：
+
+```json
+{
+  "name": "my-plugin",
+  "title": "My Plugin",
+  "version": "1.0.0",
+  "description": "What this plugin adds",
+  "author": "you",
+  "requires": ["coding"],
+  "default_enabled": true,
+  "backend": "plugin.py",
+  "routes": "routes.py",
+  "contributes": {
+    "tools": ["my_tool"],
+    "agents": ["my_agent"],
+    "skills": true
+  },
+  "frontend": {
+    "nav": [{ "label": "My Plugin", "path": "/my-plugin", "icon": "puzzle" }],
+    "commands": [{ "id": "my-plugin.run", "title": "Run my plugin" }]
+  }
+}
+```
+
+`plugin.py`：
+
+```python
+from core.contracts import AgentSpec, ToolSpec
+
+
+async def my_tool(ctx, args):
+    return {"echo": args.get("text", "")}
+
+
+def register(ctx):
+    ctx.register_tool(
+        ToolSpec(
+            name="my_tool",
+            description="Echo text",
+            input_schema={
+                "type": "object",
+                "properties": {"text": {"type": "string"}},
+                "required": ["text"],
+            },
+        ),
+        my_tool,
+    )
+    ctx.register_agent(
+        AgentSpec(
+            name="my_agent",
+            title="My Agent",
+            instructions="You are ...",
+            tools=["my_tool"],
+            kind="dev",
+        )
+    )
+    ctx.add_skill_dir("skills")
+
+
+async def startup(ctx):
+    ...
+
+
+async def shutdown(ctx):
+    ...
+```
+
+插件能力：
+
+- `requires` 依赖排序；缺失依赖会被隔离并记录错误。
+- `startup / shutdown` 生命周期。
+- `ctx.events.subscribe(sink)` 订阅全局事件（编排器就是这样接收员工完成事件的）。
+- 启用/禁用状态持久化在 SQLite；启用/禁用后需重启 API 以加载/卸载路由。
+- 前端通过 `/api/plugins` 获取 `contributes` 与 `frontend` 元数据。
+
+### 为什么这样设计
+
+参考了 WordPress 的「小内核 + 可安装插件」：内核只负责会话、事件、策略、模型与工具协议；业务能力全部下沉为插件。  
+也吸收了 DeepSeek Harness 的「harness 本身可插拔」思路：具身 Agent 就是一个独立 harness 插件，可以继续安装小车、机械臂、人形机器人等不同 harness，而不改内核。
+
+---
+
+## 6. 自测结果
+
+在本次交付环境中已执行：
+
+```bash
+cd api
+python -m pytest -q
+# 28 passed, 1 warning
+
+cd ../web
+npm run build
+# ✓ built, 83 modules transformed
+```
+
+测试覆盖：
+
+- 健康检查、模型、技能、插件、审批列表
+- mock 模型完整会话（消息 → 事件 → done）
+- 编码会话写文件 → 工具事件 → artifact → 工作区树读取
+- 人工审批流程：pending → 批准 → 工具执行 → 文件落盘
+- 会话改名 / 隐藏 / 恢复 / 清空 / 彻底删除
+- 全局门禁与默认工作区设置、用量与 CSV 导出
+- 插件启用状态持久化
+- Orchestrator git worktree 端到端（创建 → 派发 → 完成 → 合并）
+- 工具级：沙箱越界、读写/编辑/patch/multi_edit、glob/grep/符号、shell、删除/移动
+- 危险 shell 命令硬阻断
+- 符号索引、repo map、pytest 解析、修复指引
+- 方案 HTML 与分镜 HTML 产物生成
+- 意图分流：寒暄、闲聊与通用问答（如「你好吗」「今天天气不错」「什么是依赖注入」）直接回复，不扫描工作区、不触发工具或写入（含真实 deepseek-flash 验证）
+- 首条消息自动生成会话标题（跟随界面语言；mock 覆盖回退与真实模型验证）
+- 会话独立路由：`/#/s/<session-id>` 深链、标签切换、地址栏编辑、刷新恢复与关闭回退
+
+另外用 Playwright + 本机 Chrome 对生产构建做了真实浏览器巡检：
+
+- 工作台 / 控制台 / 技能 / 插件 / 设置 / 用量 / 编排页全部加载
+- 顶部会话标签与独立路由：打开、切换、关闭、地址栏深链、刷新恢复
+- 默认标题自动摘要、右上角语言菜单（English / 简体中文切换）与无预设问题的空状态
+- 简体中文、繁體中文、English 三语言切换正常，刷新后语言保持
+- 语言入口覆盖工作台顶栏、侧栏底部、设置页三处
+- 侧栏 286px ↔ 76px 收起/展开正常，收起后会话列表隐藏且展开按钮可见
+- 右侧洞察面板默认收起，展开/收起状态持久化
+- 输入框 `Enter` 提交、`Shift + Enter` 换行正常，中文输入法组合态不会误提交
+- 深色 / 浅色主题正常
+- 430px 移动端布局、侧栏抽屉、右侧洞察抽屉正常
+- SSE 实时流：真实 DeepSeek 的思考过程与正文增量在 `done` 之前可见
+- 控制台无 JS 错误、无资源 404、无 WebSocket 404（前端实时流主通道已改为 SSE）
+
+> 本次已使用 AI 助理参考的 DeepSeek Key 完成真实在线验证：`deepseek-flash` 返回 `OK`，usage provider/model = `deepseek/deepseek-flash`。Key 仅存放在 `api/configs/secrets_local.py`，已被 `.gitignore` 忽略；仓库只提交 `secrets_example.py` 模板。Mock 回归测试仍保留，断网或无 Key 时可自动降级。
+
+---
+
+## 7. Harness 公平评测结果
+
+> 最新报告：[test/testing/index-2026-10-27.html](test/testing/index-2026-10-27.html)（2026-10-27，mimo-v2.6-flash）  
+> 历史报告：[test/testing/index-2026-10-25.html](test/testing/index-2026-10-25.html)（2026-10-25，deepseek-flash）
+
+### 7.1 MiMo 公平评测（最新）
+
+**方法**：5 个可自动判分的任务（基础自适应 1 + 定位 / 性能 / 长程 / 并发 4）× 3 个工具；统一 `mimo-v2.6-flash`、提示词、种子仓库与预算。运行结束后注入隐藏测试，并对 `tests/`、`pyproject.toml` 做 SHA-256 校验，篡改即 0 分。t1/d1/d3 使用 official-r1 交错批次，d4/d6 使用冻结代码后的独立复跑批次。
+
+| 排名 | 工具 | 综合（产品加权） | 正确率 | 速度 | 成本 | 工程纪律 | 等权 |
+|---|---|---|---|---|---|---|---|
+| 1 | **豪源 HaoYuan** | **98.8** | 100.0 | 94.4 | 96.9 | 100.0 | **98.3（第 1）** |
+| 2 | OpenCode | 90.5 | 100.0 | 67.8 | 53.5 | 100.0 | 84.3（第 2） |
+| 3 | Claude Code | 88.9 | 100.0 | 65.1 | 40.9 | 100.0 | 81.2（第 3） |
+
+综合 = 0.65 × 正确率 + 0.15 × 速度 + 0.10 × 成本 + 0.10 × 工程纪律；等权口径为 0.40 / 0.20 / 0.20 / 0.20。
+
+- 三者正确率均为 100%；豪源产品加权 **98.8**、等权 **98.3**，两种口径均为第一。
+- 分任务：豪源在 t1（63.8s）、d3（220.6s）、d4（469.6s）最快；OpenCode 拿下 d1（111.3s），Claude Code 拿下 d6（254.5s）。
+- 成本：5 题总成本豪源 **$3.33**、OpenCode $6.56、Claude Code $9.04；单任务成本分别为 $0.666 / $1.313 / $1.809。
+- 自适应强度：t1 简单题 63.8s / 11 次调用，未启动计划或子代理；d4 长程题通过预装相关源码减少重复探索（从 1200s 超时降到 469.6s）。
+- 关键修复：补齐 MiMo provider（此前 `resolve("mimo", ...)` 会静默回退 deepseek）、需求感知 repo map、复杂题 30KB context pack、进程树回收、严格 provider + 单次调用上限 + 同模型重试、简单题 lite 路由。
+- 局限：正式对照每题 1 轮；d4/d6 为独立复跑批次；模型延迟方差较大（Claude d3 先前 623s、本次 884s）；d5 区分度不足未入榜；自建任务，不能替代 SWE-bench 等公开基准。
+
+复现：
+
+```bash
+cd test/bench
+python harness_bench.py run --batch official-r1 --tools haoyuan,claude,opencode --tasks t1_multisite_bugfix,d1_needle_regress,d3_perf_cliff --resume
+python harness_bench.py run --batch official-r1 --tools haoyuan,claude,opencode --tasks d4_multilayer_feature,d6_concurrency_fix --resume
+python make_report_mimo_final.py
+```
+
+### 7.2 deepseek-flash 深度评测（历史）
+
+**方法**：8 个可自动判分的编码任务（5 基础 + 3 困难）× 每任务 3 轮 × 3 个工具；统一 deepseek-flash、提示词、种子仓库与预算；运行结束后注入隐藏测试，并对 `tests/`、`pyproject.toml` 做 SHA-256 校验，篡改即 0 分。
+
+| 排名 | 工具 | 综合得分（产品加权） | 正确率 | 典型速度 | 尾延迟 | 成本 | 等权得分 |
+|---|---|---|---|---|---|---|---|
+| 1 | **豪源 HaoYuan** | **96.6** | 100.0 | 100.0（中位 30.3s） | 67.6（P90 159.4s） | 82.2（$0.364） | 95.0（第 2） |
+| 2 | OpenCode | 95.1 | 100.0 | 67.6（中位 44.8s） | 100.0（P90 107.7s） | 100.0（$0.299） | 96.8（第 1） |
+| 3 | Claude Code | 90.7 | 100.0 | 70.6（中位 42.9s） | 90.7（P90 118.7s） | 55.4（$0.540） | 91.7（第 3） |
+
+综合 = 0.70 × 正确率 + 0.15 × 典型速度 + 0.05 × 尾延迟 + 0.10 × 成本；等权口径将后两项改为 0.10 / 0.10。
+
+- 三者正确率均为 100%，差异集中在速度、尾延迟与 token 成本；豪源产品加权第一，OpenCode 等权反超。
+- 豪源任务中位耗时 30.3s 最短，T1/T2/T3/H1 四题中位最快；24 次运行完整性 100%。OpenCode 尾延迟与单任务成本最优；Claude Code token 成本最高。
+- 短板：H2 版本迁移中位 159.4s（OpenCode 101.1s），H3 出现过 260s 长尾；后续继续压缩迁移审计与自测回合。
+- 局限：仅覆盖 deepseek-flash、每任务 3 轮，任务为自建，不能替代 SWE-bench 等公开基准。
+- 自迭代：评测期间修复 Windows 管道适配、空回复/未写入保护、迁移验收审计、轻量 git diff 审计、完成态顺序，并回滚一次「过度自测」的负优化。
+
+复现：
+
+```bash
+cd test/bench
+python harness_bench.py run --batch final-r1 --tools haoyuan,claude,opencode --tasks all
+python aggregate.py
+python make_report.py
+```
+
+---
+
+## 8. 与 AI 助理的功能对齐
+
+| 能力 | 豪源 | 说明 |
+|---|---|---|
+| 编码工具链 | ✅ | 定位、最小 patch、验证、修复环、子代理 |
+| 上下文压缩 / 长程 | ✅ | 轮内压缩、老化、硬预算、检查点、幂等续跑 |
+| 多会话并行 | ✅ | 并发闸、FIFO、后台任务与前端解耦 |
+| 权限门禁 / diff 审批 | ✅ | 审批卡片、预览、超时、并发槽让出 |
+| 技能库 | ✅ | front-matter + 规则/BM25 + UI 编辑 |
+| 方案计划书 | ✅ | 独立 HTML 产物 |
+| 视频分镜 | ✅ | HTML 分镜脚本；不包含 ffmpeg 成片渲染 |
+| AI 总管 | ✅ | 快照、告警、控制台对话、调度动作 |
+| 多智能体编排 | ✅ | 任务 DAG + git worktree + 合并指标 |
+| Token / 成本统计 | ✅ | 日聚合、按模型、CSV 导出 |
+| 插件机制 | ✅ 增强 | 清单、依赖、生命周期、工具/Agent/路由/技能/前端元数据 |
+| 飞书远程指挥 | ⏳ 未纳入本版 | 接口层已解耦，可作为插件补充 |
+| ASR / TTS / 视频渲染 | ⏳ 未纳入本版 | 当前聚焦 AI 编程主链路 |
+| 权威 Benchmark | ⏳ 公开基准未跑 | 已完成自建评测：5 任务 MiMo 公平评测 + 8 任务 deepseek 深度评测（见第 7 节）；SWE-bench 等公开基准未重跑 |
+
+---
+
+## 9. 后续路线（已预留架构）
+
+### 9.1 面向 16GB 显存本地训练的 Skills 库
+
+计划内置：
+
+- Qwen3.5-0.8B 的 SFT 数据构造与训练脚本
+- RL（偏好优化 / 可验证奖励）训练脚本
+- 显存友好配置：LoRA / QLoRA、梯度累积、小 batch、序列长度控制
+- 以「技能」为单位组织：数据模板、训练配置、评估用例、部署说明
+
+豪源当前的 Skill 机制已经是文件级、可版本化的，后续可直接把训练方法论文档作为 Skill 注入 Agent。
+
+### 9.2 插件化具身 Harness
+
+`plugins/embodied` 已演示：
+
+- 机器人状态 / 传感器 / 移动 / 转向 / 急停工具
+- 高风险动作审批
+- HTTP 演示桥
+
+后续可以在不改内核的前提下增加：
+
+- `embodied-ros2`（ROS2 话题 / 服务）
+- `embodied-serial`（Arduino / ESP32）
+- `embodied-smolvla`（视觉语言动作模型）
+- 小车、机械臂、人形机器人各自的 harness 插件
+
+---
+
+## 10. API 速览
+
+统一前缀 `/api`，响应格式 `{ code, data, message }`。
+
+| 分组 | 主要端点 |
+|---|---|
+| 系统 | `GET /health`、`GET /info`、`GET /models`、`GET /agents`、`GET /tools` |
+| 会话 | `POST /sessions`、`GET /sessions`、`GET /sessions/{id}`、`PATCH /sessions/{id}` |
+| 消息 | `POST /sessions/{id}/messages`、`GET /sessions/{id}/messages` |
+| 事件 | `GET /sessions/{id}/events?after_id=`、`GET /sessions/{id}/stream`、`WS /ws` |
+| 审批 | `GET /approvals`、`POST /approvals/{id}/resolve`、`POST /sessions/{id}/confirm` |
+| 技能 | `GET/POST /skills`、`GET/PUT/DELETE /skills/{name}` |
+| 文件 | `GET /workspace/tree`、`GET /workspace/file`、`GET /workspace/changes`、`GET /workspace/diff` |
+| 设置 | `GET/PUT /settings`、`PUT /settings/gate`、`PUT /settings/workspace` |
+| 用量 | `GET /usage/today`、`GET /usage/daily`、`GET /usage/by-model`、`GET /usage/export.csv` |
+| 插件 | `GET /plugins`、`POST /plugins/{name}/toggle` |
+| 总管 | `GET /supervisor/overview`、`GET /supervisor/console`、`POST /supervisor/act`、`POST /supervisor/chat` |
+| 编排 | `POST /orchestrations`、`GET /orchestrations`、`GET /orchestrations/{id}` |
+
+交互式文档：<http://127.0.0.1:8030/docs>（端口顺延后以后端日志或 `api/data/runtime.json` 为准）
+
+---
+
+## 11. 开发与测试
+
+```bash
+cd api
+python -m pytest -q
+
+cd ../web
+npm run build
+npm run dev        # 开发模式，/api 与 /ws 自动代理到后端实际端口
+```
+
+建议在 `AGENTS.md` 中记录团队的 lint / test / build 命令，豪源会自动把项目记忆注入上下文。
+
+---
+
+## License
+
+Private project. All rights reserved.