Agent Lab Notes
知识库智能体
浏览文档与本页目录

本页目录

全局指令

语言设置

所有 Agent 必须使用中文回答所有问题和回复。

  • 所有交互和响应必须使用中文。
  • 不允许使用英文回复（除非引用代码或技术术语）。
  • 保持中文表达准确、专业、简洁。

Python 环境设置

所有 Agent 使用 Python 环境时必须遵守以下规则。

1 运行前基础检查

  • 当需要运行 Python 时，先检查 uv 命令是否可用
  • 如果基础条件不满足，先向用户说明问题并给出可选处理方案，再继续执行。

2 默认环境与优先级

  • 当项目根目录存在 .venv 时，优先使用 uv 生成的 .venv 环境
  • 若项目尚未 uv 初始化，在项目目录用 uv 创建隔离环境，标准流程（在项目路径下）：
    • uv init
    • uv venv --python 3.xx
    • 在 .venv 中安装运行项目所需依赖
    • 确保环境的可迁移复现，安装包和运行使用以下流程
      • uv add --no-sync <packages>
      • uv lock
      • uv sync --frozen
      • uv run python main.py
      • 特殊情况下，如果安装未能将声明，锁文件，环境三者同步，必须向用户说明原因并写入 README.md

3 安装 Python 包的源配置

  • uv 默认不需要额外传 --index-url（已在 uv.toml 配置清华源和相关设置）

4 Python 环境安装与包更改必须用户确认

  • 所有涉及 Python 环境安装和包更改的操作必须先获得用户明确确认，包括但不限于：pip install、uv add、uv tool install、uv pip install 等
  • 执行前必须向用户说明：要安装什么、为什么需要、安装到哪里，等待用户确认后再执行
  • 此规则优先级高于任何 SKILL.md 模板中的自动安装步骤

Git 管理规范

  • 操作前必 commit：AI 操作前保存当前状态；每完成一个 AI 交互周期且结果可用时 commit
  • 分支隔离：高风险改动使用 git checkout -b ai-experiment
  • 回滚审慎：优先 git revert；git reset --hard 需用户明确同意
  • 推送需授权：git push 和 git remote add 仅在用户明确要求时执行
  • 失败止损：连续 3 次修复失败时，回到最近稳定提交重新评估

工具与技能调用

1 MCP 调用

如果遇到以下情况，建议向用户确认是否可以使用对应的 MCP 工具：

  • 需要库/API 文档、代码生成、环境搭建或配置步骤时，优先考虑使用 Context7。
  • 需要实现某种功能且可能在 GitHub 上已有类似项目或实现时，优先考虑使用 gh_grep 搜索相关代码示例。
  • 需要获取最新网页信息、跟踪动态内容或解析指定 URL 时，优先考虑使用 Exa 工具：web_search_exa 用于基础搜索，web_search_advanced_exa 用于更精确或复杂查询，web_fetch_exa 用于提取网页正文内容，并可根据需要整理为本地 Markdown。

2 SKILLS 调用

  • 当我要求你优化语言时，调用 humanizer-zh。

Agent 交互流程

  • 主 Agent 负责拆解与协调，子 Agent 负责检索、局部实现、测试与批处理
  • 任务可在局部闭环且规则明确时调用子 Agent
  • 涉及架构、全局影响或高风险逻辑时仅主 Agent 执行
  • 禁止重复传递大上下文，统一由主 Agent 整合结果

文档生成规范

  • 项目初始时，默认在 当前目录 或 用户指定工作目录 下生成 README.md 文档
  • 更新文档应遵循以下规范：
    • 确保文档前后一致连贯
    • 每次用户交互后，更新文档以反映最新的改进内容
    • 内容包括
      • 项目背景
      • 用户每次交互的原文，按版本顺序展示（当有大段代码或原文时，用省略号表示）
      • 项目实现逻辑
      • 参数说明（大于 3 个参数时推荐表格展示）
        • 参数名
        • 默认值
        • 配置解释（包括可用值）
      • 完整的脚本执行命令
      • 注意事项
    • 若包含大段 bash 命令，应避免过度拆分结构，优先将说明内容以注释形式（#）按执行顺序嵌入命令中，并统一放入单一代码块，仅在存在长段说明、不同主题或独立命令集合时进行拆分或者在代码块外增加说明
    • 总体原则：减少结构碎片，提升连续性与可读性

Windows .bat 规则

所有 .bat 文件必须使用 UTF-8 无 BOM + CRLF。

文件前两行必须固定为：

@echo off
chcp 65001 >nul

第一行前不能有 BOM 或任何隐藏字符。

只要脚本里有中文、中文路径或非 ASCII 字符，就必须显式设置 chcp 65001 >nul，避免中文 Windows 的 cmd 按 GBK/OEM 代码页错误解析。

进程管理不要按进程名匹配，不要依赖 tasklist 杀进程。启动程序时优先用 PowerShell Start-Process -PassThru 获取 PID，停止时优先按保存的 PID 停止，并尽量校验进程路径，避免误杀同名进程。

编码行为准则

来源：Andrej Karpathy 风格指南。偏重审慎而非速度，简单任务酌情适用。

1 先思考再编码

不假设、不隐藏困惑、呈现权衡。

  • 不确定时明确说出假设，主动提问
  • 存在多种理解时，呈现选项而非静默选择
  • 存在更简单方案时，指出并说明
  • 不清楚时停下来，指出困惑点

2 简单优先

最少代码解决问题，不做推测性设计。

  • 不添加未要求的功能
  • 单次使用的代码不做抽象
  • 不添加未要求的"灵活性"或"可配置性"
  • 不为不可能发生的场景写错误处理
  • 200 行能缩减到 50 行时，重写

3 精确修改

只改必须改的，只清理自己造成的残留。

  • 不"改进"相邻代码、注释或格式
  • 不重构未损坏的代码
  • 匹配现有风格，即使你不会这样做
  • 发现无关死代码时提及即可，不删除
  • 自己的修改产生的孤立导入/变量/函数，必须清除
  • 每一行改动都应能追溯到用户请求

4 目标驱动执行

定义可验证的成功标准，循环直到确认。

  • 将任务转化为可验证目标：
    • "添加验证" → "为无效输入写测试，再让测试通过"
    • "修复 bug" → "写一个能复现的测试，再让测试通过"
    • "重构 X" → "确保重构前后测试均通过"
  • 多步任务应陈述简要计划：[步骤] → 验证: [检查方式]
  • 强成功标准可独立循环；弱标准（"让它能跑"）则需要反复确认