AI 驱动开发模板 (AI-Driven Development Template)
这是一个面向未来的、为 AI 智能体高度优化的项目脚手架与开发模板。通过内置的“契约”系统，它可以确保 AI 助手在辅助开发时遵循统一的规范和最佳实践。
AgentForge 是一个面向 AI 辅助开发场景的项目模板，目标是降低人类开发者与 AI 智能体协作时的沟通和维护成本。 本项目以马王堆帛书版《道德经》为哲学底座，追求极致简约与学以致用。它不仅提供了清晰的目录约定与智能体协作规范，更探索了将“大道至简”、“反者道之动”等理论哲学转化为可落地的工程实施方案，适合构建需要长期演进的工程化项目。
- ☯️ 哲学驱动工程：基于《道德经》底层逻辑，通过 全链路业务映射框架 实现从哲学理论到业务场景的融会贯通。
- 🤖 智能体全局契约：内置
AGENTS.md，统一 AI 助手的执行入口与协作规则。 - 🧩 清晰的目录分层：区分人类文档、AI 规则、任务工作台与长期知识资产。
- 📦 模块化技能管理：提供可复用的 AI 技能体系与规范化资产目录。
- 🛡️ 隔离式文档架构：彻底分离人类专属文档（
docs/）与 AI 专属资产库（.agents/docs/），防止 LLM 产生上下文幻觉。 - 🔄 自动化评测循环：集成了针对 AI 技能的测试驱动开发（TDD）及兼容性修复验证体系。
- 📚 Sphinx/MyST 深度集成：开箱即用的现代化文档构建流，支持多层级模块化日志追踪。
如果你是第一次进入项目，建议优先按下面的入口阅读：
| 入口 | 面向对象 | 说明 |
|---|---|---|
README.md |
人类开发者 | 当前首页，提供项目简介、环境要求、安装方式与使用入口。 |
AGENTS.md |
AI 助手 / 需要协作的开发者 | AI 执行契约、任务路由、文档边界与协作规则。 |
.agents/README.md |
想理解 AI 目录结构的读者 | .agents/ 目录说明与子目录导航。 |
.trae/ |
当前任务执行者 | 存放任务规划、草稿和执行中的临时产物。 |
.agents/docs/superpowers/ |
需要查历史沉淀的读者 | 归档 Spec、复盘和长期知识资产。 |
推荐路径：
- 快速上手：先看当前首页，再按需进入
docs/。 - 需要 AI 协作：阅读
AGENTS.md，让 AI 按契约执行。 - 需要了解 AI 资产布局：阅读
.agents/README.md。 - 需要历史方案或复盘：阅读
.agents/docs/superpowers/与CHANGELOG.md。
本项目推荐使用 mise 统一管理运行时与开发工具，再由 uv 负责 Python 包依赖同步。
- 操作系统：跨平台支持（Windows / macOS / Linux），推荐在 Windows 环境下使用
PowerShell 7+。 - Python 版本基线：由根目录
mise.toml统一锁定为3.14.5。 - 工具层管理：优先使用 mise 安装并切换 Python、
uv、Node.js、ruff、pre-commit与defuddle。 - Python 依赖层管理：统一使用 uv（禁止直接使用
pip或conda安装项目依赖）。 - 文档构建：依赖 Sphinx、MyST Parser、Jupyter Book 等工具，建议在
mise激活后的环境中执行。
git clone https://github.com/xinetzone/tao.git
cd tao请选择适合当前系统的安装方式：
# Windows: winget
winget install jdx.mise
# Windows: Scoop
scoop install mise# macOS: Homebrew
brew install mise
# Linux / macOS: 官方安装脚本
curl https://mise.run | sh首次安装后，请为当前 Shell 添加激活命令：
# PowerShell
Add-Content $PROFILE '(& mise activate pwsh) | Out-String | Invoke-Expression'# Bash
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
# Zsh
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc完成后请重新打开终端，并执行 mise --version 与 mise doctor 确认安装成功。
本项目推荐的初始化顺序如下：
# 信任当前仓库中的 mise 配置
mise trust
# 根据根目录 `mise.toml` 安装全部工具
mise install
# 同步开发、测试与文档依赖
mise run sync如需一键完成信任、安装、依赖同步与首次环境校验，请直接运行：
mise run init初始化流程基于 Python
invoke实现，原生跨平台，Windows / Linux / macOS 均可直接运行。
建议至少完成以下验证：
mise run check-env
mise run testmise run docs-html
mise run docs-linkcheck构建完成后可通过浏览器访问 docs/_build/html/index.html。
常用开发入口统一通过 mise run 执行，确保本地、CI 与跨平台环境保持一致：
| 场景 | 命令 | 说明 |
|---|---|---|
| 环境检查 | mise run check-env |
校验 Python、uv、Node.js、defuddle 等工具链版本。 |
| 依赖同步 | mise run sync |
同步开发、测试、文档依赖与全部可选功能依赖。 |
| 完整测试 | mise run test |
运行完整测试集，并触发严格文档构建校验。 |
| 覆盖率测试 | mise run test-coverage |
生成覆盖率报告，并按项目阈值校验。 |
| 代码质量 | mise run lint |
执行 pre-commit 全量检查。 |
| 代码格式化 | mise run fmt |
使用 Ruff 统一格式化代码。 |
| 文档构建 | mise run docs-html |
构建 Sphinx HTML 文档站。 |
| 外链校验 | mise run docs-linkcheck |
检查文档中的外部链接。 |
| 包构建 | mise run package-build |
构建 Python wheel 与 sdist 发布产物。 |
更多命令与配置背景请参阅 docs/build-conventions.md。
| 配置文件 | 作用 |
|---|---|
pyproject.toml |
Python 包元数据、PDM 构建后端、依赖分组、Ruff、pytest 与 coverage 配置。 |
mise.toml |
统一锁定 Python、uv、Node.js、defuddle 等工具版本，并声明跨平台任务入口。 |
uv.lock |
锁定依赖解析结果，保障开发、测试与 CI 环境可复现。 |
.pre-commit-config.yaml |
管理提交前质量检查 hooks。 |
docs/conf.py |
Sphinx 文档构建主配置。 |
docs/_config.toml |
文档站主题与展示选项配置。 |
项目采用 src/ 布局，运行时代码位于 src/taolib/；构建后端为 PDM，版本号通过 SCM 动态派生，发布产物会随 Git 标签与工作树状态自动反映版本信息。
- 升级
mise本体：运行mise self-update，然后执行mise doctor。 - 刷新项目工具版本：更新根目录
mise.toml中的精确版本后，运行mise install --force与mise run sync。 - 版本未切换：先检查 Shell 激活是否生效，再运行
mise trust、mise current与mise doctor。 - 工具下载失败：先确认网络与代理设置，必要时执行
mise cache clean后重试。 - 外部 CLI 缺失：运行
mise run init-check查看缺失项（跨平台，Windows/Linux/macOS 均可使用）。
更详细的环境说明请继续阅读 docs/quickstart.md、docs/build-conventions.md、docs/contributing.md 与 docs/deploy.md。
- 人类开发入口：访问
docs/index.md获取更详细的使用说明、API 文档与部署指南。 - AI 协作入口：在让 AI 参与任务前，先阅读
AGENTS.md以确认执行契约、文档边界与任务路由。 - AI 目录说明：如需了解
.agents/的结构与资产分布，请阅读.agents/README.md。
本项目将 AI 技能统一纳入 .agents/skills/ 目录管理，用于集中维护技能定义、脚本、评测与配套文档。
- 查看技能总入口：访问
.agents/README.md了解.agents/的整体结构。 - 查看技能开发规范：访问
.agents/rules/skills.md。 - 查看技能模板：访问
.agents/templates/SKILL.md。 - 查看已实现技能：浏览
.agents/skills/下各技能目录。 - 查看历史演进与复盘：访问
.agents/docs/superpowers/。
本项目采用分层变更日志结构，格式基于 Keep a Changelog。
- 查看全局日志索引：访问 CHANGELOG.md。
- 查看项目级月度变更：访问 tests/project_changelogs/。
- 查看技能级变更：访问
.agents/skills/下各技能目录中的CHANGELOG.md。
我们欢迎任何旨在提升人机协同效率的贡献。
- 贡献总入口：阅读 docs/contributing.md。
- AI 协作约束：阅读 AGENTS.md。
- PR 审查流程：阅读
.agents/workflows/pr-review.md。
- Issue 追踪：GitHub Issues
- 文档站点：AgentForge 官方文档