# 独立命令行触发设计方案

## 1. 背景与目标
目前 `mcp-keep-feedback` 主要作为 MCP 服务器运行，依赖于支持 MCP 协议的客户端（如 Cursor, Claude Desktop）。为了让 AI 助手在非 MCP 环境下也能使用此交互反馈工具，我们需要支持通过命令行直接触发反馈界面并获取结果。

## 2. 核心架构
采用 **CLI-Server** 架构，复用现有的 Web UI 服务：

1.  **服务端 (Server)**: 现有的 FastAPI Web 服务，负责渲染 UI 并收集反馈。
2.  **触发客户端 (Trigger Client)**: 新增的 CLI 入口，负责向服务端发送 HTTP 请求并阻塞等待结果。

## 3. 实现方案

### A. 服务端增强 (`src/mcp_keep_feedback/web/main.py` & `routes/main_routes.py`)
新增一个专门为 CLI 设计的 API 端点：
*   **端点**: `POST /api/cli/trigger`
*   **参数**: `summary`, `project_dir`
*   **行为**:
    1.  创建新的 `WebFeedbackSession`。
    2.  智能打开浏览器（复用 `manager.smart_open_browser`）。
    3.  调用 `await session.wait_for_feedback()` 挂起请求，实现同步等待。
    4.  用户在 UI 提交后，请求结束并返回反馈内容。

### B. 命令行入口 (`src/mcp_keep_feedback/__main__.py`)
增加 `feedback` 子命令：
*   **用法**: `python -m mcp_keep_feedback feedback --summary "内容" [--dir "目录"] [--json]`
*   **逻辑**:
    1.  检查服务端是否已启动（尝试访问 `/api/session-status`）。
    2.  若未启动，报错提示（或未来考虑后台静默启动）。
    3.  向服务端发送 `POST /api/cli/trigger`。
    4.  阻塞直到收到响应，然后输出反馈内容到 `stdout`。

## 4. 详细流程
1.  **AI 执行**: `mcp-keep-feedback feedback --summary "我已完成重构，请检查结果。"`
2.  **CLI**: 发送请求到 `http://127.0.0.1:8765/api/cli/trigger`。
3.  **Server**: 弹出浏览器，显示重构摘要。
4.  **User**: 在网页输入反馈并提交。
5.  **Server**: 挂起的 API 请求恢复，返回用户输入的文本。
6.  **CLI**: 将用户文本输出到终端。
7.  **AI**: 获取终端输出，完成交互循环。

## 5. 使用说明

### 第一步：启动独立 Web 伺服器
在独立终端中运行以下命令启动持久化服务：
```bash
uv run python -m mcp_keep_feedback web
```

### 第二步：从命令行触发反馈
在任意终端（或 AI 助手的终端）执行：
```bash
# 推荐方式：通过 stdin 传递长汇报 (支持换行和超长内容)
echo "这是完整的任务汇报
包含代码块和详细输出..." | uv run python -m mcp_keep_feedback feedback

# 命名参数方式 (对齐 MCP 工具定义)
uv run python -m mcp_keep_feedback feedback --project-directory "." --full-report-and-output "汇报内容"

# 简写位置参数方式
uv run python -m mcp_keep_feedback feedback . "简短汇报"
```

### 第三步：停止后台服务
如果您需要手动关闭后台运行的 Web 伺服器，可以执行：
```bash
uv run python -m mcp_keep_feedback stop --port 8765
```

### 提示：如何让命令全局可用
如果您希望直接使用 `mcp-keep-feedback` 命令，可以执行：
```bash
uv tool install . --editable
```
这样系统就会注册该快捷命令。

### 第四步：获取结果
命令将阻塞等待用户在网页端提交。提交后，用户输入的文本将直接打印到终端 `stdout`。

## 6. 待办事项 (已完成)
1. [x] 在 `main_routes.py` 中实现 `/api/cli/trigger` 和 `/api/cli/shutdown` 接口。
2. [x] 在 `__main__.py` 中添加 `web`、`feedback` 和 `stop` 命令解析。
3. [x] 实现 CLI 客户端的网络请求、自动启动、远程关闭与结果输出逻辑。
4. [x] 更新文档，说明如何在独立环境中使用。

