docs: split AGENTS.md into per-package files

Author: Guo-Zhang

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS
+
+## 仓库结构
+
+monorepo，包含以下子包：
+
+| 目录 | 包名 | 语言 | 定位 |
+|------|------|------|------|
+| `packages/dart/` | `quanttide_project` | Dart | 数据模型（参考实现） |
+| `packages/python/` | `quanttide-project` | Python | 数据模型（Pydantic） |
+| `packages/fastapi/` | `fastapi-quanttide-project` | Python | FastAPI CRUD 路由 |
+| `packages/flutter/` | `flutter_quanttide_project` | Dart/Flutter | 看板 UI 组件 |
+
+语言/包特定约定见各子包 `AGENTS.md`。
+
+## 提交消息
+
+- `feat:` — 新功能
+- `chore:` — 版本号变更、配置更新
+- `docs:` — 文档更新
+- `fix:` — 修 bug
+
+## 发布流程
+
+遵循 `.agents/skills/devops-release/SKILL.md`，关键流程：
+
+1. **更新版本号** → 改 `pyproject.toml`，跑 `uv lock` 同步 lock 文件
+2. **写 CHANGELOG** → 子模块用 `packages/<name>/CHANGELOG.md`，主仓库用 `CHANGELOG.md`
+3. **提交** → 分两次 commit：`chore: bump <name> to vX.Y.Z` + `docs: update CHANGELOG for vX.Y.Z`
+4. **预检查** → 工作区干净、版本号格式、CHANGELOG 存在、tag 不重复
+5. **用户确认**
+6. **打 tag + Release**
+
+### Tag 命名规则
+
+- **主仓库**: `vX.Y.Z`
+- **子模块**: `<name>/vX.Y.Z`（如 `fastapi/v0.2.0`、`python/v0.1.1`）
+- 注意：主仓库 tag 和子模块 tag 不可混淆。子模块 tag 不推送时 CI 不会触发 PyPI 发布
+
+### CI 自动发布
+
+Python/FastAPI 包的 PyPI 发布由 GitHub Release `published` 事件触发，workflow 内以 `startsWith(github.ref, 'refs/tags/<name>/')` 过滤。
+
+### 从 CHANGELOG 提取 Release Notes
+
+```bash
+NOTES=$(sed -n "/^## \[${VNUM}\]/,/^## \[/p" CHANGELOG.md | sed '1d;$d')
+```
+
+## 文档同步
+
+子包文档（`packages/<name>/docs/`）与根文档（`docs/`）各自独立。新功能说明需同步更新到两层，例如 FastAPI camelCase 同时更新了：
+- `packages/fastapi/docs/user/index.md` + `api.md`
+- `docs/user/index.md`

packages/dart/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS — dart
+
+Dart 包是数据模型参考实现，新字段先在 dart 包定义，其他语言对照实现。

packages/fastapi/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS — fastapi
+
+## 开发注意事项
+
+- JSON I/O 使用 camelCase（`createdAt`），Python 代码保持 snake_case（`created_at`），通过 `CamelCaseModel` 和 `response_model_by_alias=True` 实现
+- 改 `pyproject.toml` 版本号后必须跑 `uv lock`，否则 lock 文件与 pyproject 不一致
+- `ModelRouter` 自动推导 Create/Update/Response Schema，新增字段无需改 router 代码

packages/flutter/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS — flutter
+
+## 代码风格
+
+- 遵循 `flutter_lints/flutter.yaml` 规则
+- analysis_options.yaml 继承 `package:flutter_lints/flutter.yaml`
+- 纯 UI 组件，不包含数据模型，通过外部传入数据渲染

packages/python/AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS — python
+
+## 代码风格
+
+- 不写注释（除非被明确要求）
+- ruff lint，target-version = py310
+- ruff select = `["E", "F", "I", "N", "W"]`
+- hatchling 构建
+- pytest：testpaths = `["tests"]`，pythonpath = `["src"]`
+- 遵循现有代码约定，模仿邻接文件风格