JOJO
8d665ad6de
Implemented a new permission mode between and , including backend policy, runtime behavior, frontend display, and documentation updates. Backend & policy changes: - Added to permission mode validation and persistence paths. - Updated tool permission evaluation: workspace-local direct pass, out-of-workspace requires approval. - Kept readonly-first flow and added auto-approval decision path when permission denial occurs. - Added approval reason/decider support in tool approval manager. - Improved rejection tool-content format to natural language: '工具调用被拒绝\n原因：...' - Fixed permission-mode sync edge cases on conversation create/load and restart-first-switch behavior. Approval agent subsystem: - Added and . - Added lightweight auto-approval config at (name/url/key/model/extra_params + timeouts). - Added optional transcript debug switch in code and transcript output under logs/approval_agent. - Aligned transcript saving toward cumulative messages format and captured reasoning/content/tool_calls/tool sequence. Frontend changes: - Added option to personalization and permission menus. - Reworked approval panel auto-review display into a dedicated block with simplified lines: start, command, final approve/reject + reason. - Added delayed sidebar auto-close (10s) after approval resolved. - Added stricter permission-switch verification and rollback on mismatch/error. Docs updated: - Synced AGENTS.md, README.md, and docs/host_sandbox_and_permission_model.md with new permission mode, approval-agent behavior, config, and current constraints (including docker caveat).
211 lines
9.4 KiB
Markdown
211 lines
9.4 KiB
Markdown
# Repository Guidelines (Code-Verified)
|
||
|
||
> Last verified against current codebase: 2026-05-11
|
||
> 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 前端
|
||
- 监控动画相关核心文件：
|
||
- `static/src/components/chat/monitor/MonitorDirector.ts`
|
||
- `static/src/stores/monitor.ts`
|
||
- `static/src/components/chat/monitor/*`
|
||
- **其他子项目/资源**
|
||
- `android-webview-app/`: Android WebView 客户端工程
|
||
- `easyagent/`: 独立前端子目录（与根目录前端并存）
|
||
|
||
## 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`
|
||
- 开发监听（当前脚本是 build watch）：`npm run dev`
|
||
- Lint：`npm run lint`
|
||
|
||
## 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` 作为唯一入口。
|
||
|
||
## 4) 代码修改约定（实用版）
|
||
|
||
- **最小改动原则**：只改与需求直接相关文件，避免顺手重构。
|
||
- **后端改动优先级**：先改 `modules/`、`server/` 内对应模块，最后才动入口。
|
||
- **前端改动优先级**：按 `static/src` 现有分层改（`app/`、`stores/`、`components/`、`composables/`）。
|
||
- 涉及 monitor 动画/事件联动时，至少同步检查：
|
||
- `MonitorDirector.ts`（动画与场景执行）
|
||
- `stores/monitor.ts`（事件队列与状态机）
|
||
|
||
## 5) 风格与质量
|
||
|
||
- Python：4 空格、`snake_case` 函数、`PascalCase` 类，新增公共函数尽量补 type hints。
|
||
- Vue/TS：保持现有代码风格，不做无关风格清洗。
|
||
- 日志：优先复用现有 logger/日志路径，不引入大量临时 `print`。
|
||
- 提交前至少做与改动相关的最小验证（命令输出或手工步骤要可复现）。
|
||
|
||
## 6) Git 工作流（开发 + Review）
|
||
|
||
### 6.1 核心原则
|
||
|
||
- **永远不直接在 `main` 上开发**。所有改动走功能分支，合入时 Squash Merge。
|
||
- 每个功能分支合入 main 后，main 上对应一个 commit（一个功能 = 一个 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
|
||
git checkout -b feature/<简短描述> main
|
||
|
||
2. 开发并提交
|
||
git add <修改的文件>
|
||
git commit -m "feat(scope): 简短描述"
|
||
（多轮迭代可用 git commit --amend 保持一个 commit）
|
||
|
||
3. 推送到远程（备份 + 方便切设备）
|
||
git push origin feature/<分支名>
|
||
|
||
4. Squash Merge 到 main
|
||
git checkout main && git pull origin main
|
||
git merge --squash feature/<分支名>
|
||
git commit -m "feat(scope): 简短描述"
|
||
git push origin main
|
||
|
||
5. 清理
|
||
git branch -D feature/<分支名>
|
||
git push origin --delete feature/<分支名>
|
||
```
|
||
|
||
**重要约束**：
|
||
- AI 必须在本地验证修改能正常运行，再建议用户提交。
|
||
- 修改完成后主动告知：修改了哪些文件、核心变更点、验证结果。
|
||
- 禁止 AI 在未经用户确认的情况下执行 `git push`。
|
||
- 如需 Review，在同一对话内直接 `git diff main...feature/<分支>` 即可，不必跨对话。
|
||
|
||
### 6.3 常用命令速查
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 切功能分支 | `git checkout -b feature/<名称> main` |
|
||
| 暂存未完成工作 | `git stash push -m "WIP: xxx"` |
|
||
| 修改最近 commit | `git commit --amend` |
|
||
| Squash Merge | `git merge --squash feature/<名称>` |
|
||
| 强制删除本地分支 | `git branch -D feature/<名称>` |
|
||
| 删除远程分支 | `git push origin --delete feature/<名称>` |
|
||
| 同对话内 Review diff | `git diff main...feature/<名称>` |
|
||
| 查看提交历史 | `git log --oneline -10` |
|
||
|
||
## 7) 安全与仓库卫生
|
||
|
||
- 严禁提交真实密钥（`.env`、token、cookie、用户隐私）。
|
||
- `logs/`, `data/`, `users/`, `project/` 为运行态目录（见 `.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 的硬性要求
|
||
|
||
- 先读当前代码再执行，不依赖历史文档记忆。
|
||
- 输出结果必须带：
|
||
1. 修改文件列表
|
||
2. 核心变更点
|
||
3. 验证结果（已执行命令/未执行原因）
|
||
- 如果发现本文档过时，直接更新 `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` 为主，便于对齐主/子智能体会话格式
|