sayurinana/agent-aide

Fork 0

Files

sayurinana(vm) b2c26cb9db 📃 docs: 部分完成

2025-12-13 04:37:41 +08:00

8.9 KiB

Raw Blame History

Aide 程序系统开发文档

一、项目概述

1.1 项目定位

Aide 是一套命令行工具集，用于支持 AI 辅助开发工作流。本项目实现 aide 程序的核心基础功能，包括：

项目初始化（aide init）
环境管理（aide env）
配置管理（aide config）

注意：本阶段不包含 aide flow（进度追踪）和 aide decide（待定项确认）的实现，这两个功能将在后续阶段开发。

1.2 技术栈要求

Python 3.10+：主要编程语言
Shell 脚本：跨平台入口封装（aide.sh / aide.bat）
TOML：配置文件格式
标准库优先：尽量使用 Python 标准库，减少外部依赖

1.3 设计原则

确定性：相同输入产生相同输出，避免不确定性
精简输出：成功时输出极简，失败时输出详细
幂等性：重复执行不产生副作用
自文档化：配置文件包含详细注释
跨平台：支持 Linux、macOS、Windows

二、目录结构

aide-program/
├── README.md                    # 本文件：项目总览
├── docs/                        # 详细设计文档
│   ├── 01-入口脚本设计.md       # aide.sh / aide.bat 设计
│   ├── 02-aide-init设计.md      # aide init 命令设计
│   ├── 03-aide-env设计.md       # aide env 命令设计
│   ├── 04-aide-config设计.md    # aide config 命令设计
│   ├── 05-配置文件规范.md       # config.toml 格式规范
│   ├── 06-输出格式规范.md       # 统一输出格式规范
│   └── 07-测试规范.md           # 测试要求和用例
├── src/                         # 源代码目录（开发时创建）
│   ├── aide.sh                  # Linux/macOS 入口
│   ├── aide.bat                 # Windows 入口
│   ├── main.py                  # Python 主入口
│   ├── core/                    # 核心模块
│   │   ├── __init__.py
│   │   ├── config.py            # 配置读写
│   │   └── output.py            # 输出格式化
│   ├── commands/                # 命令实现
│   │   ├── __init__.py
│   │   ├── init.py              # aide init
│   │   ├── env.py               # aide env
│   │   └── config_cmd.py        # aide config
│   └── utils/                   # 工具函数
│       ├── __init__.py
│       └── validators.py        # 验证函数
└── tests/                       # 测试目录（开发时创建）
    ├── test_init.py
    ├── test_env.py
    └── test_config.py

三、命令清单

3.1 本阶段实现的命令

命令	功能	优先级
`aide init`	初始化 .aide 目录和配置文件	P0
`aide env ensure`	检测并修复项目开发环境	P0
`aide env ensure --runtime`	检测 aide 运行时环境	P0
`aide config get <key>`	获取配置值	P1
`aide config set <key> <value>`	设置配置值	P1

3.2 后续阶段实现的命令

命令	功能	说明
`aide flow ...`	进度追踪和 git 集成	后续实现
`aide decide ...`	待定项确认 Web 服务	后续实现

四、开发流程

4.1 阅读顺序

建议按以下顺序阅读文档：

README.md（本文件）- 了解项目全貌
docs/06-输出格式规范.md - 理解统一输出格式
docs/05-配置文件规范.md - 理解配置文件结构
docs/01-入口脚本设计.md - 理解命令调用流程
docs/02-aide-init设计.md - 实现 aide init
docs/03-aide-env设计.md - 实现 aide env
docs/04-aide-config设计.md - 实现 aide config
docs/07-测试规范.md - 编写测试用例

4.2 开发步骤

搭建基础框架
- 创建目录结构
- 实现入口脚本（aide.sh / aide.bat）
- 实现 main.py 命令分发
- 实现 core/output.py 输出格式化
实现核心模块
- 实现 core/config.py 配置读写
- 实现 utils/validators.py 验证函数
实现命令
- 实现 aide init
- 实现 aide env ensure --runtime
- 实现 aide env ensure
- 实现 aide config get/set
编写测试
- 单元测试
- 集成测试
- 跨平台测试
文档和打包
- 编写用户文档
- 准备分发包

4.3 质量要求

代码质量
- 遵循 PEP 8 代码规范
- 函数和类必须有文档字符串
- 关键逻辑必须有注释
测试覆盖
- 核心功能测试覆盖率 ≥ 80%
- 所有错误路径必须有测试用例
- 跨平台兼容性测试
用户体验
- 输出信息清晰易懂
- 错误提示包含解决建议
- 命令执行速度快（< 1秒）

五、核心概念

5.1 输出格式

所有 aide 命令遵循统一的输出格式：

前缀	含义	使用场景
`✓`	成功	操作成功完成
`⚠`	警告	有问题但可继续
`✗`	错误	操作失败
`→`	信息	进行中或提示信息

静默原则：无输出 = 正常完成（适用于幂等操作）

5.2 配置文件

位置：.aide/config.toml
格式：TOML
特点：自文档化，包含详细注释
访问：通过 aide config 命令或 core/config.py 模块

5.3 数据存储

所有 aide 数据统一存放在项目根目录的 .aide/ 下：

.aide/
├── config.toml          # 项目配置
├── flow-status.json     # 任务进度（后续实现）
├── decisions/           # 待定项记录（后续实现）
└── logs/                # 操作日志（可选）

5.4 错误处理

预期错误：返回明确的错误信息和建议
非预期错误：记录详细日志，返回简化错误信息
退出码：
- 0：成功
- 1：一般错误
- 2：参数错误
- 3：环境错误

六、依赖管理

6.1 Python 依赖

核心依赖（必需）：

Python 3.10+
标准库：os, sys, pathlib, subprocess, json, configparser

可选依赖：

tomli / tomllib（Python 3.11+ 内置）：TOML 解析
tomli-w：TOML 写入

6.2 系统依赖

必需：

Python 3.10+

可选（用于项目环境检测）：

git
uv / pip

七、交付物

7.1 必需交付物

源代码
- 完整的 Python 代码
- 入口脚本（aide.sh / aide.bat）
- 所有必需的模块和工具函数
测试代码
- 单元测试
- 集成测试
- 测试数据和 fixtures
文档
- 用户使用文档
- 开发者文档（如有特殊设计）
- CHANGELOG

7.2 可选交付物

打包脚本
- 用于生成分发包的脚本
- 安装说明
CI/CD 配置
- GitHub Actions 或其他 CI 配置
- 自动化测试流程

八、注意事项

8.1 设计约束

不要实现 aide flow：进度追踪功能后续实现
不要实现 aide decide：待定项确认功能后续实现
不要硬编码路径：所有路径通过配置或参数传入
不要假设环境：所有环境依赖必须检测和验证

8.2 兼容性要求

Python 版本：支持 3.10+
操作系统：Linux、macOS、Windows
路径分隔符：使用 pathlib 处理跨平台路径
编码：统一使用 UTF-8

8.3 安全考虑

配置文件权限：不存储敏感信息
命令注入：所有外部命令调用必须参数化
路径遍历：验证所有文件路径
输入验证：验证所有用户输入

九、参考资料

9.1 项目文档

../aide-requirements.md：Aide 系统需求规格
../aide-marketplace/aide-plugin/：Commands 和 Skills 定义
../discuss/：设计讨论和决策记录

9.2 外部资源

十、联系方式

如有疑问或需要澄清，请：

查阅 docs/ 目录下的详细设计文档
参考 ../aide-requirements.md 了解整体设计
查看 ../discuss/ 目录了解设计决策

附录：快速开始

A.1 验证环境

# 检查 Python 版本
python3 --version  # 应该 >= 3.10

# 检查必要的库
python3 -c "import tomllib"  # Python 3.11+
# 或
python3 -c "import tomli"    # Python 3.10

A.2 创建开发环境

# 创建虚拟环境
cd aide-program
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate     # Windows

# 安装依赖（如需要）
pip install tomli tomli-w

A.3 运行测试

# 运行所有测试
python3 -m pytest tests/

# 运行特定测试
python3 -m pytest tests/test_init.py

版本：v1.0 更新日期：2025-12-13 状态：待开发

8.9 KiB Raw Blame History Unescape Escape