promotion-harness-agent 0.1.3

Add your description here

Promotion Harness Agent

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

安装

开发态安装

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

pip install -e .

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

uv pip install -e .

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

promotion-harness --help

安装态使用

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

pip install promotion-harness-agent
promotion-harness --help

推荐使用方式

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

1. 初始化目标仓库

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

promotion-harness init

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

2. 启动本地 UI 控制台

promotion-harness ui

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

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

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

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

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

4. 命令行补充能力

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

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

其中：

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

一条完整示例

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

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

发布步骤

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

1. 更新版本号

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

[project]
version = "0.1.1"

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

在仓库根目录执行：

npm run package:build

这个命令会自动完成：

• 构建 ui_frontend/dist
• 同步静态文件到 ui_backend/static/
• 生成 dist/*.whl 和 dist/*.tar.gz

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

npm run ui:bundle

3. 本地验证发布产物

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

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：

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

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

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

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

uv publish

或：

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

5. 用户安装与使用

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

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

6. 后续迭代发布流程

后续如果你需要继续迭代，推荐固定按下面的顺序发布：

1. 修改代码
2. 本地验证必要测试
3. 更新 pyproject.toml 中的版本号
4. 重新构建发布产物
5. 再上传到包仓库

一个最常用的最短流程是：

# 1. 修改代码

# 2. 可选：本地验证
uv run pytest

# 3. 更新 pyproject.toml 版本号
# 例如：0.1.0 -> 0.1.1

# 4. 重新构建
rm -rf dist
npm run package:build

# 5. 上传
python -m twine upload dist/*

注意：

• 每次重新发布前都必须提升版本号
• 已经发布到包仓库的版本号不能覆盖上传
• 用户升级时可以执行：

pip install -U promotion-harness-agent

开发态运行入口

如果你是在本仓库里开发 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 仅用于兼容/历史参考，不是主运行路径