Merge pull request #2 from AgentFlocks/docs-align-module-implementation

docs: align module docs with implementation

Author: xiami762

docs/md/modules/agents.md

@@ -134,12 +134,13 @@ Prompt 越结构化，Agent 生成效果越稳定。也可以先给出简单描
 
 ### 6.1 存储位置
 
-Flocks 的 Agent 分为系统内置 Agent 和用户自定义 Agent：
+Flocks 的 Agent 主要来自系统内置目录、项目级插件目录和用户级插件目录：
 
 | 类型 | 存储位置 | 说明 |
 | --- | --- | --- |
-| 系统内置 Agent | 项目目录下的 `.flocks/plugins/agents/` | 随项目或系统提供，适合项目级能力。 |
-| 用户自定义 Agent | 用户目录下的 `~/.flocks/plugins/agents/` | 当前用户自定义的 Agent，可在用户环境中复用。 |
+| 系统内置 Agent | Flocks 包内的 `flocks/agent/agents/<name>/` | 随 Flocks 安装包提供，属于内置能力。 |
+| 项目级插件 Agent | 当前项目或 Workspace 下的 `.flocks/plugins/agents/<name>/` | 只在当前项目 / Workspace 中可见。 |
+| 用户级插件 Agent | 用户目录下的 `~/.flocks/plugins/agents/<name>/` | 当前用户自定义的 Agent，可在用户环境中复用。 |
 
 ### 6.2 目录结构
 
@@ -181,12 +182,12 @@ agents/
 | `tools` | 工具白名单，决定该 Agent 可调用哪些工具。 |
 | `model` | 单独指定模型；为空或默认时跟随系统默认模型。 |
 | `temperature` / `topP` | 模型采样参数，影响输出稳定性和探索性。 |
-| `prompt` | Prompt 文件或 Prompt 内容引用，通常对应 `prompt.md`。 |
 | `tags` | 标签，用于分类、搜索或能力管理。 |
 | `hidden` | 是否在页面中隐藏。 |
-| `native` | 是否为系统内置或原生 Agent。 |
 | `delegatable` | 是否允许 Rex 将任务委派给该 Agent。 |
 
+Prompt 不在 `agent.yaml` 中用 `prompt` 字段声明。运行时会优先读取 Agent 目录下的 `prompt.md` 作为静态 System Prompt；如果没有 `prompt.md`，则可以通过 `prompt_builder.py` 提供动态 Prompt。`native` 也不是 `agent.yaml` 字段，而是系统根据加载目录自动判断：包内置 Agent 和项目级插件 Agent 视为 native，用户级插件 Agent 视为非 native。
+
 `mode` 会影响 `delegatable` 的默认行为。主 Agent 通常不作为被委派对象；子 Agent 通常可以被 Rex 调度。对于关键 Agent，建议把 `description`、`tools` 和 `prompt.md` 写清楚，这会直接影响 Rex 是否能正确选择它。
 
 ## 7. 运行与验证
@@ -409,7 +410,7 @@ Rex 即使没有被显式告知巡检 Agent 名称，也会根据任务目标选
 
 ### 11.4 创建完 Agent 后在哪里查看源文件？
 
-系统内置或项目级 Agent 通常在项目目录下的 `.flocks/plugins/agents/`；用户自定义 Agent 通常在 `~/.flocks/plugins/agents/`。每个 Agent 是一个独立文件夹，核心文件是 `agent.yaml` 和 `prompt.md`。
+系统内置 Agent 位于 Flocks 包内的 `flocks/agent/agents/<name>/`；项目级插件 Agent 位于当前项目或 Workspace 下的 `.flocks/plugins/agents/<name>/`；用户级插件 Agent 位于 `~/.flocks/plugins/agents/<name>/`。每个 Agent 是一个独立文件夹，核心文件是 `agent.yaml`，通常还会包含 `prompt.md`。
 
 ### 11.5 一定要用 ReAct 模式吗？
 

docs/md/modules/cli.md

@@ -31,7 +31,7 @@ CLI 适合服务启停、日志查看、任务管理、MCP 管理、Skill 安装
 | 命令组 | 作用 |
 | --- | --- |
 | `flocks start/stop/restart/status/logs` | 服务启停、状态和日志。 |
-| `flocks tui` / `flocks run` | 启动终端里的 CLI/TUI 会话界面。 |
+| `flocks tui` | 启动终端里的 TUI 会话界面。 |
 | `flocks browser` | 调用内置浏览器运行时。 |
 | `flocks session ...` | 会话列表、详情、删除、归档和恢复。 |
 | `flocks task ...` | 任务中心、队列、定时任务和任务重跑。 |
@@ -53,7 +53,6 @@ CLI 适合服务启停、日志查看、任务管理、MCP 管理、Skill 安装
 | `flocks status` | 查看后端和 WebUI 状态。 | `flocks status` |
 | `flocks logs` | 查看后端和 WebUI 日志。 | `flocks logs --backend -n 100` |
 | `flocks tui` | 启动 TUI 对话界面。 | `flocks tui --directory .` |
-| `flocks run` | 启动 CLI 对话界面，适合直接在终端里和 Rex 对话。 | `flocks run` |
 | `flocks browser` | 透传到内置浏览器运行时。 | `flocks browser --help` |
 | `flocks update` | 执行版本更新。 | `flocks update` |
 | `flocks serve` | 直接启动 Flocks API Server，隐藏命令，主要用于开发和调试。 | `flocks serve --host 127.0.0.1 --port 8000` |
@@ -67,10 +66,11 @@ CLI 适合服务启停、日志查看、任务管理、MCP 管理、Skill 安装
 - `flocks logs --backend`：只看后端日志。
 - `flocks logs --webui`：只看 WebUI 日志。
 - `flocks logs --follow/--no-follow`：是否持续跟随日志。
-- `flocks run`：启动终端 CLI 对话界面。
 - `flocks tui --session <sessionID>`：继续指定会话。
 - `flocks tui --auto-approve/--no-auto-approve`：控制 TUI 中工具调用是否自动批准。
 
+`flocks run` 是 TUI / Node CLI 源码中的会话入口，不是当前 Python `flocks` 主 CLI 注册的稳定命令。通过 Python 包或 npm wrapper 使用时，应以 `flocks --help` 输出为准，通常使用 `flocks tui` 进入终端会话。
+
 ## 3. 会话 CLI
 
 | 命令 | 作用 |

docs/md/modules/skills.md

@@ -110,11 +110,11 @@ flocks skills install-deps <skill-name>
 | `flocks skills remove <name>` | 删除指定 Skill。 |
 | `flocks skills install-deps <skill-name>` | 安装 Skill 声明的依赖。 |
 
-如果通过 npm wrapper 使用，也可能看到单数形式：
+如果通过 npm wrapper 使用，也应使用复数命令组。npm wrapper 会透传到 Python `flocks` CLI，不会把单数 `skill` 自动改写为 `skills`：
 
 ```bash
-npx @flocks-ai/flocks skill install clawhub:github
-npx @flocks-ai/flocks skill install github:owner/repo
+npx @flocks-ai/flocks skills install clawhub:github
+npx @flocks-ai/flocks skills install github:owner/repo
 ```
 
 在 Flocks Python CLI 中，正式命令组是复数 `flocks skills ...`。

docs/md/modules/slash-commands.md

@@ -26,10 +26,9 @@ WebUI 适合查看当前会话可用工具、Skill、Agent、Workflow，也适
 
 ```bash
 flocks tui
-flocks run
 ```
 
-TUI 和 CLI 会话适合在本机终端里和 Rex 交互，同时快速查看工具、任务、Skill 和 MCP 状态。
+TUI 会话适合在本机终端里和 Rex 交互，同时快速查看工具、任务、Skill 和 MCP 状态。源码中的 TUI / Node CLI 还包含 `flocks run` 入口，但当前 Python `flocks` 主 CLI 不注册该命令；实际可用入口以 `flocks --help` 为准。
 
 ### 1.3 IM 通道