zhi/HarborForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: zhi:77d8f6098f14ea26278d3e2bea4b40720278fef7
Branches Tags
zhi:main zhi:docs/readme-refresh
..
compare: zhi:docs/readme-refresh
Branches Tags
zhi:main zhi:docs/readme-refresh

66 Commits
77d8f6098f ... docs/readm

Author SHA1 Message Date
hzhang
d69bd5213c docs: rewrite top-level README — full component map 
List all 7 submodules with stack/role, correct architecture and ports,
replace stale Issues model with tasks/milestones/proposals, add Security
notes (mandatory strong SECRET_KEY) and cross-links to component READMEs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-16 17:50:52 +01:00
hzhang
19174c899e quick fix 2026-04-15 07:14:36 +01:00
zhi
b9242a1588 chore: update HarborForge.Test submodule pointer to main head 2026-04-05 22:18:03 +00:00
zhi
08cae38b42 chore: update HarborForge submodule pointers 2026-04-05 22:14:41 +00:00
h z
e42926ec65 Merge pull request 'dev-2026-03-29' (#7) from dev-2026-03-29 into main 
Reviewed-on: #7
 2026-04-05 22:11:44 +00:00
orion
27817fb0b9 chore: bump HarborForge component pointers for code-first indexing 2026-04-03 16:25:48 +00:00
zhi
7b3eb7b940 TEST-CLI-CAL-001 TEST-CLI-PR-001 complete CLI test tasks 2026-04-01 12:03:37 +00:00
zhi
fbc88f908b TEST-FE-PR-001: Mark task as completed 
- Essential 列表与表单 ✓
- Accept milestone 选择 ✓
- story 创建入口限制 ✓
 2026-04-01 11:41:56 +00:00
zhi
bdb8586612 TEST-FE-CAL-001 complete calendar frontend test coverage 2026-04-01 11:06:05 +00:00
zhi
69b2d2774e TEST-BE-CAL-001 record calendar backend test completion 2026-04-01 10:35:57 +00:00
zhi
dced5bbcd3 TEST-BE-PR-001 verify backend proposal tests 2026-04-01 10:04:50 +00:00
zhi
77fc66c0fc PLG-CAL-004: Mark task as complete - ScheduledGatewayRestart handling 
- Update submodule to include state persistence and restart handling
- Mark PLG-CAL-004 tasks as complete in TASKLIST.md
 2026-04-01 09:41:24 +00:00
zhi
8a886a1dff PLG-CAL-003 complete plugin deferred replanning 2026-04-01 08:52:16 +00:00
zhi
ac94f7aa32 PLG-CAL-002: Mark task as complete 
- Update TASKLIST.md to mark PLG-CAL-002 as completed
- Plugin submodule updated with scheduler implementation
 2026-04-01 08:45:38 +00:00
zhi
0b7fb3a002 chore: mark PLG-CAL-001 complete in TASKLIST.md 
- PLG-CAL-001: Calendar heartbeat format — all 3 sub-items completed:
  claw_identifier 传递方式 / agent_id 传递方式 / slot 列表结构
- Spec documented in HarborForge.OpenclawPlugin/docs/PLG-CAL-001-calendar-heartbeat-format.md
 2026-04-01 07:52:39 +00:00
zhi
28b21c96c4 feat(OpenclawPlugin): PLG-CAL-001: Calendar heartbeat format — submodule update 
Update HarborForge.OpenclawPlugin to commit 55d7d11:
- plugin/calendar/types.ts: heartbeat request/response TypeScript types
- plugin/calendar/calendar-bridge.ts: CalendarBridgeClient HTTP client
- plugin/calendar/index.ts: module exports
- docs/PLG-CAL-001-calendar-heartbeat-format.md: full format specification
- plugin/openclaw.plugin.json: calendar config options

Ref: HarborForge.NEXT_WAVE_DEV_DIRECTION.md §6, PLG-CAL-001
 2026-04-01 07:52:07 +00:00
zhi
fec154f14f CLI-CAL-001/002/003/004/005/006/007/008/009/010: Calendar CLI commands 2026-04-01 07:02:47 +00:00
zhi
15360f2a4b CLI-PR-001/002/003/004: Proposal rename, Essential commands, story restriction 2026-04-01 06:56:30 +00:00
zhi
50fdd0f50b FE-CAL-004/005: Calendar create/edit/cancel + status warnings 2026-04-01 06:50:11 +00:00
zhi
a540506752 FE-CAL-001/002/003: Calendar page skeleton with slot list and plans view 2026-04-01 06:48:22 +00:00
zhi
1bc9ba7dab Update Frontend submodule: FE-PR-005 story restriction 2026-04-01 06:46:27 +00:00
zhi
cd137f3b69 FE-PR-003/004/005: Mark existing Essential forms & Accept modal done; remove story from task creation 
- FE-PR-003: Essential create/edit modal with type selector and partial refresh already implemented in ProposalDetailPage
- FE-PR-004: Accept modal with milestone selector and generated tasks display already implemented
- FE-PR-005: Remove 'story' from TASK_TYPES in CreateTaskPage and CreateTaskModal - all story/* must come from Proposal Accept workflow
 2026-04-01 06:46:01 +00:00
zhi
75ccb17742 FE-PR-002: Mark task as completed in TASKLIST.md 2026-04-01 06:28:52 +00:00
zhi
235d636fee FE-PR-002: Update Frontend submodule for Essential list feature 2026-04-01 06:25:54 +00:00
zhi
86250e0c0f FE-PR-001: Update Frontend submodule - Propose -> Proposal rename 2026-04-01 04:46:50 +00:00
zhi
c9fe8f1f51 BE-AGT-004 complete exhausted recovery parsing 2026-04-01 04:18:48 +00:00
zhi
fe7b1408ad BE-AGT-003: mark task complete, update Backend submodule ref 2026-04-01 02:50:20 +00:00
zhi
dafac0305d BE-AGT-002: mark task complete, update Backend submodule ref 2026-04-01 00:46:23 +00:00
zhi
b1ea8ccccd BE-AGT-001: mark task complete, update backend submodule 2026-03-31 23:01:52 +00:00
zhi
c73fd07295 BE-CAL-API-007: update submodule ref and mark task complete 2026-03-31 20:46:53 +00:00
zhi
b5cdd5c3c2 BE-CAL-API-006: implement plan-edit and plan-cancel API endpoints 
- PATCH /calendar/plans/{plan_id}: edit a recurring schedule plan
  - Validates period-parameter hierarchy after merge
  - Rejects edits to inactive (cancelled) plans
  - Detaches future materialized slots so they keep old data
  - Past materialized slots remain untouched

- POST /calendar/plans/{plan_id}/cancel: cancel (soft-delete) a plan
  - Sets is_active=False
  - Detaches future materialized slots (plan_id -> NULL)
  - Preserves past materialized slots, returns their IDs

- Added SchedulePlanEdit and SchedulePlanCancelResponse schemas
- Imported guard_plan_edit/cancel_no_past_retroaction from slot_immutability
 2026-03-31 16:46:22 +00:00
zhi
e74bde118a Update Backend submodule: BE-CAL-API-005 2026-03-31 14:47:21 +00:00
zhi
9378a63af2 BE-CAL-API-005: implement plan-schedule / plan-list API 
- Add SchedulePlanCreate, SchedulePlanResponse, SchedulePlanListResponse schemas
- Add DayOfWeekEnum, MonthOfYearEnum schema enums
- Add POST /calendar/plans endpoint (create plan with hierarchy validation)
- Add GET /calendar/plans endpoint (list plans, optional include_inactive)
- Add GET /calendar/plans/{plan_id} endpoint (get single plan)
- Mark BE-CAL-API-005 complete in TASKLIST.md
 2026-03-31 14:46:45 +00:00
zhi
82331aeda2 BE-CAL-API-004: Implement Calendar cancel API for real and virtual slots 
- Add POST /calendar/slots/{slot_id}/cancel for real slot cancellation
- Add POST /calendar/slots/virtual/{virtual_id}/cancel for virtual slot cancellation
- Virtual cancel materializes the slot first, then marks as Skipped
- Both endpoints enforce past-slot immutability guard
- Both endpoints detach from plan (set plan_id=NULL)
- Status set to SlotStatus.SKIPPED on cancel
- Add TimeSlotCancelResponse schema
- Import guard_cancel_real_slot and guard_cancel_virtual_slot
 2026-03-31 12:47:56 +00:00
zhi
fb3fa0ca11 BE-CAL-API-003: implement Calendar edit API for real and virtual slots 
- Add TimeSlotEdit schema (partial update, all fields optional)
- Add TimeSlotEditResponse schema
- Add PATCH /calendar/slots/{slot_id} for editing real slots
- Add PATCH /calendar/slots/virtual/{virtual_id} for editing virtual slots
  - Triggers materialization before applying edits
  - Detaches from plan after edit
- Both endpoints enforce:
  - Past-slot immutability guard
  - Overlap detection (excluding self)
  - Plan detachment on edit
  - Workload warnings in response
 2026-03-31 10:46:19 +00:00
zhi
cfed3a07ed BE-CAL-API-002: Implement calendar day-view query API 
- Add GET /calendar/day endpoint with optional ?date= query param
- Returns unified CalendarDayResponse merging real slots + virtual plan slots
- New CalendarSlotItem schema supports both real (id) and virtual (virtual_id) slots
- Excludes inactive slots (skipped/aborted) from results
- All slots sorted by scheduled_at ascending
 2026-03-31 07:19:01 +00:00
zhi
80afdd1c6a BE-CAL-API-001: Update submodule ref + mark task complete 2026-03-31 05:46:03 +00:00
zhi
4309e3d39c BE-CAL-API-001: Implement single slot creation API 
- Add TimeSlotCreate, TimeSlotResponse, TimeSlotCreateResponse schemas
- Add SlotConflictItem, SlotTypeEnum, EventTypeEnum, SlotStatusEnum to schemas
- Add POST /calendar/slots endpoint with:
  - Overlap detection (409 on conflict)
  - Workload warning computation (advisory, returned in response)
  - Support for event_type + event_data (job/system/entertainment)
  - Default date to today if not provided
- Add _slot_to_response helper for ORM -> schema conversion
 2026-03-31 05:45:51 +00:00
zhi
9deb1bf8d5 BE-CAL-007 + BE-CAL-008: mark completed, update Backend submodule 2026-03-31 04:16:58 +00:00
zhi
b14366ebd1 BE-CAL-006: mark overlap detection task complete in TASKLIST 2026-03-31 01:18:01 +00:00
zhi
bbe651c3e3 Update Backend submodule: BE-CAL-005 plan virtual-slot materialization 2026-03-30 23:47:15 +00:00
zhi
a5ec32656e BE-CAL-005: Implement plan virtual-slot identification and materialization 
- Virtual slot ID: plan-{plan_id}-{YYYY-MM-DD} format with parse/make helpers
- Plan-date matching: on_month/on_week/on_day hierarchy with week_of_month calc
- Materialization: convert virtual slot to real TimeSlot row, copy plan template
- Detach: clear plan_id after edit/cancel to break plan association
- Bulk materialization: materialize_all_for_date for daily pre-compute
- 23 tests covering all paths (matching, virtual gen, materialize, detach, bulk)
 2026-03-30 23:46:51 +00:00
zhi
8b90c7d7f2 BE-CAL-004: update submodule pointer + mark task complete in TASKLIST 2026-03-30 22:27:15 +00:00
zhi
f984b6ddb4 BE-CAL-003: Agent model with status/heartbeat/exhausted fields (backend submodule) 2026-03-30 20:47:56 +00:00
zhi
6a4e7a7c0f Mark BE-CAL-002 complete in TASKLIST.md 2026-03-30 19:16:33 +00:00
zhi
c33a1e7739 BE-CAL-001: Mark TimeSlot model task complete, update Backend submodule 2026-03-30 17:45:22 +00:00
zhi
963a5dc20d BE-PR-011: Mark Proposal/Essential/Story restricted tests complete 
- Updated HarborForge.Backend submodule (test infra fix + 29 passing tests)
- Marked BE-PR-011 complete in TASKLIST.md
 2026-03-30 16:17:16 +00:00
zhi
63cb1d284d BE-PR-010: clean up feat_task_id semantics — deprecate with read-only compat 
Decision: retain DB column, mark DEPRECATED. Existing rows still return
feat_task_id via API. New accept flow (BE-PR-007) does not write it.
Clients should migrate to generated_tasks / Task.source_proposal_id.

- Backend: model/schema/router deprecation comments updated
- Backend: added docs/BE-PR-010-feat-task-id-deprecation.md
- Tests: updated to work with Essential-based accept flow
- Tests: all 21 proposal tests pass
- TASKLIST: BE-PR-010 marked complete
 2026-03-30 12:50:14 +00:00
zhi
03c8b74968 BE-PR-009: restrict all story/* task types + fix test conftest imports 2026-03-30 11:46:28 +00:00
zhi
42703c2401 Mark BE-PR-008 complete in TASKLIST.md 2026-03-30 10:46:38 +00:00
zhi
97031a7a27 Update Backend submodule: BE-PR-008 tracking fields 2026-03-30 10:46:28 +00:00
zhi
45c8d43914 BE-PR-007: mark task complete, update Backend submodule ref 2026-03-30 07:46:28 +00:00
zhi
ce4ce6400f Update Backend submodule ref for BE-PR-006 2026-03-30 07:16:34 +00:00
zhi
f9395fc41c BE-PR-006: Add Essential CRUD API under Proposals 
- New router: /projects/{project_id}/proposals/{proposal_id}/essentials
  - GET    (list)   - list all essentials under a proposal
  - POST   (create) - create essential with auto-generated EssentialCode
  - GET    /{id}    - get single essential by id or essential_code
  - PATCH  /{id}    - update essential (title, type, description)
  - DELETE /{id}    - delete essential
- All mutations restricted to open proposals only
- Permission: creator, project owner, or global admin
- Registered essentials router in main.py
- Updated GET /proposals/{id} to return ProposalDetailResponse with
  embedded essentials list
- Activity logging on all CRUD operations
 2026-03-30 07:16:21 +00:00
zhi
d52cb44fec Update Backend submodule ref for BE-PR-005 2026-03-30 06:45:30 +00:00
zhi
79b06f2d7d BE-PR-005: Add Essential schema definitions (create/update/response) and ProposalDetailResponse with nested essentials 2026-03-30 06:45:06 +00:00
zhi
b1ddff0743 BE-PR-004: implement EssentialCode encoding rules (submodule update) 2026-03-30 06:16:05 +00:00
zhi
42c59ff62a BE-PR-003: Update Backend submodule ref + mark task complete 2026-03-29 16:33:10 +00:00
zhi
e6c9459e22 BE-PR-003: Add Essential SQLAlchemy model 
- New app/models/essential.py with Essential model and EssentialType enum
  (feature, improvement, refactor)
- Fields: id, essential_code (unique), proposal_id (FK to proposes),
  type, title, description, created_by_id (FK to users), created_at, updated_at
- Added essentials relationship to Proposal model (cascade delete-orphan)
- Added essentials table auto-migration in main.py _migrate_schema()
- Registered essential module import in startup()
 2026-03-29 16:32:40 +00:00
zhi
619bb07eed chore: update Backend submodule pointer (BE-PR-002) 2026-03-29 16:02:22 +00:00
zhi
86758846bb BE-PR-002: Proposal model naming & field adjustments 
- Add comprehensive docstring to Proposal model documenting all relationships
- Add column comments for all fields (title, description, status, project_id, etc.)
- Mark feat_task_id as DEPRECATED (will be replaced by Essential→task mapping in BE-PR-008)
- Add proposal_code hybrid property as preferred alias for DB column propose_code
- Update ProposalResponse schema to include proposal_code alongside propose_code
- Update serializer to emit both proposal_code and propose_code for backward compat
- No DB migration needed — only Python-level changes
 2026-03-29 16:02:07 +00:00
zhi
48e52e3419 BE-PR-001: Rename Propose -> Proposal across backend 
- Backend: new canonical Proposal model + /proposals router
- Backward-compat shims for old Propose imports and /proposes API
- Tests updated to use /proposals, legacy compat tests added
- Impact checklist: docs/BE-PR-001-rename-impact.md
- TASKLIST.md: BE-PR-001 marked complete

All 21 proposal tests pass.
 2026-03-29 15:35:59 +00:00
zhi
0b9767d4a6 DOC-003: 整理 Calendar 验收清单 
- 后端验收项: 数据模型、Slot ID 策略与物化、验证规则、不可变性、Calendar API、Agent/心跳协作
- 前端验收项: 页面骨架、日程展示、计划展示、操作交互、状态提示、权限
- CLI 验收项: 命令组、日程/计划操作命令、输出格式、用户创建扩展
- 插件联动验收项: 心跳请求、唤醒逻辑、状态管理、ScheduledGatewayRestart
- 跨模块集成验收项
 2026-03-29 15:01:35 +00:00
zhi
ba1349bad4 DOC-002: Proposal/Essential/Story restricted migration guide 
- Document Propose → Proposal naming changes across all layers
- Document Proposal Accept semantic change (single task → Essential-based batch)
- Document story/* restricted expansion and impact analysis
- Document feat_task_id deprecation and backward compatibility strategy
- Document migration execution order and rollback plan
 2026-03-29 14:32:23 +00:00
zhi
becfc7d719 DOC-001: 整理本波开发范围说明 
- 明确 Calendar 为独立功能线，Proposal/Essential 为项目结构调整线
- 明确两条线交叉点仅限 event_data / Agent 调度引用层
- 区分必须本波完成 vs 仅设计保留内容
- 新增 docs/wave-2026-03-scope.md
 2026-03-29 14:01:10 +00:00
hzhang
835605aa42 Merge pull request 'chore/archive-plans-and-next-wave-doc' (#6) from chore/archive-plans-and-next-wave-doc into main 
Reviewed-on: #6
 2026-03-29 11:45:01 +00:00
8 changed files with 255 additions and 227 deletions
Expand all files Collapse all files

2
HarborForge.Backend

Submodule HarborForge.Backend updated: 751b3bc574...a2ab541b73

2
HarborForge.Cli

Submodule HarborForge.Cli updated: fbfa866c9d...cd22642472

2
HarborForge.Frontend

Submodule HarborForge.Frontend updated: 6c8c8b78b6...6432255203

2
HarborForge.Monitor

Submodule HarborForge.Monitor updated: 6e60fae559...758d3d1c59

2
HarborForge.OpenclawPlugin

Submodule HarborForge.OpenclawPlugin updated: 188d0a48d7...58a800a1aa

2
HarborForge.Test

Submodule HarborForge.Test updated: ef8a4ae994...c96d012fef

117
README.md
View File

@@ -1,34 +1,45 @@
# HarborForge # HarborForge
Agent/人类协同任务管理平台 Agent / 人类协同任务管理平台 —— 用严格的状态机管理 提案 → 里程碑 → 任务 的完整生命周期，配套 CLI、监控与 OpenClaw 集成。
## 项目结构 ## 项目结构
本仓库是 umbrella 仓库，所有组件以 git 子模块形式组织：
``` ```
HarborForge/ HarborForge/
├── HarborForge.Backend/ # 后端 (FastAPI + MySQL) ├── AbstractWizard/ # Go，安全初始化服务（SSH 隧道，端口 8080）
├── HarborForge.Frontend/ # 前端 (React + Vite) ├── HarborForge.Backend/ # Python/FastAPI，核心 REST API + RBAC（端口 8000）
├── docker-compose.yml # Docker 部署配置 ├── HarborForge.Frontend/ # React + TypeScript + Vite，单页前端（端口 3000）
├── nginx-host.conf.example # 宿主机 nginx 配置示例 ├── HarborForge.Cli/ # Go，命令行客户端 `hf`
└── .env.example # 环境变量模板 ├── HarborForge.Monitor/ # Go，主机遥测客户端（可选本地 bridge 9100）
├── HarborForge.OpenclawPlugin/ # Node，OpenClaw 插件 `harbor-forge`
├── HarborForge.Test/ # 集成测试（后端 pytest / 前端 Playwright）
├── docker-compose.yml # Docker 编排配置
├── nginx-host.conf.example # 宿主机 nginx 配置示例
└── .env.example # 环境变量模板
``` ```
## 快速开始 ## 快速开始
```bash ```bash
# 克隆并初始化子模块 # 克隆并初始化所有子模块
git clone https://git.hangman-lab.top/zhi/HarborForge.git git clone --recurse-submodules https://git.hangman-lab.top/zhi/HarborForge.git
cd HarborForge cd HarborForge
# 若已克隆但未初始化子模块：
git submodule update --init --recursive git submodule update --init --recursive
# 配置环境变量（不要使用默认值，见“安全”一节）
cp .env.example .env
# 编辑 .env，至少设置强随机 SECRET_KEY 与数据库口令
# 启动服务 # 启动服务
docker compose up -d docker compose up -d
``` ```
## 首次部署 — 初始化向导 ## 首次部署 — 初始化向导
HarborForge 使用 [AbstractWizard](https://git.hangman-lab.top/hzhang/AbstractWizard) 进行安全初始化。 HarborForge 使用 [AbstractWizard](./AbstractWizard) 进行安全初始化。Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
Wizard 仅监听 `127.0.0.1`，必须通过 SSH 隧道访问。
```bash ```bash
# 1. SSH 隧道映射 wizard 端口到本地 # 1. SSH 隧道映射 wizard 端口到本地
@@ -37,65 +48,81 @@ ssh -L 18080:127.0.0.1:18080 user@your-server
# 2. 浏览器访问前端（或通过宿主机 nginx） # 2. 浏览器访问前端（或通过宿主机 nginx）
# 前端检测到后端未就绪 → 自动跳转初始化向导 # 前端检测到后端未就绪 → 自动跳转初始化向导
# 3. 在向导中配置: # 3. 在向导中配置：数据库连接、管理员账号、默认项目（可选）
# - 数据库连接信息
# - 管理员账号
# - 默认项目（可选）
# 4. 配置保存后，后端自动检测到配置并启动 # 4. 配置保存后，后端自动检测到配置并启动；刷新页面 → 登录界面
# 刷新页面 → 进入登录界面
``` ```
### 启动流程 ### 启动流程
``` ```
docker compose up docker compose up
├── mysql → 数据库启动 ├── mysql → 数据库启动
├── wizard → AbstractWizard 启动 (127.0.0.1:18080) ├── wizard → AbstractWizard 启动（127.0.0.1，SSH 隧道访问）
├── backend → 等待配置文件... (轮询 /config/harborforge.json) ├── backend → 阻塞等待配置文件（轮询 /config/harborforge.json）
└── frontend → 检测后端状态 └── frontend → 检测后端状态
├── 后端未就绪 → 显示初始化向导 (SSH 隧道连 wizard) ├── 后端未就绪 → 显示初始化向导（SSH 隧道连 wizard）
└── 后端就绪 → 正常登录界面 └── 后端就绪 → 正常登录界面
``` ```
### 安全模型 ### 安全模型
- Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络 - Wizard 端口绑定 `127.0.0.1`，不暴露到外部网络；初始化必须经 SSH 隧道完成。
- 初始化必须通过 SSH 隧道完成（与 AbstractWizard 安全模型一致） - 配置通过 Docker volume 共享给后端（不走网络），后端以只读方式挂载。
- 配置完成后 Wizard 自动切换为只读模式
- 配置通过 Docker volume 共享给后端（不走网络）
## 部署架构 ## 部署架构
``` ```
宿主机 nginx (80/443) 宿主机 nginx (80/443)
├── / → frontend (Docker, port 3000) ├── / → frontend (Docker, 端口 3000)
└── /api/ → backend (Docker, port 8000) └── /api/ → backend (Docker, 端口 8000)
Docker 内部 (不暴露): Docker 内部（不对外）:
wizard (127.0.0.1:18080) → 配置管理，SSH 隧道访问 wizard (127.0.0.1) → 配置管理，SSH 隧道访问
wizard_config volume → wizard 写入，backend 读取 wizard_config vol → wizard 写入，backend 只读读取
mysql (127.0.0.1) → 数据持久化
``` ```
## 子模块 ## 子模块
- [HarborForge.Backend](https://git.hangman-lab.top/zhi/HarborForge.Backend) - FastAPI 后端 API | 子模块 | 技术栈 | 作用 |
- [HarborForge.Frontend](https://git.hangman-lab.top/zhi/HarborForge.Frontend) - React 前端 |--------|--------|------|
| [AbstractWizard](./AbstractWizard) | Go | 首次安装向导，安全写配置（原子写 + 备份），init/readonly 模式 |
| [HarborForge.Backend](./HarborForge.Backend) | Python / FastAPI / SQLAlchemy / MySQL | 核心 API：用户、项目、任务、里程碑、提案、RBAC、Webhook、工时、通知 |
| [HarborForge.Frontend](./HarborForge.Frontend) | React 18 / TS / Vite | SPA，~20 页面；自动检测未初始化 → 引导安装向导 |
| [HarborForge.Cli](./HarborForge.Cli) | Go | 权限感知命令行客户端 `hf` |
| [HarborForge.Monitor](./HarborForge.Monitor) | Go | 独立主机遥测客户端，心跳上报 |
| [HarborForge.OpenclawPlugin](./HarborForge.OpenclawPlugin) | Node / TS | OpenClaw 插件，桥接遥测，可安装 `hf` 技能与日历调度 |
| [HarborForge.Test](./HarborForge.Test) | pytest / Playwright | 后端与前端集成测试 |
## 核心业务模型
- **里程碑**：`open → freeze → undergoing → completed`（freeze 时须恰好 1 个 release 任务）
- **任务**（issue / story / test / maintenance / research / review / resolution）：`pending → open → undergoing → completed`，完成须带评论
- **提案**：用户提 propose → 管理者 accept → 自动在里程碑内创建 feature story 任务；reject 可重开
- **RBAC**：细粒度权限 + 项目角色层级（guest < viewer < member < dev < mgr < admin）
## 端口 ## 端口
| 服务 | 默认端口 | 绑定 | 环境变量 | | 服务 | 容器端口 | 绑定 | 环境变量 |
|------|----------|------|----------| |------|----------|------|----------|
| Frontend | 3000 | 0.0.0.0 | `FRONTEND_PORT` | | Frontend | 3000 | 见 compose | `FRONTEND_PORT` |
| Backend | 8000 | 0.0.0.0 | `BACKEND_PORT` | | Backend | 8000 | 见 compose | `BACKEND_PORT` |
| MySQL | 3306 | 127.0.0.1 | `MYSQL_PORT` | | MySQL | 3306 | 127.0.0.1 | `MYSQL_PORT` |
| Wizard | 18080 | 127.0.0.1 | `WIZARD_PORT` | | Wizard | 8080 | 127.0.0.1 | `WIZARD_PORT` |
## 前端页面 > SSH 隧道示例使用本地端口 `18080` 转发到服务器 wizard。
- 🔧 初始化向导 — 首次部署配置（SSH 隧道） ## 安全
- 📊 仪表盘 — 统计概览
- 📋 Issues — 创建、列表、详情、状态变更、评论 部署前务必：
- 📁 项目 — 项目管理、成员、关联 issue
- 🏁 里程碑 — 进度追踪、完成百分比 - **设置强随机 `SECRET_KEY`**（如 `openssl rand -hex 32`）。后端在检测到弱/默认/过短密钥时会拒绝启动。
- 🔔 通知 — 实时通知中心、未读计数 - 不要使用 `.env.example` 中的占位口令；为 MySQL 设置强口令。
- 不要将含真实密钥的 `.env` 提交进版本库。
后端的鉴权/RBAC/SSRF 加固详见 [HarborForge.Backend 的 README](./HarborForge.Backend) “Security” 一节。
## 前端
前端采用集中式自定义设计系统（“Foundry Deck” 工业主题），细节见 [HarborForge.Frontend 的 README](./HarborForge.Frontend)。

353
plans/TASKLIST.md
View File

@@ -144,236 +144,237 @@
- [x] 支持 job/system/event_data - [x] 支持 job/system/event_data
- [x] 接入 overlap 与 workload warning - [x] 接入 overlap 与 workload warning
- [ ] BE-CAL-API-002:实现某日 Calendar 查询 API(backend only) - [x] BE-CAL-API-002:实现某日 Calendar 查询 API（backend only）
- [ ] 返回真实 slot - [x] 返回真实 slot
- [ ] 合成当日 plan 虚拟 slot - [x] 合成当日 plan 虚拟 slot
- [ ] 输出统一排序结构 - [x] 输出统一排序结构
- [ ] BE-CAL-API-003:实现 Calendar 编辑 API(backend only) - [x] BE-CAL-API-003:实现 Calendar 编辑 API（backend only）
- [ ] 支持真实 slot 编辑 - [x] 支持真实 slot 编辑
- [ ] 支持虚拟 slot 编辑并触发物化 - [x] 支持虚拟 slot 编辑并触发物化
- [ ] 返回编辑后的真实结果 - [x] 返回编辑后的真实结果
- [ ] BE-CAL-API-004:实现 Calendar 取消 API(backend only) - [x] BE-CAL-API-004:实现 Calendar 取消 API(backend only)
- [ ] 支持真实 slot cancel - [x] 支持真实 slot cancel
- [ ] 支持虚拟 slot cancel 并触发物化 - [x] 支持虚拟 slot cancel 并触发物化
- [ ] 处理状态字段更新 - [x] 处理状态字段更新
- [ ] BE-CAL-API-005:实现 plan-schedule / plan-list API(backend only) - [x] BE-CAL-API-005:实现 plan-schedule / plan-list API(backend only)
- [ ] 创建计划 - [x] 创建计划
- [ ] 列出计划 - [x] 列出计划
- [ ] 返回计划规则字段 - [x] 返回计划规则字段
- [ ] BE-CAL-API-006:实现 plan-edit / plan-cancel API(backend only) - [x] BE-CAL-API-006:实现 plan-edit / plan-cancel API（backend only）
- [ ] 编辑计划 - [x] 编辑计划
- [ ] 取消计划 - [x] 取消计划
- [ ] 不追溯已物化过去数据 - [x] 不追溯已物化过去数据
- [ ] BE-CAL-API-007:实现 date-list API(backend only) - [x] BE-CAL-API-007:实现 date-list API(backend only)
- [ ] 仅列出有已物化未来 slot 的日期 - [x] 仅列出有已物化未来 slot 的日期
- [ ] 排除纯 plan 未物化日期 - [x] 排除纯 plan 未物化日期
## E. HarborForge.Backend - Agent / Plugin Calendar 协作 ## E. HarborForge.Backend - Agent / Plugin Calendar 协作
- [ ] BE-AGT-001:定义心跳查询待执行 slot 的服务层(backend only) - [x] BE-AGT-001:定义心跳查询待执行 slot 的服务层(backend only)
- [ ] 筛选当天 `NotStarted / Deferred` - [x] 筛选当天 `NotStarted / Deferred`
- [ ] 仅返回 `scheduled_at` 已过的 slot - [x] 仅返回 `scheduled_at` 已过的 slot
- [ ] 按优先级排序 - [x] 按优先级排序
- [ ] BE-AGT-002:实现 Agent 状态流转服务(backend only) - [x] BE-AGT-002:实现 Agent 状态流转服务(backend only)
- [ ] Idle -> Busy / OnCall - [x] Idle -> Busy / OnCall
- [ ] Busy / OnCall -> Idle - [x] Busy / OnCall -> Idle
- [ ] 超时无心跳 -> Offline - [x] 超时无心跳 -> Offline
- [ ] API 配额错误 -> Exhausted - [x] API 配额错误 -> Exhausted
- [ ] BE-AGT-003:实现多 slot 竞争处理(backend only) - [x] BE-AGT-003:实现多 slot 竞争处理(backend only)
- [ ] 选最高 priority 执行 - [x] 选最高 priority 执行
- [ ] 其余 slot 标记 Deferred - [x] 其余 slot 标记 Deferred
- [ ] Deferred slot 自动 priority += 1 - [x] Deferred slot 自动 priority += 1
- [ ] BE-AGT-004:实现 Exhausted 恢复时间解析(backend only) - [x] BE-AGT-004:实现 Exhausted 恢复时间解析(backend only)
- [ ] 解析 retry-after / reset in / resets at - [x] 解析 retry-after / reset in / resets at
- [ ] 解析失败时默认 5 小时 - [x] 解析失败时默认 5 小时
- [ ] 到期恢复 Idle - [x] 到期恢复 Idle
## F. HarborForge.Frontend - Proposal / Essential / Story restricted ## F. HarborForge.Frontend - Proposal / Essential / Story restricted
- [ ] FE-PR-001:前端统一重命名 Propose -> Proposal(frontend only) - [x] FE-PR-001:前端统一重命名 Propose -> Proposal(frontend only)
- [ ] 调整页面标题与菜单文案 - [x] 调整页面标题与菜单文案
- [ ] 调整类型名与 API 调用命名 - [x] 调整类型名与 API 调用命名
- [ ] 清理旧 propose 文案 - [x] 清理旧 propose 文案
- [ ] FE-PR-002:Proposal 详情页增加 Essential 列表区(frontend only) - [x] FE-PR-002:Proposal 详情页增加 Essential 列表区(frontend only)
- [ ] 展示 Essential 列表 - [x] 展示 Essential 列表
- [ ] 展示 Essential type / code / title - [x] 展示 Essential type / code / title
- [ ] 处理空状态 - [x] 处理空状态
- [ ] FE-PR-003:新增 Essential 创建/编辑表单(frontend only) - [x] FE-PR-003:新增 Essential 创建/编辑表单(frontend only)
- [ ] 创建表单 - [x] 创建表单
- [ ] 编辑表单 - [x] 编辑表单
- [ ] type 选择器 - [x] type 选择器
- [ ] 提交后局部刷新 - [x] 提交后局部刷新
- [ ] FE-PR-004:Proposal Accept 增加目标 Milestone 选择(frontend only) - [x] FE-PR-004:Proposal Accept 增加目标 Milestone 选择(frontend only)
- [ ] Accept 前展示 milestone 选择控件 - [x] Accept 前展示 milestone 选择控件
- [ ] 校验必须选择 milestone - [x] 校验必须选择 milestone
- [ ] 展示 Accept 成功后的生成结果 - [x] 展示 Accept 成功后的生成结果
- [ ] FE-PR-005:限制前端直接创建 `story/*`(frontend only) - [x] FE-PR-005:限制前端直接创建 `story/*`(frontend only)
- [ ] 从 Task 创建入口移除 story - [x] 从 Task 创建入口移除 story
- [ ] 或将 story 整体设为不可选 - [x] 或将 story 整体设为不可选
- [ ] 调整相关提示文案 - [x] 调整相关提示文案
## G. HarborForge.Frontend - Calendar ## G. HarborForge.Frontend - Calendar
- [ ] FE-CAL-001:新增 Calendar 页面基础骨架(frontend only) - [x] FE-CAL-001:新增 Calendar 页面基础骨架(frontend only)
- [ ] 增加路由入口 - [x] 增加路由入口
- [ ] 增加侧边栏入口 - [x] 增加侧边栏入口
- [ ] 增加基础页面布局 - [x] 增加基础页面布局
- [ ] FE-CAL-002:实现某日 slot 列表展示(frontend only) - [x] FE-CAL-002:实现某日 slot 列表展示(frontend only)
- [ ] 展示时间轴或列表 - [x] 展示时间轴或列表
- [ ] 区分真实 slot 与 plan 虚拟 slot - [x] 区分真实 slot 与 plan 虚拟 slot
- [ ] 展示状态 / 类型 / 时长 / 优先级 - [x] 展示状态 / 类型 / 时长 / 优先级
- [ ] FE-CAL-003:实现计划列表展示(frontend only) - [x] FE-CAL-003:实现计划列表展示(frontend only)
- [ ] 展示计划规则 - [x] 展示计划规则
- [ ] 展示周期参数 - [x] 展示周期参数
- [ ] 支持跳转编辑 - [x] 支持跳转编辑
- [ ] FE-CAL-004:实现创建 / 编辑 / 取消日程交互(frontend only) - [x] FE-CAL-004:实现创建 / 编辑 / 取消日程交互(frontend only)
- [ ] 新建 slot 表单 - [x] 新建 slot 表单
- [ ] 编辑 slot 表单 - [x] 编辑 slot 表单
- [ ] cancel 操作确认 - [x] cancel 操作确认
- [ ] 展示后端 warning - [x] 展示后端 warning
- [ ] FE-CAL-005:实现 Deferred / Exhausted / overlap 等状态提示(frontend only) - [x] FE-CAL-005:实现 Deferred / Exhausted / overlap 等状态提示(frontend only)
- [ ] Deferred 提示 - [x] Deferred 提示
- [ ] overlap 报错展示 - [x] overlap 报错展示
- [ ] workload warning 展示 - [x] workload warning 展示
- [ ] Exhausted 状态展示 - [x] Exhausted 状态展示
## H. HarborForge.Cli - Proposal / Essential / Story restricted ## H. HarborForge.Cli - Proposal / Essential / Story restricted
- [ ] CLI-PR-001:统一 CLI 文案 `propose -> proposal`(cli only) - [x] CLI-PR-001:统一 CLI 文案 `propose -> proposal`(cli only)
- [ ] 调整命令 help 文案 - [x] 调整命令 help 文案
- [ ] 调整输出文本 - [x] 调整输出文本
- [ ] 评估命令名是否兼容保留 `hf propose` - [x] 评估命令名是否兼容保留 `hf propose` → 保留为 alias
- [ ] CLI-PR-002:新增 Essential 相关命令(cli only) - [x] CLI-PR-002:新增 Essential 相关命令(cli only)
- [ ] `hf proposal essential list` - [x] `hf proposal essential list`
- [ ] `hf proposal essential create` - [x] `hf proposal essential create`
- [ ] `hf proposal essential update` - [x] `hf proposal essential update`
- [ ] `hf proposal essential delete` - [x] `hf proposal essential delete`
- [ ] CLI-PR-003:更新 Proposal Accept CLI(cli only) - [x] CLI-PR-003:更新 Proposal Accept CLI(cli only)
- [ ] Accept 时支持传入 milestone - [x] Accept 时支持传入 milestone
- [ ] 展示批量生成的 task 结果 - [x] 展示批量生成的 task 结果
- [ ] 更新帮助文案 - [x] 更新帮助文案
- [ ] CLI-PR-004:限制 CLI 直接创建 `story/*`(cli only) - [x] CLI-PR-004:限制 CLI 直接创建 `story/*`(cli only)
- [ ] 阻止 story 类型直建 - [x] 阻止 story 类型直建
- [ ] 返回明确错误提示 - [x] 返回明确错误提示
- [ ] 提示改走 Proposal Accept - [x] 提示改走 Proposal Accept
## I. HarborForge.Cli - Calendar ## I. HarborForge.Cli - Calendar
- [ ] CLI-CAL-001:新增 `hf calendar` 命令组骨架(cli only) - [x] CLI-CAL-001:新增 `hf calendar` 命令组骨架(cli only)
- [ ] 注册命令组 - [x] 注册命令组
- [ ] 增加 help surface - [x] 增加 help surface
- [ ] 增加 brief help - [x] 增加 brief help
- [ ] CLI-CAL-002:实现 `hf calendar schedule`(cli only) - [x] CLI-CAL-002:实现 `hf calendar schedule`(cli only)
- [ ] 参数解析 - [x] 参数解析
- [ ] 请求构造 - [x] 请求构造
- [ ] 结果输出 - [x] 结果输出
- [ ] CLI-CAL-003:实现 `hf calendar show`(cli only) - [x] CLI-CAL-003:实现 `hf calendar show`(cli only)
- [ ] 日期参数 - [x] 日期参数
- [ ] 列表输出 - [x] 列表输出
- [ ] JSON 输出 - [x] JSON 输出
- [ ] CLI-CAL-004:实现 `hf calendar edit`(cli only) - [x] CLI-CAL-004:实现 `hf calendar edit`(cli only)
- [ ] 支持 slot-id 与 date - [x] 支持 slot-id 与 date
- [ ] PATCH/POST 适配 - [x] PATCH/POST 适配
- [ ] 输出 warning / error - [x] 输出 warning / error
- [ ] CLI-CAL-005:实现 `hf calendar cancel`(cli only) - [x] CLI-CAL-005:实现 `hf calendar cancel`(cli only)
- [ ] 支持 slot-id 与 date - [x] 支持 slot-id 与 date
- [ ] 输出结果 - [x] 输出结果
- [ ] CLI-CAL-006:实现 `hf calendar date-list`(cli only) - [x] CLI-CAL-006:实现 `hf calendar date-list`(cli only)
- [ ] 列出未来已物化日期 - [x] 列出未来已物化日期
- [ ] 适配 JSON 输出 - [x] 适配 JSON 输出
- [ ] CLI-CAL-007:实现 `hf calendar plan-schedule`(cli only) - [x] CLI-CAL-007:实现 `hf calendar plan-schedule`(cli only)
- [ ] 参数解析 `--at --on-day --on-week --on-month` - [x] 参数解析 `--at --on-day --on-week --on-month`
- [ ] 请求构造 - [x] 请求构造
- [ ] 输出结果 - [x] 输出结果
- [ ] CLI-CAL-008:实现 `hf calendar plan-list`(cli only) - [x] CLI-CAL-008:实现 `hf calendar plan-list`(cli only)
- [ ] 列表输出 - [x] 列表输出
- [ ] JSON 输出 - [x] JSON 输出
- [ ] CLI-CAL-009:实现 `hf calendar plan-edit`(cli only) - [x] CLI-CAL-009:实现 `hf calendar plan-edit`(cli only)
- [ ] 参数解析 - [x] 参数解析
- [ ] 请求发送 - [x] 请求发送
- [ ] 输出结果 - [x] 输出结果
- [ ] CLI-CAL-010:实现 `hf calendar plan-cancel`(cli only) - [x] CLI-CAL-010:实现 `hf calendar plan-cancel`(cli only)
- [ ] 参数解析 - [x] 参数解析
- [ ] 请求发送 - [x] 请求发送
- [ ] 输出结果 - [x] 输出结果
## J. HarborForge.OpenclawPlugin / Monitor 联动 ## J. HarborForge.OpenclawPlugin / Monitor 联动
- [ ] PLG-CAL-001:插件侧定义 Calendar 心跳请求格式(plugin only) - [x] PLG-CAL-001:插件侧定义 Calendar 心跳请求格式(plugin only)
- [ ] 明确 claw_identifier 传递方式 - [x] 明确 claw_identifier 传递方式
- [ ] 明确 agent_id 传递方式 - [x] 明确 agent_id 传递方式
- [ ] 明确返回 slot 列表结构 - [x] 明确返回 slot 列表结构
- [ ] PLG-CAL-002:插件侧处理待执行 slot 唤醒(plugin only) - [x] PLG-CAL-002:插件侧处理待执行 slot 唤醒(plugin only)
- [ ] Idle 时唤醒 agent - [x] Idle 时唤醒 agent
- [ ] 透传任务上下文 - [x] 透传任务上下文
- [ ] 执行前更新 attended / started_at / status - [x] 执行前更新 attended / started_at / status
- [ ] PLG-CAL-003:插件侧处理非 Idle / Deferred 分支(plugin only) - [x] PLG-CAL-003:插件侧处理非 Idle / Deferred 分支(plugin only)
- [ ] Agent 非 Idle 时上报 Deferred - [x] Agent 非 Idle 时上报 Deferred
- [ ] 处理多 slot 重排后的重新规划 - [x] 处理多 slot 重排后的重新规划
- [ ] PLG-CAL-004:插件侧处理 ScheduledGatewayRestart(plugin only) - [x] PLG-CAL-004:插件侧处理 ScheduledGatewayRestart(plugin only)
- [ ] 收到事件后持久化状态 - [x] 收到事件后持久化状态
- [ ] 发送最终心跳 - [x] 发送最终心跳
- [ ] 暂停定时任务 - [x] 暂停定时任务
## K. Tests / Integration(按子模块分别补,不混做) ## K. Tests / Integration(按子模块分别补,不混做)
- [ ] TEST-BE-CAL-001:补 Calendar backend 测试(backend tests only) - [x] TEST-BE-CAL-001:补 Calendar backend 测试(backend tests only)
- [ ] 模型测试 - [x] 模型测试
- [ ] API 测试 - [x] API 测试
- [ ] overlap / warning / materialize 测试 - [x] overlap / warning / materialize 测试
- [x] Blocker resolved: `HarborForge.Backend/app/schemas/calendar.py` 的 Python 3.12 + Pydantic 2.5 递归建模问题已通过 schema 类型别名修复，本次已继续补齐 Calendar API / model tests
- [ ] TEST-BE-PR-001:补 Proposal / Essential backend 测试(backend tests only) - [x] TEST-BE-PR-001:补 Proposal / Essential backend 测试(backend tests only)
- [ ] Essential CRUD - [x] Essential CRUD
- [ ] Accept 生成 story tasks - [x] Accept 生成 story tasks
- [ ] story restricted - [x] story restricted
- [ ] TEST-FE-CAL-001:补 Calendar 前端测试(frontend tests only) - [x] TEST-FE-CAL-001:补 Calendar 前端测试(frontend tests only)
- [ ] 页面渲染 - [x] 页面渲染
- [ ] 表单交互 - [x] 表单交互
- [ ] warning / error 展示 - [x] warning / error 展示
- [ ] TEST-FE-PR-001:补 Proposal / Essential 前端测试(frontend tests only) - [x] TEST-FE-PR-001:补 Proposal / Essential 前端测试(frontend tests only)
- [ ] Essential 列表与表单 - [x] Essential 列表与表单
- [ ] Accept milestone 选择 - [x] Accept milestone 选择
- [ ] story 创建入口限制 - [x] story 创建入口限制
- [ ] TEST-CLI-CAL-001:补 Calendar CLI 测试(cli tests only) - [x] TEST-CLI-CAL-001:补 Calendar CLI 测试(cli tests only)
- [ ] 命令解析 - [x] 命令解析
- [ ] JSON 输出 - [x] JSON 输出
- [ ] 错误输出 - [x] 错误输出
- [ ] TEST-CLI-PR-001:补 Proposal / Essential CLI 测试(cli tests only) - [x] TEST-CLI-PR-001:补 Proposal / Essential CLI 测试(cli tests only)
- [ ] Essential 子命令 - [x] Essential 子命令
- [ ] accept milestone 参数 - [x] accept milestone 参数
- [ ] story 限制提示 - [x] story 限制提示