| 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 主智能工作台”方向。
最终交付说明
完成一轮工作后，最终回复必须包含：
- 本轮改了什么。
- 为什么这样改。
- 解决了什么问题。
- 哪些命令需要作者执行验证。
- 如果没有执行验证，要明确说明原因。
