develop-process

name	develop-process
description	LinkAgent 项目的功能开发流程和阶段门禁。Use when Codex implements or changes features in linkAgent, designs backend/frontend APIs, changes database schema, writes project docs, or needs to coordinate requirements, design, coding, verification, and documentation with the author.

LinkAgent 开发流程

基本原则

• 所有功能开发按 需求分析 -> 设计方案 -> 编码实现 -> 测试验证 -> 文档编写 推进。
• 小改动可以简短通过每个阶段，但不能跳过阶段。
• 新功能、架构调整、数据库变更、对外 API 变更必须完整说明需求、方案、测试点和文档。
• 每轮只解决一个明确问题，避免混入无关优化、重构或额外功能。
• 每个阶段结束后先自检，再向作者说明结果，并在需要作者取舍或确认时等待反馈。
• 如果发现当前方案会偏离“UP 主智能工作台”主线，必须先停下来说明风险。

阶段 1：需求分析

目标：明确本轮要解决哪个创作者痛点，以及功能边界。

必须确认：

• 目标用户是谁，例如 UP 主、运营者、内容复盘者。
• 创作者场景是什么，例如文稿分析、标题生成、标签建议、评论复盘。
• 输入数据来自哪里，优先使用用户主动提供的数据或样例数据。
• 本阶段做什么，以及明确不做什么。

输出要求：

• 给出需求结论，说明输入、输出、边界和技术重点。
• 自检需求是否服务创作者工作流，而不是回到通用 Agent 展示。
• 如果需求、数据来源或业务边界不清楚，先向作者提问，不能自行扩大范围。

阶段 2：设计方案

目标：把需求拆成清晰的模块、接口、数据结构和执行流程。

必须说明：

• 涉及哪些模块、类、接口或表结构。
• 对外 API 的路径、请求参数、响应结构和校验规则。
• 是否涉及 Agent、工具调用、记忆、向量库、数据库、Redis、SSE 或前端页面。
• 为什么采用当前方案，以及为什么暂时不采用更复杂的方案。

输出要求：

• 给出技术方案，明确模块划分、接口设计、数据结构和关键流程。
• 对第三方 API、框架方法或版本兼容性不确定时，先查项目文档或官方资料。
• 涉及作者取舍的设计点必须先说明选项和影响，再等待作者确认。

阶段 3：编码实现

目标：严格按已确认的方案完成代码和配置变更。

实现要求：

• 不随意扩大功能范围。
• 不引入未使用的抽象。
• 所有对外 API 使用 Jakarta Validation 做入参校验。
• 注释使用中文，并解释为什么这么做，而不是只描述做了什么。
• 数据库 Schema 统一维护在 backend/src/main/resources/sql/ 目录。

变更中断规则：

• 如果实现中发现原设计不可行，先说明原因、影响和调整方案。
• 调整会改变接口、表结构、数据来源或用户体验时，必须等待作者确认后再继续。
• 如果只是局部实现细节调整，且不改变已确认边界，可以继续推进，并在阶段结果中说明。

阶段 4：测试验证

目标：覆盖主要功能路径和关键边界情况。

必须说明：

• 正常输入是否可用。
• 缺失参数、非法参数、空数据等边界情况如何处理。
• Agent / LLM 调用失败时是否有合理返回。
• 数据库、Redis、Milvus、SSE 等外部依赖异常时是否可控。

硬性约束：

• 开发者不得执行后端编译、测试、构建、运行或启动命令，但是对于前端可以进行编译、测试、构建、运行或启动命令。
• 需要验证时，只能告诉作者应该执行什么命令、预期看到什么结果、失败时优先排查什么。
• 作者反馈结果后，再根据反馈继续定位或修正。

阶段 5：文档编写

目标：让后续开发者能理解本次功能的设计、用法和注意事项。

要求：

• 新增功能时，在 linkAgent/docs/develop 新增对应功能文档。
• 一轮功能完整结束后，在 linkAgent/docs/reference 补充详细介绍。
• 如果开发中遇到问题，在 linkAgent/docs/error 补充阶段性错误整理。
• 新增或调整阶段文档后，同步更新 linkAgent/docs/README.md。

多 Agent 协作

复杂任务可以开启多 Agent 协作，由主 Agent 充当 Supervisor。

Supervisor 负责：

• 拆分任务。
• 分配分析、设计、编码、测试、文档等子任务。
• 汇总结论。
• 检查结果是否符合项目主线和当前阶段目标。
• 防止子 Agent 扩大范围或偏离“UP 主智能工作台”方向。

最终交付说明

完成一轮工作后，最终回复必须包含：

• 本轮改了什么。
• 为什么这样改。
• 解决了什么问题。
• 哪些命令需要作者执行验证。
• 如果没有执行验证，要明确说明原因。