Skip to content

docs: 增加有关agent的说明#1319

Open
Craun718 wants to merge 20 commits into
MaaXYZ:mainfrom
Craun718:docs/agent
Open

docs: 增加有关agent的说明#1319
Craun718 wants to merge 20 commits into
MaaXYZ:mainfrom
Craun718:docs/agent

Conversation

@Craun718
Copy link
Copy Markdown
Contributor

@Craun718 Craun718 commented May 8, 2026

Summary by Sourcery

在英文和中文文档中补充 Agent 概念说明并澄清相关术语。

文档:

  • 在英文术语表中新增一个与 UI 相关的术语定义,并优化 OCR 的描述。
  • 新增英文和中文文档页面,说明 Agent、AgentServer 和 AgentClient 的概念,包括各自的适用场景以及它们与 UI 之间的关系。
Original summary in English

Summary by Sourcery

Document Agent concepts and clarify related terminology in both English and Chinese docs.

Documentation:

  • Add a UI term definition to the English terminology glossary and refine the OCR description.
  • Introduce new English and Chinese documentation pages explaining Agent, AgentServer, and AgentClient, including when each is needed and how they relate to the UI.

Copy link
Copy Markdown
Contributor

@sourcery-ai sourcery-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - 我给出了几条整体性的反馈:

  • 在新的 Agent 文档中,建议添加一个简短且具体的示例流程(例如,一个典型的自定义识别 + 动作场景),这样可以让读者更直观地理解 AgentServer 和 AgentClient 各自的职责。
  • 请再次确认指向 UI 和通用 UI 的交叉链接(./1.2-ExplanationOfTerms.md./1.2-术语解释.md/README_en.md#generic-ui/README.md#通用-ui)是否都能正确跳转,以及这些链接中引用的锚点 ID 是否确实存在于对应文件中。
给 AI Agents 使用的提示词
Please address the comments from this code review:

## Overall Comments
- In the new Agent docs, consider adding a short concrete example flow (e.g., a typical custom recognition + action scenario) to make the AgentServer/AgentClient responsibilities more intuitive for readers.
- Double-check that the cross-links to UI and Generic UI (`./1.2-ExplanationOfTerms.md`, `./1.2-术语解释.md`, `/README_en.md#generic-ui`, `/README.md#通用-ui`) all resolve correctly and that the referenced anchor IDs actually exist in those files.

Sourcery 对开源项目免费——如果你觉得我们的评审有帮助,欢迎分享 ✨
帮我变得更有用!请对每条评论点选 👍 或 👎,我会根据你的反馈改进后续的评审。
Original comment in English

Hey - I've left some high level feedback:

  • In the new Agent docs, consider adding a short concrete example flow (e.g., a typical custom recognition + action scenario) to make the AgentServer/AgentClient responsibilities more intuitive for readers.
  • Double-check that the cross-links to UI and Generic UI (./1.2-ExplanationOfTerms.md, ./1.2-术语解释.md, /README_en.md#generic-ui, /README.md#通用-ui) all resolve correctly and that the referenced anchor IDs actually exist in those files.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- In the new Agent docs, consider adding a short concrete example flow (e.g., a typical custom recognition + action scenario) to make the AgentServer/AgentClient responsibilities more intuitive for readers.
- Double-check that the cross-links to UI and Generic UI (`./1.2-ExplanationOfTerms.md`, `./1.2-术语解释.md`, `/README_en.md#generic-ui`, `/README.md#通用-ui`) all resolve correctly and that the referenced anchor IDs actually exist in those files.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@Craun718
Copy link
Copy Markdown
Contributor Author

Craun718 commented May 8, 2026

开错了,应该用draft的

@Windsland52
Copy link
Copy Markdown
Member

虽然现在经常用 agent 写 custom,但其实 agent 并不是必要的,这个 agent 设计出来的目的是解决 ui 和 资源跨语言的问题。

  1. 有的通用 ui(MFW-CFA/MFAA)支持导入对应语言的代码(py/C#),不需要起 agent 也能
    导入 custom
  2. 全代码开发的也不需要起 agent

然后就是全代码开发也不需要 interface.json,这个纯给通用 ui 解析用的

@Craun718
Copy link
Copy Markdown
Contributor Author

Craun718 commented May 8, 2026

这些情况也许只能作为特例。用mfw-cfa的项目我记得也只是共用解释器,也是要开agent的(吧?)C#那个真的有人在用吗

至于全代码补个说明就好了。

@Windsland52
Copy link
Copy Markdown
Member

custom 是很早就有的东西了,agent 并不是和它一起出现的

@Craun718
Copy link
Copy Markdown
Contributor Author

Craun718 commented May 8, 2026

custom 是很早就有的东西了,agent 并不是和它一起出现的

现在群里一般的语境里这两者几乎被划等号了,我也没有注意到文档中有关这两者区别的具体说明。需要再加一个片段专门来写custom吗?我感觉塞在哪一章都不太合适。

@Windsland52
Copy link
Copy Markdown
Member

感觉要改的话可能吧Agent说明改成Custom说明比较合适,然后在里面提到两种编写方式。
关于非agent的因为是ui自己实现的所以得看对应ui编写的说明——CFAMFAWPF(MFAA前身)

Comment thread docs/zh_cn/3.4-Agent.md Outdated
> [!WARNING]
> AgentClient 是由 [UI](./1.2-术语解释.md) 来负责的,通常情况下你不需要自行实现。

如果你认为现有的[通用 UI](/README.md#通用-ui) 不能满足你的需求,需要自己编写一套 UI 。那么 AgentClient 是必须实现的一个部分。
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

不用吧,纯业务的 UI 逻辑完全可以写在 UI 里的,不需要 AgentClient

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

那改成“通用UI”?

Comment thread docs/zh_cn/3.4-Agent.md
> [!WARNING]
> AgentClient 是由 [UI](./1.2-术语解释.md) 来负责的,通常情况下你不需要自行实现。

如果你认为现有的[通用 UI](/README.md#通用-ui) 不能满足你的需求,需要自己编写一套新的通用 UI 。那么 AgentClient 是必须实现的一个部分。
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个表述也有点奇怪,首先会写通用 UI 的基本是群里的资深开发者了,不太需要这个说明。然后我感觉更多可能是自己搓一个业务 UI 的,那就不一定需要 AgentClient。可能直接去掉这句更合适?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

写这一段是因为之前有人在群里问 agent client 怎么写,但这个人明显不熟悉maafw。
玛丽佬认为这个地方怎么解释比较好呢?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants