# AGENTS.md — Worker 共享上下文

> 你是 omc team 中的一员。**先读这份文档**再动手。

## 项目概要
本项目落地"Plane（开源项目管理）从 GitHub 自部署 + gptproto AI 集成"方案。
- 完整设计见 `docs/PLAN.md` — 必读
- 当前阶段：**Stage A（本地 mac docker 验证）**
- 部署目标：本地 `localhost:8080`（Plane Web）+ `localhost:8100`（AI Agent）

## 工作目录
固定为 `<PROJECT_ROOT>/`。**不要修改这个目录之外的任何文件**。

## 红线
1. **不要**直接 ssh 任何远程服务器（Stage B 由用户人工执行）
2. **不要**改 `docs/PLAN.md`（设计文档已冻结）
3. **不要**写 `OPENAI_API_KEY` / `GPTPROTO_API_KEY` 实值进任何文件，全用 `.env` 占位
4. **不要**删除其它 worker 的文件
5. **TDD 强制**：写功能必须先写 pytest 让其 RED，再实现让其 GREEN

## 任务边界（避免冲突）
- **Worker A** 只动：`deploy/local/`、`deploy/remote/`、`qa/`
- **Worker B** 只动：`ai-agent/`（含 `ai_agent/`、`tests/`、`requirements.txt`、`Dockerfile`）
- 谁都不动 `docs/`、`AGENTS.md`、`README.md`

## 必读约束
### Plane 部署来源
- 必须 `git clone --branch v1.3.0 --depth 1 https://github.com/makeplane/plane.git`
- 不允许 `curl ... | bash`
- docker-compose 镜像必须锁 tag（`makeplane/plane-frontend:v1.3.0`），禁用 `:latest`

### 本地端口
- Plane Web → `localhost:8080`
- Plane API → 仅 docker 网络内 `api:8000`
- AI Agent → `localhost:8100`
- Postgres/Redis/MinIO **不**暴露到 host

### gptproto 配置
- Base URL: `https://gptproto.com/v1`（OpenAI SDK 兼容）
- Model 默认: `claude-sonnet-4-6`
- Key 通过 `GPTPROTO_API_KEY` 环境变量注入，**绝对不写明文**

### TDD 流程（Worker B 必读）
```
1. 写 tests/test_<feature>.py
2. pytest -v          # 必须 RED，且失败原因合理（不是 import error）
3. 写 ai_agent/main.py 中的实现
4. pytest -v          # GREEN
5. 提交一个端点再做下一个
```
要求：用 `pytest` + `httpx.AsyncClient` 测 FastAPI；用 `pytest-mock` 或 `respx` mock gptproto 和 Plane API（不要真发外网请求）。

### Mock 策略
- `gptproto` 调用 → respx 拦截 `https://gptproto.com/v1/chat/completions`
- `Plane API` 调用 → respx 拦截 `http://api:8000/api/v1/...`
- 单测**禁止**真实联网

## 完成定义
- **Worker A**：`deploy/local/` 下脚本可一键 `bash pull-plane.sh && docker compose up -d`，QA 脚本能验证健康；`deploy/remote/` 给出可读 README + install.sh（不实际执行远程）
- **Worker B**：`pytest ai-agent/tests/ -v` 全绿；4 个端点（healthz / create-issue / summarize / search）全实现；`ai-agent/Dockerfile` 可 `docker build` 成功

## 完成后
在 `qa/checklist.md` 末尾追加自己的"WORKER A 完成"或"WORKER B 完成"+ 时间戳，结束 worker。