agentworkshop 0.7.50 → 0.7.52

package/docs/mcp.en.md

@@ -0,0 +1,27 @@
+# aw Industrial MCP Server (mcp/)
+
+> Integration entry for external skills / MCP clients / engineer workbenches: exposes the
+> platform's key REST methods as first-class MCP tools and **auto-discovers the port of the
+> running local instance** — mount it and it just works, no manual port wiring.
+
+See [docs/mcp.md](../mcp.md) (Chinese, authoritative) for the full reference. Summary:
+
+- **Launch**: `aw mcp` (stdio) · `aw mcp --doctor` (diagnose) · `aw mcp --print-config`
+- **Port discovery priority**: `AW_BASE_URL` → `AW_PORT` → `.runtime/aw.lock` lock files
+  (explicit `AW_HOME` wins over implicit cwd/home discovery) → `PORT`/`NUXT_PORT` →
+  `config.yml` `server.dev.port`/`server.prod.port` → defaults 3000/3001.
+  Health gate: `GET /api/health` must return `data.status === 'ok'`.
+- **Self-healing**: network failures invalidate the cached base and trigger one re-discovery +
+  retry; 401 clears the token and lazy-relogins once. Bad credentials fail fast (no re-discovery).
+- **Auth**: `AW_TOKEN`, or `AW_EMAIL` + `AW_PASSWORD` (lazy login), or the `aw_login` tool.
+- **Tool surface (35)**: connection (`aw_status`, `aw_login`); lines/products/recipes
+  (`aw_line_*`, `aw_product_create`, `aw_recipe_create`); DCW nodes & parameter map
+  (`aw_dcw_*`, `aw_param_*`); DAQ (`aw_daq_*`); optimization channels
+  (`aw_channel_*`, `aw_channel_template_instantiate`, `aw_team_provision`,
+  `aw_agent_tool_bind/invoke`, `aw_twin_profile_get/patch`, `aw_task_*`, `aw_model_*`,
+  `aw_optimization_judge`); plugins (`aw_plugin_list`, `aw_plugin_toggle`);
+  escape hatch (`aw_request`, `/api/` prefix only).
+- **Skills**: `skills/aw-node-bind`, `skills/aw-opt-channel`, `skills/aw-plugin-dev` are built
+  on top of this server (`npm run test:skills` validates cross-references).
+- **Tests**: `npm run test:mcp` (unit, 12 test groups) · `npm run test:mcp-live`
+  (isolated-instance e2e, 34 assertions).

package/docs/mcp.md

@@ -0,0 +1,108 @@
+# aw 工业 MCP 服务(mcp/)
+
+> 面向外部 skill / MCP 客户端 / 工程师工作台的集成入口:把平台关键 REST 方法暴露为
+> 一等 MCP 工具,并**自动发现本机运行实例的端口**——挂上就能用,不要求手填端口。
+
+## 一、它解决什么
+
+平台已有两个 MCP 面,分工如下:
+
+| MCP 面 | 位置 | 面向 | 鉴权 |
+| --- | --- | --- | --- |
+| **aw 工业 MCP**(本文) | `mcp/aw-mcp-server.mjs`(stdio) | 外部 skill、桌面 MCP 客户端、CI 脚本 | 用户 token(AW_TOKEN 或 AW_EMAIL/AW_PASSWORD) |
+| host tools 回程桥 | `server/harness/aw-mcp-bridge.mjs`(stdio) | 频道内 harness 引擎(codex/dsh/opencode…) | agent 实例 token |
+| Workshop MCP(Streamable HTTP) | `POST /api/mcp/workshop` | 平台侧任务/消息/设备孪生 | Bearer token |
+
+工业 MCP 暴露的是**工程操作面**(产线/节点绑定/参数映射/配方/优化闭环频道/插件),
+与频道内 agent 的 host tool 面(`.AgentWorkShop/prompts/host-tools.json`)互补。
+
+## 二、快速开始
+
+```bash
+aw mcp --doctor        # 诊断:自动发现过程 → 健康 → 鉴权,一次讲清
+aw mcp --print-config  # 打印 MCP 客户端配置 JSON
+aw mcp                 # 启动 stdio 服务(由 MCP 客户端作为子进程拉起)
+```
+
+客户端配置(claude_desktop_config.json / codex config.toml 通用形态):
+
+```json
+{ "mcpServers": { "aw": { "command": "node", "args": ["<仓库>/mcp/aw-mcp-server.mjs"], "env": {} } } }
+```
+
+## 三、端口自动发现(核心机制)
+
+发现优先级(逐级 `GET /api/health` 探活,`data.status==='ok'` 才算命中;全失败才报错):
+
+1. `AW_BASE_URL` —— 显式平台地址
+2. `AW_PORT` —— 多实例并存时钉住端口
+3. 锁文件 `<configRoot>/.runtime/aw.lock`(`{pid,port,mode}`,`aw start` 端口顺延后回写,
+   是实例真实端口的唯一权威记录):
+   - 显式 `AW_HOME` 时:先 `AW_HOME/.runtime/aw.lock` 与 `AW_HOME/.AgentWorkShop/.runtime/aw.lock`,
+     再 cwd 向上找 repo 锁(**显式 AW_HOME 压过隐式发现,且不回落全局 home 锁**——多实例隔离语义)
+   - 未设 `AW_HOME` 时:cwd 向上找 `.AgentWorkShop/.runtime/aw.lock`,再 `~/.AgentWorkShop/.runtime/aw.lock`
+4. `PORT` / `NUXT_PORT`(启动惯例变量)
+5. `config.yml` 的 `server.dev.port` / `server.prod.port`(零依赖轻量解析)
+6. 默认端口 3000(dev)/ 3001(prod)
+
+**确保连接**:会话内缓存发现结果;任何工具调用遇到网络层失败,自动作废缓存重发现一次再重试
+(实例顺延换端口后下一发即自愈)。401 时作废 token 懒重登录一次。
+登录失败(凭据错误)不触发重发现,直接报错。
+
+## 四、鉴权
+
+- `AW_TOKEN`:直接携带(优先)。
+- `AW_EMAIL` + `AW_PASSWORD`:首次鉴权调用时懒登录 `POST /api/users/login`,token 会话内缓存。
+- 都没有:工具返回带补救指引的错误;客户端也可在会话里调 `aw_login` 工具显式登录。
+- 实例从未初始化管理员:先走 Web `/setup` 注册(首注册即 admin),MCP 不代注册。
+
+## 四点五、集成开关(系统设置)
+
+- 设置项:`系统设置 → MCP 集成 → 启动 MCP 集成`(`mcp.enabled`,live 键,默认**停用**)。
+  也可用环境变量 `AW_MCP_ENABLED=true` 覆盖(CI/无人值守场景)。
+- 语义:停用期间,除 `aw_status`(自诊断)外的**所有 MCP 工具调用被拒绝**,返回指引文本;
+  平台 REST 与频道内 agent 的 host tools 不受影响。切换 ≤3s 传导到 MCP 服务,无需重启。
+- 三个项目 skill(`skills/`)的前置步骤 0 都会检查该开关(`aw_status` 的 `mcpEnabled` 字段)。
+- 注意:设置页出现「MCP 集成」分组需要实例运行带该描述符的构建(`shared/config/schema.json`,
+  2026-09-27 加入);文件路径(写 `<configRoot>/runtime-settings.json`)与 env 路径不依赖构建。
+
+## 五、工具面(35 个)
+
+| 分组 | 工具 |
+| --- | --- |
+| 连接 | `aw_status`(发现+健康+鉴权状态)、`aw_login` |
+| 产线/产品/配方 | `aw_line_list/create/start/stop`、`aw_product_create`、`aw_recipe_create` |
+| DCW 节点与参数映射 | `aw_dcw_snapshot/create/write/read`、`aw_param_list/write/read` |
+| DAQ 数采 | `aw_daq_create`、`aw_daq_controller`、`aw_daq_samples` |
+| 优化闭环频道 | `aw_channel_list/create`、`aw_channel_template_list/instantiate`、`aw_team_provision`(组合:建 agent→team→成员→deploy)、`aw_agent_tool_bind/invoke`、`aw_twin_profile_get/patch`、`aw_task_create/list`、`aw_model_list/promote`、`aw_optimization_judge` |
+| 插件 | `aw_plugin_list`、`aw_plugin_toggle` |
+| 逃生舱 | `aw_request`(通用 REST,path 必须以 `/api/` 开头) |
+
+`aw_agent_tool_invoke` 可调用频道成员实例的全部宿主工具面
+(`optimization_explore` / `mpc_optimize` / `twin_*` / `dcw_control` / `param_control` / `daq_query` 等),
+是探索/寻优闭环的执行通道。
+
+## 六、与 skills 的集成
+
+三个项目级 skill 以本服务为执行底座(`skills/` 目录):
+
+- `skills/aw-node-bind/` —— 真实场景节点参数绑定(建线→绑执行点→参数映射→配方开跑→回环验收)
+- `skills/aw-opt-channel/` —— 场景优化闭环频道(模板实例化→剧组→探索→AML 门禁→绑定→投用)
+- `skills/aw-plugin-dev/` —— 插件开发(脚手架→setup(ctx)→热重载验证→发布清单)
+
+规范校验:`npm run test:skills`(含"skill 引用的工具必须真实存在于 MCP 工具面"的一致性检查)。
+
+## 七、测试
+
+```bash
+npm run test:mcp        # 单测(12 断言组):锁解析/发现优先级/RPC 面/懒登录/断线重发现/逃生舱守卫
+npm run test:mcp-live   # 真实实例 e2e(34 断言):隔离 home 实例 + 零端口提示自发现 + 全链业务
+```
+
+live e2e 的隔离纪律:临时 `AW_HOME` + 端口 3461,结束 `taskkill //T` 清场,不碰真实库。
+
+## 八、已知边界(有意为之)
+
+- `GET /api/workshop/plugins` 等少数端点是裸 `defineEventHandler`(无统一信封),服务端已做信封嗅探兼容。
+- MCP 不代理模拟器 REST(presets/export);skill 流程里对模拟器的访问走直连(默认 `http://127.0.0.1:4010`)。
+- `aw_request` 限制 method 白名单与 `/api/` 前缀,不代理任意外网。

package/docs/plugins.en.md

@@ -9,7 +9,7 @@
 >
 > Applies to: plugin system v2 has been available since **v0.7.29** (frontend component
 > injection / plugin settings / plugin i18n / runtime services surface); this document
-> describes **v0.7.50**. `ctx.sdkVersion` is currently `0.3.0`.
+> describes **v0.7.52**. `ctx.sdkVersion` is currently `0.3.0`.
 
 ## 1. Folder layout & quick start
 

package/docs/plugins.md

@@ -6,7 +6,7 @@
 > 本文是唯一权威参考;`docs/site/plugins/` 的分页文档与本文同源。
 >
 > 适用版本:插件系统 v2 自 **v0.7.29** 起可用(前端组件注入 / 插件设置 / 插件 i18n /
-> 运行时服务面);本文档对应当前版本 **v0.7.50**。`ctx.sdkVersion` 当前为 `0.3.0`。
+> 运行时服务面);本文档对应当前版本 **v0.7.52**。`ctx.sdkVersion` 当前为 `0.3.0`。
 
 ## 一、目录结构与快速开始
 

package/docs/sdk.en.md

@@ -7,7 +7,7 @@
 
 **SDK version constants**: server-side `SDK_VERSION = '0.3.0'`, browser-side `CLIENT_SDK_VERSION = '0.3.0'`.
 These two constants are the **interface version of the SDK itself** and evolve **independently**
-from the npm package version (the `version` field in `package.json`, currently 0.7.50) —
+from the npm package version (the `version` field in `package.json`, currently 0.7.52) —
 them being out of sync is expected. Never use `SDK_VERSION` to infer the package version, or the reverse.
 **Module format**: ESM only (only `import` / `export`; there is no CJS entry).
 **Types**: `sdk/index.d.mts` and `sdk/client.d.mts` ship with the package, so TypeScript projects

package/docs/sdk.md

@@ -5,7 +5,7 @@
 > 零第三方运行时依赖,Node ≥ 23.4 与现代浏览器双端可用。
 
 **SDK 版本常量**:服务端 `SDK_VERSION = '0.3.0'`,浏览器端 `CLIENT_SDK_VERSION = '0.3.0'`。
-这两个常量是 **SDK 自身接口的版本号**,与 npm 包版本(`package.json` 的 `version`,当前 0.7.50)
+这两个常量是 **SDK 自身接口的版本号**,与 npm 包版本(`package.json` 的 `version`,当前 0.7.52)
 **各自独立演进** —— 常数不同步是预期行为,不要拿 `SDK_VERSION` 去推断包版本,反之亦然。
 **模块形态**:ESM only(只有 `import` / `export`,没有 CJS 入口)。
 **类型**:`sdk/index.d.mts`、`sdk/client.d.mts` 随包发布,TS 项目零配置获得提示(覆盖范围见 §7)。

package/i18n/dicts/ctpl.json

@@ -1,32 +1,37 @@
-{
-  "k117jag9001": "删除模板?(已实例化的 Channel 不受影响)",
-  "knjomku002": "按模板新建 Channel(成员自动装配)",
-  "k1f55q76003": "模板名称",
-  "k40gkk004": "描述",
-  "k1ju32o7005": "选择 lead 模板(可空)",
-  "k5uq1js006": "Worker 成员模板(实例化时逐个克隆)",
-  "kqmdkc9007": "选择成员模板(可空)",
-  "k1q87yho008": "作业场景 Prompt(注入全部成员)",
-  "kk4u5cr009": "工作目录(留空 = 实例化时默认)",
-  "k3lrqn0010": "可见性",
-  "k18gglgp011": "场景 + 工作目录 + 团队的组合模板;一键实例化为 Channel(成员自动装配)。模板按用户隔离,公开后全员可用。",
-  "krpx6qa012": "返回工作区",
-  "k1efixrj013": "新建模板",
-  "ka1gpdj014": "admin 视图:可见全部用户的模板与创建者",
-  "k3rx4ps015": "空团队",
-  "k3xakp016": "删除",
-  "k3mr1fo017": "实例化",
-  "k19fglby018": "新建第一个 Channel 模板",
-  "k17jfge3019": "私有(仅本人可见)",
-  "k191u0u5020": "公开(全员可实例化,仅本人可修改)",
-  "k3x23c021": "内置",
-  "k3wv1t022": "公开",
-  "k447jj023": "私有",
-  "k1i0ji0y024": "模板名必填",
-  "kyppebc025": "模板已创建;可在工作区左侧会话栏一键实例化挂载",
-  "kkziya3026": "已公开:全员可实例化",
-  "k1xxabaf027": "已转为私有",
-  "k1oxfuqj028": "已删除模板",
-  "k1f54iqd029": "模板中心",
-  "kefkfnl030": "已实例化:{p0}(成员 {p1} 个),到工作区挂载使用"
-}
+{
+  "k117jag9001": "删除模板?(已实例化的 Channel 不受影响)",
+  "knjomku002": "按模板新建 Channel(成员自动装配)",
+  "k1f55q76003": "模板名称",
+  "k40gkk004": "描述",
+  "k1ju32o7005": "选择 lead 模板(可空)",
+  "k5uq1js006": "Worker 成员模板(实例化时逐个克隆)",
+  "kqmdkc9007": "选择成员模板(可空)",
+  "k1q87yho008": "作业场景 Prompt(注入全部成员)",
+  "kk4u5cr009": "工作目录(留空 = 实例化时默认)",
+  "k3lrqn0010": "可见性",
+  "k18gglgp011": "场景 + 工作目录 + 团队的组合模板;一键实例化为 Channel(成员自动装配)。模板按用户隔离,公开后全员可用。",
+  "krpx6qa012": "返回工作区",
+  "k1efixrj013": "新建模板",
+  "ka1gpdj014": "admin 视图:可见全部用户的模板与创建者",
+  "k3rx4ps015": "空团队",
+  "k3xakp016": "删除",
+  "k3mr1fo017": "实例化",
+  "k19fglby018": "新建第一个 Channel 模板",
+  "k17jfge3019": "私有(仅本人可见)",
+  "k191u0u5020": "公开(全员可实例化,仅本人可修改)",
+  "k3x23c021": "内置",
+  "k3wv1t022": "公开",
+  "k447jj023": "私有",
+  "k1i0ji0y024": "模板名必填",
+  "kyppebc025": "模板已创建;可在工作区左侧会话栏一键实例化挂载",
+  "kkziya3026": "已公开:全员可实例化",
+  "k1xxabaf027": "已转为私有",
+  "k1oxfuqj028": "已删除模板",
+  "k1f54iqd029": "模板中心",
+  "kefkfnl030": "已实例化:{p0}(成员 {p1} 个),到工作区挂载使用",
+  "kbInstTitle": "实例化 {p0}",
+  "kbOption": "知识库集成(rag-bridge)",
+  "kbHint": "开启后本频道加载知识库插件:优化前先检索场景数据分析与物理机理,收口后由 lead 把经验沉淀入知识库;lead 还可用 team_grant_nodes 把自己绑定的节点授权给 worker。",
+  "kbOn": "开启",
+  "kbOff": "关闭"
+}

package/i18n/locales/en.ts

@@ -471,6 +471,11 @@ export default {
     newTplTitle: 'New channel template',
     leadTplLabel: 'Lead template (cloned as the channel lead when instantiated)',
     kefkfnl030: 'Instantiated: {p0} ({p1} members); mount it from the workspace',
+    kbInstTitle: 'Instantiate {p0}',
+    kbOption: 'Knowledge base integration (rag-bridge)',
+    kbHint: 'When on, this channel loads the KB plugin: search scene data-analysis & physics knowledge before optimizing, and the lead sinks experience back after the loop closes; the lead can also grant its own bound nodes to workers via team_grant_nodes.',
+    kbOn: 'On',
+    kbOff: 'Off',
     k1f54iqd029: 'Template Hub',
     k117jag9001: 'Delete template? (Instantiated Channels are not affected)',
     knjomku002: 'Create Channel from template (members auto-assembled)',

package/i18n/locales/zh-CN.ts

@@ -471,6 +471,11 @@ export default {
     newTplTitle: '新建 Channel 模板',
     leadTplLabel: 'Lead 模板(实例化时克隆为 channel lead)',
     kefkfnl030: '已实例化:{p0}(成员 {p1} 个),到工作区挂载使用',
+    kbInstTitle: '实例化 {p0}',
+    kbOption: '知识库集成(rag-bridge)',
+    kbHint: '开启后本频道加载知识库插件:优化前先检索场景数据分析与物理机理,收口后由 lead 把经验沉淀入知识库;lead 还可用 team_grant_nodes 把自己绑定的节点授权给 worker。',
+    kbOn: '开启',
+    kbOff: '关闭',
     k1f54iqd029: '模板中心',
     k117jag9001: '删除模板?(已实例化的 Channel 不受影响)',
     knjomku002: '按模板新建 Channel(成员自动装配)',