Opencode-Howto: Instructions file for Codex

AGENTS.md

OpenCode Howto 项目的开发规范。

项目说明：本项目基于上游 Claude Code Howto (claude-howto-zh-cn-main) 创建，旨在为公司内部 AI 开发团队提供 OpenCode 培训指南。详见 PROJECT_OVERVIEW.md

构建命令

开发环境设置

# 创建虚拟环境并安装依赖
cd claude-howto-zh-cn-main
uv venv
uv pip install -r scripts/requirements-dev.txt

EPUB 构建

# 构建 EPUB 电子书
uv run scripts/build_epub.py

# 带参数构建
uv run scripts/build_epub.py --root . --output output.epub --verbose

# 构建选项
# --root, -r      Markdown 文件根目录
# --output, -o    输出 EPUB 文件路径
# --verbose, -v   启用详细日志
# --timeout       API 请求超时（秒）
# --max-concurrent 最大并发请求数

测试命令

运行测试

# 运行所有测试
uv run pytest scripts/tests/ -v

# 运行测试并生成覆盖率报告
uv run pytest scripts/tests/ -v --tb=short --cov=scripts --cov-report=term-missing

# 运行单个测试文件
uv run pytest scripts/tests/test_validate_localization.py -v

# 运行单个测试函数
uv run pytest scripts/tests/test_validate_localization.py::test_validate_markdown_links_detects_missing_file -v

# 安静模式（仅显示失败）
uv run pytest scripts/tests/ -q

# 运行特定标记的测试
uv run pytest scripts/tests/ -m "not slow"

代码质量检查

Lint 和格式化

# Ruff 格式检查
uv run ruff format --check scripts/

# Ruff 格式化（自动修复）
uv run ruff format scripts/

# Ruff lint 检查
uv run ruff check scripts/

# Ruff lint（自动修复）
uv run ruff check --fix scripts/

# 安全扫描
uv run bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/

# 本地化验证
uv run python scripts/validate_localization.py

Pre-commit Hooks

# 安装 pre-commit hooks
pre-commit install

# 手动运行所有检查
pre-commit run --all-files

项目结构

D:\Users\Administrator\opencode\Opencode-Howto\
├── PROJECT_OVERVIEW.md           # 项目概要文档
├── AGENTS.md                     # 本文件（开发规范）
├── OpenCode Howto 项目描述（面向AI开发）.docx  # 需求文档
└── claude-howto-zh-cn-main/      # 上游参考项目（Claude Code 中文指南）
    ├── scripts/                    # Python 脚本
    │   ├── build_epub.py          # EPUB 构建脚本
    │   ├── validate_localization.py # 本地化验证
    │   ├── pyproject.toml         # Python 项目配置
    │   ├── requirements.txt       # 生产依赖
    │   ├── requirements-dev.txt   # 开发依赖
    │   └── tests/                 # 测试目录
    ├── 01-slash-commands/         # Slash commands 文档
    ├── 02-memory/                 # Memory 文档
    ├── 03-skills/                 # Skills 文档和模板
    ├── 04-subagents/              # Subagents 文档
    ├── 05-mcp/                    # MCP 配置示例
    ├── 06-hooks/                  # Hooks 文档
    ├── 07-plugins/                # Plugins 文档
    ├── 08-checkpoints/            # Checkpoints 文档
    ├── 09-advanced-features/      # 高级功能文档
    ├── 10-cli/                    # CLI 文档
    └── .github/workflows/         # CI/CD 配置