Metadata-Version: 2.4
Name: promotion-harness-agent
Version: 0.1.0
Summary: Add your description here
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: agent-client-protocol>=0.9.0
Requires-Dist: mcp<2,>=1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pytest>=9.0.2
Requires-Dist: pytest-asyncio>=1.3.0

# Promotion Harness Agent

本仓库用于验证财经营销部门的 Promotion Harness Agent MVP。

## 安装

### 开发态安装

如果你是在当前源码仓库内开发，推荐使用可编辑安装：

```bash
pip install -e .
```

如果你使用 `uv`，也可以执行：

```bash
uv pip install -e .
```

安装完成后，先用下面的命令确认 CLI 已经可用：

```bash
promotion-harness --help
```

### 安装态使用

如果你已经从 wheel 或包仓库安装了发布版本，也可以直接使用：

```bash
pip install promotion-harness-agent
promotion-harness --help
```

## 推荐使用方式

推荐优先使用前端 UI 页面来运行 Promotion Harness Agent。

### 1. 初始化目标仓库

在你希望作为工作区的目标仓库里执行：

```bash
promotion-harness init
```

这会在当前仓库创建 `.harness/`，并把当前仓库注册为 Promotion Harness Agent 的工作根目录。

### 2. 启动本地 UI 控制台

```bash
promotion-harness ui
```

这个命令会直接启动内置的 FastAPI 服务，并托管打包好的前端静态文件；安装态使用时不再依赖本地 Node/npm。

如果需要覆盖监听地址或端口，可以执行：

```bash
promotion-harness ui --host 127.0.0.1 --port 8010
```

### 3. 在前端页面中发起运行

启动 UI 后，推荐直接在前端页面里输入需求、启动 run、查看当前阶段状态、预览产物，并在需要时通过页面继续恢复或重试流程。

### 4. 命令行补充能力

如果你明确希望绕过前端页面，也可以直接使用命令行：

```bash
promotion-harness run --requirement "写一个测试的加法函数"
promotion-harness resume
```

其中：

- `promotion-harness run`：启动一次新的流水线运行
- `promotion-harness resume`：恢复当前 active run

## 一条完整示例

```bash
cd /path/to/your-repo
promotion-harness init
promotion-harness ui
```

然后在前端页面中输入需求并启动运行。

## 发布步骤

如果你要把当前项目发布成可安装的 CLI，推荐按下面的顺序执行。

### 1. 更新版本号

修改 `pyproject.toml` 中的版本号，例如：

```toml
[project]
version = "0.1.1"
```

### 2. 构建前端并打包 Python 产物

在仓库根目录执行：

```bash
npm run package:build
```

这个命令会自动完成：
- 构建 `ui_frontend/dist`
- 同步静态文件到 `ui_backend/static/`
- 生成 `dist/*.whl` 和 `dist/*.tar.gz`

如果你只想先更新静态文件，也可以单独执行：

```bash
npm run ui:bundle
```

### 3. 本地验证发布产物

建议先在一个干净虚拟环境中验证：

```bash
python -m venv .venv-publish-check
source .venv-publish-check/bin/activate
pip install dist/*.whl
promotion-harness --help
promotion-harness ui --help
```

### 4. 上传到包仓库

如果发布到 PyPI：

```bash
python -m pip install twine
python -m twine upload dist/*
```

如果发布到内部 Python 包仓库：

```bash
python -m twine upload --repository-url https://<your-internal-pypi>/ dist/*
```

如果你们内部使用 `uv publish`，也可以执行：

```bash
uv publish
```

或：

```bash
uv publish --publish-url https://<your-internal-pypi>/legacy/
```

### 5. 用户安装与使用

发布完成后，用户可以直接安装并使用：

```bash
pip install promotion-harness-agent
cd /path/to/repo
promotion-harness init
promotion-harness ui
```

## 开发态运行入口

如果你是在本仓库里开发 Promotion Harness Agent，而不是以安装态使用它，也可以继续直接执行：

- 流水线：`uv run python run.py --requirement "..."`
- UI：`npm run ui:dev`

## 目录约定

- `core/`：状态机、上下文、ACP 运行时、沙箱
- `agents/`：PRD / Tech Spec / Coding 阶段处理逻辑
- `tools/`：正式运行时工具；旧 Coco CLI 路径保留在 `tools/legacy/`
- `tests/`：仓库级正式 pytest 测试
- `scripts/`：一次性调试 / 复现脚本
- `ui_backend/`：本地 UI 后端（FastAPI），读取 `.harness/current_run.json` 与 `.harness/runs/<run_id>/...` 并提供 API
- `ui_frontend/`：本地 UI 前端（Vite + React）
- `docs/`：架构/调研/调试记录（资源建议放在 `docs/assets/`，随手笔记建议放在 `docs/notes/`）
- `.harness/`：Harness 控制面运行产物（current run、progress、trace、stage outputs、acceptance、logs 等）
- 仓库根目录：真实业务工作区；生成代码和测试直接写入目标仓库本身，而不是额外的 `workspace/`

## 测试

- 仓库级测试：`uv run pytest`
- 运行产物测试不属于仓库默认测试收集范围；专用 runner 默认扫描目标仓库下的 `tests/`

## 说明

- 当前主链路通过 ACP 驱动 `coco acp serve`
- `tools/legacy/coco_runner.py` 仅用于兼容/历史参考，不是主运行路径
