JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
feature/workspace-conversations
agent-Specialization/AGENTS.md
JOJO cc9df7959a feat(cli): 新增 React/Ink CLI 端，修复全屏布局与光标定位 
## 新增：基于 React/Ink 的 CLI 终端（cli/）

使用 Ink 框架构建完整的终端 UI，取代原有的纯 print 交互方式：

- App.tsx：主应用组件，管理对话状态、任务轮询、键盘输入、slash 命令
- components.tsx：Timeline、Composer、StatusLine、Picker、SlashMenu 等全部 UI 组件
- eventMapper.ts：将后端 SSE 事件流映射为 Timeline 条目，支持 thinking/tool/assistant/sub_agent 等类型
- api.ts：封装所有后端 REST 接口（任务、对话、模型、权限、工作区等）
- commands.ts：slash 命令定义（/new /resume /model /permission /execution /workspace /compact /tools 等）
- workspaces.ts：本地工作区目录的持久化管理
- types.ts：所有共享类型定义
- format.ts：context 格式化、路径缩写等工具函数

## 重大修复：去除固定高度全屏模式，恢复滚轮滚动

**问题根因**：根 Box 设置了 `height={stdout.rows}` 使 Ink 进入原地重绘模式
（类似 vim/htop），所有内容在同一块屏幕区域反复擦写，永远不会真正
"滚出"屏幕顶部，导致 terminal 的 scrollback buffer 始终为空，鼠标
滚轮无任何响应。

**修复方案**：
- 移除根 Box 的 `height` 约束和 `overflow="hidden"`
- 移除内层 Box 的 `flexGrow`/`justifyContent="flex-end"` 全屏布局
- Timeline 不再做行数截断，直接渲染全部条目
- 内容自然流入 terminal scrollback buffer，鼠标滚轮恢复正常

**同步清理**：删除 `getTimelineMaxRows`、`estimateTimelineRows`、
`scrollOffset` 状态及方向键滚动逻辑（这些都是全屏模式下的补丁，
去除固定高度后不再需要）

## 修复：Composer 光标位置偏移一行

`setCursorPosition` 中 y 轴使用 `lines.length` 导致单行时偏移 +1。
改为 `lines.length - 1`，与实际最后一行渲染位置对齐。

## 其他

- AGENTS.md / README.md：补充 CLI 启动方式与架构说明
- server/chat.py：补充任务轮询接口所需字段
- package.json：新增 cli 相关脚本入口
- docs/cli_slash_commands_spec.md、docs/cli_ui_display_spec.md：CLI 设计文档

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-16 01:06:51 +08:00

238 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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/`: 独立前端子目录（与根目录前端并存）
## 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`
### 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) 代码修改约定（实用版）
- **最小改动原则**：只改与需求直接相关文件，避免顺手重构。
- **后端改动优先级**：先改 `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`。
- 提交前至少做与改动相关的最小验证（命令输出或手工步骤要可复现）。
### CLI 当前交互约束（2026-05-15）
- CLI 连接的是现有本地 Web API（默认 `127.0.0.1:8091`），不是独立 agent runtime。
- 启动 CLI 时应清屏、连接本地服务、创建新会话，并将输入区固定在底部。
- 当前目录若不在工作区中，应先弹出“是否添加到工作区”的选择。
- 思考内容当前默认隐藏，只显示“思考中 / 思考完成”标题；相关折叠代码保留，后续可继续修。
- 不要在未获得用户要求的情况下运行交互式 TUI 压测或长时间模拟输入，以免刷屏占满上下文。
## 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` 为主，便于对齐主/子智能体会话格式
Reference in New Issue View Git Blame Copy Permalink