From 8531a76a38355230b5ff1a0b01f3777720832034 Mon Sep 17 00:00:00 2001 From: Jie Liu Date: Fri, 10 Oct 2025 19:38:57 +0800 Subject: [PATCH 1/3] =?UTF-8?q?Windows=E4=B8=8B=E4=BA=A4=E4=BA=92=E5=BF=85?= =?UTF-8?q?=E8=A6=81=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- zh-CN/AGENTS.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/zh-CN/AGENTS.md b/zh-CN/AGENTS.md index 4bc1e7a..5109de6 100644 --- a/zh-CN/AGENTS.md +++ b/zh-CN/AGENTS.md @@ -85,4 +85,93 @@ - 所有阶段完成后，提醒用户进行人工验收和确认，用户确认无其他改动后，将对应任务文档移动至 `.agentdocs/workflow/done/` ，并从索引文档的“当前任务文档”部分移除。 ## 沟通原则 -- 与用户的所有回复与沟通，文档与代码注释均使用中文，必要时可保留英文专业名词，并在首次出现时附简要中文注释。 \ No newline at end of file +- 与用户的所有回复与沟通，文档与代码注释均使用中文，必要时可保留英文专业名词，并在首次出现时附简要中文注释。 +## 代码质量与开发原则 + +### 质量要求 +- 只改动必要的部分，优先复用现有成熟代码，避免重复造轮子。 +- 架构设计时让边界情况自然融入常规逻辑，而不是单独打补丁。 +- 单个代码文件不超过1000行，否则应当进行功能拆分。 +- 保持代码简单直观，不过度设计复杂架构方案。 +- 代码应表达实际逻辑，结构清晰，不保留不再使用的代码，不留无用的混淆项，避免未来维护困惑。 +- 在代码文件种使用与用户沟通的语种撰写简明专业的代码注释。 + +### 测试与验证 +- 所有变更必须通过对应语言的 lint/format/test ，只有通过必要的本地检查后，才可以回传或提交代码，禁止依赖后续修复来兜底。 +- 如目前无对应语言的测试与验证要求，应当在项目根目录的 `AGENTS.md` 中结合项目实际情况补齐要求。 +- 新增或变更功能时必须补充单元测试和集成测试。 +- 如用户未要求，不引入测试框架。 + +## 文档与记忆 +使用文档与记忆来沉淀背景信息、对齐执行约束。 + +所有文档与记忆都采用 Markdown 格式，存放于 `.agentdocs/` 及其子目录下，仅面向 AI 代理使用，不包含任何人类向说明。 + +使用 `.agentdocs/index.md` 作为根索引文档，记录所有文档的主要内容和读取场景，以及关键记忆，例如： + +``` + ## 产品文档 + `prd/idea.md` - 用户关于整个项目的想法 + `prd/board.md` - 白板模块的整体产品文档 + + ## 前端文档 + `frontend/architecture.md` - 前端架构与技术约束，修改任何前端代码时必读 + `frontend/ui-design.md` - 设计风格与样式文档，修改界面时必读 + + ## 后端文档 + `backend/architecture.md` - 后端架构与技术约束，修改任何后端代码时必读 + `backend/api.md` - 后端API接口列表，进行任何前后端对接工作时必读 + + ## 当前任务文档 + `workflow/251006-fix-audio-player.md` - 修复音频播放器BUG + `workflow/201007-floweditor-edge-feature.md` - 为工作流编辑器增加连线功能 + + ## 全局重要记忆 +``` + +创建与更新原则： +- 不要创建工作汇报或任务总结性质的文档，无使用场景。 +- 任何新增的文档都必须在 `.agentdocs/index.md` 中分类并记录。 +- 如果已有相关文档或记忆，优先更新现有内容而非新建。 +- 更新文档或记忆时，应按照原格式重新组织整理文件，而非单纯追加在末尾。 + +缺少文档的情况： +- 在推进任务过程中，若发现任务需要依赖或后续可能用到的跨模块约束、设计约定、使用规范或历史决策（例如样式基准、接口契约、复用组件规则等）而现有文档缺失，且难以通过单次阅读局部代码快速掌握，应把整理并补齐这些必要信息视为任务的一部分，及时写入对应文档。 +- 文档补充后需更新 `.agentdocs/index.md` 并继续执行剩余工作，后续按需迭代细化内容。 + +### 文档 +文档沉淀项目架构、领域边界与跨文件共性信息，帮助在处理复杂任务时快速了解全局上下文，避免重复遍历大量代码。 + +根据项目情况合理划分子目录与文档类型，例如： +- 产品文档：用户的想法，某个模块的具体功能设计等 +- 前端文档：前端技术架构，组件复用规则等 +- 后端文档：后端技术架构，API文档等 + +特殊文档类型： +- 任务文档：记录复杂任务的现状分析、方案设计、背后思考、任务阶段及TODO拆解等所有内容。存放于 `.agentdocs/workflow/` 目录下，文件名格式为 `YYMMDD-任务简述.md`，其中任务简述使用短横线连接的英文单词，如 `251007-fix-audio-player.md`。 + +### 记忆 +记忆沉淀项目中长期适用的重要共识、约束、原则或事实，确保处理不同任务时都遵循一致的执行准则。 +典型的记忆示例： +- 新实现了可复用的自定义滚动条 React 组件 CustomScrollArea ，在前端相关文档中记忆：“开发时滚动容器都应优先使用 CustomScrollArea”。 +- 后端实现完成了统一的 LLM 请求管理器 LLMManager，在后端相关文档中记忆：“所有大模型请求统一走LLMManager，不允许自行实现”。 + +## 任务处理指南 +- 启动新任务时，先读取索引文档 `.agentdocs/index.md` ，了解现有的背景文档与记忆状态。 +- 执行任务时参考索引，自主决定是否查阅相关文档或记忆，需要信息时主动读取对应文档。 +- 当需求不明确时，在继续之前向用户提出问题来澄清需求。 +- 当简单问题超过两次修改仍未解决时，应视为复杂任务处理，进行深入的分析和规划。 +- 对于用户提出的设想和意见，结合项目情况进行全面客观的分析，而不是一味遵循。 +- 对于复杂任务，在分析和规划阶段先从宏观抽象层面厘清问题，再回到具体执行步骤。 +- 对于复杂任务（例如涉及多个模块或跨域变更），必须先制定分阶段实施计划并创建任务文档，然后按阶段调用 Planning Tool 推进执行。 + +### 任务回顾 +在任务完成后，呈现最终消息前必须主动完成任务回顾，并根据任务执行情况判断是否需要形成或更新文档/记忆：若产出新的可复用模式、跨文件约束或关键决策，则写入对应文档；若仅影响局部实现且无长期价值，则无需写回。 + +对于使用任务文档的复杂任务： +- 每完成一个阶段，必须更新文档中的TODO状态。 +- 所有阶段完成后，提醒用户进行人工验收和确认，用户确认无其他改动后，将对应任务文档移动至 `.agentdocs/workflow/done/` ，并从索引文档的“当前任务文档”部分移除。 + +## 沟通原则 +- 与用户的所有回复与沟通，文档与代码注释均使用中文，必要时可保留英文专业名词，并在首次出现时附简要中文注释。 +- 检查用户操作系统，在Windows系统下，禁止使用Poweshell或者CMD或者bat批处理文件等，你在这方面不够成熟容易乱吗，请使用python或者其他流行脚本语言完成工作。 \ No newline at end of file From a47403f166bc38af9140df2cbdf54fd72bc551b3 Mon Sep 17 00:00:00 2001 From: Jie Liu Date: Fri, 10 Oct 2025 19:46:09 +0800 Subject: [PATCH 2/3] OK --- zh-CN/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh-CN/AGENTS.md b/zh-CN/AGENTS.md index 5109de6..80d4f7e 100644 --- a/zh-CN/AGENTS.md +++ b/zh-CN/AGENTS.md @@ -174,4 +174,4 @@ ## 沟通原则 - 与用户的所有回复与沟通，文档与代码注释均使用中文，必要时可保留英文专业名词，并在首次出现时附简要中文注释。 -- 检查用户操作系统，在Windows系统下，禁止使用Poweshell或者CMD或者bat批处理文件等，你在这方面不够成熟容易乱吗，请使用python或者其他流行脚本语言完成工作。 \ No newline at end of file +- 检查用户操作系统，在Windows系统下，禁止使用Poweshell或者CMD或者bat批处理文件等，你在这方面不够成熟容易乱码，请使用python或者其他流行脚本语言完成工作。 \ No newline at end of file From 0bd7d381b25a4c9d4efa2ee7c817a997f464bbf4 Mon Sep 17 00:00:00 2001 From: gaoren002 <83566620+gaoren002@users.noreply.github.com> Date: Mon, 13 Oct 2025 11:00:53 +0800 Subject: [PATCH 3/3] Update AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除重复 --- zh-CN/AGENTS.md | 90 +------------------------------------------------ 1 file changed, 1 insertion(+), 89 deletions(-) diff --git a/zh-CN/AGENTS.md b/zh-CN/AGENTS.md index 503e6a1..941e19e 100644 --- a/zh-CN/AGENTS.md +++ b/zh-CN/AGENTS.md @@ -83,92 +83,4 @@ ## 沟通原则 - 与用户的所有回复与沟通，文档与代码注释均使用中文，必要时可保留英文专业名词，并在首次出现时附简要中文注释。 -## 代码质量与开发原则 - -### 质量要求 -- 只改动必要的部分，优先复用现有成熟代码，避免重复造轮子。 -- 架构设计时让边界情况自然融入常规逻辑，而不是单独打补丁。 -- 单个代码文件不超过1000行，否则应当进行功能拆分。 -- 保持代码简单直观，不过度设计复杂架构方案。 -- 代码应表达实际逻辑，结构清晰，不保留不再使用的代码，不留无用的混淆项，避免未来维护困惑。 -- 在代码文件种使用与用户沟通的语种撰写简明专业的代码注释。 - -### 测试与验证 -- 所有变更必须通过对应语言的 lint/format/test ，只有通过必要的本地检查后，才可以回传或提交代码，禁止依赖后续修复来兜底。 -- 如目前无对应语言的测试与验证要求，应当在项目根目录的 `AGENTS.md` 中结合项目实际情况补齐要求。 -- 新增或变更功能时必须补充单元测试和集成测试。 -- 如用户未要求，不引入测试框架。 - -## 文档与记忆 -使用文档与记忆来沉淀背景信息、对齐执行约束。 - -所有文档与记忆都采用 Markdown 格式，存放于 `.agentdocs/` 及其子目录下，仅面向 AI 代理使用，不包含任何人类向说明。 - -使用 `.agentdocs/index.md` 作为根索引文档，记录所有文档的主要内容和读取场景，以及关键记忆，例如： - -``` - ## 产品文档 - `prd/idea.md` - 用户关于整个项目的想法 - `prd/board.md` - 白板模块的整体产品文档 - - ## 前端文档 - `frontend/architecture.md` - 前端架构与技术约束，修改任何前端代码时必读 - `frontend/ui-design.md` - 设计风格与样式文档，修改界面时必读 - - ## 后端文档 - `backend/architecture.md` - 后端架构与技术约束，修改任何后端代码时必读 - `backend/api.md` - 后端API接口列表，进行任何前后端对接工作时必读 - - ## 当前任务文档 - `workflow/251006-fix-audio-player.md` - 修复音频播放器BUG - `workflow/201007-floweditor-edge-feature.md` - 为工作流编辑器增加连线功能 - - ## 全局重要记忆 -``` - -创建与更新原则： -- 不要创建工作汇报或任务总结性质的文档，无使用场景。 -- 任何新增的文档都必须在 `.agentdocs/index.md` 中分类并记录。 -- 如果已有相关文档或记忆，优先更新现有内容而非新建。 -- 更新文档或记忆时，应按照原格式重新组织整理文件，而非单纯追加在末尾。 - -缺少文档的情况： -- 在推进任务过程中，若发现任务需要依赖或后续可能用到的跨模块约束、设计约定、使用规范或历史决策（例如样式基准、接口契约、复用组件规则等）而现有文档缺失，且难以通过单次阅读局部代码快速掌握，应把整理并补齐这些必要信息视为任务的一部分，及时写入对应文档。 -- 文档补充后需更新 `.agentdocs/index.md` 并继续执行剩余工作，后续按需迭代细化内容。 - -### 文档 -文档沉淀项目架构、领域边界与跨文件共性信息，帮助在处理复杂任务时快速了解全局上下文，避免重复遍历大量代码。 - -根据项目情况合理划分子目录与文档类型，例如： -- 产品文档：用户的想法，某个模块的具体功能设计等 -- 前端文档：前端技术架构，组件复用规则等 -- 后端文档：后端技术架构，API文档等 - -特殊文档类型： -- 任务文档：记录复杂任务的现状分析、方案设计、背后思考、任务阶段及TODO拆解等所有内容。存放于 `.agentdocs/workflow/` 目录下，文件名格式为 `YYMMDD-任务简述.md`，其中任务简述使用短横线连接的英文单词，如 `251007-fix-audio-player.md`。 - -### 记忆 -记忆沉淀项目中长期适用的重要共识、约束、原则或事实，确保处理不同任务时都遵循一致的执行准则。 -典型的记忆示例： -- 新实现了可复用的自定义滚动条 React 组件 CustomScrollArea ，在前端相关文档中记忆：“开发时滚动容器都应优先使用 CustomScrollArea”。 -- 后端实现完成了统一的 LLM 请求管理器 LLMManager，在后端相关文档中记忆：“所有大模型请求统一走LLMManager，不允许自行实现”。 - -## 任务处理指南 -- 启动新任务时，先读取索引文档 `.agentdocs/index.md` ，了解现有的背景文档与记忆状态。 -- 执行任务时参考索引，自主决定是否查阅相关文档或记忆，需要信息时主动读取对应文档。 -- 当需求不明确时，在继续之前向用户提出问题来澄清需求。 -- 当简单问题超过两次修改仍未解决时，应视为复杂任务处理，进行深入的分析和规划。 -- 对于用户提出的设想和意见，结合项目情况进行全面客观的分析，而不是一味遵循。 -- 对于复杂任务，在分析和规划阶段先从宏观抽象层面厘清问题，再回到具体执行步骤。 -- 对于复杂任务（例如涉及多个模块或跨域变更），必须先制定分阶段实施计划并创建任务文档，然后按阶段调用 Planning Tool 推进执行。 - -### 任务回顾 -在任务完成后，呈现最终消息前必须主动完成任务回顾，并根据任务执行情况判断是否需要形成或更新文档/记忆：若产出新的可复用模式、跨文件约束或关键决策，则写入对应文档；若仅影响局部实现且无长期价值，则无需写回。 - -对于使用任务文档的复杂任务： -- 每完成一个阶段，必须更新文档中的TODO状态。 -- 所有阶段完成后，提醒用户进行人工验收和确认，用户确认无其他改动后，将对应任务文档移动至 `.agentdocs/workflow/done/` ，并从索引文档的“当前任务文档”部分移除。 - -## 沟通原则 -- 与用户的所有回复与沟通，文档与代码注释均使用中文，必要时可保留英文专业名词，并在首次出现时附简要中文注释。 -- 检查用户操作系统，在Windows系统下，禁止使用Poweshell或者CMD或者bat批处理文件等，你在这方面不够成熟容易乱码，请使用python或者其他流行脚本语言完成工作。 \ No newline at end of file +- 检查用户操作系统，在Windows系统下，禁止使用Poweshell或者CMD或者bat批处理文件等，你在这方面不够成熟容易乱码，请使用python或者其他流行脚本语言完成工作。