kb init(jiuwenswarm): skeleton

knowledge/repos/_index.md

@@ -27,3 +27,4 @@ sources: []
 | afd-plugin | `vllm-project/afd-plugin` | [afd-plugin](afd-plugin/_index.md) |
 | Jianghan roleplay data pipeline | 私有项目 | [jianghan-roleplay-data-pipeline](jianghan-roleplay-data-pipeline/_index.md) |
 | vLLM-GR | `JiusiServe/vllm-gr` | [vllm-gr](vllm-gr/_index.md) |
+| jiuwenswarm | `openJiuwen-ai/jiuwenswarm` | [jiuwenswarm](jiuwenswarm/_index.md) |

knowledge/repos/jiuwenswarm/_index.md

@@ -0,0 +1,30 @@
+---
+title: "JiuwenSwarm 仓库经验入口"
+created: 2026-09-30
+updated: 2026-09-30
+type: index
+tags: [jiuwenswarm]
+sources: []
+---
+
+# JiuwenSwarm 仓库经验入口
+
+本页是 `openJiuwen-ai/jiuwenswarm`（JiuwenSwarm，原名 JiuwenClaw，v0.2.0 起改为现名）的审查入口。它把 PR 标题或改动路径对应到负责的知识页，再指向仓库自己的文档。仓库文档和源码是事实来源，本知识库只负责指路。
+
+**什么时候查这里**
+
+- 审查 jiuwenswarm 的 PR 时，用来判断改动属于哪一块：Gateway 与频道、E2A/A2A/ACP 协议、A2UI、AgentServer 运行时、Agent Team/Harness/Skills、Auto Harness、Web 前端、默认配置、测试与 CI、打包部署，或文档。
+- 想知道某块代码该先读哪篇文档时查这里。中文文档在 `docs/zh/`，英文文档在 `docs/en/`，总导航是 `docs/README.md` 和 `docs/README_EN.md`。
+
+**不放什么**
+
+- 不复述仓库文档。协议字段、命令用法、配置项、环境变量都以 `docs/` 和源码为准；文档和源码冲突时以源码为准（`docs/zh/A2A.md`、`docs/zh/E2A-protocol.md` 开头都这样声明）。
+- 不放换到其他仓库也成立的通用审查方法，这些放在 `general/`。
+- 不放产品使用教程和安装步骤。需要时直接读 `README_CN.md`、`docs/zh/安装指南.md`、`docs/zh/Quickstart.md`、`docs/zh/FAQ.md`。
+
+**本仓库页面**
+
+- [JiuwenSwarm 仓库经验入口 — architecture](architecture.md)
+- [JiuwenSwarm 仓库审查规则](rules.md)
+- [每次审查 jiuwenswarm 的 PR 都先读这份通用审查规则；本仓库自己的约束在 rules 页。](../../general/review/rules.md)
+- [PR 新增或修改测试、或 CI 失败时读。先看 tests/ 下已有的用例（如 tests/unit_tests/a2ui/）和 pytest.ini 的约定；TESTING.md 里有过期路径，不能照抄。](../../general/ci/guides/inspect-existing-tests-first.md)

knowledge/repos/jiuwenswarm/_routes.yaml

@@ -0,0 +1,203 @@
+# Direct-mode owner routing for jiuwenswarm, written by kb init (pin f0a69728c96b).
+schema_version: 1
+owners:
+- owner: gateway-channels
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - gateway
+  - 网关
+  - channel
+  - 频道
+  - channel_manager
+  - message_handler
+  - feishu
+  - 飞书
+  - wechat
+  - 微信
+  - xiaoyi
+  - 小艺
+  - /join
+  - HITT
+  scope_prefixes:
+  - jiuwenswarm/gateway/
+- owner: protocols
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - E2A
+  - E2AEnvelope
+  - E2AResponse
+  - A2A
+  - agent card
+  - ACP
+  - JSON-RPC
+  - session/prompt
+  - protocol
+  - 协议
+  scope_prefixes:
+  - jiuwenswarm/common/e2a/
+  - jiuwenswarm/gateway/channel_manager/protocol/
+  - scripts/run_gateway_acp.sh
+  - scripts/run_gateway_acp.cmd
+- owner: a2ui
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - A2UI
+  - a2ui
+  - 生成式界面
+  - client_event
+  - surface
+  - renderer
+  - finalizer
+  scope_prefixes:
+  - jiuwenswarm/server/runtime/a2ui/
+  - jiuwenswarm/channels/web/frontend/src/features/a2ui/
+  - tests/unit_tests/a2ui/
+  - tests/system_tests/test_a2ui_system_flow.py
+- owner: agent-server-runtime
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - AgentServer
+  - agentserver
+  - agent server
+  - runtime
+  - 运行时
+  - agent_adapter
+  - mode
+  - work_mode
+  - 模式
+  scope_prefixes:
+  - jiuwenswarm/server/
+- owner: agents-team
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - team
+  - swarm
+  - 集群模式
+  - leader
+  - teammate
+  - swarmflow
+  - rails
+  - harness
+  - skill
+  - 技能
+  - memory
+  - 记忆
+  - prompt
+  scope_prefixes:
+  - jiuwenswarm/agents/
+- owner: auto-harness
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - auto-harness
+  - auto harness
+  - AutoHarness
+  - evolve
+  - evolution
+  - 演进
+  - 自演进
+  - harness package
+  - schedule
+  - issue fix
+  scope_prefixes:
+  - docs/zh/AutoHarness.md
+- owner: web-frontend
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - web
+  - frontend
+  - 前端
+  - UI
+  - websocket
+  - react
+  - npm
+  - 页面
+  scope_prefixes:
+  - jiuwenswarm/channels/web/
+- owner: config-resources
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - config
+  - 配置
+  - config.yaml
+  - .env
+  - 环境变量
+  - init
+  - jiuwenswarm-init
+  - model provider
+  - 模型配置
+  scope_prefixes:
+  - jiuwenswarm/resources/
+- owner: subpackages
+  path: repos/jiuwenswarm/architecture.md
+  signals:
+  - jiuwenbox
+  - sdk
+  - sdks
+  - packages
+  - TUI
+  - jiuwenswarm-tui
+  scope_prefixes:
+  - jiuwenbox/
+  - packages/
+  - sdks/
+- owner: tests-ci
+  path: repos/jiuwenswarm/rules.md
+  signals:
+  - test
+  - tests
+  - 测试
+  - pytest
+  - UT
+  - 单元测试
+  - CI
+  - coverage
+  - 覆盖率
+  scope_prefixes:
+  - tests/
+  - pytest.ini
+  - run_tests.sh
+  - TESTING.md
+  - .gitcode/
+- owner: packaging-deploy
+  path: repos/jiuwenswarm/rules.md
+  signals:
+  - dependency
+  - deps
+  - 依赖
+  - bump
+  - release
+  - 发布
+  - version
+  - wheel
+  - pip
+  - uv
+  - docker
+  - deploy
+  - 部署
+  scope_prefixes:
+  - pyproject.toml
+  - uv.lock
+  - MANIFEST.in
+  - Makefile
+  - Dockerfile.claw
+  - .dockerignore
+  - docker/
+  - deploy/
+  - third_party/
+  - OPEN_SOURCE_SOFTWARE_NOTICE.md
+  - LICENSE
+- owner: docs
+  path: repos/jiuwenswarm/rules.md
+  signals:
+  - docs
+  - doc
+  - 文档
+  - README
+  - FAQ
+  - 指南
+  - guide
+  scope_prefixes:
+  - docs/
+  - README.md
+  - README_CN.md
+  - .doc_project_maintainer/

knowledge/repos/jiuwenswarm/architecture.md

@@ -0,0 +1,57 @@
+---
+title: "JiuwenSwarm 仓库经验入口 — architecture"
+created: 2026-09-30
+updated: 2026-09-30
+type: architecture
+tags: [jiuwenswarm]
+sources: []
+---
+
+# JiuwenSwarm 仓库经验入口 — architecture
+
+**怎么用这页**
+
+本页是一张地图，只列出每块代码在哪里、改它之前该先读哪篇仓库文档。如果审查时发现文档与源码不一致，应要求在同一个 PR 里把文档改对。总导航见 `docs/README.md`（中文）和 `docs/README_EN.md`（英文）。
+
+**进程与数据流**
+
+入口（Web / TUI / 飞书 / 微信 / 小艺 / ACP / A2A）
+  → Gateway：ChannelManager 注册频道 → MessageHandler
+  → E2A（请求 E2AEnvelope / 响应 E2AResponse）
+  → AgentServer 运行时（agent_adapter、a2ui）
+  → Agent harness（prompts / tools / rails / skills）与 Team / SwarmFlow
+
+- Gateway 的入口是 `jiuwenswarm/gateway/app_gateway.py`，启动命令为 `python -m jiuwenswarm.gateway.app_gateway`。它会读取 `~/.jiuwenswarm/config/.env` 并注册各个频道。主进程的启动命令是 `python -m jiuwenswarm.app`。
+- Gateway 和 AgentServer 之间只通过 `jiuwenswarm/common/e2a/` 里定义的信封通信。外部协议（A2A、ACP）先在 Gateway 边界转换成 E2A。
+- TUI 是单独发布的 pip 包 `jiuwenswarm-tui`。已提供的文档没有介绍 `jiuwenbox/`、`packages/`、`sdks/` 这三个目录，审查它们时先看目录里的 README 和代码。
+
+**各区域的代码与文档**
+
+| Gateway 与频道 | `jiuwenswarm/gateway/`（`channel_manager/`、`message_handler/`、`app_gateway.py`） | `docs/zh/A2A.md` §0–§2（模块表，以及 Web、ACP、A2A 三种频道的对照） | 改频道注册、消息派发、端口和环境变量绑定时 |
+| E2A 内部协议 | `jiuwenswarm/common/e2a/`（`models.py`、`adapters.py`、`constants.py`） | `docs/zh/E2A-protocol.md`，英文版 `docs/en/E2A-protocol.md` | 改信封或响应字段、`method` 的两种含义、`response_kind`/`status`、ACP/A2A 投影时 |
+| A2A 入站 | `jiuwenswarm/gateway/channel_manager/protocol/a2a/` | `docs/zh/A2A.md` §3–§9 | 改 AgentCard、A2A parts 与 `Message` 的互转、reasoning 输出、`A2A_SERVER_*` 变量、可选依赖 `jiuwenswarm[a2a]` 时 |
+| ACP 接入 | `scripts/run_gateway_acp.sh`、`scripts/run_gateway_acp.cmd`、`jiuwenswarm-acp` 命令 | `docs/zh/ACP插件使用.md` | 改 ACP 启动脚本、命令入口或 VS Code 接入步骤时 |
+| A2UI（只支持 Web） | 后端 `jiuwenswarm/server/runtime/a2ui/`；前端 `jiuwenswarm/channels/web/frontend/src/features/a2ui/` | `docs/zh/A2UI.md`（模块关系表、边界原则）、`docs/zh/A2UI-IM-channel-analysis.md`、`docs/zh/A2UI-web-only-pr-record.md` | 任何 A2UI 改动，尤其是想让非 Web 频道也支持 A2UI 的 PR |
+| AgentServer 运行时 | `jiuwenswarm/server/`（如 `runtime/agent_adapter`） | `docs/zh/A2UI.md` 模块表中 agent_adapter 那一行、`docs/zh/模式系统.md` | 改输入输出适配、`mode` / `work_mode` 的处理时 |
+| Agent harness、Team、Skills、记忆 | `jiuwenswarm/agents/`（如 `agents/harness/common/rails`） | `docs/zh/AgentTeam.md`（§2.4 技能可见性、§2.5 团队记忆、§2.6 SwarmFlow 启停、Q6 本地与分布式模式下的会话规则）、`docs/zh/AgentTeam人类成员联机协作.md`、`docs/zh/SwarmSkills.md`、`docs/zh/记忆.md` | 改 Leader/Teammate 协作、`skills-visibility.json`、团队记忆、SwarmFlow 生命周期，或人类成员的 `/join`、`$成员名` 语法时 |
+| Auto Harness | 已提供的文档没有给出代码目录，按 PR 的实际路径定位 | `docs/zh/AutoHarness.md` | 改 `/auto-harness` 命令、Meta/Expert pipeline、Harness Package 热加载、GitCode issue 自动处理时 |
+| Web 前端 | `jiuwenswarm/channels/web/frontend/` | `docs/zh/A2UI.md`（其中对 `useWebSocket.ts` 的约束）、`docs/zh/Quickstart.md` | 改前端组件、WebSocket hook、构建脚本时 |
+| 默认配置与资源 | `jiuwenswarm/resources/`（`config.yaml`、`.env.template`） | `docs/zh/配置信息.md`、`docs/zh/A2UI.md` 的配置一节、`docs/zh/FAQ.md` 的模型配置部分 | 改默认配置、环境变量名、`jiuwenswarm-init` 初始化流程时 |
+| 测试与 CI | `tests/`、`pytest.ini`、`run_tests.sh`、`.gitcode/workflows/` | `TESTING.md`、`tests/README.md` | 新增或修改测试、CI 失败时 |
+| 打包与部署 | `pyproject.toml`、`uv.lock`、`MANIFEST.in`、`Makefile`、`Dockerfile.claw`、`docker/`、`deploy/` | `docs/zh/安装指南.md`、`docs/zh/FAQ.md` | 改依赖、可选依赖（如 `a2a`）、镜像或发布流程时 |
+
+**文档里已知的过期内容**
+
+- `TESTING.md` 写于 JiuwenClaw 时期，和现状有出入：它同时写了 `tests/unit/` 和 `tests/unit_tests/` 两种路径；CI 部分写的是 `.github/workflows/`，而仓库实际用的是 `.gitcode/`。遇到分歧时，以 `pytest.ini`、`.gitcode/workflows/` 和 `tests/` 的实际结构为准。
+- 由于改过名，仓库里可能还留着 `claw` 字样，例如 `Dockerfile.claw` 和旧的 `JIUWENCLAW_*` 环境变量。`docs/zh/A2UI.md` 已声明 A2UI 不再支持旧前缀，只认 `JIUWENSWARM_A2UI_*`。
+- `docs/zh/A2A.md` §7 说明：出站 A2A（Agent 通过 MCP Hub 调外部）目前不在仓库里。遇到相关 PR 时，以实际接线的代码为准。
+- `docs/zh/FAQ.md` 要求和 `docs/en/FAQ.md` 同步更新。改动只涉及其中一种语言的文档时，要检查另一种语言的版本有没有一起更新。
+
+## 代码快速入口（Direct）
+<!-- kb-init:quick-map -->
+
+触发词：gateway、网关、channel、频道、channel_manager、message_handler、feishu、飞书、wechat、微信、xiaoyi、小艺。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。
+
+| PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
+|---|---|---|
+| gateway、网关、channel、频道、channel_manager、message_handler、feishu、飞书、wechat、微信、xiaoy… | 入口 | `docs/README.md`、`docs/README_EN.md`、`jiuwenswarm/gateway/app_gateway.py` |

knowledge/repos/jiuwenswarm/rules.md

@@ -0,0 +1,84 @@
+---
+title: "JiuwenSwarm 仓库审查规则"
+created: 2026-09-30
+updated: 2026-09-30
+type: rule
+tags: [jiuwenswarm]
+sources: []
+---
+
+# JiuwenSwarm 仓库审查规则
+
+## 代码快速入口（Direct）
+<!-- kb-init:quick-map -->
+
+触发词：test、tests、测试、pytest、UT、单元测试、CI、coverage、覆盖率。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。
+
+| PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
+|---|---|---|
+| 代码必须能在 Python 3.11 上运行（支持范围 `>=3.11, <3.14`） | JIUWENSW-I2 | `tests/`、`pytest.ini`、`run_tests.sh` |
+| 改依赖必须在同一 PR 里同步 `uv.lock`，可选通道的依赖放进 extras | JIUWENSW-I3 | `tests/`、`pytest.ini`、`run_tests.sh` |
+| 改名为 JiuwenSwarm 后不要再引入 `JIUWENCLAW_*`，也不要乱改其他通道的变量名 | JIUWENSW-I6 | `tests/`、`pytest.ini`、`run_tests.sh` |
+| 分清几种 `metadata`，不要写错层 | JIUWENSW-I8 | `tests/`、`pytest.ini`、`run_tests.sh` |
+| 技能实体只有一份：放在全局技能库，可见性只靠 JSON 声明 | JIUWENSW-I10 | `skills/` |
+| Team 会话切换和 SwarmFlow 启停要区分本地/分布式模式和触发来源 | JIUWENSW-I11 | `tests/`、`pytest.ini`、`run_tests.sh` |
+| 改协议或接口的实现时同步更新文档，中英文一起改 | JIUWENSW-I12 | `docs/zh/A2A.md`、`docs/zh/E2A-protocol.md`、`jiuwenswarm/common/e2a/models.py` |
+
+## JIUWENSW-I2 — 代码必须能在 Python 3.11 上运行（支持范围 `>=3.11, <3.14`）
+
+- 最低版本 3.11 分散写在 README 徽章、ACP 文档和 FAQ 里；CI 矩阵只覆盖 3.11/3.12/3.13。
+- 拒绝只有 3.12 及以上才有的语法或 API，例如 PEP 695 的 `type X = ...` 和 `def f[T]()` 泛型语法、PEP 701 的 f-string 内复用同种引号、`itertools.batched`。
+- 如果调整了 `pyproject.toml` 里的 Python 版本约束，CI 矩阵和 FAQ（中英文）要一起更新。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->
+
+## JIUWENSW-I3 — 改依赖必须在同一 PR 里同步 `uv.lock`，可选通道的依赖放进 extras
+
+- 仓库用 `uv` 管理依赖（`uv sync`、`uv run pytest`、`uv sync --extra a2a`）。`TESTING.md` 里的 `pip install -e ".[test]"` 只是另一种安装入口，不能成为漏更新锁文件的理由。
+- 在 `pyproject.toml` 里增、删、改任何依赖，都要在同一 PR 里重新生成 `uv.lock`。
+- `a2ui-agent-sdk` 保持 `==0.2.1` 这种精确锁定。升级时必须在同一 PR 里更新锁文件、跑协议校验测试，并完成 Web 前端的 `npm run build`。
+- 只有某个可选通道才用到的依赖（例如 A2A 的 `a2a-sdk`）应放进对应的 extra（`jiuwenswarm[a2a]`），不要加进主依赖。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->
+
+## JIUWENSW-I6 — 改名为 JiuwenSwarm 后不要再引入 `JIUWENCLAW_*`，也不要乱改其他通道的变量名
+
+- v0.2.0 起 JiuwenClaw 升级为 JiuwenSwarm。A2UI 的运行时覆盖项只认 `JIUWENSWARM_A2UI_*`，`JIUWENCLAW_A2UI_*` 从 2026-06-04 起不再兼容。
+- 新代码不能把 `JIUWENCLAW_` 前缀当后备来读，也不要新增这个前缀的变量。用户数据目录统一是 `~/.jiuwenswarm/`，例如 `~/.jiuwenswarm/config/.env`。
+- 各通道已有自己的变量前缀（`A2A_SERVER_*`、`ACP_GATEWAY_*`、`WEB_HOST`/`WEB_PORT`/`WEB_PATH`），不要为了“统一”去改名，那样会破坏现有部署。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->
+
+## JIUWENSW-I8 — 分清几种 `metadata`，不要写错层
+
+- 请求信封顶层的 `metadata`：旧 `AgentRequest` 留下的字段，只在 `from_dict` 时迁入 `channel_context`，新代码不能写。
+- `envelope_from_a2a_send_message` 的 `metadata` 参数：写入 `a2a_metadata`，只用于和 A2A 互通；`acp_meta` 同理只用于 ACP。
+- `E2AResponse.metadata`：这是合法字段，存放通道或业务的自定义键值（对应旧的 `AgentResponse.metadata`），协议转换失败时也可临时写入兜底内容。旧格式整包 JSON 使用 `E2A_WIRE_LEGACY_AGENT_RESPONSE_KEY` / `E2A_WIRE_LEGACY_AGENT_CHUNK_KEY`，业务自定义键建议加通道前缀，避免冲突。
+- A2A 通道里的元数据写到内部 `Message.metadata`，这不是 E2A 字段。
+- 评审时核对三点：字段写在了哪一层的 `metadata`；有没有把业务键写进 `a2a_metadata`/`acp_meta`；有没有在请求侧重新写顶层 `metadata`。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->
+
+## JIUWENSW-I10 — 技能实体只有一份：放在全局技能库，可见性只靠 JSON 声明
+
+- 技能安装只写入全局库 `~/.jiuwenswarm/agent/workspace/skills/`。`.agent_teams/<team_name>/team-workspace/` 和 `workspaces/<agent_name>_workspace/` 下都不能出现 `skills/` 目录、软链或副本。
+- 可见性只能通过团队和成员各自的 `skills-visibility.json`，以及 `skills.visibility.get`/`set`/`update` 修改。合并规则：deny 优先于 allow；团队的 deny 成员无法撤销；`allow` 为空表示继承整个技能库。
+- 配置里各角色的 `skills` 只在第一次生成声明文件时作为初始 `allow`。`skills-visibility.json` 已存在时，不能被配置覆盖。
+- FAQ 的升级备份表把自定义技能路径写成 `~/.jiuwenswarm/agent/skills`，和 AgentTeam 文档的 `~/.jiuwenswarm/agent/workspace/skills/` 不一致。涉及技能路径的改动以代码实际路径为准，并顺手修正写错的那份文档。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->
+
+## JIUWENSW-I11 — Team 会话切换和 SwarmFlow 启停要区分本地/分布式模式和触发来源
+
+  - TUI `/exit` 或双击 Ctrl+C：兜底暂停，保留进度。
+- 暂停后不能自动恢复，是否恢复由 Leader 决定。重启后没跑完的 run 显示为“暂停待恢复”，按钮置灰。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->
+
+## JIUWENSW-I12 — 改协议或接口的实现时同步更新文档，中英文一起改
+
+- `docs/zh/A2A.md` 和 `docs/zh/E2A-protocol.md` 都声明：文档与代码冲突时以源码为准，并要回头修正文档。所以修改 `jiuwenswarm/common/e2a/models.py`（`E2AEnvelope`/`E2AResponse` 的字段）、`constants.py` 里的元组、A2A 环境变量默认值或字段映射时，PR 要同步更新对应文档。
+- 中英文文档成对维护：`docs/zh/<页面>.md` 对应 `docs/en/<页面>.md`（FAQ 和 E2A 明确要求同步，A2UI 的改动也是中英文一起改），`README_CN.md` 对应 `README.md`。只改了一边的，要求补齐另一边。
+- `docs/zh/` 下的新页面沿用末尾的“返回导航”段落，链接 `../README.md` 和 `../../README_CN.md`，并在 `docs/README.md` 的导航里登记。
+
+<!-- kb:rule status=active since=init-f0a69728c96b -->