From 145daf10fb60967de0827dca152005c11903397d Mon Sep 17 00:00:00 2001 From: aaa <2481034282@qq.com> Date: Sat, 22 Aug 2026 04:54:51 +0800 Subject: [PATCH 1/4] docs: improve open-source discovery and onboarding --- .github/CODEOWNERS | 2 + .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature_request.yml | 54 ++++ README.md | 292 +++++++++------------ README.zh-CN.md | 261 ++++++++++++++++++ docs/assets/cloud-agent-platform-hero.svg | 70 +++++ docs/task-board.md | 8 + 8 files changed, 529 insertions(+), 165 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 README.zh-CN.md create mode 100644 docs/assets/cloud-agent-platform-hero.svg diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..aac549d --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# The project owner reviews repository-wide changes while the maintainer team is small. +* @aopays diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 7913c18..b4333fd 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,7 +1,7 @@ name: Bug report description: Report a reproducible defect without including secrets or private data. title: "[Bug]: " -labels: [bug] +labels: [bug, needs-triage] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..cde689a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Questions and design discussions + url: https://github.com/aopays/Agent/discussions + about: Ask usage questions or discuss ideas before opening an implementation issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..899870f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,54 @@ +name: Feature request +description: Propose a focused improvement or a real-world agent workflow. +title: "[Feature]: " +labels: + - enhancement + - needs-triage +body: + - type: markdown + attributes: + value: | + Thanks for helping improve Cloud Agent Platform. Concrete workflows and measurable outcomes are especially useful. + - type: textarea + id: problem + attributes: + label: Problem or workflow + description: Who has this problem, and what are they trying to complete? + placeholder: As a platform engineer, I need... + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed behavior + description: Describe the smallest useful behavior, including inputs and outputs. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance evidence + description: How could maintainers verify that the feature works? + placeholder: Given..., when..., then... + validations: + required: true + - type: dropdown + id: area + attributes: + label: Area + options: + - Agent runtime and tools + - Sandbox and security + - API and scheduling + - Requirement discovery + - Documentation and onboarding + - Other + validations: + required: true + - type: checkboxes + id: boundaries + attributes: + label: Safety check + options: + - label: This proposal does not require committing secrets or bypassing the sandbox boundary. + required: true diff --git a/README.md b/README.md index 71d0e6f..c6a089c 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,98 @@ # Cloud Agent Platform -> **Turn fuzzy ideas and code repositories into bounded, auditable AI work.** -> 从一句模糊需求到软件设计报告，从一个 Git 仓库到可追踪的 Agent 执行结果。 +**English** | [简体中文](README.zh-CN.md) -![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white) -![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688?logo=fastapi&logoColor=white) -![OpenAI](https://img.shields.io/badge/OpenAI-Responses_API-412991?logo=openai&logoColor=white) -![License](https://img.shields.io/badge/License-MIT-green) -![Status](https://img.shields.io/badge/Status-Alpha-orange) +![Cloud Agent Platform: bounded agents, sandboxed tools, auditable results](docs/assets/cloud-agent-platform-hero.svg) -Cloud Agent Platform 是一个面向 **AI 应用工程师、平台工程团队和技术面试候选人** 的开源 MVP。 -它把“LLM 会调用工具”扩展成一条可以真正运行、取消、审计和演进的工程链路：API 接收任务，调度器投递， -Worker 准备仓库，Agent Runtime 循环推理与调用工具，Sandbox 控制执行边界，最终返回事件、用量与产物。 +[![CI](https://github.com/aopays/Agent/actions/workflows/ci.yml/badge.svg)](https://github.com/aopays/Agent/actions/workflows/ci.yml) +[![Security](https://github.com/aopays/Agent/actions/workflows/security.yml/badge.svg)](https://github.com/aopays/Agent/actions/workflows/security.yml) +[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) +[![OpenAI](https://img.shields.io/badge/OpenAI-Responses_API-412991?logo=openai&logoColor=white)](https://developers.openai.com/api/docs/quickstart) +[![License](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE) +[![GitHub stars](https://img.shields.io/github/stars/aopays/Agent?style=social)](https://github.com/aopays/Agent/stargazers) -项目还提供独立的 **需求挖掘工作台**：用户只需要输入十几个字的模糊需求，系统通过多轮对话补齐用户、目标、 -流程、约束和验收条件，再生成可下载的软件设计报告。 +Turn a fuzzy software idea or a Git repository into a **bounded, observable AI workflow**. Cloud Agent Platform combines requirement discovery, an autonomous model–tool loop, task orchestration, sandbox adapters, event streaming, and downloadable artifacts in one runnable Python project. -> 当前版本是可运行的本地开发与架构演示 MVP，不是生产级托管平台。运行时已经实现单 Agent 工具循环； -> 多 Agent DAG、持久化基础设施和强隔离属于清晰定义的演进路线，而非已经上线的能力。 +> This repository is a production-aware local MVP and architecture reference, not a hosted production service. The single-agent runtime is implemented today; durable infrastructure, stronger isolation, and multi-agent DAG orchestration are documented evolution paths. -## 为什么值得关注 +## Why developers use this project -- **不是一个聊天壳**：包含任务状态机、at-least-once 队列、执行租约、取消传播、预算和产物管理。 -- **不是一个无限循环脚本**：模型轮次、token、墙钟时间、命令时间和工具输出都有上限。 -- **不是把 Docker 当魔法**：明确 local 与 Docker 沙箱的信任边界，并提供路径穿越、符号链接、进程树和资源限制测试。 -- **不是只展示 Happy Path**：失败、超时、取消、重复投递、幂等冲突和清理失败都有显式语义。 -- **不是只画目标架构**：仓库同时保留 As-Is 可运行代码、Next 演进设计和完整 SDLC 文档，方便面试讲解和二次开发。 +- **Learn the engineering behind coding agents** — not just prompting, but queues, leases, cancellation, budgets, idempotency, events, artifacts, and failure semantics. +- **Prototype with a real OpenAI tool loop** — the provider uses the Responses API and structured function calls behind a replaceable interface. +- **Start without an API key** — a deterministic demo provider exercises the full task lifecycle offline. +- **Inspect the security boundary** — command execution is routed through sandbox interfaces with path, timeout, output, process-tree, and network controls. +- **Use it as an interview or architecture reference** — the repository includes requirements, contracts, diagrams, test strategy, security review, release runbook, and an end-to-end SDLC. -## 两条可运行产品链路 +If that is useful to you, consider giving the project a ⭐ so other agent engineers can find it. -### 1. 模糊需求 → 软件设计报告 +## What it can do -适合产品经理、创业者、交付团队和 AI 应用工程师。输入例如： +### 1. Fuzzy requirement → software design report + +Start with a short idea such as: ```text -设计一个物流司机排班用的软件 +Design software for scheduling logistics drivers. ``` -系统通过三轮左右的澄清逐步收集角色、业务目标、关键流程、规则、数据、安全、性能和验收标准，最终生成 -Markdown 软件设计报告。入口：`http://127.0.0.1:8001/discovery`。 +The requirement-discovery workbench asks focused questions over several rounds, separates confirmed facts from assumptions and open decisions, then generates a downloadable Markdown software design report. + +### 2. Natural-language task + Git repository → agent artifact -### 2. 自然语言任务 + Git 仓库 → Agent 产物 +Submit an instruction and a public Git repository. A worker prepares the repository, starts a bounded agent loop, validates tool calls, executes them through a sandbox adapter, records public events, and returns the final result and downloadable artifacts. -适合研发团队、代码治理平台和 Agent Platform 学习者。输入包括自然语言指令、公开 HTTPS Git URL 或允许目录内 -的 `file://` 仓库 URI。平台返回： +The API exposes: -- Task ID 与完整状态； -- 单调递增的公开事件流； -- 工具调用摘要、持续时间和截断信息； -- Agent turns、token 与墙钟用量； -- 可下载的 Markdown/文本产物； -- 安全错误码、取消或超时结果。 +- task state from `CREATED` to a terminal outcome; +- monotonic status, model, tool, budget, and artifact events; +- agent turns, token usage, and wall-clock usage; +- explicit cancellation, timeout, policy, and execution errors; +- Markdown or text artifacts with download endpoints. -## 60 秒离线体验 +## Run it in 60 seconds — no API key -离线 Demo 不需要 OpenAI API Key，也不会产生模型费用： +### Windows PowerShell ```powershell +git clone https://github.com/aopays/Agent.git +cd Agent python -m venv .venv .\.venv\Scripts\python.exe -m pip install -c requirements.lock -e ".[dev]" Copy-Item .env.example .env -# 将 .env 中的 LLM_PROVIDER 改为 demo，SANDBOX_BACKEND 改为 local +$env:LLM_PROVIDER = "demo" +$env:SANDBOX_BACKEND = "local" .\scripts\start.ps1 ``` -启动后打开： - -- 首页： -- 需求挖掘： -- Swagger API： -- 就绪检查： +### Linux and macOS -也可以直接运行确定性示例： - -```powershell -.\.venv\Scripts\python.exe scripts\demo.py +```bash +git clone https://github.com/aopays/Agent.git +cd Agent +python3 -m venv .venv +./.venv/bin/python -m pip install -c requirements.lock -e ".[dev]" +cp .env.example .env +LLM_PROVIDER=demo SANDBOX_BACKEND=local bash scripts/start.sh ``` -该示例扫描 `examples/demo-repo` 中的 TODO/FIXME 并生成报告，用于验证完整任务生命周期。 +Open these pages after startup: -## 接入 OpenAI +- **Product home:** +- **Requirement discovery:** +- **Interactive API docs:** +- **Readiness check:** -复制配置文件： +You can also run the deterministic lifecycle demo directly: ```powershell -Copy-Item .env.example .env +.\.venv\Scripts\python.exe scripts\demo.py ``` -只在本机 `.env` 中填写密钥，不要提交到 Git： +It scans `examples/demo-repo` for TODO/FIXME markers and produces a report without contacting a model provider. + +## Connect OpenAI + +Keep the API key only in your local `.env`; never commit it: ```dotenv LLM_PROVIDER=openai @@ -96,27 +101,17 @@ OPENAI_MODEL=gpt-5.4-mini SANDBOX_BACKEND=local ``` -然后启动： - -```powershell -.\scripts\start.ps1 -``` - -Linux/macOS 使用 `bash scripts/start.sh`。项目通过可替换的 `LLMProvider` 接口调用 OpenAI Responses API， -把本地工具转换成 function tools，并使用 `function_call_output` 继续模型—工具循环。实现与概念可参考 -[OpenAI Developer Quickstart](https://developers.openai.com/api/docs/quickstart) 和 -[Responses API Reference](https://developers.openai.com/api/reference/resources/responses/methods/create)。 +Then start the application with `.\scripts\start.ps1` on Windows or `bash scripts/start.sh` on Linux/macOS. The provider adapter converts registered tools into Responses API function tools and returns observations with `function_call_output`. -`/readyz` 只报告 Provider、模型、Sandbox 和目录状态，不返回 API Key。 +`/readyz` reports the selected provider, model, sandbox, and directory health but never returns the API key. -## 提交仓库任务 +## Submit a repository task -打开 Swagger 的 `POST /v1/tasks`，点击 **Authorize** 并在开发环境输入 `local-demo-token`。设置至少 8 个字符的 -`Idempotency-Key`，请求体示例： +In Swagger, open `POST /v1/tasks`, select **Authorize**, and enter the development token `local-demo-token`. Add an `Idempotency-Key` of at least eight characters and submit: ```json { - "instruction": "读取仓库，找出所有 TODO 和 FIXME，生成 Markdown 报告。", + "instruction": "Read this repository, find every TODO and FIXME, and create a Markdown report.", "repository": { "url": "https://github.com/example/project.git", "ref": "main" @@ -124,7 +119,7 @@ Linux/macOS 使用 `bash scripts/start.sh`。项目通过可替换的 `LLMProvid } ``` -之后依次调用： +Use the returned task ID with: ```text GET /v1/tasks/{taskId} @@ -133,127 +128,96 @@ GET /v1/tasks/{taskId}/artifacts GET /v1/tasks/{taskId}/artifacts/{artifactId} ``` -本地仓库必须位于 `REPOSITORY_IMPORT_ROOT` 下。当前版本只支持公开 HTTPS Git 仓库；私有仓库的任务级临时凭证 -注入属于下一阶段能力，请勿把 Token 拼进 URL。 +Only public HTTPS repositories are supported in the current version. Local `file://` repositories must be under `REPOSITORY_IMPORT_ROOT`. Do not place repository credentials in a URL. -## 架构一览 +## Architecture ```mermaid flowchart LR - User[Web / API Client] --> API[FastAPI Control Plane] - API --> Repo[Task Repository] - API --> Queue[At-least-once Queue] - Queue --> Worker[Worker + Lease + Heartbeat] - Worker --> Prep[Repository Preparer] - Worker --> Runtime[Bounded Agent Runtime] - Runtime --> Provider[Demo / OpenAI Provider] - Runtime --> Registry[Tool Registry + Policy] - Registry --> Sandbox[Local trusted / Docker Sandbox] - Runtime --> Events[Monotonic Event Store] - Worker --> Artifacts[Content-addressed Artifacts] + User[Web / API client] --> API[FastAPI control plane] + API --> Store[Task repository] + API --> Queue[At-least-once queue] + Queue --> Worker[Worker + lease + heartbeat] + Worker --> Prep[Repository preparer] + Worker --> Runtime[Bounded agent runtime] + Runtime --> Provider[Demo / OpenAI provider] + Runtime --> Registry[Tool registry + policy] + Registry --> Sandbox[Local trusted / Docker sandbox] + Runtime --> Events[Monotonic event store] + Worker --> Artifacts[Content-addressed artifacts] Events --> User Artifacts --> User ``` -核心设计是 **控制面与执行面分离**。API 不执行用户命令；Worker 负责租约、仓库、沙箱、Runtime、产物和终态； -Runtime 不直接调用宿主机 shell，而是通过结构化工具与 `SandboxSession` 交互。 +The control plane never executes user commands. The worker owns repository preparation, leases, sandbox lifecycle, runtime invocation, artifact collection, cleanup, and terminal task state. The runtime can call commands only through a validated tool and `SandboxSession` boundary. -完整图解见 [系统架构](docs/system-architecture.md)，逐文件讲解见 [代码导览](docs/code-tour.md)。 +Explore the implementation in the [system architecture](docs/system-architecture.md), [code tour](docs/code-tour.md), and [API contract](docs/contracts/openapi.yaml). -## 技术栈 +## Engineering highlights -- **API / Schema**：Python 3.10+、FastAPI、Pydantic v2、OpenAPI 3.1、SSE。 -- **Agent Runtime**：异步 Python、有界循环、Provider Adapter、结构化 function calling。 -- **调度与可靠性**：进程内队列/仓储/租约 MVP，at-least-once、幂等键、心跳与取消传播。 -- **工具系统**：JSON Schema 校验、权限策略、超时、输出限额、脱敏和结果提交。 -- **沙箱**：可信本地 Adapter、Docker Adapter、非 root、cap-drop、默认禁网和进程树清理。 -- **存储**：进程内事件/任务状态、本地内容寻址产物；接口预留 PostgreSQL、Redis、S3 替换点。 -- **工程质量**：Ruff、mypy strict、pytest、Windows/Linux CI、Docker smoke 与安全标记测试。 +- **API and contracts:** FastAPI, Pydantic v2, OpenAPI 3.1, SSE. +- **Agent runtime:** asynchronous bounded loop, provider adapter, function calling, cancellation, retry, no-progress detection. +- **Scheduling:** task state machine, at-least-once delivery, idempotency, leases, heartbeat, cancellation propagation. +- **Tools:** JSON Schema validation, policy hooks, timeouts, output limits, redaction, result submission. +- **Sandboxing:** trusted local adapter plus Docker adapter, non-root execution, dropped capabilities, default-deny network, process-tree cleanup. +- **Quality:** Ruff, strict mypy, pytest, Windows/Linux CI, Docker smoke tests, CodeQL, dependency audit. -## 代码地图 +## Repository map ```text src/ -├── main.py # FastAPI composition root、SSE、下载与健康检查 -├── platform.py # Provider、Queue、Sandbox、Worker 的依赖装配 -├── worker.py # 从领取任务到终态提交的执行编排 -├── discovery.py # 多轮需求挖掘、结构化会话与报告生成 -├── agent_runtime/ # 模型—工具循环、预算、事件、OpenAI Adapter -├── api/ # Task/Discovery 路由与 Pydantic Schema -├── scheduler/ # 状态机、队列、租约、取消和幂等 -├── sandbox/ # 路径、进程、资源策略、本地与 Docker Session -├── tools/ # Tool Registry、Schema 校验和内置工具 -├── models/ # 任务与 Attempt 领域模型 -└── shared/ # 公共契约、接口与配置 +├── main.py # FastAPI composition root and HTTP endpoints +├── platform.py # Provider, queue, sandbox and worker wiring +├── worker.py # End-to-end execution orchestration +├── discovery.py # Multi-turn requirement discovery and reports +├── agent_runtime/ # Model-tool loop, budgets, events, providers +├── api/ # Task and discovery routes and schemas +├── scheduler/ # State, queue, leases, cancellation, idempotency +├── sandbox/ # Path, process, resource and Docker policies +├── tools/ # Tool registry, schemas and built-in tools +├── models/ # Task and attempt domain models +└── shared/ # Shared contracts, interfaces and settings ``` -## 文档中心 - -- [文档导航](docs/README.md)：按产品、开发、架构、安全、测试和发布查阅。 -- [产品定位与需求](docs/product-positioning.md)：谁会用、解决什么问题、MVP 范围和成功指标。 -- [代码导览](docs/code-tour.md)：像代码解释器一样按入口、调用链和模块阅读项目。 -- [系统架构](docs/system-architecture.md)：上下文、容器、组件、时序、信任边界和演进架构图。 -- [完整软件开发生命周期](docs/sdlc/README.md)：PRD、SRS、数据/API、开发、测试、安全、发布、SRE 与移交。 -- [多 Agent 目标架构](docs/multi-agent-platform-architecture.md)：需求、设计与开发团队的 DAG 和角色边界。 -- [安全策略](SECURITY.md) 与 [沙箱安全边界](docs/security-boundary.md)。 -- [贡献指南](CONTRIBUTING.md) 与 [发布前检查清单](docs/release-checklist.md)。 - -## 已实现、未实现与演进方向 - -### 已实现（As-Is） +## Security boundary -- 任务创建、查询、取消、事件与产物 API； -- 模糊需求的多轮澄清页面与设计报告下载； -- Worker、可见性超时、租约、心跳、幂等与状态机； -- Demo/OpenAI Provider、Agent Loop、工具注册表与预算； -- 本地可信与 Docker 沙箱 Adapter； -- 路径逃逸防护、输出限制、超时、取消和秘密脱敏； -- 自动化单元、集成、端到端和安全测试； -- Docker、Compose、Windows/Linux 启动与 CI 基线。 +- `SANDBOX_BACKEND=local` is for trusted development inputs only and is rejected outside development/test environments. +- Docker is an MVP isolation layer, not a final boundary for arbitrary hostile code. Production deployments should evaluate gVisor, Kata Containers, or Firecracker. +- The sandbox is denied network access by default and is never given the host Docker socket or platform credentials. +- Paths, tool arguments, command duration, output volume, cancellation, and secret redaction are enforced and tested. +- Production use requires real identity, tenant isolation, persistence, rate limits, audit, and managed secrets. -### 下一阶段（Next） +Read the full [threat model](docs/security-boundary.md) and [security policy](SECURITY.md). Vulnerabilities can be reported privately through GitHub Security Advisories. -- PostgreSQL、Redis、S3/MinIO 持久化 Adapter； -- 真实用户与租户、OIDC、RBAC、配额、限流和成本中心； -- 私有 Git 仓库的短期最小权限凭证注入； -- SSE 持续订阅、任务列表和更完整的 Web 控制台； -- 需求/架构/安全/QA 多 Agent DAG 与独立质量门； -- Temporal/Kubernetes、Worker 分池、强沙箱和灾备。 +## What is implemented vs. next -## 安全边界 +Implemented today: -- `SANDBOX_BACKEND=local` 只允许可信开发输入，且在非 development/test 环境被拒绝。 -- Docker 是 MVP 隔离，不是运行任意恶意代码的最终边界；生产应评估 gVisor、Kata 或 Firecracker。 -- 默认不向沙箱开放网络，不挂载宿主 Docker socket，不把密钥放进模型上下文、事件、日志或产物。 -- 所有路径、命令参数和工具输出都必须经过策略与边界检查。 -- 生产环境必须替换默认 Bearer Token，并补齐身份、租户、持久化、限流、审计和密钥管理。 +- task creation, query, cancellation, event and artifact APIs; +- multi-turn requirement discovery and report download; +- demo and OpenAI providers with a bounded agent/tool loop; +- local trusted and Docker sandbox adapters; +- timeout, cancellation, path escape, output and secret controls; +- unit, integration, end-to-end and security tests. -详细威胁模型见 [docs/security-boundary.md](docs/security-boundary.md)。 +Planned evolution: -## 开发验证 +- PostgreSQL, Redis and S3/MinIO adapters; +- authentication, tenancy, RBAC, quotas, rate limits and cost controls; +- temporary least-privilege credentials for private Git repositories; +- richer web console, live task list and persistent SSE subscriptions; +- requirement, architecture, security and QA multi-agent DAGs; +- Temporal/Kubernetes workers and stronger isolation. -```powershell -.\.venv\Scripts\python.exe -m ruff format --check . -.\.venv\Scripts\python.exe -m ruff check . -.\.venv\Scripts\python.exe -m mypy src -.\.venv\Scripts\python.exe -m pytest -q -.\.venv\Scripts\python.exe -m pytest -m security -q -.\.venv\Scripts\python.exe -m compileall -q src tests scripts -``` - -离线端到端烟测： - -```powershell -.\.venv\Scripts\python.exe scripts\smoke_test.py --base-url http://127.0.0.1:8001 -``` +See the detailed [multi-agent target architecture](docs/multi-agent-platform-architecture.md) and [full SDLC documentation](docs/sdlc/README.md). -## 开源协作 +## Contributing -如果这个项目对你理解 Agent 编排、工具调用、沙箱或 AI 应用工程化有帮助，欢迎： +Useful contributions include reproducible agent tasks, eval cases, sandbox attacks, persistence adapters, UI improvements, and documentation fixes. -- ⭐ Star：让更多正在做 Agent Platform 的开发者看到它； -- 🐛 Issue：提交可复现的缺陷、威胁场景或真实业务需求； -- 🧪 Eval：贡献代表性任务、黄金答案和安全回归样例； -- 🔧 Pull Request：优先完善持久化 Adapter、Web Console、质量评测和强隔离。 +1. Read [CONTRIBUTING.md](CONTRIBUTING.md). +2. Start with a focused issue or [GitHub Discussion](https://github.com/aopays/Agent/discussions). +3. Keep the trust boundary and public contracts intact. +4. Add tests for every behavior change. -提交前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。本项目使用 [MIT License](LICENSE)。 +This project is released under the [MIT License](LICENSE). If it helps you build or explain safer agent systems, please ⭐ the repository and share the use case you want it to support next. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..e41fb5d --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,261 @@ +# Cloud Agent Platform + +[English](README.md) | **简体中文** + +> **Turn fuzzy ideas and code repositories into bounded, auditable AI work.** +> 从一句模糊需求到软件设计报告，从一个 Git 仓库到可追踪的 Agent 执行结果。 + +![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white) +![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688?logo=fastapi&logoColor=white) +![OpenAI](https://img.shields.io/badge/OpenAI-Responses_API-412991?logo=openai&logoColor=white) +![License](https://img.shields.io/badge/License-MIT-green) +![Status](https://img.shields.io/badge/Status-Alpha-orange) + +Cloud Agent Platform 是一个面向 **AI 应用工程师、平台工程团队和技术面试候选人** 的开源 MVP。 +它把“LLM 会调用工具”扩展成一条可以真正运行、取消、审计和演进的工程链路：API 接收任务，调度器投递， +Worker 准备仓库，Agent Runtime 循环推理与调用工具，Sandbox 控制执行边界，最终返回事件、用量与产物。 + +项目还提供独立的 **需求挖掘工作台**：用户只需要输入十几个字的模糊需求，系统通过多轮对话补齐用户、目标、 +流程、约束和验收条件，再生成可下载的软件设计报告。 + +> 当前版本是可运行的本地开发与架构演示 MVP，不是生产级托管平台。运行时已经实现单 Agent 工具循环； +> 多 Agent DAG、持久化基础设施和强隔离属于清晰定义的演进路线，而非已经上线的能力。 + +## 为什么值得关注 + +- **不是一个聊天壳**：包含任务状态机、at-least-once 队列、执行租约、取消传播、预算和产物管理。 +- **不是一个无限循环脚本**：模型轮次、token、墙钟时间、命令时间和工具输出都有上限。 +- **不是把 Docker 当魔法**：明确 local 与 Docker 沙箱的信任边界，并提供路径穿越、符号链接、进程树和资源限制测试。 +- **不是只展示 Happy Path**：失败、超时、取消、重复投递、幂等冲突和清理失败都有显式语义。 +- **不是只画目标架构**：仓库同时保留 As-Is 可运行代码、Next 演进设计和完整 SDLC 文档，方便面试讲解和二次开发。 + +## 两条可运行产品链路 + +### 1. 模糊需求 → 软件设计报告 + +适合产品经理、创业者、交付团队和 AI 应用工程师。输入例如： + +```text +设计一个物流司机排班用的软件 +``` + +系统通过三轮左右的澄清逐步收集角色、业务目标、关键流程、规则、数据、安全、性能和验收标准，最终生成 +Markdown 软件设计报告。入口：`http://127.0.0.1:8001/discovery`。 + +### 2. 自然语言任务 + Git 仓库 → Agent 产物 + +适合研发团队、代码治理平台和 Agent Platform 学习者。输入包括自然语言指令、公开 HTTPS Git URL 或允许目录内 +的 `file://` 仓库 URI。平台返回： + +- Task ID 与完整状态； +- 单调递增的公开事件流； +- 工具调用摘要、持续时间和截断信息； +- Agent turns、token 与墙钟用量； +- 可下载的 Markdown/文本产物； +- 安全错误码、取消或超时结果。 + +## 60 秒离线体验 + +离线 Demo 不需要 OpenAI API Key，也不会产生模型费用： + +```powershell +python -m venv .venv +.\.venv\Scripts\python.exe -m pip install -c requirements.lock -e ".[dev]" +Copy-Item .env.example .env +# 将 .env 中的 LLM_PROVIDER 改为 demo，SANDBOX_BACKEND 改为 local +.\scripts\start.ps1 +``` + +启动后打开： + +- 首页： +- 需求挖掘： +- Swagger API： +- 就绪检查： + +也可以直接运行确定性示例： + +```powershell +.\.venv\Scripts\python.exe scripts\demo.py +``` + +该示例扫描 `examples/demo-repo` 中的 TODO/FIXME 并生成报告，用于验证完整任务生命周期。 + +## 接入 OpenAI + +复制配置文件： + +```powershell +Copy-Item .env.example .env +``` + +只在本机 `.env` 中填写密钥，不要提交到 Git： + +```dotenv +LLM_PROVIDER=openai +OPENAI_API_KEY= +OPENAI_MODEL=gpt-5.4-mini +SANDBOX_BACKEND=local +``` + +然后启动： + +```powershell +.\scripts\start.ps1 +``` + +Linux/macOS 使用 `bash scripts/start.sh`。项目通过可替换的 `LLMProvider` 接口调用 OpenAI Responses API， +把本地工具转换成 function tools，并使用 `function_call_output` 继续模型—工具循环。实现与概念可参考 +[OpenAI Developer Quickstart](https://developers.openai.com/api/docs/quickstart) 和 +[Responses API Reference](https://developers.openai.com/api/reference/resources/responses/methods/create)。 + +`/readyz` 只报告 Provider、模型、Sandbox 和目录状态，不返回 API Key。 + +## 提交仓库任务 + +打开 Swagger 的 `POST /v1/tasks`，点击 **Authorize** 并在开发环境输入 `local-demo-token`。设置至少 8 个字符的 +`Idempotency-Key`，请求体示例： + +```json +{ + "instruction": "读取仓库，找出所有 TODO 和 FIXME，生成 Markdown 报告。", + "repository": { + "url": "https://github.com/example/project.git", + "ref": "main" + } +} +``` + +之后依次调用： + +```text +GET /v1/tasks/{taskId} +GET /v1/tasks/{taskId}/events +GET /v1/tasks/{taskId}/artifacts +GET /v1/tasks/{taskId}/artifacts/{artifactId} +``` + +本地仓库必须位于 `REPOSITORY_IMPORT_ROOT` 下。当前版本只支持公开 HTTPS Git 仓库；私有仓库的任务级临时凭证 +注入属于下一阶段能力，请勿把 Token 拼进 URL。 + +## 架构一览 + +```mermaid +flowchart LR + User[Web / API Client] --> API[FastAPI Control Plane] + API --> Repo[Task Repository] + API --> Queue[At-least-once Queue] + Queue --> Worker[Worker + Lease + Heartbeat] + Worker --> Prep[Repository Preparer] + Worker --> Runtime[Bounded Agent Runtime] + Runtime --> Provider[Demo / OpenAI Provider] + Runtime --> Registry[Tool Registry + Policy] + Registry --> Sandbox[Local trusted / Docker Sandbox] + Runtime --> Events[Monotonic Event Store] + Worker --> Artifacts[Content-addressed Artifacts] + Events --> User + Artifacts --> User +``` + +核心设计是 **控制面与执行面分离**。API 不执行用户命令；Worker 负责租约、仓库、沙箱、Runtime、产物和终态； +Runtime 不直接调用宿主机 shell，而是通过结构化工具与 `SandboxSession` 交互。 + +完整图解见 [系统架构](docs/system-architecture.md)，逐文件讲解见 [代码导览](docs/code-tour.md)。 + +## 技术栈 + +- **API / Schema**：Python 3.10+、FastAPI、Pydantic v2、OpenAPI 3.1、SSE。 +- **Agent Runtime**：异步 Python、有界循环、Provider Adapter、结构化 function calling。 +- **调度与可靠性**：进程内队列/仓储/租约 MVP，at-least-once、幂等键、心跳与取消传播。 +- **工具系统**：JSON Schema 校验、权限策略、超时、输出限额、脱敏和结果提交。 +- **沙箱**：可信本地 Adapter、Docker Adapter、非 root、cap-drop、默认禁网和进程树清理。 +- **存储**：进程内事件/任务状态、本地内容寻址产物；接口预留 PostgreSQL、Redis、S3 替换点。 +- **工程质量**：Ruff、mypy strict、pytest、Windows/Linux CI、Docker smoke 与安全标记测试。 + +## 代码地图 + +```text +src/ +├── main.py # FastAPI composition root、SSE、下载与健康检查 +├── platform.py # Provider、Queue、Sandbox、Worker 的依赖装配 +├── worker.py # 从领取任务到终态提交的执行编排 +├── discovery.py # 多轮需求挖掘、结构化会话与报告生成 +├── agent_runtime/ # 模型—工具循环、预算、事件、OpenAI Adapter +├── api/ # Task/Discovery 路由与 Pydantic Schema +├── scheduler/ # 状态机、队列、租约、取消和幂等 +├── sandbox/ # 路径、进程、资源策略、本地与 Docker Session +├── tools/ # Tool Registry、Schema 校验和内置工具 +├── models/ # 任务与 Attempt 领域模型 +└── shared/ # 公共契约、接口与配置 +``` + +## 文档中心 + +- [文档导航](docs/README.md)：按产品、开发、架构、安全、测试和发布查阅。 +- [产品定位与需求](docs/product-positioning.md)：谁会用、解决什么问题、MVP 范围和成功指标。 +- [代码导览](docs/code-tour.md)：像代码解释器一样按入口、调用链和模块阅读项目。 +- [系统架构](docs/system-architecture.md)：上下文、容器、组件、时序、信任边界和演进架构图。 +- [完整软件开发生命周期](docs/sdlc/README.md)：PRD、SRS、数据/API、开发、测试、安全、发布、SRE 与移交。 +- [多 Agent 目标架构](docs/multi-agent-platform-architecture.md)：需求、设计与开发团队的 DAG 和角色边界。 +- [安全策略](SECURITY.md) 与 [沙箱安全边界](docs/security-boundary.md)。 +- [贡献指南](CONTRIBUTING.md) 与 [发布前检查清单](docs/release-checklist.md)。 + +## 已实现、未实现与演进方向 + +### 已实现（As-Is） + +- 任务创建、查询、取消、事件与产物 API； +- 模糊需求的多轮澄清页面与设计报告下载； +- Worker、可见性超时、租约、心跳、幂等与状态机； +- Demo/OpenAI Provider、Agent Loop、工具注册表与预算； +- 本地可信与 Docker 沙箱 Adapter； +- 路径逃逸防护、输出限制、超时、取消和秘密脱敏； +- 自动化单元、集成、端到端和安全测试； +- Docker、Compose、Windows/Linux 启动与 CI 基线。 + +### 下一阶段（Next） + +- PostgreSQL、Redis、S3/MinIO 持久化 Adapter； +- 真实用户与租户、OIDC、RBAC、配额、限流和成本中心； +- 私有 Git 仓库的短期最小权限凭证注入； +- SSE 持续订阅、任务列表和更完整的 Web 控制台； +- 需求/架构/安全/QA 多 Agent DAG 与独立质量门； +- Temporal/Kubernetes、Worker 分池、强沙箱和灾备。 + +## 安全边界 + +- `SANDBOX_BACKEND=local` 只允许可信开发输入，且在非 development/test 环境被拒绝。 +- Docker 是 MVP 隔离，不是运行任意恶意代码的最终边界；生产应评估 gVisor、Kata 或 Firecracker。 +- 默认不向沙箱开放网络，不挂载宿主 Docker socket，不把密钥放进模型上下文、事件、日志或产物。 +- 所有路径、命令参数和工具输出都必须经过策略与边界检查。 +- 生产环境必须替换默认 Bearer Token，并补齐身份、租户、持久化、限流、审计和密钥管理。 + +详细威胁模型见 [docs/security-boundary.md](docs/security-boundary.md)。 + +## 开发验证 + +```powershell +.\.venv\Scripts\python.exe -m ruff format --check . +.\.venv\Scripts\python.exe -m ruff check . +.\.venv\Scripts\python.exe -m mypy src +.\.venv\Scripts\python.exe -m pytest -q +.\.venv\Scripts\python.exe -m pytest -m security -q +.\.venv\Scripts\python.exe -m compileall -q src tests scripts +``` + +离线端到端烟测： + +```powershell +.\.venv\Scripts\python.exe scripts\smoke_test.py --base-url http://127.0.0.1:8001 +``` + +## 开源协作 + +如果这个项目对你理解 Agent 编排、工具调用、沙箱或 AI 应用工程化有帮助，欢迎： + +- ⭐ Star：让更多正在做 Agent Platform 的开发者看到它； +- 🐛 Issue：提交可复现的缺陷、威胁场景或真实业务需求； +- 🧪 Eval：贡献代表性任务、黄金答案和安全回归样例； +- 🔧 Pull Request：优先完善持久化 Adapter、Web Console、质量评测和强隔离。 + +提交前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。本项目使用 [MIT License](LICENSE)。 diff --git a/docs/assets/cloud-agent-platform-hero.svg b/docs/assets/cloud-agent-platform-hero.svg new file mode 100644 index 0000000..b926d80 --- /dev/null +++ b/docs/assets/cloud-agent-platform-hero.svg @@ -0,0 +1,70 @@ + + Cloud Agent Platform + An open-source platform for bounded, auditable AI agent workflows. + + + + + + + + + + + + + + + + + + + + + + + + + OPEN-SOURCE MVP + Cloud Agent Platform + Bounded agents. Sandboxed tools. Auditable results. + + + + + 01 / INPUT + Fuzzy requirement + or Git repository + + + + + + 02 / AGENT LOOP + Reason + call tools + within budgets & policy + + + + + + 03 / OUTPUT + Events + artifacts + traceable and downloadable + + + + OpenAI Responses API + + FastAPI + + Docker Sandbox + + Python + + + + + + + diff --git a/docs/task-board.md b/docs/task-board.md index 12a99a7..9bb4c06 100644 --- a/docs/task-board.md +++ b/docs/task-board.md @@ -10,6 +10,14 @@ ## 当前扩展任务 +### CAP-OSS-001：GitHub 开源发现与仓库治理 + +- 状态：`DONE` +- 所有者：主 Agent +- 范围：GitHub 仓库设置、README 双语入口、项目视觉、社区模板、标签、发布与验证 +- 验收：搜索元数据准确；新用户可在首屏理解价值并离线启动；main、Actions 与安全策略回读通过； + 变更通过本地质量门并以独立 PR 交付 + ### CAP-DISC-001：多轮需求发现与软件设计报告 - 状态：`DONE` From d2dfe19527823278d05629eed1f506b6ad9f60e2 Mon Sep 17 00:00:00 2001 From: aaa <2481034282@qq.com> Date: Sat, 22 Aug 2026 18:31:04 +0800 Subject: [PATCH 2/4] feat: position discovery as an FDE workflow --- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- README.md | 31 ++- README.zh-CN.md | 27 +- docs/README.md | 3 +- docs/assets/cloud-agent-platform-hero.svg | 16 +- docs/code-tour.md | 9 +- docs/contracts/openapi.yaml | 12 +- docs/fde-discovery-playbook.md | 127 ++++++++++ docs/product-positioning.md | 44 +++- docs/requirement-discovery.md | 32 ++- docs/requirements.md | 6 +- .../01-product-and-business-requirements.md | 22 +- .../11-acceptance-handover-traceability.md | 7 +- docs/task-board.md | 8 + src/api/discovery_routes.py | 12 +- src/discovery.py | 233 +++++++++++++----- src/discovery_ui.py | 39 +-- src/main.py | 4 +- tests/discovery/test_service.py | 114 ++++++++- tests/integration/test_discovery_api.py | 9 +- 21 files changed, 575 insertions(+), 184 deletions(-) create mode 100644 docs/fde-discovery-playbook.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index cde689a..1d9eb6f 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ blank_issues_enabled: false contact_links: - name: Questions and design discussions - url: https://github.com/aopays/Agent/discussions + url: https://github.com/aopays/cloud-agent-platform/discussions about: Ask usage questions or discuss ideas before opening an implementation issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 899870f..2eebcc5 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,5 +1,5 @@ name: Feature request -description: Propose a focused improvement or a real-world agent workflow. +description: Propose an FDE discovery improvement or a real-world agent workflow. title: "[Feature]: " labels: - enhancement diff --git a/README.md b/README.md index c6a089c..d655cea 100644 --- a/README.md +++ b/README.md @@ -2,22 +2,25 @@ **English** | [简体中文](README.zh-CN.md) -![Cloud Agent Platform: bounded agents, sandboxed tools, auditable results](docs/assets/cloud-agent-platform-hero.svg) +![Cloud Agent Platform: FDE discovery, bounded agents, auditable delivery](docs/assets/cloud-agent-platform-hero.svg) -[![CI](https://github.com/aopays/Agent/actions/workflows/ci.yml/badge.svg)](https://github.com/aopays/Agent/actions/workflows/ci.yml) -[![Security](https://github.com/aopays/Agent/actions/workflows/security.yml/badge.svg)](https://github.com/aopays/Agent/actions/workflows/security.yml) +[![CI](https://github.com/aopays/cloud-agent-platform/actions/workflows/ci.yml/badge.svg)](https://github.com/aopays/cloud-agent-platform/actions/workflows/ci.yml) +[![Security](https://github.com/aopays/cloud-agent-platform/actions/workflows/security.yml/badge.svg)](https://github.com/aopays/cloud-agent-platform/actions/workflows/security.yml) [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![OpenAI](https://img.shields.io/badge/OpenAI-Responses_API-412991?logo=openai&logoColor=white)](https://developers.openai.com/api/docs/quickstart) [![License](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE) -[![GitHub stars](https://img.shields.io/github/stars/aopays/Agent?style=social)](https://github.com/aopays/Agent/stargazers) +[![GitHub stars](https://img.shields.io/github/stars/aopays/cloud-agent-platform?style=social)](https://github.com/aopays/cloud-agent-platform/stargazers) -Turn a fuzzy software idea or a Git repository into a **bounded, observable AI workflow**. Cloud Agent Platform combines requirement discovery, an autonomous model–tool loop, task orchestration, sandbox adapters, event streaming, and downloadable artifacts in one runnable Python project. +An open-source **FDE discovery workspace and Cloud Agent runtime**. It helps Forward Deployed Engineers turn messy customer conversations into evidence-backed, executable technical plans, then run well-scoped repository tasks through bounded, observable AI workflows. + +The discovery workflow is designed to stop unproductive meetings: it follows vague words to numbers and examples, separates facts from assumptions, identifies decision makers and system owners, and keeps asking about blockers until the result can be reviewed by architecture, engineering, QA, security, and the customer. > This repository is a production-aware local MVP and architecture reference, not a hosted production service. The single-agent runtime is implemented today; durable infrastructure, stronger isolation, and multi-agent DAG orchestration are documented evolution paths. ## Why developers use this project - **Learn the engineering behind coding agents** — not just prompting, but queues, leases, cancellation, budgets, idempotency, events, artifacts, and failure semantics. +- **Run disciplined FDE discovery** — capture customer evidence, As-Is pain, scope, owners, data, integrations, acceptance thresholds, risks, and Go/No-Go conditions. - **Prototype with a real OpenAI tool loop** — the provider uses the Responses API and structured function calls behind a replaceable interface. - **Start without an API key** — a deterministic demo provider exercises the full task lifecycle offline. - **Inspect the security boundary** — command execution is routed through sandbox interfaces with path, timeout, output, process-tree, and network controls. @@ -27,15 +30,17 @@ If that is useful to you, consider giving the project a ⭐ so other agent engin ## What it can do -### 1. Fuzzy requirement → software design report +### 1. Customer conversation → FDE technical discovery package Start with a short idea such as: ```text -Design software for scheduling logistics drivers. +We want to use AI to improve logistics driver scheduling. ``` -The requirement-discovery workbench asks focused questions over several rounds, separates confirmed facts from assumptions and open decisions, then generates a downloadable Markdown software design report. +The FDE workbench follows five stages: business outcome and decision authority, As-Is evidence, scope/rules/exceptions, data/integration/security, and PoC/MVP acceptance. Three rounds unlock a draft; unresolved implementation blockers trigger further questions, up to twelve user rounds. The result is a downloadable technical plan with evidence, open decisions, architecture, acceptance thresholds, delivery gates, and an engineering handoff checklist. + +Read the [FDE customer discovery playbook](docs/fde-discovery-playbook.md). ### 2. Natural-language task + Git repository → agent artifact @@ -54,8 +59,8 @@ The API exposes: ### Windows PowerShell ```powershell -git clone https://github.com/aopays/Agent.git -cd Agent +git clone https://github.com/aopays/cloud-agent-platform.git +cd cloud-agent-platform python -m venv .venv .\.venv\Scripts\python.exe -m pip install -c requirements.lock -e ".[dev]" Copy-Item .env.example .env @@ -67,8 +72,8 @@ $env:SANDBOX_BACKEND = "local" ### Linux and macOS ```bash -git clone https://github.com/aopays/Agent.git -cd Agent +git clone https://github.com/aopays/cloud-agent-platform.git +cd cloud-agent-platform python3 -m venv .venv ./.venv/bin/python -m pip install -c requirements.lock -e ".[dev]" cp .env.example .env @@ -216,7 +221,7 @@ See the detailed [multi-agent target architecture](docs/multi-agent-platform-arc Useful contributions include reproducible agent tasks, eval cases, sandbox attacks, persistence adapters, UI improvements, and documentation fixes. 1. Read [CONTRIBUTING.md](CONTRIBUTING.md). -2. Start with a focused issue or [GitHub Discussion](https://github.com/aopays/Agent/discussions). +2. Start with a focused issue or [GitHub Discussion](https://github.com/aopays/cloud-agent-platform/discussions). 3. Keep the trust boundary and public contracts intact. 4. Add tests for every behavior change. diff --git a/README.zh-CN.md b/README.zh-CN.md index e41fb5d..aea21e1 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -3,7 +3,7 @@ [English](README.md) | **简体中文** > **Turn fuzzy ideas and code repositories into bounded, auditable AI work.** -> 从一句模糊需求到软件设计报告，从一个 Git 仓库到可追踪的 Agent 执行结果。 +> 从客户的一句模糊需求到可执行技术方案，从一个 Git 仓库到可追踪的 Agent 执行结果。 ![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688?logo=fastapi&logoColor=white) @@ -11,12 +11,13 @@ ![License](https://img.shields.io/badge/License-MIT-green) ![Status](https://img.shields.io/badge/Status-Alpha-orange) -Cloud Agent Platform 是一个面向 **AI 应用工程师、平台工程团队和技术面试候选人** 的开源 MVP。 +Cloud Agent Platform 是一个面向 **FDE、解决方案架构师、AI 应用工程师和平台工程团队** 的开源 MVP。 它把“LLM 会调用工具”扩展成一条可以真正运行、取消、审计和演进的工程链路：API 接收任务，调度器投递， Worker 准备仓库，Agent Runtime 循环推理与调用工具，Sandbox 控制执行边界，最终返回事件、用量与产物。 -项目还提供独立的 **需求挖掘工作台**：用户只需要输入十几个字的模糊需求，系统通过多轮对话补齐用户、目标、 -流程、约束和验收条件，再生成可下载的软件设计报告。 +项目的第一入口是 **FDE 客户需求发现工作台**：FDE 可以输入企业负责人的十几个字模糊需求，系统围绕业务结果、 +决策人、现状证据、范围与非目标、规则、数据、集成、安全和验收继续追问，直到形成可交给架构、开发、QA、 +安全和客户共同评审的技术方案草案。 > 当前版本是可运行的本地开发与架构演示 MVP，不是生产级托管平台。运行时已经实现单 Agent 工具循环； > 多 Agent DAG、持久化基础设施和强隔离属于清晰定义的演进路线，而非已经上线的能力。 @@ -31,16 +32,19 @@ Worker 准备仓库，Agent Runtime 循环推理与调用工具，Sandbox 控制 ## 两条可运行产品链路 -### 1. 模糊需求 → 软件设计报告 +### 1. 客户沟通 → FDE 技术发现与可执行方案 -适合产品经理、创业者、交付团队和 AI 应用工程师。输入例如： +适合 FDE、解决方案架构师、售前技术顾问和交付负责人。输入例如： ```text -设计一个物流司机排班用的软件 +我们想用 AI 提升物流司机排班效率 ``` -系统通过三轮左右的澄清逐步收集角色、业务目标、关键流程、规则、数据、安全、性能和验收标准，最终生成 -Markdown 软件设计报告。入口：`http://127.0.0.1:8001/discovery`。 +系统按业务结果与决策人、As-Is 证据、范围/规则/异常、数据/集成/安全、PoC/MVP 验收五个阶段推进。 +三轮后可以生成草案，但关键阻塞项未关闭时仍会继续追问，单会话最多十二轮。最终输出客户证据、事实/假设/决策、 +技术架构、验收阈值、Go/No-Go 条件和研发移交清单。入口：`http://127.0.0.1:8001/discovery`。 + +详细方法见 [FDE 客户需求发现工作手册](docs/fde-discovery-playbook.md)。 ### 2. 自然语言任务 + Git 仓库 → Agent 产物 @@ -179,7 +183,7 @@ src/ ├── main.py # FastAPI composition root、SSE、下载与健康检查 ├── platform.py # Provider、Queue、Sandbox、Worker 的依赖装配 ├── worker.py # 从领取任务到终态提交的执行编排 -├── discovery.py # 多轮需求挖掘、结构化会话与报告生成 +├── discovery.py # FDE 多轮客户发现、就绪门禁与技术方案生成 ├── agent_runtime/ # 模型—工具循环、预算、事件、OpenAI Adapter ├── api/ # Task/Discovery 路由与 Pydantic Schema ├── scheduler/ # 状态机、队列、租约、取消和幂等 @@ -192,6 +196,7 @@ src/ ## 文档中心 - [文档导航](docs/README.md)：按产品、开发、架构、安全、测试和发布查阅。 +- [FDE 客户发现手册](docs/fde-discovery-playbook.md)：访谈阶段、证据模型、就绪门禁和研发移交。 - [产品定位与需求](docs/product-positioning.md)：谁会用、解决什么问题、MVP 范围和成功指标。 - [代码导览](docs/code-tour.md)：像代码解释器一样按入口、调用链和模块阅读项目。 - [系统架构](docs/system-architecture.md)：上下文、容器、组件、时序、信任边界和演进架构图。 @@ -205,7 +210,7 @@ src/ ### 已实现（As-Is） - 任务创建、查询、取消、事件与产物 API； -- 模糊需求的多轮澄清页面与设计报告下载； +- 面向 FDE 的多轮客户发现页面与可执行技术方案下载； - Worker、可见性超时、租约、心跳、幂等与状态机； - Demo/OpenAI Provider、Agent Loop、工具注册表与预算； - 本地可信与 Docker 沙箱 Adapter； diff --git a/docs/README.md b/docs/README.md index 61afdb8..31fc9c3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,7 +11,8 @@ ## 想运行或二次开发 -- [需求挖掘功能](requirement-discovery.md) +- [FDE 客户需求发现工作手册](fde-discovery-playbook.md) +- [FDE 多轮需求发现功能](requirement-discovery.md) - [MVP 需求基线](requirements.md) - [MVP 架构基线](architecture.md) - [验收标准](acceptance-criteria.md) diff --git a/docs/assets/cloud-agent-platform-hero.svg b/docs/assets/cloud-agent-platform-hero.svg index b926d80..5abb9d5 100644 --- a/docs/assets/cloud-agent-platform-hero.svg +++ b/docs/assets/cloud-agent-platform-hero.svg @@ -1,6 +1,6 @@ Cloud Agent Platform - An open-source platform for bounded, auditable AI agent workflows. + FDE discovery and bounded, auditable AI agent workflows. @@ -27,30 +27,30 @@ OPEN-SOURCE MVP Cloud Agent Platform - Bounded agents. Sandboxed tools. Auditable results. + Customer evidence → executable plan → bounded agents. 01 / INPUT - Fuzzy requirement + Customer need or Git repository - 02 / AGENT LOOP - Reason + call tools - within budgets & policy + 02 / DISCOVER + Probe + structure + facts, owners, constraints 03 / OUTPUT - Events + artifacts - traceable and downloadable + Technical plan + executable and auditable diff --git a/docs/code-tour.md b/docs/code-tour.md index 8a2fdba..618cfa8 100644 --- a/docs/code-tour.md +++ b/docs/code-tour.md @@ -203,13 +203,14 @@ no-new-privileges、CPU/内存/PID/临时盘限制。Docker 控制命令与用 `LocalArtifactStore` 使用 SHA-256 和逻辑名称实现内容校验与幂等，限制单产物大小，并把真实存储路径隐藏在 API 响应之后。当前元数据在内存中，重启后不恢复；生产 Adapter 应使用 PostgreSQL + S3/MinIO。 -## 11. 需求挖掘：`src/discovery.py` +## 11. FDE 客户需求发现：`src/discovery.py` -Discovery 是与仓库任务并列的产品模块： +Discovery 是与仓库任务并列的产品模块，也是 FDE 进入客户后的前置工作台： - `DiscoveryService` 管理会话、消息、状态和最终报告； -- `DemoDiscoveryAssistant` 提供可重复、无需费用的确定性流程； -- `ProviderDiscoveryAssistant` 使用同一 LLMProvider 做开放式澄清； +- `DemoDiscoveryAssistant` 提供可重复、无需费用的确定性 FDE 访谈流程； +- `ProviderDiscoveryAssistant` 使用同一 LLMProvider 按就绪门禁追问实施阻塞项； +- 报告严格区分事实、假设、决策、风险和开放问题，并形成研发与 QA 移交清单； - `src/discovery_ui.py` 是无构建步骤的单页演示 UI； - `src/api/discovery_routes.py` 提供创建、追加消息、完成和下载接口。 diff --git a/docs/contracts/openapi.yaml b/docs/contracts/openapi.yaml index 5a11b78..6ce77c7 100644 --- a/docs/contracts/openapi.yaml +++ b/docs/contracts/openapi.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: Cloud Agent Platform API version: 0.1.0 - description: P0 contract for task lifecycle, events, and artifacts. + description: P0 contract for FDE discovery, task lifecycle, events, and artifacts. servers: - url: http://localhost:8000 security: @@ -11,7 +11,7 @@ paths: /v1/discovery-sessions: post: operationId: createDiscoverySession - summary: Start a multi-turn requirement discovery conversation + summary: Start a multi-turn FDE customer discovery conversation requestBody: required: true content: @@ -45,7 +45,7 @@ paths: /v1/discovery-sessions/{sessionId}/messages: post: operationId: addDiscoveryMessage - summary: Answer questions and continue requirement discovery + summary: Record customer evidence and continue FDE discovery parameters: - $ref: '#/components/parameters/DiscoverySessionId' requestBody: @@ -68,7 +68,7 @@ paths: /v1/discovery-sessions/{sessionId}/finalize: post: operationId: finalizeDiscoverySession - summary: Generate the software design report + summary: Generate the FDE technical discovery and solution report parameters: - $ref: '#/components/parameters/DiscoverySessionId' responses: @@ -83,12 +83,12 @@ paths: /v1/discovery-sessions/{sessionId}/report: get: operationId: downloadDiscoveryReport - summary: Download the finalized Markdown software design report + summary: Download the finalized Markdown FDE technical solution parameters: - $ref: '#/components/parameters/DiscoverySessionId' responses: '200': - description: Software design report + description: FDE technical discovery and solution report content: text/markdown: schema: diff --git a/docs/fde-discovery-playbook.md b/docs/fde-discovery-playbook.md new file mode 100644 index 0000000..2b2dcab --- /dev/null +++ b/docs/fde-discovery-playbook.md @@ -0,0 +1,127 @@ +# FDE 客户需求发现工作手册 + +## 1. 产品使命 + +本项目把需求发现模块定位为 Forward Deployed Engineer（FDE）的前置工作台。它服务于 FDE、解决方案架构师、 +AI 应用工程师和技术交付负责人第一次进入客户现场的阶段：把企业负责人的业务语言、现状抱怨和零散想法，转成 +一份能够被架构、开发、QA、安全和客户共同评审的技术发现包。 + +它不追求“多聊几轮”，而追求每次沟通都减少一个实施风险，最终回答五个问题： + +1. 客户为什么现在必须解决这个问题？ +2. 谁使用、谁提供数据、谁承担变更、谁最终决策？ +3. 第一版具体做什么、不做什么？ +4. 技术和组织前置条件是否真实存在？ +5. 用什么证据决定 PoC/MVP 成功或停止？ + +## 2. 需要解决的真实痛点 + +- 客户负责人描述的是方案名或症状，例如“做一个 AI 平台”，而不是可验证的问题。 +- 销售、业务、技术和一线用户使用不同语言，同一个词对应不同预期。 +- 会议反复讨论功能，却没有现状基线、数据样例、系统负责人和决策权限。 +- FDE 过早承诺技术方案，后续才发现数据拿不到、接口不存在、安全不允许或验收标准不一致。 +- 需求从 FDE 移交到研发时丢失上下文，最终变成范围蔓延、重复返工和责任争议。 + +## 3. 拒绝无效沟通的原则 + +### 3.1 从抽象词追到证据 + +客户说“系统要快”，继续追问哪个操作、现状耗时、目标耗时、测量口径和峰值规模。客户说“要智能”，继续追问 +由谁做决策、允许多大错误、错误成本、人工复核方式和可用训练或评测数据。 + +### 3.2 不重复已回答的问题 + +每轮先复用已有证据，只询问会阻塞范围、技术可行性、验收或交付承诺的缺口。问题数量控制在 3 到 5 个， +让客户可以在一次回复中给出高质量答案。 + +### 3.3 不把假设伪装成客户需求 + +所有内容按以下类型管理： + +- `FACT`：客户明确表达且最好有业务数据、文档或实例支撑。 +- `ASSUMPTION`：为了形成草案暂时采用，必须有责任人和确认日期。 +- `DECISION`：经过有权限的人确认的范围、规则或技术选择。 +- `RISK`：可能影响成本、进度、安全、质量或可行性的事项。 +- `OPEN`：尚未回答且会阻塞实施或验收的问题。 + +### 3.4 先确定问题，再选择技术 + +在业务结果、As-Is 流程、规模、边界和验收证据没有形成之前，不承诺微服务、模型、数据库或具体供应商。 +技术栈必须服务于已确认约束，而不是反过来创造需求。 + +## 4. FDE 访谈阶段 + +### 阶段 A：业务结果与决策机制 + +确认需求发起人、业务负责人、最终决策人、一线用户、预算和 Go/No-Go 机制。要求客户说明为什么现在做、 +不做的损失、希望改变的业务指标，以及谁有权确认这些指标。 + +### 阶段 B：As-Is 流程与痛点证据 + +使用一个最近发生的真实案例走查当前流程，记录每一步的负责人、输入、输出、等待时间、错误、返工和人工兜底。 +至少获得一种证据：样例数据、流程截图、工单、报表、会议纪要或系统日志。 + +### 阶段 C：范围、规则与异常 + +确定主流程、硬规则、常见例外、审批、人工覆盖和审计要求。明确 MVP 范围、非目标和变更流程，避免把未来愿景 +包装成当前承诺。 + +### 阶段 D：数据、集成与安全 + +为每个数据源和外部系统确认业务用途、负责人、接口、字段样例、规模、质量、更新频率、测试环境、权限、 +敏感等级、失败策略和预计可用日期。 + +### 阶段 E：PoC、MVP 与交付承诺 + +把成功写成可现场执行的 Given/When/Then，定义现状基线、目标阈值、测量窗口、数据来源和验收负责人。 +确认时间、预算、客户配合人、部署条件、运维责任和停止条件。 + +## 5. 技术方案就绪门禁 + +完成三轮只代表可以生成草案。以下九项没有阻塞缺口，才可以把方案标记为“可进入工程评审”： + +1. 业务结果、现状基线和成功指标； +2. 业务负责人、技术负责人、数据负责人和最终决策人； +3. 一线用户、场景、频率、规模和主流程； +4. MVP 范围、非目标、优先级和变更机制； +5. 业务规则、异常、人工兜底和审计要求； +6. 数据来源、样例、质量和责任人； +7. 外部系统、接口、测试环境和集成失败策略； +8. 安全、隐私、合规、部署和运维边界； +9. PoC/MVP 验收阈值、预算时间和 Go/No-Go 流程。 + +用户可以提前生成报告，但系统必须把缺口保留为开放问题，而不是自动补成客户承诺。单会话最多 12 个用户轮次， +用于避免无限对话；达到上限仍有阻塞项时，应升级为人工专题会议。 + +## 6. 最终交付物 + +FDE 技术发现报告至少包含： + +- 执行摘要和原始需求； +- 客户原话、事实、假设、决策、风险和开放项； +- Stakeholder/决策地图和责任边界； +- As-Is 流程、量化痛点和 To-Be 业务目标； +- MVP 范围、非目标、可追踪需求 ID、规则和异常； +- 数据与集成责任矩阵； +- 技术架构、接口、安全、可靠性和非功能要求； +- PoC 与 MVP 验收标准； +- 交付计划、依赖、风险和 Go/No-Go 条件； +- 给架构、开发、QA 和安全团队的移交清单。 + +## 7. 成功指标 + +- 首次客户访谈后关键维度覆盖率； +- 每个关键结论的证据关联率； +- 报告中未确认假设的数量和关闭周期； +- 进入开发后因需求误解产生的返工率； +- PoC 验收争议率和 Go/No-Go 决策周期； +- FDE 到研发移交后新增阻塞问题的数量； +- 客户会议时长不作为单独成功指标，减少无效轮次同时提高决策密度才是目标。 + +## 8. 产品边界 + +- 工具辅助 FDE 组织问题和证据，不替代客户业务负责人做决定。 +- 报告是技术方案草案，不是合同、法律意见、安全认证或自动交付承诺。 +- 对话质量取决于客户输入；关键事实必须由有权限的人确认。 +- 高风险行业仍需领域专家、法务、安全和合规团队参与。 +- 当前会话使用进程内存，不具备生产级 CRM、权限、长期留存和多人协作能力。 diff --git a/docs/product-positioning.md b/docs/product-positioning.md index ec9b7b4..e68da10 100644 --- a/docs/product-positioning.md +++ b/docs/product-positioning.md @@ -2,13 +2,20 @@ ## 1. 一句话定位 -Cloud Agent Platform 是一个面向 AI 应用开发与平台工程学习的开源执行底座：它把模糊需求和代码仓库转化为 -受预算、策略和沙箱约束的 Agent 工作，并把过程事件、错误、用量和产物完整返回。 +Cloud Agent Platform 是 FDE 的客户发现前置工作台和开源 Agent 执行底座：它把企业负责人的模糊表达转成 +有证据、可实施、可验收的技术方案，再把明确的仓库任务交给受预算、策略和沙箱约束的 Agent 执行。 ## 2. 给谁使用 ### 核心用户 +**Forward Deployed Engineer（FDE）与解决方案架构师** + +- 需要在客户交流早期识别真实业务结果、决策人、现状流程、规模和范围边界。 +- 需要拒绝没有证据的抽象讨论，把“快、智能、好用”追问成数字、样例和可观察行为。 +- 需要提前发现数据、接口、安全、预算、客户配合和验收条件等实施阻塞项。 +- 需要把访谈记录转成架构、开发、QA 和客户可以共同评审的技术发现包。 + **AI 应用工程师** - 需要学习或搭建 Agent Loop、function calling、工具注册表和 Provider Adapter。 @@ -29,13 +36,24 @@ Cloud Agent Platform 是一个面向 AI 应用开发与平台工程学习的开 ### 邻近用户 -**产品经理、创业者和交付顾问**可以使用需求挖掘页面，把“做一个物流司机排班软件”这类输入逐轮补全为可评审的 -软件设计报告。当前 Demo 对物流场景有确定性模板；使用 OpenAI Provider 时可处理更开放的需求，但输出仍需要 -业务与技术负责人确认。 +**产品经理、创业者、售前顾问和交付负责人**也可以使用 FDE 工作台，把“做一个物流司机排班软件”这类输入 +逐轮补全为可评审技术方案。当前 Demo 对物流场景有确定性模板；使用 OpenAI Provider 时可处理更开放的需求， +但输出仍需要客户业务负责人和技术负责人确认。 ## 3. 要解决的问题 -传统 LLM 工具 Demo 常见四个断点： +FDE 与企业负责人沟通时经常出现五个断点： + +1. 客户说的是方案名或症状，没有可量化的业务结果和现状证据； +2. 业务负责人、使用者、数据负责人、技术负责人和决策人没有明确区分； +3. 会议反复讨论功能，但范围、非目标、异常、人工兜底和验收标准始终模糊； +4. FDE 过早承诺技术方案，后续才发现数据拿不到、接口不存在或安全不允许； +5. 访谈内容移交研发时丢失上下文，产生范围蔓延、重复返工和验收争议。 + +需求发现模块通过分阶段访谈、证据分类和技术方案就绪门禁解决这些问题。详细方法见 +[FDE 客户需求发现工作手册](fde-discovery-playbook.md)。 + +作为执行底座，传统 LLM 工具 Demo 还常见四个断点： 1. 只展示一次模型调用，没有任务生命周期和失败语义； 2. 直接在宿主机执行命令，没有可信边界和资源上限； @@ -50,11 +68,11 @@ Cloud Agent Platform 是一个面向 AI 应用开发与平台工程学习的开 ## 4. 核心业务场景 -### 场景 A：需求发现 +### 场景 A：FDE 客户需求发现与技术移交 -输入：模糊的软件想法和可选前置条件。 -过程：创建会话 → 多轮澄清 → 用户补充 → 准备完成 → 生成报告。 -输出：需求摘要、用户与角色、范围、流程、非功能需求、风险、假设、未决问题和开发建议。 +输入：企业负责人的模糊需求、已知背景和前置条件。 +过程：业务结果与决策人 → As-Is 证据 → 范围/规则/异常 → 数据/集成/安全 → PoC 验收与交付条件。 +输出：事实/假设/决策/风险、角色责任、范围与非目标、技术架构、验收阈值、Go/No-Go 条件和研发移交清单。 ### 场景 B：仓库分析 @@ -79,7 +97,9 @@ Cloud Agent Platform 是一个面向 AI 应用开发与平台工程学习的开 - FR-07：排队和运行中的任务均可取消，取消传播到工具协程和进程树。 - FR-08：平台只记录公开行动摘要、工具事件、状态和用量，不保存私有思维链。 - FR-09：文本产物可列出、校验哈希并下载，重复提交保持幂等。 -- FR-10：用户可通过多轮对话把模糊需求整理为软件设计报告。 +- FR-10：FDE 可通过多轮对话把模糊客户需求整理为带证据和开放项的可执行技术方案。 +- FR-11：系统在达到最少轮次后仍按就绪门禁追问阻塞项，不把“可生成草案”误写为“需求完整”。 +- FR-12：报告必须区分事实、假设、决策、风险和开放问题，并包含研发与 QA 移交清单。 完整可追踪需求见 [软件需求规格说明书](sdlc/02-software-requirements-specification.md)。 @@ -101,6 +121,8 @@ Cloud Agent Platform 是一个面向 AI 应用开发与平台工程学习的开 - 每个成功任务的 token、模型费用和工具调用数； - 取消完成时间和孤儿进程/沙箱数量； - 需求报告的事实覆盖率、未确认假设率和人工返工率； +- 关键结论的证据关联率、开放项关闭周期和 FDE 到研发移交后的新增阻塞数； +- PoC 验收争议率、Go/No-Go 决策周期和因需求误解产生的开发返工率； - 路径逃逸、秘密泄露、越权工具和网络访问的阻断率； - Worker 崩溃后的恢复成功率与重复产物率。 diff --git a/docs/requirement-discovery.md b/docs/requirement-discovery.md index 8fb3765..7964cb7 100644 --- a/docs/requirement-discovery.md +++ b/docs/requirement-discovery.md @@ -1,13 +1,17 @@ -# 多轮需求发现与软件设计报告 +# FDE 多轮客户需求发现与可执行技术方案 ## 产品目标 -在仓库执行任务之前增加一个对话式控制面。用户可以只提交十几个字的模糊需求， -需求发现 Agent 通过多轮问题确认用户、场景、规模、规则、异常、数据、集成、成功指标和交付约束， -最后生成 Markdown 软件设计报告。 +在仓库执行任务之前增加一个面向 Forward Deployed Engineer 的对话式控制面。FDE 可以只提交客户十几个字的 +模糊需求，Discovery Agent 通过多轮问题确认业务结果、决策人、As-Is 证据、规模、范围与非目标、规则、异常、 +数据和系统负责人、安全边界、验收阈值和交付约束，最后生成 Markdown 技术发现与方案报告。 + +产品核心不是延长会议，而是拒绝无效沟通：已经回答的问题不重复问；抽象词继续追到数字、样例或可观察行为； +所有内容严格区分事实、假设、决策、风险和开放问题。完整方法见 +[FDE 客户需求发现工作手册](fde-discovery-playbook.md)。 需求发现不会直接执行用户代码，也不需要仓库地址。它与 `/v1/tasks` 的仓库执行流程相互独立； -未来可以把已确认的报告作为执行 Agent 的任务输入。 +未来可以把已确认的报告作为执行 Agent 和多 Agent 开发团队的任务输入。 ## 使用入口 @@ -20,22 +24,23 @@ 1. `POST /v1/discovery-sessions`：提交模糊需求和可选前置条件。 2. `POST /v1/discovery-sessions/{sessionId}/messages`：回答 Agent 的问题。 3. `GET /v1/discovery-sessions/{sessionId}`：获取完整对话和状态。 -4. `POST /v1/discovery-sessions/{sessionId}/finalize`：生成软件设计报告。 +4. `POST /v1/discovery-sessions/{sessionId}/finalize`：生成 FDE 技术方案草案。 5. `GET /v1/discovery-sessions/{sessionId}/report`：下载 Markdown 报告。 状态含义： - `DISCOVERY`：仍在进行需求澄清。 -- `READY`：已完成建议的三轮澄清，可以生成第一版报告。 +- `READY`：已完成建议的最少三轮，可以生成第一版草案；不代表需求已经完整。 - `FINALIZED`：报告已经生成，会话只读。 -用户可在三轮前提前生成报告。系统必须把未确认信息标记为默认假设或待确认项， -不得把模型推测伪装为用户确认。 +用户可在三轮前提前生成报告，也可以继续至最多 12 轮。达到三轮后，Agent 按九项就绪门禁检查业务结果、 +责任人、流程、范围、规则、数据、集成、安全和验收；存在实施阻塞时继续追问。系统必须把未确认信息标记为 +默认假设或待确认项，不得把模型推测伪装为用户确认。 ## Demo 与 OpenAI 模式 -Demo 模式使用确定性产品经理流程，能够离线演示物流司机排班等需求的三轮澄清， -并生成结构完整的软件设计报告。OpenAI 模式使用配置的 Responses Provider，根据已有对话动态追问和生成报告。 +Demo 模式使用确定性 FDE 发现流程，能够离线演示物流司机排班等需求的三轮澄清， +并生成结构完整的技术方案。OpenAI 模式使用配置的 Responses Provider，根据已有证据动态追问和生成报告。 OpenAI 模式采用手动重放最小消息历史的方式维持会话上下文，`store` 保持为 `false`。 生产环境可进一步评估 Responses API Conversations 或 `previous_response_id`，并结合数据保留要求选择状态管理方式。 @@ -44,12 +49,13 @@ OpenAI 模式采用手动重放最小消息历史的方式维持会话上下文 - 所有会话 API 使用与任务 API 相同的 Bearer 和租户隔离。 - 单条需求、前置条件和回答最多 20,000 字符；每个会话最多 12 个用户轮次。 -- 报告产物受认证下载，并限制为 Artifact Store 的安全文件名和大小。 +- 报告产物名为 `fde-technical-solution.md`，受认证下载，并限制为 Artifact Store 的安全文件名和大小。 - 模型错误只返回通用错误，不把 API Key、上游响应正文或内部异常写给用户。 - 对话中只保存用户可见的问答，不保存模型私有思维链。 ## 当前限制 - 会话状态使用进程内存，服务重启后丢失；报告文件仍在本地 `.artifacts`，但元数据不会自动恢复。 -- Demo 模式的问题模板对物流排班做了优化，其他领域使用通用问题和通用报告框架。 +- Demo 模式的问题模板对物流排班做了优化，其他领域使用通用 FDE 问题和技术方案框架。 - 尚未把最终报告自动转换成开发任务 DAG，也没有自动启动多 Agent 编码团队。 +- 当前 `READY` 是最少轮次门槛，不是模型给出的结构化完整度评分；生产版本应增加字段级证据模型和人工签字门禁。 diff --git a/docs/requirements.md b/docs/requirements.md index b39fb60..e48d73a 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -1,7 +1,8 @@ # Cloud Agent Platform 需求基线 > 扩展能力：在仓库执行任务之前，平台支持多轮需求发现会话。用户可以提交模糊需求和前置条件， -> 通过澄清问题形成已确认需求、默认假设和待确认项，再生成软件设计报告。 +> FDE 通过分阶段澄清形成客户需求证据、已确认事实、默认假设、决策、风险和待确认项， +> 再生成可供架构、开发、QA、安全和客户共同评审的技术方案。 > 详细契约见 `docs/requirement-discovery.md`。 ## 1. 产品定义 @@ -14,7 +15,7 @@ 以下信息尚未由真实业务方确认，实现前需要人工审阅： -- 假设目标用户是企业研发团队和内部开发者。 +- 假设核心目标用户是 FDE、解决方案架构师、AI 应用工程师、企业研发团队和内部开发者。 - 假设第一版是单区域、多租户 MVP，不承诺生产级 SLA。 - 假设输入以 Git 仓库 URL 和自然语言任务为主。 - 假设 P0 主要执行只读代码分析，但底层工具接口预留受控写文件能力。 @@ -25,6 +26,7 @@ ## 3. P0 范围 +- FDE 客户发现：围绕业务结果、现状证据、责任人、范围、数据集成、安全和验收进行多轮访谈，输出技术方案草案。 - 创建任务：自然语言目标、仓库 URL、可选分支或提交哈希。 - 查询任务：当前状态、开始/结束时间、失败原因和资源使用摘要。 - 取消任务：向运行中的 Worker 和沙箱传播取消信号。 diff --git a/docs/sdlc/01-product-and-business-requirements.md b/docs/sdlc/01-product-and-business-requirements.md index c78afdd..e0b5f0e 100644 --- a/docs/sdlc/01-product-and-business-requirements.md +++ b/docs/sdlc/01-product-and-business-requirements.md @@ -9,11 +9,12 @@ 企业研发人员经常需要把自然语言目标转换为一系列可审计的代码分析、文件修改、测试和报告操作。直接在开发者 电脑运行自治 Agent 会带来凭证泄漏、宿主机破坏、资源失控、过程不可追踪和多人协作困难。另一个上游问题是， -业务方通常只给出十几个字的模糊需求，团队在没有形成清晰范围和验收标准前就开始编码。 +企业负责人通常只给出十几个字的模糊需求，FDE 在没有确认决策人、现状证据、清晰范围、数据条件和验收标准前 +就被迫给出方案或承诺，后续造成重复沟通、范围蔓延和开发返工。 本产品提供两条连续价值链： -1. 从模糊需求出发，通过多轮会话和专业 Agent 形成结构化需求及软件设计报告。 +1. 从模糊客户需求出发，通过 FDE 多轮发现形成带证据、责任人、范围、验收和开放项的可执行技术方案。 2. 将批准的任务放入云端隔离环境，由受预算和策略约束的 Agent 执行，并返回事件、结果和产物。 ## 2. 产品愿景 @@ -23,7 +24,8 @@ ## 3. 目标用户 -- 业务产品经理：从模糊想法形成范围、流程、验收标准和未决问题。 +- Forward Deployed Engineer：在客户现场形成需求证据、范围边界、技术方案、验收门禁和研发移交。 +- 业务产品经理：与 FDE 共同确认业务目标、流程、验收标准和未决问题。 - 软件工程师：执行仓库分析、测试、文档、受控修改和技术调研。 - Tech Lead：拆分任务、控制并行开发、审核架构和集成结果。 - QA/安全人员：查看事件、工具调用、测试证据和策略拒绝。 @@ -34,7 +36,7 @@ ## 4. 核心价值指标 -- 需求澄清：80% 的内部需求在 3–5 轮后形成可评审的结构化快照。 +- FDE 发现：80% 的客户需求在 3–5 轮后形成可评审技术草案，关键结论具有证据或明确责任人。 - 任务成功：受支持的只读仓库任务成功率至少 95%。 - 开发效率：常规代码分析与报告任务的人工作业时间降低至少 50%。 - 可追踪性：100% 的模型调用、工具调用、状态变化和产物有公开事件或审计记录。 @@ -52,7 +54,7 @@ - Demo Provider 与 OpenAI Responses Provider。 - 文件列举、读取、搜索、受控写入、命令执行和结果提交工具。 - 本地可信 Sandbox 与 Docker Sandbox 策略。 -- 三轮需求发现和 Markdown 软件设计报告。 +- 至少三轮 FDE 客户发现和 Markdown 技术方案；三轮是草案门槛，不代表需求完整。 - 开发 Bearer Token、单进程存储和本地产物目录。 ### 5.2 Next：Internal Beta @@ -75,18 +77,18 @@ ## 6. 非目标 - v1 不允许 Agent 无审批部署生产、付款、删除业务数据或合并主分支。 -- v1 不承诺替代产品经理、架构师、安全专家或法律意见。 +- v1 不承诺替代 FDE、客户决策人、领域专家、架构师、安全专家或法律意见。 - 不持久化模型私有思维链，只记录面向用户的行动摘要和证据。 - 不支持任意互联网访问；网络必须通过声明式 allowlist 和出口代理。 - 不把 Docker 本身表述为可对抗任意内核级恶意代码的最终安全边界。 ## 7. 关键用户旅程 -### 旅程 A：模糊需求到设计报告 +### 旅程 A：客户模糊需求到 FDE 技术方案 -用户输入“设计一个物流司机排班软件”和前置条件。系统识别信息缺口，每轮询问最高价值的问题；用户回答规模、 -约束、集成和性能后，系统生成结构化需求快照。Domain、Product、Architecture、Data/API、Security 和 QA Agent -分别产出专业分析。若存在阻塞问题则回到用户；质量通过后生成报告和追踪矩阵。 +FDE 输入“客户想用 AI 提升物流司机排班效率”和前置条件。系统识别业务结果、决策人、As-Is 证据、范围、规则、 +数据、集成、安全和验收缺口，每轮只询问最阻塞实施的问题。若存在阻塞问题则继续访谈；达到草案条件后生成 +事实/假设/决策/风险、技术方案、PoC 验收、Go/No-Go 条件和研发移交清单。 ### 旅程 B：仓库分析 diff --git a/docs/sdlc/11-acceptance-handover-traceability.md b/docs/sdlc/11-acceptance-handover-traceability.md index 0af60d5..5c4fe35 100644 --- a/docs/sdlc/11-acceptance-handover-traceability.md +++ b/docs/sdlc/11-acceptance-handover-traceability.md @@ -30,10 +30,11 @@ ## 3. UAT 场景 -### UAT-01 需求发现 +### UAT-01 FDE 客户需求发现 -产品经理输入模糊需求，经过 3–5 轮形成快照；系统标记事实、假设和问题；生成报告包含领域实体、状态、API、NFR、 -安全和验收；用户能定位每条关键结论的来源。通过标准：业务方认为可估时、可拆任务，无 P0 未决项被隐藏。 +FDE 输入客户模糊需求，经过至少三轮形成草案；系统标记事实、假设、决策、风险和开放项；生成报告包含决策人、 +As-Is 证据、范围与非目标、数据集成、架构、API、NFR、PoC 验收和研发移交。通过标准：业务与技术负责人认为 +可估时、可拆任务、可现场验收，无 P0 阻塞项被隐藏。 ### UAT-02 只读仓库分析 diff --git a/docs/task-board.md b/docs/task-board.md index 9bb4c06..6775d5c 100644 --- a/docs/task-board.md +++ b/docs/task-board.md @@ -10,6 +10,14 @@ ## 当前扩展任务 +### CAP-FDE-001：FDE 客户需求发现前置工作流 + +- 状态：`DONE` +- 所有者：主 Agent +- 范围：Discovery Prompt、离线访谈流程、技术方案报告、Web UI、中英文产品定位、测试与 GitHub 元数据 +- 验收：访谈围绕证据和实施阻塞推进；三轮仅代表可生成草案；报告包含范围、责任人、数据集成、验收、 + Go/No-Go 与研发移交；本地及 GitHub 质量门通过 + ### CAP-OSS-001：GitHub 开源发现与仓库治理 - 状态：`DONE` diff --git a/src/api/discovery_routes.py b/src/api/discovery_routes.py index 678a631..8fec847 100644 --- a/src/api/discovery_routes.py +++ b/src/api/discovery_routes.py @@ -23,7 +23,7 @@ def create_discovery_router( *, authenticate: AuthDependency, ) -> APIRouter: - router = APIRouter(prefix="/v1/discovery-sessions", tags=["requirement discovery"]) + router = APIRouter(prefix="/v1/discovery-sessions", tags=["FDE discovery"]) def response(session: object, request: Request) -> DiscoverySessionResponse: from src.discovery import DiscoverySession @@ -42,7 +42,7 @@ def response(session: object, request: Request) -> DiscoverySessionResponse: status_code=status.HTTP_201_CREATED, response_model=DiscoverySessionResponse, operation_id="createDiscoverySession", - summary="Start a multi-turn requirement discovery conversation", + summary="Start a multi-turn FDE customer discovery conversation", responses={503: {"model": ErrorResponse, "description": "Model unavailable"}}, ) async def create_session( @@ -86,7 +86,7 @@ async def get_session( "/{sessionId}/messages", response_model=DiscoverySessionResponse, operation_id="addDiscoveryMessage", - summary="Answer questions and continue requirement discovery", + summary="Record customer evidence and continue FDE discovery", responses={ 404: {"model": ErrorResponse, "description": "Session not found"}, 409: {"model": ErrorResponse, "description": "Conversation conflict"}, @@ -121,7 +121,7 @@ async def add_message( "/{sessionId}/finalize", response_model=DiscoverySessionResponse, operation_id="finalizeDiscoverySession", - summary="Generate the software design report from the conversation", + summary="Generate the FDE technical discovery and solution report", responses={ 404: {"model": ErrorResponse, "description": "Session not found"}, 503: {"model": ErrorResponse, "description": "Model unavailable"}, @@ -148,12 +148,12 @@ async def finalize_session( "/{sessionId}/report", operation_id="downloadDiscoveryReport", name="download_discovery_report", - summary="Download the finalized Markdown software design report", + summary="Download the finalized Markdown FDE technical solution", response_class=FileResponse, response_model=None, responses={ 200: { - "description": "Software design report", + "description": "FDE technical discovery and solution report", "content": {"text/markdown": {"schema": {"type": "string", "format": "binary"}}}, }, 404: {"model": ErrorResponse, "description": "Session not found"}, diff --git a/src/discovery.py b/src/discovery.py index f0993db..28cb89f 100644 --- a/src/discovery.py +++ b/src/discovery.py @@ -60,27 +60,27 @@ async def build_report(self, session: DiscoverySession) -> str: ... class DemoDiscoveryAssistant: - """Deterministic offline product-manager flow for a usable local demo.""" + """Deterministic offline FDE discovery flow for a usable local demo.""" async def initial_questions(self, requirement: str, context: str | None) -> str: del context if self._is_logistics_scheduling(requirement): return ( - "这个需求目前比较模糊，我先确认业务背景。请尽量回答下面 5 个问题；" + "我会按 FDE 客户发现流程先确认业务结果和需求证据。请回答下面 5 个问题；" "不知道的可以写‘按合理默认值’：\n\n" - "1. 主要使用者是谁：调度员、车队管理员、司机，还是都需要？\n" - "2. 业务属于城市配送、长途货运、快递末端，还是其他场景？\n" - "3. 大约有多少司机、车辆和配送区域？按天还是按周排班？\n" - "4. 排班最重要的目标是什么：准时率、最低成本、公平性还是司机满意度？\n" - "5. 第一版必须解决的三个问题是什么？" + "1. 谁是客户侧负责人和最终决策人？主要使用者是调度员、司机还是车队管理员？\n" + "2. 现在如何排班，哪个环节最浪费时间或最容易出错？请给一个最近发生的例子。\n" + "3. 属于城市配送、长途货运还是其他场景？司机、车辆、区域和日任务量是多少？\n" + "4. 客户最想改善哪个可量化指标：准时率、成本、排班耗时、公平性还是投诉率？\n" + "5. 第一版必须解决什么、明确不解决什么，谁负责验收？" ) return ( - "我会先做需求挖掘，再生成软件设计报告。请回答：\n\n" - "1. 谁会使用这个软件，他们现在最痛苦的问题是什么？\n" - "2. 软件在哪些业务场景下使用，频率和大致规模是多少？\n" - "3. 第一版必须完成哪些核心流程？\n" - "4. 用什么指标判断软件上线成功？\n" - "5. 有哪些明确不能做或必须遵守的前置条件？" + "我会按 FDE 客户发现流程，把这句话转成可执行技术方案。第一轮请回答：\n\n" + "1. 谁提出了需求、谁最终决策、谁实际使用？三者是否是同一个人？\n" + "2. 客户现在怎么完成这件事？最痛的步骤是什么？请提供一个最近的真实例子。\n" + "3. 问题发生频率、用户量、数据量和损失或耗时大约是多少？\n" + "4. 第一版必须改变哪个业务结果？用什么数字或现场行为证明成功？\n" + "5. 明确的范围外事项、交付时间、预算或合规红线是什么？" ) async def follow_up(self, session: DiscoverySession) -> str: @@ -96,12 +96,12 @@ async def follow_up(self, session: DiscoverySession) -> str: ) if session.user_rounds == 1: return ( - "收到。第二轮确认业务规则：\n\n" - "1. 核心流程有哪些必须满足的规则和例外？\n" - "2. 需要哪些角色、权限和审批节点？\n" - "3. 需要保存哪些数据，数据从哪里来？\n" - "4. 发生冲突或失败时应由系统还是人工处理？\n" - "5. 哪些操作必须保留审计记录？" + "收到。第二轮只追问会阻塞工程实施的业务规则和证据：\n\n" + "1. 请按顺序描述当前主流程，并指出每一步的输入、负责人和完成条件。\n" + "2. 哪些规则绝不能违反？最常见的三个例外和人工兜底方式是什么？\n" + "3. 需要哪些角色、权限和审批节点？谁有权覆盖系统建议？\n" + "4. 需要哪些数据，分别来自哪个系统，由客户侧谁负责提供和解释？\n" + "5. 哪些关键说法仍是猜测？需要访谈谁或查看什么数据才能确认？" ) if session.user_rounds == 2 and logistics: return ( @@ -114,16 +114,18 @@ async def follow_up(self, session: DiscoverySession) -> str: ) if session.user_rounds == 2: return ( - "最后一轮确认交付条件：\n\n" - "1. 使用网页、手机、桌面端，还是需要多端？\n" - "2. 需要连接哪些已有系统或第三方服务？\n" - "3. 对性能、可用性、安全和合规有什么要求？\n" - "4. 预计用户量、数据量和并发量是多少？\n" - "5. 上线时间、预算、团队和技术栈有哪些限制？" + "第三轮确认技术可行性、验收和决策边界：\n\n" + "1. 需要连接哪些现有系统？接口、样例数据、测试环境和系统负责人是否可获得？\n" + "2. 哪些数据敏感，涉及哪些权限、安全、审计、地域或行业合规要求？\n" + "3. 性能、可用性、并发、数据保留和故障恢复的最低可接受标准是什么？\n" + "4. 请给出 3 到 5 条可现场验收的 Given/When/Then 标准和 PoC 成功阈值。\n" + "5. 上线时间、预算、客户配合人、技术栈和最终 Go/No-Go 决策流程是什么？" ) return ( - "需求信息已经达到第一版设计所需的基本完整度。你可以继续补充，" - "也可以点击“生成软件设计报告”。报告会区分已确认需求和默认假设。" + "已经达到生成技术方案草案的最少轮次，但这不等于需求完整。请检查业务结果与决策人、" + "现状证据、范围和非目标、规则与异常、数据和集成负责人、安全约束、验收阈值、预算与时间。" + "任何一项仍不明确，都可以继续补充；也可以生成 FDE 技术发现报告，" + "并把缺口列为下一步行动。" ) async def build_report(self, session: DiscoverySession) -> str: @@ -150,7 +152,7 @@ def _confirmed_information(session: DiscoverySession) -> str: def _logistics_report(self, session: DiscoverySession) -> str: context = session.context or "未提供；采用下文默认假设。" confirmed = self._confirmed_information(session) - return f"""# 物流司机排班软件设计报告 + return f"""# FDE 客户需求发现与物流司机排班技术方案 ## 1. 文档信息 @@ -158,8 +160,9 @@ def _logistics_report(self, session: DiscoverySession) -> str: - 已知前置条件：{context} - 需求发现轮数：{session.user_rounds} - 会话编号：{session.session_id} +- 文档性质：客户访谈后的技术方案草案，待客户业务负责人和技术负责人共同确认 -## 2. 已确认需求 +## 2. 客户需求证据 {confirmed} @@ -323,61 +326,144 @@ def _logistics_report(self, session: DiscoverySession) -> str: - TMS、订单、GPS、考勤和通知系统的接口条件。 - 司机是否有拒绝、换班和偏好配置权，以及审批流程。 - 上线时间、预算、部署环境、数据地域和保留期限。 + +## 17. FDE 下一步行动与研发移交 + +1. 与客户负责人逐项确认默认假设、非目标、决策权限和验收指标，并形成会议决策记录。 +2. 获取脱敏样例数据、现有排班表、规则清单和 TMS/GPS 接口文档，验证技术可行性。 +3. 用一周完成规则建模与低保真原型评审；未通过的数据和接口前置条件不得进入开发承诺。 +4. 将已确认项转成需求 ID、验收测试和迭代任务；待确认项保留责任人和截止时间。 +5. 在 PoC 结束时依据准时率、排班耗时、硬约束违规数和人工调整量做 Go/No-Go 决策。 """ def _generic_report(self, session: DiscoverySession) -> str: context = session.context or "未提供；未确认部分按默认假设处理。" confirmed = self._confirmed_information(session) - return f"""# 软件设计报告 + return f"""# FDE 客户需求发现与可执行技术方案 -## 1. 原始需求 +## 1. 执行摘要 -{session.initial_requirement} +- 客户原始表达：{session.initial_requirement} +- 已知前置条件：{context} +- 访谈轮数：{session.user_rounds} +- 当前成熟度：技术方案草案；未被客户明确表达的信息不得视为承诺 -## 2. 已知前置条件 +## 2. 客户需求证据 -{context} +{confirmed} -## 3. 多轮需求发现记录 +## 3. 事实、假设和待确认决策 -{confirmed} +- **已确认事实**：仅包括上方客户原始表达和逐轮回答。 +- **默认假设**：第一版采用模块化单体、人工审批高风险动作、先覆盖一个可验证主流程。 +- **待确认决策**：决策人、现状基线、范围外事项、数据负责人、集成条件、验收阈值、预算和上线窗口。 +- **证据要求**：重要结论应关联会议纪要、样例数据、流程截图、接口文档或客户负责人确认。 + +## 4. 客户角色与决策地图 + +1. 业务负责人：确认业务目标、范围、优先级和成功指标。 +2. 一线用户：验证现状流程、异常场景和实际可用性。 +3. 客户技术负责人：确认数据、接口、环境、安全与运维责任。 +4. FDE：维护需求证据、技术方案、风险和跨团队移交。 +5. 最终决策人：依据 PoC 结果、成本和风险做 Go/No-Go 决策。 + +## 5. As-Is 问题与 To-Be 目标 + +- As-Is 必须补齐当前步骤、负责人、输入输出、等待时间、错误率和人工兜底。 +- To-Be 只承诺改变已确认的业务结果，不以“上线一个系统”代替价值目标。 +- 建议先建立现状基线，再定义目标值和测量周期，避免上线后无法判断是否成功。 + +## 6. MVP 范围与非目标 + +### 范围内 + +1. 身份认证、角色权限和一个端到端核心业务流程。 +2. 核心对象的状态流转、异常处理、人工审批和审计。 +3. 必要的数据导入、外部集成适配器、通知和基础指标。 + +### 范围外 -## 4. 产品目标与成功指标 +- 未确认的全量历史数据迁移、自动化高风险决策和一次性替换所有旧系统。 +- 没有接口、数据样例或客户责任人的外部系统集成。 +- 未形成验收标准的“智能化”“高性能”“体验好”等模糊目标。 -- 解决原始需求描述中的核心业务问题。 -- 先交付覆盖主流程的可验证 MVP，再基于真实使用数据扩展。 -- 上线前由业务负责人确认角色、规则、数据、集成和合规假设。 +## 7. 可追踪功能需求 -## 5. MVP 功能框架 +- `FR-001`：目标用户能够完成已确认的端到端主流程。 +- `FR-002`：关键业务对象具有合法、可审计且不可跳过的状态转换。 +- `FR-003`：规则冲突、外部系统失败和人工覆盖具有显式处理路径。 +- `FR-004`：关键写操作支持身份校验、幂等、防重复和操作审计。 +- `FR-005`：系统输出能够关联输入数据、规则版本和处理结果。 -1. 身份认证、用户角色和权限。 -2. 核心业务对象的创建、查询、修改和状态流转。 -3. 主业务流程、异常处理和人工审批。 -4. 操作审计、基础报表和通知。 -5. 可配置业务规则以及导入、导出能力。 +## 8. 数据与集成清单 -## 6. 建议架构 +每个数据源和外部系统必须记录业务用途、系统负责人、接口方式、字段样例、数据量、更新频率、 +敏感等级、测试环境、失败策略和交付日期。没有负责人或样例数据的集成标记为阻塞项。 + +## 9. 建议技术方案 + +### 9.1 技术架构 采用模块化单体作为第一版：Web/移动端调用 API 服务，业务模块使用 PostgreSQL， 耗时任务进入 Redis 队列和异步 Worker。外部集成通过适配器隔离，日志、指标和审计分开保存。 -## 7. 安全与质量 +只有在独立扩缩容、隔离或团队所有权有真实证据时才拆分微服务。所有 AI 推断必须与确定性业务规则、 +人工审批和可追踪证据分层。 + +### 9.2 核心数据模型 + +- `Actor`：用户、角色、组织、权限和决策责任。 +- `BusinessEntity`：客户领域中的核心业务对象及其生命周期。 +- `WorkflowState`：主流程状态、合法转换、完成条件和失败原因。 +- `DecisionRule`：业务规则、优先级、版本、适用范围和人工覆盖条件。 +- `IntegrationRecord`：外部系统、幂等键、同步状态和失败重试信息。 +- `AuditEvent`：操作者、输入、变更前后内容、原因、结果和时间。 + +### 9.3 API 基线 + +- `POST /v1/entities`：幂等创建核心业务对象。 +- `GET /v1/entities/{id}`：按权限查看对象、状态和处理证据。 +- `POST /v1/entities/{id}/actions`：执行经过校验的状态动作。 +- `GET /v1/entities/{id}/events`：查看公开业务与审计事件。 +- `POST /v1/integrations/{{system}}/sync`：触发可追踪的外部系统同步。 + +具体实体名、字段、状态和 API 必须在客户确认领域模型后替换，不能把通用占位符当成最终契约。 + +## 10. 安全、可靠性与非功能要求 - 最小权限、租户隔离、输入校验、敏感数据加密和审计。 - 核心状态机、幂等写入、超时、重试和故障恢复必须自动测试。 -- 先验证业务正确性，再根据实际数据决定是否拆分微服务。 +- 性能、并发、可用性、RTO/RPO、保留期限和合规要求在客户确认数值前均为开放项。 + +## 11. PoC 与 MVP 验收标准 + +1. `Given` 已确认角色、样例数据和测试环境，`When` 执行主流程，`Then` 可完成并生成可核验结果。 +2. 规则、异常、越权、重复提交和外部依赖失败都有客户认可的处理结果。 +3. 关键操作可追踪到用户、输入、规则版本、结果和时间。 +4. PoC 指标必须包含现状基线、目标阈值、测量窗口、数据来源和验收负责人。 +5. 未通过数据质量、安全或集成前置条件时，不得以功能演示替代正式验收。 + +## 12. 交付计划与工程门禁 + +1. Discovery：确认问题、证据、范围、负责人和决策机制。 +2. Feasibility：用样例数据和接口验证关键技术风险。 +3. PoC：只实现能证明核心价值的最小闭环。 +4. MVP：补齐安全、可靠性、运维、数据治理和验收自动化。 +5. Handoff：输出需求 ID、架构决策、接口契约、验收用例、风险和责任矩阵。 -## 8. MVP 验收标准 +## 13. 风险、依赖与仍需确认 -1. 目标用户可以完整完成主业务流程。 -2. 非法状态、越权访问和重复提交被明确拒绝。 -3. 关键操作可追踪，错误对用户可解释。 -4. 性能、安全和可恢复性满足已确认的前置条件。 +- 用户角色、决策人、业务规模、现状基线、规则、异常流程和成功指标。 +- 外部系统负责人、数据样例、接口权限、部署环境、安全合规、预算和时间限制。 +- 客户未按期提供数据、接口或评审人员时，交付时间和范围必须走变更控制。 -## 9. 仍需确认 +## 14. FDE 下一步访谈清单 -- 用户角色、业务规模、核心规则、异常流程和成功指标。 -- 外部系统、部署环境、安全合规、预算和时间限制。 +- 对每个开放项指定客户责任人和确认日期。 +- 用真实业务案例走查主流程和前三类异常，拒绝只讨论抽象功能名。 +- 获取样例数据、接口文档和安全要求，安排技术可行性验证。 +- 让业务负责人签字确认范围、非目标、验收指标与变更流程。 +- 将本报告转成开发任务前，由架构、开发、QA 和安全共同完成可实施性评审。 """ @@ -412,8 +498,12 @@ async def follow_up(self, session: DiscoverySession) -> str: Message( role="user", content=( - "判断信息是否足够形成 MVP 设计。简要总结已确认内容和关键假设，" - "然后提示用户可以生成软件设计报告；不要直接输出报告。" + "按 FDE 技术发现就绪清单判断信息是否足够：业务结果和决策人、" + "现状流程与量化证据、" + "用户和规模、MVP 范围与非目标、规则与异常、数据和集成负责人、安全约束、" + "验收阈值、预算时间与 Go/No-Go 流程。若有阻塞缺口，" + "继续追问最关键的 3 到 5 个；" + "全部覆盖后才说明可以生成技术方案。不要直接输出报告。" ), ) ) @@ -432,24 +522,31 @@ async def build_report(self, session: DiscoverySession) -> str: Message( role="system", content=( - "你是资深产品经理和软件架构师。根据完整对话输出中文 Markdown 软件设计报告。" - "必须区分已确认需求、默认假设和待确认问题，并包含角色、流程、功能范围、" - "数据模型、架构、API、安全、非功能要求、MVP 验收标准、风险和迭代计划。" - "不要声称用户确认了对话中没有出现的信息。" + "你是资深 Forward Deployed Engineer、解决方案架构师和交付负责人。" + "根据完整对话输出中文 Markdown《FDE 客户需求发现与可执行技术方案》。" + "必须区分已确认事实、客户原话证据、默认假设、开放问题和已做决策。" + "报告必须包含执行摘要、决策人与用户、As-Is 流程和量化痛点、To-Be 目标、" + "MVP 范围与非目标、可追踪需求 ID、规则与异常、数据和集成责任矩阵、" + "技术架构与 API、安全和非功能要求、PoC/MVP 验收阈值、交付计划、风险依赖、" + "Go/No-Go 条件以及给开发与 QA 的移交清单。不要把模型推测写成客户承诺。" ), ) ] messages.extend(Message(role=item.role, content=item.content) for item in session.messages) - messages.append(Message(role="user", content="现在生成完整的软件设计报告。")) + messages.append(Message(role="user", content="现在生成完整的 FDE 技术发现与方案报告。")) response = await self._provider.complete(messages, []) return self._answer(response.final_answer) @staticmethod def _discovery_prompt() -> str: return ( - "你是需求发现 Agent。目标是通过多轮对话把模糊的软件需求变为可验收的 MVP。" - "优先询问用户角色、业务场景、规模、规则、异常、数据、集成、成功指标和交付约束。" - "每轮只问 3 到 5 个问题，问题要具体、容易回答；不要泄露内部推理。" + "你是资深 Forward Deployed Engineer 的客户需求发现助手。目标不是陪聊或急于给方案，" + "而是把企业负责人的模糊表达变成有证据、可实施、可验收的技术方案。" + "优先确认业务结果与决策人、As-Is 流程和真实案例、量化规模与痛点、用户与权限、" + "MVP 范围和非目标、规则与异常、数据来源和系统负责人、集成条件、安全合规、" + "PoC 验收阈值、预算时间和决策流程。严格区分事实、假设、决策、风险和开放问题。" + "不得重复已经回答的问题；遇到‘快、智能、好用’等模糊词必须追问数字、样例或可观察行为。" + "每轮只问 3 到 5 个最阻塞工程实施的问题，并说明问题所处的访谈阶段；不要泄露内部推理。" ) @staticmethod @@ -556,7 +653,7 @@ async def finalize(self, session_id: str, *, tenant_id: str) -> DiscoverySession report = await self._assistant.build_report(session) artifact = await self._artifact_store.put_text( session.session_id, - "software-design-report.md", + "fde-technical-solution.md", report, "text/markdown", ) diff --git a/src/discovery_ui.py b/src/discovery_ui.py index 12f5f0c..b39b470 100644 --- a/src/discovery_ui.py +++ b/src/discovery_ui.py @@ -5,7 +5,7 @@ - 需求发现 Agent + FDE 客户需求发现工作台