agent-Specialization/AGENTS.md

Repository Guidelines (Code-Verified)

Last verified against current codebase: 2026-05-15 Scope: /Users/jojo/Desktop/agents/正在修复中/agents

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

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

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

• 后端入口
  • main.py: 统一启动入口（当前默认走 Web 模式 + thinking_mode=True）
  • server/app.py: 推荐的 Web 服务入口（封装并转发到 server/app_legacy.py）
  • web_server.py: 兼容入口，已标记 deprecated，但仍可启动
• 后端核心目录
  • server/: Flask 业务主线（chat/task 以 REST 任务轮询为主，Socket.IO 主要用于兼容与实时辅助通道）
  • core/: 终端与工具编排（main_terminal.py、web_terminal.py、main_terminal_parts/*）
  • modules/: 可复用能力模块（terminal/file/memory/sub_agent/upload_security/user 等）
  • config/: 配置拆分（api.py, limits.py, terminal.py, paths.py ...），由 config/__init__.py 聚合并加载 .env
  • utils/: API client、日志、上下文与对话工具等公共函数
• 前端目录
  • 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 客户端工程
  • easyagent/: 子智能体执行逻辑所在目录（当前所有子智能体执行均走这里；旧版 sub_agent/ 已删除）
  • _experiments/: 本地实验残留与历史文档归档目录（不纳入 git，见 §7）

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

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

1.5.1 默认位置与模式分流

运行态根目录按运行模式自动分流（由 TERMINAL_SANDBOX_MODE 决定）：

• 宿主机模式（TERMINAL_SANDBOX_MODE=host）→ ~/.agents/host
• 其它模式（默认 docker / web）→ ~/.agents/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. 模式根目录环境变量：AGENTS_HOST_HOME 或 AGENTS_WEB_HOME（整体搬迁该模式下全部运行态数据）
3. 兜底默认：~/.agents/<mode>

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

注意：config/*.json（custom_models.json、host_workspaces.json、auto_approval.json 等）属于配置而非运行态数据，仍锚定源码树，不随运行态根目录迁移。prompts/、agentskills/ 同理。

1.5.3 日志策略（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.4 数据迁移

• 迁移脚本：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 unittest test.test_server_refactor_smoke
• 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.py 等后端接口适配，补充：
  • python3 -m py_compile server/chat.py
  • python -m unittest test.test_server_refactor_smoke

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) 风格与质量

• Python：4 空格、snake_case 函数、PascalCase 类，新增公共函数尽量补 type hints。
• Vue/TS：保持现有代码风格，不做无关风格清洗。
• CLI React/TS：保留现有 Ink 渲染方式与光标修正逻辑，不要轻易重写输入框定位策略。
• 日志：优先复用现有 logger/日志路径，不引入大量临时 print。
• 提交前至少做与改动相关的最小验证（命令输出或手工步骤要可复现）。
• 运行根目录前端构建时，默认使用 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 时必须遵守；遇到存量违规应在最小改动允许范围内顺手修正。 配色基础设施：三模式 CSS 变量定义在 static/src/styles/base/_tokens.scss（:root[data-theme='classic'|'light'|'dark']），切换逻辑见 static/src/utils/theme.ts。

1. 禁止边缘光晕：不使用任何 glow / 外发光 / 彩色光晕效果（大范围彩色 box-shadow 扩散、filter: drop-shadow 光圈、::before/::after 模糊光晕等）。已有的要移除。允许的只是中性、克制的投影——沿用 --claude-shadow / --theme-shadow-* 既有 token，不自造发光阴影。
2. 禁止原生浏览器组件：不直接使用浏览器默认外观的 <select>、<input type=checkbox/radio/range/date/color>、alert/confirm/prompt、原生右键菜单、原生 tooltip 等，一律换成与项目风格统一的自定义组件（下拉 / 开关 / 单选 / 滑块 / 模态 / Toast）。
3. 禁止圆角套娃：不允许「圆角矩形套圆角矩形套圆角矩形」的多层嵌套卡片——典型垃圾审美，且极大占据有效显示面积。容器层级要扁平，优先用分隔线 / 留白 / 底色区分，不要多包一层带边框圆角的盒子。
4. 图标外框对齐：同一组图标按钮的外框（点击热区 / 容器）必须统一对齐，不能一会居中、一会左对齐、一会右对齐；同组固定相同尺寸与对齐方式。
5. 图标视觉对齐而非理论对齐：按图标视觉重心对齐而非几何边界盒；对重心偏移的图标（三角形 / 播放键 / 放大镜等）做微调，使其「看起来居中」。
6. 颜色遵循三模式切换：所有颜色走原生三模式（经典 classic / 明亮 light / 夜间 dark），禁止写死颜色字面量，一律用 CSS 变量（--claude-* / --theme-*）。新增颜色必须在三套主题里都补齐。
7. 带文字容器固定高度：所有含内部文字的选项 / 按钮 / 标签 / 容器固定高度，禁止因文字多少被撑大撑高；过长文字用省略号或内部滚动处理。
8. 窗口设最大尺寸 + 内部滚动：所有弹窗 / 面板 / 列表设置 max-height / max-width，超出由内部容器滚动，不顶大整个窗口；滚动条要么隐藏，要么做样式适配，不暴露原生粗滚动条。

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 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、用户隐私）。
• 运行态数据默认在 ~/.agents/<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 /Users/jojo/Desktop/agents/正在修复中/agents/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 可调用，但在只读沙箱执行；写入由系统拒绝
  • write_file / edit_file 等写入类工具直接拒绝
• approval
  • run_command 先走只读沙箱
  • 若出现权限拒绝（例如 Operation not permitted / Permission denied），触发前端审批
  • 审批通过后，仅该次命令以可写沙箱重试；工具结果返回“重试后的最终结果”
• auto_approval
  • write_file / edit_file：工作区内路径直接执行，工作区外路径进入审批流程
  • run_command 先走只读沙箱；触发权限拒绝后由后台审批智能体自动审核
  • 自动审核拒绝时，工具返回“被拒绝+理由”并继续主循环（不强制结束任务）
• unrestricted
  • 不做权限模式拦截；是否沙箱由执行环境决定

10.2 执行环境

• sandbox（默认）：使用 OS 沙箱执行（macOS: sandbox-exec，Linux: bwrap + seccomp，Windows: WSL2）
• direct：宿主机直接执行（高风险，仅建议短时使用）
• 宿主机下支持会话级 TTL 自动回退 direct -> sandbox

10.3 路径授权语义

• 前端“路径授权”支持两类路径：
  • 可读可写
  • 仅可读
• 语义：
  • 可读集合 = 可读可写 + 仅可读
  • 可写集合 = 可读可写

10.4 维护约束

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

10.5 自动审批智能体配置与调试

• 自动审批配置文件：config/auto_approval.json
  • 建议字段：name / url / key / model / extra_params
  • 额外控制：timeout_seconds / max_rounds / max_command_timeout
• 调试开关（代码变量）：modules/approval_agent.py 中 DEBUG_SAVE_APPROVAL_AGENT_TRANSCRIPT
  • 开启后写入：logs/approval_agent/
  • 记录以累积 messages 为主，便于对齐主/子智能体会话格式