AGENTS.md · diff
git:20261109.2bf8c5a to git:20261110.6316d28
1 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# Hotline Agent 持久协作规则
本规则适用于 `F:\Hotline` 及其全部子目录。用户要求:任何时候都不得上传 `.env`、真实密钥或包含其真实服务地址的文件。
## 项目结构与目录管理
- 所有开发者和 Agent 开始开发前,必须阅读并遵循本文件;子目录另有说明文件时一并遵循。子目录规则不得放宽本文件中的私密信息保护要求。
- **本仓库是单一项目 Hotline Agent**:Vue 前端(`frontend/`)、FastAPI 后端(`python_backend/`)、技能中心(`python_backend/skill_center.py` 与 `skill-center/`)、静态资源与技能控制台(`static/`)、部署脚本(`deploy/`)、文档(`docs/`)同仓维护,不再有平台与项目之分。
- 修改默认限于对应子目录;涉及跨目录的公共改动(如 `.env.example`、`AGENTS.md`、根启动脚本)需在提交说明中写清影响范围。
- 项目元数据保留在 `project.yaml`,README 说明用途、当前状态、安装、启动、验证命令及配置项。
- - 根目录 `README.md` 是仓库唯一项目说明文件;不要在子目录新增 README。模块说明、迁移边界和当前状态统一写入根 README 或本文件。
+ - 根目录 `README.md` 是仓库主项目说明文件;不要在子目录新增 README。模块说明、迁移边界和当前状态统一写入根 README 或本文件。根目录另有 `README.v2.md`,是 2026-11-10 按代码实况重写的并行稿(华化排版版),在用户明确决定替换前与 `README.md` 并存,不要当成冗余文件删除。
- 根目录 `DESIGN.md` 是前端视觉唯一事实源;不要在 `frontend/` 或模块目录维护第二份设计锚。
- `python_backend/modules/` 与 `frontend/src/modules/` 是能力边界目录。新增模块先建立接口与验证,再迁移旧实现;模块之间不得直接读取彼此的数据库细节。
- 模块命名保持前后端对应:`memory`、`retrieval`、`storage`、`context_engineering`、`skills`、`mcp`、`execution`、`workspaces`、`artifacts`、`intent`;`execution` 统一承载脚本、EXE 和后台任务执行能力;`intent` 统一承载意图目录与意图分类(关键词粗筛 → embedding 向量召回 → 大模型判定的三级级联,含置信度分级);配置决策模型后该层改走 System One 协议(`modules/intent/decision.py`,阿里云百炼 decision-model-preview,与 TypeSafe Jev 同接口),一次前向同时给出意图与诉求歧义度,门闸按歧义度判断是否澄清;置信度不足时由门闸转成需求澄清,用户作答后作为新一轮对话重新进入级联。
- 运行数据及生成文件统一保存在被 Git 忽略的 `data/` 目录;真实配置遵循下方私密信息规则。
- 不擅自创建嵌套 Git 仓库或子模块。历史嵌套仓库 `projects/ai/dodo-agent` 已并入本仓库,其提交历史备份在 `data/dodo-agent-history.bundle`(Git 忽略,仅供恢复参考)。
- 交付前执行验证命令:`python -m compileall python_backend`、`python skill-center/test_center.py`、`npm --prefix frontend run build`(改动前端时)。文档修改仅核对与现有目录和命令的一致性。未经明确要求,不移动或重构现有目录结构。
- 本机没有可用的 MySQL,`import python_backend.fastapi_app` 会在 `PgVectorStore` 连接处抛 `Access denied`,所以整包导入失败不代表代码有问题。要验证路由与接口,用临时目录里的 store 单独装配 `api/routers/*` 的工厂函数(`create_*_router`)再打请求;测试用 `F:\Hotline\.venv\Scripts\python.exe` 运行。
- 本机 8888 后端由两个进程组成:网关 `python -m uvicorn main:app --host 127.0.0.1 --port 8888` 与执行 Worker `python -m python_backend.modules.execution.worker`。只起网关时 `/agent/*/stream` 返回 503(Worker 未运行),`/health/ready` 会显示 `executionWorker: unavailable`。
## 禁止外传的内容
- `.env`、`.env.*`、`*.env`,以及它们的备份、导出、压缩包和副本。只有已确认完全脱敏的 `.env.example` / `.env.sample` 可提交。
- 用户的真实服务地址(公网或内网 IP、域名、端口、连接字符串、部署地址)、API Key、密码、令牌、私钥和其他凭据,无论出现在哪种文件中。普通源码、文档、日志、截图或技能样本夹带这些信息也不得上传。
- 禁止通过 Git 暂存、提交、推送、PR 附件、发布产物或外部服务上传上述文件或内容;不得在消息、日志或工具输出中展示敏感值。
## 工作方式
- 本地运行可以使用私密配置,但必须留在本地;对外示例使用明确占位符。本地回环地址和公开第三方文档链接不属于用户私密服务地址。
- 新增包含真实服务地址的配置,保存为 `*.local.*`、`*.private.*`,或放入 `private/`、`secrets/` 目录,并确认 Git 忽略。不要把真实配置复制进可提交文件。
- 暂存和提交前,检查文件清单及敏感内容;不盲目执行 `git add .` / `git add -A`,不得使用 `git add -f` 绕过私密文件的忽略规则。发现敏感信息时先脱敏或将文件排除,再继续。
- 上传或推送前检查待发布内容及待推送提交历史;发现密钥或真实服务地址时停止该次上传,处理泄露来源。不能通过 GitHub 解除密钥拦截来绕过本规则。
- `.gitignore` 不会自动移除已跟踪文件,也不会清理历史提交。取消跟踪时保留本地文件;清理历史涉及改写提交,须有用户明确授权,不擅自改写或强推。
- 后续修改配置、文档、构建或发布流程时,始终保留本规则及忽略规则。
- 协作开发使用独立分支;代码或文档先提交到个人分支,合并到主分支时再处理冲突。
## 文档维护规则
- 文档必须描述当前代码和可验证命令;历史方案、已废弃技术栈和未实现能力不得继续作为现状说明。
- 规划内容只保留在根 README 的规划小节或明确标注为草案的文档中;功能完成后及时删除过时规划,避免与代码重复描述。
- 修改文档后至少核对路径、启动命令、端口、模块名称和验证命令;不复制 `.env`、真实服务地址或运行数据到文档。