版本: 1.1.1
最后更新: 2026-03-13
本文档定义了所有在本项目上工作的 AI 代码智能体的操作协议。每个智能体在执行任何任务之前必须阅读并遵守本文档。这些规则不可协商，优先级高于智能体的默认行为。
| # | 原则 | 摘要 |
|---|---|---|
| 1 | 先问后做 | 指令不清晰时，必须先向用户请求澄清，而不是直接开始工作。 |
| 2 | 文档随代码更新 | 每次代码变更必须伴随相应的文档更新。 |
| 3 | 先读后写 | 在进行任何修改之前，必须先阅读 doc/ 文件夹中的现有文档。 |
| 4 | Windows 下端到端使用 UTF-8 | 当任务在 Windows 上涉及中文或其他非 ASCII 文本时，智能体必须先确保终端、子进程和文件 I/O 全链路使用 UTF-8，再信任输出结果。 |
| 5 | 仅限 UV | 所有 Python 项目使用 UV 作为唯一的包管理和环境管理工具。禁止直接使用 pip、conda 或 virtualenv。 |
| 6 | 先写测试 | 严格遵循 TDD 循环。在测试存在并失败之前，不得编写功能代码。 |
如果以下任何一个条件成立，智能体必须在开始任务之前向用户请求澄清：
doc/ 中记录的项目特定术语或缩写。_config.yml 或更改构建/部署流程。请求澄清时，智能体必须：
用户: "更新博客的样式"
智能体回复（正确）：
在开始之前，我想确认几点：
- **具体修改哪方面的样式？**
(a) 博客文章内容排版（标题、段落、代码块）
(b) 博客列表页面布局
(c) 博客导航栏或侧边栏
(d) 以上全部
- **是否有具体的设计参考**（截图、URL 或文字描述）？
- **是否也需要影响主页作品集的样式**，还是仅限于博客部分？
智能体回复（错误）：
[直接开始修改 assets/css/style.css，未经询问]
以下情况智能体可以直接执行：
在对项目进行任何修改之前，智能体必须：
doc/ 文件夹中所有相关的文档。没有相应文档更新的代码变更被视为未完成。 智能体在文档也更新完毕之前，不得将任务报告为”已完成”。
任何改变项目行为、结构或约定的修改，包括但不限于：
| 变更类型 | 文档影响 |
|---|---|
| 创建新博客文章 | 如果引入了新模式，更新 doc/blog-conventions.md |
| 添加或重命名文件/文件夹 | 更新 doc/project-structure.md |
修改 _config.yml |
更新 doc/configuration.md |
| 修改布局或包含文件 | 更新 doc/layouts-and-includes.md |
| CSS/JS 变更 | 更新 doc/frontend-guide.md |
| 添加新功能 | 创建或更新 doc/ 中的相关文档 |
| 构建/部署流程变更 | 更新 doc/deployment.md |
更新文档时，智能体必须：
doc/ 文件夹中的相关文档。如果变更引入了现有文档未涵盖的内容，智能体必须：
doc/ 中创建新的 .md 文件，使用描述性文件名（kebab-case, 英文）。doc/README.md（文档索引）中添加对新文档的引用。UV 是本工作区所有 Python 项目唯一的包管理和环境管理工具。 智能体禁止直接使用 pip、conda、virtualenv、venv 或 poetry。所有依赖和环境操作必须通过 uv 完成。
| 任务 | 命令 | 说明 |
|---|---|---|
| 初始化新项目 | uv init |
创建 pyproject.toml 和项目脚手架 |
| 创建虚拟环境 | uv venv |
在项目根目录创建 .venv/ |
| 激活虚拟环境 | .venv\Scripts\activate (Windows) |
运行项目代码前激活 |
| 添加依赖 | uv add <package> |
添加到 pyproject.toml 并安装 |
| 添加开发依赖 | uv add --dev <package> |
用于测试/lint/仅开发用的包 |
| 移除依赖 | uv remove <package> |
从 pyproject.toml 中移除并卸载 |
| 安装所有依赖 | uv sync |
根据 lock 文件安装所有依赖 |
| 更新 lock 文件 | uv lock |
根据 pyproject.toml 重新生成 uv.lock |
| 在环境中运行命令 | uv run <command> |
在托管环境中运行，无需手动激活 |
| 查看已安装的包 | uv pip list |
列出当前环境中的包 |
| 文件 | 用途 | 版本控制 |
|---|---|---|
pyproject.toml |
项目元数据和依赖声明 | 必须提交 |
uv.lock |
确定性 lock 文件，包含精确解析的版本 | 必须提交 |
.venv/ |
本地虚拟环境目录 | 必须加入 .gitignore |
.python-version |
项目固定的 Python 版本（可选） | 如存在则提交 |
pip install。 始终使用 uv add 或 uv sync。uv.lock。 该文件由 uv lock 或 uv add 自动生成。pyproject.toml 和 uv.lock。uv run 执行脚本和工具，以确保使用正确的环境。pyproject.toml，先运行 uv init 再添加依赖。智能体必须严格遵循 TDD 循环。在测试存在并失败之前，禁止编写功能代码。 这是防止“幻觉式编程”（写出看似正确但实际无法运行的代码）的核心机制。
每个功能的开发必须严格按照以下步骤执行：
tests/ 文件夹中编写断言预期行为的测试用例。uv run pytest 运行测试，测试必须失败（证明功能尚未实现）。跳过步骤 2-3（先写功能代码再补测试）是严格禁止的。
智能体必须根据变更的范围编写不同层级的测试：
pytesttests/unit/pytest fixtures 搭建临时环境（如创建临时 CSV 文件），并在测试后清理。tests/integration/subprocess 或 shell 命令调用脚本。stdout/stderr 中的特定输出字符串tests/e2e/unittest.mock 或 pytest-mock 模拟外部响应。
tests/
├── conftest.py # 共享 fixtures 和测试配置
├── unit/ # 单元测试
│ ├── test_parser.py
│ └── test_models.py
├── integration/ # 集成测试
│ ├── test_pipeline.py
│ └── test_database.py
└── e2e/ # 端到端/系统测试
└── test_cli.py
在将任务标记为“完成”之前，智能体必须运行完整的测试套件：
uv run pytest tests/ -v
uv run pytest --cov=src tests/核心认知：测试本身由 AI 生成，因此测试代码也可能出错。
当测试失败时，存在两种可能的原因，智能体必须先诊断再修复：
| 原因 | 描述 | 处理方式 |
|---|---|---|
| A. 功能代码不满足需求 | 代码存在 Bug 或未实现预期行为 | 修复功能代码，重新运行测试 |
| B. 测试本身未正确反映需求 | 测试的断言、假设或 Mock 设置有误，不符合最初的设计需求 | 修正测试用例，重新运行测试 |
诊断流程：
禁止盲目修复：不得在不理解失败原因的情况下，简单修改代码让测试通过，或简单修改测试让它不再失败。每次修复都必须基于对需求的正确理解。
| 场景 | 要求 |
|---|---|
| 新增功能 | 必须先写测试 (TDD) |
| 修复 Bug | 必须先写复现该 Bug 的测试，再修复 |
| 重构代码 | 确保现有测试通过，必要时补充测试 |
| 修改配置/文档 | 无需测试 |
以下注意事项适用于日常智能体工作，即使前文没有单独点名说明，也同样必须遵守。
cmd）中，只要任务涉及读取、写入、显示、复制或比较中文或其他非 ASCII 文本，智能体必须先确认终端和子进程 I/O 端到端使用 UTF-8，再信任输出结果。[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding
Get-Content -Encoding utf8 ./notes.md
Set-Content -Encoding utf8 ./notes.md '中文示例'
python -X utf8 ./script.py
如果智能体意识到违反了本文档中的任何规则（例如，未请求澄清就开始工作，或未更新文档就修改了代码），必须：