AGENTS.md

1> 本文件是规则唯一源头。其他工具配置文件（CLAUDE.md、GEMINI.md 等）由 `python scripts/sync_rules.py` 从本文件同步生成，请勿直接编辑它们。
2 
3# Project Rules & Safety Protocol
4 
5## 1. Workflow & Communication (工作流与沟通)
6- Start replies directly with the answer or code. Drop all filler phrases like "好的"、"没问题"、"当然可以"、"我将为您...".
7- When requirements are ambiguous or information is missing, stop immediately and ask the user rather than filling in assumptions.
8- 回复必须精炼，使用中文。代码注释必须使用中文，且只写"为什么这么写"，聚焦于原因而非描述代码功能。
9- 每次任务前先读取本文件及所有 `@docs/prompts/*.md` 引用文件。
10- 先规划、后实现；没有确认的需求不脑补代码。
11- 联网优先于内部知识，尤其版本和新 API。
12- 有成熟库必须用库，prefer using established libraries over hand-rolling low-level logic.
13 
14## 2. Anti-AI-Flavor (去AI味铁律)
15- 文本侧：拒绝机械化的总分总结构（如"首先...其次...最后..."）。直接输出结论或代码，不要做无意义的铺垫。
16- 代码侧：
17  - Write defensive code only where the requirement or risk profile justifies it (e.g., add try-except only when an operation can genuinely fail in ways the caller must handle).
18  - Keep abstraction proportional to reuse: inline single-use logic rather than wrapping it in a class.
19  - Write comments that explain "why", not "what"; skip comments that restate the code (e.g., `# 初始化变量 i = 0`).
20  - Add only the security checks, CORS handling, and logging the user explicitly requests.
21 
22## 3. Change Scope & File Safety (变更范围与文件安全)
23- 最小变更原则：Scope changes to the file the user specified; modifying any other file requires explicit permission first.
24- 顺手优化限制：Defer opportunistic optimizations to the next round — list them as "⚠️ 待办建议:" at the end of the reply after the current task completes.
25- 大文件备份：在重写或大幅修改超过 100 行的文件前，必须先在终端执行 `cp <file> <file>.bak` 创建本地备份，或提醒用户先执行 `git commit`。
26- Use precise line-number or function-level replacement for large files; reserve full rewrites for cases with explicit user approval.
27 
28## 协作规则与项目隔离 (Collaboration Rule Isolation)
29- 本文件及其引用的 `docs/prompts/*.md` 仅定义 AI 与用户的协作规则，不属于任何具体开发项目的业务代码、配置或交付物。
30- Keep rule files separate from project files: modify `AGENTS.md`, `docs/prompts/`, or `docs/skills/` only when the user explicitly asks for a rule change.
31- 执行具体项目任务前，先确认项目根目录；项目代码、依赖文件、环境文件、测试结果和 Git 操作仅在该项目根目录内进行。
32- Keep collaboration rules in the rule directory and project artifacts in the project directory: copy rules into project dirs only on explicit request, and keep project dependencies, env files, configs, build outputs, and Git state out of the rule directory.
33- 同一会话涉及多个项目时，必须按项目根目录分别处理上下文、命令和变更；modify a file only after confirming which project it belongs to.
34- 项目局部规则与本文件冲突时，本文件的安全、范围和协作约束优先；其余不冲突的项目规则仅在对应项目内生效。
35- 仅在用户明确提出"完善规则""修改协作规范"或指定规则文件时，才允许修改本规则体系；修改后仅汇报规则变更，不将其计入项目开发变更。
36 
37## 4. Debugging & Error Handling (防死循环与求助机制)
38- 失败熔断：修复同一个 Bug 连续失败 2 次，或终端请求连续失败 3 次，必须立刻停止所有代码修改操作。
39- 停止后动作：After stopping, output a fault report (current error, attempted solutions, suspected root cause) and explicitly request human takeover. Drive the next step from the report rather than blind trial-and-error.
40- 远程沙箱工程规范：在远程沙箱/CI 环境开发时必须查阅 @docs/skills/remote-sandbox-sop.md（工作目录选择、push 时机、命令输出可见性、subagent 拆分等通用教训）。
41- 平台专属护栏：检测到 Trae 沙箱环境（见 `adapters/trae/session-guardrails.md` §0 检测条件）时，额外应用 `adapters/trae/session-guardrails.md` 的 Trae 专属条款。
42 
43## 5. Security & Secrets (安全与保密)
44- API Keys, passwords, tokens, and database connection strings must be read from `os.getenv()` or `python-dotenv`, never hardcoded in source.
45- 必须使用 `os.getenv()` 或 `python-dotenv` 读取环境变量。
46- 提供代码后，必须主动检查是否有敏感信息泄露，确保敏感数据已替换为占位符（如 `<YOUR_API_KEY>`）。
47- Add `.env` to `.gitignore` and keep it out of all Git commits.
48- **MCP 红线（最高优先级）**：MCP is a long-running background service involving env vars, ports, and permissions. MCP download, installation, startup, and configuration must be performed by the user in each AI tool's MCP settings (Trae / Claude Desktop / Cursor / VS Code, etc.); the AI may only output install commands and config JSON for the user to review and paste.
49 
50## 6. Engineering Hygiene (工程卫生)
51- When pulling external templates or dependencies, exclude the source repository's `.git` directory from the current project.
52- Include only explicitly requested files; keep unrelated files (LICENSE, README, `.github`, etc.) out unless the user explicitly asks for them.
53- 每次操作完成后，必须清理临时文件（如 zip 压缩包、临时脚本、`.bak` 备份文件）。
54- 提交代码前，必须执行 `git status` 检查是否有冗余或意外的未追踪文件。
55 
56## 7. Shell & Git Constraints (Windows/PowerShell 环境)
57- OS: Windows。必须使用 PowerShell 语法（`Remove-Item` 代替 `rm`，`$env:VAR` 代替 `$VAR`）。Use Windows PowerShell conventions exclusively.
58- Git 操作前必须查阅: @docs/skills/git-sop.md
59- 提交前必须 `git status` + `git diff`。
60- Wait for explicit user confirmation before any `git push`. Reserve `git push -f` for cases with explicit user approval. Stage files with targeted `git add <path>` rather than blanket `git add .`.
61 
62## 8. Skill Acquisition (技能获取协议)
63- 基础功能必须优先使用 `pip install`。
64- 复杂脚本/工具必须查阅授权白名单: @docs/skills/registry.md
65- 若需从 GitHub 下载脚本，必须先展示 URL 和 Star 数，经用户同意后下载至临时目录，审查后使用。
66- 获取层级（标准库 → 包管理器 → 本地注册表 → 优先厂商官方仓库 → 受限自主搜索）：详见 @docs/skills/registry.md。
67- **MCP 不在技能获取范围内**（见 §5 红线）。
68 
69## 意图识别与澄清协议 (Intent Recognition & Clarification)
70- 用户（尤其口语化、不规范）提示词须先归一化为稳定意图：明确【动作 + 目标 + 约束 + 范围】，normalize colloquial prompts into a stable intent before executing them as instructions.
71- 意图稳定：同一含义的不同表述必须映射到一致的意图表示，不因措辞变化漂移；涉及仓库铁律的高风险动作（git push / force / 删远程 / 改可见性）须显式映射到明确定义的安全动作，map high-risk actions to well-defined safe actions rather than guessing.
72- Ask when uncertain: when any key element is missing, a reference is unclear, or an outcome could be destructive (auto push, force, delete remote), use AskUserQuestion to clarify rather than assuming a default. Keep questions minimal, specific, and free of repeats.
73- 澄清优先于动手：未澄清前不执行任何有副作用的操作。
74 
75## Tool / Skill / MCP 管理策略
76- **Tool（内置工具）= 手和脚**：Terminal、文件读写等内置工具开箱即用，Skill 的落地必须靠它们。
77- **Skill（说明书）= 菜谱**：`docs/skills/` 下的文本/脚本教 AI 怎么做复杂事。AI 按需读取，不自动执行未知脚本。`docs/skills/` 现含：`registry.md`(工具白名单)、`git-sop.md`(Git 规范)、`powershell-tips.md`(PowerShell 要点)、`mcp-registry.md`(MCP 清单)、`tool-skill-mcp.md`(三者关系与落地结构)。
78- **MCP（外部直连通道）= 输血管**：高频对接外部系统（数据库、GitHub API、Notion）强烈建议配 MCP，比 AI 拼命令行更安全稳定；但配置权在你手里。
79- 允许的 MCP 服务清单与配置说明见 @docs/skills/mcp-registry.md（仅参考，手动配置）。
80- 三者关系与落地结构详解见 @docs/skills/tool-skill-mcp.md。
81 
82## Default Tool Sources & Deep Search Protocol
83 
84### Default Tool Sources
85 
86All profiles in this repository share the following default tool sources. These are pre-configured and should be used unless the user explicitly overrides them.
87 
88| Tool Category | Default Source | Address | Notes |
89|---|---|---|---|
90| Browser | Bing | https://www.bing.com | Default search engine for all profiles |
91| Package Registry (Python) | PyPI | https://pypi.org | Python package index |
92| Package Registry (Node.js) | npm | https://www.npmjs.com | Node.js package registry |
93| Code Repository | GitHub | https://github.com | Code hosting, issue tracking, CI/CD |
94| Q&A | Stack Overflow | https://stackoverflow.com | Programming Q&A community |
95| Web Docs | MDN Web Docs | https://developer.mozilla.org | HTML, CSS, JavaScript, Web API |
96| API Reference | DevDocs | https://devdocs.io | Consolidated API documentation |
97| Vulnerability DB | CVE Details | https://www.cvedetails.com | Security vulnerability lookup |
98| Dependency Security | Snyk DB | https://security.snyk.io | Dependency vulnerability database |
99| Python Docs | python.org | https://docs.python.org | Official Python documentation |
100 
101### Deep Search Protocol (Default for All Profiles)
102 
103When the user's task requires factual support, dependency verification, or error diagnosis, the deep search protocol is activated by default:
104 
1051. **Query**: Formulate search terms based on the user's question.
1062. **Search**: Query multiple sources (Bing, GitHub, Stack Overflow, official documentation).
1073. **Cross-validate**: Key claims require 2+ independent sources.
1084. **Synthesize**: Extract and integrate findings; flag conflicts.
109 
110> When uncertain, searching beats guessing. Do not fabricate APIs, libraries, or version numbers.
111 
112## Tech Stack & Commands (技术栈与命令)
113- Primary: Python 3.12+ (async/await + type hints by default)
114- Frameworks: FastAPI, Pydantic (按实际改)
115- 安装依赖：`pip install -r requirements.txt`
116- 运行测试：`pytest`
117- 代码检查：`ruff check .`
118- 类型检查：`mypy .`
119- 写代码前先 `pip list` 查已装包，避免重复安装。
120- 优先 httpx 而非 requests，优先 pendulum 而非 datetime。
121 
122## References
123- 智能体提示词: @docs/prompts/system-prompt.md
124- 架构师角色: @docs/prompts/architect-subagent.md
125- 工程师角色: @docs/prompts/engineer-subagent.md
126- 审查官角色: @docs/prompts/critic-subagent.md
127- 验证员角色: @docs/prompts/verifier-subagent.md
128- 交付角色: @docs/prompts/final-subagent.md
129- 技能注册表: @docs/skills/registry.md
130- 远程沙箱工程规范: @docs/skills/remote-sandbox-sop.md
131- Trae 平台专属护栏（条件激活）: `adapters/trae/session-guardrails.md`
132