11 KiB
11 KiB
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聚合并加载.envutils/: API client、日志、上下文与对话工具等公共函数
- 前端目录
static/src/: Vue 3 + TS 前端cli/src/: React 19 + Ink 6 + TypeScript CLI 前端（正在重写中）- 监控动画相关核心文件：
static/src/components/chat/monitor/MonitorDirector.tsstatic/src/stores/monitor.tsstatic/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 --silent（默认使用 silent，减少无关输出） - 开发监听（当前脚本是 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 typechecknpm --prefix cli run build
- 若改动
server/chat.py等后端接口适配，补充：python3 -m py_compile server/chat.pypython -m unittest test.test_server_refactor_smoke
4) 代码修改约定（实用版）
- 最小改动原则：只改与需求直接相关文件，避免顺手重构。
- 文件编辑方式：修改文件时优先使用
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。
CLI 当前交互约束（2026-05-15）
- CLI 连接的是现有本地 Web API（默认
127.0.0.1:8091），不是独立 agent runtime。 - 启动 CLI 时应清屏、连接本地服务、创建新会话，并将输入区固定在底部。
- 当前目录若不在工作区中，应先弹出“是否添加到工作区”的选择。
- 思考内容当前默认隐藏，只显示“思考中 / 思考完成”标题；相关折叠代码保留，后续可继续修。
- 不要在未获得用户要求的情况下运行交互式 TUI 压测或长时间模拟输入，以免刷屏占满上下文。
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。 - 如需 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、用户隐私）。 logs/,data/,users/,project/为运行态目录（见.gitignore），分享前需脱敏。- 不要把本地构建产物（如
static/dist/、node_modules/）纳入提交。
8) Android App 发布联动要求（重要）
当修改前端并需要发布 Android WebView App 时，必须同步执行以下步骤（依据 doc/android_app_release_and_update.md）：
- 同时更新版本信息
android-webview-app/app/build.gradle.kts：递增versionCode，更新versionName
- 同时更新更新说明
android-webview-app/APP_CHANGELOG.md：在顶部新增当前版本说明
- 完成修改后提醒用户运行上传脚本
- 在发布流程中运行：
bash /Users/jojo/Desktop/agents/正在修复中/agents/upload_android_apk.sh
- 在发布流程中运行：
禁止只改前端代码而不更新版本号/更新说明，否则会导致客户端更新提示与分发信息不一致。
9) 给 Agent 的硬性要求
- 先读当前代码再执行，不依赖历史文档记忆。
- 输出结果必须带：
- 修改文件列表
- 核心变更点
- 验证结果（已执行命令/未执行原因）
- 如果发现本文档过时，直接更新
AGENTS.md并在结果中说明依据。
10) 宿主机权限模式与沙箱执行机制（2026-05 更新）
完整说明文档：docs/host_sandbox_and_permission_model.md
为避免误解，当前系统有两套独立但叠加的控制：
- 权限模式（Permission Mode）：
readonly/approval/auto_approval/unrestricted - 执行环境（Execution Mode）：
sandbox/direct（仅宿主机模式可切换）
10.1 权限模式
readonlyrun_command可调用，但在只读沙箱执行；写入由系统拒绝write_file/edit_file等写入类工具直接拒绝
approvalrun_command先走只读沙箱- 若出现权限拒绝（例如
Operation not permitted/Permission denied），触发前端审批 - 审批通过后，仅该次命令以可写沙箱重试；工具结果返回“重试后的最终结果”
auto_approvalwrite_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为主，便于对齐主/子智能体会话格式
- 开启后写入：