plane-gptproto-integration/AGENTS.md

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。