AutoMind 使用手册

01产品简介

普通 AI 聊天工具只能"说"；AutoMind 除了聊天，还能真正在你的电脑上执行操作： 创建文件、修改代码、运行命令、抓取网页、生成报告——并且做每件事之前先自己规划步骤， 做完自己检查结果，出错自己纠正重试。

它能帮你做什么？

02快速上手（零基础五分钟）

三种安装方式

三种启动方式

试一试：第一个任务

# 模式切到「⚙️ 工作」，输入框输入：
在当前目录创建 hello.txt，内容为 Hello AutoMind

执行时：聊天区出现「⚙️ 执行过程」实时轨迹（计划生成 → 逐步执行 → 完成）， 右侧「📋 执行计划」同步刷新每步状态（○ 待执行 → ◐ 执行中 → ✓ 完成）， 完成后项目目录里 hello.txt 真实存在。

03界面总览

键盘快捷键v1.4 起为完整快捷键系统

macOS 上把下表的 Ctrl 读作 ⌘。应用内按 ? 可随时调出这张表（侧栏「⚙ 设置 → ⌨ 键盘快捷键」也能打开）， 内容与实际生效的按键同源，不会出现"文档写了却按不动"。

界面偏好（字号 / 通知 / 动效）v1.4 新增

在「⚙ 设置 → ⚙ 通用设置 → 🎨 界面偏好」里，三项都是本机生效、立即生效、自动记住， 不改变任何功能，也不会同步到别的机器。

04五种交互模式深度解读

模式决定了 AutoMind「怎么思考、要不要动手、如何收尾」。选对模式，事半功倍。

模式选择决策

05工具审批与安全体系

每次工具调用都被安全体系拦截评估——你可以精确控制"它能做什么"。

三种审批模式（顶部下拉切换）

权限分级

事后追责：侧边栏「🛡️ 安全审计」记录每次调用的时间、工具、参数、决策、风险分与原因， 并汇总放行 / 询问 / 拒绝 / 高危次数。

🏛 运行底座治理账本 v1.11.19 新增 · 社区版可用

内存审计之外，Agent 的每次治理决策（放行 / 拒绝 / 批准 / 拒绝批准 / 无人值守放行与拦截）与 每次工具执行都会写入持久化账本：<数据目录>/governance/ledger-*.jsonl （8MB 或跨天轮转、最多 10 个文件；state.json 保证序号与链跨重启连续）。

06模型配置详解

支持的提供商（左下角 ⚙ 设置 → 🔑 API Keys）

省钱与提效：各模式专用模型

设置菜单的「🖥 模型配置」面板可为五种模式分别指定不同模型—— 对话用便宜快的 deepseek-chat，编程用强力的 claude-sonnet， 实现成本 / 能力的精准分配。未指定的模式沿用全局默认。

通用设置（左下角 ⚙ 设置 → 通用设置）

07工具面板：工具 / 技能 / MCP / 插件

侧边栏「🔧 工具面板」四个分段，对应 AutoMind 的四类可扩展能力。

🔧 工具 —— Agent 的"手"

✨ 技能 —— 预制的"专家流程"

导入自定义技能：「📁 加载目录」批量导入 SKILL.md 技能包（YAML 头 + 指令正文，无代码）； 「📄 导入 .py」导入继承 AbstractSkill 的 Python 技能（模板见 examples/03-skill-development/）； 「⬇️ 一键导入桌面 skills 文件夹」直接吸收技能库。

🔌 MCP —— 连接外部工具生态

MCP（Model Context Protocol）是开放协议，接入后外部服务的工具自动出现在工具列表供 Agent 调用（文件系统、数据库、搜索、地图…）。支持单个添加（stdio 本地命令 / sse URL） 或直接粘贴 Claude Desktop 格式的 {"mcpServers": {...}} 批量导入。需先 pip install mcp。

⭐ 官方适配（一键添加）：内置 GitHub、PostgreSQL、MySQL、Slack、飞书、钉钉、 Playwright 浏览器 7 个预设，点「添加」即写入配置并连接；需密钥的服务会提示在系统 环境变量里设置（如 GITHUB_PERSONAL_ACCESS_TOKEN、DATABASE_URL）。

🧩 插件 —— 生命周期钩子扩展

插件在任务开始 / 结束 / 解析后 / 计划后 / 出错等时机自动执行你的逻辑 （记日志、发通知、审计上报），不改动主程序。面板中「加载 / 卸载」即时生效。

内置 4 个插件（随包分发、默认自动加载，面板以「内置 / 自定义」区分）： cost_tracker（Token/耗时入账 CSV）、pii_guard（敏感信息检测告警）、 task_notify（任务完成通知，可选 AUTOMIND_NOTIFY_WEBHOOK）、 hello_hooks（示例模板）。

# 插件目录结构
~/.automind/plugins/task-timer/
├── plugin.json     # {"name":"task-timer","version":"1.0.0","description":"…"}
└── hooks.py        # def get_hooks() -> AgentHooks

08高级功能

🔄 自主任务闭环（v0.3 新增，默认开启）

工作 / 编程模式任务完成后自动执行"质检流水线"，不合格自动返工—— 把"AI 说做完了"变成"验证过真的做完了"。

8.27 📄 Markdown 文档视图与对话排版v1.11.14 新增

Agent 交付 / 产出的 .md 文件以前点开是纯文本源码（表格糊成竖线、标题全是井号）。 v1.11.14 起以📄 文档视图打开：居中阅读列、标题层级、表格与代码块按排版显示，可随时切回源码。

10.7 🤖 IM 机器人 Markdown 排版v1.11.14 新增

飞书 / 钉钉 / 企业微信 / 公众号对 Markdown 的支持差异很大。v1.11.14 起回复发送前先经 automind/bots/md_format.py 适配：能渲染的保留，不能渲染的降级成可读文本，但绝不丢内容。

⭐ 应用内一键升级（.ampkg）v1.11.14 起

设置菜单 →「⭐ 升级专业版 / 企业版」，或点左上角版本徽标。v1.11.14 起推荐用发行方给的 .ampkg（扩展包 wheel + 许可证 + 清单打成一个文件）；v1.11.15 起包内扩展包带 v3 许可证 / 机器绑定 / CRL / 周期复检，v1.11.16 起还支持协同 / 循环断点续跑（旧扩展包不支持 resume= 参数，协同 / 循环续跑会失败）；v1.11.17 起商业特性管理接口 （语义缓存 / 智能路由 / 成本仪表盘 / 知识库进阶）随扩展包挂载修复，已激活却被提示"未开通"的问题不再出现：

8.28 🧠 输入框模型选择器与自动路由v1.11.15 新增

输入框旁新增 🧠 模型选择器，发消息前直接换模型；专业版 / 企业版还能交给「自动路由」按任务复杂度选档。

8.13 👥 团队协作工作台v1.11.15 升级

侧边栏「👥 团队」从三列任务看板升级为完整的团队工作台（同一服务器部署 = 同一团队）：

8.7.1 💬 工作区会话管理（分组 / 排序 / 筛选 / 搜索）v1.11.17 新增

每个工作区有自己的一组会话。会话一多，平铺列表就不够用了 —— v1.11.17 补上完整的检索与管理能力：

8.18 🧭 智能路由与成本v1.11.15 界面重做 · v1.11.17 路由挂载修复

侧边栏「🧭 路由与成本」整页重做（专业版起），覆盖语义缓存、模型路由与成本分析：

8.29 🪙 任务预算连续性与多模式续跑v1.11.16 新增

v1.11.16 的目标：不再出现"Token 用尽，任务没跑完就停住"。预算变成"可续的窗口"， 协同 / 循环 / 子智能体耗尽后可以接着跑，而不是从零重来。

8.30 🛡 执行治理参数生效时机v1.11.16 新增

「设置 → 🛡 执行治理」共 26 个参数（5 个布尔开关 + 4 个布尔附加项 + 15 个数值 + 2 个策略）。 v1.11.16 逐项审计后每个参数都真正生效，并明确标注生效时机。

🔀 工作流自动化强化v1.11.16 新增

工作流 YAML 新增五种能力，全部可选、默认等价旧行为，旧工作流无需修改：

8.31 🏛 运行底座治理与验收门禁v1.11.19 新增

回答两个问题：Agent 运行时到底执行了什么、谁批准的？ 以及 发布前怎么证明没跑坏、交付后怎么保证没留垃圾？

8.31.1 审计账本（可持久 / 可校验 / 可解释）

记忆里的审批记录会在重启后消失，也证明不了"这条高危操作当时被拒绝过"。v1.11.19 把治理决策与 工具执行写进按序哈希链 JSONL 账本（位置 / 轮转 / 字段 / 脱敏 / fail-open 见第 5 章 5.3）， 重启不丢、可一键校验防篡改。

8.31.2 分派级治理闸门（堵住审批旁路）

8.31.3 治理中心（接口 + 界面）

与 /api/audit 同级管理员守卫（本机回环或 X-Admin-Token，失败关闭）； 账本读取不阻塞事件循环，模块缺失 503、读取故障 500 + 可操作错误。界面入口在「🛡️ 安全审计」页顶部。

8.31.4 发布验收门禁（scripts/acceptance.py）

# 日常 / 发布前 / CI 静态 / 完整报告
python scripts/acceptance.py --profile fast
python scripts/acceptance.py --profile full
python scripts/acceptance.py --profile static
python scripts/acceptance.py --profile full --json acceptance.json --report acceptance.md

• 六类门禁：version（六处版本号与手册同步）· lint（ruff）· tests（按档位选子集 / 全量）· pro（商业扩展包测试）· web（tsc --noEmit + 前端产物完整性）· hygiene（敏感泄漏扫描、git diff --check、残留测试文件扫描）。
• 子进程带 timeout；JSON / Markdown 报告；有 fail 退出码 1；失败给可复现命令。
• 社区版强制模式：AUTOMIND_FORCE_COMMUNITY=1（只降不升）跳过商业扩展加载， 本机装了有效许可证也能稳定复现社区版结论；验收脚本自动注入该变量与临时数据目录， 不动用户 home 下的许可证文件。
• 残留清理：集中白名单 + 默认只告警 / dry-run；--clean 只删"未被 git 跟踪的 白名单临时产物"并逐条打印，绝不误伤源码 / 已跟踪文件。

8.32 ✨ 问题优化 · 🪟 静默运行 · 🧱 长任务韧性v1.11.20 新增

本节回答三类高频体验问题：问题没说清怎么让 AI 一次听懂？桌面版为什么总闪空终端窗口？ 长任务为什么会断、会卡、会跑飞？

8.32.1 输入框「✨ 优化问题」

• 什么时候用：问题很短（如「帮我弄一下」「看看这个」「优化一下」）、缺少对象 / 约束 / 期望产出， 或你感觉 AI 可能理解偏了时。输入框工具栏「✨ 优化」按钮会在这类模糊输入下轻微高亮（不会自动改写）。
• 做了什么：把原问题改写成 AI 一次就能正确理解的执行请求： 目标（保留原话与意图）→ 先复述理解与拟采取步骤 → 列出必需信息（输入文件 / 目录、环境、期望格式、 验收标准；能自行查证的就查证，无法确定时一次最多问 3 个问题，不猜测）→ 明确产出与验证方式 → 不确定处标注「假设：…」，不编造事实 / 路径 / 数据。
• 先确认再采用：弹窗并排展示原问题与可编辑的优化结果、改动点、待确认信息；点 「采用并填入输入框」才替换正文，也可「再优化一次」或取消。已足够清楚的问题会直接提示“可直接发送”， 不硬加模板。
• 模型改写 + 本地兜底：接口 POST /api/prompt/optimize 用当前配置的模型改写 （限时 30 秒、最多 2 个并发、不消耗每日任务额度、不落盘用户文本）；模型未配置 / 超时 / 返回非 JSON 时 自动改用本地规则模板，按钮始终可用。
• 安全边界：优化器只做澄清与结构化，不回答问题、不执行任何工具、不改变附件 / @ 引用 / 模式设置； 采用后仍由你按 Enter 发送。

8.32.2 桌面版静默运行（不再闪空终端窗口）

• 现象与根因：桌面版是无控制台的 GUI 进程。Windows 上任何未带 CREATE_NO_WINDOW 的 console 子进程都会新建一个空控制台窗口；环境探测、terminal / pwsh、 后台命令、沙箱、通知、ffmpeg、pip install、测试进程、更新器与 MCP stdio 服务器都会 spawn 子进程，于是表现为“不定期闪窗”。
• 现在的做法：新增 automind/core/proc.py 统一静默层 —— 所有运行时 spawn 点加 CREATE_NO_WINDOW；GUI 进程下还安装幂等的 Popen 补丁，连第三方库（如 MCP SDK） 启动的子进程也不会新建窗口。保留调用方原有的 CREATE_NEW_PROCESS_GROUP 等标志， 不设 SW_HIDE，所以浏览器 / 编辑器等 GUI 程序照常显示。
• 可关闭：AUTOMIND_SILENT_SUBPROCESS=0（关闭）、=1（强制开启）； 默认在无控制台进程 / 桌面版自动开启。
• 怎么验证：桌面版启动并跑一条命令，任务栏不应出现新的空终端窗口；命令行终端里启动时行为不变 （子进程继承当前控制台）。

8.32.3 长任务断线保活（默认开启，120 秒）

• 断线不丢任务：任务执行中浏览器 WS 断开（Wi-Fi 抖动 / 休眠唤醒 / 反代掐流 / 页面刷新）后， 任务默认继续在服务端跑 120 秒；重连后自动接管运行中状态，或回放已完成结果（含完整回答）， 不再立刻落“失败卡片”。
• 可调：AUTOMIND_RUN_DETACH_GRACE_S（默认 120，0 = 关闭保活回到旧行为）、 AUTOMIND_RUN_RESULT_TTL_S（默认 600，结束后结果保留时长）、 AUTOMIND_WS_SEND_TIMEOUT_S（默认 5，单条事件推送超时）。
• 边界：只有新前端在 run 里声明 reattach: true 才启用；旧页面 / 脚本 仍按旧语义取消。断线时若正在等待人工审批，该连接上的待决审批仍按拒绝处理（fail-closed）， 这是安全语义，不随保活改变。
• 同一会话只允许一个活跃任务：两个标签页同时发任务时，第二个会收到明确提示，避免互相覆盖 会话克隆。

8.32.4 工具执行可见、慢客户端不阻塞

• 工具调用开始即发「🛠 调用 X…」；执行超过 5 秒每 5 秒刷新「已运行 N 秒」—— 长命令 / 大文件 / 浏览器操作期间能明确区分“在跑”与“挂了”。
• 服务端向界面推事件带 5 秒超时：某个标签页很慢 / 假死时只丢那一条非终态事件，不会把正在跑的工具 或模型调用拖住。
• 工具超时让位：外层单步超时给工具内部超时留 10% 余量（默认 300s→330s）； terminal / pwsh 内部超时先返回，它自己给出的“等待了多久、输出已丢弃、 改用 background=true / 加大 timeout”回执能真正送到模型，而不是被外层取消后只剩一句笼统失败。

8.32.5 防「无限验证」跑飞

• 真实依据：本机任务历史里出现过一次 150/50 步、7.7M token、25 分钟后仍以 max_iterations 失败 的记录，轨迹里有大量“读同一个文件 / 反复核对”的成功但无进展动作。
• 读目标守卫：同一目标（file_read 的 path、file_search、 web_fetch、web_search、http_request）累计读取， 第 6 次先提示、第 7 次起拦截（默认上限 8，本地判定零 token）；不同 offset/limit 的重复整文件读取也会被识别。被拦的动作计入无进展，连续无成功即停止续步。
• 续步上限 2→1：ReAct 步数用完后最多再续 1 个窗口（最坏 100 步，此前 150 步）；续步会推送 react_iterations_extended 事件，界面可看到“已续加步数”。到上限仍走既有 「部分交付清单 + 断点续跑」，不会把已做的事丢掉。
• 建议：长任务尽量给明确验收标准；遇到反复核对同一文件，可直接补充要求“基于已有内容收尾”， 或从断点续跑只做剩余部分。

8.33 🧯 修复轮预算 · 失败原因 · 省 tokenv1.11.21 新增

本节回答三个问题：验收没过之后，系统会不会为“返工”再烧掉一整个任务？任务失败时到底停在哪一步？ 为什么这版更省 token？

8.33.1 修复轮不再是“第二个完整任务”

• 旧行为（真实数据）：自主闭环在“验收未过”后会自动修复，但修复轮此前沿用主任务的 max_iterations（默认 50 步）与续步规则 —— 本机历史里出现过 150/50 步、7.7M token、25 分钟仍以 max_iterations 失败的记录，等于把“完成计划 + 返工” 跑成了第二个完整任务。
• 新行为：新增「设置 → 🛡 执行治理 → auto_verify_fix_max_iterations」 （默认 1，0 = 关闭自动修复）。每个修复轮最多走这么多步；修复轮次数仍由 auto_verify_max_rounds 控制。
• 修复轮不续窗、只继承剩余 deadline：修复轮只能花当前 Token 窗口的剩余预算，用尽就收尾； 不会开新窗口、也不会顺延任务总时长。
• 推荐设置：默认 1 适合大多数任务（小修小补）；需要“返工重做”时先提高验收标准或把剩余目标 拆成新任务，而不是把修复轮步数调大（步数越大越容易反复读 / 反复核对，反而更慢更贵）。

8.33.2 什么情况会“部分交付”而不是死磕

当主任务因为下列原因停下时，系统判定为部分交付，直接跳过 LLM 审查 / 验收 / 修复轮， 只输出“已完成工作保留，可续跑”的摘要：

简单任务（纯问答式产出、只读工具且无失败）同样跳过昂贵的审查 / 验收 / 修复轮。 跳过的不是“交付”：已完成的文件改动 / 产出都保留；需要接着做时按 8.10 从断点续跑。

8.33.3 失败原因与调用次数在哪里看

• 历史卡片：任务记录新增 stop_reason（中文徽标：步数上限 / 预算耗尽 / 无进展 / 模型不可达 / 部分交付…）、resumable（⏸ 可续跑）、llm_calls（N 次调用）； 详情弹窗可查看并复制 error。
• 失败气泡：错误正文上方显示停止原因、⏸ 已保存可续跑断点、 N 次 LLM 调用；有断点时保留「检查现状后接着做」按钮（它只让 AI 看现状给出下一步建议， 不是断点续跑，见 8.10）。
• 兼容旧记录：旧任务没有这些字段时界面不显示，不会报错。

8.33.4 省 Token 的三个取舍

1. 复用验收结论：闭环里已经有 review / verify 结论时，直接据此生成质量报告，不再重复评估、 也不额外花一次 LLM 做反思；只有“没有结论 + 非简单 / 非部分交付”才走完整质量评估与反思。
2. 干净成功不再反思：质量评估一次通过且无 issue 时跳过反思。
3. 前缀缓存不打掉：消息顺序保持 system → 工具目录 → 环境 → 记忆 → task 稳定不变， 修复轮不重写已有 system 消息 —— 返工复用同一段缓存前缀，命中率不因“返工”下降。

8.33.5 回归保障

tests/planning/test_long_task_regressions.py 用脚本化 LLM（不依赖真实模型）锁住两类跑飞形态： 计划完成但验收未过时，修复轮 ≤1 轮 / ≤1 步且总调用有上限；ReAct 反复读同一路径时守卫触发、调用有上限、 最终部分交付而不是无限循环。另有 tests/planning/test_autonomy_budget.py（部分交付短路 / 不续窗 / 简单任务跳过 / 验收结论复用）与 tests/core/test_agent_result_fields.py（字段与落库映射）。

8.34 🤝 多智能体工程协同v1.11.22 新增

本节回答：协同模式现在到底是谁在干活、权限和写冲突怎么管、预算与验收怎么算、 怎么用评测脚本对比单 Agent / 协同 / 子任务。

8.34.1 能力：从“多角色写文本”到“能动手的工程团队”

纯文本任务（无 coder、无写范围、任务不含代码 / 文件 / 命令 / 测试 / 构建关键词）仍走旧文本流水线， 保留旧的质量 / 成本表现 —— 不为“写一份方案”启动整套工程设备。

8.34.2 权限与安全（和单 Agent 同一套）

• 角色调用仍是真实工具调用：审批模式、风险分级、路径防护、分派级治理闸门全部照旧； 多智能体没有“特权”，写 / 执行工具在非「全批准」模式下同样可能被拦。
• 角色工具按角色收紧：coder = 写 / 执行 + 读；writer = 写文件 / 读；其他角色只读 SAFE； 写角色若没有任何可用写工具会直接报错（不会静默“假装写了”）。
• 审查者（reviewer）是只读的：只复核，不改文件。

8.34.3 共享工作区与写冲突（为什么有时“看起来没并行”）

• 所有角色共享你的项目目录 —— 它们改的是真实文件。运行前建议 git 提交或用工作区隔离副本。
• 写角色用 write_paths 声明写范围：不同路径可并行，范围重叠自动串行（同一时刻只有一把锁在写）。
• 没声明写范围的写角色会拿“整片工作区”独占锁 —— 安全优先，但会明显降低并行度。
• 节点失败时，依赖它的节点直接标 skipped（不跑）；独立节点继续。最终输出如实列出哪些没跑。

8.34.4 预算与验收（失败不会伪装成成功）

• 角色预算：multi_agent_role_max_steps（默认 12 步）、 multi_agent_role_max_tokens（默认 120000）、 multi_agent_role_timeout_seconds（默认 300s），且角色不自动续窗； 并行数 multi_agent_max_parallel（默认 2）。
• 回炉：multi_agent_max_rework（默认 1）—— reviewer 不通过最多重跑一次； 审查设施不可用（available=False）只记“审查不可用”，不回炉也不判失败。
• 验证：multi_agent_verify（默认 True）收尾跑项目测试 + 语义验收； done 口径：测试通过 / 没有测试 / 测试设施不可用，且（语义验收 done 或验收设施不可用； multi_agent_verify=False 时不跑语义验收、不据此判失败）。没有任何角色成功时验证标记 skipped（不当作验证通过）。失败最多再修 1 轮，仍失败 → success=False, stop_reason=verification_failed。
• “验收未执行”不是“通过”：界面显示“验收未执行”时，只代表这次没测到，别当成已验证。
• 预算耗尽：整轮任务照旧写可续跑检查点（resumable=True），从断点续跑只补剩余角色。

8.34.5 怎么读协同结果

• 计划 / 依赖：卡片显示 DAG 与「依赖 s1,s2」；看到两个角色写同一路径说明会串行。
• 每角色数据：步数 / LLM 调用 / Token 都在角色行上；rework 标记表示回炉过。
• 验证摘要：卡片底部“测试通过 / 验收通过 / 审查有意见 / 验收未执行”，只有真实 verification 才显示。
• 失败 / 跳过：skip 图标表示依赖失败未执行；fail 是角色本身失败 —— 两者不要混。
• 旧任务记录 / 旧后端（只有 index 没有 id）按旧布局展示，新字段缺失不显示。

8.34.6 用评测脚本对比三种模式（可选）

# 先看矩阵（默认 dry-run，不调用模型、不需要 Key）
python scripts/collab_benchmark.py --dry-run

# 真跑（会消耗 Token；先配好模型 Key）
python scripts/collab_benchmark.py --live --provider deepseek --model deepseek-chat
# 只跑某些任务 / 模式
python scripts/collab_benchmark.py --live --task codegen_fizzbuzz,bugfix_calc --mode single,multi

• 三种模式：single = 单 Agent 工作模式；multi = 工程协同（需专业版）； subagent = 受限子任务。
• 指标：success / duration_ms / tokens / llm_calls / steps / verification_passed / rework_count / human_interventions；另有 benchmark 侧产物检查 artifacts_ok 与人工回填列 manual_rework。
• 结果写 .automind/collab_benchmark/（gitignore）：JSON + CSV；不提交真实结果 / API Key。
• status=unavailable（如未激活专业版）与 error 不计入成功率分母； verification_passed=None 表示该模式没有验证环节 / 未测到，不是失败。
• 仓库没有预置任何基准数字；要结论请本地自己跑（方法与口径见 docs/COLLABORATION.md）。

8.35 🧪 审计测评与压力测试v1.11.23 新增

本节回答：v1.11.23 到底审计了什么、用什么方法保证结论可信、结果在哪里看、日常使用有什么变化。

8.35.1 审计了什么（四个面）

本轮不是模型质量评测（那看 docs/EVAL.md 与 scripts/collab_benchmark.py）， 也不改产品功能 —— 除非审计确认了真实缺陷，才做最小修复并补回归测试。

8.35.2 方法：零真实模型、断言数据不变量

• 全部 fake / scripted 执行器 + 进程内 WS fixture：不消耗 Token、不需要 API Key、不联网；
• 线程 + 协程混合并发，Barrier 同步起跑放大竞争窗口；
• 断言不看“没抛异常”，而看数据不变量：任务条数、认领归属、running 计数归零、锁是否全部释放、 事件是否串台；
• 先测后修：先写能复现的压力用例，确认真实缺陷再改代码（最小改动、保留旧 API / 测试）；
• 未复现的领域如实写“未复现” —— “未发现”不等于“无风险”。

8.35.3 结果在哪里看

• 完整报告：docs/AUDIT_v1.11.23.md（范围 / 方法论 / 测试矩阵 / 结果 / 发现与修复 / 边界 / 复跑命令）；
• 本轮实测：89 个审计用例全部通过（A1 16 / A2 29 / A3 30 / A4 14），P0 = 0；团队看板、子智能体、 WS/在线共三组 P1 缺陷、8 处修复均有回归；A2 工程协同未发现需修改 engineering.py 的缺陷；
• 已修复的清单与规模数字见 docs/AUDIT_v1.11.23.md 与 CHANGELOG.md v1.11.23 第三节；
• 复跑命令（全部不需要真实 Key）：

# A1 团队任务看板并发与流程
python -m pytest tests/audit/test_team_flow.py -q

# A2 多智能体工程协同压力（需商业扩展包源码）
$env:PYTHONPATH='pro'; python -m pytest pro/tests/test_engineering_stress.py -q

# A3 子智能体委派压力与生命周期
python -m pytest tests/planning/test_subagent_stress_audit.py -q

# A4 WebSocket / 团队在线与并发
python -m pytest tests/server/test_ws_stress_audit.py -q

8.35.4 边界（诚实声明）

• 不覆盖真机网络 / 弱网 / 浏览器休眠（WS 压测是进程内 fixture）；真机验证仍靠 CI 与安装包验收；
• 不覆盖跨进程真并发（团队看板若多进程同时写 SQLite，进程内锁无法覆盖；复现到会单独记录）；
• 不覆盖长时间稳定性浸泡（>1h）与吞吐量基准；压力规模按“本地秒级到分钟级可重复”选取；
• 审计结论只对当轮代码与用例规模成立，不构成“未来永远安全”的保证。

8.35.5 对日常使用有什么影响

• 一般没有可感知变化：审计轮默认不改功能；若修复了真实并发缺陷，行为会更确定 （例如并发认领同一任务会明确成功 / 拒绝，而不是偶尔静默覆盖）；
• 如遇团队看板 / 协同 / 子智能体异常，可把 docs/AUDIT_v1.11.23.md 的复跑命令与对应场景 一起反馈。

8.36 🧪 真实能力测评与版本隔离v1.11.24 新增

本节回答：怎么用可复跑的测评判断“真实能力”、社区版 / 专业版 / 企业版的差异怎么测、 Web 界面里为什么以前跑不了测评、现在怎么跑、实测结果在哪里看。

8.36.1 核心综合测评套件（comprehensive.yml）

• 全部任务自包含：不联网、不读写仓库、单任务 300 秒上限；
• 只用现有断言类型（contains / not_contains / regex / file_exists / tool_called / max_seconds / max_tokens），不引入新 runner 语义；
• assertion_probe 的用意：如果它“通过”了，说明断言根本没被判定 —— 那是测评框架最严重的 失效形态；
• 跑法：python -m automind.eval run automind/eval/suites/comprehensive.yml --dry-run （看清单，不需 Key）；去掉 --dry-run 才是真实调用模型（计费）。

8.36.2 版本隔离测评（社区 / 专业 / 企业）

scripts/edition_benchmark.py —— 默认 dry-run（不联网、不启动 server，只打印 / 校验矩阵）； --live 才真实执行：

1. 起三个隔离 server：community（18765）/ pro（18766）/ enterprise（18767），各自独立 AUTOMIND_DATA_DIR、HOME、项目目录；
2. community 注入 AUTOMIND_FORCE_COMMUNITY=1 且不加载扩展；pro / ent 安装 staging Pro wheel + 临时许可证（结束后清理进程与许可证）；
3. 通过 /api/config 设置已接入模型（Key 不打印、不落报告），/api/eval/run 跑 comprehensive 3 轮，并调用 scripts/collab_benchmark.py --live 跑协作矩阵 （community 只 single；pro / ent 为 single + multi + subagent）；
4. 保存原始报告与隔离矩阵供复核；--report-only 跳过执行、只重算报告。

实测隔离矩阵（v1.11.24b，isolation_matrix.json，27 项商业 feature × 3 版本）：

结论：feature 门控、扩展安装与许可证步骤完全符合预期，说明三版本是真正隔离运行、 不是共用同一份环境；完整矩阵见 docs/benchmark/v1.11.24/isolation_matrix.json。

scripts/benchmark_report.py：校验 6 任务 × 3 版本 × 3 重复 与协作 cell 完整性， 缺失即失败（不允许“少跑几个也当结果”）；汇总 JSON / CSV / Markdown；对 Key、绝对路径、许可证信息 脱敏；只汇总实测数据，不补数、不估数。

8.36.3 Web 界面跑测评（取当前模型）

• 以前的问题：工作台已接入 deepseek-flash，但 /api/eval 的 dry-run target 仍按默认 openai/gpt-4o 判断 → 报“未配置”，看起来像测评不可用。
• 现在：/api/eval/run 未显式指定 provider / model 时，取当前已接入模型的 provider / model / api_base，并从当前 Agent 或已保存的 API Keys 取 Key；没有可用 Key 返回 409 （明确是“配置问题”，不是“模型失败”）；响应只报告来源，不返回 Key；CLI 默认行为不变。
• 在 Web「📊 评测」入口选套件即可跑；无人值守场景注意审批模式（评测默认 approve_all， 无人值守脚本应显式指定，见 5.1）。

8.36.4 实测结果在哪里看（v1.11.24b，2026-10-31）

核心综合评测（6 任务 × 3 版本 × 3 轮，共 54 cell）：三版本均 100%（18/18）； 耗时 / Token / 估算成本：社区 331.38s / 576,476 / $0.391097，专业 358.30s / 608,693 / $0.410784， 企业 265.59s / 545,589 / $0.354959；反向探针三版本各 3/3 passed； 数据完整性 82/82、validation.ok=true。

协作矩阵（每 task × mode 仅 1 次，n=1，不构成统计显著结论）：

• 失败案例如实保留：pro multi 0/4、enterprise multi 1/4 （含 multi_file_pkg 产物缺失）、codegen/bugfix 的 multi 验收失败、 community single 仅 1/4（但产物文件已生成）；逐条原因见基准报告 §9， 不得删除或弱化；
• 完整报告：docs/BENCHMARK_v1.11.24.md；脱敏数据（含 isolation_matrix.json、逐 cell 矩阵、SHA256SUMS.txt）： docs/benchmark/v1.11.24/；
• 本手册与 CHANGELOG 不预设“哪个版本更强”的结论：协作 n=1、单模型、单机， 不构成统计显著结论；
• 想自己复现：先 --dry-run 校验环境与矩阵，再在配好模型 Key 的机器上 --live（会产生真实 Token 费用）。

8.36.5 边界（诚实声明）

• 真实模型 / 真实计费：--live 会调用你配置的模型并消耗 Token； 不要接进 CI / 定时任务；
• 三版本隔离只保证“进程与数据目录隔离”：不等于安全沙箱；测试用临时许可证，报告已脱敏；
• 测评结果依赖模型 / 网络 / 机器：不同模型结果不可横比；本轮评测 3 轮、 协作每 cell 仅 1 次（n=1），不构成统计显著结论；
• 协作矩阵存在真实失败（pro multi 0/4、enterprise multi 1/4 等）， 发布 / 引用时必须如实披露；
• 不是安全审计：并发 / 生命周期审计见 8.35；能力结论以实测报告为准， 未实测项（环境精确版本等）不补数字。

8.37 🤝 多智能体协同修复与交付后续跑提示v1.11.25 新增

本节说明 v1.11.25 的两项修复与一项沿用：多智能体协同执行链路修复 （已在 PRO / ENTERPRISE 两个独立完整矩阵实测）、任务已交付后不再提示续跑， 以及沿用 v1.11.24 的 Web 评测取当前模型 / Key。 所有实测数字来自真实运行（模型 deepseek/deepseek-flash、单机、每组合 n=1）， 不构成统计显著结论，也不做版本或模型排名。

8.37.1 多智能体协同修复（PRO / ENTERPRISE 完整矩阵均 4/4）

修复点（7 项）：

1. 产物硬断言只认任务明确要求的路径：只对任务 expect_files（明确要求产物）做硬失败； 回答里顺带声称的 requirements.txt / pytest.ini 等降为 warning。
2. 最终交付只整合 coder / writer 产出：排除 planner / reviewer 过程文本，并遵守任务长度约束 （如 analysis_summary 的 300 字上限）。
3. 证据优先验证：测试 / 产物 / 长度等确定性证据优先，不靠模型自述；自述与证据冲突时以证据为准。
4. 写角色失败一次有界自愈：写角色（coder）失败一次后自动重跑；验证成功后补跑被 skip 的依赖角色。
5. 角色默认预算提高：12 步 / 120k token → 30 步 / 300k token（角色级）。
6. max_iterations 但产物已落盘且验证通过时回收步骤：满足任务目标的迭代计为完成，不误判失败。
7. 失败原因逐节点可解释：失败信息带角色 / 节点（如 s2(coder)）与 stop_reason。

实测结果（真实运行）：

• PRO 4/4 明细：analysis_summary 66,952ms / 33,210 tok；codegen_fizzbuzz 210,780ms / 343,633 tok； bugfix_calc 102,563ms / 99,155 tok；multi_file_pkg 131,984ms / 172,083 tok；总耗时 512.69s、 Token 648,081、LLM 调用 97、steps 14、rework 1。
• ENTERPRISE 4/4 明细：analysis_summary 206,078ms / 78,241 tok；codegen_fizzbuzz 186,250ms / 378,034 tok； bugfix_calc 101,734ms / 135,182 tok；multi_file_pkg 263,359ms / 477,635 tok；总耗时 757.94s、 Token 1,069,092、LLM 调用 133、steps 13、rework 3。
• 怎么验证：python scripts/collab_benchmark.py --dry-run 先看任务 × 模式矩阵（不联网）； --live 才真实调用模型并落 JSON / CSV（消耗 Token，不要接 CI / 定时任务）。
• 回归用例（离线，本地已通过）：tests/planning/test_artifact_scope_and_post_budget.py （新增 12 用例，12 passed）；pro/tests/test_engineering_collab_regressions.py （多智能体协同回归，14 passed）；另更新 tests/core/test_multi_agent_engineering_wiring.py、 pro/tests/test_engineering_multi_agent.py、tests/planning/test_tool_reliability.py、 pro/tests/test_engineering_stress.py。
• 残余风险（诚实记录）：① 30 步 / 300k 仍偏紧（额外样本 305,845 / 300,000 token）； ② 预算耗尽路径行级 token / LLM 调用疑似少记；③ Windows multi 检查点文件名含 : 保存失败 → benchmark 会话续跑不可用（不影响 8765 正常会话）；④ 单模型 / 单机 / n=1， 不构成统计显著结论。
• 失败与边界（不删减）：修复过程中间轮次的真实失败保留未删（20261101-074435-real codegen role_failed；20261101-080559-real multi_file budget_exhausted； 20261101-083304-pro 重复 PRO 轮次 3/4）；PRO 与 ENTERPRISE 是两个独立完整 run，不拼接。

8.37.2 已交付任务不再提示续跑

• 以前的问题：任务已经产出交付结果（交付物 / 结果卡片已生成）后，界面仍提示“继续”， 容易被误认为任务未完成，也可能误触发不必要的续跑、浪费 Token。
• 现在：主任务预算与收尾预算分离 —— 主交付完成后，收尾预算耗尽不再标记 partial、 不再提示续跑（resumable=false、检查点按 completed 记录）；真正的 partial （主任务预算耗尽）仍可续跑。
• 验收（离线，本地已通过）：tests/planning/test_artifact_scope_and_post_budget.py → TestPostDeliveryBudget（5 条覆盖：交付 + 收尾耗尽 → completed / resumable=False； ReAct 已交付 + 收尾耗尽不显示续跑入口；真正主预算耗尽 → partial / resumable=True；partial 不被 收尾耗尽掩盖；收尾耗尽不写 budget_exhausted）；全部 12 用例 12 passed。
• 仍看到“继续”提示？ 先确认任务是否真的已完成并交付、刷新界面；仍异常请附版本号、 复现步骤与截图反馈。

8.37.3 Web 评测取当前模型（沿用 v1.11.24）

• 本版无新增改动：/api/eval/run 未显式指定 provider / model 时取当前已接入模型与 已保存 Key；没有可用 Key 返回 409（配置问题，不是模型失败）；响应只报告来源、 不返回 Key；CLI 默认行为不变。
• 回归：tests/eval/test_eval_key_target.py、tests/server/test_eval_api.py （v1.11.24 离线用例沿用）。详细说明见 8.36.3。

09命令行与 REPL

不开浏览器也能用。安装后命令行直接可用 automind 命令。

# 单次任务（默认工作模式）
automind "创建一个 requirements.txt 包含 fastapi 和 uvicorn"

# 指定模式 / 模型 / 项目目录
automind --mode react --provider deepseek -p D:\myproj "修复 main.py 的报错"

# 信息查询
automind --version        automind --list-tools
automind --list-skills    automind --list-providers

Rich REPL（交互式彩色终端）

不带参数运行 automind 进入：

10部署与运维（团队 / 生产）

Docker 部署

docker compose up --build
# 数据（配置/记忆/检查点）持久化在 automind_data 卷
# 镜像特性：非 root 用户、/data 工作卷、自带健康检查

生产加固环境变量（默认全关，按需开启）

🗄 数据与存储（v1.1：SQLite）

v1.1 起高频数据从零散 JSON 平面文件收敛到 SQLite（WAL 模式，并发安全、增量写入）。 首次启动自动把旧 JSON 数据一次性导入，旧文件原地保留作备份，升级零感知。

10.6 🛡 内网 / 离线部署与运维v1.11.14 新增

v1.11.14 把离线部署从"设计文档"做成可运行、可验收的实现：离线总闸 + 出网白名单 + 探测三态 + 安装 / 备份 / 回滚 / 验收脚本。完整运维手册见 docs/OFFLINE_OPS.md， 缺口逐条对照见 docs/OFFLINE_DEPLOYMENT.md。

优先级：显式 AUTOMIND_NETWORK_POLICY > AUTOMIND_OFFLINE > 默认 open； 非法值 fail-closed 按 offline。策略在进程启动时读取，改完白名单需重启服务才生效。

# 安装（先加 -WhatIf 只看计划）
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\offline\install.ps1 -Package .\offline-wheels -DataDir D:\AutoMind -Mode offline -RegisterAutostart

# 备份 / 回滚 / 一键验收
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\offline\backup.ps1 -DataDir D:\AutoMind -OutDir E:\backups -RetainDays 90 -KeepLast 10
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\offline\rollback.ps1 -Backup E:\backups\automind-backup-20261021-120000.zip -DataDir D:\AutoMind -Yes
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\offline\verify.ps1 -ExpectMode offline

# 冒烟自检（策略 / 三态，JSON 输出）
python scripts\offline\smoke_offline.py --json

10.8 💼 商业运营与发证v1.11.15 新增

v1.11.15 把"签一份许可证"补成"可持续运营的闭环"：批量发证 + 台账、试用、机器绑定、离线 CRL 吊销、 周期复检 / 宽限期 / 时钟回拨检测、公钥平滑轮换，全程离线。技术细节见 docs/COMMERCIAL_ACTIVATION.md §12-20， 运营 SOP 见 docs/LICENSE_OPERATIONS.md，图文版见 docs/商业运营升级与发证操作手册_v1.11.17.docx。

11常见问题 FAQ

12附录：速查表

五种模式一句话

常用 API 端点（二次开发）

文件位置

13更新日志

每次升级带来了什么，按版本倒序。完整记录见仓库 CHANGELOG.md。