agent-Specialization/AGENTS.md

Repository Guidelines (Code-Verified)

Last verified against current codebase: 2026-06-25

这份文档基于当前仓库实际代码重写。若与未来代码冲突，以代码为准并及时更新本文档。

和用户交流时默认使用中文。

0) 项目名称

本项目（仓库 agents）的暂定产品名为 Astrion。

• 构词：Astr-（希腊语 astron，星星/天体）+ -ion（粒子/状态后缀，如 photon、electron）。
• 意象：星之子、星际粒子、来自宇宙尘埃的微小发光体。
• 寓意：Agent 像星际间传递信号的粒子，把人类意图传递到工具、文件、终端与子智能体之间；同时把零散任务像星尘聚合成恒星一样，聚合成可执行结果。
• 状态：暂定名，后续若变更需同步更新 AGENTS.md（及本地 claude.md，未随仓库发布）。
• 中文参考：阿斯特里恩；简称可考虑 星子。

1) 当前项目结构（按代码现状）

• 后端入口
  • main.py: 统一启动入口（当前默认走 Web 模式 + thinking_mode=True）
  • server/app.py: 推荐的 Web 服务入口（封装并转发到 server/app_legacy.py）
  • web_server.py: 兼容入口，已标记 deprecated，但仍可启动
• 后端核心目录
  • server/: Flask 业务主线（chat/task/status 已拆分为子包：server/chat/、server/status/、server/tasks/；REST 任务轮询为主，Socket.IO 主要用于兼容与实时辅助通道）
  • core/: 终端与工具编排（main_terminal.py、web_terminal.py、main_terminal_parts/*；其中 main_terminal_parts/context/ 和 main_terminal_parts/tools_definition 已拆分为 base + mixin 子包）
  • modules/: 可复用能力模块（terminal/file/memory/sub_agent/upload_security/user 等；file_manager、persistent_terminal、terminal_ops、mcp_client_manager 已拆分为子包）
  • config/: 配置拆分（api.py, limits.py, terminal.py, paths.py ...），由 config/__init__.py 聚合并加载 .env
  • utils/: API client、日志、上下文与对话工具等公共函数（api_client、tool_result_formatter、context_manager、conversation_manager 已拆分为子包；原入口文件保留为兼容入口）
• 前端目录
  • static/src/: Vue 3 + TS 前端
  • cli/src/: React 19 + Ink 6 + TypeScript CLI 前端（正在重写中）
  • 监控动画相关核心文件：
    • static/src/components/chat/monitor/MonitorDirector.ts
    • static/src/stores/monitor.ts
    • static/src/components/chat/monitor/*
• CLI 相关文档（本地文档，未随仓库发布）
  • docs/cli_ui_display_spec.md: CLI 显示层设计说明
  • docs/cli_slash_commands_spec.md: CLI / 指令设计说明
• 其他子项目/资源
  • android-webview-app/: Android WebView 客户端工程
  • modules/sub_agent/: 子智能体执行逻辑（主进程内 asyncio.Task，工具调用复用主进程链路）
  • easyagent/: 旧版 Node.js 子智能体实现，暂时保留但已不再使用
  • _experiments/: 本地实验残留与历史文档归档目录（不纳入 git，见 §7）

1.5) 运行态数据目录与路径变量（2026-06 更新）

设计目标：运行态数据（对话、用户工作区、日志等）默认存放在用户主目录的 ~/.astrion/astrion/ 下，对齐 ~/.claude、~/.codex 惯例，不落在源码树内。配置实现见 config/paths.py。

1.5.1 默认位置与模式分流

运行态数据根目录（data_root）默认为 ~/.astrion/astrion，可通过 ASTRION_DATA_ROOT 整体搬迁。在该根目录下，按运行模式自动分流（由 TERMINAL_SANDBOX_MODE 决定）：

• 宿主机模式（TERMINAL_SANDBOX_MODE=host）→ ~/.astrion/astrion/host
• 其它模式（默认 docker / web）→ ~/.astrion/astrion/web

数据根目录下还包含：settings.json（唯一配置文件）、config/（部署级配置，host/web 共享）。每个模式目录下包含：data/（对话、用户库、记忆、sub_agents.json、sub_agent_tasks 等）、users/（web 多用户工作区）、api/users/（API 用户工作区）、logs/（日志）。

1.5.2 路径解析优先级（从高到低）

1. 具体目录环境变量：DATA_DIR / LOGS_DIR / USER_SPACE_DIR / API_USER_SPACE_DIR（单独覆盖某个目录，最高优先级）
2. 数据根目录环境变量：ASTRION_DATA_ROOT（整体搬迁运行态数据根目录，默认 ~/.astrion/astrion）
3. 兜底默认：~/.astrion/astrion/<mode>

具体目录变量支持相对路径（相对仓库根目录展开）、绝对路径与 ~。

注意：config/*.json 分两类：

• 程序能力（docker_risk_markers.json、skill_hints.json）：是程序行为的一部分，随版本演进，仍锚定源码树。prompts/、agentskills/ 同理。
• 部署级配置（custom_models、host_workspaces、auto_approval、goal_review、forbidden_commands、host_sandbox_policy）：因部署/机器而异或含密钥，外置到 ~/.astrion/astrion/config/（即 DEPLOY_CONFIG_DIR，可单独用该环境变量覆盖，host/web 共享）。读取走 config.resolve_deploy_config(name)，回退链：部署目录 → 源码树 .json → 源码树 .json.example，因此开发环境不必先跑 setup 也能用源码树种子。含密钥/机器特定的 5 个（除 forbidden_commands）不纳入 git，仓库仅留 .example。

1.5.3 Host / Web 双路径机制（2026-06 新增）

paths.py 新增三个固定变量，支持 host 模式同时读取 web/ 数据：

• IS_HOST_MODE：当前是否为 host 模式（布尔值）
• WEB_DATA_DIR：固定指向 <data_root>/web/data（不受当前模式影响）
• WEB_USER_SPACE_DIR：固定指向 <data_root>/web/users（不受当前模式影响）

host 模式（modules/user_manager.py）：

• 用户列表：同时加载 host/data/users.json + web/data/users.json（web 用户不覆盖已有）
• 工作区列表：合并 host/ 和 web/ 两处
• 工作区定位：已有 web 工作区直接复用；新工作区写入 host/
• 写操作（创建/删除/重命名）：始终走 host 路径

web 模式：只读取 web/ 数据，无变化。

设计意图：host 模式 = host + web 数据都可用；web 模式 = 仅 web 数据可用。

1.5.4 日志策略（2026-06）

• API 请求体落盘（dump）默认关闭，由 AGENT_API_DUMP_ENABLED 控制（1/true/yes/on 开启）。
• 日志混合轮转（实现见 utils/log_rotation.py）：
  • 追加型单文件（host_workspace_debug.log、chunk_*.log、conn_diag.log、api_debug.log、TaskLogger/ErrorLogger）按大小轮转，默认单文件 20MB、保留 3 份。
  • 按份计量目录（api_requests/ 一请求一文件）只保留最近 N 个，默认 30。
  • 阈值可覆盖：AGENT_LOG_ROTATE_MAX_BYTES / AGENT_LOG_ROTATE_BACKUPS / AGENT_DUMP_KEEP。

1.5.5 数据迁移

• 迁移脚本：scripts/migrate_runtime_data.py（源码树 → 运行态根；复制+备份+可回滚+幂等，logs/ 丢弃不迁）。
  • 脚本 import config 复用程序同一套路径解析（含 .env），模式由 .env 决定；执行前务必先 --dry-run 确认目标。
• 清理误迁副本：scripts/cleanup_misplaced_web.sh。

2) 当前可用启动/构建命令（已按代码核对）

Python / 服务端

• 安装依赖：pip install -r requirements.txt
• 推荐启动 Web：python -m server.app
• 可选参数：python -m server.app --path ./project --port 8091 --debug --thinking-mode
• 兼容启动方式：python web_server.py
• 统一入口：python main.py（当前实现会默认进入 Web 启动流程）

Frontend（根目录）

• 安装依赖：npm install
• 构建：npm run build --silent 2>&1 | tail -n 5（默认只看最后 5 行，减少 Vite 构建资源列表等无关输出）
• 开发监听（当前脚本是 build watch）：npm run dev
• Lint：npm run lint

CLI（React / Ink）

• 安装依赖：npm --prefix cli install
• 开发启动：npm run cli 或 npm --prefix cli run dev
• 构建：npm run cli:build
• 类型检查：npm run cli:typecheck
• 可执行命令名（构建后）：agents / agents-cli

3) 测试现状（不要再写过时命令）

• 当前仓库内可见自动化冒烟：test/test_server_refactor_smoke.py（unittest）
  • 运行方式：python -m pytest test/test_server_refactor_smoke.py -q
  • 注意（2026-08-01 实测）：python -m unittest test.test_server_refactor_smoke 在标准 Windows Python 上失败——stdlib 自带常规包 test 遮蔽本地 test/ 目录（无 __init__.py 的命名空间包优先级更低），报 No module named 'test.test_server_refactor_smoke'。无 pytest 时可用： python -c "import sys; sys.path.insert(0, '.'); import unittest; suite = unittest.TestLoader().discover('test', pattern='test_server_refactor_smoke.py'); r = unittest.TextTestRunner().run(suite); sys.exit(0 if r.wasSuccessful() else 1)"
• test_system_message.py 依赖外部 MOONSHOT_API_KEY 与网络，不属于离线稳定 CI 用例。
• 当前仓库未发现 pytest.ini/pyproject.toml/tox.ini；不要默认要求 pytest 作为唯一入口（仅作为冒烟测试的便捷运行器）。
• CLI 当前最小可复现验证：
  • npm --prefix cli run typecheck
  • npm --prefix cli run build
• 若改动 server/chat/、server/status/、server/tasks/ 等后端接口适配，补充：
  • python3 -m py_compile server/chat/*.py server/status/*.py server/tasks/*.py
  • python -m pytest test/test_server_refactor_smoke.py -q

4) 代码修改约定（实用版）

• 根治优先原则：修复问题时优先判断能否根治；能根治的，应告知用户根治方案与影响范围并询问是否执行，在一定范围内的重构是可接受的，尽可能避免打补丁式的临时修改。
• 精确读取原则：禁止整文件通读。阅读/修改前先用搜索工具（grep / 符号查找 / 关键字定位）锁定需要的行段，只精确提取并阅读相关片段，不要把整个文件一次性读进来。
• 文件编辑方式：修改文件时优先使用 apply_patch 或其他原生文件编辑工具；尽量不要用 bash/python 脚本批量改文件，除非原生工具明显不适合。
• 后端改动优先级：先改 modules/、server/ 内对应模块，最后才动入口。
• 前端改动优先级：按 static/src 现有分层改（app/、stores/、components/、composables/）。
• CLI 改动优先级：优先在 cli/src/App.tsx、cli/src/components.tsx、cli/src/eventMapper.ts、cli/src/api.ts 内做最小闭环修改。
• 涉及 monitor 动画/事件联动时，至少同步检查：
  • MonitorDirector.ts（动画与场景执行）
  • stores/monitor.ts（事件队列与状态机）

5) 风格与质量

文件长度与拆分

• 单文件最好不超过 1000 行；超过时应优先考虑合理拆分，避免维护成本快速上升。

• 行数不是硬性指标：文件是否拆分取决于可维护性，而不是必须小于某个固定行数。

• 当单一文件超过约 500 行时，应评估是否具备以下拆分价值：

  • 业务逻辑过重、职责不单一；
  • 存在清晰的边界（如按工具类型、按资源、按生命周期阶段）；
  • 拆分后能提高复用性、可读性或测试便利性。

• 不要为了拆分而拆分。边界模糊、耦合紧密或改动频率低的文件，保持现状可能更划算。

• Vue SFC 因模板、样式、脚本耦合较深，拆分风险较高；优先抽离 composable 和子组件，而非直接切分 .vue 文件。

• Python：4 空格、snake_case 函数、PascalCase 类，新增公共函数尽量补 type hints。

• Vue/TS：保持现有代码风格，不做无关风格清洗。

• CLI React/TS：保留现有 Ink 渲染方式与光标修正逻辑，不要轻易重写输入框定位策略。

• 日志：优先复用现有 logger/日志路径，不引入大量临时 print。

• 提交前至少做与改动相关的最小验证（命令输出或手工步骤要可复现）。

• 视觉验证默认由用户完成：除非用户特别说明，所有需要视觉确认的修改（尤其是动画/过渡效果），构建/lint 通过后交由用户亲自查看确认，不要用 Playwright 截图或浏览器自动化代替用户验收。

• 运行根目录前端构建时，默认使用 npm run build --silent 2>&1 | tail -n 5。

CLI 当前交互约束（2026-05-15）

• CLI 连接的是现有本地 Web API（默认 127.0.0.1:8091），不是独立 agent runtime。
• 启动 CLI 时应清屏、连接本地服务、创建新会话，并将输入区固定在底部。
• 当前目录若不在工作区中，应先弹出“是否添加到工作区”的选择。
• 思考内容当前默认隐藏，只显示“思考中 / 思考完成”标题；相关折叠代码保留，后续可继续修。
• 不要在未获得用户要求的情况下运行交互式 TUI 压测或长时间模拟输入，以免刷屏占满上下文。

5.5) 前端设计风格统一规范（强制）

适用范围：所有前端 UI（以 static/src Web 为主；cli/src 在视觉可类比处同样适用；以及未来新增的任何界面）。 约束级别：写新 UI 或改动 UI 时必须遵守；遇到存量违规应在最小改动允许范围内顺手修正。 配色基础设施：两层 token（原始层 + 语义层）定义在 static/src/styles/base/_tokens.scss（:root[data-theme='classic'|'light'|'dark'] + 首屏回退 :root:not([data-theme])），切换逻辑见 static/src/utils/theme.ts；.stylelintrc.cjs 三条规则做防回退栏杆，build 含 stylelint 步骤。

1. 禁止边缘光晕：不使用任何 glow / 外发光 / 彩色光晕效果（大范围彩色 box-shadow 扩散、filter: drop-shadow 光圈、::before/::after 模糊光晕等）。已有的要移除。允许的只是中性、克制的投影——沿用 --shadow-* 既有 token，不自造发光阴影。仅在用户明确允许或要求时才可使用光晕效果。
2. 禁止原生浏览器组件：不直接使用浏览器默认外观的 <select>、<input type=checkbox/radio/range/date/color>、alert/confirm/prompt、原生右键菜单、原生 tooltip 等，一律换成与项目风格统一的自定义组件（下拉 / 开关 / 单选 / 滑块 / 模态 / Toast）。
3. 禁止圆角套娃：不允许「圆角矩形套圆角矩形套圆角矩形」的多层嵌套卡片——典型垃圾审美，且极大占据有效显示面积。容器层级要扁平，优先用分隔线 / 留白 / 底色区分，不要多包一层带边框圆角的盒子。
4. 图标外框对齐：同一组图标按钮的外框（点击热区 / 容器）必须统一对齐，不能一会居中、一会左对齐、一会右对齐；同组固定相同尺寸与对齐方式。
5. 图标视觉对齐而非理论对齐：按图标视觉重心对齐而非几何边界盒；对重心偏移的图标（三角形 / 播放键 / 放大镜等）做微调，使其「看起来居中」。
6. 颜色遵循三模式切换 + 两层 Token：所有颜色走原生三模式，禁止写死颜色字面量（裸 hex / rgb()/hsl() 字面色 / var(--x, #hex) 兜底），一律用中性语义 CSS 变量（--surface-* / --text-* / --border-* / --accent* / --state-*）。三主题定位：经典抄 Claude 亮色盘（暖奶油 + 暖橙 primary #cc785c）、浅色抄 ChatGPT 亮色盘（冷白 + 灰 + 近黑 primary #181818）、深色自研中性灰阶。亮色表面靠灰阶拉层次（经典 --surface-base #faf9f5 < soft #f5f0e8 < card #efe9de < muted #e8e0d2），不许全塌成白。primary 克制（CTA-only），hover/选中/运行态走中性灰。半透明 tint 用 color-mix(in srgb, var(--token) N%, transparent) 派生。--claude-*/--theme-* 是过时别名，新代码勿用。新增颜色必须三主题（含首屏回退）补齐。
7. 带文字容器固定高度：所有含内部文字的选项 / 按钮 / 标签 / 容器固定高度，禁止因文字多少被撑大撑高；过长文字用省略号或内部滚动处理。
8. 窗口设最大尺寸 + 内部滚动：所有弹窗 / 面板 / 列表设置 max-height / max-width，超出由内部容器滚动，不顶大整个窗口；滚动条要么隐藏，要么做样式适配，不暴露原生粗滚动条。
9. 实体面板禁止半透明：实体 UI 容器（对话区 / 侧栏 / 下拉/二级菜单 / 抽屉 / 对话框本体 / 状态条 / tooltip / 输入栏）背景必须不透明，且不加 backdrop-filter 磨砂。唯一例外：遮罩层 scrim（--overlay-scrim，position:fixed;inset:0）和刻意玻璃质感装饰保留半透明。
10. 主题变体必须与基础定义同文件（禁止跨文件补丁覆盖）：组件的 dark/light/classic 主题变体写在该组件自己的样式文件里（文件内统一的 body[data-theme='…'] { … } 块），禁止把某组件的主题样式写到别的文件去覆盖。新增主题样式前先确认该组件基础定义所在文件；发现存量跨文件覆盖应顺手回迁并删除原覆盖。!important 只准用于遮盖第三方库样式，禁止用于压过项目自有定义（出现这种需求说明应该合并定义，而不是加 !important）。审计脚本：python3 cache/style_audit.py + python3 cache/theme_diff.py（本地脚本，未随仓库发布）。
11. 大面积色块禁止纯黑/近黑：任何窗口的 hover、头部、背景等大面积色块，禁止使用纯黑（#000）或肉眼近黑（如 #0a0a0a/#0f0f0f 一档）的颜色，深色模式同样如此。深色下的层次靠中性灰阶拉开：hover 用 --hover-bg（深色为白色微量 tint，提亮而非压黑），弹窗/面板头部优先用分隔线区分而非深色衬底（参考 VersioningDialog.vue 头部）。纯黑/近黑只允许用于小范围强调渲染（如行内代码衬底等小面积场景）。

5.6) 工具结果显示规范（强制）

适用范围：所有使用 tool-result-meta / tool-result-content 结构渲染的工具结果（如 static/src/components/chat/actions/ToolAction.vue、toolRenderers.ts 等）。 约束级别：新增或修改工具结果渲染时必须遵守。

1. meta 部分只放参数：tool-result-meta 仅用于展示工具调用的参数、配置、状态标识等元信息。例如：状态、ID、路径、任务描述、超时时间等。禁止在 meta 区域放置执行结果、统计摘要、输出内容等。
2. content 部分只放结果：tool-result-content 仅用于展示工具执行后的结果、输出、统计、总结等。例如：文件内容、命令输出、搜索命中、执行统计（工作时间 / 调用次数 / 工具次数）、最终回复摘要等。禁止在 content 区域重复展示工具参数。

5.7) 调试输出规范（强制）

约束级别：需要临时加调试日志排查问题时必须遵守。

前端调试日志

• 统一筛选词（强制）：所有临时 console.log 必须使用同一个筛选前缀（例如 [route-debug]），方便用户在浏览器控制台用该前缀一次性筛选。
  • 同一次调试任务中严禁使用多个前缀。如果涉及多个模块（如状态栏、Git 摘要、用户问题），应共用同一个前缀（如 [status-bar-debug]），通过日志对象里的字段区分模块，而不是发明多个前缀增加用户筛选成本。
  • 选择前缀时优先与本次排查的「用户可见现象」对齐，而不是与内部模块名对齐。
• 控制数量与时机：
  • 禁止一次性输出上百上千条日志刷屏。
  • 只在关键路径（入口、分支判断、状态变化、导航动作）打印，避免在循环、高频事件、每帧渲染中输出。
  • 需要大量结构化数据时，优先用 console.group / console.table 或对象快照，而不是逐条打印。
• 用完即清：问题定位后应及时删除或注释掉临时调试日志，不要长期留在代码里。

后端调试日志

• 必须写入文件：后端调试信息禁止直接 print 到终端刷屏，必须写入日志文件。
• 复用现有 logger：优先复用项目已有 logger（如 utils/logger.py、modules/multi_agent/debug_logger.py 等），按模块落到 ~/.astrion/astrion/<mode>/logs/ 下。
• 关键状态转换必打：多智能体、子智能体、任务轮询等复杂链路应在关键状态转换点写结构化日志，便于复现问题后按时间线追溯。

5.8) 前端多语言（i18n）文案规范（强制，2026-08 新增）

详细规范：doc/frontend/i18n_spec.md。约束级别与 §5.5 同级：写新 UI 或改动 UI 文案时必须遵守。

• 引擎：vue-i18n v10（Composition 模式）；文案唯一定义在 static/src/locales/{zh-CN,en-US}/<namespace>.ts，中文为源语言。
• 使用：模板用 $t('ns.key')（全局注入、响应式）；SFC script / 纯 TS 用 import { t } from '@/locales'（调用时求值、非响应式；响应式标签用 useI18n() 或读取 currentLocale）。
• 公共词：高频通用词唯一来源是 common 命名空间，禁止在各域重复定义。
• key 奇偶强校验：en-US 聚合器用 DeepString<typeof zhCN> 约束，en 缺/多 key 直接 tsc 报错；新增命名空间须在 zh-CN.ts / en-US.ts 同步注册。
• 防回退栏杆：npm run lint 先跑 scripts/i18n_audit.mjs（剥离注释后查裸中文，独立命令 lint:text）；存量文件列在 scripts/i18n_baseline.txt，迁移完一个文件就删一行，删除后该文件永久受栏杆保护。
• 语言切换：个人空间 → 外观 → 界面语言；默认 zh-CN（不跟随浏览器），持久化 key agents_ui_locale。
• 边界：后端下发文字（API error、通知、工具结果摘要）不做多语言，前端原样显示；CLI 暂不纳入。

6) Git 工作流（开发 + Review）

6.1 核心原则

• 默认直接在 main 上开发，不强制新建功能分支。
• 每个功能建议在 main 上保持一个清晰 commit，历史干净可回滚。
• 使用 Conventional Commits：feat: fix: refactor: chore: docs: test: perf:。
• 个人项目，不设 PR 和 Review 流程；如用户临时要求隔离开发，再按需新建分支。

6.2 工作流（唯一步骤）

AI 执行以下流程时，每一步都要向用户说明在做什么：

0. 检查工作区状态
   git status
   如有未提交的改动：
   - 若无关：提醒用户先 commit 或 discard
   - 若有关：git stash push -m "WIP: <简短描述>" 暂存

1. 确认在 main 并同步最新代码
   git checkout main && git pull origin main

2. 开发并提交
   git add <修改的文件>
   git commit -m "feat(scope): 简短描述"
   （多轮迭代可用 git commit --amend 保持一个 commit）

3. 推送到远程（备份 + 方便切设备）
   git push origin main

重要约束：

• AI 必须在本地验证修改能正常运行，再建议用户提交。
• 修改完成后按改动规模汇报：大修改说明核心变更点与验证结果；小修改只说明核心变更点。
• 禁止 AI 在未经用户确认的情况下执行 git commit 或 git push。
• commit / push 授权均为一次性：用户说“可以 commit/push”只代表允许这一次操作；后续如需继续 commit / push，必须由用户再次主动同意。
• 允许 commit 不等于允许 push：两者授权相互独立，获得 commit 许可后仍需单独征得 push 许可。
• 不需要每次都执行或输出 diff；如用户要求 Review，再在同一对话内使用 git diff 或 git diff HEAD~1..HEAD。

6.3 常用命令速查

操作	命令
暂存未完成工作	git stash push -m "WIP: xxx"
修改最近 commit	git commit --amend
同步 main	git checkout main && git pull origin main
同对话内 Review diff	git diff 或 git diff HEAD~1..HEAD
查看提交历史	git log --oneline -10

7) 安全与仓库卫生

• 严禁提交真实密钥（.env、token、cookie、用户隐私）。
• 运行态数据默认在 ~/.astrion/astrion/<mode>/（data/、users/、logs/、api/），不在源码树内；详见 §1.5。.gitignore 仍忽略源码树内的 logs/、data/、users/、api/、project/ 等，以防通过具体变量指回源码树或历史遗留产生污染。分享前需脱敏。
• _experiments/ 用途：归档本地实验残留与历史文档（调试记录、旧变更日志、模型测试脚本、翻译资料、旧子智能体文档等）。该目录不纳入 git（已在 .gitignore）。需要保留但不属于当前主线、又不想直接删的零散文件，统一放这里，不要散落在根目录。
• 不要把本地构建产物（如 static/dist/、node_modules/）纳入提交。

8) Android App 发布联动要求（重要）

当修改前端并需要发布 Android WebView App 时，必须同步执行以下步骤（依据 doc/android_app_release_and_update.md，本地文档未随仓库发布）：

1. 同时更新版本信息
   • android-webview-app/app/build.gradle.kts：递增 versionCode，更新 versionName
2. 同时更新更新说明
   • android-webview-app/APP_CHANGELOG.md：在顶部新增当前版本说明
3. 完成修改后提醒用户运行上传脚本
   • 在发布流程中运行：bash ./upload_android_apk.sh（本地私有脚本，未随仓库发布）

禁止只改前端代码而不更新版本号/更新说明，否则会导致客户端更新提示与分发信息不一致。

9) 给 Agent 的硬性要求

• 先读当前代码再执行，不依赖历史文档记忆。
• 输出结果按改动规模决定：
  • 大修改：必须包含核心变更点、验证结果（已执行命令/未执行原因）。
  • 小修改：只需包含核心变更点。
• 不要求每次列出所有修改文件；仅在用户要求、改动复杂或有助于说明时列出。
• 不要求每次执行或展示 diff；仅在用户要求 Review 或排查差异时使用。
• 如果发现本文档过时，直接更新 AGENTS.md 并在结果中说明依据。

10) 宿主机权限模式与沙箱执行机制（2026-05 更新）

完整说明文档：docs/host_sandbox_and_permission_model.md（本地文档，未随仓库发布）

为避免误解，当前系统有两套独立但叠加的控制：

1. 权限模式（Permission Mode）：readonly / approval / auto_approval / unrestricted
2. 执行环境（Execution Mode）：sandbox / direct（仅宿主机模式可切换）

10.1 权限模式

• readonly
  • run_command 可调用，但在只读沙箱执行；写入由系统拒绝
  • 读取同样受限（各平台只读强制的可读边界见 §10.8）；读不到属预期边界，不是故障
  • write_file / edit_file 等写入类工具直接拒绝
• approval
  • run_command 先走只读沙箱（可读边界见 §10.8，读越界也会触发权限拒绝）
  • 若出现权限拒绝（例如 Operation not permitted / Permission denied），触发前端审批
  • 审批通过后，仅该次命令以可写沙箱重试；工具结果返回“重试后的最终结果”
  • 审批只授予该次命令的工作区内写权限，不放大读取（2026-08-30 方案一）：可写沙箱读边界与只读同一白名单，读越界唯一途径是「路径授权」；重试后仍为文件权限拒绝时，工具结果附带 read_scope_hint 引导模型说明
  • 执行环境锁定为沙箱（2026-08-30 起）：direct 下无沙箱兜底，启发式漏判的写命令会直接执行成功、审批承诺被架空，故批准/自动审核与 direct 硬互斥（锁定机制同 plan/只读，见 §10.6）
• auto_approval
  • write_file / edit_file：工作区内路径直接执行，工作区外路径进入审批流程
  • run_command 先走只读沙箱（可读边界见 §10.8）；触发权限拒绝后由后台审批智能体自动审核
  • 自动审核拒绝时，工具返回“被拒绝+理由”并继续主循环（不强制结束任务）
  • 批准后的读取边界与 approval 相同（不放大）
  • 执行环境同样锁定为沙箱（同 approval 条目）
• unrestricted
  • 权限层不做拦截：工作区内读写自由、命令免批准；是否沙箱由执行环境决定
  • 注意「无限制」只管工作区内：宿主机沙箱执行时读边界仍是白名单（见 §10.8），授权范围外读取需路径授权；direct 模式才真正无边界

10.2 执行环境

• sandbox（默认）：使用 OS 沙箱执行（macOS: sandbox-exec，Linux: bwrap + seccomp，Windows: WSL2）
• direct：宿主机直接执行（高风险），仅 unrestricted 权限可选：受限权限档（只读/批准/自动审核）与 plan 模式下后端 set_execution_mode 硬锁拒绝 direct（i18n 键 main_terminal.restricted_mode_locks_sandbox / plan_mode_locks_sandbox）；进入受限档时若已是 direct 会被联动压回沙箱（记录 pre_readonly_execution_mode，切回 unrestricted 时恢复）；存量「受限档+direct」对话在加载时自愈矫正回沙箱
• 切换后一直生效，无自动回退机制（2026-07 已移除原 TTL 自动回退）

10.3 路径授权语义

• 前端“路径授权”支持两类路径：
  • 可读可写
  • 仅可读
• 语义：
  • 可读集合 = 可读可写 + 仅可读
  • 可写集合 = 可读可写
• 配置来源（2026-08-30 收敛为两个）：config/host_sandbox_policy.json（UI 唯一读写目标）+ 真·环境变量 HOST_SANDBOX_MACOS_WRITABLE_PATHS（部署通道，与文件合并去重）。settings.json 的 terminal.macos_writable_paths 映射已移除（历史值一次性失效，需用路径授权重新添加）；.env 注入技术上仍生效，但不是受支持的通道，不推荐使用

10.4 维护约束

• 不要在提示词里暴露内部实现细节（例如“命令文本猜测”等）
• 文案应面向用户能力边界与操作建议，不描述内部判定算法

10.5 审核智能体配置与调试

• 审核智能体配置：统一在个人空间「审核智能体」页设置（2026-08 起），存于 personalization.json 的 review_agents 键
  • 三个审核智能体：auto_approval（自动审批）/ goal_review（目标审核）/ workflow_review（工作流审核）
  • 字段：model（子智能体模型库条目名，留空=模型库 default_model）/ thinking / timeout_seconds / max_rounds / max_command_timeout
  • 解析入口：modules/review_agent_config.py::resolve_review_agent_config（复用 sub_agent_models.json + _build_sub_agent_profile）
  • 旧的独立 json 配置（config/auto_approval.json / goal_review.json / workflow_review.json.example）已彻底废除，无向后兼容
• 调试开关（代码变量）：modules/approval_agent.py 中 DEBUG_SAVE_APPROVAL_AGENT_TRANSCRIPT
  • 开启后写入：logs/approval_agent/
  • 记录以累积 messages 为主，便于对齐主/子智能体会话格式

10.6) 运行模式（work_mode）系统（2026-08-13 新增）

运行模式（work_mode：plan / ask / execute）控制与用户的交互节奏，与权限模式（限制模型能力）正交。命名注意：run_mode 已被 fast/thinking 思考模式占用，严禁混用。

三档语义

• plan（计划）：只制定计划并讨论；权限锁定为只读且执行环境锁定为沙箱（UI 禁用 + 后端 set_permission_mode/set_execution_mode 双重强制——只读在宿主机依赖 OS 沙箱硬限制，direct 下无沙箱形同虚设）；唯一写例外是 .astrion/plan/*.md 计划文档（权限层判定，提示词要求用 write_file/edit_file 直写，不走沙箱）；计划完成后调 submit_plan 工具提请批准，批准后自动切换到 execute（恢复进入 plan 前的权限与执行环境，无记录时权限回落个性化 default_permission_mode、执行环境保持沙箱安全默认）
• ask（询问）：先讨论后开工；禁用 ask_user 工具（开放式讨论必须直接写在回复里）；与 execute 无执行层差异，仅提示词不同
• execute（执行）：自行梳理计划、脑补细节直接开工；仅硬阻塞才提问

实现要点（改代码必须知道）

• 后端核心：core/main_terminal_parts/tools_policy.py（WORK_MODES、get/set/switch_work_mode、plan 锁；RESTRICTED_PERMISSION_MODES 受限档集合 + set_permission_mode 内 _apply_restricted_execution_mode_link 处理受限档⇄沙箱联动，pre_readonly_execution_mode 存对话 metadata——键名保留，语义已泛化为受限档共用）；switch_work_mode 处理 plan⇄只读+沙箱联动，pre_plan_permission_mode/pre_plan_execution_mode 存对话 metadata；执行环境 plan 锁与受限档锁同在 core/main_terminal.py::set_execution_mode（只拦 direct）
• 创建对话的模式继承（work_mode + permission_mode 同一原则）：三条创建路径（prefer_defaults / 显式模式 / safe_navigation）一律沿用 terminal 当前值，不用个性化默认值覆盖——/new 页面切换器显示什么新对话就是什么（切换经 _sync_workspace_terminal_mode 同步到工作区级 terminal）；个性化 default_work_mode / default_permission_mode 仅在 terminal 首次构造时生效（tools_policy 加载）。多智能体创建路径（server/multi_agent.py）与工作流创建路径（workflow_runtime_api.py）同样遵守。plan 锁存在于 set_permission_mode，任何创建路径不得在其之前调用非只读 set（曾因此 500）
  • 历史教训：permission_mode 曾长期例外（a2a04b95 引入「个性化默认优先」，彼时还没有 /new 切换器同步机制），导致 /new 切只读后新建对话回落无限制（2026-08-30 修复，与 work_mode 对齐）
• 提示词：prompts/work_mode.txt 模板 + mode.py::_build_work_mode_rules（三档规则唯一来源，冻结注入与切换通知共用）；冻结注入在 messages.py（执行环境之后）；切换走现有 drift 机制（_RUNTIME_MODE_KINDS 第四种），通知携带完整新规则文本
• API：GET/POST /api/work-mode（server/chat/permission.py）；仅空闲可切换，运行中 409（无 pending 队列）；plan-approvals pending/answer 端点在 server/chat/approval.py
• submit_plan 链路：工具全模式注入（沟通类工具不过滤，非 plan 调用由 handler 运行时兜延返回引导）；PlanApprovalManager（modules/plan_approval_manager.py）+ chat_flow_tool_loop.py::_handle_submit_plan 阻塞等待 → 前端 PlanApprovalDialog.vue 弹窗 → 批准则工具循环内切 execute 并静默更新 baseline（避免误发 drift 通知）
• 个性化：default_work_mode（默认 plan），后端 personalization_manager.py 白名单 + 前端 stores/personalization.ts 三处（接口/默认值/sanitize）
• 前端：输入栏 work-mode-switcher（InputComposer，streaming 时锁定）；plan 下权限菜单内「权限」「执行环境」两组选项禁用+锁定标记（网络权限组保持可调，不整体锁死菜单），slash 菜单同步禁用；get_status 带 work_mode 供多标签页同步

10.7) 后台命令只读沙箱修复（2026-08-13）

后台 run_command（run_in_background=true）此前在所有环境绕过只读权限（background_command_manager 固定用可写沙箱计划）。已修复：create_background_command 透传 sandbox_write_access，宿主机路径按它选只读/可写计划；docker 路径按它决定是否以非特权 uid 执行（见 §10.8）。

10.8) 平台级只读强制（2026-08-30）

只读权限的强制由各平台原生机制兜底；config/limits.py 的命令文本白名单（_is_readonly_run_command_allowed）只是审批决策的启发式，不再是安全边界（已知可绕过，如 find . -delete；绕过后果只是多走一次审批）。

• docker/web 模式 = 非特权 uid 执行角色（modules/docker_readonly_exec.py）：
  • 容器主进程保持 root（可写执行不变）；sandbox_write_access=False 的执行通道（terminal_ops/run.py、background_command_manager.py、只读语境创建的持久终端）以 -u 10001:10001 运行，DOCKER_READONLY_EXEC_UID/GID 可覆盖
  • 强制力 = 内核 DAC：工作区属主为宿主机 root，非属主无写权；600 权限文件（如 .env）不可读；逃逸需提权（setuid/内核漏洞），无 umount 类捷径
  • 前提：工作区属主与该 uid 不碰撞、无 o+w 文件、容器未挂 docker.sock（云端已验证）；macOS Docker Desktop（virtiofs fakeowner）不执行 uid 权限，仅 Linux 宿主生效
  • 持久终端在 readonly/approval/auto_approval 下同以只读身份创建（docker_terminal_readonly_enabled 判定，docker_readonly_getter 注入）；终端里的写入会被拒，写命令走 run_command 审批通道
  • Dockerfile 创建 agent 用户 + /etc/gitconfig safe.directory + 去 setuid 加固；数字 uid 不依赖镜像内用户存在，旧镜像直接受益
• macOS 宿主机 = Seatbelt 白名单读模型（modules/host_sandbox_runner.py）：
  • 只读/可写两个 profile 共用同一白名单读模型（_build_macos_whitelist_read_rules），唯一区别是写权限：deny default + 系统路径白名单（MACOS_MINIMAL_READABLE_PATHS）+ 路径授权（writable + readable_extra）+ 工作区 + 祖先目录 literal allow（缺一个祖先进程 exec 直接 Abort trap，必须为 file-read*）+ env 注入 GIT_CONFIG_GLOBAL=/dev/null（可写/只读/持久终端三条 plan 均注入）
  • deny 规则（.env 正则、~/.ssh 等）必须位于所有 allow 之后（Seatbelt 后规则覆盖先规则）；两个 profile 均已修复旧顺序漏洞（工作区 .env 曾实际可读）
  • 可写 profile 已于 2026-08-30 白名单化（此前为全局可读，导致 unrestricted/审批批准后能读授权范围外文件）；白名单固有代价：祖先目录顶层文件名可列出（读文件内容仍被拒）
  • 原生文件工具对齐（file_manager/path_mixin.py）：读 roots 与沙箱白名单同源（系统路径 + 工作区 + 授权）+ 叠加同一禁读清单——至此 host+sandbox 下全部读通道（只读/可写沙箱命令、原生 read_file）共享同一边界
• Linux 宿主机 = bwrap：只读为 --ro-bind / /（全局只读）；可写为 --ro-bind / / + 工作区可写 bind——读侧仍是全局可读，尚未对齐白名单（本机无 Linux 测试环境，刻意未动，待后续）；Windows = WSL2 最小根文件系统（白名单）——命名空间内只有系统目录+工作区，天然符合

11) 多智能体对话类型（multi-agent conversation type）

2026-08 重构：已废除「多智能体模式」全局状态，多智能体是对话的不可变属性（metadata.multi_agent_mode = true，创建时确定、不可变）。URL 统一为 /<conv_id>（旧 /multiagent/* 由前端 bootstrap 重定向到裸路径）。数据目录 ~/.astrion/astrion/host/mutiagents/（保留原拼写）。重构方案见 docs/conversation_type_unification_plan.md（本地设计文档，未随仓库发布），本节只列 Agent 改代码时必须知道的硬约束。

11.0 前端对话类型模型（重构后）

• 三个语义单一的状态，互不复用：
  • currentConversationType（static/src/app/state.ts）：当前已打开对话的类型（'normal' | 'multi_agent' | null），由 enterConversation 从对话 metadata 恢复（bootstrap.ts），空对话为 null。
  • newConversationType（同上）：空对话时输入栏待创建类型（'agent' | 'multi_agent'），localStorage 持久化（agents_new_conversation_type），由输入栏底行 + 右侧的类型选择器修改（InputComposer.vue 的 agent-type-switcher）。
  • sidebarConversationType（stores/conversation.ts）：侧边栏列表过滤器（'normal' | 'multi_agent'），localStorage 持久化（agents_sidebar_conversation_type），驱动列表/搜索的 multi_agent_mode=0|1 请求参数与侧边栏新建按钮的对话类型。
• stores/conversation.ts 的 multiAgentMode 字段保留，但语义已变为「当前对话是否多智能体」，仅由 enterConversation（meta 落地）与空对话 watcher（复位 false）写入——stores/subAgent.ts 的读取点依赖它，不得删除。
• 侧边栏类型切换 UI：分段控件统一显示在「搜索对话」下方（平铺/分组模式位置一致，搜索时隐藏）；列表区域用 <Transition> 推挤式同步滑动动画（无 out-in，新面板绝对定位从侧边滑入把旧面板顶出，切多智能体向左，切回反向；切换时重置列表滚动位置）。
• 发送消息创建对话时按 newConversationType 选择 /api/conversations 或 /api/multiagent/conversations（message/send.ts）；侧边栏新建按 sidebarConversationType 选择（conversation/action.ts）。

11.1 角色与实例

• 主智能体显示名固定为 Team Leader，不需要专门的预置角色文件。
• 子智能体 = role_id（如 ui-operator / full-stack-engineer / code-reviewer / researcher）+ 角色内编号（同一 role_id 下从 1 递增）。显示名格式 {Role Name}_{角色内编号}，例如 UI Operator_1，后缀永远带数字。
• 编号暴露原则（2026-08-26 起）：角色内编号显示名是唯一对模型和用户暴露的身份；全局 agent_id 是纯内部实现细节（任务字典 key / task_id 生成），由系统自动分配对话级最小空闲正整数，不接受模型指定、不出现在工具参数/结果文案/前端展示中。所有寻址类工具（send_message/stop/terminate/get_sub_agent_status/sleep 的 wait_sub_agent_output、子侧 ask_other_agent）一律用显示名。
• 主→子 / 子→主 / 子→子三种通信通过工具完成，工具签名见 modules/multi_agent/tools.py。
• send_message_to_sub_agent 与 ask_sub_agent 语义不同，必须保留两者：前者插入引导消息不阻塞，后者阻塞等待一轮回答。
• 子智能体间通信要求同时向主智能体输出汇报，不允许「偷偷沟通」。

11.2 子智能体执行机制

• 子智能体在主进程内 asyncio.Task，跑在独立后台事件循环线程里（避开 Flask-SocketIO threading 冲突）。工具调用复用主进程沙箱/容器链路，网络调用走 utils.api_client.APIClient。
• 模型请求重试（2026-08-26 起）：_run_loop 对 _call_model 包重试循环，与主智能体 run_streaming_attempts 同构——最多 5 次尝试（_SUB_AGENT_MAX_API_RETRIES=4）、间隔 10s（_SUB_AGENT_RETRY_DELAY_SECONDS，用 asyncio.sleep 分段等待并响应软停止/取消）。重试条件：仅当零接收（未收到任何文本/思考/工具调用）才重试；已开始收到内容后断流（SubAgentModelCallError.received_any=True）直接失败。失败终态分模式：多智能体模式下 5 次全失败 → 转为 idle + _forward_output_to_master 报错（等 Team Leader 重新下达指令），输出期间断开 → 直接 failed 并同步向主智能体报错；传统模式一律 _write_failure。
• 工具「正在调用」进度事件（2026-08-26 起）：_call_model 在工具名+id 首个流式 chunk 到达时即 emit status="calling" 进度事件（与后续 running/completed 共用同一 tool_call id），前端按 id 原地更新条目；RunnerDetailPanel.vue / SubAgentActivityDialog.vue 的 normalizeStatus 识别 calling（显示 spinner + 「调用中」），并支持同一 id 历史条目跨组原地更新（多工具 calling 事件交错场景）。
• 子智能体在多智能体模式下：
  • create_sub_agent 强制 run_in_background=False，不触发 sub_agent_waiting 事件，不阻塞前端输入区。
  • 子智能体自然的 assistant 输出结束（无 tool_calls）即本轮任务结束，进入 idle，上下文保留，不算 failed。
  • 不能把 output.success == null 直接判为 failed—_check_task_status() 对多智能体任务 status=running/idle 视为正常态（见 modules/sub_agent/state.py）。
  • idle 等待必须用 asyncio.Event，不能用 threading.Event，跨线程唤醒用 call_soon_threadsafe。
  • 任务记录里 multi_agent_mode 字段必须显式写入，缺失会导致传统后台通知池把多智能体任务当后台任务处理。reconcile_task_states() 已对旧任务补回。

11.3 消息池与派发链路（重点）

输出端 ↔ 接收端分离：

• 输出端（SubAgentTask._forward_output_to_master）：子智能体每次 assistant 文本输出都封为标准格式消息并 push_master_message 到会话的 MultiAgentState.pending_master_messages，不再做事。
• 接收端（MultiAgentState + dispatch）：根据主智能体当前状态选择插入方式：
  • 情况1（主运行中）：在 execute_tool_calls 末尾 process_multi_agent_master_messages(inline=True, after_tool_call_id=...) 插入到下一轮模型 messages 列表里（详见 server/chat_flow_tool_loop.py:1326）。
  • 情况2（主空闲）：poll_multi_agent_notifications spawn 出后台 poll，主对话空闲且 pool 有消息就 drain，调 _dispatch_multi_agent_idle_messages 创建 task_type="notice" 的后续 task，触发新一轮工作。
  • 情况3（主最后一轮无工具调用）：主循环 if not tool_calls: 分支调 process_multi_agent_master_messages(inline=False) 后 continue 继续迭代，Team Leader 在同 task 续跑处理子智能体输出。（实现上与情况2同路径，即情况3通过后续 task 完成情况2）。

情况2 硬约束（调试踩过坑）：

1. Pool 优先，不能等所有 running 退出再 drain：ask_master await 期间 status=running，但子智能体本身不会产生新输出，只有等主对话回答才能解套。pool 有消息就立即 drain，不管 running 状态。「对话处于运行状态」只决定前端显示态，不阻塞 pool 消费。
2. _dispatch_multi_agent_idle_messages 持久化不要重复：前置 N-1 条调 inject_multi_agent_master_message 绑定持久化。最后一条只 emit 给在线客户端、不持久化、在后续 task_manager.create_chat_task 走的 handle_task_with_sender 里才 add_conversation。否则历史里会有两条相同 user 消息，前端刷新会被渲染两遍（一条多智能体渲染、一条通知渲染）。
3. Metadata visibility 必须显式为 "chat"：_user_message_ui_defaults("sub_agent") 默认给 {visibility: "compact"}；在 _dispatch_multi_agent_idle_messages 构造 auto_user_message_payload时，如果有**ui_defaults，必须在它之后写 "visibility": "chat"（dict 字面量中后出现的key 胜出）。同样，在handle_task_with_sender处理多智能体消息时，user_message_metadata.update(multi_agent_meta)之后要显式user_message_metadata["visibility"] = "chat"。
4. 必须传 auto_message_type：前端 isMultiAgentMessage() 只看 auto_message_type.startsWith('multi_agent_')。auto_user_message_payload 和 preceding_user_notices[i].payload 都必须显式写 auto_message_type，字段不能用空值，否则前端 fallback 起通知渲染。

11.4 通知池轮询器完全独立

• 传统后台子智能体 / 后台 run_command 通知：poll_completion_notifications，在 handle_task_with_sender 结尾的 needs_completion_poll 。
• 多智能体通知：poll_multi_agent_notifications，在 needs_ma_poll。两者完全独立，避免 task_manager 单工作区互斥竞争。
• task_complete 事件中：
  • has_running_sub_agents 只算传统后台任务，不算多智能体。
  • has_running_multi_agent 多智能体专用字段，同时包含 running 实例和 pending master 消息（详见 server/chat_flow_task_main.py:2324）。前端通过该字段走独立的 startMultiAgentTaskProbe（不启动 sub_agent_waiting）。

11.5 渲染与前端约定

• 多智能体消息渲染条件是两个独立判断：
  • isMultiAgentMessage()：看 auto_message_type.startsWith('multi_agent_')。
  • getMessageVisibility()：看 metadata.visibility。两者都必须正确，消息才能走多智能体渲染分支。任一错都会 fallback 到通知渲染。
• 多智能体消息不显示新的 assistant 回复头部（Astrion/工作时间），即 metadata.starts_work=false。但前端通过 has_running_multi_agent 在 task_complete 中单独处理恢复轮询。
• 子智能体进度弹窗：输出与工具按真实时间线混排，默认 3 行，过长用省略号或内部滚动；颜色走 --text-primary 等语义 token。
• 全局工具规范统一适用于多智能体权限：UI 不能引入 compact 以外的 fallback 样式习惯复制到多智能体渲染。

11.6 工具结果格式化与前端渲染位置

新增多智能体工具时，必须同步补齐「后端结果格式化」和「前端结构化渲染」，否则前端会 fallback 到原始 JSON 或空白。

后端 formatter（主智能体工具）

• 实现位置：utils/tool_result_formatter/agent_context.py
• 注册位置：utils/tool_result_formatter/dispatch.py 的 TOOL_FORMATTERS
• 处理入口：所有主智能体工具执行结果，最终由 format_tool_result_for_context() 转换为自然语言摘要，写入对话历史。

后端 formatter（子智能体通信工具）

• 实现位置：modules/sub_agent/toolkit.py 的 _format_tool_result()
• 覆盖工具：ask_master / ask_other_agent / answer_other_agent / list_active_sub_agents
• 处理入口：子智能体 tool call 结果回填到子对话上下文前。

前端 renderer（主路径）

• 实现位置：static/src/components/chat/actions/toolRenderers.ts 的 renderEnhancedToolResult()
• 调用方：
  • static/src/components/chat/MinimalBlocks.vue
  • static/src/components/chat/StackedBlocks.vue
• 注意：这两个视图已移除 enhanced_tool_display 开关判断，所有工具块都强制走结构化渲染，不再显示原始 JSON。

前端 renderer（备用路径）

• 实现位置：static/src/components/chat/actions/ToolAction.vue 的 renderToolResult()
• 调用方：static/src/components/chat/ChatArea.vue
• 同样已移除原始 JSON fallback，仅作为 ChatArea 独立工具块渲染的备用。

新增工具 checklist

1. modules/multi_agent/tools.py 定义工具签名。
2. core/main_terminal_parts/tools_execution.py 实现工具 handler 并返回标准 dict（success + 业务字段 + 可选 error）。
3. utils/tool_result_formatter/agent_context.py 新增 _format_<tool_name>()，dispatch.py 注册。
4. static/src/components/chat/actions/toolRenderers.ts 新增对应 render<PascalCaseToolName>() 并在 renderEnhancedToolResult() 中分发。
5. 如果是子智能体通信工具，同步在 modules/sub_agent/toolkit.py 的 _format_tool_result() 中补 formatter。

11.7 调试机制

• 调试日志统一走 modules/multi_agent/debug_logger.py 的 ma_debug() 函数，写入 ~/.astrion/astrion/host/logs/multi_agent_loop.log。
• 关键状态转换点必须打 ma_debug，便于复现 bug：
  • handle_task_with_sender_start（含 pending_master_messages_count）
  • state_push_master_message （交出 queue_len_before）
  • poll_ma_tick （每 0.5s 一次，包含 instance_count / statuses / pending_count / main_active 的完整状态快照）
  • dispatch_ma_idle_enter / dispatch_ma_idle_before_create_task / dispatch_ma_idle_task_created / dispatch_ma_idle_sender_user_message / dispatch_ma_idle_exit_ok
  • create_chat_task 异常 / provide_answer 跨循环回写
  • runtime_injected 字段标记（metadata 里能区分多智能体 inline / idle / ask插入路径）

11.8 已知坑

• 多智能体模式下根本不 emit sub_agent_waiting 事件，避免前端进入「等待后台子智能体」的输入区阻塞态。
• _announced_sub_agent_tasks / notified 等标记仅适用于传统后台子智能体任务，多智能体任务不走这条通知路径。
• 多智能体任务的 output.json 中 status 在子智能体自然进入 idle 时会被写为 "idle"；在 _check_task_status 中由 _check_task_status_keep_alive 跳过防止错误判定为 failed。
• 传统后台通知池 _collect_pending_completion_notices 在 task.get("multi_agent_mode") 为真时跳过该 task；多智能体派出走独立的 poll_multi_agent_notifications 路径，不当混用。
• _has_pending_completion_work 主动排除 multi_agent_mode=True 的任务；两者永远独立。

11.9 对话切换与状态保留

• 切换会话不清理 _running_tasks 和 _sub_agent_instances。SubAgentManager 的全局 tasks 字典按 task_id 保持，多智能体状态由 conversation_id 在 get_multi_agent_state 中查。
• 子智能体对话存在 ~/.astrion/astrion/host/host/data/sub_agents/。重启后走 manager.restore_sub_agent 恢复实例引用。
• MultiAgentState 是进程级全局单例（2026-07 重构）：存放在 modules/multi_agent/state.py 的 GLOBAL_MULTI_AGENT_STATES（key=conversation_id），所有 SubAgentManager 实例共享；manager.multi_agent_states 只是该全局 dict 的引用。此前它是 manager 实例属性，对话级 terminal 缓存重建会产生多个 manager，各自的 _load_state 都从磁盘快照 from_snapshot 出一份独立副本，导致 terminate 只标记其中一份、前端轮询落到其他副本显示陈旧 idle。get_or_create / drop / _load_state restore 均通过 GLOBAL_MULTI_AGENT_STATES_LOCK（RLock）互斥。
• 进程重启后的状态校准（2026-07 新增）：_load_state 恢复 ma 快照后，会用任务记录（持久真相）校准实例终态——任务记录是 terminated/终态而快照里还是 idle 的，一律校准为终态；同处还有存量 _None 后缀显示名的自愈迁移（按「对话×角色×创建时间」重编号）。
• 显示名编号语义：显示名后缀（如 Full-Stack Engineer_1）是角色内编号，创建路径 tools_execution.py 中通过 peek_agent_id_for_role + commit_agent_id_for_role 两步走——先 peek 构造显示名，创建成功后才提交计数器，失败不消耗编号（避免跳号）；全局 agent_id 由 manager.next_free_agent_id() 自动分配（对话级最小空闲正整数），两者是两套独立命名空间，不得混用。

---

注：本节按「现有架构 + 多智能体分支」方案描述；如与代码冲突，以代码为准并同步修订本节。

---

12) 对话级主任务门闸与单写者不变量（2026-08-12）

事故背景：一个对话并发运行了两个主聊天任务（socketio 用户任务 + 完成通知轮询器派发的通知任务），交叉写入共享 conversation_history，产生 assistant→assistant→tool→tool 乱序段，最终 API 400 tool_call_id is not found、通知永久丢失。本节机制即为修复该事故引入。

12.1 单写者不变量（核心约束）

一个 WebTerminal（≈ 一个打开的对话）同一时刻只允许存在一个主聊天任务。 主任务包括：用户消息任务、后台完成通知派发任务、多智能体 idle 派发任务等一切会向 conversation_history 追加消息并请求模型的执行体。宁可拒绝/推迟新任务，也绝不并发写入。

12.2 门闸本体

• 实现：server/main_task_gate.py（进程内字典，key=terminal_id，value=token）。
• 获取/认领：acquire_or_claim_main_task_gate(terminal_id, owner_desc)——门闸空闲或持有者是同一任务时返回 token，否则返回 None。
• 释放：release_main_task_gate(terminal_id, token)，token 不匹配则拒绝（防止错误释放他人门闸）。

12.3 唯一入口与 token 移交

• 唯一入口：process_message_task（server/chat_flow.py）是所有主任务的门闸入口——进入即获取/认领门闸，拿不到则向用户发 error 并返回，绝不强行执行；finally 中释放。
• 通知链移交：完成通知轮询器在派发前先预占门闸（server/chat_flow_task_main.py），token 经 session_data["main_task_gate_token"] 移交 _run_chat_task → run_chat_task_sync → process_message_task（持 token 认领，不重复获取）；派发失败时释放门闸并回滚已打的通知标记（_rollback_completion_notice_marks）。
• 兜底释放：_run_chat_task（server/tasks/models.py）外层 finally 兜底释放，防止异常路径门闸泄漏。

12.4 改代码注意事项（硬性）

1. 新增任何主任务入口必须走门闸：不要绕过 process_message_task 直接驱动一轮模型对话；多智能体 idle 派发（task_type="notice"）目前依赖 _multi_agent_main_task_active 标志，后续应统一纳管。
2. 不要在 return 分支手写 _tool_loop_active 恢复：execute_tool_calls（server/chat_flow_tool_loop.py）已改为守护包装（try/finally 复位，内层 _execute_tool_calls_impl），新增提前返回路径无需也不应手动操作该标志——并发交错「存旧值→置True→恢复旧值」正是此前标志卡死的原因。
3. 不要依赖 build_messages 防御层掩盖并发问题：core/main_terminal_parts/context/messages.py 的孤儿 tool 消息剥离只是「坏数据不再 400」的止血层，乱序段本身意味着历史已被污染；发现剥离 warning 日志应按事故排查，而不是视为正常。