diff --git a/CITATION.cff b/CITATION.cff index 00fdb6f..8a52c86 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -11,8 +11,9 @@ authors: # email: "you@example.com" repository-code: "https://github.com/keting/half" license: Apache-2.0 -version: "0.1.0" -date-released: "2026-04-22" +doi: 10.5281/zenodo.19809712 +version: "0.2.1" +date-released: "2026-04-27" keywords: - ai-agents - coding-agents diff --git a/README.md b/README.md index c2b24ae..3e31801 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ [English](./README.md) | [简体中文](./README.zh-CN.md) +[![DOI](https://zenodo.org/badge/1196783873.svg)](https://doi.org/10.5281/zenodo.19809712) [![CI](https://github.com/keting/half/actions/workflows/ci.yml/badge.svg)](https://github.com/keting/half/actions/workflows/ci.yml) # HALF - Human-AI Loop Framework @@ -23,6 +24,22 @@ A task management console for teams orchestrating multiple AI coding agents short-term reset windows, and long-term reset windows so planners do not dispatch work to an unavailable agent. +## Product Preview + +The built-in demo project gives first-time users a non-empty workspace for +understanding the project board, task dependencies, and agent availability. + +| Plan DAG | Available agents | Agent settings | +|---|---|---| +| Demo plan DAG | Available demo agents | Demo agent settings | + +
+Project board screenshot + +Demo project board + +
+ ## What HALF is not - A replacement for Jira, Linear, or a general-purpose project management @@ -119,6 +136,8 @@ Application code lives under [`src/`](./src). Documentation lives under - [`docs/project-structure.md`](./docs/project-structure.md) - code organization for contributors - [`docs/ui-style.md`](./docs/ui-style.md) - UI and interaction principles +- [`docs/quickstart.md`](./docs/quickstart.md) - step-by-step setup guide with + troubleshooting The **API reference** is auto-generated by FastAPI and available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` @@ -142,6 +161,26 @@ Open `http://localhost:3000` and log in as `admin` with the password you set. The `HALF_ADMIN_PASSWORD` value must be set in `.env` before the first deployment; HALF uses it to create the initial `admin` account. +### First Steps + +After logging in: + +1. **Explore the Demo Project** - A browsable demo `(Demo) 修复一个bug` is + pre-loaded with sample tasks. Review it to understand the task board, DAG + view, and handoff prompts. +2. **Create Your Own Project** - Click "新建项目" and configure: + - Git repository URL (must be accessible from the container) + - Collaboration directory (relative path for outputs) + - **At least one Agent must be selected** from the pre-seeded demo agents + - Polling intervals and timeout settings +3. **Generate a Plan** - Select a process template and provide required inputs + (e.g., doc paths, test URLs) to generate the task DAG. +4. **Dispatch Tasks** - Start tasks from the task board; HALF generates prompts + for you to paste into your agent's UI. + +See [docs/quickstart.md](./docs/quickstart.md) for a detailed walkthrough and +troubleshooting. + ## Demo Project On first startup, HALF seeds a browsable demo project by default: @@ -229,6 +268,21 @@ to report vulnerabilities. See [`CONTRIBUTING.md`](./CONTRIBUTING.md). +## Citation + +If you use HALF in your research, teaching, or software engineering +experiments, please cite the archived Zenodo project record: + +Keting. (2026). HALF: Human-AI Loop Framework. Zenodo. +https://doi.org/10.5281/zenodo.19809712 + +The citation metadata is also available in [`CITATION.cff`](./CITATION.cff). + +DOI maintenance note: HALF uses the Zenodo Concept DOI for repository-level +citation and metadata. Version-specific DOIs are managed by Zenodo and are not +written back into the repository for every release. For exact reproducibility, +use the version-specific DOI shown on the corresponding Zenodo record. + ## Screenshots Screenshots will be added in v0.2. diff --git a/README.zh-CN.md b/README.zh-CN.md index aeabd74..e393ecf 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,5 +1,6 @@ [English](./README.md) | [简体中文](./README.zh-CN.md) +[![DOI](https://zenodo.org/badge/1196783873.svg)](https://doi.org/10.5281/zenodo.19809712) [![CI](https://github.com/keting/half/actions/workflows/ci.yml/badge.svg)](https://github.com/keting/half/actions/workflows/ci.yml) # HALF - Human-AI Loop Framework @@ -8,8 +9,7 @@ coding agent（Claude Code、Codex、Copilot、GLM、Kimi 等）的协作。 > [!WARNING] -> **v0.x / 早期开源版本。** 接口和数据模型可能会在次版本间发生变化，暂不建 -> 议用于生产级多租户场景。 +> **v0.x / 早期开源版本。** 接口和数据模型可能会在次版本间发生变化，暂不建议用于生产级多租户场景。 ## HALF 是什么 @@ -20,6 +20,22 @@ coding agent（Claude Code、Codex、Copilot、GLM、Kimi 等）的协作。 - **agent 可用性模型。** 跟踪每个 agent 的订阅到期时间、短周期重置窗口和 长周期重置窗口，避免规划器把任务派发给当前不可用的 agent。 +## 产品预览 + +内置 Demo 项目会为首次使用者提供一个非空工作区，用于理解项目看板、任务 +依赖关系和 agent 可用性。 + +| Plan DAG | 可用 agents | Agent 设置 | +|---|---|---| +| Demo Plan DAG | 可用 Demo agents | Demo agent 设置 | + +
+项目看板截图 + +Demo 项目看板 + +
+ ## HALF 不是什么 - 不是 Jira、Linear 或通用项目管理工具的替代品。 @@ -104,6 +120,8 @@ agent 产品，尤其是订阅式产品，主要面向个人或团队直接交 - [`docs/project-structure.md`](./docs/project-structure.md) - 面向贡献者 的代码组织说明 - [`docs/ui-style.md`](./docs/ui-style.md) - UI 与交互原则 +- [`docs/quickstart.md`](./docs/quickstart.md) - 详细的快速上手指南和故障 + 排除 **API 参考文档** 由 FastAPI 自动生成。后端启动后，可访问 `http://localhost:8000/docs`（Swagger UI）或 @@ -127,6 +145,22 @@ docker compose up -d `HALF_ADMIN_PASSWORD` 必须在第一次部署前写入 `.env`；HALF 会用它创建初 始 `admin` 账号。 +### 首次使用步骤 + +登录后： + +1. **浏览 Demo 项目** - 预置的 `(Demo) 修复一个bug` 包含示例任务。查看任务 + 看板、DAG 视图和 handoff prompt，了解产品形态。 +2. **创建自己的项目** - 点击"新建项目"并配置： + - Git 仓库地址（需确保容器内可访问） + - 协作目录（用于存放输出的相对路径） + - **必须选择至少一个 Agent**（从预置的 demo agents 中选择） + - 轮询间隔和超时设置 +3. **生成 Plan** - 选择流程模板并填写必填参数，生成任务 DAG。 +4. **派发任务** - 从任务看板启动任务；HALF 生成 prompt 供你粘贴到 agent UI。 + +详细步骤和故障排除请参阅 [docs/quickstart.md](./docs/quickstart.md)。 + ## Demo 项目 首次启动时，HALF 默认会创建一个可浏览的 Demo 项目： @@ -210,6 +244,19 @@ HALF 通常以自托管方式部署。用于生产环境时，请保持 贡献说明请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。 +## 引用 + +如果你在研究、教学或软件工程实验中使用 HALF，请引用 Zenodo 项目归档记录： + +Keting. (2026). HALF: Human-AI Loop Framework. Zenodo. +https://doi.org/10.5281/zenodo.19809712 + +引用元数据也可以在 [`CITATION.cff`](./CITATION.cff) 中查看。 + +DOI 维护说明：HALF 使用 Zenodo Concept DOI 作为仓库级引用和元数据 DOI。 +版本级 DOI 由 Zenodo 管理，不会在每个 release 后都回写到仓库。若需要精确 +复现某个版本，请使用对应 Zenodo 记录中显示的版本级 DOI。 + ## 截图 截图将在 v0.2 版本补充。 diff --git a/docs/architecture.md b/docs/architecture.md index 7226052..31f66f6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # HALF 架构说明 -> **对应版本**：v0.1.0 +> **对应版本**：v0.2.1 > 本文档描述当前代码已经实现的系统结构、关键设计决策和公开面。以代码为事实源头；文档与代码不一致时，代码为准。 --- diff --git a/docs/images/readme-agent-settings.png b/docs/images/readme-agent-settings.png new file mode 100644 index 0000000..0ac6cd8 Binary files /dev/null and b/docs/images/readme-agent-settings.png differ diff --git a/docs/images/readme-available-agents.png b/docs/images/readme-available-agents.png new file mode 100644 index 0000000..b28f654 Binary files /dev/null and b/docs/images/readme-available-agents.png differ diff --git a/docs/images/readme-plan-dag.png b/docs/images/readme-plan-dag.png new file mode 100644 index 0000000..b85893e Binary files /dev/null and b/docs/images/readme-plan-dag.png differ diff --git a/docs/images/readme-project-board.png b/docs/images/readme-project-board.png new file mode 100644 index 0000000..b106bf4 Binary files /dev/null and b/docs/images/readme-project-board.png differ diff --git a/docs/project-structure.md b/docs/project-structure.md index 8f64c4a..2723d83 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -1,6 +1,6 @@ # 代码结构导览 -> **对应版本**：v0.1.0 +> **对应版本**：v0.2.1 > 本文档帮助想要修改 HALF 代码的贡献者快速定位对应模块。以 `main` 分支的当前真实目录结构为准。 --- diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..cac8fd4 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,191 @@ +# HALF Quick Start Guide + +This guide walks through running HALF for the first time in a clean environment. + +## Prerequisites + +- Docker 20.10+ and Docker Compose v2+ +- 2GB available RAM +- Ports 3000 (frontend) and 8000 (backend) available, or configure custom ports + +## Step 1: Configure Environment + +```bash +cd src +cp .env.example .env +``` + +Edit `.env` and set the **required** values: + +```bash +# Generate a secure random key: +# python3 -c 'import secrets; print(secrets.token_urlsafe(48))' +HALF_SECRET_KEY=your-generated-secret-key + +# Must be at least 8 characters +HALF_ADMIN_PASSWORD=YourSecurePass123 +``` + +Optional settings: + +```bash +# Set to 'false' to start without the demo project +HALF_DEMO_SEED_ENABLED=true + +# Allow self-registration (default: false, only enable for internal demos) +HALF_ALLOW_REGISTER=false +``` + +## Step 2: Start Services + +```bash +docker compose up -d --build +``` + +Wait for services to be healthy (usually 10-30 seconds): + +```bash +docker compose ps +``` + +You should see: +- `src-backend-1` status: `healthy` +- `src-frontend-1` status: `running` + +## Step 3: First Login + +Open `http://localhost:3000` in your browser. + +Login credentials: +- Username: `admin` +- Password: The `HALF_ADMIN_PASSWORD` value you set in `.env` + +## Step 4: Explore the Demo Project + +On first startup, HALF seeds a demo project: + +- **Name**: `(Demo) 修复一个bug` +- **Repository**: `https://github.com/keting/half.git` +- **Status**: Contains 5 tasks in various states (completed, ready, blocked) + +Navigate to the project to see: +1. **Task Board** - Kanban view of tasks by status +2. **DAG View** - Visual dependency graph +3. **Task Queue** - Tasks ready for execution +4. **Handoff Prompts** - Generated prompts for agents + +The demo is read-only exploration. HALF does not execute agents automatically. + +## Step 5: Create Your First Project + +1. Click "新建项目" (New Project) +2. Fill in the form: + - **项目名称**: Your project name + - **项目目标**: Description of what you want to achieve + - **Git 仓库地址**: Repository URL (e.g., `https://github.com/your/repo.git`) + - **协作目录**: Relative path for outputs (e.g., `projects/my-project`) + - **轮询间隔**: How often to check for task completion (seconds) + - **任务超时**: Task timeout in minutes + +3. **Select Agents** (Required) + - At least one agent must be selected + - Pre-seeded demo agents: Claude Max, Codex Pro, Copilot Pro + - Configure co-location settings per agent + +4. Click "创建项目" + +## Step 6: Generate a Plan + +1. Open your project +2. Click "生成 Plan" (Generate Plan) +3. Select a **流程模板** (Process Template) +4. Fill in required inputs: + - `docPath`: Path to your PRD or spec document + - `test_url`: URL for testing (if applicable) + - Other template-specific inputs +5. Select which agents to use for plan generation +6. Click "生成 Plan" + +HALF will: +- Generate a task DAG based on the template +- Assign tasks to selected agents +- Create handoff prompts for each task + +## Step 7: Dispatch and Execute Tasks + +1. Go to the **任务列表** (Task List) tab +2. Find tasks with status "待处理" (Pending) +3. Click "派发" (Dispatch) to generate the prompt +4. Copy the prompt and paste it into your agent's UI +5. The agent works in the Git repository +6. HALF polls for `result.json` to detect completion + +## Troubleshooting + +### Services fail to start + +**Check logs:** +```bash +docker compose logs backend +docker compose logs frontend +``` + +**Port conflicts:** +If ports 3000 or 8000 are in use, edit `docker-compose.yml`: +```yaml +frontend: + ports: + - "3001:80" # Change host port + +backend: + ports: + - "8001:8000" # Change host port +``` + +**Weak password error:** +HALF refuses to start with weak defaults. Ensure: +- `HALF_SECRET_KEY` is set and sufficiently random +- `HALF_ADMIN_PASSWORD` is at least 8 characters + +### Login fails + +- Verify `HALF_ADMIN_PASSWORD` in `.env` +- Check browser console for CORS errors +- Ensure you're using `http://localhost:3000`, not `https` + +### "At least one agent must be selected" error + +When creating a project, you must: +1. Select at least one agent from the list +2. Configure agent assignments with co-location settings + +### Demo project not showing + +Check if seeding is enabled: +```bash +HALF_DEMO_SEED_ENABLED=true docker compose up -d +``` + +### Git repository access fails + +For private repositories, copy `src/docker-compose.override.yml.example` to +`src/docker-compose.override.yml` and mount a dedicated deploy key. Do not mount +your whole `~/.ssh` directory into the container. + +Alternatively, use HTTPS with a deploy token in the repository URL. + +## Next Steps + +- Read [architecture.md](./architecture.md) for system design +- Read [task-lifecycle.md](./task-lifecycle.md) for task state transitions +- Review the API docs at `http://localhost:8000/docs` + +## Clean Up + +To remove all data and start fresh: + +```bash +docker compose down -v +``` + +This removes containers and volumes (SQLite database, cloned repos). diff --git a/docs/releases/v0.2.0.md b/docs/releases/v0.2.0.md new file mode 100644 index 0000000..2cd9758 --- /dev/null +++ b/docs/releases/v0.2.0.md @@ -0,0 +1,184 @@ +# HALF v0.2.0 Release Notes + +Release date: 2026-04-27 + +## English + +`v0.2.0` focuses on first-run onboarding. Compared with `v0.1.0`, this release +makes a fresh HALF deployment immediately explorable: a built-in demo project is +seeded by default, Quick Start documentation has been verified from a clean +environment, and README screenshots now show the main product surfaces. + +This remains a `v0.x` self-hosted evaluation release. HALF is still a +human-in-the-loop coordination console, not an automated agent runner. + +### What's New + +- **Built-in demo project.** Fresh deployments now create a browsable demo + project, `(Demo) 修复一个bug`, using the public repository + `https://github.com/keting/half.git` and collaboration directory + `demo/half-demo-collaboration`. +- **Demo workflow seed data.** The demo includes one final plan, five tasks, one + completed task output, two ready tasks, and two dependency-blocked downstream + tasks so users can inspect the project board, DAG, task queue, and handoff + prompts without creating their own project first. +- **Demo agents and process template.** Fresh demo-enabled deployments seed the + three demo agent types used by the sample workflow: `claude-max`, + `chatgpt-pro`, and `copilot-pro`, plus a reusable process template. +- **Demo seed control.** Operators can disable demo data before first startup by + setting `HALF_DEMO_SEED_ENABLED=false`. +- **Cleaner demo agent settings.** Demo-enabled fresh deployments now show only + the demo-related agent catalog in `/agents/settings`, avoiding unrelated + legacy defaults in the first-run experience. +- **Current default agent catalog.** Fresh deployments that disable demo seed + still start with the current `claude-max`, `chatgpt-pro`, and `copilot-pro` + agent type catalog instead of the older `claude`, `codex`, `cursor`, and + `windsurf` defaults. +- **Verified Quick Start guide.** `docs/quickstart.md` was added and README + links now point first-time users through setup, login, demo exploration, + project creation, plan generation, and common troubleshooting. +- **README screenshots.** README and README.zh-CN now include compact product + previews for the demo DAG, available agents, agent settings, and the project + board. + +### Fixes and Behavioral Polish + +- Project-level predecessor readiness now reports blocked tasks consistently, so + downstream tasks such as `T4_EVAL` and `T5_SYNC` are not shown as ready before + their required predecessor outputs exist. +- The single-task predecessor diagnostic endpoint was aligned with the + project-level readiness semantics. +- Demo task output field names and result paths were polished for clearer sample + data. +- The Docker Compose deployment path now passes `HALF_DEMO_SEED_ENABLED` into + the backend container. +- Fresh deployments that set `HALF_DEMO_SEED_ENABLED=false` no longer expose the + legacy default agent type catalog in `/agents/settings`. + +### Upgrade and Deployment Notes + +- Existing deployments are not expected to receive demo seed data retroactively. + The demo seed path is intended for fresh databases. +- `HALF_ADMIN_PASSWORD` must be set in `.env` before the first deployment. The + initial login user is `admin`, and the password is the value of + `HALF_ADMIN_PASSWORD`. +- To start without the built-in demo project, set + `HALF_DEMO_SEED_ENABLED=false` before the first `docker compose up`. +- For real workflows, use a repository that the operator can write to, such as + a personal repository or fork. The built-in demo repository is public and + intended for browsing the product shape. + +### Not Included in v0.2.0 + +- The README 30-60 second minimal-loop GIF is intentionally not included in this + release. It is tracked separately in #39. +- `release/roadmap-to-main` is not included because the roadmap content is not + finalized. + +### Validation Status + +Validated on 2026-04-27 against latest `main` after #42: + +- `HALF_DEMO_SEED_ENABLED=false` fresh deployment starts successfully. +- Demo data remains disabled: no projects, demo agents, tasks, or process + templates are created. +- The default agent catalog contains only `claude-max`, `chatgpt-pro`, and + `copilot-pro`. +- Legacy defaults `claude`, `codex`, `cursor`, and `windsurf` are not present. +- Restarting the backend does not duplicate agent type or model mappings. + +One validation host had an unrelated local port conflict on `localhost:8000`, +so the backend host port was temporarily mapped to `18000:8000`; container +behavior and frontend access were otherwise unchanged. + +### Related Work + +- Demo project seed: #29 / #36 +- Demo agent settings cleanup: #37 +- Default agent catalog cleanup: #42 +- Clean Quick Start guide: #27 / #38 +- README screenshots: #26 / #40 +- Deferred README GIF: #39 + +## 简体中文 + +`v0.2.0` 的重点是首次启动体验。相比 `v0.1.0`，这个版本让全新部署后的 +HALF 可以立即被浏览和理解：系统默认创建内置 Demo 项目，Quick Start 文档 +已经经过干净环境验证，README 也补充了主要产品界面的截图预览。 + +HALF 仍然处于 `v0.x` 自托管评估阶段。它仍是 human-in-the-loop 的协作控制 +台，不是自动执行 agent 的 runner。 + +### 新增内容 + +- **内置 Demo 项目。** 全新部署默认创建可浏览的 Demo 项目 + `(Demo) 修复一个bug`，使用公开仓库 `https://github.com/keting/half.git` + 和协作目录 `demo/half-demo-collaboration`。 +- **Demo 流程种子数据。** Demo 包含 1 个 final plan、5 个任务、1 个已完成 + 任务产物、2 个 ready 任务，以及 2 个因上游输出缺失而 blocked 的下游任 + 务。用户无需先创建自己的项目，就可以查看项目看板、DAG、任务队列和 + handoff prompt。 +- **Demo agents 与流程模板。** 启用 demo seed 的全新部署会创建示例流程中 + 使用的 3 类 demo agent：`claude-max`、`chatgpt-pro`、`copilot-pro`，以及 + 一个可复用流程模板。 +- **Demo seed 开关。** 如果不希望首次启动时创建内置 Demo 数据，可以在首 + 次启动前设置 `HALF_DEMO_SEED_ENABLED=false`。 +- **更干净的 demo agent 设置页。** 启用 demo seed 的全新部署中， + `/agents/settings` 只显示 demo 相关 agent catalog，避免首次体验中出现无 + 关 legacy 默认项。 +- **当前默认 agent catalog。** 即使全新部署关闭 demo seed，系统也会使用 + 当前的 `claude-max`、`chatgpt-pro`、`copilot-pro` agent type catalog，而 + 不是旧的 `claude`、`codex`、`cursor`、`windsurf` 默认项。 +- **经过验证的 Quick Start。** 新增 `docs/quickstart.md`，README 会引导首 + 次用户完成部署、登录、浏览 Demo、创建项目、生成 Plan 和常见故障排除。 +- **README 截图。** README 和 README.zh-CN 现在包含紧凑的产品预览，覆盖 + Demo DAG、可用 agents、agent 设置和项目看板。 + +### 修复与体验打磨 + +- 项目级前置任务状态现在会一致地报告 blocked 任务，避免 `T4_EVAL` 和 + `T5_SYNC` 在上游输出缺失时被误显示为 ready。 +- 单任务前置状态诊断接口已与项目级 ready/blocked 语义对齐。 +- Demo 任务输出字段和结果路径经过整理，示例数据更清晰。 +- Docker Compose 部署路径现在会把 `HALF_DEMO_SEED_ENABLED` 传入后端容器。 +- 设置 `HALF_DEMO_SEED_ENABLED=false` 的全新部署不再在 `/agents/settings` + 中暴露 legacy 默认 agent type catalog。 + +### 升级与部署说明 + +- 已有部署通常不会被 retroactively 写入 Demo seed 数据。Demo seed 主要面 + 向全新数据库的首次启动体验。 +- `HALF_ADMIN_PASSWORD` 必须在第一次部署前写入 `.env`。初始登录用户名为 + `admin`，密码就是 `HALF_ADMIN_PASSWORD` 的值。 +- 如果希望首次启动时不创建内置 Demo 项目，请在第一次 `docker compose up` + 前设置 `HALF_DEMO_SEED_ENABLED=false`。 +- 实际运行自己的流程时，请使用操作者有写权限的仓库，例如个人仓库或 fork。 + 内置 Demo 仓库是公开仓库，主要用于浏览产品形态。 + +### 不纳入 v0.2.0 + +- README 30-60 秒最小闭环 GIF 不纳入本次发布，已拆到 #39 单独跟踪。 +- `release/roadmap-to-main` 不纳入本次发布，因为 ROADMAP 内容尚未定稿。 + +### 验证状态 + +已在 2026-04-27 基于 #42 合并后的最新 `main` 完成验证： + +- `HALF_DEMO_SEED_ENABLED=false` 的全新部署可以正常启动。 +- Demo 数据保持关闭：不会创建 projects、demo agents、tasks 或 process + templates。 +- 默认 agent catalog 只包含 `claude-max`、`chatgpt-pro`、`copilot-pro`。 +- legacy 默认项 `claude`、`codex`、`cursor`、`windsurf` 均不存在。 +- 重启 backend 后不会重复创建 agent type 或 model mapping。 + +其中一台验证宿主机存在无关的 `localhost:8000` 端口占用，因此临时将 backend +宿主端口映射为 `18000:8000`；容器内行为和前端访问路径不受影响。 + +### 相关工作 + +- Demo project seed：#29 / #36 +- Demo agent settings 清理：#37 +- 默认 agent catalog 清理：#42 +- 干净环境 Quick Start：#27 / #38 +- README 截图：#26 / #40 +- 后续 README GIF：#39 diff --git a/docs/releases/v0.2.1.md b/docs/releases/v0.2.1.md new file mode 100644 index 0000000..a3c5253 --- /dev/null +++ b/docs/releases/v0.2.1.md @@ -0,0 +1,52 @@ +# HALF v0.2.1 Release Notes + +Release date: 2026-04-27 + +## English + +`v0.2.1` synchronizes citation metadata for Zenodo archiving and DOI +registration. + +No major functional changes are included. HALF remains a `v0.x` self-hosted +evaluation release for human-in-the-loop multi-agent coding workflow +coordination. + +### Changes + +- Updated `CITATION.cff` to version `0.2.1` for Zenodo DOI registration. +- Updated current documentation version markers to `v0.2.1`. +- Added the Zenodo project Concept DOI: + https://doi.org/10.5281/zenodo.19809712 + +### Notes + +- No major functional changes. +- No database migration. +- No deployment behavior changes. +- This release is archived on Zenodo under the HALF project record: + https://doi.org/10.5281/zenodo.19809712 +- Version-specific DOIs are managed by Zenodo and are not written back into the + repository for every release. + +## 简体中文 + +`v0.2.1` 用于同步 citation 元数据，以支持 Zenodo 归档和 DOI 注册。 + +本版本不包含主要功能变化。HALF 仍然是 `v0.x` 阶段的自托管评估版本，用于 +human-in-the-loop 的多 agent coding workflow 协调。 + +### 变更 + +- 将 `CITATION.cff` 更新到版本 `0.2.1`，用于 Zenodo DOI 注册。 +- 将当前文档的版本标记更新为 `v0.2.1`。 +- 补充 Zenodo 项目 Concept DOI： + https://doi.org/10.5281/zenodo.19809712 + +### 说明 + +- 无主要功能变化。 +- 无数据库迁移。 +- 无部署行为变化。 +- 本版本已归档到 Zenodo 的 HALF 项目记录： + https://doi.org/10.5281/zenodo.19809712 +- 版本级 DOI 由 Zenodo 管理，不会在每个 release 后都回写到仓库。 diff --git a/docs/task-lifecycle.md b/docs/task-lifecycle.md index 7e037e9..08f1a45 100644 --- a/docs/task-lifecycle.md +++ b/docs/task-lifecycle.md @@ -1,6 +1,6 @@ # 任务生命周期与运行时机制 -> **对应版本**：v0.1.0 +> **对应版本**：v0.2.1 > 本文档说明 HALF 的运行时模型：项目 / 计划 / 任务三者关系、计划生成、任务执行、状态流转、`result.json` 契约、轮询机制和 Agent 可用性跟踪。以代码为事实源头；文档与代码不一致时，代码为准。 --- diff --git a/src/backend/main.py b/src/backend/main.py index b4a19b0..ac3406d 100644 --- a/src/backend/main.py +++ b/src/backend/main.py @@ -24,7 +24,7 @@ from routers import process_templates as process_templates_router from services.polling_service import polling_loop from services.prompt_settings import DEFAULT_PLAN_CO_LOCATION_GUIDANCE, PLAN_CO_LOCATION_GUIDANCE_KEY -from services.demo_seed import seed_demo_project +from services.demo_seed import DEMO_AGENT_TYPE_CATALOG, DEMO_MODEL_CAPABILITIES, seed_demo_project logging.basicConfig(level=logging.INFO) logger = logging.getLogger("half") @@ -197,36 +197,41 @@ def repair_legacy_agent_reset_times(): def seed_agent_type_configs(): - """Seed agent type configs and model definitions from hardcoded defaults if tables are empty.""" + """Seed the default agent type catalog if tables are empty.""" db = SessionLocal() try: if db.query(AgentTypeConfig).first() is not None: return # Already seeded - SEED_TYPES = { - "claude": ["claude-sonnet-4-5", "claude-opus-4-1", "claude-3-7-sonnet-latest"], - "codex": ["codex-mini-latest", "codex-1", "gpt-5-codex"], - "cursor": ["cursor-default", "gpt-5", "claude-sonnet-4-5"], - "windsurf": ["windsurf-default", "claude-sonnet-4-5", "gpt-5"], - } - model_cache: dict[str, ModelDefinition] = {} - for type_name, model_names in SEED_TYPES.items(): - agent_type = AgentTypeConfig(name=type_name) + for type_order, type_spec in enumerate(DEMO_AGENT_TYPE_CATALOG): + agent_type = AgentTypeConfig( + name=type_spec["name"], + description=type_spec["description"], + display_order=type_order, + ) db.add(agent_type) db.flush() - for model_name in model_names: + for model_order, model_name in enumerate(type_spec["models"]): if model_name not in model_cache: - model_def = ModelDefinition(name=model_name) + model_def = ModelDefinition( + name=model_name, + capability=DEMO_MODEL_CAPABILITIES.get(model_name), + ) db.add(model_def) db.flush() model_cache[model_name] = model_def db.add(AgentTypeModelMap( agent_type_id=agent_type.id, model_definition_id=model_cache[model_name].id, + display_order=model_order, )) db.commit() - logger.info("Seeded agent type configs with %d types and %d models", len(SEED_TYPES), len(model_cache)) + logger.info( + "Seeded agent type configs with %d types and %d models", + len(DEMO_AGENT_TYPE_CATALOG), + len(model_cache), + ) finally: db.close() diff --git a/src/backend/services/demo_seed.py b/src/backend/services/demo_seed.py index 533db03..c79e7bc 100644 --- a/src/backend/services/demo_seed.py +++ b/src/backend/services/demo_seed.py @@ -27,7 +27,7 @@ DEMO_COLLABORATION_DIR = "demo/half-demo-collaboration" DEMO_REPO_URL = "https://github.com/keting/half.git" -_MODEL_CAPABILITIES = { +DEMO_MODEL_CAPABILITIES = { "gpt-5.5": ( "优先处理高复杂度、强推理、长链路的专业工作，如大型代码库改造、跨系统问题排查、" "深度研究分析、复杂产品/架构决策与端到端交付；相比 GPT-5.4，它更适合作为高难度任务的主代理、" @@ -184,7 +184,7 @@ def _mark_demo_seed_loaded(db: Session) -> None: def _model_entries(model_names: list[str]) -> list[dict[str, str]]: return [ - {"model_name": model_name, "capability": _MODEL_CAPABILITIES[model_name]} + {"model_name": model_name, "capability": DEMO_MODEL_CAPABILITIES[model_name]} for model_name in model_names ] @@ -245,12 +245,12 @@ def _ensure_agent_type_catalog(db: Session) -> None: if model_def is None: model_def = ModelDefinition( name=model_name, - capability=_MODEL_CAPABILITIES.get(model_name), + capability=DEMO_MODEL_CAPABILITIES.get(model_name), ) db.add(model_def) db.flush() elif not model_def.capability: - model_def.capability = _MODEL_CAPABILITIES.get(model_name) + model_def.capability = DEMO_MODEL_CAPABILITIES.get(model_name) existing_map = db.query(AgentTypeModelMap).filter( AgentTypeModelMap.agent_type_id == agent_type.id, diff --git a/src/backend/tests/test_agent_type_config_seed.py b/src/backend/tests/test_agent_type_config_seed.py new file mode 100644 index 0000000..b3fec78 --- /dev/null +++ b/src/backend/tests/test_agent_type_config_seed.py @@ -0,0 +1,76 @@ +import sys +import unittest +from pathlib import Path +from unittest.mock import patch + +from sqlalchemy import create_engine +from sqlalchemy.orm import sessionmaker +from sqlalchemy.pool import StaticPool + +BACKEND_DIR = Path(__file__).resolve().parents[1] +if str(BACKEND_DIR) not in sys.path: + sys.path.insert(0, str(BACKEND_DIR)) + +from main import seed_agent_type_configs +from models import AgentTypeConfig, AgentTypeModelMap, Base, ModelDefinition + + +class AgentTypeConfigSeedTests(unittest.TestCase): + def setUp(self): + engine = create_engine( + "sqlite://", + connect_args={"check_same_thread": False}, + poolclass=StaticPool, + ) + self.SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine) + Base.metadata.create_all(bind=engine) + + def test_seed_uses_current_demo_agent_catalog(self): + with patch("main.SessionLocal", self.SessionLocal): + seed_agent_type_configs() + + db = self.SessionLocal() + try: + type_names = { + agent_type.name + for agent_type in db.query(AgentTypeConfig).order_by(AgentTypeConfig.display_order).all() + } + self.assertEqual(type_names, {"claude-max", "chatgpt-pro", "copilot-pro"}) + self.assertNotIn("claude", type_names) + self.assertNotIn("codex", type_names) + self.assertNotIn("cursor", type_names) + self.assertNotIn("windsurf", type_names) + + models_by_name = {model.name: model for model in db.query(ModelDefinition).all()} + self.assertEqual( + set(models_by_name), + {"Opus 4.7", "Sonnet 4.6", "gpt-5.5", "gpt-5.4", "Opus 4.6"}, + ) + self.assertTrue(models_by_name["gpt-5.5"].capability) + + self.assertEqual(db.query(AgentTypeModelMap).count(), 8) + finally: + db.close() + + def test_seed_keeps_existing_catalog_untouched(self): + db = self.SessionLocal() + try: + db.add(AgentTypeConfig(name="custom-agent")) + db.commit() + finally: + db.close() + + with patch("main.SessionLocal", self.SessionLocal): + seed_agent_type_configs() + + db = self.SessionLocal() + try: + type_names = {agent_type.name for agent_type in db.query(AgentTypeConfig).all()} + self.assertEqual(type_names, {"custom-agent"}) + self.assertEqual(db.query(ModelDefinition).count(), 0) + finally: + db.close() + + +if __name__ == "__main__": + unittest.main()